java.lang.Object javax.sound.midi.MidiSystem
public class MidiSystem
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 |
方法详细信息 |
---|
public static MidiDevice.Info[] getMidiDeviceInfo()
getMidiDevice
,可使用返回的信息对象获得相应的设备对象。
MidiDevice.Info
对象的数组,每个已安装的 MIDI 设备对应一个对象。如果未安装这样的设备,则返回长度为 0 的数组。
public static MidiDevice getMidiDevice(MidiDevice.Info info) throws MidiUnavailableException
info
- 表示所需设备的设备信息对象。
MidiUnavailableException
- 如果由于资源限制使所请求的设备不可用
IllegalArgumentException
- 如果 info 对象并不表示系统上已安装的 MIDI 设备
getMidiDeviceInfo()
public static Receiver getReceiver() throws MidiUnavailableException
如果定义了系统属性 javax.sound.midi.Receiver
,或者在文件 "sound.properties" 中定义了该属性,则它可用于标识提供了默认接收器的设备。有关详细信息,请参阅类描述
。 如果没有适合的 MIDI 端口可用,则从已安装的合成器中检索 Receiver。
如果此方法成功返回,则隐式打开 Receiver
所属于的 MidiDevice
(如果它尚未打开)。通过在返回的 Receiver
上调用 close
可以关闭一个隐式打开的设备。所有打开的 Receiver
实例都必须关闭,以释放由 MidiDevice
所占用的系统资源。有关打开/关闭行为的详细描述,请参见 MidiDevice
的类描述。
MidiUnavailableException
- 如果由于资源限制使默认的接收器不可用,或者系统上未安装任何提供接收器的设备
public static Transmitter getTransmitter() throws MidiUnavailableException
如果定义了系统属性 javax.sound.midi.Transmitter
,或者在文件 "sound.properties" 中定义了该属性,则它可用于标识提供了默认传输器的设备。有关详细信息,请参阅类描述
。 如果此方法成功返回,则隐式打开 Transmitter
所属于的 MidiDevice
(如果它尚未打开)。通过在返回的 Transmitter
上调用 close
可以关闭一个隐式打开的设备。所有打开的 Transmitter
实例都必须关闭,以释放由 MidiDevice
所占用的系统资源。有关打开/关闭行为的详细描述,请参见 MidiDevice
的类描述。
MidiUnavailableException
- 如果由于资源限制使默认的传输器不可用,或者系统上未安装任何提供传输器的设备
public static Synthesizer getSynthesizer() throws MidiUnavailableException
如果定义了系统属性 javax.sound.midi.Synthesizer
,或者在文件 "sound.properties" 中定义了该属性,则它可用于标识默认的合成器。有关详细信息,请参阅类描述
。
MidiUnavailableException
- 如果由于资源限制使合成器不可用,或者系统上未安装任何合成器
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。有关详细信息,请参阅类描述
。
MidiUnavailableException
- 如果由于资源限制使 sequencer 不可用,或者任何已安装的
MidiDevice
上都没有可用的
Receiver
,或者系统中未安装 sequencer。
getSequencer(boolean)
,
getSynthesizer()
,
getReceiver()
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。有关详细信息,请参阅类描述
。
MidiUnavailableException
- 如果由于资源限制使 sequencer 不可用,或者系统中未安装 sequencer,或者如果
connected
为 true 并且任何已安装的
MidiDevice
都没有可用的
Receiver
getSynthesizer()
,
getReceiver()
public static Soundbank getSoundbank(InputStream stream) throws InvalidMidiDataException, IOException
stream
- 音库数据的源。
InvalidMidiDataException
- 如果该流没有指向系统识别的有效 MIDI 音库数据
IOException
- 如果加载音库时发生 I/O 错误
InputStream.markSupported()
,
InputStream.mark(int)
public static Soundbank getSoundbank(URL url) throws InvalidMidiDataException, IOException
Soundbank
。该 URL 必须指向有效的 MIDI 音库文件。
url
- 音库数据的源
InvalidMidiDataException
- 如果 URL 未指向系统识别的有效 MIDI 音库数据
IOException
- 如果加载音库时发生 I/O 错误
public static Soundbank getSoundbank(File file) throws InvalidMidiDataException, IOException
File
读取来构造一个
Soundbank
。该
File
必须指向有效的 MIDI 音库文件。
file
- 音库数据的源
InvalidMidiDataException
- 如果
File
未指向系统识别的有效 MIDI 音库数据
IOException
- 如果加载音库时发生 I/O 错误
public static MidiFileFormat getMidiFileFormat(InputStream stream) throws InvalidMidiDataException, IOException
此方法和/或它调用的代码可能需要从流读取一些数据,以确定是否支持流的数据格式。因此实现可能需要标记流、读取足够的数据来确定流是否为支持的格式,并将流的阅读指针重新设置到其初始位置。如果输入流不允许此组操作,则此方法可能会失败,并抛出 IOException
。
只有针对那些能由已安装的文件 reader 所解析的类型的文件,该操作才能成功。即使是有效的文件,如果未安装兼容的文件 reader,则也会失败并抛出 InvalidMidiDataException。如果安装了兼容的文件 reader,但在确定文件格式时遇到错误,则也会失败并抛出 InvalidMidiDataException。
stream
- 应从中提取文件格式信息的输入流
MidiFileFormat
对象
InvalidMidiDataException
- 如果流没有指向系统识别的有效 MIDI 文件数据
IOException
- 如果访问流时发生 I/O 异常
getMidiFileFormat(URL)
,
getMidiFileFormat(File)
,
InputStream.markSupported()
,
InputStream.mark(int)
public static MidiFileFormat getMidiFileFormat(URL url) throws InvalidMidiDataException, IOException
只有针对那些能由已安装的文件 reader 所解析的类型的文件,该操作才能成功。即使是有效的文件,如果未安装兼容的文件 reader,则也会失败并抛出 InvalidMidiDataException。如果安装了兼容的文件 reader,但在确定文件格式时遇到错误,则也会失败并抛出 InvalidMidiDataException。
url
- 应该从中提取文件格式信息的 URL
MidiFileFormat
对象
InvalidMidiDataException
- 如果 URL 没有指向系统识别的有效 MIDI 文件数据
IOException
- 如果访问 URL 时发生 I/O 异常
getMidiFileFormat(InputStream)
,
getMidiFileFormat(File)
public static MidiFileFormat getMidiFileFormat(File file) throws InvalidMidiDataException, IOException
File
的 MIDI 文件格式。该
File
必须指向系统可识别的文件类型的有效 MIDI 文件数据。
只有针对那些能由已安装的文件 reader 所解析的类型的文件,该操作才能成功。即使是有效的文件,如果未安装兼容的文件 reader,则也会失败并抛出 InvalidMidiDataException。如果安装了兼容的文件 reader,但在确定文件格式时遇到错误,则也会失败并抛出 InvalidMidiDataException。
file
- 应该从中提取文件格式信息的
File
MidiFileFormat
对象
InvalidMidiDataException
- 如果
File
没有指向系统可识别的有效 MIDI 文件数据
IOException
- 如果访问文件时发生 I/O 异常
getMidiFileFormat(InputStream)
,
getMidiFileFormat(URL)
public static Sequence getSequence(InputStream stream) throws InvalidMidiDataException, IOException
此方法和/或它调用的代码可能需要从流读取一些数据,以确定是否支持流的数据格式。因此实现可能需要标记流、读取足够的数据来确定流是否为支持的格式,并将流的阅读指针重新设置到其初始位置。如果输入流不允许此组操作,则此方法可能会失败,并抛出 IOException
。
只有针对那些能由已安装的文件 reader 所解析的类型的文件,该操作才能成功。即使是有效的文件,如果未安装兼容的文件 reader,则也会失败并抛出 InvalidMidiDataException。如果安装了兼容的文件 reader,但在从文件数据构造 Sequence
对象时遇到错误,则也会失败并抛出 InvalidMidiDataException。
stream
- 应该从中构造
Sequence
的输入流
Sequence
对象
InvalidMidiDataException
- 如果流没有指向系统识别的有效 MIDI 文件数据
IOException
- 如果访问流时发生 I/O 异常
InputStream.markSupported()
,
InputStream.mark(int)
public static Sequence getSequence(URL url) throws InvalidMidiDataException, IOException
只有针对那些能由已安装的文件 reader 所解析的类型的文件,该操作才能成功。即使是有效的文件,如果未安装兼容的文件 reader,则也会失败并抛出 InvalidMidiDataException。如果安装了兼容的文件 reader,但在从文件数据构造 Sequence
对象时遇到错误,则也会失败并抛出 InvalidMidiDataException。
url
- 应该从中构造
Sequence
的 URL
Sequence
对象
InvalidMidiDataException
- 如果 URL 没有指向系统识别的有效 MIDI 文件数据
IOException
- 如果访问 URL 时发生 I/O 异常
public static Sequence getSequence(File file) throws InvalidMidiDataException, IOException
File
获得 MIDI 序列。该
File
必须指向系统可识别的文件类型的有效 MIDI 文件数据。
只有针对那些能由已安装的文件 reader 所解析的类型的文件,该操作才能成功。即使是有效的文件,如果未安装兼容的文件 reader,则也会失败并抛出 InvalidMidiDataException。如果安装了兼容的文件 reader,但在从文件数据构造 Sequence
对象时遇到错误,则也会失败并抛出 InvalidMidiDataException。
file
- 应该从中构造
Sequence
的
File
Sequence
对象
InvalidMidiDataException
- 如果 File 没有指向系统识别的有效 MIDI 文件数据
IOException
- 如果发生 I/O 异常
public static int[] getMidiFileTypes()
public static boolean isFileTypeSupported(int fileType)
fileType
- 查询其写入功能的文件类型
true
;否则返回
false
public static int[] getMidiFileTypes(Sequence sequence)
sequence
- 为其查询 MIDI 文件类型支持的序列
public static boolean isFileTypeSupported(int fileType, Sequence sequence)
fileType
- 查询其写入功能的文件类型
sequence
- 查询其文件写入支持的序列
true
;否则返回
false
public static int write(Sequence in, int fileType, OutputStream out) throws IOException
in
- 包含要写入文件的 MIDI 数据的序列
fileType
- 要写入输出流的文件的文件类型
out
- 应将文件数据写入的流
IOException
- 如果发生 I/O 异常
IllegalArgumentException
- 如果系统不支持该文件格式
isFileTypeSupported(int, Sequence)
,
getMidiFileTypes(Sequence)
public static int write(Sequence in, int type, File out) throws IOException
in
- 包含要写入文件的 MIDI 数据的序列
type
- 要写入输出流的文件的文件类型
out
- 应将文件数据写入的外部文件
IOException
- 如果发生 I/O 异常
IllegalArgumentException
- 如果系统不支持该文件类型
isFileTypeSupported(int, Sequence)
,
getMidiFileTypes(Sequence)