@mega-yfue/eufy-sdk 0.5.0-beta.6 → 0.5.0-beta.61

package/dist/model/types.d.ts

@@ -39,7 +39,7 @@ export type Codec = "station" | "camera" | "sensor" | "lock" | "keypad" | "vacuu
  * it maps to a {@link CapabilityModule} that owns its property schema. Extend this union as
  * new capabilities are modelled — adding one never requires a subclass.
  */
-export type Capability = "video" | "snapshot" | "motion" | "person_detection" | "battery" | "light" | "ptz" | "doorbell" | "contact" | "leak" | "smoke" | "co" | "siren" | "lock" | "keypad" | "arming" | "storage" | "rtsp" | "camera" | "audio" | "vacuum_clean" | "vacuum_dock" | "suction" | "locate" | "smart_light" | "display" | "info";
+export type Capability = "video" | "snapshot" | "motion" | "person_detection" | "battery" | "light" | "ptz" | "doorbell" | "contact" | "leak" | "smoke" | "co" | "siren" | "lock" | "keypad" | "arming" | "storage" | "rtsp" | "camera" | "audio" | "vacuum_clean" | "vacuum_dock" | "suction" | "locate" | "mower" | "smart_light" | "display" | "info";
 /** Value type of a property. */
 export type PropertyValueType = "bool" | "number" | "string" | "enum";
 /**
@@ -52,11 +52,12 @@ export type PropertyValueType = "bool" | "number" | "string" | "enum";
  * one as the other is wrong in a way no type check catches.
  *
  *  - `boolean` — an on/off state (always paired with `type: "bool"`).
- *  - `percent` / `celsius` / `dbm` / `seconds` / `hours` / `megabytes` / `degrees` — a measured quantity
- *    in the unit the device reports it in; each pairs with the matching `unit`. Values are
- *    never converted on the way out — a converted reading is an invented one. `seconds` and `hours`
- *    are separate kinds for exactly that reason: a robot reports a run in seconds and a consumable's
- *    wear in hours, and normalising one into the other would publish a number the device never sent.
+ *  - `percent` / `celsius` / `dbm` / `seconds` / `hours` / `minutes` / `millimetres` / `megabytes` /
+ *    `degrees` — a measured quantity in the unit the device reports it in; each pairs with the
+ *    matching `unit`. Values are never converted on the way out — a converted reading is an invented
+ *    one. `seconds`, `minutes` and `hours` are separate kinds for exactly that reason: a robot reports
+ *    a run in seconds, a mower its blade wear in minutes and a vacuum's consumable wear in hours, and
+ *    normalising one into another would publish a number the device never sent.
  *  - `scalar` — a plain number in no unit at all: a step on a ladder, a mode index, a raw level, a
  *    segment count. Ordered and comparable, but its range and direction are the device's, so nothing
  *    but the device says what a given value means.
@@ -83,7 +84,7 @@ export type PropertyValueType = "bool" | "number" | "string" | "enum";
  *    decodes them and are exported beside that decoder; unlike an enum's options they are not carried
  *    here, which is a gap this vocabulary does not close on its own.
  */
-export declare const KNOWN_VALUE_KINDS: readonly ["boolean", "percent", "celsius", "dbm", "seconds", "hours", "megabytes", "degrees", "scalar", "bitfield", "enum", "identifier", "timestamp", "text"];
+export declare const KNOWN_VALUE_KINDS: readonly ["boolean", "percent", "celsius", "dbm", "seconds", "hours", "minutes", "millimetres", "megabytes", "degrees", "scalar", "bitfield", "enum", "identifier", "timestamp", "text"];
 /** One of the kinds this version models — the closed half of {@link ValueKind}. */
 export type KnownValueKind = (typeof KNOWN_VALUE_KINDS)[number];
 /**
@@ -106,7 +107,8 @@ export declare function isKnownValueKind(kind: ValueKind): kind is KnownValueKin
 /**
  * How much a param's name and meaning can be trusted, most-trusted first. This is the one definition;
  * the param dictionary and every `provenance` field use it.
- *  - `mega`     — the vendor's cloud names it: its data-point catalog (`get_product_data_point`), or a
+ *  - `mega`     — the vendor's cloud names it: its data-point catalog (`get_product_data_point`), the
+ *                 Tuya product schema of an `eufy_home_tuya` device (`thing.m.device.ref.info.list`), or a
  *                 reported value that matches what the cloud record already says (a model name or code).
  *  - `verified` — confirmed on a real device by this project: our own capture or observation, or
  *                 identified by someone who has the hardware.
@@ -140,6 +142,11 @@ export interface PropertySpec {
     kind?: ValueKind;
     /** Whether the value can be written back to the device (a setter exists). */
     writable: boolean;
+    /**
+     * Whether the device has reported this value: its own param, a read alias, or the payload it reads
+     * from. `false` means it never has. Absent when the manifest was built without the device's params.
+     */
+    reported?: boolean;
     /** Allowed values for `type: "enum"` (raw → label). */
     enumValues?: Record<number, string>;
     /**
@@ -286,6 +293,12 @@ export interface CloudRecord {
     parentSn?: string;
     /** Reported param_type → raw value. Presence of a param is a capability signal. */
     params?: Record<number, string>;
+    /**
+     * Params the device reported over its realtime channel, keyed in the device's own namespace. A line
+     * whose state exists only on that channel carries none of it in {@link params}, so this is the
+     * evidence an availability gate on such a param is decided from.
+     */
+    dpParams?: Record<number, string>;
 }
 /** The fully-resolved device shape produced by the 3-tier resolver. */
 export interface ResolvedDevice {

package/dist/transport/abortable.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Settle `work` as it settles, or reject the moment `signal` aborts, whichever comes first.
+ *
+ * The underlying wait is left to finish on its own: it may be shared work other callers are waiting on, so a
+ * caller abandoning its own call does not cancel the work itself. This abandons WAITING, which is the only
+ * part that belonged to the caller.
+ */
+export declare function abortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T>;

package/dist/transport/http/mega-client.d.ts

@@ -209,6 +209,8 @@ export interface SignedRetry {
 export declare class MegaHttpClient {
     private readonly cfg;
     private region;
+    /** The host `estimate_domain` answered, persisted with the session. */
+    private estimatedDomain;
     private bootstrapDomain?;
     private sessionKey?;
     /** Per-host ECDH session keys for non-mega gateways (e.g. eufylife) keyed by host. */
@@ -228,6 +230,8 @@ export declare class MegaHttpClient {
     /** True while a 2FA code is outstanding: `auth_` holds only the limited pre-verify token, so the
      *  restored-session short-circuit must NOT treat it as a usable session. Cleared on Ok/reset. */
     private pending2fa;
+    /** An autonomous re-login answered captcha/2FA; see {@link canReauthenticate}. */
+    private reloginChallenged;
     private tokenExpiresAt;
     /**
      * Stable per-install device id: `openudid` as configured, as restored from the session store, or as
@@ -259,10 +263,12 @@ export declare class MegaHttpClient {
     constructor(cfg: MegaClientConfig);
     /**
      * Install the session the store holds, if it holds a usable one: the token + its bound ECDH key, skipping
-     * estimate/key-exchange/login/2FA entirely. Answers the token adopted, or `undefined`.
+     * estimate/key-exchange/login/2FA entirely. Answers the token adopted, or `undefined`. A session logged in
+     * with a country other than the configured one is not usable: its shard is the other country's.
      *
      * Read at construction, and again when a rejection is being recovered from — a store SHARED with another
      * client may already hold the session that client obtained, which is cheaper to adopt than to compete with.
+     * An adopted session is a complete one, so it ends any 2FA or challenged re-login this client was left with.
      *
      * Note: the device identity (openudid + phone model + media UA) is NOT restored here — it is resolved once
      * in the constructor, where an explicit config wins over the stored value, and must not be re-derived from a
@@ -275,6 +281,21 @@ export declare class MegaHttpClient {
     } | undefined;
     /** The active region shard (e.g. `"eu-pr"`, `"us-pr"`), set after {@link login} or a region override. */
     get regionShard(): RegionShard;
+    /**
+     * The shard the RTC signalling signs on: the regional prefix of the estimated domain
+     * (`…-ie-…`/`…-ie.` → `ie-pr`), else {@link regionShard}. The eu/us classification cannot name shards
+     * like `ie-pr`, whose accounts need the IE sign host and cluster.
+     */
+    get rtcShard(): string;
+    /**
+     * The credentials the RTC signalling needs; `undefined` while logged out. The sign is refused
+     * ("gtoken not equal userid") unless its gtoken is the one every authed HTTP call carries.
+     */
+    rtcIdentity(): {
+        authToken: string;
+        userId: string;
+        gtoken: string;
+    } | undefined;
     /**
      * The name commands attribute themselves to — {@link MegaClientConfig.accountName} when the config
      * pins one (trimmed; blank counts as unset), otherwise the logged-in account's display name, which
@@ -367,6 +388,15 @@ export declare class MegaHttpClient {
      * params instead, which also carry `{param_type, param_value, update_time}` and are not owner-gated.
      */
     getDeviceParamList<T = unknown>(deviceSn: string): Promise<T>;
+    /**
+     * Fetch the account's devices as the `devicerelation` service lists them, `{attribute: 7, house_id: ""}`.
+     *
+     * Each entry is `{device: {device_sn, dps, …}}`, and `dps` is the cloud's last-known value of every
+     * data point that device has reported, keyed by DP number. Answered for an account a device is shared
+     * with as well as for its owner. Sent with `category: eufy_home`, without which the service answers
+     * `10000`.
+     */
+    getDeviceRelationList<T = unknown>(): Promise<T>;
     /**
      * Fetch one page of a device's **cleaning history** from the mega `clean` service.
      *
@@ -563,7 +593,9 @@ export declare class MegaHttpClient {
      * Structural rather than a list of paths: a login round trip is itself an authenticated call while a limited
      * token is held, so re-logging in from inside one would recurse — and a path list would have to be
      * maintained alongside every request the login flow makes. A 2FA code already outstanding is a login a human
-     * is part-way through, and restarting it silently would discard it. No credentials means nothing to try,
+     * is part-way through, and restarting it silently would discard it. A re-login that already came back needing
+     * a captcha or a 2FA code would need the same again, and each attempt sends the account another code, so
+     * none is tried until a login completes or a stored session is adopted. No credentials means nothing to try,
      * so the rejection surfaces instead.
      */
     private canReauthenticate;

package/dist/transport/mqtt/broker-discovery.d.ts

@@ -8,8 +8,9 @@ export interface BrokerCredentials {
 }
 export interface ProbeResult {
     ip: string;
-    /** True iff SUBSCRIBE to the target topic was granted (qos 0/1/2, not the 0x80 deny code). */
+    /** True iff SUBSCRIBE to the target topic was granted (qos 0/1/2). */
     granted: boolean;
+    /** The SUBACK return code for the topic, the 0x80 deny code included. */
     grantedQos?: number;
     error?: string;
     ms: number;

package/dist/transport/mqtt/command-router.d.ts

@@ -136,8 +136,9 @@ export declare class MqttCommandRouter {
      * One exception is known: a single garage unit whose own-cert SUBSCRIBE was denied on every candidate
      * while a phone-extracted cert granted on the same one, with a sibling of the same model on the same
      * account granting fine. That is a per-device authorization gap on the vendor's backend, not a
-     * broker-instance problem and not something this SDK works around — such a device reports as offline
-     * (the throw below) until the backend grants the account's own credentials.
+     * broker-instance problem and not something this SDK works around — the throw below names each
+     * candidate's outcome (its SUBACK deny code, a timeout or a connection error) until the backend grants
+     * the account's own credentials.
      *
      * One fresh, explicitly non-reconnecting (`reconnectPeriod: 0`) connection per call — it repays the
      * full mTLS handshake every command and tears the socket down right after (see

package/dist/transport/p2p/command-router.d.ts

@@ -1,14 +1,3 @@
-/**
- * P2P command router — the transport-side owner of the ThroughTek PPCS sessions and every wire
- * operation over them: opening sessions, resolving a serial to its session + routing params,
- * mapping a transport-neutral {@link Command} to a concrete frame (encryption level, wire shape),
- * the fire-and-forget control senders, request/reply queries, and the media provider.
- *
- * Layering: this module knows P2P bytes; it does NOT know capabilities. Frame → semantic-event
- * decoding is a model concern, so raw frames are handed back to the client via {@link P2PRouterDeps.onFrame}
- * (the client gates them on device capabilities and emits typed events). This keeps transport free of
- * any `model/` import — the capability↔transport decorrelation invariant.
- */
 import type { MegaHttpClient } from "../http/mega-client.js";
 import type { EufyDevice } from "../../core/types.js";
 import type { Command, AutoLockSnapshot, MediaProvider, SharedSourceHints, AbortableCall } from "../../core/contracts.js";
@@ -258,11 +247,14 @@ export declare class P2PCommandRouter {
      */
     dispatchCommand(sn: string, cmd: Command): Promise<void>;
     /**
-     * Restart a HomeBase. `RESTART_HUB` (1034) is a station-scalar on the broadcast channel 255: a
-     * level-2 frame whose body is `[u32 value][account_id padded]` — the same shape as the hub
-     * alarm-volume control. ✅ Wire-confirmed byte-exact from a capture of the app's own Restart
-     * (2026-08-03) and HW-tested: the captured frame carried value `0` and rebooted the hub. Replays
-     * like every other level-2 control, so a single dropped datagram doesn't lose it.
+     * Restart the station that owns `sn`'s P2P session. `RESTART_HUB` (1034) is a station-scalar on the
+     * broadcast channel 255 whose body is `[u32 value][account_id padded]`, value `0`. ✅ Wire-confirmed
+     * byte-exact as a level-2 frame from a capture of the app's own HomeBase Restart (2026-08-03).
+     *
+     * The seal follows the session, as {@link sendBySessionLevel} defines it: a keyed session takes the
+     * level-2 frame, a keyless one — a standalone camera, which never negotiates a key — the same body
+     * sealed level-1. Both are replayed {@link DIRECT_CMD_SENDS}× at 200ms, as every other unacknowledged
+     * control here is.
      */
     rebootStation(sn: string): Promise<void>;
     /**
@@ -308,6 +300,11 @@ export declare 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.
@@ -453,15 +450,6 @@ export declare class P2PCommandRouter {
      * A still with no live sibling re-asserts, so a tile refreshing on a quiet station is
      * unaffected.
      */
-    /**
-     * Attach a consumer, unless the caller has already abandoned the call.
-     *
-     * The acquisition it just waited through can outlast the caller's interest, and a consumer attached for
-     * somebody who has gone keeps the pull warm for nobody. Detaching immediately gives the pull back, which
-     * lets it linger and fall away if this was the only thing holding it, and leaves it untouched if it was
-     * not.
-     */
-    private attachUnlessAborted;
     /**
      * Dispose one cached live source and forget it, so the next acquisition builds a fresh one. Its claim
      * on a session goes with it, and a media session opened for this source alone is closed: nothing else
@@ -521,11 +509,11 @@ export declare class P2PCommandRouter {
      */
     private onLiveStartFailed;
     /**
-     * Replace the session under a warming source whose media start nothing acknowledged, and warm again on it.
+     * Replace the session under a warming source it is not serving, and warm again on it.
      *
      * Only a STANDALONE device's session is replaced, for the reason {@link onLiveStartFailed} gives: an attached
      * camera shares its HomeBase session with every other camera on it, and closing that to recover one would
-     * drop the rest. Such a source keeps the re-issue it always had.
+     * drop the rest. Such a source keeps the re-issue it always had, which the answer (false) tells it.
      *
      * The source is left warming throughout, holding the deadline it started, so this either produces a stream
      * within that window or fails exactly as it would have. A replacement that cannot be opened leaves the
@@ -687,7 +675,7 @@ export declare class P2PCommandRouter {
      * **`set-json-raw` intent** — bare JSON, no envelope: outer P2P cmd = `outerCmd` itself, plaintext
      * exactly `{account_id,...data}` (`session.sendRawLevel2` with no wrapper). Reversed from a live
      * capture of the app's own SET_SNOOZE_TIME (1271) frame — see `param-dictionary.ts`'s `1271` entry
-     * (`snoozeTime`); the alarm-delay config (1255, `arming.ts`'s `ARMING_CMD.ALARM_DELAY_CONFIG`) reuses
+     * (`snoozeTime`); the alarm-delay config (1255, `arming.ts`'s `ARMING_CMD.SET_ALL_ACTION`) reuses
      * the same bare-JSON shape.
      */
     private sendJsonRaw;

package/dist/transport/p2p/fmp4.d.ts

@@ -17,9 +17,12 @@ export declare class Fmp4Muxer {
     private baseDecodeTime;
     private fragTicks;
     private samples;
-    private lastVideoTimestampMs?;
+    /** Ticks from the first video sample's start to the newest sample's end, at its provisional duration. */
+    private videoTicks;
     private readonly audioRequested;
     private audioCodec?;
+    /** Decoder config of an AAC-ELD track, taken from its frames; absent for AAC-LC, whose `esds` config is fixed. */
+    private audioConfig?;
     private audioDisabled;
     private audioSamples;
     private audioBaseDecodeTime;
@@ -35,9 +38,16 @@ export declare class Fmp4Muxer {
      * Push one access unit. Returns any completed segments: the `init` on the first keyframe, and/or a
      * media fragment when this frame closed the open one. Returns `undefined` if nothing is emitted yet
      * (e.g. delta frames before the first keyframe).
+     *
+     * A sample lasts until the next frame's `timestampMs`, measured from the first keyframe's, so the video
+     * timeline follows the arrival clock; a frame that shares the previous one's timestamp leaves that
+     * sample one tick long, and the next frame's duration absorbs the difference.
      */
     push(frame: LiveVideoFrame, timestampMs?: number): MediaFragment | undefined;
-    /** Add one station-declared AAC access unit to the audio track. G.711 remains available via `live()`. */
+    /**
+     * Add one station-declared AAC access unit to the audio track: an ADTS frame for AAC-LC, a raw access unit
+     * described by its frame's config for AAC-ELD. G.711 remains available via `live()`.
+     */
     pushAudio(frame: LiveAudioFrame, timestampMs?: number): MediaFragment | undefined;
     /** Permanently omit incompatible audio while allowing the video recording to continue. */
     private disableAudio;

package/dist/transport/p2p/live-stream.d.ts

@@ -103,6 +103,9 @@ export declare class LiveStream extends EventEmitter {
     private lastCodec;
     /** Rebuilds an access unit the station split across several frames — see {@link AccessUnitAssembler}. */
     private readonly units;
+    /** Whether a missing video datagram or incomplete unit invalidated the current reference chain. */
+    private awaitingKeyframeAfterGap;
+    private readonly videoGapHandler;
     /** The channel inbound media must be tagged with, once {@link acceptsMedia} trusts the station's tag. */
     private mediaChannel?;
     private tracedFirstVideoCommand;

package/dist/transport/p2p/p2p-session.d.ts

@@ -435,6 +435,11 @@ export declare class P2PSession extends EventEmitter {
      * "direct" commands (e.g. CAMERA_SWITCH 1035) carry a binary struct, not JSON.
      */
     sendRawLevel2Bytes(payload: Buffer, channel: number, outerCmd?: number, signCode?: number): boolean;
+    /**
+     * The level-1 twin of {@link sendRawLevel2Bytes}: the plaintext `payload` sealed AES-128-ECB under the
+     * level-1 key, signCode 1 — the seal of the level-1 media start. Returns `false` when not connected.
+     */
+    sendRawLevel1Bytes(payload: Buffer, channel: number, outerCmd: number): boolean;
     /**
      * Stop the realtime media stream (`CMD_STOP_REALTIME_MEDIA`, 1004) on a camera `channel`, in the shape
      * its runtime topology takes, as {@link startLiveMedia} selects its start:
@@ -606,6 +611,18 @@ export declare class P2PSession extends EventEmitter {
         accountId?: string;
         channel?: number;
     }): void;
+    /**
+     * Read a date-ranged page of `history_record_info` from the station. The reply's `data` array groups
+     * recording rows with companion tables; each group retains its `table_name` and `payload`.
+     * `startTime` is `"0"` for the newest page or the oldest row's `yyyyMMddHHmmss` cursor for older rows.
+     */
+    queryRecordPage(opts: {
+        accountId?: string;
+        startDate: string;
+        endDate: string;
+        startTime?: string;
+        count?: number;
+    }): Promise<unknown[]>;
     /**
      * Query one on-station table and answer its rows, once the reply is whole.
      *
@@ -613,13 +630,15 @@ export declare class P2PSession extends EventEmitter {
      * several frames whose decrypted text is a fragment of one document, so the fragments are
      * accumulated here and scanned after each one. Answers that document's `data` rows. Rejects when
      * `signal` aborts, and when `timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}) elapses with no
-     * complete reply.
+     * complete reply, and when the station answers a non-zero `mIntRet`.
      *
      * One read at a time per session: while one is accumulating, every {@link queryDatabase} on the
      * session throws, so a second reply cannot land in this buffer.
      */
     readDatabase(table: string, opts?: {
         accountId?: string;
+        innerCmd?: number;
+        query?: Record<string, unknown>;
         timeoutMs?: number;
         signal?: AbortSignal;
     }): Promise<unknown[]>;
@@ -699,6 +718,7 @@ export declare class P2PSession extends EventEmitter {
      * Frames are packed back to back, so a frame header can itself be cut by a datagram boundary. The start
      * of a header left at the end of a datagram is carried into the next one rather than discarded; dropping
      * it would lose that frame and every frame after it until a datagram happened to begin on a header.
+     * Payload fragments retain their original slices and are copied once, when the complete frame is delivered.
      */
     private reassemble;
     /**

package/dist/transport/p2p/readable-egress.d.ts

@@ -17,11 +17,15 @@ import type { Consumer } from "./shared-live-source.js";
 export interface ReadableEgressOptions {
     /** Emit {@link LiveVideoFrame} objects instead of raw Annex-B bytes (default false = bytes). */
     objectMode?: boolean;
+    /** Yield ReceivedVideoFrame envelopes with original source-arrival times; ignored in raw mode. */
+    arrivalTime?: boolean;
     /** Readable highWaterMark (bytes, or object count in objectMode). */
     highWaterMark?: number;
 }
 /**
  * Wrap a shared-source {@link Consumer} in a fresh Readable. The consumer is detached when the
  * Readable is destroyed/ended, so callers own the lifetime by owning the stream.
+ * Frames arrive through onMedia; an empty video listener releases the keyframe-prime
+ * because ConsumerImpl replays it when the first video listener is added.
  */
 export declare function openReadableFromConsumer(consumer: Consumer, opts?: ReadableEgressOptions): Readable;

package/dist/transport/p2p/recording-download.d.ts

@@ -46,9 +46,10 @@ export declare function receiveRecording(session: P2PSession, request: {
     signal?: AbortSignal;
 }): RecordingTransfer;
 /**
- * Decode a recording's frames, in arrival order, into elementary streams. Keyframes go through one
- * {@link VideoFrameDecoder}, whose media key then opens the audio; a keyframe that does not open under
- * `eccPrivateKeyHex`, and every audio frame before the first media key, are dropped. Rejects with
+ * Decode a recording's frames, in arrival order, into elementary streams. Split pictures are assembled
+ * before they enter the output; an orphan continuation cannot become its own picture. Keyframes go
+ * through one {@link VideoFrameDecoder}, whose media key then opens the audio; a keyframe that does not
+ * open under `eccPrivateKeyHex`, and every audio frame before the first media key, are dropped. Rejects with
  * {@link RecordingDownloadError} `undecodable` when no video frame decodes.
  */
 export declare function decodeRecording(frames: readonly RecordingFrame[], eccPrivateKeyHex: string): RecordingDownload;

package/dist/transport/p2p/shared-live-source.d.ts

@@ -83,12 +83,13 @@ export interface SharedLiveSourceOptions {
      */
     onStopped?: () => void;
     /**
-     * A media start was abandoned unacknowledged before anything was delivered, so this session is not being
-     * heard. The owner is asked for a replacement and calls {@link SharedLiveSource.rewarm} once it has one.
+     * This session is not serving the warm-up: a media start was abandoned unacknowledged, or forced starts went
+     * unanswered by any media, before anything was delivered. The owner answers whether it is replacing the
+     * session, and calls {@link SharedLiveSource.rewarm} once it has the replacement.
      *
-     * Asked at most once per warm-up: further abandonments are the same session saying the same thing.
+     * Asked at most once per warm-up: further evidence is the same session saying the same thing.
      */
-    onSessionUnreachable?: () => void;
+    onSessionUnreachable?: () => boolean;
 }
 /**
  * A single consumer of a {@link SharedLiveSource}. A {@link LiveStreamConsumer} (so `live()` can hand it
@@ -251,18 +252,17 @@ export declare class SharedLiveSource {
      */
     private warm;
     /**
-     * A start was abandoned unacknowledged. Ask for a replacement session where nothing has been delivered yet.
+     * Ask the owner for a replacement session where nothing has been delivered yet, answering whether one is coming.
      *
-     * The abandonment is roughly twenty byte-identical sends with no reply, against acknowledgement latencies of
-     * 4–37 ms awake and 238 ms waking, so it is the session that is not being heard rather than a slow device —
-     * `P2PSession` says as much: the camera was never told to stream, so this warm-up can only time out. Where
-     * media has already flowed the abandonment means something else and this does nothing.
+     * An unacknowledged start is roughly twenty byte-identical sends with no reply, against acknowledgement latencies
+     * of 4–37 ms awake and 238 ms waking, so it is the session that is not being heard rather than a slow device: the
+     * camera was never told to stream. Where media has already flowed the abandonment means something else and this
+     * does nothing. The DEADLINE is left running: the window belongs to the attempt, not to the session it started on.
      *
-     * The retry ticker is stopped while a replacement is awaited, because every tick it issues goes to the same
-     * unheard session. The DEADLINE is left running: the window belongs to the attempt, not to the session it
-     * started on.
+     * The retry ticker is stopped only once the owner has said it is replacing the session: an owner that cannot
+     * (an attached camera shares its HomeBase session) leaves the source re-issuing as it always did.
      */
-    private onStartUnacknowledged;
+    private askForFreshSession;
     /**
      * Warm again on a session the owner has replaced, inside the deadline the first attempt started.
      *
@@ -290,6 +290,11 @@ export declare class SharedLiveSource {
      * {@link fruitlessReissues} for why one is not enough and why what the stream delivered earlier is not
      * evidence. Once media arrives the keepalive is what is wanted, and an attached camera re-sends a full start
      * either way.
+     *
+     * A forced start that a whole interval later has still produced nothing is a session that acknowledges and
+     * does not serve: a fresh session on the same camera delivers a keyframe within a second, so a warm-up asks
+     * for one rather than forcing starts onto this one until its deadline. Wired only: a cold battery camera is
+     * slow rather than deaf, measured at about 8 s to first media, and replacing its session would cost a wake.
      */
     private reissueStart;
     /**
@@ -438,3 +443,12 @@ export declare class SharedLiveSource {
      */
     dispose(): void;
 }
+/**
+ * Attach a consumer, unless the caller has already abandoned the call.
+ *
+ * The acquisition it just waited through can outlast the caller's interest, and a consumer attached for
+ * somebody who has gone keeps the pull warm for nobody. Detaching immediately gives the pull back, which
+ * lets it linger and fall away if this was the only thing holding it, and leaves it untouched if it was
+ * not.
+ */
+export declare function attachUnlessAborted(source: SharedLiveSource, signal?: AbortSignal): Consumer;

package/dist/transport/p2p/talkback.d.ts

@@ -1,10 +1,12 @@
 /**
- * Managed talkback session over P2P — the send-side twin of `live-stream.ts`. Takes AAC-LC audio from
- * a host, recovers frame boundaries, and paces the frames onto the wire at their own playback rate,
- * bracketed by the device's start/stop control frames.
+ * Managed talkback session over P2P — the send-side twin of `live-stream.ts`. Takes audio from a host in
+ * the codec the camera's speaker plays (AAC-LC ADTS, or raw AAC-ELD access units), recovers frame
+ * boundaries, and paces the frames onto the wire at their own playback rate, bracketed by the device's
+ * start/stop control frames.
  *
  * Pacing is the reason this exists rather than a bare `sendAudioFrame` loop. Each AAC-LC frame at
- * 16 kHz is 1024 samples — exactly 64 ms of audio — and the device plays what arrives when it arrives.
+ * 16 kHz is 1024 samples — exactly 64 ms of audio — and each AAC-ELD access unit is 512 samples, 32 ms.
+ * The device plays what arrives when it arrives.
  * A host piping a file would otherwise deliver a minute of audio in a few hundred milliseconds and
  * lose all but the tail. A live source paces itself and simply keeps the queue near-empty.
  *
@@ -17,7 +19,7 @@
  */
 import { EventEmitter } from "node:events";
 import { Writable } from "node:stream";
-import type { AacEncoder, StreamBudgetNotice, TalkbackHandle } from "../../core/contracts.js";
+import type { AacEncoder, StreamBudgetNotice, TalkbackCodec, TalkbackHandle } from "../../core/contracts.js";
 import { type Logger } from "../../core/logger.js";
 /**
  * The subset of the session this needs — start/stop the path, push one frame, and report a frame the
@@ -66,7 +68,7 @@ export interface TalkbackOptions {
 export declare const DEFAULT_IDLE_TIMEOUT_MS = 30000;
 /**
  * A talkback session bound to one camera channel. Opens the device's path on construction via
- * {@link start}, then drains queued frames on a fixed 64 ms tick until {@link stop}.
+ * {@link start}, then drains queued frames on a tick of one frame's duration until {@link stop}.
  */
 export declare class Talkback extends EventEmitter implements TalkbackHandle {
     private readonly sink;
@@ -74,7 +76,8 @@ export declare class Talkback extends EventEmitter implements TalkbackHandle {
     private readonly reader;
     private readonly queue;
     private readonly logger;
-    private readonly highWater;
+    /** Playback duration of one queued frame, the pacer's step: 64 ms for `aac-lc`, 32 ms for `aac-eld`. */
+    private frameMs;
     private readonly idleTimeoutMs;
     private timer?;
     private started;
@@ -94,17 +97,24 @@ export declare class Talkback extends EventEmitter implements TalkbackHandle {
     private chain;
     private readonly onAudioGap;
     constructor(sink: TalkbackSink, opts: TalkbackOptions);
+    /** Frames the pacing queue holds before a writable applies backpressure: {@link HIGH_WATER_MS} of this codec. */
+    private get highWater();
+    /** The codec this talkback sends, set by {@link start}. */
+    codec: TalkbackCodec;
     /** Frames still queued for the wire. */
     get pending(): number;
     /**
      * 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(): this;
+    start(codec: TalkbackCodec): 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
@@ -160,6 +170,7 @@ export declare class Talkback extends EventEmitter implements TalkbackHandle {
     /**
      * 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(): Writable;
     /** Drain an encoder's partial trailing block, so the last syllable is not lost. */

package/dist/transport/p2p/video.d.ts

@@ -71,6 +71,8 @@ export declare class VideoFrameDecoder {
 }
 /** One whole access unit recovered from the frame (or frames) the station sent it in. */
 export interface AssembledAccessUnit {
+    /** Unsigned 32-bit header timestamp from the first frame of this access unit. */
+    sourceTimestamp: number;
     /** True when the unit's own header flagged it a keyframe — a point a consumer may begin decoding at. */
     keyframe: boolean;
     /** Frame width the unit's header declared. */
@@ -144,9 +146,10 @@ export declare class AccessUnitAssembler {
      * `decode` extracts the payload of a frame, whatever the stream's encryption: it is called for EVERY
      * frame, including a continuation, because a continuation carries its own wrapped key ahead of its share
      * of the payload (measured: 129 bytes beyond what its header declares, exactly as a unit's first frame
-     * carries).
+     * carries). A continuation without its matching open unit has no Annex-B start code and cannot be emitted
+     * as a complete unit, even if its repeated header says keyframe.
      */
     push(payload: Buffer, decode: (payload: Buffer) => Buffer | undefined): AssembledAccessUnit[];
     /** Forget an incomplete unit, counting and reporting it. */
-    private discard;
+    discard(): void;
 }