@torrent-tv/proxy 2.86.0 → 2.87.1

package/services/orchestrators/SubtitleOrchestrator.js

@@ -1,160 +0,0 @@
-/**
- * @file Subtitle orchestrator — application layer over subtitle domain.
- *
- * Wraps torrent-worker/subtitle-cues.js domain (planFor, cuesHeldFor,
- * warmSubtitleCues, forgetSubtitles) behind Container/Track abstraction.
- * Provides per-file track list and cue streaming, with the same "only already
- * downloaded clusters" rule as before. Controllers (HTTP or data-channel)
- * depend on this, not on the worker module directly.
- *
- * Delegates to ContainerOrchestrator for track enumeration so subtitle tracks
- * and their flags come from the unified ContainerTrack hierarchy.
- */
-
-import { containerOrchestrator } from "./ContainerOrchestrator.js";
-import {
-  warmSubtitleCues as domainWarm,
-  subtitleTracksOf,
-  declaredSubtitleTracksOf,
-  forgetSubtitles as domainForget
-} from "../torrent-worker/subtitle-cues.js";
-import { logger } from "../../utils/logger.js";
-
-export class SubtitleOrchestrator {
-  /**
-   * @param {import("./ContainerOrchestrator.js").ContainerOrchestrator} containerOrchestrator
-   */
-  constructor(containerOrchestrator) {
-    this.containers = containerOrchestrator;
-  }
-
-  /**
-   * Tracks for menu — text tracks via domain, enriched with ContainerTrack flags.
-   * Falls back to container tracks when domain has no plan yet.
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @param {string} sourceKey
-   * @param {(start:number,end:number)=>Promise<Buffer|null>} [readRange]
-   * @param {number} [fileSize]
-   * @returns {Promise<import("../tracks/index.js").ContainerTrack[]>}
-   */
-  async getTracks(torrent, fileIndex, sourceKey, readRange, fileSize) {
-    try {
-      const domain = await subtitleTracksOf(torrent, fileIndex, sourceKey);
-      if (Array.isArray(domain) && domain.length > 0) return domain;
-    } catch {}
-    if (readRange && Number.isFinite(fileSize)) {
-      try {
-        const tracks = await this.containers.getTracks({ sourceKey, fileIndex, readRange, fileSize, label: torrent?.files?.[fileIndex]?.name ?? "" });
-        return tracks.filter((t) => t.type === "subtitle");
-      } catch {}
-    }
-    return [];
-  }
-
-  /**
-   * Declared subtitle tracks in container order (including image tracks) — for declaredIndex alignment.
-   */
-  async getDeclaredTracks(torrent, fileIndex, sourceKey) {
-    try {
-      return await declaredSubtitleTracksOf(torrent, fileIndex, sourceKey);
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Cues already downloaded for one track — ASKED OF THE TORRENT WORKER, never
-   * walked here.
-   *
-   * The walk decides what it may read from `torrent.bitfield` and
-   * `torrent.pieceLength`, and a torrent stand-in on the main thread has
-   * neither: it carries `infoHash`, `name` and a `files` list whose reads go
-   * back across the boundary (`torrent-worker/client.js`). So the same code
-   * called here answers that nothing is downloaded, walks no clusters, and
-   * returns an empty document — which is not a failure anything reports,
-   * because "no cues held" is a legitimate answer.
-   *
-   * Field 2026-09-03, and it is the whole reason this method changed. An
-   * episode already downloaded from an earlier sitting had its cues found
-   * within a second and a half of the file being opened, and the first four
-   * pushes — everything before 81.7 s — went out before the browser had
-   * subscribed. The catch-up pull that exists for exactly that case answered
-   * `WEBVTT` and nothing else, with `x-subtitle-covered-clusters: 0` against
-   * 283 indexed, so the viewer watched the opening of the episode with no
-   * subtitles and the rest of it with them.
-   *
-   * There is a second reason, independent of the bitfield. The register of what
-   * has been walked, what has been found and in what ORDER lives in the module
-   * that does the walking, and the worker already keeps one — the push path
-   * fills it. Walking again on the main thread would build a SECOND register
-   * with its own `seq` counter, and the browser mixes the cursors from both
-   * paths (`#rememberCursor`): two counters would make a cursor from a pull and
-   * a cursor from a push incomparable. One register, one walk, one cursor.
-   *
-   * @param {{ getSubtitleCues?: Function }} pool - The torrent pool, which is
-   *   what holds the channel to the worker.
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @param {string} sourceKey
-   * @param {number} trackNumber - Container trackNumber
-   * @returns {Promise<{ cues: object[], coveredClusters: number, indexedClusters: number, track: object | null }>}
-   */
-  async getCues(pool, torrent, fileIndex, sourceKey, trackNumber) {
-    // Built fresh on each of the three paths that need it. One shared literal
-    // returned by reference would hand every caller the same array, and a
-    // single one of them appending to it would change what the next caller
-    // reads — which in a method about cue registers not leaking into each
-    // other would be a poor thing to introduce.
-    const empty = () => ({ cues: [], coveredClusters: 0, indexedClusters: 0, track: null });
-    if (typeof pool?.getSubtitleCues !== "function") {
-      // Nothing here can read pieces, and answering an empty document would be
-      // indistinguishable from a file that genuinely holds no cues.
-      logger.warn(
-        "subtitle-orchestrator: the torrent pool cannot be asked for cues, " +
-        "so none can be served — the walk needs the thread that owns the torrent"
-      );
-      return empty();
-    }
-    try {
-      const answer = await pool.getSubtitleCues(torrent, fileIndex, trackNumber);
-      if (!answer) {
-        return empty();
-      }
-      return {
-        cues: Array.isArray(answer.cues) ? answer.cues : [],
-        coveredClusters: answer.coveredClusters ?? 0,
-        indexedClusters: answer.indexedClusters ?? 0,
-        // The worker answers with the track's own fields flat, because a
-        // `ContainerTrack` is a class and only plain objects cross the boundary.
-        track: {
-          codecId: answer.codecId ?? "",
-          codecPrivate: answer.codecPrivate ?? "",
-          language: answer.language ?? ""
-        }
-      };
-    } catch (e) {
-      logger.warn(`subtitle-orchestrator: getCues failed: ${e?.message ?? e}`);
-      return empty();
-    }
-  }
-
-  /**
-   * Warm all subtitle tracks of a file — called periodically and on verified pieces.
-   * Returns per-track fresh cues for push.
-   */
-  async warm(torrent, fileIndex, sourceKey) {
-    try {
-      return await domainWarm(torrent, fileIndex, sourceKey);
-    } catch {
-      return [];
-    }
-  }
-
-  forget(sourceKey, fileIndex) {
-    domainForget(sourceKey, fileIndex);
-    this.containers.forget(sourceKey, fileIndex);
-  }
-}
-
-export const subtitleOrchestrator = new SubtitleOrchestrator(containerOrchestrator);

package/services/output/Output.js

@@ -1,94 +0,0 @@
-/**
- * @file What one output is encoded AS, decided once.
- *
- * `OutputSpec` says what an output is — which tracks, in what form, cut how.
- * This is the other half: the shape the encoder is actually given for it. The
- * box in pixels, the frame rate, the speed setting, whether the picture is tone
- * mapped down from HDR.
- *
- * **Why it is not a fact of a session.** It is decided by the realtime budget
- * at the moment a session is created — what this machine could hold just then —
- * so two sessions of one output, made minutes apart, could be given different
- * shapes while claiming the same identity. Everything downstream assumes
- * otherwise: a segment of one is supposed to be interchangeable with a segment
- * of the other, and the master playlist names one `RESOLUTION` for both.
- *
- * Decided once per output and held here, that cannot happen. What the budget
- * learns afterwards moves the RATE cap, which is deliberately not here: rate
- * control appears in neither the SPS nor the PPS, so it can move under a player
- * that has already cached the init. The size cannot, which is exactly why the
- * size belongs to the output and the cap belongs to the run.
- */
-
-export class Output {
-  /**
-   * @param {object} params
-   * @param {number} params.encodeWidth - 0 means the source's own width.
-   * @param {number} params.encodeHeight - 0 means the source's own height.
-   * @param {number} params.outputFps
-   * @param {string | null} params.softwarePreset - The speed setting, where the
-   *   encoder has a ladder and one was chosen from it.
-   * @param {boolean} params.applyTonemap
-   */
-  constructor({ encodeWidth, encodeHeight, outputFps, softwarePreset, applyTonemap }) {
-    this.encodeWidth = Number.isFinite(encodeWidth) ? encodeWidth : 0;
-    this.encodeHeight = Number.isFinite(encodeHeight) ? encodeHeight : 0;
-    this.outputFps = Number.isFinite(outputFps) && outputFps > 0 ? outputFps : 0;
-    this.softwarePreset = typeof softwarePreset === "string" ? softwarePreset : null;
-    this.applyTonemap = applyTonemap === true;
-  }
-}
-
-/**
- * The shapes this proxy has decided, one per output.
- *
- * Keyed by `OutputSpec.toKey()` and by nothing else: the shape is a property of
- * what is being produced, and two requests that produce the same thing must be
- * given the same one however far apart they arrive.
- */
-export class Outputs {
-  /** @type {Map<string, Output>} */
-  #byKey = new Map();
-
-  /**
-   * The shape for this output, decided by `decide` the first time it is asked
-   * for and never again.
-   *
-   * @param {string} key
-   * @param {() => Output} decide
-   * @returns {Output}
-   */
-  get(key, decide) {
-    let output = this.#byKey.get(key);
-    if (!output) {
-      output = decide();
-      this.#byKey.set(key, output);
-    }
-    return output;
-  }
-
-  /**
-   * Drop every shape nobody is holding.
-   *
-   * Same reason the timelines are swept: a map that only grows is the shape of
-   * half the memory faults recorded in this project.
-   *
-   * @param {Set<Output>} inUse
-   * @returns {number}
-   */
-  forgetUnused(inUse) {
-    let dropped = 0;
-    for (const [key, output] of [...this.#byKey]) {
-      if (!inUse.has(output)) {
-        this.#byKey.delete(key);
-        dropped += 1;
-      }
-    }
-    return dropped;
-  }
-
-  /** @returns {number} */
-  get size() {
-    return this.#byKey.size;
-  }
-}

package/services/output/OutputSpec.js

@@ -1,202 +0,0 @@
-/**
- * @file What a session PRODUCES, stated once and used as its identity.
- *
- * Three domain axes already have a home in this package: what a file states
- * about itself (`container/`), what a track states about itself (`tracks/`),
- * and what anybody wants off the swarm (`demand/`). This is the fourth — what
- * we make out of them — and it had no home at all: the identity of a session
- * was a `[...].join(":")` inside a 300-line function, with no name, no test and
- * nothing printing it.
- *
- * The rule it exists to express, stated by the user 2026-09-03:
- *
- * > A session belongs to the tracks its output actually carries. Its key holds
- * > those tracks' parameters and nothing else. Two sessions whose parameters
- * > agree ARE the same session, and the encoded result is reused by definition.
- *
- * So reuse between viewers is not a feature built on top of this — it is what a
- * correctly built key already means. A field of the REQUEST that does not
- * change one byte of the output must not appear here; measured 2026-09-03, two
- * viewers of one copied picture got two sessions whose output was identical
- * byte for byte (`research/two-viewers-one-file-2026-09-03.md`).
- *
- * What deliberately does NOT appear:
- *
- * 1. the viewer, in any form. Not the consumer id, not where they started, not
- *    their viewport. A viewer is not a property of the material;
- * 2. the bitrate ceiling the viewer's measured link puts on a re-encode. It is
- *    a runtime parameter of a SHARED session — the worst link among the live
- *    consumers decides — so two viewers on one encode is the design, not a
- *    collision. Rate control appears in neither the SPS nor the PPS, which is
- *    why it can move under a player that has already cached the init;
- * 3. the video track number. Only `0:v:0` is ever mapped, so the file names the
- *    picture. Add it here the day a second video track can be chosen.
- *
- * A limit worth stating: two specs that agree name interchangeable output
- * within ONE proxy. A copied picture's bytes depend only on the source, but a
- * re-encoded one's depend on this host's encoder, its preset and its rate cap —
- * so this is not enough to reuse segments BETWEEN proxies (roadmap item 41).
- */
-
-/**
- * The picture an output carries.
- */
-export class VideoOutput {
-  /**
-   * @param {object} params
-   * @param {number} params.fileIndex - The file the picture is read from.
-   * @param {{ width: number, height: number, exactSize: boolean } | null} params.encode
-   *   Null when the picture is copied — then the output is the source's own
-   *   size and nothing about a target box can change it. The box when it is
-   *   re-encoded, with `exactSize` saying that box is produced exactly as asked
-   *   and the realtime budget must not move it.
-   *
-   *   `exactSize` says NOTHING ABOUT WHO ASKED. Every rung of a master playlist
-   *   sets it, whether the viewer picked that rung or the player moved itself,
-   *   because two rungs allowed to drift would land on one height and the
-   *   choice between them would mean nothing. It was called `manual` until
-   *   2026-09-13, and that name was read as "the viewer did this" four times
-   *   over a few weeks — in field logs where the viewer had touched nothing.
-   */
-  constructor({ fileIndex, encode = null }) {
-    this.fileIndex = Number.isInteger(fileIndex) && fileIndex >= 0 ? fileIndex : 0;
-    this.encode = encode
-      ? {
-          width: Number.isInteger(encode.width) && encode.width > 0 ? encode.width : 0,
-          height: Number.isInteger(encode.height) && encode.height > 0 ? encode.height : 0,
-          exactSize: encode.exactSize === true
-        }
-      : null;
-  }
-
-  /**
-   * @returns {string}
-   */
-  toKey() {
-    if (!this.encode) {
-      return `v=${this.fileIndex}/copy`;
-    }
-    const box = `${this.encode.width}x${this.encode.height}`;
-    return `v=${this.fileIndex}/enc:${box}:${this.encode.exactSize ? "exact" : "budget"}`;
-  }
-}
-
-/**
- * The soundtrack an output carries.
- */
-export class AudioOutput {
-  /**
-   * @param {object} params
-   * @param {number} params.fileIndex - The file the TRACK lives in, which for a
-   *   dub shipped beside the picture is not the picture's file.
-   * @param {number} params.trackIndex - `0:a:N` inside that file. The flat
-   *   number the browser sends spans the picture's own tracks and the files
-   *   beside it, and two flat numbers of two different pictures can name one
-   *   track; this is the number that cannot.
-   * @param {boolean} params.transcode - Re-encoded to AAC, or copied.
-   */
-  constructor({ fileIndex, trackIndex, transcode }) {
-    this.fileIndex = Number.isInteger(fileIndex) && fileIndex >= 0 ? fileIndex : 0;
-    this.trackIndex = Number.isInteger(trackIndex) && trackIndex >= 0 ? trackIndex : 0;
-    this.transcode = transcode === true;
-  }
-
-  /**
-   * @returns {string}
-   */
-  toKey() {
-    return `a=${this.fileIndex}/${this.trackIndex}/${this.transcode ? "aac" : "copy"}`;
-  }
-}
-
-/**
- * Where an output is cut.
- *
- * Both forms belong to a FILE and not to the session: the keyframe grid is that
- * file's own keyframe times, and the uniform grid is derived from that file's
- * duration. A soundtrack takes the grid of the picture it accompanies, so its
- * grid names the picture's file — which is what makes two soundtrack sessions
- * cut for two different pictures tell themselves apart.
- */
-export class CutGrid {
-  /**
-   * @param {object} params
-   * @param {"keyframe" | "uniform"} params.kind
-   * @param {number} params.fileIndex - Whose keyframes, or whose duration.
-   */
-  constructor({ kind, fileIndex }) {
-    this.kind = kind === "keyframe" ? "keyframe" : "uniform";
-    this.fileIndex = Number.isInteger(fileIndex) && fileIndex >= 0 ? fileIndex : 0;
-  }
-
-  /**
-   * @returns {string}
-   */
-  toKey() {
-    return `grid=${this.kind === "keyframe" ? "kf" : "even"}@${this.fileIndex}`;
-  }
-}
-
-/**
- * One encode of one torrent's material: which tracks, in what form, cut how,
- * packaged how.
- */
-export class OutputSpec {
-  /**
-   * @param {object} params
-   * @param {string} params.sourceKey - `torrent:<infohash>`, the canonical
-   *   identity of the torrent itself: a magnet and a `.torrent` file for the
-   *   same content produce the same one (`torrent-source-key.js`). Nothing
-   *   further is needed to say WHICH film this is.
-   * @param {string} params.segmentFormatId - fMP4 or MPEG-TS. Two viewers
-   *   asking for different containers cannot share one ffmpeg.
-   * @param {CutGrid} params.grid
-   * @param {VideoOutput | null} params.video
-   * @param {AudioOutput | null} params.audio
-   */
-  constructor({ sourceKey, segmentFormatId, grid, video = null, audio = null }) {
-    this.sourceKey = String(sourceKey ?? "");
-    this.segmentFormatId = String(segmentFormatId ?? "");
-    this.grid = grid;
-    this.video = video;
-    this.audio = audio;
-  }
-
-  /**
-   * What this output carries, in the vocabulary the rest of the class uses.
-   *
-   * `muxed` is the one case where a session legitimately holds the parameters
-   * of two tracks: a browser that does not understand rendition groups must be
-   * sent its sound inside the picture's own stream.
-   *
-   * @returns {"video-only" | "audio-only" | "muxed" | "empty"}
-   */
-  get carries() {
-    if (this.video && this.audio) {
-      return "muxed";
-    }
-    if (this.video) {
-      return "video-only";
-    }
-    if (this.audio) {
-      return "audio-only";
-    }
-    return "empty";
-  }
-
-  /**
-   * The identity. Two outputs with the same one are the same output.
-   *
-   * @returns {string}
-   */
-  toKey() {
-    const parts = [this.sourceKey, `fmt=${this.segmentFormatId}`, this.grid.toKey(), this.carries];
-    if (this.video) {
-      parts.push(this.video.toKey());
-    }
-    if (this.audio) {
-      parts.push(this.audio.toKey());
-    }
-    return parts.join(":");
-  }
-}

package/services/output/index.js

@@ -1 +0,0 @@
-export { OutputSpec, VideoOutput, AudioOutput, CutGrid } from "./OutputSpec.js";

package/services/output/ladder.js

@@ -1,26 +0,0 @@
-/**
- * @file The heights a picture may be offered at.
- *
- * A fact about an output and about nothing else: it takes a source height and
- * answers with heights. What the machine can afford of them is the quality
- * budget's question, and what a player may splice between is `LiveOutputs`.
- */
-
-// The resolutions a viewer may choose between. Only rungs at or below the
-// source are offered: upscaling invents detail and costs the encoder more than
-// the source itself.
-const VARIANT_LADDER = [2160, 1440, 1080, 720, 540, 480, 360, 240];
-
-/**
- * The heights offered for a source of this height, largest first.
- *
- * @param {number} sourceHeight
- * @returns {number[]}
- */
-export function variantHeightsFor(sourceHeight) {
-  if (!Number.isFinite(sourceHeight) || sourceHeight <= 0) {
-    return [];
-  }
-  const rungs = VARIANT_LADDER.filter((height) => height < sourceHeight);
-  return [Math.round(sourceHeight), ...rungs];
-}