Module  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目录）。 如果属性既作为系统属性又在属性文件中存在，则系统属性优先。 如果没有指定，则在可用设备中选择合适的默认值。 属性文件的语法在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对象的列表。 否则，或者当这些设备不提供后续匹配时，将从getMidiDeviceInfo()检索列表以包含所有可用的MidiDevice.Info对象。

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

    例如，财产javax.sound.midi.Receiver一个值"com.sun.media.sound.MidiProvider#SunMIDI1"将在下列后果getReceiver被称为：如果类com.sun.media.sound.MidiProvider在已安装的MIDI设备提供者列表存在，则第Receiver名称为设备"SunMIDI1"将被退回。 如果找不到，则该提供商的第一个Receiver将被返回，无论名称如何。 如果没有，将返回所有设备（ getMidiDeviceInfo ）返回的名称为"SunMIDI1"的第Receiver ， "SunMIDI1"返回所有设备列表中可以找到的第一个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上调用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 。 关闭并重新打开音序器将恢复与默认设备的连接。

        这个方法相当于调用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 。 关闭并重新打开音序器将恢复与默认设备的连接。

        如果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
        结果
        一个基于文件指向的MIDI文件数据的 Sequence对象
        异常
        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