- java.lang.Object
-
- javax.sound.midi.MidiSystem
-
public class MidiSystem extends Object
TheMidiSystemclass 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 moreMidiSystemmethods 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
MidiSystemfor 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 "sound.properties" properties file is read from an implementation-specific location (typically it is the
confdirectory in the Java installation directory). The optional "javax.sound.config.file" system property can be used to specify the properties file that will be read as the initial configuration. 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 inProperties.load. The following table lists the available property keys and which methods consider them:
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 concreteMIDI System Property Keys Property Key Interface Affected Method javax.sound.midi.ReceiverReceivergetReceiver()javax.sound.midi.SequencerSequencergetSequencer()javax.sound.midi.SynthesizerSynthesizergetSynthesizer()javax.sound.midi.TransmitterTransmittergetTransmitter()MIDI device providerclass. The device name is matched against theStringreturned by thegetNamemethod ofMidiDevice.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.If the provider class is specified, and it can be successfully retrieved from the installed providers, the list of
MidiDevice.Infoobjects is retrieved from the provider. Otherwise, or when these devices do not provide a subsequent match, the list is retrieved fromgetMidiDeviceInfo()to contain all availableMidiDevice.Infoobjects.If a device name is specified, the resulting list of
MidiDevice.Infoobjects is searched: the first one with a matching name, and whoseMidiDeviceimplements the respective interface, will be returned. If no matchingMidiDevice.Infoobject 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.Receiverwith a value"com.sun.media.sound.MidiProvider#SunMIDI1"will have the following consequences whengetReceiveris called: if the classcom.sun.media.sound.MidiProviderexists in the list of installed MIDI device providers, the firstReceiverdevice with name"SunMIDI1"will be returned. If it cannot be found, the firstReceiverfrom that provider will be returned, regardless of name. If there is none, the firstReceiverwith name"SunMIDI1"in the list of all devices (as returned bygetMidiDeviceInfo) will be returned, or, if not found, the firstReceiverthat can be found in the list of all devices is returned. If that fails, too, aMidiUnavailableExceptionis thrown.
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static MidiDevicegetMidiDevice(MidiDevice.Info info)Obtains the requested MIDI device.static MidiDevice.Info[]getMidiDeviceInfo()Obtains an array of information objects representing the set of all MIDI devices available on the system.static MidiFileFormatgetMidiFileFormat(File file)Obtains the MIDI file format of the specifiedFile.static MidiFileFormatgetMidiFileFormat(InputStream stream)Obtains the MIDI file format of the data in the specified input stream.static MidiFileFormatgetMidiFileFormat(URL url)Obtains the MIDI file format of the data in the specified URL.static int[]getMidiFileTypes()Obtains the set of MIDI file types for which file writing support is provided by the system.static int[]getMidiFileTypes(Sequence sequence)Obtains the set of MIDI file types that the system can write from the sequence specified.static ReceivergetReceiver()Obtains a MIDI receiver from an external MIDI port or other default device.static SequencegetSequence(File file)Obtains a MIDI sequence from the specifiedFile.static SequencegetSequence(InputStream stream)Obtains a MIDI sequence from the specified input stream.static SequencegetSequence(URL url)Obtains a MIDI sequence from the specified URL.static SequencergetSequencer()Obtains the defaultSequencer, connected to a default device.static SequencergetSequencer(boolean connected)Obtains the defaultSequencer, optionally connected to a default device.static SoundbankgetSoundbank(File file)Constructs aSoundbankby reading it from the specifiedFile.static SoundbankgetSoundbank(InputStream stream)Constructs a MIDI sound bank by reading it from the specified stream.static SoundbankgetSoundbank(URL url)Constructs aSoundbankby reading it from the specified URL.static SynthesizergetSynthesizer()Obtains the default synthesizer.static TransmittergetTransmitter()Obtains a MIDI transmitter from an external MIDI port or other default source.static booleanisFileTypeSupported(int fileType)Indicates whether file writing support for the specified MIDI file type is provided by the system.static booleanisFileTypeSupported(int fileType, Sequence sequence)Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.static intwrite(Sequence in, int type, File out)Writes a stream of bytes representing a file of the MIDI file type indicated to the external file provided.static intwrite(Sequence in, int fileType, OutputStream out)Writes a stream of bytes representing a file of the MIDI file type indicated to the output stream provided.
-
-
-
Method Detail
-
getMidiDeviceInfo
public static MidiDevice.Info[] getMidiDeviceInfo()
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 invokinggetMidiDevice.- Returns:
- an array of
MidiDevice.Infoobjects, one for each installed MIDI device. If no such devices are installed, an array of length 0 is returned.
-
getMidiDevice
public static MidiDevice getMidiDevice(MidiDevice.Info info) throws MidiUnavailableException
Obtains the requested MIDI device.- Parameters:
info- a device information object representing the desired device- Returns:
- the requested device
- Throws:
MidiUnavailableException- if the requested device is not available due to resource restrictionsIllegalArgumentException- if the info object does not represent a MIDI device installed on the systemNullPointerException- ifinfoisnull- See Also:
getMidiDeviceInfo()
-
getReceiver
public static Receiver getReceiver() throws MidiUnavailableException
Obtains a MIDI receiver from an external MIDI port or other default device. The returned receiver always implements theMidiDeviceReceiverinterface.If the system property
javax.sound.midi.Receiveris defined or it is defined in the file "sound.properties", it is used to identify the device that provides the default receiver. For details, refer to theclass description.If a suitable MIDI port is not available, the Receiver is retrieved from an installed synthesizer.
If a native receiver provided by the default device does not implement the
MidiDeviceReceiverinterface, it will be wrapped in a wrapper class that implements theMidiDeviceReceiverinterface. The correspondingReceivermethod calls will be forwarded to the native receiver.If this method returns successfully, the
MidiDevicetheReceiverbelongs to is opened implicitly, if it is not already open. It is possible to close an implicitly opened device by callingcloseon the returnedReceiver. All openReceiverinstances have to be closed in order to release system resources hold by theMidiDevice. For a detailed description of open/close behaviour see the class description ofMidiDevice.- Returns:
- the default MIDI receiver
- Throws:
MidiUnavailableException- if the default receiver is not available due to resource restrictions, or no device providing receivers is installed in the system
-
getTransmitter
public static Transmitter getTransmitter() throws MidiUnavailableException
Obtains a MIDI transmitter from an external MIDI port or other default source. The returned transmitter always implements theMidiDeviceTransmitterinterface.If the system property
javax.sound.midi.Transmitteris defined or it is defined in the file "sound.properties", it is used to identify the device that provides the default transmitter. For details, refer to theclass description.If a native transmitter provided by the default device does not implement the
MidiDeviceTransmitterinterface, it will be wrapped in a wrapper class that implements theMidiDeviceTransmitterinterface. The correspondingTransmittermethod calls will be forwarded to the native transmitter.If this method returns successfully, the
MidiDevicetheTransmitterbelongs to is opened implicitly, if it is not already open. It is possible to close an implicitly opened device by callingcloseon the returnedTransmitter. All openTransmitterinstances have to be closed in order to release system resources hold by theMidiDevice. For a detailed description of open/close behaviour see the class description ofMidiDevice.- Returns:
- the default MIDI transmitter
- Throws:
MidiUnavailableException- if the default transmitter is not available due to resource restrictions, or no device providing transmitters is installed in the system
-
getSynthesizer
public static Synthesizer getSynthesizer() throws MidiUnavailableException
Obtains the default synthesizer.If the system property
javax.sound.midi.Synthesizeris defined or it is defined in the file "sound.properties", it is used to identify the default synthesizer. For details, refer to theclass description.- Returns:
- the default synthesizer
- Throws:
MidiUnavailableException- if the synthesizer is not available due to resource restrictions, or no synthesizer is installed in the system
-
getSequencer
public static Sequencer getSequencer() throws MidiUnavailableException
Obtains the defaultSequencer, connected to a default device. The returnedSequencerinstance is connected to the defaultSynthesizer, as returned bygetSynthesizer(). If there is noSynthesizeravailable, or the defaultSynthesizercannot be opened, thesequenceris connected to the defaultReceiver, as returned bygetReceiver(). The connection is made by retrieving aTransmitterinstance from theSequencerand setting itsReceiver. 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.Sequenceris defined or it is defined in the file "sound.properties", it is used to identify the default sequencer. For details, refer to theclass 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 noReceiveravailable by any installedMidiDevice, or no sequencer is installed in the system- See Also:
getSequencer(boolean),getSynthesizer(),getReceiver()
-
getSequencer
public static Sequencer getSequencer(boolean connected) throws MidiUnavailableException
Obtains the defaultSequencer, optionally connected to a default device.If
connectedis true, the returnedSequencerinstance is connected to the defaultSynthesizer, as returned bygetSynthesizer(). If there is noSynthesizeravailable, or the defaultSynthesizercannot be opened, thesequenceris connected to the defaultReceiver, as returned bygetReceiver(). The connection is made by retrieving aTransmitterinstance from theSequencerand setting itsReceiver. Closing and re-opening the sequencer will restore the connection to the default device.If
connectedis false, the returnedSequencerinstance is not connected, it has no openTransmitters. In order to play the sequencer on a MIDI device, or aSynthesizer, it is necessary to get aTransmitterand set itsReceiver.If the system property
javax.sound.midi.Sequenceris defined or it is defined in the file "sound.properties", it is used to identify the default sequencer. For details, refer to theclass description.- Parameters:
connected- whether or not the returnedSequenceris connected to the defaultSynthesizer- 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 ifconnectedis true, and there is noReceiveravailable by any installedMidiDevice- Since:
- 1.5
- See Also:
getSynthesizer(),getReceiver()
-
getSoundbank
public static Soundbank getSoundbank(InputStream stream) throws InvalidMidiDataException, IOException
Constructs a MIDI sound bank by reading it from the specified stream. The stream must point to a valid MIDI soundbank file. In general, MIDI soundbank providers may need to read some data from the stream before determining whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support this, this method may fail with anIOException.- Parameters:
stream- the source of the sound bank data- Returns:
- the sound bank
- Throws:
InvalidMidiDataException- if the stream does not point to valid MIDI soundbank data recognized by the systemIOException- if an I/O error occurred when loading the soundbankNullPointerException- ifstreamisnull- See Also:
InputStream.markSupported(),InputStream.mark(int)
-
getSoundbank
public static Soundbank getSoundbank(URL url) throws InvalidMidiDataException, IOException
Constructs aSoundbankby reading it from the specified URL. The URL must point to a valid MIDI soundbank file.- Parameters:
url- the source of the sound bank data- Returns:
- the sound bank
- Throws:
InvalidMidiDataException- if the URL does not point to valid MIDI soundbank data recognized by the systemIOException- if an I/O error occurred when loading the soundbankNullPointerException- ifurlisnull
-
getSoundbank
public static Soundbank getSoundbank(File file) throws InvalidMidiDataException, IOException
Constructs aSoundbankby reading it from the specifiedFile. TheFilemust point to a valid MIDI soundbank file.- Parameters:
file- the source of the sound bank data- Returns:
- the sound bank
- Throws:
InvalidMidiDataException- if theFiledoes not point to valid MIDI soundbank data recognized by the systemIOException- if an I/O error occurred when loading the soundbankNullPointerException- iffileisnull
-
getMidiFileFormat
public static MidiFileFormat getMidiFileFormat(InputStream stream) throws InvalidMidiDataException, IOException
Obtains the MIDI file format of the data in the specified input stream. The stream must point to valid MIDI file data for a file type recognized by the system.This method and/or the code it invokes may need to read some data from the stream to determine whether its data format is supported. The implementation may therefore need to mark the stream, read enough data to determine whether it is in a supported format, and reset the stream's read pointer to its original position. If the input stream does not permit this set of operations, this method may fail with an
IOException.This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an
InvalidMidiDataExceptioneven for valid files if no compatible file reader is installed. It will also fail with anInvalidMidiDataExceptionif a compatible file reader is installed, but encounters errors while determining the file format.- Parameters:
stream- the input stream from which file format information should be extracted- Returns:
- an
MidiFileFormatobject describing the MIDI file format - Throws:
InvalidMidiDataException- if the stream does not point to valid MIDI file data recognized by the systemIOException- if an I/O exception occurs while accessing the streamNullPointerException- ifstreamisnull- See Also:
getMidiFileFormat(URL),getMidiFileFormat(File),InputStream.markSupported(),InputStream.mark(int)
-
getMidiFileFormat
public static MidiFileFormat getMidiFileFormat(URL url) throws InvalidMidiDataException, IOException
Obtains the MIDI file format of the data in the specified URL. The URL 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
InvalidMidiDataExceptioneven for valid files if no compatible file reader is installed. It will also fail with anInvalidMidiDataExceptionif a compatible file reader is installed, but encounters errors while determining the file format.- Parameters:
url- the URL from which file format information should be extracted- Returns:
- a
MidiFileFormatobject describing the MIDI file format - Throws:
InvalidMidiDataException- if the URL does not point to valid MIDI file data recognized by the systemIOException- if an I/O exception occurs while accessing the URLNullPointerException- ifurlisnull- See Also:
getMidiFileFormat(InputStream),getMidiFileFormat(File)
-
getMidiFileFormat
public static MidiFileFormat getMidiFileFormat(File file) throws InvalidMidiDataException, IOException
Obtains the MIDI file format of the specifiedFile. TheFilemust 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
InvalidMidiDataExceptioneven for valid files if no compatible file reader is installed. It will also fail with anInvalidMidiDataExceptionif a compatible file reader is installed, but encounters errors while determining the file format.- Parameters:
file- theFilefrom which file format information should be extracted- Returns:
- a
MidiFileFormatobject describing the MIDI file format - Throws:
InvalidMidiDataException- if theFiledoes not point to valid MIDI file data recognized by the systemIOException- if an I/O exception occurs while accessing the fileNullPointerException- iffileisnull- See Also:
getMidiFileFormat(InputStream),getMidiFileFormat(URL)
-
getSequence
public static Sequence getSequence(InputStream stream) throws InvalidMidiDataException, IOException
Obtains a MIDI sequence from the specified input stream. The stream must point to valid MIDI file data for a file type recognized by the system.This method and/or the code it invokes may need to read some data from the stream to determine whether its data format is supported. The implementation may therefore need to mark the stream, read enough data to determine whether it is in a supported format, and reset the stream's read pointer to its original position. If the input stream does not permit this set of operations, this method may fail with an
IOException.This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an
InvalidMidiDataExceptioneven for valid files if no compatible file reader is installed. It will also fail with anInvalidMidiDataExceptionif a compatible file reader is installed, but encounters errors while constructing theSequenceobject from the file data.- Parameters:
stream- the input stream from which theSequenceshould be constructed- Returns:
- a
Sequenceobject based on the MIDI file data contained in the input stream - Throws:
InvalidMidiDataException- if the stream does not point to valid MIDI file data recognized by the systemIOException- if an I/O exception occurs while accessing the streamNullPointerException- ifstreamisnull- See Also:
InputStream.markSupported(),InputStream.mark(int)
-
getSequence
public static Sequence getSequence(URL url) throws InvalidMidiDataException, IOException
Obtains a MIDI sequence from the specified URL. The URL 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
InvalidMidiDataExceptioneven for valid files if no compatible file reader is installed. It will also fail with anInvalidMidiDataExceptionif a compatible file reader is installed, but encounters errors while constructing theSequenceobject from the file data.- Parameters:
url- the URL from which theSequenceshould be constructed- Returns:
- a
Sequenceobject based on the MIDI file data pointed to by the URL - Throws:
InvalidMidiDataException- if the URL does not point to valid MIDI file data recognized by the systemIOException- if an I/O exception occurs while accessing the URLNullPointerException- ifurlisnull
-
getSequence
public static Sequence getSequence(File file) throws InvalidMidiDataException, IOException
Obtains a MIDI sequence from the specifiedFile. TheFilemust 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
InvalidMidiDataExceptioneven for valid files if no compatible file reader is installed. It will also fail with anInvalidMidiDataExceptionif a compatible file reader is installed, but encounters errors while constructing theSequenceobject from the file data.- Parameters:
file- theFilefrom which theSequenceshould be constructed- Returns:
- a
Sequenceobject based on the MIDI file data pointed to by the File - Throws:
InvalidMidiDataException- if the File does not point to valid MIDI file data recognized by the systemIOException- if an I/O exception occursNullPointerException- iffileisnull
-
getMidiFileTypes
public static int[] getMidiFileTypes()
Obtains the set of MIDI file types for which file writing support is provided by the system.- Returns:
- array of unique file types. If no file types are supported, an array of length 0 is returned.
-
isFileTypeSupported
public static boolean isFileTypeSupported(int fileType)
Indicates whether file writing support for the specified MIDI file type is provided by the system.- Parameters:
fileType- the file type for which write capabilities are queried- Returns:
trueif the file type is supported, otherwisefalse
-
getMidiFileTypes
public static int[] getMidiFileTypes(Sequence sequence)
Obtains the set of MIDI file types that the system can write from the sequence specified.- Parameters:
sequence- the sequence for which MIDI file type support is queried- Returns:
- the set of unique supported file types. If no file types are supported, returns an array of length 0.
- Throws:
NullPointerException- ifsequenceisnull
-
isFileTypeSupported
public static boolean isFileTypeSupported(int fileType, Sequence sequence)Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.- Parameters:
fileType- the file type for which write capabilities are queriedsequence- the sequence for which file writing support is queried- Returns:
trueif the file type is supported for this sequence, otherwisefalse- Throws:
NullPointerException- ifsequenceisnull
-
write
public static 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.- Parameters:
in- sequence containing MIDI data to be written to the filefileType- the file type of the file to be written to the output streamout- stream to which the file data should be written- Returns:
- the number of bytes written to the output stream
- Throws:
IOException- if an I/O exception occursIllegalArgumentException- if the file format is not supported by the systemNullPointerException- ifinoroutarenull- See Also:
isFileTypeSupported(int, Sequence),getMidiFileTypes(Sequence)
-
write
public static 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.- Parameters:
in- sequence containing MIDI data to be written to the filetype- the file type of the file to be written to the output streamout- external file to which the file data should be written- Returns:
- the number of bytes written to the file
- Throws:
IOException- if an I/O exception occursIllegalArgumentException- if the file type is not supported by the systemNullPointerException- ifinoroutarenull- See Also:
isFileTypeSupported(int, Sequence),getMidiFileTypes(Sequence)
-
-