Package net.paulhertz.pixelaudio.sampler

Class PASharedBufferSampler

java.lang.Object
ddf.minim.UGen
net.paulhertz.pixelaudio.sampler.PASharedBufferSampler
All Implemented Interfaces:
PASampler
public class PASharedBufferSampler extends ddf.minim.UGen implements PASampler
UGen-based sampler that plays multiple PASamplerVoice instances from a single shared mono buffer (channel 0 of a MultiChannelBuffer) which is an array of floating point samples over (-1.0..1.0).

Features:

  • Shared buffer (no duplication)
  • Polyphony with voice pooling
  • Looping (global default + per-voice)
  • ADSR per voice via ADSRParams
  • Oldest-first voice recycling, optional smooth stealing
  • Thread-safe triggering
  • Presets for noise reduction with MixProfile and PASamplerInstrumentPool cycleMixProfile().
Automatically patches to the provided AudioOutput.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    PASharedBufferSampler.MixProfile
    Mix-density normalization profiles for polyphonic sampler output, used to control noise and distortion.

    Nested classes/interfaces inherited from class ddf.minim.UGen

    ddf.minim.UGen.InputType, ddf.minim.UGen.UGenInput

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private float[]
    buffer
    Mono source buffer, typically channel 0 from a MultiChannelBuffer.
    private int
    bufferLen
    Cached source buffer length in samples.
    protected boolean
    DEBUG
    Enables diagnostic voice-trigger logging when true.
    private boolean
    globalLooping
    Default looping state for newly triggered voices.
    private float
    masterGain
    Master linear gain applied to mixed output.
    private int
    maxVoices
    Maximum number of simultaneous voices.
    private float
    mixNorm
    Smoothed mix-normalization gain.
    private PASharedBufferSampler.MixProfile
    mixProfile
     
    private final ddf.minim.AudioOutput
    out
    Audio output this sampler is patched to.
    private float
    playbackSampleRate
    Sample rate of the source buffer in Hz.
    private boolean
    smoothSteal
    True to release stolen voices smoothly instead of stopping them immediately.
    private final List<PASamplerVoice>
    voices
    Voice pool used for polyphonic sample playback.

  • Constructor Summary

    Constructors
    Constructor
    Description
    PASharedBufferSampler(ddf.minim.MultiChannelBuffer multiBuffer, float sampleRate, ddf.minim.AudioOutput out)
    Construct a sampler over a shared MultiChannelBuffer.
    PASharedBufferSampler(ddf.minim.MultiChannelBuffer multiBuffer, float playbackSampleRate, ddf.minim.AudioOutput out, int maxVoices)
    Constructs a sampler over a shared buffer with explicit polyphony.
    PASharedBufferSampler(ddf.minim.MultiChannelBuffer multiBuffer, ddf.minim.AudioOutput out)
    Constructs a sampler and infers playback sample rate from the output.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    countAvailableVoices()
    Counts voices that are neither active nor releasing.
    void
    cycleMixProfile()
    Advances to the next mix normalization profile.
    ddf.minim.AudioOutput
    getAudioOutput()
     
    private PASamplerVoice
    getAvailableVoice()
    Get a free voice, or recycle the oldest active one if at the polyphony limit.
    int
    getBufferLength()
     
    float
    getMasterGain()
     
    float
    getMasterGainDb()
     
    int
    getMaxVoices()
     
    PASharedBufferSampler.MixProfile
    getMixProfile()
     
    String
    getMixProfileName()
     
    float
    getPlaybackSampleRate()
    Returns the current sample rate of this sampler.
    List<PASamplerVoice>
    getVoices()
    Read-only list of voices for GUI or debugging.
    boolean
    isGlobalLooping()
     
    boolean
    isLooping()
    Returns true if any currently active voice is looping.
    boolean
    isSmoothSteal()
     
    int
    play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Play command with all the useful arguments in standard order, overrides PASampler.play().
    void
    releaseAll()
    Releases all voices through their envelopes.
    void
    setBuffer(float[] buffer)
    Replaces the sampler source buffer.
    void
    setBuffer(float[] buffer, float playbackSampleRate)
    Replaces the sampler source buffer and playback sample rate.
    void
    setGlobalLooping(boolean looping)
    Sets default looping for newly triggered voices.
    void
    setMasterGain(float linear)
    Sets master output gain.
    void
    setMasterGainDb(float db)
    Sets master output gain in decibels.
    void
    setMaxVoices(int maxVoices)
    Change maximum polyphony at runtime.
    void
    setMixProfile(PASharedBufferSampler.MixProfile profile)
    Sets the mix normalization profile.
    void
    setPlaybackSampleRate(float newRate)
    Updates the playback sample rate used for reading from the buffer.
    void
    setSmoothSteal(boolean smoothSteal)
    Enable/disable smooth stealing (release envelope) on voice recycle.
    (package private) static float
    softClipSoftsign(float x, float drive)
    Applies a softsign limiter to reduce overload without hard clipping.
    void
    stopAll()
    Stops all voices immediately.
    protected void
    uGenerate(float[] channels)
    Required by Minim.UGen, core method for audio synthesis called by Minim.
    void
    updatePlaybackRateFromOutput()
    Convenience: synchronize playback rate with AudioOutput's sample rate.

    Methods inherited from class ddf.minim.UGen

    addAudio, addControl, addControl, addInput, channelCount, channelCountChanged, getLastValues, patch, patch, patch, printInputs, removeInput, sampleRate, sampleRateChanged, setChannelCount, setSampleRate, tick, unpatch, unpatch

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

    setSampleRate

  • Field Details

    • buffer

      private float[] buffer
      Mono source buffer, typically channel 0 from a MultiChannelBuffer.

    • bufferLen

      private int bufferLen
      Cached source buffer length in samples.

    • playbackSampleRate

      private float playbackSampleRate
      Sample rate of the source buffer in Hz.

    • out

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

    • voices

      private final List<PASamplerVoice> voices
      Voice pool used for polyphonic sample playback.

    • maxVoices

      private int maxVoices
      Maximum number of simultaneous voices.

    • globalLooping

      private boolean globalLooping
      Default looping state for newly triggered voices.

    • smoothSteal

      private boolean smoothSteal
      True to release stolen voices smoothly instead of stopping them immediately.

    • mixNorm

      private float mixNorm
      Smoothed mix-normalization gain.

    • masterGain

      private volatile float masterGain
      Master linear gain applied to mixed output.

    • DEBUG

      protected boolean DEBUG
      Enables diagnostic voice-trigger logging when true.

    • mixProfile

      private volatile PASharedBufferSampler.MixProfile mixProfile

  • Constructor Details

    • PASharedBufferSampler

      public PASharedBufferSampler(ddf.minim.MultiChannelBuffer multiBuffer, float sampleRate, ddf.minim.AudioOutput out)
      Construct a sampler over a shared MultiChannelBuffer. Automatically patches to the provided AudioOutput.
      Parameters:
      multiBuffer - shared source buffer (mono or stereo)
      sampleRate - sample rate of the buffer
      out - target AudioOutput for playback

    • PASharedBufferSampler

      public PASharedBufferSampler(ddf.minim.MultiChannelBuffer multiBuffer, float playbackSampleRate, ddf.minim.AudioOutput out, int maxVoices)
      Constructs a sampler over a shared buffer with explicit polyphony.
      Parameters:
      multiBuffer - shared source buffer
      playbackSampleRate - sample rate of the source buffer in Hz
      out - target AudioOutput for playback
      maxVoices - maximum simultaneous voices

    • PASharedBufferSampler

      public PASharedBufferSampler(ddf.minim.MultiChannelBuffer multiBuffer, ddf.minim.AudioOutput out)
      Constructs a sampler and infers playback sample rate from the output.
      Parameters:
      multiBuffer - shared source buffer
      out - target AudioOutput for playback

  • Method Details

    • play

      public int play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
      Play command with all the useful arguments in standard order, overrides PASampler.play().
      Specified by:
      play in interface PASampler
      Parameters:
      samplePos - index into the buffer to start sampling
      sampleLen - expected duration of the audio event, which is expected to return its actual duration
      amplitude - maximum amplitude of signal generated by the sampler, linear value
      env - ADSR style envelope for the entire event
      pitch - pitch multiplier, where 1.0f implies pitch is unchanged and all samples are read
      pan - location of audio event in stereo field, -1.0f = left, 0.0f = center, 1.0f = right
      Returns:
      actual duration of event in samples, typically sampleLen + envelope release time

    • getAvailableVoice

      private PASamplerVoice getAvailableVoice()
      Get a free voice, or recycle the oldest active one if at the polyphony limit.

    • uGenerate

      protected void uGenerate(float[] channels)
      Required by Minim.UGen, core method for audio synthesis called by Minim. Constant-power panning and soft limiter added to support polyphonic voices.
      Specified by:
      uGenerate in class ddf.minim.UGen

    • softClipSoftsign

      static float softClipSoftsign(float x, float drive)
      Applies a softsign limiter to reduce overload without hard clipping.

      The input is first scaled by drive, then mapped through y / (1 + abs(y)). Small values stay close to linear, while large positive or negative values asymptotically approach -1 or 1.

      A drive value of 1.0 is basically neutral. Typical active values are in the range 1.2 to 1.6. 2.0 to 3.3 provides obvious compress, above 4.0 probably distorts. MixProfile provides :TRANSPARENT: 1.35, BALANCED: 1.60, PROTECTIVE: 1.25.

      Parameters:
      x - input sample
      drive - pre-limiter gain controlling how quickly the curve saturates
      Returns:
      softly limited sample

    • stopAll

      public void stopAll()
      Description copied from interface: PASampler
      Stops all voices immediately.
      Specified by:
      stopAll in interface PASampler

    • releaseAll

      public void releaseAll()
      Description copied from interface: PASampler
      Releases all voices through their envelopes.
      Specified by:
      releaseAll in interface PASampler

    • isLooping

      public boolean isLooping()
      Description copied from interface: PASampler
      Returns true if any currently active voice is looping.
      Specified by:
      isLooping in interface PASampler
      Returns:
      true if one or more voices are looping

    • setGlobalLooping

      public void setGlobalLooping(boolean looping)
      Sets default looping for newly triggered voices.
      Parameters:
      looping - true to loop newly triggered voices

    • isGlobalLooping

      public boolean isGlobalLooping()
      Returns:
      true when newly triggered voices loop by default

    • setSmoothSteal

      public void setSmoothSteal(boolean smoothSteal)
      Enable/disable smooth stealing (release envelope) on voice recycle.
      Parameters:
      smoothSteal - true to release stolen voices smoothly

    • isSmoothSteal

      public boolean isSmoothSteal()
      Returns:
      true when stolen voices release smoothly

    • setMaxVoices

      public void setMaxVoices(int maxVoices)
      Change maximum polyphony at runtime.
      Parameters:
      maxVoices - maximum simultaneous voices

    • getMaxVoices

      public int getMaxVoices()
      Returns:
      maximum simultaneous voices

    • getVoices

      public List<PASamplerVoice> getVoices()
      Read-only list of voices for GUI or debugging.
      Returns:
      unmodifiable voice list

    • setMasterGain

      public void setMasterGain(float linear)
      Sets master output gain.
      Parameters:
      linear - linear gain value

    • getMasterGain

      public float getMasterGain()
      Returns:
      master output gain as a linear value

    • setMasterGainDb

      public void setMasterGainDb(float db)
      Sets master output gain in decibels.
      Parameters:
      db - gain in decibels

    • getMasterGainDb

      public float getMasterGainDb()
      Returns:
      master output gain in decibels

    • setBuffer

      public void setBuffer(float[] buffer)
      Replaces the sampler source buffer.
      Specified by:
      setBuffer in interface PASampler
      Parameters:
      buffer - mono source sample buffer

    • setBuffer

      public void setBuffer(float[] buffer, float playbackSampleRate)
      Replaces the sampler source buffer and playback sample rate.
      Specified by:
      setBuffer in interface PASampler
      Parameters:
      buffer - mono source sample buffer
      playbackSampleRate - sample rate of the source buffer in Hz

    • countAvailableVoices

      public int countAvailableVoices()
      Counts voices that are neither active nor releasing.
      Returns:
      available voice count

    • setMixProfile

      public void setMixProfile(PASharedBufferSampler.MixProfile profile)
      Sets the mix normalization profile.
      Parameters:
      profile - mix profile to apply

    • getMixProfile

      public PASharedBufferSampler.MixProfile getMixProfile()
      Returns:
      active mix normalization profile

    • getMixProfileName

      public String getMixProfileName()
      Returns:
      active mix profile name

    • cycleMixProfile

      public void cycleMixProfile()
      Advances to the next mix normalization profile.

    • getPlaybackSampleRate

      public float getPlaybackSampleRate()
      Returns the current sample rate of this sampler.
      Returns:
      playback sample rate in Hz

    • setPlaybackSampleRate

      public void setPlaybackSampleRate(float newRate)
      Updates the playback sample rate used for reading from the buffer. Does not affect Minim's UGen sample rate.
      Parameters:
      newRate - playback sample rate in Hz

    • updatePlaybackRateFromOutput

      public void updatePlaybackRateFromOutput()
      Convenience: synchronize playback rate with AudioOutput's sample rate. Useful if you want playback speed tied to system rate.

    • getBufferLength

      public int getBufferLength()
      Returns:
      source buffer length in samples

    • getAudioOutput

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