diff --git a/docs/docs/configuration/advanced.md b/docs/docs/configuration/advanced.md index e04c347fa..7efcfb680 100644 --- a/docs/docs/configuration/advanced.md +++ b/docs/docs/configuration/advanced.md @@ -81,7 +81,7 @@ environment_vars: ### `database` -Event and clip information is managed in a sqlite database at `/media/frigate/clips/frigate.db`. If that database is deleted, clips will be orphaned and will need to be cleaned up manually. They also won't show up in the Media Browser within HomeAssistant. +Event and clip information is managed in a sqlite database at `/media/frigate/clips/frigate.db`. If that database is deleted, clips will be orphaned and will need to be cleaned up manually. They also won't show up in the Media Browser within Home Assistant. If you are storing your clips on a network share (SMB, NFS, etc), you may get a `database is locked` error message on startup. You can customize the location of the database in the config if necessary. diff --git a/docs/docs/configuration/cameras.md b/docs/docs/configuration/cameras.md index 5501b7ff2..faf871f07 100644 --- a/docs/docs/configuration/cameras.md +++ b/docs/docs/configuration/cameras.md @@ -62,7 +62,7 @@ Example of a finished row corresponding to the below example image: ```yaml motion: - mask: '0,461,3,0,1919,0,1919,843,1699,492,1344,458,1346,336,973,317,869,375,866,432' + mask: "0,461,3,0,1919,0,1919,843,1699,492,1344,458,1346,336,973,317,869,375,866,432" ``` ![poly](/img/example-mask-poly.png) @@ -131,7 +131,7 @@ objects: Frigate can save video clips without any CPU overhead for encoding by simply copying the stream directly with FFmpeg. It leverages FFmpeg's segment functionality to maintain a cache of video for each camera. The cache files are written to disk at `/tmp/cache` and do not introduce memory overhead. When an object is being tracked, it will extend the cache to ensure it can assemble a clip when the event ends. Once the event ends, it again uses FFmpeg to assemble a clip by combining the video clips without any encoding by the CPU. Assembled clips are are saved to `/media/frigate/clips`. Clips are retained according to the retention settings defined on the config for each object type. -These clips will not be playable in the web UI or in HomeAssistant's media browser unless your camera sends video as h264. +These clips will not be playable in the web UI or in Home Assistant's media browser unless your camera sends video as h264. :::caution Previous versions of frigate included `-vsync drop` in input parameters. This is not compatible with FFmpeg's segment feature and must be removed from your input parameters if you have overrides set. @@ -191,7 +191,7 @@ snapshots: ## 24/7 Recordings -24/7 recordings can be enabled and are stored at `/media/frigate/recordings`. The folder structure for the recordings is `YYYY-MM/DD/HH//MM.SS.mp4`. These recordings are written directly from your camera stream without re-encoding and are available in HomeAssistant's media browser. Each camera supports a configurable retention policy in the config. +24/7 recordings can be enabled and are stored at `/media/frigate/recordings`. The folder structure for the recordings is `YYYY-MM/DD/HH//MM.SS.mp4`. These recordings are written directly from your camera stream without re-encoding and are available in Home Assistant's media browser. Each camera supports a configurable retention policy in the config. :::caution Previous versions of frigate included `-vsync drop` in input parameters. This is not compatible with FFmpeg's segment feature and must be removed from your input parameters if you have overrides set. @@ -208,7 +208,7 @@ record: ## RTMP streams -Frigate can re-stream your video feed as a RTMP feed for other applications such as HomeAssistant to utilize it at `rtmp:///live/`. Port 1935 must be open. This allows you to use a video feed for detection in frigate and HomeAssistant live view at the same time without having to make two separate connections to the camera. The video feed is copied from the original video feed directly to avoid re-encoding. This feed does not include any annotation by Frigate. +Frigate can re-stream your video feed as a RTMP feed for other applications such as Home Assistant to utilize it at `rtmp:///live/`. Port 1935 must be open. This allows you to use a video feed for detection in frigate and Home Assistant live view at the same time without having to make two separate connections to the camera. The video feed is copied from the original video feed directly to avoid re-encoding. This feed does not include any annotation by Frigate. Some video feeds are not compatible with RTMP. If you are experiencing issues, check to make sure your camera feed is h264 with AAC audio. If your camera doesn't support a compatible format for RTMP, you can use the ffmpeg args to re-encode it on the fly at the expense of increased CPU utilization. @@ -393,29 +393,30 @@ cameras: The input and output parameters need to be adjusted for MJPEG cameras ```yaml - input_args: - - -avoid_negative_ts - - make_zero - - -fflags - - nobuffer - - -flags - - low_delay - - -strict - - experimental - - -fflags - - +genpts+discardcorrupt - - -r - - '3' # <---- adjust depending on your desired frame rate from the mjpeg image - - -use_wallclock_as_timestamps - - '1' +input_args: + - -avoid_negative_ts + - make_zero + - -fflags + - nobuffer + - -flags + - low_delay + - -strict + - experimental + - -fflags + - +genpts+discardcorrupt + - -r + - "3" # <---- adjust depending on your desired frame rate from the mjpeg image + - -use_wallclock_as_timestamps + - "1" ``` Note that mjpeg cameras require encoding the video into h264 for clips, recording, and rtmp roles. This will use significantly more CPU than if the cameras supported h264 feeds directly. + ```yaml - output_args: - record: -f segment -segment_time 60 -segment_format mp4 -reset_timestamps 1 -strftime 1 -c:v libx264 -an - clips: -f segment -segment_time 10 -segment_format mp4 -reset_timestamps 1 -strftime 1 -c:v libx264 -an - rtmp: -c:v libx264 -an -f flv +output_args: + record: -f segment -segment_time 60 -segment_format mp4 -reset_timestamps 1 -strftime 1 -c:v libx264 -an + clips: -f segment -segment_time 10 -segment_format mp4 -reset_timestamps 1 -strftime 1 -c:v libx264 -an + rtmp: -c:v libx264 -an -f flv ``` ### RTMP Cameras @@ -436,7 +437,7 @@ ffmpeg: - -fflags - +genpts+discardcorrupt - -use_wallclock_as_timestamps - - '1' + - "1" ``` ### Reolink 410/520 (possibly others) @@ -457,9 +458,9 @@ ffmpeg: - -fflags - +genpts+discardcorrupt - -rw_timeout - - '5000000' + - "5000000" - -use_wallclock_as_timestamps - - '1' + - "1" ``` ### Blue Iris RTSP Cameras @@ -480,7 +481,7 @@ ffmpeg: - -rtsp_transport - tcp - -stimeout - - '5000000' + - "5000000" - -use_wallclock_as_timestamps - - '1' + - "1" ``` diff --git a/docs/docs/configuration/index.md b/docs/docs/configuration/index.md index 6099df3b0..bdffb16ef 100644 --- a/docs/docs/configuration/index.md +++ b/docs/docs/configuration/index.md @@ -141,7 +141,7 @@ objects: ### `record` -Can be overridden at the camera level. 24/7 recordings can be enabled and are stored at `/media/frigate/recordings`. The folder structure for the recordings is `YYYY-MM/DD/HH//MM.SS.mp4`. These recordings are written directly from your camera stream without re-encoding and are available in HomeAssistant's media browser. Each camera supports a configurable retention policy in the config. +Can be overridden at the camera level. 24/7 recordings can be enabled and are stored at `/media/frigate/recordings`. The folder structure for the recordings is `YYYY-MM/DD/HH//MM.SS.mp4`. These recordings are written directly from your camera stream without re-encoding and are available in Home Assistant's media browser. Each camera supports a configurable retention policy in the config. :::caution Previous versions of frigate included `-vsync drop` in input parameters. This is not compatible with FFmpeg's segment feature and must be removed from your input parameters if you have overrides set. diff --git a/docs/docs/hardware.md b/docs/docs/hardware.md index f94a6738d..5cf20df87 100644 --- a/docs/docs/hardware.md +++ b/docs/docs/hardware.md @@ -5,7 +5,7 @@ title: Recommended hardware ## Cameras -Cameras that output H.264 video and AAC audio will offer the most compatibility with all features of Frigate and HomeAssistant. It is also helpful if your camera supports multiple substreams to allow different resolutions to be used for detection, streaming, clips, and recordings without re-encoding. +Cameras that output H.264 video and AAC audio will offer the most compatibility with all features of Frigate and Home Assistant. It is also helpful if your camera supports multiple substreams to allow different resolutions to be used for detection, streaming, clips, and recordings without re-encoding. ## Computer @@ -24,6 +24,6 @@ Cameras that output H.264 video and AAC audio will offer the most compatibility Many people have powerful enough NAS devices or home servers to also run docker. There is a Unraid Community App. To install make sure you have the [community app plugin here](https://forums.unraid.net/topic/38582-plug-in-community-applications/). Then search for "Frigate" in the apps section within Unraid - you can see the online store [here](https://unraid.net/community/apps?q=frigate#r) -| Name | Inference Speed | Notes | -| ----------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| [M2 Coral Edge TPU](http://coral.ai) | 6.2ms | Install the Coral plugin from Unraid Community App Center [info here](https://forums.unraid.net/topic/98064-support-blakeblackshear-frigate/?do=findComment&comment=949789) | +| Name | Inference Speed | Notes | +| ------------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [M2 Coral Edge TPU](http://coral.ai) | 6.2ms | Install the Coral plugin from Unraid Community App Center [info here](https://forums.unraid.net/topic/98064-support-blakeblackshear-frigate/?do=findComment&comment=949789) | diff --git a/docs/docs/index.md b/docs/docs/index.md index e04290c15..0bee0be22 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -5,11 +5,11 @@ sidebar_label: Features slug: / --- -A complete and local NVR designed for HomeAssistant with AI object detection. Uses OpenCV and Tensorflow to perform realtime object detection locally for IP cameras. +A complete and local NVR designed for Home Assistant with AI object detection. Uses OpenCV and Tensorflow to perform realtime object detection locally for IP cameras. Use of a [Google Coral Accelerator](https://coral.ai/products/) is optional, but highly recommended. The Coral will outperform even the best CPUs and can process 100+ FPS with very little overhead. -- Tight integration with HomeAssistant via a [custom component](https://github.com/blakeblackshear/frigate-hass-integration) +- Tight integration with Home Assistant via a [custom component](https://github.com/blakeblackshear/frigate-hass-integration) - Designed to minimize resource use and maximize performance by only looking for objects when and where it is necessary - Leverages multiprocessing heavily with an emphasis on realtime over processing every frame - Uses a very low overhead motion detection to determine where to run object detection diff --git a/docs/docs/installation.md b/docs/docs/installation.md index e0ca3fdb6..483fa8439 100644 --- a/docs/docs/installation.md +++ b/docs/docs/installation.md @@ -5,7 +5,7 @@ title: Installation Frigate is a Docker container that can be run on any Docker host including as a [HassOS Addon](https://www.home-assistant.io/addons/). See instructions below for installing the HassOS addon. -For HomeAssistant users, there is also a [custom component (aka integration)](https://github.com/blakeblackshear/frigate-hass-integration). This custom component adds tighter integration with HomeAssistant by automatically setting up camera entities, sensors, media browser for clips and recordings, and a public API to simplify notifications. +For Home Assistant users, there is also a [custom component (aka integration)](https://github.com/blakeblackshear/frigate-hass-integration). This custom component adds tighter integration with Home Assistant by automatically setting up camera entities, sensors, media browser for clips and recordings, and a public API to simplify notifications. Note that HassOS Addons and custom components are different things. If you are already running Frigate with Docker directly, you do not need the Addon since the Addon would run another instance of Frigate. @@ -24,17 +24,17 @@ HassOS users can install via the addon repository. Frigate requires an MQTT serv Make sure you choose the right image for your architecture: -|Arch|Image Name| -|-|-| -|amd64|blakeblackshear/frigate:stable-amd64| -|amd64nvidia|blakeblackshear/frigate:stable-amd64nvidia| -|armv7|blakeblackshear/frigate:stable-armv7| -|aarch64|blakeblackshear/frigate:stable-aarch64| +| Arch | Image Name | +| ----------- | ------------------------------------------ | +| amd64 | blakeblackshear/frigate:stable-amd64 | +| amd64nvidia | blakeblackshear/frigate:stable-amd64nvidia | +| armv7 | blakeblackshear/frigate:stable-armv7 | +| aarch64 | blakeblackshear/frigate:stable-aarch64 | It is recommended to run with docker-compose: ```yaml -version: '3.9' +version: "3.9" services: frigate: container_name: frigate @@ -53,10 +53,10 @@ services: tmpfs: size: 1000000000 ports: - - '5000:5000' - - '1935:1935' # RTMP feeds + - "5000:5000" + - "1935:1935" # RTMP feeds environment: - FRIGATE_RTSP_PASSWORD: 'password' + FRIGATE_RTSP_PASSWORD: "password" ``` If you can't use docker compose, you can run the container with something similar to this: @@ -87,7 +87,7 @@ You can calculate the necessary shm-size for each camera with the following form (width * height * 1.5 * 7 + 270480)/1048576 = ``` -The shm size cannot be set per container for HomeAssistant Addons. You must set `default-shm-size` in `/etc/docker/daemon.json` to increase the default shm size. This will increase the shm size for all of your docker containers. This may or may not cause issues with your setup. https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file +The shm size cannot be set per container for Home Assistant Addons. You must set `default-shm-size` in `/etc/docker/daemon.json` to increase the default shm size. This will increase the shm size for all of your docker containers. This may or may not cause issues with your setup. https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file ## Kubernetes @@ -120,5 +120,5 @@ lxc.cap.drop: ``` ### ESX -For details on running Frigate under ESX, see details [here](https://github.com/blakeblackshear/frigate/issues/305). +For details on running Frigate under ESX, see details [here](https://github.com/blakeblackshear/frigate/issues/305). diff --git a/docs/docs/usage/api.md b/docs/docs/usage/api.md index 25a52abd9..83ffbdf00 100644 --- a/docs/docs/usage/api.md +++ b/docs/docs/usage/api.md @@ -55,7 +55,7 @@ Example parameters: ### `/api/stats` -Contains some granular debug info that can be used for sensors in HomeAssistant. +Contains some granular debug info that can be used for sensors in Home Assistant. Sample response: @@ -125,26 +125,26 @@ Sample response: "total": 1000, "used": 700, "free": 300, - "mnt_type": "ext4", + "mnt_type": "ext4" }, "/media/frigate/recordings": { "total": 1000, "used": 700, "free": 300, - "mnt_type": "ext4", + "mnt_type": "ext4" }, "/tmp/cache": { "total": 256, "used": 100, "free": 156, - "mnt_type": "tmpfs", + "mnt_type": "tmpfs" }, "/dev/shm": { "total": 256, "used": 100, "free": 156, - "mnt_type": "tmpfs", - }, + "mnt_type": "tmpfs" + } } } } @@ -176,7 +176,7 @@ Events from the database. Accepts the following query string parameters: ### `/api/events/summary` -Returns summary data for events in the database. Used by the HomeAssistant integration. +Returns summary data for events in the database. Used by the Home Assistant integration. ### `/api/events/` diff --git a/docs/docs/usage/home-assistant.md b/docs/docs/usage/home-assistant.md index 09f9fbb26..45764e01a 100644 --- a/docs/docs/usage/home-assistant.md +++ b/docs/docs/usage/home-assistant.md @@ -4,7 +4,7 @@ title: Integration with Home Assistant sidebar_label: Home Assistant --- -The best way to integrate with HomeAssistant is to use the [official integration](https://github.com/blakeblackshear/frigate-hass-integration). When configuring the integration, you will be asked for the `Host` of your frigate instance. This value should be the url you use to access Frigate in the browser and will look like `http://:5000/`. If you are using HassOS with the addon, the host should be `http://ccab4aaf-frigate:5000` (or `http://ccab4aaf-frigate-beta:5000` if your are using the beta version of the addon). HomeAssistant needs access to port 5000 (api) and 1935 (rtmp) for all features. The integration will setup the following entities within HomeAssistant: +The best way to integrate with Home Assistant is to use the [official integration](https://github.com/blakeblackshear/frigate-hass-integration). When configuring the integration, you will be asked for the `Host` of your frigate instance. This value should be the url you use to access Frigate in the browser and will look like `http://:5000/`. If you are using HassOS with the addon, the host should be `http://ccab4aaf-frigate:5000` (or `http://ccab4aaf-frigate-beta:5000` if your are using the beta version of the addon). Home Assistant needs access to port 5000 (api) and 1935 (rtmp) for all features. The integration will setup the following entities within Home Assistant: ## Sensors: @@ -30,17 +30,19 @@ The best way to integrate with HomeAssistant is to use the [official integration Frigate publishes event information in the form of a change feed via MQTT. This allows lots of customization for notifications to meet your needs. Event changes are published with `before` and `after` information as shown [here](#frigateevents). Note that some people may not want to expose frigate to the web, so you can leverage the HA API that frigate custom_integration ties into (which is exposed to the web, and thus can be used for mobile notifications etc): -To load an image taken by frigate from HomeAssistants API see below: -``` +To load an image taken by frigate from Home Assistants API see below: + +``` https://HA_URL/api/frigate/notifications//thumbnail.jpg ``` -To load a video clip taken by frigate from HomeAssistants API : -``` +To load a video clip taken by frigate from Home Assistants API : + +``` https://HA_URL/api/frigate/notifications///clip.mp4 ``` -Here is a simple example of a notification automation of events which will update the existing notification for each change. This means the image you see in the notification will update as frigate finds a "better" image. +Here is a simple example of a notification automation of events which will update the existing notification for each change. This means the image you see in the notification will update as frigate finds a "better" image. ```yaml automation: @@ -57,7 +59,6 @@ automation: tag: '{{trigger.payload_json["after"]["id"]}}' ``` - ```yaml automation: - alias: When a person enters a zone named yard @@ -106,7 +107,7 @@ automation: action: - service: notify.mobile_app_pixel_3 data_template: - message: 'High confidence dog detection.' + message: "High confidence dog detection." data: image: "https://url.com/api/frigate/notifications/{{trigger.payload_json['after']['id']}}/thumbnail.jpg" tag: "{{trigger.payload_json['after']['id']}}" diff --git a/docs/docs/usage/mqtt.md b/docs/docs/usage/mqtt.md index 76963f7fe..83d92bbc2 100644 --- a/docs/docs/usage/mqtt.md +++ b/docs/docs/usage/mqtt.md @@ -7,17 +7,17 @@ These are the MQTT messages generated by Frigate. The default topic_prefix is `f ### `frigate/available` -Designed to be used as an availability topic with HomeAssistant. Possible message are: +Designed to be used as an availability topic with Home Assistant. Possible message are: "online": published when frigate is running (on startup) "offline": published right before frigate stops ### `frigate//` -Publishes the count of objects for the camera for use as a sensor in HomeAssistant. +Publishes the count of objects for the camera for use as a sensor in Home Assistant. ### `frigate//` -Publishes the count of objects for the zone for use as a sensor in HomeAssistant. +Publishes the count of objects for the zone for use as a sensor in Home Assistant. ### `frigate///snapshot`