zishuo/frigate
1
0
Fork 0
mirror of https://github.com/blakeblackshear/frigate.git synced 2026-04-22 23:17:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

Camera profile support (#22482)

Browse Source 
* add CameraProfileConfig model for named config overrides

* add profiles field to CameraConfig

* add active_profile field to FrigateConfig

Runtime-only field excluded from YAML serialization, tracks which
profile is currently active.

* add ProfileManager for profile activation and persistence

Handles snapshotting base configs, applying profile overrides via
deep_merge + apply_section_update, publishing ZMQ updates, and
persisting active profile to /config/.active_profile.

* add profile API endpoints (GET /profiles, GET/PUT /profile)

* add MQTT and dispatcher integration for profiles

- Subscribe to frigate/profile/set MQTT topic
- Publish profile/state and profiles/available on connect
- Add _on_profile_command handler to dispatcher
- Broadcast active profile state on WebSocket connect

* wire ProfileManager into app startup and FastAPI

- Create ProfileManager after dispatcher init
- Restore persisted profile on startup
- Pass dispatcher and profile_manager to FastAPI app

* add tests for invalid profile values and keys

Tests that Pydantic rejects: invalid field values (fps: "not_a_number"),
unknown section keys (ffmpeg in profile), invalid nested values, and
invalid profiles in full config parsing.

* formatting

* fix CameraLiveConfig JSON serialization error on profile activation

refactor _publish_updates to only publish ZMQ updates for
sections that actually changed, not all sections on affected cameras.

* consolidate

* add enabled field to camera profiles for enabling/disabling cameras

* add zones support to camera profiles

* add frontend profile types, color utility, and config save support

* add profile state management and save preview support

* add profileName prop to BaseSection for profile-aware config editing

* add profile section dropdown and wire into camera settings pages

* add per-profile camera enable/disable to Camera Management view

* add profiles summary page with card-based layout and fix backend zone comparison bug

* add active profile badge to settings toolbar

* i18n

* add red dot for any pending changes including profiles

* profile support for mask and zone editor

* fix hidden field validation errors caused by lodash wildcard and schema gaps

lodash unset does not support wildcard (*) segments, so hidden fields like
filters.*.mask were never stripped from form data, leaving null raw_coordinates
that fail RJSF anyOf validation. Add unsetWithWildcard helper and also strip
hidden fields from the JSON schema itself as defense-in-depth.

* add face_recognition and lpr to profile-eligible sections

* move profile dropdown from section panes to settings header

* add profiles enable toggle and improve empty state

* formatting

* tweaks

* tweak colors and switch

* fix profile save diff, masksAndZones delete, and config sync

* ui tweaks

* ensure profile manager gets updated config

* rename profile settings to ui settings

* refactor profilesview and add dots/border colors when overridden

* implement an update_config method for profile manager

* fix mask deletion

* more unique colors

* add top-level profiles config section with friendly names

* implement profile friendly names and improve profile UI

- Add ProfileDefinitionConfig type and profiles field to FrigateConfig
- Use ProfilesApiResponse type with friendly_name support throughout
- Replace Record<string, unknown> with proper JsonObject/JsonValue types
- Add profile creation form matching zone pattern (Zod + NameAndIdFields)
- Add pencil icon for renaming profile friendly names in ProfilesView
- Move Profiles menu item to first under Camera Configuration
- Add activity indicators on save/rename/delete buttons
- Display friendly names in CameraManagementView profile selector
- Fix duplicate colored dots in management profile dropdown
- Fix i18n namespace for overridden base config tooltips
- Move profile override deletion from dropdown trash icon to footer
  button with confirmation dialog, matching Reset to Global pattern
- Remove Add Profile from section header dropdown to prevent saving
  camera overrides before top-level profile definition exists
- Clean up newProfiles state after API profile deletion
- Refresh profiles SWR cache after saving profile definitions

* remove profile badge in settings and add profiles to main menu

* use icon only on mobile

* change color order

* docs

* show activity indicator on trash icon while deleting a profile

* tweak language

* immediately create profiles on backend instead of deferring to Save All

* hide restart-required fields when editing a profile section

fields that require a restart cannot take effect via profile switching,
so they are merged into hiddenFields when profileName is set

* show active profile indicator in desktop status bar

* fix profile config inheritance bug where Pydantic defaults override base values

The /config API was dumping profile overrides with model_dump() which included
all Pydantic defaults. When the frontend merged these over
the camera's base config, explicitly-set base values were
lost. Now profile overrides are re-dumped with exclude_unset=True so only
user-specified fields are returned.

Also fixes the Save All path generating spurious deletion markers for
restart-required fields that are hidden during profile
editing but not excluded from the raw data sanitization in
prepareSectionSavePayload.

* docs tweaks

* docs tweak

* formatting

* formatting

* fix typing

* fix test pollution

test_maintainer was injecting MagicMock() into sys.modules["frigate.config.camera.updater"] at module load time and never restoring it. When the profile tests later imported CameraConfigUpdateEnum and CameraConfigUpdateTopic from that module, they got mock objects instead of the real dataclass/enum, so equality comparisons always failed

* remove

* fix settings showing profile-merged values when editing base config

When a profile is active, the in-memory config contains effective
(profile-merged) values. The settings UI was displaying these merged
values even when the "Base Config" view was selected.

Backend: snapshot pre-profile base configs in ProfileManager and expose
them via a `base_config` key in the /api/config camera response when a
profile is active. The top-level sections continue to reflect the
effective running config.

Frontend: read from `base_config` when available in BaseSection,
useConfigOverride, useAllCameraOverrides, and prepareSectionSavePayload.
Include formData labels in Object/Audio switches widgets so that labels
added only by a profile override remain visible when editing that profile.

* use rasterized_mask as field

makes it easier to exclude from the schema with exclude=True
prevents leaking of the field when using model_dump for profiles

* fix zones

- Fix zone colors not matching across profiles by falling back to base zone color when profile zone data lacks a color field
- Use base_config for base-layer values in masks/zones view so profile-merged values don't pollute the base config editing view
- Handle zones separately in profile manager snapshot/restore since ZoneConfig requires special serialization (color as private attr, contour generation)
- Inherit base zone color and generate contours for profile zone overrides in profile manager

* formatting

* don't require restart for camera enabled change for profiles

* publish camera state when changing profiles

* formatting

* remove available profiles from mqtt

* improve typing
This commit is contained in:
Josh Hawkins
2026-03-19 09:47:57 -05:00
committed by GitHub
parent a05f35c747
commit c93dad9bd9
47 changed files with 4591 additions and 458 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs/configuration/profiles.md
+188
View File
@@ -0,0 +1,188 @@
---
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.
### Using the UI
To create and manage profiles from the UI, open **Settings**. From there you can:
1. **Create a profile** — Navigate to **Profiles**. Click the **Add Profile** button, enter a name (and optionally a profile ID).
2. **Configure overrides** — Navigate to a camera configuration section (e.g. Motion detection, Record, Notifications). In the top right, two buttons will appear - choose a camera and a profile from the profile selector to edit overrides for that camera and section. Only the fields you change will be stored as overrides — fields that require a restart are hidden since profiles are applied at runtime. You can click the **Remove Profile Override** button
3. **Activate a profile** — Use the **Profiles** option in Frigate's main menu to choose a profile. Alternatively, in Settings, navigate to **Profiles**, then choose a profile in the Active Profile dropdown to activate it. The active profile is also shown in the status bar at the bottom of the screen on desktop browsers.
4. **Delete a profile** — Navigate to **Profiles**, then click the trash icon for a profile. This removes the profile definition and all camera overrides associated with it.
### Defining Profiles in YAML
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.
docs/docs/configuration/reference.md
+53
View File
@@ -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
```
docs/docs/integrations/mqtt.md
+8
View File
@@ -275,6 +275,14 @@ 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/notifications/set`
Topic to turn notifications on and off. Expected values are `ON` and `OFF`.
docs/sidebars.ts
+1
View File
@@ -94,6 +94,7 @@ const sidebars: SidebarsConfig = {
"Extra Configuration": [
"configuration/authentication",
"configuration/notifications",
"configuration/profiles",
"configuration/ffmpeg_presets",
"configuration/pwa",
"configuration/tls",