Interface Sequencer

public interface Sequencer
extends MidiDevice

A hardware or software device that plays back a MIDI sequence is known as a sequencer. A MIDI sequence contains lists of time-stamped MIDI data, such as might be read from a standard MIDI file. Most sequencers also provide functions for creating and editing sequences.

The Sequencer interface includes methods for the following basic MIDI sequencer operations:

• obtaining a sequence from MIDI file data
• starting and stopping playback
• moving to an arbitrary position in the sequence
• changing the tempo (speed) of playback
• synchronizing playback to an internal clock or to received MIDI messages
• controlling the timing of another device

In addition, the following operations are supported, either directly, or indirectly through objects that the Sequencer has access to:

• editing the data by adding or deleting individual MIDI events or entire tracks
• muting or soloing individual tracks in the sequence
• notifying listener objects about any meta-events or control-change events encountered while playing back the sequence.

Fields

LOOP_CONTINUOUSLY

static final int LOOP_CONTINUOUSLY

A value indicating that looping should continue indefinitely rather than complete after a specific number of loops.

Since:

1.5

See Also:

setLoopCount(int), Constant Field Values

Methods

setSequence

void setSequence(Sequence sequence)
          throws InvalidMidiDataException

Parameters:

sequence - the sequence to be loaded.

Throws:

InvalidMidiDataException - if the sequence contains invalid MIDI data, or is not supported.

setSequence

void setSequence(InputStream stream)
          throws IOException,
                 InvalidMidiDataException

Parameters:

stream - stream containing MIDI file data.

Throws:

IOException - if an I/O exception occurs during reading of the stream.

InvalidMidiDataException - if invalid data is encountered in the stream, or the stream is not supported.

getSequence

Sequence getSequence()

Returns:

the current sequence, or null if no sequence is currently set.

start

void start()

Throws:

IllegalStateException - if the Sequencer is closed.

See Also:

setLoopStartPoint(long), setLoopEndPoint(long), setLoopCount(int), stop()

stop

void stop()

Stops recording, if active, and playback of the currently loaded sequence, if any.

Throws:

IllegalStateException - if the Sequencer is closed.

See Also:

start(), isRunning()

isRunning

boolean isRunning()

Indicates whether the Sequencer is currently running. The default is false. The Sequencer starts running when either start() or startRecording() is called. isRunning then returns true until playback of the sequence completes or stop() is called.

Returns:

true if the Sequencer is running, otherwise false

startRecording

void startRecording()

Throws:

IllegalStateException - if the Sequencer is closed.

See Also:

startRecording(), recordEnable(javax.sound.midi.Track, int), recordDisable(javax.sound.midi.Track)

stopRecording

void stopRecording()

Stops recording, if active. Playback of the current sequence continues.

Throws:

IllegalStateException - if the Sequencer is closed.

See Also:

startRecording(), isRecording()

isRecording

boolean isRecording()

Indicates whether the Sequencer is currently recording. The default is false. The Sequencer begins recording when startRecording() is called, and then returns true until stop() or stopRecording() is called.

Returns:

true if the Sequencer is recording, otherwise false

recordEnable

void recordEnable(Track track,
                  int channel)

Prepares the specified track for recording events received on a particular channel. Once enabled, a track will receive events when recording is active.

Parameters:

track - the track to which events will be recorded

channel - the channel on which events will be received. If -1 is specified for the channel value, the track will receive data from all channels.

Throws:

IllegalArgumentException - thrown if the track is not part of the current sequence.

recordDisable

void recordDisable(Track track)

Disables recording to the specified track. Events will no longer be recorded into this track.

Parameters:

track - the track to disable for recording, or null to disable recording for all tracks.

getTempoInBPM

float getTempoInBPM()

Obtains the current tempo, expressed in beats per minute. The actual tempo of playback is the product of the returned value and the tempo factor.

Returns:

the current tempo in beats per minute

See Also:

getTempoFactor(), setTempoInBPM(float), getTempoInMPQ()

setTempoInBPM

void setTempoInBPM(float bpm)

Sets the tempo in beats per minute. The actual tempo of playback is the product of the specified value and the tempo factor.

Parameters:

bpm - desired new tempo in beats per minute

See Also:

getTempoFactor(), setTempoInMPQ(float), getTempoInBPM()

getTempoInMPQ

float getTempoInMPQ()

Obtains the current tempo, expressed in microseconds per quarter note. The actual tempo of playback is the product of the returned value and the tempo factor.

Returns:

the current tempo in microseconds per quarter note

See Also:

getTempoFactor(), setTempoInMPQ(float), getTempoInBPM()

setTempoInMPQ

void setTempoInMPQ(float mpq)

Sets the tempo in microseconds per quarter note. The actual tempo of playback is the product of the specified value and the tempo factor.

Parameters:

mpq - desired new tempo in microseconds per quarter note.

See Also:

getTempoFactor(), setTempoInBPM(float), getTempoInMPQ()

setTempoFactor

void setTempoFactor(float factor)

Parameters:

factor - the requested tempo scalar

See Also:

getTempoFactor()

getTempoFactor

float getTempoFactor()

Returns the current tempo factor for the sequencer. The default is 1.0.

Returns:

tempo factor.

See Also:

setTempoFactor(float)

getTickLength

long getTickLength()

Obtains the length of the current sequence, expressed in MIDI ticks, or 0 if no sequence is set.

Returns:

length of the sequence in ticks

getTickPosition

long getTickPosition()

Obtains the current position in the sequence, expressed in MIDI ticks. (The duration of a tick in seconds is determined both by the tempo and by the timing resolution stored in the Sequence.)

Returns:

current tick

See Also:

setTickPosition(long)

setTickPosition

void setTickPosition(long tick)

Sets the current sequencer position in MIDI ticks

Parameters:

tick - the desired tick position

See Also:

getTickPosition()

getMicrosecondLength

long getMicrosecondLength()

Obtains the length of the current sequence, expressed in microseconds, or 0 if no sequence is set.

Returns:

length of the sequence in microseconds.

getMicrosecondPosition

long getMicrosecondPosition()

Obtains the current position in the sequence, expressed in microseconds.

Specified by:

getMicrosecondPosition in interface MidiDevice

Returns:

the current position in microseconds

See Also:

setMicrosecondPosition(long)

setMicrosecondPosition

void setMicrosecondPosition(long microseconds)

Sets the current position in the sequence, expressed in microseconds

Parameters:

microseconds - desired position in microseconds

See Also:

getMicrosecondPosition()

setMasterSyncMode

void setMasterSyncMode(Sequencer.SyncMode sync)

Sets the source of timing information used by this sequencer. The sequencer synchronizes to the master, which is the internal clock, MIDI clock, or MIDI time code, depending on the value of sync. The sync argument must be one of the supported modes, as returned by getMasterSyncModes().

Parameters:

sync - the desired master synchronization mode

See Also:

Sequencer.SyncMode.INTERNAL_CLOCK, Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, getMasterSyncMode()

getMasterSyncMode

Sequencer.SyncMode getMasterSyncMode()

Obtains the current master synchronization mode for this sequencer.

Returns:

the current master synchronization mode

See Also:

setMasterSyncMode(Sequencer.SyncMode), getMasterSyncModes()

getMasterSyncModes

Sequencer.SyncMode[] getMasterSyncModes()

Obtains the set of master synchronization modes supported by this sequencer.

Returns:

the available master synchronization modes

See Also:

Sequencer.SyncMode.INTERNAL_CLOCK, Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, getMasterSyncMode(), setMasterSyncMode(Sequencer.SyncMode)

setSlaveSyncMode

void setSlaveSyncMode(Sequencer.SyncMode sync)

Sets the slave synchronization mode for the sequencer. This indicates the type of timing information sent by the sequencer to its receiver. The sync argument must be one of the supported modes, as returned by getSlaveSyncModes().

Parameters:

sync - the desired slave synchronization mode

See Also:

Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, Sequencer.SyncMode.NO_SYNC, getSlaveSyncModes()

getSlaveSyncMode

Sequencer.SyncMode getSlaveSyncMode()

Obtains the current slave synchronization mode for this sequencer.

Returns:

the current slave synchronization mode

See Also:

setSlaveSyncMode(Sequencer.SyncMode), getSlaveSyncModes()

getSlaveSyncModes

Sequencer.SyncMode[] getSlaveSyncModes()

Obtains the set of slave synchronization modes supported by the sequencer.

Returns:

the available slave synchronization modes

See Also:

Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, Sequencer.SyncMode.NO_SYNC

setTrackMute

void setTrackMute(int track,
                  boolean mute)

Sets the mute state for a track. This method may fail for a number of reasons. For example, the track number specified may not be valid for the current sequence, or the sequencer may not support this functionality. An application which needs to verify whether this operation succeeded should follow this call with a call to getTrackMute(int).

Parameters:

track - the track number. Tracks in the current sequence are numbered from 0 to the number of tracks in the sequence minus 1.

mute - the new mute state for the track. true implies the track should be muted, false implies the track should be unmuted.

See Also:

getSequence()

getTrackMute

boolean getTrackMute(int track)

Obtains the current mute state for a track. The default mute state for all tracks which have not been muted is false. In any case where the specified track has not been muted, this method should return false. This applies if the sequencer does not support muting of tracks, and if the specified track index is not valid.

Parameters:

track - the track number. Tracks in the current sequence are numbered from 0 to the number of tracks in the sequence minus 1.

Returns:

true if muted, false if not.

setTrackSolo

void setTrackSolo(int track,
                  boolean solo)

Parameters:

track - the track number. Tracks in the current sequence are numbered from 0 to the number of tracks in the sequence minus 1.

solo - the new solo state for the track. true implies the track should be solo'd, false implies the track should not be solo'd.

See Also:

getSequence()

getTrackSolo

boolean getTrackSolo(int track)

Obtains the current solo state for a track. The default mute state for all tracks which have not been solo'd is false. In any case where the specified track has not been solo'd, this method should return false. This applies if the sequencer does not support soloing of tracks, and if the specified track index is not valid.

Parameters:

track - the track number. Tracks in the current sequence are numbered from 0 to the number of tracks in the sequence minus 1.

Returns:

true if solo'd, false if not.

addMetaEventListener

boolean addMetaEventListener(MetaEventListener listener)

Registers a meta-event listener to receive notification whenever a meta-event is encountered in the sequence and processed by the sequencer. This method can fail if, for instance,this class of sequencer does not support meta-event notification.

Parameters:

listener - listener to add

Returns:

true if the listener was successfully added, otherwise false

See Also:

removeMetaEventListener(javax.sound.midi.MetaEventListener), MetaEventListener, MetaMessage

removeMetaEventListener

void removeMetaEventListener(MetaEventListener listener)

Removes the specified meta-event listener from this sequencer's list of registered listeners, if in fact the listener is registered.

Parameters:

listener - the meta-event listener to remove

See Also:

addMetaEventListener(javax.sound.midi.MetaEventListener)

addControllerEventListener

int[] addControllerEventListener(ControllerEventListener listener,
                                 int[] controllers)

Parameters:

listener - the controller event listener to add to the list of registered listeners

controllers - the MIDI controller numbers for which change notification is requested

Returns:

the numbers of all the MIDI controllers whose changes will now be reported to the specified listener

See Also:

removeControllerEventListener(javax.sound.midi.ControllerEventListener, int[]), ControllerEventListener

removeControllerEventListener

int[] removeControllerEventListener(ControllerEventListener listener,
                                    int[] controllers)

Removes a controller event listener's interest in one or more types of controller event. The controllers argument is an array of MIDI numbers corresponding to the controllers for which the listener should no longer receive change notifications. To completely remove this listener from the list of registered listeners, pass in null for controllers. The returned array contains the MIDI controller numbers for which the listener will now receive events. The array has a length of 0 if the listener will not receive change notifications for any controllers.

Parameters:

listener - old listener

controllers - the MIDI controller numbers for which change notification should be cancelled, or null to cancel for all controllers

Returns:

the numbers of all the MIDI controllers whose changes will now be reported to the specified listener

See Also:

addControllerEventListener(javax.sound.midi.ControllerEventListener, int[])

setLoopStartPoint

void setLoopStartPoint(long tick)

Parameters:

tick - the loop's starting position, in MIDI ticks (zero-based)

Throws:

IllegalArgumentException - if the requested loop start point cannot be set, usually because it falls outside the sequence's duration or because the start point is after the end point

Since:

1.5

See Also:

setLoopEndPoint(long), setLoopCount(int), getLoopStartPoint(), start()

getLoopStartPoint

long getLoopStartPoint()

Obtains the start position of the loop, in MIDI ticks.

Returns:

the start position of the loop, in MIDI ticks (zero-based)

Since:

1.5

See Also:

setLoopStartPoint(long)

setLoopEndPoint

void setLoopEndPoint(long tick)

Parameters:

tick - the loop's ending position, in MIDI ticks (zero-based), or -1 to indicate the final tick

Throws:

IllegalArgumentException - if the requested loop point cannot be set, usually because it falls outside the sequence's duration or because the ending point is before the starting point

Since:

1.5

See Also:

setLoopStartPoint(long), setLoopCount(int), getLoopEndPoint(), start()

getLoopEndPoint

long getLoopEndPoint()

Obtains the end position of the loop, in MIDI ticks.

Returns:

the end position of the loop, in MIDI ticks (zero-based), or -1 to indicate the end of the sequence

Since:

1.5

See Also:

setLoopEndPoint(long)

setLoopCount

void setLoopCount(int count)

Parameters:

count - the number of times playback should loop back from the loop's end position to the loop's start position, or LOOP_CONTINUOUSLY to indicate that looping should continue until interrupted

Throws:

IllegalArgumentException - if count is negative and not equal to LOOP_CONTINUOUSLY

Since:

1.5

See Also:

setLoopStartPoint(long), setLoopEndPoint(long), getLoopCount(), start()

getLoopCount

int getLoopCount()

Obtains the number of repetitions for playback.

Returns:

the number of loops after which playback plays to the end of the sequence

Since:

1.5

See Also:

setLoopCount(int), start()