v10/internal/decisions/live-presentation-anchor.md

status, date

status	date
decided	2026-06-24

Single presentation-level live timeline anchor

Decision

Hold one rolling presentation-level anchor — a (media-time ↔ PDT) correspondence — and apply it to every selected track, rather than pinning each track to its own buffer.

The anchor is learned from whichever selected audio/video track first has SourceBuffer ground truth: the buffer pin (resolveBufferedAnchor) reports a buffered segment's actual native-PTS start M₀, paired with that segment's PDT P₀. From that one pair, any track's segment is placed by its own PDT:

segment.startTime = M₀ + (segment.programDateTime − P₀)

Established once per source, on first buffer ground truth (pin-once — it surfaces drift rather than masking it; we don't re-correct, and the parser's PDT carry-forward maintains the timeline across reloads). On establishment the anchor is stamped onto every track in one pass: resolved tracks shift their segment timeline onto it; not-yet-resolved shells get it as startDate, so the media-playlist parser places their segments on the shared timeline at first resolve (placeOnAnchor). So a track selected later — an ABR rung, another audio language, late captions — resolves already anchored, with no per-track positioning pass. The established anchor is also published as a presentation-level presentationAnchor, which seekToLiveEdge gates its live-edge seek on (see below).

No pre-buffer estimate. Until ground truth exists a track rides its raw parser timeline — a valid timeline for fetching the first segments (the same segments are fetched either way), so the loader bootstraps the buffer, and thus the pin, without it. The one thing the estimate originally covered: seekToLiveEdge must not seek before the pin, or it targets the raw window and the pin's later shift strands the playhead off-window (confirmed by smoke test). We address that by gating that seek on the published anchor (presentationAnchor, below) rather than bootstrapping it off a manifest estimate — the estimate's ~27 s turnover drift made it an unreliable seek target anyway. An earlier design kept the estimate as bootstrap; it's dropped in favor of the gate.

This anchor covers text tracks too — they have no SourceBuffer to pin, so the shared anchor is the only way to place them. WebVTT cues are assumed already time-aligned (the analog of assuming encoded A/V samples are aligned); what we align is the text track's segment timeline, by PDT, exactly as for A/V. (That cues are sparse/overlapping — a cue may begin or end outside its segment's nominal bounds — is a text loader/eviction concern, not an anchoring one.)

Scope: this fixes the single rolling anchor vs. per-segment measured times question deferred by live-timeline-anchoring, and realizes the manifest → buffer half of that decision's Boundary as a single shared anchor.

Context

live-timeline-anchoring settled the anchor source — PDT, the universal wall clock shared across renditions — but left open how that anchor drives a shared presentation timeline. Today's anchor-presentation-timeline pins each selected A/V track to its own buffer independently, and doesn't anchor text at all.

Two facts make a single shared anchor sufficient — and per-track pinning redundant:

1. MSE plays all SourceBuffers on one element timeline. There is a single currentTime; audio and video are coerced onto one native-PTS coordinate.
2. Native-PTS default (mse-timestamp-offset) — no timestampOffset, so every track shares the encoder's PTS clock.

Under (1) + (2) there is no inter-track skew, so one track's (media-time ↔ PDT) pair describes all tracks; further pins would only restate it. And text — which has no buffer to pin — can be placed only by a shared anchor.

Assumption committed: no inter-track PTS skew. This is the existing live-model assumption (native-PTS default); per-track skew correction remains deferred to non-zero-pts-support. If skew ever needs handling it layers a per-track offset on top of the shared anchor — it does not require returning to per-track pinning.

Alternatives Considered

• Per-track buffer pins (today's anchor-presentation-timeline). Pin each selected A/V track to its own buffered segment. Rejected: under the no-skew assumption the pins necessarily agree, so the extra pins are redundant restatement; and the approach structurally cannot anchor text, which has no SourceBuffer — keeping it would force a separate, divergent text path for the same concern.

• Per-track PDT estimate only (no buffer truth). Place every track from the manifest estimate (sequence × avgDuration + PDT) and never pin. Rejected: drops the authoritative correction — the estimate is duration-variance-prone (it produced an observed ~27 s drift at window turnover), and the buffer pin is what makes the timeline exact. The estimate is the right bootstrap, not the final answer.

Rationale

PDT is already the cross-track anchor source; this decision commits to one anchor instead of N. The win is uniformity: audio, video, and text all position by the same (media-time ↔ PDT) rule, so the behavior has one code path, text stops being a special case, and "first track to buffer wins" makes the anchor available as early as possible. Pinning once (not per reload) keeps the drift-surfacing property: if a track's PDT disagrees with the established anchor, it shows up as a visible desync rather than being silently re-corrected every reload.

This promotes open question [4] sync anchor in live-presentation-modeling from "per-segment / per-track" to "presentation-level," as that doc anticipated.

Verification

Implemented. anchor-presentation-timeline is a reactor that, on first buffer ground truth (entry to anchored), establishes the shared anchor once and stamps it onto every track via positionAllTracksToAnchor — resolved tracks shifted, shells given startDate for the parser's placeOnAnchor to honor at first resolve. No estimate, no per-track positioning pass. The old per-track pin primitives (anchorTrackToBufferedSegment / anchorTrackToSequenceOrigin) are removed.

Unit-covered: the parser honors a pre-applied anchor (parse-media-playlist.test.ts); positionAllTracksToAnchor shifts resolved tracks + stamps shells, identity- preserving (presentation-anchor.test.ts); the behavior establishes from the buffered video track and stamps all tracks, first-track-wins, establishes once across reloads, and is inert without buffer truth or a selected track (anchor-presentation-timeline.test.ts); seekToLiveEdge holds its seek until presentationAnchor is published (seek-to-live-edge.test.ts). Live A/V init smoke-tested on an ephemeral Mux LL-HLS stream: with no estimate, the seek is gated until the pin lands, then fires once to the live edge — clean startup, no stranding (an un-gated build stranded the playhead at the raw-window seek). Text anchoring against a live subtitled source is still unverified end-to-end; an intermittent ~2 s audio model offset (buffers stay aligned) is tracked as a separate startup race.

See also

• live-timeline-anchoring — the anchor source (PDT); this decision resolves its deferred "single rolling anchor vs. per-segment measured times" question.
• mse-timestamp-offset — native-PTS default; the manifest → buffer offset half this anchor realizes.
• non-zero-pts-support — where per-track skew correction lands if the no-skew assumption ever breaks.
• live-presentation-modeling — open question [4], promoted to presentation-level here.
• live-stream-support — the anchor-presentation-timeline behavior that implements this.