javax.sound.midi
Interface Sequencer

All Superinterfaces:

MidiDevice

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.

See Also:

Sequencer.SyncMode , addMetaEventListener(javax.sound.midi.MetaEventListener) , ControllerEventListener , Receiver , Transmitter , MidiDevice

Nested Class Summary

static class

Sequencer.SyncMode A SyncMode object represents one of the ways in which a MIDI sequencer's notion of time can be synchronized with a master or slave device.

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

MidiDevice.Info

Field Summary

static int

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

Method Summary

int[]	addControllerEventListener (ControllerEventListener listener, int[] controllers) Registers a controller event listener to receive notification whenever the sequencer processes a control-change event of the requested type or types.
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.
int	getLoopCount () Obtains the number of repetitions for playback.
long	getLoopEndPoint () Obtains the end position of the loop, in MIDI ticks.
long	getLoopStartPoint () Obtains the start position of the loop, in MIDI ticks.
Sequencer.SyncMode	getMasterSyncMode () Obtains the current master synchronization mode for this sequencer.
Sequencer.SyncMode []	getMasterSyncModes () Obtains the set of master synchronization modes supported by this sequencer.
long	getMicrosecondLength () Obtains the length of the current sequence, expressed in microseconds, or 0 if no sequence is set.
long	getMicrosecondPosition () Obtains the current position in the sequence, expressed in microseconds.
Sequence	getSequence () Obtains the sequence on which the Sequencer is currently operating.
Sequencer.SyncMode	getSlaveSyncMode () Obtains the current slave synchronization mode for this sequencer.
Sequencer.SyncMode []	getSlaveSyncModes () Obtains the set of slave synchronization modes supported by the sequencer.
float	getTempoFactor () Returns the current tempo factor for the sequencer.
float	getTempoInBPM () Obtains the current tempo, expressed in beats per minute.
float	getTempoInMPQ () Obtains the current tempo, expressed in microseconds per quarter note.
long	getTickLength () Obtains the length of the current sequence, expressed in MIDI ticks, or 0 if no sequence is set.
long	getTickPosition () Obtains the current position in the sequence, expressed in MIDI ticks.
boolean	getTrackMute (int track) Obtains the current mute state for a track.
boolean	getTrackSolo (int track) Obtains the current solo state for a track.
boolean	isRecording () Indicates whether the Sequencer is currently recording.
boolean	isRunning () Indicates whether the Sequencer is currently running.
void	recordDisable (Track track) Disables recording to the specified track.
void	recordEnable (Track track, int channel) Prepares the specified track for recording events received on a particular channel.
int[]	removeControllerEventListener (ControllerEventListener listener, int[] controllers) Removes a controller event listener's interest in one or more types of controller event.
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.
void	setLoopCount (int count) Sets the number of repetitions of the loop for playback.
void	setLoopEndPoint (long tick) Sets the last MIDI tick that will be played in the loop.
void	setLoopStartPoint (long tick) Sets the first MIDI tick that will be played in the loop.
void	setMasterSyncMode (Sequencer.SyncMode sync) Sets the source of timing information used by this sequencer.
void	setMicrosecondPosition (long microseconds) Sets the current position in the sequence, expressed in microseconds
void	setSequence (InputStream stream) Sets the current sequence on which the sequencer operates.
void	setSequence (Sequence sequence) Sets the current sequence on which the sequencer operates.
void	setSlaveSyncMode (Sequencer.SyncMode sync) Sets the slave synchronization mode for the sequencer.
void	setTempoFactor (float factor) Scales the sequencer's actual playback tempo by the factor provided.
void	setTempoInBPM (float bpm) Sets the tempo in beats per minute.
void	setTempoInMPQ (float mpq) Sets the tempo in microseconds per quarter note.
void	setTickPosition (long tick) Sets the current sequencer position in MIDI ticks
void	setTrackMute (int track, boolean mute) Sets the mute state for a track.
void	setTrackSolo (int track, boolean solo) Sets the solo state for a track.
void	start () Starts playback of the MIDI data in the currently loaded sequence.
void	startRecording () Starts recording and playback of MIDI data.
void	stop () Stops recording, if active, and playback of the currently loaded sequence, if any.
void	stopRecording () Stops recording, if active.

Methods inherited from interface javax.sound.midi.MidiDevice

close , getDeviceInfo , getMaxReceivers , getMaxTransmitters , getReceiver , getReceivers , getTransmitter , getTransmitters , isOpen , open

Field Detail

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

Method Detail

setSequence

void setSequence(Sequence    sequence)
                 throws InvalidMidiDataException   

Sets the current sequence on which the sequencer operates.

This method can be called even if the Sequencer is closed.

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   

Sets the current sequence on which the sequencer operates. The stream must point to MIDI file data.

This method can be called even if the Sequencer is closed.

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()

Obtains the sequence on which the Sequencer is currently operating.

This method can be called even if the Sequencer is closed.

Returns:

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

start

void start()

Starts playback of the MIDI data in the currently loaded sequence. Playback will begin from the current position. If the playback position reaches the loop end point, and the loop count is greater than 0, playback will resume at the loop start point for the number of repetitions set with setLoopCount. After that, or if the loop count is 0, playback will continue to play to the end of the sequence.

The implementation ensures that the synthesizer is brought to a consistent state when jumping to the loop start point by sending appropriate controllers, pitch bend, and program change events.

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()

Starts recording and playback of MIDI data. Data is recorded to all enabled tracks, on the channel(s) for which they were enabled. Recording begins at the current position of the sequencer. Any events already in the track are overwritten for the duration of the recording session. Events from the currently loaded sequence, if any, are delivered to the sequencer's transmitter(s) along with messages received during recording.

Note that tracks are not by default enabled for recording. In order to record MIDI data, at least one track must be specifically enabled for recording.

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()