Package net.paulhertz.pixelaudio.sampler

Class PASamplerInstrumentPool

java.lang.Object
net.paulhertz.pixelaudio.sampler.PASamplerInstrumentPool
All Implemented Interfaces:
PAPlayable, PASamplerPlayable
public class PASamplerInstrumentPool extends Object implements PASamplerPlayable, PAPlayable
Manages a group of PASamplerInstruments sharing the same source buffer and audio output. Provides polyphony management, buffer swapping, and per-instrument voice recycling.

Features:

  • Sample-based instruments with ADSR envelopes
  • Configurable pool size (number of instruments)
  • Configurable max voices per instrument
  • Safe buffer and sample rate propagation
  • Voice stealing via release or stop()
  • Looping detection
  • Thread-safe access

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private ddf.minim.MultiChannelBuffer
    buffer
    Shared source buffer for pooled instruments.
    private float
    bufferSampleRate
    Sample rate of the source from which the buffer was loaded.
    private ADSRParams
    defaultEnv
    Default ADSR envelope passed to pooled instruments.
    private float
    globalPan
    Pool-wide stereo pan offset, from -1.0 left to 1.0 right.
    private float
    globalPitch
    Pool-wide pitch multiplier.
    private boolean
    isClosed
     
    private int
    maxVoices
    Maximum voices allocated per instrument.
    private PASharedBufferSampler.MixProfile
    mixProfile
    Pool-wide sampler mix profile propagated to pooled instruments.
    private final ddf.minim.AudioOutput
    out
    Audio output shared by all instruments in this pool.
    private int
    outputBufferSize
    Output buffer size in frames per audio callback.
    private float
    outputSampleRate
    Sample rate of the AudioOutput.
    private final List<PASamplerInstrument>
    pool
    Instruments managed by this pool.
    private float
    poolGain
    Pool-wide linear gain scalar.
    private int
    poolSize
    Requested number of instruments in the pool.

  • Constructor Summary

    Constructors
    Constructor
    Description
    PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, float sampleRate, int poolSize, int perInstrumentVoices, ddf.minim.AudioOutput out, ADSRParams defaultEnv)
    Full backward-compatible constructor with a MultiChannelBuffer argument.
    PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, int poolSize)
    Convenience constructor: default env, bufferSampleRate = out.sampleRate().
    PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, int poolSize, float bufferSampleRate, ADSRParams env)
    Full constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    private static float
    clampPan(float pan)
     
    void
    close()
    Close all instruments and free audio resources.
    PASharedBufferSampler.MixProfile
    cycleMixProfile()
    Convenience: advance to the next mix profile and apply it pool-wide.
    void
    fadeOutAll()
    Smoothly release all active voices on all instruments.
    private PASamplerInstrument
    getAvailableInstrument()
    Find a free instrument; if no free instrument find least-busy; otherwise smooth-steal one.
    float
    getBufferSampleRate()
     
    ADSRParams
    getDefaultEnv()
     
    float
    getGain()
     
    float
    getGainDb()
     
    float
    getGlobalPan()
     
    float
    getGlobalPitch()
     
    List<PASamplerInstrument>
    getInstruments()
     
    int
    getMaxVoices()
     
    PASharedBufferSampler.MixProfile
    getMixProfile()
     
    int
    getOutputBufferSize()
     
    float
    getOutputSampleRate()
     
    int
    getPoolSize()
     
    private void
    initPool()
     
    boolean
    isClosed()
    Check whether the pool has been closed.
    boolean
    isLooping()
     
    int
    play(float amplitude, float pitch, float pan)
    The most basic play command, plays the entire buffer.
    int
    play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    The primary play command, with all common arguments in standard order.
    int
    playSample(int samplePos, int sampleLen, float amplitude)
    Play subrange with amplitude only.
    int
    playSample(int samplePos, int sampleLen, float amplitude, float pitch)
    Play subrange with amplitude and pitch (no envelope).
    int
    playSample(int samplePos, int sampleLen, float amplitude, float pitch, float pan)
    Plays a sample range with pitch and pan.
    int
    playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env)
    int
    playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)
    Plays a sample range with envelope and pitch.
    int
    playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Play a subrange of the buffer with full parameters.
    int
    playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)
    Plays a range from a temporary buffer.
    int
    playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Plays a range from a temporary buffer.
    private void
    propagateParentGain()
     
    private void
    reinitInstruments()
    Resize the pool gracefully without disrupting existing instruments unnecessarily.
    void
    releaseAll()
    Alias for fadeOutAll(), if you prefer the same naming style as instruments.
    int
    samplerActiveVoiceCount()
    Counts all active or releasing sampler voices across the instrument pool.
    void
    schedulePlayAtFrame(long frameIndex, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Hook: schedule by audio-frame index (frame = one AudioOutput callback).
    void
    schedulePlayAtMillis(long triggerTimeMillis, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Hook: schedule by future wallclock milliseconds; will be wired to TimedLocation later.
    void
    setBuffer(float[] newBuffer, float newBufferSampleRate)
    Propagate a new float[] buffer to all instruments in this pool.
    void
    setBuffer(ddf.minim.MultiChannelBuffer newBuffer)
    Swap the pool's shared buffer; keeps existing bufferSampleRate.
    void
    setBuffer(ddf.minim.MultiChannelBuffer newBuffer, float newBufferSampleRate)
    Swap the pool's shared buffer and update its buffer sample rate.
    void
    setDefaultEnv(ADSRParams env)
    Sets the default ADSR envelope for pooled instruments.
    void
    setGain(float linear)
    Sets pool output gain.
    void
    setGainDb(float db)
    Sets pool output gain in decibels.
    void
    setGlobalPan(float pan)
    Sets global pan used by overloads without explicit pan.
    void
    setGlobalPitch(float pitch)
    Sets global pitch multiplier applied to subsequent playback.
    void
    setMaxVoices(int maxVoices)
    Sets maximum voices per instrument and reapplies pool configuration.
    void
    setMixProfile(PASharedBufferSampler.MixProfile profile)
    Set the sampler bus mix behavior for every instrument in the pool.
    void
    setPoolSize(int newSize)
    Sets the number of instruments in the pool.
    void
    stop()
    Stop playback immediately (implementation-defined).
    void
    stopAll()
    Stops playback on all pooled instruments.
    void
    updateRateFromOutput()
    Re-sync instruments to current AudioOutput sample rate (if output device changes).

    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

    • out

      private final ddf.minim.AudioOutput out
      Audio output shared by all instruments in this pool.

    • buffer

      private ddf.minim.MultiChannelBuffer buffer
      Shared source buffer for pooled instruments.

    • pool

      private final List<PASamplerInstrument> pool
      Instruments managed by this pool.

    • poolSize

      private int poolSize
      Requested number of instruments in the pool.

    • maxVoices

      private int maxVoices
      Maximum voices allocated per instrument.

    • defaultEnv

      private ADSRParams defaultEnv
      Default ADSR envelope passed to pooled instruments.

    • globalPitch

      private float globalPitch
      Pool-wide pitch multiplier.

    • globalPan

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

    • outputBufferSize

      private int outputBufferSize
      Output buffer size in frames per audio callback.

    • bufferSampleRate

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

    • outputSampleRate

      private float outputSampleRate
      Sample rate of the AudioOutput.

    • poolGain

      private volatile float poolGain
      Pool-wide linear gain scalar.

    • mixProfile

      private volatile PASharedBufferSampler.MixProfile mixProfile
      Pool-wide sampler mix profile propagated to pooled instruments.

    • isClosed

      private boolean isClosed

  • Constructor Details

    • PASamplerInstrumentPool

      public PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, float sampleRate, int poolSize, int perInstrumentVoices, ddf.minim.AudioOutput out, ADSRParams defaultEnv)
      Full backward-compatible constructor with a MultiChannelBuffer argument. Envelope is supplied, pitch and pan default to globalPitch and globalPan. Note that the MultiChannelBuffer we supply is not copied, we use it directly for storage. Calling applications should not modify the buffer.
      Parameters:
      buffer - shared MultiChannelBuffer
      sampleRate - nominal sample rate of the buffer (Hz)
      poolSize - number of instruments in the pool
      perInstrumentVoices - number of voices per instrument
      out - AudioOutput to patch instruments into
      defaultEnv - default ADSR envelope for all instruments

    • PASamplerInstrumentPool

      public PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, int poolSize, float bufferSampleRate, ADSRParams env)
      Full constructor.
      Parameters:
      buffer - shared MultiChannelBuffer
      out - target AudioOutput
      poolSize - number of instruments to preallocate
      bufferSampleRate - nominal sample rate of buffer (Hz)
      env - default ADSR (nullable)

    • PASamplerInstrumentPool

      public PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, int poolSize)
      Convenience constructor: default env, bufferSampleRate = out.sampleRate().
      Parameters:
      buffer - shared MultiChannelBuffer
      out - target AudioOutput
      poolSize - number of instruments to preallocate

  • Method Details

    • initPool

      private void initPool()

    • getAvailableInstrument

      private PASamplerInstrument getAvailableInstrument()
      Find a free instrument; if no free instrument find least-busy; otherwise smooth-steal one.

    • play

      public int play(float amplitude, float pitch, float pan)
      The most basic play command, plays the entire buffer.
      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

    • stop

      public void stop()
      Description copied from interface: PAPlayable
      Stop playback immediately (implementation-defined).
      Specified by:
      stop in interface PAPlayable

    • play

      public int play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      The primary play command, with all common arguments in standard order. The playSample(...) methods provide the greatest flexibility in method signatures and will call this method.
      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

    • isLooping

      public boolean isLooping()
      Returns:
      true if any pooled instrument has a looping sampler

    • samplerActiveVoiceCount

      public int samplerActiveVoiceCount()
      Counts all active or releasing sampler voices across the instrument pool.
      Returns:
      total active or releasing voice count

    • stopAll

      public void stopAll()
      Stops playback on all pooled instruments.

    • fadeOutAll

      public void fadeOutAll()
      Smoothly release all active voices on all instruments. Preferred for live transitions and endings.

    • releaseAll

      public void releaseAll()
      Alias for fadeOutAll(), if you prefer the same naming style as instruments.

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      Play a subrange of the buffer with full parameters.
      Specified by:
      playSample 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

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, float pitch, float pan)
      Plays a sample range with pitch and pan.
      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:
      actual event duration in samples

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude)
      Play subrange with amplitude only.
      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)
      Play subrange with amplitude and pitch (no envelope).
      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)

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)
      Plays a sample range with envelope and pitch.
      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)
      Plays a range from a temporary buffer.
      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)
      Plays a range from a temporary buffer.
      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

    • setBuffer

      public void setBuffer(ddf.minim.MultiChannelBuffer newBuffer)
      Swap the pool's shared buffer; keeps existing bufferSampleRate.
      Parameters:
      newBuffer - a new MultiChannelBuffer as audio source for this instrument

    • setBuffer

      public void setBuffer(ddf.minim.MultiChannelBuffer newBuffer, float newBufferSampleRate)
      Swap the pool's shared buffer and update its buffer sample rate.
      Parameters:
      newBuffer - a new MultiChannelBuffer as audio source for this instrument
      newBufferSampleRate - sample rate of the replacement buffer in Hz

    • setBuffer

      public void setBuffer(float[] newBuffer, float newBufferSampleRate)
      Propagate a new float[] buffer to all instruments in this pool.
      Parameters:
      newBuffer - replacement mono source buffer
      newBufferSampleRate - sample rate of the replacement buffer in Hz

    • updateRateFromOutput

      public void updateRateFromOutput()
      Re-sync instruments to current AudioOutput sample rate (if output device changes).

    • setGain

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

    • getGain

      public float getGain()
      Returns:
      pool output gain as a linear value

    • setGainDb

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

    • getGainDb

      public float getGainDb()
      Returns:
      pool output gain in decibels

    • propagateParentGain

      private void propagateParentGain()

    • setMixProfile

      public void setMixProfile(PASharedBufferSampler.MixProfile profile)
      Set the sampler bus mix behavior for every instrument in the pool.
      Parameters:
      profile - desired PASharedBufferSampler mix profile

    • getMixProfile

      public PASharedBufferSampler.MixProfile getMixProfile()
      Returns:
      the pool-wide sampler mix profile

    • cycleMixProfile

      public PASharedBufferSampler.MixProfile cycleMixProfile()
      Convenience: advance to the next mix profile and apply it pool-wide.
      Returns:
      the newly selected profile

    • setGlobalPitch

      public void setGlobalPitch(float pitch)
      Sets global pitch multiplier applied to subsequent playback.
      Parameters:
      pitch - pitch multiplier

    • getGlobalPitch

      public float getGlobalPitch()
      Returns:
      global pitch multiplier

    • setGlobalPan

      public void setGlobalPan(float pan)
      Sets global pan used by overloads without explicit pan.
      Parameters:
      pan - stereo pan position

    • getGlobalPan

      public float getGlobalPan()
      Returns:
      global pan position

    • setDefaultEnv

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

    • getDefaultEnv

      public ADSRParams getDefaultEnv()
      Returns:
      default ADSR envelope

    • getMaxVoices

      public int getMaxVoices()
      Returns:
      maximum voices per instrument

    • setMaxVoices

      public void setMaxVoices(int maxVoices)
      Sets maximum voices per instrument and reapplies pool configuration.
      Parameters:
      maxVoices - maximum voices per instrument

    • getPoolSize

      public int getPoolSize()
      Returns:
      number of instruments in the pool

    • setPoolSize

      public void setPoolSize(int newSize)
      Sets the number of instruments in the pool.
      Parameters:
      newSize - desired pool size

    • getOutputSampleRate

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

    • getOutputBufferSize

      public int getOutputBufferSize()
      Returns:
      output buffer size in samples

    • getBufferSampleRate

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

    • reinitInstruments

      private void reinitInstruments()
      Resize the pool gracefully without disrupting existing instruments unnecessarily. Active instruments are preserved whenever possible.

    • getInstruments

      public List<PASamplerInstrument> getInstruments()
      Returns:
      mutable list of pooled instruments

    • schedulePlayAtMillis

      public void schedulePlayAtMillis(long triggerTimeMillis, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      Hook: schedule by future wallclock milliseconds; will be wired to TimedLocation later.
      Parameters:
      triggerTimeMillis - future trigger time in milliseconds
      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

    • schedulePlayAtFrame

      public void schedulePlayAtFrame(long frameIndex, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      Hook: schedule by audio-frame index (frame = one AudioOutput callback).
      Parameters:
      frameIndex - future audio callback frame index
      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

    • clampPan

      private static float clampPan(float pan)

    • close

      public void close()
      Close all instruments and free audio resources.

    • isClosed

      public boolean isClosed()
      Check whether the pool has been closed.
      Returns:
      true after the pool has been closed