模块  java.desktop
软件包  javax.sound.midi

Class MidiSystem

  • public class MidiSystem
extends Object
    MidiSystem类提供对已安装的MIDI系统资源的访问，包括合成器，音序器和MIDI输入和输出端口等设备。 典型的简单MIDI应用程序可能首先调用一个或多个MidiSystem方法来了解安装了哪些设备并获取该应用程序所需的设备。

    该类还具有读取包含标准MIDI文件数据或音库的文件，流和URL的方法。 您可以在MidiSystem中查询指定MIDI文件的格式。

    你无法实例化MidiSystem ; 所有方法都是静态的。

    属性可用于指定默认MIDI设备。 系统属性和属性文件都被考虑在内。 “sound.properties”属性文件是从特定于实现的位置读取的（通常是Java安装目录中的conf目录）。 可选的“javax.sound.config.file”系统属性可用于指定将作为初始配置读取的属性文件。 如果属性同时存在于系统属性和属性文件中，则系统属性优先。 如果未指定，则在可用设备中选择合适的默认值。 属性文件的语法在Properties.load中指定。 下表列出了可用的属性键以及考虑它们的方法：

    MIDI System Property Keys Property Key Interface Affected Method 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类的完全限定名称。 设备名称与String getName方法返回的getName MidiDevice.Info 。 可以省略类名或设备名。 如果仅指定了类名，则尾随哈希标记是可选的。

    如果指定了提供程序类，并且可以从已安装的提供程序中成功检索它， MidiDevice.Info从提供程序中检索MidiDevice.Info对象的列表。 否则，或当这些设备不提供后续匹配时，将从getMidiDeviceInfo()检索列表以包含所有可用的MidiDevice.Info对象。

    如果指定了设备名称，则会搜索MidiDevice.Info对象的结果列表：将返回第一个具有匹配名称且其MidiDevice实现相应接口的对象。 如果未找到匹配的MidiDevice.Info对象，或未指定设备名称，则将返回结果列表中的第一个合适设备。 对于Sequencer和Synthesizer，如果设备实现了相应的接口，则该设备是合适的。 而对于Receiver和Transmitter，如果设备既不实现Sequencer也不实现Synthesizer，并且分别提供至少一个Receiver或Transmitter，则设备是合适的。

    例如，财产javax.sound.midi.Receiver一个值"com.sun.media.sound.MidiProvider#SunMIDI1"将在下列后果getReceiver叫做：如果类com.sun.media.sound.MidiProvider在已安装的MIDI设备提供者列表存在，则第Receiver与名器"SunMIDI1"将被退回。 如果找不到，则无论名称如何，都将返回该提供商的第一个Receiver 。 如果没有，将返回所有设备列表中的第一个Receiver ，名称为"SunMIDI1" （由getMidiDeviceInfo返回），如果未找到，则返回可在所有设备列表中找到的第一个Receiver 。 如果失败，则抛出MidiUnavailableException 。

    • 方法详细信息

      • getMidiDeviceInfo

        public static MidiDevice.Info[] getMidiDeviceInfo()
        获得一组信息对象，表示系统上可用的所有MIDI设备的集合。 然后，通过调用getMidiDevice ，可以使用返回的信息对象来获取相应的设备对象。
        结果
        一组MidiDevice.Info对象，每个安装的MIDI设备一个。 如果未安装此类设备，则返回长度为0的数组。

      • getReceiver

        public static Receiver getReceiver()
                            throws MidiUnavailableException
        从外部MIDI端口或其他默认设备获取MIDI接收器。 返回的接收器始终实现MidiDeviceReceiver接口。

        如果定义了系统属性javax.sound.midi.Receiver或者在文件“sound.properties”中定义了该属性，则它用于标识提供默认接收器的设备。 有关详细信息，请参阅class description 。

        如果没有合适的MIDI端口，则从已安装的合成器中检索接收器。

        如果默认设备提供的本机接收器未实现MidiDeviceReceiver接口，则它将封装在实现MidiDeviceReceiver接口的包装器类中。 相应的Receiver方法调用将被转发到本机接收器。

        如果此方法成功返回，则Receiver所属的Receiver将被隐式打开（如果尚未打开）。 可以通过在返回的Receiver上调用close来关闭隐式打开的设备。 必须关闭所有打开的Receiver实例才能释放MidiDevice保留的系统资源。 有关打开/关闭行为的详细说明，请参阅MidiDevice的类说明。

        结果
        默认的MIDI接收器
        异常
        MidiUnavailableException - 如果由于资源限制而无法使用默认接收器，或者系统中未安装任何提供接收器的设备

      • getTransmitter

        public static Transmitter getTransmitter()
                                  throws MidiUnavailableException
        从外部MIDI端口或其他默认信号源获取MIDI发送器。 返回的变送器始终实现MidiDeviceTransmitter接口。

        如果定义了系统属性javax.sound.midi.Transmitter ，或者在文件“sound.properties”中定义了该属性，则它用于标识提供默认发送器的设备。 有关详细信息，请参阅class description 。

        如果默认设备提供的本机发送器未实现MidiDeviceTransmitter接口，则它将封装在实现MidiDeviceTransmitter接口的包装器类中。 相应的Transmitter方法调用将被转发到本机发送器。

        如果此方法成功返回，则Transmitter所属的Transmitter将被隐式打开，如果它尚未打开。 可以通过在返回的Transmitter上调用close来关闭隐式打开的设备。 必须关闭所有打开的Transmitter实例才能释放MidiDevice保留的系统资源。 有关打开/关闭行为的详细说明，请参阅MidiDevice的类说明。

        结果
        默认的MIDI发射器
        异常
        MidiUnavailableException - 如果由于资源限制而无法使用默认发送器，或者系统中未安装任何提供发送器的设备

      • getSynthesizer

        public static Synthesizer getSynthesizer()
                                  throws MidiUnavailableException
        获得默认合成器。

        如果定义了系统属性javax.sound.midi.Synthesizer或在文件“sound.properties”中定义了它，则它用于标识默认合成器。 有关详细信息，请参阅class description 。

        结果
        默认的合成器
        异常
        MidiUnavailableException - 如果由于资源限制导致合成器不可用，或者系统中未安装合成器

      • getSequencer

        public static Sequencer getSequencer()
                              throws MidiUnavailableException
        获得连接到默认设备的默认Sequencer 。 返回的Sequencer实例已连接到默认值Synthesizer ，由getSynthesizer()返回。 如果没有Synthesizer可用，或者无法打开默认Synthesizer ，则sequencer连接到默认Receiver ，由getReceiver()返回。 通过从Sequencer检索Transmitter实例并设置其Receiver建立Receiver 。 关闭并重新打开顺控程序将恢复与默认设备的连接。

        此方法相当于调用getSequencer(true) 。

        如果定义了系统属性javax.sound.midi.Sequencer或者在文件“sound.properties”中定义了该属性，则它用于标识默认顺控程序。 有关详细信息，请参阅class description 。

        结果
        默认音序器，连接到默认接收器
        异常
        MidiUnavailableException -如果序不可由于资源限制，或者没有 Receiver可通过任何安装 MidiDevice ，或无定序器安装在系统
        另请参见：
        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建立Receiver 。 关闭并重新打开顺控程序将恢复与默认设备的连接。

        如果connected为false，则返回的Sequencer实例未连接，它没有打开Transmitters 。 要在MIDI设备或Synthesizer上播放音序器，必须获得Transmitter并设置其Receiver 。

        如果定义了系统属性javax.sound.midi.Sequencer ，或者在文件“sound.properties”中定义了该属性，则它用于标识默认顺控程序。 有关详细信息，请参阅class description 。

        参数
        connected - 无论返回的 Sequencer是否已连接到默认值 Synthesizer
        结果
        默认音序器
        异常
        MidiUnavailableException - 如果由于资源限制而无法使用顺控程序，或者系统中未安装顺控程序，或者如果 connected为真，并且任何已安装的程序没有 Receiver MidiDevice
        从以下版本开始：
        1.5
        另请参见：
        getSynthesizer() ， getReceiver()

      • getSoundbank

        public static Soundbank getSoundbank​(InputStream stream)
                              throws InvalidMidiDataException,
                                     IOException
        通过从指定的流中读取它来构造MIDI声音库。 流必须指向有效的MIDI音库文件。 通常，MIDI声音库提供者可能需要在确定它们是否支持它之前从流中读取一些数据。 这些解析器必须能够标记流，读取足够的数据以确定它们是否支持流，如果不支持，则将流的读指针重置为其原始位置。 如果输入流不支持此方法，则此方法可能会失败，并显示IOException 。
        参数
        stream - 声音库数据的来源
        结果
        声音库
        异常
        InvalidMidiDataException - 如果流未指向系统识别的有效MIDI音库数据
        IOException - 如果加载 IOException库时发生I / O错误
        NullPointerException - 如果 stream是 null
        另请参见：
        InputStream.markSupported() ， InputStream.mark(int)

      • getMidiFileFormat

        public static MidiFileFormat getMidiFileFormat​(InputStream stream)
                                        throws InvalidMidiDataException,
                                               IOException
        获得指定输入流中数据的MIDI文件格式。 流必须指向系统识别的文件类型的有效MIDI文件数据。

        该方法和/或它调用的代码可能需要从流中读取一些数据以确定是否支持其数据格式。 因此，实现可能需要标记流，读取足够的数据以确定它是否是支持的格式，并将流的读指针重置为其原始位置。 如果输入流不允许这组操作，则此方法可能会失败，并显示IOException 。

        此操作只能对可以由已安装的文件读取器解析的类型的文件成功。 如果没有安装兼容的文件阅读器，即使对于有效文件，它也可能失败InvalidMidiDataException 。 如果安装了兼容的文件阅读器，它也将失败InvalidMidiDataException ，但在确定文件格式时遇到错误。

        参数
        stream - 应从中提取文件格式信息的输入流
        结果
        描述MIDI文件格式的 MidiFileFormat对象
        异常
        InvalidMidiDataException - 如果流未指向系统识别的有效MIDI文件数据
        IOException - 如果在访问流时发生I / O异常
        NullPointerException - 如果 stream是 null
        另请参见：
        getMidiFileFormat(URL) ， getMidiFileFormat(File) ， InputStream.markSupported() ， InputStream.mark(int)

      • getMidiFileFormat

        public static MidiFileFormat getMidiFileFormat​(URL url)
                                        throws InvalidMidiDataException,
                                               IOException
        获取指定URL中数据的MIDI文件格式。 URL必须指向系统识别的文件类型的有效MIDI文件数据。

        此操作只能对可以由已安装的文件读取器解析的类型的文件成功。 如果没有安装兼容的文件阅读器，即使对于有效文件，它也可能会失败InvalidMidiDataException 。 如果安装了兼容的文件阅读器，它也将失败InvalidMidiDataException ，但在确定文件格式时遇到错误。

        参数
        url - 应从中提取文件格式信息的URL
        结果
        描述MIDI文件格式的 MidiFileFormat对象
        异常
        InvalidMidiDataException - 如果URL未指向系统识别的有效MIDI文件数据
        IOException - 如果在访问URL时发生I / O异常
        NullPointerException - 如果 url是 null
        另请参见：
        getMidiFileFormat(InputStream) ， getMidiFileFormat(File)

      • getMidiFileFormat

        public static MidiFileFormat getMidiFileFormat​(File file)
                                        throws InvalidMidiDataException,
                                               IOException
        获得指定的File的MIDI文件格式。 File必须指向系统识别的文件类型的有效MIDI文件数据。

        此操作只能对可以由已安装的文件读取器解析的类型的文件成功。 如果没有安装兼容的文件阅读器，即使对于有效文件，它也可能会失败InvalidMidiDataException 。 如果安装了兼容的文件阅读器，它也将失败InvalidMidiDataException ，但在确定文件格式时遇到错误。

        参数
        file - 应从中提取文件格式信息的 File
        结果
        描述MIDI文件格式的 MidiFileFormat对象
        异常
        InvalidMidiDataException - 如果 File未指向系统识别的有效MIDI文件数据
        IOException - 如果在访问文件时发生I / O异常
        NullPointerException - 如果 file是 null
        另请参见：
        getMidiFileFormat(InputStream) ， getMidiFileFormat(URL)

      • getSequence

        public static Sequence getSequence​(InputStream stream)
                            throws InvalidMidiDataException,
                                   IOException
        从指定的输入流中获取MIDI序列。 流必须指向系统识别的文件类型的有效MIDI文件数据。

        该方法和/或它调用的代码可能需要从流中读取一些数据以确定是否支持其数据格式。 因此，实现可能需要标记流，读取足够的数据以确定它是否是支持的格式，并将流的读指针重置为其原始位置。 如果输入流不允许这组操作，则此方法可能会失败，并显示IOException 。

        此操作只能对可以由已安装的文件读取器解析的类型的文件成功。 如果没有安装兼容的文件阅读器，即使对于有效文件，它也可能会失败InvalidMidiDataException 。 如果安装了兼容的文件阅读器，它也将失败InvalidMidiDataException ，但在从文件数据构造Sequence对象时遇到错误。

        参数
        stream -从该输入流 Sequence应当被构造
        结果
        基于输入流中包含的MIDI文件数据的 Sequence对象
        异常
        InvalidMidiDataException - 如果流未指向系统识别的有效MIDI文件数据
        IOException - 如果在访问流时发生I / O异常
        NullPointerException - 如果 stream是 null
        另请参见：
        InputStream.markSupported() ， InputStream.mark(int)

      • getSequence

        public static Sequence getSequence​(URL url)
                            throws InvalidMidiDataException,
                                   IOException
        从指定的URL获取MIDI序列。 URL必须指向系统识别的文件类型的有效MIDI文件数据。

        此操作只能对可以由已安装的文件读取器解析的类型的文件成功。 如果没有安装兼容的文件阅读器，即使对于有效文件，它也可能会失败InvalidMidiDataException 。 如果安装了兼容的文件阅读器，它也将失败InvalidMidiDataException ，但在从文件数据构造Sequence对象时遇到错误。

        参数
        url -从该网址 Sequence应当建立
        结果
        基于URL指向的MIDI文件数据的 Sequence对象
        异常
        InvalidMidiDataException - 如果URL未指向系统识别的有效MIDI文件数据
        IOException - 如果在访问URL时发生I / O异常
        NullPointerException - 如果 url是 null

      • getSequence

        public static Sequence getSequence​(File file)
                            throws InvalidMidiDataException,
                                   IOException
        从指定的File获取MIDI序列。 File必须指向系统识别的文件类型的有效MIDI文件数据。

        此操作只能对可以由已安装的文件读取器解析的类型的文件成功。 如果没有安装兼容的文件阅读器，即使对于有效文件，它也可能失败InvalidMidiDataException 。 如果安装了兼容的文件阅读器，它也将失败InvalidMidiDataException ，但在从文件数据构造Sequence对象时遇到错误。

        参数
        file -所述 File从中 Sequence应当被构造
        结果
        一个 Sequence对象，基于File指向的MIDI文件数据
        异常
        InvalidMidiDataException - 如果文件未指向系统识别的有效MIDI文件数据
        IOException - 如果发生I / O异常
        NullPointerException - 如果 file是 null

      • 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)
        获得系统可以从指定的序列写入的MIDI文件类型集。
        参数
        sequence - 查询MIDI文件类型支持的序列
        结果
        唯一支持的文件类型集。 如果不支持任何文件类型，则返回长度为0的数组。
        异常
        NullPointerException - 如果 sequence是 null

      • isFileTypeSupported

        public static boolean isFileTypeSupported​(int fileType,
                                          Sequence sequence)
        指示是否可以从指示的序列中写入指定文件类型的MIDI文件。
        参数
        fileType - 要查询其写入功能的文件类型
        sequence - 查询文件写入支持的序列
        结果
        true如果此序列支持该文件类型，否则为 false
        异常
        NullPointerException - 如果 sequence是 null