Class thl::dsp::sampler::SamplePlayer#
-
class SamplePlayer#
A varispeed sample player / looper: one continuous interpolating play head over a region of a sample, click-free at every discontinuity.
sampler::SamplePlayer player; player.prepare(48000.0); player.note_on(); const auto source = sampler::SampleView::of(buffer); player.set_markers(0.25f, 0.75f, 0.5f); player.render({&source, 1}, 0, outputs, 2, 256);
- Region
Start / End / Loop come from set_markers() (normalised, with a minimum span and optional zero-crossing snap, see LoopMarkers) or from set_region() (an exact region, e.g. a slice). End before Start plays backwards; moving either marker never moves the audible head.
- Loop
With loop on, the head wraps from End to Loop through a loop crossfade (see LoopFadePlan): over the last stretch before End the head blends into the audio before Loop, or, without room there, fades out a copy running past End after the wrap. Equal-power, or equal-gain when the join is in phase (snapped). While a loop fade runs the region is held; marker moves land at the wrap. With loop off the head plays Start -> End once and then reports finished().
- Sources
render() takes a span of alternative sources (e.g. pitch-shifted copies, round-robins) and the index to play. Sources must be equal-length and time-aligned: switching keeps the head position and crossfades. A source that becomes empty reads as silence.
- Discontinuities
A source switch, a retrigger, End moved behind the head or a one-shot reaching End park a copy of the head in a small pool of outgoing heads that fade out while the live head fades back in. A second discontinuity inside a fade parks the head again with its current gain.
- Real-Time Safety
prepare() allocates. Everything else is real-time safe and allocation free; the setters are meant to be called once per block before render() on the audio thread.
Public Functions
-
SamplePlayer() = default#
-
SamplePlayer(const SamplePlayer&) = delete#
-
SamplePlayer &operator=(const SamplePlayer&) = delete#
-
void prepare(double sample_rate, const PlayerSettings &settings = {})#
Build the fade table and derive frame lengths. Allocates; not RT-safe.
-
void reset()#
Stop and forget the head and every tail.
-
void note_on()#
Note-on: a head that is still sounding crossfades back to the region start on the next render; a silent one restarts cold.
-
inline void set_markers(float start, float end, float loop)#
Normalised Start / End / Loop, resolved per block with the minimum span and (if enabled) snap.
Replaces a region set by set_region().
-
inline void set_region(const LoopRegion ®ion)#
An exact region in frames (no minimum span, no snap, never in phase).
Replaces the markers until set_markers() is called again.
-
inline void set_speed(float speed)#
Playback rate (1 = original speed and pitch), clamped to the settings.
-
inline void set_loop(bool loop)#
Loop (true) or play once (false).
-
inline void set_snap(bool snap)#
Snap markers to upward zero crossings (see LoopMarkers).
-
inline void sources_changed()#
The audio behind the sources changed in place or was replaced.
Snapped markers are cached against a source’s address and length; a new sample of the same length can land at the same address. Call this whenever the host loads new audio (it is cheap: the next render re-resolves the markers).
-
bool render(std::span<const SampleView> sources, size_t source, float *const *out, size_t num_channels, size_t num_frames)#
Render one block.
Writes source channel c into
out[c]for c < num_channels; a mono source feeds every channel, channels past a multichannel source’s own are silent. The output is overwritten, not mixed into.- Returns:
false on a silent early-out (no source, empty source, empty region), which also resets the player.
-
inline bool started() const#
The head is playing (between the first render after note_on() and reset() / an early-out).
-
inline bool just_started() const#
The render that just ran started the head.
-
inline bool finished() const#
One-shot reached End: its tail is fading, the head renders silence.
-
inline const LoopRegion ®ion() const#
Region of the last render.
-
inline size_t source_frames() const#
Frames of the source the last render played.
-
inline float speed() const#
Clamped playback rate of the last render.
-
float normalized_position() const#
Head as a fraction of the source, kept inside the region (a finished one-shot parks past End).
0 when nothing played.