AutoCloseable
, MidiDevice
public interface Synthesizer extends MidiDevice
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 Synthesizer
s 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.
MidiDevice.Info
Modifier and Type | Method | Description |
---|---|---|
Instrument[] |
getAvailableInstruments() |
Obtains a list of instruments that come with the synthesizer. |
MidiChannel[] |
getChannels() |
Obtains the set of MIDI channels controlled by this synthesizer. |
Soundbank |
getDefaultSoundbank() |
Obtains the default soundbank for the synthesizer, if one exists. |
long |
getLatency() |
Obtains the processing latency incurred by this synthesizer, expressed in microseconds. |
Instrument[] |
getLoadedInstruments() |
Obtains a list of the instruments that are currently loaded onto this Synthesizer . |
int |
getMaxPolyphony() |
Obtains the maximum number of notes that this synthesizer can sound simultaneously. |
VoiceStatus[] |
getVoiceStatus() |
Obtains the current status of the voices produced by this synthesizer. |
boolean |
isSoundbankSupported |
Informs the caller whether this synthesizer is capable of loading instruments from the specified soundbank. |
boolean |
loadAllInstruments |
Loads onto the Synthesizer all instruments contained in the specified Soundbank . |
boolean |
loadInstrument |
Makes a particular instrument available for synthesis. |
boolean |
loadInstruments |
Loads the instruments referenced by the specified patches, from the specified Soundbank . |
boolean |
remapInstrument |
Remaps an instrument. |
void |
unloadAllInstruments |
Unloads all instruments contained in the specified Soundbank . |
void |
unloadInstrument |
Unloads a particular instrument. |
void |
unloadInstruments |
Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified. |
close, getDeviceInfo, getMaxReceivers, getMaxTransmitters, getMicrosecondPosition, getReceiver, getReceivers, getTransmitter, getTransmitters, isOpen, open
int getMaxPolyphony()
long getLatency()
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.
MidiChannel[] getChannels()
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.
MidiChannel
objects managed by this Synthesizer
. Some of the array elements may be null
.VoiceStatus[] getVoiceStatus()
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.)VoiceStatus
objects that supply information about the corresponding synthesizer voicesboolean isSoundbankSupported(Soundbank soundbank)
IllegalArgumentException
.soundbank
- soundbank for which support is queriedtrue
if the soundbank is supported, otherwise false
boolean loadInstrument(Instrument instrument)
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
.)
instrument
- instrument to loadtrue
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)IllegalArgumentException
- if this Synthesizer
doesn't support the specified instrument's soundbankvoid unloadInstrument(Instrument instrument)
instrument
- instrument to unloadIllegalArgumentException
- if this Synthesizer
doesn't support the specified instrument's soundbankboolean remapInstrument(Instrument from, Instrument to)
to
takes the place of instrument from
. from
was located at bank number 2, program number 11, remapping causes that bank and program location to be occupied instead by to
. from
is unloaded. To cancel the remapping reload instrument from
by invoking one of loadInstrument(javax.sound.midi.Instrument)
, loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])
or loadAllInstruments(javax.sound.midi.Soundbank)
.
from
- the Instrument
object to be replacedto
- the Instrument
object to be used in place of the old instrument, it should be loaded into the synthesizertrue
if the instrument successfully remapped, false
if feature is not implemented by synthesizerIllegalArgumentException
- if instrument from
or instrument to
aren't supported by synthesizer or if instrument to
is not loadedNullPointerException
- if from
or to
parameters have null valueSoundbank getDefaultSoundbank()
null
if one does not existInstrument[] getAvailableInstruments()
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.
Instrument[] getLoadedInstruments()
Synthesizer
.boolean loadAllInstruments(Soundbank soundbank)
Synthesizer
all instruments contained in the specified Soundbank
.soundbank
- the Soundbank
whose are instruments are to be loadedtrue
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)IllegalArgumentException
- if the requested soundbank is incompatible with this synthesizervoid unloadAllInstruments(Soundbank soundbank)
Soundbank
.soundbank
- soundbank containing instruments to unloadIllegalArgumentException
- thrown if the soundbank is not supportedboolean loadInstruments(Soundbank soundbank, Patch[] patchList)
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.soundbank
- the Soundbank
containing the instruments to loadpatchList
- list of patches for which instruments should be loadedtrue
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)IllegalArgumentException
- thrown if the soundbank is not supportedvoid unloadInstruments(Soundbank soundbank, Patch[] patchList)
soundbank
- soundbank containing instruments to unloadpatchList
- list of patches for which instruments should be unloadedIllegalArgumentException
- thrown if the soundbank is not supported
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/sound/midi/Synthesizer.html