nik/frigate
1
0
Fork 0
mirror of https://github.com/blakeblackshear/frigate.git synced 2026-08-31 07:27:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor Birdseye activity types as composable booleans (#23940)

Browse Source 
* Add combined motion and object Birdseye mode

Add a motion_objects mode that keeps Birdseye active when motion is detected or a confirmed tracked object is present, including stationary objects.

Wire the mode through configuration, runtime commands, API schemas, documentation, and UI labels. Exclude false-positive trackers and add regression coverage for Birdseye activation and MQTT validation.

* Refactor Birdseye activity types as booleans

Replace combination-specific Birdseye modes with composable boolean activity types for motion, active objects, stationary objects, and continuous display.

Preserve legacy single-mode configuration and MQTT inputs, support canonical comma-separated MQTT combinations, and allow scalar YAML values to be replaced by nested settings through the config API.

* Preserve OpenVINO config translations

Regenerate the configuration translations with the OpenVINO detector schema available so the unrelated production detector labels remain intact.

* Preserve partial Birdseye mode overrides

Allow an empty activity selection with a canonical NONE MQTT state so partial camera and profile overrides can disable inherited flags without failing validation.

Add regression coverage for camera and profile inheritance, document the NONE contract, and keep the generated schema fixture scoped to Birdseye.

* Address Birdseye activity review feedback

Move scalar mode compatibility into the 0.18-1 config migration and reject empty activity selections instead of publishing a NONE state.

Pass activity signals through a frozen dataclass, preserve existing active-object tracker behavior, and require confirmed stationary objects. Revert the generic YAML mutation and cover migration, inheritance, MQTT, and activation regressions.

* Move Birdseye migration to 0.19

Use the 0.19-0 configuration revision for converting scalar Birdseye modes to composable activity flags, and update the migration regression coverage accordingly.

* Remove Birdseye migration test

Drop the dedicated config migration test as requested during review while retaining the 0.19-0 migration implementation.
This commit is contained in:
Ersa Oktavian Ramadan 2026-08-12 19:24:35 +07:00 committed by Josh Hawkins
parent 4a2fb2f09c
commit a83219af56
22 changed files with 606 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/docs/configuration/advanced/reference.md
View File

@ -251,11 +251,17 @@ birdseye:
# Optional: Encoding quality of the mpeg1 feed (default: shown below)
# 1 is the highest quality, and 31 is the lowest. Lower quality feeds utilize less CPU resources.
quality: 8
# Optional: Mode of the view. Available options are: objects, motion, and continuous
# objects - cameras are included if they have had a tracked object within the last 30 seconds
# motion - cameras are included if motion was detected in the last 30 seconds
# continuous - all cameras are included always
mode: objects
# Optional: Activity types that include cameras in Birdseye (default: shown below)
# Multiple activity types can be enabled at the same time.
mode:
# Optional: All cameras are included always (default: shown below)
continuous: False
# Optional: Cameras are included if motion was detected in the last 30 seconds (default: shown below)
motion: False
# Optional: Cameras are included if they have had an active tracked object within the last 30 seconds (default: shown below)
objects: True
# Optional: Cameras are included while they have a stationary tracked object (default: shown below)
stationary_objects: False
# Optional: Threshold for camera activity to stop showing camera (default: shown below)
inactivity_threshold: 30
# Optional: Configure the birdseye layout

30
docs/docs/configuration/birdseye.md
View File

@ -18,13 +18,14 @@ Each camera tile in Birdseye is composed from the frames of the stream assigned
## Birdseye Behavior
### Birdseye Modes
### Birdseye Activity Types
Birdseye offers different modes to customize which cameras show under which circumstances.
Birdseye offers independent activity types that control when cameras are shown. Multiple activity types can be enabled together.
- **continuous:** All cameras are always included
- **motion:** Cameras that have detected motion within the last 30 seconds are included
- **objects:** Cameras that have tracked an active object within the last 30 seconds are included
- **continuous:** The camera is always included
- **motion:** The camera is included when motion was detected within the last 30 seconds
- **objects:** The camera is included when an active object was tracked within the last 30 seconds
- **stationary_objects:** The camera is included while a stationary object is tracked
### Custom Birdseye Icon
@ -39,27 +40,30 @@ To include a camera in Birdseye view only for specific circumstances, or exclude
**Global settings:** Navigate to <NavPath path="Settings > System > Birdseye" /> to configure the default Birdseye behavior for all cameras.
**Per-camera overrides:** Navigate to <NavPath path="Settings > Camera configuration > Birdseye" /> to override the mode or disable Birdseye for a specific camera.
**Per-camera overrides:** Navigate to <NavPath path="Settings > Camera configuration > Birdseye" /> to override the activity types or disable Birdseye for a specific camera.
| Field | Description |
| ------------------- | ------------------------------------------------------------- |
| **Enable Birdseye** | Whether this camera appears in Birdseye view |
| **Tracking mode** | When to show the camera: `continuous`, `motion`, or `objects` |
| Field | Description |
| ---------------------- | ---------------------------------------------------------- |
| **Enable Birdseye** | Whether this camera appears in Birdseye view |
| **Activity types** | Conditions that determine when to show the camera |
</TabItem>
<TabItem value="yaml">
```yaml {8-10,12-14}
```yaml {8-11,13-15}
# Include all cameras by default in Birdseye view
birdseye:
enabled: True
mode: continuous
mode:
continuous: True
cameras:
front:
# Only include the "front" camera in Birdseye view when objects are detected
birdseye:
mode: objects
mode:
continuous: False
objects: True
back:
# Exclude the "back" camera from Birdseye view
birdseye:

17
docs/docs/integrations/mqtt.md
View File

@ -555,20 +555,21 @@ Topic with current state of Birdseye for a camera. Published values are `ON` and
### `frigate/<camera_name>/birdseye_mode/set`
Topic to set Birdseye mode for a camera. Birdseye offers different modes to customize under which circumstances the camera is shown.
Topic to set the Birdseye activity types for a camera. Send one uppercase activity type or combine multiple types with commas, for example `MOTION,OBJECTS,STATIONARY_OBJECTS`.
_Note: Changing the value from `CONTINUOUS` -> `MOTION | OBJECTS` will take up to 30 seconds for
_Note: Changing the value from `CONTINUOUS` to non-continuous activity types will take up to 30 seconds for
the camera to be removed from the view._
| Command | Description |
| ------------ | ----------------------------------------------------------------- |
| `CONTINUOUS` | Always included |
| `MOTION` | Show when detected motion within the last 30 seconds are included |
| `OBJECTS` | Shown if an active object tracked within the last 30 seconds |
| Command | Description |
| -------------------- | ---------------------------------------------------------------- |
| `CONTINUOUS` | Always included |
| `MOTION` | Shown if motion was detected within the last 30 seconds |
| `OBJECTS` | Shown if an active object was tracked within the last 30 seconds |
| `STATIONARY_OBJECTS` | Shown while a stationary object is tracked |
### `frigate/<camera_name>/birdseye_mode/state`
Topic with current state of the Birdseye mode for a camera. Published values are `CONTINUOUS`, `MOTION`, `OBJECTS`.
Topic with the current Birdseye activity types for a camera. Multiple enabled types are published as a comma-separated value in the order `OBJECTS`, `MOTION`, `STATIONARY_OBJECTS`, `CONTINUOUS`.
### `frigate/<camera_name>/notifications/set`

13
frigate/comms/dispatcher.py
View File

@ -11,7 +11,7 @@ from frigate.camera.activity_manager import AudioActivityManager, CameraActivity
from frigate.comms.base_communicator import Communicator
from frigate.comms.runtime_state import RuntimeStatePersistence
from frigate.comms.webpush import WebPushClient
from frigate.config import BirdseyeModeEnum, FrigateConfig
from frigate.config import BirdseyeModeConfig, FrigateConfig
from frigate.config.camera.updater import (
CameraConfigUpdateEnum,
CameraConfigUpdatePublisher,
@ -882,8 +882,9 @@ class Dispatcher:
def _on_birdseye_mode_command(self, camera_name: str, payload: str) -> None:
"""Callback for birdseye mode topic."""
if payload not in ["CONTINUOUS", "MOTION", "OBJECTS"]:
logger.info(f"Invalid birdseye_mode command: {payload}")
mode = BirdseyeModeConfig.from_mqtt_payload(payload)
if mode is None:
logger.info("Invalid birdseye_mode command: %s", payload)
return
birdseye_settings = self.config.cameras[camera_name].birdseye
@ -892,7 +893,7 @@ class Dispatcher:
logger.info(f"Birdseye mode not enabled for {camera_name}")
return
birdseye_settings.mode = BirdseyeModeEnum(payload.lower())
birdseye_settings.mode = mode
logger.info(
f"Setting birdseye mode for {camera_name} to {birdseye_settings.mode}"
)
@ -901,7 +902,9 @@ class Dispatcher:
CameraConfigUpdateTopic(CameraConfigUpdateEnum.birdseye, camera_name),
birdseye_settings,
)
self.publish(f"{camera_name}/birdseye_mode/state", payload, retain=True)
self.publish(
f"{camera_name}/birdseye_mode/state", mode.to_mqtt_payload(), retain=True
)
def _on_camera_notification_command(self, camera_name: str, payload: str) -> None:
"""Callback for camera level notifications topic."""

2
frigate/comms/mqtt.py
View File

@ -125,7 +125,7 @@ class MqttClient(Communicator):
self.publish(
f"{camera_name}/birdseye_mode/state",
(
camera.birdseye.mode.value.upper()
camera.birdseye.mode.to_mqtt_payload()
if camera.birdseye.enabled
else "OFF"
),

94
frigate/config/camera/birdseye.py
View File

@ -1,5 +1,3 @@
from enum import Enum
from pydantic import BaseModel, Field
from ..base import FrigateBaseModel
@ -8,22 +6,78 @@ __all__ = [
"BirdseyeCameraConfig",
"BirdseyeConfig",
"BirdseyeLayoutConfig",
"BirdseyeModeEnum",
"BirdseyeModeConfig",
]
BIRDSEYE_ACTIVITY_TYPES = (
"objects",
"motion",
"stationary_objects",
"continuous",
)
class BirdseyeModeEnum(str, Enum):
objects = "objects"
motion = "motion"
continuous = "continuous"
class BirdseyeModeConfig(FrigateBaseModel):
continuous: bool = Field(
default=False,
title="Continuous",
description="Always include the camera in Birdseye.",
)
motion: bool = Field(
default=False,
title="Motion",
description="Include the camera in Birdseye when motion is detected.",
)
objects: bool = Field(
default=False,
title="Active objects",
description="Include the camera in Birdseye while an active object is tracked.",
)
stationary_objects: bool = Field(
default=False,
title="Stationary objects",
description="Include the camera in Birdseye while a stationary object is tracked.",
)
@classmethod
def get_index(cls, type):
return list(cls).index(type)
def from_mqtt_payload(cls, payload: str) -> "BirdseyeModeConfig | None":
"""Create mode options from an uppercase MQTT payload."""
raw_modes = payload.split(",")
if not raw_modes or any(not mode for mode in raw_modes):
return None
@classmethod
def get(cls, index):
return list(cls)[index]
modes = [mode.lower() for mode in raw_modes]
if any(
raw_mode != mode.upper() or mode not in BIRDSEYE_ACTIVITY_TYPES
for raw_mode, mode in zip(raw_modes, modes)
):
return None
if len(modes) != len(set(modes)):
return None
return cls(**{mode: True for mode in modes})
def has_enabled_activity(self) -> bool:
"""Return whether at least one activity type is enabled."""
return any(getattr(self, activity) for activity in BIRDSEYE_ACTIVITY_TYPES)
def to_mqtt_payload(self) -> str:
"""Serialize enabled mode options for MQTT state topics."""
payload = ",".join(
activity.upper()
for activity in BIRDSEYE_ACTIVITY_TYPES
if getattr(self, activity)
)
if not payload:
raise ValueError("At least one Birdseye activity type must be enabled")
return payload
def default_birdseye_mode() -> BirdseyeModeConfig:
"""Return the default Birdseye mode configuration."""
return BirdseyeModeConfig(objects=True)
class BirdseyeLayoutConfig(FrigateBaseModel):
@ -47,10 +101,10 @@ class BirdseyeConfig(FrigateBaseModel):
title="Enable Birdseye",
description="Enable or disable the Birdseye view feature.",
)
mode: BirdseyeModeEnum = Field(
default=BirdseyeModeEnum.objects,
title="Tracking mode",
description="Mode for including cameras in Birdseye: 'objects', 'motion', or 'continuous'.",
mode: BirdseyeModeConfig = Field(
default_factory=default_birdseye_mode,
title="Activity types",
description="Activity types that include cameras in Birdseye.",
)
restream: bool = Field(
@ -102,10 +156,10 @@ class BirdseyeCameraConfig(BaseModel):
title="Enable Birdseye",
description="Enable or disable the Birdseye view feature.",
)
mode: BirdseyeModeEnum = Field(
default=BirdseyeModeEnum.objects,
title="Tracking mode",
description="Mode for including cameras in Birdseye: 'objects', 'motion', or 'continuous'.",
mode: BirdseyeModeConfig = Field(
default_factory=default_birdseye_mode,
title="Activity types",
description="Activity types that include cameras in Birdseye.",
)
order: int = Field(

20
frigate/config/config.py
View File

@ -41,7 +41,7 @@ from .auth import AuthConfig
from .base import FrigateBaseModel
from .camera import CameraConfig, CameraLiveConfig
from .camera.audio import AudioConfig, AudioFilterConfig
from .camera.birdseye import BirdseyeConfig
from .camera.birdseye import BirdseyeConfig, BirdseyeModeConfig
from .camera.detect import DetectConfig
from .camera.ffmpeg import FfmpegConfig
from .camera.genai import GenAIConfig, GenAIRoleEnum
@ -326,8 +326,20 @@ def verify_required_zones_exist(camera_config: CameraConfig) -> None:
def verify_profile_overrides_match_base(camera_config: CameraConfig) -> None:
"""Verify that profile zone and mask IDs reference entries defined on the base camera."""
"""Verify profile overrides against the resolved base camera configuration."""
for profile_name, profile in camera_config.profiles.items():
if profile.birdseye is not None:
overrides = profile.birdseye.mode.model_dump(exclude_unset=True)
base_mode = camera_config.birdseye.mode.model_dump()
resolved_mode = BirdseyeModeConfig.model_validate(
deep_merge(overrides, base_mode)
)
if not resolved_mode.has_enabled_activity():
raise ValueError(
f"Camera '{camera_config.name}' profile '{profile_name}' must "
"enable at least one Birdseye activity type"
)
if profile.zones:
for zone_name in profile.zones:
if zone_name not in camera_config.zones:
@ -998,6 +1010,10 @@ class FrigateConfig(FrigateBaseModel):
self.cameras[name] = camera_config
verify_config_roles(camera_config)
if not camera_config.birdseye.mode.has_enabled_activity():
raise ValueError(
f"Camera '{name}' must enable at least one Birdseye activity type"
)
verify_valid_live_stream_names(self, camera_config)
verify_recording_segments_setup_with_reasonable_time(camera_config)
verify_zone_objects_are_tracked(camera_config)

4
frigate/config/profile_manager.py
View File

@ -43,7 +43,9 @@ SECTION_STATE_TOPICS: dict[str, list[tuple[str, Callable[[Any], Any]]]] = {
("birdseye", lambda c: "ON" if c.birdseye.enabled else "OFF"),
(
"birdseye_mode",
lambda c: c.birdseye.mode.value.upper() if c.birdseye.enabled else "OFF",
lambda c: (
c.birdseye.mode.to_mqtt_payload() if c.birdseye.enabled else "OFF"
),
),
],
"detect": [("detect", lambda c: "ON" if c.detect.enabled else "OFF")],

2
frigate/genai/prompts.py
View File

@ -468,7 +468,7 @@ def get_tool_definitions(
],
"description": (
"The feature to change. Most features accept ON or OFF. "
"birdseye_mode accepts CONTINUOUS, MOTION, or OBJECTS. "
"birdseye_mode accepts CONTINUOUS, MOTION, OBJECTS, STATIONARY_OBJECTS, or a comma-separated combination. "
"motion_contour_area and motion_threshold accept a number. "
"profile accepts a profile name or 'none' to deactivate (requires camera='*')."
),

63
frigate/output/birdseye.py
View File

@ -9,6 +9,7 @@ import queue
import subprocess as sp
import threading
import traceback
from dataclasses import dataclass
from multiprocessing.synchronize import Event as MpEvent
from typing import Any
@ -16,7 +17,7 @@ import cv2
import numpy as np
from frigate.comms.inter_process import InterProcessRequestor
from frigate.config import BirdseyeModeEnum, FfmpegConfig, FrigateConfig
from frigate.config import BirdseyeModeConfig, FfmpegConfig, FrigateConfig
from frigate.const import BASE_DIR, BIRDSEYE_PIPE, INSTALL_DIR, UPDATE_BIRDSEYE_LAYOUT
from frigate.output.ws_auth import ws_has_camera_access
from frigate.util.image import (
@ -28,6 +29,15 @@ from frigate.util.image import (
logger = logging.getLogger(__name__)
@dataclass(frozen=True, slots=True)
class BirdseyeActivity:
"""Activity signals used to decide whether a camera is shown in Birdseye."""
has_active_object: bool
has_stationary_object: bool
has_motion: bool
def get_standard_aspect_ratio(width: int, height: int) -> tuple[int, int]:
"""Ensure that only standard aspect ratios are used."""
# it is important that all ratios have the same scale
@ -409,18 +419,16 @@ class BirdsEyeFrameManager:
)
def camera_active(
self, mode: Any, object_box_count: int, motion_box_count: int
self,
mode: BirdseyeModeConfig,
activity: BirdseyeActivity,
) -> bool:
if mode == BirdseyeModeEnum.continuous:
return True
if mode == BirdseyeModeEnum.motion and motion_box_count > 0:
return True
if mode == BirdseyeModeEnum.objects and object_box_count > 0:
return True
return False
return (
mode.continuous
or (mode.motion and activity.has_motion)
or (mode.objects and activity.has_active_object)
or (mode.stationary_objects and activity.has_stationary_object)
)
def get_camera_coordinates(self) -> dict[str, dict[str, int]]:
"""Return the coordinates of each camera in the current layout."""
@ -725,8 +733,7 @@ class BirdsEyeFrameManager:
def update(
self,
camera: str,
object_count: int,
motion_count: int,
activity: BirdseyeActivity,
frame_time: float,
frame: np.ndarray,
) -> tuple[bool, bool]:
@ -754,7 +761,10 @@ class BirdsEyeFrameManager:
# update the last active frame for the camera
self.cameras[camera]["current_frame"] = frame.copy()
self.cameras[camera]["current_frame_time"] = frame_time
if self.camera_active(camera_config.birdseye.mode, object_count, motion_count):
if self.camera_active(
camera_config.birdseye.mode,
activity,
):
self.cameras[camera]["last_active_frame"] = frame_time
now = datetime.datetime.now().timestamp()
@ -862,10 +872,29 @@ class Birdseye:
frame_time: float,
frame: np.ndarray,
) -> None:
has_active_object = False
has_stationary_object = False
for tracked_object in current_tracked_objects:
if tracked_object["stationary"]:
if not tracked_object["false_positive"]:
has_stationary_object = True
else:
# Preserve the existing objects activity behavior, which includes
# non-stationary trackers before they are confirmed.
has_active_object = True
if has_active_object and has_stationary_object:
break
activity = BirdseyeActivity(
has_active_object=has_active_object,
has_stationary_object=has_stationary_object,
has_motion=bool(motion_boxes),
)
frame_changed, frame_layout_changed = self.birdseye_manager.update(
camera,
len([o for o in current_tracked_objects if not o["stationary"]]),
len(motion_boxes),
activity,
frame_time,
frame,
)

35
frigate/test/http_api/test_http_config_set.py
View File

@ -386,9 +386,19 @@ class TestConfigSetWildcardPropagation(BaseTestHttp):
guess (mode still equals the previous global) wrongly claims a camera
whose explicit yaml mode happens to match.
"""
self.minimal_config["birdseye"] = {"enabled": True, "mode": "motion"}
self.minimal_config["birdseye"] = {
"enabled": True,
"mode": {"motion": True},
}
# explicit override that matches the global value being replaced
self.minimal_config["cameras"]["front_door"]["birdseye"] = {"mode": "motion"}
self.minimal_config["cameras"]["front_door"]["birdseye"] = {
"mode": {
"continuous": False,
"motion": True,
"objects": False,
"stationary_objects": False,
}
}
config_path = self._write_config_file()
mock_find_config.return_value = config_path
@ -399,7 +409,16 @@ class TestConfigSetWildcardPropagation(BaseTestHttp):
resp = client.put(
"/config/set",
json={
"config_data": {"birdseye": {"mode": "continuous"}},
"config_data": {
"birdseye": {
"mode": {
"continuous": True,
"motion": False,
"objects": False,
"stationary_objects": False,
}
}
},
"update_topic": "config/birdseye",
"requires_restart": 0,
},
@ -411,7 +430,7 @@ class TestConfigSetWildcardPropagation(BaseTestHttp):
mock_publisher.publisher.publish.assert_called_once()
topic, settings = mock_publisher.publisher.publish.call_args[0]
self.assertEqual(topic, "config/birdseye")
self.assertEqual(settings.mode.value, "continuous")
self.assertEqual(settings.mode.to_mqtt_payload(), "CONTINUOUS")
published = {
call[0][0].camera: call[0][1]
@ -425,8 +444,12 @@ class TestConfigSetWildcardPropagation(BaseTestHttp):
)
# the override survives, the inheriting camera follows global
self.assertEqual(published["front_door"].mode.value, "motion")
self.assertEqual(published["back_yard"].mode.value, "continuous")
self.assertEqual(
published["front_door"].mode.to_mqtt_payload(), "MOTION"
)
self.assertEqual(
published["back_yard"].mode.to_mqtt_payload(), "CONTINUOUS"
)
finally:
os.unlink(config_path)

117
frigate/test/test_birdseye.py
View File

@ -2,9 +2,15 @@
import multiprocessing as mp
import unittest
from unittest.mock import Mock
from frigate.config import FrigateConfig
from frigate.output.birdseye import BirdsEyeFrameManager, get_canvas_shape
from frigate.config import BirdseyeModeConfig, FrigateConfig
from frigate.output.birdseye import (
Birdseye,
BirdseyeActivity,
BirdsEyeFrameManager,
get_canvas_shape,
)
class TestBirdseye(unittest.TestCase):
@ -201,13 +207,118 @@ class TestBirdseye(unittest.TestCase):
self.assertEqual(cam_d[0], cam_c[0] + cam_c[2])
class TestBirdseyeActivity(unittest.TestCase):
"""Test which camera activity is included in each Birdseye mode."""
def setUp(self):
config = {
"mqtt": {"enabled": False},
"birdseye": {
"enabled": True,
"mode": {
"motion": True,
"objects": True,
"stationary_objects": True,
},
},
"cameras": {
"front": {
"ffmpeg": {
"inputs": [
{"path": "rtsp://10.0.0.1:554/video", "roles": ["detect"]}
]
},
"detect": {"height": 1080, "width": 1920, "fps": 5},
}
},
}
self.manager = BirdsEyeFrameManager(FrigateConfig(**config), mp.Event())
def test_existing_modes_keep_their_activity_rules(self):
continuous = BirdseyeModeConfig(continuous=True)
motion = BirdseyeModeConfig(motion=True)
objects = BirdseyeModeConfig(objects=True)
no_activity = BirdseyeActivity(False, False, False)
motion_activity = BirdseyeActivity(False, False, True)
stationary_activity = BirdseyeActivity(False, True, False)
active_object_activity = BirdseyeActivity(True, False, False)
assert self.manager.camera_active(continuous, no_activity)
assert self.manager.camera_active(motion, motion_activity)
assert not self.manager.camera_active(motion, stationary_activity)
assert self.manager.camera_active(objects, active_object_activity)
assert not self.manager.camera_active(objects, stationary_activity)
def test_modes_can_be_combined(self):
mode = BirdseyeModeConfig(motion=True, stationary_objects=True)
assert self.manager.camera_active(mode, BirdseyeActivity(False, False, True))
assert self.manager.camera_active(mode, BirdseyeActivity(False, True, False))
assert not self.manager.camera_active(
mode, BirdseyeActivity(False, False, False)
)
def test_stationary_objects_are_independent_from_active_objects(self):
stationary_objects = BirdseyeModeConfig(stationary_objects=True)
assert self.manager.camera_active(
stationary_objects, BirdseyeActivity(False, True, False)
)
assert not self.manager.camera_active(
stationary_objects, BirdseyeActivity(True, False, False)
)
def test_write_data_preserves_active_and_confirms_stationary_activity(self):
birdseye = Birdseye.__new__(Birdseye)
birdseye.birdseye_manager = Mock()
birdseye.birdseye_manager.update.return_value = (False, False)
birdseye._idle_interval = None
frame = Mock()
birdseye.write_data(
"front",
[
{"stationary": True, "false_positive": True},
{"stationary": False, "false_positive": True},
{"stationary": True, "false_positive": False},
],
[[0, 0, 10, 10]],
1.0,
frame,
)
birdseye.birdseye_manager.update.assert_called_once_with(
"front", BirdseyeActivity(True, True, True), 1.0, frame
)
def test_stationary_false_positive_does_not_activate_birdseye(self):
birdseye = Birdseye.__new__(Birdseye)
birdseye.birdseye_manager = Mock()
birdseye.birdseye_manager.update.return_value = (False, False)
birdseye._idle_interval = None
frame = Mock()
birdseye.write_data(
"front",
[{"stationary": True, "false_positive": True}],
[],
1.0,
frame,
)
birdseye.birdseye_manager.update.assert_called_once_with(
"front", BirdseyeActivity(False, False, False), 1.0, frame
)
class TestBirdseyeCameraOrder(unittest.TestCase):
"""Test that birdseye reacts to camera order changes without a restart."""
def setUp(self):
config = {
"mqtt": {"enabled": False},
"birdseye": {"enabled": True, "mode": "continuous"},
"birdseye": {"enabled": True, "mode": {"continuous": True}},
"cameras": {
camera: {
"ffmpeg": {

109
frigate/test/test_config.py
View File

@ -7,7 +7,7 @@ import numpy as np
from pydantic import ValidationError
from ruamel.yaml.constructor import DuplicateKeyError
from frigate.config import BirdseyeModeEnum, FrigateConfig
from frigate.config import FrigateConfig
from frigate.const import MODEL_CACHE_DIR
from frigate.detectors import DetectorTypeEnum
from frigate.util.builtin import deep_merge
@ -170,7 +170,7 @@ class TestConfig(unittest.TestCase):
def test_override_birdseye(self):
config = {
"mqtt": {"host": "mqtt"},
"birdseye": {"enabled": True, "mode": "continuous"},
"birdseye": {"enabled": True, "mode": {"continuous": True}},
"cameras": {
"back": {
"ffmpeg": {
@ -183,19 +183,30 @@ class TestConfig(unittest.TestCase):
"width": 1920,
"fps": 5,
},
"birdseye": {"enabled": False, "mode": "motion"},
"birdseye": {
"enabled": False,
"mode": {"continuous": False, "motion": True},
},
}
},
}
frigate_config = FrigateConfig(**config)
assert not frigate_config.cameras["back"].birdseye.enabled
assert frigate_config.cameras["back"].birdseye.mode is BirdseyeModeEnum.motion
mode = frigate_config.cameras["back"].birdseye.mode
assert mode.motion
assert not mode.continuous
assert not mode.objects
assert not mode.stationary_objects
def test_override_birdseye_non_inheritable(self):
config = {
"mqtt": {"host": "mqtt"},
"birdseye": {"enabled": True, "mode": "continuous", "height": 1920},
"birdseye": {
"enabled": True,
"mode": {"continuous": True},
"height": 1920,
},
"cameras": {
"back": {
"ffmpeg": {
@ -218,7 +229,7 @@ class TestConfig(unittest.TestCase):
def test_inherit_birdseye(self):
config = {
"mqtt": {"host": "mqtt"},
"birdseye": {"enabled": True, "mode": "continuous"},
"birdseye": {"enabled": True, "mode": {"continuous": True}},
"cameras": {
"back": {
"ffmpeg": {
@ -237,9 +248,89 @@ class TestConfig(unittest.TestCase):
frigate_config = FrigateConfig(**config)
assert frigate_config.cameras["back"].birdseye.enabled
assert (
frigate_config.cameras["back"].birdseye.mode is BirdseyeModeEnum.continuous
)
mode = frigate_config.cameras["back"].birdseye.mode
assert mode.continuous
assert not mode.motion
assert not mode.objects
assert not mode.stationary_objects
def test_combine_birdseye_activity_types(self):
config = {
**self.minimal,
"birdseye": {
"mode": {
"motion": True,
"stationary_objects": True,
}
},
}
frigate_config = FrigateConfig(**config)
mode = frigate_config.cameras["back"].birdseye.mode
assert mode.motion
assert mode.stationary_objects
assert not mode.continuous
assert not mode.objects
def test_birdseye_requires_an_activity_type(self):
config = {
**self.minimal,
"birdseye": {
"mode": {
"continuous": False,
"motion": False,
"objects": False,
"stationary_objects": False,
}
},
}
with self.assertRaisesRegex(
ValidationError, "must enable at least one Birdseye activity type"
):
FrigateConfig(**config)
def test_camera_can_disable_an_inherited_activity_type(self):
config = {
**self.minimal,
"birdseye": {"mode": {"motion": True, "objects": True}},
}
config["cameras"]["back"]["birdseye"] = {"mode": {"motion": False}}
frigate_config = FrigateConfig(**config)
mode = frigate_config.cameras["back"].birdseye.mode
assert not mode.motion
assert mode.objects
def test_profile_must_leave_an_activity_type_enabled(self):
config = {
**self.minimal,
"profiles": {"away": {"friendly_name": "Away"}},
"birdseye": {"mode": {"objects": True}},
}
config["cameras"]["back"]["profiles"] = {
"away": {"birdseye": {"mode": {"objects": False}}}
}
with self.assertRaisesRegex(
ValidationError, "must enable at least one Birdseye activity type"
):
FrigateConfig(**config)
def test_camera_birdseye_activity_types_override_global_values(self):
config = {
**self.minimal,
"birdseye": {"mode": {"motion": True, "objects": True}},
}
config["cameras"]["back"]["birdseye"] = {
"mode": {"motion": False, "stationary_objects": True}
}
frigate_config = FrigateConfig(**config)
mode = frigate_config.cameras["back"].birdseye.mode
assert not mode.motion
assert mode.objects
assert mode.stationary_objects
def test_override_tracked_objects(self):
config = {

53
frigate/test/test_dispatcher_runtime_state.py
View File

@ -8,6 +8,7 @@ from unittest.mock import MagicMock, patch
from frigate.app import FrigateApp
from frigate.comms.dispatcher import Dispatcher
from frigate.comms.runtime_state import RuntimeStatePersistence
from frigate.config import BirdseyeModeConfig
def _make_camera_mock(
@ -51,6 +52,58 @@ def _build_dispatcher(cameras: dict[str, MagicMock]) -> Dispatcher:
return Dispatcher(config, config_updater, onvif, ptz_metrics, communicators)
class TestBirdseyeModeCommands(unittest.TestCase):
"""Verify Birdseye mode commands use the boolean mode contract."""
def setUp(self) -> None:
self.camera = _make_camera_mock()
self.camera.birdseye.enabled = True
self.dispatcher = _build_dispatcher({"front_door": self.camera})
self.dispatcher.publish = MagicMock()
def test_combined_modes_are_accepted(self) -> None:
self.dispatcher._on_birdseye_mode_command(
"front_door", "STATIONARY_OBJECTS,MOTION"
)
self.assertEqual(
self.camera.birdseye.mode,
BirdseyeModeConfig(motion=True, stationary_objects=True),
)
self.dispatcher.config_updater.publish_update.assert_called_once()
self.dispatcher.publish.assert_called_once_with(
"front_door/birdseye_mode/state",
"MOTION,STATIONARY_OBJECTS",
retain=True,
)
def test_single_activity_type_is_accepted(self) -> None:
self.dispatcher._on_birdseye_mode_command("front_door", "OBJECTS")
self.assertEqual(
self.camera.birdseye.mode,
BirdseyeModeConfig(objects=True),
)
self.dispatcher.publish.assert_called_once_with(
"front_door/birdseye_mode/state", "OBJECTS", retain=True
)
def test_unknown_mode_is_rejected(self) -> None:
for payload in (
"UNKNOWN",
"motion",
"MOTION_OBJECTS",
"NONE",
"NONE,MOTION",
"MOTION,MOTION",
"MOTION,",
):
with self.subTest(payload=payload):
self.dispatcher._on_birdseye_mode_command("front_door", payload)
self.dispatcher.config_updater.publish_update.assert_not_called()
class TestRestoreRuntimeState(unittest.TestCase):
"""Verify replay routes through handlers and tolerates missing entries."""

19
frigate/test/test_profiles.py
View File

@ -560,6 +560,25 @@ class TestProfileManager(unittest.TestCase):
assert err is None
assert self.config.cameras["front"].enabled is False
@patch.object(ProfileManager, "_persist_active_profile")
def test_profile_can_disable_inherited_birdseye_activity(self, mock_persist):
"""A false-only mode override inherits the other base activity types."""
self.config.profiles["away"] = ProfileDefinitionConfig(friendly_name="Away")
base_mode = self.config.cameras["front"].birdseye.mode
base_mode.motion = True
base_mode.objects = True
self.config.cameras["front"].profiles["away"] = CameraProfileConfig(
birdseye={"mode": {"motion": False}}
)
self.manager = ProfileManager(self.config, self.mock_updater)
err = self.manager.activate_profile("away")
assert err is None
mode = self.config.cameras["front"].birdseye.mode
assert not mode.motion
assert mode.objects
@patch.object(ProfileManager, "_persist_active_profile")
def test_deactivate_restores_enabled(self, mock_persist):
"""Deactivating a profile restores the camera's base enabled state."""

45
frigate/util/config.py
View File

@ -20,7 +20,7 @@ from frigate.util.services import get_video_properties
logger = logging.getLogger(__name__)
CURRENT_CONFIG_VERSION = "0.18-0"
CURRENT_CONFIG_VERSION = "0.19-0"
DEFAULT_CONFIG_FILE = os.path.join(CONFIG_DIR, "config.yml")
@ -93,6 +93,7 @@ def migrate_frigate_config(config_file: str):
logger.info("copying config as backup...")
shutil.copy(config_file, os.path.join(CONFIG_DIR, "backup_config.yaml"))
new_config = config
if previous_version < "0.14":
logger.info(f"Migrating frigate config from {previous_version} to 0.14...")
@ -147,6 +148,13 @@ def migrate_frigate_config(config_file: str):
yaml.dump(new_config, f)
previous_version = "0.18-0"
if previous_version < "0.19-0":
logger.info(f"Migrating frigate config from {previous_version} to 0.19-0...")
new_config = migrate_019_0(new_config)
with open(config_file, "w") as f:
yaml.dump(new_config, f)
previous_version = "0.19-0"
logger.info("Finished frigate config migration...")
@ -525,6 +533,21 @@ def _convert_legacy_mask_to_dict(
return result
def _migrate_birdseye_mode(birdseye: dict[str, Any] | None) -> None:
"""Convert a scalar Birdseye mode to composable activity types."""
if not birdseye or not isinstance(birdseye.get("mode"), str):
return
legacy_mode = birdseye["mode"]
activity_types = ("continuous", "motion", "objects", "stationary_objects")
if legacy_mode not in activity_types:
return
birdseye["mode"] = {
activity_type: activity_type == legacy_mode for activity_type in activity_types
}
def migrate_018_0(config: dict[str, dict[str, Any]]) -> dict[str, dict[str, Any]]:
"""Handle migrating frigate config to 0.18-0"""
new_config = config.copy()
@ -658,6 +681,26 @@ def migrate_018_0(config: dict[str, dict[str, Any]]) -> dict[str, dict[str, Any]
return new_config
def migrate_019_0(config: dict[str, dict[str, Any]]) -> dict[str, dict[str, Any]]:
"""Handle migrating Frigate config to 0.19-0."""
new_config = config.copy()
_migrate_birdseye_mode(new_config.get("birdseye"))
for name, camera in new_config.get("cameras", {}).items():
camera_config: dict[str, dict[str, Any]] = camera.copy()
_migrate_birdseye_mode(camera_config.get("birdseye"))
for profile in camera_config.get("profiles", {}).values():
if isinstance(profile, dict):
_migrate_birdseye_mode(profile.get("birdseye"))
new_config["cameras"][name] = camera_config
new_config["version"] = "0.19-0"
return new_config
def get_relative_coordinates(
mask: str | list | None,
frame_shape: tuple[int, int],

2
web/e2e/fixtures/mock-data/config-schema.json
View File

File diff suppressed because one or more lines are too long

20
web/public/locales/en/config/cameras.json
View File

@ -71,8 +71,24 @@
"description": "Enable or disable the Birdseye view feature."
},
"mode": {
"label": "Tracking mode",
"description": "Mode for including cameras in Birdseye: 'objects', 'motion', or 'continuous'."
"label": "Activity types",
"description": "Activity types that include cameras in Birdseye.",
"continuous": {
"label": "Continuous",
"description": "Always include the camera in Birdseye."
},
"motion": {
"label": "Motion",
"description": "Include the camera in Birdseye when motion is detected."
},
"objects": {
"label": "Active objects",
"description": "Include the camera in Birdseye while an active object is tracked."
},
"stationary_objects": {
"label": "Stationary objects",
"description": "Include the camera in Birdseye while a stationary object is tracked."
}
},
"order": {
"label": "Position",

20
web/public/locales/en/config/global.json
View File

@ -558,8 +558,24 @@
"description": "Enable or disable the Birdseye view feature."
},
"mode": {
"label": "Tracking mode",
"description": "Mode for including cameras in Birdseye: 'objects', 'motion', or 'continuous'."
"label": "Activity types",
"description": "Activity types that include cameras in Birdseye.",
"continuous": {
"label": "Continuous",
"description": "Always include the camera in Birdseye."
},
"motion": {
"label": "Motion",
"description": "Include the camera in Birdseye when motion is detected."
},
"objects": {
"label": "Active objects",
"description": "Include the camera in Birdseye while an active object is tracked."
},
"stationary_objects": {
"label": "Stationary objects",
"description": "Include the camera in Birdseye while a stationary object is tracked."
}
},
"restream": {
"label": "Restream RTSP",

2
web/public/locales/en/views/settings.json
View File

@ -1955,7 +1955,7 @@
"noRecordRole": "No streams have the record role defined. Recording will not function."
},
"birdseye": {
"objectsModeDetectDisabled": "Birdseye is set to 'objects' mode, but object detection is disabled for this camera. The camera will not appear in Birdseye."
"objectTrackingDetectDisabled": "Birdseye includes tracked objects, but object detection is disabled for this camera. The camera will not appear in Birdseye."
},
"snapshots": {
"detectDisabled": "Object detection is disabled. Snapshots are generated from tracked objects and will not be created."

20
web/src/components/config-form/section-configs/birdseye.ts
View File

@ -5,13 +5,18 @@ const birdseye: SectionConfigOverrides = {
sectionDocs: "/configuration/birdseye",
messages: [
{
key: "objects-mode-detect-disabled",
messageKey: "configMessages.birdseye.objectsModeDetectDisabled",
key: "object-tracking-detect-disabled",
messageKey: "configMessages.birdseye.objectTrackingDetectDisabled",
severity: "info",
condition: (ctx) => {
if (ctx.level !== "camera" || !ctx.fullCameraConfig) return false;
const mode = ctx.formData?.mode;
if (!mode || typeof mode !== "object" || Array.isArray(mode)) {
return false;
}
return (
ctx.formData?.mode === "objects" &&
(mode.objects === true || mode.stationary_objects === true) &&
ctx.fullCameraConfig.detect?.enabled === false
);
},
@ -24,10 +29,10 @@ const birdseye: SectionConfigOverrides = {
overrideFields: ["enabled", "mode"],
uiSchema: {
mode: {
"ui:size": "xs",
"ui:options": {
enumI18nPrefix: "birdseye.trackingMode",
},
continuous: { "ui:size": "xs" },
motion: { "ui:size": "xs" },
objects: { "ui:size": "xs" },
stationary_objects: { "ui:size": "xs" },
},
},
},
@ -55,7 +60,6 @@ const birdseye: SectionConfigOverrides = {
],
uiSchema: {
mode: {
"ui:size": "xs",
"ui:after": { render: "BirdseyeCameraReorder" },
},
},

11
web/src/types/frigateConfig.ts
View File

@ -13,12 +13,19 @@ export interface UiConfig {
export interface BirdseyeConfig {
enabled: boolean;
height: number;
mode: "objects" | "continuous" | "motion";
mode: BirdseyeModeConfig;
quality: number;
restream: boolean;
width: number;
}
export interface BirdseyeModeConfig {
continuous: boolean;
motion: boolean;
objects: boolean;
stationary_objects: boolean;
}
export interface FaceRecognitionConfig {
enabled: boolean;
model_size: SearchModelSize;
@ -49,7 +56,7 @@ export interface CameraConfig {
best_image_timeout: number;
birdseye: {
enabled: boolean;
mode: "objects" | "continuous" | "motion";
mode: BirdseyeModeConfig;
order: number;
};
detect: {