Skip to content

feat(playback): one playback and subtitle reliability bundle (replaces #444, #446–#458) - #459

Draft
randrini wants to merge 56 commits into
mainfrom
integration/playback-combined2
Draft

randrini wants to merge 56 commits into
mainfrom
integration/playback-combined2

Conversation

@randrini

Copy link
Copy Markdown
Collaborator

Problem

This replaces fourteen stacked pull requests with one reviewable change. They accumulated over two weeks of production testing on virtual-library playback, and reviewing them individually had become the problem rather than the fix: each PR was verified in isolation, but several only made sense together, and two of them (the size-mismatch tolerance and the identity guard) composed into a behaviour neither described alone.

The underlying symptoms, all observed on a live deployment:

  • A selected version was replaced before playback in 8 of 12 starts, sometimes across resolution and dynamic range, with no explanation to the client.
  • A 4K HEVC session rebuilt its media pipeline 107 times in 170 s (508 manifest loads in 300 s) while the server served every segment at 200 and p50 250 ms. 477 of those reloads fell within 400 ms of a catalog version check.
  • PGS and ASS subtitles frequently never rendered: bitmap pages re-read the container prefix per page, and text windows ran for 40–60 s before the client gave up.
  • The same 69 GB object was served for three different declared releases, and 538 catalog rows carried a 1080p release name with a probed 2160p resolution.
  • A single failed play attempt left an item with the Play button disabled.
  • Retryable start timeouts surfaced as 500 internal_error; a client cancel surfaced as 502.

What this change does

Selection and identity

  • An explicit pick is sent as explicit on the wire, is honoured by the planner, and is never silently replaced by a different release.
  • A plan's effective row must be one of the item's selectable version rows. An unlisted row is refused, that candidate is excluded, and exhaustion answers a retryable terminal naming the version list.
  • A size gap between what a provider advertises and what is served no longer blocks probing or playback of that row's own bytes — but unverified bytes may not establish a release's inventory and may not move a plan onto another release. A foreign plan is refused and the row reports source_mismatch instead of a generic "unavailable".
  • Rotations may adopt an identity but never change the selected version or drop audio/subtitle tracks.
  • A client abort or an unverified row no longer marks a version failed, so one bad attempt cannot disable an item.

Subtitles

  • Bitmap pages are served from one progressive demux per source behind a coverage watermark, with a read budget that refuses an expensive page before reading it and answers retryable 503 with Retry-After and X-Subtitle-Coverage.
  • A windowed text extract carries an elapsed budget; a breach answers retryably and warms the breached range so the retry is served from the artifact rather than repeating the read.
  • A cue-less or header-only response is never served as content and never cached as last-good.
  • A committed .sup artifact is not invalidated by a seek, and a subtitle track change keeps the playback position.

Player and client

  • Catalog version checks no longer restart the media pipeline: the version list is read through refs, so a projection changes menus only. Polling is coalesced per row set and backed off (12 checks per 5 minutes on a 452-row title, down from 452).
  • Segment retries are bounded per index and per streak with backoff, and exhaustion surfaces a failure instead of re-fetching the same segment hundreds of times.
  • A blocked autoplay offers a tap-to-play overlay instead of an indefinite "Loading video".
  • The substitution notice names the release, stays quiet for a same-release mirror, and the item page resolves a playable version when the remembered one left the list.
  • Version liveness uses the v2 operation; the retired /api/v1 route was returning 410 for every call.

Diagnostics

  • Retryable start failures answer 503 with Retry-After instead of 500; client cancels answer 408.
  • Substitution cause is published on the plan and on replans.
  • A prefetch logs why it ran or skipped.

Verification

  • CI green on the integration head; the branch is the composition of the individual PRs, each of which was verified separately before merging here.
  • Integration gates: go build, go vet, scanner/apiv2/catalog suites, focused playback and handler suites, -race on the new tests, playback fixtures, v2 OpenAPI and web types, fork invariants, tsc, and the focused web suites.
  • The only Go failures are two pre-existing ones that reproduce on main (TestOnDemandSubtitleSegmentsDoNotWaitForTheStream, TestServeExtractDiscardsACappedDemuxCopy) plus a load-sensitive timing test that passes in isolation.
  • Production verification runs are recorded in the individual PRs being superseded.

Known open, tracked separately

  • The provider returns the same object for several distinct release rows, which is why a row's declared size and the streamed bytes can disagree. The server now refuses and explains rather than mislabelling; the mapping itself is upstream.
  • A 4K H.264 transcode is still planned for clients that cannot decode it in real time (33 % dropped frames in testing).
  • Bitmap page cost is measured as elapsed time, not bytes: ffmpeg reads HTTP with recv(2), which /proc/PID/io does not count.
  • Native clients need follow-up for the new retryable subtitle-page answers.

AI disclosure: implemented with DeepSeek V4.1 Flash 1017 (ollama-cloud/deepseek-v4.1-flash:1017) in the OpenCode agent harness, with build, test and lint gates run in the project's libvips Go image.

randrini and others added 30 commits November 13, 2026 17:02
A windowed PGS extract cannot seek a non-seekable relay, so ffmpeg demuxes
the container from byte 0 and discards the prefix: a page at offset S costs
(S + W) x bitrate, not W x bitrate. A 120 s page of an 18.25 GB / 35 Mbps
source is ~525 MB, which is also the two-minute extraction timeout, so such
pages were killed at the timeout and answered with a partial .sup that held
no complete display set.

The extract now watches the process's own read count and kills it once a
page has read more than 256 MB, the same order as the largest source a page
read is still worth attempting. The page answers the retryable 503 the
client already backs off from, with a distinct additive problem code
(subtitle_page_too_costly), a counter, and the existing per-identity
extraction backoff so a retry does not pay the same read again.

Only a bounded bitmap page read from a remote source is capped: a
whole-track extract must read everything by design, an artifact-backed
window reads a local file, and a local source's prefix read is a disk read
that finishes in seconds.
…ce demux

A windowed PGS extract cannot seek a non-seekable relay, so every page paid
for the whole container prefix again: on an 18.25 GB / 35 Mbps source a
120 s page reads ~525 MB, which is the window extract timeout, so pages
returned partial .sup bytes with no complete display set and were never
cached.

One unbounded .sup demux now runs per source identity, track and format
generation, single-flighted through the cache's warm slot and detached
relay budget. It writes the track's artifact and indexes the display sets
as bytes land, so the cache knows how far the track is covered:

- a page inside the coverage is served by copying those display sets out
  of the artifact, with no source read and no ffmpeg;
- a page beyond it answers the retryable shape with X-Subtitle-Coverage
  describing what is actually covered, never a truncated run;
- on end of file the artifact flips into the committed whole-track entry.

The watermark only advances at a complete display set (PCS through END) and
is derived from bytes already written to the artifact, so a page is never
served ahead of what has been parsed. A page refused for its read cost also
starts the fill, since the artifact is what will serve it; the API handler
owns that fill because its relay registration outlives the request.

Text windows, local files, and a remote container whose size is unknown
keep their existing paths.
…ably

The progressive bitmap fill never ran in production, so every page still cost a
fresh source extract. A page miss is served by the handler's detached warm, and
that warm admitted a bitmap track only while paused; a playing session dropped
it with "bitmap full-track warm stays paused-only". Five page misses, five
skips, no artifact, no watermark, no coverage-gated answer: 100.2 s for the first
page and 70.6/75.7/88.1 s for later distinct pages, with only an exact repeat
fast from last-good.

A bounded bitmap page is the one bitmap request whose fill is the page path, so
it now routes to the waiting-page admission: the fill starts while playing,
single-flighted per (source identity, track, format) through the cache's warm
slot and detached relay budget, and it replaces the bounded window prefetch,
which would read the same source again for pages the fill publishes. Every other
bitmap request keeps the paused-only full-track warm.

The read cap measured the wrong cost. A page at 3600 s returned 200 after 88 s
with its read count under the cap because the relay answers the seek with range
reads, so the page is now priced before the extract: the container prefix it
would discard, `start x rate`, from the row's size and runtime or bitrate, and
in wall-clock terms from the read rate this identity's own extracts measured.
A page beyond 256 MB of prefix, or whose prefix would take more than 45 s at the
measured rate, is refused before any source read with the retryable 503, its
Retry-After and X-Subtitle-Coverage, and that refusal starts the fill. An opening
page has no prefix and extracts exactly as before. The runtime 256 MB cap stays
for pages that are still attempted.

An extraction that ran out the window extract deadline answered a non-retryable
500 while the client had four attempts to spend. A page that times out now
answers the same retryable page-cost shape as the read cap; a windowed text
extract that fails or is canceled no longer commits a 200 carrying a header and
half a cue, because the slice is held until its extract completes and dropped
otherwise. The handler classifies both through one mapping: deadline, upstream
5xx and a lapsed relay token are retryable, everything else stays a loud 500.

A `.sup` muxer that refuses the mapped stream's codec after a release rotation
("sup muxer supports only codec hdmv_pgs_subtitle", exit 234) is a mapping the
drift probe missed, so it now reads as a stream-map error and takes the existing
re-probe and remap path — a remapped track or a retryable 409 — instead of a 500.
Verifying a bitmap request's live layout before every spawn is left out: that
probe costs a provider round trip per page and needs a design decision.

Serving rules for the new page path are in docs/architecture/playback-protocol-v3.md
and docs/architecture/web-pgs-subtitles.md. The web client is unchanged: it
retries with backoff and honours Retry-After.
serveProgressiveSUPPage set Content-Type and Cache-Control after
serveWindow had copied the page, and the first Write commits the status
and headers. Every non-empty page therefore went out with neither, so an
intermediary could cache a per-window subtitle slice. Set both headers
before the copy on every path through it, including the empty window.

The existing page test only read the recorder's live header map, which a
late Set still updates; the new test reads the committed response.
pagePrefixEstimate priced a page's discarded container prefix as
start x byte rate, which can exceed a known source size: a seek past the
end, or a size and bitrate that disagree, priced the page above the whole
container and refused a page the source can serve. Clamp the prefix to
SourceSizeBytes when it is known.
Only probe evidence counted as published inventory, so the item page sat on
"Discovering…" and ended at "Unavailable" whenever the pre-play probe did not
land, even though the selected version's row already carried audio and
subtitle tracks.

Render the selected row's own declared rows immediately and label them as
coming from the release listing. Probe evidence replaces them, and a probed
list never regresses to a declared one. A row with no declaration and no
evidence keeps the bounded discovery-then-retry path. The player overlay
follows the same rule for the playing version, and a plan's inventory is still
published only under the rows it describes, so a substituted release cannot
leak onto the selected version.
… parsed

A page request at a playhead inside the progressive artifact's watermark was
answered with 503 subtitle_source_unavailable. The serve gate required the whole
page range to be parsed (end <= coveredUntil), so a request for 10-130 s against
an artifact that had parsed 0-120 s was refused although every display set that
shows in its first 110 s was complete on disk.

Production showed it plainly: the artifact's watermark reached 126.543 s while
page requests at 10, 20, 40 and 60 s answered 503 with X-Subtitle-Coverage:
0.000-126.543 and no page was ever served; "subtitle page served from the
progressive artifact" never appeared in the log because the copy was never
reached. Each of those requests is snapped onto the source-zero page grid, so
the page under test ends at 240 s even though the requested range ends at 130 s,
and the old gate asked for the whole 0-240 s.

Serve the parsed prefix instead: the cut stops at the watermark, the response is
a 200, and X-Subtitle-Coverage reports the range it really produced. The cut
comes from the display-set index and its first complete display set is checked
before a byte is written (supHasDisplaySet), so a partial run or a cut that
cannot draw is never served. A page that starts at or past the watermark is
still retryable, now as 503 subtitle_page_not_ready with Retry-After and the
covered range, because the source was never read and the page is only waiting
for the artifact that will answer it.
A subtitle response's X-Subtitle-Coverage is the range it really produced, and
a bitmap page answered from a partly parsed track is shorter than the page it
asked for. The window fetcher committed the whole requested range whenever the
body streamed in, so the unparsed tail of such a page was marked as covered and
never requested again: playback would draw the prefix and then nothing until the
next page boundary.

Commit the advertised end when the response carries one, and on the page grid
request the page that contains the committed end rather than the page after it.
A partly produced page is therefore asked for again as the artifact catches up,
and a page that arrived whole is unaffected because its advertised end is the
page end.
Separate release identity from usability in the virtual probe gate. A
served-vs-declared size gap no longer rejects a candidate: the probe's
measured inventory is written metadata-only, planned and played, while
the verdict stays Unverified and never stamps the row or pins the
candidate. Duration or track-layout contradictions still reject as a
different file, and every acceptance path now uses one classification
entry point so the fresh-probe, cache, and persist seams agree.
An explicit version pick reached `/playback/start` as `file_selection:
"auto"` whenever playback began from an item detail page. The action bar
passed the flag, but `buildWatchLocationState` dropped it on the way to
the watch route, and `WatchRoute` rebuilt the request from the URL, which
names a file but not why it was chosen. The player therefore treated
every detail-page start as the server's choice: it sent `auto`, showed
Auto checked in the version menu, and armed cross-version fallback.

Carry the flag through the location state and the route, and include it
in the request key so a route sync cannot fold a pinned start into an
Auto one.

A reload keeps only the remembered row in `silo-requested-version`, so
the store now records whether the viewer named that row. The detail page
and the watch page pin a remembered row only when they can still tell it
is the viewer's; a row an Auto start played stays a hint and stays
substitutable. The player reports the standing of a row it commits, and
its Auto entry reports the row being played as no longer pinned.
…erequisite

#448 (fix/rotation-respects-selection) is open, not merged. This change
extends the same guard to the resolve-timeout fallback, so it must reuse
virtualRotationWouldDropTracks/virtualRequestedRowIsSelection instead of
growing a second policy. Whichever of the two lands first, the other's
call sites keep working.
The item page and both version menus posted to /api/v1/catalog/versions/check, which the upstream sync retired: every request answered 410, so every row stayed at its snapshot availability.

Call checkCatalogVersions at POST /api/v2/catalog/versions/check. The v2 contract renders file ids as opaque strings, so the request sends strings and the response adapter restores the numeric ids the menus key on (dropping a value that names no row). Treat the call as the read it is, so a stalled check still hits the read deadline.
The version-swap notice treated any effective row id different from the requested one as a substitution. A sibling mirror of the same release has its own row, so every virtual play of such a release claimed the chosen version was not playable on the device while the same release played fine.

Decide the notice from release identity rather than the row id: the plan's substituted_from_file_id is the server's substitution signal, and without it two rows are compared by release name, then declared size plus encode fingerprint. Same-release movement stays quiet, a provably different release still speaks, and an unidentifiable pair makes no claim instead of guessing.
Bound the implicit text page to 120 s so a cold ASS extract reads a page of container instead of ten minutes of it. Skip the drift probe when a committed .sup artifact already pins the identity, and warm the track after a failed probe so the retry reads a committed artifact instead of repeating the probe.
A virtual resolve attempt took its bound from a nested WithTimeout on a
deadline an earlier stage had already spent. The derived context expired
before the wait began, the resolver logged a negative bound
(bound_ms=-34/-65/-95/-126 on four consecutive attempts), and every attempt
failed immediately with context deadline exceeded. Callers read that as a
provider listing failure: the failover loop ran on a spent budget, the version
fallback used it to justify a release substitution, and the transport reported
the last attempt as a non-retryable transcode_start_failed.

Derive each attempt's budget from the request's remaining time under an
explicit cap (virtualResolveAttemptBudget), refuse an attempt when nothing is
left, and stop the cold-path candidate loop once its single deadline is spent.
Logs report 0 ms left with an explicit bound_exhausted flag instead of a
negative wait. A transport startup with no budget left answers the retryable
provider_unavailable instead of a fabricated transcode verdict.

The cold-path and stale-pin tests now pin the new truth: a spent budget is
refused, and the recovery listing is identified by its own sub-budget rather
than by a global call ordinal.
The cold-start version fallback walked alternate releases on any provider
listing failure, including a resolve timeout, and served the first that
resolved. Production: a 3-audio/4-subtitle selection played as a
1-audio/0-subtitle sibling.

Apply the rotation guard #448 introduced to the fallback: a substitute that
contradicts the item's runtime (duration_contradiction) or offers fewer audio
or subtitle tracks than the selected row (track_loss) is refused, and when every
substitute would lose the selection the start answers a retryable terminal that
names the version list instead of serving a poorer menu.

A walk whose own budget is spent does not run at all: a timeout is not evidence
that the selected release cannot serve, and every alternate would be resolved
on the same expired deadline.
The plan's substituted_from_file_id and substitution_reason were set in the
domain type, but the v2 projection rebuilt the plan field by field and dropped
both. Across 35 production plan/replan decisions with 14 effective-id changes
the client saw them zero times, so it could only guess which release it got.

Project both fields into the v2 plan and publish them on every replan that
commits a row other than the requested one, not only the explicit version-pick
hunt. The cause comes from a reason the plan already carries, a decode
rotation, or the replan's failure class.

Additive: two optional plan fields, regenerated OpenAPI and web types, and a
short playback API section naming the substitution vocabulary. Tests pin the
serialized body, the omitted-when-unsubstituted case, and a replan rotation.
Conflict in internal/api/handlers/playback_virtual.go: #447 had folded its
size-gap exemption into the duration guard while #448 carried the untouched
guard plus its rotation guard. Kept a single duration guard carrying the
size-gap exemption, then #448's rotation guard and substitution marking.
Conflict in internal/api/handlers/stream.go: #451 added a force admission
and #444 a page-waiting admission to the detached warm. Unified the warm
signature to (pageWaiting, force): the window-miss and probe-failure callers
pass bitmapPageWaitingForFill(opts), the waiting-page caller passes true, the
param-less bypass stays force-only, and the bitmap playing gate now admits
either exception. #444's refactor of the extract-failure block into
writeSubtitleExtractFailure keeps #451's upstream/relay-token handling.
The notice names the release when the row carries one; this #449/#450
assertion still expected the format-label fallback for rows that do.
The session hook built `loadSession` from the `versions`, `playbackVariants`
and `resumeHints` props, so a new versions array changed its identity. That
identity ran through `selectFileId` -> `loadSession` -> `replan` ->
`recoverFromFailure` (the player's `onPlanFailure`) into the transport effect's
dependency list in VideoPlayer.tsx:3780-3795. Every catalog projection of a
title — the version-liveness check's stamped verdicts, an inventory poll's
merged rows, a watch-detail refresh — therefore tore the transport down and
reassigned `video.src`, restarting playback from the plan's start position.

Those three props are file-selection inputs, not transport inputs. Read them
through refs so a projection can change what the menus show without changing
any callback the transport effect depends on. A start still selects from the
list as it stands when the request runs, and the subtitle remap for a version
switch still uses the newest rows.

Regression test: restamping the version list mid-play leaves the media element,
its `src`, and the plan revision untouched, and issues no replan.
A version check resolves the provider per row, and the player was issuing
hundreds of them per session: one per liveness chunk for every
`versions_updated` event, on every remount, and on every invalidated re-render.
Each answer also restamped the version list, which is what tore the transport
down (fixed separately).

Route the check through one gate per row set (the sorted file_ids a single
request names):

- one request in flight per row set; a second caller waits on the first;
- an answer stands for the 5 min freshness window, or ten times the check's own
  latency when that was slower than 1 s, capped at 15 min;
- a catalog `versions_updated` event may force an earlier check, but not more
  often than once per row set per 30 s, and the event burst is coalesced into
  one invalidation (750 ms window, 3 s ceiling) instead of one per row.

A row set that actually changed is a new key and is checked at once, so the
gate never polls and never delays a genuinely new list. A failed check drops
its record so the next caller retries instead of reusing a stale verdict.
A text or ASS window that ran out its 20 s request budget answered 503 and
started the ordinary playhead-grid prefetch. That prefetch extracts the same
page length from an earlier start, so its range ends before the retry's range
and the covering lookup rejects it. The retry then paid the same 20 s read;
production recorded three consecutive kills for one item and session, after
which the track never rendered.

Warm the breached window itself with one extra client grid cell on the end,
detached from the request budget and from the cooldown the breach armed. The
extra cell covers the shifted window both subtitle clients ask for on retry.
A retry whose range falls inside an in-flight warm now joins that flight
instead of starting a second read. The range is bounded by the client window
plus one cell, not by time, so no whole-track progressive fill is needed: the
retry asks for a bounded window and this warm produces exactly that.
A start's effective_media_file_id must name a row the client can show. A
deployed plan answered requested_media_file_id=304999 with
effective_media_file_id=1320729, and 1320729 was not among the item's 452
version rows: progress recorded one row while watch state recorded the other,
so the client could never reconcile what was playing with what was picked.

The detail service now answers the ids of the rows its own version list
carries (the same authorization, fetch and duplicate collapse), and a start
consults that set before planning. A resolver substitution that lands outside
it is refused like any unusable candidate: the candidate that produced it is
excluded and the walk tries the next one. When nothing qualifies the start
answers the retryable version-list terminal instead of planning an unlisted
row, and the refusal never stamps the requested row failed: the release was
not indicted.

Two cases are exempt, both documented at the guard: the requested row itself
(the client's own pick from the list it holds), and a provider-neutral listing
row, which owns no bytes so binding it to the row that owns the served
candidate is ordinary auto selection. An unknown answer (unwired seam, lookup
error, item with no version rows) fails open rather than blocking playback.
A row whose provider served another release's bytes is not a dead release,
but one play attempt left it durable failed:true. The candidate loop joins
each refusal with "no usable stream", and the dead-pin classifier matched that
text, so a single attempt condemned the row. The refusal also never armed the
wrong-source marker, so the versions check could only answer
available:false/failed:true and the user was told "unavailable" instead of
"these bytes are a different release".

The refusal now arms the same process-local served-vs-declared verdict the
version list already renders as source_mismatch, and neither it nor an
unlisted effective row can reach the dead-pin classifier. The start terminal
carries the same vocabulary: the retryable source_mismatch reason, documented
in the playback API contract, with a message naming the version list. The
version list and the player now tell one story about the same bytes.

The dead-end itself is not fatal either way: a refusal that leaves no usable
candidate answers the retryable virtual_source_unavailable terminal naming the
version list, and nothing stamps the requested row failed.

Docs: the catalog and playback API pages record that a playback refusal
publishes source_mismatch, and that an effective row outside the version list
is refused rather than planned.
Two production items showed "Version unavailable" with Play disabled. One
plan had written last_file_id=1320729, a row the item's version list does not
carry, so the page saw a persisted pick it could not select and blocked the
only action. The other had playback_variants[0].default_file_id=416262 marked
failed while 1204391 was not in the list at all.

The page now always resolves a playable row. An explicit pick the viewer made
on this device is kept even when liveness reports it failed, because Play
re-links that row rather than choosing another release behind their back.
Every other preference - the server's last_file_id, or the server's default
row - is skipped when it is failed or unavailable, and the page names the row
it skipped and the row it plays instead. Nothing disables Play while another
row can be tried, and the version list stays one click away.

The shared selection lives in versionRankingUtils so the movie and episode
pages cannot drift. The player also recognizes the new source_mismatch
terminal: it explains the wrong bytes and offers the retry the server marks as
available.
#458 moved two literal strings out of ActionBar.tsx, so the file now raises 46
formatjs/no-literal-string-in-jsx warnings where its suppression recorded 48.
ESLint treats an over-counted suppression as stale and exits non-zero for the
whole tree, which fails `pnpm run lint` on the combined branch while base stays
clean. Pruned with `eslint . --prune-suppressions`.
A replan the viewer did not seek for (a lowering, a re-offer of the same
route) can land on the generation's origin while the transport it replaces
has already played past it. The replacement started at the plan's start, so
a 2160p HEVC transcode session that had played to 120 s reloaded at zero and
asked the live generation for seg_00009 while it was producing past 1268.
Every such request answered 412 and the recovery ended in adaptation_exhausted.

The reloaded transport now begins where the one it replaces had got to on the
new plan's player clock, reusing the existing timeline conversion, and keeps
the plan's own start when that is further ahead or when a different session
is mounting. The transport of a new session never inherits the playhead.
…load

The start of playback rebuilt the HLS transport three times in two seconds
and sent every rebuild back to the plan's origin, so a resumable session
re-requested segment 734 while the server was producing past 776.

Two causes. The watch route rebuilds its pre-play subtitle index maps on
every host render; as `loadSession` dependencies they re-keyed `replan`, and
with it `onPlanFailure`, which the transport effect lists as a dependency.
Every host render therefore tore the media element down and reloaded the
stream. Those inputs are file-selection inputs, so `loadSession` now reads
them through refs like the version list, and `VideoPlayer` reads the failure
callback through a ref so no host callback identity can rebuild a live (or
paused) transport: a plan revision or a new stream URL is the only cause.

The reload's playhead guard also required a played frame, but the flag is
reset by each rebuild, so the second rebuild fell back to the plan's start.
It now carries the element's clock whenever it holds a real position, still
keeping the plan's start when that is further ahead, and a replacement
still inherits nothing from another session.

A failed subtitle window no longer has a transport rebuild to ride: the
track is rebuilt only by a stream/source generation change, and the failure
state itself does not re-enter the fetch (the backoff timer is the only
retry path).
…drift

A text subtitle window can take many seconds to extract on the server. The
fetcher cancelled the request in flight whenever the playhead landed in a
different window, so a cold extraction was thrown away and restarted: one
captured session had 28 of 70 requests end before the response was read, with
one track's window costing 48 ms, 713 ms, 3466 ms and 6791 ms across retries of
the same range, and a track that never loaded at all.

- A window the playhead moves to while one is already streaming is now planned
  again once that window settles, instead of aborting it. Only a deliberate
  seek supersedes an in-flight window, and unmount/track change still aborts.
- Window starts come from one canonical base: `subtitleWindowStartForPlayhead`
  in subtitleWindows, which also owns the cell length and seek backoff. The text
  hook read the playhead with its own copy of the readyState rule; it now uses
  the shared `subtitlePlayheadSeconds`, the same helper the bitmap fetcher uses.
- A build that lands while a stream reload has replaced the <video> element now
  rebuilds once the element appears. Nothing else re-ran that effect, so the
  track fetched nothing and never loaded.
- A fresh window that streams in whole with no cues is a valid empty window: the
  next window is requested immediately instead of waiting for the prefetch lead.
  Only a fresh window chains, so a silent track cannot turn into a fetch loop.

Retry budgets, the stall timeout and the server's window length are unchanged.
A request-path text window killed at its budget answered a bare
subtitle_source_unavailable: the source was fine and the window was the
problem, so a client and an operator could not tell the refusal apart from
a provider failure. Name it subtitle_window_budget_exceeded, the same
additive shape the bitmap page refusals use.

A bounded bitmap page retried inside the extraction cooldown a refusal
armed lost its page reason and answered the generic problem too. The
handler starts the recovery fill only for a page refusal, so that retry
had no fill behind it and could only repeat the read that earned the
refusal. Keep the page reason and the cooldown's remaining delay, and
advertise 0.000-0.000 for a page refusal whose artifact has parsed
nothing rather than omitting the coverage header.

Retry-After, the 20 s budget and every timeout are unchanged.
…iling the track

Every subtitle fetcher moved the player to its error state as soon as one
window failed, including a 503 the server was already recovering from.
The viewer saw "Subtitles couldn't load. Retry" while the track was still
selected and playback was still running, and the recovery the server had
started was never collected.

Treat a retryable answer as what it is: honor its Retry-After (raised, never
shortened, inside the existing cap), keep the cues already on screen, and
let the bounded retry budget own the retry. Only a non-retryable failure (a
404 for a track this file does not have, an unsupported format) or a spent
retry budget reports the error, so the final failure stays honest.

The bitmap fetcher now tells its caller whether a failed window is
retryable, so a 503 is retried while a 404 ends the overlay.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants