Repository navigation
Conversation
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.
Collaborator
Author
|
Superseded by #459, which contains this change plus the rest of the playback reliability bundle. Closing to keep the review surface to one PR. |
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
Related issue: N/A
Validation tasks: none
Two items on the combined build could not be played, and one of the two failures also hid the reason.
A start answered
requested_media_file_id=304999witheffective_media_file_id=1320729. The item had 452 version rows and 1320729 was not one of them, so progress recorded 304999 while watch state recorded 1320729 and the client had no way to reconcile what was playing with what was picked.The item page then dead-ended: it kept the stored
last_file_idas the selected row, found no matching row in the version list, and showed "Version unavailable / The selected version is no longer available" with Play disabled. A second item showed the same screen withplayback_variants[0].default_file_id=416262markedfailed:true, available:falseanduser_data.last_file_id=1204391absent from the list, so the page had no row it was willing to start.POST /catalog/versions/checkfor a row whose bytes belong to a different release answered onlyavailable:false, failed:true. The user was told the version was unavailable rather than that the provider served a different release. One play attempt was enough to stamp that row failed: the candidate loop joins each refusal with "no usable stream", and the dead-pin classifier matched that text as a confirmed-dead pin.This PR is stacked on
integration/playback-combinedand targets that branch rather thanmain.Approach
A start's effective row now has to be one of the item's selectable version rows. The detail service exposes the ids from its own version-list projection (same authorization, fetch and duplicate collapse the page gets), and a start checks the resolved row against that set before planning. A row outside the set is refused like any other unusable candidate: the candidate that produced it is excluded and the walk tries the next one, and when nothing qualifies the start answers the retryable version-list terminal instead of planning a row the client cannot reconcile.
Two cases are exempt, for reasons written at the guard. The requested row itself is the client's own pick from the list it holds. A provider-neutral listing row owns no bytes, so binding it to the row that owns the served candidate is ordinary auto selection, not a substituted version; that is the one shape where the effective row is legitimately absent from the list. An unknown answer (unwired seam, lookup error, item with no version rows) fails open, so a catalog hiccup cannot refuse playable content.
The refusal that reports served bytes contradicting the row now arms the same served-vs-declared verdict the version list already renders as
source_mismatch, and the start terminal carries that reason with the version-list hint. The value is additive:reasonis a free-form string in the v2 contract, the version-check field already exists, and no artifact changed.Neither refusal can indict the requested row. Both are excluded from the dead-pin classifier, which is the path that turned one attempt on a source-mismatch row into a durable
failed:true.The item page always resolves a playable row. An explicit pick made on this device is kept even when liveness reports it failed, because Play re-links that row rather than choosing another release behind the viewer's 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. The shared selection lives next to the existing version-ranking helpers so the movie and episode pages cannot drift, and the player recognizessource_mismatchwith the retry the server marks as available.Validation
go build ./..., with the embed stubmake buildcreates.go veton./internal/api/handlers,./internal/catalog,./internal/apiv2,./internal/playback: clean.go test -count=1 ./internal/apiv2 ./internal/catalog: pass.go test -count=1 ./internal/api/handlers: pass exceptTestHandleStartPlaybackV3ReturnsBoundedOnSlowProbeandTestHandleStartPlaybackV3DoesNotWaitForSessionSync. Both are wall-clock assertions (40 ms and 1 s) that fail identically on the base commit in this arm64 test container; verified by stashing the branch's Go changes and re-running them.go test -count=1 ./internal/playback: three tests fail in this container while generating or measuring ffmpeg fixtures (TestResolveCopySeekAnchorMatchesRealLongGOPHEVCreportssignal: killedfrom fixture generation, plusTestOnDemandSubtitleSegmentsDoNotWaitForTheStreamandTestServeExtractDiscardsACappedDemuxCopy). This branch does not change that package.go test -raceon the new handlers tests: pass.make verify-playback-fixturesandmake verify-apiv2-openapi: current. The wire shape did not change.scripts/check-fork-invariants.sh: fork invariants hold.scripts/lint-changed.shwithBASE_REF=integration/playback-combined, run inside the repository's build container: 0 issues.Risks
Behavior change: a start that used to plan an unlisted effective row now refuses that candidate and either plays another listed row or answers a retryable terminal naming the version list. Clients that relied on the effective id to point at a duplicate row the list collapses will instead see the requested row or a clear refusal.
The version-list lookup runs only when the resolved row differs from the requested one, and it fails open. A catalog read failure cannot block playback.
Existing rows already stamped
failedkeep that verdict until a liveness check clears it; this change stops new ones from being created by a source mismatch or an unlisted effective row.Checklist
AI Disclosure
Posted by an AI agent (Muse Spark, OpenCode harness).