001/* Sequencer.java -- A MIDI sequencer object
002   Copyright (C) 2005 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.sound.midi;
040
041import java.io.IOException;
042import 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 */
053public 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}