[blurbery]

Stacked on #183 (fix/subtitles-follow-settings-everywhere). Retarget to main once #183 merges.

Problem and reproduction

On Emby and Jellyfin, image-based subtitles (PGS, VobSub, DVB) vanished whenever the server transcoded. That's often the forced track, so signs and foreign dialogue went missing on anime and foreign films at lower qualities.

1. Play a title with a PGS track from Emby or Jellyfin.
2. Pick a quality that makes the server transcode (for example 720p), or play somewhere the server already transcodes.
3. The PGS track isn't in the subtitle list, and Auto can't pick it, even though the detail page names it.

Root cause: Vivid always sent SubtitleStreamIndex: -1 in PlaybackInfo and drew subtitles itself. On direct play the engine draws embedded PGS natively, but an HLS transcode only carries the text tracks Vivid mounts beside it, so bitmap tracks had no way to reach the screen.

Implementation and impact

• On an Emby or Jellyfin transcode, the file's bitmap tracks (embedded or beside the media) are listed in the subtitle picker after the tracks Vivid plays itself, in the sidecar ID space keyed by the server stream index. They look like any other row. Text comes first, so Auto still prefers a text track to a bitmap one of the same kind.
• Choosing one, by hand or by Auto, reloads at the current position like a quality change, with the stream index as the load's subtitle pick. Choosing anything else (Off, a text track, an OpenSubtitles file) reloads without it. No reload when the chosen track is already burned in. Cycling and toggling subtitles skip these rows.
• ServerSubtitleBurnIn.negotiate: the bridge sends PlaybackInfo as before. Only when that answer is a transcode, and the load's pick is one of the file's bitmap tracks, it asks once more with SubtitleStreamIndex set. It plays that second answer only when the TranscodingUrl names the same stream with SubtitleMethod=Encode (or the subtitle's DeliveryMethod is Encode when the URL has no method). Otherwise it plays the first answer without subtitles. Asking only after a transcode means direct play never changes: the engine already draws these tracks, and asking for a DVB or external bitmap subtitle there would make the server transcode just for it. It also lets a detail-page pick or a quality change burn the track in on the first load, with no extra reload.
• The pick rides on the existing preferredSubtitleTrackIndex, so seek reloads, retries, renewals and quality changes carry it. It's passed to the bridge separately and only the Emby and Jellyfin branches use it, so Silo plans and their subtitle intent are unchanged. Going to Original just direct plays and the engine shows the track natively.
• Failure handling: when the server answers without confirming the burn-in, or the burned-in stream won't open for a reason that points at the transcode (a server error, a rejected playlist, a pipeline failure), playback carries on without subtitles with a notice (the open failure reloads once without it instead of ending playback), and that row is dropped until another title plays. A burn-in request that fails (a dropped connection, a timeout or an HTTP error) only misses that time: a notice says so, but the row stays so it can be chosen again. Open failures from the connection (any URL loading error), sign-in, timeouts, rate limiting or the audio session take the usual failure path and leave the track alone.
• Auto leaves burn-in rows alone while the transcode only repackages the video (an H.264 source whose TranscodeReasons are all audio or container reasons, and Vivid allowing a video copy), so an automatic pick doesn't add a full video encode on the server. They can still be picked by hand. The SubtitleMethod and comma-separated TranscodeReasons formats were read from my Emby 4.10 server's own logs.
• A burned-in track takes no subtitle style, so the style controls hide for it as they already do for bitmap tracks the engine draws. Subtitle delay has no effect on it. No other UI changes.
• New code is mostly in ServerSubtitleBurnIn.swift and PlayerViewModel+ServerBurnIn.swift, with small hooks in the playback files, inventory adoption and track selection.

Deliberately unchanged: direct play, Silo, offline playback, the device profile (no new subtitle profiles, so legacyBody is untouched), and the detail page's runtime inventory (burn-in rows are kept out of it).

Known limits:

• An automatic burn-in pick on a fresh load starts the transcode once without it and then reloads with it, since the pick is made after the file opens.
• A burned-in stream that fails mid-playback, rather than at open, goes through the usual recovery and may ask for the burn-in again.
• Lucid reports a stream that won't open without saying why, so a connection drop right as a burned-in stream opens still counts against that track until another title plays.
• External bitmap files beside the media still aren't offered on direct play (unchanged).
• Merged with fix: make audio follow Settings on every server, on detail pages and in the player [skip release] #185 by a merge commit, no force push. A confirmed burn-in counts as the item's pick, so Auto doesn't run again on that load, including when fix: make audio follow Settings on every server, on detail pages and in the player [skip release] #185's keepsAutomaticSubtitles carries Auto's pick through a quality change or renewal.
• The open-failure reload and the deferred reload after a pick have no unit tests; the decisions they rely on (which failures count, whether a reload is needed) do.

Release: this PR merges last and releases the batch. Squash commit body for merging:

Release-Notes:
- Subtitles now follow your Subtitles settings on Silo, Emby and Jellyfin alike. A subtitle setting saved on the server could turn subtitles off on movie and series pages and in the player, whatever you had chosen.
- Movie and series pages now show exactly which subtitles will play, such as "Auto: English (Forced)", and the Subtitles box shows for every file, even one without subtitles.
- Added Backup Language in Settings > Subtitles, used when full subtitles would play but a title has none in your main language.
- Switching audio now re-checks Auto, and on Silo an audio or quality change keeps the subtitle you had.
- Show Forced Subtitles is honoured everywhere: with it off a forced track never plays, a track named Forced counts as forced, and a forced pick stays forced into the next episode.
- Always with no subtitle language set now shows subtitles instead of nothing.
- Use Device Settings now follows Apple's rules for Automatic and Forced Only, uses the caption font chosen in Accessibility, and picks up changes when you come back to Vivid.
- Fixed the Shadow subtitle style sometimes being invisible on embedded subtitles, and subtitle delay being lost after a reload.
- Movie, series and season pages now show the audio track that will actually play, chosen from your Audio Language, instead of a track the server remembered, so the page and the player agree on Silo, Emby and Jellyfin.
- Audio picks are no longer saved to the server: your Audio Language decides the audio for every title, and a track you pick lasts for that viewing.
- An audio track you switch to now carries on to the next episodes, instead of going back to your Audio Language while your subtitle choice carried on.
- Fixed audio jumping back to the file's first track after a quality change or reconnect while transcoding, which could turn Japanese audio into English mid-episode.
- Retry after a playback error now keeps the audio track you switched to.
- After a quality change on Emby or Jellyfin, switching audio re-checks Auto subtitles again.
- Downloaded movies and episodes now start with the audio your Audio Language picks, the same as streaming.
- Emby and Jellyfin now see which audio and subtitle tracks are playing, instead of always the starting audio and no subtitles.
- On iPhone and iPad, the Audio menu's Auto option now says it uses your Playback audio preference, as on Apple TV.
- Continue Watching on Apple TV shows the audio format of the track that will play.
- Embedded subtitles now match external subtitle files with the same Settings > Subtitles style: the same size, position, box and outline, and a closer font and weight. Before, embedded text was smaller, thinner and lower on screen.
- External subtitle files keep their italics, bold, underline, strike-through and colours, and a line the file moves to the top now shows there instead of showing the tag as text.
- Overlapping external subtitle lines now stack instead of drawing over each other.
- With Zoom on, external subtitles stay the same size and on screen instead of growing off the bottom on iPhone.
- External subtitles on anamorphic video now sit in the right place, and custom subtitle fonts no longer grow with larger text settings.
- External subtitle files now show in Picture in Picture on iPhone and iPad.
- Subtitles stored on your Silo server (downloaded, uploaded or made by Silo's AI) now show in the player's subtitle menu and the detail page's Subtitles menu on iPhone, iPad and Apple TV. Before, only the file's own tracks and the subtitle files beside it were listed.
- Auto and the rest of Settings > Subtitles now count those stored subtitles too, so a title whose only subtitle in your language is stored on Silo plays it, and the detail page's Auto preview names it.
- A subtitle Silo finishes making while you're watching now joins the player's subtitle menu straight away.
- On Emby and Jellyfin, image-based subtitles (PGS, VobSub and DVB) now show when the server transcodes: the server draws the one you choose, or the one Auto picks, into the picture. Before, they disappeared whenever the server transcoded, which often hid forced subtitles for signs and foreign dialogue.
- If the server can't draw a subtitle in, playback now carries on without subtitles and tells you, instead of failing.
- This release will be available on TestFlight soon.

The bullets above come from all five PRs, in merge order: #183, #185, #188 (subtitle drawing), #187 (Silo stored subtitles) and this one. I'll check them against each description again right before merging.

Validation

Local, Xcode 27.0, revision 83a818b (code; 1d02d7b only changes docs wording):

• iOS, iPad Air 11-inch (M4) simulator (iOS 27.0), ad-hoc simulator signing, 60 s per-test limit, no parallel testing: ServerSubtitleBurnInTests (new, 15), JellyfinAdapterTests (49), EmbyAdapterTests (59), SubtitleAutoSelectionTests (15), SubtitleAutoResolverTests (38), ServerDeviceProfileTests (3), DetailSubtitlePreviewTests (12), PlaybackProtocolV3Tests (55), PlaybackEndRecoveryTests (18): 264 tests, 0 failures.
• ServerDeviceProfileTests still matches legacyBody, so the PlaybackInfo body Vivid sends is unchanged apart from the follow-up burn-in request.
• After merging feat: make subtitles follow Settings on every server and add a backup subtitle language [skip release] #183's latest commit (f3cd6d4, the resolver change), revision 164e9ef: ServerSubtitleBurnInTests, SubtitleAutoResolverTests, SubtitleAutoSelectionTests, JellyfinAdapterTests, EmbyAdapterTests: 176 tests, 0 failures.
• After the Claude review fixes, revision 1061f7a: ServerSubtitleBurnInTests (now 18), JellyfinAdapterTests, EmbyAdapterTests, SubtitleAutoSelectionTests: 141 tests, 0 failures.
• Revision 5444311 (confirmed burn-in holds for the item, README paragraph break): ServerSubtitleBurnInTests (19), SubtitleAutoSelectionTests, PlayerAudioContinuityTests: 41 tests, 0 failures.
• After merging main with fix: make audio follow Settings on every server, on detail pages and in the player [skip release] #185, fix: show subtitles stored on Silo in the player, detail menus and Auto [skip release] #187 and fix: draw embedded subtitles like external ones and fix overlay layout bugs [skip release] #188 in, revision d9412c8: ServerSubtitleBurnInTests, SiloStoredSubtitleTests, PlayerAudioContinuityTests, SubtitleAutoSelectionTests, JellyfinAdapterTests, EmbyAdapterTests, PlaybackProtocolV3Tests, DetailSubtitlePreviewTests: 223 tests, 0 failures. scripts/tests/jellyfin-replacement-tests.py: 54 checks pass.
• python3 scripts/ci/check-docs.py --base origin/main: passes.
• Not run locally: tvOS (CI's Apple TV suite now includes ServerSubtitleBurnInTests), devices, and live playback on either server.

New tests:

• ServerSubtitleBurnInTests: no burn-in request on direct play; the follow-up request on a transcode and playing the confirmed answer; falling back to the first answer when the server answers with another method, another stream, an error or a failed request; SubtitleMethod/DeliveryMethod confirmation (case-insensitive); the video-copy rule; which picks count as bitmap; burn-in rows (sidecar ID, no FFmpeg index, failed rows dropped); the reload decision, including no reload when already burned; a text track beating a bitmap row of the same kind; the burned row staying selected and carrying its stream index through reloads; Auto skipping rows while the video is only copied; an unconfirmed burn-in turning subtitles off with a notice; the pick carrying through seek reloads, retries, renewals and quality changes, and never for Silo or offline.
• JellyfinAdapterTests: a transcode with a PGS pick sends PlaybackInfo twice (-1, then 3), plays the burned session, reports stream 3 and mounts only the text track beside it.
• EmbyAdapterTests: an unconfirmed burn-in plays the first transcode without subtitles.

Performance

No benchmark run. A burn-in makes the server encode video (it usually already is on a transcode), and the burn-in request adds one PlaybackInfo call only when a bitmap pick meets a transcode.

Testing status

• Tested? Partly.
• Environment: iPad Air 11-inch (M4) simulator, iOS 27.0.
• Revision: 83a818b, 164e9ef after merging feat: make subtitles follow Settings on every server and add a backup subtitle language [skip release] #183, and 1061f7a after the review fixes.
• Checks and results: The focused suites above pass (264 tests, 0 failures). The Emby transcode URL fields the confirmation reads were checked against my Emby 4.10 server's logs.
• Limitations: Burned-in playback hasn't been checked live on Emby or Jellyfin, on a simulator or a device, and nothing ran on tvOS locally. Jellyfin's URL fields come from its source, not a live server.

Design impact and approval

• Design impact: No design changes. Burn-in rows use the existing picker rows, the style controls hide the same way they already do for bitmap tracks, and the only new copy is the failure notice.
• Approval from blurbery: Not applicable, no design changes. Server burn-in for bitmap subtitles on Emby and Jellyfin transcodes was approved as the fix for this gap, in its own PR stacked on feat: make subtitles follow Settings on every server and add a backup subtitle language [skip release] #183.

Documentation impact

• docs/cores/emby.md and docs/cores/jellyfin.md: transcodes now offer bitmap tracks for the server to burn in, how it's confirmed, the fallback and what's been checked.

• docs/playback/README.md: the subtitle menus paragraph.

• docs/playback/architecture.md: how burn-in rows, the PlaybackInfo retry, the fallback and the Auto rule work.

• docs/cores/player-engine.md: the subtitle inventory sentence.

• I checked the docs this change affects and updated them in this PR, or explained above why none needed changes.

AI disclosure

I implemented these changes and used Claude Opus as a tool.

[github-actions]

Claude review of the whole PR at 164e9ef. The summary comment lists everything found.

[github-actions]

Claude review of the new commits 0712b72..5444311

I reviewed the new commits since 0712b72. They add the rule that a confirmed burn-in holds for the item (adoptServerTranscodeSubtitles), the matching test and the README paragraph break. I also read the merged #185, #187 and #188 changes where they touch burn-in: Emby and Jellyfin progress reports, keepsAutomaticSubtitles and the audio continuity changes. I skimmed the large docs diffs and the project.yml and Python test-stub edits but did not check every sentence in them.

P3, PlayerViewModel+ServerBurnIn.swift: when Auto picks a burn-in row and the server confirms it, an audio switch no longer re-runs Auto. The README and the release notes still say it does.

I found nothing else. I couldn't check this against live Emby or Jellyfin servers, or on tvOS.

I checked the new commits (the hold on a confirmed burn-in, the README paragraph break and the merge of #185, #187 and #188) against the PR description and the changed docs. One P3 doc gap needs fixing.

P3

• docs/cores/emby.md: the description says the file now covers burn-in on transcodes, how it's confirmed, the fallback and what's been checked. It doesn't mention burn-in anywhere, though docs/cores/jellyfin.md has the full paragraph.

Everything else I checked matches the code:

• The confirmed-burn-in hold matches adoptServerTranscodeSubtitles and its new test, and the keepsAutomaticSubtitles ordering is correct.
• The Emby and Jellyfin progress-report text matches MediaServerPlayingTracks.streamIndexes.
• The audio-rule claims, including downloads, and the Silo stored-subtitle claims match the code.
• The doc anchors I checked resolve, and the new test files exist.

I did not re-report the existing finding that a confirmed burn-in stops audio switches re-running Auto.

Not on a changed line:

• P3 docs/cores/emby.md:73: Emby core guide never mentions the burn-in behaviour The description says docs/cores/emby.md now covers bitmap tracks on transcodes, how burn-in is confirmed, the fallback and what's been checked. A search of the file for burn-in, bitmap and PGS finds nothing. The only Emby doc change is the audio and progress-report text on this line. docs/cores/jellyfin.md has the full paragraph, and docs/playback/architecture.md describes the shared behaviour. Add the equivalent Emby text: the SubtitleMethod=Encode confirmation read from the 4.10 logs, the fallback without subtitles, the row dropped for the title, a failed request counting only that attempt, and that it hasn't been checked live.

_{claude-sonnet-5-5, high effort, 29 turns, about US$0.95 of API credit}

[github-actions]

Claude review of the new commits 164e9ef..1061f7a. The summary comment lists everything found.

[github-actions]

Claude review of the new commits 1061f7a..85de52f. The summary comment lists everything found.

[blurbery]

On the review of 85de52f: the fallback does still fire for a failed burn-in. Engine load failures reach loadFailureBlamesServerBurnIn as LoadFailures, and Lucid reports a stream that won't open as .softwarePipelineFailed or .noPlayableTrackWithinBudget with no error domain (VividMPVPlayer). The only place an HTTP status is put under NSURLErrorDomain is VividAuthenticationRecoveryPolicy.finalFailure on the renewal path, and PlaybackInfo HTTP errors arrive as HTTPError, so neither reaches the check. The real limit is the other way round: Lucid doesn't say why a stream won't open, so a connection drop right as a burned-in stream opens still counts against the track. I've added that to the architecture doc and the PR's known limits rather than guess at it in code.

[github-actions]

Claude review of the new commits 0712b72..d9412c8. The summary comment lists everything found.

[blurbery]

On the review of d9412c8 (Auto running again after a quality change carries its pick into a burned-in load): fixed in 5444311. adoptServerTranscodeSubtitles now treats a confirmed burn-in as the item's pick (hasExplicitSubtitleChoice, no automatic prefs), so Auto doesn't run again on that load and can't hide the row and reload on a video-copying transcode. testAConfirmedBurnInHoldsForTheItemEvenWhenAutoChoseIt covers it, and the architecture doc says so.

[github-actions]

Claude review of the new commits 0712b72..5444311. The summary comment lists everything found.