# Package net.paulhertz.pixelaudio.granular

package net.paulhertz.pixelaudio.granular
Granular synthesis classes for PixelAudio.

The modern granular synthesis engine follows the chain `PAGranularInstrumentDirector -> PAGranularInstrument -> PAGranularSampler -> PAGranularVoice`, with `PASource` implementations providing sample data and grain behavior. Example code makes exclusive use of `PABurstGranularSource` as the most versatile `PASource`.

Modern granular synthesis engine

- `PAGranularInstrumentDirector` coordinates gesture playback, scheduling, event parameters, and granular source creation.
- `PAGranularInstrument` provides the high-level instrument API for pan, gain, envelopes, looping, and scheduled starts.
- `PAGranularSampler` manages granular voices, voice pooling, and sample-accurate scheduling.
- `PAGranularVoice` renders individual granular voices with envelope, pan, gain, and optional looping.

Sources and audio data

- `PAFloatSource` defines the minimal audio source abstraction used by granular voices.
- `PASource` extends PAFloatSource with pitch-policy and buffer-access support.
- `PABurstGranularSource` provides windowed granular synthesis with normalization and powers the granular synthesis engine.

Gesture configuration and event data

- `GestureGranularConfig` stores editable gesture, timing, and synthesis settings, with builder support.
- `GestureGranularParams` provides immutable granular playback parameters used by the engine.
- `GestureEventParams` stores schedule-aligned sample indices and optional per-event pan, gain, and pitch data.

Utilities

- `WindowCache` caches generated window curves for granular playback.
- `OverlapUtil` computes block/span overlaps for sample-accurate audio processing.

- Related Packages
  Package
  Description
  net.paulhertz.pixelaudio
  Core classes for PixelAudio, a Processing library that maps between sound and image data.
  net.paulhertz.pixelaudio.curves
  Gesture, path, and Bézier curve modeling classes for PixelAudio.
  net.paulhertz.pixelaudio.example
  Package `net.paulhertz.pixelaudio.example` provides example Processing sketches and demonstrations of PixelAudio library functionality.
  net.paulhertz.pixelaudio.io
  Package `net.paulhertz.pixelaudio.io` provides JSON-based persistence for PixelAudio data structures.
  net.paulhertz.pixelaudio.sampler
  Digital audio sampling synthesis classes for PixelAudio, built on the Minim library for Processing.
  net.paulhertz.pixelaudio.schedule
  Package `net.paulhertz.pixelaudio.schedule` provides sample-accurate event scheduling, gesture-based time management, and audio utility functions for the PixelAudio library.
- Class
  Description
  GestureEventParams
  Immutable, schedule-aligned per-event parameters for gesture playback where each event accepts a buffer sample index and optional pan, gain, and pitch modifiers.
  GestureEventParams.Builder
  GestureGranularConfig
  Class for storing core parameters for both granular and sample synthesis engine events, used extensively in PixelAudio examples.
  GestureGranularConfig.Builder
  GestureGranularConfig.HopMode
  GestureGranularConfig.PathMode
  GestureGranularConfig.TimeTransform
  GestureGranularConfig.WarpShape
  GestureGranularParams
  Immutable core parameters for gesture-driven granular playback.
  GestureGranularParams.Builder
  GestureGranularParams.HopMode
  GestureGranularParams.TimeTransform
  UI preset hint for timing.
  GestureGranularParams.WarpShape
  OverlapUtil
  OverlapUtil Small helper for computing overlap between a span [spanStart, spanEnd) and a block [blockStart, blockStart+blockSize).
  OverlapUtil.Slice
  PABurstGranularSource
  Core class in the PAGranularInstrumentDirector granular synthesis processing chain, provides windowed granular synthesis with normalization.
  Calling chain: PAGranularInstrumentDirector -> PAGranularInstrument -> PAGranularSampler -> PAGranularVoice,
  with PABurstGranularSource handling the complexities of the granular synthesis sample by sample.
  PAFloatSource
  PAFloatSource Minimal, library-agnostic "audio source" abstraction for PixelAudio voices.
  PAGranularInstrument
  PAGranularInstrument High-level granular instrument wrapper.
  PAGranularInstrumentDirector
  The top-level entry point for Granular Synthesis in the PixelAudio library, PAGranularInstrumentDirector acts as a facade to `PAGranularInstrument`, calling PAGranularInstrument.play(...) with a `PABurstGranularSource` instance as a PASource and all necessary gesture and timing data.
  PAGranularSampler
  PAGranularSampler UGen-based multi-voice granular sampler.
  PAGranularSampler.ScheduledPlay
  PAGranularVoice
  PAGranularVoice A single granular "voice" driven by a PASource.
  PASource
  PASource A PAFloatSource with an additional pitch policy hint.
  WindowCache
  WindowCache Simple cache for windowFunction.generateCurve(length) results.
  WindowCache.Key