chris/frigate
1
0
Fork 0
forked from Github/frigate
Code Pull Requests Packages Activity

docs updates

Browse Source
This commit is contained in:
Blake Blackshear
2021-09-12 14:48:21 -05:00
parent a7b7a45b23
commit 0320d94ea6
33 changed files with 3911 additions and 7160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/docs/guides/camera_setup.md Normal file
View File

@@ -0,0 +1,47 @@
---
id: camera_setup
title: Camera setup
---
Cameras configured to output H.264 video and AAC audio will offer the most compatibility with all features of Frigate and Home Assistant. H.265 has better compression, but far less compatibility. Safari and Edge are the only browsers able to play H.265. Ideally, cameras should be configured directly for the desired resolutions and frame rates you want to use in Frigate. Reducing frame rates within Frigate will waste CPU resources decoding extra frames that are discarded. There are three different goals that you want to tune your stream configurations around.
- **Detection**: This is the only stream that Frigate will decode for processing. Also, this is the stream where snapshots will be generated from. The resolution for detection should be tuned for the size of the objects you want to detect. See [Choosing a detect resolution](#choosing-a-detect-resolution) for more details. The recommended frame rate is 5fps, but may need to be higher for very fast moving objects. Higher resolutions and frame rates will drive higher CPU usage on your server.
- **Recording**: This stream should be the resolution you wish to store for reference. Typically, this will be the highest resolution your camera supports. I recommend setting this feed to 15 fps.
- **Stream Viewing**: This stream will be rebroadcast as is to Home Assistant for viewing with the stream component. Setting this resolution too high will use significant bandwidth when viewing streams in Home Assistant, and they may not load reliably over slower connections.
### Choosing a detect resolution
The ideal resolution for detection is one where the objects you want to detect fit inside the dimensions of the model used by Frigate (320x320). Frigate does not pass the entire camera frame to object detection. It will crop an area of motion from the full frame and look in that portion of the frame. If the area being inspected is larger than 320x320, Frigate must resize it before running object detection. Higher resolutions do not improve the detection accuracy because the additional detail is lost in the resize. Below you can see a reference for how large a 320x320 area is against common resolutions.
Larger resolutions **do** improve performance if the objects are very small in the frame.
![Resolutions](/img/resolutions.png)
### Example Camera Configuration
For the Dahua/Loryta 5442 camera, I use the following settings:
**Main Stream (Recording)**
- Encode Mode: H.264
- Resolution: 2688\*1520
- Frame Rate(FPS): 15
- I Frame Interval: 30
**Sub Stream 1 (RTMP)**
- Enable: Sub Stream 1
- Encode Mode: H.264
- Resolution: 720\*576
- Frame Rate: 10
- I Frame Interval: 10
**Sub Stream 2 (Detection)**
- Enable: Sub Stream 2
- Encode Mode: H.264
- Resolution: 1280\*720
- Frame Rate: 5
- I Frame Interval: 5

19
docs/docs/guides/false_positives.md Normal file
View File

@@ -0,0 +1,19 @@
---
id: false_positives
title: Reducing false positives
---
Tune your object filters to adjust false positives: `min_area`, `max_area`, `min_score`, `threshold`.
For object filters in your configuration, any single detection below `min_score` will be ignored as a false positive. `threshold` is based on the median of the history of scores (padded to 3 values) for a tracked object. Consider the following frames when `min_score` is set to 0.6 and threshold is set to 0.85:
| Frame | Current Score | Score History | Computed Score | Detected Object |
| ----- | ------------- | --------------------------------- | -------------- | --------------- |
| 1 | 0.7 | 0.0, 0, 0.7 | 0.0 | No |
| 2 | 0.55 | 0.0, 0.7, 0.0 | 0.0 | No |
| 3 | 0.85 | 0.7, 0.0, 0.85 | 0.7 | No |
| 4 | 0.90 | 0.7, 0.85, 0.95, 0.90 | 0.875 | Yes |
| 5 | 0.88 | 0.7, 0.85, 0.95, 0.90, 0.88 | 0.88 | Yes |
| 6 | 0.95 | 0.7, 0.85, 0.95, 0.90, 0.88, 0.95 | 0.89 | Yes |
In frame 2, the score is below the `min_score` value, so frigate ignores it and it becomes a 0.0. The computed score is the median of the score history (padding to at least 3 values), and only when that computed score crosses the `threshold` is the object marked as a true positive. That happens in frame 4 in the example.

193
docs/docs/guides/getting_started.md Normal file
View File

@@ -0,0 +1,193 @@
---
id: getting_started
title: Creating a config file
---
This guide walks through the steps to build a configuration file for Frigate. It assumes that you already have an environment setup as described in [Installation](/installation). You should also configure your cameras according to the [camera setup guide](/guides/camera_setup)
### Step 1: Configure the MQTT server
Frigate requires a functioning MQTT server. Start by adding the mqtt section at the top level in your config:
```yaml
mqtt:
host: <ip of your mqtt server>
```
If using the Mosquitto Addon in Home Assistant, a username and password is required. For example:
```yaml
mqtt:
host: <ip of your mqtt server>
user: <username>
password: <password>
```
Frigate supports many configuration options for mqtt. See the [configuration reference](/configuration/index#full-configuration-reference) for more info.
### Step 2: Configure detectors
By default, Frigate will use a single CPU detector. If you have a USB Coral, you will need to add a detectors section to your config.
```yaml
mqtt:
host: <ip of your mqtt server>
detectors:
coral:
type: edgetpu
device: usb
```
More details on available detectors can be found [here](/configuration/detectors).
### Step 3: Add a minimal camera configuration
Now let's add the first camera:
```yaml
mqtt:
host: <ip of your mqtt server>
detectors:
coral:
type: edgetpu
device: usb
cameras:
camera_1: # <------ Name the camera
ffmpeg:
inputs:
- path: rtsp://10.0.10.10:554/rtsp # <----- Update for your camera
roles:
- detect
- rtmp
detect:
width: 1280 # <---- update for your camera's resolution
height: 720 # <---- update for your camera's resolution
```
### Step 4: Start Frigate
At this point you should be able to start Frigate and see the the video feed in the UI.
If you get a green image from the camera, this means ffmpeg was not able to get the video feed from your camera. Check the logs for error messages from ffmpeg. The default ffmpeg arguments are designed to work with RTSP cameras that support TCP connections. FFmpeg arguments for other types of cameras can be found [here](/configuration/camera_specific).
### Step 5: Configure hardware acceleration (optional)
Now that you have a working camera configuration, you want to setup hardware acceleration to minimize the CPU required to decode your video streams. See the [hardware acceleration](/configuration/hardware_acceleration) config reference for examples applicable to your hardware.
In order to best evaluate the performance impact of hardware acceleration, it is recommended to temporarily disable detection.
```yaml
mqtt: ...
detectors: ...
cameras:
camera_1:
ffmpeg: ...
detect:
enabled: False
...
```
Here is an example configuration with hardware acceleration configured:
```yaml
mqtt: ...
detectors: ...
cameras:
camera_1:
ffmpeg:
inputs: ...
hwaccel_args: -c:v h264_v4l2m2m
detect: ...
```
### Step 6: Setup motion masks
Now that you have optimized your configuration for decoding the video stream, you will want to check to see where to implement motion masks. To do this, navigate to the camera in the UI, select "Debug" at the top, and enable "Motion boxes" in the options below the video feed. Watch for areas that continuously trigger unwanted motion to be detected. Common areas to mask include camera timestamps and trees that frequently blow in the wind. The goal is to avoid wasting object detection cycles looking at these areas.
Now that you know where you need to mask, use the "Mask & Zone creator" in the options pane to generate the coordinates needed for your config file. More information about masks can be found [here](/configuration/masks).
:::caution
Note that motion masks should not be used to mark out areas where you do not want objects to be detected or to reduce false positives. They do not alter the image sent to object detection, so you can still get events and detections in areas with motion masks. These only prevent motion in these areas from initiating object detection.
:::
Your configuration should look similar to this now.
```yaml
mqtt:
host: mqtt.local
detectors:
coral:
type: edgetpu
device: usb
cameras:
camera_1:
ffmpeg:
inputs:
- path: rtsp://10.0.10.10:554/rtsp
roles:
- detect
- rtmp
detect:
width: 1280
height: 720
motion:
mask:
- 0,461,3,0,1919,0,1919,843,1699,492,1344,458,1346,336,973,317,869,375,866,432
```
### Step 7: Enable recording (optional)
To enable recording video, add the `record` role to a stream and enable it in the config.
```yaml
mqtt: ...
detectors: ...
cameras:
camera_1:
ffmpeg:
inputs:
- path: rtsp://10.0.10.10:554/rtsp
roles:
- detect
- rtmp
- record # <----- Add role
detect: ...
record: # <----- Enable recording
enabled: True
motion: ...
```
By default, Frigate will retain video of all events for 10 days. The full set of options for recording can be found [here](/configuration/index#full-configuration-reference).
### Step 8: Enable snapshots (optional)
To enable snapshots of your events, just enable it in the config.
```yaml
mqtt: ...
detectors: ...
cameras:
camera_1: ...
detect: ...
record: ...
snapshots: # <----- Enable snapshots
enabled: True
motion: ...
```
By default, Frigate will retain snapshots of all events for 10 days. The full set of options for snapshots can be found [here](/configuration/index#full-configuration-reference).