@apocaliss92/nodelink-js 0.1.8 → 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.
  *
@@ -1549,8 +1627,16 @@ export declare class BaichuanWebRTCServer extends EventEmitter {
     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
@@ -2178,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;
 
 /**
@@ -3171,8 +3265,8 @@ export declare type DebugOptions = {
  * - 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"
+ * @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;
@@ -3190,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).
@@ -3802,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.
  *
@@ -4165,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;
@@ -4389,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.
@@ -4510,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.
@@ -5751,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;
@@ -6365,6 +6627,13 @@ export declare class ReolinkBaichuanApi {
          * 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>;
@@ -6408,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.
      *
@@ -8013,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> & {