Package net.paulhertz.pixelaudio.voices

Class PASamplerInstrumentPool

java.lang.Object
net.paulhertz.pixelaudio.voices.PASamplerInstrumentPool
All Implemented Interfaces:
PAPlayable, PASamplerPlayable
public class PASamplerInstrumentPool extends Object implements PASamplerPlayable, PAPlayable
PASamplerInstrumentPool Manages a group of PASamplerInstruments sharing the same source buffer and audio output. Provides polyphony management, buffer swapping, and per-instrument voice recycling. -- TODO Uses a Minim MultiChannelBuffer for its audio sample storage. This could change. -- TODO Duplicates the MultiChannelBuffer. This may be overkill. Features: - 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 Details

    • out

      private final ddf.minim.AudioOutput out

    • buffer

      private ddf.minim.MultiChannelBuffer buffer

    • pool

      private final List<PASamplerInstrument> pool

    • poolSize

      private int poolSize

    • maxVoices

      private int maxVoices

    • defaultEnv

      private ADSRParams defaultEnv

    • globalPitch

      private float globalPitch

    • globalPan

      private float globalPan

    • outputBufferSize

      private int outputBufferSize

    • bufferSampleRate

      private float bufferSampleRate

    • outputSampleRate

      private float outputSampleRate

    • 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().

  • Method Details

    • initPool

      private void initPool()

    • getAvailableInstrument

      private PASamplerInstrument getAvailableInstrument()
      Find a free instrument; otherwise 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

    • isLooping

      public boolean isLooping()

    • stopAll

      public void stopAll()

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      Description copied from interface: PASamplerPlayable
      Play a subrange of the buffer with full parameters.
      Specified by:
      playSample in interface PASamplerPlayable

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, float pitch, float pan)

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude)
      Description copied from interface: PASamplerPlayable
      Play subrange with amplitude only.
      Specified by:
      playSample in interface PASamplerPlayable

    • playSample

      public int playSample(int samplePos, int sampleLen, float amplitude, float pitch)
      Description copied from interface: PASamplerPlayable
      Play subrange with amplitude and pitch (no envelope).
      Specified by:
      playSample in interface PASamplerPlayable

    • 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)

    • playSample

      public int playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)

    • playSample

      public int playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)

    • 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 -
      newBufferSampleRate -

    • setBuffer

      public void setBuffer(float[] newBuffer, float newBufferSampleRate)
      Propagate a new float[] buffer to all instruments in this pool.

    • updateRateFromOutput

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

    • setGlobalPitch

      public void setGlobalPitch(float pitch)

    • getGlobalPitch

      public float getGlobalPitch()

    • setGlobalPan

      public void setGlobalPan(float pan)

    • getGlobalPan

      public float getGlobalPan()

    • setDefaultEnv

      public void setDefaultEnv(ADSRParams env)

    • getDefaultEnv

      public ADSRParams getDefaultEnv()

    • getMaxVoices

      public int getMaxVoices()

    • setMaxVoices

      public void setMaxVoices(int maxVoices)

    • getPoolSize

      public int getPoolSize()

    • setPoolSize

      public void setPoolSize(int newSize)

    • getOutputSampleRate

      public float getOutputSampleRate()

    • getOutputBufferSize

      public int getOutputBufferSize()

    • getBufferSampleRate

      public float getBufferSampleRate()

    • reinitInstruments

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

    • getInstruments

      public List<PASamplerInstrument> getInstruments()

    • schedulePlayAtMillis

      public void schedulePlayAtMillis(long triggerTimeMillis, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      Hook: schedule by (future) wallclock ms — will be wired to TimedLocation later.

    • 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).

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