@camstack/addon-decoder-nodeav 1.1.3 → 1.1.5

package/dist/index.mjs

@@ -1,5 +1,6 @@
-import { FrameRingReaderCache, FrameRingWriter, MIN_RING_SLOTS, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount } from "@camstack/shm-ring";
+import { FrameRingReaderCache, FrameRingWriter, MIN_RING_SLOTS, computeSegmentSize, computeSlotByteLength, createSegment, deriveSlotCount, unlinkSegment } from "@camstack/shm-ring";
 import { randomUUID } from "node:crypto";
+import { readdirSync } from "node:fs";
 //#region src/frame-ring-sink.ts
 /**
 * `DecoderFrameRingSink` — the decoder's shared-memory write side (Phase 5 / D9).
@@ -67,10 +68,16 @@ var RING_BUDGET_BYTES = RING_BUDGET_MB * 1024 * 1024;
 * segment (resolution change) a distinct name so a stale consumer mapping is
 * never silently reused.
 */
+/**
+* Shared prefix for every decoder shm segment name. Startup orphan reclamation
+* (`purgeOrphanSegments`) keys off this to find segments left behind by a
+* crashed prior instance.
+*/
+var SEGMENT_NAME_PREFIX = "csf.";
 function makeSegmentName(seed, generation) {
 	let hash = 5381;
 	for (let i = 0; i < seed.length; i += 1) hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
-	return `csf.${(hash >>> 0).toString(36)}.${generation}`;
+	return `${SEGMENT_NAME_PREFIX}${(hash >>> 0).toString(36)}.${generation}`;
 }
 /**
 * The decoder-side owner of one stream's shared-memory frame ring.
@@ -4893,7 +4900,7 @@ function _instanceof(cls, params = {}) {
 	return inst;
 }
 //#endregion
-//#region ../types/dist/sleep-BiDFW0E7.mjs
+//#region ../types/dist/sleep-CZDdRBua.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -7500,7 +7507,16 @@ var DecoderStatsSchema = object({
 	inputFps: number(),
 	outputFps: number(),
 	avgDecodeTimeMs: number(),
-	droppedFrames: number()
+	droppedFrames: number(),
+	/**
+	* Pull-mode adaptive-fps telemetry (optional — only pull sessions run the
+	* lag-driven controller; push sessions omit these). `lagMs` is the EWMA of
+	* the decoder's real-time drift (rising = falling behind live); `adaptiveFps`
+	* is the current lag-throttled emit rate (≤ `effectiveFps` ceiling).
+	*/
+	lagMs: number().optional(),
+	effectiveFps: number().optional(),
+	adaptiveFps: number().optional()
 });
 var DecoderSessionConfigSchema = object({
 	codec: string(),
@@ -7541,7 +7557,15 @@ var DecoderSessionConfigSchema = object({
 	*   other — `pullFrames` returns nothing for an `'shm'` session and
 	*   `pullHandles` returns nothing for a `'callback'` session.
 	*/
-	frameSink: _enum(["callback", "shm"]).default("callback")
+	frameSink: _enum(["callback", "shm"]).default("callback"),
+	/**
+	* Per-camera decoder DEBUG facility. When `true`, a pull-mode session emits
+	* a throttled (~1Hz) structured `decoder debug` line (effective/adaptive fps,
+	* real-time lag, dropped-frame delta, avg decode time, hwaccel). Mirrors the
+	* stream-broker's `streamingDebug` gate — off by default so production logs
+	* stay quiet and the emit path pays zero per-frame cost when disabled.
+	*/
+	debug: boolean().optional()
 });
 var EncodeProfileSchema = object({
 	video: object({
@@ -9699,6 +9723,75 @@ DeviceType.Cover, method(object({ deviceId: number().int().nonnegative() }), _vo
 	auth: "admin"
 });
 /**
+* Vendor-neutral day/night (IR-cut) control — the per-camera config cap
+* shared by reolink / hikvision / amcrest. Models the common firmware
+* surface: the IR-cut switching MODE plus the two knobs that gate it
+* (photocell `sensitivity` + `switchDelaySec`). Each vendor maps these
+* onto its own ISAPI / Baichuan / Dahua-CGI fields; the cap standardises
+* the shape so ONE derived-form renders every camera.
+*
+* Follows the D14 `deviceConfig` archetype (see `stream-params.cap.ts`):
+* `getOptions` advertises per-camera availability, `getStatus` (auto-
+* injected from `status`) reports the live values, and a single
+* `setSettings` mutation applies a partial change. No hand-written
+* settings-contribution methods — the framework derives the UI + save
+* routing from this surface.
+*/
+/** IR-cut switching mode. `schedule` = time-of-day table configured on the camera. */
+var DayNightModeSchema = _enum([
+	"auto",
+	"day",
+	"night",
+	"schedule"
+]);
+/** Normalized numeric range descriptor — `{ min, max, step }` per the
+*  getOptions availability convention. Normalized values are 0–100. */
+var NormalizedRangeSchema$1 = object({
+	min: number(),
+	max: number(),
+	step: number()
+});
+object({
+	mode: DayNightModeSchema,
+	/** IR-cut trigger sensitivity, NORMALIZED 0–100 (higher = switches to night sooner). */
+	sensitivity: number().optional(),
+	/** Delay before the IR-cut filter flips, in seconds. */
+	switchDelaySec: number().optional(),
+	lastFetchedAt: number()
+});
+/**
+* Per-camera availability descriptor — drives which controls the admin UI
+* renders. Booleans as `supportsX`; numeric ranges as `{ min, max, step }`
+* (normalized 0–100); the mode choice-set as an array. A provider returns
+* honest, camera-probed values — never hardcoded.
+*/
+var DayNightOptionsSchema = object({
+	/** Modes this camera accepts. Empty → the camera has no configurable day/night mode. */
+	modes: array(DayNightModeSchema),
+	supportsSensitivity: boolean(),
+	/** Present when `supportsSensitivity` — the normalized 0–100 range. */
+	sensitivity: NormalizedRangeSchema$1.optional(),
+	supportsSwitchDelay: boolean(),
+	/** Present when `supportsSwitchDelay` — the allowed delay range in seconds. */
+	switchDelaySec: NormalizedRangeSchema$1.optional()
+});
+/**
+* Partial change to the day/night config — every field optional. A
+* provider ignores fields it does not support.
+*/
+var DayNightSettingsPatchSchema = object({
+	mode: DayNightModeSchema.optional(),
+	sensitivity: number().optional(),
+	switchDelaySec: number().optional()
+});
+DeviceType.Camera, method(object({ deviceId: number() }), DayNightOptionsSchema), method(object({
+	deviceId: number(),
+	settings: DayNightSettingsPatchSchema
+}), _void(), {
+	kind: "mutation",
+	auth: "admin"
+});
+/**
 * Identity envelope for a device's upstream-system metadata.
 *
 * Two jobs:
@@ -10054,6 +10147,130 @@ object({
 });
 DeviceType.Image;
 /**
+* Vendor-neutral image / picture-adjustment cap — the per-camera config
+* cap shared by reolink / hikvision / amcrest. Models the common ISP
+* surface: the four picture sliders (brightness / contrast / saturation /
+* sharpness), orientation (mirror / flip / rotate), white-balance,
+* exposure and backlight-compensation modes.
+*
+* NORMALIZATION: every slider is a normalized int 0–100. Vendors expose
+* these natively as 0–100 or 0–255 (or other ranges); each provider maps
+* its native range to/from this normalized 0–100 space so the cap surface
+* (and the derived form) is identical across cameras. `warmth` (manual
+* white-balance) is likewise normalized 0–100.
+*
+* Follows the D14 `deviceConfig` archetype (see `stream-params.cap.ts`):
+* `getOptions` advertises per-camera availability, `getStatus` (auto-
+* injected from `status`) reports the live values, and a single
+* `setSettings` mutation applies a partial change. No hand-written
+* settings-contribution methods — the framework derives the UI + save
+* routing from this surface.
+*/
+/** Sensor/image rotation, degrees clockwise. */
+var ImageRotateSchema = _enum([
+	"0",
+	"90",
+	"180",
+	"270"
+]);
+/** White-balance mode. `manual` unlocks the normalized `warmth` knob. */
+var WhiteBalanceModeSchema = _enum(["auto", "manual"]);
+/** Exposure mode. */
+var ExposureModeSchema = _enum(["auto", "manual"]);
+/**
+* Backlight-compensation mode:
+*   - `off` — disabled
+*   - `blc` — backlight compensation
+*   - `wdr` — wide dynamic range
+*   - `hlc` — highlight compensation
+*/
+var BacklightModeSchema = _enum([
+	"off",
+	"blc",
+	"wdr",
+	"hlc"
+]);
+/** Normalized numeric range descriptor — `{ min, max, step }` per the
+*  getOptions availability convention. Slider values are normalized 0–100. */
+var NormalizedRangeSchema = object({
+	min: number(),
+	max: number(),
+	step: number()
+});
+object({
+	/** Normalized 0–100. */
+	brightness: number().optional(),
+	/** Normalized 0–100. */
+	contrast: number().optional(),
+	/** Normalized 0–100. */
+	saturation: number().optional(),
+	/** Normalized 0–100. */
+	sharpness: number().optional(),
+	mirror: boolean().optional(),
+	flip: boolean().optional(),
+	rotate: ImageRotateSchema.optional(),
+	whiteBalance: WhiteBalanceModeSchema.optional(),
+	/** Manual white-balance warmth, NORMALIZED 0–100. Meaningful only when `whiteBalance === 'manual'`. */
+	warmth: number().optional(),
+	exposureMode: ExposureModeSchema.optional(),
+	backlightMode: BacklightModeSchema.optional(),
+	lastFetchedAt: number()
+});
+/**
+* Per-camera availability descriptor — drives which controls the admin UI
+* renders. Booleans as `supportsX`; numeric ranges as `{ min, max, step }`
+* (the normalized 0–100 range); enums as arrays of supported values (empty
+* array → control hidden). A provider returns honest, camera-probed values
+* — never hardcoded.
+*/
+var ImageSettingsOptionsSchema = object({
+	supportsBrightness: boolean(),
+	brightness: NormalizedRangeSchema.optional(),
+	supportsContrast: boolean(),
+	contrast: NormalizedRangeSchema.optional(),
+	supportsSaturation: boolean(),
+	saturation: NormalizedRangeSchema.optional(),
+	supportsSharpness: boolean(),
+	sharpness: NormalizedRangeSchema.optional(),
+	supportsMirror: boolean(),
+	supportsFlip: boolean(),
+	/** Supported rotation values. Empty → rotation not configurable. */
+	rotateOptions: array(ImageRotateSchema),
+	/** Supported white-balance modes. Empty → white-balance not configurable. */
+	whiteBalanceModes: array(WhiteBalanceModeSchema),
+	supportsWarmth: boolean(),
+	/** Present when `supportsWarmth` — the normalized 0–100 range. */
+	warmth: NormalizedRangeSchema.optional(),
+	/** Supported exposure modes. Empty → exposure not configurable. */
+	exposureModes: array(ExposureModeSchema),
+	/** Supported backlight modes. Empty → backlight-compensation not configurable. */
+	backlightModes: array(BacklightModeSchema)
+});
+/**
+* Partial change to the image config — every field optional. Slider values
+* are normalized 0–100. A provider ignores fields it does not support.
+*/
+var ImageSettingsPatchSchema = object({
+	brightness: number().optional(),
+	contrast: number().optional(),
+	saturation: number().optional(),
+	sharpness: number().optional(),
+	mirror: boolean().optional(),
+	flip: boolean().optional(),
+	rotate: ImageRotateSchema.optional(),
+	whiteBalance: WhiteBalanceModeSchema.optional(),
+	warmth: number().optional(),
+	exposureMode: ExposureModeSchema.optional(),
+	backlightMode: BacklightModeSchema.optional()
+});
+DeviceType.Camera, method(object({ deviceId: number() }), ImageSettingsOptionsSchema), method(object({
+	deviceId: number(),
+	settings: ImageSettingsPatchSchema
+}), _void(), {
+	kind: "mutation",
+	auth: "admin"
+});
+/**
 * Robotic lawn-mower cap. Models HA `lawn_mower.*` entities — anything
 * with a mowing lifecycle plus a dock action.
 *
@@ -10948,6 +11165,16 @@ var RunnerCameraConfigSchema = object({
 	* this gate is bypassed.
 	*/
 	onboardMotionDrivesAnalyzer: boolean().default(true),
+	/**
+	* Master toggle for the occupancy re-check. When `false` (DEFAULT) the runner
+	* never arms the periodic recheck timer, regardless of `occupancyRecheckSec` —
+	* this is off by default because the recheck re-subscribes a detection session
+	* every N seconds while `watching`, a major source of pull-decoder re-dial
+	* churn (each cycle creates+tears a session → RTSP re-dial → latency). The
+	* `occupancyRecheckSec` / `occupancyRecheckFrames` sliders only take effect
+	* (and only render) when this is enabled.
+	*/
+	occupancyRecheckEnabled: boolean().default(false),
 	occupancyRecheckSec: number().min(occupancyRecheckSecField.min).max(occupancyRecheckSecField.max).default(occupancyRecheckSecField.default),
 	occupancyRecheckFrames: number().min(occupancyRecheckFramesField.min).max(occupancyRecheckFramesField.max).default(occupancyRecheckFramesField.default),
 	/**
@@ -12793,42 +13020,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(),
@@ -19331,6 +19595,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"dayNight.getOptions": {
+		capName: "day-night",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"dayNight.setSettings": {
+		capName: "day-night",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"decoder.createSession": {
 		capName: "decoder",
 		capScope: "system",
@@ -20261,6 +20537,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"imageSettings.getOptions": {
+		capName: "image-settings",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"imageSettings.setSettings": {
+		capName: "image-settings",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"integrations.create": {
 		capName: "integrations",
 		capScope: "system",
@@ -23039,6 +23327,71 @@ function rankDecodeHwAccels(preferred, supportedMethods) {
 	return candidates.sort((a, b) => decodeHwAccelRankIndex(a) - decodeHwAccelRankIndex(b));
 }
 //#endregion
+//#region src/shm-orphan-purge.ts
+/**
+* Startup reclamation of orphaned shared-memory segments.
+*
+* A decoder writes frames into named `/dev/shm` segments and unlinks each one
+* on graceful session teardown (`DecoderFrameRingSink.destroy`). When the
+* decoder process dies *ungracefully* — SIGBUS, OOM-kill, or a SIGKILL during
+* redeploy — that teardown never runs and the segment is orphaned: it stays in
+* the tmpfs forever, since nothing else knows its name. Across many
+* crashes/redeploys these accumulate until `/dev/shm` fills, at which point the
+* next `mmap` write faults with an uncatchable SIGBUS and the decoder
+* crash-loops into its circuit breaker (which is exactly the incident this
+* guards against).
+*
+* The reclamation is safe *at process startup*: a freshly-booting decoder owns
+* no live sessions, so every pre-existing segment with its prefix is by
+* definition an orphan from a dead instance. `shm_unlink` only removes the
+* name — any consumer still holding a mapping keeps reading valid memory until
+* it closes (POSIX deferred reclaim + the ring seqlock), so unlinking is safe
+* even if a stale reader is momentarily still attached.
+*
+* POSIX-only: segments surface as files under `/dev/shm` on Linux. On platforms
+* without that directory (Windows, macOS) the scan finds nothing — no-op.
+*
+* NOTE: this lives inside the decoder addon (not `@camstack/shm-ring`) so it
+* ships in the self-contained addon bundle via `camstack deploy`, reusing the
+* already-deployed `unlinkSegment`; no host base-image rebuild required.
+*/
+/** Default tmpfs directory where POSIX shared-memory segments appear on Linux. */
+var DEFAULT_SHM_DIR = "/dev/shm";
+/**
+* Unlink every shared-memory segment whose name starts with `prefix`.
+*
+* Intended to run ONCE at decoder startup, before any session is created, to
+* reclaim segments orphaned by a previously-crashed instance. A per-file unlink
+* failure is swallowed so one stuck segment cannot block reclaiming the rest.
+*/
+function purgeOrphanSegments(prefix, options = {}) {
+	const dir = options.dir ?? DEFAULT_SHM_DIR;
+	const unlink = options.unlink ?? unlinkSegment;
+	let entries;
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return {
+			scanned: 0,
+			removed: 0,
+			names: []
+		};
+	}
+	const names = [];
+	for (const name of entries) {
+		if (!name.startsWith(prefix)) continue;
+		try {
+			unlink(name);
+			names.push(name);
+		} catch {}
+	}
+	return {
+		scanned: entries.length,
+		removed: names.length,
+		names
+	};
+}
+//#endregion
 //#region src/shared/notifying-ring-buffer.ts
 /**
 * A {@link RingBuffer} that can notify a single blocked consumer the moment an
@@ -23224,6 +23577,36 @@ async function resolveDecoderBackend(api, nodeId, logger) {
 	return DEFAULT_DECODER_BACKEND;
 }
 //#endregion
+//#region src/pull-demuxer-options.ts
+/**
+* libav demuxer options for the node-av PULL decode path — RTP sources
+* (`isRtpSource()`) dialing the broker's RTSP restream (`rtsp://…/muted`).
+*
+* Without low-latency flags libav buffers up to `analyzeduration` (default
+* **5s**) of the live stream during `avformat_find_stream_info`, and that buffer
+* becomes a fixed ~5s offset on the decoded-frame timeline — detection overlays
+* then lag the WebRTC raw-RTP passthrough (which never decodes) by ~5s. Adding
+* `fflags: nobuffer` + a short `analyzeduration` collapses that offset to
+* sub-second, mirroring the ffmpeg backend's `-fflags +nobuffer` on its pull
+* path (decoder-ffmpeg/ffmpeg-args.ts).
+*
+* ‼ `analyzeduration`/`probesize` stay SMALL BUT NON-ZERO. Probe-zeroing
+* (`analyzeduration 0`) on the pull RTSP path STARVES the Reolink rfc4571
+* restream demuxer (garbage / zero frames — looked like a ~3000fps churn
+* runaway); that optimisation is push-mode-only. Keep them > 0.
+*/
+function buildPullDemuxerOptions() {
+	return {
+		rtsp_transport: "tcp",
+		fflags: "nobuffer",
+		analyzeduration: "1000000",
+		probesize: "1000000",
+		max_delay: "0",
+		reorder_queue_size: "0",
+		user_agent: "decoder"
+	};
+}
+//#endregion
 //#region src/scaler-geometry.ts
 /**
 * Decide the scaler action for an incoming frame's source geometry.
@@ -23246,6 +23629,49 @@ function resolveScalerAction(current, incoming) {
 * not hot-loop `Demuxer.open`.
 */
 var PULL_REDIAL_MS = 3e3;
+/**
+* Short re-dial backoff for the adaptive "drop-to-live" path. When the decoder
+* has fallen hopelessly behind the live edge ({@link DROP_TO_LIVE_LAG_MS}) the
+* loop tears the input down and re-dials fast so the restream's burst-prime
+* re-seats it at the live edge, instead of waiting the full {@link PULL_REDIAL_MS}
+* (which is for transient stream blips, not a deliberate re-seat).
+*/
+var PULL_FAST_REDIAL_MS = 250;
+/** Adaptive controller cadence — recompute emit-fps from lag at most this often. */
+var ADAPTIVE_TICK_MS = 1e3;
+/** Lag EWMA above this (ms) → halve the adaptive emit-fps. */
+var ADAPTIVE_LAG_HIGH_MS = 750;
+/** Lag EWMA below this (ms), sustained {@link ADAPTIVE_RECOVER_SUSTAIN_MS} → grow emit-fps. */
+var ADAPTIVE_LAG_LOW_MS = 250;
+/** How long lag must stay below {@link ADAPTIVE_LAG_LOW_MS} before growing emit-fps. */
+var ADAPTIVE_RECOVER_SUSTAIN_MS = 5e3;
+/** Floor the adaptive controller never sheds below (fps). */
+var ADAPTIVE_MIN_FPS = 2;
+/**
+* Ceiling the adaptive controller recovers toward when the subscriber requested
+* an UNLIMITED rate (`maxFps <= 0`). Source cameras run ≤ this, so the clamp is
+* a no-op in practice while keeping the /2 shed + *1.5 recover math bounded.
+*/
+var ADAPTIVE_FALLBACK_CEILING_FPS = 30;
+/**
+* Lag EWMA above this (ms) = hopelessly behind → drop-to-live re-seat.
+*
+* This bounds the MAX glass-to-box media staleness: `lagMsEwma` is how far the
+* decoder's media clock trails live, i.e. how old the *content* of an emitted
+* frame is (distinct from `frameAge`, which only measures decode→pick pipeline
+* delay and does NOT capture this media lag). On a host that decodes marginally
+* below real-time the lag sawtooths up to this ceiling, then re-seats to live —
+* so this constant directly caps how stale the boxes can get. 1200 ms (was
+* 2000) trades slightly more frequent 250 ms re-seats for fresher overlays; the
+* re-seat cost is negligible (~1.4 drops/cam/min at the observed drift). The
+* real fix — keeping decode at real-time so the lag never builds — is the
+* co-located / subprocess-decode epic.
+*/
+var DROP_TO_LIVE_LAG_MS = 1200;
+/** Never trigger drop-to-live more than once per this window (ms). */
+var DROP_TO_LIVE_MIN_INTERVAL_MS = 3e3;
+/** Decoder DEBUG facility flush cadence (~1Hz). */
+var DEBUG_FLUSH_MS = 1e3;
 /** Map our canonical backend name to the node-av `AV_HWDEVICE_TYPE_*` constant. */
 function backendToHwDeviceConst(backend, consts) {
 	switch (backend) {
@@ -23407,6 +23833,34 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 	scalerSrcFmt = -1;
 	lastEmitTime = 0;
 	minIntervalMs;
+	/** Gates {@link emitDebugFlash}; set from `config.debug === true`. Off = zero cost. */
+	debugEnabled;
+	/** Wall-clock of the last `decoder debug` flush — throttles the facility to ~1Hz. */
+	lastDebugFlush = 0;
+	/** `droppedFrames` snapshot at the last debug flush — window base for the drop delta. */
+	debugWindowDropped = 0;
+	/** Subscriber-requested emit ceiling (fps). `maxFps<=0` clamps to the fallback ceiling. */
+	ceilingFps;
+	/** Current lag-throttled emit rate (fps) — starts at the ceiling, floored at ADAPTIVE_MIN_FPS. */
+	adaptiveFps;
+	/** Frames actually emitted/sec over the last adaptive-tick window (feeds getStats + debug). */
+	effectiveFps = 0;
+	/** `outputFrames` snapshot at the last adaptive tick — window base for effective-fps. */
+	adaptiveWindowFrames = 0;
+	/** First sampled frame's pts (timebase units); `null` until the current dial seeds it. */
+	basePts = null;
+	/** Wall-clock at `basePts` — the real-time anchor for the drift computation. */
+	baseWall = 0;
+	/** EWMA of real-time drift (ms). Rising = decoder falling behind the live edge. */
+	lagMsEwma = 0;
+	/** Wall-clock the lag EWMA first dropped below ADAPTIVE_LAG_LOW_MS (0 = not low). */
+	lowLagSince = 0;
+	/** Wall-clock of the last adaptive-controller tick. */
+	lastAdaptiveCheck = 0;
+	/** Wall-clock of the last drop-to-live re-seat — rate-limits the re-dial. */
+	lastDropToLive = 0;
+	/** Set by drop-to-live so `runPullLoop` uses the SHORT re-dial backoff for one iteration. */
+	pullFastRedial = false;
 	inputPackets = 0;
 	outputFrames = 0;
 	droppedFrames = 0;
@@ -23441,6 +23895,9 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 		if (typeof config.tag === "string" && config.tag.length > 0) sessionTags["tag"] = config.tag;
 		this.logger = Object.keys(sessionTags).length > 0 ? logger.withTags(sessionTags) : logger;
 		this.minIntervalMs = config.maxFps > 0 ? 1e3 / config.maxFps : 0;
+		this.debugEnabled = config.debug === true;
+		this.ceilingFps = config.maxFps > 0 ? config.maxFps : ADAPTIVE_FALLBACK_CEILING_FPS;
+		this.adaptiveFps = this.ceilingFps;
 		this.outputMode = NodeAvDecoderSession.resolveOutputMode(config.outputFormat);
 		this.hwaccelPref = options?.hwaccel ?? "auto";
 		this.hwaccelResolver = options?.hwaccelResolver ?? null;
@@ -23755,7 +24212,9 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 				this.closePullInput();
 			}
 			if (this.destroyed || !this.pullActive) break;
-			await this.pullSleep(PULL_REDIAL_MS);
+			const backoffMs = this.pullFastRedial ? PULL_FAST_REDIAL_MS : PULL_REDIAL_MS;
+			this.pullFastRedial = false;
+			await this.pullSleep(backoffMs);
 		}
 	}
 	/**
@@ -23766,7 +24225,7 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 	* stream ends or the session is torn down.
 	*/
 	async pullDialAndDecode(nav, C, url) {
-		const demuxer = await nav.Demuxer.open(url, { options: { rtsp_transport: "tcp" } });
+		const demuxer = await nav.Demuxer.open(url, { options: buildPullDemuxerOptions() });
 		if (this.destroyed || !this.pullActive) {
 			demuxer[Symbol.dispose]?.();
 			return;
@@ -23776,7 +24235,8 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 		if (!videoStream) throw new Error("node-av decoder: pull input has no video stream");
 		const decoder = await nav.Decoder.create(videoStream, {
 			...this.pullHwContext ? { hardware: this.pullHwContext } : {},
-			rescale: { pixelFormat: C.AV_PIX_FMT_YUV420P }
+			rescale: { pixelFormat: C.AV_PIX_FMT_YUV420P },
+			exitOnError: false
 		});
 		if (this.destroyed || !this.pullActive) {
 			decoder[Symbol.dispose]?.();
@@ -23789,11 +24249,45 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 			hwAccel: this.activeHwAccel,
 			streamIndex: videoStream.index
 		} });
-		for await (const frame of decoder.frames(demuxer.packets(videoStream.index))) {
-			if (this.destroyed || !this.pullActive) break;
-			if (!frame) continue;
-			this.inputPackets++;
+		const probeTb = videoStream.timeBase;
+		const tbNum = probeTb?.num ?? 0;
+		const tbDen = probeTb?.den ?? 0;
+		this.resetLagTracker(Date.now());
+		await this.consumePullFrames(decoder.frames(demuxer.packets(videoStream.index)), tbNum, tbDen);
+	}
+	/**
+	* Consume decoded pull frames until the stream ends or the session is torn
+	* down. Each yielded frame is a node-av `Frame` — for the HW path a `clone`
+	* that refs a VAAPI surface + the decoder's whole `hw_frames_ctx`, so a SINGLE
+	* unfreed frame pins the dial's entire GPU surface pool (i915 GEM/shmem) until
+	* the process dies. Therefore EVERY exit path (teardown break, drop-to-live
+	* re-seat, normal emit, or a throw from the lag/emit calls) MUST `frame.free()`
+	* — the `try/finally` below is the single release point that guarantees it.
+	*
+	* Extracted from {@link pullDialAndDecode} so this free-on-all-paths contract
+	* is unit-testable with a stub async iterable (no live libav / GPU needed).
+	*/
+	async consumePullFrames(frames, tbNum, tbDen) {
+		for await (const frame of frames) {
+			if (!frame) {
+				if (this.destroyed || !this.pullActive) break;
+				continue;
+			}
 			try {
+				if (this.destroyed || !this.pullActive) break;
+				this.inputPackets++;
+				const wallNow = Date.now();
+				this.updateLagTracker(frame.pts, tbNum, tbDen, wallNow);
+				this.runAdaptiveController(wallNow);
+				this.emitDebugFlash(wallNow);
+				if (this.shouldDropToLive(wallNow)) {
+					this.logger.warn("node-av decoder: lag beyond recovery — dropping to live edge", { meta: {
+						lagMs: Math.round(this.lagMsEwma),
+						redialInMs: PULL_FAST_REDIAL_MS
+					} });
+					this.pullFastRedial = true;
+					break;
+				}
 				this.emitDecodedFrame(frame);
 			} finally {
 				frame.free();
@@ -23801,10 +24295,11 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 		}
 	}
 	/**
-	* Resolve and build the HW context for pull mode ONCE. Explicit backend →
-	* single try; `'auto'` → the kernel resolver's ordered list; no resolver →
-	* software. The first `HardwareContext.create` that succeeds wins; all
-	* failures fall through to software decode (`hardware: null`).
+	* Resolve and build the HW context for pull mode ONCE (reused across every
+	* re-dial, freed in `destroy`). Explicit backend → single try; `'auto'` → the
+	* kernel resolver's ordered list; no resolver → software. The first
+	* `HardwareContext.create` that succeeds wins; all failures fall through to
+	* software decode (`hardware: null`).
 	*/
 	async ensurePullHwContext(nav, C) {
 		if (this.hwaccelPref === "none") {
@@ -23824,7 +24319,7 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 			if (!deviceType) continue;
 			const hw = nav.HardwareContext.create(deviceType);
 			if (!hw) {
-				this.logger.warn("node-av: pull hwaccel context create failed — trying next", { meta: { backend } });
+				this.logger.debug("node-av: pull hwaccel context create failed — trying next", { meta: { backend } });
 				continue;
 			}
 			this.pullHwContext = hw;
@@ -23859,6 +24354,107 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 			}, ms);
 		});
 	}
+	/**
+	* Re-anchor the real-time lag tracker + per-dial controllers at the start of
+	* each dial. A fresh dial (including a drop-to-live re-seat) begins at the
+	* live edge, so the drift EWMA resets to 0 — otherwise the just-torn dial's
+	* accumulated lag would re-trigger drop-to-live immediately. The learned
+	* `adaptiveFps` is intentionally NOT reset: a re-seat should keep the shed
+	* emit-rate and recover from there once lag stays low.
+	*/
+	resetLagTracker(wallNow) {
+		this.basePts = null;
+		this.baseWall = 0;
+		this.lagMsEwma = 0;
+		this.lowLagSince = 0;
+		this.lastAdaptiveCheck = wallNow;
+		this.adaptiveWindowFrames = this.outputFrames;
+		this.lastDebugFlush = wallNow;
+		this.debugWindowDropped = this.droppedFrames;
+	}
+	/**
+	* Update the EWMA of the decoder's real-time drift from a decoded frame's
+	* pts. The first frame of a dial anchors `basePts`/`baseWall`; every later
+	* frame compares elapsed wall-clock against elapsed media time —
+	* `lagMs = wallElapsed - mediaElapsed`. A rising EWMA means the decoder is
+	* falling behind the live edge (wall time outrunning the media timeline).
+	*/
+	updateLagTracker(pts, tbNum, tbDen, wallNow) {
+		if (tbDen === 0) return;
+		if (this.basePts === null) {
+			this.basePts = pts;
+			this.baseWall = wallNow;
+			return;
+		}
+		const sample = wallNow - this.baseWall - Number(pts - this.basePts) * 1e3 * tbNum / tbDen;
+		this.lagMsEwma = .9 * this.lagMsEwma + .1 * sample;
+	}
+	/**
+	* Lag-driven adaptive emit-fps controller (P1), self-throttled to
+	* {@link ADAPTIVE_TICK_MS}. Under load (lag EWMA high) it halves the emit-fps
+	* — fewer frames transferred + GPU-scaled + emitted, so the decoder stays
+	* real-time instead of accumulating lag; once lag stays low for a sustained
+	* window it grows the emit-fps back toward the subscriber's ceiling.
+	* `minIntervalMs` (the throttle both emit paths honour) is recomputed from
+	* `adaptiveFps`, NOT the raw ceiling.
+	*/
+	runAdaptiveController(wallNow) {
+		const windowMs = wallNow - this.lastAdaptiveCheck;
+		if (windowMs < ADAPTIVE_TICK_MS) return;
+		this.lastAdaptiveCheck = wallNow;
+		const framesDelta = this.outputFrames - this.adaptiveWindowFrames;
+		this.adaptiveWindowFrames = this.outputFrames;
+		this.effectiveFps = windowMs > 0 ? framesDelta * 1e3 / windowMs : 0;
+		const lag = this.lagMsEwma;
+		if (lag > ADAPTIVE_LAG_HIGH_MS) {
+			this.adaptiveFps = Math.max(ADAPTIVE_MIN_FPS, this.adaptiveFps / 2);
+			this.lowLagSince = 0;
+		} else if (lag < ADAPTIVE_LAG_LOW_MS) {
+			if (this.lowLagSince === 0) this.lowLagSince = wallNow;
+			else if (wallNow - this.lowLagSince >= ADAPTIVE_RECOVER_SUSTAIN_MS) {
+				this.adaptiveFps = Math.min(this.ceilingFps, this.adaptiveFps * 1.5);
+				this.lowLagSince = wallNow;
+			}
+		} else this.lowLagSince = 0;
+		this.minIntervalMs = this.adaptiveFps > 0 ? 1e3 / this.adaptiveFps : 0;
+	}
+	/**
+	* Whether the decoder is hopelessly behind the live edge and should tear the
+	* input down for a fast re-seat. Rate-limited to at most once per
+	* {@link DROP_TO_LIVE_MIN_INTERVAL_MS} so a bad stretch can't hot-loop the
+	* dial. Records the trigger time as a side effect when it returns `true`.
+	*/
+	shouldDropToLive(wallNow) {
+		if (this.lagMsEwma <= DROP_TO_LIVE_LAG_MS) return false;
+		if (wallNow - this.lastDropToLive < DROP_TO_LIVE_MIN_INTERVAL_MS) return false;
+		this.lastDropToLive = wallNow;
+		return true;
+	}
+	/**
+	* Per-camera DEBUG facility (mirrors the stream-broker's `streamingDebug`
+	* gate). When `config.debug` is set, flush a single structured `decoder
+	* debug` line at ~1Hz — effective/adaptive fps, real-time lag, dropped-frame
+	* delta, avg decode time, hwaccel. `deviceId`/`tag` ride on the logger tags.
+	* Cheap: all values come from running counters, and the whole method is a
+	* no-op (one comparison) when debug is disabled or the window hasn't elapsed.
+	*/
+	emitDebugFlash(wallNow) {
+		if (!this.debugEnabled) return;
+		if (wallNow - this.lastDebugFlush < DEBUG_FLUSH_MS) return;
+		this.lastDebugFlush = wallNow;
+		const droppedDelta = this.droppedFrames - this.debugWindowDropped;
+		this.debugWindowDropped = this.droppedFrames;
+		const decodeMsAvg = this.outputFrames > 0 ? this.totalDecodeTimeMs / this.outputFrames : 0;
+		this.logger.info("decoder debug", { meta: {
+			effectiveFps: Number(this.effectiveFps.toFixed(1)),
+			adaptiveFps: Number(this.adaptiveFps.toFixed(1)),
+			ceilingFps: this.ceilingFps,
+			lagMs: Math.round(this.lagMsEwma),
+			droppedFrames: droppedDelta,
+			decodeMs: Number(decodeMsAvg.toFixed(2)),
+			hwAccel: this.activeHwAccel
+		} });
+	}
 	pushPacket(packet) {
 		if (this.destroyed) return;
 		if (this.pullActive) {
@@ -23915,6 +24511,10 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 	}
 	emitDecodedFrame(frame) {
 		const now = performance.now();
+		if (frame.isHwFrame()) {
+			this.droppedFrames++;
+			return;
+		}
 		if (this.minIntervalMs > 0 && now - this.lastEmitTime < this.minIntervalMs) {
 			this.droppedFrames++;
 			return;
@@ -24284,18 +24884,809 @@ var NodeAvDecoderSession = class NodeAvDecoderSession {
 	}
 	getStats() {
 		const uptimeSec = Math.max((Date.now() - this.startTime) / 1e3, 1);
-		return {
+		const base = {
 			inputFps: this.inputPackets / uptimeSec,
 			outputFps: this.outputFrames / uptimeSec,
 			avgDecodeTimeMs: this.outputFrames > 0 ? this.totalDecodeTimeMs / this.outputFrames : 0,
 			droppedFrames: this.droppedFrames
 		};
+		if (!this.pullActive) return base;
+		return {
+			...base,
+			lagMs: this.lagMsEwma,
+			effectiveFps: this.effectiveFps,
+			adaptiveFps: this.adaptiveFps
+		};
 	}
 	get isPullMode() {
 		return this.pullActive;
 	}
 };
 //#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 MAX_ENCODED_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);
+			if (s.encodedQueue.length > MAX_ENCODED_QUEUE_CHUNKS) s.encodedQueue.splice(0, s.encodedQueue.length - MAX_ENCODED_QUEUE_CHUNKS);
+		});
+	}
+	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 +25712,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 +25752,45 @@ 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 } });
+		const purged = purgeOrphanSegments(SEGMENT_NAME_PREFIX);
+		if (purged.removed > 0) this.ctx.logger.warn("node-av decoder: reclaimed orphaned shm segments at startup", { meta: {
+			removed: purged.removed,
+			scanned: purged.scanned
+		} });
 		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 +26036,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 +26056,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 };