@camstack/addon-pipeline 1.2.307 → 1.2.308

package/dist/stream-broker/index.mjs

@@ -1,10 +1,10 @@
 import { r as __toESM } from "../chunk-DnnnRqeS.mjs";
-import { An as array, Bn as union, Cn as makeSourceBrokerId, En as parseProfileBrokerId, Fn as number, Ft as rankStreams, H as addonWidgetsSourceCapability, Ht as resolveEgressDecodeHwAccel, In as object, K as batteryCapability, M as RATE_CONTROL_TIGHT, Mn as discriminatedUnion, Pn as literal, Q as declareLogChannel, R as RingBuffer, Rn as record, Sn as makeProfileBrokerId, St as maskUrlCredentials, Vn as EventCategory, X as createHwAccelCache, Xt as streamBrokerCapability, Y as clipExportFailureOf, Z as createLogChannelsProvider, a as BatteryStatusSchema, at as egressTransportFromRequest, bt as logChannelsCapability, cn as DeviceFeature, dn as BOOT_RECOVERY_BACKOFF_MS, en as webrtcSessionCapability, et as deriveBatteryPresence, fn as BaseAddon, ft as ffmpegRate, gn as createEvent, ht as gifFromMp4Args, in as buildFfmpegArgs$1, it as egressTranscodeSharingKey, j as RATE_CONTROL_RELAXED, jn as boolean, kn as _enum, ln as DeviceType, mn as CamProfileSchema, mt as gifDeriveSpeed, o as CLIP_BROKER_PACED_RATES, on as invocationFromEncodeProfile, pn as CAM_PROFILE_ORDER, q as cameraStreamsCapability, s as CLIP_STILL_REASON_CODE_HEADER, sn as isSoftwareDecode, tn as AUDIO_PRESETS, un as errMsg, w as G711_SCALE_CORRECTION_DB, wn as nodePin, x as EncodeProfileSchema, xn as isEvent, yn as expandAudioChunkToF32le, yt as loadContributionCapability, zn as string } from "../dist-DdVMFlJ6.mjs";
-import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-COu_tHy4.mjs";
+import { An as _enum, Bn as string, Cn as makeProfileBrokerId, Dn as parseProfileBrokerId, Fn as literal, H as addonWidgetsSourceCapability, Hn as EventCategory, In as number, It as rankStreams, K as batteryCapability, Ln as object, M as RATE_CONTROL_TIGHT, Mn as boolean, Nn as discriminatedUnion, Q as declareLogChannel, R as RingBuffer, Sn as isEvent, St as maskUrlCredentials, Tn as nodePin, Tt as memoizePinnedFfmpeg, Ut as resolveEgressDecodeHwAccel, Vn as union, X as createHwAccelCache, Y as clipExportFailureOf, Z as createLogChannelsProvider, Zt as streamBrokerCapability, _n as createEvent, a as BatteryStatusSchema, an as buildFfmpegArgs$1, at as egressTransportFromRequest, bn as expandAudioChunkToF32le, bt as logChannelsCapability, cn as isSoftwareDecode, dn as errMsg, et as deriveBatteryPresence, fn as BOOT_RECOVERY_BACKOFF_MS, ft as ffmpegRate, hn as CamProfileSchema, ht as gifFromMp4Args, it as egressTranscodeSharingKey, j as RATE_CONTROL_RELAXED, jn as array, ln as DeviceFeature, mn as CAM_PROFILE_ORDER, mt as gifDeriveSpeed, nn as AUDIO_PRESETS, o as CLIP_BROKER_PACED_RATES, pn as BaseAddon, q as cameraStreamsCapability, s as CLIP_STILL_REASON_CODE_HEADER, sn as invocationFromEncodeProfile, tn as webrtcSessionCapability, un as DeviceType, w as G711_SCALE_CORRECTION_DB, wn as makeSourceBrokerId, x as EncodeProfileSchema, yt as loadContributionCapability, zn as record } from "../dist-jy-7xoW5.mjs";
+import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-NCge1qZM.mjs";
 import { a as parseRestreamPath, d as PREBUFFER_MAX_MS, f as capPreRollRequestMs, i as isLiveEdgeOnlyDial, m as resolvePrebuffer, n as NO_DECLARATION, p as prebufferRetentionMs, s as sdpVariantFor, u as withSentryIntent } from "../restream-intent-DyGmLAU9.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
 import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DZvlso2l.mjs";
-import { a as avccSampleToAnnexB, i as require_mp4box_all, n as demuxSegmentPreferJs, o as buildKeyframeAnnexB, r as runFfmpegOnce, s as parseNalLengthSize, t as demuxSegmentFullJs } from "../segment-demux-js-CEJn4BR0.mjs";
+import { a as require_mp4box_all, c as parseNalLengthSize, i as runFfmpegOnce, n as demuxSegmentPreferJs, o as avccSampleToAnnexB, r as FfmpegFallbackRefusedError, s as buildKeyframeAnnexB, t as demuxSegmentFullJs } from "../segment-demux-js-BaI2VdPX.mjs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
@@ -99,6 +99,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
 /**
@@ -5449,6 +5529,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;
@@ -6566,13 +6656,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 ?? spawn,
 			acquireChannel: () => channel,
 			...spec.onDied ? { onChildExit: spec.onDied } : {},
@@ -6604,10 +6700,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 Fmp4FragmentChild({
 			logger: this.opts.logger.child("egress-fmp4"),
-			ffmpegBinaryPath: this.opts.ffmpegConfig().binaryPath,
+			ffmpegBinaryPath,
 			spawnFn: this.opts.spawnFn ?? spawn,
 			...this.opts.fragmentFirstUnitTimeoutMs === void 0 ? {} : { firstUnitTimeoutMs: this.opts.fragmentFirstUnitTimeoutMs },
 			...spec.onDied ? { onChildExit: spec.onDied } : {}
@@ -6657,7 +6753,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;
@@ -6675,7 +6771,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 } : {}
@@ -6702,7 +6798,7 @@ var EgressTranscodeManager = class {
 				meta: {
 					brokerId: spec.brokerId,
 					camStreamId: spec.publishedCamStreamId,
-					ffmpegPath: this.opts.ffmpegConfig().binaryPath,
+					ffmpegPath: ffmpegBinaryPath,
 					decodeHwAccel: decodeHwAccel ?? "software",
 					argv: args.join(" ")
 				}
@@ -7121,7 +7217,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"
@@ -7985,7 +8081,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
@@ -12802,11 +12898,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). */
@@ -13389,12 +13486,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
@@ -15320,18 +15426,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: 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)
 		}, {
@@ -16307,7 +16423,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
 };
@@ -16341,6 +16457,7 @@ var TranscodePipelineManager = class {
 	resolveProfileSource;
 	releaseGraceMs;
 	ffmpegConfig;
+	onFfmpegMissing;
 	resolveStreamHwAccel;
 	spawnFn;
 	acquireChannel;
@@ -16353,6 +16470,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 ?? probeFfmpegBinary;
 		this.resolveStreamHwAccel = opts.resolveStreamHwAccel ?? null;
 		this.spawnFn = opts.spawnFn ?? spawn;
@@ -16425,11 +16543,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
 		});
@@ -16459,7 +16583,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
 		}, {
@@ -16688,11 +16812,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;
@@ -17373,12 +17498,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
 	};
@@ -17414,6 +17541,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),
@@ -17476,6 +17604,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) => {
@@ -17851,11 +17980,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 +
@@ -18196,7 +18349,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,
@@ -19448,7 +19606,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,
@@ -19457,7 +19620,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 				speed: gifDeriveSpeed(gifSpeed, input.speed),
 				...this.logger !== void 0 ? { logger: this.logger } : {},
 				spawnFn: spawn,
-				...this.ffmpegConfig.binaryPath !== void 0 ? { ffmpegPath: this.ffmpegConfig.binaryPath } : {}
+				ffmpegPath: gifFfmpeg
 			});
 			if (gif !== null) {
 				const height = scaledHeight(cut, input.gifMaxWidth);
@@ -19626,7 +19789,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", {
@@ -21704,7 +21872,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);
@@ -21882,7 +22050,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 })
 		}, {
@@ -33830,7 +34003,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 demuxSegmentPreferJs(bytes, {
 		...opts,
 		jsParse: offThreadJsParse
@@ -34015,9 +34188,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 runFfmpegOnce({
 		ffmpegPath,
 		args: SEGMENT_AUDIO_FFMPEG_ARGS,
@@ -34149,15 +34322,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 runFfmpegOnce({
-			ffmpegPath: opts.ffmpegPath ?? "ffmpeg",
+			ffmpegPath: opts.ffmpegPath,
 			args: SEGMENT_AUDIO_OPUS_FFMPEG_ARGS,
 			input: bytes,
 			tolerateNonZeroExit: true
@@ -35219,12 +35396,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;
@@ -35239,6 +35429,9 @@ var BrokerWebrtcServer = class {
 						}
 					});
 				}
+			}).catch((err) => {
+				if (err instanceof FfmpegFallbackRefusedError) reportNoPinnedFfmpeg("video");
+				throw err;
 			});
 			const scrubCache = new ScrubFragmentCache();
 			const initialLiveProfile = this.profileTierResolver?.(brokerId) ?? null;
@@ -35354,9 +35547,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: {
@@ -35370,7 +35565,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,
@@ -36820,10 +37022,21 @@ var PROBE_SNAPSHOTS_PERSIST_INTERVAL_MS = 6e4;
 var NETWORK_QUALITY_STATS_TIMEOUT_MS = 2e3;
 var StreamBrokerAddon = class extends 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 = 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;
@@ -36884,36 +37097,7 @@ var StreamBrokerAddon = class extends 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: 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) } });
@@ -36943,7 +37127,16 @@ var StreamBrokerAddon = class extends 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();
@@ -37228,7 +37421,10 @@ var StreamBrokerAddon = class extends 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;
@@ -37638,6 +37834,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;
@@ -37646,8 +37844,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();
@@ -37658,7 +37857,8 @@ var FfmpegDecoderSession = class {
 		this.outputBuffer = Buffer.alloc(0);
 		this.cachedWidth = 0;
 		this.cachedHeight = 0;
-		const child = spawn("ffmpeg", buildFfmpegArgs(this.config));
+		const args = buildFfmpegArgs(this.config);
+		const child = spawn(this.ffmpegPath, args);
 		this.process = child;
 		child.stdin?.on("error", () => {});
 		child.stdout?.on("data", (chunk) => {
@@ -37791,7 +37991,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. */
@@ -37799,8 +38006,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