Sequencer


1   /*
2    * @(#)Sequencer.java   1.36 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.sound.midi;
9   
10  import java.io.InputStream  ;
11  import java.io.IOException  ;
12  
13  
14  /**
15   * A hardware or software device that plays back a MIDI
16   * <code>{@link Sequence sequence}</code> is known as a <em>sequencer</em>.
17   * A MIDI sequence contains lists of time-stamped MIDI data, such as
18   * might be read from a standard MIDI file.  Most
19   * sequencers also provide functions for creating and editing sequences.
20   * <p>
21   * The <code>Sequencer</code> interface includes methods for the following
22   * basic MIDI sequencer operations:
23   * <ul>
24   * <li>obtaining a sequence from MIDI file data</li>
25   * <li>starting and stopping playback</li>
26   * <li>moving to an arbitrary position in the sequence</li>
27   * <li>changing the tempo (speed) of playback</li>
28   * <li>synchronizing playback to an internal clock or to received MIDI
29   * messages</li>
30   * <li>controlling the timing of another device</li>
31   * </ul>
32   * In addition, the following operations are supported, either directly, or
33   * indirectly through objects that the <code>Sequencer</code> has access to:
34   * <ul>
35   * <li>editing the data by adding or deleting individual MIDI events or entire
36   * tracks</li>
37   * <li>muting or soloing individual tracks in the sequence</li>
38   * <li>notifying listener objects about any meta-events or
39   * control-change events encountered while playing back the sequence.</li>
40   * </ul>
41   *
42   * @see Sequencer.SyncMode
43   * @see #addMetaEventListener
44   * @see ControllerEventListener
45   * @see Receiver
46   * @see Transmitter
47   * @see MidiDevice
48   *
49   * @version 1.36, 03/12/19
50   * @author Kara Kytle
51   * @author Florian Bomers
52   */
53  public interface Sequencer extends MidiDevice   {
54  
55  
56      /**
57       * A value indicating that looping should continue
58       * indefinitely rather than complete after a specific
59       * number of loops.
60       *
61       * @see #setLoopCount
62       * @since 1.5
63       */
64      public static final int LOOP_CONTINUOUSLY = -1;
65  
66  
67  
68      /**
69       * Sets the current sequence on which the sequencer operates.
70       *
71       * <p>This method can be called even if the
72       * <code>Sequencer</code> is closed.
73       *
74       * @param sequence the sequence to be loaded.
75       * @throws InvalidMidiDataException if the sequence contains invalid
76       * MIDI data, or is not supported.
77       */
78      public void setSequence(Sequence   sequence) throws InvalidMidiDataException  ;
79  
80  
81      /**
82       * Sets the current sequence on which the sequencer operates.
83       * The stream must point to MIDI file data.
84       *
85       * <p>This method can be called even if the
86       * <code>Sequencer</code> is closed.
87       *
88       * @param stream stream containing MIDI file data.
89       * @throws IOException if an I/O exception occurs during reading of the stream.
90       * @throws InvalidMidiDataException if invalid data is encountered
91       * in the stream, or the stream is not supported.
92       */
93      public void setSequence(InputStream   stream) throws IOException  , InvalidMidiDataException  ;
94  
95  
96      /**
97       * Obtains the sequence on which the Sequencer is currently operating.
98       *
99       * <p>This method can be called even if the
100      * <code>Sequencer</code> is closed.
101      *
102      * @return the current sequence, or <code>null</code> if no sequence is currently set.
103      */
104     public Sequence   getSequence();
105 
106 
107     /**
108      * Starts playback of the MIDI data in the currently
109      * loaded sequence.
110      * Playback will begin from the current position.
111      * If the playback position reaches the loop end point,
112      * and the loop count is greater than 0, playback will
113      * resume at the loop start point for the number of
114      * repetitions set with <code>setLoopCount</code>.
115      * After that, or if the loop count is 0, playback will
116      * continue to play to the end of the sequence.
117      *
118      * <p>The implementation ensures that the synthesizer
119      * is brought to a consistent state when jumping
120      * to the loop start point by sending appropriate
121      * controllers, pitch bend, and program change events.
122      *
123      * @throws IllegalStateException if the <code>Sequencer</code> is
124      * closed.
125      *
126      * @see #setLoopStartPoint
127      * @see #setLoopEndPoint
128      * @see #setLoopCount
129      * @see #stop
130      */
131     public void start();
132 
133 
134     /**
135      * Stops recording, if active, and playback of the currently loaded sequence,
136      * if any.
137      *
138      * @throws IllegalStateException if the <code>Sequencer</code> is
139      * closed.
140      *
141      * @see #start
142      * @see #isRunning
143      */
144     public void stop();
145 
146 
147     /**
148      * Indicates whether the Sequencer is currently running.  The default is <code>false</code>.
149      * The Sequencer starts running when either <code>{@link #start}</code> or <code>{@link #startRecording}</code>
150      * is called.  <code>isRunning</code> then returns <code>true</code> until playback of the
151      * sequence completes or <code>{@link #stop}</code> is called.
152      * @return <code>true</code> if the Sequencer is running, otherwise <code>false</code>
153      */
154     public boolean isRunning();
155 
156 
157     /**
158      * Starts recording and playback of MIDI data.  Data is recorded to all enabled tracks,
159      * on the channel(s) for which they were enabled.  Recording begins at the current position
160      * of the sequencer.   Any events already in the track are overwritten for the duration
161      * of the recording session.  Events from the currently loaded sequence,
162      * if any, are delivered to the sequencer's transmitter(s) along with messages
163      * received during recording.
164      * <p>
165      * Note that tracks are not by default enabled for recording.  In order to record MIDI data,
166      * at least one track must be specifically enabled for recording.
167      *
168      * @throws IllegalStateException if the <code>Sequencer</code> is
169      * closed.
170      *
171      * @see #startRecording
172      * @see #recordEnable
173      * @see #recordDisable
174      */
175     public void startRecording();
176 
177 
178     /**
179      * Stops recording, if active.  Playback of the current sequence continues.
180      *
181      * @throws IllegalStateException if the <code>Sequencer</code> is
182      * closed.
183      *
184      * @see #startRecording
185      * @see #isRecording
186      */
187     public void stopRecording();
188 
189 
190     /**
191      * Indicates whether the Sequencer is currently recording.  The default is <code>false</code>.
192      * The Sequencer begins recording when <code>{@link #startRecording}</code> is called,
193      * and then returns <code>true</code> until <code>{@link #stop}</code> or <code>{@link #stopRecording}</code>
194      * is called.
195      * @return <code>true</code> if the Sequencer is recording, otherwise <code>false</code>
196      */
197     public boolean isRecording();
198 
199 
200     /**
201      * Prepares the specified track for recording events received on a particular channel.
202      * Once enabled, a track will receive events when recording is active.
203      * @param track the track to which events will be recorded
204      * @param channel the channel on which events will be received.  If -1 is specified
205      * for the channel value, the track will receive data from all channels.
206      * @throws IllegalArgumentException thrown if the track is not part of the current
207      * sequence.
208      */
209     public void recordEnable(Track   track, int channel);
210 
211 
212     /**
213      * Disables recording to the specified track.  Events will no longer be recorded
214      * into this track.
215      * @param track the track to disable for recording, or <code>null</code> to disable
216      * recording for all tracks.
217      */
218     public void recordDisable(Track   track);
219 
220 
221     /**
222      * Obtains the current tempo, expressed in beats per minute.  The
223      * actual tempo of playback is the product of the returned value
224      * and the tempo factor.
225      *
226      * @return the current tempo in beats per minute
227      *
228      * @see #getTempoFactor
229      * @see #setTempoInBPM(float)
230      * @see #getTempoInMPQ
231      */
232     public float getTempoInBPM();
233 
234 
235     /**
236      * Sets the tempo in beats per minute.   The actual tempo of playback
237      * is the product of the specified value and the tempo factor.
238      *
239      * @param bpm desired new tempo in beats per minute
240      * @see #getTempoFactor
241      * @see #setTempoInMPQ(float)
242      * @see #getTempoInBPM
243      */
244     public void setTempoInBPM(float bpm);
245 
246 
247     /**
248      * Obtains the current tempo, expressed in microseconds per quarter
249      * note.  The actual tempo of playback is the product of the returned
250      * value and the tempo factor.
251      *
252      * @return the current tempo in microseconds per quarter note
253      * @see #getTempoFactor
254      * @see #setTempoInMPQ(float)
255      * @see #getTempoInBPM
256      */
257     public float getTempoInMPQ();
258 
259 
260     /**
261      * Sets the tempo in microseconds per quarter note.  The actual tempo
262      * of playback is the product of the specified value and the tempo
263      * factor.
264      *
265      * @param mpq desired new tempo in microseconds per quarter note.
266      * @see #getTempoFactor
267      * @see #setTempoInBPM(float)
268      * @see #getTempoInMPQ
269      */
270     public void setTempoInMPQ(float mpq);
271 
272 
273     /**
274      * Scales the sequencer's actual playback tempo by the factor provided.
275      * The default is 1.0.  A value of 1.0 represents the natural rate (the
276      * tempo specified in the sequence), 2.0 means twice as fast, etc.
277      * The tempo factor does not affect the values returned by
278      * <code>{@link #getTempoInMPQ}</code> and <code>{@link #getTempoInBPM}</code>.
279      * Those values indicate the tempo prior to scaling.
280      * <p>
281      * Note that the tempo factor cannot be adjusted when external
282      * synchronization is used.  In that situation,
283      * <code>setTempoFactor</code> always sets the tempo factor to 1.0.
284      *
285      * @param factor the requested tempo scalar
286      * @see #getTempoFactor
287      */
288     public void setTempoFactor(float factor);
289 
290 
291     /**
292      * Returns the current tempo factor for the sequencer.  The default is
293      * 1.0.
294      *
295      * @return tempo factor.
296      * @see #setTempoFactor(float)
297      */
298     public float getTempoFactor();
299 
300 
301     /**
302      * Obtains the length of the current sequence, expressed in MIDI ticks,
303      * or 0 if no sequence is set.
304      * @return length of the sequence in ticks
305      */
306     public long getTickLength();
307 
308 
309     /**
310      * Obtains the current position in the sequence, expressed in MIDI
311      * ticks.  (The duration of a tick in seconds is determined both by
312      * the tempo and by the timing resolution stored in the
313      * <code>{@link Sequence}</code>.)
314      *
315      * @return current tick
316      * @see #setTickPosition
317      */
318     public long getTickPosition();
319 
320 
321     /**
322      * Sets the current sequencer position in MIDI ticks
323      * @param tick the desired tick position
324      * @see #getTickPosition
325      */
326     public void setTickPosition(long tick);
327 
328 
329     /**
330      * Obtains the length of the current sequence, expressed in microseconds,
331      * or 0 if no sequence is set.
332      * @return length of the sequence in microseconds.
333      */
334     public long getMicrosecondLength();
335 
336 
337     /**
338      * Obtains the current position in the sequence, expressed in
339      * microseconds.
340      * @return the current position in microseconds
341      * @see #setMicrosecondPosition
342      */
343     public long getMicrosecondPosition();
344 
345 
346     /**
347      * Sets the current position in the sequence, expressed in microseconds
348      * @param microseconds desired position in microseconds
349      * @see #getMicrosecondPosition
350      */
351     public void setMicrosecondPosition(long microseconds);
352 
353 
354     /**
355      * Sets the source of timing information used by this sequencer.
356      * The sequencer synchronizes to the master, which is the internal clock,
357      * MIDI clock, or MIDI time code, depending on the value of
358      * <code>sync</code>.  The <code>sync</code> argument must be one
359      * of the supported modes, as returned by
360      * <code>{@link #getMasterSyncModes}</code>.
361      *
362      * @param sync the desired master synchronization mode
363      *
364      * @see SyncMode#INTERNAL_CLOCK
365      * @see SyncMode#MIDI_SYNC
366      * @see SyncMode#MIDI_TIME_CODE
367      * @see #getMasterSyncMode
368      */
369     public void setMasterSyncMode(SyncMode sync);
370 
371 
372     /**
373      * Obtains the current master synchronization mode for this sequencer.
374      *
375      * @return the current master synchronization mode
376      *
377      * @see #setMasterSyncMode(Sequencer.SyncMode)
378      * @see #getMasterSyncModes
379      */
380     public SyncMode getMasterSyncMode();
381 
382 
383     /**
384      * Obtains the set of master synchronization modes supported by this
385      * sequencer.
386      *
387      * @return the available master synchronization modes
388      *
389      * @see SyncMode#INTERNAL_CLOCK
390      * @see SyncMode#MIDI_SYNC
391      * @see SyncMode#MIDI_TIME_CODE
392      * @see #getMasterSyncMode
393      * @see #setMasterSyncMode(Sequencer.SyncMode)
394      */
395     public SyncMode[] getMasterSyncModes();
396 
397 
398     /**
399      * Sets the slave synchronization mode for the sequencer.
400      * This indicates the type of timing information sent by the sequencer
401      * to its receiver.  The <code>sync</code> argument must be one
402      * of the supported modes, as returned by
403      * <code>{@link #getSlaveSyncModes}</code>.
404      *
405      * @param sync the desired slave synchronization mode
406      *
407      * @see SyncMode#MIDI_SYNC
408      * @see SyncMode#MIDI_TIME_CODE
409      * @see SyncMode#NO_SYNC
410      * @see #getSlaveSyncModes
411      */
412     public void setSlaveSyncMode(SyncMode sync);
413 
414 
415     /**
416      * Obtains the current slave synchronization mode for this sequencer.
417      *
418      * @return the current slave synchronization mode
419      *
420      * @see #setSlaveSyncMode(Sequencer.SyncMode)
421      * @see #getSlaveSyncModes
422      */
423     public SyncMode getSlaveSyncMode();
424 
425 
426     /**
427      * Obtains the set of slave synchronization modes supported by the sequencer.
428      *
429      * @return the available slave synchronization modes
430      *
431      * @see SyncMode#MIDI_SYNC
432      * @see SyncMode#MIDI_TIME_CODE
433      * @see SyncMode#NO_SYNC
434      */
435     public SyncMode[] getSlaveSyncModes();
436 
437 
438     /**
439      * Sets the mute state for a track.  This method may fail for a number
440      * of reasons.  For example, the track number specified may not be valid
441      * for the current sequence, or the sequencer may not support this functionality.
442      * An application which needs to verify whether this operation succeeded should
443      * follow this call with a call to <code>{@link #getTrackMute}</code>.
444      *
445      * @param track the track number.  Tracks in the current sequence are numbered
446      * from 0 to the number of tracks in the sequence minus 1.
447      * @param mute the new mute state for the track.  <code>true</code> implies the
448      * track should be muted, <code>false</code> implies the track should be unmuted.
449      * @see #getSequence
450      */
451     public void setTrackMute(int track, boolean mute);
452 
453 
454     /**
455      * Obtains the current mute state for a track.  The default mute
456      * state for all tracks which have not been muted is false.  In any
457      * case where the specified track has not been muted, this method should
458      * return false.  This applies if the sequencer does not support muting
459      * of tracks, and if the specified track index is not valid.
460      *
461      * @param track the track number.  Tracks in the current sequence are numbered
462      * from 0 to the number of tracks in the sequence minus 1.
463      * @return <code>true</code> if muted, <code>false</code> if not.
464      */
465     public boolean getTrackMute(int track);
466 
467     /**
468      * Sets the solo state for a track.  If <code>solo</code> is <code>true</code>
469      * only this track and other solo'd tracks will sound. If <code>solo</code>
470      * is <code>false</code> then only other solo'd tracks will sound, unless no
471      * tracks are solo'd in which case all un-muted tracks will sound.
472      * <p>
473      * This method may fail for a number
474      * of reasons.  For example, the track number specified may not be valid
475      * for the current sequence, or the sequencer may not support this functionality.
476      * An application which needs to verify whether this operation succeeded should
477      * follow this call with a call to <code>{@link #getTrackSolo}</code>.
478      *
479      * @param track the track number.  Tracks in the current sequence are numbered
480      * from 0 to the number of tracks in the sequence minus 1.
481      * @param solo the new solo state for the track.  <code>true</code> implies the
482      * track should be solo'd, <code>false</code> implies the track should not be solo'd.
483      * @see #getSequence
484      */
485     public void setTrackSolo(int track, boolean solo);
486 
487 
488     /**
489      * Obtains the current solo state for a track.  The default mute
490      * state for all tracks which have not been solo'd is false.  In any
491      * case where the specified track has not been solo'd, this method should
492      * return false.  This applies if the sequencer does not support soloing
493      * of tracks, and if the specified track index is not valid.
494      *
495      * @param track the track number.  Tracks in the current sequence are numbered
496      * from 0 to the number of tracks in the sequence minus 1.
497      * @return <code>true</code> if solo'd, <code>false</code> if not.
498      */
499     public boolean getTrackSolo(int track);
500 
501 
502     /**
503      * Registers a meta-event listener to receive
504      * notification whenever a meta-event is encountered in the sequence
505      * and processed by the sequencer. This method can fail if, for
506      * instance,this class of sequencer does not support meta-event
507      * notification.
508      *
509      * @param listener listener to add
510      * @return <code>true</code> if the listener was successfully added,
511      * otherwise <code>false</code>
512      *
513      * @see #removeMetaEventListener
514      * @see MetaEventListener
515      * @see MetaMessage
516      */
517     public boolean addMetaEventListener(MetaEventListener   listener);
518 
519 
520     /**
521      * Removes the specified meta-event listener from this sequencer's
522      * list of registered listeners, if in fact the listener is registered.
523      *
524      * @param listener the meta-event listener to remove
525      * @see #addMetaEventListener
526      */
527     public void removeMetaEventListener(MetaEventListener   listener);
528 
529 
530     /**
531      * Registers a controller event listener to receive notification
532      * whenever the sequencer processes a control-change event of the
533      * requested type or types.  The types are specified by the
534      * <code>controllers</code> argument, which should contain an array of
535      * MIDI controller numbers.  (Each number should be between 0 and 127,
536      * inclusive.  See the MIDI 1.0 Specification for the numbers that
537      * correspond to various types of controllers.)
538      * <p>
539      * The returned array contains the MIDI controller
540      * numbers for which the listener will now receive events.
541      * Some sequencers might not support controller event notification, in
542      * which case the array has a length of 0.  Other sequencers might
543      * support notification for some controllers but not all.
544      * This method may be invoked repeatedly.
545      * Each time, the returned array indicates all the controllers
546      * that the listener will be notified about, not only the controllers
547      * requested in that particular invocation.
548      *
549      * @param listener the controller event listener to add to the list of
550      * registered listeners
551      * @param controllers the MIDI controller numbers for which change
552      * notification is requested
553      * @return the numbers of all the MIDI controllers whose changes will
554      * now be reported to the specified listener
555      *
556      * @see #removeControllerEventListener
557      * @see ControllerEventListener
558      */
559     public int[] addControllerEventListener(ControllerEventListener   listener, int[] controllers);
560 
561 
562     /**
563      * Removes a controller event listener's interest in one or more
564      * types of controller event. The <code>controllers</code> argument
565      * is an array of MIDI numbers corresponding to the  controllers for
566      * which the listener should no longer receive change notifications.
567      * To completely remove this listener from the list of registered
568      * listeners, pass in <code>null</code> for <code>controllers</code>.
569      * The returned array contains the MIDI controller
570      * numbers for which the listener will now receive events.  The
571      * array has a length of 0 if the listener will not receive
572      * change notifications for any controllers.
573      *
574      * @param listener old listener
575      * @param controllers the MIDI controller numbers for which change
576      * notification should be cancelled, or <code>null</code> to cancel
577      * for all controllers
578      * @return the numbers of all the MIDI controllers whose changes will
579      * now be reported to the specified listener
580      *
581      * @see #addControllerEventListener
582      */
583     public int[] removeControllerEventListener(ControllerEventListener   listener, int[] controllers);
584 
585 
586     /**
587      * Sets the first MIDI tick that will be
588      * played in the loop. If the loop count is
589      * greater than 0, playback will jump to this
590      * point when reaching the loop end point.
591      *
592      * <p>A value of 0 for the starting point means the
593      * beginning of the loaded sequence. The starting
594      * point must be lower than or equal to the ending
595      * point, and it must fall within the size of the
596      * loaded sequence.
597      *
598      * <p>A sequencer's loop start point defaults to
599      * start of the sequence.
600      *
601      * @param tick the loop's starting position,
602      *        in MIDI ticks (zero-based)
603      * @throws IllegalArgumentException if the requested
604      *         loop start point cannot be set, usually because
605      *         it falls outside the sequence's
606      *         duration or because the start point is
607      *         after the end point
608      *
609      * @see #setLoopEndPoint
610      * @see #setLoopCount
611      * @see #getLoopStartPoint
612      * @see #start
613      * @since 1.5
614      */
615     public void setLoopStartPoint(long tick);
616 
617 
618     /**
619      * Obtains the start position of the loop,
620      * in MIDI ticks.
621      *
622      * @return the start position of the loop,
623                in MIDI ticks (zero-based)
624      * @see #setLoopStartPoint
625      * @since 1.5
626      */
627     public long getLoopStartPoint();
628 
629 
630     /**
631      * Sets the last MIDI tick that will be played in
632      * the loop. If the loop count is 0, the loop end
633      * point has no effect and playback continues to
634      * play when reaching the loop end point.
635      *
636      * <p>A value of -1 for the ending point
637      * indicates the last tick of the sequence.
638      * Otherwise, the ending point must be greater
639      * than or equal to the starting point, and it must
640      * fall within the size of the loaded sequence.
641      *
642      * <p>A sequencer's loop end point defaults to -1,
643      * meaning the end of the sequence.
644      *
645      * @param tick the loop's ending position,
646      *        in MIDI ticks (zero-based), or
647      *        -1 to indicate the final tick
648      * @throws IllegalArgumentException if the requested
649      *         loop point cannot be set, usually because
650      *         it falls outside the sequence's
651      *         duration or because the ending point is
652      *         before the starting point
653      *
654      * @see #setLoopStartPoint
655      * @see #setLoopCount
656      * @see #getLoopEndPoint
657      * @see #start
658      * @since 1.5
659      */
660     public void setLoopEndPoint(long tick);
661 
662 
663     /**
664      * Obtains the end position of the loop,
665      * in MIDI ticks.
666      *
667      * @return the end position of the loop, in MIDI
668      *         ticks (zero-based), or -1 to indicate
669      *         the end of the sequence
670      * @see #setLoopEndPoint
671      * @since 1.5
672      */
673     public long getLoopEndPoint();
674 
675 
676     /**
677      * Sets the number of repetitions of the loop for
678      * playback.
679      * When the playback position reaches the loop end point,
680      * it will loop back to the loop start point
681      * <code>count</code> times, after which playback will
682      * continue to play to the end of the sequence.
683      * <p>
684      * If the current position when this method is invoked
685      * is greater than the loop end point, playback
686      * continues to the end of the sequence without looping,
687      * unless the loop end point is changed subsequently.
688      * <p>
689      * A <code>count</code> value of 0 disables looping:
690      * playback will continue at the loop end point, and it
691      * will not loop back to the loop start point.
692      * This is a sequencer's default.
693      *
694      * <p>If playback is stopped during looping, the
695      * current loop status is cleared; subsequent start
696      * requests are not affected by an interrupted loop
697      * operation.
698      *
699      * @param count the number of times playback should
700      *        loop back from the loop's end position
701      *        to the loop's start position, or
702      *        <code>{@link #LOOP_CONTINUOUSLY}</code>
703      *        to indicate that looping should
704      *        continue until interrupted
705      *
706      * @throws IllegalArgumentException if <code>count</code> is
707      * negative and not equal to {@link #LOOP_CONTINUOUSLY}
708      *
709      * @see #setLoopStartPoint
710      * @see #setLoopEndPoint
711      * @see #getLoopCount
712      * @see #start
713      * @since 1.5
714      */
715     public void setLoopCount(int count);
716 
717 
718     /**
719      * Obtains the number of repetitions for
720      * playback.
721      *
722      * @return the number of loops after which
723      *         playback plays to the end of the
724      *         sequence
725      * @see #setLoopCount
726      * @see #start
727      * @since 1.5
728      */
729     public int getLoopCount();
730 
731     /**
732      * A <code>SyncMode</code> object represents one of the ways in which
733      * a MIDI sequencer's notion of time can be synchronized with a master
734      * or slave device.
735      * If the sequencer is being synchronized to a master, the
736      * sequencer revises its current time in response to messages from
737      * the master.  If the sequencer has a slave, the sequencer
738      * similarly sends messages to control the slave's timing.
739      * <p>
740      * There are three predefined modes that specify possible masters
741      * for a sequencer: <code>INTERNAL_CLOCK</code>,
742      * <code>MIDI_SYNC</code>, and <code>MIDI_TIME_CODE</code>.  The
743      * latter two work if the sequencer receives MIDI messages from
744      * another device.  In these two modes, the sequencer's time gets reset
745      * based on system real-time timing clock messages or MIDI time code
746      * (MTC) messages, respectively.  These two modes can also be used
747      * as slave modes, in which case the sequencer sends the corresponding
748      * types of MIDI messages to its receiver (whether or not the sequencer
749      * is also receiving them from a master).  A fourth mode,
750      * <code>NO_SYNC</code>, is used to indicate that the sequencer should
751      * not control its receiver's timing.
752      *
753      * @see Sequencer#setMasterSyncMode(Sequencer.SyncMode)
754      * @see Sequencer#setSlaveSyncMode(Sequencer.SyncMode)
755      */
756     public static class SyncMode {
757 
758     /**
759      * Synchronization mode name.
760      */
761     private String   name;
762 
763     /**
764      * Constructs a synchronization mode.
765      * @param name name of the synchronization mode
766      */
767     protected SyncMode(String   name) {
768 
769         this.name = name;
770     }
771 
772 
773     /**
774      * Determines whether two objects are equal.
775      * Returns <code>true</code> if the objects are identical
776      * @param obj the reference object with which to compare
777      * @return <code>true</code> if this object is the same as the
778      * <code>obj</code> argument, <code>false</code> otherwise
779      */
780     public final boolean equals(Object   obj) {
781 
782         return super.equals(obj);
783     }
784 
785 
786     /**
787      * Finalizes the hashcode method.
788      */
789     public final int hashCode() {
790 
791         return super.hashCode();
792     }
793 
794 
795     /**
796      * Provides this synchronization mode's name as the string
797      * representation of the mode.
798      * @return the name of this synchronization mode
799      */
800     public final String   toString() {
801 
802         return name;
803     }
804 
805 
806     /**
807      * A master synchronization mode that makes the sequencer get
808      * its timing information from its internal clock.  This is not
809      * a legal slave sync mode.
810      */
811     public static final SyncMode INTERNAL_CLOCK     = new SyncMode("Internal Clock");
812 
813 
814     /**
815      * A master or slave synchronization mode that specifies the
816      * use of MIDI clock
817      * messages.  If this mode is used as the master sync mode,
818      * the sequencer gets its timing information from system real-time
819      * MIDI clock messages.  This mode only applies as the master sync
820      * mode for sequencers that are also MIDI receivers.  If this is the
821      * slave sync mode, the sequencer sends system real-time MIDI clock
822      * messages to its receiver.  MIDI clock messages are sent at a rate
823      * of 24 per quarter note.
824      */
825     public static final SyncMode MIDI_SYNC          = new SyncMode("MIDI Sync");
826 
827 
828     /**
829      * A master or slave synchronization mode that specifies the
830      * use of MIDI Time Code.
831      * If this mode is used as the master sync mode,
832      * the sequencer gets its timing information from MIDI Time Code
833      * messages.  This mode only applies as the master sync
834      * mode to sequencers that are also MIDI receivers.  If this
835      * mode is used as the
836      * slave sync mode, the sequencer sends MIDI Time Code
837      * messages to its receiver.  (See the MIDI 1.0 Detailed
838      * Specification for a description of MIDI Time Code.)
839      */
840     public static final SyncMode MIDI_TIME_CODE     = new SyncMode("MIDI Time Code");
841 
842 
843     /**
844      * A slave synchronization mode indicating that no timing information
845      * should be sent to the receiver.  This is not a legal master sync
846      * mode.
847      */
848     public static final SyncMode NO_SYNC                = new SyncMode("No Timing");
849 
850     } // class SyncMode
851 }
852
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags