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
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. DONE We are sticking with MultiChannelBuffer but may provide a future abstraction that works with float[] arrays and provide the desired sample format for each synth.

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. This should go into a small demo sketch, SampleAccurateTriggers.

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
    Source buffer for this instrument.
    private float
    bufferSampleRate
    Sample rate of the source from which the buffer was loaded.
    private int
    bufferSize
    Cached source buffer size in samples.
    private ADSRParams
    defaultEnv
    Default ADSR envelope for playback.
    private float
    gain
    Per-instrument linear trim.
    private float
    globalPan
    Global stereo pan offset, from -1.0 left to 1.0 right.
    private float
    globalPitch
    Global pitch multiplier.
    private boolean
    isClosed
     
    private int
    maxVoices
    Maximum number of simultaneous voices for the sampler backend.
    private final ddf.minim.AudioOutput
    out
    Audio output this instrument is patched to.
    private float
    outputSampleRate
    Sample rate of the AudioOutput.
    private float
    parentGain
    Parent pool gain, set by PASamplerInstrumentPool.
    private final PASampler
    sampler
    Sampler backend used to trigger playback.
    private float
    sampleRateRatio
    Buffer-rate to output-rate ratio, used to correct playback speed.

  • 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()
    Counts active or releasing voices.
    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()
    Reports whether any voice is active or releasing.
    boolean
    hasAvailableVoice()
    Reports whether this instrument has an available voice.
    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 and set a new sample rate.
    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)
    Sets the default ADSR envelope.
    void
    setGain(float linear)
    Sets per-instrument output gain.
    void
    setGainDb(float db)
    Sets per-instrument output gain in decibels.
    void
    setGlobalPan(float pan)
    Sets global 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)
    Sets global pitch multiplier.
    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
      Sampler backend used to trigger playback.

    • buffer

      private ddf.minim.MultiChannelBuffer buffer
      Source buffer for this instrument.

    • out

      private final ddf.minim.AudioOutput out
      Audio output this instrument is patched to.

    • bufferSize

      private int bufferSize
      Cached source buffer size in samples. TODO consider replacing with buffer.getBufferSize().

    • maxVoices

      private int maxVoices
      Maximum number of simultaneous voices for the sampler backend.

    • bufferSampleRate

      private float bufferSampleRate
      Sample rate of the source from which the buffer was loaded.

    • outputSampleRate

      private float outputSampleRate
      Sample rate of the AudioOutput.

    • sampleRateRatio

      private float sampleRateRatio
      Buffer-rate to output-rate ratio, used to correct playback speed.

    • defaultEnv

      private ADSRParams defaultEnv
      Default ADSR envelope for playback.

    • globalPitch

      private volatile float globalPitch
      Global pitch multiplier.

    • globalPan

      private float globalPan
      Global stereo pan offset, from -1.0 left to 1.0 right.

    • gain

      private volatile float gain
      Per-instrument linear trim.

    • parentGain

      private volatile float parentGain
      Parent pool gain, set by PASamplerInstrumentPool.

    • 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.
      Parameters:
      buffer - shared MultiChannelBuffer
      out - target AudioOutput
      sampler - sampler implementation to use
      defaultEnv - default ADSR envelope
      bufferSampleRate - sample rate of the source buffer in Hz

    • PASamplerInstrument

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

  • 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
      Parameters:
      samplePos - buffer index to start playback
      sampleLen - requested duration in samples
      amplitude - gain multiplier
      env - optional ADSR envelope
      pitch - pitch or playback-rate multiplier
      pan - stereo pan
      Returns:
      actual event duration in samples

    • 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 - buffer index to start playback
      sampleLen - requested duration in samples
      amplitude - gain multiplier
      pitch - pitch or playback-rate multiplier
      pan - stereo 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
      Parameters:
      samplePos - buffer index to start playback
      sampleLen - requested duration in samples
      amplitude - gain multiplier
      Returns:
      actual event duration in samples

    • 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
      Parameters:
      samplePos - buffer index to start playback
      sampleLen - requested duration in samples
      amplitude - gain multiplier
      pitch - pitch or playback-rate multiplier
      Returns:
      actual event duration in samples

    • 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.
      Parameters:
      samplePos - buffer index to start playback
      sampleLen - requested duration in samples
      amplitude - gain multiplier
      env - optional ADSR envelope
      Returns:
      actual event duration in samples

    • 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.
      Parameters:
      samplePos - buffer index to start playback
      sampleLen - requested duration in samples
      amplitude - gain multiplier
      env - optional ADSR envelope
      pitch - pitch or playback-rate multiplier
      Returns:
      actual event duration in samples

    • 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.
      Parameters:
      buffer - source buffer for playback
      samplePos - buffer index to start playback
      sampleLen - requested duration in samples
      amplitude - gain multiplier
      env - optional ADSR envelope
      pitch - pitch or playback-rate multiplier
      pan - stereo pan
      Returns:
      actual event duration in samples

    • 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.
      Parameters:
      buffer - source buffer for playback
      samplePos - buffer index to start playback
      sampleLen - requested duration in samples
      amplitude - gain multiplier
      env - optional ADSR envelope
      pitch - pitch or playback-rate multiplier
      Returns:
      actual event duration in samples

    • setGain

      public void setGain(float linear)
      Sets per-instrument output gain.
      Parameters:
      linear - linear gain value

    • getGain

      public float getGain()
      Returns:
      per-instrument output gain as a linear value

    • setGainDb

      public void setGainDb(float db)
      Sets per-instrument output gain in decibels.
      Parameters:
      db - gain in decibels

    • getGainDb

      public float getGainDb()
      Returns:
      per-instrument output gain in decibels

    • 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()
      Reports whether this instrument has an available voice.
      Returns:
      true if at least one voice is available

    • hasActiveOrReleasingVoices

      public boolean hasActiveOrReleasingVoices()
      Reports whether any voice is active or releasing.
      Returns:
      true when one or more voices are active or releasing

    • activeOrReleasingVoiceCount

      public int activeOrReleasingVoiceCount()
      Counts active or releasing voices.
      Returns:
      active or releasing voice count

    • releaseAllVoices

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

    • getSampler

      public PASampler getSampler()
      Returns:
      sampler implementation used by this instrument

    • getBuffer

      public ddf.minim.MultiChannelBuffer getBuffer()
      Returns:
      current source buffer

    • getBufferSize

      public int getBufferSize()
      Returns:
      current source buffer size in samples

    • 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 - sample rate of the replacement buffer in Hz

    • setBuffer

      public void setBuffer(float[] newBuffer, float newSampleRate)
      Replace the instrument's active buffer contents and set a new sample rate. Replace 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.

      Parameters:
      newBuffer - replacement mono source buffer
      newSampleRate - sample rate of the replacement buffer in Hz

    • getAudioOutput

      public ddf.minim.AudioOutput getAudioOutput()
      Returns:
      target AudioOutput

    • getBufferSampleRate

      public float getBufferSampleRate()
      Returns:
      source buffer sample rate in Hz

    • getOutputSampleRate

      public float getOutputSampleRate()
      Returns:
      output sample rate in Hz

    • getSampleRateRatio

      public float getSampleRateRatio()
      Returns:
      buffer-to-output sample-rate ratio

    • 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 - new output sample rate in Hz

    • updateRateFromOutput

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

    • getDefaultEnv

      public ADSRParams getDefaultEnv()
      Returns:
      default ADSR envelope

    • setDefaultEnv

      public void setDefaultEnv(ADSRParams env)
      Sets the default ADSR envelope.
      Parameters:
      env - default ADSR envelope

    • setPitchScale

      public void setPitchScale(float scale)
      Sets global pitch multiplier.
      Parameters:
      scale - pitch multiplier

    • getPitchScale

      public float getPitchScale()
      Returns:
      global pitch multiplier

    • setGlobalPan

      public void setGlobalPan(float pan)
      Sets global pan.
      Parameters:
      pan - stereo pan position

    • getGlobalPan

      public float getGlobalPan()
      Returns:
      global pan position

    • clampPan

      private static float clampPan(float pan)

    • close

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