@torrent-tv/proxy 2.88.3 → 2.88.5

package/services/server/wire-outputs.js

@@ -84,7 +84,8 @@ import { OutputOpening } from "../encode/OutputOpening.js";
 import { segmentFormatOfKey } from "../encode/output-key-format.js";
 import { OutputSpec } from "../encode/output/OutputSpec.js";
 import { compareInits } from "../encode/segment-formats/init-compat.js";
-import { nominalKbpsFor } from "../encode/args.js";
+import { nominalKbpsFor, AUDIO_TRANSCODE_KBPS } from "../encode/args.js";
+import { audioReadingFor } from "../encode/audio-work-rate.js";
 import { probeInputMediaInfo } from "../media/media-info-probe.js";
 import { probeVideoKeyframeTimes } from "../media/keyframe-probe.js";
 import { wireMachineBudget } from "../storage/wire.js";
@@ -210,6 +211,7 @@ export function wireOutputs({
     // is inventing a penalty, which is the same fault as inventing a fill rate.
     contentionPenalties = null,
     copySpeedX = null,
+    audioCalibration = [],
     tonemapSupported = false,
     getCachedMediaInfo = null,
     getCachedAudioTracks = null,
@@ -227,6 +229,10 @@ export function wireOutputs({
     memoryClaimant = null,
     budgetPolicy = null}) {
   const parts = {};
+  const audioDescriptionOf = (output) => (getCachedAudioTracks?.({
+    sourceKey: output.file.sourceKey, fileIndex: output.spec.grid?.fileIndex ?? output.file.fileIndex
+  }) ?? []).find((track) => track.fileIndex === output.spec.audio?.fileIndex &&
+    track.sourceTrackIndex === output.spec.audio?.trackIndex) ?? null;
   // Encode components receive only the storage operations they use. The
   // concrete SegmentStore remains owned by this assembly and is never handed
   // to the encode layer.
@@ -240,7 +246,7 @@ export function wireOutputs({
     pathFor: (address) => parts.segmentStore.pathFor(address),
     initOf: (address) => parts.segmentStore.initOf(address),
     directoryFor: (address) => parts.segmentStore.directoryFor(address),
-    publish: (address, makingName, format) => parts.segmentStore.publish(address, makingName, format)
+    publish: (address, makingName, format, coverage) => parts.segmentStore.publish(address, makingName, format, coverage)
   };
   const segmentOutputFiles = {
     addresses: () => parts.segmentStore.addresses(),
@@ -353,6 +359,9 @@ export function wireOutputs({
     worstSupplyWaitSec: parts.hostLoad.supplyFor(output.file)?.worstWaitSec
   })?.seconds ?? null;
   parts.renditions = new Renditions({
+    // Whether this proxy re-encodes at all: a soundtrack with no stated rate is
+    // re-encoded where it may be, and copied where it may not.
+    get transcodeEnabled() { return parts.enabled; },
     observedPeakMbps: (spec) => parts.localObservations?.peakMbps(spec) ?? null,
     // A viewer has been moved onto an output prepared for them: how long it
     // took, and what they held.
@@ -545,7 +554,24 @@ export function wireOutputs({
     waitUntilReady: (...args) => parts.serving.waitUntilReady(...args),
     get encodeRuns() { return parts.encodeRuns; },
     encodeSpeedReadingOf: (output) => parts.encodeCost.latestSpeedReadingOf(output),
-    projectedEncodeSpeedOf: () => parts.admission.projectedSpeedX(),
+    projectedEncodeSpeedOf: (output) => parts.encodeCost.projectedSpeedOf(output),
+    audioDescriptionOf,
+    processingStartupSecondsOf: (output) => output.spec.carries === "audio-only" ?
+      audioReadingFor(audioCalibration, { ...audioDescriptionOf(output),
+        codec: audioDescriptionOf(output)?.codec ?? output.file.media?.audioCodec,
+        transcode: output.spec.audio?.transcode })?.startupSeconds ?? 0 :
+      Math.max(0, (startStopCost?.firstByteWaitSec ?? 0) - parts.segmentDurationSec /
+        parts.encodeCost.projectedSpeedOf(output)),
+    initialOutputBitsPerMediaSecondOf: (output) => {
+      const description = audioDescriptionOf(output);
+      const reference = audioReadingFor(audioCalibration, { codec: description?.codec, transcode: false });
+      const audio = output.spec.audio ? output.spec.audio.transcode ? AUDIO_TRANSCODE_KBPS * 1000 :
+        description?.bitrateKbps > 0 ? description.bitrateKbps * 1000 :
+          reference ? reference.bytes * 8 / reference.durationSeconds : 0 : 0;
+      const video = output.spec.video ? (output.spec.video.encode?.rateControl?.maxrateKbps ??
+        output.file.media?.bitrateKbps ?? 0) * 1000 : 0;
+      return video + audio;
+    },
     get opening() { return parts.opening; },
     get outputTimes() { return parts.outputTimes; },
     get outputs() { return parts.outputs; },
@@ -761,6 +787,8 @@ export function wireOutputs({
       decodeModel: parts.decodeCostModel,
       contentionPenalties: parts.contentionPenalties,
       copySpeedX: parts.copySpeedX,
+      audioCalibration,
+      audioDescriptionOf,
       availability: parts.hostLoad.hostAvailability,
       // WHICH encoder this host settled on. Only the software ladder is
       // benchmarked, so a reading taken off a hardware encoder cannot be

package/services/storage/piece-store/shared-piece-store.js

@@ -814,6 +814,12 @@ export class SharedPieceStore {
     return this.#buffers.get(index);
   }
 
+  /** Availability belongs to the store, not to a second cached bitfield. */
+  locationOf(index) {
+    return this.#buffers.has(index) ? "memory" : this.#evicting.has(index) ? "writing" :
+      this.#disk.has(index) ? "disk" : this.isInWholeFiles(index) ? "whole-file" : "missing";
+  }
+
   pin(index) {
     this.#lru.pin(index);
     // A piece reader pins before it waits for the bytes to arrive or return

package/services/storage/segment-store/SegmentStore.js

@@ -426,7 +426,7 @@ export class SegmentStore {
    * @param {{ servedNameOf?: (name: string) => string | null }} format
    * @returns {string | null} The served name, or null where nothing was renamed.
    */
-  publish(key, makingName, format) {
+  publish(key, makingName, format, { endSeconds } = {}) {
     const served = format?.servedNameOf?.(makingName) ?? null;
     if (!served) {
       return null;
@@ -438,6 +438,11 @@ export class SegmentStore {
       try {
         mediaRanges = format.readMediaRanges(readFileSync(path.join(dir, makingName)));
         if (mediaRanges.length === 0) throw new Error("The closed file contains no playable media intervals.");
+        const end = format.mediaCoverageEnd?.(mediaRanges);
+        if (Number.isFinite(endSeconds) && Number.isFinite(end) && end < endSeconds) {
+          this.#logger?.warn?.(`segment store: refusing short segment ${index}: coverage=${end}s cut=${endSeconds}s`);
+          return null;
+        }
       } catch (error) {
         this.#logger?.warn?.(`segment store: could not read media coverage of ${makingName}: ${error.message}`);
         return null;
@@ -471,11 +476,20 @@ export class SegmentStore {
     return served;
   }
 
-  mediaRangesOf(key, index, { startSeconds = 0 } = {}) {
+  mediaRangesOf(key, index, { startSeconds = 0, endSeconds } = {}) {
     const known = this.#mediaRanges.get(key)?.get(index);
-    if (known) return known;
     const format = this.#formats.get(key);
     if (!format?.readMediaRanges) return undefined;
+    const checked = (ranges) => {
+      const end = format.mediaCoverageEnd?.(ranges);
+      if (Number.isFinite(endSeconds) && Number.isFinite(end) && end < endSeconds) {
+        this.#logger?.warn?.(`segment store: removing short cached segment ${index}: coverage=${end}s cut=${endSeconds}s`);
+        this.#removeSegment(key, index);
+        return undefined;
+      }
+      return ranges;
+    };
+    if (known) return checked(known);
     const filePath = this.pathOf(key, index);
     if (!filePath) return undefined;
     try {
@@ -492,7 +506,7 @@ export class SegmentStore {
       const byIndex = this.#mediaRanges.get(key) ?? new Map();
       byIndex.set(index, ranges);
       this.#mediaRanges.set(key, byIndex);
-      return ranges;
+      return checked(ranges);
     } catch {
       return [];
     }
@@ -1092,6 +1106,7 @@ export class SegmentStore {
       // Gone already, or refused. The next refresh reports what is really there.
     }
     this.#held.delete(key);
+    this.#mediaRanges.get(key)?.delete(index);
     return size;
   }
 

package/services/torrent/episode-naming.js

@@ -1,182 +1,182 @@
-/**
- * @file What a picture's NAME says about which episode it is.
- *
- * A season pack states its structure in names — `s01e02_Murder.in.the.Mews.avi`,
- * `Reacher.S04E01.1080p.rus.LostFilm.TV.mkv`, `[HorribleSubs] Drifters - 01
- * [1080p].mkv` under a folder, or an episode number under `Season_01/`. This
- * reads that statement and nothing else: which season, which episode numbers,
- * which part of an episode, whether it is a special, and the text on either
- * side of the marker.
- *
- * The numbers are the RELEASE's numbering. They are often the same as a
- * metadata provider's and sometimes not — one release numbers the two parts of
- * a feature-length episode as two episodes, which shifts every number after
- * them — so nothing here claims to know which episode of the show a file is.
- * That is decided later, against the provider's own list, by whoever holds it.
- *
- * A name without a marker returns `null`: absence of a number is absence of
- * information, not evidence that the file is not an episode.
- */
-
-import { stripExtension } from "./naming.js";
-
-/** Most episodes one file may claim before the claim is read as noise. */
-const MAX_EPISODES_PER_FILE = 8;
-
-/** Longest hint returned, in characters; a name longer than this is not a title. */
-const MAX_HINT_LENGTH = 160;
-
-/** `S01E02`, `s03.e01`, `S01E01E02`, `S01E01-E02`, `S01E01-02`. */
-const SEASON_EPISODE = /(?<![a-z0-9])s(\d{1,3})[ ._]?e(\d{1,4})((?:-?e\d{1,4}|-\d{1,4})*)(?![0-9])/i;
-
-/** `1x02`; four-digit sides are picture sizes (`1920x1080`) and never match. */
-const CROSS = /(?<![a-z0-9])(\d{1,2})x(\d{2,3})(?![0-9a-z])/i;
-
-/** `E05`, `Ep 5`, `Episode.05`, `Серия 5` — an episode number with no season in it. */
-const EPISODE_ONLY = /(?<![\p{L}0-9])(?:e|ep|episode|серия)[ ._-]?(\d{1,4})(?![0-9])/iu;
-
-/** `Show - 01`, `Show - 01v2` — the numbering most anime releases use. */
-const DASH_NUMBER = / - (\d{1,4})(?:v\d)?(?=[ .[(]|$)/;
-
-/** A folder that names a season: `Season_01`, `Season 1`, `S01`, `Сезон 1`, `1 сезон`. */
-const SEASON_FOLDER = /^(?:season|сезон|s)[ ._-]*(\d{1,3})$|^(\d{1,3})[ ._-]*(?:season|сезон)$/iu;
-
-/** `Part.1`, `Pt 2`, `Часть 1`. */
-const PART = /(?<![\p{L}0-9])(?:part|pt|часть)[ ._-]?(\d{1,2})(?![0-9])/iu;
-
-/** `Special`, `Specials`, `SP01`. */
-const SPECIAL = /(?<![\p{L}])(?:specials?|sp\d{1,3})(?![\p{L}])/iu;
-
-/** Separators a release puts between words, trimmed off the ends of a hint. */
-const EDGE_SEPARATORS = /^[\s._\-–—]+|[\s._\-–—]+$/g;
-
-/**
- * An episode marker read from a name.
- *
- * @typedef {object} EpisodeMarker
- * @property {number | null} season - `null` when neither the name nor a folder states one.
- * @property {number[]} episodes - The release's numbers, one or more.
- * @property {number | null} part - Which part of one episode, when the name says so.
- * @property {boolean} special - Season 0, or a name calling itself a special.
- * @property {string} showHint - The name's text before the marker, as written.
- * @property {string} titleHint - The name's text after the marker, part removed, as written.
- */
-
-/**
- * Trim a piece of a name to a hint.
- *
- * @param {string} text
- * @returns {string}
- */
-function hint(text) {
-  return String(text ?? "").replace(EDGE_SEPARATORS, "").slice(0, MAX_HINT_LENGTH);
-}
-
-/**
- * The numbers after the first episode in `S01E01E02` or `S01E01-03`.
- *
- * A `-` joins a range, a repeated `E` lists another episode.
- *
- * @param {number} first
- * @param {string} rest
- * @returns {number[] | null} `null` when the claim is longer than any file carries.
- */
-function episodesFrom(first, rest) {
-  const episodes = [first];
-  for (const token of rest.match(/-?e?\d+/gi) ?? []) {
-    const value = Number(token.replace(/[^0-9]/g, ""));
-    const last = episodes[episodes.length - 1];
-    if (token.startsWith("-") && value > last) {
-      for (let next = last + 1; next <= value; next += 1) {
-        episodes.push(next);
-        if (episodes.length > MAX_EPISODES_PER_FILE) {
-          return null;
-        }
-      }
-    } else if (value !== last) {
-      episodes.push(value);
-    }
-  }
-  return episodes.length > MAX_EPISODES_PER_FILE ? null : episodes;
-}
-
-/**
- * The season the deepest season-naming folder states, if any does.
- *
- * @param {string[]} folders
- * @returns {number | null}
- */
-function seasonFromFolders(folders) {
-  for (let index = folders.length - 1; index >= 0; index -= 1) {
-    const match = SEASON_FOLDER.exec(String(folders[index] ?? "").trim());
-    if (match) {
-      return Number(match[1] ?? match[2]);
-    }
-  }
-  return null;
-}
-
-/**
- * Which episode a picture's name says it is.
- *
- * @param {{ name: string, folders?: string[] }} file - File name and the folders above it.
- * @returns {EpisodeMarker | null}
- */
-export function readEpisodeMarker({ name, folders = [] }) {
-  const stem = stripExtension(String(name ?? ""));
-  const folderSeason = seasonFromFolders(Array.isArray(folders) ? folders : []);
-
-  let season = null;
-  let episodes = null;
-  let before = "";
-  let after = "";
-
-  const seasonEpisode = SEASON_EPISODE.exec(stem);
-  const cross = seasonEpisode ? null : CROSS.exec(stem);
-  const episodeOnly = seasonEpisode || cross ? null : EPISODE_ONLY.exec(stem);
-  const dash = seasonEpisode || cross || episodeOnly ? null : DASH_NUMBER.exec(stem);
-  const match = seasonEpisode ?? cross ?? episodeOnly ?? dash;
-  if (!match) {
-    return null;
-  }
-  before = stem.slice(0, match.index);
-  after = stem.slice(match.index + match[0].length);
-
-  if (seasonEpisode) {
-    season = Number(seasonEpisode[1]);
-    episodes = episodesFrom(Number(seasonEpisode[2]), seasonEpisode[3] ?? "");
-  } else if (cross) {
-    season = Number(cross[1]);
-    episodes = [Number(cross[2])];
-  } else {
-    // `Show S1 - 01` states its season just before the number; a folder is the
-    // other place a release puts it.
-    const trailingSeason = /(?<![a-z0-9])s(\d{1,3})[\s._-]*$/i.exec(before);
-    season = trailingSeason ? Number(trailingSeason[1]) : folderSeason;
-    if (trailingSeason) {
-      before = before.slice(0, trailingSeason.index);
-    }
-    episodes = [Number(match[1])];
-  }
-  // A year where an episode number would be is a year far more often than an
-  // episode: `Film - 2024 [1080p]`, and `WALL-E.2008.mkv` reads as `E` then
-  // `2008`. Only the markers without a season can be fooled this way.
-  if ((dash || episodeOnly) && /^(?:19|20)\d\d$/.test(match[1])) {
-    return null;
-  }
-  if (!episodes) {
-    return null;
-  }
-
-  const part = PART.exec(after);
-  const titleText = part ? `${after.slice(0, part.index)} ${after.slice(part.index + part[0].length)}` : after;
-
-  return {
-    season,
-    episodes,
-    part: part ? Number(part[1]) : null,
-    special: season === 0 || SPECIAL.test(stem),
-    showHint: hint(before),
-    titleHint: hint(titleText)
-  };
-}
+/**
+ * @file What a picture's NAME says about which episode it is.
+ *
+ * A season pack states its structure in names — `s01e02_Murder.in.the.Mews.avi`,
+ * `Reacher.S04E01.1080p.rus.LostFilm.TV.mkv`, `[HorribleSubs] Drifters - 01
+ * [1080p].mkv` under a folder, or an episode number under `Season_01/`. This
+ * reads that statement and nothing else: which season, which episode numbers,
+ * which part of an episode, whether it is a special, and the text on either
+ * side of the marker.
+ *
+ * The numbers are the RELEASE's numbering. They are often the same as a
+ * metadata provider's and sometimes not — one release numbers the two parts of
+ * a feature-length episode as two episodes, which shifts every number after
+ * them — so nothing here claims to know which episode of the show a file is.
+ * That is decided later, against the provider's own list, by whoever holds it.
+ *
+ * A name without a marker returns `null`: absence of a number is absence of
+ * information, not evidence that the file is not an episode.
+ */
+
+import { stripExtension } from "./naming.js";
+
+/** Most episodes one file may claim before the claim is read as noise. */
+const MAX_EPISODES_PER_FILE = 8;
+
+/** Longest hint returned, in characters; a name longer than this is not a title. */
+const MAX_HINT_LENGTH = 160;
+
+/** `S01E02`, `s03.e01`, `S01E01E02`, `S01E01-E02`, `S01E01-02`. */
+const SEASON_EPISODE = /(?<![a-z0-9])s(\d{1,3})[ ._]?e(\d{1,4})((?:-?e\d{1,4}|-\d{1,4})*)(?![0-9])/i;
+
+/** `1x02`; four-digit sides are picture sizes (`1920x1080`) and never match. */
+const CROSS = /(?<![a-z0-9])(\d{1,2})x(\d{2,3})(?![0-9a-z])/i;
+
+/** `E05`, `Ep 5`, `Episode.05`, `Серия 5` — an episode number with no season in it. */
+const EPISODE_ONLY = /(?<![\p{L}0-9])(?:e|ep|episode|серия)[ ._-]?(\d{1,4})(?![0-9])/iu;
+
+/** `Show - 01`, `Show - 01v2` — the numbering most anime releases use. */
+const DASH_NUMBER = / - (\d{1,4})(?:v\d)?(?=[ .[(]|$)/;
+
+/** A folder that names a season: `Season_01`, `Season 1`, `S01`, `Сезон 1`, `1 сезон`. */
+const SEASON_FOLDER = /^(?:season|сезон|s)[ ._-]*(\d{1,3})$|^(\d{1,3})[ ._-]*(?:season|сезон)$/iu;
+
+/** `Part.1`, `Pt 2`, `Часть 1`. */
+const PART = /(?<![\p{L}0-9])(?:part|pt|часть)[ ._-]?(\d{1,2})(?![0-9])/iu;
+
+/** `Special`, `Specials`, `SP01`. */
+const SPECIAL = /(?<![\p{L}])(?:specials?|sp\d{1,3})(?![\p{L}])/iu;
+
+/** Separators a release puts between words, trimmed off the ends of a hint. */
+const EDGE_SEPARATORS = /^[\s._\-–—]+|[\s._\-–—]+$/g;
+
+/**
+ * An episode marker read from a name.
+ *
+ * @typedef {object} EpisodeMarker
+ * @property {number | null} season - `null` when neither the name nor a folder states one.
+ * @property {number[]} episodes - The release's numbers, one or more.
+ * @property {number | null} part - Which part of one episode, when the name says so.
+ * @property {boolean} special - Season 0, or a name calling itself a special.
+ * @property {string} showHint - The name's text before the marker, as written.
+ * @property {string} titleHint - The name's text after the marker, part removed, as written.
+ */
+
+/**
+ * Trim a piece of a name to a hint.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function hint(text) {
+  return String(text ?? "").replace(EDGE_SEPARATORS, "").slice(0, MAX_HINT_LENGTH);
+}
+
+/**
+ * The numbers after the first episode in `S01E01E02` or `S01E01-03`.
+ *
+ * A `-` joins a range, a repeated `E` lists another episode.
+ *
+ * @param {number} first
+ * @param {string} rest
+ * @returns {number[] | null} `null` when the claim is longer than any file carries.
+ */
+function episodesFrom(first, rest) {
+  const episodes = [first];
+  for (const token of rest.match(/-?e?\d+/gi) ?? []) {
+    const value = Number(token.replace(/[^0-9]/g, ""));
+    const last = episodes[episodes.length - 1];
+    if (token.startsWith("-") && value > last) {
+      for (let next = last + 1; next <= value; next += 1) {
+        episodes.push(next);
+        if (episodes.length > MAX_EPISODES_PER_FILE) {
+          return null;
+        }
+      }
+    } else if (value !== last) {
+      episodes.push(value);
+    }
+  }
+  return episodes.length > MAX_EPISODES_PER_FILE ? null : episodes;
+}
+
+/**
+ * The season the deepest season-naming folder states, if any does.
+ *
+ * @param {string[]} folders
+ * @returns {number | null}
+ */
+function seasonFromFolders(folders) {
+  for (let index = folders.length - 1; index >= 0; index -= 1) {
+    const match = SEASON_FOLDER.exec(String(folders[index] ?? "").trim());
+    if (match) {
+      return Number(match[1] ?? match[2]);
+    }
+  }
+  return null;
+}
+
+/**
+ * Which episode a picture's name says it is.
+ *
+ * @param {{ name: string, folders?: string[] }} file - File name and the folders above it.
+ * @returns {EpisodeMarker | null}
+ */
+export function readEpisodeMarker({ name, folders = [] }) {
+  const stem = stripExtension(String(name ?? ""));
+  const folderSeason = seasonFromFolders(Array.isArray(folders) ? folders : []);
+
+  let season = null;
+  let episodes = null;
+  let before = "";
+  let after = "";
+
+  const seasonEpisode = SEASON_EPISODE.exec(stem);
+  const cross = seasonEpisode ? null : CROSS.exec(stem);
+  const episodeOnly = seasonEpisode || cross ? null : EPISODE_ONLY.exec(stem);
+  const dash = seasonEpisode || cross || episodeOnly ? null : DASH_NUMBER.exec(stem);
+  const match = seasonEpisode ?? cross ?? episodeOnly ?? dash;
+  if (!match) {
+    return null;
+  }
+  before = stem.slice(0, match.index);
+  after = stem.slice(match.index + match[0].length);
+
+  if (seasonEpisode) {
+    season = Number(seasonEpisode[1]);
+    episodes = episodesFrom(Number(seasonEpisode[2]), seasonEpisode[3] ?? "");
+  } else if (cross) {
+    season = Number(cross[1]);
+    episodes = [Number(cross[2])];
+  } else {
+    // `Show S1 - 01` states its season just before the number; a folder is the
+    // other place a release puts it.
+    const trailingSeason = /(?<![a-z0-9])s(\d{1,3})[\s._-]*$/i.exec(before);
+    season = trailingSeason ? Number(trailingSeason[1]) : folderSeason;
+    if (trailingSeason) {
+      before = before.slice(0, trailingSeason.index);
+    }
+    episodes = [Number(match[1])];
+  }
+  // A year where an episode number would be is a year far more often than an
+  // episode: `Film - 2024 [1080p]`, and `WALL-E.2008.mkv` reads as `E` then
+  // `2008`. Only the markers without a season can be fooled this way.
+  if ((dash || episodeOnly) && /^(?:19|20)\d\d$/.test(match[1])) {
+    return null;
+  }
+  if (!episodes) {
+    return null;
+  }
+
+  const part = PART.exec(after);
+  const titleText = part ? `${after.slice(0, part.index)} ${after.slice(part.index + part[0].length)}` : after;
+
+  return {
+    season,
+    episodes,
+    part: part ? Number(part[1]) : null,
+    special: season === 0 || SPECIAL.test(stem),
+    showHint: hint(before),
+    titleHint: hint(titleText)
+  };
+}

package/services/torrent/torrent-pool.js

@@ -2233,12 +2233,25 @@ export class TorrentPool {
     // deselected null piece — see fileDownloadedBytes).
     const fileLength = typeof file.length === "number" ? file.length : 0;
     const fileDownloaded = fileDownloadedBytes(torrent, file);
+    const residence = [];
+    const store = pieceStoreOf(torrent);
+    const firstPiece = Math.floor(file.offset / torrent.pieceLength);
+    const lastPiece = Math.ceil((file.offset + fileLength) / torrent.pieceLength);
+    for (let index = firstPiece; index < lastPiece; index += 1) {
+      const start = Math.max(0, index * torrent.pieceLength - file.offset);
+      const end = Math.min(fileLength, (index + 1) * torrent.pieceLength - file.offset);
+      const location = store?.locationOf?.(index) ?? (torrent.bitfield?.get(index) ? "available" : "missing");
+      const previous = residence.at(-1);
+      if (previous?.location === location && previous.end === start) previous.end = end;
+      else residence.push({ start, end, location });
+    }
 
     return {
       ...base,
       fileProgress: fileLength > 0 ? Math.max(0, Math.min(1, fileDownloaded / fileLength)) : 0,
       fileDownloaded,
       fileLength,
+      residence,
       // Resume window (ahead of the anchor): bytes needed vs downloaded, plus
       // the anchor itself so the caller can pin it for the rest of one episode.
       resumeNeededBytes: resume ? resume.totalBytes : null,