libjava/classpath/javax/sound/midi/Sequencer.java

   1 /* Sequencer.java -- A MIDI sequencer object
   2    Copyright (C) 2005 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.sound.midi;
  40
  41 import java.io.IOException;
  42 import java.io.InputStream;
  43
  44 /**
  45  * A Sequencer object plays MIDI sequences described as Sequence objects.
  46  * This class provides methods for loading and unloading sequences, as well
  47  * as basic transport controls.
  48  *
  49  * @author Anthony Green (green@redhat.com)
  50  * @since 1.3
  51  *
  52  */
  53 public interface Sequencer extends MidiDevice
  54 {
  55   /**
  56    * Set the Sequence object for this sequencer.
  57    *
  58    * @param seq the Sequence to process
  59    * @throws InvalidMidiDataException if the sequence is invalid for any reason
  60    */
  61   public void setSequence(Sequence seq) throws InvalidMidiDataException;
  62
  63   /**
  64    * Set the sequence for this sequencer.  istream reads on a valid MIDI file.
  65    *
  66    * @param istream an input stream for a valid MIDI file
  67    * @throws IOException if an I/O exception happens
  68    * @throws InvalidMidiDataException if the MIDI file contains bad data
  69    */
  70   public void setSequence(InputStream istream)
  71       throws IOException, InvalidMidiDataException;
  72
  73   /**
  74    * Get the current sequence object for this sequencer.
  75    *
  76    * @return the current sequence object.  May be null.
  77    */
  78   public Sequence getSequence();
  79
  80   /**
  81    * Start playback of the current sequence.
  82    */
  83   public void start();
  84
  85   /**
  86    * Stop playback of the current sequence.
  87    */
  88   public void stop();
  89
  90   /**
  91    * Returns true if the sequence is playing.
  92    *
  93    * @return true if the sequence is playing and false otherwise
  94    */
  95   public boolean isRunning();
  96
  97   /**
  98    * Start playback and record of MIDI events.
  99    * 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 }