Package com.softsynth.jmsl

Class InstrumentAdapter

java.lang.Object
com.softsynth.jmsl.InstrumentAdapter
All Implemented Interfaces:
Instrument, Namable, OutputProvider, Transposable
Direct Known Subclasses:
BackgroundColorInstrument, FreqSynthNoteInstrument, JSynSimpleUnitVoiceInstrument, MaxInstrument, MidiInstrument, QuietPlayLurkingInstrument, SimpleSamplePlayingInstrument, SineInstrument, SynthNoteInstrument
public class InstrumentAdapter
extends java.lang.Object
implements Instrument
An Instrument sonifies double[] data in its play() method, either directly or by invoking its Interpreter. The double[] data may have come from a MusicShape or may be built on the fly somewhere else (like in a MusicJob, for example, which has an Instrument and could repeatedly assemble a double[] and hand it to its Instrument.play()

You may provide custom interpretation of MusicShape data (ie double[]) one of two ways: 1) by providing an Instrument with an Intepreter, or 2) overriding Instrument's play() method and doing the interpretation there directly.



JMSL v102 introduced the DimensionNameSpace class. Instrument.play() can use the DimensionNameSpace to retrieve values from the double[] by name (like "modfreq") instead of by dimension index.

InstrumentAdapter's constructor sets its DimensionNameSpace to DefaultDimensionNameSpace.instance() Your subclasses may of course setDimensionNameSpace(yourDimNameSpace)

Author:
Nick Didkovsky and Phil Burk
See Also:
DefaultDimensionNameSpace, DimensionNameSpace

  • Constructor Summary

    Constructors
    Constructor Description
    InstrumentAdapter()  

  • Method Summary

    Modifier and Type Method Description
    double close​(double playTime)  
    DimensionNameSpace getDimensionNameSpace()  
    Interpreter getInterpreter()  
    java.lang.String getMixerClassName()
    The default implementation returns "com.softsynth.jmsl.NullMixer"
    MusicDevice getMusicDevice()
    Get the MusicDevice associated with this Instrument
    java.lang.String getName()  
    int getNumOutputs()  
    java.lang.Object getOutput()
    get this output (SynthOutput in the case of a JSyn Instrument, for example
    java.lang.Object getOutput​(int partNumber)  
    double getTransposition()  
    static void main​(java.lang.String[] args)  
    double noteOff​(double playTime, double pitch, double velocity)
    Override to provide custom functionality.
    double noteOn​(double playTime, double pitch, double velocity)
    Override to provide custom functionality.
    double noteOnFor​(double playTime, double holdtime, double pitch, double velocity)
    Calls noteOn() and noteOff() holdtime later.
    java.lang.Object off​(double playTime, double timeStretch, double[] dar)  
    java.lang.Object on​(double playTime, double timeStretch, double[] dar)
    turn an event on.
    double open​(double playTime)  
    double play​(double playTime, double timeStretch, double[] dar)
    You can override this play() method with your own custom code, if you don't want to use an interpreter.
    void setDimensionNameSpace​(DimensionNameSpace dns)  
    void setInterpreter​(Interpreter interp)
    Plug a custom interpreter into this instrument.
    void setMixerClassName​(java.lang.String mixerClassName)
    set the preferred Mixer class name (if any) for this Instrument
    void setMusicDevice​(MusicDevice dev)
    Set the MusicDevice associated with this Instrument
    void setName​(java.lang.String n)  
    void setTransposition​(double steps)  
    java.lang.String toString()  
    double update​(double playTime, double timeStretch, double[] dar)
    update is used to change parameters on a sound event that has already been sounded by play() and is currently sounding.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • InstrumentAdapter

      public InstrumentAdapter()

  • Method Details

    • setDimensionNameSpace

      public void setDimensionNameSpace​(DimensionNameSpace dns)
      Specified by:
      setDimensionNameSpace in interface Instrument

    • getDimensionNameSpace

      public DimensionNameSpace getDimensionNameSpace()
      Specified by:
      getDimensionNameSpace in interface Instrument

    • setTransposition

      public void setTransposition​(double steps)
      Specified by:
      setTransposition in interface Transposable

    • getTransposition

      public double getTransposition()
      Specified by:
      getTransposition in interface Transposable

    • setInterpreter

      public void setInterpreter​(Interpreter interp)
      Plug a custom interpreter into this instrument. Interpreters extract information from a double[] and execute it in time. If you're using simple noteOn/off you don't need a custom interpreter (see MidiInstrument for example).
      Specified by:
      setInterpreter in interface Instrument

    • getInterpreter

      public Interpreter getInterpreter()
      Specified by:
      getInterpreter in interface Instrument

    • open

      public double open​(double playTime) throws java.lang.InterruptedException
      Specified by:
      open in interface Instrument
      Throws:
      java.lang.InterruptedException

    • close

      public double close​(double playTime) throws java.lang.InterruptedException
      Specified by:
      close in interface Instrument
      Throws:
      java.lang.InterruptedException

    • play

      public double play​(double playTime, double timeStretch, double[] dar)
      You can override this play() method with your own custom code, if you don't want to use an interpreter. Be sure to return same or updated playTime!
      Source of default implementation of play(): 
              public double play(double playTime, double timeStretch, double dar[])
        {
                if (interpreter != null) playTime = interpreter.interpret(playTime, timeStretch, dar, this );
                return playTime; // note: if interpreter == null, this will return a playTime with no time delay.
        }
      IMPORTANT: A typical return would be return playTime + dar[0] * timeStretch; which follows a convention of putting duration value in dar[0]. If you don't add something to playTime, play() will be scheduled as though it took no time (unless interpreter returns a later playTime).

      RE-EMPHASIS: This return comment assumes that there is no interpreter returning an updated playTime. A stock Instrument does set its Interpreter to a default printing Interpreter which does update playTime, using dar[0] as duration. So the default Instrument.play() shown above will schedule itself as expected.
      Specified by:
      play in interface Instrument

    • update

      public double update​(double playTime, double timeStretch, double[] dar)
      update is used to change parameters on a sound event that has already been sounded by play() and is currently sounding. For example, it might look up the JSyn SynthNote that was allocated in play() by looking up its the pitch, then update other dimensions like "resonance" or "cutoff" (as it does in SynthNoteAllPortsInstrument ) This stub prints a msg and returns playTime + dar[0] * timeStretch
      Specified by:
      update in interface Instrument

    • noteOn

      public double noteOn​(double playTime, double pitch, double velocity)
      Override to provide custom functionality. Default does nothing.

    • noteOff

      public double noteOff​(double playTime, double pitch, double velocity)
      Override to provide custom functionality. Default does nothing.

    • noteOnFor

      public double noteOnFor​(double playTime, double holdtime, double pitch, double velocity)
      Calls noteOn() and noteOff() holdtime later. Don't need to override if your custom noteOn() and noteOff() work ok

    • getName

      public java.lang.String getName()
      Specified by:
      getName in interface Namable

    • setName

      public void setName​(java.lang.String n)
      Specified by:
      setName in interface Namable

    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object

    • setMusicDevice

      public void setMusicDevice​(MusicDevice dev)
      Description copied from interface: Instrument
      Set the MusicDevice associated with this Instrument
      Specified by:
      setMusicDevice in interface Instrument

    • getMusicDevice

      public MusicDevice getMusicDevice()
      Description copied from interface: Instrument
      Get the MusicDevice associated with this Instrument
      Specified by:
      getMusicDevice in interface Instrument

    • main

      public static void main​(java.lang.String[] args)

    • getOutput

      public java.lang.Object getOutput()
      Description copied from interface: OutputProvider
      get this output (SynthOutput in the case of a JSyn Instrument, for example
      Specified by:
      getOutput in interface OutputProvider
      Returns:
      null

    • getOutput

      public java.lang.Object getOutput​(int partNumber)
      Specified by:
      getOutput in interface OutputProvider
      Returns:
      null

    • getNumOutputs

      public int getNumOutputs()
      Specified by:
      getNumOutputs in interface OutputProvider
      Returns:
      0

    • getMixerClassName

      public java.lang.String getMixerClassName()
      The default implementation returns "com.softsynth.jmsl.NullMixer"
      Specified by:
      getMixerClassName in interface Instrument
      Returns:
      class name of the preferred Mixer (if any) for this Instrument

    • setMixerClassName

      public void setMixerClassName​(java.lang.String mixerClassName)
      set the preferred Mixer class name (if any) for this Instrument
      Specified by:
      setMixerClassName in interface Instrument

    • on

      public java.lang.Object on​(double playTime, double timeStretch, double[] dar)
      Description copied from interface: Instrument
      turn an event on. return an object associated with this (an allocated voice for example )
      Specified by:
      on in interface Instrument
      Returns:
      null. subclasses might return an object that represents an allocated voice.
      See Also:
      Instrument.on(double, double, double[])

    • off

      public java.lang.Object off​(double playTime, double timeStretch, double[] dar)
      Specified by:
      off in interface Instrument
      Returns:
      null
      See Also:
      com.softsynth.jmsl.Instrument#off(double, Object)