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    }