JavaTM 2 Platform
Std. Ed. v1.4.1

javax.sound.midi
Class MidiSystem

java.lang.Object
  |
  +--javax.sound.midi.MidiSystem

public class MidiSystem
extends Object

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.


Method Summary
static MidiDevice getMidiDevice(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 MidiFileFormat getMidiFileFormat(File file)
          Obtains the MIDI file format of the specified File.
static MidiFileFormat getMidiFileFormat(InputStream stream)
          Obtains the MIDI file format of the data in the specified input stream.
static MidiFileFormat getMidiFileFormat(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 Receiver getReceiver()
          Obtains a MIDI receiver from an external MIDI port or other default source.
static Sequence getSequence(File file)
          Obtains a MIDI sequence from the specified File.
static Sequence getSequence(InputStream stream)
          Obtains a MIDI sequence from the specified input stream.
static Sequence getSequence(URL url)
          Obtains a MIDI sequence from the specified URL.
static Sequencer getSequencer()
          Obtains the default sequencer.
static Soundbank getSoundbank(File file)
          Constructs a Soundbank by reading it from the specified File.
static Soundbank getSoundbank(InputStream stream)
          Constructs a MIDI sound bank by reading it from the specified stream.
static Soundbank getSoundbank(URL url)
          Constructs a Soundbank by reading it from the specified URL.
static Synthesizer getSynthesizer()
          Obtains the default synthesizer.
static Transmitter getTransmitter()
          Obtains a MIDI transmitter from an external MIDI port or other default source.
static boolean isFileTypeSupported(int fileType)
          Indicates whether file writing support for the specified MIDI file type is provided by the system.
static boolean isFileTypeSupported(int fileType, Sequence sequence)
          Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.
static int write(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 int write(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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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 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.

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 restrictions
IllegalArgumentException - if the info object does not represent a MIDI device installed on the system
See Also:
getMidiDeviceInfo()

getReceiver

public static Receiver getReceiver()
                            throws MidiUnavailableException
Obtains a MIDI receiver from an external MIDI port or other default source.

Returns:
the default MIDI receiver
Throws:
MidiUnavailableException - if the default receiver is not available due to resource restrictions

getTransmitter

public static Transmitter getTransmitter()
                                  throws MidiUnavailableException
Obtains a MIDI transmitter from an external MIDI port or other default source.

Returns:
the default MIDI transmitter
Throws:
MidiUnavailableException - if the default transmitter is not available due to resource restrictions

getSynthesizer

public static Synthesizer getSynthesizer()
                                  throws MidiUnavailableException
Obtains the default synthesizer.

Returns:
the default synthesizer
Throws:
MidiUnavailableException - if the synthesizer is not available due to resource restrictions

getSequencer

public static Sequencer getSequencer()
                              throws MidiUnavailableException
Obtains the default sequencer.

Returns:
the default sequencer
Throws:
MidiUnavailableException - if the sequencer is not available due to resource restrictions

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 an IOException.

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 system
IOException - if an I/O error occurred when loading the soundbank
See Also:
InputStream.markSupported(), InputStream.mark(int)

getSoundbank

public static Soundbank getSoundbank(URL url)
                              throws InvalidMidiDataException,
                                     IOException
Constructs a Soundbank by 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 system
IOException - if an I/O error occurred when loading the soundbank

getSoundbank

public static Soundbank getSoundbank(File file)
                              throws InvalidMidiDataException,
                                     IOException
Constructs a Soundbank by reading it from the specified File. The File must point to a valid MIDI soundbank file.

Parameters:
file - the source of the sound bank data
Returns:
the sound bank
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

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 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.

Parameters:
stream - the input stream from which file format information should be extracted
Returns:
an MidiFileFormat object describing the MIDI file format
Throws:
InvalidMidiDataException - if the stream does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs while accessing the stream
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 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.

Parameters:
url - the URL from which file format information should be extracted
Returns:
a MidiFileFormat object describing the MIDI file format
Throws:
InvalidMidiDataException - if the URL does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs while accessing the URL
See Also:
getMidiFileFormat(InputStream), getMidiFileFormat(File)

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(File file)
                                        throws InvalidMidiDataException,
                                               IOException
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.

Parameters:
file - the File from which file format information should be extracted
Returns:
a MidiFileFormat object describing the MIDI file format
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:
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 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.

Parameters:
stream - the input stream from which the Sequence should be constructed
Returns:
a Sequence object 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 system
IOException - if an I/O exception occurs while accessing the stream
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 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.

Parameters:
url - the URL from which the Sequence should be constructed
Returns:
a Sequence object 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 system
IOException - if an I/O exception occurs while accessing the URL

getSequence

public static Sequence getSequence(File file)
                            throws InvalidMidiDataException,
                                   IOException
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.

Parameters:
file - the File from which the Sequence should be constructed
Returns:
a Sequence object 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 system
IOException - if an I/O exception occurs

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 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:
true if the file type is supported, otherwise false

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 supported file types. If no file types are supported, returns an array of length 0.

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 queried
sequence - the sequence for which file writing support is queried
Returns:
true if the file type is supported for this sequence, otherwise false

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 file
fileType - the file type of the file to be written to the output stream
out - 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 occurs
IllegalArgumentException - if the file format is not supported by the system
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 file
out - 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 occurs
IllegalArgumentException - if the file type is not supported by the system
See Also:
isFileTypeSupported(int, Sequence), getMidiFileTypes(Sequence)

JavaTM 2 Platform
Std. Ed. v1.4.1

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.