Merge branch 'master' into release-0.9.0

README.md

@@ -4,11 +4,11 @@
 
 # Frigate - NVR With Realtime Object Detection for IP Cameras
 
-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](https://www.home-assistant.io) 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
@@ -26,7 +26,7 @@ View the documentation at https://blakeblackshear.github.io/frigate
 If you would like to make a donation to support development, please use [Github Sponsors](https://github.com/sponsors/blakeblackshear).
 
 ## Screenshots
-Integration into HomeAssistant
+Integration into Home Assistant
 <div>
 <a href="docs/static/img/media_browser.png"><img src="docs/static/img/media_browser.png" height=400></a>
 <a href="docs/static/img/notification.png"><img src="docs/static/img/notification.png" height=400></a>

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.
 
@@ -99,7 +99,8 @@ detectors:
  # Required: name of the detector
  coral:
  # Required: type of the detector
- # Valid values are 'edgetpu' (requires device property below) and 'cpu'. type: edgetpu
+ # Valid values are 'edgetpu' (requires device property below) and 'cpu'.
+ type: edgetpu
  # Optional: device name as defined here: https://coral.ai/docs/edgetpu/multiple-edgetpu/#using-the-tensorflow-lite-python-api
  device: usb
  # Optional: num_threads value passed to the tflite.Interpreter (default: shown below)
@@ -116,24 +117,3 @@ model:
  # Required: width of the trained model
  width: 320
 ```
-
-## Custom Models
-
-Models for both CPU and EdgeTPU (Coral) are bundled in the image. You can use your own models with volume mounts:
-
-- CPU Model: `/cpu_model.tflite`
-- EdgeTPU Model: `/edgetpu_model.tflite`
-- Labels: `/labelmap.txt`
-
-You also need to update the model width/height in the config if they differ from the defaults.
-
-### Customizing the Labelmap
-
-The labelmap can be customized to your needs. A common reason to do this is to combine multiple object types that are easily confused when you don't need to be as granular such as car/truck. You must retain the same number of labels, but you can change the names. To change:
-
-- Download the [COCO labelmap](https://dl.google.com/coral/canned_models/coco_labels.txt)
-- Modify the label names as desired. For example, change `7 truck` to `7 car`
-- Mount the new file at `/labelmap.txt` in the container with an additional volume
- ```
- -v ./config/labelmap.txt:/labelmap.txt
- ```

docs/docs/configuration/cameras.md

@@ -41,9 +41,11 @@ cameras:
 ## Masks & Zones
 
 ### Masks
+
 Masks are used to ignore initial detection in areas of your camera's field of view.
 
 There are two types of masks available:
+
 - **Motion masks**: Motion masks are used to prevent unwanted types of motion from triggering detection. Try watching the video feed with `Motion Boxes` enabled to see what may be regularly detected as motion. For example, you want to mask out your timestamp, the sky, rooftops, etc. Keep in mind that this mask only prevents motion from being detected and does not prevent objects from being detected if object detection was started due to motion in unmasked areas. Motion is also used during object tracking to refine the object detection area in the next frame. Over masking will make it more difficult for objects to be tracked. To see this effect, create a mask, and then watch the video feed with `Motion Boxes` enabled again.
 - **Object filter masks**: Object filter masks are used to filter out false positives for a given object type. These should be used to filter any areas where it is not possible for an object of that type to be. The bottom center of the detected object's bounding box is evaluated against the mask. If it is in a masked area, it is assumed to be a false positive. For example, you may want to mask out rooftops, walls, the sky, treetops for people. For cars, masking locations other than the street or your driveway will tell frigate that anything in your yard is a false positive.
 
@@ -60,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)
@@ -102,14 +104,16 @@ zones:
 
 ## Objects
 
+For a list of available objects, see the [objects documentation](./objects.mdx).
+
 ```yaml
 # Optional: Camera level object filters config.
 objects:
  track:
  - person
  - car
  # Optional: mask to prevent all object types from being detected in certain areas (default: no mask)
- # Checks based on the bottom center of the bounding box of the object. 
+ # Checks based on the bottom center of the bounding box of the object.
  # NOTE: This mask is COMBINED with the object type specific mask below
  mask: 0,0,1000,0,1000,200,0,200
  filters:
@@ -127,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.
@@ -187,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/<camera_name>/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/<camera_name>/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.
@@ -204,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:https://<frigate_host>/live/<camera_name>`. 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:https://<frigate_host>/live/<camera_name>`. 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.
 
@@ -368,7 +372,7 @@ cameras:
  - person
  - car
  # Optional: mask to prevent all object types from being detected in certain areas (default: no mask)
- # Checks based on the bottom center of the bounding box of the object. 
+ # Checks based on the bottom center of the bounding box of the object.
  # NOTE: This mask is COMBINED with the object type specific mask below
  mask: 0,0,1000,0,1000,200,0,200
  filters:
@@ -384,6 +388,37 @@ cameras:
 
 ## Camera specific configuration
 
+### MJPEG 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"
+```
+
+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
+```
+
 ### RTMP Cameras
 
 The input parameters need to be adjusted for RTMP cameras
@@ -402,10 +437,11 @@ ffmpeg:
  - -fflags
  - +genpts+discardcorrupt
  - -use_wallclock_as_timestamps
- - '1'
+ - "1"
 ```
 
 ### Reolink 410/520 (possibly others)
+
 Several users have reported success with the rtmp video from Reolink cameras.
 
 ```yaml
@@ -422,12 +458,11 @@ ffmpeg:
  - -fflags
  - +genpts+discardcorrupt
  - -rw_timeout
- - '5000000'
+ - "5000000"
  - -use_wallclock_as_timestamps
- - '1'
+ - "1"
 ```
 
-
 ### Blue Iris RTSP Cameras
 
 You will need to remove `nobuffer` flag for Blue Iris RTSP cameras
@@ -446,7 +481,7 @@ ffmpeg:
  - -rtsp_transport
  - tcp
  - -stimeout
- - '5000000'
+ - "5000000"
  - -use_wallclock_as_timestamps
- - '1'
+ - "1"
 ```

docs/docs/configuration/detectors.md

@@ -30,6 +30,18 @@ detectors:
  device: usb:1
 ```
 
+Multiple PCIE/M.2 Corals:
+
+```yaml
+detectors:
+ coral1:
+ type: edgetpu
+ device: pci:0
+ coral2:
+ type: edgetpu
+ device: pci:1
+```
+
 Mixing Corals:
 
 ```yaml

docs/docs/configuration/index.md

@@ -3,7 +3,9 @@ id: index
 title: Configuration
 ---
 
-HassOS users can manage their configuration directly in the addon Configuration tab. For other installations, the default location for the config file is `/config/config.yml`. This can be overridden with the `CONFIG_FILE` environment variable. Camera specific ffmpeg parameters are documented [here](cameras.md).
+For HassOS installations, the default location for the config file is `/config/frigate.yml`.
+
+For all other installations, the default location for the config file is '/config/config.yml'. This can be overridden with the `CONFIG_FILE` environment variable. Camera specific ffmpeg parameters are documented [here](cameras.md).
 
 It is recommended to start with a minimal configuration and add to it:
 
@@ -112,7 +114,7 @@ ffmpeg:
 
 ### `objects`
 
-Can be overridden at the camera level
+Can be overridden at the camera level. For a list of available objects, see the [objects documentation](./objects.mdx).
 
 ```yaml
 objects:
@@ -131,3 +133,19 @@ objects:
  # Optional: minimum decimal percentage for tracked object's computed score to be considered a true positive (default: shown below)
  threshold: 0.7
 ```
+
+### `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/<camera_name>/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.
+:::
+
+```yaml
+record:
+ # Optional: Enable recording
+ enabled: False
+ # Optional: Number of days to retain
+ retain_days: 30
+```

docs/docs/configuration/nvdec.md

@@ -55,7 +55,7 @@ A list of supported codecs (you can use `ffmpeg -decoders | grep cuvid` in the c
 ```
 
 For example, for H265 video (hevc), you'll select `hevc_cuvid`. Add
-`-c:v hevc_covid` to your ffmpeg input arguments:
+`-c:v hevc_cuvid` to your ffmpeg input arguments:
 
 ```
 ffmpeg:

docs/docs/configuration/objects.mdx

@@ -0,0 +1,36 @@
+---
+id: objects
+title: Default available objects
+sidebar_label: Available objects
+---
+
+import labels from '../../../labelmap.txt';
+
+By default, Frigate includes the following object models from the Google Coral test data.
+
+<ul>
+ {labels.split('\n').map((label) => (
+ <li>{label.replace(/^\d+\s+/, '')}</li>
+ ))}
+</ul>
+
+## Custom Models
+
+Models for both CPU and EdgeTPU (Coral) are bundled in the image. You can use your own models with volume mounts:
+
+- CPU Model: `/cpu_model.tflite`
+- EdgeTPU Model: `/edgetpu_model.tflite`
+- Labels: `/labelmap.txt`
+
+You also need to update the model width/height in the config if they differ from the defaults.
+
+### Customizing the Labelmap
+
+The labelmap can be customized to your needs. A common reason to do this is to combine multiple object types that are easily confused when you don't need to be as granular such as car/truck. You must retain the same number of labels, but you can change the names. To change:
+
+- Download the [COCO labelmap](https://dl.google.com/coral/canned_models/coco_labels.txt)
+- Modify the label names as desired. For example, change `7 truck` to `7 car`
+- Mount the new file at `/labelmap.txt` in the container with an additional volume
+ ```
+ -v ./config/labelmap.txt:/labelmap.txt
+ ```

docs/docs/configuration/optimizing.md

@@ -3,7 +3,7 @@ id: optimizing
 title: Optimizing performance
 ---
 
-- **Google Coral**: It is strongly recommended to use a Google Coral, but Frigate will fall back to CPU in the event one is not found. Offloading TensorFlow to the Google Coral is an order of magnitude faster and will reduce your CPU load dramatically. A $60 device will outperform $2000 CPU. Frigate should work with any supported Coral device from https://coral.ai
+- **Google Coral**: It is strongly recommended to use a Google Coral, Frigate will no longer fall back to CPU in the event one is not found. Offloading TensorFlow to the Google Coral is an order of magnitude faster and will reduce your CPU load dramatically. A $60 device will outperform $2000 CPU. Frigate should work with any supported Coral device from https://coral.ai
 - **Resolution**: For the `detect` input, choose a camera resolution where the smallest object you want to detect barely fits inside a 300x300px square. The model used by Frigate is trained on 300x300px images, so you will get worse performance and no improvement in accuracy by using a larger resolution since Frigate resizes the area where it is looking for objects to 300x300 anyway.
 - **FPS**: 5 frames per second should be adequate. Higher frame rates will require more CPU usage without improving detections or accuracy. Reducing the frame rate on your camera will have the greatest improvement on system resources.
 - **Hardware Acceleration**: Make sure you configure the `hwaccel_args` for your hardware. They provide a significant reduction in CPU usage if they are available.

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:https://coral.ai)  | 6.2ms  | Little complicated to get installed, as needs drivers on the host OS, [info here](https://forums.unraid.net/topic/98064-support-blakeblackshear-frigate/?do=findComment&comment=945776)  |
+| Name  | Inference Speed | Notes  |
+| ------------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [M2 Coral Edge TPU](http:https://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) |