pulp::playback Namespace Reference

Namespaces
namespace	detail

Classes
struct	AudioRendererError
struct	DecodedAudioAsset
class	DecodedAudioAssetPool
	Immutable, ID-sorted ownership table prepared off the audio thread. More...
struct	ClipPlacementFadeSegment
	One placement-fade ramp a flattened leaf sits under, in clip-relative frames. More...
struct	ClipPlacementFadeProgram
	Every placement fade one flattened leaf sits under. More...
struct	AudioClipRendererProgram
class	AudioTrackRendererProgram
class	ArrangementAudioRenderer
	Renders every arrangement-selected audio track in PlaybackProgram order. More...
class	ArrangementAudioTrackRenderer
	One stable SignalGraph-facing arrangement audio renderer. More...
class	TrackMixerTrackRenderer
	Stable SignalGraph-facing post-device track mixer. More...
struct	AudioRendererLimits
	Shared compile and RT ceilings. More...
struct	AutomationBlockEvent
struct	AutomationCursorResult
class	AutomationSegmentView
	Random-access, immutable segment storage used by the production cursor. More...
class	AutomationProgramView
	The identity, exact tempo-map object, and immutable segments consumed by AutomationCursor. More...
class	AutomationCursor
	Allocation-free renderer for one immutable AutomationProgram. More...
struct	AutomationPlaybackLimits
	Preparation and callback-work ceilings shared by document compilation and track automation rendering. More...
struct	AutomationProgramInstanceToken
struct	AutomationProgramError
struct	AutomationProgramSegment
class	AutomationProgram
	Immutable tick- and sample-domain form of one automation lane. More...
struct	RecordedAutomationPoint
struct	MaterializedAutomationCurve
class	AutomationRecorder
	Captures parameter gestures into a bounded point stream. More...
struct	BufferedContentSourceConfig
class	BufferedContentSource
struct	CaptureTrackConfig
struct	CaptureEngineConfig
struct	CaptureSession
struct	CaptureTakeHandle
struct	CapturedMidiEvent
struct	CaptureCommand
struct	CaptureEvent
struct	CaptureEngineStats
class	CaptureEngine
	Fixed-capacity input recorder. More...
struct	ChordPatternContent
	Immutable authored settings for the deterministic chord-pattern compiler. More...
struct	LaunchEvent
class	LaunchHandle
struct	FollowActionEvent
class	FollowActionTimer
struct	ContentFragmentNote
	One musical note emitted by a registered content compiler. More...
struct	ContentFragmentError
class	ContentProgramFragment
	Owned immutable note output from one off-realtime compile-hook invocation. More...
struct	RegisteredContentCompileInput
	Bounded input presented to a trusted compiler hook on the compile worker. More...
struct	ContentRendererRegistration
	One content renderer's registration, reduced to the part the dirty set depends on: which content kind it renders, and which timeline context its compile hook reads beyond that content. More...
struct	ContextRegistrationError
class	CompileContextRegistry
	The declaration side of the compile-context subscription contract. More...
class	CompileInvalidationIndex
	Bundled reverse index for nested dependencies and compile-context readers. More...
struct	CompileSliceBudget
class	CompileTask
class	CompileExecutor
class	DeferredCompileExecutor
class	WorkerCompileExecutor
struct	DirtyTrackSet
struct	EventCompensationShift
	One event-injection point's prepared scheduling shift, counted in samples at the program's compiled sample rate. More...
struct	EventCompensationResult
struct	CompensatedReadSegment
	One contiguous run of a compensated read window after an enabled loop has been applied to it. More...
struct	CompensatedReadPlan
	How a compensated read window resolves against an enabled loop. More...
struct	MtcTimecode
struct	MtcChaseUpdate
class	MtcChaser
	Allocation-free MTC decoder. More...
struct	ExternalSyncOutputConfig
struct	ExternalSyncOutputResult
class	ExternalSyncOutput
	Stateless block projection from the musical transport to MIDI sync. More...
struct	GeneratedEventSpan
	A half-open span on the transport's non-looping clock. More...
struct	GeneratedEvent
	One value-owned generated event. More...
struct	GeneratedEventDegradationLadder
struct	GeneratedEventSourceConfig
struct	GeneratedEventStageResult
struct	GeneratedEventCommitResult
struct	GeneratedEventPullResult
class	GeneratedEventSource
struct	MidiCaptureMaterializationConfig
struct	MaterializedMidiCapture
struct	NoteRenderResult
class	ArrangementNoteRenderer
	Arrangement-note scheduler for the engine transport-tick lane. More...
struct	OfflineStretchAlgorithmConfig
struct	OfflineStretchArtifactKey
struct	OfflineStretchArtifact
struct	OfflineStretchProvenance
struct	OfflineStretchError
struct	OfflineStretchLimits
class	OfflineStretchArtifactCache
	Control-thread-only bounded semantic artifact cache. More...
class	OfflineStretchCompileJob
	Control-thread-only resumable source-SRC-stretch-seal pipeline. More...
struct	ProgramError
struct	ProviderSelectorProgram
struct	NoteProgramEvent
	Immutable arrangement-note event lowered by the program compiler. More...
struct	CompiledNoteModifier
	One note's playback modifier, lowered with its draw key already folded from the content's authored seed and the note identity. More...
struct	ControllerProgramEvent
	Immutable controller/expression value lowered by the program compiler. More...
class	TrackProgram
class	PlaybackProgram
class	PlaybackProgramStore
struct	TrackCompilePolicy
struct	CompileInvalidationInput
	One committed document delta lowered through the compile-context registry. More...
struct	ProgramCompileRequest
struct	CompileError
struct	CompileTicket
struct	CompilerStatus
class	PlaybackProgramCompiler
struct	RendererProgramKey
struct	ProgramWireError
struct	ProgramWireHeader
	The fixed prefix every payload starts with. More...
struct	ProgramWireSectionEntry
struct	ProgramWireProgramRecord
	The whole-program scalars, including the tempo map's sample rate and the automation ceilings the adopting realm must render within. More...
struct	ProgramWireTempoPointRecord
	The editable tempo points, not the compiled segments. More...
struct	ProgramWireTrackRecord
	One track. More...
struct	ProgramWireIdRecord
struct	ProgramWireNoteEventRecord
	This happens to hold the same fields in the same order as NoteProgramEvent, and that correspondence is coincidental and must not be relied on. More...
struct	ProgramWireNoteModifierRecord
struct	ProgramWireControllerRangeRecord
	One track's range into the ControllerEvents section. More...
struct	ProgramWireControllerEventRecord
	One ControllerProgramEvent, field by field — never cast between the two, for the reason given on ProgramWireNoteEventRecord. More...
struct	ProgramWireAutomationLaneRecord
	instance_token is the producer's own AutomationProgram::instance_token() carried verbatim, because lane identity is not (lane_id, generation) alone. More...
struct	ProgramWireAutomationSegmentRecord
	Deliberately not laid out like AutomationProgramSegment: this groups the three floats and puts interpolation last so the record packs to 48 bytes with one run of padding, where the program type interleaves them. More...
class	ProgramWireView
	A validated, zero-copy view over one encoded program generation. More...
class	ProgramWireBytePin
	A unique lease over immutable publication bytes. More...
struct	ProgramWireAdoptionResult
struct	ProgramWireLaneIdentity
struct	ProgramWireLaneState
	One caller-provided fixed-capacity state slot. More...
struct	ProgramWireAutomationLaneOutput
struct	ProgramWireAutomationRenderResult
class	ProgramWireAutomationConsumer
	Allocation-free automation consumer over one uniquely pinned wire payload. More...
class	RealtimeStretchProgramRuntime
	One exact-publication live Stretch runtime. More...
struct	RealtimeStretchStateSpec
struct	RealtimeStretchStateBankAdmission
class	RealtimeStretchStateBank
	Control-thread-prepared bank of clip-keyed realtime stretch processors. More...
struct	RecordingTakeCommitRequest
struct	SealedRecordingTake
struct	RecordingSource
struct	RecordingTrackConfig
struct	RecordingCoordinatorConfig
class	RecordingMediaStager
	Package-neutral durability boundary used before a Timeline transaction is published. More...
struct	CommittedRecordingTake
class	RecordingCoordinator
	Control-thread coordinator for capture completion, calibrated placement, media durability, and one atomic Timeline publication. More...
struct	RendererCarryState
class	PlaybackProgramBlock
class	PlaybackProgramBlockLatch
struct	StableRendererBlockView
class	StableRendererShell
class	TempoSyncHostTime
	Opaque host-clock timestamp produced by the TempoSyncSource that owns the corresponding clock domain. More...
struct	TempoSyncCommand
	Backend-independent command bundle applied at the first output sample of an audio block. More...
struct	TempoSyncBlockRequest
	Timing information for one audio callback. More...
struct	TempoSyncBlockState
	Captured session mapping at both boundaries of one audio block. More...
struct	TempoSyncPlayingProjection
	Block-coherent projection of a timestamped start/stop state. More...
class	TempoSyncSource
	Backend-neutral session-tempo boundary. More...
struct	TrackAutomationProgramError
class	TrackAutomationProgram
	Immutable compiler-supplied grouping of one track's compiled automation lanes. More...
struct	TrackAutomationEvent
struct	DeviceAutomationBatch
struct	TrackAutomationRendererError
struct	TrackAutomationRenderResult
class	TrackAutomationRenderer
	Allocation-free block renderer for one prepared track automation program. More...
struct	TrackMixerProgram
	The compiled form of a track's own level and stereo placement. More...
struct	TrackMixerChannelGains
	Per-side multipliers for a stereo balance. More...
class	TrackMixerControlCursor
	Streams one mixer control's value in timeline-sample order without allocating. More...
struct	TransportRange
struct	TransportSnapshot
struct	TransportPlayhead
	Where the transport is, published for a reader that is not the audio thread. More...
struct	TransportLoopState
	The transport's accepted loop control state. More...
struct	MasterTransportConfig
class	MasterTransport
	Master musical transport with one control-thread writer and one audio-thread consumer. More...
struct	LaunchQuantize
	Musical-boundary quantization for one launch. More...

Typedefs
using	BufferedContentEpoch = std::uint64_t
	Identifies one continuous production interval.
using	BufferedContentProducer
	Caller-supplied producer of buffered content.
using	RegisteredContentCompileFn
using	GeneratedEventCommitGeneration = std::uint64_t
using	GeneratedEventRevision = std::uint64_t
using	ProgramGeneration = std::uint64_t
using	MeterSignature = timebase::MeterSignature
using	LoopRegion = timebase::LoopRegion
	The loop is a pair of document positions, so the timebase owns it and every rung that describes a loop names the same type.

Enumerations
enum class	AudioRendererErrorCode : std::uint8_t {   InvalidIdentity , DuplicateAsset , MissingDecodedAsset , InvalidAsset ,   AssetMetadataMismatch , UnsupportedSampleRate , InvalidClipRange , InvalidFade ,   CapacityExceeded , InvalidTakeComp , OfflineStretchRequired , OfflineStretchFailed }
enum class	AudioRenderStatus : std::uint8_t {   Rendered , Silent , InvalidProgram , InvalidTransport ,   InvalidOutput , CapacityExceeded , RealtimeStretchStateRequired , RealtimeStretchGap ,   RealtimeStretchStalePublication , RealtimeStretchImpossibleRatio , RealtimeStretchBackpressure , RealtimeStretchUnderflow ,   RealtimeStretchUnsupportedScrubbing }
enum class	AutomationTransition : std::uint8_t { Seed , Immediate , LinearRamp }
enum class	AutomationCursorCode : std::uint8_t {   Ok , Coalesced , AdoptionRejected , InvalidTransport ,   TempoMapMismatch , InsufficientCapacity , WorkCapacityExceeded }
enum class	AutomationProgramAdoption : std::uint8_t { Adopted , Unchanged , Rejected }
enum class	AutomationProgramErrorCode : std::uint8_t { InvalidGeneration , MissingTempoMap , UnsupportedTarget , InstanceTokenExhausted }
enum class	AutomationRecordMode : std::uint8_t { Touch , Latch , Write }
enum class	AutomationRecordError : std::uint8_t {   None , NotPrepared , NotRecording , InvalidValue ,   NonMonotonicPosition , CapacityExceeded }
enum class	AutomationCurveMaterializationError : std::uint8_t { NoPoints , IdentityExhausted , InvalidCurve }
enum class	CaptureCommandType : std::uint8_t { Start , Stop , Cancel , ReleaseTake }
enum class	CaptureEventType : std::uint8_t {   Started , TakeCompleted , Stopped , Cancelled ,   CommandRejected , NoFreeTakeSlot , TakeCapacityExceeded , MidiCapacityExceeded ,   TakeCancelled }
enum class	CaptureProcessResult : std::uint8_t { Ok , NotPrepared , InvalidBuffers , InvalidTransport }
enum class	LaunchState : std::uint8_t { Stopped , Armed , Playing , Stopping }
enum class	LaunchEventKind : std::uint8_t { None , Start , Stop }
enum class	ContentProgramOutputKind : std::uint8_t { Notes }
	The immutable program-fragment family emitted by a registered compiler. More...
enum class	RegisteredRendererStatePolicy : std::uint8_t { Reset , CarryByItemId }
	Registered note fragments currently admit Reset only. More...
enum class	ContentFragmentErrorCode : std::uint8_t { RendererFailed , InvalidNote }
enum class	ContextRegistrationErrorCode : std::uint8_t {   EmptyContentTypeName , DuplicateContentType , CapacityExceeded , InvalidSchemaVersion ,   SchemaUnavailable , SchemaCodecUnavailable , InvalidFragmentQuota , InvalidProductionDeclaration ,   MissingCompileHook , InvalidOutputKind , InvalidStatePolicy }
enum class	CompileTaskStatus { Pending , Complete }
enum class	EventCompensationCode : std::uint8_t { Ok , NegativeDeviceLatency , DeviceLatencyOutOfRange , ChainShiftOutOfRange }
enum class	MtcFrameRate : std::uint8_t { Fps24 , Fps25 , Fps2997Drop , Fps30 }
enum class	MtcChaseCode : std::uint8_t {   Ignored , Incomplete , Locked , Discontinuity ,   Invalid }
enum class	MtcDirection : std::int8_t { Reverse = -1 , Unknown = 0 , Forward = 1 }
enum class	ExternalSyncOutputCode : std::uint8_t {   Complete , InvalidTransport , InvalidSampleRate , InvalidFrameRate ,   InvalidOutputLimit , OutputOverflow }
enum class	GeneratedEventDegradation : std::uint8_t { None , RepeatLastCommitted , UseSkeleton , Silence }
enum class	GeneratedEventStageCode : std::uint8_t {   Staged , Revised , NotPrepared , EpochNotStarted ,   WrongEpoch , InvalidSpan , NotQuantized , InvalidRevision ,   StaleRevision , FrozenSpan , OutOfOrder , OverlappingSpan ,   InvalidEvent , EventCapacityExceeded , StagingCapacityExceeded }
enum class	GeneratedEventCommitCode : std::uint8_t {   Committed , NotPrepared , EpochNotStarted , WrongEpoch ,   InvalidBoundary , InvalidGeneration , StaleGeneration , CommitRingFull }
enum class	GeneratedEventPullCode : std::uint8_t { Ready , Starved , OutputOverflow , InvalidRequest }
enum class	MidiCaptureMaterializationError : std::uint8_t { InvalidConfig , IdentityExhausted , InvalidNotes , SampleRateMismatch }
enum class	NoteRenderCode : std::uint8_t {   Ok , NotPrepared , MissingProgram , AdoptionRejected ,   InvalidTransport , TempoMapMismatch , ActiveStateOverflow , OutputOverflow ,   CompensationUnsupported }
enum class	OfflineStretchErrorCode : std::uint8_t {   None , InvalidClip , MissingSource , AssetMetadataMismatch ,   UnsupportedSampleRate , InvalidAlgorithmConfig , InvalidTempoSchedule , CapacityExceeded ,   SampleRateConverterPrepareFailed , ProcessorPrepareFailed , InvalidRatio , OutputTooShort ,   OutputTooLong , ProcessorProtocolError }
enum class	OfflineStretchCompileStatus : std::uint8_t { Progress , Complete , Failed }
enum class	ProgramErrorCode : std::uint8_t {   InvalidGeneration , InvalidIdentity , DuplicateTrack , DuplicateClip ,   MissingTempoMap }
enum class	ProviderKind : std::uint8_t { Arrangement , Launcher , ExternalInput }
enum class	RendererStatePolicy : std::uint8_t { Stateless , CarryByItemId }
enum class	NoteProgramEventKind : std::uint8_t { Off , On }
enum class	ControllerProgramEventOrigin : std::uint8_t { Authored , Chased }
	Whether a lowered controller value was authored at its own position or synthesized at a window boundary to answer "what is sounding here". More...
enum class	CompileErrorCode : std::uint8_t {   InvalidRequest , StaleRevision , ExecutorUnavailable , InvalidStructure ,   GenerationExhausted , CompilerAlreadyBound , AudioProgramInvalid , AutomationProgramInvalid ,   ExpansionBudgetExceeded , NoteProgramCapacityExceeded , OfflineStretchFailed , TrimmedMidiLaneUnsupported ,   MidiExpressionLaneUnsupported , MidiExpressionLaneBudgetExceeded , TrimmedGrooveUnsupported , UnresolvedRegisteredContent ,   RegisteredContentCompileFailed , RegisteredContentFragmentQuotaExceeded , NestedMixerPanUnsupported , NestedGainSinkUnsupported ,   NestedPlacementFadeUnsupported , NestedFrozenTrackUnsupported , NestedActiveTakeUnsupported , NestedDeviceChainUnsupported ,   NestedAutomationPanUnsupported , NestedAutomationGainEventLeafUnsupported , NestedAutomationGainMediaUnsupported , NestedConformedTrimUnsupported ,   NestedAbsoluteChildUnsupported }
enum class	ProgramWireSection : std::uint32_t {   Program = 1 , TempoPoints = 2 , Tracks = 3 , ClipIds = 4 ,   NoteEvents = 5 , NoteModifiers = 6 , DevicePlacementIds = 7 , AutomationLanes = 8 ,   AutomationSegments = 9 , ControllerRanges = 10 , ControllerEvents = 11 }
enum class	AutomationEvaluationRate : std::uint8_t { SampleAccurate = 0 , BlockRate = 1 }
	How often the adopting realm must evaluate one automation lane. More...
enum class	ProgramWireTargetKind : std::uint8_t { DeviceParameter = 0 , TrackMixer = 1 }
enum class	ProgramWireErrorCode : std::uint8_t {   InsufficientCapacity , MisalignedBuffer , TempoMapMismatch , AudioProgramUnsupported ,   ProductionDeclarationUnsupported , MixerAutomationUnresolved , CountOverflow , ShortBuffer ,   BadMagic , UnsupportedVersion , BadHeaderSize , ChecksumMismatch ,   SectionOutOfBounds , SectionsNotTiled , SectionMisaligned , NonCanonicalSectionOrder ,   DuplicateSection , UnknownSection , MissingSection , TrailingData ,   BadRecordSize , BadSectionCardinality , RangeOutOfBounds , NonCanonicalRangeOwnership ,   AutomationTargetUnresolved , DuplicateAutomationTarget , StaleLaneGeneration , InvalidEnum ,   MalformedNoteModifier , MalformedSegment , MalformedControllerEvent , InvalidSampleRate ,   InvalidLimits , InvalidProducerEpoch , InvalidInstanceToken }
enum class	ProgramWireConsumerCode : std::uint8_t {   Ok , DecodeRejected , TempoMapMismatch , StateCapacityExceeded ,   StalePublication , MissingProgram , InvalidTransport , OutputCapacityExceeded ,   CursorRejected }
enum class	ProgramWireAdoption : std::uint8_t { Adopted , Unchanged , Rejected }
enum class	RealtimeStretchRenderCode : std::uint8_t {   NotRequired , Rendered , GapIdentityChanged , StateRequired ,   StalePublication , UnsupportedScrubbing , ImpossibleRatio , Backpressure ,   Underflow }
enum class	RealtimeStretchStateBankError : std::uint8_t {   None , InvalidConfiguration , InvalidIdentity , DuplicateIdentity ,   StateLimitExceeded , ChannelLimitExceeded , TimeRatioLimitExceeded , StateBytesExceeded ,   ProcessorPrepareRejected , AllocationFailed }
enum class	RecordingCommitError : std::uint8_t {   InvalidRequest , UnsupportedWaveShape , WaveSizeExceeded , HashFailure ,   InvalidTake , InvalidTakeLane , RetrospectiveUnavailable }
enum class	RecordingMonitorMode : std::uint8_t { Off , Direct , Software , Auto }
enum class	RecordingMonitorPath : std::uint8_t { Off , Direct , Software }
enum class	RecordingCoordinatorError : std::uint8_t {   NotPrepared , StaleLatency , InvalidTake , CaptureCopyFailed ,   SealFailed , MediaStageFailed , DocumentCommitFailed }
enum class	ShellAdoptionResult : std::uint8_t { Adopted , Unchanged , Missing , Rejected }
enum class	TempoSyncPlayingBoundary : std::uint8_t { BeforeOrAtBlockStart , InsideBlock , AtOrAfterBlockEnd }
enum class	TempoSyncError : std::uint8_t {   None , Disabled , InvalidRequest , InvalidState ,   BackendFailure }
enum class	TrackAutomationProgramErrorCode : std::uint8_t {   InvalidTrackId , MissingTempoMap , MissingProgram , InvalidLaneId ,   TempoMapMismatch , DuplicateLane , DuplicateTarget }
enum class	TrackAutomationRendererCode : std::uint8_t {   Ok , Coalesced , MissingProgram , TrackMismatch ,   InvalidTransport , TempoMapMismatch , LaneAdoptionRejected , LaneCapacityExceeded ,   PointCapacityExceeded , DeviceCapacityExceeded , WorkCapacityExceeded , InvalidLimits }
enum class	TrackAutomationRendererAdoption : std::uint8_t { Adopted , Unchanged }
enum class	TransportError {   None , NotPrepared , InvalidMeter , InvalidLoop ,   LoopTooShortForMaximumBlock , InvalidFrameCount , InvalidScrubWindow , ScrubWindowTooShortForMaximumBlock ,   NotScrubbing , InvalidTempo , InvalidTempoSyncConfig , TempoSyncHostTimeRequired ,   TempoSyncUnavailable , InvalidTempoSyncState , PlaybackEpochExhausted }

Functions
runtime::Result< AudioClipRendererProgram, AudioRendererError >	compile_audio_clip_program (const timeline::Clip &clip, const timeline::Project &project, const timebase::CompiledTempoMap &tempo_map, const DecodedAudioAssetPool &assets, const AudioRendererLimits &limits)
runtime::Result< AudioClipRendererProgram, AudioRendererError >	compile_take_comp_segment_program (const timeline::TakeLane &lane, std::size_t segment_index, const timeline::Project &project, const timebase::CompiledTempoMap &tempo_map, const DecodedAudioAssetPool &assets, const AudioRendererLimits &limits)
	Lowers one canonical take-comp selection to the same immutable audio-region artifact used by arrangement clips.
runtime::Result< AudioClipRendererProgram, AudioRendererError >	compile_track_freeze_program (const timeline::Track &track, const timeline::Project &project, const timebase::CompiledTempoMap &tempo_map, const DecodedAudioAssetPool &assets, const AudioRendererLimits &limits)
	Lowers a track's selected freeze artifact to one immutable audio region.
runtime::Result< std::shared_ptr< const AudioTrackRendererProgram >, AudioRendererError >	link_audio_track_program (timeline::ItemId track_id, std::vector< AudioClipRendererProgram > clips, const AudioRendererLimits &limits)
std::size_t	select_automation_segment (const AutomationProgram &program, timebase::SamplePosition sample, bool cold, std::size_t segment_index) noexcept
	Selects the segment governing an absolute timeline sample.
float	evaluate_automation_segment (const AutomationProgram &program, std::size_t segment_index, timebase::SamplePosition sample, timebase::TickPosition tick) noexcept
	The authored value of one already-selected segment at an exact tick.
runtime::Result< timeline::SchemaRegistration, timeline::SchemaError >	register_chord_pattern_content_schema (timeline::SchemaRegistryBuilder &builder)
	Registers the exact versioned Content schema and codec.
runtime::Result< timeline::RegisteredContent, timeline::PersistenceError >	create_chord_pattern_content (const ChordPatternContent &content, const timeline::SchemaRegistry &schemas, std::size_t maximum_json_bytes=1024)
	Creates schema-backed chord-pattern content after strict payload validation.
std::optional< ContextRegistrationError >	declare_chord_pattern_renderer (CompileContextRegistry &registry, const timeline::SchemaRegistry &schemas)
	Declares the trusted deterministic note compiler and its ChordScale read.
constexpr timebase::MonotonicBeat	next_launch_boundary (timebase::MonotonicBeat from, LaunchQuantize quantize) noexcept
std::optional< std::uint32_t >	resolve_launch_sample (const TransportSnapshot &snapshot, const timebase::CompiledTempoMap &tempo_map, timebase::MonotonicBeat target) noexcept
DirtyTrackSet	resolve_dirty_tracks (const timeline::Project &project, timeline::ItemId root_sequence_id, const timeline::DirtySet &dirty, const CompileInvalidationIndex &index)
	Canonical translation from transaction dirtiness to root-track compiler dirtiness.
constexpr EventCompensationResult	accumulate_event_chain_shift (std::span< const int > device_latency_samples, int ceiling_samples) noexcept
	Accumulates the event-domain latency of one chain into a scheduling shift.
constexpr timebase::SamplePosition	shifted_range_origin (const TransportRange &range, EventCompensationShift shift) noexcept
	The sample position an event stream at a compensated injection point must be read from for range.
constexpr bool	range_admits_event_compensation (const TransportRange &range, EventCompensationShift shift) noexcept
	Whether a compensating shift has a defined meaning for range.
constexpr bool	loop_admits_event_compensation (const TransportRange &range, EventCompensationShift shift, timebase::SamplePosition loop_end_samples) noexcept
	Whether a compensating shift's read-ahead stays inside an enabled loop.
constexpr CompensatedReadPlan	plan_compensated_read (const TransportRange &range, EventCompensationShift shift) noexcept
	The one run a window that no loop bounds resolves to.
constexpr CompensatedReadPlan	plan_compensated_read (const TransportRange &range, EventCompensationShift shift, timebase::SamplePosition loop_start_samples, timebase::SamplePosition loop_end_samples) noexcept
	Wrap-aware read-ahead: the runs a compensated window reads when an enabled loop bounds it.
constexpr bool	event_compensation_admits_live_input (EventCompensationShift shift, ProviderSelectorProgram provider) noexcept
	Whether a track may offer live input while its event chain is compensated.
bool	valid_mtc_timecode (const MtcTimecode &timecode) noexcept
timebase::SamplePosition	mtc_timecode_to_samples (const MtcTimecode &timecode, timebase::RationalRate sample_rate) noexcept
	Convert between an MTC wall-clock label and a non-negative timeline sample.
MtcTimecode	samples_to_mtc_timecode (timebase::SamplePosition position, timebase::RationalRate sample_rate, MtcFrameRate frame_rate) noexcept
runtime::Result< MaterializedMidiCapture, MidiCaptureMaterializationError >	materialize_midi_capture (std::span< const CapturedMidiEvent > events, MidiCaptureMaterializationConfig config)
timeline::ProductionDeclaration	provider_production_declaration (ProviderSelectorProgram provider) noexcept
	What content served by provider declares about its production.
timeline::ProductionDeclaration	track_production_declaration (const TrackProgram &track) noexcept
	What a single track's compiled content declares about its production.
timeline::ReproducibilityClass	program_reproducibility (const PlaybackProgram &program) noexcept
	The weakest claim any track in the program is entitled to make.
runtime::Result< ProgramGeneration, ProgramError >	next_program_generation (ProgramGeneration current) noexcept
const CompiledNoteModifier *	find_note_modifier (std::span< const CompiledNoteModifier > modifiers, timeline::ItemId note_id) noexcept
	Looks up the modifier for note_id in a table sorted by note id.
constexpr bool	controller_program_event_less (const ControllerProgramEvent &lhs, const ControllerProgramEvent &rhs) noexcept
	Total order for controller events sharing a block.
constexpr bool	note_program_event_less (const NoteProgramEvent &lhs, const NoteProgramEvent &rhs) noexcept
constexpr bool	is_monotonic_renderer_adoption (RendererProgramKey active, RendererProgramKey candidate) noexcept
constexpr std::uint64_t	program_wire_checksum (std::span< const std::byte > bytes) noexcept
	FNV-1a over 64 bits.
std::uint64_t	program_wire_process_epoch () noexcept
	A nonzero value that is stable for this process and differs between processes.
runtime::Result< std::size_t, ProgramWireError >	program_wire_encoded_size (const PlaybackProgram &program, std::span< const timebase::TempoPoint > tempo_points) noexcept
	Bytes encode_program_wire needs for this program.
runtime::Result< std::size_t, ProgramWireError >	encode_program_wire (const PlaybackProgram &program, std::span< const timebase::TempoPoint > tempo_points, std::uint64_t producer_epoch, std::span< std::byte > out) noexcept
	Writes program into out and returns the bytes written.
runtime::Result< ProgramWireView, ProgramWireError >	decode_program_wire (std::span< const std::byte > bytes) noexcept
	Validates bytes and returns a borrowing view.
bool	program_wire_matches (const ProgramWireView &view, const PlaybackProgram &program, std::span< const timebase::TempoPoint > tempo_points, std::uint64_t producer_epoch) noexcept
	Whether view carries exactly program compiled from tempo_points.
RealtimeStretchStateBankAdmission	admit_realtime_stretch_state_bank (std::span< const RealtimeStretchStateSpec > specs, double sample_rate, std::uint32_t maximum_block_frames, const AudioRendererLimits &limits) noexcept
	Pure, allocation-free admission for one immutable bank shape.
RealtimeStretchStateBankAdmission	admit_realtime_stretch_program (const PlaybackProgram &program, double sample_rate, std::uint32_t maximum_block_frames, const AudioRendererLimits &limits)
	Control-thread aggregate admission for the exact immutable publication.
runtime::Result< SealedRecordingTake, RecordingCommitError >	seal_recording_take (const audio::BufferView< const float > &audio, RecordingTakeCommitRequest request)
runtime::Result< SealedRecordingTake, RecordingCommitError >	seal_retrospective_take (const audio::RollingAudioCaptureBuffer &capture, const audio::RollingAudioCaptureHold &hold, RecordingTakeCommitRequest request)
bool	valid_tempo_sync_request (const TempoSyncBlockRequest &request) noexcept
bool	valid_tempo_sync_state (const TempoSyncBlockState &state) noexcept
bool	tempo_sync_add_output_latency (std::int64_t clock_time_micros, std::uint32_t output_latency_frames, double sample_rate, std::int64_t &output_host_time_micros) noexcept
bool	tempo_sync_block_end_host_time_micros (const TempoSyncBlockRequest &request, std::int64_t &block_end) noexcept
TempoSyncPlayingProjection	project_tempo_sync_playing (const TempoSyncBlockRequest &request, const TempoSyncBlockState &state, bool previous_playing) noexcept
constexpr float	clamped_track_gain (float value) noexcept
	Constrains a streamed control value to the range the document accepts for the same control as a constant.
constexpr float	clamped_track_pan (float value) noexcept
constexpr TrackMixerChannelGains	track_mixer_channel_gains (float pan) noexcept
constexpr float	track_mixer_channel_gain (float pan, std::size_t channel, std::size_t channel_count) noexcept
	The balance multiplier for one output channel.
bool	valid_transport_ranges (const TransportSnapshot &transport) noexcept
	Validates the shared structural contract consumed by every block renderer.
long double	host_mapped_document_sample_at_output_offset (const TransportRange &range, const timebase::CompiledTempoMap &tempo_map, std::uint32_t output_offset) noexcept
	Maps an output-frame boundary in a host-beat-mapped range back into the program's document-sample domain.
bool	host_mapped_output_offset_for_tick (const TransportRange &range, timebase::TickPosition document_tick, std::uint32_t &output_offset) noexcept
	Maps an exact program event tick into a half-open host-beat-mapped transport range.

Variables
constexpr const char *	kChordPatternContentType = "pulp.playback.chord_pattern"
constexpr std::uint32_t	kChordPatternContentSchemaVersion = 1
constexpr std::size_t	kMaximumChordPatternNotes = 4096
constexpr std::uint32_t	kOfflineStretchAlgorithmVersion = 1
constexpr std::size_t	kMaximumControllerEventsPerTrack = std::size_t{1} << 20
	Ceiling on controller events one track program may carry.
constexpr std::uint16_t	kProgramWireVersion = 3
	The format this build writes and is able to read.
constexpr std::uint16_t	kProgramWireMinReaderVersion = 2
	The floor written into a payload that carries no controller events: the version whose readers can still render it exactly.
constexpr std::uint16_t	kProgramWireControllerMinReaderVersion = 3
	The floor written into a payload that carries at least one controller event.
constexpr std::uint32_t	kProgramWireMagic = 0x5750'4C50u
	Spells PLPW in the first four bytes of every payload.
constexpr std::uint32_t	kProgramWireNoLane = 0xFFFF'FFFFu
	A track's mixer control that no automation lane supersedes.
constexpr std::size_t	kProgramWireMaximumTracks = 1'024
	Decoder work and fixed scratch remain bounded even for untrusted payloads.
constexpr std::size_t	kProgramWireMaximumAutomationLanes = 1'024
	Total automation lanes one publication consumer can prepare across all tracks.
constexpr std::size_t	kProgramWireMaximumControllerEventsPerTrack
	Controller events one track may carry on the wire.
constexpr std::uint32_t	kProgramWireSectionOptional = 1u << 0u
	The section is safe to ignore: a reader that does not know this id still renders the program the writer meant.
constexpr std::uint8_t	kProgramWireTrackHasAutomationProgram = 1u << 0u
constexpr std::size_t	kProgramWireAlignment = 8
	Every record is a multiple of eight bytes, so tiling sections back to back keeps each one eight-byte aligned without a padding section between them.
constexpr float	kMaximumTrackMixerGain = 64.0f
	Mirrors timeline::kMaximumTrackGainLinear.

Typedef Documentation

BufferedContentEpoch

using pulp::playback::BufferedContentEpoch = std::uint64_t

Identifies one continuous production interval.

Zero is never a valid epoch; every seek or loop wrap must begin a strictly newer one, so a frame produced under an older epoch can always be recognized as stale.

BufferedContentProducer

using pulp::playback::BufferedContentProducer

Initial value:

 
    std::function<std::uint64_t(BufferedContentEpoch epoch, std::uint64_t start_frame,
                                audio::BufferView<float> destination,
                                std::uint64_t frames, audio::FrameReaderStopToken stop_token)>

Caller-supplied producer of buffered content.

Fills destination with up to frames frames of planar float audio starting at content frame start_frame and returns how many frames it actually produced. Runs only on the background/pump thread, never on the audio thread.

epoch is the production epoch this call belongs to; a producer that caches work across calls must key that work by epoch, because a call made for a superseded epoch is discarded instead of reaching the ring. stop_token asks the call to return early — on cancellation, teardown, or reposition — and honoring it keeps those paths bounded by one chunk.

GeneratedEventCommitGeneration

using pulp::playback::GeneratedEventCommitGeneration = std::uint64_t

GeneratedEventRevision

using pulp::playback::GeneratedEventRevision = std::uint64_t

LoopRegion

using pulp::playback::LoopRegion = timebase::LoopRegion

The loop is a pair of document positions, so the timebase owns it and every rung that describes a loop names the same type.

The transport adds meaning — what wrapping does, and when it is suspended — never a second struct.

MeterSignature

using pulp::playback::MeterSignature = timebase::MeterSignature

ProgramGeneration

using pulp::playback::ProgramGeneration = std::uint64_t

RegisteredContentCompileFn

using pulp::playback::RegisteredContentCompileFn

Initial value:

 
    runtime::Result<ContentProgramFragment, ContentFragmentError> (*)(
        const RegisteredContentCompileInput& input, const void* context) noexcept

Enumeration Type Documentation

AudioRendererErrorCode

enum class pulp::playback::AudioRendererErrorCode : std::uint8_t

strong

Enumerator
InvalidIdentity
DuplicateAsset
MissingDecodedAsset
InvalidAsset
AssetMetadataMismatch
UnsupportedSampleRate
InvalidClipRange
InvalidFade
CapacityExceeded
InvalidTakeComp
OfflineStretchRequired
OfflineStretchFailed

AudioRenderStatus

enum class pulp::playback::AudioRenderStatus : std::uint8_t

strong

Enumerator
Rendered
Silent
InvalidProgram
InvalidTransport
InvalidOutput
CapacityExceeded
RealtimeStretchStateRequired
RealtimeStretchGap
RealtimeStretchStalePublication
RealtimeStretchImpossibleRatio
RealtimeStretchBackpressure
RealtimeStretchUnderflow
RealtimeStretchUnsupportedScrubbing

AutomationCursorCode

enum class pulp::playback::AutomationCursorCode : std::uint8_t

strong

Enumerator
Ok
Coalesced
AdoptionRejected
InvalidTransport
TempoMapMismatch
InsufficientCapacity
WorkCapacityExceeded

AutomationCurveMaterializationError

enum class pulp::playback::AutomationCurveMaterializationError : std::uint8_t

strong

Enumerator
NoPoints
IdentityExhausted
InvalidCurve

AutomationEvaluationRate

enum class pulp::playback::AutomationEvaluationRate : std::uint8_t

strong

How often the adopting realm must evaluate one automation lane.

Which parameters warrant per-sample evaluation is an open product decision; the wire commits only to carrying the answer per lane. Every lane this build encodes is SampleAccurate, which is what AutomationCursor already does.

Enumerator
SampleAccurate
BlockRate

AutomationProgramAdoption

enum class pulp::playback::AutomationProgramAdoption : std::uint8_t

strong

Enumerator
Adopted
Unchanged
Rejected

AutomationProgramErrorCode

enum class pulp::playback::AutomationProgramErrorCode : std::uint8_t

strong

Enumerator
InvalidGeneration
MissingTempoMap
UnsupportedTarget
InstanceTokenExhausted

AutomationRecordError

enum class pulp::playback::AutomationRecordError : std::uint8_t

strong

Enumerator
None
NotPrepared
NotRecording
InvalidValue
NonMonotonicPosition
CapacityExceeded

AutomationRecordMode

enum class pulp::playback::AutomationRecordMode : std::uint8_t

strong

Enumerator
Touch
Latch
Write

AutomationTransition

enum class pulp::playback::AutomationTransition : std::uint8_t

strong

Enumerator
Seed
Immediate
LinearRamp

CaptureCommandType

enum class pulp::playback::CaptureCommandType : std::uint8_t

strong

Enumerator
Start
Stop
Cancel
ReleaseTake

CaptureEventType

enum class pulp::playback::CaptureEventType : std::uint8_t

strong

Enumerator
Started
TakeCompleted
Stopped
Cancelled
CommandRejected
NoFreeTakeSlot
TakeCapacityExceeded
MidiCapacityExceeded
TakeCancelled

CaptureProcessResult

enum class pulp::playback::CaptureProcessResult : std::uint8_t

strong

Enumerator
Ok
NotPrepared
InvalidBuffers
InvalidTransport

CompileErrorCode

enum class pulp::playback::CompileErrorCode : std::uint8_t

strong

Enumerator
InvalidRequest
StaleRevision
ExecutorUnavailable
InvalidStructure
GenerationExhausted
CompilerAlreadyBound
AudioProgramInvalid
AutomationProgramInvalid
ExpansionBudgetExceeded
NoteProgramCapacityExceeded
OfflineStretchFailed
TrimmedMidiLaneUnsupported
MidiExpressionLaneUnsupported
MidiExpressionLaneBudgetExceeded	The arrangement authors more controller values than one program may carry. Bounded like every other expansion so a pathological document cannot make compilation unbounded.
TrimmedGrooveUnsupported
UnresolvedRegisteredContent
RegisteredContentCompileFailed
RegisteredContentFragmentQuotaExceeded
NestedMixerPanUnsupported
NestedGainSinkUnsupported
NestedPlacementFadeUnsupported
NestedFrozenTrackUnsupported
NestedActiveTakeUnsupported
NestedDeviceChainUnsupported
NestedAutomationPanUnsupported
NestedAutomationGainEventLeafUnsupported
NestedAutomationGainMediaUnsupported
NestedConformedTrimUnsupported
NestedAbsoluteChildUnsupported

CompileTaskStatus

enum class pulp::playback::CompileTaskStatus

strong

Enumerator
Pending
Complete

ContentFragmentErrorCode

enum class pulp::playback::ContentFragmentErrorCode : std::uint8_t

strong

Enumerator
RendererFailed
InvalidNote

ContentProgramOutputKind

enum class pulp::playback::ContentProgramOutputKind : std::uint8_t

strong

The immutable program-fragment family emitted by a registered compiler.

Built-in MIDI and audio stay on their direct compiler paths.

Enumerator
Notes

ContextRegistrationErrorCode

enum class pulp::playback::ContextRegistrationErrorCode : std::uint8_t

strong

Enumerator
EmptyContentTypeName
DuplicateContentType
CapacityExceeded
InvalidSchemaVersion
SchemaUnavailable
SchemaCodecUnavailable
InvalidFragmentQuota
InvalidProductionDeclaration
MissingCompileHook
InvalidOutputKind
InvalidStatePolicy

ControllerProgramEventOrigin

enum class pulp::playback::ControllerProgramEventOrigin : std::uint8_t

strong

Whether a lowered controller value was authored at its own position or synthesized at a window boundary to answer "what is sounding here".

A chased value is not a weaker value: it is the authored stream's real reading at that instant. The distinction is kept because a consumer that re-edits the arrangement must be able to tell a point the user placed from one the compiler derived, and because dropping it would make flattening lossy in a way no later pass could detect.

Enumerator
Authored
Chased

EventCompensationCode

enum class pulp::playback::EventCompensationCode : std::uint8_t

strong

Enumerator
Ok
NegativeDeviceLatency	A device reported a negative latency. There is no reading of that a scheduler can honour, so it fails closed rather than clamping to zero.
DeviceLatencyOutOfRange	A device's own reported latency exceeds the ceiling the caller supplied.
ChainShiftOutOfRange	The accumulated chain shift exceeds the ceiling the caller supplied.

ExternalSyncOutputCode

enum class pulp::playback::ExternalSyncOutputCode : std::uint8_t

strong

Enumerator
Complete
InvalidTransport
InvalidSampleRate
InvalidFrameRate
InvalidOutputLimit
OutputOverflow

GeneratedEventCommitCode

enum class pulp::playback::GeneratedEventCommitCode : std::uint8_t

strong

Enumerator
Committed
NotPrepared
EpochNotStarted
WrongEpoch
InvalidBoundary
InvalidGeneration
StaleGeneration
CommitRingFull

GeneratedEventDegradation

enum class pulp::playback::GeneratedEventDegradation : std::uint8_t

strong

Enumerator
None
RepeatLastCommitted
UseSkeleton
Silence

GeneratedEventPullCode

enum class pulp::playback::GeneratedEventPullCode : std::uint8_t

strong

Enumerator
Ready
Starved
OutputOverflow
InvalidRequest

GeneratedEventStageCode

enum class pulp::playback::GeneratedEventStageCode : std::uint8_t

strong

Enumerator
Staged
Revised
NotPrepared
EpochNotStarted
WrongEpoch
InvalidSpan
NotQuantized
InvalidRevision
StaleRevision
FrozenSpan
OutOfOrder
OverlappingSpan
InvalidEvent
EventCapacityExceeded
StagingCapacityExceeded

LaunchEventKind

enum class pulp::playback::LaunchEventKind : std::uint8_t

strong

Enumerator
None
Start
Stop

LaunchState

enum class pulp::playback::LaunchState : std::uint8_t

strong

Enumerator
Stopped
Armed
Playing
Stopping

MidiCaptureMaterializationError

enum class pulp::playback::MidiCaptureMaterializationError : std::uint8_t

strong

Enumerator
InvalidConfig
IdentityExhausted
InvalidNotes
SampleRateMismatch

MtcChaseCode

enum class pulp::playback::MtcChaseCode : std::uint8_t

strong

Enumerator
Ignored
Incomplete
Locked
Discontinuity
Invalid

MtcDirection

enum class pulp::playback::MtcDirection : std::int8_t

strong

Enumerator
Reverse
Unknown
Forward

MtcFrameRate

enum class pulp::playback::MtcFrameRate : std::uint8_t

strong

Enumerator
Fps24
Fps25
Fps2997Drop
Fps30

NoteProgramEventKind

enum class pulp::playback::NoteProgramEventKind : std::uint8_t

strong

Enumerator
Off
On

NoteRenderCode

enum class pulp::playback::NoteRenderCode : std::uint8_t

strong

Enumerator
Ok
NotPrepared
MissingProgram
AdoptionRejected
InvalidTransport
TempoMapMismatch
ActiveStateOverflow
OutputOverflow
CompensationUnsupported	A compensating shift met a range that locates events by host beat. The shift is a document-sample quantity and that range has no document-sample origin to add it to, so the block fails closed rather than scheduling against a position nothing defined.

OfflineStretchCompileStatus

enum class pulp::playback::OfflineStretchCompileStatus : std::uint8_t

strong

Enumerator
Progress
Complete
Failed

OfflineStretchErrorCode

enum class pulp::playback::OfflineStretchErrorCode : std::uint8_t

strong

Enumerator
None
InvalidClip
MissingSource
AssetMetadataMismatch
UnsupportedSampleRate
InvalidAlgorithmConfig
InvalidTempoSchedule
CapacityExceeded
SampleRateConverterPrepareFailed
ProcessorPrepareFailed
InvalidRatio
OutputTooShort
OutputTooLong
ProcessorProtocolError

ProgramErrorCode

enum class pulp::playback::ProgramErrorCode : std::uint8_t

strong

Enumerator
InvalidGeneration
InvalidIdentity
DuplicateTrack
DuplicateClip
MissingTempoMap

ProgramWireAdoption

enum class pulp::playback::ProgramWireAdoption : std::uint8_t

strong

Enumerator
Adopted
Unchanged
Rejected

ProgramWireConsumerCode

enum class pulp::playback::ProgramWireConsumerCode : std::uint8_t

strong

Enumerator
Ok
DecodeRejected
TempoMapMismatch
StateCapacityExceeded
StalePublication
MissingProgram
InvalidTransport
OutputCapacityExceeded
CursorRejected

ProgramWireErrorCode

enum class pulp::playback::ProgramWireErrorCode : std::uint8_t

strong

Enumerator
InsufficientCapacity	The destination span is smaller than the encoding needs. detail carries the required byte count.
MisalignedBuffer	The buffer's base address is not eight-byte aligned, so typed spans borrowed from it would be misaligned.
TempoMapMismatch	The supplied tempo points did not compile the program's tempo map.
AudioProgramUnsupported	A track carries an audio renderer program, which this version does not represent. Refused rather than dropped. detail carries the track id.
ProductionDeclarationUnsupported	A track has a non-default production declaration, which this wire version cannot carry. Refused rather than silently strengthening the adopting realm's replay claim. detail carries the track id.
MixerAutomationUnresolved	A mixer control points at an automation program that is not one of the owning track's lanes. detail carries the track id.
CountOverflow	A count exceeded the 32-bit index domain the flat layout addresses.
ShortBuffer	Fewer bytes than the fixed header, the section directory, or the payload the header declares.
BadMagic
UnsupportedVersion	The payload's min_reader_version exceeds this build's version.
BadHeaderSize	header_bytes disagrees with this format's fixed header size.
ChecksumMismatch
SectionOutOfBounds	A section's offset plus length overflows or leaves the payload.
SectionsNotTiled	Sections do not tile the payload exactly: unsorted, gapped, overlapping, or not reaching payload_bytes.
SectionMisaligned	A section's payload offset is not eight-byte aligned.
NonCanonicalSectionOrder	Known sections must appear in ascending canonical id order. Optional unknown sections may be interleaved only in ascending id order.
DuplicateSection
UnknownSection	An unknown section id that the writer did not mark optional.
MissingSection	A known section id is absent.
TrailingData	The buffer holds bytes past the payload the header declares.
BadRecordSize	A section's byte length is not a whole number of its records.
BadSectionCardinality	A section holds a record count the format does not admit.
RangeOutOfBounds	A track's (first, count) range leaves the section it indexes.
NonCanonicalRangeOwnership	Track and lane ranges must exclusively partition their sections in canonical track/lane order; aliases and unowned records are rejected.
AutomationTargetUnresolved	A device lane names no placement in its owning track.
DuplicateAutomationTarget	Two lanes in one track drive the same device parameter or mixer control.
StaleLaneGeneration	A publication from the active producer regresses one lane generation.
InvalidEnum	A record holds a value outside its enumeration.
MalformedNoteModifier	A note modifier is not a combination the document model admits — a zero condition period, an offset past it, a ratchet count out of range. The renderer divides by the period, so this is a rejection and not a clamp.
MalformedSegment	An automation segment runs backwards or carries a non-finite value, either of which would propagate through every sample downstream.
MalformedControllerEvent	A controller event names no clip, lane, or point, or carries an address component wider than the MIDI wire gives it. Judged by the document model's own midi_lane_address_well_formed rather than a second rule here, so the two cannot drift apart. A consumer emits the address onto a real MIDI stream, where a 200 in a four-bit group field is not a controller the producer meant but bits landing in a neighbouring field. detail carries the record's index within the section.
InvalidSampleRate
InvalidLimits	The carried automation ceilings are not a configuration the renderer accepts.
InvalidProducerEpoch	The producer epoch is zero. A zero epoch would compare equal to every other zero, making two unrelated producers look like one, so it is refused at both ends rather than silently acting as a wildcard.
InvalidInstanceToken	An automation lane's instance token is zero. Same reasoning one level down: two lanes carrying zero would compare equal, so a consumer would report Unchanged for a program it has never seen. detail carries the lane's index within the section.

ProgramWireSection

enum class pulp::playback::ProgramWireSection : std::uint32_t

strong

Enumerator
Program
TempoPoints
Tracks
ClipIds
NoteEvents
NoteModifiers
DevicePlacementIds
AutomationLanes
AutomationSegments
ControllerRanges	One (first, count) range per track into ControllerEvents, in track order. A separate section rather than two more fields on the track record, so the track record's layout — and every version 2 reader's stride over it — stays exactly what it was.
ControllerEvents

ProgramWireTargetKind

enum class pulp::playback::ProgramWireTargetKind : std::uint8_t

strong

Enumerator
DeviceParameter
TrackMixer

ProviderKind

enum class pulp::playback::ProviderKind : std::uint8_t

strong

Enumerator
Arrangement
Launcher
ExternalInput

RealtimeStretchRenderCode

enum class pulp::playback::RealtimeStretchRenderCode : std::uint8_t

strong

Enumerator
NotRequired
Rendered
GapIdentityChanged
StateRequired
StalePublication
UnsupportedScrubbing
ImpossibleRatio
Backpressure
Underflow

RealtimeStretchStateBankError

enum class pulp::playback::RealtimeStretchStateBankError : std::uint8_t

strong

Enumerator
None
InvalidConfiguration
InvalidIdentity
DuplicateIdentity
StateLimitExceeded
ChannelLimitExceeded
TimeRatioLimitExceeded
StateBytesExceeded
ProcessorPrepareRejected
AllocationFailed

RecordingCommitError

enum class pulp::playback::RecordingCommitError : std::uint8_t

strong

Enumerator
InvalidRequest
UnsupportedWaveShape
WaveSizeExceeded
HashFailure
InvalidTake
InvalidTakeLane
RetrospectiveUnavailable

RecordingCoordinatorError

enum class pulp::playback::RecordingCoordinatorError : std::uint8_t

strong

Enumerator
NotPrepared
StaleLatency
InvalidTake
CaptureCopyFailed
SealFailed
MediaStageFailed
DocumentCommitFailed

RecordingMonitorMode

enum class pulp::playback::RecordingMonitorMode : std::uint8_t

strong

Enumerator
Off
Direct
Software
Auto

RecordingMonitorPath

enum class pulp::playback::RecordingMonitorPath : std::uint8_t

strong

Enumerator
Off
Direct
Software

RegisteredRendererStatePolicy

enum class pulp::playback::RegisteredRendererStatePolicy : std::uint8_t

strong

Registered note fragments currently admit Reset only.

CarryByItemId is a reserved value for a future fragment contract with renderer-stable note keys; ordinal-generated IDs cannot safely carry state across insertions.

Enumerator
Reset
CarryByItemId

RendererStatePolicy

enum class pulp::playback::RendererStatePolicy : std::uint8_t

strong

Enumerator
Stateless
CarryByItemId

ShellAdoptionResult

enum class pulp::playback::ShellAdoptionResult : std::uint8_t

strong

Enumerator
Adopted
Unchanged
Missing
Rejected

TempoSyncError

enum class pulp::playback::TempoSyncError : std::uint8_t

strong

Enumerator
None
Disabled
InvalidRequest
InvalidState
BackendFailure

TempoSyncPlayingBoundary

enum class pulp::playback::TempoSyncPlayingBoundary : std::uint8_t

strong

Enumerator
BeforeOrAtBlockStart
InsideBlock
AtOrAfterBlockEnd

TrackAutomationProgramErrorCode

enum class pulp::playback::TrackAutomationProgramErrorCode : std::uint8_t

strong

Enumerator
InvalidTrackId
MissingTempoMap
MissingProgram
InvalidLaneId
TempoMapMismatch
DuplicateLane
DuplicateTarget

TrackAutomationRendererAdoption

enum class pulp::playback::TrackAutomationRendererAdoption : std::uint8_t

strong

Enumerator
Adopted
Unchanged

TrackAutomationRendererCode

enum class pulp::playback::TrackAutomationRendererCode : std::uint8_t

strong

Enumerator
Ok
Coalesced
MissingProgram
TrackMismatch
InvalidTransport
TempoMapMismatch
LaneAdoptionRejected
LaneCapacityExceeded
PointCapacityExceeded
DeviceCapacityExceeded
WorkCapacityExceeded
InvalidLimits

TransportError

enum class pulp::playback::TransportError

strong

Enumerator
None
NotPrepared
InvalidMeter
InvalidLoop
LoopTooShortForMaximumBlock
InvalidFrameCount
InvalidScrubWindow
ScrubWindowTooShortForMaximumBlock
NotScrubbing
InvalidTempo
InvalidTempoSyncConfig
TempoSyncHostTimeRequired
TempoSyncUnavailable
InvalidTempoSyncState
PlaybackEpochExhausted

Function Documentation

accumulate_event_chain_shift()

EventCompensationResult pulp::playback::accumulate_event_chain_shift ( std::span< const int > device_latency_samples, int ceiling_samples )

constexprnoexcept

Accumulates the event-domain latency of one chain into a scheduling shift.

Only latency that delays the EVENTS themselves belongs here. A device that converts events to audio contributes nothing: its audio output is already aligned by the graph's own plug-in delay compensation, which delays every sibling branch to match, so adding it again would compensate twice and pull the stream early by exactly the amount the graph had already handled.

ceiling_samples is supplied by the caller rather than defined here so this rung introduces no second latency constant beside the graph's own.

admit_realtime_stretch_program()

RealtimeStretchStateBankAdmission pulp::playback::admit_realtime_stretch_program	(	const PlaybackProgram &	program,
		double	sample_rate,
		std::uint32_t	maximum_block_frames,
		const AudioRendererLimits &	limits )

Control-thread aggregate admission for the exact immutable publication.

Per-track banks partition this already-admitted set so parallel graph nodes retain single-owner DSP state without multiplying the global ceilings.

admit_realtime_stretch_state_bank()

RealtimeStretchStateBankAdmission pulp::playback::admit_realtime_stretch_state_bank ( std::span< const RealtimeStretchStateSpec > specs, double sample_rate, std::uint32_t maximum_block_frames, const AudioRendererLimits & limits )

noexcept

Pure, allocation-free admission for one immutable bank shape.

The byte calculation checked-sums each processor geometry's conservative retained charge. The separate per-allocation ceiling remains an addressability bound.

clamped_track_gain()

float pulp::playback::clamped_track_gain ( float value )

constexprnoexcept

Constrains a streamed control value to the range the document accepts for the same control as a constant.

A curve is authored point by point and is not range checked at insert time, so without this a lane could ask for a gain the model refuses to store, and a single NaN point would poison every sample downstream of the track. A value the mixer cannot interpret rests at neutral rather than at an extreme, so a broken curve leaves the track audible and centred instead of silently muting or hard-panning it.

clamped_track_pan()

float pulp::playback::clamped_track_pan ( float value )

constexprnoexcept

compile_audio_clip_program()

runtime::Result< AudioClipRendererProgram, AudioRendererError > pulp::playback::compile_audio_clip_program	(	const timeline::Clip &	clip,
		const timeline::Project &	project,
		const timebase::CompiledTempoMap &	tempo_map,
		const DecodedAudioAssetPool &	assets,
		const AudioRendererLimits &	limits )

compile_take_comp_segment_program()

runtime::Result< AudioClipRendererProgram, AudioRendererError > pulp::playback::compile_take_comp_segment_program	(	const timeline::TakeLane &	lane,
		std::size_t	segment_index,
		const timeline::Project &	project,
		const timebase::CompiledTempoMap &	tempo_map,
		const DecodedAudioAssetPool &	assets,
		const AudioRendererLimits &	limits )

Lowers one canonical take-comp selection to the same immutable audio-region artifact used by arrangement clips.

The ordinal is stable within the owning lane snapshot and distinguishes repeated selections from one take.

compile_track_freeze_program()

runtime::Result< AudioClipRendererProgram, AudioRendererError > pulp::playback::compile_track_freeze_program	(	const timeline::Track &	track,
		const timeline::Project &	project,
		const timebase::CompiledTempoMap &	tempo_map,
		const DecodedAudioAssetPool &	assets,
		const AudioRendererLimits &	limits )

Lowers a track's selected freeze artifact to one immutable audio region.

controller_program_event_less()

bool pulp::playback::controller_program_event_less ( const ControllerProgramEvent & lhs, const ControllerProgramEvent & rhs )

constexprnoexcept

Total order for controller events sharing a block.

Sample position decides first, then tick, because distinct ticks can quantize to one compiled sample and tick order stays authoritative within it. Beyond that the order is by address, so two streams that resolve at the same instant are emitted in a stable, wire-meaningful sequence rather than in whatever order the lanes happened to be stored. A chased value sorts before an authored one at an identical position: the boundary reading establishes what is sounding on entry, and an authored point at that exact instant is the user overriding it.

create_chord_pattern_content()

runtime::Result< timeline::RegisteredContent, timeline::PersistenceError > pulp::playback::create_chord_pattern_content	(	const ChordPatternContent &	content,
		const timeline::SchemaRegistry &	schemas,
		std::size_t	maximum_json_bytes = 1024 )

Creates schema-backed chord-pattern content after strict payload validation.

declare_chord_pattern_renderer()

std::optional< ContextRegistrationError > pulp::playback::declare_chord_pattern_renderer	(	CompileContextRegistry &	registry,
		const timeline::SchemaRegistry &	schemas )

Declares the trusted deterministic note compiler and its ChordScale read.

decode_program_wire()

runtime::Result< ProgramWireView, ProgramWireError > pulp::playback::decode_program_wire ( std::span< const std::byte > bytes )

noexcept

Validates bytes and returns a borrowing view.

This is untrusted-input surface the moment a payload crosses a realm, so nothing is assumed: the header, the checksum, the section tiling, every record count, every (first, count) range, and every enumerated field are checked before any accessor can be called.

encode_program_wire()

runtime::Result< std::size_t, ProgramWireError > pulp::playback::encode_program_wire ( const PlaybackProgram & program, std::span< const timebase::TempoPoint > tempo_points, std::uint64_t producer_epoch, std::span< std::byte > out )

noexcept

Writes program into out and returns the bytes written.

A destination larger than the encoding keeps its trailing bytes untouched, and those bytes are not part of the payload — hand the decoder out.first(written), since a buffer longer than its declared payload is rejected as trailing data. tempo_points must be the points that compiled the program's tempo map; the compiled segments are private and derived, so the wire carries the inputs and this check is what proves they are the right ones. Allocates nothing: the caller owns the destination, which is what lets a producer write straight into a shared ring. producer_epoch identifies whoever minted this program's generation and must be nonzero and stable for that producer's lifetime; it is a required argument rather than a defaulted one so a caller cannot omit producer identity without noticing.

evaluate_automation_segment()

float pulp::playback::evaluate_automation_segment ( const AutomationProgram & program, std::size_t segment_index, timebase::SamplePosition sample, timebase::TickPosition tick )

noexcept

The authored value of one already-selected segment at an exact tick.

The sample is needed only to recognise a zero-length terminal segment. Every consumer that needs a curve value at a position goes through here, so device delivery and track-mixer application can never drift apart.

event_compensation_admits_live_input()

bool pulp::playback::event_compensation_admits_live_input ( EventCompensationShift shift, ProviderSelectorProgram provider )

constexprnoexcept

Whether a track may offer live input while its event chain is compensated.

Compensation works by reading the future: the program is lowered over the whole timeline before playback begins, so a scheduled event can be issued early and arrive on time. Live input has no future. A note played into a chain with event-domain latency L is heard L late however the software is arranged, so a compensated chain and a live provider cannot both be honoured and the pair is refused rather than silently diverging by L. A per-track monitor bypass is the eventual answer; refusing documents the absence instead of shipping a divergence nothing reports.

find_note_modifier()

const CompiledNoteModifier * pulp::playback::find_note_modifier ( std::span< const CompiledNoteModifier > modifiers, timeline::ItemId note_id )

noexcept

Looks up the modifier for note_id in a table sorted by note id.

Returns nullptr when the note plays unconditionally, which is the common case.

host_mapped_document_sample_at_output_offset()

long double pulp::playback::host_mapped_document_sample_at_output_offset ( const TransportRange & range, const timebase::CompiledTempoMap & tempo_map, std::uint32_t output_offset )

noexcept

Maps an output-frame boundary in a host-beat-mapped range back into the program's document-sample domain.

The returned value is fractional so audio renderers can interpolate without discarding host-tempo scaling.

host_mapped_output_offset_for_tick()

bool pulp::playback::host_mapped_output_offset_for_tick ( const TransportRange & range, timebase::TickPosition document_tick, std::uint32_t & output_offset )

noexcept

Maps an exact program event tick into a half-open host-beat-mapped transport range.

Callers must retain the source tick rather than round-tripping an integer document sample through the tempo map at range boundaries.

is_monotonic_renderer_adoption()

bool pulp::playback::is_monotonic_renderer_adoption ( RendererProgramKey active, RendererProgramKey candidate )

constexprnoexcept

link_audio_track_program()

runtime::Result< std::shared_ptr< const AudioTrackRendererProgram >, AudioRendererError > pulp::playback::link_audio_track_program	(	timeline::ItemId	track_id,
		std::vector< AudioClipRendererProgram >	clips,
		const AudioRendererLimits &	limits )

loop_admits_event_compensation()

bool pulp::playback::loop_admits_event_compensation ( const TransportRange & range, EventCompensationShift shift, timebase::SamplePosition loop_end_samples )

constexprnoexcept

Whether a compensating shift's read-ahead stays inside an enabled loop.

A window that stays inside reads one contiguous run from the shifted origin and needs no fold. A window that does not is not refused: plan_compensated_read folds it back around the loop point so the read-ahead returns the post-wrap content, which is what the musician hears when those frames reach the device. The fold costs a second run and a wrap-time release, so the predicate stays worth asking. loop_end_samples is the loop end in the program's own document samples; a disabled loop is unbounded and the caller passes nothing.

materialize_midi_capture()

runtime::Result< MaterializedMidiCapture, MidiCaptureMaterializationError > pulp::playback::materialize_midi_capture	(	std::span< const CapturedMidiEvent >	events,
		MidiCaptureMaterializationConfig	config )

mtc_timecode_to_samples()

timebase::SamplePosition pulp::playback::mtc_timecode_to_samples ( const MtcTimecode & timecode, timebase::RationalRate sample_rate )

noexcept

Convert between an MTC wall-clock label and a non-negative timeline sample.

The 29.97 mode uses SMPTE drop-frame numbering; no video frames are removed.

next_launch_boundary()

timebase::MonotonicBeat pulp::playback::next_launch_boundary ( timebase::MonotonicBeat from, LaunchQuantize quantize )

constexprnoexcept

next_program_generation()

runtime::Result< ProgramGeneration, ProgramError > pulp::playback::next_program_generation ( ProgramGeneration current )

noexcept

note_program_event_less()

bool pulp::playback::note_program_event_less ( const NoteProgramEvent & lhs, const NoteProgramEvent & rhs )

constexprnoexcept

plan_compensated_read() [1/2]

CompensatedReadPlan pulp::playback::plan_compensated_read ( const TransportRange & range, EventCompensationShift shift )

constexprnoexcept

The one run a window that no loop bounds resolves to.

The unlooped, the uncompensated, and the host-beat-mapped cases all take this shape, so a consumer walks segments once rather than carrying two code paths.

plan_compensated_read() [2/2]

CompensatedReadPlan pulp::playback::plan_compensated_read ( const TransportRange & range, EventCompensationShift shift, timebase::SamplePosition loop_start_samples, timebase::SamplePosition loop_end_samples )

constexprnoexcept

Wrap-aware read-ahead: the runs a compensated window reads when an enabled loop bounds it.

The shifted origin is first folded into [loop_start, loop_end), which is a no-op for an ordinary window and recovers the post-wrap position for one that has already been carried past the loop point by the shift. The number of loop lengths that fold consumed is the pass the run belongs to. Whatever remains of the window past the loop point becomes a second run reading from loop_start.

program_reproducibility()

timeline::ReproducibilityClass pulp::playback::program_reproducibility ( const PlaybackProgram & program )

noexcept

The weakest claim any track in the program is entitled to make.

An empty program renders silence, which is bit-reproducible.

program_wire_checksum()

std::uint64_t pulp::playback::program_wire_checksum ( std::span< const std::byte > bytes )

constexprnoexcept

FNV-1a over 64 bits.

Detects the truncation, splice, and single-field corruption a transport can produce; it is not a defence against a chosen forgery, which the realm boundary's own trust model has to answer.

program_wire_encoded_size()

runtime::Result< std::size_t, ProgramWireError > pulp::playback::program_wire_encoded_size ( const PlaybackProgram & program, std::span< const timebase::TempoPoint > tempo_points )

noexcept

Bytes encode_program_wire needs for this program.

Runs the same refusals the encoder does, so a caller that sizes a buffer learns about an unrepresentable program before it allocates one. The producer epoch does not affect the size and is therefore not required here.

program_wire_matches()

bool pulp::playback::program_wire_matches ( const ProgramWireView & view, const PlaybackProgram & program, std::span< const timebase::TempoPoint > tempo_points, std::uint64_t producer_epoch )

noexcept

Whether view carries exactly program compiled from tempo_points.

Structural equality by value — every field the wire carries compared against its source — because the two share no pointers and shared-pointer identity is precisely what the wire exists to leave behind. The tempo points are passed rather than recovered so the comparison allocates nothing. A program the encoder would refuse compares false.

program_wire_process_epoch()

std::uint64_t pulp::playback::program_wire_process_epoch ( )

noexcept

A nonzero value that is stable for this process and differs between processes.

Producers with no better source of identity can stamp payloads with this; one that owns a longer-lived notion of "producer" (a store, a session) should mint its own and keep it for that lifetime. It is never zero, so it can be handed straight to encode_program_wire.

project_tempo_sync_playing()

TempoSyncPlayingProjection pulp::playback::project_tempo_sync_playing ( const TempoSyncBlockRequest & request, const TempoSyncBlockState & state, bool previous_playing )

noexcept

provider_production_declaration()

timeline::ProductionDeclaration pulp::playback::provider_production_declaration ( ProviderSelectorProgram provider )

noexcept

What content served by provider declares about its production.

range_admits_event_compensation()

bool pulp::playback::range_admits_event_compensation ( const TransportRange & range, EventCompensationShift shift )

constexprnoexcept

Whether a compensating shift has a defined meaning for range.

A host-beat-mapped range locates events by their authored tick against the host's own beat window, not by a document sample, so a sample-domain shift has nowhere to land in it. Converting the shift to ticks is exactly what the unit rule forbids, so the combination fails closed instead of scheduling against a quantity nothing defined.

register_chord_pattern_content_schema()

runtime::Result< timeline::SchemaRegistration, timeline::SchemaError > pulp::playback::register_chord_pattern_content_schema

(

timeline::SchemaRegistryBuilder &

builder

)

Registers the exact versioned Content schema and codec.

resolve_dirty_tracks()

DirtyTrackSet pulp::playback::resolve_dirty_tracks	(	const timeline::Project &	project,
		timeline::ItemId	root_sequence_id,
		const timeline::DirtySet &	dirty,
		const CompileInvalidationIndex &	index )

Canonical translation from transaction dirtiness to root-track compiler dirtiness.

This combines direct edits, transitive SequenceRef dependencies, and compile-context subscriptions in one fail-closed path.

resolve_launch_sample()

std::optional< std::uint32_t > pulp::playback::resolve_launch_sample ( const TransportSnapshot & snapshot, const timebase::CompiledTempoMap & tempo_map, timebase::MonotonicBeat target )

inlinenoexcept

samples_to_mtc_timecode()

MtcTimecode pulp::playback::samples_to_mtc_timecode ( timebase::SamplePosition position, timebase::RationalRate sample_rate, MtcFrameRate frame_rate )

noexcept

seal_recording_take()

runtime::Result< SealedRecordingTake, RecordingCommitError > pulp::playback::seal_recording_take	(	const audio::BufferView< const float > &	audio,
		RecordingTakeCommitRequest	request )

seal_retrospective_take()

runtime::Result< SealedRecordingTake, RecordingCommitError > pulp::playback::seal_retrospective_take	(	const audio::RollingAudioCaptureBuffer &	capture,
		const audio::RollingAudioCaptureHold &	hold,
		RecordingTakeCommitRequest	request )

select_automation_segment()

std::size_t pulp::playback::select_automation_segment ( const AutomationProgram & program, timebase::SamplePosition sample, bool cold, std::size_t segment_index )

noexcept

Selects the segment governing an absolute timeline sample.

A cold call searches; a warm one advances forward from segment_index, which is the amortized O(1) path monotonic playback takes. Never called on an empty program.

shifted_range_origin()

timebase::SamplePosition pulp::playback::shifted_range_origin ( const TransportRange & range, EventCompensationShift shift )

constexprnoexcept

The sample position an event stream at a compensated injection point must be read from for range.

Applied per TransportRange, never per block. The loop wrap is the hazard: a block that straddles a wrap carries two monotonic ranges, and reading the second one from the first one's origin would replay the pre-wrap window. Saturating, so a shift near the end of the sample domain clamps instead of wrapping into the past.

tempo_sync_add_output_latency()

bool pulp::playback::tempo_sync_add_output_latency ( std::int64_t clock_time_micros, std::uint32_t output_latency_frames, double sample_rate, std::int64_t & output_host_time_micros )

noexcept

tempo_sync_block_end_host_time_micros()

bool pulp::playback::tempo_sync_block_end_host_time_micros ( const TempoSyncBlockRequest & request, std::int64_t & block_end )

noexcept

track_mixer_channel_gain()

float pulp::playback::track_mixer_channel_gain ( float pan, std::size_t channel, std::size_t channel_count )

constexprnoexcept

The balance multiplier for one output channel.

A bus narrower than stereo has no opposite side to attenuate, so pan is inert there rather than silently halving a mono track. Wider buses alternate sides by channel parity.

track_mixer_channel_gains()

TrackMixerChannelGains pulp::playback::track_mixer_channel_gains ( float pan )

constexprnoexcept

track_production_declaration()

timeline::ProductionDeclaration pulp::playback::track_production_declaration ( const TrackProgram & track )

noexcept

What a single track's compiled content declares about its production.

valid_mtc_timecode()

bool pulp::playback::valid_mtc_timecode ( const MtcTimecode & timecode )

noexcept

valid_tempo_sync_request()

bool pulp::playback::valid_tempo_sync_request ( const TempoSyncBlockRequest & request )

noexcept

valid_tempo_sync_state()

bool pulp::playback::valid_tempo_sync_state ( const TempoSyncBlockState & state )

noexcept

valid_transport_ranges()

bool pulp::playback::valid_transport_ranges ( const TransportSnapshot & transport )

noexcept

Validates the shared structural contract consumed by every block renderer.

Variable Documentation

kChordPatternContentSchemaVersion

std::uint32_t pulp::playback::kChordPatternContentSchemaVersion = 1

inlineconstexpr

kChordPatternContentType

const char* pulp::playback::kChordPatternContentType = "pulp.playback.chord_pattern"

inlineconstexpr

kMaximumChordPatternNotes

std::size_t pulp::playback::kMaximumChordPatternNotes = 4096

inlineconstexpr

kMaximumControllerEventsPerTrack

std::size_t pulp::playback::kMaximumControllerEventsPerTrack = std::size_t{1} << 20

inlineconstexpr

Ceiling on controller events one track program may carry.

The compiler refuses a track that would exceed it with a named code, and the program wire enforces the same bound on a decoded track, so a foreign payload can claim no more than a compiled program could hold.

kMaximumTrackMixerGain

float pulp::playback::kMaximumTrackMixerGain = 64.0f

inlineconstexpr

Mirrors timeline::kMaximumTrackGainLinear.

Kept here so the render path can bound a streamed curve value without the playback module reaching into the document model for a constant; the static_assert below keeps the two honest.

kOfflineStretchAlgorithmVersion

std::uint32_t pulp::playback::kOfflineStretchAlgorithmVersion = 1

inlineconstexpr

kProgramWireAlignment

std::size_t pulp::playback::kProgramWireAlignment = 8

inlineconstexpr

Every record is a multiple of eight bytes, so tiling sections back to back keeps each one eight-byte aligned without a padding section between them.

The alignment a payload's base address must satisfy for a decoder to borrow typed spans out of it.

kProgramWireControllerMinReaderVersion

std::uint16_t pulp::playback::kProgramWireControllerMinReaderVersion = 3

inlineconstexpr

The floor written into a payload that carries at least one controller event.

A reader below it has no controller section to read, and missing that data is a musical loss rather than a cosmetic one, so it is refused.

kProgramWireMagic

std::uint32_t pulp::playback::kProgramWireMagic = 0x5750'4C50u

inlineconstexpr

Spells PLPW in the first four bytes of every payload.

kProgramWireMaximumAutomationLanes

std::size_t pulp::playback::kProgramWireMaximumAutomationLanes = 1'024

inlineconstexpr

Total automation lanes one publication consumer can prepare across all tracks.

This is deliberately separate from the carried per-track ceiling; callers size ProgramWireLaneState storage against this publication bound.

kProgramWireMaximumControllerEventsPerTrack

std::size_t pulp::playback::kProgramWireMaximumControllerEventsPerTrack

inlineconstexpr

Initial value:

=
    kMaximumControllerEventsPerTrack

Controller events one track may carry on the wire.

This is the compiler's own per-track ceiling (kMaximumControllerEventsPerTrack), so no program the compiler publishes can exceed it and the encoder needs no check of its own; the decoder enforces it because a foreign payload is untrusted input, and a track record claiming more is refused with InvalidLimits before its range is even bounds-checked, so a corrupted count is a typed rejection rather than a million-record walk.

kProgramWireMaximumTracks

std::size_t pulp::playback::kProgramWireMaximumTracks = 1'024

inlineconstexpr

Decoder work and fixed scratch remain bounded even for untrusted payloads.

kProgramWireMinReaderVersion

std::uint16_t pulp::playback::kProgramWireMinReaderVersion = 2

inlineconstexpr

The floor written into a payload that carries no controller events: the version whose readers can still render it exactly.

Bump only when a reader at an earlier version would misread the bytes rather than merely miss data.

kProgramWireNoLane

std::uint32_t pulp::playback::kProgramWireNoLane = 0xFFFF'FFFFu

inlineconstexpr

A track's mixer control that no automation lane supersedes.

kProgramWireSectionOptional

std::uint32_t pulp::playback::kProgramWireSectionOptional = 1u << 0u

inlineconstexpr

The section is safe to ignore: a reader that does not know this id still renders the program the writer meant.

Absent, an unknown id is a rejection.

kProgramWireTrackHasAutomationProgram

std::uint8_t pulp::playback::kProgramWireTrackHasAutomationProgram = 1u << 0u

inlineconstexpr

kProgramWireVersion

std::uint16_t pulp::playback::kProgramWireVersion = 3

inlineconstexpr

The format this build writes and is able to read.

Version 2 widened ProgramWireAutomationLaneRecord to carry the lane's instance token. A version 1 reader would not merely miss that field: it divides the section's byte length by its own 48-byte record, and a lane count whose 56-byte length happens to divide by 48 — six lanes, for one — decodes as seven records of shifted garbage rather than failing. So min_reader_version moves with it, which is what makes that reader refuse the payload instead of misreading it.

Version 3 appended two sections — the per-track controller ranges and the controller events themselves — and changed no existing record. Every version 2 layout is byte-identical, so a version 2 reader strides every section it knows exactly as before; what it does with the two it does not know is decided per payload, by min_reader_version, and the decision is the whole point of the design:

• A program carrying no controller events is written with min_reader_version 2 and the two new sections flagged optional. A version 2 reader skips them and renders precisely the program the writer meant, because there was nothing in them to miss.
• A program carrying any controller event is written with min_reader_version 3 and the two sections required. A version 2 reader refuses at the header with UnsupportedVersion — and would refuse again at the directory with UnknownSection if it somehow read past that — and never renders the notes with the expression silently gone. That silent loss is exactly what the encoder's former refusal of controller-bearing programs existed to prevent, so it is the one outcome an older reader is never allowed to reach.

Both numbers are functions of the program, so one program still has exactly one encoding. In the other direction a version 3 reader accepts a version 2 payload — the two sections absent, read as empty — so a producer and a consumer can be upgraded in either order.