@apocaliss92/nodelink-js 0.1.7 → 0.1.9

package/dist/index.d.ts

@@ -919,6 +919,84 @@ export declare type BaichuanHeader = {
     payloadOffset?: number;
 };
 
+export declare class BaichuanHlsServer extends EventEmitter {
+    private readonly api;
+    private readonly channel;
+    private readonly profile;
+    private readonly variant;
+    private readonly segmentDuration;
+    private readonly playlistSize;
+    private readonly ffmpegPath;
+    private readonly log;
+    private outputDir;
+    private createdTempDir;
+    private playlistPath;
+    private segmentPattern;
+    private state;
+    private codec;
+    private framesReceived;
+    private ffmpeg;
+    private nativeStream;
+    private pumpPromise;
+    private startedAt;
+    private lastError;
+    constructor(options: BaichuanHlsServerOptions);
+    /**
+     * Start HLS streaming
+     */
+    start(): Promise<void>;
+    /**
+     * Stop HLS streaming
+     */
+    stop(): Promise<void>;
+    /**
+     * Get current status
+     */
+    getStatus(): HlsServerStatus;
+    /**
+     * Get playlist file path
+     */
+    getPlaylistPath(): string | null;
+    /**
+     * Get output directory
+     */
+    getOutputDir(): string | null;
+    /**
+     * Check if playlist file exists
+     */
+    waitForPlaylist(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Read an HLS asset (playlist or segment)
+     */
+    readAsset(assetName: string): Promise<{
+        data: Buffer;
+        contentType: string;
+    } | null>;
+    private pumpNativeToFfmpeg;
+    private spawnFfmpeg;
+}
+
+export declare interface BaichuanHlsServerOptions {
+    /** API instance (required) */
+    api: ReolinkBaichuanApi;
+    /** Channel number (required) */
+    channel: number;
+    /** Stream profile (required) */
+    profile: StreamProfile;
+    /** Native-only: TrackMix tele/autotrack variants */
+    variant?: NativeVideoStreamVariant;
+    /** Output directory for HLS segments. If not provided, a temp directory will be created. */
+    outputDir?: string;
+    /** HLS segment duration in seconds (default: 2) */
+    segmentDuration?: number;
+    /** Number of segments to keep in playlist (default: 5) */
+    playlistSize?: number;
+    /** ffmpeg binary path (default: "ffmpeg") */
+    ffmpegPath?: string;
+    /** Logger callback */
+    logger?: (level: "debug" | "info" | "warn" | "error", message: string) => void;
+}
+
 /**
  * BaichuanHttpStreamServer - HTTP server that serves a Baichuan video stream as MPEG-TS.
  *
@@ -980,6 +1058,106 @@ export declare type BaichuanLedState = {
     lightState?: string;
 };
 
+/**
+ * BaichuanMjpegServer - MJPEG HTTP server for Baichuan video streams
+ *
+ * Events:
+ * - 'started': Server started
+ * - 'stopped': Server stopped
+ * - 'client-connected': Client connected
+ * - 'client-disconnected': Client disconnected
+ * - 'error': Error occurred
+ */
+export declare class BaichuanMjpegServer extends EventEmitter {
+    private readonly options;
+    private readonly clients;
+    private httpServer;
+    private transformer;
+    private nativeStream;
+    private streamPump;
+    private detectedCodec;
+    private started;
+    private clientIdCounter;
+    constructor(options: BaichuanMjpegServerOptions);
+    /**
+     * Start the MJPEG server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the MJPEG server
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle HTTP request
+     */
+    private handleRequest;
+    /**
+     * Handle new MJPEG client
+     */
+    private handleMjpegClient;
+    /**
+     * Start the native video stream and MJPEG transformer
+     */
+    private startStream;
+    /**
+     * Pump native stream and feed to transformer
+     */
+    private pumpStream;
+    /**
+     * Initialize MJPEG transformer once codec is detected
+     */
+    private initTransformer;
+    /**
+     * Broadcast JPEG frame to all connected clients
+     */
+    private broadcastFrame;
+    /**
+     * Stop the stream and transformer
+     */
+    private stopStream;
+    /**
+     * Get current number of connected clients
+     */
+    getClientCount(): number;
+    /**
+     * Get server status
+     */
+    getStatus(): {
+        running: boolean;
+        clients: number;
+        codec: string | null;
+        frames: number;
+    };
+    private log;
+}
+
+export declare interface BaichuanMjpegServerOptions {
+    /** API instance (required) */
+    api: ReolinkBaichuanApi;
+    /** Channel number (required) */
+    channel: number;
+    /** Stream profile (required) */
+    profile: StreamProfile;
+    /** Native-only: TrackMix tele/autotrack variants */
+    variant?: NativeVideoStreamVariant;
+    /** HTTP server port (default: 8080) */
+    port?: number;
+    /** HTTP server host (default: "0.0.0.0") */
+    host?: string;
+    /** URL path for MJPEG stream (default: "/mjpeg") */
+    path?: string;
+    /** JPEG quality (1-31, lower is better, default: 5) */
+    quality?: number;
+    /** Output width (optional) */
+    width?: number;
+    /** Output height (optional) */
+    height?: number;
+    /** Max FPS (optional) */
+    maxFps?: number;
+    /** Logger callback */
+    logger?: (level: "debug" | "info" | "warn" | "error", message: string) => void;
+}
+
 export declare type BaichuanNetInfoPush = {
     netType?: string;
     signal?: number;
@@ -1376,6 +1554,133 @@ export declare interface BaichuanVideoStreamOptions {
     acceptAnyStreamType?: boolean;
 }
 
+/**
+ * BaichuanWebRTCServer - WebRTC server for Baichuan video streams
+ *
+ * Events:
+ * - 'session-created': New session created
+ * - 'session-connected': Session connected (ICE complete)
+ * - 'session-closed': Session closed
+ * - 'intercom-started': Intercom started for session
+ * - 'intercom-stopped': Intercom stopped for session
+ * - 'error': Error occurred
+ */
+export declare class BaichuanWebRTCServer extends EventEmitter {
+    private readonly options;
+    private readonly sessions;
+    private sessionIdCounter;
+    private weriftModule;
+    constructor(options: BaichuanWebRTCServerOptions);
+    /**
+     * Initialize werift module (lazy load to avoid requiring it if not used)
+     */
+    private loadWerift;
+    /**
+     * Create a new WebRTC session
+     * Returns a session ID and SDP offer to send to the browser
+     */
+    createSession(): Promise<{
+        sessionId: string;
+        offer: WebRTCOffer;
+    }>;
+    /**
+     * Handle WebRTC answer from browser and start streaming
+     */
+    handleAnswer(sessionId: string, answer: WebRTCAnswer): Promise<void>;
+    /**
+     * Add ICE candidate from browser
+     */
+    addIceCandidate(sessionId: string, candidate: WebRTCIceCandidate): Promise<void>;
+    /**
+     * Close a WebRTC session
+     */
+    closeSession(sessionId: string): Promise<void>;
+    /**
+     * Get information about all active sessions
+     */
+    getSessions(): WebRTCSessionInfo[];
+    /**
+     * Get information about a specific session
+     */
+    getSession(sessionId: string): WebRTCSessionInfo | null;
+    /**
+     * Close all sessions and stop the server
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the number of active sessions
+     */
+    get sessionCount(): number;
+    /**
+     * Wait for ICE gathering to complete
+     */
+    private waitForIceGathering;
+    /**
+     * Start native Baichuan stream and pump frames to WebRTC
+     */
+    private startNativeStream;
+    /**
+     * Pump frames from native stream to WebRTC tracks
+     * H.264 → RTP media track (standard WebRTC)
+     * H.265 → DataChannel with raw Annex-B frames (decoded by WebCodecs in browser)
+     */
+    private pumpFramesToWebRTC;
+    /**
+     * Send H.264 frame via RTP media track
+     * Returns the number of RTP packets sent
+     */
+    private sendH264Frame;
+    /**
+     * Send video frame via DataChannel (works for both H.264 and H.265)
+     * Format: 12-byte header + Annex-B data
+     * Header: [frameNum (4)] [timestamp (4)] [flags (1)] [keyframe (1)] [reserved (2)]
+     * Flags: 0x01 = H.265, 0x02 = H.264
+     */
+    private sendVideoFrameViaDataChannel;
+    /**
+     * Send H.265 frame via DataChannel
+     * Format: 12-byte header + Annex-B data
+     * Header: [frameNum (4)] [timestamp (4)] [flags (1)] [keyframe (1)] [reserved (2)]
+     */
+    private sendH265Frame;
+    /**
+     * Create RTP packets for H.264 NAL unit
+     * Handles single NAL, STAP-A aggregation, and FU-A fragmentation
+     */
+    private createH264RtpPackets;
+    /**
+     * Start intercom (two-way audio)
+     */
+    private startIntercom;
+    /**
+     * Log helper
+     */
+    private log;
+}
+
+export declare interface BaichuanWebRTCServerOptions {
+    /** API instance (required) */
+    api: ReolinkBaichuanApi;
+    /** Channel number (required) */
+    channel: number;
+    /** Stream profile (required) */
+    profile: StreamProfile;
+    /** Native-only: TrackMix tele/autotrack variants */
+    variant?: NativeVideoStreamVariant;
+    /** Enable two-way audio intercom (default: false) */
+    enableIntercom?: boolean;
+    /** STUN servers for ICE (default: Google STUN) */
+    stunServers?: string[];
+    /** TURN servers for NAT traversal (optional) */
+    turnServers?: Array<{
+        urls: string;
+        username?: string;
+        credential?: string;
+    }>;
+    /** Logger callback */
+    logger?: (level: "debug" | "info" | "warn" | "error", message: string) => void;
+}
+
 export declare type BaichuanWifi = {
     protocol?: number;
     mode?: string;
@@ -1959,6 +2264,14 @@ export declare function buildChannelExtensionXml(channelId: number | string | un
  */
 export declare function buildFloodlightManualXml(channelId: number, status: number, durationSeconds?: number): string;
 
+/**
+ * Build the HLS redirect URL from the original request URL.
+ *
+ * @param originalUrl - The original request URL
+ * @returns The URL with ?hls=playlist.m3u8 appended
+ */
+export declare function buildHlsRedirectUrl(originalUrl: string): string;
+
 export declare function buildLoginXml(userNameHash: string, passwordHash: string): string;
 
 /**
@@ -2791,6 +3104,25 @@ export declare function createLogger(options?: {
     tag?: string;
 }): Logger_2;
 
+/**
+ * Create an MJPEG HTTP response handler
+ *
+ * Usage:
+ * ```ts
+ * const transformer = new MjpegTransformer({ codec: "h264" });
+ * transformer.start();
+ *
+ * // In your stream handler:
+ * stream.on("accessUnit", (au) => transformer.push(au.data, au.timestamp));
+ *
+ * // HTTP handler:
+ * app.get("/mjpeg", (req, res) => {
+ *   serveMjpeg(res, transformer);
+ * });
+ * ```
+ */
+export declare function createMjpegBoundary(): string;
+
 /**
  * Stream frame data for rebroadcast.
  * Similar to Wyze forkAndStream() implementation.
@@ -2923,6 +3255,22 @@ export declare type DebugOptions = {
     };
 };
 
+/**
+ * Determine if H.265 should be transcoded to H.264 based on client capabilities.
+ *
+ * Decision logic:
+ * - iOS devices (Safari): Need transcoding (no native H.265 in <video> without HLS)
+ * - macOS Safari: Supports H.265 natively
+ * - Chrome/Edge: Limited H.265 support, safer to transcode
+ * - Firefox: No H.265 support, needs transcoding
+ * - Android: Variable support, transcode for safety
+ *
+ * @param headers - HTTP request headers
+ * @param forceMode - Optional override: "passthrough" or "transcode-h264"
+ * @returns Decision with mode, reason, and client info
+ */
+export declare function decideVideoclipTranscodeMode(headers: Record<string, string | string[] | undefined>, forceMode?: VideoclipTranscodeMode): VideoclipModeDecision;
+
 export declare function decodeHeader(buf: AnyBuffer): {
     header: BaichuanHeader;
     headerLen: number;
@@ -2936,6 +3284,18 @@ export declare function decodeHeader(buf: AnyBuffer): {
  */
 export declare function deriveAesKey(nonce: string, password: string): Buffer;
 
+/**
+ * Detect if the request is from an iOS device that needs HLS.
+ *
+ * @param userAgent - The User-Agent header from the request
+ * @returns Object with iOS detection results
+ */
+export declare function detectIosClient(userAgent: string | undefined): {
+    isIos: boolean;
+    isIosInstalledApp: boolean;
+    needsHls: boolean;
+};
+
 /**
  * Detect the actual video codec from raw NAL data.
  * Some cameras report wrong codec (e.g. "H264" but send H.265 data).
@@ -3350,6 +3710,8 @@ declare interface FloodlightTaskState {
     detectType?: string;
 }
 
+export declare function formatMjpegFrame(frame: Buffer, boundary: string): Buffer;
+
 /**
  * FTP task configuration.
  */
@@ -3378,6 +3740,8 @@ export declare function getGlobalLogger(): Logger_2;
  */
 export declare function getH265NalType(nalPayload: Buffer): number | null;
 
+export declare function getMjpegContentType(boundary: string): string;
+
 /**
  * Result of getRecordingVideo() - a fully muxed MP4 with stats.
  */
@@ -3416,6 +3780,11 @@ export declare interface GetRecordingVideoStats {
     hasAudio: boolean;
 }
 
+/**
+ * Extract client info from HTTP request headers.
+ */
+export declare function getVideoclipClientInfo(headers: Record<string, string | string[] | undefined>): VideoclipClientInfo;
+
 /**
  * Parameters for getVideoclips() recording search.
  */
@@ -3539,6 +3908,145 @@ export declare interface HddInfoListConfig {
     };
 }
 
+export declare type HlsCodec = "h264" | "h265";
+
+/**
+ * HTTP response result.
+ */
+export declare interface HlsHttpResponse {
+    /** HTTP status code */
+    statusCode: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Response body (string for playlist, Buffer for segment) */
+    body: string | Buffer;
+}
+
+export declare interface HlsServerStatus {
+    state: "idle" | "starting" | "running" | "stopping" | "stopped" | "error";
+    codec: HlsCodec | null;
+    framesReceived: number;
+    ffmpegRunning: boolean;
+    playlistPath: string | null;
+    outputDir: string | null;
+    startedAt: Date | null;
+    error: string | null;
+}
+
+/**
+ * HLS session returned by createRecordingReplayHlsSession.
+ */
+export declare interface HlsSession {
+    /** Get the current HLS playlist content (.m3u8) */
+    getPlaylist: () => string;
+    /** Get a segment file by name */
+    getSegment: (name: string) => Buffer | undefined;
+    /** List all available segment names */
+    listSegments: () => string[];
+    /** Wait for the HLS session to be ready */
+    waitForReady: () => Promise<void>;
+    /** Stop the HLS session and cleanup */
+    stop: () => Promise<void>;
+    /** Path to the temporary directory */
+    tempDir: string;
+}
+
+/**
+ * Manages HLS sessions with caching, TTL, and HTTP response generation.
+ */
+export declare class HlsSessionManager {
+    private readonly api;
+    private sessions;
+    private readonly logger;
+    private readonly sessionTtlMs;
+    private cleanupTimer;
+    private creationLocks;
+    constructor(api: ReolinkBaichuanApi, options?: HlsSessionManagerOptions);
+    /**
+     * Handle an HLS request and return the HTTP response.
+     *
+     * @param params - Request parameters
+     * @returns HTTP response ready to be sent
+     */
+    handleRequest(params: {
+        /** Unique session key (e.g., `${deviceId}:${fileId}`) */
+        sessionKey: string;
+        /** HLS path: "playlist.m3u8" or segment name like "segment_001.ts" */
+        hlsPath: string;
+        /** Full request URL for rewriting playlist URLs */
+        requestUrl: string;
+        /** Function to create session params if session doesn't exist */
+        createSession: () => Promise<HlsSessionParams> | HlsSessionParams;
+        /**
+         * Optional prefix used to ensure only one active HLS session per logical client.
+         * When a new session is created, any other sessions whose keys start with this
+         * prefix will be stopped. This prevents replay/ffmpeg queue starvation when
+         * clients quickly switch clips.
+         */
+        exclusiveKeyPrefix?: string;
+    }): Promise<HlsHttpResponse>;
+    private withCreationLock;
+    /**
+     * Check if a session exists for the given key.
+     */
+    hasSession(sessionKey: string): boolean;
+    /**
+     * Stop a specific session.
+     */
+    stopSession(sessionKey: string): Promise<void>;
+    /**
+     * Stop all sessions and cleanup.
+     */
+    stopAll(): Promise<void>;
+    /**
+     * Get the number of active sessions.
+     */
+    get sessionCount(): number;
+    /**
+     * Serve the HLS playlist with rewritten segment URLs.
+     */
+    private servePlaylist;
+    /**
+     * Serve an HLS segment.
+     */
+    private serveSegment;
+    /**
+     * Cleanup expired sessions.
+     */
+    private cleanupExpiredSessions;
+    private stopOtherSessionsWithPrefix;
+}
+
+/**
+ * Options for HlsSessionManager constructor.
+ */
+export declare interface HlsSessionManagerOptions {
+    /** Logger instance */
+    logger?: Logger_2;
+    /** Session TTL in milliseconds (default: 5 minutes) */
+    sessionTtlMs?: number;
+    /** Cleanup interval in milliseconds (default: 30 seconds) */
+    cleanupIntervalMs?: number;
+}
+
+/**
+ * Parameters for creating a new HLS session.
+ */
+export declare interface HlsSessionParams {
+    /** Channel number */
+    channel: number;
+    /** Recording file name/path */
+    fileName: string;
+    /** Whether this is an NVR recording */
+    isNvr?: boolean;
+    /** External device ID for dedicated socket */
+    deviceId?: string;
+    /** Transcode H.265 to H.264 */
+    transcodeH265ToH264?: boolean;
+    /** HLS segment duration in seconds */
+    hlsSegmentDuration?: number;
+}
+
 /**
  * Intercom - Two-way audio support for Reolink cameras via Baichuan protocol.
  *
@@ -3651,6 +4159,9 @@ declare interface Logger_2 {
     child?(tag: string): Logger_2;
 }
 
+/** Logger callback type for MjpegTransformer */
+export declare type LoggerCallback = (level: "debug" | "info" | "warn" | "error", message: string) => void;
+
 declare type LoggerLike = Partial<Logger_2> | Console;
 
 export declare type LoginResponseValue = {
@@ -3696,6 +4207,74 @@ export declare interface MediaStream {
     };
 }
 
+export declare interface MjpegFrame {
+    /** JPEG data */
+    data: Buffer;
+    /** Timestamp in microseconds */
+    timestamp: number;
+}
+
+/**
+ * MjpegTransformer - Transforms H.264/H.265 access units to JPEG frames
+ *
+ * Events:
+ * - 'frame': Emitted when a JPEG frame is ready (MjpegFrame)
+ * - 'error': Emitted on error
+ * - 'close': Emitted when transformer is closed
+ */
+export declare class MjpegTransformer extends EventEmitter {
+    private readonly options;
+    private ffmpeg;
+    private started;
+    private closed;
+    private jpegBuffer;
+    private frameCount;
+    private lastTimestamp;
+    constructor(options: MjpegTransformerOptions);
+    /**
+     * Start the transformer (spawns FFmpeg process)
+     */
+    start(): void;
+    /**
+     * Push an H.264/H.265 access unit (Annex-B format with start codes)
+     */
+    push(accessUnit: Buffer, timestamp?: number): void;
+    /**
+     * Handle JPEG data from FFmpeg stdout
+     * FFmpeg outputs complete JPEG images, each starting with SOI (0xFFD8)
+     * and ending with EOI (0xFFD9)
+     */
+    private handleJpegData;
+    /**
+     * Stop the transformer
+     */
+    stop(): Promise<void>;
+    /**
+     * Get frame count
+     */
+    getFrameCount(): number;
+    /**
+     * Check if running
+     */
+    isRunning(): boolean;
+    private log;
+}
+
+export declare interface MjpegTransformerOptions {
+    /** Video codec (required) */
+    codec: "h264" | "h265";
+    /** JPEG quality (1-31, lower is better, default: 5) */
+    quality?: number | undefined;
+    /** Output width (optional, maintains aspect ratio if only one dimension set) */
+    width?: number | undefined;
+    /** Output height (optional, maintains aspect ratio if only one dimension set) */
+    height?: number | undefined;
+    /** Frame rate limit (optional, e.g., 10 for max 10 fps) */
+    maxFps?: number | undefined;
+    /** Logger callback */
+    logger?: LoggerCallback | undefined;
+}
+
 /**
  * Motion alarm configuration (getMotionAlarm response).
  * cmdId=46 (GetMdAlarm)
@@ -3831,6 +4410,8 @@ export declare interface ParsedRecordingFileName {
     durationMs: number;
     /** Frame rate extracted from filename hex flags (if available) */
     framerate?: number;
+    /** File size in bytes extracted from filename (last hex field before extension) */
+    sizeBytes?: number;
     flags?: RecordingVodFlags;
     rawFlags?: Record<string, number>;
     animalTypeRaw?: string;
@@ -4055,6 +4636,8 @@ export declare class ReolinkBaichuanApi {
      * Value: client, refCount, createdAt
      */
     private readonly dedicatedClients;
+    /** Keep replay dedicated sockets warm briefly to reduce clip switch latency. */
+    private static readonly REPLAY_DEDICATED_KEEPALIVE_MS;
     /**
      * Get a summary of currently active dedicated sessions.
      * Useful for debugging/logging to see how many sockets are open.
@@ -4176,6 +4759,17 @@ export declare class ReolinkBaichuanApi {
      * This ensures clean teardown at the end of each clip.
      */
     private releaseDedicatedClient;
+    /**
+     * Force-close a dedicated client if it exists.
+     * This is called BEFORE entering the queue to immediately terminate any existing stream
+     * for the same sessionKey. The existing stream will receive an error, release its queue slot,
+     * and the new request can then proceed.
+     *
+     * @param sessionKey - The session key to force-close (e.g., `replay:${deviceId}`)
+     * @param logger - Optional logger
+     * @returns true if a client was closed, false if no client existed
+     */
+    private forceCloseDedicatedClient;
     /**
      * Create a dedicated Baichuan client session for streaming.
      * This is useful for consumers that need isolated socket connections per stream.
@@ -5417,11 +6011,13 @@ export declare class ReolinkBaichuanApi {
      * @param settings - Floodlight settings to apply
      *
      * @example
+     * ```typescript
      * await api.setFloodlightSettings(0, {
      *   duration: 300, // 5 minutes
      *   detectType: 'people,vehicle',
      *   brightness: 80,
      * });
+     * ```
      */
     setFloodlightSettings(channel: number | undefined, settings: {
         duration?: number;
@@ -6024,6 +6620,20 @@ export declare class ReolinkBaichuanApi {
          * Recommended: pass a unique identifier per logical device/player instance.
          */
         deviceId?: string;
+        /**
+         * Transcode H.265/HEVC to H.264/AVC for compatibility with clients that don't support H.265.
+         * When true and the source is H.265, ffmpeg will transcode to H.264 using libx264.
+         * This increases CPU usage but ensures playback on iOS Safari, older browsers, etc.
+         * Default: false (passthrough/copy).
+         */
+        transcodeH265ToH264?: boolean;
+        /**
+         * Use MPEG-TS muxer to preserve frame timestamps (PTS).
+         * When true, frames are muxed into MPEG-TS before being passed to ffmpeg.
+         * This can help with variable framerate streams but may cause issues with some decoders.
+         * Default: true (MPEG-TS muxing for proper timestamp alignment).
+         */
+        useMpegTsMuxer?: boolean;
     }): Promise<{
         mp4: Readable;
         stop: () => Promise<void>;
@@ -6067,6 +6677,98 @@ export declare class ReolinkBaichuanApi {
         mp4: Readable;
         stop: () => Promise<void>;
     }>;
+    /**
+     * Create an HLS (HTTP Live Streaming) session for a recording.
+     *
+     * This method creates HLS segments on-the-fly from a recording replay stream.
+     * HLS is required for iOS devices (Safari, Home app) which don't support
+     * fragmented MP4 streaming well and require Range request support.
+     *
+     * The session writes HLS segments (.ts files) and playlist (.m3u8) to a
+     * temporary directory. You must serve these files via HTTP to the client.
+     *
+     * @example
+     * ```ts
+     * const session = await api.createRecordingReplayHlsSession({
+     *   channel: 0,
+     *   fileName: "/mnt/sda/Mp4Record/2026-01-25/RecS03.mp4",
+     * });
+     *
+     * // Serve playlist
+     * app.get('/clip.m3u8', (req, res) => {
+     *   res.type('application/vnd.apple.mpegurl');
+     *   res.send(session.getPlaylist());
+     * });
+     *
+     * // Serve segments
+     * app.get('/segment/:name', (req, res) => {
+     *   const data = session.getSegment(req.params.name);
+     *   if (data) {
+     *     res.type('video/mp2t');
+     *     res.send(data);
+     *   } else {
+     *     res.status(404).end();
+     *   }
+     * });
+     *
+     * // Cleanup when done
+     * await session.stop();
+     * ```
+     */
+    createRecordingReplayHlsSession(params: {
+        /** Channel number (0-based). Required. */
+        channel: number;
+        /** Full path to the recording file. Required. */
+        fileName: string;
+        /**
+         * Force NVR mode (uses id-based XML with UID) or standalone mode (name-based XML).
+         * If not specified, the library will detect based on device channel count.
+         */
+        isNvr?: boolean;
+        /** Optional logger override. If not provided, uses the API's logger. */
+        logger?: Logger;
+        /**
+         * External identifier for the dedicated socket session.
+         * When provided, a dedicated BaichuanClient is created/reused for this deviceId.
+         */
+        deviceId?: string;
+        /**
+         * Transcode H.265/HEVC to H.264/AVC for compatibility.
+         * Default: false (passthrough).
+         */
+        transcodeH265ToH264?: boolean;
+        /**
+         * HLS segment duration in seconds. Default: 4.
+         */
+        hlsSegmentDuration?: number;
+    }): Promise<{
+        /**
+         * Get the current HLS playlist content (.m3u8).
+         * Call this to serve the playlist to the client.
+         */
+        getPlaylist: () => string;
+        /**
+         * Get a segment file by name.
+         * Returns undefined if the segment doesn't exist yet.
+         */
+        getSegment: (name: string) => Buffer | undefined;
+        /**
+         * List all available segment names.
+         */
+        listSegments: () => string[];
+        /**
+         * Wait for the HLS session to be ready (at least one segment available).
+         */
+        waitForReady: () => Promise<void>;
+        /**
+         * Stop the HLS session and cleanup.
+         */
+        stop: () => Promise<void>;
+        /**
+         * Path to the temporary directory containing HLS files.
+         */
+        tempDir: string;
+    }>;
     /**
      * List recordings from a standalone camera.
      *
@@ -7547,6 +8249,28 @@ export declare interface TwoWayAudioConfig {
     mode?: "mixAudioStream" | string;
 }
 
+/**
+ * Client information extracted from HTTP request headers.
+ * Used to determine optimal video delivery format.
+ */
+export declare type VideoclipClientInfo = {
+    userAgent: string | undefined;
+    accept: string | undefined;
+    range: string | undefined;
+    secChUa: string | undefined;
+    secChUaMobile: string | undefined;
+    secChUaPlatform: string | undefined;
+};
+
+/**
+ * Result of videoclip mode decision.
+ */
+export declare type VideoclipModeDecision = {
+    mode: VideoclipTranscodeMode;
+    reason: string;
+    clientInfo: VideoclipClientInfo;
+};
+
 export declare type VideoclipThumbnailResult = {
     /** Raw I-frame data (H.264 or H.265) */
     frame: Buffer;
@@ -7560,6 +8284,13 @@ export declare type VideoclipThumbnailResult = {
     streamInfo: PlaybackSnapshotStreamInfo;
 };
 
+/**
+ * Videoclip delivery mode.
+ * - `passthrough`: Copy codec as-is (H.264 or H.265)
+ * - `transcode-h264`: Transcode H.265 to H.264 for compatibility
+ */
+export declare type VideoclipTranscodeMode = "passthrough" | "transcode-h264";
+
 export declare type VideoCodec = "H.264" | "H.265" | "MJPEG" | "MPEG4" | string;
 
 /**
@@ -7643,7 +8374,8 @@ export declare type VodFile = {
         sec: number;
     };
     name: string;
-    size: number;
+    /** File size in bytes - API may return as string or number */
+    size: number | string;
 };
 
 export declare type VodSearchResponse = ReolinkCmdResponseExt<VodSearchResult> & {
@@ -7684,6 +8416,34 @@ export declare type WakeUpOptions = {
     reconnect?: boolean;
 };
 
+export declare interface WebRTCAnswer {
+    sdp: string;
+    type: "answer";
+}
+
+export declare interface WebRTCIceCandidate {
+    candidate: string;
+    sdpMid?: string;
+    sdpMLineIndex?: number;
+}
+
+export declare interface WebRTCOffer {
+    sdp: string;
+    type: "offer";
+}
+
+export declare interface WebRTCSessionInfo {
+    id: string;
+    state: "connecting" | "connected" | "disconnected" | "failed";
+    createdAt: Date;
+    stats: {
+        videoFrames: number;
+        audioFrames: number;
+        bytesSent: number;
+        intercomBytesSent: number;
+    };
+}
+
 /**
  * White LED state configuration.
  */