Add audio labelmap grouping (#24004)

Allow audio classes to be grouped under a shared configured label.

Keep audio overrides separate from object labels and retain only the highest-scoring grouped detection.

Refs #23967

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

docker/main/rootfs/usr/local/nginx/conf/nginx.conf

@@ -75,6 +75,12 @@ http {
         vod_align_segments_to_key_frames on;
         vod_manifest_segment_durations_mode accurate;
         vod_ignore_edit_list on;
+        # short leading segments at each playlist start; sources start at
+        # the seek target, so the ladder applies to every seek. Only
+        # effective when clips declare real keyFrameDurations
+        vod_bootstrap_segment_durations 1000;
+        vod_bootstrap_segment_durations 2000;
+        vod_bootstrap_segment_durations 4000;
         vod_segment_duration 10000;
 
         # MPEG-TS settings (not used when fMP4 is enabled, kept for reference)

docs/docs/configuration/advanced/reference.md

@@ -217,6 +217,8 @@ audio:
     - fire_alarm
     - speech
     - yell
+  # Optional: Audio label name modifications. These are merged into the standard audio labelmap.
+  labelmap: {}
   # Optional: Filters to configure detection.
   filters:
     # Label that matches label in listen config.
@@ -251,11 +253,15 @@ 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 listed at the same time.
+  #   continuous:  all cameras are included always
+  #   motion:      included if motion was detected within the inactivity threshold
+  #   all_objects: included if a tracked object was present within the inactivity threshold
+  #   alerts:      included while an alert review item is in progress
+  #   detections:  included while a detection review item is in progress
+  modes:
+    - all_objects
   # Optional: Threshold for camera activity to stop showing camera (default: shown below)
   inactivity_threshold: 30
   # Optional: Configure the birdseye layout
@@ -287,6 +293,8 @@ ffmpeg:
     detect: -threads 2 -f rawvideo -pix_fmt yuv420p
     # Optional: output args for record streams (default: shown below)
     record: preset-record-generic
+    # Optional: output args for sub stream record streams (default: the record output args above)
+    # record_sub: preset-record-generic
   # Optional: Time in seconds to wait before ffmpeg retries connecting to the camera. (default: shown below)
   # If set too low, frigate will retry a connection to the camera's stream too frequently, using up the limited streams some cameras can allow at once
   # If set too high, then if a ffmpeg crash or camera stream timeout occurs, you could potentially lose up to a maximum of retry_interval second(s) of footage
@@ -637,6 +645,42 @@ record:
       #       For example, if the camera retain mode is "motion", the segments without motion are
       #       never stored, so setting the mode to "all" here won't bring them back.
       mode: motion
+  # Optional: Sub stream recording settings
+  # Records a second, lower quality stream for quality selection during playback
+  # and extended low quality retention. Requires the record_sub role to be assigned
+  # to one of the camera's inputs.
+  sub:
+    # Optional: Enable sub stream recording (default: shown below)
+    # NOTE: Recording must also be enabled for sub stream recording to run.
+    enabled: False
+    # Optional: Continuous retention settings for sub stream recordings
+    continuous:
+      # Optional: Number of days to retain sub stream recordings regardless of tracked objects or motion (default: shown below)
+      days: 0
+    # Optional: Motion retention settings for sub stream recordings
+    motion:
+      # Optional: Number of days to retain sub stream recordings triggered by motion (default: shown below)
+      days: 0
+    # Optional: Retention settings for sub stream recordings of alerts
+    # NOTE: Pre and post capture windows are taken from the main alerts config above.
+    alerts:
+      # Required: Retention days (default: shown below)
+      days: 10
+      # Optional: Mode for retention. (default: shown below)
+      #   all - save all sub stream recording segments for alerts regardless of activity
+      #   motion - save all sub stream recording segments for alerts with any detected motion
+      #   active_objects - save all sub stream recording segments for alerts with active/moving objects
+      mode: motion
+    # Optional: Retention settings for sub stream recordings of detections
+    # NOTE: Pre and post capture windows are taken from the main detections config above.
+    detections:
+      # Required: Retention days (default: shown below)
+      days: 10
+      # Optional: Mode for retention. (default: shown below)
+      #   all - save all sub stream recording segments for detections regardless of activity
+      #   motion - save all sub stream recording segments for detections with any detected motion
+      #   active_objects - save all sub stream recording segments for detections with active/moving objects
+      mode: motion
 
 # Optional: Configuration for the snapshots written to the clips directory for each tracked object
 # Timestamp, bounding_box, crop and height settings are applied by default to API requests for snapshots.
@@ -888,7 +932,7 @@ cameras:
         # Required: the path to the stream
         # NOTE: path may include environment variables or docker secrets, which must begin with 'FRIGATE_' and be referenced in {}
         - path: rtsp://viewer:{FRIGATE_RTSP_PASSWORD}@10.0.10.10:554/cam/realmonitor?channel=1&subtype=2
-          # Required: list of roles for this stream. valid values are: audio,detect,record
+          # Required: list of roles for this stream. valid values are: audio,detect,record,record_sub
           # NOTICE: In addition to assigning the audio, detect, and record roles
           # they must also be enabled in the camera config.
           roles:

docs/docs/configuration/audio_detectors.md

@@ -114,6 +114,30 @@ audio:
 </TabItem>
 </ConfigTabs>
 
+#### Grouping Audio Labels
+
+Related audio classes can be grouped under one label by mapping their numeric
+class IDs to the same name. Add the grouped name to `listen` and use it for any
+corresponding filter:
+
+```yaml
+audio:
+  listen:
+    - dogs
+  labelmap:
+    69: dogs # dog
+    70: dogs # bark
+    75: dogs # whimper_dog
+  filters:
+    dogs:
+      threshold: 0.8
+```
+
+Class IDs are zero-based indices in
+[`audio-labelmap.txt`](https://github.com/blakeblackshear/frigate/blob/dev/audio-labelmap.txt),
+so each ID is one less than the displayed file line number.
+Audio label mappings are separate from the object detector's `model.labelmap`.
+
 ### Common Audio Labels
 
 The labelmap includes hundreds of sound types. The labels below are the ones most users may find practical, grouped by what they're typically used for. Use the exact label string from the left column in your `listen` config, or search for the label in the Frigate UI directly.

docs/docs/configuration/birdseye.md

@@ -18,13 +18,17 @@ 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 listed 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
+- **all_objects:** The camera is included when a tracked object is present, active or stationary
+- **alerts:** The camera is included while an alert review item is in progress
+- **detections:** The camera is included while a detection review item is in progress
+
+`alerts` and `detections` follow the review item's own lifetime, so the camera is removed as soon as the review item ends. Which objects qualify for each is set in [review configuration](./review.md).
 
 ### Custom Birdseye Icon
 
@@ -39,27 +43,29 @@ 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 {10-12,15-16}
 # Include all cameras by default in Birdseye view
 birdseye:
   enabled: True
-  mode: continuous
+  modes:
+    - continuous
 
 cameras:
   front:
-    # Only include the "front" camera in Birdseye view when objects are detected
+    # Only include the "front" camera in Birdseye view when an alert is in progress
     birdseye:
-      mode: objects
+      modes:
+        - alerts
   back:
     # Exclude the "back" camera from Birdseye view
     birdseye:
@@ -71,7 +77,7 @@ cameras:
 
 ### Birdseye Inactivity
 
-By default birdseye shows all cameras that have had the configured activity in the last 30 seconds. This threshold can be configured.
+By default birdseye shows all cameras that have had the configured activity in the last 30 seconds. This threshold can be configured, and applies to the `motion` and `all_objects` activity types only.
 
 <ConfigTabs>
 <TabItem value="ui">
@@ -140,7 +146,8 @@ Navigate to <NavPath path="Settings > System > Birdseye" /> and in the **Camera
 # Include all cameras by default in Birdseye view
 birdseye:
   enabled: True
-  mode: continuous
+  modes:
+    - continuous
 
 cameras:
   front:

docs/docs/configuration/ffmpeg_presets.md

@@ -106,3 +106,5 @@ Output arguments are passed to FFmpeg after your camera source and control how r
 | preset-record-mjpeg              | Record - MJPEG Cameras          | Record an MJPEG stream              | Restreaming the MJPEG stream is recommended instead                                                                                                               |
 | preset-record-jpeg               | Record - JPEG Cameras           | Record a live JPEG                  | Restreaming the live JPEG is recommended instead                                                                                                                  |
 | preset-record-ubiquiti           | Record - Ubiquiti Cameras       | Record a Ubiquiti stream with audio | Handles Ubiquiti's non-standard audio format                                                                                                                      |
+
+These presets apply to the `record` output args. If [sub stream recording](/configuration/record#sub-stream-recording) is enabled, the same args are used for the `record_sub` role unless `output_args.record_sub` is set, which accepts the same presets and manual args.

docs/docs/configuration/record.md

@@ -275,6 +275,163 @@ record:
 
 This configuration will retain recording segments that overlap with alerts and detections for 10 days. Because multiple tracked objects can reference the same recording segments, this avoids storing duplicate footage for overlapping tracked objects and reduces overall storage needs.
 
+## Sub Stream Recording
+
+In addition to the main recording stream, Frigate can record a second, lower quality stream for each camera. This serves two purposes:
+
+- **Quality selection during playback**: A quality selector (`Auto`, `Original`, or `Low`) appears in History view for cameras with sub stream recording enabled. `Original` and `Low` play only that stream's recordings. Time ranges where the selected stream has no footage are skipped during playback, and the selector notes when the selected stream has no recordings at all in the viewed time range. With `Auto` (the default), playback prefers the original quality and automatically falls back to the low quality stream when the connection cannot keep up, or for time ranges where the original recordings have expired. The selector shows each stream's video codec and audio details beneath the options; footage recorded by older Frigate versions shows no details.
+- **Extended retention**: Sub stream recordings have their own retention settings, fully independent of the main recordings. By giving the low quality recordings a longer retention period, you can keep weeks or months of low quality history using a fraction of the storage, and that history remains playable after the main recordings expire. Playback falls back to the low quality recordings automatically, and the timeline shows a muted treatment for time ranges where only low quality footage remains.
+
+### Configuring sub stream recording
+
+Sub stream recording uses the `record_sub` input role. This role can be assigned to the same input as `detect`, so in the common case where detect already uses the camera's sub stream, no additional camera connection is needed. Like the main recording stream, sub stream segments are copied directly from the camera stream without re-encoding, so the recording quality is determined by the source stream.
+
+The following examples keep 7 days of full quality continuous recordings and 60 days of low quality continuous recordings:
+
+<ConfigTabs>
+<TabItem value="ui">
+
+Navigate to <NavPath path="Settings > Camera configuration > Streams (FFmpeg)" /> and select the camera.
+
+- In **Camera inputs**, enable the **Record (Sub Stream)** role on the stream you want to record at low quality, commonly the same stream that has the **Detect** role. Only one stream may have this role, and it cannot be assigned to the same stream as the **Record** role.
+
+Navigate to <NavPath path="Settings > Camera configuration > Recording" /> and select the camera.
+
+- Set **Enable recording** to on
+- Set **Continuous retention > Retention days** to `7`
+- Set **Sub stream recording > Enable sub stream recording** to on
+- Set **Sub stream recording > Sub stream continuous retention > Retention days** to `60`
+
+The camera setup wizard also offers the **Record (Sub Stream)** role when assigning stream roles for a newly added camera.
+
+</TabItem>
+<TabItem value="yaml">
+
+```yaml
+cameras:
+  front_door:
+    ffmpeg:
+      inputs:
+        - path: rtsp://camera/main
+          roles:
+            - record
+        - path: rtsp://camera/sub
+          roles:
+            - detect
+            - record_sub
+    record:
+      enabled: true
+      continuous:
+        days: 7
+      sub:
+        enabled: true
+        continuous:
+          days: 60
+```
+
+If your camera does not provide a suitable sub stream (or the sub stream is already used at a resolution you don't want to record), you can use a go2rtc transcode as the source for `record_sub` instead:
+
+```yaml
+go2rtc:
+  streams:
+    front_door: rtsp://camera/main
+    front_door_lq: ffmpeg:front_door#video=h264#width=854#hardware
+
+cameras:
+  front_door:
+    ffmpeg:
+      inputs:
+        - path: rtsp://127.0.0.1:8554/front_door
+          input_args: preset-rtsp-restream
+          roles:
+            - detect
+            - record
+        - path: rtsp://127.0.0.1:8554/front_door_lq
+          input_args: preset-rtsp-restream
+          roles:
+            - record_sub
+    record:
+      enabled: true
+      continuous:
+        days: 7
+      sub:
+        enabled: true
+        continuous:
+          days: 60
+```
+
+</TabItem>
+</ConfigTabs>
+
+The `record.sub` config supports the same retention structure as the main recording config: `continuous`, `motion`, `alerts`, and `detections` each with their own `days` (and `mode` for alerts and detections). The pre-capture and post-capture windows for alerts and detections are taken from the main `record.alerts` and `record.detections` config. Extending `sub.alerts.days` or `sub.detections.days` beyond the main values also keeps those review items visible in the review timeline for the longer window, with playback falling back to the low quality stream once the main recordings expire.
+
+:::note
+
+Recording must be enabled (`record.enabled`) for sub stream recording to run, and Frigate will fail to start if `record.sub.enabled` is set without a `record_sub` role assigned to one of the camera's inputs.
+
+:::
+
+### How Auto picks a quality
+
+`Auto` measures throughput on every segment download and compares it against the original stream's bitrate (computed from the recorded footage itself). Playback drops to the low quality stream when any of these happen:
+
+- A freeze lasts 4 seconds (10 seconds when it starts within 2 seconds of a seek, since the seek target is rarely buffered), or freezes total 7 seconds within the last minute.
+- 3 downloads in a row measure below the original bitrate plus 10%, dropping quality before a stall ever becomes visible.
+- No first frame appears within 10 seconds, or loading fails outright.
+
+Playback returns to full quality only when measured throughput exceeds the original bitrate by 50%, checked continuously while playing the low quality stream and again at each new hour. The asymmetric thresholds (1.1x to drop, 1.5x to return) keep a borderline connection from switching back and forth.
+
+The most recent measurement is remembered on the device: a connection last measured below the original bitrate (or below 3 Mbps when the bitrate is not yet known) starts playback on the low quality stream so a first frame appears immediately, then upgrades within a few segments if the speed allows.
+
+The quality selector shows which stream Auto is currently playing and why. A browser with Data Saver enabled stays on the low quality stream, a browser that cannot decode the original stream's codec (for example H.265 without HEVC support) plays the low quality stream for that camera, and pinning `Original` or `Low` bypasses Auto entirely.
+
+### Sub stream output args
+
+By default the sub stream is recorded with the same [output args](/configuration/ffmpeg_presets#output-args-presets) as the main recording stream, so it inherits any customization made to `ffmpeg.output_args.record`. Setting `ffmpeg.output_args.record_sub` gives the sub stream its own args instead. Like all `ffmpeg` config, this can be set globally or per camera.
+
+The most common reason to set this is a pair of streams whose audio differs. Many cameras send AAC on the main stream but PCM on the sub stream, and PCM cannot be copied into an mp4 recording. Copying the main stream's audio avoids re-encoding audio that is already AAC, while the sub stream still needs to be transcoded:
+
+```yaml
+ffmpeg:
+  output_args:
+    # main stream audio is already AAC, so copy it
+    record: preset-record-generic-audio-copy
+    # sub stream audio is PCM, so transcode it to AAC
+    record_sub: preset-record-generic-audio-aac
+```
+
+Other reasons to set this are recording a sub stream whose codec needs a different preset than the main stream, such as `preset-record-mjpeg`, or forcing a matching audio sample rate across the two streams with manual args ending in `-c:a aac -ar 16000`.
+
+:::warning
+
+Avoid removing audio from only one of the two streams (for example with `-an`). When one stream has audio and the other does not, playback of time ranges that combine both qualities is silent, so stripping audio from the sub stream also silences the merged timeline.
+
+:::
+
+### Which stream do features use?
+
+As a general rule, features that read recordings prefer the main stream and fall back to the sub stream for time ranges where the main recordings have expired. Analytics features use only the main stream.
+
+| Feature                                                                                  | Stream used                                                                                                   |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Recording playback (History and Review)                                                  | Both (main preferred with sub fallback by default), or exactly one stream when a quality is selected manually |
+| Tracking details and Explore clip playback                                               | Main, falling back to sub where the main recordings have expired                                              |
+| Exports and clip downloads                                                               | Main; sub is used when no main recordings remain in the range (streams are never mixed in one file)           |
+| Frames grabbed from a recording in History (download snapshot, submit frame to Frigate+) | Main preferred, sub fallback                                                                                  |
+| Audio extraction (e.g., transcription)                                                   | Main preferred, sub fallback                                                                                  |
+| Motion search                                                                            | Main only                                                                                                     |
+| Review timeline motion data                                                              | Main only                                                                                                     |
+| Storage usage statistics                                                                 | Both streams counted, and listed separately per camera                                                        |
+
+This table covers only features that read recordings from disk. Tracked object snapshots and thumbnails (the images shown in Explore and sent with notifications, and the images submitted to Frigate+ from a tracked object) are captured live from the `detect` stream as the object is tracked, never from recordings, so sub stream recording does not affect them.
+
+### Trade-offs
+
+- Recording a second stream increases overall storage use. The increase is typically small relative to the main recordings, since the low quality stream is much smaller.
+- The go2rtc transcode approach continuously encodes the low quality stream, which uses CPU or GPU resources. This cost only applies to the transcode path; recording the camera's native sub stream does not re-encode. See the [go2rtc hardware acceleration documentation](https://github.com/AlexxIT/go2rtc?tab=readme-ov-file#source-ffmpeg) for accelerating the transcode.
+- Many camera sub streams do not include audio. If the source stream has no audio, the low quality recordings will not have audio.
+- **Matching video codecs and audio settings between the two streams gives the smoothest playback.** When playback combines both qualities on one timeline (the default `Auto` behavior: for example original quality during events with low quality in between, or low quality history after the original recordings expire) and the streams use different video codecs or audio settings, for example H.265 on the main stream and H.264 on the sub stream, or 16 kHz audio on one and 8 kHz on the other, playback still works: Frigate inserts a decoder reset at each quality transition, which can cause a barely-perceptible pause there. Configuring both streams in the camera's firmware to use the same video codec, audio codec, and sample rate makes transitions fully seamless, and a mismatched audio sample rate can also be corrected with [sub stream output args](#sub-stream-output-args). If one stream has audio and the other does not, combined time ranges play **without audio**; selecting a single quality with the playback selector always keeps that stream's audio.
+
 ## Can I have "continuous" recordings, but only at certain times?
 
 Using Frigate UI, Home Assistant, or MQTT, cameras can be automated to only record in certain situations or at certain times.

docs/docs/integrations/mqtt.md

@@ -553,22 +553,25 @@ must be enabled in the configuration.
 
 Topic with current state of Birdseye for a camera. Published values are `ON` and `OFF`.
 
-### `frigate/<camera_name>/birdseye_mode/set`
+### `frigate/<camera_name>/birdseye_modes/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,ALERTS`.
 
-_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          |
+| `ALL_OBJECTS` | Shown if a tracked object was present within the last 30 seconds |
+| `ALERTS`      | Shown while an alert review item is in progress                  |
+| `DETECTIONS`  | Shown while a detection review item is in progress               |
+| `NONE`        | Never included                                                   |
 
-### `frigate/<camera_name>/birdseye_mode/state`
+### `frigate/<camera_name>/birdseye_modes/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 `CONTINUOUS`, `MOTION`, `ALL_OBJECTS`, `ALERTS`, `DETECTIONS`. `NONE` is published when no activity types are enabled.
 
 ### `frigate/<camera_name>/notifications/set`
 

docs/static/frigate-api.yaml

@@ -713,7 +713,7 @@ paths:
         | `improve_contrast` | `ON`, `OFF` |
         | `ptz_autotracker` | `ON`, `OFF` |
         | `birdseye` | `ON`, `OFF` |
-        | `birdseye_mode` | `CONTINUOUS`, `MOTION`, `OBJECTS` |
+        | `birdseye_modes` | `CONTINUOUS`, `MOTION`, `ALL_OBJECTS`, `ALERTS`, `DETECTIONS`, `NONE`, or a comma-separated combination |
         | `motion_contour_area` | integer |
         | `motion_threshold` | integer |
         | `motion_mask` | `ON`, `OFF` |
@@ -803,7 +803,7 @@ paths:
         | `improve_contrast` | `ON`, `OFF` |
         | `ptz_autotracker` | `ON`, `OFF` |
         | `birdseye` | `ON`, `OFF` |
-        | `birdseye_mode` | `CONTINUOUS`, `MOTION`, `OBJECTS` |
+        | `birdseye_modes` | `CONTINUOUS`, `MOTION`, `ALL_OBJECTS`, `ALERTS`, `DETECTIONS`, `NONE`, or a comma-separated combination |
         | `motion_contour_area` | integer |
         | `motion_threshold` | integer |
         | `motion_mask` | `ON`, `OFF` |
@@ -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:
@@ -5984,6 +6022,65 @@ paths:
       security:
         - frigateUserAuth: []
       x-required-role: camera
+  /vod/{camera_name}/{stream}/start/{start_ts}/end/{end_ts}:
+    get:
+      tags:
+        - Media
+      summary: Vod Ts Stream
+      description: |-
+        **Access:** Authenticated user with access to the referenced camera.
+
+        Returns an HLS playlist pinned to one stream type (main or sub) for the specified timestamp-range on the specified camera. Append /master.m3u8 or /index.m3u8 for HLS playback.
+      operationId: 
+        vod_ts_stream_vod__camera_name___stream__start__start_ts__end__end_ts__get
+      parameters:
+        - name: camera_name
+          in: path
+          required: true
+          schema:
+            anyOf:
+              - type: string
+              - type: 'null'
+            title: Camera Name
+        - name: stream
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/VodStreamPreference'
+        - name: start_ts
+          in: path
+          required: true
+          schema:
+            type: number
+            title: Start Ts
+        - name: end_ts
+          in: path
+          required: true
+          schema:
+            type: number
+            title: End Ts
+        - name: force_discontinuity
+          in: query
+          required: false
+          schema:
+            type: boolean
+            default: false
+            title: Force Discontinuity
+      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: camera
   /events/{event_id}/snapshot.jpg:
     get:
       tags:
@@ -6922,6 +7019,63 @@ paths:
       security:
         - frigateUserAuth: []
       x-required-role: camera
+  /{camera_name}/recordings/coverage:
+    get:
+      tags:
+        - Recordings
+      summary: Recordings Coverage
+      description: |-
+        **Access:** Authenticated user with access to the referenced camera.
+
+        Returns merged recording coverage spans plus codec compatibility.
+
+        codecs_compatible is false only when more than one known video codec
+        appears across the range's rows, the case where the merged vod route
+        degrades to a single-stream manifest.
+      operationId: recordings_coverage__camera_name__recordings_coverage_get
+      parameters:
+        - name: camera_name
+          in: path
+          required: true
+          schema:
+            anyOf:
+              - type: string
+              - type: 'null'
+            title: Camera Name
+        - name: after
+          in: query
+          required: true
+          schema:
+            type: number
+            title: After
+        - name: before
+          in: query
+          required: true
+          schema:
+            type: number
+            title: Before
+        - name: timelines
+          in: query
+          required: false
+          schema:
+            type: boolean
+            default: false
+            title: Timelines
+      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: camera
   /{camera_name}/recordings:
     get:
       tags:
@@ -8903,6 +9057,17 @@ components:
         - msg
         - type
       title: ValidationError
+    VodStreamPreference:
+      type: string
+      enum:
+        - main
+        - sub
+      title: VodStreamPreference
+      description: |-
+        Stream pin for the path-segment VOD route.
+
+        nginx-vod derives its mapping fetch URI from the playlist URL path
+        (query params are dropped), so the preference must be a path segment.
   securitySchemes:
     frigateAdminAuth:
       type: apiKey

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/camera.py

@@ -651,6 +651,32 @@ async def _connect_onvif_camera(
     raise first_error
 
 
+def _supports_continuous_pan_tilt(nodes) -> bool:
+    """Whether any PTZ node advertises continuous pan/tilt velocity.
+
+    The web UI's directional controls issue ContinuousMove with a PanTilt
+    velocity, so continuous pan/tilt is what makes those controls usable. This
+    is intentionally narrower than ptz_supported, which is true for any device
+    exposing the ONVIF PTZ service - including zoom/focus-only varifocal lenses.
+    """
+    for node in nodes or []:
+        spaces = getattr(node, "SupportedPTZSpaces", None) or (
+            node.get("SupportedPTZSpaces") if isinstance(node, dict) else None
+        )
+        if spaces is None:
+            continue
+
+        continuous = getattr(spaces, "ContinuousPanTiltVelocitySpace", None) or (
+            spaces.get("ContinuousPanTiltVelocitySpace")
+            if isinstance(spaces, dict)
+            else None
+        )
+        if continuous:
+            return True
+
+    return False
+
+
 @router.get(
     "/onvif/probe",
     dependencies=[Depends(require_role(["admin"]))],
@@ -808,6 +834,7 @@ async def onvif_probe(
 
         # Check PTZ support and capabilities
         ptz_supported = False
+        pan_tilt_supported = False
         presets_count = 0
         autotrack_supported = False
 
@@ -841,6 +868,15 @@ async def onvif_probe(
                     logger.debug(f"Failed to get presets: {e}")
                     presets_count = 0
 
+            # Check for real (continuous) pan/tilt, which the UI controls need
+            if ptz_supported:
+                try:
+                    nodes = await ptz_service.GetNodes()
+                    pan_tilt_supported = _supports_continuous_pan_tilt(nodes)
+                    logger.debug(f"Continuous pan/tilt supported: {pan_tilt_supported}")
+                except Exception as e:
+                    logger.debug(f"Failed to read PTZ nodes for pan/tilt support: {e}")
+
             # Check for autotracking support - requires both FOV relative movement and MoveStatus
             if ptz_supported and first_profile_token and ptz_config_token:
                 # First check for FOV relative movement support
@@ -960,6 +996,7 @@ async def onvif_probe(
             "firmware_version": device_info["firmware_version"],
             "profiles_count": profiles_count,
             "ptz_supported": ptz_supported,
+            "pan_tilt_supported": pan_tilt_supported,
             "presets_count": presets_count,
             "autotrack_supported": autotrack_supported,
         }
@@ -1349,7 +1386,7 @@ def camera_set(
     | `improve_contrast` | `ON`, `OFF` |
     | `ptz_autotracker` | `ON`, `OFF` |
     | `birdseye` | `ON`, `OFF` |
-    | `birdseye_mode` | `CONTINUOUS`, `MOTION`, `OBJECTS` |
+    | `birdseye_modes` | `CONTINUOUS`, `MOTION`, `ALL_OBJECTS`, `ALERTS`, `DETECTIONS`, `NONE`, or a comma-separated combination |
     | `motion_contour_area` | integer |
     | `motion_threshold` | integer |
     | `motion_mask` | `ON`, `OFF` |

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

@@ -8,6 +8,7 @@ import os
 import subprocess as sp
 import time
 from datetime import UTC, datetime, timedelta
+from enum import Enum
 from pathlib import Path as FilePath
 from typing import Any
 from urllib.parse import unquote
@@ -39,8 +40,9 @@ from frigate.config.camera.snapshots import SnapshotsConfig
 from frigate.const import (
     CACHE_DIR,
     INSTALL_DIR,
-    MAX_SEGMENT_DURATION,
     PREVIEW_FRAME_TYPE,
+    STREAM_TYPE_MAIN,
+    STREAM_TYPE_SUB,
 )
 from frigate.models import Event, Previews, Recordings, Regions, ReviewSegment
 from frigate.output.preview import get_most_recent_preview_frame
@@ -52,12 +54,34 @@ from frigate.util.file import (
     load_event_snapshot_image,
 )
 from frigate.util.image import get_image_from_recording, get_image_quality_params
-from frigate.util.media import get_keyframe_before
 from frigate.util.object import create_empty_regions_grid
+from frigate.util.recording_coverage import (
+    build_spans,
+    null_audio_glitches,
+    plan_clip,
+    resolve_coverage,
+    stream_has_audio,
+)
 
 logger = logging.getLogger(__name__)
 
 
+# must match the patched MAX_CLIPS in docker/main/build_nginx.sh; a
+# normal hour needs ~360, one clip per recording file
+NGINX_VOD_MAX_CLIPS = 1080
+
+
+class VodStreamPreference(str, Enum):
+    """Stream pin for the path-segment VOD route.
+
+    nginx-vod derives its mapping fetch URI from the playlist URL path
+    (query params are dropped), so the preference must be a path segment.
+    """
+
+    main = STREAM_TYPE_MAIN
+    sub = STREAM_TYPE_SUB
+
+
 router = APIRouter(tags=[Tags.media])
 
 
@@ -319,7 +343,7 @@ async def get_snapshot_from_recording(
                 & (frame_time <= Recordings.end_time)
             )
             .where(Recordings.camera == camera_name)
-            .order_by(Recordings.start_time.desc())
+            .order_by(Recordings.stream_type.asc(), Recordings.start_time.desc())
             .limit(1)
             .get()
         )
@@ -338,7 +362,7 @@ async def get_snapshot_from_recording(
                     & (frame_time <= Recordings.end_time)
                 )
                 .where(Recordings.camera == camera_name)
-                .order_by(Recordings.start_time.desc())
+                .order_by(Recordings.stream_type.asc(), Recordings.start_time.desc())
                 .limit(1)
                 .get()
             )
@@ -398,7 +422,7 @@ async def submit_recording_snapshot_to_plus(
             (frame_time >= Recordings.start_time) & (frame_time <= Recordings.end_time)
         )
         .where(Recordings.camera == camera_name)
-        .order_by(Recordings.start_time.desc())
+        .order_by(Recordings.stream_type.asc(), Recordings.start_time.desc())
         .limit(1)
     )
 
@@ -472,20 +496,29 @@ async def recording_clip(
                         FilePath(file_path).unlink(missing_ok=True)
                     break
 
-    recordings = (
-        Recordings.select(
-            Recordings.path,
-            Recordings.start_time,
-            Recordings.end_time,
+    def get_clip_query(stream_type: str):
+        return (
+            Recordings.select(
+                Recordings.path,
+                Recordings.start_time,
+                Recordings.end_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))
+            )
+            .where(Recordings.camera == camera_name)
+            .where(Recordings.stream_type == stream_type)
+            .order_by(Recordings.start_time.asc())
         )
-        .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))
-        )
-        .where(Recordings.camera == camera_name)
-        .order_by(Recordings.start_time.asc())
-    )
+
+    # never mix streams in one concat; use main when available and
+    # fall back to sub for expired-main history
+    recordings = get_clip_query(STREAM_TYPE_MAIN)
+
+    if recordings.count() == 0:
+        recordings = get_clip_query(STREAM_TYPE_SUB)
 
     if recordings.count() == 0:
         return JSONResponse(
@@ -549,17 +582,60 @@ async def recording_clip(
     )
 
 
-@router.get(
-    "/vod/{camera_name}/start/{start_ts}/end/{end_ts}",
-    dependencies=[Depends(require_camera_access)],
-    description="Returns an HLS playlist for the specified timestamp-range on the specified camera. Append /master.m3u8 or /index.m3u8 for HLS playback.",
-)
-async def vod_ts(
+def _build_vod_clip(
+    row: Any, start: float, end: float
+) -> tuple[dict[str, Any], int] | None:
+    """Build one nginx-vod clip dict + duration (ms) for a recording row trimmed to [start, end).
+
+    Realization comes entirely from the shared plan_clip, so the coverage
+    endpoint's realized timelines match this manifest by construction.
+    """
+    plan = plan_clip(row, start, end)
+
+    if plan.skipped:
+        return None
+
+    clip: dict[str, Any] = {"type": "source", "path": row.path}
+    if plan.clip_from_ms is not None:
+        clip["clipFrom"] = plan.clip_from_ms
+    if plan.key_frame_durations is not None:
+        # real gaps enable keyframe-aligned sub-file segments (bootstrap
+        # ladder); the whole-clip fallback keeps one segment per file,
+        # the only safe cut without an index
+        if plan.first_key_frame_offset_ms > 0:
+            clip["firstKeyFrameOffset"] = plan.first_key_frame_offset_ms
+        clip["keyFrameDurations"] = plan.key_frame_durations
+    else:
+        clip["keyFrameDurations"] = [plan.duration_ms]
+    logger.debug(
+        "VOD: added clip %s duration_ms=%s clipFrom=%s",
+        row.path,
+        plan.duration_ms,
+        clip.get("clipFrom"),
+    )
+    return clip, plan.duration_ms
+
+
+async def _vod_response(
     camera_name: str,
     start_ts: float,
     end_ts: float,
     force_discontinuity: bool = False,
-):
+    stream_preference: str | None = None,
+) -> JSONResponse:
+    """Build an nginx-vod mapping JSON for a camera over a timestamp range.
+
+    Always a single-sequence mapping; quality selection happens in the
+    frontend by choosing between this route and the stream-pinned routes.
+
+    Args:
+        camera_name: The camera to build the mapping for
+        start_ts: Range start as a unix timestamp
+        end_ts: Range end as a unix timestamp
+        force_discontinuity: Emit HLS discontinuity markers between clips
+        stream_preference: Pin the manifest to one stream type ("main" or
+            "sub"), serving only that stream's recordings
+    """
     logger.debug(
         "VOD: Generating VOD for %s from %s to %s with force_discontinuity=%s",
         camera_name,
@@ -567,104 +643,85 @@ async def vod_ts(
         end_ts,
         force_discontinuity,
     )
-    recordings = (
-        Recordings.select(
-            Recordings.path,
-            Recordings.duration,
-            Recordings.end_time,
-            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))
-        )
-        .where(Recordings.camera == camera_name)
-        .order_by(Recordings.start_time.asc())
-        .iterator()
+    intervals = resolve_coverage(camera_name, start_ts, end_ts)
+
+    # rows contradicting their stream's audio composition are
+    # truncated-shutdown glitches
+    main_audio = stream_has_audio(intervals, main=True)
+    sub_audio = stream_has_audio(intervals, main=False)
+
+    spans = build_spans(
+        null_audio_glitches(intervals, main_audio, sub_audio),
+        stream_preference,
     )
 
-    clips = []
-    durations = []
-    min_duration_ms = 100  # Minimum 100ms to ensure at least one video frame
-    max_duration_ms = MAX_SEGMENT_DURATION * 1000
-
-    recording: Recordings
-    for recording in recordings:
+    durations: list[int] = []
+    clips: list[dict[str, Any]] = []
+    # gathered after glitch-nulling and span building, so the policy
+    # decisions below reflect the manifest's real contents
+    video_codecs: set[str] = set()
+    audio_presence: set[bool] = set()
+    audio_params: set[tuple[str | None, int | None]] = set()
+    span_streams: set[bool] = set()
+    for row, span_start, span_end, span_is_main in spans:
         logger.debug(
             "VOD: processing recording: %s start=%s end=%s duration=%s",
-            recording.path,
-            recording.start_time,
-            recording.end_time,
-            recording.duration,
+            row.path,
+            row.start_time,
+            row.end_time,
+            row.duration,
         )
+        built = _build_vod_clip(row, span_start, span_end)
 
-        clip = {"type": "source", "path": recording.path}
-        duration = int(recording.duration * 1000)
-
-        # adjust start offset if start_ts is after recording.start_time
-        if start_ts > recording.start_time:
-            inpoint = int((start_ts - recording.start_time) * 1000)
-            clip["clipFrom"] = inpoint
-            duration -= inpoint
-            logger.debug(
-                "VOD: applied clipFrom %sms to %s",
-                inpoint,
-                recording.path,
-            )
-
-        # adjust end if recording.end_time is after end_ts
-        if recording.end_time > end_ts:
-            duration -= int((recording.end_time - end_ts) * 1000)
-
-        # nginx-vod-module pushes clipFrom forward to the next keyframe,
-        # which can leave too few frames and produce an empty/unplayable
-        # segment. Snap clipFrom back to the preceding keyframe so the
-        # segment always starts with a decodable frame.
-        if "clipFrom" in clip:
-            keyframe_ms = get_keyframe_before(recording.path, clip["clipFrom"])
-            if keyframe_ms is not None:
-                gained = clip["clipFrom"] - keyframe_ms
-                clip["clipFrom"] = keyframe_ms
-                duration += gained
-                logger.debug(
-                    "VOD: snapped clipFrom to keyframe at %sms for %s, duration now %sms",
-                    keyframe_ms,
-                    recording.path,
-                    duration,
-                )
-            else:
-                # could not read keyframes, remove clipFrom to use full recording
-                logger.debug(
-                    "VOD: no keyframe info for %s, removing clipFrom to use full recording",
-                    recording.path,
-                )
-                del clip["clipFrom"]
-                duration = int(recording.duration * 1000)
-                if recording.end_time > end_ts:
-                    duration -= int((recording.end_time - end_ts) * 1000)
-
-        if duration < min_duration_ms:
-            # skip if the clip has no valid duration (too short to contain frames)
-            logger.debug(
-                "VOD: skipping recording %s - resulting duration %sms too short",
-                recording.path,
-                duration,
-            )
+        if built is None:
             continue
 
-        if min_duration_ms <= duration < max_duration_ms:
-            clip["keyFrameDurations"] = [duration]
-            clips.append(clip)
-            durations.append(duration)
-            logger.debug(
-                "VOD: added clip %s duration_ms=%s clipFrom=%s",
-                recording.path,
-                duration,
-                clip.get("clipFrom"),
-            )
-        else:
-            logger.warning(f"Recording clip is missing or empty: {recording.path}")
+        clips.append(built[0])
+        durations.append(built[1])
+        span_streams.add(span_is_main)
+        if row.video_codec is not None:
+            video_codecs.add(row.video_codec)
+        audio_presence.add(row.has_audio is not False)
+        # legacy rows contribute no signature, so uniformly-unknown
+        # history keeps the legacy shape
+        if row.has_audio is not False and (
+            row.audio_codec is not None or row.audio_rate is not None
+        ):
+            audio_params.add((row.audio_codec, row.audio_rate))
+
+    # nginx-vod requires a uniform track count per sequence, and adding or
+    # removing an audio track across an MSE discontinuity is unproven
+    if len(audio_presence) > 1:
+        logger.debug(
+            "VOD: %s mixes audio-bearing and audio-less recordings between "
+            "%s and %s; serving the range without audio",
+            camera_name,
+            start_ts,
+            end_ts,
+        )
+        for clip in clips:
+            clip["tracks"] = "v"
+
+    # discontinuity mode emits per-clip init segments, letting the decoder
+    # reconfigure at each boundary. Stream type counts as a signature of
+    # its own: the two encoders differ in SPS/PPS even when codec name and
+    # audio params match, and a single-init manifest then decode-fails on
+    # players that only configure from the init segment (iOS)
+    use_discontinuity = (
+        len(video_codecs) > 1 or len(audio_params) > 1 or len(span_streams) > 1
+    )
+    if use_discontinuity:
+        logger.debug(
+            "VOD: %s mixes media signatures between %s and %s (video codecs "
+            "%s, audio params %s, streams %s); serving a discontinuity "
+            "manifest with per-clip init segments",
+            camera_name,
+            start_ts,
+            end_ts,
+            sorted(video_codecs),
+            sorted(audio_params, key=str),
+            sorted(span_streams),
+        )
 
     if not clips:
         logger.error(
@@ -678,16 +735,50 @@ async def vod_ts(
             status_code=404,
         )
 
+    if len(clips) > NGINX_VOD_MAX_CLIPS:
+        logger.warning(
+            "VOD: %s needs %d clips between %s and %s, exceeding nginx's "
+            "limit of %d; playback of this range will fail. This usually "
+            "means the camera produced abnormally short recording segments "
+            "(check the stream's timestamps)",
+            camera_name,
+            len(clips),
+            start_ts,
+            end_ts,
+            NGINX_VOD_MAX_CLIPS,
+        )
+
+    # segmentation comes from the vod_* nginx directives plus per-clip
+    # keyFrameDurations; a segment_duration field here was always ignored
+    # (nginx-vod parses only camelCase segmentDuration)
     hour_ago = datetime.now() - timedelta(hours=1)
-    return JSONResponse(
-        content={
-            "cache": hour_ago.timestamp() > start_ts,
-            "discontinuity": force_discontinuity,
-            "consistentSequenceMediaInfo": True,
-            "durations": durations,
-            "segment_duration": max(durations),
-            "sequences": [{"clips": clips}],
-        }
+    content = {
+        "cache": hour_ago.timestamp() > start_ts,
+        "discontinuity": force_discontinuity or use_discontinuity,
+        "consistentSequenceMediaInfo": True,
+        "durations": durations,
+        "sequences": [{"clips": clips}],
+    }
+    if use_discontinuity:
+        # clip-indexed naming is what makes nginx-vod emit per-clip
+        # EXT-X-MAP outside of its live mode
+        content["initialClipIndex"] = 1
+    return JSONResponse(content=content)
+
+
+@router.get(
+    "/vod/{camera_name}/start/{start_ts}/end/{end_ts}",
+    dependencies=[Depends(require_camera_access)],
+    description="Returns an HLS playlist for the specified timestamp-range on the specified camera. Append /master.m3u8 or /index.m3u8 for HLS playback.",
+)
+async def vod_ts(
+    camera_name: str,
+    start_ts: float,
+    end_ts: float,
+    force_discontinuity: bool = False,
+):
+    return await _vod_response(
+        camera_name, start_ts, end_ts, force_discontinuity=force_discontinuity
     )
 
 
@@ -776,7 +867,43 @@ async def vod_clip(
     start_ts: float,
     end_ts: float,
 ):
-    return await vod_ts(camera_name, start_ts, end_ts, force_discontinuity=True)
+    # the tracking-details player corrects its timeline from
+    # sequences[0].clips[0].clipFrom
+    return await _vod_response(
+        camera_name,
+        start_ts,
+        end_ts,
+        force_discontinuity=True,
+    )
+
+
+# registered after /vod/clip/... on purpose: both routes are six path
+# segments, Starlette matches structurally in registration order, and the
+# enum validation on {stream} would otherwise 422 every /vod/clip request
+@router.get(
+    "/vod/{camera_name}/{stream}/start/{start_ts}/end/{end_ts}",
+    dependencies=[Depends(require_camera_access)],
+    description="Returns an HLS playlist pinned to one stream type (main or sub) for the specified timestamp-range on the specified camera. Append /master.m3u8 or /index.m3u8 for HLS playback.",
+)
+async def vod_ts_stream(
+    camera_name: str,
+    stream: VodStreamPreference,
+    start_ts: float,
+    end_ts: float,
+    force_discontinuity: bool = False,
+):
+    """VOD for a timestamp range pinned to one stream type.
+
+    How the frontend selects quality, now that mappings are always
+    single-sequence.
+    """
+    return await _vod_response(
+        camera_name,
+        start_ts,
+        end_ts,
+        force_discontinuity=force_discontinuity,
+        stream_preference=stream.value,
+    )
 
 
 @router.get(
@@ -820,7 +947,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 +1025,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 +1254,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,8 +25,20 @@ 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,
+    STREAM_TYPE_MAIN,
+    STREAM_TYPE_SUB,
+)
 from frigate.models import Event, Recordings
+from frigate.util.recording_coverage import (
+    coverage_spans,
+    known_video_codecs,
+    realized_timelines,
+    resolve_coverage,
+    stream_media_summary,
+)
 from frigate.util.time import get_dst_transitions
 
 logger = logging.getLogger(__name__)
@@ -59,7 +71,7 @@ def get_recordings_storage_usage(request: Request):
 
 
 @router.get("/recordings/summary", dependencies=[Depends(allow_any_authenticated())])
-def all_recordings_summary(
+async def all_recordings_summary(
     request: Request,
     params: MediaRecordingsSummaryQueryParams = Depends(),
     allowed_cameras: list[str] = Depends(get_allowed_cameras_for_filter),
@@ -76,18 +88,23 @@ def all_recordings_summary(
     else:
         camera_list = allowed_cameras
 
-    time_range_query = (
-        Recordings.select(
-            fn.MIN(Recordings.start_time).alias("min_time"),
-            fn.MAX(Recordings.start_time).alias("max_time"),
+    min_time: float | None = None
+    max_time: float | None = None
+    for camera in camera_list:
+        cam_min = (
+            Recordings.select(fn.MIN(Recordings.start_time))
+            .where(Recordings.camera == camera)
+            .scalar()
         )
-        .where(Recordings.camera << camera_list)
-        .dicts()
-        .get()
-    )
-
-    min_time = time_range_query.get("min_time")
-    max_time = time_range_query.get("max_time")
+        if cam_min is None:
+            continue
+        cam_max = (
+            Recordings.select(fn.MAX(Recordings.start_time))
+            .where(Recordings.camera == camera)
+            .scalar()
+        )
+        min_time = cam_min if min_time is None else min(min_time, cam_min)
+        max_time = cam_max if max_time is None else max(max_time, cam_max)
 
     if min_time is None or max_time is None:
         return JSONResponse(content={})
@@ -97,22 +114,60 @@ def all_recordings_summary(
     days: dict[str, bool] = {}
 
     for period_start, period_end, period_offset in dst_periods:
-        day_expr = ((Recordings.start_time + period_offset) / 86400).cast("int")
+        first_start = max(min_time, period_start - MAX_SEGMENT_DURATION)
+        first_day = int((first_start + period_offset) // 86400)
+        last_day = int((min(max_time, period_end) + period_offset) // 86400)
 
-        period_query = (
-            Recordings.select(day_expr.alias("day_idx"))
-            .where(
-                (Recordings.camera << camera_list)
-                & (Recordings.end_time >= period_start)
-                & (Recordings.start_time <= period_end)
+        day_idx = first_day
+        while day_idx <= last_day:
+            day_str = (dt.date(1970, 1, 1) + dt.timedelta(days=day_idx)).isoformat()
+            day_start = day_idx * 86400 - period_offset
+            day_end = day_start + 86400
+
+            if day_str in days:
+                day_idx += 1
+                continue
+
+            if day_end <= period_end:
+                upper = Recordings.start_time < day_end
+            else:
+                upper = Recordings.start_time <= period_end
+
+            has_recordings = (
+                Recordings.select(Recordings.id)
+                .where(
+                    (Recordings.camera << camera_list)
+                    & (Recordings.end_time >= period_start)
+                    & (Recordings.start_time >= day_start)
+                    & upper
+                )
+                .exists()
             )
-            .distinct()
-            .namedtuples()
-        )
+            if has_recordings:
+                days[day_str] = True
+                day_idx += 1
+                continue
 
-        for g in period_query:
-            day_str = (dt.date(1970, 1, 1) + dt.timedelta(days=g.day_idx)).isoformat()
-            days[day_str] = True
+            # empty day
+            next_start: float | None = None
+            for camera in camera_list:
+                cam_next = (
+                    Recordings.select(fn.MIN(Recordings.start_time))
+                    .where(
+                        Recordings.camera == camera,
+                        Recordings.start_time >= day_end,
+                        Recordings.start_time <= period_end,
+                    )
+                    .scalar()
+                )
+                if cam_next is not None and (
+                    next_start is None or cam_next < next_start
+                ):
+                    next_start = cam_next
+
+            if next_start is None:
+                break
+            day_idx = max(day_idx + 1, int((next_start + period_offset) // 86400))
 
     return JSONResponse(content=dict(sorted(days.items())))
 
@@ -149,23 +204,28 @@ async def recordings_summary(camera_name: str, timezone: str = "utc"):
         period_hour_modifier = f"{hours_offset} hour"
         period_minute_modifier = f"{minutes_offset} minute"
 
+        hour_expression = fn.strftime(
+            "%Y-%m-%d %H",
+            fn.datetime(
+                Recordings.start_time,
+                "unixepoch",
+                period_hour_modifier,
+                period_minute_modifier,
+            ),
+        )
+
+        # sub rows duplicate the camera's motion/object stats, so
+        # aggregating them too would double-count
         recording_groups = (
             Recordings.select(
-                fn.strftime(
-                    "%Y-%m-%d %H",
-                    fn.datetime(
-                        Recordings.start_time,
-                        "unixepoch",
-                        period_hour_modifier,
-                        period_minute_modifier,
-                    ),
-                ).alias("hour"),
+                hour_expression.alias("hour"),
                 fn.SUM(Recordings.duration).alias("duration"),
                 fn.SUM(Recordings.motion).alias("motion"),
                 fn.SUM(Recordings.objects).alias("objects"),
             )
             .where(
                 (Recordings.camera == camera_name)
+                & (Recordings.stream_type == STREAM_TYPE_MAIN)
                 & (Recordings.end_time >= period_start)
                 & (Recordings.start_time <= period_end)
             )
@@ -174,6 +234,23 @@ async def recordings_summary(camera_name: str, timezone: str = "utc"):
             .namedtuples()
         )
 
+        # sub recordings can outlive main, so hours covered only by sub
+        # rows are reported too, flagged as sub_only
+        sub_groups = (
+            Recordings.select(
+                hour_expression.alias("hour"),
+                fn.SUM(Recordings.duration).alias("duration"),
+            )
+            .where(
+                (Recordings.camera == camera_name)
+                & (Recordings.stream_type == STREAM_TYPE_SUB)
+                & (Recordings.end_time >= period_start)
+                & (Recordings.start_time <= period_end)
+            )
+            .group_by((Recordings.start_time + period_offset).cast("int") / 3600)
+            .namedtuples()
+        )
+
         event_groups = (
             Event.select(
                 fn.strftime(
@@ -197,17 +274,43 @@ async def recordings_summary(camera_name: str, timezone: str = "utc"):
 
         event_map = {g.hour: g.count for g in event_groups}
 
-        for recording_group in recording_groups:
-            parts = recording_group.hour.split()
+        hour_stats = [
+            (
+                g.hour,
+                {
+                    "motion": g.motion,
+                    "objects": g.objects,
+                    "duration": round(g.duration),
+                },
+            )
+            for g in recording_groups
+        ]
+        main_hours = {group_hour for group_hour, _ in hour_stats}
+        hour_stats.extend(
+            (
+                g.hour,
+                {
+                    "motion": 0,
+                    "objects": 0,
+                    "duration": round(g.duration),
+                    "sub_only": True,
+                },
+            )
+            for g in sub_groups
+            if g.hour not in main_hours
+        )
+        # restore the most-recent-first ordering after merging in sub hours
+        hour_stats.sort(key=lambda entry: entry[0], reverse=True)
+
+        for group_hour, stats in hour_stats:
+            parts = group_hour.split()
             hour = parts[1]
             day = parts[0]
-            events_count = event_map.get(recording_group.hour, 0)
+            events_count = event_map.get(group_hour, 0)
             hour_data = {
                 "hour": hour,
                 "events": events_count,
-                "motion": recording_group.motion,
-                "objects": recording_group.objects,
-                "duration": round(recording_group.duration),
+                **stats,
             }
             if day in days:
                 # merge counts if already present (edge-case at DST boundary)
@@ -223,6 +326,35 @@ async def recordings_summary(camera_name: str, timezone: str = "utc"):
     return JSONResponse(content=list(days.values()))
 
 
+@router.get(
+    "/{camera_name}/recordings/coverage",
+    dependencies=[Depends(require_camera_access)],
+)
+async def recordings_coverage(
+    camera_name: str, after: float, before: float, timelines: bool = False
+):
+    """Returns merged recording coverage spans plus codec compatibility.
+
+    codecs_compatible is false only when more than one known video codec
+    appears across the range's rows, the case where the merged vod route
+    degrades to a single-stream manifest.
+    """
+    intervals = resolve_coverage(camera_name, after, before)
+
+    content = {
+        "spans": coverage_spans(intervals),
+        "codecs_compatible": len(known_video_codecs(intervals)) <= 1,
+        "streams": stream_media_summary(intervals),
+    }
+
+    # pure computation (shared plan_clip, record-time keyframe index), but
+    # opt-in for payload hygiene: day-level requests need only the spans
+    if timelines:
+        content["timelines"] = realized_timelines(intervals)
+
+    return JSONResponse(content=content)
+
+
 @router.get("/{camera_name}/recordings", dependencies=[Depends(require_camera_access)])
 async def recordings(
     camera_name: str,
@@ -243,6 +375,8 @@ async def recordings(
         )
         .where(
             Recordings.camera == camera_name,
+            Recordings.stream_type == STREAM_TYPE_MAIN,
+            Recordings.start_time >= after - MAX_SEGMENT_DURATION,
             Recordings.end_time >= after,
             Recordings.start_time <= before,
         )
@@ -282,22 +416,22 @@ async def no_recordings(
     )
     scale = params.scale
 
-    clauses = [
-        (Recordings.end_time >= after) & (Recordings.start_time <= before),
-        (Recordings.camera << camera_list),
-    ]
+    recordings: list[tuple[float, float]] = []
+    for camera in camera_list:
+        recordings.extend(
+            Recordings.select(Recordings.start_time, Recordings.end_time)
+            .where(
+                Recordings.camera == camera,
+                Recordings.start_time >= after - MAX_SEGMENT_DURATION,
+                Recordings.end_time >= after,
+                Recordings.start_time <= before,
+            )
+            .tuples()
+            .iterator()
+        )
 
-    # Get recording start times
-    data: list[Recordings] = (
-        Recordings.select(Recordings.start_time, Recordings.end_time)
-        .where(reduce(operator.and_, clauses))
-        .order_by(Recordings.start_time.asc())
-        .dicts()
-        .iterator()
-    )
-
-    # Convert recordings to list of (start, end) tuples, ordered by start_time
-    recordings = [(r["start_time"], r["end_time"]) for r in data]
+    # the merge pass below expects a single start-ordered timeline
+    recordings.sort()
 
     # Merge overlapping/adjacent recordings into covered intervals. The query
     # orders by start_time, so a single pass merges them

frigate/api/review.py

@@ -32,6 +32,7 @@ from frigate.api.defs.response.review_response import (
     ReviewSummaryResponse,
 )
 from frigate.api.defs.tags import Tags
+from frigate.const import STREAM_TYPE_MAIN
 from frigate.embeddings import EmbeddingsContext
 from frigate.models import Recordings, ReviewSegment, UserReviewStatus
 from frigate.review.types import SeverityEnum
@@ -597,6 +598,8 @@ def motion_activity(
 
     clauses = [(Recordings.start_time > after) & (Recordings.end_time < before)]
     clauses.append(Recordings.motion > 0)
+    # sub rows duplicate the camera's motion stats, so only count main rows
+    clauses.append(Recordings.stream_type == STREAM_TYPE_MAIN)
 
     if cameras != "all":
         requested = set(cameras.split(","))

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,11 @@ 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 (
+    FrigateConfig,
+    birdseye_modes_from_mqtt_payload,
+    birdseye_modes_to_mqtt_payload,
+)
 from frigate.config.camera.updater import (
     CameraConfigUpdateEnum,
     CameraConfigUpdatePublisher,
@@ -45,6 +49,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."""
@@ -84,7 +93,7 @@ class Dispatcher:
             "recordings": self._on_recordings_command,
             "snapshots": self._on_snapshots_command,
             "birdseye": self._on_birdseye_command,
-            "birdseye_mode": self._on_birdseye_mode_command,
+            "birdseye_modes": self._on_birdseye_modes_command,
             "review_alerts": self._on_alerts_command,
             "review_detections": self._on_detections_command,
             "object_descriptions": self._on_object_description_command,
@@ -99,12 +108,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 +234,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 +372,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 +399,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"):
@@ -879,11 +928,12 @@ class Dispatcher:
         )
         self.publish(f"{camera_name}/birdseye/state", payload, retain=True)
 
-    def _on_birdseye_mode_command(self, camera_name: str, payload: str) -> None:
+    def _on_birdseye_modes_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}")
+        modes = birdseye_modes_from_mqtt_payload(payload)
+        if modes is None:
+            logger.info("Invalid birdseye_modes command: %s", payload)
             return
 
         birdseye_settings = self.config.cameras[camera_name].birdseye
@@ -892,16 +942,20 @@ class Dispatcher:
             logger.info(f"Birdseye mode not enabled for {camera_name}")
             return
 
-        birdseye_settings.mode = BirdseyeModeEnum(payload.lower())
+        birdseye_settings.modes = modes
         logger.info(
-            f"Setting birdseye mode for {camera_name} to {birdseye_settings.mode}"
+            f"Setting birdseye mode for {camera_name} to {birdseye_settings.modes}"
         )
 
         self.config_updater.publish_update(
             CameraConfigUpdateTopic(CameraConfigUpdateEnum.birdseye, camera_name),
             birdseye_settings,
         )
-        self.publish(f"{camera_name}/birdseye_mode/state", payload, retain=True)
+        self.publish(
+            f"{camera_name}/birdseye_modes/state",
+            birdseye_modes_to_mqtt_payload(modes),
+            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,16 +1,38 @@
+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
 
 from frigate.comms.base_communicator import Communicator
-from frigate.config import FrigateConfig
+from frigate.config import FrigateConfig, birdseye_modes_to_mqtt_payload
+
+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(
@@ -123,9 +197,9 @@ class MqttClient(Communicator):
                 retain=True,
             )
             self.publish(
-                f"{camera_name}/birdseye_mode/state",
+                f"{camera_name}/birdseye_modes/state",
                 (
-                    camera.birdseye.mode.value.upper()
+                    birdseye_modes_to_mqtt_payload(camera.birdseye.modes)
                     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,521 @@ 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.
+
+        Oldest first: the outage buffer replays before the queue, so a topic
+        that changed since the reconnect ends up on its newest value rather
+        than being reverted by the replay.
+        """
+        if self.connected and not self._subscription_ready:
+            return
+
+        self._flush_pending_retained()
+
+        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)
+
+    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:
+                # never attempted, so anything already buffered for this topic
+                # was written later and has to survive
+                self._buffer_undelivered(queued_publish, overwrite=False)
+                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 +787,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 +801,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/audio.py

@@ -41,6 +41,11 @@ class AudioConfig(FrigateBaseModel):
         title="Listen types",
         description="List of audio event types to detect (for example: bark, fire_alarm, speech, yell).",
     )
+    labelmap: dict[int, str] = Field(
+        default_factory=dict,
+        title="Audio labelmap customization",
+        description="Overrides or remapping entries to merge into the standard audio labelmap.",
+    )
     filters: dict[str, AudioFilterConfig] | None = Field(
         None,
         title="Audio filters",

frigate/config/camera/birdseye.py

@@ -9,21 +9,57 @@ __all__ = [
     "BirdseyeConfig",
     "BirdseyeLayoutConfig",
     "BirdseyeModeEnum",
+    "birdseye_modes_from_mqtt_payload",
+    "birdseye_modes_to_mqtt_payload",
 ]
 
+# canonical MQTT payload for an empty mode list
+MQTT_NO_MODES = "NONE"
+
 
 class BirdseyeModeEnum(str, Enum):
-    objects = "objects"
-    motion = "motion"
     continuous = "continuous"
+    motion = "motion"
+    all_objects = "all_objects"
+    alerts = "alerts"
+    detections = "detections"
 
-    @classmethod
-    def get_index(cls, type):
-        return list(cls).index(type)
 
-    @classmethod
-    def get(cls, index):
-        return list(cls)[index]
+def birdseye_modes_from_mqtt_payload(payload: str) -> list[BirdseyeModeEnum] | None:
+    """Parse an uppercase MQTT payload into activity modes, or None when invalid."""
+    raw_modes = payload.split(",")
+
+    if any(not raw_mode or raw_mode != raw_mode.upper() for raw_mode in raw_modes):
+        return None
+
+    if raw_modes == [MQTT_NO_MODES]:
+        return []
+
+    modes: list[BirdseyeModeEnum] = []
+
+    for raw_mode in raw_modes:
+        try:
+            mode = BirdseyeModeEnum(raw_mode.lower())
+        except ValueError:
+            return None
+
+        if mode in modes:
+            return None
+
+        modes.append(mode)
+
+    return modes
+
+
+def birdseye_modes_to_mqtt_payload(modes: list[BirdseyeModeEnum]) -> str:
+    """Serialize activity modes for MQTT state topics."""
+    payload = ",".join(mode.value.upper() for mode in BirdseyeModeEnum if mode in modes)
+    return payload or MQTT_NO_MODES
+
+
+def default_birdseye_modes() -> list[BirdseyeModeEnum]:
+    """Return the default Birdseye activity modes."""
+    return [BirdseyeModeEnum.all_objects]
 
 
 class BirdseyeLayoutConfig(FrigateBaseModel):
@@ -47,10 +83,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'.",
+    modes: list[BirdseyeModeEnum] = Field(
+        default_factory=default_birdseye_modes,
+        title="Activity types",
+        description="Activity types that include cameras in Birdseye.",
     )
 
     restream: bool = Field(
@@ -102,10 +138,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'.",
+    modes: list[BirdseyeModeEnum] = Field(
+        default_factory=default_birdseye_modes,
+        title="Activity types",
+        description="Activity types that include cameras in Birdseye.",
     )
 
     order: int = Field(

frigate/config/camera/camera.py

@@ -3,7 +3,12 @@ from enum import Enum
 
 from pydantic import Field, PrivateAttr, model_validator
 
-from frigate.const import CACHE_DIR, CACHE_SEGMENT_FORMAT, REGEX_CAMERA_NAME
+from frigate.const import (
+    CACHE_DIR,
+    CACHE_SEGMENT_FORMAT,
+    REGEX_CAMERA_NAME,
+    SUB_CACHE_TAG,
+)
 from frigate.ffmpeg_presets import (
     parse_preset_hardware_acceleration_decode,
     parse_preset_hardware_acceleration_scale,
@@ -294,6 +299,28 @@ class CameraConfig(FrigateBaseModel):
                 + ffmpeg_output_args
             )
 
+        if (
+            "record_sub" in ffmpeg_input.roles
+            and self.record.enabled
+            and self.record.sub.enabled
+        ):
+            sub_output_args = self.ffmpeg.output_args.effective_record_sub
+            record_args = get_ffmpeg_arg_list(
+                parse_preset_output_record(
+                    sub_output_args,
+                    self.ffmpeg.apple_compatibility,
+                )
+                or sub_output_args
+            )
+
+            ffmpeg_output_args = (
+                record_args
+                + [
+                    f"{os.path.join(CACHE_DIR, self.name)}{SUB_CACHE_TAG}@{CACHE_SEGMENT_FORMAT}.mp4"
+                ]
+                + ffmpeg_output_args
+            )
+
         # if there aren't any outputs enabled for this input
         if len(ffmpeg_output_args) == 0:
             return None

frigate/config/camera/ffmpeg.py

@@ -42,6 +42,20 @@ class FfmpegOutputArgsConfig(FrigateBaseModel):
         title="Record output arguments",
         description="Default output arguments for record role streams.",
     )
+    record_sub: str | list[str] = Field(
+        default_factory=list,
+        title="Sub stream record output arguments",
+        description="Output arguments for record_sub role streams. The record output arguments are used when this is not set.",
+    )
+
+    @property
+    def effective_record_sub(self) -> str | list[str]:
+        """Output arguments used for the record_sub role.
+
+        Falls back to the record arguments rather than to the stock preset so
+        that a customized record value keeps applying to both recorded streams.
+        """
+        return self.record_sub or self.record
 
 
 class FfmpegConfig(FrigateBaseModel):
@@ -99,6 +113,7 @@ class FfmpegConfig(FrigateBaseModel):
 class CameraRoleEnum(str, Enum):
     audio = "audio"
     record = "record"
+    record_sub = "record_sub"
     detect = "detect"
 
 

frigate/config/camera/record.py

@@ -13,6 +13,7 @@ __all__ = [
     "RecordExportConfig",
     "RecordPreviewConfig",
     "RecordQualityEnum",
+    "RecordSubConfig",
     "EventsConfig",
     "ReviewRetainConfig",
     "RecordRetainConfig",
@@ -110,6 +111,34 @@ class RecordExportConfig(FrigateBaseModel):
     )
 
 
+class RecordSubConfig(FrigateBaseModel):
+    enabled: bool = Field(
+        default=False,
+        title="Enable sub stream recording",
+        description="Enable recording of a second, lower quality stream for adaptive quality playback and extended retention.",
+    )
+    continuous: RecordRetainConfig = Field(
+        default_factory=RecordRetainConfig,
+        title="Sub stream continuous retention",
+        description="Number of days to retain sub stream recordings regardless of tracked objects or motion.",
+    )
+    motion: RecordRetainConfig = Field(
+        default_factory=RecordRetainConfig,
+        title="Sub stream motion retention",
+        description="Number of days to retain sub stream recordings triggered by motion.",
+    )
+    alerts: ReviewRetainConfig = Field(
+        default_factory=ReviewRetainConfig,
+        title="Sub stream alert retention",
+        description="Retention settings for sub stream recordings of alerts.",
+    )
+    detections: ReviewRetainConfig = Field(
+        default_factory=ReviewRetainConfig,
+        title="Sub stream detection retention",
+        description="Retention settings for sub stream recordings of detections.",
+    )
+
+
 class RecordConfig(FrigateBaseModel):
     enabled: bool = Field(
         default=False,
@@ -151,12 +180,35 @@ class RecordConfig(FrigateBaseModel):
         title="Preview config",
         description="Settings controlling the quality of recording previews shown in the UI.",
     )
+    sub: RecordSubConfig = Field(
+        default_factory=RecordSubConfig,
+        title="Sub stream recording",
+        description="Settings for recording a second, lower quality stream.",
+    )
     enabled_in_config: bool | None = Field(
         default=None,
         title="Original recording state",
         description="Indicates whether recording was enabled in the original static configuration.",
     )
 
+    @property
+    def effective_alert_days(self) -> float:
+        """Alert retention extended to the sub stream window when sub is enabled.
+
+        Review items and tracked objects must stay visible for as long as
+        either stream still has recordings.
+        """
+        if self.sub.enabled:
+            return max(self.alerts.retain.days, self.sub.alerts.days)
+        return self.alerts.retain.days
+
+    @property
+    def effective_detection_days(self) -> float:
+        """Detection retention extended to the sub window when sub is enabled."""
+        if self.sub.enabled:
+            return max(self.detections.retain.days, self.sub.detections.days)
+        return self.detections.retain.days
+
     @property
     def event_pre_capture(self) -> int:
         return max(

frigate/config/camera/updater.py

@@ -129,8 +129,13 @@ class CameraConfigUpdateSubscriber:
             config.objects = updated_config
         elif update_type == CameraConfigUpdateEnum.record:
             old_enabled_in_config = config.record.enabled_in_config
+            old_sub_enabled = config.record.sub.enabled
             config.record = updated_config
-            if old_enabled_in_config != updated_config.enabled_in_config:
+            # the record and record_sub ffmpeg outputs are gated on these
+            if (
+                old_enabled_in_config != updated_config.enabled_in_config
+                or old_sub_enabled != updated_config.sub.enabled
+            ):
                 config.recreate_ffmpeg_cmds()
         elif update_type == CameraConfigUpdateEnum.review:
             config.review = updated_config

frigate/config/config.py

@@ -255,6 +255,15 @@ def verify_config_roles(camera_config: CameraConfig) -> None:
             f"Camera {camera_config.name} has record enabled, but record is not assigned to an input."
         )
 
+    if (
+        camera_config.record.enabled
+        and camera_config.record.sub.enabled
+        and "record_sub" not in assigned_roles
+    ):
+        raise ValueError(
+            f"Camera {camera_config.name} has sub stream recording enabled, but record_sub is not assigned to an input."
+        )
+
     if camera_config.audio.enabled and "audio" not in assigned_roles:
         raise ValueError(
             f"Camera {camera_config.name} has audio events enabled, but audio is not assigned to an input."
@@ -275,13 +284,11 @@ def verify_valid_live_stream_names(
             )
 
 
-def verify_recording_segments_setup_with_reasonable_time(
-    camera_config: CameraConfig,
+def verify_record_output_args_segment_time(
+    camera_config: CameraConfig, output_args: str | list[str], role: str
 ) -> None:
-    """Verify that recording segments are setup and segment time is not greater than 60."""
-    record_args: list[str] = get_ffmpeg_arg_list(
-        camera_config.ffmpeg.output_args.record
-    )
+    """Verify that a recording role's output args segment at a reasonable time."""
+    record_args: list[str] = get_ffmpeg_arg_list(output_args)
 
     if record_args[0].startswith("preset"):
         return
@@ -291,16 +298,32 @@ def verify_recording_segments_setup_with_reasonable_time(
     except ValueError:
         raise ValueError(
             f"Camera {camera_config.name} has no segment_time in \
-                         recording output args, segment args are required for record."
+                         {role} output args, segment args are required for record."
         ) from None
 
     if int(record_args[seg_arg_index + 1]) > 60:
         raise ValueError(
-            f"Camera {camera_config.name} has invalid segment_time output arg, \
+            f"Camera {camera_config.name} has invalid segment_time in {role} output args, \
                          segment_time must be 60 or less."
         )
 
 
+def verify_recording_segments_setup_with_reasonable_time(
+    camera_config: CameraConfig,
+) -> None:
+    """Verify that recording segments are setup and segment time is not greater than 60."""
+    verify_record_output_args_segment_time(
+        camera_config, camera_config.ffmpeg.output_args.record, "recording"
+    )
+
+    if camera_config.record.sub.enabled:
+        verify_record_output_args_segment_time(
+            camera_config,
+            camera_config.ffmpeg.output_args.effective_record_sub,
+            "sub stream recording",
+        )
+
+
 def verify_zone_objects_are_tracked(camera_config: CameraConfig) -> None:
     """Verify that user has not entered zone objects that are not in the tracking config."""
     for zone_name, zone in camera_config.zones.items():

frigate/config/profile_manager.py

@@ -8,6 +8,7 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
+from frigate.config.camera.birdseye import birdseye_modes_to_mqtt_payload
 from frigate.config.camera.updater import (
     CameraConfigUpdateEnum,
     CameraConfigUpdatePublisher,
@@ -42,8 +43,12 @@ SECTION_STATE_TOPICS: dict[str, list[tuple[str, Callable[[Any], Any]]]] = {
     "birdseye": [
         ("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",
+            "birdseye_modes",
+            lambda c: (
+                birdseye_modes_to_mqtt_payload(c.birdseye.modes)
+                if c.birdseye.enabled
+                else "OFF"
+            ),
         ),
     ],
     "detect": [("detect", lambda c: "ON" if c.detect.enabled else "OFF")],

frigate/const.py

@@ -23,6 +23,12 @@ SHM_FRAMES_VAR = "SHM_MAX_FRAMES"
 
 REDACTED_CREDENTIAL_SENTINEL = "__FRIGATE_SAVED_CREDENTIAL__"
 
+# Stream type constants
+
+STREAM_TYPE_MAIN = "main"
+STREAM_TYPE_SUB = "sub"
+SUB_CACHE_TAG = "@sub"
+
 # Attribute & Object constants
 
 DEFAULT_ATTRIBUTE_LABEL_MAP = {

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/events/audio.py

@@ -210,7 +210,11 @@ class AudioEventMaintainer(threading.Thread):
         # per-camera stop signal so a single maintainer can be torn down at
         # runtime (e.g. on camera removal) without stopping the whole process
         self.camera_stop_event = threading.Event()
-        self.detector = AudioTfl(stop_event, self.camera_config.audio.num_threads)
+        self.detector = AudioTfl(
+            stop_event,
+            self.camera_config.audio.num_threads,
+            self.camera_config.audio.labelmap,
+        )
         self.shape = (int(round(AUDIO_DURATION * AUDIO_SAMPLE_RATE)),)
         self.chunk_size = int(round(AUDIO_DURATION * AUDIO_SAMPLE_RATE * 2))
         self.logger = logging.getLogger(f"audio.{self.camera_config.name}")
@@ -392,7 +396,10 @@ class AudioEventMaintainer(threading.Thread):
 
         while not self.stop_event.is_set() and not self.camera_stop_event.is_set():
             # check if there is an updated config
-            self.config_subscriber.check_for_updates()
+            updated_topics = self.config_subscriber.check_for_updates()
+
+            if CameraConfigUpdateEnum.audio.name in updated_topics:
+                self.detector.update_labelmap(self.camera_config.audio.labelmap)
 
             enabled = self.camera_config.enabled
             if enabled != self.was_enabled:
@@ -451,10 +458,17 @@ class AudioEventMaintainer(threading.Thread):
 
 
 class AudioTfl:
-    def __init__(self, stop_event: threading.Event, num_threads: int = 2) -> None:
+    def __init__(
+        self,
+        stop_event: threading.Event,
+        num_threads: int = 2,
+        labelmap: dict[int, str] | None = None,
+    ) -> None:
         self.stop_event = stop_event
         self.num_threads = num_threads
-        self.labels = load_labels("/audio-labelmap.txt", prefill=521)
+        self._default_labels = load_labels("/audio-labelmap.txt", prefill=521)
+        self.labels: dict[int, str] = {}
+        self.update_labelmap(labelmap or {})
         # Suppress TFLite delegate creation messages that bypass Python logging
         with suppress_stderr_during("tflite_interpreter_init"):
             self.interpreter = Interpreter(
@@ -466,6 +480,10 @@ class AudioTfl:
         self.tensor_input_details = self.interpreter.get_input_details()
         self.tensor_output_details = self.interpreter.get_output_details()
 
+    def update_labelmap(self, labelmap: dict[int, str]) -> None:
+        """Merge configured label overrides into the default audio labelmap."""
+        self.labels = {**self._default_labels, **labelmap}
+
     def _detect_raw(self, tensor_input: np.ndarray) -> np.ndarray:
         self.interpreter.set_tensor(self.tensor_input_details[0]["index"], tensor_input)
         self.interpreter.invoke()
@@ -504,10 +522,14 @@ class AudioTfl:
 
         raw_detections = self._detect_raw(tensor_input)
 
+        detected_labels: set[str] = set()
+
         for d in raw_detections:
             if d[1] < threshold:
                 break
-            detections.append(
-                (self.labels[int(d[0])], float(d[1]), (d[2], d[3], d[4], d[5]))
-            )
+            label = self.labels[int(d[0])]
+            if label in detected_labels:
+                continue
+            detected_labels.add(label)
+            detections.append((label, float(d[1]), (d[2], d[3], d[4], d[5])))
         return detections

frigate/events/cleanup.py

@@ -197,9 +197,11 @@ class EventCleanup(threading.Thread):
 
     def expire_clips(self) -> list[str]:
         ## Expire events from unlisted cameras based on the global config
+        # effective days cover the sub window, keeping tracked objects in
+        # Explore while sub recordings and review items still exist
         expire_days = max(
-            self.config.record.alerts.retain.days,
-            self.config.record.detections.retain.days,
+            self.config.record.effective_alert_days,
+            self.config.record.effective_detection_days,
         )
         file_extension = None  # mp4 clips are no longer stored in /clips
         update_params = {"has_clip": False}
@@ -278,15 +280,13 @@ class EventCleanup(threading.Thread):
 
         ## Expire events from cameras based on the camera config
         for name, camera in self.config.cameras.items():
-            expire_days = max(
-                camera.record.alerts.retain.days,
-                camera.record.detections.retain.days,
-            )
+            # effective days cover the sub window, keeping tracked objects
+            # in Explore while sub recordings and review items still exist
             alert_expire_date = (
-                now - datetime.timedelta(days=camera.record.alerts.retain.days)
+                now - datetime.timedelta(days=camera.record.effective_alert_days)
             ).timestamp()
             detection_expire_date = (
-                now - datetime.timedelta(days=camera.record.detections.retain.days)
+                now - datetime.timedelta(days=camera.record.effective_detection_days)
             ).timestamp()
             # grab all events after specific time
             expired_events = (

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": {
@@ -495,7 +453,7 @@ def get_tool_definitions(
                                 "motion",
                                 "enabled",
                                 "birdseye",
-                                "birdseye_mode",
+                                "birdseye_modes",
                                 "improve_contrast",
                                 "ptz_autotracker",
                                 "motion_contour_area",
@@ -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_modes accepts CONTINUOUS, MOTION, ALL_OBJECTS, ALERTS, DETECTIONS, NONE, 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/jobs/motion_search.py

@@ -15,7 +15,7 @@ import numpy as np
 
 from frigate.comms.inter_process import InterProcessRequestor
 from frigate.config import FrigateConfig
-from frigate.const import UPDATE_JOB_STATE
+from frigate.const import STREAM_TYPE_MAIN, UPDATE_JOB_STATE
 from frigate.jobs.job import Job
 from frigate.jobs.manager import (
     get_job_by_id,
@@ -485,6 +485,7 @@ class MotionSearchRunner(threading.Thread):
                 )
             )
             .where(Recordings.camera == camera_name)
+            .where(Recordings.stream_type == STREAM_TYPE_MAIN)
             .order_by(Recordings.start_time.asc())
         )
 

frigate/models.py

@@ -79,6 +79,12 @@ class Recordings(Model):
     segment_size = FloatField(default=0)  # this should be stored as MB
     regions = IntegerField(null=True)
     motion_heatmap = JSONField(null=True)  # 16x16 grid, 256 values (0-255)
+    keyframes = JSONField(null=True)  # ms offsets; NULL = unprobed (legacy rows)
+    stream_type = CharField(default="main", max_length=8)
+    has_audio = BooleanField(null=True)  # NULL = unknown (legacy rows)
+    audio_rate = IntegerField(null=True)  # Hz; NULL = unknown (legacy rows)
+    audio_codec = CharField(null=True, max_length=20)  # NULL = unknown (legacy rows)
+    video_codec = CharField(null=True, max_length=20)  # NULL = unknown (legacy rows)
 
 
 class ExportCase(Model):

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,9 +17,11 @@ import cv2
 import numpy as np
 
 from frigate.comms.inter_process import InterProcessRequestor
+from frigate.comms.review_updater import ReviewDataSubscriber
 from frigate.config import BirdseyeModeEnum, 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.review.types import SeverityEnum
 from frigate.util.image import (
     SharedMemoryFrameManager,
     copy_yuv_to_position,
@@ -28,6 +31,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_object: bool
+    has_motion: bool
+    severity: str | None
+
+
 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
@@ -357,6 +369,7 @@ class BirdsEyeFrameManager:
                 settings.detect.height,
             ],
             "last_active_frame": 0.0,
+            "live_active": False,
             "current_frame": 0.0,
             "layout_frame": 0.0,
             "channel_dims": {
@@ -408,19 +421,33 @@ class BirdsEyeFrameManager:
             channel_dims,
         )
 
-    def camera_active(
-        self, mode: Any, object_box_count: int, motion_box_count: int
+    def camera_threshold_active(
+        self,
+        modes: list[BirdseyeModeEnum],
+        activity: BirdseyeActivity,
     ) -> bool:
-        if mode == BirdseyeModeEnum.continuous:
-            return True
+        """Return whether activity subject to inactivity_threshold is present."""
+        return (BirdseyeModeEnum.motion in modes and activity.has_motion) or (
+            BirdseyeModeEnum.all_objects in modes and activity.has_object
+        )
 
-        if mode == BirdseyeModeEnum.motion and motion_box_count > 0:
-            return True
-
-        if mode == BirdseyeModeEnum.objects and object_box_count > 0:
-            return True
-
-        return False
+    def camera_live_active(
+        self,
+        modes: list[BirdseyeModeEnum],
+        activity: BirdseyeActivity,
+    ) -> bool:
+        """Return whether activity that ends the moment it stops is present."""
+        return (
+            BirdseyeModeEnum.continuous in modes
+            or (
+                BirdseyeModeEnum.alerts in modes
+                and activity.severity == SeverityEnum.alert
+            )
+            or (
+                BirdseyeModeEnum.detections in modes
+                and activity.severity == SeverityEnum.detection
+            )
+        )
 
     def get_camera_coordinates(self) -> dict[str, dict[str, int]]:
         """Return the coordinates of each camera in the current layout."""
@@ -451,9 +478,15 @@ class BirdsEyeFrameManager:
                 and self.config.cameras[cam].birdseye.enabled
                 and self.config.cameras[cam].enabled_in_config
                 and self.config.cameras[cam].enabled
-                and cam_data["last_active_frame"] > 0
-                and cam_data["current_frame_time"] - cam_data["last_active_frame"]
-                < self.config.birdseye.inactivity_threshold
+                and (
+                    cam_data["live_active"]
+                    or (
+                        cam_data["last_active_frame"] > 0
+                        and cam_data["current_frame_time"]
+                        - cam_data["last_active_frame"]
+                        < self.config.birdseye.inactivity_threshold
+                    )
+                )
             ]
         )
         logger.debug(f"Active cameras: {active_cameras}")
@@ -470,7 +503,9 @@ class BirdsEyeFrameManager:
                 limited_active_cameras = sorted(
                     active_cameras,
                     key=lambda active_camera: (
-                        self.cameras[active_camera]["current_frame_time"]
+                        0.0
+                        if self.cameras[active_camera]["live_active"]
+                        else self.cameras[active_camera]["current_frame_time"]
                         - self.cameras[active_camera]["last_active_frame"]
                     ),
                 )
@@ -604,112 +639,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 +733,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 +749,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 +760,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 +774,30 @@ 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 we've rendered a frame (we have activity state) then clear it
+            if camera_state["last_active_frame"] > 0 or camera_state["live_active"]:
+                camera_state["last_active_frame"] = 0
+                camera_state["live_active"] = False
                 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
+        modes = camera_config.birdseye.modes
+
+        if self.camera_threshold_active(modes, activity):
+            camera_state["last_active_frame"] = frame_time
+
+        camera_state["live_active"] = self.camera_live_active(modes, activity)
 
         now = datetime.datetime.now().timestamp()
 
@@ -834,6 +856,8 @@ class Birdseye:
         self.frame_manager = SharedMemoryFrameManager()
         self.stop_event = stop_event
         self.requestor = InterProcessRequestor()
+        self.review_subscriber = ReviewDataSubscriber("")
+        self.review_severity: dict[str, str] = {}
         self.idle_fps: float = self.config.birdseye.idle_heartbeat_fps
         self._idle_interval: float | None = (
             (1.0 / self.idle_fps) if self.idle_fps > 0 else None
@@ -864,6 +888,21 @@ class Birdseye:
         self.birdseye_manager.clear_frame()
         self.__send_new_frame()
 
+    def check_review_updates(self) -> None:
+        """Drain review updates so each camera's active severity stays current."""
+        while True:
+            update = self.review_subscriber.check_for_update(timeout=0)
+
+            if update is None:
+                break
+
+            camera = update["after"]["camera"]
+
+            if update["type"] == "end":
+                self.review_severity.pop(camera, None)
+            else:
+                self.review_severity[camera] = update["after"]["severity"]
+
     def add_camera(self, camera: str) -> None:
         """Add a camera to the birdseye manager."""
         self.birdseye_manager.add_camera(camera)
@@ -872,6 +911,7 @@ class Birdseye:
     def remove_camera(self, camera: str) -> None:
         """Remove a camera from the birdseye manager."""
         self.birdseye_manager.remove_camera(camera)
+        self.review_severity.pop(camera, None)
         logger.debug(f"Removed camera {camera} from birdseye")
 
     def write_data(
@@ -882,10 +922,18 @@ class Birdseye:
         frame_time: float,
         frame: np.ndarray,
     ) -> None:
+        activity = BirdseyeActivity(
+            has_object=any(
+                not tracked_object["false_positive"]
+                for tracked_object in current_tracked_objects
+            ),
+            has_motion=bool(motion_boxes),
+            severity=self.review_severity.get(camera),
+        )
+
         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,
         )
@@ -906,5 +954,6 @@ class Birdseye:
                 self.__send_new_frame()
 
     def stop(self) -> None:
+        self.review_subscriber.stop()
         self.converter.join()
         self.broadcaster.join()

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")
@@ -184,6 +188,11 @@ class OutputProcess(FrigateProcess):
                 self.config.birdseye = birdseye_config
                 logger.debug("Applied dynamic birdseye config update")
 
+            # drain review updates every iteration, not just when birdseye is
+            # being consumed, so a dropped end never strands a camera
+            if birdseye is not None:
+                birdseye.check_review_updates()
+
             # check if there is an updated config
             updates = config_subscriber.check_for_updates()
 
@@ -309,10 +318,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

@@ -72,7 +72,11 @@ class OnvifController:
         self.config_subscriber = CameraConfigUpdateSubscriber(
             self.config,
             self.config.cameras,
-            [CameraConfigUpdateEnum.onvif],
+            [
+                CameraConfigUpdateEnum.onvif,
+                CameraConfigUpdateEnum.add,
+                CameraConfigUpdateEnum.remove,
+            ],
         )
 
         asyncio.run_coroutine_threadsafe(self._init_cameras(), self.loop)
@@ -101,6 +105,16 @@ class OnvifController:
                     if update_type == CameraConfigUpdateEnum.onvif.name:
                         for cam_name in cameras:
                             await self._reinit_camera(cam_name)
+                    elif update_type == CameraConfigUpdateEnum.add.name:
+                        # a camera added at runtime only needs ONVIF set up if
+                        # it actually has an onvif host configured
+                        for cam_name in cameras:
+                            cam = self.config.cameras.get(cam_name)
+                            if cam and cam.onvif.host:
+                                await self._reinit_camera(cam_name)
+                    elif update_type == CameraConfigUpdateEnum.remove.name:
+                        for cam_name in cameras:
+                            await self._remove_camera(cam_name)
             except Exception:
                 logger.error("Error checking for ONVIF config updates")
 
@@ -113,6 +127,18 @@ class OnvifController:
             except Exception:
                 logger.debug(f"Error closing ONVIF session for {cam_name}")
 
+    async def _remove_camera(self, cam_name: str) -> None:
+        """Tear down the ONVIF session for a camera removed at runtime."""
+        if cam_name not in self.cams and cam_name not in self.camera_configs:
+            return
+
+        logger.debug(f"Tearing down ONVIF for {cam_name} after camera removal")
+        await self._close_camera(cam_name)
+        self.cams.pop(cam_name, None)
+        self.camera_configs.pop(cam_name, None)
+        self.failed_cams.pop(cam_name, None)
+        self.status_locks.pop(cam_name, None)
+
     async def _reinit_camera(self, cam_name: str) -> None:
         """Re-initialize a camera after config change."""
         logger.info(f"Re-initializing ONVIF for {cam_name} due to config change")
@@ -180,6 +206,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 +266,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 +370,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 +645,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 +663,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 +729,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 +775,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 +789,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 +913,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 +1025,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 +1069,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 +1100,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/cleanup.py

@@ -12,7 +12,14 @@ from typing import Any
 from playhouse.sqlite_ext import SqliteExtDatabase
 
 from frigate.config import CameraConfig, FrigateConfig, RetainModeEnum
-from frigate.const import CACHE_DIR, CLIPS_DIR, MAX_WAL_SIZE, RECORD_DIR
+from frigate.const import (
+    CACHE_DIR,
+    CLIPS_DIR,
+    MAX_WAL_SIZE,
+    RECORD_DIR,
+    STREAM_TYPE_MAIN,
+    STREAM_TYPE_SUB,
+)
 from frigate.models import Previews, Recordings, ReviewSegment, UserReviewStatus
 from frigate.util.builtin import clear_and_unlink
 from frigate.util.media import remove_empty_directories
@@ -20,6 +27,29 @@ from frigate.util.media import remove_empty_directories
 logger = logging.getLogger(__name__)
 
 
+def _filter_reviews_for_pass(
+    reviews: list[Any],
+    now: datetime.datetime,
+    alerts_days: float,
+    detections_days: float,
+) -> list[Any]:
+    """Limit reviews to those still within this pass's per-severity retention window.
+
+    Review rows survive to the longer of the main and sub retention windows,
+    so a pass that honored all of them would let extended sub retention keep
+    main recordings alive too. Filtering preserves sort order for the overlap
+    loop in expire_existing_camera_recordings.
+    """
+    alert_cutoff = (now - datetime.timedelta(days=alerts_days)).timestamp()
+    detection_cutoff = (now - datetime.timedelta(days=detections_days)).timestamp()
+    return [
+        r
+        for r in reviews
+        if r.end_time is None
+        or (r.end_time >= (alert_cutoff if r.severity == "alert" else detection_cutoff))
+    ]
+
+
 class RecordingCleanup(threading.Thread):
     """Cleanup existing recordings based on retention config."""
 
@@ -65,11 +95,14 @@ class RecordingCleanup(threading.Thread):
         self, config: CameraConfig, now: datetime.datetime
     ) -> set[Path]:
         """Delete review segments that are expired"""
-        alert_expire_date = (
-            now - datetime.timedelta(days=config.record.alerts.retain.days)
-        ).timestamp()
+        # review rows survive to the longer of the main and sub windows so
+        # they stay visible while either stream still has recordings
+        alert_days = config.record.effective_alert_days
+        detection_days = config.record.effective_detection_days
+
+        alert_expire_date = (now - datetime.timedelta(days=alert_days)).timestamp()
         detection_expire_date = (
-            now - datetime.timedelta(days=config.record.detections.retain.days)
+            now - datetime.timedelta(days=detection_days)
         ).timestamp()
         expired_reviews = (
             ReviewSegment.select(ReviewSegment.id, ReviewSegment.thumb_path)
@@ -109,8 +142,11 @@ class RecordingCleanup(threading.Thread):
 
     def expire_existing_camera_recordings(
         self,
+        stream_type: str,
         continuous_expire_date: float,
         motion_expire_date: float,
+        alerts_retain_mode: RetainModeEnum,
+        detections_retain_mode: RetainModeEnum,
         config: CameraConfig,
         reviews: list[Any],
     ) -> set[Path]:
@@ -130,6 +166,11 @@ class RecordingCleanup(threading.Thread):
             )
             .where(
                 (Recordings.camera == config.name)
+                & (Recordings.stream_type == stream_type)
+                & (
+                    Recordings.start_time
+                    < max(continuous_expire_date, motion_expire_date)
+                )
                 & (
                     (
                         (Recordings.end_time < continuous_expire_date)
@@ -175,9 +216,9 @@ class RecordingCleanup(threading.Thread):
                 ):
                     keep = True
                     mode = (
-                        config.record.alerts.retain.mode
+                        alerts_retain_mode
                         if review.severity == "alert"
-                        else config.record.detections.retain.mode
+                        else detections_retain_mode
                     )
                     break
 
@@ -216,6 +257,10 @@ class RecordingCleanup(threading.Thread):
                 Recordings.id << deleted_recordings_list[i : i + max_deletes]
             ).execute()
 
+        # previews follow main retention, so only the main pass expires them
+        if stream_type != STREAM_TYPE_MAIN:
+            return maybe_empty_dirs
+
         previews = (
             Previews.select(
                 Previews.id,
@@ -292,27 +337,45 @@ class RecordingCleanup(threading.Thread):
         expire_before = (
             datetime.datetime.now() - datetime.timedelta(days=expire_days)
         ).timestamp()
-        no_camera_recordings = (
-            Recordings.select(
-                Recordings.id,
-                Recordings.path,
-            )
-            .where(
-                Recordings.camera.not_in(list(self.config.cameras.keys())),  # type: ignore[call-arg, arg-type, misc]
-                Recordings.end_time < expire_before,
-            )
-            .namedtuples()
-            .iterator()
-        )
+
+        # enumerate the distinct cameras with one index seek each
+        db_cameras: list[str] = []
+        last_camera: str | None = None
+        while True:
+            query = Recordings.select(Recordings.camera)
+            if last_camera is not None:
+                query = query.where(Recordings.camera > last_camera)
+            next_camera = query.order_by(Recordings.camera.asc()).limit(1).scalar()
+            if next_camera is None:
+                break
+            db_cameras.append(next_camera)
+            last_camera = next_camera
 
         maybe_empty_dirs = set()
 
         deleted_recordings = set()
-        for recording in no_camera_recordings:
-            recording_path = Path(recording.path)
-            recording_path.unlink(missing_ok=True)
-            deleted_recordings.add(recording.id)
-            maybe_empty_dirs.add(recording_path.parent)
+        for camera in db_cameras:
+            if camera in self.config.cameras:
+                continue
+
+            no_camera_recordings = (
+                Recordings.select(
+                    Recordings.id,
+                    Recordings.path,
+                )
+                .where(
+                    Recordings.camera == camera,
+                    Recordings.end_time < expire_before,
+                )
+                .namedtuples()
+                .iterator()
+            )
+
+            for recording in no_camera_recordings:
+                recording_path = Path(recording.path)
+                recording_path.unlink(missing_ok=True)
+                deleted_recordings.add(recording.id)
+                maybe_empty_dirs.add(recording_path.parent)
 
         logger.debug(f"Expiring {len(deleted_recordings)} recordings")
         # delete up to 100,000 at a time
@@ -342,6 +405,20 @@ class RecordingCleanup(threading.Thread):
                 )
             ).timestamp()
 
+            # computed here so the reviews window below covers both passes
+            sub_continuous_expire_date = (
+                now - datetime.timedelta(days=config.record.sub.continuous.days)
+            ).timestamp()
+            sub_motion_expire_date = (
+                now
+                - datetime.timedelta(
+                    days=max(
+                        config.record.sub.motion.days,
+                        config.record.sub.continuous.days,
+                    )  # can't keep motion for less than continuous
+                )
+            ).timestamp()
+
             # Get all the reviews to check against
             reviews = (
                 ReviewSegment.select(
@@ -351,18 +428,46 @@ class RecordingCleanup(threading.Thread):
                 )
                 .where(
                     ReviewSegment.camera == camera,
-                    # candidate recordings can extend up to continuous_expire_date
-                    # (the no-motion no-audio branch of the recordings query),
-                    # so reviews must cover that full range to avoid deleting
-                    # segments that overlap recent alerts/detections.
-                    ReviewSegment.start_time < continuous_expire_date,
+                    # candidate recordings reach the later of the two passes'
+                    # continuous cutoffs, so reviews must cover that whole
+                    # range or segments overlapping recent alerts get deleted
+                    ReviewSegment.start_time
+                    < max(continuous_expire_date, sub_continuous_expire_date),
                 )
                 .order_by(ReviewSegment.start_time)
                 .namedtuples()
             )
 
             maybe_empty_dirs |= self.expire_existing_camera_recordings(
-                continuous_expire_date, motion_expire_date, config, reviews
+                STREAM_TYPE_MAIN,
+                continuous_expire_date,
+                motion_expire_date,
+                config.record.alerts.retain.mode,
+                config.record.detections.retain.mode,
+                config,
+                _filter_reviews_for_pass(
+                    reviews,
+                    now,
+                    config.record.alerts.retain.days,
+                    config.record.detections.retain.days,
+                ),
+            )
+
+            # runs even when sub recording is disabled so old rows still
+            # expire
+            maybe_empty_dirs |= self.expire_existing_camera_recordings(
+                STREAM_TYPE_SUB,
+                sub_continuous_expire_date,
+                sub_motion_expire_date,
+                config.record.sub.alerts.mode,
+                config.record.sub.detections.mode,
+                config,
+                _filter_reviews_for_pass(
+                    reviews,
+                    now,
+                    config.record.sub.alerts.days,
+                    config.record.sub.detections.days,
+                ),
             )
             logger.debug(f"End camera: {camera}.")
 

frigate/record/export.py

@@ -12,6 +12,7 @@ import threading
 from collections.abc import Callable
 from enum import Enum
 from pathlib import Path
+from typing import Any
 
 import pytz  # type: ignore[import-untyped]
 from peewee import DoesNotExist
@@ -24,6 +25,8 @@ from frigate.const import (
     EXPORT_DIR,
     MAX_PLAYLIST_SECONDS,
     PREVIEW_FRAME_TYPE,
+    STREAM_TYPE_MAIN,
+    STREAM_TYPE_SUB,
 )
 from frigate.ffmpeg_presets import (
     EncodeTypeEnum,
@@ -283,6 +286,29 @@ class RecordingExporter(threading.Thread):
 
         return input_duration * factor
 
+    def _get_recordings_for_range(self, stream_type: str) -> list[Any]:
+        """Fetch one stream type's recording rows overlapping the export range."""
+        return list(
+            Recordings.select(
+                Recordings.start_time,
+                Recordings.end_time,
+            )
+            .where(
+                Recordings.start_time.between(self.start_time, self.end_time)
+                | Recordings.end_time.between(self.start_time, self.end_time)
+                | (
+                    (self.start_time > Recordings.start_time)
+                    & (self.end_time < Recordings.end_time)
+                )
+            )
+            .where(
+                (Recordings.camera == self.camera)
+                & (Recordings.stream_type == stream_type)
+            )
+            .order_by(Recordings.start_time.asc())
+            .iterator()
+        )
+
     def _sum_source_duration_seconds(self) -> float | None:
         """Sum saved-video seconds inside [start_time, end_time].
 
@@ -293,19 +319,12 @@ class RecordingExporter(threading.Thread):
         """
         try:
             if self.playback_source == PlaybackSourceEnum.recordings:
-                rows = (
-                    Recordings.select(Recordings.start_time, Recordings.end_time)
-                    .where(
-                        Recordings.start_time.between(self.start_time, self.end_time)
-                        | Recordings.end_time.between(self.start_time, self.end_time)
-                        | (
-                            (self.start_time > Recordings.start_time)
-                            & (self.end_time < Recordings.end_time)
-                        )
-                    )
-                    .where(Recordings.camera == self.camera)
-                    .iterator()
-                )
+                # never mix streams in one estimate; use main when available
+                # and fall back to sub for expired-main history
+                rows = self._get_recordings_for_range(STREAM_TYPE_MAIN)
+
+                if not rows:
+                    rows = self._get_recordings_for_range(STREAM_TYPE_SUB)
             else:
                 rows = (
                     Previews.select(Previews.start_time, Previews.end_time)
@@ -691,23 +710,12 @@ class RecordingExporter(threading.Thread):
         if type(internal_port) is str:
             internal_port = int(internal_port.split(":")[-1])
 
-        recordings = list(
-            Recordings.select(
-                Recordings.start_time,
-                Recordings.end_time,
-            )
-            .where(
-                Recordings.start_time.between(self.start_time, self.end_time)
-                | Recordings.end_time.between(self.start_time, self.end_time)
-                | (
-                    (self.start_time > Recordings.start_time)
-                    & (self.end_time < Recordings.end_time)
-                )
-            )
-            .where(Recordings.camera == self.camera)
-            .order_by(Recordings.start_time.asc())
-            .iterator()
-        )
+        # never mix streams in one playlist; use main when available and
+        # fall back to sub for expired-main history
+        recordings = self._get_recordings_for_range(STREAM_TYPE_MAIN)
+
+        if not recordings:
+            recordings = self._get_recordings_for_range(STREAM_TYPE_SUB)
 
         playlist_lines: list[str] = []
         if (self.end_time - self.start_time) <= MAX_PLAYLIST_SECONDS:

frigate/record/maintainer.py

@@ -15,6 +15,7 @@ from typing import Any
 
 import numpy as np
 import psutil
+from peewee import fn
 
 from frigate.comms.detections_updater import DetectionSubscriber, DetectionTypeEnum
 from frigate.comms.inter_process import InterProcessRequestor
@@ -35,15 +36,48 @@ from frigate.const import (
     MAX_SEGMENT_DURATION,
     MAX_SEGMENTS_IN_CACHE,
     RECORD_DIR,
+    STREAM_TYPE_MAIN,
+    STREAM_TYPE_SUB,
+    SUB_CACHE_TAG,
 )
 from frigate.models import Recordings, ReviewSegment
 from frigate.review.types import SeverityEnum
+from frigate.util.media import get_keyframe_offsets
 from frigate.util.services import get_video_properties
 
 logger = logging.getLogger(__name__)
 
 STALE_RECORDINGS_INFO_TTL = MAX_SEGMENTS_IN_CACHE * MAX_SEGMENT_DURATION * 2
 
+# cache filenames have whole-second resolution, so a contiguous segment's
+# parsed start lands up to 1s before the previous segment's true end
+SEGMENT_CHAIN_TOLERANCE_S = 1.0
+
+# against an mtime-measured start, disagreement beyond this means
+# accumulated probe-duration error and the chain re-anchors on the mtime
+SEGMENT_CHAIN_DRIFT_LIMIT_S = 0.5
+
+# probing every cached segment at once starves the camera and detection
+# processes, and the probes then blow their own timeouts together, so
+# segments get discarded as corrupt and the record watchdog restarts ffmpeg
+MAX_CONCURRENT_SEGMENT_PROBES = 4
+
+
+def parse_cache_segment_name(basename: str) -> tuple[str, str, str] | None:
+    """Parse a cache segment basename into (camera, stream_type, date).
+
+    Main segments are named {camera}@{date}; sub segments {camera}@sub@{date}.
+    """
+    try:
+        prefix, date = basename.rsplit("@", maxsplit=1)
+    except ValueError:
+        return None
+
+    if prefix.endswith(SUB_CACHE_TAG):
+        return (prefix[: -len(SUB_CACHE_TAG)], STREAM_TYPE_SUB, date)
+
+    return (prefix, STREAM_TYPE_MAIN, date)
+
 
 class SegmentInfo:
     def __init__(
@@ -83,6 +117,10 @@ class SegmentInfo:
 
 
 class RecordingMaintainer(threading.Thread):
+    # move_files replaces this per cycle: an asyncio primitive binds to the
+    # first event loop that contends it, and every cycle runs in a new loop
+    probe_semaphore = asyncio.Semaphore(MAX_CONCURRENT_SEGMENT_PROBES)
+
     def __init__(self, config: FrigateConfig, stop_event: MpEvent):
         super().__init__(name="recording_maintainer")
         self.config = config
@@ -100,10 +138,101 @@ class RecordingMaintainer(threading.Thread):
         self.stop_event = stop_event
         self.object_recordings_info: dict[str, list] = defaultdict(list)
         self.audio_recordings_info: dict[str, list] = defaultdict(list)
-        self.end_time_cache: dict[str, tuple[datetime.datetime, float]] = {}
+        # cache_path -> (end_time, duration, has_audio, audio_rate,
+        # audio_codec, video_codec, keyframes)
+        self.end_time_cache: dict[
+            str,
+            tuple[
+                datetime.datetime,
+                float,
+                bool | None,
+                int | None,
+                str | None,
+                str | None,
+                list[int] | None,
+            ],
+        ] = {}
+        # last known capture end per (camera, stream_type); 0.0 marks a key
+        # whose DB seed found no rows
+        self.last_segment_end: dict[tuple[str, str], float] = {}
         self.unexpected_cache_files_logged: bool = False
 
+    def _get_last_segment_end(self, camera: str, stream_type: str) -> float | None:
+        """Return the last known capture end time for a camera stream.
+
+        Lazily seeds from the most recent stored recording so start-time
+        chains survive restarts.
+        """
+        key = (camera, stream_type)
+
+        if key not in self.last_segment_end:
+            last_db_end = (
+                Recordings.select(fn.MAX(Recordings.end_time))
+                .where(
+                    Recordings.camera == camera,
+                    Recordings.stream_type == stream_type,
+                )
+                .scalar()
+            )
+            # the 0.0 sentinel keeps the seed query from repeating
+            self.last_segment_end[key] = last_db_end if last_db_end is not None else 0.0
+
+        return self.last_segment_end[key] or None
+
+    def _resolve_segment_start(
+        self,
+        camera: str,
+        stream_type: str,
+        filename_start: datetime.datetime,
+        duration: float,
+        cache_path: str,
+    ) -> datetime.datetime:
+        """Resolve a segment's true start time from its cache file.
+
+        Cache filenames carry whole-second resolution, so the parsed start
+        sits up to 1s early. The cache file's mtime is the wall clock when
+        ffmpeg rolled the segment, so mtime minus the probed duration
+        restores the fractional start. Contiguous segments still chain to
+        the previous segment's end so rows stay exactly adjacent.
+        """
+        filename_ts = filename_start.timestamp()
+
+        measured: float | None = None
+        try:
+            mtime = os.path.getmtime(cache_path)
+        except OSError:
+            mtime = None
+        if mtime is not None:
+            candidate = mtime - duration
+            # media shorter than its wall span (a stalled stream, an early
+            # close) derives a start past the truncation window, where the
+            # floored filename start is safer
+            if 0 <= candidate - filename_ts < SEGMENT_CHAIN_TOLERANCE_S:
+                measured = candidate
+
+        last_end = self._get_last_segment_end(camera, stream_type)
+
+        if measured is not None:
+            if (
+                last_end is not None
+                and abs(last_end - measured) < SEGMENT_CHAIN_DRIFT_LIMIT_S
+            ):
+                return datetime.datetime.fromtimestamp(last_end, tz=datetime.UTC)
+            return datetime.datetime.fromtimestamp(measured, tz=datetime.UTC)
+
+        # no usable mtime: capture is continuous within a run, so a
+        # filename start just before the previous end chains to that end
+        if (
+            last_end is not None
+            and 0 <= last_end - filename_ts < SEGMENT_CHAIN_TOLERANCE_S
+        ):
+            return datetime.datetime.fromtimestamp(last_end, tz=datetime.UTC)
+
+        return filename_start
+
     async def move_files(self) -> None:
+        self.probe_semaphore = asyncio.Semaphore(MAX_CONCURRENT_SEGMENT_PROBES)
+
         cache_files = [
             d
             for d in os.listdir(CACHE_DIR)
@@ -117,13 +246,17 @@ class RecordingMaintainer(threading.Thread):
         for cache in cache_files:
             cache_path = os.path.join(CACHE_DIR, cache)
             basename = os.path.splitext(cache)[0]
-            try:
-                camera, date = basename.rsplit("@", maxsplit=1)
-            except ValueError:
+            parsed = parse_cache_segment_name(basename)
+            if parsed is None:
                 if not self.unexpected_cache_files_logged:
                     logger.warning("Skipping unexpected files in cache")
                     self.unexpected_cache_files_logged = True
                 continue
+            camera, stream_type, date = parsed
+
+            # this topic feeds main-stream health/sync consumers only
+            if stream_type == STREAM_TYPE_SUB:
+                continue
 
             start_time = datetime.datetime.strptime(
                 date, CACHE_SEGMENT_FORMAT
@@ -167,8 +300,10 @@ class RecordingMaintainer(threading.Thread):
             except psutil.Error:
                 continue
 
-        # group recordings by camera (skip in-use for validation/moving)
-        grouped_recordings: defaultdict[str, list[dict[str, Any]]] = defaultdict(list)
+        # group recordings by camera and stream type (skip in-use for validation/moving)
+        grouped_recordings: defaultdict[tuple[str, str], list[dict[str, Any]]] = (
+            defaultdict(list)
+        )
         for cache in cache_files:
             # Skip files currently in use
             if cache in files_in_use:
@@ -176,32 +311,35 @@ class RecordingMaintainer(threading.Thread):
 
             cache_path = os.path.join(CACHE_DIR, cache)
             basename = os.path.splitext(cache)[0]
-            try:
-                camera, date = basename.rsplit("@", maxsplit=1)
-            except ValueError:
+            parsed = parse_cache_segment_name(basename)
+            if parsed is None:
                 if not self.unexpected_cache_files_logged:
                     logger.warning("Skipping unexpected files in cache")
                     self.unexpected_cache_files_logged = True
                 continue
+            camera, stream_type, date = parsed
 
             # important that start_time is utc because recordings are stored and compared in utc
             start_time = datetime.datetime.strptime(
                 date, CACHE_SEGMENT_FORMAT
             ).astimezone(datetime.UTC)
 
-            grouped_recordings[camera].append(
+            grouped_recordings[(camera, stream_type)].append(
                 {
                     "cache_path": cache_path,
                     "start_time": start_time,
+                    "stream_type": stream_type,
                 }
             )
 
         # delete all cached files past the most recent MAX_SEGMENTS_IN_CACHE
         keep_count = MAX_SEGMENTS_IN_CACHE
-        for camera in grouped_recordings.keys():
+        for key in grouped_recordings.keys():
+            camera, stream_type = key
+
             # sort based on start time
-            grouped_recordings[camera] = sorted(
-                grouped_recordings[camera], key=lambda s: s["start_time"]
+            grouped_recordings[key] = sorted(
+                grouped_recordings[key], key=lambda s: s["start_time"]
             )
 
             camera_info = self.object_recordings_info[camera]
@@ -216,7 +354,7 @@ class RecordingMaintainer(threading.Thread):
                             r["start_time"].timestamp()
                             < most_recently_processed_frame_time
                         ),
-                        grouped_recordings[camera],
+                        grouped_recordings[key],
                     )
                 )
             )
@@ -226,103 +364,133 @@ class RecordingMaintainer(threading.Thread):
                 logger.warning(
                     f"Unable to keep up with recording segments in cache for {camera}. Keeping the {keep_count} most recent segments out of {processed_segment_count} and discarding the rest..."
                 )
-                to_remove = grouped_recordings[camera][:-keep_count]
+                to_remove = grouped_recordings[key][:-keep_count]
                 for rec in to_remove:
                     cache_path = rec["cache_path"]
                     Path(cache_path).unlink(missing_ok=True)
                     self.end_time_cache.pop(cache_path, None)
-                grouped_recordings[camera] = grouped_recordings[camera][-keep_count:]
+                grouped_recordings[key] = grouped_recordings[key][-keep_count:]
 
             # see if detection has failed and unprocessed segments need to be deleted
             unprocessed_segment_count = (
-                len(grouped_recordings[camera]) - processed_segment_count
+                len(grouped_recordings[key]) - processed_segment_count
             )
             if unprocessed_segment_count > keep_count:
                 logger.warning(
                     f"Too many unprocessed recording segments in cache for {camera}. This likely indicates an issue with the detect stream, keeping the {keep_count} most recent segments out of {unprocessed_segment_count} and discarding the rest..."
                 )
-                to_remove = grouped_recordings[camera][:-keep_count]
+                to_remove = grouped_recordings[key][:-keep_count]
                 for rec in to_remove:
                     cache_path = rec["cache_path"]
                     Path(cache_path).unlink(missing_ok=True)
                     self.end_time_cache.pop(cache_path, None)
-                grouped_recordings[camera] = grouped_recordings[camera][-keep_count:]
+                grouped_recordings[key] = grouped_recordings[key][-keep_count:]
 
-        tasks = []
-        for camera, recordings in grouped_recordings.items():
+        # frame stats are shared per camera across stream types, so trimming
+        # to one stream's oldest cache would pop frames the other still needs
+        min_start_per_camera: dict[str, float] = {}
+        for key, recordings in grouped_recordings.items():
+            camera, _ = key
+            oldest_start = recordings[0]["start_time"].timestamp()
+            if (
+                camera not in min_start_per_camera
+                or oldest_start < min_start_per_camera[camera]
+            ):
+                min_start_per_camera[camera] = oldest_start
+
+        for camera, min_start in min_start_per_camera.items():
             # clear out all the object recording info for old frames
             while (
                 len(self.object_recordings_info[camera]) > 0
-                and self.object_recordings_info[camera][0][0]
-                < recordings[0]["start_time"].timestamp()
+                and self.object_recordings_info[camera][0][0] < min_start
             ):
                 self.object_recordings_info[camera].pop(0)
 
             # clear out all the audio recording info for old frames
             while (
                 len(self.audio_recordings_info[camera]) > 0
-                and self.audio_recordings_info[camera][0][0]
-                < recordings[0]["start_time"].timestamp()
+                and self.audio_recordings_info[camera][0][0] < min_start
             ):
                 self.audio_recordings_info[camera].pop(0)
 
-            # get all reviews with the end time after the start of the oldest cache file
-            # or with end_time None
-            reviews = (
-                ReviewSegment.select(
-                    ReviewSegment.start_time,
-                    ReviewSegment.end_time,
-                    ReviewSegment.severity,
-                    ReviewSegment.data,
+        tasks = []
+        reviews_by_camera: dict[str, Any] = {}
+        for key, recordings in grouped_recordings.items():
+            camera, stream_type = key
+
+            # get all reviews with the end time after the start of the oldest
+            # cache file or with end_time None; shared across stream types
+            if camera not in reviews_by_camera:
+                reviews_by_camera[camera] = (
+                    ReviewSegment.select(
+                        ReviewSegment.start_time,
+                        ReviewSegment.end_time,
+                        ReviewSegment.severity,
+                        ReviewSegment.data,
+                    )
+                    .where(
+                        ReviewSegment.camera == camera,
+                        (ReviewSegment.end_time == None)
+                        | (ReviewSegment.end_time >= min_start_per_camera[camera]),
+                    )
+                    .order_by(ReviewSegment.start_time)
                 )
-                .where(
-                    ReviewSegment.camera == camera,
-                    (ReviewSegment.end_time == None)
-                    | (
-                        ReviewSegment.end_time
-                        >= recordings[0]["start_time"].timestamp()
-                    ),
-                )
-                .order_by(ReviewSegment.start_time)
-            )
+            reviews = reviews_by_camera[camera]
 
             tasks.extend(
                 [self.validate_and_move_segment(camera, reviews, r) for r in recordings]
             )
 
             # publish most recently available recording time and None if disabled
-            camera_cfg = self.config.cameras.get(camera)
-            self.recordings_publisher.publish(
-                (
-                    camera,
-                    recordings[0]["start_time"].timestamp()
-                    if camera_cfg and camera_cfg.record.enabled
-                    else None,
-                    None,
-                ),
-                RecordingsDataTypeEnum.saved.value,
-            )
+            if stream_type == STREAM_TYPE_MAIN:
+                camera_cfg = self.config.cameras.get(camera)
+                self.recordings_publisher.publish(
+                    (
+                        camera,
+                        recordings[0]["start_time"].timestamp()
+                        if camera_cfg and camera_cfg.record.enabled
+                        else None,
+                        None,
+                    ),
+                    RecordingsDataTypeEnum.saved.value,
+                )
 
         self._expire_stale_recordings_info(grouped_recordings)
 
-        recordings_to_insert: list[dict[str, Any] | None] = await asyncio.gather(*tasks)
-
-        # fire and forget recordings entries
-        self.requestor.send_data(
-            INSERT_MANY_RECORDINGS,
-            [r for r in recordings_to_insert if r is not None],
+        # one segment must not abort the cycle: an exception propagating out
+        # of gather would abandon the other segments' in-flight probes
+        results: list[dict[str, Any] | None | BaseException] = await asyncio.gather(
+            *tasks, return_exceptions=True
         )
 
+        recordings_to_insert: list[dict[str, Any]] = []
+
+        for result in results:
+            if isinstance(result, BaseException):
+                logger.error(
+                    "Failed to validate and move a recording segment", exc_info=result
+                )
+                continue
+
+            if result is not None:
+                recordings_to_insert.append(result)
+
+        # fire and forget recordings entries
+        self.requestor.send_data(INSERT_MANY_RECORDINGS, recordings_to_insert)
+
     def _expire_stale_recordings_info(
-        self, grouped_recordings: defaultdict[str, list[dict[str, Any]]]
+        self, grouped_recordings: defaultdict[tuple[str, str], list[dict[str, Any]]]
     ) -> None:
         expire_before = datetime.datetime.now().timestamp() - STALE_RECORDINGS_INFO_TTL
+        # a camera is still active when any of its streams cached segments
+        cameras_with_cache = {camera for camera, _ in grouped_recordings}
+
         for recordings_info in (
             self.object_recordings_info,
             self.audio_recordings_info,
         ):
             for camera in list(recordings_info.keys()):
-                if camera in grouped_recordings:
+                if camera in cameras_with_cache:
                     continue
                 info = recordings_info[camera]
                 while info and info[0][0] < expire_before:
@@ -337,64 +505,121 @@ class RecordingMaintainer(threading.Thread):
     ) -> dict[str, Any] | None:
         cache_path: str = recording["cache_path"]
         start_time: datetime.datetime = recording["start_time"]
+        stream_type: str = recording["stream_type"]
 
         # Just delete files if camera removed or recordings are turned off
         if (
             camera not in self.config.cameras
             or not self.config.cameras[camera].record.enabled
+            or (
+                stream_type == STREAM_TYPE_SUB
+                and not self.config.cameras[camera].record.sub.enabled
+            )
         ):
             self.drop_segment(cache_path)
             return None
 
         if cache_path in self.end_time_cache:
-            end_time, duration = self.end_time_cache[cache_path]
+            (
+                end_time,
+                duration,
+                has_audio,
+                audio_rate,
+                audio_codec,
+                video_codec,
+                keyframes,
+            ) = self.end_time_cache[cache_path]
+            # recover the resolved start rather than reusing the truncated
+            # filename timestamp
+            start_time = end_time - datetime.timedelta(seconds=duration)
         else:
-            segment_info = await get_video_properties(
-                self.config.ffmpeg, cache_path, get_duration=True
-            )
+            async with self.probe_semaphore:
+                segment_info = await get_video_properties(
+                    self.config.ffmpeg, cache_path, get_duration=True
+                )
 
             if not segment_info.get("has_valid_video", False):
                 logger.warning(
                     f"Invalid or missing video stream in segment {cache_path}. Discarding."
                 )
-                self.recordings_publisher.publish(
-                    (camera, start_time.timestamp(), cache_path),
-                    RecordingsDataTypeEnum.invalid.value,
-                )
+                if stream_type == STREAM_TYPE_MAIN:
+                    self.recordings_publisher.publish(
+                        (camera, start_time.timestamp(), cache_path),
+                        RecordingsDataTypeEnum.invalid.value,
+                    )
                 self.drop_segment(cache_path)
                 return None
 
             duration = float(segment_info.get("duration", -1))
+            has_audio = segment_info.get("has_audio")
+            audio_rate = segment_info.get("audio_rate")
+            audio_codec = segment_info.get("audio_codec")
+            video_codec = segment_info.get("video_codec")
 
             # ensure duration is within expected length
             if 0 < duration < MAX_SEGMENT_DURATION:
+                # playback snaps mid-file entry points against these offsets
+                # instead of probing files on demand
+                async with self.probe_semaphore:
+                    keyframes = await get_keyframe_offsets(cache_path)
+
+                start_time = self._resolve_segment_start(
+                    camera, stream_type, start_time, duration, cache_path
+                )
                 end_time = start_time + datetime.timedelta(seconds=duration)
-                self.end_time_cache[cache_path] = (end_time, duration)
+                self.end_time_cache[cache_path] = (
+                    end_time,
+                    duration,
+                    has_audio,
+                    audio_rate,
+                    audio_codec,
+                    video_codec,
+                    keyframes,
+                )
+                # segments later discarded by retention still advance the
+                # chain for the next kept segment
+                self.last_segment_end[(camera, stream_type)] = end_time.timestamp()
             else:
                 if duration == -1:
                     logger.warning(f"Failed to probe corrupt segment {cache_path}")
 
                 logger.warning(f"Discarding a corrupt recording segment: {cache_path}")
-                self.recordings_publisher.publish(
-                    (camera, start_time.timestamp(), cache_path),
-                    RecordingsDataTypeEnum.invalid.value,
-                )
+                if stream_type == STREAM_TYPE_MAIN:
+                    self.recordings_publisher.publish(
+                        (camera, start_time.timestamp(), cache_path),
+                        RecordingsDataTypeEnum.invalid.value,
+                    )
                 self.drop_segment(cache_path)
                 return None
 
             # this segment has a valid duration and has video data, so publish an update
-            self.recordings_publisher.publish(
-                (camera, start_time.timestamp(), cache_path),
-                RecordingsDataTypeEnum.valid.value,
-            )
+            if stream_type == STREAM_TYPE_MAIN:
+                self.recordings_publisher.publish(
+                    (camera, start_time.timestamp(), cache_path),
+                    RecordingsDataTypeEnum.valid.value,
+                )
 
         record_config = self.config.cameras[camera].record
+
+        # sub's alerts/detections carry the retain mode directly, unlike
+        # main's nested retain config
+        if stream_type == STREAM_TYPE_SUB:
+            continuous_days = record_config.sub.continuous.days
+            motion_days = record_config.sub.motion.days
+            alerts_retain_mode = record_config.sub.alerts.mode
+            detections_retain_mode = record_config.sub.detections.mode
+        else:
+            continuous_days = record_config.continuous.days
+            motion_days = record_config.motion.days
+            alerts_retain_mode = record_config.alerts.retain.mode
+            detections_retain_mode = record_config.detections.retain.mode
+
         segment_stats: SegmentInfo | None = None
         highest = None
 
-        if record_config.continuous.days > 0:
+        if continuous_days > 0:
             highest = "continuous"
-        elif record_config.motion.days > 0:
+        elif motion_days > 0:
             highest = "motion"
 
         # if we have continuous or motion recording enabled
@@ -426,11 +651,17 @@ class RecordingMaintainer(threading.Thread):
                 if not segment_stats.should_discard_segment(record_mode):
                     return await self.move_segment(
                         camera,
+                        stream_type,
                         start_time,
                         end_time,
                         duration,
                         cache_path,
                         segment_stats,
+                        has_audio,
+                        audio_rate,
+                        audio_codec,
+                        video_codec,
+                        keyframes,
                     )
 
         # we fell through the continuous / motion check, so we need to check the review items
@@ -459,9 +690,9 @@ class RecordingMaintainer(threading.Thread):
 
         if overlaps:
             record_mode = (
-                record_config.alerts.retain.mode
+                alerts_retain_mode
                 if review.severity == "alert"
-                else record_config.detections.retain.mode
+                else detections_retain_mode
             )
 
             if segment_stats is None:
@@ -471,11 +702,17 @@ class RecordingMaintainer(threading.Thread):
                 # move from cache to recordings immediately
                 return await self.move_segment(
                     camera,
+                    stream_type,
                     start_time,
                     end_time,
                     duration,
                     cache_path,
                     segment_stats,
+                    has_audio,
+                    audio_rate,
+                    audio_codec,
+                    video_codec,
+                    keyframes,
                 )
             else:
                 self.drop_segment(cache_path)
@@ -614,17 +851,24 @@ class RecordingMaintainer(threading.Thread):
     async def move_segment(
         self,
         camera: str,
+        stream_type: str,
         start_time: datetime.datetime,
         end_time: datetime.datetime,
         duration: float,
         cache_path: str,
         segment_info: SegmentInfo,
+        has_audio: bool | None = None,
+        audio_rate: int | None = None,
+        audio_codec: str | None = None,
+        video_codec: str | None = None,
+        keyframes: list[int] | None = None,
     ) -> dict[str, Any] | None:
         # directory will be in utc due to start_time being in utc
+        # sub segments get a tagged directory to avoid filename collisions
         directory = os.path.join(
             RECORD_DIR,
             start_time.strftime("%Y-%m-%d/%H"),
-            camera,
+            camera if stream_type == STREAM_TYPE_MAIN else f"{camera}{SUB_CACHE_TAG}",
         )
 
         os.makedirs(directory, exist_ok=True)
@@ -684,6 +928,7 @@ class RecordingMaintainer(threading.Thread):
                 return {
                     Recordings.id.name: f"{start_time.timestamp()}-{rand_id}",
                     Recordings.camera.name: camera,
+                    Recordings.stream_type.name: stream_type,
                     Recordings.path.name: file_path,
                     Recordings.start_time.name: start_time.timestamp(),
                     Recordings.end_time.name: end_time.timestamp(),
@@ -695,6 +940,11 @@ class RecordingMaintainer(threading.Thread):
                     Recordings.dBFS.name: segment_info.average_dBFS,
                     Recordings.segment_size.name: segment_size,
                     Recordings.motion_heatmap.name: segment_info.motion_heatmap,
+                    Recordings.has_audio.name: has_audio,
+                    Recordings.audio_rate.name: audio_rate,
+                    Recordings.audio_codec.name: audio_codec,
+                    Recordings.video_codec.name: video_codec,
+                    Recordings.keyframes.name: keyframes,
                 }
         except Exception as e:
             logger.error(f"Unable to store recording segment {cache_path}")
@@ -745,7 +995,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 +1014,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,
@@ -784,11 +1038,10 @@ class RecordingMaintainer(threading.Thread):
 
             try:
                 asyncio.run(self.move_files())
-            except Exception as e:
-                logger.error(
+            except Exception:
+                logger.exception(
                     "Error occurred when attempting to maintain recording cache"
                 )
-                logger.error(e)
             duration = datetime.datetime.now().timestamp() - run_start
             wait_time = max(0, 5 - duration)
 

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/storage.py

@@ -6,10 +6,15 @@ import threading
 from multiprocessing.synchronize import Event as MpEvent
 from pathlib import Path
 
-from peewee import SQL, fn
+from peewee import SQL, Case, fn
 
 from frigate.config import FrigateConfig
-from frigate.const import RECORD_DIR, REPLAY_CAMERA_PREFIX
+from frigate.const import (
+    RECORD_DIR,
+    REPLAY_CAMERA_PREFIX,
+    STREAM_TYPE_MAIN,
+    STREAM_TYPE_SUB,
+)
 from frigate.models import Event, Recordings
 from frigate.util.builtin import clear_and_unlink
 
@@ -30,6 +35,35 @@ class StorageMaintainer(threading.Thread):
         self.stop_event = stop_event
         self.camera_storage_stats: dict[str, dict] = {}
 
+    def _recent_stream_bandwidth(
+        self, camera: str, stream_type: str, window: int
+    ) -> float | None:
+        """Average MB/s over a stream's most recent rows, or None if no sample.
+
+        Zero-size rows are excluded inside the projection, not the WHERE
+        clause: a segment_size predicate baits the planner into the
+        (camera, segment_size) index plus a full sort of the camera's
+        history instead of the time-ordered index.
+        """
+        recent = (
+            Recordings.select(
+                Case(
+                    None,
+                    [(Recordings.segment_size > 0, bandwidth_equation)],
+                    None,
+                ).alias("bw")
+            )
+            .where(
+                Recordings.camera == camera,
+                Recordings.stream_type == stream_type,
+            )
+            .order_by(Recordings.start_time.desc())
+            .limit(window)
+            .alias("recent")
+        )
+        avg: float | None = Recordings.select(fn.AVG(SQL("bw"))).from_(recent).scalar()
+        return avg
+
     def calculate_camera_bandwidth(self) -> None:
         """Calculate an average MB/hr for each camera."""
         for camera in self.config.cameras.keys():
@@ -42,39 +76,50 @@ class StorageMaintainer(threading.Thread):
             if self.camera_storage_stats.get(camera, {}).get("needs_refresh", True):
                 self.camera_storage_stats[camera] = {
                     "needs_refresh": (
-                        Recordings.select(fn.COUNT("*"))
+                        Recordings.select(Recordings.id)
                         .where(Recordings.camera == camera, Recordings.segment_size > 0)
-                        .scalar()
+                        .limit(50)
+                        .count()
                         < 50
                     )
                 }
 
-                # calculate MB/hr from last 100 segments
-                try:
-                    # Subquery to get last 100 segments, then average their bandwidth
-                    last_100 = (
-                        Recordings.select(bandwidth_equation.alias("bw"))
-                        .where(Recordings.camera == camera, Recordings.segment_size > 0)
-                        .order_by(Recordings.start_time.desc())
-                        .limit(100)
-                        .alias("recent")
-                    )
-
-                    bandwidth = round(
-                        Recordings.select(fn.AVG(SQL("bw"))).from_(last_100).scalar()
-                        * 3600,
-                        2,
-                    )
-
-                    if bandwidth > MAX_CALCULATED_BANDWIDTH:
-                        logger.warning(
-                            f"{camera} has a bandwidth of {bandwidth} MB/hr which exceeds the expected maximum. This typically indicates an issue with the cameras recordings."
+                # calculate MB/hr from the last 100 segments of each stream
+                # type and sum the rates; mixing streams would average small
+                # sub segments against large main segments and underestimate
+                # the true write rate
+                bandwidth_by_stream: dict[str, float] = {}
+                for stream_type in (STREAM_TYPE_MAIN, STREAM_TYPE_SUB):
+                    avg_bw = self._recent_stream_bandwidth(camera, stream_type, 100)
+                    if avg_bw is None:
+                        # the recent window can be all zero-size ingest
+                        # glitches; look further back before concluding
+                        # the stream writes nothing
+                        avg_bw = self._recent_stream_bandwidth(
+                            camera, stream_type, 1000
                         )
-                        bandwidth = MAX_CALCULATED_BANDWIDTH
-                except TypeError:
-                    bandwidth = 0
+                    if avg_bw is not None:
+                        bandwidth_by_stream[stream_type] = round(avg_bw * 3600, 2)
+
+                bandwidth = round(sum(bandwidth_by_stream.values()), 2)
+
+                if bandwidth > MAX_CALCULATED_BANDWIDTH:
+                    logger.warning(
+                        f"{camera} has a bandwidth of {bandwidth} MB/hr which exceeds the expected maximum. This typically indicates an issue with the cameras recordings."
+                    )
+                    # scale each stream so the per stream values still sum to
+                    # the clamped total the UI displays alongside them
+                    scale = MAX_CALCULATED_BANDWIDTH / bandwidth
+                    bandwidth_by_stream = {
+                        stream_type: round(value * scale, 2)
+                        for stream_type, value in bandwidth_by_stream.items()
+                    }
+                    bandwidth = MAX_CALCULATED_BANDWIDTH
 
                 self.camera_storage_stats[camera]["bandwidth"] = bandwidth
+                self.camera_storage_stats[camera]["bandwidth_by_stream"] = (
+                    bandwidth_by_stream
+                )
                 logger.debug(f"{camera} has a bandwidth of {bandwidth} MiB/hr.")
 
     def calculate_camera_usages(self) -> dict[str, dict]:
@@ -86,20 +131,42 @@ class StorageMaintainer(threading.Thread):
             if camera.startswith(REPLAY_CAMERA_PREFIX):
                 continue
 
-            camera_storage = (
-                Recordings.select(fn.SUM(Recordings.segment_size))
-                .where(Recordings.camera == camera, Recordings.segment_size != 0)
-                .scalar()
+            stream_usages = {
+                row["stream_type"]: row["usage"] or 0
+                for row in (
+                    Recordings.select(
+                        Recordings.stream_type,
+                        fn.SUM(Recordings.segment_size).alias("usage"),
+                    )
+                    .where(Recordings.camera == camera, Recordings.segment_size != 0)
+                    .group_by(Recordings.stream_type)
+                    .dicts()
+                )
+            }
+            stream_bandwidths = self.camera_storage_stats.get(camera, {}).get(
+                "bandwidth_by_stream", {}
             )
 
             camera_key = (
                 getattr(self.config.cameras[camera], "friendly_name", None) or camera
             )
             usages[camera_key] = {
-                "usage": camera_storage,
+                "usage": sum(stream_usages.values()),
                 "bandwidth": self.camera_storage_stats.get(camera, {}).get(
                     "bandwidth", 0
                 ),
+                # only streams with segments on disk are reported, so a camera
+                # keeps its sub entry until sub retention expires those segments.
+                # bandwidth is null rather than 0 when the cache holds no sample
+                # for the stream, since 0 would claim it writes nothing
+                "streams": {
+                    stream_type: {
+                        "usage": stream_usages[stream_type],
+                        "bandwidth": stream_bandwidths.get(stream_type),
+                    }
+                    for stream_type in (STREAM_TYPE_MAIN, STREAM_TYPE_SUB)
+                    if stream_usages.get(stream_type)
+                },
             }
 
         return usages

frigate/test/http_api/test_http_config_set.py

@@ -7,7 +7,7 @@ from unittest.mock import MagicMock, Mock, patch
 
 import ruamel.yaml
 
-from frigate.config import FrigateConfig
+from frigate.config import BirdseyeModeEnum, FrigateConfig
 from frigate.config.camera.updater import (
     CameraConfigUpdateEnum,
     CameraConfigUpdatePublisher,
@@ -383,12 +383,15 @@ class TestConfigSetWildcardPropagation(BaseTestHttp):
         Global birdseye only seeds enabled and mode; the camera copies are what
         the output process actually reads. Sending just the global object makes
         a worker guess which cameras were inheriting, and the only available
-        guess (mode still equals the previous global) wrongly claims a camera
-        whose explicit yaml mode happens to match.
+        guess (modes still equals the previous global) wrongly claims a camera
+        whose explicit yaml modes happens to match.
         """
-        self.minimal_config["birdseye"] = {"enabled": True, "mode": "motion"}
+        self.minimal_config["birdseye"] = {
+            "enabled": True,
+            "modes": ["motion"],
+        }
         # 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"] = {"modes": ["motion"]}
 
         config_path = self._write_config_file()
         mock_find_config.return_value = config_path
@@ -399,7 +402,7 @@ class TestConfigSetWildcardPropagation(BaseTestHttp):
                 resp = client.put(
                     "/config/set",
                     json={
-                        "config_data": {"birdseye": {"mode": "continuous"}},
+                        "config_data": {"birdseye": {"modes": ["continuous"]}},
                         "update_topic": "config/birdseye",
                         "requires_restart": 0,
                     },
@@ -411,7 +414,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.modes, [BirdseyeModeEnum.continuous])
 
                 published = {
                     call[0][0].camera: call[0][1]
@@ -425,8 +428,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"].modes, [BirdseyeModeEnum.motion]
+                )
+                self.assertEqual(
+                    published["back_yard"].modes, [BirdseyeModeEnum.continuous]
+                )
         finally:
             os.unlink(config_path)
 

frigate/test/test_audio.py

@@ -0,0 +1,75 @@
+"""Tests for audio label mapping."""
+
+import threading
+import unittest
+from unittest.mock import Mock
+
+import numpy as np
+
+from frigate.events.audio import AudioTfl
+
+
+class TestAudioTfl(unittest.TestCase):
+    def setUp(self):
+        self.detector = AudioTfl.__new__(AudioTfl)
+        self.detector.stop_event = threading.Event()
+        self.detector._default_labels = {
+            69: "dog",
+            70: "bark",
+            75: "whimper_dog",
+            117: "dogs",
+        }
+
+    def test_update_labelmap_replaces_and_resets_overrides(self):
+        self.detector.update_labelmap({69: "dogs", 70: "dogs"})
+        assert self.detector.labels == {
+            69: "dogs",
+            70: "dogs",
+            75: "whimper_dog",
+            117: "dogs",
+        }
+
+        self.detector.update_labelmap({75: "whimper"})
+        assert self.detector.labels == {
+            69: "dog",
+            70: "bark",
+            75: "whimper",
+            117: "dogs",
+        }
+
+    def test_detect_returns_highest_scoring_detection_for_grouped_label(self):
+        self.detector.update_labelmap({69: "dogs", 70: "dogs", 75: "dogs"})
+        self.detector._detect_raw = Mock(
+            return_value=np.array(
+                [
+                    [117, 0.95, -1, -1, -1, -1],
+                    [70, 0.9, -1, -1, -1, -1],
+                    [69, 0.8, -1, -1, -1, -1],
+                    [75, 0.7, -1, -1, -1, -1],
+                ],
+                dtype=np.float32,
+            )
+        )
+
+        detections = self.detector.detect(np.array([], dtype=np.float32))
+
+        assert len(detections) == 1
+        assert detections[0][0] == "dogs"
+        self.assertAlmostEqual(detections[0][1], 0.95)
+
+    def test_each_dog_audio_label_maps_to_grouped_label(self):
+        self.detector.update_labelmap({69: "dogs", 70: "dogs", 75: "dogs"})
+
+        for class_id in (69, 70, 75):
+            with self.subTest(class_id=class_id):
+                self.detector._detect_raw = Mock(
+                    return_value=np.array(
+                        [[class_id, 0.9, -1, -1, -1, -1]], dtype=np.float32
+                    )
+                )
+
+                detections = self.detector.detect(np.array([], dtype=np.float32))
+
+                assert len(detections) == 1
+                assert detections[0][0] == "dogs"
+                self.assertAlmostEqual(detections[0][1], 0.9)

frigate/test/test_birdseye.py

@@ -1,13 +1,75 @@
-"""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 (
+    BirdseyeModeEnum,
+    FrigateConfig,
+    birdseye_modes_from_mqtt_payload,
+    birdseye_modes_to_mqtt_payload,
+)
+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 +110,258 @@ 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,
+                "modes": ["motion", "all_objects"],
+            },
+            "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_each_mode_matches_only_its_own_activity(self):
+        motion_activity = BirdseyeActivity(
+            has_object=False, has_motion=True, severity=None
+        )
+        object_activity = BirdseyeActivity(
+            has_object=True, has_motion=False, severity=None
+        )
+        no_activity = BirdseyeActivity(
+            has_object=False, has_motion=False, severity=None
+        )
+
+        assert self.manager.camera_threshold_active(
+            [BirdseyeModeEnum.motion], motion_activity
+        )
+        assert not self.manager.camera_threshold_active(
+            [BirdseyeModeEnum.motion], object_activity
+        )
+        assert self.manager.camera_threshold_active(
+            [BirdseyeModeEnum.all_objects], object_activity
+        )
+        assert not self.manager.camera_threshold_active(
+            [BirdseyeModeEnum.all_objects], motion_activity
+        )
+        assert self.manager.camera_live_active(
+            [BirdseyeModeEnum.continuous], no_activity
+        )
+
+    def test_continuous_is_not_threshold_activity(self):
+        no_activity = BirdseyeActivity(
+            has_object=False, has_motion=False, severity=None
+        )
+
+        assert not self.manager.camera_threshold_active(
+            [BirdseyeModeEnum.continuous], no_activity
+        )
+
+    def test_modes_can_be_combined(self):
+        modes = [BirdseyeModeEnum.motion, BirdseyeModeEnum.all_objects]
+
+        assert self.manager.camera_threshold_active(
+            modes, BirdseyeActivity(has_object=False, has_motion=True, severity=None)
+        )
+        assert self.manager.camera_threshold_active(
+            modes, BirdseyeActivity(has_object=True, has_motion=False, severity=None)
+        )
+        assert not self.manager.camera_threshold_active(
+            modes, BirdseyeActivity(has_object=False, has_motion=False, severity=None)
+        )
+
+    def test_empty_modes_never_activate(self):
+        activity = BirdseyeActivity(has_object=True, has_motion=True, severity=None)
+
+        assert not self.manager.camera_threshold_active([], activity)
+        assert not self.manager.camera_live_active([], activity)
+
+    def test_alerts_and_detections_match_review_severity(self):
+        alert = BirdseyeActivity(has_object=False, has_motion=False, severity="alert")
+        detection = BirdseyeActivity(
+            has_object=False, has_motion=False, severity="detection"
+        )
+        idle = BirdseyeActivity(has_object=False, has_motion=False, severity=None)
+
+        assert self.manager.camera_live_active([BirdseyeModeEnum.alerts], alert)
+        assert not self.manager.camera_live_active([BirdseyeModeEnum.alerts], detection)
+        assert not self.manager.camera_live_active([BirdseyeModeEnum.alerts], idle)
+        assert self.manager.camera_live_active([BirdseyeModeEnum.detections], detection)
+        assert not self.manager.camera_live_active([BirdseyeModeEnum.detections], alert)
+
+    def test_review_severity_is_not_threshold_activity(self):
+        alert = BirdseyeActivity(has_object=False, has_motion=False, severity="alert")
+
+        assert not self.manager.camera_threshold_active(
+            [BirdseyeModeEnum.alerts, BirdseyeModeEnum.motion], alert
+        )
+
+    def test_all_objects_covers_active_and_stationary_objects(self):
+        birdseye = Birdseye.__new__(Birdseye)
+        birdseye.birdseye_manager = Mock()
+        birdseye.birdseye_manager.update.return_value = (False, False)
+        birdseye._idle_interval = None
+        birdseye.review_severity = {}
+        frame = Mock()
+
+        birdseye.write_data(
+            "front",
+            [
+                {"stationary": True, "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(has_object=True, has_motion=True, severity=None),
+            1.0,
+            frame,
+        )
+
+    def test_false_positives_do_not_count_as_objects(self):
+        birdseye = Birdseye.__new__(Birdseye)
+        birdseye.birdseye_manager = Mock()
+        birdseye.birdseye_manager.update.return_value = (False, False)
+        birdseye._idle_interval = None
+        birdseye.review_severity = {}
+        frame = Mock()
+
+        birdseye.write_data(
+            "front",
+            [
+                {"stationary": True, "false_positive": True},
+                {"stationary": False, "false_positive": True},
+            ],
+            [],
+            1.0,
+            frame,
+        )
+
+        birdseye.birdseye_manager.update.assert_called_once_with(
+            "front",
+            BirdseyeActivity(has_object=False, has_motion=False, severity=None),
+            1.0,
+            frame,
+        )
+
 
 class TestBirdseyeCameraOrder(unittest.TestCase):
     """Test that birdseye reacts to camera order changes without a restart."""
@@ -55,7 +369,7 @@ class TestBirdseyeCameraOrder(unittest.TestCase):
     def setUp(self):
         config = {
             "mqtt": {"enabled": False},
-            "birdseye": {"enabled": True, "mode": "continuous"},
+            "birdseye": {"enabled": True, "modes": ["continuous"]},
             "cameras": {
                 camera: {
                     "ffmpeg": {
@@ -77,6 +391,7 @@ class TestBirdseyeCameraOrder(unittest.TestCase):
             camera_data["current_frame"] = None
             camera_data["current_frame_time"] = 1.0
             camera_data["last_active_frame"] = 1.0
+            camera_data["live_active"] = True
 
     def layout_order(self) -> list[str]:
         """Return the cameras in the order the current layout renders them."""
@@ -114,3 +429,155 @@ class TestBirdseyeCameraOrder(unittest.TestCase):
 
         assert not layout_changed
         assert self.layout_order() == ["back", "front", "side"]
+
+
+class TestBirdseyeLiveActivity(unittest.TestCase):
+    """Test that live activity bypasses the inactivity threshold."""
+
+    def setUp(self):
+        config = {
+            "mqtt": {"enabled": False},
+            "birdseye": {
+                "enabled": True,
+                "modes": ["continuous"],
+                "inactivity_threshold": 30,
+            },
+            "cameras": {
+                camera: {
+                    "ffmpeg": {
+                        "inputs": [
+                            {"path": "rtsp://10.0.0.1:554/video", "roles": ["detect"]}
+                        ]
+                    },
+                    "detect": {"height": 1080, "width": 1920, "fps": 5},
+                }
+                for camera in ("back", "front")
+            },
+        }
+        self.config = FrigateConfig(**config)
+        self.manager = BirdsEyeFrameManager(self.config, mp.Event())
+
+        for camera_data in self.manager.cameras.values():
+            camera_data["current_frame"] = None
+            camera_data["current_frame_time"] = 1000.0
+            camera_data["last_active_frame"] = 0.0
+            camera_data["live_active"] = False
+
+    def test_live_active_camera_is_shown_without_a_recent_active_frame(self):
+        self.manager.cameras["front"]["live_active"] = True
+
+        self.manager.update_frame()
+
+        assert self.manager.active_cameras == {"front"}
+
+    def test_live_active_camera_drops_out_immediately(self):
+        self.manager.cameras["front"]["live_active"] = True
+        self.manager.update_frame()
+        assert self.manager.active_cameras == {"front"}
+
+        self.manager.cameras["front"]["live_active"] = False
+        self.manager.update_frame()
+
+        assert self.manager.active_cameras == set()
+
+    def test_threshold_activity_lingers_then_expires(self):
+        self.manager.cameras["front"]["last_active_frame"] = 980.0
+        self.manager.update_frame()
+        assert self.manager.active_cameras == {"front"}
+
+        self.manager.cameras["front"]["last_active_frame"] = 960.0
+        self.manager.update_frame()
+
+        assert self.manager.active_cameras == set()
+
+    def test_max_cameras_ranks_live_active_cameras_first(self):
+        self.config.birdseye.layout.max_cameras = 1
+        self.manager.cameras["front"]["live_active"] = True
+        self.manager.cameras["back"]["last_active_frame"] = 995.0
+
+        self.manager.update_frame()
+
+        assert self.manager.active_cameras == {"front"}
+
+
+class TestBirdseyeModePayload(unittest.TestCase):
+    """Test the MQTT payload contract for Birdseye activity modes."""
+
+    def test_single_mode_round_trips(self):
+        modes = birdseye_modes_from_mqtt_payload("ALERTS")
+
+        assert modes == [BirdseyeModeEnum.alerts]
+        assert birdseye_modes_to_mqtt_payload(modes) == "ALERTS"
+
+    def test_combined_modes_are_published_in_enum_order(self):
+        modes = birdseye_modes_from_mqtt_payload("ALERTS,MOTION")
+
+        assert modes == [BirdseyeModeEnum.alerts, BirdseyeModeEnum.motion]
+        assert birdseye_modes_to_mqtt_payload(modes) == "MOTION,ALERTS"
+
+    def test_none_round_trips_to_an_empty_list(self):
+        assert birdseye_modes_from_mqtt_payload("NONE") == []
+        assert birdseye_modes_to_mqtt_payload([]) == "NONE"
+
+    def test_invalid_payloads_are_rejected(self):
+        for payload in (
+            "UNKNOWN",
+            "motion",
+            "MOTION_OBJECTS",
+            "NONE,MOTION",
+            "MOTION,MOTION",
+            "MOTION,",
+            "",
+        ):
+            with self.subTest(payload=payload):
+                assert birdseye_modes_from_mqtt_payload(payload) is None
+
+
+class TestBirdseyeReviewSeverity(unittest.TestCase):
+    """Test that review updates drive the per-camera severity map."""
+
+    def setUp(self):
+        self.birdseye = Birdseye.__new__(Birdseye)
+        self.birdseye.review_subscriber = Mock()
+        self.birdseye.review_severity = {}
+        self.birdseye.birdseye_manager = Mock()
+        self.birdseye.birdseye_manager.update.return_value = (False, False)
+        self.birdseye._idle_interval = None
+
+    def _drain(self, *updates):
+        self.birdseye.review_subscriber.check_for_update.side_effect = [*updates, None]
+        self.birdseye.check_review_updates()
+
+    def test_new_segment_sets_severity(self):
+        self._drain({"type": "new", "after": {"camera": "front", "severity": "alert"}})
+
+        assert self.birdseye.review_severity == {"front": "alert"}
+
+    def test_update_upgrades_severity(self):
+        self._drain(
+            {"type": "new", "after": {"camera": "front", "severity": "detection"}},
+            {"type": "update", "after": {"camera": "front", "severity": "alert"}},
+        )
+
+        assert self.birdseye.review_severity == {"front": "alert"}
+
+    def test_end_clears_severity(self):
+        self._drain(
+            {"type": "new", "after": {"camera": "front", "severity": "alert"}},
+            {"type": "end", "after": {"camera": "front", "severity": "alert"}},
+        )
+
+        assert self.birdseye.review_severity == {}
+
+    def test_write_data_passes_the_tracked_severity(self):
+        self.birdseye.review_severity = {"front": "alert"}
+        frame = Mock()
+
+        self.birdseye.write_data("front", [], [], 1.0, frame)
+
+        self.birdseye.birdseye_manager.update.assert_called_once_with(
+            "front",
+            BirdseyeActivity(has_object=False, has_motion=False, severity="alert"),
+            1.0,
+            frame,
+        )

frigate/test/test_camera_config_updater.py

@@ -0,0 +1,102 @@
+"""Tests for dynamic camera config updates recreating ffmpeg commands."""
+
+import unittest
+from unittest.mock import patch
+
+from frigate.config import CameraConfig, FrigateConfig
+from frigate.config.camera.updater import (
+    CameraConfigUpdateEnum,
+    CameraConfigUpdateSubscriber,
+)
+from frigate.const import SUB_CACHE_TAG
+
+
+def _build_camera_config(sub_enabled: bool) -> CameraConfig:
+    config = FrigateConfig(
+        **{
+            "mqtt": {"host": "mqtt"},
+            "cameras": {
+                "front_door": {
+                    "ffmpeg": {
+                        "inputs": [
+                            {
+                                "path": "rtsp://10.0.0.1:554/video",
+                                "roles": ["detect", "record"],
+                            },
+                            {
+                                "path": "rtsp://10.0.0.1:554/video2",
+                                "roles": ["record_sub"],
+                            },
+                        ]
+                    },
+                    "record": {"enabled": True, "sub": {"enabled": sub_enabled}},
+                }
+            },
+        }
+    )
+    return config.cameras["front_door"]
+
+
+def _has_sub_output(camera_config: CameraConfig) -> bool:
+    return any(
+        SUB_CACHE_TAG in part for c in camera_config.ffmpeg_cmds for part in c["cmd"]
+    )
+
+
+class TestRecordUpdateRecreatesFfmpegCmds(unittest.TestCase):
+    def setUp(self):
+        # avoid binding a real ZMQ socket; updates are fed directly through
+        # the mocked subscriber below
+        patcher = patch("frigate.config.camera.updater.ConfigSubscriber")
+        patcher.start()
+        self.addCleanup(patcher.stop)
+
+    def _push_record_update(
+        self, subscriber: CameraConfigUpdateSubscriber, record_config
+    ) -> None:
+        subscriber.subscriber.check_for_update.side_effect = [
+            ("config/cameras/front_door/record", record_config),
+            (None, None),
+        ]
+        subscriber.check_for_updates()
+
+    def test_enabling_sub_recreates_ffmpeg_cmds(self):
+        camera_config = _build_camera_config(sub_enabled=False)
+        subscriber = CameraConfigUpdateSubscriber(
+            None, {"front_door": camera_config}, [CameraConfigUpdateEnum.record]
+        )
+        assert not _has_sub_output(camera_config)
+
+        self._push_record_update(
+            subscriber, _build_camera_config(sub_enabled=True).record
+        )
+
+        assert _has_sub_output(camera_config)
+
+    def test_disabling_sub_recreates_ffmpeg_cmds(self):
+        camera_config = _build_camera_config(sub_enabled=True)
+        subscriber = CameraConfigUpdateSubscriber(
+            None, {"front_door": camera_config}, [CameraConfigUpdateEnum.record]
+        )
+        assert _has_sub_output(camera_config)
+
+        self._push_record_update(
+            subscriber, _build_camera_config(sub_enabled=False).record
+        )
+
+        assert not _has_sub_output(camera_config)
+
+    def test_unchanged_record_update_keeps_existing_cmds(self):
+        camera_config = _build_camera_config(sub_enabled=False)
+        subscriber = CameraConfigUpdateSubscriber(
+            None, {"front_door": camera_config}, [CameraConfigUpdateEnum.record]
+        )
+        cmds_before = camera_config.ffmpeg_cmds
+
+        # neither enabled_in_config nor sub.enabled changed, so the
+        # commands should not be rebuilt
+        self._push_record_update(
+            subscriber, _build_camera_config(sub_enabled=False).record
+        )
+
+        assert camera_config.ffmpeg_cmds is cmds_before

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

@@ -1,13 +1,14 @@
 import json
 import os
 import unittest
+from copy import deepcopy
 from unittest.mock import patch
 
 import numpy as np
 from pydantic import ValidationError
 from ruamel.yaml.constructor import DuplicateKeyError
 
-from frigate.config import BirdseyeModeEnum, FrigateConfig
+from frigate.config import BirdseyeModeEnum, FrigateConfig, RetainModeEnum
 from frigate.const import MODEL_CACHE_DIR
 from frigate.detectors import DetectorTypeEnum
 from frigate.util.builtin import deep_merge
@@ -170,7 +171,7 @@ class TestConfig(unittest.TestCase):
     def test_override_birdseye(self):
         config = {
             "mqtt": {"host": "mqtt"},
-            "birdseye": {"enabled": True, "mode": "continuous"},
+            "birdseye": {"enabled": True, "modes": ["continuous"]},
             "cameras": {
                 "back": {
                     "ffmpeg": {
@@ -183,19 +184,28 @@ class TestConfig(unittest.TestCase):
                         "width": 1920,
                         "fps": 5,
                     },
-                    "birdseye": {"enabled": False, "mode": "motion"},
+                    "birdseye": {
+                        "enabled": False,
+                        "modes": ["motion"],
+                    },
                 }
             },
         }
 
         frigate_config = FrigateConfig(**config)
         assert not frigate_config.cameras["back"].birdseye.enabled
-        assert frigate_config.cameras["back"].birdseye.mode is BirdseyeModeEnum.motion
+        assert frigate_config.cameras["back"].birdseye.modes == [
+            BirdseyeModeEnum.motion
+        ]
 
     def test_override_birdseye_non_inheritable(self):
         config = {
             "mqtt": {"host": "mqtt"},
-            "birdseye": {"enabled": True, "mode": "continuous", "height": 1920},
+            "birdseye": {
+                "enabled": True,
+                "modes": ["continuous"],
+                "height": 1920,
+            },
             "cameras": {
                 "back": {
                     "ffmpeg": {
@@ -217,29 +227,38 @@ class TestConfig(unittest.TestCase):
 
     def test_inherit_birdseye(self):
         config = {
-            "mqtt": {"host": "mqtt"},
-            "birdseye": {"enabled": True, "mode": "continuous"},
-            "cameras": {
-                "back": {
-                    "ffmpeg": {
-                        "inputs": [
-                            {"path": "rtsp://10.0.0.1:554/video", "roles": ["detect"]}
-                        ]
-                    },
-                    "detect": {
-                        "height": 1080,
-                        "width": 1920,
-                        "fps": 5,
-                    },
-                }
-            },
+            **self.minimal,
+            "birdseye": {"enabled": True, "modes": ["continuous"]},
         }
 
         frigate_config = FrigateConfig(**config)
         assert frigate_config.cameras["back"].birdseye.enabled
-        assert (
-            frigate_config.cameras["back"].birdseye.mode is BirdseyeModeEnum.continuous
-        )
+        assert frigate_config.cameras["back"].birdseye.modes == [
+            BirdseyeModeEnum.continuous
+        ]
+
+    def test_camera_modes_replace_the_global_list(self):
+        """A camera list fully replaces the global one, it does not merge into it."""
+        config = {
+            **self.minimal,
+            "birdseye": {"modes": ["motion", "all_objects"]},
+        }
+        config["cameras"]["back"]["birdseye"] = {"modes": ["alerts"]}
+
+        frigate_config = FrigateConfig(**config)
+        assert frigate_config.cameras["back"].birdseye.modes == [
+            BirdseyeModeEnum.alerts
+        ]
+
+    def test_camera_can_select_no_modes(self):
+        config = {
+            **self.minimal,
+            "birdseye": {"modes": ["motion"]},
+        }
+        config["cameras"]["back"]["birdseye"] = {"modes": []}
+
+        frigate_config = FrigateConfig(**config)
+        assert frigate_config.cameras["back"].birdseye.modes == []
 
     def test_override_tracked_objects(self):
         config = {
@@ -877,6 +896,162 @@ class TestConfig(unittest.TestCase):
         assert len(ffmpeg_cmds) == 1
         assert "clips" not in ffmpeg_cmds[0]["roles"]
 
+    def test_record_sub_cmd_writes_sub_cache_path(self):
+        config = {
+            "mqtt": {"host": "mqtt"},
+            "cameras": {
+                "back": {
+                    "ffmpeg": {
+                        "inputs": [
+                            {
+                                "path": "rtsp://10.0.0.1:554/video",
+                                "roles": ["detect", "record"],
+                            },
+                            {
+                                "path": "rtsp://10.0.0.1:554/video2",
+                                "roles": ["record_sub"],
+                            },
+                        ]
+                    },
+                    "record": {"enabled": True, "sub": {"enabled": True}},
+                }
+            },
+        }
+
+        frigate_config = FrigateConfig(**config)
+        cmds = frigate_config.cameras["back"].ffmpeg_cmds
+        sub_cmds = [c for c in cmds if "record_sub" in c["roles"]]
+        assert len(sub_cmds) == 1
+        joined = " ".join(sub_cmds[0]["cmd"])
+        assert "back@sub@" in joined
+
+    def test_record_sub_disabled_no_sub_cache_path(self):
+        config = {
+            "mqtt": {"host": "mqtt"},
+            "cameras": {
+                "back": {
+                    "ffmpeg": {
+                        "inputs": [
+                            {
+                                "path": "rtsp://10.0.0.1:554/video",
+                                "roles": ["detect", "record"],
+                            },
+                        ]
+                    },
+                    "record": {"enabled": True, "sub": {"enabled": False}},
+                }
+            },
+        }
+
+        frigate_config = FrigateConfig(**config)
+        cmds = frigate_config.cameras["back"].ffmpeg_cmds
+        assert all("@sub@" not in " ".join(c["cmd"]) for c in cmds)
+
+    def _sub_record_config(self, ffmpeg_extra: dict | None = None) -> dict:
+        return {
+            "mqtt": {"host": "mqtt"},
+            "cameras": {
+                "back": {
+                    "ffmpeg": {
+                        "inputs": [
+                            {
+                                "path": "rtsp://10.0.0.1:554/video",
+                                "roles": ["detect", "record"],
+                            },
+                            {
+                                "path": "rtsp://10.0.0.1:554/video2",
+                                "roles": ["record_sub"],
+                            },
+                        ],
+                        **(ffmpeg_extra or {}),
+                    },
+                    "record": {"enabled": True, "sub": {"enabled": True}},
+                }
+            },
+        }
+
+    def _sub_record_cmd(self, config: dict) -> str:
+        cmds = FrigateConfig(**config).cameras["back"].ffmpeg_cmds
+        sub_cmds = [c for c in cmds if "record_sub" in c["roles"]]
+        assert len(sub_cmds) == 1
+        return " ".join(sub_cmds[0]["cmd"])
+
+    def test_record_sub_output_args_inherit_record(self):
+        config = self._sub_record_config(
+            {"output_args": {"record": "preset-record-generic-audio-copy"}}
+        )
+
+        cmd = self._sub_record_cmd(config)
+        # the customized record args, not the stock aac default
+        assert "-c copy" in cmd
+        assert "-c:a aac" not in cmd
+
+    def test_record_sub_output_args_override_record(self):
+        config = self._sub_record_config(
+            {
+                "output_args": {
+                    "record": "preset-record-generic-audio-aac",
+                    "record_sub": "preset-record-generic",
+                }
+            }
+        )
+
+        cmd = self._sub_record_cmd(config)
+        assert "-c copy -an" in cmd
+        assert "-c:a aac" not in cmd
+
+    def test_record_output_args_unaffected_by_record_sub(self):
+        config = self._sub_record_config(
+            {
+                "output_args": {
+                    "record": "preset-record-generic-audio-aac",
+                    "record_sub": "preset-record-generic",
+                }
+            }
+        )
+
+        cmds = FrigateConfig(**config).cameras["back"].ffmpeg_cmds
+        record_cmd = " ".join(next(c for c in cmds if "record" in c["roles"])["cmd"])
+        assert "-c:a aac" in record_cmd
+
+    def test_record_sub_manual_output_args(self):
+        config = self._sub_record_config(
+            {
+                "output_args": {
+                    "record_sub": "-f segment -segment_time 10 -segment_format mp4 -reset_timestamps 1 -strftime 1 -c:v copy -c:a aac -ar 16000"
+                }
+            }
+        )
+
+        assert "-ar 16000" in self._sub_record_cmd(config)
+
+    def test_fails_on_bad_record_sub_segment_time(self):
+        config = self._sub_record_config(
+            {
+                "output_args": {
+                    "record_sub": "-f segment -segment_time 70 -segment_format mp4 -reset_timestamps 1 -strftime 1 -c copy -an"
+                }
+            }
+        )
+
+        self.assertRaisesRegex(
+            ValueError,
+            "segment_time",
+            lambda: FrigateConfig(**config).cameras,
+        )
+
+    def test_record_sub_segment_time_not_checked_when_disabled(self):
+        config = self._sub_record_config(
+            {
+                "output_args": {
+                    "record_sub": "-f segment -segment_time 70 -segment_format mp4 -reset_timestamps 1 -strftime 1 -c copy -an"
+                }
+            }
+        )
+        config["cameras"]["back"]["record"]["sub"]["enabled"] = False
+
+        FrigateConfig(**config).cameras
+
     def test_max_disappeared_default(self):
         config = {
             "mqtt": {"host": "mqtt"},
@@ -979,6 +1154,28 @@ class TestConfig(unittest.TestCase):
         frigate_config = FrigateConfig(**config)
         assert frigate_config.model.merged_labelmap[7] == "truck"
 
+    def test_audio_labelmap_inheritance_is_separate_from_model_labelmap(self):
+        config = deep_merge(
+            {
+                "audio": {"labelmap": {69: "dogs", 70: "dogs"}},
+                "cameras": {
+                    "back": {
+                        "audio": {"labelmap": {75: "dogs"}},
+                    }
+                },
+            },
+            self.minimal,
+        )
+
+        frigate_config = FrigateConfig(**config)
+
+        assert frigate_config.cameras["back"].audio.labelmap == {
+            69: "dogs",
+            70: "dogs",
+            75: "dogs",
+        }
+        assert frigate_config.model.merged_labelmap[69] != "dogs"
+
     def test_default_labelmap_empty(self):
         config = {
             "mqtt": {"host": "mqtt"},
@@ -1119,6 +1316,44 @@ class TestConfig(unittest.TestCase):
 
         self.assertRaises(ValueError, lambda: FrigateConfig(**config))
 
+    def test_record_sub_config_defaults(self):
+        config = FrigateConfig(**self.minimal)
+        record = config.cameras["back"].record
+        assert record.sub.enabled is False
+        assert record.sub.continuous.days == 0
+        assert record.sub.alerts.mode == RetainModeEnum.motion
+
+    def test_record_sub_enabled_requires_role(self):
+        config = deepcopy(self.minimal)
+        config["cameras"]["back"]["ffmpeg"]["inputs"] = [
+            {"path": "rtsp://10.0.0.1:554/video", "roles": ["detect", "record"]},
+        ]
+        config["cameras"]["back"]["record"] = {
+            "enabled": True,
+            "sub": {"enabled": True},
+        }
+
+        # no record_sub role assigned -> must raise
+        self.assertRaisesRegex(
+            ValueError,
+            "record_sub is not assigned",
+            lambda: FrigateConfig(**config),
+        )
+
+    def test_record_sub_role_accepted(self):
+        config = deepcopy(self.minimal)
+        config["cameras"]["back"]["ffmpeg"]["inputs"] = [
+            {"path": "rtsp://10.0.0.1:554/video", "roles": ["detect", "record"]},
+            {"path": "rtsp://10.0.0.1:554/video2", "roles": ["record_sub"]},
+        ]
+        config["cameras"]["back"]["record"] = {
+            "enabled": True,
+            "sub": {"enabled": True, "continuous": {"days": 30}},
+        }
+
+        parsed = FrigateConfig(**config)
+        assert parsed.cameras["back"].record.sub.continuous.days == 30
+
     def test_works_on_missing_role_multiple_cams(self):
         config = {
             "mqtt": {"host": "mqtt"},

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 BirdseyeModeEnum
 
 
 def _make_camera_mock(
@@ -51,6 +52,60 @@ 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 activity list 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_modes_command("front_door", "ALERTS,MOTION")
+
+        self.assertEqual(
+            self.camera.birdseye.modes,
+            [BirdseyeModeEnum.alerts, BirdseyeModeEnum.motion],
+        )
+        self.dispatcher.config_updater.publish_update.assert_called_once()
+        self.dispatcher.publish.assert_called_once_with(
+            "front_door/birdseye_modes/state",
+            "MOTION,ALERTS",
+            retain=True,
+        )
+
+    def test_single_activity_type_is_accepted(self) -> None:
+        self.dispatcher._on_birdseye_modes_command("front_door", "ALL_OBJECTS")
+
+        self.assertEqual(self.camera.birdseye.modes, [BirdseyeModeEnum.all_objects])
+        self.dispatcher.publish.assert_called_once_with(
+            "front_door/birdseye_modes/state", "ALL_OBJECTS", retain=True
+        )
+
+    def test_none_clears_every_activity_type(self) -> None:
+        self.dispatcher._on_birdseye_modes_command("front_door", "NONE")
+
+        self.assertEqual(self.camera.birdseye.modes, [])
+        self.dispatcher.publish.assert_called_once_with(
+            "front_door/birdseye_modes/state", "NONE", retain=True
+        )
+
+    def test_unknown_mode_is_rejected(self) -> None:
+        for payload in (
+            "UNKNOWN",
+            "motion",
+            "MOTION_OBJECTS",
+            "NONE,MOTION",
+            "MOTION,MOTION",
+            "MOTION,",
+        ):
+            with self.subTest(payload=payload):
+                self.dispatcher._on_birdseye_modes_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_event_cleanup_sub.py

@@ -0,0 +1,127 @@
+"""Tests for sub stream retention extending event clip lifetimes."""
+
+import datetime
+import unittest
+from unittest.mock import MagicMock
+
+from playhouse.sqlite_ext import SqliteExtDatabase
+
+from frigate.config import FrigateConfig
+from frigate.events.cleanup import EventCleanup
+from frigate.models import Event, Timeline
+
+
+class TestEventCleanupSubRetention(unittest.TestCase):
+    def setUp(self):
+        # in-memory database keeps these tests isolated from the shared
+        # on-disk test.db used by the http api tests
+        self.db = SqliteExtDatabase(":memory:")
+        models = [Event, Timeline]
+        self.db.bind(models)
+        self.db.create_tables(models)
+
+    def tearDown(self):
+        self.db.close()
+
+    def _build_cleanup(self, record_config: dict) -> EventCleanup:
+        config = FrigateConfig(
+            **{
+                "mqtt": {"host": "mqtt"},
+                "cameras": {
+                    "front_door": {
+                        "ffmpeg": {
+                            "inputs": [
+                                {
+                                    "path": "rtsp://10.0.0.1:554/video",
+                                    "roles": ["detect", "record"],
+                                },
+                                {
+                                    "path": "rtsp://10.0.0.1:554/video2",
+                                    "roles": ["record_sub"],
+                                },
+                            ]
+                        },
+                        "record": record_config,
+                    }
+                },
+            }
+        )
+        return EventCleanup(config, MagicMock(), MagicMock())
+
+    def _insert_event(self, id: str, age_days: float, severity: str = "alert") -> None:
+        end_time = (
+            datetime.datetime.now() - datetime.timedelta(days=age_days)
+        ).timestamp()
+        Event.create(
+            id=id,
+            label="person",
+            camera="front_door",
+            start_time=end_time - 10,
+            end_time=end_time,
+            top_score=0.9,
+            score=0.9,
+            false_positive=False,
+            zones=[],
+            thumbnail="",
+            has_clip=True,
+            has_snapshot=False,
+            region=[],
+            box=[],
+            area=0,
+            retain_indefinitely=False,
+            plus_id="",
+            model_hash="",
+            detector_type="cpu",
+            model_type="ssd",
+            data={"max_severity": severity},
+        )
+
+    def test_sub_alerts_days_extends_event_clip_retention(self):
+        # a 20-day-old alert event keeps its clip for the 60 day sub window
+        # so Explore stays coherent with the surviving sub recordings
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "alerts": {"retain": {"days": 10}},
+                "sub": {"enabled": True, "alerts": {"days": 60}},
+            }
+        )
+        self._insert_event("e1", 20)
+
+        expired = cleanup.expire_clips()
+
+        assert "e1" not in expired
+        assert Event.get(Event.id == "e1").has_clip is True
+
+    def test_event_clip_expires_when_sub_disabled(self):
+        # with sub recording disabled, the 20-day-old alert event expires
+        # under the 10 day main alerts retention exactly as before
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "alerts": {"retain": {"days": 10}},
+                "sub": {"enabled": False, "alerts": {"days": 60}},
+            }
+        )
+        self._insert_event("e1", 20)
+
+        expired = cleanup.expire_clips()
+
+        assert "e1" in expired
+        assert Event.get(Event.id == "e1").has_clip is False
+
+    def test_sub_detections_days_extends_event_clip_retention(self):
+        # detection severity uses the sub detections window
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "detections": {"retain": {"days": 10}},
+                "sub": {"enabled": True, "detections": {"days": 60}},
+            }
+        )
+        self._insert_event("e1", 20, severity="detection")
+
+        expired = cleanup.expire_clips()
+
+        assert "e1" not in expired
+        assert Event.get(Event.id == "e1").has_clip is True

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_maintainer.py

@@ -98,7 +98,9 @@ class TestMaintainer(unittest.IsolatedAsyncioTestCase):
         end_time = now - datetime.timedelta(seconds=10)
         cache_path = "/tmp/cache/test_cam@20260417150000+0000.mp4"
 
-        maintainer.end_time_cache = {cache_path: (end_time, 10.0)}
+        maintainer.end_time_cache = {
+            cache_path: (end_time, 10.0, None, None, None, None, None)
+        }
         # Single processed frame well past end_time with no motion/objects.
         maintainer.object_recordings_info["test_cam"] = [(now.timestamp(), [], [], [])]
         maintainer.audio_recordings_info["test_cam"] = []
@@ -109,7 +111,11 @@ class TestMaintainer(unittest.IsolatedAsyncioTestCase):
         result = await maintainer.validate_and_move_segment(
             "test_cam",
             reviews=[],
-            recording={"start_time": start_time, "cache_path": cache_path},
+            recording={
+                "start_time": start_time,
+                "cache_path": cache_path,
+                "stream_type": "main",
+            },
         )
 
         self.assertIsNone(result)
@@ -137,7 +143,8 @@ class TestMaintainer(unittest.IsolatedAsyncioTestCase):
             (recent, 0, []),
         ]
 
-        grouped_recordings = {"present_cam": [{"start_time": ancient}]}
+        # keyed by (camera, stream_type), matching what move_files passes
+        grouped_recordings = {("present_cam", "main"): [{"start_time": ancient}]}
 
         maintainer._expire_stale_recordings_info(grouped_recordings)
 

frigate/test/test_mqtt_lifecycle.py

@@ -0,0 +1,907 @@
+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_outage_buffer_replays_before_newer_queued_value(self) -> None:
+        """A topic that changed since the reconnect must not be reverted by the
+        replay of the value buffered during the outage."""
+        mock_client = MagicMock()
+        mock_client.publish.return_value = MagicMock(
+            rc=mqtt.MQTT_ERR_SUCCESS, mid=1, **{"is_published.return_value": True}
+        )
+        self.client._pending_retained = {"frigate/front/detect/state": ("OFF", True)}
+        self.client.client = mock_client
+        self.client.connected = True
+        self.client._subscription_ready = True
+        self.client._publish_queue.put(
+            QueuedPublish("frigate/front/detect/state", "ON", True)
+        )
+
+        self.client._drain_publish_queue()
+
+        published = [
+            (call.args[0], call.args[1]) for call in mock_client.publish.call_args_list
+        ]
+        self.assertEqual(
+            published,
+            [
+                ("frigate/front/detect/state", "OFF"),
+                ("frigate/front/detect/state", "ON"),
+            ],
+        )
+
+    def test_flush_failure_does_not_clobber_newer_queued_value(self) -> None:
+        """If the session dies mid-replay, the newer queued value that gets
+        rebuffered has to win over the older entries still being replayed."""
+        self.client._pending_retained = {
+            "frigate/a/detect/state": ("OLD", True),
+            "frigate/front/detect/state": ("OFF", True),
+        }
+        self.client.connected = True
+        self.client._subscription_ready = True
+        self.client._publish_queue.put(
+            QueuedPublish("frigate/front/detect/state", "ON", True)
+        )
+
+        mock_client = MagicMock()
+        mock_client.publish.side_effect = BrokenPipeError("broken pipe")
+        self.client.client = mock_client
+
+        self.client._drain_publish_queue()
+
+        self.assertEqual(
+            self.client._pending_retained["frigate/front/detect/state"], ("ON", 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

@@ -6,7 +6,7 @@ import os
 import unittest
 from unittest.mock import MagicMock, patch
 
-from frigate.config import FrigateConfig
+from frigate.config import BirdseyeModeEnum, FrigateConfig
 from frigate.config.camera.profile import CameraProfileConfig
 from frigate.config.profile import ProfileDefinitionConfig
 from frigate.config.profile_manager import PERSISTENCE_FILE, ProfileManager
@@ -560,6 +560,24 @@ 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_replaces_birdseye_activity_modes(self, mock_persist):
+        """A profile mode list replaces the base list rather than merging into it."""
+        self.config.profiles["away"] = ProfileDefinitionConfig(friendly_name="Away")
+        self.config.cameras["front"].birdseye.modes = [
+            BirdseyeModeEnum.motion,
+            BirdseyeModeEnum.all_objects,
+        ]
+        self.config.cameras["front"].profiles["away"] = CameraProfileConfig(
+            birdseye={"modes": ["alerts"]}
+        )
+        self.manager = ProfileManager(self.config, self.mock_updater)
+
+        err = self.manager.activate_profile("away")
+
+        assert err is None
+        assert self.config.cameras["front"].birdseye.modes == [BirdseyeModeEnum.alerts]
+
     @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 +738,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/test/test_record_cleanup_sub.py

@@ -0,0 +1,253 @@
+"""Tests for independent sub stream retention in recording cleanup."""
+
+import datetime
+import unittest
+from unittest.mock import MagicMock
+
+from playhouse.sqlite_ext import SqliteExtDatabase
+
+from frigate.config import FrigateConfig
+from frigate.models import Previews, Recordings, ReviewSegment, UserReviewStatus
+from frigate.record.cleanup import RecordingCleanup
+
+
+class TestRecordingCleanupSubRetention(unittest.TestCase):
+    def setUp(self):
+        # in-memory database keeps these tests isolated from the shared
+        # on-disk test.db used by the http api tests
+        self.db = SqliteExtDatabase(":memory:")
+        models = [Previews, Recordings, ReviewSegment, UserReviewStatus]
+        self.db.bind(models)
+        self.db.create_tables(models)
+
+    def tearDown(self):
+        self.db.close()
+
+    def _build_cleanup(self, record_config: dict) -> RecordingCleanup:
+        config = FrigateConfig(
+            **{
+                "mqtt": {"host": "mqtt"},
+                "cameras": {
+                    "front_door": {
+                        "ffmpeg": {
+                            "inputs": [
+                                {
+                                    "path": "rtsp://10.0.0.1:554/video",
+                                    "roles": ["detect", "record"],
+                                },
+                                {
+                                    "path": "rtsp://10.0.0.1:554/video2",
+                                    "roles": ["record_sub"],
+                                },
+                            ]
+                        },
+                        "record": record_config,
+                    }
+                },
+            }
+        )
+        return RecordingCleanup(config, MagicMock())
+
+    def _insert_recording(
+        self,
+        id: str,
+        stream_type: str,
+        age_days: float,
+        motion: int = 0,
+        camera: str = "front_door",
+    ) -> None:
+        end_time = (
+            datetime.datetime.now() - datetime.timedelta(days=age_days)
+        ).timestamp()
+        Recordings.create(
+            id=id,
+            camera=camera,
+            path=f"/media/frigate/recordings/{id}.mp4",
+            start_time=end_time - 10,
+            end_time=end_time,
+            duration=10,
+            motion=motion,
+            objects=0,
+            dBFS=0,
+            segment_size=0,
+            stream_type=stream_type,
+        )
+
+    def test_sub_recordings_expire_independently(self):
+        # main retention 7 days, sub retention 30 days; rows 10 days old
+        # -> main row deleted, sub row kept
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "continuous": {"days": 7},
+                "sub": {"enabled": True, "continuous": {"days": 30}},
+            }
+        )
+        self._insert_recording("m1", "main", 10)
+        self._insert_recording("s1", "sub", 10)
+
+        cleanup.expire_recordings()
+
+        assert Recordings.get_or_none(Recordings.id == "m1") is None
+        assert Recordings.get_or_none(Recordings.id == "s1") is not None
+
+    def test_sub_recordings_expire_after_sub_retention(self):
+        # sub retention 30 days; sub row 40 days old -> deleted
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "continuous": {"days": 7},
+                "sub": {"enabled": True, "continuous": {"days": 30}},
+            }
+        )
+        self._insert_recording("s_old", "sub", 40)
+        self._insert_recording("s_new", "sub", 10)
+
+        cleanup.expire_recordings()
+
+        assert Recordings.get_or_none(Recordings.id == "s_old") is None
+        assert Recordings.get_or_none(Recordings.id == "s_new") is not None
+
+    def test_sub_recordings_overlapping_recent_reviews_survive(self):
+        # sub retention shorter than main: the reviews window must reach the
+        # sub pass cutoff or sub segments overlapping recent alerts are
+        # deleted on the first cleanup after being stored
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "continuous": {"days": 7},
+                "sub": {"enabled": True, "alerts": {"mode": "motion"}},
+            }
+        )
+        self._insert_recording("m1", "main", 1, motion=10)
+        self._insert_recording("s1", "sub", 1, motion=10)
+
+        # alert review covering the same time window as the recordings
+        recording = Recordings.get(Recordings.id == "s1")
+        ReviewSegment.create(
+            id="r1",
+            camera="front_door",
+            start_time=recording.start_time,
+            end_time=recording.end_time,
+            severity="alert",
+            thumb_path="/media/frigate/clips/review/thumb-r1.webp",
+            data={},
+        )
+
+        cleanup.expire_recordings()
+
+        assert Recordings.get_or_none(Recordings.id == "m1") is not None
+        assert Recordings.get_or_none(Recordings.id == "s1") is not None
+
+    def test_sub_alerts_days_extends_review_and_sub_retention(self):
+        # a 20-day-old alert review survives for the 60 day sub window and
+        # keeps the sub row alive, but must not hold the main row past the
+        # 10 day main alerts window
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "continuous": {"days": 7},
+                "sub": {"enabled": True, "alerts": {"days": 60}},
+            }
+        )
+        self._insert_recording("m1", "main", 20, motion=10)
+        self._insert_recording("s1", "sub", 20, motion=10)
+
+        # alert review covering the same time window as the recordings
+        recording = Recordings.get(Recordings.id == "s1")
+        ReviewSegment.create(
+            id="r1",
+            camera="front_door",
+            start_time=recording.start_time,
+            end_time=recording.end_time,
+            severity="alert",
+            thumb_path="/media/frigate/clips/review/thumb-r1.webp",
+            data={},
+        )
+
+        cleanup.expire_recordings()
+
+        assert ReviewSegment.get_or_none(ReviewSegment.id == "r1") is not None
+        assert Recordings.get_or_none(Recordings.id == "m1") is None
+        assert Recordings.get_or_none(Recordings.id == "s1") is not None
+
+    def test_main_review_lifetime_unchanged_when_sub_disabled(self):
+        # with sub recording disabled, the 20-day-old alert review expires
+        # under the 10 day main alerts retention exactly as before
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "continuous": {"days": 7},
+                "sub": {"enabled": False, "alerts": {"days": 60}},
+            }
+        )
+        end_time = (datetime.datetime.now() - datetime.timedelta(days=20)).timestamp()
+        ReviewSegment.create(
+            id="r1",
+            camera="front_door",
+            start_time=end_time - 10,
+            end_time=end_time,
+            severity="alert",
+            thumb_path="/media/frigate/clips/review/thumb-r1.webp",
+            data={},
+        )
+
+        cleanup.expire_recordings()
+
+        assert ReviewSegment.get_or_none(ReviewSegment.id == "r1") is None
+
+    def test_disabled_sub_still_expires_old_sub_rows(self):
+        # sub disabled but old sub rows remain: the sub pass still runs and
+        # expires them by the sub config dates
+        cleanup = self._build_cleanup(
+            {
+                "enabled": True,
+                "continuous": {"days": 7},
+                "sub": {"enabled": False, "continuous": {"days": 30}},
+            }
+        )
+        self._insert_recording("s_old", "sub", 40)
+        self._insert_recording("s_new", "sub", 10)
+
+        cleanup.expire_recordings()
+
+        assert Recordings.get_or_none(Recordings.id == "s_old") is None
+        assert Recordings.get_or_none(Recordings.id == "s_new") is not None
+
+    def test_deleted_camera_recordings_expire(self):
+        # rows for a camera no longer in the config expire by the GLOBAL
+        # record retention window; newer orphan rows and configured-camera
+        # rows are untouched by the deleted-cameras sweep
+        config = FrigateConfig(
+            **{
+                "mqtt": {"host": "mqtt"},
+                "record": {"continuous": {"days": 7}},
+                "cameras": {
+                    "front_door": {
+                        "ffmpeg": {
+                            "inputs": [
+                                {
+                                    "path": "rtsp://10.0.0.1:554/video",
+                                    "roles": ["detect", "record"],
+                                },
+                            ]
+                        },
+                        "record": {"enabled": True, "continuous": {"days": 7}},
+                    }
+                },
+            }
+        )
+        cleanup = RecordingCleanup(config, MagicMock())
+        self._insert_recording("gone_old", "main", 10, camera="removed_cam")
+        self._insert_recording("gone_new", "main", 5, camera="removed_cam")
+        self._insert_recording("gone_blank", "main", 10, camera="")
+        self._insert_recording("kept", "main", 5)
+
+        cleanup.expire_recordings()
+
+        assert Recordings.get_or_none(Recordings.id == "gone_old") is None
+        assert Recordings.get_or_none(Recordings.id == "gone_new") is not None
+        # empty-string camera names sort before every real name and must
+        # still be enumerated by the sweep
+        assert Recordings.get_or_none(Recordings.id == "gone_blank") is None
+        assert Recordings.get_or_none(Recordings.id == "kept") is not None

frigate/test/test_record_sub_maintainer.py

@@ -0,0 +1,544 @@
+"""Tests for sub stream cache segment handling in the recording maintainer."""
+
+import datetime
+import os
+import tempfile
+import unittest
+from collections import defaultdict
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from playhouse.sqlite_ext import SqliteExtDatabase
+
+from frigate.config import FrigateConfig
+from frigate.models import Recordings
+from frigate.record.maintainer import (
+    RecordingMaintainer,
+    SegmentInfo,
+    parse_cache_segment_name,
+)
+
+
+def _build_chaining_maintainer(
+    t0: float, retention: str = "continuous"
+) -> RecordingMaintainer:
+    """Build a maintainer for start-time chaining tests.
+
+    Built without __init__ to avoid the IPC scaffolding; move_segment and
+    drop_segment are mocked so the times passed downstream are observable.
+    """
+    camera_config = MagicMock()
+    camera_config.record.enabled = True
+    camera_config.record.event_pre_capture = 0
+    camera_config.detect.width = 1920
+    camera_config.detect.height = 1080
+    camera_config.record.continuous.days = 1 if retention == "continuous" else 0
+    camera_config.record.motion.days = 0 if retention == "continuous" else 1
+
+    # no spec: pydantic fields like config.ffmpeg are not visible to
+    # spec'd mocks, and the probe path needs them
+    config = MagicMock()
+    config.cameras = {"test_cam": camera_config}
+
+    maintainer = RecordingMaintainer.__new__(RecordingMaintainer)
+    maintainer.config = config
+    maintainer.end_time_cache = {}
+    maintainer.object_recordings_info = defaultdict(list)
+    maintainer.audio_recordings_info = defaultdict(list)
+    maintainer.recordings_publisher = MagicMock()
+    maintainer.drop_segment = MagicMock()
+    maintainer.move_segment = AsyncMock(return_value=None)
+    # pre-seed the chain state so the lazy DB seed query is not attempted
+    maintainer.last_segment_end = {("test_cam", "main"): 0.0}
+    # a processed frame far past any segment end marks segments ready
+    maintainer.object_recordings_info["test_cam"] = [(t0 + 1000, [], [], [])]
+    return maintainer
+
+
+async def _validate_segment(
+    maintainer: RecordingMaintainer,
+    t0: float,
+    offset: float,
+    duration: float,
+    mtime: float | None = None,
+):
+    """Run validate_and_move_segment for a segment named t0+offset.
+
+    mtime injects the cache file's close time; None simulates a missing file.
+    """
+    start = datetime.datetime.fromtimestamp(t0 + offset, tz=datetime.UTC)
+    probe = AsyncMock(return_value={"has_valid_video": True, "duration": duration})
+    getmtime = (
+        MagicMock(side_effect=OSError("missing"))
+        if mtime is None
+        else MagicMock(return_value=mtime)
+    )
+    with (
+        patch("frigate.record.maintainer.get_video_properties", probe),
+        patch(
+            "frigate.record.maintainer.get_keyframe_offsets",
+            AsyncMock(return_value=[0]),
+        ),
+        patch("frigate.record.maintainer.os.path.getmtime", getmtime),
+    ):
+        return await maintainer.validate_and_move_segment(
+            "test_cam",
+            reviews=[],
+            recording={
+                "start_time": start,
+                "cache_path": f"/tmp/cache/test_cam@chain{offset}.mp4",
+                "stream_type": "main",
+            },
+        )
+
+
+class TestParseCacheSegmentName(unittest.TestCase):
+    def test_parses_main_segment(self):
+        camera, stream_type, date = parse_cache_segment_name(
+            "front_door@20260610143022+0000"
+        )
+        assert camera == "front_door"
+        assert stream_type == "main"
+        assert date == "20260610143022+0000"
+
+    def test_parses_sub_segment(self):
+        camera, stream_type, date = parse_cache_segment_name(
+            "front_door@sub@20260610143022+0000"
+        )
+        assert camera == "front_door"
+        assert stream_type == "sub"
+        assert date == "20260610143022+0000"
+
+    def test_returns_none_for_unexpected_name(self):
+        assert parse_cache_segment_name("no_at_sign_here") is None
+
+
+class TestValidateAndMoveSubSegment(unittest.IsolatedAsyncioTestCase):
+    """Behavioral tests for sub stream segments in validate_and_move_segment.
+
+    The maintainer is built without __init__ to avoid the ZMQ scaffolding
+    the real constructor sets up.
+    """
+
+    def _build_maintainer(self, camera_config: MagicMock) -> RecordingMaintainer:
+        config = MagicMock(spec=FrigateConfig)
+        config.cameras = {"test_cam": camera_config}
+
+        maintainer = RecordingMaintainer.__new__(RecordingMaintainer)
+        maintainer.config = config
+        maintainer.end_time_cache = {}
+        maintainer.object_recordings_info = defaultdict(list)
+        maintainer.audio_recordings_info = defaultdict(list)
+        maintainer.drop_segment = MagicMock()
+        maintainer.recordings_publisher = MagicMock()
+        maintainer.move_segment = AsyncMock(return_value=None)
+        return maintainer
+
+    async def test_drops_sub_segment_when_sub_recording_disabled(self):
+        camera_config = MagicMock()
+        camera_config.record.enabled = True
+        camera_config.record.sub.enabled = False
+
+        maintainer = self._build_maintainer(camera_config)
+        cache_path = "/tmp/cache/test_cam@sub@20260610143022+0000.mp4"
+
+        result = await maintainer.validate_and_move_segment(
+            "test_cam",
+            reviews=[],
+            recording={
+                "start_time": datetime.datetime.now(datetime.UTC),
+                "cache_path": cache_path,
+                "stream_type": "sub",
+            },
+        )
+
+        self.assertIsNone(result)
+        maintainer.drop_segment.assert_called_once_with(cache_path)
+        maintainer.move_segment.assert_not_awaited()
+
+    async def test_sub_segment_uses_sub_continuous_retention(self):
+        # main continuous/motion are disabled, but sub continuous is enabled;
+        # the sub segment must be kept based on the sub retention config
+        camera_config = MagicMock()
+        camera_config.record.enabled = True
+        camera_config.record.sub.enabled = True
+        camera_config.record.continuous.days = 0
+        camera_config.record.motion.days = 0
+        camera_config.record.sub.continuous.days = 1
+        camera_config.record.sub.motion.days = 0
+
+        maintainer = self._build_maintainer(camera_config)
+
+        now = datetime.datetime.now(datetime.UTC)
+        start_time = now - datetime.timedelta(seconds=20)
+        end_time = now - datetime.timedelta(seconds=10)
+        cache_path = "/tmp/cache/test_cam@sub@20260610143022+0000.mp4"
+
+        # pre-fill the end time cache so no ffprobe is attempted; the
+        # audio and codec fields stay unknown without one
+        maintainer.end_time_cache = {
+            cache_path: (end_time, 10.0, None, None, None, None, None)
+        }
+        # a processed frame past end_time so the segment is considered ready
+        maintainer.object_recordings_info["test_cam"] = [(now.timestamp(), [], [], [])]
+
+        result = await maintainer.validate_and_move_segment(
+            "test_cam",
+            reviews=[],
+            recording={
+                "start_time": start_time,
+                "cache_path": cache_path,
+                "stream_type": "sub",
+            },
+        )
+
+        self.assertIsNone(result)
+        maintainer.move_segment.assert_awaited_once()
+        call_args = maintainer.move_segment.await_args.args
+        self.assertEqual(call_args[0], "test_cam")
+        self.assertEqual(call_args[1], "sub")
+        maintainer.drop_segment.assert_not_called()
+
+
+class TestSegmentAudioPresence(unittest.IsolatedAsyncioTestCase):
+    """Audio presence must flow from the segment probe into the DB insert."""
+
+    def _build_maintainer(self) -> RecordingMaintainer:
+        camera_config = MagicMock()
+        camera_config.record.enabled = True
+        camera_config.record.continuous.days = 1
+        camera_config.record.motion.days = 0
+
+        # no spec: pydantic fields like config.ffmpeg are not visible to
+        # spec'd mocks, and the probe/move paths need them
+        config = MagicMock()
+        config.cameras = {"test_cam": camera_config}
+
+        maintainer = RecordingMaintainer.__new__(RecordingMaintainer)
+        maintainer.config = config
+        maintainer.end_time_cache = {}
+        maintainer.object_recordings_info = defaultdict(list)
+        maintainer.audio_recordings_info = defaultdict(list)
+        maintainer.recordings_publisher = MagicMock()
+        # pre-seed the chain state so the lazy DB seed query is not attempted
+        maintainer.last_segment_end = {("test_cam", "main"): 0.0}
+        return maintainer
+
+    async def test_probe_audio_presence_reaches_move_segment(self):
+        for has_audio, audio_rate, audio_codec, video_codec in (
+            (True, 16000, "aac", "hevc"),
+            (True, 8000, "pcm_alaw", "h264"),
+            (False, None, None, "h264"),
+            (False, None, None, None),
+        ):
+            with self.subTest(
+                has_audio=has_audio,
+                audio_rate=audio_rate,
+                audio_codec=audio_codec,
+                video_codec=video_codec,
+            ):
+                maintainer = self._build_maintainer()
+                maintainer.move_segment = AsyncMock(return_value=None)
+
+                now = datetime.datetime.now(datetime.UTC)
+                start_time = now - datetime.timedelta(seconds=20)
+                cache_path = "/tmp/cache/test_cam@20260610143022+0000.mp4"
+                # a processed frame past the segment end marks it ready
+                maintainer.object_recordings_info["test_cam"] = [
+                    (now.timestamp(), [], [], [])
+                ]
+
+                probe = AsyncMock(
+                    return_value={
+                        "has_valid_video": True,
+                        "width": 1920,
+                        "height": 1080,
+                        "duration": 10.0,
+                        "has_audio": has_audio,
+                        "audio_rate": audio_rate,
+                        "audio_codec": audio_codec,
+                        "video_codec": video_codec,
+                    }
+                )
+                with (
+                    patch("frigate.record.maintainer.get_video_properties", probe),
+                    patch(
+                        "frigate.record.maintainer.get_keyframe_offsets",
+                        AsyncMock(return_value=[0, 2000]),
+                    ),
+                ):
+                    await maintainer.validate_and_move_segment(
+                        "test_cam",
+                        reviews=[],
+                        recording={
+                            "start_time": start_time,
+                            "cache_path": cache_path,
+                            "stream_type": "main",
+                        },
+                    )
+
+                maintainer.move_segment.assert_awaited_once()
+                call_args = maintainer.move_segment.await_args.args
+                self.assertEqual(call_args[7], has_audio)
+                self.assertEqual(call_args[8], audio_rate)
+                self.assertEqual(call_args[9], audio_codec)
+                self.assertEqual(call_args[11], [0, 2000])
+                self.assertEqual(call_args[10], video_codec)
+                # the probe result is cached alongside the end time so the
+                # cached path stays as informed as the probed path
+                self.assertEqual(maintainer.end_time_cache[cache_path][2], has_audio)
+                self.assertEqual(maintainer.end_time_cache[cache_path][3], audio_rate)
+                self.assertEqual(maintainer.end_time_cache[cache_path][4], audio_codec)
+                self.assertEqual(maintainer.end_time_cache[cache_path][5], video_codec)
+
+    async def test_move_segment_insert_includes_has_audio(self):
+        for has_audio, audio_rate, audio_codec, video_codec in (
+            (True, 16000, "aac", "hevc"),
+            (False, None, None, None),
+        ):
+            with self.subTest(
+                has_audio=has_audio,
+                audio_rate=audio_rate,
+                audio_codec=audio_codec,
+                video_codec=video_codec,
+            ):
+                maintainer = self._build_maintainer()
+                maintainer.config.ffmpeg.ffmpeg_path = "ffmpeg"
+
+                start_time = datetime.datetime.now(datetime.UTC)
+                end_time = start_time + datetime.timedelta(seconds=10)
+
+                proc = MagicMock()
+                proc.returncode = 0
+                proc.wait = AsyncMock(return_value=0)
+
+                with tempfile.TemporaryDirectory() as tmpdir:
+                    cache_path = os.path.join(
+                        tmpdir, "test_cam@20260610143022+0000.mp4"
+                    )
+                    with open(cache_path, "wb") as f:
+                        f.write(b"\x00" * 16)
+
+                    with (
+                        patch(
+                            "frigate.record.maintainer.RECORD_DIR",
+                            os.path.join(tmpdir, "recordings"),
+                        ),
+                        patch(
+                            "frigate.record.maintainer.asyncio.create_subprocess_exec",
+                            AsyncMock(return_value=proc),
+                        ),
+                    ):
+                        result = await maintainer.move_segment(
+                            "test_cam",
+                            "main",
+                            start_time,
+                            end_time,
+                            10.0,
+                            cache_path,
+                            SegmentInfo(0, 0, 0, 0),
+                            has_audio,
+                            audio_rate,
+                            audio_codec,
+                            video_codec,
+                        )
+
+                self.assertIsNotNone(result)
+                self.assertEqual(result[Recordings.has_audio.name], has_audio)
+                self.assertEqual(result[Recordings.audio_rate.name], audio_rate)
+                self.assertEqual(result[Recordings.audio_codec.name], audio_codec)
+                self.assertEqual(result[Recordings.video_codec.name], video_codec)
+
+
+class TestSegmentStartChaining(unittest.IsolatedAsyncioTestCase):
+    """Contiguous segments must chain start times across filename truncation.
+
+    A contiguous segment's parsed start lands up to 1s before the previous
+    segment's fractional end, and must snap to it without ever snapping
+    across a genuine gap.
+    """
+
+    T0 = datetime.datetime(2026, 6, 10, 14, 30, 22, tzinfo=datetime.UTC).timestamp()
+
+    async def test_contiguous_segment_snaps_to_previous_end(self):
+        maintainer = _build_chaining_maintainer(self.T0)
+
+        # segment A named at a whole second with a fractional duration
+        await _validate_segment(maintainer, self.T0, 0, 10.4)
+        # segment B's filename truncates its true start (T0 + 10.4) to T0 + 10
+        await _validate_segment(maintainer, self.T0, 10, 10.4)
+
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 2)
+        self.assertEqual(calls[0].args[2].timestamp(), self.T0)
+        self.assertAlmostEqual(calls[0].args[3].timestamp(), self.T0 + 10.4, places=3)
+        self.assertAlmostEqual(calls[1].args[2].timestamp(), self.T0 + 10.4, places=3)
+        self.assertAlmostEqual(calls[1].args[3].timestamp(), self.T0 + 20.8, places=3)
+
+    async def test_genuine_gap_is_not_snapped(self):
+        maintainer = _build_chaining_maintainer(self.T0)
+
+        await _validate_segment(maintainer, self.T0, 0, 10.4)
+        # a segment starting well after the previous end is a genuine gap
+        await _validate_segment(maintainer, self.T0, 30, 10.4)
+
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 2)
+        self.assertEqual(calls[1].args[2].timestamp(), self.T0 + 30)
+        self.assertAlmostEqual(calls[1].args[3].timestamp(), self.T0 + 40.4, places=3)
+
+    async def test_difference_over_tolerance_is_not_snapped(self):
+        # a last end far ahead of the parsed start (dual recorders or
+        # cache-pressure deletions) must never pull the start forward
+        maintainer = _build_chaining_maintainer(self.T0)
+        maintainer.last_segment_end = {("test_cam", "main"): self.T0 + 5.0}
+
+        await _validate_segment(maintainer, self.T0, 0, 10.4)
+
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(calls[0].args[2].timestamp(), self.T0)
+
+    async def test_start_after_last_end_within_tolerance_is_not_snapped(self):
+        maintainer = _build_chaining_maintainer(self.T0)
+
+        await _validate_segment(maintainer, self.T0, 0, 10.4)
+        # parsed start T0 + 11 is after the last end (T0 + 10.4): a real
+        # sub-second gap, never snapped backwards
+        await _validate_segment(maintainer, self.T0, 11, 10.4)
+
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 2)
+        self.assertEqual(calls[1].args[2].timestamp(), self.T0 + 11)
+
+    async def test_chain_survives_retention_discarded_segment(self):
+        # motion retention: A and C overlap motion frames, B has none and is
+        # discarded, but capture continued through B so C chains to B's end
+        maintainer = _build_chaining_maintainer(self.T0, retention="motion")
+        maintainer.object_recordings_info["test_cam"] = [
+            (self.T0 + 5, [], [(0, 0, 10, 10)], []),
+            (self.T0 + 25, [], [(0, 0, 10, 10)], []),
+            (self.T0 + 1000, [], [], []),
+        ]
+
+        await _validate_segment(maintainer, self.T0, 0, 10.4)
+        await _validate_segment(maintainer, self.T0, 10, 10.4)
+        await _validate_segment(maintainer, self.T0, 20, 10.4)
+
+        calls = maintainer.move_segment.await_args_list
+        # B was discarded by motion retention, only A and C moved
+        self.assertEqual(len(calls), 2)
+        maintainer.drop_segment.assert_called_once_with(
+            "/tmp/cache/test_cam@chain10.mp4"
+        )
+        # C snaps to B's end (T0 + 20.8), not A's end (T0 + 10.4)
+        self.assertAlmostEqual(calls[1].args[2].timestamp(), self.T0 + 20.8, places=3)
+        self.assertAlmostEqual(calls[1].args[3].timestamp(), self.T0 + 31.2, places=3)
+
+
+class TestSegmentStartMtimeAnchoring(unittest.IsolatedAsyncioTestCase):
+    """Segment starts must anchor to the cache file's close time.
+
+    mtime is the wall clock when ffmpeg rolled the segment, so mtime minus
+    the probed duration restores the fractional start the filename floored
+    away. Contiguous segments still chain within probe jitter.
+    """
+
+    T0 = datetime.datetime(2026, 8, 7, 9, 15, 42, tzinfo=datetime.UTC).timestamp()
+
+    async def test_mtime_restores_fractional_start(self):
+        maintainer = _build_chaining_maintainer(self.T0)
+
+        # true start T0 + 0.437; the filename floored it to T0
+        await _validate_segment(
+            maintainer, self.T0, 0, 10.0, mtime=self.T0 + 0.437 + 10.0
+        )
+
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 1)
+        self.assertAlmostEqual(calls[0].args[2].timestamp(), self.T0 + 0.437, places=3)
+        self.assertAlmostEqual(calls[0].args[3].timestamp(), self.T0 + 10.437, places=3)
+
+    async def test_chain_wins_within_probe_jitter(self):
+        maintainer = _build_chaining_maintainer(self.T0)
+
+        await _validate_segment(
+            maintainer, self.T0, 0, 10.0, mtime=self.T0 + 0.437 + 10.0
+        )
+        # B measures T0 + 10.420, a 17ms disagreement with A's chained end
+        # (T0 + 10.437): the chain wins so the rows stay exactly adjacent
+        await _validate_segment(
+            maintainer, self.T0, 10, 10.0, mtime=self.T0 + 10.420 + 10.0
+        )
+
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 2)
+        self.assertAlmostEqual(calls[1].args[2].timestamp(), self.T0 + 10.437, places=3)
+        self.assertAlmostEqual(calls[1].args[3].timestamp(), self.T0 + 20.437, places=3)
+
+    async def test_chain_reanchors_when_drifted(self):
+        maintainer = _build_chaining_maintainer(self.T0)
+        # accumulated probe error left the chain 0.7s past the measured start
+        maintainer.last_segment_end = {("test_cam", "main"): self.T0 + 0.9}
+
+        await _validate_segment(
+            maintainer, self.T0, 0, 10.0, mtime=self.T0 + 0.2 + 10.0
+        )
+
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 1)
+        self.assertAlmostEqual(calls[0].args[2].timestamp(), self.T0 + 0.2, places=3)
+
+    async def test_implausible_mtime_falls_back_to_filename_chain(self):
+        maintainer = _build_chaining_maintainer(self.T0)
+        maintainer.last_segment_end = {("test_cam", "main"): self.T0 + 0.4}
+
+        # a stalled stream: media (8s) is shorter than the wall span to the
+        # close time (9.5s), so mtime - duration lands outside the window
+        await _validate_segment(maintainer, self.T0, 0, 8.0, mtime=self.T0 + 9.5)
+
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 1)
+        self.assertAlmostEqual(calls[0].args[2].timestamp(), self.T0 + 0.4, places=3)
+
+
+class TestSegmentChainSeeding(unittest.IsolatedAsyncioTestCase):
+    """Chain state must lazily seed from the DB so chains survive restarts."""
+
+    T0 = datetime.datetime(2026, 6, 10, 14, 30, 22, tzinfo=datetime.UTC).timestamp()
+
+    def setUp(self):
+        self.db = SqliteExtDatabase(":memory:")
+        self.db.bind([Recordings])
+        self.db.create_tables([Recordings])
+
+    def tearDown(self):
+        self.db.close()
+
+    async def test_seeds_chain_from_db_once(self):
+        maintainer = _build_chaining_maintainer(self.T0)
+        # empty chain state forces the lazy DB seed on first encounter
+        maintainer.last_segment_end = {}
+
+        Recordings.create(
+            id="seed-row",
+            camera="test_cam",
+            path="/recordings/seed.mp4",
+            start_time=self.T0 - 10,
+            end_time=self.T0 + 0.35,
+            duration=10.35,
+            stream_type="main",
+        )
+
+        with patch.object(Recordings, "select", wraps=Recordings.select) as select_spy:
+            await _validate_segment(maintainer, self.T0, 0, 10.4)
+            await _validate_segment(maintainer, self.T0, 10, 10.4)
+
+        # the seed query runs once; the second segment uses in-memory state
+        self.assertEqual(select_spy.call_count, 1)
+        calls = maintainer.move_segment.await_args_list
+        self.assertEqual(len(calls), 2)
+        # first segment snaps to the stored fractional end_time
+        self.assertAlmostEqual(calls[0].args[2].timestamp(), self.T0 + 0.35, places=3)
+        self.assertAlmostEqual(calls[0].args[3].timestamp(), self.T0 + 10.75, places=3)
+        # second segment chains off the first's in-memory end
+        self.assertAlmostEqual(calls[1].args[2].timestamp(), self.T0 + 10.75, places=3)

frigate/test/test_recording_coverage.py

@@ -0,0 +1,376 @@
+"""Tests for the unified recording coverage resolver."""
+
+import asyncio
+import json
+import unittest
+from types import SimpleNamespace
+
+from playhouse.sqlite_ext import SqliteExtDatabase
+
+from frigate.api.media import _vod_response
+from frigate.const import MAX_SEGMENT_DURATION
+from frigate.models import Recordings
+from frigate.util.recording_coverage import (
+    _rows_query,
+    coverage_spans,
+    plan_clip,
+    realized_timeline,
+    resolve_coverage,
+    stream_media_summary,
+)
+
+
+class CoverageDbTestCase(unittest.TestCase):
+    def setUp(self):
+        # in-memory database keeps these tests isolated from the shared
+        # on-disk test.db used by the http api tests
+        self.db = SqliteExtDatabase(":memory:")
+        models = [Recordings]
+        self.db.bind(models)
+        self.db.create_tables(models)
+
+    def tearDown(self):
+        self.db.close()
+
+    def _insert(
+        self,
+        id,
+        start,
+        end,
+        stream_type,
+        camera="front_door",
+        video_codec=None,
+        audio_rate=None,
+        audio_codec=None,
+        has_audio=None,
+        segment_size=0,
+        keyframes=None,
+    ):
+        Recordings.create(
+            id=id,
+            camera=camera,
+            path=f"/tmp/{id}.mp4",
+            start_time=start,
+            end_time=end,
+            duration=end - start,
+            stream_type=stream_type,
+            video_codec=video_codec,
+            audio_rate=audio_rate,
+            audio_codec=audio_codec,
+            has_audio=has_audio,
+            segment_size=segment_size,
+            keyframes=keyframes,
+        )
+
+
+class TestRecordingCoverage(CoverageDbTestCase):
+    def test_both_streams_offset_boundaries(self):
+        # main: [1000,1010) [1010,1020)   sub: [1003,1013) [1013,1023)
+        self._insert("m1", 1000.0, 1010.0, "main")
+        self._insert("m2", 1010.0, 1020.0, "main")
+        self._insert("s1", 1003.0, 1013.0, "sub")
+        self._insert("s2", 1013.0, 1023.0, "sub")
+        intervals = resolve_coverage("front_door", 1000.0, 1020.0)
+        # boundaries: 1000,1003,1010,1013,1020
+        assert [round(i.start_time) for i in intervals] == [1000, 1003, 1010, 1013]
+        assert intervals[0].main is not None and intervals[0].sub is None
+        assert intervals[1].main is not None and intervals[1].sub is not None
+
+    def test_sub_only_when_main_expired(self):
+        self._insert("s1", 1000.0, 1010.0, "sub")
+        intervals = resolve_coverage("front_door", 1000.0, 1010.0)
+        assert len(intervals) == 1
+        assert intervals[0].main is None and intervals[0].sub is not None
+
+    def test_gap_when_neither_exists(self):
+        self._insert("m1", 1000.0, 1010.0, "main")
+        self._insert("m2", 1030.0, 1040.0, "main")
+        intervals = resolve_coverage("front_door", 1000.0, 1040.0)
+        assert len(intervals) == 2  # the [1010,1030) gap produces no interval
+
+    def test_spans_merge_same_availability(self):
+        self._insert("m1", 1000.0, 1010.0, "main")
+        self._insert("m2", 1010.0, 1020.0, "main")
+        spans = coverage_spans(resolve_coverage("front_door", 1000.0, 1020.0))
+        assert spans == [
+            {"start_time": 1000.0, "end_time": 1020.0, "streams": ["main"]}
+        ]
+
+    def test_requested_range_clamps_intervals(self):
+        # query range partially overlaps the rows; the first and last
+        # intervals must be clamped to the requested [after, before]
+        self._insert("m1", 1000.0, 1010.0, "main")
+        self._insert("m2", 1010.0, 1020.0, "main")
+        intervals = resolve_coverage("front_door", 1005.0, 1015.0)
+        assert intervals[0].start_time == 1005.0
+        assert intervals[-1].end_time == 1015.0
+        spans = coverage_spans(intervals)
+        assert spans == [
+            {"start_time": 1005.0, "end_time": 1015.0, "streams": ["main"]}
+        ]
+
+    def test_stream_media_summary_newest_known_wins(self):
+        # the newer main row's NULL codecs must not mask the older row's
+        # known codecs, while its known audio fields take precedence
+        self._insert(
+            "m1",
+            1000.0,
+            1010.0,
+            "main",
+            video_codec="hevc",
+            audio_rate=16000,
+            audio_codec="aac",
+        )
+        self._insert("m2", 1010.0, 1020.0, "main", audio_rate=8000, has_audio=True)
+        self._insert("s1", 1000.0, 1010.0, "sub", has_audio=False)
+        summary = stream_media_summary(resolve_coverage("front_door", 1000.0, 1020.0))
+        assert summary == {
+            "main": {
+                "video_codec": "hevc",
+                "audio_rate": 8000,
+                "audio_codec": "aac",
+                "has_audio": True,
+                "bitrate": None,
+            },
+            "sub": {
+                "video_codec": None,
+                "audio_rate": None,
+                "audio_codec": None,
+                "has_audio": False,
+                "bitrate": None,
+            },
+        }
+
+    def test_stream_media_summary_omits_absent_stream(self):
+        self._insert("m1", 1000.0, 1010.0, "main", video_codec="h264")
+        summary = stream_media_summary(resolve_coverage("front_door", 1000.0, 1010.0))
+        assert list(summary.keys()) == ["main"]
+        assert stream_media_summary([]) == {}
+
+    def test_stream_media_summary_bitrate_weighted_by_duration(self):
+        # main: 10 MiB over 10s + 30 MiB over 20s -> 40 MiB / 30s
+        self._insert("m1", 1000.0, 1010.0, "main", segment_size=10)
+        self._insert("m2", 1010.0, 1030.0, "main", segment_size=30)
+        # sub rows without a stored size (legacy default 0) report None
+        self._insert("s1", 1000.0, 1030.0, "sub")
+        summary = stream_media_summary(resolve_coverage("front_door", 1000.0, 1030.0))
+        expected = int(40 * 1024 * 1024 * 8 / 30)
+        assert summary["main"]["bitrate"] == expected
+        assert summary["sub"]["bitrate"] is None
+
+    def test_stream_media_summary_bitrate_skips_zero_size_rows(self):
+        # the zero-size glitch row contributes neither bytes nor seconds
+        self._insert("m1", 1000.0, 1010.0, "main", segment_size=5)
+        self._insert("m2", 1010.0, 1020.0, "main", segment_size=0)
+        summary = stream_media_summary(resolve_coverage("front_door", 1000.0, 1020.0))
+        expected = int(5 * 1024 * 1024 * 8 / 10)
+        assert summary["main"]["bitrate"] == expected
+
+    def test_other_camera_rows_excluded(self):
+        self._insert("m1", 1000.0, 1010.0, "main")
+        self._insert("o1", 1000.0, 1010.0, "main", camera="back_yard")
+        self._insert("o2", 1000.0, 1010.0, "sub", camera="back_yard")
+        intervals = resolve_coverage("front_door", 1000.0, 1010.0)
+        assert len(intervals) == 1
+        assert intervals[0].main is not None and intervals[0].sub is None
+        assert resolve_coverage("side_gate", 1000.0, 1010.0) == []
+
+    def test_realized_timeline_snap_lead_in(self):
+        """A mid-file resume's back-snap lead-in appears in the realized duration.
+
+        Sub resumes at 1010 with a 7000ms inpoint; the stored keyframe
+        index snaps back to 6000ms, so the clip serves 1000ms of pre-span
+        content on top of the 3000ms span.
+        """
+        self._insert("m1", 1000.0, 1010.0, "main")
+        self._insert("s1", 1003.0, 1013.0, "sub", keyframes=[0, 2000, 4000, 6000, 8000])
+        timeline = realized_timeline(
+            resolve_coverage("front_door", 1000.0, 1013.0), None
+        )
+        assert timeline == [
+            {"start_time": 1000.0, "end_time": 1010.0, "duration": 10000},
+            {"start_time": 1010.0, "end_time": 1013.0, "duration": 4000},
+        ]
+
+    def test_realized_timeline_no_keyframe_index_serves_whole_file(self):
+        """A row without a stored keyframe index serves the whole file.
+
+        NULL keyframes mean the record-time probe failed, so a mid-file
+        entry cannot be snapped to a decodable frame.
+        """
+        self._insert("m1", 1000.0, 1010.0, "main")
+        self._insert("s1", 1003.0, 1013.0, "sub")
+        timeline = realized_timeline(
+            resolve_coverage("front_door", 1000.0, 1013.0), None
+        )
+        # the resume clip serves all 10000ms of the sub file for a 3000ms span
+        assert timeline[1] == {
+            "start_time": 1010.0,
+            "end_time": 1013.0,
+            "duration": 10000,
+        }
+
+    def test_realized_timeline_pinned_stream_no_mid_range_lead_in(self):
+        """A pinned stream's spans start at its own file starts: no lead-in."""
+        self._insert("s1", 1000.0, 1010.0, "sub", keyframes=[0, 5000])
+        self._insert("s2", 1010.0, 1020.0, "sub", keyframes=[0, 5000])
+        timeline = realized_timeline(
+            resolve_coverage("front_door", 1000.0, 1020.0), "sub"
+        )
+        assert [t["duration"] for t in timeline] == [10000, 10000]
+
+    def test_rows_query_scan_is_bounded_below(self):
+        """The row query must give SQLite a lower bound on start_time.
+
+        Without one the best index range is (camera=? AND start_time<?),
+        which walks the camera's entire history on every coverage call:
+        ~20s on a cold page cache, blocking the API event loop.
+        """
+        # the index the planner picks in production (migration 020)
+        self.db.execute_sql(
+            "CREATE INDEX recordings_api_recordings_summary ON recordings "
+            '("camera", "start_time" DESC, "duration", "motion", "objects")'
+        )
+        sql, params = _rows_query("front_door", 2000.0, 3000.0, "main").sql()
+        plan = " ".join(
+            row[-1] for row in self.db.execute_sql("EXPLAIN QUERY PLAN " + sql, params)
+        )
+        assert "start_time>?" in plan and "start_time<?" in plan, plan
+
+    def test_longest_segment_spanning_window_start_included(self):
+        # a maximum-length segment overlapping `after` sits right at the
+        # start_time lower bound the query is allowed to apply
+        self._insert("m1", 1000.0, 1000.0 + MAX_SEGMENT_DURATION - 0.5, "main")
+        intervals = resolve_coverage("front_door", 1599.0, 1700.0)
+        assert len(intervals) == 1
+        assert intervals[0].main is not None
+
+    def test_plan_clip_skips_too_short(self):
+        """A clip left with under 100ms of media is skipped (duration 0 in timelines)."""
+        row = SimpleNamespace(
+            path="/tmp/x.mp4",
+            start_time=1000.0,
+            end_time=1000.15,
+            duration=0.15,
+            keyframes=[0, 100],
+        )
+        plan = plan_clip(row, 1000.1, 1000.15)
+        assert plan.skipped
+        assert plan.duration_ms == 0
+
+
+class TestVodManifestPolicy(CoverageDbTestCase):
+    """Discontinuity policy of the vod mapping builder."""
+
+    def _mapping(self, start, end, stream=None):
+        response = asyncio.run(
+            _vod_response("front_door", start, end, stream_preference=stream)
+        )
+        return json.loads(response.body)
+
+    def _insert_stream(self, prefix, stream_type, spans):
+        for idx, (start, end) in enumerate(spans):
+            self._insert(
+                f"{prefix}{idx}",
+                start,
+                end,
+                stream_type,
+                video_codec="h264",
+                audio_codec="aac",
+                audio_rate=16000,
+                has_audio=True,
+            )
+
+    def test_cross_stream_handoff_forces_discontinuity(self):
+        # codec and audio params match on both streams, so only the stream
+        # mix can force per-clip init segments here
+        self._insert_stream("m", "main", [(1000.0, 1010.0)])
+        self._insert_stream("s", "sub", [(1000.0, 1010.0), (1010.0, 1020.0)])
+        mapping = self._mapping(1000.0, 1020.0)
+        assert mapping["discontinuity"] is True
+        assert mapping["initialClipIndex"] == 1
+        assert len(mapping["sequences"][0]["clips"]) == 2
+
+    def test_single_stream_range_stays_consistent(self):
+        self._insert_stream("s", "sub", [(1000.0, 1010.0), (1010.0, 1020.0)])
+        mapping = self._mapping(1000.0, 1020.0)
+        assert mapping["discontinuity"] is False
+        assert "initialClipIndex" not in mapping
+
+    def test_pinned_stream_over_mixed_coverage_stays_consistent(self):
+        self._insert_stream("m", "main", [(1000.0, 1010.0), (1010.0, 1020.0)])
+        self._insert_stream("s", "sub", [(1000.0, 1010.0), (1010.0, 1020.0)])
+        mapping = self._mapping(1000.0, 1020.0, stream="sub")
+        assert mapping["discontinuity"] is False
+        assert "initialClipIndex" not in mapping
+
+
+class TestClipKeyFrames(unittest.TestCase):
+    """Keyframe data emitted for nginx-vod segmentation."""
+
+    def _row(self, keyframes):
+        return SimpleNamespace(
+            path="/tmp/kf.mp4",
+            start_time=1000.0,
+            end_time=1010.0,
+            duration=10.0,
+            keyframes=keyframes,
+        )
+
+    def test_whole_file_clip_emits_keyframe_gaps(self):
+        keyframes = [0, 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000]
+        plan = plan_clip(self._row(keyframes), 1000.0, 1010.0)
+        assert plan.clip_from_ms is None
+        assert plan.key_frame_durations == [1000] * 9
+        assert plan.first_key_frame_offset_ms == 0
+
+    def test_mid_file_clip_offsets_are_clip_relative(self):
+        # start 3.5s in: clipFrom snaps back to the 3000ms keyframe, so
+        # the emitted offsets must be relative to that snapped start
+        keyframes = [0, 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000]
+        plan = plan_clip(self._row(keyframes), 1003.5, 1010.0)
+        assert plan.clip_from_ms == 3000
+        assert plan.duration_ms == 7000
+        assert plan.key_frame_durations == [1000] * 6
+        assert plan.first_key_frame_offset_ms == 0
+
+    def test_no_index_reports_none(self):
+        plan = plan_clip(self._row(None), 1000.0, 1010.0)
+        assert plan.key_frame_durations is None
+
+    def test_single_keyframe_in_range_reports_none(self):
+        # one cut point cannot split anything; the manifest falls back
+        # to a whole-clip declaration
+        plan = plan_clip(self._row([0]), 1000.0, 1010.0)
+        assert plan.key_frame_durations is None
+
+    def test_keyframe_on_clip_end_excluded(self):
+        # a keyframe landing exactly on the clip end would only declare
+        # a zero-length tail segment
+        plan = plan_clip(self._row([0, 5000, 10000]), 1000.0, 1010.0)
+        assert plan.key_frame_durations == [5000]
+
+
+class TestVodManifestKeyFrames(CoverageDbTestCase):
+    """Mapping emission of real vs placeholder keyFrameDurations."""
+
+    def _clips(self, start, end):
+        response = asyncio.run(_vod_response("front_door", start, end))
+        return json.loads(response.body)["sequences"][0]["clips"]
+
+    def test_indexed_row_emits_real_gaps(self):
+        self._insert(
+            "m1",
+            1000.0,
+            1010.0,
+            "main",
+            keyframes=[0, 2000, 4000, 6000, 8000],
+        )
+        clips = self._clips(1000.0, 1010.0)
+        assert clips[0]["keyFrameDurations"] == [2000, 2000, 2000, 2000]
+        assert "firstKeyFrameOffset" not in clips[0]
+
+    def test_unindexed_row_keeps_whole_clip_placeholder(self):
+        self._insert("m1", 1000.0, 1010.0, "main")
+        clips = self._clips(1000.0, 1010.0)
+        assert clips[0]["keyFrameDurations"] == [10000]

frigate/test/test_storage.py

@@ -11,8 +11,9 @@ from playhouse.sqlite_ext import SqliteExtDatabase
 from playhouse.sqliteq import SqliteQueueDatabase
 
 from frigate.config import FrigateConfig
+from frigate.const import STREAM_TYPE_MAIN, STREAM_TYPE_SUB
 from frigate.models import Event, Recordings
-from frigate.storage import StorageMaintainer
+from frigate.storage import MAX_CALCULATED_BANDWIDTH, StorageMaintainer
 from frigate.test.const import TEST_DB, TEST_DB_CLEANUPS
 
 
@@ -114,8 +115,16 @@ class TestHttp(unittest.TestCase):
         )
         storage.calculate_camera_bandwidth()
         assert storage.camera_storage_stats == {
-            "front_door": {"bandwidth": 1440, "needs_refresh": True},
-            "back_door": {"bandwidth": 2880, "needs_refresh": True},
+            "front_door": {
+                "bandwidth": 1440,
+                "bandwidth_by_stream": {STREAM_TYPE_MAIN: 1440},
+                "needs_refresh": True,
+            },
+            "back_door": {
+                "bandwidth": 2880,
+                "bandwidth_by_stream": {STREAM_TYPE_MAIN: 2880},
+                "needs_refresh": True,
+            },
         }
 
     def test_segment_calculations_with_zero_segments(self):
@@ -136,9 +145,198 @@ class TestHttp(unittest.TestCase):
         )
         storage.calculate_camera_bandwidth()
         assert storage.camera_storage_stats == {
-            "front_door": {"bandwidth": 0, "needs_refresh": True},
+            "front_door": {
+                "bandwidth": 0,
+                "bandwidth_by_stream": {},
+                "needs_refresh": True,
+            },
         }
 
+    def test_segment_calculations_with_recent_zero_segments(self):
+        """A run of recent zero-size segments must not zero out the bandwidth.
+
+        Older nonzero segments still describe the camera's real write rate.
+        """
+        config = FrigateConfig(**self.minimal_config)
+        storage = StorageMaintainer(config, MagicMock())
+
+        time_keep = datetime.datetime.now().timestamp()
+        for i in range(10):
+            _insert_mock_recording(
+                f"nonzero_{i}.frontdoor",
+                os.path.join(self.test_dir, f"nonzero_{i}.tmp"),
+                time_keep + i * 10,
+                time_keep + i * 10 + 10,
+                camera="front_door",
+                seg_size=4,
+                seg_dur=10,
+            )
+        for i in range(100):
+            _insert_mock_recording(
+                f"zero_{i}.frontdoor",
+                os.path.join(self.test_dir, f"zero_{i}.tmp"),
+                time_keep + 1000 + i * 10,
+                time_keep + 1000 + i * 10 + 10,
+                camera="front_door",
+                seg_size=0,
+                seg_dur=10,
+            )
+
+        storage.calculate_camera_bandwidth()
+        assert storage.camera_storage_stats == {
+            "front_door": {
+                "bandwidth": 1440,
+                "bandwidth_by_stream": {STREAM_TYPE_MAIN: 1440},
+                "needs_refresh": True,
+            },
+        }
+
+    def test_camera_usages_split_by_stream_type(self):
+        """Usage and bandwidth are reported per stream type."""
+        config = FrigateConfig(**self.minimal_config)
+        storage = StorageMaintainer(config, MagicMock())
+
+        time_keep = datetime.datetime.now().timestamp()
+        _insert_mock_recording(
+            "1234567.frontdoor",
+            os.path.join(self.test_dir, "main.tmp"),
+            time_keep,
+            time_keep + 10,
+            seg_size=20,
+            seg_dur=10,
+            stream_type=STREAM_TYPE_MAIN,
+        )
+        _insert_mock_recording(
+            "1234568.frontdoor",
+            os.path.join(self.test_dir, "sub.tmp"),
+            time_keep,
+            time_keep + 10,
+            seg_size=2,
+            seg_dur=10,
+            stream_type=STREAM_TYPE_SUB,
+        )
+
+        storage.calculate_camera_bandwidth()
+        usages = storage.calculate_camera_usages()
+
+        assert usages["front_door"]["usage"] == 22
+        assert usages["front_door"]["bandwidth"] == 7920
+        assert usages["front_door"]["streams"] == {
+            STREAM_TYPE_MAIN: {"usage": 20, "bandwidth": 7200},
+            STREAM_TYPE_SUB: {"usage": 2, "bandwidth": 720},
+        }
+
+    def test_camera_usages_omits_streams_without_segments(self):
+        """A camera with no sub segments reports no sub entry."""
+        config = FrigateConfig(**self.minimal_config)
+        storage = StorageMaintainer(config, MagicMock())
+
+        time_keep = datetime.datetime.now().timestamp()
+        _insert_mock_recording(
+            "1234567.frontdoor",
+            os.path.join(self.test_dir, "main.tmp"),
+            time_keep,
+            time_keep + 10,
+            seg_size=20,
+            seg_dur=10,
+        )
+
+        storage.calculate_camera_bandwidth()
+        usages = storage.calculate_camera_usages()
+
+        assert usages["front_door"]["usage"] == 20
+        assert usages["front_door"]["streams"] == {
+            STREAM_TYPE_MAIN: {"usage": 20, "bandwidth": 7200},
+        }
+
+    def test_camera_bandwidth_clamp_scales_stream_values(self):
+        """Clamping the total keeps the per stream values summing to it."""
+        config = FrigateConfig(**self.minimal_config)
+        storage = StorageMaintainer(config, MagicMock())
+
+        time_keep = datetime.datetime.now().timestamp()
+        _insert_mock_recording(
+            "1234567.frontdoor",
+            os.path.join(self.test_dir, "main.tmp"),
+            time_keep,
+            time_keep + 10,
+            seg_size=40,
+            seg_dur=10,
+            stream_type=STREAM_TYPE_MAIN,
+        )
+        _insert_mock_recording(
+            "1234568.frontdoor",
+            os.path.join(self.test_dir, "sub.tmp"),
+            time_keep,
+            time_keep + 10,
+            seg_size=4,
+            seg_dur=10,
+            stream_type=STREAM_TYPE_SUB,
+        )
+
+        storage.calculate_camera_bandwidth()
+        stats = storage.camera_storage_stats["front_door"]
+
+        assert stats["bandwidth"] == MAX_CALCULATED_BANDWIDTH
+        assert (
+            round(sum(stats["bandwidth_by_stream"].values()), 2)
+            == MAX_CALCULATED_BANDWIDTH
+        )
+
+    def test_stream_bandwidth_is_none_without_a_cached_sample(self):
+        """A stream that appears after the bandwidth cache freezes has no estimate.
+
+        Sub stream recording can be toggled on at runtime, so the cache can hold
+        a main-only sample while sub segments are already landing on disk.
+        Reporting 0 there would claim the sub stream costs nothing.
+        """
+        config = FrigateConfig(**self.minimal_config)
+        storage = StorageMaintainer(config, MagicMock())
+
+        time_keep = datetime.datetime.now().timestamp()
+        for i in range(60):
+            _insert_mock_recording(
+                f"main_{i}.frontdoor",
+                os.path.join(self.test_dir, f"main_{i}.tmp"),
+                time_keep + i * 10,
+                time_keep + i * 10 + 10,
+                seg_size=20,
+                seg_dur=10,
+            )
+
+        # 50 or more segments flips needs_refresh off, freezing the cache
+        storage.calculate_camera_bandwidth()
+        assert storage.camera_storage_stats["front_door"]["needs_refresh"] is False
+
+        for i in range(60):
+            _insert_mock_recording(
+                f"sub_{i}.frontdoor",
+                os.path.join(self.test_dir, f"sub_{i}.tmp"),
+                time_keep + 5000 + i * 10,
+                time_keep + 5000 + i * 10 + 10,
+                seg_size=2,
+                seg_dur=10,
+                stream_type=STREAM_TYPE_SUB,
+            )
+
+        storage.calculate_camera_bandwidth()
+        streams = storage.calculate_camera_usages()["front_door"]["streams"]
+
+        assert streams[STREAM_TYPE_SUB]["usage"] == 120
+        assert streams[STREAM_TYPE_SUB]["bandwidth"] is None
+        assert streams[STREAM_TYPE_MAIN]["bandwidth"] == 7200
+
+    def test_camera_usages_with_no_recordings(self):
+        """A camera with no segments reports zero usage and no streams."""
+        config = FrigateConfig(**self.minimal_config)
+        storage = StorageMaintainer(config, MagicMock())
+
+        storage.calculate_camera_bandwidth()
+        usages = storage.calculate_camera_usages()
+
+        assert usages["front_door"]["usage"] == 0
+        assert usages["front_door"]["streams"] == {}
+
     def test_storage_cleanup(self):
         """Ensure that all recordings are cleaned up when necessary."""
         config = FrigateConfig(**self.minimal_config)
@@ -297,6 +495,7 @@ def _insert_mock_recording(
     camera="front_door",
     seg_size=8,
     seg_dur=10,
+    stream_type=STREAM_TYPE_MAIN,
 ) -> Event:
     """Inserts a basic recording model with a given id."""
     # we must open the file so storage maintainer will delete it
@@ -313,4 +512,5 @@ def _insert_mock_recording(
         motion=True,
         objects=True,
         segment_size=seg_size,
+        stream_type=stream_type,
     ).execute()

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/audio.py

@@ -6,12 +6,33 @@ import subprocess as sp
 
 from pathvalidate import sanitize_filename
 
-from frigate.const import CACHE_DIR
+from frigate.const import CACHE_DIR, STREAM_TYPE_MAIN, STREAM_TYPE_SUB
 from frigate.models import Recordings
 
 logger = logging.getLogger(__name__)
 
 
+def _get_recordings_for_range(
+    camera_name: str, start_ts: float, end_ts: float, stream_type: str
+) -> list[Recordings]:
+    """Fetch one stream type's recording rows overlapping the requested range."""
+    return list(
+        Recordings.select(
+            Recordings.path,
+            Recordings.start_time,
+            Recordings.end_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))
+        )
+        .where(Recordings.camera == camera_name)
+        .where(Recordings.stream_type == stream_type)
+        .order_by(Recordings.start_time.asc())
+    )
+
+
 def get_audio_from_recording(
     ffmpeg,
     camera_name: str,
@@ -31,22 +52,17 @@ def get_audio_from_recording(
     Returns:
         Bytes of WAV audio data or None if extraction failed
     """
-    # Fetch all relevant recording segments
-    recordings = (
-        Recordings.select(
-            Recordings.path,
-            Recordings.start_time,
-            Recordings.end_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))
-        )
-        .where(Recordings.camera == camera_name)
-        .order_by(Recordings.start_time.asc())
+    # Fetch all relevant recording segments; never mix streams in one
+    # concat, so prefer main and fall back to sub for expired-main history
+    recordings = _get_recordings_for_range(
+        camera_name, start_ts, end_ts, STREAM_TYPE_MAIN
     )
 
+    if not recordings:
+        recordings = _get_recordings_for_range(
+            camera_name, start_ts, end_ts, STREAM_TYPE_SUB
+        )
+
     if not recordings:
         logger.debug(
             f"No recordings found for {camera_name} between {start_ts} and {end_ts}"

frigate/util/classification.py

@@ -18,6 +18,7 @@ from frigate.const import (
     CLIPS_DIR,
     MODEL_CACHE_DIR,
     PROCESS_PRIORITY_LOW,
+    STREAM_TYPE_MAIN,
     UPDATE_MODEL_STATE,
 )
 from frigate.log import redirect_output_to_logger, suppress_stderr_during
@@ -555,6 +556,7 @@ def _extract_keyframes(
                     (timestamp >= Recordings.start_time)
                     & (timestamp <= Recordings.end_time)
                     & (Recordings.camera == camera)
+                    & (Recordings.stream_type == STREAM_TYPE_MAIN)
                 )
                 .order_by(Recordings.start_time.desc())
                 .limit(1)

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,28 @@ def _convert_legacy_mask_to_dict(
     return result
 
 
+# the 0.18 scalar Birdseye modes, mapped to their activity mode names
+_LEGACY_BIRDSEYE_MODES = {
+    "continuous": "continuous",
+    "motion": "motion",
+    "objects": "all_objects",
+}
+
+
+def _migrate_birdseye_mode(birdseye: dict[str, Any] | None) -> None:
+    """Convert a scalar Birdseye mode to an activity mode list."""
+    if not birdseye or not isinstance(birdseye.get("mode"), str):
+        return
+
+    legacy_mode = birdseye["mode"]
+
+    if legacy_mode not in _LEGACY_BIRDSEYE_MODES:
+        return
+
+    del birdseye["mode"]
+    birdseye["modes"] = [_LEGACY_BIRDSEYE_MODES[legacy_mode]]
+
+
 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 +688,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/media.py

@@ -1,10 +1,11 @@
 """Recordings Utilities."""
 
+import asyncio
+import contextlib
 import datetime
 import errno
 import logging
 import os
-import subprocess as sp
 from collections.abc import Iterable
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -879,38 +880,43 @@ def sync_all_media(
     return results
 
 
-def get_keyframe_before(path: str, offset_ms: int) -> int | None:
-    """Get the timestamp (ms) of the last keyframe at or before offset_ms.
+async def get_keyframe_offsets(path: str) -> list[int] | None:
+    """Get every video keyframe offset (ms from segment start) in an mp4.
 
-    Uses ffprobe packet index to read keyframe positions from the mp4 file.
-    Returns None if ffprobe fails or no keyframe is found before the offset.
+    Runs at record time so playback never needs to probe. Returns None if
+    ffprobe fails, so the caller stores NULL and playback falls back to
+    serving whole files.
     """
+    proc = None
     try:
-        result = sp.run(
-            [
-                FFPROBE_PATH,
-                "-select_streams",
-                "v:0",
-                "-show_entries",
-                "packet=pts_time,flags",
-                "-of",
-                "csv=p=0",
-                "-loglevel",
-                "error",
-                path,
-            ],
-            capture_output=True,
-            timeout=5,
+        proc = await asyncio.create_subprocess_exec(
+            FFPROBE_PATH,
+            "-select_streams",
+            "v:0",
+            "-show_entries",
+            "packet=pts_time,flags",
+            "-of",
+            "csv=p=0",
+            "-loglevel",
+            "error",
+            path,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
         )
-    except (sp.TimeoutExpired, FileNotFoundError):
+        stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=5)
+    except (TimeoutError, FileNotFoundError):
+        if proc is not None and proc.returncode is None:
+            with contextlib.suppress(ProcessLookupError):
+                proc.kill()
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(proc.communicate(), timeout=2)
         return None
 
-    if result.returncode != 0:
+    if proc.returncode != 0:
         return None
 
-    offset_s = offset_ms / 1000.0
-    best_ms = None
-    for line in result.stdout.decode().strip().splitlines():
+    offsets: list[int] = []
+    for line in stdout.decode().strip().splitlines():
         parts = line.strip().split(",")
         if len(parts) != 2:
             continue
@@ -918,12 +924,8 @@ def get_keyframe_before(path: str, offset_ms: int) -> int | None:
         if "K" not in flags:
             continue
         try:
-            ts = float(ts_str)
+            offsets.append(int(float(ts_str) * 1000))
         except ValueError:
             continue
-        if ts <= offset_s:
-            best_ms = int(ts * 1000)
-        else:
-            break
 
-    return best_ms
+    return offsets

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/recording_coverage.py

@@ -0,0 +1,460 @@
+"""Merge main and sub stream recording rows into a unified coverage timeline."""
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from frigate.const import MAX_SEGMENT_DURATION, STREAM_TYPE_MAIN, STREAM_TYPE_SUB
+from frigate.models import Recordings
+
+logger = logging.getLogger(__name__)
+
+# intervals shorter than this are boundary artifacts, not playable content
+MIN_INTERVAL_S = 0.1
+
+
+@dataclass
+class CoverageInterval:
+    """A time span annotated with the recording row covering it per stream."""
+
+    start_time: float
+    end_time: float
+    main: Any | None
+    sub: Any | None
+
+
+def _rows_query(camera: str, after: float, before: float, stream_type: str) -> Any:
+    return (
+        Recordings.select(
+            Recordings.path,
+            Recordings.start_time,
+            Recordings.end_time,
+            Recordings.duration,
+            Recordings.has_audio,
+            Recordings.audio_rate,
+            Recordings.audio_codec,
+            Recordings.video_codec,
+            Recordings.segment_size,
+            Recordings.keyframes,
+        )
+        .where(
+            (Recordings.camera == camera)
+            & (Recordings.stream_type == stream_type)
+            & (Recordings.end_time > after)
+            & (Recordings.start_time < before)
+            & (Recordings.start_time > after - MAX_SEGMENT_DURATION)
+        )
+        .order_by(Recordings.start_time.asc())
+        .namedtuples()
+    )
+
+
+def _get_rows(camera: str, after: float, before: float, stream_type: str) -> list[Any]:
+    return list(_rows_query(camera, after, before, stream_type))
+
+
+def _covering(
+    rows: list[Any], idx: int, start: float, end: float
+) -> tuple[Any | None, int]:
+    """Find the row covering [start, end), advancing idx (rows are sorted, non-overlapping)."""
+    while idx < len(rows) and rows[idx].end_time <= start:
+        idx += 1
+    if idx < len(rows) and rows[idx].start_time <= start and rows[idx].end_time >= end:
+        return rows[idx], idx
+    return None, idx
+
+
+def resolve_coverage(
+    camera: str, after: float, before: float
+) -> list[CoverageInterval]:
+    """Resolve the unified coverage timeline for a camera and time range.
+
+    Returns intervals bounded by the union of both streams' segment edges,
+    clamped to [after, before]. Ranges covered by neither stream produce no
+    interval (a gap).
+    """
+    main_rows = _get_rows(camera, after, before, STREAM_TYPE_MAIN)
+    sub_rows = _get_rows(camera, after, before, STREAM_TYPE_SUB)
+
+    boundaries: set[float] = set()
+    for row in main_rows + sub_rows:
+        boundaries.add(max(row.start_time, after))
+        boundaries.add(min(row.end_time, before))
+
+    ordered = sorted(boundaries)
+    intervals: list[CoverageInterval] = []
+    main_idx = 0
+    sub_idx = 0
+
+    for i in range(len(ordered) - 1):
+        start, end = ordered[i], ordered[i + 1]
+
+        if end - start < MIN_INTERVAL_S:
+            continue
+
+        main_row, main_idx = _covering(main_rows, main_idx, start, end)
+        sub_row, sub_idx = _covering(sub_rows, sub_idx, start, end)
+
+        if main_row is None and sub_row is None:
+            continue
+
+        intervals.append(CoverageInterval(start, end, main_row, sub_row))
+
+    return intervals
+
+
+def known_video_codecs(intervals: list[CoverageInterval]) -> set[str]:
+    """Collect the known video codecs across all rows in a coverage window.
+
+    NULL codecs (legacy rows probed before the column existed) are
+    excluded, so uniformly-unknown data reports an empty set.
+    """
+    return {
+        row.video_codec
+        for interval in intervals
+        for row in (interval.main, interval.sub)
+        if row is not None and row.video_codec is not None
+    }
+
+
+def stream_media_summary(
+    intervals: list[CoverageInterval],
+) -> dict[str, dict[str, Any]]:
+    """Summarize the most recently known media details per stream.
+
+    Every field reports the newest non-NULL value across that stream's
+    rows, so an older row can still supply a value a legacy newer row
+    lacks. A stream with no rows is omitted entirely.
+    """
+    fields = ("video_codec", "audio_rate", "audio_codec", "has_audio")
+    summary: dict[str, dict[str, Any]] = {}
+
+    for stream_type in (STREAM_TYPE_MAIN, STREAM_TYPE_SUB):
+        # the same row can back many intervals, so dedupe by path
+        rows = {
+            row.path: row
+            for interval in intervals
+            if (row := getattr(interval, stream_type)) is not None
+        }
+
+        if not rows:
+            continue
+
+        newest_first = sorted(rows.values(), key=lambda r: r.start_time, reverse=True)
+        stream_summary: dict[str, Any] = {field: None for field in fields}
+
+        for field in fields:
+            for row in newest_first:
+                value = getattr(row, field)
+                if value is not None:
+                    stream_summary[field] = value
+                    break
+
+        # segment_size is stored in MiB; totalling bytes and seconds
+        # weights by duration, unlike averaging per-row ratios
+        total_bytes = 0.0
+        total_seconds = 0.0
+        for row in rows.values():
+            size = row.segment_size
+            if size is None or size <= 0 or row.duration is None or row.duration <= 0:
+                continue
+            total_bytes += size * 1024 * 1024
+            total_seconds += row.duration
+
+        stream_summary["bitrate"] = (
+            int(total_bytes * 8 / total_seconds) if total_seconds > 0 else None
+        )
+
+        summary[stream_type] = stream_summary
+
+    return summary
+
+
+def coverage_spans(intervals: list[CoverageInterval]) -> list[dict[str, Any]]:
+    """Collapse intervals into contiguous spans of identical stream availability."""
+    spans: list[dict[str, Any]] = []
+
+    for interval in intervals:
+        streams = [
+            t
+            for t, row in (
+                (STREAM_TYPE_MAIN, interval.main),
+                (STREAM_TYPE_SUB, interval.sub),
+            )
+            if row is not None
+        ]
+        if (
+            spans
+            and spans[-1]["end_time"] == interval.start_time
+            and spans[-1]["streams"] == streams
+        ):
+            spans[-1]["end_time"] = interval.end_time
+        else:
+            spans.append(
+                {
+                    "start_time": interval.start_time,
+                    "end_time": interval.end_time,
+                    "streams": streams,
+                }
+            )
+
+    return spans
+
+
+def stream_has_audio(intervals: list[CoverageInterval], main: bool) -> bool:
+    """Whether a stream is audio-bearing over a coverage window.
+
+    A stream counts as audio-bearing unless EVERY one of its rows reports
+    has_audio False; NULL (legacy or undetermined) counts as audio.
+    """
+    return any(
+        row is not None and row.has_audio is not False
+        for row in ((interval.main if main else interval.sub) for interval in intervals)
+    )
+
+
+def null_audio_glitches(
+    intervals: list[CoverageInterval], main_audio: bool, sub_audio: bool
+) -> list[CoverageInterval]:
+    """Treat video-only glitch rows on audio-bearing streams as no recording.
+
+    nginx-vod requires every clip in a sequence to carry the same track
+    count, so a truncated video-only segment (a backend restart can flush
+    a sub-second file before any audio packet landed) poisons every
+    manifest that includes it. Nulling the row turns the glitch into a
+    hole the span builder skips like any recording gap.
+    """
+    result: list[CoverageInterval] = []
+    for interval in intervals:
+        main = interval.main
+        sub = interval.sub
+        if main is not None and main_audio and main.has_audio is False:
+            main = None
+        if sub is not None and sub_audio and sub.has_audio is False:
+            sub = None
+        if main is None and sub is None:
+            continue
+        if main is interval.main and sub is interval.sub:
+            result.append(interval)
+        else:
+            result.append(
+                CoverageInterval(interval.start_time, interval.end_time, main, sub)
+            )
+    return result
+
+
+def build_spans(
+    intervals: list[CoverageInterval], stream: str | None
+) -> list[list[Any]]:
+    """Merge coverage intervals into single-sequence spans of one row each.
+
+    Each span is [row, start, end, is_main]; is_main lets the manifest
+    builder detect cross-stream hand-offs. A pinned stream serves only
+    its own rows; otherwise main is preferred and sub fills the gaps.
+    Intervals served by the same row merge on row identity alone, since
+    splitting a row mid-file would re-snap to a keyframe and repeat
+    content.
+    """
+    spans: list[list[Any]] = []
+    last_is_main: bool | None = None
+    for interval in intervals:
+        if stream == STREAM_TYPE_MAIN:
+            row, is_main = interval.main, True
+        elif stream == STREAM_TYPE_SUB:
+            row, is_main = interval.sub, False
+        elif interval.main is not None:
+            row, is_main = interval.main, True
+        else:
+            row, is_main = interval.sub, False
+        if row is None:
+            continue
+        if spans and spans[-1][0] == row:
+            spans[-1][2] = interval.end_time
+        else:
+            start = interval.start_time
+            # adjacent same-stream rows routinely overlap; trimming the
+            # previous span's end is free, where starting this span
+            # mid-file would cost a clipFrom keyframe snap. Inclusive on
+            # the span end, since sub-MIN_INTERVAL_S overlaps are dropped
+            # by the resolver and leave the previous span ending a hair
+            # past this row's start
+            if (
+                spans
+                and is_main == last_is_main
+                and spans[-1][1] < row.start_time <= spans[-1][2]
+            ):
+                spans[-1][2] = row.start_time
+                start = row.start_time
+            spans.append([row, start, interval.end_time, is_main])
+        last_is_main = is_main
+    return spans
+
+
+def _keyframe_before(keyframes: Any, offset_ms: int) -> int | None:
+    """Last stored keyframe offset at or before offset_ms.
+
+    keyframes is the row's record-time keyframe index (ms from segment
+    start). Returns None when the row has no usable index, which callers
+    treat as "serve the whole file".
+    """
+    if not keyframes:
+        return None
+
+    candidates = [k for k in keyframes if k <= offset_ms]
+    return max(candidates) if candidates else None
+
+
+@dataclass
+class ClipPlan:
+    """The exact playlist realization of one span.
+
+    clip_from_ms is the keyframe-snapped clipFrom, or None when the whole
+    file is served. skipped means the clip is omitted from the manifest.
+
+    key_frame_durations / first_key_frame_offset_ms carry clip-relative
+    keyframe data for nginx-vod sub-file segmentation; None means no
+    usable index, and the manifest declares one whole-clip segment (the
+    only safe cut without keyframe knowledge).
+    """
+
+    clip_from_ms: int | None
+    duration_ms: int
+    skipped: bool
+    key_frame_durations: list[int] | None = None
+    first_key_frame_offset_ms: int = 0
+
+
+def plan_clip(row: Any, start: float, end: float) -> ClipPlan:
+    """Plan one nginx-vod clip for a recording row trimmed to [start, end).
+
+    The single source of truth for clip realization: the vod mapping
+    builder emits exactly this plan and the coverage timelines report it
+    to the frontend, so the playhead model matches the playlist by
+    construction rather than accumulating drift at each hand-off.
+    """
+    min_duration_ms = 100  # Minimum 100ms to ensure at least one video frame
+    max_duration_ms = MAX_SEGMENT_DURATION * 1000
+
+    clip_from: int | None = None
+    duration = int(row.duration * 1000)
+
+    # adjust start offset if start is after the recording start
+    inpoint = int((start - row.start_time) * 1000) if start > row.start_time else 0
+    if inpoint > 0:
+        clip_from = inpoint
+        duration -= inpoint
+
+    # adjust end if the recording ends after the requested end
+    if row.end_time > end:
+        duration -= int((row.end_time - end) * 1000)
+
+    # nginx-vod-module pushes clipFrom forward to the next keyframe,
+    # which can leave too few frames for a playable segment; snapping
+    # back to the preceding keyframe always starts on a decodable frame
+    if clip_from is not None:
+        keyframe_ms = _keyframe_before(row.keyframes, clip_from)
+        if keyframe_ms is not None:
+            gained = clip_from - keyframe_ms
+            clip_from = keyframe_ms
+            duration += gained
+            logger.debug(
+                "VOD: snapped clipFrom to keyframe at %sms for %s, duration now %sms",
+                keyframe_ms,
+                row.path,
+                duration,
+            )
+        else:
+            logger.debug(
+                "VOD: no keyframe index for %s, removing clipFrom to use full recording",
+                row.path,
+            )
+            clip_from = None
+            duration = int(row.duration * 1000)
+            if row.end_time > end:
+                duration -= int((row.end_time - end) * 1000)
+
+    if duration < min_duration_ms:
+        logger.debug(
+            "VOD: skipping recording %s - resulting duration %sms too short",
+            row.path,
+            duration,
+        )
+        return ClipPlan(None, 0, True)
+
+    if duration >= max_duration_ms:
+        logger.warning(f"Recording clip is missing or empty: {row.path}")
+        return ClipPlan(None, 0, True)
+
+    return ClipPlan(
+        clip_from,
+        duration,
+        False,
+        *_clip_key_frames(row.keyframes, clip_from, duration),
+    )
+
+
+def _clip_key_frames(
+    keyframes: Any, clip_from: int | None, duration: int
+) -> tuple[list[int] | None, int]:
+    """Clip-relative keyframe gaps and first offset for a served range.
+
+    nginx-vod validates firstKeyFrameOffset against the clip duration,
+    so offsets are clip-relative. A keyframe exactly on the clip end is
+    excluded (it would declare a zero-length tail), and fewer than two
+    keyframes returns (None, 0): one cut point cannot split anything.
+    """
+    if not keyframes:
+        return None, 0
+
+    clip_start = clip_from if clip_from is not None else 0
+    relative = [
+        int(k) - clip_start
+        for k in keyframes
+        if clip_start <= k < clip_start + duration
+    ]
+
+    if len(relative) < 2:
+        return None, 0
+
+    return [b - a for a, b in zip(relative, relative[1:])], relative[0]
+
+
+def realized_timeline(
+    intervals: list[CoverageInterval], stream: str | None
+) -> list[dict[str, Any]]:
+    """The exact playlist timeline a vod route will realize for a range.
+
+    Each item pairs a span's wall-clock bounds with the duration (ms) of
+    the manifest clip serving it, including keyframe back-snap lead-in,
+    so summing durations reproduces playlist time exactly. A span whose
+    clip is skipped reports duration 0.
+    """
+    return [
+        {
+            "start_time": span_start,
+            "end_time": span_end,
+            "duration": plan.duration_ms,
+        }
+        for row, span_start, span_end, _ in build_spans(intervals, stream)
+        for plan in (plan_clip(row, span_start, span_end),)
+    ]
+
+
+def realized_timelines(
+    intervals: list[CoverageInterval],
+) -> dict[str, list[dict[str, Any]]]:
+    """All three variant timelines for a coverage window.
+
+    Applies the same glitch-nulling as the manifest builder, then
+    assembles each variant's realized spans. Keyframe snapping reads the
+    per-row index stored at record time, so no file is touched.
+    """
+    main_audio = stream_has_audio(intervals, main=True)
+    sub_audio = stream_has_audio(intervals, main=False)
+    nulled = null_audio_glitches(intervals, main_audio, sub_audio)
+
+    return {
+        "auto": realized_timeline(nulled, None),
+        "main": realized_timeline(nulled, STREAM_TYPE_MAIN),
+        "sub": realized_timeline(nulled, STREAM_TYPE_SUB),
+    }

frigate/util/services.py

@@ -1,6 +1,8 @@
 """Utilities for services."""
 
 import asyncio
+import contextlib
+import glob
 import json
 import logging
 import os
@@ -670,19 +672,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()
@@ -1241,8 +1257,22 @@ async def get_video_properties(
     async def probe_with_ffprobe(
         url: str,
         rtsp_transport: str | None = None,
-    ) -> tuple[bool, int, int, str | None, float]:
-        """Fallback using ffprobe: returns (valid, width, height, codec, duration)."""
+    ) -> tuple[
+        bool,
+        int,
+        int,
+        str | None,
+        str | None,
+        float,
+        bool | None,
+        int | None,
+        str | None,
+    ]:
+        """Probe using ffprobe: returns (valid, width, height, fourcc, video_codec, duration, has_audio, audio_rate, audio_codec).
+
+        ffprobe reports the codec name directly, so fourcc and
+        video_codec are the same value on this path.
+        """
         cmd = [ffmpeg.ffprobe_path]
         if rtsp_transport:
             cmd += ["-rtsp_transport", rtsp_transport]
@@ -1270,19 +1300,17 @@ async def get_video_properties(
                     clean_camera_user_pass(url),
                     rtsp_transport or "default",
                 )
-                proc.kill()
-                await proc.wait()
-                return False, 0, 0, None, -1
+                return False, 0, 0, None, None, -1, None, None, None
 
             if proc.returncode != 0:
-                return False, 0, 0, None, -1
+                return False, 0, 0, None, None, -1, None, None, None
 
             data = json.loads(stdout.decode())
             video_streams = [
                 s for s in data.get("streams", []) if s.get("codec_type") == "video"
             ]
             if not video_streams:
-                return False, 0, 0, None, -1
+                return False, 0, 0, None, None, -1, None, None, None
 
             v = video_streams[0]
             width = int(v.get("width", 0))
@@ -1292,16 +1320,70 @@ async def get_video_properties(
             duration_str = data.get("format", {}).get("duration")
             duration = float(duration_str) if duration_str else -1.0
 
-            return True, width, height, codec, duration
-        except (json.JSONDecodeError, ValueError, KeyError, sp.SubprocessError):
-            return False, 0, 0, None, -1
+            audio_streams = [
+                s for s in data.get("streams", []) if s.get("codec_type") == "audio"
+            ]
+            has_audio = bool(audio_streams)
 
-    def probe_with_cv2(url: str) -> tuple[bool, int, int, str | None, float]:
-        """Primary attempt using cv2: returns (valid, width, height, fourcc, duration)."""
+            # codec and sample rate distinguish audio tracks whose decoder
+            # configs cannot share an HLS sequence
+            audio_rate: int | None = None
+            audio_codec: str | None = None
+            if audio_streams:
+                try:
+                    audio_rate = int(audio_streams[0]["sample_rate"])
+                except (KeyError, TypeError, ValueError):
+                    audio_rate = None
+                audio_codec = audio_streams[0].get("codec_name")
+
+            return (
+                True,
+                width,
+                height,
+                codec,
+                codec,
+                duration,
+                has_audio,
+                audio_rate,
+                audio_codec,
+            )
+        except (json.JSONDecodeError, ValueError, KeyError, sp.SubprocessError):
+            return False, 0, 0, None, None, -1, None, None, None
+        finally:
+            # callers run in a per-cycle event loop, and an ffprobe still
+            # running when that loop closes is finalized against a dead loop
+            # ("Event loop is closed"). Draining after the kill is what
+            # closes the pipes and their transports
+            if proc is not None and proc.returncode is None:
+                with contextlib.suppress(ProcessLookupError):
+                    proc.kill()
+
+                with contextlib.suppress(TimeoutError):
+                    await asyncio.wait_for(proc.communicate(), timeout=2)
+
+    def probe_with_cv2(
+        url: str,
+    ) -> tuple[
+        bool,
+        int,
+        int,
+        str | None,
+        str | None,
+        float,
+        bool | None,
+        int | None,
+        str | None,
+    ]:
+        """Probe using cv2: returns (valid, width, height, fourcc, video_codec, duration, has_audio, audio_rate, audio_codec).
+
+        cv2 cannot report audio streams or a normalized codec name, so
+        has_audio, audio_rate, audio_codec, and video_codec are always
+        None (unknown) on this path.
+        """
         cap = cv2.VideoCapture(url)
         if not cap.isOpened():
             cap.release()
-            return False, 0, 0, None, -1
+            return False, 0, 0, None, None, -1, None, None, None
 
         width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
         height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
@@ -1320,7 +1402,7 @@ async def get_video_properties(
                     duration = total_frames / fps
 
         cap.release()
-        return valid, width, height, fourcc, duration
+        return valid, width, height, fourcc, None, duration, None, None, None
 
     is_rtsp = url.startswith("rtsp://")
 
@@ -1328,24 +1410,99 @@ async def get_video_properties(
         # skip cv2 for RTSP: its FFmpeg backend has a hardcoded ~30s internal
         # timeout that cannot be shortened per-call, and ffprobe bounded by
         # -rw_timeout handles RTSP probing reliably
-        has_video, width, height, fourcc, duration = await probe_with_ffprobe(url)
+        (
+            has_video,
+            width,
+            height,
+            fourcc,
+            video_codec,
+            duration,
+            has_audio,
+            audio_rate,
+            audio_codec,
+        ) = await probe_with_ffprobe(url)
+    elif get_duration:
+        # ffprobe first: segment validation also needs audio presence,
+        # which cv2 cannot report
+        (
+            has_video,
+            width,
+            height,
+            fourcc,
+            video_codec,
+            duration,
+            has_audio,
+            audio_rate,
+            audio_codec,
+        ) = await probe_with_ffprobe(url)
+
+        # fallback to cv2 if needed; audio stays unknown there
+        if not has_video or duration < 0:
+            (
+                has_video,
+                width,
+                height,
+                fourcc,
+                video_codec,
+                duration,
+                has_audio,
+                audio_rate,
+                audio_codec,
+            ) = probe_with_cv2(url)
     else:
         # try cv2 first for local files, HTTP, RTMP
-        has_video, width, height, fourcc, duration = probe_with_cv2(url)
+        (
+            has_video,
+            width,
+            height,
+            fourcc,
+            video_codec,
+            duration,
+            has_audio,
+            audio_rate,
+            audio_codec,
+        ) = probe_with_cv2(url)
 
         # fallback to ffprobe if needed
-        if not has_video or (get_duration and duration < 0):
-            has_video, width, height, fourcc, duration = await probe_with_ffprobe(url)
+        if not has_video:
+            (
+                has_video,
+                width,
+                height,
+                fourcc,
+                video_codec,
+                duration,
+                has_audio,
+                audio_rate,
+                audio_codec,
+            ) = await probe_with_ffprobe(url)
 
     # last resort for RTSP: try TCP transport, since default UDP may be blocked
     if (not has_video or (get_duration and duration < 0)) and is_rtsp:
-        has_video, width, height, fourcc, duration = await probe_with_ffprobe(
-            url, rtsp_transport="tcp"
-        )
+        (
+            has_video,
+            width,
+            height,
+            fourcc,
+            video_codec,
+            duration,
+            has_audio,
+            audio_rate,
+            audio_codec,
+        ) = await probe_with_ffprobe(url, rtsp_transport="tcp")
 
     result: dict[str, Any] = {"has_valid_video": has_video}
     if has_video:
-        result.update({"width": width, "height": height})
+        result.update(
+            {
+                "width": width,
+                "height": height,
+                "has_audio": has_audio,
+                "audio_rate": audio_rate,
+                "audio_codec": audio_codec,
+                "video_codec": video_codec,
+            }
+        )
         if fourcc:
             result["fourcc"] = fourcc
     if get_duration:

frigate/video/ffmpeg.py

@@ -54,59 +54,48 @@ def capture_frames(
     skipped_eps = EventsPerSecond()
     skipped_eps.start()
 
-    config_subscriber = CameraConfigUpdateSubscriber(
-        None, {config.name: config}, [CameraConfigUpdateEnum.enabled]
-    )
+    while not stop_event.is_set():
+        # CameraWatchdog applies enabled updates onto this same CameraConfig
+        # before it stops ffmpeg. Do not subscribe here: it would be rebuilt per
+        # ffmpeg restart and strand a pipe in the idle main process config PUB.
+        if not config.enabled:
+            logger.debug(f"Stopping capture thread for disabled {config.name}")
+            break
 
-    def get_enabled_state():
-        """Fetch the latest enabled state from ZMQ."""
-        config_subscriber.check_for_updates()
-        return config.enabled
-
-    try:
-        while not stop_event.is_set():
-            if not get_enabled_state():
-                logger.debug(f"Stopping capture thread for disabled {config.name}")
+        fps.value = frame_rate.eps()
+        skipped_fps.value = skipped_eps.eps()
+        current_frame.value = datetime.now().timestamp()
+        frame_name = f"{config.name}_frame{frame_index}"
+        frame_buffer = frame_manager.write(frame_name)
+        try:
+            frame_buffer[:] = ffmpeg_process.stdout.read(frame_size)
+        except Exception:
+            # shutdown has been initiated
+            if stop_event.is_set():
                 break
 
-            fps.value = frame_rate.eps()
-            skipped_fps.value = skipped_eps.eps()
-            current_frame.value = datetime.now().timestamp()
-            frame_name = f"{config.name}_frame{frame_index}"
-            frame_buffer = frame_manager.write(frame_name)
-            try:
-                frame_buffer[:] = ffmpeg_process.stdout.read(frame_size)
-            except Exception:
-                # shutdown has been initiated
-                if stop_event.is_set():
-                    break
+            logger.error(f"{config.name}: Unable to read frames from ffmpeg process.")
 
+            if ffmpeg_process.poll() is not None:
                 logger.error(
-                    f"{config.name}: Unable to read frames from ffmpeg process."
+                    f"{config.name}: ffmpeg process is not running. exiting capture thread..."
                 )
+                break
 
-                if ffmpeg_process.poll() is not None:
-                    logger.error(
-                        f"{config.name}: ffmpeg process is not running. exiting capture thread..."
-                    )
-                    break
+            continue
 
-                continue
+        frame_rate.update()
 
-            frame_rate.update()
+        # don't lock the queue to check, just try since it should rarely be full
+        try:
+            # add to the queue
+            frame_queue.put((frame_name, current_frame.value), False)
+            frame_manager.close(frame_name)
+        except queue.Full:
+            # if the queue is full, skip this frame
+            skipped_eps.update()
 
-            # don't lock the queue to check, just try since it should rarely be full
-            try:
-                # add to the queue
-                frame_queue.put((frame_name, current_frame.value), False)
-                frame_manager.close(frame_name)
-            except queue.Full:
-                # if the queue is full, skip this frame
-                skipped_eps.update()
-
-            frame_index = 0 if frame_index == shm_frame_count - 1 else frame_index + 1
-    finally:
-        config_subscriber.stop()
+        frame_index = 0 if frame_index == shm_frame_count - 1 else frame_index + 1
 
 
 class CameraWatchdog(threading.Thread):
@@ -158,6 +147,7 @@ class CameraWatchdog(threading.Thread):
         self.requestor = InterProcessRequestor()
         self.was_enabled = self.config.enabled
         self.was_record_enabled_in_config = self.config.record.enabled_in_config
+        self.was_record_sub_enabled = self.config.record.sub.enabled
 
         self.segment_subscriber = RecordingsDataSubscriber(RecordingsDataTypeEnum.all)
         self.latest_valid_segment_time: float = 0
@@ -323,6 +313,24 @@ class CameraWatchdog(threading.Thread):
                 self.was_record_enabled_in_config = record_enabled_in_config
                 continue
 
+            record_sub_enabled = self.config.record.sub.enabled
+            if record_sub_enabled != self.was_record_sub_enabled:
+                # adding and removing the record_sub output both require a
+                # restart, unlike the main record toggle
+                if record_enabled_in_config and enabled:
+                    self.logger.debug(
+                        f"Sub stream recording toggled in config for {self.config.name}, restarting ffmpeg"
+                    )
+                    self.stop_all_ffmpeg()
+                    self.start_all_ffmpeg()
+                    self.latest_valid_segment_time = 0
+                    self.latest_invalid_segment_time = 0
+                    self.latest_cache_segment_time = 0
+                    self.record_enable_time = datetime.now().astimezone(UTC)
+                    last_restart_time = datetime.now().timestamp()
+                self.was_record_sub_enabled = record_sub_enabled
+                continue
+
             if not enabled:
                 continue
 

migrations/036_add_recordings_stream_metadata.py

@@ -0,0 +1,49 @@
+"""Peewee migrations -- 036_add_recordings_stream_metadata.py.
+
+Some examples (model - class or model name)::
+
+    > Model = migrator.orm['model_name']            # Return model in current state by name
+
+    > migrator.sql(sql)                             # Run custom SQL
+    > migrator.python(func, *args, **kwargs)        # Run python code
+    > migrator.create_model(Model)                  # Create a model (could be used as decorator)
+    > migrator.remove_model(model, cascade=True)    # Remove a model
+    > migrator.add_fields(model, **fields)          # Add fields to a model
+    > migrator.change_fields(model, **fields)       # Change fields
+    > migrator.remove_fields(model, *field_names, cascade=True)
+    > migrator.rename_field(model, old_field_name, new_field_name)
+    > migrator.rename_table(model, new_table_name)
+    > migrator.add_index(model, *col_names, unique=False)
+    > migrator.drop_index(model, *col_names)
+    > migrator.add_not_null(model, *field_names)
+    > migrator.drop_not_null(model, *field_names)
+    > migrator.add_default(model, field_name, default)
+
+"""
+
+import peewee as pw
+
+SQL = pw.SQL
+
+
+def migrate(migrator, database, fake=False, **kwargs):
+    migrator.sql(
+        'ALTER TABLE "recordings" ADD COLUMN "stream_type" VARCHAR(8) NOT NULL DEFAULT \'main\''
+    )
+    migrator.sql(
+        'CREATE INDEX IF NOT EXISTS "recordings_camera_stream_type" ON "recordings" ("camera", "stream_type")'
+    )
+
+    # nullable so legacy rows stay NULL, meaning unknown
+    migrator.sql('ALTER TABLE "recordings" ADD COLUMN "has_audio" INTEGER')
+    migrator.sql('ALTER TABLE "recordings" ADD COLUMN "audio_rate" INTEGER')
+    migrator.sql('ALTER TABLE "recordings" ADD COLUMN "audio_codec" TEXT')
+    migrator.sql('ALTER TABLE "recordings" ADD COLUMN "video_codec" TEXT')
+
+    # keyframe offsets in ms from segment start; nullable so legacy rows
+    # stay NULL and playback serves whole files for them
+    migrator.sql('ALTER TABLE "recordings" ADD COLUMN "keyframes" TEXT')
+
+
+def rollback(migrator, database, fake=False, **kwargs):
+    pass

migrations/037_add_recordings_stream_index.py

@@ -0,0 +1,43 @@
+"""Peewee migrations -- 037_add_recordings_stream_index.py.
+
+Some examples (model - class or model name)::
+
+    > Model = migrator.orm['model_name']            # Return model in current state by name
+
+    > migrator.sql(sql)                             # Run custom SQL
+    > migrator.python(func, *args, **kwargs)        # Run python code
+    > migrator.create_model(Model)                  # Create a model (could be used as decorator)
+    > migrator.remove_model(model, cascade=True)    # Remove a model
+    > migrator.add_fields(model, **fields)          # Add fields to a model
+    > migrator.change_fields(model, **fields)       # Change fields
+    > migrator.remove_fields(model, *field_names, cascade=True)
+    > migrator.rename_field(model, old_field_name, new_field_name)
+    > migrator.rename_table(model, new_table_name)
+    > migrator.add_index(model, *col_names, unique=False)
+    > migrator.drop_index(model, *col_names)
+    > migrator.add_not_null(model, *field_names)
+    > migrator.drop_not_null(model, *field_names)
+    > migrator.add_default(model, field_name, default)
+
+"""
+
+import peewee as pw
+
+SQL = pw.SQL
+
+
+def migrate(migrator, database, fake=False, **kwargs):
+    # time-ordered per-stream lookups (bandwidth estimation, pinned-stream
+    # queries) need this ordering; without it, a per-stream ORDER BY
+    # start_time query on a camera with no rows for that stream walks the
+    # camera's entire history via per-row table lookups
+    migrator.sql(
+        'CREATE INDEX IF NOT EXISTS "recordings_camera_stream_type_start_time" ON "recordings" ("camera", "stream_type", "start_time" DESC)'
+    )
+    # the 036 index is a strict prefix of the one above, so keeping it
+    # would only add write amplification on the hottest table
+    migrator.sql('DROP INDEX IF EXISTS "recordings_camera_stream_type"')
+
+
+def rollback(migrator, database, fake=False, **kwargs):
+    pass

web/e2e/specs/export.spec.ts

@@ -867,6 +867,31 @@ test.describe("Multi-Camera Export from History @high", () => {
     await frigateApp.page.route("**/api/recordings/unavailable**", (route) =>
       route.fulfill({ json: [] }),
     );
+    // registered after the broad recordings route so it wins the match;
+    // coverage is an object, and the array above crashes the player
+    await frigateApp.page.route("**/api/*/recordings/coverage**", (route) =>
+      route.fulfill({
+        json: {
+          spans: [
+            {
+              start_time: playbackTime - 3600,
+              end_time: playbackTime + 600,
+              streams: ["main"],
+            },
+          ],
+          codecs_compatible: true,
+          streams: {
+            main: {
+              video_codec: "h264",
+              audio_rate: null,
+              audio_codec: null,
+              has_audio: false,
+              bitrate: 2_000_000,
+            },
+          },
+        },
+      }),
+    );
 
     await frigateApp.goto(`/review?timestamp=front_door_${playbackTime}`);
   }

web/e2e/specs/settings/camera-wizard-ptz.spec.ts

@@ -0,0 +1,187 @@
+/**
+ * Add-camera wizard — PTZ controls pane.
+ *
+ * The pane lives on Step 3 (Stream Configuration) and only appears when the
+ * ONVIF probe from Step 2 reported `ptz_supported`. These tests drive the
+ * wizard to Step 3 with a mocked probe and assert the pane's contract:
+ *   1. Visible + enabled when the probe reports PTZ, with the connection
+ *      fields collapsed by default and pre-filled once expanded.
+ *   2. Toggling the switch off hides the disclosure and its fields.
+ *   3. Clearing the host shows the validation warning and blocks "Next".
+ *   4. Absent entirely when the probe reports no PTZ support.
+ *
+ * The save path (writing the `onvif` section to config/set) runs through
+ * Step 4's live-validation flow, which registers go2rtc streams and renders
+ * MSE previews that are unreliable in headless Chromium. Consistent with
+ * clone-camera.spec.ts, that assertion is deferred to manual QA; the logic is
+ * covered by the Step 4 -> parent handleSave wiring.
+ */
+
+import { test, expect } from "../../fixtures/frigate-test";
+import type { Page, Locator } from "@playwright/test";
+
+const PTZ_PROBE = {
+  success: true,
+  host: "192.168.1.100",
+  port: 80,
+  manufacturer: "Acme",
+  model: "PTZ-1",
+  firmware_version: "1.0",
+  profiles_count: 1,
+  ptz_supported: true,
+  pan_tilt_supported: true,
+  presets_count: 2,
+  autotrack_supported: false,
+  rtsp_candidates: [
+    {
+      source: "GetStreamUri",
+      profile_token: "profile_1",
+      uri: "rtsp://admin:pw@192.168.1.100:554/stream1",
+    },
+  ],
+};
+
+async function mockProbe(page: Page, probe: object) {
+  await page.route("**/api/onvif/probe**", (route) =>
+    route.fulfill({ json: probe }),
+  );
+}
+
+/** Open the wizard and drive Step 1 -> Step 2 -> Step 3. */
+async function gotoStep3(page: Page, host = "192.168.1.100") {
+  await page.getByRole("button", { name: /Add New Camera/i }).click();
+  const dialog = page.getByRole("dialog");
+  await expect(dialog).toBeVisible();
+
+  // Step 1: name + host (probe mode is the default), then Continue.
+  await dialog.getByPlaceholder(/front_door/i).fill("ptz_test_camera");
+  await dialog.getByPlaceholder("192.168.1.100").fill(host);
+  await dialog.getByRole("button", { name: /^Continue$/i }).click();
+
+  // Step 2: the probe auto-runs on mount; once candidates exist, Next enables.
+  const next = dialog.getByRole("button", { name: /^Next$/i });
+  await expect(next).toBeEnabled({ timeout: 10_000 });
+  await next.click();
+
+  // Step 3 is the stream-configuration step; key off a stable control rather
+  // than the description text (which has been reworded).
+  await expect(
+    dialog.getByRole("button", { name: /Add Another Stream/i }),
+  ).toBeVisible();
+  return dialog;
+}
+
+/** The PTZ enable switch (scoped to the PTZ card header row). */
+function ptzSwitch(dialog: Locator) {
+  return dialog
+    .locator("div.justify-between", { hasText: "Enable PTZ Controls" })
+    .getByRole("switch");
+}
+
+/** Expand the (collapsed-by-default) ONVIF connection-detail fields. */
+async function expandOnvifDetails(dialog: Locator) {
+  await dialog
+    .getByRole("button", { name: /ONVIF connection details/i })
+    .click();
+}
+
+test.describe("Camera wizard PTZ pane @medium @mobile", () => {
+  test.beforeEach(async ({ frigateApp }) => {
+    // not in the default mock; unmocked it 500s and trips the error collector
+    await frigateApp.page.route("**/api/config/raw_paths", (route) =>
+      route.fulfill({ json: {} }),
+    );
+    await frigateApp.goto("/settings?page=cameraManagement");
+    await expect(
+      frigateApp.page.getByRole("heading", { name: /Manage Cameras/i }),
+    ).toBeVisible();
+  });
+
+  test("shows an enabled PTZ pane with collapsed, pre-filled fields", async ({
+    frigateApp,
+  }) => {
+    await mockProbe(frigateApp.page, PTZ_PROBE);
+    const dialog = await gotoStep3(frigateApp.page);
+
+    // Card is present with the detected note and the switch defaults on.
+    await expect(
+      dialog.getByText("Enable PTZ Controls", { exact: true }),
+    ).toBeVisible();
+    await expect(
+      dialog.getByText(/PTZ support has been detected via ONVIF/i),
+    ).toBeVisible();
+    await expect(ptzSwitch(dialog)).toBeChecked();
+
+    // Connection fields are collapsed by default.
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toHaveCount(0);
+
+    // Expanding reveals the host pre-filled from the probe.
+    await expandOnvifDetails(dialog);
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toHaveValue(
+      "192.168.1.100",
+    );
+  });
+
+  test("toggling the switch off hides the disclosure and fields", async ({
+    frigateApp,
+  }) => {
+    await mockProbe(frigateApp.page, PTZ_PROBE);
+    const dialog = await gotoStep3(frigateApp.page);
+
+    await expandOnvifDetails(dialog);
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toBeVisible();
+
+    await ptzSwitch(dialog).click();
+
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toHaveCount(0);
+    await expect(
+      dialog.getByRole("button", { name: /ONVIF connection details/i }),
+    ).toHaveCount(0);
+  });
+
+  test("clearing the host shows the warning and blocks Next", async ({
+    frigateApp,
+  }) => {
+    await mockProbe(frigateApp.page, PTZ_PROBE);
+    const dialog = await gotoStep3(frigateApp.page);
+
+    await expandOnvifDetails(dialog);
+    await dialog.getByPlaceholder("192.168.1.100").fill("");
+
+    await expect(
+      dialog.getByText(/An ONVIF host and port are required/i),
+    ).toBeVisible();
+    await expect(
+      dialog.getByRole("button", { name: /^Next$/i }),
+    ).toBeDisabled();
+  });
+
+  test("shows the pane but leaves the switch off without continuous pan/tilt", async ({
+    frigateApp,
+  }) => {
+    // e.g. a varifocal camera: PTZ service present, but zoom/focus only
+    await mockProbe(frigateApp.page, {
+      ...PTZ_PROBE,
+      pan_tilt_supported: false,
+    });
+    const dialog = await gotoStep3(frigateApp.page);
+
+    await expect(
+      dialog.getByText("Enable PTZ Controls", { exact: true }),
+    ).toBeVisible();
+    await expect(ptzSwitch(dialog)).not.toBeChecked();
+    // with the switch off, the connection fields are not shown
+    await expect(dialog.getByPlaceholder("192.168.1.100")).toHaveCount(0);
+  });
+
+  test("hides the PTZ pane when the probe reports no PTZ support", async ({
+    frigateApp,
+  }) => {
+    await mockProbe(frigateApp.page, { ...PTZ_PROBE, ptz_supported: false });
+    const dialog = await gotoStep3(frigateApp.page);
+
+    await expect(
+      dialog.getByText("Enable PTZ Controls", { exact: true }),
+    ).toHaveCount(0);
+  });
+});

web/public/locales/en/components/player.json

@@ -13,6 +13,20 @@
     "desc": "No frames have been received on the {{cameraName}} <code>detect</code> stream, check error logs"
   },
   "cameraOff": "Camera is off",
+  "quality": {
+    "auto": "Auto",
+    "autoLow": "Playing low quality (limited bandwidth)",
+    "autoLowCodec": "Playing low quality (Original not supported by this browser)",
+    "autoLowSaveData": "Playing low quality (data saver)",
+    "main": "Original",
+    "sub": "Low",
+    "notSupportedBrowser": "Not supported by this browser",
+    "label": "Quality",
+    "noAudio": "No audio",
+    "audioRate": "{{rate}} kHz audio",
+    "audioCodecRate": "{{codec}} {{rate}} kHz",
+    "noRecordings": "No recordings in this time range"
+  },
   "stats": {
     "streamType": {
       "title": "Stream Type:",
@@ -46,7 +60,8 @@
       "submittedFrigatePlus": "Successfully submitted frame to Frigate+"
     },
     "error": {
-      "submitFrigatePlusFailed": "Failed to submit frame to Frigate+"
+      "submitFrigatePlusFailed": "Failed to submit frame to Frigate+",
+      "playRecordingsFailed": "Failed to play recordings (error {{code}}): {{message}}"
     }
   }
 }

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

@@ -31,6 +31,10 @@
       "label": "Listen types",
       "description": "List of audio event types to detect (for example: bark, fire_alarm, speech, yell)."
     },
+    "labelmap": {
+      "label": "Audio labelmap customization",
+      "description": "Overrides or remapping entries to merge into the standard audio labelmap."
+    },
     "filters": {
       "label": "Audio filters",
       "description": "Per-audio-type filter settings such as confidence thresholds used to reduce false positives.",
@@ -70,9 +74,9 @@
       "label": "Enable Birdseye",
       "description": "Enable or disable the Birdseye view feature."
     },
-    "mode": {
-      "label": "Tracking mode",
-      "description": "Mode for including cameras in Birdseye: 'objects', 'motion', or 'continuous'."
+    "modes": {
+      "label": "Activity types",
+      "description": "Activity types that include cameras in Birdseye."
     },
     "order": {
       "label": "Position",
@@ -180,6 +184,10 @@
       "record": {
         "label": "Record output arguments",
         "description": "Default output arguments for record role streams."
+      },
+      "record_sub": {
+        "label": "Sub stream record output arguments",
+        "description": "Output arguments for record_sub role streams. The record output arguments are used when this is not set."
       }
     },
     "retry_interval": {
@@ -506,6 +514,54 @@
         "description": "Preview quality level (very_low, low, medium, high, very_high)."
       }
     },
+    "sub": {
+      "label": "Sub stream recording",
+      "description": "Settings for recording a second, lower quality stream.",
+      "enabled": {
+        "label": "Enable sub stream recording",
+        "description": "Enable recording of a second, lower quality stream for adaptive quality playback and extended retention."
+      },
+      "continuous": {
+        "label": "Sub stream continuous retention",
+        "description": "Number of days to retain sub stream recordings regardless of tracked objects or motion.",
+        "days": {
+          "label": "Retention days",
+          "description": "Days to retain recordings."
+        }
+      },
+      "motion": {
+        "label": "Sub stream motion retention",
+        "description": "Number of days to retain sub stream recordings triggered by motion.",
+        "days": {
+          "label": "Retention days",
+          "description": "Days to retain recordings."
+        }
+      },
+      "alerts": {
+        "label": "Sub stream alert retention",
+        "description": "Retention settings for sub stream recordings of alerts.",
+        "days": {
+          "label": "Retention days",
+          "description": "Number of days to retain recordings of detection events."
+        },
+        "mode": {
+          "label": "Retention mode",
+          "description": "Mode for retention: all (save all segments), motion (save segments with motion), or active_objects (save segments with active objects)."
+        }
+      },
+      "detections": {
+        "label": "Sub stream detection retention",
+        "description": "Retention settings for sub stream recordings of detections.",
+        "days": {
+          "label": "Retention days",
+          "description": "Number of days to retain recordings of detection events."
+        },
+        "mode": {
+          "label": "Retention mode",
+          "description": "Mode for retention: all (save all segments), motion (save segments with motion), or active_objects (save segments with active objects)."
+        }
+      }
+    },
     "enabled_in_config": {
       "label": "Original recording state",
       "description": "Indicates whether recording was enabled in the original static configuration."

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

@@ -533,6 +533,10 @@
       "label": "Listen types",
       "description": "List of audio event types to detect (for example: bark, fire_alarm, speech, yell)."
     },
+    "labelmap": {
+      "label": "Audio labelmap customization",
+      "description": "Overrides or remapping entries to merge into the standard audio labelmap."
+    },
     "filters": {
       "label": "Audio filters",
       "description": "Per-audio-type filter settings such as confidence thresholds used to reduce false positives.",
@@ -557,9 +561,9 @@
       "label": "Enable Birdseye",
       "description": "Enable or disable the Birdseye view feature."
     },
-    "mode": {
-      "label": "Tracking mode",
-      "description": "Mode for including cameras in Birdseye: 'objects', 'motion', or 'continuous'."
+    "modes": {
+      "label": "Activity types",
+      "description": "Activity types that include cameras in Birdseye."
     },
     "restream": {
       "label": "Restream RTSP",
@@ -691,6 +695,10 @@
       "record": {
         "label": "Record output arguments",
         "description": "Default output arguments for record role streams."
+      },
+      "record_sub": {
+        "label": "Sub stream record output arguments",
+        "description": "Output arguments for record_sub role streams. The record output arguments are used when this is not set."
       }
     },
     "retry_interval": {
@@ -1032,6 +1040,54 @@
         "description": "Preview quality level (very_low, low, medium, high, very_high)."
       }
     },
+    "sub": {
+      "label": "Sub stream recording",
+      "description": "Settings for recording a second, lower quality stream.",
+      "enabled": {
+        "label": "Enable sub stream recording",
+        "description": "Enable recording of a second, lower quality stream for adaptive quality playback and extended retention."
+      },
+      "continuous": {
+        "label": "Sub stream continuous retention",
+        "description": "Number of days to retain sub stream recordings regardless of tracked objects or motion.",
+        "days": {
+          "label": "Retention days",
+          "description": "Days to retain recordings."
+        }
+      },
+      "motion": {
+        "label": "Sub stream motion retention",
+        "description": "Number of days to retain sub stream recordings triggered by motion.",
+        "days": {
+          "label": "Retention days",
+          "description": "Days to retain recordings."
+        }
+      },
+      "alerts": {
+        "label": "Sub stream alert retention",
+        "description": "Retention settings for sub stream recordings of alerts.",
+        "days": {
+          "label": "Retention days",
+          "description": "Number of days to retain recordings of detection events."
+        },
+        "mode": {
+          "label": "Retention mode",
+          "description": "Mode for retention: all (save all segments), motion (save segments with motion), or active_objects (save segments with active objects)."
+        }
+      },
+      "detections": {
+        "label": "Sub stream detection retention",
+        "description": "Retention settings for sub stream recordings of detections.",
+        "days": {
+          "label": "Retention days",
+          "description": "Number of days to retain recordings of detection events."
+        },
+        "mode": {
+          "label": "Retention mode",
+          "description": "Mode for retention: all (save all segments), motion (save segments with motion), or active_objects (save segments with active objects)."
+        }
+      }
+    },
     "enabled_in_config": {
       "label": "Original recording state",
       "description": "Indicates whether recording was enabled in the original static configuration."

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

@@ -21,6 +21,7 @@
   },
   "zoomIn": "Zoom In",
   "zoomOut": "Zoom Out",
+  "subOnlyQuality": "Only low quality recordings are available in this time range",
   "events": {
     "label": "Events",
     "aria": "Select events",

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

@@ -364,7 +364,7 @@
       }
     },
     "step3": {
-      "description": "Configure stream roles and add additional streams for your camera.",
+      "description": "Configure features, stream roles, and add additional streams for your camera.",
       "streamsTitle": "Camera Streams",
       "addStream": "Add Stream",
       "addAnotherStream": "Add Another Stream",
@@ -398,11 +398,22 @@
         "title": "Stream Roles",
         "detect": "Main feed for object detection.",
         "record": "Saves segments of the video feed based on configuration settings.",
+        "record_sub": "Lower quality recordings for adaptive playback and extended retention (typically the camera sub stream).",
         "audio": "Feed for audio based detection."
       },
       "featuresPopover": {
         "title": "Stream Features",
         "description": "Use go2rtc restreaming to reduce connections to your camera."
+      },
+      "ptz": {
+        "title": "Enable PTZ Controls",
+        "detectedNote": "PTZ support has been detected via ONVIF. If this is a PTZ camera, enabling this option will allow you to control the camera's pan/tilt/zoom functions from the UI.",
+        "connectionDetails": "ONVIF connection details",
+        "host": "ONVIF Host",
+        "port": "ONVIF Port",
+        "username": "ONVIF Username",
+        "password": "ONVIF Password",
+        "hostRequiredWarning": "An ONVIF host and port are required when PTZ controls are enabled."
       }
     },
     "step4": {
@@ -1528,6 +1539,7 @@
       "manual": "Manual arguments",
       "inherit": "Inherit from camera setting",
       "none": "None",
+      "sameAsRecord": "Same as record output arguments",
       "useGlobalSetting": "Inherit from global setting",
       "selectPreset": "Select preset",
       "manualPlaceholder": "Enter FFmpeg arguments",
@@ -1645,12 +1657,25 @@
       "summary": "{{count}} selected",
       "empty": "No zones available"
     },
+    "birdseyeModes": {
+      "summary": "{{count}} selected",
+      "options": {
+        "continuous": "Continuous",
+        "motion": "Motion",
+        "all_objects": "All objects",
+        "alerts": "Alerts",
+        "detections": "Detections"
+      }
+    },
     "inputRoles": {
       "summary": "{{count}} roles selected",
       "empty": "No roles available",
+      "roleInUse": "Already assigned to another stream",
+      "recordSubConflict": "A stream cannot have both record and record_sub roles",
       "options": {
         "detect": "Detect",
         "record": "Record",
+        "record_sub": "Record (Sub Stream)",
         "audio": "Audio"
       }
     },
@@ -1841,11 +1866,6 @@
     }
   },
   "birdseye": {
-    "trackingMode": {
-      "objects": "Objects",
-      "motion": "Motion",
-      "continuous": "Continuous"
-    },
     "cameraOrder": {
       "label": "Camera order",
       "description": "Drag cameras to set their order in the Birdseye layout.",
@@ -1952,10 +1972,11 @@
       "modelSizeLarge": "The 'large' model is optimized for multi-line license plates. The 'small' model provides better performance over 'large' and should be used unless your region uses multi-line plate formats."
     },
     "record": {
-      "noRecordRole": "No streams have the record role defined. Recording will not function."
+      "noRecordRole": "No streams have the record role defined. Recording will not function.",
+      "noRecordSubRole": "No streams have the record_sub role defined. Sub stream 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/public/locales/en/views/system.json

@@ -148,6 +148,10 @@
       "unused": {
         "title": "Unused",
         "tips": "This value may not accurately represent the free space available to Frigate if you have other files stored on your drive beyond Frigate's recordings. Frigate does not track storage usage outside of its recordings."
+      },
+      "subStream": {
+        "information": "Sub Stream Storage Information",
+        "tips": "Cameras that record a sub stream show their Original and Low quality usage separately, using the same names as the quality options in recording playback. Low quality recordings stay on disk until their retention period expires, so this breakdown can still appear for a camera after sub stream recording has been turned off."
       }
     }
   },

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

@@ -31,7 +31,7 @@ const audio: SectionConfigOverrides = {
       detection: ["listen", "filters"],
       sensitivity: ["min_volume", "max_not_heard"],
     },
-    hiddenFields: ["enabled_in_config"],
+    hiddenFields: ["enabled_in_config", "labelmap"],
     advancedFields: ["min_volume", "max_not_heard", "num_threads"],
     uiSchema: {
       filters: {

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

@@ -5,29 +5,31 @@ 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 modes = ctx.formData?.modes;
+          if (!Array.isArray(modes)) {
+            return false;
+          }
+
           return (
-            ctx.formData?.mode === "objects" &&
+            modes.includes("all_objects") &&
             ctx.fullCameraConfig.detect?.enabled === false
           );
         },
       },
     ],
     restartRequired: [],
-    fieldOrder: ["enabled", "mode", "order"],
+    fieldOrder: ["enabled", "modes", "order"],
     hiddenFields: ["order"],
     advancedFields: [],
-    overrideFields: ["enabled", "mode"],
+    overrideFields: ["enabled", "modes"],
     uiSchema: {
-      mode: {
-        "ui:size": "xs",
-        "ui:options": {
-          enumI18nPrefix: "birdseye.trackingMode",
-        },
+      modes: {
+        "ui:widget": "birdseyeModes",
       },
     },
   },
@@ -38,7 +40,7 @@ const birdseye: SectionConfigOverrides = {
       "width",
       "height",
       "quality",
-      "mode",
+      "modes",
       "layout",
       "inactivity_threshold",
       "idle_heartbeat_fps",
@@ -54,8 +56,7 @@ const birdseye: SectionConfigOverrides = {
       "idle_heartbeat_fps",
     ],
     uiSchema: {
-      mode: {
-        "ui:size": "xs",
+      modes: {
         "ui:after": { render: "BirdseyeCameraReorder" },
       },
     },

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

@@ -20,6 +20,13 @@ const ffmpegArgsWidget = (
   },
 });
 
+const recordSubArgsWidget = () =>
+  ffmpegArgsWidget("output_args.record_sub", {
+    allowInherit: true,
+    forceSplitLayout: true,
+    unsetLabelKey: "configForm.ffmpegArgs.sameAsRecord",
+  });
+
 const ffmpeg: SectionConfigOverrides = {
   base: {
     sectionDocs: "/configuration/ffmpeg_presets",
@@ -75,6 +82,8 @@ const ffmpeg: SectionConfigOverrides = {
       output_args: "/configuration/ffmpeg_presets#output-args-presets",
       "inputs.output_args": "/configuration/ffmpeg_presets#output-args-presets",
       "output_args.record": "/configuration/ffmpeg_presets#output-args-presets",
+      "output_args.record_sub":
+        "/configuration/ffmpeg_presets#output-args-presets",
       "inputs.roles": "/configuration/cameras/#setting-up-camera-inputs",
       apple_compatibility:
         "/configuration/camera_specific#h265-cameras-via-safari",
@@ -112,9 +121,11 @@ const ffmpeg: SectionConfigOverrides = {
       output_args: {
         detect: arrayAsTextWidget,
         record: ffmpegArgsWidget("output_args.record"),
+        record_sub: recordSubArgsWidget(),
         items: {
           detect: arrayAsTextWidget,
           record: ffmpegArgsWidget("output_args.record"),
+          record_sub: recordSubArgsWidget(),
         },
       },
       inputs: {
@@ -148,6 +159,7 @@ const ffmpeg: SectionConfigOverrides = {
             items: {
               detect: arrayAsTextWidget,
               record: ffmpegArgsWidget("output_args.record"),
+              record_sub: recordSubArgsWidget(),
             },
           },
         },
@@ -176,6 +188,7 @@ const ffmpeg: SectionConfigOverrides = {
       output_args: {
         detect: arrayAsTextWidget,
         record: ffmpegArgsWidget("output_args.record"),
+        record_sub: recordSubArgsWidget(),
       },
     },
   },

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

@@ -15,6 +15,19 @@ const record: SectionConfigOverrides = {
           );
         },
       },
+      {
+        key: "no-record-sub-role",
+        messageKey: "configMessages.record.noRecordSubRole",
+        severity: "warning",
+        condition: (ctx) => {
+          if (ctx.level !== "camera" || !ctx.fullCameraConfig) return false;
+          const sub = ctx.formData?.sub as Record<string, unknown> | undefined;
+          if (!sub?.enabled) return false;
+          return !ctx.fullCameraConfig.ffmpeg?.inputs?.some((i) =>
+            i.roles?.includes("record_sub"),
+          );
+        },
+      },
     ],
     fieldDocs: {
       "alerts.pre_capture":
@@ -34,6 +47,7 @@ const record: SectionConfigOverrides = {
       "motion",
       "alerts",
       "detections",
+      "sub",
       "preview",
       "export",
     ],
@@ -67,6 +81,12 @@ const record: SectionConfigOverrides = {
       "detections.retain.mode": {
         "ui:options": { enumI18nPrefix: "retainMode" },
       },
+      "sub.alerts.mode": {
+        "ui:options": { enumI18nPrefix: "retainMode" },
+      },
+      "sub.detections.mode": {
+        "ui:options": { enumI18nPrefix: "retainMode" },
+      },
       preview: {
         "ui:options": { defaultOpen: true, disableCollapsible: true },
         quality: {

web/src/components/config-form/theme/fields/CameraInputsField.tsx

@@ -193,6 +193,25 @@ export function CameraInputsField(props: FieldProps) {
     }
   }, [fieldPathId.path, inputs, onChange]);
 
+  const getRolesUsedByOtherInputs = useCallback(
+    (index: number): string[] => {
+      const used = new Set<string>();
+      inputs.forEach((input, currentIndex) => {
+        if (currentIndex === index || !Array.isArray(input.roles)) {
+          return;
+        }
+
+        input.roles.forEach((role) => {
+          if (typeof role === "string") {
+            used.add(role);
+          }
+        });
+      });
+      return [...used];
+    },
+    [inputs],
+  );
+
   const handleFieldValueChange = useCallback(
     (index: number, fieldName: string, nextValue: unknown) => {
       const nextInputs = cloneDeep(inputs);
@@ -466,7 +485,16 @@ export function CameraInputsField(props: FieldProps) {
                     />
                   </div>
 
-                  <div className="w-full">{renderField(index, "roles")}</div>
+                  <div className="w-full">
+                    {renderField(index, "roles", {
+                      extraUiSchema: {
+                        "ui:options": {
+                          rolesUsedByOtherInputs:
+                            getRolesUsedByOtherInputs(index),
+                        },
+                      },
+                    })}
+                  </div>
 
                   {renderField(index, "input_args")}
 

web/src/components/config-form/theme/frigateTheme.ts

@@ -22,6 +22,7 @@ import { ObjectLabelSwitchesWidget } from "./widgets/ObjectLabelSwitchesWidget";
 import { AudioLabelSwitchesWidget } from "./widgets/AudioLabelSwitchesWidget";
 import { ReviewLabelSwitchesWidget } from "./widgets/ReviewLabelSwitchesWidget";
 import { ZoneSwitchesWidget } from "./widgets/ZoneSwitchesWidget";
+import { BirdseyeModesWidget } from "./widgets/BirdseyeModesWidget";
 import { ArrayAsTextWidget } from "./widgets/ArrayAsTextWidget";
 import { FfmpegArgsWidget } from "./widgets/FfmpegArgsWidget";
 import { GenAIModelWidget } from "./widgets/GenAIModelWidget";
@@ -87,6 +88,7 @@ export const frigateTheme: FrigateTheme = {
     audioLabels: AudioLabelSwitchesWidget,
     reviewLabels: ReviewLabelSwitchesWidget,
     zoneNames: ZoneSwitchesWidget,
+    birdseyeModes: BirdseyeModesWidget,
     timezoneSelect: TimezoneSelectWidget,
     optionalField: OptionalFieldWidget,
     semanticSearchModel: SemanticSearchModelWidget,

web/src/components/config-form/theme/widgets/BirdseyeModesWidget.tsx

@@ -0,0 +1,44 @@
+// Birdseye Modes Widget - For selecting Birdseye activity types via switches
+import type { WidgetProps } from "@rjsf/utils";
+import { SwitchesWidget } from "./SwitchesWidget";
+import type { FormContext } from "./SwitchesWidget";
+
+// order matches BirdseyeModeEnum in frigate/config/camera/birdseye.py
+const BIRDSEYE_MODES: string[] = [
+  "continuous",
+  "motion",
+  "all_objects",
+  "alerts",
+  "detections",
+];
+
+function getBirdseyeModes(): string[] {
+  return BIRDSEYE_MODES;
+}
+
+function getBirdseyeModeLabel(mode: string, context?: FormContext): string {
+  const t = context?.t;
+
+  if (!t) {
+    return mode;
+  }
+
+  return t(`configForm.birdseyeModes.options.${mode}`, {
+    ns: "views/settings",
+    defaultValue: mode,
+  });
+}
+
+export function BirdseyeModesWidget(props: WidgetProps) {
+  return (
+    <SwitchesWidget
+      {...props}
+      options={{
+        ...props.options,
+        getEntities: getBirdseyeModes,
+        getDisplayLabel: getBirdseyeModeLabel,
+        i18nKey: "birdseyeModes",
+      }}
+    />
+  );
+}

web/src/components/config-form/theme/widgets/FfmpegArgsWidget.tsx

@@ -30,6 +30,7 @@ type PresetField =
   | "hwaccel_args"
   | "input_args"
   | "output_args.record"
+  | "output_args.record_sub"
   | "output_args.detect";
 
 const getPresetOptions = (
@@ -49,7 +50,10 @@ const getPresetOptions = (
   }
 
   if (field.startsWith("output_args.")) {
-    const key = field.split(".")[1] as "record" | "detect";
+    const key =
+      field === "output_args.record_sub"
+        ? "record"
+        : (field.split(".")[1] as "record" | "detect");
     return data.output_args?.[key] ?? [];
   }
 
@@ -127,6 +131,7 @@ export function FfmpegArgsWidget(props: WidgetProps) {
   const globalFieldPath =
     (options?.ffmpegGlobalFieldPath as string | undefined) ?? presetField;
   const allowInherit = options?.allowInherit === true;
+  const unsetLabelKey = options?.unsetLabelKey as string | undefined;
   const hideDescription = options?.hideDescription === true;
   const useSplitLayout = options?.splitLayout !== false;
 
@@ -287,6 +292,12 @@ export function FfmpegArgsWidget(props: WidgetProps) {
         : "ffmpeg.output_args.record.description";
     }
 
+    if (presetField === "output_args.record_sub") {
+      return isInputScoped
+        ? "ffmpeg.inputs.output_args.record_sub.description"
+        : "ffmpeg.output_args.record_sub.description";
+    }
+
     if (presetField === "output_args.detect") {
       return isInputScoped
         ? "ffmpeg.inputs.output_args.detect.description"
@@ -345,7 +356,9 @@ export function FfmpegArgsWidget(props: WidgetProps) {
               }
             />
             <label htmlFor={`${id}-inherit`} className="cursor-pointer text-sm">
-              {t("configForm.ffmpegArgs.inherit", { ns: "views/settings" })}
+              {t(unsetLabelKey ?? "configForm.ffmpegArgs.inherit", {
+                ns: "views/settings",
+              })}
             </label>
           </div>
         ) : (
@@ -361,7 +374,9 @@ export function FfmpegArgsWidget(props: WidgetProps) {
               }
             />
             <label htmlFor={`${id}-none`} className="cursor-pointer text-sm">
-              {t("configForm.ffmpegArgs.none", { ns: "views/settings" })}
+              {t(unsetLabelKey ?? "configForm.ffmpegArgs.none", {
+                ns: "views/settings",
+              })}
             </label>
           </div>
         )}

web/src/components/config-form/theme/widgets/InputRolesWidget.tsx

@@ -3,7 +3,14 @@ import { useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { Switch } from "@/components/ui/switch";
 
-const INPUT_ROLES = ["detect", "record", "audio"] as const;
+const INPUT_ROLES = ["detect", "record", "record_sub", "audio"] as const;
+
+// Recording the sub stream from the same input as record would just
+// re-record the main stream, so the two roles are mutually exclusive.
+const CONFLICTING_ROLES: Partial<Record<string, string>> = {
+  record: "record_sub",
+  record_sub: "record",
+};
 
 function normalizeValue(value: unknown): string[] {
   if (Array.isArray(value)) {
@@ -18,11 +25,18 @@ function normalizeValue(value: unknown): string[] {
 }
 
 export function InputRolesWidget(props: WidgetProps) {
-  const { id, value, disabled, readonly, onChange } = props;
+  const { id, value, disabled, readonly, onChange, options } = props;
   const { t } = useTranslation(["views/settings"]);
 
   const selectedRoles = useMemo(() => normalizeValue(value), [value]);
 
+  // Each role may only be assigned to a single input, so roles already
+  // used by sibling inputs are locked.
+  const rolesUsedByOtherInputs = useMemo(
+    () => normalizeValue(options?.rolesUsedByOtherInputs),
+    [options],
+  );
+
   const toggleRole = (role: string, enabled: boolean) => {
     if (enabled) {
       if (!selectedRoles.includes(role)) {
@@ -39,6 +53,20 @@ export function InputRolesWidget(props: WidgetProps) {
       <div className="grid gap-2">
         {INPUT_ROLES.map((role) => {
           const checked = selectedRoles.includes(role);
+          const usedByOtherInput =
+            !checked && rolesUsedByOtherInputs.includes(role);
+          const conflictingRole = CONFLICTING_ROLES[role];
+          const hasConflict =
+            !checked &&
+            conflictingRole !== undefined &&
+            selectedRoles.includes(conflictingRole);
+          const hint = usedByOtherInput
+            ? t("configForm.inputRoles.roleInUse", { ns: "views/settings" })
+            : hasConflict
+              ? t("configForm.inputRoles.recordSubConflict", {
+                  ns: "views/settings",
+                })
+              : undefined;
           const label = t(`configForm.inputRoles.options.${role}`, {
             ns: "views/settings",
             defaultValue: role,
@@ -49,13 +77,20 @@ export function InputRolesWidget(props: WidgetProps) {
               key={role}
               className="flex items-center justify-between rounded-md px-3 py-0"
             >
-              <label htmlFor={`${id}-${role}`} className="text-sm">
-                {label}
-              </label>
+              <div className="flex flex-col">
+                <label htmlFor={`${id}-${role}`} className="text-sm">
+                  {label}
+                </label>
+                {hint ? (
+                  <span className="text-xs text-muted-foreground">{hint}</span>
+                ) : null}
+              </div>
               <Switch
                 id={`${id}-${role}`}
                 checked={checked}
-                disabled={disabled || readonly}
+                disabled={
+                  disabled || readonly || usedByOtherInput || hasConflict
+                }
                 onCheckedChange={(enabled) => toggleRole(role, !!enabled)}
               />
             </div>

web/src/components/filter/ReviewFilterGroup.tsx

@@ -14,12 +14,10 @@ import { FaCheckCircle, FaFilter, FaRunning } from "react-icons/fa";
 import { isDesktop, isMobile } from "react-device-detect";
 import { Switch } from "../ui/switch";
 import { Label } from "../ui/label";
-import MobileReviewSettingsDrawer, {
-  DrawerFeatures,
-} from "../overlay/MobileReviewSettingsDrawer";
+import MobileReviewSettingsDrawer from "../overlay/MobileReviewSettingsDrawer";
 import useOptimisticState from "@/hooks/use-optimistic-state";
 import FilterSwitch from "./FilterSwitch";
-import { FilterList, GeneralFilter } from "@/types/filter";
+import { DrawerFeatures, FilterList, GeneralFilter } from "@/types/filter";
 import CalendarFilterButton from "./CalendarFilterButton";
 import { CamerasFilterButton } from "./CamerasFilterButton";
 import PlatformAwareDialog from "../overlay/dialog/PlatformAwareDialog";