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