Source for javax.sound.midi.Sequencer

   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: }