pulp::timeline::Sequence Class Reference

Immutable identity-bearing arrangement with tracks, annotations, context, and launch scenes. More...

#include <model.hpp>

Classes
class	SceneView
	Snapshot-owned random-access view preserving authored scene order. More...

Public Member Functions
ItemId	id () const noexcept
	Returns the stable sequence identity.
const std::string &	name () const noexcept
	Returns the authored sequence name.
std::optional< timebase::TickDuration >	duration () const noexcept
	Returns the optional musical duration in canonical ticks.
std::optional< AbsoluteTimelineDuration >	absolute_duration () const noexcept
	Returns the optional absolute duration and its rational rate.
std::span< const Track >	tracks () const noexcept
	Returns tracks in canonical identity order.
std::span< const ItemId >	track_order () const noexcept
	Returns track identities in authored top-to-bottom order.
std::span< const ItemId >	outgoing_sequence_refs () const noexcept
	Returns sorted unique referenced sequence identities derived from clips.
const Track *	find_track (ItemId id) const noexcept
	Finds a track by identity, or returns nullptr.
const ChordScaleLane &	chord_scale_lane () const noexcept
	Returns the always-present chord/scale context lane.
const DynamicsLane &	dynamics_lane () const noexcept
	Returns the always-present intensity context lane.
const GrooveTemplate &	groove () const noexcept
	Returns the always-present groove context.
std::span< const SequenceMarker >	markers () const noexcept
	Returns markers ordered by position then identity.
std::span< const SequenceRegion >	regions () const noexcept
	Returns regions ordered by position, duration, then identity.
SceneView	scenes () const noexcept
	Returns authored scenes and slots in persistent snapshot-owned storage.
const SequenceMarker *	find_marker (ItemId id) const noexcept
	Finds a marker by identity, or returns nullptr.
const SequenceRegion *	find_region (ItemId id) const noexcept
	Finds a region by identity, or returns nullptr.
const Scene *	find_scene (ItemId id) const noexcept
	Finds a scene by identity, or returns nullptr.
const Slot *	find_slot (ItemId id) const noexcept
	Finds a slot across all scenes by identity, or returns nullptr.
runtime::Result< Sequence, ModelError >	replace_track (Track track) const
	Returns a snapshot replacing an existing track by identity.
runtime::Result< Sequence, ModelError >	insert_track (Track track, std::optional< ItemId > before_track_id=std::nullopt) const
	Inserts track before an existing track in authored order, or appends.
runtime::Result< Sequence, ModelError >	move_track (ItemId track_id, std::optional< ItemId > before_track_id=std::nullopt) const
	Moves a track before an existing track in authored order, or to the end.
runtime::Result< Sequence, ModelError >	erase_track (ItemId id) const
	Removes a track and its owned clips by identity.
runtime::Result< Sequence, ModelError >	insert_marker (SequenceMarker marker) const
	Inserts a validated marker and returns a new snapshot.
runtime::Result< Sequence, ModelError >	erase_marker (ItemId id) const
	Removes a marker by identity and returns a new snapshot.
runtime::Result< Sequence, ModelError >	insert_region (SequenceRegion region) const
	Inserts a validated region and returns a new snapshot.
runtime::Result< Sequence, ModelError >	erase_region (ItemId id) const
	Removes a region by identity and returns a new snapshot.
runtime::Result< Sequence, ModelError >	replace_region (SequenceRegion replacement) const
	Replaces a region in place, keeping its identity, and returns a new snapshot.
runtime::Result< Sequence, ModelError >	insert_scene (Scene scene, std::optional< ItemId > before_scene_id=std::nullopt) const
	Inserts scene before an existing scene, or appends when no position is supplied.
runtime::Result< Sequence, ModelError >	erase_scene (ItemId id) const
	Removes a scene and its owned slots by identity.
runtime::Result< Sequence, ModelError >	insert_slot (ItemId scene_id, Slot slot, std::optional< ItemId > before_slot_id=std::nullopt) const
	Inserts slot in scene_id, before an existing slot or at the end.
runtime::Result< Sequence, ModelError >	erase_slot (ItemId scene_id, ItemId slot_id) const
	Removes slot_id from scene_id.
Sequence	with_chord_scale_lane (ChordScaleLane lane) const
	Returns a snapshot with replacement harmonic context.
Sequence	with_dynamics_lane (DynamicsLane lane) const
	Returns a snapshot with replacement intensity context.
Sequence	with_groove (GrooveTemplate groove) const
	Returns a snapshot with replacement groove context.
std::size_t	shared_launcher_nodes_with (const Sequence &other) const
	Counts persistent launcher nodes shared with other.
bool	shares_launcher_storage_with (const Sequence &other) const noexcept
	Returns whether both sequences share launcher collection storage.
bool	shares_storage_with (const Sequence &other) const noexcept
	Returns whether both values share complete immutable sequence storage.

Static Public Member Functions
static runtime::Result< Sequence, ModelError >	create (ItemId id, std::string name, std::optional< timebase::TickDuration > duration, std::vector< Track > tracks)
	Creates a musical sequence with tracks and no annotations or launch scenes.
static runtime::Result< Sequence, ModelError >	create (ItemId id, std::string name, std::optional< timebase::TickDuration > musical_duration, std::optional< AbsoluteTimelineDuration > absolute_duration, std::vector< Track > tracks)
	Creates a mixed-domain sequence with tracks and explicit optional durations.
static runtime::Result< Sequence, ModelError >	create (ItemId id, std::string name, std::optional< timebase::TickDuration > musical_duration, std::optional< AbsoluteTimelineDuration > absolute_duration, std::vector< Track > tracks, std::vector< SequenceMarker > markers, std::vector< SequenceRegion > regions)
	Creates a sequence with annotations and canonical default context.
static runtime::Result< Sequence, ModelError >	create (SequenceInput input)
	Validates and creates a sequence from all authored collections.
static runtime::Result< Sequence, ModelError >	create (ItemId id, std::string name, std::optional< timebase::TickDuration > musical_duration, std::optional< AbsoluteTimelineDuration > absolute_duration, std::vector< Track > tracks, std::vector< SequenceMarker > markers, std::vector< SequenceRegion > regions, ChordScaleLane chord_scale_lane)
	Creates a sequence with an explicit chord/scale context lane.
static LauncherIndexStats	launcher_index_stats () noexcept
	Returns process-wide persistent launcher-index diagnostic counters.

Friends
class	Project
struct	detail::SequenceEditAccess

Detailed Description

Immutable identity-bearing arrangement with tracks, annotations, context, and launch scenes.

Member Function Documentation

absolute_duration()

std::optional< AbsoluteTimelineDuration > pulp::timeline::Sequence::absolute_duration ( ) const

noexcept

Returns the optional absolute duration and its rational rate.

chord_scale_lane()

const ChordScaleLane & pulp::timeline::Sequence::chord_scale_lane ( ) const

noexcept

Returns the always-present chord/scale context lane.

create() [1/5]

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::create ( ItemId id, std::string name, std::optional< timebase::TickDuration > duration, std::vector< Track > tracks )

static

Creates a musical sequence with tracks and no annotations or launch scenes.

create() [2/5]

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::create ( ItemId id, std::string name, std::optional< timebase::TickDuration > musical_duration, std::optional< AbsoluteTimelineDuration > absolute_duration, std::vector< Track > tracks )

static

Creates a mixed-domain sequence with tracks and explicit optional durations.

create() [3/5]

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::create ( ItemId id, std::string name, std::optional< timebase::TickDuration > musical_duration, std::optional< AbsoluteTimelineDuration > absolute_duration, std::vector< Track > tracks, std::vector< SequenceMarker > markers, std::vector< SequenceRegion > regions )

static

Creates a sequence with annotations and canonical default context.

create() [4/5]

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::create ( ItemId id, std::string name, std::optional< timebase::TickDuration > musical_duration, std::optional< AbsoluteTimelineDuration > absolute_duration, std::vector< Track > tracks, std::vector< SequenceMarker > markers, std::vector< SequenceRegion > regions, ChordScaleLane chord_scale_lane )

static

Creates a sequence with an explicit chord/scale context lane.

create() [5/5]

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::create ( SequenceInput input )

static

Validates and creates a sequence from all authored collections.

duration()

std::optional< timebase::TickDuration > pulp::timeline::Sequence::duration ( ) const

noexcept

Returns the optional musical duration in canonical ticks.

dynamics_lane()

const DynamicsLane & pulp::timeline::Sequence::dynamics_lane ( ) const

noexcept

Returns the always-present intensity context lane.

A sequence that states no dynamics returns an empty lane rather than an absence, matching chord_scale_lane: callers ask the lane what it says at a position, and "nothing yet" is that lane's answer, not a missing lane.

erase_marker()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::erase_marker

(

ItemId

id

)

const

Removes a marker by identity and returns a new snapshot.

erase_region()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::erase_region

(

ItemId

id

)

const

Removes a region by identity and returns a new snapshot.

erase_scene()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::erase_scene

(

ItemId

id

)

const

Removes a scene and its owned slots by identity.

erase_slot()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::erase_slot	(	ItemId	scene_id,
		ItemId	slot_id ) const

Removes slot_id from scene_id.

erase_track()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::erase_track

(

ItemId

id

)

const

Removes a track and its owned clips by identity.

find_marker()

const SequenceMarker * pulp::timeline::Sequence::find_marker ( ItemId id ) const

noexcept

Finds a marker by identity, or returns nullptr.

find_region()

const SequenceRegion * pulp::timeline::Sequence::find_region ( ItemId id ) const

noexcept

Finds a region by identity, or returns nullptr.

find_scene()

const Scene * pulp::timeline::Sequence::find_scene ( ItemId id ) const

noexcept

Finds a scene by identity, or returns nullptr.

find_slot()

const Slot * pulp::timeline::Sequence::find_slot ( ItemId id ) const

noexcept

Finds a slot across all scenes by identity, or returns nullptr.

find_track()

const Track * pulp::timeline::Sequence::find_track ( ItemId id ) const

noexcept

Finds a track by identity, or returns nullptr.

groove()

const GrooveTemplate & pulp::timeline::Sequence::groove ( ) const

noexcept

Returns the always-present groove context.

id()

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

noexcept

Returns the stable sequence identity.

insert_marker()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::insert_marker

(

SequenceMarker

marker

)

const

Inserts a validated marker and returns a new snapshot.

insert_region()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::insert_region

(

SequenceRegion

region

)

const

Inserts a validated region and returns a new snapshot.

insert_scene()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::insert_scene	(	Scene	scene,
		std::optional< ItemId >	before_scene_id = std::nullopt ) const

Inserts scene before an existing scene, or appends when no position is supplied.

insert_slot()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::insert_slot	(	ItemId	scene_id,
		Slot	slot,
		std::optional< ItemId >	before_slot_id = std::nullopt ) const

Inserts slot in scene_id, before an existing slot or at the end.

insert_track()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::insert_track	(	Track	track,
		std::optional< ItemId >	before_track_id = std::nullopt ) const

Inserts track before an existing track in authored order, or appends.

The track itself is appended to tracks(), so existing identity order and every index derived from it stay put; only authored order records the requested position.

launcher_index_stats()

LauncherIndexStats pulp::timeline::Sequence::launcher_index_stats ( )

staticnoexcept

Returns process-wide persistent launcher-index diagnostic counters.

markers()

std::span< const SequenceMarker > pulp::timeline::Sequence::markers ( ) const

noexcept

Returns markers ordered by position then identity.

move_track()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::move_track	(	ItemId	track_id,
		std::optional< ItemId >	before_track_id = std::nullopt ) const

Moves a track before an existing track in authored order, or to the end.

This rewrites track_order() and nothing else: tracks(), every index derived from it, and the compile-structure token all carry over, because a reorder changes display order alone. Composing it out of erase and insert would instead rebuild the whole subtree, mint a fresh compile token, and refuse outright for a track whose clip a launcher slot sources.

before_track_id may not name the moved track itself.

name()

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

noexcept

Returns the authored sequence name.

outgoing_sequence_refs()

std::span< const ItemId > pulp::timeline::Sequence::outgoing_sequence_refs ( ) const

noexcept

Returns sorted unique referenced sequence identities derived from clips.

This index is not serialized.

regions()

std::span< const SequenceRegion > pulp::timeline::Sequence::regions ( ) const

noexcept

Returns regions ordered by position, duration, then identity.

replace_region()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::replace_region

(

SequenceRegion

replacement

)

const

Replaces a region in place, keeping its identity, and returns a new snapshot.

The replacement's identity must already name a region this sequence owns; the annotation validator and canonical ordering are reapplied whole, so a replacement that would not have been admitted as an insert is refused.

replace_track()

runtime::Result< Sequence, ModelError > pulp::timeline::Sequence::replace_track

(

Track

track

)

const

Returns a snapshot replacing an existing track by identity.

scenes()

SceneView pulp::timeline::Sequence::scenes ( ) const

noexcept

Returns authored scenes and slots in persistent snapshot-owned storage.

shared_launcher_nodes_with()

std::size_t pulp::timeline::Sequence::shared_launcher_nodes_with

(

const Sequence &

other

)

const

Counts persistent launcher nodes shared with other.

shares_launcher_storage_with()

bool pulp::timeline::Sequence::shares_launcher_storage_with ( const Sequence & other ) const

noexcept

Returns whether both sequences share launcher collection storage.

shares_storage_with()

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

noexcept

Returns whether both values share complete immutable sequence storage.

track_order()

std::span< const ItemId > pulp::timeline::Sequence::track_order ( ) const

noexcept

Returns track identities in authored top-to-bottom order.

Authored order is carried beside tracks(), never as a permutation of it: compile order, census counts, and render hashes read tracks() and must not move when a track is only reordered for display. A sequence constructed without a recorded order presents the identity order of tracks() here.

tracks()

std::span< const Track > pulp::timeline::Sequence::tracks ( ) const

noexcept

Returns tracks in canonical identity order.

with_chord_scale_lane()

Sequence pulp::timeline::Sequence::with_chord_scale_lane

(

ChordScaleLane

lane

)

const

Returns a snapshot with replacement harmonic context.

with_dynamics_lane()

Sequence pulp::timeline::Sequence::with_dynamics_lane

(

DynamicsLane

lane

)

const

Returns a snapshot with replacement intensity context.

with_groove()

Sequence pulp::timeline::Sequence::with_groove

(

GrooveTemplate

groove

)

const

Returns a snapshot with replacement groove context.

Friends And Related Symbol Documentation

detail::SequenceEditAccess

friend struct detail::SequenceEditAccess

friend

Project

friend class Project

friend

---

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

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