Package net.paulhertz.pixelaudio.granular

Class PAGranularSampler

java.lang.Object
ddf.minim.UGen
net.paulhertz.pixelaudio.granular.PAGranularSampler
public class PAGranularSampler extends ddf.minim.UGen
UGen-based multi-voice sampler for granular PASource playback.

PAGranularSampler is the voice-pool and sample-accurate scheduling layer in PixelAudio's granular synthesis chain. PAGranularInstrument passes immediate and scheduled playback requests to this class; the sampler allocates or reuses PAGranularVoice instances, starts scheduled voices at the requested sample time, and mixes active voices into Minim's audio callback.

Core responsibilities:

  • manage a bounded pool of PAGranularVoice instances;
  • start sources immediately or through AudioScheduler;
  • carry per-voice envelope, gain, pan, looping, and grain-window settings;
  • mix active voices sample by sample in uGenerate(float[]);
  • apply light mix normalization and soft clipping to reduce overload.

When the voice pool is full, the sampler may steal the oldest active voice. With smooth stealing enabled, the old voice is released before reuse; otherwise it is stopped immediately.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    PAGranularSampler.ScheduledPlay
     

    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 int
    blockSize
     
    private float
    globalMakeUpGain
     
    private int
    maxVoices
     
    private float
    mixNorm
     
    private final ddf.minim.AudioOutput
    out
     
    private long
    sampleCursor
     
    private final AudioScheduler<PAGranularSampler.ScheduledPlay>
    scheduler
     
    private boolean
    smoothSteal
     
    private final float[]
    tmpStereo
     
    private final List<PAGranularVoice>
    voices
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    PAGranularSampler(ddf.minim.AudioOutput out)
    Creates a granular sampler with a default maximum of 32 voices.
    PAGranularSampler(ddf.minim.AudioOutput out, int maxVoices)
    Initializes this PAGranularSampler, which extends UGen and gets patched to an AudioOutput, with the result that its uGenerate method is called on each audio block.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    activeOrReleasingVoiceCount()
    Counts voices that are active or releasing.
    void
    cancelAndReleaseAll()
    Clear pending scheduled starts and release currently sounding voices.
    void
    cancelAndStopAll()
    Clear pending scheduled starts and immediately stop all active voices.
    void
    clearScheduled()
    Remove all pending scheduled starts that have not yet been launched.
    ddf.minim.AudioOutput
    getAudioOutput()
     
    private PAGranularVoice
    getAvailableVoice(PASource src, ADSRParams env, float gain, float pan, boolean looping)
     
    private PAGranularVoice
    getAvailableVoice(PASource src, ADSRParams env, float gain, float pan, boolean looping, ddf.minim.analysis.WindowFunction grainWindow, int grainLenSamples)
    Allocates or reuses a voice for a source.
    long
    getCurrentSampleTime()
    Returns the current absolute sample cursor for higher-level scheduling.
    int
    getMaxVoices()
     
    List<PAGranularVoice>
    getVoices()
     
    boolean
    isSmoothSteal()
    Reports whether smooth voice stealing is enabled.
    long
    play(PASource src, float gain, float pan, ADSRParams defaultEnv, boolean looping)
    Convenience overload for callers that supply an already-resolved default envelope.
    long
    play(PASource src, ADSRParams env, float gain, float pan)
    Convenience overload that disables looping.
    long
    play(PASource src, ADSRParams env, float gain, float pan, boolean looping)
    Plays a granular source immediately as a voice.
    void
    releaseAll()
    Release all currently active or releasing voices.
    void
    setMaxVoices(int maxVoices)
    Sets the maximum number of voices in the pool.
    void
    setSmoothSteal(boolean smoothSteal)
    Enables or disables smooth voice stealing.
    private static float
    softClipSoftsign(float x, float drive)
     
    void
    startAfterDelaySamples(PASource src, ADSRParams env, float gain, float pan, boolean looping, long delaySamples)
    Schedules a new voice to start after a delay in samples.
    void
    startAtSampleTime(PASource src, ADSRParams env, float gain, float pan, boolean looping, long startSample)
    Schedules a new voice to start at an absolute sample time.
    void
    startAtSampleTime(PASource src, ADSRParams env, float gain, float pan, boolean looping, long startSample, ddf.minim.analysis.WindowFunction grainWindow, int grainLenSamples)
    Schedules a new voice to start at an absolute sample time with grain-window settings.
    void
    stopAll()
    Immediately stops all voices without clearing pending scheduled starts.
    protected void
    uGenerate(float[] channels)
    Generates one audio sample frame for Minim.

    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

  • Field Details

    • out

      private final ddf.minim.AudioOutput out

    • voices

      private final List<PAGranularVoice> voices

    • maxVoices

      private int maxVoices

    • blockSize

      private int blockSize

    • smoothSteal

      private boolean smoothSteal

    • scheduler

      private final AudioScheduler<PAGranularSampler.ScheduledPlay> scheduler

    • sampleCursor

      private long sampleCursor

    • tmpStereo

      private final float[] tmpStereo

    • mixNorm

      private float mixNorm

    • globalMakeUpGain

      private float globalMakeUpGain

  • Constructor Details

    • PAGranularSampler

      public PAGranularSampler(ddf.minim.AudioOutput out, int maxVoices)
      Initializes this PAGranularSampler, which extends UGen and gets patched to an AudioOutput, with the result that its uGenerate method is called on each audio block.
      Parameters:
      out - a Minim AudioOutput that this PAGranularSampler will patch to
      maxVoices - maximum number of voices to allocate

    • PAGranularSampler

      public PAGranularSampler(ddf.minim.AudioOutput out)
      Creates a granular sampler with a default maximum of 32 voices.
      Parameters:
      out - Minim audio output this sampler patches to

  • Method Details

    • getAvailableVoice

      private PAGranularVoice getAvailableVoice(PASource src, ADSRParams env, float gain, float pan, boolean looping, ddf.minim.analysis.WindowFunction grainWindow, int grainLenSamples)
      Allocates or reuses a voice for a source.

      If no inactive voice is available and the pool is below maxVoices, a new voice is created. If the pool is full, the oldest active voice is stolen. Smooth stealing releases the old voice first; hard stealing stops it immediately.

      Parameters:
      src - source to render
      env - ADSRParams envelope, or null for the voice default
      gain - linear voice gain
      pan - stereo pan in the range [-1, 1]
      looping - true to loop the source path where supported
      grainWindow - window function for shaping grain amplitude, or null for source default
      grainLenSamples - number of samples in one grain
      Returns:
      allocated voice, or null if no voice could be allocated

    • getAvailableVoice

      private PAGranularVoice getAvailableVoice(PASource src, ADSRParams env, float gain, float pan, boolean looping)

    • play

      public long play(PASource src, ADSRParams env, float gain, float pan, boolean looping)
      Plays a granular source immediately as a voice.
      Parameters:
      src - source to render
      env - ADSR for the macro envelope
      gain - linear voice gain
      pan - stereo pan in the range [-1, 1]
      looping - true to loop the source path where supported
      Returns:
      voice id, or -1 if playback could not start

    • play

      public long play(PASource src, ADSRParams env, float gain, float pan)
      Convenience overload that disables looping.

    • play

      public long play(PASource src, float gain, float pan, ADSRParams defaultEnv, boolean looping)
      Convenience overload for callers that supply an already-resolved default envelope.

    • startAtSampleTime

      public void startAtSampleTime(PASource src, ADSRParams env, float gain, float pan, boolean looping, long startSample)
      Schedules a new voice to start at an absolute sample time.
      Parameters:
      src - source to render
      env - ADSR (already resolved: either custom or default)
      gain - final linear voice gain
      pan - final stereo pan
      looping - true to loop the source path where supported
      startSample - absolute sample index at which to start the voice

    • startAtSampleTime

      public void startAtSampleTime(PASource src, ADSRParams env, float gain, float pan, boolean looping, long startSample, ddf.minim.analysis.WindowFunction grainWindow, int grainLenSamples)
      Schedules a new voice to start at an absolute sample time with grain-window settings.

      Called by PAGranularInstrument.startAtSampleTime(PASource, float, float, ADSRParams, boolean, long, WindowFunction, int). This method packages the source and rendering settings in a scheduled payload that is launched from Minim's uGenerate(float[]) callback.

      Parameters:
      src - source to render
      env - ADSR (already resolved: either custom or default)
      gain - final linear voice gain
      pan - final stereo pan
      looping - true to loop the source path where supported
      startSample - absolute sample index at which to start the voice
      grainWindow - a window function for shaping grain amplitude
      grainLenSamples - number of samples in one grain

    • startAfterDelaySamples

      public void startAfterDelaySamples(PASource src, ADSRParams env, float gain, float pan, boolean looping, long delaySamples)
      Schedules a new voice to start after a delay in samples.
      Parameters:
      src - source to render
      env - ADSR
      gain - final linear voice gain
      pan - final stereo pan
      looping - true to loop the source path where supported
      delaySamples - how many samples from "now" to start

    • getCurrentSampleTime

      public long getCurrentSampleTime()
      Returns the current absolute sample cursor for higher-level scheduling.
      Returns:
      current sample time maintained by this sampler

    • uGenerate

      protected void uGenerate(float[] channels)
      Generates one audio sample frame for Minim.

      This method advances the scheduler, launches voices whose start time has arrived, renders active voices, applies mix normalization and soft clipping, and increments the sample cursor.

      Specified by:
      uGenerate in class ddf.minim.UGen

    • softClipSoftsign

      private static float softClipSoftsign(float x, float drive)

    • stopAll

      public void stopAll()
      Immediately stops all voices without clearing pending scheduled starts.

      A stop halts voice processing directly and is more abrupt than a release.

    • clearScheduled

      public void clearScheduled()
      Remove all pending scheduled starts that have not yet been launched. Does not affect currently active voices.

    • releaseAll

      public void releaseAll()
      Release all currently active or releasing voices.

      A release is generally less abrupt than a stop, because each active voice is allowed to pass through its envelope release stage. This is useful for a musical stop after clearing pending scheduled starts.

    • cancelAndStopAll

      public void cancelAndStopAll()
      Clear pending scheduled starts and immediately stop all active voices.

      A stop halts voice processing directly and is therefore more abrupt than a release.

    • cancelAndReleaseAll

      public void cancelAndReleaseAll()
      Clear pending scheduled starts and release currently sounding voices.

      This is the less abrupt counterpart to cancelAndStopAll().

    • activeOrReleasingVoiceCount

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

    • setMaxVoices

      public void setMaxVoices(int maxVoices)
      Sets the maximum number of voices in the pool.
      Parameters:
      maxVoices - maximum voices; values below 1 are clamped to 1

    • getMaxVoices

      public int getMaxVoices()

    • setSmoothSteal

      public void setSmoothSteal(boolean smoothSteal)
      Enables or disables smooth voice stealing.

      Voice stealing occurs when all voices are busy and a new source must start. With smooth stealing enabled, the oldest active voice is released before reuse; with it disabled, the oldest active voice is stopped immediately.

      Parameters:
      smoothSteal - true to release stolen voices, false to stop them immediately

    • isSmoothSteal

      public boolean isSmoothSteal()
      Reports whether smooth voice stealing is enabled.
      Returns:
      true when stolen voices are released instead of stopped immediately

    • getVoices

      public List<PAGranularVoice> getVoices()

    • getAudioOutput

      public ddf.minim.AudioOutput getAudioOutput()