streaming_sample_source.hpp File Reference

Real-time-safe streaming sample playback primitive. More...

#include <atomic>
#include <cstdint>
#include <functional>
#include <thread>
#include <pulp/audio/buffer.hpp>
#include <pulp/runtime/wake_signal.hpp>
#include <pulp/audio/planar_audio_ring_buffer.hpp>

Go to the source code of this file.

Classes
class	pulp::audio::FrameReaderStopToken
	Cooperative cancellation signal passed to a streaming frame reader. More...
struct	pulp::audio::FrameReaderBinding
struct	pulp::audio::StreamingSampleSourceConfig
class	pulp::audio::StreamingSampleSource
struct	pulp::audio::StreamingSampleSource::Stats

Namespaces
namespace	pulp
namespace	pulp::audio

Typedefs
using	pulp::audio::FrameReader
	Caller-supplied random-access frame reader.
using	pulp::audio::StoppableFrameReader

Enumerations
enum class	pulp::audio::FrameReaderStopMode : std::uint8_t { pulp::audio::JoinOnly , pulp::audio::Cooperative }
enum class	pulp::audio::StreamingUnderrunPolicy : std::uint8_t { pulp::audio::PreservePosition = 0 , pulp::audio::AdvancePosition }

Detailed Description

Real-time-safe streaming sample playback primitive.

Plays a long sample without holding the whole thing resident in RAM, and without ever blocking the audio thread on disk/decoder I/O. The model is a resident preload window (the head of the sample, kept in memory for a glitch-free note-on) followed by a streamed tail served from a single-producer/single-consumer ring buffer that a background reader thread keeps topped up.

Short samples (total length <= preload window) take a zero-overhead fully-resident fast path: no ring, no background thread, free looping. This makes the primitive useful for one sequential long-sample transport beside resident short material. Polyphonic samplers should share decoded pages through SampleStreamCacheService rather than instantiate this source, its ring, and its worker once per voice (see docs/guides/streaming-sample-source.md).

Thread model:

• prepare()/release()/reset() — control thread, may allocate, never on the audio thread.
• pull() — audio thread, RT-safe after prepare: allocation-free, lock-free, wait-free, zero-fills on underrun.
• the background reader — one owned std::thread that calls the caller-supplied FrameReader off the audio thread. Disable it (start_background_thread = false) and drive pump_background() manually for deterministic tests.