Package net.paulhertz.pixelaudio.sampler

package net.paulhertz.pixelaudio.sampler

Digital audio sampling synthesis classes for PixelAudio.

PixelAudio's sampler engine follows the chain PASamplerInstrumentPoolMulti -> PASamplerInstrumentPool -> PASamplerInstrument -> PASharedBufferSampler -> PASamplerVoice. Small sketches may use PASamplerInstrument directly, while larger gesture-driven sketches can route playback through one or more instrument pools.

The package provides shared-buffer sample playback, polyphonic sampler instruments, ADSR envelope support, pitch and pan controls, gain staging, and event objects used by gesture-driven sampler workflows. It is built on the Minim library for Processing.

Immediate playback and scheduled playback both follow the same hierarchy. Calls made on PASamplerInstrumentPoolMulti, PASamplerInstrumentPool, or PASamplerInstrument are forwarded to the level below, ending in PASharedBufferSampler, where voices are allocated and mixed. The scheduled playback API mirrors the granular synthesis API with startAtSampleTime(...) and startAfterDelaySamples(...) methods. These methods schedule against the sampler's local audio-thread sample clock, exposed by getCurrentSampleTime().

For cross-engine alignment, such as playing sampler and granular instruments from the same generated beat brush, application code should choose a shared transport clock and convert gesture or beat times to absolute sample times before calling either synth. The sampler-local clock is the timing mechanism for one sampler backend; it is not, by itself, a global application transport.

Sampler playback can optionally wrap finite source-buffer reads across the buffer boundary. This is distinct from looping: a wrapped event still ends according to its requested duration and envelope, but reads that pass the end of the buffer continue from the beginning.

Sampler playback processing chain

1. PASamplerInstrumentPoolMulti manages named sampler pools and routes playback to the active pool or a tagged pool.
2. PASamplerInstrumentPool owns a reusable group of sampler instruments, selects an available instrument for each event, and propagates buffer, gain, pan, pitch, and envelope defaults.
3. PASamplerInstrument applies instrument-level gain, pitch, pan, envelope defaults, and sample-rate correction, then forwards playback requests to the sampler backend.
4. PASharedBufferSampler owns the voice pool for one shared mono buffer, starts voices, mixes active voices into Minim's audio callback, and applies mix normalization and soft clipping.
5. PASamplerVoice reads samples from the source buffer, applies per-voice gain, pan, pitch, envelope state, looping state, and release/finish lifecycle handling.

Sampler synthesis engine

• PASamplerInstrument provides the high-level instrument API for pan, gain, pitch scaling, envelopes, buffer replacement, and sampler backend access.
• PASamplerInstrumentPool manages a collection of sampler instruments for polyphony, reuse, and group gain.
• PASamplerInstrumentPoolMulti manages multiple sampler pools for multi-buffer or multi-sample playback.
• PASharedBufferSampler manages sampler voices, voice pooling, looping defaults, panning, gain, smooth voice stealing, finite-event wrap-around, and mix profiles.
• PASamplerVoice renders individual sampler voices with gain, pitch, pan, and optional ADSR envelope.

Interfaces and event data

• PAPlayable defines the minimal playable audio API used by sampler instruments and pools.
• PASampler defines the backend sampler contract, including immediate playback, scheduled playback, looping, stop, source-buffer playback sample rate, and buffer update methods.
• PASamplerPlayable extends PAPlayable for sample-based playback with buffer position, duration, gain, pitch, pan, and envelope parameters.
• PlaybackInfo stores computed duration and timing information for triggered sampler events.
• PitchPolicy defines pitch behavior for sample playback.
• SamplerBrushEvent stores gesture-derived sampler event data such as location, timing, sample position, gain, pitch, pan, and envelope.

Envelope support

• ADSRParams stores parameters for ADSR envelopes and can create Minim ADSR instances.
• ADSRUtils provides utility methods for fitting envelope times to event durations.
• SimpleADSR provides a sample-by-sample ADSR envelope used by sampler voices.

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	Example Processing sketches and demonstrations of PixelAudio library functionality.
net.paulhertz.pixelaudio.granular	Granular synthesis classes for PixelAudio.
net.paulhertz.pixelaudio.io	JSON-based persistence for PixelAudio data structures supported by file i/o classes.
net.paulhertz.pixelaudio.schedule	Sample-accurate event scheduling, gesture-based time management, and audio utility functions.

Class	Description
ADSRParams	Value object describing an ADSR envelope.
ADSRUtils	Utility functions for ADSRParams.
PAPlayable	Generic interface for anything that can be "played." Provides a minimal playback API plus backward-compatible overloads for sampler instruments and other PAPlayable classes.
PASampler	Backend engine contract for sampler implementations.
PASamplerInstrument	Represents a playable instrument that uses a PASampler instantiated as a PASharedBufferSampler to trigger audio playback from a shared buffer that is (currently) a Minim MultiChannelBuffer.
PASamplerInstrumentPool	Manages a group of PASamplerInstruments sharing the same source buffer and audio output.
PASamplerInstrumentPoolMulti	PASamplerInstrumentPoolMulti Manages multiple PASamplerInstrumentPool instances, each keyed by name.
PASamplerPlayable	Specialized playable interface for sample-based instruments.
PASamplerVoice	PASamplerVoice - a single playback "voice" reading from a shared mono buffer.
PASharedBufferSampler	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).
PASharedBufferSampler.MixProfile	Mix-density normalization profiles for polyphonic sampler output, used to control noise and distortion.
PASharedBufferSampler.ScheduledPlay
PitchPolicy	PitchPolicy determines how PASamplerInstrument / PASamplerVoice should interpret their pitch parameter in combination with a given PASource.
PlaybackInfo	Holds information about a triggered playback event.
SamplerBrushEvent	Stores values used for SamplerBrush event staging, used in tutorial examples such as TutorialOne_03_Drawing.
SimpleADSR	SimpleADSR - software envelope generator with optional exponential curves.
SimpleADSR.Stage