homebridge-unifi-protect is a Homebridge plugin that provides HomeKit support to the UniFi Protect device ecosystem. UniFi Protect is Ubiquiti's video security platform, with rich camera, doorbell, and NVR controller hardware options for you to choose from, as well as an app which you can use to view, configure and manage your video camera and doorbells.
This plugin will attempt to autoconfigure all devices it detects attached to a UniFi Protect controller in order to create a more seamless end user experience. In order to do so, the UniFi Protect controller local user account that you configure this plugin to use utilizes the full management role enabled for UniFi Protect. Enabling the full management role is optional and primarily required if you want this plugin to configure your UniFi Protect controller to make all RTSP streams available and providing some of the functionality you can selectively enable in additional feature options. You can also choose to manually enable all RTSP streams on all cameras yourself, if you prefer.
Why is enabling all RTSP streams a good idea? There's no performance penalty on the Protect controller end. More importantly, it provides flexibility in the stream quality that's available to use in HBUP which you can further tailor in a granular way using feature options. For this plugin to work correctly, you will need to enable at least one RTSP stream on each camera that you want to see in HomeKit.
Which leads to the final point on autoconfiguration - sane defaults. This plugin's north star is to make it as easy and seamless to integrate with HomeKit as possible in order to provide a terrific user experience -- and that includes great video streaming performance. By default, this plugin dynamically selects the best streaming quality to use by understanding HomeKit's limitations and using the RTSP profile (High, Medium, or Low) that most closely resembles the quality being requested by the streaming client.
Of course, you can override which RTSP profiles are used in your specific environment. See the video section of the HBUP feature options webUI for more detail.
Consistent with the ethos of this plugin, HBUP always strives to default to combining the highest possible quality combined with the best quality that can be delivered within the performance capabilities of the hardware environment HBUP is run on.
Briefly:
- Transcoding involves a CPU-intensive conversion of a video stream from one format or quality level to another. The process can be made significantly faster (with caveats and compromises) and less resource intensive through the use of GPU hardware acceleration.
- Transmuxing involves repackaging a video stream from one container format or another. No change in format or quality occurs. Notably, it is not a resource intensive activity.
Here are the rules that are used by default to decide when to transcode and when to transmux:
- At home, on a local network, livestreams are transmuxed rather than transcoded by default. HBUP will select the Protect stream that is closest to the resolution that HomeKit is requesting without exceeding the requested resolution, when available. This results in high quality video with low latency being streamed to clients - with the exception of the Apple Watch. Apple Watch clients will always receives transcoded video due to Watch hardware constraints.
- When away from home, Apple Watch, or on a high-latency connection (as decided upon by HomeKit, not HBUP), livestreams are transcoded.
The defaault behavior can be tailored to your preferences, using the appropriate feature options.
When transcoding, these are the rules used to determine which Protect camera streams (Protect has three stream qualities available: High, Medium, and Low) are used for transcoding.
- If you’re on a hardware accelerated platform, we always use the highest quality camera stream that's available to us as a starting point when transcoding. It always yields better performance and quality results for fixed-function hardware transcoders (e.g. most GPUs).
- If you’re not on a hardware accelerated platform, we always try to match the quality that’s being requested, with a bias of going higher versus lower, and then passing that along to the software transcoder.
- By default, the highest available stream quality is used to give you the best event recording output you can get before HomeKit further processes and compresses it.
- On Raspberry Pi platform, the software interface to the onboard GPU transcoder has issues dealing with very high bitrate stream quality and HBUP will default to a starting point of Medium because of those capability constraints.
All of the behavior described above can be tailored to your environment and taste through the HBUP feature options webUI. Specifically, you can:
- Choose to transcode instead of transmux for local clients or not. Default: transmux local clients.
- Choose to transmux instead of transcode for high-latency / remote clients. Default: transcode high-latency / remote clients.
- Which Protect stream qualities to make available for HBUP. Default: all stream qualities are available (High, Medium, and Low) that are configured on the Protect camera.
- Bypass the intelligence applied by HBUP when selecting which Protect stream quality to use for transcoding livestreams by forcing the use of a specific Protect stream quality. Default: HBUP will decide based on the transcoding rules above.
- Change the Protect stream quality used for HomeKit Secure Video event recording. Default: HBUP will use the highest quality Protect stream available.
In general, I would discourage most users from changing the defaults unless they have a specific need to do so. But if you're reading this, probably like to tinker with things. 😄 I have taken a lot of time and care to design these behaviors and defaults - they really do exist for good reasons.