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