@aphrody/frames 0.2.0

package/README.md

@@ -0,0 +1,161 @@
+# @aphrody/frames
+
+Retrouver **d'où vient une image** : quel épisode, quelle seconde. Index local
+image par image, avec trace.moe en recours.
+
+```bash
+bxc frames index ~/videos/inazuma-s1e01.mp4 --season 1 --episode 1
+bxc frames search capture.jpg
+#  96.1%  Inazuma Eleven S1E1  2:41.000 → 2:44.000
+```
+
+## Pourquoi un index local
+
+Trois façons de répondre à la question existaient déjà. Mesurées sur Inazuma
+Eleven le 3 septembre 2026 :
+
+| | couverture Inazuma Eleven | quota | ce qui sort de la machine |
+| --- | --- | --- | --- |
+| [trace.moe](https://trace.moe) | partielle : 125 fichiers pour la série d'origine (AniList 5231), 47 pour GO, 51 Chrono Stone, 43 Galaxy, 25 Ares, 48 Orion — rien en VF | 100 recherches / 24 h, **1 requête à la fois** | l'image entière (ou 33 entiers, voir plus bas) |
+| [fancaps.net](https://fancaps.net/anime/) | **aucune** — la lettre « I » du catalogue liste 95 séries, pas une seule Inazuma | pas d'API publique, seulement des scrapers tiers | l'URL consultée |
+| index local (ce paquet) | ce qu'on lui donne — les 412 épisodes VF du catalogue IETV, par exemple | aucun | **rien** |
+
+L'index public est excellent là où il est complet, et muet ailleurs : les VF,
+les diffusions récentes, les films, les extraits — tout ce qu'il n'a jamais
+indexé. Un index local coûte 32 Mo pour un catalogue entier et répond en une
+demi-seconde ; il n'y a pas de raison de s'en priver.
+
+### Ce que valent les deux, mesuré
+
+- **Une vraie trame d'épisode → trace.moe la reconnaît parfaitement** :
+  similarité **0,9919** en envoyant l'image, **0,9920** en n'envoyant que le
+  descripteur, horodatage juste à 0,3 s près, 125 ms de latence.
+- **Une vignette YouTube brandée ne marche pas** : sur 10 requêtes construites
+  à partir des vignettes officielles de la chaîne IETV (bandeau de saison,
+  drapeau, logo, numéro d'épisode), 4 seulement retrouvaient la bonne série et
+  **une seule** dépassait le seuil de 0,90. Recadrer pour retirer les
+  incrustations n'arrange rien : le descripteur est une grille 8×8 sur l'image
+  entière, donc rogner déplace tout. Il faut une capture plein cadre.
+- **L'index local**, sur les mêmes images : 0,966 pour la trame correspondante,
+  et il trouve ce que l'index public n'a pas.
+
+### Débits mesurés (VPS 2 cœurs, ffmpeg 8.0.1)
+
+| | valeur |
+| --- | --- |
+| indexation d'un épisode de 24 min à 1 img/s | 10,7 s (**135× le temps réel**) |
+| idem à 4 img/s | 9,4 s (154×, le décodage domine, pas l'extraction) |
+| poids de l'index | 65 à 82 o par trame — **92 Ko** l'épisode à 1 img/s |
+| catalogue complet simulé (412 épisodes, 593 280 trames) | **32,5 Mo** |
+| recherche exhaustive dans ces 593 280 trames | **~500 ms** |
+
+## Prérequis
+
+`ffmpeg` et `ffprobe` dans le `PATH` (ou `FfmpegDeps.ffmpeg` / `.ffprobe`).
+C'est la seule dépendance externe : le descripteur, la base et la recherche
+sont en TypeScript pur.
+
+## CLI
+
+```bash
+bxc frames index <video...>     # indexe (ffmpeg décode en flux, rien sur disque)
+bxc frames search <image>       # local d'abord, trace.moe si le local ne sait pas
+bxc frames vector <image>       # les 33 coefficients, en base64 — partageable sans l'image
+bxc frames list                 # médias indexés
+bxc frames stats                # taille et couverture de l'index
+bxc frames quota                # quota trace.moe de cette machine
+```
+
+Options utiles : `--fps` (trames indexées par seconde, défaut 1), `--db`
+(emplacement de l'index, défaut `~/.cache/bxc/frames.db`, ou `BXC_FRAMES_DB`),
+`--local` / `--remote`, `--at 12:34` pour prendre la trame d'une vidéo comme
+requête, `--json`.
+
+```bash
+# indexer une saison entière
+for f in ~/videos/inazuma-s1e*.mp4; do bxc frames index "$f" --season 1 --fps 2; done
+
+# d'où vient cette capture ?
+bxc frames search capture.png --limit 3
+
+# à quelle seconde de l'épisode 12 se trouve ce plan ?
+bxc frames search plan.jpg --local --limit 1
+```
+
+## API
+
+```ts
+import { FrameSearch } from "@aphrody/frames";
+
+const frames = new FrameSearch({ indexPath: "~/.cache/bxc/frames.db" });
+
+await frames.indexVideo("ep01.mkv", { fps: 2, title: "Inazuma Eleven", season: 1, episode: 1 });
+
+const found = await frames.search("capture.jpg");
+// { origin: "local" | "remote", matches: [{ title, episode, fromMs, atMs, toMs, similarity }] }
+```
+
+Briques séparées si la façade ne convient pas :
+`@aphrody/frames/descriptor` (extraction, distance), `/extract` (ffmpeg),
+`/store` (index SQLite), `/search` (recherche + regroupement en scènes),
+`/trace-moe` (client de l'API publique).
+
+## Similarité
+
+Le score suit l'échelle de trace.moe : **au-dessous de 0,90, le résultat est
+probablement faux**, quelle que soit sa place au classement. Il est dérivé de
+la distance MPEG-7 par `1 − d / 100`, où 100 vient de mesures sur des trames
+d'anime décodées par ce module :
+
+| distance | ce que c'est |
+| --- | --- |
+| 0 – 10 | la même image (ré-encodée, redimensionnée) |
+| 10 – 30 | le même plan, à une seconde près |
+| > 34 | deux images sans rapport |
+
+La taille de vignette n'influe pas : sur une trame d'épisode, le descripteur
+est **identique** entre 64 et 512 pixels de côté (il ne garde que la moyenne de
+64 blocs). D'où le décodage en 128×128 par défaut — cent fois moins de pixels
+que la pleine résolution, pour le même vecteur.
+
+## Confidentialité
+
+C'est la raison d'être du chemin local. Chercher une image, c'est révéler ce
+qu'on regarde ; un service tiers qui reçoit la capture apprend l'image *et*
+l'intention.
+
+- **Index local** : rien ne quitte la machine.
+- **Recours distant** : `searchByVector` n'envoie que les **33 entiers** du
+  descripteur (28 caractères en base64), jamais l'image — et c'est aussi le
+  chemin le plus rapide, le serveur n'ayant rien à télécharger ni décoder. Même
+  précision mesurée : 0,9920 contre 0,9919 en téléversant le fichier.
+- La clé d'API éventuelle part en en-tête `x-trace-key`, jamais dans l'URL.
+- `bxc frames vector capture.jpg` donne de quoi faire chercher quelqu'un
+  d'autre à votre place, sans lui montrer l'image.
+
+## Limites connues
+
+- **Le descripteur est global** : une incrustation, un bandeau, un recadrage ou
+  une bordure changent le vecteur. Une capture plein cadre marche, une vignette
+  brandée non (mesuré plus haut). `cutBorders` côté trace.moe ne retire que les
+  bandes noires.
+- **Deux plans quasi identiques** (un ciel, un fondu au noir, un écran blanc)
+  se ressemblent forcément : le score sera élevé et le résultat arbitraire.
+- **La recherche est exhaustive** : linéaire en nombre de trames. Une demi-
+  seconde pour 600 000 trames ; au-delà de quelques millions, il faudra un
+  index approché.
+- **L'échantillonnage borne la précision** : à 1 img/s, l'horodatage est juste
+  à la seconde. Monter à 4 img/s coûte 4× l'espace, pas le temps d'indexation.
+- **trace.moe** : 100 recherches par 24 h sans clé, une seule à la fois (une
+  deuxième requête simultanée est refusée avec le même code HTTP qu'un quota
+  épuisé — le client distingue les deux avec le quota connu).
+
+## Tests
+
+```bash
+bun test packages/frames    # 61 cas, sans ffmpeg, sans réseau
+```
+
+Le processus ffmpeg et le `fetch` sont injectables : les tests vérifient les
+arguments de commande, rejouent un flux `rawvideo` factice (y compris coupé au
+milieu d'une trame) et pilotent l'horloge pour les reprises et les budgets.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aphrody/frames",
+  "version": "0.2.0",
+  "description": "Index et recherche image par image d'épisodes d'anime — descripteur MPEG-7 ColorLayout local, compatible trace.moe",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./descriptor": "./src/descriptor.ts",
+    "./extract": "./src/extract.ts",
+    "./store": "./src/store.ts",
+    "./search": "./src/search.ts",
+    "./trace-moe": "./src/trace-moe.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "keywords": [
+    "anime",
+    "frame",
+    "color-layout",
+    "mpeg-7",
+    "reverse-image-search",
+    "trace.moe"
+  ],
+  "dependencies": {
+    "trace.moe-id": "^2.0.0"
+  },
+  "files": [
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "license": "Apache-2.0"
+}

package/src/descriptor.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Descripteur d'image : MPEG-7 ColorLayout, 33 coefficients.
+ *
+ * C'est le même descripteur que celui utilisé par trace.moe, et volontairement :
+ * un vecteur extrait ici s'interroge indifféremment sur l'index **local**
+ * (`store.ts` + `search.ts`) ou sur l'API distante (`trace-moe.ts`, paramètre
+ * `?vector=`). L'extraction et l'encodage viennent de `trace.moe-id` (MIT,
+ * sans dépendance) pour que les vecteurs restent bit-à-bit compatibles ; ce
+ * module n'ajoute que ce qui manque côté index :
+ *
+ *  - {@link packVector} / {@link unpackVector} — 33 octets, la forme stockée en
+ *    base (un coefficient tient sur 6 bits au plus, donc sur un octet).
+ *  - {@link colorLayoutDistance} — la métrique MPEG-7 sur `Uint8Array`, sans
+ *    allocation, pour balayer des centaines de milliers de trames.
+ *  - {@link similarityFromDistance} — la conversion en score 0..1 comparable à
+ *    celui que renvoie trace.moe (échelle calibrée, cf. {@link DISTANCE_SCALE}).
+ */
+
+import { ColorLayout, type PixelData } from "trace.moe-id";
+
+/** Nombre de coefficients d'un vecteur ColorLayout. */
+export const CL_DIMS = 33;
+
+/** Coefficients de luminance (1 DC + 20 AC), en tête du vecteur. */
+export const CL_Y_COUNT = 21;
+
+/** Coefficients par plan de chrominance (1 DC + 5 AC), Cb puis Cr. */
+export const CL_C_COUNT = 6;
+
+/**
+ * Poids MPEG-7 de la distance : les trois premiers coefficients de chaque plan
+ * pèsent plus que les suivants (ils portent la structure globale de l'image).
+ */
+const W_Y = [2, 2, 2] as const;
+const W_CB = [2, 1, 1] as const;
+const W_CR = [4, 2, 2] as const;
+
+/**
+ * Distance au-delà de laquelle deux images n'ont plus rien à voir.
+ *
+ * Mesurée, pas devinée (cf. `README.md`, section « Similarité ») : sur des
+ * trames d'anime décodées par ce module, la même image ré-encodée reste sous
+ * 10, deux trames de la même scène tiennent sous 30, et deux images sans
+ * rapport se placent entre 34 et 79. L'échelle 100 fait donc tomber le seuil
+ * « probablement faux » au même endroit que celui de trace.moe (0,90).
+ *
+ * Ne sert qu'à afficher un score lisible : le classement des résultats, lui,
+ * ne dépend que de la distance.
+ */
+export const DISTANCE_SCALE = 100;
+
+/** Un vecteur ColorLayout, tel que produit par {@link extractColorLayout}. */
+export type ColorLayoutVector = number[];
+
+/** Image décodée en pixels bruts, telle qu'attendue par l'extracteur. */
+export type { PixelData };
+
+/** Extrait le vecteur 33 coefficients d'une image décodée. */
+export function extractColorLayout(image: PixelData): ColorLayoutVector {
+	return ColorLayout.extract(image);
+}
+
+/** Encode un vecteur en chaîne base64 URL-safe (28 caractères), forme acceptée par api.trace.moe. */
+export function encodeVector(vector: ColorLayoutVector): string {
+	return ColorLayout.encode(vector);
+}
+
+/** Décode une chaîne base64 URL-safe en vecteur. */
+export function decodeVector(hash: string): ColorLayoutVector {
+	return ColorLayout.decode(hash);
+}
+
+/**
+ * Forme stockée : 33 octets. Chaque coefficient est déjà quantifié sur 5 ou
+ * 6 bits par l'extracteur, un octet suffit donc et la distance se calcule
+ * directement sur le buffer lu en base, sans reconstruire de tableau.
+ */
+export function packVector(vector: ColorLayoutVector): Uint8Array {
+	if (vector.length !== CL_DIMS) {
+		throw new Error(`vecteur ColorLayout attendu de ${CL_DIMS} coefficients, reçu ${vector.length}`);
+	}
+	const out = new Uint8Array(CL_DIMS);
+	for (let i = 0; i < CL_DIMS; i++) {
+		const v = vector[i] ?? 0;
+		out[i] = v < 0 ? 0 : v > 255 ? 255 : v;
+	}
+	return out;
+}
+
+/** Inverse de {@link packVector}. */
+export function unpackVector(bytes: Uint8Array): ColorLayoutVector {
+	if (bytes.length !== CL_DIMS) {
+		throw new Error(`buffer de ${CL_DIMS} octets attendu, reçu ${bytes.length}`);
+	}
+	return Array.from(bytes);
+}
+
+/**
+ * Distance MPEG-7 entre deux vecteurs : somme des racines des écarts pondérés
+ * de chaque plan (Y, Cb, Cr). Accepte indifféremment les deux représentations
+ * pour qu'un vecteur fraîchement extrait se compare à une ligne de la base
+ * sans conversion intermédiaire.
+ */
+export function colorLayoutDistance(
+	a: ArrayLike<number>,
+	b: ArrayLike<number>,
+): number {
+	let sumY = 0;
+	for (let i = 0; i < CL_Y_COUNT; i++) {
+		const d = a[i] - b[i];
+		sumY += (W_Y[i] ?? 1) * d * d;
+	}
+	let sumCb = 0;
+	let sumCr = 0;
+	for (let i = 0; i < CL_C_COUNT; i++) {
+		const cb = a[CL_Y_COUNT + i] - b[CL_Y_COUNT + i];
+		sumCb += (W_CB[i] ?? 1) * cb * cb;
+		const j = CL_Y_COUNT + CL_C_COUNT + i;
+		const cr = a[j] - b[j];
+		sumCr += (W_CR[i] ?? 1) * cr * cr;
+	}
+	return Math.sqrt(sumY) + Math.sqrt(sumCb) + Math.sqrt(sumCr);
+}
+
+/**
+ * Score 0..1 dérivé de la distance, sur la même échelle que la similarité
+ * renvoyée par trace.moe : au-dessous de 0,90 le résultat est probablement
+ * faux, quelle que soit sa place au classement.
+ */
+export function similarityFromDistance(distance: number): number {
+	const s = 1 - distance / DISTANCE_SCALE;
+	return s < 0 ? 0 : s > 1 ? 1 : s;
+}

package/src/ffmpeg.ts

@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Décodage : la seule dépendance externe du paquet est `ffmpeg`.
+ *
+ * Une vidéo n'est jamais chargée en mémoire ni recopiée sur disque : ffmpeg
+ * décode en flux, redimensionne chaque trame à une vignette carrée et l'écrit
+ * en `rawvideo` sur sa sortie standard, que {@link iterateFrames} découpe au
+ * fur et à mesure. Indexer un épisode coûte donc la taille d'**une** vignette
+ * en mémoire, quelle que soit la durée.
+ *
+ * La vignette est carrée à dessein : le descripteur ColorLayout découpe l'image
+ * en 8×8 blocs et n'en garde que la moyenne, donc écraser le rapport d'aspect
+ * vers un multiple de 8 revient exactement à moyenner les blocs de l'image
+ * d'origine — et coûte cent fois moins cher que de décoder en pleine
+ * résolution.
+ *
+ * Tout ce qui touche au processus passe par {@link FfmpegDeps.spawn} : les
+ * tests construisent et vérifient les arguments, et rejouent un flux factice,
+ * sans que ffmpeg soit installé.
+ */
+
+import type { PixelData } from "./descriptor.ts";
+
+/** Le strict minimum d'un processus, pour que les tests puissent en simuler un. */
+export interface SpawnedProcess {
+	stdout: ReadableStream<Uint8Array> | null;
+	stderr?: ReadableStream<Uint8Array> | null;
+	exited: Promise<number>;
+	kill?(): void;
+}
+
+/** Lance une commande et rend ses flux. */
+export type Spawner = (cmd: readonly string[]) => SpawnedProcess;
+
+/** Points d'injection : binaires et lanceur de processus. */
+export interface FfmpegDeps {
+	/** Chemin du binaire ffmpeg (défaut : `ffmpeg` dans le `PATH`). */
+	ffmpeg?: string;
+	/** Chemin du binaire ffprobe (défaut : `ffprobe` dans le `PATH`). */
+	ffprobe?: string;
+	/** Lanceur de processus (défaut : `Bun.spawn`). */
+	spawn?: Spawner;
+}
+
+/** Options d'échantillonnage d'une vidéo. */
+export interface FrameStreamOptions {
+	/** Trames extraites par seconde de vidéo (défaut : 1). */
+	fps?: number;
+	/** Côté de la vignette carrée décodée, en pixels (défaut : 128). */
+	size?: number;
+	/** Début de la plage à décoder, en millisecondes. */
+	startMs?: number;
+	/** Fin de la plage à décoder, en millisecondes. */
+	endMs?: number;
+}
+
+/** Une trame décodée et son horodatage dans la vidéo. */
+export interface DecodedFrame {
+	/** Rang de la trame dans le flux échantillonné, à partir de 0. */
+	index: number;
+	/** Position dans la vidéo, en millisecondes. */
+	tMs: number;
+	/** Pixels RGB de la vignette. */
+	pixels: PixelData;
+}
+
+/** Ce que `ffprobe` sait dire d'un média avant de le décoder. */
+export interface MediaInfo {
+	durationMs: number;
+	width: number;
+	height: number;
+	/** Cadence d'origine, en images par seconde (0 si inconnue). */
+	fps: number;
+	codec: string;
+}
+
+const DEFAULT_SIZE = 128;
+const DEFAULT_FPS = 1;
+
+function defaultSpawn(cmd: readonly string[]): SpawnedProcess {
+	return Bun.spawn([...cmd], { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+}
+
+/** Millisecondes → `HH:MM:SS.mmm`, la forme que ffmpeg accepte sans ambiguïté. */
+export function timecode(ms: number): string {
+	const clamped = Math.max(0, Math.round(ms));
+	const h = Math.floor(clamped / 3_600_000);
+	const m = Math.floor((clamped % 3_600_000) / 60_000);
+	const s = Math.floor((clamped % 60_000) / 1000);
+	const milli = clamped % 1000;
+	return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}.${String(milli).padStart(3, "0")}`;
+}
+
+/** Arguments de la commande d'échantillonnage — isolés pour être testables. */
+export function buildFrameArgs(
+	source: string,
+	opts: FrameStreamOptions = {},
+	deps: FfmpegDeps = {},
+): string[] {
+	const fps = opts.fps ?? DEFAULT_FPS;
+	const size = opts.size ?? DEFAULT_SIZE;
+	const args = [deps.ffmpeg ?? "ffmpeg", "-v", "error", "-nostdin"];
+	// `-ss` avant `-i` : ffmpeg saute directement à la position demandée au
+	// lieu de décoder tout ce qui précède.
+	if (opts.startMs) args.push("-ss", timecode(opts.startMs));
+	args.push("-i", source);
+	if (opts.endMs !== undefined) {
+		args.push("-t", timecode(opts.endMs - (opts.startMs ?? 0)));
+	}
+	args.push(
+		"-an",
+		"-sn",
+		"-vf",
+		`fps=${fps},scale=${size}:${size}:flags=area`,
+		"-pix_fmt",
+		"rgb24",
+		"-f",
+		"rawvideo",
+		"-",
+	);
+	return args;
+}
+
+/** Arguments de la commande d'inspection — isolés pour être testables. */
+export function buildProbeArgs(source: string, deps: FfmpegDeps = {}): string[] {
+	return [
+		deps.ffprobe ?? "ffprobe",
+		"-v",
+		"error",
+		"-select_streams",
+		"v:0",
+		"-show_entries",
+		"stream=width,height,r_frame_rate,codec_name:format=duration",
+		"-of",
+		"json",
+		source,
+	];
+}
+
+/** Lit la sortie JSON de ffprobe. Tolère les champs absents : un flux peut tout ignorer sauf sa taille. */
+export function parseProbe(json: string): MediaInfo {
+	const parsed = JSON.parse(json) as {
+		streams?: Array<{
+			width?: number;
+			height?: number;
+			r_frame_rate?: string;
+			codec_name?: string;
+		}>;
+		format?: { duration?: string };
+	};
+	const stream = parsed.streams?.[0] ?? {};
+	const [num, den] = (stream.r_frame_rate ?? "0/1").split("/");
+	const denominator = Number(den) || 1;
+	const duration = Number(parsed.format?.duration ?? 0);
+	return {
+		durationMs: Number.isFinite(duration) ? Math.round(duration * 1000) : 0,
+		width: stream.width ?? 0,
+		height: stream.height ?? 0,
+		fps: Number(num) / denominator || 0,
+		codec: stream.codec_name ?? "",
+	};
+}
+
+async function drain(stream: ReadableStream<Uint8Array> | null | undefined): Promise<string> {
+	if (!stream) return "";
+	return await new Response(stream).text();
+}
+
+/** Inspecte un média (durée, dimensions, cadence) sans le décoder. */
+export async function probeMedia(source: string, deps: FfmpegDeps = {}): Promise<MediaInfo> {
+	const spawn = deps.spawn ?? defaultSpawn;
+	const proc = spawn(buildProbeArgs(source, deps));
+	const [out, err, code] = await Promise.all([
+		drain(proc.stdout),
+		drain(proc.stderr),
+		proc.exited,
+	]);
+	if (code !== 0) {
+		throw new Error(`ffprobe a échoué (${code}) sur ${source}: ${err.trim() || "sans message"}`);
+	}
+	return parseProbe(out);
+}
+
+/**
+ * Échantillonne une vidéo et rend ses trames une par une.
+ *
+ * Le flux `rawvideo` n'a ni en-tête ni séparateur : chaque trame occupe
+ * exactement `size × size × 3` octets, et son horodatage se déduit de son rang
+ * puisque le filtre `fps` produit une cadence constante.
+ */
+export async function* iterateFrames(
+	source: string,
+	opts: FrameStreamOptions = {},
+	deps: FfmpegDeps = {},
+): AsyncGenerator<DecodedFrame> {
+	const fps = opts.fps ?? DEFAULT_FPS;
+	const size = opts.size ?? DEFAULT_SIZE;
+	const startMs = opts.startMs ?? 0;
+	const frameBytes = size * size * 3;
+	const spawn = deps.spawn ?? defaultSpawn;
+	const proc = spawn(buildFrameArgs(source, opts, deps));
+	if (!proc.stdout) throw new Error("ffmpeg n'a pas ouvert de sortie standard");
+
+	const errPromise = drain(proc.stderr);
+	const reader = proc.stdout.getReader();
+	let pending = new Uint8Array(0);
+	let index = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (value && value.length) {
+				const merged = new Uint8Array(pending.length + value.length);
+				merged.set(pending);
+				merged.set(value, pending.length);
+				pending = merged;
+				let offset = 0;
+				while (pending.length - offset >= frameBytes) {
+					const data = pending.subarray(offset, offset + frameBytes);
+					offset += frameBytes;
+					yield {
+						index,
+						tMs: startMs + Math.round((index * 1000) / fps),
+						pixels: { data, width: size, height: size, channels: 3 },
+					};
+					index++;
+				}
+				pending = offset ? pending.slice(offset) : pending;
+			}
+			if (done) break;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+
+	const code = await proc.exited;
+	if (code !== 0) {
+		const err = await errPromise;
+		throw new Error(`ffmpeg a échoué (${code}) sur ${source}: ${err.trim() || "sans message"}`);
+	}
+}
+
+/** Arguments du décodage d'une image unique — isolés pour être testables. */
+export function buildStillArgs(
+	source: string,
+	opts: { atMs?: number; size?: number } = {},
+	deps: FfmpegDeps = {},
+): string[] {
+	const size = opts.size ?? DEFAULT_SIZE;
+	const args = [deps.ffmpeg ?? "ffmpeg", "-v", "error", "-nostdin"];
+	if (opts.atMs) args.push("-ss", timecode(opts.atMs));
+	args.push(
+		"-i",
+		source,
+		"-an",
+		"-sn",
+		"-vf",
+		`scale=${size}:${size}:flags=area`,
+		"-frames:v",
+		"1",
+		"-pix_fmt",
+		"rgb24",
+		"-f",
+		"rawvideo",
+		"-",
+	);
+	return args;
+}
+
+/**
+ * Décode une seule image : un fichier JPEG/PNG, ou la trame d'une vidéo à la
+ * position `atMs`. C'est le chemin d'une requête de recherche.
+ *
+ * Une image fixe n'a pas de durée : le filtre `fps` d'{@link iterateFrames} ne
+ * produirait rien sur un JPEG. D'où une commande distincte, bornée par
+ * `-frames:v 1`.
+ */
+export async function decodeStill(
+	source: string,
+	opts: { atMs?: number; size?: number } = {},
+	deps: FfmpegDeps = {},
+): Promise<PixelData> {
+	const size = opts.size ?? DEFAULT_SIZE;
+	const frameBytes = size * size * 3;
+	const spawn = deps.spawn ?? defaultSpawn;
+	const proc = spawn(buildStillArgs(source, opts, deps));
+	if (!proc.stdout) throw new Error("ffmpeg n'a pas ouvert de sortie standard");
+	const errPromise = drain(proc.stderr);
+	const raw = new Uint8Array(await new Response(proc.stdout).arrayBuffer());
+	const code = await proc.exited;
+	if (code !== 0) {
+		const err = await errPromise;
+		throw new Error(`ffmpeg a échoué (${code}) sur ${source}: ${err.trim() || "sans message"}`);
+	}
+	if (raw.length < frameBytes) {
+		throw new Error(`aucune image décodable dans ${source}`);
+	}
+	return { data: raw.subarray(0, frameBytes), width: size, height: size, channels: 3 };
+}