java.lang.Object

javax.sound.midi.MidiSystem

public class MidiSystem extends Object

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

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

您不能实例化MidiSystem；所有方法都是静态的。

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

MIDI系统属性键
属性键	接口	受影响的方法
`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设备提供程序类的完全限定名称。设备名称与MidiDevice.Info的getName方法返回的String进行匹配。可以省略类名或设备名称。如果只指定类名，则尾随的井号是可选的。

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

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

例如，属性javax.sound.midi.Receiver的值为"com.sun.media.sound.MidiProvider#SunMIDI1"，当调用getReceiver时将产生以下后果：如果类com.sun.media.sound.MidiProvider存在于安装的MIDI设备提供程序列表中，则将返回名称为"SunMIDI1"的第一个Receiver设备。如果找不到，则将返回该提供程序的第一个Receiver，而不管名称如何。如果没有，则将返回结果列表中名称为"SunMIDI1"的第一个Receiver（由getMidiDeviceInfo返回），或者如果找不到，则返回结果列表中找到的第一个Receiver。如果这也失败，则会抛出MidiUnavailableException。

Method Summary

Modifier and Type

Method

Description

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)

获取系统可以从指定序列写入的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文件类型的文件的字节流写入提供的输出流。

Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- 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 - 如果信息对象不表示系统上安装的MIDI设备
  
  NullPointerException - 如果info为null
  
  参见：
  
  getMidiDeviceInfo()
- getReceiver
  
  public static Receiver getReceiver() throws MidiUnavailableException
  
  从外部MIDI端口或其他默认设备获取MIDI接收器。返回的接收器始终实现MidiDeviceReceiver接口。
  如果系统属性javax.sound.midi.Receiver已定义，或者在文件"sound.properties"中定义了它，则将用于标识提供默认接收器的设备。有关详细信息，请参阅类描述。
  
  如果没有合适的MIDI端口可用，则将从已安装的合成器中检索接收器。
  
  如果默认设备提供的本机接收器未实现MidiDeviceReceiver接口，则将其包装在一个实现MidiDeviceReceiver接口的包装类中。相应的Receiver方法调用将转发到本机接收器。
  
  如果此方法成功返回，则所属的MidiDevice的Receiver将隐式打开，如果尚未打开。可以通过在返回的Receiver上调用close来关闭隐式打开的设备。为了释放MidiDevice占用的系统资源，必须关闭所有打开的Receiver实例。有关打开/关闭行为的详细描述，请参阅MidiDevice的类描述。
  
  返回：
  
  默认的MIDI接收器
  
  抛出：
  
  MidiUnavailableException - 如果由于资源限制而无法使用默认接收器，或者系统中没有提供接收器的设备
- getTransmitter
  
  public static Transmitter getTransmitter() throws MidiUnavailableException
  
  从外部MIDI端口或其他默认源获取MIDI发射器。返回的发射器始终实现MidiDeviceTransmitter接口。
  如果系统属性javax.sound.midi.Transmitter已定义，或者在文件"sound.properties"中定义了它，它将用于标识提供默认发射器的设备。有关详细信息，请参阅类描述。
  
  如果默认设备提供的本机发射器未实现MidiDeviceTransmitter接口，则将其包装在一个实现MidiDeviceTransmitter接口的包装类中。相应的Transmitter方法调用将转发到本机发射器。
  
  如果此方法成功返回，则Transmitter所属的MidiDevice将隐式打开，如果尚未打开。可以通过在返回的Transmitter上调用close来关闭隐式打开的设备。为了释放MidiDevice占用的系统资源，必须关闭所有打开的Transmitter实例。有关打开/关闭行为的详细描述，请参阅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来完成的。关闭并重新打开序列器将恢复与默认设备的连接。
  此方法等效于调用getSequencer(true)。
  
  如果系统属性javax.sound.midi.Sequencer已定义，或者在文件"sound.properties"中定义了它，它将用于标识默认序列器。有关详细信息，请参阅类描述。
  返回：
  
  默认连接到默认Receiver的序列器
  
  抛出：
  
  MidiUnavailableException - 如果由于资源限制而无法使用序列器，或任何已安装的MidiDevice中没有可用的Receiver，或系统中未安装序列器
  
  参见：
  
  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"中定义了它，它将用于标识默认序列器。有关详细信息，请参阅类描述。
  参数：
  
  connected - 返回的Sequencer是否连接到默认Synthesizer
  
  返回：
  
  默认序列器
  
  抛出：
  
  MidiUnavailableException - 如果由于资源限制而无法使用序列器，或系统中未安装序列器，或者如果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错误
  
  NullPointerException - 如果stream为null
  
  参见：
  
  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错误
  
  NullPointerException - 如果url为null
- getSoundbank
  
  public static Soundbank getSoundbank(File file) throws InvalidMidiDataException, IOException
  
  通过从指定File中读取它来构造Soundbank。File必须指向有效的MIDI音色库文件。
  
  参数：
  
  file - 音色库数据的来源
  
  返回：
  
  音色库
  
  抛出：
  
  InvalidMidiDataException - 如果File不指向系统识别的有效MIDI音色库数据
  
  IOException - 加载音色库时发生I/O错误
  
  NullPointerException - 如果file为null
- 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。如果安装了兼容的文件读取器，但在构建Sequence对象时遇到错误，也会出现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。如果安装了兼容的文件读取器，但在从文件数据构建Sequence对象时遇到错误，也会出现InvalidMidiDataException。
  参数:
  
  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。如果安装了兼容的文件读取器，但在从文件数据构建Sequence对象时遇到错误，也会出现InvalidMidiDataException。
  
  参数:
  
  url - 应从中构建Sequence的URL
  
  返回:
  
  基于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。如果安装了兼容的文件读取器，但在从文件数据构建Sequence对象时遇到错误，也会出现InvalidMidiDataException。
  
  参数:
  
  file - 应从中构建Sequence的File
  
  返回:
  
  基于File指向的MIDI文件数据的Sequence对象
  
  抛出:
  
  InvalidMidiDataException - 如果File不指向系统识别的有效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
- write
  
  public static int write(Sequence in, int fileType, OutputStream out) throws IOException
  
  将表示指定MIDI文件类型的字节流写入提供的输出流。
  参数:
  
  in - 包含要写入文件的MIDI数据的序列
  
  fileType - 要写入输出流的文件类型
  
  out - 应将文件数据写入的流
  
  返回:
  
  写入输出流的字节数
  
  抛出:
  
  IOException - 如果发生I/O异常
  
  IllegalArgumentException - 如果系统不支持文件格式
  
  NullPointerException - 如果in或out为null
  
  参见:
  
  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 - 如果系统不支持文件类型
  
  NullPointerException - 如果in或out为null
  
  参见:
  
  isFileTypeSupported(int, Sequence)
  
  getMidiFileTypes(Sequence)

Class MidiSystem

Method Summary

Methods declared in class java.lang.Object

Method Details

getMidiDeviceInfo

getMidiDevice

getReceiver

getTransmitter

getSynthesizer

getSequencer

getSequencer

getSoundbank

getSoundbank

getSoundbank

getMidiFileFormat

getMidiFileFormat

getMidiFileFormat

getSequence

getSequence

getSequence

getMidiFileTypes

isFileTypeSupported

getMidiFileTypes

isFileTypeSupported

write

write