@camstack/addon-decoder-nodeav 1.1.4 → 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),
 	/**
@@ -19368,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",
@@ -20298,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",
@@ -23076,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
@@ -23261,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.
@@ -23283,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) {
@@ -23444,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;
@@ -23478,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;
@@ -23792,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);
 		}
 	}
 	/**
@@ -23803,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;
@@ -23813,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]?.();
@@ -23826,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();
@@ -23838,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") {
@@ -23861,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;
@@ -23896,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) {
@@ -23952,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;
@@ -24321,12 +24884,19 @@ 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;
@@ -24836,6 +25406,7 @@ var NodeAvAudioEncodeSession = class {
 //#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;
@@ -25042,6 +25613,7 @@ var NodeAvAudioCodecProvider = class {
 			...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) {
@@ -25205,6 +25777,11 @@ var DecoderNodeAvAddon = class extends BaseAddon {
 			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) } });