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