Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.sound.midi
Interface Synthesizer

All Superinterfaces:
  MidiDevice

public interface Synthesizer
extends MidiDevice

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 `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.

See Also:
  `MidiSystem.getSynthesizer()`, `Soundbank`, `Instrument`, `MidiChannel.programChange(int, int)`, `Receiver`, `Transmitter`, `MidiDevice`

Nested Class Summary

Nested classes inherited from class javax.sound.midi.MidiDevice
`MidiDevice.Info`

Method Summary
`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(Soundbank soundbank)` Informs the caller whether this synthesizer is capable of loading instruments from the specified soundbank.
`boolean` | `loadAllInstruments(Soundbank soundbank)` Loads onto the `Synthesizer` all instruments contained in the specified `Soundbank`.
`boolean` | `loadInstrument(Instrument instrument)` Makes a particular instrument available for synthesis.
`boolean` | `loadInstruments(Soundbank soundbank, Patch[] patchList)` Loads the instruments referenced by the specified patches, from the specified `Soundbank`.
`boolean` | `remapInstrument(Instrument from, Instrument to)` Remaps an instrument.
`void` | `unloadAllInstruments(Soundbank soundbank)` Unloads all instruments contained in the specified `Soundbank`.
`void` | `unloadInstrument(Instrument instrument)` Unloads a particular instrument.
`void` | `unloadInstruments(Soundbank soundbank, Patch[] patchList)` Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.

Methods inherited from interface javax.sound.midi.MidiDevice
`close, getDeviceInfo, getMaxReceivers, getMaxTransmitters, getMicrosecondPosition, getReceiver, getTransmitter, isOpen, open`

Method Detail

### getMaxPolyphony

    public int getMaxPolyphony()

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

  Returns:
    the maximum number of simultaneous notes
  See Also:
    `getVoiceStatus()`

### getLatency

    public long getLatency()

  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

### getChannels

    public MidiChannel[] getChannels()

  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`.

### getVoiceStatus

    public VoiceStatus[] getVoiceStatus()

  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.)

  Returns:
    an array of `VoiceStatus` objects that supply information about the corresponding synthesizer voices
  See Also:
    `getMaxPolyphony()`, `VoiceStatus`

### isSoundbankSupported

    public boolean isSoundbankSupported(Soundbank soundbank)

  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`.

  Parameters:
    `soundbank` - soundbank for which support is queried
  Returns:
    `true` if the soundbank is supported, otherwise `false`
  See Also:
    `loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])`, `loadAllInstruments(javax.sound.midi.Soundbank)`, `unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])`, `unloadAllInstruments(javax.sound.midi.Soundbank)`, `getDefaultSoundbank()`

### loadInstrument

    public boolean loadInstrument(Instrument instrument)

  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`.)

  Parameters:
    `instrument` - instrument to load
  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)
  Throws:
    ``IllegalArgumentException`` - if this `Synthesizer` doesn't support the specified instrument's soundbank
  See Also:
    `unloadInstrument(javax.sound.midi.Instrument)`, `loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])`, `loadAllInstruments(javax.sound.midi.Soundbank)`, `remapInstrument(javax.sound.midi.Instrument, javax.sound.midi.Instrument)`, `SoundbankResource.getSoundbank()`, `MidiChannel.programChange(int, int)`

### unloadInstrument

    public void unloadInstrument(Instrument instrument)

  Unloads a particular instrument.

  Parameters:
    `instrument` - instrument to unload
  Throws:
    ``IllegalArgumentException`` - if this `Synthesizer` doesn't support the specified instrument's soundbank
  See Also:
    `loadInstrument(javax.sound.midi.Instrument)`, `unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])`, `unloadAllInstruments(javax.sound.midi.Soundbank)`, `getLoadedInstruments()`, `remapInstrument(javax.sound.midi.Instrument, javax.sound.midi.Instrument)`

### remapInstrument

    public boolean remapInstrument(Instrument from,
                                   Instrument to)

  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`. Instrument `from` is unloaded.

  Parameters:
    `from` - instrument to be replaced
    `to` - new instrument to be used in place of the old instrument
  Returns:
    `true` if the instrument could be remapped, `false` otherwise
  Throws:
    ``IllegalArgumentException`` - if the soundbank is not supported

### getDefaultSoundbank

    public Soundbank getDefaultSoundbank()

  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.

  Returns:
    default soundbank, or `null` if one does not exist.
  See Also:
    `isSoundbankSupported(javax.sound.midi.Soundbank)`

### getAvailableInstruments

    public Instrument[] getAvailableInstruments()

  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.

  Returns:
    list of available instruments.
  See Also:
    `getLoadedInstruments()`, `isSoundbankSupported(Soundbank)`, `loadInstrument(javax.sound.midi.Instrument)`

### getLoadedInstruments

    public Instrument[] getLoadedInstruments()

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

  Returns:
    a list of currently loaded instruments
  See Also:
    `loadInstrument(javax.sound.midi.Instrument)`, `getAvailableInstruments()`, `Soundbank.getInstruments()`

### loadAllInstruments

    public boolean loadAllInstruments(Soundbank soundbank)

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

  Parameters:
    `soundbank` - the `Soundbank` whose are instruments are to be loaded
  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)
  Throws:
    `IllegalArgumentException` - if the requested soundbank is incompatible with this synthesizer.
  See Also:
    `isSoundbankSupported(javax.sound.midi.Soundbank)`, `loadInstrument(javax.sound.midi.Instrument)`, `loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])`

### unloadAllInstruments

    public void unloadAllInstruments(Soundbank soundbank)

  Unloads all instruments contained in the specified `Soundbank`.

  Parameters:
    `soundbank` - soundbank containing instruments to unload
  Throws:
    `IllegalArgumentException` - thrown if the soundbank is not supported.
  See Also:
    `isSoundbankSupported(javax.sound.midi.Soundbank)`, `unloadInstrument(javax.sound.midi.Instrument)`, `unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])`

### loadInstruments

    public boolean loadInstruments(Soundbank soundbank,
                                   Patch[] patchList)

  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.

  Parameters:
    `soundbank` - the `Soundbank` containing the instruments to load
    `patchList` - list of patches for which instruments should be loaded
  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)
  Throws:
    `IllegalArgumentException` - thrown if the soundbank is not supported.
  See Also:
    `isSoundbankSupported(javax.sound.midi.Soundbank)`, `Instrument.getPatch()`, `loadAllInstruments(javax.sound.midi.Soundbank)`, `loadInstrument(javax.sound.midi.Instrument)`, `Soundbank.getInstrument(Patch)`, `Sequence.getPatchList()`

### unloadInstruments

    public void unloadInstruments(Soundbank soundbank,
                                  Patch[] patchList)

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

  Parameters:
    `soundbank` - soundbank containing instruments to unload
    `patchList` - list of patches for which instruments should be unloaded
  Throws:
    `IllegalArgumentException` - thrown if the soundbank is not supported.
  See Also:
    `unloadInstrument(javax.sound.midi.Instrument)`, `unloadAllInstruments(javax.sound.midi.Soundbank)`, `isSoundbankSupported(javax.sound.midi.Soundbank)`, `Instrument.getPatch()`, `loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.