Docs tweaks (#23787)

* docs fixes * backend tweaks * regenerate i18n * tweak genai * add config overrides section * add common errors * add suggestions for rebuilding a corrupt database
2026-09-28 05:08:58 +03:00 · 2026-07-22 11:13:58 -05:00
parent c0cf08ab4a
commit 168cbea9ea
17 changed files with 593 additions and 74 deletions
@@ -11,6 +11,8 @@ It is not recommended to copy this full configuration file. Only specify values

 :::

+Sections marked `# NOTE: Can be overridden at the camera level` can be set globally and then adjusted per camera. See [Global and Camera-Level Configuration](../config_overrides.md) for how that works.
+
 ```yaml
 mqtt:
  # Optional: Enable mqtt server (default: shown below)
@@ -171,13 +173,14 @@ model:
  # Valid values are rgb, bgr, or yuv. (default: shown below)
  input_pixel_format: rgb
  # Required: Object detection model input tensor format
-  # Valid values are nhwc or nchw (default: shown below)
+  # Valid values are nhwc, nchw, hwnc, or hwcn (default: shown below)
  input_tensor: nhwc
  # Optional: Data type of the model input tensor
  # Valid values are float, float_denorm, or int (default: shown below)
  input_dtype: int
-  # Required: Object detection model type, currently only used with the OpenVINO detector
-  # Valid values are ssd, yolox, yolonas (default: shown below)
+  # Required: Object detection model architecture, used by detectors that support more
+  # than one model type (openvino, onnx, rknn, memryx, axengine, synaptics, and others)
+  # Valid values are ssd, yolox, yolonas, yolo-generic, rfdetr, dfine (default: shown below)
  model_type: ssd
  # Required: Label name modifications. These are merged into the standard labelmap.
  labelmap:
@@ -468,8 +471,8 @@ review:
    detections: False
    # Optional: Activity Context Prompt to give context to the GenAI what activity is and is not suspicious.
    # It is important to be direct and detailed. See documentation for the default prompt structure.
-    activity_context_prompt: """Define what is and is not suspicious
-"""
+    activity_context_prompt: |
+      Define what is and is not suspicious
    # Optional: Image source for GenAI (default: preview)
    # Options: "preview" (uses cached preview frames at ~180p) or "recordings" (extracts frames from recordings at 480p)
    # Using "recordings" provides better image quality but uses more tokens per image.
@@ -813,7 +816,8 @@ classification:
        cameras:
          camera_name:
            # Required: Crop of image frame on this camera to run classification on
-            crop: [0, 180, 220, 400]
+            # [x1, y1, x2, y2] as decimals between 0 and 1, relative to the detect resolution
+            crop: [0.0, 0.25, 0.3, 0.85]
        # Optional: If classification should be run when motion is detected in the crop (default: shown below)
        motion: False
        # Optional: Interval to run classification on in seconds (default: shown below)
@@ -335,7 +335,7 @@ For example:
 ```
 services:
  frigate:
-    image: blakeblackshear/frigate:latest
+    image: ghcr.io/blakeblackshear/frigate:stable
    environment:
      - FRIGATE_BASE_PATH=/frigate
 ```
@@ -20,7 +20,7 @@ Settings are organized into two scopes:
 - **Global configuration**: values under <NavPath path="Settings > Global configuration" /> apply to every camera by default. This is where you set the baseline behavior for object detection, recording, snapshots, motion, and so on.
 - **Camera configuration**: values under <NavPath path="Settings > Camera configuration" /> apply to a single camera. Use the camera selector button at the top of these pages to choose which camera you are editing.

-When a camera-level section is left untouched, the camera simply inherits the global values. Changing a value on a camera page **overrides** the global value for that camera only: the global setting and every other camera are unaffected. This mirrors how the YAML works, where a value set under `cameras.<name>` takes precedence over the same value set at the top level.
+When a camera-level section is left untouched, the camera simply inherits the global values. Changing a value on a camera page **overrides** the global value for that camera only: the global setting and every other camera are unaffected. This mirrors how the YAML works, where a value set under `cameras.<name>` takes precedence over the same value set at the top level. See [Global and Camera-Level Configuration](./config_overrides.md) for the full details, including how lists and maps are handled and which settings must be enabled globally first.

 To undo an override and go back to inheriting from the parent scope, use the reset button at the bottom of the section:

@@ -130,7 +130,8 @@ go2rtc:

 ```yaml
 genai:
-  api_key: "{FRIGATE_GENAI_API_KEY}"
+  my_provider:
+    api_key: "{FRIGATE_GENAI_API_KEY}"
 ```

 ## Common configuration examples
@@ -0,0 +1,244 @@
+---
+id: config_overrides
+title: Global and Camera-Level Configuration
+---
+
+import ConfigTabs from "@site/src/components/ConfigTabs";
+import TabItem from "@theme/TabItem";
+import NavPath from "@site/src/components/NavPath";
+
+Most of Frigate's configuration can be set once for all cameras and then adjusted for individual cameras. The global value acts as the default for every camera, and any camera can override it.
+
+This page explains how that inheritance works. For a tour of the Settings UI itself, see [Frigate Configuration](./config.md).
+
+## The basics
+
+Set a value globally and every camera uses it. Set the same value on a camera and that camera uses its own value instead.
+
+<ConfigTabs>
+<TabItem value="ui">
+
+1. Navigate to <NavPath path="Settings > Global configuration > Object detection" /> and set **Detect FPS** to `5`. Every camera now detects at 5 fps.
+2. Navigate to <NavPath path="Settings > Camera configuration > Object detection" />, select the `driveway` camera, and set **Detect FPS** to `10`.
+
+The `driveway` camera now detects at 10 fps. Every other camera still uses the global value of 5.
+
+</TabItem>
+<TabItem value="yaml">
+
+```yaml
+detect:
+  fps: 5 # every camera detects at 5 fps
+
+cameras:
+  front_door:
+    ffmpeg: ...
+  driveway:
+    ffmpeg: ...
+    detect:
+      fps: 10 # except this one
+```
+
+`front_door` inherits `fps: 5`, and `driveway` uses `10`.
+
+</TabItem>
+</ConfigTabs>
+
+## Overrides apply per value, not per section
+
+Overriding one value in a section does not detach the rest of that section. Everything you don't set on the camera still comes from the global configuration.
+
+<ConfigTabs>
+<TabItem value="ui">
+
+If you set a camera's **Motion threshold** but leave **Contour area** alone, only the threshold is overridden. The contour area continues to follow <NavPath path="Settings > Global configuration > Motion detection" />, and changing it there still affects that camera.
+
+Open a section to see which values are overridden: the section header indicates how many fields differ from the global configuration.
+
+</TabItem>
+<TabItem value="yaml">
+
+```yaml
+motion:
+  threshold: 30
+  contour_area: 10
+
+cameras:
+  driveway:
+    motion:
+      threshold: 40
+```
+
+The `driveway` camera ends up with `threshold: 40` and `contour_area: 10`. Only the value you wrote was overridden.
+
+</TabItem>
+</ConfigTabs>
+
+## Returning a camera to the global value
+
+<ConfigTabs>
+<TabItem value="ui">
+
+A camera section that has its own values shows an **Overridden** badge. To remove the override and go back to inheriting, use the **Reset to Global** button at the bottom of the section.
+
+</TabItem>
+<TabItem value="yaml">
+
+Frigate treats a camera value as an override because it is written in the config file, not because it differs from the global value. Repeating the global value under a camera still creates an override:
+
+```yaml
+snapshots:
+  enabled: true
+
+cameras:
+  driveway:
+    snapshots:
+      enabled: true # this is an override, even though it matches
+```
+
+If you later change the global `snapshots.enabled` to `false`, `driveway` keeps saving snapshots, because it has its own value. To make a camera follow the global value again, delete the key from the camera rather than setting it to match.
+
+</TabItem>
+</ConfigTabs>
+
+## Lists replace, maps merge
+
+This is the distinction that surprises people most.
+
+**Lists are replaced entirely.** A camera's list does not add to the global list, it takes its place.
+
+<ConfigTabs>
+<TabItem value="ui">
+
+The camera page shows the objects the camera is currently tracking, starting from the global list. Changing that selection under <NavPath path="Settings > Camera configuration > Objects" /> replaces the list for that camera, so make sure every object you want tracked is selected, not just the ones you are adding.
+
+</TabItem>
+<TabItem value="yaml">
+
+```yaml
+objects:
+  track:
+    - person
+    - car
+
+cameras:
+  backyard:
+    objects:
+      track:
+        - dog # backyard tracks ONLY dog, not person or car
+```
+
+To track `dog` in addition to the global objects, list all of them on the camera.
+
+</TabItem>
+</ConfigTabs>
+
+An empty list is a valid override, and is the normal way to opt a camera out of something:
+
+```yaml
+review:
+  alerts:
+    labels:
+      - person
+
+cameras:
+  street:
+    review:
+      alerts:
+        labels: [] # this camera never creates alerts
+```
+
+**Maps are merged key by key.** A camera can add an entry without redeclaring the others.
+
+<ConfigTabs>
+<TabItem value="ui">
+
+Adding a filter for one object under <NavPath path="Settings > Camera configuration > Objects" /> does not remove the filters inherited from <NavPath path="Settings > Global configuration > Objects" />. The camera keeps both.
+
+</TabItem>
+<TabItem value="yaml">
+
+```yaml
+objects:
+  filters:
+    person:
+      min_area: 5000
+
+cameras:
+  driveway:
+    objects:
+      filters:
+        car:
+          min_area: 10000
+```
+
+The `driveway` camera ends up with both the `car` filter it defined and the `person` filter from the global configuration.
+
+</TabItem>
+</ConfigTabs>
+
+## Which settings can be overridden
+
+Most, but not all. The [full reference config](./advanced/reference.md) is the authoritative source: sections that support camera-level overrides are marked with the comment `# NOTE: Can be overridden at the camera level`. In the UI, a setting can be overridden if it appears under both <NavPath path="Settings > Global configuration" /> and <NavPath path="Settings > Camera configuration" />.
+
+A few things worth knowing beyond that:
+
+- Some sections are **global only** and have no camera-level equivalent, including `go2rtc`, `genai` providers, `classification`, `telemetry`, `camera_groups`, and `ui`.
+- Some sections exist **only at the camera level**, such as `zones` and `onvif`.
+- Some sections are **partially overridable**, meaning a camera accepts only a few of the keys available globally. `face_recognition`, `lpr`, and `audio_transcription` work this way, and the reference config notes which keys apply.
+
+## Enrichments that must be enabled globally first
+
+License plate recognition and face recognition are special: the global setting is not just a default, it is a switch that must be on before any camera can use the feature. Enabling one on a camera while it is disabled globally is a configuration error, and Frigate will refuse to start:
+
+```
+Camera driveway has lpr enabled but lpr is disabled at the global level of the config. You must enable lpr at the global level.
+```
+
+Enable the feature globally, then turn it off on the cameras that don't need it.
+
+<ConfigTabs>
+<TabItem value="ui">
+
+1. Navigate to <NavPath path="Settings > Global configuration > License plate recognition" /> and enable **LPR**.
+2. Navigate to <NavPath path="Settings > Camera configuration > License plate recognition" />, select each camera that should not run LPR, and disable the **Enable LPR** toggle.
+
+</TabItem>
+<TabItem value="yaml">
+
+```yaml
+lpr:
+  enabled: true
+
+cameras:
+  driveway:
+    ffmpeg: ... # inherits lpr, enabled
+  backyard:
+    ffmpeg: ...
+    lpr:
+      enabled: false # opted out
+```
+
+</TabItem>
+</ConfigTabs>
+
+:::note
+
+This applies only to `lpr` and `face_recognition`, because the global setting controls whether the supporting background process starts at all. Other features do not work this way. Audio transcription, for example, can be enabled on a single camera without being enabled globally.
+
+:::
+
+## Profiles
+
+[Profiles](./profiles.md) add a further layer on top of everything described above. A profile is a named set of camera overrides that you can switch on and off while Frigate is running, for example to change detection and recording behavior when you leave the house.
+
+Profiles are applied on top of a camera's already-resolved configuration, so a profile value wins over both the camera and the global value while that profile is active. Profiles cover a subset of the camera sections and do not modify your config file.
+
+## Summary
+
+- A camera inherits every value you don't set on it.
+- Overriding one value does not detach the rest of the section.
+- Writing a value on a camera overrides it, even if it matches the global value. Remove it to inherit again.
+- Lists replace the global list. Maps merge into it.
+- An empty list is an override, not an omission.
+- `lpr` and `face_recognition` must be enabled globally before a camera can use them.
@@ -73,9 +73,13 @@ classification:
        interval: 10 # also run every N seconds (optional)
        cameras:
          front:
-            crop: [0, 180, 220, 400]
+            # [x1, y1, x2, y2] as decimals between 0 and 1, relative to the
+            # camera's detect resolution
+            crop: [0.0, 0.25, 0.3, 0.85]
 ```

+Crop coordinates are normalized: each value is a fraction of the camera's `detect` width or height, not a pixel value. Drawing the crop in the UI wizard writes these values for you.
+
 An optional config, `save_attempts`, can be set as a key under the model name. This defines the number of classification attempts to save in the Recent Classifications tab. For state classification models, the default is 100.

 </TabItem>
@@ -9,9 +9,27 @@ import NavPath from "@site/src/components/NavPath";

 ## Configuration

-A Generative AI provider can be configured in the global config, which will make the Generative AI features available for use. There are currently 4 native providers available to integrate with Frigate. Other providers that support the OpenAI standard API can also be used. See the OpenAI-Compatible section below.
+A Generative AI provider can be configured in the global config, which will make the Generative AI features available for use. There are currently 5 native providers available to integrate with Frigate. Other providers that support the OpenAI standard API can also be used. See the OpenAI-Compatible section below.

-To use Generative AI, you must define a single provider at the global level of your Frigate configuration. If the provider you choose requires an API key, you may either directly paste it in your configuration, or store it in an environment variable prefixed with `FRIGATE_`.
+`genai` is a map of named providers. Each key under `genai` is a name you choose, and its value is that provider's settings:
+
+```yaml
+genai:
+  my_provider: # any name you like
+    provider: ollama
+    base_url: http://localhost:11434
+    model: qwen3-vl:4b
+    roles:
+      - descriptions
+      - embeddings
+      - chat
+```
+
+The examples on this page all use `my_provider`, but the name is arbitrary and is only used to reference the provider elsewhere in the config (for example, `semantic_search.model`).
+
+Each provider handles one or more **roles**: `chat`, `descriptions`, and `embeddings`. A provider handles all three by default, and each role may be assigned to exactly one provider. Define a single provider if you want it to do everything, or split the roles across several providers using the `roles` option.
+
+If the provider you choose requires an API key, you may either directly paste it in your configuration, or store it in an environment variable prefixed with `FRIGATE_`.

 ## Local Providers

@@ -85,11 +103,12 @@ All llama.cpp native options can be passed through `provider_options`, including

 ```yaml
 genai:
-  provider: llamacpp
-  base_url: http://localhost:8080
-  model: your-model-name
-  provider_options:
-    context_size: 16000 # Optional, overrides the context size reported by the server.
+  my_provider:
+    provider: llamacpp
+    base_url: http://localhost:8080
+    model: your-model-name
+    provider_options:
+      context_size: 16000 # Optional, overrides the context size reported by the server.
 ```

 </TabItem>
@@ -129,13 +148,14 @@ Note that Frigate will not automatically download the model you specify in your

 ```yaml
 genai:
-  provider: ollama
-  base_url: http://localhost:11434
-  model: qwen3-vl:4b
-  provider_options: # other Ollama client options can be defined
-    keep_alive: -1
-    options:
-      num_ctx: 8192 # make sure the context matches other services that are using ollama
+  my_provider:
+    provider: ollama
+    base_url: http://localhost:11434
+    model: qwen3-vl:4b
+    provider_options: # other Ollama client options can be defined
+      keep_alive: -1
+      options:
+        num_ctx: 8192 # make sure the context matches other services that are using ollama
 ```

 </TabItem>
@@ -151,11 +171,12 @@ For OpenAI-compatible servers (such as llama.cpp) that don't expose the configur

 ```yaml
 genai:
-  provider: openai
-  base_url: http://your-llama-server
-  model: your-model-name
-  provider_options:
-    context_size: 8192 # Specify the configured context size
+  my_provider:
+    provider: openai
+    base_url: http://your-llama-server
+    model: your-model-name
+    provider_options:
+      context_size: 8192 # Specify the configured context size
 ```

 This ensures Frigate uses the correct context window size when generating prompts.
@@ -178,10 +199,11 @@ This ensures Frigate uses the correct context window size when generating prompt

 ```yaml
 genai:
-  provider: openai
-  base_url: http://your-server:port
-  api_key: your-api-key # May not be required for local servers
-  model: your-model-name
+  my_provider:
+    provider: openai
+    base_url: http://your-server:port
+    api_key: your-api-key # May not be required for local servers
+    model: your-model-name
 ```

 </TabItem>
@@ -219,19 +241,21 @@ Ollama also supports [cloud models](https://ollama.com/cloud), where model infer

 ```yaml
 genai:
-  provider: ollama
-  base_url: http://localhost:11434
-  model: cloud-model-name
+  my_provider:
+    provider: ollama
+    base_url: http://localhost:11434
+    model: cloud-model-name
 ```

 or when using Ollama Cloud directly

 ```yaml
 genai:
-  provider: ollama
-  base_url: https://ollama.com
-  model: cloud-model-name
-  api_key: your-api-key
+  my_provider:
+    provider: ollama
+    base_url: https://ollama.com
+    model: cloud-model-name
+    api_key: your-api-key
 ```

 </TabItem>
@@ -269,9 +293,10 @@ To start using Gemini, you must first get an API key from [Google AI Studio](htt

 ```yaml
 genai:
-  provider: gemini
-  api_key: "{FRIGATE_GEMINI_API_KEY}"
-  model: gemini-2.5-flash
+  my_provider:
+    provider: gemini
+    api_key: "{FRIGATE_GEMINI_API_KEY}"
+    model: gemini-2.5-flash
 ```

 </TabItem>
@@ -281,12 +306,13 @@ genai:

 To use a different Gemini-compatible API endpoint, set the `provider_options` with the `base_url` key to your provider's API URL. For example:

-```yaml {4,5}
+```yaml {5,6}
 genai:
-  provider: gemini
-  ...
-  provider_options:
-    base_url: https://...
+  my_provider:
+    provider: gemini
+    ...
+    provider_options:
+      base_url: https://...
 ```

 Other HTTP options are available, see the [python-genai documentation](https://github.com/googleapis/python-genai).
@@ -320,9 +346,10 @@ To start using OpenAI, you must first [create an API key](https://platform.opena

 ```yaml
 genai:
-  provider: openai
-  api_key: "{FRIGATE_OPENAI_API_KEY}"
-  model: gpt-4o
+  my_provider:
+    provider: openai
+    api_key: "{FRIGATE_OPENAI_API_KEY}"
+    model: gpt-4o
 ```

 </TabItem>
@@ -338,13 +365,14 @@ To use a different OpenAI-compatible API endpoint, set the `OPENAI_BASE_URL` env

 For OpenAI-compatible servers (such as llama.cpp) that don't expose the configured context size in the API response, you can manually specify the context size in `provider_options`:

-```yaml {5,6}
+```yaml {6,7}
 genai:
-  provider: openai
-  base_url: http://your-llama-server
-  model: your-model-name
-  provider_options:
-    context_size: 8192 # Specify the configured context size
+  my_provider:
+    provider: openai
+    base_url: http://your-llama-server
+    model: your-model-name
+    provider_options:
+      context_size: 8192 # Specify the configured context size
 ```

 This ensures Frigate uses the correct context window size when generating prompts.
@@ -379,10 +407,11 @@ To start using Azure OpenAI, you must first [create a resource](https://learn.mi

 ```yaml
 genai:
-  provider: azure_openai
-  base_url: https://instance.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview
-  model: gpt-5-mini
-  api_key: "{FRIGATE_OPENAI_API_KEY}"
+  my_provider:
+    provider: azure_openai
+    base_url: https://instance.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview
+    model: gpt-5-mini
+    api_key: "{FRIGATE_OPENAI_API_KEY}"
 ```

 </TabItem>
@@ -52,9 +52,10 @@ You can define custom prompts at the global level and per-object type. To config

 ```yaml
 genai:
-  provider: ollama
-  base_url: http://localhost:11434
-  model: qwen3-vl:8b-instruct
+  my_provider:
+    provider: ollama
+    base_url: http://localhost:11434
+    model: qwen3-vl:8b-instruct

 objects:
  genai:
@@ -196,7 +196,7 @@ services:

 :::

-See [go2rtc WebRTC docs](https://github.com/AlexxIT/go2rtc/tree/v1.8.3#module-webrtc) for more information about this.
+See [go2rtc WebRTC docs](https://github.com/AlexxIT/go2rtc/tree/v1.9.14#module-webrtc) for more information about this.

 ### Two way talk

@@ -163,8 +163,8 @@ genai:
    model: your-model-name
    roles:
      - embeddings
-      - vision
-      - tools
+      - descriptions
+      - chat

 semantic_search:
  enabled: True