@camstack/addon-decoder-nodeav 1.1.3 → 1.1.4

package/dist/index.mjs

@@ -12793,42 +12793,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(),
@@ -24296,6 +24333,788 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 	}
 };
 //#endregion
+//#region src/audio-codec/codec-catalog.ts
+/**
+* Normalise an SDP-reported codec name to the libav/ffmpeg name. Mirrors
+* `audio-codec-ffmpeg`'s `resolveAudioCodecAlias` 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;
+}
+/**
+* Supported codec matrix. `aac_latm` / `mpeg4-generic` are decode-only (they
+* exist only as camera-side inbound streams; the intercom back-channel encodes
+* plain `aac`). Kept byte-for-byte in step with the ffmpeg addon's catalogue.
+*/
+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"
+	}
+];
+/** Resolve the catalogue entry for a codec name (alias-normalised). */
+function catalogEntryFor(codec) {
+	const resolved = resolveAudioCodecAlias(codec);
+	return CODEC_CATALOG.find((e) => resolveAudioCodecAlias(e.codec) === resolved) ?? null;
+}
+/** Cheap predicate — is `(codec, kind)` in the catalogue? */
+function codecSupports(codec, kind) {
+	const entry = catalogEntryFor(codec);
+	if (!entry) return false;
+	return kind === "decode" ? entry.canDecode : entry.canEncode;
+}
+/**
+* Resolve an (alias-normalised) codec name to its canonical libav key, or
+* `null` for names outside this addon's SDP audio matrix. Kept pure (string
+* only) — the branded `AVCodecID` lookup lives in `nodeav-av-types.ts` where
+* node-av's constants are in scope. G.722 maps to `AV_CODEC_ID_ADPCM_G722`.
+*/
+function resolveCodecKey(codec) {
+	switch (resolveAudioCodecAlias(codec)) {
+		case "aac": return "aac";
+		case "aac_latm": return "aac_latm";
+		case "opus": return "opus";
+		case "pcm_alaw": return "pcm_alaw";
+		case "pcm_mulaw": return "pcm_mulaw";
+		case "g722": return "g722";
+		default: return null;
+	}
+}
+//#endregion
+//#region src/audio-codec/nodeav-av-types.ts
+/**
+* Resolve a codec name to its branded libav `AVCodecID` using the real
+* constants. Returns `null` for names outside this addon's matrix. G.722 maps
+* to `AV_CODEC_ID_ADPCM_G722` (there is no plain `AV_CODEC_ID_G722`).
+*/
+function resolveAvCodecId(codec, consts) {
+	switch (resolveCodecKey(codec)) {
+		case "aac": return consts.AV_CODEC_ID_AAC;
+		case "aac_latm": return consts.AV_CODEC_ID_AAC_LATM;
+		case "opus": return consts.AV_CODEC_ID_OPUS;
+		case "pcm_alaw": return consts.AV_CODEC_ID_PCM_ALAW;
+		case "pcm_mulaw": return consts.AV_CODEC_ID_PCM_MULAW;
+		case "g722": return consts.AV_CODEC_ID_ADPCM_G722;
+		case null: return null;
+	}
+}
+/** Build a canonical mono/stereo (or bare-mask) channel layout. */
+function buildChannelLayout(consts, channels) {
+	if (channels === 1) return {
+		nbChannels: 1,
+		order: consts.AV_CHANNEL_ORDER_NATIVE,
+		mask: consts.AV_CH_LAYOUT_MONO
+	};
+	if (channels === 2) return {
+		nbChannels: 2,
+		order: consts.AV_CHANNEL_ORDER_NATIVE,
+		mask: consts.AV_CH_LAYOUT_STEREO
+	};
+	return {
+		nbChannels: channels,
+		order: consts.AV_CHANNEL_ORDER_NATIVE,
+		mask: 0n
+	};
+}
+//#endregion
+//#region src/audio-codec/nodeav-audio-decode-session.ts
+function targetSampleFmt(consts, format) {
+	return format === "f32le" ? consts.AV_SAMPLE_FMT_FLT : consts.AV_SAMPLE_FMT_S16;
+}
+function bytesPerSample(format) {
+	return format === "f32le" ? 4 : 2;
+}
+var NodeAvAudioDecodeSession = class {
+	runtime;
+	cfg;
+	logger;
+	onPcm;
+	ctx;
+	swr;
+	packet;
+	inFrame;
+	outFrame;
+	outLayout;
+	outSampleFmt;
+	outBytesPerSample;
+	outFormat;
+	nextPts = 0;
+	closed = false;
+	/**
+	* Synchronously build a decode runtime from the already-loaded node-av
+	* runtime. Throws (freeing anything already allocated) on any libav error so
+	* the addon surfaces a clean "decode session failed" without leaking a
+	* half-open context.
+	*/
+	constructor(runtime, cfg, logger, onPcm) {
+		this.runtime = runtime;
+		this.cfg = cfg;
+		this.logger = logger;
+		this.onPcm = onPcm;
+		this.outFormat = cfg.targetFormat;
+		this.outBytesPerSample = bytesPerSample(cfg.targetFormat);
+		const { nav, consts } = runtime;
+		const codecId = resolveAvCodecId(cfg.codec, consts);
+		if (codecId === null) throw new Error(`audio-codec-nodeav: unknown codec '${cfg.codec}' for decode`);
+		const codec = nav.Codec.findDecoder(codecId);
+		if (!codec) throw new Error(`audio-codec-nodeav: decoder not registered for '${cfg.codec}'`);
+		const ctx = new nav.CodecContext();
+		ctx.allocContext3(codec);
+		ctx.sampleRate = cfg.sourceSampleRate;
+		const inLayout = buildChannelLayout(consts, cfg.sourceChannels);
+		ctx.channelLayout = inLayout;
+		if (cfg.extraData && cfg.extraData.byteLength > 0) ctx.extraData = Buffer.from(cfg.extraData);
+		const openRet = ctx.open2Sync(codec, null);
+		if (openRet < 0) {
+			ctx.freeContext();
+			throw new Error(`audio-codec-nodeav: open2 failed for '${cfg.codec}' (ret=${openRet})`);
+		}
+		const inSampleFmt = ctx.sampleFormat;
+		this.outSampleFmt = targetSampleFmt(consts, cfg.targetFormat);
+		this.outLayout = buildChannelLayout(consts, cfg.targetChannels);
+		const swr = new nav.SoftwareResampleContext();
+		const allocRet = swr.allocSetOpts2(this.outLayout, this.outSampleFmt, cfg.targetSampleRate, inLayout, inSampleFmt, cfg.sourceSampleRate);
+		if (allocRet < 0) {
+			ctx.freeContext();
+			throw new Error(`audio-codec-nodeav: swr allocSetOpts2 failed (ret=${allocRet})`);
+		}
+		const initRet = swr.init();
+		if (initRet < 0) {
+			swr.free();
+			ctx.freeContext();
+			throw new Error(`audio-codec-nodeav: swr init failed (ret=${initRet})`);
+		}
+		const packet = new nav.Packet();
+		packet.alloc();
+		const inFrame = new nav.Frame();
+		inFrame.alloc();
+		const outFrame = new nav.Frame();
+		outFrame.alloc();
+		this.ctx = ctx;
+		this.swr = swr;
+		this.packet = packet;
+		this.inFrame = inFrame;
+		this.outFrame = outFrame;
+	}
+	/** Decode one encoded access unit, emitting resampled PCM via `onPcm`. */
+	pushEncoded(data, pts) {
+		if (this.closed) return;
+		const { consts } = this.runtime;
+		this.packet.data = Buffer.from(data);
+		if (pts !== void 0) {
+			const p = BigInt(Math.round(pts));
+			this.packet.pts = p;
+			this.packet.dts = p;
+		}
+		const sendRet = this.ctx.sendPacketSync(this.packet);
+		if (sendRet < 0 && sendRet !== consts.AVERROR_EAGAIN) throw new Error(`audio-codec-nodeav: sendPacket failed (ret=${sendRet})`);
+		for (;;) {
+			const recvRet = this.ctx.receiveFrameSync(this.inFrame);
+			if (recvRet === consts.AVERROR_EAGAIN || recvRet === consts.AVERROR_EOF) break;
+			if (recvRet < 0) throw new Error(`audio-codec-nodeav: receiveFrame failed (ret=${recvRet})`);
+			try {
+				const chunk = this.resampleFrame(this.inFrame);
+				if (chunk) this.onPcm(chunk);
+			} finally {
+				this.inFrame.unref();
+			}
+		}
+	}
+	resampleFrame(inFrame) {
+		const outSamples = this.swr.getOutSamples(inFrame.nbSamples);
+		if (outSamples <= 0) return null;
+		this.outFrame.unref();
+		this.outFrame.format = this.outSampleFmt;
+		this.outFrame.sampleRate = this.cfg.targetSampleRate;
+		this.outFrame.channelLayout = this.outLayout;
+		this.outFrame.nbSamples = outSamples;
+		const bufRet = this.outFrame.getBuffer(0);
+		if (bufRet < 0) throw new Error(`audio-codec-nodeav: outFrame.getBuffer failed (ret=${bufRet})`);
+		const convRet = this.swr.convertFrame(this.outFrame, inFrame);
+		if (convRet < 0) throw new Error(`audio-codec-nodeav: swr.convertFrame failed (ret=${convRet})`);
+		const produced = this.outFrame.nbSamples;
+		if (produced <= 0) return null;
+		const planes = this.outFrame.extendedData;
+		const plane0 = planes && planes.length > 0 ? planes[0] : null;
+		if (!plane0) return null;
+		const bytes = produced * this.cfg.targetChannels * this.outBytesPerSample;
+		const out = new Uint8Array(new ArrayBuffer(bytes));
+		out.set(plane0.subarray(0, bytes));
+		const ptsMs = this.nextPts;
+		this.nextPts = ptsMs + Math.round(produced * 1e3 / this.cfg.targetSampleRate);
+		return {
+			data: out,
+			sampleRate: this.cfg.targetSampleRate,
+			channels: this.cfg.targetChannels,
+			format: this.outFormat,
+			pts: ptsMs
+		};
+	}
+	/** Release every native handle. Idempotent; safe to call from a reaper. */
+	destroy() {
+		if (this.closed) return;
+		this.closed = true;
+		this.freeQuietly(() => this.outFrame.free(), "outFrame");
+		this.freeQuietly(() => this.inFrame.free(), "inFrame");
+		this.freeQuietly(() => this.packet.free(), "packet");
+		this.freeQuietly(() => this.swr.free(), "swr");
+		this.freeQuietly(() => this.ctx.freeContext(), "codecContext");
+	}
+	freeQuietly(fn, what) {
+		try {
+			fn();
+		} catch (err) {
+			this.logger.warn("audio-codec-nodeav: decode handle free failed", { meta: {
+				what,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
+//#region src/audio-codec/nodeav-audio-encode-session.ts
+function sourceSampleFmt(consts, format) {
+	return format === "f32le" ? consts.AV_SAMPLE_FMT_FLT : consts.AV_SAMPLE_FMT_S16;
+}
+function sourceBytesPerSample(format) {
+	return format === "f32le" ? 4 : 2;
+}
+var NodeAvAudioEncodeSession = class {
+	runtime;
+	cfg;
+	logger;
+	onChunk;
+	codecName;
+	ctx;
+	swr;
+	fifo;
+	packet;
+	outLayout;
+	encoderSampleFmt;
+	srcSampleFmt;
+	srcBytesPerSample;
+	/** Encoder-required samples per frame; `<= 0` means variable (drain all). */
+	frameSize;
+	ptsSamples = 0;
+	closed = false;
+	constructor(runtime, cfg, logger, onChunk) {
+		this.runtime = runtime;
+		this.cfg = cfg;
+		this.logger = logger;
+		this.onChunk = onChunk;
+		this.codecName = resolveAudioCodecAlias(cfg.codec);
+		this.srcSampleFmt = sourceSampleFmt(runtime.consts, cfg.sourceFormat);
+		this.srcBytesPerSample = sourceBytesPerSample(cfg.sourceFormat);
+		const { nav, consts } = runtime;
+		const codecId = resolveAvCodecId(cfg.codec, consts);
+		if (codecId === null) throw new Error(`audio-codec-nodeav: unknown codec '${cfg.codec}' for encode`);
+		const codec = nav.Codec.findEncoder(codecId);
+		if (!codec) throw new Error(`audio-codec-nodeav: encoder not registered for '${cfg.codec}'`);
+		const fmts = codec.sampleFormats;
+		this.encoderSampleFmt = fmts && fmts.length > 0 ? fmts[0] : consts.AV_SAMPLE_FMT_S16;
+		this.outLayout = buildChannelLayout(consts, cfg.targetChannels);
+		const ctx = new nav.CodecContext();
+		ctx.allocContext3(codec);
+		ctx.sampleRate = cfg.targetSampleRate;
+		ctx.channelLayout = this.outLayout;
+		ctx.sampleFormat = this.encoderSampleFmt;
+		if (cfg.bitrateKbps !== void 0) ctx.bitRate = BigInt(Math.round(cfg.bitrateKbps * 1e3));
+		const openRet = ctx.open2Sync(codec, null);
+		if (openRet < 0) {
+			ctx.freeContext();
+			throw new Error(`audio-codec-nodeav: encoder open2 failed for '${cfg.codec}' (ret=${openRet})`);
+		}
+		this.frameSize = ctx.frameSize > 0 ? ctx.frameSize : 0;
+		const swr = new nav.SoftwareResampleContext();
+		const inLayout = buildChannelLayout(consts, cfg.sourceChannels);
+		const allocRet = swr.allocSetOpts2(this.outLayout, this.encoderSampleFmt, cfg.targetSampleRate, inLayout, this.srcSampleFmt, cfg.sourceSampleRate);
+		if (allocRet < 0) {
+			ctx.freeContext();
+			throw new Error(`audio-codec-nodeav: encode swr allocSetOpts2 failed (ret=${allocRet})`);
+		}
+		if (swr.init() < 0) {
+			swr.free();
+			ctx.freeContext();
+			throw new Error("audio-codec-nodeav: encode swr init failed");
+		}
+		const fifo = new nav.AudioFifo();
+		fifo.alloc(this.encoderSampleFmt, cfg.targetChannels, this.frameSize > 0 ? this.frameSize : 1024);
+		const packet = new nav.Packet();
+		packet.alloc();
+		this.ctx = ctx;
+		this.swr = swr;
+		this.fifo = fifo;
+		this.packet = packet;
+	}
+	/** Push one interleaved PCM chunk; emits encoded packets via `onChunk`. */
+	pushPcm(data) {
+		if (this.closed || data.byteLength === 0) return;
+		const frameBytes = this.cfg.sourceChannels * this.srcBytesPerSample;
+		const inSamples = Math.floor(data.byteLength / frameBytes);
+		if (inSamples <= 0) return;
+		this.resampleIntoFifo(data, inSamples);
+		this.drainFifo(false);
+	}
+	/**
+	* Flush the encoder: drain any partial frame left in the FIFO, then signal
+	* end-of-stream so the codec emits its tail packets. Called before a graceful
+	* close.
+	*/
+	flush() {
+		if (this.closed) return;
+		this.drainFifo(true);
+		try {
+			if (this.ctx.sendFrameSync(null) >= 0) this.drainEncoder();
+		} catch (err) {
+			this.logger.warn("audio-codec-nodeav: encode flush failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+	}
+	resampleIntoFifo(data, inSamples) {
+		const { nav } = this.runtime;
+		const inFrame = new nav.Frame();
+		inFrame.alloc();
+		const outFrame = new nav.Frame();
+		outFrame.alloc();
+		try {
+			inFrame.format = this.srcSampleFmt;
+			inFrame.sampleRate = this.cfg.sourceSampleRate;
+			inFrame.channelLayout = buildChannelLayout(this.runtime.consts, this.cfg.sourceChannels);
+			inFrame.nbSamples = inSamples;
+			const inBufRet = inFrame.getBuffer(0);
+			if (inBufRet < 0) throw new Error(`inFrame.getBuffer failed (ret=${inBufRet})`);
+			const planes = inFrame.extendedData;
+			const plane0 = planes && planes.length > 0 ? planes[0] : null;
+			if (!plane0) throw new Error("inFrame has no data plane");
+			plane0.set(data.subarray(0, inSamples * this.cfg.sourceChannels * this.srcBytesPerSample));
+			const outSamples = this.swr.getOutSamples(inSamples);
+			if (outSamples <= 0) return;
+			outFrame.format = this.encoderSampleFmt;
+			outFrame.sampleRate = this.cfg.targetSampleRate;
+			outFrame.channelLayout = this.outLayout;
+			outFrame.nbSamples = outSamples;
+			const outBufRet = outFrame.getBuffer(0);
+			if (outBufRet < 0) throw new Error(`outFrame.getBuffer failed (ret=${outBufRet})`);
+			const convRet = this.swr.convertFrame(outFrame, inFrame);
+			if (convRet < 0) throw new Error(`swr.convertFrame failed (ret=${convRet})`);
+			const produced = outFrame.nbSamples;
+			if (produced <= 0) return;
+			const outPlanes = outFrame.extendedData;
+			if (!outPlanes || outPlanes.length === 0) return;
+			this.fifo.writeSync(outPlanes, produced);
+		} finally {
+			inFrame.free();
+			outFrame.free();
+		}
+	}
+	/**
+	* Pull `frameSize`-sized frames out of the FIFO and encode them. When
+	* `flushTail` is set, also encode the final short frame (< frameSize) so no
+	* tail samples are dropped on close.
+	*/
+	drainFifo(flushTail) {
+		const chunk = this.frameSize > 0 ? this.frameSize : this.fifo.size;
+		if (chunk <= 0) return;
+		while (this.fifo.size >= chunk && chunk > 0) {
+			this.encodeFromFifo(chunk);
+			if (this.frameSize <= 0) break;
+		}
+		if (flushTail && this.fifo.size > 0) this.encodeFromFifo(this.fifo.size);
+	}
+	encodeFromFifo(nbSamples) {
+		if (nbSamples <= 0) return;
+		const { nav } = this.runtime;
+		const frame = new nav.Frame();
+		frame.alloc();
+		try {
+			frame.format = this.encoderSampleFmt;
+			frame.sampleRate = this.cfg.targetSampleRate;
+			frame.channelLayout = this.outLayout;
+			frame.nbSamples = nbSamples;
+			const bufRet = frame.getBuffer(0);
+			if (bufRet < 0) throw new Error(`encodeFrame.getBuffer failed (ret=${bufRet})`);
+			const planes = frame.extendedData;
+			if (!planes || planes.length === 0) throw new Error("encodeFrame has no data plane");
+			const read = this.fifo.readSync(planes, nbSamples);
+			if (read <= 0) return;
+			frame.nbSamples = read;
+			frame.pts = BigInt(this.ptsSamples);
+			this.ptsSamples += read;
+			const sendRet = this.ctx.sendFrameSync(frame);
+			if (sendRet < 0) throw new Error(`sendFrame failed (ret=${sendRet})`);
+			this.drainEncoder();
+		} finally {
+			frame.free();
+		}
+	}
+	drainEncoder() {
+		const { consts } = this.runtime;
+		for (;;) {
+			const recvRet = this.ctx.receivePacketSync(this.packet);
+			if (recvRet === consts.AVERROR_EAGAIN || recvRet === consts.AVERROR_EOF) break;
+			if (recvRet < 0) throw new Error(`audio-codec-nodeav: receivePacket failed (ret=${recvRet})`);
+			try {
+				const payload = this.packet.data;
+				if (payload && payload.byteLength > 0) {
+					const out = new Uint8Array(new ArrayBuffer(payload.byteLength));
+					out.set(payload);
+					const pktPts = this.packet.pts;
+					const ptsMs = pktPts >= 0n ? Math.round(Number(pktPts) * 1e3 / this.cfg.targetSampleRate) : 0;
+					this.onChunk({
+						data: out,
+						codec: this.codecName,
+						pts: ptsMs,
+						frameComplete: true
+					});
+				}
+			} finally {
+				this.packet.unref();
+			}
+		}
+	}
+	destroy() {
+		if (this.closed) return;
+		this.closed = true;
+		this.freeQuietly(() => this.packet.free(), "packet");
+		this.freeQuietly(() => this.fifo.free(), "fifo");
+		this.freeQuietly(() => this.swr.free(), "swr");
+		this.freeQuietly(() => this.ctx.freeContext(), "codecContext");
+	}
+	freeQuietly(fn, what) {
+		try {
+			fn();
+		} catch (err) {
+			this.logger.warn("audio-codec-nodeav: encode handle free failed", { meta: {
+				what,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
+//#region src/audio-codec/provider.ts
+var DEFAULT_IDLE_MS = 3e4;
+var MAX_PCM_QUEUE_CHUNKS = 500;
+var REAPER_INTERVAL_MS = 5e3;
+/** Grace wait for the encoder to drain its tail after `flushEncode`. */
+var FLUSH_DRAIN_MS = 60;
+/**
+* Audio codec I/O box backed by **node-av's in-process libavcodec +
+* libswresample bindings** — the native counterpart to `audio-codec-ffmpeg`.
+* Decode/encode run in this addon's process (no subprocess), feeding raw
+* depacketized access units straight into a `CodecContext` (no ADTS/Ogg
+* container shim needed).
+*
+* This is a PLAIN provider (not a `BaseAddon`): it is owned and driven by the
+* `decoder-nodeav` addon, which loads the shared node-av runtime once and
+* hands it in. When node-av cannot be loaded on this node the owning addon
+* never constructs this provider, so the singleton slot falls back to
+* `audio-codec-ffmpeg`.
+*/
+var NodeAvAudioCodecProvider = class {
+	deps;
+	sessions = /* @__PURE__ */ new Map();
+	reaperTimer = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Arm the idle-session reaper. Called by the owning addon after construction. */
+	start() {
+		this.reaperTimer = setInterval(() => this.reapIdleSessions(), REAPER_INTERVAL_MS);
+		if (typeof this.reaperTimer.unref === "function") this.reaperTimer.unref();
+	}
+	/** Stop the reaper and dispose every live session. Called on addon 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) {
+		return codecSupports(input.codec, input.kind);
+	}
+	async createDecodeSession(input) {
+		const codec = resolveAudioCodecAlias(input.codec);
+		const entry = catalogEntryFor(input.codec);
+		if (!entry || !entry.canDecode) throw new Error(`audio-codec-nodeav: 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-nodeav: 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 = catalogEntryFor(input.codec);
+		if (!entry || !entry.canEncode) throw new Error(`audio-codec-nodeav: 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-nodeav: 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-nodeav: 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, input.pts);
+	}
+	async pullPcm(input) {
+		const s = this.sessions.get(input.sessionId);
+		if (!s || s.kind !== "decode") throw new Error(`audio-codec-nodeav: 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-nodeav: 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-nodeav: 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-nodeav: 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 NodeAvAudioDecodeSession(this.deps.runtime, {
+			codec: s.config.codec,
+			sourceSampleRate: s.config.sourceSampleRate,
+			sourceChannels: s.config.sourceChannels,
+			...s.config.extraData ? { extraData: s.config.extraData } : {},
+			targetSampleRate: s.config.targetSampleRate,
+			targetChannels: s.config.targetChannels,
+			targetFormat: this.pcmFormat(s.config.targetFormat)
+		}, 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 NodeAvAudioEncodeSession(this.deps.runtime, {
+			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 } : {}
+		}, this.deps.logger, (chunk) => {
+			s.encodedQueue.push(chunk);
+		});
+	}
+	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 ?? DEFAULT_IDLE_MS;
+			if (now - s.lastActivityMs > limit) {
+				this.deps.logger.info("audio-codec-nodeav: 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-nodeav: 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-nodeav: session destroy failed", {
+				tags: { sessionId: s.sessionId },
+				meta: { error: errMsg(err) }
+			});
+		}
+		s.session = null;
+	}
+};
+//#endregion
+//#region src/audio-codec/nodeav-runtime-loader.ts
+var _runtime = null;
+/**
+* Load (or return the cached) node-av runtime. Rejects if the native binding
+* cannot be loaded on this node — the caller treats that as "node-av
+* unavailable" and declines to register the cap so the singleton falls back to
+* `audio-codec-ffmpeg`.
+*/
+async function loadNodeAvRuntime() {
+	if (_runtime) return _runtime;
+	const [nav, consts] = await Promise.all([import("node-av"), import("node-av/constants")]);
+	_runtime = {
+		nav,
+		consts
+	};
+	return _runtime;
+}
+/**
+* The already-loaded runtime, or `null` if `loadNodeAvRuntime` has not resolved
+* yet. Session runtimes read this synchronously — the addon guarantees it is
+* populated before any session is created.
+*/
+function peekNodeAvRuntime() {
+	return _runtime;
+}
+//#endregion
 //#region src/addon/index.ts
 var FRAME_BUFFER_CAPACITY = 32;
 var DecoderNodeAvAddon = class extends BaseAddon {
@@ -24321,6 +25140,12 @@ var DecoderNodeAvAddon = class extends BaseAddon {
 	/** Running `getFrame` hit/miss counters surfaced via `getShmStats`. */
 	getFrameHits = 0;
 	getFrameMisses = 0;
+	/**
+	* node-av audio-codec provider — registered independently of the video
+	* decoder backend gate whenever node-av loads on this node, so this single
+	* addon provides both the `decoder` and `audio-codec` caps.
+	*/
+	audioProvider = null;
 	constructor() {
 		super(DEFAULT_DECODER_HWACCEL_CONFIG);
 	}
@@ -24355,20 +25180,40 @@ var DecoderNodeAvAddon = class extends BaseAddon {
 		}] });
 	}
 	async onInitialize() {
+		const registrations = [];
+		let runtime = null;
+		try {
+			runtime = await loadNodeAvRuntime();
+		} catch (err) {
+			this.ctx.logger.error("decoder-nodeav: node-av failed to load — no audio-codec provider", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+		if (runtime) {
+			this.audioProvider = new NodeAvAudioCodecProvider({
+				logger: this.ctx.logger,
+				runtime,
+				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 !== "nodeav") {
 			this.ctx.logger.info("node-av decoder: this node selects a different decoder backend — standing down (no decoder provider registered)", { meta: { selectedBackend: backend } });
-			return [];
+			return registrations;
 		}
 		this.ctx.logger.info("node-av decoder addon initialized", { meta: { selectedBackend: backend } });
 		this.frameReaders = new FrameRingReaderCache(this.ctx.logger);
 		if (!this.config.probedBestHwaccel) this.reprobeHwaccel().catch((err) => {
 			this.ctx.logger.warn("nodeav: auto-reprobe hwaccel failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
 		});
-		return [{
+		registrations.push({
 			capability: decoderCapability,
 			provider: this
-		}];
+		});
+		return registrations;
 	}
 	/**
 	* Resolve the effective hwaccel backend for a new session — from THIS addon's
@@ -24614,6 +25459,8 @@ var DecoderNodeAvAddon = class extends BaseAddon {
 		};
 	}
 	async onShutdown() {
+		this.audioProvider?.stop();
+		this.audioProvider = null;
 		this.ctx.logger.info("node-av decoder addon shutdown — destroying all sessions");
 		const destroyPromises = [];
 		for (const [sessionId, session] of this.sessions) {
@@ -24632,4 +25479,4 @@ var DecoderNodeAvAddon = class extends BaseAddon {
 	}
 };
 //#endregion
-export { DecoderFrameRingSink, DecoderNodeAvAddon, DecoderNodeAvAddon as default, NodeAvDecoderSession, makeSegmentName };
+export { DecoderFrameRingSink, DecoderNodeAvAddon, DecoderNodeAvAddon as default, NodeAvAudioCodecProvider, NodeAvAudioDecodeSession, NodeAvAudioEncodeSession, NodeAvDecoderSession, loadNodeAvRuntime, makeSegmentName, peekNodeAvRuntime };