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 中指定。下表列出了可用的属性键和获取该属性的方法：

如果指定了提供者类，并且可从所安装的提供者中成功地检索到此类，则从该提供者检索 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。

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)

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。