Immutable identity-bearing arrangement track. More...

#include <model.hpp>

Classes
class	ClipView
	Snapshot-owned random-access view of clips in timeline order. More...

Public Member Functions
runtime::Result< Track, ModelError >	insert_clip (Clip clip) const
	Returns a snapshot with a validated, non-overlapping clip inserted.
runtime::Result< Track, ModelError >	erase_clip (ItemId id) const
	Returns a snapshot without the identified clip, or MissingItem.
runtime::Result< Track, ModelError >	replace_clip (Clip replacement) const
	Replaces one clip by identity with O(log n) path-copy updates.
runtime::Result< Track, ModelError >	insert_automation_lane (AutomationLane lane) const
	Returns a snapshot with a validated automation lane inserted.
runtime::Result< Track, ModelError >	erase_automation_lane (ItemId id) const
	Returns a snapshot without the identified automation lane.
runtime::Result< Track, ModelError >	insert_modulator (Modulator modulator) const
	Returns a snapshot with a validated modulation source inserted.
runtime::Result< Track, ModelError >	erase_modulator (ItemId id) const
	Removes a modulation source; a route still reading it refuses.
runtime::Result< Track, ModelError >	replace_modulator (Modulator replacement) const
	Replaces one modulation source without changing its identity.
runtime::Result< Track, ModelError >	insert_macro (MacroControl macro) const
	Returns a snapshot with a validated macro control inserted.
runtime::Result< Track, ModelError >	erase_macro (ItemId id) const
	Removes a macro control; a route still reading it refuses.
runtime::Result< Track, ModelError >	replace_macro (MacroControl replacement) const
	Replaces one macro control without changing its identity.
runtime::Result< Track, ModelError >	insert_modulation_route (ModulationRoute route) const
	Returns a snapshot with a validated modulation route inserted.
runtime::Result< Track, ModelError >	erase_modulation_route (ItemId id) const
	Returns a snapshot without the identified modulation route.
runtime::Result< Track, ModelError >	replace_modulation_route (ModulationRoute replacement) const
	Replaces one modulation route without changing its identity.
runtime::Result< Track, ModelError >	insert_device (DevicePlacement placement, std::optional< ItemId > before_device_id=std::nullopt) const
	Inserts a typed device declaration at an authored position; empty appends.
runtime::Result< Track, ModelError >	erase_device (ItemId id) const
	Removes a device declaration; attached automation/modulation refuses.
runtime::Result< Track, ModelError >	move_device (ItemId id, std::optional< ItemId > before_device_id) const
	Moves a device in authored order; empty selects the final position.
runtime::Result< Track, ModelError >	replace_device (DevicePlacement replacement) const
	Replaces one declaration without changing its placement identity.
runtime::Result< Track, ModelError >	insert_take_lane (TakeLane lane) const
	Returns a snapshot with a validated take lane inserted.
runtime::Result< Track, ModelError >	erase_take_lane (ItemId id) const
	Removes a take lane unless it is currently selected.
runtime::Result< Track, ModelError >	insert_take (ItemId lane_id, Take take) const
	Inserts a take into lane_id and returns the new track snapshot.
runtime::Result< Track, ModelError >	erase_take (ItemId lane_id, ItemId take_id) const
	Removes a take unless the lane comp still references it.
runtime::Result< Track, ModelError >	with_take_comp (ItemId lane_id, std::vector< TakeCompSegment > comp) const
	Replaces one lane's comp with validated, canonical segments.
Track	with_record_armed (bool armed) const
	Returns a snapshot with record-arm intent set to armed.
runtime::Result< Track, ModelError >	with_active_take_lane (ItemId lane_id) const
	Selects arrangement when zero, or an existing take lane otherwise.
runtime::Result< Track, ModelError >	with_freeze (std::optional< TrackFreeze > freeze) const
	Publishes or clears a validated freeze artifact.
runtime::Result< Track, ModelError >	with_mixer (TrackMixer mixer) const
	Returns a snapshot with finite, in-range gain and pan.
runtime::Result< Track, ModelError >	with_tuning (std::optional< TuningReference > tuning) const
	Returns a snapshot carrying a replacement tuning override.
Track	with_name (std::string name) const
	Returns a snapshot carrying a replacement authored name.
ItemId	id () const noexcept
	Returns the stable track identity.
const std::string &	name () const noexcept
	Returns the authored track name.
ClipView	clips () const noexcept
	Returns clips ordered by anchor, start, then identity.
const Clip *	find_clip (ItemId id) const noexcept
	Finds a clip by identity, or returns nullptr.
std::span< const DevicePlacement >	device_chain () const noexcept
	Returns device placements in authored processing order.
const DevicePlacement *	find_device_placement (ItemId id) const noexcept
	Finds a device placement by identity, or returns nullptr.
std::span< const AutomationLane >	automation_lanes () const noexcept
	Returns automation lanes in canonical identity order.
const AutomationLane *	find_automation_lane (ItemId id) const noexcept
	Finds an automation lane by identity, or returns nullptr.
std::span< const Modulator >	modulators () const noexcept
	Returns modulators in canonical identity order.
const Modulator *	find_modulator (ItemId id) const noexcept
	Finds a modulator by identity, or returns nullptr.
std::span< const MacroControl >	macros () const noexcept
	Returns macro controls in canonical identity order.
const MacroControl *	find_macro (ItemId id) const noexcept
	Finds a macro control by identity, or returns nullptr.
std::span< const ModulationRoute >	modulation_routes () const noexcept
	Returns modulation routes in canonical identity order.
const ModulationRoute *	find_modulation_route (ItemId id) const noexcept
	Finds a modulation route by identity, or returns nullptr.
std::vector< ModulationRoute >	routes_from_source (ItemId source_id) const
	Returns the routes drawing from source_id, in canonical identity order.
std::span< const TakeLane >	take_lanes () const noexcept
	Returns take lanes in canonical identity order.
const TakeLane *	find_take_lane (ItemId id) const noexcept
	Finds a take lane by identity, or returns nullptr.
bool	record_armed () const noexcept
	Returns document intent for capture into a take lane.
ItemId	active_take_lane_id () const noexcept
	Returns zero for arrangement playback or the selected take-lane identity.
const std::optional< TrackFreeze > &	freeze () const noexcept
	Returns the published optional freeze artifact.
const TrackMixer &	mixer () const noexcept
	Returns the authored track mixer.
const std::optional< TuningReference > &	tuning () const noexcept
	Returns the tuning this track overrides the project's with, if any.
std::size_t	shared_index_nodes_with (const Track &other) const
	Counts persistent clip-index nodes shared with other.
bool	shares_clip_membership_with (const Track &other) const noexcept
	Returns whether both snapshots contain the same clip identities.
bool	shares_storage_with (const Track &other) const noexcept
	Returns whether both values reference the same complete track storage.

Static Public Member Functions
static runtime::Result< Track, ModelError >	create (ItemId id, std::string name, std::vector< Clip > clips)
	Creates a track containing only its identity, name, and clips.
static runtime::Result< Track, ModelError >	create (TrackInput input)
	Validates and creates a track from all authored collections.
static TrackIndexStats	index_stats () noexcept
	Returns process-wide persistent clip-index diagnostic counters.

Friends
class	Sequence

Detailed Description

Immutable identity-bearing arrangement track.

Owned collections use persistent storage. Successful edits return a new Track and preserve this snapshot and all borrowed views into it.

Member Function Documentation

◆ active_take_lane_id()

ItemId pulp::timeline::Track::active_take_lane_id ( ) const

noexcept

Returns zero for arrangement playback or the selected take-lane identity.

◆ automation_lanes()

std::span< const AutomationLane > pulp::timeline::Track::automation_lanes ( ) const

noexcept

Returns automation lanes in canonical identity order.

◆ clips()

ClipView pulp::timeline::Track::clips ( ) const

noexcept

Returns clips ordered by anchor, start, then identity.

◆ create() [1/2]

runtime::Result< Track, ModelError > pulp::timeline::Track::create	(	ItemId	id,
		std::string	name,
		std::vector< Clip >	clips )

static

Creates a track containing only its identity, name, and clips.

◆ create() [2/2]

runtime::Result< Track, ModelError > pulp::timeline::Track::create ( TrackInput input )

static

Validates and creates a track from all authored collections.

◆ device_chain()

std::span< const DevicePlacement > pulp::timeline::Track::device_chain ( ) const

noexcept

Returns device placements in authored processing order.

◆ erase_automation_lane()

runtime::Result< Track, ModelError > pulp::timeline::Track::erase_automation_lane ( ItemId id ) const

Returns a snapshot without the identified automation lane.

◆ erase_clip()

runtime::Result< Track, ModelError > pulp::timeline::Track::erase_clip ( ItemId id ) const

Returns a snapshot without the identified clip, or MissingItem.

◆ erase_device()

runtime::Result< Track, ModelError > pulp::timeline::Track::erase_device ( ItemId id ) const

Removes a device declaration; attached automation/modulation refuses.

◆ erase_macro()

runtime::Result< Track, ModelError > pulp::timeline::Track::erase_macro ( ItemId id ) const

Removes a macro control; a route still reading it refuses.

◆ erase_modulation_route()

runtime::Result< Track, ModelError > pulp::timeline::Track::erase_modulation_route ( ItemId id ) const

Returns a snapshot without the identified modulation route.

Nothing reads a route, so this is the one modulation removal no other member can refuse: the source it named stays and only the connection goes.

◆ erase_modulator()

runtime::Result< Track, ModelError > pulp::timeline::Track::erase_modulator ( ItemId id ) const

Removes a modulation source; a route still reading it refuses.

◆ erase_take()

runtime::Result< Track, ModelError > pulp::timeline::Track::erase_take	(	ItemId	lane_id,
		ItemId	take_id ) const

Removes a take unless the lane comp still references it.

◆ erase_take_lane()

runtime::Result< Track, ModelError > pulp::timeline::Track::erase_take_lane ( ItemId id ) const

Removes a take lane unless it is currently selected.

◆ find_automation_lane()

const AutomationLane * pulp::timeline::Track::find_automation_lane ( ItemId id ) const

noexcept

Finds an automation lane by identity, or returns nullptr.

◆ find_clip()

const Clip * pulp::timeline::Track::find_clip ( ItemId id ) const

noexcept

Finds a clip by identity, or returns nullptr.

Returned storage is snapshot-owned.

◆ find_device_placement()

const DevicePlacement * pulp::timeline::Track::find_device_placement ( ItemId id ) const

noexcept

Finds a device placement by identity, or returns nullptr.

◆ find_macro()

const MacroControl * pulp::timeline::Track::find_macro ( ItemId id ) const

noexcept

Finds a macro control by identity, or returns nullptr.

◆ find_modulation_route()

const ModulationRoute * pulp::timeline::Track::find_modulation_route ( ItemId id ) const

noexcept

Finds a modulation route by identity, or returns nullptr.

◆ find_modulator()

const Modulator * pulp::timeline::Track::find_modulator ( ItemId id ) const

noexcept

Finds a modulator by identity, or returns nullptr.

◆ find_take_lane()

const TakeLane * pulp::timeline::Track::find_take_lane ( ItemId id ) const

noexcept

Finds a take lane by identity, or returns nullptr.

◆ freeze()

const std::optional< TrackFreeze > & pulp::timeline::Track::freeze ( ) const

noexcept

Returns the published optional freeze artifact.

◆ id()

ItemId pulp::timeline::Track::id ( ) const

noexcept

Returns the stable track identity.

◆ index_stats()

TrackIndexStats pulp::timeline::Track::index_stats ( )

staticnoexcept

Returns process-wide persistent clip-index diagnostic counters.

◆ insert_automation_lane()

runtime::Result< Track, ModelError > pulp::timeline::Track::insert_automation_lane ( AutomationLane lane ) const

Returns a snapshot with a validated automation lane inserted.

◆ insert_clip()

runtime::Result< Track, ModelError > pulp::timeline::Track::insert_clip ( Clip clip ) const

Returns a snapshot with a validated, non-overlapping clip inserted.

◆ insert_device()

runtime::Result< Track, ModelError > pulp::timeline::Track::insert_device	(	DevicePlacement	placement,
		std::optional< ItemId >	before_device_id = std::nullopt ) const

Inserts a typed device declaration at an authored position; empty appends.

◆ insert_macro()

runtime::Result< Track, ModelError > pulp::timeline::Track::insert_macro ( MacroControl macro ) const

Returns a snapshot with a validated macro control inserted.

◆ insert_modulation_route()

runtime::Result< Track, ModelError > pulp::timeline::Track::insert_modulation_route ( ModulationRoute route ) const

Returns a snapshot with a validated modulation route inserted.

◆ insert_modulator()

runtime::Result< Track, ModelError > pulp::timeline::Track::insert_modulator ( Modulator modulator ) const

Returns a snapshot with a validated modulation source inserted.

◆ insert_take()

runtime::Result< Track, ModelError > pulp::timeline::Track::insert_take	(	ItemId	lane_id,
		Take	take ) const

Inserts a take into lane_id and returns the new track snapshot.

◆ insert_take_lane()

runtime::Result< Track, ModelError > pulp::timeline::Track::insert_take_lane ( TakeLane lane ) const

Returns a snapshot with a validated take lane inserted.

◆ macros()

std::span< const MacroControl > pulp::timeline::Track::macros ( ) const

noexcept

Returns macro controls in canonical identity order.

◆ mixer()

const TrackMixer & pulp::timeline::Track::mixer ( ) const

noexcept

Returns the authored track mixer.

◆ modulation_routes()

std::span< const ModulationRoute > pulp::timeline::Track::modulation_routes ( ) const

noexcept

Returns modulation routes in canonical identity order.

◆ modulators()

std::span< const Modulator > pulp::timeline::Track::modulators ( ) const

noexcept

Returns modulators in canonical identity order.

◆ move_device()

runtime::Result< Track, ModelError > pulp::timeline::Track::move_device	(	ItemId	id,
		std::optional< ItemId >	before_device_id ) const

Moves a device in authored order; empty selects the final position.

◆ name()

const std::string & pulp::timeline::Track::name ( ) const

noexcept

Returns the authored track name.

◆ record_armed()

bool pulp::timeline::Track::record_armed ( ) const

noexcept

Returns document intent for capture into a take lane.

◆ replace_clip()

runtime::Result< Track, ModelError > pulp::timeline::Track::replace_clip ( Clip replacement ) const

Replaces one clip by identity with O(log n) path-copy updates.

The old Track remains valid; untouched index subtrees are shared.

◆ replace_device()

runtime::Result< Track, ModelError > pulp::timeline::Track::replace_device ( DevicePlacement replacement ) const

Replaces one declaration without changing its placement identity.

◆ replace_macro()

runtime::Result< Track, ModelError > pulp::timeline::Track::replace_macro ( MacroControl replacement ) const

Replaces one macro control without changing its identity.

◆ replace_modulation_route()

runtime::Result< Track, ModelError > pulp::timeline::Track::replace_modulation_route ( ModulationRoute replacement ) const

Replaces one modulation route without changing its identity.

◆ replace_modulator()

runtime::Result< Track, ModelError > pulp::timeline::Track::replace_modulator ( Modulator replacement ) const

Replaces one modulation source without changing its identity.

◆ routes_from_source()

std::vector< ModulationRoute > pulp::timeline::Track::routes_from_source ( ItemId source_id ) const

Returns the routes drawing from source_id, in canonical identity order.

This is the fan-out of one macro or modulator: the set a removal has to account for, and the set an inverse has to restore.

◆ shared_index_nodes_with()

std::size_t pulp::timeline::Track::shared_index_nodes_with ( const Track & other ) const

Counts persistent clip-index nodes shared with other.

◆ shares_clip_membership_with()

bool pulp::timeline::Track::shares_clip_membership_with ( const Track & other ) const

noexcept

Returns whether both snapshots contain the same clip identities.

Clip content and timing may differ.

◆ shares_storage_with()

bool pulp::timeline::Track::shares_storage_with ( const Track & other ) const

noexcept

Returns whether both values reference the same complete track storage.

◆ take_lanes()

std::span< const TakeLane > pulp::timeline::Track::take_lanes ( ) const

noexcept

Returns take lanes in canonical identity order.

◆ tuning()

const std::optional< TuningReference > & pulp::timeline::Track::tuning ( ) const

noexcept

Returns the tuning this track overrides the project's with, if any.

◆ with_active_take_lane()

runtime::Result< Track, ModelError > pulp::timeline::Track::with_active_take_lane ( ItemId lane_id ) const

Selects arrangement when zero, or an existing take lane otherwise.

◆ with_freeze()

runtime::Result< Track, ModelError > pulp::timeline::Track::with_freeze ( std::optional< TrackFreeze > freeze ) const

Publishes or clears a validated freeze artifact.

◆ with_mixer()

runtime::Result< Track, ModelError > pulp::timeline::Track::with_mixer ( TrackMixer mixer ) const

Returns a snapshot with finite, in-range gain and pan.

◆ with_name()

Track pulp::timeline::Track::with_name ( std::string name ) const

Returns a snapshot carrying a replacement authored name.

Owned collection storage and the compile-structure token are shared with the old Track: a name is a label, not a processing property.

◆ with_record_armed()

Track pulp::timeline::Track::with_record_armed ( bool armed ) const

Returns a snapshot with record-arm intent set to armed.

Owned collection storage is shared with the old Track.

◆ with_take_comp()

runtime::Result< Track, ModelError > pulp::timeline::Track::with_take_comp	(	ItemId	lane_id,
		std::vector< TakeCompSegment >	comp ) const

Replaces one lane's comp with validated, canonical segments.

◆ with_tuning()

runtime::Result< Track, ModelError > pulp::timeline::Track::with_tuning ( std::optional< TuningReference > tuning ) const

Returns a snapshot carrying a replacement tuning override.

An absent override hands the track back to the project's tuning. A stated one is admitted only when valid_tuning_reference accepts it, the same helper Track::create applies, so a snapshot cannot hold a tuning a fresh construction would refuse.

◆ Sequence

friend class Sequence

friend

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

/home/runner/work/pulp/pulp/core/timeline/include/pulp/timeline/model.hpp

Pulp 1.88.0 Cross-platform audio plugin framework

Classes

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ active_take_lane_id()

◆ automation_lanes()

◆ clips()

◆ create() [1/2]

◆ create() [2/2]

◆ device_chain()

◆ erase_automation_lane()

◆ erase_clip()

◆ erase_device()

◆ erase_macro()

◆ erase_modulation_route()

◆ erase_modulator()

◆ erase_take()

◆ erase_take_lane()

◆ find_automation_lane()

◆ find_clip()

◆ find_device_placement()

◆ find_macro()

◆ find_modulation_route()

◆ find_modulator()

◆ find_take_lane()

◆ freeze()

◆ id()

◆ index_stats()

◆ insert_automation_lane()

◆ insert_clip()

◆ insert_device()

◆ insert_macro()

◆ insert_modulation_route()

◆ insert_modulator()

◆ insert_take()

◆ insert_take_lane()

◆ macros()

◆ mixer()

◆ modulation_routes()

◆ modulators()

◆ move_device()

◆ name()

◆ record_armed()

◆ replace_clip()

◆ replace_device()

◆ replace_macro()

◆ replace_modulation_route()

◆ replace_modulator()

◆ routes_from_source()

◆ shared_index_nodes_with()

◆ shares_clip_membership_with()

◆ shares_storage_with()

◆ take_lanes()

◆ tuning()

◆ with_active_take_lane()

◆ with_freeze()

◆ with_mixer()

◆ with_name()

◆ with_record_armed()

◆ with_take_comp()

◆ with_tuning()

Friends And Related Symbol Documentation

◆ Sequence