@mega-yfue/eufy-sdk 0.5.0-beta.17 → 0.5.0-beta.19

package/dist/core/contracts.d.ts

@@ -548,6 +548,8 @@ export interface LiveVideoConfig {
  * 7 → `mp4a.40.39`); it fails the stream on anything else.
  */
 export type AudioCodec = "aac-lc" | "aac-eld" | "g711a";
+/** The codec a camera's speaker plays: `aac-eld` on a camera whose speaker plays it, `aac-lc` otherwise. */
+export type TalkbackCodec = Extract<AudioCodec, "aac-lc" | "aac-eld">;
 /**
  * One audio access unit, carrying the codec the station declared for it.
  *
@@ -877,10 +879,11 @@ export interface MediaProvider {
     }): Promise<Record<string, unknown>>;
 }
 /**
- * An encoder that turns raw PCM into AAC-LC frames, supplied by the CALLER. The SDK ships none: the
- * device's audio path is fixed at AAC-LC 16 kHz mono, and every plausible encoder is either a native
+ * An encoder that turns raw PCM into AAC-LC frames, supplied by the CALLER. The SDK ships none: an
+ * `aac-lc` speaker plays AAC-LC 16 kHz mono, and every plausible encoder is either a native
  * dependency or an external process, both of which belong to the host rather than to a protocol SDK.
- * It is unnecessary where the audio is already AAC — see {@link TalkbackHandle}.
+ * It is unnecessary where the audio is already AAC — see {@link TalkbackHandle}. A camera whose speaker
+ * plays `aac-eld` refuses an encoder: a talkback opened with one is rejected before the speaker path opens.
  *
  * `encode` receives 16-bit little-endian mono PCM at 16 kHz and returns whole ADTS frames, zero or
  * more per call (an encoder buffers until it has a full 1024-sample block). `flush` drains a partial
@@ -895,17 +898,19 @@ export interface AacEncoder {
  * A live talkback session: audio pushed from the host to a camera's speaker, the mirror of
  * {@link LiveStreamHandle}'s inbound feed.
  *
- * Audio must be **AAC-LC, 16 kHz, mono, in ADTS frames** — what the device's path is fixed at, so a
- * stream at another rate or channel count is rejected rather than resampled (it would otherwise play
- * at the wrong pitch and speed). Feed it either way:
+ * Audio must be in the codec the camera's speaker plays, {@link TalkbackHandle.codec}:
  *
- *  - **ADTS AAC** — the default. Chunk boundaries are irrelevant; frames are recovered from the
- *    stream, so piping an encoder's output straight in works.
- *  - **PCM** — only when the handle was opened with an {@link AacEncoder}, which then does the
- *    conversion. `write` takes 16-bit little-endian mono PCM at 16 kHz instead.
+ *  - **`aac-lc`:** AAC-LC, 16 kHz, mono, in ADTS frames, through `write` / `writable()`. Chunk boundaries are
+ *    irrelevant; frames are recovered from the stream. With an {@link AacEncoder}, `write` takes 16-bit
+ *    little-endian mono PCM at 16 kHz instead.
+ *  - **`aac-eld`:** one raw AAC-ELD access unit with LD-SBR (16 kHz, mono, 512 samples) per `write`, or per
+ *    object-mode `writable()` write. No encoder applies.
  *
- * Frames are **paced** at their own playback rate (64 ms each) rather than flushed as fast as they
- * arrive, so feeding a file plays it at speed instead of overrunning the device. A live source keeps
+ * An `aac-lc` stream at another rate or channel count is rejected rather than resampled. An `aac-eld` unit longer
+ * than the device accepts is refused with an `error`.
+ *
+ * Frames are **paced** at their own playback rate (64 ms for `aac-lc`, 32 ms for `aac-eld`) rather than flushed as
+ * fast as they arrive, so feeding a file plays it at speed instead of overrunning the device. A live source keeps
  * the queue near-empty and is unaffected.
  *
  * @example
@@ -917,7 +922,16 @@ export interface AacEncoder {
  * ```
  */
 export interface TalkbackHandle {
-    /** Queue audio — ADTS frames, or PCM when an encoder was supplied. Partial frames are held. */
+    /**
+     * The codec this camera's speaker plays: `aac-eld` on a camera whose speaker plays it and whose stream on the same
+     * media session carries `aac-eld`, `aac-lc` otherwise, including when that stream carries no audio. It decides
+     * what {@link write} and {@link writable} take.
+     */
+    readonly codec: TalkbackCodec;
+    /**
+     * Queue audio: ADTS frames or PCM for `aac-lc`, one access unit per call for `aac-eld`. Partial ADTS frames are
+     * held.
+     */
     write(chunk: Buffer): void;
     /**
      * A `node:stream` Writable over {@link write}, for piping a file or an encoder's stdout. Applies
@@ -940,7 +954,7 @@ export interface TalkbackHandle {
      *
      * This deliberately does NOT fire on a merely-empty queue. A realtime source keeps the queue near
      * empty by design, so "queue is empty" arrives after the very first frame and stopping on it would
-     * cut the clip to 64 ms. {@link pending} is the instantaneous depth.
+     * cut the clip to one frame. {@link pending} is the instantaneous depth.
      */
     on(event: "finished", listener: () => void): this;
     /**

package/dist/index.js

@@ -6233,6 +6233,9 @@ var LIGHT_MEMBERS = {
    * This is the switch a user changes and expects to STAY changed. {@link isOn} is a different fact:
    * the lamp being lit right now, driven by whichever
    * client is streaming — the vendor app lights it for a live view and drops it on quitting.
+   *
+   * The T8423 write takes the session-chosen level; level-1 int+string was verified live on a standalone
+   * unit.
    */
   spotlightEnabled: {
     param: LIGHT_CMD.SPOTLIGHT_ENABLE,
@@ -6240,7 +6243,7 @@ var LIGHT_MEMBERS = {
     kind: "boolean",
     provenance: "verified",
     description: "The spotlight master switch, distinct from the on/off above \u2014 whether the spotlight may light at all. Read verified live on a T8170 (param 1403, direct polarity: 1 = enabled).",
-    write: (v, ctx) => directBinary(LIGHT_CMD.SPOTLIGHT_ENABLE, asBool(v) ? 1 : 0, ctx),
+    write: (v, ctx) => setScalar(LIGHT_CMD.SPOTLIGHT_ENABLE, asBool(v) ? 1 : 0, ctx, ctx.deviceType === DeviceType.FLOODLIGHT_CAMERA_8423 ? "auto" : "direct-binary"),
     writeAs: "setEnabled"
   }
 };
@@ -19920,7 +19923,8 @@ var AdtsFrameReader = class {
 };
 
 // dist/transport/p2p/talkback.js
-var DEFAULT_HIGH_WATER_FRAMES = Math.ceil(2e3 / AAC_FRAME_MS);
+var HIGH_WATER_MS = 2e3;
+var TALKBACK_ELD_FRAME_MS = 32;
 var DEFAULT_IDLE_TIMEOUT_MS = 3e4;
 var Talkback = class extends EventEmitter5 {
   sink;
@@ -19928,7 +19932,8 @@ var Talkback = class extends EventEmitter5 {
   reader = new AdtsFrameReader();
   queue = [];
   logger;
-  highWater;
+  /** Playback duration of one queued frame, the pacer's step: 64 ms for `aac-lc`, 32 ms for `aac-eld`. */
+  frameMs = AAC_FRAME_MS;
   idleTimeoutMs;
   timer;
   started = false;
@@ -19954,9 +19959,14 @@ var Talkback = class extends EventEmitter5 {
     this.sink = sink;
     this.opts = opts;
     this.logger = opts.logger ?? noopLogger;
-    this.highWater = opts.highWaterFrames ?? DEFAULT_HIGH_WATER_FRAMES;
     this.idleTimeoutMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
   }
+  /** Frames the pacing queue holds before a writable applies backpressure: {@link HIGH_WATER_MS} of this codec. */
+  get highWater() {
+    return this.opts.highWaterFrames ?? Math.ceil(HIGH_WATER_MS / this.frameMs);
+  }
+  /** The codec this talkback sends, set by {@link start}. */
+  codec = "aac-lc";
   /** Frames still queued for the wire. */
   get pending() {
     return this.queue.length;
@@ -19965,25 +19975,33 @@ var Talkback = class extends EventEmitter5 {
    * Open the device's talkback path and begin the pacing tick. Throws when the topology's control
    * frame could not be sent — for a HomeBase-attached camera that means the level-2 key was never
    * negotiated, which would otherwise leave a silent session that accepts audio nobody hears.
+   *
+   * `codec` is the codec the camera's speaker plays; it fixes the input this talkback accepts and the pacing step.
    */
-  start() {
+  start(codec) {
     if (this.started)
       return this;
+    if (codec === "aac-eld" && this.opts.encoder) {
+      throw new Error("talkback: this camera plays aac-eld; an AacEncoder produces aac-lc");
+    }
+    this.codec = codec;
+    this.frameMs = codec === "aac-eld" ? TALKBACK_ELD_FRAME_MS : AAC_FRAME_MS;
     if (!this.sink.startTalkback(this.opts.channel, this.opts.homeBaseAttached)) {
       throw new Error(`talkback: could not open the audio path on channel ${this.opts.channel}`);
     }
     this.started = true;
     const now2 = Date.now();
-    this.nextDueAt = now2 + AAC_FRAME_MS;
+    this.nextDueAt = now2 + this.frameMs;
     this.lastWriteAt = now2;
-    this.timer = setInterval(() => this.tick(), AAC_FRAME_MS);
+    this.timer = setInterval(() => this.tick(), this.frameMs);
     this.timer.unref?.();
     this.sink.on?.("audioGap", this.onAudioGap);
     return this;
   }
   /**
-   * Queue audio. Bytes are ADTS AAC, or PCM when an encoder was supplied; either way the input is
-   * treated as a stream, so a chunk carrying part of a frame is held until the rest arrives.
+   * Queue audio in the codec this talkback sends. For `aac-lc` the bytes are ADTS, or PCM when an encoder was
+   * supplied, read as a stream, so a chunk carrying part of a frame is held until the rest arrives. For `aac-eld`
+   * each call is one whole access unit; a unit over the device's length limit is dropped with an `error`.
    *
    * Audio written after {@link end} is dropped with an `error` rather than queued: `finished` has
    * either already fired or is owed on the frames written before it, so a late chunk would either play
@@ -19997,6 +20015,15 @@ var Talkback = class extends EventEmitter5 {
       return;
     }
     this.lastWriteAt = Date.now();
+    if (this.codec === "aac-eld") {
+      if (chunk.length > MAX_AUDIO_FRAME_BYTES) {
+        this.fail(new Error(`talkback: frame of ${chunk.length} B exceeds the device's ${MAX_AUDIO_FRAME_BYTES} B limit`));
+        return;
+      }
+      if (chunk.length)
+        this.queue.push(chunk);
+      return;
+    }
     if (!this.opts.encoder) {
       this.enqueue(this.reader.push(chunk));
       return;
@@ -20065,14 +20092,14 @@ var Talkback = class extends EventEmitter5 {
       return;
     const now2 = Date.now();
     if (!this.queue.length) {
-      this.nextDueAt = now2 + AAC_FRAME_MS;
+      this.nextDueAt = now2 + this.frameMs;
       this.idleCheck(now2);
       this.announceFinishIfDone();
       return;
     }
     while (this.queue.length && now2 >= this.nextDueAt) {
       const frame = this.queue.shift();
-      this.nextDueAt += AAC_FRAME_MS;
+      this.nextDueAt += this.frameMs;
       try {
         this.sink.sendAudioFrame(this.opts.channel, frame);
       } catch (e) {
@@ -20130,9 +20157,11 @@ var Talkback = class extends EventEmitter5 {
   /**
    * A Writable over {@link write} that withholds its callback while the queue is at the high-water
    * mark — which is what turns `pipe()` from a file into playback at speed rather than a memory spike.
+   * For `aac-eld` it is object-mode: each write is one access unit.
    */
   writable() {
     return new Writable({
+      objectMode: this.codec === "aac-eld",
       write: (chunk, _enc, cb) => {
         this.write(chunk);
         if (this.queue.length < this.highWater)
@@ -20860,6 +20889,30 @@ var P2P_STATION_WAITS = {
   level2Settle: LEVEL2_SETTLE_MS
 };
 var RTSP_URL_READ_TIMEOUT_MS = 12e3;
+var TALKBACK_CODEC_WAIT_MS = 3e3;
+var ELD_TALKBACK_MODELS = /* @__PURE__ */ new Set(["T8410C"]);
+function speakerCodec(consumer, talk, timeoutMs) {
+  return new Promise((resolve) => {
+    let timer;
+    const settle = (codec) => {
+      clearTimeout(timer);
+      consumer.off("video", onVideo);
+      consumer.off("audio", onAudio);
+      consumer.off("stop", onStop);
+      talk.off("stop", onStop);
+      resolve(codec);
+    };
+    const onVideo = () => {
+      timer ??= setTimeout(() => settle("aac-lc"), timeoutMs);
+    };
+    const onAudio = (frame) => settle(frame.codec === "aac-eld" ? "aac-eld" : "aac-lc");
+    const onStop = () => settle("aac-lc");
+    consumer.on("video", onVideo);
+    consumer.on("audio", onAudio);
+    consumer.on("stop", onStop);
+    talk.once("stop", onStop);
+  });
+}
 var SHARED_LIVE_OPT_KEYS = [
   "eccPrivateKey",
   "keepAliveMs",
@@ -21413,6 +21466,11 @@ var P2PCommandRouter = class _P2PCommandRouter {
    * stream costs nothing extra and a talkback on an otherwise idle camera opens the session it needs
    * instead of playing into silence.
    *
+   * **On a model in {@link ELD_TALKBACK_MODELS}, the speaker plays the codec the camera sends.** So the first
+   * audio frame of the media session this talkback holds decides its codec ({@link speakerCodec}), within
+   * {@link TALKBACK_CODEC_WAIT_MS} of the session's first frame, and the claim is re-checked after that wait as
+   * after the warm-up. Every other model opens `aac-lc` at once.
+   *
    * The level-2 key is waited for softly: only the HomeBase-attached path requires it, and
    * {@link Talkback.start} reports that failure precisely, so a hard wait here would reject an
    * own-session camera that legitimately never negotiates one.
@@ -21482,7 +21540,11 @@ var P2PCommandRouter = class _P2PCommandRouter {
       consumer.on("stop", () => {
         void talk.stop().catch((e) => logger.warn?.(`talkback: stop for ${sn} failed: ${String(e)}`));
       });
-      return talk.start();
+      const codec = ELD_TALKBACK_MODELS.has(this.recordFor(sn)?.model ?? "") ? await speakerCodec(consumer, talk, TALKBACK_CODEC_WAIT_MS) : "aac-lc";
+      if (this.talkbacks.get(key) !== talk) {
+        throw new Error(`talkback: ${sn} was closed while its speaker codec was being read`);
+      }
+      return talk.start(codec);
     } catch (e) {
       if (this.talkbacks.get(key) === talk)
         this.talkbacks.delete(key);