@camstack/addon-pipeline 1.1.19 → 1.1.21

package/dist/audio-codec-ffmpeg/index.mjs

@@ -0,0 +1,1107 @@
+import { B as BaseAddon, _ as audioCodecCapability, z as errMsg } from "../dist-tzhTTRq4.mjs";
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+//#region src/audio-codec-ffmpeg/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-ffmpeg/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-ffmpeg/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 `pre-skip`: samples the decoder discards at stream start. 3840
+* samples (80 ms at 48 kHz) is a common, safe over-estimate for libopus — it
+* only trims a one-time startup transient and never drops steady-state audio.
+* (The precise libopus encoder lookahead is 312 samples; for a live stream we
+* do not need sample-accurate trimming, so the larger value is fine.)
+*/
+var DEFAULT_OPUS_PRE_SKIP = 3840;
+/** 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-ffmpeg/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;
+	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;
+		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;
+		}
+		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/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-ffmpeg/addon/index.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 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;
+var DEFAULT_GLOBAL_CONFIG = { defaultIdleMs: DEFAULT_IDLE_MS };
+/**
+* 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 addon is the cap's `preferredProvider` (declared on
+* `audio-codec.cap.ts`), so with no operator override it wins the singleton
+* active slot.
+*/
+var AudioCodecFfmpegAddon = class extends BaseAddon {
+	sessions = /* @__PURE__ */ new Map();
+	reaperTimer = null;
+	logger = null;
+	/**
+	* The ffmpeg binary every session spawns — resolved once at init from the
+	* operator `ffmpeg.binaryPath` override, else provisioned via
+	* `ctx.deps.ensureFfmpeg()`. Same binary the broker / recorder / decoder use.
+	*/
+	ffmpegPath = "ffmpeg";
+	constructor() {
+		super(DEFAULT_GLOBAL_CONFIG);
+	}
+	async onInitialize() {
+		this.logger = this.ctx.logger;
+		this.ffmpegPath = await this.resolveFfmpegBinaryPath();
+		this.reaperTimer = setInterval(() => this.reapIdleSessions(), REAPER_INTERVAL_MS);
+		if (typeof this.reaperTimer.unref === "function") this.reaperTimer.unref();
+		return [{
+			capability: audioCodecCapability,
+			provider: this
+		}];
+	}
+	async onShutdown() {
+		if (this.reaperTimer) {
+			clearInterval(this.reaperTimer);
+			this.reaperTimer = null;
+		}
+		for (const s of this.sessions.values()) this.disposeSession(s);
+		this.sessions.clear();
+	}
+	/**
+	* Resolve the ffmpeg binary the sessions spawn.
+	*
+	* Precedence (mirrors `decoder-ffmpeg`):
+	* 1. Operator override in the cluster `ffmpeg` config section (`binaryPath`).
+	* 2. Otherwise `ctx.deps.ensureFfmpeg()` — provisions a portable static
+	*    ffmpeg into the node's deps dir when the system has none.
+	*
+	* On failure, logs a loud ERROR and falls back to PATH `ffmpeg`; the addon
+	* still registers the cap and a later spawn re-runs against the same path.
+	*/
+	async resolveFfmpegBinaryPath() {
+		try {
+			const bp = (await this.ctx.settings?.getSection("ffmpeg") ?? {})["binaryPath"];
+			if (typeof bp === "string" && bp.trim().length > 0) return bp;
+		} catch {}
+		try {
+			return await this.ctx.deps.ensureFfmpeg();
+		} catch (err) {
+			this.ctx.logger.error("audio-codec-ffmpeg: ensureFfmpeg() failed to provision ffmpeg — falling back to PATH \"ffmpeg\"", { meta: { error: errMsg(err) } });
+			return "ffmpeg";
+		}
+	}
+	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.logger?.info("audio-codec-ffmpeg: decode session created", {
+			tags: { sessionId },
+			meta: {
+				codec,
+				target: `${input.targetSampleRate}Hz×${input.targetChannels}`
+			}
+		});
+		return {
+			sessionId,
+			nodeId: this.ctx.kernel.localNodeId ?? "local"
+		};
+	}
+	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.logger?.info("audio-codec-ffmpeg: encode session created", {
+			tags: { sessionId },
+			meta: {
+				codec,
+				target: `${input.targetSampleRate}Hz×${input.targetChannels}`
+			}
+		});
+		return {
+			sessionId,
+			nodeId: this.ctx.kernel.localNodeId ?? "local"
+		};
+	}
+	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) {
+		const logger = this.logger ?? this.ctx.logger;
+		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.ffmpegPath,
+			oggSerialSeed: s.sessionId
+		}, logger, (chunk) => {
+			s.pcmQueue.push(chunk);
+		});
+	}
+	spawnEncodeSession(s) {
+		const logger = this.logger ?? this.ctx.logger;
+		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.ffmpegPath
+		}, 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.config.defaultIdleMs ?? DEFAULT_IDLE_MS;
+			if (now - s.lastActivityMs > limit) {
+				this.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.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.logger?.warn("audio-codec-ffmpeg: session destroy failed", {
+				tags: { sessionId: s.sessionId },
+				meta: { error: errMsg(err) }
+			});
+		}
+		s.session = null;
+	}
+};
+//#endregion
+export { AUDIO_LOW_LATENCY_ARGS, AudioCodecFfmpegAddon, AudioCodecFfmpegAddon as default, DEFAULT_OPUS_PRE_SKIP, OggOpusFramer, audioBytesPerSample, buildAudioDecodeArgs, buildAudioEncodeArgs, buildLacing, decodeFormatForCodec, encodeFormatForCodec, oggCrc32, opusPacketSampleCount, resolveAudioCodecAlias, serialFromSeed };