From af0696771a4f0cc6f05566240632d98c1979aaf9 Mon Sep 17 00:00:00 2001 From: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com> Date: Thu, 12 Mar 2026 09:13:20 -0500 Subject: [PATCH] docs --- docs/docs/configuration/profiles.md | 179 +++++++++++++++++++++++++++ docs/docs/configuration/reference.md | 53 ++++++++ docs/docs/integrations/mqtt.md | 19 +++ docs/sidebars.ts | 1 + 4 files changed, 252 insertions(+) create mode 100644 docs/docs/configuration/profiles.md diff --git a/docs/docs/configuration/profiles.md b/docs/docs/configuration/profiles.md new file mode 100644 index 000000000..cbbf37442 --- /dev/null +++ b/docs/docs/configuration/profiles.md @@ -0,0 +1,179 @@ +--- +id: profiles +title: Profiles +--- + +Profiles allow you to define named sets of camera configuration overrides that can be activated and deactivated at runtime without restarting Frigate. This is useful for scenarios like switching between "Home" and "Away" modes, daytime and nighttime configurations, or any situation where you want to quickly change how multiple cameras behave. + +## How Profiles Work + +Profiles operate as a two-level system: + +1. **Profile definitions** are declared at the top level of your config under `profiles`. Each definition has a machine name (the key) and a `friendly_name` for display in the UI. +2. **Camera profile overrides** are declared under each camera's `profiles` section, keyed by the profile name. Only the settings you want to change need to be specified — everything else is inherited from the camera's base configuration. + +When a profile is activated, Frigate merges each camera's profile overrides on top of its base config. When the profile is deactivated, all cameras revert to their original settings. Only one profile can be active at a time. + +:::info + +Profile changes are applied in-memory and take effect immediately — no restart is required. The active profile is persisted across Frigate restarts (stored in the `/config/.active_profile` file). + +::: + +## Configuration + +The easiest way to define profiles is to use the Frigate UI. Profiles can also be configured manually in your configuration file. + +### Defining Profiles + +First, define your profiles at the top level of your Frigate config. Every profile name referenced by a camera must be defined here. + +```yaml +profiles: + home: + friendly_name: Home + away: + friendly_name: Away + night: + friendly_name: Night Mode +``` + +### Camera Profile Overrides + +Under each camera, add a `profiles` section with overrides for each profile. You only need to include the settings you want to change. + +```yaml +cameras: + front_door: + ffmpeg: + inputs: + - path: rtsp://camera:554/stream + roles: + - detect + - record + detect: + enabled: true + record: + enabled: true + profiles: + away: + detect: + enabled: true + notifications: + enabled: true + objects: + track: + - person + - car + - package + review: + alerts: + labels: + - person + - car + - package + home: + detect: + enabled: true + notifications: + enabled: false + objects: + track: + - person +``` + +### Supported Override Sections + +The following camera configuration sections can be overridden in a profile: + +| Section | Description | +| ------------------ | ----------------------------------------- | +| `enabled` | Enable or disable the camera entirely | +| `audio` | Audio detection settings | +| `birdseye` | Birdseye view settings | +| `detect` | Object detection settings | +| `face_recognition` | Face recognition settings | +| `lpr` | License plate recognition settings | +| `motion` | Motion detection settings | +| `notifications` | Notification settings | +| `objects` | Object tracking and filter settings | +| `record` | Recording settings | +| `review` | Review alert and detection settings | +| `snapshots` | Snapshot settings | +| `zones` | Zone definitions (merged with base zones) | + +:::note + +Only the fields you explicitly set in a profile override are applied. All other fields retain their base configuration values. For zones, profile zones are merged with the camera's base zones — any zone defined in the profile will override or add to the base zones. + +::: + +## Activating Profiles + +Profiles can be activated and deactivated from the Frigate UI. Open the Settings cog and select **Profiles** from the submenu to see all defined profiles. From there you can activate any profile or deactivate the current one. The active profile is indicated in the UI so you always know which profile is in effect. + +## Example: Home / Away Setup + +A common use case is having different detection and notification settings based on whether you are home or away. + +```yaml +profiles: + home: + friendly_name: Home + away: + friendly_name: Away + +cameras: + front_door: + ffmpeg: + inputs: + - path: rtsp://camera:554/stream + roles: + - detect + - record + detect: + enabled: true + record: + enabled: true + notifications: + enabled: false + profiles: + away: + notifications: + enabled: true + review: + alerts: + labels: + - person + - car + home: + notifications: + enabled: false + + indoor_cam: + ffmpeg: + inputs: + - path: rtsp://camera:554/indoor + roles: + - detect + - record + detect: + enabled: false + record: + enabled: false + profiles: + away: + enabled: true + detect: + enabled: true + record: + enabled: true + home: + enabled: false +``` + +In this example: + +- **Away profile**: The front door camera enables notifications and tracks specific alert labels. The indoor camera is fully enabled with detection and recording. +- **Home profile**: The front door camera disables notifications. The indoor camera is completely disabled for privacy. +- **No profile active**: All cameras use their base configuration values. diff --git a/docs/docs/configuration/reference.md b/docs/docs/configuration/reference.md index cac508195..1b6f8758a 100644 --- a/docs/docs/configuration/reference.md +++ b/docs/docs/configuration/reference.md @@ -1026,6 +1026,49 @@ cameras: actions: - notification + # Optional: Named config profiles with partial overrides that can be activated at runtime. + # NOTE: Profile names must be defined in the top-level 'profiles' section. + profiles: + # Required: name of the profile (must match a top-level profile definition) + away: + # Optional: Enable or disable the camera when this profile is active (default: not set, inherits base) + enabled: true + # Optional: Override audio settings + audio: + enabled: true + # Optional: Override birdseye settings + # birdseye: + # Optional: Override detect settings + detect: + enabled: true + # Optional: Override face_recognition settings + # face_recognition: + # Optional: Override lpr settings + # lpr: + # Optional: Override motion settings + # motion: + # Optional: Override notification settings + notifications: + enabled: true + # Optional: Override objects settings + objects: + track: + - person + - car + # Optional: Override record settings + record: + enabled: true + # Optional: Override review settings + review: + alerts: + labels: + - person + - car + # Optional: Override snapshot settings + # snapshots: + # Optional: Override or add zones (merged with base zones) + # zones: + # Optional ui: # Optional: Set a timezone to use in the UI (default: use browser local time) @@ -1092,4 +1135,14 @@ camera_groups: icon: LuCar # Required: index of this group order: 0 + +# Optional: Profile definitions for named config overrides +# NOTE: Profile names defined here can be referenced in camera profiles sections +profiles: + # Required: name of the profile (machine name used internally) + home: + # Required: display name shown in the UI + friendly_name: Home + away: + friendly_name: Away ``` diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index 0ef6774a8..101e95410 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -275,6 +275,25 @@ Same data available at `/api/stats` published at a configurable interval. Returns data about each camera, its current features, and if it is detecting motion, objects, etc. Can be triggered by publising to `frigate/onConnect` +### `frigate/profile/set` + +Topic to activate or deactivate a [profile](/configuration/profiles). Publish a profile name to activate it, or `none` to deactivate the current profile. + +### `frigate/profile/state` + +Topic with the currently active profile name. Published value is the profile name or `none` if no profile is active. This topic is retained. + +### `frigate/profiles/available` + +Topic with a JSON array of all available profile definitions. Published on startup as a retained message. + +```json +[ + { "name": "away", "friendly_name": "Away" }, + { "name": "home", "friendly_name": "Home" } +] +``` + ### `frigate/notifications/set` Topic to turn notifications on and off. Expected values are `ON` and `OFF`. diff --git a/docs/sidebars.ts b/docs/sidebars.ts index a4c1bca9d..2d1085af1 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -94,6 +94,7 @@ const sidebars: SidebarsConfig = { "Extra Configuration": [ "configuration/authentication", "configuration/notifications", + "configuration/profiles", "configuration/ffmpeg_presets", "configuration/pwa", "configuration/tls",