@apocaliss92/scrypted-reolink-native 0.1.36 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "@apocaliss92/scrypted-reolink-native",
-   "version": "0.1.36",
+   "version": "0.1.37",
    "description": "Use any reolink camera with Scrypted, even older/unsupported models without HTTP protocol support",
    "author": "@apocaliss92",
    "license": "Apache",

package/src/baichuan-base.ts

@@ -1,4 +1,4 @@
-import type { ReolinkBaichuanApi, ReolinkSimpleEvent } from "@apocaliss92/reolink-baichuan-js" with { "resolution-mode": "import" };
+import type { BaichuanClientOptions, ReolinkBaichuanApi, ReolinkSimpleEvent } from "@apocaliss92/reolink-baichuan-js" with { "resolution-mode": "import" };
 import { ScryptedDeviceBase } from "@scrypted/sdk";
 import { createBaichuanApi, type BaichuanTransport } from "./connect";
 
@@ -8,8 +8,8 @@ export interface BaichuanConnectionConfig {
     password: string;
     uid?: string;
     transport: BaichuanTransport;
-    logger: Console;
     debugOptions?: any;
+    udpDiscoveryMethod?: BaichuanClientOptions["udpDiscoveryMethod"];
 }
 
 export interface BaichuanConnectionCallbacks {
@@ -259,6 +259,7 @@ export abstract class BaseBaichuanClass extends ScryptedDeviceBase {
                     uid: config.uid,
                     logger,
                     debugOptions: config.debugOptions,
+                    udpDiscoveryMethod: config.udpDiscoveryMethod,
                 },
                 transport: config.transport,
             });

package/src/common.ts

@@ -1,4 +1,4 @@
-import type { DeviceCapabilities, PtzCommand, PtzPreset, ReolinkBaichuanApi, ReolinkSimpleEvent, ReolinkSupportedStream, StreamProfile, StreamSamplingSelection } from "@apocaliss92/reolink-baichuan-js" with { "resolution-mode": "import" };
+import type { BaichuanClientOptions, DeviceCapabilities, PtzCommand, PtzPreset, ReolinkBaichuanApi, ReolinkSimpleEvent, ReolinkSupportedStream, StreamProfile, StreamSamplingSelection } from "@apocaliss92/reolink-baichuan-js" with { "resolution-mode": "import" };
 import sdk, { BinarySensor, Brightness, Camera, Device, DeviceProvider, Intercom, MediaObject, MediaStreamUrl, ObjectDetectionTypes, ObjectDetector, ObjectsDetected, OnOff, PanTiltZoom, PanTiltZoomCommand, Reboot, RequestMediaStreamOptions, RequestPictureOptions, ResponsePictureOptions, ScryptedDeviceBase, ScryptedDeviceType, ScryptedInterface, ScryptedMimeTypes, Setting, Settings, SettingValue, VideoCamera, VideoClip, VideoClipOptions, VideoClips, VideoClipThumbnailOptions, VideoTextOverlay, VideoTextOverlays } from "@scrypted/sdk";
 import { StorageSettings } from "@scrypted/sdk/storage-settings";
 import path from 'path';
@@ -24,7 +24,7 @@ import {
     selectStreamOption,
     StreamManager
 } from "./stream-utils";
-import { floodlightSuffix, getDeviceInterfaces, getVideoClipWebhookUrls, pirSuffix, recordingFileToVideoClip, sanitizeFfmpegOutput, sirenSuffix, updateDeviceInfo, vodSearchResultsToVideoClips } from "./utils";
+import { floodlightSuffix, getDeviceInterfaces, getVideoClipWebhookUrls, pirSuffix, recordingsToVideoClips, sanitizeFfmpegOutput, sirenSuffix, updateDeviceInfo, vodSearchResultsToVideoClips } from "./utils";
 
 export type CameraType = 'battery' | 'regular' | 'multi-focal' | 'multi-focal-battery';
 
@@ -300,6 +300,17 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
                 await this.credentialsChanged();
             }
         },
+        discoveryMethod: {
+            title: 'Discovery Method',
+            description: 'UDP discovery method for battery cameras (BCUDP).',
+            type: 'string',
+            choices: ['local', 'remote', 'map', 'relay'],
+            defaultValue: 'local',
+            hide: true,
+            onPut: async () => {
+                await this.credentialsChanged();
+            }
+        },
         debugLogs: {
             title: 'Debug logs',
             type: 'boolean',
@@ -664,6 +675,7 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
     private streamManagerRestartTimeout: NodeJS.Timeout | undefined;
     private videoClipsAutoLoadInterval: NodeJS.Timeout | undefined;
     private videoClipsAutoLoadInProgress: boolean = false;
+    private videoClipsAutoLoadMode: boolean = false;
 
     constructor(
         nativeId: string,
@@ -698,7 +710,8 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
             return [];
         }
 
-        if (this.isBattery && this.sleeping) {
+        // Skip sleeping check during auto-load to allow auto-load to start for battery cameras
+        if (!this.videoClipsAutoLoadMode && this.isBattery && this.sleeping) {
             const logger = this.getBaichuanLogger();
             logger.debug('getVideoClips: disabled for battery devices');
             return [];
@@ -728,13 +741,14 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
 
         const start = new Date(startMs);
         const end = new Date(endMs);
-        // Use UTC to match API's dateToReolinkTime conversion
-        start.setUTCHours(0, 0, 0, 0);
+        start.setHours(0, 0, 0, 0);
 
         try {
             const { clipsSource } = this.storageSettings.values;
             const useNvr = clipsSource === "NVR" && this.nvrDevice;
 
+            const api = await this.ensureClient();
+
             if (useNvr) {
                 // Fetch from NVR using listEnrichedVodFiles (library handles parsing correctly)
                 const channel = this.storageSettings.values.rtspChannel ?? 0;
@@ -742,106 +756,49 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
                 // Use listEnrichedVodFiles which properly parses filenames and extracts detection info
                 logger.debug(`[NVR VOD] Searching for video clips: channel=${channel}, start=${start.toISOString()}, end=${end.toISOString()}`);
                 // Filter to only include recordings within the requested time window
-                const enrichedRecordings = await this.nvrDevice.listEnrichedVodFiles({
+                const enrichedRecordings = await api.listNvrRecordings({
                     channel,
                     start,
                     end,
                     streamType: "main",
-                    autoSearchByDay: false, // Disable autoSearchByDay to avoid searching past days
-                    bypassCache: false,
                 });
 
                 logger.debug(`[NVR VOD] Found ${enrichedRecordings.length} enriched recordings from NVR`);
 
-                // Log sample of enriched recordings to see what the library returned
-                if (enrichedRecordings.length > 0) {
-                    const sampleSize = Math.min(3, enrichedRecordings.length);
-                    for (let i = 0; i < sampleSize; i++) {
-                        const rec = enrichedRecordings[i];
-                        logger.debug(`[NVR VOD] Sample enriched recording ${i + 1}/${enrichedRecordings.length}:`, {
-                            fileName: rec.fileName,
-                            startTimeMs: rec.startTimeMs,
-                            endTimeMs: rec.endTimeMs,
-                            durationMs: rec.durationMs,
-                            hasPerson: rec.hasPerson,
-                            hasVehicle: rec.hasVehicle,
-                            hasAnimal: rec.hasAnimal,
-                            hasFace: rec.hasFace,
-                            hasMotion: rec.hasMotion,
-                            hasDoorbell: rec.hasDoorbell,
-                            hasPackage: rec.hasPackage,
-                            recordType: rec.recordType,
-                            parsedFileName: rec.parsedFileName ? {
-                                start: rec.parsedFileName.start?.toISOString(),
-                                end: rec.parsedFileName.end?.toISOString(),
-                                flags: rec.parsedFileName.flags,
-                            } : null,
-                        });
-                    }
-                }
-
-                // Convert enriched recordings to VideoClip array
-                const clips: VideoClip[] = [];
-
-                for (const rec of enrichedRecordings) {
-                    // Log detection flags before conversion
-                    const flags = {
-                        hasPerson: 'hasPerson' in rec ? rec.hasPerson : false,
-                        hasVehicle: 'hasVehicle' in rec ? rec.hasVehicle : false,
-                        hasAnimal: 'hasAnimal' in rec ? rec.hasAnimal : false,
-                        hasFace: 'hasFace' in rec ? rec.hasFace : false,
-                        hasMotion: 'hasMotion' in rec ? rec.hasMotion : false,
-                        hasDoorbell: 'hasDoorbell' in rec ? rec.hasDoorbell : false,
-                        hasPackage: 'hasPackage' in rec ? rec.hasPackage : false,
-                        recordType: rec.recordType || 'none',
-                    };
-                    logger.debug(`[NVR VOD] Processing recording: fileName=${rec.fileName}, flags=${JSON.stringify(flags)}`);
-
-                    const clip = await recordingFileToVideoClip(rec, {
-                        fallbackStart: start,
-                        logger,
-                        plugin: this,
-                        deviceId: this.id,
-                        useWebhook: true,
-                    });
-
-                    // Log detection classes in the final clip
-                    logger.debug(`[NVR VOD] Generated clip: id=${clip.id}, detectionClasses=${clip.detectionClasses?.join(',') || 'none'}`);
-                    clips.push(clip);
-                }
+                // Convert enriched recordings to VideoClip array using the shared parser
+                const clips = await recordingsToVideoClips(enrichedRecordings, {
+                    fallbackStart: start,
+                    logger,
+                    plugin: this,
+                    deviceId: this.id,
+                    useWebhook: true,
+                    count,
+                });
 
-                // Apply count limit if specified
-                const finalClips = count ? clips.slice(0, count) : clips;
-                logger.debug(`[NVR VOD] Converted ${finalClips.length} video clips (limit: ${count || 'none'})`);
+                logger.debug(`[NVR VOD] Converted ${clips.length} video clips (limit: ${count || 'none'})`);
 
-                return finalClips;
+                return clips;
             } else {
-                // Fetch directly from device using Baichuan API
-                const api = await this.ensureClient();
-
-                const recordings = await api.listEnrichedRecordingsByTime({
+                const recordings = await api.listDeviceRecordings({
                     start,
                     end,
                     count,
                     channel: this.storageSettings.values.rtspChannel,
                     streamType: 'mainStream',
                     httpFallback: false,
-                    fetchRtmpUrls: true
+                    fetchRtmpUrls: false
                 });
 
-                const clips: VideoClip[] = [];
-
-                for (const rec of recordings) {
-                    const clip = await recordingFileToVideoClip(rec, {
-                        fallbackStart: start,
-                        api,
-                        logger,
-                        plugin: this,
-                        deviceId: this.id,
-                        useWebhook: true,
-                    });
-                    clips.push(clip);
-                }
+                // Convert recordings to VideoClip array using the shared parser
+                const clips = await recordingsToVideoClips(recordings, {
+                    fallbackStart: start,
+                    api,
+                    logger,
+                    plugin: this,
+                    deviceId: this.id,
+                    useWebhook: true,
+                    count,
+                });
 
                 logger.debug(`Videoclips found: ${clips.length}`);
 
@@ -1166,12 +1123,12 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
 
         if (useNvr) {
             logger.debug(`[getVideoClipRtmpUrl] Using NVR API for fileId="${fileId}", forThumbnail=${forThumbnail}`);
-            const nvrApi = await this.nvrDevice.ensureClient();
+            const api = await this.ensureClient();
             const channel = this.storageSettings.values.rtspChannel ?? 0;
 
             try {
                 logger.debug(`[getVideoClipRtmpUrl] Trying getVodUrl with Download requestType...`);
-                const url = await nvrApi.getVodUrl(fileId, channel, {
+                const url = await api.getVodUrl(fileId, channel, {
                     requestType: "Download",
                     streamType: "main",
                 });
@@ -1250,6 +1207,7 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
         const logger = this.getBaichuanLogger();
 
         this.videoClipsAutoLoadInProgress = true;
+        this.videoClipsAutoLoadMode = true;
 
         try {
             const daysToPreload = this.storageSettings.values.videoclipsDaysToPreload ?? 1;
@@ -1315,6 +1273,7 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
             logger.error('Error during auto-loading video clips:', e);
         } finally {
             this.videoClipsAutoLoadInProgress = false;
+            this.videoClipsAutoLoadMode = false;
         }
     }
 
@@ -1325,7 +1284,7 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
 
     // BaseBaichuanClass abstract methods implementation
     protected getConnectionConfig(): BaichuanConnectionConfig {
-        const { ipAddress, username, password, uid } = this.storageSettings.values;
+        const { ipAddress, username, password, uid, discoveryMethod } = this.storageSettings.values;
         const debugOptions = this.getBaichuanDebugOptions();
         const normalizedUid = this.isBattery ? normalizeUid(uid) : undefined;
 
@@ -1333,15 +1292,14 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
             throw new Error('UID is required for battery cameras (BCUDP)');
         }
 
-        const logger = this.getBaichuanLogger();
         return {
             host: ipAddress,
             username,
             password,
             uid: normalizedUid,
             transport: this.protocol,
-            logger,
             debugOptions,
+            udpDiscoveryMethod: discoveryMethod as BaichuanClientOptions["udpDiscoveryMethod"],
         };
     }
 
@@ -1424,12 +1382,17 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
 
         try {
             const api = await this.ensureClient();
+            const { ipAddress, username, password } = this.storageSettings.values;
 
             const result = await api.runAllDiagnosticsConsecutively({
+                host: ipAddress,
+                username,
+                password,
                 outDir: outputPath,
                 channel,
                 durationSeconds,
                 selection,
+                api,
             });
 
             logger.log(`Diagnostics completed successfully. Output directory: ${result.runDir}`);
@@ -2497,6 +2460,7 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
                 logger.warn('Failed to connect/refresh during init', e);
             }
         }
+        this.storageSettings.settings.socketApiDebugLogs.hide = !!this.nvrDevice;
         this.storageSettings.settings.clipsSource.hide = !this.nvrDevice;
         this.storageSettings.settings.clipsSource.defaultValue = this.nvrDevice ? "NVR" : "Device";
 
@@ -2513,6 +2477,9 @@ export abstract class CommonCameraMixin extends BaseBaichuanClass implements Vid
         this.storageSettings.settings.widerChannel.hide = !this.isMultiFocal;
         this.storageSettings.settings.teleChannel.hide = !this.isMultiFocal;
 
+        this.storageSettings.settings.uid.hide = !this.isBattery;
+        this.storageSettings.settings.discoveryMethod.hide = !this.isBattery;
+
         if (this.isBattery && !this.storageSettings.values.mixinsSetup) {
             try {
                 const device = sdk.systemManager.getDeviceById<Settings>(this.id);

package/src/connect.ts

@@ -9,6 +9,7 @@ export type BaichuanConnectInputs = {
     uid?: string;
     logger?: Console;
     debugOptions?: BaichuanClientOptions['debugOptions'];
+    udpDiscoveryMethod?: "local" | "remote" | "map" | "relay";
 };
 
 export function normalizeUid(uid?: string): string | undefined {
@@ -81,6 +82,7 @@ export async function createBaichuanApi(props: {
         transport: "udp",
         uid,
         idleDisconnect: true,
+        udpDiscoveryMethod: inputs.udpDiscoveryMethod,
     });
     attachErrorHandler(api);
     return api;

package/src/main.ts

@@ -200,6 +200,7 @@ class ReolinkNativePlugin extends ScryptedDeviceBase implements DeviceProvider,
             device.storageSettings.values.ipAddress = ipAddress;
             device.storageSettings.values.capabilities = capabilities;
             device.storageSettings.values.uid = uid;
+            device.storageSettings.values.discoveryMethod = detection.udpDiscoveryMethod;
 
             return nativeId;
         }

package/src/nvr.ts

@@ -1,9 +1,10 @@
-import type { DeviceInfoResponse, EnrichedRecordingFile, EventsResponse, ReolinkBaichuanApi, ReolinkCgiApi, ReolinkSimpleEvent } from "@apocaliss92/reolink-baichuan-js" with { "resolution-mode": "import" };
+import type { DeviceInfoResponse, EnrichedRecordingFile, EventsResponse, ListNvrRecordingsParams, ReolinkBaichuanApi, ReolinkCgiApi, ReolinkSimpleEvent } from "@apocaliss92/reolink-baichuan-js" with { "resolution-mode": "import" };
 import sdk, { AdoptDevice, Device, DeviceDiscovery, DeviceProvider, DiscoveredDevice, Reboot, ScryptedDeviceType, ScryptedInterface, Setting, Settings, SettingValue } from "@scrypted/sdk";
 import { StorageSettings } from "@scrypted/sdk/storage-settings";
 import { BaseBaichuanClass, type BaichuanConnectionCallbacks, type BaichuanConnectionConfig } from "./baichuan-base";
 import { ReolinkNativeCamera } from "./camera";
 import { ReolinkNativeBatteryCamera } from "./camera-battery";
+import { convertDebugLogsToApiOptions, getApiRelevantDebugLogs, getDebugLogChoices } from "./debug-options";
 import { normalizeUid } from "./connect";
 import ReolinkNativePlugin from "./main";
 import { getDeviceInterfaces, updateDeviceInfo } from "./utils";
@@ -44,8 +45,8 @@ export class ReolinkNativeNvrDevice extends BaseBaichuanClass implements Setting
             onPut: async () => await this.reinit()
         },
         diagnosticsRun: {
-            subgroup: 'Diagnostics',
-            title: 'Run NVR Diagnostics',
+            subgroup: 'Advanced',
+            title: 'Run Diagnostics',
             description: 'Collect NVR diagnostics and display results in logs.',
             type: 'button',
             immediate: true,
@@ -53,6 +54,47 @@ export class ReolinkNativeNvrDevice extends BaseBaichuanClass implements Setting
                 await this.runNvrDiagnostics();
             },
         },
+        socketApiDebugLogs: {
+            subgroup: 'Advanced',
+            title: 'Socket API Debug Logs',
+            description: 'Enable specific debug logs.',
+            multiple: true,
+            combobox: true,
+            immediate: true,
+            defaultValue: [],
+            choices: getDebugLogChoices(),
+            onPut: async (ov, value) => {
+                const logger = this.getBaichuanLogger();
+                const oldApiOptions = getApiRelevantDebugLogs(ov || []);
+                const newApiOptions = getApiRelevantDebugLogs(value || []);
+
+                const oldSel = new Set(oldApiOptions);
+                const newSel = new Set(newApiOptions);
+
+                const changed = oldSel.size !== newSel.size || Array.from(oldSel).some((k) => !newSel.has(k));
+                if (changed) {
+                    // Clear any existing timeout
+                    if (this.debugLogsResetTimeout) {
+                        clearTimeout(this.debugLogsResetTimeout);
+                        this.debugLogsResetTimeout = undefined;
+                    }
+
+                    // Defer reset by 2 seconds to allow settings to settle
+                    this.debugLogsResetTimeout = setTimeout(async () => {
+                        this.debugLogsResetTimeout = undefined;
+                        try {
+                            // Force reconnection with new debug options
+                            this.baichuanApi = undefined;
+                            this.ensureClientPromise = undefined;
+                            // Trigger reconnection
+                            await this.ensureBaichuanClient();
+                        } catch (e) {
+                            logger.warn('Failed to reset client after debug logs change', e);
+                        }
+                    }, 2000);
+                }
+            },
+        },
     });
     plugin: ReolinkNativePlugin;
     nvrApi: ReolinkCgiApi | undefined;
@@ -71,6 +113,7 @@ export class ReolinkNativeNvrDevice extends BaseBaichuanClass implements Setting
     private discoverDevicesPromise: Promise<DiscoveredDevice[]> | undefined;
     processing = false;
     private initReinitTimeout: NodeJS.Timeout | undefined;
+    private debugLogsResetTimeout: NodeJS.Timeout | undefined;
 
     constructor(nativeId: string, plugin: ReolinkNativePlugin) {
         super(nativeId);
@@ -84,22 +127,28 @@ export class ReolinkNativeNvrDevice extends BaseBaichuanClass implements Setting
         await api.reboot();
     }
 
-    // BaseBaichuanClass abstract methods implementation
     protected getConnectionConfig(): BaichuanConnectionConfig {
         const { ipAddress, username, password } = this.storageSettings.values;
         if (!ipAddress || !username || !password) {
             throw new Error('Missing NVR credentials');
         }
 
+        const debugOptions = this.getBaichuanDebugOptions();
+
         return {
             host: ipAddress,
             username,
             password,
             transport: 'tcp',
-            logger: this.console,
+            debugOptions,
         };
     }
 
+    getBaichuanDebugOptions(): any | undefined {
+        const socketDebugLogs = this.storageSettings.values.socketApiDebugLogs || [];
+        return convertDebugLogsToApiOptions(socketDebugLogs);
+    }
+
     protected getConnectionCallbacks(): BaichuanConnectionCallbacks {
         return {
             onError: undefined, // Use default error handling
@@ -187,29 +236,6 @@ export class ReolinkNativeNvrDevice extends BaseBaichuanClass implements Setting
         return this.nvrApi;
     }
 
-    /**
-     * List enriched VOD files (with proper parsing and detection info)
-     * This uses the library's enrichVodFile which handles all parsing correctly
-     */
-    async listEnrichedVodFiles(params: {
-        channel: number;
-        start: Date;
-        end: Date;
-        streamType?: "main" | "sub";
-        autoSearchByDay?: boolean;
-        bypassCache?: boolean;
-    }): Promise<Array<EnrichedRecordingFile>> {
-        const api = await this.ensureClient();
-        return await api.listEnrichedVodFiles({
-            channel: params.channel,
-            start: params.start,
-            end: params.end,
-            streamType: params.streamType,
-            autoSearchByDay: params.autoSearchByDay,
-            bypassCache: params.bypassCache,
-        });
-    }
-
     private forwardNativeEvent(ev: ReolinkSimpleEvent): void {
         const logger = this.getBaichuanLogger();
 
@@ -298,15 +324,13 @@ export class ReolinkNativeNvrDevice extends BaseBaichuanClass implements Setting
         logger.log(`Starting NVR diagnostics...`);
 
         try {
-            const cgiApi = await this.ensureClient();
+            const cgiApi = await this.ensureBaichuanClient();
 
             const diagnostics = await cgiApi.collectNvrDiagnostics({
                 logger: this.console,
             });
 
             logger.log(`NVR diagnostics completed successfully.`);
-
-            cgiApi.printNvrDiagnostics(diagnostics, this.console);
         } catch (e) {
             logger.error('Failed to run NVR diagnostics', e);
             throw e;
@@ -427,7 +451,7 @@ export class ReolinkNativeNvrDevice extends BaseBaichuanClass implements Setting
 
         const { ipAddress } = this.storageSettings.values;
         try {
-            const api = await this.ensureClient();
+            const api = await this.ensureBaichuanClient();
             const deviceData = await api.getInfo();
 
             await updateDeviceInfo({

package/src/utils.ts

@@ -329,6 +329,53 @@ export async function recordingFileToVideoClip(
     };
 }
 
+/**
+ * Convert an array of RecordingFile or EnrichedRecordingFile to VideoClip array
+ * Uses recordingFileToVideoClip for each recording
+ * Handles both NVR (EnrichedRecordingFile) and device standalone (RecordingFile) cases
+ */
+export async function recordingsToVideoClips(
+    recordings: (RecordingFile | EnrichedRecordingFile)[],
+    options: {
+        /** Fallback start date if recording doesn't have one */
+        fallbackStart: Date;
+        /** API instance to get playback URLs (optional, for device standalone recordings) */
+        api?: ReolinkBaichuanApi;
+        /** Logger for debug messages */
+        logger?: Console;
+        /** Plugin instance for generating webhook URLs */
+        plugin?: ScryptedDeviceBase;
+        /** Device ID for webhook URLs */
+        deviceId?: string;
+        /** Use webhook URLs instead of direct RTMP URLs */
+        useWebhook?: boolean;
+        /** Maximum number of clips to return (optional) */
+        count?: number;
+    }
+): Promise<VideoClip[]> {
+    const { fallbackStart, api, logger, plugin, deviceId, useWebhook, count } = options;
+    const clips: VideoClip[] = [];
+
+    for (const rec of recordings) {
+        try {
+            const clip = await recordingFileToVideoClip(rec, {
+                fallbackStart,
+                api,
+                logger,
+                plugin,
+                deviceId,
+                useWebhook,
+            });
+            clips.push(clip);
+        } catch (e) {
+            logger?.warn(`Failed to convert recording to video clip: fileName=${rec.fileName}`, e);
+        }
+    }
+
+    // Apply count limit if specified
+    return count ? clips.slice(0, count) : clips;
+}
+
 /**
  * Generate webhook URLs for video clips
  */