@torrent-tv/proxy 2.68.0 → 2.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.68.0",
+  "version": "2.69.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/subtitles/get.js

@@ -25,7 +25,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { detectLanguage } from "../../../services/language-detect.js";
+import { detectLanguageFromVtt } from "../../../services/language-detect.js";
 import { SubtitleController } from "../../../services/controllers/SubtitleController.js";
 import { logger } from "../../../utils/logger.js";
 
@@ -137,7 +137,7 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
  * Extractions by `sourceKey:fileIndex:trackIndex`, so the scan happens once per
  * track however many times it is asked for.
  *
- * @type {Map<string, { state: "running" | "done" | "failed", body?: Buffer, language?: string, error?: string }>}
+ * @type {Map<string, { state: "running" | "done" | "failed", body?: Buffer, language?: { code: string, name: string } | null, error?: string }>}
  */
 const extractions = new Map();
 
@@ -190,7 +190,12 @@ function startExtraction({ key, ffmpegBin, localBaseUrl, sourceKey, fileIndex, t
       logger.warn(`subtitles ${key}: nothing produced after ${seconds}s`);
       return;
     }
-    extractions.set(key, { state: "done", body, language: detectLanguage(String(body.subarray(0, 4096))) });
+    // The whole document, decoded as one string, and only its cue text.
+    // Detecting on the first 4096 BYTES was wrong twice over: a byte cut lands
+    // mid-character on any non-Latin track, and most of those bytes are
+    // timestamps rather than words. This runs once per track in the background,
+    // so reading all of it costs nothing anybody waits for.
+    extractions.set(key, { state: "done", body, language: detectLanguageFromVtt(body.toString("utf8")) });
     logger.info(`subtitles ${key}: ${body.length} bytes in ${seconds}s`);
   };
   ffmpeg.once("close", settle);

package/services/controllers/SubtitleController.js

@@ -9,7 +9,7 @@
 
 import { subtitleOrchestrator } from "../orchestrators/SubtitleOrchestrator.js";
 import { convertSubtitleToVtt, decodeSubtitleBytes } from "../subtitle-convert.js";
-import { detectLanguage } from "../language-detect.js";
+import { detectLanguage, detectLanguageFromVtt } from "../language-detect.js";
 import { finalizeCues } from "../torrent-worker/subtitle-cues.js";
 
 const EXTERNAL_MAX_BYTES = 8 * 1024 * 1024;
@@ -75,7 +75,12 @@ export class SubtitleController {
         const text = decodeSubtitleBytes(bytes);
         const vtt = convertSubtitleToVtt(text, ext);
         if (!vtt) return { error: `Unsupported subtitle format: ${ext}`, status: 422 };
-        return { vtt, language: detectLanguage(text), headers: {} };
+        // The language is read from the CONVERTED document, not from the file.
+        // The conversion has already dropped everything that is not the words —
+        // and on an ASS file that is half of it, in Latin letters, which is what
+        // made a Russian track answer `en` (field 2026-09-01, and the whole of
+        // `research/subtitle-language-ass-markup-2026-09-01.md`).
+        return { vtt, language: detectLanguageFromVtt(vtt), headers: {} };
       } catch (e) {
         return { error: `Could not read subtitle file: ${e?.message ?? e}`, status: 502 };
       } finally {
@@ -105,8 +110,23 @@ export class SubtitleController {
       const cursor = held.cues.reduce((h, c) => Math.max(h, Number(c.seq) || 0), 0);
       const fresh = Number.isInteger(since) ? held.cues.filter((c) => (Number(c.seq) || 0) > since)
         : Number.isFinite(after) ? held.cues.filter((c) => c.startSeconds > after) : held.cues;
-      const vtt = cuesToVtt(fresh, held.track?.codecId ?? track?.codecId ?? "");
-      const language = held.cues.length > 0 ? detectLanguage(held.cues.map((c) => c.text).join("\n")) : null;
+      const codecId = held.track?.codecId ?? track?.codecId ?? "";
+      const vtt = cuesToVtt(fresh, codecId);
+      // Two things this reads, and each of them was wrong before 2.68.1.
+      //
+      // It reads the cues through `finalizeCues`, which is what turns an ASS
+      // dialogue row into the words: a raw cue carries the nine
+      // comma-separated fields of the row and its `{\…}` override groups, and
+      // those are Latin on a Russian track. Detecting on the raw text is the
+      // same fault as detecting on a whole `.ass` file, one layer down.
+      //
+      // And it reads EVERY cue held so far, not the `fresh` subset that is
+      // being sent. A re-subscription after a reconnect asks only for what this
+      // page missed, which can be three lines, and three lines are not a sample
+      // of a language.
+      const language = detectLanguage(
+        finalizeCues(held.cues, codecId).map((cue) => cue.text).join("\n")
+      );
       return {
         vtt,
         language,

package/services/data-channel-handler.js

@@ -590,10 +590,12 @@ export function createDataChannelHandler({
    * are tiny (kilobytes at most for a whole track), so this is one message,
    * not a stream.
    *
-   * @param {{ sourceKey: string, fileIndex: number, trackIndex: number, cues: object[], language: string, cursor: number }} event
+   * @param {{ sourceKey: string, fileIndex: number, trackIndex: number, cues: object[],
+   *   language: string, detectedLanguage: { code: string, name: string } | null,
+   *   cursor: number }} event
    * @returns {void}
    */
-  function publishSubtitleCues({ sourceKey, fileIndex, trackIndex, cues, language, cursor }) {
+  function publishSubtitleCues({ sourceKey, fileIndex, trackIndex, cues, language, detectedLanguage, cursor }) {
     const set = subtitleSubscribers.get(`${sourceKey}:${fileIndex}`);
     if (!set || set.size === 0) {
       log(
@@ -602,7 +604,7 @@ export function createDataChannelHandler({
       );
       return;
     }
-    const message = { type: "subtitle-cues", fileIndex, trackIndex, cues, language, cursor };
+    const message = { type: "subtitle-cues", fileIndex, trackIndex, cues, language, detectedLanguage, cursor };
     const total = set.size;
     let sent = 0;
     for (const channel of set) {

package/services/language-detect.js

@@ -54,20 +54,175 @@ const LANG_3_TO_1 = {
 
 const ONLY = Object.keys(LANG_3_TO_1);
 
+/**
+ * The least text, in characters, that supports an answer of each language.
+ *
+ * MEASURED, not chosen — `research/franc-boundary-2026-09-02.md`. Method:
+ * Wikipedia extracts per language (deliberately NOT the UDHR, which is what
+ * franc's own profiles are built from and would read optimistically), 120
+ * windows cut at random from them at each length of a ladder from 40 to 1300
+ * characters, and the figure recorded is the shortest length from which franc
+ * answered correctly in at least 95 % of trials AND kept doing so at every
+ * longer length measured.
+ *
+ * Why it is per language rather than one number: the answer is not equally hard
+ * to reach, and the spread is fivefold. Greek and Korean settle at 40
+ * characters because their script settles it; English needs 130; Russian and
+ * Czech need 650, because each competes with neighbours in this very list for
+ * the same trigrams — Russian with Bulgarian, Serbian and Ukrainian, Czech with
+ * Slovak.
+ *
+ * Two languages are deliberately ABSENT. Swedish and Chinese did not settle
+ * anywhere in the ladder on the corpora collected, so no figure for them is
+ * measured and none is invented; they take the fallback below.
+ *
+ * A language with no entry gets the WORST measured figure. That is the
+ * conservative reading and it is still a measurement rather than a guess: it
+ * says "no better than the hardest language we have measured".
+ *
+ * @type {Record<string, number>}
+ */
+const LEAST_TEXT = {
+  bel: 100,
+  bul: 80,
+  ces: 650,
+  deu: 200,
+  ell: 40,
+  eng: 130,
+  fra: 80,
+  heb: 60,
+  ita: 160,
+  kor: 40,
+  nld: 130,
+  pol: 200,
+  por: 200,
+  rus: 650,
+  spa: 100,
+  srp: 100,
+  tur: 160,
+  ukr: 250
+};
+
+/** The worst measured figure, used for any language not in the table. */
+const LEAST_TEXT_WORST = Math.max(...Object.values(LEAST_TEXT), 0);
+
+/** franc's own floor: below this it is not asked at all. */
+const FRANC_FLOOR = 15;
+
+/** One space between words, nothing else — the form every figure above is in. */
+function normalise(text) {
+  return typeof text === "string" ? text.replace(/\s+/g, " ").trim() : "";
+}
+
+/**
+ * franc's answer for this text, or null when it has none.
+ *
+ * @param {string} text
+ * @returns {string | null} ISO 639-3.
+ */
+function ask(text) {
+  if (text.length < FRANC_FLOOR) {
+    return null;
+  }
+  const iso3 = franc(text, { only: ONLY, minLength: FRANC_FLOOR });
+  return iso3 === "und" ? null : iso3;
+}
+
 /**
  * Best-effort detect the language of subtitle text.
  *
- * @param {string} text - Decoded subtitle text (VTT/SRT/ASS — franc ignores markup well enough).
+ * **Give this the words a viewer reads and nothing else.** franc scores letter
+ * trigrams over the whole string it is handed, so anything around the words
+ * competes with them. An ASS file is markup by half: measured 2026-09-01 on
+ * `[HorribleSubs] Drifters - 03 [1080p].ass`, 5040 Latin characters of Aegisub
+ * headers, style and font names, `Format:`/`Dialogue:` field prefixes and
+ * `{\…}` override groups against 5983 Cyrillic characters of dialogue —
+ * `franc(the file) = eng`, `franc(the dialogue) = rus`. The proxy had already
+ * built the markup-free text and detected on the file anyway, so a Russian
+ * track was offered to the viewer as English.
+ *
+ * `detectLanguageFromVtt` below is the safe entry point for a whole document;
+ * this one is for text that is already only text.
+ *
+ * @param {string} text - Subtitle text with no markup left in it.
  * @returns {{ code: string, name: string } | null} Detected language, or null when uncertain.
  */
 export function detectLanguage(text) {
-  if (typeof text !== "string" || text.trim().length < 15) {
+  const words = normalise(text);
+  if (words.length < FRANC_FLOOR) {
+    return null;
+  }
+  const candidate = ask(words);
+  if (candidate === null) {
+    return null;
+  }
+  // Enough text to support THIS answer. The figure is the language's own,
+  // because the languages are not alike: Russian shares its trigrams with
+  // Bulgarian, Serbian and Ukrainian and needs several times what English does.
+  if (words.length < (LEAST_TEXT[candidate] ?? LEAST_TEXT_WORST)) {
     return null;
   }
-  // Restrict to plausible subtitle languages; require a little text.
-  const iso3 = franc(text, { only: ONLY, minLength: 15 });
-  if (iso3 === "und") {
+  // And an answer that does not survive losing half the text was an accident of
+  // where the text happened to stop, not a reading of it. Free — franc costs
+  // about 2 ms whatever the size, measured — and it needs no figure of its own,
+  // because the test is taken on the text in hand.
+  const middle = Math.floor(words.length / 2);
+  if (ask(words.slice(0, middle)) !== candidate || ask(words.slice(middle)) !== candidate) {
     return null;
   }
-  return LANG_3_TO_1[iso3] ?? null;
+  return LANG_3_TO_1[candidate] ?? null;
+}
+
+/**
+ * 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.
+ */
+export function 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.
+ */
+export function detectLanguageFromVtt(vtt) {
+  return detectLanguage(cueTextOfVtt(vtt));
 }

package/services/torrent-worker/subtitle-cues.js

@@ -20,6 +20,7 @@
 import { readSubtitlePlan, harvestCluster } from "../container-index/matroska-subtitles.js";
 import { decodeSubtitleSample, readMp4SubtitlePlan } from "../container-index/mp4-subtitles.js";
 import { iterateElements } from "../container-index/ebml-reader.js";
+import { detectLanguage } from "../language-detect.js";
 import { logger } from "../../utils/logger.js";
 
 /** Enough to read any cluster's own element header. */
@@ -483,12 +484,23 @@ export async function warmSubtitleCues(torrent, fileIndex, sourceKey) {
     }
     const highest = newCues.reduce((max, cue) => Math.max(max, Number(cue.seq) || 0), since);
     state.pushed.set(track.trackNumber, highest);
-    const cues = finalizeCues(newCues, held.track?.codecId ?? track.codecId);
+    const codecId = held.track?.codecId ?? track.codecId;
+    const cues = finalizeCues(newCues, codecId);
     fresh.push({
       // ffmpeg's own numbering, which is the only one the browser knows.
       trackIndex: Number.isInteger(track.declaredIndex) ? track.declaredIndex : order,
       cues,
       language: held.track?.language ?? "",
+      // What the CUES say the language is, re-read on every push over every cue
+      // held so far rather than over this batch. A track whose container states
+      // no language is unreadable at the start of a session — a handful of cues
+      // is not a sample of a language, and the detector refuses to answer on one
+      // — so the answer has to be re-taken as the film downloads, and the label
+      // moved when it arrives. Costs about 6 ms per push, measured; pushes
+      // arrive about once a second per file being read.
+      detectedLanguage: detectLanguage(
+        finalizeCues(held.cues, codecId).map((cue) => cue.text).join("\n")
+      ),
       // Where the browser should resume from if it has to ask again — after a
       // reconnect, which loses the subscription these pushes ride on.
       cursor: highest,

package/test/subtitle-language.test.js

@@ -0,0 +1,241 @@
+/**
+ * @file What the language detector is FED.
+ *
+ * Field 2026-09-01: a Russian subtitle file was offered to the viewer as
+ * `English (Stan WarHammer & Nesitach)`. The detector was not at fault — it was
+ * handed the raw `.ass` file, which is half Latin markup, while the markup-free
+ * WebVTT it was about to serve sat in the variable beside it. Measured on that
+ * file: 5040 Latin characters against 5983 Cyrillic, `franc(the file) = eng`,
+ * `franc(the dialogue) = rus`.
+ * `research/subtitle-language-ass-markup-2026-09-01.md`.
+ *
+ * These checks pin the input at each of the three places a language is read.
+ *
+ * **On the size of the fixtures.** franc's answer among the Cyrillic languages
+ * is not stable on a small sample: measured 2026-09-01 by growing one Russian
+ * text line by line, it answered `bul` at 129 characters, `srp` at 158, 241 and
+ * `bul` again at 292, then `rus` at every length from 337 to 881. So the
+ * dialogue here is ~880 Cyrillic characters — past that boundary by a factor of
+ * about 2.6, and still an order of magnitude below a real episode's 5983. The
+ * fixtures are NOT sized to make these checks pass; they are sized to resemble
+ * the thing. That instability is a separate defect and is recorded as one.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { cueTextOfVtt, detectLanguage, detectLanguageFromVtt } from "../services/language-detect.js";
+import { convertSubtitleToVtt } from "../services/subtitle-convert.js";
+import { finalizeCues } from "../services/torrent-worker/subtitle-cues.js";
+
+/** Varied Russian dialogue, the length a few minutes of an episode carries. */
+const RUSSIAN_DIALOGUE = [
+  "Ты видишь их?",
+  "Да.",
+  "Но не столько вижу, сколько чувствую.",
+  "Скорее всего, они будут здесь с минуты на минуту.",
+  "Почему господа октябристы решили напасть именно сейчас?",
+  "Им никогда не преодолеть эти стены.",
+  "Мы держали эту крепость три года и продержим ещё столько же.",
+  "Готовьте лучников на восточной стороне.",
+  "Если они подойдут ближе, мы откроем огонь без предупреждения.",
+  "Я не собираюсь умирать здесь, в этой богом забытой дыре.",
+  "Тогда возьми меч и вставай рядом со мной.",
+  "Сколько у нас осталось воды и хлеба?",
+  "На неделю, если не считать раненых.",
+  "Раненых считать придётся, они тоже люди.",
+  "Отправь гонца к южным воротам и передай приказ отступать.",
+  "Он не успеет, дорога перерезана ещё вчера вечером.",
+  "Значит пойду сам, а ты останешься за меня командовать.",
+  "Это безумие, и ты прекрасно об этом знаешь.",
+  "Безумие — это сидеть и ждать, пока нас перебьют по одному.",
+  "Хорошо. Но возьми с собой хотя бы двоих.",
+  "Двоих я возьму. Больше не могу себе позволить.",
+  "Береги себя. Мы будем держать стену до последнего.",
+  "Я знаю. Именно поэтому я и ухожу спокойно.",
+  "Смотри, дым над лесом. Они уже жгут деревни.",
+  "Тогда времени у нас меньше, чем мы думали."
+];
+
+/** `hh:mm:ss.cc` for the ASS `Start`/`End` fields. */
+function assTime(seconds) {
+  const mm = String(Math.floor(seconds / 60)).padStart(2, "0");
+  const ss = String(seconds % 60).padStart(2, "0");
+  return `0:${mm}:${ss}.00`;
+}
+
+/**
+ * An ASS file in the shape a fansub release ships: an Aegisub header, a styles
+ * section with English font and style names, and Russian dialogue carrying
+ * override groups. Modelled on the field file.
+ */
+const RUSSIAN_ASS = `[Script Info]
+Title: Default Aegisub file
+ScriptType: v4.00+
+PlayResX: 1280
+PlayResY: 720
+Original Translation: Nesitach
+Original Editing: Stan WarHammer
+WrapStyle: 0
+ScaledBorderAndShadow: no
+Video Aspect Ratio: c1.77778
+YCbCr Matrix: TV.601
+Aegisub Video Aspect Ratio: c1.777778
+
+[Aegisub Project Garbage]
+Last Style Storage: Default
+Audio File: [HorribleSubs] Drifters - 03 [720p].mkv
+Video File: [HorribleSubs] Drifters - 03 [720p].mkv
+Video AR Mode: 4
+Video AR Value: 1.777778
+Video Zoom Percent: 0.600000
+Scroll Position: 256
+Active Line: 257
+Video Position: 33159
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Default,Trebuchet MS,54,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2.5,1.5,2,20,20,25,1
+Style: Signs,Times New Roman,48,&H00FFFF00,&H000000FF,&H00202020,&H00000000,-1,0,0,0,100,100,0,0,1,2,1,8,20,20,20,1
+Style: Italics,Trebuchet MS Italic,54,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,-1,0,0,100,100,0,0,1,2.5,1.5,2,20,20,25,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+${RUSSIAN_DIALOGUE.map((line, index) => {
+    const style = index % 7 === 6 ? "Signs" : "Default";
+    const tag = index % 5 === 4 ? "{\\pos(640,620)}" : "";
+    return `Dialogue: 0,${assTime(index * 4)},${assTime(index * 4 + 3)},${style},,0,0,0,,${tag}${line}`;
+  }).join("\n")}
+`;
+
+test("a Russian .ass is reported as Russian, and its markup does not reach the detector", () => {
+  const vtt = convertSubtitleToVtt(RUSSIAN_ASS, ".ass");
+  assert.ok(vtt.startsWith("WEBVTT"), "the conversion produced a WebVTT document");
+
+  const spoken = cueTextOfVtt(vtt);
+  // Every one of these is a piece of the file the viewer never reads, and each
+  // was competing with the dialogue for the detector's answer.
+  for (const markup of [
+    "Aegisub", "Script Info", "V4+ Styles", "Format:", "Dialogue:",
+    "Trebuchet MS", "Times New Roman", "Default", "Signs", "pos(",
+    "-->", "0:00:12"
+  ]) {
+    assert.ok(!spoken.includes(markup), `cue text still carries "${markup}"`);
+  }
+  assert.ok(spoken.includes("Ты видишь их?"), "cue text keeps the dialogue");
+
+  assert.deepEqual(detectLanguageFromVtt(vtt), { code: "ru", name: "Russian" });
+});
+
+test("the fixture is the hard case: the file itself is nearly half Latin", () => {
+  // Not an assertion about franc — an assertion that this fixture reproduces the
+  // field file's proportions. A fixture whose markup were negligible would pass
+  // the check above with or without the fix.
+  const cyrillic = (RUSSIAN_ASS.match(/[Ѐ-ӿ]/gu) ?? []).length;
+  const latin = (RUSSIAN_ASS.match(/[A-Za-z]/g) ?? []).length;
+  assert.ok(cyrillic > 800, `too little dialogue: ${cyrillic} Cyrillic characters`);
+  assert.ok(latin > cyrillic * 0.5, `markup too small to reproduce the fault: ${latin} vs ${cyrillic}`);
+});
+
+test("cue identifiers, NOTE, STYLE and REGION blocks are not text", () => {
+  const vtt = [
+    "WEBVTT - This file has cues.",
+    "Kind: captions",
+    "Language: en",
+    "",
+    "NOTE",
+    "Translated by an English speaking volunteer, all rights reserved.",
+    "",
+    "STYLE",
+    "::cue { background-image: linear-gradient(to bottom, dimgray, lightgray); }",
+    "",
+    "REGION",
+    "id:speaker width:40% lines:3 regionanchor:0%,100%",
+    "",
+    "opening-line",
+    "00:00:12.060 --> 00:00:13.270 align:start position:0%",
+    "<v Тоёхиса>Ты видишь их?</v>",
+    "",
+    "2",
+    "00:00:15.400 --> 00:00:16.650",
+    "<i>Но не столько вижу,</i>",
+    "сколько чувствую &amp; ощущаю.",
+    ""
+  ].join("\n");
+
+  const spoken = cueTextOfVtt(vtt);
+  assert.equal(
+    spoken,
+    "Ты видишь их?\nНо не столько вижу,\nсколько чувствую   ощущаю."
+  );
+});
+
+test("a document with no cues yields no language rather than a guess", () => {
+  assert.equal(cueTextOfVtt("WEBVTT\n"), "");
+  assert.equal(detectLanguageFromVtt("WEBVTT\n"), null);
+  assert.equal(detectLanguageFromVtt(null), null);
+});
+
+test("an embedded ASS cue is read through finalizeCues, not raw", () => {
+  // What the cluster walk holds: the dialogue row without its `Dialogue:`
+  // header — nine comma-separated fields, then the text with override groups.
+  const cues = RUSSIAN_DIALOGUE.map((line, index) => ({
+    startSeconds: index * 4,
+    endSeconds: index * 4 + 3,
+    text: `0,${assTime(index * 4)},${assTime(index * 4 + 3)},Default,,0,0,0,,` +
+      `${index % 5 === 4 ? "{\\pos(640,620)}" : ""}${line}`
+  }));
+
+  const spoken = finalizeCues(cues, "S_TEXT/ASS").map((cue) => cue.text).join("\n");
+  assert.ok(!spoken.includes("Default"), "the style field survived into the text");
+  assert.ok(!spoken.includes("pos("), "an override group survived into the text");
+  assert.ok(!spoken.includes("0:00:12"), "a timestamp field survived into the text");
+  assert.deepEqual(detectLanguage(spoken), { code: "ru", name: "Russian" });
+});
+
+test("too little text is answered with nothing, not with a guess", () => {
+  // Measured 2026-09-02 (`research/franc-boundary-2026-09-02.md`): franc's
+  // answer for Russian walks between Bulgarian, Serbian and Russian until about
+  // 650 characters. Below that the honest answer is none — the browser then
+  // shows "Unknown", and the label moves when enough of the file has arrived.
+  const short = RUSSIAN_DIALOGUE.slice(0, 6).join("\n");
+  assert.ok(short.length < 300, `the fixture must be short: ${short.length}`);
+  assert.equal(detectLanguage(short), null);
+
+  const long = RUSSIAN_DIALOGUE.join("\n");
+  assert.ok(long.length > 650, `the fixture must be long enough: ${long.length}`);
+  assert.deepEqual(detectLanguage(long), { code: "ru", name: "Russian" });
+});
+
+test("an answer that does not survive losing half the text is not an answer", () => {
+  // A file carrying two languages — a bilingual release, or a track that turns
+  // into signs-only English partway. franc answers something for the whole; the
+  // halves disagree with it, and that disagreement is the text saying the
+  // answer rests on where it happened to be cut.
+  const english = [
+    "Do you see them out there beyond the wall?",
+    "I do, though not as clearly as I would like to.",
+    "They have been gathering since the morning came.",
+    "We should send word to the southern gate at once.",
+    "The road was cut yesterday and no rider will pass.",
+    "Then we hold what we have and wait for the dawn."
+  ].join("\n");
+  const mixed = `${RUSSIAN_DIALOGUE.slice(0, 13).join("\n")}\n${english}`;
+  assert.equal(detectLanguage(mixed), null);
+});
+
+test("a WebVTT body is decoded whole, so no character is cut in half", () => {
+  // The ffmpeg extraction path used to detect on `String(body.subarray(0, 4096))`.
+  // Two faults: a byte cut lands mid-character on any non-Latin track, and most
+  // of those bytes are timestamps rather than words. Cyrillic is two bytes per
+  // character in UTF-8, so 4096 bytes of this document is a few hundred
+  // characters of dialogue — inside the unstable region measured above.
+  const cues = RUSSIAN_DIALOGUE.map((line, index) => {
+    const start = `00:00:${String(index * 2).padStart(2, "0")}.000`;
+    const end = `00:00:${String(index * 2 + 1).padStart(2, "0")}.000`;
+    return `${start} --> ${end}\n${line}`;
+  });
+  const body = Buffer.from(`WEBVTT\n\n${cues.join("\n\n")}\n`, "utf8");
+
+  assert.deepEqual(detectLanguageFromVtt(body.toString("utf8")), { code: "ru", name: "Russian" });
+});

package/test/worker-channel.test.js

@@ -75,9 +75,17 @@ test("chunks arrive with their contents intact", async () => {
   const { port1, port2 } = new MessageChannel();
   try {
     const received = [];
+    // Waited on rather than slept through. This test used to sleep 50 ms and
+    // then assert, so it failed whenever the run was busy — recorded as flaky in
+    // roadmap items 53 and 54, and it failed again on 2026-09-02 for a reason
+    // that shows exactly how little a chosen interval is worth: the worker had
+    // gained one more module to load, and 50 ms stopped being enough.
+    let arrived;
+    const firstChunk = new Promise((resolve) => { arrived = resolve; });
     port2.on("message", (message) => {
       if (message?.type === "chunk") {
         received.push(Buffer.from(message.bytes));
+        arrived();
       }
     });
 
@@ -86,7 +94,7 @@ test("chunks arrive with their contents intact", async () => {
     await sender.send(piece);
     sender.end();
 
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await firstChunk;
     assert.equal(received.length, 1);
     assert.equal(received[0].length, 256 * 1024);
     assert.equal(received[0][0], 42);