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.
A value indicating that looping should continue
indefinitely rather than complete after a specific
number of loops.
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 the
controllers
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.
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.
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
.
Obtains information about the device, including its Java class and
Strings
containing its name, vendor, and description.
Obtains the number of repetitions for
playback.
Obtains the end position of the loop,
in MIDI ticks.
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.
Obtains the maximum number of MIDI IN connections available on this
MIDI device for receiving MIDI data.
Obtains the maximum number of MIDI OUT connections available on this
MIDI device for transmitting MIDI data.
Obtains the length of the current sequence, expressed in microseconds,
or 0 if no sequence is set.
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.
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.
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 all currently active, non-closed receivers
connected with this MidiDevice.
A receiver can be removed
from the device by closing it.
Obtains the sequence on which the Sequencer is currently operating.
This method can be called even if the
Sequencer
is closed.
Obtains the current slave synchronization mode for this sequencer.
Obtains the set of slave synchronization modes supported by the sequencer.
Returns the current tempo factor for the sequencer. The default is
1.0.
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.
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.
Obtains the length of the current sequence, expressed in MIDI ticks,
or 0 if no sequence is set.
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
.)
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.
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.
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.
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 all currently active, non-closed transmitters
connected with this MidiDevice.
A transmitter can be removed
from the device by closing it.
Reports whether the device is open.
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.
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.
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.
Disables recording to the specified track. Events will no longer be recorded
into this track.
Prepares the specified track for recording events received on a particular channel.
Once enabled, a track will receive events when recording is active.
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.
Removes the specified meta-event listener from this sequencer's
list of registered listeners, if in fact the listener is registered.
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 point
count
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.
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.
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.
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
.
Sets the current position in the sequence, expressed in microseconds
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.
Sets the current sequence on which the sequencer operates.
This method can be called even if the
Sequencer
is closed.
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
.
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 by
#getTempoInMPQ
and
#getTempoInBPM
.
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.
Sets the tempo in beats per minute. The actual tempo of playback
is the product of the specified value and the tempo factor.
Sets the tempo in microseconds per quarter note. The actual tempo
of playback is the product of the specified value and the tempo
factor.
Sets the current sequencer position in MIDI ticks
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
.
Sets the solo state for a track. If
solo
is
true
only this track and other solo'd tracks will sound. If
solo
is
false
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
.
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.
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.
Stops recording, if active, and playback of the currently loaded sequence,
if any.
Stops recording, if active. Playback of the current sequence continues.