Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Inner 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.

Inner classes inherited from class javax.sound.midi.MidiDevice
`MidiDevice.Info`

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.
`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.
`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.
`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` | `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, getTransmitter, isOpen, open`

Method Detail

### setSequence

    public void setSequence(Sequence sequence)
                     throws InvalidMidiDataException

  Sets the current sequence on which the sequencer operates.
  Parameters:
    `sequence` - the sequence to be loaded.
  Throws:
    `InvalidMidiDataException` - if the sequence contains invalid MIDI data, or is not supported.

### setSequence

    public void setSequence(InputStream stream)
                     throws IOException,
                            InvalidMidiDataException

  Sets the current sequence on which the sequencer operates. The stream must point to MIDI file data.
  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

    public Sequence getSequence()

  Obtains the sequence on which the Sequencer is currently operating.
  Returns:
    the current sequence, or `null` if no sequence is currently set.

### start

    public void start()

  Starts playback of the MIDI data in the currently loaded sequence.
  See Also:
    `start()`, `stop()`

### stop

    public void stop()

  Stops recording, if active, and playback of the currently loaded sequence, if any.
  See Also:
    `start()`, `isRunning()`

### isRunning

    public 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

    public 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 MIDI OUT receiver(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.

  See Also:
    `startRecording()`, `recordEnable(javax.sound.midi.Track, int)`, `recordDisable(javax.sound.midi.Track)`

### stopRecording

    public void stopRecording()

  Stops recording, if active. Playback of the current sequence continues.
  See Also:
    `startRecording()`, `isRecording()`

### isRecording

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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 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.

  Parameters:
    `factor` - the requested tempo scalar
  See Also:
    `getTempoFactor()`

### getTempoFactor

    public float getTempoFactor()

  Returns the current tempo factor for the sequencer. The default is 1.0.
  Returns:
    tempo factor.
  See Also:
    `setTempoFactor(float)`

### getTickLength

    public long getTickLength()

  Obtains the length of the current sequence, expressed in MIDI ticks.
  Returns:
    length of the sequence in ticks

### getTickPosition

    public 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

    public void setTickPosition(long tick)

  Sets the current sequencer position in MIDI ticks
  Parameters:
    `tick` - the desired tick position
  See Also:
    `getTickPosition()`

### getMicrosecondLength

    public long getMicrosecondLength()

  Obtains the length of the current sequence, expressed in microseconds.
  Returns:
    length of the sequence in microseconds

### getMicrosecondPosition

    public 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

    public void setMicrosecondPosition(long microseconds)

  Sets the current position in the sequence, expressed in microseconds
  Parameters:
    `microseconds` - desired position in microseconds
  See Also:
    `getMicrosecondPosition()`

### setMasterSyncMode

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public void setTrackSolo(int track,
                             boolean solo)

  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(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:
    `getSequence()`

### getTrackSolo

    public 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

    public 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

    public 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

    public 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. 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.

  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

    public 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[])`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2001 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.