@mega-yfue/eufy-sdk 0.4.0-beta.14 → 0.4.0-beta.16

package/dist/core/contracts.d.ts

@@ -150,6 +150,39 @@ export declare class DeviceChannelUnresolvedError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Why {@link MediaProvider.downloadRecording} returned no recording.
+ *
+ * - `invalid-recording` — the recording name is not one the station could hold.
+ * - `key-unavailable` — the key the recording was stored under could not be obtained.
+ * - `no-data` — the station sent nothing within the wait.
+ * - `incomplete` — the transfer ended before the station's finish frame.
+ * - `undecodable` — data arrived but no video frame could be decoded from it.
+ */
+export type RecordingDownloadFailureReason = "invalid-recording" | "key-unavailable" | "no-data" | "incomplete" | "undecodable";
+/** Thrown by {@link MediaProvider.downloadRecording} when no recording could be returned. */
+export declare class RecordingDownloadError extends Error {
+    readonly reason: RecordingDownloadFailureReason;
+    constructor(reason: RecordingDownloadFailureReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A recording downloaded from the station, as elementary streams.
+ *
+ * `video` is Annex-B H.264 in decode order, `audio` AAC-LC 16 kHz mono in ADTS framing (absent when the
+ * recording carried none that could be decoded). `frames` counts the distinct video frames received,
+ * `missingFrames` the ones the camera numbered but that never arrived, and `durationMs` spans the first
+ * to the last received frame by the camera's own timestamps; `fps` is derived from those two stamps.
+ */
+export interface RecordingDownload {
+    video: Buffer;
+    audio?: Buffer;
+    frames: number;
+    missingFrames: number;
+    durationMs: number;
+    fps: number;
+}
 /**
  * How a live stream ended before its first video keyframe: the warm-up deadline elapsed, the source
  * reported an error, or the source ended on its own.
@@ -804,6 +837,16 @@ export interface MediaProvider {
     talkback?(opts?: {
         encoder?: AacEncoder;
     } & SharedSourceHints): Promise<TalkbackHandle>;
+    /**
+     * Download one recording the camera's station stored, identified by the recording name and cipher id of
+     * the event. One download runs at a time per station. Rejects with {@link RecordingDownloadError}.
+     * Optional, and absent on a camera whose station's recording download is unverified.
+     */
+    downloadRecording?(opts: {
+        recording: string;
+        cipherId: number;
+        timeoutMs?: number;
+    } & AbortableCall): Promise<RecordingDownload>;
     /**
      * Generic P2P request/reply query: send a `SET_PAYLOAD` sub-command and resolve with the reply
      * frame's `payload` (the reply whose `cmd` echoes `subCmd`). Transport-only — the caller owns the

package/dist/index.js

@@ -1147,6 +1147,14 @@ var DeviceChannelUnresolvedError = class extends Error {
     this.name = "DeviceChannelUnresolvedError";
   }
 };
+var RecordingDownloadError = class extends Error {
+  reason;
+  constructor(reason, message, options) {
+    super(message, options);
+    this.reason = reason;
+    this.name = "RecordingDownloadError";
+  }
+};
 var LiveStreamStartError = class extends Error {
   reason;
   stage;
@@ -5702,6 +5710,7 @@ var CAMERA_MEMBERS = {
     refuseWhenDisabled(ctx, read);
     return m.recordFragments({ powered: poweredOf(ctx), ...opts });
   }), "Continuous fragmented-MP4 (CMAF) recording."),
+  downloadRecording: provided("media", (m) => m.downloadRecording && ((opts) => m.downloadRecording(opts)), "Download a recording the station holds \u2192 H.264 and AAC elementary streams."),
   /**
    * Push audio from the host to this camera's speaker. Gated on the **speaker** param specifically —
    * not the `audio` capability, which resolves on a microphone alone and would advertise a speaker the
@@ -14342,6 +14351,7 @@ __export(codec_exports, {
   buildLookupWithKeyPayload2: () => buildLookupWithKeyPayload2,
   buildRawCommandPayload: () => buildRawCommandPayload,
   buildStringCommandPayload: () => buildStringCommandPayload,
+  buildStringPairCommandPayload: () => buildStringPairCommandPayload,
   buildVoidCommandPayload: () => buildVoidCommandPayload,
   decodeP2PCloudIPs: () => decodeP2PCloudIPs,
   decryptP2PData: () => decryptP2PData,
@@ -14378,6 +14388,11 @@ var ResponseMessageType = {
   LOOKUP_ADDR: Buffer.from([241, 64]),
   LOOKUP_ADDR2: Buffer.from([241, 130]),
   CAM_ID: Buffer.from([241, 66]),
+  /**
+   * The device's own address record, sent in answer to CHECK_CAM ahead of CAM_ID: its 20-byte device id, one
+   * record in `encodeSelfAddress`'s shape naming the address it answers from, then 8 zero bytes (44-byte payload).
+   */
+  CAM_ADDR: Buffer.from([241, 67]),
   TURN_SERVER_CAM_ID: Buffer.from([241, 132]),
   PING: Buffer.from([241, 224]),
   PONG: Buffer.from([241, 225]),
@@ -14589,6 +14604,12 @@ function buildIntStringCommandPayload(value, valueSub, strValue, channel = 0, ke
     data
   ]);
 }
+function buildStringPairCommandPayload(strValue, strValueSub, channel = 0, key, encType = 1) {
+  const encrypted = !!key && key.length === 16;
+  const body = Buffer.concat([Buffer.alloc(5), stringWithLength(strValue), stringWithLength(strValueSub)]);
+  const data = encrypted ? encryptP2PData(paddingP2PData(body), key) : body;
+  return buildRawCommandPayload(data, channel, encrypted ? encType : 0);
+}
 function buildRawCommandPayload(data, channel = 0, signCode = 0, magic = [1, 0], streamId = 0) {
   const header = Buffer.allocUnsafe(2);
   header.writeUInt16LE(data.length, 0);
@@ -15737,6 +15758,9 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
    * straddling a level-2 wait on a camera whose failure to deliver video had a separate cause, and did not
    * recur across later probes of it. Correlate an unmodelled type against a WORKING session before reading it
    * as a cause.
+   *
+   * CAM_ADDR is recognised and dropped: it names the address the device is already answering from, and the
+   * CAM_ID that follows it is what completes the connect.
    */
   onMessage(msg, rinfo, socket = this.socket) {
     if (!socket)
@@ -15767,7 +15791,7 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
     } else if (hasHeader(msg, ResponseMessageType.DATA)) {
       if (this.connected)
         this.onData(msg, { host: rinfo.address, port: rinfo.port });
-    } else {
+    } else if (!hasHeader(msg, ResponseMessageType.CAM_ADDR)) {
       this.logger.debug(`[p2p] ${this.cfg.stationSn} UNHANDLED payload hex: ${msg.toString("hex")}`);
     }
   }
@@ -16058,6 +16082,17 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
     this.seqNumber = this.seqNumber + 1 & 65535;
     this.send(this.connectAddress, RequestMessageType.DATA, data);
   }
+  /** Send a level-1 {@link buildStringPairCommandPayload} command on `channel`. */
+  sendStringPairCommand(commandType, strValue, strValueSub, channel) {
+    if (!this.connectAddress)
+      throw new Error(`P2P session ${this.cfg.stationSn} is not connected`);
+    const data = Buffer.concat([
+      buildCommandHeader(this.seqNumber, commandType),
+      buildStringPairCommandPayload(strValue, strValueSub, channel, this.level1Key, 1)
+    ]);
+    this.seqNumber = this.seqNumber + 1 & 65535;
+    this.send(this.connectAddress, RequestMessageType.DATA, data);
+  }
   /**
    * Send a **level-2 (AES-256-GCM, signCode 8) control payload** to a HomeBase-attached device. The
    * target camera is selected by `channel` (= device_channel) + the `mChannel` envelope — the same
@@ -18236,6 +18271,282 @@ function annexbToJpeg(annexb, spawn2) {
   });
 }
 
+// dist/transport/p2p/recording-download.js
+import { createDecipheriv as createDecipheriv7 } from "node:crypto";
+
+// dist/transport/p2p/adts.js
+var PROFILE_AAC_LC = 1;
+var FREQ_INDEX_16K = 8;
+var CHANNELS_MONO = 1;
+var AAC_SAMPLES_PER_FRAME = 1024;
+var AAC_SAMPLE_RATE = 16e3;
+var AAC_FRAME_MS = AAC_SAMPLES_PER_FRAME * 1e3 / AAC_SAMPLE_RATE;
+var MAX_AUDIO_FRAME_BYTES = 640;
+var HEADER_LEN_NO_CRC = 7;
+function parseAdtsHeader(buf, offset = 0) {
+  if (offset + HEADER_LEN_NO_CRC > buf.length)
+    return void 0;
+  if (buf[offset] !== 255 || (buf[offset + 1] & 240) !== 240)
+    return void 0;
+  const headerLength = buf[offset + 1] & 1 ? 7 : 9;
+  const frameLength = (buf[offset + 3] & 3) << 11 | buf[offset + 4] << 3 | (buf[offset + 5] & 224) >> 5;
+  if (frameLength < headerLength)
+    return void 0;
+  return {
+    frameLength,
+    headerLength,
+    profile: (buf[offset + 2] & 192) >> 6,
+    frequencyIndex: (buf[offset + 2] & 60) >> 2,
+    channels: (buf[offset + 2] & 1) << 2 | (buf[offset + 3] & 192) >> 6
+  };
+}
+function buildAdtsHeader(payloadLength) {
+  const frameLength = payloadLength + HEADER_LEN_NO_CRC;
+  return Buffer.from([
+    255,
+    241,
+    PROFILE_AAC_LC << 6 | FREQ_INDEX_16K << 2 | CHANNELS_MONO >> 2,
+    (CHANNELS_MONO & 3) << 6 | frameLength >> 11 & 3,
+    frameLength >> 3 & 255,
+    (frameLength & 7) << 5 | 31,
+    252
+  ]);
+}
+function isSupportedAdts(h) {
+  return h.profile === PROFILE_AAC_LC && h.frequencyIndex === FREQ_INDEX_16K && h.channels === CHANNELS_MONO;
+}
+function describeAdts(h) {
+  const rate = ADTS_SAMPLE_RATES[h.frequencyIndex] ?? `index ${h.frequencyIndex}`;
+  const profile = h.profile === PROFILE_AAC_LC ? "AAC-LC" : `profile field ${h.profile}`;
+  return `${profile}, ${rate} Hz, ${h.channels} channel(s)`;
+}
+var ADTS_SAMPLE_RATES = [
+  96e3,
+  88200,
+  64e3,
+  48e3,
+  44100,
+  32e3,
+  24e3,
+  22050,
+  16e3,
+  12e3,
+  11025,
+  8e3,
+  7350
+];
+var AdtsFrameReader = class {
+  buffered = Buffer.alloc(0);
+  /**
+   * Append `chunk` and return every complete frame now available, each a standalone buffer that still
+   * carries its own ADTS header (the device expects the header on the wire).
+   */
+  push(chunk) {
+    this.buffered = this.buffered.length ? Buffer.concat([this.buffered, chunk]) : chunk;
+    const frames = [];
+    let at = 0;
+    for (; ; ) {
+      const h = parseAdtsHeader(this.buffered, at);
+      if (!h) {
+        if (at + HEADER_LEN_NO_CRC > this.buffered.length)
+          break;
+        at++;
+        continue;
+      }
+      if (at + h.frameLength > this.buffered.length)
+        break;
+      frames.push(this.buffered.subarray(at, at + h.frameLength));
+      at += h.frameLength;
+    }
+    this.buffered = at ? this.buffered.subarray(at) : this.buffered;
+    return frames;
+  }
+  /** Bytes held back awaiting the rest of their frame — non-zero mid-stream, zero on a clean boundary. */
+  get pending() {
+    return this.buffered.length;
+  }
+};
+
+// dist/transport/p2p/recording-download.js
+var RECORDING_DATA_TYPE = 3;
+var VIDEO_HEADER_LEN2 = 22;
+var AUDIO_HEADER_LEN2 = 16;
+var AUDIO_NONCE_START = 32;
+var AUDIO_BODY_START = 44;
+var AUDIO_CODEC_AAC_LC = 0;
+var FIRST_FRAME_WAIT_MS = 2e4;
+var IDLE_END_MS = 15e3;
+var DEFAULT_TRANSFER_MS = 12e4;
+var MAX_TRANSFER_BYTES = 32 * 1024 * 1024;
+function homeBase2RecordingPath(channel, recording) {
+  if (!/^\d{14}$/.test(recording) || !Number.isInteger(channel) || channel < 0 || channel > 99)
+    return void 0;
+  return `/media/mmcblk0p1/Camera${String(channel).padStart(2, "0")}/${recording}.dat`;
+}
+function receiveRecording(session, request) {
+  let resolveFrames;
+  let rejectFrames;
+  const frames = new Promise((resolve, reject) => {
+    resolveFrames = resolve;
+    rejectFrames = reject;
+  });
+  let resolveDrained;
+  const drained = new Promise((resolve) => resolveDrained = resolve);
+  const limitMs = request.timeoutMs ?? DEFAULT_TRANSFER_MS;
+  let collected = [];
+  const started = Date.now();
+  let lastFrameAt = started;
+  let received = false;
+  let bytes2 = 0;
+  let draining;
+  let delivered = false;
+  let listening = true;
+  const deliver = (error) => {
+    if (delivered)
+      return;
+    delivered = true;
+    request.signal?.removeEventListener("abort", onAbort);
+    if (error)
+      rejectFrames(error);
+    else
+      resolveFrames(collected);
+  };
+  const stop = () => {
+    if (!listening)
+      return;
+    listening = false;
+    clearInterval(tick);
+    session.off("data", onData);
+    resolveDrained();
+  };
+  const incomplete = (why) => deliver(new RecordingDownloadError("incomplete", `the recording transfer ${why} before its finish frame`));
+  const drain = (why) => {
+    draining ??= why;
+    collected = [];
+  };
+  const onData = (frame) => {
+    if (frame.channel !== request.channel)
+      return;
+    if (frame.commandId === CommandType.CMD_DOWNLOAD_FINISH) {
+      if (draining)
+        incomplete(draining);
+      else
+        deliver();
+      return stop();
+    }
+    if (frame.commandId !== CommandType.CMD_VIDEO_FRAME && frame.commandId !== CommandType.CMD_AUDIO_FRAME)
+      return;
+    if (frame.dataType !== RECORDING_DATA_TYPE)
+      return;
+    received = true;
+    lastFrameAt = Date.now();
+    if (draining)
+      return;
+    collected.push({ commandId: frame.commandId, signCode: frame.signCode, raw: Buffer.from(frame.raw) });
+    bytes2 += frame.raw.length;
+    if (bytes2 >= MAX_TRANSFER_BYTES)
+      drain(`reached ${MAX_TRANSFER_BYTES} bytes`);
+  };
+  const onAbort = () => {
+    deliver(request.signal?.reason instanceof Error ? request.signal.reason : new Error("aborted"));
+    drain("was aborted");
+  };
+  const tick = setInterval(() => {
+    const now2 = Date.now();
+    if (!received && now2 - started > FIRST_FRAME_WAIT_MS) {
+      deliver(new RecordingDownloadError("no-data", `the station sent nothing within ${FIRST_FRAME_WAIT_MS} ms`));
+      stop();
+    } else if (received && now2 - lastFrameAt > IDLE_END_MS) {
+      incomplete(draining ?? `went quiet for ${IDLE_END_MS} ms`);
+      stop();
+    } else if (now2 - started > 2 * limitMs && draining) {
+      incomplete(draining);
+      stop();
+    } else if (now2 - started > limitMs) {
+      drain(`ran past ${limitMs} ms`);
+    }
+  }, 250);
+  if (request.signal?.aborted) {
+    onAbort();
+    stop();
+    return { frames, drained };
+  }
+  request.signal?.addEventListener("abort", onAbort, { once: true });
+  session.on("data", onData);
+  try {
+    session.sendStringPairCommand(CommandType.CMD_DOWNLOAD_VIDEO, request.path, request.accountId, request.channel);
+  } catch (error) {
+    deliver(error instanceof Error ? error : new Error(String(error)));
+    stop();
+  }
+  return { frames, drained };
+}
+function openAudio(key, nonce, tag2, body) {
+  try {
+    const decipher = createDecipheriv7("aes-256-gcm", key, nonce);
+    decipher.setAAD(VIDEO_GCM_AAD);
+    decipher.setAuthTag(tag2);
+    return Buffer.concat([decipher.update(body), decipher.final()]);
+  } catch {
+    return void 0;
+  }
+}
+function decodeRecording(frames, eccPrivateKeyHex) {
+  const eccPrivateKey = Buffer.from(eccPrivateKeyHex, "hex");
+  if (eccPrivateKey.length !== 32)
+    throw new RecordingDownloadError("undecodable", "the cipher key is not a P-256 key");
+  const decoder = new VideoFrameDecoder(eccPrivateKey);
+  const video = [];
+  const audio = [];
+  const numbers = /* @__PURE__ */ new Set();
+  let firstStamp;
+  let lastStamp;
+  for (const { commandId, raw } of frames) {
+    if (commandId === CommandType.CMD_VIDEO_FRAME) {
+      const header = parseVideoFrameHeader(raw);
+      if (!header)
+        continue;
+      const h264 = header.keyframe ? decoder.decodeFrame(raw)?.h264 : raw.length >= VIDEO_HEADER_LEN2 + header.payloadLength ? raw.subarray(VIDEO_HEADER_LEN2, VIDEO_HEADER_LEN2 + header.payloadLength) : void 0;
+      if (!h264?.length)
+        continue;
+      video.push(h264);
+      numbers.add(header.sequence);
+      const stamp = raw.readUIntLE(14, 6);
+      firstStamp ??= stamp;
+      lastStamp = stamp;
+    } else if (commandId === CommandType.CMD_AUDIO_FRAME) {
+      const mediaKey = decoder.currentMediaKey;
+      if (!mediaKey || raw.length < AUDIO_BODY_START || raw[5] !== AUDIO_CODEC_AAC_LC)
+        continue;
+      const len = raw.readUInt32LE(0);
+      if (raw.length < AUDIO_BODY_START + len)
+        continue;
+      const aac = openAudio(mediaKey, raw.subarray(AUDIO_NONCE_START, AUDIO_BODY_START), raw.subarray(AUDIO_HEADER_LEN2, AUDIO_NONCE_START), raw.subarray(AUDIO_BODY_START, AUDIO_BODY_START + len));
+      if (aac?.length)
+        audio.push(buildAdtsHeader(aac.length), aac);
+    }
+  }
+  if (!video.length)
+    throw new RecordingDownloadError("undecodable", "no video frame of the recording decoded");
+  const ordered = [...numbers];
+  let missingFrames = 0;
+  for (let i = 1; i < ordered.length; i++) {
+    const step = ordered[i] - ordered[i - 1] & 65535;
+    if (step > 1 && step < 32768)
+      missingFrames += step - 1;
+  }
+  const span = ordered.length > 1 ? ordered[ordered.length - 1] - ordered[0] & 65535 : 0;
+  const durationMs = (lastStamp ?? 0) - (firstStamp ?? 0);
+  return {
+    video: Buffer.concat(video),
+    ...audio.length ? { audio: Buffer.concat(audio) } : {},
+    frames: ordered.length,
+    missingFrames,
+    durationMs,
+    fps: durationMs > 0 && span > 0 ? Math.round(span * 1e5 / durationMs) / 100 : 0
+  };
+}
+
 // dist/transport/p2p/shared-live-source.js
 import { EventEmitter as EventEmitter4 } from "node:events";
 var MAX_TIMER_DELAY_MS = 2147483647;
@@ -19358,89 +19669,6 @@ function openReadableFromConsumer(consumer, opts = {}) {
 // dist/transport/p2p/talkback.js
 import { EventEmitter as EventEmitter5 } from "node:events";
 import { Writable } from "node:stream";
-
-// dist/transport/p2p/adts.js
-var PROFILE_AAC_LC = 1;
-var FREQ_INDEX_16K = 8;
-var CHANNELS_MONO = 1;
-var AAC_SAMPLES_PER_FRAME = 1024;
-var AAC_SAMPLE_RATE = 16e3;
-var AAC_FRAME_MS = AAC_SAMPLES_PER_FRAME * 1e3 / AAC_SAMPLE_RATE;
-var MAX_AUDIO_FRAME_BYTES = 640;
-var HEADER_LEN_NO_CRC = 7;
-function parseAdtsHeader(buf, offset = 0) {
-  if (offset + HEADER_LEN_NO_CRC > buf.length)
-    return void 0;
-  if (buf[offset] !== 255 || (buf[offset + 1] & 240) !== 240)
-    return void 0;
-  const headerLength = buf[offset + 1] & 1 ? 7 : 9;
-  const frameLength = (buf[offset + 3] & 3) << 11 | buf[offset + 4] << 3 | (buf[offset + 5] & 224) >> 5;
-  if (frameLength < headerLength)
-    return void 0;
-  return {
-    frameLength,
-    headerLength,
-    profile: (buf[offset + 2] & 192) >> 6,
-    frequencyIndex: (buf[offset + 2] & 60) >> 2,
-    channels: (buf[offset + 2] & 1) << 2 | (buf[offset + 3] & 192) >> 6
-  };
-}
-function isSupportedAdts(h) {
-  return h.profile === PROFILE_AAC_LC && h.frequencyIndex === FREQ_INDEX_16K && h.channels === CHANNELS_MONO;
-}
-function describeAdts(h) {
-  const rate = ADTS_SAMPLE_RATES[h.frequencyIndex] ?? `index ${h.frequencyIndex}`;
-  const profile = h.profile === PROFILE_AAC_LC ? "AAC-LC" : `profile field ${h.profile}`;
-  return `${profile}, ${rate} Hz, ${h.channels} channel(s)`;
-}
-var ADTS_SAMPLE_RATES = [
-  96e3,
-  88200,
-  64e3,
-  48e3,
-  44100,
-  32e3,
-  24e3,
-  22050,
-  16e3,
-  12e3,
-  11025,
-  8e3,
-  7350
-];
-var AdtsFrameReader = class {
-  buffered = Buffer.alloc(0);
-  /**
-   * Append `chunk` and return every complete frame now available, each a standalone buffer that still
-   * carries its own ADTS header (the device expects the header on the wire).
-   */
-  push(chunk) {
-    this.buffered = this.buffered.length ? Buffer.concat([this.buffered, chunk]) : chunk;
-    const frames = [];
-    let at = 0;
-    for (; ; ) {
-      const h = parseAdtsHeader(this.buffered, at);
-      if (!h) {
-        if (at + HEADER_LEN_NO_CRC > this.buffered.length)
-          break;
-        at++;
-        continue;
-      }
-      if (at + h.frameLength > this.buffered.length)
-        break;
-      frames.push(this.buffered.subarray(at, at + h.frameLength));
-      at += h.frameLength;
-    }
-    this.buffered = at ? this.buffered.subarray(at) : this.buffered;
-    return frames;
-  }
-  /** Bytes held back awaiting the rest of their frame — non-zero mid-stream, zero on a clean boundary. */
-  get pending() {
-    return this.buffered.length;
-  }
-};
-
-// dist/transport/p2p/talkback.js
 var DEFAULT_HIGH_WATER_FRAMES = Math.ceil(2e3 / AAC_FRAME_MS);
 var DEFAULT_IDLE_TIMEOUT_MS = 3e4;
 var Talkback = class extends EventEmitter5 {
@@ -20416,6 +20644,8 @@ var P2PCommandRouter = class _P2PCommandRouter {
   talkbacks = /* @__PURE__ */ new Map();
   /** cipher_id → ECC private key (one eufylife get_ciphers call per cipher), shared across (re)opens. */
   cipherKeyCache = /* @__PURE__ */ new Map();
+  /** The recording download in flight per station; a station serves one at a time. */
+  recordingDownloads = /* @__PURE__ */ new Map();
   constructor(deps) {
     this.deps = deps;
     this.manager = new SessionManager({
@@ -20628,28 +20858,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
       localAddress,
       dskKey,
       noBroadcast: this.deps.noBroadcast,
-      resolveCipherKey: async (cipherId) => {
-        if (this.cipherKeyCache.has(cipherId))
-          return this.cipherKeyCache.get(cipherId);
-        let ecc;
-        try {
-          const ciphers = await this.deps.mega.getCiphers([cipherId], adminUserId, stationSn);
-          ecc = ciphers.find((c) => Number(c.cipher_id) === cipherId)?.ecc_private_key;
-          if (ecc === void 0 && ciphers[0]?.ecc_private_key !== void 0) {
-            ecc = ciphers[0].ecc_private_key;
-            this.traceOnStation(session, {
-              phase: "cipher-fallback",
-              cipherId,
-              answeredCipherId: Number(ciphers[0].cipher_id)
-            });
-          }
-        } catch (e) {
-          this.deps.onError(e instanceof Error ? e : new Error(String(e)));
-        }
-        if (ecc !== void 0)
-          this.cipherKeyCache.set(cipherId, ecc);
-        return ecc;
-      },
+      resolveCipherKey: (cipherId) => this.cipherKeyFor(session, cipherId, adminUserId, stationSn),
       logger: this.deps.logger ?? noopLogger
     });
     session.on("error", (e) => this.reportError(e));
@@ -20673,6 +20882,33 @@ var P2PCommandRouter = class _P2PCommandRouter {
     session.on("data", (f) => this.deps.onFrame(stationSn, f));
     return session;
   }
+  /**
+   * The ECC private key of `cipherId`, from the router's cache or one `get_ciphers` call. When the cloud
+   * answers with another cipher, that one is used and traced on `session`. Only a successful lookup is
+   * cached.
+   */
+  async cipherKeyFor(session, cipherId, userId, stationSn) {
+    if (this.cipherKeyCache.has(cipherId))
+      return this.cipherKeyCache.get(cipherId);
+    let ecc;
+    try {
+      const ciphers = await this.deps.mega.getCiphers([cipherId], userId, stationSn);
+      ecc = ciphers.find((c) => Number(c.cipher_id) === cipherId)?.ecc_private_key;
+      if (ecc === void 0 && ciphers[0]?.ecc_private_key !== void 0) {
+        ecc = ciphers[0].ecc_private_key;
+        this.traceOnStation(session, {
+          phase: "cipher-fallback",
+          cipherId,
+          answeredCipherId: Number(ciphers[0].cipher_id)
+        });
+      }
+    } catch (e) {
+      this.deps.onError(e instanceof Error ? e : new Error(String(e)));
+    }
+    if (ecc !== void 0)
+      this.cipherKeyCache.set(cipherId, ecc);
+    return ecc;
+  }
   /**
    * Open (or reuse) a station's P2P session and await its completed handshake. An optional abort only
    * stops this wait; session ownership remains with {@link SessionManager} and its normal teardown.
@@ -20800,7 +21036,9 @@ var P2PCommandRouter = class _P2PCommandRouter {
    * start has no level-1 form for.
    */
   mediaProviderFor(sn) {
+    const recordings = this.downloadsRecordings(sn) ? { downloadRecording: (opts) => this.downloadRecording(sn, opts) } : {};
     return {
+      ...recordings,
       snapshotLive: async (opts) => {
         const source = await this.sharedLiveSourceFor(sn, opts ?? {});
         return captureSnapshotFromShared(source, {
@@ -20839,6 +21077,63 @@ var P2PCommandRouter = class _P2PCommandRouter {
       }
     };
   }
+  /**
+   * Whether `sn` is a camera attached to a HomeBase 2 (T8010), the one station whose recording path layout
+   * and frame formats are confirmed.
+   */
+  downloadsRecordings(sn) {
+    const dev = this.recordFor(sn);
+    if (!dev)
+      return false;
+    const parentSn = stationOf(dev);
+    return parentSn !== sn && this.recordFor(parentSn)?.model === "T8010";
+  }
+  /**
+   * Download one recording a HomeBase 2 holds for an attached camera, then decode it
+   * ({@link decodeRecording}). Downloads queue per station: the station streams one recording at a time
+   * on the camera's channel, so a download starts only once the previous one has drained
+   * ({@link RecordingTransfer.drained}), even when that one's caller already has its answer. An abort
+   * while waiting rejects without sending anything; an abort mid-transfer rejects at once and the station's
+   * turn is held until the transfer drains.
+   */
+  async downloadRecording(sn, opts) {
+    opts.signal?.throwIfAborted();
+    const parentSn = this.stationKeyOf(sn);
+    const previous = this.recordingDownloads.get(parentSn) ?? Promise.resolve();
+    const started = this.waitTurn(previous, opts.signal).then(() => this.startRecordingDownload(sn, opts));
+    const turn = Promise.allSettled([previous, started.then((t) => t.drained)]).then(() => {
+      if (this.recordingDownloads.get(parentSn) === turn)
+        this.recordingDownloads.delete(parentSn);
+    });
+    this.recordingDownloads.set(parentSn, turn);
+    return started.then((t) => t.recording);
+  }
+  /** Resolve once `previous` settles, or reject as soon as `signal` aborts. */
+  waitTurn(previous, signal) {
+    return abortable(previous.then(() => void 0, () => void 0), signal);
+  }
+  /**
+   * Start one recording download, once the station's previous download has drained: the decoded recording,
+   * and when the station is done sending it.
+   */
+  async startRecordingDownload(sn, opts) {
+    const { session, parentSn, channel, accountId } = await this.resolveSession(sn, { signal: opts.signal });
+    const path = homeBase2RecordingPath(channel, opts.recording);
+    if (!path)
+      throw new RecordingDownloadError("invalid-recording", `no recording named ${opts.recording}`);
+    const eccKey = await this.cipherKeyFor(session, opts.cipherId, accountId, parentSn);
+    if (!eccKey) {
+      throw new RecordingDownloadError("key-unavailable", `cipher ${opts.cipherId} could not be obtained`);
+    }
+    const transfer = receiveRecording(session, {
+      path,
+      accountId,
+      channel,
+      timeoutMs: opts.timeoutMs,
+      signal: opts.signal
+    });
+    return { recording: transfer.frames.then((frames) => decodeRecording(frames, eccKey)), drained: transfer.drained };
+  }
   /**
    * Open a {@link Talkback} on a device's camera channel.
    *
@@ -28189,6 +28484,7 @@ export {
   ROOM_SUCTIONS,
   RTSP_MEMBERS,
   RawDpWriter,
+  RecordingDownloadError,
   RecordingQuality,
   RtspRecordingMode,
   SCENE_INVALID_REASONS,
@@ -28232,6 +28528,7 @@ export {
   VACUUM_DOCK_MEMBERS,
   VACUUM_SCHEDULE_ACTIONS,
   VACUUM_SCHEDULE_WEEKDAYS,
+  VIDEO_GCM_AAD,
   VacuumMapStore,
   VideoFrameDecoder,
   WORKING_MODE_MAPS,