Synthesizer


1   /*
2    * @(#)Synthesizer.java 1.27 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.sound.midi;            
9   
10  import javax.sound.sampled.Control  ;
11  
12  
13  /**
14   * A <code>Synthesizer</code> generates sound.  This usually happens when one of 
15   * the <code>Synthesizer</code>'s {@link MidiChannel} objects receives a 
16   * {@link MidiChannel#noteOn(int, int) noteOn} message, either
17   * directly or via the <code>Synthesizer</code> object.
18   * Many <code>Synthesizer</code>s support <code>Receivers</code>, through which
19   * MIDI events can be delivered to the <code>Synthesizer</code>.  
20   * In such cases, the <code>Synthesizer</code> typically responds by sending
21   * a corresponding message to the appropriate <code>MidiChannel</code>, or by
22   * processing the event itself if the event isn't one of the MIDI channel 
23   * messages.
24   * <p>
25   * The <code>Synthesizer</code> interface includes methods for loading and 
26   * unloading instruments from soundbanks.  An instrument is a specification for synthesizing a
27   * certain type of sound, whether that sound emulates a traditional instrument or is
28   * some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized
29   * by bank and program number (via the instrument's <code>Patch</code> object).  
30   * Different <code>Synthesizer</code> classes might implement different sound-synthesis
31   * techniques, meaning that some instruments and not others might be compatible with a
32   * given synthesizer.
33   * Also, synthesizers may have a limited amount of memory for instruments, meaning
34   * that not every soundbank and instrument can be used by every synthesizer, even if
35   * the synthesis technique is compatible.
36   * To see whether the instruments from 
37   * a certain soundbank can be played by a given synthesizer, invoke the
38   * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} method of 
39   * <code>Synthesizer</code>.
40   * <p>
41   * "Loading" an instrument means that that instrument becomes available for 
42   * synthesizing notes.  The instrument is loaded into the bank and 
43   * program location specified by its <code>Patch</code> object.  Loading does
44   * not necessarily mean that subsequently played notes will immediately have 
45   * the sound of this newly loaded instrument.  For the instrument to play notes, 
46   * one of the synthesizer's <code>MidiChannel</code> objects must receive (or have received)
47   * a program-change message that causes that particular instrument's
48   * bank and program number to be selected.
49   *
50   * @see MidiSystem#getSynthesizer
51   * @see Soundbank
52   * @see Instrument
53   * @see MidiChannel#programChange(int, int)
54   * @see Receiver
55   * @see Transmitter
56   * @see MidiDevice
57   *
58   * @version 1.27, 03/12/19
59   * @author Kara Kytle
60   */
61  public interface Synthesizer extends MidiDevice   {
62  
63  
64      // SYNTHESIZER METHODS
65  
66  
67      /**
68       * Obtains the maximum number of notes that this synthesizer can sound simultaneously.
69       * @return the maximum number of simultaneous notes
70       * @see #getVoiceStatus
71       */
72      public int getMaxPolyphony();
73  
74  
75      /**
76       * Obtains the processing latency incurred by this synthesizer, expressed in 
77       * microseconds.  This latency measures the worst-case delay between the  
78       * time a MIDI message is delivered to the synthesizer and the time that the
79       * synthesizer actually produces the corresponding result.
80       * <p>
81       * Although the latency is expressed in microseconds, a synthesizer's actual measured 
82       * delay may vary over a wider range than this resolution suggests.  For example,
83       * a synthesizer might have a worst-case delay of a few milliseconds or more.
84       *
85       * @return the worst-case delay, in microseconds
86       */
87      public long getLatency();   
88  
89      
90      /**
91       * Obtains the set of MIDI channels controlled by this synthesizer.  Each 
92       * non-null element in the returned array is a <code>MidiChannel</code> that 
93       * receives the MIDI messages sent on that channel number.
94       * <p>
95       * The MIDI 1.0 specification provides for 16 channels, so this 
96       * method returns an array of at least 16 elements.  However, if this synthesizer 
97       * doesn't make use of all 16 channels, some of the elements of the array
98       * might be <code>null</code>, so you should check each element
99       * before using it.
100      * @return an array of the <code>MidiChannel</code> objects managed by this
101      * <code>Synthesizer</code>.  Some of the array elements may be <code>null</code>.
102      */
103     public MidiChannel  [] getChannels();
104 
105 
106     /**
107      * Obtains the current status of the voices produced by this synthesizer.  
108      * If this class of <code>Synthesizer</code> does not provide voice 
109      * information, the returned array will always be of length 0.  Otherwise,
110      * its length is always equal to the total number of voices, as returned by 
111      * <code>getMaxPolyphony()</code>.  (See the <code>VoiceStatus</code> class 
112      * description for an explanation of synthesizer voices.)
113      *
114      * @return an array of <code>VoiceStatus</code> objects that supply 
115      * information about the corresponding synthesizer voices
116      * @see #getMaxPolyphony
117      * @see VoiceStatus
118      */
119     public VoiceStatus  [] getVoiceStatus();
120 
121 
122     /**
123      * Informs the caller whether this synthesizer is capable of loading 
124      * instruments from the specified soundbank.
125      * If the soundbank is unsupported, any attempts to load instruments from
126      * it will result in an <code>IllegalArgumentException</code>.
127      * @param soundbank soundbank for which support is queried
128      * @return <code>true</code> if the soundbank is supported, otherwise <code>false</code>
129      * @see #loadInstruments
130      * @see #loadAllInstruments
131      * @see #unloadInstruments
132      * @see #unloadAllInstruments
133      * @see #getDefaultSoundbank
134      */
135     public boolean isSoundbankSupported(Soundbank   soundbank);
136 
137 
138     /**
139      * Makes a particular instrument available for synthesis.  This instrument
140      * is loaded into the patch location specified by its <code>Patch</code> 
141      * object, so that if a program-change message is 
142      * received (or has been received) that causes that patch to be selected,
143      * subsequent notes will be played using the sound of 
144      * <code>instrument</code>.  If the specified instrument is already loaded,
145      * this method does nothing and returns <code>true</code>.
146      * <p>
147      * The instrument must be part of a soundbank 
148      * that this <code>Synthesizer</code> supports.  (To make sure, you can use
149      * the <code>getSoundbank</code> method of <code>Instrument</code> and the 
150      * <code>isSoundbankSupported</code> method of <code>Synthesizer</code>.)
151      * @param instrument instrument to load
152      * @return <code>true</code> if the instrument is successfully loaded (or 
153      * already had been), <code>false</code> if the instrument could not be 
154      * loaded (for example, if the synthesizer has insufficient
155      * memory to load it)
156      * @throws <code>IllegalArgumentException</code> if this 
157      * <code>Synthesizer</code> doesn't support the specified instrument's 
158      * soundbank 
159      * @see #unloadInstrument    
160      * @see #loadInstruments     
161      * @see #loadAllInstruments  
162      * @see #remapInstrument
163      * @see SoundbankResource#getSoundbank   
164      * @see MidiChannel#programChange(int, int)
165      */
166     public boolean loadInstrument(Instrument   instrument);
167 
168     
169     /**
170      * Unloads a particular instrument.
171      * @param instrument instrument to unload
172      * @throws <code>IllegalArgumentException</code> if this 
173      * <code>Synthesizer</code> doesn't support the specified instrument's 
174      * soundbank 
175      * @see #loadInstrument  
176      * @see #unloadInstruments   
177      * @see #unloadAllInstruments    
178      * @see #getLoadedInstruments
179      * @see #remapInstrument     
180      */
181     public void unloadInstrument(Instrument   instrument);
182 
183 
184     /**
185      * Remaps an instrument.  Instrument <code>to</code> takes the 
186      * place of instrument <code>from</code>.
187      * For example, if <code>from</code> was located at bank number 2,
188      * program number 11, remapping causes
189      * that bank and program location to be occupied instead by 
190      * <code>to</code>.  Instrument <code>from</code> is unloaded.
191      * 
192      * @param from instrument to be replaced
193      * @param to new instrument to be used in place of the old instrument
194      * @return <code>true</code> if the instrument could be remapped, 
195      * <code>false</code> otherwise
196      * @throws <code>IllegalArgumentException</code> if the soundbank is not supported
197      */
198     public boolean remapInstrument(Instrument   from, Instrument   to); 
199 
200     
201     /**
202      * Obtains the default soundbank for the synthesizer, if one exists.
203      * (Some synthesizers provide a default or built-in soundbank.)
204      * If a synthesizer doesn't have a default soundbank, instruments must
205      * be loaded explicitly from an external soundbank.  
206      * @return default soundbank, or <code>null</code> if one does not exist.
207      * @see #isSoundbankSupported
208      */
209     public Soundbank   getDefaultSoundbank();
210 
211     
212     /**
213      * Obtains a list of instruments that come with the synthesizer.  These
214      * instruments might be built into the synthesizer, or they might be
215      * part of a default soundbank provided with the synthesizer, etc.
216      * <p>  
217      * Note that you don't use this method  to find out which instruments are 
218      * currently loaded onto the synthesizer; for that purpose, you use 
219      * <code>getLoadedInstruments()</code>.
220      * Nor does the method indicate all the instruments that can be loaded onto
221      * the synthesizer; it only indicates the subset that come with the synthesizer.
222      * To learn whether another instrument can be loaded, you can invoke 
223      * <code>isSoundbankSupported()</code>, and if the instrument's 
224      * <code>Soundbank</code> is supported, you can try loading the instrument.
225      *  
226      * @return list of available instruments.
227      * @see #getLoadedInstruments    
228      * @see #isSoundbankSupported(Soundbank)
229      * @see #loadInstrument  
230      */
231     public Instrument  [] getAvailableInstruments();
232 
233 
234     /**
235      * Obtains a list of the instruments that are currently loaded onto this 
236      * <code>Synthesizer</code>.
237      * @return a list of currently loaded instruments
238      * @see #loadInstrument  
239      * @see #getAvailableInstruments     
240      * @see Soundbank#getInstruments     
241      */
242     public Instrument  [] getLoadedInstruments();
243 
244     
245     /**
246      * Loads onto the <code>Synthesizer</code> all instruments contained 
247      * in the specified <code>Soundbank</code>.
248      * @param soundbank the <code>Soundbank</code> whose are instruments are 
249      * to be loaded
250      * @return <code>true</code> if the instruments are all successfully loaded (or 
251      * already had been), <code>false</code> if any instrument could not be 
252      * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)
253      * @throws IllegalArgumentException if the requested soundbank is 
254      * incompatible with this synthesizer.
255      * @see #isSoundbankSupported
256      * @see #loadInstrument  
257      * @see #loadInstruments     
258      */
259     public boolean loadAllInstruments(Soundbank   soundbank);
260 
261 
262     
263     /**
264      * Unloads all instruments contained in the specified <code>Soundbank</code>.
265      * @param soundbank soundbank containing instruments to unload
266      * @throws IllegalArgumentException thrown if the soundbank is not supported.
267      * @see #isSoundbankSupported
268      * @see #unloadInstrument    
269      * @see #unloadInstruments   
270      */
271     public void unloadAllInstruments(Soundbank   soundbank);
272 
273     
274     /**
275      * Loads the instruments referenced by the specified patches, from the 
276      * specified <code>Soundbank</code>.  Each of the <code>Patch</code> objects
277      * indicates a bank and program number; the <code>Instrument</code> that
278      * has the matching <code>Patch</code> is loaded into that bank and program
279      * location.
280      * @param soundbank the <code>Soundbank</code> containing the instruments to load
281      * @param patchList list of patches for which instruments should be loaded
282      * @return <code>true</code> if the instruments are all successfully loaded (or 
283      * already had been), <code>false</code> if any instrument could not be 
284      * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)
285      * @throws IllegalArgumentException thrown if the soundbank is not supported.
286      * @see #isSoundbankSupported
287      * @see Instrument#getPatch
288      * @see #loadAllInstruments
289      * @see #loadInstrument  
290      * @see Soundbank#getInstrument(Patch)
291      * @see Sequence#getPatchList()
292      */
293     public boolean loadInstruments(Soundbank   soundbank, Patch  [] patchList);
294     
295     /**
296      * Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.
297      * @param soundbank soundbank containing instruments to unload
298      * @param patchList list of patches for which instruments should be unloaded
299      * @throws IllegalArgumentException thrown if the soundbank is not supported.
300      *
301      * @see #unloadInstrument    
302      * @see #unloadAllInstruments    
303      * @see #isSoundbankSupported
304      * @see Instrument#getPatch
305      * @see #loadInstruments     
306      */
307     public void unloadInstruments(Soundbank   soundbank, Patch  [] patchList);
308 
309 
310     // RECEIVER METHODS
311 
312     /**
313      * Obtains the name of the receiver.
314      * @return receiver name
315      */
316     //  public abstract String getName();
317 
318     
319     /**
320      * Opens the receiver.
321      * @throws MidiUnavailableException if the receiver is cannot be opened, 
322      * usually because the MIDI device is in use by another application.
323      * @throws SecurityException if the receiver cannot be opened due to security
324      * restrictions.
325      */
326     //  public abstract void open() throws MidiUnavailableException, SecurityException;
327 
328 
329     /**
330      * Closes the receiver.
331      */
332     //  public abstract void close();
333 
334 
335     /**
336      * Sends a MIDI event to the receiver.
337      * @param event event to send.
338      * @throws IllegalStateException if the receiver is not open.
339      */ 
340     //  public void send(MidiEvent event) throws IllegalStateException {
341     //
342     //  }
343 
344 
345     /**
346      * Obtains the set of controls supported by the
347      * element.  If no controls are supported, returns an
348      * array of length 0.
349      * @return set of controls
350      */
351     // $$kk: 03.04.99: josh bloch recommends getting rid of this: 
352     // what can you really do with a set of untyped controls??  
353     // $$kk: 03.05.99: i am putting this back in.  for one thing,
354     // you can check the length and know whether you should keep
355     // looking.... 
356     // public Control[] getControls();
357 
358     /**
359      * Obtains the specified control.
360      * @param controlClass class of the requested control
361      * @return requested control object, or null if the 
362      * control is not supported.
363      */
364     // public Control getControl(Class controlClass);
365 }
366
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags