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)
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 Instrumentjava.lang.String
getName()
int
getNumOutputs()
java.lang.Object
getOutput()
get this output (SynthOutput in the case of a JSyn Instrument, for examplejava.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 Instrumentvoid
setMusicDevice(MusicDevice dev)
Set the MusicDevice associated with this Instrumentvoid
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
- Specified by:
setDimensionNameSpace
in interfaceInstrument
-
getDimensionNameSpace
- Specified by:
getDimensionNameSpace
in interfaceInstrument
-
setTransposition
public void setTransposition(double steps)- Specified by:
setTransposition
in interfaceTransposable
-
getTransposition
public double getTransposition()- Specified by:
getTransposition
in interfaceTransposable
-
setInterpreter
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 interfaceInstrument
-
getInterpreter
- Specified by:
getInterpreter
in interfaceInstrument
-
open
public double open(double playTime) throws java.lang.InterruptedException- Specified by:
open
in interfaceInstrument
- Throws:
java.lang.InterruptedException
-
close
public double close(double playTime) throws java.lang.InterruptedException- Specified by:
close
in interfaceInstrument
- 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 interfaceInstrument
-
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 interfaceInstrument
-
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() -
setName
public void setName(java.lang.String n) -
toString
public java.lang.String toString()- Overrides:
toString
in classjava.lang.Object
-
setMusicDevice
Description copied from interface:Instrument
Set the MusicDevice associated with this Instrument- Specified by:
setMusicDevice
in interfaceInstrument
-
getMusicDevice
Description copied from interface:Instrument
Get the MusicDevice associated with this Instrument- Specified by:
getMusicDevice
in interfaceInstrument
-
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 interfaceOutputProvider
- Returns:
- null
-
getOutput
public java.lang.Object getOutput(int partNumber)- Specified by:
getOutput
in interfaceOutputProvider
- Returns:
- null
-
getNumOutputs
public int getNumOutputs()- Specified by:
getNumOutputs
in interfaceOutputProvider
- Returns:
- 0
-
getMixerClassName
public java.lang.String getMixerClassName()The default implementation returns "com.softsynth.jmsl.NullMixer"- Specified by:
getMixerClassName
in interfaceInstrument
- 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 interfaceInstrument
-
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 interfaceInstrument
- 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 interfaceInstrument
- Returns:
- null
- See Also:
com.softsynth.jmsl.Instrument#off(double, Object)
-