From f4eb3662c1e6323363b9db92c816200a1a931e2c Mon Sep 17 00:00:00 2001 From: 4gray Date: Sun, 23 Aug 2026 12:05:31 +0200 Subject: [PATCH] docs(playback): consolidate capability list and describe the final encoding heuristic Codex review round 4 on #1471: the merge left two overlapping capability inventories in the player-controls contract (the new one omitting qualityLevels), and the encoding-detection description still named the replaced high-byte-density heuristic. One authoritative list now covers both features, and the doc describes the mixed-script word-plausibility algorithm actually implemented. Co-Authored-By: Claude Fable 5 --- docs/architecture/player-controls-contract.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/architecture/player-controls-contract.md b/docs/architecture/player-controls-contract.md index b0c12fbff..a18ecfbbd 100644 --- a/docs/architecture/player-controls-contract.md +++ b/docs/architecture/player-controls-contract.md @@ -173,9 +173,7 @@ interface PlayerController { `PlayerControlsCapabilities` contains booleans for `seek`, `volume`, `audioTracks`, `subtitles`, `externalSubtitles`, `subtitleDelay`, -`subtitleStyle`, `playbackSpeed`, `aspectRatio`, `recording`, -`pictureInPicture`, `fullscreen`, and `seriesNavigation`. -`audioTracks`, `subtitles`, `qualityLevels`, `playbackSpeed`, `aspectRatio`, +`subtitleStyle`, `qualityLevels`, `playbackSpeed`, `aspectRatio`, `recording`, `pictureInPicture`, `fullscreen`, and `seriesNavigation`. The default is all-false. An adapter enables only features that its engine and @@ -694,8 +692,12 @@ Per-engine implementations: picker is a renderer-side DOM file input (`.srt`/`.vtt` only; works in the PWA and Electron alike, and no filesystem path ever enters the app). File bytes are decoded encoding-aware (`decodeExternalSubtitleBytes`: UTF-16 - BOMs, strict UTF-8, then a Windows-1251/1252 heuristic keyed on high-byte - density), because `Blob.text()`'s silent UTF-8 substitution turns common + BOMs, strict UTF-8, then `chooseLegacySingleByteDecode`, which picks + between Windows-1251 and Windows-1252 by the plausibility of the 1251 + candidate's decoded words — pure-Cyrillic words vote for 1251, words + mixing Cyrillic with ASCII letters vote against, since misread Latin text + like "était" decodes to the mixed-script "йtait" that real subtitles never + contain), because `Blob.text()`'s silent UTF-8 substitution turns common legacy-encoded SRT files into mojibake. `WebVideoExternalSubtitles` parses the file (`external-subtitle-cues.util.ts`) and renders it through a native `TextTrack` on the video element, so it works under every source kind. The