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}