Package net.paulhertz.pixelaudio.sampler

# Class PASamplerInstrument

java.lang.Object
net.paulhertz.pixelaudio.sampler.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. float[] is preferred for the general style of PixelAudio, but MultiChannelBuffer support is a useful consideration for the future. TODO sample accurate start for sampler events to unify timing API with PAGranularInstrument. Currently sampler play() is block-time accurate only. In the future, add sample-time scheduling (startAtSampleTime / startAfterDelaySamples) using AudioScheduler so sampler and granular share a transport model. Supports: - Global pitch scaling - Global stereo pan - Default ADSR envelope - Linear trim (gain) per instrument - 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`
  `gain`
  `private float`
  `globalPan`
  `private float`
  `globalPitch`
  `private boolean`
  `isClosed`
  `private int`
  `maxVoices`
  `private final ddf.minim.AudioOutput`
  `out`
  `private float`
  `outputSampleRate`
  `private float`
  `parentGain`
  `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.
  `PASharedBufferSampler.MixProfile`
  `cycleMixProfile()`
  Convenience: cycle to the next available sampler mix profile.
  `void`
  `fadeOutAll()`
  Alias for fadeToStop(), useful when calling from UI or pool code.
  `void`
  `fadeToStop()`
  Smoothly stop all active voices by triggering their envelope release.
  `ddf.minim.AudioOutput`
  `getAudioOutput()`
  `ddf.minim.MultiChannelBuffer`
  `getBuffer()`
  `float`
  `getBufferSampleRate()`
  `int`
  `getBufferSize()`
  `ADSRParams`
  `getDefaultEnv()`
  `float`
  `getGain()`
  `float`
  `getGainDb()`
  `float`
  `getGlobalPan()`
  `PASharedBufferSampler.MixProfile`
  `getMixProfile()`
  `float`
  `getOutputSampleRate()`
  `(package private) float`
  `getParentGain()`
  `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`
  `setGain(float linear)`
  `void`
  `setGainDb(float db)`
  `void`
  `setGlobalPan(float pan)`
  `void`
  `setMixProfile(PASharedBufferSampler.MixProfile profile)`
  Pass-through to the underlying PASharedBufferSampler mix behavior.
  `void`
  `setOutputSampleRate(float newRate)`
  Update the output sample rate, for example, if audio device changes.
  `(package private) void`
  `setParentGain(float linear)`
  `void`
  `setPitchScale(float scale)`
  `void`
  `stop()`
  Stop playback (stop all active voices).
  `private void`
  `syncMasterGain()`
  `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.sampler.PAPlayable

  `play, play, play, play, play`

  ### Methods inherited from interface net.paulhertz.pixelaudio.sampler.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

  - ### gain

    private volatile float gain

  - ### parentGain

    private volatile float parentGain

  - ### 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`

  - ### fadeToStop

    public void fadeToStop()
    Smoothly stop all active voices by triggering their envelope release. This is the preferred performance stop.

  - ### fadeOutAll

    public void fadeOutAll()
    Alias for fadeToStop(), useful when calling from UI or pool code.

  - ### 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.

  - ### setGain

    public void setGain(float linear)

  - ### getGain

    public float getGain()

  - ### setGainDb

    public void setGainDb(float db)

  - ### getGainDb

    public float getGainDb()

  - ### setParentGain

    void setParentGain(float linear)

  - ### getParentGain

    float getParentGain()

  - ### syncMasterGain

    private void syncMasterGain()

  - ### setMixProfile

    public void setMixProfile(PASharedBufferSampler.MixProfile profile)
    Pass-through to the underlying PASharedBufferSampler mix behavior. This lets a host application tune density normalization / soft clipping without changing per-event gain or envelope settings.
    Parameters:
      `profile` - a PASharedBufferSampler mix profile

  - ### getMixProfile

    public PASharedBufferSampler.MixProfile getMixProfile()
    Returns:
      the current PASharedBufferSampler mix profile, or BALANCED if the sampler implementation is not PASharedBufferSampler.

  - ### cycleMixProfile

    public PASharedBufferSampler.MixProfile cycleMixProfile()
    Convenience: cycle to the next available sampler mix profile.
    Returns:
      the newly selected profile

  - ### 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.