/*

 * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.sound.midi;

import java.io.InputStream;

import java.io.IOException;

/**

 * A hardware or software device that plays back a MIDI

 * <code>{@link Sequence sequence}</code> is known as a <em>sequencer</em>.

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

 * <p>

 * The <code>Sequencer</code> interface includes methods for the following

 * basic MIDI sequencer operations:

 * <ul>

 * <li>obtaining a sequence from MIDI file data</li>

 * <li>starting and stopping playback</li>

 * <li>moving to an arbitrary position in the sequence</li>

 * <li>changing the tempo (speed) of playback</li>

 * <li>synchronizing playback to an internal clock or to received MIDI

 * messages</li>

 * <li>controlling the timing of another device</li>

 * </ul>

 * In addition, the following operations are supported, either directly, or

 * indirectly through objects that the <code>Sequencer</code> has access to:

 * <ul>

 * <li>editing the data by adding or deleting individual MIDI events or entire

 * tracks</li>

 * <li>muting or soloing individual tracks in the sequence</li>

 * <li>notifying listener objects about any meta-events or

 * control-change events encountered while playing back the sequence.</li>

 * </ul>

 *

 * @see Sequencer.SyncMode

 * @see #addMetaEventListener

 * @see ControllerEventListener

 * @see Receiver

 * @see Transmitter

 * @see MidiDevice

 *

 * @author Kara Kytle

 * @author Florian Bomers

 */

public interface Sequencer extends MidiDevice {

    /**

     * A value indicating that looping should continue

     * indefinitely rather than complete after a specific

     * number of loops.

     *

     * @see #setLoopCount

     * @since 1.5

     */

    public static final int LOOP_CONTINUOUSLY = -1;

    /**

     * Sets the current sequence on which the sequencer operates.

     *

     * <p>This method can be called even if the

     * <code>Sequencer</code> is closed.

     *

     * @param sequence the sequence to be loaded.

     * @throws InvalidMidiDataException if the sequence contains invalid

     * MIDI data, or is not supported.

     */

    public void setSequence(Sequence sequence) throws InvalidMidiDataException;

    /**

     * Sets the current sequence on which the sequencer operates.

     * The stream must point to MIDI file data.

     *

     * <p>This method can be called even if the

     * <code>Sequencer</code> is closed.

     *

     * @param stream stream containing MIDI file data.

     * @throws IOException if an I/O exception occurs during reading of the stream.

     * @throws InvalidMidiDataException if invalid data is encountered

     * in the stream, or the stream is not supported.

     */

    public void setSequence(InputStream stream) throws IOException, InvalidMidiDataException;

    /**

     * Obtains the sequence on which the Sequencer is currently operating.

     *

     * <p>This method can be called even if the

     * <code>Sequencer</code> is closed.

     *

     * @return the current sequence, or <code>null</code> if no sequence is currently set.

     */

    public Sequence getSequence();

    /**

     * 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 <code>setLoopCount</code>.

     * After that, or if the loop count is 0, playback will

     * continue to play to the end of the sequence.

     *

     * <p>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 <code>Sequencer</code> is

     * closed.

     *

     * @see #setLoopStartPoint

     * @see #setLoopEndPoint

     * @see #setLoopCount

     * @see #stop

     */

    public void start();

    /**

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

     * if any.

     *

     * @throws IllegalStateException if the <code>Sequencer</code> is

     * closed.

     *

     * @see #start

     * @see #isRunning

     */

    public void stop();

    /**

     * Indicates whether the Sequencer is currently running.  The default is <code>false</code>.

     * The Sequencer starts running when either <code>{@link #start}</code> or <code>{@link #startRecording}</code>

     * is called.  <code>isRunning</code> then returns <code>true</code> until playback of the

     * sequence completes or <code>{@link #stop}</code> is called.

     * @return <code>true</code> if the Sequencer is running, otherwise <code>false</code>

     */

    public boolean isRunning();

    /**

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

     * <p>

     * 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 <code>Sequencer</code> is

     * closed.

     *

     * @see #startRecording

     * @see #recordEnable

     * @see #recordDisable

     */

    public void startRecording();

    /**

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

     *

     * @throws IllegalStateException if the <code>Sequencer</code> is

     * closed.

     *

     * @see #startRecording

     * @see #isRecording

     */

    public void stopRecording();

    /**

     * Indicates whether the Sequencer is currently recording.  The default is <code>false</code>.

     * The Sequencer begins recording when <code>{@link #startRecording}</code> is called,

     * and then returns <code>true</code> until <code>{@link #stop}</code> or <code>{@link #stopRecording}</code>

     * is called.

     * @return <code>true</code> if the Sequencer is recording, otherwise <code>false</code>

     */

    public boolean isRecording();

    /**

     * Prepares the specified track for recording events received on a particular channel.

     * Once enabled, a track will receive events when recording is active.

     * @param track the track to which events will be recorded

     * @param 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.

     */

    public void recordEnable(Track track, int channel);

    /**

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

     * into this track.

     * @param track the track to disable for recording, or <code>null</code> to disable

     * recording for all tracks.

     */

    public void recordDisable(Track track);

    /**

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

     *

     * @return the current tempo in beats per minute

     *

     * @see #getTempoFactor

     * @see #setTempoInBPM(float)

     * @see #getTempoInMPQ

     */

    public float getTempoInBPM();

    /**

     * Sets the tempo in beats per minute.   The actual tempo of playback

     * is the product of the specified value and the tempo factor.

     *

     * @param bpm desired new tempo in beats per minute

     * @see #getTempoFactor

     * @see #setTempoInMPQ(float)

     * @see #getTempoInBPM

     */

    public void setTempoInBPM(float bpm);

    /**

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

     *

     * @return the current tempo in microseconds per quarter note

     * @see #getTempoFactor

     * @see #setTempoInMPQ(float)

     * @see #getTempoInBPM

     */

    public float getTempoInMPQ();

    /**

     * Sets the tempo in microseconds per quarter note.  The actual tempo

     * of playback is the product of the specified value and the tempo

     * factor.

     *

     * @param mpq desired new tempo in microseconds per quarter note.

     * @see #getTempoFactor

     * @see #setTempoInBPM(float)

     * @see #getTempoInMPQ

     */

    public void setTempoInMPQ(float mpq);

    /**

     * 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

     * <code>{@link #getTempoInMPQ}</code> and <code>{@link #getTempoInBPM}</code>.

     * Those values indicate the tempo prior to scaling.

     * <p>

     * Note that the tempo factor cannot be adjusted when external

     * synchronization is used.  In that situation,

     * <code>setTempoFactor</code> always sets the tempo factor to 1.0.

     *

     * @param factor the requested tempo scalar

     * @see #getTempoFactor

     */

    public void setTempoFactor(float factor);

    /**

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

     * 1.0.

     *

     * @return tempo factor.

     * @see #setTempoFactor(float)

     */

    public float getTempoFactor();

    /**

     * Obtains the length of the current sequence, expressed in MIDI ticks,

     * or 0 if no sequence is set.

     * @return length of the sequence in ticks

     */

    public long getTickLength();

    /**

     * 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

     * <code>{@link Sequence}</code>.)

     *

     * @return current tick

     * @see #setTickPosition

     */

    public long getTickPosition();

    /**

     * Sets the current sequencer position in MIDI ticks

     * @param tick the desired tick position

     * @see #getTickPosition

     */

    public void setTickPosition(long tick);

    /**

     * Obtains the length of the current sequence, expressed in microseconds,

     * or 0 if no sequence is set.

     * @return length of the sequence in microseconds.

     */

    public long getMicrosecondLength();

    /**

     * Obtains the current position in the sequence, expressed in

     * microseconds.

     * @return the current position in microseconds

     * @see #setMicrosecondPosition

     */

    public long getMicrosecondPosition();

    /**

     * Sets the current position in the sequence, expressed in microseconds

     * @param microseconds desired position in microseconds

     * @see #getMicrosecondPosition

     */

    public void setMicrosecondPosition(long microseconds);

    /**

     * 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

     * <code>sync</code>.  The <code>sync</code> argument must be one

     * of the supported modes, as returned by

     * <code>{@link #getMasterSyncModes}</code>.

     *

     * @param sync the desired master synchronization mode

     *

     * @see SyncMode#INTERNAL_CLOCK

     * @see SyncMode#MIDI_SYNC

     * @see SyncMode#MIDI_TIME_CODE

     * @see #getMasterSyncMode

     */

    public void setMasterSyncMode(SyncMode sync);

    /**

     * Obtains the current master synchronization mode for this sequencer.

     *

     * @return the current master synchronization mode

     *

     * @see #setMasterSyncMode(Sequencer.SyncMode)

     * @see #getMasterSyncModes

     */

    public SyncMode getMasterSyncMode();

    /**

     * Obtains the set of master synchronization modes supported by this

     * sequencer.

     *

     * @return the available master synchronization modes

     *

     * @see SyncMode#INTERNAL_CLOCK

     * @see SyncMode#MIDI_SYNC

     * @see SyncMode#MIDI_TIME_CODE

     * @see #getMasterSyncMode

     * @see #setMasterSyncMode(Sequencer.SyncMode)

     */

    public SyncMode[] getMasterSyncModes();

    /**

     * Sets the slave synchronization mode for the sequencer.

     * This indicates the type of timing information sent by the sequencer

     * to its receiver.  The <code>sync</code> argument must be one

     * of the supported modes, as returned by

     * <code>{@link #getSlaveSyncModes}</code>.

     *

     * @param sync the desired slave synchronization mode

     *

     * @see SyncMode#MIDI_SYNC

     * @see SyncMode#MIDI_TIME_CODE

     * @see SyncMode#NO_SYNC

     * @see #getSlaveSyncModes

     */

    public void setSlaveSyncMode(SyncMode sync);

    /**

     * Obtains the current slave synchronization mode for this sequencer.

     *

     * @return the current slave synchronization mode

     *

     * @see #setSlaveSyncMode(Sequencer.SyncMode)

     * @see #getSlaveSyncModes

     */

    public SyncMode getSlaveSyncMode();

    /**

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

     *

     * @return the available slave synchronization modes

     *

     * @see SyncMode#MIDI_SYNC

     * @see SyncMode#MIDI_TIME_CODE

     * @see SyncMode#NO_SYNC

     */

    public SyncMode[] getSlaveSyncModes();

    /**

     * 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 <code>{@link #getTrackMute}</code>.

     *

     * @param track the track number.  Tracks in the current sequence are numbered

     * from 0 to the number of tracks in the sequence minus 1.

     * @param mute the new mute state for the track.  <code>true</code> implies the

     * track should be muted, <code>false</code> implies the track should be unmuted.

     * @see #getSequence

     */

    public void setTrackMute(int track, boolean mute);

    /**

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

     *

     * @param track the track number.  Tracks in the current sequence are numbered

     * from 0 to the number of tracks in the sequence minus 1.

     * @return <code>true</code> if muted, <code>false</code> if not.

     */

    public boolean getTrackMute(int track);

    /**

     * Sets the solo state for a track.  If <code>solo</code> is <code>true</code>

     * only this track and other solo'd tracks will sound. If <code>solo</code>

     * is <code>false</code> then only other solo'd tracks will sound, unless no

     * tracks are solo'd in which case all un-muted tracks will sound.

     * <p>

     * 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 <code>{@link #getTrackSolo}</code>.

     *

     * @param track the track number.  Tracks in the current sequence are numbered

     * from 0 to the number of tracks in the sequence minus 1.

     * @param solo the new solo state for the track.  <code>true</code> implies the

     * track should be solo'd, <code>false</code> implies the track should not be solo'd.

     * @see #getSequence

     */

    public void setTrackSolo(int track, boolean solo);

    /**

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

     *

     * @param track the track number.  Tracks in the current sequence are numbered

     * from 0 to the number of tracks in the sequence minus 1.

     * @return <code>true</code> if solo'd, <code>false</code> if not.

     */

    public boolean getTrackSolo(int track);

    /**

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

     *

     * @param listener listener to add

     * @return <code>true</code> if the listener was successfully added,

     * otherwise <code>false</code>