javax.sound.midi
Interface MidiDevice

All Known Subinterfaces:
Sequencer sample code for javax.sound.midi.Sequencer definition code for javax.sound.midi.Sequencer , Synthesizer sample code for javax.sound.midi.Synthesizer definition code for javax.sound.midi.Synthesizer

public interface MidiDevice

MidiDevice is the base interface for all MIDI devices. Common devices include synthesizers, sequencers, MIDI input ports, and MIDI output ports.

A MidiDevice can be a transmitter or a receiver of MIDI events, or both. Therefore, it can provide Transmitter sample code for javax.sound.midi.Transmitter definition code for javax.sound.midi.Transmitter or Receiver sample code for javax.sound.midi.Receiver definition code for javax.sound.midi.Receiver instances (or both). Typically, MIDI IN ports provide transmitters, MIDI OUT ports and synthesizers provide receivers. A Sequencer typically provides transmitters for playback and receivers for recording.

A MidiDevice can be opened and closed explicitly as well as implicitly. Explicit opening is accomplished by calling open() sample code for javax.sound.midi.MidiDevice.open() definition code for javax.sound.midi.MidiDevice.open() , explicit closing is done by calling close() sample code for javax.sound.midi.MidiDevice.close() definition code for javax.sound.midi.MidiDevice.close() on the MidiDevice instance. If an application opens a MidiDevice explicitly, it has to close it explicitly to free system resources and enable the application to exit cleanly. Implicit opening is done by calling MidiSystem.getReceiver sample code for javax.sound.midi.MidiSystem.getReceiver() definition code for javax.sound.midi.MidiSystem.getReceiver() and MidiSystem.getTransmitter sample code for javax.sound.midi.MidiSystem.getTransmitter() definition code for javax.sound.midi.MidiSystem.getTransmitter() . The MidiDevice used by MidiSystem.getReceiver and MidiSystem.getTransmitter is implementation-dependant unless the properties javax.sound.midi.Receiver and javax.sound.midi.Transmitter are used (see the description of properties to select default providers in MidiSystem sample code for javax.sound.midi.MidiSystem definition code for javax.sound.midi.MidiSystem ). A MidiDevice that was opened implicitly, is closed implicitly by closing the Receiver or Transmitter that resulted in opening it. If more than one implicitly opening Receiver or Transmitter were obtained by the application, the decive is closed after the last Receiver or Transmitter has been closed. On the other hand, calling getReceiver or getTransmitter on the device instance directly does not open the device implicitly. Closing these Transmitters and Receivers does not close the device implicitly. To use a device with Receivers or Transmitters obtained this way, the device has to be opened and closed explicitly.

If implicit and explicit opening and closing are mixed on the same MidiDevice instance, the following rules apply:

To detect if a MidiDevice represents a hardware MIDI port, the following programming technique can be used:
 MidiDevice device = ...;
 if ( ! (device instanceof Sequencer) && ! (device instanceof Synthesizer)) {
   // we're now sure that device represents a MIDI port
   // ...
 }
 

A MidiDevice includes a MidiDevice.Info sample code for javax.sound.midi.MidiDevice.Info definition code for javax.sound.midi.MidiDevice.Info object to provide manufacturer information and so on.

See Also:
Synthesizer sample code for javax.sound.midi.Synthesizer definition code for javax.sound.midi.Synthesizer , Sequencer sample code for javax.sound.midi.Sequencer definition code for javax.sound.midi.Sequencer , Receiver sample code for javax.sound.midi.Receiver definition code for javax.sound.midi.Receiver , Transmitter sample code for javax.sound.midi.Transmitter definition code for javax.sound.midi.Transmitter

Nested Class Summary
static class MidiDevice.Info sample code for javax.sound.midi.MidiDevice.Info definition code for javax.sound.midi.MidiDevice.Info
          A MidiDevice.Info object contains assorted data about a MidiDevice sample code for javax.sound.midi.MidiDevice definition code for javax.sound.midi.MidiDevice , including its name, the company who created it, and descriptive text.
 
Method Summary
 void close sample code for javax.sound.midi.MidiDevice.close() definition code for javax.sound.midi.MidiDevice.close() ()
          Closes the device, indicating that the device should now release any system resources it is using.
 MidiDevice.Info sample code for javax.sound.midi.MidiDevice.Info definition code for javax.sound.midi.MidiDevice.Info getDeviceInfo sample code for javax.sound.midi.MidiDevice.getDeviceInfo() definition code for javax.sound.midi.MidiDevice.getDeviceInfo() ()
          Obtains information about the device, including its Java class and Strings containing its name, vendor, and description.
 int getMaxReceivers sample code for javax.sound.midi.MidiDevice.getMaxReceivers() definition code for javax.sound.midi.MidiDevice.getMaxReceivers() ()
          Obtains the maximum number of MIDI IN connections available on this MIDI device for receiving MIDI data.
 int getMaxTransmitters sample code for javax.sound.midi.MidiDevice.getMaxTransmitters() definition code for javax.sound.midi.MidiDevice.getMaxTransmitters() ()
          Obtains the maximum number of MIDI OUT connections available on this MIDI device for transmitting MIDI data.
 long getMicrosecondPosition sample code for javax.sound.midi.MidiDevice.getMicrosecondPosition() definition code for javax.sound.midi.MidiDevice.getMicrosecondPosition() ()
          Obtains the current time-stamp of the device, in microseconds.
 Receiver sample code for javax.sound.midi.Receiver definition code for javax.sound.midi.Receiver getReceiver sample code for javax.sound.midi.MidiDevice.getReceiver() definition code for javax.sound.midi.MidiDevice.getReceiver() ()
          Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data.
 List sample code for java.util.List definition code for java.util.List <Receiver sample code for javax.sound.midi.Receiver definition code for javax.sound.midi.Receiver > getReceivers sample code for javax.sound.midi.MidiDevice.getReceivers() definition code for javax.sound.midi.MidiDevice.getReceivers() ()
          Returns all currently active, non-closed receivers connected with this MidiDevice.
 Transmitter sample code for javax.sound.midi.Transmitter definition code for javax.sound.midi.Transmitter getTransmitter sample code for javax.sound.midi.MidiDevice.getTransmitter() definition code for javax.sound.midi.MidiDevice.getTransmitter() ()
          Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data The returned transmitter must be closed when the application has finished using it.
 List sample code for java.util.List definition code for java.util.List <Transmitter sample code for javax.sound.midi.Transmitter definition code for javax.sound.midi.Transmitter > getTransmitters sample code for javax.sound.midi.MidiDevice.getTransmitters() definition code for javax.sound.midi.MidiDevice.getTransmitters() ()
          Returns all currently active, non-closed transmitters connected with this MidiDevice.
 boolean isOpen sample code for javax.sound.midi.MidiDevice.isOpen() definition code for javax.sound.midi.MidiDevice.isOpen() ()
          Reports whether the device is open.
 void open sample code for javax.sound.midi.MidiDevice.open() definition code for javax.sound.midi.MidiDevice.open() ()
          Opens the device, indicating that it should now acquire any system resources it requires and become operational.
 

Method Detail

getDeviceInfo sample code for javax.sound.midi.MidiDevice.getDeviceInfo() definition code for javax.sound.midi.MidiDevice.getDeviceInfo()

MidiDevice.Info sample code for javax.sound.midi.MidiDevice.Info definition code for javax.sound.midi.MidiDevice.Info  getDeviceInfo()
Obtains information about the device, including its Java class and Strings containing its name, vendor, and description.

Returns:
device info

open sample code for javax.sound.midi.MidiDevice.open() definition code for javax.sound.midi.MidiDevice.open()

void open()
          throws MidiUnavailableException sample code for javax.sound.midi.MidiUnavailableException definition code for javax.sound.midi.MidiUnavailableException 
Opens the device, indicating that it should now acquire any system resources it requires and become operational.

An application opening a device explicitly with this call has to close the device by calling close() sample code for javax.sound.midi.MidiDevice.close() definition code for javax.sound.midi.MidiDevice.close() . This is necessary to release system resources and allow applications to exit cleanly.

Note that some devices, once closed, cannot be reopened. Attempts to reopen such a device will always result in a MidiUnavailableException.

Throws:
MidiUnavailableException sample code for javax.sound.midi.MidiUnavailableException definition code for javax.sound.midi.MidiUnavailableException - thrown if the device cannot be opened due to resource restrictions.
SecurityException sample code for java.lang.SecurityException definition code for java.lang.SecurityException - thrown if the device cannot be opened due to security restrictions.
See Also:
close() sample code for javax.sound.midi.MidiDevice.close() definition code for javax.sound.midi.MidiDevice.close() , isOpen() sample code for javax.sound.midi.MidiDevice.isOpen() definition code for javax.sound.midi.MidiDevice.isOpen()

close sample code for javax.sound.midi.MidiDevice.close() definition code for javax.sound.midi.MidiDevice.close()

void close()
Closes the device, indicating that the device should now release any system resources it is using.

All Receiver and Transmitter instances open from this device are closed. This includes instances retrieved via MidiSystem.

See Also:
open() sample code for javax.sound.midi.MidiDevice.open() definition code for javax.sound.midi.MidiDevice.open() , isOpen() sample code for javax.sound.midi.MidiDevice.isOpen() definition code for javax.sound.midi.MidiDevice.isOpen()

isOpen sample code for javax.sound.midi.MidiDevice.isOpen() definition code for javax.sound.midi.MidiDevice.isOpen()

boolean isOpen()
Reports whether the device is open.

Returns:
true if the device is open, otherwise false
See Also:
open() sample code for javax.sound.midi.MidiDevice.open() definition code for javax.sound.midi.MidiDevice.open() , close() sample code for javax.sound.midi.MidiDevice.close() definition code for javax.sound.midi.MidiDevice.close()

getMicrosecondPosition sample code for javax.sound.midi.MidiDevice.getMicrosecondPosition() definition code for javax.sound.midi.MidiDevice.getMicrosecondPosition()

long getMicrosecondPosition()
Obtains the current time-stamp of the device, in microseconds. If a device supports time-stamps, it should start counting at 0 when the device is opened and continue incrementing its time-stamp in microseconds until the device is closed. If it does not support time-stamps, it should always return -1.

Returns:
the current time-stamp of the device in microseconds, or -1 if time-stamping is not supported by the device.

getMaxReceivers sample code for javax.sound.midi.MidiDevice.getMaxReceivers() definition code for javax.sound.midi.MidiDevice.getMaxReceivers()

int getMaxReceivers()
Obtains the maximum number of MIDI IN connections available on this MIDI device for receiving MIDI data.

Returns:
maximum number of MIDI IN connections, or -1 if an unlimited number of connections is available.

getMaxTransmitters sample code for javax.sound.midi.MidiDevice.getMaxTransmitters() definition code for javax.sound.midi.MidiDevice.getMaxTransmitters()

int getMaxTransmitters()
Obtains the maximum number of MIDI OUT connections available on this MIDI device for transmitting MIDI data.

Returns:
maximum number of MIDI OUT connections, or -1 if an unlimited number of connections is available.

getReceiver sample code for javax.sound.midi.MidiDevice.getReceiver() definition code for javax.sound.midi.MidiDevice.getReceiver()

Receiver sample code for javax.sound.midi.Receiver definition code for javax.sound.midi.Receiver  getReceiver()
                     throws MidiUnavailableException sample code for javax.sound.midi.MidiUnavailableException definition code for javax.sound.midi.MidiUnavailableException 
Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data. The returned receiver must be closed when the application has finished using it.

Obtaining a Receiver with this method does not open the device. To be able to use the device, it has to be opened explicitly by calling open() sample code for javax.sound.midi.MidiDevice.open() definition code for javax.sound.midi.MidiDevice.open() . Also, closing the Receiver does not close the device. It has to be closed explicitly by calling close() sample code for javax.sound.midi.MidiDevice.close() definition code for javax.sound.midi.MidiDevice.close() .

Returns:
a receiver for the device.
Throws:
MidiUnavailableException sample code for javax.sound.midi.MidiUnavailableException definition code for javax.sound.midi.MidiUnavailableException - thrown if a receiver is not available due to resource restrictions
See Also:
Receiver.close() sample code for javax.sound.midi.Receiver.close() definition code for javax.sound.midi.Receiver.close()

getReceivers sample code for javax.sound.midi.MidiDevice.getReceivers() definition code for javax.sound.midi.MidiDevice.getReceivers()

List sample code for java.util.List definition code for java.util.List <Receiver sample code for javax.sound.midi.Receiver definition code for javax.sound.midi.Receiver > getReceivers()
Returns all currently active, non-closed receivers connected with this MidiDevice. A receiver can be removed from the device by closing it.

Returns:
an unmodifiable list of the open receivers
Since:
1.5

getTransmitter sample code for javax.sound.midi.MidiDevice.getTransmitter() definition code for javax.sound.midi.MidiDevice.getTransmitter()

Transmitter sample code for javax.sound.midi.Transmitter definition code for javax.sound.midi.Transmitter  getTransmitter()
                           throws MidiUnavailableException sample code for javax.sound.midi.MidiUnavailableException definition code for javax.sound.midi.MidiUnavailableException 
Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data The returned transmitter must be closed when the application has finished using it.

Obtaining a Transmitter with this method does not open the device. To be able to use the device, it has to be opened explicitly by calling open() sample code for javax.sound.midi.MidiDevice.open() definition code for javax.sound.midi.MidiDevice.open() . Also, closing the Transmitter does not close the device. It has to be closed explicitly by calling close() sample code for javax.sound.midi.MidiDevice.close() definition code for javax.sound.midi.MidiDevice.close() .

Returns:
a MIDI OUT transmitter for the device.
Throws:
MidiUnavailableException sample code for javax.sound.midi.MidiUnavailableException definition code for javax.sound.midi.MidiUnavailableException - thrown if a transmitter is not available due to resource restrictions
See Also:
Transmitter.close() sample code for javax.sound.midi.Transmitter.close() definition code for javax.sound.midi.Transmitter.close()

getTransmitters sample code for javax.sound.midi.MidiDevice.getTransmitters() definition code for javax.sound.midi.MidiDevice.getTransmitters()

List sample code for java.util.List definition code for java.util.List <Transmitter sample code for javax.sound.midi.Transmitter definition code for javax.sound.midi.Transmitter > getTransmitters()
Returns all currently active, non-closed transmitters connected with this MidiDevice. A transmitter can be removed from the device by closing it.

Returns:
an unmodifiable list of the open transmitters
Since:
1.5