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 or 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, explicit closing is done by calling 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 and MidiSystem#getTransmitter. The MidiDevice used by MidiSystem.getReceiver and MidiSystem.getTransmitter is implementation-dependent 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). 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 device 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:

After an explicit open (either before or after implicit opens), the device will not be closed by implicit closing. The only way to close an explicitly opened device is an explicit close.
An explicit close always closes the device, even if it also has been opened implicitly. A subsequent implicit close has no further effect.

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 Info object to provide manufacturer information and so on.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	MidiDevice.Info A `MidiDevice.Info` object contains assorted data about a `MidiDevice`, including its name, the company who created it, and descriptive text.

Method Summary

Modifier and Type	Method and Description
public void	close() Redeclares java.lang.AutoCloseable.close. Closes the device, indicating that the device should now release any system resources it is using.
public MidiDevice.Info	Returns: device info getDeviceInfo() Obtains information about the device, including its Java class and `Strings` containing its name, vendor, and description.
public int	Returns: maximum number of MIDI IN connections, or -1 if an unlimited number of connections is available getMaxReceivers() Obtains the maximum number of MIDI IN connections available on this MIDI device for receiving MIDI data.
public int	Returns: maximum number of MIDI OUT connections, or -1 if an unlimited number of connections is available getMaxTransmitters() Obtains the maximum number of MIDI OUT connections available on this MIDI device for transmitting MIDI data.
public long	Returns: the current time-stamp of the device in microseconds, or -1 if time-stamping is not supported by the device getMicrosecondPosition() Obtains the current time-stamp of the device, in microseconds.
public Receiver	Returns: a receiver for the device getReceiver() Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data.
public List<Receiver>	Returns: an unmodifiable list of the open receivers getReceivers() Returns all currently active, non-closed receivers connected with this `MidiDevice`.
public Transmitter	Returns: a MIDI OUT transmitter for the device getTransmitter() Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data.
public List<Transmitter>	Returns: an unmodifiable list of the open transmitters getTransmitters() Returns all currently active, non-closed transmitters connected with this `MidiDevice`.
public boolean	Returns: `true` if the device is open, otherwise `false` isOpen() Reports whether the device is open.
public void	open() Opens the device, indicating that it should now acquire any system resources it requires and become operational.

Method Detail

close back to summary

close	back to summary
public void close() Redeclares java.lang.AutoCloseable.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`. Annotations @Override See Also `open`, `isOpen`

public void close()

Redeclares java.lang.AutoCloseable.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.

Annotations

@Override

See Also

open, isOpen

getDeviceInfo back to summary

getDeviceInfo	back to summary
public MidiDevice.Info getDeviceInfo() Obtains information about the device, including its Java class and `Strings` containing its name, vendor, and description. Returns:MidiDevice.Info device info

public MidiDevice.Info getDeviceInfo()

Obtains information about the device, including its Java class and Strings containing its name, vendor, and description.

Returns:MidiDevice.Info: device info

getMaxReceivers	back to summary
public int getMaxReceivers() Obtains the maximum number of MIDI IN connections available on this MIDI device for receiving MIDI data. Returns:int maximum number of MIDI IN connections, or -1 if an unlimited number of connections is available

getMaxReceivers

back to summary

public int getMaxReceivers()

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

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

getMaxTransmitters	back to summary
public int getMaxTransmitters() Obtains the maximum number of MIDI OUT connections available on this MIDI device for transmitting MIDI data. Returns:int maximum number of MIDI OUT connections, or -1 if an unlimited number of connections is available

getMaxTransmitters

back to summary

public int getMaxTransmitters()

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

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

getMicrosecondPosition	back to summary
public 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:long the current time-stamp of the device in microseconds, or -1 if time-stamping is not supported by the device

getMicrosecondPosition

back to summary

public 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:long: the current time-stamp of the device in microseconds, or -1 if time-stamping is not supported by the device

getReceiver back to summary

getReceiver	back to summary
public Receiver getReceiver() throws 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. Usually the returned receiver implements the `MidiDeviceReceiver` interface. 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`. Also, closing the `Receiver` does not close the device. It has to be closed explicitly by calling `close`. Returns:Receiver a receiver for the device Exceptions MidiUnavailableException: thrown if a receiver is not available due to resource restrictions See Also `Receiver#close()`

public Receiver getReceiver() throws 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.

Usually the returned receiver implements the MidiDeviceReceiver interface.

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. Also, closing the Receiver does not close the device. It has to be closed explicitly by calling close.

Returns:Receiver

a receiver for the device

Exceptions

MidiUnavailableException:: thrown if a receiver is not available due to resource restrictions

See Also

Receiver#close()

getReceivers back to summary

getReceivers	back to summary
public List<Receiver> getReceivers() Returns all currently active, non-closed receivers connected with this `MidiDevice`. A receiver can be removed from the device by closing it. Usually the returned receivers implement the `MidiDeviceReceiver` interface. Returns:List<Receiver> an unmodifiable list of the open receivers Since 1.5

public List<Receiver> getReceivers()

Returns all currently active, non-closed receivers connected with this MidiDevice. A receiver can be removed from the device by closing it.

Usually the returned receivers implement the MidiDeviceReceiver interface.

Returns:List<Receiver>: an unmodifiable list of the open receivers
Since: 1.5

getTransmitter back to summary

getTransmitter	back to summary
public Transmitter getTransmitter() throws 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. Usually the returned transmitter implements the `MidiDeviceTransmitter` interface. 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`. Also, closing the `Transmitter` does not close the device. It has to be closed explicitly by calling `close`. Returns:Transmitter a MIDI OUT transmitter for the device Exceptions MidiUnavailableException: thrown if a transmitter is not available due to resource restrictions See Also `Transmitter#close()`

public Transmitter getTransmitter() throws 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.

Usually the returned transmitter implements the MidiDeviceTransmitter interface.

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. Also, closing the Transmitter does not close the device. It has to be closed explicitly by calling close.

Returns:Transmitter

a MIDI OUT transmitter for the device

Exceptions

MidiUnavailableException:: thrown if a transmitter is not available due to resource restrictions

See Also

Transmitter#close()

getTransmitters back to summary

getTransmitters	back to summary
public List<Transmitter> getTransmitters() Returns all currently active, non-closed transmitters connected with this `MidiDevice`. A transmitter can be removed from the device by closing it. Usually the returned transmitters implement the `MidiDeviceTransmitter` interface. Returns:List<Transmitter> an unmodifiable list of the open transmitters Since 1.5

public List<Transmitter> getTransmitters()

Returns all currently active, non-closed transmitters connected with this MidiDevice. A transmitter can be removed from the device by closing it.

Usually the returned transmitters implement the MidiDeviceTransmitter interface.

Returns:List<Transmitter>: an unmodifiable list of the open transmitters
Since: 1.5

isOpen back to summary

isOpen	back to summary
public boolean isOpen() Reports whether the device is open. Returns:boolean `true` if the device is open, otherwise `false` See Also `open`, `close`

public boolean isOpen()

Reports whether the device is open.

Returns:boolean: true if the device is open, otherwise false
See Also: open, close

open back to summary

open	back to summary
public void open() throws 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`. 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`. Exceptions MidiUnavailableException: thrown if the device cannot be opened due to resource restrictions SecurityException: thrown if the device cannot be opened due to security restrictions See Also `close`, `isOpen`

public void open() throws 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. 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.

Exceptions

MidiUnavailableException:: thrown if the device cannot be opened due to resource restrictions
SecurityException:: thrown if the device cannot be opened due to security restrictions

See Also

close, isOpen

javax.sound.midi back to summary

public Class MidiDevice.Info

Class Inheritance

extends Object

java.lang.Object
javax.sound.midi.MidiDevice.Info

Known Direct Subclasses

com.sun.media.sound.AbstractMidiDeviceProvider.Info, com.sun.media.sound.RealTimeSequencer.RealTimeSequencerInfo, com.sun.media.sound.SoftSynthesizer.Info

A MidiDevice.Info object contains assorted data about a MidiDevice, including its name, the company who created it, and descriptive text.

See Also: MidiDevice#getDeviceInfo

Field Summary

Modifier and Type	Field and Description
private final String	description A description of the device.
private final String	name The device's name.
private final String	vendor The name of the company who provides the device.
private final String	version Device version.

Constructor Summary

Access	Constructor and Description
protected	Info(String the name of the device name, String the name of the company who provides the device vendor, String a description of the device description, String version information for the device version) Constructs a device info object.

Method Summary

Modifier and Type	Method and Description
public final boolean	Returns: `true` if the specified object is equal to this info object; `false` otherwise equals(Object the reference object with which to compare obj) Overrides java.lang.Object.equals. Indicates whether the specified object is equal to this info object, returning `true` if the objects are the same.
public final String	Returns: a description of the device getDescription() Obtains the description of the device.
public final String	Returns: a string containing the device's name getName() Obtains the name of the device.
public final String	Returns: device the vendor's name getVendor() Obtains the name of the company who supplies the device.
public final String	Returns: textual version information for the device getVersion() Obtains the version of the device.
public final int	Returns: a hash code value for this info object hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this info object.
public final String	Returns: a string representation of the info object toString() Overrides java.lang.Object.toString. Returns a string representation of the info object.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

Field Detail

description	back to summary
private final String description A description of the device.

name	back to summary
private final String name The device's name.

vendor	back to summary
private final String vendor The name of the company who provides the device.

version	back to summary
private final String version Device version.

Constructor Detail

Info	back to summary
protected Info(String name, String vendor, String description, String version) Constructs a device info object. Parameters name:String the name of the device vendor:String the name of the company who provides the device description:String a description of the device version:String version information for the device

Info

back to summary

protected Info(String name, String vendor, String description, String version)

Constructs a device info object.

Parameters

name:String: the name of the device
vendor:String: the name of the company who provides the device
description:String: a description of the device
version:String: version information for the device

Method Detail

equals back to summary

equals	back to summary
public final boolean equals(Object obj) Overrides java.lang.Object.equals. Indicates whether the specified object is equal to this info object, returning `true` if the objects are the same. Parameters obj:Object the reference object with which to compare Returns:boolean `true` if the specified object is equal to this info object; `false` otherwise Annotations @Override

public final boolean equals(Object obj)

Overrides java.lang.Object.equals.

Indicates whether the specified object is equal to this info object, returning true if the objects are the same.

Parameters

obj:Object: the reference object with which to compare

Returns:boolean

true if the specified object is equal to this info object; false otherwise

Annotations

@Override

getDescription	back to summary
public final String getDescription() Obtains the description of the device. Returns:String a description of the device

getDescription

back to summary

public final String getDescription()

Obtains the description of the device.

Returns:String: a description of the device

getName	back to summary
public final String getName() Obtains the name of the device. Returns:String a string containing the device's name

getName

back to summary

public final String getName()

Obtains the name of the device.

Returns:String: a string containing the device's name

getVendor	back to summary
public final String getVendor() Obtains the name of the company who supplies the device. Returns:String device the vendor's name

getVendor

back to summary

public final String getVendor()

Obtains the name of the company who supplies the device.

Returns:String: device the vendor's name

getVersion	back to summary
public final String getVersion() Obtains the version of the device. Returns:String textual version information for the device

getVersion

back to summary

public final String getVersion()

Obtains the version of the device.

Returns:String: textual version information for the device

hashCode	back to summary
public final int hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this info object. Returns:int a hash code value for this info object Annotations @Override

hashCode

back to summary

public final int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this info object.

Returns:int

a hash code value for this info object

Annotations

@Override

toString	back to summary
public final String toString() Overrides java.lang.Object.toString. Returns a string representation of the info object. Returns:String a string representation of the info object Annotations @Override

toString

back to summary

public final String toString()

Overrides java.lang.Object.toString.

Returns a string representation of the info object.

Returns:String

a string representation of the info object

Annotations