@camstack/addon-pipeline 0.1.13 → 0.1.15

package/dist/pipeline-runner/index.mjs

@@ -1,20 +1,29 @@
-import { o as object, s as string, _ as _enum, l as lazy, a as array, b as boolean, n as number, d as defineCustomActions, c as customAction, B as BaseAddon, E as EventCategory, p as pipelineRunnerCapability, e as errMsg, f as createEvent } from "../index-BwLnHesq.mjs";
+import { e as errMsg, o as object, s as string, _ as _enum, l as lazy, a as array, b as boolean, n as number, d as defineCustomActions, c as customAction, B as BaseAddon, E as EventCategory, p as pipelineRunnerCapability, f as createEvent } from "../index-CVzLrojg.mjs";
+import { FrameRingReaderCache } from "@camstack/shm-ring";
 class FrameQueue {
-  constructor(maxSize) {
+  /**
+   * `clone` runs on every {@link enqueue} to detach a queue-owned copy from
+   * the (possibly borrowed) source — required by the D9 Task 7b ownership
+   * contract above. Motion call sites pass {@link ownFrame}; the detection
+   * path passes a clone that copies its inner frame's pixel buffer.
+   */
+  constructor(maxSize, clone) {
     this.maxSize = maxSize;
+    this.clone = clone;
   }
   latest = null;
   _droppedFrames = 0;
-  enqueue(frame) {
+  clone;
+  enqueue(item) {
     if (this.latest !== null) {
       this._droppedFrames++;
     }
-    this.latest = frame;
+    this.latest = this.clone(item);
   }
   dequeue() {
-    const frame = this.latest ?? void 0;
+    const item = this.latest ?? void 0;
     this.latest = null;
-    return frame;
+    return item;
   }
   get size() {
     return this.latest !== null ? 1 : 0;
@@ -26,6 +35,9 @@ class FrameQueue {
     this.latest = null;
   }
 }
+function ownFrame(frame) {
+  return { ...frame, data: Buffer.from(frame.data) };
+}
 class Semaphore {
   _concurrency;
   _available;
@@ -194,6 +206,9 @@ class PipelineTimingSampler {
     this.audioSamples.clear();
   }
 }
+function ownDetectionEntry(entry) {
+  return { frame: ownFrame(entry.frame), handle: entry.handle };
+}
 const DEFAULT_MOTION_COOLDOWN_MS = 3e4;
 function toFrameInput$1(frame) {
   return {
@@ -268,8 +283,11 @@ class PipelineRunner {
     this.detectionStreamHandler = handler;
   }
   registerCamera(deviceId, registration) {
-    const motionQueue = new FrameQueue(this.config.maxQueueDepth);
-    const detectionQueue = new FrameQueue(this.config.maxQueueDepth);
+    const motionQueue = new FrameQueue(this.config.maxQueueDepth, ownFrame);
+    const detectionQueue = new FrameQueue(
+      this.config.maxQueueDepth,
+      ownDetectionEntry
+    );
     const initialPhase = registration.detectionMode === "disabled" ? "idle" : registration.detectionMode === "always-on" ? "active" : "watching";
     const state = {
       registration,
@@ -324,12 +342,12 @@ class PipelineRunner {
     if (!state) return;
     state.motionQueue.enqueue(frame);
   }
-  enqueueDetectionFrame(deviceId, frame) {
+  enqueueDetectionFrame(deviceId, frame, handle) {
     const state = this.cameras.get(deviceId);
     if (!state) return;
     if (state.phase !== "active") return;
     frame._enqueuedAt = Date.now();
-    state.detectionQueue.enqueue(frame);
+    state.detectionQueue.enqueue({ frame, handle });
   }
   /**
    * Report a motion event for a camera. Drives the unified phase
@@ -482,9 +500,9 @@ class PipelineRunner {
     if (this.semaphore.available <= 0) return;
     const picked = this.pickNextDetectionFrame();
     if (!picked) return;
-    const { deviceId, frame, state } = picked;
-    const frameInput = toFrameInput$1(frame);
-    void this.processWithSemaphore(deviceId, frame, frameInput, state, "detection");
+    const { deviceId, entry, state } = picked;
+    const frameInput = toFrameInput$1(entry.frame);
+    void this.processWithSemaphore(deviceId, entry, frameInput, state, "detection");
   }
   drainMotionQueues() {
     for (const [deviceId, state] of this.cameras) {
@@ -496,8 +514,9 @@ class PipelineRunner {
       }
     }
   }
-  async processWithSemaphore(deviceId, frame, frameInput, state, streamType) {
+  async processWithSemaphore(deviceId, entry, frameInput, state, streamType) {
     const pickedAt = Date.now();
+    const { frame, handle } = entry;
     const captureTs = frame.timestamp;
     const enqueuedAt = frame._enqueuedAt ?? captureTs;
     const release = await this.semaphore.acquire();
@@ -512,7 +531,7 @@ class PipelineRunner {
       }
       state.processedCount++;
       if (result) {
-        await this.notifyCallbacks(deviceId, frame, result, streamType);
+        await this.notifyCallbacks(deviceId, frame, result, streamType, handle);
         const emittedAt = Date.now();
         this.timingSampler.addSample(deviceId, {
           captureToEnqueue: enqueuedAt - captureTs,
@@ -528,10 +547,10 @@ class PipelineRunner {
       release();
     }
   }
-  async notifyCallbacks(deviceId, frame, result, streamType) {
+  async notifyCallbacks(deviceId, frame, result, streamType, handle) {
     for (const callback of this.resultCallbacks) {
       try {
-        await callback(deviceId, frame, result, streamType);
+        await callback(deviceId, frame, result, streamType, handle);
       } catch {
       }
     }
@@ -539,8 +558,8 @@ class PipelineRunner {
   pickNextDetectionFrame() {
     for (const [deviceId, state] of this.cameras) {
       if (state.registration.detectionMode === "always-on" && state.detectionQueue.size > 0) {
-        const frame = state.detectionQueue.dequeue();
-        return { deviceId, frame, state };
+        const entry = state.detectionQueue.dequeue();
+        return { deviceId, entry, state };
       }
     }
     if (this.defaultRoundRobinKeys.length === 0) return null;
@@ -553,14 +572,75 @@ class PipelineRunner {
       if (!state) continue;
       if (state.phase === "active" && state.detectionQueue.size > 0) {
         this.defaultRoundRobinIndex = (idx + 1) % this.defaultRoundRobinKeys.length;
-        const frame = state.detectionQueue.dequeue();
-        if (!frame) continue;
-        return { deviceId, frame, state };
+        const entry = state.detectionQueue.dequeue();
+        if (!entry) continue;
+        return { deviceId, entry, state };
       }
     }
     return null;
   }
 }
+const PULL_MAX_COUNT = 4;
+const MIN_POLL_INTERVAL_MS = 20;
+const FALLBACK_POLL_INTERVAL_MS = 200;
+async function startFrameHandlePoller(options) {
+  const { api, brokerId, format, maxFps, tag, onFrame, logger } = options;
+  let result;
+  try {
+    result = await api.streamBroker.subscribeFrames.mutate({
+      brokerId,
+      format,
+      maxFps,
+      tag
+    });
+  } catch (err) {
+    logger.warn("frame-handle poller: subscribeFrames failed", {
+      meta: { brokerId, format, tag, error: errMsg(err) }
+    });
+    return null;
+  }
+  const { subscriptionId } = result;
+  const readers = new FrameRingReaderCache(logger);
+  const pollIntervalMs = result.maxFps > 0 ? Math.max(MIN_POLL_INTERVAL_MS, Math.round(1e3 / result.maxFps)) : FALLBACK_POLL_INTERVAL_MS;
+  let stopped = false;
+  let timer;
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      const handles = await api.streamBroker.pullFrameHandles.query({
+        subscriptionId,
+        maxCount: PULL_MAX_COUNT
+      });
+      for (const handle of handles) {
+        if (stopped) break;
+        const frame = readers.read(handle);
+        if (frame) onFrame(frame, handle);
+      }
+    } catch (err) {
+      logger.warn("frame-handle poller: pullFrameHandles failed", {
+        meta: { brokerId, subscriptionId, error: errMsg(err) }
+      });
+    }
+    if (!stopped) {
+      timer = setTimeout(() => void tick(), pollIntervalMs);
+    }
+  };
+  void tick();
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
+    }
+    readers.close();
+    api.streamBroker.unsubscribeFrames.mutate({ subscriptionId }).catch((err) => {
+      logger.warn("frame-handle poller: unsubscribeFrames failed", {
+        meta: { brokerId, subscriptionId, error: errMsg(err) }
+      });
+    });
+  };
+}
 const BenchEngineChoiceSchema = object({
   runtime: _enum(["node", "python"]),
   backend: string(),
@@ -721,8 +801,8 @@ class PipelineRunnerAddon extends BaseAddon {
     this.runner.onDetectionStreamChange((deviceId, action) => {
       this.handleDetectionStreamChange(deviceId, action);
     });
-    this.runner.onResult(async (deviceId, frame, result, _streamType) => {
-      this.emitInferenceResult(deviceId, frame, result);
+    this.runner.onResult(async (deviceId, frame, result, _streamType, handle) => {
+      this.emitInferenceResult(deviceId, frame, result, handle);
     });
     this.runner.start();
     this.ctx.logger.info(
@@ -1276,18 +1356,19 @@ class PipelineRunnerAddon extends BaseAddon {
       log.warn("subscribeMotionFrames: this.ctx.api not available");
       return null;
     }
-    const motionBrokerId = `${config.deviceId}/${config.motionStreamId}`;
-    const motionBroker = await api.streamBroker.getBroker.query({ brokerId: motionBrokerId });
-    if (!motionBroker) {
-      log.warn("subscribeMotionFrames: no broker found", { meta: { brokerId: motionBrokerId } });
-      return null;
-    }
-    return motionBroker.onDecodedFrame(
-      (frame) => {
+    return startFrameHandlePoller({
+      api,
+      brokerId: `${config.deviceId}/${config.motionStreamId}`,
+      format: "gray",
+      maxFps: config.motionFps,
+      tag: "motion",
+      logger: log,
+      // Motion analysis is intra-process and never propagates beyond
+      // the runner; the handle is intentionally ignored here.
+      onFrame: (frame, _handle) => {
         runner.enqueueMotionFrame(config.deviceId, frame);
-      },
-      { maxFps: config.motionFps, format: "gray", tag: "motion" }
-    );
+      }
+    });
   }
   handleDetectionStreamChange(deviceId, action) {
     const attachment = this.attached.get(deviceId);
@@ -1361,23 +1442,20 @@ class PipelineRunnerAddon extends BaseAddon {
       log.warn("subscribeDetectionFrames: this.ctx.api not available");
       return null;
     }
-    const detectionBrokerId = `${config.deviceId}/${config.detectionStreamId}`;
-    const detectionBroker = await api.streamBroker.getBroker.query({ brokerId: detectionBrokerId });
-    if (!detectionBroker) {
-      log.warn("subscribeDetectionFrames: no broker found", { meta: { brokerId: detectionBrokerId } });
-      return null;
-    }
-    return detectionBroker.onDecodedFrame(
-      (frame) => {
-        runner.enqueueDetectionFrame(config.deviceId, frame);
-      },
-      // `format: 'rgb'` is the Phase 4 hot-path switch: detection now
-      // requests raw RGB24 from the broker so the decoder skips the
-      // sharp JPEG encode and the Python pool skips PIL JPEG decode.
-      // When WebRTC also subscribes (jpeg), the broker derives JPEG
-      // once per frame via its conversion cache — no double work.
-      { maxFps: config.detectionFps, format: "rgb", tag: "detection" }
-    );
+    return startFrameHandlePoller({
+      api,
+      brokerId: `${config.deviceId}/${config.detectionStreamId}`,
+      format: "rgb",
+      maxFps: config.detectionFps,
+      tag: "detection",
+      logger: log,
+      // Detection threads the `FrameHandle` through the runner so the
+      // emitted `PipelineInferenceResultPayload` can name the shm slot
+      // post-analysis (Task 8) reads pixels back from.
+      onFrame: (frame, handle) => {
+        runner.enqueueDetectionFrame(config.deviceId, frame, handle);
+      }
+    });
   }
   // ── Internal: inference + motion callbacks ───────────────────────────
   async runInference(deviceId, frame) {
@@ -1494,13 +1572,14 @@ class PipelineRunnerAddon extends BaseAddon {
       log.error("runMotionAnalysis failed", { meta: { error: msg } });
     }
   }
-  emitInferenceResult(deviceId, _frame, result) {
+  emitInferenceResult(deviceId, _frame, result, handle) {
     const ctx = this.ctx;
     if (!ctx?.eventBus) return;
     const payload = {
       deviceId,
       frame: result,
-      nodeId: this.nodeId
+      nodeId: this.nodeId,
+      frameHandle: handle
     };
     this.ctx.eventBus.emit(createEvent(
       EventCategory.PipelineInferenceResult,