com.softsynth.jmsl
Class InstrumentAdapter

java.lang.Object
  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)