@mega-yfue/eufy-sdk 0.0.4 → 0.1.0-beta.0

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

@@ -0,0 +1,33 @@
+import { EventEmitter } from "node:events";
+import type { FragmentRecordingHandle, MediaFragment, StreamBudgetNotice } from "../../core/contracts.js";
+import type { SharedLiveSource } from "./shared-live-source.js";
+export interface FragmentRecordingOptions {
+    fragmentSeconds?: number;
+    preBufferSeconds?: number;
+}
+/**
+ * One caller-owned fragmented recording over a shared live source. Buffered and live frames pass
+ * through the same timestamp-aware muxer, while budget notices retain the source's `extend()` handle.
+ */
+export declare class FragmentRecording extends EventEmitter implements FragmentRecordingHandle {
+    private readonly opts;
+    private readonly mux;
+    private readonly queue;
+    private consumer?;
+    private wake?;
+    private failure?;
+    private ended;
+    private iterated;
+    private held;
+    private readonly ready;
+    constructor(source: Promise<SharedLiveSource>, opts?: FragmentRecordingOptions);
+    on(event: "budget", listener: (notice: StreamBudgetNotice) => void): this;
+    stop(): void;
+    [Symbol.asyncIterator](): AsyncIterator<MediaFragment>;
+    private attach;
+    private ingest;
+    /** Hand over the next fragment, releasing the consumer once the owner is back inside the bound. */
+    private take;
+    private fail;
+    private nudge;
+}

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

@@ -0,0 +1,13 @@
+export * from "./p2p-session.js";
+export * from "./live-stream.js";
+export * from "./video.js";
+export * from "./media.js";
+export { SharedLiveSource, type SharedLiveState, type SharedLiveSourceOptions, type TimedMediaFrame, type Consumer as LiveConsumer, } from "./shared-live-source.js";
+export { extractParamSets, codedGeometry, type ParamSets, type CodedGeometry, type Size } from "./annexb.js";
+export { type PowerTier } from "./session-manager.js";
+export * from "./commands.js";
+export * from "./envelope.js";
+export * from "./write-commands.js";
+export * from "./lan-ip.js";
+export { LIVE_TRACE_MESSAGE, type LiveTrace } from "./live-trace.js";
+export * as p2pCodec from "./codec.js";

package/dist/transport/p2p/lan-ip.d.ts

@@ -0,0 +1,25 @@
+/**
+ * LAN-address resolution for a P2P station from its cloud device record.
+ *
+ * Pure helpers (no session state) — used when opening a P2P session to prefer a direct on-LAN
+ * lookup over the cloud relay (works when broadcast is blocked by AP isolation / macOS, even if
+ * the record's pairing `ip_addr` went stale).
+ */
+/** True for an RFC-1918 private IPv4 (a routable LAN address, not a WAN/public one). */
+export declare function isPrivateIpv4(s: string): boolean;
+/**
+ * Resolve the freshest LAN IP for a station from its cloud record.
+ *
+ * The record carries the device IP in several places of differing trust:
+ *  - **params** (`{param_type, param_value, update_time}`) — self-reported by the device on each
+ *    heartbeat, so a private-IP param value is timestamped and updates when the device roams.
+ *  - **`ip_addr`** (top-level) — frozen at pairing, no timestamp; goes stale if the device moved
+ *    to another subnet since (observed live: a SoloCam still advertising a 192.168.86.x pairing
+ *    address while actually on 192.168.1.x).
+ *  - **`local_ip`** — often empty, or the public WAN address.
+ *
+ * Strategy: collect every param whose value is a private IPv4, take the one with the newest
+ * `update_time`, and only fall back to `ip_addr` / `local_ip` when no param IP exists. This
+ * prefers the most recent evidence over a fixed field-priority order.
+ */
+export declare function freshestLanIp(raw: unknown): string | undefined;

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

@@ -0,0 +1,223 @@
+/**
+ * Managed realtime live stream over P2P — turns a station's `CMD_VIDEO_FRAME` (1300) /
+ * `CMD_AUDIO_FRAME` (1301) frames into a clean, continuous **Annex-B H.264** (+ audio) elementary
+ * feed a muxer can ingest.
+ *
+ * Two video frame variants are handled:
+ *  - **Plaintext** (`signCode 0`, e.g. HomeBase-attached cameras): a fixed 22-byte frame header
+ *    (`parseVideoFrameHeader`) followed directly by Annex-B NAL units — verified live (960×540,
+ *    keyframe = header flag bit0). We strip the 22-byte header.
+ *  - **Encrypted** (E2E cameras): the body is AES-256-GCM under a per-stream media key wrapped in a
+ *    keyframe ECIES envelope. If an `eccPrivateKey` is supplied we run `VideoFrameDecoder`; otherwise
+ *    those frames are skipped (no key → no video).
+ *
+ * Emits: `video` ({@link LiveVideoFrame} — Annex-B), `audio` ({@link LiveAudioFrame}), `start`, `stop`,
+ * `error`.
+ */
+import { EventEmitter } from "node:events";
+import { type P2PSession } from "./p2p-session.js";
+import { type Logger } from "../../core/logger.js";
+import type { LiveAudioFrame, LiveVideoFrame } from "../../core/contracts.js";
+/**
+ * How often the media start is re-issued to hold a stream open, when a caller expresses no preference.
+ *
+ * This is **on by default** because some cameras stop sending without it. With the nudge disabled, a
+ * T8170 went quiet 13.6 s into a plain `live()` — no `stop`, no `error`, the feed simply stopped — and
+ * ran the full window with it on (185 frames vs 704 over 40 s).
+ *
+ * Which cameras need it does **not** follow topology or power source, so there is no predicate to gate
+ * it on: measured across four cameras, an own-session T8410 and both HomeBase-attached cameras (T8210,
+ * T8114) held a 40 s stream up with the nudge disabled, while the own-session T8170 did not. All four
+ * are battery. Since a camera that needs it goes silent rather than reporting anything, the default
+ * covers the one that fails.
+ *
+ * What the nudge costs differs by topology, and only one branch is a true keepalive: an own-session
+ * camera's `startLiveMedia` tracks that the stream is already started and sends the small ping, while a
+ * HomeBase-attached camera has no such state and re-sends the full media start — a genuine restart on
+ * that path.
+ *
+ * That restart is harmless on a station serving ONE camera and harmful on a station serving several: it
+ * re-asserts this camera's channel every interval, so two attached streams contend continuously. Measured on
+ * a real base as a full start every 3 s from each. So an attached stream stops nudging as soon as the station
+ * delivers a frame of its own channel — see the private `settleKeepalive`. The measurement that justifies it
+ * is the one above: the attached cameras held their window with the nudge disabled outright.
+ */
+export declare const DEFAULT_KEEPALIVE_MS = 3000;
+export interface LiveStreamOptions {
+    /**
+     * Camera channel to START (the device's `device_channel`) — sent in CMD_START_REALTIME_MEDIA to
+     * select which camera on a multi-camera HomeBase streams. Defaults to the station channel.
+     *
+     * On a HomeBase-attached camera it is ALSO what inbound media is matched against, so one camera's stream
+     * never carries another camera's frames: a station fanning several cameras out over one session tags every
+     * media frame with the camera it belongs to. A frame tagged for a channel a sibling started is never taken,
+     * however long the station keeps serving that sibling instead of this one.
+     */
+    channel?: number;
+    /** Camera ECC private key (32B) for E2E/encrypted cameras; omit for plaintext cameras. */
+    eccPrivateKey?: Buffer;
+    /** Admin account id — required for the level-2 (`signCode 8`) media-start payload selecting a camera. */
+    accountId?: string;
+    /**
+     * Re-send the media start every N ms to hold the stream open. Defaults to
+     * {@link DEFAULT_KEEPALIVE_MS}; pass `0` to disable.
+     */
+    keepAliveMs?: number;
+    /**
+     * How long an attached stream tolerates silence on its own channel before re-asserting again, in ms.
+     *
+     * The re-assert is settled by the first own-channel frame, because settling it is what stops two attached
+     * streams contending on a station that serves one camera at a time. Silence for this long says the station
+     * is no longer serving this camera, which is the only condition the re-assert was for. Defaults to twice
+     * the keepalive interval, so a stream whose media flows never reaches it.
+     */
+    stallMs?: number;
+    /**
+     * Whether re-asserting this camera's channel is still wanted, consulted each time the stall window
+     * elapses. Absent means always wanted.
+     *
+     * A re-assert on an attached camera is a full media start, so it takes the station from whichever camera
+     * it was serving. Whether that is wanted depends on who is attached to this pull and to its siblings,
+     * which this stream cannot see. Its owner can, so it asks rather than assuming.
+     *
+     * The watch keeps re-arming while this answers false, so a pull that gains a consumer re-asserts at the
+     * next window rather than staying silent for the rest of its life.
+     */
+    reassertWanted?: () => boolean;
+    /**
+     * Runtime topology fact (from the device record: `parent_sn && parent_sn !== sn`): true = the camera
+     * rides a HomeBase's session (start via the level-2 `1003` payload), false = own-session camera
+     * (start via the `1700`/`cmd 1000` path, level-2 or level-1 per the session key). NOT a family trait.
+     */
+    homeBaseAttached?: boolean;
+    /** Diagnostics sink. Omit for silence. */
+    logger?: Logger;
+}
+export declare class LiveStream extends EventEmitter {
+    private readonly session;
+    private readonly opts;
+    private listening;
+    private decoder?;
+    private kaTimer?;
+    /** Last codec sniffed off a keyframe; delta frames (no config NAL) inherit it. Default h264. */
+    private lastCodec;
+    /** Rebuilds an access unit the station split across several frames — see {@link AccessUnitAssembler}. */
+    private readonly units;
+    /** The channel inbound media must be tagged with, once {@link acceptsMedia} trusts the station's tag. */
+    private mediaChannel?;
+    private tracedFirstVideoCommand;
+    private tracedFirstVideoUnit;
+    private tracedFirstKeyframe;
+    private tracedDecodeFailures;
+    private tracedFirstForeignFrame;
+    private stallTimer?;
+    /**
+     * The channel this stream starts, stops, traces under and matches its own abandonment on. An omitted
+     * channel resolves to {@link STATION_CHANNEL} — the value the session resolves it to.
+     */
+    private readonly channel;
+    private readonly handler;
+    /** Forwards `liveStartUnacknowledged` only where it carries this stream's own channel. */
+    private readonly unackedHandler;
+    private readonly logger;
+    constructor(session: P2PSession, opts?: LiveStreamOptions);
+    /** Emit a live trace under its session's handle and the channel this stream pulls. */
+    private trace;
+    /** Begin streaming: attach the frame listener and tell the station to start realtime media. */
+    start(): this;
+    /**
+     * Stop re-issuing the media start once this camera's own media has arrived, on an attached camera.
+     *
+     * The nudge differs by topology and only one branch is a ping: an own-session camera sends a small
+     * keepalive, while an attached camera has no such state and re-sends the FULL media start. On a station that
+     * serves one camera at a time that restart re-asserts this channel against whatever else is warm, so two
+     * attached streams restart every interval and contend for the station continuously — measured on a real base
+     * as a full start every 3 s from each.
+     *
+     * A frame of this camera's own channel is the station stating it is serving THIS camera, which is the only
+     * thing the restart was trying to bring about. The SDK's own measurement agrees it is then unnecessary: both
+     * attached cameras held a 40 s stream with the nudge disabled, while the own-session camera that needs it
+     * went quiet at 13.6 s without it — so an own-session stream keeps its ping.
+     *
+     * The warm-up retry a shared source runs is untouched: it recovers a start that raced the level-2 key, and
+     * it stops at the first keyframe by its own rule.
+     */
+    private settleKeepalive;
+    /**
+     * Re-arm the attached re-assert if this camera's own media goes silent.
+     *
+     * Holding the re-assert off is right while the station is serving this camera and wrong the moment it stops:
+     * a station that switches to a sibling leaves this stream with no frames, no error and no `stop`, and the
+     * warm-up watch that would have caught it was cleared by the first frame. Silence is therefore the condition
+     * the re-assert exists for, and the only one — re-arming while media flows is the contention this settle was
+     * introduced to remove.
+     *
+     * Replaced on every own-channel frame, so the window is measured from the last one.
+     *
+     * Gated on {@link LiveStreamOptions.reassertWanted}: silence with nobody attached is not a condition to
+     * act on, because the re-assert would take the station from a camera someone is watching.
+     */
+    private armStallWatch;
+    /**
+     * Re-issue the start command (idempotent while listening) — the media-start / keepalive nudge. The
+     * shared source calls this to retry a start that raced key negotiation, until frames flow. Safe to
+     * call repeatedly: `startLiveMedia` self-selects start vs keepalive per the session state.
+     */
+    nudge(force?: boolean): void;
+    private sendStart;
+    /** Stop streaming: detach the listener and tell the station to stop. Idempotent. */
+    stop(): void;
+    /** Extract the Annex-B payload from a plaintext 1300 frame (fixed 22-byte header), or undefined. */
+    private plaintextAnnexB;
+    private onFrame;
+    /**
+     * Whether this stream may take `frame` — the demultiplexer for a station that serves several cameras.
+     *
+     * Every stream over a station's session reads the same inbound feed, so with two cameras warm each stream
+     * sees both. The station DOES say which camera a media frame belongs to: measured with two cameras of
+     * different geometry streaming at once on one HomeBase, the frame's channel field partitioned them
+     * exactly — 43 frames of 1920x1080 on the started channel 0 and 28 of 640x480 on channel 2, video and
+     * audio alike — while each handle was delivered both cameras' frames.
+     *
+     * The tag is only meaningful where a station fans out to several cameras. A camera that owns its session
+     * numbers its stream for itself: one was started on channel 0 and tagged its frames channel 1, so
+     * matching there would drop the whole stream. Hence only an attached camera filters.
+     *
+     * The match is UNCONDITIONAL, however long a station serves another camera instead of this one.
+     *
+     * A station serving one camera at a time hands a newly opened camera nothing but its sibling's frames until
+     * it switches, so "no media of my own yet, plenty for someone else" is what an ordinary handover looks like
+     * and does not distinguish a station that tags differently from one that is simply busy.
+     *
+     * A stream receiving none of its own media reaches the warm-up deadline and raises a typed start failure
+     * naming the stage it got to. Delivering another camera's picture raises nothing.
+     */
+    private acceptsMedia;
+    /**
+     * The Annex-B payload of a frame that starts an access unit. The session decodes it when it can (it
+     * holds the RSA private key, and handles the plaintext form); the legacy header-strip and the ECIES
+     * {@link VideoFrameDecoder} are the fallbacks for an E2E camera.
+     */
+    private annexbOf;
+    /**
+     * Report an access unit the transport could not complete.
+     *
+     * Loud once per stream, then quiet: a station losing datagrams steadily would otherwise flood a host's
+     * log with one line per unit, and the first one already says everything the rest repeat. A dropped unit is
+     * otherwise silent in both directions: no frame reaches a consumer, and nothing states why.
+     */
+    private reportDroppedUnit;
+}
+export interface LiveStream {
+    on(event: "video", listener: (frame: LiveVideoFrame) => void): this;
+    on(event: "audio", listener: (frame: LiveAudioFrame) => void): this;
+    on(event: "start" | "stop", listener: () => void): this;
+    on(event: "error", listener: (err: Error) => void): this;
+    on(event: "budget", listener: (notice: import("../../core/contracts.js").StreamBudgetNotice) => void): this;
+    /** This channel's media start was abandoned unacknowledged — see {@link LiveStreamHandle}. */
+    on(event: "unacknowledged", listener: () => void): this;
+    emit(event: "video", frame: LiveVideoFrame): boolean;
+    emit(event: "audio", frame: LiveAudioFrame): boolean;
+    emit(event: "start" | "stop" | "unacknowledged"): boolean;
+    emit(event: "error", err: Error): boolean;
+}

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

@@ -0,0 +1,123 @@
+/**
+ * Bounded, identity-free live-startup diagnostics.
+ *
+ * A live start spans two modules — the session issues the media command and reassembles datagrams, the
+ * stream turns accepted frames into access units — so the message and its phase vocabulary have one owner
+ * here rather than a literal repeated at each call site. A caller reads these to tell one startup outcome
+ * from another, and matches on {@link LIVE_TRACE_MESSAGE} plus a {@link LiveTrace} phase to do it.
+ *
+ * Every field is a fixed label, a boolean, a data-type id, or a sign code. No serial, P2P identifier,
+ * address, account id, key material, or media byte is carried, so the records are safe in a host's log.
+ *
+ * @module p2p/live-trace
+ */
+import type { Logger } from "../../core/logger.js";
+/** The message every startup trace is logged under. */
+export declare const LIVE_TRACE_MESSAGE = "[live] start trace";
+/** One bounded startup observation. */
+export type LiveTrace = 
+/** A media start or keepalive was sent, with the topology and encryption level it was sent under. */
+{
+    phase: "media-command";
+    topology: "attached" | "own";
+    action: "start" | "keepalive";
+    level2: boolean;
+}
+/** The device acknowledged a retained start, or that start was repeated / abandoned unacknowledged. */
+ | {
+    phase: "media-command-ack" | "media-command-retry" | "media-command-unacknowledged";
+    action: "start";
+}
+/** The first inbound video command, and whether this stream's channel filter accepted it. */
+ | {
+    phase: "first-video-command";
+    signCode: number;
+    accepted: boolean;
+}
+/** The first reassembled video access unit, and whether it was decodable on its own. */
+ | {
+    phase: "first-video-unit";
+    keyframe: boolean;
+}
+/** The first keyframe reached the consumer. */
+ | {
+    phase: "first-keyframe";
+}
+/** Media tagged for another camera on the same station arrived first. */
+ | {
+    phase: "first-foreign-media-command";
+    media: "audio" | "video";
+}
+/** A video payload decoded to nothing, so no access unit could be built from it. */
+ | {
+    phase: "video-decode-empty";
+    signCode: number;
+}
+/** A datagram was missing on a data channel, discarding the logical frame being reassembled. */
+ | {
+    phase: "datagram-gap";
+    dataType: number;
+}
+/** A data channel's numbering restarted mid-connection, so sequencing resynchronized onto it. */
+ | {
+    phase: "sequence-restart";
+    dataType: number;
+}
+/**
+ * A live start is holding for the station's level-2 key, with the milliseconds it will wait.
+ *
+ * The first of three phases that account for the wait before any media command is sent. A start that looks
+ * slow is either waiting here, waiting for the station to serve the channel it was asked for, or being
+ * re-issued — and only these separate them.
+ */
+ | {
+    phase: "level2-wait";
+    waitMs: number;
+}
+/** The station's level-2 key was negotiated, under the cipher it selected. */
+ | {
+    phase: "level2-ready";
+    cipherId: number;
+}
+/** The level-2 key did not arrive in its grace, so the start proceeds at level 1 or not at all. */
+ | {
+    phase: "level2-absent";
+    waitedMs: number;
+}
+/** A shared source began warming, with the interval it re-issues on and the deadline it fails at. */
+ | {
+    phase: "warming";
+    retryMs: number;
+    deadlineMs: number;
+}
+/**
+ * A media command was never put on the wire, and what it was missing.
+ *
+ * The attached media start has no level-1 form, so without the station's level-2 key there is nothing to
+ * send. A command that was never sent is otherwise indistinguishable from one the station ignored, which is
+ * the difference between a key that never arrived and a station that is not answering.
+ */
+ | {
+    phase: "media-command-unsent";
+    reason: "level2-key" | "address";
+}
+/**
+ * This connection's path has stopped answering the heartbeat, with how long it has been silent.
+ *
+ * The station answers every PING with a PONG, so silence past several heartbeats is the path being gone.
+ * Stated only where a pong arrived: a station that has never answered says nothing by not answering now.
+ */
+ | {
+    phase: "path-stale";
+    silentMs: number;
+};
+/**
+ * Record one startup observation at debug level.
+ *
+ * `source` states which pull the record belongs to, as an OPAQUE per-process handle — never a serial, a
+ * channel or an address. A phase says what happened and nothing about where, so four cameras warming off one
+ * HomeBase produce four indistinguishable records; the handle groups them without naming anything, cannot be
+ * resolved to a device by whoever reads it, and means nothing in the next run. That is what keeps these
+ * records retainable.
+ */
+export declare function traceLiveStart(logger: Logger, trace: LiveTrace, source?: string): void;

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

@@ -0,0 +1,105 @@
+/**
+ * Camera **media** operations over P2P — live snapshot, live stream, clip recording.
+ *
+ * These take an already-resolved {@link P2PSession} (the client owns session/channel resolution) and
+ * return data. They speak only P2P + ffmpeg — no dependency on the client class — so the client stays
+ * thin and this stays the single home for the media protocol. Surfaced to consumers via
+ * `device.camera()`.
+ *
+ * `snapshotLive` / `record` shell out to ffmpeg. The binary is whatever {@link spawnFfmpeg} resolves —
+ * the bare name on `PATH` by default, or the executable the caller named (`ffmpegPath`).
+ *
+ * @module p2p/media
+ */
+import { P2PSession } from "./p2p-session.js";
+import { LiveStream, type LiveStreamOptions } from "./live-stream.js";
+import { type FfmpegLevel } from "../ffmpeg.js";
+import { type Logger } from "../../core/logger.js";
+import type { SharedLiveSource } from "./shared-live-source.js";
+/**
+ * Open a managed **live stream** on an already-connected session. Returns the {@link LiveStream}
+ * already `start()`ed; call `.stop()` when done. (Session/channel/level-2-key resolution is the
+ * caller's job — see `EufyMega.resolveSession`.)
+ */
+export declare function openLiveStream(session: P2PSession, opts?: LiveStreamOptions): Promise<LiveStream>;
+/**
+ * **Live snapshot off a SHARED source** (V6) — snapshot as just another consumer of the shared live
+ * pull. If the source is already warm and has a cached keyframe (V2 keyframe-prime), the joining
+ * consumer receives that IDR immediately and we decode it with **no extra pull** — a snapshot while
+ * someone else watches costs nothing on the wire. Otherwise we warm the source and wait for a clean
+ * keyframe (the first IDR after a cold start is frequently partial, so skip it by default). Requires
+ * `ffmpeg` for the Annex-B → JPEG decode.
+ *
+ * The returned dimensions are the ENCODED IMAGE's own, read back out of it — never the frame header's.
+ * The header states the stream's geometry when the capture started, and a stream that reconfigures
+ * mid-burst leaves it describing something the returned bytes contradict; the return value describes an
+ * image, so the image is its source of truth.
+ */
+export declare function captureSnapshotFromShared(source: SharedLiveSource, opts?: {
+    timeoutMs?: number;
+    collectMs?: number;
+    skipKeyframes?: number;
+    logger?: Logger;
+    ffmpegLevel?: FfmpegLevel;
+    ffmpegPath?: string;
+}): Promise<{
+    jpeg: Buffer;
+    width: number;
+    height: number;
+}>;
+/**
+ * **Record** a clip — collect the live H.264/H.265 stream for `seconds` and mux it to a fragmented
+ * MP4 (same source as {@link captureSnapshotFromShared}, kept running and written to a container).
+ * Recording starts at the first complete keyframe so the clip is seekable. Requires `ffmpeg`.
+ *
+ * Opens its OWN {@link LiveStream} over the session rather than joining the device's shared source, so it
+ * costs a second pull on a camera already streaming, and the shared path's release of a sibling's lingering
+ * pull does not reach it. `recordFragments` is the shared-consumer path.
+ *
+ * The clip therefore starts at the SECOND keyframe, so parameter sets announced only with the first are
+ * dropped along with it — every frame is watched for an announcement, including the skipped ones, and
+ * the collected run is primed before muxing. This also settles the codec, which is sniffed from a config NAL:
+ * a run of bare slices would otherwise fall back to H.264 and mislabel an H.265 clip.
+ *
+ * **Bounded in both phases, so it always settles.** The first phase is bounded by `timeoutMs` waiting for the
+ * keyframe the clip starts at; the second is bounded by the clip's own window, which is armed as a deadline
+ * the moment capture starts rather than being read off the next frame to arrive. A camera that goes quiet
+ * mid-clip delivers no further frame to compare a clock against — measured on an own-session camera that
+ * stopped 13.6 s into a stream with no `stop` and no `error` — so a clip whose end is decided inside a frame
+ * handler has no end at all, and the promise stays pending for the life of the process. The deadline answers
+ * with the run collected up to it: the window the caller asked for has elapsed, and frames the camera never
+ * sent cannot be waited into existence.
+ *
+ * A pull whose SESSION goes away before that window elapses fails the clip instead, naming the close. No
+ * further frame can arrive on it, so there is nothing left to wait for, and a caller that asked for a clip of
+ * a stated length is told the session went away rather than handed a fragment as if it were the clip. A decode
+ * failure on the stream fails it the same way.
+ *
+ * The `error` listener outlives the collection deliberately. An unhandled `error` on an emitter takes the host
+ * process down, and the stream is stopped only after the promise settles, so it stays attached and a late
+ * failure lands on an already-settled promise as the no-op it is.
+ */
+export declare function recordClip(session: P2PSession, seconds: number, opts?: {
+    timeoutMs?: number;
+    skipKeyframes?: number;
+    logger?: Logger;
+    ffmpegLevel?: FfmpegLevel;
+    ffmpegPath?: string;
+} & LiveStreamOptions): Promise<Buffer>;
+/**
+ * The geometry a JPEG declares in its own frame header (`SOFn`), or `undefined` when it carries none.
+ *
+ * Walks the marker segments from the SOI rather than searching for the marker bytes: a `0xffc0` pair
+ * occurs inside quantization tables and entropy-coded data, and the first one found there would answer
+ * with two bytes of image content. Every `SOFn` puts precision, then height, then width at the same
+ * offset past its length field, so one read serves all of them. Any number of `0xff` fill bytes may
+ * precede a marker, and the standalone markers carry no length to skip by — both are what a naive walk
+ * gets wrong, and either would make a perfectly good image read as having no geometry.
+ *
+ * Decoding the image (the `jpeg-js` path the v2 thumbnail decoder needs) would answer the same question,
+ * but it is synchronous pure JS over every pixel: this needs a dozen bytes of header, so it reads them.
+ */
+export declare function jpegGeometry(jpeg: Buffer): {
+    width: number;
+    height: number;
+} | undefined;