@torrent-tv/proxy 2.9.27 → 2.9.29

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.9.29
+
+- **New**: Global disk cap with LRU eviction (OpenSpec change `disk-cap`; Disk hygiene Level 1, final piece). Downloaded torrent data was already removed on a 5-min idle TTL and at shutdown, but under pressure it could still fill a small Home Assistant host's disk (which can take down HA itself). The pool now caps total downloaded data — default min(10 GB, half of free disk), overridable with `--max-disk-bytes` (0 disables) — and, when exceeded, evicts whole torrents with no active reader least-recently-used first (checked every 30 s). A torrent that is currently playing is never evicted. (LRU = least-recently-used.)
+- **New**: Output frame rate follows the source instead of a fixed 24 fps (OpenSpec change `transcode-quality`, part 1). 25/30 fps content no longer plays resampled to 24 (which caused judder). Frame-count-GOP encoders (software libx264, v4l2m2m) use an integer rate — source rounded, capped at 30 as a speed guard — with the fps filter and the GOP length kept in lockstep so a keyframe still lands on every segment boundary; the time-based-keyframe encoders (nvenc, vaapi, qsv) inherit the exact source rate untouched (nvenc previously forced 24 — its fps filter is removed). Source rate is parsed from the existing startup probe. (GOP = group of pictures, the span between keyframes; the segment grid needs a keyframe at each boundary.)
+- **Fix**: `GET /api/sources/:key/files` no longer blocks until metadata arrives (or fails prematurely on a cold magnet). It now waits only a short per-request budget (`maxWaitMs`, default 8 s, cap 20 s) and returns `{ pending: true }` while the swarm fetch continues in the background, so the browser can poll — mirroring the cold-torrent playback-plan poll. Field-found: a magnet whose metadata had not arrived yet failed with "no peers" on the first paste, then succeeded on a second paste because the fetch had kept running in the background. A real fetch error now returns 502 (distinct from pending). Pairs with server 0.8.39 (which references this as "proxy 2.9.28" — that release was folded into 2.9.29 before publishing).
+
 ## 2.9.27
 
 - **Fix**: A magnet whose infoHash matches a torrent already loaded in the pool no longer fails with 500 "Cannot add duplicate torrent" (scenario: one viewer opened the .torrent file, another pasted the magnet of the same content — different source keys, one swarm). The duplicate-add error now resolves to the already-loaded torrent (waiting for its metadata when it is itself still cold), so both source keys share the swarm. Found by a field test of the magnet flow.

package/bin/cli.js

@@ -56,6 +56,7 @@ program
   .option("--name <name>", "Display name")
   .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
   .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
+  .option("--max-disk-bytes <bytes>", "Cap total downloaded torrent data (0 = disabled; default min(10GB, half free disk))")
   .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
   .option("--token <token>", "Registration token", "")
   .addHelpText("after", HELP_EXAMPLES);
@@ -79,6 +80,12 @@ const clientName = options.name ? String(options.name) : `proxy-${clientId.slice
 const token = String(options.token ?? "");
 const transcodeAudio = options.transcodeAudio !== false;
 const portMappingEnabled = options.portMapping !== false;
+// Optional disk cap. undefined → the pool computes its own default; a valid
+// non-negative number (0 disables) → passed through.
+const maxDiskBytes =
+  options.maxDiskBytes !== undefined && Number.isFinite(Number(options.maxDiskBytes)) && Number(options.maxDiskBytes) >= 0
+    ? Number(options.maxDiskBytes)
+    : undefined;
 const bundledFfmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : "";
 const ffmpegBin = options.ffmpegBin ? String(options.ffmpegBin) : bundledFfmpegBin || "ffmpeg";
 
@@ -234,7 +241,8 @@ try {
     host: bindHost,
     port: localPort,
     transcodeAudio,
-    ffmpegBin
+    ffmpegBin,
+    maxDiskBytes
   });
   app = started.app;
   actualPort = started.port;

package/openspec/changes/disk-cap/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-07

package/openspec/changes/disk-cap/proposal.md

@@ -0,0 +1,37 @@
+# Proposal: Global disk cap with LRU eviction (Disk hygiene Level 1, final)
+
+## Why
+
+Downloaded torrent data is already removed on a 300 s idle TTL and at
+shutdown, and orphans are swept at startup — but under pressure (several
+large files opened within the TTL window, or a fast fill) the total can
+still grow unbounded and fill a small Home Assistant host's disk
+(SD/eMMC on a Yellow/Pi is often 16–32 GB). A full disk can take down Home
+Assistant itself. This adds the last missing Level 1 piece: a global cap.
+
+## What Changes
+
+- The pool tracks total downloaded bytes and, when it exceeds a cap, evicts
+  whole torrents with NO active reader, least-recently-used first, until
+  back under the cap (checked every 30 s and reused via the existing
+  remove-with-store path). A torrent that is currently playing is never
+  evicted — we cannot delete what is in use.
+- The cap defaults to `min(10 GB, half of free disk)` (measured via
+  `statfs` on the store filesystem), and is overridable with
+  `--max-disk-bytes` (0 disables).
+
+## Capabilities
+
+### New Capabilities
+
+- `disk-cap`: bounded total on-disk footprint via LRU eviction.
+
+### Modified Capabilities
+
+<!-- none -->
+
+## Impact
+
+- `services/torrent-pool.js` (access tracking, cap enforcement),
+  `bin/cli.js` (`--max-disk-bytes`), `server.js` (option pass-through);
+  ha-addon bump. Part of the proxy transcode/hygiene batch (2.9.29).

package/openspec/changes/disk-cap/specs/disk-cap/spec.md

@@ -0,0 +1,25 @@
+# disk-cap — delta spec
+
+## ADDED Requirements
+
+### Requirement: Total torrent data is bounded by a disk cap
+The pool SHALL keep the total downloaded torrent footprint under a cap. When
+the total exceeds the cap it SHALL evict whole torrents that have no active
+file reader, least-recently-used first, removing each with its on-disk store,
+until back under the cap or no evictable torrent remains. A torrent with an
+active reader SHALL NEVER be evicted. The cap SHALL default to the smaller of
+10 GB and half the free disk, and be overridable (0 disables).
+
+#### Scenario: Idle torrents evicted under pressure
+- **WHEN** the total downloaded data exceeds the cap and some torrents have no
+  active reader
+- **THEN** the least-recently-used idle torrents are removed with their stores
+  until the total is back under the cap
+
+#### Scenario: Active torrent protected
+- **WHEN** the cap is exceeded but the only large torrent is currently playing
+- **THEN** it is not evicted (the cap cannot delete in-use data)
+
+#### Scenario: Cap disabled
+- **WHEN** the cap is set to 0
+- **THEN** no eviction occurs

package/openspec/changes/disk-cap/tasks.md

@@ -0,0 +1,19 @@
+# Tasks: Global disk cap with LRU eviction
+
+## 1. Implementation
+
+- [x] 1.1 Access tracking (`#lastAccess`) updated on getTorrent (incl. the
+      duplicate-infoHash path) and acquireFile
+- [x] 1.2 Cap computed at construction (`min(10GB, half free)` via statfs) or
+      taken from the `maxDiskBytes` option; 0 disables
+- [x] 1.3 Periodic (30 s) `#enforceDiskCap`: evict zero-reader torrents
+      LRU-first via the existing remove-with-store path; clear timer on
+      destroyAll; drop `#lastAccess` on removal
+- [x] 1.4 `--max-disk-bytes` CLI flag → server.js → pool
+- [x] 1.5 Syntax checks + unit-test the eviction ordering/active-skip
+
+## 2. Release
+
+- [ ] 2.1 Ship in the proxy batch (2.9.29) + ha-addon bump
+- [ ] 2.2 Field-check on the host: open several large files, confirm idle
+      ones are evicted and playback is never interrupted

package/openspec/changes/transcode-quality/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-07

package/openspec/changes/transcode-quality/proposal.md

@@ -0,0 +1,51 @@
+# Proposal: Transcode quality — source fps, realtime budget, HDR, manual quality
+
+## Why
+
+The transcode pipeline was tuned for "make it play at all" and left several
+quality/robustness gaps flagged in the project analysis: output was hard-
+locked to 24 fps (25/30 fps content played with resampling judder); the
+encoder profile could be slower than realtime on weak hosts (stalls instead
+of graceful degradation); 10-bit/HDR sources transcoded to 8-bit H.264
+without tone mapping (washed-out colours); and the viewer had no way to force
+a resolution. This change is the transcode-stage batch (proxy side; the
+manual-quality menu also needs the server UI).
+
+## What Changes
+
+- **Source fps** (DONE): the output frame rate is inherited from the source
+  (rounded to an integer, capped at 30), replacing the fixed 24. The
+  fixed-GOP encoders keep the fps↔GOP relationship exact so keyframes stay on
+  the segment grid; time-based-keyframe encoders (nvenc) just use it as the
+  rate; VAAPI/QSV already inherited.
+- **Realtime budget** (planned): the startup benchmark picks the
+  encoder/preset/resolution/fps combination whose predicted throughput stays
+  above realtime; a source that would not encode in time is downscaled
+  (720/540p) rather than refused, and a sustained runtime `speed<1` triggers
+  a restart with a lighter profile. `-maxrate`/`-bufsize` cap bitrate spikes.
+- **HDR tone mapping** (planned): detect 10-bit/HDR (pix_fmt,
+  color_transfer smpte2084/HLG) and insert a tone-map chain when re-encoding
+  to 8-bit H.264, so colours are not washed out. Depends on the ffmpeg build
+  having the tonemap filters.
+- **Manual quality** (planned): a player Quality menu — Auto (current
+  viewport/DPR behaviour) plus forced resolutions — the proxy already
+  honours a requested target height.
+
+## Capabilities
+
+### New Capabilities
+
+- `transcode-quality`: output frame rate, realtime encode budget, HDR tone
+  mapping, and explicit quality selection.
+
+### Modified Capabilities
+
+<!-- none -->
+
+## Impact
+
+- `services/hwaccel.js` (fps, benchmark, tonemap args),
+  `services/hls-session-manager.js` (fps probe, runtime speed watch),
+  `services/playback-planner.js` (HDR/fps in the plan);
+  server player UI for the Quality menu; ha-addon bump.
+- Released as a batch (proxy 2.9.29 + addon) after the pieces land.

package/openspec/changes/transcode-quality/specs/transcode-quality/spec.md

@@ -0,0 +1,37 @@
+# transcode-quality — delta spec
+
+## ADDED Requirements
+
+### Requirement: Output frame rate follows the source
+When re-encoding video, the proxy SHALL NOT force a fixed 24 fps. The output
+rate SHALL follow the source, and the fps handling SHALL depend on how the
+chosen encoder places keyframes:
+
+- Frame-count-GOP encoders (software libx264, v4l2m2m) SHALL use an INTEGER
+  output rate — source rate rounded and capped — with the `fps` filter and
+  the GOP length (`segmentDuration × fps`) using that same integer, so a
+  keyframe lands on every segment boundary and segments do not drift off the
+  synthetic playlist's uniform grid. When the source rate is unknown they
+  SHALL fall back to the default rate.
+- Time-based-keyframe encoders (nvenc, vaapi, qsv) SHALL inherit the exact
+  source rate with no fps filter (their keyframes are forced by output time,
+  so any rate segments correctly); no rounding, no cap.
+
+#### Scenario: 25 fps source on the software encoder
+- **WHEN** a 25 fps video is re-encoded with libx264 and 4-second segments
+- **THEN** the output is 25 fps and the GOP is 100 frames (keyframe every
+  segment)
+
+#### Scenario: High-fps source on the software encoder
+- **WHEN** a 60 fps video is re-encoded with libx264/v4l2m2m
+- **THEN** the output rate is capped at 30 fps (speed guard)
+
+#### Scenario: Fractional source on a hardware time-based encoder
+- **WHEN** a 23.976 fps video is re-encoded with nvenc/vaapi/qsv
+- **THEN** the exact source rate is kept (no fps filter) and segments are
+  still cut on time
+
+#### Scenario: Unknown source rate
+- **WHEN** the source frame rate cannot be probed on the software path
+- **THEN** the output falls back to the default rate and playback still
+  segments correctly

package/openspec/changes/transcode-quality/tasks.md

@@ -0,0 +1,34 @@
+# Tasks: Transcode quality
+
+## 1. Source fps
+
+- [x] 1.1 hwaccel: `chooseOutputFps` (integer, capped); `buildVideoArgs`
+      takes `fps`, threaded into the filter + frame-count GOP (software,
+      v4l2m2m) and the filter only (nvenc); VAAPI/QSV unchanged (already
+      inherit); startup test-encode/benchmark keep the fixed rate
+- [x] 1.2 hls-session-manager: parse source fps from the probe, compute
+      `session.outputFps`, pass it into `buildVideoArgs`
+- [x] 1.3 Unit-verify fps choice and fps↔GOP consistency (25→100, 24→96,
+      default→96); syntax checks
+
+## 2. Realtime budget (planned)
+
+- [ ] 2.1 Benchmark picks encoder/preset/resolution/fps within a realtime
+      margin; downscale instead of refuse
+- [ ] 2.2 Runtime `speed<1` watch → restart with a lighter profile
+- [ ] 2.3 `-maxrate`/`-bufsize`
+
+## 3. HDR tone mapping (planned)
+
+- [ ] 3.1 Detect 10-bit/HDR; insert tonemap chain when re-encoding to 8-bit
+- [ ] 3.2 Guard on tonemap-filter availability in the ffmpeg build
+
+## 4. Manual quality (planned)
+
+- [ ] 4.1 Proxy honours requested target height (already partly there)
+- [ ] 4.2 Server Quality menu (Auto + forced resolutions)
+
+## 5. Release
+
+- [ ] 5.1 Batch release: proxy 2.9.29 + ha-addon bump; field-test on the
+      owner's hardware (25/30 fps content plays without judder; seek intact)

package/package.json

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

package/routes/api/sources/files/get.js

@@ -4,9 +4,14 @@
  * GET /api/sources/:sourceKey/files
  *
  * The browser parses `.torrent` files locally, but a magnet URI carries no
- * file list — the metadata comes from the swarm. This route resolves the
- * torrent (waiting for metadata on a cold magnet; callers should use a
- * generous timeout) and returns the file inventory.
+ * file list — the metadata comes from the swarm and can take a while to
+ * arrive on a cold magnet. Rather than block the request until it does (a
+ * single long request racing the transport timeout, which surfaced as a
+ * premature "no peers" error while the metadata was in fact still arriving),
+ * this waits only a short per-request budget: if the metadata is not ready it
+ * returns `{ pending: true }` while the fetch continues in the background. The
+ * caller polls again until the file list comes back — mirroring the cold-
+ * torrent playback-plan poll.
  *
  * @param {import("fastify").FastifyRequest} req
  * @param {import("fastify").FastifyReply} reply
@@ -16,6 +21,10 @@
  * }} deps
  * @returns {Promise<void>}
  */
+
+/** Sentinel resolved when the per-request wait elapses before metadata. */
+const PENDING = Symbol("pending");
+
 export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool }) {
   const sourceKey = typeof req.params?.sourceKey === "string" ? req.params.sourceKey.trim() : "";
   if (!sourceKey) {
@@ -26,7 +35,41 @@ export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torr
     return reply.code(404).send({ error: "Source key was not found." });
   }
 
-  const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+  // How long to wait within THIS request before returning `pending`. Well
+  // under the transport's request timeout so a single poll never races it.
+  const rawWait = Number(req.query?.maxWaitMs);
+  const maxWaitMs = Number.isFinite(rawWait) && rawWait > 0 ? Math.min(rawWait, 20_000) : 8_000;
+
+  // getTorrent dedupes concurrent/repeated calls via the pool's in-flight map,
+  // so polling keeps joining the same background fetch (metadata keeps
+  // downloading between polls). Race it against the wait budget; if the wait
+  // wins, the fetch is left running for the next poll to observe.
+  let timer;
+  const waitPromise = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(PENDING), maxWaitMs);
+    timer.unref?.();
+  });
+  const torrentPromise = torrentPool
+    .getTorrent(sourceRecord.sourceType, sourceRecord.source)
+    // Swallow so a rejection that loses the race is not an unhandled rejection;
+    // the next poll re-issues getTorrent and re-observes any real error.
+    .catch((error) => (error instanceof Error ? error : new Error(String(error))));
+
+  let result;
+  try {
+    result = await Promise.race([torrentPromise, waitPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (result === PENDING) {
+    return reply.send({ pending: true });
+  }
+  if (result instanceof Error) {
+    return reply.code(502).send({ error: `Could not load torrent metadata: ${result.message}` });
+  }
+
+  const torrent = result;
   const files = (torrent.files ?? []).map((file, index) => ({
     index,
     name: file?.name ?? "",

package/server.js

@@ -60,6 +60,7 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
  * @property {number}  port           - Preferred listen port.
  * @property {boolean} transcodeAudio - Whether HLS audio transcoding is enabled.
  * @property {string}  ffmpegBin      - Path to the ffmpeg executable.
+ * @property {number}  [maxDiskBytes] - Global disk cap for torrent data (undefined = pool default).
  */
 
 /**
@@ -68,7 +69,7 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
  * @param {ProxyServerOptions} options
  * @returns {Promise<{ app: import("fastify").FastifyInstance, port: number }>}
  */
-export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin }) {
+export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin, maxDiskBytes }) {
   const app = Fastify({
     // No practical body-size limit — the proxy server is localhost-only and
     // receives torrent source payloads that may be arbitrarily large.
@@ -94,7 +95,7 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin }
   });
 
   const sourceRegistry = createSourceRegistry(200);
-  const torrentPool = new TorrentPool();
+  const torrentPool = new TorrentPool({ maxDiskBytes });
   const selectedPort = await getPort({
     port: buildPortCandidates(port)
   });

package/services/hls-session-manager.js

@@ -15,7 +15,7 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { logger } from "../utils/logger.js";
-import { softwareDescriptor, pickSoftwarePreset, TRANSCODE_FPS } from "./hwaccel.js";
+import { softwareDescriptor, pickSoftwarePreset, TRANSCODE_FPS, chooseOutputFps } from "./hwaccel.js";
 
 const PLAYLIST_FILE_NAME = "index.m3u8";
 const SEGMENT_FILE_NAME_PATTERN = /^segment-\d{5}\.ts$/;
@@ -295,6 +295,29 @@ function parseFfmpegVideoDimensions(stderrText) {
   };
 }
 
+/**
+ * Parse the source frame rate from the ffmpeg "Video:" line
+ * (e.g. "… 23.98 fps," / "… 25 fps,"). Returns null when absent.
+ *
+ * @param {string} stderrText
+ * @returns {number | null}
+ */
+function parseFfmpegVideoFps(stderrText) {
+  if (typeof stderrText !== "string" || stderrText.length === 0) {
+    return null;
+  }
+  const videoLine = stderrText.match(/Video:[^\n]*/i);
+  if (!videoLine) {
+    return null;
+  }
+  const match = videoLine[0].match(/([\d.]+)\s*fps/i);
+  if (!match) {
+    return null;
+  }
+  const value = Number(match[1]);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
 /**
  * Run a short ffmpeg probe to extract the total duration AND video resolution
  * of a stream from the container header. Both are printed almost immediately
@@ -323,6 +346,7 @@ async function probeInputMediaInfo(ffmpegBin, inputUrl) {
         durationSeconds: parseFfmpegDurationSeconds(stderr),
         width: dims.width,
         height: dims.height,
+        fps: parseFfmpegVideoFps(stderr),
         startTime: parseFfmpegStartTimeSeconds(stderr)
       });
     };
@@ -720,6 +744,10 @@ export class HlsSessionManager {
     const sourceWidth = mediaInfo.width;
     const sourceHeight = mediaInfo.height;
     const sourceStartTime = Number.isFinite(mediaInfo.startTime) ? mediaInfo.startTime : 0;
+    // Output frame rate inherited from the source (integer, capped) so 25/30
+    // fps content is not resampled to 24. Fixed-GOP encoders keep the fps↔GOP
+    // relationship exact; time-based-keyframe encoders just use it as the rate.
+    const outputFps = chooseOutputFps(mediaInfo.fps);
     const hasDuration = Number.isFinite(durationSeconds) && durationSeconds > 0;
     const logName = normalizeLogFileName(fileName, fileIndex);
     if (!hasDuration) {
@@ -789,6 +817,7 @@ export class HlsSessionManager {
       transcodeVideo,
       transcodeAudio,
       audioTrackIndex: normalizedAudioTrack,
+      outputFps,
       targetWidth: normalizedTargetWidth,
       targetHeight: normalizedTargetHeight,
       sourceWidth,
@@ -1001,6 +1030,9 @@ export class HlsSessionManager {
           targetWidth: session.targetWidth,
           targetHeight: session.targetHeight,
           segmentDurationSec: this.segmentDurationSec,
+          // Source-inherited output rate (integer, capped); descriptors that
+          // use time-based keyframes just apply it as the frame rate.
+          fps: session.outputFps,
           // Software-only; hardware descriptors ignore it.
           preset: session.softwarePreset ?? undefined
         })