@mega-yfue/eufy-sdk 0.5.0-beta.82 → 0.5.0-beta.84

package/dist/core/contracts.d.ts

@@ -680,10 +680,9 @@ export interface LiveStreamConsumer extends LiveStreamHandle {
      * consumer receives, so a consumer holding media it has not been told the configuration of is not a state
      * it can reach.
      *
-     * Per consumer, against what THIS consumer was last given: a consumer that joins mid-session is primed
-     * with a cached keyframe it did not witness arriving, and one that crosses its bound resynchronises onto
-     * a later IDR having skipped the frame the source saw the change on. Announcing what the source saw
-     * would leave both holding an encoder built for media they never received.
+     * Per consumer, against what this consumer was last given: a mid-session join begins at its next live
+     * keyframe, and a consumer crossing its queue bound resynchronises onto a later IDR. Each receives
+     * the configuration of the media it is delivered, even when another consumer has already seen it.
      *
      * Only a consumer announces this, never a bare {@link LiveStreamHandle}: it is read from the parameter
      * sets a shared source watches every frame for, which the raw pull underneath it does not do. That is

package/dist/index.js

@@ -19128,10 +19128,9 @@ async function openLiveStream(session, opts = {}) {
 async function captureSnapshotFromShared(source, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 2e4;
   const collectMs = opts.collectMs ?? 1500;
-  const skip = opts.skipKeyframes ?? 1;
   opts.signal?.throwIfAborted();
   const consumer = source.attach();
-  const primed = consumer.primed;
+  const skip = opts.skipKeyframes ?? (source.state === "live" ? 0 : 1);
   let burst;
   try {
     burst = await new Promise((resolve, reject) => {
@@ -19148,8 +19147,7 @@ async function captureSnapshotFromShared(source, opts = {}) {
         if (fr.keyframe)
           keyCount++;
         if (!capturing) {
-          const threshold = primed ? 0 : skip;
-          if (!fr.keyframe || keyCount <= threshold)
+          if (!fr.keyframe || keyCount <= skip)
             return;
           capturing = true;
           codec = fr.codec;
@@ -19159,7 +19157,7 @@ async function captureSnapshotFromShared(source, opts = {}) {
           settle = setTimeout(() => {
             cleanup();
             resolve({ h264: Buffer.concat(bufs), codec, sets });
-          }, primed ? 0 : collectMs);
+          }, collectMs);
       };
       const onError = (err) => {
         cleanup();
@@ -19549,30 +19547,24 @@ var ConsumerImpl = class extends EventEmitter4 {
   queue = [];
   paused = false;
   detached = false;
-  primed = false;
   awaitingKeyframe = false;
   /** The last coded configuration announced to THIS consumer — see {@link flush}. */
   config;
-  /** Cached keyframe to replay, held until a "video" listener actually subscribes (see below). */
-  pendingPrime;
-  constructor(onDetach, maxQueue) {
+  /** Re-arm an ordinary join when its first video-bearing subscription starts, including after an async gap. */
+  constructor(onDetach, maxQueue, waitForKeyframe) {
     super();
     this.onDetach = onDetach;
     this.maxQueue = maxQueue;
-    this.on("newListener", (event) => {
-      if (event !== "video" || this.listenerCount("video") !== 0)
-        return;
-      const kf = this.pendingPrime;
-      if (!kf)
-        return;
-      this.pendingPrime = void 0;
-      queueMicrotask(() => this.deliverVideo(kf));
-    });
-  }
-  /** Stage a keyframe to replay when the first video listener subscribes. */
-  prime(item) {
-    this.primed = true;
-    this.pendingPrime = item;
+    if (waitForKeyframe) {
+      this.on("newListener", (event) => {
+        if (event !== "video" && event !== "media")
+          return;
+        if (this.listenerCount("video") > 0 || this.listenerCount("media") > 0)
+          return;
+        this.awaitingKeyframe = true;
+        this.config = void 0;
+      });
+    }
   }
   /** Attached-by-construction — `start()` is a no-op so a Consumer satisfies LiveStreamHandle. */
   start() {
@@ -19623,14 +19615,7 @@ var ConsumerImpl = class extends EventEmitter4 {
       this.flush(q[i]);
     }
   }
-  /**
-   * Source → consumer video, honouring resync-to-keyframe and the bounded queue.
-   *
-   * Takes the whole item rather than a frame, because a keyframe-prime replays a RETAINED one and has to
-   * arrive by the same route: a primed keyframe is exactly the IDR a resynchronising consumer is waiting
-   * for, so it must clear that wait as a live keyframe does, and it carries the configuration its own media
-   * was coded under. While that wait is unsatisfied a delta frame is dropped — nothing can begin at it.
-   */
+  /** Source → consumer video, dropping dependent pictures until a subscribed consumer receives a keyframe. */
   deliverVideo(item) {
     if (this.detached)
       return;
@@ -19675,9 +19660,8 @@ var ConsumerImpl = class extends EventEmitter4 {
    * about ahead of the frame that carries it.
    *
    * The single delivery point is where the announcement belongs, because every way media reaches a
-   * consumer passes through here: a live frame, a replayed keyframe-prime, and a backlog drained by
-   * {@link resume}. Comparing against what this consumer was last given rather than what the source last
-   * saw is what makes a primed join and a post-overflow resynchronisation correct.
+   * consumer passes through here, including a backlog drained by {@link resume}. The comparison is
+   * against what this consumer was last given rather than what the source last saw.
    */
   flush(item) {
     if (item.kind === "video") {
@@ -19731,8 +19715,8 @@ var SharedLiveSource = class {
    * {@link LiveStreamStartError}.
    */
   delivered = { keyframe: false, video: false, audio: false };
-  /** Last keyframe access unit seen — replayed to a joining consumer (keyframe-prime). */
-  lastKeyframe;
+  /** Whether the upstream has delivered a keyframe since its last teardown. */
+  hasKeyframe = false;
   /** Last parameter sets the stream announced — see {@link parameterSets}. */
   lastParamSets;
   /**
@@ -19750,14 +19734,7 @@ var SharedLiveSource = class {
   warmRetryTimer;
   /** Whether this warm-up has already asked its owner to replace the session. */
   sessionReplacementAsked = false;
-  /**
-   * Whether the pending watch is a REUSE watch, which any frame settles.
-   *
-   * A cold warm-up needs a keyframe: nothing can be decoded without one. A join already holds the retained
-   * keyframe, so what its watch is missing is evidence the stream is still being served — and a delta frame is
-   * that evidence. Requiring a keyframe there let the deadline outlive an actively delivering stream whose
-   * group of pictures is longer than the window, and the timeout fails EVERY consumer.
-   */
+  /** A reuse watch settles on upstream media independently of each consumer's keyframe gate. */
   reuseWatch = false;
   /** This source's opaque handle for tracing — see {@link SharedLiveSource.trace}. */
   traceId;
@@ -19765,8 +19742,8 @@ var SharedLiveSource = class {
    * How many re-issues this watch has spent with nothing arriving since it was armed.
    *
    * What a stream delivered BEFORE the current watch is no evidence about now — a reused stream's upstream may
-   * have served plenty and since been dropped by the station, and the retained keyframe replayed to a joining
-   * consumer says nothing either. Only a frame arriving after the watch was armed does, and {@link delivered}
+   * have served plenty and since been dropped by the station. Only a frame arriving after the watch was
+   * armed proves current delivery, and {@link delivered}
    * is reset to track exactly that.
    *
    * The first re-issue is therefore a keepalive: a reuse cannot yet know which case it is in, and a keepalive
@@ -19825,40 +19802,38 @@ var SharedLiveSource = class {
   }
   /**
    * Attach a new consumer. Warms the stream on the first attach (or cancels a pending linger teardown
-   * and reuses the warm stream), then replays the cached keyframe so the consumer can decode at once.
+   * and reuses the warm stream). Delivery starts at the next live keyframe so every dependent
+   * picture follows its reference pictures without a gap from a cached keyframe.
    */
   attach() {
     return this.attachConsumer(true);
   }
   /**
    * Attach at the same instant a keyframe-aligned prebuffer snapshot is taken. The returned consumer
-   * is not separately keyframe-primed, so replaying `buffered` followed by its live events neither
-   * duplicates the newest IDR nor leaves a gap at the handoff.
+   * continues after `buffered` without waiting for another keyframe or duplicating the newest IDR.
    */
   attachWithPrebuffer(seconds) {
     const consumer = this.attachConsumer(false);
     return { consumer, buffered: this.bufferedMedia(seconds) };
   }
-  attachConsumer(prime) {
+  attachConsumer(waitForKeyframe) {
     if (this.disposed)
       throw new Error("SharedLiveSource is disposed");
     const wasEmpty = this.consumers.size === 0;
-    const consumer = new ConsumerImpl((c) => this.onDetach(c), this.maxQueue);
+    const consumer = new ConsumerImpl((c) => this.onDetach(c), this.maxQueue, waitForKeyframe);
     this.consumers.add(consumer);
     if (wasEmpty)
       this.opts.onActive?.();
     if (this.lingerTimer.pending) {
       this.lingerTimer.cancel();
       if (this._state === "lingering")
-        this._state = this.lastKeyframe ? "live" : "warming";
+        this._state = this.hasKeyframe ? "live" : "warming";
       this.logger.debug(`${this.tag} re-attach in linger window \u2014 reusing warm stream (consumers=${this.consumers.size})`);
     }
     if (!this.stream)
       this.warm();
     else
       this.watchReusedStream();
-    if (prime && this.lastKeyframe)
-      consumer.prime(this.lastKeyframe);
     return consumer;
   }
   /**
@@ -19990,24 +19965,9 @@ var SharedLiveSource = class {
     current.nudge(!arrivedSinceWatch && this.fruitlessReissues > 1);
   }
   /**
-   * Watch a stream this consumer joined rather than warmed, so a dead one cannot pass for a live one.
-   *
-   * A reused stream hands a joining consumer the retained keyframe at once, which is evidence about the past:
-   * it says the stream WAS being served, not that it still is. A caller commits to media on that frame — a
-   * process, a negotiated session — so a stream the station has quietly stopped serving strands it with no
-   * deadline, because warming is what arms one and a reuse skips warming by definition.
-   *
-   * The watch is the warm-up's own, deadline and retry alike, and the first frame to arrive AFTER the join
-   * clears it, that being the only frame which says the stream is still being served. A stream still serving
-   * clears it long before the deadline fires; one that is not fails its consumers exactly as a cold start that
-   * never delivered would.
-   *
-   * The start is re-issued at once and then on the retry's cadence, because a station that stopped serving a
-   * channel when its last consumer left is the very case the retry recovers: waiting the whole window to
-   * report what one re-issued start can fix is a timeout where a stream was available.
-   *
-   * Nothing is armed while a watch is already pending, so several consumers joining one reused stream share the
-   * watch the first of them started.
+   * Watch an existing upstream with the warm-up retry and deadline. Any video or audio received after
+   * the watch begins confirms delivery and settles it. Each consumer's keyframe gate remains separate.
+   * Concurrent joins share a pending watch; the first join reissues the start immediately.
    */
   watchReusedStream() {
     if (this.warmDeadlineTimer.pending || this.warmRetryTimer !== void 0)
@@ -20056,7 +20016,7 @@ var SharedLiveSource = class {
     this.clearBudget();
     this.budgetTimer.arm(timerMs(ms, this.batteryBudgetMs), () => this.onBudgetExpire());
   }
-  /** Settle a reuse watch on any frame — the join already holds a decodable picture. */
+  /** Settle a reuse watch on any upstream frame without changing consumer keyframe gates. */
   settleReuseWatch() {
     if (!this.reuseWatch)
       return;
@@ -20118,7 +20078,7 @@ var SharedLiveSource = class {
     this.lastParamSets = updatedParamSets(frame.data, this.lastParamSets);
     const item = { kind: "video", frame, timestampMs: Date.now(), config: this.configOf(frame) };
     if (frame.keyframe) {
-      this.lastKeyframe = item;
+      this.hasKeyframe = true;
       const wasWarming = this.warmRetryTimer !== void 0 || this.warmDeadlineTimer.pending;
       this.delivered.keyframe = true;
       if (this._state === "warming")
@@ -20251,7 +20211,7 @@ var SharedLiveSource = class {
     this.lingerTimer.arm(this.lingerMs, () => this.teardown("stopped"));
   }
   /**
-   * Stop + drop the underlying stream and clear the prime/ring caches. Rebuildable via attach().
+   * Stop + drop the underlying stream and clear the keyframe/ring caches. Rebuildable via attach().
    *
    * The stream reference is dropped BEFORE stopping it, because `stop()` emits `"stop"` synchronously and
    * this source listens for that — so stopping re-enters `teardown` through {@link onUpstreamEnd}. Clearing
@@ -20271,7 +20231,7 @@ var SharedLiveSource = class {
       stream?.stop();
     } catch {
     }
-    this.lastKeyframe = void 0;
+    this.hasKeyframe = false;
     this.lastParamSets = void 0;
     this.declaredGeometry = void 0;
     this.configuredFrom = void 0;
@@ -20674,8 +20634,6 @@ function openReadableFromConsumer(consumer, opts = {}) {
     if (!readable.push(value))
       consumer.pause();
   });
-  consumer.on("video", () => {
-  });
   consumer.on("stop", () => readable.push(null));
   consumer.on("error", (err) => readable.destroy(err));
   return readable;
@@ -22187,7 +22145,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
    * A {@link MediaProvider} bound to one serial — resolves the session then calls `p2p/media`.
    *
    * Every live egress here is a consumer of the SAME shared pull, so N `live()` calls collapse to one
-   * PPCS session and a live snapshot against a warm, keyframe-primed source costs no extra pull at all; a
+   * PPCS session and a live snapshot against a warm shared source costs no extra pull at all; a
    * cold source warms one and waits for a clean keyframe. Each shared egress passes its complete options
    * through because any of them may create the source, whose power and retention hints are fixed for
    * everyone who joins later. The bounded {@link MediaProvider.record} clip is the exception: it opens its