MidiSystem JDK 1.6)

Description

public class MidiSystem

The MidiSystem class provides access to the installed MIDI system resources, including devices such as synthesizers, sequencers, and MIDI input and output ports.

The MidiSystem class provides access to the installed MIDI system resources, including devices such as synthesizers, sequencers, and MIDI input and output ports. A typical simple MIDI application might begin by invoking one or more MidiSystem methods to learn what devices are installed and to obtain the ones needed in that application.

The class also has methods for reading files, streams, and URLs that contain standard MIDI file data or soundbanks. You can query the MidiSystem for the format of a specified MIDI file.

You cannot instantiate a MidiSystem; all the methods are static.

Properties can be used to specify default MIDI devices. Both system properties and a properties file are considered. The properties file is "lib/sound.properties" in the JRE directory. If a property exists both as a system property and in the properties file, the system property takes precedence. If none is specified, a suitable default is chosen among the available devices. The syntax of the properties file is specified in Properties.load. The following table lists the available property keys and which methods consider them:

Property Key Interface Affected Method

javax.sound.midi.Receiver Receiver MidiSystem.getReceiver()

javax.sound.midi.Sequencer Sequencer MidiSystem.getSequencer()

javax.sound.midi.Synthesizer Synthesizer MidiSystem.getSynthesizer()

javax.sound.midi.Transmitter Transmitter MidiSystem.getTransmitter()

The property value consists of the provider class name and the device name, separated by the hash mark ("#"). The provider class name is the fully-qualified name of a concrete MIDI device provider class. The device name is matched against the String returned by the getName method of MidiDevice.Info. Either the class name, or the device name may be omitted. If only the class name is specified, the trailing hash mark is optional.

Property Key	Interface	Affected Method
`javax.sound.midi.Receiver`	`Receiver`	`MidiSystem.getReceiver()`
`javax.sound.midi.Sequencer`	`Sequencer`	`MidiSystem.getSequencer()`
`javax.sound.midi.Synthesizer`	`Synthesizer`	`MidiSystem.getSynthesizer()`
`javax.sound.midi.Transmitter`	`Transmitter`	`MidiSystem.getTransmitter()`

If the provider class is specified, and it can be successully retrieved from the installed providers, the list of MidiDevice.Info objects is retrieved from the provider. Otherwise, or when these devices do not provide a subsequent match, the list is retrieved from MidiSystem.getMidiDeviceInfo() to contain all available MidiDevice.Info objects.

If a device name is specified, the resulting list of MidiDevice.Info objects is searched: the first one with a matching name, and whose MidiDevice implements the respective interface, will be returned. If no matching MidiDevice.Info object is found, or the device name is not specified, the first suitable device from the resulting list will be returned. For Sequencer and Synthesizer, a device is suitable if it implements the respective interface; whereas for Receiver and Transmitter, a device is suitable if it implements neither Sequencer nor Synthesizer and provides at least one Receiver or Transmitter, respectively. For example, the property javax.sound.midi.Receiver with a value "com.sun.media.sound.MidiProvider#SunMIDI1" will have the following consequences when getReceiver is called: if the class com.sun.media.sound.MidiProvider exists in the list of installed MIDI device providers, the first Receiver device with name "SunMIDI1" will be returned. If it cannot be found, the first Receiver from that provider will be returned, regardless of name. If there is none, the first Receiver with name "SunMIDI1" in the list of all devices (as returned by getMidiDeviceInfo) will be returned, or, if not found, the first Receiver that can be found in the list of all devices is returned. If that fails, too, a MidiUnavailableException is thrown.

See also:

Methods

Hide/Show inherited methods

publicstatic MidiDevice getMidiDevice (Info info) throws MidiUnavailableException

Obtains the requested MIDI device.

publicstatic Info getMidiDeviceInfo ()

Obtains an array of information objects representing the set of all MIDI devices available on the system.

Obtains an array of information objects representing
the set of all MIDI devices available on the system.
A returned information object can then be used to obtain the
corresponding device object, by invoking
getMidiDevice.
Returns: an array of MidiDevice.Info objects, one for each installed MIDI device. If no such devices are installed, an array of length 0 is returned.

publicstatic MidiFileFormat getMidiFileFormat (File file) throws InvalidMidiDataException IOException

Obtains the MIDI file format of the specified File.

Obtains the MIDI file format of the specified File. The File must point to valid MIDI file data for a file type recognized by the system.

This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an InvalidMidiDataException even for valid files if no compatible file reader is installed. It will also fail with an InvalidMidiDataException if a compatible file reader is installed, but encounters errors while determining the file format.
Returns: a MidiFileFormat object describing the MIDI file format
Parameters:
- file - the File from which file format information should be extracted
Throws:
- InvalidMidiDataException - if the File does not point to valid MIDI file data recognized by the system
- IOException - if an I/O exception occurs while accessing the file
See Also: MidiSystem.getMidiFileFormat(InputStream), MidiSystem.getMidiFileFormat(URL),

publicstatic MidiFileFormat getMidiFileFormat (InputStream stream) throws InvalidMidiDataException IOException

Obtains the MIDI file format of the data in the specified input stream.

publicstatic MidiFileFormat getMidiFileFormat (URL url) throws InvalidMidiDataException IOException

Obtains the MIDI file format of the data in the specified URL.

publicstatic int getMidiFileTypes ()

Obtains the set of MIDI file types for which file writing support is provided by the system.

publicstatic int getMidiFileTypes (Sequence sequence)

Obtains the set of MIDI file types that the system can write from the sequence specified.

publicstatic Receiver getReceiver () throws MidiUnavailableException

Obtains a MIDI receiver from an external MIDI port or other default device.

publicstatic Sequence getSequence (File file) throws InvalidMidiDataException IOException

Obtains a MIDI sequence from the specified File.

Obtains a MIDI sequence from the specified File. The File must point to valid MIDI file data for a file type recognized by the system.

This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an InvalidMidiDataException even for valid files if no compatible file reader is installed. It will also fail with an InvalidMidiDataException if a compatible file reader is installed, but encounters errors while constructing the Sequence object from the file data.
Returns: a Sequence object based on the MIDI file data pointed to by the File
Parameters:
- file - the File from which the Sequence should be constructed
Throws:
- InvalidMidiDataException - if the File does not point to valid MIDI file data recognized by the system
- IOException - if an I/O exception occurs

publicstatic Sequence getSequence (InputStream stream) throws InvalidMidiDataException IOException

Obtains a MIDI sequence from the specified input stream.

publicstatic Sequence getSequence (URL url) throws InvalidMidiDataException IOException

Obtains a MIDI sequence from the specified URL.

publicstatic Sequencer getSequencer () throws MidiUnavailableException

Obtains the default Sequencer, connected to a default device.

Obtains the default Sequencer, connected to a default device. The returned Sequencer instance is connected to the default Synthesizer, as returned by MidiSystem.getSynthesizer(). If there is no Synthesizer available, or the default Synthesizer cannot be opened, the sequencer is connected to the default Receiver, as returned by MidiSystem.getReceiver(). The connection is made by retrieving a Transmitter instance from the Sequencer and setting its Receiver. Closing and re-opening the sequencer will restore the connection to the default device.

This method is equivalent to calling getSequencer(true).

If the system property javax.sound.midi.Sequencer is defined or it is defined in the file "sound.properties", it is used to identify the default sequencer. For details, refer to the class description.
Returns: the default sequencer, connected to a default Receiver
Throws:
- MidiUnavailableException - if the sequencer is not available due to resource restrictions, or there is no Receiver available by any installed MidiDevice, or no sequencer is installed in the system.
See Also: MidiSystem.getSequencer(boolean), MidiSystem.getSynthesizer(), MidiSystem.getReceiver(),

publicstatic Sequencer getSequencer (boolean connected) throws MidiUnavailableException

Obtains the default Sequencer, optionally connected to a default device.

If connected is true, the returned Sequencer instance is connected to the default Synthesizer, as returned by MidiSystem.getSynthesizer(). If there is no Synthesizer available, or the default Synthesizer cannot be opened, the sequencer is connected to the default Receiver, as returned by MidiSystem.getReceiver(). The connection is made by retrieving a Transmitter instance from the Sequencer and setting its Receiver. Closing and re-opening the sequencer will restore the connection to the default device.

If connected is false, the returned Sequencer instance is not connected, it has no open Transmitters. In order to play the sequencer on a MIDI device, or a Synthesizer, it is necessary to get a Transmitter and set its Receiver.

If the system property javax.sound.midi.Sequencer is defined or it is defined in the file "sound.properties", it is used to identify the default sequencer. For details, refer to the class description.
Returns: the default sequencer
Throws:
- MidiUnavailableException - if the sequencer is not available due to resource restrictions, or no sequencer is installed in the system, or if connected is true, and there is no Receiver available by any installed MidiDevice
Since: 1.5
See Also: MidiSystem.getSynthesizer(), MidiSystem.getReceiver(),

publicstatic Soundbank getSoundbank (File file) throws InvalidMidiDataException IOException

Constructs a Soundbank by reading it from the specified File.

Constructs a Soundbank by reading it from the specified
File.
The File must point to a valid MIDI soundbank file.
Returns: the sound bank
Parameters:
- file - the source of the sound bank data
Throws:
- InvalidMidiDataException - if the File does not point to valid MIDI soundbank data recognized by the system
- IOException - if an I/O error occurred when loading the soundbank

publicstatic Soundbank getSoundbank (InputStream stream) throws InvalidMidiDataException IOException

Constructs a MIDI sound bank by reading it from the specified stream.

publicstatic Soundbank getSoundbank (URL url) throws InvalidMidiDataException IOException

Constructs a Soundbank by reading it from the specified URL.

Constructs a Soundbank by reading it from the specified URL.
The URL must point to a valid MIDI soundbank file.
Returns: the sound bank
Parameters:
- url - the source of the sound bank data
Throws:
- InvalidMidiDataException - if the URL does not point to valid MIDI soundbank data recognized by the system
- IOException - if an I/O error occurred when loading the soundbank

publicstatic Synthesizer getSynthesizer () throws MidiUnavailableException

Obtains the default synthesizer.

publicstatic Transmitter getTransmitter () throws MidiUnavailableException

Obtains a MIDI transmitter from an external MIDI port or other default source.

publicstatic boolean isFileTypeSupported (int fileType)

Indicates whether file writing support for the specified MIDI file type is provided by the system.

Indicates whether file writing support for the specified MIDI file type
is provided by the system.
Returns: true if the file type is supported, otherwise false
Parameters:
- fileType - the file type for which write capabilities are queried

publicstatic boolean isFileTypeSupported (int fileType, Sequence sequence)

Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.

Indicates whether a MIDI file of the file type specified can be written
from the sequence indicated.
Returns: true if the file type is supported for this sequence, otherwise false
Parameters:
- fileType - the file type for which write capabilities are queried
- sequence - the sequence for which file writing support is queried

publicstatic int write (Sequence in, int type, File out) throws IOException

Writes a stream of bytes representing a file of the MIDI file type indicated to the external file provided.

publicstatic int write (Sequence in, int fileType, OutputStream out) throws IOException

Writes a stream of bytes representing a file of the MIDI file type indicated to the output stream provided.