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

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

@@ -16227,6 +16227,10 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
    * change (the level-2 key arrived after an initial level-1 start), otherwise sends the 1139 nudge.
    */
   liveStartedChannels = /* @__PURE__ */ new Map();
+  /** The `cipher_id` this connection's `CMD_GATEWAYINFO` reply named, once its negotiation has read it. */
+  gatewayCipherId;
+  /** The `n` of the last `[0x01, n]` header this connection sent in the clear — see {@link nextClearCommandBytes}. */
+  clearCommandCount = 0;
   unackedLiveStarts = /* @__PURE__ */ new Map();
   liveStartRetransmitTimer;
   logger;
@@ -16424,6 +16428,7 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
     this.level2Negotiating = true;
     const generation = this.connectionGeneration;
     const cipherId = gatewayInfoCipherId(gwPayload);
+    this.gatewayCipherId = cipherId;
     this.trace({ phase: "level2-negotiating", cipherId });
     void (async () => {
       try {
@@ -16530,6 +16535,8 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
       this.level2Pending = this.cfg.resolveCipherKey !== void 0;
       this.level2Negotiating = false;
       this.level2Reprompted = false;
+      this.gatewayCipherId = void 0;
+      this.clearCommandCount = 0;
     }
     const socket = dgram.createSocket("udp4");
     this.socket = socket;
@@ -16820,7 +16827,7 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
       this.sendMediaPayloadLevel2(CMD_START_REALTIME_MEDIA, channel, accountId, {});
       return;
     }
-    const want = this.level2Key ? "l2" : "l1";
+    const want = this.level2Key ? "l2" : this.sendsInTheClear() ? "clear" : "l1";
     if (opts?.force) {
       for (const pending of this.unackedLiveStarts.values())
         if (pending.channel === channel)
@@ -16850,8 +16857,17 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
    * `video_type` is 12, and `transaction` is the millisecond timestamp as a string. The device answers a
    * start carrying these values with a keyframe; `encryptkey` is the modulus it RSA-wraps each keyframe's
    * AES media key with (unwrapped by {@link decodeVideoFrame}).
+   *
+   * With `clearMsgId`, the body of a start sent in the clear: `{accountId, encryptkey, msg_id, streamtype: 1}`
+   * only, `msg_id` being `clearMsgId`, which changes from one start to the next.
    */
-  startLiveJson(channel, accountId) {
+  startLiveJson(channel, accountId, clearMsgId) {
+    if (clearMsgId !== void 0) {
+      return Buffer.from(JSON.stringify({
+        commandType: CMD_START_LIVE,
+        data: { accountId, encryptkey: this.rsaModulus(), msg_id: clearMsgId, streamtype: 1 }
+      }), "utf-8");
+    }
     const now2 = Date.now();
     return Buffer.from(JSON.stringify({
       commandType: CMD_START_LIVE,
@@ -16882,25 +16898,31 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
    * (GCM, signCode 8, frame type 10) when the session has a negotiated key, else level-1 (AES-128-ECB,
    * signCode 1, frame type 11) — chosen by the session key, not the device family. The camera RSA-wraps
    * each keyframe's AES media key with the `encryptkey` modulus (unwrapped by {@link decodeVideoFrame}).
+   * A session that {@link sendsInTheClear} sends it unencrypted instead: signCode 0, frame type 0, header
+   * bytes `[0x01, n]` from {@link nextClearCommandBytes}, and `n` as the body's `msg_id`.
    */
   sendStartLiveOwnSession(channel, accountId) {
     if (!this.connectAddress)
       return;
-    const plain = this.startLiveJson(channel, accountId);
     let payload;
     let signCode;
     let magic;
     let frameType;
     if (this.level2Key) {
-      const enc2 = this.encryptLevel2(plain);
+      const enc2 = this.encryptLevel2(this.startLiveJson(channel, accountId));
       if (!enc2)
         return;
       payload = enc2;
       signCode = 8;
       magic = [8, 0];
       frameType = START_LIVE_FRAME_TYPE_L2;
+    } else if (this.sendsInTheClear()) {
+      magic = this.nextClearCommandBytes();
+      payload = this.startLiveJson(channel, accountId, magic[1]);
+      signCode = 0;
+      frameType = 0;
     } else {
-      payload = encryptP2PData(paddingP2PData(plain), this.level1Key);
+      payload = encryptP2PData(paddingP2PData(this.startLiveJson(channel, accountId)), this.level1Key);
       signCode = 1;
       magic = [1, 0];
       frameType = START_LIVE_FRAME_TYPE_L1;
@@ -16920,6 +16942,21 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
     this.armLiveStartRetransmit();
     this.send(this.connectAddress, RequestMessageType.DATA, data);
   }
+  /**
+   * Whether this session's own-session start and stop go in the clear: its `CMD_GATEWAYINFO` reply named
+   * `cipher_id` 0.
+   */
+  sendsInTheClear() {
+    return this.gatewayCipherId === 0;
+  }
+  /**
+   * Header bytes 10-11 of this connection's next command sent in the clear: `[0x01, n]`, with `n` counting
+   * those commands from 1 and never 0. A retransmit repeats its `n`, and the device's reply echoes it.
+   */
+  nextClearCommandBytes() {
+    this.clearCommandCount = this.clearCommandCount % 255 + 1;
+    return [1, this.clearCommandCount];
+  }
   /**
    * Repeat unacknowledged own-session live starts until the device takes one. Runs only while a start is
    * outstanding.
@@ -17082,6 +17119,8 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
    *    `uint32`, the same 4-byte body as the attached talkback frames. The app sends this frame on closing
    *    an own-session camera's live view; the camera stops streaming on it within a second, and keeps
    *    streaming through the 1350-wrapped form.
+   *  - own-session on a session that {@link sendsInTheClear}: the same 4-byte body unencrypted, signCode 0,
+   *    header bytes from {@link nextClearCommandBytes}.
    *  - without a level-2 key: the bare 1004 command.
    */
   stopLiveMedia(channel = STATION_CHANNEL3, accountId = "", homeBaseAttached = false) {
@@ -17094,12 +17133,19 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
       clearInterval(this.liveStartRetransmitTimer);
       this.liveStartRetransmitTimer = void 0;
     }
+    const body = Buffer.allocUnsafe(4);
+    body.writeUInt32LE(channel >>> 0, 0);
     if (this.level2Key && !homeBaseAttached) {
-      const body = Buffer.allocUnsafe(4);
-      body.writeUInt32LE(channel >>> 0, 0);
       this.sendRawLevel2Bytes(body, channel, CMD_STOP_REALTIME_MEDIA, 8);
     } else if (this.level2Key) {
       this.sendMediaPayloadLevel2(CMD_STOP_REALTIME_MEDIA, channel, accountId, {});
+    } else if (!homeBaseAttached && this.sendsInTheClear() && this.connectAddress) {
+      const data = Buffer.concat([
+        buildCommandHeader(this.seqNumber, CMD_STOP_REALTIME_MEDIA),
+        buildRawCommandPayload(body, channel, 0, this.nextClearCommandBytes(), 0)
+      ]);
+      this.seqNumber = this.seqNumber + 1 & 65535;
+      this.send(this.connectAddress, RequestMessageType.DATA, data);
     } else {
       this.sendCommand(CMD_STOP_REALTIME_MEDIA, channel);
     }
@@ -19128,10 +19174,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 +19193,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 +19203,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 +19593,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 +19661,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 +19706,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 +19761,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 +19780,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 +19788,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 +19848,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 +20011,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 +20062,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 +20124,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 +20257,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 +20277,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 +20680,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 +22191,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