com.softsynth.jmsl
Class InstrumentAdapter

java.lang.Object
  extended by com.softsynth.jmsl.InstrumentAdapter
All Implemented Interfaces:
Instrument, Namable, OutputProvider, Transposable
Direct Known Subclasses:
AppletColorInstrument, FreqSynthNoteInstrument, 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
InstrumentAdapter()
           
 
Method Summary
 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 Detail

InstrumentAdapter

public InstrumentAdapter()
Method Detail

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)