Streaming Settings
Since the most used feature of this plugin is streaming video and this topic is influenced by a lot of settings, this article is dedicated to issues you might have with streaming video through the plugin.
Eufy generally supports two streaming modes with it's cameras:
- P2P Streaming, also referenced to as 'Local Livestreams' by the plugin
- RTSP Streaming
While RTSP is only supported by some devices (e.g. Doorbells do not support this streaming method), P2P is always available.
Here is a comparision of the two for your consideration:
| Local Livestream | RTSP Stream | |
|---|---|---|
| Availablity | On all cameras | Only on some devices |
| Activation | None required | Has to be enabled through eufy app + Enable RTSP setting in the plugin |
| Downsides | If started through a homebase another camera on the same homebase cannot stream at the same time |
Not available on all devices Might interfere with some features (like HKSV) |
You can follow this guide to enable RTSP with your device. Be advised that the app seems to claim, that a NAS is required to activate this option - but in general this is not true. Activating RTSP should also be possible without owning a supported NAS.
To use your camera with the plugin it's best to set it up using the configuration wizard in Homebridge UI. Just click on settings and log in using your eufy credentials.
It should load an overview with the devices that are linked to your account. You can click on any device to access it's specific settings in the plugin. See also Installation and Configuration.
Most cameras are loaded as bare motion sensors by default. You'll have to enable the camera mode in the devices settings manually. Doorbells on the other hand are always recognized as cameras by default.
When you try to stream from a camera through HomeKit, the plugin will request the video and audio stream, or the url to the rtsp stream (see above) as input.
The chosen input will then be encoded by ffmpeg in a suitable format for HomeKit and send to the requesting device (e.g. your iPhone, iPad, ...).
This is where most of the magic happens and also where most can go wrong. Since there are a wide variety of encoding options concerning ffmpeg and performance is highly dependent on your hardware, the encoding process can be modified to some extent by the user.
Please take note of the fact that encoding video is a ressource heavy process. If you don't have powerful enough hardware it might be that some features are not available to you.
By default it will use a H264 Encoder and try to fulfill the requested streaming parameters, that were configured by the HomeKit Controller. But since this will not always be the ideal option (e.g. the encoding process might be slow on hardware like a raspberry pi), there are multiple presets you can choose from:
You can choose the different presets by selecting the device in the config ui and go to 'Advanced Video Config'. All current presets only affect the video processing for now (not audio).
-
No Preset: This is the default option. The complete input will be encoded with the
libx264codec to match the requested stream resolution, fps and bitrate. -
Preset Copy: This will forward the incoming video data to the HomeKit Controller without encoding it to the requested parameters. Since this does not run any encoding process on the video stream, this can have extreme performance and quality advantages.
However some users report frame skipping. This is likely caused by the high bitrate of the video stream which cannot be properly handled by the HomeKit Controller. You could try and reduce the stream quality in the official eufy app in that case.
Other users report no issues with this setting at all. So go ahead and test it.
Additionally the video and audio encodings will be run as separate ffmpeg proceses. This can lead to quicker stream start times. -
Preset Performance: This setting decreases the video quality to improve the performance on lower end hardware. In detail the resolution and fps are reduced. As a result the encoding process doesn't need as much ressources.
Additionally the video and audio encodings will be run as separate ffmpeg proceses. This can lead to quicker stream start times. -
Custom: You can mix any of these settings to try and get the most out of your streaming experience. Let us know if you find any settings that you think are best for encoding eufy streams to HomeKit.
| Setting | What it does |
|---|---|
| ffmpeg debug | This will write all the ffmpeg debug messages to the Homebridge log. This will clutter your log with a lot of messages while streaming, but can help if a ffmpeg process crashes. |
| use separate processes for video and audio | As the name suggests this will split the video and audio encoding onto separate processes. This can improve performance slightly, while others have reported issues with multiple ffmpeg processes running at the same time. |
| readRate | This setting tells ffmpeg to encode the input at realtime. This can almost always be ignored for streaming purposes. |
| vcodec | The codec used for video encoding. libx264 will be used by default. If you choose copy some other options will automatically disabled. |
| acodec | The codec used for audio encoding. libfdk_aac will be used by default. Other options like copy will most likely break audio streaming. |
| videoFilter | Here you can set custom video filters. See -filter:v in the ffmpeg documentation to learn more. |
| encoderOptions | Here you can set additional options for the specified codec. By default -preset ultrafast -tune zerolatency is used for libx264. |
| probeSize | Set the size of streaming data that is analyzed to get stream information |
| analyzeDuration | Set how many microseconds are analyzed to probe the input. Higher values will introduce more latency. |
| maxStreams | This setting tells the HomeKit Controller how many concurrent streams can be handled. Default: 2 |
| maxWidth & maxHeight | Set the maximum resolution |
| force crop image to requested/defined resolution | The input might be in another aspect ratio than requested by HomeKit (e.g. Doorbells may stream 1600x1200 -> 4:3 while HomeKit requests 1920x1080 -> 16:9). This setting will ensure that the requested aspect ratio is hit by cropping the image accordingly. |
| fps | Set the frames per second. |
| bitrate | Set the bitrate for video encoding. By default the bitrate requested by Homekit ist used. |
This section tries to help you if your streaming isn't working.
Try the next few advices step by step. You'll have to restart the plugin after each change and try streaming afterwards.
- Enable debug messages (you'll find the instructions here) and look for error messages in the log output
- If the log says that a ffmpeg process failed, enable
ffmpeg debugalso (see above for more detail) - If your device is connected through a Homebase try restarting the station (Cut the power and reconnect it).
Also look for a red light on the Homebase indicating an issue with the network connection. - If your device is connected through a Homebase make sure that no other device is streaming through the same Homebase at the same time (This could be the case for example if the other camera tries to get a snapshot). If you are unsure, try removing all other eufy devices temporarily from your eufy account.
- Actually disabling other devices in your account can sometimes help with the response of a camera. If nothing works, this might be worth a try.
- Don't forget to check the settings in the eufy app. There are also settings regarding video codec and quality that influence the data that the plugin receives. You can try to change the values to lower values temporarily.
- Disable all ffmpeg processes that might interfere with your main video encoding. So please,
- disable Talkback
- disable Audio
- disable HomeKit Secure Video (only beta for now)
- set the snapshot Handling method to 'Cloud Snapshots'
- If your device has this capability try
RTSPvs.Local Livestream(see above for more information) - Try different presets:
No preset,copyandPerformance - If you have the possibility try running homebridge on a more powerful computer.
If one of these steps helps with your streaming you can try and enable the other ones again.
-
There is an option in the 'Plugin Settings' that determines how long a livestream will be kept alive. Try a higher value here. (See Configuration)
-
Usually the plugin tells the device to start the local livestream which in effect sends the livestream started event and after that the video and audio data are transmitted. This error means that this procedure could not be executed sucessfully.
It can have various causes why this fails. Maybe your hardware has trouble processing the raw video data in time, or network issues prevent the livestream from starting. You can try these steps to solve this:
- Check your codec and quality settings in the official eufy App. Set them to low, and test again. This reduces the amount of data in the videostream and can mitigate the issue in that way.
- If you have really slow hardware (like a nas) it might be overloaded by the workload. Try reducing the quality settings in the devices video config. A good starting point is the 'Performance' preset.
- Check your Homebase and try to restart it. Sometimes the problem is caused by network issues. If it has a red led light, this is most likely the cause.
- In rare cases it might be, that the eufy servers blocked your public IP address from requesting anything from the servers. (This will be indicated by a red led light usually)
If that is the case a connection to the station/device might not be possible for the client. You can therefore try to reset your internet connection and get a new public IP adress.
This might be caused by restarting the plugin multiple times, so that the servers think you are not a valid user.
You can also try to login using a different eufy account. See here about adding additional accounts to your home.
-
There seems to be an issue with the virtual network drivers of Hyper-V guest systems. This causes the video data stream to fail early. You can read more about this here.
-
We use a npm package (
ffmpeg-for-homebridge) that ships with a precompiled ffmpeg executable with all necessary codecs compiled. However in rare cases it might not be recognized properly by the plugin. Some users have reported that installing the package globally can help with these issues.sudo npm install -g ffmpeg-for-homebridge -
This can have multiple causes ranging from the hardware not powerful enough to things that seem unrelated (like the snapshot handling method). Please try all the options mentioned in Basic troubleshooting above.
Since Homebridge is executing the requests in a strict order, this might also be caused by another eufy device stalling the stream request for some time. You could try 'unbridging' the device and see if this helps. See here for more details.As mentioned above Homebridge is executing the requests in a strict order. That's why snapshots can have an influence on start up times of streams. If you open the Home app HomeKit will request the latest snapshot of the camera. Some snapshot handling methods startup the camera in the background and try to get an up-to-date image. However any subsequent request (like starting a stream) is delayed until this snapshot request is fulfilled or rejected. So choosing the 'Cloud Snapshot' option ensures that snapshot requests are fulfilled as quickly as possible, hence not stalling any other requests.
-
HomeKit can be picky about the stream configuration it accepts. If your stream does not match the request from the HomeKit Controller it might well be that it decides to cancel the stream. You can try to play around with the advanced video confinguration to get it working, but there does not seem to exist an all time solution yet.
-
This is most likely caused by a firewall blocking the ffmpeg process that handles the talkback feature. Adding a firewall rule to allow this process getting and sending data packets should resolve the issue. See instructions for your OS on how to add firewall rules for a program.
Please take note that Windows systems might not show a popup to inform the user that a network activity is blocked by the firewall.
The path to the ffmpeg executable can be found in the streaming start command in the debug logs. It may look something like this:
DEBUG: [Doorbell] [Video Process] Stream command: /usr/local/lib/node_modules/homebridge-eufy-security/node_modules/ffmpeg-for-homebridge/ffmpeg [...] -
This is a bug with Apples HomeKit implementation and also affects native HomeKit cameras.
Apple Watches seem to be able to stream cameras fine if they are on a wifi network or on their own cellular network. But as soon as the watch is connected via a paired iPhone streaming stops working entirely. -
As written above there can be a lot of causes for faulty streams. Please also consider that there is a network issue, that prevents proper streaming or even communicating with the eufy cloud in general.
Also consider the options described in Basic Troubleshooting, since it might also help to remove the device from HomeKit and add it again, and so on.
If you still have no luck, feel free to contact us on github or discord.