The Live/DVR panel guessed DVR from a 60s seekable-window threshold, so an
EVENT source read as 'sliding live' until it had aggregated enough segments.
Classify from the parsed playlistType ('EVENT') via getMediaPlaylistMetadata
instead. Gate on metadata presence (show 'live (resolving…)' until a timeline
track has metadata) so an EVENT source no longer flickers through 'sliding
live' on load/reload before the playlist resolves.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Surfaces the HLS media-playlist metadata accessor (and MediaPlaylistMetadata
type) on @videojs/spf/hls, including playlistType ('VOD' | 'EVENT'). Lets
consumers distinguish an EVENT / DVR source from sliding-window live directly
from the manifest instead of inferring it from the seekable window size.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
apps/sandbox/scripts/live/ — spin up an ephemeral Mux live source for
exercising the live path in any HLS-capable sandbox page:
- create-stream.sh: create a low-latency Mux live stream (creds via
--token-id/--token-secret flags or MUX_TOKEN_ID/MUX_TOKEN_SECRET env;
--quiet for scripting)
- broadcast.sh: push an ffmpeg testsrc + tone feed to the stream
- dvr-url.sh: resolve active_asset_id to the DVR/EVENT playback URL
- live-test.sh: orchestrate create -> broadcast -> wait -> open the page,
parameterized by --page (renderer-agnostic), --flavor sliding|dvr|both,
--port, --params, --latency; deletes the stream on exit unless --keep
- README.md: quick-start, manual steps, and cross-renderer reuse notes
Credentials are read only from flags/env; none are committed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add issue refs to the live/DVR Open-questions bullets (#1743-#1746) and
a Status pointer to the Live/DVR Seekable and Anchor Hardening epic
(#1742), so the design docs and the issue tracker are bidirectional.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- live-stream-support.md: correct the window-exit guard description and
test matrix to match the shipped fix (guard no longer bails on
`seeking`); add the resolved out-of-window-seek-stall note; add Open
questions for the seekable-range "lip", clamp-to-seekable as the
general mechanism, and back-of-window yank-to-edge on discrete window
slides. Remove stray EOF tags.
- live-presentation-modeling.md: add Open question flagging the
model <-> anchor <-> resolve-track coupling for a holistic revisit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The window-exit guard in seekToLiveEdge bailed whenever
`mediaElement.seeking` was true, to avoid fighting an in-flight DVR
scrub-back. But a seek whose target sits behind the window start can
never complete — the data has slid out of the window and been evicted —
so `seeking` stays true forever and the playhead strands permanently,
the very stall the guard exists to rescue.
Drop the `seeking` bail. The `currentTime < windowStart` test is itself
the precise discriminator: an in-window scrub-back lands at
`currentTime >= windowStart` and never trips it, so only a stuck
out-of-window seek is repositioned to the live edge.
Verified live (Mux sliding-window LL-HLS): repeated seeks to the window
start now snap back to the edge within ~1.5s instead of stalling, while
mid-window DVR scrub-back still holds.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a Live/DVR panel (stream type, window classification, live gap,
DVR window length, buffer-ahead, presentation anchor + wall-clock) and
seek controls (seek-to-live, -10/-30s, jump to window start) to the SPF
segment-loading harness. All derived sandbox-side from presentation
streamType + the native video; degrades cleanly to on-demand.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The initial "jump near the live edge" was modeled as a reactor entry, so it
re-fired on every entry into `live`. A transient precondition flip (e.g. the live
window briefly unknown mid track-switch) re-enters `live` for the same source and
yanked a viewer who had scrubbed back into the DVR window. The actual rule is
"on initial load of a source, jump near the edge — once," so latch it on the
source url: a genuine source change re-seeks; a transient re-entry does not. The
continuous window-exit guard is unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
liveWindowFromState keyed the live window on the *selected* timeline-bearing
track, so when an ABR/user switch briefly left the newly-selected rendition
unresolved (a shell, no segments), the window blinked to null. That flipped
seekToLiveEdge out of `live` and stalled the seekable-range writer. The live
window is a presentation-level property — all renditions are time-aligned and
share the anchor — so fall back to any resolved track of the timeline-bearing
type when the selected one isn't resolved yet, rather than returning null. A
deselected track's window may trail live by up to one reload during the switch
gap; the selected track's fresh window resumes the moment it resolves.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
bufferedAnchorFor paired the newest appended segment with maxBufferedEnd, but
appendSegment streams one appendBuffer per chunk, so the newest segment's bytes
are only partway into `buffered` mid-append — mis-reading its native start by up
to a full segment, skewing the derived anchor ~2s and shifting the whole model
timeline. seg0 went negative on a window anchored at the origin, so
setLiveSeekableRange threw every reload and back-seek stalled in the gap. Pin to
the trailing edge instead (earliest settled segment + minBufferedStart), which
only moves on eviction, and exclude partial (still-appending) segments — the
actor already flags them. Intermittent and live-only; exposed by DVR/EVENT
growing windows, masked at the live edge.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The behavior's mechanism — pin one track from buffer ground truth, derive one
shared offset, stamp every track onto it — is format-neutral; only the offset
source (PDT) is live-specific. Rename it and its published signal (liveAnchor →
presentationAnchor, matching the PresentationAnchor type it holds) so the name
reflects the general role, and note the non-zero-PTS reuse path through the
existing resolveBufferedAnchor seam. No behavior change.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The anchor reactor's monitor re-derived buffer ground truth on every reload, so a
transient loss of it — a buffer underrun, flush, or seek that momentarily empties
both SourceBuffers — flipped the reactor back to `unanchored` and cleared
`liveAnchor`. The anchor value itself is idempotent, but `seekToLiveEdge` gates
its `live` state on `liveAnchor` being set: clearing it drove `live → inactive →
live` and re-fired the one-time live-edge seek, jumping the playhead forward.
Make the anchor sticky per source: once `liveAnchor` is published, stay
`anchored` while the presentation stays resolved; only a source change (the
presentation reset to an unresolved value) reverts it. This matches the
"established once per source" intent in live-presentation-anchor.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A track reload read its `previous` (the prior window it carries the timeline
forward from) before the playlist fetch await, then parsed against that stale
snapshot after. When anchor-live-tracks established the shared live anchor during
the fetch — stamping every track's timeline via positionAllTracksToAnchor — the
in-flight reload wrote a window built on the pre-stamp (un-anchored) snapshot,
clobbering the stamp. Anchoring is pin-once, so the track was never re-corrected:
its model timeline sat seconds off the anchor and the loader stopped fetching it
near currentTime. Observed live on Mux LL-HLS as the selected video track
stranded ~hundreds of seconds off the anchor while its un-reloaded ABR-shell
siblings stayed anchored — video never buffered, playback stalled.
Re-read `previous` from a fresh peek after the fetch and parse against that. With
no yield between the re-read and the write, no concurrent writer can interleave,
so the stamp is carried forward instead of lost.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework live anchoring around a single shared anchor established only from
authoritative buffer ground truth, dropping the unreliable manifest estimate:
- anchorLiveTracks establishes the anchor once per source from the first
actually-buffered A/V track (the buffer actor's `initTrackId`, not the
selection), stamps it onto every track via `positionAllTracksToAnchor`
(resolved tracks shift; not-yet-resolved shells get `startDate` for the
parser's `placeOnAnchor`), and publishes it as `liveAnchor`.
- seekToLiveEdge gates its live-edge seek on `liveAnchor`: with no estimate the
pre-anchor window is the raw one, and seeking there would strand the playhead
when the pin later shifts the window. Gating holds the seek until the timeline
is anchored, so it targets the final native-PTS window. (Smoke-tested on Mux
LL-HLS: single seek to the live edge after the pin, clean startup.)
- The resolveBufferedAnchor seam becomes `(deps) -> { trackId, segmentId,
actualStart }`, reading the buffer actor directly (video-first).
An intermittent ~2 s audio model-`startDate` offset (buffers stay aligned, so
playback is synced) remains, tracked as a separate startup race.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
parseMediaPlaylist now places a first-resolved window relative to a
`startDate` set on the unresolved shell (each segment at PDT − anchor)
instead of always anchoring at the local base 0. This lets the shared
presentation anchor pre-position not-yet-resolved tracks so they resolve
already on the shared timeline — no separate positioning pass needed.
Inert until a caller sets `startDate` on a shell; a playlist with no PDT
falls back to the local base, and the recomputed track `startDate` reads
back as the anchor.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
anchorTrackToBufferedSegment and anchorTrackToSequenceOrigin implemented
the per-track pinning that the shared presentation anchor replaces; they
have no remaining callers. Drop them and their tests, repoint
buffered-anchor's doc link to presentationAnchorFromBuffer, and remove
the now-moot bridge test in presentation-anchor.test.ts.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Convert anchor-live-tracks from N per-track buffer pins to a single
shared (media-time <-> PDT) anchor applied to every selected track —
video, audio, and now text. A two-state reactor (unanchored -> anchored)
positions from the manifest estimate until a selected A/V track has
SourceBuffer ground truth, then establishes the shared anchor once
(first track to buffer wins) and positions each track onto it by PDT,
leaving it to the parser's carry-forward thereafter.
The resolveBufferedAnchor seam now takes the standard (track, deps)
setup arguments instead of closing over engine scope; the HLS engine's
implementation lives in its own generic module (resolve-buffered-anchor)
so a future audio-only-live engine can reuse it. anchorLiveTracks is now
a makeAnchorLiveTracks<Context>() factory mirroring makeShareSignals.
Realizes internal/decisions/live-presentation-anchor.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Introduce media/presentation-anchor.ts realizing the single presentation-level
anchor decision (internal/decisions/live-presentation-anchor.md):
presentationAnchorFromBuffer / presentationAnchorEstimate derive the shared
(media-time ↔ PDT) anchor — buffer-pinned, or the pre-buffer estimate — and
positionTrackToAnchor re-origins any track onto it by its own per-segment PDT.
Tested to generalize anchorTrackToBufferedSegment. Consumed by the
anchor-live-tracks reactor conversion (next), which replaces the per-track
anchor primitives.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Capture the decision to hold one rolling (media-time ↔ PDT) anchor — learned
from the first A/V track to obtain SourceBuffer ground truth and applied to all
selected tracks (incl. text) by per-segment PDT — replacing today's per-track
buffer pins, which are redundant under the no-skew assumption and can't anchor
text (no SourceBuffer). New decision doc live-presentation-anchor.md; resolves
the deferred single-rolling-anchor question in live-timeline-anchoring and
promotes [4] in live-presentation-modeling to presentation-level.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The HLS live-latency bridge was defined inside createSimpleHlsEngine's closure
despite capturing nothing — a fresh allocation per engine, and pure HLS logic
stranded where it can't be tested. Move it to media/hls/reload-policy.ts as a
pure resolveLiveLatency(presentation, trackId) next to liveLatencyFor; the
engine injects the import. Adds direct coverage for the bridge (previously only
stubbed via seek-to-live-edge's injected resolver).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
context.mediaSource is published only while open (setupMediaSource is the sole
writer; cleared on detach), and a non-null live window means the timeline-bearing
track is still Infinity-duration, so endOfStream hasn't ended the MS. Present +
live window ⟹ open, so the explicit `readyState !== 'open'` guard before
setLiveSeekableRange (which throws off-open) is redundant. The "until open" test
becomes a publish transition.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The repositionPolicy seam was removed when seek-to-live-edge's guard became
reload-driven. Reframe the sibling references: the guard does window-exit, and
the edge-only [live-edge-only-mode] use-case supplies its own reposition
behavior (alternative-impl) rather than flipping a seam.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
seek-to-live-edge is now a reactor (inactive ↔ live): entry does the one-time
seek, effects runs the window-exit guard (window-update re-fire + a single
`play` listener — `play`, not `playing`, since a slid-past playhead is at an
unseekable position where `playing` never fires). The repositionPolicy seam
was removed once the guard became reload-driven (nothing consumed it); the
live-edge-only use-case defines its own reposition behavior when built.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework seek-to-live-edge's guard effect: read the live edge first (the only
tracked dep) so window-update re-fires survive the paused bail, reposition on
each window slide (catches a stall, where timeupdate is silent), and add a
single `play` listener for immediate reposition on resume — `play`, not
`playing`, since after a long pause the playhead sits behind the window at an
unseekable position where `playing` never fires. Drop the now-unused
repositionPolicy seam; the live-edge-only use-case reintroduces it when real.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the single effect with a two-state machine (inactive ↔ live) gated on
deriveState (mediaElement + published-hence-open MediaSource + a derivable live
edge). The one-time seek becomes the live state's entry; the window-exit guard
becomes its effects. Entry-once-per-live-entry dissolves the closure `seeked`
latch — a source change drops to inactive and re-entry re-seeks. Drop the
MediaSource readyState check: setupMediaSource publishes the signal only once
open, so the signal's presence is the open gate.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
liveWindowFor is now {start, end}; the holdback rule lives in liveLatencyFor
and reaches seek-to-live-edge via the resolveLiveLatency seam + getLiveEdge.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Unwind the HLS holdback assumption from seek-to-live-edge so the live
behaviors stay format-neutral. liveWindowFor returns a purely geometric
{start, end}; the 3×targetDuration HOLD-BACK rule moves to liveLatencyFor
in the HLS reload-policy, injected by the engine as seek-to-live-edge's
resolveLiveLatency seam. A new getLiveEdge primitive bundles the window
with the resolved latency into {start, end, liveEdgeStart}, so the behavior
consumes one edge and never reads delivery-format metadata. A DASH engine
injects its own resolver (suggestedPresentationDelay) with no model change.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reframe the "clearLiveSeekableRange() on termination" follow-up as a
deliberate non-action rather than a gap. Per the W3C MSE spec, the live
seekable range is consulted only while duration === Infinity; when a live
stream ends, endOfStream() sets a finite duration and the UA derives seekable
from buffered + duration, ignoring the live range — so clearing is unnecessary.
Clearing on the ENDLIST->finite-Track.duration transition would also be
premature (duration is still Infinity until endOfStream) and shrink seekable to
buffered-only. No logic change; the existing behavior (bail on null window) is
already correct, and the 'no-ops for a complete playlist' test locks it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
liveWindowFor hardcoded the selected *video* track, so audio-only live (no
video track / no selectedVideoTrackId) derived no window — leaving both
seek-to-live-edge and sync-live-seekable-range inert. Make liveWindowFor
track-type-agnostic (findTrackById instead of findTrack('video')), and add a
liveWindowFromState primitive that picks the timeline-bearing track:
selectedVideoTrackId ?? selectedAudioTrackId (video positions both A/V; audio-only
falls back to audio). Both behaviors now share that single call site, removing
the two brittle, must-stay-identical liveWindowFor(...) call sites.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
setLiveSeekableRange throws only on a non-'open' readyState or an invalid
range. The readyState is checked synchronously immediately before the call
(no await between, so it can't change), and liveWindowFor guarantees
0 <= start <= end — neither throw vector is reachable. The try/catch was
load-bearing pre-split (it also wrapped a duration write that could throw
mid-append); that write is gone, leaving the catch dead.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
syncLiveSeekableRange dropped its defensive mediaSource.duration = Infinity
write — it duplicated updateMediaSourceDuration (the canonical owner). Per the
W3C MSE spec, setLiveSeekableRange requires only readyState === 'open', not a
set duration, so this behavior never needed it. Verified live (Mux LL-HLS):
with the write removed, duration is Infinity and the initial seek lands at the
holdback from the first frame — updateMediaSourceDuration's async write resolves
fast at startup (buffers idle), ahead of seekToLiveEdge's seek.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the Implementation surface + live-edge phase row to attribute
setLiveSeekableRange to syncLiveSeekableRange and the window derivation to the
pure liveWindowFor helper, rather than the (now leaner) seekToLiveEdge.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Decompose the seek-to-live-edge behavior (which coupled three concerns) into:
- liveWindowFor (media/live-window.ts) — a pure derivation of the live window
{start,end,targetDuration}, or null for VOD/ended/unresolved. The single
source of truth, centralizing all inertness so consumers don't re-derive.
- syncLiveSeekableRange (behaviors/dom) — declares setLiveSeekableRange on each
window slide, including while paused (the seekable range must stay current
regardless of play state).
- seekToLiveEdge — now just the one-time HOLD-BACK seek + the window-exit guard,
consuming liveWindowFor; sheds the seekable/duration writes (keeps the
mediaSource open-gate so the seek lands in the declared range).
Composed syncLiveSeekableRange before seekToLiveEdge to preserve the
declare-before-seek ordering (a seek outside seekable is clamped). Behavior-
preserving; tests redistributed (7 liveWindowFor + 14 seekToLiveEdge + 5
syncLiveSeekableRange). Deferred follow-ups: clearLiveSeekableRange on
termination; duration-ownership cleanup vs updateMediaSourceDuration; B's
seeked-latch source-reset; window-derives-from-accumulated-segments-while-paused.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Extend seek-to-live-edge with a live-window playhead guard: while playing
(!paused && !seeking && readyState>0), reposition currentTime to the live edge
(holdback) when it falls outside the sliding window [windowStart, windowEnd]
(0.1s tolerance). Covers a paused-too-long playhead the window slid past
(caught on the playing resume) and playback that fell behind on poor network
(caught on the effect's window-update re-fire, since timeupdate stops once a
stall freezes currentTime). In-window pause and DVR scrub-back are untouched.
The one-time initial seek is preserved (latched) and the guard reuses the same
liveEdgeStart, keeping the live playhead position single-owned. repositionPolicy
is a behavior-scoped seam (default 'window-exit'); the edge-only 'on-resume'
branch is inert, reserved for a future live-edge-only-mode use-case.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Promote the live-window playhead guard phase from planned to implemented
(window-exit reposition in seek-to-live-edge): update the Status block, phase
row, What's-not-implemented, Implementation/Config surface, and Verification
(landed unit matrix; e2e deferred). Record the resolved seam-shape decision
(behavior-scoped repositionPolicy, not a public engine-config field) and guard
placement (extends seek-to-live-edge).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bump live-stream-support to sketched depth grounded in feat/spf-hls-live
(reload loop, sliding-window tracking, Infinity duration, live-edge seek,
ENDLIST termination all implemented); resolve its 5 open questions. Add the
planned live-window playhead guard (reposition on window-exit, covering
paused-too-long and fallen-behind) with a repositionPolicy seam for a future
edge-only composition.
Cascade: register [live-edge-only-mode] use-case candidate; cross-ref
buffer-stall-recovery (in-window stall vs window-exit reposition) and
dvr-event-stream-support (seekable spectrum).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The model timeline (an averageDuration×sequence estimate) could drift from
the SourceBuffer's native-PTS timeline across reloads. At ENDLIST the drifted
model placed the final segments behind the playhead, so the loader skipped
them and end-of-stream's isLastSegmentAppended never satisfied — playback
stalled in `waiting`, duration stuck at Infinity, `ended` never fired.
Pin the model to ground truth: once a segment is buffered, re-origin the track
onto where it actually landed (anchorTrackToBufferedSegment), correlated via
bufferedAnchorFor over the buffer actor's DOM-free snapshot. Pin once per track
(the offset is constant under no-discontinuity); the parser's now-PDT-exact
carry-forward maintains it. The sequence estimate stays the pre-buffer
bootstrap. anchorLiveTracks stays DOM-free — the engine injects the resolver
from the buffer actors; no timestampOffset (preserves A/V sync). The same pin
serves non-zero-PTS VOD.
Smoke-tested on a live Mux LL-HLS stream: durationchange → finite duration →
plays out → `ended`, no stall.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
When a live reload skips the whole window (no media-sequence overlap),
placeOnPreviousTimeline bridged the gap with a target-duration estimate,
which drifts whenever actual segment durations differ from the declared
ceiling. PROGRAM-DATE-TIME is the spec-consistent cross-reload reference and
places the turnover window exactly; use it when present, falling back to the
estimate only when PDT is absent.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The createResolveTask factory was a single-call hoist (the RecurringRunner
clones the task itself), so inline the task back into runner.schedule(...) as
on main, and inline the shouldLoadTrack gate the same way. Restore the
surrounding comments and formatting to main's, deviating only where the
refactor changed meaning: the gate now reloads resolved-but-incomplete (live)
windows (resolved→complete), and the obsolete scheduler/commit-time-id-check
notes are dropped. Net diff against main: 131+/70- down to 33+/18-.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
startSequence read ambiguously. Rename to presumedStartSequence across the
hls engine config, the anchorLiveTracks behavior, and the (HLS-agnostic)
anchorTrackToSequenceOrigin media primitive — conveying that it's the media
sequence presumed to be the stream origin. Kept HLS-free so the media-layer
primitive stays layering-clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Live playback was folded into createSimpleHlsEngine (VoD + live, one
composition), making the separate createLiveHlsEngine — which only wrapped
the same behaviors plus the hls engine itself — redundant, and leaving
live-playlist-spike an orphaned experiment with no exports or consumers.
Delete both, drop the ./live-hls package export and tsdown entry, and point
the sandbox live harness at createSimpleHlsEngine.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
live-presentation-modeling: category [3] refetch policy is realized as the
pure §6.3.4 cadence (mediaPlaylistReloadDelay) + delayedReschedule +
RecurringRunner, fetch scheduling per-track. Record the decided error
semantics — a failed reload's rejection propagates and ends the recurrence;
transient-fetch retry is deferred to network-resilience, kept out of the
cadence — and mark the [3] placement open question decided.
ll-hls-support: note that regular-live change-detection keys off the
full-segment signature, so a parts-only update reads as unchanged; LL-HLS
must fold part progression into change-detection or switch to blocking reload.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The resolve-track live-reload tests stub the reschedule, so they never
assert the interval. Drive the real composition the engine wires —
RecurringRunner + delayedReschedule + mediaPlaylistReloadDelay + Task.clone
previous-threading — under fake timers and assert: a sliding window reloads
at the full target duration (per RFC 8216 §6.3.4), a stale window floors at
half target and never faster, and a completed playlist stops after one run.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The RecurringRunner propagates a rejected run as the recurrence's failure
(Promise.all short-circuits before any retry verdict lands), so the
retry-on-error affordance in delayedReschedule and mediaPlaylistReloadDelay
was dead code. Remove it: delayedReschedule awaits the run directly (a
rejection now rejects the reschedule), and mediaPlaylistReloadDelay takes a
non-optional current track. Transient-fetch-failure recovery belongs at the
fetch layer, not in the cadence.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the imperative `#loop()` with a single chained promise: each cycle's
`.then` returns the next cycle's `schedule(clone())`, so the recurrence is the
method calling itself. The slot is released just before re-scheduling the same-id
clone so the call advances rather than dedup-returning; ownership is tracked by
`#active === task`.
Error handling moves downstream — the runner no longer invents a retry policy:
- A genuine run/reschedule failure rejects schedule()'s promise (propagates to
the caller); no swallowing.
- The runner's own cancellation (abort/supersede/destroy) is not a failure, so an
aborted recurrence settles quietly — callers don't `.catch` routine teardown.
Consequences:
- `reschedule` is now required; `runOnce` expresses run-exactly-once explicitly
(a missing reschedule is a bug, not a silent run-once).
- Reschedule-driven retry-on-transient-error is dropped (a rejected run is
terminal). The retry logic in delayedReschedule / mediaPlaylistReloadDelay is
now vestigial — to be cleaned up or relocated to the fetch layer next.
- `resolve-track` catches schedule()'s promise (abort settles quietly; genuine
resolve failures end the recurrence, TODO surface to state).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Collapse `Reschedule<T>` from `(task, previous, signal) => ...` to
`(task) => PromiseLike<boolean>`. One `delayedReschedule` instance is shared
across the video + audio runners, so per-recurrence state can't live in its
closure — the task is the only per-recurrence carrier, so both dropped params
move onto it:
- `task.signal` exposes the task's composed signal. RecurringRunner drops its
separate `#abort` AbortController: the task is now the sole cancellation
channel and loop ownership is task-identity, not an AbortController token.
- `task.previous` is carried by `clone()` as lineage
(`#previous = this.#value ?? this.#previous`), reproducing the last-*successful*
value semantics (an errored cycle inherits the prior good value) with no
bookkeeping in the runner — `#loop` no longer threads previous/result.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Memoize the run-machinery promise itself (`#promise ??= this.#execute()`) rather
than reassigning `#promise` to fresh `Promise.resolve(value)` / `Promise.reject(error)`
on settle. The reassigned promises were never awaited, so an errored or aborted
task that's not re-run (the norm — the RecurringRunner moves on to a clone) left
an unhandled rejection. The memoized promise is the one callers await, so it's
always handled.
Also closes a sync-throw gap: a `#runFn` that throws synchronously is now captured
as a rejected memoized promise instead of leaving `#promise` unset (which would
re-execute on the next run()).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the signal-as-event live-reload scheduler with a runner-driven model.
The `resolveTrack` loader schedules its resolve work on a new `RecurringRunner`
that re-runs the task on an injected `reschedule` policy; the separate
`scheduleTrackReload` behavior and its per-type reload-epoch signals are deleted.
Core (`core/tasks`):
- `Task.run()` is now memoized (runs once, shares the result across calls) and
gains `clone()` (fresh, pending, structurally identical) — added to `TaskLike`.
- `RecurringRunner`: single-slot, id-keyed (dedup same id / abort-and-replace on
new id), time-free. Each cycle runs `Promise.all([task.run(), reschedule(task,
previous, signal)])` and re-runs a `clone()` while reschedule resolves `true`.
- `Reschedule<T> = (task, previous, signal) => PromiseLike<boolean>` — invoked
concurrently with the run, observes it via the memoized `run()`, owns its delay.
- `delayedReschedule(cadence)` builds a Reschedule from a pure ms-cadence fn,
start-anchored (subtracts the run's elapsed) so reloads are measured from
load-start per RFC 8216 §6.3.4, preserving half-on-unchanged.
Supporting:
- `@videojs/utils/time`: add cancellable `sleep(ms, signal)`.
- `media/hls/reload-policy`: `mediaPlaylistReloadDelay` (pure cadence; relocated
scheduler logic — target-duration, half-on-unchanged, stop-on-ENDLIST, retry).
- `resolve-track`: baked universal completeness gate + injected `reschedule`;
engine composes `delayedReschedule(mediaPlaylistReloadDelay)`.
WIP: not fully validated end-to-end against a live stream through this path.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
