Compare commits

...
5 Commits
Author SHA1 Message Date
GuoQing LiuandGitHub a7ce2b6633 Merge edca412856 into 81b53b7835 2026-07-15 03:58:40 +08:00
81b53b7835 Miscellaneous fixes (0.18 beta) (#23716)
CI / AMD64 Build (push) Waiting to run
CI / ARM Build (push) Waiting to run
CI / Jetson Jetpack 6 (push) Waiting to run
CI / AMD64 Extra Build (push) Blocked by required conditions
CI / ARM Extra Build (push) Blocked by required conditions
CI / Assemble and push default build (push) Blocked by required conditions
CI / Synaptics Build (push) Blocked by required conditions
* resolve zone friendly names against the correct camera

* Improve handling of zone names in chat prompt

* show a numeric keyboard for numeric config form fields on mobile

* Specify english only for semantic search tool when model is JinaV1

* resolve export hwaccel args global value against the correct config path

---------

Co-authored-by: Nicolas Mowen <nickmowen213@gmail.com>
2026-07-14 08:42:26 -06:00
Josh HawkinsandGitHub c2e739b4bc bound REGEXP evaluation with a timeout to prevent ReDoS on the database thread (#23714)
CI / AMD64 Build (push) Waiting to run
CI / ARM Build (push) Waiting to run
CI / Jetson Jetpack 6 (push) Waiting to run
CI / ARM Extra Build (push) Blocked by required conditions
CI / Synaptics Build (push) Blocked by required conditions
CI / Assemble and push default build (push) Blocked by required conditions
CI / AMD64 Extra Build (push) Blocked by required conditions
The recognized_license_plate event filter passed attacker-controlled patterns to re.search on the single serialized SQLite queue thread, letting any authenticated user freeze the whole application with a catastrophic regex. This swaps stdlib re for the regex module with a per-evaluation timeout so a pathological pattern is aborted instead of stalling every database operation.
2026-07-14 06:27:00 -05:00
nulledyandGitHub 62d4e87e5d Add logout endpoint to Nginx configuration to prevent a new token on logout (#23678)
* Add logout endpoint to Nginx configuration to prevent logout from silently generating a new frigate_token cookie

* Change JWT cookie expiration to use max_age and have the appropriate expiration time based on JWT_SESSION_LENGTH

* ruff formatting
2026-07-14 02:35:51 -08:00
ZhaiSoul edca412856 docs: Add docs Frigate UI mock view 2026-07-12 21:34:08 +08:00
32 changed files with 10852 additions and 286 deletions
@@ -274,6 +274,13 @@ http {
include proxy.conf;
}
location /api/logout {
auth_request off;
rewrite ^/api(/.*)$ $1 break;
proxy_pass http://frigate_api;
include proxy.conf;
}
# Allow unauthenticated access to the first_time_login endpoint
# so the login page can load help text before authentication.
location /api/auth/first_time_login {
+33 -15
View File
@@ -1149,6 +1149,11 @@ rknn:
| **Model Input D Type** | `int` (Frigate's default value) |
| **Object Detection Model Type** | `yolo-generic` |
yaml: |-
detectors:
rknn:
type: rknn
num_cores: 0
model: # required
# name of model (will be automatically downloaded) or path to your own .rknn model file
# possible values are:
@@ -1187,6 +1192,11 @@ rknn:
| **Model Input D Type** | `int` (Frigate's default value) |
| **Object Detection Model Type** | `yolonas` |
yaml: |-
detectors:
rknn:
type: rknn
num_cores: 0
model: # required
# name of model (will be automatically downloaded) or path to your own .rknn model file
# possible values are:
@@ -1222,6 +1232,11 @@ rknn:
| **Model Input D Type** | `int` (Frigate's default value) |
| **Object Detection Model Type** | `yolox` |
yaml: |-
detectors:
rknn:
type: rknn
num_cores: 0
model: # required
# name of model (will be automatically downloaded) or path to your own .rknn model file
# possible values are:
@@ -1297,11 +1312,12 @@ degirumAiServer:
| **Zoo** | `degirum/public` |
| **Token** | your AI Hub token (optional for the public zoo) |
yaml: |
degirum_detector:
type: degirum
location: degirum
zoo: degirum/public
token: dg_example_token
detectors:
degirum_detector:
type: degirum
location: degirum
zoo: degirum/public
token: dg_example_token
degirumLocal:
title: DeGirum Local
models:
@@ -1318,11 +1334,12 @@ degirumLocal:
| **Zoo** | `degirum/public` |
| **Token** | your AI Hub token (optional for the public zoo) |
yaml: |
degirum_detector:
type: degirum
location: @local
zoo: degirum/public
token: dg_example_token
detectors:
degirum_detector:
type: degirum
location: "@local"
zoo: degirum/public
token: dg_example_token
degirumCloud:
title: DeGirum AI Hub Cloud
models:
@@ -1339,8 +1356,9 @@ degirumCloud:
| **Zoo** | `degirum/public` |
| **Token** | your AI Hub token (optional for the public zoo) |
yaml: |
degirum_detector:
type: degirum
location: @cloud
zoo: degirum/public
token: dg_example_token
detectors:
degirum_detector:
type: degirum
location: "@cloud"
zoo: degirum/public
token: dg_example_token
@@ -4,6 +4,7 @@ title: License Plate Recognition (LPR)
---
import ConfigTabs from "@site/src/components/ConfigTabs";
import FrigateConfigMock from "@site/src/components/FrigateConfigMock";
import TabItem from "@theme/TabItem";
import NavPath from "@site/src/components/NavPath";
import FaqItem from "@site/src/components/FaqItem";
@@ -50,9 +51,11 @@ License plate recognition is disabled by default and must be enabled before it c
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
- Set **Enable LPR** to on
<FrigateConfigMock
section="lpr"
values={{ enabled: true }}
targets={["enabled"]}
/>
</TabItem>
<TabItem value="yaml">
@@ -70,7 +73,17 @@ Like other enrichments in Frigate, LPR **must be enabled globally** to use the f
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Camera configuration > License plate recognition" /> for the desired camera and disable the **Enable LPR** toggle.
<FrigateConfigMock
section="lpr"
level="camera"
values={{ enabled: false }}
targets={[
{
field: "enabled",
hint: "Disable the Enable LPR toggle for this camera.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -99,16 +112,40 @@ Fine-tune the LPR feature using these optional parameters. The only optional par
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
- **Detection threshold**: License plate object detection confidence score required before recognition runs. This field only applies to the standalone license plate detection model; `threshold` and `min_score` object filters should be used for models like Frigate+ that have license plate detection built in.
- Default: `0.7`
- **Minimum plate area**: Minimum area (in pixels) a license plate must be before recognition runs. This is an _area_ measurement (length x width). For reference, 1000 pixels represents a ~32x32 pixel square in your camera image. Depending on the resolution of your camera's `detect` stream, you can increase this value to ignore small or distant plates.
- Default: `1000` pixels
- **Device**: Device to use to run license plate detection _and_ recognition models. Auto-selected by Frigate and can be `CPU`, `GPU`, or the GPU's device number. For users without a model that detects license plates natively, using a GPU may increase performance of the YOLOv9 license plate detector model. See the [Hardware Accelerated Enrichments](/configuration/hardware_acceleration_enrichments.md) documentation.
- Default: `None`
- **Model size**: The size of the model used to identify regions of text on plates. The `small` model is fast and identifies groups of Latin and Chinese characters. The `large` model identifies Latin characters only, and uses an enhanced text detector to find characters on multi-line plates. If your country or region does not use multi-line plates, you should use the `small` model.
- Default: `small`
<FrigateConfigMock
showNavigationSteps={false}
section="lpr"
autoPlay={false}
values={{
enabled: true,
detection_threshold: 0.7,
min_area: 1000,
device: "CPU",
model_size: "small",
}}
targets={[
{
field: "detection_threshold",
hint:
"License plate object detection confidence score required before recognition runs. This field only applies to the standalone license plate detection model; threshold and min_score object filters should be used for models like Frigate+ that have license plate detection built in.",
},
{
field: "min_area",
hint:
"Minimum area (in pixels) a license plate must be before recognition runs. This is an area measurement (length x width). For reference, 1000 pixels represents a ~32x32 pixel square in your camera image. Depending on the resolution of your camera's detect stream, you can increase this value to ignore small or distant plates.",
},
{
field: "device",
hint:
"Device to use to run license plate detection and recognition models. Auto-selected by Frigate and can be CPU, GPU, or the GPU's device number. For users without a model that detects license plates natively, using a GPU may increase performance of the YOLOv9 license plate detector model. See the Hardware Accelerated Enrichments documentation.",
},
{
field: "model_size",
hint:
"The size of the model used to identify regions of text on plates. The small model is fast and identifies groups of Latin and Chinese characters. The large model identifies Latin characters only, and uses an enhanced text detector to find characters on multi-line plates. If your country or region does not use multi-line plates, you should use the small model.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -130,12 +167,34 @@ lpr:
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
- **Recognition threshold**: Recognition confidence score required to add the plate to the object as a `recognized_license_plate` and/or `sub_label`.
- Default: `0.9`
- **Min plate length**: Minimum number of characters a detected license plate must have to be added as a `recognized_license_plate` and/or `sub_label`. Use this to filter out short, incomplete, or incorrect detections.
- **Plate format regex**: A regular expression defining the expected format of detected plates. Plates that do not match this format will be discarded. Websites like https://regex101.com/ can help test regular expressions for your plates.
<FrigateConfigMock
showNavigationSteps={false}
section="lpr"
autoPlay={false}
values={{
enabled: true,
recognition_threshold: 0.9,
min_plate_length: 4,
format: "^[A-Z]{2}[0-9]{2} [A-Z]{3}$",
}}
targets={[
{
field: "recognition_threshold",
hint:
"Recognition confidence score required to add the plate to the object as a recognized_license_plate and/or sub_label.",
},
{
field: "min_plate_length",
hint:
"Minimum number of characters a detected license plate must have to be added as a recognized_license_plate and/or sub_label. Use this to filter out short, incomplete, or incorrect detections.",
},
{
field: "format",
hint:
"A regular expression defining the expected format of detected plates. Plates that do not match this format will be discarded. Websites like https://regex101.com/ can help test regular expressions for your plates.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -156,10 +215,31 @@ lpr:
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
- **Known plates**: Assign custom `sub_label` values to `car` and `motorcycle` objects when a recognized plate matches a known value. These labels appear in the UI, filters, and notifications. Unknown plates are still saved but are added to the `recognized_license_plate` field rather than the `sub_label`.
- **Match distance**: Allows for minor variations (missing/incorrect characters) when matching a detected plate to a known plate. For example, setting to `1` allows a plate `ABCDE` to match `ABCBE` or `ABCD`. This parameter will _not_ operate on known plates that are defined as regular expressions.
<FrigateConfigMock
showNavigationSteps={false}
section="lpr"
autoPlay={false}
values={{
enabled: true,
match_distance: 1,
known_plates: {
"Wife's Car": ["ABC-1234"],
Johnny: ["J*N-*234"],
},
}}
targets={[
{
field: "match_distance",
hint:
"Allows for minor variations (missing/incorrect characters) when matching a detected plate to a known plate. For example, setting to 1 allows a plate ABCDE to match ABCBE or ABCD. This parameter will not operate on known plates that are defined as regular expressions.",
},
{
field: "known_plates",
hint:
"Assign custom sub_label values to car and motorcycle objects when a recognized plate matches a known value. These labels appear in the UI, filters, and notifications. Unknown plates are still saved but are added to the recognized_license_plate field rather than the sub_label.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -183,10 +263,19 @@ lpr:
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
- **Enhancement level**: A value between 0 and 10 that adjusts the level of image enhancement applied to captured license plates before they are processed for recognition. Higher values increase contrast, sharpen details, and reduce noise, but excessive enhancement can blur or distort characters. This setting is best adjusted at the camera level if running LPR on multiple cameras.
- Default: `0` (no enhancement)
<FrigateConfigMock
showNavigationSteps={false}
section="lpr"
autoPlay={false}
values={{ enabled: true, enhancement: 1 }}
targets={[
{
field: "enhancement",
hint:
"A value between 0 and 10 that adjusts the level of image enhancement applied to captured license plates before they are processed for recognition. Higher values increase contrast, sharpen details, and reduce noise, but excessive enhancement can blur or distort characters. This setting is best adjusted at the camera level if running LPR on multiple cameras.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -207,17 +296,27 @@ If Frigate is already recognizing plates correctly, leave enhancement at the def
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
Under **Replacement rules**, add regex rules to normalize detected plate strings before matching. Rules fire in order. For example:
| Pattern | Replacement | Description |
| ---------------- | ----------- | -------------------------------------------------- |
| `[%#*?]` | _(empty)_ | Remove noise symbols |
| `[= ]` | `-` | Normalize `=` or space to dash |
| `O` | `0` | Swap `O` to `0` (common OCR error) |
| `I` | `1` | Swap `I` to `1` |
| `(\w{3})(\w{3})` | `\1-\2` | Split 6 chars into groups (e.g., ABC123 → ABC-123) |
<FrigateConfigMock
showNavigationSteps={false}
section="lpr"
autoPlay={false}
values={{
replace_rules: [
{ pattern: "[%#*?]", replacement: "" },
{ pattern: "[= ]", replacement: "-" },
{ pattern: "O", replacement: "0" },
{ pattern: "I", replacement: "1" },
{ pattern: "(\\w{3})(\\w{3})", replacement: "\\1-\\2" },
],
}}
targets={[
{
field: "replace_rules",
hint:
"Add regex rules to normalize detected plate strings before matching. Rules fire in order.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -252,9 +351,19 @@ These rules must be defined at the global level of your `lpr` config.
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
- **Save debug plates**: Set to on to save captured text on plates for debugging. These images are stored in `/media/frigate/clips/lpr`, organized into subdirectories by `<camera>/<event_id>`, and named based on the capture timestamp.
<FrigateConfigMock
showNavigationSteps={false}
section="lpr"
autoPlay={false}
values={{ enabled: true, debug_save_plates: true }}
targets={[
{
field: "debug_save_plates",
hint:
"Set to on to save captured text on plates for debugging. These images are stored in /media/frigate/clips/lpr and named based on the capture timestamp.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -279,17 +388,35 @@ These configuration parameters are available at the global level. The only optio
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
| Field | Description |
| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **Enable LPR** | Set to on |
| **Minimum plate area** | Set to `1500` to ignore plates with an area (length x width) smaller than 1500 pixels |
| **Min plate length** | Set to `4` to only recognize plates with 4 or more characters |
| **Known plates > Wife's Car** | `ABC-1234`, `ABC-I234` (accounts for potential confusion between the number one and capital letter I) |
| **Known plates > Johnny** | `J*N-*234` (matches JHN-1234 and JMN-I234; `*` matches any number of characters) |
| **Known plates > Sally** | `[S5]LL 1234` (matches both SLL 1234 and 5LL 1234) |
| **Known plates > Work Trucks** | `EMP-[0-9]{3}[A-Z]` (matches plates like EMP-123A, EMP-456Z) |
<FrigateConfigMock
showNavigationSteps={false}
section="lpr"
autoPlay={false}
values={{
enabled: true,
min_area: 1500,
min_plate_length: 4,
known_plates: {
"Wife's Car": ["ABC-1234", "ABC-I234"],
Johnny: ["J*N-*234"],
Sally: ["[S5]LL 1234"],
"Work Trucks": ["EMP-[0-9]{3}[A-Z]"],
},
}}
targets={[
{ field: "enabled", hint: "Set to on." },
{
field: "min_area",
hint:
"Set to 1500 to ignore plates with an area (length x width) smaller than 1500 pixels.",
},
{
field: "min_plate_length",
hint: "Set to 4 to only recognize plates with 4 or more characters.",
},
"known_plates",
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -321,7 +448,18 @@ If a camera is configured to detect `car` or `motorcycle` but you don't want Fri
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Camera configuration > License plate recognition" /> for the desired camera and disable the **Enable LPR** toggle.
<FrigateConfigMock
autoPlay={false}
section="lpr"
level="camera"
values={{ enabled: false }}
targets={[
{
field: "enabled",
hint: "Disable the Enable LPR toggle for this camera.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -362,48 +500,93 @@ An example configuration for a dedicated LPR camera using a `license_plate`-dete
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" /> and set **Enable LPR** to on. Set **Device** to `CPU` (can also be `GPU` if available).
Navigate to <NavPath path="Settings > Camera configuration > Streams (FFmpeg)" /> and add your camera streams.
Navigate to <NavPath path="Settings > Camera configuration > Object detection" />.
| Field | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Enable object detection** | Set to on |
| **Detect FPS** | Set to `5`. Increase to `10` if vehicles move quickly across your frame. Higher than 10 is unnecessary and is not recommended. |
| **Minimum initialization frames** | Set to `2` |
| **Detect width** | Set to `1920` |
| **Detect height** | Set to `1080` |
Navigate to <NavPath path="Settings > Camera configuration > Objects" />.
| Field | Description |
| ---------------------------------------------- | ------------------- |
| **Objects to track** | Add `license_plate` |
| **Object filters > License Plate > Threshold** | Set to `0.7` |
Navigate to <NavPath path="Settings > Camera configuration > Motion detection" />.
| Field | Description |
| -------------------- | --------------------------------------------------------------------- |
| **Motion threshold** | Set to `30` |
| **Contour area** | Set to `60`. Use an increased value to tune out small motion changes. |
| **Improve contrast** | Set to off |
Also add a motion mask over your camera's timestamp so it is not incorrectly detected as a license plate.
Navigate to <NavPath path="Settings > Camera configuration > Recording" />.
| Field | Description |
| -------------------- | -------------------------------------------------------- |
| **Enable recording** | Set to on. Disable recording if you only want snapshots. |
Navigate to <NavPath path="Settings > Camera configuration > Snapshots" />.
| Field | Description |
| -------------------- | ----------- |
| **Enable snapshots** | Set to on |
<FrigateConfigMock
section="lpr"
autoPlay={false}
steps={[
{
section: "lpr",
level: "global",
values: { enabled: true, device: "CPU" },
targets: ["enabled", "device"],
},
{
section: "detect",
level: "camera",
values: {
enabled: true,
fps: 5,
min_initialized: 2,
width: 1920,
height: 1080,
},
targets: [
{ field: "enabled", hint: "Set to on." },
{
field: "fps",
hint:
"Set to 5. Increase to 10 if vehicles move quickly across your frame. Higher than 10 is unnecessary and is not recommended.",
},
{ field: "min_initialized", hint: "Set to 2." },
{ field: "width", hint: "Set to 1920." },
{ field: "height", hint: "Set to 1080." },
],
},
{
section: "objects",
level: "camera",
values: {
track: ["license_plate"],
filters: { license_plate: { threshold: 0.7 } },
},
targets: [
{ field: "track", hint: "Add license_plate." },
"filters",
],
},
{
section: "motion",
level: "camera",
values: {
threshold: 30,
contour_area: 60,
improve_contrast: false,
},
targets: [
{ field: "threshold", hint: "Set to 30." },
{
field: "contour_area",
hint:
"Set to 60. Use an increased value to tune out small motion changes.",
},
{ field: "improve_contrast", hint: "Set to off." },
],
},
{
section: "record",
level: "camera",
values: { enabled: true },
targets: [
{
field: "enabled",
hint: "Set to on. Disable recording if you only want snapshots.",
},
],
},
{
section: "snapshots",
level: "camera",
values: { enabled: true },
targets: [{ field: "enabled", hint: "Set to on." }],
},
{
section: "review",
level: "camera",
values: { "detections.labels": ["license_plate"] },
targets: ["detections.labels"],
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -467,54 +650,104 @@ An example configuration for a dedicated LPR camera using the secondary pipeline
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" /> and set **Enable LPR** to on. Set **Device** to `CPU` (can also be `GPU` if available and the correct Docker image is used). Set **Detection threshold** to `0.7` (change if necessary).
Navigate to <NavPath path="Settings > Camera configuration > License plate recognition" /> for your dedicated LPR camera.
| Field | Description |
| --------------------- | -------------------------------------------------------------------------------- |
| **Enable LPR** | Set to on |
| **Enhancement level** | Set to `3` (optional, enhances the image before trying to recognize characters) |
Navigate to <NavPath path="Settings > Camera configuration > Streams (FFmpeg)" /> and add your camera streams.
Navigate to <NavPath path="Settings > Camera configuration > Object detection" />.
| Field | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Enable object detection** | Set to off to disable Frigate's standard object detection pipeline |
| **Detect FPS** | Set to `5`. Increase if necessary, though high values may slow down Frigate's enrichments pipeline and use considerable CPU. |
| **Detect width** | Set to `1920` (recommended value, but depends on your camera) |
| **Detect height** | Set to `1080` (recommended value, but depends on your camera) |
Navigate to <NavPath path="Settings > Camera configuration > Objects" />.
| Field | Description |
| -------------------- | -------------------------------------------------------------------------------------- |
| **Objects to track** | Set to an empty list, required when not using a Frigate+ model for dedicated LPR mode |
Navigate to <NavPath path="Settings > Camera configuration > Motion detection" />.
| Field | Description |
| -------------------- | --------------------------------------------------------------------- |
| **Motion threshold** | Set to `30` |
| **Contour area** | Set to `60`. Use an increased value to tune out small motion changes. |
| **Improve contrast** | Set to off |
Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and add a motion mask over your camera's timestamp so it is not incorrectly detected as a license plate.
Navigate to <NavPath path="Settings > Camera configuration > Recording" />.
| Field | Description |
| -------------------- | -------------------------------------------------------- |
| **Enable recording** | Set to on. Disable recording if you only want snapshots. |
Navigate to <NavPath path="Settings > Camera configuration > Review" />.
| Field | Description |
| ----------------------------------------- | --------------- |
| **Detections config > Enable detections** | Set to on |
| **Detections config > Retain > Default** | Set to `7` days |
<FrigateConfigMock
steps={[
{
section: "lpr",
level: "global",
values: {
enabled: true,
device: "CPU",
detection_threshold: 0.7,
},
targets: ["enabled", "device", "detection_threshold"],
},
{
section: "lpr",
level: "camera",
values: { enabled: true, enhancement: 3 },
targets: [
{ field: "enabled", hint: "Set to on." },
{
field: "enhancement",
hint:
"Set to 3. This optional setting enhances the image before trying to recognize characters.",
},
],
},
{
section: "detect",
level: "camera",
values: { enabled: false, fps: 5, width: 1920, height: 1080 },
targets: [
{
field: "enabled",
hint: "Set to off to disable Frigate's standard object detection pipeline.",
},
{
field: "fps",
hint:
"Set to 5. Increase if necessary, though high values may slow down Frigate's enrichments pipeline and use considerable CPU.",
},
{
field: "width",
hint: "Set to 1920. The appropriate value depends on your camera.",
},
{
field: "height",
hint: "Set to 1080. The appropriate value depends on your camera.",
},
],
},
{
section: "objects",
level: "camera",
values: { track: [] },
targets: [
{
field: "track",
hint:
"Set to an empty list. This is required when not using a Frigate+ model for dedicated LPR mode.",
},
],
},
{
section: "motion",
level: "camera",
values: {
threshold: 30,
contour_area: 60,
improve_contrast: false,
},
targets: [
{ field: "threshold", hint: "Set to 30." },
{
field: "contour_area",
hint:
"Set to 60. Use an increased value to tune out small motion changes.",
},
{ field: "improve_contrast", hint: "Set to off." },
],
},
{
section: "record",
level: "camera",
values: { enabled: true },
targets: [
{
field: "enabled",
hint: "Set to on. Disable recording if you only want snapshots.",
},
],
},
{
section: "review",
level: "camera",
values: { "detections.enabled": true },
targets: ["detections.enabled"],
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -655,11 +888,13 @@ Start with ["Why isn't my license plate being detected and recognized?"](#why-is
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Enrichments > License plate recognition" />.
- Set **Enable LPR** to on
- Set **Device** to `CPU`
- Set **Save debug plates** to on
<FrigateConfigMock
autoPlay={false}
section="lpr"
showNavigationSteps={false}
values={{ enabled: true, device: "CPU", debug_save_plates: true }}
targets={["enabled", "device", "debug_save_plates"]}
/>
</TabItem>
<TabItem value="yaml">
+53 -8
View File
@@ -5,7 +5,7 @@ title: Masks
import ConfigTabs from "@site/src/components/ConfigTabs";
import TabItem from "@theme/TabItem";
import NavPath from "@site/src/components/NavPath";
import FrigateConfigMock from "@site/src/components/FrigateConfigMock";
Frigate has two kinds of masks: motion masks and object filter masks. Both are narrow tools for fine-tuning, **not for hiding an area from Frigate**. Masks should be used sparingly; in most cases where users reach for one, a [zone](zones.md) with [`required_zones`](zones.md#restricting-alerts-and-detections-to-specific-zones) is the right tool instead. See [Which tool do I need?](#which-tool-do-i-need) and [Common mistakes](#common-mistakes) below if you're new to Frigate's mask behavior.
@@ -25,19 +25,64 @@ Object filter masks can be used to filter out stubborn false positives in fixed
## Which tool do I need?
| What you're trying to do | Recommended tool | How it works |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Only get alerts/detections for activity in the areas you care about, ignoring activity elsewhere (e.g., alert when someone enters your yard, but not when they walk past on the sidewalk) | A [zone](zones.md) combined with [`required_zones`](zones.md#restricting-alerts-and-detections-to-specific-zones) | Frigate keeps detecting and tracking activity everywhere in the frame, but a review item is only created once the bottom-center of an object's bounding box enters a required zone. |
| Stop a stubborn false positive at a specific fixed spot (e.g., a tree base that keeps being detected as a person) | An **object filter mask** for that object type | Any detection of that object type whose bounding-box bottom-center lands inside the mask is treated as a false positive and discarded. |
| Ignore motion in an area that obviously isn't an object of interest (e.g., the camera timestamp, sky, flags, treetops swaying) | A **motion mask** | Motion inside the mask is ignored when deciding whether to run object detection. Objects can still be detected in a motion masked area if motion elsewhere in the frame triggers detection. |
| Stop tracking an object type altogether on this camera (e.g., you never care about cats) | Remove the object from the camera's [`objects.track`](objects.md) list | Frigate skips this object type entirely on this camera, regardless of where it appears. |
| What you're trying to do | Recommended tool | How it works |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Only get alerts/detections for activity in the areas you care about, ignoring activity elsewhere (e.g., alert when someone enters your yard, but not when they walk past on the sidewalk) | A [zone](zones.md) combined with [`required_zones`](zones.md#restricting-alerts-and-detections-to-specific-zones) | Frigate keeps detecting and tracking activity everywhere in the frame, but a review item is only created once the bottom-center of an object's bounding box enters a required zone. |
| Stop a stubborn false positive at a specific fixed spot (e.g., a tree base that keeps being detected as a person) | An **object filter mask** for that object type | Any detection of that object type whose bounding-box bottom-center lands inside the mask is treated as a false positive and discarded. |
| Ignore motion in an area that obviously isn't an object of interest (e.g., the camera timestamp, sky, flags, treetops swaying) | A **motion mask** | Motion inside the mask is ignored when deciding whether to run object detection. Objects can still be detected in a motion masked area if motion elsewhere in the frame triggers detection. |
| Stop tracking an object type altogether on this camera (e.g., you never care about cats) | Remove the object from the camera's [`objects.track`](objects.md) list | Frigate skips this object type entirely on this camera, regardless of where it appears. |
## Using the mask creator
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and select a camera. Use the mask editor to draw motion masks and object filter masks directly on the camera feed. Each mask can be given a friendly name and toggled on or off.
<FrigateConfigMock
level="camera"
section="masksAndZones"
steps={[
{
focus: "motionMasks",
label: "Motion Mask",
hint: "Motion masks prevent unwanted motion from triggering detection. Use them sparingly so object tracking is not disrupted.",
},
{
focus: "motionMask.add",
label: "New Motion Mask",
hint: "Select the plus button beside Motion Mask to create a mask.",
},
{
focus: "motionMask.canvas",
label: "Draw the motion mask",
hint: "Select points on the camera image, then close the polygon by selecting the first point again.",
},
{
focus: "motionMask.options",
label: "Motion mask options",
hint: "Give the mask a friendly name and choose whether it is enabled.",
},
{
focus: "objectMasks",
label: "Object Masks",
hint: "Object masks filter false positives according to the bottom center of an object's bounding box.",
},
{
focus: "objectMask.add",
label: "New Object Mask",
hint: "Select the plus button beside Object Masks to create an object filter mask.",
},
{
focus: "objectMask.canvas",
label: "Draw the object mask",
hint: "Draw a precise polygon over the fixed location that produces false positives.",
},
{
focus: "objectMask.options",
label: "Object mask options",
hint: "Name the mask, select the object type it applies to, and save it.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
+8 -7
View File
@@ -4,6 +4,7 @@ title: Motion Detection
---
import ConfigTabs from "@site/src/components/ConfigTabs";
import FrigateConfigMock from "@site/src/components/FrigateConfigMock";
import TabItem from "@theme/TabItem";
import NavPath from "@site/src/components/NavPath";
@@ -44,13 +45,13 @@ The threshold value dictates how much of a change in a pixels luminance is requi
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Global configuration > Motion detection" /> to set the threshold globally.
To override for a specific camera, navigate to <NavPath path="Settings > Camera configuration > Motion detection" /> and select the camera, or use the <NavPath path="Settings > Camera configuration > Motion tuner" /> to adjust it live.
| Field | Description |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Motion threshold** | The threshold passed to cv2.threshold to determine if a pixel is different enough to be counted as motion. Increasing this value will make motion detection less sensitive and decreasing it will make motion detection more sensitive. The value should be between 1 and 255. (default: 30) |
<FrigateConfigMock
section="motion"
fields={["threshold"]}
values={{ threshold: 30 }}
focus="threshold"
hint="The threshold passed to cv2.threshold to determine if a pixel is different enough to be counted as motion. Increasing this value will make motion detection less sensitive and decreasing it will make motion detection more sensitive. The value should be between 1 and 255. (default: 30)"
/>
</TabItem>
<TabItem value="yaml">
+91 -6
View File
@@ -5,6 +5,7 @@ title: Object Detectors
import CommunityBadge from '@site/src/components/CommunityBadge';
import ConfigTabs from '@site/src/components/ConfigTabs';
import FrigateConfigMock from '@site/src/components/FrigateConfigMock';
import TabItem from '@theme/TabItem';
import NavPath from '@site/src/components/NavPath';
import ModelConfigDropdown from '@site/src/components/ModelConfigDropdown';
@@ -112,7 +113,17 @@ See [common Edge TPU troubleshooting steps](/troubleshooting/edgetpu) if the Edg
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > System > Detectors and model" /> and select **EdgeTPU** from the detector type dropdown and click **Add**, then set device to `usb`.
<FrigateConfigMock
autoPlay={false}
section="model"
values={{ detectors: { coral: { type: "edgetpu", device: "usb" } } }}
targets={[
{
field: "detectors",
hint: "Add an EdgeTPU detector named coral and set its device to usb.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -132,7 +143,24 @@ detectors:
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > System > Detectors and model" /> and select **EdgeTPU** from the detector type dropdown and click **Add** to add multiple detectors, specifying `usb:0` and `usb:1` as the device for each.
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
section="model"
values={{
detectors: {
coral1: { type: "edgetpu", device: "usb:0" },
coral2: { type: "edgetpu", device: "usb:1" },
},
}}
targets={[
{
field: "detectors",
hint:
"Add two EdgeTPU detectors and assign usb:0 and usb:1 as their devices.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -157,7 +185,19 @@ _warning: may have [compatibility issues](https://github.com/blakeblackshear/fri
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > System > Detectors and model" /> and select **EdgeTPU** from the detector type dropdown and click **Add**, then leave the device field empty.
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
section="model"
values={{ detectors: { coral: { type: "edgetpu", device: "" } } }}
targets={[
{
field: "detectors",
hint:
"Add an EdgeTPU detector and leave Device empty so Frigate auto-detects the native Coral.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -177,7 +217,18 @@ detectors:
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > System > Detectors and model" /> and select **EdgeTPU** from the detector type dropdown and click **Add**, then set device to `pci`.
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
section="model"
values={{ detectors: { coral: { type: "edgetpu", device: "pci" } } }}
targets={[
{
field: "detectors",
hint: "Add an EdgeTPU detector named coral and set its device to pci.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -197,7 +248,24 @@ detectors:
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > System > Detectors and model" /> and select **EdgeTPU** from the detector type dropdown and click **Add** to add multiple detectors, specifying `pci:0` and `pci:1` as the device for each.
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
section="model"
values={{
detectors: {
coral1: { type: "edgetpu", device: "pci:0" },
coral2: { type: "edgetpu", device: "pci:1" },
},
}}
targets={[
{
field: "detectors",
hint:
"Add two EdgeTPU detectors and assign pci:0 and pci:1 as their devices.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -220,7 +288,24 @@ detectors:
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > System > Detectors and model" /> and select **EdgeTPU** from the detector type dropdown and click **Add** to add multiple detectors with different device types (e.g., `usb` and `pci`).
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
section="model"
values={{
detectors: {
coral_usb: { type: "edgetpu", device: "usb" },
coral_pci: { type: "edgetpu", device: "pci" },
},
}}
targets={[
{
field: "detectors",
hint:
"Add two EdgeTPU detectors and assign usb to one device and pci to the other.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
+134 -48
View File
@@ -5,7 +5,7 @@ title: Zones
import ConfigTabs from "@site/src/components/ConfigTabs";
import TabItem from "@theme/TabItem";
import NavPath from "@site/src/components/NavPath";
import FrigateConfigMock from "@site/src/components/FrigateConfigMock";
Zones allow you to define a specific area of the frame and apply additional filters for object types so you can determine whether or not an object is within a particular area. Presence in a zone is evaluated based on the bottom center of the bounding box for the object. It does not matter how much of the bounding box overlaps with the zone.
@@ -25,11 +25,32 @@ During testing, enable the Zones option for the [Debug view](/usage/live#the-sin
<ConfigTabs>
<TabItem value="ui">
1. Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and select the desired camera.
2. Under the **Zones** section, click the plus icon to add a new zone.
3. Click on the camera's latest image to create the points for the zone boundary. Click the first point again to close the polygon.
4. Configure zone options such as **Friendly name**, **Objects**, **Loitering time**, and **Inertia** in the zone editor.
5. Press **Save** when finished.
<FrigateConfigMock
level="camera"
section="masksAndZones"
steps={[
{
focus: "zone.add",
label: "Add Zone",
hint: "Select the plus button beside Zones to create a zone.",
},
{
focus: "zone.canvas",
label: "Draw the zone",
hint: "Select points on the camera image, then close the polygon by selecting the first point again.",
},
{
focus: "zone.options",
label: "Zone options",
hint: "Configure the friendly name, objects, loitering time, inertia, and optional speed settings.",
},
{
focus: "zone.save",
label: "Save",
hint: "Save the zone after its boundary and options are complete.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -57,11 +78,14 @@ To create an alert only when an object enters the `entire_yard` zone:
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Camera configuration > Review" />.
| Field | Description |
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
| **Alerts config > Required zones** | Set to `entire_yard` so an object must enter that zone to be considered an alert; leave empty to allow alerts anywhere in the frame. |
<FrigateConfigMock
autoPlay={false}
level="camera"
section="review"
focus="alerts.required_zones"
values={{ "alerts.required_zones": ["entire_yard"] }}
hint="Select entire_yard so an object must enter that zone to be considered an alert."
/>
</TabItem>
<TabItem value="yaml">
@@ -87,12 +111,26 @@ You may also want to filter detections to only be created when an object enters
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > Camera configuration > Review" />.
| Field | Description |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Alerts config > Required zones** | Set to `inner_yard` so an object must enter that zone to be considered an alert; leave empty to allow alerts anywhere in the frame. |
| **Detections config > Required zones** | Set to `edge_yard` so an object must enter that zone to be considered a detection; leave empty to allow detections anywhere in the frame. |
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
level="camera"
section="review"
values={{
"alerts.required_zones": ["inner_yard"],
"detections.required_zones": ["edge_yard"],
}}
targets={[
{
field: "alerts.required_zones",
hint: "Select inner_yard so an object must enter the inner area to be considered an alert.",
},
{
field: "detections.required_zones",
hint: "Select edge_yard so activity in the secondary area can be retained as a detection.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -126,8 +164,15 @@ To only save snapshots when an object enters a specific zone, for example an `en
<ConfigTabs>
<TabItem value="ui">
1. Navigate to <NavPath path="Settings > Camera configuration > Snapshots" /> and select your camera.
- Set **Required zones** to `entire_yard`
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
level="camera"
section="snapshots"
focus="required_zones"
values={{ required_zones: ["entire_yard"] }}
hint="Select entire_yard to save snapshots only after an object enters that zone."
/>
</TabItem>
<TabItem value="yaml">
@@ -154,11 +199,15 @@ Sometimes you want to limit a zone to specific object types to have more granula
<ConfigTabs>
<TabItem value="ui">
1. Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and select the desired camera.
2. Create a zone named `entire_yard` covering everywhere you want to track a person.
- Under **Objects**, add `person`
3. Create a second zone named `front_yard_street` covering just the street.
- Under **Objects**, add `car`
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
level="camera"
section="masksAndZones"
focus="zone.objects"
label="Objects"
hint="Choose which object types apply to the zone. For example, use person for the yard and car for the street."
/>
</TabItem>
<TabItem value="yaml">
@@ -198,10 +247,15 @@ When using loitering zones, a review item will behave in the following way:
<ConfigTabs>
<TabItem value="ui">
1. Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and select the desired camera.
2. Edit or create the zone (e.g., `sidewalk`).
- Set **Loitering time** to the desired number of seconds (e.g., `4`)
- Under **Objects**, add the relevant object types (e.g., `person`)
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
level="camera"
section="masksAndZones"
focus="zone.loitering_time"
label="Loitering Time"
hint="Set the minimum number of seconds an object must remain in the zone before the zone activates."
/>
</TabItem>
<TabItem value="yaml">
@@ -227,9 +281,15 @@ Sometimes an objects bounding box may be slightly incorrect and the bottom cente
<ConfigTabs>
<TabItem value="ui">
1. Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and select the desired camera.
2. Edit or create the zone (e.g., `front_yard`).
- Set **Inertia** to the desired number of consecutive frames (e.g., `3`)
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
level="camera"
section="masksAndZones"
focus="zone.inertia"
label="Inertia"
hint="Set the number of consecutive frames an object must be inside the zone. The default is 3."
/>
</TabItem>
<TabItem value="yaml">
@@ -253,9 +313,15 @@ There may also be cases where you expect an object to quickly enter and exit a z
<ConfigTabs>
<TabItem value="ui">
1. Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and select the desired camera.
2. Edit or create the zone (e.g., `driveway_entrance`).
- Set **Inertia** to `1`
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
level="camera"
section="masksAndZones"
focus="zone.inertia"
label="Inertia"
hint="Set Inertia to 1 when an object should be considered inside the zone immediately."
/>
</TabItem>
<TabItem value="yaml">
@@ -289,11 +355,23 @@ Accurate real-world distance measurements are required to estimate speeds. These
<ConfigTabs>
<TabItem value="ui">
1. Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and select the desired camera.
2. Create or edit a zone with exactly 4 points aligned to the ground plane.
3. In the zone editor, enter the real-world **Distances** between each pair of consecutive points.
- For example, if the distance between the first and second points is 10 meters, between the second and third is 12 meters, etc.
4. Distances are measured in meters (metric) or feet (imperial), depending on the **Unit system** setting.
<FrigateConfigMock
level="camera"
showNavigationSteps={false}
section="masksAndZones"
steps={[
{
focus: "zone.canvas",
label: "Draw a four-point zone",
hint: "Draw exactly four points aligned to the ground plane where objects will travel.",
},
{
focus: "zone.speed",
label: "Speed Estimation",
hint: "Enter the real-world distance between each pair of consecutive points. Units follow the UI unit system setting.",
},
]}
/>
</TabItem>
<TabItem value="yaml">
@@ -317,11 +395,14 @@ The `distance` values are measured in meters (metric) or feet (imperial), depend
<ConfigTabs>
<TabItem value="ui">
Navigate to <NavPath path="Settings > System > UI" />.
| Field | Description |
| --------------- | -------------------------------------------------------------------- |
| **Unit system** | Set to `metric` (kilometers per hour) or `imperial` (miles per hour) |
<FrigateConfigMock
autoPlay={false}
level="global"
section="ui"
focus="unit_system"
values={{ unit_system: "metric" }}
hint="Choose metric for kilometers per hour or imperial for miles per hour."
/>
</TabItem>
<TabItem value="yaml">
@@ -356,10 +437,15 @@ Zones can be configured with a minimum speed requirement, meaning an object must
<ConfigTabs>
<TabItem value="ui">
1. Navigate to <NavPath path="Settings > Camera configuration > Masks / Zones" /> and select the desired camera.
2. Edit or create the zone with distances configured.
- Set **Speed threshold** to the desired minimum speed (e.g., `20`)
- The unit is kph or mph, depending on the **Unit system** setting
<FrigateConfigMock
autoPlay={false}
showNavigationSteps={false}
level="camera"
section="masksAndZones"
focus="zone.speed_threshold"
label="Speed Threshold"
hint="Set the minimum speed required for an object to be considered inside the zone. Units follow the UI unit system setting."
/>
</TabItem>
<TabItem value="yaml">
+12 -1
View File
@@ -19,10 +19,12 @@
"docusaurus-plugin-openapi-docs": "^4.5.1",
"docusaurus-theme-openapi-docs": "^4.5.1",
"js-yaml": "^4.1.1",
"marked": "^16.4.2",
"prism-react-renderer": "^2.4.1",
"raw-loader": "^4.0.2",
"react": "^18.3.1",
"react-dom": "^18.3.1"
"react-dom": "^18.3.1",
"react-icons": "^5.7.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^3.7.0",
@@ -18761,6 +18763,15 @@
"react": "^16.8.0 || ^17 || ^18 || ^19"
}
},
"node_modules/react-icons": {
"version": "5.7.0",
"resolved": "https://registry.npmmirror.com/react-icons/-/react-icons-5.7.0.tgz",
"integrity": "sha512-LBLy340Rzqy6+/yVhZKT3B/QpP1BZaesGqasf09HPOBzRarcDIFH0WwXlXQfE7q7ipxK4MSiC5DIBWURCny6fw==",
"license": "MIT",
"peerDependencies": {
"react": "*"
}
},
"node_modules/react-is": {
"version": "16.13.1",
"resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz",
+6 -3
View File
@@ -4,9 +4,11 @@
"private": true,
"scripts": {
"build:config": "node scripts/build-config.mjs",
"build:mock": "node scripts/generate-mock-manifest.mjs",
"check:mock": "node scripts/generate-mock-manifest.mjs --check",
"docusaurus": "docusaurus",
"start": "npm run build:config && npm run regen-docs && docusaurus start --host 0.0.0.0",
"build": "npm run build:config && npm run regen-docs && docusaurus build",
"start": "npm run build:config && npm run build:mock && npm run regen-docs && docusaurus start --host 0.0.0.0",
"build": "npm run build:config && npm run build:mock && npm run regen-docs && docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
@@ -33,7 +35,8 @@
"prism-react-renderer": "^2.4.1",
"raw-loader": "^4.0.2",
"react": "^18.3.1",
"react-dom": "^18.3.1"
"react-dom": "^18.3.1",
"react-icons": "^5.7.0"
},
"browserslist": {
"production": [
+366
View File
@@ -0,0 +1,366 @@
#!/usr/bin/env node
/** Build the compact field catalog used by documentation config mocks. */
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
const repoRoot = path.resolve(scriptDir, "../..");
const schemaPath = path.join(
repoRoot,
"web/e2e/fixtures/mock-data/config-schema.json",
);
const localeRoot = path.join(repoRoot, "web/public/locales/en/config");
const sectionConfigRoot = path.join(
repoRoot,
"web/src/components/config-form/section-configs",
);
const settingsSourcePath = path.join(repoRoot, "web/src/pages/Settings.tsx");
const settingsLocalePath = path.join(
repoRoot,
"web/public/locales/en/views/settings.json",
);
const outputPath = path.join(
repoRoot,
"docs/src/components/FrigateConfigMock/manifest.json",
);
const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
const translations = {
global: JSON.parse(
fs.readFileSync(path.join(localeRoot, "global.json"), "utf8"),
),
camera: JSON.parse(
fs.readFileSync(path.join(localeRoot, "cameras.json"), "utf8"),
),
groups: JSON.parse(
fs.readFileSync(path.join(localeRoot, "groups.json"), "utf8"),
),
};
const settingsTranslations = JSON.parse(
fs.readFileSync(settingsLocalePath, "utf8"),
);
function resolveNode(node) {
if (!node || typeof node !== "object") return {};
if (node.$ref) {
const refName = node.$ref.split("/").at(-1);
return {
...resolveNode(schema.$defs?.[refName]),
...node,
$ref: undefined,
};
}
const variants = node.anyOf ?? node.oneOf;
if (Array.isArray(variants)) {
const concrete = variants.find((variant) => variant.type !== "null");
return {
...resolveNode(concrete),
...node,
anyOf: undefined,
oneOf: undefined,
};
}
return node;
}
function translationAt(level, section, fieldPath) {
let current = translations[level]?.[section];
for (const segment of fieldPath) {
if (!current || typeof current !== "object") return {};
current = current[segment];
}
return current && typeof current === "object" ? current : {};
}
function inferWidget(node) {
if (Array.isArray(node.enum)) return "select";
if (node.type === "boolean") return "switch";
if (
["integer", "number"].includes(node.type) &&
node.minimum !== undefined &&
(node.maximum !== undefined || node.exclusiveMaximum !== undefined)
) {
return "range";
}
if (node.type === "integer" || node.type === "number") return "number";
if (node.type === "array") return "tags";
if (node.type === "object") return "object";
return "text";
}
function extractArray(source, key) {
const match = source.match(new RegExp(`${key}\\s*:\\s*\\[([\\s\\S]*?)\\]`));
return match
? [...match[1].matchAll(/["']([^"']+)["']/g)].map((item) => item[1])
: [];
}
function extractObjectBlock(source, key) {
const match = new RegExp(`\\b${key}\\s*:\\s*\\{`).exec(source);
if (!match) return "";
const start = source.indexOf("{", match.index);
let depth = 0;
let quote = null;
let escaped = false;
for (let index = start; index < source.length; index += 1) {
const character = source[index];
if (quote) {
if (escaped) escaped = false;
else if (character === "\\") escaped = true;
else if (character === quote) quote = null;
continue;
}
if (['"', "'", "`"].includes(character)) {
quote = character;
continue;
}
if (character === "{") depth += 1;
if (character === "}") {
depth -= 1;
if (depth === 0) return source.slice(start + 1, index);
}
}
return "";
}
function extractGroups(source) {
const fieldGroups = {};
const groupsBlock = extractObjectBlock(source, "fieldGroups");
for (const match of groupsBlock.matchAll(/(\w+)\s*:\s*\[([\s\S]*?)\]/g)) {
fieldGroups[match[1]] = [...match[2].matchAll(/["']([^"']+)["']/g)].map(
(item) => item[1],
);
}
return fieldGroups;
}
function loadSectionHints(section, level) {
const configPath = path.join(sectionConfigRoot, `${section}.ts`);
if (!fs.existsSync(configPath)) return {};
const source = fs.readFileSync(configPath, "utf8");
const base = extractObjectBlock(source, "base");
const override = extractObjectBlock(source, level);
const overrideHas = (key) => new RegExp(`\\b${key}\\s*:`).test(override);
return {
order: overrideHas("fieldOrder")
? extractArray(override, "fieldOrder")
: extractArray(base, "fieldOrder"),
hidden: [
...extractArray(base, "hiddenFields"),
...extractArray(override, "hiddenFields"),
],
advanced: overrideHas("advancedFields")
? extractArray(override, "advancedFields")
: extractArray(base, "advancedFields"),
groups: overrideHas("fieldGroups")
? extractGroups(override)
: extractGroups(base),
docs: base.match(/sectionDocs\s*:\s*["']([^"']+)["']/)?.[1] ?? null,
};
}
function groupLabel(level, section, group) {
const domain = level === "camera" ? "cameras" : "global";
return (
translations.groups?.[section]?.[domain]?.[group] ??
group.replaceAll("_", " ").replace(/^./, (value) => value.toUpperCase())
);
}
function collectFields(level, section, sectionNode, hints) {
const fields = {};
function visit(rawNode, fieldPath = []) {
const node = resolveNode(rawNode);
const properties = node.properties;
if (properties && typeof properties === "object") {
for (const [name, child] of Object.entries(properties)) {
visit(child, [...fieldPath, name]);
}
return;
}
if (fieldPath.length === 0) return;
const key = fieldPath.join(".");
const localized = translationAt(level, section, fieldPath);
fields[key] = {
label: localized.label ?? node.title ?? fieldPath.at(-1),
description: localized.description ?? node.description ?? "",
widget: inferWidget(node),
default: node.default ?? null,
enum: node.enum ?? null,
minimum: node.minimum ?? node.exclusiveMinimum ?? null,
maximum: node.maximum ?? node.exclusiveMaximum ?? null,
advanced: hints.advanced?.includes(key) ?? false,
};
}
visit(sectionNode);
return fields;
}
function buildLevel(level) {
const rootProperties =
level === "camera"
? resolveNode(schema.$defs.CameraConfig).properties
: schema.properties;
const result = {};
for (const [section, rawNode] of Object.entries(rootProperties ?? {})) {
const node = resolveNode(rawNode);
if (!node.properties) continue;
const hints = loadSectionHints(section, level);
const hidden = new Set(hints.hidden ?? []);
const fields = collectFields(level, section, node, hints);
for (const key of hidden) delete fields[key];
const localized = translations[level]?.[section] ?? {};
result[section] = {
label: localized.label ?? rawNode.title ?? node.title ?? section,
description: localized.description ?? rawNode.description ?? "",
order: hints.order ?? [],
groups: Object.entries(hints.groups ?? {}).map(([key, groupFields]) => ({
key,
label: groupLabel(level, section, key),
fields: groupFields,
})),
docs: hints.docs ?? null,
fields,
};
}
return result;
}
function parseSectionMapping(source, constantName, level) {
const match = source.match(
new RegExp(`const ${constantName}[^=]*=\\s*\\{([\\s\\S]*?)\\n\\};`),
);
if (!match) return [];
return [...match[1].matchAll(/(\w+)\s*:\s*"([^"]+)"/g)].map(
([, section, page]) => ({ section, page, level }),
);
}
function buildNavigation() {
const source = fs.readFileSync(settingsSourcePath, "utf8");
const settingsBlock = source.match(
/const settingsGroups\s*=\s*\[([\s\S]*?)\n\];/,
)?.[1];
if (!settingsBlock) return { groups: [], pages: {} };
const mappings = [
...parseSectionMapping(source, "GLOBAL_SECTION_MAPPING", "global"),
...parseSectionMapping(source, "CAMERA_SECTION_MAPPING", "camera"),
...parseSectionMapping(source, "ENRICHMENTS_SECTION_MAPPING", "global"),
...parseSectionMapping(source, "SYSTEM_SECTION_MAPPING", "global"),
];
const pages = Object.fromEntries(
mappings.map((mapping) => [mapping.page, mapping]),
);
const groupMatches = [...settingsBlock.matchAll(/\{\s*label:\s*"([^"]+)"/g)];
const groups = groupMatches.map((match, index) => {
const start = match.index ?? 0;
const end = groupMatches[index + 1]?.index ?? settingsBlock.length;
const sourceSlice = settingsBlock.slice(start, end);
const itemKeys = [...sourceSlice.matchAll(/key:\s*"([^"]+)"/g)].map(
(item) => item[1],
);
return {
key: match[1],
label: settingsTranslations.menu?.[match[1]] ?? match[1],
items: itemKeys.map((key) => ({
key,
label: settingsTranslations.menu?.[key] ?? key,
...(key === "masksAndZones"
? { section: key, page: key, level: "camera" }
: {}),
...(pages[key] ?? {}),
})),
};
});
return { groups, pages };
}
function buildDetectorTypes() {
const detectorTranslations = translations.global?.detectors ?? {};
const reserved = new Set([
"label",
"description",
"type",
"model",
"model_path",
]);
return Object.fromEntries(
Object.entries(detectorTranslations)
.filter(
([key, value]) =>
!reserved.has(key) &&
value &&
typeof value === "object" &&
typeof value.label === "string" &&
typeof value.description === "string",
)
.map(([type, value]) => [
type,
{
label: value.label,
description: value.description,
fields: Object.fromEntries(
Object.entries(value)
.filter(
([key, field]) =>
!["label", "description"].includes(key) &&
field &&
typeof field === "object" &&
typeof field.label === "string",
)
.map(([key, field]) => [
key,
{
label: field.label,
description: field.description ?? "",
},
]),
),
},
]),
);
}
const manifest = {
generatedFrom: path.relative(repoRoot, schemaPath).replaceAll("\\", "/"),
detectorTypes: buildDetectorTypes(),
levels: {
global: buildLevel("global"),
camera: buildLevel("camera"),
},
navigation: buildNavigation(),
};
const serialized = `${JSON.stringify(manifest, null, 2)}\n`;
if (process.argv.includes("--check")) {
const current = fs.existsSync(outputPath)
? fs.readFileSync(outputPath, "utf8")
: "";
if (current !== serialized) {
console.error(
`${path.relative(repoRoot, outputPath)} is stale. Run npm run build:mock.`,
);
process.exit(1);
}
console.log(`Checked ${path.relative(repoRoot, outputPath)}`);
} else {
fs.mkdirSync(path.dirname(outputPath), { recursive: true });
fs.writeFileSync(outputPath, serialized);
console.log(`Generated ${path.relative(repoRoot, outputPath)}`);
}
+28 -8
View File
@@ -45,7 +45,7 @@ from lib.i18n_loader import load_i18n
from lib.nav_map import ALL_CONFIG_SECTIONS
from lib.schema_loader import load_schema
from lib.section_config_parser import load_section_configs
from lib.ui_generator import generate_ui_content, wrap_with_config_tabs
from lib.ui_generator import generate_mock_content, generate_ui_content, wrap_with_config_tabs
from lib.yaml_extractor import (
extract_config_tabs_blocks,
extract_yaml_blocks,
@@ -60,6 +60,7 @@ def process_file(
inject: bool = False,
verbose: bool = False,
outpath: Path | None = None,
mock: bool = False,
) -> dict:
"""Process a single markdown file for initial injection of bare YAML blocks.
@@ -114,7 +115,8 @@ def process_file(
continue
# Generate UI content
ui_content = generate_ui_content(
generator = generate_mock_content if mock else generate_ui_content
ui_content = generator(
block, schema, i18n, section_configs
)
@@ -188,6 +190,7 @@ def regenerate_file(
dry_run: bool = False,
verbose: bool = False,
outpath: Path | None = None,
mock: bool = False,
) -> dict:
"""Regenerate UI tabs in existing ConfigTabs blocks.
@@ -233,7 +236,8 @@ def regenerate_file(
continue
# Generate fresh UI content
new_ui = generate_ui_content(
generator = generate_mock_content if mock else generate_ui_content
new_ui = generator(
yaml_block, schema, i18n, section_configs
)
@@ -302,6 +306,7 @@ def check_file(
i18n: dict,
section_configs: dict,
verbose: bool = False,
mock: bool = False,
) -> dict:
"""Check for drift between existing UI tabs and what would be generated.
@@ -333,7 +338,8 @@ def check_file(
stats["skipped"] += 1
continue
new_ui = generate_ui_content(
generator = generate_mock_content if mock else generate_ui_content
new_ui = generator(
yaml_block, schema, i18n, section_configs
)
@@ -406,6 +412,10 @@ def _ensure_imports(content: str) -> str:
needed_imports.append(
'import NavPath from "@site/src/components/NavPath";'
)
if "<FrigateConfigMock" in content and 'import FrigateConfigMock' not in content:
needed_imports.append(
'import FrigateConfigMock from "@site/src/components/FrigateConfigMock";'
)
if not needed_imports:
return content
@@ -472,6 +482,11 @@ def main():
action="store_true",
help="Show detailed warnings and diagnostics",
)
parser.add_argument(
"--mock",
action="store_true",
help="Generate focused Frigate UI mocks instead of text instructions",
)
args = parser.parse_args()
# Collect files and determine base directory for relative path computation
@@ -525,23 +540,25 @@ def main():
print(f"Processing {len(files)} file(s)...\n", file=sys.stderr)
if args.check:
_run_check(files, schema, i18n, section_configs, args.verbose)
_run_check(files, schema, i18n, section_configs, args.verbose, args.mock)
elif args.regenerate:
_run_regenerate(
files, schema, i18n, section_configs,
args.dry_run, args.verbose, file_outpaths,
args.mock,
)
else:
_run_inject(
files, schema, i18n, section_configs,
args.inject, args.verbose, file_outpaths,
args.mock,
)
if outdir is not None:
print(f"\nOutput written to: {outdir}", file=sys.stderr)
def _run_inject(files, schema, i18n, section_configs, inject, verbose, file_outpaths):
def _run_inject(files, schema, i18n, section_configs, inject, verbose, file_outpaths, mock):
"""Run default mode: preview or inject bare YAML blocks."""
total_stats = {
"files": 0,
@@ -557,6 +574,7 @@ def _run_inject(files, schema, i18n, section_configs, inject, verbose, file_outp
filepath, schema, i18n, section_configs,
inject=inject, verbose=verbose,
outpath=file_outpaths.get(filepath),
mock=mock,
)
total_stats["files"] += 1
@@ -580,7 +598,7 @@ def _run_inject(files, schema, i18n, section_configs, inject, verbose, file_outp
print("=" * 60, file=sys.stderr)
def _run_regenerate(files, schema, i18n, section_configs, dry_run, verbose, file_outpaths):
def _run_regenerate(files, schema, i18n, section_configs, dry_run, verbose, file_outpaths, mock):
"""Run regenerate mode: update existing ConfigTabs blocks."""
total_stats = {
"files": 0,
@@ -595,6 +613,7 @@ def _run_regenerate(files, schema, i18n, section_configs, dry_run, verbose, file
filepath, schema, i18n, section_configs,
dry_run=dry_run, verbose=verbose,
outpath=file_outpaths.get(filepath),
mock=mock,
)
total_stats["files"] += 1
@@ -617,7 +636,7 @@ def _run_regenerate(files, schema, i18n, section_configs, dry_run, verbose, file
print("=" * 60, file=sys.stderr)
def _run_check(files, schema, i18n, section_configs, verbose):
def _run_check(files, schema, i18n, section_configs, verbose, mock):
"""Run check mode: detect drift without modifying files."""
total_stats = {
"files": 0,
@@ -630,6 +649,7 @@ def _run_check(files, schema, i18n, section_configs, verbose):
for filepath in files:
stats = check_file(
filepath, schema, i18n, section_configs, verbose=verbose,
mock=mock,
)
total_stats["files"] += 1
+76 -1
View File
@@ -1,5 +1,6 @@
"""Generate UI tab markdown content from parsed YAML blocks."""
"""Generate UI tab content from parsed YAML blocks."""
import json
from typing import Any
from .i18n_loader import get_field_description, get_field_label, get_value_label
@@ -9,6 +10,80 @@ from .section_config_parser import get_hidden_fields
from .yaml_extractor import YamlBlock, get_leaf_paths
def generate_mock_content(
block: YamlBlock,
schema: dict[str, Any],
i18n: dict[str, Any],
section_configs: dict[str, dict[str, Any]],
) -> str | None:
"""Generate a focused Frigate config mock for a YAML block."""
if block.section_key is None:
return None
if block.is_camera_level:
cameras = block.parsed.get("cameras", {})
camera_name = block.camera_name or next(iter(cameras), None)
if not camera_name or not isinstance(cameras.get(camera_name), dict):
return None
config = cameras[camera_name]
level = "camera"
else:
config = block.parsed
level = detect_level(block.section_key)
if level not in ("global", "camera"):
level = "global"
steps: list[dict[str, object]] = []
for section, section_data in config.items():
if section not in ALL_CONFIG_SECTIONS or not isinstance(
section_data, dict
):
continue
hidden = get_hidden_fields(section_configs, section, level)
values: dict[str, object] = {}
for path, value in get_leaf_paths(section_data):
path_parts = list(path)
if not _is_hidden(path_parts[-1], path_parts, hidden):
values[".".join(path_parts)] = value
if values:
steps.append(
{
"section": section,
"level": level,
"fields": list(values),
"values": values,
"focus": next(iter(values)),
}
)
if not steps:
return None
if len(steps) == 1:
step = steps[0]
return "\n".join(
[
"<FrigateConfigMock",
f' section="{step["section"]}"',
f' level="{step["level"]}"',
f" fields={{{json.dumps(step['fields'])}}}",
f" values={{{json.dumps(step['values'])}}}",
f' focus="{step["focus"]}"',
"/>",
]
)
return "\n".join(
[
"<FrigateConfigMock",
f" steps={{{json.dumps(steps)}}}",
"/>",
]
)
def _format_value(
value: object,
field_schema: dict[str, Any] | None,
+99
View File
@@ -0,0 +1,99 @@
"""Tests for focused Frigate configuration mock generation."""
import sys
import types
import unittest
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
try:
import yaml # noqa: F401
except ModuleNotFoundError:
yaml_stub = types.ModuleType("yaml")
yaml_stub.YAMLError = ValueError
yaml_stub.safe_load = lambda _value: {}
sys.modules["yaml"] = yaml_stub
from lib.ui_generator import generate_mock_content
from lib.yaml_extractor import YamlBlock
def make_block(parsed: dict, section: str, camera: bool = False) -> YamlBlock:
"""Create a parsed YAML block for generator tests."""
return YamlBlock(
raw="",
parsed=parsed,
line_start=1,
line_end=1,
highlight=None,
has_comments=False,
inside_config_tabs=False,
section_key=section,
is_camera_level=camera,
camera_name="front_door" if camera else None,
config_keys=list(parsed),
)
class TestGenerateMockContent(unittest.TestCase):
def test_generates_focused_global_section(self):
content = generate_mock_content(
make_block({"motion": {"threshold": 30}}, "motion"),
{},
{},
{},
)
self.assertIn('section="motion"', content)
self.assertIn('level="global"', content)
self.assertIn('fields={["threshold"]}', content)
self.assertIn('values={{"threshold": 30}}', content)
self.assertIn('focus="threshold"', content)
def test_unwraps_camera_and_omits_hidden_fields(self):
content = generate_mock_content(
make_block(
{
"cameras": {
"front_door": {
"motion": {
"threshold": 20,
"raw_mask": "ignored",
}
}
}
},
"motion",
camera=True,
),
{},
{},
{"motion": {"hiddenFields": ["raw_mask"]}},
)
self.assertIn('level="camera"', content)
self.assertIn('fields={["threshold"]}', content)
self.assertNotIn("raw_mask", content)
def test_generates_steps_for_multiple_sections(self):
content = generate_mock_content(
make_block(
{
"record": {"enabled": True},
"snapshots": {"enabled": True},
},
"record",
),
{},
{},
{},
)
self.assertIn("steps={", content)
self.assertIn('"section": "record"', content)
self.assertIn('"section": "snapshots"', content)
if __name__ == "__main__":
unittest.main()
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -1,7 +1,9 @@
import React, { useState } from "react";
import React, { useMemo, useState } from "react";
import CodeBlock from "@theme/CodeBlock";
import ConfigTabs from "@site/src/components/ConfigTabs";
import FrigateConfigMock from "@site/src/components/FrigateConfigMock";
import TabItem from "@theme/TabItem";
import { load } from "js-yaml";
import { marked } from "marked";
import styles from "./styles.module.css";
@@ -103,6 +105,40 @@ export default function ModelConfigDropdown({ models }) {
const selectedModel = models[selectedModelIndex];
const hasChoices = models.length > 1;
const mockConfig = useMemo(() => {
try {
const parsed = load(selectedModel.yaml) ?? {};
const model = parsed.model ?? {};
const legacyDetectors = Object.fromEntries(
Object.entries(parsed).filter(
([key, value]) =>
key !== "model" &&
value &&
typeof value === "object" &&
typeof value.type === "string",
),
);
const detectors = parsed.detectors ?? legacyDetectors;
const values = {
detectors,
...model,
};
const targets = [
...(Object.keys(detectors).length ? ["detectors"] : []),
...(Object.keys(model).length
? [
{
field: "custom_model",
hint: `Configure the custom detection model, input size, and input format for ${selectedModel.label}.`,
},
]
: []),
];
return { targets, values };
} catch {
return { targets: ["detectors"], values: { detectors: {} } };
}
}, [selectedModel.label, selectedModel.yaml]);
const handleModelSelect = (index) => {
setSelectedModelIndex(index);
@@ -158,7 +194,13 @@ export default function ModelConfigDropdown({ models }) {
<h4 className={styles.stepTitle}>Step 3 — Configure the detector</h4>
<ConfigTabs>
<TabItem value="ui">
<Markdown>{selectedModel.ui}</Markdown>
<FrigateConfigMock
autoPlay={false}
key={selectedModel.key}
section="model"
targets={mockConfig.targets}
values={mockConfig.values}
/>
</TabItem>
<TabItem value="yaml">
<CodeBlock language="yaml">{selectedModel.yaml}</CodeBlock>
+13 -5
View File
@@ -415,7 +415,7 @@ def create_encoded_jwt(user, role, expiration, secret):
)
def set_jwt_cookie(response: Response, cookie_name, encoded_jwt, expiration, secure):
def set_jwt_cookie(response: Response, cookie_name, encoded_jwt, max_age, secure):
# TODO: ideally this would set secure as well, but that requires TLS
# SameSite is intentionally left unset (browsers default to Lax). Setting
# SameSite=Lax/Strict would stop the cookie from being sent in cross-origin
@@ -427,7 +427,7 @@ def set_jwt_cookie(response: Response, cookie_name, encoded_jwt, expiration, sec
key=cookie_name,
value=encoded_jwt,
httponly=True,
expires=expiration,
max_age=max_age,
secure=secure,
)
@@ -762,7 +762,7 @@ def auth(request: Request):
success_response,
JWT_COOKIE_NAME,
new_encoded_jwt,
new_expiration,
JWT_SESSION_LENGTH,
JWT_COOKIE_SECURE,
)
@@ -875,7 +875,11 @@ def login(request: Request, body: AppPostLoginBody):
encoded_jwt = create_encoded_jwt(user, role, expiration, request.app.jwt_token)
response = Response("", 200)
set_jwt_cookie(
response, JWT_COOKIE_NAME, encoded_jwt, expiration, JWT_COOKIE_SECURE
response,
JWT_COOKIE_NAME,
encoded_jwt,
JWT_SESSION_LENGTH,
JWT_COOKIE_SECURE,
)
# Clear admin_first_time_login flag after successful admin login so the
# UI stops showing the first-time login documentation link.
@@ -1037,7 +1041,11 @@ async def update_password(
)
# Set new JWT cookie on response
set_jwt_cookie(
response, JWT_COOKIE_NAME, encoded_jwt, expiration, JWT_COOKIE_SECURE
response,
JWT_COOKIE_NAME,
encoded_jwt,
JWT_SESSION_LENGTH,
JWT_COOKIE_SECURE,
)
return response
+28 -7
View File
@@ -7,7 +7,7 @@ import operator
import time
from datetime import datetime
from functools import reduce
from typing import Any
from typing import Any, Literal
import cv2
from fastapi import APIRouter, Body, Depends, HTTPException, Request
@@ -37,6 +37,7 @@ from frigate.api.defs.response.chat_response import (
from frigate.api.defs.tags import Tags
from frigate.api.event import _build_attribute_filter_clause, events
from frigate.config import FrigateConfig
from frigate.config.classification import SemanticSearchModelEnum
from frigate.genai.prompts import (
build_chat_system_prompt,
get_attribute_classifications,
@@ -86,10 +87,23 @@ def get_tools(request: Request) -> JSONResponse:
tools = get_tool_definitions(
semantic_search_enabled=semantic_search_enabled,
attribute_classifications=attribute_classifications,
embeddings_language=_embeddings_language(config),
)
return JSONResponse(content={"tools": tools})
def _embeddings_language(config: FrigateConfig) -> Literal["english", "multi"]:
"""Return the language capability of the configured embeddings model.
JinaV1 is English-only; every other option (JinaV2 or a GenAI embeddings
provider) handles multiple languages.
"""
if config.semantic_search.model == SemanticSearchModelEnum.jinav1:
return "english"
return "multi"
def _resolve_zones(
zones: list[str],
config: FrigateConfig,
@@ -98,11 +112,14 @@ def _resolve_zones(
"""Map zone names to their canonical config keys, case-insensitively.
LLMs frequently echo a user's casing ("Front Yard") instead of the
configured key ("front_yard"). The downstream zone filter is a SQLite GLOB
over the JSON-encoded zones column, which is case-sensitive — so an
unnormalized name silently returns zero matches. Build a lookup over the
relevant cameras' configured zones and substitute when we find a match;
unknown names pass through so behavior matches what the model asked for.
configured key ("front_yard"), or fall back to a zone's friendly name
("Front Walkway") instead of its ID ("front_walk"). The downstream zone
filter is a SQLite GLOB over the JSON-encoded zones column, which stores
config keys and is case-sensitive — so an unnormalized name silently
returns zero matches. Build a lookup over the relevant cameras' configured
zones, keyed by both the config key and the friendly name, and substitute
when we find a match; unknown names pass through so behavior matches what
the model asked for.
"""
if not zones:
return zones
@@ -112,8 +129,11 @@ def _resolve_zones(
camera_config = config.cameras.get(camera_id)
if camera_config is None:
continue
for zone_name in camera_config.zones.keys():
for zone_name, zone_config in camera_config.zones.items():
lookup.setdefault(zone_name.lower(), zone_name)
lookup.setdefault(
zone_config.get_formatted_name(zone_name).lower(), zone_name
)
return [lookup.get(z.lower(), z) for z in zones]
@@ -1134,6 +1154,7 @@ async def chat_completion(
tools = get_tool_definitions(
semantic_search_enabled=semantic_search_enabled,
attribute_classifications=attribute_classifications,
embeddings_language=_embeddings_language(config),
)
conversation = []
+7 -3
View File
@@ -1,9 +1,11 @@
import re
import sqlite3
from typing import Any
import regex
from playhouse.sqliteq import SqliteQueueDatabase
REGEXP_TIMEOUT_SECONDS = 1.0
class SqliteVecQueueDatabase(SqliteQueueDatabase):
def __init__(
@@ -34,8 +36,10 @@ class SqliteVecQueueDatabase(SqliteQueueDatabase):
if item is None:
return False
try:
return re.search(expr, item) is not None
except re.error:
return (
regex.search(expr, item, timeout=REGEXP_TIMEOUT_SECONDS) is not None
)
except (regex.error, TimeoutError):
return False
conn.create_function("REGEXP", 2, regexp)
+20 -6
View File
@@ -6,7 +6,7 @@ transport.
"""
import datetime
from typing import Any
from typing import Any, Literal
from playhouse.shortcuts import model_to_dict
@@ -249,6 +249,7 @@ def get_attribute_classifications(config: FrigateConfig) -> list[dict[str, Any]]
def get_tool_definitions(
semantic_search_enabled: bool = False,
attribute_classifications: list[dict[str, Any]] | None = None,
embeddings_language: Literal["english", "multi"] = "multi",
) -> list[dict[str, Any]]:
"""
Get OpenAI-compatible tool definitions for Frigate.
@@ -258,7 +259,9 @@ def get_tool_definitions(
tool exposes an additional `semantic_query` parameter for descriptive
queries (e.g. "person riding a lawn mower") and find_similar_objects is
included. When attribute classification models are configured, an
`attribute` parameter is exposed for filtering by their labels.
`attribute` parameter is exposed for filtering by their labels. When the
embeddings model only understands English (JinaV1), the `semantic_query`
description instructs the model to write the query in English.
"""
search_objects_properties: dict[str, Any] = {
"camera": {
@@ -349,6 +352,14 @@ def get_tool_definitions(
"When set, combine with label/time/camera/zone filters as "
"usual (e.g. label='person', semantic_query='riding a lawn "
"mower', after='2024-05-01T00:00:00Z')."
+ (
" The configured embeddings model only understands "
"English, so always write semantic_query in English, "
"translating the user's description if they phrased it "
"in another language."
if embeddings_language == "english"
else ""
)
),
}
@@ -682,14 +693,17 @@ def build_chat_system_prompt(
if camera_config.friendly_name
else camera_id.replace("_", " ").title()
)
zone_names = list(camera_config.zones.keys())
zone_descriptors = [
f"{zone_config.get_formatted_name(zone_name)} (ID: {zone_name})"
for zone_name, zone_config in camera_config.zones.items()
]
if not has_speed_zone:
has_speed_zone = any(
zone.distances for zone in camera_config.zones.values()
)
if zone_names:
if zone_descriptors:
cameras_info.append(
f" - {friendly_name} (ID: {camera_id}, zones: {', '.join(zone_names)})"
f" - {friendly_name} (ID: {camera_id}, zones: {', '.join(zone_descriptors)})"
)
else:
cameras_info.append(f" - {friendly_name} (ID: {camera_id})")
@@ -699,7 +713,7 @@ def build_chat_system_prompt(
cameras_section = (
"\n\nAvailable cameras:\n"
+ "\n".join(cameras_info)
+ "\n\nWhen users refer to cameras by their friendly name (e.g., 'Back Deck Camera'), use the corresponding camera ID (e.g., 'back_deck_cam') in tool calls."
+ "\n\nWhen users refer to cameras or zones by their friendly name (e.g., 'Back Deck Camera', 'Front Walkway'), use the corresponding ID (e.g., 'back_deck_cam', 'front_walk') in tool calls. Tool results also identify zones by their ID, so when presenting cameras or zones back to the user, translate the ID to its friendly name."
)
speed_units_section = ""
+54
View File
@@ -0,0 +1,54 @@
"""Tests for the REGEXP function registered on the main Frigate database.
Regression coverage for GHSA-q8jx-q884-jcq9: an attacker-controlled
catastrophic (ReDoS) pattern reaching the REGEXP sink must not be able to
stall the serialized database worker thread.
"""
import sqlite3
import time
import unittest
from frigate.db.sqlitevecq import REGEXP_TIMEOUT_SECONDS, SqliteVecQueueDatabase
class TestRegexpFunction(unittest.TestCase):
def setUp(self) -> None:
# autostart=False keeps the queue worker thread from spinning up; we
# only need the REGEXP registration, exercised on our own connection.
self.db = SqliteVecQueueDatabase(":memory:", autostart=False)
self.conn = sqlite3.connect(":memory:")
self.db._register_regexp(self.conn)
def tearDown(self) -> None:
self.conn.close()
def _regexp(self, value: str | None, pattern: str) -> int | None:
# SQLite maps "value REGEXP pattern" to regexp(pattern, value).
return self.conn.execute("SELECT ? REGEXP ?", (value, pattern)).fetchone()[0]
def test_normal_patterns_still_match(self) -> None:
self.assertTrue(self._regexp("ABC123", "^ABC"))
self.assertTrue(self._regexp("ABC123", "ABC.*"))
self.assertTrue(self._regexp("ABC123", "[0-9]+$"))
self.assertFalse(self._regexp("ABC123", "^XYZ"))
def test_null_value_does_not_match(self) -> None:
self.assertFalse(self._regexp(None, ".*"))
def test_invalid_pattern_does_not_raise(self) -> None:
self.assertFalse(self._regexp("ABC123", "(unclosed"))
def test_catastrophic_pattern_is_time_bounded(self) -> None:
# Without the timeout this evaluation backtracks for minutes to hours
# and wedges the whole database thread (GHSA-q8jx-q884-jcq9).
catastrophic = "(a{2,})+c"
subject = "a" * 4000
start = time.monotonic()
result = self._regexp(subject, catastrophic)
elapsed = time.monotonic() - start
# The pattern does not match; the guarantee is that it returns quickly.
self.assertFalse(result)
self.assertLess(elapsed, REGEXP_TIMEOUT_SECONDS + 2.0)
@@ -169,6 +169,13 @@ const detect: SectionConfigOverrides = {
resolution: ["width", "height", "fps"],
tracking: ["min_initialized", "max_disappeared"],
},
uiSchema: {
annotation_offset: {
"ui:options": {
signed: true,
},
},
},
hiddenFields: ["enabled_in_config"],
advancedFields: [
"min_initialized",
@@ -57,6 +57,7 @@ const record: SectionConfigOverrides = {
"ui:options": {
suppressMultiSchema: true,
ffmpegPresetField: "hwaccel_args",
ffmpegGlobalFieldPath: "export.hwaccel_args",
},
},
},
@@ -17,3 +17,4 @@ export {
isSubtreeModified,
} from "./overrides";
export { getSizedFieldClassName } from "./fieldSizing";
export { getNumericInputMode } from "./inputMode";
@@ -0,0 +1,51 @@
import type { RJSFSchema } from "@rjsf/utils";
type NumericInputOptions = {
signed?: boolean;
};
/**
* Derive the on-screen keyboard hint for a schema field.
*
* Numeric config fields render as text inputs because RJSF's NumberField
* relies on the widget echoing raw strings back, so that trailing "." and "0"
* characters survive while a value is being typed. That means the numeric
* keypad has to be requested explicitly. Desktop browsers ignore inputMode, so
* this only affects virtual keyboards.
*
* Fields accepting negative values opt out, since the iOS numeric and decimal
* keypads have no minus key. Most numeric fields declare no minimum even
* though they are non-negative, so signed fields are marked explicitly with
* ui:options.signed.
*
* Args:
* schema: The JSON schema for the field being rendered
* options: The resolved ui:options for the field
*
* Returns:
* The inputMode to apply, or undefined to leave the keyboard alone
*/
export function getNumericInputMode(
schema: RJSFSchema,
options: unknown,
): "numeric" | "decimal" | undefined {
const types = Array.isArray(schema.type) ? schema.type : [schema.type];
const isInteger = types.includes("integer");
if (!isInteger && !types.includes("number")) {
return undefined;
}
const numericOptions =
typeof options === "object" && options !== null
? (options as NumericInputOptions)
: undefined;
const minimum = schema.minimum ?? schema.exclusiveMinimum;
if (numericOptions?.signed || (minimum ?? 0) < 0) {
return undefined;
}
return isInteger ? "numeric" : "decimal";
}
@@ -120,6 +120,12 @@ export function FfmpegArgsWidget(props: WidgetProps) {
id,
} = props;
const presetField = options?.ffmpegPresetField as PresetField | undefined;
// Path to this field within its config section. This is usually the same as
// the preset field, but the two diverge when the field sits below the
// section root: record.export.hwaccel_args uses the hwaccel_args preset list
// while living at export.hwaccel_args inside the record section.
const globalFieldPath =
(options?.ffmpegGlobalFieldPath as string | undefined) ?? presetField;
const allowInherit = options?.allowInherit === true;
const hideDescription = options?.hideDescription === true;
const useSplitLayout = options?.splitLayout !== false;
@@ -131,11 +137,18 @@ export function FfmpegArgsWidget(props: WidgetProps) {
// Extract the global value for this specific field to detect inheritance
const globalFieldValue = useMemo(() => {
if (!showUseGlobalSetting || !formContext?.globalValue || !presetField) {
if (
!showUseGlobalSetting ||
!formContext?.globalValue ||
!globalFieldPath
) {
return undefined;
}
return get(formContext.globalValue as Record<string, unknown>, presetField);
}, [showUseGlobalSetting, formContext?.globalValue, presetField]);
return get(
formContext.globalValue as Record<string, unknown>,
globalFieldPath,
);
}, [showUseGlobalSetting, formContext?.globalValue, globalFieldPath]);
const { data } = useSWR<FfmpegPresetResponse>("ffmpeg/presets");
@@ -2,7 +2,7 @@
import type { WidgetProps } from "@rjsf/utils";
import { Input } from "@/components/ui/input";
import { cn } from "@/lib/utils";
import { getSizedFieldClassName } from "../utils";
import { getNumericInputMode, getSizedFieldClassName } from "../utils";
export function TextWidget(props: WidgetProps) {
const {
@@ -28,6 +28,7 @@ export function TextWidget(props: WidgetProps) {
id={id}
className={cn(fieldClassName)}
type="text"
inputMode={getNumericInputMode(schema, options)}
value={value ?? ""}
disabled={disabled || readonly}
placeholder={placeholder || (options.placeholder as string) || ""}
@@ -127,8 +127,12 @@ export default function ObjectTrackOverlay({
},
);
const getZonesFriendlyNames = (zones: string[], config: FrigateConfig) => {
return zones?.map((zone) => resolveZoneName(config, zone)) ?? [];
const getZonesFriendlyNames = (
zones: string[],
config: FrigateConfig,
cameraId?: string,
) => {
return zones?.map((zone) => resolveZoneName(config, zone, cameraId)) ?? [];
};
const timelineResults = useMemo(() => {
@@ -151,7 +155,7 @@ export default function ObjectTrackOverlay({
data: {
...event.data,
zones_friendly_names: config
? getZonesFriendlyNames(event.data?.zones, config)
? getZonesFriendlyNames(event.data?.zones, config, event.camera)
: [],
},
}));
@@ -61,7 +61,11 @@ export function ObjectPath({
...pos.lifecycle_item?.data,
zones_friendly_names: pos.lifecycle_item?.data.zones.map(
(zone) => {
return resolveZoneName(config, zone);
return resolveZoneName(
config,
zone,
pos.lifecycle_item?.camera,
);
},
),
},
@@ -301,11 +301,19 @@ export function TrackingDetails({
[recordings, actualVideoStart],
);
eventSequence?.map((event) => {
event.data.zones_friendly_names = event.data?.zones?.map((zone) => {
return resolveZoneName(config, zone);
});
});
const sequence = useMemo(
() =>
eventSequence?.map((item) => ({
...item,
data: {
...item.data,
zones_friendly_names: item.data?.zones?.map((zone) =>
resolveZoneName(config, zone, item.camera),
),
},
})),
[eventSequence, config],
);
// Use manualOverride (set when seeking in image mode) if present so
// lifecycle rows and overlays follow image-mode seeks. Otherwise fall
@@ -849,9 +857,9 @@ export function TrackingDetails({
</div>
<div className="mt-2">
{!eventSequence ? (
{!sequence ? (
<ActivityIndicator className="size-2" size={2} />
) : eventSequence.length === 0 ? (
) : sequence.length === 0 ? (
<div className="py-2 text-muted-foreground">
{t("detail.noObjectDetailData", { ns: "views/events" })}
</div>
@@ -871,7 +879,7 @@ export function TrackingDetails({
/>
)}
<div className="space-y-2">
{eventSequence.map((item, idx) => {
{sequence.map((item, idx) => {
return (
<div
key={`${item.timestamp}-${item.source_id ?? ""}-${idx}`}
+1 -1
View File
@@ -1032,7 +1032,7 @@ function ObjectTimeline({
data: {
...event.data,
zones_friendly_names: event.data?.zones?.map((zone) =>
resolveZoneName(config, zone),
resolveZoneName(config, zone, event.camera),
),
},
}));