001 /* Sequencer.java -- A MIDI sequencer object
002 Copyright (C) 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package javax.sound.midi;
040
041 import java.io.IOException;
042 import java.io.InputStream;
043
044 /**
045 * A Sequencer object plays MIDI sequences described as Sequence objects.
046 * This class provides methods for loading and unloading sequences, as well
047 * as basic transport controls.
048 *
049 * @author Anthony Green (green@redhat.com)
050 * @since 1.3
051 *
052 */
053 public interface Sequencer extends MidiDevice
054 {
055 /**
056 * Set the Sequence object for this sequencer.
057 *
058 * @param seq the Sequence to process
059 * @throws InvalidMidiDataException if the sequence is invalid for any reason
060 */
061 public void setSequence(Sequence seq) throws InvalidMidiDataException;
062
063 /**
064 * Set the sequence for this sequencer. istream reads on a valid MIDI file.
065 *
066 * @param istream an input stream for a valid MIDI file
067 * @throws IOException if an I/O exception happens
068 * @throws InvalidMidiDataException if the MIDI file contains bad data
069 */
070 public void setSequence(InputStream istream)
071 throws IOException, InvalidMidiDataException;
072
073 /**
074 * Get the current sequence object for this sequencer.
075 *
076 * @return the current sequence object. May be null.
077 */
078 public Sequence getSequence();
079
080 /**
081 * Start playback of the current sequence.
082 */
083 public void start();
084
085 /**
086 * Stop playback of the current sequence.
087 */
088 public void stop();
089
090 /**
091 * Returns true if the sequence is playing.
092 *
093 * @return true if the sequence is playing and false otherwise
094 */
095 public boolean isRunning();
096
097 /**
098 * Start playback and record of MIDI events.
099 * Any tracks enabled for recording will have their events replaced.
100 * Any newly recorded events, and all events from non-recording tracks
101 * will be sent to the sequencer's transmitter.
102 */
103 public void startRecording();
104
105 /**
106 * Stop recording, although continue playing.
107 */
108 public void stopRecording();
109
110 /**
111 * Returns true if sequence is recording.
112 *
113 * @return true if the sequence is recording and false otherwise
114 */
115 public boolean isRecording();
116
117 /**
118 * Enable recording for a specific track using data from a specific channel.
119 *
120 * @param track the track to enable for recording
121 * @param channel the channel from which to record
122 */
123 public void recordEnable(Track track, int channel);
124
125 /**
126 * Disable recording for a specific track.
127 *
128 * @param track the track to disable recording for
129 */
130 public void recordDisable(Track track);
131
132 /**
133 * Get the current tempo in beats per minute.
134 *
135 * @return the current tempo in beats per minute
136 */
137 public float getTempoInBPM();
138
139 /**
140 * Sets the current tempo in beats per minute.
141 *
142 * @param bpm the new tempo in bears per minutes
143 */
144 public void setTempoInBPM(float bpm);
145
146 /**
147 * Get the current tempo in microseconds per quarter note.
148 *
149 * @return the current tempo in microseconds per quarter note.
150 */
151 public float getTempoInMPQ();
152
153 /**
154 * Sets the current tempo in microseconds per quarter note.
155 *
156 * @param mpq the new tempo in microseconds per quarter note.
157 */
158 public void setTempoInMPQ(float mpq);
159
160 /**
161 * Set a scaling factor for the playback tempo, which is 1.0 by default.
162 *
163 * @param factor the new tempo scaling factor
164 */
165 public void setTempoFactor(float factor);
166
167 /**
168 * Get the current scaling factor for the playback tempo.
169 *
170 * @return the current tempo scaling factor
171 */
172 public float getTempoFactor();
173
174 /**
175 * Get the length of the current sequence in MIDI ticks.
176 *
177 * @return the length of the current sequence in MIDI ticks
178 */
179 public long getTickLength();
180
181 /**
182 * Get the current playback position of the sequencer in MIDI ticks.
183 *
184 * @return the current playback position of the sequencer in MIDI ticks
185 */
186 public long getTickPosition();
187
188 /**
189 * Set the current playback position of the sequencer in MIDI ticks.
190 *
191 * @param tick the new playback position of the sequencer in MIDI ticks
192 */
193 public void setTickPosition(long tick);
194
195 /**
196 * Get the length of the current sequence in microseconds.
197 *
198 * @return the length of the current sequence in microseconds
199 */
200 public long getMicrosecondLength();
201
202 /**
203 * Get the current playback position of the sequencer in microseconds.
204 *
205 * @return the current playback position of the sequencer in microseconds
206 */
207 public long getMicrosecondPosition();
208
209 /**
210 * Set the current playback position of the sequencer in microseconds.
211 *
212 * @param microsecond the new playback position of the sequencer in microseconds
213 */
214 public void setMicrosecondPosition(long microsecond);
215
216 /**
217 * Set the source of timing information. sync must be found in the array
218 * returned by getMasterSyncModes().
219 * FIXME: What happens if it isn't?
220 *
221 * @param sync the new source of timing information
222 */
223 public void setMasterSyncMode(SyncMode sync);
224
225 /**
226 * Get the source of timing information.
227 *
228 * @return the current source of timing information
229 */
230 public SyncMode getMasterSyncMode();
231
232 /**
233 * Get an array of timing sources supported by this sequencer.
234 *
235 * @return an array of timing sources supported by this sequencer
236 */
237 public SyncMode[] getMasterSyncModes();
238
239 /**
240 * Set the slave synchronization mode for this sequencer. sync must be
241 * found in the array returned by getSlaveSyncModes().
242 * FIXME: What happens if it isn't?
243 *
244 * @param sync the new slave sync mode for this sequencer
245 */
246 public void setSlaveSyncMode(SyncMode sync);
247
248 /**
249 * Get the current slave synchronization mode.
250 *
251 * @return the current slave synchronization mode
252 */
253 public SyncMode getSlaveSyncMode();
254
255 /**
256 * Get an array of slave sync modes supported by this sequencer.
257 *
258 * @return an array of slave sync modes supported by this sequencer
259 */
260 public SyncMode[] getSlaveSyncModes();
261
262 /**
263 * Sets the mute state for a specific track.
264 *
265 * @param track the track to modify
266 * @param mute the new mute state
267 */
268 public void setTrackMute(int track, boolean mute);
269
270 /**
271 * Get the mute state of a specific track.
272 *
273 * @param track the track to query
274 * @return the mute state for track
275 */
276 public boolean getTrackMute(int track);
277
278 /**
279 * Sets the solo state for a specific track.
280 *
281 * @param track the track to modify
282 * @param solo the new solo state
283 */
284 public void setTrackSolo(int track, boolean solo);
285
286 /**
287 * Get the solo state for a specific track.
288 *
289 * @param track the track to query
290 * @return the solo state for track
291 */
292 public boolean getTrackSolo(int track);
293
294 /**
295 * Add a meta event listening object to this sequencer. It will receive
296 * notification whenever the sequencer processes a meta event.
297 * A listener may fail to get added if this sequencer doesn't support
298 * meta events.
299 *
300 * @param listener the listener to add
301 * @return true if listener was added, false othewise
302 */
303 public boolean addMetaEventListener(MetaEventListener listener);
304
305 /**
306 * Remove a meta event listener from this sequencer.
307 *
308 * @param listener the listener to remove
309 */
310 public void removeMetaEventListener(MetaEventListener listener);
311
312 /**
313 * Add a controller event listening object to this sequencer. It will
314 * receive notification whenever the sequencer processes a controller
315 * event for a specified controller number..
316 *
317 * @param listener the listener to add
318 * @param controllers the conroller numbers to listen to
319 * @return the controller numbers being listened to
320 */
321 public int[] addControllerEventListener(ControllerEventListener listener,
322 int controllers[]);
323
324 /**
325 * Remove a controller listener from this sequencer for the specified
326 * controller numbers.
327 *
328 * @param listener the listener to remove
329 * @param controllers the controllers to unlisten
330 * @return the controller numbers being unlistened
331 */
332 public int[] removeControllerEventListener(ControllerEventListener listener,
333 int controllers[]);
334
335 /**
336 * A SyncMode object represents the mechanism by which a MIDI sequencer
337 * synchronizes time with a master or slave device.
338 *
339 * @author green@redhat.com
340 *
341 */
342 public static class SyncMode
343 {
344 /**
345 * A master sync mode indicating the use of an internal sequencer clock.
346 */
347 public static final SyncMode INTERNAL_CLOCK = new SyncMode("Internal Clock");
348
349 /**
350 * A master or slave sync mode indicating the use of MIDI clock messages.
351 */
352 public static final SyncMode MIDI_SYNC = new SyncMode("MIDI Sync");
353
354 /**
355 * A master or slave sync mode indicating the use of MIDI Time Code
356 * messages.
357 */
358 public static final SyncMode MIDI_TIME_CODE = new SyncMode("MIDI Time Code");
359
360 /**
361 * A slave sync mode indicating that no timing info will be transmitted.
362 */
363 public static final SyncMode NO_SYNC = new SyncMode("No Timing");
364
365 // The name
366 private String name;
367
368 /**
369 * Create a new SyncMode object
370 * @param name the SyncMode name
371 */
372 protected SyncMode(String name)
373 {
374 this.name = name;
375 }
376
377 /**
378 * SyncMode objects are only equal when identical.
379 */
380 public final boolean equals(Object o)
381 {
382 return super.equals(o);
383 }
384
385 /**
386 * SyncMode objects use the Object hashCode.
387 */
388 public final int hashCode()
389 {
390 return super.hashCode();
391 }
392
393 /**
394 * Use the SyncMode name as the string representation.
395 * @see java.lang.Object#toString()
396 */
397 public final String toString()
398 {
399 return name;
400 }
401 }
402 }