pulp::playback::MasterTransport Class Reference

Master musical transport with one control-thread writer and one audio-thread consumer. More...

#include <transport.hpp>

Public Member Functions
	MasterTransport ()=default
TransportError	prepare (const timebase::CompiledTempoMap &tempo_map, const MasterTransportConfig &config) noexcept
	tempo_map must outlive this transport or the next reset()/prepare().
TransportError	set_playing (bool playing) noexcept
TransportError	set_tempo_sync_tempo (double tempo_bpm) noexcept
	Publishes an explicit session-tempo request.
TransportError	seek (timebase::TickPosition position) noexcept
TransportError	set_loop (LoopRegion loop) noexcept
TransportError	set_meter (MeterSignature meter) noexcept
TransportError	begin_scrub (std::uint32_t window_frames, timebase::TickPosition position) noexcept
	Enters scrub mode: the transport renders repeated window_frames-long windows that each start at the latest posted anchor, which is how a dragged playhead becomes audible.
TransportError	scrub_to (timebase::TickPosition position) noexcept
	Moves the scrub anchor. Fails with NotScrubbing outside scrub mode.
TransportError	end_scrub () noexcept
	Leaves scrub mode and parks the playhead on the last posted anchor — where the drag was released — never mid-window.
TransportError	begin_block (std::uint32_t frame_count, TransportSnapshot &snapshot) noexcept
TransportError	begin_block (std::uint32_t frame_count, TempoSyncHostTime output_host_time, TransportSnapshot &snapshot) noexcept
	output_host_time names the first sample's output-boundary time and must have been produced by the configured TempoSyncSource.
TransportPlayhead	playhead () const noexcept
	The latest published playhead reading, by value.
TransportLoopState	loop_state () const noexcept
	The latest accepted loop state, including edits not yet consumed by an audio block.
void	reset () noexcept

Static Public Attributes
static constexpr audio::RtSafetyClass	begin_block_rt_safety_class

Detailed Description

Master musical transport with one control-thread writer and one audio-thread consumer.

Control methods publish one coherent desired-state snapshot through SeqLock. begin_block() is allocation-free and never locks.

Position travels in both directions, through one SeqLock each. The control thread states where playback should go; the audio thread publishes where it actually is, so a view can read the playhead without touching a callback.

Constructor & Destructor Documentation

MasterTransport()

pulp::playback::MasterTransport::MasterTransport ( )

default

Member Function Documentation

begin_block() [1/2]

TransportError pulp::playback::MasterTransport::begin_block ( std::uint32_t frame_count, TempoSyncHostTime output_host_time, TransportSnapshot & snapshot )

noexcept

output_host_time names the first sample's output-boundary time and must have been produced by the configured TempoSyncSource.

Required only when a source is configured; the ordinary document-clock path is unchanged.

begin_block() [2/2]

TransportError pulp::playback::MasterTransport::begin_block ( std::uint32_t frame_count, TransportSnapshot & snapshot )

noexcept

begin_scrub()

TransportError pulp::playback::MasterTransport::begin_scrub ( std::uint32_t window_frames, timebase::TickPosition position )

noexcept

Enters scrub mode: the transport renders repeated window_frames-long windows that each start at the latest posted anchor, which is how a dragged playhead becomes audible.

The anchor is latched, not immediate — a new position takes effect at the next window boundary, so the grain rate is the window length rather than the UI event rate. The window must be at least one maximum block so a block spans at most two windows, preserving the two-range snapshot contract.

Scrubbing suspends loop wrapping. A drag is a direct statement of position, so the transport must not pull the audible window back to the loop start or make positions outside the loop unreachable; the loop is still reported in the snapshot so a UI keeps drawing it, and wrapping resumes at end_scrub().

Starting a drag is itself immediate even mid-window: it abandons any window in flight so a fresh drag's window length takes effect at once.

end_scrub()

TransportError pulp::playback::MasterTransport::end_scrub ( )

noexcept

Leaves scrub mode and parks the playhead on the last posted anchor — where the drag was released — never mid-window.

loop_state()

TransportLoopState pulp::playback::MasterTransport::loop_state ( ) const

inlinenoexcept

The latest accepted loop state, including edits not yet consumed by an audio block.

A reset or failed prepare publishes prepared=false while retaining a monotonic sequence, so stale lifecycle state cannot look prepared merely because an older playhead had a nonzero sequence.

playhead()

TransportPlayhead pulp::playback::MasterTransport::playhead ( ) const

inlinenoexcept

The latest published playhead reading, by value.

Call it from any thread that is not the audio thread, as often as a frame needs it: it allocates nothing, takes no lock, and returns a coherent reading rather than one torn across a concurrent publish — at worst it retries while a publish is in flight. It returns the newest reading, never a backlog: a reader that skipped frames sees where playback is now, not where it was.

prepare()

TransportError pulp::playback::MasterTransport::prepare ( const timebase::CompiledTempoMap & tempo_map, const MasterTransportConfig & config )

noexcept

tempo_map must outlive this transport or the next reset()/prepare().

reset()

void pulp::playback::MasterTransport::reset ( )

noexcept

scrub_to()

TransportError pulp::playback::MasterTransport::scrub_to ( timebase::TickPosition position )

noexcept

Moves the scrub anchor. Fails with NotScrubbing outside scrub mode.

seek()

TransportError pulp::playback::MasterTransport::seek ( timebase::TickPosition position )

noexcept

set_loop()

TransportError pulp::playback::MasterTransport::set_loop ( LoopRegion loop )

noexcept

set_meter()

TransportError pulp::playback::MasterTransport::set_meter ( MeterSignature meter )

noexcept

set_playing()

TransportError pulp::playback::MasterTransport::set_playing ( bool playing )

noexcept

set_tempo_sync_tempo()

TransportError pulp::playback::MasterTransport::set_tempo_sync_tempo ( double tempo_bpm )

noexcept

Publishes an explicit session-tempo request.

This never edits the document TempoMap; it is sent to the configured TempoSyncSource at the next audio block.

Member Data Documentation

begin_block_rt_safety_class

audio::RtSafetyClass pulp::playback::MasterTransport::begin_block_rt_safety_class

staticconstexpr

Initial value:

=
        audio::RtSafetyClass::AudioCallbackSafeAfterPrepare

---

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

• /home/runner/work/pulp/pulp/core/playback/include/pulp/playback/transport.hpp