https://openjdk.java.net/ 
/*
 * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.sound.midi;

import javax.sound.sampled.Control;



A Synthesizer generates sound.  This usually happens when one of
the Synthesizer's MidiChannel objects receives a noteOn message, either directly or via the Synthesizer object.
Many Synthesizers support Receivers, through which
MIDI events can be delivered to the Synthesizer.
In such cases, the Synthesizer typically responds by sending
a corresponding message to the appropriate MidiChannel, or by
processing the event itself if the event isn't one of the MIDI channel
messages.


The Synthesizer interface includes methods for loading and
unloading instruments from soundbanks.  An instrument is a specification for synthesizing a
certain type of sound, whether that sound emulates a traditional instrument or is
some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized
by bank and program number (via the instrument's Patch object).
Different Synthesizer classes might implement different sound-synthesis techniques, meaning that some instruments and not others might be compatible with a given synthesizer. Also, synthesizers may have a limited amount of memory for instruments, meaning that not every soundbank and instrument can be used by every synthesizer, even if the synthesis technique is compatible. To see whether the instruments from a certain soundbank can be played by a given synthesizer, invoke the isSoundbankSupported method of Synthesizer.


"Loading" an instrument means that that instrument becomes available for
synthesizing notes.  The instrument is loaded into the bank and
program location specified by its Patch object.  Loading does
not necessarily mean that subsequently played notes will immediately have
the sound of this newly loaded instrument.  For the instrument to play notes,
one of the synthesizer's MidiChannel objects must receive (or have received)
a program-change message that causes that particular instrument's
bank and program number to be selected.

Author:Kara Kytle
See Also:
/**
 * A <code>Synthesizer</code> generates sound.  This usually happens when one of
 * the <code>Synthesizer</code>'s {@link MidiChannel} objects receives a
 * {@link MidiChannel#noteOn(int, int) noteOn} message, either
 * directly or via the <code>Synthesizer</code> object.
 * Many <code>Synthesizer</code>s support <code>Receivers</code>, through which
 * MIDI events can be delivered to the <code>Synthesizer</code>.
 * In such cases, the <code>Synthesizer</code> typically responds by sending
 * a corresponding message to the appropriate <code>MidiChannel</code>, or by
 * processing the event itself if the event isn't one of the MIDI channel
 * messages.
 * <p>
 * The <code>Synthesizer</code> interface includes methods for loading and
 * unloading instruments from soundbanks.  An instrument is a specification for synthesizing a
 * certain type of sound, whether that sound emulates a traditional instrument or is
 * some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized
 * by bank and program number (via the instrument's <code>Patch</code> object).
 * Different <code>Synthesizer</code> classes might implement different sound-synthesis
 * techniques, meaning that some instruments and not others might be compatible with a
 * given synthesizer.
 * Also, synthesizers may have a limited amount of memory for instruments, meaning
 * that not every soundbank and instrument can be used by every synthesizer, even if
 * the synthesis technique is compatible.
 * To see whether the instruments from
 * a certain soundbank can be played by a given synthesizer, invoke the
 * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} method of
 * <code>Synthesizer</code>.
 * <p>
 * "Loading" an instrument means that that instrument becomes available for
 * synthesizing notes.  The instrument is loaded into the bank and
 * program location specified by its <code>Patch</code> object.  Loading does
 * not necessarily mean that subsequently played notes will immediately have
 * the sound of this newly loaded instrument.  For the instrument to play notes,
 * one of the synthesizer's <code>MidiChannel</code> objects must receive (or have received)
 * a program-change message that causes that particular instrument's
 * bank and program number to be selected.
 *
 * @see MidiSystem#getSynthesizer
 * @see Soundbank
 * @see Instrument
 * @see MidiChannel#programChange(int, int)
 * @see Receiver
 * @see Transmitter
 * @see MidiDevice
 *
 * @author Kara Kytle
 */
public interface Synthesizer extends MidiDevice {


    // SYNTHESIZER METHODS


    
Obtains the maximum number of notes that this synthesizer can sound simultaneously.

See Also:
Returns:the maximum number of simultaneous notes
/**
     * Obtains the maximum number of notes that this synthesizer can sound simultaneously.
     * @return the maximum number of simultaneous notes
     * @see #getVoiceStatus
     */
    public int getMaxPolyphony();


    
Obtains the processing latency incurred by this synthesizer, expressed in
microseconds.  This latency measures the worst-case delay between the
time a MIDI message is delivered to the synthesizer and the time that the
synthesizer actually produces the corresponding result.


Although the latency is expressed in microseconds, a synthesizer's actual measured
delay may vary over a wider range than this resolution suggests.  For example,
a synthesizer might have a worst-case delay of a few milliseconds or more.

Returns:the worst-case delay, in microseconds
/**
     * Obtains the processing latency incurred by this synthesizer, expressed in
     * microseconds.  This latency measures the worst-case delay between the
     * time a MIDI message is delivered to the synthesizer and the time that the
     * synthesizer actually produces the corresponding result.
     * <p>
     * Although the latency is expressed in microseconds, a synthesizer's actual measured
     * delay may vary over a wider range than this resolution suggests.  For example,
     * a synthesizer might have a worst-case delay of a few milliseconds or more.
     *
     * @return the worst-case delay, in microseconds
     */
    public long getLatency();


    
Obtains the set of MIDI channels controlled by this synthesizer.  Each
non-null element in the returned array is a MidiChannel that
receives the MIDI messages sent on that channel number.


The MIDI 1.0 specification provides for 16 channels, so this
method returns an array of at least 16 elements.  However, if this synthesizer
doesn't make use of all 16 channels, some of the elements of the array
might be null, so you should check each element
before using it.

Returns:an array of the MidiChannel objects managed by this
Synthesizer.  Some of the array elements may be null.
/**
     * Obtains the set of MIDI channels controlled by this synthesizer.  Each
     * non-null element in the returned array is a <code>MidiChannel</code> that
     * receives the MIDI messages sent on that channel number.
     * <p>
     * The MIDI 1.0 specification provides for 16 channels, so this
     * method returns an array of at least 16 elements.  However, if this synthesizer
     * doesn't make use of all 16 channels, some of the elements of the array
     * might be <code>null</code>, so you should check each element
     * before using it.
     * @return an array of the <code>MidiChannel</code> objects managed by this
     * <code>Synthesizer</code>.  Some of the array elements may be <code>null</code>.
     */
    public MidiChannel[] getChannels();


    
Obtains the current status of the voices produced by this synthesizer.
If this class of Synthesizer does not provide voice
information, the returned array will always be of length 0.  Otherwise,
its length is always equal to the total number of voices, as returned by
getMaxPolyphony().  (See the VoiceStatus class
description for an explanation of synthesizer voices.)

See Also:
Returns:an array of VoiceStatus objects that supply
information about the corresponding synthesizer voices
/**
     * Obtains the current status of the voices produced by this synthesizer.
     * If this class of <code>Synthesizer</code> does not provide voice
     * information, the returned array will always be of length 0.  Otherwise,
     * its length is always equal to the total number of voices, as returned by
     * <code>getMaxPolyphony()</code>.  (See the <code>VoiceStatus</code> class
     * description for an explanation of synthesizer voices.)
     *
     * @return an array of <code>VoiceStatus</code> objects that supply
     * information about the corresponding synthesizer voices
     * @see #getMaxPolyphony
     * @see VoiceStatus
     */
    public VoiceStatus[] getVoiceStatus();


    
Informs the caller whether this synthesizer is capable of loading
instruments from the specified soundbank.
If the soundbank is unsupported, any attempts to load instruments from
it will result in an IllegalArgumentException.

Params:
  • soundbank – soundbank for which support is queried
See Also:
Returns:true if the soundbank is supported, otherwise false
/**
     * Informs the caller whether this synthesizer is capable of loading
     * instruments from the specified soundbank.
     * If the soundbank is unsupported, any attempts to load instruments from
     * it will result in an <code>IllegalArgumentException</code>.
     * @param soundbank soundbank for which support is queried
     * @return <code>true</code> if the soundbank is supported, otherwise <code>false</code>
     * @see #loadInstruments
     * @see #loadAllInstruments
     * @see #unloadInstruments
     * @see #unloadAllInstruments
     * @see #getDefaultSoundbank
     */
    public boolean isSoundbankSupported(Soundbank soundbank);


    
Makes a particular instrument available for synthesis.  This instrument
is loaded into the patch location specified by its Patch
object, so that if a program-change message is
received (or has been received) that causes that patch to be selected,
subsequent notes will be played using the sound of
instrument.  If the specified instrument is already loaded,
this method does nothing and returns true.


The instrument must be part of a soundbank
that this Synthesizer supports.  (To make sure, you can use
the getSoundbank method of Instrument and the
isSoundbankSupported method of Synthesizer.)

Params:
  • instrument – instrument to load
Throws:
  •  IllegalArgumentException if this
 – Synthesizer doesn't support the specified instrument's
soundbank
See Also:
Returns:true if the instrument is successfully loaded (or
already had been), false if the instrument could not be
loaded (for example, if the synthesizer has insufficient
memory to load it)
/**
     * Makes a particular instrument available for synthesis.  This instrument
     * is loaded into the patch location specified by its <code>Patch</code>
     * object, so that if a program-change message is
     * received (or has been received) that causes that patch to be selected,
     * subsequent notes will be played using the sound of
     * <code>instrument</code>.  If the specified instrument is already loaded,
     * this method does nothing and returns <code>true</code>.
     * <p>
     * The instrument must be part of a soundbank
     * that this <code>Synthesizer</code> supports.  (To make sure, you can use
     * the <code>getSoundbank</code> method of <code>Instrument</code> and the
     * <code>isSoundbankSupported</code> method of <code>Synthesizer</code>.)
     * @param instrument instrument to load
     * @return <code>true</code> if the instrument is successfully loaded (or
     * already had been), <code>false</code> if the instrument could not be
     * loaded (for example, if the synthesizer has insufficient
     * memory to load it)
     * @throws <code>IllegalArgumentException</code> if this
     * <code>Synthesizer</code> doesn't support the specified instrument's
     * soundbank
     * @see #unloadInstrument
     * @see #loadInstruments
     * @see #loadAllInstruments
     * @see #remapInstrument
     * @see SoundbankResource#getSoundbank
     * @see MidiChannel#programChange(int, int)
     */
    public boolean loadInstrument(Instrument instrument);


    
Unloads a particular instrument.

Params:
  • instrument – instrument to unload
Throws:
  •  IllegalArgumentException if this
 – Synthesizer doesn't support the specified instrument's
soundbank
See Also:
/**
     * Unloads a particular instrument.
     * @param instrument instrument to unload
     * @throws <code>IllegalArgumentException</code> if this
     * <code>Synthesizer</code> doesn't support the specified instrument's
     * soundbank
     * @see #loadInstrument
     * @see #unloadInstruments
     * @see #unloadAllInstruments
     * @see #getLoadedInstruments
     * @see #remapInstrument
     */
    public void unloadInstrument(Instrument instrument);


    
Remaps an instrument. Instrument to takes the
place of instrument from.

For example, if from was located at bank number 2,
program number 11, remapping causes that bank and program location
to be occupied instead by to.

If the function succeeds,  instrument from is unloaded.

To cancel the remapping reload instrument from by invoking one of loadInstrument, loadInstruments or loadAllInstruments. 
Params:
  • from – the Instrument object to be replaced
  • to – the Instrument object to be used in place
of the old instrument, it should be loaded into the synthesizer
Throws:
  •  IllegalArgumentException if instrument
 – from or instrument to aren't supported by
synthesizer or if instrument to is not loaded
  •  NullPointerException if from or
 – to parameters have null value
See Also:
Returns:true if the instrument succeessfully remapped,
false if feature is not implemented by synthesizer
/**
     * Remaps an instrument. Instrument <code>to</code> takes the
     * place of instrument <code>from</code>.<br>
     * For example, if <code>from</code> was located at bank number 2,
     * program number 11, remapping causes that bank and program location
     * to be occupied instead by <code>to</code>.<br>
     * If the function succeeds,  instrument <code>from</code> is unloaded.
     * <p>To cancel the remapping reload instrument <code>from</code> by
     * invoking one of {@link #loadInstrument}, {@link #loadInstruments}
     * or {@link #loadAllInstruments}.
     *
     * @param from the <code>Instrument</code> object to be replaced
     * @param to the <code>Instrument</code> object to be used in place
     * of the old instrument, it should be loaded into the synthesizer
     * @return <code>true</code> if the instrument succeessfully remapped,
     * <code>false</code> if feature is not implemented by synthesizer
     * @throws <code>IllegalArgumentException</code> if instrument
     * <code>from</code> or instrument <code>to</code> aren't supported by
     * synthesizer or if instrument <code>to</code> is not loaded
     * @throws <code>NullPointerException</code> if <code>from</code> or
     * <code>to</code> parameters have null value
     * @see #loadInstrument
     * @see #loadInstruments
     * @see #loadAllInstruments
     */
    public boolean remapInstrument(Instrument from, Instrument to);


    
Obtains the default soundbank for the synthesizer, if one exists.
(Some synthesizers provide a default or built-in soundbank.)
If a synthesizer doesn't have a default soundbank, instruments must
be loaded explicitly from an external soundbank.

See Also:
Returns:default soundbank, or null if one does not exist.
/**
     * Obtains the default soundbank for the synthesizer, if one exists.
     * (Some synthesizers provide a default or built-in soundbank.)
     * If a synthesizer doesn't have a default soundbank, instruments must
     * be loaded explicitly from an external soundbank.
     * @return default soundbank, or <code>null</code> if one does not exist.
     * @see #isSoundbankSupported
     */
    public Soundbank getDefaultSoundbank();


    
Obtains a list of instruments that come with the synthesizer.  These
instruments might be built into the synthesizer, or they might be
part of a default soundbank provided with the synthesizer, etc.


Note that you don't use this method  to find out which instruments are
currently loaded onto the synthesizer; for that purpose, you use
getLoadedInstruments().
Nor does the method indicate all the instruments that can be loaded onto
the synthesizer; it only indicates the subset that come with the synthesizer.
To learn whether another instrument can be loaded, you can invoke
isSoundbankSupported(), and if the instrument's
Soundbank is supported, you can try loading the instrument.

See Also:
Returns:list of available instruments. If the synthesizer
has no instruments coming with it, an array of length 0 is returned.
/**
     * Obtains a list of instruments that come with the synthesizer.  These
     * instruments might be built into the synthesizer, or they might be
     * part of a default soundbank provided with the synthesizer, etc.
     * <p>
     * Note that you don't use this method  to find out which instruments are
     * currently loaded onto the synthesizer; for that purpose, you use
     * <code>getLoadedInstruments()</code>.
     * Nor does the method indicate all the instruments that can be loaded onto
     * the synthesizer; it only indicates the subset that come with the synthesizer.
     * To learn whether another instrument can be loaded, you can invoke
     * <code>isSoundbankSupported()</code>, and if the instrument's
     * <code>Soundbank</code> is supported, you can try loading the instrument.
     *
     * @return list of available instruments. If the synthesizer
     * has no instruments coming with it, an array of length 0 is returned.
     * @see #getLoadedInstruments
     * @see #isSoundbankSupported(Soundbank)
     * @see #loadInstrument
     */
    public Instrument[] getAvailableInstruments();


    
Obtains a list of the instruments that are currently loaded onto this
Synthesizer.

See Also:
Returns:a list of currently loaded instruments
/**
     * Obtains a list of the instruments that are currently loaded onto this
     * <code>Synthesizer</code>.
     * @return a list of currently loaded instruments
     * @see #loadInstrument
     * @see #getAvailableInstruments
     * @see Soundbank#getInstruments
     */
    public Instrument[] getLoadedInstruments();


    
Loads onto the Synthesizer all instruments contained
in the specified Soundbank.

Params:
  • soundbank – the Soundbank whose are instruments are
to be loaded
Throws:
See Also:
Returns:true if the instruments are all successfully loaded (or
already had been), false if any instrument could not be
loaded (for example, if the Synthesizer had insufficient memory)
/**
     * Loads onto the <code>Synthesizer</code> all instruments contained
     * in the specified <code>Soundbank</code>.
     * @param soundbank the <code>Soundbank</code> whose are instruments are
     * to be loaded
     * @return <code>true</code> if the instruments are all successfully loaded (or
     * already had been), <code>false</code> if any instrument could not be
     * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)
     * @throws IllegalArgumentException if the requested soundbank is
     * incompatible with this synthesizer.
     * @see #isSoundbankSupported
     * @see #loadInstrument
     * @see #loadInstruments
     */
    public boolean loadAllInstruments(Soundbank soundbank);



    
Unloads all instruments contained in the specified Soundbank.

Params:
  • soundbank – soundbank containing instruments to unload
Throws:
See Also:
/**
     * Unloads all instruments contained in the specified <code>Soundbank</code>.
     * @param soundbank soundbank containing instruments to unload
     * @throws IllegalArgumentException thrown if the soundbank is not supported.
     * @see #isSoundbankSupported
     * @see #unloadInstrument
     * @see #unloadInstruments
     */
    public void unloadAllInstruments(Soundbank soundbank);


    
Loads the instruments referenced by the specified patches, from the
specified Soundbank.  Each of the Patch objects
indicates a bank and program number; the Instrument that
has the matching Patch is loaded into that bank and program
location.

Params:
  • soundbank – the Soundbank containing the instruments to load
  • patchList – list of patches for which instruments should be loaded
Throws:
See Also:
Returns:true if the instruments are all successfully loaded (or
already had been), false if any instrument could not be
loaded (for example, if the Synthesizer had insufficient memory)
/**
     * Loads the instruments referenced by the specified patches, from the
     * specified <code>Soundbank</code>.  Each of the <code>Patch</code> objects
     * indicates a bank and program number; the <code>Instrument</code> that
     * has the matching <code>Patch</code> is loaded into that bank and program
     * location.
     * @param soundbank the <code>Soundbank</code> containing the instruments to load
     * @param patchList list of patches for which instruments should be loaded
     * @return <code>true</code> if the instruments are all successfully loaded (or
     * already had been), <code>false</code> if any instrument could not be
     * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)
     * @throws IllegalArgumentException thrown if the soundbank is not supported.
     * @see #isSoundbankSupported
     * @see Instrument#getPatch
     * @see #loadAllInstruments
     * @see #loadInstrument
     * @see Soundbank#getInstrument(Patch)
     * @see Sequence#getPatchList()
     */
    public boolean loadInstruments(Soundbank soundbank, Patch[] patchList);

    
Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.

Params:
  • soundbank – soundbank containing instruments to unload
  • patchList – list of patches for which instruments should be unloaded
Throws:
See Also:
/**
     * Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.
     * @param soundbank soundbank containing instruments to unload
     * @param patchList list of patches for which instruments should be unloaded
     * @throws IllegalArgumentException thrown if the soundbank is not supported.
     *
     * @see #unloadInstrument
     * @see #unloadAllInstruments
     * @see #isSoundbankSupported
     * @see Instrument#getPatch
     * @see #loadInstruments
     */
    public void unloadInstruments(Soundbank soundbank, Patch[] patchList);


    // RECEIVER METHODS

    /**
     * Obtains the name of the receiver.
     * @return receiver name
     */
    //  public abstract String getName();


    /**
     * Opens the receiver.
     * @throws MidiUnavailableException if the receiver is cannot be opened,
     * usually because the MIDI device is in use by another application.
     * @throws SecurityException if the receiver cannot be opened due to security
     * restrictions.
     */
    //  public abstract void open() throws MidiUnavailableException, SecurityException;


    /**
     * Closes the receiver.
     */
    //  public abstract void close();


    /**
     * Sends a MIDI event to the receiver.
     * @param event event to send.
     * @throws IllegalStateException if the receiver is not open.
     */
    //  public void send(MidiEvent event) throws IllegalStateException {
    //
    //  }


    /**
     * Obtains the set of controls supported by the
     * element.  If no controls are supported, returns an
     * array of length 0.
     * @return set of controls
     */
    // $$kk: 03.04.99: josh bloch recommends getting rid of this:
    // what can you really do with a set of untyped controls??
    // $$kk: 03.05.99: i am putting this back in.  for one thing,
    // you can check the length and know whether you should keep
    // looking....
    // public Control[] getControls();

    /**
     * Obtains the specified control.
     * @param controlClass class of the requested control
     * @return requested control object, or null if the
     * control is not supported.
     */
    // public Control getControl(Class controlClass);
}