Package net.paulhertz.pixelaudio.granular

Class PAGranularInstrumentDirector

java.lang.Object
net.paulhertz.pixelaudio.granular.PAGranularInstrumentDirector
public final class PAGranularInstrumentDirector extends Object
Top-level director for gesture-driven granular synthesis in PixelAudio.

PAGranularInstrumentDirector is the high-level entry point most callers use after they have a mono source buffer, a GestureSchedule, runtime synthesis settings, and per-event buffer indices. The director prepares the schedule, creates one PABurstGranularSource for each scheduled event, and delegates playback to a PAGranularInstrument, which further delegates audio generation.

Granular playback chain:

  1. PAGranularInstrumentDirector receives a mono source buffer, gesture schedule, runtime synthesis parameters, and per-event parameters. It prepares event timing, resolves defaults, creates one PABurstGranularSource per gesture event, and schedules each source at an absolute sample time.
  2. PAGranularInstrument applies instrument-level gain, pan, and envelope defaults, then forwards immediate or scheduled playback requests to the sampler.
  3. PAGranularSampler owns the voice pool and sample-accurate scheduler. It starts voices immediately or when scheduled sample times arrive.
  4. PAGranularVoice applies the macro envelope, voice gain, pan, and lifecycle state while asking its PASource to render audio blocks.
  5. PABurstGranularSource renders the actual burst grains sample by sample, including source-buffer lookup, pitch-ratio playback, windowing, and overlap-add normalization.

This class owns the gesture-level decisions: when events occur, where each event reads from the source buffer, which per-event pan/gain/pitch overrides apply, and which grain window is used. PABurstGranularSource owns sample-level burst rendering for each event.

See Also:

  • Field Details

    • instrument

      private final PAGranularInstrument instrument

    • sampleRate

      private final float sampleRate

    • lastScheduleSize

      private int lastScheduleSize

    • lastScheduleEndMs

      private float lastScheduleEndMs

    • cachedEventOffsetsSamples

      private long[] cachedEventOffsetsSamples

    • lastRawScheduleRef

      private GestureSchedule lastRawScheduleRef

    • lastOffsetsParamsRef

      private GestureGranularParams lastOffsetsParamsRef

    • lastTransformedScheduleRef

      private GestureSchedule lastTransformedScheduleRef

    • lastOffsetsScheduleRef

      private GestureSchedule lastOffsetsScheduleRef

    • DEFAULT_GRAIN_WINDOW

      private static final ddf.minim.analysis.WindowFunction DEFAULT_GRAIN_WINDOW

  • Constructor Details

    • PAGranularInstrumentDirector

      public PAGranularInstrumentDirector(PAGranularInstrument instrument)
      Creates a director for the supplied granular instrument.
      Parameters:
      instrument - instrument used to schedule and render granular voices
      Throws:
      NullPointerException - if instrument is null

  • Method Details

    • resolveGrainWindow

      private static ddf.minim.analysis.WindowFunction resolveGrainWindow(GestureGranularParams params)

    • playGestureNow

      public void playGestureNow(float[] monoBuf, GestureSchedule schedule, GestureGranularParams params, int[] startIndices)
      Plays a gesture immediately using per-event source-buffer indices.

      The start time is the instrument's current sample cursor plus a short lead-in.

      Parameters:
      monoBuf - mono source buffer containing audio samples
      schedule - gesture schedule whose size must match startIndices.length
      params - runtime granular playback parameters
      startIndices - per-event start indices into monoBuf

    • playGestureNow

      public void playGestureNow(float[] monoBuf, GestureSchedule schedule, GestureGranularParams params, int[] startIndices, float[] panValues)
      Plays a gesture immediately using per-event source-buffer indices and pan overrides.
      Parameters:
      monoBuf - mono source buffer containing audio samples
      schedule - gesture schedule whose size must match the per-event arrays
      params - runtime granular playback parameters
      startIndices - per-event start indices into monoBuf
      panValues - optional per-event pan values

    • playGestureNow

      public void playGestureNow(float[] monoBuf, GestureSchedule schedule, GestureGranularParams params, GestureEventParams evtParams)
      Plays a gesture immediately using a complete per-event parameter object.
      Parameters:
      monoBuf - mono source buffer containing audio samples
      schedule - gesture schedule whose size must match evtParams.n
      params - runtime granular playback parameters
      evtParams - per-event source indices and optional pan, gain, and pitch overrides

    • playGestureAtSampleTime

      public void playGestureAtSampleTime(float[] monoBuf, GestureSchedule schedule, GestureGranularParams params, int[] startIndices, long startSampleTime)
      Schedules a gesture at an absolute sample time using per-event source-buffer indices.
      Parameters:
      monoBuf - mono source buffer containing audio samples
      schedule - gesture schedule whose size must match startIndices.length
      params - runtime granular playback parameters
      startIndices - per-event start indices into monoBuf
      startSampleTime - absolute sample time for the first gesture event

    • playGestureAtSampleTime

      public void playGestureAtSampleTime(float[] monoBuf, GestureSchedule schedule, GestureGranularParams params, int[] startIndices, float[] panValues, long startSampleTime)
      Schedules a gesture at an absolute sample time using source-buffer indices and pan overrides.
      Parameters:
      monoBuf - mono source buffer containing audio samples
      schedule - gesture schedule whose size must match the per-event arrays
      params - runtime granular playback parameters
      startIndices - per-event start indices into monoBuf
      panValues - optional per-event pan values
      startSampleTime - absolute sample time for the first gesture event

    • playGestureAtSampleTime

      public void playGestureAtSampleTime(float[] monoBuf, GestureSchedule schedule, GestureGranularParams params, GestureEventParams evtParams, long startSampleTime)
      Schedules a gesture at an absolute sample time using complete per-event parameters.

      This method prepares the schedule according to params, validates the per-event parameter count, caches event offsets in samples, and schedules one PABurstGranularSource for each event.

      Parameters:
      monoBuf - mono source buffer containing audio samples
      schedule - raw gesture schedule in milliseconds
      params - runtime granular playback parameters
      evtParams - per-event source indices and optional pan, gain, and pitch overrides
      startSampleTime - absolute sample time for the first gesture event

    • playGestureAtSampleTimeTransformed

      public void playGestureAtSampleTimeTransformed(float[] monoBuf, GestureSchedule transformedSchedule, GestureGranularParams params, GestureEventParams evtParams, long startSampleTime)
      Schedules a gesture whose timing has already been transformed.

      Use this overload when schedule preparation has been performed elsewhere and transformedSchedule.timesMs already contains the desired event offsets.

      Parameters:
      monoBuf - mono source buffer containing audio samples
      transformedSchedule - prepared schedule in milliseconds
      params - runtime granular playback parameters
      evtParams - per-event source indices and optional pan, gain, and pitch overrides
      startSampleTime - absolute sample time for the first gesture event

    • scheduleEvents

      private void scheduleEvents(float[] monoBuf, GestureSchedule sched, GestureGranularParams params, GestureEventParams evtParams, ddf.minim.analysis.WindowFunction wf, long startSampleTime)
      Creates and schedules one burst source for each gesture event.
      Parameters:
      monoBuf - mono source buffer containing audio samples
      sched - prepared gesture schedule in milliseconds
      params - runtime granular playback parameters
      evtParams - per-event source indices and optional pan, gain, and pitch overrides
      wf - grain window function resolved from params, or the default window
      startSampleTime - absolute sample time for the first gesture event

    • ensureCache

      private void ensureCache(GestureSchedule sched, GestureGranularParams params)

    • applyTimeTransform

      private static GestureSchedule applyTimeTransform(GestureSchedule rawSchedule, GestureGranularParams ggParams)
      Applies the director's schedule-time transform pipeline.

      The pipeline applies, in order, optional resampling, optional duration scaling, and optional timing warp. Callers normally reach this method through prepareSchedule(GestureSchedule, GestureGranularParams).

      Parameters:
      rawSchedule - original gesture schedule
      ggParams - runtime granular playback parameters
      Returns:
      transformed schedule, or the input schedule when no transform applies

    • prepareSchedule

      public GestureSchedule prepareSchedule(GestureSchedule rawSchedule, GestureGranularParams params)
      Returns a schedule prepared for playback by this director.

      If params.timeTransform is GestureGranularParams.TimeTransform.RAW_GESTURE, the raw schedule is returned unchanged. Otherwise this method applies the director's transform pipeline and caches the result by raw schedule and parameter object identity.

      Parameters:
      rawSchedule - original gesture schedule
      params - runtime granular playback parameters
      Returns:
      prepared schedule, or rawSchedule when no transform is needed

    • msToSamples

      private static long msToSamples(float ms, float sr)

    • resampleToCount

      private static GestureSchedule resampleToCount(GestureSchedule in, int targetCount)

    • scaleToDuration

      private static GestureSchedule scaleToDuration(GestureSchedule in, float targetDurationMs)

    • warpScheduleTimesMs

      private static GestureSchedule warpScheduleTimesMs(GestureSchedule in, GestureGranularParams.WarpShape shape, float exponent)

    • warpU

      private static float warpU(float u, GestureGranularParams.WarpShape shape, float exponent)

    • easeInOutPow

      private static float easeInOutPow(float u, float exp)

    • lerp

      private static float lerp(float a, float b, float u)

    • clampPan

      private static float clampPan(float p)

    • getInstrument

      public PAGranularInstrument getInstrument()
      Returns the underlying granular instrument.
      Returns:
      granular instrument used by this director

    • clearScheduled

      public void clearScheduled()
      Clears pending scheduled granular events without stopping voices already playing.

      For a musical stop, call this first and then call releaseAll().

    • releaseAll

      public void releaseAll()
      Releases all currently playing granular voices through their envelopes.

      A release is generally less abrupt than a stop, because each active voice is allowed to pass through its envelope release stage.

    • cancelAndStopAll

      public void cancelAndStopAll()
      Cancels pending events and stops all granular voices immediately.

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

    • cancelAndReleaseAll

      public void cancelAndReleaseAll()
      Cancels pending events and releases all granular voices through their envelopes.

      This is the less abrupt counterpart to cancelAndStopAll() and is generally better suited to musical fade-outs.

    • activeOrReleasingVoiceCount

      public int activeOrReleasingVoiceCount()
      Counts active or releasing granular voices in the underlying instrument.
      Returns:
      active or releasing voice count