homebridge-ring-hksv 14.3.5 → 14.3.7

package/README.md

@@ -31,6 +31,9 @@ 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 |
+| `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`) |
 | `hideDoorbellSwitch` / `hideCameraMotionSensor` / `hideCameraSirenSwitch` | Hides specific HomeKit-exposed services |
@@ -86,6 +89,12 @@ HKSV support is experimental and actively evolving. Behavior may vary by camera
 I currently am able to run 3 cameras with HKSV enabled on a Homebridge instance ran on a M4 Mac Mini 32GB of RAM.
 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,
+`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.
+
 ### Minimum specifications for HKSV: 
 [TBD - will be added as more users test and report their setups]
 

package/config.schema.json

@@ -53,6 +53,86 @@
         "maximum": 300,
         "description": "Optional safety cap for a single HKSV recording stream duration."
       },
+      "hksvVideoBitrateKbps": {
+        "title": "HKSV Video Bitrate (kbps)",
+        "type": "integer",
+        "minimum": 256,
+        "maximum": 12000,
+        "default": 3000,
+        "description": "Target video bitrate for HKSV recording transcodes. Increase this first if fast motion becomes blocky or pixelated. 4000-6000 is a good starting range for wired cameras."
+      },
+      "hksvVideoMaxBitrateKbps": {
+        "title": "HKSV Max Video Bitrate (kbps)",
+        "type": "integer",
+        "minimum": 256,
+        "maximum": 20000,
+        "description": "Maximum burst bitrate for HKSV recording transcodes. Defaults to 2x the target bitrate. A practical starting range is 8000-12000 when target bitrate is 4000-6000."
+      },
+      "hksvVideoBufferSizeKbps": {
+        "title": "HKSV Video Buffer Size (kbps)",
+        "type": "integer",
+        "minimum": 256,
+        "maximum": 40000,
+        "description": "FFmpeg VBV buffer size for HKSV recording transcodes. Defaults to 2x the max video bitrate. Leave unset unless you are tuning bitrate stability."
+      },
+      "hksvVideoCrf": {
+        "title": "HKSV x264 Quality (CRF)",
+        "type": "integer",
+        "minimum": 18,
+        "maximum": 35,
+        "description": "Optional libx264 quality value. Lower values improve quality and use more bitrate/CPU. Try 20-23 if you stay on libx264. Ignored when using VideoToolbox."
+      },
+      "hksvVideoKeyframeInterval": {
+        "title": "HKSV Keyframe Interval",
+        "type": "integer",
+        "minimum": 5,
+        "maximum": 240,
+        "default": 30,
+        "description": "Maximum number of frames between video keyframes in HKSV recordings. 30 is the recommended default. Shorter intervals can improve fragmenting at the cost of bitrate."
+      },
+      "hksvVideoPreset": {
+        "title": "HKSV x264 Preset",
+        "type": "string",
+        "description": "libx264 speed/quality preset for HKSV recordings. veryfast is the recommended default. Move toward fast or medium for quality, or superfast for lower CPU. Ignored when using VideoToolbox.",
+        "oneOf": [
+          {
+            "title": "ultrafast",
+            "enum": ["ultrafast"]
+          },
+          {
+            "title": "superfast",
+            "enum": ["superfast"]
+          },
+          {
+            "title": "veryfast",
+            "enum": ["veryfast"]
+          },
+          {
+            "title": "faster",
+            "enum": ["faster"]
+          },
+          {
+            "title": "fast",
+            "enum": ["fast"]
+          },
+          {
+            "title": "medium",
+            "enum": ["medium"]
+          },
+          {
+            "title": "slow",
+            "enum": ["slow"]
+          },
+          {
+            "title": "slower",
+            "enum": ["slower"]
+          },
+          {
+            "title": "veryslow",
+            "enum": ["veryslow"]
+          }
+        ]
+      },
       "homeKitAccessoryTag": {
         "title": "HomeKit Accessory Tag",
         "type": "string",
@@ -61,7 +141,7 @@
       "cameraVideoCodec": {
         "title": "Camera Video Codec",
         "type": "string",
-        "description": "Preferred ffmpeg H.264 encoder for camera paths.",
+        "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.",
         "oneOf": [
           {
             "title": "h264_videotoolbox",
@@ -215,6 +295,12 @@
         "hksvPrebufferLengthMs",
         "hksvFragmentLengthMs",
         "hksvMaxRecordingSeconds",
+        "hksvVideoBitrateKbps",
+        "hksvVideoMaxBitrateKbps",
+        "hksvVideoBufferSizeKbps",
+        "hksvVideoCrf",
+        "hksvVideoKeyframeInterval",
+        "hksvVideoPreset",
         "homeKitAccessoryTag",
         "cameraVideoCodec",
         "hideLightGroups",

package/lib/camera-source.js

@@ -23,6 +23,12 @@ function getSessionConfig(srtpOptions) {
         profile: 1,
     };
 }
+function getIntegerConfigValue(value, defaultValue, min, max) {
+    if (!Number.isFinite(value)) {
+        return defaultValue;
+    }
+    return Math.min(Math.max(Math.round(value), min), max);
+}
 function* parseMp4Boxes(data) {
     let offset = 0;
     while (offset + 8 <= data.length) {
@@ -254,6 +260,7 @@ export class CameraSource {
     sessions = {};
     cachedSnapshot;
     ringCamera;
+    config;
     recordingActive = false;
     recordingConfiguration;
     closedRecordingStreams = new Set();
@@ -261,6 +268,7 @@ export class CameraSource {
     activeRecordingSessions = new Map();
     constructor(ringCamera, config) {
         this.ringCamera = ringCamera;
+        this.config = config;
         const enableHksv = config.enableHksv && !(config.disableHksvOnBattery && ringCamera.hasBattery);
         const controllerOptions = {
             cameraStreamCount: enableHksv ? 1 : 10,
@@ -358,6 +366,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') {
+            videoArguments.push('-preset', hksvVideoPreset, '-tune', 'zerolatency', '-keyint_min', `${keyframeInterval}`, '-sc_threshold', '0');
+            if (Number.isFinite(hksvVideoCrf)) {
+                videoArguments.push('-crf', `${getIntegerConfigValue(hksvVideoCrf, 23, 18, 35)}`);
+            }
+        }
+        return videoArguments;
+    }
     previousLoadSnapshotPromise;
     async loadSnapshot(imageUuid) {
         // cache a promise of the snapshot load
@@ -533,32 +568,21 @@ export class CameraSource {
         this.activeRecordingSessions.set(streamId, closeSession);
         let liveCall;
         let keyFrameTimer;
+        let maxRecordingTimer;
         try {
             liveCall = await this.ringCamera.startLiveCall();
             liveCall.onCallEnded.pipe(take(1)).subscribe(() => {
                 closeSession();
             });
+            const maxRecordingSeconds = getIntegerConfigValue(this.config.hksvMaxRecordingSeconds, 0, 0, 300);
+            if (maxRecordingSeconds) {
+                maxRecordingTimer = setTimeout(() => {
+                    logInfo(`HKSV recording stream reached max duration for ${this.ringCamera.name} (streamId=${streamId}, maxSeconds=${maxRecordingSeconds})`);
+                    closeSession();
+                }, maxRecordingSeconds * 1000);
+            }
             await liveCall.startTranscoding({
-                video: [
-                    '-vcodec',
-                    'libx264',
-                    '-preset',
-                    'veryfast',
-                    '-tune',
-                    'zerolatency',
-                    '-pix_fmt',
-                    'yuv420p',
-                    '-profile:v',
-                    'baseline',
-                    '-level:v',
-                    '3.1',
-                    '-g',
-                    '30',
-                    '-keyint_min',
-                    '30',
-                    '-sc_threshold',
-                    '0',
-                ],
+                video: this.getHksvVideoArguments(),
                 output: [
                     '-movflags',
                     'frag_keyframe+empty_moov+default_base_moof',
@@ -650,6 +674,9 @@ export class CameraSource {
             if (keyFrameTimer) {
                 clearInterval(keyFrameTimer);
             }
+            if (maxRecordingTimer) {
+                clearTimeout(maxRecordingTimer);
+            }
             if (liveCall) {
                 liveCall.stop();
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ring-hksv",
   "displayName": "Homebridge Ring HKSV",
-  "version": "14.3.5",
+  "version": "14.3.7",
   "description": "Homebridge plugin for Ring devices with HomeKit Secure Video support",
   "type": "module",
   "main": "./lib/index.js",