@camstack/addon-decoder-ffmpeg 1.1.4 → 1.1.6

package/dist/index.js

@@ -5,6 +5,7 @@ Object.defineProperties(exports, {
 let node_crypto = require("node:crypto");
 let _camstack_shm_ring = require("@camstack/shm-ring");
 let node_child_process = require("node:child_process");
+let node_fs = require("node:fs");
 //#region ../../node_modules/zod/v4/core/core.js
 var _a$1;
 function $constructor(name, initializer, params) {
@@ -4634,7 +4635,7 @@ function _instanceof(cls, params = {}) {
 	return inst;
 }
 //#endregion
-//#region ../types/dist/sleep-BiDFW0E7.mjs
+//#region ../types/dist/sleep-CZDdRBua.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -7241,7 +7242,16 @@ var DecoderStatsSchema = object({
 	inputFps: number(),
 	outputFps: number(),
 	avgDecodeTimeMs: number(),
-	droppedFrames: number()
+	droppedFrames: number(),
+	/**
+	* Pull-mode adaptive-fps telemetry (optional — only pull sessions run the
+	* lag-driven controller; push sessions omit these). `lagMs` is the EWMA of
+	* the decoder's real-time drift (rising = falling behind live); `adaptiveFps`
+	* is the current lag-throttled emit rate (≤ `effectiveFps` ceiling).
+	*/
+	lagMs: number().optional(),
+	effectiveFps: number().optional(),
+	adaptiveFps: number().optional()
 });
 var DecoderSessionConfigSchema = object({
 	codec: string(),
@@ -7282,7 +7292,15 @@ var DecoderSessionConfigSchema = object({
 	*   other — `pullFrames` returns nothing for an `'shm'` session and
 	*   `pullHandles` returns nothing for a `'callback'` session.
 	*/
-	frameSink: _enum(["callback", "shm"]).default("callback")
+	frameSink: _enum(["callback", "shm"]).default("callback"),
+	/**
+	* Per-camera decoder DEBUG facility. When `true`, a pull-mode session emits
+	* a throttled (~1Hz) structured `decoder debug` line (effective/adaptive fps,
+	* real-time lag, dropped-frame delta, avg decode time, hwaccel). Mirrors the
+	* stream-broker's `streamingDebug` gate — off by default so production logs
+	* stay quiet and the emit path pays zero per-frame cost when disabled.
+	*/
+	debug: boolean().optional()
 });
 var EncodeProfileSchema = object({
 	video: object({
@@ -9440,6 +9458,75 @@ DeviceType.Cover, method(object({ deviceId: number().int().nonnegative() }), _vo
 	auth: "admin"
 });
 /**
+* Vendor-neutral day/night (IR-cut) control — the per-camera config cap
+* shared by reolink / hikvision / amcrest. Models the common firmware
+* surface: the IR-cut switching MODE plus the two knobs that gate it
+* (photocell `sensitivity` + `switchDelaySec`). Each vendor maps these
+* onto its own ISAPI / Baichuan / Dahua-CGI fields; the cap standardises
+* the shape so ONE derived-form renders every camera.
+*
+* Follows the D14 `deviceConfig` archetype (see `stream-params.cap.ts`):
+* `getOptions` advertises per-camera availability, `getStatus` (auto-
+* injected from `status`) reports the live values, and a single
+* `setSettings` mutation applies a partial change. No hand-written
+* settings-contribution methods — the framework derives the UI + save
+* routing from this surface.
+*/
+/** IR-cut switching mode. `schedule` = time-of-day table configured on the camera. */
+var DayNightModeSchema = _enum([
+	"auto",
+	"day",
+	"night",
+	"schedule"
+]);
+/** Normalized numeric range descriptor — `{ min, max, step }` per the
+*  getOptions availability convention. Normalized values are 0–100. */
+var NormalizedRangeSchema$1 = object({
+	min: number(),
+	max: number(),
+	step: number()
+});
+object({
+	mode: DayNightModeSchema,
+	/** IR-cut trigger sensitivity, NORMALIZED 0–100 (higher = switches to night sooner). */
+	sensitivity: number().optional(),
+	/** Delay before the IR-cut filter flips, in seconds. */
+	switchDelaySec: number().optional(),
+	lastFetchedAt: number()
+});
+/**
+* Per-camera availability descriptor — drives which controls the admin UI
+* renders. Booleans as `supportsX`; numeric ranges as `{ min, max, step }`
+* (normalized 0–100); the mode choice-set as an array. A provider returns
+* honest, camera-probed values — never hardcoded.
+*/
+var DayNightOptionsSchema = object({
+	/** Modes this camera accepts. Empty → the camera has no configurable day/night mode. */
+	modes: array(DayNightModeSchema),
+	supportsSensitivity: boolean(),
+	/** Present when `supportsSensitivity` — the normalized 0–100 range. */
+	sensitivity: NormalizedRangeSchema$1.optional(),
+	supportsSwitchDelay: boolean(),
+	/** Present when `supportsSwitchDelay` — the allowed delay range in seconds. */
+	switchDelaySec: NormalizedRangeSchema$1.optional()
+});
+/**
+* Partial change to the day/night config — every field optional. A
+* provider ignores fields it does not support.
+*/
+var DayNightSettingsPatchSchema = object({
+	mode: DayNightModeSchema.optional(),
+	sensitivity: number().optional(),
+	switchDelaySec: number().optional()
+});
+DeviceType.Camera, method(object({ deviceId: number() }), DayNightOptionsSchema), method(object({
+	deviceId: number(),
+	settings: DayNightSettingsPatchSchema
+}), _void(), {
+	kind: "mutation",
+	auth: "admin"
+});
+/**
 * Identity envelope for a device's upstream-system metadata.
 *
 * Two jobs:
@@ -9795,6 +9882,130 @@ object({
 });
 DeviceType.Image;
 /**
+* Vendor-neutral image / picture-adjustment cap — the per-camera config
+* cap shared by reolink / hikvision / amcrest. Models the common ISP
+* surface: the four picture sliders (brightness / contrast / saturation /
+* sharpness), orientation (mirror / flip / rotate), white-balance,
+* exposure and backlight-compensation modes.
+*
+* NORMALIZATION: every slider is a normalized int 0–100. Vendors expose
+* these natively as 0–100 or 0–255 (or other ranges); each provider maps
+* its native range to/from this normalized 0–100 space so the cap surface
+* (and the derived form) is identical across cameras. `warmth` (manual
+* white-balance) is likewise normalized 0–100.
+*
+* Follows the D14 `deviceConfig` archetype (see `stream-params.cap.ts`):
+* `getOptions` advertises per-camera availability, `getStatus` (auto-
+* injected from `status`) reports the live values, and a single
+* `setSettings` mutation applies a partial change. No hand-written
+* settings-contribution methods — the framework derives the UI + save
+* routing from this surface.
+*/
+/** Sensor/image rotation, degrees clockwise. */
+var ImageRotateSchema = _enum([
+	"0",
+	"90",
+	"180",
+	"270"
+]);
+/** White-balance mode. `manual` unlocks the normalized `warmth` knob. */
+var WhiteBalanceModeSchema = _enum(["auto", "manual"]);
+/** Exposure mode. */
+var ExposureModeSchema = _enum(["auto", "manual"]);
+/**
+* Backlight-compensation mode:
+*   - `off` — disabled
+*   - `blc` — backlight compensation
+*   - `wdr` — wide dynamic range
+*   - `hlc` — highlight compensation
+*/
+var BacklightModeSchema = _enum([
+	"off",
+	"blc",
+	"wdr",
+	"hlc"
+]);
+/** Normalized numeric range descriptor — `{ min, max, step }` per the
+*  getOptions availability convention. Slider values are normalized 0–100. */
+var NormalizedRangeSchema = object({
+	min: number(),
+	max: number(),
+	step: number()
+});
+object({
+	/** Normalized 0–100. */
+	brightness: number().optional(),
+	/** Normalized 0–100. */
+	contrast: number().optional(),
+	/** Normalized 0–100. */
+	saturation: number().optional(),
+	/** Normalized 0–100. */
+	sharpness: number().optional(),
+	mirror: boolean().optional(),
+	flip: boolean().optional(),
+	rotate: ImageRotateSchema.optional(),
+	whiteBalance: WhiteBalanceModeSchema.optional(),
+	/** Manual white-balance warmth, NORMALIZED 0–100. Meaningful only when `whiteBalance === 'manual'`. */
+	warmth: number().optional(),
+	exposureMode: ExposureModeSchema.optional(),
+	backlightMode: BacklightModeSchema.optional(),
+	lastFetchedAt: number()
+});
+/**
+* Per-camera availability descriptor — drives which controls the admin UI
+* renders. Booleans as `supportsX`; numeric ranges as `{ min, max, step }`
+* (the normalized 0–100 range); enums as arrays of supported values (empty
+* array → control hidden). A provider returns honest, camera-probed values
+* — never hardcoded.
+*/
+var ImageSettingsOptionsSchema = object({
+	supportsBrightness: boolean(),
+	brightness: NormalizedRangeSchema.optional(),
+	supportsContrast: boolean(),
+	contrast: NormalizedRangeSchema.optional(),
+	supportsSaturation: boolean(),
+	saturation: NormalizedRangeSchema.optional(),
+	supportsSharpness: boolean(),
+	sharpness: NormalizedRangeSchema.optional(),
+	supportsMirror: boolean(),
+	supportsFlip: boolean(),
+	/** Supported rotation values. Empty → rotation not configurable. */
+	rotateOptions: array(ImageRotateSchema),
+	/** Supported white-balance modes. Empty → white-balance not configurable. */
+	whiteBalanceModes: array(WhiteBalanceModeSchema),
+	supportsWarmth: boolean(),
+	/** Present when `supportsWarmth` — the normalized 0–100 range. */
+	warmth: NormalizedRangeSchema.optional(),
+	/** Supported exposure modes. Empty → exposure not configurable. */
+	exposureModes: array(ExposureModeSchema),
+	/** Supported backlight modes. Empty → backlight-compensation not configurable. */
+	backlightModes: array(BacklightModeSchema)
+});
+/**
+* Partial change to the image config — every field optional. Slider values
+* are normalized 0–100. A provider ignores fields it does not support.
+*/
+var ImageSettingsPatchSchema = object({
+	brightness: number().optional(),
+	contrast: number().optional(),
+	saturation: number().optional(),
+	sharpness: number().optional(),
+	mirror: boolean().optional(),
+	flip: boolean().optional(),
+	rotate: ImageRotateSchema.optional(),
+	whiteBalance: WhiteBalanceModeSchema.optional(),
+	warmth: number().optional(),
+	exposureMode: ExposureModeSchema.optional(),
+	backlightMode: BacklightModeSchema.optional()
+});
+DeviceType.Camera, method(object({ deviceId: number() }), ImageSettingsOptionsSchema), method(object({
+	deviceId: number(),
+	settings: ImageSettingsPatchSchema
+}), _void(), {
+	kind: "mutation",
+	auth: "admin"
+});
+/**
 * Robotic lawn-mower cap. Models HA `lawn_mower.*` entities — anything
 * with a mowing lifecycle plus a dock action.
 *
@@ -10689,6 +10900,16 @@ var RunnerCameraConfigSchema = object({
 	* this gate is bypassed.
 	*/
 	onboardMotionDrivesAnalyzer: boolean().default(true),
+	/**
+	* Master toggle for the occupancy re-check. When `false` (DEFAULT) the runner
+	* never arms the periodic recheck timer, regardless of `occupancyRecheckSec` —
+	* this is off by default because the recheck re-subscribes a detection session
+	* every N seconds while `watching`, a major source of pull-decoder re-dial
+	* churn (each cycle creates+tears a session → RTSP re-dial → latency). The
+	* `occupancyRecheckSec` / `occupancyRecheckFrames` sliders only take effect
+	* (and only render) when this is enabled.
+	*/
+	occupancyRecheckEnabled: boolean().default(false),
 	occupancyRecheckSec: number().min(occupancyRecheckSecField.min).max(occupancyRecheckSecField.max).default(occupancyRecheckSecField.default),
 	occupancyRecheckFrames: number().min(occupancyRecheckFramesField.min).max(occupancyRecheckFramesField.max).default(occupancyRecheckFramesField.default),
 	/**
@@ -12534,42 +12755,79 @@ var SessionInventoryEntrySchema = object({
 	framesIn: number(),
 	framesOut: number()
 });
-method(_void(), array(AudioCodecInfoSchema).readonly()), method(object({
-	codec: string(),
-	kind: _enum(["decode", "encode"])
-}), boolean()), method(AudioDecodeSessionConfigSchema, object({
-	sessionId: string(),
-	nodeId: string()
-}), { kind: "mutation" }), method(AudioEncodeSessionConfigSchema, object({
-	sessionId: string(),
-	nodeId: string()
-}), { kind: "mutation" }), method(object({
-	sessionId: string(),
-	nodeId: string().optional()
-}), _void(), { kind: "mutation" }), method(object({
-	sessionId: string(),
-	nodeId: string().optional(),
-	data: _instanceof(Uint8Array),
-	/** Source PTS in milliseconds. Synthesised when omitted. */
-	pts: number().optional()
-}), _void(), { kind: "mutation" }), method(object({
-	sessionId: string(),
-	nodeId: string().optional(),
-	maxCount: number().int().positive().default(8)
-}), array(AudioPcmChunkSchema)), method(object({
-	sessionId: string(),
-	nodeId: string().optional(),
-	data: _instanceof(Uint8Array),
-	/** Source PTS in milliseconds. */
-	pts: number().optional()
-}), _void(), { kind: "mutation" }), method(object({
-	sessionId: string(),
-	nodeId: string().optional(),
-	maxCount: number().int().positive().default(8)
-}), array(AudioEncodedChunkSchema)), method(object({
-	sessionId: string(),
-	nodeId: string().optional()
-}), array(AudioEncodedChunkSchema), { kind: "mutation" }), method(_void(), array(SessionInventoryEntrySchema).readonly());
+/**
+* audio-codec — bidirectional PCM ↔ encoded audio I/O box.
+*
+* Independent per-consumer sessions. The provider runs decode + resample
+* (or resample + encode) inside the session so a 16kHz mono ASA
+* subscriber and a 48kHz stereo WebRTC subscriber on the same source
+* stream don't share resamplers.
+*
+* Singleton on each node. Decoder and encoder live in the same provider
+* because they share the underlying libav contexts (node-av today,
+* pluggable later) — operators always install one or the other together.
+*/
+var audioCodecCapability = {
+	name: "audio-codec",
+	scope: "system",
+	mode: "singleton",
+	preferredProvider: "decoder-nodeav",
+	methods: {
+		/** Probe the local runtime and return the supported codec matrix. */
+		listSupportedCodecs: method(_void(), array(AudioCodecInfoSchema).readonly()),
+		/** Cheap predicate — does the runtime support `(codec, kind)`? */
+		canHandle: method(object({
+			codec: string(),
+			kind: _enum(["decode", "encode"])
+		}), boolean()),
+		createDecodeSession: method(AudioDecodeSessionConfigSchema, object({
+			sessionId: string(),
+			nodeId: string()
+		}), { kind: "mutation" }),
+		createEncodeSession: method(AudioEncodeSessionConfigSchema, object({
+			sessionId: string(),
+			nodeId: string()
+		}), { kind: "mutation" }),
+		closeSession: method(object({
+			sessionId: string(),
+			nodeId: string().optional()
+		}), _void(), { kind: "mutation" }),
+		/** Push one encoded audio frame into a decode session. */
+		pushEncodedFrame: method(object({
+			sessionId: string(),
+			nodeId: string().optional(),
+			data: _instanceof(Uint8Array),
+			/** Source PTS in milliseconds. Synthesised when omitted. */
+			pts: number().optional()
+		}), _void(), { kind: "mutation" }),
+		/** Pull up to `maxCount` PCM chunks from a decode session. */
+		pullPcm: method(object({
+			sessionId: string(),
+			nodeId: string().optional(),
+			maxCount: number().int().positive().default(8)
+		}), array(AudioPcmChunkSchema)),
+		/** Push one PCM chunk into an encode session. */
+		pushPcm: method(object({
+			sessionId: string(),
+			nodeId: string().optional(),
+			data: _instanceof(Uint8Array),
+			/** Source PTS in milliseconds. */
+			pts: number().optional()
+		}), _void(), { kind: "mutation" }),
+		/** Pull up to `maxCount` encoded chunks from an encode session. */
+		pullEncoded: method(object({
+			sessionId: string(),
+			nodeId: string().optional(),
+			maxCount: number().int().positive().default(8)
+		}), array(AudioEncodedChunkSchema)),
+		/** Flush any pending encoded output (call before close on graceful tear). */
+		flushEncode: method(object({
+			sessionId: string(),
+			nodeId: string().optional()
+		}), array(AudioEncodedChunkSchema), { kind: "mutation" }),
+		listActiveSessions: method(_void(), array(SessionInventoryEntrySchema).readonly())
+	}
+};
 var AuthResultSchema = object({
 	userId: string(),
 	username: string(),
@@ -19072,6 +19330,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"dayNight.getOptions": {
+		capName: "day-night",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"dayNight.setSettings": {
+		capName: "day-night",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"decoder.createSession": {
 		capName: "decoder",
 		capScope: "system",
@@ -20002,6 +20272,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"imageSettings.getOptions": {
+		capName: "image-settings",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"imageSettings.setSettings": {
+		capName: "image-settings",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"integrations.create": {
 		capName: "integrations",
 		capScope: "system",
@@ -23292,10 +23574,16 @@ var RING_BUDGET_BYTES = RING_BUDGET_MB * 1024 * 1024;
 * segment (resolution change) a distinct name so a stale consumer mapping is
 * never silently reused.
 */
+/**
+* Shared prefix for every decoder shm segment name. Startup orphan reclamation
+* (`purgeOrphanSegments`) keys off this to find segments left behind by a
+* crashed prior instance.
+*/
+var SEGMENT_NAME_PREFIX = "csf.";
 function makeSegmentName(seed, generation) {
 	let hash = 5381;
 	for (let i = 0; i < seed.length; i += 1) hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
-	return `csf.${(hash >>> 0).toString(36)}.${generation}`;
+	return `${SEGMENT_NAME_PREFIX}${(hash >>> 0).toString(36)}.${generation}`;
 }
 /**
 * The decoder-side owner of one stream's shared-memory frame ring.
@@ -24138,6 +24426,1225 @@ function probeGpuScaleFilters(ffmpegPath, logger) {
 	});
 }
 //#endregion
+//#region src/shm-orphan-purge.ts
+/**
+* Startup reclamation of orphaned shared-memory segments.
+*
+* A decoder writes frames into named `/dev/shm` segments and unlinks each one
+* on graceful session teardown (`DecoderFrameRingSink.destroy`). When the
+* decoder process dies *ungracefully* — SIGBUS, OOM-kill, or a SIGKILL during
+* redeploy — that teardown never runs and the segment is orphaned: it stays in
+* the tmpfs forever, since nothing else knows its name. Across many
+* crashes/redeploys these accumulate until `/dev/shm` fills, at which point the
+* next `mmap` write faults with an uncatchable SIGBUS and the decoder
+* crash-loops into its circuit breaker (which is exactly the incident this
+* guards against).
+*
+* The reclamation is safe *at process startup*: a freshly-booting decoder owns
+* no live sessions, so every pre-existing segment with its prefix is by
+* definition an orphan from a dead instance. `shm_unlink` only removes the
+* name — any consumer still holding a mapping keeps reading valid memory until
+* it closes (POSIX deferred reclaim + the ring seqlock), so unlinking is safe
+* even if a stale reader is momentarily still attached.
+*
+* POSIX-only: segments surface as files under `/dev/shm` on Linux. On platforms
+* without that directory (Windows, macOS) the scan finds nothing — no-op.
+*
+* NOTE: this lives inside the decoder addon (not `@camstack/shm-ring`) so it
+* ships in the self-contained addon bundle via `camstack deploy`, reusing the
+* already-deployed `unlinkSegment`; no host base-image rebuild required.
+*/
+/** Default tmpfs directory where POSIX shared-memory segments appear on Linux. */
+var DEFAULT_SHM_DIR = "/dev/shm";
+/**
+* Unlink every shared-memory segment whose name starts with `prefix`.
+*
+* Intended to run ONCE at decoder startup, before any session is created, to
+* reclaim segments orphaned by a previously-crashed instance. A per-file unlink
+* failure is swallowed so one stuck segment cannot block reclaiming the rest.
+*/
+function purgeOrphanSegments(prefix, options = {}) {
+	const dir = options.dir ?? DEFAULT_SHM_DIR;
+	const unlink = options.unlink ?? _camstack_shm_ring.unlinkSegment;
+	let entries;
+	try {
+		entries = (0, node_fs.readdirSync)(dir);
+	} catch {
+		return {
+			scanned: 0,
+			removed: 0,
+			names: []
+		};
+	}
+	const names = [];
+	for (const name of entries) {
+		if (!name.startsWith(prefix)) continue;
+		try {
+			unlink(name);
+			names.push(name);
+		} catch {}
+	}
+	return {
+		scanned: entries.length,
+		removed: names.length,
+		names
+	};
+}
+//#endregion
+//#region src/audio-codec/ffmpeg-audio-process.ts
+/**
+* Minimal ffmpeg subprocess wrapper shared by the audio decode + encode
+* sessions of `audio-codec-ffmpeg`.
+*
+* Owns exactly the process concerns both directions need: spawn, stdin write
+* with tolerated backpressure, stdout chunk delivery, and the kill sequence.
+*
+* The kill logic copies the CORRECTED pattern from `decoder-ffmpeg`'s
+* `killFfmpeg`: SIGTERM, then SIGKILL after a grace — gated on
+* `exitCode === null && signalCode === null`, NOT on `child.killed` (which Node
+* sets true after ANY `kill()`, so `!child.killed` never fires and the SIGKILL
+* would leak the process).
+*/
+/** Grace period between SIGTERM and the escalated SIGKILL. */
+var KILL_GRACE_MS = 500;
+var FfmpegAudioProcess = class {
+	child = null;
+	logger;
+	opts;
+	killed = false;
+	constructor(opts) {
+		this.opts = opts;
+		this.logger = opts.logger;
+		this.spawn();
+	}
+	spawn() {
+		let child;
+		try {
+			child = (0, node_child_process.spawn)(this.opts.ffmpegPath, [...this.opts.args]);
+		} catch (err) {
+			this.logger.error("audio-codec-ffmpeg: spawn threw", { meta: { error: errMsg(err) } });
+			return;
+		}
+		this.child = child;
+		child.stdin?.on("error", () => {});
+		child.stdout?.on("data", (chunk) => this.opts.onStdout(chunk));
+		child.stderr?.on("data", (data) => {
+			const line = data.toString().trim();
+			if (line) this.logger.debug("audio-codec-ffmpeg stderr", { meta: { line } });
+		});
+		child.on("error", (err) => {
+			this.logger.error("audio-codec-ffmpeg: process error", { meta: { error: err.message } });
+		});
+		child.on("exit", (code, signal) => {
+			if (this.killed) return;
+			this.opts.onExit(code, signal);
+		});
+	}
+	/** Write encoded frames / PCM into ffmpeg stdin. Backpressure is tolerated. */
+	write(data) {
+		const stdin = this.child?.stdin;
+		if (!stdin) return;
+		try {
+			stdin.write(Buffer.from(data.buffer, data.byteOffset, data.byteLength));
+		} catch {}
+	}
+	/** Close stdin so ffmpeg flushes and drains its remaining output. */
+	endStdin() {
+		try {
+			this.child?.stdin?.end();
+		} catch {}
+	}
+	/** SIGTERM then escalated SIGKILL — see class doc for the gating rationale. */
+	kill() {
+		const child = this.child;
+		if (!child) return;
+		this.killed = true;
+		this.child = null;
+		try {
+			child.stdin?.end();
+		} catch {}
+		try {
+			child.kill("SIGTERM");
+		} catch {}
+		const { pid } = child;
+		setTimeout(() => {
+			if (pid !== void 0 && child.exitCode === null && child.signalCode === null) try {
+				child.kill("SIGKILL");
+			} catch {}
+		}, KILL_GRACE_MS).unref?.();
+	}
+};
+//#endregion
+//#region src/audio-codec/audio-codec-args.ts
+/**
+* Low-latency flag set shared by both the decode and encode invocations.
+*
+* - `-hide_banner -nostats -loglevel error`: quiet stderr (no periodic counter).
+* - `-fflags +nobuffer+flush_packets`: don't buffer input; flush output packets
+*   the moment they are ready (critical for the intercom encode path).
+* - `-flags low_delay`: request the lowest-latency codec behaviour.
+* - `-probesize 32 -analyzeduration 0`: skip stream probing — the input format
+*   is fully specified by `-f`/`-ar`/`-ac`, so probing only adds startup delay.
+* - `-threads 1`: single-threaded — audio frames are tiny, and extra worker
+*   threads only add scheduling jitter to a real-time path.
+*/
+var AUDIO_LOW_LATENCY_ARGS = [
+	"-hide_banner",
+	"-nostats",
+	"-loglevel",
+	"error",
+	"-fflags",
+	"+nobuffer+flush_packets",
+	"-flags",
+	"low_delay",
+	"-probesize",
+	"32",
+	"-analyzeduration",
+	"0",
+	"-threads",
+	"1"
+];
+/**
+* Normalise an SDP-reported codec name to the libav/ffmpeg name. Mirrors the
+* `resolveCodecAlias` in `audio-codec-nodeav` so callers can pass the
+* SDP-reported value verbatim.
+*/
+function resolveAudioCodecAlias(codec) {
+	const c = codec.toLowerCase();
+	if (c === "mpeg4-generic") return "aac";
+	if (c === "l16") return "pcm_s16be";
+	return c;
+}
+/**
+* codec → ffmpeg DECODE input format.
+*
+* | codec                         | -f     | raw? | note                          |
+* | ----------------------------- | ------ | ---- | ----------------------------- |
+* | pcm_mulaw                     | mulaw  | yes  | G.711 µ-law                   |
+* | pcm_alaw                      | alaw   | yes  | G.711 A-law                   |
+* | pcm_s16be (l16)               | s16be  | yes  | RTP L16                       |
+* | pcm_s16le                     | s16le  | yes  |                               |
+* | g722                          | g722   | yes  | 16 kHz wideband               |
+* | aac / aac_latm / mpeg4-generic| aac    | no   | ADTS demuxer                  |
+* | opus                          | ogg    | no   | ⚠ needs Ogg framing (see NOTE)|
+*
+* NOTE (opus decode): ffmpeg has no raw-packet Opus demuxer. `audio-codec-nodeav`
+* feeds raw RTP Opus packets straight to the `AV_CODEC_ID_OPUS` decoder with no
+* demuxer; a subprocess cannot do that from a pipe. We map to `ogg`, which is
+* correct only if the pushed bytes are Ogg-Opus. Raw RTP Opus decode via the
+* subprocess is a KNOWN limitation — see the addon report.
+*/
+var DECODE_FORMAT_BY_CODEC = {
+	pcm_mulaw: {
+		inputFormat: "mulaw",
+		rawInput: true
+	},
+	pcm_alaw: {
+		inputFormat: "alaw",
+		rawInput: true
+	},
+	pcm_s16be: {
+		inputFormat: "s16be",
+		rawInput: true
+	},
+	pcm_s16le: {
+		inputFormat: "s16le",
+		rawInput: true
+	},
+	g722: {
+		inputFormat: "g722",
+		rawInput: true
+	},
+	aac: {
+		inputFormat: "aac",
+		rawInput: false
+	},
+	aac_latm: {
+		inputFormat: "aac",
+		rawInput: false
+	},
+	opus: {
+		inputFormat: "ogg",
+		rawInput: false
+	}
+};
+/**
+* codec → ffmpeg ENCODE codec + container.
+*
+* | codec     | -c:a       | -f    | bitrate? |
+* | --------- | ---------- | ----- | -------- |
+* | pcm_mulaw | pcm_mulaw  | mulaw | no       |
+* | pcm_alaw  | pcm_alaw   | alaw  | no       |
+* | g722      | g722       | g722  | no       |
+* | aac       | aac        | adts  | yes      |
+* | opus      | libopus    | ogg   | yes      |
+*/
+var ENCODE_FORMAT_BY_CODEC = {
+	pcm_mulaw: {
+		encoder: "pcm_mulaw",
+		outputFormat: "mulaw",
+		acceptsBitrate: false
+	},
+	pcm_alaw: {
+		encoder: "pcm_alaw",
+		outputFormat: "alaw",
+		acceptsBitrate: false
+	},
+	g722: {
+		encoder: "g722",
+		outputFormat: "g722",
+		acceptsBitrate: false
+	},
+	aac: {
+		encoder: "aac",
+		outputFormat: "adts",
+		acceptsBitrate: true
+	},
+	opus: {
+		encoder: "libopus",
+		outputFormat: "ogg",
+		acceptsBitrate: true
+	}
+};
+/** Resolve the DECODE input-format descriptor for a codec, or `null` if unknown. */
+function decodeFormatForCodec(codec) {
+	return DECODE_FORMAT_BY_CODEC[resolveAudioCodecAlias(codec)] ?? null;
+}
+/** Resolve the ENCODE codec+container descriptor for a codec, or `null` if unknown. */
+function encodeFormatForCodec(codec) {
+	return ENCODE_FORMAT_BY_CODEC[resolveAudioCodecAlias(codec)] ?? null;
+}
+/** Packed bytes-per-sample for a PCM format (s16le = 2, f32le = 4). */
+function audioBytesPerSample(format) {
+	return format === "f32le" ? 4 : 2;
+}
+/**
+* Build the ffmpeg argv for a DECODE session — encoded frames on `pipe:0`, raw
+* PCM on `pipe:1`. PURE: no spawn, no env access.
+*
+*   ffmpeg <low-latency> -f <inputFmt> [-ar <src> -ac <srcCh>] -i pipe:0 \
+*          -ar <target> -ac <targetCh> -f <s16le|f32le> pipe:1
+*
+* @throws if the codec has no known decode mapping.
+*/
+function buildAudioDecodeArgs(config) {
+	const entry = decodeFormatForCodec(config.codec);
+	if (!entry) throw new Error(`audio-codec-ffmpeg: no decode format for codec '${config.codec}'`);
+	const outFormat = config.targetFormat ?? "s16le";
+	const inputRateChannel = entry.rawInput ? [
+		"-ar",
+		String(config.sourceSampleRate),
+		"-ac",
+		String(config.sourceChannels)
+	] : [];
+	return [
+		...AUDIO_LOW_LATENCY_ARGS,
+		"-f",
+		entry.inputFormat,
+		...inputRateChannel,
+		"-i",
+		"pipe:0",
+		"-ar",
+		String(config.targetSampleRate),
+		"-ac",
+		String(config.targetChannels),
+		"-f",
+		outFormat,
+		"pipe:1"
+	];
+}
+/**
+* Build the ffmpeg argv for an ENCODE session — raw PCM on `pipe:0`, encoded
+* bytes on `pipe:1`. PURE: no spawn, no env access.
+*
+*   ffmpeg <low-latency> -f <s16le|f32le> -ar <src> -ac <srcCh> -i pipe:0 \
+*          -c:a <encoder> -ar <target> -ac <targetCh> [-b:a <k>k] \
+*          [-application lowdelay] -f <containerFmt> pipe:1
+*
+* For `libopus` the intercom-oriented `-application lowdelay` mode is added,
+* trading a little quality for the lowest algorithmic latency.
+*
+* @throws if the codec has no known encode mapping.
+*/
+function buildAudioEncodeArgs(config) {
+	const entry = encodeFormatForCodec(config.codec);
+	if (!entry) throw new Error(`audio-codec-ffmpeg: no encode format for codec '${config.codec}'`);
+	const inFormat = config.sourceFormat ?? "s16le";
+	const bitrateArgs = entry.acceptsBitrate && config.bitrateKbps !== void 0 ? ["-b:a", `${config.bitrateKbps}k`] : [];
+	const opusLowDelay = entry.encoder === "libopus" ? ["-application", "lowdelay"] : [];
+	return [
+		...AUDIO_LOW_LATENCY_ARGS,
+		"-f",
+		inFormat,
+		"-ar",
+		String(config.sourceSampleRate),
+		"-ac",
+		String(config.sourceChannels),
+		"-i",
+		"pipe:0",
+		"-c:a",
+		entry.encoder,
+		"-ar",
+		String(config.targetSampleRate),
+		"-ac",
+		String(config.targetChannels),
+		...bitrateArgs,
+		...opusLowDelay,
+		"-f",
+		entry.outputFormat,
+		"pipe:1"
+	];
+}
+//#endregion
+//#region src/audio-codec/ogg-opus-framer.ts
+/**
+* Ogg-Opus encapsulator for the `audio-codec-ffmpeg` decode path.
+*
+* Cameras / RTP deliver RAW Opus packets — one self-delimited Opus packet per
+* `pushEncodedFrame`. ffmpeg has NO raw-Opus demuxer, so the subprocess cannot
+* decode a bare packet stream from a pipe (unlike `audio-codec-nodeav`, which
+* feeds raw packets straight to `AV_CODEC_ID_OPUS` in-process). To decode Opus
+* out-of-process we must wrap the raw packets in a valid **Ogg-Opus** container
+* so `ffmpeg -f ogg -i pipe:0` can demux + decode them.
+*
+* This framer turns a stream of raw Opus packets into a byte stream shaped per
+* RFC 7845 (Ogg Encapsulation for Opus) + RFC 3533 (the Ogg container):
+*
+*   Page 0 (BOS) : one "OpusHead" identification packet
+*   Page 1       : one "OpusTags" comment packet
+*   Page 2..n    : one Opus audio packet each (one-packet-per-page = lowest
+*                  latency, simplest lacing), granule = running 48 kHz sample
+*                  total.
+*   flush()      : optional final EOS page.
+*
+* The Ogg page CRC is NOT the common zlib CRC-32: it uses polynomial
+* 0x04C11DB7 with init 0, NO input/output bit reflection, and NO final XOR,
+* computed over the whole page with the CRC field zeroed (see `oggCrc32`).
+*/
+/** Ogg capture pattern, "OggS". */
+var OGG_CAPTURE_PATTERN = Buffer.from("OggS", "ascii");
+/** Opus identification header magic, "OpusHead". */
+var OPUS_HEAD_MAGIC = Buffer.from("OpusHead", "ascii");
+/** Opus comment header magic, "OpusTags". */
+var OPUS_TAGS_MAGIC = Buffer.from("OpusTags", "ascii");
+/** Ogg page header byte offsets (before the segment table). */
+var OGG_HEADER_FIXED_BYTES = 27;
+/** Byte offset of the 4-byte CRC field within the fixed header. */
+var OGG_CRC_OFFSET = 22;
+var HEADER_TYPE_BOS = 2;
+var HEADER_TYPE_EOS = 4;
+/** OpusHead `input sample rate` — informational per RFC 7845 (§5.1). */
+var OPUS_INPUT_SAMPLE_RATE = 48e3;
+/** Opus granule positions are ALWAYS counted at 48 kHz (RFC 7845 §4). */
+var OPUS_GRANULE_SAMPLE_RATE = 48e3;
+/**
+* Opus frame size, in 48 kHz samples, indexed by the 5-bit TOC `config`
+* (0..31). Derived from the frame-duration table in RFC 6716 §3.1:
+*
+*   config 0-11  SILK  NB/MB/WB  →  10 / 20 / 40 / 60 ms
+*   config 12-15 Hybrid SWB/FB   →  10 / 20 ms
+*   config 16-31 CELT  NB/…/FB   →  2.5 / 5 / 10 / 20 ms
+*
+* samples@48k = ms * 48  (2.5→120, 5→240, 10→480, 20→960, 40→1920, 60→2880).
+*/
+var OPUS_FRAME_SAMPLES_48K = [
+	480,
+	960,
+	1920,
+	2880,
+	480,
+	960,
+	1920,
+	2880,
+	480,
+	960,
+	1920,
+	2880,
+	480,
+	960,
+	480,
+	960,
+	120,
+	240,
+	480,
+	960,
+	120,
+	240,
+	480,
+	960,
+	120,
+	240,
+	480,
+	960,
+	120,
+	240,
+	480,
+	960
+];
+/**
+* Precomputed Ogg CRC-32 lookup table (MSB-first, polynomial 0x04C11DB7).
+*
+* Each entry is the CRC of the single byte `i` placed in the top position of a
+* 32-bit register, shifted out MSB-first with no reflection. This is the table
+* form of the bit-serial algorithm used by `oggCrc32`.
+*/
+var OGG_CRC_TABLE = (() => {
+	const table = new Uint32Array(256);
+	for (let i = 0; i < 256; i++) {
+		let r = i << 24 >>> 0;
+		for (let bit = 0; bit < 8; bit++) r = (r & 2147483648) !== 0 ? (r << 1 ^ 79764919) >>> 0 : r << 1 >>> 0;
+		table[i] = r >>> 0;
+	}
+	return table;
+})();
+/**
+* Ogg page CRC-32 (RFC 3533 §4). Polynomial 0x04C11DB7, init 0, NO input or
+* output reflection, NO final XOR — deliberately different from the reflected
+* zlib/IEEE CRC-32. Computed over the ENTIRE page bytes with the 4-byte CRC
+* field already zeroed.
+*/
+function oggCrc32(data) {
+	let crc = 0;
+	for (let i = 0; i < data.length; i++) {
+		const idx = (crc >>> 24 ^ (data[i] ?? 0)) & 255;
+		crc = (crc << 8 >>> 0 ^ (OGG_CRC_TABLE[idx] ?? 0)) >>> 0;
+	}
+	return crc >>> 0;
+}
+/**
+* Decode an Opus packet's total duration in samples from its TOC byte
+* (RFC 6716 §3). Returns samples at `sampleRate` (default 48 kHz — the rate Ogg
+* granule positions are counted in).
+*
+* TOC byte layout: `config` (bits 3-7), `s` stereo (bit 2), `c` frame-count
+* code (bits 0-1):
+*   - code 0 → 1 frame
+*   - code 1 / 2 → 2 frames
+*   - code 3 → arbitrary; frame count = low 6 bits of the byte after the TOC.
+*
+* Returns 0 for an empty or malformed (code-3 with no count byte) packet.
+*/
+function opusPacketSampleCount(packet, sampleRate = 48e3) {
+	if (packet.length < 1) return 0;
+	const toc = packet[0] ?? 0;
+	const config = toc >> 3;
+	const code = toc & 3;
+	const samplesPerFrame48k = OPUS_FRAME_SAMPLES_48K[config] ?? 0;
+	if (samplesPerFrame48k === 0) return 0;
+	let frameCount;
+	if (code === 0) frameCount = 1;
+	else if (code === 1 || code === 2) frameCount = 2;
+	else {
+		if (packet.length < 2) return 0;
+		frameCount = (packet[1] ?? 0) & 63;
+	}
+	const samples48k = samplesPerFrame48k * frameCount;
+	if (sampleRate === OPUS_GRANULE_SAMPLE_RATE) return samples48k;
+	return Math.round(samples48k * sampleRate / OPUS_GRANULE_SAMPLE_RATE);
+}
+/**
+* Encode an Ogg lacing segment table for a single packet of length `len`
+* (RFC 3533 §6): `floor(len/255)` bytes of 0xFF then one final byte `len%255`.
+* A length that is an exact multiple of 255 therefore ends in a `0x00` lacing
+* value — required so the demuxer knows the packet terminates on this page.
+*/
+function buildLacing(len) {
+	const full = Math.floor(len / 255);
+	const table = Buffer.alloc(full + 1);
+	table.fill(255, 0, full);
+	table[full] = len % 255;
+	return table;
+}
+/**
+* Turn a hash-derivable seed into a stable 32-bit Ogg bitstream serial. FNV-1a
+* over the seed string keeps distinct sessions on distinct serials without
+* requiring the caller to allocate one.
+*/
+function serialFromSeed(seed) {
+	let hash = 2166136261;
+	for (let i = 0; i < seed.length; i++) {
+		hash ^= seed.charCodeAt(i) & 255;
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+}
+/**
+* Streaming Ogg-Opus encapsulator. Stateful: tracks page sequence numbers and
+* the running 48 kHz granule position across calls. One instance per decode
+* session; call {@link reset} to reuse it for a fresh stream.
+*/
+var OggOpusFramer = class {
+	channelCount;
+	serial;
+	preSkip;
+	vendor;
+	pageSeq = 0;
+	granule = 0;
+	headersEmitted = false;
+	audioEmitted = false;
+	constructor(config) {
+		this.channelCount = config.channelCount;
+		this.serial = config.serial >>> 0;
+		this.preSkip = config.preSkip ?? 3840;
+		this.vendor = config.vendor ?? "camstack";
+	}
+	/**
+	* Build the two header pages (OpusHead BOS + OpusTags). Advances the page
+	* sequence to 2 so audio pages follow. Returns an empty buffer if the headers
+	* were already emitted (idempotent within a stream).
+	*/
+	headerPages() {
+		if (this.headersEmitted) return Buffer.alloc(0);
+		this.headersEmitted = true;
+		const head = this.buildOpusHead();
+		const tags = this.buildOpusTags();
+		const headPage = this.buildPage(head, HEADER_TYPE_BOS, 0);
+		const tagsPage = this.buildPage(tags, 0, 0);
+		return Buffer.concat([headPage, tagsPage]);
+	}
+	/**
+	* Encapsulate one raw Opus packet as a single audio page, advancing the
+	* granule by the packet's decoded sample count. Header pages are emitted
+	* (and prepended) automatically on the first call, so the caller can simply
+	* write the returned bytes to ffmpeg stdin.
+	*/
+	framePacket(packet) {
+		const prefix = this.headersEmitted ? Buffer.alloc(0) : this.headerPages();
+		this.granule += opusPacketSampleCount(packet, OPUS_GRANULE_SAMPLE_RATE);
+		this.audioEmitted = true;
+		const page = this.buildPage(packet, 0, this.granule);
+		return prefix.length > 0 ? Buffer.concat([prefix, page]) : page;
+	}
+	/**
+	* Emit a final EOS page terminating the logical bitstream. Returns `null`
+	* when no audio was written (nothing to terminate). The EOS page carries no
+	* packet data (0 segments) and the final granule position.
+	*/
+	flush() {
+		if (!this.audioEmitted) return null;
+		return this.buildPage(null, HEADER_TYPE_EOS, this.granule);
+	}
+	/** Reset all page/granule state so the instance can frame a fresh stream. */
+	reset() {
+		this.pageSeq = 0;
+		this.granule = 0;
+		this.headersEmitted = false;
+		this.audioEmitted = false;
+	}
+	/** OpusHead identification packet (RFC 7845 §5.1) — 19 bytes for family 0. */
+	buildOpusHead() {
+		const buf = Buffer.alloc(19);
+		OPUS_HEAD_MAGIC.copy(buf, 0);
+		buf.writeUInt8(1, 8);
+		buf.writeUInt8(this.channelCount, 9);
+		buf.writeUInt16LE(this.preSkip & 65535, 10);
+		buf.writeUInt32LE(OPUS_INPUT_SAMPLE_RATE, 12);
+		buf.writeInt16LE(0, 16);
+		buf.writeUInt8(0, 18);
+		return buf;
+	}
+	/** OpusTags comment packet (RFC 7845 §5.2) — magic, vendor, 0 comments. */
+	buildOpusTags() {
+		const vendor = Buffer.from(this.vendor, "utf8");
+		const buf = Buffer.alloc(12 + vendor.length + 4);
+		OPUS_TAGS_MAGIC.copy(buf, 0);
+		buf.writeUInt32LE(vendor.length, 8);
+		vendor.copy(buf, 12);
+		buf.writeUInt32LE(0, 12 + vendor.length);
+		return buf;
+	}
+	/**
+	* Assemble one Ogg page around a single packet (or none, for an EOS
+	* terminator), compute its CRC, and return the framed bytes. Keeps to a
+	* single packet per page so the segment count never approaches the 255 limit
+	* (an Opus packet is ≤ ~1275 bytes → ≤ 6 lacing segments).
+	*/
+	buildPage(packet, headerType, granule) {
+		const lacing = packet !== null ? buildLacing(packet.length) : Buffer.alloc(0);
+		const segmentCount = lacing.length;
+		const bodyLen = packet !== null ? packet.length : 0;
+		const page = Buffer.alloc(OGG_HEADER_FIXED_BYTES + segmentCount + bodyLen);
+		OGG_CAPTURE_PATTERN.copy(page, 0);
+		page.writeUInt8(0, 4);
+		page.writeUInt8(headerType & 7, 5);
+		this.writeGranule(page, granule, 6);
+		page.writeUInt32LE(this.serial, 14);
+		page.writeUInt32LE(this.pageSeq >>> 0, 18);
+		page.writeUInt32LE(0, OGG_CRC_OFFSET);
+		page.writeUInt8(segmentCount, 26);
+		lacing.copy(page, OGG_HEADER_FIXED_BYTES);
+		if (packet !== null) packet.copy(page, OGG_HEADER_FIXED_BYTES + segmentCount);
+		const crc = oggCrc32(page);
+		page.writeUInt32LE(crc, OGG_CRC_OFFSET);
+		this.pageSeq = this.pageSeq + 1 >>> 0;
+		return page;
+	}
+	/**
+	* Write a 64-bit little-endian granule position. Values fit comfortably in a
+	* JS safe integer for any realistic stream duration (2^53 samples @48k ≈ 5940
+	* years), so a split 32-bit lo/hi write is exact and avoids BigInt on the
+	* hot path.
+	*/
+	writeGranule(page, granule, offset) {
+		const lo = granule >>> 0;
+		const hi = Math.floor(granule / 4294967296) >>> 0;
+		page.writeUInt32LE(lo, offset);
+		page.writeUInt32LE(hi, offset + 4);
+	}
+};
+//#endregion
+//#region src/audio-codec/adts.ts
+/**
+* ADTS framing for raw AAC access units.
+*
+* The audio decode path runs `ffmpeg -f aac -i pipe:0` — the **ADTS** demuxer,
+* which requires each frame to begin with a 7-byte ADTS header (0xFFF sync).
+* But every AAC source that reaches the decoder delivers **raw** AAC access
+* units with no ADTS header: push sources (Reolink Baichuan) emit one bare
+* codec frame per packet, and rfc3640 (RTP AAC) depacketization yields bare
+* AUs too. Piping those straight into `-f aac` fails with
+* `Invalid data found when processing input` → no PCM → a silent WebRTC audio
+* track. Wrapping each raw AU in an ADTS header (built from the source
+* sample-rate / channel-count / AAC object type) makes the demuxer accept it.
+*
+* Opus is handled separately (Ogg encapsulation); this module is AAC-only.
+*/
+/** MPEG-4 AAC sampling-frequency index table (ISO/IEC 14496-3). */
+var AAC_SAMPLE_RATES = [
+	96e3,
+	88200,
+	64e3,
+	48e3,
+	44100,
+	32e3,
+	24e3,
+	22050,
+	16e3,
+	12e3,
+	11025,
+	8e3,
+	7350
+];
+/** AAC-LC is object type 2; the ADTS `profile` field is objectType - 1. */
+var DEFAULT_AAC_OBJECT_TYPE = 2;
+/** Resolve the ADTS sampling-frequency index for a sample rate (default 16 kHz → 8). */
+function aacSampleRateIndex(sampleRate) {
+	const idx = AAC_SAMPLE_RATES.indexOf(sampleRate);
+	return idx >= 0 ? idx : AAC_SAMPLE_RATES.indexOf(16e3);
+}
+/**
+* True when `buf` already begins with an ADTS syncword (0xFFF) + MPEG layer 0.
+* Raw AAC AUs never do; ADTS-framed frames always do. Lets the wrapper pass
+* already-framed input through untouched.
+*/
+function hasAdtsSync(buf) {
+	return buf.length >= 2 && buf[0] === 255 && (buf[1] & 246) === 240;
+}
+/**
+* Build the 7-byte ADTS header (no CRC) for a payload of `payloadLength` bytes.
+*/
+function buildAdtsHeader(config, payloadLength) {
+	const objectType = config.aacObjectType ?? DEFAULT_AAC_OBJECT_TYPE;
+	const profile = Math.max(0, objectType - 1) & 3;
+	const freqIdx = aacSampleRateIndex(config.sampleRate) & 15;
+	const chanCfg = Math.max(1, config.channels) & 7;
+	const frameLength = payloadLength + 7;
+	const h = Buffer.alloc(7);
+	h[0] = 255;
+	h[1] = 241;
+	h[2] = profile << 6 | freqIdx << 2 | chanCfg >> 2 & 1;
+	h[3] = (chanCfg & 3) << 6 | frameLength >> 11 & 3;
+	h[4] = frameLength >> 3 & 255;
+	h[5] = (frameLength & 7) << 5 | 31;
+	h[6] = 252;
+	return h;
+}
+/**
+* Return `frame` framed as ADTS: unchanged when it already carries an ADTS
+* sync, otherwise the 7-byte header prepended. Pure; the input is never mutated.
+*/
+function wrapAacAsAdts(frame, config) {
+	if (hasAdtsSync(frame)) return Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength);
+	const payload = Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength);
+	return Buffer.concat([buildAdtsHeader(config, payload.length), payload]);
+}
+//#endregion
+//#region src/audio-codec/ffmpeg-audio-decode-session.ts
+var FfmpegAudioDecodeSession = class {
+	logger;
+	process;
+	outFormat;
+	bytesPerFrame;
+	targetSampleRate;
+	targetChannels;
+	onChunk;
+	/**
+	* Ogg-Opus encapsulator, present ONLY when the codec is Opus. Raw Opus
+	* packets have no ffmpeg demuxer, so each pushed packet is wrapped in an
+	* Ogg page (with OpusHead/OpusTags emitted before the first) so
+	* `ffmpeg -f ogg -i pipe:0` can demux + decode. `null` for all other codecs,
+	* which pipe their encoded frames straight through.
+	*/
+	oggFramer;
+	/**
+	* ADTS framing config, present ONLY when the codec is AAC. `ffmpeg -f aac`
+	* is the ADTS demuxer, but every AAC source delivers raw AAC access units
+	* (push sources emit bare frames; rfc3640 depacketization yields bare AUs) —
+	* piping those in raw fails `Invalid data found when processing input` → no
+	* PCM → silent WebRTC audio. Each frame is ADTS-wrapped before ffmpeg.
+	*/
+	adtsConfig;
+	residual = Buffer.alloc(0);
+	nextPts = 0;
+	destroyed = false;
+	constructor(params, logger, onChunk) {
+		this.logger = logger;
+		this.onChunk = onChunk;
+		this.outFormat = params.targetFormat ?? "s16le";
+		this.targetSampleRate = params.targetSampleRate;
+		this.targetChannels = params.targetChannels;
+		this.bytesPerFrame = Math.max(1, params.targetChannels * audioBytesPerSample(this.outFormat));
+		this.oggFramer = resolveAudioCodecAlias(params.codec) === "opus" ? new OggOpusFramer({
+			channelCount: Math.max(1, params.sourceChannels),
+			serial: serialFromSeed(params.oggSerialSeed ?? "audio-codec-ffmpeg-opus")
+		}) : null;
+		this.adtsConfig = resolveAudioCodecAlias(params.codec) === "aac" ? {
+			sampleRate: params.sourceSampleRate,
+			channels: Math.max(1, params.sourceChannels)
+		} : null;
+		const args = buildAudioDecodeArgs(params);
+		this.process = new FfmpegAudioProcess({
+			ffmpegPath: params.ffmpegPath,
+			args,
+			logger,
+			onStdout: (chunk) => this.handleStdout(chunk),
+			onExit: (code, signal) => {
+				if (this.destroyed) return;
+				this.logger.warn("audio-codec-ffmpeg: decode child exited", { meta: {
+					code,
+					signal
+				} });
+			}
+		});
+	}
+	/** Push one encoded audio frame into ffmpeg stdin. */
+	pushEncoded(data) {
+		if (this.destroyed) return;
+		if (this.oggFramer) {
+			const packet = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+			this.process.write(this.oggFramer.framePacket(packet));
+			return;
+		}
+		if (this.adtsConfig) {
+			this.process.write(wrapAacAsAdts(data, this.adtsConfig));
+			return;
+		}
+		this.process.write(data);
+	}
+	handleStdout(chunk) {
+		if (this.destroyed) return;
+		const buf = this.residual.length === 0 ? chunk : Buffer.concat([this.residual, chunk]);
+		const frameBytes = this.bytesPerFrame;
+		const usable = buf.length - buf.length % frameBytes;
+		if (usable <= 0) {
+			this.residual = buf;
+			return;
+		}
+		const emit = buf.subarray(0, usable);
+		this.residual = usable < buf.length ? Buffer.from(buf.subarray(usable)) : Buffer.alloc(0);
+		const out = new Uint8Array(new ArrayBuffer(usable));
+		out.set(emit);
+		const samples = usable / frameBytes;
+		const pts = this.nextPts;
+		this.nextPts = pts + Math.round(samples * 1e3 / this.targetSampleRate);
+		this.onChunk({
+			data: out,
+			sampleRate: this.targetSampleRate,
+			channels: this.targetChannels,
+			format: this.outFormat,
+			pts
+		});
+	}
+	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		if (this.oggFramer) {
+			const eos = this.oggFramer.flush();
+			if (eos) this.process.write(eos);
+		}
+		this.process.kill();
+		this.residual = Buffer.alloc(0);
+	}
+};
+//#endregion
+//#region src/audio-codec/ffmpeg-audio-encode-session.ts
+var FfmpegAudioEncodeSession = class {
+	logger;
+	process;
+	codec;
+	onChunk;
+	nextPts = 0;
+	destroyed = false;
+	constructor(params, logger, onChunk) {
+		this.logger = logger;
+		this.onChunk = onChunk;
+		this.codec = resolveAudioCodecAlias(params.codec);
+		const args = buildAudioEncodeArgs(params);
+		this.process = new FfmpegAudioProcess({
+			ffmpegPath: params.ffmpegPath,
+			args,
+			logger,
+			onStdout: (chunk) => this.handleStdout(chunk),
+			onExit: (code, signal) => {
+				if (this.destroyed) return;
+				this.logger.warn("audio-codec-ffmpeg: encode child exited", { meta: {
+					code,
+					signal
+				} });
+			}
+		});
+	}
+	/** Push one PCM chunk into ffmpeg stdin. */
+	pushPcm(data) {
+		if (this.destroyed) return;
+		this.process.write(data);
+	}
+	/** Close stdin so ffmpeg flushes and drains the remaining encoded output. */
+	flush() {
+		if (this.destroyed) return;
+		this.process.endStdin();
+	}
+	handleStdout(chunk) {
+		if (this.destroyed || chunk.length === 0) return;
+		const out = new Uint8Array(new ArrayBuffer(chunk.length));
+		out.set(chunk);
+		const pts = this.nextPts;
+		this.nextPts = pts + 1;
+		this.onChunk({
+			data: out,
+			codec: this.codec,
+			pts,
+			frameComplete: true
+		});
+	}
+	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.process.kill();
+	}
+};
+//#endregion
+//#region src/audio-codec/provider.ts
+var CODEC_CATALOG = [
+	{
+		codec: "pcm_mulaw",
+		canDecode: true,
+		canEncode: true,
+		label: "PCM µ-law (G.711)"
+	},
+	{
+		codec: "pcm_alaw",
+		canDecode: true,
+		canEncode: true,
+		label: "PCM A-law (G.711)"
+	},
+	{
+		codec: "g722",
+		canDecode: true,
+		canEncode: true,
+		label: "G.722"
+	},
+	{
+		codec: "aac",
+		canDecode: true,
+		canEncode: true,
+		label: "AAC"
+	},
+	{
+		codec: "aac_latm",
+		canDecode: true,
+		canEncode: false,
+		label: "AAC LATM"
+	},
+	{
+		codec: "mpeg4-generic",
+		canDecode: true,
+		canEncode: false,
+		label: "AAC (MPEG4-GENERIC)"
+	},
+	{
+		codec: "opus",
+		canDecode: true,
+		canEncode: true,
+		label: "Opus"
+	}
+];
+var DEFAULT_IDLE_MS = 3e4;
+var MAX_PCM_QUEUE_CHUNKS = 500;
+var REAPER_INTERVAL_MS = 5e3;
+/**
+* Grace wait in `flushEncode` for ffmpeg to drain its encoder after stdin is
+* closed. This is a graceful-teardown path (not the real-time push path), so a
+* short wait is acceptable to capture the encoder's tail output.
+*/
+var FLUSH_DRAIN_MS = 60;
+/**
+* Audio codec I/O box backed by an **ffmpeg subprocess** (Phase B replacement
+* for `audio-codec-nodeav`, which runs libavcodec + libswresample in-process).
+*
+* Each `createDecodeSession` / `createEncodeSession` spawns its own ffmpeg
+* child, so consumers never share a resampler and a codec crash is isolated to
+* the child — the addon runner survives. Cap surface + session bookkeeping
+* mirror the node-av addon exactly; only the codec backend changed.
+*
+* This is a PLAIN provider class merged into the `decoder-ffmpeg` addon (which
+* provides both the `decoder` video cap and this `audio-codec` cap). The parent
+* addon owns lifecycle: it resolves the ffmpeg path once, calls {@link start} in
+* `onInitialize`, and {@link stop} in `onShutdown`.
+*/
+var FfmpegAudioCodecProvider = class {
+	deps;
+	sessions = /* @__PURE__ */ new Map();
+	reaperTimer = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Start the idle-session reaper. Called by the parent addon at init. */
+	start() {
+		this.reaperTimer = setInterval(() => this.reapIdleSessions(), REAPER_INTERVAL_MS);
+		if (typeof this.reaperTimer.unref === "function") this.reaperTimer.unref();
+	}
+	/** Clear the reaper and dispose every session. Called by the parent at shutdown. */
+	stop() {
+		if (this.reaperTimer) {
+			clearInterval(this.reaperTimer);
+			this.reaperTimer = null;
+		}
+		for (const s of this.sessions.values()) this.disposeSession(s);
+		this.sessions.clear();
+	}
+	async listSupportedCodecs() {
+		return CODEC_CATALOG.map((e) => ({
+			codec: e.codec,
+			canDecode: e.canDecode,
+			canEncode: e.canEncode,
+			...e.label ? { label: e.label } : {}
+		}));
+	}
+	async canHandle(input) {
+		const resolved = resolveAudioCodecAlias(input.codec);
+		const entry = CODEC_CATALOG.find((e) => resolveAudioCodecAlias(e.codec) === resolved);
+		if (!entry) return false;
+		return input.kind === "decode" ? entry.canDecode : entry.canEncode;
+	}
+	async createDecodeSession(input) {
+		const codec = resolveAudioCodecAlias(input.codec);
+		const entry = CODEC_CATALOG.find((e) => resolveAudioCodecAlias(e.codec) === codec);
+		if (!entry || !entry.canDecode) throw new Error(`audio-codec-ffmpeg: decode unsupported for codec '${input.codec}'`);
+		const sessionId = `dec-${(0, node_crypto.randomUUID)()}`;
+		const state = {
+			sessionId,
+			kind: "decode",
+			config: {
+				...input,
+				codec
+			},
+			...input.tag ? { tag: input.tag } : {},
+			createdAtMs: Date.now(),
+			lastActivityMs: Date.now(),
+			framesIn: 0,
+			framesOut: 0,
+			pcmQueue: [],
+			session: null
+		};
+		state.session = this.spawnDecodeSession(state);
+		this.sessions.set(sessionId, state);
+		this.deps.logger.info("audio-codec-ffmpeg: decode session created", {
+			tags: { sessionId },
+			meta: {
+				codec,
+				target: `${input.targetSampleRate}Hz×${input.targetChannels}`
+			}
+		});
+		return {
+			sessionId,
+			nodeId: this.deps.resolveLocalNodeId()
+		};
+	}
+	async createEncodeSession(input) {
+		const codec = resolveAudioCodecAlias(input.codec);
+		const entry = CODEC_CATALOG.find((e) => resolveAudioCodecAlias(e.codec) === codec);
+		if (!entry || !entry.canEncode) throw new Error(`audio-codec-ffmpeg: encode unsupported for codec '${input.codec}'`);
+		const sessionId = `enc-${(0, node_crypto.randomUUID)()}`;
+		const state = {
+			sessionId,
+			kind: "encode",
+			config: {
+				...input,
+				codec
+			},
+			...input.tag ? { tag: input.tag } : {},
+			createdAtMs: Date.now(),
+			lastActivityMs: Date.now(),
+			framesIn: 0,
+			framesOut: 0,
+			encodedQueue: [],
+			session: null
+		};
+		state.session = this.spawnEncodeSession(state);
+		this.sessions.set(sessionId, state);
+		this.deps.logger.info("audio-codec-ffmpeg: encode session created", {
+			tags: { sessionId },
+			meta: {
+				codec,
+				target: `${input.targetSampleRate}Hz×${input.targetChannels}`
+			}
+		});
+		return {
+			sessionId,
+			nodeId: this.deps.resolveLocalNodeId()
+		};
+	}
+	async closeSession(input) {
+		const s = this.sessions.get(input.sessionId);
+		if (!s) return;
+		this.disposeSession(s);
+		this.sessions.delete(input.sessionId);
+	}
+	async pushEncodedFrame(input) {
+		const s = this.sessions.get(input.sessionId);
+		if (!s || s.kind !== "decode") throw new Error(`audio-codec-ffmpeg: decode session '${input.sessionId}' not found`);
+		s.lastActivityMs = Date.now();
+		s.framesIn++;
+		if (!s.session) s.session = this.spawnDecodeSession(s);
+		s.session.pushEncoded(input.data);
+	}
+	async pullPcm(input) {
+		const s = this.sessions.get(input.sessionId);
+		if (!s || s.kind !== "decode") throw new Error(`audio-codec-ffmpeg: decode session '${input.sessionId}' not found`);
+		s.lastActivityMs = Date.now();
+		const out = s.pcmQueue.splice(0, input.maxCount);
+		s.framesOut += out.length;
+		return out;
+	}
+	async pushPcm(input) {
+		const s = this.sessions.get(input.sessionId);
+		if (!s || s.kind !== "encode") throw new Error(`audio-codec-ffmpeg: encode session '${input.sessionId}' not found`);
+		s.lastActivityMs = Date.now();
+		s.framesIn++;
+		if (!s.session) s.session = this.spawnEncodeSession(s);
+		s.session.pushPcm(input.data);
+	}
+	async pullEncoded(input) {
+		const s = this.sessions.get(input.sessionId);
+		if (!s || s.kind !== "encode") throw new Error(`audio-codec-ffmpeg: encode session '${input.sessionId}' not found`);
+		s.lastActivityMs = Date.now();
+		const out = s.encodedQueue.splice(0, input.maxCount);
+		s.framesOut += out.length;
+		return out;
+	}
+	async flushEncode(input) {
+		const s = this.sessions.get(input.sessionId);
+		if (!s || s.kind !== "encode") throw new Error(`audio-codec-ffmpeg: encode session '${input.sessionId}' not found`);
+		s.lastActivityMs = Date.now();
+		s.session?.flush();
+		await new Promise((resolve) => setTimeout(resolve, FLUSH_DRAIN_MS));
+		const out = s.encodedQueue.splice(0);
+		s.framesOut += out.length;
+		return out;
+	}
+	async listActiveSessions() {
+		return [...this.sessions.values()].map((s) => ({
+			sessionId: s.sessionId,
+			kind: s.kind,
+			codec: s.config.codec,
+			sourceSampleRate: s.config.sourceSampleRate,
+			sourceChannels: s.config.sourceChannels,
+			targetSampleRate: s.config.targetSampleRate,
+			targetChannels: s.config.targetChannels,
+			format: this.resolveFormat(s),
+			...s.tag ? { tag: s.tag } : {},
+			createdAtMs: s.createdAtMs,
+			lastActivityMs: s.lastActivityMs,
+			framesIn: s.framesIn,
+			framesOut: s.framesOut
+		}));
+	}
+	spawnDecodeSession(s) {
+		return new FfmpegAudioDecodeSession({
+			codec: s.config.codec,
+			sourceSampleRate: s.config.sourceSampleRate,
+			sourceChannels: s.config.sourceChannels,
+			targetSampleRate: s.config.targetSampleRate,
+			targetChannels: s.config.targetChannels,
+			targetFormat: this.pcmFormat(s.config.targetFormat),
+			ffmpegPath: this.deps.ffmpegPath,
+			oggSerialSeed: s.sessionId
+		}, this.deps.logger, (chunk) => {
+			s.pcmQueue.push(chunk);
+			if (s.pcmQueue.length > MAX_PCM_QUEUE_CHUNKS) s.pcmQueue.splice(0, s.pcmQueue.length - MAX_PCM_QUEUE_CHUNKS);
+		});
+	}
+	spawnEncodeSession(s) {
+		return new FfmpegAudioEncodeSession({
+			codec: s.config.codec,
+			sourceSampleRate: s.config.sourceSampleRate,
+			sourceChannels: s.config.sourceChannels,
+			sourceFormat: this.pcmFormat(s.config.sourceFormat),
+			targetSampleRate: s.config.targetSampleRate,
+			targetChannels: s.config.targetChannels,
+			...s.config.bitrateKbps !== void 0 ? { bitrateKbps: s.config.bitrateKbps } : {},
+			ffmpegPath: this.deps.ffmpegPath
+		}, this.deps.logger, (chunk) => {
+			s.encodedQueue.push(chunk);
+		});
+	}
+	/** Narrow the cap's PCM format enum to the two ffmpeg sessions produce/read. */
+	pcmFormat(format) {
+		return format === "f32le" ? "f32le" : "s16le";
+	}
+	resolveFormat(s) {
+		if (s.kind === "decode") return this.pcmFormat(s.config.targetFormat);
+		return this.pcmFormat(s.config.sourceFormat);
+	}
+	reapIdleSessions() {
+		const now = Date.now();
+		for (const [id, s] of this.sessions) {
+			const limit = s.config.idleMs ?? this.deps.defaultIdleMs ?? DEFAULT_IDLE_MS;
+			if (now - s.lastActivityMs > limit) {
+				this.deps.logger.info("audio-codec-ffmpeg: reaping idle session", {
+					tags: { sessionId: id },
+					meta: {
+						kind: s.kind,
+						idleMs: now - s.lastActivityMs,
+						limit
+					}
+				});
+				try {
+					this.disposeSession(s);
+				} catch (err) {
+					this.deps.logger.warn("audio-codec-ffmpeg: dispose failed during reap", {
+						tags: { sessionId: id },
+						meta: { error: errMsg(err) }
+					});
+				}
+				this.sessions.delete(id);
+			}
+		}
+	}
+	disposeSession(s) {
+		try {
+			s.session?.destroy();
+		} catch (err) {
+			this.deps.logger.warn("audio-codec-ffmpeg: session destroy failed", {
+				tags: { sessionId: s.sessionId },
+				meta: { error: errMsg(err) }
+			});
+		}
+		s.session = null;
+	}
+};
+//#endregion
 //#region src/addon/index.ts
 var FRAME_BUFFER_CAPACITY = 32;
 /**
@@ -24177,6 +25684,14 @@ var DecoderFfmpegAddon = class extends BaseAddon {
 	* process — e.g. a videotoolbox build whose decode returns software frames.
 	*/
 	unsupportedGpuScaleFilters = /* @__PURE__ */ new Set();
+	/**
+	* The merged-in ffmpeg AUDIO codec provider — registers the `audio-codec` cap
+	* ALWAYS (independent of the per-node video decoder backend), so this addon
+	* serves both video decode and bidirectional audio transcode. Owns its own
+	* ffmpeg subprocess sessions + idle reaper; started at init, stopped at
+	* shutdown. Shares the single node-level ffmpeg binary this addon resolves.
+	*/
+	audioProvider = null;
 	constructor() {
 		super(DEFAULT_DECODER_FFMPEG_ADDON_CONFIG);
 	}
@@ -24214,23 +25729,40 @@ var DecoderFfmpegAddon = class extends BaseAddon {
 		if (!this.config.probedBestHwaccel) this.reprobeHwaccel().catch((err) => {
 			this.ctx.logger.warn("ffmpeg: auto-reprobe hwaccel failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
 		});
+		const registrations = [];
+		this.ffmpegPath = await this.resolveFfmpegBinaryPath();
+		this.audioProvider = new FfmpegAudioCodecProvider({
+			logger: this.ctx.logger,
+			ffmpegPath: this.ffmpegPath,
+			resolveLocalNodeId: () => this.resolveLocalNodeId()
+		});
+		this.audioProvider.start();
+		registrations.push({
+			capability: audioCodecCapability,
+			provider: this.audioProvider
+		});
 		const backend = await resolveDecoderBackend(this.ctx.api, this.resolveLocalNodeId(), this.ctx.logger);
 		if (backend !== "ffmpeg") {
-			this.ctx.logger.info("ffmpeg decoder: this node selects a different decoder backend — standing down (no decoder provider registered)", { meta: { selectedBackend: backend } });
-			return [];
+			this.ctx.logger.info("ffmpeg decoder: this node selects a different decoder backend — standing down (no decoder provider registered; audio-codec stays)", { meta: { selectedBackend: backend } });
+			return registrations;
 		}
 		this.ctx.logger.info("ffmpeg decoder addon initialized", { meta: { selectedBackend: backend } });
+		const purged = purgeOrphanSegments(SEGMENT_NAME_PREFIX);
+		if (purged.removed > 0) this.ctx.logger.warn("ffmpeg decoder: reclaimed orphaned shm segments at startup", { meta: {
+			removed: purged.removed,
+			scanned: purged.scanned
+		} });
 		this.frameReaders = new _camstack_shm_ring.FrameRingReaderCache(this.ctx.logger);
-		this.ffmpegPath = await this.resolveFfmpegBinaryPath();
 		this.probedGpuScaleFilters = await probeGpuScaleFilters(this.ffmpegPath, this.ctx.logger);
 		this.ctx.logger.info("decoder-ffmpeg: probed GPU scale filters", { meta: {
 			filters: [...this.probedGpuScaleFilters],
 			ffmpeg: this.ffmpegPath
 		} });
-		return [{
+		registrations.push({
 			capability: decoderCapability,
 			provider: this
-		}];
+		});
+		return registrations;
 	}
 	/**
 	* Resolve the ffmpeg binary the sessions spawn — node-level only.
@@ -24518,6 +26050,8 @@ var DecoderFfmpegAddon = class extends BaseAddon {
 	}
 	async onShutdown() {
 		this.ctx.logger.info("ffmpeg decoder addon shutdown — destroying all sessions");
+		this.audioProvider?.stop();
+		this.audioProvider = null;
 		const destroyPromises = [];
 		for (const [sessionId, session] of this.sessions) {
 			const unsub = this.unsubscribers.get(sessionId);