javax.sound.midi
接口 Synthesizer

所有超级接口：

MidiDevice

public interface Synthesizer
extends MidiDevice

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

Synthesizer 接口包括用于从音库加载和卸载乐器的方法。一个乐器就是用于合成某种类型声音的规范，无论声音模仿的是传统的乐器还是某种音效或其他想象中的声音。音库是通过库和程序号组织的一组乐器（通过乐器的 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 元素都是一个接收该通道号上发送的 MIDI 消息的 MidiChannel。

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 被卸载。

参数：

from - 要替换的乐器

to - 在旧乐器位置使用的新乐器

返回：

如果乐器可以重新映射，则返回 true；否则返回 false

抛出：

IllegalArgumentException - 如果不支持该音库

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[])