javax.sound.midi
類別 MidiSystem

java.lang.Object
  javax.sound.midi.MidiSystem

public class MidiSystem
extends Object

MidiSystem 類別提供了對已安裝的 MIDI 系統資源的存取，包括諸如 synthesizer、sequencer 和 MIDI 輸入和輸出埠號等設備。典型的簡單 MIDI 應用程序可通過調用一個或多個 MidiSystem 方法開始，這樣可瞭解已安裝的設備並獲得該應用程序中所需要的設備。

該類別還有用於讀取那些包含了標準 MIDI 檔案資料或音資源庫的檔案、串流和 URL 的方法。可以查詢 MidiSystem 瞭解指定 MIDI 檔案的格式。

無法實例化 MidiSystem；所有的方法都是靜態的。

屬性可用於指定預設的 MIDI 設備。系統屬性和屬性檔案都可用於指定預設 MIDI 設備。屬性檔案是位於 JRE 目錄中的 "lib/sound.properties"。如果一個屬性既是系統屬性，又包含在屬性檔案中，則系統屬性優先。如果兩者都未指定，則會在可用的設備中選擇一個合適的預設值。屬性檔案的語法在 Properties.load 中指定。下表列出了可用的屬性鍵和獲取該屬性的方法：

屬性鍵	介面	起作用的方法
javax.sound.midi.Receiver	Receiver	getReceiver()
javax.sound.midi.Sequencer	Sequencer	getSequencer()
javax.sound.midi.Synthesizer	Synthesizer	getSynthesizer()
javax.sound.midi.Transmitter	Transmitter	getTransmitter()

屬性值包含提供者類別名和設備名，二者通過雜湊標記 ("#") 分隔。提供者類別名是具體 MIDI device provider 類別的完全限定名稱。設備名與由 MidiDevice.Info 的 getName 方法返回的 String 比對。 類別名或設備名都可以被忽略。如果只指定了類別名，則尾部的雜湊標記是可選的。

如果指定了提供者類別，並且可從所安裝的提供者中成功地檢索到此類別，則從該提供者檢索 MidiDevice.Info 物件列表。否則，當這些設備未提供後續比對時，則從 getMidiDeviceInfo() 檢索該列表以包含所有可用的 MidiDevice.Info 物件。

如果指定了設備名，則搜尋得到的 MidiDevice.Info 物件列表：將返回第一個具有比對的名稱，並且其 MidiDevice 實作了相應介面的結果。如果未找到任何比對的 MidiDevice.Info 物件，或者未指定設備名稱，則從結果列表返回第一個適合的設備。對於 Sequencer 和 Synthesizer，如果設備實作了相應的介面，則該設備為適合的設備；對於 Receiver 和 Transmitter，如果設備既未實作 Sequencer 也未實作 Synthesizer，並且至少分別提供了一個 Receiver 或 Transmitter，則該設備為適合的設備。 例如，對於具有 "com.sun.media.sound.MidiProvider#SunMIDI1" 值的屬性 javax.sound.midi.Receiver，在調用 getReceiver 時，它將具有下面的結果：如果類別 com.sun.media.sound.MidiProvider 出現在已安裝的 MIDI 設備提供者列表中，則將返回第一個名稱為 "SunMIDI1" 的 Receiver 設備。如果未找到此種設備，則將返回該提供者的第一個 Receiver，不考慮其名稱。如果沒有，則將返回所有設備列表中的第一個名稱為 "SunMIDI1" 的 Receiver（如同從 getMidiDeviceInfo 返回的結果），如果未找到，則返回在所有設備列表中能找到的第一個 Receiver。如果仍未找到，則拋出 MidiUnavailableException。

方法摘要

static MidiDevice	getMidiDevice(MidiDevice.Info info) 獲得請求的 MIDI 設備。
static MidiDevice.Info[]	getMidiDeviceInfo() 獲得資訊物件陣列，表示系統中可用的所有 MIDI 設備集。
static MidiFileFormat	getMidiFileFormat(File file) 獲得指定 File 的 MIDI 檔案格式。
static MidiFileFormat	getMidiFileFormat(InputStream stream) 獲得指定的輸入串流中資料的 MIDI 檔案格式。
static MidiFileFormat	getMidiFileFormat(URL url) 獲得指定 URL 中資料的 MIDI 檔案格式。
static int[]	getMidiFileTypes() 獲得系統為其提供檔案寫入支持的 MIDI 檔案型別的集合。
static int[]	getMidiFileTypes(Sequence sequence) 獲得系統可從指定 sequence 寫入的 MIDI 檔案型別集合。
static Receiver	getReceiver() 從外部 MIDI 埠號或其他預設設備獲得 MIDI 接收器。
static Sequence	getSequence(File file) 從指定的 File 獲得 MIDI 序列。
static Sequence	getSequence(InputStream stream) 從指定的輸入串流獲得 MIDI 序列。
static Sequence	getSequence(URL url) 從指定的 URL 獲得 MIDI 序列。
static Sequencer	getSequencer() 獲得連接到預設設備上的預設的 Sequencer。
static Sequencer	getSequencer(boolean connected) 獲得預設的 Sequencer，它可選地連接到預設設備上。
static Soundbank	getSoundbank(File file) 通過從指定的 File 讀取來建構一個 Soundbank。
static Soundbank	getSoundbank(InputStream stream) 通過從指定的串流讀取來建構一個 MIDI 音資源庫。
static Soundbank	getSoundbank(URL url) 通過從指定的 URL 處讀取來建構一個 Soundbank。
static Synthesizer	getSynthesizer() 獲得預設的合成器。
static Transmitter	getTransmitter() 從外部 MIDI 埠號或其他預設源獲得 MIDI 傳輸器。
static boolean	isFileTypeSupported(int fileType) 指示系統是否提供了指定 MIDI 檔案型別的檔案寫入支持。
static boolean	isFileTypeSupported(int fileType, Sequence sequence) 指示是否可從指示的序列寫入指定檔案型別的 MIDI 檔案。
static int	write(Sequence in, int type, File out) 將表示所指示 MIDI 檔案型別的檔案的位元組串流寫入提供的外部檔案。
static int	write(Sequence in, int fileType, OutputStream out) 將表示所指示 MIDI 檔案型別的檔案的位元組串流寫入提供的輸出串流。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

方法詳細資訊

getMidiDeviceInfo

public static MidiDevice.Info[] getMidiDeviceInfo()

獲得資訊物件陣列，表示系統中可用的所有 MIDI 設備集。然後，通過調用 getMidiDevice，可使用返回的資訊物件獲得相應的設備物件。

返回：

一個 MidiDevice.Info 物件的陣列，每個已安裝的 MIDI 設備對應一個物件。如果未安裝這樣的設備，則返回長度為 0 的陣列。

getMidiDevice

public static MidiDevice getMidiDevice(MidiDevice.Info info)
                                throws MidiUnavailableException

獲得請求的 MIDI 設備。

參數：

info - 表示所需設備的設備資訊物件。

返回：

所請求的設備

拋出：

MidiUnavailableException - 如果由於資源限制使所請求的設備不可用

IllegalArgumentException - 如果 info 物件並不表示系統上已安裝的 MIDI 設備

另請參見：

getMidiDeviceInfo()

getReceiver

public static Receiver getReceiver()
                            throws MidiUnavailableException

從外部 MIDI 埠號或其他預設設備獲得 MIDI 接收器。

如果定義了系統屬性 javax.sound.midi.Receiver，或者在檔案 "sound.properties" 中定義了該屬性，則它可用於標識提供了預設接收器的設備。有關詳細資訊，請參閱類別描述。 如果沒有適合的 MIDI 埠號可用，則從已安裝的合成器中檢索 Receiver。

如果此方法成功返回，則隱式打開 Receiver 所屬於的 MidiDevice（如果它尚未打開）。通過在返回的 Receiver 上調用 close 可以關閉一個隱式打開的設備。所有打開的 Receiver 實例都必須關閉，以釋放由 MidiDevice 所佔用的系統資源。有關打開/關閉行為的詳細描述，請參見 MidiDevice 的類別描述。

返回：

預設的 MIDI 接收器

拋出：

MidiUnavailableException - 如果由於資源限制使預設的接收器不可用，或者系統上未安裝任何提供接收器的設備

getTransmitter

public static Transmitter getTransmitter()
                                  throws MidiUnavailableException

從外部 MIDI 埠號或其他預設源獲得 MIDI 傳輸器。

如果定義了系統屬性 javax.sound.midi.Transmitter，或者在檔案 "sound.properties" 中定義了該屬性，則它可用於標識提供了預設傳輸器的設備。有關詳細資訊，請參閱類別描述。 如果此方法成功返回，則隱式打開 Transmitter 所屬於的 MidiDevice（如果它尚未打開）。通過在返回的 Transmitter 上調用 close 可以關閉一個隱式打開的設備。所有打開的 Transmitter 實例都必須關閉，以釋放由 MidiDevice 所佔用的系統資源。有關打開/關閉行為的詳細描述，請參見 MidiDevice 的類別描述。

返回：

預設的 MIDI 傳輸器

拋出：

MidiUnavailableException - 如果由於資源限制使預設的傳輸器不可用，或者系統上未安裝任何提供傳輸器的設備

getSynthesizer

public static Synthesizer getSynthesizer()
                                  throws MidiUnavailableException

獲得預設的合成器。

如果定義了系統屬性 javax.sound.midi.Synthesizer，或者在檔案 "sound.properties" 中定義了該屬性，則它可用於標識預設的合成器。有關詳細資訊，請參閱類別描述。

返回：

預設的合成器

拋出：

MidiUnavailableException - 如果由於資源限制使合成器不可用，或者系統上未安裝任何合成器

getSequencer

public static Sequencer getSequencer()
                              throws MidiUnavailableException

獲得連接到預設設備上的預設的 Sequencer。返回的 Sequencer 實例連接到預設的 Synthesizer，如同由 getSynthesizer() 返回的結果。如果沒有可用的 Synthesizer，或者預設的 Synthesizer 無法打開，則 sequencer 會連接到預設的 Receiver，如同由 getReceiver() 返回的結果。該連接是通過從 Sequencer 檢索 Transmitter 實例並設置其 Receiver 來建立的。關閉和重新打開 sequencer 將恢復到預設設備的連接。

此方法等效於調用 getSequencer(true)。

如果定義了系統屬性 javax.sound.midi.Sequencer，或者在檔案 "sound.properties" 中定義了該屬性，則它可用於標識預設的 sequencer。有關詳細資訊，請參閱類別描述。

返回：

連接到預設 Receiver 上的預設 sequencer

拋出：

MidiUnavailableException - 如果由於資源限制使 sequencer 不可用，或者任何已安裝的 MidiDevice 上都沒有可用的 Receiver，或者系統中未安裝 sequencer。

另請參見：

getSequencer(boolean), getSynthesizer(), getReceiver()

getSequencer

public static Sequencer getSequencer(boolean connected)
                              throws MidiUnavailableException

獲得預設的 Sequencer，它可選地連接到預設設備上。

如果 connected 為 true，則返回的 Sequencer 實例連接到預設的 Synthesizer，如同由 getSynthesizer() 返回的結果。如果沒有可用的 Synthesizer，或者預設的 Synthesizer 無法打開，則 sequencer 會連接到預設的 Receiver，如同由 getReceiver() 返回的結果。該連接是通過從 Sequencer 檢索 Transmitter 實例並設置其 Receiver 來建立的。關閉和重新打開 sequencer 將恢復到預設設備的連接。

如果 connected 為 false，則返回的 Sequencer 實例為未連接，它沒有打開的 Transmitter。為了在 MIDI 設備或 Synthesizer 上運行 sequencer，有必要獲得 Transmitter 並設置其 Receiver。

如果定義了系統屬性 javax.sound.midi.Sequencer，或者在檔案 "sound.properties" 中定義了該屬性，則它可用於標識預設的 sequencer。有關詳細資訊，請參閱類別描述。

返回：

預設的 sequencer

拋出：

MidiUnavailableException - 如果由於資源限制使 sequencer 不可用，或者系統中未安裝 sequencer，或者如果 connected 為 true 並且任何已安裝的 MidiDevice 都沒有可用的 Receiver

從以下版本開始：

1.5

另請參見：

getSynthesizer(), getReceiver()

getSoundbank

public static Soundbank getSoundbank(InputStream stream)
                              throws InvalidMidiDataException,
                                     IOException

通過從指定的串流讀取來建構一個 MIDI 音資源庫。該串流必須指向有效的 MIDI 音資源庫檔案。通常，MIDI 檔案提供者可能需要在確定它們是否支持串流之前從中讀取一些資料。這些解析器必須能夠標記串流，讀取足夠多的資料來確定它們是否支持串流，並且如果不支持，則將串流的閱讀指針重新設置到其初始位置。如果輸入串流不支持此操作，則此方法可能會失敗，並拋出 IOException。

參數：

stream - 音資源庫資料的源。

返回：

音資源庫

拋出：

InvalidMidiDataException - 如果該串流沒有指向系統識別的有效 MIDI 音資源庫資料

IOException - 如果載入音資源庫時發生 I/O 錯誤

另請參見：

InputStream.markSupported(), InputStream.mark(int)

getSoundbank

public static Soundbank getSoundbank(URL url)
                              throws InvalidMidiDataException,
                                     IOException

通過從指定的 URL 處讀取來建構一個 Soundbank。該 URL 必須指向有效的 MIDI 音資源庫檔案。

參數：

url - 音資源庫資料的源

返回：

音資源庫

拋出：

InvalidMidiDataException - 如果 URL 未指向系統識別的有效 MIDI 音資源庫資料

IOException - 如果載入音資源庫時發生 I/O 錯誤

getSoundbank

public static Soundbank getSoundbank(File file)
                              throws InvalidMidiDataException,
                                     IOException

通過從指定的 File 讀取來建構一個 Soundbank。該 File 必須指向有效的 MIDI 音資源庫檔案。

參數：

file - 音資源庫資料的源

返回：

音資源庫

拋出：

InvalidMidiDataException - 如果 File 未指向系統識別的有效 MIDI 音資源庫資料

IOException - 如果載入音資源庫時發生 I/O 錯誤

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(InputStream stream)
                                        throws InvalidMidiDataException,
                                               IOException

獲得指定的輸入串流中資料的 MIDI 檔案格式。該串流必須指向系統可識別的檔案型別的有效 MIDI 檔案資料。

此方法和/或它調用的程式碼可能需要從串流讀取一些資料，以確定是否支持串流的資料格式。因此實作可能需要標記串流、讀取足夠的資料來確定串流是否為支持的格式，並將串流的閱讀指針重新設置到其初始位置。如果輸入串流不允許此組操作，則此方法可能會失敗，並拋出 IOException。

只有針對那些能由已安裝的檔案 reader 所解析的型別的檔案，該操作才能成功。即使是有效的檔案，如果未安裝相容的檔案 reader，則也會失敗並拋出 InvalidMidiDataException。如果安裝了相容的檔案 reader，但在確定檔案格式時遇到錯誤，則也會失敗並拋出 InvalidMidiDataException。

參數：

stream - 應從中提取檔案格式資訊的輸入串流

返回：

描述 MIDI 檔案格式的 MidiFileFormat 物件

拋出：

InvalidMidiDataException - 如果串流沒有指向系統識別的有效 MIDI 檔案資料

IOException - 如果存取串流時發生 I/O 異常

另請參見：

getMidiFileFormat(URL), getMidiFileFormat(File), InputStream.markSupported(), InputStream.mark(int)

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(URL url)
                                        throws InvalidMidiDataException,
                                               IOException

獲得指定 URL 中資料的 MIDI 檔案格式。該 URL 必須指向系統可識別的檔案型別的有效 MIDI 檔案資料。

只有針對那些能由已安裝的檔案 reader 所解析的型別的檔案，該操作才能成功。即使是有效的檔案，如果未安裝相容的檔案 reader，則也會失敗並拋出 InvalidMidiDataException。如果安裝了相容的檔案 reader，但在確定檔案格式時遇到錯誤，則也會失敗並拋出 InvalidMidiDataException。

參數：

url - 應該從中提取檔案格式資訊的 URL

返回：

描述 MIDI 檔案格式的 MidiFileFormat 物件

拋出：

InvalidMidiDataException - 如果 URL 沒有指向系統識別的有效 MIDI 檔案資料

IOException - 如果存取 URL 時發生 I/O 異常

另請參見：

getMidiFileFormat(InputStream), getMidiFileFormat(File)

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(File file)
                                        throws InvalidMidiDataException,
                                               IOException

獲得指定 File 的 MIDI 檔案格式。該 File 必須指向系統可識別的檔案型別的有效 MIDI 檔案資料。

只有針對那些能由已安裝的檔案 reader 所解析的型別的檔案，該操作才能成功。即使是有效的檔案，如果未安裝相容的檔案 reader，則也會失敗並拋出 InvalidMidiDataException。如果安裝了相容的檔案 reader，但在確定檔案格式時遇到錯誤，則也會失敗並拋出 InvalidMidiDataException。

參數：

file - 應該從中提取檔案格式資訊的 File

返回：

描述 MIDI 檔案格式的 MidiFileFormat 物件

拋出：

InvalidMidiDataException - 如果 File 沒有指向系統可識別的有效 MIDI 檔案資料

IOException - 如果存取檔案時發生 I/O 異常

另請參見：

getMidiFileFormat(InputStream), getMidiFileFormat(URL)

getSequence

public static Sequence getSequence(InputStream stream)
                            throws InvalidMidiDataException,
                                   IOException

從指定的輸入串流獲得 MIDI 序列。該串流必須指向系統可識別的檔案型別的有效 MIDI 檔案資料。

此方法和/或它調用的程式碼可能需要從串流讀取一些資料，以確定是否支持串流的資料格式。因此實作可能需要標記串流、讀取足夠的資料來確定串流是否為支持的格式，並將串流的閱讀指針重新設置到其初始位置。如果輸入串流不允許此組操作，則此方法可能會失敗，並拋出 IOException。

只有針對那些能由已安裝的檔案 reader 所解析的型別的檔案，該操作才能成功。即使是有效的檔案，如果未安裝相容的檔案 reader，則也會失敗並拋出 InvalidMidiDataException。如果安裝了相容的檔案 reader，但在從檔案資料建構 Sequence 物件時遇到錯誤，則也會失敗並拋出 InvalidMidiDataException。

參數：

stream - 應該從中建構 Sequence 的輸入串流

返回：

基於輸入串流中包含的 MIDI 檔案資料的 Sequence 物件

拋出：

InvalidMidiDataException - 如果串流沒有指向系統識別的有效 MIDI 檔案資料

IOException - 如果存取串流時發生 I/O 異常

另請參見：

InputStream.markSupported(), InputStream.mark(int)

getSequence

public static Sequence getSequence(URL url)
                            throws InvalidMidiDataException,
                                   IOException

從指定的 URL 獲得 MIDI 序列。該 URL 必須指向系統可識別的檔案型別的有效 MIDI 檔案資料。

只有針對那些能由已安裝的檔案 reader 所解析的型別的檔案，該操作才能成功。即使是有效的檔案，如果未安裝相容的檔案 reader，則也會失敗並拋出 InvalidMidiDataException。如果安裝了相容的檔案 reader，但在從檔案資料建構 Sequence 物件時遇到錯誤，則也會失敗並拋出 InvalidMidiDataException。

參數：

url - 應該從中建構 Sequence 的 URL

返回：

基於由 URL 指向的 MIDI 檔案資料的 Sequence 物件

拋出：

InvalidMidiDataException - 如果 URL 沒有指向系統識別的有效 MIDI 檔案資料

IOException - 如果存取 URL 時發生 I/O 異常

getSequence

public static Sequence getSequence(File file)
                            throws InvalidMidiDataException,
                                   IOException

從指定的 File 獲得 MIDI 序列。該 File 必須指向系統可識別的檔案型別的有效 MIDI 檔案資料。

只有針對那些能由已安裝的檔案 reader 所解析的型別的檔案，該操作才能成功。即使是有效的檔案，如果未安裝相容的檔案 reader，則也會失敗並拋出 InvalidMidiDataException。如果安裝了相容的檔案 reader，但在從檔案資料建構 Sequence 物件時遇到錯誤，則也會失敗並拋出 InvalidMidiDataException。

參數：

file - 應該從中建構 Sequence 的 File

返回：

基於由 File 指向的 MIDI 檔案資料的 Sequence 物件

拋出：

InvalidMidiDataException - 如果 File 沒有指向系統識別的有效 MIDI 檔案資料

IOException - 如果發生 I/O 異常

getMidiFileTypes

public static int[] getMidiFileTypes()

獲得系統為其提供檔案寫入支持的 MIDI 檔案型別的集合。

返回：

唯一檔案型別的陣列。如果不支持任何檔案型別，則返回長度為 0 的陣列。

isFileTypeSupported

public static boolean isFileTypeSupported(int fileType)

指示系統是否提供了指定 MIDI 檔案型別的檔案寫入支持。

參數：

fileType - 查詢其寫入功能的檔案型別

返回：

如果支持檔案型別，則返回 true；否則返回 false

getMidiFileTypes

public static int[] getMidiFileTypes(Sequence sequence)

獲得系統可從指定 sequence 寫入的 MIDI 檔案型別集合。

參數：

sequence - 為其查詢 MIDI 檔案型別支持的序列

返回：

唯一的受支持檔案型別的集合。如果不支持任何檔案型別，則返回長度為 0 的陣列。

isFileTypeSupported

public static boolean isFileTypeSupported(int fileType,
                                          Sequence sequence)

指示是否可從指示的序列寫入指定檔案型別的 MIDI 檔案。

參數：

fileType - 查詢其寫入功能的檔案型別

sequence - 查詢其檔案寫入支持的序列

返回：

如果支持此序列的檔案型別，則返回 true；否則返回 false

write

public static int write(Sequence in,
                        int fileType,
                        OutputStream out)
                 throws IOException

將表示所指示 MIDI 檔案型別的檔案的位元組串流寫入提供的輸出串流。

參數：

in - 套件含要寫入檔案的 MIDI 資料的序列

fileType - 要寫入輸出串流的檔案的檔案型別

out - 應將檔案資料寫入的串流

返回：

寫入到輸出串流的位元組數

拋出：

IOException - 如果發生 I/O 異常

IllegalArgumentException - 如果系統不支持該檔案格式

另請參見：

isFileTypeSupported(int, Sequence), getMidiFileTypes(Sequence)

write

public static int write(Sequence in,
                        int type,
                        File out)
                 throws IOException

將表示所指示 MIDI 檔案型別的檔案的位元組串流寫入提供的外部檔案。

參數：

in - 套件含要寫入檔案的 MIDI 資料的序列

type - 要寫入輸出串流的檔案的檔案型別

out - 應將檔案資料寫入的外部檔案

返回：

寫入到檔案的位元組數

拋出：

IOException - 如果發生 I/O 異常

IllegalArgumentException - 如果系統不支持該檔案型別

另請參見：

isFileTypeSupported(int, Sequence), getMidiFileTypes(Sequence)