@apocaliss92/nodelink-js 0.4.11 → 0.4.13

package/dist/index.d.ts

@@ -180,15 +180,27 @@ export declare type AiTypesCacheEntry = {
 export declare type AnyBuffer = Buffer<ArrayBufferLike>;
 
 /**
- * Patch one or more fields inside an `<Enc>` stream block
- * (`<mainStream>` or `<subStream>`). Used by `setEnc` —
- * Reolink emits both blocks in the same document so a per-block scope
- * is needed to avoid clobbering the wrong stream.
- */
-export declare function applyStreamPatch(xml: string, streamTag: "mainStream" | "subStream", patch: {
+ * Patch fields inside a `<Compression>` stream block (`<mainStream>`,
+ * `<subStream>`, or `<thirdStream>`). Used by `setEnc` — Reolink emits all
+ * three blocks in the same document so a per-block scope is needed to avoid
+ * clobbering the wrong stream.
+ *
+ * The mapping `videoEncType` ↔ codec uses the convention seen on the wire:
+ *   0 = H.264
+ *   1 = H.265
+ * Both `<frame>` (camera-side preferred) and `<frameRate>` (older reolink_aio
+ * naming) are patched defensively — no-op if only one is present.
+ */
+export declare function applyStreamPatch(xml: string, streamTag: "mainStream" | "subStream" | "thirdStream", patch: {
+    audio?: 0 | 1;
+    width?: number;
+    height?: number;
     bitRate?: number;
     frameRate?: number;
     videoEncType?: "h264" | "h265";
+    encoderType?: "vbr" | "cbr";
+    encoderProfile?: "high" | "main" | "baseline";
+    gop?: number;
 } | undefined): string;
 
 /**
@@ -435,6 +447,17 @@ export declare interface AutoFocusConfig {
     };
 }
 
+/** AutoReboot schedule (cmdId=100/101). */
+export declare interface AutoRebootConfig {
+    enable: 0 | 1;
+    weekDay: DayOfWeek;
+    hour: number;
+    minute: number;
+    second: number;
+}
+
+export declare type AutoRebootConfigPatch = Partial<AutoRebootConfig>;
+
 export declare type BaichuanCachedPush<T> = {
     updatedAtMs: number;
     value: T;
@@ -464,6 +487,23 @@ export declare class BaichuanClient extends EventEmitter<{
      *   even if the current client instance is idle/disconnected.
      */
     private static readonly streamingRegistry;
+    /**
+     * Per-device set of live BaichuanClient instances.
+     *
+     * Why: when a streaming client unsubscribes (e.g. RTSP grace timer expires
+     * and SocketPool tears the streaming socket down), the global streaming
+     * registry decrements but the GENERAL client of the same device has no
+     * way of knowing — its idle-disconnect timer was last evaluated while
+     * `isDeviceStreamingActive()` was still true (because the streaming socket
+     * was still alive) and wasn't rescheduled. Without this registry the
+     * general socket stays connected, the 60-second session-guard timer keeps
+     * sending getOnlineUserList() to the camera, and a battery camera ends up
+     * waking up every minute (issue #18).
+     *
+     * On streamingRegistry decrement-to-zero we walk this set and kick every
+     * sibling's idle-disconnect timer so it can re-evaluate eligibility.
+     */
+    private static readonly deviceClients;
     /**
      * Per-host D2C_DISC backoff state that persists across client instance recreation.
      *
@@ -552,6 +592,10 @@ export declare class BaichuanClient extends EventEmitter<{
     private streamTraceStats;
     private rxCmdTraceStats;
     private readonly alarmEventState;
+    /** Whether this instance is currently in BaichuanClient.deviceClients. */
+    private registeredInDeviceClients;
+    private registerInDeviceClients;
+    private unregisterFromDeviceClients;
     constructor(options: BaichuanClientOptions);
     private newSocketSessionId;
     private logFixed;
@@ -1701,6 +1745,50 @@ export declare type BaichuanStreamInfoList = {
 
 export declare type BaichuanTransport = "tcp" | "udp";
 
+/**
+ * Snapshot of `<VersionInfo>` returned by Baichuan cmd_id=80
+ * (`BC_CMD_ID_GET_VERSION_INFO`) — the same payload the Reolink mobile app
+ * displays in "About this device". Distinct from `getSystemGeneral`
+ * (cmd_104) which holds time/locale.
+ *
+ * All fields optional because firmware variants and models include
+ * different subsets. Empty XML elements (e.g. `<cc3200Version></cc3200Version>`)
+ * come through as the empty string so callers can distinguish "absent"
+ * (undefined) from "explicitly empty" ("").
+ */
+export declare interface BaichuanVersionInfo {
+    /** User-assigned name (matches the OSD camera name). */
+    name?: string;
+    /** Model code, e.g. `"E1 Zoom"`, `"RLC-810A"`. */
+    type?: string;
+    /** Hardware serial number. */
+    serialNumber?: string;
+    /** Build identifier, typically a date string like `"build 2503281992"`. */
+    buildDay?: string;
+    /** Internal hardware revision, e.g. `"IPC_NT14NA48MPSD6"`. */
+    hardwareVersion?: string;
+    /** Config-format version Reolink uses to identify the schema the device speaks. */
+    cfgVersion?: string;
+    /** Firmware version, e.g. `"v3.2.0.4741_2503281992"`. */
+    firmwareVersion?: string;
+    /** Extended hardware detail (often hardwareVersion + region/sku suffix). */
+    detail?: string;
+    /** IE-Client identifier (legacy plug-in tag, usually `"IEClient"`). */
+    IEClient?: string;
+    /** Legacy MCU firmware version (present on some Reolink wireless models). */
+    cc3200Version?: string;
+    /** Signal-processor firmware version (rarely populated). */
+    spVersion?: string;
+    /** File extension Reolink expects for firmware updates (`"pak"`). */
+    pakSuffix?: string;
+    /** Reolink item / SKU number, e.g. `"E340"`. */
+    itemNo?: string;
+    /** AI-model bundle version (the on-device people/vehicle/animal detector). */
+    aiVersion?: string;
+    /** Diagnostic helper string the app sends to support, e.g. `"blackPointsLevel=0"`. */
+    helpVersion?: string;
+}
+
 export declare type BaichuanVideoInputPush = {
     channelId?: number;
     bright?: number;
@@ -1737,6 +1825,22 @@ export declare class BaichuanVideoStream extends EventEmitter<{
         time?: number;
     }
     ];
+    /**
+     * Raw BcMedia `additionalHeader` block emitted for every I-frame and P-frame.
+     * Carries Reolink's per-frame side-channel metadata (detection bounding boxes).
+     * `frameWidth`/`frameHeight` come from the most recent BcMedia InfoV1/V2 packet
+     * so consumers can normalize pixel coordinates against the actual stream size.
+     */
+    additionalHeader: [
+        {
+        raw: Buffer;
+        frameType: "Iframe" | "Pframe";
+        videoType: "H264" | "H265";
+        microseconds: number;
+        frameWidth?: number;
+        frameHeight?: number;
+    }
+    ];
     audioFrame: [Buffer];
     error: [Error];
     close: [];
@@ -1755,6 +1859,13 @@ export declare class BaichuanVideoStream extends EventEmitter<{
     private readonly acceptAnyStreamType;
     private lockedChannelId;
     private bcMediaCodec;
+    /**
+     * Diagnostic-only accessor for the BcMedia codec. Used by tools that need to
+     * inspect unknown chunks (for example to discover undocumented audio
+     * sub-packets the parser currently skips). Not part of the supported public
+     * surface — do not rely on it in application code.
+     */
+    get _bcMediaCodec(): BcMediaCodec;
     private debugH264LogsLeft;
     private debugSavedSamples;
     private warnedNonAnnexBOnce;
@@ -1773,6 +1884,9 @@ export declare class BaichuanVideoStream extends EventEmitter<{
     private lastPpsH265;
     private lastPrependedParamSetsH265;
     private aesStreamDecryptor;
+    private latestFrameWidth;
+    private latestFrameHeight;
+    private detectionTeardown;
     /**
      * Pending startup error stashed when emitSafeError is called before any
      * "error" listener is registered (e.g. camera returns 400 during start()).
@@ -1902,6 +2016,14 @@ export declare class BaichuanWebRTCServer extends EventEmitter {
      * H.265 → DataChannel with raw Annex-B frames (decoded by WebCodecs in browser)
      */
     private pumpFramesToWebRTC;
+    /**
+     * Lazily start the AAC → Opus transcoder for `session` and wire it to the
+     * audio RTP track. ffmpeg writes RTP-formatted Opus packets back to a UDP
+     * loopback the transcoder owns; we strip the RTP header and rewrap the
+     * Opus payload with our audioTrack's SSRC so the browser receives a
+     * coherent stream.
+     */
+    private ensureAudioTranscoder;
     /**
      * Send H.264 frame via RTP media track
      * Returns the number of RTP packets sent
@@ -1960,6 +2082,12 @@ export declare interface BaichuanWebRTCServerOptions {
     iceAdditionalHostAddresses?: string[];
     /** Force relay-only (TURN) if needed */
     iceTransportPolicy?: "all" | "relay";
+    /**
+     * Path to ffmpeg used for AAC → Opus audio transcoding. Defaults to
+     * "ffmpeg" on PATH. Pass an empty string to disable audio (the audio track
+     * will still appear in the SDP for SDP-stability, but stay silent).
+     */
+    ffmpegPath?: string;
     /** Logger callback */
     logger?: (level: "debug" | "info" | "warn" | "error", message: string) => void;
 }
@@ -2095,6 +2223,8 @@ export declare const BC_CMD_ID_GET_AUDIO_TASK = 232;
 
 export declare const BC_CMD_ID_GET_AUTO_FOCUS = 224;
 
+export declare const BC_CMD_ID_GET_AUTO_REBOOT = 101;
+
 export declare const BC_CMD_ID_GET_BATTERY_INFO = 253;
 
 export declare const BC_CMD_ID_GET_BATTERY_INFO_LIST = 252;
@@ -2109,6 +2239,10 @@ export declare const BC_CMD_ID_GET_DING_DONG_LIST = 484;
 
 export declare const BC_CMD_ID_GET_DING_DONG_SILENT = 609;
 
+export declare const BC_CMD_ID_GET_DST = 106;
+
+export declare const BC_CMD_ID_GET_EMAIL = 42;
+
 export declare const BC_CMD_ID_GET_EMAIL_TASK = 217;
 
 export declare const BC_CMD_ID_GET_ENC = 56;
@@ -2123,6 +2257,8 @@ export declare const BC_CMD_ID_GET_LED_STATE = 208;
 
 export declare const BC_CMD_ID_GET_MOTION_ALARM = 46;
 
+export declare const BC_CMD_ID_GET_NTP = 38;
+
 export declare const BC_CMD_ID_GET_ONLINE_USER_LIST = 120;
 
 export declare const BC_CMD_ID_GET_OSD_DATETIME = 44;
@@ -2155,6 +2291,8 @@ export declare const BC_CMD_ID_GET_SYSTEM_GENERAL = 104;
 
 export declare const BC_CMD_ID_GET_TIMELAPSE_CFG = 319;
 
+export declare const BC_CMD_ID_GET_VERSION_INFO = 80;
+
 export declare const BC_CMD_ID_GET_VIDEO_INPUT = 26;
 
 export declare const BC_CMD_ID_GET_WHITE_LED = 289;
@@ -2208,12 +2346,18 @@ export declare const BC_CMD_ID_SET_AUDIO_TASK = 231;
 
 export declare const BC_CMD_ID_SET_AUTO_FOCUS = 225;
 
+export declare const BC_CMD_ID_SET_AUTO_REBOOT = 100;
+
 export declare const BC_CMD_ID_SET_DAY_NIGHT_THRESHOLD = 297;
 
 export declare const BC_CMD_ID_SET_DING_DONG_CFG = 487;
 
 export declare const BC_CMD_ID_SET_DING_DONG_SILENT = 610;
 
+export declare const BC_CMD_ID_SET_DST = 107;
+
+export declare const BC_CMD_ID_SET_EMAIL = 43;
+
 export declare const BC_CMD_ID_SET_EMAIL_TASK = 216;
 
 export declare const BC_CMD_ID_SET_ENC = 57;
@@ -2222,6 +2366,10 @@ export declare const BC_CMD_ID_SET_LED_STATE = 209;
 
 export declare const BC_CMD_ID_SET_MOTION_ALARM = 47;
 
+export declare const BC_CMD_ID_SET_NTP = 39;
+
+export declare const BC_CMD_ID_SET_OSD_DATETIME = 45;
+
 export declare const BC_CMD_ID_SET_PIR_INFO = 213;
 
 export declare const BC_CMD_ID_SET_PRIVACY_MASK = 53;
@@ -2232,6 +2380,8 @@ export declare const BC_CMD_ID_SET_RECORD = 82;
 
 export declare const BC_CMD_ID_SET_RECORD_CFG = 55;
 
+export declare const BC_CMD_ID_SET_SYSTEM_GENERAL = 105;
+
 export declare const BC_CMD_ID_SET_VIDEO_INPUT = 25;
 
 export declare const BC_CMD_ID_SET_WHITE_LED_STATE = 288;
@@ -2250,6 +2400,8 @@ export declare const BC_CMD_ID_TALK_CONFIG = 201;
 
 export declare const BC_CMD_ID_TALK_RESET = 11;
 
+export declare const BC_CMD_ID_TEST_EMAIL = 141;
+
 export declare const BC_CMD_ID_UDP_KEEP_ALIVE = 234;
 
 /**
@@ -2373,7 +2525,10 @@ export declare class BcMediaCodec {
     private strict;
     private amountSkipped;
     private logger;
+    private onUnknownChunk;
     constructor(strict?: boolean, logger?: Logger);
+    /** Register a listener that fires for every unknown chunk before recovery. */
+    setUnknownChunkListener(listener: UnknownChunkListener | undefined): void;
     /**
      * Push data into the codec buffer and try to parse complete BcMedia packets.
      * Returns an array of complete BcMedia packets found.
@@ -3964,6 +4119,9 @@ export declare interface DayNightThresholdConfig {
     };
 }
 
+/** Day-of-week labels accepted by Dst and AutoReboot blocks. */
+export declare type DayOfWeek = "Sunday" | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "everyday";
+
 export declare type DebugConfig = {
     general: boolean;
     debugRtsp: boolean;
@@ -4046,6 +4204,23 @@ export declare function decodeHeader(buf: AnyBuffer): {
     messageKey: number;
 };
 
+/**
+ * Decode the base64 `valueTable` from a `<scope>` (or `<area>`) into a flat
+ * boolean grid. Bytes are packed MSB-first: bit 7 of byte 0 is cell (0,0).
+ *
+ * The camera ships TWO pairs of dimensions: `<scope><columns>×<rows>`
+ * (bitmap size — typically 96×64) and `<width>×<height>` in the parent
+ * block (the effective motion grid — typically smaller, e.g. 60×33 on
+ * E1 Zoom). The user-editable region matches `width × height`, not the
+ * full bitmap; bits past that are camera-side padding that stays 0.
+ *
+ * When `width`/`height` are omitted we treat the whole bitmap as the
+ * active region (back-compat).
+ *
+ * Throws if the base64 contains too few bytes for `columns*rows` bits.
+ */
+export declare function decodeMotionScopeBitmap(valueTable: string, columns: number, rows: number, width?: number, height?: number): MotionZoneScope;
+
 /**
  * AES key derivation used by Reolink:
  * keyString = md5_str_modern(`${nonce}-${password}`).slice(0,16)
@@ -4351,6 +4526,30 @@ export declare interface DownloadRecordingParams {
     timeoutMs?: number;
 }
 
+/** Daylight Saving Time configuration (cmdId=106/107). */
+export declare interface DstConfig {
+    enable: 0 | 1;
+    /** Offset in hours (typically 1). */
+    offset: number;
+    startMonth: number;
+    /** Week-of-month index (1..5). 5 = "last week of the month". */
+    startWeekIndex: number;
+    startWeekday: DayOfWeek;
+    startHour: number;
+    startMinute: number;
+    startSecond: number;
+    endMonth: number;
+    endWeekIndex: number;
+    endWeekday: DayOfWeek;
+    endHour: number;
+    endMinute: number;
+    endSecond: number;
+    /** Schema version (returned by camera, defaults to 0). */
+    version?: number;
+}
+
+export declare type DstConfigPatch = Partial<DstConfig>;
+
 export declare const DUAL_LENS_DUAL_MOTION_MODELS: Set<string>;
 
 export declare const DUAL_LENS_MODELS: Set<string>;
@@ -4425,19 +4624,73 @@ export declare interface DualLensChannelInfo {
     };
 }
 
+/** Image vs video attachment for motion alert emails. */
+export declare type EmailAttachmentType = "picture" | "video" | "none";
+
 /**
- * Email task configuration.
- */
+ * Email SMTP server configuration. Returned by GetEmail (cmdId=42) and
+ * accepted by SetEmail (cmdId=43) and TestEmail (cmdId=141).
+ *
+ * Read-only fields (only present on GET): `senderMaxLen`, `pwdMaxLen`,
+ * `emailAttachAbility` — the camera-reported capability bitmap.
+ */
+export declare interface EmailConfig {
+    smtpServer: string;
+    /** Sender email address / SMTP username. Empty when unconfigured. */
+    userName: string;
+    /** SMTP password. Always sent in cleartext — camera limitation. */
+    password: string;
+    /** Recipient 1. */
+    address1: string;
+    /** Recipient 2 (optional). */
+    address2: string;
+    /** Recipient 3 (optional). */
+    address3: string;
+    smtpPort: number;
+    sendNickname: string;
+    /** 1 = attach picture/video, 0 = text-only. */
+    attachment: 0 | 1;
+    attachmentType: EmailAttachmentType;
+    textType: EmailTextType;
+    /** 1 = SSL/TLS, 0 = plain SMTP. */
+    ssl: 0 | 1;
+    /** Throttle between successive motion mails in seconds. Ignored on battery cams. */
+    interval: number;
+    senderMaxLen?: number;
+    pwdMaxLen?: number;
+    /** Bitmap of supported attachment combinations. */
+    emailAttachAbility?: number;
+}
+
+/** Patch payload accepted by SetEmail. All fields optional — only supplied ones are written. */
+export declare type EmailConfigPatch = Partial<Omit<EmailConfig, "senderMaxLen" | "pwdMaxLen" | "emailAttachAbility">>;
+
+/** Email schedule configuration (cmdId=216/217). */
 export declare interface EmailTaskConfig {
-    body?: {
-        EmailTask?: {
-            channelId?: number | undefined;
-            enable?: number | undefined;
-            [key: string]: unknown;
-        };
-    };
+    channelId: number;
+    enable: 0 | 1;
+    typeScheduleList: EmailTaskScheduleItem[];
 }
 
+/**
+ * Single entry in the EmailTask `typeScheduleList`. `valueTable` is a
+ * 168-char string of '0'/'1' representing the 7-days × 24-hours grid.
+ */
+export declare interface EmailTaskScheduleItem {
+    /**
+     * Trigger type. Known: "MD" (motion), "Normal" (continuous record),
+     * "people", "vehicle", "dog_cat", "face", "package", "cry", "visitor",
+     * "doorbell", "none" (placeholder slot).
+     * Treated as string to cover firmware-specific extensions.
+     */
+    type: string;
+    /** 168-char 0/1 schedule bitmap. */
+    valueTable: string;
+}
+
+/** Whether the alert body carries the standard human-readable text. */
+export declare type EmailTextType = "withText" | "noText";
+
 /**
  * Encoding configuration (getEnc response).
  * cmdId=56 (GetEnc) — payload is wrapped in `Compression`, not `Enc`.
@@ -4463,6 +4716,49 @@ export declare function encodeHeader(h: Omit<BaichuanHeader, "magic"> & {
     magic?: AnyBuffer;
 }): AnyBuffer;
 
+/**
+ * Encode a `width × height` boolean grid back into the camera's
+ * `columns × rows` `valueTable`. Bits outside the active region stay 0,
+ * matching what the camera ships on the way down.
+ *
+ * `scope.cells.length` must equal `scope.width * scope.height`.
+ */
+export declare function encodeMotionScopeBitmap(scope: MotionZoneScope): string;
+
+/**
+ * Reply from `getEncOptions` — the set of allowable values for `setEnc`,
+ * derived from `getStreamInfoList`. Use this to validate user input or
+ * populate UI selectors.
+ */
+export declare interface EncOptions {
+    channel: number;
+    mainStream?: EncStreamOptions;
+    subStream?: EncStreamOptions;
+    thirdStream?: EncStreamOptions;
+}
+
+/**
+ * One allowable resolution from a `getEncOptions` reply.
+ * `videoEncTypeList` enumerates the codecs supported at this resolution
+ * (mapped to `"h264"`/`"h265"`).
+ */
+export declare interface EncResolutionOption {
+    width: number;
+    height: number;
+    /** Codecs available at this resolution. */
+    videoEncTypes: Array<"h264" | "h265">;
+    /** Camera-default framerate at this resolution, if reported. */
+    defaultFramerate?: number;
+    /** Camera-default bitrate (kbps) at this resolution, if reported. */
+    defaultBitrate?: number;
+    /** Camera-default GOP at this resolution, if reported. */
+    defaultGop?: number;
+    /** Allowed framerate values. */
+    framerateOptions: number[];
+    /** Allowed bitrate values (kbps). */
+    bitrateOptions: number[];
+}
+
 export declare type EncryptionProtocol = {
     kind: "none";
 } | {
@@ -4475,6 +4771,40 @@ export declare type EncryptionProtocol = {
     key: Buffer;
 };
 
+/**
+ * Allowable values for a single stream profile (mainStream / subStream / thirdStream).
+ * Aggregated from `getStreamInfoList` (cmd_146) so consumers can populate UI
+ * pickers without re-implementing the parsing logic.
+ */
+export declare interface EncStreamOptions {
+    /** Stream profile (one of `mainStream` / `subStream` / `thirdStream`). */
+    type: string;
+    /** Each entry is a `{width, height}` paired with its allowed values. */
+    resolutions: EncResolutionOption[];
+    /** Encoder rate-control modes Reolink exposes in the app. */
+    encoderTypes: Array<"vbr" | "cbr">;
+    /** Encoder profiles Reolink exposes in the app. */
+    encoderProfiles: Array<"high" | "main" | "baseline">;
+}
+
+/**
+ * Patch payload accepted by `setEnc` for a single stream block
+ * (`mainStream` / `subStream` / `thirdStream`). All fields optional —
+ * unspecified ones are preserved from the device's current config.
+ */
+export declare interface EncStreamPatch {
+    audio?: 0 | 1;
+    width?: number;
+    height?: number;
+    bitRate?: number;
+    frameRate?: number;
+    videoEncType?: "h264" | "h265";
+    encoderType?: "vbr" | "cbr";
+    encoderProfile?: "high" | "main" | "baseline";
+    /** Keyframe interval in seconds — patches `<gop><cur>`. */
+    gop?: number;
+}
+
 /**
  * Prepend the XML declaration if the body doesn't already start with
  * one. Reolink rejects payloads without it on most setX commands.
@@ -4557,7 +4887,7 @@ export declare interface FloodlightTaskConfig {
  * Parse FloodlightTask XML to extract floodlight-on-motion state.
  * Returns the alarmMode (1 = floodlight turns on when motion detected, 0 = off)
  */
-declare interface FloodlightTaskState {
+export declare interface FloodlightTaskState {
     /** Whether floodlight turns on when motion is detected (alarmMode) */
     floodlightOnMotion: boolean;
     /** Whether the task is enabled */
@@ -4585,6 +4915,13 @@ export declare interface FtpTaskConfig {
     };
 }
 
+/**
+ * Convenience: build an "everything enabled" grid of the given dimensions.
+ * Useful when the camera response has no `<valueTable>` and we want to
+ * start the user off with a clean slate.
+ */
+export declare function fullCoverageScope(columns: number, rows: number, width?: number, height?: number): MotionZoneScope;
+
 /**
  * Get constructed video stream options for all available profiles.
  *
@@ -4733,6 +5070,9 @@ export declare class Go2rtcTcpServer extends EventEmitter<{
     private resolvedPort;
     private nativeFanout;
     private nativeStreamActive;
+    private nativeStreamStopping;
+    private nativeStreamRetryTimer;
+    private nativeStreamRetryDelayMs;
     private dedicatedSessionRelease;
     private detectedVideoType;
     private connectedClients;
@@ -4794,6 +5134,21 @@ export declare class Go2rtcTcpServer extends EventEmitter<{
      * Returns null when the buffer is not a valid ADTS frame.
      */
     private static parseAdtsSamplingInfo;
+    /**
+     * Schedule another startNativeStream() attempt after the given delay.
+     * Idempotent: a no-op if a retry is already scheduled, the server is no
+     * longer active, or an explicit stop is in progress. Implements unbounded
+     * exponential backoff (5s → 60s) so a camera that stays unreachable for
+     * minutes (e.g. nightly maintenance reboot) eventually recovers without
+     * manual intervention — see issue #16.
+     */
+    private scheduleNativeStreamRetry;
+    /**
+     * Cancel any pending retry timer and reset the backoff. Called on explicit
+     * stop and on first-frame-received so the next failure starts the backoff
+     * window from scratch.
+     */
+    private clearNativeStreamRetry;
     private startNativeStream;
     private stopNativeStream;
     private startStreamHealthMonitor;
@@ -5463,6 +5818,37 @@ export declare interface MotionEvent {
     source?: "md" | "pir" | "unknown";
 }
 
+/**
+ * Motion-detection zone grid helpers.
+ *
+ * Reolink's GetMdAlarm response (cmd_id=46) carries the active detection
+ * region as a base64-encoded bitmap inside `<scope><valueTable>...</valueTable></scope>`.
+ * The bitmap has one bit per grid cell:
+ *
+ *   <scope>
+ *     <columns>96</columns>
+ *     <rows>64</rows>
+ *     <valueTable>{base64 of columns*rows bits, packed MSB-first per byte}</valueTable>
+ *   </scope>
+ *
+ * The same shape is reused by AI detection (`<AiDetectCfg><area>...</area>`)
+ * — only the column/row counts differ across firmwares. Use the helpers
+ * here to round-trip between the camera's base64 string and a flat boolean
+ * grid the UI can render and edit.
+ */
+export declare interface MotionZoneScope {
+    /** Active region width (effective grid columns, `<width>` in MD). */
+    width: number;
+    /** Active region height (effective grid rows, `<height>` in MD). */
+    height: number;
+    /** Bitmap columns reported by `<scope><columns>`. */
+    columns: number;
+    /** Bitmap rows reported by `<scope><rows>`. */
+    rows: number;
+    /** Flat `width × height` array, row-major. `true` = cell included. */
+    cells: boolean[];
+}
+
 /**
  * Stateful MPEG-TS muxer.  Each instance has its own continuity counters —
  * create one per output stream (or per client connection for prebuffer replay).
@@ -5561,6 +5947,20 @@ export declare function normalizeOpenClose(input: string): string;
  */
 export declare function normalizeUid(uid?: string): string | undefined;
 
+/** NTP server configuration (cmdId=38/39). */
+export declare interface NtpConfig {
+    /** 1 = NTP sync enabled, 0 = disabled. */
+    enable: 0 | 1;
+    /** Hostname or IP of the NTP server. */
+    server: string;
+    /** Sync interval in minutes. */
+    synchronizeInterval: number;
+    /** UDP port. Default 123. */
+    port: number;
+}
+
+export declare type NtpConfigPatch = Partial<NtpConfig>;
+
 /**
  * Exact type values that indicate NVR/Hub devices.
  * These are checked with exact case-insensitive match.
@@ -5628,6 +6028,9 @@ export declare interface OsdConfig {
     bgcolor?: number;
 }
 
+/** OSD date format. */
+export declare type OsdDateFormat = "DMY" | "MDY" | "YMD";
+
 export declare interface OsdTime {
     enable: number;
     pos: string;
@@ -5996,6 +6399,12 @@ export declare class ReolinkBaichuanApi {
     private sessionGuardIntervalTimer;
     private readonly simpleEventListeners;
     private simpleEventSubscribed;
+    private readonly detectionEventListeners;
+    private readonly detectionEventStreamHooks;
+    private readonly objectDetectionListeners;
+    private objectDetectionStream;
+    private objectDetectionStreamStartInFlight;
+    private objectDetectionInternalListener;
     private simpleEventSubscribeInFlight;
     private simpleEventUnsubscribeInFlight;
     private simpleEventResubscribeTimer;
@@ -6413,6 +6822,73 @@ export declare class ReolinkBaichuanApi {
      * When the last listener is removed, the API unsubscribes from Baichuan events.
      */
     offSimpleEvent(callback?: (event: ReolinkSimpleEvent) => void | Promise<void>): Promise<void>;
+    /**
+     * Subscribe to per-frame detection events sourced from the BcMedia
+     * `additionalHeader` block on active video streams.
+     *
+     * Mirrors {@link onSimpleEvent} but is fed by the streaming side-channel:
+     * one event fires for every I-frame / P-frame that carries an overlay block.
+     * Coordinates are reported in normalized [0, 1] fractions of the source
+     * frame, so the same box renders correctly on mainStream, subStream, and
+     * externStream.
+     *
+     * Unlike `onSimpleEvent`, no Baichuan subscribe command is involved — events
+     * only flow while a video stream is open. The library hooks every
+     * `BaichuanVideoStream` created via this API for the listener's lifetime.
+     */
+    onDetection(callback: (event: ReolinkDetectionEvent) => void | Promise<void>): void;
+    /**
+     * Remove a single detection callback, or all of them if `callback` is omitted.
+     */
+    offDetection(callback?: (event: ReolinkDetectionEvent) => void | Promise<void>): void;
+    /**
+     * Subscribe to AI object detections (people / vehicle / animal / face boxes
+     * with class label and confidence) without managing a video stream yourself.
+     *
+     * Mirrors {@link onSimpleEvent} end-to-end: the API opens a dedicated
+     * substream behind the scenes on the first listener, forwards every box-bearing
+     * `additionalHeader` to your callback, and tears the stream down when the last
+     * listener unsubscribes. The substream is the lightest profile (typically
+     * 640×360) so the additional bandwidth/CPU overhead is minimal.
+     *
+     * Each event carries normalized `[0, 1]` box coordinates, a class label, and
+     * a confidence score — render-ready without further conversion.
+     */
+    onObjectDetections(callback: (event: ReolinkDetectionEvent) => void | Promise<void>): Promise<void>;
+    /**
+     * Remove one detection callback, or all of them if `callback` is omitted.
+     * When the last listener is removed the auto-managed substream is closed.
+     */
+    offObjectDetections(callback?: (event: ReolinkDetectionEvent) => void | Promise<void>): Promise<void>;
+    private ensureObjectDetectionStream;
+    private tearDownObjectDetectionStream;
+    /**
+     * Internal: invoked by BaichuanVideoStream when it starts so the API can hook
+     * its `additionalHeader` event. Returns a teardown function the stream calls
+     * on stop. Not intended for direct use by consumers.
+     */
+    _registerVideoStreamForDetection(stream: {
+        on: (event: "additionalHeader", listener: (info: {
+            raw: Buffer;
+            frameType: "Iframe" | "Pframe";
+            videoType: "H264" | "H265";
+            microseconds: number;
+            frameWidth?: number;
+            frameHeight?: number;
+        }) => void) => void;
+        off: (event: "additionalHeader", listener: (info: {
+            raw: Buffer;
+            frameType: "Iframe" | "Pframe";
+            videoType: "H264" | "H265";
+            microseconds: number;
+            frameWidth?: number;
+            frameHeight?: number;
+        }) => void) => void;
+    }, context: {
+        channel: number;
+        profile: "main" | "sub" | "ext";
+    }): () => void;
+    private dispatchDetectionEvent;
     private startSimpleEventResubscribeTimer;
     private stopSimpleEventResubscribeTimer;
     /**
@@ -6568,6 +7044,55 @@ export declare class ReolinkBaichuanApi {
         port: "rtsp" | "rtmp" | "onvif" | "http" | "https";
         enable: boolean;
     }): Promise<void>;
+    /**
+     * Full port-config setter (cmd_id 36). Patches one or more of the six
+     * service ports the camera serves — Server (Baichuan), HTTP, HTTPS,
+     * RTSP, RTMP, ONVIF. Each entry takes an optional `port` (number) and
+     * `enable` (boolean); fields the caller doesn't pass are left alone.
+     *
+     * Sends one block per port that has any field set, then issues a
+     * single cmd_36 with the merged body. The camera accepts multiple
+     * `<XxxPort>` siblings in the same payload.
+     *
+     * Wire format observed on E1 Zoom:
+     *
+     *   <body>
+     *     <RtspPort version="1.1">
+     *       <rtspPort>554</rtspPort>
+     *       <enable>1</enable>
+     *     </RtspPort>
+     *     <HttpsPort version="1.1">
+     *       <enable>0</enable>
+     *     </HttpsPort>
+     *     ...
+     *   </body>
+     */
+    setPortConfig(patch: {
+        server?: {
+            port?: number;
+            enable?: boolean;
+        };
+        http?: {
+            port?: number;
+            enable?: boolean;
+        };
+        https?: {
+            port?: number;
+            enable?: boolean;
+        };
+        rtsp?: {
+            port?: number;
+            enable?: boolean;
+        };
+        rtmp?: {
+            port?: number;
+            enable?: boolean;
+        };
+        onvif?: {
+            port?: number;
+            enable?: boolean;
+        };
+    }): Promise<void>;
     /** GetDevInfo via Baichuan: host cmd_id 80, channel cmd_id 318 */
     getInfo(channel?: number, options?: {
         timeoutMs?: number;
@@ -7358,6 +7883,15 @@ export declare class ReolinkBaichuanApi {
      */
     setPtzPreset(presetId: number, name: string, channel?: number): Promise<void>;
     setPtzPreset(channel: number, presetId: number, name: string): Promise<void>;
+    /**
+     * Recall (move to) a saved PTZ preset.
+     *
+     * cmd_id 19 (PTZ_CONTROL_PRESET) with command="toPos". The camera moves
+     * the head at its own default preset-recall speed; we don't expose
+     * speed here because most firmwares ignore the field on toPos.
+     */
+    gotoPtzPreset(presetId: number, channel?: number): Promise<void>;
+    gotoPtzPreset(channel: number, presetId: number): Promise<void>;
     /**
      * Best-effort delete/disable a PTZ preset.
      *
@@ -7532,6 +8066,39 @@ export declare class ReolinkBaichuanApi {
      */
     setMotionDetection(enabled: boolean, sensitivity?: number, channel?: number): Promise<void>;
     setMotionDetection(channel: number, enabled: boolean, sensitivity?: number): Promise<void>;
+    /**
+     * Set motion alarm with full control, including the detection-zone grid.
+     *
+     * Wire format observed on E1 Zoom (cmd_id=47 SetMdAlarm body):
+     *
+     *   <MD version="1.1">
+     *     <channelId>0</channelId>
+     *     <enable>1</enable>
+     *     <usepir>0</usepir>
+     *     <width>60</width> <height>33</height>
+     *     <scope>
+     *       <columns>96</columns> <rows>64</rows>
+     *       <valueTable>{base64 6144-bit bitmap}</valueTable>
+     *     </scope>
+     *     ... other camera-specific fields ...
+     *   </MD>
+     *
+     * We do a read-modify-write of the GET response so any camera-specific
+     * extension fields are preserved untouched. Pass `valueTable` to update
+     * the detection zone — see `encodeMotionScopeBitmap` for the bitmap layout.
+     *
+     * @param channel - 0-based channel
+     * @param enabled - toggle motion detection on/off (optional)
+     * @param sensitivity - 0-50, higher = more sensitive (optional)
+     * @param valueTable - base64-encoded grid bitmap; size must match
+     *   `<scope><columns>×<rows></scope>` from the GET (optional)
+     */
+    setMotionAlarmFull(opts: {
+        channel?: number;
+        enabled?: boolean;
+        sensitivity?: number;
+        valueTable?: string;
+    }): Promise<void>;
     /**
      * Set AI detection settings via Baichuan.
      * cmd_id: 343 (SetAiAlarm)
@@ -7822,25 +8389,30 @@ export declare class ReolinkBaichuanApi {
     }): Promise<EncConfig>;
     /**
      * SetEnc via Baichuan (cmdId=57). Read-modify-write — preserves
-     * unspecified fields. Mirrors reolink_aio's `SetEnc`.
+     * unspecified fields. Mirrors reolink_aio's `SetEnc` plus the additional
+     * `width`/`height`/`encoderType`/`encoderProfile`/`gop`/`thirdStream`
+     * fields observed in the official mobile app (see `pcap/resolution.pcapng`).
+     *
+     * Field meaning per stream:
+     *  - `audio`           — 0/1 toggle
+     *  - `width`/`height`  — resolution in pixels. Must be one of the
+     *                        resolutions returned by {@link getStreamInfoList}.
+     *  - `bitRate`         — kbps. Must match the table from `getStreamInfoList`.
+     *  - `frameRate`       — fps. Must match the table from `getStreamInfoList`.
+     *  - `videoEncType`    — `"h264"` or `"h265"`
+     *  - `encoderType`     — `"vbr"` or `"cbr"`
+     *  - `encoderProfile`  — `"high"`, `"main"`, or `"baseline"`
+     *  - `gop`             — keyframe interval in seconds (sets `<gop><cur>`)
      *
      * @param channel - Channel number (0-based)
-     * @param patch - Fields to update on `mainStream` and/or `subStream`,
-     *   plus a top-level `audio` toggle (0/1). Pass only what you want
-     *   to change.
+     * @param patch - Fields to update. Pass only the fields you want to change;
+     *   everything else is preserved from the device's current configuration.
      */
     setEnc(channel: number, patch: {
         audio?: 0 | 1;
-        mainStream?: {
-            bitRate?: number;
-            frameRate?: number;
-            videoEncType?: "h264" | "h265";
-        };
-        subStream?: {
-            bitRate?: number;
-            frameRate?: number;
-            videoEncType?: "h264" | "h265";
-        };
+        mainStream?: EncStreamPatch;
+        subStream?: EncStreamPatch;
+        thirdStream?: EncStreamPatch;
     }, options?: {
         timeoutMs?: number;
     }): Promise<void>;
@@ -8100,6 +8672,35 @@ export declare class ReolinkBaichuanApi {
     getCoordinatePointListFromPushCache(channel?: number): BaichuanCachedPush<BaichuanCoordinatePointListPush> | undefined;
     private isNvrLikeDevice;
     private sendPcapDerivedSettingsGetXml;
+    /**
+     * Update the OSD timestamp + channel-name overlay via cmd_id=45
+     * (SetOsdDatetime). The schema is the same `<body><OsdDatetime>` +
+     * `<OsdChannelName>` block returned by `getOsdDatetime` — we
+     * read-modify-write so any extension fields the camera sent are
+     * preserved.
+     *
+     * Position is in **camera pixel coordinates** (e.g. (1,1) for top-left,
+     * not preset strings). Set `enable=0` to hide the overlay; the camera
+     * keeps the stored position so re-enabling later restores it.
+     */
+    setOsdDatetime(channel: number, patch: {
+        datetime?: {
+            enable?: boolean | 0 | 1;
+            topLeftX?: number;
+            topLeftY?: number;
+            language?: string;
+        };
+        channelName?: {
+            name?: string;
+            enable?: boolean | 0 | 1;
+            topLeftX?: number;
+            topLeftY?: number;
+            enWatermark?: boolean | 0 | 1;
+            enBgcolor?: boolean | 0 | 1;
+        };
+    }, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
     getOsdDatetime(channel: number, options?: {
         timeoutMs?: number;
     }): Promise<BaichuanGetOsdDatetimeResult>;
@@ -8118,6 +8719,36 @@ export declare class ReolinkBaichuanApi {
     getStreamInfoList(channel: number, options?: {
         timeoutMs?: number;
     }): Promise<BaichuanStreamInfoList>;
+    /**
+     * Return the set of values `setEnc` will accept on each stream of `channel`.
+     * Aggregates `getStreamInfoList` (cmd_146) into a UI-friendly shape:
+     * per-stream resolutions with their allowed codecs/framerates/bitrates plus
+     * the enumerated encoder modes/profiles Reolink exposes.
+     *
+     * Useful for populating selectors and validating user input before calling
+     * `setEnc` — picking an unsupported combination causes the camera to reject
+     * the SET_ENC command (responseCode != 200).
+     */
+    getEncOptions(channel: number, options?: {
+        timeoutMs?: number;
+    }): Promise<EncOptions>;
+    /**
+     * Read the camera's `<VersionInfo>` block (cmd_id=80). Returns the
+     * friendly name, model code (e.g. `"E1 Zoom"`), serial number, firmware
+     * version, hardware revision, build day, AI model bundle version, etc.
+     *
+     * This is the same info the Reolink mobile app shows in "About this
+     * device" — distinct from `getSystemGeneral` (cmd_104) which carries
+     * time/locale.
+     *
+     * No channel parameter: this command is device-global on NVRs/Hubs and
+     * camera-global on standalone cameras. Pass an explicit channel via the
+     * underlying `sendXml` only if a specific firmware demands it (none we've
+     * tested do).
+     */
+    getVersionInfo(options?: {
+        timeoutMs?: number;
+    }): Promise<BaichuanVersionInfo>;
     getLedState(channel: number, options?: {
         timeoutMs?: number;
     }): Promise<BaichuanLedState>;
@@ -8139,6 +8770,178 @@ export declare class ReolinkBaichuanApi {
     getEmailTask(channel?: number, options?: {
         timeoutMs?: number;
     }): Promise<EmailTaskConfig>;
+    /**
+     * SetEmailTask via Baichuan (cmdId=216). Updates the email alarm schedule
+     * (per-event-type 7×24 valueTable + master enable).
+     *
+     * Reolink expects the FULL `typeScheduleList` — pass the array from a prior
+     * GET and only flip the entries you care about. Slots you don't track must
+     * be sent back unchanged to avoid the camera dropping them.
+     */
+    setEmailTask(channel: number | undefined, task: EmailTaskConfig, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Convenience wrapper that patches the schedule of one or more trigger
+     * types on the camera's EmailTask without touching the others.
+     *
+     * Pass a high-level schedule spec (`always` / `never` / explicit windows)
+     * and the trigger types it should apply to. The method:
+     *
+     * 1. Reads the current EmailTask via GET (so we keep every existing slot).
+     * 2. Builds the new `valueTable` once from `schedule`.
+     * 3. Replaces the `valueTable` of every matching `type` in the list.
+     * 4. Appends entries for any requested type not already present.
+     * 5. Writes the merged list back via SET.
+     *
+     * Returns the list of types that were actually touched.
+     */
+    patchEmailSchedule(channel: number | undefined, spec: {
+        types: string[];
+        schedule: {
+            kind: "always";
+        } | {
+            kind: "never";
+        } | {
+            kind: "windows";
+            windows: Array<{
+                days: number[];
+                startHour: number;
+                endHour: number;
+            }>;
+        };
+        /** When provided, also flips the EmailTask master `enable` flag. */
+        enable?: 0 | 1;
+    }, options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        touchedTypes: string[];
+    }>;
+    /**
+     * Read the SMTP email configuration (cmdId=42). Returns the full `<Email>`
+     * block including capability hints (`senderMaxLen`, `pwdMaxLen`,
+     * `emailAttachAbility`).
+     */
+    getEmail(options?: {
+        timeoutMs?: number;
+    }): Promise<EmailConfig>;
+    /**
+     * Patch the SMTP email configuration (cmdId=43). Reads the current config
+     * first then merges the patch — Reolink rejects partial `<Email>` blocks.
+     */
+    setEmail(patch: EmailConfigPatch, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Send a test email using either the current config or an override patch
+     * (cmdId=141). Returns true when the camera reports 200 (test succeeded),
+     * false when it reports 482 (test failed — server unreachable / bad creds).
+     * Other non-200 codes propagate as exceptions via `sendXml`.
+     */
+    testEmail(patch?: EmailConfigPatch, options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    /**
+     * Read the NTP server configuration (cmdId=38).
+     */
+    getNtp(options?: {
+        timeoutMs?: number;
+    }): Promise<NtpConfig>;
+    /**
+     * Patch the NTP server configuration (cmdId=39). Reads the current state
+     * first and merges the patch — Reolink rejects partial `<Ntp>` blocks.
+     */
+    setNtp(patch: NtpConfigPatch, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Patch SystemGeneral (cmdId=105). Supports partial payloads: include only
+     * the fields you want to change. By default the builder emits `<year>0</year>`
+     * as the "do not set manual clock" marker; pass `manualTime` to actually
+     * set the date/time. Setting only `deviceName` automatically uses the
+     * Reolink Client's `deviceNameOnly=1` shape.
+     */
+    setSystemGeneral(patch: SystemGeneralPatch, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Read the Daylight Saving Time configuration (cmdId=106).
+     */
+    getDst(options?: {
+        timeoutMs?: number;
+    }): Promise<DstConfig>;
+    /**
+     * Patch the DST configuration (cmdId=107). Reads the current state first
+     * and merges the patch.
+     */
+    setDst(patch: DstConfigPatch, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Read the auto-reboot schedule (cmdId=101).
+     */
+    getAutoReboot(options?: {
+        timeoutMs?: number;
+    }): Promise<AutoRebootConfig>;
+    /**
+     * Patch the auto-reboot schedule (cmdId=100).
+     */
+    setAutoReboot(patch: AutoRebootConfigPatch, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * High-level helper that configures the camera to deliver motion alerts via
+     * SMTP to the local nodelink manager. Orchestrates `setEmail` + `setEmailTask`
+     * in a single call so UI code can offer "auto-configure" without juggling
+     * the underlying commands.
+     *
+     * Pass `runTest: true` to also send a test email (cmdId=141). Returns a
+     * structured result describing each leg of the flow so the caller can show
+     * granular feedback.
+     *
+     * @param params Auto-configuration parameters
+     * @param channel Logical channel (default 0). Used for the EmailTask SET.
+     */
+    setupEmailPushToManager(params: {
+        /** Manager hostname or IP reachable from the camera's network. */
+        managerHost: string;
+        /** Manager SMTP port. Default 2525. */
+        managerPort?: number;
+        /** Per-camera recipient local-part — typically `cam-<cameraId>`. */
+        recipientLocalPart: string;
+        /** Virtual mail domain (must match the server-side setting). */
+        domain?: string;
+        /** Attachment kind on motion. Default "picture". */
+        attachmentType?: "picture" | "video" | "none";
+        /** Optional sender nickname shown in the From header. */
+        sendNickname?: string;
+        /** Interval throttle in seconds (ignored on battery cams). Default 30. */
+        interval?: number;
+        /** Optional SMTP auth — required when the server's `requireAuth` is on. */
+        authUsername?: string;
+        authPassword?: string;
+        /**
+         * Trigger types to enable in the email schedule. Must match the types
+         * already present in the current EmailTask (we patch their schedule to
+         * full-week 24/7, leaving any other slot untouched).
+         */
+        triggerTypes?: string[];
+        /** Send a test email after the SET. Default false. */
+        runTest?: boolean;
+    }, channel?: number, options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        setEmail: {
+            applied: true;
+        };
+        setEmailTask: {
+            applied: true;
+            touchedTypes: string[];
+        };
+        testEmail?: {
+            success: boolean;
+        };
+    }>;
     /**
      * Get siren-on-motion state via AudioTask (cmdId=232).
      *
@@ -9353,6 +10156,64 @@ export declare interface ReolinkDayNightNotification {
     timestamp?: number;
 }
 
+/**
+ * A single detection bounding box in normalized [0, 1] coordinates relative to
+ * the source video frame. Using fractions instead of pixels keeps the same box
+ * valid across mainStream / subStream / externStream output and across firmware
+ * resolution changes.
+ */
+export declare interface ReolinkDetectionBox {
+    /** Left edge in [0, 1] (0 = left, 1 = right). */
+    x: number;
+    /** Top edge in [0, 1] (0 = top, 1 = bottom). */
+    y: number;
+    /** Width in [0, 1]. */
+    width: number;
+    /** Height in [0, 1]. */
+    height: number;
+    /** AI class label if the camera reports one (e.g. "person", "vehicle"). */
+    label?: string;
+    /** Confidence in [0, 1] if exposed by the camera. */
+    confidence?: number;
+}
+
+/**
+ * Diagnostic state describing how much of the BcMedia additionalHeader the
+ * decoder was able to interpret. Useful for consumers iterating on the format.
+ */
+export declare type ReolinkDetectionDecodeState = 
+/** Header marker was missing or malformed. */
+"invalid-marker"
+/** Baseline 128-byte header — camera reports no overlay metadata. */
+| "no-overlay"
+/** Overlay block present, but coordinates have not been decoded yet. */
+| "overlay-undecoded"
+/** Overlay block decoded successfully. */
+| "overlay-decoded";
+
+/**
+ * High-level "detection" event emitted alongside every video frame that carries
+ * a non-empty BcMedia additionalHeader. Mirrors `ReolinkSimpleEvent` but is
+ * sourced from the streaming side-channel rather than from cmd_id 33 push events.
+ */
+export declare interface ReolinkDetectionEvent {
+    channel: number;
+    /** Microseconds timestamp from the BcMedia video frame. */
+    microseconds: number;
+    /** Stream profile that produced the underlying frame. */
+    profile: "main" | "sub" | "ext";
+    /** Boxes in [0, 1] fractional coordinates. */
+    boxes: ReolinkDetectionBox[];
+    /** Source frame width (from BcMedia InfoV1/V2) if known. */
+    frameWidth?: number;
+    /** Source frame height (from BcMedia InfoV1/V2) if known. */
+    frameHeight?: number;
+    /** Decoder diagnostic state. */
+    decodeState: ReolinkDetectionDecodeState;
+    /** Raw additionalHeader bytes — kept for downstream decoder work. */
+    rawHeader: Buffer;
+}
+
 export declare interface ReolinkDeviceInfo {
     type?: string;
     hardwareVersion?: string;
@@ -10126,21 +10987,55 @@ export declare interface SupportItem {
 }
 
 /**
- * System general configuration.
- * cmdId=77 (GetSystemGeneral)
+ * Full SystemGeneral block returned by cmdId=104. SET (cmdId=105) accepts a
+ * subset (any combination of these fields) plus the mandatory `<year>0</year>`
+ * marker that signals "do not set the manual clock". When you DO want to set
+ * the manual clock, pass year/month/day/hour/minute/second together.
  */
 export declare interface SystemGeneralConfig {
-    body?: {
-        SystemGeneral?: {
-            timeZone?: number | undefined;
-            deviceName?: string | undefined;
-            language?: string | undefined;
-            dstMode?: number | undefined;
-            [key: string]: unknown;
-        };
-        Norm?: {
-            [key: string]: unknown;
-        };
+    /** Timezone offset in seconds. POSIX convention: UTC+1 → -3600. */
+    timeZone: number;
+    osdFormat: OsdDateFormat;
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    deviceId: number;
+    timeFormat: TimeFormat;
+    language: string;
+    deviceName: string;
+    loginLock: 0 | 1;
+    lockTime: number;
+    allowedTimes: number;
+    /** 1 when DST is currently active (camera-side). Read-only on most firmwares. */
+    isDst: 0 | 1;
+}
+
+/**
+ * Patch accepted by SetSystemGeneral. When `manualTime` is provided, the
+ * year/month/day/hour/minute/second fields are sent as-is. When omitted, the
+ * builder injects `<year>0</year>` to skip the manual clock even when other
+ * fields are present. Setting only `deviceName` triggers the
+ * `<deviceNameOnly>1</deviceNameOnly>` flag automatically.
+ */
+export declare interface SystemGeneralPatch {
+    timeZone?: number;
+    osdFormat?: OsdDateFormat;
+    timeFormat?: TimeFormat;
+    language?: string;
+    deviceName?: string;
+    loginLock?: 0 | 1;
+    lockTime?: number;
+    allowedTimes?: number;
+    manualTime?: {
+        year: number;
+        month: number;
+        day: number;
+        hour: number;
+        minute: number;
+        second: number;
     };
 }
 
@@ -10204,6 +11099,9 @@ export declare function testChannelStreams(params: {
     logger?: Logger;
 }): Promise<Record<string, unknown>>;
 
+/** 24h (0) or 12h (1) clock format. */
+export declare type TimeFormat = 0 | 1;
+
 /**
  * Timelapse configuration.
  */
@@ -10224,6 +11122,27 @@ export declare interface TwoWayAudioConfig {
     mode?: "mixAudioStream" | string;
 }
 
+/**
+ * Optional listener invoked whenever the codec encounters a 4-byte sequence
+ * at the buffer head that does NOT match any known BcMedia magic and is about
+ * to be skipped as "recovery". Use it to discover undocumented sub-packet
+ * shapes (e.g. AI overlay metadata) without altering the codec's behaviour.
+ */
+export declare type UnknownChunkListener = (info: {
+    magic: number;
+    /** Up to 256 bytes starting at the unknown chunk's first byte. */
+    preview: Buffer;
+    /** Number of bytes the codec is about to skip before resyncing. */
+    skipped: number;
+}) => void;
+
+/**
+ * Like {@link applyXmlTagPatch} but inserts the tag at the end of the block
+ * when it is not already present. Required for fields the camera omits on
+ * GET responses but expects on SET (e.g. `<encoderType>` on `setEnc`).
+ */
+export declare function upsertXmlTag(xml: string, tag: string, value: string | number | boolean | undefined): string;
+
 /**
  * Client information extracted from HTTP request headers.
  * Used to determine optimal video delivery format.
@@ -10470,13 +11389,13 @@ export declare function xmlEscape(text: string | undefined | null): string;
  */
 export declare function xmlIndicatesFloodlight(xml: string): boolean;
 
-declare type XmlJsonObject = {
+export declare type XmlJsonObject = {
     [key: string]: XmlJsonValue;
 };
 
-declare type XmlJsonPrimitive = string | number | boolean | null;
+export declare type XmlJsonPrimitive = string | number | boolean | null;
 
-declare type XmlJsonValue = XmlJsonPrimitive | XmlJsonObject | XmlJsonValue[];
+export declare type XmlJsonValue = XmlJsonPrimitive | XmlJsonObject | XmlJsonValue[];
 
 export declare function zipDirectory(params: {
     sourceDir: string;