javax.sound.midi
接口 Synthesizer

所有超级接口：

MidiDevice

public interface Synthesizer
extends MidiDevice

Synthesizer 生成声音。这通常发生在某个 Synthesizer 的 MidiChannel 对象直接或通过 Synthesizer 对象接收到 noteOn 消息时。很多 Synthesizer 都支持 Receiver，通过后者可将 MIDI 事件发送至 Synthesizer。这种情况下，Synthesizer 通常的响应是发送一个相应的消息至合适的 MidiChannel，如果事件不是 MIDI 通道消息之一，则自己处理该事件。

Synthesizer 接口包括可从音库加载和卸载乐器 (instrument) 的方法。一个乐器就是用于合成某种声音类型的规范，无论这种声音模仿的是传统乐器还是某种音效或其他想象出来的声音。音库是通过库和程序号组织的一组乐器（通过乐器的 Patch 对象）。不同的 Synthesizer 类可实现不同的声音合成技巧，这意味着某些乐器可以与给定的合成器兼容，而另一些则不行。同样，合成器可以为乐器保留有限的内存量，这意味着不是每种合成器都可使用每种音库和乐器，即使合成技术兼容时也是如此。要查看取自某种音库的乐器是否可由给定的合成器演奏，可调用 Synthesizer 的 isSoundbankSupported 方法。

“加载”乐器意味着该乐器可用于合成音符。乐器加载至由其 Patch 对象指定的库和程序位置。加载并不一定意味着后续演奏的音符将立即具有此新加载乐器的声音。要使乐器演奏音符，某个合成器的 MidiChannel 对象必须接收（或已经接收）可使该特定乐器的库和程序号被选中的程序更改消息。

另请参见：

MidiSystem.getSynthesizer(), Soundbank, Instrument, MidiChannel.programChange(int, int), Receiver, Transmitter, MidiDevice

嵌套类摘要

从接口 javax.sound.midi.MidiDevice 继承的嵌套类/接口

MidiDevice.Info

方法摘要

Instrument[]	getAvailableInstruments() 获得该合成器随附的乐器列表。
MidiChannel[]	getChannels() 获得此合成器控制的一组 MIDI 通道。
Soundbank	getDefaultSoundbank() 获得合成器的默认音库（如果合成器存在）。
long	getLatency() 获得此合成器导致的处理延迟，用微秒表示。
Instrument[]	getLoadedInstruments() 获得当前加载到此 Synthesizer 中的乐器列表。
int	getMaxPolyphony() 获得此合成器可同时发声的最大音符数。
VoiceStatus[]	getVoiceStatus() 获得由此合成器生成的声音的当前状态。
boolean	isSoundbankSupported(Soundbank soundbank) 通知调用者此合成器是否能够从指定的音库加载乐器。
boolean	loadAllInstruments(Soundbank soundbank) 将指定 Soundbank 中包含的所有乐器加载到 Synthesizer 中。
boolean	loadInstrument(Instrument instrument) 让特定的乐器可用于合成。
boolean	loadInstruments(Soundbank soundbank, Patch[] patchList) 从指定 Soundbank 加载指定修补程序所引用的乐器。
boolean	remapInstrument(Instrument from, Instrument to) 重新映射一个乐器。
void	unloadAllInstruments(Soundbank soundbank) 卸载指定 Soundbank 中包含的所有乐器。
void	unloadInstrument(Instrument instrument) 卸载特定的乐器。
void	unloadInstruments(Soundbank soundbank, Patch[] patchList) 从指定的 MIDI 音库中卸载指定修补程序所引用的乐器。

从接口 javax.sound.midi.MidiDevice 继承的方法

close, getDeviceInfo, getMaxReceivers, getMaxTransmitters, getMicrosecondPosition, getReceiver, getReceivers, getTransmitter, getTransmitters, isOpen, open

方法详细信息

getMaxPolyphony

int getMaxPolyphony()

获得此合成器可同时发声的最大音符数。

返回：

同时发声的最大音符数

另请参见：

getVoiceStatus()

getLatency

long getLatency()

获得此合成器导致的处理延迟，用微秒表示。此延迟可衡量从 MIDI 消息发送至合成器的时刻到该合成器实际生成相应结果的时刻之间最坏的延迟情况。

尽管延迟用微秒表示，但合成器实际延迟测量值的变化范围可能远大于此精度所建议的时间（微秒）。例如，合成器最坏的情况下可能延迟几个毫秒或更多。

返回：

最坏的延迟情况，以微秒为单位

getChannels

MidiChannel[] getChannels()

获得此合成器控制的一组 MIDI 通道。返回数组中的每个非 null 元素都是一个 MidiChannel，可接收该通道号上发送的 MIDI 消息。

MIDI 1.0 规范提供 16 个通道，所以此方法返回一个至少有 16 个元素的数组。但是，如果此合成器不使用所有的 16 个通道，则数组中的某些元素可能为 null，所以应在使用前检查每个元素。

返回：

一个由此 Synthesizer 管理的 MidiChannel 对象数组。有些数组元素可能为 null。

getVoiceStatus

VoiceStatus[] getVoiceStatus()

获得由此合成器生成的声音的当前状态。如果此 Synthesizer 类未提供声音信息，则返回的数组长度将始终为 0。否则其长度始终等于声音总数，与 getMaxPolyphony() 的返回结果一样。（有关合成器声音的说明，请参阅 VoiceStatus 类描述。）

返回：

一个 VoiceStatus 对象数组，该对象提供关于相应合成器声音的信息

另请参见：

getMaxPolyphony(), VoiceStatus

isSoundbankSupported

boolean isSoundbankSupported(Soundbank soundbank)

通知调用者此合成器是否能够从指定的音库加载乐器。如果不支持该音库，则任何试图从中加载乐器的尝试将抛出 IllegalArgumentException。

参数：

soundbank - 查询其是否受支持的音库

返回：

如果支持该音库，则返回 true，否则返回 false

另请参见：

loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]), loadAllInstruments(javax.sound.midi.Soundbank), unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]), unloadAllInstruments(javax.sound.midi.Soundbank), getDefaultSoundbank()

loadInstrument

boolean loadInstrument(Instrument instrument)

让特定的乐器可用于合成。此乐器加载至由其 Patch 对象指定的修补程序位置，所以如果接收到（或已经收到）导致该修补程序被选中的程序更改消息，则使用 instrument 的声音演奏随后的音符。如果已加载指定的乐器，则此方法不执行任何操作并返回 true。

该乐器必须是此 Synthesizer 支持的音库的一部分。（可以使用 Instrument 的 getSoundbank 方法和 Synthesizer 的 isSoundbankSupported 方法验证。）

参数：

instrument - 要加载的乐器

返回：

如果乐器成功加载（或已经加载），则返回 true，如果乐器无法加载（例如，合成器内存不足无法加载），则返回 false

抛出：

IllegalArgumentException - 如果此 Synthesizer 不支持指定乐器的音库

另请参见：

unloadInstrument(javax.sound.midi.Instrument), loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]), loadAllInstruments(javax.sound.midi.Soundbank), remapInstrument(javax.sound.midi.Instrument, javax.sound.midi.Instrument), SoundbankResource.getSoundbank(), MidiChannel.programChange(int, int)

unloadInstrument

void unloadInstrument(Instrument instrument)

卸载特定的乐器。

参数：

instrument - 要卸载的乐器

抛出：

IllegalArgumentException - 如果此 Synthesizer 不支持指定乐器的音库

另请参见：

loadInstrument(javax.sound.midi.Instrument), unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]), unloadAllInstruments(javax.sound.midi.Soundbank), getLoadedInstruments(), remapInstrument(javax.sound.midi.Instrument, javax.sound.midi.Instrument)

remapInstrument

boolean remapInstrument(Instrument from,
                        Instrument to)

重新映射一个乐器。 乐器 to 将替换乐器 from。
例如，如果 from 位于库号 2，即程序号 11 的位置，则重新映射导致该库和程序位置被 to 所占用。
如果该函数获得成功，则乐器 from 被卸载。

通过调用 loadInstrument(javax.sound.midi.Instrument)、loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]) 或 loadAllInstruments(javax.sound.midi.Soundbank) 之一，可以取消对重载乐器 from 的重新映射。

参数：

from - 要替换的 Instrument 对象

to - 用来替换旧乐器的 Instrument 对象，应该将它加载到合成器中

返回：

如果成功地重新映射乐器，则返回 true，如果合成器没有实现此功能，则返回 false

抛出：

IllegalArgumentException - 如果乐器 from 或乐器 to 不受合成器的支持，或者没有加载乐器 to

NullPointerException - 如果 from 或 to 参数使用 null 值

另请参见：

loadInstrument(javax.sound.midi.Instrument), loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]), loadAllInstruments(javax.sound.midi.Soundbank)

getDefaultSoundbank

Soundbank getDefaultSoundbank()

获得合成器的默认音库（如果合成器存在）。（有些合成器提供默认或内置的音库。）如果合成器没有默认音库，则必须从外部音库显式加载乐器。

返回：

默认音库，如果不存在，则返回 null。

另请参见：

isSoundbankSupported(javax.sound.midi.Soundbank)

getAvailableInstruments

Instrument[] getAvailableInstruments()

获得该合成器随附的乐器列表。这些乐器可能内置在合成器中，也可能是合成器提供的默认音库的一部分等等。

注意，不能使用此方法查找当前加载到合成器中的乐器；如果要查找，可使用 getLoadedInstruments()。此方法也不指示可加载到合成器中的所有乐器；它仅指示合成器随附的乐器子集。要了解是否可加载另一个乐器，可以调用 isSoundbankSupported()，如果支持该乐器的 Soundbank，则可尝试加载该乐器。

返回：

可用乐器列表。

另请参见：

getLoadedInstruments(), isSoundbankSupported(Soundbank), loadInstrument(javax.sound.midi.Instrument)

getLoadedInstruments

Instrument[] getLoadedInstruments()

获得当前加载到此 Synthesizer 中的乐器列表。

返回：

当前已加载乐器的列表

另请参见：

loadInstrument(javax.sound.midi.Instrument), getAvailableInstruments(), Soundbank.getInstruments()

loadAllInstruments

boolean loadAllInstruments(Soundbank soundbank)

将指定 Soundbank 中包含的所有乐器加载到 Synthesizer 中。

参数：

soundbank - 将被加载乐器的 Soundbank

返回：

如果所有乐器均成功加载（或已经加载），则返回 true；如果有乐器无法加载（例如，Synthesizer 没有足够的内存），则返回 false

抛出：

IllegalArgumentException - 如果所请求的音库与此合成器不兼容。

另请参见：

isSoundbankSupported(javax.sound.midi.Soundbank), loadInstrument(javax.sound.midi.Instrument), loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])

unloadAllInstruments

void unloadAllInstruments(Soundbank soundbank)

卸载指定 Soundbank 中包含的所有乐器。

参数：

soundbank - 包含要卸载的乐器的音库

抛出：

IllegalArgumentException - 如果不支持该音库。

另请参见：

isSoundbankSupported(javax.sound.midi.Soundbank), unloadInstrument(javax.sound.midi.Instrument), unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])

loadInstruments

boolean loadInstruments(Soundbank soundbank,
                        Patch[] patchList)

从指定 Soundbank 加载指定修补程序所引用的乐器。每个 Patch 对象都指示一个库和程序号；具有匹配的 Patch 的 Instrument 将被加载至该库和程序位置。

参数：

soundbank - 包含要加载的乐器的 Soundbank

patchList - 应为其加载乐器的修补程序列表

返回：

如果所有乐器均成功加载（或已经加载），则返回 true，如果有乐器无法加载（例如，Synthesizer 没有足够的内存），则返回 false

抛出：

IllegalArgumentException - 如果不支持该音库。

另请参见：

isSoundbankSupported(javax.sound.midi.Soundbank), Instrument.getPatch(), loadAllInstruments(javax.sound.midi.Soundbank), loadInstrument(javax.sound.midi.Instrument), Soundbank.getInstrument(Patch), Sequence.getPatchList()

unloadInstruments

void unloadInstruments(Soundbank soundbank,
                       Patch[] patchList)

从指定的 MIDI 音库中卸载指定修补程序所引用的乐器。

参数：

soundbank - 包含要卸载的乐器的音库

patchList - 应为其卸载乐器的修补程序列表

抛出：

IllegalArgumentException - 如果不支持该音库。

另请参见：

unloadInstrument(javax.sound.midi.Instrument), unloadAllInstruments(javax.sound.midi.Soundbank), isSoundbankSupported(javax.sound.midi.Soundbank), Instrument.getPatch(), loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])