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