Interface Sequencer
- All Superinterfaces:
AutoCloseable
,MidiDevice
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
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:
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic class
ASyncMode
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
Modifier and TypeFieldDescriptionstatic final int
A value indicating that looping should continue indefinitely rather than complete after a specific number of loops. -
Method Summary
Modifier and TypeMethodDescriptionint[]
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
Obtains the number of repetitions for playback.long
Obtains the end position of the loop, in MIDI ticks.long
Obtains the start position of the loop, in MIDI ticks.Obtains the current master synchronization mode for this sequencer.Obtains the set of master synchronization modes supported by this sequencer.long
Obtains the length of the current sequence, expressed in microseconds, or 0 if no sequence is set.long
Obtains the current position in the sequence, expressed in microseconds.Obtains the sequence on which the Sequencer is currently operating.Obtains the current slave synchronization mode for this sequencer.Obtains the set of slave synchronization modes supported by the sequencer.float
Returns the current tempo factor for the sequencer.float
Obtains the current tempo, expressed in beats per minute.float
Obtains the current tempo, expressed in microseconds per quarter note.long
Obtains the length of the current sequence, expressed in MIDI ticks, or 0 if no sequence is set.long
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
Indicates whether the Sequencer is currently recording.boolean
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
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
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
Starts recording and playback of MIDI data.void
stop()
Stops recording, if active, and playback of the currently loaded sequence, if any.void
Stops recording, if active.Methods inherited from interface javax.sound.midi.MidiDevice
close, getDeviceInfo, getMaxReceivers, getMaxTransmitters, getReceiver, getReceivers, getTransmitter, getTransmitters, isOpen, open
-
Field Details
-
LOOP_CONTINUOUSLY
static final int LOOP_CONTINUOUSLYA value indicating that looping should continue indefinitely rather than complete after a specific number of loops.- Since:
- 1.5
- See Also:
-
-
Method Details
-
setSequence
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
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 streamInvalidMidiDataException
- 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 withsetLoopCount
. 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 theSequencer
is closed- See Also:
-
stop
void stop()Stops recording, if active, and playback of the currently loaded sequence, if any.- Throws:
IllegalStateException
- if theSequencer
is closed- See Also:
-
isRunning
boolean isRunning()Indicates whether the Sequencer is currently running. The default isfalse
. The Sequencer starts running when eitherstart()
orstartRecording()
is called.isRunning
then returnstrue
until playback of the sequence completes orstop()
is called.- Returns:
true
if the Sequencer is running, otherwisefalse
-
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 theSequencer
is closed- See Also:
-
stopRecording
void stopRecording()Stops recording, if active. Playback of the current sequence continues.- Throws:
IllegalStateException
- if theSequencer
is closed- See Also:
-
isRecording
boolean isRecording()Indicates whether the Sequencer is currently recording. The default isfalse
. The Sequencer begins recording whenstartRecording()
is called, and then returnstrue
untilstop()
orstopRecording()
is called.- Returns:
true
if the Sequencer is recording, otherwisefalse
-
recordEnable
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 recordedchannel
- 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
Disables recording to the specified track. Events will no longer be recorded into this track.- Parameters:
track
- the track to disable for recording, ornull
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:
-
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:
-
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:
-
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:
-
setTempoFactor
void setTempoFactor(float factor) Scales the sequencer's actual playback tempo by the factor provided. The default is 1.0. A value of 1.0 represents the natural rate (the tempo specified in the sequence), 2.0 means twice as fast, etc. The tempo factor does not affect the values returned bygetTempoInMPQ()
andgetTempoInBPM()
. Those values indicate the tempo prior to scaling.Note that the tempo factor cannot be adjusted when external synchronization is used. In that situation,
setTempoFactor
always sets the tempo factor to 1.0.- Parameters:
factor
- the requested tempo scalar- See Also:
-
getTempoFactor
float getTempoFactor()Returns the current tempo factor for the sequencer. The default is 1.0.- Returns:
- tempo factor
- See Also:
-
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 theSequence
.)- Returns:
- current tick
- See Also:
-
setTickPosition
void setTickPosition(long tick) Sets the current sequencer position in MIDI ticks.- Parameters:
tick
- the desired tick position- See Also:
-
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 interfaceMidiDevice
- Returns:
- the current position in microseconds
- See Also:
-
setMicrosecondPosition
void setMicrosecondPosition(long microseconds) Sets the current position in the sequence, expressed in microseconds.- Parameters:
microseconds
- desired position in microseconds- See Also:
-
setMasterSyncMode
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 ofsync
. Thesync
argument must be one of the supported modes, as returned bygetMasterSyncModes()
.- Parameters:
sync
- the desired master synchronization mode- See Also:
-
getMasterSyncMode
Sequencer.SyncMode getMasterSyncMode()Obtains the current master synchronization mode for this sequencer.- Returns:
- the current master synchronization mode
- See Also:
-
getMasterSyncModes
Sequencer.SyncMode[] getMasterSyncModes()Obtains the set of master synchronization modes supported by this sequencer.- Returns:
- the available master synchronization modes
- See Also:
-
setSlaveSyncMode
Sets the slave synchronization mode for the sequencer. This indicates the type of timing information sent by the sequencer to its receiver. Thesync
argument must be one of the supported modes, as returned bygetSlaveSyncModes()
.- Parameters:
sync
- the desired slave synchronization mode- See Also:
-
getSlaveSyncMode
Sequencer.SyncMode getSlaveSyncMode()Obtains the current slave synchronization mode for this sequencer.- Returns:
- the current slave synchronization mode
- See Also:
-
getSlaveSyncModes
Sequencer.SyncMode[] getSlaveSyncModes()Obtains the set of slave synchronization modes supported by the sequencer.- Returns:
- the available slave synchronization modes
- See Also:
-
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 togetTrackMute(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:
-
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) Sets the solo state for a track. Ifsolo
istrue
only this track and other solo'd tracks will sound. Ifsolo
isfalse
then only other solo'd tracks will sound, unless no tracks are solo'd in which case all un-muted tracks will sound.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
getTrackSolo(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.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:
-
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
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, otherwisefalse
- See Also:
-
removeMetaEventListener
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:
-
addControllerEventListener
Registers a controller event listener to receive notification whenever the sequencer processes a control-change event of the requested type or types. The types are specified by thecontrollers
argument, which should contain an array of MIDI controller numbers. (Each number should be between 0 and 127, inclusive. See the MIDI 1.0 Specification for the numbers that correspond to various types of controllers.)The returned array contains the MIDI controller numbers for which the listener will now receive events. Some sequencers might not support controller event notification, in which case the array has a length of 0. Other sequencers might support notification for some controllers but not all. This method may be invoked repeatedly. Each time, the returned array indicates all the controllers that the listener will be notified about, not only the controllers requested in that particular invocation.
- Parameters:
listener
- the controller event listener to add to the list of registered listenerscontrollers
- 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
Removes a controller event listener's interest in one or more types of controller event. Thecontrollers
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 innull
forcontrollers
. 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 listenercontrollers
- the MIDI controller numbers for which change notification should be cancelled, ornull
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:
-
setLoopStartPoint
void setLoopStartPoint(long tick) Sets the first MIDI tick that will be played in the loop. If the loop count is greater than 0, playback will jump to this point when reaching the loop end point.A value of 0 for the starting point means the beginning of the loaded sequence. The starting point must be lower than or equal to the ending point, and it must fall within the size of the loaded sequence.
A sequencer's loop start point defaults to start of the sequence.
- 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:
-
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:
-
setLoopEndPoint
void setLoopEndPoint(long tick) Sets the last MIDI tick that will be played in the loop. If the loop count is 0, the loop end point has no effect and playback continues to play when reaching the loop end point.A value of -1 for the ending point indicates the last tick of the sequence. Otherwise, the ending point must be greater than or equal to the starting point, and it must fall within the size of the loaded sequence.
A sequencer's loop end point defaults to -1, meaning the end of the sequence.
- 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:
-
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:
-
setLoopCount
void setLoopCount(int count) Sets the number of repetitions of the loop for playback. When the playback position reaches the loop end point, it will loop back to the loop start pointcount
times, after which playback will continue to play to the end of the sequence.If the current position when this method is invoked is greater than the loop end point, playback continues to the end of the sequence without looping, unless the loop end point is changed subsequently.
A
count
value of 0 disables looping: playback will continue at the loop end point, and it will not loop back to the loop start point. This is a sequencer's default.If playback is stopped during looping, the current loop status is cleared; subsequent start requests are not affected by an interrupted loop operation.
- Parameters:
count
- the number of times playback should loop back from the loop's end position to the loop's start position, orLOOP_CONTINUOUSLY
to indicate that looping should continue until interrupted- Throws:
IllegalArgumentException
- ifcount
is negative and not equal toLOOP_CONTINUOUSLY
- Since:
- 1.5
- See Also:
-
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:
-