collapse in-flight retained values by topic and release the shutdown barrier from a finally

* Guard object processor queue handlers against unknown cameras

* Skip embeddings post processing for removed cameras

* End review segments for removed cameras

* Drop queued autotracker moves for removed cameras

* Release tracked event thumbnails when skipping a removed camera

* Add locked accessors for camera states

* Read camera states through the processor accessors

* Guard output and recording paths against cameras not yet known

* Resolve camera state once in ONVIF, notification, and transcription paths

Makefile

@@ -1,7 +1,7 @@
 default_target: local
 
 COMMIT_HASH := $(shell git log -1 --pretty=format:"%h"|tail -1)
-VERSION = 0.18.0
+VERSION = 0.19.0
 IMAGE_REPO ?= ghcr.io/blakeblackshear/frigate
 GITHUB_REF_NAME ?= $(shell git rev-parse --abbrev-ref HEAD)
 BOARDS= #Initialized empty

docs/docs/configuration/advanced/reference.md

@@ -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

docs/docs/configuration/birdseye.md

@@ -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:

docs/docs/integrations/mqtt.md

@@ -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`
 

docs/static/frigate-api.yaml

@@ -2946,6 +2946,44 @@ paths:
         - frigateUserAuth: []
       x-required-role: any
       description: '**Access:** Any authenticated user.'
+  /categorized_object_names:
+    get:
+      tags:
+        - App
+      summary: Get known object names by object type
+      description: |-
+        **Access:** Any authenticated user.
+
+        Returns the sub labels and attributes this install can attach,
+            grouped by object type. Unlike /sub_labels, which reflects what has already been
+            detected, this reads the config and model files, so it covers recognized face
+            names, named license plates, custom object classification categories, and the
+            detector attributes of tracked objects.
+      operationId: categorized_object_names_categorized_object_names_get
+      parameters:
+        - name: object_type
+          in: query
+          required: false
+          schema:
+            anyOf:
+              - type: string
+              - type: 'null'
+            title: Object Type
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema: {}
+        '422':
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
+      security:
+        - frigateUserAuth: []
+      x-required-role: any
   /audio_labels:
     get:
       tags:

frigate/api/app.py

@@ -71,6 +71,7 @@ from frigate.util.config import (
     find_config_file,
     redact_credential,
 )
+from frigate.util.object_names import get_categorized_object_names
 from frigate.util.schema import get_config_schema
 from frigate.util.services import (
     get_nvidia_driver_info,
@@ -1313,6 +1314,28 @@ def get_sub_labels(
     return JSONResponse(content=sub_labels)
 
 
+@router.get(
+    "/categorized_object_names",
+    dependencies=[Depends(allow_any_authenticated())],
+    summary="Get known object names by object type",
+    description="""Returns the sub labels and attributes this install can attach,
+    grouped by object type. Unlike /sub_labels, which reflects what has already been
+    detected, this reads the config and model files, so it covers recognized face
+    names, named license plates, custom object classification categories, and the
+    detector attributes of tracked objects.""",
+)
+def categorized_object_names(
+    request: Request,
+    object_type: str | None = None,
+    allowed_cameras: list[str] = Depends(get_allowed_cameras_for_filter),
+):
+    return JSONResponse(
+        content=get_categorized_object_names(
+            request.app.frigate_config, allowed_cameras, object_type
+        )
+    )
+
+
 @router.get("/audio_labels", dependencies=[Depends(allow_any_authenticated())])
 def get_audio_labels():
     labels = load_labels("/audio-labelmap.txt", prefill=521)

frigate/api/auth.py

@@ -83,6 +83,7 @@ def require_admin_by_default():
         "/nvinfo",
         "/labels",
         "/sub_labels",
+        "/categorized_object_names",
         "/plus/models",
         "/recognized_license_plates",
         "/timeline",

frigate/api/chat.py

@@ -50,6 +50,7 @@ from frigate.jobs.vlm_watch import (
     stop_vlm_watch_job,
 )
 from frigate.models import Event
+from frigate.util.object_names import get_categorized_object_names
 
 logger = logging.getLogger(__name__)
 
@@ -539,6 +540,11 @@ async def execute_tool(
     if tool_name == "search_objects":
         return await _execute_search_objects(request, arguments, allowed_cameras)
 
+    if tool_name == "get_categorized_object_names":
+        return JSONResponse(
+            content=_execute_get_categorized_object_names(request, allowed_cameras)
+        )
+
     if tool_name == "find_similar_objects":
         result = await _execute_find_similar_objects(
             request, arguments, allowed_cameras
@@ -591,7 +597,7 @@ async def _execute_get_live_context(
 
     try:
         frame_processor = request.app.detected_frames_processor
-        camera_state = frame_processor.camera_states.get(camera)
+        camera_state = frame_processor.get_camera_state(camera)
 
         if camera_state is None:
             return {
@@ -655,7 +661,7 @@ async def _get_live_frame_image_url(
         return None
     try:
         frame_processor = request.app.detected_frames_processor
-        if camera not in frame_processor.camera_states:
+        if frame_processor.get_camera_state(camera) is None:
             return None
         frame = frame_processor.get_current_frame(camera, {})
         if frame is None:
@@ -717,6 +723,21 @@ async def _execute_set_camera_state(
     return {"success": True, "camera": camera, "feature": feature, "value": value}
 
 
+def _execute_get_categorized_object_names(
+    request: Request,
+    allowed_cameras: list[str],
+) -> dict[str, Any]:
+    names = get_categorized_object_names(request.app.frigate_config, allowed_cameras)
+
+    if not names:
+        return {
+            "names": {},
+            "message": "No names configured; search by label or semantic_query.",
+        }
+
+    return {"names": names}
+
+
 async def _execute_tool_internal(
     tool_name: str,
     arguments: dict[str, Any],
@@ -741,6 +762,8 @@ async def _execute_tool_internal(
         except (json.JSONDecodeError, AttributeError) as e:
             logger.warning(f"Failed to extract tool result: {e}")
             return {"error": "Failed to parse tool result"}
+    elif tool_name == "get_categorized_object_names":
+        return _execute_get_categorized_object_names(request, allowed_cameras)
     elif tool_name == "find_similar_objects":
         return await _execute_find_similar_objects(request, arguments, allowed_cameras)
     elif tool_name == "set_camera_state":
@@ -773,8 +796,8 @@ async def _execute_tool_internal(
     else:
         logger.error(
             "Tool call failed: unknown tool %r. Expected one of: search_objects, find_similar_objects, "
-            "get_live_context, start_camera_watch, stop_camera_watch, get_profile_status, get_recap. "
-            "Arguments received: %s",
+            "get_categorized_object_names, get_live_context, start_camera_watch, stop_camera_watch, "
+            "get_profile_status, get_recap. Arguments received: %s",
             tool_name,
             json.dumps(arguments),
         )

frigate/api/event.py

@@ -1313,7 +1313,7 @@ async def set_sub_label(
     if request.app.detected_frames_processor:
         tracked_obj: TrackedObject = None
 
-        for state in request.app.detected_frames_processor.camera_states.values():
+        for state in request.app.detected_frames_processor.get_camera_states():
             tracked_obj = state.tracked_objects.get(event_id)
 
             if tracked_obj is not None:
@@ -1372,7 +1372,7 @@ async def set_plate(
     if request.app.detected_frames_processor:
         tracked_obj: TrackedObject = None
 
-        for state in request.app.detected_frames_processor.camera_states.values():
+        for state in request.app.detected_frames_processor.get_camera_states():
             tracked_obj = state.tracked_objects.get(event_id)
 
             if tracked_obj is not None:

frigate/api/media.py

@@ -575,11 +575,11 @@ async def vod_ts(
             Recordings.start_time,
         )
         .where(
-            Recordings.start_time.between(start_ts, end_ts)
-            | Recordings.end_time.between(start_ts, end_ts)
-            | ((start_ts > Recordings.start_time) & (end_ts < Recordings.end_time))
+            Recordings.camera == camera_name,
+            Recordings.start_time >= start_ts - MAX_SEGMENT_DURATION,
+            Recordings.start_time <= end_ts,
+            Recordings.end_time >= start_ts,
         )
-        .where(Recordings.camera == camera_name)
         .order_by(Recordings.start_time.asc())
         .iterator()
     )
@@ -820,7 +820,7 @@ async def event_snapshot(
         # see if the object is currently being tracked
         try:
             camera_states: list[CameraState] = (
-                request.app.detected_frames_processor.camera_states.values()
+                request.app.detected_frames_processor.get_camera_states()
             )
             for camera_state in camera_states:
                 if event_id in camera_state.tracked_objects:
@@ -898,7 +898,7 @@ async def event_thumbnail(
     if thumbnail_bytes is None:
         # see if the object is currently being tracked
         try:
-            camera_states = request.app.detected_frames_processor.camera_states.values()
+            camera_states = request.app.detected_frames_processor.get_camera_states()
             for camera_state in camera_states:
                 if event_id in camera_state.tracked_objects:
                     tracked_obj = camera_state.tracked_objects.get(event_id)
@@ -1127,7 +1127,7 @@ async def event_snapshot_clean(request: Request, event_id: str, download: bool =
             # see if the object is currently being tracked
             try:
                 camera_states = (
-                    request.app.detected_frames_processor.camera_states.values()
+                    request.app.detected_frames_processor.get_camera_states()
                 )
                 for camera_state in camera_states:
                     if event_id in camera_state.tracked_objects:

frigate/api/record.py

@@ -25,7 +25,7 @@ from frigate.api.defs.query.recordings_query_parameters import (
 )
 from frigate.api.defs.response.generic_response import GenericResponse
 from frigate.api.defs.tags import Tags
-from frigate.const import RECORD_DIR
+from frigate.const import MAX_SEGMENT_DURATION, RECORD_DIR
 from frigate.models import Event, Recordings
 from frigate.util.time import get_dst_transitions
 
@@ -243,6 +243,7 @@ async def recordings(
         )
         .where(
             Recordings.camera == camera_name,
+            Recordings.start_time >= after - MAX_SEGMENT_DURATION,
             Recordings.end_time >= after,
             Recordings.start_time <= before,
         )

frigate/app.py

@@ -335,6 +335,7 @@ class FrigateApp:
             self.ptz_metrics,
             comms,
         )
+        self.dispatcher.start_communicators()
 
     def init_profile_manager(self) -> None:
         self.profile_manager = ProfileManager(

frigate/comms/base_communicator.py

@@ -1,11 +1,27 @@
 from abc import ABC, abstractmethod
 from collections.abc import Callable
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from frigate.comms.dispatcher import Dispatcher
 
 
 class Communicator(ABC):
     """pub/sub model via specific protocol."""
 
+    def attach_dispatcher(self, dispatcher: "Dispatcher") -> None:
+        """Receive the owning dispatcher.
+
+        Transports that need more than the receiver callback (the command topic
+        surface, the snapshot API) take it here rather than reaching through the
+        bound receiver.
+        """
+        return None
+
+    def start(self) -> None:
+        """Start background I/O after receiver wiring is complete."""
+        return None
+
     @abstractmethod
     def publish(self, topic: str, payload: Any, retain: bool = False) -> None:
         """Send data via specific protocol."""

frigate/comms/dispatcher.py

@@ -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,
@@ -45,6 +45,11 @@ from frigate.util.services import restart_frigate
 
 logger = logging.getLogger(__name__)
 
+# <camera>/<command>/<sub_command>/set, one segment longer than the rest
+SUB_COMMAND_TOPICS = frozenset({"motion_mask", "object_mask", "zone"})
+
+BARE_COMMAND_TOPICS = frozenset({"onConnect", "restart"})
+
 
 class Dispatcher:
     """Handle communication between Frigate and communicators."""
@@ -99,12 +104,114 @@ class Dispatcher:
         }
         self.profile_manager: ProfileManager | None = None
 
-        for comm in self.comms:
-            comm.subscribe(self._receive)
-
         self.web_push_client = next(
             (comm for comm in communicators if isinstance(comm, WebPushClient)), None
         )
+
+        for comm in self.comms:
+            comm.subscribe(self._receive)
+            comm.attach_dispatcher(self)
+
+    def start_communicators(self) -> None:
+        """Start communicators after dispatcher wiring is fully initialized."""
+        for comm in self.comms:
+            comm.start()
+
+    def is_command_topic(self, topic: str) -> bool:
+        """Whether a prefix-stripped topic maps to a command handler.
+
+        Transports that fan a whole topic tree in must filter on this:
+        _receive() republishes anything it does not recognize, so forwarding
+        unfiltered would echo Frigate's own publishes back.
+        """
+        parts = topic.split("/")
+
+        if topic in BARE_COMMAND_TOPICS:
+            return True
+
+        if len(parts) == 2 and parts[1] == "ptz":
+            return True
+
+        if len(parts) == 2 and parts[1] == "set":
+            return parts[0] in self._global_settings_handlers
+
+        if len(parts) == 3 and parts[2] == "set":
+            return (
+                parts[1] in self._camera_settings_handlers
+                and parts[1] not in SUB_COMMAND_TOPICS
+            )
+
+        if len(parts) == 3 and parts[2] == "suspend":
+            return parts[1] == "notifications"
+
+        if len(parts) == 4 and parts[3] == "set":
+            return parts[1] in SUB_COMMAND_TOPICS
+
+        return False
+
+    def _build_camera_activity_snapshot(self) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Build the current runtime activity snapshot for reconnect consumers."""
+        camera_status = {
+            camera: status
+            for camera, status in self.camera_activity.last_camera_activity.copy().items()
+            if camera in self.config.cameras
+        }
+        audio_detections = self.audio_activity.current_audio_detections.copy()
+        cameras_with_status = camera_status.keys()
+
+        for camera in self.config.cameras.keys():
+            if camera not in cameras_with_status:
+                camera_status[camera] = {}
+
+            camera_status[camera]["config"] = {
+                "detect": self.config.cameras[camera].detect.enabled,
+                "enabled": self.config.cameras[camera].enabled,
+                "snapshots": self.config.cameras[camera].snapshots.enabled,
+                "record": self.config.cameras[camera].record.enabled,
+                "audio": self.config.cameras[camera].audio.enabled,
+                "audio_transcription": self.config.cameras[
+                    camera
+                ].audio_transcription.live_enabled,
+                "notifications": self.config.cameras[camera].notifications.enabled,
+                "notifications_suspended": int(
+                    self.web_push_client.suspended_cameras.get(camera, 0)
+                )
+                if self.web_push_client
+                and camera in self.web_push_client.suspended_cameras
+                else 0,
+                "autotracking": self.config.cameras[camera].onvif.autotracking.enabled,
+                "alerts": self.config.cameras[camera].review.alerts.enabled,
+                "detections": self.config.cameras[camera].review.detections.enabled,
+                "object_descriptions": self.config.cameras[
+                    camera
+                ].objects.genai.enabled,
+                "review_descriptions": self.config.cameras[camera].review.genai.enabled,
+            }
+
+        return camera_status, audio_detections
+
+    def publish_runtime_snapshot(
+        self,
+        publisher: Callable[[str, Any, bool], None] | None = None,
+    ) -> None:
+        """Publish the runtime snapshot for newly connected listeners."""
+        publish = publisher or self.publish
+        camera_status, audio_detections = self._build_camera_activity_snapshot()
+
+        publish("camera_activity", json.dumps(camera_status), False)
+        publish("model_state", json.dumps(self.model_state.copy()), False)
+        publish(
+            "embeddings_reindex_progress",
+            json.dumps(self.embeddings_reindex.copy()),
+            False,
+        )
+        publish("birdseye_layout", json.dumps(self.birdseye_layout.copy()), False)
+        publish("audio_detections", json.dumps(audio_detections), False)
+        publish(
+            "profile/state",
+            self.config.active_profile or "none",
+            True,
+        )
         if self.web_push_client is not None:
             self.web_push_client.set_suspension_broadcaster(self.publish)
 
@@ -123,17 +230,11 @@ class Dispatcher:
 
             try:
                 if command_type == "set":
-                    # Commands that require a sub-command (mask/zone name)
-                    sub_command_required = {
-                        "motion_mask",
-                        "object_mask",
-                        "zone",
-                    }
                     if sub_command:
                         self._camera_settings_handlers[command](
                             camera_name, sub_command, payload
                         )
-                    elif command in sub_command_required:
+                    elif command in SUB_COMMAND_TOPICS:
                         logger.error(
                             "Command %s requires a sub-command (mask/zone name)",
                             command,
@@ -267,67 +368,11 @@ class Dispatcher:
         def handle_birdseye_layout() -> None:
             self.publish("birdseye_layout", json.dumps(self.birdseye_layout.copy()))
 
-        def handle_on_connect() -> None:
-            camera_status = {
-                camera: status
-                for camera, status in self.camera_activity.last_camera_activity.copy().items()
-                if camera in self.config.cameras
-            }
-            audio_detections = self.audio_activity.current_audio_detections.copy()
-            cameras_with_status = camera_status.keys()
-
-            for camera in self.config.cameras.keys():
-                if camera not in cameras_with_status:
-                    camera_status[camera] = {}
-
-                camera_status[camera]["config"] = {
-                    "detect": self.config.cameras[camera].detect.enabled,
-                    "enabled": self.config.cameras[camera].enabled,
-                    "snapshots": self.config.cameras[camera].snapshots.enabled,
-                    "record": self.config.cameras[camera].record.enabled,
-                    "audio": self.config.cameras[camera].audio.enabled,
-                    "audio_transcription": self.config.cameras[
-                        camera
-                    ].audio_transcription.live_enabled,
-                    "notifications": self.config.cameras[camera].notifications.enabled,
-                    "notifications_suspended": int(
-                        self.web_push_client.suspended_cameras.get(camera, 0)
-                    )
-                    if self.web_push_client
-                    and camera in self.web_push_client.suspended_cameras
-                    else 0,
-                    "autotracking": self.config.cameras[
-                        camera
-                    ].onvif.autotracking.enabled,
-                    "alerts": self.config.cameras[camera].review.alerts.enabled,
-                    "detections": self.config.cameras[camera].review.detections.enabled,
-                    "object_descriptions": self.config.cameras[
-                        camera
-                    ].objects.genai.enabled,
-                    "review_descriptions": self.config.cameras[
-                        camera
-                    ].review.genai.enabled,
-                }
-
-            self.publish("camera_activity", json.dumps(camera_status))
-            self.publish("model_state", json.dumps(self.model_state.copy()))
-            self.publish(
-                "embeddings_reindex_progress",
-                json.dumps(self.embeddings_reindex.copy()),
-            )
-            self.publish("birdseye_layout", json.dumps(self.birdseye_layout.copy()))
-            self.publish("audio_detections", json.dumps(audio_detections))
-            self.publish(
-                "profile/state",
-                self.config.active_profile or "none",
-                retain=True,
-            )
-
         def handle_notification_test() -> None:
             self.publish("notification_test", "Test notification")
 
         # Dictionary mapping topic to handlers
-        topic_handlers = {
+        topic_handlers: dict[str, Callable[[], Any]] = {
             INSERT_MANY_RECORDINGS: handle_insert_many_recordings,
             REQUEST_REGION_GRID: handle_request_region_grid,
             INSERT_PREVIEW: handle_insert_preview,
@@ -350,7 +395,7 @@ class Dispatcher:
             "jobState": handle_job_state,
             "audioTranscriptionState": handle_audio_transcription_state,
             "birdseyeLayout": handle_birdseye_layout,
-            "onConnect": handle_on_connect,
+            "onConnect": self.publish_runtime_snapshot,
         }
 
         if topic.endswith("set") or topic.endswith("ptz") or topic.endswith("suspend"):
@@ -882,8 +927,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 +938,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 +947,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."""

frigate/comms/inter_process.py

@@ -18,10 +18,13 @@ SOCKET_REP_REQ = "ipc:///tmp/cache/comms"
 
 class InterProcessCommunicator(Communicator):
     def __init__(self) -> None:
+        # bound eagerly so subprocesses starting before start_communicators()
+        # can still connect; their requests queue in zmq until the reader runs
         self.context = zmq.Context()
         self.socket = self.context.socket(zmq.REP)
         self.socket.bind(SOCKET_REP_REQ)
         self.stop_event: MpEvent = mp.Event()
+        self.reader_thread: threading.Thread | None = None
 
     def publish(self, topic: str, payload: Any, retain: bool = False) -> None:
         """There is no communication back to the processes."""
@@ -29,6 +32,8 @@ class InterProcessCommunicator(Communicator):
 
     def subscribe(self, receiver: Callable) -> None:
         self._dispatcher = receiver
+
+    def start(self) -> None:
         self.reader_thread = threading.Thread(target=self.read)
         self.reader_thread.start()
 
@@ -61,7 +66,8 @@ class InterProcessCommunicator(Communicator):
 
     def stop(self) -> None:
         self.stop_event.set()
-        self.reader_thread.join()
+        if self.reader_thread is not None:
+            self.reader_thread.join()
         self.socket.close(linger=0)
         self.context.destroy(linger=0)
 

frigate/comms/mqtt.py

@@ -1,7 +1,12 @@
+from __future__ import annotations
+
 import logging
+import queue
 import threading
+import time
 from collections.abc import Callable
-from typing import Any
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
 
 import paho.mqtt.client as mqtt
 from paho.mqtt.enums import CallbackAPIVersion
@@ -9,8 +14,25 @@ from paho.mqtt.enums import CallbackAPIVersion
 from frigate.comms.base_communicator import Communicator
 from frigate.config import FrigateConfig
 
+if TYPE_CHECKING:
+    from frigate.comms.dispatcher import Dispatcher
+
 logger = logging.getLogger(__name__)
 
+MQTT_LOOP_TIMEOUT = 1.0
+MQTT_RECONNECT_INTERVAL = 10.0
+MQTT_SHUTDOWN_FLUSH_TIMEOUT = 5.0
+MQTT_ON_CONNECT_RATE_LIMIT = 1.0
+MQTT_PUBLISH_WAIT_INTERVAL = 0.1
+
+
+@dataclass(slots=True)
+class QueuedPublish:
+    topic: str
+    payload: Any
+    retain: bool
+    done: threading.Event | None = None
+
 
 class MqttClient(Communicator):
     """Frigate wrapper for mqtt client."""
@@ -19,28 +41,80 @@ class MqttClient(Communicator):
         self.config = config
         self.mqtt_config = config.mqtt
         self.connected = False
+        self.client: mqtt.Client | None = None
+        self._dispatcher: Callable[[str, Any], Any] | None = None
+        self._command_router: Dispatcher | None = None
+        self._worker: threading.Thread | None = None
+        self._stop_event = threading.Event()
+        self._publish_queue: queue.Queue[QueuedPublish] = queue.Queue()
+        self._callback_queue: queue.Queue[tuple[Any, ...]] = queue.Queue()
+        self._retained_lock = threading.Lock()
+        self._pending_retained: dict[str, tuple[Any, bool]] = {}
+        self._inflight_retained: dict[int, tuple[str, Any]] = {}
+        self._subscription_mid: int | None = None
+        self._subscription_ready = False
+        self._next_connect_time = 0.0
+        self._last_on_connect_dispatch = 0.0
 
     def subscribe(self, receiver: Callable) -> None:
         """Wrapper for allowing dispatcher to subscribe."""
         self._dispatcher = receiver
-        self._start()
+
+    def attach_dispatcher(self, dispatcher: Dispatcher) -> None:
+        """Take Dispatcher's command surface and snapshot API."""
+        self._command_router = dispatcher
+
+    def start(self) -> None:
+        """Start the MQTT worker after all receiver wiring is complete."""
+
+        if self._worker and self._worker.is_alive():
+            return
+
+        self._stop_event.clear()
+        self._start_worker()
 
     def publish(self, topic: str, payload: Any, retain: bool = False) -> None:
         """Wrapper for publishing when client is in valid state."""
+        full_topic = f"{self.mqtt_config.topic_prefix}/{topic}"
+
         if not self.connected:
-            logger.debug(f"Unable to publish to {topic}: client is not connected")
+            if retain:
+                self._queue_retained(full_topic, payload, retain)
+            else:
+                logger.debug("Unable to publish to %s: client is not connected", topic)
             return
 
-        self.client.publish(
-            f"{self.mqtt_config.topic_prefix}/{topic}",
-            payload,
-            qos=self.config.mqtt.qos,
-            retain=retain,
-        )
+        self._publish_queue.put(QueuedPublish(full_topic, payload, retain))
 
     def stop(self) -> None:
-        self.publish("available", "stopped", retain=True)
-        self.client.disconnect()
+        if self._worker is None:
+            return
+
+        if self.connected and self._subscription_ready:
+            publish_done = threading.Event()
+            self._publish_queue.put(
+                QueuedPublish(
+                    f"{self.mqtt_config.topic_prefix}/available",
+                    "stopped",
+                    True,
+                    publish_done,
+                )
+            )
+            publish_done.wait(MQTT_SHUTDOWN_FLUSH_TIMEOUT)
+
+        self._stop_event.set()
+
+        if self.client is not None:
+            try:
+                self.client.disconnect()
+            except Exception:
+                logger.debug("MQTT disconnect raised during shutdown", exc_info=True)
+
+        if self._worker.is_alive():
+            self._worker.join(MQTT_SHUTDOWN_FLUSH_TIMEOUT + MQTT_LOOP_TIMEOUT)
+
+        self._cleanup_client()
+        self._worker = None
 
     def _notifications_enabled_in_config(self) -> bool:
         """Whether notifications are configured globally or on any camera.
@@ -54,17 +128,17 @@ class MqttClient(Communicator):
             for cam in self.config.cameras.values()
         )
 
-    def _set_initial_topics(self) -> None:
-        """Set initial state topics."""
+    def _publish_retained_state(self) -> None:
+        """Publish retained MQTT state after a successful subscribe."""
         for camera_name, camera in self.config.cameras.items():
             self.publish(
                 f"{camera_name}/enabled/state",
-                "ON" if camera.enabled_in_config else "OFF",
+                "ON" if camera.enabled else "OFF",
                 retain=True,
             )
             self.publish(
                 f"{camera_name}/recordings/state",
-                "ON" if camera.record.enabled_in_config else "OFF",
+                "ON" if camera.record.enabled else "OFF",
                 retain=True,
             )
             self.publish(
@@ -74,7 +148,7 @@ class MqttClient(Communicator):
             )
             self.publish(
                 f"{camera_name}/audio/state",
-                "ON" if camera.audio.enabled_in_config else "OFF",
+                "ON" if camera.audio.enabled else "OFF",
                 retain=True,
             )
             self.publish(
@@ -89,7 +163,7 @@ class MqttClient(Communicator):
             )
             self.publish(
                 f"{camera_name}/motion/state",
-                "ON",
+                "ON" if camera.motion.enabled else "OFF",
                 retain=True,
             )
             self.publish(
@@ -99,7 +173,7 @@ class MqttClient(Communicator):
             )
             self.publish(
                 f"{camera_name}/ptz_autotracker/state",
-                "ON" if camera.onvif.autotracking.enabled_in_config else "OFF",
+                "ON" if camera.onvif.autotracking.enabled else "OFF",
                 retain=True,
             )
             self.publish(
@@ -125,7 +199,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"
                 ),
@@ -133,22 +207,22 @@ class MqttClient(Communicator):
             )
             self.publish(
                 f"{camera_name}/review_alerts/state",
-                "ON" if camera.review.alerts.enabled_in_config else "OFF",
+                "ON" if camera.review.alerts.enabled else "OFF",
                 retain=True,
             )
             self.publish(
                 f"{camera_name}/review_detections/state",
-                "ON" if camera.review.detections.enabled_in_config else "OFF",
+                "ON" if camera.review.detections.enabled else "OFF",
                 retain=True,
             )
             self.publish(
                 f"{camera_name}/object_descriptions/state",
-                "ON" if camera.objects.genai.enabled_in_config else "OFF",
+                "ON" if camera.objects.genai.enabled else "OFF",
                 retain=True,
             )
             self.publish(
                 f"{camera_name}/review_descriptions/state",
-                "ON" if camera.review.genai.enabled_in_config else "OFF",
+                "ON" if camera.review.genai.enabled else "OFF",
                 retain=True,
             )
 
@@ -189,13 +263,514 @@ class MqttClient(Communicator):
         )
         self.publish("available", "online", retain=True)
 
-    def on_mqtt_command(
-        self, client: mqtt.Client, userdata: Any, message: mqtt.MQTTMessage
-    ) -> None:
-        self._dispatcher(
-            message.topic.replace(f"{self.mqtt_config.topic_prefix}/", "", 1),
-            message.payload.decode(),
+    def _create_client(self) -> mqtt.Client:
+        """Build a fresh paho client for a single connect attempt."""
+        client = mqtt.Client(
+            callback_api_version=CallbackAPIVersion.VERSION2,
+            client_id=self.mqtt_config.client_id,
+            reconnect_on_failure=False,
         )
+        client.on_connect = self._on_connect
+        client.on_disconnect = self._on_disconnect
+        client.on_message = self._on_message
+        client.on_subscribe = self._on_subscribe
+        client.on_publish = self._on_publish
+        client.will_set(
+            self.mqtt_config.topic_prefix + "/available",
+            payload="offline",
+            qos=1,
+            retain=True,
+        )
+
+        if self.mqtt_config.tls_ca_certs is not None:
+            if (
+                self.mqtt_config.tls_client_cert is not None
+                and self.mqtt_config.tls_client_key is not None
+            ):
+                client.tls_set(
+                    self.mqtt_config.tls_ca_certs,
+                    self.mqtt_config.tls_client_cert,
+                    self.mqtt_config.tls_client_key,
+                )
+            else:
+                client.tls_set(self.mqtt_config.tls_ca_certs)
+
+        if self.mqtt_config.tls_insecure is not None:
+            client.tls_insecure_set(self.mqtt_config.tls_insecure)
+
+        if self.mqtt_config.user is not None:
+            client.username_pw_set(
+                self.mqtt_config.user,
+                password=self.mqtt_config.password,
+            )
+
+        return client
+
+    def _start_worker(self) -> None:
+        self._worker = threading.Thread(
+            target=self._worker_main, name="mqtt", daemon=True
+        )
+        self._worker.start()
+        logger.info("MQTT worker started")
+
+    def _worker_main(self) -> None:
+        """Run the worker loop.
+
+        An unexpected crash disables MQTT for this session rather than taking
+        Frigate down with it, so it has to announce itself: without the offline
+        publish, consumers keep the last retained values and see a healthy
+        Frigate that has simply stopped updating.
+        """
+        try:
+            self._mqtt_loop_worker()
+        except Exception:
+            if not self._stop_event.is_set():
+                logger.exception("MQTT worker crashed, disabling MQTT for this session")
+                self._stop_event.set()
+                self._subscription_ready = False
+                self._publish_offline_availability()
+                self.connected = False
+        finally:
+            # nothing drains the queue once the loop is gone, so release any
+            # waiter here or stop() blocks for the full flush timeout
+            self._requeue_disconnected_publishes()
+            self._cleanup_client()
+
+    def _publish_offline_availability(self) -> None:
+        """Announce that MQTT is going away after a worker crash.
+
+        _cleanup_client() disconnects cleanly, which tells the broker to
+        suppress the will, so the retained topic would otherwise stay "online".
+        """
+        if self.client is None:
+            return
+
+        try:
+            message_info = self.client.publish(
+                f"{self.mqtt_config.topic_prefix}/available",
+                "offline",
+                qos=self.config.mqtt.qos,
+                retain=True,
+            )
+
+            # pumped here rather than through _wait_for_publish() so the drain
+            # that may have just crashed is not re-entered
+            deadline = time.monotonic() + MQTT_SHUTDOWN_FLUSH_TIMEOUT
+            while not message_info.is_published() and time.monotonic() < deadline:
+                if (
+                    self.client.loop(timeout=MQTT_PUBLISH_WAIT_INTERVAL)
+                    != mqtt.MQTT_ERR_SUCCESS
+                ):
+                    break
+        except Exception:
+            logger.warning(
+                "MQTT is dormant and the broker could not be told Frigate is offline",
+                exc_info=True,
+            )
+
+    def _mqtt_loop_worker(self) -> None:
+        # The worker owns all socket I/O so reconnect, subscribe, and publish
+        # ordering stays serialized in one place.
+        while not self._stop_event.is_set():
+            if self.client is None:
+                wait_time = self._next_connect_time - time.monotonic()
+                if wait_time > 0:
+                    self._stop_event.wait(min(wait_time, MQTT_LOOP_TIMEOUT))
+                    continue
+
+                if not self._connect_client():
+                    self._next_connect_time = time.monotonic() + MQTT_RECONNECT_INTERVAL
+                    continue
+
+            assert self.client is not None
+            try:
+                result = self.client.loop(timeout=MQTT_LOOP_TIMEOUT)
+            except (OSError, mqtt.WebsocketConnectionError) as err:
+                logger.warning("MQTT loop error: %s", err)
+                self._schedule_reconnect()
+                continue
+
+            self._drain_callback_queue()
+            self._drain_publish_queue()
+
+            if self._stop_event.is_set():
+                break
+
+            if result != mqtt.MQTT_ERR_SUCCESS and self.client is not None:
+                logger.error("MQTT loop returned error code: %s", result)
+                self._schedule_reconnect()
+
+    def _connect_client(self) -> bool:
+        """Create and connect a new client instance owned by the worker thread."""
+        try:
+            self.client = self._create_client()
+            self.client.connect(self.mqtt_config.host, self.mqtt_config.port, 60)
+        except Exception as err:
+            logger.error("Unable to connect to MQTT server: %s", err)
+            self._cleanup_client()
+            return False
+
+        return True
+
+    def _cleanup_client(self) -> None:
+        """Drop session-specific state and release the current paho client."""
+        self.connected = False
+        self._subscription_ready = False
+        self._subscription_mid = None
+        self._requeue_inflight_retained()
+
+        client = self.client
+        self.client = None
+
+        if client is None:
+            return
+
+        try:
+            client.disconnect()
+        except Exception:
+            logger.debug("MQTT client cleanup raised disconnect error", exc_info=True)
+
+    def _schedule_reconnect(self) -> None:
+        """Tear down the current session and arm the next reconnect attempt."""
+        if self._stop_event.is_set():
+            return
+
+        self.connected = False
+        self._subscription_ready = False
+        self._subscription_mid = None
+        self._requeue_disconnected_publishes()
+        self._next_connect_time = time.monotonic() + MQTT_RECONNECT_INTERVAL
+        logger.info("MQTT reconnect scheduled in %.1fs", MQTT_RECONNECT_INTERVAL)
+        self._cleanup_client()
+
+    def _requeue_inflight_retained(self) -> None:
+        """Rebuffer retained publishes paho took but the broker never acked.
+
+        Dropping the client drops paho's outbound queue with it, and the session
+        is clean, so the broker will not resume delivery on the new one.
+        """
+        with self._retained_lock:
+            # mids are insertion ordered, so collapsing by topic keeps the
+            # newest value when several updates to one topic were in flight
+            latest = {
+                topic: payload for topic, payload in self._inflight_retained.values()
+            }
+            self._inflight_retained.clear()
+
+        for topic, payload in latest.items():
+            self._queue_retained(topic, payload, True, overwrite=False)
+
+    def _buffer_undelivered(
+        self, queued_publish: QueuedPublish, overwrite: bool = True
+    ) -> None:
+        """Handle a publish that never reached the broker.
+
+        Releasing the waiter matters on every path: stop() blocks on it, so a
+        broker error would otherwise stall shutdown for the full flush timeout.
+        """
+        if queued_publish.retain:
+            self._queue_retained(
+                queued_publish.topic,
+                queued_publish.payload,
+                queued_publish.retain,
+                overwrite=overwrite,
+            )
+
+        if queued_publish.done is not None:
+            queued_publish.done.set()
+
+    def _requeue_disconnected_publishes(self) -> None:
+        while True:
+            try:
+                queued_publish = self._publish_queue.get_nowait()
+            except queue.Empty:
+                break
+
+            self._buffer_undelivered(queued_publish)
+
+    def _drain_callback_queue(self) -> None:
+        # Paho callbacks only enqueue transport events; state transitions run
+        # here on the worker thread.
+        while True:
+            try:
+                event = self._callback_queue.get_nowait()
+            except queue.Empty:
+                break
+
+            event_type = event[0]
+
+            if event_type == "connect":
+                self._handle_connect_event(event[1])
+            elif event_type == "connect_failure":
+                self._handle_connect_failure(event[1])
+            elif event_type == "disconnect":
+                self._handle_disconnect_event(event[1])
+            elif event_type == "subscribed":
+                self._handle_subscribe_event(event[1], event[2])
+            elif event_type == "message":
+                self._handle_inbound_message(event[1], event[2])
+            elif event_type == "published":
+                self._handle_publish_event(event[1])
+
+    def _drain_publish_queue(self) -> None:
+        """Publish queued work only after the session is fully subscribed."""
+        if self.connected and not self._subscription_ready:
+            return
+
+        while True:
+            try:
+                queued_publish = self._publish_queue.get_nowait()
+            except queue.Empty:
+                break
+
+            if not self.connected:
+                self._buffer_undelivered(queued_publish)
+                continue
+
+            self._publish_direct(queued_publish)
+
+        self._flush_pending_retained()
+
+    def _flush_pending_retained(self) -> None:
+        """Replay the latest retained state once the broker session is ready."""
+        if not self.connected or not self._subscription_ready:
+            return
+
+        with self._retained_lock:
+            pending = list(self._pending_retained.items())
+            self._pending_retained.clear()
+
+        for topic, (payload, retain) in pending:
+            self._publish_direct(QueuedPublish(topic, payload, retain))
+
+    def _publish_direct(self, queued_publish: QueuedPublish) -> None:
+        """Publish a queued message from the worker thread's serialized context.
+
+        The waiter is released however this exits. The message is already off
+        the queue by now, so nothing else can recover it for a stop() that is
+        blocked waiting on it.
+        """
+        try:
+            if self.client is None:
+                self._buffer_undelivered(queued_publish)
+                return
+
+            try:
+                message_info = self.client.publish(
+                    queued_publish.topic,
+                    queued_publish.payload,
+                    qos=self.config.mqtt.qos,
+                    retain=queued_publish.retain,
+                )
+            except (OSError, mqtt.WebsocketConnectionError) as err:
+                logger.warning(
+                    "MQTT publish failed for %s: %s", queued_publish.topic, err
+                )
+                # a newer buffered value for this topic wins over the failed one
+                self._buffer_undelivered(queued_publish, overwrite=False)
+                self._schedule_reconnect()
+                return
+
+            if message_info.rc != mqtt.MQTT_ERR_SUCCESS:
+                logger.error(
+                    "Unable to publish to %s: mqtt error %s",
+                    queued_publish.topic,
+                    message_info.rc,
+                )
+                self._buffer_undelivered(queued_publish, overwrite=False)
+                self._schedule_reconnect()
+                return
+
+            # a successful rc only means paho accepted the message; above qos 0
+            # it is not durable until the broker acks, so keep a copy for replay
+            if queued_publish.retain and not message_info.is_published():
+                with self._retained_lock:
+                    self._inflight_retained[message_info.mid] = (
+                        queued_publish.topic,
+                        queued_publish.payload,
+                    )
+
+            if queued_publish.done is not None:
+                self._wait_for_publish(message_info)
+        finally:
+            if queued_publish.done is not None:
+                queued_publish.done.set()
+
+    def _handle_publish_event(self, mid: int) -> None:
+        """Drop the replay copy once the broker has acknowledged the message."""
+        with self._retained_lock:
+            self._inflight_retained.pop(mid, None)
+
+    def _wait_for_publish(self, message_info: mqtt.MQTTMessageInfo) -> None:
+        """Pump the loop until a shutdown-critical publish is acknowledged."""
+        deadline = time.monotonic() + MQTT_SHUTDOWN_FLUSH_TIMEOUT
+
+        while not message_info.is_published() and time.monotonic() < deadline:
+            if self.client is None:
+                return
+
+            try:
+                result = self.client.loop(timeout=MQTT_PUBLISH_WAIT_INTERVAL)
+            except (OSError, mqtt.WebsocketConnectionError) as err:
+                logger.warning("MQTT publish wait failed: %s", err)
+                self._schedule_reconnect()
+                return
+
+            self._drain_callback_queue()
+
+            if result != mqtt.MQTT_ERR_SUCCESS:
+                logger.error(
+                    "MQTT loop returned error code while waiting for publish: %s",
+                    result,
+                )
+                self._schedule_reconnect()
+                return
+
+    def _queue_retained(
+        self,
+        topic: str,
+        payload: Any,
+        retain: bool,
+        overwrite: bool = True,
+    ) -> None:
+        """Store the last retained value per topic for replay after reconnect."""
+        with self._retained_lock:
+            if overwrite or topic not in self._pending_retained:
+                self._pending_retained[topic] = (payload, retain)
+
+    def _handle_connect_event(self, reason_code: mqtt.ReasonCode) -> None:  # type: ignore[name-defined]
+        """Begin a new session by subscribing before any replay is published."""
+        if self.client is None:
+            return
+
+        self.connected = True
+        self._subscription_ready = False
+        self._subscription_mid = None
+        logger.debug("MQTT connected")
+
+        try:
+            result, mid = self.client.subscribe(
+                f"{self.mqtt_config.topic_prefix}/#",
+                qos=self.config.mqtt.qos,
+            )
+        except (OSError, mqtt.WebsocketConnectionError) as err:
+            logger.warning("MQTT subscribe failed: %s", err)
+            self._schedule_reconnect()
+            return
+
+        if result != mqtt.MQTT_ERR_SUCCESS:
+            logger.error(
+                "Unable to subscribe to MQTT command tree: mqtt error %s", result
+            )
+            self._schedule_reconnect()
+            return
+
+        self._subscription_mid = mid
+
+    def _handle_connect_failure(self, reason_code: mqtt.ReasonCode) -> None:  # type: ignore[name-defined]
+        """Record a failed connect attempt and transition into reconnect state."""
+        self.connected = False
+        logger.error(
+            "Unable to connect to MQTT server: %s", self._reason_code_name(reason_code)
+        )
+        self._schedule_reconnect()
+
+    def _handle_disconnect_event(self, reason_code: mqtt.ReasonCode) -> None:  # type: ignore[name-defined]
+        """Handle broker disconnects idempotently from the worker thread."""
+        if not self.connected:
+            return
+
+        self.connected = False
+        self._subscription_ready = False
+        self._subscription_mid = None
+
+        if self._stop_event.is_set():
+            logger.debug("MQTT disconnected")
+            self._cleanup_client()
+            return
+
+        logger.error("MQTT disconnected: %s", self._reason_code_name(reason_code))
+        self._schedule_reconnect()
+
+    def _handle_subscribe_event(
+        self,
+        mid: int,
+        reason_codes: list[mqtt.ReasonCode],  # type: ignore[name-defined]
+    ) -> None:
+        """Mark the session ready after SUBACK, then replay retained/runtime state."""
+        if mid != self._subscription_mid:
+            return
+
+        if any(
+            getattr(reason_code, "is_failure", False) for reason_code in reason_codes
+        ):
+            logger.error("MQTT subscription was rejected by the broker")
+            self._schedule_reconnect()
+            return
+
+        self._subscription_ready = True
+        self._subscription_mid = None
+
+        # a bug in replay should cost a snapshot, not the MQTT session
+        try:
+            self._publish_retained_state()
+
+            if self._command_router is not None:
+                self._command_router.publish_runtime_snapshot(self.publish)
+        except Exception:
+            logger.exception("Error replaying MQTT state after subscribe")
+
+    def _handle_inbound_message(self, topic: str, payload: str) -> None:
+        """Forward supported command topics into Dispatcher semantics."""
+        if self._dispatcher is None:
+            return
+
+        if not self._is_supported_command_topic(topic):
+            return
+
+        if topic == "onConnect":
+            now = time.monotonic()
+            if now - self._last_on_connect_dispatch < MQTT_ON_CONNECT_RATE_LIMIT:
+                logger.debug("Skipping MQTT onConnect replay request due to rate limit")
+                return
+            self._last_on_connect_dispatch = now
+
+        # a raise here used to end the network thread and take MQTT down
+        try:
+            self._dispatcher(topic, payload)
+        except Exception:
+            logger.exception("Error handling MQTT command topic %s", topic)
+
+    def _is_supported_command_topic(self, topic: str) -> bool:
+        """Filter the wildcard subscription down to Dispatcher's command surface.
+
+        Load-bearing rather than an optimization: the broker echoes Frigate's own
+        publishes back through frigate/#, and Dispatcher republishes topics it
+        does not recognize, so forwarding unfiltered would loop.
+        """
+        if self._command_router is None:
+            return False
+
+        # mirrors the gate on the state topic in _publish_retained_state()
+        if topic == "notifications/set" and not self._notifications_enabled_in_config():
+            return False
+
+        return self._command_router.is_command_topic(topic)
+
+    def _strip_topic_prefix(self, topic: str) -> str:
+        return topic.replace(f"{self.mqtt_config.topic_prefix}/", "", 1)
+
+    def _is_success_reason_code(self, reason_code: mqtt.ReasonCode) -> bool:  # type: ignore[name-defined]
+        if hasattr(reason_code, "is_failure"):
+            return not bool(reason_code.is_failure)
+
+        return bool(reason_code == 0)
+
+    def _reason_code_name(self, reason_code: mqtt.ReasonCode) -> str:  # type: ignore[name-defined]
+        if hasattr(reason_code, "getName"):
+            return str(reason_code.getName())
+
+        return str(reason_code)
 
     def _on_connect(
         self,
@@ -205,29 +780,11 @@ class MqttClient(Communicator):
         reason_code: mqtt.ReasonCode,  # type: ignore[name-defined]
         properties: Any,
     ) -> None:
-        """Mqtt connection callback."""
-        threading.current_thread().name = "mqtt"
-        if reason_code != 0:
-            if reason_code == "Server unavailable":
-                logger.error(
-                    "Unable to connect to MQTT server: MQTT Server unavailable"
-                )
-            elif reason_code == "Bad user name or password":
-                logger.error(
-                    "Unable to connect to MQTT server: MQTT Bad username or password"
-                )
-            elif reason_code == "Not authorized":
-                logger.error("Unable to connect to MQTT server: MQTT Not authorized")
-            else:
-                logger.error(
-                    "Unable to connect to MQTT server: Connection refused. Error code: %s",
-                    reason_code.getName(),
-                )
-
-        self.connected = True
-        logger.debug("MQTT connected")
-        client.subscribe(f"{self.mqtt_config.topic_prefix}/#", qos=self.config.mqtt.qos)
-        self._set_initial_topics()
+        """Handle broker connect notifications from paho."""
+        if self._is_success_reason_code(reason_code):
+            self._callback_queue.put(("connect", reason_code))
+        else:
+            self._callback_queue.put(("connect_failure", reason_code))
 
     def _on_disconnect(
         self,
@@ -237,126 +794,63 @@ class MqttClient(Communicator):
         reason_code: mqtt.ReasonCode,  # type: ignore[name-defined]
         properties: Any,
     ) -> None:
-        """Mqtt disconnection callback."""
-        self.connected = False
-        logger.error("MQTT disconnected")
+        """Handle broker disconnect notifications from paho."""
+        self._callback_queue.put(("disconnect", reason_code))
 
-    def _start(self) -> None:
-        """Start mqtt client."""
-        self.client = mqtt.Client(
-            callback_api_version=CallbackAPIVersion.VERSION2,
-            client_id=self.mqtt_config.client_id,
-        )
-        self.client.on_connect = self._on_connect
-        self.client.on_disconnect = self._on_disconnect
-        self.client.will_set(
-            self.mqtt_config.topic_prefix + "/available",
-            payload="offline",
-            qos=1,
-            retain=True,
-        )
+    def _on_subscribe(
+        self,
+        client: mqtt.Client,
+        userdata: Any,
+        mid: int,
+        reason_codes: list[mqtt.ReasonCode],  # type: ignore[name-defined]
+        properties: Any,
+    ) -> None:
+        """Handle subscribe acknowledgements from paho."""
+        self._callback_queue.put(("subscribed", mid, reason_codes))
 
-        # register callbacks
-        callback_types = [
-            "enabled",
-            "recordings",
-            "snapshots",
-            "detect",
-            "audio",
-            "audio_transcription",
-            "motion",
-            "improve_contrast",
-            "ptz_autotracker",
-            "motion_threshold",
-            "motion_contour_area",
-            "birdseye",
-            "birdseye_mode",
-            "review_alerts",
-            "review_detections",
-            "object_descriptions",
-            "review_descriptions",
-            "notifications",
-        ]
+    def _on_publish(
+        self,
+        client: mqtt.Client,
+        userdata: Any,
+        mid: int,
+        reason_code: mqtt.ReasonCode,  # type: ignore[name-defined]
+        properties: Any,
+    ) -> None:
+        """Handle publish acknowledgements from paho.
 
-        for name in self.config.cameras.keys():
-            for callback in callback_types:
-                self.client.message_callback_add(
-                    f"{self.mqtt_config.topic_prefix}/{name}/{callback}/set",
-                    self.on_mqtt_command,
-                )
+        Only tracked retained messages need an event. At the default qos 0
+        nothing is tracked, so this stays off the hot publish path.
+        """
+        with self._retained_lock:
+            if mid not in self._inflight_retained:
+                return
 
-            # notifications suspend doesn't follow the /set topic pattern
-            self.client.message_callback_add(
-                f"{self.mqtt_config.topic_prefix}/{name}/notifications/suspend",
-                self.on_mqtt_command,
-            )
+        self._callback_queue.put(("published", mid))
 
-            if self.config.cameras[name].onvif.host:
-                self.client.message_callback_add(
-                    f"{self.mqtt_config.topic_prefix}/{name}/ptz",
-                    self.on_mqtt_command,
-                )
+    def _on_message(
+        self,
+        client: mqtt.Client,
+        userdata: Any,
+        message: mqtt.MQTTMessage,
+    ) -> None:
+        """Queue inbound MQTT messages for processing in the worker loop."""
+        topic = self._strip_topic_prefix(message.topic)
 
-            for mask_name in self.config.cameras[name].motion.mask.keys():
-                self.client.message_callback_add(
-                    f"{self.mqtt_config.topic_prefix}/{name}/motion_mask/{mask_name}/set",
-                    self.on_mqtt_command,
-                )
-
-            for mask_name in self.config.cameras[name].objects.mask.keys():
-                self.client.message_callback_add(
-                    f"{self.mqtt_config.topic_prefix}/{name}/object_mask/{mask_name}/set",
-                    self.on_mqtt_command,
-                )
-
-            for zone_name in self.config.cameras[name].zones.keys():
-                self.client.message_callback_add(
-                    f"{self.mqtt_config.topic_prefix}/{name}/zone/{zone_name}/set",
-                    self.on_mqtt_command,
-                )
-
-        if self._notifications_enabled_in_config():
-            self.client.message_callback_add(
-                f"{self.mqtt_config.topic_prefix}/notifications/set",
-                self.on_mqtt_command,
-            )
-
-        self.client.message_callback_add(
-            f"{self.mqtt_config.topic_prefix}/profile/set",
-            self.on_mqtt_command,
-        )
-
-        self.client.message_callback_add(
-            f"{self.mqtt_config.topic_prefix}/onConnect", self.on_mqtt_command
-        )
-
-        self.client.message_callback_add(
-            f"{self.mqtt_config.topic_prefix}/restart", self.on_mqtt_command
-        )
-
-        if self.mqtt_config.tls_ca_certs is not None:
-            if (
-                self.mqtt_config.tls_client_cert is not None
-                and self.mqtt_config.tls_client_key is not None
-            ):
-                self.client.tls_set(
-                    self.mqtt_config.tls_ca_certs,
-                    self.mqtt_config.tls_client_cert,
-                    self.mqtt_config.tls_client_key,
-                )
-            else:
-                self.client.tls_set(self.mqtt_config.tls_ca_certs)
-        if self.mqtt_config.tls_insecure is not None:
-            self.client.tls_insecure_set(self.mqtt_config.tls_insecure)
-        if self.mqtt_config.user is not None:
-            self.client.username_pw_set(
-                self.mqtt_config.user, password=self.mqtt_config.password
-            )
-        try:
-            # https://stackoverflow.com/a/55390477
-            # with connect_async, retries are handled automatically
-            self.client.connect_async(self.mqtt_config.host, self.mqtt_config.port, 60)
-            self.client.loop_start()
-        except Exception as e:
-            logger.error(f"Unable to connect to MQTT server: {e}")
+        # Ignore everything outside Frigate's command surface before decoding or
+        # dispatching into the rest of the app.
+        if not self._is_supported_command_topic(topic):
             return
+
+        try:
+            payload = message.payload.decode()
+        except UnicodeDecodeError:
+            logger.debug("Ignoring non-UTF-8 MQTT payload for topic %s", topic)
+            return
+
+        self._callback_queue.put(
+            (
+                "message",
+                topic,
+                payload,
+            )
+        )

frigate/comms/webpush.py

@@ -63,14 +63,8 @@ class WebPushClient(Communicator):
         self.last_notification_time: float = 0
         self.user_cameras: dict[str, set[str]] = {}
         self.notification_queue: queue.Queue[PushNotification] = queue.Queue()
-        self.notification_thread = threading.Thread(
-            target=self._process_notifications, daemon=True
-        )
-        self.notification_thread.start()
-        self.suspension_thread = threading.Thread(
-            target=self._process_suspensions, daemon=True
-        )
-        self.suspension_thread.start()
+        self.notification_thread: threading.Thread | None = None
+        self.suspension_thread: threading.Thread | None = None
 
         if not self.config.notifications.email:
             logger.warning("Email must be provided for push notifications to be sent.")
@@ -97,6 +91,16 @@ class WebPushClient(Communicator):
         """Wrapper for allowing dispatcher to subscribe."""
         pass
 
+    def start(self) -> None:
+        self.notification_thread = threading.Thread(
+            target=self._process_notifications, daemon=True
+        )
+        self.notification_thread.start()
+        self.suspension_thread = threading.Thread(
+            target=self._process_suspensions, daemon=True
+        )
+        self.suspension_thread.start()
+
     def check_registrations(self) -> None:
         # check for valid claim or create new one
         now = datetime.datetime.now().timestamp()
@@ -216,7 +220,9 @@ class WebPushClient(Communicator):
         if topic == "reviews":
             decoded = json.loads(payload)
             camera = decoded["before"]["camera"]
-            if not self.config.cameras[camera].notifications.enabled:
+            camera_config = self.config.cameras.get(camera)
+
+            if camera_config is None or not camera_config.notifications.enabled:
                 return
             if self.is_camera_suspended(camera):
                 logger.debug(f"Notifications for {camera} are currently suspended.")
@@ -230,13 +236,14 @@ class WebPushClient(Communicator):
 
             # ensure notifications are enabled and the specific trigger has
             # notification action enabled
+            camera_config = self.config.cameras.get(camera)
+
             if (
-                not self.config.cameras[camera].notifications.enabled
-                or name not in self.config.cameras[camera].semantic_search.triggers
+                camera_config is None
+                or not camera_config.notifications.enabled
+                or name not in camera_config.semantic_search.triggers
                 or "notification"
-                not in self.config.cameras[camera]
-                .semantic_search.triggers[name]
-                .actions
+                not in camera_config.semantic_search.triggers[name].actions
             ):
                 return
 
@@ -247,7 +254,9 @@ class WebPushClient(Communicator):
         elif topic == "camera_monitoring":
             decoded = json.loads(payload)
             camera = decoded["camera"]
-            if not self.config.cameras[camera].notifications.enabled:
+            camera_config = self.config.cameras.get(camera)
+
+            if camera_config is None or not camera_config.notifications.enabled:
                 return
             if self.is_camera_suspended(camera):
                 logger.debug(f"Notifications for {camera} are currently suspended.")
@@ -598,4 +607,5 @@ class WebPushClient(Communicator):
 
     def stop(self) -> None:
         logger.info("Closing notification queue")
-        self.notification_thread.join()
+        if self.notification_thread is not None:
+            self.notification_thread.join()

frigate/comms/ws.py

@@ -466,7 +466,6 @@ class WebSocketClient(Communicator):
 
     def subscribe(self, receiver: Callable) -> None:
         self._dispatcher = receiver
-        self.start()
 
     def start(self) -> None:
         """Start the websocket client."""

frigate/config/camera/birdseye.py

@@ -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(

frigate/config/config.py

@@ -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)

frigate/config/profile_manager.py

@@ -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")],

frigate/data_processing/post/audio_transcription.py

@@ -83,6 +83,10 @@ class AudioTranscriptionPostProcessor(PostProcessorApi):
         """
         event_id = data["event_id"]
         camera_name = data["camera"]
+        camera_config = self.config.cameras.get(camera_name)
+
+        if camera_config is None:
+            return
 
         if data_type == PostProcessDataEnum.recording:
             start_ts = data["frame_time"]
@@ -104,7 +108,7 @@ class AudioTranscriptionPostProcessor(PostProcessorApi):
 
         try:
             audio_data = get_audio_from_recording(
-                self.config.cameras[camera_name].ffmpeg,
+                camera_config.ffmpeg,
                 camera_name,
                 start_ts,
                 end_ts,

frigate/data_processing/post/object_descriptions.py

@@ -151,7 +151,12 @@ class ObjectDescriptionProcessor(PostProcessorApi):
             logger.error(f"Event {event_id} not found for description regeneration")
             return
 
-        camera_config = self.config.cameras[str(event.camera)]
+        camera_config = self.config.cameras.get(str(event.camera))
+
+        if camera_config is None:
+            logger.error("Camera %s no longer exists", event.camera)
+            return
+
         if not camera_config.objects.genai.enabled and not force:
             logger.error(f"GenAI not enabled for camera {event.camera}")
             return

frigate/data_processing/post/review_descriptions.py

@@ -137,7 +137,10 @@ class ReviewDescriptionProcessor(PostProcessorApi):
             return
 
         camera = data["after"]["camera"]
-        camera_config = self.config.cameras[camera]
+        camera_config = self.config.cameras.get(camera)
+
+        if camera_config is None:
+            return
 
         if not camera_config.review.genai.enabled:
             return

frigate/embeddings/maintainer.py

@@ -609,6 +609,18 @@ class EmbeddingMaintainer(threading.Thread):
                 # Embed the thumbnail
                 self._embed_thumbnail(event_id, thumbnail)
 
+            # every post processor below reads config.cameras[camera], but
+            # tracked_events still has to be released or the thumbnails held
+            # for this event leak, same as the two exits above
+            if camera not in self.config.cameras:
+                logger.debug("Skipping post processing for removed camera %s", camera)
+
+                for processor in self.post_processors:
+                    if isinstance(processor, ObjectDescriptionProcessor):
+                        processor.cleanup_event(event_id)
+
+                continue
+
             # call any defined post processors
             for processor in self.post_processors:
                 if isinstance(processor, LicensePlatePostProcessor):
@@ -666,11 +678,18 @@ class EmbeddingMaintainer(threading.Thread):
         to_remove = []
 
         for id, data in self.detected_license_plates.items():
+            camera_config = self.config.cameras.get(data["camera"])
+
+            if camera_config is None:
+                # camera was removed, drop the entry rather than expiring it
+                to_remove.append(id)
+                continue
+
             last_seen = data.get("last_seen", 0)
             if not last_seen:
                 continue
 
-            if now - last_seen > self.config.cameras[data["camera"]].lpr.expire_time:
+            if now - last_seen > camera_config.lpr.expire_time:
                 to_remove.append(id)
         for id in to_remove:
             self.event_metadata_publisher.publish(

frigate/genai/prompts.py

@@ -262,6 +262,10 @@ def get_tool_definitions(
     `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.
+
+    Descriptions here stay mechanical: which tool to reach for, and how the
+    filters relate to each other, is stated once in the system prompt so the
+    guidance is not paid for twice on every request.
     """
     search_objects_properties: dict[str, Any] = {
         "camera": {
@@ -270,26 +274,13 @@ def get_tool_definitions(
         },
         "label": {
             "type": "string",
-            "description": (
-                "Generic object class to filter by — one of the tracked detector "
-                "labels such as 'person', 'package', 'car', 'dog', 'bird'. Use "
-                "this for broad queries like 'show me all cars today'. Combine "
-                "with semantic_query when the user also describes appearance or "
-                "behavior (e.g. label='person', semantic_query='riding a lawn "
-                "mower')."
-            ),
+            "description": "Tracked object class to filter by.",
         },
         "sub_label": {
             "type": "string",
             "description": (
-                "Filter by a DISCRETE NAMED entity recognized in the detection. "
-                "Use this for: a known person's name ('John'), a delivery "
-                "company ('Amazon', 'UPS'), a recognized animal species or "
-                "breed ('blue jay', 'cardinal', 'golden retriever'), or a "
-                "license plate string. When filtering by a specific name, set "
-                "only sub_label and leave label unset. Do NOT use sub_label "
-                "for descriptions of appearance, clothing, or actions — those "
-                "belong in semantic_query."
+                "Name recognized in the detection: a person, delivery company, "
+                "animal species or breed, or license plate."
             ),
         },
         "after": {
@@ -313,20 +304,11 @@ def get_tool_definitions(
     }
 
     if attribute_classifications:
-        model_outline = "; ".join(
-            f"{m['name']} (applies to {', '.join(m['objects']) or 'any object'})"
-            for m in attribute_classifications
-        )
         search_objects_properties["attribute"] = {
             "type": "string",
             "description": (
-                "Filter by a classification attribute label produced by a "
-                "configured attribute classification model. Use this INSTEAD "
-                "of semantic_query when the user's request matches one of "
-                "these classifications. Configured models: "
-                f"{model_outline}. "
-                "Set the value to the attribute label that matches the user's "
-                "phrasing (case-sensitive)."
+                "Attribute label produced by a configured classification model "
+                "(case-sensitive)."
             ),
         }
 
@@ -334,29 +316,12 @@ def get_tool_definitions(
         search_objects_properties["semantic_query"] = {
             "type": "string",
             "description": (
-                "Optional natural-language description of a PHYSICAL "
-                "CHARACTERISTIC, APPEARANCE, or ACTIVITY the user mentioned, "
-                "used to semantically narrow results. Only set this when the "
-                "user describes something beyond what label and sub_label can "
-                "express on their own.\n"
-                "USE for descriptive phrases like: 'riding a lawn mower', "
-                "'wearing a red jacket', 'carrying a package', 'walking a "
-                "dog', 'on a bicycle', 'holding an umbrella'.\n"
-                "DO NOT USE for:\n"
-                "- specific named people, pets, or delivery companies → use sub_label\n"
-                "- animal species or breed names like 'blue jay', 'cardinal', "
-                "'golden retriever' → use sub_label\n"
-                "- license plate strings → use sub_label\n"
-                "- generic object queries like 'all cars today' or 'every "
-                "person' → use label alone with no semantic_query\n"
-                "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')."
+                "Description of an appearance or activity, used to semantically "
+                "narrow results."
                 + (
-                    " 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."
+                    " The configured embeddings model only understands English, so "
+                    "always write this in English, translating the user's "
+                    "description if they phrased it in another language."
                     if embeddings_language == "english"
                     else ""
                 )
@@ -364,26 +329,10 @@ def get_tool_definitions(
         }
 
     search_objects_description = (
-        "Search the historical record of detected objects in Frigate. "
-        "Use this ONLY for questions about the PAST — e.g. 'did anyone come by today?', "
-        "'when was the last car?', 'show me detections from yesterday'. "
-        "Do NOT use this for monitoring or alerting requests about future events — "
-        "use start_camera_watch instead for those. "
-        "An 'object' in Frigate represents a tracked detection (e.g., a person, package, car).\n\n"
-        "Choose filters based on what the user is asking for:\n"
-        "- Generic class query ('show me all cars today'): set `label` only.\n"
-        "- Specific NAMED entity (known person, delivery company, animal "
-        "species/breed like 'blue jay' or 'golden retriever', license "
-        "plate): set `sub_label` only and leave `label` unset.\n"
+        "Search the historical record of tracked detections. Use this ONLY for "
+        "questions about the PAST, e.g. 'did anyone come by today?', 'when was the "
+        "last car?'. For alerting on future events use start_camera_watch instead."
     )
-    if semantic_search_enabled:
-        search_objects_description += (
-            "- Physical CHARACTERISTIC, APPEARANCE, or ACTIVITY that is not a "
-            "discrete name ('person riding a lawn mower', 'someone in a red "
-            "jacket', 'person carrying a package'): set `semantic_query` with "
-            "the descriptive phrase, optionally alongside `label` for the "
-            "object class. Do NOT put descriptive phrases in sub_label."
-        )
 
     return [
         {
@@ -398,20 +347,30 @@ def get_tool_definitions(
                 "required": [],
             },
         },
+        {
+            "type": "function",
+            "function": {
+                "name": "get_categorized_object_names",
+                "description": (
+                    "Every name that can be attached as a sub_label, grouped by object "
+                    "type: recognized faces, named license plates, classification "
+                    "categories, and delivery logos. Takes no arguments and always "
+                    "returns the complete map."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+            },
+        },
         {
             "type": "function",
             "function": {
                 "name": "find_similar_objects",
                 "description": (
-                    "Find tracked objects that are visually and semantically similar "
-                    "to a specific past event. Use this when the user references a "
-                    "particular object they have seen and wants to find other "
-                    "sightings of the same or similar one ('that green car', 'the "
-                    "person in the red jacket', 'the package that was delivered'). "
-                    "Prefer this over search_objects whenever the user's intent is "
-                    "'find more like this specific one.' Use search_objects first "
-                    "only if you need to locate the anchor event. Requires semantic "
-                    "search to be enabled."
+                    "Find tracked objects visually and semantically similar to a "
+                    "specific past event. Requires semantic search to be enabled."
                 ),
                 "parameters": {
                     "type": "object",
@@ -473,9 +432,8 @@ def get_tool_definitions(
             "function": {
                 "name": "set_camera_state",
                 "description": (
-                    "Change a camera's feature state (e.g., turn detection on/off, enable/disable recordings). "
-                    "Use camera='*' to apply to all cameras at once. "
-                    "Only call this tool when the user explicitly asks to change a camera setting. "
+                    "Change a camera's feature state, e.g. turn detection on or off. "
+                    "Only call this when the user explicitly asks to change a setting. "
                     "Requires admin privileges."
                 ),
                 "parameters": {
@@ -510,14 +468,14 @@ 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='*')."
                             ),
                         },
                         "value": {
                             "type": "string",
-                            "description": "The value to set. ON or OFF for toggles, a number for thresholds, a profile name or 'none' for profile.",
+                            "description": "The value to set, as accepted by the chosen feature.",
                         },
                     },
                     "required": ["camera", "feature", "value"],
@@ -529,11 +487,9 @@ def get_tool_definitions(
             "function": {
                 "name": "get_live_context",
                 "description": (
-                    "Get the current live image and detection information for a single camera: objects being tracked, "
-                    "zones, timestamps. Use this to understand what is visible in the live view. "
-                    "Call this when answering questions about what is happening right now on a specific camera. "
-                    "Operates on one camera at a time; call the tool again for each additional camera. "
-                    "Wildcards and empty values are not accepted."
+                    "Current live image and detections (tracked objects, zones, "
+                    "timestamps) for one camera. Use this for questions about what is "
+                    "happening right now. Call it again for each additional camera."
                 ),
                 "parameters": {
                     "type": "object",
@@ -541,8 +497,8 @@ def get_tool_definitions(
                         "camera": {
                             "type": "string",
                             "description": (
-                                "Exact name of a single camera to get live context for. "
-                                "Wildcards (e.g. '*', 'all') and empty strings are not accepted."
+                                "Exact name of a single camera. Wildcards (e.g. '*', "
+                                "'all') and empty strings are not accepted."
                             ),
                         },
                     },
@@ -555,10 +511,9 @@ def get_tool_definitions(
             "function": {
                 "name": "start_camera_watch",
                 "description": (
-                    "Start a continuous VLM watch job that monitors a camera and sends a notification "
-                    "when a specified condition is met. Use this when the user wants to be alerted about "
-                    "a future event, e.g. 'tell me when guests arrive' or 'notify me when the package is picked up'. "
-                    "Only one watch job can run at a time. Returns a job ID."
+                    "Start a continuous watch job that monitors a camera and notifies "
+                    "the user when a condition is met, e.g. 'tell me when guests "
+                    "arrive'. Only one watch job can run at a time. Returns a job ID."
                 ),
                 "parameters": {
                     "type": "object",
@@ -598,10 +553,7 @@ def get_tool_definitions(
             "type": "function",
             "function": {
                 "name": "stop_camera_watch",
-                "description": (
-                    "Cancel the currently running VLM watch job. Use this when the user wants to "
-                    "stop a previously started watch, e.g. 'stop watching the front door'."
-                ),
+                "description": "Cancel the currently running watch job.",
                 "parameters": {
                     "type": "object",
                     "properties": {},
@@ -614,11 +566,9 @@ def get_tool_definitions(
             "function": {
                 "name": "get_profile_status",
                 "description": (
-                    "Get the current profile status including the active profile and "
-                    "timestamps of when each profile was last activated. Use this to "
-                    "determine time periods for recap requests — e.g. when the user asks "
-                    "'what happened while I was away?', call this first to find the relevant "
-                    "time window based on profile activation history."
+                    "Get the active profile and when each profile was last activated. "
+                    "Call this before get_recap to derive the time window for requests "
+                    "like 'what happened while I was away?'."
                 ),
                 "parameters": {
                     "type": "object",
@@ -632,11 +582,9 @@ def get_tool_definitions(
             "function": {
                 "name": "get_recap",
                 "description": (
-                    "Get a recap of all activity (alerts and detections) for a given time period. "
-                    "Use this after calling get_profile_status to retrieve what happened during "
-                    "a specific window — e.g. 'what happened while I was away?'. Returns a "
-                    "chronological list of activity with camera, objects, zones, and GenAI-generated "
-                    "descriptions when available. Summarize the results for the user."
+                    "Get all activity (alerts and detections) for a time period, as a "
+                    "chronological list with camera, objects, zones, and descriptions "
+                    "when available. Summarize the results for the user."
                 ),
                 "parameters": {
                     "type": "object",
@@ -723,14 +671,13 @@ def build_chat_system_prompt(
         )
         speed_units_section = f"\n\nReport object speeds to the user in {speed_unit}."
 
-    semantic_search_section = ""
+    filter_routing_section = (
+        "\n\nWhen routing a search_objects call, pick filters by the shape of the user's request:\n"
+        "- Generic class ('show me all cars today'): set `label` only.\n"
+        "- Specific named entity — a known person ('John'), delivery company ('Amazon'), animal species/breed ('blue jay', 'golden retriever'), or license plate: set `sub_label` only and leave `label` unset. Call get_categorized_object_names first and use the exact spelling it returns; a guessed spelling matches nothing. If the name is absent, say it is not configured rather than searching for it."
+    )
     if semantic_search_enabled:
-        semantic_search_section = (
-            "\n\nWhen routing a search_objects call, pick filters by the shape of the user's request:\n"
-            "- Generic class ('show me all cars today'): set `label` only.\n"
-            "- Specific named entity — a known person ('John'), delivery company ('Amazon'), animal species/breed ('blue jay', 'cardinal', 'golden retriever'), or license plate: set `sub_label` only and leave `label` unset.\n"
-            "- Physical characteristic, appearance, or activity that is NOT a discrete name ('find me people riding a lawn mower', 'someone in a red jacket', 'a person carrying a package'): set `semantic_query` with the descriptive phrase, optionally combined with `label` for the object class. Never put descriptive phrases in `sub_label`."
-        )
+        filter_routing_section += "\n- Physical characteristic, appearance, or activity that is NOT a discrete name ('riding a lawn mower', 'someone in a red jacket'): set `semantic_query` with the descriptive phrase, optionally combined with `label`. Never put descriptive phrases in `sub_label`."
 
     attribute_classification_section = ""
     if attribute_classifications:
@@ -739,9 +686,9 @@ def build_chat_system_prompt(
             for m in attribute_classifications
         )
         attribute_classification_section = (
-            "\n\nAttribute classification models are configured for the following object types:\n"
+            "\n\nConfigured attribute classification models:\n"
             f"{model_lines}\n"
-            "When the user's request matches one of these classifications, set the search_objects `attribute` field to the matching label rather than using `semantic_query`. Reserve `semantic_query` for descriptive phrases that fall outside the configured attribute labels."
+            "When the user's request matches one of these classifications, set the search_objects `attribute` field to the matching label (case-sensitive) rather than using `semantic_query`. Reserve `semantic_query` for descriptive phrases outside the configured attribute labels."
         )
 
     return f"""You are a helpful assistant for Frigate, a security camera NVR system. You help users answer questions about their cameras, detected objects, and events.
@@ -750,9 +697,6 @@ Current server local date and time: {current_date_str} at {current_time_str}
 
 Do not start your response with phrases like "I will check...", "Let me see...", or "Let me look...". Answer directly.
 
-Always present times to the user in the server's local timezone. When tool results include start_time_local and end_time_local, use those exact strings when listing or describing detection times—do not convert or invent timestamps. Do not use UTC or ISO format with Z for the user-facing answer unless the tool result only provides Unix timestamps without local time fields.
-When users ask about "today", "yesterday", "this week", etc., use the current date above as reference.
-When searching for objects or events, use ISO 8601 format for dates (e.g., {current_date_str}T00:00:00Z for the start of today).
-Always be accurate with time calculations based on the current date provided.
+Always present times in the server's local timezone. When tool results include start_time_local and end_time_local, quote those strings exactly; never convert or invent timestamps, and fall back to UTC or ISO format only when a result has no local time fields. Resolve relative dates like "today" or "this week" against the current date above, and pass dates to tools in ISO 8601 (e.g. {current_date_str}T00:00:00Z for the start of today).
 
-When a user refers to a specific object they have seen or describe with identifying details ("that green car", "the person in the red jacket", "a package left today"), prefer the find_similar_objects tool over search_objects. Use search_objects first only to locate the anchor event, then pass its id to find_similar_objects. For generic queries like "show me all cars today", keep using search_objects. If a user message begins with [attached_event:<id>], treat that event id as the anchor for any similarity or "tell me more" request in the same message and call find_similar_objects with that id.{semantic_search_section}{attribute_classification_section}{cameras_section}{speed_units_section}"""
+When the user refers to a specific object they have seen ("that green car", "the person in the red jacket", "a package left today"), prefer find_similar_objects over search_objects, using search_objects only to locate the anchor event and passing its id along. Keep search_objects for generic queries like "show me all cars today". If a user message begins with [attached_event:<id>], treat that id as the anchor for any similarity or "tell me more" request in the same message.{filter_routing_section}{attribute_classification_section}{cameras_section}{speed_units_section}"""

frigate/output/birdseye.py

@@ -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."""
@@ -604,112 +612,92 @@ class BirdsEyeFrameManager:
     ) -> list[list[Any]] | None:
         """Calculate the optimal layout for 2+ cameras."""
 
-        def map_layout(
-            camera_layout: list[list[Any]], row_height: int
-        ) -> tuple[int, int, list[list[Any]] | None]:
-            """Map the calculated layout."""
-            candidate_layout = []
-            starting_x = 0
-            x = 0
-            max_width = 0
-            y = 0
+        def find_available_x(
+            current_x: int,
+            width: int,
+            reserved_ranges: list[tuple[int, int]],
+            max_width: int,
+        ) -> int | None:
+            """Find the first horizontal slot that does not collide with reservations."""
+            x = current_x
 
-            for row in camera_layout:
-                final_row = []
-                max_width = max(max_width, x)
-                x = starting_x
-                for cameras in row:
-                    camera_dims = self.cameras[cameras[0]]["dimensions"].copy()
-                    camera_aspect = cameras[1]
+            for reserved_start, reserved_end in sorted(reserved_ranges):
+                if x >= reserved_end:
+                    continue
 
-                    if camera_dims[1] > camera_dims[0]:
-                        scaled_height = int(row_height * 2)
-                        scaled_width = int(scaled_height * camera_aspect)
-                        starting_x = scaled_width
-                    else:
-                        scaled_height = row_height
-                        scaled_width = int(scaled_height * camera_aspect)
+                if x + width <= reserved_start:
+                    return x
 
-                    # layout is too large
-                    if (
-                        x + scaled_width > self.canvas.width
-                        or y + scaled_height > self.canvas.height
-                    ):
-                        return x + scaled_width, y + scaled_height, None
+                x = max(x, reserved_end)
 
-                    final_row.append((cameras[0], (x, y, scaled_width, scaled_height)))
-                    x += scaled_width
+            if x + width <= max_width:
+                return x
 
-                y += row_height
-                candidate_layout.append(final_row)
-
-            if max_width == 0:
-                max_width = x
-
-            return max_width, y, candidate_layout
-
-        canvas_aspect_x, canvas_aspect_y = self.canvas.get_aspect(coefficient)
-        camera_layout: list[list[Any]] = []
-        camera_layout.append([])
-        starting_x = 0
-        x = starting_x
-        y = 0
-        y_i = 0
-        max_y = 0
-        for camera in cameras_to_add:
-            camera_dims = self.cameras[camera]["dimensions"].copy()
-            camera_aspect_x, camera_aspect_y = self.canvas.get_camera_aspect(
-                camera, camera_dims[0], camera_dims[1]
-            )
-
-            if camera_dims[1] > camera_dims[0]:
-                portrait = True
-            else:
-                portrait = False
-
-            if (x + camera_aspect_x) <= canvas_aspect_x:
-                # insert if camera can fit on current row
-                camera_layout[y_i].append(
-                    (
-                        camera,
-                        camera_aspect_x / camera_aspect_y,
-                    )
-                )
-
-                if portrait:
-                    starting_x = camera_aspect_x
-                else:
-                    max_y = max(
-                        max_y,
-                        camera_aspect_y,
-                    )
-
-                x += camera_aspect_x
-            else:
-                # move on to the next row and insert
-                y += max_y
-                y_i += 1
-                camera_layout.append([])
-                x = starting_x
-
-                if x + camera_aspect_x > canvas_aspect_x:
-                    return None
-
-                camera_layout[y_i].append(
-                    (
-                        camera,
-                        camera_aspect_x / camera_aspect_y,
-                    )
-                )
-                x += camera_aspect_x
-
-        if y + max_y > canvas_aspect_y:
             return None
 
-        row_height = int(self.canvas.height / coefficient)
-        total_width, total_height, standard_candidate_layout = map_layout(
-            camera_layout, row_height
-        )
+        def map_layout(row_height: int) -> tuple[int, int, list[list[Any]] | None]:
+            """Lay out cameras row by row while reserving portrait spans for the next row."""
+            candidate_layout: list[list[Any]] = []
+            reserved_ranges: dict[int, list[tuple[int, int]]] = {}
+            current_row: list[Any] = []
+            row_index = 0
+            row_y = 0
+            row_x = 0
+            max_width = 0
+            max_height = 0
+
+            for camera in cameras_to_add:
+                camera_dims = self.cameras[camera]["dimensions"].copy()
+                camera_aspect_x, camera_aspect_y = self.canvas.get_camera_aspect(
+                    camera, camera_dims[0], camera_dims[1]
+                )
+                portrait = camera_dims[1] > camera_dims[0]
+                scaled_height = row_height * 2 if portrait else row_height
+                scaled_width = int(scaled_height * (camera_aspect_x / camera_aspect_y))
+
+                while True:
+                    x = find_available_x(
+                        row_x,
+                        scaled_width,
+                        reserved_ranges.get(row_index, []),
+                        self.canvas.width,
+                    )
+
+                    if x is not None and row_y + scaled_height <= self.canvas.height:
+                        current_row.append(
+                            (camera, (x, row_y, scaled_width, scaled_height))
+                        )
+                        row_x = x + scaled_width
+                        max_width = max(max_width, row_x)
+                        max_height = max(max_height, row_y + scaled_height)
+
+                        if portrait:
+                            reserved_ranges.setdefault(row_index + 1, []).append(
+                                (x, row_x)
+                            )
+
+                        break
+
+                    if current_row:
+                        candidate_layout.append(current_row)
+                        current_row = []
+
+                    row_index += 1
+                    row_y = row_index * row_height
+                    row_x = 0
+
+                    if row_y + scaled_height > self.canvas.height:
+                        overflow_width = max(max_width, scaled_width)
+                        overflow_height = row_y + scaled_height
+                        return overflow_width, overflow_height, None
+
+            if current_row:
+                candidate_layout.append(current_row)
+
+            return max_width, max_height, candidate_layout
+
+        row_height = max(1, int(self.canvas.height / coefficient))
+        total_width, total_height, standard_candidate_layout = map_layout(row_height)
 
         if not standard_candidate_layout:
             # if standard layout didn't work
@@ -718,9 +706,9 @@ class BirdsEyeFrameManager:
                 total_width / self.canvas.width,
                 total_height / self.canvas.height,
             )
-            row_height = int(row_height / scale_down_percent)
+            row_height = max(1, int(row_height / scale_down_percent))
             total_width, total_height, standard_candidate_layout = map_layout(
-                camera_layout, row_height
+                row_height
             )
 
             if not standard_candidate_layout:
@@ -734,8 +722,8 @@ class BirdsEyeFrameManager:
             1 / (total_width / self.canvas.width),
             1 / (total_height / self.canvas.height),
         )
-        row_height = int(row_height * scale_up_percent)
-        _, _, scaled_layout = map_layout(camera_layout, row_height)
+        row_height = max(1, int(row_height * scale_up_percent))
+        _, _, scaled_layout = map_layout(row_height)
 
         if scaled_layout:
             return scaled_layout
@@ -745,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]:
@@ -760,22 +747,29 @@ class BirdsEyeFrameManager:
             return False, False
 
         force_update = False
+        camera_state = self.cameras.get(camera)
+
+        if camera_state is None:
+            return False, False
 
         # disabling birdseye is a little tricky
         if not camera_config.birdseye.enabled or not camera_config.enabled:
             # if we've rendered a frame (we have a value for last_active_frame)
             # then we need to set it to zero
-            if self.cameras[camera]["last_active_frame"] > 0:
-                self.cameras[camera]["last_active_frame"] = 0
+            if camera_state["last_active_frame"] > 0:
+                camera_state["last_active_frame"] = 0
                 force_update = True
             else:
                 return False, False
 
         # 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):
-            self.cameras[camera]["last_active_frame"] = frame_time
+        camera_state["current_frame"] = frame.copy()
+        camera_state["current_frame_time"] = frame_time
+        if self.camera_active(
+            camera_config.birdseye.mode,
+            activity,
+        ):
+            camera_state["last_active_frame"] = frame_time
 
         now = datetime.datetime.now().timestamp()
 
@@ -882,10 +876,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,
         )

frigate/output/output.py

@@ -51,8 +51,12 @@ def check_disabled_camera_update(
 
     for camera, last_update in write_times.items():
         offline_time = now - last_update
+        camera_config = config.cameras.get(camera)
 
-        if config.cameras[camera].enabled:
+        if camera_config is None:
+            continue
+
+        if camera_config.enabled:
             has_enabled_camera = True
         else:
             # flag camera as offline when it is disabled
@@ -62,8 +66,8 @@ def check_disabled_camera_update(
             # last camera update was more than 1 second ago
             # need to send empty data to birdseye because current
             # frame is now out of date
-            cam_width = config.cameras[camera].detect.width
-            cam_height = config.cameras[camera].detect.height
+            cam_width = camera_config.detect.width
+            cam_height = camera_config.detect.height
 
             if cam_width is None or cam_height is None:
                 raise ValueError(f"Camera {camera} detect dimensions not configured")
@@ -309,10 +313,11 @@ class OutputProcess(FrigateProcess):
                 regions,
             ) = data
 
-            frame = frame_manager.get(
-                frame_name, self.config.cameras[camera].frame_shape_yuv
-            )
-            frame_manager.close(frame_name)
+            camera_config = self.config.cameras.get(camera)
+
+            if camera_config is not None:
+                frame_manager.get(frame_name, camera_config.frame_shape_yuv)
+                frame_manager.close(frame_name)
 
         detection_subscriber.stop()
 

frigate/ptz/autotrack.py

@@ -799,14 +799,24 @@ class PtzAutoTracker:
             except TimeoutError:
                 continue
 
+            # both are popped when the camera is deleted, so resolve them once
+            # here and use the locals for the rest of the move; a move already
+            # in flight then finishes against valid objects
+            metrics = self.ptz_metrics.get(camera)
+            camera_config = self.config.cameras.get(camera)
+
+            if metrics is None or camera_config is None:
+                logger.debug("%s: Dropping queued move, camera was removed", camera)
+                continue
+
             async with self.move_queue_locks[camera]:
                 frame_time, pan, tilt, zoom = move_data
 
                 # if we're receiving move requests during a PTZ move, ignore them
                 if ptz_moving_at_frame_time(
                     frame_time,
-                    self.ptz_metrics[camera].start_time.value,
-                    self.ptz_metrics[camera].stop_time.value,
+                    metrics.start_time.value,
+                    metrics.stop_time.value,
                 ):
                     logger.debug(
                         f"{camera}: Move queue: PTZ moving, dequeueing move request - frame time: {frame_time}, final pan: {pan}, final tilt: {tilt}, final zoom: {zoom}"
@@ -815,7 +825,7 @@ class PtzAutoTracker:
 
                 else:
                     if (
-                        self.config.cameras[camera].onvif.autotracking.zooming
+                        camera_config.onvif.autotracking.zooming
                         == ZoomingModeEnum.relative
                     ):
                         await self.onvif._move_relative(camera, pan, tilt, zoom, 1)
@@ -824,25 +834,22 @@ class PtzAutoTracker:
                             await self.onvif._move_relative(camera, pan, tilt, 0, 1)
 
                             # Wait until the camera finishes moving
-                            while not self.ptz_metrics[camera].motor_stopped.is_set():
+                            while not metrics.motor_stopped.is_set():
                                 await self.onvif.get_camera_status(camera)
 
-                        if (
-                            zoom > 0
-                            and self.ptz_metrics[camera].zoom_level.value != zoom
-                        ):
+                        if zoom > 0 and metrics.zoom_level.value != zoom:
                             await self.onvif._zoom_absolute(camera, zoom, 1)
 
                     # Wait until the camera finishes moving
-                    while not self.ptz_metrics[camera].motor_stopped.is_set():
+                    while not metrics.motor_stopped.is_set():
                         await self.onvif.get_camera_status(camera)
 
-                    if self.config.cameras[camera].onvif.autotracking.movement_weights:
+                    if camera_config.onvif.autotracking.movement_weights:
                         logger.debug(
                             f"{camera}: Predicted movement time: {self._predict_movement_time(camera, pan, tilt)}"
                         )
                         logger.debug(
-                            f"{camera}: Actual movement time: {self.ptz_metrics[camera].stop_time.value - self.ptz_metrics[camera].start_time.value}"
+                            f"{camera}: Actual movement time: {metrics.stop_time.value - metrics.start_time.value}"
                         )
 
                     # save metrics for better estimate calculations
@@ -851,21 +858,15 @@ class PtzAutoTracker:
                         and len(self.move_metrics[camera])
                         < AUTOTRACKING_MAX_MOVE_METRICS
                         and (pan != 0 or tilt != 0)
-                        and self.config.cameras[
-                            camera
-                        ].onvif.autotracking.calibrate_on_startup
+                        and camera_config.onvif.autotracking.calibrate_on_startup
                     ):
                         logger.debug(f"{camera}: Adding new values to move metrics")
                         self.move_metrics[camera].append(
                             {
                                 "pan": pan,
                                 "tilt": tilt,
-                                "start_timestamp": self.ptz_metrics[
-                                    camera
-                                ].start_time.value,
-                                "end_timestamp": self.ptz_metrics[
-                                    camera
-                                ].stop_time.value,
+                                "start_timestamp": metrics.start_time.value,
+                                "end_timestamp": metrics.stop_time.value,
                             }
                         )
 

frigate/ptz/onvif.py

@@ -180,6 +180,11 @@ class OnvifController:
             return False
 
     async def _init_onvif(self, camera_name: str) -> bool:
+        camera_config = self.config.cameras.get(camera_name)
+
+        if camera_config is None:
+            return False
+
         onvif: ONVIFCamera = self.cams[camera_name]["onvif"]
         try:
             await onvif.update_xaddrs()
@@ -235,7 +240,7 @@ class OnvifController:
                 p.token,
             )
 
-        configured_profile = self.config.cameras[camera_name].onvif.profile
+        configured_profile = camera_config.onvif.profile
         profile = None
 
         if configured_profile is not None:
@@ -339,7 +344,7 @@ class OnvifController:
             except (AttributeError, TypeError):
                 fov_space_id = None
 
-        autotracking_config = self.config.cameras[camera_name].onvif.autotracking
+        autotracking_config = camera_config.onvif.autotracking
         autotracking_enabled = (
             autotracking_config.enabled_in_config and autotracking_config.enabled
         )
@@ -614,6 +619,11 @@ class OnvifController:
             logger.error(f"{camera_name} does not support ONVIF RelativeMove (FOV).")
             return
 
+        metrics = self.ptz_metrics.get(camera_name)
+
+        if metrics is None:
+            return
+
         logger.debug(
             f"{camera_name} called RelativeMove: pan: {pan} tilt: {tilt} zoom: {zoom}"
         )
@@ -627,15 +637,11 @@ class OnvifController:
         self.cams[camera_name]["active"] = True
 
         # only track start_time for autotracking
-        if self.ptz_metrics[camera_name].autotracker_enabled.value:
-            self.ptz_metrics[camera_name].motor_stopped.clear()
-            logger.debug(
-                f"{camera_name}: PTZ start time: {self.ptz_metrics[camera_name].frame_time.value}"
-            )
-            self.ptz_metrics[camera_name].start_time.value = self.ptz_metrics[
-                camera_name
-            ].frame_time.value
-            self.ptz_metrics[camera_name].stop_time.value = 0
+        if metrics.autotracker_enabled.value:
+            metrics.motor_stopped.clear()
+            logger.debug(f"{camera_name}: PTZ start time: {metrics.frame_time.value}")
+            metrics.start_time.value = metrics.frame_time.value
+            metrics.stop_time.value = 0
 
         move_request = self.cams[camera_name]["relative_move_request"]
 
@@ -697,9 +703,14 @@ class OnvifController:
             logger.error(f"{preset} is not a valid preset for {camera_name}")
             return
 
+        metrics = self.ptz_metrics.get(camera_name)
+
+        if metrics is None:
+            return
+
         self.cams[camera_name]["active"] = True
-        self.ptz_metrics[camera_name].start_time.value = 0
-        self.ptz_metrics[camera_name].stop_time.value = 0
+        metrics.start_time.value = 0
+        metrics.stop_time.value = 0
         move_request = self.cams[camera_name]["move_request"]
         preset_token = self.cams[camera_name]["presets"][preset]
 
@@ -738,6 +749,11 @@ class OnvifController:
             logger.error(f"{camera_name} does not support ONVIF AbsoluteMove zooming.")
             return
 
+        metrics = self.ptz_metrics.get(camera_name)
+
+        if metrics is None:
+            return
+
         logger.debug(f"{camera_name} called AbsoluteMove: zoom: {zoom}")
 
         if self.cams[camera_name]["active"]:
@@ -747,14 +763,10 @@ class OnvifController:
             return
 
         self.cams[camera_name]["active"] = True
-        self.ptz_metrics[camera_name].motor_stopped.clear()
-        logger.debug(
-            f"{camera_name}: PTZ start time: {self.ptz_metrics[camera_name].frame_time.value}"
-        )
-        self.ptz_metrics[camera_name].start_time.value = self.ptz_metrics[
-            camera_name
-        ].frame_time.value
-        self.ptz_metrics[camera_name].stop_time.value = 0
+        metrics.motor_stopped.clear()
+        logger.debug(f"{camera_name}: PTZ start time: {metrics.frame_time.value}")
+        metrics.start_time.value = metrics.frame_time.value
+        metrics.stop_time.value = 0
         move_request = self.cams[camera_name]["absolute_move_request"]
 
         # function takes in 0 to 1 for zoom, interpolate to the values of the camera.
@@ -875,16 +887,18 @@ class OnvifController:
 
         Returns camera details including features and presets if available.
         """
-        if not self.config.cameras[camera_name].enabled:
+        camera_config = self.config.cameras.get(camera_name)
+
+        if camera_config is None:
+            return {}
+
+        if not camera_config.enabled:
             logger.debug(
                 f"Camera {camera_name} disabled, won't try to initialize ONVIF"
             )
             return {}
 
-        if camera_name not in self.cams.keys() and (
-            camera_name not in self.config.cameras
-            or not self.config.cameras[camera_name].onvif.host
-        ):
+        if camera_name not in self.cams.keys() and (not camera_config.onvif.host):
             logger.debug(f"ONVIF is not configured for {camera_name}")
             return {}
 
@@ -985,6 +999,12 @@ class OnvifController:
                 logger.error(f"ONVIF is not configured for {camera_name}")
                 return
 
+            metrics = self.ptz_metrics.get(camera_name)
+            camera_config = self.config.cameras.get(camera_name)
+
+            if metrics is None or camera_config is None:
+                return
+
             if not self.cams[camera_name]["init"]:
                 if not await self._init_onvif(camera_name):
                     return
@@ -1023,36 +1043,29 @@ class OnvifController:
                 zoom_status is None or zoom_status == "IDLE"
             ):
                 self.cams[camera_name]["active"] = False
-                if not self.ptz_metrics[camera_name].motor_stopped.is_set():
-                    self.ptz_metrics[camera_name].motor_stopped.set()
+                if not metrics.motor_stopped.is_set():
+                    metrics.motor_stopped.set()
 
                     logger.debug(
-                        f"{camera_name}: PTZ stop time: {self.ptz_metrics[camera_name].frame_time.value}"
+                        f"{camera_name}: PTZ stop time: {metrics.frame_time.value}"
                     )
 
-                    self.ptz_metrics[camera_name].stop_time.value = self.ptz_metrics[
-                        camera_name
-                    ].frame_time.value
+                    metrics.stop_time.value = metrics.frame_time.value
             else:
                 self.cams[camera_name]["active"] = True
-                if self.ptz_metrics[camera_name].motor_stopped.is_set():
-                    self.ptz_metrics[camera_name].motor_stopped.clear()
+                if metrics.motor_stopped.is_set():
+                    metrics.motor_stopped.clear()
 
                     logger.debug(
-                        f"{camera_name}: PTZ start time: {self.ptz_metrics[camera_name].frame_time.value}"
+                        f"{camera_name}: PTZ start time: {metrics.frame_time.value}"
                     )
 
-                    self.ptz_metrics[camera_name].start_time.value = self.ptz_metrics[
-                        camera_name
-                    ].frame_time.value
-                    self.ptz_metrics[camera_name].stop_time.value = 0
+                    metrics.start_time.value = metrics.frame_time.value
+                    metrics.stop_time.value = 0
 
-            if (
-                self.config.cameras[camera_name].onvif.autotracking.zooming
-                != ZoomingModeEnum.disabled
-            ):
+            if camera_config.onvif.autotracking.zooming != ZoomingModeEnum.disabled:
                 # store absolute zoom level as 0 to 1 interpolated from the values of the camera
-                self.ptz_metrics[camera_name].zoom_level.value = numpy.interp(
+                metrics.zoom_level.value = numpy.interp(
                     round(status.Position.Zoom.x, 2),
                     [
                         self.cams[camera_name]["absolute_zoom_range"]["XRange"]["Min"],
@@ -1061,25 +1074,22 @@ class OnvifController:
                     [0, 1],
                 )
                 logger.debug(
-                    f"{camera_name}: Camera zoom level: {self.ptz_metrics[camera_name].zoom_level.value}"
+                    f"{camera_name}: Camera zoom level: {metrics.zoom_level.value}"
                 )
 
             # some hikvision cams won't update MoveStatus, so warn if it hasn't changed
             if (
-                not self.ptz_metrics[camera_name].motor_stopped.is_set()
-                and not self.ptz_metrics[camera_name].reset.is_set()
-                and self.ptz_metrics[camera_name].start_time.value != 0
-                and self.ptz_metrics[camera_name].frame_time.value
-                > (self.ptz_metrics[camera_name].start_time.value + 10)
-                and self.ptz_metrics[camera_name].stop_time.value == 0
+                not metrics.motor_stopped.is_set()
+                and not metrics.reset.is_set()
+                and metrics.start_time.value != 0
+                and metrics.frame_time.value > (metrics.start_time.value + 10)
+                and metrics.stop_time.value == 0
             ):
                 logger.debug(
-                    f"Start time: {self.ptz_metrics[camera_name].start_time.value}, Stop time: {self.ptz_metrics[camera_name].stop_time.value}, Frame time: {self.ptz_metrics[camera_name].frame_time.value}"
+                    f"Start time: {metrics.start_time.value}, Stop time: {metrics.stop_time.value}, Frame time: {metrics.frame_time.value}"
                 )
                 # set the stop time so we don't come back into this again and spam the logs
-                self.ptz_metrics[camera_name].stop_time.value = self.ptz_metrics[
-                    camera_name
-                ].frame_time.value
+                metrics.stop_time.value = metrics.frame_time.value
                 logger.warning(
                     f"Camera {camera_name} is still in ONVIF 'MOVING' status."
                 )

frigate/record/maintainer.py

@@ -745,7 +745,9 @@ class RecordingMaintainer(threading.Thread):
                         regions,
                     ) = data
 
-                    if self.config.cameras[camera].record.enabled:
+                    camera_config = self.config.cameras.get(camera)
+
+                    if camera_config is not None and camera_config.record.enabled:
                         self.object_recordings_info[camera].append(
                             (
                                 frame_time,
@@ -762,7 +764,9 @@ class RecordingMaintainer(threading.Thread):
                         audio_detections,
                     ) = data
 
-                    if self.config.cameras[camera].record.enabled:
+                    camera_config = self.config.cameras.get(camera)
+
+                    if camera_config is not None and camera_config.record.enabled:
                         self.audio_recordings_info[camera].append(
                             (
                                 frame_time,

frigate/review/maintainer.py

@@ -418,6 +418,11 @@ class ReviewSegmentMaintainer(threading.Thread):
 
         return None
 
+    def _handle_camera_removed(self, camera: str) -> None:
+        """Close out a deleted camera's segment so a reused name cannot inherit it."""
+        self.forcibly_end_segment(camera)
+        self.indefinite_events.pop(camera, None)
+
     def update_existing_segment(
         self,
         segment: PendingReviewSegment,
@@ -666,6 +671,10 @@ class ReviewSegmentMaintainer(threading.Thread):
                 for camera in updated_topics["enabled"]:
                     self.forcibly_end_segment(camera)
 
+            if "remove" in updated_topics:
+                for camera in updated_topics["remove"]:
+                    self._handle_camera_removed(camera)
+
             result = self.detection_subscriber.check_for_update(timeout=1)
 
             if not result:

frigate/test/http_api/test_http_config_set.py

@@ -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)
 

frigate/test/http_api/test_http_media.py

@@ -1,15 +1,73 @@
 """Unit tests for recordings/media API endpoints."""
 
+from dataclasses import dataclass
 from datetime import UTC, datetime
+from unittest.mock import patch
 
 import pytz
 from fastapi import Request
 
 from frigate.api.auth import get_allowed_cameras_for_filter, get_current_user
+from frigate.const import MAX_SEGMENT_DURATION
 from frigate.models import Recordings
 from frigate.test.http_api.base_http_test import AuthTestClient, BaseTestHttp
 
 
+@dataclass(frozen=True)
+class RangeCase:
+    """Expected behavior for one segment relative to the requested range.
+
+    Offsets are seconds from REQUEST_START; the request ends at +100 seconds.
+    """
+
+    name: str
+    start_offset: float
+    end_offset: float
+    included_in_recordings: bool
+    vod_clip_from_ms: int | None = None
+    vod_duration_ms: int | None = None
+
+
+REQUEST_START = 1000
+REQUEST_END = 1100
+RANGE_CASES = (
+    RangeCase("before", -MAX_SEGMENT_DURATION + 1, -1, False),
+    RangeCase("meets_start", -10, 0, True),
+    RangeCase(
+        "overlaps_start",
+        -MAX_SEGMENT_DURATION + 0.5,
+        0.25,
+        True,
+        vod_clip_from_ms=599500,
+        vod_duration_ms=250,
+    ),
+    RangeCase("starts_at_start", 0, 10, True, vod_duration_ms=10000),
+    RangeCase("inside", 20, 80, True, vod_duration_ms=60000),
+    RangeCase("ends_at_end", 90, 100, True, vod_duration_ms=10000),
+    RangeCase("matches_range", 0, 100, True, vod_duration_ms=100000),
+    RangeCase("starts_with_range", 0, 110, True, vod_duration_ms=100000),
+    RangeCase(
+        "covers_range",
+        -20,
+        120,
+        True,
+        vod_clip_from_ms=20000,
+        vod_duration_ms=100000,
+    ),
+    RangeCase(
+        "ends_with_range",
+        -10,
+        100,
+        True,
+        vod_clip_from_ms=10000,
+        vod_duration_ms=100000,
+    ),
+    RangeCase("overlaps_end", 95, 105, True, vod_duration_ms=5000),
+    RangeCase("starts_at_end", 100, 110, True),
+    RangeCase("after", 101, 110, False),
+)
+
+
 class TestHttpMedia(BaseTestHttp):
     """Test media API endpoints, particularly recordings with DST handling."""
 
@@ -44,6 +102,26 @@ class TestHttpMedia(BaseTestHttp):
         self.app.dependency_overrides.clear()
         super().tearDown()
 
+    def _assert_vod_response(
+        self,
+        response,
+        expected_clips: list[tuple[str, int | None, int]],
+    ) -> None:
+        """Assert VOD clip metadata and its derived duration fields."""
+        assert response.status_code == 200
+        vod = response.json()
+        assert [
+            (
+                clip["path"],
+                clip.get("clipFrom"),
+                clip["keyFrameDurations"][0],
+            )
+            for clip in vod["sequences"][0]["clips"]
+        ] == expected_clips
+        expected_durations = [clip[2] for clip in expected_clips]
+        assert vod["durations"] == expected_durations
+        assert vod["segment_duration"] == max(expected_durations)
+
     def test_recordings_summary_across_dst_spring_forward(self):
         """
         Test recordings summary across spring DST transition (spring forward).
@@ -404,6 +482,102 @@ class TestHttpMedia(BaseTestHttp):
             assert "2024-03-10" in summary
             assert summary["2024-03-10"] is True
 
+    def test_recordings_handles_all_range_relations(self):
+        """Recordings return every interval relation that touches the range."""
+        with AuthTestClient(self.app) as client:
+            for case in RANGE_CASES:
+                with self.subTest(case=case.name):
+                    Recordings.delete().execute()
+                    super().insert_mock_recording(
+                        case.name,
+                        REQUEST_START + case.start_offset,
+                        REQUEST_START + case.end_offset,
+                    )
+
+                    response = client.get(
+                        "/front_door/recordings",
+                        params={"after": REQUEST_START, "before": REQUEST_END},
+                    )
+
+                    assert response.status_code == 200
+                    expected_ids = [case.name] if case.included_in_recordings else []
+                    assert [
+                        recording["id"] for recording in response.json()
+                    ] == expected_ids
+
+    def test_vod_handles_all_range_relations(self):
+        """VOD clips every interval relation with positive playback duration."""
+        with (
+            AuthTestClient(self.app) as client,
+            patch(
+                "frigate.api.media.get_keyframe_before",
+                side_effect=lambda _path, offset: offset,
+            ),
+        ):
+            for case in RANGE_CASES:
+                with self.subTest(case=case.name):
+                    Recordings.delete().execute()
+                    super().insert_mock_recording(
+                        case.name,
+                        REQUEST_START + case.start_offset,
+                        REQUEST_START + case.end_offset,
+                    )
+
+                    response = client.get(
+                        f"/vod/front_door/start/{REQUEST_START}/end/{REQUEST_END}"
+                    )
+
+                    if case.vod_duration_ms is None:
+                        assert response.status_code == 404
+                        continue
+
+                    self._assert_vod_response(
+                        response,
+                        [
+                            (
+                                case.name,
+                                case.vod_clip_from_ms,
+                                case.vod_duration_ms,
+                            )
+                        ],
+                    )
+
+    def test_vod_handles_segment_ending_at_start_with_keyframe_fallbacks(self):
+        """VOD keeps a boundary segment when keyframe lookup extends it."""
+
+        def keyframe_before(path: str, offset: int) -> int | None:
+            return offset - 1000 if path == "previous_keyframe" else None
+
+        with (
+            AuthTestClient(self.app) as client,
+            patch(
+                "frigate.api.media.get_keyframe_before",
+                side_effect=keyframe_before,
+            ),
+        ):
+            super().insert_mock_recording(
+                "previous_keyframe",
+                REQUEST_START - 10,
+                REQUEST_START,
+            )
+            super().insert_mock_recording(
+                "missing_keyframe",
+                REQUEST_START - 5,
+                REQUEST_START,
+            )
+
+            response = client.get(
+                f"/vod/front_door/start/{REQUEST_START}/end/{REQUEST_END}"
+            )
+
+            self._assert_vod_response(
+                response,
+                [
+                    ("previous_keyframe", 9000, 1000),
+                    ("missing_keyframe", None, 5000),
+                ],
+            )
+
     def test_recordings_unavailable_reports_gap_between_recordings(self):
         """A gap between two recordings is reported as an unavailable segment."""
         with AuthTestClient(self.app) as client:

frigate/test/test_birdseye.py

@@ -1,13 +1,70 @@
-"""Test camera user and password cleanup."""
+"""Tests for Birdseye canvas sizing and layout behavior."""
 
 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):
+    def _build_manager(
+        self, camera_dimensions: dict[str, tuple[int, int]]
+    ) -> BirdsEyeFrameManager:
+        config = {
+            "mqtt": {"host": "mqtt"},
+            "birdseye": {"width": 1280, "height": 720},
+            "cameras": {},
+        }
+
+        for order, (camera, dimensions) in enumerate(
+            camera_dimensions.items(), start=1
+        ):
+            config["cameras"][camera] = {
+                "ffmpeg": {
+                    "inputs": [
+                        {
+                            "path": f"rtsp://10.0.0.1:554/{camera}",
+                            "roles": ["detect"],
+                        }
+                    ]
+                },
+                "detect": {
+                    "width": dimensions[0],
+                    "height": dimensions[1],
+                    "fps": 5,
+                },
+                "birdseye": {"order": order},
+            }
+
+        return BirdsEyeFrameManager(FrigateConfig(**config), mp.Event())
+
+    def _assert_no_overlaps(
+        self, layout: list[list[tuple[str, tuple[int, int, int, int]]]]
+    ):
+        rectangles = [position for row in layout for _, position in row]
+
+        for index, rect in enumerate(rectangles):
+            x1, y1, width1, height1 = rect
+            for other in rectangles[index + 1 :]:
+                x2, y2, width2, height2 = other
+                overlap = (
+                    x1 < x2 + width2
+                    and x2 < x1 + width1
+                    and y1 < y2 + height2
+                    and y2 < y1 + height1
+                )
+                self.assertFalse(
+                    overlap,
+                    msg=f"Overlapping rectangles found: {rect} and {other}",
+                )
+
     def test_16x9(self):
         """Test 16x9 aspect ratio works as expected for birdseye."""
         width = 1280
@@ -48,6 +105,212 @@ class TestBirdseye(unittest.TestCase):
         assert canvas_width == width  # width will be the same
         assert canvas_height != height
 
+    def test_portrait_camera_does_not_overlap_next_row(self):
+        """Portrait cameras should reserve their real horizontal position on the next row."""
+        manager = self._build_manager(
+            {
+                "cam_a": (1280, 720),
+                "cam_p": (360, 640),
+                "cam_b": (1280, 720),
+                "cam_c": (640, 480),
+            }
+        )
+
+        layout = manager.calculate_layout(["cam_a", "cam_p", "cam_b", "cam_c"], 3)
+
+        self.assertIsNotNone(layout)
+        assert layout is not None
+        self._assert_no_overlaps(layout)
+
+        cam_c = [
+            position for row in layout for camera, position in row if camera == "cam_c"
+        ][0]
+        self.assertEqual(cam_c[0], 0)
+
+    def test_portrait_reservation_only_applies_to_next_row(self):
+        """Portrait reservations should not push later rows after the span ends."""
+        manager = self._build_manager(
+            {
+                "cam_a": (1280, 720),
+                "cam_p": (360, 640),
+                "cam_b": (1280, 720),
+                "cam_c": (1280, 720),
+                "cam_d": (1280, 720),
+                "cam_e": (1280, 720),
+            }
+        )
+
+        layout = manager.calculate_layout(
+            ["cam_a", "cam_p", "cam_b", "cam_c", "cam_d", "cam_e"],
+            3,
+        )
+
+        self.assertIsNotNone(layout)
+        assert layout is not None
+        self._assert_no_overlaps(layout)
+
+        cam_e = [
+            position for row in layout for camera, position in row if camera == "cam_e"
+        ][0]
+        self.assertEqual(cam_e[0], 0)
+
+    def test_multiple_portraits_reserve_distinct_ranges(self):
+        """Multiple portrait cameras in one row should reserve separate spans below them."""
+        manager = self._build_manager(
+            {
+                "cam_a": (640, 480),
+                "cam_p1": (360, 640),
+                "cam_p2": (360, 640),
+                "cam_b": (640, 480),
+                "cam_c": (1280, 720),
+                "cam_d": (640, 480),
+            }
+        )
+
+        layout = manager.calculate_layout(
+            ["cam_a", "cam_p1", "cam_p2", "cam_b", "cam_c", "cam_d"],
+            4,
+        )
+
+        self.assertIsNotNone(layout)
+        assert layout is not None
+        self._assert_no_overlaps(layout)
+
+    def test_two_landscapes_then_portrait_then_two_landscapes(self):
+        """A portrait after two landscapes should reserve only its own tail span."""
+        manager = self._build_manager(
+            {
+                "cam_a": (1280, 720),
+                "cam_b": (1280, 720),
+                "cam_p": (360, 640),
+                "cam_c": (1280, 720),
+                "cam_d": (1280, 720),
+            }
+        )
+
+        layout = manager.calculate_layout(
+            ["cam_a", "cam_b", "cam_p", "cam_c", "cam_d"],
+            3,
+        )
+
+        self.assertIsNotNone(layout)
+        assert layout is not None
+        self._assert_no_overlaps(layout)
+
+        cam_c = [
+            position for row in layout for camera, position in row if camera == "cam_c"
+        ][0]
+        cam_d = [
+            position for row in layout for camera, position in row if camera == "cam_d"
+        ][0]
+        self.assertEqual(cam_c[0], 0)
+        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."""
@@ -55,7 +318,7 @@ class TestBirdseyeCameraOrder(unittest.TestCase):
     def setUp(self):
         config = {
             "mqtt": {"enabled": False},
-            "birdseye": {"enabled": True, "mode": "continuous"},
+            "birdseye": {"enabled": True, "mode": {"continuous": True}},
             "cameras": {
                 camera: {
                     "ffmpeg": {

frigate/test/test_camera_lifecycle.py

@@ -0,0 +1,227 @@
+"""Regression tests for runtime camera add and delete handling."""
+
+import asyncio
+import threading
+import unittest
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+# LicensePlatePostProcessor is imported via the maintainer rather than from
+# data_processing.post.license_plate, which circularly imports back through
+# frigate.embeddings before that package finishes initializing
+from frigate.embeddings.maintainer import (
+    EmbeddingMaintainer,
+    LicensePlatePostProcessor,
+)
+from frigate.ptz.autotrack import PtzAutoTracker
+from frigate.review.maintainer import ReviewSegmentMaintainer
+from frigate.track.object_processing import TrackedObjectProcessor
+
+
+def _make_processor() -> TrackedObjectProcessor:
+    """Build a processor with no cameras, bypassing __init__."""
+    processor = TrackedObjectProcessor.__new__(TrackedObjectProcessor)
+    processor.camera_states = {}
+    processor.camera_states_lock = threading.Lock()
+    processor.config = SimpleNamespace(cameras={})
+    processor.event_sender = MagicMock()
+    processor.detection_publisher = MagicMock()
+    processor.ongoing_manual_events = {}
+    return processor
+
+
+class TestObjectProcessorUnknownCamera(unittest.TestCase):
+    def test_save_lpr_snapshot_ignores_unknown_camera(self):
+        processor = _make_processor()
+
+        # 1x1 png, base64; decoding must not be what fails
+        payload = (
+            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+            "1234.5-abcdef",
+            "deleted_cam",
+        )
+
+        processor.save_lpr_snapshot(payload)
+
+        processor.event_sender.publish.assert_not_called()
+
+    def test_create_manual_event_ignores_unknown_camera(self):
+        processor = _make_processor()
+
+        payload = (
+            1234.5,
+            "deleted_cam",
+            "person",
+            "1234.5-abcdef",
+            True,
+            0.9,
+            None,
+            None,
+            "api",
+            False,
+            None,
+        )
+
+        processor.create_manual_event(payload)
+
+        processor.event_sender.publish.assert_not_called()
+        self.assertEqual(processor.ongoing_manual_events, {})
+
+    def test_create_lpr_event_ignores_unknown_camera(self):
+        processor = _make_processor()
+
+        payload = (
+            1234.5,
+            "deleted_cam",
+            "license_plate",
+            "1234.5-abcdef",
+            True,
+            0.9,
+            None,
+            "ABC123",
+        )
+
+        processor.create_lpr_event(payload)
+
+        processor.event_sender.publish.assert_not_called()
+        self.assertEqual(processor.ongoing_manual_events, {})
+
+    def test_create_manual_event_ignores_camera_added_but_not_yet_drained(self):
+        """The add window: present in config.cameras, absent from camera_states.
+
+        debug_replay writes the camera into the shared config before publishing
+        add, so a guard on config.cameras passes here and falls through to
+        camera_states. This test fails against such a guard.
+        """
+        processor = _make_processor()
+        processor.config = SimpleNamespace(
+            cameras={
+                "new_cam": SimpleNamespace(
+                    record=SimpleNamespace(event_pre_capture=5, enabled=True)
+                )
+            }
+        )
+
+        payload = (
+            1234.5,
+            "new_cam",
+            "person",
+            "1234.5-abcdef",
+            True,
+            0.9,
+            None,
+            None,
+            "api",
+            False,
+            None,
+        )
+
+        processor.create_manual_event(payload)
+
+        processor.event_sender.publish.assert_not_called()
+
+
+class TestEmbeddingsUnknownCamera(unittest.TestCase):
+    def _make_maintainer(self) -> EmbeddingMaintainer:
+        maintainer = EmbeddingMaintainer.__new__(EmbeddingMaintainer)
+        maintainer.config = SimpleNamespace(cameras={})
+        maintainer.event_end_subscriber = MagicMock()
+        maintainer.realtime_processors = [MagicMock()]
+        # spec is required: the dispatch loop is a chain of isinstance checks,
+        # and a bare MagicMock matches none of them, so the crashing branch
+        # would never run and the test would pass against unfixed code
+        maintainer.post_processors = [MagicMock(spec=LicensePlatePostProcessor)]
+        maintainer.detected_license_plates = {"1234.5-abcdef": {"obj_data": {}}}
+        maintainer.recordings_available_through = {"deleted_cam": 1234.5}
+        maintainer.event_metadata_publisher = MagicMock()
+        return maintainer
+
+    def test_process_finalized_skips_unknown_camera(self):
+        maintainer = self._make_maintainer()
+        # updated_db=False bypasses the Event.get branch, which would hit the
+        # database and mask the KeyError this test is about
+        maintainer.event_end_subscriber.check_for_update.side_effect = [
+            ("1234.5-abcdef", "deleted_cam", False),
+            None,
+        ]
+
+        maintainer._process_finalized()
+
+        maintainer.post_processors[0].process_data.assert_not_called()
+
+    def test_process_finalized_still_expires_realtime_state(self):
+        """The guard must not skip per-event cleanup, only post processing."""
+        maintainer = self._make_maintainer()
+        maintainer.event_end_subscriber.check_for_update.side_effect = [
+            ("1234.5-abcdef", "deleted_cam", False),
+            None,
+        ]
+
+        maintainer._process_finalized()
+
+        maintainer.realtime_processors[0].expire_object.assert_called_once_with(
+            "1234.5-abcdef", "deleted_cam"
+        )
+
+    def test_expire_dedicated_lpr_drops_entry_for_unknown_camera(self):
+        maintainer = self._make_maintainer()
+        maintainer.detected_license_plates = {
+            "1234.5-abcdef": {"camera": "deleted_cam", "last_seen": 1.0}
+        }
+
+        maintainer._expire_dedicated_lpr()
+
+        self.assertEqual(maintainer.detected_license_plates, {})
+
+
+class TestReviewMaintainerRemoval(unittest.TestCase):
+    def test_camera_removal_ends_segment_and_clears_state(self):
+        maintainer = ReviewSegmentMaintainer.__new__(ReviewSegmentMaintainer)
+        maintainer.active_review_segments = {"deleted_cam": MagicMock()}
+        maintainer.indefinite_events = {"deleted_cam": {"1234.5-abcdef": 1.0}}
+        maintainer.forcibly_end_segment = MagicMock()
+
+        maintainer._handle_camera_removed("deleted_cam")
+
+        maintainer.forcibly_end_segment.assert_called_once_with("deleted_cam")
+        self.assertNotIn("deleted_cam", maintainer.indefinite_events)
+
+
+class TestAutotrackerMoveQueue(unittest.TestCase):
+    def test_move_queue_drops_move_for_removed_camera(self):
+        tracker = PtzAutoTracker.__new__(PtzAutoTracker)
+        tracker.stop_event = MagicMock()
+        # one pass through the loop, then stop
+        tracker.stop_event.is_set.side_effect = [False, True]
+        tracker.ptz_metrics = {}
+        tracker.move_queues = {"deleted_cam": asyncio.Queue()}
+        tracker.move_queue_locks = {"deleted_cam": asyncio.Lock()}
+        tracker.onvif = MagicMock()
+        tracker.config = SimpleNamespace(cameras={})
+        tracker.move_queues["deleted_cam"].put_nowait((1234.5, 0.1, 0.1, 0.0))
+
+        asyncio.run(tracker._process_move_queue("deleted_cam"))
+
+        tracker.onvif._move_relative.assert_not_called()
+
+
+class TestCameraStateAccessors(unittest.TestCase):
+    def test_get_camera_state_returns_none_for_unknown_camera(self):
+        processor = _make_processor()
+
+        self.assertIsNone(processor.get_camera_state("deleted_cam"))
+
+    def test_get_camera_states_returns_a_snapshot_not_a_view(self):
+        """A live values() view raises RuntimeError if the writer pops mid-iteration."""
+        processor = _make_processor()
+        processor.camera_states = {"one": MagicMock(), "two": MagicMock()}
+
+        states = processor.get_camera_states()
+        processor.camera_states.pop("one")
+
+        self.assertEqual(len(states), 2)
+
+    def test_get_current_frame_time_is_zero_for_unknown_camera(self):
+        processor = _make_processor()
+
+        self.assertEqual(processor.get_current_frame_time("deleted_cam"), 0.0)

frigate/test/test_config.py

@@ -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 = {

frigate/test/test_dispatcher_runtime_state.py

@@ -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."""
 

frigate/test/test_gpu_stats.py

@@ -1,7 +1,12 @@
 import unittest
+from io import StringIO
 from unittest.mock import MagicMock, patch
 
-from frigate.util.services import get_amd_gpu_stats, get_intel_gpu_stats
+from frigate.util.services import (
+    get_amd_gpu_stats,
+    get_intel_gpu_stats,
+    get_openvino_npu_stats,
+)
 
 
 class TestGpuStats(unittest.TestCase):
@@ -17,6 +22,88 @@ class TestGpuStats(unittest.TestCase):
         amd_stats = get_amd_gpu_stats()
         assert amd_stats == {"gpu": "4.17%", "mem": "60.37%"}
 
+    @patch("frigate.util.services.time.sleep")
+    @patch("frigate.util.services.time.time", side_effect=[0.0, 1.0])
+    @patch(
+        "frigate.util.services.os.readlink",
+        return_value="/sys/bus/pci/drivers/intel_vpu",
+    )
+    @patch(
+        "frigate.util.services.glob.glob",
+        return_value=["/sys/class/accel/accel0"],
+    )
+    @patch(
+        "builtins.open",
+        side_effect=[StringIO("1000"), StringIO("1250")],
+    )
+    def test_openvino_npu_stats_discovers_accel0(
+        self, open_file, glob, readlink, time, sleep
+    ):
+        assert get_openvino_npu_stats() == {"npu": "25.0", "mem": "-%"}
+
+        open_file.assert_any_call(
+            "/sys/class/accel/accel0/device/power/runtime_active_time"
+        )
+
+    @patch("frigate.util.services.time.sleep")
+    @patch("frigate.util.services.time.time", side_effect=[0.0, 1.0])
+    @patch(
+        "frigate.util.services.os.readlink",
+        side_effect=[
+            "/sys/bus/pci/drivers/other",
+            "/sys/bus/pci/drivers/intel_vpu",
+        ],
+    )
+    @patch(
+        "frigate.util.services.glob.glob",
+        return_value=[
+            "/sys/class/accel/accel0",
+            "/sys/class/accel/accel1",
+        ],
+    )
+    @patch(
+        "builtins.open",
+        side_effect=[StringIO("1000"), StringIO("1250")],
+    )
+    def test_openvino_npu_stats_skips_non_intel_accelerator(
+        self, open_file, glob, readlink, time, sleep
+    ):
+        assert get_openvino_npu_stats() == {"npu": "25.0", "mem": "-%"}
+
+        open_file.assert_any_call(
+            "/sys/class/accel/accel1/device/power/runtime_active_time"
+        )
+
+    @patch(
+        "frigate.util.services.os.readlink",
+        return_value="/sys/bus/pci/drivers/other",
+    )
+    @patch(
+        "frigate.util.services.glob.glob",
+        return_value=["/sys/class/accel/accel0"],
+    )
+    @patch("builtins.open")
+    def test_openvino_npu_stats_no_intel_accelerator(self, open_file, glob, readlink):
+        assert get_openvino_npu_stats() is None
+        open_file.assert_not_called()
+
+    @patch(
+        "frigate.util.services.os.readlink",
+        return_value="/sys/bus/pci/drivers/intel_vpu",
+    )
+    @patch(
+        "frigate.util.services.glob.glob",
+        return_value=["/sys/class/accel/accel0"],
+    )
+    @patch("builtins.open", side_effect=FileNotFoundError)
+    def test_openvino_npu_stats_runtime_counter_unavailable(
+        self, open_file, glob, readlink
+    ):
+        assert get_openvino_npu_stats() is None
+        open_file.assert_called_once_with(
+            "/sys/class/accel/accel0/device/power/runtime_active_time"
+        )
+
     @patch("frigate.stats.intel_gpu_info.intel_gpu_name_resolver.get_names")
     @patch("frigate.util.services.time.sleep")
     @patch("frigate.util.services.time.monotonic")

frigate/test/test_mqtt_lifecycle.py

@@ -0,0 +1,856 @@
+import os
+import threading
+import unittest
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import paho.mqtt.client as mqtt
+
+from frigate.comms.dispatcher import Dispatcher
+from frigate.comms.mqtt import MqttClient, QueuedPublish
+from frigate.config import FrigateConfig
+from frigate.const import MODEL_CACHE_DIR
+
+
+class RuntimeSnapshotReceiver:
+    def __init__(self) -> None:
+        self.messages: list[tuple[str, str]] = []
+
+    def _receive(self, topic: str, payload: str) -> None:
+        self.messages.append((topic, payload))
+
+
+class FakeMessage:
+    def __init__(self, topic: str, payload: bytes) -> None:
+        self.topic = topic
+        self.payload = payload
+
+
+class FakeCommunicator:
+    def __init__(self) -> None:
+        self.receiver = None
+        self.dispatcher = None
+        self.started = False
+
+    def subscribe(self, receiver) -> None:
+        self.receiver = receiver
+
+    def attach_dispatcher(self, dispatcher) -> None:
+        self.dispatcher = dispatcher
+
+    def start(self) -> None:
+        self.started = True
+
+    def publish(self, topic: str, payload: Any, retain: bool = False) -> None:
+        return None
+
+    def stop(self) -> None:
+        return None
+
+
+class FakeSnapshotCommunicator(FakeCommunicator):
+    def start(self) -> None:
+        self.started = True
+        assert self.dispatcher is not None
+        self.dispatcher.publish_runtime_snapshot(lambda *_args, **_kwargs: None)
+
+
+def build_config() -> FrigateConfig:
+    config = {
+        "mqtt": {
+            "host": "mqtt",
+            "client_id": "frigate-test",
+            "topic_prefix": "frigate",
+        },
+        "notifications": {"enabled": True},
+        "cameras": {
+            "front": {
+                "ffmpeg": {
+                    "inputs": [
+                        {
+                            "path": "rtsp://10.0.0.1:554/video",
+                            "roles": ["detect", "audio"],
+                        }
+                    ]
+                },
+                "detect": {
+                    "height": 1080,
+                    "width": 1920,
+                    "fps": 5,
+                },
+                "audio": {"enabled": True},
+                "notifications": {"enabled": False},
+                "onvif": {"host": "10.0.0.5"},
+                "motion": {
+                    "mask": {
+                        "motion_mask_1": {
+                            "coordinates": "0,0,1,0,1,1,0,1",
+                        }
+                    }
+                },
+                "objects": {
+                    "track": ["person"],
+                    "mask": {
+                        "object_mask_1": {
+                            "coordinates": "0,0,1,0,1,1,0,1",
+                        }
+                    },
+                },
+                "zones": {
+                    "driveway": {
+                        "coordinates": "0.1,0.1,0.9,0.1,0.9,0.9,0.1,0.9",
+                        "objects": ["person"],
+                    }
+                },
+            }
+        },
+    }
+    return FrigateConfig(**config)
+
+
+def build_dispatcher(config: FrigateConfig, communicators: list[Any]) -> Dispatcher:
+    """Build a real Dispatcher with only the activity managers stubbed out."""
+    with (
+        patch("frigate.comms.dispatcher.CameraActivityManager") as mock_camera_activity,
+        patch("frigate.comms.dispatcher.AudioActivityManager") as mock_audio_activity,
+    ):
+        mock_camera_activity.return_value.last_camera_activity = {}
+        mock_audio_activity.return_value.current_audio_detections = {}
+
+        return Dispatcher(config, MagicMock(), MagicMock(), {}, communicators)
+
+
+class TestMqttClientLifecycle(unittest.TestCase):
+    def setUp(self) -> None:
+        if not os.path.exists(MODEL_CACHE_DIR) and not os.path.islink(MODEL_CACHE_DIR):
+            os.makedirs(MODEL_CACHE_DIR)
+
+        self.config = build_config()
+        self.client = MqttClient(self.config)
+        self.receiver = RuntimeSnapshotReceiver()
+        self.client.attach_dispatcher(build_dispatcher(self.config, []))
+
+    def test_subscribe_stores_receiver_without_starting_worker(self) -> None:
+        client = MqttClient(self.config)
+
+        with patch.object(client, "_start_worker") as mock_start_worker:
+            client.subscribe(self.receiver._receive)
+
+        self.assertIsNotNone(client._dispatcher)
+        self.assertIs(client._dispatcher.__self__, self.receiver)
+        self.assertIs(client._dispatcher.__func__, RuntimeSnapshotReceiver._receive)
+        mock_start_worker.assert_not_called()
+
+    def test_attach_dispatcher_supplies_command_surface(self) -> None:
+        client = MqttClient(self.config)
+
+        self.assertFalse(client._is_supported_command_topic("front/detect/set"))
+
+        dispatcher = build_dispatcher(self.config, [])
+        client.attach_dispatcher(dispatcher)
+
+        self.assertIs(client._command_router, dispatcher)
+        self.assertTrue(client._is_supported_command_topic("front/detect/set"))
+
+    def test_start_starts_worker_after_receiver_registration(self) -> None:
+        self.client.subscribe(self.receiver._receive)
+
+        with patch.object(self.client, "_start_worker") as mock_start_worker:
+            self.client.start()
+
+        mock_start_worker.assert_called_once()
+
+    def test_dispatcher_initializes_state_before_starting_communicators(self) -> None:
+        fake_comm = FakeSnapshotCommunicator()
+        dispatcher = build_dispatcher(self.config, [fake_comm])
+
+        self.assertIsNone(dispatcher.web_push_client)
+        self.assertIs(fake_comm.receiver.__self__, dispatcher)
+        self.assertIs(fake_comm.dispatcher, dispatcher)
+        self.assertFalse(fake_comm.started)
+
+        dispatcher.start_communicators()
+
+        self.assertTrue(fake_comm.started)
+
+    def test_publish_drops_ephemeral_and_coalesces_retained_while_disconnected(
+        self,
+    ) -> None:
+        self.client.publish("front/events", "payload")
+        self.assertTrue(self.client._publish_queue.empty())
+
+        self.client.publish("profile/state", "armed", retain=True)
+        self.client.publish("profile/state", "disarmed", retain=True)
+
+        self.assertEqual(
+            self.client._pending_retained["frigate/profile/state"],
+            ("disarmed", True),
+        )
+
+    def test_publish_buffers_messages_until_subscription_ready(self) -> None:
+        self.client.connected = True
+
+        self.client.publish("front/events", "payload")
+        self.client.publish("profile/state", "armed", retain=True)
+
+        self.assertEqual(self.client._publish_queue.qsize(), 2)
+        self.assertEqual(self.client._pending_retained, {})
+
+    @patch("frigate.comms.mqtt.mqtt.Client")
+    def test_connect_client_initializes_manual_loop_client(
+        self, mock_client_cls
+    ) -> None:
+        mock_client = MagicMock()
+        mock_client_cls.return_value = mock_client
+
+        connected = self.client._connect_client()
+
+        self.assertTrue(connected)
+        mock_client_cls.assert_called_once_with(
+            callback_api_version=mqtt.CallbackAPIVersion.VERSION2,
+            client_id="frigate-test",
+            reconnect_on_failure=False,
+        )
+        self.assertIs(mock_client.on_connect.__self__, self.client)
+        self.assertIs(mock_client.on_connect.__func__, MqttClient._on_connect)
+        self.assertIs(mock_client.on_disconnect.__self__, self.client)
+        self.assertIs(mock_client.on_disconnect.__func__, MqttClient._on_disconnect)
+        self.assertIs(mock_client.on_message.__self__, self.client)
+        self.assertIs(mock_client.on_message.__func__, MqttClient._on_message)
+        self.assertIs(mock_client.on_subscribe.__self__, self.client)
+        self.assertIs(mock_client.on_subscribe.__func__, MqttClient._on_subscribe)
+        mock_client.connect.assert_called_once_with("mqtt", 1883, 60)
+
+    def test_handle_connect_failure_leaves_client_disconnected(self) -> None:
+        self.client.client = MagicMock()
+        reason_code = MagicMock()
+        reason_code.getName.return_value = "Not authorized"
+
+        with patch.object(
+            self.client, "_schedule_reconnect"
+        ) as mock_schedule_reconnect:
+            self.client._handle_connect_failure(reason_code)
+
+        self.assertFalse(self.client.connected)
+        mock_schedule_reconnect.assert_called_once()
+
+    def test_handle_connect_event_subscribes_wildcard_topic(self) -> None:
+        self.client.client = MagicMock()
+        self.client.client.subscribe.return_value = (mqtt.MQTT_ERR_SUCCESS, 42)
+
+        self.client._handle_connect_event(MagicMock())
+
+        self.assertTrue(self.client.connected)
+        self.assertEqual(self.client._subscription_mid, 42)
+        self.client.client.subscribe.assert_called_once_with("frigate/#", qos=0)
+
+    def test_handle_connect_event_reconnects_on_recoverable_subscribe_error(
+        self,
+    ) -> None:
+        self.client.client = MagicMock()
+        self.client.client.subscribe.side_effect = BrokenPipeError("broken pipe")
+
+        with patch.object(
+            self.client, "_schedule_reconnect"
+        ) as mock_schedule_reconnect:
+            self.client._handle_connect_event(MagicMock())
+
+        mock_schedule_reconnect.assert_called_once()
+
+    def test_handle_subscribe_event_publishes_snapshots_after_matching_suback(
+        self,
+    ) -> None:
+        self.client.connected = True
+        self.client._subscription_mid = 7
+
+        with (
+            patch.object(self.client, "_publish_retained_state") as mock_retained,
+            patch.object(
+                self.client._command_router, "publish_runtime_snapshot"
+            ) as mock_snapshot,
+        ):
+            self.client._handle_subscribe_event(7, [MagicMock(is_failure=False)])
+
+        self.assertTrue(self.client._subscription_ready)
+        mock_retained.assert_called_once()
+        mock_snapshot.assert_called_once_with(self.client.publish)
+
+    def test_handle_subscribe_event_ignores_other_suback_mid(self) -> None:
+        self.client.connected = True
+        self.client._subscription_mid = 8
+
+        with (
+            patch.object(self.client, "_publish_retained_state") as mock_retained,
+            patch.object(
+                self.client._command_router, "publish_runtime_snapshot"
+            ) as mock_snapshot,
+        ):
+            self.client._handle_subscribe_event(9, [MagicMock(is_failure=False)])
+
+        self.assertFalse(self.client._subscription_ready)
+        mock_retained.assert_not_called()
+        mock_snapshot.assert_not_called()
+
+    def test_on_message_strips_prefix_and_dispatches_supported_topic(self) -> None:
+        dispatcher = MagicMock()
+        self.client._dispatcher = dispatcher
+
+        self.client._on_message(
+            MagicMock(),
+            None,
+            FakeMessage("frigate/front/detect/set", b"ON"),
+        )
+        self.client._drain_callback_queue()
+
+        dispatcher.assert_called_once_with("front/detect/set", "ON")
+
+    def test_on_message_ignores_unsupported_state_topic(self) -> None:
+        dispatcher = MagicMock()
+        self.client._dispatcher = dispatcher
+
+        self.client._on_message(
+            MagicMock(),
+            None,
+            FakeMessage("frigate/front/detect/state", b"ON"),
+        )
+        self.client._drain_callback_queue()
+
+        dispatcher.assert_not_called()
+
+    def test_on_message_ignores_non_utf8_payloads(self) -> None:
+        self.client._on_message(
+            MagicMock(),
+            None,
+            FakeMessage("frigate/onConnect", b"\xff"),
+        )
+
+        self.assertTrue(self.client._callback_queue.empty())
+
+    def test_on_connect_requests_are_rate_limited(self) -> None:
+        dispatcher = MagicMock()
+        self.client._dispatcher = dispatcher
+
+        with patch("frigate.comms.mqtt.time.monotonic", side_effect=[100.0, 100.1]):
+            self.client._handle_inbound_message("onConnect", "")
+            self.client._handle_inbound_message("onConnect", "")
+
+        dispatcher.assert_called_once_with("onConnect", "")
+
+    def test_supported_command_topics_preserve_command_surface(self) -> None:
+        for topic in (
+            "front/detect/set",
+            "front/audio_transcription/set",
+            "front/notifications/set",
+            "front/notifications/suspend",
+            "front/zone/driveway/set",
+            "front/motion_mask/motion_mask_1/set",
+            "front/ptz",
+            "notifications/set",
+            "profile/set",
+            "onConnect",
+            "restart",
+        ):
+            with self.subTest(topic=topic):
+                self.assertTrue(self.client._is_supported_command_topic(topic))
+
+        for topic in (
+            # Frigate's own publishes echoing back through the wildcard
+            "front/detect/state",
+            "available",
+            "front/notifications/suspended",
+            "front/zone/set",
+            "front/nonsense/set",
+            "nonsense/set",
+        ):
+            with self.subTest(topic=topic):
+                self.assertFalse(self.client._is_supported_command_topic(topic))
+
+    def test_command_surface_tracks_dispatcher_handlers(self) -> None:
+        """The allowlist is derived, so a new handler is routable for free."""
+        router = self.client._command_router
+        router._camera_settings_handlers["brand_new_toggle"] = MagicMock()
+
+        self.assertTrue(
+            self.client._is_supported_command_topic("front/brand_new_toggle/set")
+        )
+
+    def test_global_notifications_set_follows_config_gate(self) -> None:
+        """The command gate must match the publish gate in
+        _publish_retained_state: with notifications unconfigured there is no
+        state topic, so the command must not flip runtime state either."""
+        self.assertTrue(self.client._notifications_enabled_in_config())
+        self.assertTrue(self.client._is_supported_command_topic("notifications/set"))
+
+        with patch.object(
+            self.client, "_notifications_enabled_in_config", return_value=False
+        ):
+            self.assertFalse(
+                self.client._is_supported_command_topic("notifications/set")
+            )
+            # per-camera topics stay routable regardless of the global gate
+            self.assertTrue(
+                self.client._is_supported_command_topic("front/notifications/set")
+            )
+            self.assertTrue(
+                self.client._is_supported_command_topic("front/notifications/suspend")
+            )
+
+    def test_publish_direct_waits_for_flush_barrier(self) -> None:
+        mock_client = MagicMock()
+        mock_client.loop.return_value = mqtt.MQTT_ERR_SUCCESS
+        self.client.client = mock_client
+        message_info = MagicMock(rc=mqtt.MQTT_ERR_SUCCESS, mid=1)
+        # inflight tracking checks once, then _wait_for_publish polls
+        message_info.is_published.side_effect = [False, False, True]
+        mock_client.publish.return_value = message_info
+        barrier = MagicMock()
+
+        self.client._publish_direct(
+            QueuedPublish("frigate/available", "stopped", True, barrier)
+        )
+
+        mock_client.loop.assert_called_once()
+        barrier.set.assert_called_once()
+
+    def test_shutdown_barrier_releases_when_publish_raises(self) -> None:
+        """stop() waits on this barrier, so a broker error must not stall
+        shutdown for the full flush timeout."""
+        self.client.client = MagicMock()
+        self.client.client.publish.side_effect = BrokenPipeError("broken pipe")
+        barrier = threading.Event()
+
+        with patch.object(self.client, "_schedule_reconnect"):
+            self.client._publish_direct(
+                QueuedPublish("frigate/available", "stopped", True, barrier)
+            )
+
+        self.assertTrue(barrier.is_set())
+        self.assertEqual(
+            self.client._pending_retained["frigate/available"], ("stopped", True)
+        )
+
+    def test_shutdown_barrier_releases_on_publish_error_code(self) -> None:
+        self.client.client = MagicMock()
+        self.client.client.publish.return_value = MagicMock(rc=mqtt.MQTT_ERR_NO_CONN)
+        barrier = threading.Event()
+
+        with patch.object(self.client, "_schedule_reconnect"):
+            self.client._publish_direct(
+                QueuedPublish("frigate/available", "stopped", True, barrier)
+            )
+
+        self.assertTrue(barrier.is_set())
+
+    def test_shutdown_barrier_releases_when_requeued_while_disconnected(self) -> None:
+        barrier = threading.Event()
+        self.client._publish_queue.put(
+            QueuedPublish("frigate/available", "stopped", True, barrier)
+        )
+
+        self.client._requeue_disconnected_publishes()
+
+        self.assertTrue(barrier.is_set())
+        self.assertEqual(
+            self.client._pending_retained["frigate/available"], ("stopped", True)
+        )
+
+    def test_shutdown_barrier_releases_when_worker_crashes(self) -> None:
+        """stop() can queue the final publish just as the worker dies, and
+        nothing drains the queue after that."""
+        barrier = threading.Event()
+        self.client._publish_queue.put(
+            QueuedPublish("frigate/available", "stopped", True, barrier)
+        )
+
+        with patch.object(
+            self.client,
+            "_mqtt_loop_worker",
+            side_effect=RuntimeError("unexpected bug"),
+        ):
+            self.client._worker_main()
+
+        self.assertTrue(barrier.is_set())
+
+    def test_shutdown_barrier_releases_when_publish_raises_unexpectedly(self) -> None:
+        """The message is off the queue by the time this runs, so crash cleanup
+        cannot recover it and only _publish_direct can release the waiter."""
+        self.client.client = MagicMock()
+        self.client.client.publish.side_effect = RuntimeError("unexpected bug")
+        barrier = threading.Event()
+
+        with self.assertRaises(RuntimeError):
+            self.client._publish_direct(
+                QueuedPublish("frigate/available", "stopped", True, barrier)
+            )
+
+        self.assertTrue(barrier.is_set())
+
+    def test_newest_inflight_retained_value_wins(self) -> None:
+        """Several updates to one topic can be unacked at once above qos 0, and
+        the newest is the one subscribers should end up with."""
+        mock_client = MagicMock()
+        self.client.client = mock_client
+        self.client.connected = True
+
+        for mid, payload in ((1, "ON"), (2, "OFF")):
+            message_info = MagicMock(rc=mqtt.MQTT_ERR_SUCCESS, mid=mid)
+            message_info.is_published.return_value = False
+            mock_client.publish.return_value = message_info
+            self.client._publish_direct(
+                QueuedPublish("frigate/front/detect/state", payload, True)
+            )
+
+        self.client._requeue_inflight_retained()
+
+        self.assertEqual(
+            self.client._pending_retained["frigate/front/detect/state"], ("OFF", True)
+        )
+
+    def test_inflight_retained_does_not_clobber_queued_value(self) -> None:
+        """Anything still queued was written later than anything in flight."""
+        self.client._pending_retained = {"frigate/front/detect/state": ("OFF", True)}
+        self.client._inflight_retained = {1: ("frigate/front/detect/state", "ON")}
+
+        self.client._requeue_inflight_retained()
+
+        self.assertEqual(
+            self.client._pending_retained["frigate/front/detect/state"], ("OFF", True)
+        )
+
+    def test_unacked_retained_publish_survives_reconnect(self) -> None:
+        """Above qos 0 a successful rc only means paho queued the message, and
+        dropping the client drops its outbound queue with it."""
+        mock_client = MagicMock()
+        message_info = MagicMock(rc=mqtt.MQTT_ERR_SUCCESS, mid=12)
+        message_info.is_published.return_value = False
+        mock_client.publish.return_value = message_info
+        self.client.client = mock_client
+        self.client.connected = True
+
+        self.client._publish_direct(
+            QueuedPublish("frigate/profile/state", "armed", True)
+        )
+        self.assertEqual(
+            self.client._inflight_retained[12], ("frigate/profile/state", "armed")
+        )
+
+        self.client._cleanup_client()
+
+        self.assertEqual(self.client._inflight_retained, {})
+        self.assertEqual(
+            self.client._pending_retained["frigate/profile/state"], ("armed", True)
+        )
+
+    def test_acked_retained_publish_is_not_replayed(self) -> None:
+        mock_client = MagicMock()
+        message_info = MagicMock(rc=mqtt.MQTT_ERR_SUCCESS, mid=12)
+        message_info.is_published.return_value = False
+        mock_client.publish.return_value = message_info
+        self.client.client = mock_client
+        self.client.connected = True
+
+        self.client._publish_direct(
+            QueuedPublish("frigate/profile/state", "armed", True)
+        )
+        self.client._on_publish(mock_client, None, 12, MagicMock(), None)
+        self.client._drain_callback_queue()
+
+        self.assertEqual(self.client._inflight_retained, {})
+
+        self.client._cleanup_client()
+
+        self.assertEqual(self.client._pending_retained, {})
+
+    def test_already_published_retained_is_not_tracked(self) -> None:
+        """At the default qos 0 paho reports the message as published inline,
+        so there is nothing to wait on."""
+        mock_client = MagicMock()
+        message_info = MagicMock(rc=mqtt.MQTT_ERR_SUCCESS, mid=12)
+        message_info.is_published.return_value = True
+        mock_client.publish.return_value = message_info
+        self.client.client = mock_client
+        self.client.connected = True
+
+        self.client._publish_direct(
+            QueuedPublish("frigate/profile/state", "armed", True)
+        )
+
+        self.assertEqual(self.client._inflight_retained, {})
+
+    def test_wait_for_publish_survives_disconnect_during_wait(self) -> None:
+        mock_client = MagicMock()
+        self.client.client = mock_client
+        self.client.connected = True
+        message_info = MagicMock(rc=mqtt.MQTT_ERR_SUCCESS)
+        message_info.is_published.side_effect = [False, False]
+
+        loop_calls = [0]
+
+        def loop_side_effect(timeout: float) -> int:
+            if loop_calls[0] == 0:
+                self.client._callback_queue.put(("disconnect", 1))
+            loop_calls[0] += 1
+            return mqtt.MQTT_ERR_SUCCESS
+
+        mock_client.loop.side_effect = loop_side_effect
+
+        self.client._wait_for_publish(message_info)
+
+        self.assertEqual(loop_calls[0], 1)
+        self.assertIsNone(self.client.client)
+
+    def test_publish_direct_reconnects_on_recoverable_publish_error(self) -> None:
+        self.client.client = MagicMock()
+        self.client.client.publish.side_effect = BrokenPipeError("broken pipe")
+
+        with patch.object(
+            self.client, "_schedule_reconnect"
+        ) as mock_schedule_reconnect:
+            self.client._publish_direct(
+                QueuedPublish("frigate/profile/state", "armed", True)
+            )
+
+        self.assertEqual(
+            self.client._pending_retained["frigate/profile/state"],
+            ("armed", True),
+        )
+        mock_schedule_reconnect.assert_called_once()
+
+    def test_mqtt_loop_worker_reconnects_on_recoverable_loop_error(self) -> None:
+        self.client.client = MagicMock()
+        self.client.client.loop.side_effect = OSError("socket closed")
+
+        def stop_after_reconnect() -> None:
+            self.client._stop_event.set()
+
+        with patch.object(
+            self.client,
+            "_schedule_reconnect",
+            side_effect=stop_after_reconnect,
+        ) as mock_schedule_reconnect:
+            self.client._mqtt_loop_worker()
+
+        mock_schedule_reconnect.assert_called_once()
+
+    def test_worker_main_goes_dormant_on_unexpected_exception(self) -> None:
+        with patch.object(
+            self.client,
+            "_mqtt_loop_worker",
+            side_effect=RuntimeError("unexpected bug"),
+        ):
+            self.client._worker_main()
+
+        self.assertTrue(self.client._stop_event.is_set())
+        self.assertFalse(self.client.connected)
+        self.assertFalse(self.client._subscription_ready)
+        self.assertIsNone(self.client.client)
+
+    def test_worker_crash_announces_offline_before_disconnecting(self) -> None:
+        """The clean disconnect in cleanup suppresses the will, so a dormant
+        MQTT session must say so itself or consumers keep the stale values."""
+        mock_client = MagicMock()
+        mock_client.publish.return_value = MagicMock(
+            rc=mqtt.MQTT_ERR_SUCCESS, **{"is_published.return_value": True}
+        )
+        self.client.client = mock_client
+        self.client.connected = True
+
+        with patch.object(
+            self.client,
+            "_mqtt_loop_worker",
+            side_effect=RuntimeError("unexpected bug"),
+        ):
+            self.client._worker_main()
+
+        mock_client.publish.assert_called_once_with(
+            "frigate/available",
+            "offline",
+            qos=self.config.mqtt.qos,
+            retain=True,
+        )
+        # the announcement has to land before the socket is torn down
+        self.assertLess(
+            mock_client.method_calls.index(
+                next(c for c in mock_client.method_calls if c[0] == "publish")
+            ),
+            mock_client.method_calls.index(
+                next(c for c in mock_client.method_calls if c[0] == "disconnect")
+            ),
+        )
+
+    def test_worker_crash_stays_dormant_when_offline_publish_fails(self) -> None:
+        self.client.client = MagicMock()
+        self.client.client.publish.side_effect = BrokenPipeError("broken pipe")
+
+        with patch.object(
+            self.client,
+            "_mqtt_loop_worker",
+            side_effect=RuntimeError("unexpected bug"),
+        ):
+            self.client._worker_main()
+
+        self.assertTrue(self.client._stop_event.is_set())
+        self.assertIsNone(self.client.client)
+
+    def test_command_handler_exception_does_not_kill_worker(self) -> None:
+        """A raise in a dispatcher handler used to end the network thread and
+        take MQTT down until the next Frigate restart."""
+        self.client._dispatcher = MagicMock(side_effect=RuntimeError("handler bug"))
+        self.client._callback_queue.put(("message", "front/detect/set", "ON"))
+        self.client._callback_queue.put(("message", "front/motion/set", "ON"))
+
+        with self.assertLogs("frigate.comms.mqtt", level="ERROR"):
+            self.client._drain_callback_queue()
+
+        self.assertEqual(self.client._dispatcher.call_count, 2)
+
+    def test_snapshot_replay_exception_does_not_kill_worker(self) -> None:
+        self.client.connected = True
+        self.client._subscription_mid = 3
+
+        with (
+            patch.object(
+                self.client,
+                "_publish_retained_state",
+                side_effect=RuntimeError("replay bug"),
+            ),
+            self.assertLogs("frigate.comms.mqtt", level="ERROR"),
+        ):
+            self.client._handle_subscribe_event(3, [MagicMock(is_failure=False)])
+
+        self.assertTrue(self.client._subscription_ready)
+
+    def test_schedule_reconnect_drops_stale_ephemeral_and_preserves_retained(
+        self,
+    ) -> None:
+        mock_client = MagicMock()
+        message_info = MagicMock(rc=mqtt.MQTT_ERR_SUCCESS)
+        mock_client.publish.return_value = message_info
+        self.client.client = mock_client
+        self.client.connected = True
+        self.client._subscription_ready = True
+
+        self.client.publish("front/events", "ephemeral")
+        self.client.publish("profile/state", "armed", retain=True)
+
+        self.client._schedule_reconnect()
+
+        self.assertTrue(self.client._publish_queue.empty())
+        self.assertEqual(
+            self.client._pending_retained["frigate/profile/state"],
+            ("armed", True),
+        )
+
+        self.client.client = mock_client
+        self.client.connected = True
+        self.client._subscription_ready = True
+        self.client._drain_publish_queue()
+
+        mock_client.publish.assert_called_once_with(
+            "frigate/profile/state",
+            "armed",
+            qos=self.config.mqtt.qos,
+            retain=True,
+        )
+
+    def test_stop_disconnects_client_and_joins_worker(self) -> None:
+        worker = MagicMock()
+        worker.is_alive.return_value = True
+        self.client._worker = worker
+        mock_client = MagicMock()
+        self.client.client = mock_client
+
+        self.client.stop()
+
+        self.assertTrue(self.client._stop_event.is_set())
+        self.assertGreaterEqual(mock_client.disconnect.call_count, 1)
+        worker.join.assert_called_once()
+
+    def test_stop_skips_stopped_publish_until_subscription_ready(self) -> None:
+        worker = MagicMock()
+        worker.is_alive.return_value = True
+        self.client._worker = worker
+        self.client.client = MagicMock()
+        self.client.connected = True
+        self.client._subscription_ready = False
+
+        with patch.object(self.client._publish_queue, "put") as mock_queue_put:
+            self.client.stop()
+
+        mock_queue_put.assert_not_called()
+
+    def test_duplicate_disconnect_callback_is_safe(self) -> None:
+        self.client.connected = True
+
+        with patch.object(
+            self.client, "_schedule_reconnect"
+        ) as mock_schedule_reconnect:
+            self.client._handle_disconnect_event(MagicMock())
+            self.client._handle_disconnect_event(MagicMock())
+
+        mock_schedule_reconnect.assert_called_once()
+
+    def test_publish_retained_state_emits_expected_topic_families(self) -> None:
+        published_topics: list[tuple[str, Any, bool]] = []
+
+        with patch.object(
+            self.client,
+            "publish",
+            side_effect=lambda topic, payload, retain=False: published_topics.append(
+                (topic, payload, retain)
+            ),
+        ):
+            self.client._publish_retained_state()
+
+        topics = {topic for topic, _, _ in published_topics}
+        self.assertIn("front/enabled/state", topics)
+        self.assertIn("front/motion_mask/motion_mask_1/state", topics)
+        self.assertIn("front/object_mask/object_mask_1/state", topics)
+        self.assertIn("front/zone/driveway/state", topics)
+        self.assertIn("notifications/state", topics)
+        self.assertIn("profile/state", topics)
+        self.assertIn("available", topics)
+
+    def test_publish_retained_state_uses_runtime_values(self) -> None:
+        camera = self.config.cameras["front"]
+        camera.enabled_in_config = True
+        camera.enabled = False
+        camera.record.enabled_in_config = True
+        camera.record.enabled = False
+        camera.audio.enabled_in_config = True
+        camera.audio.enabled = False
+        camera.motion.enabled = False
+        camera.onvif.autotracking.enabled_in_config = True
+        camera.onvif.autotracking.enabled = False
+        camera.review.alerts.enabled_in_config = True
+        camera.review.alerts.enabled = False
+        camera.review.detections.enabled_in_config = True
+        camera.review.detections.enabled = False
+        camera.objects.genai.enabled_in_config = True
+        camera.objects.genai.enabled = False
+        camera.review.genai.enabled_in_config = True
+        camera.review.genai.enabled = False
+        self.config.notifications.enabled_in_config = True
+        self.config.notifications.enabled = False
+
+        published_states: dict[str, Any] = {}
+
+        with patch.object(
+            self.client,
+            "publish",
+            side_effect=lambda topic, payload, retain=False: (
+                published_states.__setitem__(topic, payload)
+            ),
+        ):
+            self.client._publish_retained_state()
+
+        self.assertEqual(published_states["front/enabled/state"], "OFF")
+        self.assertEqual(published_states["front/recordings/state"], "OFF")
+        self.assertEqual(published_states["front/audio/state"], "OFF")
+        self.assertEqual(published_states["front/motion/state"], "OFF")
+        self.assertEqual(published_states["front/ptz_autotracker/state"], "OFF")
+        self.assertEqual(published_states["front/review_alerts/state"], "OFF")
+        self.assertEqual(published_states["front/review_detections/state"], "OFF")
+        self.assertEqual(published_states["front/object_descriptions/state"], "OFF")
+        self.assertEqual(published_states["front/review_descriptions/state"], "OFF")
+        self.assertEqual(published_states["notifications/state"], "OFF")

frigate/test/test_mqtt_topic_registration.py

@@ -1,100 +0,0 @@
-"""Tests for MQTT command topic callback registration."""
-
-import unittest
-from unittest.mock import MagicMock, patch
-
-from frigate.comms.mqtt import MqttClient
-
-
-def _make_camera_mock(
-    *,
-    enabled: bool = True,
-    notifications_enabled_in_config: bool = False,
-) -> MagicMock:
-    """Build a camera config mock with the fields _start() reads."""
-    camera = MagicMock()
-    camera.enabled = enabled
-    camera.notifications.enabled_in_config = notifications_enabled_in_config
-    camera.onvif.host = None
-    camera.motion.mask = {}
-    camera.objects.mask = {}
-    camera.zones = {}
-    return camera
-
-
-def _registered_topics(
-    cameras: dict[str, MagicMock],
-    *,
-    global_notifications_enabled_in_config: bool = False,
-) -> set[str]:
-    """Start an MqttClient against a mocked paho client and collect the
-    topics registered via message_callback_add."""
-    config = MagicMock()
-    config.cameras = cameras
-    config.notifications.enabled_in_config = global_notifications_enabled_in_config
-    config.mqtt.topic_prefix = "frigate"
-    config.mqtt.client_id = "frigate"
-    config.mqtt.user = None
-    config.mqtt.tls_ca_certs = None
-    config.mqtt.tls_insecure = None
-
-    with patch("frigate.comms.mqtt.mqtt.Client") as client_cls:
-        mqtt_client = MqttClient(config)
-        mqtt_client.subscribe(MagicMock())
-
-    paho_client = client_cls.return_value
-    return {call.args[0] for call in paho_client.message_callback_add.call_args_list}
-
-
-class TestMqttTopicRegistration(unittest.TestCase):
-    def test_camera_notification_topics_registered(self):
-        """Per-camera notification set/suspend must be registered so paho
-        routes them to the dispatcher (unregistered topics drop silently)."""
-        topics = _registered_topics(
-            {"front_door": _make_camera_mock(notifications_enabled_in_config=True)}
-        )
-
-        self.assertIn("frigate/front_door/notifications/set", topics)
-        self.assertIn("frigate/front_door/notifications/suspend", topics)
-
-    def test_global_set_registered_with_camera_only_notifications(self):
-        """The global topic must work when notifications are enabled only at
-        the camera level, matching the WebPushClient gating in app.py."""
-        topics = _registered_topics(
-            {"front_door": _make_camera_mock(notifications_enabled_in_config=True)},
-            global_notifications_enabled_in_config=False,
-        )
-
-        self.assertIn("frigate/notifications/set", topics)
-
-    def test_global_set_registered_with_global_notifications(self):
-        topics = _registered_topics(
-            {"front_door": _make_camera_mock()},
-            global_notifications_enabled_in_config=True,
-        )
-
-        self.assertIn("frigate/notifications/set", topics)
-
-    def test_global_set_not_registered_when_notifications_unconfigured(self):
-        topics = _registered_topics(
-            {"front_door": _make_camera_mock()},
-            global_notifications_enabled_in_config=False,
-        )
-
-        self.assertNotIn("frigate/notifications/set", topics)
-
-    def test_disabled_camera_does_not_enable_global_set(self):
-        topics = _registered_topics(
-            {
-                "front_door": _make_camera_mock(
-                    enabled=False, notifications_enabled_in_config=True
-                )
-            },
-            global_notifications_enabled_in_config=False,
-        )
-
-        self.assertNotIn("frigate/notifications/set", topics)
-
-
-if __name__ == "__main__":
-    unittest.main()

frigate/test/test_profiles.py

@@ -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."""
@@ -720,6 +739,53 @@ class TestProfileManager(unittest.TestCase):
         assert "objects" in api_base
         assert api_base["objects"]["track"] == ["person"]
 
+    @patch.object(ProfileManager, "_persist_active_profile")
+    def test_update_config_reapplies_active_profile(self, mock_persist):
+        """Replacing the config preserves the active profile overrides."""
+        self.manager.activate_profile("armed")
+
+        new_config = FrigateConfig(**self.config_data)
+        self.manager.update_config(new_config)
+
+        assert self.manager.config.active_profile == "armed"
+        assert self.manager.config.cameras["front"].notifications.enabled is True
+        assert self.manager.config.cameras["front"].objects.track == [
+            "person",
+            "car",
+            "package",
+        ]
+
+    @patch.object(ProfileManager, "_persist_active_profile")
+    def test_update_config_deactivates_removed_profile(self, mock_persist):
+        """Replacing the config clears the active profile if it no longer exists."""
+        self.manager.activate_profile("armed")
+
+        new_config_data = json.loads(json.dumps(self.config_data))
+        del new_config_data["profiles"]["armed"]
+        del new_config_data["cameras"]["front"]["profiles"]["armed"]
+        del new_config_data["cameras"]["back"]["profiles"]["armed"]
+
+        new_config = FrigateConfig(**new_config_data)
+        self.manager.update_config(new_config)
+
+        assert self.manager.config.active_profile is None
+
+    @patch.object(ProfileManager, "_persist_active_profile")
+    def test_enabled_state_is_published_via_dispatcher_when_profile_changes(
+        self, mock_persist
+    ):
+        """Enabled state updates are published through the dispatcher when present."""
+        self.config.profiles["away"] = ProfileDefinitionConfig(friendly_name="Away")
+        self.config.cameras["front"].profiles["away"] = CameraProfileConfig(
+            enabled=False
+        )
+        dispatcher = MagicMock()
+        self.manager = ProfileManager(self.config, self.mock_updater, dispatcher)
+
+        self.manager.activate_profile("away")
+
+        dispatcher.publish.assert_any_call("front/enabled/state", "OFF", retain=True)
+
     def test_base_configs_for_api_are_json_serializable(self):
         """API base configs are JSON-serializable (mode='json')."""
         import json

frigate/track/object_processing.py

@@ -68,6 +68,7 @@ class TrackedObjectProcessor(threading.Thread):
         self.tracked_objects_queue = tracked_objects_queue
         self.stop_event: MpEvent = stop_event
         self.camera_states: dict[str, CameraState] = {}
+        self.camera_states_lock = threading.Lock()
         self.frame_manager = SharedMemoryFrameManager()
         self.last_motion_detected: dict[str, float] = {}
         self.ptz_autotracker_thread = ptz_autotracker_thread
@@ -236,7 +237,9 @@ class TrackedObjectProcessor(threading.Thread):
         camera_state.on("end", end)
         camera_state.on("snapshot", snapshot)
         camera_state.on("camera_activity", camera_activity)
-        self.camera_states[camera] = camera_state
+
+        with self.camera_states_lock:
+            self.camera_states[camera] = camera_state
 
     def should_save_snapshot(self, camera: str, obj: TrackedObject) -> bool:
         if obj.false_positive:
@@ -324,9 +327,22 @@ class TrackedObjectProcessor(threading.Thread):
                 # reset the last_motion so redundant `off` commands aren't sent
                 self.last_motion_detected[camera] = 0
 
+    def get_camera_state(self, camera: str) -> CameraState | None:
+        """Returns the state for a camera, or None if it does not exist."""
+        with self.camera_states_lock:
+            return self.camera_states.get(camera)
+
+    def get_camera_states(self) -> list[CameraState]:
+        """Returns a snapshot of camera states that is safe to iterate."""
+        with self.camera_states_lock:
+            return list(self.camera_states.values())
+
     def get_best(self, camera: str, label: str) -> dict[str, Any]:
-        # TODO: need a lock here
-        camera_state = self.camera_states[camera]
+        camera_state = self.get_camera_state(camera)
+
+        if camera_state is None:
+            return {}
+
         if label in camera_state.best_objects:
             best_obj = camera_state.best_objects[label]
 
@@ -350,17 +366,21 @@ class TrackedObjectProcessor(threading.Thread):
                 (self.config.birdseye.height * 3 // 2, self.config.birdseye.width),
             )
 
-        if camera not in self.camera_states:
+        camera_state = self.get_camera_state(camera)
+
+        if camera_state is None:
             return None
 
-        return self.camera_states[camera].get_current_frame(draw_options)
+        return camera_state.get_current_frame(draw_options)
 
     def get_current_frame_time(self, camera: str) -> float:
         """Returns the latest frame time for a given camera."""
-        if camera not in self.camera_states:
+        camera_state = self.get_camera_state(camera)
+
+        if camera_state is None:
             return 0.0
 
-        return self.camera_states[camera].current_frame_time
+        return camera_state.current_frame_time
 
     def set_sub_label(
         self, event_id: str, sub_label: str | None, score: float | None
@@ -498,14 +518,18 @@ class TrackedObjectProcessor(threading.Thread):
         # save the snapshot image
         (frame, event_id, camera) = payload
 
+        camera_state = self.camera_states.get(camera)
+
+        if camera_state is None:
+            logger.debug("Discarding LPR snapshot for unknown camera %s", camera)
+            return
+
         img = cv2.imdecode(
             np.frombuffer(base64.b64decode(frame), dtype=np.uint8),
             cv2.IMREAD_COLOR,
         )
 
-        self.camera_states[camera].save_manual_event_image(
-            img, event_id, "license_plate", {}
-        )
+        camera_state.save_manual_event_image(img, event_id, "license_plate", {})
 
     def create_manual_event(self, payload: tuple) -> None:
         (
@@ -522,13 +546,17 @@ class TrackedObjectProcessor(threading.Thread):
             pre_capture,
         ) = payload
 
+        camera_state = self.camera_states.get(camera_name)
+
+        if camera_state is None:
+            logger.debug("Discarding manual event for unknown camera %s", camera_name)
+            return
+
         # save the snapshot image
-        self.camera_states[camera_name].save_manual_event_image(
-            None, event_id, label, draw
-        )
+        camera_state.save_manual_event_image(None, event_id, label, draw)
         end_time = frame_time + duration if duration is not None else None
         start_time = (
-            frame_time - self.config.cameras[camera_name].record.event_pre_capture
+            frame_time - camera_state.camera_config.record.event_pre_capture
             if pre_capture is None
             else frame_time - pre_capture
         )
@@ -548,7 +576,7 @@ class TrackedObjectProcessor(threading.Thread):
                     "camera": camera_name,
                     "start_time": start_time,
                     "end_time": end_time,
-                    "has_clip": self.config.cameras[camera_name].record.enabled
+                    "has_clip": camera_state.camera_config.record.enabled
                     and include_recording,
                     "has_snapshot": True,
                     "snapshot_clean": True,
@@ -591,6 +619,12 @@ class TrackedObjectProcessor(threading.Thread):
             plate,
         ) = payload
 
+        camera_state = self.camera_states.get(camera_name)
+
+        if camera_state is None:
+            logger.debug("Discarding LPR event for unknown camera %s", camera_name)
+            return
+
         # send event to event maintainer
         self.event_sender.publish(
             (
@@ -605,9 +639,9 @@ class TrackedObjectProcessor(threading.Thread):
                     "score": score,
                     "camera": camera_name,
                     "start_time": frame_time
-                    - self.config.cameras[camera_name].record.event_pre_capture,
+                    - camera_state.camera_config.record.event_pre_capture,
                     "end_time": None,
-                    "has_clip": self.config.cameras[camera_name].record.enabled
+                    "has_clip": camera_state.camera_config.record.enabled
                     and include_recording,
                     "has_snapshot": True,
                     "snapshot_clean": True,
@@ -699,7 +733,10 @@ class TrackedObjectProcessor(threading.Thread):
                         continue
 
                     camera_state.shutdown()
-                    self.camera_states.pop(camera)
+
+                    with self.camera_states_lock:
+                        self.camera_states.pop(camera)
+
                     self.camera_activity.pop(camera, None)
                     self.last_motion_detected.pop(camera, None)
 
@@ -715,8 +752,6 @@ class TrackedObjectProcessor(threading.Thread):
                 if camera_state is None:
                     continue
 
-                camera_state = self.camera_states[camera]
-
                 if camera_state.prev_enabled and not current_enabled:
                     logger.debug(f"Not processing objects for disabled camera {camera}")
                     self.force_end_all_events(camera, camera_state)
@@ -812,7 +847,11 @@ class TrackedObjectProcessor(threading.Thread):
                     break
 
                 event_id, camera, _ = update
-                self.camera_states[camera].finished(event_id)
+                camera_state = self.camera_states.get(camera)
+
+                # the camera may have been removed while its event was pending
+                if camera_state is not None:
+                    camera_state.finished(event_id)
 
         # shut down camera states
         for state in self.camera_states.values():

frigate/util/config.py

@@ -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],

frigate/util/object_names.py

@@ -0,0 +1,209 @@
+"""Aggregation of the known sub label names an object can be tagged with."""
+
+import logging
+import os
+
+from pathvalidate import sanitize_filename
+
+from frigate.config import FrigateConfig
+from frigate.config.classification import ObjectClassificationType
+from frigate.const import CLIPS_DIR, FACE_DIR, MODEL_CACHE_DIR
+from frigate.util.builtin import load_labels
+
+logger = logging.getLogger(__name__)
+
+# subdirectory of FACE_DIR holding unassigned training images, not a face name
+FACE_TRAIN_DIR = "train"
+
+# category used by classification models for "no match", never attached to an object
+CLASSIFICATION_NONE_CATEGORY = "none"
+
+
+def get_categorized_object_names(
+    config: FrigateConfig,
+    allowed_cameras: list[str],
+    object_type: str | None = None,
+) -> dict[str, list[str]]:
+    """Collect every sub label name this install can attach, by object type.
+
+    Unlike the database-backed /sub_labels endpoint, this reads the config and
+    model files, so it also covers names that are configured but have not been
+    detected yet. Names come from the detector's logo attributes (limited to
+    objects the allowed cameras actually track), LPR known plate names,
+    registered face names, and custom object classification categories.
+
+    Structural attributes such as `face` and `license_plate` are excluded: they
+    describe a part of an object rather than naming it, and are never attached
+    as a sub label.
+
+    Args:
+        config: The running Frigate config
+        allowed_cameras: Cameras the requesting user may see
+        object_type: Optional object label to restrict the result to
+
+    Returns:
+        Mapping of object label to its known sub label names, sorted and
+        deduplicated. Object types with no known names are omitted.
+    """
+    tracked_objects = _get_tracked_objects(config, allowed_cameras)
+    names: dict[str, set[str]] = {}
+    logos = set(config.model.all_attribute_logos)
+
+    # 1. detector logo attributes, only for objects that are actually tracked
+    for label, label_attributes in config.model.attributes_map.items():
+        if label not in tracked_objects:
+            continue
+
+        label_logos = logos.intersection(label_attributes)
+
+        if label_logos:
+            names.setdefault(label, set()).update(label_logos)
+
+    # 2. LPR known plate names, for objects that can carry a plate
+    if config.lpr.known_plates and _lpr_enabled(config, allowed_cameras):
+        known_plates = set(config.lpr.known_plates)
+
+        for label in _objects_with_attribute(config, tracked_objects, "license_plate"):
+            names.setdefault(label, set()).update(known_plates)
+
+    # 3. registered face names, for objects that can carry a face
+    if _face_recognition_enabled(config, allowed_cameras):
+        face_names = _get_face_names()
+
+        if face_names:
+            for label in _objects_with_attribute(config, tracked_objects, "face"):
+                names.setdefault(label, set()).update(face_names)
+
+    # 4. custom object classification categories
+    for model_key, model_config in config.classification.custom.items():
+        if not model_config.enabled or model_config.object_config is None:
+            continue
+
+        if (
+            model_config.object_config.classification_type
+            != ObjectClassificationType.sub_label
+        ):
+            continue
+
+        categories = _get_classification_categories(model_key)
+
+        if not categories:
+            continue
+
+        for label in model_config.object_config.objects:
+            names.setdefault(label, set()).update(categories)
+
+    return {
+        label: sorted(label_names)
+        for label, label_names in sorted(names.items())
+        if label_names and (object_type is None or label == object_type)
+    }
+
+
+def _get_tracked_objects(config: FrigateConfig, allowed_cameras: list[str]) -> set[str]:
+    """Get the union of objects tracked by the cameras the user can see."""
+    tracked: set[str] = set()
+
+    for camera_name in allowed_cameras:
+        camera_config = config.cameras.get(camera_name)
+
+        if camera_config is None:
+            continue
+
+        tracked.update(camera_config.objects.track)
+
+    return tracked
+
+
+def _objects_with_attribute(
+    config: FrigateConfig, tracked_objects: set[str], attribute: str
+) -> set[str]:
+    """Get the tracked objects that a given attribute can be recognized on.
+
+    The attribute may also be tracked as an object in its own right, as
+    `license_plate` is on a dedicated LPR camera, in which case the name is
+    attached to that object directly.
+    """
+    objects = {
+        label
+        for label, label_attributes in config.model.attributes_map.items()
+        if attribute in label_attributes and label in tracked_objects
+    }
+
+    if attribute in tracked_objects:
+        objects.add(attribute)
+
+    return objects
+
+
+def _lpr_enabled(config: FrigateConfig, allowed_cameras: list[str]) -> bool:
+    return any(
+        config.cameras[camera_name].lpr.enabled
+        for camera_name in allowed_cameras
+        if camera_name in config.cameras
+    )
+
+
+def _face_recognition_enabled(
+    config: FrigateConfig, allowed_cameras: list[str]
+) -> bool:
+    return any(
+        config.cameras[camera_name].face_recognition.enabled
+        for camera_name in allowed_cameras
+        if camera_name in config.cameras
+    )
+
+
+def _get_face_names() -> set[str]:
+    """Get the names of every registered face collection."""
+    if not os.path.exists(FACE_DIR):
+        return set()
+
+    try:
+        entries = os.listdir(FACE_DIR)
+    except OSError:
+        logger.debug("Failed to read face directory %s", FACE_DIR)
+        return set()
+
+    return {
+        name
+        for name in entries
+        if name != FACE_TRAIN_DIR and os.path.isdir(os.path.join(FACE_DIR, name))
+    }
+
+
+def _get_classification_categories(model_key: str) -> set[str]:
+    """Get the categories a custom classification model can output.
+
+    The trained labelmap is authoritative, but it only exists once the model
+    has been trained, so fall back to the dataset directories that will become
+    the labelmap on the next training run.
+    """
+    safe_key = sanitize_filename(model_key)
+    categories: set[str] = set()
+    labelmap_path = os.path.join(MODEL_CACHE_DIR, safe_key, "labelmap.txt")
+
+    if os.path.exists(labelmap_path):
+        try:
+            labelmap = load_labels(labelmap_path, prefill=0, indexed=False)
+        except OSError:
+            logger.debug("Failed to read labelmap %s", labelmap_path)
+            labelmap = {}
+
+        categories.update(label for label in labelmap.values() if label)
+
+    dataset_dir = os.path.join(CLIPS_DIR, safe_key, "dataset")
+
+    if os.path.exists(dataset_dir):
+        try:
+            entries = os.listdir(dataset_dir)
+        except OSError:
+            logger.debug("Failed to read dataset directory %s", dataset_dir)
+            entries = []
+
+        categories.update(
+            name for name in entries if os.path.isdir(os.path.join(dataset_dir, name))
+        )
+
+    categories.discard(CLASSIFICATION_NONE_CATEGORY)
+    return categories

frigate/util/services.py

@@ -1,6 +1,7 @@
 """Utilities for services."""
 
 import asyncio
+import glob
 import json
 import logging
 import os
@@ -670,19 +671,33 @@ def get_intel_gpu_stats(
 
 def get_openvino_npu_stats() -> dict[str, str] | None:
     """Get NPU stats using openvino."""
-    NPU_RUNTIME_PATH = "/sys/devices/pci0000:00/0000:00:0b.0/power/runtime_active_time"
+    for accel_path in sorted(glob.glob("/sys/class/accel/accel*")):
+        try:
+            driver = os.path.basename(os.readlink(f"{accel_path}/device/driver"))
+        except OSError:
+            continue
+
+        if driver != "intel_vpu":
+            continue
+
+        try:
+            runtime_path = f"{accel_path}/device/power/runtime_active_time"
+            with open(runtime_path) as f:
+                initial_runtime = float(f.read().strip())
+            break
+        except (FileNotFoundError, PermissionError, ValueError):
+            continue
+    else:
+        return None
 
     try:
-        with open(NPU_RUNTIME_PATH) as f:
-            initial_runtime = float(f.read().strip())
-
         initial_time = time.time()
 
         # Sleep for 1 second to get an accurate reading
         time.sleep(1.0)
 
         # Read runtime value again
-        with open(NPU_RUNTIME_PATH) as f:
+        with open(runtime_path) as f:
             current_runtime = float(f.read().strip())
 
         current_time = time.time()

web/public/locales/en/config/cameras.json

@@ -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",

web/public/locales/en/config/global.json

@@ -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",

web/public/locales/en/views/settings.json

@@ -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."

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

@@ -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" },
       },
     },

web/src/types/frigateConfig.ts

@@ -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: {