homebridge-camera-onvif

ONVIF-native camera platform for Homebridge.

This plugin discovers camera channels from one or more ONVIF NVRs or standalone cameras, resolves their RTSP streams through ONVIF, and exposes them as HomeKit camera accessories. HomeKit live view and HomeKit Secure Video use the same ffmpeg-based streaming and recording pipeline as the standard Homebridge camera plugins, while discovery and motion eventing come from ONVIF instead of static per-camera RTSP configuration.

Features

• Multi-source ONVIF discovery with one config entry per NVR or camera.
• Per-channel HomeKit accessories with stable identities.
• Main/sub stream selection for live view and HKSV recording.
• ONVIF PullPoint event polling for motion, person, vehicle, and face topics, mapped to HomeKit motion events.
• Optional HomeKit Secure Video recording with continuous prebuffer.
• Per-stream rotation and aspect-ratio correction for cameras whose encoded video does not match reported metadata.
• Custom Homebridge UI for discovery, naming, stream selection, and common advanced settings.
• Manual local HTTP motion trigger endpoint for testing.

Configuration

Use the plugin settings page in Homebridge whenever possible. The settings page can discover channels from an ONVIF source and write the sources and cameras entries for you.

Minimal JSON shape:

{
  "platform": "Camera-ONVIF",
  "name": "Camera ONVIF",
  "sources": [
    {
      "host": "192.168.1.10",
      "port": 8000,
      "username": "camera-user",
      "password": "camera-password"
    }
  ],
  "defaults": {
    "streamQuality": "sub",
    "recordingStreamQuality": "same",
    "recording": true,
    "audio": true
  },
  "cameras": [
    {
      "sourceHost": "192.168.1.10",
      "sourcePort": 8000,
      "channelToken": "000",
      "name": "Front Door"
    }
  ]
}

Notes

• ONVIF GetStreamUri often returns RTSP URLs without credentials. The plugin adds the configured ONVIF username/password to the RTSP URL before passing it to ffmpeg, and redacts credentials from logs.
• ONVIF devices differ in how reliably they support WS-Discovery and PullPoint event polling. Manual host entry is the reliable discovery path.
• HomeKit camera pairing state is controlled by Homebridge/HAP. If Apple Home keeps broken state for a camera, set homekitId on that camera to intentionally publish it as a fresh accessory identity.

Development

npm install
npm test
npm run build

Packaging for a Homebridge host:

npm pack