homebridge-ring-secure-video 1.0.0-beta.6 → 1.0.0-beta.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,47 @@
1
1
  # homebridge-ring-secure-video
2
2
 
3
+ ## 1.0.0-beta.7 (2026-11-14)
4
+
5
+ **Changes in behaviour to check after updating:**
6
+
7
+ - The flat recording settings are removed: `hksvPerformanceMode`, `cameraVideoCodec`,
8
+ `hksvVideoBitrateKbps`, `hksvVideoMaxBitrateKbps`, `hksvVideoBufferSizeKbps`, `hksvVideoCrf`,
9
+ `hksvVideoPreset`, `hksvVideoKeyframeInterval`, `hksvPrebufferLengthMs`,
10
+ `hksvFragmentLengthMs`, `hksvMaxRecordingSeconds`, `hksvMaxQueuedBytes` and
11
+ `hksvMaxConcurrentRecordings`. Recording is set up only in `media` ("Recording Settings" in
12
+ the plugin settings), which has each of them with the same allowed values
13
+ (`hksvPerformanceMode`'s `balanced`/`rpi`/`quality` become `media.profile`'s
14
+ `adaptive`/`lowPower`/`quality`); the README has a table of what replaces what. A removed
15
+ setting left in a config is ignored, with a warning at start naming it and its replacement:
16
+ move its value if needed, then delete it in the JSON editor. Configs last saved from the
17
+ settings form in beta.6 or earlier usually contain `hksvPerformanceMode` and
18
+ `hksvVideoKeyframeInterval` (the form filled them in), so expect those two warnings. Without `media.profile` the profile is `adaptive`, so a config that only had
19
+ `"hksvPerformanceMode": "rpi"` needs `"media": { "profile": "lowPower" }`.
20
+ - The recording log line says `profile=lowPower`, `adaptive` or `quality` instead of
21
+ `mode=rpi`, `balanced` or `quality`.
22
+
23
+ **Fixes** (from homebridge-ring 15.0.0-beta.0):
24
+
25
+ - A volume, brightness, dimmer or fan-speed change that Ring rejects no longer crashes
26
+ Homebridge (and with it the plugin's bridge); it is logged, and the value goes back to the last
27
+ level Ring reported, unless a newer change was sent meanwhile (dgreif/ring#1892).
28
+ - A Ring mode change (Home, Away, Disarmed) from HomeKit that Ring rejects no longer crashes
29
+ Homebridge; it is logged, and the target goes back to the mode Ring reports. A pending Home (Stay) target is no
30
+ longer overwritten by another mode report before Ring confirms it, and an older request
31
+ failing late no longer undoes a newer one (dgreif/ring#1871).
32
+ - A Ring token without its refresh token (from a sign-in response that couldn't be read, seen
33
+ with unsupported Node.js versions) is no longer saved over a working one (which made every
34
+ later start fail until signing in again) or used for reconnecting; the working token is kept,
35
+ and the error is logged once per run (the plugin's side of dgreif/ring#1886).
36
+
37
+ **Docs:**
38
+
39
+ - The settings form calls `media` "Recording Settings", "Enable HKSV" is no longer marked
40
+ experimental, and the settings' descriptions carry the Raspberry Pi advice, bitrate ranges,
41
+ verified codecs and each profile's defaults.
42
+ - README: a fuller disclaimer, and in "Origin and Attribution" the versions this started from
43
+ and where to report problems.
44
+
3
45
  ## 1.0.0-beta.6 (2026-11-13)
4
46
 
5
47
  **Changes in behaviour to check after updating:**
package/README.md CHANGED
@@ -17,7 +17,7 @@ Everything `homebridge-ring` exposes is here too (it is not a drop-in swap, thou
17
17
  platform names differ, so its accessories are new to HomeKit and are set up again), plus:
18
18
 
19
19
  - **HomeKit Secure Video recording** for Ring cameras and doorbells, with media profiles for small
20
- machines such as a Raspberry Pi (`media`, `hksvPerformanceMode`).
20
+ machines such as a Raspberry Pi (`media`).
21
21
  - **Instant motion notifications** with HKSV on: an optional separate motion sensor per camera
22
22
  (`cameraMotionNotificationSensor`), so the Home app notifies without waiting for clip analysis.
23
23
  - **Motion when Ring's push notifications fail**: motion from Ring's event history
@@ -37,34 +37,33 @@ platform names differ, so its accessories are new to HomeKit and are set up agai
37
37
 
38
38
  ## Origin and Attribution
39
39
 
40
- This project is based on Dusty Greif's original Ring Homebridge ecosystem:
40
+ This is an independent project, not a GitHub fork and not maintained by the authors it builds on:
41
41
 
42
- - Upstream plugin and API library: [dgreif/ring](https://github.com/dgreif/ring)
43
- (`homebridge-ring` and `ring-client-api`)
42
+ - [`homebridge-ring`](https://github.com/dgreif/ring) by Dusty Greif: this plugin's accessory code
43
+ started from homebridge-ring 14.3.0, and it uses
44
+ [`ring-client-api`](https://www.npmjs.com/package/ring-client-api) 14.3.0 from npm as a
45
+ dependency.
46
+ - [`homebridge-ring-hksv`](https://github.com/trinityhades/homebridge-ring-hksv) by trinityhades:
47
+ this plugin continues from its version 15.0.2 (HKSV recording pipeline, Ring Intercom Video).
44
48
 
45
- - HKSV fork: [trinityhades/homebridge-ring-hksv](https://github.com/trinityhades/homebridge-ring-hksv), whose history this repository continues
49
+ Changes since then are listed in [CHANGELOG.md](CHANGELOG.md). Thanks to Dusty Greif, trinityhades
50
+ and all upstream contributors.
46
51
 
47
- Big thanks to Dusty, trinityhades and all upstream contributors. This plugin reuses and extends that foundation.
52
+ **Please report problems with this plugin
53
+ [here](https://github.com/zmanuel1234/homebridge-ring-secure-video/issues), not to dgreif/ring or
54
+ trinityhades.**
48
55
 
49
56
  ## Important Plugin Options
50
57
 
51
58
  | Option | Purpose |
52
59
  | --- | --- |
53
- | `enableHksv` | Enables experimental HKSV support for eligible cameras; on by default, set `false` to turn it off |
60
+ | `enableHksv` | Enables HKSV recording for eligible cameras; on by default, set `false` to turn it off |
61
+ | `media` | Recording profile (`media.profile`: `adaptive`, `lowPower` or `quality`) and optional recording settings (`media.recording`); see [Media configuration](#media-configuration) and [Recording codecs](#recording-codecs) |
54
62
  | `enableCameraMotionHistory` | Allows camera motion to fall back to recent Ring event history if push notifications don't arrive. The history is checked every `cameraStatusPollingSeconds` until motion events turn out to come by push too, then every 5 minutes as a safety net (and frequently again once a push is missed, so motion can go unreported for up to 5 minutes after push stops working); disable to only trust push-triggered motion |
55
63
  | `automaticSessionRefresh` | When Ring's event history shows motion that Ring sent no push notification for (3 events over at least 30 minutes, none pushed), refreshes the Ring API session by itself, as **Force Ring API Session Refresh** does (see Troubleshooting): a child bridge restarts for it, the main bridge does it at the next Homebridge restart. Events while motion is snoozed are not counted, nor, when the camera alerts for people only, events without a person. At most once a day, and no more after 2 refreshes that brought no motion push notification. Needs `enableCameraMotionHistory`. On by default; set `false` to turn it off, for example if Ring is set to send no motion alerts in some Modes or on a schedule |
56
64
  | `sessionRefreshSensor` | Adds a "Ring Session Refreshed" contact sensor that opens after an automatic session refresh (10 s after the Home app is connected to it, within 3 minutes) and stays open for a day, also across restarts (which don't notify again). Turn on its notifications in the Home app (needs a home hub) to be told when to remove the older `homebridge-ring-secure-video` entry from Authorized Client Devices. Needs `automaticSessionRefresh`. Off by default |
57
65
  | `disableHksvOnBattery` | Disables HKSV on cameras running on battery to reduce battery/network usage; wired battery models keep it. On by default |
58
- | `hksvPrebufferLengthMs` | HKSV prebuffer duration (minimum 4000ms) |
59
- | `hksvFragmentLengthMs` | HKSV fragment duration target |
60
- | `hksvMaxRecordingSeconds` | Optional safety cap for a recording session (default 180 s; 0 disables) |
61
- | `hksvPerformanceMode` | HKSV tuning profile (`balanced`, `rpi`, or `quality`) |
62
- | `hksvMaxConcurrentRecordings` / `hksvMaxQueuedBytes` | HKSV safeguards for small systems under load |
63
- | `hksvVideoBitrateKbps` / `hksvVideoMaxBitrateKbps` / `hksvVideoBufferSizeKbps` | HKSV recording bitrate controls for improving fast-motion quality |
64
- | `hksvVideoCrf` / `hksvVideoPreset` | Optional libx264 quality and CPU tuning controls |
65
- | `hksvVideoKeyframeInterval` | HKSV recording keyframe interval |
66
66
  | `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 |
67
- | `cameraVideoCodec` | Preferred H.264 handling (`auto`, `copy`, `h264_v4l2m2m`, `h264_videotoolbox`, or `libx264`) |
68
67
  | `hideDoorbellSwitch` / `hideCameraMotionSensor` / `hideCameraSirenSwitch` | Hides specific HomeKit-exposed services |
69
68
  | `cameraMotionNotificationSensor` | Adds a separate "<camera> Motion" sensor per camera for instant motion notifications (see below) |
70
69
  | `doorbellPressMotion` | For Ring doorbells with HKSV recording on: a press also turns on the camera's motion for 30 seconds, so HKSV records the visitor even when Ring reported no motion (during a live view, or a quick press-and-leave). One recording per visit, not two. Notifications and automations on the camera's motion sensor also see it; the separate notification sensor does not. No effect with `hideCameraMotionSensor`. Off by default |
@@ -73,16 +72,37 @@ Big thanks to Dusty, trinityhades and all upstream contributors. This plugin reu
73
72
  | `debug` | Enables additional logging |
74
73
  | `disableLogs` | Disables plugin logging |
75
74
 
76
- ## v15 media configuration
75
+ ## Media configuration
77
76
 
78
- v15 uses an adaptive media engine that keeps Ring call ownership separate from
79
- each live-view and recording FFmpeg process. Configure `media.profile` as
80
- `adaptive` (default), `lowPower`, or `quality`. Advanced overrides live in
81
- `media.recording`; they are strictly validated and take precedence over legacy
82
- `hksv*` fields, which remain compatibility aliases during migration. Set
77
+ Recording is set up in `media` ("Recording Settings" in the plugin settings). The media engine
78
+ keeps the Ring call separate from each live-view and recording FFmpeg process. Set
79
+ `media.profile` to `adaptive` (default), `lowPower` or `quality`. Advanced settings live in
80
+ `media.recording`; each is validated, and an unusable value is ignored with a warning. Set
83
81
  `media.recording.maxDurationSeconds` to change its safety cap (default 180 seconds; HomeKit
84
82
  normally ends a recording itself when motion stops), or to `0` to disable it.
85
83
 
84
+ ### Settings removed in 1.0.0
85
+
86
+ The flat recording settings from earlier versions were removed in 1.0.0; `media` replaces each
87
+ of them, with the same allowed values (except `hksvPerformanceMode`, whose values are renamed as
88
+ shown). A removed setting left in a config is ignored, and the log says which one and what
89
+ replaces it: move its value there if it isn't set there yet, then delete it in the JSON editor.
90
+ Without `media.profile`, the profile is `adaptive`, so a config that only had
91
+ `"hksvPerformanceMode": "rpi"` needs `"media": { "profile": "lowPower" }`.
92
+
93
+ | Removed setting | Use instead |
94
+ | --- | --- |
95
+ | `hksvPerformanceMode` (`balanced`, `rpi`, `quality`) | `media.profile` (`adaptive`, `lowPower`, `quality`) |
96
+ | `cameraVideoCodec` | `media.recording.codec` |
97
+ | `hksvVideoBitrateKbps` / `hksvVideoMaxBitrateKbps` / `hksvVideoBufferSizeKbps` | `media.recording.bitrateKbps` / `maxBitrateKbps` / `bufferSizeKbps` |
98
+ | `hksvVideoCrf` / `hksvVideoPreset` | `media.recording.crf` / `preset` |
99
+ | `hksvVideoKeyframeInterval` | `media.recording.keyframeInterval` |
100
+ | `hksvPrebufferLengthMs` / `hksvFragmentLengthMs` | `media.recording.prebufferLengthMs` / `fragmentLengthMs` |
101
+ | `hksvMaxRecordingSeconds` | `media.recording.maxDurationSeconds` |
102
+ | `hksvMaxQueuedBytes` / `hksvMaxConcurrentRecordings` | `media.recording.maxQueuedBytes` / `maxConcurrentRecordings` |
103
+
104
+ `media.recording.rateControl` (`vbr` or `cbr`) had no flat setting.
105
+
86
106
  ## Installation
87
107
 
88
108
  Requires Node.js 22 or 24 and Homebridge 1.8 or later (2.x recommended). If Homebridge is installed
@@ -174,7 +194,7 @@ fork).
174
194
  ### Recording codecs
175
195
 
176
196
  Only HKSV recordings are encoded; live view passes Ring's video through. `media.recording.codec`
177
- (or the older `cameraVideoCodec`) chooses how:
197
+ chooses how:
178
198
 
179
199
  | Codec | What it does | CPU |
180
200
  | --- | --- | --- |
@@ -197,14 +217,13 @@ ignores all of them. The Pi's hardware encoder uses `bitrateKbps` and `keyframeI
197
217
 
198
218
  | Profile (`media.profile`) | `auto` picks |
199
219
  | --- | --- |
200
- | `lowPower` (also `"hksvPerformanceMode": "rpi"`) | `copy` |
220
+ | `lowPower` | `copy` |
201
221
  | `adaptive` (default) or `quality` | `h264_v4l2m2m` if FFmpeg has it (Raspberry Pi 4), else `h264_videotoolbox` if FFmpeg has it (Mac), else `libx264` |
202
222
 
203
223
  "FFmpeg has it" means the encoder is built into FFmpeg, not that the hardware is there: on a
204
224
  Raspberry Pi 5 (no hardware encoder), set `codec` to `copy` or `libx264` rather than relying on
205
- `auto` in the `adaptive` and `quality` profiles. A valid legacy `cameraVideoCodec` in the config
206
- counts as the codec when `media.recording.codec` isn't set. The log shows the choice for each recording: `Starting HKSV recording pipeline ...
207
- video=<codec>`.
225
+ `auto` in the `adaptive` and `quality` profiles. The log shows the choice for each recording:
226
+ `Starting HKSV recording pipeline ... video=<codec>`.
208
227
 
209
228
  #### Settings verified on a Raspberry Pi 4
210
229
 
@@ -284,10 +303,25 @@ use the next time they sign in from scratch, since they share `.ring.json`.
284
303
 
285
304
  ## Disclaimer
286
305
 
287
- This plugin is not affiliated with Ring or Amazon.
288
-
289
- Use emergency/panic-related automations at your own risk.
306
+ - **Unofficial.** This plugin is not affiliated with, endorsed by or supported by Ring LLC, Amazon,
307
+ Apple or the Homebridge project. Ring, HomeKit and other names and logos are trademarks of their
308
+ owners and are used only to describe what the plugin works with.
309
+ - **Unsupported Ring API.** It talks to Ring through the same private, undocumented API the Ring app
310
+ uses. Ring can change or block it at any time, and features can stop working without warning.
311
+ - **Not a safety device.** Don't rely on it for security, alarm monitoring or emergencies. Motion,
312
+ doorbell presses and recordings can be late or missed (for example while a live view is open, when
313
+ Ring stops sending push notifications, or when the Homebridge host is offline). Use the Ring app
314
+ for anything that matters, and use panic or emergency automations at your own risk.
315
+ - **Your Ring sign-in.** The Ring refresh token is stored in Homebridge's `config.json` in plain
316
+ text and gives access to your Ring account. Protect that file and its backups, and remove the
317
+ token from logs or config before sharing them. Each Ring API session refresh (automatic or
318
+ forced) adds an entry under Control Center > Authorized Client Devices in the Ring app; remove
319
+ the older one there. Removing the plugin's current entry signs it out of Ring.
320
+ - **Recordings and privacy.** HKSV recordings are processed on your Homebridge host and stored in
321
+ iCloud under Apple's terms. You are responsible for following local laws on recording video and
322
+ audio.
323
+ - Provided as is, without warranty. See [LICENSE](LICENSE).
290
324
 
291
325
  ## License
292
326
 
293
- MIT
327
+ MIT. Copyright Dusty Greif, trinityhades and contributors, and zmanuel1234; see [LICENSE](LICENSE).
@@ -22,21 +22,21 @@
22
22
  "description": "If enabled, HomeKit will register a delayed entry event as a triggered alarm. Useful if you want to know as soon as someone opens a door with the alarm armed"
23
23
  },
24
24
  "enableHksv": {
25
- "title": "Enable HKSV (Experimental)",
25
+ "title": "Enable HKSV",
26
26
  "type": "boolean",
27
27
  "default": true,
28
- "description": "Enables HomeKit Secure Video services for supported Ring cameras. This implementation is currently in-progress."
28
+ "description": "Enables HomeKit Secure Video recording for supported Ring cameras."
29
29
  },
30
30
  "media": {
31
- "title": "Media Engine (v15)",
31
+ "title": "Recording Settings (media)",
32
32
  "type": "object",
33
- "description": "Adaptive media profile with optional validated recording overrides. This supersedes the legacy HKSV tuning fields.",
33
+ "description": "The recording profile and optional recording settings.",
34
34
  "additionalProperties": false,
35
35
  "properties": {
36
36
  "profile": {
37
37
  "title": "Media profile",
38
38
  "type": "string",
39
- "description": "Defaults to the HKSV Performance Mode (rpi gives lowPower, quality gives quality), otherwise adaptive.",
39
+ "description": "adaptive (default), lowPower or quality. Use lowPower for a Raspberry Pi and other small computers: lower recording resolutions, one recording at a time, and copy (no re-encoding) unless another codec is set. Verified on a Pi 4 with copy, h264_v4l2m2m and libx264.",
40
40
  "oneOf": [
41
41
  { "title": "adaptive", "enum": ["adaptive"] },
42
42
  { "title": "lowPower", "enum": ["lowPower"] },
@@ -52,28 +52,28 @@
52
52
  "title": "Recording codec",
53
53
  "type": "string",
54
54
  "enum": ["auto", "copy", "libx264", "h264_v4l2m2m", "h264_videotoolbox"],
55
- "description": "Preferred H.264 handling for recordings."
55
+ "description": "Preferred H.264 handling for recordings. auto (the default, except copy in lowPower) chooses the lowest-cost option for the profile; copy records Ring's video without re-encoding. Complete clips are verified on a Raspberry Pi 4 with a Ring Video Doorbell 3 Plus for copy, h264_v4l2m2m and libx264; if clips from another camera don't play with copy, try h264_v4l2m2m (Raspberry Pi 4; the Pi 5 has no hardware H.264 encoder) or libx264."
56
56
  },
57
57
  "bitrateKbps": {
58
58
  "title": "Video bitrate (kbps)",
59
59
  "type": "integer",
60
60
  "minimum": 256,
61
61
  "maximum": 12000,
62
- "description": "Target video bitrate."
62
+ "description": "Target video bitrate when re-encoding (not with copy). Defaults to the profile's (1000 lowPower, 3000 adaptive, 5000 quality). Increase this first if fast motion becomes blocky or pixelated; 4000-6000 is a good starting range for wired cameras."
63
63
  },
64
64
  "maxBitrateKbps": {
65
65
  "title": "Maximum video bitrate (kbps)",
66
66
  "type": "integer",
67
67
  "minimum": 256,
68
68
  "maximum": 20000,
69
- "description": "Maximum burst video bitrate when using VBR."
69
+ "description": "Maximum burst video bitrate when using VBR. Defaults to 2x the bitrate; 8000-12000 is a practical range for a bitrate of 4000-6000."
70
70
  },
71
71
  "bufferSizeKbps": {
72
72
  "title": "Rate-control buffer size (kbps)",
73
73
  "type": "integer",
74
74
  "minimum": 256,
75
75
  "maximum": 40000,
76
- "description": "FFmpeg video rate-control buffer size."
76
+ "description": "FFmpeg rate-control buffer size. Defaults to 2x the maximum bitrate. Leave unset unless you are tuning bitrate stability."
77
77
  },
78
78
  "rateControl": {
79
79
  "title": "Rate control",
@@ -87,34 +87,34 @@
87
87
  "type": "integer",
88
88
  "minimum": 18,
89
89
  "maximum": 35,
90
- "description": "Optional libx264 quality value for VBR recordings."
90
+ "description": "Optional libx264 quality value for VBR recordings (libx264 only). Lower values improve quality and use more bitrate and CPU; try 20-23."
91
91
  },
92
92
  "preset": {
93
93
  "title": "libx264 preset",
94
94
  "type": "string",
95
95
  "enum": ["ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow"],
96
- "description": "Optional libx264 speed/quality preset."
96
+ "description": "libx264 speed/quality preset (libx264 only). Defaults to ultrafast in lowPower, otherwise veryfast. Move toward fast or medium for quality, or superfast for lower CPU."
97
97
  },
98
98
  "keyframeInterval": {
99
99
  "title": "Keyframe interval (frames)",
100
100
  "type": "integer",
101
101
  "minimum": 5,
102
102
  "maximum": 240,
103
- "description": "Maximum frames between keyframes."
103
+ "description": "Maximum frames between keyframes when re-encoding. Defaults to 30, the recommended value; shorter intervals can improve fragmenting at the cost of bitrate."
104
104
  },
105
105
  "prebufferLengthMs": {
106
106
  "title": "Prebuffer length (ms)",
107
107
  "type": "integer",
108
108
  "minimum": 4000,
109
109
  "maximum": 16000,
110
- "description": "How much pre-event video HomeKit retains."
110
+ "description": "How much pre-event video HomeKit retains. Minimum and default 4000 ms."
111
111
  },
112
112
  "fragmentLengthMs": {
113
113
  "title": "Fragment length (ms)",
114
114
  "type": "integer",
115
115
  "minimum": 1000,
116
116
  "maximum": 8000,
117
- "description": "Target fragmented MP4 duration."
117
+ "description": "Target fragmented MP4 duration. Defaults to 4000 ms."
118
118
  },
119
119
  "maxDurationSeconds": {
120
120
  "title": "Maximum recording length (s)",
@@ -129,14 +129,14 @@
129
129
  "type": "integer",
130
130
  "minimum": 1048576,
131
131
  "maximum": 67108864,
132
- "description": "Maximum per-recording buffered data."
132
+ "description": "Maximum recording data queued in memory per recording before it is closed to protect Homebridge. Defaults to 6 MB in lowPower, otherwise 16 MB."
133
133
  },
134
134
  "maxConcurrentRecordings": {
135
135
  "title": "Maximum simultaneous recordings",
136
136
  "type": "integer",
137
137
  "minimum": 1,
138
138
  "maximum": 4,
139
- "description": "Maximum simultaneous recording pipelines."
139
+ "description": "Maximum simultaneous recording pipelines. Defaults to 1 in lowPower, otherwise 2; keep 1 on a Raspberry Pi."
140
140
  }
141
141
  }
142
142
  }
@@ -176,173 +176,11 @@
176
176
  "description": "If enabled, HKSV is disabled on cameras running on battery, to reduce battery and network impact. Battery models that are wired (power mode wired in the Ring app) keep HKSV.",
177
177
  "default": true
178
178
  },
179
- "hksvPrebufferLengthMs": {
180
- "title": "HKSV Prebuffer Length (ms)",
181
- "type": "integer",
182
- "minimum": 4000,
183
- "maximum": 16000,
184
- "description": "How much pre-event video is retained for HKSV. Minimum is 4000ms."
185
- },
186
- "hksvFragmentLengthMs": {
187
- "title": "HKSV Fragment Length (ms)",
188
- "type": "integer",
189
- "minimum": 1000,
190
- "maximum": 8000,
191
- "description": "Target recording fragment duration for HKSV fragmented MP4 output."
192
- },
193
- "hksvMaxRecordingSeconds": {
194
- "title": "HKSV Max Recording Seconds",
195
- "type": "integer",
196
- "minimum": 0,
197
- "maximum": 300,
198
- "placeholder": 180,
199
- "description": "Optional safety cap for a single HKSV recording stream duration (default 180). Set 0 to disable the cap."
200
- },
201
- "hksvPerformanceMode": {
202
- "title": "HKSV Performance Mode",
203
- "type": "string",
204
- "description": "High-level HKSV tuning profile. Use rpi for Raspberry Pi and other small computers: lower advertised recording tiers, one recording at a time, and remuxing (copy) unless a codec other than auto is set. Verified on a Pi 4 with copy, h264_v4l2m2m and libx264.",
205
- "default": "balanced",
206
- "oneOf": [
207
- {
208
- "title": "balanced",
209
- "enum": ["balanced"]
210
- },
211
- {
212
- "title": "rpi",
213
- "enum": ["rpi"]
214
- },
215
- {
216
- "title": "quality",
217
- "enum": ["quality"]
218
- }
219
- ]
220
- },
221
- "hksvMaxQueuedBytes": {
222
- "title": "HKSV Max Queued Bytes",
223
- "type": "integer",
224
- "minimum": 1048576,
225
- "maximum": 67108864,
226
- "description": "Maximum fragmented MP4 data queued in memory per HKSV recording stream before the stream is closed to protect Homebridge."
227
- },
228
- "hksvMaxConcurrentRecordings": {
229
- "title": "HKSV Max Concurrent Recordings",
230
- "type": "integer",
231
- "minimum": 1,
232
- "maximum": 4,
233
- "description": "Maximum number of simultaneous HKSV recording pipelines. Raspberry Pi users should keep this at 1."
234
- },
235
- "hksvVideoBitrateKbps": {
236
- "title": "HKSV Video Bitrate (kbps)",
237
- "type": "integer",
238
- "minimum": 256,
239
- "maximum": 12000,
240
- "description": "Target video bitrate for HKSV recording transcodes. Defaults to the media profile's (1000 lowPower, 3000 adaptive, 5000 quality). Increase this first if fast motion becomes blocky or pixelated. 4000-6000 is a good starting range for wired cameras."
241
- },
242
- "hksvVideoMaxBitrateKbps": {
243
- "title": "HKSV Max Video Bitrate (kbps)",
244
- "type": "integer",
245
- "minimum": 256,
246
- "maximum": 20000,
247
- "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."
248
- },
249
- "hksvVideoBufferSizeKbps": {
250
- "title": "HKSV Video Buffer Size (kbps)",
251
- "type": "integer",
252
- "minimum": 256,
253
- "maximum": 40000,
254
- "description": "FFmpeg VBV buffer size for HKSV recording transcodes. Defaults to 2x the max video bitrate. Leave unset unless you are tuning bitrate stability."
255
- },
256
- "hksvVideoCrf": {
257
- "title": "HKSV x264 Quality (CRF)",
258
- "type": "integer",
259
- "minimum": 18,
260
- "maximum": 35,
261
- "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."
262
- },
263
- "hksvVideoKeyframeInterval": {
264
- "title": "HKSV Keyframe Interval",
265
- "type": "integer",
266
- "minimum": 5,
267
- "maximum": 240,
268
- "default": 30,
269
- "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."
270
- },
271
- "hksvVideoPreset": {
272
- "title": "HKSV x264 Preset",
273
- "type": "string",
274
- "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.",
275
- "oneOf": [
276
- {
277
- "title": "ultrafast",
278
- "enum": ["ultrafast"]
279
- },
280
- {
281
- "title": "superfast",
282
- "enum": ["superfast"]
283
- },
284
- {
285
- "title": "veryfast",
286
- "enum": ["veryfast"]
287
- },
288
- {
289
- "title": "faster",
290
- "enum": ["faster"]
291
- },
292
- {
293
- "title": "fast",
294
- "enum": ["fast"]
295
- },
296
- {
297
- "title": "medium",
298
- "enum": ["medium"]
299
- },
300
- {
301
- "title": "slow",
302
- "enum": ["slow"]
303
- },
304
- {
305
- "title": "slower",
306
- "enum": ["slower"]
307
- },
308
- {
309
- "title": "veryslow",
310
- "enum": ["veryslow"]
311
- }
312
- ]
313
- },
314
179
  "homeKitAccessoryTag": {
315
180
  "title": "HomeKit Accessory Tag",
316
181
  "type": "string",
317
182
  "description": "Optional tag appended to Ring accessory names and HomeKit identities. Change this to expose the same Ring devices as distinct accessories in Home app for debugging or multi-home testing."
318
183
  },
319
- "cameraVideoCodec": {
320
- "title": "Camera Video Codec",
321
- "type": "string",
322
- "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. Complete clips are verified on a Raspberry Pi 4 with a Ring Video Doorbell 3 Plus for copy, h264_v4l2m2m and libx264; if clips from another camera don't play with copy, try h264_v4l2m2m (Raspberry Pi 4; the Pi 5 has no hardware H.264 encoder) or libx264.",
323
- "oneOf": [
324
- {
325
- "title": "auto",
326
- "enum": ["auto"]
327
- },
328
- {
329
- "title": "copy",
330
- "enum": ["copy"]
331
- },
332
- {
333
- "title": "h264_v4l2m2m",
334
- "enum": ["h264_v4l2m2m"]
335
- },
336
- {
337
- "title": "h264_videotoolbox",
338
- "enum": ["h264_videotoolbox"]
339
- },
340
- {
341
- "title": "libx264",
342
- "enum": ["libx264"]
343
- }
344
- ]
345
- },
346
184
  "hideLightGroups": {
347
185
  "title": "Hide Light Groups",
348
186
  "type": "boolean",
@@ -505,20 +343,7 @@
505
343
  "automaticSessionRefresh",
506
344
  "sessionRefreshSensor",
507
345
  "enableCameraMotionHistory",
508
- "disableHksvOnBattery",
509
- "hksvVideoPreset",
510
- "cameraVideoCodec",
511
- "hksvPrebufferLengthMs",
512
- "hksvFragmentLengthMs",
513
- "hksvMaxRecordingSeconds",
514
- "hksvPerformanceMode",
515
- "hksvMaxQueuedBytes",
516
- "hksvMaxConcurrentRecordings",
517
- "hksvVideoBitrateKbps",
518
- "hksvVideoMaxBitrateKbps",
519
- "hksvVideoBufferSizeKbps",
520
- "hksvVideoCrf",
521
- "hksvVideoKeyframeInterval"
346
+ "disableHksvOnBattery"
522
347
  ]
523
348
  },
524
349
  {
@@ -1,10 +1,10 @@
1
1
  import { BaseAccessory } from "./base-accessory.js";
2
- import { Subject } from 'rxjs';
2
+ import { merge, Subject } from 'rxjs';
3
3
  import { debounceTime, distinctUntilChanged, map } from 'rxjs/operators';
4
4
  import { logError } from 'ring-client-api/util';
5
5
  export class BaseDataAccessory extends BaseAccessory {
6
6
  registerCharacteristic({ characteristicType, serviceType, getValue, setValue, setValueDebounceTime = 0, name, requestUpdate, serviceSubType, }) {
7
- const service = this.getService(serviceType, name, serviceSubType), characteristic = service.getCharacteristic(characteristicType), { device } = this;
7
+ const service = this.getService(serviceType, name, serviceSubType), characteristic = service.getCharacteristic(characteristicType), { device } = this, onValue = new Subject();
8
8
  if (requestUpdate) {
9
9
  // Only register for GET if an async request should be made to get an updated value
10
10
  characteristic.on("get" /* CharacteristicEventTypes.GET */, (callback) => {
@@ -21,10 +21,17 @@ export class BaseDataAccessory extends BaseAccessory {
21
21
  if (setValue && setValueDebounceTime) {
22
22
  const onValueToSet = new Subject();
23
23
  characteristic.on("set" /* CharacteristicEventTypes.SET */, (newValue, callback) => {
24
+ onValue.next(newValue);
24
25
  onValueToSet.next(newValue);
25
26
  callback();
26
27
  });
27
- onValueToSet.pipe(debounceTime(setValueDebounceTime)).subscribe(setValue);
28
+ onValueToSet
29
+ .pipe(debounceTime(setValueDebounceTime))
30
+ .subscribe((value) => {
31
+ Promise.resolve()
32
+ .then(() => setValue(value))
33
+ .catch(logError);
34
+ });
28
35
  }
29
36
  else if (setValue) {
30
37
  characteristic.on("set" /* CharacteristicEventTypes.SET */, (newValue, callback) => {
@@ -32,14 +39,14 @@ export class BaseDataAccessory extends BaseAccessory {
32
39
  callback();
33
40
  });
34
41
  }
35
- ;
36
- this.device.onData
37
- .pipe(map(getValue), distinctUntilChanged())
42
+ merge(this.device.onData.pipe(map(getValue)), onValue)
43
+ .pipe(distinctUntilChanged())
38
44
  .subscribe((value) => characteristic.updateValue(value));
45
+ return (value) => onValue.next(value);
39
46
  }
40
47
  registerLevelCharacteristic({ characteristicType, serviceType, getValue, setValue, requestUpdate, }) {
41
- let targetLevel;
42
- this.registerCharacteristic({
48
+ let targetLevel, levelRequestId = 0;
49
+ const updateValue = this.registerCharacteristic({
43
50
  characteristicType,
44
51
  serviceType,
45
52
  getValue: (data) => {
@@ -49,9 +56,19 @@ export class BaseDataAccessory extends BaseAccessory {
49
56
  }
50
57
  return targetLevel === undefined ? newLevel : targetLevel;
51
58
  },
52
- setValue: (level) => {
59
+ setValue: async (level) => {
60
+ const requestId = ++levelRequestId;
53
61
  targetLevel = level;
54
- setValue(level);
62
+ try {
63
+ await setValue(level);
64
+ }
65
+ catch (e) {
66
+ if (requestId === levelRequestId) {
67
+ targetLevel = undefined;
68
+ updateValue(getValue(this.device.data));
69
+ }
70
+ throw e;
71
+ }
55
72
  },
56
73
  setValueDebounceTime: 500,
57
74
  requestUpdate,
@@ -10,7 +10,7 @@ import { RtcpSenderInfo, RtcpSrPacket, RtpPacket, SrtpSession, SrtcpSession, } f
10
10
  import path from 'node:path';
11
11
  import { FragmentedMp4Parser } from "./fragmented-mp4-parser.js";
12
12
  import { getFfmpegCapabilities, } from "./ffmpeg-capabilities.js";
13
- import { getHksvPerformanceMode, getHksvRecordingResolutions, selectHksvVideoCodec, } from "./hksv-options.js";
13
+ import { getHksvRecordingResolutions, selectHksvVideoCodec } from "./hksv-options.js";
14
14
  import { hksvRecordingQueue } from "./hksv-work-queue.js";
15
15
  import { RingMediaIngress, } from "./ring-media-ingress.js";
16
16
  import { normalizeMediaConfig } from "./media-config.js";
@@ -484,7 +484,7 @@ export class CameraSource {
484
484
  this.controller = new hap.CameraController(controllerOptions);
485
485
  }
486
486
  getHksvVideoArguments(capabilities) {
487
- const media = normalizeMediaConfig(this.config), { codec: cameraVideoCodec, crf: hksvVideoCrf, preset: hksvVideoPreset, bitrateKbps, maxBitrateKbps, bufferSizeKbps, rateControl, keyframeInterval, } = media.recording, selectedCodec = selectHksvVideoCodec(cameraVideoCodec, capabilities, this.config), videoArguments = selectedCodec === 'copy'
487
+ const media = normalizeMediaConfig(this.config), { codec, crf, preset, bitrateKbps, maxBitrateKbps, bufferSizeKbps, rateControl, keyframeInterval, } = media.recording, selectedCodec = selectHksvVideoCodec(codec, capabilities, this.config), videoArguments = selectedCodec === 'copy'
488
488
  ? ['-vcodec', 'copy']
489
489
  : [
490
490
  '-vf',
@@ -522,9 +522,9 @@ export class CameraSource {
522
522
  return videoArguments;
523
523
  }
524
524
  if (selectedCodec === 'libx264') {
525
- videoArguments.push('-preset', hksvVideoPreset, '-tune', 'zerolatency', '-keyint_min', `${keyframeInterval}`, '-sc_threshold', '0');
526
- if (rateControl !== 'cbr' && Number.isFinite(hksvVideoCrf)) {
527
- videoArguments.push('-crf', `${getIntegerConfigValue(hksvVideoCrf, 23, 18, 35)}`);
525
+ videoArguments.push('-preset', preset, '-tune', 'zerolatency', '-keyint_min', `${keyframeInterval}`, '-sc_threshold', '0');
526
+ if (rateControl !== 'cbr' && Number.isFinite(crf)) {
527
+ videoArguments.push('-crf', `${getIntegerConfigValue(crf, 23, 18, 35)}`);
528
528
  }
529
529
  }
530
530
  if (selectedCodec === 'h264_videotoolbox') {
@@ -775,7 +775,7 @@ export class CameraSource {
775
775
  ? String(videoArguments[videoCodecIndex + 1])
776
776
  : 'unknown';
777
777
  throwIfClosed();
778
- logInfo(`Starting HKSV recording pipeline for ${this.ringCamera.name} (streamId=${streamId}, mode=${getHksvPerformanceMode(this.config)}, video=${selectedVideoCodec})`);
778
+ logInfo(`Starting HKSV recording pipeline for ${this.ringCamera.name} (streamId=${streamId}, profile=${normalizeMediaConfig(this.config).profile}, video=${selectedVideoCodec})`);
779
779
  sourceSession = await this.mediaIngress.acquire('HKSV recording', queueAbortController.signal);
780
780
  liveCall = sourceSession.session;
781
781
  stopActiveLiveCall = () => sourceSession?.release();
@@ -1,7 +1,4 @@
1
- import { getLegacyHksvPerformanceMode, normalizeMediaConfig, } from "./media-config.js";
2
- export function getHksvPerformanceMode(config) {
3
- return getLegacyHksvPerformanceMode(config);
4
- }
1
+ import { normalizeMediaConfig } from "./media-config.js";
5
2
  export function getHksvRecordingResolutions(config) {
6
3
  if (normalizeMediaConfig(config).profile === 'lowPower') {
7
4
  return [
@@ -18,6 +18,7 @@ function getStateFromMode(mode) {
18
18
  }
19
19
  export class LocationModeSwitch extends BaseAccessory {
20
20
  targetState;
21
+ modeRequestId = 0;
21
22
  device;
22
23
  location;
23
24
  accessory;
@@ -36,7 +37,7 @@ export class LocationModeSwitch extends BaseAccessory {
36
37
  if (state === this.targetState) {
37
38
  this.targetState = undefined;
38
39
  }
39
- if (!this.targetState) {
40
+ if (this.targetState === undefined) {
40
41
  targetState.updateValue(state);
41
42
  }
42
43
  currentState.updateValue(state);
@@ -58,28 +59,53 @@ export class LocationModeSwitch extends BaseAccessory {
58
59
  : await getCurrentState());
59
60
  });
60
61
  targetState.on("set" /* CharacteristicEventTypes.SET */, async (state, callback) => {
61
- const { Characteristic: { SecuritySystemTargetState: State }, } = hap;
62
+ const { Characteristic: { SecuritySystemTargetState: State }, } = hap, requestId = ++this.modeRequestId;
62
63
  callback();
63
- if (state === State.NIGHT_ARM) {
64
- state = State.STAY_ARM;
65
- // Ring doesn't have night mode, so switch over to stay mode
66
- setTimeout(() => targetState.updateValue(state), 100);
64
+ try {
65
+ const current = await getCurrentState();
66
+ if (requestId !== this.modeRequestId) {
67
+ return;
68
+ }
69
+ if (state === State.NIGHT_ARM) {
70
+ state = State.STAY_ARM;
71
+ // Ring doesn't have night mode, so switch over to stay mode
72
+ setTimeout(() => {
73
+ if (requestId === this.modeRequestId) {
74
+ targetState.updateValue(state);
75
+ }
76
+ }, 100);
77
+ }
78
+ if (state === current) {
79
+ this.targetState = undefined;
80
+ return;
81
+ }
82
+ this.targetState = state;
83
+ if (state === State.AWAY_ARM) {
84
+ logInfo(`Setting ${this.location.name} Mode to away`);
85
+ await this.location.setLocationMode('away');
86
+ }
87
+ else if (state === State.DISARM) {
88
+ logInfo(`Setting ${this.location.name} Mode to disarmed`);
89
+ await this.location.setLocationMode('disarmed');
90
+ }
91
+ else {
92
+ logInfo(`Setting ${this.location.name} Mode to home`);
93
+ await this.location.setLocationMode('home');
94
+ }
67
95
  }
68
- if (state === (await getCurrentState())) {
69
- this.targetState = undefined;
70
- return;
71
- }
72
- this.targetState = state;
73
- if (state === State.AWAY_ARM) {
74
- logInfo(`Setting ${this.location.name} Mode to away`);
75
- return this.location.setLocationMode('away');
76
- }
77
- else if (state === State.DISARM) {
78
- logInfo(`Setting ${this.location.name} Mode to disarmed`);
79
- return this.location.setLocationMode('disarmed');
96
+ catch (e) {
97
+ logError('Failed to set location mode for ' + location.name);
98
+ logError(e);
99
+ if (requestId !== this.modeRequestId) {
100
+ return;
101
+ }
102
+ const current = await getCurrentState();
103
+ if (requestId === this.modeRequestId) {
104
+ this.targetState = undefined;
105
+ this.modeRequestId++;
106
+ targetState.updateValue(current);
107
+ }
80
108
  }
81
- logInfo(`Setting ${this.location.name} Mode to home`);
82
- return this.location.setLocationMode('home');
83
109
  });
84
110
  targetState.setProps({
85
111
  validValues: [
@@ -83,77 +83,34 @@ function integer(value, path, fallback, minimum, maximum) {
83
83
  }
84
84
  return value;
85
85
  }
86
- function legacyInteger(value, fallback, minimum, maximum) {
87
- // Keep the flat v14 options compatible: they were rounded and clamped at
88
- // consumption time. Nested v15 values use integer() and fail fast instead.
89
- if (typeof value !== 'number' || !Number.isFinite(value)) {
90
- return fallback;
91
- }
92
- return Math.min(Math.max(Math.round(value), minimum), maximum);
93
- }
94
- function preferInteger(modern, legacy, path, fallback, minimum, maximum, legacyMinimum = minimum) {
95
- return modern === undefined
96
- ? legacyInteger(legacy, fallback, legacyMinimum, maximum)
97
- : integer(modern, path, fallback, minimum, maximum);
98
- }
99
- function preferOptionalInteger(modern, legacy, path, minimum, maximum, legacyMinimum = minimum) {
100
- if (modern !== undefined) {
101
- return integer(modern, path, minimum, minimum, maximum);
102
- }
103
- if (typeof legacy !== 'number' || !Number.isFinite(legacy)) {
104
- return undefined;
105
- }
106
- return Math.min(Math.max(Math.round(legacy), legacyMinimum), maximum);
86
+ function optionalInteger(value, path, minimum, maximum) {
87
+ return value === undefined ? undefined : integer(value, path, minimum, minimum, maximum);
107
88
  }
108
- function legacyEnum(value, values, fallback) {
109
- return typeof value === 'string' && values.includes(value)
110
- ? value
111
- : fallback;
112
- }
113
- function preferEnum(modern, legacy, path, values, fallback) {
114
- return modern === undefined
115
- ? legacyEnum(legacy, values, fallback)
116
- : enumValue(modern, path, values, fallback);
117
- }
118
- function getProfile(config, modernProfile) {
119
- // The nested v15 setting is authoritative when both forms are present.
120
- // This makes it safe for config UIs to retain legacy fields during upgrade.
121
- if (modernProfile !== undefined) {
122
- return enumValue(modernProfile, 'media.profile', ['adaptive', 'lowPower', 'quality'], 'adaptive');
123
- }
124
- return config.hksvPerformanceMode === 'rpi'
125
- ? 'lowPower'
126
- : config.hksvPerformanceMode === 'quality' ? 'quality' : 'adaptive';
127
- }
128
- /**
129
- * Converts legacy flat HKSV options and v15 media options into one validated
130
- * configuration. New nested recording values intentionally win over legacy
131
- * values; legacy fields remain supported while users migrate.
132
- */
89
+ /** Converts the media options into one validated configuration, with each profile's defaults. */
133
90
  export function normalizeMediaConfig(config) {
134
91
  const media = getMediaInput(config);
135
- const profile = getProfile(config, media.profile);
92
+ const profile = enumValue(media.profile, 'media.profile', ['adaptive', 'lowPower', 'quality'], 'adaptive');
136
93
  const input = media.recording;
137
94
  const lowPower = profile === 'lowPower';
138
- const bitrateKbps = preferInteger(input.bitrateKbps, config.hksvVideoBitrateKbps, 'media.recording.bitrateKbps', lowPower ? 1000 : profile === 'quality' ? 5000 : 3000, 256, 12000);
139
- const maxBitrateKbps = preferInteger(input.maxBitrateKbps, config.hksvVideoMaxBitrateKbps, 'media.recording.maxBitrateKbps', Math.min(bitrateKbps * 2, 20000), bitrateKbps, 20000);
140
- const bufferSizeKbps = preferInteger(input.bufferSizeKbps, config.hksvVideoBufferSizeKbps, 'media.recording.bufferSizeKbps', Math.min(maxBitrateKbps * 2, 40000), maxBitrateKbps, 40000);
95
+ const bitrateKbps = integer(input.bitrateKbps, 'media.recording.bitrateKbps', lowPower ? 1000 : profile === 'quality' ? 5000 : 3000, 256, 12000);
96
+ const maxBitrateKbps = integer(input.maxBitrateKbps, 'media.recording.maxBitrateKbps', Math.min(bitrateKbps * 2, 20000), bitrateKbps, 20000);
97
+ const bufferSizeKbps = integer(input.bufferSizeKbps, 'media.recording.bufferSizeKbps', Math.min(maxBitrateKbps * 2, 40000), maxBitrateKbps, 40000);
141
98
  return {
142
99
  profile,
143
100
  recording: {
144
- codec: preferEnum(input.codec, config.cameraVideoCodec, 'media.recording.codec', codecs, lowPower ? 'copy' : 'auto'),
101
+ codec: enumValue(input.codec, 'media.recording.codec', codecs, lowPower ? 'copy' : 'auto'),
145
102
  bitrateKbps,
146
103
  maxBitrateKbps,
147
104
  bufferSizeKbps,
148
105
  rateControl: enumValue(input.rateControl, 'media.recording.rateControl', ['cbr', 'vbr'], 'vbr'),
149
- crf: preferOptionalInteger(input.crf, config.hksvVideoCrf, 'media.recording.crf', 18, 35),
150
- preset: preferEnum(input.preset, config.hksvVideoPreset, 'media.recording.preset', presets, lowPower ? 'ultrafast' : 'veryfast'),
151
- keyframeInterval: preferInteger(input.keyframeInterval, config.hksvVideoKeyframeInterval, 'media.recording.keyframeInterval', 30, 5, 240),
152
- prebufferLengthMs: preferInteger(input.prebufferLengthMs, config.hksvPrebufferLengthMs, 'media.recording.prebufferLengthMs', 4000, 4000, 16000),
153
- fragmentLengthMs: preferInteger(input.fragmentLengthMs, config.hksvFragmentLengthMs, 'media.recording.fragmentLengthMs', 4000, 1000, 8000),
154
- maxDurationSeconds: preferOptionalInteger(input.maxDurationSeconds, config.hksvMaxRecordingSeconds, 'media.recording.maxDurationSeconds', 0, 300, 0),
155
- maxQueuedBytes: preferInteger(input.maxQueuedBytes, config.hksvMaxQueuedBytes, 'media.recording.maxQueuedBytes', lowPower ? 6 * 1024 * 1024 : 16 * 1024 * 1024, 1024 * 1024, 64 * 1024 * 1024),
156
- maxConcurrentRecordings: preferInteger(input.maxConcurrentRecordings, config.hksvMaxConcurrentRecordings, 'media.recording.maxConcurrentRecordings', lowPower ? 1 : 2, 1, 4),
106
+ crf: optionalInteger(input.crf, 'media.recording.crf', 18, 35),
107
+ preset: enumValue(input.preset, 'media.recording.preset', presets, lowPower ? 'ultrafast' : 'veryfast'),
108
+ keyframeInterval: integer(input.keyframeInterval, 'media.recording.keyframeInterval', 30, 5, 240),
109
+ prebufferLengthMs: integer(input.prebufferLengthMs, 'media.recording.prebufferLengthMs', 4000, 4000, 16000),
110
+ fragmentLengthMs: integer(input.fragmentLengthMs, 'media.recording.fragmentLengthMs', 4000, 1000, 8000),
111
+ maxDurationSeconds: optionalInteger(input.maxDurationSeconds, 'media.recording.maxDurationSeconds', 0, 300),
112
+ maxQueuedBytes: integer(input.maxQueuedBytes, 'media.recording.maxQueuedBytes', lowPower ? 6 * 1024 * 1024 : 16 * 1024 * 1024, 1024 * 1024, 64 * 1024 * 1024),
113
+ maxConcurrentRecordings: integer(input.maxConcurrentRecordings, 'media.recording.maxConcurrentRecordings', lowPower ? 1 : 2, 1, 4),
157
114
  },
158
115
  };
159
116
  }
@@ -178,7 +135,7 @@ function removeSetting(config, path) {
178
135
  /**
179
136
  * Like normalizeMediaConfig, but never throws: each media setting that can't be used is taken out
180
137
  * of config (in memory only, so every later normalizeMediaConfig call agrees) and reported, and the
181
- * older flat setting or the default is used instead. A bad value, for example a maximum bitrate below the bitrate, would
138
+ * default is used instead. A bad value, for example a maximum bitrate below the bitrate, would
182
139
  * otherwise stop the plugin from starting and take everything on its bridge down with it.
183
140
  */
184
141
  export function sanitizeMediaConfig(config) {
@@ -200,8 +157,25 @@ export function sanitizeMediaConfig(config) {
200
157
  ignored.push(new MediaConfigError('media', 'fewer than 64 unusable settings, so all of them are ignored'));
201
158
  return { media: normalizeMediaConfig(config), ignored };
202
159
  }
203
- /** Maps v15 profiles to the legacy names used by existing camera code. */
204
- export function getLegacyHksvPerformanceMode(config) {
205
- const profile = normalizeMediaConfig(config).profile;
206
- return profile === 'lowPower' ? 'rpi' : profile === 'quality' ? 'quality' : 'balanced';
160
+ /** Each flat recording setting removed in 1.0.0 and the media setting that replaced it. */
161
+ export const removedMediaSettings = {
162
+ hksvPerformanceMode: 'media.profile',
163
+ cameraVideoCodec: 'media.recording.codec',
164
+ hksvVideoBitrateKbps: 'media.recording.bitrateKbps',
165
+ hksvVideoMaxBitrateKbps: 'media.recording.maxBitrateKbps',
166
+ hksvVideoBufferSizeKbps: 'media.recording.bufferSizeKbps',
167
+ hksvVideoCrf: 'media.recording.crf',
168
+ hksvVideoPreset: 'media.recording.preset',
169
+ hksvVideoKeyframeInterval: 'media.recording.keyframeInterval',
170
+ hksvPrebufferLengthMs: 'media.recording.prebufferLengthMs',
171
+ hksvFragmentLengthMs: 'media.recording.fragmentLengthMs',
172
+ hksvMaxRecordingSeconds: 'media.recording.maxDurationSeconds',
173
+ hksvMaxQueuedBytes: 'media.recording.maxQueuedBytes',
174
+ hksvMaxConcurrentRecordings: 'media.recording.maxConcurrentRecordings',
175
+ };
176
+ /** Removed settings still in a config (they are ignored), with what replaced each. */
177
+ export function getRemovedSettings(config) {
178
+ return Object.entries(removedMediaSettings)
179
+ .filter(([removed]) => config[removed] != null)
180
+ .map(([removed, replacement]) => ({ removed, replacement }));
207
181
  }
@@ -23,7 +23,7 @@ import { PushHealthMonitor, readPushRecoveryState, writePushRecoveryState, } fro
23
23
  import { readFileSync } from 'fs';
24
24
  import { getSessionRefreshSensorUuid, SessionRefreshSensor, } from "./session-refresh-sensor.js";
25
25
  import { PanicButtons } from "./panic-buttons.js";
26
- import { logInfo, useLogger } from 'ring-client-api/util';
26
+ import { logError, logInfo, useLogger } from 'ring-client-api/util';
27
27
  import { FloodFreezeSensor } from "./flood-freeze-sensor.js";
28
28
  import { FreezeSensor } from "./freeze-sensor.js";
29
29
  import { TemperatureSensor } from "./temperature-sensor.js";
@@ -33,7 +33,7 @@ import { Thermostat } from "./thermostat.js";
33
33
  import { UnknownZWaveSwitchSwitch } from "./unknown-zwave-switch.js";
34
34
  import { Intercom } from "./intercom.js";
35
35
  import { Valve } from "./valve.js";
36
- import { sanitizeMediaConfig } from "./media-config.js";
36
+ import { getRemovedSettings, sanitizeMediaConfig } from "./media-config.js";
37
37
  import { configureHksvResourceGovernor } from "./hksv-work-queue.js";
38
38
  import { getMotionNotificationSensorUuid, setUpMotionNotificationSensor, } from "./motion-notification-sensor.js";
39
39
  const ignoreHiddenDeviceTypes = [
@@ -185,6 +185,34 @@ function clearRefreshPending(storagePath, update = {}) {
185
185
  writePushRecoveryState(storagePath, { ...state, ...update, refreshPending: false });
186
186
  }
187
187
  }
188
+ /**
189
+ * False for a token ring-client-api built from a Ring sign-in response without a refresh token
190
+ * (its `rt`). Saving one would make every later start fail with invalid_grant until signing in
191
+ * again, while the token it replaces may still work (dgreif/ring#1886). A token that isn't
192
+ * ring-client-api's JSON form (an old plain refresh token) can't be checked and counts as valid.
193
+ */
194
+ export function hasRingRefreshToken(token) {
195
+ try {
196
+ const auth = JSON.parse(Buffer.from(token, 'base64').toString());
197
+ if (auth && typeof auth === 'object' && !Array.isArray(auth)) {
198
+ return typeof auth.rt === 'string' && auth.rt !== '';
199
+ }
200
+ }
201
+ catch {
202
+ // Not ring-client-api's JSON form.
203
+ }
204
+ return token !== '';
205
+ }
206
+ let reportedTokenWithoutRt = false;
207
+ function isUsableNewToken(token) {
208
+ if (hasRingRefreshToken(token))
209
+ return true;
210
+ if (!reportedTokenWithoutRt) {
211
+ reportedTokenWithoutRt = true;
212
+ logError('Could not read a refresh token in Ring\'s sign-in response (this can happen with an unsupported Node.js version); the previous Ring token is kept (in config.json and for reconnecting). If this repeats, check the Node.js version and update the plugin, then sign in again in the plugin settings if needed.');
213
+ }
214
+ return false;
215
+ }
188
216
  /**
189
217
  * Saves each new Ring refresh token into config.json, replacing the token that is there now.
190
218
  *
@@ -200,7 +228,7 @@ export function createRefreshTokenSaver(api, tokenInConfig, clearRefreshFlags, o
200
228
  clearFlags = clearRefreshFlags, warned = false;
201
229
  return ({ oldRefreshToken, newRefreshToken, }) => {
202
230
  const replace = current ?? oldRefreshToken;
203
- if (!replace || newRefreshToken === replace) {
231
+ if (!replace || newRefreshToken === replace || !isUsableNewToken(newRefreshToken)) {
204
232
  return;
205
233
  }
206
234
  const saved = updateHomebridgeConfig(api, (configContents) => {
@@ -296,7 +324,10 @@ export class RingPlatform {
296
324
  // cameras are constructed; individual cameras must never overwrite it.
297
325
  const { media, ignored } = sanitizeMediaConfig(config);
298
326
  for (const setting of ignored) {
299
- this.log.warn(`Ignoring the media setting ${setting.path} (expected ${setting.expectation}); the older setting or the default is used instead. Correct it in the plugin settings.`);
327
+ this.log.warn(`Ignoring the media setting ${setting.path} (expected ${setting.expectation}); the default is used instead. Correct it in the plugin settings.`);
328
+ }
329
+ for (const { removed, replacement } of getRemovedSettings(config)) {
330
+ this.log.warn(`The setting ${removed} was removed in 1.0.0 and is ignored: move its value to ${replacement} (Recording Settings) if it isn't set there yet, then delete ${removed} in the JSON editor (Config tab).`);
300
331
  }
301
332
  configureHksvResourceGovernor({
302
333
  recordingConcurrency: media.recording.maxConcurrentRecordings,
@@ -449,6 +480,9 @@ export class RingPlatform {
449
480
  // A retry must sign in with the newest token (Ring may have replaced the old one) and must
450
481
  // not force a new identity or push registration again.
451
482
  ringApi.onRefreshTokenUpdated.subscribe(({ newRefreshToken }) => {
483
+ // A broken token is not kept for reconnecting either (see hasRingRefreshToken).
484
+ if (!isUsableNewToken(newRefreshToken))
485
+ return;
452
486
  config.refreshToken = newRefreshToken;
453
487
  config.forceRefreshRingPushCredentials = false;
454
488
  config.forceRefreshRingApiSession = false;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "homebridge-ring-secure-video",
3
3
  "displayName": "Ring Secure Video",
4
- "version": "1.0.0-beta.6",
4
+ "version": "1.0.0-beta.7",
5
5
  "description": "Homebridge plugin for Ring devices with HomeKit Secure Video recording, based on homebridge-ring and homebridge-ring-hksv",
6
6
  "type": "module",
7
7
  "main": "./lib/index.js",