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