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 &region)#

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.

note_on() / reset() clear it.

inline const LoopRegion &region() 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.