@camstack/types 1.2.41 → 1.2.43

package/dist/node.js

@@ -21,7 +21,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
+const require_canonical_hash = require("./canonical-hash-BcZHRHIx.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
+let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs);
 let node_path = require("node:path");
@@ -29,7 +31,6 @@ node_path = __toESM(node_path);
 let node_stream_promises = require("node:stream/promises");
 let node_stream = require("node:stream");
 let node_child_process = require("node:child_process");
-let node_crypto = require("node:crypto");
 //#region src/deps/binary-downloader.ts
 /**
 * Recursively find the first file named exactly `name` under `dir`. Used as the
@@ -600,39 +601,6 @@ var FilesystemStorageProvider = class {
 	}
 };
 //#endregion
-//#region src/utils/canonical-hash.ts
-/**
-* Deterministic SHA-256 hash of an arbitrary serialisable value. The
-* canonical form sorts object keys alphabetically at every depth so two
-* structurally-equal inputs with different key insertion orders produce
-* the same hash. Returns a 64-char lowercase hex digest.
-*
-* Used by export adapters (Alexa, HAP) to short-circuit re-discovery /
-* accessory-rebuild work when the upstream shape is byte-identical to
-* the last applied state — preventing user-visible "re-discovery"
-* notifications on every addon-runner respawn. Each respawn re-fires
-* `DeviceBindingsChanged` for every cap registration, which without
-* this guard would propagate redundant pushes.
-*
-* Note: this is a SYMPTOMATIC fix layered on top of the binding-change
-* subscription. The proper fix is a single "device ready" lifecycle
-* barrier so exports react only when the full cap set has landed —
-* tracked separately for post-HA-integration work.
-*/
-function canonicalHash(value) {
-	const canonical = JSON.stringify(value, replaceWithSortedKeys);
-	return (0, node_crypto.createHash)("sha256").update(canonical ?? "").digest("hex");
-}
-function replaceWithSortedKeys(_key, value) {
-	if (value && typeof value === "object" && !Array.isArray(value)) {
-		const obj = value;
-		const out = {};
-		for (const k of Object.keys(obj).toSorted()) out[k] = obj[k];
-		return out;
-	}
-	return value;
-}
-//#endregion
 //#region src/utils/export-reconciler.ts
 /**
 * Compute the stable 64-char lowercase-hex fingerprint of a device's
@@ -641,7 +609,7 @@ function replaceWithSortedKeys(_key, value) {
 */
 function canonicalDeviceFingerprint(shape) {
 	const features = [...new Set(shape.features)].toSorted();
-	return canonicalHash({
+	return require_canonical_hash.canonicalHash({
 		deviceType: shape.deviceType,
 		features
 	});
@@ -689,11 +657,277 @@ function resolveExportFingerprint(input) {
 	return input.persisted ?? input.fresh;
 }
 //#endregion
+//#region src/ffmpeg/process.ts
+/**
+* `FfmpegProcess` — the ONE spawn/lifecycle wrapper for a live-media ffmpeg.
+*
+* Extracted from `TranscodeEgress.spawnAttempt`, which was already the most
+* complete of the repo's hand-rolled lifecycles: first-data deadline, hardware
+* →software retry, SIGTERM-then-SIGKILL. This generalises it and adds the two
+* things every copy was missing — a `tags: { deviceId }` on every line, and a
+* bounded restart — so a consumer gets them by construction instead of by
+* remembering.
+*
+* ## What it owns
+*
+* - spawn, with the argv from the ONE builder (`./invocation.js`);
+* - a FIRST-DATA deadline: an ffmpeg that starts but never emits is dead, and
+*   nothing downstream can tell that apart from a slow camera;
+* - HARDWARE→SOFTWARE retry, announced at `warn`. A silent downgrade on this
+*   hub is a flow bug, not a capability limit — see `docs/design/decode-path.md`;
+* - exit classification (`ok` / `signalled-by-us` / `crashed` / `no-output`);
+* - bounded restart with backoff, and a terminal give-up (never an infinite
+*   loop — the same rule `CrashSupervisor` enforces for runners, D6);
+* - SIGTERM then SIGKILL after a grace, gated on the child not having already
+*   exited.
+*
+* ## What it does NOT own
+*
+* The output PLUMBING. A consumer attaches to `stdout` / `stderr` itself,
+* because what the bytes mean is the consumer's business: the broker deframes
+* Annex-B into a restreamer, the WebRTC leg regroups access units, HomeKit
+* writes nothing to stdout at all (its output is two RTP sockets). A wrapper
+* that also owned the bytes would need a mode per consumer, which is the same
+* mistake as one builder per consumer.
+*/
+var DEFAULT_FIRST_DATA_TIMEOUT_MS = 8e3;
+var DEFAULT_RESTART_DELAY_MS = 1e3;
+var DEFAULT_STABLE_RUN_MS = 3e4;
+var DEFAULT_KILL_GRACE_MS = 500;
+var STDERR_TAIL_LINES = 12;
+var FfmpegProcess = class {
+	opts;
+	child = null;
+	stopped = false;
+	producedOutput = false;
+	consecutiveFailures = 0;
+	startedAtMs = 0;
+	stderrTail = [];
+	activeHwAccel;
+	triedSoftwareFallback = false;
+	firstDataTimer = null;
+	constructor(opts) {
+		this.opts = opts;
+		this.activeHwAccel = opts.decodeHwAccel;
+	}
+	/** Queryable tags on every line — `deviceId` is never optional. */
+	get logTags() {
+		return {
+			deviceId: this.opts.deviceId,
+			...this.opts.tags
+		};
+	}
+	get now() {
+		return (this.opts.now ?? Date.now)();
+	}
+	/** `true` while a child is running. */
+	isRunning() {
+		return this.child !== null && !this.stopped;
+	}
+	/** The backend the CURRENT child decodes with (`null` ⇒ software). */
+	activeDecodeHwAccel() {
+		return this.activeHwAccel;
+	}
+	/**
+	* Spawn the first child. Resolves as soon as it produces output; rejects if
+	* it dies or stays silent past the deadline AFTER the software retry has
+	* also been exhausted. A caller that wants fire-and-forget can ignore the
+	* promise — the restart loop runs regardless.
+	*/
+	start() {
+		return new Promise((resolve, reject) => {
+			this.spawnAttempt(resolve, reject);
+		});
+	}
+	spawnAttempt(onLive, onDead) {
+		if (this.stopped) return;
+		const args = [...this.opts.buildArgs(this.activeHwAccel)];
+		const spawnFn = this.opts.spawnFn ?? node_child_process.spawn;
+		const setTimeoutImpl = this.opts.setTimeoutFn ?? setTimeout;
+		this.opts.logger.info(`ffmpeg ${this.opts.role}: spawning`, {
+			tags: this.logTags,
+			meta: {
+				decodeHwAccel: this.activeHwAccel ?? "software",
+				attempt: this.consecutiveFailures + 1
+			}
+		});
+		let child;
+		try {
+			child = spawnFn(this.opts.binaryPath, args, { stdio: this.opts.stdio ?? [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+		} catch (err) {
+			this.handleFailure("crashed", null, null, err, onLive, onDead);
+			return;
+		}
+		this.child = child;
+		this.startedAtMs = this.now;
+		this.producedOutput = false;
+		this.stderrTail = [];
+		let settled = false;
+		const timeoutMs = this.opts.firstDataTimeoutMs ?? DEFAULT_FIRST_DATA_TIMEOUT_MS;
+		if (timeoutMs > 0) this.firstDataTimer = setTimeoutImpl(() => {
+			if (settled || this.producedOutput || this.stopped) return;
+			settled = true;
+			this.opts.logger.warn(`ffmpeg ${this.opts.role}: no output within ${timeoutMs}ms`, {
+				tags: this.logTags,
+				meta: { decodeHwAccel: this.activeHwAccel ?? "software" }
+			});
+			this.killChild();
+			this.handleFailure("no-output", null, null, null, onLive, onDead);
+		}, timeoutMs);
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (line) => {
+			const text = String(line).trim();
+			if (text.length === 0) return;
+			this.stderrTail.push(text);
+			if (this.stderrTail.length > STDERR_TAIL_LINES) this.stderrTail.shift();
+			this.opts.logger.debug(`ffmpeg ${this.opts.role}`, {
+				tags: this.logTags,
+				meta: { line: text }
+			});
+		});
+		child.once("error", (err) => {
+			if (settled || this.stopped) return;
+			settled = true;
+			this.handleFailure("crashed", null, null, err, onLive, onDead);
+		});
+		child.once("exit", (code, signal) => {
+			this.clearFirstDataTimer();
+			if (this.child === child) this.child = null;
+			if (this.stopped) {
+				this.report("stopped", code, signal);
+				return;
+			}
+			if (settled && this.producedOutput) {
+				this.report("crashed", code, signal);
+				this.scheduleRestart(onLive, onDead);
+				return;
+			}
+			if (settled) return;
+			settled = true;
+			this.handleFailure(this.producedOutput ? "crashed" : "no-output", code, signal, null, onLive, onDead);
+		});
+		this.opts.onChild(child);
+		child.stdout?.once("data", () => {
+			this.producedOutput = true;
+			this.clearFirstDataTimer();
+			if (settled) return;
+			settled = true;
+			this.opts.logger.info(`ffmpeg ${this.opts.role}: live`, {
+				tags: this.logTags,
+				meta: { decodeHwAccel: this.activeHwAccel ?? "software" }
+			});
+			onLive();
+		});
+	}
+	/**
+	* A child failed before going live. Try SOFTWARE once if it was decoding in
+	* hardware — loudly — then fall through to the bounded restart.
+	*/
+	handleFailure(classification, code, signal, err, onLive, onDead) {
+		this.report(classification, code, signal, err);
+		if (this.activeHwAccel !== null && !this.triedSoftwareFallback && !this.stopped) {
+			this.triedSoftwareFallback = true;
+			this.opts.logger.warn(`ffmpeg ${this.opts.role}: hardware decode produced no output — retrying in SOFTWARE`, {
+				tags: this.logTags,
+				meta: {
+					decodeHwAccel: this.activeHwAccel,
+					classification,
+					code,
+					signal,
+					stderrTail: this.stderrTail
+				}
+			});
+			this.activeHwAccel = null;
+			this.spawnAttempt(onLive, onDead);
+			return;
+		}
+		this.consecutiveFailures += 1;
+		const maxRestarts = this.opts.maxRestarts ?? 0;
+		if (this.consecutiveFailures > maxRestarts || this.stopped) {
+			const reason = `ffmpeg ${this.opts.role} gave up after ${this.consecutiveFailures} attempt(s) (${classification}, code=${code} signal=${signal})`;
+			this.opts.logger.error(reason, {
+				tags: this.logTags,
+				meta: { stderrTail: this.stderrTail }
+			});
+			onDead(new Error(reason));
+			return;
+		}
+		this.scheduleRestart(onLive, onDead);
+	}
+	scheduleRestart(onLive, onDead) {
+		if (this.stopped) return;
+		const maxRestarts = this.opts.maxRestarts ?? 0;
+		if (maxRestarts === 0) return;
+		if (this.producedOutput && this.now - this.startedAtMs >= (this.opts.stableRunMs ?? DEFAULT_STABLE_RUN_MS)) this.consecutiveFailures = 0;
+		if (this.consecutiveFailures > maxRestarts) return;
+		(this.opts.setTimeoutFn ?? setTimeout)(() => {
+			if (this.stopped) return;
+			this.spawnAttempt(onLive, onDead);
+		}, (this.opts.restartDelayMs ?? DEFAULT_RESTART_DELAY_MS) * Math.min(this.consecutiveFailures + 1, 8));
+	}
+	report(classification, code, signal, err) {
+		const exit = {
+			classification,
+			code,
+			signal,
+			stderrTail: [...this.stderrTail],
+			decodeHwAccel: this.activeHwAccel
+		};
+		if (classification === "crashed" || classification === "no-output") this.opts.logger.warn(`ffmpeg ${this.opts.role} exited: ${classification}`, {
+			tags: this.logTags,
+			meta: {
+				code,
+				signal,
+				decodeHwAccel: this.activeHwAccel ?? "software",
+				error: err instanceof Error ? err.message : err === void 0 ? void 0 : String(err),
+				stderrTail: exit.stderrTail
+			}
+		});
+		this.opts.onExit?.(exit);
+	}
+	clearFirstDataTimer() {
+		if (this.firstDataTimer !== null) {
+			clearTimeout(this.firstDataTimer);
+			this.firstDataTimer = null;
+		}
+	}
+	/** Terminate for good. Idempotent; no restart follows. */
+	stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.clearFirstDataTimer();
+		this.killChild();
+	}
+	killChild() {
+		const child = this.child;
+		this.child = null;
+		if (!child) return;
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		try {
+			child.kill("SIGTERM");
+		} catch {
+			return;
+		}
+		const grace = (this.opts.setTimeoutFn ?? setTimeout)(() => {
+			if (child.exitCode !== null || child.signalCode !== null) return;
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+		}, this.opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS);
+		if (typeof grace === "object" && grace !== null && "unref" in grace) grace.unref();
+	}
+};
+//#endregion
+exports.FfmpegProcess = FfmpegProcess;
 exports.FilesystemStorageProvider = FilesystemStorageProvider;
 exports.PYTHON_VERSION = PYTHON_VERSION;
 exports.buildBinaryPath = buildBinaryPath;
 exports.canonicalDeviceFingerprint = canonicalDeviceFingerprint;
-exports.canonicalHash = canonicalHash;
+exports.canonicalHash = require_canonical_hash.canonicalHash;
 exports.diffExportTargets = diffExportTargets;
 exports.downloadBinary = downloadBinary;
 exports.ensureBinary = ensureBinary;

package/dist/node.mjs

@@ -1,12 +1,13 @@
+import { t as canonicalHash } from "./canonical-hash-7nfBbEqR.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
+import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { basename, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { execFileSync, spawn } from "node:child_process";
 //#region src/deps/binary-downloader.ts
 /**
 * Recursively find the first file named exactly `name` under `dir`. Used as the
@@ -577,39 +578,6 @@ var FilesystemStorageProvider = class {
 	}
 };
 //#endregion
-//#region src/utils/canonical-hash.ts
-/**
-* Deterministic SHA-256 hash of an arbitrary serialisable value. The
-* canonical form sorts object keys alphabetically at every depth so two
-* structurally-equal inputs with different key insertion orders produce
-* the same hash. Returns a 64-char lowercase hex digest.
-*
-* Used by export adapters (Alexa, HAP) to short-circuit re-discovery /
-* accessory-rebuild work when the upstream shape is byte-identical to
-* the last applied state — preventing user-visible "re-discovery"
-* notifications on every addon-runner respawn. Each respawn re-fires
-* `DeviceBindingsChanged` for every cap registration, which without
-* this guard would propagate redundant pushes.
-*
-* Note: this is a SYMPTOMATIC fix layered on top of the binding-change
-* subscription. The proper fix is a single "device ready" lifecycle
-* barrier so exports react only when the full cap set has landed —
-* tracked separately for post-HA-integration work.
-*/
-function canonicalHash(value) {
-	const canonical = JSON.stringify(value, replaceWithSortedKeys);
-	return createHash("sha256").update(canonical ?? "").digest("hex");
-}
-function replaceWithSortedKeys(_key, value) {
-	if (value && typeof value === "object" && !Array.isArray(value)) {
-		const obj = value;
-		const out = {};
-		for (const k of Object.keys(obj).toSorted()) out[k] = obj[k];
-		return out;
-	}
-	return value;
-}
-//#endregion
 //#region src/utils/export-reconciler.ts
 /**
 * Compute the stable 64-char lowercase-hex fingerprint of a device's
@@ -666,4 +634,269 @@ function resolveExportFingerprint(input) {
 	return input.persisted ?? input.fresh;
 }
 //#endregion
-export { FilesystemStorageProvider, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, resolveExportFingerprint };
+//#region src/ffmpeg/process.ts
+/**
+* `FfmpegProcess` — the ONE spawn/lifecycle wrapper for a live-media ffmpeg.
+*
+* Extracted from `TranscodeEgress.spawnAttempt`, which was already the most
+* complete of the repo's hand-rolled lifecycles: first-data deadline, hardware
+* →software retry, SIGTERM-then-SIGKILL. This generalises it and adds the two
+* things every copy was missing — a `tags: { deviceId }` on every line, and a
+* bounded restart — so a consumer gets them by construction instead of by
+* remembering.
+*
+* ## What it owns
+*
+* - spawn, with the argv from the ONE builder (`./invocation.js`);
+* - a FIRST-DATA deadline: an ffmpeg that starts but never emits is dead, and
+*   nothing downstream can tell that apart from a slow camera;
+* - HARDWARE→SOFTWARE retry, announced at `warn`. A silent downgrade on this
+*   hub is a flow bug, not a capability limit — see `docs/design/decode-path.md`;
+* - exit classification (`ok` / `signalled-by-us` / `crashed` / `no-output`);
+* - bounded restart with backoff, and a terminal give-up (never an infinite
+*   loop — the same rule `CrashSupervisor` enforces for runners, D6);
+* - SIGTERM then SIGKILL after a grace, gated on the child not having already
+*   exited.
+*
+* ## What it does NOT own
+*
+* The output PLUMBING. A consumer attaches to `stdout` / `stderr` itself,
+* because what the bytes mean is the consumer's business: the broker deframes
+* Annex-B into a restreamer, the WebRTC leg regroups access units, HomeKit
+* writes nothing to stdout at all (its output is two RTP sockets). A wrapper
+* that also owned the bytes would need a mode per consumer, which is the same
+* mistake as one builder per consumer.
+*/
+var DEFAULT_FIRST_DATA_TIMEOUT_MS = 8e3;
+var DEFAULT_RESTART_DELAY_MS = 1e3;
+var DEFAULT_STABLE_RUN_MS = 3e4;
+var DEFAULT_KILL_GRACE_MS = 500;
+var STDERR_TAIL_LINES = 12;
+var FfmpegProcess = class {
+	opts;
+	child = null;
+	stopped = false;
+	producedOutput = false;
+	consecutiveFailures = 0;
+	startedAtMs = 0;
+	stderrTail = [];
+	activeHwAccel;
+	triedSoftwareFallback = false;
+	firstDataTimer = null;
+	constructor(opts) {
+		this.opts = opts;
+		this.activeHwAccel = opts.decodeHwAccel;
+	}
+	/** Queryable tags on every line — `deviceId` is never optional. */
+	get logTags() {
+		return {
+			deviceId: this.opts.deviceId,
+			...this.opts.tags
+		};
+	}
+	get now() {
+		return (this.opts.now ?? Date.now)();
+	}
+	/** `true` while a child is running. */
+	isRunning() {
+		return this.child !== null && !this.stopped;
+	}
+	/** The backend the CURRENT child decodes with (`null` ⇒ software). */
+	activeDecodeHwAccel() {
+		return this.activeHwAccel;
+	}
+	/**
+	* Spawn the first child. Resolves as soon as it produces output; rejects if
+	* it dies or stays silent past the deadline AFTER the software retry has
+	* also been exhausted. A caller that wants fire-and-forget can ignore the
+	* promise — the restart loop runs regardless.
+	*/
+	start() {
+		return new Promise((resolve, reject) => {
+			this.spawnAttempt(resolve, reject);
+		});
+	}
+	spawnAttempt(onLive, onDead) {
+		if (this.stopped) return;
+		const args = [...this.opts.buildArgs(this.activeHwAccel)];
+		const spawnFn = this.opts.spawnFn ?? spawn;
+		const setTimeoutImpl = this.opts.setTimeoutFn ?? setTimeout;
+		this.opts.logger.info(`ffmpeg ${this.opts.role}: spawning`, {
+			tags: this.logTags,
+			meta: {
+				decodeHwAccel: this.activeHwAccel ?? "software",
+				attempt: this.consecutiveFailures + 1
+			}
+		});
+		let child;
+		try {
+			child = spawnFn(this.opts.binaryPath, args, { stdio: this.opts.stdio ?? [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+		} catch (err) {
+			this.handleFailure("crashed", null, null, err, onLive, onDead);
+			return;
+		}
+		this.child = child;
+		this.startedAtMs = this.now;
+		this.producedOutput = false;
+		this.stderrTail = [];
+		let settled = false;
+		const timeoutMs = this.opts.firstDataTimeoutMs ?? DEFAULT_FIRST_DATA_TIMEOUT_MS;
+		if (timeoutMs > 0) this.firstDataTimer = setTimeoutImpl(() => {
+			if (settled || this.producedOutput || this.stopped) return;
+			settled = true;
+			this.opts.logger.warn(`ffmpeg ${this.opts.role}: no output within ${timeoutMs}ms`, {
+				tags: this.logTags,
+				meta: { decodeHwAccel: this.activeHwAccel ?? "software" }
+			});
+			this.killChild();
+			this.handleFailure("no-output", null, null, null, onLive, onDead);
+		}, timeoutMs);
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (line) => {
+			const text = String(line).trim();
+			if (text.length === 0) return;
+			this.stderrTail.push(text);
+			if (this.stderrTail.length > STDERR_TAIL_LINES) this.stderrTail.shift();
+			this.opts.logger.debug(`ffmpeg ${this.opts.role}`, {
+				tags: this.logTags,
+				meta: { line: text }
+			});
+		});
+		child.once("error", (err) => {
+			if (settled || this.stopped) return;
+			settled = true;
+			this.handleFailure("crashed", null, null, err, onLive, onDead);
+		});
+		child.once("exit", (code, signal) => {
+			this.clearFirstDataTimer();
+			if (this.child === child) this.child = null;
+			if (this.stopped) {
+				this.report("stopped", code, signal);
+				return;
+			}
+			if (settled && this.producedOutput) {
+				this.report("crashed", code, signal);
+				this.scheduleRestart(onLive, onDead);
+				return;
+			}
+			if (settled) return;
+			settled = true;
+			this.handleFailure(this.producedOutput ? "crashed" : "no-output", code, signal, null, onLive, onDead);
+		});
+		this.opts.onChild(child);
+		child.stdout?.once("data", () => {
+			this.producedOutput = true;
+			this.clearFirstDataTimer();
+			if (settled) return;
+			settled = true;
+			this.opts.logger.info(`ffmpeg ${this.opts.role}: live`, {
+				tags: this.logTags,
+				meta: { decodeHwAccel: this.activeHwAccel ?? "software" }
+			});
+			onLive();
+		});
+	}
+	/**
+	* A child failed before going live. Try SOFTWARE once if it was decoding in
+	* hardware — loudly — then fall through to the bounded restart.
+	*/
+	handleFailure(classification, code, signal, err, onLive, onDead) {
+		this.report(classification, code, signal, err);
+		if (this.activeHwAccel !== null && !this.triedSoftwareFallback && !this.stopped) {
+			this.triedSoftwareFallback = true;
+			this.opts.logger.warn(`ffmpeg ${this.opts.role}: hardware decode produced no output — retrying in SOFTWARE`, {
+				tags: this.logTags,
+				meta: {
+					decodeHwAccel: this.activeHwAccel,
+					classification,
+					code,
+					signal,
+					stderrTail: this.stderrTail
+				}
+			});
+			this.activeHwAccel = null;
+			this.spawnAttempt(onLive, onDead);
+			return;
+		}
+		this.consecutiveFailures += 1;
+		const maxRestarts = this.opts.maxRestarts ?? 0;
+		if (this.consecutiveFailures > maxRestarts || this.stopped) {
+			const reason = `ffmpeg ${this.opts.role} gave up after ${this.consecutiveFailures} attempt(s) (${classification}, code=${code} signal=${signal})`;
+			this.opts.logger.error(reason, {
+				tags: this.logTags,
+				meta: { stderrTail: this.stderrTail }
+			});
+			onDead(new Error(reason));
+			return;
+		}
+		this.scheduleRestart(onLive, onDead);
+	}
+	scheduleRestart(onLive, onDead) {
+		if (this.stopped) return;
+		const maxRestarts = this.opts.maxRestarts ?? 0;
+		if (maxRestarts === 0) return;
+		if (this.producedOutput && this.now - this.startedAtMs >= (this.opts.stableRunMs ?? DEFAULT_STABLE_RUN_MS)) this.consecutiveFailures = 0;
+		if (this.consecutiveFailures > maxRestarts) return;
+		(this.opts.setTimeoutFn ?? setTimeout)(() => {
+			if (this.stopped) return;
+			this.spawnAttempt(onLive, onDead);
+		}, (this.opts.restartDelayMs ?? DEFAULT_RESTART_DELAY_MS) * Math.min(this.consecutiveFailures + 1, 8));
+	}
+	report(classification, code, signal, err) {
+		const exit = {
+			classification,
+			code,
+			signal,
+			stderrTail: [...this.stderrTail],
+			decodeHwAccel: this.activeHwAccel
+		};
+		if (classification === "crashed" || classification === "no-output") this.opts.logger.warn(`ffmpeg ${this.opts.role} exited: ${classification}`, {
+			tags: this.logTags,
+			meta: {
+				code,
+				signal,
+				decodeHwAccel: this.activeHwAccel ?? "software",
+				error: err instanceof Error ? err.message : err === void 0 ? void 0 : String(err),
+				stderrTail: exit.stderrTail
+			}
+		});
+		this.opts.onExit?.(exit);
+	}
+	clearFirstDataTimer() {
+		if (this.firstDataTimer !== null) {
+			clearTimeout(this.firstDataTimer);
+			this.firstDataTimer = null;
+		}
+	}
+	/** Terminate for good. Idempotent; no restart follows. */
+	stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.clearFirstDataTimer();
+		this.killChild();
+	}
+	killChild() {
+		const child = this.child;
+		this.child = null;
+		if (!child) return;
+		if (child.exitCode !== null || child.signalCode !== null) return;
+		try {
+			child.kill("SIGTERM");
+		} catch {
+			return;
+		}
+		const grace = (this.opts.setTimeoutFn ?? setTimeout)(() => {
+			if (child.exitCode !== null || child.signalCode !== null) return;
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+		}, this.opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS);
+		if (typeof grace === "object" && grace !== null && "unref" in grace) grace.unref();
+	}
+};
+//#endregion
+export { FfmpegProcess, FilesystemStorageProvider, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, resolveExportFingerprint };