@camstack/addon-pipeline 0.1.14 → 0.1.15

package/dist/stream-broker/index.mjs

@@ -1,8 +1,8 @@
-import { e as errMsg, J as maskUrlCredentials, R as RingBuffer, E as EventCategory, K as CAM_PROFILE_ORDER, L as DeviceFeature, B as BaseAddon, M as asJsonObject, N as streamBrokerCapability, O as cameraStreamsCapability, P as webrtcSessionCapability, Q as addonWidgetsSourceCapability, f as createEvent } from "../index-DKh0uEve.mjs";
-import * as net from "node:net";
-import net__default from "node:net";
+import { R as RingBuffer, e as errMsg, J as maskUrlCredentials, E as EventCategory, K as CAM_PROFILE_ORDER, L as DeviceFeature, B as BaseAddon, M as asJsonObject, N as streamBrokerCapability, O as cameraStreamsCapability, P as webrtcSessionCapability, Q as addonWidgetsSourceCapability, f as createEvent } from "../index-CVzLrojg.mjs";
 import * as crypto from "node:crypto";
 import crypto__default, { randomUUID, createHash, randomBytes } from "node:crypto";
+import * as net from "node:net";
+import net__default from "node:net";
 import { Socket } from "net";
 import { once } from "events";
 import { spawn } from "node:child_process";
@@ -31,6 +31,21 @@ class DecoderSessionProxy {
       if (frames.length === 0) await new Promise((r) => setTimeout(r, 1));
     }
   }
+  /**
+   * Poll a `frameSink: 'shm'` session for `FrameHandle`s (Phase 5 / D9).
+   * Mirrors `startPolling` but drains `pullHandles` — the decoder has
+   * already written the pixels into a shared-memory ring, so what crosses
+   * the cap boundary is the tiny serialisable handle. Runs until
+   * `stopPolling` or `destroy`.
+   */
+  async startHandlePolling(onHandle) {
+    this.polling = true;
+    while (this.polling) {
+      const handles = await this.api.pullHandles({ sessionId: this.sessionId, maxCount: 4 });
+      for (const handle of handles) onHandle(handle);
+      if (handles.length === 0) await new Promise((r) => setTimeout(r, 1));
+    }
+  }
   stopPolling() {
     this.polling = false;
   }
@@ -45,6 +60,462 @@ class DecoderSessionProxy {
     await this.api.destroySession({ sessionId: this.sessionId });
   }
 }
+const HANDLE_QUEUE_CAPACITY = 64;
+const DEFAULT_HINT_FPS = 5;
+const DECODE_FPS_WINDOW_MS = 2e3;
+class FrameHandlePlane {
+  decoderApi;
+  logger;
+  resolveStreamInfo;
+  subscriptions = /* @__PURE__ */ new Map();
+  sessions = /* @__PURE__ */ new Map();
+  disposed = false;
+  /** Re-entrancy guard for `armPendingSessions` — collapses the per-packet
+   *  `pushPacket` calls into a single in-flight deferred-arm pass. */
+  armInFlight = false;
+  /** Aggregate decoded-frame rate state — frames fanned out in the current
+   *  rolling window, the window's start epoch, and the last computed fps. */
+  framesInWindow = 0;
+  windowStartMs = Date.now();
+  decodedFps = 0;
+  constructor(options) {
+    this.decoderApi = options.decoderApi;
+    this.logger = options.logger;
+    this.resolveStreamInfo = options.resolveStreamInfo;
+  }
+  /** Number of active handle subscriptions — surfaced for diagnostics. */
+  get subscriberCount() {
+    return this.subscriptions.size;
+  }
+  /**
+   * Moleculer nodeIDs of the decoder providers currently hosting this plane's
+   * `frameSink: 'shm'` sessions. Used by the broker-manager's per-agent
+   * hwaccel-change handler to decide which brokers need a decoder rotation.
+   */
+  decoderNodeIds() {
+    const ids = [];
+    for (const session of this.sessions.values()) {
+      if (session.nodeId) ids.push(session.nodeId);
+    }
+    return ids;
+  }
+  /**
+   * Rotate every shm decoder session hosted on `agentNodeId` — destroy and
+   * rebuild it so the new session re-pulls the latest per-agent decoder
+   * preferences (hwaccel backend, …). Subscriptions are preserved: the same
+   * `subscriptionId`s read from the rebuilt session's fresh ring. A no-op for
+   * sessions on other nodes. Returns the number of sessions rotated.
+   */
+  async rotate(agentNodeId, reason) {
+    if (this.disposed) return 0;
+    let rotated = 0;
+    for (const session of this.sessions.values()) {
+      const sessionAgent = session.nodeId && session.nodeId.includes("/") ? session.nodeId.split("/")[0] : session.nodeId;
+      if (sessionAgent !== agentNodeId) continue;
+      this.logger?.info("frame-handle plane: rotating shm decoder session", {
+        meta: { format: session.format, reason, nodeId: session.nodeId }
+      });
+      await this.destroySession(session);
+      await this.startSessionDecoder(session);
+      rotated += 1;
+    }
+    return rotated;
+  }
+  /**
+   * Register a frame-handle subscription. Spins up (or reuses) a
+   * `frameSink: 'shm'` decoder session producing `format`. The returned
+   * `subscriptionId` is the handle the consumer passes to
+   * `pullFrameHandles` / `unsubscribe`.
+   */
+  async subscribe(input) {
+    if (this.disposed) {
+      throw new Error("FrameHandlePlane: subscribe after dispose");
+    }
+    const subscriptionId = `fh-${randomUUID()}`;
+    const maxFps = input.maxFps !== void 0 && input.maxFps > 0 ? input.maxFps : DEFAULT_HINT_FPS;
+    const subscription = {
+      id: subscriptionId,
+      format: input.format,
+      maxFps,
+      tag: input.tag ?? "unknown",
+      subscribedAt: Date.now(),
+      queue: new RingBuffer(HANDLE_QUEUE_CAPACITY),
+      framesDelivered: 0
+    };
+    this.subscriptions.set(subscriptionId, subscription);
+    await this.ensureSession(input.format, subscriptionId);
+    this.logger?.info("frame-handle subscription added", {
+      meta: { subscriptionId, format: input.format, tag: subscription.tag, maxFps }
+    });
+    return { subscriptionId, maxFps };
+  }
+  /**
+   * Drain up to `maxCount` `FrameHandle`s for a subscription, latest-wins.
+   * An unknown subscription id returns `[]` (the consumer may have been
+   * torn down concurrently).
+   */
+  pullHandles(subscriptionId, maxCount) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return [];
+    const handles = subscription.queue.drain(maxCount);
+    subscription.framesDelivered += handles.length;
+    return handles;
+  }
+  /**
+   * Release a subscription. When it was the last reader of its format the
+   * underlying decoder session is destroyed (and its shm segment unlinked
+   * by the decoder). Returns `true` when a known subscription was released.
+   */
+  async unsubscribe(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return false;
+    this.subscriptions.delete(subscriptionId);
+    const session = this.sessions.get(subscription.format);
+    if (session) {
+      session.subscriberIds.delete(subscriptionId);
+      if (session.subscriberIds.size === 0) {
+        this.sessions.delete(subscription.format);
+        await this.destroySession(session);
+      }
+    }
+    this.logger?.info("frame-handle subscription removed", {
+      meta: { subscriptionId, format: subscription.format }
+    });
+    return true;
+  }
+  /**
+   * Forward a video `EncodedPacket` to every active shm decoder session.
+   * Push-mode decoders consume this; a pull-mode decoder ignores it (it
+   * reads its own pipe via `openStream`). Audio packets are not forwarded.
+   *
+   * The packet feed doubles as the plane's stream-ready signal: the broker
+   * only calls `pushPacket` once it has a source and the first keyframe has
+   * landed — exactly the point `resolveStreamInfo` starts returning a
+   * descriptor. Each packet therefore triggers `armPendingSessions`, which
+   * re-attempts session creation for any deferred subscription so a lone
+   * first subscriber on a not-yet-started broker self-arms without a
+   * redundant re-`subscribe`.
+   */
+  pushPacket(packet) {
+    if (this.disposed || packet.type !== "video") return;
+    void this.armPendingSessions(packet).catch((err) => {
+      this.logger?.warn("frame-handle plane: arm pending sessions error", {
+        meta: { error: errMsg(err) }
+      });
+    });
+    this.feedSessions(packet);
+  }
+  /** Forward a video `EncodedPacket` to every live shm decoder session. */
+  feedSessions(packet) {
+    for (const session of this.sessions.values()) {
+      if (!session.proxy) continue;
+      session.proxy.pushPacket(packet).catch((err) => {
+        this.logger?.warn("frame-handle plane: decoder push error", {
+          meta: { format: session.format, error: errMsg(err) }
+        });
+      });
+    }
+  }
+  /**
+   * Re-attempt session creation for every subscription whose format has no
+   * live `FormatSession` yet — the subscriptions whose `startSessionDecoder`
+   * was deferred because the broker had no stream at `subscribe` time. Driven
+   * off the `pushPacket` feed (event-driven, no polling timer); a no-op once
+   * every subscribed format already owns a session.
+   *
+   * `armInFlight` collapses re-entrant calls: `pushPacket` fires per packet,
+   * but `ensureSession` is async — without the guard a burst of packets would
+   * launch overlapping decoder-creation round-trips for the same format.
+   *
+   * `triggerPacket` is the packet whose arrival armed the pass. Because
+   * `ensureSession` is async, the synchronous `feedSessions` in `pushPacket`
+   * runs before the session lands in `this.sessions` — so this method feeds
+   * the triggering packet to each session it just created, otherwise that
+   * first (keyframe-carrying) packet would be lost and a push-mode H264/H265
+   * decoder would stall waiting for SPS/PPS.
+   */
+  async armPendingSessions(triggerPacket) {
+    if (this.disposed || this.armInFlight) return;
+    const pending = /* @__PURE__ */ new Map();
+    for (const subscription of this.subscriptions.values()) {
+      if (this.sessions.has(subscription.format)) continue;
+      if (!pending.has(subscription.format)) {
+        pending.set(subscription.format, subscription.id);
+      }
+    }
+    if (pending.size === 0) return;
+    this.armInFlight = true;
+    try {
+      for (const [format, subscriptionId] of pending) {
+        if (this.disposed) return;
+        await this.ensureSession(format, subscriptionId);
+        const armed = this.sessions.get(format);
+        if (armed?.proxy) {
+          armed.proxy.pushPacket(triggerPacket).catch((err) => {
+            this.logger?.warn("frame-handle plane: decoder push error", {
+              meta: { format, error: errMsg(err) }
+            });
+          });
+        }
+      }
+    } finally {
+      this.armInFlight = false;
+    }
+  }
+  /**
+   * Aggregate decoded-frame rate across every `frameSink: 'shm'` session in
+   * this plane, frames/s. Each `fanoutHandle` call is one decoded frame
+   * delivered into the plane; the rate is recomputed over a rolling
+   * `DECODE_FPS_WINDOW_MS` window. Returns the last computed value between
+   * window rolls, and `0` while no session is producing.
+   */
+  decodeFps() {
+    this.rollDecodeFpsWindow();
+    return this.decodedFps;
+  }
+  /**
+   * Roll the decoded-fps window when it has elapsed: convert frames seen in
+   * the window into a per-second rate, then reset the counter. Called both
+   * on every fanout and on every `decodeFps()` read so a stalled session
+   * (no fanout) decays its rate to `0` rather than reporting a stale value.
+   */
+  rollDecodeFpsWindow() {
+    const now = Date.now();
+    const windowMs = now - this.windowStartMs;
+    if (windowMs < DECODE_FPS_WINDOW_MS) return;
+    this.decodedFps = this.framesInWindow / windowMs * 1e3;
+    this.framesInWindow = 0;
+    this.windowStartMs = now;
+  }
+  /** Diagnostic snapshot of every active frame-handle subscription. */
+  listSubscribers() {
+    return [...this.subscriptions.values()].map((s) => ({
+      tag: s.tag,
+      subscribedAt: s.subscribedAt,
+      maxFps: s.maxFps,
+      framesDelivered: s.framesDelivered
+    }));
+  }
+  /**
+   * Force-release every subscription whose tag matches `tag`. Returns the
+   * number released. Decoder sessions wind down when their last subscriber
+   * leaves, same as a normal `unsubscribe`.
+   */
+  async killByTag(tag) {
+    const victims = [...this.subscriptions.values()].filter((s) => s.tag === tag).map((s) => s.id);
+    for (const id of victims) {
+      await this.unsubscribe(id);
+    }
+    return victims.length;
+  }
+  /** Tear down every subscription + decoder session. Idempotent. */
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.subscriptions.clear();
+    const sessions = [...this.sessions.values()];
+    this.sessions.clear();
+    await Promise.all(sessions.map((s) => this.destroySession(s)));
+  }
+  // ── Internal ───────────────────────────────────────────────────────
+  /**
+   * Ensure a `frameSink: 'shm'` decoder session for `format` exists and add
+   * `subscriptionId` to its reader set. Reuses the session when one already
+   * runs for that format.
+   *
+   * When a session is created fresh, its reader set is seeded with EVERY
+   * subscription currently reading `format`, not just `subscriptionId` — a
+   * deferred-arm pass (`armPendingSessions`) may create the session long
+   * after several subscriptions of that format have registered, and the
+   * session is reference-counted by `subscriberIds`. Seeding only the one id
+   * would let an `unsubscribe` of that id tear the session down while its
+   * sibling subscriptions still read it.
+   */
+  async ensureSession(format, subscriptionId) {
+    const existing = this.sessions.get(format);
+    if (existing) {
+      existing.subscriberIds.add(subscriptionId);
+      return;
+    }
+    const subscriberIds = /* @__PURE__ */ new Set([subscriptionId]);
+    for (const subscription of this.subscriptions.values()) {
+      if (subscription.format === format) subscriberIds.add(subscription.id);
+    }
+    const session = {
+      format,
+      proxy: null,
+      nodeId: null,
+      subscriberIds
+    };
+    const started = await this.startSessionDecoder(session);
+    if (started) {
+      this.sessions.set(format, session);
+    }
+  }
+  /**
+   * Create the `frameSink: 'shm'` decoder for a `FormatSession` and start
+   * draining its handle queue. Mutates `session.proxy` / `session.nodeId` in
+   * place so a `rotate()` can rebuild a registered session without disturbing
+   * its `subscriberIds`. Returns `false` when no stream / unsupported codec
+   * means no decoder could be created.
+   */
+  async startSessionDecoder(session) {
+    const { format } = session;
+    const info = this.resolveStreamInfo();
+    if (!info) {
+      this.logger?.info("frame-handle plane: no stream — session deferred", {
+        meta: { format }
+      });
+      return false;
+    }
+    const supported = await this.decoderApi.supportsCodec({ codec: info.codec });
+    if (!supported) {
+      this.logger?.warn("frame-handle plane: codec unsupported — session skipped", {
+        meta: { format, codec: info.codec }
+      });
+      return false;
+    }
+    const { sessionId, nodeId } = await this.decoderApi.createSession({
+      codec: info.codec,
+      maxFps: 0,
+      outputFormat: format,
+      scale: 1,
+      frameSink: "shm",
+      ...info.numericDeviceId !== void 0 ? { deviceId: info.numericDeviceId } : {},
+      tag: `${info.tag}:shm:${format}`
+    });
+    const proxy = new DecoderSessionProxy(this.decoderApi, sessionId);
+    session.proxy = proxy;
+    session.nodeId = nodeId;
+    proxy.startHandlePolling((handle) => {
+      this.fanoutHandle(format, handle);
+    }).catch((err) => {
+      this.logger?.warn("frame-handle plane: handle polling error", {
+        meta: { format, error: errMsg(err) }
+      });
+    });
+    if (info.pullModeUrl) {
+      proxy.openStream(info.pullModeUrl).catch((err) => {
+        this.logger?.error("frame-handle plane: pull-mode openStream failed", {
+          meta: { format, error: errMsg(err) }
+        });
+      });
+    }
+    this.logger?.info("frame-handle plane: shm decoder session created", {
+      meta: { format, codec: info.codec, sessionId, nodeId }
+    });
+    return true;
+  }
+  /** Push one decoded `FrameHandle` to every subscription of `format`. */
+  fanoutHandle(format, handle) {
+    this.rollDecodeFpsWindow();
+    this.framesInWindow += 1;
+    for (const subscription of this.subscriptions.values()) {
+      if (subscription.format !== format) continue;
+      subscription.queue.push(handle);
+    }
+  }
+  /** Destroy a decoder session, swallowing teardown errors. */
+  async destroySession(session) {
+    const proxy = session.proxy;
+    session.proxy = null;
+    session.nodeId = null;
+    if (!proxy) return;
+    try {
+      await proxy.destroy();
+    } catch (err) {
+      this.logger?.warn("frame-handle plane: session destroy failed", {
+        meta: { format: session.format, error: errMsg(err) }
+      });
+    }
+  }
+}
+const AUDIO_QUEUE_CAPACITY = 64;
+class AudioChunkPlane {
+  logger;
+  subscriptions = /* @__PURE__ */ new Map();
+  constructor(logger) {
+    this.logger = logger;
+  }
+  /** Number of active audio-chunk subscriptions — surfaced as audio demand. */
+  get subscriberCount() {
+    return this.subscriptions.size;
+  }
+  /**
+   * Register an audio-chunk subscription. The returned `subscriptionId` is
+   * the handle the consumer passes to `pull` / `unsubscribe`.
+   */
+  subscribe(input) {
+    const subscriptionId = `ac-${randomUUID()}`;
+    const subscription = {
+      id: subscriptionId,
+      tag: input?.tag ?? "unknown",
+      subscribedAt: Date.now(),
+      queue: new RingBuffer(AUDIO_QUEUE_CAPACITY),
+      chunksDelivered: 0
+    };
+    this.subscriptions.set(subscriptionId, subscription);
+    this.logger?.info("audio-chunk subscription added", {
+      meta: { subscriptionId, tag: subscription.tag }
+    });
+    return { subscriptionId };
+  }
+  /**
+   * Drain up to `maxCount` `DecodedAudioChunk`s for a subscription, in FIFO
+   * arrival order. An unknown subscription id returns `[]` (the consumer may
+   * have been torn down concurrently).
+   */
+  pull(subscriptionId, maxCount) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return [];
+    const chunks = subscription.queue.drain(maxCount);
+    subscription.chunksDelivered += chunks.length;
+    return chunks;
+  }
+  /** Release a subscription. Returns `true` when a known subscription was released. */
+  unsubscribe(subscriptionId) {
+    const existed = this.subscriptions.delete(subscriptionId);
+    if (existed) {
+      this.logger?.info("audio-chunk subscription removed", {
+        meta: { subscriptionId }
+      });
+    }
+    return existed;
+  }
+  /**
+   * Fan one decoded `DecodedAudioChunk` into every active subscription's FIFO
+   * queue. A full queue drops its oldest chunk (bounded safety valve for a
+   * stalled consumer). No-op when there are no subscriptions.
+   */
+  fanout(chunk) {
+    for (const subscription of this.subscriptions.values()) {
+      subscription.queue.push(chunk);
+    }
+  }
+  /** Diagnostic snapshot of every active audio-chunk subscription. */
+  listSubscribers() {
+    return [...this.subscriptions.values()].map((s) => ({
+      tag: s.tag,
+      subscribedAt: s.subscribedAt,
+      chunksDelivered: s.chunksDelivered
+    }));
+  }
+  /**
+   * Force-release every subscription whose tag matches `tag`. Returns the
+   * number released.
+   */
+  killByTag(tag) {
+    const victims = [...this.subscriptions.values()].filter((s) => s.tag === tag).map((s) => s.id);
+    for (const id of victims) {
+      this.subscriptions.delete(id);
+    }
+    return victims.length;
+  }
+  /** Tear down every subscription. Idempotent. */
+  dispose() {
+    this.subscriptions.clear();
+  }
+}
 const SAMPLERATE_TABLE = [
   96e3,
   88200,
@@ -434,25 +905,6 @@ class AudioCodecSession {
     });
   }
 }
-class FrameDropper {
-  intervalMs;
-  lastPassedAt = -Infinity;
-  constructor(maxFps) {
-    this.intervalMs = maxFps > 0 ? 1e3 / maxFps : 0;
-  }
-  shouldKeep() {
-    if (this.intervalMs === 0) return true;
-    const now = Date.now();
-    if (now - this.lastPassedAt >= this.intervalMs) {
-      this.lastPassedAt = now;
-      return true;
-    }
-    return false;
-  }
-  setMaxFps(maxFps) {
-    this.intervalMs = maxFps > 0 ? 1e3 / maxFps : 0;
-  }
-}
 const MAX_WRITE_BUFFER_BYTES = 2 * 1024 * 1024;
 class StreamPipeServer {
   server;
@@ -3144,27 +3596,8 @@ function getPlaceholderFrame(kind, codec) {
   codecCache[kind] = buf;
   return buf;
 }
-let cachedSharp = null;
-async function getSharp() {
-  if (cachedSharp) return cachedSharp;
-  const mod = await import("sharp");
-  cachedSharp = mod.default;
-  return cachedSharp;
-}
-function swapRedBlue(rgb) {
-  const out = Buffer.allocUnsafe(rgb.length);
-  for (let i = 0; i + 2 < rgb.length; i += 3) {
-    out[i] = rgb[i + 2];
-    out[i + 1] = rgb[i + 1];
-    out[i + 2] = rgb[i];
-  }
-  return out;
-}
-const DEFAULT_MAX_FPS = 5;
-const DEFAULT_SCALE = 1;
 const INITIAL_RECONNECT_DELAY_MS = 1e3;
 const MAX_RECONNECT_DELAY_MS = 3e4;
-const DECODER_TEARDOWN_GRACE_MS = 2e3;
 const SUSPEND_GRACE_MS = 5e3;
 const PUSH_STALL_TIMEOUT_MS = 15e3;
 class StreamBroker {
@@ -3204,17 +3637,13 @@ class StreamBroker {
   lastRefreshRequestAt = 0;
   /** Detected or configured codec — persists across reconnects */
   detectedCodec;
-  decoderProxy = null;
-  /** Current output format of the shared decoder session. */
-  decoderOutputFormat = null;
   /**
-   * Moleculer nodeID of the decoder provider currently hosting
-   * `decoderProxy`. Set from the `{ nodeId }` returned by
-   * `decoderApi.createSession`; used by the broker-manager's
-   * hwaccel-change subscription to decide which brokers need a forced
-   * decoder rotation. Null when no shared decoder session exists.
+   * The shared-memory frame-handle surface (Phase 5 / D9) — the broker's sole
+   * decoded-frame path. Lazily created on the first `subscribeFrameHandles`
+   * call; owns the per-format `frameSink: 'shm'` decoder sessions a handle
+   * consumer reads from. `null` until a consumer subscribes.
    */
-  decoderNodeId = null;
+  frameHandlePlane = null;
   decoderApi;
   audioCodecApi;
   logger;
@@ -3265,7 +3694,6 @@ class StreamBroker {
   static FIRST_VIDEO_TIMEOUT_MS = 8e3;
   manualStop = false;
   stopping = false;
-  decoderTeardownTimer;
   restreamers = [];
   pipeServer;
   rtspRestreamer;
@@ -3300,19 +3728,20 @@ class StreamBroker {
    * quiet unless an operator explicitly enables debug for one device.
    */
   streamingDebug = false;
-  decodedSubscribers = /* @__PURE__ */ new Map();
-  audioSubscribers = /* @__PURE__ */ new Map();
-  /** Stored options from first onDecodedFrame call when codec was not yet known */
-  pendingDecodeOptions;
-  /** Pull mode decoder needs to wait for the first keyframe before opening */
-  pendingPullModeOpen = null;
+  /**
+   * Decoded audio-chunk plane (Phase 5 / D9) — the poll-based, tRPC-reachable
+   * replacement for the live-object `onDecodedAudioChunk` callback path.
+   * Holds the per-subscription FIFO chunk queues. Assigned in the constructor
+   * so it gets a scoped logger child.
+   */
+  audioChunkPlane;
+  /**
+   * Gate for feeding encoded packets to the decoder: H.264/H.265 decoders
+   * need the SPS/PPS carried in the first keyframe to initialise, so the
+   * broker withholds packets from the shm frame plane until the first
+   * keyframe arrives.
+   */
   firstKeyframeReceived = false;
-  /** Retry handle for "no decoder provider yet" — addons register in
-   *  arbitrary order, the broker must wait rather than fail. Cancelled
-   *  on decoder attach or broker destroy. */
-  decoderResolveRetryTimer;
-  /** Attempt counter for the retry loop above — feeds bounded backoff. */
-  decoderResolveAttempts = 0;
   /** Timer for push-mode stall detection. */
   pushStallTimer;
   /** Whether pre-buffer counts as demand (keeps the stream alive even with 0 subscribers). */
@@ -3321,15 +3750,10 @@ class StreamBroker {
   suspendTimer;
   /** True while the stream is suspended (ffmpeg killed, no RTSP connection). */
   _suspended = false;
-  /** Debug counters for decoder troubleshooting */
-  decoderPushCount = 0;
-  decoderFrameCount = 0;
   /** Counter for video RTP packets — drives the milestone diagnostic
    *  log alongside `audioRtpSeen`, so a wake-up cycle that brings audio
    *  back but never video is observable from the structured logs. */
   videoRtpSeen = 0;
-  /** Cached decoder stats — updated by the polling loop, read synchronously by getStats(). */
-  cachedDecoderStats;
   /** Tracking flags set synchronously by the RTP depacketizer callback. */
   _lastNalKeyframe = false;
   _lastNalParamSet = false;
@@ -3362,6 +3786,7 @@ class StreamBroker {
     this.rtspRestreamer = new RtspRestreamer(deviceId);
     if (logger) this.rtspRestreamer.setLogger(logger.child("rtsp"));
     this.preBuffer = new EncodedRingBuffer(StreamBroker.DEFAULT_PRE_BUFFER_SEC);
+    this.audioChunkPlane = new AudioChunkPlane(logger?.child("audio-chunk-plane"));
     this.rtspRestreamer.onSessionCountChanged(() => this.checkDemand());
     this.pipeServer.onClientCountChanged(() => this.checkDemand());
   }
@@ -3533,10 +3958,6 @@ class StreamBroker {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = void 0;
     }
-    if (this.decoderTeardownTimer) {
-      clearTimeout(this.decoderTeardownTimer);
-      this.decoderTeardownTimer = void 0;
-    }
     if (this.suspendTimer) {
       clearTimeout(this.suspendTimer);
       this.suspendTimer = void 0;
@@ -3545,18 +3966,18 @@ class StreamBroker {
       clearTimeout(this.pushStallTimer);
       this.pushStallTimer = void 0;
     }
-    if (this.decoderProxy) {
-      await this.destroyDecoder();
+    if (this.frameHandlePlane) {
+      const plane = this.frameHandlePlane;
+      this.frameHandlePlane = null;
+      await plane.dispose();
     }
     await this.pipeServer.stop();
     this.rtspRestreamer.destroy();
     this.preBuffer.clear();
     this.pendingParamNals = [];
-    this.pendingPullModeOpen = null;
     this.firstKeyframeReceived = false;
     this.encodedCallbacks.clear();
-    this.decodedSubscribers.clear();
-    this.audioSubscribers.clear();
+    this.audioChunkPlane.dispose();
   }
   // ── Auto-suspend / resume ─────────────────────────────────────────────
   /** Whether the broker is currently suspended (idle, no RTSP connection). */
@@ -3572,8 +3993,8 @@ class StreamBroker {
   hasDemand() {
     if (this.encodedCallbacks.size > 0) return true;
     if (this.rtpVideoCallbacks.size > 0) return true;
-    if (this.decodedSubscribers.size > 0) return true;
-    if (this.audioSubscribers.size > 0) return true;
+    if ((this.frameHandlePlane?.subscriberCount ?? 0) > 0) return true;
+    if (this.audioChunkPlane.subscriberCount > 0) return true;
     if (this.rtspRestreamer.getSessionCount() > 0) return true;
     if (this.pipeServer.getClientCount() > 0) return true;
     if (this._preBufferEnabled && this.preBuffer.getDuration() > 0) return true;
@@ -3583,160 +4004,6 @@ class StreamBroker {
    * Check demand and schedule suspend/resume. Called after every subscriber
    * add/remove and after pre-buffer enable/disable.
    */
-  /**
-   * Pick the decoder's native output format given the current subscriber
-   * mix. Phase 3 collapsed three concerns into this one decision:
-   *
-   *   1. Avoid wasted CPU when subscribers are homogeneous — `gray`-
-   *      only stays `gray` (motion-only camera), `jpeg`-only stays
-   *      `jpeg` (no detection consumer joined yet, broker doesn't have
-   *      to encode either).
-   *   2. Pick the cheapest *canonical* mode for mixed subscribers —
-   *      `rgb` is the universal source for the broker-side conversion
-   *      cache: gray is one luminance pass, jpeg is one sharp encode,
-   *      bgr is a channel swap. Producing JPEG decoder-side and then
-   *      *decoding back* to feed a raw consumer would cost more than
-   *      both consumers combined.
-   *   3. Stay stable when there are no subscribers — defaults to
-   *      `jpeg` so the legacy "no subscriber yet" code path keeps
-   *      behaving as it did pre-refactor.
-   */
-  resolveDecoderFormat() {
-    if (this.decodedSubscribers.size === 0) return "jpeg";
-    let allGray = true;
-    let allJpeg = true;
-    for (const sub of this.decodedSubscribers.values()) {
-      if (sub.format !== "gray") allGray = false;
-      if (sub.format !== "jpeg") allJpeg = false;
-    }
-    if (allGray) return "gray";
-    if (allJpeg) return "jpeg";
-    return "rgb";
-  }
-  /**
-   * Check if the decoder's output format needs upgrading because a new
-   * subscriber requires a richer format (e.g. gray → jpeg when detection
-   * joins after motion). Calls updateConfig on the decoder proxy to
-   * reinitialize the scaler without recreating the session.
-   */
-  maybeUpgradeDecoderFormat() {
-    if (!this.decoderProxy || !this.decoderOutputFormat) return;
-    const needed = this.resolveDecoderFormat();
-    if (needed === this.decoderOutputFormat) return;
-    this.logger?.info("upgrading decoder output format", {
-      meta: { from: this.decoderOutputFormat, to: needed }
-    });
-    this.decoderOutputFormat = needed;
-    this.decoderProxy.updateConfig({ outputFormat: needed }).catch((err) => {
-      this.logger?.warn("decoder format upgrade failed", { meta: { error: errMsg(err) } });
-    });
-  }
-  /**
-   * Fan a single decoded frame out to every active subscriber. Each
-   * subscriber may have requested a different `format` than the one the
-   * decoder is currently producing — the per-frame `convertedCache` map
-   * memoises any format the decoder didn't already supply, so multiple
-   * subscribers asking for the same target share the conversion.
-   *
-   * Conversion paths covered today:
-   *   - rgb → jpeg (sharp encode)
-   *   - rgb → bgr  (R/B channel swap, in-process)
-   *   - rgb → gray (BT.601 luminance)
-   *   - rgb → yuv420 (sharp toFormat)
-   *   - gray → jpeg (sharp encode 1ch)
-   *   - jpeg → rgb / bgr / gray / yuv420 — not supported in Phase 3.
-   *     Decoder picks `jpeg` as canonical only when ALL subscribers
-   *     want jpeg, so this branch should never trigger. Such a request
-   *     is logged and the subscriber receives the JPEG passthrough as a
-   *     graceful fallback (caller is expected to re-decode).
-   */
-  fanoutDecodedFrame(frame) {
-    const convertedCache = /* @__PURE__ */ new Map();
-    convertedCache.set(frame.format, frame);
-    for (const subscriber of this.decodedSubscribers.values()) {
-      if (!subscriber.frameDropper.shouldKeep()) {
-        subscriber.framesDropped++;
-        continue;
-      }
-      this.deliverConvertedFrame(subscriber, frame, convertedCache);
-    }
-  }
-  deliverConvertedFrame(subscriber, frame, cache2) {
-    if (subscriber.format === frame.format) {
-      subscriber.callback(frame);
-      subscriber.framesDelivered++;
-      return;
-    }
-    const cached = cache2.get(subscriber.format);
-    if (cached && !(cached instanceof Promise)) {
-      subscriber.callback(cached);
-      subscriber.framesDelivered++;
-      return;
-    }
-    if (cached instanceof Promise) {
-      cached.then((converted) => {
-        subscriber.callback(converted);
-        subscriber.framesDelivered++;
-      }).catch((err) => {
-        subscriber.framesDropped++;
-        this.logger?.warn("frame conversion failed", {
-          meta: { tag: subscriber.tag, target: subscriber.format, error: errMsg(err) }
-        });
-      });
-      return;
-    }
-    const conversion = this.convertFrame(frame, subscriber.format);
-    cache2.set(subscriber.format, conversion);
-    conversion.then((converted) => {
-      cache2.set(subscriber.format, converted);
-      subscriber.callback(converted);
-      subscriber.framesDelivered++;
-    }).catch((err) => {
-      subscriber.framesDropped++;
-      this.logger?.warn("frame conversion failed", {
-        meta: { tag: subscriber.tag, target: subscriber.format, error: errMsg(err) }
-      });
-    });
-  }
-  async convertFrame(source, target) {
-    if (source.format === target) return source;
-    const sharp = await getSharp();
-    if (source.format === "rgb" || source.format === "gray") {
-      const channels = source.format === "gray" ? 1 : 3;
-      const raw = { width: source.width, height: source.height, channels };
-      const pipeline = sharp(source.data, { raw });
-      if (target === "jpeg") {
-        const data = await pipeline.jpeg({ quality: 80, mozjpeg: false }).toBuffer();
-        return { ...source, data, format: "jpeg" };
-      }
-      if (target === "bgr") {
-        if (source.format !== "rgb") {
-          throw new Error(`bgr conversion requires rgb source, got ${source.format}`);
-        }
-        const data = swapRedBlue(source.data);
-        return { ...source, data, format: "bgr" };
-      }
-      if (target === "gray") {
-        const data = await pipeline.toColorspace("b-w").raw().toBuffer();
-        return { ...source, data, format: "gray" };
-      }
-      if (target === "rgb") {
-        const data = await pipeline.toColorspace("srgb").raw().toBuffer();
-        return { ...source, data, format: "rgb" };
-      }
-      if (target === "yuv420") {
-        const data = await pipeline.toColorspace("yuv").raw().toBuffer();
-        return { ...source, data, format: "yuv420" };
-      }
-    }
-    if (source.format === "jpeg") {
-      this.logger?.warn("jpeg-source frame requested as non-jpeg — passthrough", {
-        meta: { target }
-      });
-      return source;
-    }
-    throw new Error(`unsupported conversion ${source.format} → ${target}`);
-  }
   checkDemand() {
     if (this.manualStop || this.stopping) return;
     if (this.hasDemand()) {
@@ -3922,10 +4189,6 @@ class StreamBroker {
       if (!this.firstKeyframeReceived && packet.keyframe) {
         this.firstKeyframeReceived = true;
         this.logger?.info("First keyframe received — decoder can start");
-        if (this.pendingPullModeOpen) {
-          this.pendingPullModeOpen();
-          this.pendingPullModeOpen = null;
-        }
       }
     }
     for (const restreamer of this.restreamers) {
@@ -3933,22 +4196,7 @@ class StreamBroker {
       restreamer.pushPacket(streamId, packet);
     }
     if (packet.type === "video" && this.firstKeyframeReceived) {
-      if (this.decoderProxy) {
-        this.decoderPushCount++;
-        if (this.decoderPushCount === 1 || this.decoderPushCount % 500 === 0) {
-          this.logger?.info("decoder push", {
-            meta: {
-              pushCount: this.decoderPushCount,
-              size: packet.data.length,
-              keyframe: packet.keyframe,
-              decodedCount: this.decoderFrameCount
-            }
-          });
-        }
-        this.decoderProxy.pushPacket(packet).catch((err) => {
-          this.logger?.warn("decoder push error", { meta: { error: errMsg(err) } });
-        });
-      }
+      this.frameHandlePlane?.pushPacket(packet);
     }
   }
   onEncodedData(callback) {
@@ -4120,89 +4368,107 @@ class StreamBroker {
   setStreamingDebug(enabled) {
     this.streamingDebug = enabled;
   }
-  onDecodedFrame(callback, options) {
-    const maxFps = options?.maxFps ?? DEFAULT_MAX_FPS;
-    const subscriberId = Symbol("decoded-subscriber");
-    const frameDropper = new FrameDropper(maxFps);
+  // ── Decoded audio-chunk plane (Phase 5 / D9) ─────────────────────────
+  /**
+   * Open a decoded audio-chunk subscription — the poll-based, tRPC-reachable
+   * replacement for the live-object `onDecodedAudioChunk` callback. The
+   * broker registers a per-subscription FIFO queue and returns a
+   * `subscriptionId` the consumer drains via `pullAudioChunks`.
+   */
+  subscribeAudioChunks(options) {
     const tag = options?.tag;
     if (!tag) {
-      this.logger?.warn(`onDecodedFrame called without tag — listClients will show 'unknown' (Phase 10: every caller must pass options.tag)`);
+      this.logger?.warn(`subscribeAudioChunks called without tag — listClients will show 'unknown'`);
     }
-    const subscriber = {
-      callback,
-      frameDropper,
-      tag: tag ?? "unknown",
-      maxFps,
-      format: options?.format ?? "jpeg",
-      subscribedAt: Date.now(),
-      framesDelivered: 0,
-      framesDropped: 0
-    };
-    this.decodedSubscribers.set(subscriberId, subscriber);
-    this.logger?.info("decoded subscriber added", {
-      meta: { tag: subscriber.tag, total: this.decodedSubscribers.size, maxFps, format: subscriber.format }
-    });
+    const result = this.audioChunkPlane.subscribe({ tag });
     this.checkDemand();
-    if (this.decoderTeardownTimer) {
-      clearTimeout(this.decoderTeardownTimer);
-      this.decoderTeardownTimer = void 0;
-    }
-    if (!this.decoderProxy && this.source) {
-      const codec = this.detectedCodec ?? this.source.videoCodec;
-      if (codec) {
-        this.createSharedDecoderSession(options);
-      } else {
-        this.pendingDecodeOptions = options;
-        this.logger?.info("Decoder creation deferred — waiting for codec probe");
-      }
-    } else if (this.decoderProxy) {
-      this.maybeUpgradeDecoderFormat();
-    }
-    return () => {
-      this.decodedSubscribers.delete(subscriberId);
-      this.logger?.info("decoded subscriber removed", { meta: { total: this.decodedSubscribers.size } });
-      this.checkDemand();
-      if (this.decodedSubscribers.size === 0 && this.decoderProxy) {
-        this.logger?.info("last decoded subscriber left — scheduling decoder teardown", {
-          meta: { graceMs: DECODER_TEARDOWN_GRACE_MS }
-        });
-        this.decoderTeardownTimer = setTimeout(() => {
-          this.decoderTeardownTimer = void 0;
-          if (this.decodedSubscribers.size === 0 && this.decoderProxy) {
-            this.logger?.info("decoder teardown — no subscribers reconnected");
-            this.destroyDecoder();
-          }
-        }, DECODER_TEARDOWN_GRACE_MS);
-      }
+    return result;
+  }
+  /** Drain up to `maxCount` `DecodedAudioChunk`s for an audio-chunk subscription. */
+  pullAudioChunks(subscriptionId, maxCount) {
+    return this.audioChunkPlane.pull(subscriptionId, maxCount);
+  }
+  /** Release an audio-chunk subscription. Returns `true` when it existed. */
+  unsubscribeAudioChunks(subscriptionId) {
+    const released = this.audioChunkPlane.unsubscribe(subscriptionId);
+    if (released) this.checkDemand();
+    return released;
+  }
+  // ── Shared-memory frame-handle plane (Phase 5 / D9) ──────────────────
+  /**
+   * Resolve the stream descriptor the `FrameHandlePlane` needs to create a
+   * `frameSink: 'shm'` decoder session — codec, numeric device id, log tag,
+   * and (for a pull-mode decoder) the local pipe URL. Returns `null` before
+   * the broker has a source.
+   */
+  resolveFrameHandleStreamInfo() {
+    const codec = this.detectedCodec ?? this.source?.videoCodec;
+    if (!codec || !this.source) return null;
+    const slash = this.deviceId.indexOf("/");
+    const numericDeviceId = slash >= 0 ? Number.parseInt(this.deviceId.slice(0, slash), 10) : Number.parseInt(this.deviceId, 10);
+    return {
+      codec,
+      ...Number.isFinite(numericDeviceId) ? { numericDeviceId } : {},
+      tag: `broker:${this.deviceId}`,
+      // push-mode is the node-av default today; pull-mode URL wiring is deferred to a later Phase-5 task.
+      pullModeUrl: null
     };
   }
-  onDecodedAudioChunk(callback, options) {
-    const tag = options?.tag;
-    if (!tag) {
-      this.logger?.warn(`onDecodedAudioChunk called without tag — listClients will show 'unknown' (Phase 10)`);
+  /** Lazily construct the frame-handle plane, returning `null` with no decoder. */
+  ensureFrameHandlePlane() {
+    if (this.frameHandlePlane) return this.frameHandlePlane;
+    if (!this.decoderApi) {
+      this.logger?.warn("subscribeFrameHandles: no decoder API — frame handles unavailable");
+      return null;
+    }
+    this.frameHandlePlane = new FrameHandlePlane({
+      decoderApi: this.decoderApi,
+      logger: this.logger?.child("frame-handle-plane"),
+      resolveStreamInfo: () => this.resolveFrameHandleStreamInfo()
+    });
+    return this.frameHandlePlane;
+  }
+  /**
+   * Subscribe to this broker's shared-memory frame-handle stream — the broker's
+   * decoded-frame surface. The broker spins up (or reuses) a `frameSink: 'shm'`
+   * decoder session producing `input.format` and returns a `subscriptionId`
+   * the consumer polls via `pullFrameHandles`. fps throttling is implicit
+   * (latest-wins ring reads); `input.maxFps` is echoed as a cadence hint.
+   */
+  async subscribeFrameHandles(input) {
+    const plane = this.ensureFrameHandlePlane();
+    if (!plane) {
+      throw new Error("stream-broker: no decoder available for frame-handle subscription");
     }
-    const subscriberId = Symbol("audio-subscriber");
-    const subscriber = {
-      callback,
-      tag: tag ?? "unknown",
-      subscribedAt: Date.now(),
-      chunksDelivered: 0
-    };
-    this.audioSubscribers.set(subscriberId, subscriber);
     this.checkDemand();
-    return () => {
-      this.audioSubscribers.delete(subscriberId);
+    const { subscriptionId, maxFps } = await plane.subscribe({
+      format: input.format,
+      maxFps: input.maxFps,
+      tag: input.tag
+    });
+    return { subscriptionId, maxFps };
+  }
+  /** Drain up to `maxCount` `FrameHandle`s for a frame-handle subscription. */
+  pullFrameHandles(subscriptionId, maxCount) {
+    return this.frameHandlePlane?.pullHandles(subscriptionId, maxCount) ?? [];
+  }
+  /** Release a frame-handle subscription. Returns `true` when it existed. */
+  async unsubscribeFrameHandles(subscriptionId) {
+    const plane = this.frameHandlePlane;
+    if (!plane) return false;
+    const released = await plane.unsubscribe(subscriptionId);
+    if (released && plane.subscriberCount === 0) {
       this.checkDemand();
-    };
+    }
+    return released;
   }
   getStats() {
-    const decoderStats = this._suspended ? void 0 : this.cachedDecoderStats;
     return {
       status: this._suspended ? "idle" : this._status,
-      inputFps: decoderStats?.inputFps ?? this.encodedInputFps,
-      decodeFps: decoderStats?.outputFps ?? 0,
+      inputFps: this.encodedInputFps,
+      decodeFps: this.frameHandlePlane?.decodeFps() ?? 0,
       encodedSubscribers: this.encodedCallbacks.size,
-      decodedSubscribers: this.decodedSubscribers.size,
+      decodedSubscribers: this.frameHandlePlane?.subscriberCount ?? 0,
       uptimeMs: Date.now() - this.startedAt,
       bitrateKbps: this.bitrateKbps,
       idrIntervalMs: this.idrIntervalMs,
@@ -4214,7 +4480,7 @@ class StreamBroker {
       preBufferSec: this.preBuffer.getDuration(),
       preBufferMs: this.preBuffer.getBufferedDurationMs(),
       preBufferPackets: this.preBuffer.getPacketCount(),
-      decoderNodeId: this.decoderNodeId,
+      decoderNodeId: this.frameHandlePlane?.decoderNodeIds()[0] ?? null,
       audio: this.audioTrackInfo ?? null
     };
   }
@@ -4228,14 +4494,17 @@ class StreamBroker {
   listClients() {
     return {
       rtsp: this.rtspRestreamer.listSessionInfos(),
-      decoded: [...this.decodedSubscribers.values()].map((s) => ({
+      // Phase 5 / D9: the `decoded` channel is the shm frame-handle plane's
+      // subscriber set. `framesDropped` is always 0 — a slow consumer's
+      // dropped frames are recycled silently at the ring, not counted here.
+      decoded: (this.frameHandlePlane?.listSubscribers() ?? []).map((s) => ({
         tag: s.tag,
         subscribedAt: s.subscribedAt,
         maxFps: s.maxFps,
         framesDelivered: s.framesDelivered,
-        framesDropped: s.framesDropped
+        framesDropped: 0
       })),
-      audio: [...this.audioSubscribers.values()].map((s) => ({
+      audio: this.audioChunkPlane.listSubscribers().map((s) => ({
         tag: s.tag,
         subscribedAt: s.subscribedAt,
         chunksDelivered: s.chunksDelivered
@@ -4247,24 +4516,38 @@ class StreamBroker {
   /**
    * Force-disconnect a single consumer. Matches by channel:
    *   - `rtsp`: by `sessionId` (calls `RtspRestreamer.killSession`).
-   *   - `decoded` / `audio`: by `tag` — drops every subscriber whose tag
-   *     matches, then re-evaluates demand so the decoder can wind down
-   *     if nothing else is holding it.
+   *   - `decoded`: by `tag` — releases every shm frame-handle subscription
+   *     whose tag matches (the plane winds the decoder session down once its
+   *     last subscriber leaves).
+   *   - `audio`: by `tag` — drops every audio subscriber whose tag matches,
+   *     then re-evaluates demand.
    * Returns `true` when at least one consumer was dropped.
    */
   killClient(channel, handle) {
     if (channel === "rtsp") {
       return this.rtspRestreamer.killSession(handle);
     }
-    const subscribers = channel === "decoded" ? this.decodedSubscribers : this.audioSubscribers;
-    const victims = [];
-    for (const [key, sub] of subscribers) {
-      if (sub.tag === handle) victims.push(key);
+    if (channel === "decoded") {
+      const plane = this.frameHandlePlane;
+      if (!plane) return false;
+      const matched = plane.listSubscribers().some((s) => s.tag === handle);
+      if (!matched) return false;
+      plane.killByTag(handle).then((killed2) => {
+        this.logger?.info("frame-handle subscribers force-disconnected", {
+          meta: { handle, killed: killed2 }
+        });
+        this.checkDemand();
+      }).catch((err) => {
+        this.logger?.warn("frame-handle killByTag failed", {
+          meta: { handle, error: errMsg(err) }
+        });
+      });
+      return true;
     }
-    if (victims.length === 0) return false;
-    for (const key of victims) subscribers.delete(key);
-    this.logger?.info("subscribers force-disconnected", {
-      meta: { channel, handle, killed: victims.length, remaining: subscribers.size }
+    const killed = this.audioChunkPlane.killByTag(handle);
+    if (killed === 0) return false;
+    this.logger?.info("audio subscribers force-disconnected", {
+      meta: { handle, killed, remaining: this.audioChunkPlane.subscriberCount }
     });
     this.checkDemand();
     return true;
@@ -4412,13 +4695,6 @@ class StreamBroker {
         });
         this.armFirstVideoWatchdog();
         this.rtspRestreamer.setCameraSdp(sdpText, track.codec, track.codecParams);
-        if (!this.decoderProxy && this.decodedSubscribers.size > 0 && this.pendingDecodeOptions !== void 0) {
-          this.logger?.info("native: codec detected — creating deferred decoder", {
-            meta: { codec: track.codec }
-          });
-          this.createSharedDecoderSession(this.pendingDecodeOptions);
-          this.pendingDecodeOptions = void 0;
-        }
       },
       onVideoRtp: (rtpData) => {
         if (this.stopping) return;
@@ -4473,10 +4749,7 @@ class StreamBroker {
         let effectiveChannels = audioTrack.channels;
         if (supportedNative) {
           this.audioRtpDecoder = new AudioRtpDecoder(codecUpper, (chunk) => {
-            for (const sub of this.audioSubscribers.values()) {
-              sub.callback(chunk);
-              sub.chunksDelivered++;
-            }
+            this.audioChunkPlane.fanout(chunk);
           });
           this.logger?.info("native: audio decoder initialized", {
             meta: { codec: codecUpper, sampleRate: audioTrack.clockRate, channels: audioTrack.channels }
@@ -4889,90 +5162,28 @@ class StreamBroker {
       this._status = "error";
     }, PUSH_STALL_TIMEOUT_MS);
   }
-  destroyDecoder() {
-    if (this.decoderResolveRetryTimer) {
-      clearTimeout(this.decoderResolveRetryTimer);
-      this.decoderResolveRetryTimer = void 0;
-    }
-    this.decoderResolveAttempts = 0;
-    const proxy = this.decoderProxy;
-    this.decoderProxy = null;
-    this.decoderNodeId = null;
-    this.cachedDecoderStats = void 0;
-    return proxy?.destroy() ?? Promise.resolve();
-  }
   /**
-   * Moleculer nodeID of the decoder provider currently owning this broker's
-   * shared session. `null` when no session is active. Used by the
-   * broker-manager's `rotateDecodersOnNode` method to drop only the
-   * sessions affected by a per-agent event (e.g. hwaccel override change).
+   * Moleculer nodeID of a decoder provider hosting one of this broker's shm
+   * frame-plane sessions. `null` when the plane has no session. Used by the
+   * broker-manager's `rotateDecodersOnNode` to drop only the sessions
+   * affected by a per-agent event (e.g. an hwaccel override change).
    */
   getDecoderNodeId() {
-    return this.decoderNodeId;
-  }
-  /**
-   * Force the current shared decoder session to tear down. The next
-   * subscriber will trigger a fresh `createSharedDecoderSession` which
-   * re-pulls the latest per-agent preferences (hwaccel backend, …). Safe
-   * to call when there's no active session — resolves to a no-op.
-   */
-  async rotateDecoderSession(reason) {
-    if (!this.decoderProxy) return;
-    this.logger?.info("rotating decoder session", { meta: { reason, decoderNodeId: this.decoderNodeId } });
-    await this.destroyDecoder();
-    if (this.decodedSubscribers.size > 0 && this.source) {
-      const codec = this.detectedCodec ?? this.source.videoCodec;
-      if (codec) {
-        this.createSharedDecoderSession(this.pendingDecodeOptions).catch((err) => {
-          this.logger?.warn("decoder session rebuild after rotation failed", { meta: { error: errMsg(err) } });
-        });
-      }
-    }
+    return this.frameHandlePlane?.decoderNodeIds()[0] ?? null;
   }
   /**
-   * Poll the decoder resolver until a provider for `codec` shows up, then
-   * build the session. Addons register asynchronously and out-of-order:
-   * the broker must NOT fail when the decoder addon hasn't yet finished
-   * spawning its isolated process — it must wait.
-   *
-   * Bounded backoff: 500ms → 1s → 2s → 4s → 8s (capped), with a hard
-   * ceiling of ~60s total wait. If the decoder still isn't registered
-   * after that, log once at error level and stop retrying — at that
-   * point something is genuinely wrong with the addon config.
-   *
-   * The first failure is logged at debug so a healthy boot (decoder
-   * arriving within the first few hundred ms) doesn't pollute the log
-   * with noisy errors.
-   */
-  scheduleDecoderResolveRetry(codec) {
-    if (this.decoderResolveRetryTimer) return;
-    const attempt = this.decoderResolveAttempts++;
-    const backoffMs = Math.min(500 * Math.pow(2, attempt), 8e3);
-    const cumulativeMs = (Math.pow(2, this.decoderResolveAttempts) - 1) * 500;
-    if (cumulativeMs > 6e4) {
-      this.logger?.error(
-        "No decoder provider — giving up. Check that addon-decoder-nodeav or addon-decoder-ffmpeg is installed and enabled.",
-        { meta: { codec, attempts: this.decoderResolveAttempts } }
-      );
-      this.decoderResolveAttempts = 0;
-      return;
-    }
-    if (attempt === 0) {
-      this.logger?.debug(
-        "Decoder not yet registered — will retry (addon boot race)",
-        { meta: { codec } }
-      );
-    }
-    this.decoderResolveRetryTimer = setTimeout(() => {
-      this.decoderResolveRetryTimer = void 0;
-      if (this.decoderProxy) return;
-      if (this.decodedSubscribers.size === 0) {
-        this.decoderResolveAttempts = 0;
-        this.pendingDecodeOptions = void 0;
-        return;
-      }
-      this.createSharedDecoderSession(this.pendingDecodeOptions);
-    }, backoffMs);
+   * Force this broker's shm frame-plane decoder sessions hosted on
+   * `agentNodeId` to rotate — destroy and rebuild so they re-pull the latest
+   * per-agent preferences (hwaccel backend, …). A no-op when the broker has
+   * no frame plane. Subscriptions survive the rotation.
+   */
+  async rotateDecoderSession(reason, agentNodeId) {
+    const plane = this.frameHandlePlane;
+    if (!plane) return;
+    const target = agentNodeId ?? plane.decoderNodeIds()[0]?.split("/")[0];
+    if (!target) return;
+    this.logger?.info("rotating shm decoder sessions", { meta: { reason, agentNodeId: target } });
+    await plane.rotate(target, reason);
   }
   destroyNativeClient() {
     if (this.nativeClient) {
@@ -5059,78 +5270,6 @@ class StreamBroker {
       });
     }
   }
-  async createSharedDecoderSession(options) {
-    const codec = this.detectedCodec ?? this.source?.videoCodec ?? "h264";
-    if (!this.decoderApi) {
-      this.logger?.warn("no decoder API available — decoded frames will not be produced");
-      return;
-    }
-    const supported = await this.decoderApi.supportsCodec({ codec });
-    if (!supported) {
-      this.pendingDecodeOptions = options;
-      this.scheduleDecoderResolveRetry(codec);
-      return;
-    }
-    if (this.decoderResolveRetryTimer) {
-      clearTimeout(this.decoderResolveRetryTimer);
-      this.decoderResolveRetryTimer = void 0;
-    }
-    this.decoderResolveAttempts = 0;
-    const resolvedFormat = this.resolveDecoderFormat();
-    const slash = this.deviceId.indexOf("/");
-    const numericDeviceId = slash >= 0 ? Number.parseInt(this.deviceId.slice(0, slash), 10) : Number.parseInt(this.deviceId, 10);
-    const config = {
-      codec,
-      maxFps: 0,
-      outputFormat: resolvedFormat,
-      scale: options?.scale ?? DEFAULT_SCALE,
-      ...Number.isFinite(numericDeviceId) ? { deviceId: numericDeviceId } : {},
-      tag: `broker:${this.deviceId}`
-    };
-    this.decoderOutputFormat = resolvedFormat;
-    const { sessionId, nodeId } = await this.decoderApi.createSession(config);
-    const proxy = new DecoderSessionProxy(this.decoderApi, sessionId);
-    this.decoderProxy = proxy;
-    this.decoderNodeId = nodeId;
-    const onFrame = (frame) => {
-      this.decoderFrameCount++;
-      if (this.decoderFrameCount === 1) {
-        this.logger?.info("first decoded frame", {
-          meta: { width: frame.width, height: frame.height, format: frame.format }
-        });
-      }
-      if (this.decoderFrameCount % 30 === 0) {
-        proxy.getStats().then((stats) => {
-          this.cachedDecoderStats = stats;
-        }).catch(() => {
-        });
-      }
-      this.fanoutDecodedFrame(frame);
-    };
-    proxy.startPolling(onFrame).catch((err) => {
-      this.logger?.warn("decoder polling error", { meta: { error: errMsg(err) } });
-    });
-    const info = await this.decoderApi.getInfo();
-    if (info.isPullMode) {
-      const localUrl = this.pipeServer.getUrl();
-      const isHevc = codec === "h265" || codec === "hevc";
-      const inputUrl = `${localUrl}?format=${isHevc ? "hevc" : "h264"}`;
-      const doOpen = () => {
-        this.logger?.info("Pull mode decoder: opening local pipe", {
-          meta: { localUrl, codec }
-        });
-        proxy.openStream(inputUrl).catch((err) => {
-          this.logger?.error("Pull mode decoder failed", { meta: { error: errMsg(err) } });
-        });
-      };
-      if (this.firstKeyframeReceived) {
-        doOpen();
-      } else {
-        this.logger?.info("Pull mode decoder: waiting for first keyframe before opening");
-        this.pendingPullModeOpen = doOpen;
-      }
-    }
-  }
   /**
    * Map an SDP audio track to an `AudioCodecSession` config the
    * audio-codec cap can consume. Returns `null` when the codec is
@@ -5145,10 +5284,7 @@ class StreamBroker {
    */
   buildAudioCodecEmitCallback() {
     return (chunk) => {
-      for (const sub of this.audioSubscribers.values()) {
-        sub.callback(chunk);
-        sub.chunksDelivered++;
-      }
+      this.audioChunkPlane.fanout(chunk);
       if (this.encodedCallbacks.size > 0) {
         const f32 = new Float32Array(chunk.data.buffer, chunk.data.byteOffset, chunk.data.byteLength / 4);
         const pcm16 = new Int16Array(f32.length);
@@ -5806,7 +5942,6 @@ class TranscodePipelineManager {
   logger;
   api;
   cameraStreamLookup;
-  rtspEntryLookup;
   localRtspPort;
   releaseGraceMs;
   ffmpegPath;
@@ -5814,7 +5949,6 @@ class TranscodePipelineManager {
     this.logger = opts.logger;
     this.api = opts.api;
     this.cameraStreamLookup = opts.cameraStreamLookup;
-    this.rtspEntryLookup = opts.rtspEntryLookup;
     this.localRtspPort = opts.localRtspPort;
     this.releaseGraceMs = opts.releaseGraceMs ?? 5e3;
     this.ffmpegPath = opts.ffmpegPath ?? "ffmpeg";
@@ -6119,6 +6253,18 @@ class StreamBrokerManager {
    */
   streamHealthByBroker = /* @__PURE__ */ new Map();
   streamHealthTimer;
+  /**
+   * Routes a frame-handle `subscriptionId` (Phase 5 / D9) back to its owning
+   * brokerId so `pullFrameHandles` / `unsubscribeFrames` resolve in O(1)
+   * without scanning every broker.
+   */
+  frameSubscriptionBroker = /* @__PURE__ */ new Map();
+  /**
+   * Routes an audio-chunk `subscriptionId` (Phase 5 / D9) back to its owning
+   * brokerId so `pullAudioChunks` / `unsubscribeAudioChunks` resolve in O(1)
+   * without scanning every broker. Mirrors `frameSubscriptionBroker`.
+   */
+  audioSubscriptionBroker = /* @__PURE__ */ new Map();
   // Legacy static restreamers list — production reads via capabilities.
   restreamers = [];
   staticDecoders;
@@ -6223,6 +6369,12 @@ class StreamBrokerManager {
         if (!localApi) return [];
         return localApi.pullFrames(input);
       },
+      pullHandles: async (input) => {
+        const proxy = apiDecoder();
+        if (proxy) return proxy.pullHandles.query(input);
+        if (!localApi) return [];
+        return localApi.pullHandles(input);
+      },
       destroySession: async (input) => {
         const proxy = apiDecoder();
         if (proxy) return proxy.destroySession.query(input);
@@ -6292,6 +6444,14 @@ class StreamBrokerManager {
         if (!buffer) return [];
         return buffer.drain(input.maxCount);
       },
+      // The in-process `staticDecoders` fallback has no shm sink — its
+      // `IDecoderSession` exposes only `onFrame` (pixels), not
+      // `onFrameHandle`. The shared-memory frame plane (Phase 5 / D9) runs
+      // through the real `decoder` cap (the node-av addon, which owns the
+      // `frameSink: 'shm'` ring writer). `pullHandles` therefore returns
+      // nothing here — a `frameSink: 'shm'` request degrades to no frames
+      // rather than crashing the broker.
+      pullHandles: async () => [],
       destroySession: async (input) => {
         const session = sessions.get(input.sessionId);
         if (session) {
@@ -6555,10 +6715,111 @@ class StreamBrokerManager {
     if (!this.cameraStreams.has(deviceId) && !this.assignments.has(deviceId)) return [];
     return this.snapshotProfileSlots(deviceId);
   }
-  // ── Cap methods: broker runtime (stats + client inventory) ──────────
+  // ── Internal: live broker lookup (not a cap method) ─────────────────
+  /**
+   * Resolve the live `StreamBroker` instance for a broker id. In-process
+   * only — a `StreamBroker` is not tRPC-serialisable, so this is reachable
+   * solely from same-process callers (device-scoped providers, the WebRTC
+   * server). Cross-process frame access goes through the shm `subscribeFrames`
+   * surface; cross-process stats through `getBrokerStats` / `listClients`.
+   */
   async getBroker(input) {
     return this.brokers.get(input.brokerId) ?? null;
   }
+  // ── Cap methods: broker runtime (stats + client inventory) ──────────
+  // ── Cap methods: shared-memory frame-handle plane (Phase 5 / D9) ─────
+  /**
+   * Open a `FrameHandle` subscription on a broker — the handle-based
+   * replacement for the live-object `onDecodedFrame` callback. Routed over
+   * tRPC, so a consumer in a different process can subscribe; the consumer
+   * then polls `pullFrameHandles` and feeds each handle to a
+   * `FrameRingReader`.
+   */
+  async subscribeFrames(input) {
+    const broker = this.brokers.get(input.brokerId);
+    if (!broker) {
+      throw new Error(`stream-broker: no broker for "${input.brokerId}"`);
+    }
+    const result = await broker.subscribeFrameHandles({
+      format: input.format,
+      maxFps: input.maxFps,
+      tag: input.tag
+    });
+    this.frameSubscriptionBroker.set(result.subscriptionId, input.brokerId);
+    return result;
+  }
+  /** Drain `FrameHandle`s for a subscription opened via `subscribeFrames`. */
+  async pullFrameHandles(input) {
+    const brokerId = this.frameSubscriptionBroker.get(input.subscriptionId);
+    if (!brokerId) return [];
+    const broker = this.brokers.get(brokerId);
+    if (!broker) return [];
+    return broker.pullFrameHandles(input.subscriptionId, input.maxCount);
+  }
+  /**
+   * Drop every `frameSubscriptionBroker` + `audioSubscriptionBroker` entry
+   * pointing at `brokerId`. Called on broker teardown so a destroyed broker
+   * leaves no dangling `subscriptionId → brokerId` rows (a slow consumer that
+   * never calls `unsubscribeFrames` / `unsubscribeAudioChunks` would otherwise
+   * leak a map entry per stream).
+   */
+  sweepFrameSubscriptions(brokerId) {
+    for (const [subscriptionId, mappedBrokerId] of this.frameSubscriptionBroker) {
+      if (mappedBrokerId === brokerId) {
+        this.frameSubscriptionBroker.delete(subscriptionId);
+      }
+    }
+    for (const [subscriptionId, mappedBrokerId] of this.audioSubscriptionBroker) {
+      if (mappedBrokerId === brokerId) {
+        this.audioSubscriptionBroker.delete(subscriptionId);
+      }
+    }
+  }
+  /** Release a frame-handle subscription. */
+  async unsubscribeFrames(input) {
+    const brokerId = this.frameSubscriptionBroker.get(input.subscriptionId);
+    if (!brokerId) return { released: false };
+    this.frameSubscriptionBroker.delete(input.subscriptionId);
+    const broker = this.brokers.get(brokerId);
+    if (!broker) return { released: false };
+    const released = await broker.unsubscribeFrameHandles(input.subscriptionId);
+    return { released };
+  }
+  // ── Cap methods: decoded audio-chunk plane (Phase 5 / D9) ────────────
+  /**
+   * Open a decoded audio-chunk subscription on a broker — the poll-based,
+   * tRPC-reachable replacement for the live-object `onDecodedAudioChunk`
+   * callback. The consumer then polls `pullAudioChunks` and feeds each
+   * `DecodedAudioChunk` to its downstream audio logic. Audio chunks are tiny
+   * so their bytes travel inline on the RPC wire — no shared memory.
+   */
+  async subscribeAudioChunks(input) {
+    const broker = this.brokers.get(input.brokerId);
+    if (!broker) {
+      throw new Error(`stream-broker: no broker for "${input.brokerId}"`);
+    }
+    const result = broker.subscribeAudioChunks({ tag: input.tag });
+    this.audioSubscriptionBroker.set(result.subscriptionId, input.brokerId);
+    return result;
+  }
+  /** Drain `DecodedAudioChunk`s for a subscription opened via `subscribeAudioChunks`. */
+  async pullAudioChunks(input) {
+    const brokerId = this.audioSubscriptionBroker.get(input.subscriptionId);
+    if (!brokerId) return [];
+    const broker = this.brokers.get(brokerId);
+    if (!broker) return [];
+    return broker.pullAudioChunks(input.subscriptionId, input.maxCount);
+  }
+  /** Release an audio-chunk subscription. */
+  async unsubscribeAudioChunks(input) {
+    const brokerId = this.audioSubscriptionBroker.get(input.subscriptionId);
+    if (!brokerId) return { released: false };
+    this.audioSubscriptionBroker.delete(input.subscriptionId);
+    const broker = this.brokers.get(brokerId);
+    if (!broker) return { released: false };
+    const released = broker.unsubscribeAudioChunks(input.subscriptionId);
+    return { released };
+  }
   async getBrokerStats(input) {
     const broker = this.brokers.get(input.brokerId);
     if (!broker) {
@@ -6599,12 +6860,10 @@ class StreamBrokerManager {
   async rotateDecodersOnNode(agentNodeId, reason) {
     let rotated = 0;
     for (const broker of this.brokers.values()) {
-      const nodeId = broker.getDecoderNodeId();
-      if (!nodeId) continue;
-      const brokerAgent = nodeId.includes("/") ? nodeId.split("/")[0] : nodeId;
-      if (brokerAgent !== agentNodeId) continue;
+      const onNode = broker.getDecoderNodeId()?.split("/")[0] === agentNodeId;
+      if (!onNode) continue;
       try {
-        await broker.rotateDecoderSession(reason);
+        await broker.rotateDecoderSession(reason, agentNodeId);
         rotated++;
       } catch (err) {
         this.logger.warn("decoder rotation failed", {
@@ -6631,6 +6890,8 @@ class StreamBrokerManager {
     await Promise.all(stopPromises);
     this.brokers.clear();
     this.streamHealthByBroker.clear();
+    this.frameSubscriptionBroker.clear();
+    this.audioSubscriptionBroker.clear();
     await this.rtspServer.stop();
   }
   // ── Stream health watchdog ──────────────────────────────────────────
@@ -7270,6 +7531,7 @@ class StreamBrokerManager {
     this.streamHealthByBroker.delete(brokerId);
     await broker.stop();
     this.brokers.delete(brokerId);
+    this.sweepFrameSubscriptions(brokerId);
     this.rtspProvider.persistTokens();
   }
   /**
@@ -10254,11 +10516,17 @@ class StreamBrokerAddon extends BaseAddon {
     const widgetsProvider = {
       listWidgets: async () => [
         {
-          stableId: "stream-broker-panel",
+          tab: "device-tab",
           label: "Stream Brokers",
+          kind: "remote",
+          remote: {
+            remoteName: "addon_stream_broker_widgets",
+            exposedModule: "./widgets",
+            componentKey: "stream-broker-panel"
+          },
+          stableId: "stream-broker-panel",
           description: "Per-camera stream broker panel with adaptive controls.",
           icon: "radio",
-          remoteName: "addon_stream_broker_widgets",
           bundle: "remoteEntry.js",
           hosts: ["device-tab", "dashboard"],
           requires: { deviceContext: true, integrationContext: false },
@@ -10274,15 +10542,11 @@ class StreamBrokerAddon extends BaseAddon {
       { capability: streamBrokerCapability, provider: this.brokerManager },
       {
         capability: cameraStreamsCapability,
-        provider: cameraStreamsProvider,
-        kind: "wrapper",
-        defaultActive: true
+        provider: cameraStreamsProvider
       },
       {
         capability: webrtcSessionCapability,
-        provider: webrtcSessionProvider,
-        kind: "wrapper",
-        defaultActive: true
+        provider: webrtcSessionProvider
       },
       { capability: addonWidgetsSourceCapability, provider: widgetsProvider }
     ];
@@ -10412,6 +10676,25 @@ class StreamBrokerAddon extends BaseAddon {
     });
   }
 }
+class FrameDropper {
+  intervalMs;
+  lastPassedAt = -Infinity;
+  constructor(maxFps) {
+    this.intervalMs = maxFps > 0 ? 1e3 / maxFps : 0;
+  }
+  shouldKeep() {
+    if (this.intervalMs === 0) return true;
+    const now = Date.now();
+    if (now - this.lastPassedAt >= this.intervalMs) {
+      this.lastPassedAt = now;
+      return true;
+    }
+    return false;
+  }
+  setMaxFps(maxFps) {
+    this.intervalMs = maxFps > 0 ? 1e3 / maxFps : 0;
+  }
+}
 const noopLogger = {
   debug() {
   },