Module java.desktop

Package javax.sound.midi

Interface Synthesizer

所有超级接口:

AutoCloseable, MidiDevice

       public interface Synthesizer extends MidiDevice
      

Synthesizer生成声音。通常情况下，当Synthesizer的一个MidiChannel对象接收到一个noteOn消息时，声音就会产生，无论是直接还是通过Synthesizer对象。许多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

Nested Class Summary

Nested classes/interfaces declared in interface javax.sound.midi.MidiDevice

MidiDevice.Info

Method Summary

Modifier and Type	Method	Description
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声音库中卸载由指定补丁引用的所有乐器。

Methods declared in interface javax.sound.midi.MidiDevice

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

Method Details

getMaxPolyphony

             int getMaxPolyphony()
            

获取此合成器可以同时发出的最大音符数。

返回:

最大同时音符数

参见:

• getVoiceStatus()

getLatency

             long getLatency()
            

获取此合成器产生的处理延迟，以微秒表示。此延迟测量了传递给合成器的MIDI消息和合成器实际产生相应结果之间的最坏情况延迟。

尽管延迟以微秒表示，但合成器的实际测量延迟可能在比此分辨率更广的范围内变化。例如，合成器的最坏情况延迟可能为几毫秒或更长。

返回:

最坏情况延迟，以微秒表示

getChannels

             MidiChannel[] getChannels()
            

获取此合成器控制的MIDI通道集。返回数组中的每个非空元素都是接收该通道号上发送的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将被卸载。

要取消重新映射，请通过调用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，则可以尝试加载该乐器。

返回:

可用乐器列表。 如果合成器没有附带乐器，则返回长度为0的数组。

参见:

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