vendor hls.js and play transcodes over hls

a live transcode has no length and no byte ranges, so the progressive mp4 the player used could not be seeked — a scrub restarted ffmpeg at a new offset. jellyfin's own HLS playlist is VOD and spans the whole runtime, so seeking it is a segment request. hls.js is checked in rather than installed. installs are frozen so that adding a package is a reviewed act, and a committed file also has no install-time hook, which is the vector the 2026-08-04 npm worm used. provenance, hashes and the update recipe are in vendor/README.md; the tarball sha512 matches the registry's published integrity. the sidecar now overrides VideoBitrate and MaxWidth on the TranscodingUrl jellyfin hands back, for the same reason progressivePath computes them: jellyfin resolves that bitrate from MaxStreamingBitrate (~119 Mbit, the ceiling that exists to let a stream copy through) and sets no width, which asks a CPU-only container to encode 4K. safari is deliberately not given the m3u8 — segment URIs are relative and would not carry the ?token=, and it cannot set an Authorization header the way hls.js can. progressive stays as the fallback for any browser without MSE. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-04 18:52:15 +00:00
parent 9990c04008
commit 7732ca1da5
7 changed files with 36973 additions and 30 deletions
@@ -1,5 +1,5 @@
 import type { PlaybackPlan } from './shared';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Link, useLocation, useSearchParams } from 'react-router';
 import { Loader2, Maximize2, Pause, Play, X } from 'lucide-react';
 import { useClient } from 'hooks/useClient';
@@ -13,23 +13,40 @@ import {
  ticksToSeconds,
 } from './shared';
 import { useJellyfinItem, usePlaybackPlan, usePlaystateReporter } from './useJellyfinData';
+import Hls from './vendor/hls.mjs';

 // The player — a full-panel overlay opened by `?play=<id>`.
 //
-// THE ONE THING THAT MAKES THIS DIFFERENT FROM A NORMAL <video>: a transcoded stream has no length and no byte
-// ranges, so the browser cannot seek it. `plan.seekable` says which world we are in, and the two are handled
-// differently rather than pretended to be the same:
+// THE ONE THING THAT MAKES THIS DIFFERENT FROM A NORMAL <video>: what the server hands back is not always a
+// file. There are three transports, and `mode` names which one is in use rather than letting the difference
+// leak out as mysterious behaviour:
 //
-//   direct play / direct stream → a real file. Native controls, native seeking, `currentTime` is the position.
-//   transcode                   → a live progressive mp4 starting at an offset. Seeking means asking the
-//                                 server for a NEW stream at a new offset, so the position is
-//                                 `offset + currentTime` and the scrubber is ours.
+//   file        — direct play or direct stream. A real byte-range resource; native controls, native seeking,
+//                 `currentTime` is the position.
+//   hls-mse     — a transcode, driven by the vendored hls.js over Media Source Extensions. A real timeline
+//                 too: Jellyfin's playlist is VOD and spans the whole runtime, so a scrub is a segment
+//                 request and the server moves its ffmpeg to that point.
+//   progressive — the fallback for a browser without MSE. One endless mp4 with no length and no ranges, so
+//                 the browser CANNOT seek it: seeking means asking the server for a NEW stream at an offset,
+//                 the position is `startSeconds + currentTime`, and the scrubber has to be ours.
 //
-// Every progress report uses that same computed position, which is why resume points are correct in both
-// modes instead of being wrong by the offset in one of them.
+// Only that last mode is the odd one, and `hasTimeline` is the single flag every other decision here reads.
+//
+// Safari plays an m3u8 natively and is deliberately NOT given one. Segment URIs inside the playlist are
+// relative, so they inherit the playlist's path but not its `?token=` — every segment would come back 401,
+// and Safari cannot set an Authorization header the way hls.js can. Where hls.js runs (including iOS 17.1+,
+// via Managed Media Source) it is used; where it does not, progressive is the honest fallback.

 const PROGRESS_INTERVAL_MS = 10_000;

+type Mode = 'file' | 'hls-mse' | 'progressive';
+
+function transportFor(plan: PlaybackPlan): Mode {
+  if (plan.seekable) return 'file';
+  if (plan.hlsUrl && Hls.isSupported()) return 'hls-mse';
+  return 'progressive';
+}
+
 export const VideoPlayer = ({ id }: { id: string }) => {
  const { token } = useClient();
  const { pathname } = useLocation();
@@ -51,6 +68,8 @@ export const VideoPlayer = ({ id }: { id: string }) => {
  const positionRef = useRef(0);
  const startedRef = useRef(false);

+  const mode = useMemo(() => (plan ? transportFor(plan) : null), [plan]);
+  const hasTimeline = mode !== null && mode !== 'progressive';
  const duration = plan?.runtimeSeconds ?? ticksToSeconds(item?.RunTimeTicks);

  const sendReport = useCallback(
@@ -69,7 +88,7 @@ export const VideoPlayer = ({ id }: { id: string }) => {
    [id, report],
  );

-  /** Open (or re-open) the stream at an offset. A seek in transcode mode is exactly this call. */
+  /** Open (or re-open) the stream at an offset. In progressive mode a seek is exactly this call. */
  const open = useCallback(
    async (startSeconds: number) => {
      // Tell the server the previous session ended before starting another, or its ffmpeg keeps running and
@@ -97,6 +116,39 @@ export const VideoPlayer = ({ id }: { id: string }) => {
    void open(ticksToSeconds(item.UserData?.PlaybackPositionTicks));
  }, [item, open]);

+  // hls.js owns the element's buffer in `hls-mse` mode, so the element gets no `src` at all — attaching one
+  // alongside MSE is how you get two sources fighting over the same video.
+  //
+  // The credential goes on as a header rather than in the URL because hls.js fetches every segment itself:
+  // segment URIs are RELATIVE to the playlist, so a `?token=` on the playlist would not survive onto them.
+  // `xhrSetup` runs before hls.js opens the request and it skips its own `open` if one already happened,
+  // which is what makes setting a header here possible at all.
+  useEffect(() => {
+    const video = videoRef.current;
+    if (mode !== 'hls-mse' || !plan?.hlsUrl || !video) return;
+
+    const hls = new Hls({
+      startPosition: plan.startSeconds > 0 ? plan.startSeconds : -1,
+      xhrSetup: (xhr, url) => {
+        xhr.open('GET', url, true);
+        if (token) xhr.setRequestHeader('Authorization', `Bearer ${token}`);
+      },
+    });
+
+    // Non-fatal errors are hls.js's normal weather and it recovers from them itself. A fatal one is worth one
+    // attempt at the documented recovery for its kind before giving the player back to the user as broken.
+    hls.on(Hls.Events.ERROR, (_event, data) => {
+      if (!data.fatal) return;
+      if (data.type === Hls.ErrorTypes.NETWORK_ERROR) hls.startLoad();
+      else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) hls.recoverMediaError();
+      else setError('The stream stopped unexpectedly.');
+    });
+
+    hls.loadSource(`/api/jellyfin${plan.hlsUrl}`);
+    hls.attachMedia(video);
+    return () => hls.destroy();
+  }, [mode, plan, token]);
+
  // The stop report, on the way out. Also the only place the server learns a transcode is no longer wanted.
  useEffect(
    () => () => {
@@ -115,8 +167,8 @@ export const VideoPlayer = ({ id }: { id: string }) => {
  const onTimeUpdate = () => {
    const video = videoRef.current;
    if (!video || !plan) return;
-    // In transcode mode the element's clock starts at zero for a stream that begins mid-film.
-    const next = plan.seekable ? video.currentTime : plan.startSeconds + video.currentTime;
+    // Only progressive starts the element's clock at zero for a stream that begins mid-film.
+    const next = hasTimeline ? video.currentTime : plan.startSeconds + video.currentTime;
    positionRef.current = next;
    setPosition(next);
  };
@@ -124,7 +176,7 @@ export const VideoPlayer = ({ id }: { id: string }) => {
  const seek = (seconds: number) => {
    const video = videoRef.current;
    const clamped = Math.max(0, duration ? Math.min(seconds, duration - 1) : seconds);
-    if (plan?.seekable && video) {
+    if (hasTimeline && video) {
      video.currentTime = clamped;
      return;
    }
@@ -138,6 +190,10 @@ export const VideoPlayer = ({ id }: { id: string }) => {
    else video.pause();
  };

+  // `src` for everything except MSE, where hls.js feeds the element instead. The key remounts the element when
+  // the source genuinely changes — which in progressive mode is every scrub.
+  const source = plan && mode !== 'hls-mse' ? streamUrl(plan.url, token) : null;
+
  const close = closeHref(pathname, params, PLAY_PARAM);
  const title = item ? episodeLabel(item) : '';

@@ -167,14 +223,14 @@ export const VideoPlayer = ({ id }: { id: string }) => {
          </div>
        ) : plan ? (
          <video
-            key={plan.url}
+            key={mode === 'hls-mse' ? (plan.hlsUrl ?? plan.url) : plan.url}
            ref={videoRef}
-            src={streamUrl(plan.url, token)}
+            src={source ?? undefined}
            className="h-full w-full"
            autoPlay
-            // A direct file is seekable, so the browser's own controls are correct and better than ours.
-            // A live transcode is not, and its controls would show a scrubber that does nothing.
-            controls={plan.seekable}
+            // A real timeline means the browser's own controls are correct, and better than ours. Progressive
+            // has none, and native controls there would show a scrubber that does nothing.
+            controls={hasTimeline}
            onTimeUpdate={onTimeUpdate}
            onPlay={() => {
              setPaused(false);
@@ -185,7 +241,9 @@ export const VideoPlayer = ({ id }: { id: string }) => {
              sendReport('progress', true);
            }}
            onEnded={() => sendReport('stopped')}
-            onError={() => setError('The stream stopped unexpectedly.')}
+            // hls.js reports its own errors through the ERROR event, and sets a MediaError on the element for
+            // ones it is already recovering from — so in MSE mode this handler would fire on the recoverable.
+            onError={() => mode !== 'hls-mse' && setError('The stream stopped unexpectedly.')}
          />
        ) : (
          <div className="flex h-full items-center justify-center text-white/60">
@@ -194,7 +252,7 @@ export const VideoPlayer = ({ id }: { id: string }) => {
        )}
      </div>

-      {plan && !plan.seekable && !error && (
+      {plan && !hasTimeline && !error && (
        <div className="flex items-center gap-3 px-3 py-2 text-white">
          <button type="button" onClick={togglePlay} aria-label={paused ? 'Play' : 'Pause'} className="shrink-0">
            {paused ? <Play className="h-4 w-4" fill="currentColor" /> : <Pause className="h-4 w-4" />}
@@ -0,0 +1,51 @@
+# Vendored hls.js
+
+`hls.mjs` is **hls.js 1.6.16**, checked in rather than installed.
+
+## Why it is here and not in `package.json`
+
+Chromium cannot play an HLS playlist natively, so seeking inside a live Jellyfin transcode needs a player
+library. `bunfig.toml` freezes installs (`frozenLockfile = true`) specifically so that adding a package is a
+deliberate act with a reviewed lockfile diff — see `platform/CLAUDE.md` → "Installs are frozen", and the
+2026-08-04 npm cache-package worm that prompted it.
+
+Vendoring makes the trade explicit instead of implicit:
+
+- **No install-time code.** A committed file has no `preinstall`/`postinstall` hook, which is the exact vector
+  that compromise used. hls.js's own tarball has no install script either — but a future version of it, or of
+  anything it might later depend on, could.
+- **No transitive tree.** hls.js 1.6.16 publishes `dependencies: {}`, `peerDependencies: {}` and
+  `optionalDependencies: {}`, so nothing is being skipped by not resolving it. Its *build-time* devDependencies
+  do reach the affected packages (eslint 8 → file-entry-cache → flat-cache → keyv), but this artifact was
+  published 2026-04-13, months before those versions existed.
+- **It is reviewable.** One unminified file in the diff. That is the point; do not replace it with a minified
+  build to save bytes.
+
+The upstream `.d.ts` is *not* vendored — it imports a tree of internal type modules, which would undo the one
+file rule. `hls.d.mts` next to it declares the API this player actually uses, by hand.
+
+## Provenance
+
+| | |
+|---|---|
+| Package | `hls.js@1.6.16` |
+| Published | 2026-04-13 |
+| Tarball | `https://registry.npmjs.org/hls.js/-/hls.js-1.6.16.tgz` |
+| Tarball sha512 | `VSIRpLfRwlAAdGL4wiTucx2ScRipo0ed1FBatWkyt832jC4CReKstga6yIhYVwGu9LOBjuX9wzmRMeQdBJtzEA==` (matches the registry's published `dist.integrity`) |
+| Extracted from | `package/dist/hls.mjs` |
+| Local change | the trailing `//# sourceMappingURL=hls.mjs.map` line removed — the map is not vendored, and leaving the reference makes devtools 404 |
+| `hls.mjs` sha256 | `45a4bb55e5346bf9284fa7e46b6fac7d62dce5b90394dcba9747d471940fea6e` as published; `ca442f1f963ff66607a242cc7be227b243770d86bfc3251bf675f8a342dfe798` as committed here (the two differ only by that removed line) |
+| Licence | Apache-2.0 — `hls.LICENSE` |
+
+## Updating it
+
+```sh
+V=1.6.17
+curl -sO https://registry.npmjs.org/hls.js/-/hls.js-$V.tgz
+# compare the sha512 against `curl -s https://registry.npmjs.org/hls.js/$V | jq -r .dist.integrity`
+tar xzf hls.js-$V.tgz package/dist/hls.mjs package/LICENSE
+```
+
+Copy `package/dist/hls.mjs` over this one, drop the `sourceMappingURL` line, update the table above, and read
+the diff. A version bump that arrives with a diff you did not read is the thing this directory exists to
+prevent.
@@ -0,0 +1,28 @@
+Copyright (c) 2017 Dailymotion (http://www.dailymotion.com)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+src/remux/mp4-generator.js and src/demux/exp-golomb.ts implementation in this project
+are derived from the HLS library for video.js (https://github.com/videojs/videojs-contrib-hls)
+
+That work is also covered by the Apache 2 License, following copyright:
+Copyright (c) 2013-2015 Brightcove
+
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
@@ -0,0 +1,63 @@
+// Hand-written declarations for the vendored `hls.mjs`.
+//
+// Deliberately narrow: it declares the API this player actually calls, not hls.js's full surface. The upstream
+// `.d.ts` is not vendored because it pulls in a tree of internal type modules, and the point of vendoring was
+// to have ONE reviewable file. Anything added to the player that hls.js supports but this file does not gets
+// declared here, in the open, rather than cast away at the call site.
+
+export type HlsErrorData = {
+  fatal: boolean;
+  type: string;
+  details: string;
+  reason?: string;
+  error?: Error;
+};
+
+export type HlsLevel = { height?: number; width?: number; bitrate?: number };
+
+export type HlsConfig = {
+  /** Where playback begins, in seconds. -1 means "the start", which is not the same as 0 for a live edge. */
+  startPosition?: number;
+  /** Called before `xhr.open`, so it may open the request itself and then set headers on it. */
+  xhrSetup?: (xhr: XMLHttpRequest, url: string) => void;
+  enableWorker?: boolean;
+  lowLatencyMode?: boolean;
+  maxBufferLength?: number;
+  maxMaxBufferLength?: number;
+  backBufferLength?: number;
+};
+
+declare class Hls {
+  constructor(config?: HlsConfig);
+
+  static isSupported(): boolean;
+  static readonly Events: {
+    MANIFEST_PARSED: string;
+    LEVEL_LOADED: string;
+    ERROR: string;
+    MEDIA_ATTACHED: string;
+  };
+  static readonly ErrorTypes: {
+    NETWORK_ERROR: string;
+    MEDIA_ERROR: string;
+    KEY_SYSTEM_ERROR: string;
+    MUX_ERROR: string;
+    OTHER_ERROR: string;
+  };
+
+  loadSource(url: string): void;
+  attachMedia(media: HTMLMediaElement): void;
+  detachMedia(): void;
+  startLoad(startPosition?: number): void;
+  stopLoad(): void;
+  recoverMediaError(): void;
+  destroy(): void;
+
+  on(event: string, listener: (event: string, data: HlsErrorData) => void): void;
+  off(event: string, listener?: (event: string, data: HlsErrorData) => void): void;
+
+  readonly levels: HlsLevel[];
+  currentLevel: number;
+}
+
+export default Hls;