@apocaliss92/nodelink-js 0.1.8 → 0.1.9

package/dist/cli/rtsp-server.cjs

@@ -1884,13 +1884,31 @@ var init_BaichuanVideoStream = __esm({
               searchStart = bodyEnd + Buffer.from("</body>").length;
             dataToParse = rawCandidate.subarray(searchStart);
           }
+          let encryptLen;
+          if (frame.extension && frame.extension.length > 0) {
+            try {
+              const extDec = this.client.tryDecryptXml(
+                frame.extension,
+                frame.header.channelId,
+                enc
+              );
+              const encryptLenMatch = extDec.match(
+                /<encryptLen>(\d+)<\/encryptLen>/i
+              );
+              if (encryptLenMatch && encryptLenMatch[1]) {
+                encryptLen = parseInt(encryptLenMatch[1], 10);
+              }
+            } catch {
+            }
+          }
           const dataAfterXml = this.chooseDecryptedOrRawCandidate({
             raw: dataToParse,
             enc,
             channelId: frame.header.channelId,
             // Some NVR/Hub streams appear to include non-media bytes even when payloadOffset is present.
             // Allow a one-time resync at startup to avoid delaying the first keyframe.
-            allowResync: frame.payload.length === 0 || totalFramesReceived <= 10 && totalMediaPackets === 0
+            allowResync: frame.payload.length === 0 || totalFramesReceived <= 10 && totalMediaPackets === 0,
+            ...encryptLen !== void 0 ? { encryptLen } : {}
           });
           if (this.bcMediaCodec.getRemainingBuffer().length === 0 && dataAfterXml.length <= 600) {
             const s = _BaichuanVideoStream.scoreBcMediaLike(dataAfterXml);
@@ -2003,15 +2021,38 @@ var init_BaichuanVideoStream = __esm({
                 }
               }
             };
-            const prependParamSetsIfNeeded = (annexB, videoType) => {
+            const prependParamSetsIfNeeded = (annexB, videoType, isPframe = false) => {
               if (videoType === "H264") {
                 const nals = splitAnnexBToNalPayloads(annexB);
                 if (nals.length === 0) return annexB;
                 const types = nals.map((n) => (n[0] ?? 0) & 31);
-                if (types.includes(7) && types.includes(8)) return annexB;
                 const hasVcl = types.some(
                   (t) => t === 1 || t === 5 || t === 19 || t === 20
                 );
+                if (isPframe && !hasVcl) {
+                  if (dbg.traceNativeStream) {
+                    this.logger?.warn(
+                      `[BaichuanVideoStream] Dropping P-frame without VCL (only param sets): types=${types.join(",")}`
+                    );
+                  }
+                  return Buffer.alloc(0);
+                }
+                if (types.includes(7) && types.includes(8)) {
+                  let ppsIdFromSlice = null;
+                  for (const nal of nals) {
+                    const t = (nal[0] ?? 0) & 31;
+                    if (t === 1 || t === 5) {
+                      ppsIdFromSlice = parseSlicePpsIdFromNal(nal);
+                      break;
+                    }
+                  }
+                  if (ppsIdFromSlice != null && ppsIdFromSlice <= 255) {
+                    this.lastPrependedPpsId = ppsIdFromSlice;
+                  } else {
+                    this.lastPrependedPpsId = -1;
+                  }
+                  return annexB;
+                }
                 if (!hasVcl) return annexB;
                 let ppsId = null;
                 for (const nal of nals) {
@@ -2058,11 +2099,19 @@ var init_BaichuanVideoStream = __esm({
                 const nals = splitAnnexBToNalPayloads2(annexB);
                 if (nals.length === 0) return annexB;
                 const types = nals.map((n) => getH265NalType(n)).filter((t) => t !== null);
-                if (types.includes(32) && types.includes(33) && types.includes(34))
-                  return annexB;
                 const hasVcl = types.some(
                   (t) => t >= 0 && t <= 9 || t >= 16 && t <= 23
                 );
+                if (isPframe && !hasVcl) {
+                  if (dbg.traceNativeStream) {
+                    this.logger?.warn(
+                      `[BaichuanVideoStream] Dropping H.265 P-frame without VCL (only param sets): types=${types.join(",")}`
+                    );
+                  }
+                  return Buffer.alloc(0);
+                }
+                if (types.includes(32) && types.includes(33) && types.includes(34))
+                  return annexB;
                 if (!hasVcl) return annexB;
                 if (this.lastPrependedParamSetsH265) return annexB;
                 if (!this.lastVps || !this.lastSpsH265 || !this.lastPpsH265)
@@ -2244,7 +2293,7 @@ var init_BaichuanVideoStream = __esm({
               }
               for (const p of parts) {
                 maybeCacheParamSets(p, "Pframe", videoType);
-                const outP0 = prependParamSetsIfNeeded(p, videoType);
+                const outP0 = prependParamSetsIfNeeded(p, videoType, true);
                 if (outP0.length === 0) continue;
                 const outP = outP0;
                 dumpNalSummary(outP, "Pframe", media.microseconds);
@@ -2726,17 +2775,20 @@ function parseRecordingFileName(fileName) {
   let widthRaw;
   let heightRaw;
   let hexValue = "";
+  let sizeHex;
   if (parts.length === 6) {
     startDate = parts[1] ?? "";
     startTime = parts[2] ?? "";
     endTime = parts[3] ?? "";
     hexValue = parts[4] ?? "";
+    sizeHex = parts[5];
   } else if (parts.length === 7) {
     startDate = parts[1] ?? "";
     startTime = parts[2] ?? "";
     endTime = parts[3] ?? "";
     animalTypeRaw = parts[4];
     hexValue = parts[5] ?? "";
+    sizeHex = parts[6];
   } else if (parts.length === 9) {
     devType = "hub";
     startDate = parts[1] ?? "";
@@ -2746,6 +2798,7 @@ function parseRecordingFileName(fileName) {
     widthRaw = parts[5];
     heightRaw = parts[6];
     hexValue = parts[7] ?? "";
+    sizeHex = parts[8];
   } else {
     return void 0;
   }
@@ -2776,6 +2829,12 @@ function parseRecordingFileName(fileName) {
   if (animalTypeRaw != null) parsed.animalTypeRaw = animalTypeRaw;
   if (widthRaw != null) parsed.widthRaw = widthRaw;
   if (heightRaw != null) parsed.heightRaw = heightRaw;
+  if (sizeHex && /^[0-9a-fA-F]+$/.test(sizeHex)) {
+    const sizeBytes = parseInt(sizeHex, 16);
+    if (Number.isFinite(sizeBytes) && sizeBytes > 0) {
+      parsed.sizeBytes = sizeBytes;
+    }
+  }
   return parsed;
 }
 var FLAGS_CAM_V2, FLAGS_HUB_V0, FLAGS_HUB_V1, FLAGS_HUB_V2, FLAGS_MAPPING;
@@ -4735,15 +4794,18 @@ var init_ReolinkCgiApi = __esm({
         if (detectionClasses.length === 0) {
           detectionClasses.push("motion");
         }
+        const sizeBytes = typeof vodFile.size === "string" ? parseInt(vodFile.size, 10) : vodFile.size;
         const result = {
           fileName: vodFile.name,
           id: vodFile.name,
-          sizeBytes: vodFile.size,
           startTime,
           endTime,
           recordType: vodFile.type,
           detectionClasses
         };
+        if (Number.isFinite(sizeBytes)) {
+          result.sizeBytes = sizeBytes;
+        }
         if (parsed) {
           result.parsedFileName = parsed;
         }
@@ -4959,7 +5021,7 @@ async function createDiagnosticsBundle(params) {
 }
 function sanitizeFfmpegError(error) {
   return error.replace(
-    /([a-z]+:\/\/)([^:@\/\s]+):([^@\/\s]+)@/gi,
+    /([a-z]+:\/\/)([^:@/\s]+):([^@/\s]+)@/gi,
     (match, protocol, username, password) => {
       return `${protocol}***:***@`;
     }
@@ -14508,10 +14570,15 @@ var parseRecordingFilesFromXml = (xml) => {
     if (startDt) item.startTime = startDt;
     if (endDt) item.endTime = endDt;
     const parsed = parseRecordingFileName(item.name ?? item.fileName);
-    if (parsed) {
-      item.parsedFileName = parsed;
-      if (!item.startTime) item.startTime = parsed.start;
-      if (!item.endTime) item.endTime = parsed.end;
+    const parsedFromPath = item.fileName !== item.name ? parseRecordingFileName(item.fileName) : void 0;
+    const bestParsed = parsedFromPath?.sizeBytes != null ? parsedFromPath : parsed;
+    if (bestParsed) {
+      item.parsedFileName = bestParsed;
+      if (!item.startTime) item.startTime = bestParsed.start;
+      if (!item.endTime) item.endTime = bestParsed.end;
+      if (item.sizeBytes == null && bestParsed.sizeBytes != null) {
+        item.sizeBytes = bestParsed.sizeBytes;
+      }
     }
     item.detectionClasses = buildDetectionClasses(parsed, item.recordType);
     out.push(item);
@@ -14538,6 +14605,9 @@ var parseRecordingFilesFromXml = (xml) => {
       item.parsedFileName = parsed;
       if (!item.startTime) item.startTime = parsed.start;
       if (!item.endTime) item.endTime = parsed.end;
+      if (item.sizeBytes == null && parsed.sizeBytes != null) {
+        item.sizeBytes = parsed.sizeBytes;
+      }
     }
     item.detectionClasses = buildDetectionClasses(parsed, item.recordType);
     out.push(item);
@@ -15852,6 +15922,10 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
    * Value: client, refCount, createdAt
    */
   dedicatedClients = /* @__PURE__ */ new Map();
+  /** Keep replay dedicated sockets warm briefly to reduce clip switch latency. */
+  // Keep replay sockets warm briefly for fast clip switches, but tear down quickly
+  // when clients stop requesting HLS segments (avoids looking like a stuck session).
+  static REPLAY_DEDICATED_KEEPALIVE_MS = 1e4;
   /**
    * Get a summary of currently active dedicated sessions.
    * Useful for debugging/logging to see how many sockets are open.
@@ -15961,22 +16035,35 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
    * Process the replay queue - executes operations one at a time.
    */
   async processReplayQueue() {
-    if (this.replayQueueProcessing) return;
+    if (this.replayQueueProcessing) {
+      this.logger?.debug?.(
+        `[ReplayQueue] Already processing, queue length: ${this.replayQueue.length}`
+      );
+      return;
+    }
     this.replayQueueProcessing = true;
+    this.logger?.debug?.(
+      `[ReplayQueue] Starting queue processing, items: ${this.replayQueue.length}`
+    );
     while (this.replayQueue.length > 0) {
       const item = this.replayQueue.shift();
       if (item) {
         const timeSinceLastReplay = Date.now() - this.lastReplayEndTime;
         if (timeSinceLastReplay < this.REPLAY_COOLDOWN_MS) {
-          await new Promise(
-            (r) => setTimeout(r, this.REPLAY_COOLDOWN_MS - timeSinceLastReplay)
-          );
+          const waitTime = this.REPLAY_COOLDOWN_MS - timeSinceLastReplay;
+          this.logger?.debug?.(`[ReplayQueue] Waiting ${waitTime}ms cooldown`);
+          await new Promise((r) => setTimeout(r, waitTime));
         }
+        this.logger?.debug?.(
+          `[ReplayQueue] Executing item, remaining: ${this.replayQueue.length}`
+        );
         await item.execute();
         this.lastReplayEndTime = Date.now();
+        this.logger?.debug?.(`[ReplayQueue] Item completed`);
       }
     }
     this.replayQueueProcessing = false;
+    this.logger?.debug?.(`[ReplayQueue] Queue processing complete`);
   }
   /**
    * Enqueue a replay operation with optional de-duplication.
@@ -16039,14 +16126,35 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
     this.replayQueue.push({
       execute: () => {
         return new Promise((releaseSlot) => {
+          let released = false;
+          const safeRelease = () => {
+            if (released) return;
+            released = true;
+            releaseSlot();
+          };
+          const safetyTimeout = setTimeout(
+            () => {
+              if (!released) {
+                this.logger?.warn?.(
+                  "[ReplayQueue] Safety timeout: releasing queue slot after 10 minutes"
+                );
+                safeRelease();
+              }
+            },
+            10 * 60 * 1e3
+          );
           setup().then((result) => {
             resolvePromise({
               result,
-              release: () => releaseSlot()
+              release: () => {
+                clearTimeout(safetyTimeout);
+                safeRelease();
+              }
             });
           }).catch((e) => {
+            clearTimeout(safetyTimeout);
             rejectPromise(e);
-            releaseSlot();
+            safeRelease();
           });
         });
       }
@@ -16116,30 +16224,68 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
    * immediately and create a new one. This ensures clean state for each clip.
    */
   async acquireDedicatedClient(sessionKey, logger) {
+    const log = logger ?? this.logger;
+    const isReplayKey = sessionKey.startsWith("replay:");
     const existing = this.dedicatedClients.get(sessionKey);
     if (existing) {
-      logger?.debug?.(
-        `[DedicatedClient] Closing existing client for ${sessionKey} (new stream requested)`
+      if (existing.idleCloseTimer) {
+        clearTimeout(existing.idleCloseTimer);
+        existing.idleCloseTimer = void 0;
+      }
+      if (existing.refCount === 0) {
+        existing.refCount = 1;
+        existing.lastUsedAt = Date.now();
+        log?.debug?.(
+          `[DedicatedClient] Reusing existing dedicated socket for sessionKey=${sessionKey}`
+        );
+        try {
+          if (!existing.client.loggedIn) {
+            await existing.client.login();
+          }
+        } catch {
+        }
+        if (existing.client.loggedIn) {
+          return {
+            client: existing.client,
+            release: () => this.releaseDedicatedClient(sessionKey, logger)
+          };
+        }
+      }
+      log?.log?.(
+        `[DedicatedClient] Closing existing socket for sessionKey=${sessionKey} (preempting active session)`
       );
       this.dedicatedClients.delete(sessionKey);
-      existing.client.close({ reason: "new stream for same device" }).catch((e) => {
-        logger?.debug?.(`[DedicatedClient] Error closing old socket: ${e}`);
-      });
+      try {
+        await existing.client.close({ reason: "preempted by new session" });
+        log?.log?.(
+          `[DedicatedClient] Old socket closed successfully for sessionKey=${sessionKey}`
+        );
+      } catch (e) {
+        log?.warn?.(
+          `[DedicatedClient] Error closing old socket for sessionKey=${sessionKey}: ${e}`
+        );
+      }
     }
-    logger?.debug?.(`[DedicatedClient] Creating new client for ${sessionKey}`);
+    log?.log?.(
+      `[DedicatedClient] Opening new dedicated socket for sessionKey=${sessionKey}`
+    );
     const dedicatedClient = new BaichuanClient({
       host: this.host,
       username: this.username,
       password: this.password,
-      logger: logger ?? this.logger,
+      logger: log,
       debugOptions: this.client.getDebugConfig?.()
     });
     await dedicatedClient.login();
+    log?.log?.(
+      `[DedicatedClient] Dedicated socket logged in for sessionKey=${sessionKey}`
+    );
     this.dedicatedClients.set(sessionKey, {
       client: dedicatedClient,
       refCount: 1,
-      // Keep for compatibility, but not used for reuse logic
-      createdAt: Date.now()
+      createdAt: Date.now(),
+      lastUsedAt: Date.now(),
+      idleCloseTimer: void 0
     });
     return {
       client: dedicatedClient,
@@ -16151,16 +16297,82 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
    * This ensures clean teardown at the end of each clip.
    */
   async releaseDedicatedClient(sessionKey, logger) {
+    const log = logger ?? this.logger;
     const entry = this.dedicatedClients.get(sessionKey);
     if (!entry) return;
+    entry.refCount = Math.max(0, entry.refCount - 1);
+    entry.lastUsedAt = Date.now();
+    if (entry.refCount > 0) return;
+    const isReplayKey = sessionKey.startsWith("replay:");
+    const allowReplayKeepAlive = /^replay:[^:]+$/.test(sessionKey);
+    if (isReplayKey && allowReplayKeepAlive) {
+      if (entry.idleCloseTimer) return;
+      entry.idleCloseTimer = setTimeout(async () => {
+        const current = this.dedicatedClients.get(sessionKey);
+        if (!current) return;
+        if (current.refCount > 0) return;
+        this.dedicatedClients.delete(sessionKey);
+        log?.debug?.(
+          `[DedicatedClient] Closing idle replay socket for sessionKey=${sessionKey} (keepalive expired)`
+        );
+        try {
+          await current.client.close({
+            reason: "replay idle keepalive expired"
+          });
+        } catch {
+        }
+      }, _ReolinkBaichuanApi.REPLAY_DEDICATED_KEEPALIVE_MS);
+      return;
+    }
     this.dedicatedClients.delete(sessionKey);
-    logger?.debug?.(`[DedicatedClient] Releasing and closing ${sessionKey}`);
+    log?.log?.(
+      `[DedicatedClient] Closing socket for sessionKey=${sessionKey} (session ended)`
+    );
     try {
       await entry.client.close({ reason: "dedicated session ended" });
+      log?.log?.(
+        `[DedicatedClient] Socket closed successfully for sessionKey=${sessionKey}`
+      );
     } catch (e) {
-      logger?.debug?.(`[DedicatedClient] Error closing socket: ${e}`);
+      log?.warn?.(
+        `[DedicatedClient] Error closing socket for sessionKey=${sessionKey}: ${e}`
+      );
     }
   }
+  /**
+   * 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
+   */
+  async forceCloseDedicatedClient(sessionKey, logger) {
+    const log = logger ?? this.logger;
+    const entry = this.dedicatedClients.get(sessionKey);
+    if (!entry) return false;
+    if (entry.idleCloseTimer) {
+      clearTimeout(entry.idleCloseTimer);
+      entry.idleCloseTimer = void 0;
+    }
+    log?.log?.(
+      `[DedicatedClient] Force-closing existing socket for sessionKey=${sessionKey} (new request preempting)`
+    );
+    this.dedicatedClients.delete(sessionKey);
+    try {
+      await entry.client.close({ reason: "preempted by new request" });
+      log?.log?.(
+        `[DedicatedClient] Force-close complete for sessionKey=${sessionKey}`
+      );
+    } catch (e) {
+      log?.warn?.(
+        `[DedicatedClient] Error during force-close for sessionKey=${sessionKey}: ${e}`
+      );
+    }
+    return true;
+  }
   /**
    * Create a dedicated Baichuan client session for streaming.
    * This is useful for consumers that need isolated socket connections per stream.
@@ -16196,6 +16408,9 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
     await Promise.allSettled(
       entries.map(async ([key, entry]) => {
         try {
+          if (entry.idleCloseTimer) {
+            clearTimeout(entry.idleCloseTimer);
+          }
           this.logger?.debug?.(`[DedicatedClient] Cleanup: closing ${key}`);
           await entry.client.close({ reason: "API cleanup" });
         } catch {
@@ -18051,7 +18266,8 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
             channel,
             payloadXml: stopXml,
             messageClass: BC_CLASS_MODERN_24,
-            timeoutMs: 1e4,
+            timeoutMs: 2e3,
+            // Short timeout - if socket is closed, fail fast
             internal: true
           });
         } catch {
@@ -18187,7 +18403,8 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
             channel,
             payloadXml: stopXml,
             messageClass: BC_CLASS_MODERN_24,
-            timeoutMs: 1e4,
+            timeoutMs: 2e3,
+            // Short timeout - if socket is closed, fail fast
             internal: true
           });
         } catch {
@@ -19234,11 +19451,20 @@ ${stderr}`)
     }
   }
   async downloadRecording(params) {
+    this.logger?.debug?.(
+      `[downloadRecording] Queuing download for: ${params.fileName}, channel=${params.channel}`
+    );
     return this.enqueueReplayOperation(async () => {
+      this.logger?.debug?.(
+        `[downloadRecording] Starting download for: ${params.fileName}`
+      );
       await this.client.login();
       const channel = this.normalizeChannel(params.channel);
       const uid = await this.ensureUidForRecordings(channel, params.uid);
       const fileName = params.fileName;
+      this.logger?.debug?.(
+        `[downloadRecording] Trying fileInfoListReplayBinaryDownload for: ${fileName}`
+      );
       let replayErr;
       try {
         return await this.fileInfoListReplayBinaryDownload({
@@ -19249,7 +19475,13 @@ ${stderr}`)
         });
       } catch (e) {
         replayErr = e;
+        this.logger?.debug?.(
+          `[downloadRecording] fileInfoListReplayBinaryDownload failed: ${e instanceof Error ? e.message : String(e)}`
+        );
       }
+      this.logger?.debug?.(
+        `[downloadRecording] Trying fileInfoListDownload for: ${fileName}`
+      );
       let downloadErr;
       try {
         return await this.fileInfoListDownload({
@@ -19260,7 +19492,13 @@ ${stderr}`)
         });
       } catch (e) {
         downloadErr = e;
+        this.logger?.debug?.(
+          `[downloadRecording] fileInfoListDownload failed: ${e instanceof Error ? e.message : String(e)}`
+        );
       }
+      this.logger?.debug?.(
+        `[downloadRecording] Trying fileInfoListPagedDownload for: ${fileName}`
+      );
       try {
         const result = await this.fileInfoListPagedDownload({
           channel,
@@ -19272,6 +19510,9 @@ ${stderr}`)
           return result;
         }
       } catch (e) {
+        this.logger?.debug?.(
+          `[downloadRecording] fileInfoListPagedDownload failed: ${e instanceof Error ? e.message : String(e)}`
+        );
       }
       const replayMsg = replayErr instanceof Error ? replayErr.message : replayErr != null ? String(replayErr) : "";
       const dlMsg = downloadErr instanceof Error ? downloadErr.message : downloadErr != null ? String(downloadErr) : "";
@@ -21344,11 +21585,13 @@ ${stderr}`)
    * @param settings - Floodlight settings to apply
    *
    * @example
+   * ```typescript
    * await api.setFloodlightSettings(0, {
    *   duration: 300, // 5 minutes
    *   detectType: 'people,vehicle',
    *   brightness: 80,
    * });
+   * ```
    */
   async setFloodlightSettings(channel, settings) {
     const ch = this.normalizeChannel(channel);
@@ -23490,11 +23733,13 @@ ${scheduleItems}
    */
   async createRecordingReplayMp4Stream(params) {
     const logger = params.logger ?? this.logger;
+    const useMpegTsMuxer = params.useMpegTsMuxer ?? true;
     const parsed = parseRecordingFileName(params.fileName);
     const durationMs = parsed?.durationMs ?? 3e5;
+    const fps = parsed?.framerate && parsed.framerate > 0 ? parsed.framerate : 15;
     const seconds = Math.ceil(durationMs / 1e3 * 1.1);
     logger?.debug?.(
-      `[createRecordingReplayMp4Stream] Starting: channel=${params.channel}, fileName=${params.fileName}, durationMs=${durationMs}, timeoutSec=${seconds}, deviceId=${params.deviceId ?? "auto"}`
+      `[createRecordingReplayMp4Stream] Starting: channel=${params.channel}, fileName=${params.fileName}, durationMs=${durationMs}, fps=${fps}, timeoutSec=${seconds}, deviceId=${params.deviceId ?? "auto"}, useMpegTsMuxer=${useMpegTsMuxer}`
     );
     const startParams = {
       channel: params.channel,
@@ -23503,12 +23748,23 @@ ${scheduleItems}
       ...params.isNvr != null ? { isNvr: params.isNvr } : {},
       ...params.deviceId != null ? { deviceId: params.deviceId } : {}
     };
-    const { result: replayResult, release: releaseQueueSlot } = await this.enqueueStreamingReplayOperation(
-      () => this.startRecordingReplayStream(startParams)
-    );
+    const { result: replayResult, release: releaseQueueSlot } = await this.enqueueStreamingReplayOperation(async () => {
+      try {
+        return await this.startRecordingReplayStream(startParams);
+      } catch (e) {
+        if (!params.deviceId) throw e;
+        const sessionKey = `replay:${params.deviceId}`;
+        logger?.debug?.(
+          `[createRecordingReplayMp4Stream] startRecordingReplayStream failed; force-closing dedicated client and retrying once`
+        );
+        await this.forceCloseDedicatedClient(sessionKey, logger);
+        return await this.startRecordingReplayStream(startParams);
+      }
+    });
     const { stream, stop: stopReplay } = replayResult;
     const input = new import_node_stream.PassThrough();
     const output = new import_node_stream.PassThrough();
+    const H264_AUD = Buffer.from([0, 0, 0, 1, 9, 240]);
     let tsMuxer = null;
     let ff = null;
     let ended = false;
@@ -23517,26 +23773,59 @@ ${scheduleItems}
       if (ff) return;
       const needsTranscode = videoType === "H265" && params.transcodeH265ToH264 === true;
       logger?.debug?.(
-        `[createRecordingReplayMp4Stream] Starting ffmpeg with videoType=${videoType}, transcode=${needsTranscode}`
+        `[createRecordingReplayMp4Stream] Starting ffmpeg with videoType=${videoType}, transcode=${needsTranscode}, useMpegTsMuxer=${useMpegTsMuxer}, fps=${fps}`
       );
-      MpegTsMuxer.resetCounters();
-      tsMuxer = new MpegTsMuxer({ videoType });
-      const args = [
-        "-hide_banner",
-        "-loglevel",
-        "error",
-        "-f",
-        "mpegts",
-        "-i",
-        "pipe:0",
-        // Video codec: transcode H.265→H.264 if requested, otherwise copy
-        ...needsTranscode ? ["-c:v", "libx264", "-preset", "ultrafast", "-crf", "23"] : ["-c", "copy"],
-        "-movflags",
-        "frag_keyframe+empty_moov",
-        "-f",
-        "mp4",
-        "pipe:1"
-      ];
+      let args;
+      if (useMpegTsMuxer) {
+        MpegTsMuxer.resetCounters();
+        tsMuxer = new MpegTsMuxer({ videoType });
+        args = [
+          "-hide_banner",
+          "-loglevel",
+          "error",
+          "-f",
+          "mpegts",
+          "-i",
+          "pipe:0",
+          // Video codec: transcode H.265→H.264 if requested, otherwise copy
+          ...needsTranscode ? ["-c:v", "libx264", "-preset", "ultrafast", "-crf", "23"] : ["-c", "copy"],
+          // frag_keyframe: create new fragment at each keyframe
+          // empty_moov: write ftyp/moov immediately (required for streaming)
+          // default_base_moof: required for iOS Media Source Extensions
+          // negative_cts_offsets: fixes some iOS playback issues
+          "-movflags",
+          "frag_keyframe+empty_moov+default_base_moof+negative_cts_offsets",
+          "-f",
+          "mp4",
+          "pipe:1"
+        ];
+      } else {
+        const inputFormat = videoType === "H265" ? "hevc" : "h264";
+        args = [
+          "-hide_banner",
+          "-loglevel",
+          "error",
+          "-fflags",
+          "+genpts",
+          "-r",
+          String(fps),
+          "-f",
+          inputFormat,
+          "-i",
+          "pipe:0",
+          // Video codec: transcode H.265→H.264 if requested, otherwise copy
+          ...needsTranscode ? ["-c:v", "libx264", "-preset", "ultrafast", "-crf", "23"] : ["-c", "copy"],
+          // frag_keyframe: create new fragment at each keyframe
+          // empty_moov: write ftyp/moov immediately (required for streaming)
+          // default_base_moof: required for iOS Media Source Extensions
+          // negative_cts_offsets: fixes some iOS playback issues
+          "-movflags",
+          "frag_keyframe+empty_moov+default_base_moof+negative_cts_offsets",
+          "-f",
+          "mp4",
+          "pipe:1"
+        ];
+      }
       ff = (0, import_node_child_process3.spawn)("ffmpeg", args, { stdio: ["pipe", "pipe", "pipe"] });
       if (!ff.stdin || !ff.stdout || !ff.stderr) {
         throw new Error("ffmpeg stdio streams not available");
@@ -23574,17 +23863,19 @@ ${scheduleItems}
     const stopAll = async () => {
       if (ended) return;
       ended = true;
+      releaseQueueSlot();
       logger?.debug?.(
         `[createRecordingReplayMp4Stream] Stopping stream, frames=${frameCount}`
       );
-      try {
-        await stopReplay();
-      } catch {
-      }
-      try {
-        await stream.stop();
-      } catch {
-      }
+      const cleanupPromises = [];
+      cleanupPromises.push(
+        stopReplay().catch(() => {
+        })
+      );
+      cleanupPromises.push(
+        stream.stop().catch(() => {
+        })
+      );
       try {
         input.end();
       } catch {
@@ -23597,7 +23888,11 @@ ${scheduleItems}
         output.end();
       } catch {
       }
-      releaseQueueSlot();
+      await Promise.race([
+        Promise.all(cleanupPromises),
+        new Promise((resolve) => setTimeout(resolve, 2e3))
+        // Max 2s for cleanup
+      ]);
     };
     const timer = setTimeout(
       () => {
@@ -23619,15 +23914,25 @@ ${scheduleItems}
       output.destroy(e);
       void stopAll();
     });
+    stream.on("close", () => {
+      logger?.debug?.(
+        `[createRecordingReplayMp4Stream] Stream closed, frames=${frameCount}`
+      );
+      clearTimeout(timer);
+      void stopAll();
+    });
     stream.on(
       "videoAccessUnit",
       ({ data, videoType, isKeyframe, microseconds }) => {
         if (ended) return;
         startFfmpeg(videoType);
         frameCount++;
-        if (tsMuxer) {
+        if (useMpegTsMuxer && tsMuxer) {
           const tsData = tsMuxer.mux(data, microseconds, isKeyframe);
           input.write(tsData);
+        } else {
+          if (videoType === "H264") input.write(H264_AUD);
+          input.write(data);
         }
       }
     );
@@ -23666,19 +23971,53 @@ ${scheduleItems}
    */
   async createRecordingDownloadMp4Stream(params) {
     const timeoutMs = params.timeoutMs ?? 12e4;
-    const parsed = parseRecordingFileName(params.fileName);
-    const fps = parsed?.framerate && parsed.framerate > 0 ? parsed.framerate : 15;
     const channel = this.normalizeChannel(params.channel);
     const uid = await this.ensureUidForRecordings(channel);
-    const { annexB, videoType } = await this.downloadRecordingDemuxed({
+    const raw = await this.downloadRecording({
       channel,
       uid,
       fileName: params.fileName,
       timeoutMs
     });
-    if (annexB.length === 0) {
+    if (raw.length === 0) {
       throw new Error("Downloaded recording is empty");
     }
+    const videoFrames = [];
+    let videoType = null;
+    const decoder = new BcMediaAnnexBDecoder({
+      strict: false,
+      logger: this.logger,
+      onVideoAccessUnit: ({ annexB: annexB2, microseconds }) => {
+        videoFrames.push({ annexB: annexB2, microseconds });
+      }
+    });
+    decoder.push(raw);
+    const stats = decoder.getStats();
+    videoType = stats.videoType;
+    if (videoFrames.length === 0) {
+      throw new Error("Downloaded recording has no video frames");
+    }
+    let fps;
+    if (videoFrames.length >= 2) {
+      const firstTs = videoFrames[0].microseconds;
+      const lastTs = videoFrames[videoFrames.length - 1].microseconds;
+      const durationUs = lastTs - firstTs;
+      if (durationUs > 0) {
+        const durationSeconds = durationUs / 1e6;
+        fps = (videoFrames.length - 1) / durationSeconds;
+      } else {
+        const infoFps = stats.infos[0]?.fps;
+        fps = infoFps && infoFps > 0 ? infoFps : 15;
+      }
+    } else {
+      const infoFps = stats.infos[0]?.fps;
+      fps = infoFps && infoFps > 0 ? infoFps : 15;
+    }
+    if (fps > 14 && fps < 16) fps = 15;
+    else if (fps > 23 && fps < 26) fps = 25;
+    else if (fps > 29 && fps < 31) fps = 30;
+    else fps = Math.round(fps * 100) / 100;
+    const annexB = Buffer.concat(videoFrames.map((f) => f.annexB));
     const input = new import_node_stream.PassThrough();
     const output = new import_node_stream.PassThrough();
     let ff = null;
@@ -23750,6 +24089,338 @@ ${scheduleItems}
       stop: stopAll
     };
   }
+  /**
+   * 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();
+   * ```
+   */
+  async createRecordingReplayHlsSession(params) {
+    const logger = params.logger ?? this.logger;
+    const hlsSegmentDuration = params.hlsSegmentDuration ?? 4;
+    const os = await import("os");
+    const path5 = await import("path");
+    const fs5 = await import("fs/promises");
+    const crypto2 = await import("crypto");
+    const tempDir = path5.join(
+      os.tmpdir(),
+      `reolink-hls-${crypto2.randomBytes(8).toString("hex")}`
+    );
+    await fs5.mkdir(tempDir, { recursive: true });
+    const playlistPath = path5.join(tempDir, "playlist.m3u8");
+    const segmentPattern = path5.join(tempDir, "segment_%03d.ts");
+    const parsed = parseRecordingFileName(params.fileName);
+    const durationMs = parsed?.durationMs ?? 3e5;
+    const fps = parsed?.framerate && parsed.framerate > 0 ? parsed.framerate : 15;
+    const seconds = Math.ceil(durationMs / 1e3 * 1.1);
+    logger?.debug?.(
+      `[createRecordingReplayHlsSession] Starting: channel=${params.channel}, fileName=${params.fileName}, durationMs=${durationMs}, hlsSegmentDuration=${hlsSegmentDuration}`
+    );
+    const startParams = {
+      channel: params.channel,
+      fileName: params.fileName,
+      logger,
+      ...params.isNvr != null ? { isNvr: params.isNvr } : {},
+      ...params.deviceId != null ? { deviceId: params.deviceId } : {}
+    };
+    const { result: replayResult, release: releaseQueueSlot } = await this.enqueueStreamingReplayOperation(async () => {
+      try {
+        return await this.startRecordingReplayStream(startParams);
+      } catch (e) {
+        if (!params.deviceId) throw e;
+        const sessionKey = `replay:${params.deviceId}`;
+        logger?.debug?.(
+          `[createRecordingReplayHlsSession] startRecordingReplayStream failed; force-closing dedicated client and retrying once`
+        );
+        await this.forceCloseDedicatedClient(sessionKey, logger);
+        return await this.startRecordingReplayStream(startParams);
+      }
+    });
+    const { stream, stop: stopReplay } = replayResult;
+    const input = new import_node_stream.PassThrough();
+    const H264_AUD = Buffer.from([0, 0, 0, 1, 9, 240]);
+    let tsMuxer = null;
+    let ff = null;
+    let ended = false;
+    let frameCount = 0;
+    let readyResolve = null;
+    let segmentWatcher = null;
+    const readyPromise = new Promise((resolve) => {
+      readyResolve = resolve;
+    });
+    const segments = /* @__PURE__ */ new Map();
+    const startSegmentWatcher = () => {
+      if (segmentWatcher || !readyResolve) return;
+      const firstSegmentPath = path5.join(tempDir, "segment_000.ts");
+      let checkCount = 0;
+      const maxChecks = Math.ceil((hlsSegmentDuration + 2) * 10);
+      segmentWatcher = setInterval(async () => {
+        checkCount++;
+        try {
+          const stats = await fs5.stat(firstSegmentPath);
+          if (stats.size > 256) {
+            if (segmentWatcher) {
+              clearInterval(segmentWatcher);
+              segmentWatcher = null;
+            }
+            logger?.debug?.(
+              `[createRecordingReplayHlsSession] First segment ready after ${checkCount * 100}ms, size=${stats.size}`
+            );
+            readyResolve?.();
+            readyResolve = null;
+          }
+        } catch {
+        }
+        if (checkCount >= maxChecks && readyResolve) {
+          if (segmentWatcher) {
+            clearInterval(segmentWatcher);
+            segmentWatcher = null;
+          }
+          logger?.debug?.(
+            `[createRecordingReplayHlsSession] Segment watcher timeout, resolving anyway`
+          );
+          readyResolve?.();
+          readyResolve = null;
+        }
+      }, 100);
+    };
+    const startFfmpeg = (videoType) => {
+      if (ff) return;
+      const needsTranscode = videoType === "H265" && params.transcodeH265ToH264 === true;
+      const gop = Math.max(1, Math.round(fps * hlsSegmentDuration));
+      logger?.log?.(
+        `[createRecordingReplayHlsSession] Starting ffmpeg HLS with videoType=${videoType}, transcode=${needsTranscode}, hlsTime=${hlsSegmentDuration}s, fileName=${params.fileName}`
+      );
+      MpegTsMuxer.resetCounters();
+      tsMuxer = new MpegTsMuxer({ videoType });
+      const args = [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-f",
+        "mpegts",
+        "-i",
+        "pipe:0",
+        // Video codec
+        ...needsTranscode ? [
+          "-c:v",
+          "libx264",
+          "-preset",
+          "ultrafast",
+          "-tune",
+          "zerolatency",
+          "-crf",
+          "23",
+          "-pix_fmt",
+          "yuv420p",
+          // Ensure regular GOP for consistent HLS cutting.
+          "-g",
+          String(gop),
+          "-keyint_min",
+          String(gop),
+          "-sc_threshold",
+          "0",
+          // Force frequent keyframes so HLS can cut segments reliably.
+          // Without this, ffmpeg will only cut on keyframes and segments can become huge.
+          "-force_key_frames",
+          `expr:gte(t,n_forced*${hlsSegmentDuration})`
+        ] : ["-c", "copy"],
+        // HLS output options
+        "-f",
+        "hls",
+        "-hls_time",
+        String(hlsSegmentDuration),
+        "-hls_list_size",
+        "0",
+        // Keep all segments in playlist
+        "-hls_playlist_type",
+        "event",
+        // Growing playlist (not VOD until end)
+        "-hls_segment_filename",
+        segmentPattern,
+        "-hls_flags",
+        "independent_segments+temp_file",
+        playlistPath
+      ];
+      ff = (0, import_node_child_process3.spawn)("ffmpeg", args, { stdio: ["pipe", "pipe", "pipe"] });
+      if (!ff.stdin || !ff.stderr) {
+        throw new Error("ffmpeg stdio streams not available");
+      }
+      input.pipe(ff.stdin);
+      ff.stdin.on("error", () => {
+      });
+      ff.stderr.on("error", () => {
+      });
+      input.on("error", () => {
+      });
+      let stderr = "";
+      ff.stderr.on("data", (d) => stderr += String(d));
+      ff.on("close", (code) => {
+        if (ended) return;
+        ended = true;
+        if ((code ?? 0) !== 0 && stderr.trim()) {
+          logger?.error?.(
+            `[createRecordingReplayHlsSession] ffmpeg exited with code ${code}: ${stderr}`
+          );
+        } else {
+          logger?.debug?.(
+            `[createRecordingReplayHlsSession] ffmpeg closed normally, frames=${frameCount}`
+          );
+        }
+      });
+    };
+    const stopAll = async () => {
+      if (ended) return;
+      ended = true;
+      releaseQueueSlot();
+      if (segmentWatcher) {
+        clearInterval(segmentWatcher);
+        segmentWatcher = null;
+      }
+      logger?.debug?.(
+        `[createRecordingReplayHlsSession] Stopping, frames=${frameCount}`
+      );
+      const cleanupPromises = [];
+      cleanupPromises.push(stopReplay().catch(() => {
+      }));
+      cleanupPromises.push(stream.stop().catch(() => {
+      }));
+      try {
+        input.end();
+      } catch {
+      }
+      try {
+        ff?.kill("SIGKILL");
+      } catch {
+      }
+      await Promise.race([
+        Promise.all(cleanupPromises),
+        new Promise((resolve) => setTimeout(resolve, 2e3))
+      ]);
+      setTimeout(async () => {
+        try {
+          const files = await fs5.readdir(tempDir);
+          for (const file of files) {
+            await fs5.unlink(path5.join(tempDir, file)).catch(() => {
+            });
+          }
+          await fs5.rmdir(tempDir).catch(() => {
+          });
+        } catch {
+        }
+      }, 6e4);
+    };
+    const timer = setTimeout(
+      () => {
+        logger?.debug?.(
+          `[createRecordingReplayHlsSession] Timeout reached (${seconds}s), stopping`
+        );
+        void stopAll();
+      },
+      Math.max(1, seconds) * 1e3
+    );
+    stream.on("error", (e) => {
+      logger?.error?.(
+        `[createRecordingReplayHlsSession] Stream error: ${e.message}`
+      );
+      clearTimeout(timer);
+      void stopAll();
+    });
+    stream.on("close", () => {
+      logger?.debug?.(
+        `[createRecordingReplayHlsSession] Stream closed, frames=${frameCount}`
+      );
+      clearTimeout(timer);
+      try {
+        input.end();
+      } catch {
+      }
+    });
+    stream.on(
+      "videoAccessUnit",
+      ({ data, videoType, isKeyframe, microseconds }) => {
+        if (ended) return;
+        startFfmpeg(videoType);
+        frameCount++;
+        if (tsMuxer) {
+          const tsData = tsMuxer.mux(data, microseconds, isKeyframe);
+          input.write(tsData);
+        }
+        if (frameCount === 1) {
+          startSegmentWatcher();
+        }
+      }
+    );
+    return {
+      getPlaylist: () => {
+        try {
+          const { readFileSync } = require("fs");
+          return readFileSync(playlistPath, "utf8");
+        } catch {
+          return "#EXTM3U\n#EXT-X-VERSION:3\n#EXT-X-TARGETDURATION:4\n";
+        }
+      },
+      getSegment: (name) => {
+        if (segments.has(name)) {
+          return segments.get(name);
+        }
+        try {
+          const { readFileSync } = require("fs");
+          const segmentPath = path5.join(tempDir, name);
+          const data = readFileSync(segmentPath);
+          segments.set(name, data);
+          return data;
+        } catch {
+          return void 0;
+        }
+      },
+      listSegments: () => {
+        try {
+          const { readdirSync } = require("fs");
+          return readdirSync(tempDir).filter(
+            (f) => f.endsWith(".ts")
+          );
+        } catch {
+          return [];
+        }
+      },
+      waitForReady: () => readyPromise,
+      stop: stopAll,
+      tempDir
+    };
+  }
   // ============================================================
   // STANDALONE CAMERA METHODS
   // ============================================================