net.beadsproject.beads.ugens
Class SamplePlayer

java.lang.Object
  extended by net.beadsproject.beads.core.Bead
      extended by net.beadsproject.beads.core.UGen
          extended by net.beadsproject.beads.ugens.SamplePlayer
Direct Known Subclasses:
GranularSamplePlayer

public class SamplePlayer
extends UGen

SamplePlayer plays back a Sample. Playback rate and loop points can be controlled by UGens. The playback point in the Sample can also be directly controlled from UGen to perform scrubbing. The player can be set to a number of different loop modes. If constructed with a Sample argument, the number of outputs of SamplePlayer is determined by the number of channels of the Sample. Sample playback can use either linear or cubic interpolation. TODO: Loop cross-fading has not been implemented yet.

Author:
ollie

Nested Class Summary
static class SamplePlayer.EnvelopeType
          Used to determine whether the SamplePlayer updates control values at sample rate (SamplePlayer.EnvelopeType.FINE) or just every frame (SamplePlayer.EnvelopeType.COARSE).
static class SamplePlayer.InterpolationType
          Used to determine what kind of interpolation is used when access samples.
static class SamplePlayer.LoopType
          Used to determine which kind of loop the sample player will use.
 
Nested classes/interfaces inherited from class net.beadsproject.beads.core.UGen
UGen.OutputInitializationRegime, UGen.OutputPauseRegime
 
Field Summary
static float ADAPTIVE_INTERP_HIGH_THRESH
           
static float ADAPTIVE_INTERP_LOW_THRESH
           
protected  SamplePlayer.EnvelopeType envelopeType
           
protected  boolean forwards
          Flag for alternating loop mode to determine if playback is in forward or reverse phase.
protected  float[] frame
          Array for temp storage.
protected  SamplePlayer.InterpolationType interpolationType
          The interpolation type.
protected  boolean killOnEnd
          Flag to determine whether the SamplePlayer should kill itself when it gets to the end of the Sample.
protected  float loopCrossFade
          The loop cross fade in milliseconds.
protected  float loopEnd
          The loop end.
protected  UGen loopEndEnvelope
          The loop end envelope.
protected  float loopStart
          The loop start.
protected  UGen loopStartEnvelope
          The loop start envelope.
protected  SamplePlayer.LoopType loopType
          The loop type.
protected  double position
          The position in milliseconds.
protected  UGen positionEnvelope
          The position envelope.
protected  double positionIncrement
          The millisecond position increment per sample.
protected  float rate
          The rate.
protected  UGen rateEnvelope
          The rate envelope.
protected  Sample sample
          The Sample.
protected  boolean startLoop
          Flag to determine whether playback starts at the beginning of the sample or at the beginning of the loop.
 
Fields inherited from class net.beadsproject.beads.core.UGen
bufferSize, bufIn, bufOut, context, ins, outputInitializationRegime, outputPauseRegime, outs
 
Constructor Summary
SamplePlayer(AudioContext context, int outs)
          Instantiates a new SamplePlayer with given number of outputs.
SamplePlayer(AudioContext context, Sample buffer)
          Instantiates a new SamplePlayer with given Sample.
 
Method Summary
 void calculateBuffer()
          Called by the signal chain to update this UGen's ouput data.
protected  void calculateNextPosition(int i)
          Used at each sample in the perform routine to determine the next playback position.
 Sample getBuffer()
          Deprecated.  
 Bead getEndListener()
          Gets the current endListener.
 SamplePlayer.EnvelopeType getEnvelopeType()
          Gets the SamplePlayer.EnvelopeType, either SamplePlayer.EnvelopeType.COARSE or SamplePlayer.EnvelopeType.FINE.
 SamplePlayer.InterpolationType getInterpolationType()
          Gets the SamplePlayer.InterpolationType used for accessing samples.
 boolean getKillOnEnd()
          Determines whether this SamplePlayer will kill itself at the end of the Sample it is playing.
 float getLoopCrossFade()
          Gets the loop cross fade.
 UGen getLoopEndEnvelope()
          Deprecated. Use getLoopEndUGen() instead.
 UGen getLoopEndUGen()
          Gets the loop end UGen.
 UGen getLoopStartEnvelope()
          Deprecated. Use getLoopStartUGen() instead.
 UGen getLoopStartUGen()
          Gets the loop start UGen.
 SamplePlayer.LoopType getLoopType()
          Gets the loop type.
 UGen getPitchEnvelope()
          Deprecated. use getPitchUGen() instead.
 UGen getPitchUGen()
          Gets the rate UGen (this method is provided so that SamplePlayer and GranularSamplePlayer can be used interchangeably).
 double getPosition()
          Gets the playback position.
 UGen getPositionEnvelope()
          Deprecated. Use getRateUGen() instead.
 UGen getPositionUGen()
          Gets the position UGen.
 UGen getRateEnvelope()
          Deprecated. use getRateUGen() instead.
 UGen getRateUGen()
          Gets the rate UGen.
 Sample getSample()
          Gets the Sample.
 float getSampleRate()
          Gets the sample rate.
 boolean inLoop()
          Determines whether the playback position is within the loop points.
 void reset()
          Resets the position to the start of the Sample.
 void reTrigger()
          Re trigger the SamplePlayer from the beginning.
 void setBuffer(Sample s)
          Deprecated.  
 void setEndListener(Bead endListener)
          Sets a Bead that will be triggered when this SamplePlayer gets to the end.
 void setEnvelopeType(SamplePlayer.EnvelopeType et)
          Sets the SamplePlayer.EnvelopeType.
 void setInterpolationType(SamplePlayer.InterpolationType interpolationType)
          Sets the interpolation type.
 void setKillOnEnd(boolean killOnEnd)
          Sets/unsets option for SamplePlayer to kill itself when it reaches the end of the Sample it is playing.
 void setLoopCrossFade(float loopCrossFade)
          Sets the loop cross fade.
 void setLoopEnd(UGen loopEndUGen)
          Sets the loop end UGen.
 void setLoopEndEnvelope(UGen loopEndEnvelope)
          Deprecated. Use setLoopEnd(UGen) instead.
 void setLoopPointsFraction(float start, float end)
          Sets both loop points to static values as fractions of the Sample length, overriding any UGens that were controlling the loop points.
 void setLoopStart(UGen loopStartUGen)
          Sets the loop start UGen.
 void setLoopStartEnvelope(UGen loopStartEnvelope)
          Deprecated. Use setLoopStart(UGen) instead.
 void setLoopType(SamplePlayer.LoopType loopType)
          Sets the loop type.
 void setPitch(UGen rateUGen)
          Sets the rate UGen (this method is provided so that SamplePlayer and GranularSamplePlayer can be used interchangeably).
 void setPitchEnvelope(UGen rateEnvelope)
          Deprecated. use setPitch(UGen) instead.
 void setPosition(double position)
          Sets the playback position.
 void setPosition(UGen positionUGen)
          Sets the position as a UGen.
 void setPositionEnvelope(UGen positionEnvelope)
          Deprecated. Use setPosition(UGen) instead.
 void setRate(UGen rateUGen)
          Sets the rate to a UGen.
 void setRateEnvelope(UGen rateEnvelope)
          Deprecated. use setRate(UGen) instead.
 void setSample(Sample sample)
          Sets the Sample.
 void setToEnd()
          Sets the playback position to the end of the Sample.
 void setToLoopStart()
          Sets the playback position to the loop start point.
 void start(float msPosition)
          Starts the sample at the given position.
 
Methods inherited from class net.beadsproject.beads.core.UGen
addDependent, addInput, addInput, clearDependents, clearInputConnections, containsInput, crossfadeInput, getConnectedInputs, getContext, getEnvelopes, getIns, getNumberOfConnectedUGens, getNumberOfDependents, getOutBuffer, getOuts, getTimeTakenLastUpdate, getValue, getValue, getValueDouble, getValueDouble, initializeOuts, isTimerMode, isUpdated, noInputs, pause, printInBuffers, printInputList, printOutBuffers, removeAllConnections, removeConnection, removeDependent, setOutsToPause, setTimerMode, setValue, update, zeroIns, zeroOuts
 
Methods inherited from class net.beadsproject.beads.core.Bead
getKillListener, getName, isDeleted, isPaused, kill, message, messageReceived, setKillListener, setName, start, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ADAPTIVE_INTERP_LOW_THRESH

public static final float ADAPTIVE_INTERP_LOW_THRESH
See Also:
Constant Field Values

ADAPTIVE_INTERP_HIGH_THRESH

public static final float ADAPTIVE_INTERP_HIGH_THRESH
See Also:
Constant Field Values

sample

protected Sample sample
The Sample.


position

protected double position
The position in milliseconds.


positionEnvelope

protected UGen positionEnvelope
The position envelope.


rateEnvelope

protected UGen rateEnvelope
The rate envelope.


positionIncrement

protected double positionIncrement
The millisecond position increment per sample. Calculated from the ratio of the AudioContext's sample rate and the Sample's sample rate.


forwards

protected boolean forwards
Flag for alternating loop mode to determine if playback is in forward or reverse phase.


envelopeType

protected SamplePlayer.EnvelopeType envelopeType

interpolationType

protected SamplePlayer.InterpolationType interpolationType
The interpolation type.


loopStartEnvelope

protected UGen loopStartEnvelope
The loop start envelope.


loopEndEnvelope

protected UGen loopEndEnvelope
The loop end envelope.


loopType

protected SamplePlayer.LoopType loopType
The loop type.


loopCrossFade

protected float loopCrossFade
The loop cross fade in milliseconds.


startLoop

protected boolean startLoop
Flag to determine whether playback starts at the beginning of the sample or at the beginning of the loop.


killOnEnd

protected boolean killOnEnd
Flag to determine whether the SamplePlayer should kill itself when it gets to the end of the Sample.


rate

protected float rate
The rate. Calculated and used internally from the rate envelope.


loopStart

protected float loopStart
The loop start. Calculated and used internally from the loop start envelope.


loopEnd

protected float loopEnd
The loop end. Calculated and used internally from the loop end envelope.


frame

protected float[] frame
Array for temp storage.

Constructor Detail

SamplePlayer

public SamplePlayer(AudioContext context,
                    int outs)
Instantiates a new SamplePlayer with given number of outputs.

Parameters:
context - the AudioContext.
outs - the number of outputs.

SamplePlayer

public SamplePlayer(AudioContext context,
                    Sample buffer)
Instantiates a new SamplePlayer with given Sample. Number of outputs is determined by number of channels in Sample.

Parameters:
context - the AudioContext.
buffer - the Sample.
Method Detail

setSample

public void setSample(Sample sample)
Sets the Sample.


setBuffer

public void setBuffer(Sample s)
Deprecated. 


getSample

public Sample getSample()
Gets the Sample.

Returns:
the Sample.

getBuffer

public Sample getBuffer()
Deprecated. 


setToEnd

public void setToEnd()
Sets the playback position to the end of the Sample.


inLoop

public boolean inLoop()
Determines whether the playback position is within the loop points.

Returns:
true if the playback position is within the loop points.

setToLoopStart

public void setToLoopStart()
Sets the playback position to the loop start point.


start

public void start(float msPosition)
Starts the sample at the given position.

Parameters:
msPosition - the position in milliseconds.

reset

public void reset()
Resets the position to the start of the Sample.


getPosition

public double getPosition()
Gets the playback position.

Returns:
the position in milliseconds.

setPosition

public void setPosition(double position)
Sets the playback position. This will not work if the position envelope is not null.

Parameters:
position - the new position in milliseconds.

getPositionEnvelope

@Deprecated
public UGen getPositionEnvelope()
Deprecated. Use getRateUGen() instead.

Gets the position envelope.

Returns:
the position envelope.

getPositionUGen

public UGen getPositionUGen()
Gets the position UGen.

Returns:
the position UGen.

setPositionEnvelope

@Deprecated
public void setPositionEnvelope(UGen positionEnvelope)
Deprecated. Use setPosition(UGen) instead.

Sets the position envelope. Setting the position envelope means that the position is then controlled by this envelope. If the envelope is null the position continues to be modified by the SamplePlayer's internal playback or by calls to change the position.

Parameters:
positionEnvelope - the new position envelope.

setPosition

public void setPosition(UGen positionUGen)
Sets the position as a UGen. Setting the position envelope means that the position is then controlled by this UGen. If the UGen is null the position continues to be modified by the SamplePlayer's internal playback or by calls to change the position.

Parameters:
positionUGen - the new position UGen.

getRateEnvelope

@Deprecated
public UGen getRateEnvelope()
Deprecated. use getRateUGen() instead.

Gets the rate envelope.

Returns:
the rate envelope.

getRateUGen

public UGen getRateUGen()
Gets the rate UGen.

Returns:
the rate UGen.

setRateEnvelope

@Deprecated
public void setRateEnvelope(UGen rateEnvelope)
Deprecated. use setRate(UGen) instead.

Sets the rate envelope.

Parameters:
rateEnvelope - the new rate envelope.

setRate

public void setRate(UGen rateUGen)
Sets the rate to a UGen.

Parameters:
rateUGen - the new rate UGen.

getPitchEnvelope

@Deprecated
public UGen getPitchEnvelope()
Deprecated. use getPitchUGen() instead.

Gets the rate envelope (this method is provided so that SamplePlayer and GranularSamplePlayer can be used interchangeably).

Returns:
the rate envelope.

getPitchUGen

public UGen getPitchUGen()
Gets the rate UGen (this method is provided so that SamplePlayer and GranularSamplePlayer can be used interchangeably).

Returns:
the rate envelope.

setPitchEnvelope

@Deprecated
public void setPitchEnvelope(UGen rateEnvelope)
Deprecated. use setPitch(UGen) instead.

Sets the rate envelope (this method is provided so that SamplePlayer and GranularSamplePlayer can be used interchangeably).

Parameters:
rateEnvelope - the new rate envelope.

setPitch

public void setPitch(UGen rateUGen)
Sets the rate UGen (this method is provided so that SamplePlayer and GranularSamplePlayer can be used interchangeably).

Parameters:
rateUGen - the new rate UGen.

getEnvelopeType

public SamplePlayer.EnvelopeType getEnvelopeType()
Gets the SamplePlayer.EnvelopeType, either SamplePlayer.EnvelopeType.COARSE or SamplePlayer.EnvelopeType.FINE.

Returns:
the SamplePlayer.EnvelopeType.

setEnvelopeType

public void setEnvelopeType(SamplePlayer.EnvelopeType et)
Sets the SamplePlayer.EnvelopeType. The value SamplePlayer.EnvelopeType.COARSE means that elements controlled by UGens will not be modified every sample, but every sample frame. The value SamplePlayer.EnvelopeType.FINE means that values will be updated every sample. Use COARSE to save processing resources, but use FINE if you want clean and sample accurate control of values.

Parameters:
et - the SamplePlayer.EnvelopeType.

getInterpolationType

public SamplePlayer.InterpolationType getInterpolationType()
Gets the SamplePlayer.InterpolationType used for accessing samples.

Returns:
the interpolation type.

setInterpolationType

public void setInterpolationType(SamplePlayer.InterpolationType interpolationType)
Sets the interpolation type.

Parameters:
interpolationType - the new interpolation type.

getLoopCrossFade

public float getLoopCrossFade()
Gets the loop cross fade.

Returns:
the loop cross fade in milliseconds.

setLoopCrossFade

public void setLoopCrossFade(float loopCrossFade)
Sets the loop cross fade.

Parameters:
loopCrossFade - the new loop cross fade in milliseconds.

getLoopEndEnvelope

@Deprecated
public UGen getLoopEndEnvelope()
Deprecated. Use getLoopEndUGen() instead.

Gets the loop end envelope.

Returns:
the loop end envelope.

getLoopEndUGen

public UGen getLoopEndUGen()
Gets the loop end UGen.

Returns:
the loop end UGen.

setLoopEndEnvelope

@Deprecated
public void setLoopEndEnvelope(UGen loopEndEnvelope)
Deprecated. Use setLoopEnd(UGen) instead.

Sets the loop end envelope.

Parameters:
loopEndEnvelope - the new loop end envelope.

setLoopEnd

public void setLoopEnd(UGen loopEndUGen)
Sets the loop end UGen.

Parameters:
loopEndUGen - the new loop end UGen.

getLoopStartEnvelope

@Deprecated
public UGen getLoopStartEnvelope()
Deprecated. Use getLoopStartUGen() instead.

Gets the loop start envelope.

Returns:
the loop start envelope

getLoopStartUGen

public UGen getLoopStartUGen()
Gets the loop start UGen.

Returns:
the loop start UGen

setLoopStartEnvelope

@Deprecated
public void setLoopStartEnvelope(UGen loopStartEnvelope)
Deprecated. Use setLoopStart(UGen) instead.

Sets the loop start envelope.

Parameters:
loopStartEnvelope - the new loop start envelope.

setLoopStart

public void setLoopStart(UGen loopStartUGen)
Sets the loop start UGen.

Parameters:
loopStartUGen - the new loop start UGen.

setLoopPointsFraction

public void setLoopPointsFraction(float start,
                                  float end)
Sets both loop points to static values as fractions of the Sample length, overriding any UGens that were controlling the loop points.

Parameters:
start - the start value, as fraction of the Sample length.
end - the end value, as fraction of the Sample length.

getLoopType

public SamplePlayer.LoopType getLoopType()
Gets the loop type.

Returns:
the loop type.

setLoopType

public void setLoopType(SamplePlayer.LoopType loopType)
Sets the loop type.

Parameters:
loopType - the new loop type.

getSampleRate

public float getSampleRate()
Gets the sample rate.

Returns:
the sample rate, in samples per second.

calculateBuffer

public void calculateBuffer()
Description copied from class: UGen
Called by the signal chain to update this UGen's ouput data. Subclassses of UGen should implement the UGen's DSP perform routine here. In general this involves grabbing data from UGen.bufIn and putting data into UGen.bufOut in some way. UGen.bufIn and UGen.bufOut are 2D arrays of floats of the form float[numChannels][bufferSize]. The length of the buffers is given by UGen.bufferSize, and the number of channels of the input and output buffers are given by UGen.ins and UGen.outs respectively.

Specified by:
calculateBuffer in class UGen

setKillOnEnd

public void setKillOnEnd(boolean killOnEnd)
Sets/unsets option for SamplePlayer to kill itself when it reaches the end of the Sample it is playing. True by default.

Parameters:
killOnEnd - true to kill on end.

getKillOnEnd

public boolean getKillOnEnd()
Determines whether this SamplePlayer will kill itself at the end of the Sample it is playing.

Returns:
true of SamplePlayer will kill itself at the end of the Sample it is playing.

setEndListener

public void setEndListener(Bead endListener)
Sets a Bead that will be triggered when this SamplePlayer gets to the end. This occurs when the SamplePlayer's position reaches then end when playing forwards in a non-looping mode, or reaches the the beginning when playing backwards in a non-looping mode. It is never triggered in a looping mode. As an alternative, you can use the method Bead.#setKillListener(Bead) as long as setKillOnEnd(boolean) is set to true. In other words, you set this SamplePlayer to kill itself when it reaches the end of the sample, and then use the functionality of Bead, which allows you to create a trigger whenever a Bead is killed. Set to null to remove the current listener.

Parameters:
endListener - the Bead that responds to this SamplePlayer reaching its end.

getEndListener

public Bead getEndListener()
Gets the current endListener.

Returns:
the current endListener.
See Also:
{#setEndListener(Bead)}.

reTrigger

public void reTrigger()
Re trigger the SamplePlayer from the beginning.


calculateNextPosition

protected void calculateNextPosition(int i)
Used at each sample in the perform routine to determine the next playback position.

Parameters:
i - the index within the buffer loop.