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

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # homebridge-ring-secure-video
 
+## 1.0.0 (2026-11-14)
+
+First stable release. Compared with homebridge-ring 14.3.0, it adds HomeKit Secure Video
+recording with media profiles (`media`), a separate motion sensor per camera for instant
+notifications, motion from Ring's event history when push notifications fail, automatic Ring
+session refresh with an optional sensor, an optional recording on doorbell press, Ring Intercom
+Video as a camera, and the fixes listed in the betas below. Every homebridge-ring setting is
+available with the same name. Tested on a Raspberry Pi 4 (Node 22, Homebridge 2.5) with a Ring
+Video Doorbell 3 Plus, Ring Alarm and 21 sensors.
+
+Changes since 1.0.0-beta.7:
+
+**Fixes:**
+
+- A packet on a live view's audio port that isn't valid RTP no longer stops Homebridge (any
+  device on the network could send one). Any other error that would have reached rxjs's
+  unhandled-error handler (which stops Homebridge) is logged instead; if it ended a stream, such
+  as a live view's audio, only that stream stops.
+- Ring Intercom Video: a pre-warmed live call that fails no longer stops Homebridge, and the
+  recording starts its own call; an unclaimed pre-warmed call is stopped after 20 s without
+  stopping a call a recording took meanwhile. Pre-warming happens only with HKSV recording on.
+  The check for an active ding runs only for Intercom Video (audio intercoms get dings by push),
+  every 5 s instead of 3 s, and a slow check no longer has its answer dropped when the next is
+  due.
+- A renewed Ring token is saved only into this plugin's platform block. Before, if no block of
+  this plugin had the old token (it was changed in the settings meanwhile, or only another
+  plugin's block had it, such as homebridge-ring set up with the same token), it was written by
+  text replace, possibly into the other plugin's block; now config.json is left as it is, and
+  "Could not save a new Ring token" is logged once.
+- When Homebridge shuts down, live views, talk-back, recordings and Ring calls are ended and the
+  plugin disconnects from Ring, instead of leaving them running until the process exits.
+- With `codec` set to `auto` (the default outside `lowPower`), recordings on a PC, Docker, a NAS
+  or a Raspberry Pi 5 no longer fail by picking the Raspberry Pi 4 hardware encoder
+  (`h264_v4l2m2m`) just because FFmpeg lists it: it is picked only on Linux with a video encoder
+  device Homebridge can open, and `h264_videotoolbox` only on a Mac; otherwise `auto` picks
+  `libx264`. The check now asks the FFmpeg that records (the one bundled with the plugin, or the
+  one set with `ffmpegPath`) instead of a system `ffmpeg`, and gives up after 10 s instead of
+  holding recordings if FFmpeg hangs; a check that fails is logged and tried again 5 minutes
+  later. FFmpeg is only asked when `auto` has to choose (not with `lowPower` or a set codec).
+
+**Settings form and docs:**
+
+- "Custom FFmpeg Path" is in the settings form again (it was only in the JSON editor), and CI
+  now fails if a setting is left out of the form. Settings are grouped by topic, the hide-camera
+  settings have descriptions (hiding the camera motion sensor also stops HKSV recordings), and
+  the prebuffer setting no longer suggests it adds video from before the motion.
+- The README shows the plugin's own icon instead of the "Homebridge x Ring" logo; Ring's logo
+  and unused upstream images are removed and no longer in the npm package. The README says which
+  setups are tested and which aren't.
+
+**Other:** unused code removed; the encoder check runs FFmpeg once instead of twice.
+
+**Known:** `npm audit --omit=dev` reports one high-severity advisory for `ip`
+(GHSA-2p57-rm9w-gvfp), listed against `ip`, `werift` and ring-client-api 14.3.0. It concerns
+`ip.isPublic`, which werift doesn't call, so the plugin isn't affected; it goes away with
+ring-client-api 15 and the werift 0.26 it uses.
+
+## 1.0.0-beta.7 (2026-11-14)
+
+**Changes in behaviour to check after updating:**
+
+- The flat recording settings are removed: `hksvPerformanceMode`, `cameraVideoCodec`,
+  `hksvVideoBitrateKbps`, `hksvVideoMaxBitrateKbps`, `hksvVideoBufferSizeKbps`, `hksvVideoCrf`,
+  `hksvVideoPreset`, `hksvVideoKeyframeInterval`, `hksvPrebufferLengthMs`,
+  `hksvFragmentLengthMs`, `hksvMaxRecordingSeconds`, `hksvMaxQueuedBytes` and
+  `hksvMaxConcurrentRecordings`. Recording is set up only in `media` ("Recording Settings" in
+  the plugin settings), which has each of them with the same allowed values
+  (`hksvPerformanceMode`'s `balanced`/`rpi`/`quality` become `media.profile`'s
+  `adaptive`/`lowPower`/`quality`); the README has a table of what replaces what. A removed
+  setting left in a config is ignored, with a warning at start naming it and its replacement:
+  move its value if needed, then delete it in the JSON editor. Configs last saved from the
+  settings form in beta.6 or earlier usually contain `hksvPerformanceMode` and
+  `hksvVideoKeyframeInterval` (the form filled them in), so expect those two warnings. Without `media.profile` the profile is `adaptive`, so a config that only had
+  `"hksvPerformanceMode": "rpi"` needs `"media": { "profile": "lowPower" }`.
+- The recording log line says `profile=lowPower`, `adaptive` or `quality` instead of
+  `mode=rpi`, `balanced` or `quality`.
+
+**Fixes** (from homebridge-ring 15.0.0-beta.0):
+
+- A volume, brightness, dimmer or fan-speed change that Ring rejects no longer crashes
+  Homebridge (and with it the plugin's bridge); it is logged, and the value goes back to the last
+  level Ring reported, unless a newer change was sent meanwhile (dgreif/ring#1892).
+- A Ring mode change (Home, Away, Disarmed) from HomeKit that Ring rejects no longer crashes
+  Homebridge; it is logged, and the target goes back to the mode Ring reports. A pending Home (Stay) target is no
+  longer overwritten by another mode report before Ring confirms it, and an older request
+  failing late no longer undoes a newer one (dgreif/ring#1871).
+- A Ring token without its refresh token (from a sign-in response that couldn't be read, seen
+  with unsupported Node.js versions) is no longer saved over a working one (which made every
+  later start fail until signing in again) or used for reconnecting; the working token is kept,
+  and the error is logged once per run (the plugin's side of dgreif/ring#1886).
+
+**Docs:**
+
+- The settings form calls `media` "Recording Settings", "Enable HKSV" is no longer marked
+  experimental, and the settings' descriptions carry the Raspberry Pi advice, bitrate ranges,
+  verified codecs and each profile's defaults.
+- README: a fuller disclaimer, and in "Origin and Attribution" the versions this started from
+  and where to report problems.
+
 ## 1.0.0-beta.6 (2026-11-13)
 
 **Changes in behaviour to check after updating:**

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img alt="Homebridge x Ring" src="branding/Homebridge_x_Ring.svg" width="500px">
+  <img alt="Ring Secure Video" src="https://raw.githubusercontent.com/zmanuel1234/homebridge-ring-secure-video/main/branding/homebridge-ring-secure-video.svg" width="150">
 </p>
 
 # homebridge-ring-secure-video
@@ -13,11 +13,10 @@ It is meant to replace `homebridge-ring` on its own: one plugin, one Ring sign-i
 
 ## What it adds to homebridge-ring
 
-Everything `homebridge-ring` exposes is here too (it is not a drop-in swap, though: the plugin and
-platform names differ, so its accessories are new to HomeKit and are set up again), plus:
+Everything `homebridge-ring` exposes is here too, with the same settings, plus:
 
 - **HomeKit Secure Video recording** for Ring cameras and doorbells, with media profiles for small
-  machines such as a Raspberry Pi (`media`, `hksvPerformanceMode`).
+  machines such as a Raspberry Pi (`media`).
 - **Instant motion notifications** with HKSV on: an optional separate motion sensor per camera
   (`cameraMotionNotificationSensor`), so the Home app notifies without waiting for clip analysis.
 - **Motion when Ring's push notifications fail**: motion from Ring's event history
@@ -37,34 +36,33 @@ platform names differ, so its accessories are new to HomeKit and are set up agai
 
 ## Origin and Attribution
 
-This project is based on Dusty Greif's original Ring Homebridge ecosystem:
+This is an independent project, not a GitHub fork and not maintained by the authors it builds on:
 
-- Upstream plugin and API library: [dgreif/ring](https://github.com/dgreif/ring)
-  (`homebridge-ring` and `ring-client-api`)
+- [`homebridge-ring`](https://github.com/dgreif/ring) by Dusty Greif: this plugin's accessory code
+  started from homebridge-ring 14.3.0, and it uses
+  [`ring-client-api`](https://www.npmjs.com/package/ring-client-api) 14.3.0 from npm as a
+  dependency.
+- [`homebridge-ring-hksv`](https://github.com/trinityhades/homebridge-ring-hksv) by trinityhades:
+  this plugin continues from its version 15.0.2 (HKSV recording pipeline, Ring Intercom Video).
 
-- HKSV fork: [trinityhades/homebridge-ring-hksv](https://github.com/trinityhades/homebridge-ring-hksv), whose history this repository continues
+Changes since then are listed in [CHANGELOG.md](CHANGELOG.md). Thanks to Dusty Greif, trinityhades
+and all upstream contributors.
 
-Big thanks to Dusty, trinityhades and all upstream contributors. This plugin reuses and extends that foundation.
+**Please report problems with this plugin
+[here](https://github.com/zmanuel1234/homebridge-ring-secure-video/issues), not to dgreif/ring or
+trinityhades.**
 
 ## Important Plugin Options
 
 | Option | Purpose |
 | --- | --- |
-| `enableHksv` | Enables experimental HKSV support for eligible cameras; on by default, set `false` to turn it off |
+| `enableHksv` | Enables HKSV recording for eligible cameras; on by default, set `false` to turn it off |
+| `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) |
 | `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 |
 | `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 |
 | `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 |
 | `disableHksvOnBattery` | Disables HKSV on cameras running on battery to reduce battery/network usage; wired battery models keep it. On by default |
-| `hksvPrebufferLengthMs` | HKSV prebuffer duration (minimum 4000ms) |
-| `hksvFragmentLengthMs` | HKSV fragment duration target |
-| `hksvMaxRecordingSeconds` | Optional safety cap for a recording session (default 180 s; 0 disables) |
-| `hksvPerformanceMode` | HKSV tuning profile (`balanced`, `rpi`, or `quality`) |
-| `hksvMaxConcurrentRecordings` / `hksvMaxQueuedBytes` | HKSV safeguards for small systems under load |
-| `hksvVideoBitrateKbps` / `hksvVideoMaxBitrateKbps` / `hksvVideoBufferSizeKbps` | HKSV recording bitrate controls for improving fast-motion quality |
-| `hksvVideoCrf` / `hksvVideoPreset` | Optional libx264 quality and CPU tuning controls |
-| `hksvVideoKeyframeInterval` | HKSV recording keyframe interval |
 | `homeKitAccessoryTag` | Appends a tag to accessory names and HomeKit IDs so the same Ring device can be exposed as a distinct HomeKit accessory for debugging/testing |
-| `cameraVideoCodec` | Preferred H.264 handling (`auto`, `copy`, `h264_v4l2m2m`, `h264_videotoolbox`, or `libx264`) |
 | `hideDoorbellSwitch` / `hideCameraMotionSensor` / `hideCameraSirenSwitch` | Hides specific HomeKit-exposed services |
 | `cameraMotionNotificationSensor` | Adds a separate "<camera> Motion" sensor per camera for instant motion notifications (see below) |
 | `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,20 +71,41 @@ Big thanks to Dusty, trinityhades and all upstream contributors. This plugin reu
 | `debug` | Enables additional logging |
 | `disableLogs` | Disables plugin logging |
 
-## v15 media configuration
+## Media configuration
 
-v15 uses an adaptive media engine that keeps Ring call ownership separate from
-each live-view and recording FFmpeg process. Configure `media.profile` as
-`adaptive` (default), `lowPower`, or `quality`. Advanced overrides live in
-`media.recording`; they are strictly validated and take precedence over legacy
-`hksv*` fields, which remain compatibility aliases during migration. Set
+Recording is set up in `media` ("Recording Settings" in the plugin settings). The media engine
+keeps the Ring call separate from each live-view and recording FFmpeg process. Set
+`media.profile` to `adaptive` (default), `lowPower` or `quality`. Advanced settings live in
+`media.recording`; each is validated, and an unusable value is ignored with a warning. Set
 `media.recording.maxDurationSeconds` to change its safety cap (default 180 seconds; HomeKit
 normally ends a recording itself when motion stops), or to `0` to disable it.
 
+### Settings removed in 1.0.0
+
+The flat recording settings from earlier versions were removed in 1.0.0; `media` replaces each
+of them, with the same allowed values (except `hksvPerformanceMode`, whose values are renamed as
+shown). A removed setting left in a config is ignored, and the log says which one and what
+replaces it: move its value there if it isn't set there yet, then delete it in the JSON editor.
+Without `media.profile`, the profile is `adaptive`, so a config that only had
+`"hksvPerformanceMode": "rpi"` needs `"media": { "profile": "lowPower" }`.
+
+| Removed setting | Use instead |
+| --- | --- |
+| `hksvPerformanceMode` (`balanced`, `rpi`, `quality`) | `media.profile` (`adaptive`, `lowPower`, `quality`) |
+| `cameraVideoCodec` | `media.recording.codec` |
+| `hksvVideoBitrateKbps` / `hksvVideoMaxBitrateKbps` / `hksvVideoBufferSizeKbps` | `media.recording.bitrateKbps` / `maxBitrateKbps` / `bufferSizeKbps` |
+| `hksvVideoCrf` / `hksvVideoPreset` | `media.recording.crf` / `preset` |
+| `hksvVideoKeyframeInterval` | `media.recording.keyframeInterval` |
+| `hksvPrebufferLengthMs` / `hksvFragmentLengthMs` | `media.recording.prebufferLengthMs` / `fragmentLengthMs` |
+| `hksvMaxRecordingSeconds` | `media.recording.maxDurationSeconds` |
+| `hksvMaxQueuedBytes` / `hksvMaxConcurrentRecordings` | `media.recording.maxQueuedBytes` / `maxConcurrentRecordings` |
+
+`media.recording.rateControl` (`vbr` or `cbr`) had no flat setting.
+
 ## Installation
 
-Requires Node.js 22 or 24 and Homebridge 1.8 or later (2.x recommended). If Homebridge is installed
-globally:
+Requires Node.js 22 or 24 and Homebridge 1.8 or later (tested with 2.5; 1.8 is supported but not
+tested). If Homebridge is installed globally:
 
 ```bash
 npm i -g homebridge-ring-secure-video
@@ -141,11 +160,15 @@ Changing `homeKitAccessoryTag` updates both the exposed accessory name and the g
 
 ## HKSV Status
 
-HKSV support is experimental and actively evolving. Behavior may vary by camera model, wired vs battery power, Ring API changes, and FFmpeg environment.
+Behavior may vary by camera model, wired vs battery power, Ring API changes, and FFmpeg
+environment.
 
-Verified so far: complete HomeKit clips from a Ring Video Doorbell 3 Plus on a Raspberry Pi 4
-(Node 22, Homebridge 2) with each of `copy`, `h264_v4l2m2m` and `libx264` (see below). The HKSV fork this continues reported 3 cameras on an M4 Mac mini.
-Please report your experience and setup details to help improve support.
+Tested: complete HomeKit clips from a Ring Video Doorbell 3 Plus on a Raspberry Pi 4 (Node 22,
+Homebridge 2.5) with each of `copy`, `h264_v4l2m2m` and `libx264` (see below). The HKSV fork this
+continues reported 3 cameras on an M4 Mac mini. Not tested here: other Ring cameras, battery
+cameras, Ring Intercom Video, `h264_videotoolbox` and Homebridge 1.8. Please
+[report](https://github.com/zmanuel1234/homebridge-ring-secure-video/issues) how it works with
+your setup.
 
 Recordings follow the frame rate and audio format HomeKit asks for, and include audio only when
 **Record Audio** is on in the camera's settings in the Home app.
@@ -174,7 +197,7 @@ fork).
 ### Recording codecs
 
 Only HKSV recordings are encoded; live view passes Ring's video through. `media.recording.codec`
-(or the older `cameraVideoCodec`) chooses how:
+chooses how:
 
 | Codec | What it does | CPU |
 | --- | --- | --- |
@@ -197,14 +220,16 @@ ignores all of them. The Pi's hardware encoder uses `bitrateKbps` and `keyframeI
 
 | Profile (`media.profile`) | `auto` picks |
 | --- | --- |
-| `lowPower` (also `"hksvPerformanceMode": "rpi"`) | `copy` |
-| `adaptive` (default) or `quality` | `h264_v4l2m2m` if FFmpeg has it (Raspberry Pi 4), else `h264_videotoolbox` if FFmpeg has it (Mac), else `libx264` |
+| `lowPower` | `copy` |
+| `adaptive` (default) or `quality` | `h264_v4l2m2m` on Linux with a usable video encoder device (Raspberry Pi 4), else `h264_videotoolbox` on a Mac, else `libx264` |
 
-"FFmpeg has it" means the encoder is built into FFmpeg, not that the hardware is there: on a
-Raspberry Pi 5 (no hardware encoder), set `codec` to `copy` or `libx264` rather than relying on
-`auto` in the `adaptive` and `quality` profiles. A valid legacy `cameraVideoCodec` in the config
-counts as the codec when `media.recording.codec` isn't set. The log shows the choice for each recording: `Starting HKSV recording pipeline ...
-video=<codec>`.
+A hardware encoder is picked only if the FFmpeg that records has it and the computer has the
+hardware: `h264_v4l2m2m` needs a Linux video encoder device that Homebridge can open (the Pi 4's
+`bcm2835-codec-encode`), so a Raspberry Pi 5, a PC or a NAS gets `libx264`, as does Docker unless
+the device is passed through. The log shows the choice for each recording:
+`Starting HKSV recording pipeline ... video=<codec>`. If FFmpeg doesn't answer when asked which
+encoders it has, an error is logged (the first time) and `auto` records with `libx264` until FFmpeg
+is asked again, at the first recording after 5 minutes.
 
 #### Settings verified on a Raspberry Pi 4
 
@@ -229,9 +254,6 @@ For a Raspberry Pi, start with:
 }
 ```
 
-### Minimum specifications for HKSV: 
-[TBD - will be added as more users test and report their setups]
-
 ## Troubleshooting
 
 For support and debugging:
@@ -284,10 +306,25 @@ use the next time they sign in from scratch, since they share `.ring.json`.
 
 ## Disclaimer
 
-This plugin is not affiliated with Ring or Amazon.
-
-Use emergency/panic-related automations at your own risk.
+- **Unofficial.** This plugin is not affiliated with, endorsed by or supported by Ring LLC, Amazon,
+  Apple or the Homebridge project. Ring, HomeKit and other names and logos are trademarks of their
+  owners and are used only to describe what the plugin works with.
+- **Unsupported Ring API.** It talks to Ring through the same private, undocumented API the Ring app
+  uses. Ring can change or block it at any time, and features can stop working without warning.
+- **Not a safety device.** Don't rely on it for security, alarm monitoring or emergencies. Motion,
+  doorbell presses and recordings can be late or missed (for example while a live view is open, when
+  Ring stops sending push notifications, or when the Homebridge host is offline). Use the Ring app
+  for anything that matters, and use panic or emergency automations at your own risk.
+- **Your Ring sign-in.** The Ring refresh token is stored in Homebridge's `config.json` in plain
+  text and gives access to your Ring account. Protect that file and its backups, and remove the
+  token from logs or config before sharing them. Each Ring API session refresh (automatic or
+  forced) adds an entry under Control Center > Authorized Client Devices in the Ring app; remove
+  the older one there. Removing the plugin's current entry signs it out of Ring.
+- **Recordings and privacy.** HKSV recordings are processed on your Homebridge host and stored in
+  iCloud under Apple's terms. You are responsible for following local laws on recording video and
+  audio.
+- Provided as is, without warranty. See [LICENSE](LICENSE).
 
 ## License
 
-MIT
+MIT. Copyright Dusty Greif, trinityhades and contributors, and zmanuel1234; see [LICENSE](LICENSE).