public class MidiSystem extends Object
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 "sound.properties" properties file is read from an implementation-specific location (typically it is the conf
directory 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 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 |
getReceiver() |
javax.sound.midi.Sequencer |
Sequencer |
getSequencer() |
javax.sound.midi.Synthesizer |
Synthesizer |
getSynthesizer() |
javax.sound.midi.Transmitter |
Transmitter |
getTransmitter() |
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. If the provider class is specified, and it can be successfully 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 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.
Modifier and Type | Method | Description |
---|---|---|
static MidiDevice |
getMidiDevice |
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 |
Obtains the MIDI file format of the specified File . |
static MidiFileFormat |
getMidiFileFormat |
Obtains the MIDI file format of the data in the specified input stream. |
static MidiFileFormat |
getMidiFileFormat |
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 |
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 device. |
static Sequence |
getSequence |
Obtains a MIDI sequence from the specified File . |
static Sequence |
getSequence |
Obtains a MIDI sequence from the specified input stream. |
static Sequence |
getSequence |
Obtains a MIDI sequence from the specified URL. |
static Sequencer |
getSequencer() |
Obtains the default Sequencer , connected to a default device. |
static Sequencer |
getSequencer |
Obtains the default Sequencer , optionally connected to a default device. |
static Soundbank |
getSoundbank |
Constructs a Soundbank by reading it from the specified File . |
static Soundbank |
getSoundbank |
Constructs a MIDI sound bank by reading it from the specified stream. |
static Soundbank |
getSoundbank |
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 |
Indicates whether file writing support for the specified MIDI file type is provided by the system. |
static boolean |
isFileTypeSupported |
Indicates whether a MIDI file of the file type specified can be written from the sequence indicated. |
static int |
write |
Writes a stream of bytes representing a file of the MIDI file type indicated to the external file provided. |
static int |
write |
Writes a stream of bytes representing a file of the MIDI file type indicated to the output stream provided. |
public static MidiDevice.Info[] getMidiDeviceInfo()
getMidiDevice
.MidiDevice.Info
objects, one for each installed MIDI device. If no such devices are installed, an array of length 0 is returned.public static MidiDevice getMidiDevice(MidiDevice.Info info) throws MidiUnavailableException
info
- a device information object representing the desired deviceMidiUnavailableException
- 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
- if info
is null
public static Receiver getReceiver() throws MidiUnavailableException
MidiDeviceReceiver
interface. If the system property javax.sound.midi.Receiver
is 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 the class 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 MidiDeviceReceiver
interface, it will be wrapped in a wrapper class that implements the MidiDeviceReceiver
interface. The corresponding Receiver
method calls will be forwarded to the native receiver.
If this method returns successfully, the MidiDevice
the Receiver
belongs to is opened implicitly, if it is not already open. It is possible to close an implicitly opened device by calling close
on the returned Receiver
. All open Receiver
instances have to be closed in order to release system resources hold by the MidiDevice
. For a detailed description of open/close behaviour see the class description of MidiDevice
.
MidiUnavailableException
- if the default receiver is not available due to resource restrictions, or no device providing receivers is installed in the systempublic static Transmitter getTransmitter() throws MidiUnavailableException
MidiDeviceTransmitter
interface. If the system property javax.sound.midi.Transmitter
is 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 the class description
.
If a native transmitter provided by the default device does not implement the MidiDeviceTransmitter
interface, it will be wrapped in a wrapper class that implements the MidiDeviceTransmitter
interface. The corresponding Transmitter
method calls will be forwarded to the native transmitter.
If this method returns successfully, the MidiDevice
the Transmitter
belongs to is opened implicitly, if it is not already open. It is possible to close an implicitly opened device by calling close
on the returned Transmitter
. All open Transmitter
instances have to be closed in order to release system resources hold by the MidiDevice
. For a detailed description of open/close behaviour see the class description of MidiDevice
.
MidiUnavailableException
- if the default transmitter is not available due to resource restrictions, or no device providing transmitters is installed in the systempublic static Synthesizer getSynthesizer() throws MidiUnavailableException
If the system property javax.sound.midi.Synthesizer
is defined or it is defined in the file "sound.properties", it is used to identify the default synthesizer. For details, refer to the class description
.
MidiUnavailableException
- if the synthesizer is not available due to resource restrictions, or no synthesizer is installed in the systempublic static Sequencer getSequencer() throws MidiUnavailableException
Sequencer
, connected to a default device. The returned Sequencer
instance is connected to the default Synthesizer
, as returned by 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 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
.
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 systempublic static Sequencer getSequencer(boolean connected) throws MidiUnavailableException
Sequencer
, optionally connected to a default device. If connected
is true, the returned Sequencer
instance is connected to the default Synthesizer
, as returned by 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 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
.
connected
- whether or not the returned Sequencer
is connected to the default Synthesizer
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
public static Soundbank getSoundbank(InputStream stream) throws InvalidMidiDataException, IOException
IOException
.stream
- the source of the sound bank dataInvalidMidiDataException
- 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
- if stream
is null
public static Soundbank getSoundbank(URL url) throws InvalidMidiDataException, IOException
Soundbank
by reading it from the specified URL. The URL must point to a valid MIDI soundbank file.url
- the source of the sound bank dataInvalidMidiDataException
- 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
- if url
is null
public static Soundbank getSoundbank(File file) throws InvalidMidiDataException, IOException
Soundbank
by reading it from the specified File
. The File
must point to a valid MIDI soundbank file.file
- the source of the sound bank dataInvalidMidiDataException
- if the File
does not point to valid MIDI soundbank data recognized by the systemIOException
- if an I/O error occurred when loading the soundbankNullPointerException
- if file
is null
public static MidiFileFormat getMidiFileFormat(InputStream stream) throws InvalidMidiDataException, IOException
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.
stream
- the input stream from which file format information should be extractedMidiFileFormat
object describing the MIDI file formatInvalidMidiDataException
- 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
- if stream
is null
public static MidiFileFormat getMidiFileFormat(URL url) throws InvalidMidiDataException, 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.
url
- the URL from which file format information should be extractedMidiFileFormat
object describing the MIDI file formatInvalidMidiDataException
- 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
- if url
is null
public static MidiFileFormat getMidiFileFormat(File file) throws InvalidMidiDataException, IOException
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.
file
- the File
from which file format information should be extractedMidiFileFormat
object describing the MIDI file formatInvalidMidiDataException
- if the File
does not point to valid MIDI file data recognized by the systemIOException
- if an I/O exception occurs while accessing the fileNullPointerException
- if file
is null
public static Sequence getSequence(InputStream stream) throws InvalidMidiDataException, IOException
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.
stream
- the input stream from which the Sequence
should be constructedSequence
object based on the MIDI file data contained in the input streamInvalidMidiDataException
- 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
- if stream
is null
public static Sequence getSequence(URL url) throws InvalidMidiDataException, 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.
url
- the URL from which the Sequence
should be constructedSequence
object based on the MIDI file data pointed to by the URLInvalidMidiDataException
- 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
- if url
is null
public static Sequence getSequence(File file) throws InvalidMidiDataException, IOException
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.
file
- the File
from which the Sequence
should be constructedSequence
object based on the MIDI file data pointed to by the FileInvalidMidiDataException
- if the File does not point to valid MIDI file data recognized by the systemIOException
- if an I/O exception occursNullPointerException
- if file
is null
public static int[] getMidiFileTypes()
public static boolean isFileTypeSupported(int fileType)
fileType
- the file type for which write capabilities are queriedtrue
if the file type is supported, otherwise false
public static int[] getMidiFileTypes(Sequence sequence)
sequence
- the sequence for which MIDI file type support is queriedNullPointerException
- if sequence
is null
public static boolean isFileTypeSupported(int fileType, Sequence sequence)
fileType
- the file type for which write capabilities are queriedsequence
- the sequence for which file writing support is queriedtrue
if the file type is supported for this sequence, otherwise false
NullPointerException
- if sequence
is null
public static int write(Sequence in, int fileType, OutputStream out) throws IOException
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 writtenIOException
- if an I/O exception occursIllegalArgumentException
- if the file format is not supported by the systemNullPointerException
- if in
or out
are null
public static int write(Sequence in, int type, File out) throws IOException
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 writtenIOException
- if an I/O exception occursIllegalArgumentException
- if the file type is not supported by the systemNullPointerException
- if in
or out
are null
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/sound/midi/MidiSystem.html