Package org.jjazz.midi.api

Class Instrument

java.lang.Object
org.jjazz.midi.api.Instrument
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
GM1Instrument, GSDrumsInstrument, GSInstrument
public class Instrument extends Object implements Serializable
The data used to select via MIDI an instrument on a synthesizer.
See Also:

  • Constructor Details

    • Instrument

      public Instrument(int programChange, String patchName)
      Constructor with bank=null, drumKit=null, and a MidiAddress(pc=programChange, bankLSB=-1, bankMSB=-1, bankSelectMethod=null).
      Parameters:
      programChange -
      patchName -

    • Instrument

      public Instrument(int programChange, String patchName, DrumKit kit)
      Constructor with bank=null, drumKit=kit, a MidiAddress(pc=programChange, bankLSB=-1, bankMSB=-1, bankSelectMethod=null), and no GM1Instrument substitute.
      Parameters:
      programChange -
      patchName -
      kit - Must be null if instrument is not a drums/percussion kit

    • Instrument

      public Instrument(String patchName, InstrumentBank<?> bank, MidiAddress ma, DrumKit kit, GM1Instrument substitute)
      Create an instrument.

      If bank is non-null and ma is not fully defined (see MidiAddress.isFullyDefined()), then a new MidiAddress is created which replaces the undefined values by the bank default values.

      Parameters:
      patchName - The patchName of the patch, e.g. "Grand Piano"
      bank - The InstrumentBank this instruments belongs to. Can be null if undefined.
      ma - The MidiAddress of the instrument. Can't be null.
      kit - Optional. Must be non-null for drums/percussion instruments.
      substitute - Optional. Must be null for drums/percussion instruments.

  • Method Details

    • getCopy

      public Instrument getCopy()

    • setBank

      public void setBank(InstrumentBank<?> bank)
      This function can be called only once.

      It is the responsibility of the specified bank to add the Instrument.

      If this object's MidiAddress has undefined bankMSB or bankLSB or bankSelectMethod, then a new MidiAddress is created which replaces the undefined values by the bank default values.

      Parameters:
      bank - A non null value, the InstrumentBank this Instrument belongs to, e.g. GM1Bank.

    • isDrumKit

      public boolean isDrumKit()
      True is this instrument represents a DrumKit (each note is a different percussion sound).
      Returns:

    • getDrumKit

      public DrumKit getDrumKit()
      An optional DrumKit associated to this instrument.
      Returns:
      Can be null.

    • getSubstitute

      public GM1Instrument getSubstitute()
      An optional GM1Instrument that can be used as a GM1 replacement instrument.
      Returns:
      Can be null if not defined, or for drums instruments.

    • setSubstitute

      public void setSubstitute(GM1Instrument ins)
      Set the optional GM1Instrument that can be used as a GM1 replacement instrument.

      Parameters:
      ins - Can be null

    • getBank

      public InstrumentBank<?> getBank()
      Returns:
      Can be null.

    • getPatchName

      public String getPatchName()

    • getFullName

      public String getFullName()
      A user-friendly string describing the instrument with its synth (or bank if its a standard bank).

      Examples: "GM: Acoustic Piano", "MOXF: JP Strings"

      Returns:

    • getMidiAddress

      public MidiAddress getMidiAddress()
      Get the MidiAddress for this instrument.

      Returns:

    • getMidiMessages

      public MidiMessage[] getMidiMessages(int channel)
      Get the Midi messages to be sent to initialize the instrument.

      Parameters:
      channel -
      Returns:

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      Same as getPatchName()

    • toLongString

      public String toLongString()
      Longer version.
      Returns:
      "[patchname, bank, substitute, drumkit]" (null values are skipped)

    • saveAsString

      public String saveAsString()
      Save this Instrument as a string so that it can be retrieved by loadFromString().

      Returns:
      A string "MidiSynthName#_#BankName#_#PatchName"
      Throws:
      IllegalStateException - If instrument does not have an InstrumentBank and MidiSynth defined.
      See Also:

    • loadFromString

      public static Instrument loadFromString(String s)
      Get the Instrument corresponding to the string produced by saveAsString().

      Search the synth and bank from their name, then the Instrument from its patchName (ignoring case).

      Parameters:
      s -
      Returns:
      Null if no instrument could be found corresponding to s.
      See Also: