2362N/A * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * A hardware or software device that plays back a MIDI 0N/A * <code>{@link Sequence sequence}</code> is known as a <em>sequencer</em>. 0N/A * A MIDI sequence contains lists of time-stamped MIDI data, such as 0N/A * might be read from a standard MIDI file. Most 0N/A * sequencers also provide functions for creating and editing sequences. 0N/A * The <code>Sequencer</code> interface includes methods for the following 0N/A * basic MIDI sequencer operations: 0N/A * <li>obtaining a sequence from MIDI file data</li> 0N/A * <li>starting and stopping playback</li> 0N/A * <li>moving to an arbitrary position in the sequence</li> 0N/A * <li>changing the tempo (speed) of playback</li> 0N/A * <li>synchronizing playback to an internal clock or to received MIDI 0N/A * <li>controlling the timing of another device</li> 0N/A * In addition, the following operations are supported, either directly, or 0N/A * indirectly through objects that the <code>Sequencer</code> has access to: 0N/A * <li>editing the data by adding or deleting individual MIDI events or entire 0N/A * <li>muting or soloing individual tracks in the sequence</li> 0N/A * <li>notifying listener objects about any meta-events or 0N/A * control-change events encountered while playing back the sequence.</li> 0N/A * @see Sequencer.SyncMode 0N/A * @see #addMetaEventListener 0N/A * @see ControllerEventListener 0N/A * @author Kara Kytle 0N/A * @author Florian Bomers 0N/A * A value indicating that looping should continue 0N/A * indefinitely rather than complete after a specific 0N/A * @see #setLoopCount 0N/A * Sets the current sequence on which the sequencer operates. 0N/A * <p>This method can be called even if the 0N/A * <code>Sequencer</code> is closed. 0N/A * @param sequence the sequence to be loaded. 0N/A * @throws InvalidMidiDataException if the sequence contains invalid 0N/A * MIDI data, or is not supported. 0N/A * Sets the current sequence on which the sequencer operates. 0N/A * The stream must point to MIDI file data. 0N/A * <p>This method can be called even if the 0N/A * <code>Sequencer</code> is closed. 0N/A * @param stream stream containing MIDI file data. 0N/A * @throws IOException if an I/O exception occurs during reading of the stream. 0N/A * @throws InvalidMidiDataException if invalid data is encountered 0N/A * in the stream, or the stream is not supported. 0N/A * Obtains the sequence on which the Sequencer is currently operating. 0N/A * <p>This method can be called even if the 0N/A * <code>Sequencer</code> is closed. 0N/A * @return the current sequence, or <code>null</code> if no sequence is currently set. 0N/A * Starts playback of the MIDI data in the currently 0N/A * Playback will begin from the current position. 0N/A * If the playback position reaches the loop end point, 0N/A * and the loop count is greater than 0, playback will 0N/A * resume at the loop start point for the number of 0N/A * repetitions set with <code>setLoopCount</code>. 0N/A * After that, or if the loop count is 0, playback will 0N/A * continue to play to the end of the sequence. 0N/A * <p>The implementation ensures that the synthesizer 0N/A * is brought to a consistent state when jumping 0N/A * to the loop start point by sending appropriate 0N/A * controllers, pitch bend, and program change events. 0N/A * @throws IllegalStateException if the <code>Sequencer</code> is 0N/A * @see #setLoopStartPoint 0N/A * @see #setLoopEndPoint 0N/A * @see #setLoopCount 0N/A * Stops recording, if active, and playback of the currently loaded sequence, 0N/A * @throws IllegalStateException if the <code>Sequencer</code> is 0N/A * Indicates whether the Sequencer is currently running. The default is <code>false</code>. 0N/A * The Sequencer starts running when either <code>{@link #start}</code> or <code>{@link #startRecording}</code> 0N/A * is called. <code>isRunning</code> then returns <code>true</code> until playback of the 0N/A * sequence completes or <code>{@link #stop}</code> is called. 0N/A * @return <code>true</code> if the Sequencer is running, otherwise <code>false</code> 0N/A * Starts recording and playback of MIDI data. Data is recorded to all enabled tracks, 0N/A * on the channel(s) for which they were enabled. Recording begins at the current position 0N/A * of the sequencer. Any events already in the track are overwritten for the duration 0N/A * of the recording session. Events from the currently loaded sequence, 0N/A * if any, are delivered to the sequencer's transmitter(s) along with messages 0N/A * received during recording. 0N/A * Note that tracks are not by default enabled for recording. In order to record MIDI data, 0N/A * at least one track must be specifically enabled for recording. 0N/A * @throws IllegalStateException if the <code>Sequencer</code> is 0N/A * @see #startRecording 0N/A * @see #recordEnable 0N/A * @see #recordDisable 0N/A * Stops recording, if active. Playback of the current sequence continues. 0N/A * @throws IllegalStateException if the <code>Sequencer</code> is 0N/A * @see #startRecording 0N/A * Indicates whether the Sequencer is currently recording. The default is <code>false</code>. 0N/A * The Sequencer begins recording when <code>{@link #startRecording}</code> is called, 0N/A * and then returns <code>true</code> until <code>{@link #stop}</code> or <code>{@link #stopRecording}</code> 0N/A * @return <code>true</code> if the Sequencer is recording, otherwise <code>false</code> 0N/A * Prepares the specified track for recording events received on a particular channel. 0N/A * Once enabled, a track will receive events when recording is active. 0N/A * @param track the track to which events will be recorded 0N/A * @param channel the channel on which events will be received. If -1 is specified 0N/A * for the channel value, the track will receive data from all channels. 0N/A * @throws IllegalArgumentException thrown if the track is not part of the current 0N/A * Disables recording to the specified track. Events will no longer be recorded 0N/A * @param track the track to disable for recording, or <code>null</code> to disable 0N/A * recording for all tracks. 0N/A * Obtains the current tempo, expressed in beats per minute. The 0N/A * actual tempo of playback is the product of the returned value 0N/A * and the tempo factor. 0N/A * @return the current tempo in beats per minute 0N/A * @see #getTempoFactor 0N/A * @see #setTempoInBPM(float) 0N/A * @see #getTempoInMPQ 0N/A * Sets the tempo in beats per minute. The actual tempo of playback 0N/A * is the product of the specified value and the tempo factor. 0N/A * @param bpm desired new tempo in beats per minute 0N/A * @see #getTempoFactor 0N/A * @see #setTempoInMPQ(float) 0N/A * @see #getTempoInBPM 0N/A * Obtains the current tempo, expressed in microseconds per quarter 0N/A * note. The actual tempo of playback is the product of the returned 0N/A * value and the tempo factor. 0N/A * @return the current tempo in microseconds per quarter note 0N/A * @see #getTempoFactor 0N/A * @see #setTempoInMPQ(float) 0N/A * @see #getTempoInBPM 0N/A * Sets the tempo in microseconds per quarter note. The actual tempo 0N/A * of playback is the product of the specified value and the tempo 0N/A * @param mpq desired new tempo in microseconds per quarter note. 0N/A * @see #getTempoFactor 0N/A * @see #setTempoInBPM(float) 0N/A * @see #getTempoInMPQ 0N/A * Scales the sequencer's actual playback tempo by the factor provided. 0N/A * The default is 1.0. A value of 1.0 represents the natural rate (the 0N/A * tempo specified in the sequence), 2.0 means twice as fast, etc. 0N/A * The tempo factor does not affect the values returned by 0N/A * <code>{@link #getTempoInMPQ}</code> and <code>{@link #getTempoInBPM}</code>. 0N/A * Those values indicate the tempo prior to scaling. 0N/A * Note that the tempo factor cannot be adjusted when external 0N/A * synchronization is used. In that situation, 0N/A * <code>setTempoFactor</code> always sets the tempo factor to 1.0. 0N/A * @param factor the requested tempo scalar 0N/A * @see #getTempoFactor 0N/A * Returns the current tempo factor for the sequencer. The default is 0N/A * @return tempo factor. 0N/A * @see #setTempoFactor(float) 0N/A * Obtains the length of the current sequence, expressed in MIDI ticks, 0N/A * or 0 if no sequence is set. 0N/A * @return length of the sequence in ticks 0N/A * Obtains the current position in the sequence, expressed in MIDI 0N/A * ticks. (The duration of a tick in seconds is determined both by 0N/A * the tempo and by the timing resolution stored in the 0N/A * <code>{@link Sequence}</code>.) 0N/A * @return current tick 0N/A * @see #setTickPosition 0N/A * Sets the current sequencer position in MIDI ticks 0N/A * @param tick the desired tick position 0N/A * @see #getTickPosition 0N/A * Obtains the length of the current sequence, expressed in microseconds, 0N/A * or 0 if no sequence is set. 0N/A * @return length of the sequence in microseconds. 0N/A * Obtains the current position in the sequence, expressed in 0N/A * @return the current position in microseconds 0N/A * @see #setMicrosecondPosition 0N/A * Sets the current position in the sequence, expressed in microseconds 0N/A * @param microseconds desired position in microseconds 0N/A * @see #getMicrosecondPosition 0N/A * Sets the source of timing information used by this sequencer. 0N/A * The sequencer synchronizes to the master, which is the internal clock, 0N/A * MIDI clock, or MIDI time code, depending on the value of 0N/A * <code>sync</code>. The <code>sync</code> argument must be one 0N/A * of the supported modes, as returned by 0N/A * <code>{@link #getMasterSyncModes}</code>. 0N/A * @param sync the desired master synchronization mode 0N/A * @see SyncMode#INTERNAL_CLOCK 0N/A * @see SyncMode#MIDI_SYNC 0N/A * @see SyncMode#MIDI_TIME_CODE 0N/A * @see #getMasterSyncMode 0N/A * Obtains the current master synchronization mode for this sequencer. 0N/A * @return the current master synchronization mode 0N/A * @see #setMasterSyncMode(Sequencer.SyncMode) 0N/A * @see #getMasterSyncModes 0N/A * Obtains the set of master synchronization modes supported by this 0N/A * @return the available master synchronization modes 0N/A * @see SyncMode#INTERNAL_CLOCK 0N/A * @see SyncMode#MIDI_SYNC 0N/A * @see SyncMode#MIDI_TIME_CODE 0N/A * @see #getMasterSyncMode 0N/A * @see #setMasterSyncMode(Sequencer.SyncMode) 0N/A * Sets the slave synchronization mode for the sequencer. 0N/A * This indicates the type of timing information sent by the sequencer 0N/A * to its receiver. The <code>sync</code> argument must be one 0N/A * of the supported modes, as returned by 0N/A * <code>{@link #getSlaveSyncModes}</code>. 0N/A * @param sync the desired slave synchronization mode 0N/A * @see SyncMode#MIDI_SYNC 0N/A * @see SyncMode#MIDI_TIME_CODE 0N/A * @see SyncMode#NO_SYNC 0N/A * @see #getSlaveSyncModes 0N/A * Obtains the current slave synchronization mode for this sequencer. 0N/A * @return the current slave synchronization mode 0N/A * @see #setSlaveSyncMode(Sequencer.SyncMode) 0N/A * @see #getSlaveSyncModes 0N/A * Obtains the set of slave synchronization modes supported by the sequencer. 0N/A * @return the available slave synchronization modes 0N/A * @see SyncMode#MIDI_SYNC 0N/A * @see SyncMode#MIDI_TIME_CODE 0N/A * @see SyncMode#NO_SYNC 0N/A * Sets the mute state for a track. This method may fail for a number 0N/A * of reasons. For example, the track number specified may not be valid 0N/A * for the current sequence, or the sequencer may not support this functionality. 0N/A * An application which needs to verify whether this operation succeeded should 0N/A * follow this call with a call to <code>{@link #getTrackMute}</code>. 0N/A * @param track the track number. Tracks in the current sequence are numbered 0N/A * from 0 to the number of tracks in the sequence minus 1. 0N/A * @param mute the new mute state for the track. <code>true</code> implies the 0N/A * track should be muted, <code>false</code> implies the track should be unmuted. 0N/A * Obtains the current mute state for a track. The default mute 0N/A * state for all tracks which have not been muted is false. In any 0N/A * case where the specified track has not been muted, this method should 0N/A * return false. This applies if the sequencer does not support muting 0N/A * of tracks, and if the specified track index is not valid. 0N/A * @param track the track number. Tracks in the current sequence are numbered 0N/A * from 0 to the number of tracks in the sequence minus 1. 0N/A * @return <code>true</code> if muted, <code>false</code> if not. 0N/A * Sets the solo state for a track. If <code>solo</code> is <code>true</code> 0N/A * only this track and other solo'd tracks will sound. If <code>solo</code> 0N/A * is <code>false</code> then only other solo'd tracks will sound, unless no 0N/A * tracks are solo'd in which case all un-muted tracks will sound. 0N/A * This method may fail for a number 0N/A * of reasons. For example, the track number specified may not be valid 0N/A * for the current sequence, or the sequencer may not support this functionality. 0N/A * An application which needs to verify whether this operation succeeded should 0N/A * follow this call with a call to <code>{@link #getTrackSolo}</code>. 0N/A * @param track the track number. Tracks in the current sequence are numbered 0N/A * from 0 to the number of tracks in the sequence minus 1. 0N/A * @param solo the new solo state for the track. <code>true</code> implies the 0N/A * track should be solo'd, <code>false</code> implies the track should not be solo'd. 0N/A * Obtains the current solo state for a track. The default mute 0N/A * state for all tracks which have not been solo'd is false. In any 0N/A * case where the specified track has not been solo'd, this method should 0N/A * return false. This applies if the sequencer does not support soloing 0N/A * of tracks, and if the specified track index is not valid. 0N/A * @param track the track number. Tracks in the current sequence are numbered 0N/A * from 0 to the number of tracks in the sequence minus 1. 0N/A * @return <code>true</code> if solo'd, <code>false</code> if not. 0N/A * Registers a meta-event listener to receive 0N/A * notification whenever a meta-event is encountered in the sequence 0N/A * and processed by the sequencer. This method can fail if, for 0N/A * instance,this class of sequencer does not support meta-event 0N/A * @param listener listener to add 0N/A * @return <code>true</code> if the listener was successfully added, 0N/A * otherwise <code>false</code> 0N/A * @see #removeMetaEventListener 0N/A * @see MetaEventListener 0N/A * Removes the specified meta-event listener from this sequencer's 0N/A * list of registered listeners, if in fact the listener is registered. 0N/A * @param listener the meta-event listener to remove 0N/A * @see #addMetaEventListener 0N/A * Registers a controller event listener to receive notification 0N/A * whenever the sequencer processes a control-change event of the 0N/A * requested type or types. The types are specified by the 0N/A * <code>controllers</code> argument, which should contain an array of 0N/A * MIDI controller numbers. (Each number should be between 0 and 127, 0N/A * inclusive. See the MIDI 1.0 Specification for the numbers that 0N/A * correspond to various types of controllers.) 0N/A * The returned array contains the MIDI controller 0N/A * numbers for which the listener will now receive events. 0N/A * Some sequencers might not support controller event notification, in 0N/A * which case the array has a length of 0. Other sequencers might 0N/A * support notification for some controllers but not all. 0N/A * This method may be invoked repeatedly. 0N/A * Each time, the returned array indicates all the controllers 0N/A * that the listener will be notified about, not only the controllers 0N/A * requested in that particular invocation. 0N/A * @param listener the controller event listener to add to the list of 0N/A * registered listeners 0N/A * @param controllers the MIDI controller numbers for which change 0N/A * notification is requested 0N/A * @return the numbers of all the MIDI controllers whose changes will 0N/A * now be reported to the specified listener 0N/A * @see #removeControllerEventListener 0N/A * @see ControllerEventListener 0N/A * Removes a controller event listener's interest in one or more 0N/A * types of controller event. The <code>controllers</code> argument 0N/A * is an array of MIDI numbers corresponding to the controllers for 0N/A * which the listener should no longer receive change notifications. 0N/A * To completely remove this listener from the list of registered 0N/A * listeners, pass in <code>null</code> for <code>controllers</code>. 0N/A * The returned array contains the MIDI controller 0N/A * numbers for which the listener will now receive events. The 0N/A * array has a length of 0 if the listener will not receive 0N/A * change notifications for any controllers. 0N/A * @param listener old listener 0N/A * @param controllers the MIDI controller numbers for which change 0N/A * notification should be cancelled, or <code>null</code> to cancel 0N/A * for all controllers 0N/A * @return the numbers of all the MIDI controllers whose changes will 0N/A * now be reported to the specified listener 0N/A * @see #addControllerEventListener 0N/A * Sets the first MIDI tick that will be 0N/A * played in the loop. If the loop count is 0N/A * greater than 0, playback will jump to this 0N/A * point when reaching the loop end point. 0N/A * <p>A value of 0 for the starting point means the 0N/A * beginning of the loaded sequence. The starting 0N/A * point must be lower than or equal to the ending 0N/A * point, and it must fall within the size of the 0N/A * <p>A sequencer's loop start point defaults to 0N/A * start of the sequence. 0N/A * @param tick the loop's starting position, 0N/A * in MIDI ticks (zero-based) 0N/A * @throws IllegalArgumentException if the requested 0N/A * loop start point cannot be set, usually because 0N/A * it falls outside the sequence's 0N/A * duration or because the start point is 0N/A * after the end point 0N/A * @see #setLoopEndPoint 0N/A * @see #setLoopCount 0N/A * @see #getLoopStartPoint 0N/A * Obtains the start position of the loop, 0N/A * @return the start position of the loop, 0N/A in MIDI ticks (zero-based) 0N/A * @see #setLoopStartPoint 0N/A * Sets the last MIDI tick that will be played in 0N/A * the loop. If the loop count is 0, the loop end 0N/A * point has no effect and playback continues to 0N/A * play when reaching the loop end point. 0N/A * <p>A value of -1 for the ending point 0N/A * indicates the last tick of the sequence. 0N/A * Otherwise, the ending point must be greater 0N/A * than or equal to the starting point, and it must 0N/A * fall within the size of the loaded sequence. 0N/A * <p>A sequencer's loop end point defaults to -1, 0N/A * meaning the end of the sequence. 0N/A * @param tick the loop's ending position, 0N/A * in MIDI ticks (zero-based), or 0N/A * -1 to indicate the final tick 0N/A * @throws IllegalArgumentException if the requested 0N/A * loop point cannot be set, usually because 0N/A * it falls outside the sequence's 0N/A * duration or because the ending point is 0N/A * before the starting point 0N/A * @see #setLoopStartPoint 0N/A * @see #setLoopCount 0N/A * @see #getLoopEndPoint 0N/A * Obtains the end position of the loop, 0N/A * @return the end position of the loop, in MIDI 0N/A * ticks (zero-based), or -1 to indicate 0N/A * the end of the sequence 0N/A * @see #setLoopEndPoint 0N/A * Sets the number of repetitions of the loop for 0N/A * When the playback position reaches the loop end point, 0N/A * it will loop back to the loop start point 0N/A * <code>count</code> times, after which playback will 0N/A * continue to play to the end of the sequence. 0N/A * If the current position when this method is invoked 0N/A * is greater than the loop end point, playback 0N/A * continues to the end of the sequence without looping, 0N/A * unless the loop end point is changed subsequently. 0N/A * A <code>count</code> value of 0 disables looping: 0N/A * playback will continue at the loop end point, and it 0N/A * will not loop back to the loop start point. 0N/A * This is a sequencer's default. 0N/A * <p>If playback is stopped during looping, the 0N/A * current loop status is cleared; subsequent start 0N/A * requests are not affected by an interrupted loop 0N/A * @param count the number of times playback should 0N/A * loop back from the loop's end position 0N/A * to the loop's start position, or 0N/A * <code>{@link #LOOP_CONTINUOUSLY}</code> 0N/A * to indicate that looping should 0N/A * continue until interrupted 0N/A * @throws IllegalArgumentException if <code>count</code> is 0N/A * negative and not equal to {@link #LOOP_CONTINUOUSLY} 0N/A * @see #setLoopStartPoint 0N/A * @see #setLoopEndPoint 0N/A * @see #getLoopCount 0N/A * Obtains the number of repetitions for 0N/A * @return the number of loops after which 0N/A * playback plays to the end of the 0N/A * @see #setLoopCount 0N/A * A <code>SyncMode</code> object represents one of the ways in which 0N/A * a MIDI sequencer's notion of time can be synchronized with a master 0N/A * If the sequencer is being synchronized to a master, the 0N/A * sequencer revises its current time in response to messages from 0N/A * the master. If the sequencer has a slave, the sequencer 0N/A * similarly sends messages to control the slave's timing. 0N/A * There are three predefined modes that specify possible masters 0N/A * for a sequencer: <code>INTERNAL_CLOCK</code>, 0N/A * <code>MIDI_SYNC</code>, and <code>MIDI_TIME_CODE</code>. The 0N/A * latter two work if the sequencer receives MIDI messages from 0N/A * another device. In these two modes, the sequencer's time gets reset 0N/A * based on system real-time timing clock messages or MIDI time code 0N/A * (MTC) messages, respectively. These two modes can also be used 0N/A * as slave modes, in which case the sequencer sends the corresponding 0N/A * types of MIDI messages to its receiver (whether or not the sequencer 0N/A * is also receiving them from a master). A fourth mode, 0N/A * <code>NO_SYNC</code>, is used to indicate that the sequencer should 0N/A * not control its receiver's timing. 0N/A * @see Sequencer#setMasterSyncMode(Sequencer.SyncMode) 0N/A * @see Sequencer#setSlaveSyncMode(Sequencer.SyncMode) 0N/A * Synchronization mode name. 0N/A * Constructs a synchronization mode. 0N/A * @param name name of the synchronization mode 0N/A * Determines whether two objects are equal. 0N/A * Returns <code>true</code> if the objects are identical 0N/A * @param obj the reference object with which to compare 0N/A * @return <code>true</code> if this object is the same as the 0N/A * <code>obj</code> argument, <code>false</code> otherwise 0N/A * Finalizes the hashcode method. 0N/A * Provides this synchronization mode's name as the string 0N/A * representation of the mode. 0N/A * @return the name of this synchronization mode 0N/A * A master synchronization mode that makes the sequencer get 0N/A * its timing information from its internal clock. This is not 0N/A * a legal slave sync mode. 0N/A * A master or slave synchronization mode that specifies the 0N/A * messages. If this mode is used as the master sync mode, 0N/A * the sequencer gets its timing information from system real-time 0N/A * MIDI clock messages. This mode only applies as the master sync 0N/A * mode for sequencers that are also MIDI receivers. If this is the 0N/A * slave sync mode, the sequencer sends system real-time MIDI clock 0N/A * messages to its receiver. MIDI clock messages are sent at a rate 0N/A * of 24 per quarter note. 0N/A * A master or slave synchronization mode that specifies the 0N/A * use of MIDI Time Code. 0N/A * If this mode is used as the master sync mode, 0N/A * the sequencer gets its timing information from MIDI Time Code 0N/A * messages. This mode only applies as the master sync 0N/A * mode to sequencers that are also MIDI receivers. If this 0N/A * mode is used as the 0N/A * slave sync mode, the sequencer sends MIDI Time Code 0N/A * messages to its receiver. (See the MIDI 1.0 Detailed 0N/A * Specification for a description of MIDI Time Code.) 0N/A * A slave synchronization mode indicating that no timing information 0N/A * should be sent to the receiver. This is not a legal master sync