homebridge-ring-secure-video 1.0.0-beta.3 → 1.0.0-beta.5

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,103 @@
1
1
  # homebridge-ring-secure-video
2
2
 
3
+ ## 1.0.0-beta.5 (2026-11-13)
4
+
5
+ **Changes in behaviour to check after updating:**
6
+
7
+ - Automatic Ring session refresh is on by default. When it runs, a child bridge restarts itself,
8
+ a new `homebridge-ring-secure-video` entry appears in Authorized Client Devices in the Ring app
9
+ (remove the older one), and the identity in `.ring.json` changes, which other Ring plugins in
10
+ the same Homebridge (such as homebridge-ring) also use the next time they sign in from scratch.
11
+ If Ring is set to send no motion alerts in some Modes or on a schedule, set
12
+ `"automaticSessionRefresh": false`.
13
+
14
+ **New:**
15
+
16
+ - **Automatic Ring session refresh** (`automaticSessionRefresh`, on by default). Ring can stop
17
+ sending push notifications to the plugin's device identity while the connection to Google's
18
+ push service stays healthy: motion then only arrives late from the event history, and doorbell
19
+ presses not at all. When Ring's event history shows 3 motion events over at least 30 minutes
20
+ that Ring sent no push notification for, and no push notification of any kind arrived in
21
+ between, the plugin does what "Force Ring API Session Refresh" does: a new device identity and
22
+ push registration. A child bridge restarts itself for it; on the main bridge it happens at the
23
+ next Homebridge restart (dropped if a push notification arrives first). At most once a day,
24
+ and no more after 2 refreshes that brought no motion push. Not counted:
25
+ motion while snoozed, and motion without a person when the camera alerts for people only.
26
+ Needs the motion history fallback (on by default). After a refresh the log says "Automatic Ring
27
+ session refresh done", naming the Authorized Client Devices entry to remove.
28
+ - **"Ring Session Refreshed" sensor** (`sessionRefreshSensor`, off by default): a contact sensor
29
+ that opens after an automatic session refresh and closes a day later, so the Home app can
30
+ notify you (turn on its notifications; needs a home hub). Needs Automatic Ring Session Refresh.
31
+
32
+ **Fixes:**
33
+
34
+ - A child bridge that Homebridge restarted on its own (after a crash, or for the automatic
35
+ refresh) signed in with the Ring token from when Homebridge started, and couldn't save the
36
+ next one; a "Force Ring ..." setting cleared since was on again. It now takes the token and
37
+ the force settings from its block in config.json.
38
+ - New Ring tokens are also saved when the platform block in config.json is named
39
+ `"homebridge-ring-secure-video.Ring Secure Video"`; before, they weren't, and the next start
40
+ signed in with an old token.
41
+ - README: what to do when Ring's push notifications stop arriving (Troubleshooting).
42
+
43
+ **Maintenance:** dependency updates (`@homebridge/plugin-ui-utils` 2.3, ajv, globals,
44
+ typescript-eslint, concurrently 10), Homebridge 2.5 for development, and newer GitHub Actions for
45
+ CI and publishing. `@eneris/push-receiver` stays at 4.3.1 and ring-client-api at 14.3.0;
46
+ Dependabot no longer bundles them with other updates. werift stays at 0.22.4 (the version
47
+ ring-client-api pins), and Dependabot now ignores it.
48
+
49
+ ## 1.0.0-beta.4 (2026-11-13)
50
+
51
+ More fixes from the full independent review of 1.0.0-beta.2.
52
+
53
+ **Changes in behaviour to check after updating:**
54
+
55
+ - `enableHksv` now means on when it isn't set, as the settings form shows. Configs without it
56
+ (written by hand, or copied from homebridge-ring) now offer HKSV recording: live view allows
57
+ one viewer at a time, and recording starts once turned on for the camera in the Home app. Set
58
+ `"enableHksv": false` to keep the old behaviour.
59
+ - `disableHksvOnBattery` now means on when it isn't set, and looks at whether a camera actually
60
+ runs on battery: battery models that are wired (power mode wired in the Ring app), like many
61
+ doorbells, keep HKSV; battery-only cameras don't get it. Configs without the setting therefore
62
+ lose HKSV on battery-only cameras; set `"disableHksvOnBattery": false` to keep it. Configs
63
+ saved by the old settings form have it set to true, so their wired battery doorbells now get
64
+ HKSV.
65
+ - Values the old settings form saved stay until removed: a saved `"media": { "profile":
66
+ "adaptive" }` still overrides `"hksvPerformanceMode": "rpi"`, and a saved
67
+ `"hksvVideoBitrateKbps": 3000` still overrides the profile's bitrate. Remove them if you didn't
68
+ choose them.
69
+
70
+ **Fixes:**
71
+
72
+ - One device or location that fails to set up no longer stops the others, the alarm included.
73
+ A failed device keeps its HomeKit accessory (rooms and automations stay) but shows "No
74
+ Response"; a location whose devices can't be loaded is logged, and its accessories are kept and
75
+ show "No Response". If
76
+ Ring can't be reached when Homebridge starts (an outage, a server error, a sign-in server
77
+ outage), connecting is retried after 30 s, 1 min, 2 min, ... up to every 10 minutes, with the
78
+ newest sign-in token and without forcing a new Ring registration.
79
+ - The motion fallback no longer asks Ring for each camera's event history every 20 s all day
80
+ (about 4,300 requests a day). Once motion events turn out to arrive by push too, it checks every
81
+ 5 minutes as a safety net; a motion event no push reported switches back to frequent checks. A
82
+ history event counts as pushed if a motion push had its id or came within 90 s of it. If push
83
+ stops working, it is noticed at the next 5-minute check; a visit found then is only reported if
84
+ it is at most 3 minutes old, so it can be missed. Remembered events are forgotten an hour after
85
+ they leave Ring's history.
86
+ - ffmpeg errors no longer end the whole bridge (alarm included): further errors on a process and
87
+ errors on its output are logged, and a talk-back ffmpeg that fails to start is logged and the
88
+ live view is reported to HomeKit as not started.
89
+ - A snapshot that can't be refreshed is shown for at most Ring's snapshot lifetime plus 2
90
+ minutes, as in homebridge-ring, rather than indefinitely.
91
+ - The settings form no longer fills in a bitrate or media profile that overrode the media
92
+ profile and the older HKSV performance mode.
93
+ - README and settings text: the Raspberry Pi section shows the settings verified on a Pi 4
94
+ (`lowPower`, `libx264`, with a Ring Video Doorbell 3 Plus); `copy` and `h264_v4l2m2m` are
95
+ described as not yet verified. Upstream links point to dgreif/ring, and the install commands
96
+ no longer use `--unsafe-perm`.
97
+ - Development: GitHub Actions and the publishing npm are pinned to exact versions, the GitHub
98
+ token is kept out of dependency installs, Dependabot is set up, and locked dependencies include
99
+ the available security fixes.
100
+
3
101
  ## 1.0.0-beta.3 (2026-11-13)
4
102
 
5
103
  Fixes from a full independent review of 1.0.0-beta.2.
package/README.md CHANGED
@@ -13,22 +13,24 @@ It is meant to replace `homebridge-ring` on its own: one plugin, one Ring sign-i
13
13
 
14
14
  ## Origin and Attribution
15
15
 
16
- This project is based on Dustin Greif's original Ring Homebridge ecosystem:
16
+ This project is based on Dusty Greif's original Ring Homebridge ecosystem:
17
17
 
18
- - Upstream plugin: [dgreif/homebridge-ring](https://github.com/dgreif/homebridge-ring)
19
- - Upstream API library: [dgreif/ring-client-api](https://github.com/dgreif/ring-client-api)
18
+ - Upstream plugin and API library: [dgreif/ring](https://github.com/dgreif/ring)
19
+ (`homebridge-ring` and `ring-client-api`)
20
20
 
21
21
  - HKSV fork: [trinityhades/homebridge-ring-hksv](https://github.com/trinityhades/homebridge-ring-hksv), whose history this repository continues
22
22
 
23
- Big thanks to Dustin, trinityhades and all upstream contributors. This plugin reuses and extends that foundation.
23
+ Big thanks to Dusty, trinityhades and all upstream contributors. This plugin reuses and extends that foundation.
24
24
 
25
25
  ## Important Plugin Options
26
26
 
27
27
  | Option | Purpose |
28
28
  | --- | --- |
29
- | `enableHksv` | Enables experimental HKSV support for eligible cameras |
30
- | `enableCameraMotionHistory` | Allows camera motion to fall back to recent Ring event history if live notifications are stale; disable to only trust push-triggered motion |
31
- | `disableHksvOnBattery` | Disables HKSV on battery cameras to reduce battery/network usage |
29
+ | `enableHksv` | Enables experimental HKSV support for eligible cameras; on by default, set `false` to turn it off |
30
+ | `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 |
31
+ | `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. At most once a day, and no more after 2 refreshes that brought no 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 |
32
+ | `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 |
33
+ | `disableHksvOnBattery` | Disables HKSV on cameras running on battery to reduce battery/network usage; wired battery models keep it. On by default |
32
34
  | `hksvPrebufferLengthMs` | HKSV prebuffer duration (minimum 4000ms) |
33
35
  | `hksvFragmentLengthMs` | HKSV fragment duration target |
34
36
  | `hksvMaxRecordingSeconds` | Optional safety cap for a recording session (default 180 s; 0 disables) |
@@ -61,13 +63,13 @@ normally ends a recording itself when motion stops), or to `0` to disable it.
61
63
  If Homebridge is installed globally:
62
64
 
63
65
  ```bash
64
- npm i -g --unsafe-perm homebridge-ring-secure-video
66
+ npm i -g homebridge-ring-secure-video
65
67
  ```
66
68
 
67
69
  To try a beta, install the `beta` tag instead:
68
70
 
69
71
  ```bash
70
- npm i -g --unsafe-perm homebridge-ring-secure-video@beta
72
+ npm i -g homebridge-ring-secure-video@beta
71
73
  ```
72
74
 
73
75
  If running from source:
@@ -115,7 +117,8 @@ Changing `homeKitAccessoryTag` updates both the exposed accessory name and the g
115
117
 
116
118
  HKSV support is experimental and actively evolving. Behavior may vary by camera model, wired vs battery power, Ring API changes, and FFmpeg environment.
117
119
 
118
- I currently am able to run 3 cameras with HKSV enabled on a Homebridge instance ran on a M4 Mac Mini 32GB of RAM.
120
+ Verified so far: complete HomeKit clips from a Ring Video Doorbell 3 Plus on a Raspberry Pi 4
121
+ (Node 22, Homebridge 2) with the settings below. The HKSV fork this continues reported 3 cameras on an M4 Mac mini.
119
122
  Please report your experience and setup details to help improve support.
120
123
 
121
124
  Recordings follow the frame rate and audio format HomeKit asks for, and include audio only when
@@ -133,24 +136,23 @@ For fast-motion pixelation or stuttering in HKSV recordings, try increasing
133
136
  `cameraVideoCodec: "h264_videotoolbox"` can reduce CPU load by using hardware
134
137
  encoding.
135
138
 
136
- For Raspberry Pi 4/5 and other small computers, start with:
139
+ For Raspberry Pi 4/5 and other small computers, start with what has been verified on a Pi 4:
137
140
 
138
141
  ```json
139
142
  {
140
143
  "enableHksv": true,
141
- "hksvPerformanceMode": "rpi",
142
- "cameraVideoCodec": "auto",
143
- "hksvMaxConcurrentRecordings": 1
144
+ "media": {
145
+ "profile": "lowPower",
146
+ "recording": { "codec": "libx264", "bitrateKbps": 800 }
147
+ }
144
148
  }
145
149
  ```
146
150
 
147
- The `rpi` profile favors remuxing Ring's H.264 video into HomeKit Secure Video
148
- fragmented MP4 instead of re-encoding it. This is much lighter than libx264, but
149
- it depends on Ring's current stream being compatible with HomeKit's H.264
150
- recording requirements. If recording fails in this mode, try
151
- `cameraVideoCodec: "h264_v4l2m2m"` when your FFmpeg build exposes that encoder,
152
- or fall back to `cameraVideoCodec: "libx264"` with `hksvVideoPreset:
153
- "ultrafast"`.
151
+ The `lowPower` profile (also chosen by `"hksvPerformanceMode": "rpi"`) records one clip at a
152
+ time with conservative settings. Lighter codecs exist but complete HomeKit clips with them are
153
+ not verified yet: `copy` (the `lowPower` default for `auto`) remuxes Ring's H.264 without
154
+ re-encoding, which only works when Ring's stream meets HomeKit's recording requirements, and
155
+ `h264_v4l2m2m` uses the Pi's hardware encoder when FFmpeg has it.
154
156
 
155
157
  ### Minimum specifications for HKSV:
156
158
  [TBD - will be added as more users test and report their setups]
@@ -163,16 +165,47 @@ For support and debugging:
163
165
 
164
166
  - Upstream Ring wiki (token/auth/camera references): <https://github.com/dgreif/ring/wiki>
165
167
 
166
- If motion and doorbell events arrive late (the log shows "Detected Motion from Ring event history
167
- fallback" rather than right away), Ring's instant notifications aren't reaching the plugin. At start the
168
- log says which `@eneris/push-receiver` the Ring push client uses ("Ring push notifications: ..."), or
169
- warns "Could not fix Ring push notifications" if the plugin couldn't give it the fixed 4.3.1. See also the upstream [notification troubleshooting](https://github.com/dgreif/ring/wiki/Notification-Troubleshooting).
170
-
171
- Use the "Force Ring Push Credential Refresh" and "Force Ring API Session Refresh" settings only as a
172
- last resort, once. Each refresh adds a registration with Ring, and repeated ones can make Ring stop
173
- sending notifications to the plugin. If that happens, remove `homebridge-ring-secure-video` from
174
- Authorized Client Devices in the Ring app's Control Center, create a new refresh token, and paste it
175
- into the plugin's settings.
168
+ ### Motion arrives late or doorbell presses are missed
169
+
170
+ If motion arrives 20–30 seconds late with "Detected Motion from Ring event history fallback" in the
171
+ log (or "Ring event history shows motion no push notification reported"), and doorbell presses don't
172
+ reach HomeKit at all, Ring's instant push notifications aren't reaching the plugin. Once they do, the
173
+ "...from Ring event history fallback" lines stop, and (with the motion history fallback on, the
174
+ default) the log says "Ring push notifications are arriving".
175
+
176
+ 1. Check that the Homebridge machine can reach Google's push service: `mtalk.google.com` must
177
+ resolve to a real address (not `0.0.0.0`; DNS ad blockers such as AdGuard or Pi-hole can block it)
178
+ and TCP port 5228 must be open. See the upstream
179
+ [notification troubleshooting](https://github.com/dgreif/ring/wiki/Notification-Troubleshooting).
180
+ 2. If the connection is fine, Ring may have stopped sending to the plugin's device identity, even
181
+ though the Ring app on your phone still gets alerts. Removing the plugin from Authorized Client
182
+ Devices and signing in again keeps the same identity (it is stored in `.ring.json`), so it may not
183
+ help. What does: turn on **Force Ring API Session Refresh** in the plugin's settings once, and
184
+ restart. The log then shows "Forcing Ring API session refresh" (and usually "Session hardware_id
185
+ not found" as Ring meets the new identity), and the setting turns itself off once the new sign-in
186
+ is saved. Then, in
187
+ the Ring app's Control Center, remove the older `homebridge-ring-secure-video` entry from
188
+ Authorized Client Devices.
189
+
190
+ With **Automatic Ring Session Refresh** on (the default) and the motion history fallback on, the
191
+ plugin does step 2 by itself when Ring's event history shows 3 motion events over at least 30
192
+ minutes that Ring sent no push notification for, and no push arrived in between. Events while
193
+ motion is snoozed, and events Ring saw no person in (which Smart Alerts may keep quiet), are not
194
+ counted. The log then says "Ring event history shows motion that Ring sent no push notification
195
+ for", and as a child bridge it restarts (on the main bridge, the refresh waits for the next
196
+ Homebridge restart, and is dropped if a push arrives first). It does this at most once a day, and
197
+ stops after 2 refreshes that brought no motion push notification, logging "Ring still sends no
198
+ push notifications after 2 automatic Ring session refreshes": then check step 1 and Authorized
199
+ Client Devices. If you have Ring send no motion alerts on purpose (for example in some Modes, or on
200
+ a schedule), turn the setting off, or the plugin will take the missing alerts for a fault.
201
+
202
+ Use the "Force Ring ..." settings only for this, and only once. Each API session refresh, automatic
203
+ or not, adds an entry to Authorized Client Devices, and many entries can themselves make Ring stop
204
+ sending notifications, so after one remove the older `homebridge-ring-secure-video` entry (after
205
+ an automatic refresh the log says "Automatic Ring session refresh done", and the optional
206
+ `sessionRefreshSensor` opens in the Home app). It also
207
+ changes the identity that other Ring plugins in the same Homebridge (such as homebridge-ring) will
208
+ use the next time they sign in from scratch, since they share `.ring.json`.
176
209
 
177
210
  ## Disclaimer
178
211
 
@@ -36,7 +36,7 @@
36
36
  "profile": {
37
37
  "title": "Media profile",
38
38
  "type": "string",
39
- "default": "adaptive",
39
+ "description": "Defaults to the HKSV Performance Mode (rpi gives lowPower, quality gives quality), otherwise adaptive.",
40
40
  "oneOf": [
41
41
  { "title": "adaptive", "enum": ["adaptive"] },
42
42
  { "title": "lowPower", "enum": ["lowPower"] },
@@ -152,16 +152,28 @@
152
152
  "type": "boolean",
153
153
  "description": "Advanced recovery option: rotates the Ring API hardware/session identity and forces fresh push credentials on next startup. Try this when refreshing only Ring push credentials still leaves motion/button events delayed or missing. The option clears itself after the updated refresh token is saved. The identity is stored in .ring.json in the Homebridge storage folder, which other Ring plugins in the same Homebridge (such as homebridge-ring) also use, so rotating it can affect their sign-in."
154
154
  },
155
+ "automaticSessionRefresh": {
156
+ "title": "Automatic Ring Session Refresh",
157
+ "type": "boolean",
158
+ "description": "When Ring's event history shows motion but Ring has sent the plugin no push notification for it (3 events over at least 30 minutes, none pushed), the plugin does a Ring API session refresh by itself, as Force Ring API Session Refresh does: as a child bridge it restarts, otherwise at the next restart of Homebridge. Events while motion is snoozed or without a person are not counted. At most once a day, and no more after 2 that brought no push notification. Needs the camera motion history fallback. Turn this off if Ring is set to send no motion alerts in some Modes or on a schedule. Each refresh adds an entry to Authorized Client Devices in the Ring app (remove the older homebridge-ring-secure-video entries) and changes the identity in .ring.json, which other Ring plugins in the same Homebridge also use.",
159
+ "default": true
160
+ },
161
+ "sessionRefreshSensor": {
162
+ "title": "Session Refresh Sensor",
163
+ "type": "boolean",
164
+ "description": "Adds a \"Ring Session Refreshed\" contact sensor that opens after an automatic Ring session refresh (10 s after the Home app is connected to it, within 3 minutes) and stays open for a day, so the Home app can notify you (turn on its notifications; needs a home hub): then remove the older homebridge-ring-secure-video entry from Authorized Client Devices in the Ring app. Needs Automatic Ring Session Refresh.",
165
+ "default": false
166
+ },
155
167
  "enableCameraMotionHistory": {
156
168
  "title": "Enable Camera Motion History Fallback",
157
169
  "type": "boolean",
158
- "description": "If enabled, cameras can synthesize motion from recent Ring event history when live push notifications are missing or stale. Disable this if you only want motion triggered by Ring notifications.",
170
+ "description": "If enabled, cameras can synthesize motion from recent Ring event history when push notifications don't arrive. The history is checked frequently until push is seen to work, then every 5 minutes as a safety net. Disable this if you only want motion triggered by Ring notifications.",
159
171
  "default": true
160
172
  },
161
173
  "disableHksvOnBattery": {
162
174
  "title": "Disable HKSV On Battery Cameras",
163
175
  "type": "boolean",
164
- "description": "If enabled, HKSV is disabled on battery-powered cameras to reduce battery and network impact.",
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.",
165
177
  "default": true
166
178
  },
167
179
  "hksvPrebufferLengthMs": {
@@ -189,7 +201,7 @@
189
201
  "hksvPerformanceMode": {
190
202
  "title": "HKSV Performance Mode",
191
203
  "type": "string",
192
- "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.",
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 the codec set to libx264.",
193
205
  "default": "balanced",
194
206
  "oneOf": [
195
207
  {
@@ -225,8 +237,7 @@
225
237
  "type": "integer",
226
238
  "minimum": 256,
227
239
  "maximum": 12000,
228
- "default": 3000,
229
- "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."
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."
230
241
  },
231
242
  "hksvVideoMaxBitrateKbps": {
232
243
  "title": "HKSV Max Video Bitrate (kbps)",
@@ -308,7 +319,7 @@
308
319
  "cameraVideoCodec": {
309
320
  "title": "Camera Video Codec",
310
321
  "type": "string",
311
- "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.",
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 with libx264; copy and h264_v4l2m2m are not verified yet.",
312
323
  "oneOf": [
313
324
  {
314
325
  "title": "auto",
@@ -485,6 +496,8 @@
485
496
  "media",
486
497
  "forceRefreshRingPushCredentials",
487
498
  "forceRefreshRingApiSession",
499
+ "automaticSessionRefresh",
500
+ "sessionRefreshSensor",
488
501
  "enableCameraMotionHistory",
489
502
  "disableHksvOnBattery",
490
503
  "hksvVideoPreset",
@@ -225,46 +225,79 @@ class StreamingSessionWrapper {
225
225
  // deSerialize will sometimes fail, but the errors can be ignored
226
226
  }
227
227
  return null;
228
- }), releaseReturnAudioFfmpeg = hksvRecordingQueue.trackFfmpegProcess(), returnAudioTranscoder = new ReturnAudioTranscoder({
229
- prepareStreamRequest: getReturnAudioPrepareStreamRequest(this.prepareStreamRequest),
230
- startStreamRequest: request,
231
- incomingAudioOptions: {
232
- ssrc: this.audioSsrc,
233
- rtcpPort: 0, // we don't care about rtcp for incoming audio
234
- },
235
- outputArgs: [
236
- '-acodec',
237
- 'libopus',
238
- '-application',
239
- 'lowdelay',
240
- '-frame_duration',
241
- '60',
242
- '-flags',
243
- '+global_header',
244
- '-ar',
245
- '48k',
246
- '-b:a',
247
- '48k',
248
- '-bufsize',
249
- '192k',
250
- '-ac',
251
- '2',
252
- '-f',
253
- 'rtp',
254
- `rtp://127.0.0.1:${await returnAudioTranscodedSplitter.portPromise}`,
255
- ],
256
- ffmpegPath: getFfmpegPath(),
257
- exitCallback: () => {
258
- releaseReturnAudioFfmpeg();
259
- this.stop();
260
- },
261
- logger: {
262
- info: logDebug,
263
- error: logError,
264
- },
265
- logLabel: `Return Audio (${this.ringCamera.name})`,
266
- returnAudioSplitter: this.audioSplitter,
267
228
  });
229
+ // Port first, so a failure here leaves nothing counted or open.
230
+ let returnAudioPort;
231
+ try {
232
+ returnAudioPort = await returnAudioTranscodedSplitter.portPromise;
233
+ }
234
+ catch (e) {
235
+ returnAudioTranscodedSplitter.close();
236
+ throw e;
237
+ }
238
+ if (this.stopped) {
239
+ returnAudioTranscodedSplitter.close();
240
+ throw getLiveStreamAbortError();
241
+ }
242
+ const releaseReturnAudioFfmpeg = hksvRecordingQueue.trackFfmpegProcess();
243
+ let returnAudioTranscoder;
244
+ try {
245
+ returnAudioTranscoder = new ReturnAudioTranscoder({
246
+ prepareStreamRequest: getReturnAudioPrepareStreamRequest(this.prepareStreamRequest),
247
+ startStreamRequest: request,
248
+ incomingAudioOptions: {
249
+ ssrc: this.audioSsrc,
250
+ rtcpPort: 0, // we don't care about rtcp for incoming audio
251
+ },
252
+ outputArgs: [
253
+ '-acodec',
254
+ 'libopus',
255
+ '-application',
256
+ 'lowdelay',
257
+ '-frame_duration',
258
+ '60',
259
+ '-flags',
260
+ '+global_header',
261
+ '-ar',
262
+ '48k',
263
+ '-b:a',
264
+ '48k',
265
+ '-bufsize',
266
+ '192k',
267
+ '-ac',
268
+ '2',
269
+ '-f',
270
+ 'rtp',
271
+ `rtp://127.0.0.1:${returnAudioPort}`,
272
+ ],
273
+ ffmpegPath: getFfmpegPath(),
274
+ exitCallback: () => {
275
+ releaseReturnAudioFfmpeg();
276
+ this.stop();
277
+ },
278
+ logger: {
279
+ info: logDebug,
280
+ error: logError,
281
+ },
282
+ logLabel: `Return Audio (${this.ringCamera.name})`,
283
+ returnAudioSplitter: this.audioSplitter,
284
+ });
285
+ }
286
+ catch (e) {
287
+ releaseReturnAudioFfmpeg();
288
+ returnAudioTranscodedSplitter.close();
289
+ throw e;
290
+ }
291
+ // @homebridge/camera-utils' ffmpeg has no 'error' listener: a failed start (no ffmpeg, too
292
+ // many processes) would be an unhandled 'error' event and end the whole bridge, alarm
293
+ // included. Its spawn errors arrive on the next tick, so listening now is in time.
294
+ const returnAudioFfmpeg = returnAudioTranscoder.ffmpegProcess?.ff;
295
+ for (const emitter of [returnAudioFfmpeg, returnAudioFfmpeg?.stdout, returnAudioFfmpeg?.stderr]) {
296
+ emitter?.on('error', (error) => {
297
+ logError(`Return Audio (${this.ringCamera.name}): ${error.message}`);
298
+ this.stop();
299
+ });
300
+ }
268
301
  this.streamingSession.onCallEnded.pipe(take(1)).subscribe(() => {
269
302
  returnAudioTranscoder.stop();
270
303
  returnAudioTranscodedSplitter.close();
@@ -277,6 +310,9 @@ class StreamingSessionWrapper {
277
310
  });
278
311
  this.listenForAudioPackets(request);
279
312
  await returnAudioTranscoder.start();
313
+ // A talk-back ffmpeg that failed to start stopped the stream meanwhile: report it to HomeKit.
314
+ if (this.stopped)
315
+ throw getLiveStreamAbortError();
280
316
  }
281
317
  stop() {
282
318
  if (this.stopped) {
@@ -329,10 +365,20 @@ export function getHksvRecordingFormatArguments(configuration, videoArguments, c
329
365
  // Raspberry Pi's V4L2 encoder) otherwise leave an empty avcC, and HomeKit can't decode the
330
366
  // recording. The first media fragment arrives no later than before.
331
367
  export const HKSV_RECORDING_MOVFLAGS = 'frag_keyframe+empty_moov+default_base_moof+delay_moov';
368
+ /**
369
+ * Whether a camera gets HomeKit Secure Video. Unset settings mean what the settings form shows:
370
+ * HKSV on, except for cameras running on battery (each recording opens a Ring live call, which
371
+ * drains it). A battery model that is wired, like many doorbells, counts as wired.
372
+ */
373
+ export function isHksvEnabled(config, operatingOnBattery) {
374
+ return (config.enableHksv !== false &&
375
+ !(config.disableHksvOnBattery !== false && operatingOnBattery));
376
+ }
332
377
  export class CameraSource {
333
378
  controller;
334
379
  sessions = {};
335
380
  cachedSnapshot;
381
+ cachedSnapshotAt = 0;
336
382
  ringCamera;
337
383
  config;
338
384
  mediaIngress;
@@ -345,7 +391,7 @@ export class CameraSource {
345
391
  this.ringCamera = ringCamera;
346
392
  this.config = config;
347
393
  this.mediaIngress = new RingMediaIngress(ringCamera);
348
- const enableHksv = config.enableHksv && !(config.disableHksvOnBattery && ringCamera.hasBattery);
394
+ const enableHksv = isHksvEnabled(config, ringCamera.operatingOnBattery);
349
395
  const controllerOptions = {
350
396
  cameraStreamCount: enableHksv ? 1 : 10,
351
397
  delegate: this,
@@ -512,6 +558,7 @@ export class CameraSource {
512
558
  try {
513
559
  const previousSnapshot = this.cachedSnapshot, newSnapshot = await this.ringCamera.getSnapshot({ uuid: imageUuid });
514
560
  this.cachedSnapshot = newSnapshot;
561
+ this.cachedSnapshotAt = Date.now();
515
562
  logDebug(`Snapshot cached for ${this.ringCamera.name}${imageUuid ? ' by uuid' : ''} (${getDurationSeconds(start)}s)`);
516
563
  }
517
564
  catch (e) {
@@ -535,7 +582,13 @@ export class CameraSource {
535
582
  if (!this.ringCamera.hasSnapshotWithinLifetime) {
536
583
  this.loadSnapshot().catch(logError);
537
584
  }
538
- // may or may not have a snapshot cached
585
+ // May or may not have a snapshot cached. A failed load keeps the last one for a while, but
586
+ // not past Ring's snapshot lifetime plus 2 minutes (as upstream): an hours-old image would
587
+ // look current in the Home app.
588
+ if (this.cachedSnapshot &&
589
+ Date.now() - this.cachedSnapshotAt > this.ringCamera.snapshotLifeTime + 2 * 60_000) {
590
+ return undefined;
591
+ }
539
592
  return this.cachedSnapshot;
540
593
  }
541
594
  async handleSnapshotRequest(request, callback) {