Repository navigation
Conversation
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.
… pgs sidecar branch No conflicts.
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/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 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`.
This was referenced Nov 15, 2026
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
500 internal_error; a client cancel surfaced as502.What this change does
Selection and identity
expliciton the wire, is honoured by the planner, and is never silently replaced by a different release.source_mismatchinstead of a generic "unavailable".Subtitles
503withRetry-AfterandX-Subtitle-Coverage..supartifact is not invalidated by a seek, and a subtitle track change keeps the playback position.Player and client
/api/v1route was returning 410 for every call.Diagnostics
503withRetry-Afterinstead of500; client cancels answer408.Verification
go build,go vet, scanner/apiv2/catalog suites, focused playback and handler suites,-raceon the new tests, playback fixtures, v2 OpenAPI and web types, fork invariants,tsc, and the focused web suites.main(TestOnDemandSubtitleSegmentsDoNotWaitForTheStream,TestServeExtractDiscardsACappedDemuxCopy) plus a load-sensitive timing test that passes in isolation.Known open, tracked separately
recv(2), which/proc/PID/iodoes not count.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.