uk.co.xfactorylibrarians.coremidi4j

Class CoreMidiSource

java.lang.Object

uk.co.xfactorylibrarians.coremidi4j.CoreMidiSource

All Implemented Interfaces:

AutoCloseable, MidiDevice

public class CoreMidiSource
extends Object
implements MidiDevice

CoreMidiDevice - a MidiDevice implementation for Apple CoreMIDI

Nested Class Summary

Nested classes/interfaces inherited from interface javax.sound.midi.MidiDevice

MidiDevice.Info

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	currentDataIsSingleByte
private int	currentMessage
private byte	firstDataByte
private CoreMidiDeviceInfo	info
private AtomicReference<CoreMidiInputPort>	input
private AtomicBoolean	isOpen
private long	startTime
private Vector<byte[]>	sysexMessageData
private int	sysexMessageLength
private Set<CoreMidiTransmitter>	transmitters
private boolean	wasFirstByteReceived

Constructor Summary

Constructors

Constructor and Description
CoreMidiSource(CoreMidiDeviceInfo info) Default constructor.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the Core MIDI Device, which also closes all its transmitters
private SysexMessage	constructSysexMessage() Creates a SYSEX message from the received (potentially partial) messages.
(package private) void	deviceDisappeared() Forcibly close because the underlying CoreMIDI device has disappeared.
private int	expectedDataLength(byte status) Determine how many data bytes are expected for a given MIDI message other than a SYSEX message, which varies.
MidiDevice.Info	getDeviceInfo() Gets the MIDI Info object
private String	getHexString(byte[] aByteArray) Formats the provided data into a HEX string, which is useful for debugging
int	getMaxReceivers() Gets the maximum number of receivers that can be attached to this device.
int	getMaxTransmitters() Gets the maximum number of transmitters that can be attached to this device.
long	getMicrosecondPosition() Obtains the time in microseconds that has elapsed since this MIDI Device was opened.
private long	getMicroSecondTime() Obtains the current system time in microseconds.
Receiver	getReceiver() Creates and returns a MIDI Receiver for use with this Device
List<Receiver>	getReceivers() Gets a list of receivers connected to the device
Transmitter	getTransmitter() Gets a transmitter for this device (which is also added to the internal list)
List<Transmitter>	getTransmitters() Gets the list of transmitters registered with this MIDI device
boolean	isOpen() Checks to see if the MIDI Device is open
private boolean	isRealTimeMessage(byte status) Checks whether a status byte represents a real-time message, which can occur even in the middle of another multi-byte message.
private boolean	isRunningStatusMessage(int status) Checks whether a status byte represents a running-status message, which means that multiple messages can be sent without re-sending the status byte, for example to support multiple note-on messages in a row by simply sending a stream of data byte pairs after the note-on status byte.
void	messageCallback(long coreTimestamp, int packetlength, byte[] data) The message callback for receiving midi data from the JNI code
void	open() Opens the Core MIDI Device
private int	processSysexData(int packetLength, byte[] sourceData, int startOffset, long timestamp) Called when a SYSEX message is being received, either because an F0 byte has been seen at the start of a message, which starts the process of gathering a SYSEX potentially across multiple packets, or because a new packet has been received while we are still in the process of gathering bytes of a SYSEX which was started in a previous message.
private void	transmitMessage(MidiMessage message, long timestamp) Sends a MIDI message to all of the registered transmitters
(package private) void	transmitterClosed(CoreMidiTransmitter transmitter) Reacts to the closing of a transmitter by removing it from the set of active transmitters
(package private) void	updateDeviceInfo(CoreMidiDeviceInfo info) Changes the MIDI Info object; can only be done by this package as a result of a MIDI environment change event.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

info

private CoreMidiDeviceInfo info

isOpen

private final AtomicBoolean isOpen

input

private final AtomicReference<CoreMidiInputPort> input

transmitters

private final Set<CoreMidiTransmitter> transmitters

currentMessage

private int currentMessage

currentDataIsSingleByte

private boolean currentDataIsSingleByte

firstDataByte

private byte firstDataByte

wasFirstByteReceived

private boolean wasFirstByteReceived

sysexMessageData

private Vector<byte[]> sysexMessageData

sysexMessageLength

private int sysexMessageLength

startTime

private long startTime

Constructor Detail

CoreMidiSource

CoreMidiSource(CoreMidiDeviceInfo info)

Default constructor.

Parameters:

info - a CoreMidiDeviceInfo object providing details of the MIDI interface

Method Detail

getDeviceInfo

public MidiDevice.Info getDeviceInfo()

Gets the MIDI Info object

Specified by:

getDeviceInfo in interface MidiDevice

Returns:

the MIDI Info object, which provides details about the interface

updateDeviceInfo

void updateDeviceInfo(CoreMidiDeviceInfo info)

Changes the MIDI Info object; can only be done by this package as a result of a MIDI environment change event.

Parameters:

info - CoreMidiDeviceInfo object

open

public void open()
          throws MidiUnavailableException

Opens the Core MIDI Device

Specified by:

open in interface MidiDevice

Throws:

MidiUnavailableException - if the MIDI system cannot be used

close

public void close()

Closes the Core MIDI Device, which also closes all its transmitters

Specified by:

close in interface AutoCloseable

Specified by:

close in interface MidiDevice

deviceDisappeared

void deviceDisappeared()

Forcibly close because the underlying CoreMIDI device has disappeared. Behaves like close() without attempting to detach from the now-nonexistent underlying device.

isOpen

public boolean isOpen()

Checks to see if the MIDI Device is open

Specified by:

isOpen in interface MidiDevice

Returns:

true if the device is open, otherwise false;

See Also:

MidiDevice.isOpen()

getMicrosecondPosition

public long getMicrosecondPosition()

Obtains the time in microseconds that has elapsed since this MIDI Device was opened.

Specified by:

getMicrosecondPosition in interface MidiDevice

Returns:

the time in microseconds that has elapsed since this MIDI Device was opened.

See Also:

MidiDevice.getMicrosecondPosition()

getMaxReceivers

public int getMaxReceivers()

Gets the maximum number of receivers that can be attached to this device.

Specified by:

getMaxReceivers in interface MidiDevice

Returns:

the maximum number of receivers that can be attached to this device. This is always 0 as a CoreMidiSource has no receivers

See Also:

MidiDevice.getMaxReceivers()

getMaxTransmitters

public int getMaxTransmitters()

Gets the maximum number of transmitters that can be attached to this device.

Specified by:

getMaxTransmitters in interface MidiDevice

Returns:

the maximum number of transmitters that can be attached to this device. -1 is returned to indicate that the number is unlimited

See Also:

MidiDevice.getMaxTransmitters()

getReceiver

public Receiver getReceiver()
                     throws MidiUnavailableException

Creates and returns a MIDI Receiver for use with this Device

Specified by:

getReceiver in interface MidiDevice

Returns:

the created receiver

Throws:

MidiUnavailableException

See Also:

MidiDevice.getReceiver()

getReceivers

public List<Receiver> getReceivers()

Gets a list of receivers connected to the device

Specified by:

getReceivers in interface MidiDevice

Returns:

an empty list - we do not maintain a list of receivers

See Also:

MidiDevice.getReceivers()

getTransmitter

public Transmitter getTransmitter()
                           throws MidiUnavailableException

Gets a transmitter for this device (which is also added to the internal list)

Specified by:

getTransmitter in interface MidiDevice

Returns:

a transmitter for this device

Throws:

MidiUnavailableException - Thrown if MIDI services unavailable.

See Also:

MidiDevice.getTransmitter()

transmitterClosed

void transmitterClosed(CoreMidiTransmitter transmitter)

Reacts to the closing of a transmitter by removing it from the set of active transmitters

Parameters:

transmitter - the transmitter which is reporting itself as having closed

getTransmitters

public List<Transmitter> getTransmitters()

Gets the list of transmitters registered with this MIDI device

Specified by:

getTransmitters in interface MidiDevice

Returns:

The list of transmitters created from this MIDI device that are still open

See Also:

MidiDevice.getTransmitters()

isRealTimeMessage

private boolean isRealTimeMessage(byte status)

Checks whether a status byte represents a real-time message, which can occur even in the middle of another multi-byte message.

Parameters:

status - the status byte which has just been received.

Returns:

true if the status byte represents a standalone real-time message which should be passed on without interrupting any other message being gathered.

isRunningStatusMessage

private boolean isRunningStatusMessage(int status)

Checks whether a status byte represents a running-status message, which means that multiple messages can be sent without re-sending the status byte, for example to support multiple note-on messages in a row by simply sending a stream of data byte pairs after the note-on status byte.

Parameters:

status - the status byte which is being processed.

Returns:

true if we should stay in this status after receiving our full complement of data bytes.

expectedDataLength

private int expectedDataLength(byte status)
                        throws InvalidMidiDataException

Determine how many data bytes are expected for a given MIDI message other than a SYSEX message, which varies.

Parameters:

status - the status byte introducing the MIDI message.

Returns:

the number of data bytes which must be received for the message to be complete.

Throws:

InvalidMidiDataException - if the status byte is not valid.

messageCallback

public void messageCallback(long coreTimestamp,
                            int packetlength,
                            byte[] data)
                     throws InvalidMidiDataException

The message callback for receiving midi data from the JNI code

Parameters:

coreTimestamp - The time in microseconds since boot at which the messages should take effect

packetlength - The length of the packet of messages

data - The data array that holds the messages

Throws:

InvalidMidiDataException - if the message contained values that could not be interpreted as valid MIDI

constructSysexMessage

private SysexMessage constructSysexMessage()
                                    throws InvalidMidiDataException

Creates a SYSEX message from the received (potentially partial) messages. This function is called when F7 was detected in the most recent message gathered, indicating the end of the SYSEX.

Returns:

The constructed SYSEX message

Throws:

InvalidMidiDataException - if the data is not properly formed

processSysexData

private int processSysexData(int packetLength,
                             byte[] sourceData,
                             int startOffset,
                             long timestamp)
                      throws InvalidMidiDataException

Called when a SYSEX message is being received, either because an F0 byte has been seen at the start of a message, which starts the process of gathering a SYSEX potentially across multiple packets, or because a new packet has been received while we are still in the process of gathering bytes of a SYSEX which was started in a previous message. The partial data is added to the sysexMessageData Vector. If we see another status byte, except for one which represents a real-time message, we know the SYSEX is finished, and so we can assemble and transmit it from any fragments which have been gathered. If we see a real-time message or the end of the packet, we return the data we have gathered, and let the main loop decide what to do next.

Parameters:

packetLength - The length of the data packet

sourceData - The source data received from Core MIDI

startOffset - The position within the packet where the current message began

timestamp - The message timestamp

Returns:

The number of bytes consumed from the packet by the SYSEX message

Throws:

InvalidMidiDataException - if the data is not properly formed

transmitMessage

private void transmitMessage(MidiMessage message,
                             long timestamp)

Sends a MIDI message to all of the registered transmitters

Parameters:

message - the message to send

timestamp - the time stamp

getHexString

private String getHexString(byte[] aByteArray)

Formats the provided data into a HEX string, which is useful for debugging

Parameters:

aByteArray - The data to format

Returns:

The formatted HEX string

getMicroSecondTime

private long getMicroSecondTime()

Obtains the current system time in microseconds.

Returns:

The current system time in microseconds.