Turn any camera stream into HomeKit motion sensors with local YOLO object
detection for 🐶 Animals, 📦 Packages, 🧍 People, 🚗 Vehicles.
- Open the Plugins tab in the Homebridge UI.
- Search for
homebridge-stream-sensors. - Click Install.
npm install -g homebridge-stream-sensorsConfigure everything from the plugin settings form.
- Add a video stream.
- Paste your camera/stream URL.
- Tick the categories you want.
- Click Save.
Add a StreamSensors platform to your Homebridge config. Each stream is one camera; each sensor fires when any of its selected categories is detected.
{
"platforms": [
{
"platform": "StreamSensors",
"streams": [
{
"name": "Front Door",
"url": "rtsp://user:password@192.168.1.50:8554/stream",
"sensors": [
{ "categories": ["people", "packages"] },
{ "categories": ["vehicles"], "threshold": 0.6 }
]
}
]
}
]
}name— used as a prefix for auto-named sensors (e.g.Front Door People & Packages Sensor).url— any ffmpeg-readable stream URL (RTSP is typical).categories— one or more ofanimals,packages,people,vehicles. The sensor triggers on any of them.threshold(optional) — detection confidence from 0–1 (default0.5). Lower is more sensitive.
Most cameras expose an RTSP URL — paste it as the stream URL. The exact path varies by brand, model, and firmware, so when in doubt look your model up in a community database like the iSpy camera connection database or your camera's manual.
Common RTSP URL patterns (replace user, pass, and the IP address):
| Brand | Main stream | Substream (low-res) |
|---|---|---|
| Reolink | rtsp://user:pass@IP:554/h264Preview_01_main |
rtsp://user:pass@IP:554/h264Preview_01_sub |
| Hikvision | rtsp://user:pass@IP:554/Streaming/Channels/101 |
rtsp://user:pass@IP:554/Streaming/Channels/102 |
| Dahua / Amcrest | rtsp://user:pass@IP:554/cam/realmonitor?channel=1&subtype=0 |
rtsp://user:pass@IP:554/cam/realmonitor?channel=1&subtype=1 |
| TP-Link Tapo | rtsp://user:pass@IP:554/stream1 |
rtsp://user:pass@IP:554/stream2 |
- UniFi Protect — enable RTSP on the camera in the Protect app (Settings → Advanced), which generates a per-camera
rtsps://…:7441/…URL to paste here. - ONVIF cameras — if you can't find the path, an ONVIF discovery tool (e.g. ONVIF Device Manager) will report the exact RTSP URL.
- Wyze — RTSP requires Wyze's separate RTSP firmware, which is unofficial and unmaintained; a standalone bridge that re-exposes the camera as RTSP is more reliable.
- Docker — no special config needed: the plugin forces RTSP over TCP, which avoids the dropped-UDP-media problem common on Docker's bridge network.
Point the plugin at your camera's substream (the low-resolution secondary stream) when one is available. Every frame is downscaled to a fixed size before inference, so a substream doesn't lower the inference cost — but it does cut the ffmpeg decode and network load, which is the main per-stream CPU cost on a busy host. Switch to the main stream only if the substream is too low-resolution to detect your subjects reliably.
Detection is CPU-intensive and each stream runs its own decode + inference loop. As soon as you add a second or third camera, run this plugin as a child bridge: it isolates the plugin in its own process, so a busy detection loop can't slow the rest of Homebridge down — and a crash can't take Homebridge with it.
- Homebridge v1.8 or newer
- Node.js v20 or newer
- A supported platform (see below)
- A camera or video stream URL that ffmpeg can open (RTSP, etc.)
- Enough CPU headroom for inference — each camera stream runs one detection pass per sampling interval
A bundled static ffmpeg binary and the ONNX runtime are installed automatically; there's no separate setup.
The on-device detector uses onnxruntime-node, which ships prebuilt native binaries only for:
| OS | Architectures |
|---|---|
| macOS | x64, arm64 |
| Linux | x64, arm64 |
| Windows | x64, arm64 |
There is no build for 32-bit ARM (armv7/armhf) — including the legacy 32-bit Raspberry Pi OS. On a Raspberry Pi, install the 64-bit (arm64) Raspberry Pi OS. On an unsupported platform the plugin logs a clear error and stays idle rather than crashing Homebridge.
- Frames are decoded with ffmpeg and analyzed with a local YOLO26n ONNX model, entirely inside your Homebridge environment — they are never uploaded to any cloud service.
- Each frame is resized to a fixed input size before inference, so per-frame cost is the same regardless of your camera's resolution. The plugin samples the stream at a modest interval and only ever processes the latest frame.
- The main cost driver is the number of camera streams (each runs its own detection loop), not how many sensors a stream has. Start with one stream and grow from there.
- Sensor doesn't appear in HomeKit — confirm the stream has at least one sensor with valid categories, then restart Homebridge.
- Stream won't open / "no frames" — verify the URL works in another player. For RTSP cameras the plugin uses TCP transport, which is the most compatible.
- ffmpeg can't decode the stream — check the URL, credentials, and that the camera is reachable from the Homebridge host (use an IP address if a hostname won't resolve).
- Too many false triggers — raise the sensor's
threshold. - Detections are missed — lower the
threshold, or make sure the subject is large enough in frame. - Homebridge feels sluggish — detection is CPU-intensive. Try running this plugin as a child bridge to isolate it in its own process, and/or reduce the number of streams.
Licensed under AGPL-3.0-only — free to use, study, and build on. Contributions and forks are welcome; please keep them under the same license terms.
Issues and camera-compatibility reports are appreciated. When reporting a problem, please include your Homebridge version, plugin version, platform, stream type, and relevant logs. Focused, maintainable pull requests are welcome.
If this plugin helps your HomeKit setup, please consider starring the repo — it helps others discover the project.