feat(playback): let Rust decide what stream to play, and say so

Playing a video meant asking the server to re-encode it, always. That decision was made nowhere and written down nowhere, so whoever needed it re-derived it downstream — the player worked out whether it had been handed a playlist by looking for ".m3u8" in the URL, in two places. A viewer paid for a transcode of a file their device could have played untouched, and the app could not tell them which it was. One negotiation now produces one self-describing StreamSelection — direct play, remux or transcode; over a playlist, a plain HTTP file, or a local one — and every renderer consumes that same answer. Measured against the development server (Jellyfin 10.11.5), 400 items sampled for codec mix and 40 put through a real PlaybackInfo negotiation per profile: Linux / WebKitGTK (h264 only, 2ch) 3/40 — 7% direct play Android / ExoPlayer (hevc, ac3/eac3, 6ch) 34/40 — 85% direct play The library is ~80% hevc, which is why the two diverge so hard. The payoff is overwhelmingly Android, where 85% of plays were starting a transcode nobody needed. Linux stays near 7% until libmpv decodes the picture — the h264-only profile is a WebKitGTK constraint, not a JellyTau choice. DR-219 StreamSelection: url + tagged Transport (hls/progressive/localFile) + PlaybackKind (directPlay/directStream/transcode) + the negotiated rendition + this source's ladder + a needs_transcoding flag derived in Rust so the rule is answered once. Both enums are serde-tagged so the frontend matches a discriminant, not a substring. The paths that never negotiate get the same shape from Rust rather than assembling one — media_local_selection for a downloaded file, LiveStreamInfo.transport for a live channel — so there is no second place where a transport is decided. DR-220 The ceiling becomes two levels: a durable device default (Settings, persisted) and a per-playback override the in-player picker sets. The picker had called itself a "this film, this connection" control since it was written but wrote the process-wide default, so dropping one awkward film to 2 Mbps silently capped every video played afterwards for the rest of the process, with Settings still showing the old value. The override is cleared whenever playback moves to a new item, which stops it surviving into an autoplayed next episode. effective_streaming_quality() is the single resolution point. DR-221 The quality picker is filled from what this media source can offer. Rust marks a rung exceeds_source when its ceiling is at or above the source's own bitrate — such a rung is another way to spell Original — and the frontend does not draw those. Original is never marked; a source whose bitrate the server does not report marks nothing, which keeps every rung offered. DR-222 Direct play and direct stream are negotiated, with two client-side overrides on top because the server's answer is right about the file and wrong about what this app will do with it: undecodable audio (Jellyfin 10.11.5 honours a DirectPlayProfile's container and video codec but ignores its audio codec, so it offers direct play for an E-AC-3 track the webview renders in silence) and a viewer-pinned audio track the file does not default to. A direct stream is a remux and is deliberately not counted as transcoding. DR-223 Dropped on measurement, not deferred. A master playlist from this server carries exactly one EXT-X-STREAM-INF: Jellyfin builds it from the single rendition the request asked for rather than publishing a ladder. So there is no adaptation for hls.js to be preserving and none mpv would lose — the claim that there was, in playback-backend-unification.md, does not hold. Recorded rather than deleted because it is a measurement: a server that does publish a ladder would change the answer. DR-224 Every backend consumes the same selection. The queue item carries the transport, so player_seek_video picks its seek strategy from the backend's decision instead of the last stream_url.contains(".m3u8") in the codebase. Items queued by a path that never negotiated carry None and fall back to needs_transcoding, which is exact rather than a guess because every transcode this app requests is HLS (DR-140). The frontend loader decision moves to streamTransport.ts so it can be tested: the two cases that pin it are the ones that failed against the old implementation — a progressive stream whose URL contains ".m3u8" must not get an HLS loader, and an HLS stream whose URL contains none must. Also verified the URL the direct-play branch builds actually serves playable bytes: 206, video/mp4, valid ISO-BMFF, and a mid-file range works, so seeking a direct play works. The spec is folded into docs/architecture/{01,02,03} and deleted, per the rule that docs/specs holds only work that has not shipped. DR-121 leaves read-through-media-cache.md with a pointer; that spec keeps its capture half. Not verified: real playback on a device. Direct play changes what actually gets played, and neither fixtures nor curl prove the WebKitGTK and ExoPlayer paths render it.
2026-08-22 13:45:03 +02:00
parent 5fede123e7
commit 109700b949
45 changed files with 9744 additions and 6581 deletions
@@ -0,0 +1,68 @@
+/**
+ * Which loader opens a stream in the webview `<video>` element.
+ *
+ * Extracted from `VideoPlayer.svelte` so the decision can be unit-tested — the
+ * same pattern as `episodeStrip.ts` and `TrackList.logic.test.ts`.
+ *
+ * TRACES: UR-079 | DR-224 | UT-213
+ */
+
+import type { StreamSelection, Transport } from "$lib/api/bindings";
+
+/** How the element should be fed. */
+export type VideoLoader =
+  /** hls.js drives a MediaSource; the element's own `src` stays empty. */
+  | "hlsjs"
+  /** The element loads the playlist itself (Safari/WebKit native HLS). */
+  | "nativeHls"
+  /** The element loads the URL directly — a progressive file or a local one. */
+  | "direct";
+
+/** What the running browser can do, passed in so the decision stays pure. */
+export interface LoaderCapabilities {
+  /** `Hls.isSupported()` */
+  hlsJsSupported: boolean;
+  /** `video.canPlayType("application/vnd.apple.mpegurl")` was non-empty */
+  nativeHlsSupported: boolean;
+}
+
+/**
+ * Pick the loader from the backend's tagged `transport`.
+ *
+ * This used to read `url.includes(".m3u8")`, in two places in
+ * `VideoPlayer.svelte`. Rust *builds* that URL and knows exactly what it is;
+ * re-deriving the answer here by substring match is a domain fact reconstructed
+ * in the presentation layer — the same error as leaking item-type taxonomy, and
+ * one that fails silently in both directions: a progressive file served from a
+ * path containing `.m3u8` gets an HLS loader, and a playlist served from a path
+ * without it does not.
+ *
+ * The transport is the *stream's* property; whether a given loader exists is the
+ * *browser's*. Only the second is decided here.
+ */
+export function videoLoaderFor(
+  selection: Pick<StreamSelection, "url" | "transport">,
+  capabilities: LoaderCapabilities,
+): VideoLoader {
+  if (selection.transport.type !== "hls") {
+    // Progressive and local files are what the element loads natively. No
+    // MediaSource, no playlist parsing.
+    return "direct";
+  }
+  if (capabilities.hlsJsSupported) return "hlsjs";
+  if (capabilities.nativeHlsSupported) return "nativeHls";
+  // Nothing here can parse a playlist. Handing the URL to the element is very
+  // likely to fail, but it is the only remaining move and it surfaces a real
+  // media error rather than silently doing nothing.
+  return "direct";
+}
+
+/** Convenience for the template: does the element's `src` stay empty? */
+export function elementSrcFor(
+  selection: Pick<StreamSelection, "url" | "transport">,
+  capabilities: LoaderCapabilities,
+): string {
+  return videoLoaderFor(selection, capabilities) === "hlsjs" ? "" : selection.url;
+}
+
+export type { Transport };