@torrent-tv/proxy 2.71.1 → 2.72.1

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 2.72.1
+
+- **Fix**: Subtitles on an embedded ASS track were shown to the viewer as the whole dialogue row — `21,0,Default,,0000,0000,0000,,I am the powerful Demon King of the Sixth Heaven.` — because one function both unwrapped the container's framing and stripped the codec's markup, and decided which framing it held by counting commas. Matroska writes eight fields before the text and takes the two timing fields out into the block's own timestamp (`matroska.org/technical/subtitles.html`); a row in a `.ass` FILE has nine and states its own column order in `[Events]`. The function expected the file's shape, found nine fields where it wanted more than nine, and returned the row untouched. The test that covered this passed because its fixture carried the file's two timestamps — a shape that never occurs on that path.
+- **New**: `Container.cueTextOf` — each container answers for its own framing, because how a cue's bytes are wrapped is stated by the container's specification and not by the subtitle format's. `MatroskaContainer` carries the eight-field rule with the quotation it comes from, `Mp4Container` the length-prefixed sample, and `AviContainer` throws rather than guessing at somebody else's framing. The unwrapping now happens where the cue is READ, which is the only place the container is known.
+- **New**: `SubtitleFileContainer` — a file of subtitles is a container of its own. It reads the `Format:` line of `[Events]` for ASS, which is where a FILE states its field order, and SubRip's positional form; `.vtt` is passed through unparsed, since taking it apart to write it back would drop its styles, regions and cue identifiers for nothing.
+- **New**: `services/tracks/subtitle-markup.js` — the other axis: `{\pos(…)}`, `\N`, `\n`, `\h`, the same wherever ASS is stored. One table for every name a codec has — Matroska CodecID, MP4 sample entry, file extension — because the answer for all of them is the same. `\h` reached the viewer as a backslash and an h on embedded tracks until now; the file path had always handled it.
+- **Chore**: `finalizeCues` and the WebVTT writing move to `subtitle-convert.js` and exist once. The writer was duplicated between the controller and the file conversion, so a pushed cue and a pulled one were formatted by two different pieces of code.
+- **Chore**: `test/subtitle-cue-framing.test.js`, 17 checks across both axes; three of them fail on the old code, including the field case itself and "one line of dialogue, two framings, one result". Measurements and the spec quotations: `research/subtitle-cue-framing-2026-09-03.md`.
+
+- **Fix**: A file's NAME was being read as proof that a segment exists. The `segment` muxer creates its output the moment it OPENS it, so a run killed for a seek leaves a file of zero bytes behind whose name is indistinguishable from a finished piece's — measured 2026-09-03: ffmpeg exited 19 ms after SIGTERM leaving `segment-00025.mp4` empty, and that empty file closed the only hole in the numbering. The two sides of the session then deadlocked on it without either being able to see the other's reason: the look-ahead read `420s ahead of the viewer` and kept the encoder stopped because the segment was on disk, while the serving path refused the very same file for carrying no track. Both sides now ask `usableSegmentIndices`, where a number counts only when some run holds a NON-EMPTY copy of it — which is exactly the condition under which the serving path can answer.
+- **Fix**: The piece a run had open when it ended is removed once that run's process is gone, and only when it is unusable — a run stopped between two cuts leaves a finished file, and deleting good output would mean encoding it a second time. The current run's own unfinished piece is waited for, never deleted.
+- **Fix**: A segment is served from the newest copy that carries every track, across every run the session has had, instead of from whichever run wrote the name last. Where nothing can judge the copies — before the session has an init segment there is nothing to compare a piece against — the newest copy with bytes in it stands, and a piece that no run holds servably is still handed back so the readiness path can say WHY rather than answering "not produced".
+- **Fix**: Two more places asked a file's name where they meant its contents. That a segment is finished is proved by the NEXT one existing, and the proof was taken from whichever run happened to hold that number — a run that has ended closed everything it wrote and needs no such proof, so the evidence now has to come from the same run. And the session's header is derived from the first piece that has bytes in it rather than the first name, since an empty file skips a number whose header is sitting in the run before it.
+- **Chore**: Segment sizes are asked of the filesystem once per file. A piece that has bytes never loses them and a run rewriting a number writes into its own directory, so without that memory every request walked every segment of every run — 1350 of them for a 90-minute film — on the thread that also carries the data channel.
+- **Chore**: `test/produced-copy-choice.test.js`, 9 checks: an empty file is not counted by the look-ahead, a killed run leaves nothing behind, a run that finished its last piece keeps it, a last piece short of a track goes even though it has bytes, and the sizes are read once.
+
+## 2.72.0
+
+- **Fix**: The proxy was killed by the machine's out-of-memory killer at 4.37 GB, twenty minutes after 2.71.0 went out, and the cause was 2.71.0's own budget. A piece being written out to disk leaves the store's count of what it holds the moment the eviction begins, while its memory stays held until the write — which reads from that very block — has finished. The allowance counted resident pieces, so a block held by a pending write was counted nowhere: every admission turned one resident block into one held by the disk and took a fresh block for the arrival, and memory in use rose by one block per admission for as long as the disk was behind. It was behind by a factor of two: 233 evictions started against about 119 writes completed in the same minute. The store reported 203 blocks held with THREE pieces resident against 68 MB allowed. The allowance now bounds blocks in use — resident, reserved, and held by writes that have not finished — so a full store waits for the disk instead of evicting another piece, using the wait and the wake that were already there.
+- **Fix**: And the reason there were so many evictions: 2.71.0 made the allowance equal to what the readers ask for, exactly. `6 reader(s) want 23 piece(s) of 23 the store may hold` — no free place ever exists, so every arriving piece must evict a wanted one. The allowance now includes room for what arrives while one write is finishing, measured from the store's own median write duration and its own arrival rate, and zero until both have been seen rather than invented in advance.
+- **Chore**: `test/piece-store-slow-disk.test.js` drives a disk that answers only when the test says so, which is the field condition — writes slower than arrivals — and it fails without the fix. The check that shipped with the first attempt at this did not: it passed with the defect in place, which is worth recording, because a test that cannot fail proves nothing.
+
+- **Fix**: A proxy reported how much memory it had free with `os.freemem()`, and on Linux that counts only the pages free at this instant — the kernel keeps that number low on purpose and fills the rest with cache, which it hands back the moment anything asks. A host with 4 GB of cache and 200 MB genuinely free called itself nearly full while it had 4.2 GB to give. That figure weighs 0.4 of every proxy's score, so every Linux proxy in the pool understated itself, each by a different amount according to how much cache it happened to hold. It reads `MemAvailable` now — the same fix the piece store's budget got on 2026-08-27, which had stayed in this file until today.
+- **New**: A proxy can answer whether it could sustain a file it is only told ABOUT. The expensive half of that question is finding out what the file IS — add the torrent, wait for metadata, fetch the header, run ffmpeg — and it has already been paid by whichever proxy probed it. Its answer is a handful of numbers; every other proxy answers by arithmetic against its own startup benchmarks in milliseconds, without adding the torrent or fetching a byte. Asked over the tunnel as `can-serve-request`.
+- **New**: The refusal added in 2.71.1 now carries that description, so a viewer whose proxy cannot keep up is moved to one that can instead of being shown an error. A viewer is given a proxy BEFORE the file is known, by a score that reads processor load, free memory and round-trip time — none of which can answer a question about a particular source — and this is where that ordering is repaired, after the fact and only when it went wrong.
+
 ## 2.71.1
 
 - **Fix**: A reader stated the same thing twice — `protectRange` to the piece store for memory, and a window to the torrent for download — and the two were separate lists that could drift. There is one statement now: `SwarmSelection.reconcile` derives both views from the register, so the swarm and the store are told what to do from the same words. Only the urgent levels reach memory: it holds what will be READ soon, and protecting the speculative tail would push out a piece the decoder is about to want.

package/bin/cli.js

@@ -476,6 +476,14 @@ try {
     onHealthRequest() {
       return collectHealthMetrics();
     },
+    // Whether this host could sustain a file it has only been told about. The
+    // same arithmetic the first offer uses, against this host's own startup
+    // benchmarks — no torrent, no bytes, no ffmpeg — so the browser can ask
+    // every proxy in the pool and be sent to one that will work instead of
+    // being shown an error on the one it happened to land on.
+    onCanServeRequest(mediaInfo) {
+      return started?.hlsSessionManager?.predictOfferedHeights?.(mediaInfo) ?? null;
+    },
     onConnect() {
       // Re-register on every tunnel connect/reconnect so the server's
       // in-memory store stays consistent after server restarts.

package/package.json

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

package/server.js

@@ -318,6 +318,10 @@ export async function startProxyServer({
   return {
     app,
     port: selectedPort,
+    // Asked over the tunnel when the proxy a viewer landed on has refused their
+    // file: could THIS host sustain it? Answered from the startup benchmarks
+    // and a description, so it needs no torrent and costs milliseconds.
+    hlsSessionManager,
     // The browser only ever knows a source by its REGISTRY key (a hash of the
     // raw request bytes, scoped to one API session) — never the torrent
     // pool's own key (the content's infohash, shared across a magnet and a

package/services/container/Container.js

@@ -56,4 +56,39 @@ export class Container {
    * Subtitle-specific: where cues live (Matroska cluster positions or MP4 sample ranges).
    * Returned via track objects' clusterPositions/samples, so base has no extra method — tracks carry it.
    */
+
+  /**
+   * The TEXT FIELD of one subtitle cue, taken out of this container's framing.
+   *
+   * How a cue's bytes are wrapped is stated by the container's own
+   * specification, so each subclass answers for itself: Matroska reorders an ASS
+   * dialogue row, drops its two timing fields and prepends a read order
+   * (`matroska.org/technical/subtitles.html`); an MP4 prefixes a `tx3g` sample
+   * with its length (ISO/IEC 14496-12 §12.6); a subtitle FILE states its own
+   * field order in `[Events]`. None of that is a fact about the subtitle format,
+   * and the format's own markup — `{\pos(…)}`, `\N` — is not a fact about the
+   * container. The second half is `tracks/subtitle-markup.js`; this is the
+   * first, and the two are applied in that order.
+   *
+   * Static because de-framing reads no instance state: a caller that has bytes
+   * and knows the format needs no container built over the whole file. The
+   * instance form below exists so a caller that DOES hold a container gets the
+   * right answer without naming the subclass.
+   *
+   * @param {Buffer} _payload - The cue's bytes as the container stores them.
+   * @param {string} _codecId - CodecID / sample entry type / file extension.
+   * @returns {string} The text field, markup still in place.
+   */
+  static cueTextOf(_payload, _codecId) {
+    throw new Error("cueTextOf not implemented");
+  }
+
+  /**
+   * @param {Buffer} payload
+   * @param {string} codecId
+   * @returns {string}
+   */
+  cueTextOf(payload, codecId) {
+    return /** @type {typeof Container} */ (this.constructor).cueTextOf(payload, codecId);
+  }
 }

package/services/container/MatroskaContainer.js

@@ -50,6 +50,12 @@ const ID_DISPLAY_WIDTH = 0x54b0;
 const ID_DISPLAY_HEIGHT = 0x54ba;
 const ID_SAMPLING_FREQUENCY = 0xb5;
 const ID_CHANNELS = 0x9f;
+/**
+ * ReadOrder, Layer, Style, Name, MarginL, MarginR, MarginV, Effect — the eight
+ * fields Matroska writes before the text of an SSA/ASS event. See
+ * {@link MatroskaContainer.cueTextOf} for the quotation this comes from.
+ */
+const ASS_FIELDS_BEFORE_TEXT = 8;
 
 function readString(buf, el) {
   return buf.toString("utf8", el.dataOffset, el.dataOffset + el.size).replace(/\0+$/, "");
@@ -280,6 +286,42 @@ export class MatroskaContainer extends Container {
     return result;
   }
 
+  /**
+   * The text field of one cue as Matroska frames it.
+   *
+   * Two rules, both from `matroska.org/technical/subtitles.html`, "Now, how are
+   * they stored in Matroska?":
+   *
+   * 1. "All text is converted to UTF-8", so the block is decoded as UTF-8 and
+   *    no other encoding is guessed at. A subtitle FILE is a different matter —
+   *    there the bytes may be Windows-1251 and `decodeSubtitleBytes` sniffs for
+   *    it — but a muxer had to convert before writing the block.
+   * 2. "Events are stored in the Block in this order: ReadOrder, Layer, Style,
+   *    Name, MarginL, MarginR, MarginV, Effect, Text", and "Start & End field
+   *    are used to set TimeStamp and the BlockDuration element". So eight fields
+   *    stand before the text, the two timing fields of the file's own row are
+   *    NOT among them, and a read order takes their place at the front. The text
+   *    itself may hold commas, so everything from the ninth field on is joined
+   *    back together.
+   *
+   * `S_TEXT/UTF8` and `S_TEXT/WEBVTT` have no such framing: the block holds the
+   * cue text and nothing else. (A WebVTT cue's settings, identifier and
+   * preceding comments live in a BlockAddition, which this proxy does not read;
+   * losing them costs positioning, not words.)
+   *
+   * @param {Buffer} payload - The block's own bytes.
+   * @param {string} codecId - Matroska CodecID of the track the block belongs to.
+   * @returns {string}
+   */
+  static cueTextOf(payload, codecId) {
+    const text = Buffer.isBuffer(payload) ? payload.toString("utf8") : String(payload ?? "");
+    if (codecId !== "S_TEXT/ASS" && codecId !== "S_TEXT/SSA") {
+      return text;
+    }
+    const fields = text.split(",");
+    return fields.length > ASS_FIELDS_BEFORE_TEXT ? fields.slice(ASS_FIELDS_BEFORE_TEXT).join(",") : "";
+  }
+
   async readKeyframeIndex() {
     const times = await readMatroskaKeyframeTimes(this.readRange, this.fileSize);
     if (!times) return null;

package/services/container/Mp4Container.js

@@ -16,7 +16,7 @@
 
 import { Container } from "./Container.js";
 import { isMp4, readMp4KeyframeTimes } from "../container-index/mp4.js";
-import { readMp4SubtitlePlan } from "../container-index/mp4-subtitles.js";
+import { decodeSubtitleSample, readMp4SubtitlePlan } from "../container-index/mp4-subtitles.js";
 import { VideoTrack } from "../tracks/VideoTrack.js";
 import { AudioTrack } from "../tracks/AudioTrack.js";
 import { TextSubtitleTrack, TEXT_FORMATS_MP4 } from "../tracks/TextSubtitleTrack.js";
@@ -233,6 +233,27 @@ export class Mp4Container extends Container {
     return result;
   }
 
+  /**
+   * The text field of one cue as MP4 frames it.
+   *
+   * A `tx3g`/`text` sample is a 16-bit big-endian length followed by that many
+   * bytes of UTF-8 (ISO/IEC 14496-12 §12.6.3 and Apple's text sample format); a
+   * `wvtt` sample is a sequence of boxes whose `vttc`/`payl` holds the cue text
+   * (§12.6.3.2). Neither carries the subtitle format's own markup, so the
+   * markup step that follows has nothing to take off — it is applied all the
+   * same, because which step applies is decided by the codec and not here.
+   *
+   * The byte reading itself stays in `container-index/mp4-subtitles.js`,
+   * alongside the sample-table walk that found the range.
+   *
+   * @param {Buffer} payload - The sample's own bytes.
+   * @param {string} codecId - Sample entry type: `tx3g`, `text` or `wvtt`.
+   * @returns {string}
+   */
+  static cueTextOf(payload, codecId) {
+    return decodeSubtitleSample(payload, codecId);
+  }
+
   async readKeyframeIndex() {
     const r = await readMp4KeyframeTimes(this.readRange, this.fileSize);
     if (!r) return null;

package/services/container/SubtitleFileContainer.js

@@ -0,0 +1,261 @@
+/**
+ * @file A file of subtitles as a container of its own — `.srt`, `.ass`, `.ssa`,
+ * `.vtt` shipped beside the film.
+ *
+ * It belongs in this folder for the same reason `.mka` does: "a file of its
+ * own" is not a KIND of track, only the answer to where a track's bytes are,
+ * and the question this folder answers is how a format frames what it carries.
+ * SubRip frames a cue as an ordinal, a timing line and the lines under it; ASS
+ * frames one as a `Dialogue:` row whose FIELD ORDER the file itself states in
+ * `[Events]`; WebVTT is already what a browser reads.
+ *
+ * That last point about ASS is what makes the file different from Matroska and
+ * the reason both need their own answer. Matroska fixes the order in its own
+ * specification, so eight fields always stand before the text. A file does not:
+ * `Format:` may list the columns in any order, and the specification is that
+ * the reader obeys it. Two framings of one subtitle format, each stated by
+ * whoever stores it.
+ *
+ * What this file does NOT do is take off ASS's own markup — `{\pos(…)}`, `\N`,
+ * `\h`. That is the same wherever ASS is stored and lives in
+ * `tracks/subtitle-markup.js`.
+ */
+
+import { Container } from "./Container.js";
+import { TextSubtitleTrack } from "../tracks/TextSubtitleTrack.js";
+
+/** The extensions this reads. `.vtt` is included and passes through unparsed. */
+const EXTENSIONS = new Set([".srt", ".ass", ".ssa", ".vtt", ".webvtt"]);
+
+/**
+ * A SubRip timing line. The specification writes a comma before the
+ * milliseconds; WebVTT writes a dot, which is the only difference between the
+ * two lines.
+ */
+const SRT_TIMING = /^(\d{1,2}):(\d{2}):(\d{2})[,.](\d{1,3})\s*-->\s*(\d{1,2}):(\d{2}):(\d{2})[,.](\d{1,3})/;
+
+/** An ASS timing field: `h:mm:ss.cc`, centiseconds. */
+const ASS_TIMING = /^(\d+):(\d{2}):(\d{2})\.(\d{1,2})$/;
+
+/**
+ * Seconds from a SubRip timing line's four captured parts.
+ *
+ * @param {string[]} parts - [hours, minutes, seconds, fraction]
+ * @returns {number}
+ */
+function srtSeconds([hours, minutes, seconds, fraction]) {
+  const ms = Number(String(fraction).padEnd(3, "0"));
+  return Number(hours) * 3600 + Number(minutes) * 60 + Number(seconds) + ms / 1000;
+}
+
+/**
+ * Seconds from an ASS timing field.
+ *
+ * @param {string} field
+ * @returns {number | null} Null when the field is not a timing at all, which is
+ *   a malformed row and not a cue at zero.
+ */
+function assSeconds(field) {
+  const match = ASS_TIMING.exec(String(field ?? "").trim());
+  if (!match) {
+    return null;
+  }
+  const centiseconds = Number(String(match[4]).padEnd(2, "0"));
+  return Number(match[1]) * 3600 + Number(match[2]) * 60 + Number(match[3]) + centiseconds / 100;
+}
+
+export class SubtitleFileContainer extends Container {
+  /**
+   * @param {object} params
+   * @param {string} params.extension - Lowercase, including the dot.
+   * @param {string} [params.label]
+   */
+  constructor({ extension, label = "" }) {
+    // A subtitle file is read whole — it is kilobytes — so there is no range
+    // reading and no size to bound it by. `readTracks` and `readCues` take the
+    // decoded text directly, which is why the base's `readRange` is unused.
+    super({ readRange: null, fileSize: 0, label });
+    this.extension = String(extension ?? "").toLowerCase();
+    /** Column order from `[Events]`'s `Format:`, once a file has been read. */
+    this.eventColumns = null;
+  }
+
+  get formatName() {
+    return "subtitle-file";
+  }
+
+  /**
+   * @param {string} extension - Lowercase, including the dot.
+   * @returns {boolean}
+   */
+  static detect(extension) {
+    return EXTENSIONS.has(String(extension ?? "").toLowerCase());
+  }
+
+  /**
+   * The single track a subtitle file carries.
+   *
+   * Its `codecId` is the extension, which is the only thing the file says about
+   * its own format, and `subtitle-markup.js` accepts extensions alongside
+   * container codec names for exactly this reason.
+   *
+   * @returns {Promise<TextSubtitleTrack[]>}
+   */
+  async readTracks() {
+    return [new TextSubtitleTrack({
+      trackNumber: 0,
+      declaredIndex: 0,
+      codecId: this.extension,
+      language: "",
+      languageBcp47: "",
+      name: this.label,
+      isEnabled: true,
+      isDefault: false,
+      declaresDefault: false
+    })];
+  }
+
+  /**
+   * The text field of one ASS `Dialogue:` row, by the order the file declared.
+   *
+   * Not static, unlike the other containers': the order is read out of the
+   * file's own header, so the answer depends on which file this is. A row
+   * arriving before any `Format:` line has been seen has no declared order and
+   * is not guessed at.
+   *
+   * @param {string} row - The row after `Dialogue:`.
+   * @param {string} [codecId]
+   * @returns {string}
+   */
+  cueTextOf(row, codecId = this.extension) {
+    if (codecId !== ".ass" && codecId !== ".ssa") {
+      return String(row ?? "");
+    }
+    const at = this.eventColumns ? this.eventColumns.indexOf("text") : -1;
+    if (at < 0) {
+      return "";
+    }
+    // The text field is last by the specification and may hold commas, so
+    // everything from its column on is joined back together.
+    return String(row ?? "").split(",").slice(at).join(",");
+  }
+
+  /**
+   * Every cue in the file, with its markup still in place.
+   *
+   * @param {string} text - The file, already decoded to characters.
+   * @returns {{ startSeconds: number, endSeconds: number, text: string }[] | null}
+   *   Null for WebVTT, which is not parsed: it is already what a browser reads,
+   *   and taking it apart to write it back would drop its styles, its regions
+   *   and its cue identifiers for nothing.
+   */
+  readCues(text) {
+    const lines = String(text ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+    if (this.extension === ".ass" || this.extension === ".ssa") {
+      return this.#assCues(lines);
+    }
+    if (this.extension === ".srt") {
+      return this.#srtCues(lines);
+    }
+    return null;
+  }
+
+  /**
+   * @param {string[]} lines
+   * @returns {{ startSeconds: number, endSeconds: number, text: string }[]}
+   */
+  #assCues(lines) {
+    const cues = [];
+    let inEvents = false;
+    this.eventColumns = null;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (/^\[.*\]$/.test(trimmed)) {
+        inEvents = trimmed === "[Events]";
+        continue;
+      }
+      if (!inEvents) {
+        continue;
+      }
+      if (trimmed.startsWith("Format:")) {
+        this.eventColumns = trimmed
+          .slice("Format:".length)
+          .split(",")
+          .map((column) => column.trim().toLowerCase());
+        continue;
+      }
+      if (!trimmed.startsWith("Dialogue:") || !this.eventColumns) {
+        continue;
+      }
+      const row = trimmed.slice("Dialogue:".length);
+      const fields = row.split(",");
+      const startAt = this.eventColumns.indexOf("start");
+      const endAt = this.eventColumns.indexOf("end");
+      if (startAt < 0 || endAt < 0) {
+        continue;
+      }
+      const startSeconds = assSeconds(fields[startAt]);
+      const endSeconds = assSeconds(fields[endAt]);
+      const cueText = this.cueTextOf(row);
+      if (startSeconds === null || endSeconds === null || !cueText) {
+        continue;
+      }
+      cues.push({ startSeconds, endSeconds, text: cueText });
+    }
+    return cues;
+  }
+
+  /**
+   * @param {string[]} lines
+   * @returns {{ startSeconds: number, endSeconds: number, text: string }[]}
+   */
+  #srtCues(lines) {
+    const cues = [];
+    /** @type {{ startSeconds: number, endSeconds: number, text: string[] } | null} */
+    let open = null;
+    const close = () => {
+      if (!open) {
+        return;
+      }
+      // A file with no blank line between cues leaves the next cue's ordinal as
+      // the last line of this one. It is SubRip's own numbering, never
+      // dialogue, so it goes rather than being shown.
+      while (open.text.length > 0 && /^\d+$/.test(open.text[open.text.length - 1].trim())) {
+        open.text.pop();
+      }
+      const text = open.text.join("\n").trim();
+      if (text) {
+        cues.push({ startSeconds: open.startSeconds, endSeconds: open.endSeconds, text });
+      }
+      open = null;
+    };
+    for (const line of lines) {
+      const timing = SRT_TIMING.exec(line.trim());
+      if (timing) {
+        // A timing line opens a cue and closes the one before it. The ordinal
+        // above it is SubRip's own numbering and carries nothing a player needs,
+        // so it is dropped rather than carried into the cue's text — which is
+        // what taking the lines between timings would do.
+        close();
+        open = {
+          startSeconds: srtSeconds(timing.slice(1, 5)),
+          endSeconds: srtSeconds(timing.slice(5, 9)),
+          text: []
+        };
+        continue;
+      }
+      if (!open) {
+        continue;
+      }
+      if (line.trim() === "") {
+        close();
+        continue;
+      }
+      open.text.push(line);
+    }
+    close();
+    return cues;
+  }
+}
+
+export { EXTENSIONS as SUBTITLE_FILE_EXTENSIONS };

package/services/container/index.js

@@ -2,4 +2,5 @@ export { Container } from "./Container.js";
 export { MatroskaContainer } from "./MatroskaContainer.js";
 export { Mp4Container } from "./Mp4Container.js";
 export { AviContainer } from "./AviContainer.js";
+export { SubtitleFileContainer, SUBTITLE_FILE_EXTENSIONS } from "./SubtitleFileContainer.js";
 export { ContainerFactory } from "./ContainerFactory.js";

package/services/container-index/matroska-subtitles.js

@@ -359,9 +359,14 @@ export function harvestCluster(bytes, trackNumber, secondsPerTick) {
     trackNumber,
     secondsPerTick
   );
+  // The payload is handed on as BYTES. What those bytes mean — which of them
+  // are the text and which are the eight fields Matroska puts before it — is
+  // stated by the container's specification and answered by
+  // `MatroskaContainer.cueTextOf`, not here: this function's subject is where a
+  // block sits and how long it lasts.
   return blocks.map((block) => ({
     startSeconds: block.startSeconds,
     endSeconds: block.durationSeconds === null ? null : block.startSeconds + block.durationSeconds,
-    text: block.payload.toString("utf8")
+    payload: block.payload
   }));
 }

package/services/controllers/SubtitleController.js

@@ -8,30 +8,11 @@
  */
 
 import { subtitleOrchestrator } from "../orchestrators/SubtitleOrchestrator.js";
-import { convertSubtitleToVtt, decodeSubtitleBytes } from "../subtitle-convert.js";
+import { convertSubtitleToVtt, cuesToVtt, decodeSubtitleBytes, finalizeCues } from "../subtitle-convert.js";
 import { detectLanguage, detectLanguageFromVtt } from "../language-detect.js";
-import { finalizeCues } from "../torrent-worker/subtitle-cues.js";
 
 const EXTERNAL_MAX_BYTES = 8 * 1024 * 1024;
 
-function vttTime(s) {
-  const safe = Math.max(0, s);
-  const h = Math.floor(safe / 3600);
-  const m = Math.floor((safe % 3600) / 60);
-  const r = safe % 60;
-  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${r.toFixed(3).padStart(6, "0")}`;
-}
-
-function cuesToVtt(cues, codecId) {
-  const lines = ["WEBVTT", ""];
-  for (const c of finalizeCues(cues, codecId)) {
-    lines.push(`${vttTime(c.startSeconds)} --> ${vttTime(c.endSeconds)}`);
-    lines.push(c.text);
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-
 function readFileFully(file, maxBytes) {
   return new Promise((resolve, reject) => {
     const stream = file.createReadStream();
@@ -114,11 +95,11 @@ export class SubtitleController {
       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.
+      // It reads the cues through `finalizeCues`, so what reaches the detector
+      // is the words and not ASS's `{\…}` override groups, which are Latin on a
+      // Russian track. (The dialogue row's own fields are gone earlier now, in
+      // the container that framed them — before 2.72.1 they were not gone at
+      // all, and the detector was reading them too.)
       //
       // 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

package/services/health-collector.js

@@ -6,6 +6,7 @@
  * All values are cheap to read and require no background work.
  */
 
+import { readFileSync } from "node:fs";
 import os from "node:os";
 
 /**
@@ -16,17 +17,50 @@ import os from "node:os";
  *   Suitable as input to `Math.max(0, 1 - Math.min(1, cpuLoad))` for a
  *   normalised "CPU availability" score.
  *
- * `memFree`  — fraction of total system RAM that is currently free (0–1).
+ * `memFree`  — fraction of total system RAM that could still be given out
+ *   (0–1). See {@link availableMemoryBytes} for why that is not the same as
+ *   free memory.
  *
  * `uptime`   — process uptime in whole seconds (useful for preferring
  *   already-warmed proxies over freshly started ones).
  *
  * @typedef {Object} HealthMetrics
  * @property {number} cpuLoad - 1-min load avg / cpu-count.  0 = idle, 1 = saturated, >1 = overloaded.
- * @property {number} memFree - Free RAM as a fraction of total RAM (0–1).
+ * @property {number} memFree - Memory an allocation could obtain, as a fraction of total RAM (0–1).
  * @property {number} uptime  - Process uptime in seconds.
  */
 
+/**
+ * How much memory the machine could still give out, in bytes.
+ *
+ * NOT `os.freemem()`. On Linux that counts only the pages free at this
+ * instant, and the kernel keeps that number low on purpose: what is not in use
+ * is filled with cache, which is handed back the moment anything asks. A host
+ * with 4 GB of cache and 200 MB genuinely free reports 200 MB and looks full
+ * while it has 4.2 GB to give.
+ *
+ * The kernel publishes its own estimate as `MemAvailable`, and that is what is
+ * read here. The same mistake was fixed in the piece store's budget on
+ * 2026-08-27 and stayed in this file until 2026-09-02, where it weighed 0.4 of
+ * every proxy's score — so every Linux proxy in the pool understated itself,
+ * and by a different amount each, according to how much cache it happened to
+ * hold.
+ *
+ * @returns {number}
+ */
+export function availableMemoryBytes() {
+  try {
+    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(readFileSync("/proc/meminfo", "utf8"));
+    if (match) {
+      return Number(match[1]) * 1024;
+    }
+  } catch {
+    // silent-ok: not Linux, or /proc is not readable. `os.freemem()` is then
+    // the best available answer and on those systems it is not misleading.
+  }
+  return os.freemem();
+}
+
 /**
  * Collect current system health metrics.
  *
@@ -38,7 +72,7 @@ import os from "node:os";
 export function collectHealthMetrics() {
   const cpuCount = os.cpus().length || 1;
   const cpuLoad = os.loadavg()[0] / cpuCount;
-  const memFree = os.freemem() / os.totalmem();
+  const memFree = availableMemoryBytes() / os.totalmem();
 
   return {
     cpuLoad: Math.round(cpuLoad * 1000) / 1000,