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 }