@torrent-tv/proxy 2.88.3 → 2.88.4

package/services/media/tracks/audio-bound.js

@@ -0,0 +1,233 @@
+/**
+ * @file The most a soundtrack's codec allows it to carry, from what its
+ * container declares about it.
+ *
+ * A copied soundtrack is sent to the viewer as the file has it, so the most it
+ * can weigh on their link is a property of its CODEC as configured: a bound
+ * the stream is held to by its own specification, not an average a file
+ * happens to state. Only bounds confirmed against a published source are
+ * given, for exactly the configurations those sources describe; any other
+ * combination answers null, and the caller falls back to what the file states
+ * or to re-encoding the track. Sources, and why each other codec has none:
+ * `research/soundtrack-rate-bound-2026-10-01.md`.
+ *
+ * 1. AAC-LC (`audioObjectType` 2) with 1024-sample frames: at most 6144 bits
+ *    per channel in one frame, whatever the bit reservoir holds (ISO/IEC
+ *    14496-3 §4.5.3.1; Fraunhofer's FDK AAC encoder states the same: "For
+ *    AAC-LC, the bitrate is only limited by the maximum AAC frame length. It
+ *    is, regardless of the available bit reservoir, defined as 6144 bits per
+ *    channel"). One frame lasts 1024 / samplingFrequency seconds, so the rate
+ *    over any stretch of whole frames is at most
+ *    6144 x channels x samplingFrequency / 1024 bit/s. The channel count and
+ *    the sampling frequency are the ones the AudioSpecificConfig states — for
+ *    a stream with implicit SBR that is the core's, which is what one frame
+ *    lasts. The count includes an LFE channel the buffer rule does not, so the
+ *    bound errs high.
+ * 2. AC-3: the largest syncframe ATSC A/52:2018 Table 5.18 allows at each
+ *    sampling frequency (`frmsizecod` 37), over the 1536 samples it carries.
+ *    That is 640 kbit/s at 32 and 48 kHz and 640.369 kbit/s at 44.1 kHz, whose
+ *    frames alternate in length; with the frequency unknown the largest of the
+ *    three is the bound.
+ *
+ * PURE: plain values in, plain values out. No container, no torrent.
+ */
+
+/** ISO/IEC 14496-3 Table 1.18: samplingFrequencyIndex to Hz. 0xF is explicit. */
+const AAC_SAMPLING_FREQUENCIES = Object.freeze([
+  96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350
+]);
+
+/** ISO/IEC 14496-3 Table 1.19: channelConfiguration to channels; 0 is a PCE. */
+const AAC_CHANNELS = Object.freeze([null, 1, 2, 3, 4, 5, 6, 8]);
+
+/** The AAC-LC object type, and the one frame length the bound is stated for. */
+const AAC_LC = 2;
+const AAC_LC_FRAME_LENGTH = 1024;
+const AAC_MAX_BITS_PER_CHANNEL_FRAME = 6144;
+
+/**
+ * ATSC A/52:2018 Table 5.18, `frmsizecod` 37 (640 kbps nominal): 16-bit words
+ * in the largest syncframe at each sampling frequency. A syncframe carries
+ * 1536 samples (§5.1).
+ */
+const AC3_LARGEST_WORDS = Object.freeze(new Map([[48000, 1280], [44100, 1394], [32000, 1920]]));
+const AC3_SAMPLES_PER_FRAME = 1536;
+
+/**
+ * @typedef {object} CodecParameters
+ * @property {string} codec - The ffmpeg-side name: "aac", "ac3", ...
+ * @property {number | null} objectType - AAC `audioObjectType`.
+ * @property {number | null} frameLength - Samples per frame.
+ * @property {number | null} channels
+ * @property {number | null} sampleRate - Hz.
+ */
+
+/**
+ * A minimal MSB-first bit reader over a buffer.
+ *
+ * @param {Buffer} bytes
+ */
+function bitReader(bytes) {
+  let position = 0;
+  return {
+    read(count) {
+      let value = 0;
+      for (let i = 0; i < count; i += 1) {
+        const byte = bytes[position >> 3];
+        if (byte === undefined) {
+          throw new RangeError("AudioSpecificConfig ended early");
+        }
+        value = (value * 2) + ((byte >> (7 - (position & 7))) & 1);
+        position += 1;
+      }
+      return value;
+    }
+  };
+}
+
+/**
+ * The fields of an AudioSpecificConfig the bound is computed from (ISO/IEC
+ * 14496-3 §1.6.2.1 and the GASpecificConfig that follows it for AAC-LC).
+ *
+ * @param {Buffer | null} bytes
+ * @returns {{ objectType: number, sampleRate: number | null, channels: number | null, frameLength: number | null } | null}
+ *   Null when the bytes are not a readable config.
+ */
+export function parseAudioSpecificConfig(bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.length < 2) {
+    return null;
+  }
+  try {
+    const bits = bitReader(bytes);
+    let objectType = bits.read(5);
+    if (objectType === 31) {
+      objectType = 32 + bits.read(6);
+    }
+    const frequencyIndex = bits.read(4);
+    const sampleRate = frequencyIndex === 0xf
+      ? bits.read(24)
+      : (AAC_SAMPLING_FREQUENCIES[frequencyIndex] ?? null);
+    const channelConfiguration = bits.read(4);
+    const channels = AAC_CHANNELS[channelConfiguration] ?? null;
+    // GASpecificConfig begins with frameLengthFlag for the object types that
+    // carry one; for any other the frame length is not read here.
+    const frameLength = objectType === AAC_LC
+      ? (bits.read(1) === 1 ? 960 : AAC_LC_FRAME_LENGTH)
+      : null;
+    return { objectType, sampleRate: sampleRate > 0 ? sampleRate : null, channels, frameLength };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What a container declares about one soundtrack's codec configuration, as
+ * plain values.
+ *
+ * For AAC the AudioSpecificConfig is the statement, and the container's own
+ * channel count and frequency are not used in its place: for HE-AAC the
+ * container may state the output frequency while a frame lasts the core's.
+ *
+ * @param {object} params
+ * @param {string} params.codec - The ffmpeg-side name.
+ * @param {string} [params.codecPrivateB64] - The AudioSpecificConfig for AAC.
+ * @param {number | null} [params.channels] - As the container states it.
+ * @param {number | null} [params.samplingFrequency] - As the container states it.
+ * @returns {CodecParameters | null} Null when nothing names the codec.
+ */
+export function codecParametersOf({ codec, codecPrivateB64 = "", channels = null, samplingFrequency = null }) {
+  const name = typeof codec === "string" ? codec.trim().toLowerCase() : "";
+  if (!name) {
+    return null;
+  }
+  if (name === "aac") {
+    const config = typeof codecPrivateB64 === "string" && codecPrivateB64.length > 0
+      ? parseAudioSpecificConfig(Buffer.from(codecPrivateB64, "base64"))
+      : null;
+    return {
+      codec: name,
+      objectType: config?.objectType ?? null,
+      frameLength: config?.frameLength ?? null,
+      channels: config?.channels ?? null,
+      sampleRate: config?.sampleRate ?? null
+    };
+  }
+  return {
+    codec: name,
+    objectType: null,
+    frameLength: null,
+    channels: Number.isFinite(channels) && channels > 0 ? channels : null,
+    sampleRate: Number.isFinite(samplingFrequency) && samplingFrequency > 0 ? samplingFrequency : null
+  };
+}
+
+/**
+ * Whether a set of parameters holds everything the bound for its codec is
+ * computed from. A set that is complete can replace another whole; one that is
+ * not adds nothing to a set already known.
+ *
+ * @param {CodecParameters | null} params
+ * @returns {boolean}
+ */
+export function codecParametersComplete(params) {
+  if (!params?.codec) {
+    return false;
+  }
+  if (params.codec === "aac") {
+    return [params.objectType, params.frameLength, params.channels, params.sampleRate]
+      .every((value) => Number.isFinite(value) && value > 0);
+  }
+  // Every other codec's bound — where it has one — needs no more than its name.
+  return true;
+}
+
+/**
+ * Whether two sets contradict each other: a field both state, stated
+ * differently.
+ *
+ * @param {CodecParameters | null} left
+ * @param {CodecParameters | null} right
+ * @returns {boolean}
+ */
+export function codecParametersConflict(left, right) {
+  if (!left || !right) {
+    return false;
+  }
+  return ["codec", "objectType", "frameLength", "channels", "sampleRate"].some(
+    (field) => left[field] !== null && left[field] !== undefined &&
+      right[field] !== null && right[field] !== undefined &&
+      left[field] !== right[field]
+  );
+}
+
+/**
+ * The confirmed bound for these parameters, in kbit/s, or null.
+ *
+ * @param {CodecParameters | null} params
+ * @returns {number | null}
+ */
+export function peakKbpsOf(params) {
+  if (!params?.codec) {
+    return null;
+  }
+  if (params.codec === "aac") {
+    if (
+      params.objectType !== AAC_LC ||
+      params.frameLength !== AAC_LC_FRAME_LENGTH ||
+      !(params.channels > 0) ||
+      !(params.sampleRate > 0)
+    ) {
+      return null;
+    }
+    return (AAC_MAX_BITS_PER_CHANNEL_FRAME * params.channels * params.sampleRate) / AAC_LC_FRAME_LENGTH / 1000;
+  }
+  if (params.codec === "ac3") {
+    const rateOf = (sampleRate, words) => (words * 16 * sampleRate) / AC3_SAMPLES_PER_FRAME / 1000;
+    const words = AC3_LARGEST_WORDS.get(params.sampleRate);
+    if (words !== undefined) {
+      return rateOf(params.sampleRate, words);
+    }
+    return Math.max(...[...AC3_LARGEST_WORDS].map(([sampleRate, largest]) => rateOf(sampleRate, largest)));
+  }
+  return null;
+}

package/services/media/tracks/index.js

@@ -1,15 +1,15 @@
-// Only what is imported through this file, which is the one type five other
-// modules name in their JSDoc. Every class beside it — `VideoTrack`,
-// `AudioTrack`, `SubtitleTrack`, `TextSubtitleTrack`, `ImageSubtitleTrack` —
-// and the tables `TEXT_CODECS_MATROSKA`, `TEXT_FORMATS_MP4` and `MarkupKind`
-// were re-exported here and taken by nobody: whoever needs one imports the
-// module that declares it.
-export { ContainerTrack } from "./ContainerTrack.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.
+// Only what is imported through this file, which is the one type five other
+// modules name in their JSDoc. Every class beside it — `VideoTrack`,
+// `AudioTrack`, `SubtitleTrack`, `TextSubtitleTrack`, `ImageSubtitleTrack` —
+// and the tables `TEXT_CODECS_MATROSKA`, `TEXT_FORMATS_MP4` and `MarkupKind`
+// were re-exported here and taken by nobody: whoever needs one imports the
+// module that declares it.
+export { ContainerTrack } from "./ContainerTrack.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/services/media/tracks/language-detect.js

@@ -1,174 +1,174 @@
-/**
- * @file Content-based subtitle language detection (proxy side).
- *
- * Uses `franc` (n-gram / trigram frequency against per-language reference
- * profiles — MIT). Runs on the proxy where the full subtitle text and
- * node_modules live, so no detection model ships to the browser. Detection is
- * restricted to a curated set of plausible subtitle languages via franc's
- * `only` option: this both maps ISO 639-3 → ISO 639-1 + English name and
- * avoids exotic false positives on short text (e.g. English mis-detected as
- * Scots). Returns null when franc is not confident (too little text, or
- * undetermined).
- */
-
-import { franc } from "franc";
-
-/** ISO 639-3 (franc output) → { code: ISO 639-1 / BCP-47, name }. Curated allowlist. */
-const LANG_3_TO_1 = {
-  eng: { code: "en", name: "English" },
-  rus: { code: "ru", name: "Russian" },
-  ukr: { code: "uk", name: "Ukrainian" },
-  bel: { code: "be", name: "Belarusian" },
-  jpn: { code: "ja", name: "Japanese" },
-  kor: { code: "ko", name: "Korean" },
-  cmn: { code: "zh", name: "Chinese" },
-  spa: { code: "es", name: "Spanish" },
-  fra: { code: "fr", name: "French" },
-  deu: { code: "de", name: "German" },
-  ita: { code: "it", name: "Italian" },
-  por: { code: "pt", name: "Portuguese" },
-  pol: { code: "pl", name: "Polish" },
-  nld: { code: "nl", name: "Dutch" },
-  arb: { code: "ar", name: "Arabic" },
-  tur: { code: "tr", name: "Turkish" },
-  vie: { code: "vi", name: "Vietnamese" },
-  tha: { code: "th", name: "Thai" },
-  hin: { code: "hi", name: "Hindi" },
-  ind: { code: "id", name: "Indonesian" },
-  zlm: { code: "ms", name: "Malay" },
-  ces: { code: "cs", name: "Czech" },
-  slk: { code: "sk", name: "Slovak" },
-  ron: { code: "ro", name: "Romanian" },
-  hun: { code: "hu", name: "Hungarian" },
-  srp: { code: "sr", name: "Serbian" },
-  hrv: { code: "hr", name: "Croatian" },
-  bul: { code: "bg", name: "Bulgarian" },
-  ell: { code: "el", name: "Greek" },
-  heb: { code: "he", name: "Hebrew" },
-  dan: { code: "da", name: "Danish" },
-  fin: { code: "fi", name: "Finnish" },
-  nob: { code: "no", name: "Norwegian" },
-  swe: { code: "sv", name: "Swedish" },
-  fas: { code: "fa", name: "Persian" }
-};
-
-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.
- *
- * **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) {
-  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;
-  }
-  // 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[candidate] ?? null;
-}
+/**
+ * @file Content-based subtitle language detection (proxy side).
+ *
+ * Uses `franc` (n-gram / trigram frequency against per-language reference
+ * profiles — MIT). Runs on the proxy where the full subtitle text and
+ * node_modules live, so no detection model ships to the browser. Detection is
+ * restricted to a curated set of plausible subtitle languages via franc's
+ * `only` option: this both maps ISO 639-3 → ISO 639-1 + English name and
+ * avoids exotic false positives on short text (e.g. English mis-detected as
+ * Scots). Returns null when franc is not confident (too little text, or
+ * undetermined).
+ */
+
+import { franc } from "franc";
+
+/** ISO 639-3 (franc output) → { code: ISO 639-1 / BCP-47, name }. Curated allowlist. */
+const LANG_3_TO_1 = {
+  eng: { code: "en", name: "English" },
+  rus: { code: "ru", name: "Russian" },
+  ukr: { code: "uk", name: "Ukrainian" },
+  bel: { code: "be", name: "Belarusian" },
+  jpn: { code: "ja", name: "Japanese" },
+  kor: { code: "ko", name: "Korean" },
+  cmn: { code: "zh", name: "Chinese" },
+  spa: { code: "es", name: "Spanish" },
+  fra: { code: "fr", name: "French" },
+  deu: { code: "de", name: "German" },
+  ita: { code: "it", name: "Italian" },
+  por: { code: "pt", name: "Portuguese" },
+  pol: { code: "pl", name: "Polish" },
+  nld: { code: "nl", name: "Dutch" },
+  arb: { code: "ar", name: "Arabic" },
+  tur: { code: "tr", name: "Turkish" },
+  vie: { code: "vi", name: "Vietnamese" },
+  tha: { code: "th", name: "Thai" },
+  hin: { code: "hi", name: "Hindi" },
+  ind: { code: "id", name: "Indonesian" },
+  zlm: { code: "ms", name: "Malay" },
+  ces: { code: "cs", name: "Czech" },
+  slk: { code: "sk", name: "Slovak" },
+  ron: { code: "ro", name: "Romanian" },
+  hun: { code: "hu", name: "Hungarian" },
+  srp: { code: "sr", name: "Serbian" },
+  hrv: { code: "hr", name: "Croatian" },
+  bul: { code: "bg", name: "Bulgarian" },
+  ell: { code: "el", name: "Greek" },
+  heb: { code: "he", name: "Hebrew" },
+  dan: { code: "da", name: "Danish" },
+  fin: { code: "fi", name: "Finnish" },
+  nob: { code: "no", name: "Norwegian" },
+  swe: { code: "sv", name: "Swedish" },
+  fas: { code: "fa", name: "Persian" }
+};
+
+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.
+ *
+ * **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) {
+  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;
+  }
+  // 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[candidate] ?? null;
+}