@camstack/addon-pipeline 0.1.8

package/dist/decoder-nodeav/index.mjs

@@ -0,0 +1,907 @@
+import { randomUUID } from "node:crypto";
+import { errMsg, BaseAddon, DEFAULT_DECODER_HWACCEL_CONFIG, HWACCEL_OPTIONS, decoderCapability, RingBuffer } from "@camstack/types";
+function backendToHwDeviceConst(backend, consts) {
+  switch (backend) {
+    case "videotoolbox":
+      return consts.AV_HWDEVICE_TYPE_VIDEOTOOLBOX;
+    case "cuda":
+      return consts.AV_HWDEVICE_TYPE_CUDA;
+    case "nvdec":
+      return consts.AV_HWDEVICE_TYPE_CUDA;
+    // node-av exposes only CUDA; nvdec aliases to it
+    case "vaapi":
+      return consts.AV_HWDEVICE_TYPE_VAAPI;
+    case "qsv":
+      return consts.AV_HWDEVICE_TYPE_QSV;
+    case "d3d11va":
+      return consts.AV_HWDEVICE_TYPE_D3D11VA;
+    case "dxva2":
+      return consts.AV_HWDEVICE_TYPE_DXVA2;
+    case "amf":
+      return consts.AV_HWDEVICE_TYPE_AMF;
+    case "vdpau":
+      return consts.AV_HWDEVICE_TYPE_VDPAU;
+    case "drm":
+      return consts.AV_HWDEVICE_TYPE_DRM;
+    default:
+      return null;
+  }
+}
+function backendToHwPixFmt(backend, consts) {
+  switch (backend) {
+    case "videotoolbox":
+      return consts.AV_PIX_FMT_VIDEOTOOLBOX;
+    case "cuda":
+      return consts.AV_PIX_FMT_CUDA;
+    case "nvdec":
+      return consts.AV_PIX_FMT_CUDA;
+    case "vaapi":
+      return consts.AV_PIX_FMT_VAAPI;
+    case "qsv":
+      return consts.AV_PIX_FMT_QSV;
+    case "d3d11va":
+      return consts.AV_PIX_FMT_D3D11;
+    case "dxva2":
+      return consts.AV_PIX_FMT_DXVA2_VLD;
+    case "amf":
+      return consts.AV_PIX_FMT_D3D11;
+    case "vdpau":
+      return consts.AV_PIX_FMT_VDPAU;
+    case "drm":
+      return consts.AV_PIX_FMT_DRM_PRIME;
+    default:
+      return null;
+  }
+}
+let _nav = null;
+let _consts = null;
+let _sharp = null;
+async function getNodeAv() {
+  if (!_nav) _nav = await import("node-av");
+  return _nav;
+}
+async function getConstants() {
+  if (!_consts) _consts = await import("../index-UbcdLS7a.mjs");
+  return _consts;
+}
+async function getSharp() {
+  if (!_sharp) {
+    const mod = await import("sharp");
+    _sharp = mod.default;
+  }
+  return _sharp;
+}
+const noopLogger = {
+  debug() {
+  },
+  info() {
+  },
+  warn() {
+  },
+  error() {
+  },
+  child() {
+    return noopLogger;
+  },
+  withTags() {
+    return noopLogger;
+  }
+};
+class NodeAvDecoderSession {
+  config;
+  logger;
+  frameCallbacks = /* @__PURE__ */ new Set();
+  destroyed = false;
+  // Low-level node-av objects (initialized on first keyframe)
+  parser = null;
+  codecCtx = null;
+  scaler = null;
+  avPacket = null;
+  avFrame = null;
+  dstFrame = null;
+  // Cached constants (loaded during init, used in hot path)
+  // Hard-coded numeric defaults are replaced in initDecoder() with the real
+  // branded constants from `node-av/constants`. The `as` cast at the literal
+  // is a one-time branding bridge — once initDecoder runs we hold the exact
+  // AVPixelFormat/SwsFlags/AVError values.
+  EAGAIN = -11;
+  PIX_FMT_GRAY8 = 8;
+  PIX_FMT_RGB24 = 2;
+  SWS_FAST_BILINEAR = 1;
+  /**
+   * Decoder output mode. Drives both the scaler's destination pixel
+   * format and whether sharp runs the JPEG encode at the end:
+   *
+   * - `'jpeg'` — scaler→RGB24 → sharp encode → emit JPEG bytes
+   * - `'rgb'`  — scaler→RGB24 → emit raw RGB24 (no sharp)
+   * - `'gray'` — scaler→GRAY8 → emit raw GRAY8 (no sharp)
+   *
+   * The broker holds the policy decision on which mode to request based
+   * on its active subscribers; on-the-fly conversion (e.g. RGB→JPEG for
+   * a WebRTC consumer that joined while detection holds the decoder in
+   * RGB mode) happens broker-side via the per-frame conversion cache.
+   */
+  outputMode;
+  sharpFn = null;
+  /**
+   * Backpressure for the sharp JPEG encode pipeline. The broker
+   * currently creates sessions with `maxFps: 0` (unlimited) and relies
+   * on per-subscriber throttling, so without a bound the
+   * fire-and-forget `sharp(...).toBuffer()` chain would accumulate
+   * unboundedly whenever sharp falls behind the decoder. Cap at
+   * `MAX_JPEG_INFLIGHT` pending encodes per session — any frame that
+   * arrives while the cap is saturated is dropped and counted.
+   */
+  static MAX_JPEG_INFLIGHT = 2;
+  jpegEncodeInFlight = 0;
+  /**
+   * Map a `DecoderSessionConfig.outputFormat` value to one of the three
+   * native scaler/encoder modes the session understands. The cap-level
+   * format vocabulary is broader (it accepts `bgr`, `yuv420`) than what
+   * libav's scaler is wired for here — anything else degrades to RGB
+   * (the canonical raw mode) and the broker is expected to convert
+   * downstream if a subscriber needs a different shape.
+   */
+  static resolveOutputMode(format) {
+    if (format === "jpeg" || format === void 0) return "jpeg";
+    if (format === "gray") return "gray";
+    return "rgb";
+  }
+  initialized = false;
+  initializing = false;
+  scalerInitializing = false;
+  /**
+   * Monotonic counter incremented by `updateConfig` whenever the
+   * scaler + dstFrame get invalidated (e.g. output format toggle).
+   * `initScaler` captures the current value at entry and aborts — or
+   * disposes the locally-built scaler — if the epoch moved while
+   * its async init was in flight. Without this, a toggle racing an
+   * in-flight init could leave two scalers allocated natively while
+   * `this.scaler` only holds a reference to one → libav leak.
+   */
+  scalerEpoch = 0;
+  /**
+   * One-shot guard for the "first frame" diagnostic log + raw frame
+   * dump. Setting this synchronously inside `emitDecodedFrame`
+   * prevents re-entry — without it we were using `outputFrames === 0`
+   * which stays true until the async sharp encode callback runs, so
+   * several decoded frames could trigger the dump before the first
+   * JPEG landed.
+   */
+  firstFrameLogged = false;
+  // Output dimensions
+  outWidth = 0;
+  outHeight = 0;
+  // FPS limiter
+  lastEmitTime = 0;
+  minIntervalMs;
+  // Stats
+  inputPackets = 0;
+  outputFrames = 0;
+  droppedFrames = 0;
+  totalDecodeTimeMs = 0;
+  startTime = Date.now();
+  hwaccelPref;
+  hwaccelResolver;
+  /** The backend that actually initialised successfully — `'none'` = software fallback. */
+  activeHwAccel = "none";
+  hwDevice = null;
+  swTransferFrame = null;
+  constructor(config, logger = noopLogger, options) {
+    this.config = { ...config };
+    const sessionTags = {};
+    if (typeof config.deviceId === "number") sessionTags["deviceId"] = config.deviceId;
+    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.outputMode = NodeAvDecoderSession.resolveOutputMode(config.outputFormat);
+    this.hwaccelPref = options?.hwaccel ?? "auto";
+    this.hwaccelResolver = options?.hwaccelResolver ?? null;
+  }
+  /**
+   * Resolve the backend preference list and try each one against
+   * node-av's HW context APIs. The first backend whose
+   * `HardwareDeviceContext.create()` succeeds gets attached to
+   * `codecCtx.hwDeviceCtx` + its hw pixel format registered via
+   * `setHardwarePixelFormat`. On any failure, falls through to the
+   * next backend; if all fail, returns with `activeHwAccel='none'`
+   * and the decoder runs in software on the same context.
+   */
+  async tryAttachHwAccel(nav, C) {
+    if (!this.codecCtx) return;
+    if (this.hwaccelPref === "none") {
+      this.activeHwAccel = "none";
+      return;
+    }
+    const explicit = this.hwaccelPref === "auto" ? null : this.hwaccelPref;
+    const resolution = this.hwaccelResolver ? await this.hwaccelResolver.resolve(explicit) : explicit ? { preferred: [explicit], rationale: "explicit (no resolver)" } : { preferred: [], rationale: "auto + no resolver → software" };
+    if (resolution.preferred.length === 0) {
+      this.activeHwAccel = "none";
+      return;
+    }
+    for (const backend of resolution.preferred) {
+      const deviceType = backendToHwDeviceConst(backend, C);
+      const hwPixFmt = backendToHwPixFmt(backend, C);
+      if (!deviceType || !hwPixFmt) continue;
+      const device = new nav.HardwareDeviceContext();
+      const rc = device.create(deviceType);
+      if (rc < 0) {
+        this.logger.warn("node-av: hwaccel device create failed — trying next", {
+          meta: { backend, rc }
+        });
+        device.free();
+        continue;
+      }
+      try {
+        this.codecCtx.hwDeviceCtx = device;
+        this.codecCtx.setHardwarePixelFormat(hwPixFmt);
+      } catch (err) {
+        this.logger.warn("node-av: hwaccel context attach failed — trying next", {
+          meta: { backend, error: errMsg(err) }
+        });
+        device.free();
+        continue;
+      }
+      this.hwDevice = device;
+      this.activeHwAccel = backend;
+      return;
+    }
+    this.logger.warn("node-av: no hwaccel backend initialised — using software", {
+      meta: { attempted: resolution.preferred.join(","), rationale: resolution.rationale }
+    });
+    this.activeHwAccel = "none";
+  }
+  /**
+   * Download a HW frame (format == hw pix fmt) into a SW frame so the
+   * rest of the pipeline (scaler, JPEG encoder, grayscale passthrough)
+   * handles it identically to the pure-software path. Uses the sync
+   * variant so the synchronous receive loop below doesn't need to be
+   * async-ified. Returns `null` on transfer failure, meaning the
+   * caller should drop the frame.
+   */
+  transferHwFrame(hwFrame) {
+    if (this.activeHwAccel === "none" || !this.swTransferFrame) return hwFrame;
+    const rc = hwFrame.hwframeTransferDataSync(this.swTransferFrame, 0);
+    if (rc < 0) {
+      this.logger.warn("node-av: hwframeTransferData failed", { meta: { rc } });
+      return null;
+    }
+    return this.swTransferFrame;
+  }
+  /**
+   * Initialize the decoder pipeline on the first keyframe.
+   * After this returns, all hot-path methods are fully synchronous (except JPEG encode).
+   */
+  async initDecoder() {
+    if (this.initialized || this.initializing || this.destroyed) return;
+    this.initializing = true;
+    try {
+      const nav = await getNodeAv();
+      const C = await getConstants();
+      this.EAGAIN = C.AVERROR_EAGAIN;
+      this.PIX_FMT_GRAY8 = C.AV_PIX_FMT_GRAY8;
+      this.PIX_FMT_RGB24 = C.AV_PIX_FMT_RGB24;
+      this.SWS_FAST_BILINEAR = C.SWS_FAST_BILINEAR;
+      if (this.outputMode === "jpeg") {
+        this.sharpFn = await getSharp();
+      }
+      nav.Log.setLevel(C.AV_LOG_FATAL);
+      const isHevc = this.config.codec === "h265" || this.config.codec === "hevc";
+      const codecId = isHevc ? C.AV_CODEC_ID_HEVC : C.AV_CODEC_ID_H264;
+      this.parser = new nav.CodecParser();
+      this.parser.init(codecId);
+      const codec = nav.Codec.findDecoder(codecId);
+      if (!codec) {
+        this.logger.error("node-av: no decoder found", { meta: { codec: this.config.codec } });
+        return;
+      }
+      this.codecCtx = new nav.CodecContext();
+      this.codecCtx.allocContext3(codec);
+      if (this.config.width && this.config.height) {
+        this.codecCtx.width = this.config.width;
+        this.codecCtx.height = this.config.height;
+      }
+      this.codecCtx.threadCount = 1;
+      await this.tryAttachHwAccel(nav, C);
+      const ret = await this.codecCtx.open2(codec);
+      if (ret < 0) {
+        if (this.activeHwAccel !== "none") {
+          this.logger.warn("node-av: open2 failed with hwaccel — retrying in software", {
+            meta: { ret, hwAccel: this.activeHwAccel }
+          });
+          this.hwDevice?.free();
+          this.hwDevice = null;
+          this.activeHwAccel = "none";
+          this.codecCtx = new nav.CodecContext();
+          this.codecCtx.allocContext3(codec);
+          if (this.config.width && this.config.height) {
+            this.codecCtx.width = this.config.width;
+            this.codecCtx.height = this.config.height;
+          }
+          this.codecCtx.threadCount = 1;
+          const retry = await this.codecCtx.open2(codec);
+          if (retry < 0) {
+            this.logger.error("node-av: failed to open decoder (sw fallback)", { meta: { ret: retry } });
+            return;
+          }
+        } else {
+          this.logger.error("node-av: failed to open decoder", { meta: { ret } });
+          return;
+        }
+      }
+      if (this.activeHwAccel !== "none") {
+        this.swTransferFrame = new nav.Frame();
+        this.swTransferFrame.alloc();
+      }
+      this.avPacket = new nav.Packet();
+      this.avPacket.alloc();
+      this.avFrame = new nav.Frame();
+      this.avFrame.alloc();
+      this.initialized = true;
+      this.logger.info("node-av push decoder initialized", {
+        meta: {
+          codec: this.config.codec,
+          output: this.outputMode,
+          // Reports the backend that actually succeeded at
+          // `open2(codec)` with `hwDeviceCtx` attached, or `'none'` if
+          // we fell back to software (explicit `hwaccel: 'none'`
+          // override, empty resolver output, or every attempted
+          // backend failed init).
+          hwAccel: this.activeHwAccel
+        }
+      });
+    } catch (err) {
+      this.logger.error("node-av init error", { meta: { error: errMsg(err) } });
+    } finally {
+      this.initializing = false;
+    }
+  }
+  /**
+   * Initialize the scaler after the first frame tells us the actual
+   * dimensions. Output pixel format: RGB24 for JPEG encoding, GRAY8
+   * for raw motion.
+   *
+   * Builds `scaler` + `dstFrame` on local variables and publishes
+   * them onto `this` in a single atomic step at the end. Captures
+   * `scalerEpoch` at entry; if `updateConfig` invalidated the scaler
+   * while this init was in flight (epoch mismatch), the locally
+   * built pair is disposed and discarded so the later init wins.
+   * Without the local-first approach, partial state (scaler set,
+   * dstFrame still null) could be observed by a concurrent
+   * `emitDecodedFrame` call.
+   */
+  async initScaler(srcW, srcH, srcFmt) {
+    if (this.scalerInitializing) return;
+    this.scalerInitializing = true;
+    const myEpoch = this.scalerEpoch;
+    let localScaler = null;
+    let localDstFrame = null;
+    try {
+      const nav = await getNodeAv();
+      if (this.destroyed || myEpoch !== this.scalerEpoch) return;
+      const scale = this.config.scale > 1 ? this.config.scale : 1;
+      const maxW = Math.floor(640 / scale);
+      const outWidth = Math.min(srcW, maxW);
+      const outHeight = Math.round(outWidth * srcH / srcW);
+      const dstFmt = this.outputMode === "gray" ? this.PIX_FMT_GRAY8 : this.PIX_FMT_RGB24;
+      const fmtName = this.outputMode === "gray" ? "gray8" : "rgb24";
+      localScaler = new nav.SoftwareScaleContext();
+      localScaler.getContext(
+        srcW,
+        srcH,
+        srcFmt,
+        outWidth,
+        outHeight,
+        dstFmt,
+        this.SWS_FAST_BILINEAR
+      );
+      const ret = localScaler.initContext();
+      if (ret < 0) {
+        this.logger.error("node-av: sws_init_context failed", { meta: { ret } });
+        return;
+      }
+      localDstFrame = new nav.Frame();
+      localDstFrame.alloc();
+      localDstFrame.width = outWidth;
+      localDstFrame.height = outHeight;
+      localDstFrame.format = dstFmt;
+      const allocRet = localDstFrame.allocBuffer();
+      if (allocRet < 0) {
+        this.logger.error("node-av: dst frame allocBuffer failed", { meta: { ret: allocRet } });
+        return;
+      }
+      if (this.destroyed || myEpoch !== this.scalerEpoch) return;
+      this.scaler?.[Symbol.dispose]?.();
+      this.dstFrame?.[Symbol.dispose]?.();
+      this.scaler = localScaler;
+      this.dstFrame = localDstFrame;
+      this.outWidth = outWidth;
+      this.outHeight = outHeight;
+      localScaler = null;
+      localDstFrame = null;
+      this.logger.info("node-av scaler initialized", {
+        meta: { srcWidth: srcW, srcHeight: srcH, outWidth, outHeight, format: fmtName }
+      });
+    } catch (err) {
+      this.logger.error("Scaler init failed", { meta: { error: errMsg(err) } });
+    } finally {
+      localScaler?.[Symbol.dispose]?.();
+      localDstFrame?.[Symbol.dispose]?.();
+      this.scalerInitializing = false;
+    }
+  }
+  pushPacket(packet) {
+    if (this.destroyed) return;
+    this.inputPackets++;
+    if (!this.initialized && !this.initializing && packet.keyframe) {
+      this.initDecoder().then(() => {
+        if (this.initialized) this.decodeRawData(packet.data, packet.pts ?? Date.now());
+      }).catch((err) => {
+        this.logger.error("node-av init failed", { meta: { error: errMsg(err) } });
+      });
+      return;
+    }
+    if (!this.initialized) return;
+    this.decodeRawData(packet.data, packet.pts ?? Date.now());
+  }
+  decodeRawData(data, pts) {
+    if (!this.parser || !this.codecCtx || !this.avPacket || !this.avFrame) return;
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    const bigPts = BigInt(pts);
+    let offset = 0;
+    while (offset < buf.length) {
+      const remaining = buf.subarray(offset);
+      const consumed = this.parser.parse2(
+        this.codecCtx,
+        this.avPacket,
+        remaining,
+        bigPts,
+        bigPts,
+        offset
+      );
+      if (consumed < 0) {
+        this.logger.warn("node-av parser error", { meta: { ret: consumed } });
+        break;
+      }
+      offset += consumed;
+      if (this.avPacket.size > 0) {
+        this.decodePacket();
+        this.avPacket.unref();
+      }
+    }
+  }
+  decodePacket() {
+    if (!this.codecCtx || !this.avFrame) return;
+    const sendRet = this.codecCtx.sendPacketSync(this.avPacket);
+    if (sendRet < 0 && sendRet !== this.EAGAIN) {
+      this.logger.warn("node-av sendPacket error", { meta: { ret: sendRet } });
+      return;
+    }
+    while (true) {
+      const recvRet = this.codecCtx.receiveFrameSync(this.avFrame);
+      if (recvRet < 0) break;
+      const frame = this.transferHwFrame(this.avFrame);
+      if (!frame) continue;
+      this.emitDecodedFrame(frame);
+    }
+  }
+  emitDecodedFrame(frame) {
+    const now = performance.now();
+    if (this.minIntervalMs > 0 && now - this.lastEmitTime < this.minIntervalMs) {
+      this.droppedFrames++;
+      return;
+    }
+    if (!this.scaler && !this.scalerInitializing) {
+      this.initScaler(frame.width, frame.height, frame.format);
+      return;
+    }
+    if (!this.dstFrame || !this.scaler) return;
+    const decodeStart = performance.now();
+    try {
+      this.dstFrame.makeWritable();
+      this.scaler.scaleFrameSync(this.dstFrame, frame);
+    } catch (err) {
+      this.logger.warn("node-av scale error", { meta: { error: errMsg(err) } });
+      return;
+    }
+    if (!this.firstFrameLogged) {
+      this.firstFrameLogged = true;
+      const channels = this.outputMode === "gray" ? 1 : 3;
+      const ls = this.dstFrame.linesize;
+      const buf = this.dstFrame.toBuffer();
+      this.logger.info("dstFrame after scale", {
+        meta: {
+          phase: "frame-debug",
+          width: this.dstFrame.width,
+          height: this.dstFrame.height,
+          linesize: [ls[0], ls[1], ls[2]],
+          expectedStride: this.dstFrame.width * channels,
+          bufLen: buf.length,
+          expectedPacked: this.dstFrame.width * channels * this.dstFrame.height,
+          srcFormat: frame.format ?? "?"
+        }
+      });
+      if (this.outputMode !== "gray") {
+        import("node:fs").then((fsModule) => {
+          import("node:path").then((pathModule) => {
+            const dumpPath = pathModule.join(process.cwd(), "camstack-data", "debug-frame-rgb24.raw");
+            fsModule.writeFileSync(dumpPath, buf);
+            this.logger.info("Dumped first RGB24 frame", { meta: { phase: "frame-debug", path: dumpPath, bytes: buf.length } });
+          }).catch(() => {
+          });
+        }).catch(() => {
+        });
+      }
+    }
+    const rawBuf = this.extractPackedBuffer(this.dstFrame);
+    if (this.outputMode === "jpeg") {
+      this.encodeAndEmitJpeg(rawBuf, decodeStart);
+    } else if (this.outputMode === "rgb") {
+      this.emitRawFrame(rawBuf, "rgb", decodeStart);
+    } else {
+      this.emitRawFrame(rawBuf, "gray", decodeStart);
+    }
+  }
+  /**
+   * Extract packed pixel buffer from a decoded frame.
+   * FFmpeg's av_frame_get_buffer() may pad each row to alignment (32/64 bytes).
+   * Sharp and WASM consumers expect tightly-packed rows (stride = width * channels).
+   * If linesize matches expected stride, return the buffer directly (zero-copy).
+   */
+  extractPackedBuffer(frame) {
+    const channels = this.outputMode === "gray" ? 1 : 3;
+    const expectedStride = frame.width * channels;
+    const actualStride = frame.linesize[0] ?? expectedStride;
+    const src = frame.data?.[0];
+    if (!src) {
+      return frame.toBuffer();
+    }
+    if (actualStride === expectedStride) {
+      return Buffer.from(src.buffer, src.byteOffset, expectedStride * frame.height);
+    }
+    const dst = Buffer.allocUnsafe(expectedStride * frame.height);
+    for (let y = 0; y < frame.height; y++) {
+      src.copy(dst, y * expectedStride, y * actualStride, y * actualStride + expectedStride);
+    }
+    return dst;
+  }
+  /**
+   * Encode RGB24 raw buffer as JPEG and emit.
+   *
+   * Drops the frame (and counts it) when `MAX_JPEG_INFLIGHT` encodes
+   * are already pending — prevents unbounded growth of the
+   * fire-and-forget promise chain when sharp cannot keep up with the
+   * decode rate.
+   */
+  encodeAndEmitJpeg(rgb, decodeStart) {
+    if (!this.sharpFn) return;
+    if (this.jpegEncodeInFlight >= NodeAvDecoderSession.MAX_JPEG_INFLIGHT) {
+      this.droppedFrames++;
+      return;
+    }
+    this.jpegEncodeInFlight++;
+    this.sharpFn(rgb, {
+      raw: { width: this.outWidth, height: this.outHeight, channels: 3 }
+    }).jpeg({ quality: 80, mozjpeg: false }).toBuffer().then((jpegBuf) => {
+      if (this.destroyed) return;
+      this.emitRawFrame(jpegBuf, "jpeg", decodeStart);
+    }).catch((err) => {
+      this.logger.warn("sharp jpeg encode error", { meta: { error: errMsg(err) } });
+    }).finally(() => {
+      this.jpegEncodeInFlight--;
+    });
+  }
+  emitRawFrame(data, format, decodeStart) {
+    const decodeMs = performance.now() - decodeStart;
+    this.totalDecodeTimeMs += decodeMs;
+    this.outputFrames++;
+    this.lastEmitTime = performance.now();
+    if (this.outputFrames === 1 || this.outputFrames % 500 === 0) {
+      this.logger.info("node-av frame emitted", {
+        meta: {
+          frameNumber: this.outputFrames,
+          width: this.outWidth,
+          height: this.outHeight,
+          format,
+          decodeMs,
+          subs: this.frameCallbacks.size
+        }
+      });
+    }
+    const decodedFrame = {
+      data,
+      width: this.outWidth,
+      height: this.outHeight,
+      format,
+      timestamp: Date.now()
+    };
+    for (const cb of this.frameCallbacks) {
+      cb(decodedFrame);
+    }
+  }
+  onFrame(callback) {
+    this.frameCallbacks.add(callback);
+    return () => {
+      this.frameCallbacks.delete(callback);
+    };
+  }
+  updateConfig(update) {
+    const prevFormat = this.config.outputFormat;
+    this.config = { ...this.config, ...update };
+    if (update.maxFps !== void 0) {
+      this.minIntervalMs = update.maxFps > 0 ? 1e3 / update.maxFps : 0;
+    }
+    if (update.outputFormat !== void 0 && update.outputFormat !== prevFormat) {
+      const prevMode = this.outputMode;
+      this.outputMode = NodeAvDecoderSession.resolveOutputMode(update.outputFormat);
+      if (this.outputMode === prevMode) return;
+      this.scalerEpoch++;
+      if (this.scaler) {
+        this.scaler[Symbol.dispose]?.();
+        this.scaler = null;
+      }
+      if (this.dstFrame) {
+        this.dstFrame[Symbol.dispose]?.();
+        this.dstFrame = null;
+      }
+      if (this.outputMode === "jpeg" && !this.sharpFn) {
+        getSharp().then((fn) => {
+          this.sharpFn = fn;
+        }).catch(() => {
+        });
+      }
+      this.logger.info("node-av: output format changed — scaler will reinit", {
+        meta: { from: prevFormat, to: update.outputFormat, mode: this.outputMode }
+      });
+    }
+  }
+  async destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.frameCallbacks.clear();
+    this.dstFrame?.[Symbol.dispose]?.();
+    this.avFrame?.[Symbol.dispose]?.();
+    this.avPacket?.[Symbol.dispose]?.();
+    this.scaler?.[Symbol.dispose]?.();
+    this.parser?.[Symbol.dispose]?.();
+    this.swTransferFrame?.[Symbol.dispose]?.();
+    this.codecCtx?.[Symbol.dispose]?.();
+    this.hwDevice?.free();
+    this.dstFrame = null;
+    this.avFrame = null;
+    this.avPacket = null;
+    this.scaler = null;
+    this.parser = null;
+    this.codecCtx = null;
+    this.swTransferFrame = null;
+    this.hwDevice = null;
+  }
+  getStats() {
+    const uptimeSec = Math.max((Date.now() - this.startTime) / 1e3, 1);
+    return {
+      inputFps: this.inputPackets / uptimeSec,
+      outputFps: this.outputFrames / uptimeSec,
+      avgDecodeTimeMs: this.outputFrames > 0 ? this.totalDecodeTimeMs / this.outputFrames : 0,
+      droppedFrames: this.droppedFrames
+    };
+  }
+  get isPullMode() {
+    return false;
+  }
+}
+const FRAME_BUFFER_CAPACITY = 32;
+class DecoderNodeAvAddon extends BaseAddon {
+  sessions = /* @__PURE__ */ new Map();
+  frameBuffers = /* @__PURE__ */ new Map();
+  unsubscribers = /* @__PURE__ */ new Map();
+  sessionMeta = /* @__PURE__ */ new Map();
+  constructor() {
+    super(DEFAULT_DECODER_HWACCEL_CONFIG);
+  }
+  globalSettingsSchema() {
+    return this.schema({
+      sections: [{
+        id: "hwaccel",
+        title: "Hardware acceleration",
+        tab: "decoder",
+        description: 'Backend used by node-av decoder sessions. "Auto" defers to the probed best; concrete backends force it. Changes apply to NEW sessions — existing sessions keep the backend they were created with.',
+        fields: [
+          this.field({
+            type: "select",
+            key: "hwaccel",
+            label: "Preferred backend",
+            options: [...HWACCEL_OPTIONS],
+            default: "auto",
+            immediate: true
+          }),
+          this.field({
+            type: "text",
+            key: "probedBestHwaccel",
+            label: "Probed best",
+            description: "Auto-detected best decoder backend on this host. Click the refresh icon to re-run the probe.",
+            readonlyField: true,
+            default: "",
+            actions: [
+              { action: "reprobe-hwaccel", icon: "refresh-cw", tooltip: "Re-probe hwaccel" }
+            ]
+          })
+        ]
+      }]
+    });
+  }
+  async onInitialize() {
+    this.ctx.logger.info("node-av decoder addon initialized");
+    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 [{ capability: decoderCapability, provider: this }];
+  }
+  /**
+   * Resolve the effective hwaccel backend for a new session. Reads
+   * this addon's own `hwaccel` setting first. `'auto'` defers to the
+   * session's local resolver (`ctx.kernel.hwaccel`) which probes the
+   * host and picks. No more orchestrator round-trip — decoder addon
+   * is self-sufficient for this setting as of phase 2d.
+   */
+  resolveHwAccelPref() {
+    return this.config.hwaccel;
+  }
+  /**
+   * Re-run the platform probe on this host and persist the detected
+   * backend as `probedBestHwaccel`. The operator's `hwaccel` setting
+   * is intentionally left alone — the probe only updates the hint.
+   */
+  async reprobeHwaccel() {
+    const resolver = this.ctx.kernel.hwaccel;
+    if (!resolver) {
+      this.ctx.logger.warn("reprobeHwaccel: no kernel hwaccel resolver — returning none");
+      await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: "none" });
+      return { backend: "none" };
+    }
+    try {
+      const res = await resolver.resolve();
+      const backend = res.preferred[0] ?? "none";
+      await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: backend });
+      this.ctx.logger.info("reprobeHwaccel: wrote probedBestHwaccel", {
+        meta: { backend, rationale: res.rationale, preferred: res.preferred }
+      });
+      return { backend };
+    } catch (err) {
+      this.ctx.logger.warn("reprobeHwaccel failed", {
+        meta: { error: err instanceof Error ? err.message : String(err) }
+      });
+      await this.ctx.settings?.writeAddonStore({ probedBestHwaccel: "none" });
+      return { backend: "none" };
+    }
+  }
+  async supportsCodec(input) {
+    return ["h264", "h265", "hevc"].includes(input.codec.toLowerCase());
+  }
+  async getInfo() {
+    return {
+      id: "decoder-nodeav",
+      name: "Decoder (node-av)",
+      isPullMode: false,
+      priority: 10
+    };
+  }
+  async createSession(config) {
+    const sessionId = randomUUID();
+    const hwaccel = this.resolveHwAccelPref();
+    const session = new NodeAvDecoderSession(config, this.ctx.logger, {
+      hwaccel,
+      hwaccelResolver: this.ctx.kernel.hwaccel
+    });
+    const ringBuffer = new RingBuffer(FRAME_BUFFER_CAPACITY);
+    const unsub = session.onFrame((frame) => {
+      const { format } = frame;
+      if (format !== "jpeg" && format !== "rgb" && format !== "bgr" && format !== "yuv420" && format !== "gray") return;
+      const arrayBuf = new ArrayBuffer(frame.data.byteLength);
+      new Uint8Array(arrayBuf).set(frame.data);
+      const capData = new Uint8Array(arrayBuf);
+      const capFrame = {
+        data: capData,
+        width: frame.width,
+        height: frame.height,
+        format,
+        timestamp: frame.timestamp
+      };
+      ringBuffer.push(capFrame);
+    });
+    this.sessions.set(sessionId, session);
+    this.frameBuffers.set(sessionId, ringBuffer);
+    this.unsubscribers.set(sessionId, unsub);
+    this.sessionMeta.set(sessionId, {
+      codec: config.codec,
+      outputFormat: config.outputFormat,
+      createdAtMs: Date.now()
+    });
+    this.ctx.logger.info("node-av: created session", { meta: { sessionId, codec: config.codec, hwaccelPref: hwaccel } });
+    return { sessionId, nodeId: this.ctx.kernel.localNodeId ?? "local" };
+  }
+  async destroySession(input) {
+    const { sessionId } = input;
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`decoder-nodeav: unknown sessionId ${sessionId}`);
+    }
+    const unsub = this.unsubscribers.get(sessionId);
+    if (unsub) unsub();
+    await session.destroy();
+    this.sessions.delete(sessionId);
+    this.frameBuffers.delete(sessionId);
+    this.unsubscribers.delete(sessionId);
+    this.sessionMeta.delete(sessionId);
+    this.ctx.logger.info("node-av: destroyed session", { meta: { sessionId } });
+  }
+  async listActiveSessions() {
+    const out = [];
+    for (const [sessionId, meta] of this.sessionMeta) {
+      out.push({ sessionId, codec: meta.codec, outputFormat: meta.outputFormat, createdAtMs: meta.createdAtMs });
+    }
+    return out;
+  }
+  async pushPacket(input) {
+    const session = this.sessions.get(input.sessionId);
+    if (!session) {
+      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+    }
+    const rawData = input.packet.data;
+    const data = Buffer.isBuffer(rawData) ? rawData : rawData instanceof Uint8Array ? Buffer.from(rawData.buffer, rawData.byteOffset, rawData.byteLength) : Buffer.from(rawData);
+    session.pushPacket({ ...input.packet, data });
+  }
+  async openStream(input) {
+    const session = this.sessions.get(input.sessionId);
+    if (!session) {
+      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+    }
+    if (session.openStream) {
+      await session.openStream(input.url);
+    }
+  }
+  async pullFrames(input) {
+    const ringBuffer = this.frameBuffers.get(input.sessionId);
+    if (!ringBuffer) {
+      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+    }
+    return ringBuffer.drain(input.maxCount);
+  }
+  async updateConfig(input) {
+    const session = this.sessions.get(input.sessionId);
+    if (!session) {
+      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+    }
+    session.updateConfig(input.config);
+  }
+  async getStats(input) {
+    const session = this.sessions.get(input.sessionId);
+    if (!session) {
+      throw new Error(`decoder-nodeav: unknown sessionId ${input.sessionId}`);
+    }
+    return session.getStats();
+  }
+  async onShutdown() {
+    this.ctx.logger.info("node-av decoder addon shutdown — destroying all sessions");
+    const destroyPromises = [];
+    for (const [sessionId, session] of this.sessions) {
+      const unsub = this.unsubscribers.get(sessionId);
+      if (unsub) unsub();
+      destroyPromises.push(session.destroy());
+    }
+    await Promise.all(destroyPromises);
+    this.sessions.clear();
+    this.frameBuffers.clear();
+    this.unsubscribers.clear();
+    this.sessionMeta.clear();
+  }
+}
+export {
+  DecoderNodeAvAddon,
+  NodeAvDecoderSession,
+  DecoderNodeAvAddon as default
+};
+//# sourceMappingURL=index.mjs.map