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 }