@camstack/addon-pipeline 1.2.307 → 1.2.308

package/dist/stream-broker/index.js

@@ -3,12 +3,12 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-CyJWk-_f.js");
-const require_node = require("../node-HsWG5fGp.js");
+const require_dist = require("../dist-CdRsXAov.js");
+const require_node = require("../node-pWHpwpBa.js");
 const require_restream_intent = require("../restream-intent-7uDNqMKs.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_retire_root_keys = require("../retire-root-keys-Csb8z2f3.js");
-const require_segment_demux_js = require("../segment-demux-js-BrKa7tpr.js");
+const require_segment_demux_js = require("../segment-demux-js-0bM2Anej.js");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_crypto = require("node:crypto");
@@ -103,6 +103,86 @@ function createClientLogIngest(onEntries) {
 		});
 	};
 }
+var FfmpegReresolver = class {
+	deps;
+	inFlight = null;
+	lastAttemptAt = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Ask again, unless an attempt is running or one started inside the bound.
+	* Never throws; the outcome is logged either way.
+	*/
+	request(reason) {
+		if (this.inFlight !== null) return "in-flight";
+		const now = (this.deps.now ?? Date.now)();
+		const minIntervalMs = this.deps.minIntervalMs ?? 3e4;
+		if (this.lastAttemptAt !== null && now - this.lastAttemptAt < minIntervalMs) return "too-soon";
+		this.lastAttemptAt = now;
+		this.deps.logger.warn("stream-broker: re-resolving the pinned ffmpeg after a refusal (D540)", { meta: { reason } });
+		this.inFlight = this.attempt().finally(() => {
+			this.inFlight = null;
+		});
+		return "started";
+	}
+	/** The attempt in flight, for a caller (or a spec) that wants to wait. */
+	settled() {
+		return this.inFlight ?? Promise.resolve();
+	}
+	async attempt() {
+		try {
+			const binaryPath = await this.deps.resolve();
+			this.deps.apply(binaryPath);
+			this.deps.logger.info("stream-broker: pinned ffmpeg resolved on retry — children may spawn", { meta: { binaryPath } });
+		} catch (err) {
+			this.deps.logger.error("stream-broker: pinned ffmpeg still unavailable — every ffmpeg child keeps refusing", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+	}
+};
+/**
+* The broker addon's whole ffmpeg wiring, in one place a spec can drive: the
+* boot-time resolution, the refusal handler on the manager, and the
+* re-resolve that hands a later success back to the manager's config — which
+* every live broker reads per dial.
+*/
+function wireBrokerFfmpeg(deps) {
+	const give = (binaryPath) => {
+		deps.host.setFfmpegConfig({
+			binaryPath,
+			hwAccel: deps.hwAccel(),
+			threadCount: 0
+		});
+		deps.onBinaryPath?.(binaryPath);
+	};
+	const reresolver = new FfmpegReresolver({
+		resolve: deps.resolve,
+		apply: give,
+		logger: deps.logger,
+		...deps.now !== void 0 ? { now: deps.now } : {},
+		...deps.minIntervalMs !== void 0 ? { minIntervalMs: deps.minIntervalMs } : {}
+	});
+	deps.host.setFfmpegMissingHandler(() => {
+		reresolver.request("a broker ffmpeg child was refused");
+	});
+	return {
+		load: async () => {
+			try {
+				const binaryPath = await deps.resolve();
+				give(binaryPath);
+				deps.logger.info("Loaded ffmpeg config", { meta: {
+					binaryPath,
+					hwAccel: deps.hwAccel()
+				} });
+			} catch (err) {
+				give(null);
+				deps.logger.error("stream-broker: could not resolve the pinned ffmpeg — every ffmpeg child on this node refuses until this is fixed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			}
+		},
+		request: (reason) => reresolver.request(reason),
+		settled: () => reresolver.settled()
+	};
+}
 //#endregion
 //#region src/stream-broker/log-channels.ts
 /**
@@ -5453,6 +5533,16 @@ function classifyDecodeHwAccel(setting) {
 		prefer: setting
 	};
 }
+/**
+* The binary to spawn, or a THROW after an ERROR naming the camera and the
+* child that was refused. Never a PATH name (D540).
+*/
+function requireBrokerFfmpeg(binaryPath, ask) {
+	if (binaryPath !== null) return binaryPath;
+	ask.logger.error(`${ask.purpose} refused — no pinned ffmpeg on this node (D540)`, { ...ask.deviceId !== null ? { tags: { deviceId: ask.deviceId } } : {} });
+	ask.onMissing?.();
+	throw new Error(`${ask.purpose}: no pinned ffmpeg resolved on this node`);
+}
 /** Narrow an audio target to a sidecar-capable codec, or `null` (copy/none). */
 function toAudioSidecarCodec(audio) {
 	return audio === "aac" || audio === "opus" || audio === "pcmu" ? audio : null;
@@ -6570,13 +6660,19 @@ var EgressTranscodeManager = class {
 	}
 	createChild(spec) {
 		if (this.opts.createChild) return this.opts.createChild(spec);
-		if (spec.fragments) return this.createFragmentChild(spec, spec.fragments);
-		if (spec.pushSink) return this.createPushChild(spec, spec.pushSink);
+		const ffmpegBinaryPath = requireBrokerFfmpeg(this.opts.ffmpegConfig().binaryPath, {
+			logger: this.opts.logger,
+			deviceId: spec.deviceId,
+			purpose: "egress transcode",
+			...this.opts.onFfmpegMissing === void 0 ? {} : { onMissing: this.opts.onFfmpegMissing }
+		});
+		if (spec.fragments) return this.createFragmentChild(spec, spec.fragments, ffmpegBinaryPath);
+		if (spec.pushSink) return this.createPushChild(spec, spec.pushSink, ffmpegBinaryPath);
 		const channel = spec.channel;
 		if (channel === void 0) throw new Error("egress transcode: a dial child was created without a channel");
 		const egress = new TranscodeEgress({
 			logger: this.opts.logger.child("egress"),
-			ffmpegBinaryPath: this.opts.ffmpegConfig().binaryPath,
+			ffmpegBinaryPath,
 			spawnFn: this.opts.spawnFn ?? node_child_process.spawn,
 			acquireChannel: () => channel,
 			...spec.onDied ? { onChildExit: spec.onDied } : {},
@@ -6608,10 +6704,10 @@ var EgressTranscodeManager = class {
 	* same shape as the other two transports; this wrapper is the adapter, not
 	* the logic. See the primitive's `ffmpeg/fmp4-fragment-child.ts`.
 	*/
-	createFragmentChild(spec, fragments) {
+	createFragmentChild(spec, fragments, ffmpegBinaryPath) {
 		const child = new require_node.Fmp4FragmentChild({
 			logger: this.opts.logger.child("egress-fmp4"),
-			ffmpegBinaryPath: this.opts.ffmpegConfig().binaryPath,
+			ffmpegBinaryPath,
 			spawnFn: this.opts.spawnFn ?? node_child_process.spawn,
 			...this.opts.fragmentFirstUnitTimeoutMs === void 0 ? {} : { firstUnitTimeoutMs: this.opts.fragmentFirstUnitTimeoutMs },
 			...spec.onDied ? { onChildExit: spec.onDied } : {}
@@ -6661,7 +6757,7 @@ var EgressTranscodeManager = class {
 	* masked the same failure on the dial path with its own software retry, which
 	* is why only this transport was dark.
 	*/
-	createPushChild(spec, sink) {
+	createPushChild(spec, sink, ffmpegBinaryPath) {
 		const logger = this.opts.logger.child("egress-push");
 		const deviceId = spec.deviceId;
 		const timeoutMs = this.opts.pushFirstPacketTimeoutMs ?? DEFAULT_PUSH_FIRST_PACKET_TIMEOUT_MS;
@@ -6679,7 +6775,7 @@ var EgressTranscodeManager = class {
 		const makeReader = (input) => {
 			if (this.opts.createPushReader) return this.opts.createPushReader(input);
 			return new FfmpegPushReader({
-				ffmpegPath: this.opts.ffmpegConfig().binaryPath,
+				ffmpegPath: ffmpegBinaryPath,
 				args: [...input.args],
 				logger,
 				...this.opts.spawnFn ? { spawnFn: this.opts.spawnFn } : {}
@@ -6706,7 +6802,7 @@ var EgressTranscodeManager = class {
 				meta: {
 					brokerId: spec.brokerId,
 					camStreamId: spec.publishedCamStreamId,
-					ffmpegPath: this.opts.ffmpegConfig().binaryPath,
+					ffmpegPath: ffmpegBinaryPath,
 					decodeHwAccel: decodeHwAccel ?? "software",
 					argv: args.join(" ")
 				}
@@ -7125,7 +7221,7 @@ async function gifFromMp4(input) {
 }
 function runGif(input, args) {
 	return new Promise((resolve, reject) => {
-		const proc = input.spawnFn(input.ffmpegPath ?? "ffmpeg", [...args], { stdio: [
+		const proc = input.spawnFn(input.ffmpegPath, [...args], { stdio: [
 			"pipe",
 			"pipe",
 			"pipe"
@@ -7989,7 +8085,7 @@ async function renderPreBufferClip(input) {
 			hevc,
 			sourceWidth: input.sourceWidth ?? 0
 		});
-		const proc = input.spawn(input.ffmpegPath ?? "ffmpeg", clipFfmpegArgs({
+		const proc = input.spawn(input.ffmpegPath, clipFfmpegArgs({
 			...input,
 			hevc,
 			copyVideo
@@ -12806,11 +12902,12 @@ var StreamBroker = class StreamBroker {
 	/** Active "ffmpeg parser" ingress reader when `source.ffmpegParser` is set. */
 	ffmpegSourceReader = null;
 	/**
-	* Resolved `ffmpeg` binary path for the ffmpeg-parser ingress, threaded from
-	* the manager's system-config (`ffmpeg.binaryPath`). Defaults to bare
-	* `'ffmpeg'` (PATH lookup) for tests / stand-alone callers.
+	* Where the ffmpeg-parser ingress reads the node's pinned ffmpeg — the
+	* manager's LIVE config, asked at each dial rather than copied at creation,
+	* so a broker created while a re-resolve was in flight still sees its result.
+	* `null` — the ingress REFUSES by name; there is no PATH default (D540).
 	*/
-	ffmpegBinaryPath = "ffmpeg";
+	ffmpegBinaryPathSource = () => null;
 	rtpDepacketizer = null;
 	/** Flag-only depacketizer for the `push-rtp` source-RTP pre-buffer path
 	*  (sets keyframe/param-set flags without re-emitting AnnexB packets). */
@@ -13393,12 +13490,21 @@ var StreamBroker = class StreamBroker {
 		this.restreamUrlResolver = resolver;
 	}
 	/**
-	* Inject the resolved `ffmpeg` binary path used by the "ffmpeg parser"
-	* ingress ({@link startFfmpegSourceReader}). Threaded from the manager's
-	* system-config (`ffmpeg.binaryPath`). Absent = bare `'ffmpeg'` (PATH lookup).
+	* Inject where the "ffmpeg parser" ingress ({@link startFfmpegSourceReader})
+	* reads the node's pinned ffmpeg: the manager's live config, asked per dial.
 	*/
-	setFfmpegBinaryPath(binaryPath) {
-		this.ffmpegBinaryPath = binaryPath;
+	setFfmpegBinaryPathSource(source) {
+		this.ffmpegBinaryPathSource = source;
+	}
+	/** The pinned ffmpeg this broker would spawn right now (`null` = none). */
+	getFfmpegBinaryPath() {
+		return this.ffmpegBinaryPathSource();
+	}
+	/** Told when the ingress was refused for want of the pinned ffmpeg. */
+	ffmpegMissingHandler = null;
+	/** Wire the manager's re-resolve request. */
+	setFfmpegMissingHandler(handler) {
+		this.ffmpegMissingHandler = handler;
 	}
 	/**
 	* Inject the addon's child-cost registry. Injected rather than constructed
@@ -15324,18 +15430,28 @@ var StreamBroker = class StreamBroker {
 			transport: source.ffmpegParser?.transport ?? "tcp"
 		} });
 		this.destroyFfmpegSourceReader();
+		const ffmpegPath = this.ffmpegBinaryPathSource();
+		if (ffmpegPath === null) {
+			this.logger?.error("ffmpeg source reader refused — no pinned ffmpeg on this node (D540)", {
+				...this.numericDeviceId === void 0 ? {} : { tags: { deviceId: this.numericDeviceId } },
+				meta: { url: require_dist.maskUrlCredentials(source.url) }
+			});
+			this._status = "error";
+			this.ffmpegMissingHandler?.();
+			this.scheduleReconnect();
+			return;
+		}
 		const parser = source.ffmpegParser;
 		const sourceKind = source.type === "rtmp" ? "rtmp" : source.type === "flv" || source.type === "http" ? "http" : "rtsp";
-		const args = buildFfmpegSourceReaderArgs({
-			sourceUrl: source.url,
-			sourceKind,
-			transport: parser?.transport ?? "tcp",
-			...parser?.inputArgs ? { inputArgs: parser.inputArgs } : {},
-			...parser?.outputArgs ? { outputArgs: parser.outputArgs } : {}
-		});
 		const reader = new FfmpegSourceReader({
-			ffmpegPath: this.ffmpegBinaryPath,
-			args,
+			ffmpegPath,
+			args: buildFfmpegSourceReaderArgs({
+				sourceUrl: source.url,
+				sourceKind,
+				transport: parser?.transport ?? "tcp",
+				...parser?.inputArgs ? { inputArgs: parser.inputArgs } : {},
+				...parser?.outputArgs ? { outputArgs: parser.outputArgs } : {}
+			}),
 			...this.logger ? { logger: this.logger.child("ffmpeg-source") } : {},
 			claimCost: (pid) => this.claimIngestCost(pid)
 		}, {
@@ -16311,7 +16427,7 @@ function hexToBytes(hex) {
 * pipe is the pattern proven by the WebRTC transcode feed.
 */
 var DEFAULT_FFMPEG_CONFIG = {
-	binaryPath: "ffmpeg",
+	binaryPath: null,
 	hwAccel: "copy",
 	threadCount: 0
 };
@@ -16345,6 +16461,7 @@ var TranscodePipelineManager = class {
 	resolveProfileSource;
 	releaseGraceMs;
 	ffmpegConfig;
+	onFfmpegMissing;
 	resolveStreamHwAccel;
 	spawnFn;
 	acquireChannel;
@@ -16357,6 +16474,7 @@ var TranscodePipelineManager = class {
 		this.resolveProfileSource = opts.resolveProfileSource ?? null;
 		this.releaseGraceMs = opts.releaseGraceMs ?? 5e3;
 		this.ffmpegConfig = opts.ffmpegConfig ?? (() => DEFAULT_FFMPEG_CONFIG);
+		this.onFfmpegMissing = opts.onFfmpegMissing ?? null;
 		this.probeFfmpeg = opts.probeFfmpeg ?? require_node.probeFfmpegBinary;
 		this.resolveStreamHwAccel = opts.resolveStreamHwAccel ?? null;
 		this.spawnFn = opts.spawnFn ?? node_child_process.spawn;
@@ -16429,11 +16547,17 @@ var TranscodePipelineManager = class {
 	async startTranscode(opts) {
 		if (!this.acquireChannel) throw new Error("getStreamWithCodec: transcode egress not wired (acquireChannel missing)");
 		const cfg = this.ffmpegConfig();
+		const ffmpegBinaryPath = requireBrokerFfmpeg(cfg.binaryPath, {
+			logger: this.logger,
+			deviceId: opts.deviceId,
+			purpose: "transcode egress",
+			...this.onFfmpegMissing === null ? {} : { onMissing: this.onFfmpegMissing }
+		});
 		const effectiveHwAccel = this.effectiveHwAccelSetting(opts.deviceId, opts.camStreamId, cfg.hwAccel);
 		const choice = chooseVideoEncoder({
 			target: opts.targetCodec,
 			backend: await this.resolveHardwareBackend(),
-			binaryEncoders: await this.resolveBinaryEncoders(cfg.binaryPath),
+			binaryEncoders: await this.resolveBinaryEncoders(ffmpegBinaryPath),
 			hwAccelSetting: effectiveHwAccel,
 			renderNode: DEFAULT_VAAPI_RENDER_DEVICE
 		});
@@ -16463,7 +16587,7 @@ var TranscodePipelineManager = class {
 		const sidecarCodec = opts.audioEgress ? toAudioSidecarCodec(opts.audio) : null;
 		const egress = new TranscodeEgress({
 			logger: this.logger.child("egress"),
-			ffmpegBinaryPath: cfg.binaryPath,
+			ffmpegBinaryPath,
 			spawnFn: this.spawnFn,
 			acquireChannel: this.acquireChannel
 		}, {
@@ -16692,11 +16816,12 @@ var TranscodePipelineManager = class {
 		try {
 			const backend = rankDecodeHwAccels((await this.hwaccel.resolve(prefer)).preferred, [])[0] ?? null;
 			if (backend === null) return null;
-			const caps = await this.resolveBinaryCapabilities(this.ffmpegConfig().binaryPath);
+			const binaryPath = this.ffmpegConfig().binaryPath;
+			const caps = binaryPath === null ? null : await this.resolveBinaryCapabilities(binaryPath);
 			if (caps !== null && !caps.hwaccels.has(backend)) {
 				this.logger.warn("this ffmpeg has no such decode backend compiled in — decoding in software instead of dying on a device that cannot exist", { meta: {
 					backend,
-					ffmpeg: this.ffmpegConfig().binaryPath,
+					ffmpeg: binaryPath,
 					hwaccels: [...caps.hwaccels].join(",") || "none"
 				} });
 				return null;
@@ -17377,12 +17502,14 @@ var StreamBrokerManager = class StreamBrokerManager {
 	/**
 	* Snapshot of the system `ffmpeg` config section (binaryPath / hwAccel /
 	* threadCount). Refreshed by the host addon via `setFfmpegConfig`; the
-	* transcode manager reads it live per spawn. Defaults are safe (PATH ffmpeg,
-	* `'copy'` software decode, auto threads) until the addon loads the section —
-	* software decode never hard-fails on a fragile HEVC source.
+	* transcode manager reads it live per spawn. Until the addon resolves the
+	* node's pinned binary there is NONE (`binaryPath: null`) and every child
+	* refuses by name — never a PATH `ffmpeg` (D540). `'copy'` software decode
+	* and auto threads stay the defaults: software decode never hard-fails on a
+	* fragile HEVC source.
 	*/
 	ffmpegConfig = {
-		binaryPath: "ffmpeg",
+		binaryPath: null,
 		hwAccel: "copy",
 		threadCount: 0
 	};
@@ -17418,6 +17545,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			},
 			resolveProfileSource: (deviceId, profile) => this.assignments.get(deviceId)?.map[profile] ?? null,
 			ffmpegConfig: () => this.ffmpegConfig,
+			onFfmpegMissing: () => this.reportFfmpegMissing(),
 			resolveStreamHwAccel: (deviceId, camStreamId) => this.getStreamHwAccelOverride(deviceId, camStreamId),
 			sentryOffered: async (deviceId) => sentryEligible({
 				batteryOperated: await this.isBatteryOperated(deviceId),
@@ -17480,6 +17608,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 					});
 				},
 				ffmpegConfig: () => this.ffmpegConfig,
+				onFfmpegMissing: () => this.reportFfmpegMissing(),
 				...this.costRegistry === null ? {} : { costRegistry: this.costRegistry },
 				resolveDecodeHwAccel: (deviceId, override) => this.resolveEgressHwAccel(deviceId, override),
 				acquireChannel: (brokerId) => {
@@ -17855,11 +17984,35 @@ var StreamBrokerManager = class StreamBrokerManager {
 		if (localNodeId !== void 0) this.localNodeId = localNodeId;
 		if (hwaccel !== void 0) this.hwaccel = hwaccel;
 	}
-	/** Update the system `ffmpeg` config snapshot used by the transcode egress. */
+	/**
+	* Update the node's ffmpeg config snapshot. Every broker READS it per dial
+	* ({@link bindBrokerFfmpeg}), so a re-resolved binary reaches live brokers —
+	* including one created while the re-resolve was in flight — with no copy to
+	* fan out (D540).
+	*/
 	setFfmpegConfig(cfg) {
 		this.ffmpegConfig = cfg;
 	}
 	/**
+	* Point a broker at the node's LIVE pinned ffmpeg and at the re-resolve
+	* request, so its ffmpeg-parser ingress spawns the current binary and a
+	* refusal asks for it again.
+	*/
+	bindBrokerFfmpeg(broker) {
+		broker.setFfmpegBinaryPathSource(() => this.ffmpegConfig.binaryPath);
+		broker.setFfmpegMissingHandler(() => this.reportFfmpegMissing());
+	}
+	/** Who asks for the pinned binary again after a refusal. Set by the addon. */
+	ffmpegMissingHandler = null;
+	/** Wire the host's re-resolve (`FfmpegReresolver.request`). */
+	setFfmpegMissingHandler(handler) {
+		this.ffmpegMissingHandler = handler;
+	}
+	/** A child was refused for want of the pinned ffmpeg: ask the host again. */
+	reportFfmpegMissing() {
+		this.ffmpegMissingHandler?.();
+	}
+	/**
 	* The decode `hwaccel` options surfaceable in a (future) UI: the always-valid
 	* settings (`copy`, `auto`, `none`) plus the concrete hardware backends THIS
 	* node can use, resolved from the LOCAL `ctx.kernel.hwaccel` (os.platform +
@@ -18200,7 +18353,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 		let annexB;
 		try {
 			annexB = await encodePrestreamIdr({
-				ffmpegPath: this.ffmpegConfig.binaryPath,
+				ffmpegPath: requireBrokerFfmpeg(this.ffmpegConfig.binaryPath, {
+					logger,
+					deviceId,
+					purpose: "sentry pre-stream encode",
+					onMissing: () => this.reportFfmpegMissing()
+				}),
 				plan,
 				jpeg: picture.jpeg,
 				logger,
@@ -19452,7 +19610,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 			height: scaledHeight(cut, clipWidth)
 		});
 		const gifSpeed = input.gifSpeed ?? 4;
-		if (input.kinds.includes("gif")) {
+		const gifFfmpeg = this.ffmpegConfig.binaryPath;
+		if (input.kinds.includes("gif") && gifFfmpeg === null) {
+			this.logger?.error("event media gif refused — no pinned ffmpeg on this node (D540)", { tags: { deviceId: input.deviceId } });
+			this.reportFfmpegMissing();
+		}
+		if (input.kinds.includes("gif") && gifFfmpeg !== null) {
 			const gif = await gifFromMp4({
 				mp4,
 				deviceId: input.deviceId,
@@ -19461,7 +19624,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 				speed: require_dist.gifDeriveSpeed(gifSpeed, input.speed),
 				...this.logger !== void 0 ? { logger: this.logger } : {},
 				spawnFn: node_child_process.spawn,
-				...this.ffmpegConfig.binaryPath !== void 0 ? { ffmpegPath: this.ffmpegConfig.binaryPath } : {}
+				ffmpegPath: gifFfmpeg
 			});
 			if (gif !== null) {
 				const height = scaledHeight(cut, input.gifMaxWidth);
@@ -19630,7 +19793,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 				"pipe",
 				"pipe"
 			] }),
-			ffmpegPath: this.ffmpegConfig.binaryPath,
+			ffmpegPath: requireBrokerFfmpeg(this.ffmpegConfig.binaryPath, {
+				logger: this.logger,
+				deviceId: cut.deviceId,
+				purpose: "pre-buffer clip render",
+				onMissing: () => this.reportFfmpegMissing()
+			}),
 			sdpParameterSets: cut.broker.getSdpParameterSets()
 		});
 		this.logger?.info("pre-buffer clip rendered", {
@@ -21708,7 +21876,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		const source = this.buildSourceFromCamStream(cam);
 		const broker = new StreamBroker(brokerId, this.buildDecoderCapApi(deviceId), brokerLogger, buildAudioCodecCapApi(this.api), this.localNodeId);
 		broker.setRestreamUrlResolver(() => this.rtspProvider.getEntry(brokerId)?.mutedUrl ?? null);
-		broker.setFfmpegBinaryPath(this.ffmpegConfig.binaryPath);
+		this.bindBrokerFfmpeg(broker);
 		if (this.costRegistry !== null) broker.setCostRegistry(this.costRegistry);
 		this.applyPrebufferConfig(broker, deviceId, camStreamId);
 		this.applyAudioMuteConfig(broker, deviceId);
@@ -21886,7 +22054,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 			}
 		});
 		const feeder = new DerivedStreamFeeder({
-			ffmpegPath: this.ffmpegConfig.binaryPath,
+			ffmpegPath: requireBrokerFfmpeg(this.ffmpegConfig.binaryPath, {
+				logger: this.logger,
+				deviceId,
+				purpose: "derived transcode",
+				onMissing: () => this.reportFfmpegMissing()
+			}),
 			args,
 			logger: this.logger.child(`derived-ffmpeg:${camStreamId}`).withTags({ deviceId })
 		}, {
@@ -33834,7 +34007,7 @@ var offThreadJsParse = (bytes) => {
 * Drop-in for the session `demuxVideo` hook: JS parse off the live loop,
 * ffmpeg subprocess fallback unchanged.
 */
-async function demuxSegmentPreferJsOffThread(bytes, opts = {}) {
+async function demuxSegmentPreferJsOffThread(bytes, opts) {
 	return require_segment_demux_js.demuxSegmentPreferJs(bytes, {
 		...opts,
 		jsParse: offThreadJsParse
@@ -34019,9 +34192,9 @@ function sliceMuLawToPcmuFrames(mulaw) {
 * can't decode) — ffmpeg exits non-zero, which is tolerated as empty output.
 *
 * @param bytes - The full `.m4s` fragment.
-* @param ffmpegPath - ffmpeg binary path (defaults to PATH `ffmpeg`).
+* @param ffmpegPath - The node's pinned ffmpeg (D540). Required: no PATH default.
 */
-async function demuxSegmentToPcmu(bytes, ffmpegPath = "ffmpeg") {
+async function demuxSegmentToPcmu(bytes, ffmpegPath) {
 	const mulaw = await require_segment_demux_js.runFfmpegOnce({
 		ffmpegPath,
 		args: SEGMENT_AUDIO_FFMPEG_ARGS,
@@ -34153,15 +34326,19 @@ var SEGMENT_AUDIO_OPUS_FFMPEG_ARGS = [
 * best-effort and must never block recorded video. Mirrors the video-side
 * `demuxSegmentPreferJs`.
 */
-async function demuxSegmentAudioOpusPreferJs(bytes, opts = {}) {
+async function demuxSegmentAudioOpusPreferJs(bytes, opts) {
 	try {
 		const direct = await demuxSegmentAudioOpusJs(bytes);
 		if (direct) return direct;
 	} catch {}
+	if (opts.ffmpegPath === null) {
+		opts.onFfmpegFallback?.("audio track is not Opus (legacy fragment) and the ffmpeg fallback is refused — no pinned ffmpeg on this node (D540)");
+		return [];
+	}
 	opts.onFfmpegFallback?.("audio track is not Opus (legacy fragment)");
 	try {
 		const opusFmp4 = await require_segment_demux_js.runFfmpegOnce({
-			ffmpegPath: opts.ffmpegPath ?? "ffmpeg",
+			ffmpegPath: opts.ffmpegPath,
 			args: SEGMENT_AUDIO_OPUS_FFMPEG_ARGS,
 			input: bytes,
 			tolerateNonZeroExit: true
@@ -35223,12 +35400,25 @@ var BrokerWebrtcServer = class {
 		session.onClosed = () => this.cleanupSession(sessionId);
 		const locateRecorded = this.locateRecordedSegment;
 		const readRecorded = this.readRecordedSegmentBytes;
-		const resolveFfmpeg = this.resolveFfmpegPath;
+		const resolveFfmpegPath = this.resolveFfmpegPath;
+		const resolveFfmpeg = () => resolveFfmpegPath?.() ?? null;
+		let noPinnedFfmpegLogged = false;
+		const reportNoPinnedFfmpeg = (what) => {
+			if (noPinnedFfmpegLogged) return;
+			noPinnedFfmpegLogged = true;
+			sessionLogger.error("recorded playback: ffmpeg fallback refused — no pinned ffmpeg on this node (D540)", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					what
+				}
+			});
+		};
 		const demuxTally = new DemuxPathTally();
 		let audioOpusFallbackLogged = false;
 		if (locateRecorded && readRecorded) {
 			const demuxVideo = (b) => demuxSegmentPreferJsOffThread(b, {
-				ffmpegPath: resolveFfmpeg?.(),
+				ffmpegPath: resolveFfmpeg(),
 				onDemuxPath: (outcome) => {
 					const report = demuxTally.record(outcome, Date.now());
 					if (!report) return;
@@ -35243,6 +35433,9 @@ var BrokerWebrtcServer = class {
 						}
 					});
 				}
+			}).catch((err) => {
+				if (err instanceof require_segment_demux_js.FfmpegFallbackRefusedError) reportNoPinnedFfmpeg("video");
+				throw err;
 			});
 			const scrubCache = new ScrubFragmentCache();
 			const initialLiveProfile = this.profileTierResolver?.(brokerId) ?? null;
@@ -35358,9 +35551,11 @@ var BrokerWebrtcServer = class {
 					pushAudioPcmu: (pcmu, ts) => session.writeRecordedAudio(Buffer.from(pcmu), ts)
 				};
 				const demuxAudio = opusSession ? async (b) => {
+					const ffmpegPath = resolveFfmpeg();
 					return (await demuxSegmentAudioOpusPreferJs(b, {
-						ffmpegPath: resolveFfmpeg?.(),
+						ffmpegPath,
 						onFfmpegFallback: (reason) => {
+							if (ffmpegPath === null) reportNoPinnedFfmpeg("audio");
 							if (audioOpusFallbackLogged) return;
 							audioOpusFallbackLogged = true;
 							sessionLogger.warn("recorded audio: JS Opus demux missed — ffmpeg AAC→Opus fallback (once/session)", { meta: {
@@ -35374,7 +35569,14 @@ var BrokerWebrtcServer = class {
 						data: au.data,
 						ptsMs: au.ptsMs
 					}));
-				} : (b) => demuxSegmentToPcmu(b, resolveFfmpeg?.());
+				} : async (b) => {
+					const ffmpegPath = resolveFfmpeg();
+					if (ffmpegPath === null) {
+						reportNoPinnedFfmpeg("audio");
+						return [];
+					}
+					return await demuxSegmentToPcmu(b, ffmpegPath);
+				};
 				const clipSource = clip && readClip ? createClipFileSource({
 					handle: clip,
 					read: readClip,
@@ -36824,10 +37026,21 @@ var PROBE_SNAPSHOTS_PERSIST_INTERVAL_MS = 6e4;
 var NETWORK_QUALITY_STATS_TIMEOUT_MS = 2e3;
 var StreamBrokerAddon = class extends require_dist.BaseAddon {
 	brokerManager = null;
-	/** ffmpeg binary path from the `ffmpeg` config section, mirrored here so the
-	*  recorded-playback demuxers (segment-demux/segment-audio) spawn the same
-	*  configured binary as the transcode egress. Kept in sync by loadFfmpegConfig. */
-	ffmpegBinaryPath = "ffmpeg";
+	/** The node's pinned ffmpeg, mirrored here so the recorded-playback demuxers
+	*  (segment-demux/segment-audio) spawn the same binary as the transcode
+	*  egress. Kept in sync by the ffmpeg wiring. `null` = none could be resolved:
+	*  their ffmpeg fallbacks refuse by name — never a PATH `ffmpeg` (D540). */
+	ffmpegBinaryPath = null;
+	/** The node's pinned build, asked once on success (D540). A failure is not
+	*  remembered, so the re-resolve below can succeed later. */
+	pinnedFfmpeg = require_dist.memoizePinnedFfmpeg(() => this.ctx.deps.ensureFfmpeg());
+	/**
+	* The way back from a failed boot-time resolution: a refused child asks, and
+	* ONE bounded re-resolve hands the binary to the manager config (which every
+	* live broker reads per dial) and the demuxers. Without it one failed
+	* download disabled every broker ffmpeg child until the runner restarted.
+	*/
+	ffmpegWiring = null;
 	/** Once-per-addon log guard for the readGopBytes → whole-segment downgrade. */
 	gopReadFallbackLogged = false;
 	metricsSnapshotTimer = null;
@@ -36888,36 +37101,7 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 	async resolveFfmpegBinaryPath() {
 		const override = this.config.binaryPath;
 		if (typeof override === "string" && override.trim().length > 0) return override;
-		return await this.ctx.deps.ensureFfmpeg();
-	}
-	/**
-	* Push THIS node's ffmpeg config into the broker — all node-local now, NOT the
-	* retired global `ffmpeg` section. `binaryPath` via {@link resolveFfmpegBinaryPath}
-	* (per-node override → ensureFfmpeg); `hwAccel` = the per-node `hwaccel`
-	* preference (default `'copy'` = software, the safe HEVC-compatible choice; the
-	* concrete backend is resolved node-locally by the egress transcode manager,
-	* which asks the DECODER ADDON — never the kernel resolver, whose qsv-first
-	* order is the known-bad one here). `threadCount` is always `0` (auto — ffmpeg uses the
-	* node's own cores; the manual knob was removed).
-	*/
-	async loadFfmpegConfig() {
-		if (!this.brokerManager) return;
-		try {
-			const binaryPath = await this.resolveFfmpegBinaryPath();
-			const hwAccel = this.config.hwaccel;
-			this.brokerManager.setFfmpegConfig({
-				binaryPath,
-				hwAccel,
-				threadCount: 0
-			});
-			this.ffmpegBinaryPath = binaryPath;
-			this.ctx.logger.info("Loaded ffmpeg config", { meta: {
-				binaryPath,
-				hwAccel
-			} });
-		} catch (err) {
-			this.ctx.logger.error("stream-broker: could not resolve an ffmpeg binary — no transcode on this node can be trusted until this is fixed", { meta: { error: require_dist.errMsg(err) } });
-		}
+		return await this.pinnedFfmpeg();
 	}
 	async onInitialize() {
 		this.ctx.logger.info("log channels declared", { meta: { channels: STREAM_BROKER_LOG_CHANNELS.map((c) => c.descriptor.name) } });
@@ -36947,7 +37131,16 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 		};
 		this.brokerManager.setDeviceSignalReader(async (deviceId) => (await readSignals(deviceId)).map((s) => s.code));
 		this.brokerManager.setDeviceSignalDetailReader(readSignals);
-		await this.loadFfmpegConfig();
+		this.ffmpegWiring = wireBrokerFfmpeg({
+			host: this.brokerManager,
+			resolve: () => this.resolveFfmpegBinaryPath(),
+			hwAccel: () => this.config.hwaccel,
+			onBinaryPath: (binaryPath) => {
+				this.ffmpegBinaryPath = binaryPath;
+			},
+			logger: this.ctx.logger
+		});
+		await this.ffmpegWiring.load();
 		await this.declareRowCollections();
 		await this.purgeFlattenedSettingsKeys();
 		const rtspProvider = this.brokerManager.getRtspRestreamProvider();
@@ -37232,7 +37425,10 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 					};
 				}
 			},
-			resolveFfmpegPath: () => this.ffmpegBinaryPath
+			resolveFfmpegPath: () => {
+				if (this.ffmpegBinaryPath === null) this.ffmpegWiring?.request("a recorded-playback demux needed ffmpeg");
+				return this.ffmpegBinaryPath;
+			}
 		});
 		this.brokerManager.setWebrtcServer(webrtcServer);
 		this.webrtcServer = webrtcServer;
@@ -37642,6 +37838,8 @@ var FfmpegDecoderSession = class {
 	outputBuffer = Buffer.alloc(0);
 	destroyed = false;
 	logger;
+	/** The pinned ffmpeg to spawn (D540). Required: there is no PATH default. */
+	ffmpegPath;
 	cachedWidth = 0;
 	cachedHeight = 0;
 	inputPackets = 0;
@@ -37650,8 +37848,9 @@ var FfmpegDecoderSession = class {
 	totalDecodeTimeMs = 0;
 	decodeCount = 0;
 	startTime = Date.now();
-	constructor(config, logger = noopLogger) {
+	constructor(config, ffmpegPath, logger = noopLogger) {
 		this.config = { ...config };
+		this.ffmpegPath = ffmpegPath;
 		this.logger = logger;
 		this.frameDropper = new FrameDropper(config.maxFps);
 		this.spawnFfmpeg();
@@ -37662,7 +37861,8 @@ var FfmpegDecoderSession = class {
 		this.outputBuffer = Buffer.alloc(0);
 		this.cachedWidth = 0;
 		this.cachedHeight = 0;
-		const child = (0, node_child_process.spawn)("ffmpeg", buildFfmpegArgs(this.config));
+		const args = buildFfmpegArgs(this.config);
+		const child = (0, node_child_process.spawn)(this.ffmpegPath, args);
 		this.process = child;
 		child.stdin?.on("error", () => {});
 		child.stdout?.on("data", (chunk) => {
@@ -37795,7 +37995,14 @@ var SUPPORTED_CODECS = new Set([
 	"hevc",
 	"mjpeg"
 ]);
+/**
+* A static decoder provider for stand-alone broker harnesses. Production
+* decodes through the `decoder` cap; this exists for the manual streaming
+* diagnostics. It is handed the pinned ffmpeg (D540) — there is no PATH
+* default for it to fall back to.
+*/
 var FfmpegDecoderProvider = class {
+	ffmpegPath;
 	id = "ffmpeg";
 	name = "FFmpeg Decoder";
 	/** Software decoder — used as fallback when hardware decoders are unavailable. */
@@ -37803,8 +38010,11 @@ var FfmpegDecoderProvider = class {
 	async supportsCodec(input) {
 		return SUPPORTED_CODECS.has(input.codec);
 	}
+	constructor(ffmpegPath) {
+		this.ffmpegPath = ffmpegPath;
+	}
 	async createSession(config) {
-		return new FfmpegDecoderSession(config);
+		return new FfmpegDecoderSession(config, this.ffmpegPath);
 	}
 };
 //#endregion