@torrent-tv/proxy 2.93.4 → 2.94.1

package/package.json

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

package/routes/api/sources/container-metadata/get.js

@@ -0,0 +1,32 @@
+/**
+ * What one file of a registered source states about the work it carries.
+ *
+ * GET /api/sources/:sourceKey/files/:fileIndex/container-metadata
+ *
+ * Answers `200` with the file's statements (`services/media/container/work-tags.js`)
+ * once they are read, `202 { status: "pending" }` while the bytes at the edges of
+ * the file have not arrived (the page asks again), and `404` where the format
+ * states nothing this proxy reads or the file cannot be read. The reading never
+ * asks the swarm for anything beyond the first and the last piece of the file,
+ * which opening a file fetches anyway.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{
+ *   sourceRegistry: { get: (key: string) => unknown },
+ *   inspectWorkTags: (address: { sourceKey: string, fileIndex: number, requestId?: string }) => Promise<{ kind: string, value?: object, reason?: string }>
+ * }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiSourceContainerMetadataGet(req, reply, { sourceRegistry, inspectWorkTags }) {
+  const sourceKey = typeof req.params?.sourceKey === "string" ? req.params.sourceKey.trim() : "";
+  const fileIndex = Number(req.params?.fileIndex);
+  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply.code(400).send({ error: "sourceKey and a file index are required." });
+  }
+  if (!sourceRegistry.get(sourceKey)) return reply.code(404).send({ error: "Source key was not found." });
+  const result = await inspectWorkTags({ sourceKey, fileIndex, requestId: req.id });
+  if (result.kind === "result" && result.value) return reply.send(result.value);
+  if (result.kind === "terminal") return reply.code(404).send({ error: `This file states nothing about the work (${result.reason ?? "unavailable"}).` });
+  return reply.code(202).send({ status: "pending" });
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The cover image one file of a registered source carries inside it.
+ *
+ * GET /api/sources/:sourceKey/files/:fileIndex/cover
+ *
+ * Answers `200` with the image's bytes and its type, `202 { status: "pending" }`
+ * while they have not arrived, and `404` where the file carries none. Nothing
+ * keeps the image but the file itself: the page turns the bytes into a `blob:`
+ * address for as long as it shows them.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{
+ *   sourceRegistry: { get: (key: string) => unknown },
+ *   inspectCover: (address: { sourceKey: string, fileIndex: number, requestId?: string }) => Promise<{ kind: string, value?: { type: string, bytes: Buffer }, reason?: string }>
+ * }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiSourceCoverGet(req, reply, { sourceRegistry, inspectCover }) {
+  const sourceKey = typeof req.params?.sourceKey === "string" ? req.params.sourceKey.trim() : "";
+  const fileIndex = Number(req.params?.fileIndex);
+  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply.code(400).send({ error: "sourceKey and a file index are required." });
+  }
+  if (!sourceRegistry.get(sourceKey)) return reply.code(404).send({ error: "Source key was not found." });
+  const result = await inspectCover({ sourceKey, fileIndex, requestId: req.id });
+  if (result.kind === "result" && result.value) return reply.type(result.value.type).send(result.value.bytes);
+  if (result.kind === "terminal") return reply.code(404).send({ error: `This file carries no cover (${result.reason ?? "unavailable"}).` });
+  return reply.code(202).send({ status: "pending" });
+}

package/server.js

@@ -25,6 +25,8 @@ import { handleApiSourcesPost } from "./routes/api/sources/post.js";
 import { handleApiSourceStatsGet } from "./routes/api/sources/stats/get.js";
 import { handleApiSourceFilesGet } from "./routes/api/sources/files/get.js";
 import { handleApiSourceFingerprintGet } from "./routes/api/sources/fingerprint/get.js";
+import { handleApiSourceContainerMetadataGet } from "./routes/api/sources/container-metadata/get.js";
+import { handleApiSourceCoverGet } from "./routes/api/sources/cover/get.js";
 import { handleApiSourceWarmPost } from "./routes/api/sources/warm/post.js";
 import { handleApiSourceViewerPost } from "./routes/api/sources/viewer/post.js";
 import { handleApiPlaybackPlanPost } from "./routes/api/playback-plan/post.js";
@@ -52,7 +54,7 @@ import { createPlaybackPlanner } from "./services/media/playback-planner.js";
 import { KeyframeTables } from "./services/media/KeyframeTables.js";
 import { contentsOf } from "./services/torrent/Contents.js";
 import { SubtitleOrchestrator } from "./services/media/SubtitleOrchestrator.js";
-import { containerOrchestrator, CONTAINER_HEAD_BYTES } from "./services/media/ContainerOrchestrator.js";
+import { containerOrchestrator, CONTAINER_HEAD_BYTES, describeWorkTags } from "./services/media/ContainerOrchestrator.js";
 import { readPlaybackDeclarations } from "./services/media/read-playback-declarations.js";
 import { DownloadMaps } from "./services/viewer/DownloadMaps.js";
 import { nativeSourceMap } from "./services/viewer/NativeSourceMap.js";
@@ -516,6 +518,7 @@ export async function startProxyServer({
           return probePackets({ url: url.toString(), statement, signal, onRecord });
         } }),
       label: String(file.name ?? ""),
+      fileOffset: file.offset,
       onTracks: (tracks) => contentsOf(torrent).noteVideo(fileIndex, tracks.some((track) => track.type === "video")),
       onReadStart: () => ({ storage: mediaReads.revision(sourceKey, fileIndex), memory: mediaReads.memoryRevision(), demand: downloadMaps.epoch(sourceKey, fileIndex) }),
       onReadResult: async (statement, result, revision) => {
@@ -981,6 +984,33 @@ export async function startProxyServer({
       }
     })
   );
+  // What the opened file states about the work, and its cover: read only from
+  // the edges of the file, which opening it fetches anyway (meta#139).
+  const workTagsLogged = new Set();
+  app.get("/api/sources/:sourceKey/files/:fileIndex/container-metadata", async (req, reply) =>
+    handleApiSourceContainerMetadataGet(req, reply, {
+      sourceRegistry,
+      inspectWorkTags: async (address) => {
+        const params = await containerOver(address);
+        const result = params ? await containerOrchestrator.inspect(params, "work-tags") : { kind: "pending" };
+        const key = `${address.sourceKey}:${address.fileIndex}`;
+        if (result.kind !== "pending" && result.kind !== "needs-ranges" && !workTagsLogged.has(key)) {
+          workTagsLogged.add(key);
+          logger.info(`container metadata "${params?.label ?? ""}": ${describeWorkTags(result)}`);
+        }
+        return result;
+      }
+    })
+  );
+  app.get("/api/sources/:sourceKey/files/:fileIndex/cover", async (req, reply) =>
+    handleApiSourceCoverGet(req, reply, {
+      sourceRegistry,
+      inspectCover: async (address) => {
+        const params = await containerOver(address);
+        return params ? containerOrchestrator.inspect(params, "cover") : { kind: "pending" };
+      }
+    })
+  );
   app.post("/api/sources/:sourceKey/warm", async (req, reply) =>
     handleApiSourceWarmPost(req, reply, {
       sourceRegistry,

package/services/media/ContainerOrchestrator.js

@@ -19,6 +19,7 @@ import { ContainerFactory } from "./container/ContainerFactory.js";
 import { BytesUnavailable, isUnavailable, strictReader } from "./container/unavailable.js";
 import { OSHASH_EDGE_BYTES, hasOshash, oshash } from "./oshash.js";
 import { IndexMemoryUnavailable } from "./container/memory-unavailable.js";
+import { OutsideReadableEdges } from "./container/work-tags.js";
 import { logger } from "../../utils/logger.js";
 
 /**
@@ -45,6 +46,45 @@ async function readFingerprint({ readRange, fileSize }) {
   return { hash: oshash(fileSize, head, tail), size: fileSize };
 }
 
+/**
+ * Which bytes of a file a reading of what it states about the work may ask the
+ * swarm for: the pieces that hold its first and last bytes. Those are fetched
+ * when a file is opened anyway — its OpenSubtitles hash is read from both
+ * edges (`readFingerprint`) and its container head from the first — so a
+ * reading that stays inside them costs no download (torrent-tv/meta#139).
+ *
+ * Where the file lies in the torrent is what decides which pieces those are;
+ * without it, the first and the last piece length of the file are taken, which
+ * is never more than one piece beyond them at each end.
+ *
+ * @param {{ fileSize: number, fileOffset?: number, portionBytes?: number }} params
+ * @returns {(start: number, end: number) => boolean}
+ */
+export function edgesOf({ fileSize, fileOffset, portionBytes }) {
+  const piece = Number.isFinite(portionBytes) && portionBytes > 0 ? portionBytes : CONTAINER_HEAD_BYTES;
+  const offset = Number.isInteger(fileOffset) && fileOffset >= 0 ? fileOffset : null;
+  const headEnd = offset === null ? piece : (Math.floor(offset / piece) + 1) * piece - offset;
+  const tailStart = offset === null ? fileSize - piece : Math.floor((offset + fileSize - 1) / piece) * piece - offset;
+  return (start, end) => end < headEnd || start >= tailStart;
+}
+
+/**
+ * One log line's worth of what a reading of work tags found: which fields the
+ * file states, not their values, and whether something was left outside the
+ * edges — the two things a field check counts.
+ *
+ * @param {{ kind: string, value?: object, reason?: string }} result
+ * @returns {string}
+ */
+export function describeWorkTags(result) {
+  if (result.kind !== "result" || !result.value) return `none (${result.reason ?? result.kind})`;
+  const tags = result.value;
+  const stated = Object.entries(tags)
+    .filter(([key, value]) => key !== "outsideEdges" && (Array.isArray(value) ? value.length > 0 : value && typeof value === "object" ? Object.keys(value).length > 0 : value !== null))
+    .map(([key, value]) => (key === "externalIds" ? `ids:${Object.keys(value).join("+")}` : key));
+  return `${stated.length ? stated.join(" ") : "nothing stated"}${tags.outsideEdges ? " (some elements lie outside the edges and are not held)" : ""}`;
+}
+
 export class ContainerOrchestrator {
   #reads = new Map();
   #lifetimes = new Map();
@@ -89,7 +129,7 @@ export class ContainerOrchestrator {
 
   /** Read one statement without converting missing bytes into an empty answer. */
   async inspect(params, statement = "tracks") {
-    if (!["container", "tracks", "media-info", "keyframes", "packets", "fingerprint"].includes(statement)) {
+    if (!["container", "tracks", "media-info", "keyframes", "packets", "fingerprint", "work-tags", "cover"].includes(statement)) {
       throw new TypeError(`Unknown media statement: ${statement}`);
     }
     const key = `${params.sourceKey}:${params.fileIndex}`;
@@ -148,6 +188,9 @@ export class ContainerOrchestrator {
         value = await container.readMediaInfo();
       } else if (statement === "keyframes") {
         value = await container.readKeyframeIndex();
+      } else if (statement === "work-tags" || statement === "cover") {
+        value = await (statement === "cover" ? container.readCover(edgesOf(params)) : container.readWorkTags(edgesOf(params)));
+        if (value === null) return { kind: "terminal", reason: statement === "cover" ? "no-cover" : "format-states-nothing", requestId };
       } else if (statement === "packets") {
         value = await container.readPacketIndex(params.packetInterval);
         await value?.prepareAudioDependencies?.(params.packetInterval, container.readRange);
@@ -161,6 +204,11 @@ export class ContainerOrchestrator {
         logger.info(`media request=${requestId} needs memory=${error.bytes}`);
         return result;
       }
+      if (error instanceof OutsideReadableEdges) {
+        // Not a fault and not "not here yet": the bytes lie where this reading
+        // may not ask for them. Asked again, it reads them once they are held.
+        return { kind: "terminal", reason: "outside-edges", requestId };
+      }
       if (isUnavailable(error)) {
         const result = { kind: "needs-ranges", ranges: [[error.start, error.end]], requestId };
         logger.info(`media request=${requestId} needs bytes=${error.start}-${error.end}`);

package/services/media/container/AviContainer.js

@@ -14,6 +14,7 @@ import { isUnavailable } from "./unavailable.js";
 import { Mpeg4PictureTiming } from "./mpeg4-picture-timing.js";
 import { MpegElementaryIndex } from "./mpeg-elementary-index.js";
 import { RetainedReads } from "./RetainedReads.js";
+import { OutsideReadableEdges, edgeReader, emptyWorkTags, text, textList, yearOf } from "./work-tags.js";
 
 const MPEG4_CODECS = new Set(["FMP4", "XVID", "DIVX", "DX50", "MP4V", "M4S2", "MP4S"]);
 const MPEG_AUDIO_CODECS = new Set(["mp1", "mp2", "mp3"]);
@@ -25,6 +26,7 @@ export class AviContainer extends Container {
   #packets = null;
   #scan = null;
   #declarations = null;
+  #workTags = null;
 
   async #readHeaders() {
     if (this.#headers) return this.#headers;
@@ -61,6 +63,50 @@ export class AviContainer extends Container {
   get formatName() {
     return "avi";
   }
+  /**
+   * What the file states about the work, from the `LIST INFO` chunk of the
+   * RIFF (Microsoft, "Multimedia Programming Interface and Data
+   * Specifications 1.0", INFO list): `INAM` the title, `IGNR` the genre,
+   * `ICRD` the creation date, `ISBJ` the subject, `ICMT` comments.
+   *
+   * Looked for among the top-level chunks before `movi`, where writers put it;
+   * walking past `movi` would read the header of what follows it, which lies
+   * wherever the film ends. The specification states no character set, so a
+   * value that is not valid UTF-8 is left out rather than shown garbled.
+   *
+   * @param {(start: number, end: number) => boolean} mayFetch
+   * @returns {Promise<import("./work-tags.js").WorkTags>}
+   */
+  async readWorkTags(mayFetch) {
+    if (this.#workTags) return this.#workTags;
+    const tags = emptyWorkTags();
+    const head = await this.readRange(0, Math.min(11, this.fileSize - 1));
+    if (!isAvi(head)) throw new Error("AVI RIFF header is absent.");
+    const end = Math.min(this.fileSize, 8 + head.readUInt32LE(4));
+    const read = edgeReader(this.readRange, mayFetch, isUnavailable);
+    try {
+      const top = await riffChunks(read, 12, end, "movi");
+      const info = top.find((chunk) => chunk.id === "LIST" && chunk.type === "INFO");
+      const fields = new Map();
+      for (const field of info ? await riffChunks(read, info.start + 4, info.end) : []) {
+        if (field.end <= field.start || fields.has(field.id)) continue;
+        const value = (await read(field.start, field.end - 1)).toString("utf8");
+        // U+FFFD is what the decoder puts where the bytes were not UTF-8.
+        if (!value.includes(String.fromCodePoint(0xfffd))) fields.set(field.id, text(value));
+      }
+      tags.title = fields.get("INAM") ?? null;
+      tags.genres = textList([fields.get("IGNR")]);
+      tags.year = yearOf(fields.get("ICRD"));
+      tags.description = fields.get("ISBJ") ?? fields.get("ICMT") ?? null;
+    } catch (error) {
+      if (!(error instanceof OutsideReadableEdges)) throw error;
+      tags.outsideEdges = true;
+    }
+    tags.trackTitles = await this.trackTitlesForWork();
+    if (!tags.outsideEdges) this.#workTags = tags;
+    return tags;
+  }
+
 
   packetIndexBytes() { return (this.#packets ?? this.#scan?.index)?.allocatedBytes() ?? 0; }
 

package/services/media/container/Container.js

@@ -12,7 +12,8 @@
  *  - AVI RIFF §: LIST hdrl, idx1
  */
 
-import { strictReader } from "./unavailable.js";
+import { isUnavailable, strictReader } from "./unavailable.js";
+import { textList } from "./work-tags.js";
 
 /**
  * What one file declares about itself. Every field is either a value the
@@ -495,6 +496,53 @@ export class Container {
     return this.mediaInfo;
   }
 
+  /**
+   * What the file states about the WORK it carries — title, series, season,
+   * episode, year, genre, description, ids, track and chapter titles, and
+   * whether it has a cover — in the one shape of `work-tags.js`.
+   *
+   * `mayFetch` says which bytes this reading may ask the swarm for: the edges
+   * of the file, which playback fetches anyway. Anything elsewhere is read only
+   * if already held, and left out otherwise (`outsideEdges`).
+   *
+   * `null` means this format states nothing about the work that this proxy
+   * reads — a final answer about the format, not "nobody has looked yet".
+   *
+   * @param {(start: number, end: number) => boolean} _mayFetch
+   * @returns {Promise<import("./work-tags.js").WorkTags | null>}
+   */
+  async readWorkTags(_mayFetch) {
+    return null;
+  }
+
+  /**
+   * The titles of the file's tracks, for what it states about its work. A
+   * track table this program refuses to read costs only the titles: the
+   * statements about the work are read from other elements. Bytes that have
+   * not arrived are still "not here yet".
+   *
+   * @returns {Promise<string[]>}
+   */
+  async trackTitlesForWork() {
+    try {
+      return textList((await this.readTracks()).map((track) => track.name));
+    } catch (error) {
+      if (isUnavailable(error)) throw error;
+      return [];
+    }
+  }
+
+  /**
+   * The cover image the file carries, checked to be an image by its bytes.
+   * `null` where it carries none.
+   *
+   * @param {(start: number, end: number) => boolean} _mayFetch
+   * @returns {Promise<{ type: string, bytes: Buffer } | null>}
+   */
+  async readCover(_mayFetch) {
+    return null;
+  }
+
   /**
    * 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.

package/services/media/container/MatroskaContainer.js

@@ -45,6 +45,14 @@ import { ElementReader } from "./ebml-stream.js";
 import { firstFrameOffset, readBlockHeader, walkHeldClusters } from "./matroska-clusters.js";
 import { readMatroskaPackets } from "./matroska-packets.js";
 import { RetainedReads } from "./RetainedReads.js";
+import { isUnavailable } from "./unavailable.js";
+import {
+  ID_ATTACHED_FILE, ID_ATTACHMENTS, ID_CHAPTERS, ID_FILE_DATA, ID_FILE_MEDIA_TYPE, ID_FILE_NAME, ID_INFO_TITLE, ID_TAGS,
+  chapterTitlesOf, coverIndexOf, workFromTags
+} from "./matroska-work-tags.js";
+import {
+  COVER_TYPES, MAX_COVER_BYTES, OutsideReadableEdges, edgeReader, emptyWorkTags, imageTypeOf, isNumberingOnly, text, textList
+} from "./work-tags.js";
 
 const ID_EBML = 0x1a45dfa3;
 const ID_SEGMENT = 0x18538067;
@@ -124,6 +132,10 @@ function readString(buf, el) {
  *   the walk to the first cluster or from the SeekHead.
  * @property {number | null} tracksAt
  * @property {number | null} cuesAt
+ * @property {number | null} tagsAt
+ * @property {number | null} chaptersAt
+ * @property {number | null} attachmentsAt
+ * @property {string | null} segmentTitle - `Info/Title`, RFC 9559 §5.1.2.12.
  * @property {number | null} firstClusterAt
  */
 
@@ -145,6 +157,15 @@ export class MatroskaContainer extends Container {
    */
   #cues = undefined;
 
+  /** @type {import("./work-tags.js").WorkTags | null} */
+  #workTags = null;
+
+  /**
+   * Where the cover's data lies: undefined until looked for, null for none.
+   * @type {{ at: number, size: number, mediaType: string } | null | undefined}
+   */
+  #coverAt = undefined;
+
   get formatName() {
     return "matroska";
   }
@@ -293,6 +314,7 @@ export class MatroskaContainer extends Container {
     const positionOf = (id) => found.get(id) ?? seeks.get(id) ?? null;
 
     let secondsPerTick = DEFAULT_TIMESTAMP_SCALE / 1e9;
+    let segmentTitle = null;
     const infoAt = positionOf(ID_INFO);
     if (infoAt !== null) {
       const info = await reader.header(infoAt, segmentEnd);
@@ -304,6 +326,8 @@ export class MatroskaContainer extends Container {
             if (scale > 0) {
               secondsPerTick = scale / 1e9;
             }
+          } else if (field.id === ID_INFO_TITLE) {
+            segmentTitle = readString(data, field);
           }
         }
       }
@@ -315,6 +339,10 @@ export class MatroskaContainer extends Container {
       infoAt,
       tracksAt: positionOf(ID_TRACKS),
       cuesAt: positionOf(ID_CUES),
+      tagsAt: positionOf(ID_TAGS),
+      chaptersAt: positionOf(ID_CHAPTERS),
+      attachmentsAt: positionOf(ID_ATTACHMENTS),
+      segmentTitle,
       firstClusterAt: firstClusterAt ?? seeks.get(ID_CLUSTER) ?? null
     };
     return this.#layout;
@@ -366,6 +394,116 @@ export class MatroskaContainer extends Container {
     return info;
   }
 
+  /**
+   * What the file states about the work: `Info/Title`, the `Tags` that apply
+   * to the whole file, the titles of its chapters and tracks, and whether it
+   * carries a cover (see `matroska-work-tags.js`).
+   *
+   * Each element is read on its own, so one that lies outside the bytes this
+   * reading may fetch costs only itself. A reading that left something out is
+   * not kept: the bytes may be held by the next ask.
+   *
+   * @param {(start: number, end: number) => boolean} mayFetch
+   * @returns {Promise<import("./work-tags.js").WorkTags>}
+   */
+  async readWorkTags(mayFetch) {
+    if (this.#workTags) return this.#workTags;
+    const tags = emptyWorkTags();
+    const layout = await this.#segmentLayout();
+    if (!layout) {
+      this.#workTags = tags;
+      return tags;
+    }
+    tags.segmentTitle = text(layout.segmentTitle);
+    const reader = new ElementReader({ read: edgeReader(this.readRange, mayFetch, isUnavailable), fileSize: this.fileSize, portionBytes: this.portionBytes });
+    const leftOut = (error) => {
+      if (!(error instanceof OutsideReadableEdges)) throw error;
+      tags.outsideEdges = true;
+    };
+    const dataOf = async (at, id) => {
+      if (at === null) return null;
+      const header = await reader.header(at, layout.segmentEnd);
+      return header && header.id === id ? reader.data(header) : null;
+    };
+    try {
+      const data = await dataOf(layout.tagsAt, ID_TAGS);
+      if (data) Object.assign(tags, workFromTags(data));
+    } catch (error) { leftOut(error); }
+    try {
+      const data = await dataOf(layout.chaptersAt, ID_CHAPTERS);
+      if (data) tags.chapterTitles = textList(chapterTitlesOf(data).filter((title) => !isNumberingOnly(title)));
+    } catch (error) { leftOut(error); }
+    try {
+      const cover = await this.#coverAddress(reader, layout);
+      if (cover && cover.size > 0 && cover.size <= MAX_COVER_BYTES) tags.cover = { type: cover.mediaType, size: cover.size };
+    } catch (error) { leftOut(error); }
+    tags.trackTitles = await this.trackTitlesForWork();
+    if (!tags.outsideEdges) this.#workTags = tags;
+    return tags;
+  }
+
+  /**
+   * The cover the file carries as an attachment, its bytes checked to be the
+   * image its type says. `null` where there is none, it is larger than
+   * {@link MAX_COVER_BYTES}, or its bytes are not an image a browser shows.
+   *
+   * @param {(start: number, end: number) => boolean} mayFetch
+   * @returns {Promise<{ type: string, bytes: Buffer } | null>}
+   */
+  async readCover(mayFetch) {
+    const layout = await this.#segmentLayout();
+    if (!layout) return null;
+    const read = edgeReader(this.readRange, mayFetch, isUnavailable);
+    const reader = new ElementReader({ read, fileSize: this.fileSize, portionBytes: this.portionBytes });
+    const cover = await this.#coverAddress(reader, layout);
+    if (!cover || cover.size === 0 || cover.size > MAX_COVER_BYTES) return null;
+    const bytes = Buffer.from(await read(cover.at, cover.at + cover.size - 1));
+    const type = imageTypeOf(bytes);
+    return type && COVER_TYPES.has(type) ? { type, bytes } : null;
+  }
+
+  /**
+   * Where the cover's data lies, from the headers of the attachments: each
+   * `AttachedFile`'s name and media type are read, its data never — fonts of
+   * an anime release are megabytes each.
+   *
+   * @param {ElementReader} reader
+   * @param {SegmentLayout} layout
+   * @returns {Promise<{ at: number, size: number, mediaType: string } | null>}
+   */
+  async #coverAddress(reader, layout) {
+    if (this.#coverAt !== undefined) return this.#coverAt;
+    if (layout.attachmentsAt === null) return (this.#coverAt = null);
+    const attachments = await reader.header(layout.attachmentsAt, layout.segmentEnd);
+    if (!attachments || attachments.id !== ID_ATTACHMENTS || attachments.end === null) return (this.#coverAt = null);
+    const files = [];
+    for (let at = attachments.dataOffset; at < attachments.end;) {
+      const file = await reader.header(at, attachments.end);
+      if (!file || file.end === null) break;
+      if (file.id === ID_ATTACHED_FILE) {
+        const found = { name: "", mediaType: "", at: null, size: 0 };
+        for (let inner = file.dataOffset; inner < file.end;) {
+          const field = await reader.header(inner, file.end);
+          if (!field || field.end === null) break;
+          if (field.id === ID_FILE_NAME || field.id === ID_FILE_MEDIA_TYPE) {
+            const value = (await reader.data(field))?.toString("utf8").replace(/\0+$/u, "") ?? "";
+            if (field.id === ID_FILE_NAME) found.name = value;
+            else found.mediaType = value.toLowerCase();
+          } else if (field.id === ID_FILE_DATA) {
+            found.at = field.dataOffset;
+            found.size = field.size ?? 0;
+          }
+          inner = field.end;
+        }
+        if (found.at !== null) files.push(found);
+      }
+      at = file.end;
+    }
+    const index = coverIndexOf(files);
+    this.#coverAt = index < 0 ? null : { at: files[index].at, size: files[index].size, mediaType: files[index].mediaType || "image/jpeg" };
+    return this.#coverAt;
+  }
+
   /**
    * Every track the file declares, in its order, read once.
    *

package/services/media/container/Mp4Container.js

@@ -27,6 +27,8 @@ import { h264Configuration } from "./h264-configuration.js";
 import { hevcConfiguration } from "./hevc-configuration.js";
 import { mpegAudioFrame } from "./mpeg-audio-frame.js";
 import { readMp4Fragments } from "./mp4-fragments.js";
+import { workFromMoov } from "./mp4-work-tags.js";
+import { COVER_TYPES, MAX_COVER_BYTES, emptyWorkTags, imageTypeOf } from "./work-tags.js";
 
 /** A box header is eight bytes, or sixteen when the size field says 1 (§4.2). */
 const HEADER_BYTES = 8;
@@ -513,6 +515,44 @@ export class Mp4Container extends Container {
     return this.moovHeld;
   }
 
+  /**
+   * What the file states about the work, from the `moov` box this class
+   * already holds for its tracks (see `mp4-work-tags.js`). The box is a read
+   * playback makes anyway, so `mayFetch` has nothing to decide here.
+   *
+   * @param {(start: number, end: number) => boolean} _mayFetch
+   * @returns {Promise<import("./work-tags.js").WorkTags>}
+   */
+  async readWorkTags(_mayFetch) {
+    if (this.workTags) return this.workTags;
+    const tags = emptyWorkTags();
+    const held = await this.#moovBuffer();
+    if (held) {
+      const { work, cover } = workFromMoov(held.moov, held.header);
+      Object.assign(tags, work);
+      if (cover && cover.size > 0 && cover.size <= MAX_COVER_BYTES) tags.cover = { type: cover.type, size: cover.size };
+    }
+    tags.trackTitles = await this.trackTitlesForWork();
+    this.workTags = tags;
+    return tags;
+  }
+
+  /**
+   * The cover the item list carries, its bytes checked to be the image its
+   * type says. `null` where there is none or it is larger than {@link MAX_COVER_BYTES}.
+   *
+   * @param {(start: number, end: number) => boolean} _mayFetch
+   * @returns {Promise<{ type: string, bytes: Buffer } | null>}
+   */
+  async readCover(_mayFetch) {
+    const held = await this.#moovBuffer();
+    const cover = held ? workFromMoov(held.moov, held.header).cover : null;
+    if (!cover || cover.size === 0 || cover.size > MAX_COVER_BYTES) return null;
+    const bytes = Buffer.from(held.moov.subarray(cover.at, cover.at + cover.size));
+    const type = imageTypeOf(bytes);
+    return type && COVER_TYPES.has(type) ? { type, bytes } : null;
+  }
+
   /** Exact decode-order samples from the same moov used for all metadata. */
   async readPacketIndex() {
     if (this.packetIndex) return this.packetIndex;

package/services/media/container/matroska-work-tags.js

@@ -0,0 +1,217 @@
+/**
+ * @file What a Matroska file states about the work, per the Matroska tagging
+ * specification (matroska.org, "Tags" and "Tagging"), RFC 9559 §5.1.7
+ * (Chapters), §5.1.6 (Attachments) and §5.1.8 (Tags).
+ *
+ * A `Tag` applies to what its `Targets` name. `TargetTypeValue` states the
+ * level (70 a collection, 60 a season or volume, 50 an episode or a film, 30 a
+ * chapter or a scene) and is 50 when absent. A `Tag` whose `Targets` name a
+ * particular track, edition, chapter or attachment by a non-zero UID describes
+ * that one only — mkvmerge's per-track statistics are of this kind — and says
+ * nothing about the work.
+ *
+ * Parsing over buffers already read; where the bytes come from is the
+ * container's business.
+ */
+
+import { iterateElements, readUint } from "./ebml-reader.js";
+import { externalIdsOf, text, textList, wholeNumber, yearOf } from "./work-tags.js";
+
+export const ID_TAGS = 0x1254c367;
+export const ID_CHAPTERS = 0x1043a770;
+export const ID_ATTACHMENTS = 0x1941a469;
+export const ID_INFO_TITLE = 0x7ba9;
+
+const ID_TAG = 0x7373;
+const ID_TARGETS = 0x63c0;
+const ID_TARGET_TYPE_VALUE = 0x68ca;
+const TARGET_UIDS = new Set([0x63c5, 0x63c9, 0x63c4, 0x63c6]);
+const ID_SIMPLE_TAG = 0x67c8;
+const ID_TAG_NAME = 0x45a3;
+const ID_TAG_STRING = 0x4487;
+const ID_TAG_DEFAULT = 0x4484;
+
+const ID_EDITION_ENTRY = 0x45b9;
+const ID_CHAPTER_ATOM = 0xb6;
+const ID_CHAPTER_DISPLAY = 0x80;
+const ID_CHAP_STRING = 0x85;
+const ID_CHAPTER_FLAG_HIDDEN = 0x98;
+
+export const ID_ATTACHED_FILE = 0x61a7;
+export const ID_FILE_NAME = 0x466e;
+export const ID_FILE_MEDIA_TYPE = 0x4660;
+export const ID_FILE_DATA = 0x465c;
+
+/** The level a `Tag` applies to when its `Targets` say nothing (Matroska tagging). */
+const DEFAULT_TARGET_TYPE_VALUE = 50;
+
+const string = (buffer, element) => buffer.toString("utf8", element.dataOffset, element.dataOffset + element.size).replace(/\0+$/u, "");
+
+/**
+ * Every `SimpleTag` of one `Tag`, nested ones included, as name and value.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start
+ * @param {number} end
+ * @param {Array<{ name: string, value: string, isDefault: boolean }>} out
+ */
+function simpleTags(buffer, start, end, out) {
+  for (const element of iterateElements(buffer, start, end)) {
+    if (element.id !== ID_SIMPLE_TAG) continue;
+    const limit = Math.min(end, element.dataOffset + element.size);
+    let name = null;
+    let value = null;
+    let isDefault = true;
+    for (const field of iterateElements(buffer, element.dataOffset, limit)) {
+      if (field.id === ID_TAG_NAME) name = string(buffer, field).toUpperCase();
+      else if (field.id === ID_TAG_STRING) value = string(buffer, field);
+      else if (field.id === ID_TAG_DEFAULT) isDefault = readUint(buffer, field.dataOffset, field.size) !== 0;
+    }
+    if (name && value !== null) out.push({ name, value, isDefault });
+    simpleTags(buffer, element.dataOffset, limit, out);
+  }
+}
+
+/**
+ * The `Tag`s of a `Tags` element that describe the work, grouped by level.
+ *
+ * @param {Buffer} data - The data of a `Tags` element.
+ * @returns {Map<number, Array<{ name: string, value: string, isDefault: boolean }>>}
+ */
+export function tagsByLevel(data) {
+  /** @type {Map<number, Array<{ name: string, value: string, isDefault: boolean }>>} */
+  const levels = new Map();
+  for (const tag of iterateElements(data)) {
+    if (tag.id !== ID_TAG) continue;
+    const end = Math.min(data.length, tag.dataOffset + tag.size);
+    let level = DEFAULT_TARGET_TYPE_VALUE;
+    let particular = false;
+    for (const element of iterateElements(data, tag.dataOffset, end)) {
+      if (element.id !== ID_TARGETS) continue;
+      for (const field of iterateElements(data, element.dataOffset, Math.min(end, element.dataOffset + element.size))) {
+        if (field.id === ID_TARGET_TYPE_VALUE) level = readUint(data, field.dataOffset, field.size);
+        else if (TARGET_UIDS.has(field.id) && readUint(data, field.dataOffset, field.size) !== 0) particular = true;
+      }
+    }
+    if (particular) continue;
+    const found = [];
+    simpleTags(data, tag.dataOffset, end, found);
+    if (!levels.has(level)) levels.set(level, []);
+    levels.get(level).push(...found);
+  }
+  return levels;
+}
+
+/**
+ * The values one level states for one name, the default one first.
+ *
+ * @param {Map<number, Array<{ name: string, value: string, isDefault: boolean }>>} levels
+ * @param {number} level
+ * @param {string[]} names
+ * @returns {string[]}
+ */
+function valuesOf(levels, level, names) {
+  const at = (levels.get(level) ?? []).filter((tag) => names.includes(tag.name));
+  return [...at.filter((tag) => tag.isDefault), ...at.filter((tag) => !tag.isDefault)].map((tag) => tag.value);
+}
+
+/**
+ * What the `Tags` element states about the work.
+ *
+ * An episode is recognised by what the file states, never by a name: a season
+ * number (`PART_NUMBER` at level 60) or an episode number (`PART_NUMBER` at
+ * level 50). For an episode the level-50 `TITLE` is the episode's and the
+ * level-70 one is the series'; otherwise the level-50 `TITLE` is the film's.
+ * The year of a series is its level-70 date; a level-50 date of an episode is
+ * the episode's and is kept apart.
+ *
+ * @param {Buffer} data
+ * @returns {Partial<import("./work-tags.js").WorkTags>}
+ */
+export function workFromTags(data) {
+  const levels = tagsByLevel(data);
+  const first = (level, ...names) => valuesOf(levels, level, names)[0];
+  const season = wholeNumber(first(60, "PART_NUMBER"), 0, 999);
+  const episode = wholeNumber(first(50, "PART_NUMBER"), 0, 9999);
+  const isEpisode = season !== null || episode !== null;
+  const itemTitles = valuesOf(levels, 50, ["TITLE"]);
+  const collectionTitles = valuesOf(levels, 70, ["TITLE"]);
+  const itemDate = first(50, "DATE_RELEASED", "DATE_RECORDED", "DATE_ENCODED");
+  const collectionDate = first(70, "DATE_RELEASED", "DATE_RECORDED");
+  const statedAt = (...names) => [70, 60, 50, 30].flatMap((level) => valuesOf(levels, level, names));
+  return {
+    title: text(isEpisode ? collectionTitles[0] : itemTitles[0]),
+    otherTitles: textList(isEpisode ? collectionTitles.slice(1) : itemTitles.slice(1)),
+    seriesTitle: isEpisode ? text(collectionTitles[0]) : null,
+    season,
+    episode,
+    episodeTitle: isEpisode ? text(itemTitles[0]) : null,
+    year: isEpisode ? yearOf(collectionDate) : yearOf(itemDate),
+    itemYear: isEpisode ? yearOf(itemDate) : null,
+    genres: textList(statedAt("GENRE")),
+    description: text([50, 70].flatMap((level) => valuesOf(levels, level, ["DESCRIPTION", "SYNOPSIS", "SUMMARY"]))[0]),
+    externalIds: externalIdsOf({
+      imdb: [50, 70].flatMap((level) => valuesOf(levels, level, ["IMDB"]))[0],
+      tmdb: [70, 50].flatMap((level) => valuesOf(levels, level, ["TMDB"]))[0],
+      tvdb: [70, 50].flatMap((level) => valuesOf(levels, level, ["TVDB"]))[0]
+    })
+  };
+}
+
+/**
+ * The titles of the chapters a file states, hidden ones left out, nested ones
+ * included, in their order.
+ *
+ * @param {Buffer} data - The data of a `Chapters` element.
+ * @returns {string[]}
+ */
+export function chapterTitlesOf(data) {
+  const titles = [];
+  const atoms = (start, end) => {
+    for (const element of iterateElements(data, start, end)) {
+      const limit = Math.min(end, element.dataOffset + element.size);
+      if (element.id === ID_EDITION_ENTRY) atoms(element.dataOffset, limit);
+      if (element.id !== ID_CHAPTER_ATOM) continue;
+      let hidden = false;
+      let title = null;
+      for (const field of iterateElements(data, element.dataOffset, limit)) {
+        if (field.id === ID_CHAPTER_FLAG_HIDDEN) hidden = readUint(data, field.dataOffset, field.size) !== 0;
+        if (field.id === ID_CHAPTER_DISPLAY && title === null) {
+          for (const display of iterateElements(data, field.dataOffset, Math.min(limit, field.dataOffset + field.size))) {
+            if (display.id === ID_CHAP_STRING) {
+              title = string(data, display);
+              break;
+            }
+          }
+        }
+      }
+      if (!hidden && title) titles.push(title);
+      atoms(element.dataOffset, limit);
+    }
+  };
+  atoms(0, data.length);
+  return titles;
+}
+
+/**
+ * Which attachment is the cover, by the names the Matroska attachments
+ * specification gives covers (`cover`, `cover_land`, `small_cover`,
+ * `small_cover_land`, any image extension), the full-size portrait one first.
+ *
+ * @param {Array<{ name: string, mediaType: string }>} files
+ * @returns {number} The index of the cover, or -1.
+ */
+export function coverIndexOf(files) {
+  const ranks = ["cover", "cover_land", "small_cover", "small_cover_land"];
+  let best = -1;
+  let bestRank = ranks.length;
+  files.forEach((file, index) => {
+    const match = /^(.+)\.(?:jpe?g|png|webp|gif|bmp)$/iu.exec(file.name.trim());
+    const rank = match ? ranks.indexOf(match[1].toLowerCase()) : -1;
+    if (rank >= 0 && rank < bestRank && /^image\//iu.test(file.mediaType || "image/")) {
+      best = index;
+      bestRank = rank;
+    }
+  });
+  return best;
+}

package/services/media/container/mp4-work-tags.js

@@ -0,0 +1,220 @@
+/**
+ * @file What an MP4 or QuickTime file states about the work, from the `moov`
+ * box the container already holds for its tracks.
+ *
+ * Three places carry it, and a file may use any of them:
+ *
+ *  1. the iTunes item list — `moov/udta/meta` with handler `mdir`, then `ilst`,
+ *     each item a box named by its four characters (`©nam`, `tvsh`, `tvsn`,
+ *     `tves`, `tven`, `©gen`, `©day`, `desc`, `ldes`, `©cmt`, `stik`, `covr`)
+ *     holding a `data` box: a type indicator, a locale, then the value
+ *     (Apple, "QuickTime File Format", Metadata, "Data atom"; the well-known
+ *     types 1 UTF-8, 13 JPEG, 14 PNG, 21 big-endian signed integer, 27 BMP);
+ *  2. QuickTime metadata keys — `meta` with handler `mdta`, a `keys` box naming
+ *     each item, and `ilst` items addressed by the 1-based index of their key
+ *     (`com.apple.quicktime.title`, `.genre`, `.description`, `.year`,
+ *     `.creationdate`, `.artwork`);
+ *  3. QuickTime user data text — `moov/udta/©nam` and its kind, each a 16-bit
+ *     length, a 16-bit language and the text.
+ *
+ * The LostFilm files measured in #136 use the first: `©nam` is the episode,
+ * `tvsh` the series, `tvsn`/`tves` the season and episode. An item that is a TV
+ * episode is recognised by what the file states (`tvsh`, `tvsn`, `tves`, or
+ * `stik` 10, "TV Show"), never by a name.
+ */
+
+import { text, textList, wholeNumber, yearOf } from "./work-tags.js";
+
+const TYPE_UTF8 = 1;
+const TYPE_UTF16 = 2;
+const TYPE_JPEG = 13;
+const TYPE_PNG = 14;
+const TYPE_INTEGER = 21;
+const TYPE_UNSIGNED = 22;
+const TYPE_BMP = 27;
+
+/** `stik` 10: the item is an episode of a TV show (Apple). */
+const MEDIA_KIND_TV_SHOW = 10;
+
+/**
+ * The boxes directly inside a range.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start
+ * @param {number} end
+ * @returns {Array<{ type: string, rawType: number, dataOffset: number, end: number }>}
+ */
+function boxes(buffer, start, end) {
+  const out = [];
+  for (let at = start; at + 8 <= end;) {
+    let size = buffer.readUInt32BE(at);
+    let header = 8;
+    if (size === 1) {
+      if (at + 16 > end) break;
+      size = Number(buffer.readBigUInt64BE(at + 8));
+      header = 16;
+    } else if (size === 0) {
+      size = end - at;
+    }
+    if (size < header || at + size > end) break;
+    out.push({ type: buffer.toString("latin1", at + 4, at + 8), rawType: buffer.readUInt32BE(at + 4), dataOffset: at + header, end: at + size });
+    at += size;
+  }
+  return out;
+}
+
+const child = (buffer, box, type) => boxes(buffer, box.dataOffset, box.end).find((one) => one.type === type) ?? null;
+
+/**
+ * The children of a `meta` box. ISO/IEC 14496-12 makes it a full box (four
+ * bytes of version and flags before its children); QuickTime writes it without
+ * them. Which one a file wrote is read from where the handler box is.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} meta
+ */
+function metaChildren(buffer, meta) {
+  const plain = meta.dataOffset + 8 <= meta.end && buffer.toString("latin1", meta.dataOffset + 4, meta.dataOffset + 8) === "hdlr";
+  return boxes(buffer, meta.dataOffset + (plain ? 0 : 4), meta.end);
+}
+
+/**
+ * The value of one item's first `data` box.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} item
+ * @returns {{ type: number, value: Buffer, at: number } | null}
+ */
+function dataOf(buffer, item) {
+  const data = boxes(buffer, item.dataOffset, item.end).find((one) => one.type === "data");
+  if (!data || data.end - data.dataOffset < 8) return null;
+  const type = buffer.readUInt32BE(data.dataOffset) & 0xffffff;
+  return { type, value: buffer.subarray(data.dataOffset + 8, data.end), at: data.dataOffset + 8 };
+}
+
+/** @param {{ type: number, value: Buffer }} data */
+function stringOf(data) {
+  if (!data) return null;
+  // Type 2 is UTF-16 big-endian; Node reads only little-endian, so the bytes are swapped on a copy.
+  if (data.type === TYPE_UTF16) return data.value.length % 2 === 0 ? text(Buffer.from(data.value).swap16().toString("utf16le")) : null;
+  // Type 0 is "implicit"; writers use it for text as often as for anything else.
+  return data.type === TYPE_UTF8 || data.type === 0 ? text(data.value.toString("utf8")) : null;
+}
+
+/** @param {{ type: number, value: Buffer }} data */
+function integerOf(data) {
+  if (!data || ![0, TYPE_INTEGER, TYPE_UNSIGNED].includes(data.type)) return null;
+  const { value } = data;
+  if (value.length === 1) return value.readUInt8(0);
+  if (value.length === 2) return value.readUInt16BE(0);
+  if (value.length === 4) return data.type === TYPE_INTEGER ? value.readInt32BE(0) : value.readUInt32BE(0);
+  if (value.length === 8) return Number(value.readBigUInt64BE(0));
+  return null;
+}
+
+/** The image type an item's data type states. */
+function imageType(data) {
+  if (!data) return null;
+  if (data.type === TYPE_JPEG) return "image/jpeg";
+  if (data.type === TYPE_PNG) return "image/png";
+  if (data.type === TYPE_BMP) return "image/bmp";
+  return data.type === 0 ? "image/jpeg" : null;
+}
+
+/**
+ * Every item one `meta` box states, by name: an iTunes four-character name, or
+ * for an `mdta` list the key the item's index points at.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} meta
+ * @returns {Map<string, { type: number, value: Buffer, at: number }>}
+ */
+function itemsOf(buffer, meta) {
+  const items = new Map();
+  const children = metaChildren(buffer, meta);
+  const hdlr = children.find((one) => one.type === "hdlr");
+  const handler = hdlr && hdlr.end - hdlr.dataOffset >= 12 ? buffer.toString("latin1", hdlr.dataOffset + 8, hdlr.dataOffset + 12) : "";
+  const ilst = children.find((one) => one.type === "ilst");
+  if (!ilst) return items;
+  /** @type {string[]} */
+  const keys = [];
+  if (handler === "mdta") {
+    const keysBox = children.find((one) => one.type === "keys");
+    if (keysBox) {
+      for (const key of boxes(buffer, keysBox.dataOffset + 8, keysBox.end)) keys.push(buffer.toString("utf8", key.dataOffset, key.end));
+    }
+  }
+  for (const item of boxes(buffer, ilst.dataOffset, ilst.end)) {
+    const name = handler === "mdta" ? keys[item.rawType - 1] : item.type;
+    const data = name ? dataOf(buffer, item) : null;
+    if (data && !items.has(name)) items.set(name, data);
+  }
+  return items;
+}
+
+/**
+ * QuickTime user data text atoms directly inside `udta` (`©nam` and its kind).
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} udta
+ * @returns {Map<string, string>}
+ */
+function userDataTexts(buffer, udta) {
+  const texts = new Map();
+  for (const box of boxes(buffer, udta.dataOffset, udta.end)) {
+    if (box.type.charCodeAt(0) !== 0xa9 || box.end - box.dataOffset < 4) continue;
+    const length = buffer.readUInt16BE(box.dataOffset);
+    const value = text(buffer.toString("utf8", box.dataOffset + 4, Math.min(box.end, box.dataOffset + 4 + length)));
+    if (value && !texts.has(box.type)) texts.set(box.type, value);
+  }
+  return texts;
+}
+
+/**
+ * What a `moov` box states about the work, and where its cover lies inside it.
+ *
+ * @param {Buffer} moov - The whole box, its header included.
+ * @param {number} header - The size of its header.
+ * @returns {{ work: Partial<import("./work-tags.js").WorkTags>, cover: { type: string, at: number, size: number } | null }}
+ */
+export function workFromMoov(moov, header) {
+  const root = { dataOffset: header, end: moov.length };
+  const udta = child(moov, root, "udta");
+  /** @type {Map<string, { type: number, value: Buffer, at: number }>} */
+  const items = new Map();
+  for (const meta of [udta && child(moov, udta, "meta"), child(moov, root, "meta")]) {
+    if (!meta) continue;
+    for (const [name, data] of itemsOf(moov, meta)) if (!items.has(name)) items.set(name, data);
+  }
+  const texts = udta ? userDataTexts(moov, udta) : new Map();
+  const say = (...names) => {
+    for (const name of names) {
+      const value = items.has(name) ? stringOf(items.get(name)) : texts.get(name) ?? null;
+      if (value) return value;
+    }
+    return null;
+  };
+  const show = say("tvsh");
+  const season = wholeNumber(integerOf(items.get("tvsn")), 0, 999);
+  const episode = wholeNumber(integerOf(items.get("tves")), 0, 9999);
+  const isEpisode = Boolean(show) || season !== null || episode !== null || integerOf(items.get("stik")) === MEDIA_KIND_TV_SHOW;
+  const name = say("©nam", "com.apple.quicktime.title", "com.apple.quicktime.displayname");
+  const date = say("©day", "com.apple.quicktime.year", "com.apple.quicktime.creationdate");
+  const artwork = items.get("covr") ?? items.get("com.apple.quicktime.artwork") ?? null;
+  const coverType = imageType(artwork);
+  return {
+    work: {
+      title: isEpisode ? show : name,
+      seriesTitle: show,
+      season,
+      episode,
+      episodeId: say("tven"),
+      episodeTitle: isEpisode ? name : null,
+      year: isEpisode ? null : yearOf(date),
+      itemYear: isEpisode ? yearOf(date) : null,
+      genres: textList([say("©gen", "com.apple.quicktime.genre")]),
+      description: say("ldes", "desc", "com.apple.quicktime.description", "©des", "©cmt")
+    },
+    cover: artwork && coverType ? { type: coverType, at: artwork.at, size: artwork.value.length } : null
+  };
+}

package/services/media/container/work-tags.js

@@ -0,0 +1,205 @@
+/**
+ * @file What a file states about the WORK it carries — title, series, season,
+ * episode, year, genre, description, external ids, track and chapter titles,
+ * a cover — in one shape for every container.
+ *
+ * Each container reads its own format's fields (Matroska `Tags`, `Chapters` and
+ * `Attachments`; MP4's iTunes item list and QuickTime metadata keys; AVI's
+ * `LIST INFO`) and states them here by meaning, so the reader of the answer
+ * never needs to know which format said it. Nothing here interprets a value
+ * beyond the format's own definition: whether a title is a release name, and
+ * how much a field is trusted, is decided by whoever identifies the work.
+ *
+ * These fields are read only from bytes the proxy already fetches for playback
+ * — the first and the last piece of the file, and whatever is already held —
+ * so reading them never asks the swarm for anything (torrent-tv/meta#139). A
+ * field whose bytes lie elsewhere and have not arrived is left out, and the
+ * answer says so in `outsideEdges`.
+ */
+
+/** Longest text taken from one field, in characters. A stated limit. */
+export const MAX_TEXT = 2000;
+
+/** Most genres, track titles or chapter titles kept. A stated limit. */
+export const MAX_LIST = 32;
+
+/** Largest cover image read, in bytes. A stated limit: covers measured in #136 are tens of kilobytes. */
+export const MAX_COVER_BYTES = 4 * 1024 * 1024;
+
+/** Image types a cover may have; anything else is not shown by a browser as a poster. */
+export const COVER_TYPES = new Set(["image/jpeg", "image/png", "image/webp", "image/gif", "image/bmp"]);
+
+/**
+ * @typedef {object} WorkTags
+ * @property {string | null} title - The title of what the file holds: the film,
+ *   or for an episode the series.
+ * @property {string[]} otherTitles - Further titles the file states for the same thing.
+ * @property {string | null} segmentTitle - A title the container states for the
+ *   file as a whole without saying what it names (Matroska `Info/Title`); often
+ *   a release name.
+ * @property {string | null} seriesTitle
+ * @property {number | null} season
+ * @property {number | null} episode
+ * @property {string | null} episodeId - An episode code as written (`101`).
+ * @property {string | null} episodeTitle
+ * @property {number | null} year - The year of the work: of the film, or of the series.
+ * @property {number | null} itemYear - The year of one episode, where the file states it apart.
+ * @property {string[]} genres
+ * @property {string | null} description
+ * @property {{ imdb?: string, tmdb?: { kind: "movie" | "tv", id: number }, tvdb?: number }} externalIds
+ * @property {string[]} trackTitles
+ * @property {string[]} chapterTitles
+ * @property {{ type: string, size: number } | null} cover - What the cover is; its
+ *   bytes are read by `readCover`.
+ * @property {boolean} outsideEdges - Some element lies outside the bytes this
+ *   reading may fetch and was not held; it was left out.
+ */
+
+/** @returns {WorkTags} */
+export function emptyWorkTags() {
+  return {
+    title: null, otherTitles: [], segmentTitle: null, seriesTitle: null, season: null, episode: null, episodeId: null,
+    episodeTitle: null, year: null, itemYear: null, genres: [], description: null, externalIds: {},
+    trackTitles: [], chapterTitles: [], cover: null, outsideEdges: false
+  };
+}
+
+/**
+ * A text field, trimmed and bounded; `null` for nothing.
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function text(value) {
+  if (typeof value !== "string") return null;
+  // Control characters other than tab and line breaks are padding or damage, not text.
+  const clean = [...value].filter((char) => {
+    const code = char.codePointAt(0) ?? 0;
+    return code >= 0x20 || code === 0x09 || code === 0x0a || code === 0x0d;
+  }).join("").trim();
+  return clean.length > 0 ? clean.slice(0, MAX_TEXT) : null;
+}
+
+/**
+ * A whole number written as text or stored as one, within bounds.
+ *
+ * @param {unknown} value
+ * @param {number} min
+ * @param {number} max
+ * @returns {number | null}
+ */
+export function wholeNumber(value, min, max) {
+  const number = typeof value === "number" ? value : typeof value === "string" && /^\s*\d{1,9}\s*$/u.test(value) ? Number(value) : NaN;
+  return Number.isInteger(number) && number >= min && number <= max ? number : null;
+}
+
+/**
+ * The year a date field states: its leading four digits (`2026`, `2026-03-01`,
+ * `2026-03-01T00:00:00Z`).
+ *
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+export function yearOf(value) {
+  const match = typeof value === "string" ? /^\s*(\d{4})(?:\D|$)/u.exec(value) : null;
+  return match ? wholeNumber(Number(match[1]), 1888, 2100) : null;
+}
+
+/**
+ * Ids in the forms the Matroska tagging specification states: `IMDB` is `tt`
+ * followed by digits, `TMDB` is `movie/<id>` or `tv/<id>`, `TVDB` is a number.
+ *
+ * @param {{ imdb?: unknown, tmdb?: unknown, tvdb?: unknown }} raw
+ * @returns {WorkTags["externalIds"]}
+ */
+export function externalIdsOf({ imdb, tmdb, tvdb }) {
+  const ids = {};
+  const imdbMatch = typeof imdb === "string" ? /^\s*(tt\d{7,12})\s*$/u.exec(imdb) : null;
+  if (imdbMatch) ids.imdb = imdbMatch[1];
+  const tmdbMatch = typeof tmdb === "string" ? /^\s*(movie|tv)\/(\d{1,10})\s*$/u.exec(tmdb) : null;
+  if (tmdbMatch) ids.tmdb = { kind: /** @type {"movie" | "tv"} */ (tmdbMatch[1]), id: Number(tmdbMatch[2]) };
+  const tvdbNumber = wholeNumber(tvdb, 1, 2_147_483_647);
+  if (tvdbNumber !== null) ids.tvdb = tvdbNumber;
+  return ids;
+}
+
+/**
+ * A chapter title that only numbers the chapter (`Chapter 01`, `Глава 3`,
+ * `01`, `00:12:00.000`) says nothing about the work.
+ *
+ * @param {string} title
+ * @returns {boolean}
+ */
+export function isNumberingOnly(title) {
+  return /^\s*(?:chapter|chap|глава|часть|kapitel|chapitre|capitulo|capítulo)?\s*[#№]?\s*[\d:.]+\s*$/iu.test(title);
+}
+
+/**
+ * Distinct non-empty texts, bounded.
+ *
+ * @param {Iterable<unknown>} values
+ * @returns {string[]}
+ */
+export function textList(values) {
+  const out = [];
+  for (const value of values) {
+    const one = text(value);
+    if (one && !out.includes(one)) out.push(one);
+    if (out.length >= MAX_LIST) break;
+  }
+  return out;
+}
+
+/**
+ * The image type a cover's bytes have, from their signature — a container's own
+ * statement of the type is checked against the bytes rather than trusted alone.
+ *
+ * @param {Buffer} head - At least the first twelve bytes.
+ * @returns {string | null}
+ */
+export function imageTypeOf(head) {
+  if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) return "image/jpeg";
+  if (head.length >= 8 && head.readUInt32BE(0) === 0x89504e47 && head.readUInt32BE(4) === 0x0d0a1a0a) return "image/png";
+  if (head.length >= 12 && head.toString("latin1", 0, 4) === "RIFF" && head.toString("latin1", 8, 12) === "WEBP") return "image/webp";
+  if (head.length >= 6 && /^GIF8[79]a$/u.test(head.toString("latin1", 0, 6))) return "image/gif";
+  if (head.length >= 2 && head.toString("latin1", 0, 2) === "BM") return "image/bmp";
+  return null;
+}
+
+/**
+ * Thrown by a reading of work tags where the bytes lie outside what it may
+ * fetch and have not arrived. The reading leaves that element out; it is not a
+ * fault of the file and not "not here yet".
+ */
+export class OutsideReadableEdges extends Error {
+  /**
+   * @param {number} start
+   * @param {number} end - Inclusive.
+   */
+  constructor(start, end) {
+    super(`bytes ${start}-${end} lie outside the edges this reading may fetch and are not held`);
+    this.name = "OutsideReadableEdges";
+    this.start = start;
+    this.end = end;
+  }
+}
+
+/**
+ * A reader that fetches only inside the edges, and reads elsewhere only what is
+ * already held.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer>} read - Strict: every byte or `BytesUnavailable`.
+ * @param {(start: number, end: number) => boolean} mayFetch
+ * @param {(error: unknown) => boolean} isUnavailable
+ * @returns {(start: number, end: number) => Promise<Buffer>}
+ */
+export function edgeReader(read, mayFetch, isUnavailable) {
+  return async (start, end) => {
+    try {
+      return await read(start, end);
+    } catch (error) {
+      if (isUnavailable(error) && !mayFetch(start, end)) throw new OutsideReadableEdges(start, end);
+      throw error;
+    }
+  };
+}

package/services/torrent/worker/worker.js

@@ -353,7 +353,10 @@ async function runCommand(command, params, id) {
           index,
           name: file.name,
           path: file.path,
-          length: file.length
+          length: file.length,
+          // Where the file begins in the torrent's bytes: which pieces hold its
+          // edges follows from it.
+          offset: file.offset
         }))
       };
     }
@@ -1046,7 +1049,7 @@ async function keepWholeFiles() {
         infoHash: torrent.infoHash,
         name: torrent.name,
         pieceLength: Number(torrent.pieceLength) || 0,
-        files: torrent.files.map((file, index) => ({ index, name: file.name, path: file.path, length: file.length }))
+        files: torrent.files.map((file, index) => ({ index, name: file.name, path: file.path, length: file.length, offset: file.offset }))
       });
       pool.remove(torrent, "downloaded-whole");
       pool.addWholeSource(sourceKey);