homebridge-ring-hksv 14.3.6 → 14.3.8

package/README.md

@@ -31,11 +31,13 @@ Big thanks to Dustin and all upstream contributors. This fork reuses and extends
 | `hksvPrebufferLengthMs` | HKSV prebuffer duration (minimum 4000ms) |
 | `hksvFragmentLengthMs` | HKSV fragment duration target |
 | `hksvMaxRecordingSeconds` | Optional safety cap for a recording session |
+| `hksvPerformanceMode` | HKSV tuning profile (`balanced`, `rpi`, or `quality`) |
+| `hksvMaxConcurrentRecordings` / `hksvMaxQueuedBytes` | HKSV safeguards for small systems under load |
 | `hksvVideoBitrateKbps` / `hksvVideoMaxBitrateKbps` / `hksvVideoBufferSizeKbps` | HKSV recording bitrate controls for improving fast-motion quality |
 | `hksvVideoCrf` / `hksvVideoPreset` | Optional libx264 quality and CPU tuning controls |
 | `hksvVideoKeyframeInterval` | HKSV recording keyframe interval |
 | `homeKitAccessoryTag` | Appends a tag to accessory names and HomeKit IDs so the same Ring device can be exposed as a distinct HomeKit accessory for debugging/testing |
-| `cameraVideoCodec` | Preferred H.264 encoder (`h264_videotoolbox` or `libx264`) |
+| `cameraVideoCodec` | Preferred H.264 handling (`auto`, `copy`, `h264_v4l2m2m`, `h264_videotoolbox`, or `libx264`) |
 | `hideDoorbellSwitch` / `hideCameraMotionSensor` / `hideCameraSirenSwitch` | Hides specific HomeKit-exposed services |
 | `showPanicButtons` | Adds panic switches (use with caution) |
 | `ffmpegPath` | Override FFmpeg binary path |
@@ -90,10 +92,28 @@ I currently am able to run 3 cameras with HKSV enabled on a Homebridge instance
 Please report your experience and setup details to help improve support.
 
 For fast-motion pixelation or stuttering in HKSV recordings, try increasing
-`hksvVideoBitrateKbps` first. On Apple Silicon Macs,
+`hksvVideoBitrateKbps` first if you are transcoding. On Apple Silicon Macs,
 `cameraVideoCodec: "h264_videotoolbox"` can reduce CPU load by using hardware
-encoding. A good starting point is 4000-6000 kbps target bitrate, 8000-12000
-kbps max bitrate, and the default keyframe interval of 30.
+encoding.
+
+For Raspberry Pi 4/5 and other small computers, start with:
+
+```json
+{
+  "enableHksv": true,
+  "hksvPerformanceMode": "rpi",
+  "cameraVideoCodec": "auto",
+  "hksvMaxConcurrentRecordings": 1
+}
+```
+
+The `rpi` profile favors remuxing Ring's H.264 video into HomeKit Secure Video
+fragmented MP4 instead of re-encoding it. This is much lighter than libx264, but
+it depends on Ring's current stream being compatible with HomeKit's H.264
+recording requirements. If recording fails in this mode, try
+`cameraVideoCodec: "h264_v4l2m2m"` when your FFmpeg build exposes that encoder,
+or fall back to `cameraVideoCodec: "libx264"` with `hksvVideoPreset:
+"ultrafast"`.
 
 ### Minimum specifications for HKSV: 
 [TBD - will be added as more users test and report their setups]

package/config.schema.json

@@ -53,6 +53,40 @@
         "maximum": 300,
         "description": "Optional safety cap for a single HKSV recording stream duration."
       },
+      "hksvPerformanceMode": {
+        "title": "HKSV Performance Mode",
+        "type": "string",
+        "description": "High-level HKSV tuning profile. Use rpi for Raspberry Pi and other small computers; it favors remuxing, lower advertised recording tiers, and conservative concurrency.",
+        "default": "balanced",
+        "oneOf": [
+          {
+            "title": "balanced",
+            "enum": ["balanced"]
+          },
+          {
+            "title": "rpi",
+            "enum": ["rpi"]
+          },
+          {
+            "title": "quality",
+            "enum": ["quality"]
+          }
+        ]
+      },
+      "hksvMaxQueuedBytes": {
+        "title": "HKSV Max Queued Bytes",
+        "type": "integer",
+        "minimum": 1048576,
+        "maximum": 67108864,
+        "description": "Maximum fragmented MP4 data queued in memory per HKSV recording stream before the stream is closed to protect Homebridge."
+      },
+      "hksvMaxConcurrentRecordings": {
+        "title": "HKSV Max Concurrent Recordings",
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 4,
+        "description": "Maximum number of simultaneous HKSV recording pipelines. Raspberry Pi users should keep this at 1."
+      },
       "hksvVideoBitrateKbps": {
         "title": "HKSV Video Bitrate (kbps)",
         "type": "integer",
@@ -141,8 +175,20 @@
       "cameraVideoCodec": {
         "title": "Camera Video Codec",
         "type": "string",
-        "description": "Preferred FFmpeg H.264 encoder for HKSV recording transcodes. On Apple Silicon or newer Intel Macs, h264_videotoolbox is the recommended first choice because it uses hardware acceleration.",
+        "description": "Preferred FFmpeg H.264 handling for HKSV recordings. auto chooses the lowest-cost option for the configured performance mode; copy remuxes Ring video without re-encoding.",
         "oneOf": [
+          {
+            "title": "auto",
+            "enum": ["auto"]
+          },
+          {
+            "title": "copy",
+            "enum": ["copy"]
+          },
+          {
+            "title": "h264_v4l2m2m",
+            "enum": ["h264_v4l2m2m"]
+          },
           {
             "title": "h264_videotoolbox",
             "enum": ["h264_videotoolbox"]
@@ -295,6 +341,9 @@
         "hksvPrebufferLengthMs",
         "hksvFragmentLengthMs",
         "hksvMaxRecordingSeconds",
+        "hksvPerformanceMode",
+        "hksvMaxQueuedBytes",
+        "hksvMaxConcurrentRecordings",
         "hksvVideoBitrateKbps",
         "hksvVideoMaxBitrateKbps",
         "hksvVideoBufferSizeKbps",

package/lib/camera-source.js

@@ -8,6 +8,10 @@ import { promisify } from 'util';
 import { getFfmpegPath } from 'ring-client-api/ffmpeg';
 import { RtcpSenderInfo, RtcpSrPacket, RtpPacket, SrtpSession, SrtcpSession, } from 'werift';
 import path from 'node:path';
+import { FragmentedMp4Parser } from "./fragmented-mp4-parser.js";
+import { getFfmpegCapabilities, } from "./ffmpeg-capabilities.js";
+import { getHksvPerformanceMode, getHksvRecordingResolutions, selectHksvVideoCodec, } from "./hksv-options.js";
+import { hksvRecordingQueue } from "./hksv-work-queue.js";
 const __dirname = new URL('.', import.meta.url).pathname, mediaDirectory = path.join(__dirname.replace(/\/lib\/?$/, ''), 'media'), readFileAsync = promisify(readFile), cameraOfflinePath = path.join(mediaDirectory, 'camera-offline.jpg'), snapshotsBlockedPath = path.join(mediaDirectory, 'snapshots-blocked.jpg');
 function getDurationSeconds(start) {
     return (Date.now() - start) / 1000;
@@ -29,30 +33,6 @@ function getIntegerConfigValue(value, defaultValue, min, max) {
     }
     return Math.min(Math.max(Math.round(value), min), max);
 }
-function* parseMp4Boxes(data) {
-    let offset = 0;
-    while (offset + 8 <= data.length) {
-        const shortLength = data.readUInt32BE(offset);
-        let boxLength = shortLength;
-        let headerLength = 8;
-        if (shortLength === 1) {
-            if (offset + 16 > data.length) {
-                break;
-            }
-            boxLength = Number(data.readBigUInt64BE(offset + 8));
-            headerLength = 16;
-        }
-        else if (shortLength === 0) {
-            break;
-        }
-        if (boxLength < headerLength || offset + boxLength > data.length) {
-            break;
-        }
-        const box = data.subarray(offset, offset + boxLength), type = box.subarray(4, 8).toString('ascii');
-        yield { type, box };
-        offset += boxLength;
-    }
-}
 class StreamingSessionWrapper {
     audioSsrc = hap.CameraController.generateSynchronisationSource();
     videoSsrc = hap.CameraController.generateSynchronisationSource();
@@ -269,6 +249,7 @@ export class CameraSource {
     constructor(ringCamera, config) {
         this.ringCamera = ringCamera;
         this.config = config;
+        hksvRecordingQueue.setConcurrency(getIntegerConfigValue(config.hksvMaxConcurrentRecordings, getHksvPerformanceMode(config) === 'rpi' ? 1 : 2, 1, 4));
         const enableHksv = config.enableHksv && !(config.disableHksvOnBattery && ringCamera.hasBattery);
         const controllerOptions = {
             cameraStreamCount: enableHksv ? 1 : 10,
@@ -340,12 +321,7 @@ export class CameraSource {
                                 2 /* H264Level.LEVEL4_0 */,
                             ],
                         },
-                        resolutions: [
-                            [1920, 1080, 30],
-                            [1280, 720, 30],
-                            [640, 480, 30],
-                            [320, 240, 15],
-                        ],
+                        resolutions: getHksvRecordingResolutions(config),
                     },
                     audio: {
                         codecs: {
@@ -366,26 +342,33 @@ export class CameraSource {
         }
         this.controller = new hap.CameraController(controllerOptions);
     }
-    getHksvVideoArguments() {
-        const { cameraVideoCodec = 'libx264', hksvVideoCrf, hksvVideoPreset = 'veryfast', } = this.config, bitrateKbps = getIntegerConfigValue(this.config.hksvVideoBitrateKbps, 3000, 256, 12000), maxBitrateKbps = getIntegerConfigValue(this.config.hksvVideoMaxBitrateKbps, bitrateKbps * 2, bitrateKbps, 20000), bufferSizeKbps = getIntegerConfigValue(this.config.hksvVideoBufferSizeKbps, maxBitrateKbps * 2, maxBitrateKbps, 40000), keyframeInterval = getIntegerConfigValue(this.config.hksvVideoKeyframeInterval, 30, 5, 240), videoArguments = [
-            '-vcodec',
-            cameraVideoCodec,
-            '-b:v',
-            `${bitrateKbps}k`,
-            '-maxrate',
-            `${maxBitrateKbps}k`,
-            '-bufsize',
-            `${bufferSizeKbps}k`,
-            '-pix_fmt',
-            'yuv420p',
-            '-profile:v',
-            'baseline',
-            '-level:v',
-            '3.1',
-            '-g',
-            `${keyframeInterval}`,
-        ];
-        if (cameraVideoCodec === 'libx264') {
+    getHksvVideoArguments(capabilities) {
+        const { cameraVideoCodec, hksvVideoCrf, hksvVideoPreset = getHksvPerformanceMode(this.config) === 'rpi'
+            ? 'ultrafast'
+            : 'veryfast', } = this.config, selectedCodec = selectHksvVideoCodec(cameraVideoCodec, capabilities, this.config), bitrateKbps = getIntegerConfigValue(this.config.hksvVideoBitrateKbps, getHksvPerformanceMode(this.config) === 'rpi' ? 1000 : 3000, 256, 12000), maxBitrateKbps = getIntegerConfigValue(this.config.hksvVideoMaxBitrateKbps, bitrateKbps * 2, bitrateKbps, 20000), bufferSizeKbps = getIntegerConfigValue(this.config.hksvVideoBufferSizeKbps, maxBitrateKbps * 2, maxBitrateKbps, 40000), keyframeInterval = getIntegerConfigValue(this.config.hksvVideoKeyframeInterval, 30, 5, 240), videoArguments = selectedCodec === 'copy'
+            ? ['-vcodec', 'copy']
+            : [
+                '-vcodec',
+                selectedCodec,
+                '-b:v',
+                `${bitrateKbps}k`,
+                '-maxrate',
+                `${maxBitrateKbps}k`,
+                '-bufsize',
+                `${bufferSizeKbps}k`,
+                '-pix_fmt',
+                'yuv420p',
+                '-profile:v',
+                'baseline',
+                '-level:v',
+                '3.1',
+                '-g',
+                `${keyframeInterval}`,
+            ];
+        if (selectedCodec === 'copy') {
+            return videoArguments;
+        }
+        if (selectedCodec === 'libx264') {
             videoArguments.push('-preset', hksvVideoPreset, '-tune', 'zerolatency', '-keyint_min', `${keyframeInterval}`, '-sc_threshold', '0');
             if (Number.isFinite(hksvVideoCrf)) {
                 videoArguments.push('-crf', `${getIntegerConfigValue(hksvVideoCrf, 23, 18, 35)}`);
@@ -434,7 +417,7 @@ export class CameraSource {
             this.cachedSnapshot = undefined;
             logDebug(`Failed to cache snapshot for ${this.ringCamera.name} (${getDurationSeconds(start)}s), The camera currently reports that it is ${this.ringCamera.isOffline ? 'offline' : 'online'}`);
             // log additioanl snapshot error message if one is present
-            if (e.message && e.message.includes('Snapshot')) {
+            if (e.message.includes('Snapshot')) {
                 logDebug(e.message);
             }
         }
@@ -547,15 +530,15 @@ export class CameraSource {
         }
         this.closedRecordingStreams.delete(streamId);
         const packetQueue = [];
-        let waitForPacket, pendingData = Buffer.alloc(0), initBoxes = [], initSent = false, fragmentBoxes = [], closed = false;
-        const fragmentLengthMs = this.recordingConfiguration.mediaContainerConfiguration.fragmentLength;
-        const wake = () => {
+        let waitForPacket, queuedBytes = 0, closed = false;
+        const fragmentLengthMs = this.recordingConfiguration.mediaContainerConfiguration.fragmentLength, parser = new FragmentedMp4Parser(), maxQueuedBytes = getIntegerConfigValue(this.config.hksvMaxQueuedBytes, getHksvPerformanceMode(this.config) === 'rpi'
+            ? 6 * 1024 * 1024
+            : 16 * 1024 * 1024, 1024 * 1024, 64 * 1024 * 1024), start = Date.now();
+        function wake() {
             waitForPacket?.();
             waitForPacket = undefined;
-        }, enqueuePacket = (packet) => {
-            packetQueue.push(packet);
-            wake();
-        }, closeSession = () => {
+        }
+        const closeSession = () => {
             if (closed) {
                 return;
             }
@@ -563,13 +546,26 @@ export class CameraSource {
             this.closedRecordingStreams.add(streamId);
             this.activeRecordingSessions.delete(streamId);
             wake();
+        }, enqueuePacket = (packet) => {
+            queuedBytes += packet.data.length;
+            if (queuedBytes > maxQueuedBytes) {
+                logInfo(`HKSV recording queue limit reached for ${this.ringCamera.name} (streamId=${streamId}, queuedBytes=${queuedBytes}, maxQueuedBytes=${maxQueuedBytes})`);
+                closeSession();
+                return;
+            }
+            packetQueue.push(packet);
+            wake();
         };
         this.recordingWaiters.set(streamId, closeSession);
         this.activeRecordingSessions.set(streamId, closeSession);
         let liveCall;
         let keyFrameTimer;
         let maxRecordingTimer;
+        let releaseQueueSlot;
         try {
+            releaseQueueSlot = await hksvRecordingQueue.acquire();
+            const capabilities = await getFfmpegCapabilities(), videoArguments = this.getHksvVideoArguments(capabilities), selectedVideoCodec = String(videoArguments[1]);
+            logInfo(`Starting HKSV recording pipeline for ${this.ringCamera.name} (streamId=${streamId}, mode=${getHksvPerformanceMode(this.config)}, video=${selectedVideoCodec})`);
             liveCall = await this.ringCamera.startLiveCall();
             liveCall.onCallEnded.pipe(take(1)).subscribe(() => {
                 closeSession();
@@ -582,7 +578,7 @@ export class CameraSource {
                 }, maxRecordingSeconds * 1000);
             }
             await liveCall.startTranscoding({
-                video: this.getHksvVideoArguments(),
+                video: videoArguments,
                 output: [
                     '-movflags',
                     'frag_keyframe+empty_moov+default_base_moof',
@@ -600,50 +596,15 @@ export class CameraSource {
                     if (closed) {
                         return;
                     }
-                    pendingData = Buffer.concat([pendingData, data]);
-                    let consumed = 0;
-                    for (const { type, box } of parseMp4Boxes(pendingData)) {
-                        consumed += box.length;
-                        if (!initSent) {
-                            initBoxes.push(box);
-                            if (type === 'moov') {
-                                enqueuePacket({
-                                    data: Buffer.concat(initBoxes),
-                                    isLast: false,
-                                });
-                                initBoxes = [];
-                                initSent = true;
-                            }
-                            continue;
-                        }
-                        if (type === 'styp') {
-                            fragmentBoxes = [box];
-                            continue;
-                        }
-                        if (type === 'moof') {
-                            fragmentBoxes = fragmentBoxes.length ? [...fragmentBoxes, box] : [box];
-                            continue;
-                        }
-                        if (!fragmentBoxes.length) {
-                            continue;
-                        }
-                        fragmentBoxes.push(box);
-                        if (type === 'mdat') {
-                            enqueuePacket({
-                                data: Buffer.concat(fragmentBoxes),
-                                isLast: false,
-                            });
-                            fragmentBoxes = [];
-                        }
-                    }
-                    if (consumed > 0) {
-                        pendingData = pendingData.subarray(consumed);
+                    for (const packet of parser.append(data)) {
+                        enqueuePacket(packet);
                     }
                 },
             });
             liveCall.requestKeyFrame();
             keyFrameTimer = setInterval(() => {
-                if (closed || initSent) {
+                if (closed ||
+                    (selectedVideoCodec !== 'copy' && parser.hasInitializationSegment)) {
                     if (keyFrameTimer) {
                         clearInterval(keyFrameTimer);
                         keyFrameTimer = undefined;
@@ -651,10 +612,12 @@ export class CameraSource {
                     return;
                 }
                 liveCall?.requestKeyFrame();
-            }, 2000);
+            }, selectedVideoCodec === 'copy' ? Math.max(fragmentLengthMs, 1000) : 2000);
             while (!closed) {
                 if (packetQueue.length) {
-                    yield packetQueue.shift();
+                    const packet = packetQueue.shift();
+                    queuedBytes -= packet.data.length;
+                    yield packet;
                     continue;
                 }
                 await new Promise((resolve) => {
@@ -669,6 +632,7 @@ export class CameraSource {
             closeSession();
         }
         finally {
+            logInfo(`HKSV recording pipeline ended for ${this.ringCamera.name} (streamId=${streamId}, duration=${getDurationSeconds(start)}s, queuedBytes=${queuedBytes})`);
             this.recordingWaiters.delete(streamId);
             this.activeRecordingSessions.delete(streamId);
             if (keyFrameTimer) {
@@ -680,6 +644,7 @@ export class CameraSource {
             if (liveCall) {
                 liveCall.stop();
             }
+            releaseQueueSlot?.();
         }
     }
     closeRecordingStream(streamId, reason) {

package/lib/ffmpeg-capabilities.js

@@ -0,0 +1,46 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { getFfmpegPath } from 'ring-client-api/ffmpeg';
+import { logDebug } from 'ring-client-api/util';
+const execFileAsync = promisify(execFile);
+let cachedCapabilities;
+function parseNames(output) {
+    return new Set(output
+        .split(/\s+/)
+        .map((entry) => entry.trim())
+        .filter(Boolean));
+}
+async function getFfmpegOutput(args) {
+    const ffmpegPath = getFfmpegPath() || 'ffmpeg';
+    try {
+        const { stdout, stderr } = await execFileAsync(ffmpegPath, args, {
+            maxBuffer: 1024 * 1024,
+        });
+        return `${stdout}\n${stderr}`;
+    }
+    catch (e) {
+        return `${e.stdout ?? ''}\n${e.stderr ?? ''}`;
+    }
+}
+async function loadCapabilities() {
+    const [encodersOutput, hwaccelsOutput] = await Promise.all([
+        getFfmpegOutput(['-hide_banner', '-encoders']),
+        getFfmpegOutput(['-hide_banner', '-hwaccels']),
+    ]);
+    const capabilities = {
+        encoders: parseNames(encodersOutput),
+        hwaccels: parseNames(hwaccelsOutput),
+    };
+    logDebug(`FFmpeg HKSV capabilities: encoders=${[
+        'h264_v4l2m2m',
+        'h264_videotoolbox',
+        'libx264',
+    ]
+        .filter((encoder) => capabilities.encoders.has(encoder))
+        .join(',') || 'none detected'}`);
+    return capabilities;
+}
+export function getFfmpegCapabilities() {
+    cachedCapabilities ??= loadCapabilities();
+    return cachedCapabilities;
+}

package/lib/fragmented-mp4-parser.js

@@ -0,0 +1,80 @@
+function* parseMp4Boxes(data) {
+    let offset = 0;
+    while (offset + 8 <= data.length) {
+        const shortLength = data.readUInt32BE(offset);
+        let boxLength = shortLength;
+        let headerLength = 8;
+        if (shortLength === 1) {
+            if (offset + 16 > data.length) {
+                break;
+            }
+            boxLength = Number(data.readBigUInt64BE(offset + 8));
+            headerLength = 16;
+        }
+        else if (shortLength === 0) {
+            break;
+        }
+        if (boxLength < headerLength || offset + boxLength > data.length) {
+            break;
+        }
+        const box = data.subarray(offset, offset + boxLength), type = box.subarray(4, 8).toString('ascii');
+        yield { type, box };
+        offset += boxLength;
+    }
+}
+export class FragmentedMp4Parser {
+    pendingData = Buffer.alloc(0);
+    initBoxes = [];
+    initSent = false;
+    fragmentBoxes = [];
+    get hasInitializationSegment() {
+        return this.initSent;
+    }
+    append(data) {
+        const packets = [];
+        this.pendingData = this.pendingData.length
+            ? Buffer.concat([this.pendingData, data])
+            : data;
+        let consumed = 0;
+        for (const { type, box } of parseMp4Boxes(this.pendingData)) {
+            consumed += box.length;
+            if (!this.initSent) {
+                this.initBoxes.push(box);
+                if (type === 'moov') {
+                    packets.push({
+                        data: Buffer.concat(this.initBoxes),
+                        isLast: false,
+                    });
+                    this.initBoxes = [];
+                    this.initSent = true;
+                }
+                continue;
+            }
+            if (type === 'styp') {
+                this.fragmentBoxes = [box];
+                continue;
+            }
+            if (type === 'moof') {
+                this.fragmentBoxes = this.fragmentBoxes.length
+                    ? [...this.fragmentBoxes, box]
+                    : [box];
+                continue;
+            }
+            if (!this.fragmentBoxes.length) {
+                continue;
+            }
+            this.fragmentBoxes.push(box);
+            if (type === 'mdat') {
+                packets.push({
+                    data: Buffer.concat(this.fragmentBoxes),
+                    isLast: false,
+                });
+                this.fragmentBoxes = [];
+            }
+        }
+        if (consumed > 0) {
+            this.pendingData = this.pendingData.subarray(consumed);
+        }
+        return packets;
+    }
+}

package/lib/hksv-options.js

@@ -0,0 +1,35 @@
+export function getHksvPerformanceMode(config) {
+    return config.hksvPerformanceMode ?? 'balanced';
+}
+export function getHksvRecordingResolutions(config) {
+    if (getHksvPerformanceMode(config) === 'rpi') {
+        return [
+            [1280, 720, 30],
+            [640, 480, 30],
+            [640, 360, 30],
+            [320, 240, 15],
+        ];
+    }
+    return [
+        [1920, 1080, 30],
+        [1280, 720, 30],
+        [640, 480, 30],
+        [320, 240, 15],
+    ];
+}
+export function selectHksvVideoCodec(configuredCodec, capabilities, config) {
+    const codec = configuredCodec ?? 'auto';
+    if (codec !== 'auto') {
+        return codec;
+    }
+    if (getHksvPerformanceMode(config) === 'rpi') {
+        return 'copy';
+    }
+    if (capabilities?.encoders.has('h264_v4l2m2m')) {
+        return 'h264_v4l2m2m';
+    }
+    if (capabilities?.encoders.has('h264_videotoolbox')) {
+        return 'h264_videotoolbox';
+    }
+    return 'libx264';
+}

package/lib/hksv-work-queue.js

@@ -0,0 +1,33 @@
+class WorkQueue {
+    active = 0;
+    waiters = [];
+    concurrency;
+    constructor(concurrency) {
+        this.concurrency = concurrency;
+    }
+    setConcurrency(concurrency) {
+        this.concurrency = Math.max(1, Math.floor(concurrency));
+        this.drain();
+    }
+    async acquire() {
+        if (this.active < this.concurrency) {
+            this.active++;
+            return () => this.release();
+        }
+        await new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+        this.active++;
+        return () => this.release();
+    }
+    release() {
+        this.active = Math.max(0, this.active - 1);
+        this.drain();
+    }
+    drain() {
+        while (this.active < this.concurrency && this.waiters.length) {
+            this.waiters.shift()?.();
+        }
+    }
+}
+export const hksvRecordingQueue = new WorkQueue(1);

package/lib/intercom.js

@@ -1,125 +1,7 @@
-import { RingCamera } from 'ring-client-api';
 import { hap } from "./hap.js";
 import { BaseDataAccessory } from "./base-data-accessory.js";
 import { logError, logInfo } from 'ring-client-api/util';
-import { filter, map, share, switchMap, throttleTime } from 'rxjs/operators';
-import { interval, merge, Subject } from 'rxjs';
-import { CameraSource } from "./camera-source.js";
-/**
- * Creates a RingCamera-compatible proxy for a Ring Intercom Video device.
- * Ring Intercom Video is classified as RingIntercom by ring-client-api but has a
- * real camera. We use Object.create(RingCamera.prototype) so that startLiveCall()
- * and createStreamingConnection() are inherited and work with the intercom's
- * restClient and device id (Ring's signalling server uses the same doorbot_id
- * scheme for video intercoms as for cameras).
- */
-function createIntercomVideoProxy(device) {
-    const proxy = Object.create(RingCamera.prototype);
-    const defineValue = (key, value) => Object.defineProperty(proxy, key, {
-        value,
-        writable: true,
-        configurable: true,
-        enumerable: true,
-    });
-    const defineGetter = (key, get) => Object.defineProperty(proxy, key, {
-        get,
-        configurable: true,
-        enumerable: true,
-    });
-    defineValue('id', device.id);
-    defineGetter('name', () => device.name);
-    defineGetter('deviceType', () => device.deviceType);
-    defineGetter('data', () => ({
-        ...device.data,
-        kind: device.deviceType,
-        device_id: String(device.id),
-        metadata: device.data.metadata ?? {},
-        settings: {
-            live_view_disabled: false,
-            motion_detection_enabled: true,
-            ...device.data.settings,
-        },
-    }));
-    // restClient is technically private in TypeScript but public in compiled JS
-    defineValue('restClient', device.restClient);
-    defineGetter('isRingEdgeEnabled', () => false);
-    defineGetter('hasBattery', () => device.batteryLevel !== null);
-    defineGetter('isOffline', () => device.isOffline);
-    defineGetter('snapshotsAreBlocked', () => false);
-    defineGetter('canTakeSnapshotWhileRecording', () => false);
-    defineGetter('latestNotificationSnapshotUuid', () => undefined);
-    defineValue('onNewNotification', new Subject());
-    defineValue('onMotionDetected', new Subject());
-    defineValue('onDoorbellPressed', device.onDing);
-    defineValue('onBatteryLevel', device.onBatteryLevel);
-    defineValue('onInHomeDoorbellStatus', new Subject());
-    defineGetter('hasLowBattery', () => Boolean(device.data.alerts?.battery === 'low'));
-    defineGetter('isCharging', () => false);
-    defineValue('isDoorbot', true);
-    defineValue('hasLight', false);
-    defineValue('hasSiren', false);
-    defineValue('hasInHomeDoorbell', false);
-    defineValue('model', 'Ring Intercom Video');
-    defineValue('snapshotLifeTime', 55000); // camera stays active ~1 min after a ring
-    // Pre-warm support: start the WebRTC call the moment a ding is detected so
-    // the camera is already streaming when HKSV requests the recording.
-    let preWarmedCall = null;
-    let preWarmCleanup = null;
-    let lastSnapshotAt = 0;
-    const realStartLiveCall = () => RingCamera.prototype.startLiveCall.call(proxy);
-    defineValue('startLiveCall', () => {
-        if (preWarmedCall) {
-            const call = preWarmedCall;
-            preWarmedCall = null;
-            if (preWarmCleanup) {
-                clearTimeout(preWarmCleanup);
-                preWarmCleanup = null;
-            }
-            logInfo(`${device.name}: using pre-warmed camera session for recording`);
-            return call;
-        }
-        return realStartLiveCall();
-    });
-    defineValue('preWarmCamera', () => {
-        if (preWarmedCall)
-            return;
-        logInfo(`${device.name}: pre-warming camera connection`);
-        preWarmedCall = realStartLiveCall();
-        // Clean up if HKSV doesn't claim it within 20 seconds
-        preWarmCleanup = setTimeout(async () => {
-            if (preWarmedCall) {
-                try {
-                    const session = await preWarmedCall;
-                    session.stop();
-                }
-                catch (e) {
-                    logError(`Failed to stop pre-warmed camera session for ${device.name}`);
-                    logError(e);
-                }
-                finally {
-                    preWarmedCall = null;
-                    preWarmCleanup = null;
-                }
-            }
-        }, 20000);
-    });
-    // Override getSnapshot: intercom uses the same doorbots snapshot endpoint as cameras.
-    defineGetter('hasSnapshotWithinLifetime', () => Date.now() - lastSnapshotAt < proxy.snapshotLifeTime);
-    defineValue('getSnapshot', async (_options) => {
-        try {
-            const snapshot = await device.restClient.request({
-                url: device.doorbotUrl('snapshot'),
-                responseType: 'buffer',
-            });
-            lastSnapshotAt = Date.now();
-            return snapshot;
-        }
-        catch {
-            throw new Error(`Snapshot not available for ${device.name}`);
-        }
-    });
-    return proxy;
-}
+import { map, throttleTime } from 'rxjs/operators';
 export class Intercom extends BaseDataAccessory {
     unlocking = false;
     unlockTimeout;
@@ -131,64 +13,7 @@ export class Intercom extends BaseDataAccessory {
         this.device = device;
         this.accessory = accessory;
         this.config = config;
-        const { Characteristic, Service } = hap, isIntercomVideo = device.deviceType === 'intercom_handset_video';
-        // Set up camera streaming for Ring Intercom Video before other services
-        let intercomVideoProxy = null;
-        if (isIntercomVideo) {
-            const cameraProxy = createIntercomVideoProxy(device);
-            intercomVideoProxy = cameraProxy;
-            const cameraSource = new CameraSource(cameraProxy, config);
-            accessory.configureController(cameraSource.controller);
-            this.registerCharacteristic({
-                characteristicType: Characteristic.Mute,
-                serviceType: Service.Microphone,
-                getValue: () => false,
-            });
-            this.registerCharacteristic({
-                characteristicType: Characteristic.Mute,
-                serviceType: Service.Speaker,
-                getValue: () => false,
-            });
-            logInfo(`Camera streaming enabled for Ring Intercom Video: ${device.name}`);
-        }
-        const lockService = this.getService(Service.LockMechanism), { LockCurrentState, LockTargetState, ProgrammableSwitchEvent } = Characteristic, 
-        // Ring Intercom Video ding events may arrive as camera-style FCM push
-        // notifications (different category than RingIntercom.onDing expects),
-        // so onDing never fires. Poll Ring's active-dings endpoint as a reliable
-        // fallback — it reflects the current ring in real time (unlike the history
-        // endpoint which can lag by ~60 seconds).
-        onDingDetected = (() => {
-            if (!isIntercomVideo) {
-                return device.onDing.pipe(share());
-            }
-            let lastDingId;
-            const polled = interval(3000).pipe(switchMap(async () => {
-                try {
-                    const active = await device.restClient.request({
-                        url: 'https://api.ring.com/clients_api/dings/active',
-                    });
-                    return Array.isArray(active) ? active : [];
-                }
-                catch {
-                    return [];
-                }
-            }), filter((active) => {
-                const ding = active.find((d) => String(d.doorbot_id) === String(device.id) &&
-                    d.kind === 'ding');
-                if (!ding)
-                    return false;
-                if (String(ding.id) === lastDingId)
-                    return false;
-                lastDingId = String(ding.id);
-                return true;
-            }), map(() => undefined));
-            // share() makes this hot: one polling interval, one lastDingId,
-            // emission fans out to all subscribers that rely on ding events.
-            return merge(device.onDing, polled).pipe(throttleTime(3000), share());
-        })(), onDoorbellPressed = onDingDetected.pipe(throttleTime(15000), map(() => {
-            logInfo(`Doorbell pressed on ${device.name} — sending HomeKit event`);
-            return ProgrammableSwitchEvent.SINGLE_PRESS;
-        })), syncLockState = () => {
+        const { Characteristic, Service } = hap, lockService = this.getService(Service.LockMechanism), { LockCurrentState, LockTargetState, ProgrammableSwitchEvent } = Characteristic, programableSwitchService = this.getService(Service.StatelessProgrammableSwitch), onDoorbellPressed = device.onDing.pipe(throttleTime(15000), map(() => ProgrammableSwitchEvent.SINGLE_PRESS)), syncLockState = () => {
             const state = this.getLockState();
             lockService
                 .getCharacteristic(Characteristic.LockCurrentState)
@@ -243,42 +68,25 @@ export class Intercom extends BaseDataAccessory {
                 }
             },
         });
-        // For audio-only intercom the lock is the main function; for video intercom
-        // the camera controller owns the primary-service role so HomeKit routes
-        // doorbell events (and HomePod chimes) correctly.
-        if (!isIntercomVideo) {
-            lockService.setPrimaryService(true);
-        }
-        // Pre-warm the camera WebRTC connection on every ding so HKSV recording
-        // gets live video instead of black frames.
-        if (intercomVideoProxy) {
-            const proxy = intercomVideoProxy;
-            onDingDetected.subscribe(() => {
-                ;
-                proxy.preWarmCamera?.();
-            });
-        }
+        lockService.setPrimaryService(true);
         // Doorbell Service
         this.registerObservableCharacteristic({
             characteristicType: ProgrammableSwitchEvent,
             serviceType: Service.Doorbell,
             onValue: onDoorbellPressed,
         });
-        // Programmable Switch Service — only for audio-only intercom; the video
-        // variant already exposes Service.Doorbell which covers this.
-        if (!isIntercomVideo) {
-            const programableSwitchService = this.getService(Service.StatelessProgrammableSwitch);
-            this.registerObservableCharacteristic({
-                characteristicType: ProgrammableSwitchEvent,
-                serviceType: programableSwitchService,
-                onValue: onDoorbellPressed,
-            });
-            programableSwitchService
-                .getCharacteristic(ProgrammableSwitchEvent)
-                .setProps({
-                maxValue: ProgrammableSwitchEvent.SINGLE_PRESS,
-            });
-        }
+        // Programmable Switch Service
+        this.registerObservableCharacteristic({
+            characteristicType: ProgrammableSwitchEvent,
+            serviceType: programableSwitchService,
+            onValue: onDoorbellPressed,
+        });
+        // Hide long and double press events by setting max value
+        programableSwitchService
+            .getCharacteristic(ProgrammableSwitchEvent)
+            .setProps({
+            maxValue: ProgrammableSwitchEvent.SINGLE_PRESS,
+        });
         // Battery Service
         if (device.batteryLevel !== null) {
             this.registerObservableCharacteristic({
@@ -299,7 +107,7 @@ export class Intercom extends BaseDataAccessory {
         this.registerCharacteristic({
             characteristicType: Characteristic.Model,
             serviceType: Service.AccessoryInformation,
-            getValue: () => isIntercomVideo ? 'Ring Intercom Video' : 'Ring Intercom',
+            getValue: () => 'Intercom Handset Audio',
         });
         this.registerCharacteristic({
             characteristicType: Characteristic.SerialNumber,

package/lib/ring-platform.js

@@ -170,17 +170,10 @@ export class RingPlatform {
         });
         await Promise.all(locations.map(async (location) => {
             const devices = await location.getDevices(), { cameras, chimes, intercoms } = location, allDevices = [...devices, ...cameras, ...chimes, ...intercoms], securityPanel = devices.find((x) => x.deviceType === RingDeviceType.SecurityPanel), debugPrefix = debug ? 'TEST ' : '', hapDevices = allDevices.map((device) => {
-                const isCamera = device instanceof RingCamera, isIntercomVideo = device instanceof RingIntercom &&
-                    device.deviceType === 'intercom_handset_video', cameraIdentitySalt = isCamera && config.externalCameraIdSalt
+                const isCamera = device instanceof RingCamera, cameraIdentitySalt = isCamera && config.externalCameraIdSalt
                     ? `-${config.externalCameraIdSalt}`
-                    : '', 
-                // 'camera' forces bridged cameras from old plugin version to be seen as "stale"
-                // 'intercam' gives Ring Intercom Video a distinct external-accessory UUID
-                cameraIdDifferentiator = isCamera
-                    ? 'camera'
-                    : isIntercomVideo
-                        ? 'intercam'
-                        : '', AccessoryClass = (device instanceof RingCamera
+                    : '', cameraIdDifferentiator = isCamera ? 'camera' : '', // this forces bridged cameras from old version of the plugin to be seen as "stale"
+                AccessoryClass = (device instanceof RingCamera
                     ? Camera
                     : device instanceof RingChime
                         ? Chime
@@ -191,7 +184,6 @@ export class RingPlatform {
                     deviceType: device.deviceType,
                     device: device,
                     isCamera,
-                    isIntercomVideo,
                     id: device.id.toString() +
                         cameraIdDifferentiator +
                         cameraIdentitySalt +
@@ -207,7 +199,6 @@ export class RingPlatform {
                     deviceType: securityPanel.deviceType,
                     device: securityPanel,
                     isCamera: false,
-                    isIntercomVideo: false,
                     id: securityPanel.id.toString() + 'panic' + accessoryIdSuffix,
                     name: 'Panic Buttons' + accessoryNameSuffix,
                     AccessoryClass: PanicButtons,
@@ -219,14 +210,13 @@ export class RingPlatform {
                     deviceType: 'location.mode',
                     device: location,
                     isCamera: false,
-                    isIntercomVideo: false,
                     id: location.id + 'mode' + accessoryIdSuffix,
                     name: location.name + ' Mode' + accessoryNameSuffix,
                     AccessoryClass: LocationModeSwitch,
                 });
             }
             logInfo(`Configuring ${cameras.length} cameras and ${hapDevices.length} devices for location "${location.name}" - locationId: ${location.id}`);
-            hapDevices.forEach(({ deviceType, device, isCamera, isIntercomVideo, id, name, AccessoryClass, }) => {
+            hapDevices.forEach(({ deviceType, device, isCamera, id, name, AccessoryClass }) => {
                 const uuid = hap.uuid.generate(debugPrefix + id), displayName = debugPrefix + name;
                 if (!AccessoryClass ||
                     (config.hideLightGroups &&
@@ -247,20 +237,13 @@ export class RingPlatform {
                     delete this.homebridgeAccessories[uuid];
                 }
                 const createHomebridgeAccessory = () => {
-                    const category = isCamera
+                    const accessory = new api.platformAccessory(displayName, uuid, isCamera
                         ? 17 /* hap.Categories.CAMERA */
-                        : isIntercomVideo
-                            ? 18 /* hap.Categories.VIDEO_DOORBELL */
-                            : 11 /* hap.Categories.SECURITY_SYSTEM */;
-                    const accessory = new api.platformAccessory(displayName, uuid, category);
+                        : 11 /* hap.Categories.SECURITY_SYSTEM */);
                     if (isCamera) {
                         logInfo(`Configured camera ${uuid} ${deviceType} ${displayName}`);
                         externalAccessories.push(accessory);
                     }
-                    else if (isIntercomVideo) {
-                        logInfo(`Configured Ring Intercom Video ${uuid} ${deviceType} ${displayName}`);
-                        externalAccessories.push(accessory);
-                    }
                     else {
                         logInfo(`Adding new accessory ${uuid} ${deviceType} ${displayName}`);
                         platformAccessories.push(accessory);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ring-hksv",
   "displayName": "Homebridge Ring HKSV",
-  "version": "14.3.6",
+  "version": "14.3.8",
   "description": "Homebridge plugin for Ring devices with HomeKit Secure Video support",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,6 +17,7 @@
   "dependencies": {
     "@homebridge/camera-utils": "^3.0.0",
     "@homebridge/plugin-ui-utils": "^2.1.2",
+    "homebridge-config-ui-x": "^5.24.0",
     "ring-client-api": "14.3.0",
     "werift": "0.22.4"
   },
@@ -26,12 +27,12 @@
     "concurrently": "^9.2.1",
     "eslint": "9.39.2",
     "globals": "17.3.0",
-    "homebridge": "1.11.1",
+    "homebridge": "^2.1.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.54.0"
   },
   "engines": {
-    "node": "^20 || ^22 || ^24",
+    "node": "^20 || ^22 || ^24 || ^26",
     "homebridge": ">=1.4.0 || ^2.0.0-beta.0"
   },
   "homebridge": {
@@ -84,5 +85,9 @@
     "category-video",
     "category-hubs",
     "category-outdoor"
-  ]
+  ],
+  "allowScripts": {
+    "ffmpeg-for-homebridge@2.2.1": true,
+    "protobufjs@7.6.4": true
+  }
 }