Package net.paulhertz.pixelaudio.voices

# Class PASamplerInstrument

java.lang.Object
net.paulhertz.pixelaudio.voices.PASamplerInstrument

All Implemented Interfaces:
  `PAPlayable`, `PASamplerPlayable`

public class PASamplerInstrument extends Object implements PASamplerPlayable
PASamplerInstrument Represents a playable instrument that uses a PASampler instantiated as a PASharedBufferSampler to trigger audio playback from a shared buffer that is (currently) a Minim MultiChannelBuffer. TODO decide if MultiChannelBuffer or float[] is the appropriate structure for storing the buffer. Supports: - Global pitch scaling - Global stereo pan - Default ADSR envelope - Compensation for differing buffer vs. output sample rates - Cached buffer size for efficiency Implements both PAPlayable and PASamplerPlayable for full compatibility.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `private ddf.minim.MultiChannelBuffer`
  `buffer`
  `private float`
  `bufferSampleRate`
  `private int`
  `bufferSize`
  `private ADSRParams`
  `defaultEnv`
  `private float`
  `globalPan`
  `private float`
  `globalPitch`
  `private boolean`
  `isClosed`
  `private int`
  `maxVoices`
  `private final ddf.minim.AudioOutput`
  `out`
  `private float`
  `outputSampleRate`
  `private final PASampler`
  `sampler`
  `private float`
  `sampleRateRatio`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, float sampleRate, int maxVoices, ddf.minim.AudioOutput audioOut, ADSRParams env)`
  Primary constructor for backward compatibility.
  `PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out)`
  Convenience constructor assuming buffer and output share the same rate.
  `PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, PASampler sampler, ADSRParams defaultEnv, float bufferSampleRate)`
  Full constructor with explicit buffer sample rate, custom sampler, and envelope.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `activeOrReleasingVoiceCount()`
  `private static float`
  `clampPan(float pan)`
  `void`
  `close()`
  Stop all voices and disconnect UGens from the output.
  `ddf.minim.AudioOutput`
  `getAudioOutput()`
  `ddf.minim.MultiChannelBuffer`
  `getBuffer()`
  `float`
  `getBufferSampleRate()`
  `int`
  `getBufferSize()`
  `ADSRParams`
  `getDefaultEnv()`
  `float`
  `getGlobalPan()`
  `float`
  `getOutputSampleRate()`
  `float`
  `getPitchScale()`
  `PASampler`
  `getSampler()`
  `float`
  `getSampleRateRatio()`
  `boolean`
  `hasActiveOrReleasingVoices()`
  `boolean`
  `hasAvailableVoice()`
  `int`
  `play(float amplitude, float pitch, float pan)`
  Generic play() from PAPlayable, will play the entire buffer from the beginning of the buffer with specified pitch and pan and default envelope.
  `int`
  `play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)`
  The primary play method, called by all playSample() methods, from PASamplerPlayable interface.
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude)`
  Convenience overload: uses default envelope, default pitch, and center pan.
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, float pitch)`
  Convenience overload: uses default envelope, supplied pitch and center pan.
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, float pitch, float pan)`
  All params except the envelope, so we use the default envelope.
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env)`
  Plays a sample using a supplied envelope with default pitch and default pan.
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)`
  Plays a sample using a supplied envelope, pitch, and current global pan.
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)`
  Trigger playback using all six standard per-voice parameters.
  `int`
  `playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)`
  Sets a new buffer for PASamplerInstrument and plays it with envelope, pitch, and default pan.
  `int`
  `playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)`
  Sets a new buffer for PASamplerInstrument and plays it with envelope, pitch, and pan.
  `void`
  `releaseAllVoices()`
  Smoothly release all active voices (used only if we must recycle an instrument).
  `void`
  `setBuffer(float[] newBuffer, float newSampleRate)`
  Replace the instrument's active buffer contents with a new signal array using MultiChannelBuffer.setChannel(0, newBuffer), which creates a copy of the supplied array, and set a new bufferSamplerRate.
  `void`
  `setBuffer(ddf.minim.MultiChannelBuffer newBuffer)`
  Copy the data and settings in the provided MultiChannelBuffer to this.buffer; bufferSampleRate is unchanged.
  `void`
  `setBuffer(ddf.minim.MultiChannelBuffer newBuffer, float newSampleRate)`
  Copy the data and settings of the provided MultiChannelBuffer to this.buffer and set bufferSampleRate.
  `void`
  `setBufferSampleRate(float newRate)`
  Update the buffer's intrinsic sample rate.
  `void`
  `setDefaultEnv(ADSRParams env)`
  `void`
  `setGlobalPan(float pan)`
  `void`
  `setOutputSampleRate(float newRate)`
  Update the output sample rate, for example, if audio device changes.
  `void`
  `setPitchScale(float scale)`
  `void`
  `stop()`
  Stop playback (stop all active voices).
  `void`
  `updateRateFromOutput()`
  Synchronize output sample rate from AudioOutput directly.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface net.paulhertz.pixelaudio.voices.PAPlayable

  `play, play, play, play, play`

  ### Methods inherited from interface net.paulhertz.pixelaudio.voices.PASamplerPlayable

  `playSample, playSample, playSample, playSample, playSample`

- ## Field Details

  - ### sampler

    private final PASampler sampler

  - ### buffer

    private ddf.minim.MultiChannelBuffer buffer

  - ### out

    private final ddf.minim.AudioOutput out

  - ### bufferSize

    private int bufferSize

  - ### maxVoices

    private int maxVoices

  - ### bufferSampleRate

    private float bufferSampleRate

  - ### outputSampleRate

    private float outputSampleRate

  - ### sampleRateRatio

    private float sampleRateRatio

  - ### defaultEnv

    private ADSRParams defaultEnv

  - ### globalPitch

    private volatile float globalPitch

  - ### globalPan

    private float globalPan

  - ### isClosed

    private boolean isClosed

- ## Constructor Details

  - ### PASamplerInstrument

    public PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, float sampleRate, int maxVoices, ddf.minim.AudioOutput audioOut, ADSRParams env)
    Primary constructor for backward compatibility.
    Parameters:
      `buffer` - the shared MultiChannelBuffer
      `sampleRate` - nominal sample rate of the buffer (Hz)
      `maxVoices` - number of simultaneous voices (polyphony)
      `audioOut` - target AudioOutput
      `env` - default ADSR envelope parameters

  - ### PASamplerInstrument

    public PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, PASampler sampler, ADSRParams defaultEnv, float bufferSampleRate)
    Full constructor with explicit buffer sample rate, custom sampler, and envelope.

  - ### PASamplerInstrument

    public PASamplerInstrument(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out)
    Convenience constructor assuming buffer and output share the same rate.

- ## Method Details

  - ### play

    public int play(float amplitude, float pitch, float pan)
    Generic play() from PAPlayable, will play the entire buffer from the beginning of the buffer with specified pitch and pan and default envelope.
    Specified by:
      `play` in interface `PAPlayable`
    Parameters:
      `amplitude` - gain multiplier (0..1+)
      `pitch` - playback rate or pitch factor (implementation-defined)
      `pan` - stereo pan (-1 left .. +1 right)
    Returns:
      non-zero if a voice/event was triggered

  - ### play

    public int play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    The primary play method, called by all playSample() methods, from PASamplerPlayable interface.
    Specified by:
      `play` in interface `PASamplerPlayable`

  - ### stop

    public void stop()
    Stop playback (stop all active voices).
    Specified by:
      `stop` in interface `PAPlayable`

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Trigger playback using all six standard per-voice parameters.
    Specified by:
      `playSample` in interface `PASamplerPlayable`
    Parameters:
      `samplePos` - start position (samples)
      `sampleLen` - playback length (samples)
      `amplitude` - per-voice amplitude
      `env` - ADSR envelope parameters
      `pitch` - playback rate (1.0 = normal)
      `pan` - stereo position (-1.0 = left, +1.0 = right)
    Returns:
      the actual length of the audio event, in samples

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, float pitch, float pan)
    All params except the envelope, so we use the default envelope.
    Parameters:
      `samplePos` -
      `sampleLen` -
      `amplitude` -
      `pitch` -
      `pan` -
    Returns:
      the actual length of the audio event, in samples

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude)
    Convenience overload: uses default envelope, default pitch, and center pan.
    Specified by:
      `playSample` in interface `PASamplerPlayable`

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, float pitch)
    Convenience overload: uses default envelope, supplied pitch and center pan.
    Specified by:
      `playSample` in interface `PASamplerPlayable`

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env)
    Plays a sample using a supplied envelope with default pitch and default pan.

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)
    Plays a sample using a supplied envelope, pitch, and current global pan.

  - ### playSample

    public int playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Sets a new buffer for PASamplerInstrument and plays it with envelope, pitch, and pan. For large buffers, there may be some latency.

  - ### playSample

    public int playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)
    Sets a new buffer for PASamplerInstrument and plays it with envelope, pitch, and default pan.

  - ### hasAvailableVoice

    public boolean hasAvailableVoice()

  - ### hasActiveOrReleasingVoices

    public boolean hasActiveOrReleasingVoices()

  - ### activeOrReleasingVoiceCount

    public int activeOrReleasingVoiceCount()

  - ### releaseAllVoices

    public void releaseAllVoices()
    Smoothly release all active voices (used only if we must recycle an instrument).

  - ### getSampler

    public PASampler getSampler()

  - ### getBuffer

    public ddf.minim.MultiChannelBuffer getBuffer()

  - ### getBufferSize

    public int getBufferSize()

  - ### setBuffer

    public void setBuffer(ddf.minim.MultiChannelBuffer newBuffer)
    Copy the data and settings in the provided MultiChannelBuffer to this.buffer; bufferSampleRate is unchanged. The sampler and its voices are also refreshed. Note that bufferSize will change if the buffers are not the same size.
    Parameters:
      `newBuffer` - buffer to replace the current buffer

  - ### setBuffer

    public void setBuffer(ddf.minim.MultiChannelBuffer newBuffer, float newSampleRate)
    Copy the data and settings of the provided MultiChannelBuffer to this.buffer and set bufferSampleRate. The sampler and its voices are also refreshed. Note that bufferSize will change if the buffers are not the same size.
    Parameters:
      `newBuffer` - buffer to replace the current buffer
      `newSampleRate` -

  - ### setBuffer

    public void setBuffer(float[] newBuffer, float newSampleRate)
    Replace the instrument's active buffer contents with a new signal array using MultiChannelBuffer.setChannel(0, newBuffer), which creates a copy of the supplied array, and set a new bufferSamplerRate. The sampler and its voices are also refreshed. Note that bufferSize will change if the this.buffer and newBuffer are not the same size. The instrument retains its own MultiChannelBuffer but updates its internal copy. The sampler and its voices also receive a fresh copy.

  - ### getAudioOutput

    public ddf.minim.AudioOutput getAudioOutput()

  - ### getBufferSampleRate

    public float getBufferSampleRate()

  - ### getOutputSampleRate

    public float getOutputSampleRate()

  - ### getSampleRateRatio

    public float getSampleRateRatio()

  - ### setBufferSampleRate

    public void setBufferSampleRate(float newRate)
    Update the buffer's intrinsic sample rate.
    Parameters:
      `newRate` - new sample rate for the buffer, affects playback rate

  - ### setOutputSampleRate

    public void setOutputSampleRate(float newRate)
    Update the output sample rate, for example, if audio device changes. This is unlikely to happen, but we'll be cautious.
    Parameters:
      `newRate` -

  - ### updateRateFromOutput

    public void updateRateFromOutput()
    Synchronize output sample rate from AudioOutput directly.

  - ### getDefaultEnv

    public ADSRParams getDefaultEnv()

  - ### setDefaultEnv

    public void setDefaultEnv(ADSRParams env)

  - ### setPitchScale

    public void setPitchScale(float scale)

  - ### getPitchScale

    public float getPitchScale()

  - ### setGlobalPan

    public void setGlobalPan(float pan)

  - ### getGlobalPan

    public float getGlobalPan()

  - ### clampPan

    private static float clampPan(float pan)

  - ### close

    public void close()
    Stop all voices and disconnect UGens from the output.