@torrent-tv/proxy 2.73.0 → 2.74.0

package/services/tracks/TextSubtitleTrack.js

@@ -1,47 +1,287 @@
-/**
- * @file Text subtitle track — convertible to WebVTT.
- *
- * Matroska: S_TEXT/UTF8, S_TEXT/ASS, S_TEXT/SSA, S_TEXT/WEBVTT (RFC 9559)
- * MP4: tx3g, text, wvtt (stpp/TTML is NOT text for this pipeline — excluded)
- * External files: .srt .ass .ssa .vtt — modelled as TextSubtitleTrack with no container backing.
- */
-
-import { SubtitleTrack } from "./SubtitleTrack.js";
-import { markupKindOf, plainCueText } from "./subtitle-markup.js";
-
-const TEXT_CODECS_MATROSKA = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA", "S_TEXT/WEBVTT"]);
-const TEXT_FORMATS_MP4 = new Set(["tx3g", "text", "wvtt"]);
-
-export class TextSubtitleTrack extends SubtitleTrack {
-  constructor(params) {
-    super(params);
-    this.textCodec = params.codecId ?? "";
-  }
-
-  isTextBased() {
-    return true;
-  }
-
-  /** Which markup this track's cue text carries — see `subtitle-markup.js`. */
-  get markupKind() {
-    return markupKindOf(this.textCodec);
-  }
-
-  /**
-   * The visible text of one of this track's cues.
-   *
-   * @param {string} textField - The cue's text field, already out of its
-   *   container's framing. This method knows the codec and not the container,
-   *   which is why it cannot be handed a whole dialogue row.
-   * @returns {string}
-   */
-  plainText(textField) {
-    return plainCueText(textField, this.textCodec);
-  }
-
-  static isTextCodec(codecId) {
-    return TEXT_CODECS_MATROSKA.has(codecId) || TEXT_FORMATS_MP4.has(codecId);
-  }
-}
-
-export { TEXT_CODECS_MATROSKA, TEXT_FORMATS_MP4 };
+/**
+ * @file A subtitle track whose cues are text, and everything that follows from
+ * that being true.
+ *
+ * Matroska: `S_TEXT/UTF8`, `S_TEXT/ASS`, `S_TEXT/SSA`, `S_TEXT/WEBVTT`
+ * (RFC 9559). MP4: `tx3g`, `text`, `wvtt` (`stpp`/TTML is XML and is not text
+ * for this pipeline). A file beside the film is one of these too, with no
+ * container behind it.
+ *
+ * Two axes meet on a subtitle cue and only ONE of them is here. How a cue's
+ * bytes are FRAMED is stated by the container's specification and is answered
+ * by `container/`: Matroska reorders an ASS dialogue row and drops its two
+ * timing fields (`matroska.org/technical/subtitles.html`), a `.ass` file states
+ * its own field order in the `Format:` line of `[Events]`, an MP4 carries each
+ * cue as a sample with a length prefix. What the CODEC then puts inside that
+ * text — override groups in braces, `\N` and `\n` for a break, `\h` for a hard
+ * space — is a fact about ASS wherever it is stored, and that is this file,
+ * along with writing the cues out as WebVTT.
+ *
+ * The two were one function until 2.72.1, which is what showed English
+ * subtitles as `21,0,Default,,0000,0000,0000,,I am the powerful Demon King`:
+ * it counted commas to guess which framing it held, expected the ten fields of
+ * a row in a FILE, and a Matroska block carries nine. A function that has to
+ * guess the shape of its input is being called by someone who knew and did not
+ * say.
+ */
+
+import { SubtitleTrack } from "./SubtitleTrack.js";
+import { detectLanguage } from "../language-detect.js";
+
+const TEXT_CODECS_MATROSKA = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA", "S_TEXT/WEBVTT"]);
+const TEXT_FORMATS_MP4 = new Set(["tx3g", "text", "wvtt"]);
+
+/** How a cue's text is marked up, once the container's framing is off. */
+export const MarkupKind = {
+  /** Sub Station Alpha and its advanced form: `{\pos(…)}`, `\N`, `\h`. */
+  ASS: "ass",
+  /** Nothing to strip: the text is what is shown. */
+  NONE: "none"
+};
+
+/**
+ * Which markup a codec's cue text carries, by any of the codec's names.
+ *
+ * The keys are every name this proxy has for a text subtitle codec: Matroska
+ * CodecIDs (RFC 9559 §5.1.4.1.28 and the codec mappings beside it), MP4 sample
+ * entry types (ISO/IEC 14496-12 §12.6, plus Apple's `tx3g`), and the file
+ * extensions a subtitle shipped beside the film uses. They are listed together
+ * because the ANSWER is the same for all of them — ASS is ASS whether it sits
+ * in a Matroska block, in a file, or nowhere yet — and keeping three tables
+ * would mean three places to forget.
+ *
+ * @type {Map<string, string>}
+ */
+const MARKUP_BY_CODEC = new Map([
+  ["S_TEXT/ASS", MarkupKind.ASS],
+  ["S_TEXT/SSA", MarkupKind.ASS],
+  [".ass", MarkupKind.ASS],
+  [".ssa", MarkupKind.ASS],
+  ["S_TEXT/UTF8", MarkupKind.NONE],
+  ["S_TEXT/WEBVTT", MarkupKind.NONE],
+  [".srt", MarkupKind.NONE],
+  [".vtt", MarkupKind.NONE],
+  [".webvtt", MarkupKind.NONE],
+  ["tx3g", MarkupKind.NONE],
+  ["text", MarkupKind.NONE],
+  ["wvtt", MarkupKind.NONE]
+]);
+
+/** How long a cue with no stated end is shown, when no cue follows it. */
+const OPEN_ENDED_CUE_SECONDS = 4;
+
+export class TextSubtitleTrack extends SubtitleTrack {
+  constructor(params) {
+    super(params);
+    this.textCodec = params.codecId ?? "";
+  }
+
+  isTextBased() {
+    return true;
+  }
+
+  /**
+   * Which markup a codec's cue text carries.
+   *
+   * An unknown codec is answered `NONE` rather than refused: the text is then
+   * shown as it is, which is wrong only in so far as some markup stays visible,
+   * where a refusal would show nothing at all.
+   *
+   * @param {string} codecId - Matroska CodecID, MP4 sample entry type, or a
+   *   file extension including the dot. Case is ignored for extensions, which
+   *   arrive from file names, and kept for the others, which a spec spells.
+   * @returns {string} One of {@link MarkupKind}.
+   */
+  static markupKindOf(codecId) {
+    const name = String(codecId ?? "");
+    return MARKUP_BY_CODEC.get(name) ?? MARKUP_BY_CODEC.get(name.toLowerCase()) ?? MarkupKind.NONE;
+  }
+
+  /**
+   * The visible text of one cue: its markup taken off, nothing else touched.
+   *
+   * @param {string} text - The cue's text FIELD, already out of the container's
+   *   framing. Handing a whole dialogue row to this is the mistake described at
+   *   the top of this file.
+   * @param {string} codecId
+   * @returns {string} Possibly empty — a cue whose text is only a drawing
+   *   command or a positioning group has nothing to show, and the caller drops
+   *   it.
+   */
+  static plainTextOf(text, codecId) {
+    const raw = String(text ?? "");
+    if (TextSubtitleTrack.markupKindOf(codecId) !== MarkupKind.ASS) {
+      return raw.trim();
+    }
+    return raw
+      // An override group. Any brace content is a directive, never dialogue:
+      // drawing commands, karaoke timing, positioning, font changes.
+      .replace(/\{[^}]*\}/g, "")
+      // Both breaks reach a player as a break. ASS distinguishes them — `\N` is
+      // always a break, `\n` only where the style does not wrap — and a WebVTT
+      // cue has no way to express the difference, so it takes the break.
+      .replace(/\\N/g, "\n")
+      .replace(/\\n/g, "\n")
+      // A space the renderer may not collapse.
+      .replace(/\\h/g, " ")
+      .trim();
+  }
+
+  /**
+   * One cue's start or end as WebVTT writes it: `hh:mm:ss.mmm`.
+   *
+   * @param {number} seconds
+   * @returns {string}
+   */
+  static vttTime(seconds) {
+    const safe = Math.max(0, Number(seconds) || 0);
+    const hours = Math.floor(safe / 3600);
+    const minutes = Math.floor((safe % 3600) / 60);
+    const rest = safe % 60;
+    return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:${rest.toFixed(3).padStart(6, "0")}`;
+  }
+
+  /**
+   * Resolve what a cue is missing and take its codec's markup off, so what is
+   * left is what a player shows.
+   *
+   * A cue with no duration — a Matroska SimpleBlock, which subtitles rarely use
+   * — is given the time until the next one IN THIS LIST, and the last such cue
+   * a few seconds. Not an invention about the film: it is what a player does
+   * with an open-ended cue, made explicit so every consumer agrees on it.
+   *
+   * @param {{ startSeconds: number, endSeconds?: number | null, text: string }[]} cues
+   * @param {string} codecId
+   * @returns {{ startSeconds: number, endSeconds: number, text: string }[]}
+   */
+  static finalizeCues(cues, codecId) {
+    const result = [];
+    (Array.isArray(cues) ? cues : []).forEach((cue, index) => {
+      const next = cues[index + 1];
+      const endSeconds =
+        cue.endSeconds ?? (next ? next.startSeconds : cue.startSeconds + OPEN_ENDED_CUE_SECONDS);
+      const text = TextSubtitleTrack.plainTextOf(cue.text, codecId);
+      if (!text) {
+        return;
+      }
+      result.push({ startSeconds: cue.startSeconds, endSeconds, text });
+    });
+    return result;
+  }
+
+  /**
+   * A WebVTT document from a list of cues — the one writer, used by every path
+   * that produces subtitles: a file beside the film, a track inside it, a pull
+   * and a push.
+   *
+   * @param {{ startSeconds: number, endSeconds?: number | null, text: string }[]} cues
+   * @param {string} codecId
+   * @returns {string}
+   */
+  static cuesToVtt(cues, codecId) {
+    const lines = ["WEBVTT", ""];
+    for (const cue of TextSubtitleTrack.finalizeCues(cues, codecId)) {
+      lines.push(`${TextSubtitleTrack.vttTime(cue.startSeconds)} --> ${TextSubtitleTrack.vttTime(cue.endSeconds)}`);
+      lines.push(cue.text);
+      lines.push("");
+    }
+    return lines.join("\n");
+  }
+
+  /**
+   * The words of a WebVTT document — what a viewer reads, with everything the
+   * format puts around them removed.
+   *
+   * A WebVTT document is a series of blocks separated by blank lines. A block
+   * that holds a timing line (`00:00:12.060 --> 00:00:13.270`) is a cue, and the
+   * lines after that timing line are its text; the lines before it are the cue's
+   * optional identifier. A block with NO timing line is the `WEBVTT` header or a
+   * `NOTE` / `STYLE` / `REGION` block, and none of those is anybody's language.
+   * That one rule removes the identifiers, the timings and the headers together.
+   *
+   * What is left can still carry WebVTT's own inline markup — `<v Speaker>`,
+   * `<i>`, `<c.yellow>` — and character references. Both are dropped: a speaker
+   * name and a class name are written in whatever language the releaser's tooling
+   * used, which is not the language of the film.
+   *
+   * @param {string} vtt - A WebVTT document.
+   * @returns {string} The cue text, blocks joined by newlines.
+   */
+  static cueTextOfVtt(vtt) {
+    if (typeof vtt !== "string") {
+      return "";
+    }
+    const blocks = vtt.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split(/\n{2,}/);
+    const spoken = [];
+    for (const block of blocks) {
+      const lines = block.split("\n");
+      const timingAt = lines.findIndex((line) => line.includes("-->"));
+      if (timingAt < 0) {
+        continue;
+      }
+      for (const line of lines.slice(timingAt + 1)) {
+        spoken.push(line);
+      }
+    }
+    return spoken
+      .join("\n")
+      .replace(/<[^>]*>/g, "")
+      // A character reference stands for one character and never for a word, so a
+      // space in its place keeps the neighbouring words apart and adds nothing.
+      .replace(/&[a-z]+;|&#\d+;|&#x[0-9a-f]+;/gi, " ")
+      .trim();
+  }
+
+  /**
+   * Detect the language of a WebVTT document, reading only its cue text.
+   *
+   * @param {string} vtt - A WebVTT document.
+   * @returns {{ code: string, name: string } | null} Detected language, or null when uncertain.
+   */
+  static detectLanguageFromVtt(vtt) {
+    return detectLanguage(TextSubtitleTrack.cueTextOfVtt(vtt));
+  }
+
+  static isTextCodec(codecId) {
+    return TEXT_CODECS_MATROSKA.has(codecId) || TEXT_FORMATS_MP4.has(codecId);
+  }
+
+  /** Which markup this track's cue text carries. */
+  get markupKind() {
+    return TextSubtitleTrack.markupKindOf(this.textCodec);
+  }
+
+  /**
+   * The visible text of one of this track's cues.
+   *
+   * @param {string} textField - The cue's text field, already out of its
+   *   container's framing. This method knows the codec and not the container,
+   *   which is why it cannot be handed a whole dialogue row.
+   * @returns {string}
+   */
+  plainText(textField) {
+    return TextSubtitleTrack.plainTextOf(textField, this.textCodec);
+  }
+
+  /**
+   * This track's cues, resolved and stripped, as a player reads them.
+   *
+   * @param {{ startSeconds: number, endSeconds?: number | null, text: string }[]} cues
+   * @returns {{ startSeconds: number, endSeconds: number, text: string }[]}
+   */
+  finalize(cues) {
+    return TextSubtitleTrack.finalizeCues(cues, this.textCodec);
+  }
+
+  /**
+   * This track's cues as a WebVTT document.
+   *
+   * @param {{ startSeconds: number, endSeconds?: number | null, text: string }[]} cues
+   * @returns {string}
+   */
+  toVtt(cues) {
+    return TextSubtitleTrack.cuesToVtt(cues, this.textCodec);
+  }
+}
+
+export { TEXT_CODECS_MATROSKA, TEXT_FORMATS_MP4 };

package/services/tracks/index.js

@@ -1,14 +1,14 @@
-export { ContainerTrack } from "./ContainerTrack.js";
-export { VideoTrack } from "./VideoTrack.js";
-export { AudioTrack } from "./AudioTrack.js";
-export { SubtitleTrack } from "./SubtitleTrack.js";
-export { TextSubtitleTrack, TEXT_CODECS_MATROSKA, TEXT_FORMATS_MP4 } from "./TextSubtitleTrack.js";
-export { ImageSubtitleTrack } from "./ImageSubtitleTrack.js";
-export { MarkupKind, markupKindOf, plainCueText } from "./subtitle-markup.js";
-// There is deliberately no class for a track that lives in a file of its own.
-// `<name>.mka` is a Matroska container holding an `AudioTrack`, and
-// `MatroskaContainer` reads it exactly as it reads the picture's — so "external"
-// is not a KIND of track, only the answer to where a track's bytes are. That
-// answer belongs to the application layer, which knows about torrents; this one
-// describes what a container declares and must not. `ExternalSubtitleFile`,
-// which asserted the opposite, was never used by anything and is gone.
+export { ContainerTrack } from "./ContainerTrack.js";
+export { VideoTrack } from "./VideoTrack.js";
+export { AudioTrack } from "./AudioTrack.js";
+export { SubtitleTrack } from "./SubtitleTrack.js";
+export { TextSubtitleTrack, TEXT_CODECS_MATROSKA, TEXT_FORMATS_MP4 } from "./TextSubtitleTrack.js";
+export { ImageSubtitleTrack } from "./ImageSubtitleTrack.js";
+export { MarkupKind } from "./TextSubtitleTrack.js";
+// There is deliberately no class for a track that lives in a file of its own.
+// `<name>.mka` is a Matroska container holding an `AudioTrack`, and
+// `MatroskaContainer` reads it exactly as it reads the picture's — so "external"
+// is not a KIND of track, only the answer to where a track's bytes are. That
+// answer belongs to the application layer, which knows about torrents; this one
+// describes what a container declares and must not. `ExternalSubtitleFile`,
+// which asserted the opposite, was never used by anything and is gone.

package/test/delivery-probe.test.js

@@ -211,3 +211,70 @@ test("a browser that does not report its bytes is judged as before", () => {
   assert.equal(reading.verdict, "association-stopped");
   assert.doesNotMatch(reading.detail, /peerBytes=/);
 });
+
+test("a frozen tab's own event-loop delay counts toward the allowance", () => {
+  // Field case 2026-09-03, session 03f211b8. The viewer paused at 15:24:21 with
+  // 121.5 s buffered; the tab went hidden at 15:24:35 and its event loop fell
+  // behind — loopLag 681 → 1881 → 4297 → 5957 ms. At 15:26:05 the probes read
+  // `gap 12 of 11` and printed `association-stopped`, the ring files were kept
+  // and a 180 s capture was taken; seven seconds later the same connection read
+  // `flowing`. Nothing had stopped: the browser simply could not run the timer
+  // that answers a probe.
+  // The line printed `gap 12 of 11`; the queue was empty and the round trip
+  // 162 ms, so the cadence term is whatever makes the allowance 11.
+  const measured = {
+    queuedBytes: 0,
+    bytesPerSecond: 300,
+    rttMs: 162,
+    echoIntervalMs: 5000
+  };
+  const withoutLag = allowedGap(measured);
+  const withLag = allowedGap({ ...measured, peerLoopLagMs: 1881 });
+  assert.equal(withoutLag, 11, `the field allowance was 11, not ${withoutLag}`);
+  assert.ok(withLag > 12, `a gap of 12 must fit inside ${withLag}`);
+  const allowed = Object.fromEntries(ALL.map((label) => [label, withLag]));
+  const { verdict, detail } = readProbeState(
+    state(
+      { proxy: 9547, "proxy-control": 9547, "proxy-fast": 9547 },
+      {
+        seq: 9559,
+        allowed,
+        echoAgeMs: 5963,
+        echoStaleMs: 11 * PROBE_INTERVAL_MS + 162 + 5000 + 1881,
+        peerBytesAdvancing: false,
+        peerLoopLagMs: 1881,
+        peerVisibility: "hidden"
+      }
+    )
+  );
+  assert.equal(verdict, "flowing");
+  assert.match(detail, /peerLoopLag=1881ms/);
+  assert.match(detail, /peerTab=hidden/);
+});
+
+test("the peer's lag widens the bound on a stale echo without removing it", () => {
+  // The same term must not make `reverse-direction-gone` unreachable: a peer
+  // that has genuinely gone silent is still silent for far longer than its own
+  // loop delay explains.
+  const { verdict } = readProbeState(
+    state(
+      { proxy: 99, "proxy-control": 99, "proxy-fast": 99 },
+      {
+        echoAgeMs: 120_000,
+        echoStaleMs: 5500 + 162 + 1000 + 4297,
+        peerLoopLagMs: 4297,
+        peerVisibility: "hidden"
+      }
+    )
+  );
+  assert.equal(verdict, "reverse-direction-gone");
+});
+
+test("a peer that reports no loop delay is judged exactly as before", () => {
+  const reading = readProbeState(
+    state({ proxy: 90, "proxy-control": 90, "proxy-fast": 90 }, { peerBytesAdvancing: false })
+  );
+  assert.equal(reading.verdict, "association-stopped");
+  assert.doesNotMatch(reading.detail, /peerLoopLag=/);
+  assert.doesNotMatch(reading.detail, /peerTab=/);
+});