zrythm::dsp::Playhead Class Reference

Provides thread-safe playhead positioning with sample-accurate timing. More...

#include <src/dsp/playhead.h>

Public Member Functions
	Playhead (const TempoMap &tempo_map)
	Construct a Playhead associated with a TempoMap.
void	advance_processing (units::sample_t nframes) noexcept
	Advance processing position (audio thread safe).
auto	position_during_processing_precise () const noexcept
	Get current position during processing (audio thread safe).
units::sample_t	position_during_processing_rounded () const noexcept
void	set_position_ticks (units::precise_tick_t ticks)
	Set playhead position in musical ticks (GUI thread only).
auto	position_ticks () const
	Get current playhead position in ticks (GUI thread only).
void	update_ticks_from_samples ()
	Update tick position from sample position.
const auto &	get_tempo_map () const
auto	position_samples_FOR_TESTING () const noexcept
	Get current playhead position in samples (non-RT).

Friends
class	PlayheadProcessingGuard
void	to_json (nlohmann::json &j, const Playhead &pos)
void	from_json (const nlohmann::json &j, Playhead &pos)

Detailed Description

Provides thread-safe playhead positioning with sample-accurate timing.

The Playhead class maintains synchronized position information in both samples (for audio processing) and ticks (for musical operations). It guarantees real-time safety for audio threads while allowing GUI updates.

Definition at line 62 of file playhead.h.

Constructor & Destructor Documentation

Playhead()

zrythm::dsp::Playhead::Playhead ( const TempoMap & tempo_map )

inline

Construct a Playhead associated with a TempoMap.

Parameters

tempo_map

Reference to project's TempoMap

Definition at line 71 of file playhead.h.

Member Function Documentation

advance_processing()

void zrythm::dsp::Playhead::advance_processing ( units::sample_t nframes )

inlinenoexcept

Advance processing position (audio thread safe).

Parameters

nframes

Number of frames advanced (negative for backwards, eg when looping back)

Warning

Must only be called from the system audio callback thread.

Definition at line 99 of file playhead.h.

get_tempo_map()

const auto & zrythm::dsp::Playhead::get_tempo_map ( ) const

inline

Definition at line 194 of file playhead.h.

position_during_processing_precise()

auto zrythm::dsp::Playhead::position_during_processing_precise ( ) const

inlinenoexcept

Get current position during processing (audio thread safe).

Returns

Position in samples as double

Note

Can be called concurrently from multiple audio threads

Definition at line 119 of file playhead.h.

position_during_processing_rounded()

units::sample_t zrythm::dsp::Playhead::position_during_processing_rounded ( ) const

inlinenoexcept

Definition at line 123 of file playhead.h.

position_samples_FOR_TESTING()

auto zrythm::dsp::Playhead::position_samples_FOR_TESTING ( ) const

inlinenoexcept

Get current playhead position in samples (non-RT).

Note

For testing and debugging only

Definition at line 200 of file playhead.h.

position_ticks()

auto zrythm::dsp::Playhead::position_ticks ( ) const

inline

Get current playhead position in ticks (GUI thread only).

Returns

Position in ticks

Definition at line 173 of file playhead.h.

set_position_ticks()

void zrythm::dsp::Playhead::set_position_ticks ( units::precise_tick_t ticks )

inline

Set playhead position in musical ticks (GUI thread only).

Parameters

ticks

New position in ticks

Note

Uses mutex to synchronize with GUI thread

Definition at line 161 of file playhead.h.

update_ticks_from_samples()

void zrythm::dsp::Playhead::update_ticks_from_samples ( )

inline

Update tick position from sample position.

To be called periodically as part of the GUI event loop to synchronize positions

Definition at line 187 of file playhead.h.

Friends And Related Symbol Documentation

from_json

void from_json ( const nlohmann::json & j, Playhead & pos )

friend

Definition at line 211 of file playhead.h.

PlayheadProcessingGuard

friend class PlayheadProcessingGuard

friend

Definition at line 64 of file playhead.h.

to_json

void to_json ( nlohmann::json & j, const Playhead & pos )

friend

Definition at line 207 of file playhead.h.

---

The documentation for this class was generated from the following file:

• src/dsp/playhead.h