Back to index...

	/*
	* Copyright (c) 1999, 2013, 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 <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.
	* @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.
	* <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 <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 <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 <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 <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 IllegalArgumentException 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.
	* @param instrument instrument to unload
	* @throws IllegalArgumentException 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 <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 successfully remapped,
	* <code>false</code> if feature is not implemented by synthesizer
	* @throws IllegalArgumentException 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 NullPointerException 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.
	* @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.
	* <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
	* <code>Synthesizer</code>.
	* @return a list of currently loaded instruments
	* @see #loadInstrument
	* @see #getAvailableInstruments
	* @see Soundbank#getInstruments
	*/
	public Instrument[] getLoadedInstruments();


	/**
	* 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 <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 <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.
	* @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);
	}

Back to index...