@camstack/addon-decoder-ffmpeg 1.1.3 → 1.1.5

package/dist/index.mjs

@@ -12530,42 +12530,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(),
@@ -24134,6 +24171,1160 @@ function probeGpuScaleFilters(ffmpegPath, logger) {
 	});
 }
 //#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 = 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-${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-${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;
 /**
@@ -24173,6 +25364,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);
 	}
@@ -24210,23 +25409,35 @@ 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 } });
 		this.frameReaders = new 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.
@@ -24514,6 +25725,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);