Update uvicorn requirement from ==0.35.* to ==0.46.* in /docker/main

Updates the requirements on [uvicorn](https://github.com/Kludex/uvicorn) to permit the latest version.
- [Release notes](https://github.com/Kludex/uvicorn/releases)
- [Changelog](https://github.com/Kludex/uvicorn/blob/main/docs/release-notes.md)
- [Commits](https://github.com/Kludex/uvicorn/compare/0.35.0...0.46.0)

---
updated-dependencies:
- dependency-name: uvicorn
  dependency-version: 0.46.0
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/pull_request_template.md

@@ -26,7 +26,7 @@ _Please read the [contributing guidelines](https://github.com/blakeblackshear/fr
 
 - This PR fixes or closes issue: fixes #
 - This PR is related to issue:
-- Link to discussion with maintainers (**required** for large/pinned features):
+- Link to discussion with maintainers (**required** for any large or "planned" features):
 
 ## For new features
 

.github/workflows/pr_template_check.yml

@@ -13,10 +13,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check PR description against template
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         with:
           script: |
-            const maintainers = ['blakeblackshear', 'NickM-27', 'hawkeye217', 'dependabot[bot]'];
+            const maintainers = ['blakeblackshear', 'NickM-27', 'hawkeye217', 'dependabot[bot]', 'weblate'];
             const author = context.payload.pull_request.user.login;
 
             if (maintainers.includes(author)) {

.github/workflows/pull_request.yml

@@ -50,6 +50,37 @@ jobs:
       #   run: npm run test
       #   working-directory: ./web
 
+  web_e2e:
+    name: Web - E2E Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20.x
+      - run: npm install
+        working-directory: ./web
+      - name: Install Playwright Chromium
+        run: npx playwright install chromium --with-deps
+        working-directory: ./web
+      - name: Build web for E2E
+        run: npm run e2e:build
+        working-directory: ./web
+      - name: Run E2E tests
+        run: npm run e2e
+        working-directory: ./web
+      - name: Upload test artifacts
+        uses: actions/upload-artifact@v7
+        if: failure()
+        with:
+          name: playwright-report
+          path: |
+            web/test-results/
+            web/playwright-report/
+          retention-days: 7
+
   python_checks:
     runs-on: ubuntu-latest
     name: Python Checks

.github/workflows/stale.yml

@@ -18,9 +18,9 @@ jobs:
           close-issue-message: ""
           days-before-stale: 30
           days-before-close: 3
-          exempt-draft-pr: true
-          exempt-issue-labels: "pinned,security"
-          exempt-pr-labels: "pinned,security,dependencies"
+          exempt-draft-pr: false
+          exempt-issue-labels: "planned,security"
+          exempt-pr-labels: "planned,security,dependencies"
           operations-per-run: 120
       - name: Print outputs
         env:

CONTRIBUTING.md

@@ -12,7 +12,7 @@ If you've found a bug and want to fix it, go for it. Link to the relevant issue
 
 Every new feature adds scope that the maintainers must test, maintain, and support long-term. Before writing code for a new feature:
 
-1. **Check for existing discussion.** Search [feature requests](https://github.com/blakeblackshear/frigate/issues) and [discussions](https://github.com/blakeblackshear/frigate/discussions) to see if it's been proposed or discussed. Pinned feature requests are on our radar — we plan to get to them, but we don't maintain a public roadmap or timeline. Check in with us first if you have interest in contributing to one.
+1. **Check for existing discussion.** Search [feature requests](https://github.com/blakeblackshear/frigate/issues) and [discussions](https://github.com/blakeblackshear/frigate/discussions) to see if it's been proposed or discussed. Feature requests tagged with "planned" are on our radar — we plan to get to them, but we don't maintain a public roadmap or timeline. Check in with us first if you have interest in contributing to one.
 2. **Start a discussion or feature request first.** This helps ensure your idea aligns with Frigate's direction before you invest time building it. Community interest in a feature request helps us gauge demand, though a great idea is a great idea even without a crowd behind it.
 3. **Be open to "no".** We try to be thoughtful about what we take on, and sometimes that means saying no to good code if the feature isn't the right fit for the project. These calls are sometimes subjective, and we won't always get them right. We're happy to discuss and reconsider.
 

docker-compose.yml

@@ -14,6 +14,8 @@ services:
       dockerfile: docker/main/Dockerfile
       # Use target devcontainer-trt for TensorRT dev
       target: devcontainer
+      cache_from:
+        - ghcr.io/blakeblackshear/frigate:cache-amd64
     ## Uncomment this block for nvidia gpu support
     # deploy:
     #       resources:

docker/main/Dockerfile

@@ -52,6 +52,14 @@ RUN --mount=type=tmpfs,target=/tmp --mount=type=tmpfs,target=/var/cache/apt \
     --mount=type=cache,target=/root/.ccache \
     /deps/build_sqlite_vec.sh
 
+# Build intel-media-driver from source against bookworm's system libva so it
+# works with Debian 12's glibc/libstdc++ (pre-built noble/trixie packages
+# require glibc 2.38 which is not available on bookworm).
+FROM base AS intel-media-driver
+ARG DEBIAN_FRONTEND
+RUN --mount=type=bind,source=docker/main/build_intel_media_driver.sh,target=/deps/build_intel_media_driver.sh \
+    /deps/build_intel_media_driver.sh
+
 FROM scratch AS go2rtc
 ARG TARGETARCH
 WORKDIR /rootfs/usr/local/go2rtc/bin
@@ -200,6 +208,7 @@ RUN --mount=type=bind,source=docker/main/install_hailort.sh,target=/deps/install
 FROM scratch AS deps-rootfs
 COPY --from=nginx /usr/local/nginx/ /usr/local/nginx/
 COPY --from=sqlite-vec /usr/local/lib/ /usr/local/lib/
+COPY --from=intel-media-driver /rootfs/ /
 COPY --from=go2rtc /rootfs/ /
 COPY --from=libusb-build /usr/local/lib /usr/local/lib
 COPY --from=tempio /rootfs/ /

docker/main/build_intel_media_driver.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+set -euxo pipefail
+
+# Intel media driver is x86_64-only. Create empty rootfs on other arches so
+# the downstream COPY --from has a valid source.
+if [ "$(uname -m)" != "x86_64" ]; then
+    mkdir -p /rootfs
+    exit 0
+fi
+
+MEDIA_DRIVER_VERSION="intel-media-25.2.6"
+GMMLIB_VERSION="intel-gmmlib-22.7.2"
+
+apt-get -qq update
+apt-get -qq install -y wget gnupg ca-certificates cmake g++ make pkg-config
+
+# Use Intel's jammy repo for newer libva-dev (2.22) which provides the
+# VVC/VVC-decode headers required by media-driver 25.x
+wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | gpg --yes --dearmor --output /usr/share/keyrings/intel-graphics.gpg
+echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy client" > /etc/apt/sources.list.d/intel-gpu-jammy.list
+apt-get -qq update
+apt-get -qq install -y libva-dev
+
+# Build gmmlib (required by media-driver)
+wget -qO gmmlib.tar.gz "https://github.com/intel/gmmlib/archive/refs/tags/${GMMLIB_VERSION}.tar.gz"
+mkdir /tmp/gmmlib
+tar -xf gmmlib.tar.gz -C /tmp/gmmlib --strip-components 1
+cmake -S /tmp/gmmlib -B /tmp/gmmlib/build -DCMAKE_BUILD_TYPE=Release
+make -C /tmp/gmmlib/build -j"$(nproc)"
+make -C /tmp/gmmlib/build install
+
+# Build intel-media-driver
+wget -qO media-driver.tar.gz "https://github.com/intel/media-driver/archive/refs/tags/${MEDIA_DRIVER_VERSION}.tar.gz"
+mkdir /tmp/media-driver
+tar -xf media-driver.tar.gz -C /tmp/media-driver --strip-components 1
+cmake -S /tmp/media-driver -B /tmp/media-driver/build \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DENABLE_KERNELS=ON \
+    -DENABLE_NONFREE_KERNELS=ON \
+    -DCMAKE_INSTALL_PREFIX=/usr \
+    -DCMAKE_INSTALL_LIBDIR=/usr/lib/x86_64-linux-gnu \
+    -DCMAKE_C_FLAGS="-Wno-error" \
+    -DCMAKE_CXX_FLAGS="-Wno-error"
+make -C /tmp/media-driver/build -j"$(nproc)"
+
+# Install driver to rootfs for COPY --from
+make -C /tmp/media-driver/build install DESTDIR=/rootfs

docker/main/install_deps.sh

@@ -87,38 +87,47 @@ if [[ "${TARGETARCH}" == "amd64" ]]; then
     # intel packages use zst compression so we need to update dpkg
     apt-get install -y dpkg
 
-    # use intel apt intel packages
+    # use intel apt repo for libmfx1 (legacy QSV, pre-Gen12)
     wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | gpg --yes --dearmor --output /usr/share/keyrings/intel-graphics.gpg
     echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy client" | tee /etc/apt/sources.list.d/intel-gpu-jammy.list
     apt-get -qq update
-    apt-get -qq install --no-install-recommends --no-install-suggests -y \
-        intel-media-va-driver-non-free libmfx1 libmfxgen1 libvpl2
 
+    # intel-media-va-driver-non-free is built from source in the
+    # intel-media-driver Dockerfile stage for Battlemage (Xe2) support
+    apt-get -qq install --no-install-recommends --no-install-suggests -y \
+        libmfx1
+    rm -f /usr/share/keyrings/intel-graphics.gpg
+    rm -f /etc/apt/sources.list.d/intel-gpu-jammy.list
+
+    # upgrade libva2, oneVPL runtime, and libvpl2 from trixie for Battlemage support
+    echo "deb http://deb.debian.org/debian trixie main" > /etc/apt/sources.list.d/trixie.list
+    apt-get -qq update
+    apt-get -qq install -y -t trixie libva2 libva-drm2 libzstd1
+    apt-get -qq install -y -t trixie libmfx-gen1.2 libvpl2
+    rm -f /etc/apt/sources.list.d/trixie.list
+    apt-get -qq update
     apt-get -qq install -y ocl-icd-libopencl1
 
     # install libtbb12 for NPU support
     apt-get -qq install -y libtbb12
 
-    rm -f /usr/share/keyrings/intel-graphics.gpg
-    rm -f /etc/apt/sources.list.d/intel-gpu-jammy.list
-
-    # install legacy and standard intel icd and level-zero-gpu
+    # install legacy and standard intel compute packages
     # see https://github.com/intel/compute-runtime/blob/master/LEGACY_PLATFORMS.md for more info
     # needed core package
-    wget https://github.com/intel/compute-runtime/releases/download/25.13.33276.19/libigdgmm12_22.7.0_amd64.deb
-    dpkg -i libigdgmm12_22.7.0_amd64.deb
-    rm libigdgmm12_22.7.0_amd64.deb
+    wget https://github.com/intel/compute-runtime/releases/download/26.14.37833.4/libigdgmm12_22.9.0_amd64.deb
+    dpkg -i libigdgmm12_22.9.0_amd64.deb
+    rm libigdgmm12_22.9.0_amd64.deb
 
-    # legacy packages
+    # legacy compute-runtime packages
     wget https://github.com/intel/compute-runtime/releases/download/24.35.30872.36/intel-opencl-icd-legacy1_24.35.30872.36_amd64.deb
     wget https://github.com/intel/compute-runtime/releases/download/24.35.30872.36/intel-level-zero-gpu-legacy1_1.5.30872.36_amd64.deb
     wget https://github.com/intel/intel-graphics-compiler/releases/download/igc-1.0.17537.24/intel-igc-opencl_1.0.17537.24_amd64.deb
     wget https://github.com/intel/intel-graphics-compiler/releases/download/igc-1.0.17537.24/intel-igc-core_1.0.17537.24_amd64.deb
-    # standard packages
-    wget https://github.com/intel/compute-runtime/releases/download/25.13.33276.19/intel-opencl-icd_25.13.33276.19_amd64.deb
-    wget https://github.com/intel/compute-runtime/releases/download/25.13.33276.19/intel-level-zero-gpu_1.6.33276.19_amd64.deb
-    wget https://github.com/intel/intel-graphics-compiler/releases/download/v2.10.10/intel-igc-opencl-2_2.10.10+18926_amd64.deb
-    wget https://github.com/intel/intel-graphics-compiler/releases/download/v2.10.10/intel-igc-core-2_2.10.10+18926_amd64.deb
+    # standard compute-runtime packages
+    wget https://github.com/intel/compute-runtime/releases/download/26.14.37833.4/intel-opencl-icd_26.14.37833.4-0_amd64.deb
+    wget https://github.com/intel/compute-runtime/releases/download/26.14.37833.4/libze-intel-gpu1_26.14.37833.4-0_amd64.deb
+    wget https://github.com/intel/intel-graphics-compiler/releases/download/v2.32.7/intel-igc-opencl-2_2.32.7+21184_amd64.deb
+    wget https://github.com/intel/intel-graphics-compiler/releases/download/v2.32.7/intel-igc-core-2_2.32.7+21184_amd64.deb
     # npu packages
     wget https://github.com/oneapi-src/level-zero/releases/download/v1.28.2/level-zero_1.28.2+u22.04_amd64.deb
     wget https://github.com/intel/linux-npu-driver/releases/download/v1.19.0/intel-driver-compiler-npu_1.19.0.20250707-16111289554_ubuntu22.04_amd64.deb
@@ -128,6 +137,10 @@ if [[ "${TARGETARCH}" == "amd64" ]]; then
     dpkg -i *.deb
     rm *.deb
     apt-get -qq install -f -y
+
+    # Battlemage uses the xe kernel driver, but the VA-API driver is still iHD.
+    # The oneVPL runtime may look for a driver named after the kernel module.
+    ln -sf /usr/lib/x86_64-linux-gnu/dri/iHD_drv_video.so /usr/lib/x86_64-linux-gnu/dri/xe_drv_video.so
 fi
 
 if [[ "${TARGETARCH}" == "arm64" ]]; then

docker/main/requirements-wheels.txt

@@ -5,13 +5,13 @@ aiohttp == 3.12.*
 starlette == 0.47.*
 starlette-context == 0.4.*
 fastapi[standard-no-fastapi-cloud-cli] == 0.116.*
-uvicorn == 0.35.*
+uvicorn == 0.46.*
 slowapi == 0.1.*
 joserfc == 1.2.*
 cryptography == 44.0.*
 pathvalidate == 3.3.*
 markupsafe == 3.0.*
-python-multipart == 0.0.20
+python-multipart == 0.0.26
 # Classification Model Training
 tensorflow == 2.19.* ; platform_machine == 'aarch64'
 tensorflow-cpu == 2.19.* ; platform_machine == 'x86_64'
@@ -42,7 +42,7 @@ opencv-python-headless == 4.11.0.*
 opencv-contrib-python == 4.11.0.*
 scipy == 1.16.*
 # OpenVino & ONNX
-openvino == 2025.3.*
+openvino == 2025.4.*
 onnxruntime == 1.22.*
 # Embeddings
 transformers == 4.45.*

docker/main/rootfs/usr/local/go2rtc/create_config.py

@@ -9,6 +9,7 @@ from typing import Any
 from ruamel.yaml import YAML
 
 sys.path.insert(0, "/opt/frigate")
+from frigate.config.env import substitute_frigate_vars
 from frigate.const import (
     BIRDSEYE_PIPE,
     DEFAULT_FFMPEG_VERSION,
@@ -47,14 +48,6 @@ ALLOW_ARBITRARY_EXEC = allow_arbitrary_exec is not None and str(
     allow_arbitrary_exec
 ).lower() in ("true", "1", "yes")
 
-FRIGATE_ENV_VARS = {k: v for k, v in os.environ.items() if k.startswith("FRIGATE_")}
-# read docker secret files as env vars too
-if os.path.isdir("/run/secrets"):
-    for secret_file in os.listdir("/run/secrets"):
-        if secret_file.startswith("FRIGATE_"):
-            FRIGATE_ENV_VARS[secret_file] = (
-                Path(os.path.join("/run/secrets", secret_file)).read_text().strip()
-            )
 
 config_file = find_config_file()
 
@@ -103,13 +96,13 @@ if go2rtc_config["webrtc"].get("candidates") is None:
     go2rtc_config["webrtc"]["candidates"] = default_candidates
 
 if go2rtc_config.get("rtsp", {}).get("username") is not None:
-    go2rtc_config["rtsp"]["username"] = go2rtc_config["rtsp"]["username"].format(
-        **FRIGATE_ENV_VARS
+    go2rtc_config["rtsp"]["username"] = substitute_frigate_vars(
+        go2rtc_config["rtsp"]["username"]
     )
 
 if go2rtc_config.get("rtsp", {}).get("password") is not None:
-    go2rtc_config["rtsp"]["password"] = go2rtc_config["rtsp"]["password"].format(
-        **FRIGATE_ENV_VARS
+    go2rtc_config["rtsp"]["password"] = substitute_frigate_vars(
+        go2rtc_config["rtsp"]["password"]
     )
 
 # ensure ffmpeg path is set correctly
@@ -145,7 +138,7 @@ for name in list(go2rtc_config.get("streams", {})):
 
     if isinstance(stream, str):
         try:
-            formatted_stream = stream.format(**FRIGATE_ENV_VARS)
+            formatted_stream = substitute_frigate_vars(stream)
             if not ALLOW_ARBITRARY_EXEC and is_restricted_source(formatted_stream):
                 print(
                     f"[ERROR] Stream '{name}' uses a restricted source (echo/expr/exec) which is disabled by default for security. "
@@ -164,7 +157,7 @@ for name in list(go2rtc_config.get("streams", {})):
         filtered_streams = []
         for i, stream_item in enumerate(stream):
             try:
-                formatted_stream = stream_item.format(**FRIGATE_ENV_VARS)
+                formatted_stream = substitute_frigate_vars(stream_item)
                 if not ALLOW_ARBITRARY_EXEC and is_restricted_source(formatted_stream):
                     print(
                         f"[ERROR] Stream '{name}' item {i + 1} uses a restricted source (echo/expr/exec) which is disabled by default for security. "

docker/rocm/Dockerfile

@@ -32,11 +32,14 @@ RUN echo /opt/rocm/lib|tee /opt/rocm-dist/etc/ld.so.conf.d/rocm.conf
 FROM deps AS deps-prelim
 
 COPY docker/rocm/debian-backports.sources /etc/apt/sources.list.d/debian-backports.sources
-RUN apt-get update && \
+# install_deps.sh upgraded libstdc++6 from trixie for Battlemage; the matching
+# -dev package must also come from trixie or apt refuses to satisfy it.
+RUN echo "deb http://deb.debian.org/debian trixie main" > /etc/apt/sources.list.d/trixie.list && \
+    apt-get update && \
     apt-get install -y libnuma1 && \
     apt-get install -qq -y -t bookworm-backports mesa-va-drivers mesa-vulkan-drivers && \
-    # Install C++ standard library headers for HIPRTC kernel compilation fallback
-    apt-get install -qq -y libstdc++-12-dev && \
+    apt-get install -qq -y -t trixie libstdc++-14-dev && \
+    rm -f /etc/apt/sources.list.d/trixie.list && \
     rm -rf /var/lib/apt/lists/*
 
 WORKDIR /opt/frigate

docs/docs/configuration/audio_detectors.md

@@ -119,6 +119,12 @@ audio:
 
 Frigate supports fully local audio transcription using either `sherpa-onnx` or OpenAI's open-source Whisper models via `faster-whisper`. The goal of this feature is to support Semantic Search for `speech` audio events. Frigate is not intended to act as a continuous, fully-automatic speech transcription service — automatically transcribing all speech (or queuing many audio events for transcription) requires substantial CPU (or GPU) resources and is impractical on most systems. For this reason, transcriptions for events are initiated manually from the UI or the API rather than being run continuously in the background.
 
+:::info
+
+Audio transcription requires a one-time internet connection to download the Whisper or Sherpa-ONNX model on first use. Once cached, transcription runs fully offline. See [Network Requirements](/frigate/network_requirements#one-time-model-downloads) for details.
+
+:::
+
 Transcription accuracy also depends heavily on the quality of your camera's microphone and recording conditions. Many cameras use inexpensive microphones, and distance to the speaker, low audio bitrate, or background noise can significantly reduce transcription quality. If you need higher accuracy, more robust long-running queues, or large-scale automatic transcription, consider using the HTTP API in combination with an automation platform and a cloud transcription service.
 
 #### Configuration

docs/docs/configuration/bird_classification.md

@@ -9,6 +9,12 @@ import NavPath from "@site/src/components/NavPath";
 
 Bird classification identifies known birds using a quantized Tensorflow model. When a known bird is recognized, its common name will be added as a `sub_label`. This information is included in the UI, filters, as well as in notifications.
 
+:::info
+
+Bird classification requires a one-time internet connection to download the classification model and label map from GitHub. Once cached, models work fully offline. See [Network Requirements](/frigate/network_requirements#one-time-model-downloads) for details.
+
+:::
+
 ## Minimum System Requirements
 
 Bird classification runs a lightweight tflite model on the CPU, there are no significantly different system requirements than running Frigate itself.

docs/docs/configuration/custom_classification/object_classification.md

@@ -9,6 +9,12 @@ import NavPath from "@site/src/components/NavPath";
 
 Object classification allows you to train a custom MobileNetV2 classification model to run on tracked objects (persons, cars, animals, etc.) to identify a finer category or attribute for that object. Classification results are visible in the Tracked Object Details pane in Explore, through the `frigate/tracked_object_details` MQTT topic, in Home Assistant sensors via the official Frigate integration, or through the event endpoints in the HTTP API.
 
+:::info
+
+Training a custom object classification model requires a one-time internet connection to download MobileNetV2 base weights. Once trained, the model runs fully offline. See [Network Requirements](/frigate/network_requirements#one-time-model-downloads) for details.
+
+:::
+
 ## Minimum System Requirements
 
 Object classification models are lightweight and run very fast on CPU.
@@ -158,7 +164,7 @@ Enable debug logs for classification models by adding `frigate.data_processing.r
 Navigate to <NavPath path="Settings > System > Logging" />.
 
 - Set **Logging level** to `debug`
-- Set **Per-process log level > Frigate.Data Processing.Real Time.Custom Classification** to `debug` for verbose classification logging
+- Set **Per-process log level > `frigate.data_processing.real_time.custom_classification`** to `debug` for verbose classification logging
 
 </TabItem>
 <TabItem value="yaml">

docs/docs/configuration/custom_classification/state_classification.md

@@ -9,6 +9,12 @@ import NavPath from "@site/src/components/NavPath";
 
 State classification allows you to train a custom MobileNetV2 classification model on a fixed region of your camera frame(s) to determine a current state. The model can be configured to run on a schedule and/or when motion is detected in that region. Classification results are available through the `frigate/<camera_name>/classification/<model_name>` MQTT topic and in Home Assistant sensors via the official Frigate integration.
 
+:::info
+
+Training a custom state classification model requires a one-time internet connection to download MobileNetV2 base weights. Once trained, the model runs fully offline. See [Network Requirements](/frigate/network_requirements#one-time-model-downloads) for details.
+
+:::
+
 ## Minimum System Requirements
 
 State classification models are lightweight and run very fast on CPU.

docs/docs/configuration/face_recognition.md

@@ -9,6 +9,12 @@ import NavPath from "@site/src/components/NavPath";
 
 Face recognition identifies known individuals by matching detected faces with previously learned facial data. When a known `person` is recognized, their name will be added as a `sub_label`. This information is included in the UI, filters, as well as in notifications.
 
+:::info
+
+Face recognition requires a one-time internet connection to download detection and embedding models from GitHub. Once cached, models work fully offline. See [Network Requirements](/frigate/network_requirements#one-time-model-downloads) for details.
+
+:::
+
 ## Model Requirements
 
 ### Face Detection
@@ -165,7 +171,7 @@ When choosing images to include in the face training set it is recommended to al
 - If it is difficult to make out details in a persons face it will not be helpful in training.
 - Avoid images with extreme under/over-exposure.
 - Avoid blurry / pixelated images.
-- Avoid training on infrared (gray-scale). The models are trained on color images and will be able to extract features from gray-scale images.
+- Avoid training on infrared (gray-scale). The models are trained on color images and will not be able to extract features from gray-scale images.
 - Using images of people wearing hats / sunglasses may confuse the model.
 - Do not upload too many similar images at the same time, it is recommended to train no more than 4-6 similar images for each person to avoid over-fitting.
 

docs/docs/configuration/genai/config.md

@@ -193,6 +193,12 @@ To use a different OpenAI-compatible API endpoint, set the `OPENAI_BASE_URL` env
 
 Cloud providers run on remote infrastructure and require an API key for authentication. These services handle all model inference on their servers.
 
+:::info
+
+Cloud Generative AI providers require an active internet connection to send images and prompts for processing. Local providers like llama.cpp and Ollama (with local models) do not require internet. See [Network Requirements](/frigate/network_requirements#generative-ai) for details.
+
+:::
+
 ### Ollama Cloud
 
 Ollama also supports [cloud models](https://ollama.com/cloud), where your local Ollama instance handles requests from Frigate, but model inference is performed in the cloud. Set up Ollama locally, sign in with your Ollama account, and specify the cloud model name in your Frigate config. For more details, see the Ollama cloud model [docs](https://docs.ollama.com/cloud).

docs/docs/configuration/hardware_acceleration_video.md

@@ -59,13 +59,14 @@ Frigate can utilize most Intel integrated GPUs and Arc GPUs to accelerate video
 
 **Recommended hwaccel Preset**
 
-| CPU Generation | Intel Driver | Recommended Preset  | Notes                                       |
-| -------------- | ------------ | ------------------- | ------------------------------------------- |
-| gen1 - gen5    | i965         | preset-vaapi        | qsv is not supported, may not support H.265 |
-| gen6 - gen7    | iHD          | preset-vaapi        | qsv is not supported                        |
-| gen8 - gen12   | iHD          | preset-vaapi        | preset-intel-qsv-\* can also be used        |
-| gen13+         | iHD / Xe     | preset-intel-qsv-\* |                                             |
-| Intel Arc GPU  | iHD / Xe     | preset-intel-qsv-\* |                                             |
+| CPU Generation     | Intel Driver | Recommended Preset  | Notes                                       |
+| ------------------ | ------------ | ------------------- | ------------------------------------------- |
+| gen1 - gen5        | i965         | preset-vaapi        | qsv is not supported, may not support H.265 |
+| gen6 - gen7        | iHD          | preset-vaapi        | qsv is not supported                        |
+| gen8 - gen12       | iHD          | preset-vaapi        | preset-intel-qsv-\* can also be used        |
+| gen13+             | iHD / Xe     | preset-intel-qsv-\* |                                             |
+| Intel Arc A-series | iHD / Xe     | preset-intel-qsv-\* |                                             |
+| Intel Arc B-series | iHD / Xe     | preset-intel-qsv-\* | Requires host kernel 6.12+                  |
 
 :::
 

docs/docs/configuration/license_plate_recognition.md

@@ -11,6 +11,12 @@ Frigate can recognize license plates on vehicles and automatically add the detec
 
 LPR works best when the license plate is clearly visible to the camera. For moving vehicles, Frigate continuously refines the recognition process, keeping the most confident result. When a vehicle becomes stationary, LPR continues to run for a short time after to attempt recognition.
 
+:::info
+
+License plate recognition requires a one-time internet connection to download OCR and detection models from GitHub. Once cached, models work fully offline. See [Network Requirements](/frigate/network_requirements#one-time-model-downloads) for details.
+
+:::
+
 When a plate is recognized, the details are:
 
 - Added as a `sub_label` (if [known](#matching)) or the `recognized_license_plate` field (if unknown) to a tracked object.

docs/docs/configuration/live.md

@@ -21,6 +21,12 @@ The jsmpeg live view will use more browser and client GPU resources. Using go2rt
 | mse    | native                                | native     | yes (depends on audio codec) | yes             | iPhone requires iOS 17.1+, Firefox is h.264 only. This is Frigate's default when go2rtc is configured.                                                              |
 | webrtc | native                                | native     | yes (depends on audio codec) | yes             | Requires extra configuration. Frigate attempts to use WebRTC when MSE fails or when using a camera's two-way talk feature.                                          |
 
+:::info
+
+WebRTC may use an external STUN server for NAT traversal. MSE and HLS streaming do not require any internet access. See [Network Requirements](/frigate/network_requirements#webrtc-stun) for details.
+
+:::
+
 ### Camera Settings Recommendations
 
 If you are using go2rtc, you should adjust the following settings in your camera's firmware for the best experience with Live view:

docs/docs/configuration/notifications.md

@@ -11,6 +11,12 @@ import NavPath from "@site/src/components/NavPath";
 
 Frigate offers native notifications using the [WebPush Protocol](https://web.dev/articles/push-notifications-web-push-protocol) which uses the [VAPID spec](https://tools.ietf.org/html/draft-thomson-webpush-vapid) to deliver notifications to web apps using encryption.
 
+:::info
+
+Push notifications require internet access from the Frigate server to the browser vendor's push service (e.g., Google FCM, Mozilla autopush). See [Network Requirements](/frigate/network_requirements#push-notifications) for details.
+
+:::
+
 ## Setting up Notifications
 
 In order to use notifications the following requirements must be met:

docs/docs/configuration/object_detectors.md

@@ -288,6 +288,12 @@ This detector is available for use with both Hailo-8 and Hailo-8L AI Acceleratio
 
 See the [installation docs](../frigate/installation.md#hailo-8) for information on configuring the Hailo hardware.
 
+:::info
+
+If no custom model is provided, the Hailo detector downloads a default model from the Hailo Model Zoo on first startup. Once cached, the model works fully offline. See [Network Requirements](/frigate/network_requirements#hardware-specific-detector-models) for details.
+
+:::
+
 ### Configuration
 
 When configuring the Hailo detector, you have two options to specify the model: a local **path** or a **URL**.
@@ -1793,6 +1799,12 @@ Hardware accelerated object detection is supported on the following SoCs:
 
 This implementation uses the [Rockchip's RKNN-Toolkit2](https://github.com/airockchip/rknn-toolkit2/), version v2.3.2.
 
+:::info
+
+If no custom model is provided, the RKNN detector downloads a default model from GitHub on first startup. Once cached, the model works fully offline. See [Network Requirements](/frigate/network_requirements#hardware-specific-detector-models) for details.
+
+:::
+
 :::tip
 
 When using many cameras one detector may not be enough to keep up. Multiple detectors can be defined assuming NPU resources are available. An example configuration would be:
@@ -2176,6 +2188,12 @@ This implementation uses the [AXera Pulsar2 Toolchain](https://huggingface.co/AX
 
 See the [installation docs](../frigate/installation.md#axera) for information on configuring the AXEngine hardware.
 
+:::info
+
+The AXEngine detector downloads its default model from HuggingFace on first startup. Once cached, the model works fully offline. See [Network Requirements](/frigate/network_requirements#hardware-specific-detector-models) for details.
+
+:::
+
 ### Configuration
 
 When configuring the AXEngine detector, you have to specify the model name.

docs/docs/configuration/object_filters.md

@@ -24,6 +24,12 @@ For object filters, any single detection below `min_score` will be ignored as a
 
 In frame 2, the score is below the `min_score` value, so Frigate ignores it and it becomes a 0.0. The computed score is the median of the score history (padding to at least 3 values), and only when that computed score crosses the `threshold` is the object marked as a true positive. That happens in frame 4 in the example.
 
+The **top score** is the highest computed score the tracked object has ever reached during its lifetime. Because the computed score rises and falls as new frames come in, the top score can be thought of as the peak confidence Frigate had in the object. In Frigate's UI (such as the Tracking Details pane in Explore), you may see all three values:
+
+- **Score** — the raw detector score for that single frame.
+- **Computed Score** — the median of the most recent score history at that moment. This is the value compared against `threshold`.
+- **Top Score** — the highest computed score reached so far for the tracked object.
+
 ### Minimum Score
 
 Any detection below `min_score` will be immediately thrown out and never tracked because it is considered a false positive. If `min_score` is too low then false positives may be detected and tracked which can confuse the object tracker and may lead to wasted resources. If `min_score` is too high then lower scoring true positives like objects that are further away or partially occluded may be thrown out which can also confuse the tracker and cause valid tracked objects to be lost or disjointed.

docs/docs/configuration/profiles.md

@@ -20,7 +20,7 @@ When a profile is activated, Frigate merges each camera's profile overrides on t
 
 :::info
 
-Profile changes are applied in-memory and take effect immediately — no restart is required. The active profile is persisted across Frigate restarts (stored in the `/config/.active_profile` file).
+Profile changes are applied in-memory and take effect immediately — no restart is required. The active profile is persisted across Frigate restarts (stored in the `/config/.profiles` file).
 
 :::
 
@@ -130,14 +130,14 @@ Profiles can be activated and deactivated from the Frigate UI. Open the Settings
 
 ## Example: Home / Away Setup
 
-A common use case is having different detection and notification settings based on whether you are home or away.
+A common use case is having different detection and notification settings based on whether you are home or away. This example below is for a system with two cameras, `front_door` and `indoor_cam`.
 
 <ConfigTabs>
 <TabItem value="ui">
 
 1. Navigate to <NavPath path="Settings > Camera configuration > Profiles" /> and create two profiles: **Home** and **Away**.
-2. For the **front_door** camera, configure the **Away** profile to enable notifications and set alert labels to `person` and `car`. Configure the **Home** profile to disable notifications.
-3. For the **indoor_cam** camera, configure the **Away** profile to enable the camera, detection, and recording. Configure the **Home** profile to disable the camera entirely for privacy.
+2. From to the Camera configuration section in Settings, choose the **front_door** camera, and select the **Away** profile from the profile dropdown. Then, enable notifications from the Notifications pane, and set alert labels to `person` and `car` from the Review pane. Then, from the profile dropdown choose **Home** profile, then navigate to Notifications to disable notifications.
+3. For the **indoor_cam** camera, perform similar steps - configure the **Away** profile to enable the camera, detection, and recording. Configure the **Home** profile to disable the camera entirely for privacy.
 4. Activate the desired profile from <NavPath path="Settings > Camera configuration > Profiles" /> or from the **Profiles** option in Frigate's main menu.
 
 </TabItem>

docs/docs/configuration/record.md

@@ -123,6 +123,76 @@ record:
 </TabItem>
 </ConfigTabs>
 
+## Pre-capture and Post-capture
+
+The `pre_capture` and `post_capture` settings control how many seconds of video are included before and after an alert or detection. These can be configured independently for alerts and detections, and can be set globally or overridden per camera.
+
+<ConfigTabs>
+<TabItem value="ui">
+
+Navigate to <NavPath path="Settings > Global configuration > Recording" /> for global defaults, or <NavPath path="Settings > Camera configuration > (select camera) > Recording" /> to override for a specific camera.
+
+| Field                                          | Description                                          |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| **Alert retention > Pre-capture seconds**      | Seconds of video to include before an alert event    |
+| **Alert retention > Post-capture seconds**     | Seconds of video to include after an alert event     |
+| **Detection retention > Pre-capture seconds**  | Seconds of video to include before a detection event |
+| **Detection retention > Post-capture seconds** | Seconds of video to include after a detection event  |
+
+</TabItem>
+<TabItem value="yaml">
+
+```yaml
+record:
+  enabled: True
+  alerts:
+    pre_capture: 5 # seconds before the alert to include
+    post_capture: 5 # seconds after the alert to include
+  detections:
+    pre_capture: 5 # seconds before the detection to include
+    post_capture: 5 # seconds after the detection to include
+```
+
+</TabItem>
+</ConfigTabs>
+
+- **Default**: 5 seconds for both pre and post capture.
+- **Pre-capture maximum**: 60 seconds.
+- These settings apply per review category (alerts and detections), not per object type.
+
+### How pre/post capture interacts with retention mode
+
+The `pre_capture` and `post_capture` values define the **time window** around a review item, but only recording segments that also match the configured **retention mode** are actually kept on disk.
+
+- **`mode: all`** — Retains every segment within the capture window, regardless of whether motion was detected.
+- **`mode: motion`** (default) — Only retains segments within the capture window that contain motion. This includes segments with active tracked objects, since object motion implies motion. Segments without any motion are discarded even if they fall within the pre/post capture range.
+- **`mode: active_objects`** — Only retains segments within the capture window where tracked objects were actively moving. Segments with general motion but no active objects are discarded.
+
+This means that with the default `motion` mode, you may see less footage than the configured pre/post capture duration if parts of the capture window had no motion.
+
+To guarantee the full pre/post capture duration is always retained:
+
+```yaml
+record:
+  enabled: True
+  alerts:
+    pre_capture: 10
+    post_capture: 10
+    retain:
+      days: 30
+      mode: all # retains all segments within the capture window
+```
+
+:::note
+
+Because recording segments are written in 10 second chunks, pre-capture timing depends on segment boundaries. The actual pre-capture footage may be slightly shorter or longer than the exact configured value.
+
+:::
+
+### Where to view pre/post capture footage
+
+Pre and post capture footage is included in the **recording timeline**, visible in the History view. Note that pre/post capture settings only affect which recording segments are **retained on disk** — they do not change the start and end points shown in the UI. The History view will still center on the review item's actual time range, but you can scrub backward and forward through the retained pre/post capture footage on the timeline. The Explore view shows object-specific clips that are trimmed to when the tracked object was actually visible, so pre/post capture time will not be reflected there.
+
 ## Will Frigate delete old recordings if my storage runs out?
 
 As of Frigate 0.12 if there is less than an hour left of storage, the oldest 2 hours of recordings will be deleted.
@@ -211,31 +281,52 @@ Using Frigate UI, Home Assistant, or MQTT, cameras can be automated to only reco
 
 Footage can be exported from Frigate by right-clicking (desktop) or long pressing (mobile) on a review item in the Review pane or by clicking the Export button in the History view. Exported footage is then organized and searchable through the Export view, accessible from the main navigation bar.
 
-### Time-lapse export
+### Custom export with FFmpeg arguments
 
-Time lapse exporting is available only via the [HTTP API](../integrations/api/export-recording-export-camera-name-start-start-time-end-end-time-post.api.mdx).
+For advanced use cases, the [custom export HTTP API](../integrations/api/export-recording-custom-export-custom-camera-name-start-start-time-end-end-time-post.api.mdx) lets you pass custom FFmpeg arguments when exporting a recording:
 
-When exporting a time-lapse the default speed-up is 25x with 30 FPS. This means that every 25 seconds of (real-time) recording is condensed into 1 second of time-lapse video (always without audio) with a smoothness of 30 FPS.
-
-To configure the speed-up factor, the frame rate and further custom settings, use the `timelapse_args` parameter. The below configuration example would change the time-lapse speed to 60x (for fitting 1 hour of recording into 1 minute of time-lapse) with 25 FPS:
-
-```yaml {3-4}
-record:
-  enabled: True
-  export:
-    timelapse_args: "-vf setpts=PTS/60 -r 25"
+```
+POST /export/custom/{camera_name}/start/{start_time}/end/{end_time}
 ```
 
-:::tip
+The request body accepts `ffmpeg_input_args` and `ffmpeg_output_args` to control encoding, frame rate, filters, and other FFmpeg options. If neither is provided, Frigate defaults to time-lapse output settings (25x speed, 30 FPS).
 
-When using `hwaccel_args`, hardware encoding is used for timelapse generation. This setting can be overridden for a specific camera (e.g., when camera resolution exceeds hardware encoder limits); set the camera-level export hwaccel_args with the appropriate settings. Using an unrecognized value or empty string will fall back to software encoding (libx264).
+The following example exports a time-lapse at 60x speed with 25 FPS:
+
+```json
+{
+  "name": "Front Door Time-lapse",
+  "ffmpeg_output_args": "-vf setpts=PTS/60 -r 25"
+}
+```
+
+#### CPU fallback
+
+If hardware acceleration is configured and the export fails (e.g., the GPU is unavailable), set `cpu_fallback: true` in the request body to automatically retry using software encoding.
+
+```json
+{
+  "name": "My Export",
+  "ffmpeg_output_args": "-c:v libx264 -crf 23",
+  "cpu_fallback": true
+}
+```
+
+:::note
+
+Non-admin users are restricted from using FFmpeg arguments that can access the filesystem (e.g., `-filter_complex`, file paths, and protocol references). Admin users have full control over FFmpeg arguments.
 
 :::
 
 :::tip
 
-The encoder determines its own behavior so the resulting file size may be undesirably large.
-To reduce the output file size the ffmpeg parameter `-qp n` can be utilized (where `n` stands for the value of the quantisation parameter). The value can be adjusted to get an acceptable tradeoff between quality and file size for the given scenario.
+When `hwaccel_args` is configured, hardware encoding is used for exports. This can be overridden per camera (e.g., when camera resolution exceeds hardware encoder limits) by setting a camera-level `hwaccel_args`. Using an unrecognized value or empty string falls back to software encoding (libx264).
+
+:::
+
+:::tip
+
+To reduce output file size, add the FFmpeg parameter `-qp n` to `ffmpeg_output_args` (where `n` is the quantization parameter). Adjust the value to balance quality and file size for your scenario.
 
 :::
 

docs/docs/configuration/semantic_search.md

@@ -13,6 +13,12 @@ Frigate uses models from [Jina AI](https://huggingface.co/jinaai) to create and
 
 Semantic Search is accessed via the _Explore_ view in the Frigate UI.
 
+:::info
+
+Semantic search requires a one-time internet connection to download embedding models from HuggingFace. Once cached, models work fully offline. See [Network Requirements](/frigate/network_requirements#one-time-model-downloads) for details.
+
+:::
+
 ## Minimum System Requirements
 
 Semantic Search works by running a large AI model locally on your system. Small or underpowered systems like a Raspberry Pi will not run Semantic Search reliably or at all.

docs/docs/frigate/hardware.md

@@ -146,17 +146,11 @@ A single Coral can handle many cameras using the default model and will be suffi
 The OpenVINO detector type is able to run on:
 
 - 6th Gen Intel Platforms and newer that have an iGPU
-- x86 hosts with an Intel Arc GPU
+- x86 hosts with an Intel Arc GPU (including Arc A-series and B-series Battlemage)
 - Intel NPUs
 - Most modern AMD CPUs (though this is officially not supported by Intel)
 - x86 & Arm64 hosts via CPU (generally not recommended)
 
-:::note
-
-Intel B-series (Battlemage) GPUs are not officially supported with Frigate 0.17, though a user has [provided steps to rebuild the Frigate container](https://github.com/blakeblackshear/frigate/discussions/21257) with support for them.
-
-:::
-
 More information is available [in the detector docs](/configuration/object_detectors#openvino-detector)
 
 Inference speeds vary greatly depending on the CPU or GPU used, some known examples of GPU inference times are below:

docs/docs/frigate/installation.md

@@ -482,7 +482,8 @@ services:
       - /dev/apex_0:/dev/apex_0 # Passes a PCIe Coral, follow driver instructions here https://github.com/jnicolson/gasket-builder
       - /dev/video11:/dev/video11 # For Raspberry Pi 4B
       - /dev/dri/renderD128:/dev/dri/renderD128 # AMD / Intel GPU, needs to be updated for your hardware
-      - /dev/accel:/dev/accel # Intel NPU
+      - /dev/kfd:/dev/kfd # AMD Kernel Fusion Driver for ROCm
+      - /dev/accel:/dev/accel # AMD / Intel NPU
     volumes:
       - /etc/localtime:/etc/localtime:ro
       - /path/to/your/config:/config

docs/docs/frigate/network_requirements.md

@@ -0,0 +1,155 @@
+---
+id: network_requirements
+title: Network Requirements
+---
+
+# Network Requirements
+
+Frigate is designed to run locally and does not require a persistent internet connection for core functionality. However, certain features need internet access for initial setup or ongoing operation. This page describes what connects to the internet, when, and how to control it.
+
+## How Frigate Uses the Internet
+
+Frigate's internet usage falls into three categories:
+
+1. **One-time model downloads** — ML models are downloaded the first time a feature is enabled, then cached locally. No internet is needed on subsequent startups.
+2. **Optional cloud services** — Features like Frigate+ and Generative AI connect to external APIs only when explicitly configured.
+3. **Build-time dependencies** — Components bundled into the Docker image during the build process. These require no internet at runtime.
+
+:::tip
+
+After initial setup, Frigate can run fully offline as long as all required models have been downloaded and no cloud-dependent features are enabled.
+
+:::
+
+## One-Time Model Downloads
+
+The following models are downloaded automatically the first time their associated feature is enabled. Once cached in `/config/model_cache/`, they do not require internet again.
+
+| Feature                                                                                       | Models Downloaded                                                          | Source               |
+| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------- |
+| [Semantic search](/configuration/semantic_search)                                             | Jina CLIP v1 or v2 (ONNX) + tokenizer                                      | HuggingFace          |
+| [Face recognition](/configuration/face_recognition)                                           | FaceNet, ArcFace, face detection model                                     | GitHub               |
+| [License plate recognition](/configuration/license_plate_recognition)                         | PaddleOCR (detection, classification, recognition) + YOLOv9 plate detector | GitHub               |
+| [Bird classification](/configuration/bird_classification)                                     | MobileNetV2 bird model + label map                                         | GitHub               |
+| [Custom classification](/configuration/custom_classification/state_classification) (training) | MobileNetV2 ImageNet base weights (via Keras)                              | Google storage       |
+| [Audio transcription](/configuration/advanced)                                                | Whisper or Sherpa-ONNX streaming model                                     | HuggingFace / OpenAI |
+
+### Hardware-Specific Detector Models
+
+If you are using one of the following hardware detectors and have not provided your own model file, a default model will be downloaded on first startup:
+
+| Detector                                                           | Model Downloaded     | Source                   |
+| ------------------------------------------------------------------ | -------------------- | ------------------------ |
+| [Rockchip RKNN](/configuration/object_detectors#rockchip-platform) | RKNN detection model | GitHub                   |
+| [Hailo 8 / 8L](/configuration/object_detectors#hailo-8)            | YOLOv6n (.hef)       | Hailo Model Zoo (AWS S3) |
+| [AXERA AXEngine](/configuration/object_detectors)                  | Detection model      | HuggingFace              |
+
+:::note
+
+The default CPU, EdgeTPU, and OpenVINO object detection models are bundled into the Docker image and do not require any download at runtime.
+
+:::
+
+### Preventing Model Downloads
+
+If you have already downloaded all required models and want to prevent Frigate from attempting any outbound connections to HuggingFace or the Transformers library, set the following environment variables on your Frigate container:
+
+```yaml
+environment:
+  HF_HUB_OFFLINE: "1"
+  TRANSFORMERS_OFFLINE: "1"
+```
+
+:::warning
+
+Setting these variables without having the correct model files already cached in `/config/model_cache/` will cause failures. Only use these after a successful initial setup with internet access.
+
+:::
+
+### Mirror Support
+
+If your Frigate instance has restricted internet access, you can point model downloads at internal mirrors using environment variables:
+
+| Environment Variable                | Default                             | Used By                                       |
+| ----------------------------------- | ----------------------------------- | --------------------------------------------- |
+| `HF_ENDPOINT`                       | `https://huggingface.co`            | Semantic search, Sherpa-ONNX, AXEngine models |
+| `GITHUB_ENDPOINT`                   | `https://github.com`                | Face recognition, LPR, RKNN models            |
+| `GITHUB_RAW_ENDPOINT`               | `https://raw.githubusercontent.com` | Bird classification                           |
+| `TF_KERAS_MOBILENET_V2_WEIGHTS_URL` | Google storage (Keras default)      | Custom classification training                |
+
+## Optional Cloud Services
+
+These features connect to external services during normal operation and require internet whenever they are active.
+
+### Frigate+
+
+When a Frigate+ API key is configured, Frigate communicates with `https://api.frigate.video` to download models, upload snapshots for training, submit annotations, and report false positives. Remove the API key to disable all Frigate+ network activity.
+
+See [Frigate+](/integrations/plus) for details.
+
+### Generative AI
+
+When a Generative AI provider is configured, Frigate sends images and prompts to the configured provider for event descriptions, chat, and camera monitoring. Available providers:
+
+| Provider      | Internet Required                                                |
+| ------------- | ---------------------------------------------------------------- |
+| OpenAI        | Yes — connects to OpenAI API (or custom base URL)                |
+| Google Gemini | Yes — connects to Google Generative AI API                       |
+| Azure OpenAI  | Yes — connects to your Azure endpoint                            |
+| Ollama        | Depends — typically local (`localhost:11434`), but can be remote |
+| llama.cpp     | No — runs entirely locally                                       |
+
+Disable Generative AI by removing the `genai` configuration from your cameras. See [Generative AI](/configuration/genai/genai_config) for details.
+
+### Version Check
+
+Frigate checks GitHub for the latest release version on startup by querying `https://api.github.com`. This can be disabled:
+
+```yaml
+telemetry:
+  version_check: false
+```
+
+### Push Notifications
+
+When [notifications](/configuration/notifications) are enabled and users have registered for push notifications in the web UI, Frigate sends push messages through the browser vendor's push service (e.g., Google FCM, Mozilla autopush). This requires internet access from the Frigate server to these push endpoints.
+
+### MQTT
+
+If an [MQTT broker](/integrations/mqtt) is configured, Frigate maintains a connection to the broker's host and port. This is typically a local network connection, but will require internet if you use a cloud-hosted MQTT broker.
+
+### DeepStack / CodeProject.AI
+
+When using the [DeepStack detector plugin](/configuration/object_detectors), Frigate sends images to the configured API endpoint for inference. This is typically local but depends on where the service is hosted.
+
+## WebRTC (STUN)
+
+For [WebRTC live streaming](/configuration/live), Frigate uses STUN for NAT traversal:
+
+- **go2rtc** defaults to a local STUN listener (`stun:8555`) — no internet required.
+- **The web UI's WebRTC player** includes a fallback to Google's public STUN server (`stun:stun.l.google.com:19302`), which requires internet.
+
+## Home Assistant Supervisor
+
+When running as a Home Assistant add-on, the go2rtc startup script queries the local Supervisor API (`http://supervisor/`) to discover the host IP address and WebRTC port. This is a local network call to the Home Assistant host, not an internet connection.
+
+## What Does NOT Require Internet
+
+- **Object detection** — CPU, EdgeTPU, OpenVINO, and other bundled detector models are included in the Docker image.
+- **Recording and playback** — All video is stored and served locally.
+- **Live streaming** — Camera streams are pulled over your local network. MSE and HLS streaming work without any external connections.
+- **The web interface** — Fully self-contained with no external fonts, scripts, analytics, or CDN dependencies. All translations are bundled locally.
+- **Custom classification inference** — After training, custom models run entirely locally.
+- **Audio detection** — The YAMNet audio classification model is bundled in the Docker image.
+
+## Running Frigate Offline
+
+To run Frigate in an air-gapped or offline environment:
+
+1. **Pre-download models** — Start Frigate with internet access once with all desired features enabled. Models will be cached in `/config/model_cache/`.
+2. **Disable version check** — Set `telemetry.version_check: false` in your configuration.
+3. **Block outbound model requests** — Set the `HF_HUB_OFFLINE=1` and `TRANSFORMERS_OFFLINE=1` environment variables to prevent HuggingFace and Transformers from attempting any network requests.
+4. **Avoid cloud features** — Do not configure Frigate+, Generative AI providers that require internet, or cloud MQTT brokers.
+5. **Use local model mirrors** — If limited internet is available, set the `HF_ENDPOINT`, `GITHUB_ENDPOINT`, and `GITHUB_RAW_ENDPOINT` environment variables to point to local mirrors.
+
+After these steps, Frigate will operate with no outbound internet connections.

docs/docs/integrations/mqtt.md

@@ -5,6 +5,12 @@ title: MQTT
 
 These are the MQTT messages generated by Frigate. The default topic_prefix is `frigate`, but can be changed in the config file.
 
+:::info
+
+MQTT requires a network connection to your broker. This is typically local, but will require internet if using a cloud-hosted MQTT broker. See [Network Requirements](/frigate/network_requirements#mqtt) for details.
+
+:::
+
 ## General Frigate Topics
 
 ### `frigate/available`

docs/docs/integrations/plus.md

@@ -5,6 +5,12 @@ title: Frigate+
 
 For more information about how to use Frigate+ to improve your model, see the [Frigate+ docs](/plus/).
 
+:::info
+
+Frigate+ requires an active internet connection to communicate with `https://api.frigate.video` for model downloads, image uploads, and annotations. See [Network Requirements](/frigate/network_requirements#frigate) for details.
+
+:::
+
 ## Setup
 
 ### Create an account

docs/docs/integrations/third_party_extensions.md

@@ -17,6 +17,10 @@ Please use your own knowledge to assess and vet them before you install anything
 
 The [Advanced Camera Card](https://card.camera/#/README) is a Home Assistant dashboard card with deep Frigate integration.
 
+## [cctvQL](https://github.com/arunrajiah/cctvql)
+
+[cctvQL](https://github.com/arunrajiah/cctvql) is a natural language query layer for Frigate and other CCTV systems. It connects to Frigate's REST API and MQTT broker to let you ask conversational questions about cameras and events (e.g. "Was there motion at the front door last night?"), with support for real-time event streaming, anomaly detection, PTZ control, alert rules, and a Home Assistant custom component.
+
 ## [Double Take](https://github.com/skrashevich/double-take)
 
 [Double Take](https://github.com/skrashevich/double-take) provides an unified UI and API for processing and training images for facial recognition.
@@ -35,6 +39,10 @@ This is a fork (with fixed errors and new features) of [original Double Take](ht
 
 [Frigate telegram](https://github.com/OldTyT/frigate-telegram) makes it possible to send events from Frigate to Telegram. Events are sent as a message with a text description, video, and thumbnail.
 
+## [kiosk-monitor](https://github.com/extremeshok/kiosk-monitor)
+
+[kiosk-monitor](https://github.com/extremeshok/kiosk-monitor) is a Raspberry Pi watchdog that runs Chromium fullscreen on a Frigate dashboard (optionally with VLC on a second monitor for an RTSP camera stream), auto-restarts on frozen screens or unreachable URLs, and ships a Birdseye-aware Chromium helper that auto-sizes the grid to the display.
+
 ## [Periscope](https://github.com/maksz42/periscope)
 
 [Periscope](https://github.com/maksz42/periscope) is a lightweight Android app that turns old devices into live viewers for Frigate. It works on Android 2.2 and above, including Android TV. It supports authentication and HTTPS.

docs/docs/troubleshooting/faqs.md

@@ -110,3 +110,17 @@ No. Frigate uses the TCP protocol to connect to your camera's RTSP URL. VLC auto
 TCP ensures that all data packets arrive in the correct order. This is crucial for video recording, decoding, and stream processing, which is why Frigate enforces a TCP connection. UDP is faster but less reliable, as it does not guarantee packet delivery or order, and VLC does not have the same requirements as Frigate.
 
 You can still configure Frigate to use UDP by using ffmpeg input args or the preset `preset-rtsp-udp`. See the [ffmpeg presets](/configuration/ffmpeg_presets) documentation.
+
+### Frigate is slow to start up with a "probing detect stream" message in the logs
+
+When `detect.width` and `detect.height` are not set, Frigate probes each camera's detect stream on startup (and when saving the config) to auto-detect its resolution. For RTSP streams Frigate probes with ffprobe and automatically retries over TCP if UDP doesn't respond, with a 5 second timeout per attempt. A camera that cannot be reached over either transport will add up to ~10 seconds to startup before Frigate falls through with default dimensions, which may show up as width `0` and height `0` in Camera Probe Info under System Metrics.
+
+To skip the probe entirely and make startup instant, set `detect.width` and `detect.height` explicitly in your camera config:
+
+```yaml
+cameras:
+  my_camera:
+    detect:
+      width: 1280
+      height: 720
+```

docs/docs/troubleshooting/recordings.md

@@ -80,3 +80,85 @@ Some users found that mounting a drive via `fstab` with the `sync` option caused
 #### Copy Times < 1 second
 
 If the storage is working quickly then this error may be caused by CPU load on the machine being too high for Frigate to have the resources to keep up. Try temporarily shutting down other services to see if the issue improves.
+
+## I see the message: WARNING : Too many unprocessed recording segments in cache for camera. This likely indicates an issue with the detect stream...
+
+This warning means that the detect stream for the affected camera has fallen behind or stopped processing frames. Frigate's recording cache holds segments waiting to be analyzed by the detector — when more than 6 segments pile up without being processed, Frigate discards the oldest ones to prevent the cache from filling up.
+
+:::warning
+
+This error is a **symptom**, not the root cause. The actual cause is always logged **before** these messages start appearing. You must review the full logs from Frigate startup through the first occurrence of this warning to identify the real issue.
+
+:::
+
+### Step 1: Get the full logs
+
+Collect complete Frigate logs from startup through the first occurrence of the error. Look for errors or warnings that appear **before** the "Too many unprocessed" messages begin — that is where the root cause will be found.
+
+### Step 2: Check the cache directory
+
+Exec into the Frigate container and inspect the recording cache:
+
+```
+docker exec -it frigate ls -la /tmp/cache
+```
+
+Each camera should have a small number of `.mp4` segment files. If one camera has significantly more files than others, that camera is the source of the problem. A problem with a single camera can cascade and cause all cameras to show this error.
+
+### Step 3: Verify segment duration
+
+Recording segments should be approximately 10 seconds long. Run `ffprobe` on segments in the cache to check:
+
+```
+docker exec -it frigate ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1 /tmp/cache/<camera>@<segment>.mp4
+```
+
+If segments are only ~1 second instead of ~10 seconds, the camera is sending corrupt timestamp data, causing segments to be split too frequently and filling the cache 10x faster than expected.
+
+**Common causes of short segments:**
+
+- **"Smart Codec" or "Smart+" enabled on the camera** — These features dynamically change encoding parameters mid-stream, which corrupts timestamps. Disable them in your camera's settings.
+- **Changing codec, bitrate, or resolution mid-stream** — Any encoding changes during an active stream can cause unpredictable segment splitting.
+- **Camera firmware bugs** — Check for firmware updates from your camera manufacturer.
+
+### Step 4: Check for a stuck detector
+
+If the detect stream is not processing frames, segments will accumulate. Common causes:
+
+- **Detection resolution too high** — Use a substream for detection, not the full resolution main stream.
+- **Detection FPS too high** — 5 fps is the recommended maximum for detection.
+- **Model too large** — Use smaller model variants (e.g., YOLO `s` or `t` size, not `e` or `x`). Use 320x320 input size rather than 640x640 unless you have a powerful dedicated detector.
+- **Virtualization** — Running Frigate in a VM (especially Proxmox) can cause the detector to hang or stall. This is a known issue with GPU/TPU passthrough in virtualized environments and is not something Frigate can fix. Running Frigate in Docker on bare metal is recommended.
+
+### Step 5: Check for GPU hangs
+
+On the host machine, check `dmesg` for GPU-related errors:
+
+```
+dmesg | grep -i -E "gpu|drm|reset|hang"
+```
+
+Messages like `trying reset from guc_exec_queue_timedout_job` or similar GPU reset/hang messages indicate a driver or hardware issue. Ensure your kernel and GPU drivers (especially Intel) are up to date.
+
+### Step 6: Verify hardware acceleration configuration
+
+An incorrect `hwaccel_args` preset can cause ffmpeg to fail silently or consume excessive CPU, starving the detector of resources.
+
+- After upgrading Frigate, verify your preset matches your hardware (e.g., `preset-intel-qsv-h264` instead of the deprecated `preset-vaapi`).
+- For h265 cameras, use the corresponding h265 preset (e.g., `preset-intel-qsv-h265`).
+- Note that `hwaccel_args` are only relevant for the detect stream — Frigate does not decode the record stream.
+
+### Step 7: Verify go2rtc stream configuration
+
+Ensure that the ffmpeg source names in your go2rtc configuration match the correct camera stream. A misconfigured stream name (e.g., copying a config from one camera to another without updating the stream reference) will cause the wrong stream to be used or the stream to fail entirely.
+
+### Step 8: Check system resources
+
+If none of the above apply, the issue may be a general resource constraint. Monitor the following on your host:
+
+- **CPU usage** — An overloaded CPU can prevent the detector from keeping up.
+- **RAM and swap** — Excessive swapping dramatically slows all I/O operations.
+- **Disk I/O** — Use `iotop` or `iostat` to check for saturation.
+- **Storage space** — Verify you have free space on the Frigate storage volume (check the Storage page in the Frigate UI).
+
+Try temporarily disabling resource-intensive features like `genai` and `face_recognition` to see if the issue resolves. This can help isolate whether the detector is being starved of resources.

docs/package-lock.json

@@ -10897,9 +10897,9 @@
       "license": "MIT"
     },
     "node_modules/express/node_modules/path-to-regexp": {
-      "version": "0.1.12",
-      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.12.tgz",
-      "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==",
+      "version": "0.1.13",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.13.tgz",
+      "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==",
       "license": "MIT"
     },
     "node_modules/express/node_modules/range-parser": {

docs/sidebars.ts

@@ -12,6 +12,7 @@ const sidebars: SidebarsConfig = {
       "frigate/updating",
       "frigate/camera_setup",
       "frigate/video_pipeline",
+      "frigate/network_requirements",
       "frigate/glossary",
     ],
     Guides: [

docs/static/frigate-api.yaml

@@ -2724,6 +2724,135 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/HTTPValidationError"
+  /exports/batch:
+    post:
+      tags:
+        - Export
+      summary: Start recording export batch
+      description: >-
+        Starts recording exports for a batch of items, each with its own camera
+        and time range. Optionally assigns them to a new or existing export case.
+        When neither export_case_id nor new_case_name is provided, exports are
+        added as uncategorized. Attaching to an existing case is admin-only.
+      operationId: export_recordings_batch_exports_batch_post
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/BatchExportBody"
+      responses:
+        "202":
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BatchExportResponse"
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "503":
+          description: Service Unavailable
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "422":
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HTTPValidationError"
+  /exports/delete:
+    post:
+      tags:
+        - Export
+      summary: Bulk delete exports
+      description: >-
+        Deletes one or more exports by ID. All IDs must exist and none can be
+        in-progress. Admin-only.
+      operationId: bulk_delete_exports_exports_delete_post
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ExportBulkDeleteBody"
+      responses:
+        "200":
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "400":
+          description: Bad Request - one or more exports are in-progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "404":
+          description: Not Found - one or more export IDs do not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "422":
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HTTPValidationError"
+  /exports/reassign:
+    post:
+      tags:
+        - Export
+      summary: Bulk reassign exports to a case
+      description: >-
+        Assigns or unassigns one or more exports to/from a case. All IDs must
+        exist. Pass export_case_id as null to unassign (move to uncategorized).
+        Admin-only.
+      operationId: bulk_reassign_exports_exports_reassign_post
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ExportBulkReassignBody"
+      responses:
+        "200":
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "404":
+          description: Not Found - one or more export IDs or the target case do not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenericResponse"
+        "422":
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HTTPValidationError"
   /cases:
     get:
       tags:
@@ -2853,39 +2982,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/HTTPValidationError"
-  "/export/{export_id}/case":
-    patch:
-      tags:
-        - Export
-      summary: Assign export to case
-      description: "Assigns an export to a case, or unassigns it if export_case_id is null."
-      operationId: assign_export_case_export__export_id__case_patch
-      parameters:
-        - name: export_id
-          in: path
-          required: true
-          schema:
-            type: string
-            title: Export Id
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/ExportCaseAssignBody"
-      responses:
-        "200":
-          description: Successful Response
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/GenericResponse"
-        "422":
-          description: Validation Error
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/HTTPValidationError"
   "/export/{camera_name}/start/{start_time}/end/{end_time}":
     post:
       tags:
@@ -2973,32 +3069,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/HTTPValidationError"
-  "/export/{event_id}":
-    delete:
-      tags:
-        - Export
-      summary: Delete export
-      operationId: export_delete_export__event_id__delete
-      parameters:
-        - name: event_id
-          in: path
-          required: true
-          schema:
-            type: string
-            title: Event Id
-      responses:
-        "200":
-          description: Successful Response
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/GenericResponse"
-        "422":
-          description: Validation Error
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/HTTPValidationError"
   "/export/custom/{camera_name}/start/{start_time}/end/{end_time}":
     post:
       tags:
@@ -6501,6 +6571,149 @@ components:
       required:
         - recognizedLicensePlate
       title: EventsLPRBody
+    BatchExportBody:
+      properties:
+        items:
+          items:
+            $ref: "#/components/schemas/BatchExportItem"
+          type: array
+          minItems: 1
+          maxItems: 50
+          title: Items
+          description: List of export items. Each item has its own camera and time range.
+        export_case_id:
+          anyOf:
+            - type: string
+              maxLength: 30
+            - type: "null"
+          title: Export case ID
+          description: Existing export case ID to assign all exports to. Attaching to an existing case is temporarily admin-only until case-level ACLs exist.
+        new_case_name:
+          anyOf:
+            - type: string
+              maxLength: 100
+            - type: "null"
+          title: New case name
+          description: Name of a new export case to create when export_case_id is omitted
+        new_case_description:
+          anyOf:
+            - type: string
+            - type: "null"
+          title: New case description
+          description: Optional description for a newly created export case
+      type: object
+      required:
+        - items
+      title: BatchExportBody
+    BatchExportItem:
+      properties:
+        camera:
+          type: string
+          title: Camera name
+        start_time:
+          type: number
+          title: Start time
+        end_time:
+          type: number
+          title: End time
+        image_path:
+          anyOf:
+            - type: string
+            - type: "null"
+          title: Existing thumbnail path
+          description: Optional existing image to use as the export thumbnail
+        friendly_name:
+          anyOf:
+            - type: string
+              maxLength: 256
+            - type: "null"
+          title: Friendly name
+          description: Optional friendly name for this specific export item
+        client_item_id:
+          anyOf:
+            - type: string
+              maxLength: 128
+            - type: "null"
+          title: Client item ID
+          description: Optional opaque client identifier echoed back in results
+      type: object
+      required:
+        - camera
+        - start_time
+        - end_time
+      title: BatchExportItem
+    BatchExportResponse:
+      properties:
+        export_case_id:
+          anyOf:
+            - type: string
+            - type: "null"
+          title: Export Case Id
+          description: Export case ID associated with the batch
+        export_ids:
+          items:
+            type: string
+          type: array
+          title: Export Ids
+          description: Export IDs successfully queued
+        results:
+          items:
+            $ref: "#/components/schemas/BatchExportResultModel"
+          type: array
+          title: Results
+          description: Per-item batch export results
+      type: object
+      required:
+        - export_ids
+        - results
+      title: BatchExportResponse
+      description: Response model for starting an export batch.
+    BatchExportResultModel:
+      properties:
+        camera:
+          type: string
+          title: Camera
+          description: Camera name for this export attempt
+        export_id:
+          anyOf:
+            - type: string
+            - type: "null"
+          title: Export Id
+          description: The export ID when the export was successfully queued
+        success:
+          type: boolean
+          title: Success
+          description: Whether the export was successfully queued
+        status:
+          anyOf:
+            - type: string
+            - type: "null"
+          title: Status
+          description: Queue status for this camera export
+        error:
+          anyOf:
+            - type: string
+            - type: "null"
+          title: Error
+          description: Validation or queueing error for this item, if any
+        item_index:
+          anyOf:
+            - type: integer
+            - type: "null"
+          title: Item Index
+          description: Zero-based index of this result within the request items list
+        client_item_id:
+          anyOf:
+            - type: string
+            - type: "null"
+          title: Client Item Id
+          description: Opaque client-supplied item identifier echoed from the request
+      type: object
+      required:
+        - camera
+        - success
+      title: BatchExportResultModel
+      description: Per-item result for a batch export request.
     EventsSubLabelBody:
       properties:
         subLabel:
@@ -6523,18 +6736,41 @@ components:
       required:
         - subLabel
       title: EventsSubLabelBody
-    ExportCaseAssignBody:
+    ExportBulkDeleteBody:
       properties:
+        ids:
+          items:
+            type: string
+            minLength: 1
+          type: array
+          minItems: 1
+          title: Ids
+      type: object
+      required:
+        - ids
+      title: ExportBulkDeleteBody
+      description: Request body for bulk deleting exports.
+    ExportBulkReassignBody:
+      properties:
+        ids:
+          items:
+            type: string
+            minLength: 1
+          type: array
+          minItems: 1
+          title: Ids
         export_case_id:
           anyOf:
             - type: string
               maxLength: 30
             - type: "null"
           title: Export Case Id
-          description: "Case ID to assign to the export, or null to unassign"
+          description: "Case ID to assign to, or null to unassign from current case"
       type: object
-      title: ExportCaseAssignBody
-      description: Request body for assigning or unassigning an export to a case.
+      required:
+        - ids
+      title: ExportBulkReassignBody
+      description: Request body for bulk reassigning exports to a case.
     ExportCaseCreateBody:
       properties:
         name:

frigate/api/app.py

@@ -694,6 +694,9 @@ def config_set(request: Request, body: AppConfigSetBody):
                 if request.app.stats_emitter is not None:
                     request.app.stats_emitter.config = config
 
+                if request.app.dispatcher is not None:
+                    request.app.dispatcher.config = config
+
                 if body.update_topic:
                     if body.update_topic.startswith("config/cameras/"):
                         _, _, camera, field = body.update_topic.split("/")

frigate/api/auth.py

@@ -64,6 +64,7 @@ def require_admin_by_default():
         "/logout",
         # Authenticated user endpoints (allow_any_authenticated)
         "/profile",
+        "/profiles",
         # Public info endpoints (allow_public)
         "/",
         "/version",
@@ -87,7 +88,9 @@ def require_admin_by_default():
         "/go2rtc/streams",
         "/event_ids",
         "/events",
+        "/cases",
         "/exports",
+        "/jobs/export",
     }
 
     # Path prefixes that should be exempt (for paths with parameters)
@@ -100,7 +103,9 @@ def require_admin_by_default():
         "/go2rtc/streams/",  # /go2rtc/streams/{camera}
         "/users/",  # /users/{username}/password (has own auth)
         "/preview/",  # /preview/{file}/thumbnail.jpg
+        "/cases/",  # /cases/{case_id}
         "/exports/",  # /exports/{export_id}
+        "/jobs/export/",  # /jobs/export/{export_id}
         "/vod/",  # /vod/{camera_name}/...
         "/notifications/",  # /notifications/pubkey, /notifications/register
     )

frigate/api/camera.py

@@ -30,7 +30,7 @@ from frigate.config.camera.updater import (
     CameraConfigUpdateEnum,
     CameraConfigUpdateTopic,
 )
-from frigate.config.env import FRIGATE_ENV_VARS
+from frigate.config.env import substitute_frigate_vars
 from frigate.util.builtin import clean_camera_user_pass
 from frigate.util.camera_cleanup import cleanup_camera_db, cleanup_camera_files
 from frigate.util.config import find_config_file
@@ -126,7 +126,7 @@ def go2rtc_add_stream(request: Request, stream_name: str, src: str = ""):
         params = {"name": stream_name}
         if src:
             try:
-                params["src"] = src.format(**FRIGATE_ENV_VARS)
+                params["src"] = substitute_frigate_vars(src)
             except KeyError:
                 params["src"] = src
 

frigate/api/chat.py

@@ -3,9 +3,11 @@
 import base64
 import json
 import logging
+import operator
 import time
 from datetime import datetime
-from typing import Any, Dict, Generator, List, Optional
+from functools import reduce
+from typing import Any, Dict, List, Optional
 
 import cv2
 from fastapi import APIRouter, Body, Depends, Request
@@ -17,6 +19,14 @@ from frigate.api.auth import (
     get_allowed_cameras_for_filter,
     require_camera_access,
 )
+from frigate.api.chat_util import (
+    chunk_content,
+    distance_to_score,
+    format_events_with_local_time,
+    fuse_scores,
+    hydrate_event,
+    parse_iso_to_timestamp,
+)
 from frigate.api.defs.query.events_query_parameters import EventsQueryParams
 from frigate.api.defs.request.chat_body import ChatCompletionRequest
 from frigate.api.defs.response.chat_response import (
@@ -26,61 +36,20 @@ from frigate.api.defs.response.chat_response import (
 )
 from frigate.api.defs.tags import Tags
 from frigate.api.event import events
+from frigate.config import FrigateConfig
 from frigate.genai.utils import build_assistant_message_for_conversation
 from frigate.jobs.vlm_watch import (
     get_vlm_watch_job,
     start_vlm_watch_job,
     stop_vlm_watch_job,
 )
+from frigate.models import Event
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(tags=[Tags.chat])
 
 
-def _chunk_content(content: str, chunk_size: int = 80) -> Generator[str, None, None]:
-    """Yield content in word-aware chunks for streaming."""
-    if not content:
-        return
-    words = content.split(" ")
-    current: List[str] = []
-    current_len = 0
-    for w in words:
-        current.append(w)
-        current_len += len(w) + 1
-        if current_len >= chunk_size:
-            yield " ".join(current) + " "
-            current = []
-            current_len = 0
-    if current:
-        yield " ".join(current)
-
-
-def _format_events_with_local_time(
-    events_list: List[Dict[str, Any]],
-) -> List[Dict[str, Any]]:
-    """Add human-readable local start/end times to each event for the LLM."""
-    result = []
-    for evt in events_list:
-        if not isinstance(evt, dict):
-            result.append(evt)
-            continue
-        copy_evt = dict(evt)
-        try:
-            start_ts = evt.get("start_time")
-            end_ts = evt.get("end_time")
-            if start_ts is not None:
-                dt_start = datetime.fromtimestamp(start_ts)
-                copy_evt["start_time_local"] = dt_start.strftime("%Y-%m-%d %I:%M:%S %p")
-            if end_ts is not None:
-                dt_end = datetime.fromtimestamp(end_ts)
-                copy_evt["end_time_local"] = dt_end.strftime("%Y-%m-%d %I:%M:%S %p")
-        except (TypeError, ValueError, OSError):
-            pass
-        result.append(copy_evt)
-    return result
-
-
 class ToolExecuteRequest(BaseModel):
     """Request model for tool execution."""
 
@@ -158,6 +127,76 @@ def get_tool_definitions() -> List[Dict[str, Any]]:
                 "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."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "event_id": {
+                            "type": "string",
+                            "description": "The id of the anchor event to find similar objects to.",
+                        },
+                        "after": {
+                            "type": "string",
+                            "description": "Start time in ISO 8601 format (e.g., '2024-01-01T00:00:00Z').",
+                        },
+                        "before": {
+                            "type": "string",
+                            "description": "End time in ISO 8601 format (e.g., '2024-01-01T23:59:59Z').",
+                        },
+                        "cameras": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Optional list of cameras to restrict to. Defaults to all.",
+                        },
+                        "labels": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Optional list of labels to restrict to. Defaults to the anchor event's label.",
+                        },
+                        "sub_labels": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Optional list of sub_labels (names) to restrict to.",
+                        },
+                        "zones": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "Optional list of zones. An event matches if any of its zones overlap.",
+                        },
+                        "similarity_mode": {
+                            "type": "string",
+                            "enum": ["visual", "semantic", "fused"],
+                            "description": "Which similarity signal(s) to use. 'fused' (default) combines visual and semantic.",
+                            "default": "fused",
+                        },
+                        "min_score": {
+                            "type": "number",
+                            "description": "Drop matches with a similarity score below this threshold (0.0-1.0).",
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Maximum number of matches to return (default: 10).",
+                            "default": 10,
+                        },
+                    },
+                    "required": ["event_id"],
+                },
+            },
+        },
         {
             "type": "function",
             "function": {
@@ -363,9 +402,38 @@ def get_tools() -> JSONResponse:
     return JSONResponse(content={"tools": tools})
 
 
+def _resolve_zones(
+    zones: List[str],
+    config: FrigateConfig,
+    target_cameras: List[str],
+) -> List[str]:
+    """Map zone names to their canonical config keys, case-insensitively.
+
+    LLMs frequently echo a user's casing ("Front Yard") instead of the
+    configured key ("front_yard"). The downstream zone filter is a SQLite GLOB
+    over the JSON-encoded zones column, which is case-sensitive — so an
+    unnormalized name silently returns zero matches. Build a lookup over the
+    relevant cameras' configured zones and substitute when we find a match;
+    unknown names pass through so behavior matches what the model asked for.
+    """
+    if not zones:
+        return zones
+
+    lookup: Dict[str, str] = {}
+    for camera_id in target_cameras:
+        camera_config = config.cameras.get(camera_id)
+        if camera_config is None:
+            continue
+        for zone_name in camera_config.zones.keys():
+            lookup.setdefault(zone_name.lower(), zone_name)
+
+    return [lookup.get(z.lower(), z) for z in zones]
+
+
 async def _execute_search_objects(
     arguments: Dict[str, Any],
     allowed_cameras: List[str],
+    config: FrigateConfig,
 ) -> JSONResponse:
     """
     Execute the search_objects tool.
@@ -399,6 +467,11 @@ async def _execute_search_objects(
     # Convert zones array to comma-separated string if provided
     zones = arguments.get("zones")
     if isinstance(zones, list):
+        camera_arg = arguments.get("camera")
+        target_cameras = (
+            [camera_arg] if camera_arg and camera_arg != "all" else allowed_cameras
+        )
+        zones = _resolve_zones(zones, config, target_cameras)
         zones = ",".join(zones)
     elif zones is None:
         zones = "all"
@@ -407,7 +480,7 @@ async def _execute_search_objects(
     query_params = EventsQueryParams(
         cameras=arguments.get("camera", "all"),
         labels=arguments.get("label", "all"),
-        sub_labels=arguments.get("sub_label", "all").lower(),
+        sub_labels=arguments.get("sub_label", "all"),  # case-insensitive on the backend
         zones=zones,
         zone=zones,
         after=after,
@@ -434,6 +507,171 @@ async def _execute_search_objects(
         )
 
 
+async def _execute_find_similar_objects(
+    request: Request,
+    arguments: Dict[str, Any],
+    allowed_cameras: List[str],
+) -> Dict[str, Any]:
+    """Execute the find_similar_objects tool.
+
+    Returns a plain dict (not JSONResponse) so the chat loop can embed it
+    directly in tool-result messages.
+    """
+    # 1. Semantic search enabled?
+    config = request.app.frigate_config
+    if not getattr(config.semantic_search, "enabled", False):
+        return {
+            "error": "semantic_search_disabled",
+            "message": (
+                "Semantic search must be enabled to find similar objects. "
+                "Enable it in the Frigate config under semantic_search."
+            ),
+        }
+
+    context = request.app.embeddings
+    if context is None:
+        return {
+            "error": "semantic_search_disabled",
+            "message": "Embeddings context is not available.",
+        }
+
+    # 2. Anchor lookup.
+    event_id = arguments.get("event_id")
+    if not event_id:
+        return {"error": "missing_event_id", "message": "event_id is required."}
+
+    try:
+        anchor = Event.get(Event.id == event_id)
+    except Event.DoesNotExist:
+        return {
+            "error": "anchor_not_found",
+            "message": f"Could not find event {event_id}.",
+        }
+
+    # 3. Parse params.
+    after = parse_iso_to_timestamp(arguments.get("after"))
+    before = parse_iso_to_timestamp(arguments.get("before"))
+
+    cameras = arguments.get("cameras")
+    if cameras:
+        # Respect RBAC: intersect with the user's allowed cameras.
+        cameras = [c for c in cameras if c in allowed_cameras]
+    else:
+        cameras = list(allowed_cameras) if allowed_cameras else None
+
+    labels = arguments.get("labels") or [anchor.label]
+    sub_labels = arguments.get("sub_labels")
+    zones = arguments.get("zones")
+
+    if zones:
+        zones = _resolve_zones(
+            zones, request.app.frigate_config, cameras or list(allowed_cameras)
+        )
+
+    similarity_mode = arguments.get("similarity_mode", "fused")
+    if similarity_mode not in ("visual", "semantic", "fused"):
+        similarity_mode = "fused"
+
+    min_score = arguments.get("min_score")
+    limit = int(arguments.get("limit", 10))
+    limit = max(1, min(limit, 50))
+
+    # 4. Run similarity searches. We deliberately do NOT pass event_ids into
+    # the vec queries — the IN filter on sqlite-vec is broken in the installed
+    # version (see frigate/embeddings/__init__.py). Mirror the pattern used by
+    # frigate/api/event.py events_search: fetch top-k globally, then intersect
+    # with the structured filters via Peewee.
+    visual_distances: Dict[str, float] = {}
+    description_distances: Dict[str, float] = {}
+
+    try:
+        if similarity_mode in ("visual", "fused"):
+            rows = context.search_thumbnail(anchor)
+            visual_distances = {row[0]: row[1] for row in rows}
+
+        if similarity_mode in ("semantic", "fused"):
+            query_text = (
+                (anchor.data or {}).get("description")
+                or anchor.sub_label
+                or anchor.label
+            )
+            rows = context.search_description(query_text)
+            description_distances = {row[0]: row[1] for row in rows}
+    except Exception:
+        logger.exception("Similarity search failed")
+        return {
+            "error": "similarity_search_failed",
+            "message": "Failed to run similarity search.",
+        }
+
+    vec_ids = set(visual_distances) | set(description_distances)
+    vec_ids.discard(anchor.id)
+    # vec layer returns up to k=100 per modality; flag when we hit that ceiling
+    # so the LLM can mention there may be more matches beyond what we saw.
+    candidate_truncated = (
+        len(visual_distances) >= 100 or len(description_distances) >= 100
+    )
+
+    if not vec_ids:
+        return {
+            "anchor": hydrate_event(anchor),
+            "results": [],
+            "similarity_mode": similarity_mode,
+            "candidate_truncated": candidate_truncated,
+        }
+
+    # 5. Apply structured filters, intersected with vec hits.
+    clauses = [Event.id.in_(list(vec_ids))]
+    if after is not None:
+        clauses.append(Event.start_time >= after)
+    if before is not None:
+        clauses.append(Event.start_time <= before)
+    if cameras:
+        clauses.append(Event.camera.in_(cameras))
+    if labels:
+        clauses.append(Event.label.in_(labels))
+    if sub_labels:
+        clauses.append(Event.sub_label.in_(sub_labels))
+    if zones:
+        # Mirror the pattern used by frigate/api/event.py for JSON-array zone match.
+        zone_clauses = [Event.zones.cast("text") % f'*"{zone}"*' for zone in zones]
+        clauses.append(reduce(operator.or_, zone_clauses))
+
+    eligible = {e.id: e for e in Event.select().where(reduce(operator.and_, clauses))}
+
+    # 6. Fuse and rank.
+    scored: List[tuple[str, float]] = []
+    for eid in eligible:
+        v_score = (
+            distance_to_score(visual_distances[eid], context.thumb_stats)
+            if eid in visual_distances
+            else None
+        )
+        d_score = (
+            distance_to_score(description_distances[eid], context.desc_stats)
+            if eid in description_distances
+            else None
+        )
+        fused = fuse_scores(v_score, d_score)
+        if fused is None:
+            continue
+        if min_score is not None and fused < min_score:
+            continue
+        scored.append((eid, fused))
+
+    scored.sort(key=lambda pair: pair[1], reverse=True)
+    scored = scored[:limit]
+
+    results = [hydrate_event(eligible[eid], score=score) for eid, score in scored]
+
+    return {
+        "anchor": hydrate_event(anchor),
+        "results": results,
+        "similarity_mode": similarity_mode,
+        "candidate_truncated": candidate_truncated,
+    }
+
+
 @router.post(
     "/chat/execute",
     dependencies=[Depends(allow_any_authenticated())],
@@ -457,7 +695,16 @@ async def execute_tool(
     logger.debug(f"Executing tool: {tool_name} with arguments: {arguments}")
 
     if tool_name == "search_objects":
-        return await _execute_search_objects(arguments, allowed_cameras)
+        return await _execute_search_objects(
+            arguments, allowed_cameras, request.app.frigate_config
+        )
+
+    if tool_name == "find_similar_objects":
+        result = await _execute_find_similar_objects(
+            request, arguments, allowed_cameras
+        )
+        status_code = 200 if "error" not in result else 400
+        return JSONResponse(content=result, status_code=status_code)
 
     if tool_name == "set_camera_state":
         result = await _execute_set_camera_state(request, arguments)
@@ -630,7 +877,9 @@ async def _execute_tool_internal(
     This is used by the chat completion endpoint to execute tools.
     """
     if tool_name == "search_objects":
-        response = await _execute_search_objects(arguments, allowed_cameras)
+        response = await _execute_search_objects(
+            arguments, allowed_cameras, request.app.frigate_config
+        )
         try:
             if hasattr(response, "body"):
                 body_str = response.body.decode("utf-8")
@@ -642,6 +891,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 == "find_similar_objects":
+        return await _execute_find_similar_objects(request, arguments, allowed_cameras)
     elif tool_name == "set_camera_state":
         return await _execute_set_camera_state(request, arguments)
     elif tool_name == "get_live_context":
@@ -664,8 +915,9 @@ async def _execute_tool_internal(
         return _execute_get_recap(arguments, allowed_cameras)
     else:
         logger.error(
-            "Tool call failed: unknown tool %r. Expected one of: search_objects, get_live_context, "
-            "start_camera_watch, stop_camera_watch, get_profile_status, get_recap. Arguments received: %s",
+            "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",
             tool_name,
             json.dumps(arguments),
         )
@@ -691,6 +943,9 @@ async def _execute_start_camera_watch(
 
     await require_camera_access(camera, request=request)
 
+    if zones:
+        zones = _resolve_zones(zones, config, [camera])
+
     genai_manager = request.app.genai_manager
     chat_client = genai_manager.chat_client
     if chat_client is None or not chat_client.supports_vision:
@@ -927,7 +1182,7 @@ async def _execute_pending_tools(
                     json.dumps(tool_args),
                 )
             if tool_name == "search_objects" and isinstance(tool_result, list):
-                tool_result = _format_events_with_local_time(tool_result)
+                tool_result = format_events_with_local_time(tool_result)
                 _keys = {
                     "id",
                     "camera",
@@ -1080,7 +1335,9 @@ Do not start your response with phrases like "I will check...", "Let me see...",
 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.{cameras_section}"""
+Always be accurate with time calculations based on the current date provided.
+
+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.{cameras_section}"""
 
     conversation.append(
         {
@@ -1118,6 +1375,9 @@ Always be accurate with time calculations based on the current date provided.{ca
         async def stream_body_llm():
             nonlocal conversation, stream_tool_calls, stream_iterations
             while stream_iterations < max_iterations:
+                if await request.is_disconnected():
+                    logger.debug("Client disconnected, stopping chat stream")
+                    return
                 logger.debug(
                     f"Streaming LLM (iteration {stream_iterations + 1}/{max_iterations}) "
                     f"with {len(conversation)} message(s)"
@@ -1127,6 +1387,9 @@ Always be accurate with time calculations based on the current date provided.{ca
                     tools=tools if tools else None,
                     tool_choice="auto",
                 ):
+                    if await request.is_disconnected():
+                        logger.debug("Client disconnected, stopping chat stream")
+                        return
                     kind, value = event
                     if kind == "content_delta":
                         yield (
@@ -1156,6 +1419,11 @@ Always be accurate with time calculations based on the current date provided.{ca
                                     msg.get("content"), pending
                                 )
                             )
+                            if await request.is_disconnected():
+                                logger.debug(
+                                    "Client disconnected before tool execution"
+                                )
+                                return
                             (
                                 executed_calls,
                                 tool_results,
@@ -1240,7 +1508,7 @@ Always be accurate with time calculations based on the current date provided.{ca
                                 + b"\n"
                             )
                         # Stream content in word-sized chunks for smooth UX
-                        for part in _chunk_content(final_content):
+                        for part in chunk_content(final_content):
                             yield (
                                 json.dumps({"type": "content", "delta": part}).encode(
                                     "utf-8"

frigate/api/chat_util.py

@@ -0,0 +1,135 @@
+"""Pure, stateless helpers used by the chat tool dispatchers.
+
+These were extracted from frigate/api/chat.py to keep that module focused on
+route handlers, tool dispatchers, and streaming loop internals. Nothing in
+this file touches the FastAPI request, the embeddings context, or the chat
+loop state — all inputs and outputs are plain data.
+"""
+
+import logging
+import math
+import time
+from datetime import datetime
+from typing import Any, Dict, Generator, List, Optional
+
+from frigate.embeddings.util import ZScoreNormalization
+from frigate.models import Event
+
+logger = logging.getLogger(__name__)
+
+
+# Similarity fusion weights for find_similar_objects.
+# Visual dominates because the feature's primary use case is "same specific object."
+# If these change, update the test in test_chat_find_similar_objects.py.
+VISUAL_WEIGHT = 0.65
+DESCRIPTION_WEIGHT = 0.35
+
+
+def chunk_content(content: str, chunk_size: int = 80) -> Generator[str, None, None]:
+    """Yield content in word-aware chunks for streaming."""
+    if not content:
+        return
+    words = content.split(" ")
+    current: List[str] = []
+    current_len = 0
+    for w in words:
+        current.append(w)
+        current_len += len(w) + 1
+        if current_len >= chunk_size:
+            yield " ".join(current) + " "
+            current = []
+            current_len = 0
+    if current:
+        yield " ".join(current)
+
+
+def format_events_with_local_time(
+    events_list: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    """Add human-readable local start/end times to each event for the LLM."""
+    result = []
+    for evt in events_list:
+        if not isinstance(evt, dict):
+            result.append(evt)
+            continue
+        copy_evt = dict(evt)
+        try:
+            start_ts = evt.get("start_time")
+            end_ts = evt.get("end_time")
+            if start_ts is not None:
+                dt_start = datetime.fromtimestamp(start_ts)
+                copy_evt["start_time_local"] = dt_start.strftime("%Y-%m-%d %I:%M:%S %p")
+            if end_ts is not None:
+                dt_end = datetime.fromtimestamp(end_ts)
+                copy_evt["end_time_local"] = dt_end.strftime("%Y-%m-%d %I:%M:%S %p")
+        except (TypeError, ValueError, OSError):
+            pass
+        result.append(copy_evt)
+    return result
+
+
+def distance_to_score(distance: float, stats: ZScoreNormalization) -> float:
+    """Convert a cosine distance to a [0, 1] similarity score.
+
+    Uses the existing ZScoreNormalization stats maintained by EmbeddingsContext
+    to normalize across deployments, then a bounded sigmoid. Lower distance ->
+    higher score. If stats are uninitialized (stddev == 0), returns a neutral
+    0.5 so the fallback ordering by raw distance still dominates.
+    """
+    if stats.stddev == 0:
+        return 0.5
+    z = (distance - stats.mean) / stats.stddev
+    # Sigmoid on -z so that small distance (good) -> high score.
+    return 1.0 / (1.0 + math.exp(z))
+
+
+def fuse_scores(
+    visual_score: Optional[float],
+    description_score: Optional[float],
+) -> Optional[float]:
+    """Weighted fusion of visual and description similarity scores.
+
+    If one side is missing (e.g., no description embedding for this event),
+    the other side's score is returned alone with no penalty. If both are
+    missing, returns None and the caller should drop the event.
+    """
+    if visual_score is None and description_score is None:
+        return None
+    if visual_score is None:
+        return description_score
+    if description_score is None:
+        return visual_score
+    return VISUAL_WEIGHT * visual_score + DESCRIPTION_WEIGHT * description_score
+
+
+def parse_iso_to_timestamp(value: Optional[str]) -> Optional[float]:
+    """Parse an ISO-8601 string as server-local time -> unix timestamp.
+
+    Mirrors the parsing _execute_search_objects uses so both tools accept the
+    same format from the LLM.
+    """
+    if value is None:
+        return None
+    try:
+        s = value.replace("Z", "").strip()[:19]
+        dt = datetime.strptime(s, "%Y-%m-%dT%H:%M:%S")
+        return time.mktime(dt.timetuple())
+    except (ValueError, AttributeError, TypeError):
+        logger.warning("Invalid timestamp format: %s", value)
+        return None
+
+
+def hydrate_event(event: Event, score: Optional[float] = None) -> Dict[str, Any]:
+    """Convert an Event row into the dict shape returned by find_similar_objects."""
+    data: Dict[str, Any] = {
+        "id": event.id,
+        "camera": event.camera,
+        "label": event.label,
+        "sub_label": event.sub_label,
+        "start_time": event.start_time,
+        "end_time": event.end_time,
+        "zones": event.zones,
+    }
+    if score is not None:
+        data["score"] = score
+    return data

frigate/api/defs/request/batch_export_body.py

@@ -0,0 +1,65 @@
+from typing import List, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+MAX_BATCH_EXPORT_ITEMS = 50
+
+
+class BatchExportItem(BaseModel):
+    camera: str = Field(title="Camera name")
+    start_time: float = Field(title="Start time")
+    end_time: float = Field(title="End time")
+    image_path: Optional[str] = Field(
+        default=None,
+        title="Existing thumbnail path",
+        description="Optional existing image to use as the export thumbnail",
+    )
+    friendly_name: Optional[str] = Field(
+        default=None,
+        title="Friendly name",
+        max_length=256,
+        description="Optional friendly name for this specific export item",
+    )
+    client_item_id: Optional[str] = Field(
+        default=None,
+        title="Client item ID",
+        max_length=128,
+        description="Optional opaque client identifier echoed back in results",
+    )
+
+
+class BatchExportBody(BaseModel):
+    items: List[BatchExportItem] = Field(
+        title="Items",
+        min_length=1,
+        max_length=MAX_BATCH_EXPORT_ITEMS,
+        description="List of export items. Each item has its own camera and time range.",
+    )
+    export_case_id: Optional[str] = Field(
+        default=None,
+        title="Export case ID",
+        max_length=30,
+        description=(
+            "Existing export case ID to assign all exports to. Attaching to an "
+            "existing case is temporarily admin-only until case-level ACLs exist."
+        ),
+    )
+    new_case_name: Optional[str] = Field(
+        default=None,
+        title="New case name",
+        max_length=100,
+        description="Name of a new export case to create when export_case_id is omitted",
+    )
+    new_case_description: Optional[str] = Field(
+        default=None,
+        title="New case description",
+        description="Optional description for a newly created export case",
+    )
+
+    @model_validator(mode="after")
+    def validate_case_target(self) -> "BatchExportBody":
+        for item in self.items:
+            if item.end_time <= item.start_time:
+                raise ValueError("end_time must be after start_time")
+
+        return self

frigate/api/defs/request/export_bulk_body.py

@@ -0,0 +1,24 @@
+"""Request bodies for bulk export operations."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, conlist, constr
+
+
+class ExportBulkDeleteBody(BaseModel):
+    """Request body for bulk deleting exports."""
+
+    # List of export IDs with at least one element and each element with at least one char
+    ids: conlist(constr(min_length=1), min_length=1)
+
+
+class ExportBulkReassignBody(BaseModel):
+    """Request body for bulk reassigning exports to a case."""
+
+    # List of export IDs with at least one element and each element with at least one char
+    ids: conlist(constr(min_length=1), min_length=1)
+    export_case_id: Optional[str] = Field(
+        default=None,
+        max_length=30,
+        description="Case ID to assign to, or null to unassign from current case",
+    )

frigate/api/defs/request/export_case_body.py

@@ -23,13 +23,3 @@ class ExportCaseUpdateBody(BaseModel):
     description: Optional[str] = Field(
         default=None, description="Updated description of the export case"
     )
-
-
-class ExportCaseAssignBody(BaseModel):
-    """Request body for assigning or unassigning an export to a case."""
-
-    export_case_id: Optional[str] = Field(
-        default=None,
-        max_length=30,
-        description="Case ID to assign to the export, or null to unassign",
-    )

frigate/api/defs/response/export_response.py

@@ -1,4 +1,4 @@
-from typing import List, Optional
+from typing import Any, List, Optional
 
 from pydantic import BaseModel, Field
 
@@ -28,6 +28,96 @@ class StartExportResponse(BaseModel):
     export_id: Optional[str] = Field(
         default=None, description="The export ID if successfully started"
     )
+    status: Optional[str] = Field(
+        default=None,
+        description="Queue status for the export job",
+    )
+
+
+class BatchExportResultModel(BaseModel):
+    """Per-item result for a batch export request."""
+
+    camera: str = Field(description="Camera name for this export attempt")
+    export_id: Optional[str] = Field(
+        default=None,
+        description="The export ID when the export was successfully queued",
+    )
+    success: bool = Field(description="Whether the export was successfully queued")
+    status: Optional[str] = Field(
+        default=None,
+        description="Queue status for this camera export",
+    )
+    error: Optional[str] = Field(
+        default=None,
+        description="Validation or queueing error for this item, if any",
+    )
+    item_index: Optional[int] = Field(
+        default=None,
+        description="Zero-based index of this result within the request items list",
+    )
+    client_item_id: Optional[str] = Field(
+        default=None,
+        description="Opaque client-supplied item identifier echoed from the request",
+    )
+
+
+class BatchExportResponse(BaseModel):
+    """Response model for starting an export batch."""
+
+    export_case_id: Optional[str] = Field(
+        default=None,
+        description="Export case ID associated with the batch",
+    )
+    export_ids: List[str] = Field(description="Export IDs successfully queued")
+    results: List[BatchExportResultModel] = Field(
+        description="Per-item batch export results"
+    )
+
+
+class ExportJobModel(BaseModel):
+    """Model representing a queued or running export job."""
+
+    id: str = Field(description="Unique identifier for the export job")
+    job_type: str = Field(description="Job type")
+    status: str = Field(description="Current job status")
+    camera: str = Field(description="Camera associated with this export job")
+    name: Optional[str] = Field(
+        default=None,
+        description="Friendly name for the export",
+    )
+    export_case_id: Optional[str] = Field(
+        default=None,
+        description="ID of the export case this export belongs to",
+    )
+    request_start_time: float = Field(description="Requested export start time")
+    request_end_time: float = Field(description="Requested export end time")
+    start_time: Optional[float] = Field(
+        default=None,
+        description="Unix timestamp when execution started",
+    )
+    end_time: Optional[float] = Field(
+        default=None,
+        description="Unix timestamp when execution completed",
+    )
+    error_message: Optional[str] = Field(
+        default=None,
+        description="Error message for failed jobs",
+    )
+    results: Optional[dict[str, Any]] = Field(
+        default=None,
+        description="Result metadata for completed jobs",
+    )
+    current_step: str = Field(
+        default="queued",
+        description="Current execution step (queued, preparing, encoding, encoding_retry, finalizing)",
+    )
+    progress_percent: float = Field(
+        default=0.0,
+        description="Progress percentage of the current step (0.0 - 100.0)",
+    )
+
+
+ExportJobsResponse = List[ExportJobModel]
 
 
 ExportsResponse = List[ExportModel]

frigate/api/event.py

@@ -199,13 +199,18 @@ def events(
             sub_label_clauses.append((Event.sub_label.is_null()))
 
         for label in filtered_sub_labels:
+            lowered = label.lower()
             sub_label_clauses.append(
-                (Event.sub_label.cast("text") == label)
-            )  # include exact matches
+                (fn.LOWER(Event.sub_label.cast("text")) == lowered)
+            )  # include exact matches (case-insensitive)
 
-            # include this label when part of a list
-            sub_label_clauses.append((Event.sub_label.cast("text") % f"*{label},*"))
-            sub_label_clauses.append((Event.sub_label.cast("text") % f"*, {label}*"))
+            # include this label when part of a list (LIKE is case-insensitive in sqlite for ASCII)
+            sub_label_clauses.append(
+                (fn.LOWER(Event.sub_label.cast("text")) % f"*{lowered},*")
+            )
+            sub_label_clauses.append(
+                (fn.LOWER(Event.sub_label.cast("text")) % f"*, {lowered}*")
+            )
 
         sub_label_clause = reduce(operator.or_, sub_label_clauses)
         clauses.append((sub_label_clause))
@@ -609,13 +614,18 @@ def events_search(
             sub_label_clauses.append((Event.sub_label.is_null()))
 
         for label in filtered_sub_labels:
+            lowered = label.lower()
             sub_label_clauses.append(
-                (Event.sub_label.cast("text") == label)
-            )  # include exact matches
+                (fn.LOWER(Event.sub_label.cast("text")) == lowered)
+            )  # include exact matches (case-insensitive)
 
-            # include this label when part of a list
-            sub_label_clauses.append((Event.sub_label.cast("text") % f"*{label},*"))
-            sub_label_clauses.append((Event.sub_label.cast("text") % f"*, {label}*"))
+            # include this label when part of a list (LIKE is case-insensitive in sqlite for ASCII)
+            sub_label_clauses.append(
+                (fn.LOWER(Event.sub_label.cast("text")) % f"*{lowered},*")
+            )
+            sub_label_clauses.append(
+                (fn.LOWER(Event.sub_label.cast("text")) % f"*, {lowered}*")
+            )
 
         event_filters.append((reduce(operator.or_, sub_label_clauses)))
 
@@ -744,6 +754,15 @@ def events_search(
                 status_code=404,
             )
 
+        if search_event.camera not in allowed_cameras:
+            return JSONResponse(
+                content={
+                    "success": False,
+                    "message": "Event not found",
+                },
+                status_code=404,
+            )
+
         thumb_result = context.search_thumbnail(search_event)
         thumb_ids = {result[0]: result[1] for result in thumb_result}
         search_results = {

frigate/api/media.py

@@ -1368,12 +1368,17 @@ def preview_gif(
         file_start = f"preview_{camera_name}-"
         start_file = f"{file_start}{start_ts}.{PREVIEW_FRAME_TYPE}"
         end_file = f"{file_start}{end_ts}.{PREVIEW_FRAME_TYPE}"
+
+        camera_files = [
+            entry.name
+            for entry in os.scandir(preview_dir)
+            if entry.name.startswith(file_start)
+        ]
+        camera_files.sort()
+
         selected_previews = []
 
-        for file in sorted(os.listdir(preview_dir)):
-            if not file.startswith(file_start):
-                continue
-
+        for file in camera_files:
             if file < start_file:
                 continue
 
@@ -1550,12 +1555,17 @@ def preview_mp4(
         file_start = f"preview_{camera_name}-"
         start_file = f"{file_start}{start_ts}.{PREVIEW_FRAME_TYPE}"
         end_file = f"{file_start}{end_ts}.{PREVIEW_FRAME_TYPE}"
+
+        camera_files = [
+            entry.name
+            for entry in os.scandir(preview_dir)
+            if entry.name.startswith(file_start)
+        ]
+        camera_files.sort()
+
         selected_previews = []
 
-        for file in sorted(os.listdir(preview_dir)):
-            if not file.startswith(file_start):
-                continue
-
+        for file in camera_files:
             if file < start_file:
                 continue
 

frigate/api/preview.py

@@ -148,12 +148,17 @@ def get_preview_frames_from_cache(camera_name: str, start_ts: float, end_ts: flo
     file_start = f"preview_{camera_name}-"
     start_file = f"{file_start}{start_ts}.{PREVIEW_FRAME_TYPE}"
     end_file = f"{file_start}{end_ts}.{PREVIEW_FRAME_TYPE}"
+
+    camera_files = [
+        entry.name
+        for entry in os.scandir(preview_dir)
+        if entry.name.startswith(file_start)
+    ]
+    camera_files.sort()
+
     selected_previews = []
 
-    for file in sorted(os.listdir(preview_dir)):
-        if not file.startswith(file_start):
-            continue
-
+    for file in camera_files:
         if file < start_file:
             continue
 

frigate/api/record.py

@@ -35,7 +35,7 @@ logger = logging.getLogger(__name__)
 router = APIRouter(tags=[Tags.recordings])
 
 
-@router.get("/recordings/storage", dependencies=[Depends(allow_any_authenticated())])
+@router.get("/recordings/storage", dependencies=[Depends(require_role(["admin"]))])
 def get_recordings_storage_usage(request: Request):
     recording_stats = request.app.stats_emitter.get_latest_stats()["service"][
         "storage"

frigate/app.py

@@ -52,6 +52,7 @@ from frigate.embeddings import EmbeddingProcess, EmbeddingsContext
 from frigate.events.audio import AudioProcessor
 from frigate.events.cleanup import EventCleanup
 from frigate.events.maintainer import EventProcessor
+from frigate.jobs.export import reap_stale_exports
 from frigate.jobs.motion_search import stop_all_motion_search_jobs
 from frigate.log import _stop_logging
 from frigate.models import (
@@ -188,17 +189,6 @@ class FrigateApp:
             except PermissionError:
                 logger.error("Unable to write to /config to save DB state")
 
-        def cleanup_timeline_db(db: SqliteExtDatabase) -> None:
-            db.execute_sql(
-                "DELETE FROM timeline WHERE source_id NOT IN (SELECT id FROM event);"
-            )
-
-            try:
-                with open(f"{CONFIG_DIR}/.timeline", "w") as f:
-                    f.write(str(datetime.datetime.now().timestamp()))
-            except PermissionError:
-                logger.error("Unable to write to /config to save DB state")
-
         # Migrate DB schema
         migrate_db = SqliteExtDatabase(self.config.database.path)
 
@@ -215,11 +205,6 @@ class FrigateApp:
 
         router.run()
 
-        # this is a temporary check to clean up user DB from beta
-        # will be removed before final release
-        if not os.path.exists(f"{CONFIG_DIR}/.timeline"):
-            cleanup_timeline_db(migrate_db)
-
         # check if vacuum needs to be run
         if os.path.exists(f"{CONFIG_DIR}/.vacuum"):
             with open(f"{CONFIG_DIR}/.vacuum") as f:
@@ -611,6 +596,11 @@ class FrigateApp:
         # Clean up any stale replay camera artifacts (filesystem + DB)
         cleanup_replay_cameras()
 
+        # Reap any Export rows still marked in_progress from a previous
+        # session (crash, kill, broken migration). Runs synchronously before
+        # uvicorn binds so no API request can observe a stale row.
+        reap_stale_exports()
+
         self.init_inter_process_communicator()
         self.start_detectors()
         self.init_dispatcher()

frigate/comms/webpush.py

@@ -549,6 +549,14 @@ class WebPushClient(Communicator):
         logger.debug(f"Sending camera monitoring push notification for {camera_name}")
 
         for user in self.web_pushers:
+            if not self._user_has_camera_access(user, camera):
+                logger.debug(
+                    "Skipping notification for user %s - no access to camera %s",
+                    user,
+                    camera,
+                )
+                continue
+
             self.send_push_notification(
                 user=user,
                 payload=payload,

frigate/config/camera/record.py

@@ -92,6 +92,12 @@ class RecordExportConfig(FrigateBaseModel):
         title="Export hwaccel args",
         description="Hardware acceleration args to use for export/transcode operations.",
     )
+    max_concurrent: int = Field(
+        default=3,
+        ge=1,
+        title="Maximum concurrent exports",
+        description="Maximum number of export jobs to process at the same time.",
+    )
 
 
 class RecordConfig(FrigateBaseModel):

frigate/config/camera/updater.py

@@ -20,6 +20,7 @@ class CameraConfigUpdateEnum(str, Enum):
     ffmpeg = "ffmpeg"
     live = "live"
     motion = "motion"  # includes motion and motion masks
+    mqtt = "mqtt"
     notifications = "notifications"
     objects = "objects"
     object_genai = "object_genai"
@@ -33,6 +34,7 @@ class CameraConfigUpdateEnum(str, Enum):
     lpr = "lpr"
     snapshots = "snapshots"
     timestamp_style = "timestamp_style"
+    ui = "ui"
     zones = "zones"
 
 

frigate/config/config.py

@@ -730,6 +730,9 @@ class FrigateConfig(FrigateBaseModel):
                 )
 
                 if need_detect_dimensions:
+                    logger.info(
+                        f"detect.width and detect.height not set for {camera_config.name}, probing detect stream to determine resolution."
+                    )
                     stream_info = {"width": 0, "height": 0, "fourcc": None}
                     try:
                         stream_info = stream_info_retriever.get_stream_info(

frigate/config/env.py

@@ -1,4 +1,5 @@
 import os
+import re
 from pathlib import Path
 from typing import Annotated
 
@@ -15,8 +16,77 @@ if os.path.isdir(secrets_dir) and os.access(secrets_dir, os.R_OK):
             )
 
 
+# Matches a FRIGATE_* identifier following an opening brace.
+_FRIGATE_IDENT_RE = re.compile(r"FRIGATE_[A-Za-z0-9_]+")
+
+
+def substitute_frigate_vars(value: str) -> str:
+    """Substitute `{FRIGATE_*}` placeholders in *value*.
+
+    Reproduces the subset of `str.format()` brace semantics that Frigate's
+    config has historically supported, while leaving unrelated brace content
+    (e.g. ffmpeg `%{localtime\\:...}` expressions) untouched:
+
+    * `{{` and `}}` collapse to literal `{` / `}` (the documented escape).
+    * `{FRIGATE_NAME}` is replaced from `FRIGATE_ENV_VARS`; an unknown name
+      raises `KeyError` to preserve the existing "Invalid substitution"
+      error path.
+    * A `{` that begins `{FRIGATE_` but is not a well-formed
+      `{FRIGATE_NAME}` placeholder raises `ValueError` (malformed
+      placeholder). Callers that catch `KeyError` to allow unknown-var
+      passthrough will still surface malformed syntax as an error.
+    * Any other `{` or `}` is treated as a literal and passed through.
+    """
+    out: list[str] = []
+    i = 0
+    n = len(value)
+    while i < n:
+        ch = value[i]
+        if ch == "{":
+            # Escaped literal `{{`.
+            if i + 1 < n and value[i + 1] == "{":
+                out.append("{")
+                i += 2
+                continue
+            # Possible `{FRIGATE_*}` placeholder.
+            if value.startswith("{FRIGATE_", i):
+                ident_match = _FRIGATE_IDENT_RE.match(value, i + 1)
+                if (
+                    ident_match is not None
+                    and ident_match.end() < n
+                    and value[ident_match.end()] == "}"
+                ):
+                    key = ident_match.group(0)
+                    if key not in FRIGATE_ENV_VARS:
+                        raise KeyError(key)
+                    out.append(FRIGATE_ENV_VARS[key])
+                    i = ident_match.end() + 1
+                    continue
+                # Looks like a FRIGATE placeholder but is malformed
+                # (no closing brace, illegal char, format spec, etc.).
+                raise ValueError(
+                    f"Malformed FRIGATE_ placeholder near {value[i : i + 32]!r}"
+                )
+            # Plain `{` — pass through (e.g. `%{localtime\:...}`).
+            out.append("{")
+            i += 1
+            continue
+        if ch == "}":
+            # Escaped literal `}}`.
+            if i + 1 < n and value[i + 1] == "}":
+                out.append("}")
+                i += 2
+                continue
+            out.append("}")
+            i += 1
+            continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
 def validate_env_string(v: str) -> str:
-    return v.format(**FRIGATE_ENV_VARS)
+    return substitute_frigate_vars(v)
 
 
 EnvString = Annotated[str, AfterValidator(validate_env_string)]

frigate/const.py

@@ -15,7 +15,7 @@ TRIGGER_DIR = f"{CLIPS_DIR}/triggers"
 BIRDSEYE_PIPE = "/tmp/cache/birdseye"
 CACHE_DIR = "/tmp/cache"
 REPLAY_CAMERA_PREFIX = "_replay_"
-REPLAY_DIR = os.path.join(CACHE_DIR, "replay")
+REPLAY_DIR = os.path.join(CLIPS_DIR, "replay")
 PLUS_ENV_VAR = "PLUS_API_KEY"
 PLUS_API_HOST = "https://api.frigate.video"
 
@@ -44,6 +44,22 @@ DEFAULT_ATTRIBUTE_LABEL_MAP = {
     ],
     "motorcycle": ["license_plate"],
 }
+ATTRIBUTE_LABEL_DISPLAY_MAP = {
+    "amazon": "Amazon",
+    "an_post": "An Post",
+    "canada_post": "Canada Post",
+    "dhl": "DHL",
+    "dpd": "DPD",
+    "fedex": "FedEx",
+    "gls": "GLS",
+    "nzpost": "NZ Post",
+    "postnl": "PostNL",
+    "postnord": "PostNord",
+    "purolator": "Purolator",
+    "royal_mail": "Royal Mail",
+    "ups": "UPS",
+    "usps": "USPS",
+}
 LABEL_CONSOLIDATION_MAP = {
     "car": 0.8,
     "face": 0.5,

frigate/data_processing/common/face/model.py

@@ -133,6 +133,61 @@ class FaceRecognizer(ABC):
             return 0.0
 
 
+def build_class_mean(
+    embs: list[np.ndarray],
+    trim: float = 0.15,
+    outlier_threshold: float = 0.30,
+    min_keep_frac: float = 0.7,
+    max_iters: int = 3,
+) -> np.ndarray:
+    """Build a class-mean embedding with two-layer outlier protection.
+
+    Layer 1 (iterative, vector-wise): drop whole embeddings whose cosine
+    similarity to the current class mean is below ``outlier_threshold``.
+    Catches mislabeled or corrupted training samples (wrong face in the
+    folder, full-frame screenshots, extreme crops) that per-dimension
+    trimming cannot detect.
+
+    Layer 2 (per-dimension): ``scipy.stats.trim_mean`` on the retained set
+    to smooth per-component noise (lighting, expression, alignment jitter).
+
+    Collections with fewer than 5 images bypass outlier rejection — too few
+    samples to establish a reliable class center.
+    """
+    arr = np.stack(embs, axis=0)
+
+    if len(arr) < 5:
+        return np.asarray(stats.trim_mean(arr, trim, axis=0))
+
+    keep = np.ones(len(arr), dtype=bool)
+    floor = max(5, int(np.ceil(min_keep_frac * len(arr))))
+
+    for _ in range(max_iters):
+        mean = stats.trim_mean(arr[keep], trim, axis=0)
+        m_norm = mean / (np.linalg.norm(mean) + 1e-9)
+        e_norms = arr / (np.linalg.norm(arr, axis=1, keepdims=True) + 1e-9)
+        cos = e_norms @ m_norm
+        new_keep = cos >= outlier_threshold
+
+        if new_keep.sum() < floor:
+            top = np.argsort(-cos)[:floor]
+            new_keep = np.zeros(len(arr), dtype=bool)
+            new_keep[top] = True
+
+        if np.array_equal(new_keep, keep):
+            break
+        keep = new_keep
+
+    dropped = int((~keep).sum())
+
+    if dropped:
+        logger.debug(
+            f"Vector-wise outlier filter dropped {dropped}/{len(arr)} embeddings"
+        )
+
+    return np.asarray(stats.trim_mean(arr[keep], trim, axis=0))
+
+
 def similarity_to_confidence(
     cosine_similarity: float,
     median: float = 0.3,
@@ -229,7 +284,7 @@ class FaceNetRecognizer(FaceRecognizer):
 
         for name, embs in face_embeddings_map.items():
             if embs:
-                self.mean_embs[name] = stats.trim_mean(embs, 0.15)
+                self.mean_embs[name] = build_class_mean(embs)
 
         logger.debug("Finished building ArcFace model")
 
@@ -340,7 +395,7 @@ class ArcFaceRecognizer(FaceRecognizer):
 
         for name, embs in face_embeddings_map.items():
             if embs:
-                self.mean_embs[name] = stats.trim_mean(embs, 0.15)
+                self.mean_embs[name] = build_class_mean(embs)
 
         logger.debug("Finished building ArcFace model")
 

frigate/data_processing/post/review_descriptions.py

@@ -19,7 +19,12 @@ from frigate.comms.inter_process import InterProcessRequestor
 from frigate.config import FrigateConfig
 from frigate.config.camera import CameraConfig
 from frigate.config.camera.review import GenAIReviewConfig, ImageSourceEnum
-from frigate.const import CACHE_DIR, CLIPS_DIR, UPDATE_REVIEW_DESCRIPTION
+from frigate.const import (
+    ATTRIBUTE_LABEL_DISPLAY_MAP,
+    CACHE_DIR,
+    CLIPS_DIR,
+    UPDATE_REVIEW_DESCRIPTION,
+)
 from frigate.data_processing.types import PostProcessDataEnum
 from frigate.genai import GenAIClient
 from frigate.genai.manager import GenAIClientManager
@@ -34,6 +39,8 @@ logger = logging.getLogger(__name__)
 
 RECORDING_BUFFER_EXTENSION_PERCENT = 0.10
 MIN_RECORDING_DURATION = 10
+MAX_IMAGE_TOKENS = 24000
+MAX_FRAMES_PER_SECOND = 1
 
 
 class ReviewDescriptionProcessor(PostProcessorApi):
@@ -55,14 +62,22 @@ class ReviewDescriptionProcessor(PostProcessorApi):
     def calculate_frame_count(
         self,
         camera: str,
+        duration: float,
         image_source: ImageSourceEnum = ImageSourceEnum.preview,
         height: int = 480,
     ) -> int:
-        """Calculate optimal number of frames based on context size, image source, and resolution.
+        """Calculate optimal number of frames based on event duration, context size,
+        image source, and resolution.
 
-        Token usage varies by resolution: larger images (ultra-wide aspect ratios) use more tokens.
-        Estimates ~1 token per 1250 pixels. Targets 98% context utilization with safety margin.
-        Capped at 20 frames.
+        Per-image token cost is asked of the GenAI provider so providers that know
+        their model's true cost (e.g. llama.cpp can probe the loaded mmproj) can
+        diverge from the default ~1-token-per-1250-pixels heuristic. The frame
+        budget is bounded by:
+          - remaining context window after prompt + response reservations
+          - a fixed MAX_IMAGE_TOKENS ceiling
+          - MAX_FRAMES_PER_SECOND x duration, to avoid drowning short events in
+            near-duplicate frames where the model latches onto the redundant middle
+            and skips the start/end action
         """
         client = self.genai_manager.description_client
 
@@ -100,14 +115,15 @@ class ReviewDescriptionProcessor(PostProcessorApi):
                 width = target_width
                 height = int(target_width / aspect_ratio)
 
-        pixels_per_image = width * height
-        tokens_per_image = pixels_per_image / 1250
+        tokens_per_image = client.estimate_image_tokens(width, height)
         prompt_tokens = 3800
         response_tokens = 300
-        available_tokens = context_size - prompt_tokens - response_tokens
-        max_frames = int(available_tokens / tokens_per_image)
-
-        return min(max(max_frames, 3), 20)
+        context_budget = context_size - prompt_tokens - response_tokens
+        image_token_budget = min(context_budget, MAX_IMAGE_TOKENS)
+        max_frames_by_tokens = int(image_token_budget / tokens_per_image)
+        max_frames_by_duration = int(duration * MAX_FRAMES_PER_SECOND)
+        max_frames = min(max_frames_by_tokens, max_frames_by_duration)
+        return max(max_frames, 3)
 
     def process_data(
         self, data: dict[str, Any], data_type: PostProcessDataEnum
@@ -350,12 +366,17 @@ class ReviewDescriptionProcessor(PostProcessorApi):
         file_start = f"preview_{camera}-"
         start_file = f"{file_start}{start_time}.webp"
         end_file = f"{file_start}{end_time}.webp"
+
+        camera_files = [
+            entry.name
+            for entry in os.scandir(preview_dir)
+            if entry.name.startswith(file_start)
+        ]
+        camera_files.sort()
+
         all_frames: list[str] = []
 
-        for file in sorted(os.listdir(preview_dir)):
-            if not file.startswith(file_start):
-                continue
-
+        for file in camera_files:
             if file < start_file:
                 if len(all_frames):
                     all_frames[0] = os.path.join(preview_dir, file)
@@ -371,7 +392,9 @@ class ReviewDescriptionProcessor(PostProcessorApi):
             all_frames.append(os.path.join(preview_dir, file))
 
         frame_count = len(all_frames)
-        desired_frame_count = self.calculate_frame_count(camera)
+        desired_frame_count = self.calculate_frame_count(
+            camera, duration=end_time - start_time
+        )
 
         if frame_count <= desired_frame_count:
             return all_frames
@@ -395,7 +418,7 @@ class ReviewDescriptionProcessor(PostProcessorApi):
         """Get frames from recordings at specified timestamps."""
         duration = end_time - start_time
         desired_frame_count = self.calculate_frame_count(
-            camera, ImageSourceEnum.recordings, height
+            camera, duration, ImageSourceEnum.recordings, height
         )
 
         # Calculate evenly spaced timestamps throughout the duration
@@ -556,10 +579,11 @@ def run_analysis(
         if "-verified" in label:
             continue
         elif label in labelmap_objects:
-            object_type = titlecase(label.replace("_", " "))
+            object_type = label.replace("_", " ")
 
             if label in attribute_labels:
-                unified_objects.append(f"{object_type} (delivery/service)")
+                display_name = ATTRIBUTE_LABEL_DISPLAY_MAP.get(label, object_type)
+                unified_objects.append(f"{display_name} (delivery/service)")
             else:
                 unified_objects.append(object_type)
 

frigate/data_processing/post/types.py

@@ -1,21 +1,48 @@
-from pydantic import BaseModel, ConfigDict, Field
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+ObservationItem = Annotated[str, StringConstraints(min_length=20, max_length=160)]
 
 
 class ReviewMetadata(BaseModel):
     model_config = ConfigDict(extra="ignore", protected_namespaces=())
 
+    observations: list[ObservationItem] = Field(
+        ...,
+        min_length=3,
+        max_length=15,
+        description=(
+            "Enumerate the significant observations across all frames, in "
+            "chronological order, BEFORE composing the scene narrative. "
+            "Include the very start of the activity — for example, a vehicle "
+            "entering the frame or pulling into the driveway — even if it "
+            "lasts only a few frames and the rest of the clip is dominated "
+            "by a longer activity. Include each arrival, departure, motion "
+            "event, object handled, and notable change in position or state. "
+            "Each item is a single concrete fact written as a complete "
+            "sentence. Do not summarize, interpret, or assign meaning here — "
+            "that belongs in the scene field."
+        ),
+    )
     title: str = Field(
-        description="A short title characterizing what took place and where, under 10 words."
+        max_length=80,
+        description="Under 10 words. Name the apparent purpose or outcome of the activity together with the location involved. Do not narrate or list the sequence of actions step by step.",
     )
     scene: str = Field(
-        description="A chronological narrative of what happens from start to finish."
+        min_length=150,
+        max_length=600,
+        description="A chronological narrative of what happens from start to finish, drawing directly from the items in observations.",
     )
     shortSummary: str = Field(
-        description="A brief 2-sentence summary of the scene, suitable for notifications."
+        min_length=70,
+        max_length=120,
+        description="A brief 2-sentence summary of the scene, suitable for notifications.",
     )
     confidence: float = Field(
         ge=0.0,
-        description="Confidence in the analysis, from 0 to 1.",
+        le=1.0,
+        description="Confidence in the analysis as a decimal between 0.0 and 1.0, where 0.0 means no confidence and 1.0 means complete confidence. Express ONLY as a decimal.",
     )
     potential_threat_level: int = Field(
         ge=0,

frigate/data_processing/real_time/api.py

@@ -1,8 +1,12 @@
 """Local only processors for handling real time object processing."""
 
 import logging
+import threading
 from abc import ABC, abstractmethod
-from typing import Any
+from collections import deque
+from concurrent.futures import Future
+from queue import Empty, Full, Queue
+from typing import Any, Callable
 
 import numpy as np
 
@@ -74,3 +78,123 @@ class RealTimeProcessorApi(ABC):
             payload: The updated configuration object.
         """
         pass
+
+    def drain_results(self) -> list[dict[str, Any]]:
+        """Return pending results that need IPC side-effects.
+
+        Deferred processors accumulate results on a worker thread.
+        The maintainer calls this each loop iteration to collect them
+        and perform publishes on the main thread.
+
+        Synchronous processors return an empty list (default).
+        """
+        return []
+
+    def shutdown(self) -> None:
+        """Stop any background work and release resources.
+
+        Called when the processor is being removed or the maintainer
+        is shutting down. Default is a no-op for synchronous processors.
+        """
+        pass
+
+
+class DeferredRealtimeProcessorApi(RealTimeProcessorApi):
+    """Base class for processors that offload heavy work to a background thread.
+
+    Subclasses implement:
+      - process_frame(): do cheap gating + crop + copy, then call _enqueue_task()
+      - _process_task(task): heavy work (inference, consensus) on the worker thread
+      - handle_request(): optionally use _enqueue_request() for sync request/response
+      - expire_object(): call _enqueue_task() with a control message
+
+    The worker thread owns all processor state. No locks are needed because
+    only the worker mutates state. Results that need IPC are placed in
+    _pending_results via _emit_result(), and the maintainer drains them
+    each loop iteration.
+    """
+
+    def __init__(
+        self,
+        config: FrigateConfig,
+        metrics: DataProcessorMetrics,
+        max_queue: int = 8,
+    ) -> None:
+        super().__init__(config, metrics)
+        self._task_queue: Queue = Queue(maxsize=max_queue)
+        self._pending_results: deque[dict[str, Any]] = deque()
+        self._results_lock = threading.Lock()
+        self._stop_event = threading.Event()
+        self._worker = threading.Thread(
+            target=self._drain_loop,
+            daemon=True,
+            name=f"{type(self).__name__}_worker",
+        )
+        self._worker.start()
+
+    def _drain_loop(self) -> None:
+        """Worker thread main loop — drains the task queue until stopped."""
+        while not self._stop_event.is_set():
+            try:
+                task = self._task_queue.get(timeout=0.5)
+            except Empty:
+                continue
+
+            if (
+                isinstance(task, tuple)
+                and len(task) == 2
+                and isinstance(task[1], Future)
+            ):
+                # Request/response: (callable_and_args, future)
+                (func, args), future = task
+                try:
+                    result = func(args)
+                    future.set_result(result)
+                except Exception as e:
+                    future.set_exception(e)
+            else:
+                try:
+                    self._process_task(task)
+                except Exception:
+                    logger.exception("Error processing deferred task")
+
+    def _enqueue_task(self, task: Any) -> bool:
+        """Enqueue a task for the worker. Returns False if queue is full (dropped)."""
+        try:
+            self._task_queue.put_nowait(task)
+            return True
+        except Full:
+            logger.debug("Deferred processor queue full, dropping task")
+            return False
+
+    def _enqueue_request(self, func: Callable, args: Any, timeout: float = 10.0) -> Any:
+        """Enqueue a request and block until the worker returns a result."""
+        future: Future = Future()
+        self._task_queue.put(((func, args), future), timeout=timeout)
+        return future.result(timeout=timeout)
+
+    def _emit_result(self, result: dict[str, Any]) -> None:
+        """Called by the worker thread to stage a result for the maintainer."""
+        with self._results_lock:
+            self._pending_results.append(result)
+
+    def drain_results(self) -> list[dict[str, Any]]:
+        """Called by the maintainer on the main thread to collect pending results."""
+        with self._results_lock:
+            results = list(self._pending_results)
+            self._pending_results.clear()
+        return results
+
+    def shutdown(self) -> None:
+        """Signal the worker to stop and wait for it to finish."""
+        self._stop_event.set()
+        self._worker.join(timeout=5.0)
+
+    @abstractmethod
+    def _process_task(self, task: Any) -> None:
+        """Process a single task on the worker thread.
+
+        Subclasses implement inference, consensus, training image saves here.
+        Call _emit_result() to stage results for the maintainer to publish.
+        """
+        pass

frigate/data_processing/real_time/custom_classification.py

@@ -1,7 +1,6 @@
 """Real time processor that works with classification tflite models."""
 
 import datetime
-import json
 import logging
 import os
 from typing import Any
@@ -10,25 +9,18 @@ import cv2
 import numpy as np
 
 from frigate.comms.embeddings_updater import EmbeddingsRequestEnum
-from frigate.comms.event_metadata_updater import (
-    EventMetadataPublisher,
-    EventMetadataTypeEnum,
-)
+from frigate.comms.event_metadata_updater import EventMetadataPublisher
 from frigate.comms.inter_process import InterProcessRequestor
 from frigate.config import FrigateConfig
-from frigate.config.classification import (
-    CustomClassificationConfig,
-    ObjectClassificationType,
-)
+from frigate.config.classification import CustomClassificationConfig
 from frigate.const import CLIPS_DIR, MODEL_CACHE_DIR
 from frigate.log import suppress_stderr_during
-from frigate.types import TrackedObjectUpdateTypesEnum
 from frigate.util.builtin import EventsPerSecond, InferenceSpeed, load_labels
 from frigate.util.image import calculate_region
 from frigate.util.object import box_overlaps
 
 from ..types import DataProcessorMetrics
-from .api import RealTimeProcessorApi
+from .api import DeferredRealtimeProcessorApi
 
 try:
     from tflite_runtime.interpreter import Interpreter
@@ -40,7 +32,7 @@ logger = logging.getLogger(__name__)
 MAX_OBJECT_CLASSIFICATIONS = 16
 
 
-class CustomStateClassificationProcessor(RealTimeProcessorApi):
+class CustomStateClassificationProcessor(DeferredRealtimeProcessorApi):
     def __init__(
         self,
         config: FrigateConfig,
@@ -48,7 +40,7 @@ class CustomStateClassificationProcessor(RealTimeProcessorApi):
         requestor: InterProcessRequestor,
         metrics: DataProcessorMetrics,
     ):
-        super().__init__(config, metrics)
+        super().__init__(config, metrics, max_queue=4)
         self.model_config = model_config
 
         if not self.model_config.name:
@@ -259,14 +251,34 @@ class CustomStateClassificationProcessor(RealTimeProcessorApi):
             )
             return
 
-        frame = rgb[y1:y2, x1:x2]
+        cropped_frame = rgb[y1:y2, x1:x2]
 
         try:
-            resized_frame = cv2.resize(frame, (224, 224))
+            resized_frame = cv2.resize(cropped_frame, (224, 224))
         except Exception:
             logger.warning("Failed to resize image for state classification")
             return
 
+        # Copy for training image saves on worker thread
+        crop_bgr = cv2.cvtColor(cropped_frame, cv2.COLOR_RGB2BGR)
+
+        self._enqueue_task(("classify", camera, now, resized_frame, crop_bgr))
+
+    def _process_task(self, task: Any) -> None:
+        kind = task[0]
+        if kind == "classify":
+            _, camera, timestamp, resized_frame, crop_bgr = task
+            self._classify_state(camera, timestamp, resized_frame, crop_bgr)
+        elif kind == "reload":
+            self.__build_detector()
+
+    def _classify_state(
+        self,
+        camera: str,
+        timestamp: float,
+        resized_frame: np.ndarray,
+        crop_bgr: np.ndarray,
+    ) -> None:
         if self.interpreter is None:
             # When interpreter is None, always save (score is 0.0, which is < 1.0)
             if self._should_save_image(camera, "unknown", 0.0):
@@ -277,15 +289,18 @@ class CustomStateClassificationProcessor(RealTimeProcessorApi):
                 )
                 write_classification_attempt(
                     self.train_dir,
-                    cv2.cvtColor(frame, cv2.COLOR_RGB2BGR),
+                    crop_bgr,
                     "none-none",
-                    now,
+                    timestamp,
                     "unknown",
                     0.0,
                     max_files=save_attempts,
                 )
             return
 
+        if not self.tensor_input_details or not self.tensor_output_details:
+            return
+
         input = np.expand_dims(resized_frame, axis=0)
         self.interpreter.set_tensor(self.tensor_input_details[0]["index"], input)
         self.interpreter.invoke()
@@ -298,7 +313,7 @@ class CustomStateClassificationProcessor(RealTimeProcessorApi):
         )
         best_id = int(np.argmax(probs))
         score = round(probs[best_id], 2)
-        self.__update_metrics(datetime.datetime.now().timestamp() - now)
+        self.__update_metrics(datetime.datetime.now().timestamp() - timestamp)
 
         detected_state = self.labelmap[best_id]
 
@@ -310,9 +325,9 @@ class CustomStateClassificationProcessor(RealTimeProcessorApi):
             )
             write_classification_attempt(
                 self.train_dir,
-                cv2.cvtColor(frame, cv2.COLOR_RGB2BGR),
+                crop_bgr,
                 "none-none",
-                now,
+                timestamp,
                 detected_state,
                 score,
                 max_files=save_attempts,
@@ -327,9 +342,14 @@ class CustomStateClassificationProcessor(RealTimeProcessorApi):
         verified_state = self.verify_state_change(camera, detected_state)
 
         if verified_state is not None:
-            self.requestor.send_data(
-                f"{camera}/classification/{self.model_config.name}",
-                verified_state,
+            self._emit_result(
+                {
+                    "type": "classification",
+                    "processor": "state",
+                    "model_name": self.model_config.name,
+                    "camera": camera,
+                    "state": verified_state,
+                }
             )
 
     def handle_request(
@@ -337,14 +357,19 @@ class CustomStateClassificationProcessor(RealTimeProcessorApi):
     ) -> dict[str, Any] | None:
         if topic == EmbeddingsRequestEnum.reload_classification_model.value:
             if request_data.get("model_name") == self.model_config.name:
-                self.__build_detector()
-                logger.info(
-                    f"Successfully loaded updated model for {self.model_config.name}"
-                )
-                return {
-                    "success": True,
-                    "message": f"Loaded {self.model_config.name} model.",
-                }
+
+                def _do_reload(data: dict[str, Any]) -> dict[str, Any]:
+                    self.__build_detector()
+                    logger.info(
+                        f"Successfully loaded updated model for {self.model_config.name}"
+                    )
+                    return {
+                        "success": True,
+                        "message": f"Loaded {self.model_config.name} model.",
+                    }
+
+                result: dict[str, Any] = self._enqueue_request(_do_reload, request_data)
+                return result
             else:
                 return None
         else:
@@ -354,7 +379,7 @@ class CustomStateClassificationProcessor(RealTimeProcessorApi):
         pass
 
 
-class CustomObjectClassificationProcessor(RealTimeProcessorApi):
+class CustomObjectClassificationProcessor(DeferredRealtimeProcessorApi):
     def __init__(
         self,
         config: FrigateConfig,
@@ -363,7 +388,7 @@ class CustomObjectClassificationProcessor(RealTimeProcessorApi):
         requestor: InterProcessRequestor,
         metrics: DataProcessorMetrics,
     ):
-        super().__init__(config, metrics)
+        super().__init__(config, metrics, max_queue=8)
         self.model_config = model_config
 
         if not self.model_config.name:
@@ -536,18 +561,41 @@ class CustomObjectClassificationProcessor(RealTimeProcessorApi):
         )
 
         rgb = cv2.cvtColor(frame, cv2.COLOR_YUV2RGB_I420)
-        crop = rgb[
-            y:y2,
-            x:x2,
-        ]
+        crop = rgb[y:y2, x:x2]
 
-        if crop.shape != (224, 224):
-            try:
-                resized_crop = cv2.resize(crop, (224, 224))
-            except Exception:
-                logger.warning("Failed to resize image for state classification")
-                return
+        try:
+            resized_crop = cv2.resize(crop, (224, 224))
+        except Exception:
+            logger.warning("Failed to resize image for object classification")
+            return
 
+        # Copy crop for training images (will be used on worker thread)
+        crop_bgr = cv2.cvtColor(crop, cv2.COLOR_RGB2BGR)
+
+        self._enqueue_task(
+            ("classify", object_id, obj_data["camera"], now, resized_crop, crop_bgr)
+        )
+
+    def _process_task(self, task: Any) -> None:
+        kind = task[0]
+        if kind == "classify":
+            _, object_id, camera, timestamp, resized_crop, crop_bgr = task
+            self._classify_object(object_id, camera, timestamp, resized_crop, crop_bgr)
+        elif kind == "expire":
+            _, object_id = task
+            if object_id in self.classification_history:
+                self.classification_history.pop(object_id)
+        elif kind == "reload":
+            self.__build_detector()
+
+    def _classify_object(
+        self,
+        object_id: str,
+        camera: str,
+        timestamp: float,
+        resized_crop: np.ndarray,
+        crop_bgr: np.ndarray,
+    ) -> None:
         if self.interpreter is None:
             save_attempts = (
                 self.model_config.save_attempts
@@ -556,9 +604,9 @@ class CustomObjectClassificationProcessor(RealTimeProcessorApi):
             )
             write_classification_attempt(
                 self.train_dir,
-                cv2.cvtColor(crop, cv2.COLOR_RGB2BGR),
+                crop_bgr,
                 object_id,
-                now,
+                timestamp,
                 "unknown",
                 0.0,
                 max_files=save_attempts,
@@ -569,7 +617,10 @@ class CustomObjectClassificationProcessor(RealTimeProcessorApi):
             if object_id not in self.classification_history:
                 self.classification_history[object_id] = []
 
-            self.classification_history[object_id].append(("unknown", 0.0, now))
+            self.classification_history[object_id].append(("unknown", 0.0, timestamp))
+            return
+
+        if not self.tensor_input_details or not self.tensor_output_details:
             return
 
         input = np.expand_dims(resized_crop, axis=0)
@@ -584,7 +635,7 @@ class CustomObjectClassificationProcessor(RealTimeProcessorApi):
         )
         best_id = int(np.argmax(probs))
         score = round(probs[best_id], 2)
-        self.__update_metrics(datetime.datetime.now().timestamp() - now)
+        self.__update_metrics(datetime.datetime.now().timestamp() - timestamp)
 
         save_attempts = (
             self.model_config.save_attempts
@@ -593,9 +644,9 @@ class CustomObjectClassificationProcessor(RealTimeProcessorApi):
         )
         write_classification_attempt(
             self.train_dir,
-            cv2.cvtColor(crop, cv2.COLOR_RGB2BGR),
+            crop_bgr,
             object_id,
-            now,
+            timestamp,
             self.labelmap[best_id],
             score,
             max_files=save_attempts,
@@ -610,92 +661,57 @@ class CustomObjectClassificationProcessor(RealTimeProcessorApi):
         sub_label = self.labelmap[best_id]
 
         logger.debug(
-            f"{self.model_config.name}: Object {object_id} (label={obj_data['label']}) passed threshold with sub_label={sub_label}, score={score}"
+            f"{self.model_config.name}: Object {object_id} passed threshold with sub_label={sub_label}, score={score}"
         )
 
         consensus_label, consensus_score = self.get_weighted_score(
-            object_id, sub_label, score, now
+            object_id, sub_label, score, timestamp
         )
 
         logger.debug(
             f"{self.model_config.name}: get_weighted_score returned consensus_label={consensus_label}, consensus_score={consensus_score} for {object_id}"
         )
 
-        if consensus_label is not None:
-            camera = obj_data["camera"]
-            logger.debug(
-                f"{self.model_config.name}: Publishing sub_label={consensus_label} for {obj_data['label']} object {object_id} on {camera}"
+        if consensus_label is not None and self.model_config.object_config is not None:
+            self._emit_result(
+                {
+                    "type": "classification",
+                    "processor": "object",
+                    "model_name": self.model_config.name,
+                    "classification_type": self.model_config.object_config.classification_type,
+                    "object_id": object_id,
+                    "camera": camera,
+                    "timestamp": timestamp,
+                    "label": consensus_label,
+                    "score": consensus_score,
+                }
             )
 
-            if (
-                self.model_config.object_config.classification_type
-                == ObjectClassificationType.sub_label
-            ):
-                self.sub_label_publisher.publish(
-                    (object_id, consensus_label, consensus_score),
-                    EventMetadataTypeEnum.sub_label,
-                )
-                self.requestor.send_data(
-                    "tracked_object_update",
-                    json.dumps(
-                        {
-                            "type": TrackedObjectUpdateTypesEnum.classification,
-                            "id": object_id,
-                            "camera": camera,
-                            "timestamp": now,
-                            "model": self.model_config.name,
-                            "sub_label": consensus_label,
-                            "score": consensus_score,
-                        }
-                    ),
-                )
-            elif (
-                self.model_config.object_config.classification_type
-                == ObjectClassificationType.attribute
-            ):
-                self.sub_label_publisher.publish(
-                    (
-                        object_id,
-                        self.model_config.name,
-                        consensus_label,
-                        consensus_score,
-                    ),
-                    EventMetadataTypeEnum.attribute.value,
-                )
-                self.requestor.send_data(
-                    "tracked_object_update",
-                    json.dumps(
-                        {
-                            "type": TrackedObjectUpdateTypesEnum.classification,
-                            "id": object_id,
-                            "camera": camera,
-                            "timestamp": now,
-                            "model": self.model_config.name,
-                            "attribute": consensus_label,
-                            "score": consensus_score,
-                        }
-                    ),
-                )
-
-    def handle_request(self, topic: str, request_data: dict) -> dict | None:
+    def handle_request(
+        self, topic: str, request_data: dict[str, Any]
+    ) -> dict[str, Any] | None:
         if topic == EmbeddingsRequestEnum.reload_classification_model.value:
             if request_data.get("model_name") == self.model_config.name:
-                self.__build_detector()
-                logger.info(
-                    f"Successfully loaded updated model for {self.model_config.name}"
-                )
-                return {
-                    "success": True,
-                    "message": f"Loaded {self.model_config.name} model.",
-                }
+
+                def _do_reload(data: dict[str, Any]) -> dict[str, Any]:
+                    self.__build_detector()
+                    logger.info(
+                        f"Successfully loaded updated model for {self.model_config.name}"
+                    )
+                    return {
+                        "success": True,
+                        "message": f"Loaded {self.model_config.name} model.",
+                    }
+
+                result: dict[str, Any] = self._enqueue_request(_do_reload, request_data)
+                return result
             else:
                 return None
         else:
             return None
 
     def expire_object(self, object_id: str, camera: str) -> None:
-        if object_id in self.classification_history:
-            self.classification_history.pop(object_id)
+        self._enqueue_task(("expire", object_id))
 
 
 def write_classification_attempt(

frigate/embeddings/__init__.py

@@ -4,6 +4,7 @@ import base64
 import json
 import logging
 import os
+import sys
 import threading
 from json.decoder import JSONDecodeError
 from multiprocessing.synchronize import Event as MpEvent
@@ -52,6 +53,14 @@ class EmbeddingProcess(FrigateProcess):
             self.stop_event,
         )
         maintainer.start()
+        maintainer.join()
+
+        # If the maintainer thread exited but no shutdown was requested, it
+        # crashed. Surface as a non-zero exit so the watchdog restarts us
+        # instead of treating the silent thread death as a clean shutdown.
+        if not self.stop_event.is_set():
+            logger.error("Embeddings maintainer thread exited unexpectedly")
+            sys.exit(1)
 
 
 class EmbeddingsContext:

frigate/embeddings/maintainer.py

@@ -2,6 +2,7 @@
 
 import base64
 import datetime
+import json
 import logging
 import threading
 from multiprocessing.synchronize import Event as MpEvent
@@ -33,6 +34,7 @@ from frigate.config.camera.updater import (
     CameraConfigUpdateEnum,
     CameraConfigUpdateSubscriber,
 )
+from frigate.config.classification import ObjectClassificationType
 from frigate.data_processing.common.license_plate.model import (
     LicensePlateModelRunner,
 )
@@ -61,6 +63,7 @@ from frigate.db.sqlitevecq import SqliteVecQueueDatabase
 from frigate.events.types import EventTypeEnum, RegenerateDescriptionEnum
 from frigate.genai import GenAIClientManager
 from frigate.models import Event, Recordings, ReviewSegment, Trigger
+from frigate.types import TrackedObjectUpdateTypesEnum
 from frigate.util.builtin import serialize
 from frigate.util.file import get_event_thumbnail_bytes
 from frigate.util.image import SharedMemoryFrameManager
@@ -92,6 +95,7 @@ class EmbeddingMaintainer(threading.Thread):
                 CameraConfigUpdateEnum.add,
                 CameraConfigUpdateEnum.remove,
                 CameraConfigUpdateEnum.object_genai,
+                CameraConfigUpdateEnum.review,
                 CameraConfigUpdateEnum.review_genai,
                 CameraConfigUpdateEnum.semantic_search,
             ],
@@ -273,10 +277,15 @@ class EmbeddingMaintainer(threading.Thread):
             self._process_recordings_updates()
             self._process_review_updates()
             self._process_frame_updates()
+            self._process_deferred_results()
             self._expire_dedicated_lpr()
             self._process_finalized()
             self._process_event_metadata()
 
+        # Shutdown deferred processors
+        for processor in self.realtime_processors:
+            processor.shutdown()
+
         self.config_updater.stop()
         self.enrichment_config_subscriber.stop()
         self.event_subscriber.stop()
@@ -301,6 +310,10 @@ class EmbeddingMaintainer(threading.Thread):
             self._handle_custom_classification_update(topic, payload)
             return
 
+        if topic == "config/genai":
+            self.config.genai = payload
+            self.genai_manager.update_config(self.config)
+
         # Broadcast to all processors — each decides if the topic is relevant
         for processor in self.realtime_processors:
             processor.update_config(topic, payload)
@@ -315,10 +328,9 @@ class EmbeddingMaintainer(threading.Thread):
         model_name = topic.split("/")[-1]
 
         if model_config is None:
-            self.realtime_processors = [
-                processor
-                for processor in self.realtime_processors
-                if not (
+            remaining = []
+            for processor in self.realtime_processors:
+                if (
                     isinstance(
                         processor,
                         (
@@ -327,8 +339,11 @@ class EmbeddingMaintainer(threading.Thread):
                         ),
                     )
                     and processor.model_config.name == model_name
-                )
-            ]
+                ):
+                    processor.shutdown()
+                else:
+                    remaining.append(processor)
+            self.realtime_processors = remaining
 
             logger.info(
                 f"Successfully removed classification processor for model: {model_name}"
@@ -502,10 +517,16 @@ class EmbeddingMaintainer(threading.Thread):
                 try:
                     event: Event = Event.get(Event.id == event_id)
                 except DoesNotExist:
+                    for processor in self.post_processors:
+                        if isinstance(processor, ObjectDescriptionProcessor):
+                            processor.cleanup_event(event_id)
                     continue
 
                 # Skip the event if not an object
                 if event.data.get("type") != "object":
+                    for processor in self.post_processors:
+                        if isinstance(processor, ObjectDescriptionProcessor):
+                            processor.cleanup_event(event_id)
                     continue
 
                 # Extract valid thumbnail
@@ -696,6 +717,68 @@ class EmbeddingMaintainer(threading.Thread):
 
         self.frame_manager.close(frame_name)
 
+    def _process_deferred_results(self) -> None:
+        """Drain results from deferred processors and perform IPC side-effects."""
+        for processor in self.realtime_processors:
+            results = processor.drain_results()
+
+            for result in results:
+                if result.get("type") != "classification":
+                    continue
+
+                if result["processor"] == "state":
+                    self.requestor.send_data(
+                        f"{result['camera']}/classification/{result['model_name']}",
+                        result["state"],
+                    )
+                elif result["processor"] == "object":
+                    object_id = result["object_id"]
+                    camera = result["camera"]
+                    timestamp = result["timestamp"]
+                    model_name = result["model_name"]
+                    label = result["label"]
+                    score = result["score"]
+                    classification_type = result["classification_type"]
+
+                    if classification_type == ObjectClassificationType.sub_label:
+                        self.event_metadata_publisher.publish(
+                            (object_id, label, score),
+                            EventMetadataTypeEnum.sub_label,
+                        )
+                        self.requestor.send_data(
+                            "tracked_object_update",
+                            json.dumps(
+                                {
+                                    "type": TrackedObjectUpdateTypesEnum.classification,
+                                    "id": object_id,
+                                    "camera": camera,
+                                    "timestamp": timestamp,
+                                    "model": model_name,
+                                    "sub_label": label,
+                                    "score": score,
+                                }
+                            ),
+                        )
+                    elif classification_type == ObjectClassificationType.attribute:
+                        self.event_metadata_publisher.publish(
+                            (object_id, model_name, label, score),
+                            EventMetadataTypeEnum.attribute.value,
+                        )
+                        self.requestor.send_data(
+                            "tracked_object_update",
+                            json.dumps(
+                                {
+                                    "type": TrackedObjectUpdateTypesEnum.classification,
+                                    "id": object_id,
+                                    "camera": camera,
+                                    "timestamp": timestamp,
+                                    "model": model_name,
+                                    "attribute": label,
+                                    "score": score,
+                                }
+                            ),
+                        )
+
     def _embed_thumbnail(self, event_id: str, thumbnail: bytes) -> None:
         """Embed the thumbnail for an event."""
         if not self.config.semantic_search.enabled:

frigate/events/audio.py

@@ -205,6 +205,7 @@ class AudioEventMaintainer(threading.Thread):
             self.transcription_thread.start()
 
         self.was_enabled = camera.enabled
+        self.was_audio_enabled = camera.audio.enabled
 
     def detect_audio(self, audio: np.ndarray) -> None:
         if not self.camera_config.audio.enabled or self.stop_event.is_set():
@@ -363,6 +364,17 @@ class AudioEventMaintainer(threading.Thread):
                 time.sleep(0.1)
                 continue
 
+            audio_enabled = self.camera_config.audio.enabled
+            if audio_enabled != self.was_audio_enabled:
+                if not audio_enabled:
+                    self.logger.debug(
+                        f"Disabling audio detections for {self.camera_config.name}, ending events"
+                    )
+                    self.requestor.send_data(
+                        EXPIRE_AUDIO_ACTIVITY, self.camera_config.name
+                    )
+                self.was_audio_enabled = audio_enabled
+
             self.read_audio()
 
         if self.audio_listener:

frigate/genai/__init__.py

@@ -2,6 +2,7 @@
 
 import datetime
 import importlib
+import json
 import logging
 import os
 import re
@@ -9,6 +10,7 @@ from typing import Any, Callable, Optional
 
 import numpy as np
 from playhouse.shortcuts import model_to_dict
+from pydantic import ValidationError
 
 from frigate.config import CameraConfig, GenAIConfig, GenAIProviderEnum
 from frigate.const import CLIPS_DIR
@@ -106,8 +108,8 @@ When forming your description:
 ## Response Field Guidelines
 
 Respond with a JSON object matching the provided schema. Field-specific guidance:
-- `scene`: Describe how the sequence begins, then the progression of events — all significant movements and actions in order. For example, if a vehicle arrives and then a person exits, describe both sequentially. Always use subject names from "Objects in Scene" — do not replace named subjects with generic terms like "a person" or "the individual". Your description should align with and support the threat level you assign.
-- `title`: Characterize **what took place and where** — interpret the overall purpose or outcome, do not simply compress the scene description into fewer words. Include the relevant location (zone, area, or entry point). Always include subject names from "Objects in Scene" — do not replace named subjects with generic terms. No editorial qualifiers like "routine" or "suspicious."
+- `scene`: Describe how the sequence begins, then the progression of events — all significant movements and actions in order. For example, if a vehicle arrives and then a person exits, describe both sequentially. For named subjects (those with a `←` separator in "Objects in Scene"), always use their name — do not replace them with generic terms. For unnamed objects (e.g., "person", "car"), refer to them naturally with articles (e.g., "a person", "the car"). Your description should align with and support the threat level you assign.
+- `title`: Characterize **what took place and where** — interpret the overall purpose or outcome, do not simply compress the scene description into fewer words. Include the relevant location (zone, area, or entry point). For named subjects, always use their name. For unnamed objects, refer to them naturally with articles. No editorial qualifiers like "routine" or "suspicious."
 - `potential_threat_level`: Must be consistent with your scene description and the activity patterns above.
 {get_concern_prompt()}
 
@@ -151,9 +153,6 @@ Each line represents a detection state, not necessarily unique individuals. The
             if "other_concerns" in schema.get("required", []):
                 schema["required"].remove("other_concerns")
 
-        # OpenAI strict mode requires additionalProperties: false on all objects
-        schema["additionalProperties"] = False
-
         response_format = {
             "type": "json_schema",
             "json_schema": {
@@ -181,7 +180,36 @@ Each line represents a detection state, not necessarily unique individuals. The
 
             try:
                 metadata = ReviewMetadata.model_validate_json(clean_json)
+            except ValidationError as ve:
+                # Constraint violations (length, item count, ranges) are logged
+                # at debug and the response is kept anyway — a slightly
+                # off-spec answer is still usable, and dropping the whole
+                # response loses the narrative content the model produced.
+                for err in ve.errors():
+                    loc = ".".join(str(p) for p in err["loc"]) or "<root>"
+                    logger.debug(
+                        "Review metadata soft validation: %s — %s (input: %r)",
+                        loc,
+                        err["msg"],
+                        err.get("input"),
+                    )
+                try:
+                    raw = json.loads(clean_json)
+                except json.JSONDecodeError as je:
+                    logger.error("Failed to parse review description JSON: %s", je)
+                    return None
+                # observations and confidence are required on the model; fill an empty default
+                # if the response omitted it so attribute access stays safe.
+                raw.setdefault("observations", [])
+                raw.setdefault("confidence", 0.0)
+                metadata = ReviewMetadata.model_construct(**raw)
+            except Exception as e:
+                logger.error(
+                    f"Failed to parse review description as the response did not match expected format. {e}"
+                )
+                return None
 
+            try:
                 # Normalize confidence if model returned a percentage (e.g. 85 instead of 0.85)
                 if metadata.confidence > 1.0:
                     metadata.confidence = min(metadata.confidence / 100.0, 1.0)
@@ -190,15 +218,16 @@ Each line represents a detection state, not necessarily unique individuals. The
                 if any("←" in obj for obj in review_data["unified_objects"]):
                     metadata.potential_threat_level = 0
 
+                metadata.title = metadata.title[0].upper() + metadata.title[1:]
                 metadata.time = review_data["start"]
                 return metadata
             except Exception as e:
-                # rarely LLMs can fail to follow directions on output format
-                logger.warning(
-                    f"Failed to parse review description as the response did not match expected format. {e}"
-                )
+                logger.error(f"Failed to post-process review metadata: {e}")
                 return None
         else:
+            logger.debug(
+                f"Invalid response received from GenAI provider for review description on {review_data['camera']}. Response: {response}",
+            )
             return None
 
     def generate_review_summary(
@@ -340,6 +369,14 @@ Guidelines:
         """Get the context window size for this provider in tokens."""
         return 4096
 
+    def estimate_image_tokens(self, width: int, height: int) -> float:
+        """Estimate prompt tokens consumed by a single image of the given dimensions.
+
+        Default heuristic: ~1 token per 1250 pixels. Providers that can measure or
+        know their model's exact image-token cost should override.
+        """
+        return (width * height) / 1250
+
     def embed(
         self,
         texts: list[str] | None = None,

frigate/genai/gemini.py

@@ -136,22 +136,44 @@ class GeminiClient(GenAIClient):
                             )
                         )
                 elif role == "assistant":
-                    gemini_messages.append(
-                        types.Content(
-                            role="model", parts=[types.Part.from_text(text=content)]
-                        )
-                    )
+                    parts: list[types.Part] = []
+                    if content:
+                        parts.append(types.Part.from_text(text=content))
+                    for tc in msg.get("tool_calls") or []:
+                        func = tc.get("function") or {}
+                        tc_name = func.get("name") or ""
+                        tc_args: Any = func.get("arguments")
+                        if isinstance(tc_args, str):
+                            try:
+                                tc_args = json.loads(tc_args)
+                            except (json.JSONDecodeError, TypeError):
+                                tc_args = {}
+                        if not isinstance(tc_args, dict):
+                            tc_args = {}
+                        if tc_name:
+                            parts.append(
+                                types.Part.from_function_call(
+                                    name=tc_name, args=tc_args
+                                )
+                            )
+                    if not parts:
+                        parts.append(types.Part.from_text(text=" "))
+                    gemini_messages.append(types.Content(role="model", parts=parts))
                 elif role == "tool":
                     # Handle tool response
-                    function_response = {
-                        "name": msg.get("name", ""),
-                        "response": content,
-                    }
+                    response_payload = (
+                        content if isinstance(content, dict) else {"result": content}
+                    )
                     gemini_messages.append(
                         types.Content(
                             role="function",
                             parts=[
-                                types.Part.from_function_response(function_response)  # type: ignore[misc,call-arg,arg-type]
+                                types.Part.from_function_response(
+                                    name=msg.get("name")
+                                    or msg.get("tool_call_id")
+                                    or "",
+                                    response=response_payload,
+                                )
                             ],
                         )
                     )
@@ -343,22 +365,44 @@ class GeminiClient(GenAIClient):
                             )
                         )
                 elif role == "assistant":
-                    gemini_messages.append(
-                        types.Content(
-                            role="model", parts=[types.Part.from_text(text=content)]
-                        )
-                    )
+                    parts: list[types.Part] = []
+                    if content:
+                        parts.append(types.Part.from_text(text=content))
+                    for tc in msg.get("tool_calls") or []:
+                        func = tc.get("function") or {}
+                        tc_name = func.get("name") or ""
+                        tc_args: Any = func.get("arguments")
+                        if isinstance(tc_args, str):
+                            try:
+                                tc_args = json.loads(tc_args)
+                            except (json.JSONDecodeError, TypeError):
+                                tc_args = {}
+                        if not isinstance(tc_args, dict):
+                            tc_args = {}
+                        if tc_name:
+                            parts.append(
+                                types.Part.from_function_call(
+                                    name=tc_name, args=tc_args
+                                )
+                            )
+                    if not parts:
+                        parts.append(types.Part.from_text(text=" "))
+                    gemini_messages.append(types.Content(role="model", parts=parts))
                 elif role == "tool":
                     # Handle tool response
-                    function_response = {
-                        "name": msg.get("name", ""),
-                        "response": content,
-                    }
+                    response_payload = (
+                        content if isinstance(content, dict) else {"result": content}
+                    )
                     gemini_messages.append(
                         types.Content(
                             role="function",
                             parts=[
-                                types.Part.from_function_response(function_response)  # type: ignore[misc,call-arg,arg-type]
+                                types.Part.from_function_response(
+                                    name=msg.get("name")
+                                    or msg.get("tool_call_id")
+                                    or "",
+                                    response=response_payload,
+                                )
                             ],
                         )
                     )

frigate/genai/llama_cpp.py

@@ -42,6 +42,9 @@ class LlamaCppClient(GenAIClient):
     _supports_vision: bool
     _supports_audio: bool
     _supports_tools: bool
+    _image_token_cache: dict[tuple[int, int], int]
+    _text_baseline_tokens: int | None
+    _media_marker: str
 
     def _init_provider(self) -> str | None:
         """Initialize the client and query model metadata from the server."""
@@ -52,6 +55,9 @@ class LlamaCppClient(GenAIClient):
         self._supports_vision = False
         self._supports_audio = False
         self._supports_tools = False
+        self._image_token_cache = {}
+        self._text_baseline_tokens = None
+        self._media_marker = "<__media__>"
 
         base_url = (
             self.genai_config.base_url.rstrip("/")
@@ -137,6 +143,13 @@ class LlamaCppClient(GenAIClient):
             chat_caps = props.get("chat_template_caps", {})
             self._supports_tools = chat_caps.get("supports_tools", False)
 
+            # Media marker for multimodal embeddings; the server randomizes this
+            # per startup unless LLAMA_MEDIA_MARKER is set, so we must read it
+            # from /props rather than hardcoding "<__media__>".
+            media_marker = props.get("media_marker")
+            if isinstance(media_marker, str) and media_marker:
+                self._media_marker = media_marker
+
             logger.info(
                 "llama.cpp model '%s' initialized — context: %s, vision: %s, audio: %s, tools: %s",
                 configured_model,
@@ -238,10 +251,15 @@ class LlamaCppClient(GenAIClient):
 
     def list_models(self) -> list[str]:
         """Return available model IDs from the llama.cpp server."""
-        if self.provider is None:
+        base_url = self.provider or (
+            self.genai_config.base_url.rstrip("/")
+            if self.genai_config.base_url
+            else None
+        )
+        if base_url is None:
             return []
         try:
-            response = requests.get(f"{self.provider}/v1/models", timeout=10)
+            response = requests.get(f"{base_url}/v1/models", timeout=10)
             response.raise_for_status()
             models = []
             for m in response.json().get("data", []):
@@ -267,6 +285,91 @@ class LlamaCppClient(GenAIClient):
             return self._context_size
         return 4096
 
+    def estimate_image_tokens(self, width: int, height: int) -> float:
+        """Probe the llama.cpp server to learn the model's image-token cost at the
+        requested dimensions.
+
+        llama.cpp's image tokenization is a deterministic function of dimensions and
+        the loaded mmproj, so the result is cached per (width, height) for the
+        lifetime of the process. Falls back to the base pixel heuristic if the
+        server is unreachable or the response is malformed.
+        """
+        if self.provider is None:
+            return super().estimate_image_tokens(width, height)
+
+        cached = self._image_token_cache.get((width, height))
+
+        if cached is not None:
+            return cached
+
+        try:
+            baseline = self._probe_baseline_tokens()
+            with_image = self._probe_image_prompt_tokens(width, height)
+            tokens = max(1, with_image - baseline)
+        except Exception as e:
+            logger.debug(
+                "llama.cpp image-token probe failed for %dx%d (%s); using heuristic",
+                width,
+                height,
+                e,
+            )
+            return super().estimate_image_tokens(width, height)
+
+        self._image_token_cache[(width, height)] = tokens
+        logger.debug(
+            "llama.cpp model '%s' uses ~%d tokens for %dx%d images",
+            self.genai_config.model,
+            tokens,
+            width,
+            height,
+        )
+        return tokens
+
+    def _probe_baseline_tokens(self) -> int:
+        """Return prompt_tokens for a minimal text-only request. Cached after first call."""
+        if self._text_baseline_tokens is not None:
+            return self._text_baseline_tokens
+
+        self._text_baseline_tokens = self._probe_prompt_tokens(
+            [{"type": "text", "text": "."}]
+        )
+        return self._text_baseline_tokens
+
+    def _probe_image_prompt_tokens(self, width: int, height: int) -> int:
+        """Return prompt_tokens for a single synthetic image plus minimal text."""
+        img = Image.new("RGB", (width, height), (128, 128, 128))
+        buf = io.BytesIO()
+        img.save(buf, format="JPEG", quality=60)
+        encoded = base64.b64encode(buf.getvalue()).decode("utf-8")
+        return self._probe_prompt_tokens(
+            [
+                {"type": "text", "text": "."},
+                {
+                    "type": "image_url",
+                    "image_url": {"url": f"data:image/jpeg;base64,{encoded}"},
+                },
+            ]
+        )
+
+    def _probe_prompt_tokens(self, content: list[dict[str, Any]]) -> int:
+        """POST a 1-token chat completion and return reported prompt_tokens.
+
+        Uses a generous timeout to absorb a cold model load on the first probe
+        when the server lazily loads models on demand (e.g. llama-swap).
+        """
+        payload = {
+            "model": self.genai_config.model,
+            "messages": [{"role": "user", "content": content}],
+            "max_tokens": 1,
+        }
+        response = requests.post(
+            f"{self.provider}/v1/chat/completions",
+            json=payload,
+            timeout=60,
+        )
+        response.raise_for_status()
+        return int(response.json()["usage"]["prompt_tokens"])
+
     def _build_payload(
         self,
         messages: list[dict[str, Any]],
@@ -371,10 +474,11 @@ class LlamaCppClient(GenAIClient):
             jpeg_bytes = _to_jpeg(img)
             to_encode = jpeg_bytes if jpeg_bytes is not None else img
             encoded = base64.b64encode(to_encode).decode("utf-8")
-            # prompt_string must contain <__media__> placeholder for image tokenization
+            # prompt_string must contain the server's media marker placeholder.
+            # The marker is randomized per server startup (read from /props).
             content.append(
                 {
-                    "prompt_string": "<__media__>\n",
+                    "prompt_string": f"{self._media_marker}\n",
                     "multimodal_data": [encoded],  # type: ignore[dict-item]
                 }
             )

frigate/genai/ollama.py

@@ -113,6 +113,15 @@ class OllamaClient(GenAIClient):
                 schema = response_format.get("json_schema", {}).get("schema")
                 if schema:
                     ollama_options["format"] = self._clean_schema_for_ollama(schema)
+            logger.debug(
+                "Ollama generate request: model=%s, prompt_len=%s, image_count=%s, "
+                "has_format=%s, options=%s",
+                self.genai_config.model,
+                len(prompt),
+                len(images) if images else 0,
+                "format" in ollama_options,
+                {k: v for k, v in ollama_options.items() if k != "format"},
+            )
             result = self.provider.generate(
                 self.genai_config.model,
                 prompt,
@@ -120,9 +129,24 @@ class OllamaClient(GenAIClient):
                 **ollama_options,
             )
             logger.debug(
-                f"Ollama tokens used: eval_count={result.get('eval_count')}, prompt_eval_count={result.get('prompt_eval_count')}"
+                "Ollama generate response: done=%s, done_reason=%s, eval_count=%s, "
+                "prompt_eval_count=%s, response_len=%s",
+                result.get("done"),
+                result.get("done_reason"),
+                result.get("eval_count"),
+                result.get("prompt_eval_count"),
+                len(result.get("response", "") or ""),
             )
-            return str(result["response"]).strip()
+            response_text = str(result["response"]).strip()
+            if not response_text:
+                logger.warning(
+                    "Ollama returned a blank response for model %s (done_reason=%s, "
+                    "eval_count=%s). Check model output, ensure thinking is disabled.",
+                    self.genai_config.model,
+                    result.get("done_reason"),
+                    result.get("eval_count"),
+                )
+            return response_text
         except (
             TimeoutException,
             ResponseError,
@@ -134,10 +158,20 @@ class OllamaClient(GenAIClient):
 
     def list_models(self) -> list[str]:
         """Return available model names from the Ollama server."""
-        if self.provider is None:
-            return []
+        client = self.provider
+        if client is None:
+            # Provider init may have failed due to invalid model, but we can
+            # still list available models with a fresh client.
+            if not self.genai_config.base_url:
+                return []
+            try:
+                client = ApiClient(
+                    host=self.genai_config.base_url, timeout=self.timeout
+                )
+            except Exception:
+                return []
         try:
-            response = self.provider.list()
+            response = client.list()
             return sorted(
                 m.get("name", m.get("model", "")) for m in response.get("models", [])
             )

frigate/genai/openai.py

@@ -73,14 +73,39 @@ class OpenAIClient(GenAIClient):
                 **self.genai_config.runtime_options,
             }
             if response_format:
+                # OpenAI strict mode requires additionalProperties: false on the schema
+                if response_format.get("type") == "json_schema" and response_format.get(
+                    "json_schema", {}
+                ).get("strict"):
+                    schema = response_format.get("json_schema", {}).get("schema")
+                    if isinstance(schema, dict):
+                        schema["additionalProperties"] = False
                 request_params["response_format"] = response_format
+
             result = self.provider.chat.completions.create(**request_params)
+
             if (
                 result is not None
                 and hasattr(result, "choices")
                 and len(result.choices) > 0
             ):
-                return str(result.choices[0].message.content.strip())
+                message = result.choices[0].message
+                content = message.content
+
+                if not content:
+                    # When reasoning is enabled for some OpenAI backends the actual response
+                    # is incorrectly placed in reasoning_content instead of content.
+                    # This is buggy/incorrect behavior — reasoning should not be
+                    # enabled for these models.
+                    reasoning_content = getattr(message, "reasoning_content", None)
+                    if reasoning_content:
+                        logger.warning(
+                            "Response content was empty but reasoning_content was provided; "
+                            "reasoning appears to be enabled and should be disabled for this model."
+                        )
+                        content = reasoning_content
+
+                return str(content.strip()) if content else None
             return None
         except (TimeoutException, Exception) as e:
             logger.warning("OpenAI returned an error: %s", str(e))

frigate/jobs/export.py

@@ -0,0 +1,504 @@
+"""Export job management with queued background execution."""
+
+import logging
+import os
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from queue import Full, Queue
+from typing import Any, Callable, Optional
+
+from peewee import DoesNotExist
+
+from frigate.comms.inter_process import InterProcessRequestor
+from frigate.config import FrigateConfig
+from frigate.const import UPDATE_JOB_STATE
+from frigate.jobs.job import Job
+from frigate.models import Export
+from frigate.record.export import PlaybackSourceEnum, RecordingExporter
+from frigate.types import JobStatusTypesEnum
+
+logger = logging.getLogger(__name__)
+
+# Maximum number of jobs that can sit in the queue waiting to run.
+# Prevents a runaway client from unbounded memory growth.
+MAX_QUEUED_EXPORT_JOBS = 100
+
+# Minimum interval between progress broadcasts. FFmpeg can emit progress
+# events many times per second; we coalesce them so the WebSocket isn't
+# flooded with redundant updates.
+PROGRESS_BROADCAST_MIN_INTERVAL = 1.0
+
+# Delay before removing a completed job from the in-memory map. Gives the
+# frontend a chance to receive the final state via WebSocket before SWR
+# polling takes over.
+COMPLETED_JOB_CLEANUP_DELAY = 5.0
+
+
+class ExportQueueFullError(RuntimeError):
+    """Raised when the export queue is at capacity."""
+
+
+@dataclass
+class ExportJob(Job):
+    """Job state for export operations."""
+
+    job_type: str = "export"
+    camera: str = ""
+    name: Optional[str] = None
+    image_path: Optional[str] = None
+    export_case_id: Optional[str] = None
+    request_start_time: float = 0.0
+    request_end_time: float = 0.0
+    playback_source: str = PlaybackSourceEnum.recordings.value
+    ffmpeg_input_args: Optional[str] = None
+    ffmpeg_output_args: Optional[str] = None
+    cpu_fallback: bool = False
+    current_step: str = "queued"
+    progress_percent: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for API responses.
+
+        Only exposes fields that are part of the public ExportJobModel schema.
+        Internal execution details (image_path, ffmpeg args, cpu_fallback) are
+        intentionally omitted so they don't leak through the API.
+        """
+        return {
+            "id": self.id,
+            "job_type": self.job_type,
+            "status": self.status,
+            "camera": self.camera,
+            "name": self.name,
+            "export_case_id": self.export_case_id,
+            "request_start_time": self.request_start_time,
+            "request_end_time": self.request_end_time,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "error_message": self.error_message,
+            "results": self.results,
+            "current_step": self.current_step,
+            "progress_percent": self.progress_percent,
+        }
+
+
+class ExportQueueWorker(threading.Thread):
+    """Worker that executes queued exports."""
+
+    def __init__(self, manager: "ExportJobManager", worker_index: int) -> None:
+        super().__init__(
+            daemon=True,
+            name=f"export_queue_worker_{worker_index}",
+        )
+        self.manager = manager
+
+    def run(self) -> None:
+        while True:
+            job = self.manager.queue.get()
+
+            try:
+                self.manager.run_job(job)
+            except Exception:
+                logger.exception(
+                    "Export queue worker failed while processing %s", job.id
+                )
+            finally:
+                self.manager.queue.task_done()
+
+
+class JobStatePublisher:
+    """Publishes a single job state payload to the dispatcher.
+
+    Each call opens a short-lived :py:class:`InterProcessRequestor`, sends
+    the payload, and closes the socket. The short-lived design avoids
+    REQ/REP state corruption that would arise from sharing a single REQ
+    socket across the API thread and worker threads (REQ sockets must
+    strictly alternate send/recv).
+
+    With the 1s broadcast throttle in place, socket creation overhead is
+    negligible. The class also exists so tests can substitute a no-op
+    instance instead of stubbing ZMQ — see ``BaseTestHttp.setUp``.
+    """
+
+    def publish(self, payload: dict[str, Any]) -> None:
+        try:
+            requestor = InterProcessRequestor()
+        except Exception as err:
+            logger.warning("Failed to open job state requestor: %s", err)
+            return
+
+        try:
+            requestor.send_data(UPDATE_JOB_STATE, payload)
+        except Exception as err:
+            logger.debug("Job state broadcast failed: %s", err)
+        finally:
+            try:
+                requestor.stop()
+            except Exception:
+                pass
+
+
+class ExportJobManager:
+    """Concurrency-limited manager for queued export jobs."""
+
+    def __init__(
+        self,
+        config: FrigateConfig,
+        max_concurrent: int,
+        max_queued: int = MAX_QUEUED_EXPORT_JOBS,
+        publisher: Optional[JobStatePublisher] = None,
+    ) -> None:
+        self.config = config
+        self.max_concurrent = max(1, max_concurrent)
+        self.queue: Queue[ExportJob] = Queue(maxsize=max(1, max_queued))
+        self.jobs: dict[str, ExportJob] = {}
+        self.lock = threading.Lock()
+        self.workers: list[ExportQueueWorker] = []
+        self.started = False
+        self.publisher = publisher if publisher is not None else JobStatePublisher()
+        self._last_broadcast_monotonic: float = 0.0
+        self._broadcast_throttle_lock = threading.Lock()
+
+    def _broadcast_all_jobs(self, force: bool = False) -> None:
+        """Publish aggregate export job state via the job_state WS topic.
+
+        When ``force`` is False, broadcasts within
+        ``PROGRESS_BROADCAST_MIN_INTERVAL`` of the previous one are skipped
+        to avoid flooding the WebSocket with rapid progress updates.
+        ``force`` bypasses the throttle and is used for status transitions
+        (enqueue/start/finish) where the frontend needs the latest state.
+        """
+        now = time.monotonic()
+        with self._broadcast_throttle_lock:
+            if (
+                not force
+                and now - self._last_broadcast_monotonic
+                < PROGRESS_BROADCAST_MIN_INTERVAL
+            ):
+                return
+            self._last_broadcast_monotonic = now
+
+        with self.lock:
+            active = [
+                j
+                for j in self.jobs.values()
+                if j.status in (JobStatusTypesEnum.queued, JobStatusTypesEnum.running)
+            ]
+
+        any_running = any(j.status == JobStatusTypesEnum.running for j in active)
+        payload: dict[str, Any] = {
+            "job_type": "export",
+            "status": "running" if any_running else "queued",
+            "results": {"jobs": [j.to_dict() for j in active]},
+        }
+
+        try:
+            self.publisher.publish(payload)
+        except Exception as err:
+            logger.warning("Publisher raised during job state broadcast: %s", err)
+
+    def _make_progress_callback(self, job: ExportJob) -> Callable[[str, float], None]:
+        """Build a callback the exporter can invoke during execution."""
+
+        def on_progress(step: str, percent: float) -> None:
+            job.current_step = step
+            job.progress_percent = percent
+            self._broadcast_all_jobs()
+
+        return on_progress
+
+    def _schedule_job_cleanup(self, job_id: str) -> None:
+        """Drop a completed job from ``self.jobs`` after a short delay."""
+
+        def cleanup() -> None:
+            with self.lock:
+                self.jobs.pop(job_id, None)
+
+        timer = threading.Timer(COMPLETED_JOB_CLEANUP_DELAY, cleanup)
+        timer.daemon = True
+        timer.start()
+
+    def ensure_started(self) -> None:
+        """Ensure worker threads are started exactly once."""
+        with self.lock:
+            if self.started:
+                self._restart_dead_workers_locked()
+                return
+
+            for index in range(self.max_concurrent):
+                worker = ExportQueueWorker(self, index)
+                worker.start()
+                self.workers.append(worker)
+
+            self.started = True
+
+    def _restart_dead_workers_locked(self) -> None:
+        for index, worker in enumerate(self.workers):
+            if worker.is_alive():
+                continue
+
+            logger.error(
+                "Export queue worker %s died unexpectedly, restarting", worker.name
+            )
+            replacement = ExportQueueWorker(self, index)
+            replacement.start()
+            self.workers[index] = replacement
+
+    def enqueue(self, job: ExportJob) -> str:
+        """Queue a job for background execution.
+
+        Raises ExportQueueFullError if the queue is at capacity.
+        """
+        self.ensure_started()
+
+        try:
+            self.queue.put_nowait(job)
+        except Full as err:
+            raise ExportQueueFullError(
+                "Export queue is full; try again once current exports finish"
+            ) from err
+
+        with self.lock:
+            self.jobs[job.id] = job
+
+        self._broadcast_all_jobs(force=True)
+
+        return job.id
+
+    def get_job(self, job_id: str) -> Optional[ExportJob]:
+        """Get a job by ID."""
+        with self.lock:
+            return self.jobs.get(job_id)
+
+    def list_active_jobs(self) -> list[ExportJob]:
+        """List queued and running jobs."""
+        with self.lock:
+            return [
+                job
+                for job in self.jobs.values()
+                if job.status in (JobStatusTypesEnum.queued, JobStatusTypesEnum.running)
+            ]
+
+    def cancel_queued_jobs_for_case(self, case_id: str) -> list[ExportJob]:
+        """Cancel queued export jobs assigned to a deleted case."""
+        cancelled_jobs: list[ExportJob] = []
+
+        with self.lock:
+            with self.queue.mutex:
+                retained_jobs: list[ExportJob] = []
+
+                while self.queue.queue:
+                    job = self.queue.queue.popleft()
+
+                    if (
+                        job.export_case_id == case_id
+                        and job.status == JobStatusTypesEnum.queued
+                    ):
+                        job.status = JobStatusTypesEnum.cancelled
+                        job.end_time = time.time()
+                        cancelled_jobs.append(job)
+                        continue
+
+                    retained_jobs.append(job)
+
+                self.queue.queue.extend(retained_jobs)
+
+                if cancelled_jobs:
+                    self.queue.unfinished_tasks = max(
+                        0,
+                        self.queue.unfinished_tasks - len(cancelled_jobs),
+                    )
+                    if self.queue.unfinished_tasks == 0:
+                        self.queue.all_tasks_done.notify_all()
+                    self.queue.not_full.notify_all()
+
+        return cancelled_jobs
+
+    def available_slots(self) -> int:
+        """Approximate number of additional jobs that could be queued right now.
+
+        Uses Queue.qsize() which is best-effort; callers should treat the
+        result as advisory since another thread could enqueue between
+        checking and enqueueing.
+        """
+        return max(0, self.queue.maxsize - self.queue.qsize())
+
+    def run_job(self, job: ExportJob) -> None:
+        """Execute a queued export job."""
+        job.status = JobStatusTypesEnum.running
+        job.start_time = time.time()
+        self._broadcast_all_jobs(force=True)
+
+        exporter = RecordingExporter(
+            self.config,
+            job.id,
+            job.camera,
+            job.name,
+            job.image_path,
+            int(job.request_start_time),
+            int(job.request_end_time),
+            PlaybackSourceEnum(job.playback_source),
+            job.export_case_id,
+            job.ffmpeg_input_args,
+            job.ffmpeg_output_args,
+            job.cpu_fallback,
+            on_progress=self._make_progress_callback(job),
+        )
+
+        try:
+            exporter.run()
+            export = Export.get_or_none(Export.id == job.id)
+            if export is None:
+                job.status = JobStatusTypesEnum.failed
+                job.error_message = "Export failed"
+            elif export.in_progress:
+                job.status = JobStatusTypesEnum.failed
+                job.error_message = "Export did not complete"
+            else:
+                job.status = JobStatusTypesEnum.success
+                job.results = {
+                    "export_id": export.id,
+                    "export_case_id": export.export_case_id,
+                    "video_path": export.video_path,
+                    "thumb_path": export.thumb_path,
+                }
+        except DoesNotExist:
+            job.status = JobStatusTypesEnum.failed
+            job.error_message = "Export not found"
+        except Exception as err:
+            logger.exception("Export job %s failed: %s", job.id, err)
+            job.status = JobStatusTypesEnum.failed
+            job.error_message = str(err)
+        finally:
+            job.end_time = time.time()
+            self._broadcast_all_jobs(force=True)
+            self._schedule_job_cleanup(job.id)
+
+
+_job_manager: Optional[ExportJobManager] = None
+_job_manager_lock = threading.Lock()
+
+
+def _get_max_concurrent(config: FrigateConfig) -> int:
+    return int(config.record.export.max_concurrent)
+
+
+def reap_stale_exports() -> None:
+    """Sweep Export rows stuck with in_progress=True from previous sessions.
+
+    On Frigate startup no export job is alive yet, so any in_progress=True
+    row must be a leftover from a previous session that crashed, was killed
+    mid-export, or returned early from RecordingExporter.run() without
+    flipping the flag. For each stale row we either:
+
+    - delete the row (and any thumb) if the video file is missing or empty,
+      since there is nothing worth recovering
+    - flip in_progress to False if the video file exists on disk and is
+      non-empty, treating it as a completed export the user can manage
+      through the normal UI
+
+    Must only be called when the export job manager is certain to have no
+    active jobs — i.e., at Frigate startup, before any worker runs.
+
+    All exceptions are caught and logged; the caller does not need to wrap
+    this in a try/except. A failure on a single row will not stop the rest
+    of the sweep, and a failure in the top-level query will log and return.
+    """
+    try:
+        stale_exports = list(Export.select().where(Export.in_progress == True))  # noqa: E712
+    except Exception:
+        logger.exception("Failed to query stale in-progress exports")
+        return
+
+    if not stale_exports:
+        logger.debug("No stale in-progress exports found on startup")
+        return
+
+    flipped = 0
+    deleted = 0
+    errored = 0
+
+    for export in stale_exports:
+        try:
+            video_path = export.video_path
+            has_usable_file = False
+
+            if video_path:
+                try:
+                    has_usable_file = os.path.getsize(video_path) > 0
+                except OSError:
+                    has_usable_file = False
+
+            if has_usable_file:
+                # Unassign from any case on recovery: the user should
+                # re-triage a recovered export rather than have it silently
+                # reappear inside a case they curated.
+                Export.update(
+                    {Export.in_progress: False, Export.export_case: None}
+                ).where(Export.id == export.id).execute()
+                flipped += 1
+                logger.info(
+                    "Recovered stale in-progress export %s (file intact on disk)",
+                    export.id,
+                )
+                continue
+
+            if export.thumb_path:
+                Path(export.thumb_path).unlink(missing_ok=True)
+            if video_path:
+                Path(video_path).unlink(missing_ok=True)
+            Export.delete().where(Export.id == export.id).execute()
+            deleted += 1
+            logger.info(
+                "Deleted stale in-progress export %s (no usable file on disk)",
+                export.id,
+            )
+        except Exception:
+            errored += 1
+            logger.exception("Failed to reap stale export %s", export.id)
+
+    logger.info(
+        "Stale export cleanup complete: %d recovered, %d deleted, %d errored",
+        flipped,
+        deleted,
+        errored,
+    )
+
+
+def get_export_job_manager(config: FrigateConfig) -> ExportJobManager:
+    """Get or create the singleton export job manager."""
+    global _job_manager
+
+    with _job_manager_lock:
+        if _job_manager is None:
+            _job_manager = ExportJobManager(config, _get_max_concurrent(config))
+        _job_manager.ensure_started()
+        return _job_manager
+
+
+def start_export_job(config: FrigateConfig, job: ExportJob) -> str:
+    """Queue an export job and return its ID."""
+    return get_export_job_manager(config).enqueue(job)
+
+
+def get_export_job(config: FrigateConfig, job_id: str) -> Optional[ExportJob]:
+    """Get a queued or completed export job by ID."""
+    return get_export_job_manager(config).get_job(job_id)
+
+
+def list_active_export_jobs(config: FrigateConfig) -> list[ExportJob]:
+    """List queued and running export jobs."""
+    return get_export_job_manager(config).list_active_jobs()
+
+
+def cancel_queued_export_jobs_for_case(
+    config: FrigateConfig, case_id: str
+) -> list[ExportJob]:
+    """Cancel queued export jobs that still point at a deleted case."""
+    return get_export_job_manager(config).cancel_queued_jobs_for_case(case_id)
+
+
+def available_export_queue_slots(config: FrigateConfig) -> int:
+    """Approximate number of additional export jobs that could be queued now."""
+    return get_export_job_manager(config).available_slots()

frigate/output/birdseye.py

@@ -8,7 +8,6 @@ import os
 import queue
 import subprocess as sp
 import threading
-import time
 import traceback
 from multiprocessing.synchronize import Event as MpEvent
 from typing import Any, Optional
@@ -19,6 +18,7 @@ import numpy as np
 from frigate.comms.inter_process import InterProcessRequestor
 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.util.image import (
     SharedMemoryFrameManager,
     copy_yuv_to_position,
@@ -236,12 +236,14 @@ class BroadcastThread(threading.Thread):
         converter: FFMpegConverter,
         websocket_server: Any,
         stop_event: MpEvent,
+        config: FrigateConfig,
     ):
         super().__init__()
         self.camera = camera
         self.converter = converter
         self.websocket_server = websocket_server
         self.stop_event = stop_event
+        self.config = config
 
     def run(self) -> None:
         while not self.stop_event.is_set():
@@ -256,6 +258,7 @@ class BroadcastThread(threading.Thread):
                     if (
                         not ws.terminated
                         and ws.environ["PATH_INFO"] == f"/{self.camera}"
+                        and ws_has_camera_access(ws, self.camera, self.config)
                     ):
                         try:
                             ws.send(buf, binary=True)
@@ -806,7 +809,11 @@ class Birdseye:
             config.birdseye.restream,
         )
         self.broadcaster = BroadcastThread(
-            "birdseye", self.converter, websocket_server, stop_event
+            "birdseye",
+            self.converter,
+            websocket_server,
+            stop_event,
+            config,
         )
         self.birdseye_manager = BirdsEyeFrameManager(self.config, stop_event)
         self.frame_manager = SharedMemoryFrameManager()
@@ -874,7 +881,7 @@ class Birdseye:
                 coordinates = self.birdseye_manager.get_camera_coordinates()
                 self.requestor.send_data(UPDATE_BIRDSEYE_LAYOUT, coordinates)
         if self._idle_interval:
-            now = time.monotonic()
+            now = datetime.datetime.now().timestamp()
             is_idle = len(self.birdseye_manager.camera_layout) == 0
             if (
                 is_idle

frigate/output/camera.py

@@ -7,7 +7,8 @@ import threading
 from multiprocessing.synchronize import Event as MpEvent
 from typing import Any
 
-from frigate.config import CameraConfig, FfmpegConfig
+from frigate.config import CameraConfig, FfmpegConfig, FrigateConfig
+from frigate.output.ws_auth import ws_has_camera_access
 
 logger = logging.getLogger(__name__)
 
@@ -102,12 +103,14 @@ class BroadcastThread(threading.Thread):
         converter: FFMpegConverter,
         websocket_server: Any,
         stop_event: MpEvent,
+        config: FrigateConfig,
     ):
         super().__init__()
         self.camera = camera
         self.converter = converter
         self.websocket_server = websocket_server
         self.stop_event = stop_event
+        self.config = config
 
     def run(self) -> None:
         while not self.stop_event.is_set():
@@ -122,6 +125,7 @@ class BroadcastThread(threading.Thread):
                     if (
                         not ws.terminated
                         and ws.environ["PATH_INFO"] == f"/{self.camera}"
+                        and ws_has_camera_access(ws, self.camera, self.config)
                     ):
                         try:
                             ws.send(buf, binary=True)
@@ -135,7 +139,11 @@ class BroadcastThread(threading.Thread):
 
 class JsmpegCamera:
     def __init__(
-        self, config: CameraConfig, stop_event: MpEvent, websocket_server: Any
+        self,
+        config: CameraConfig,
+        frigate_config: FrigateConfig,
+        stop_event: MpEvent,
+        websocket_server: Any,
     ) -> None:
         self.config = config
         self.input: queue.Queue[bytes] = queue.Queue(maxsize=config.detect.fps)
@@ -154,7 +162,11 @@ class JsmpegCamera:
             config.live.quality,
         )
         self.broadcaster = BroadcastThread(
-            config.name or "", self.converter, websocket_server, stop_event
+            config.name or "",
+            self.converter,
+            websocket_server,
+            stop_event,
+            frigate_config,
         )
 
         self.converter.start()

frigate/output/output.py

@@ -32,6 +32,7 @@ from frigate.const import (
 from frigate.output.birdseye import Birdseye
 from frigate.output.camera import JsmpegCamera
 from frigate.output.preview import PreviewRecorder
+from frigate.output.ws_auth import ws_has_camera_access
 from frigate.util.image import SharedMemoryFrameManager, get_blank_yuv_frame
 from frigate.util.process import FrigateProcess
 
@@ -102,7 +103,7 @@ class OutputProcess(FrigateProcess):
     ) -> None:
         camera_config = self.config.cameras[camera]
         jsmpeg_cameras[camera] = JsmpegCamera(
-            camera_config, self.stop_event, websocket_server
+            camera_config, self.config, self.stop_event, websocket_server
         )
         preview_recorders[camera] = PreviewRecorder(camera_config)
         preview_write_times[camera] = 0
@@ -262,6 +263,7 @@ class OutputProcess(FrigateProcess):
             # send camera frame to ffmpeg process if websockets are connected
             if any(
                 ws.environ["PATH_INFO"].endswith(camera)
+                and ws_has_camera_access(ws, camera, self.config)
                 for ws in websocket_server.manager
             ):
                 # write to the converter for the camera if clients are listening to the specific camera
@@ -275,6 +277,7 @@ class OutputProcess(FrigateProcess):
                     self.config.birdseye.restream
                     or any(
                         ws.environ["PATH_INFO"].endswith("birdseye")
+                        and ws_has_camera_access(ws, "birdseye", self.config)
                         for ws in websocket_server.manager
                     )
                 )

frigate/output/ws_auth.py

@@ -0,0 +1,43 @@
+"""Authorization helpers for JSMPEG websocket clients."""
+
+from typing import Any
+
+from frigate.config import FrigateConfig
+from frigate.models import User
+
+
+def _get_valid_ws_roles(ws: Any, config: FrigateConfig) -> list[str]:
+    role_header = ws.environ.get("HTTP_REMOTE_ROLE", "")
+    roles = [
+        role.strip()
+        for role in role_header.split(config.proxy.separator)
+        if role.strip()
+    ]
+    return [role for role in roles if role in config.auth.roles]
+
+
+def ws_has_camera_access(ws: Any, camera_name: str, config: FrigateConfig) -> bool:
+    """Return True when a websocket client is authorized for the camera path."""
+    roles = _get_valid_ws_roles(ws, config)
+
+    if not roles:
+        return False
+
+    roles_dict = config.auth.roles
+
+    # Birdseye is a composite stream, so only users with unrestricted access
+    # should receive it.
+    if camera_name == "birdseye":
+        return any(role == "admin" or not roles_dict.get(role) for role in roles)
+
+    all_camera_names = set(config.cameras.keys())
+
+    for role in roles:
+        if role == "admin" or not roles_dict.get(role):
+            return True
+
+        allowed_cameras = User.get_allowed_cameras(role, roles_dict, all_camera_names)
+        if camera_name in allowed_cameras:
+            return True
+
+    return False

frigate/ptz/onvif.py

@@ -152,21 +152,12 @@ class OnvifController:
 
         cam = self.camera_configs[cam_name]
         try:
-            user = cam.onvif.user
-            password = cam.onvif.password
-
-            if user is not None and isinstance(user, bytes):
-                user = user.decode("utf-8")
-
-            if password is not None and isinstance(password, bytes):
-                password = password.decode("utf-8")
-
             self.cams[cam_name] = {
                 "onvif": ONVIFCamera(
                     cam.onvif.host,
                     cam.onvif.port,
-                    user,
-                    password,
+                    cam.onvif.user,
+                    cam.onvif.password,
                     wsdl_dir=str(Path(find_spec("onvif").origin).parent / "wsdl"),
                     adjust_time=cam.onvif.ignore_time_mismatch,
                     encrypt=not cam.onvif.tls_insecure,
@@ -459,15 +450,15 @@ class OnvifController:
             presets = []
 
         for preset in presets:
-            # Ensure preset name is a Unicode string and handle UTF-8 characters correctly
             preset_name = getattr(preset, "Name") or f"preset {preset['token']}"
-
-            if isinstance(preset_name, bytes):
-                preset_name = preset_name.decode("utf-8")
-
-            # Convert to lowercase while preserving UTF-8 characters
-            preset_name_lower = preset_name.lower()
-            self.cams[camera_name]["presets"][preset_name_lower] = preset["token"]
+            # Some cameras (e.g. Reolink) return UTF-8 bytes that zeep decodes
+            # as latin-1, producing mojibake. Detect that and repair it by
+            # round-tripping through latin-1 -> utf-8.
+            try:
+                preset_name = preset_name.encode("latin-1").decode("utf-8")
+            except (UnicodeEncodeError, UnicodeDecodeError):
+                pass
+            self.cams[camera_name]["presets"][preset_name.lower()] = preset["token"]
 
         # get list of supported features
         supported_features = []
@@ -695,9 +686,6 @@ class OnvifController:
         self.cams[camera_name]["active"] = False
 
     async def _move_to_preset(self, camera_name: str, preset: str) -> None:
-        if isinstance(preset, bytes):
-            preset = preset.decode("utf-8")
-
         preset = preset.lower()
 
         if preset not in self.cams[camera_name]["presets"]:

frigate/record/export.py

@@ -4,13 +4,14 @@ import datetime
 import logging
 import os
 import random
+import re
 import shutil
 import string
 import subprocess as sp
 import threading
 from enum import Enum
 from pathlib import Path
-from typing import Optional
+from typing import Callable, Optional
 
 from peewee import DoesNotExist
 
@@ -27,7 +28,7 @@ from frigate.ffmpeg_presets import (
     EncodeTypeEnum,
     parse_preset_hardware_acceleration_encode,
 )
-from frigate.models import Export, Previews, Recordings
+from frigate.models import Export, Previews, Recordings, ReviewSegment
 from frigate.util.time import is_current_hour
 
 logger = logging.getLogger(__name__)
@@ -36,22 +37,24 @@ logger = logging.getLogger(__name__)
 DEFAULT_TIME_LAPSE_FFMPEG_ARGS = "-vf setpts=0.04*PTS -r 30"
 TIMELAPSE_DATA_INPUT_ARGS = "-an -skip_frame nokey"
 
-# ffmpeg flags that can read from or write to arbitrary files.
-# filter flags are blocked because source filters like movie= and
-# amovie= can read arbitrary files from the filesystem.
+# Matches the setpts factor used in timelapse exports (e.g. setpts=0.04*PTS).
+# Captures the floating-point factor so we can scale expected duration.
+SETPTS_FACTOR_RE = re.compile(r"setpts=([0-9]*\.?[0-9]+)\*PTS")
+
+# ffmpeg flags that can read from or write to arbitrary files
 BLOCKED_FFMPEG_ARGS = frozenset(
     {
         "-i",
         "-filter_script",
-        "-vstats_file",
-        "-passlogfile",
-        "-sdp_file",
-        "-dump_attachment",
         "-filter_complex",
         "-lavfi",
         "-vf",
         "-af",
         "-filter",
+        "-vstats_file",
+        "-passlogfile",
+        "-sdp_file",
+        "-dump_attachment",
         "-attach",
     }
 )
@@ -62,8 +65,11 @@ def validate_ffmpeg_args(args: str) -> tuple[bool, str]:
 
     Blocks:
     - The -i flag and other flags that read/write arbitrary files
+    - Filter flags (can read files via movie=/amovie= source filters)
     - Absolute/relative file paths (potential extra outputs)
     - URLs and ffmpeg protocol references (data exfiltration)
+
+    Admin users skip this validation entirely since they are trusted.
     """
     if not args or not args.strip():
         return True, ""
@@ -115,6 +121,7 @@ class RecordingExporter(threading.Thread):
         ffmpeg_input_args: Optional[str] = None,
         ffmpeg_output_args: Optional[str] = None,
         cpu_fallback: bool = False,
+        on_progress: Optional[Callable[[str, float], None]] = None,
     ) -> None:
         super().__init__()
         self.config = config
@@ -129,14 +136,333 @@ class RecordingExporter(threading.Thread):
         self.ffmpeg_input_args = ffmpeg_input_args
         self.ffmpeg_output_args = ffmpeg_output_args
         self.cpu_fallback = cpu_fallback
+        self.on_progress = on_progress
 
         # ensure export thumb dir
         Path(os.path.join(CLIPS_DIR, "export")).mkdir(exist_ok=True)
 
+    def _emit_progress(self, step: str, percent: float) -> None:
+        """Invoke the progress callback if one was supplied."""
+        if self.on_progress is None:
+            return
+        try:
+            self.on_progress(step, max(0.0, min(100.0, percent)))
+        except Exception:
+            logger.exception("Export progress callback failed")
+
+    def _expected_output_duration_seconds(self) -> float:
+        """Compute the expected duration of the output video in seconds.
+
+        Users often request a wide time range (e.g. a full hour) when only
+        a few minutes of recordings actually live on disk for that span,
+        so the requested range overstates the work and progress would
+        plateau very early. We sum the actual saved seconds from the
+        Recordings/Previews tables and use that as the input duration.
+        Timelapse exports then scale this by the setpts factor.
+        """
+        requested_duration = max(0.0, float(self.end_time - self.start_time))
+
+        recorded = self._sum_source_duration_seconds()
+        input_duration = (
+            recorded if recorded is not None and recorded > 0 else requested_duration
+        )
+
+        if not self.ffmpeg_output_args:
+            return input_duration
+
+        match = SETPTS_FACTOR_RE.search(self.ffmpeg_output_args)
+        if match is None:
+            return input_duration
+
+        try:
+            factor = float(match.group(1))
+        except ValueError:
+            return input_duration
+
+        if factor <= 0:
+            return input_duration
+
+        return input_duration * factor
+
+    def _sum_source_duration_seconds(self) -> Optional[float]:
+        """Sum saved-video seconds inside [start_time, end_time].
+
+        Queries Recordings or Previews depending on the playback source,
+        clamps each segment to the requested range, and returns the total.
+        Returns ``None`` on any error so the caller can fall back to the
+        requested range duration without losing progress reporting.
+        """
+        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()
+                )
+            else:
+                rows = (
+                    Previews.select(Previews.start_time, Previews.end_time)
+                    .where(
+                        Previews.start_time.between(self.start_time, self.end_time)
+                        | Previews.end_time.between(self.start_time, self.end_time)
+                        | (
+                            (self.start_time > Previews.start_time)
+                            & (self.end_time < Previews.end_time)
+                        )
+                    )
+                    .where(Previews.camera == self.camera)
+                    .iterator()
+                )
+        except Exception:
+            logger.exception(
+                "Failed to sum source duration for export %s", self.export_id
+            )
+            return None
+
+        total = 0.0
+        try:
+            for row in rows:
+                clipped_start = max(float(row.start_time), float(self.start_time))
+                clipped_end = min(float(row.end_time), float(self.end_time))
+                if clipped_end > clipped_start:
+                    total += clipped_end - clipped_start
+        except Exception:
+            logger.exception(
+                "Failed to read recording rows for export %s", self.export_id
+            )
+            return None
+
+        return total
+
+    def _inject_progress_flags(self, ffmpeg_cmd: list[str]) -> list[str]:
+        """Insert FFmpeg progress reporting flags before the output path.
+
+        ``-progress pipe:2`` writes structured key=value lines to stderr,
+        ``-nostats`` suppresses the noisy default stats output.
+        """
+        if not ffmpeg_cmd:
+            return ffmpeg_cmd
+        return ffmpeg_cmd[:-1] + ["-progress", "pipe:2", "-nostats", ffmpeg_cmd[-1]]
+
+    def _run_ffmpeg_with_progress(
+        self,
+        ffmpeg_cmd: list[str],
+        playlist_lines: str | list[str],
+        step: str = "encoding",
+    ) -> tuple[int, str]:
+        """Run an FFmpeg export command, parsing progress events from stderr.
+
+        Returns ``(returncode, captured_stderr)``. Stdout is left attached to
+        the parent process so we don't have to drain it (and risk a deadlock
+        if the buffer fills). Progress percent is computed against the
+        expected output duration; values are clamped to [0, 100] inside
+        :py:meth:`_emit_progress`.
+        """
+        cmd = ["nice", "-n", str(PROCESS_PRIORITY_LOW)] + self._inject_progress_flags(
+            ffmpeg_cmd
+        )
+
+        if isinstance(playlist_lines, list):
+            stdin_payload = "\n".join(playlist_lines)
+        else:
+            stdin_payload = playlist_lines
+
+        expected_duration = self._expected_output_duration_seconds()
+
+        self._emit_progress(step, 0.0)
+
+        proc = sp.Popen(
+            cmd,
+            stdin=sp.PIPE,
+            stderr=sp.PIPE,
+            text=True,
+            encoding="ascii",
+            errors="replace",
+        )
+
+        assert proc.stdin is not None
+        assert proc.stderr is not None
+
+        try:
+            proc.stdin.write(stdin_payload)
+        except (BrokenPipeError, OSError):
+            # FFmpeg may have rejected the input early; still wait for it
+            # to terminate so the returncode is meaningful.
+            pass
+        finally:
+            try:
+                proc.stdin.close()
+            except (BrokenPipeError, OSError):
+                pass
+
+        captured: list[str] = []
+
+        try:
+            for raw_line in proc.stderr:
+                captured.append(raw_line)
+                line = raw_line.strip()
+
+                if not line:
+                    continue
+
+                if line.startswith("out_time_us="):
+                    if expected_duration <= 0:
+                        continue
+                    try:
+                        out_time_us = int(line.split("=", 1)[1])
+                    except (ValueError, IndexError):
+                        continue
+                    if out_time_us < 0:
+                        continue
+                    out_seconds = out_time_us / 1_000_000.0
+                    percent = (out_seconds / expected_duration) * 100.0
+                    self._emit_progress(step, percent)
+                elif line == "progress=end":
+                    self._emit_progress(step, 100.0)
+                    break
+        except Exception:
+            logger.exception("Failed reading FFmpeg progress for %s", self.export_id)
+
+        proc.wait()
+
+        # Drain any remaining stderr so callers can log it on failure.
+        try:
+            remaining = proc.stderr.read()
+            if remaining:
+                captured.append(remaining)
+        except Exception:
+            pass
+
+        return proc.returncode, "".join(captured)
+
     def get_datetime_from_timestamp(self, timestamp: int) -> str:
         # return in iso format
         return datetime.datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d %H:%M:%S")
 
+    def _chapter_metadata_path(self) -> str:
+        return os.path.join(CACHE_DIR, f"export_chapters_{self.export_id}.txt")
+
+    def _build_chapter_metadata_file(self, recordings: list) -> Optional[str]:
+        """Write an FFmpeg metadata file with chapters for review items in range.
+
+        Chapter offsets are computed in *output time*: the VOD endpoint
+        concatenates recording clips back-to-back, so wall-clock gaps
+        between recordings collapse in the produced video. We walk the
+        same recording rows that feed the playlist and convert each
+        review item's wall-clock boundaries into output-time offsets.
+        Returns ``None`` when there are no recordings, no review items,
+        or any chapter would have zero output duration.
+        """
+        if not recordings:
+            return None
+
+        windows: list[tuple[float, float, float]] = []
+        output_offset = 0.0
+        for rec in recordings:
+            clipped_start = max(float(rec.start_time), float(self.start_time))
+            clipped_end = min(float(rec.end_time), float(self.end_time))
+            if clipped_end <= clipped_start:
+                continue
+            windows.append((clipped_start, clipped_end, output_offset))
+            output_offset += clipped_end - clipped_start
+
+        if not windows:
+            return None
+
+        try:
+            review_rows = list(
+                ReviewSegment.select(
+                    ReviewSegment.start_time,
+                    ReviewSegment.end_time,
+                    ReviewSegment.severity,
+                    ReviewSegment.data,
+                )
+                .where(
+                    ReviewSegment.start_time.between(self.start_time, self.end_time)
+                    | ReviewSegment.end_time.between(self.start_time, self.end_time)
+                    | (
+                        (self.start_time > ReviewSegment.start_time)
+                        & (self.end_time < ReviewSegment.end_time)
+                    )
+                )
+                .where(ReviewSegment.camera == self.camera)
+                .order_by(ReviewSegment.start_time.asc())
+                .iterator()
+            )
+        except Exception:
+            logger.exception(
+                "Failed to query review segments for export %s", self.export_id
+            )
+            return None
+
+        if not review_rows:
+            return None
+
+        total_output = windows[-1][2] + (windows[-1][1] - windows[-1][0])
+
+        def wall_to_output(t: float) -> float:
+            t = max(float(self.start_time), min(float(self.end_time), t))
+            for w_start, w_end, w_offset in windows:
+                if t < w_start:
+                    return w_offset
+                if t <= w_end:
+                    return w_offset + (t - w_start)
+            return total_output
+
+        chapter_blocks: list[str] = []
+        for review in review_rows:
+            start_out = wall_to_output(float(review.start_time))
+            end_out = wall_to_output(float(review.end_time))
+
+            # Drop chapters that fall entirely in a recording gap, or are
+            # too short to be navigable in a player.
+            if end_out - start_out < 1.0:
+                continue
+
+            data = review.data or {}
+            labels: list[str] = []
+            for obj in data.get("objects") or []:
+                label = str(obj).split("-")[0]
+                if label and label not in labels:
+                    labels.append(label)
+
+            title = str(review.severity).capitalize()
+            if labels:
+                title = f"{title}: {', '.join(labels)}"
+
+            chapter_blocks.append(
+                "[CHAPTER]\n"
+                "TIMEBASE=1/1000\n"
+                f"START={int(start_out * 1000)}\n"
+                f"END={int(end_out * 1000)}\n"
+                f"title={title}"
+            )
+
+        if not chapter_blocks:
+            return None
+
+        meta_path = self._chapter_metadata_path()
+        try:
+            with open(meta_path, "w", encoding="utf-8") as f:
+                f.write(";FFMETADATA1\n")
+                f.write("\n".join(chapter_blocks))
+                f.write("\n")
+        except OSError:
+            logger.exception(
+                "Failed to write chapter metadata file for export %s", self.export_id
+            )
+            return None
+
+        return meta_path
+
     def save_thumbnail(self, id: str) -> str:
         thumb_path = os.path.join(CLIPS_DIR, f"export/{id}.webp")
 
@@ -241,6 +567,24 @@ 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()
+        )
+
         playlist_lines: list[str] = []
         if (self.end_time - self.start_time) <= MAX_PLAYLIST_SECONDS:
             playlist_url = f"http://127.0.0.1:{internal_port}/vod/{self.camera}/start/{self.start_time}/end/{self.end_time}/index.m3u8"
@@ -248,32 +592,13 @@ class RecordingExporter(threading.Thread):
                 f"-y -protocol_whitelist pipe,file,http,tcp -i {playlist_url}"
             )
         else:
-            # get full set of recordings
-            export_recordings = (
-                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())
-            )
-
-            # Use pagination to process records in chunks
+            # Chunk the recording rows into pages so each playlist line
+            # references a bounded sub-range rather than the full export.
             page_size = 1000
-            num_pages = (export_recordings.count() + page_size - 1) // page_size
-
-            for page in range(1, num_pages + 1):
-                playlist = export_recordings.paginate(page, page_size)
+            for i in range(0, len(recordings), page_size):
+                chunk = recordings[i : i + page_size]
                 playlist_lines.append(
-                    f"file 'http://127.0.0.1:{internal_port}/vod/{self.camera}/start/{float(playlist[0].start_time)}/end/{float(playlist[-1].end_time)}/index.m3u8'"
+                    f"file 'http://127.0.0.1:{internal_port}/vod/{self.camera}/start/{float(chunk[0].start_time)}/end/{float(chunk[-1].end_time)}/index.m3u8'"
                 )
 
             ffmpeg_input = "-y -protocol_whitelist pipe,file,http,tcp -f concat -safe 0 -i /dev/stdin"
@@ -294,8 +619,12 @@ class RecordingExporter(threading.Thread):
                 )
             ).split(" ")
         else:
+            chapters_path = self._build_chapter_metadata_file(recordings)
+            chapter_args = (
+                f" -i {chapters_path} -map 0 -map_metadata 1" if chapters_path else ""
+            )
             ffmpeg_cmd = (
-                f"{self.config.ffmpeg.ffmpeg_path} -hide_banner {ffmpeg_input} -c copy -movflags +faststart"
+                f"{self.config.ffmpeg.ffmpeg_path} -hide_banner {ffmpeg_input}{chapter_args} -c copy -movflags +faststart"
             ).split(" ")
 
         # add metadata
@@ -405,6 +734,7 @@ class RecordingExporter(threading.Thread):
         logger.debug(
             f"Beginning export for {self.camera} from {self.start_time} to {self.end_time}"
         )
+        self._emit_progress("preparing", 0.0)
         export_name = (
             self.user_provided_name
             or f"{self.camera.replace('_', ' ')} {self.get_datetime_from_timestamp(self.start_time)} {self.get_datetime_from_timestamp(self.end_time)}"
@@ -442,16 +772,23 @@ class RecordingExporter(threading.Thread):
         except DoesNotExist:
             return
 
-        p = sp.run(
-            ["nice", "-n", str(PROCESS_PRIORITY_LOW)] + ffmpeg_cmd,
-            input="\n".join(playlist_lines),
-            encoding="ascii",
-            capture_output=True,
+        # When neither custom ffmpeg arg is set the default path uses
+        # `-c copy` (stream copy — no re-encoding). Report that as a
+        # distinct step so the UI doesn't mislabel a remux as encoding.
+        # The retry branch below always re-encodes because cpu_fallback
+        # requires custom args; it stays "encoding_retry".
+        is_stream_copy = (
+            self.ffmpeg_input_args is None and self.ffmpeg_output_args is None
+        )
+        initial_step = "copying" if is_stream_copy else "encoding"
+
+        returncode, stderr = self._run_ffmpeg_with_progress(
+            ffmpeg_cmd, playlist_lines, step=initial_step
         )
 
         # If export failed and cpu_fallback is enabled, retry without hwaccel
         if (
-            p.returncode != 0
+            returncode != 0
             and self.cpu_fallback
             and self.ffmpeg_input_args is not None
             and self.ffmpeg_output_args is not None
@@ -469,23 +806,23 @@ class RecordingExporter(threading.Thread):
                     video_path, use_hwaccel=False
                 )
 
-            p = sp.run(
-                ["nice", "-n", str(PROCESS_PRIORITY_LOW)] + ffmpeg_cmd,
-                input="\n".join(playlist_lines),
-                encoding="ascii",
-                capture_output=True,
+            returncode, stderr = self._run_ffmpeg_with_progress(
+                ffmpeg_cmd, playlist_lines, step="encoding_retry"
             )
 
-        if p.returncode != 0:
+        Path(self._chapter_metadata_path()).unlink(missing_ok=True)
+
+        if returncode != 0:
             logger.error(
                 f"Failed to export {self.playback_source.value} for command {' '.join(ffmpeg_cmd)}"
             )
-            logger.error(p.stderr)
+            logger.error(stderr)
             Path(video_path).unlink(missing_ok=True)
             Export.delete().where(Export.id == self.export_id).execute()
             Path(thumb_path).unlink(missing_ok=True)
             return
         else:
+            self._emit_progress("finalizing", 100.0)
             Export.update({Export.in_progress: False}).where(
                 Export.id == self.export_id
             ).execute()

frigate/record/maintainer.py

@@ -372,6 +372,7 @@ class RecordingMaintainer(threading.Thread):
             )
 
         record_config = self.config.cameras[camera].record
+        segment_stats: SegmentInfo | None = None
         highest = None
 
         if record_config.continuous.days > 0:
@@ -401,9 +402,19 @@ class RecordingMaintainer(threading.Thread):
                     if highest == "continuous"
                     else RetainModeEnum.motion
                 )
-                return await self.move_segment(
-                    camera, start_time, end_time, duration, cache_path, record_mode
-                )
+                segment_stats = self.segment_stats(camera, start_time, end_time)
+
+                # Here we only check if we should move the segment based on non-object recording retention
+                # we will always want to check for overlapping review items below before dropping the segment
+                if not segment_stats.should_discard_segment(record_mode):
+                    return await self.move_segment(
+                        camera,
+                        start_time,
+                        end_time,
+                        duration,
+                        cache_path,
+                        segment_stats,
+                    )
 
         # we fell through the continuous / motion check, so we need to check the review items
         # if the cached segment overlaps with the review items:
@@ -435,19 +446,30 @@ class RecordingMaintainer(threading.Thread):
                 if review.severity == "alert"
                 else record_config.detections.retain.mode
             )
-            # move from cache to recordings immediately
-            return await self.move_segment(
-                camera,
-                start_time,
-                end_time,
-                duration,
-                cache_path,
-                record_mode,
-            )
-        # if it doesn't overlap with an review item, go ahead and drop the segment
-        # if it ends more than the configured pre_capture for the camera
-        # BUT only if continuous/motion is NOT enabled (otherwise wait for processing)
-        elif highest is None:
+
+            if segment_stats is None:
+                segment_stats = self.segment_stats(camera, start_time, end_time)
+
+            if not segment_stats.should_discard_segment(record_mode):
+                # move from cache to recordings immediately
+                return await self.move_segment(
+                    camera,
+                    start_time,
+                    end_time,
+                    duration,
+                    cache_path,
+                    segment_stats,
+                )
+            else:
+                self.drop_segment(cache_path)
+                return None
+
+        # if it doesn't overlap with a review item, drop the segment once it
+        # ends more than event_pre_capture before the most recently processed
+        # frame. at this point we've already decided not to keep it for
+        # continuous/motion retention (either disabled or segment_stats said
+        # discard), so waiting longer just fills the cache.
+        else:
             camera_info = self.object_recordings_info[camera]
             most_recently_processed_frame_time = (
                 camera_info[-1][0] if len(camera_info) > 0 else 0
@@ -455,6 +477,7 @@ class RecordingMaintainer(threading.Thread):
             retain_cutoff = datetime.datetime.fromtimestamp(
                 most_recently_processed_frame_time - record_config.event_pre_capture
             ).astimezone(datetime.timezone.utc)
+
             if end_time < retain_cutoff:
                 self.drop_segment(cache_path)
 
@@ -578,15 +601,8 @@ class RecordingMaintainer(threading.Thread):
         end_time: datetime.datetime,
         duration: float,
         cache_path: str,
-        store_mode: RetainModeEnum,
+        segment_info: SegmentInfo,
     ) -> Optional[dict[str, Any]]:
-        segment_info = self.segment_stats(camera, start_time, end_time)
-
-        # check if the segment shouldn't be stored
-        if segment_info.should_discard_segment(store_mode):
-            self.drop_segment(cache_path)
-            return None
-
         # directory will be in utc due to start_time being in utc
         directory = os.path.join(
             RECORD_DIR,

frigate/storage.py

@@ -197,7 +197,7 @@ class StorageMaintainer(threading.Thread):
         # check if need to delete retained segments
         if deleted_segments_size < hourly_bandwidth:
             logger.error(
-                f"Could not clear {hourly_bandwidth} MB, currently {deleted_segments_size} MB have been cleared. Retained recordings must be deleted."
+                f"Could not clear {hourly_bandwidth} MB, currently {deleted_segments_size:.2f} MB have been cleared. Retained recordings must be deleted."
             )
             recordings = (
                 Recordings.select(
@@ -225,7 +225,7 @@ class StorageMaintainer(threading.Thread):
                     # this file was not found so we must assume no space was cleaned up
                     pass
         else:
-            logger.info(f"Cleaned up {deleted_segments_size} MB of recordings")
+            logger.info(f"Cleaned up {deleted_segments_size:.2f} MB of recordings")
 
         logger.debug(f"Expiring {len(deleted_recordings)} recordings")
         # delete up to 100,000 at a time

frigate/test/http_api/base_http_test.py

@@ -2,6 +2,7 @@ import datetime
 import logging
 import os
 import unittest
+from unittest.mock import patch
 
 from fastapi import Request
 from fastapi.testclient import TestClient
@@ -14,6 +15,7 @@ from frigate.api.fastapi_app import create_fastapi_app
 from frigate.config import FrigateConfig
 from frigate.const import BASE_DIR, CACHE_DIR
 from frigate.debug_replay import DebugReplayManager
+from frigate.jobs.export import JobStatePublisher
 from frigate.models import Event, Recordings, ReviewSegment
 from frigate.review.types import SeverityEnum
 from frigate.test.const import TEST_DB, TEST_DB_CLEANUPS
@@ -44,6 +46,19 @@ class BaseTestHttp(unittest.TestCase):
         self.db = SqliteQueueDatabase(TEST_DB)
         self.db.bind(models)
 
+        # The export job manager broadcasts via JobStatePublisher on
+        # enqueue/start/finish. There is no dispatcher process bound to
+        # the IPC socket in tests, so a real publish() would block on
+        # recv_json forever. Replace publish with a no-op for the
+        # lifetime of this test; the lookup goes through the class so any
+        # already-instantiated publisher (the singleton manager's) picks
+        # up the no-op too.
+        publisher_patch = patch.object(
+            JobStatePublisher, "publish", lambda self, payload: None
+        )
+        publisher_patch.start()
+        self.addCleanup(publisher_patch.stop)
+
         self.minimal_config = {
             "mqtt": {"host": "mqtt"},
             "cameras": {

frigate/test/http_api/test_http_app.py

@@ -23,6 +23,26 @@ class TestHttpApp(BaseTestHttp):
             response_json = response.json()
             assert response_json == self.test_stats
 
+    def test_recordings_storage_requires_admin(self):
+        stats = Mock(spec=StatsEmitter)
+        stats.get_latest_stats.return_value = self.test_stats
+        app = super().create_app(stats)
+        app.storage_maintainer = Mock()
+        app.storage_maintainer.calculate_camera_usages.return_value = {
+            "front_door": {"usage": 2.0},
+        }
+
+        with AuthTestClient(app) as client:
+            response = client.get(
+                "/recordings/storage",
+                headers={"remote-user": "viewer", "remote-role": "viewer"},
+            )
+            assert response.status_code == 403
+
+            response = client.get("/recordings/storage")
+            assert response.status_code == 200
+            assert response.json()["front_door"]["usage_percent"] == 25.0
+
     def test_config_set_in_memory_replaces_objects_track_list(self):
         self.minimal_config["cameras"]["front_door"]["objects"] = {
             "track": ["person", "car"],

frigate/test/http_api/test_http_event.py

@@ -219,6 +219,25 @@ class TestHttpApp(BaseTestHttp):
             assert len(events) == 1
             assert events[0]["id"] == event_id
 
+    def test_similarity_search_hides_unauthorized_anchor_event(self):
+        mock_embeddings = Mock()
+        self.app.frigate_config.semantic_search.enabled = True
+        self.app.embeddings = mock_embeddings
+
+        with AuthTestClient(self.app) as client:
+            super().insert_mock_event("hidden.anchor", camera="back_door")
+            response = client.get(
+                "/events/search",
+                params={
+                    "search_type": "similarity",
+                    "event_id": "hidden.anchor",
+                },
+            )
+
+        assert response.status_code == 404
+        assert response.json()["message"] == "Event not found"
+        mock_embeddings.search_thumbnail.assert_not_called()
+
     def test_get_good_event(self):
         id = "123456.random"
 

frigate/test/test_chat_find_similar_objects.py

@@ -0,0 +1,306 @@
+"""Tests for the find_similar_objects chat tool."""
+
+import asyncio
+import os
+import tempfile
+import unittest
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from playhouse.sqlite_ext import SqliteExtDatabase
+
+from frigate.api.chat import (
+    _execute_find_similar_objects,
+    get_tool_definitions,
+)
+from frigate.api.chat_util import (
+    DESCRIPTION_WEIGHT,
+    VISUAL_WEIGHT,
+    distance_to_score,
+    fuse_scores,
+)
+from frigate.embeddings.util import ZScoreNormalization
+from frigate.models import Event
+
+
+def _run(coro):
+    return asyncio.new_event_loop().run_until_complete(coro)
+
+
+class TestDistanceToScore(unittest.TestCase):
+    def test_lower_distance_gives_higher_score(self):
+        stats = ZScoreNormalization()
+        # Seed the stats with a small distribution so stddev > 0.
+        stats._update([0.1, 0.2, 0.3, 0.4, 0.5])
+
+        close_score = distance_to_score(0.1, stats)
+        far_score = distance_to_score(0.5, stats)
+
+        self.assertGreater(close_score, far_score)
+        self.assertGreaterEqual(close_score, 0.0)
+        self.assertLessEqual(close_score, 1.0)
+        self.assertGreaterEqual(far_score, 0.0)
+        self.assertLessEqual(far_score, 1.0)
+
+    def test_uninitialized_stats_returns_neutral_score(self):
+        stats = ZScoreNormalization()  # n == 0, stddev == 0
+        self.assertEqual(distance_to_score(0.3, stats), 0.5)
+
+
+class TestFuseScores(unittest.TestCase):
+    def test_weights_sum_to_one(self):
+        self.assertAlmostEqual(VISUAL_WEIGHT + DESCRIPTION_WEIGHT, 1.0)
+
+    def test_fuses_both_sides(self):
+        fused = fuse_scores(visual_score=0.8, description_score=0.4)
+        expected = VISUAL_WEIGHT * 0.8 + DESCRIPTION_WEIGHT * 0.4
+        self.assertAlmostEqual(fused, expected)
+
+    def test_missing_description_uses_visual_only(self):
+        fused = fuse_scores(visual_score=0.7, description_score=None)
+        self.assertAlmostEqual(fused, 0.7)
+
+    def test_missing_visual_uses_description_only(self):
+        fused = fuse_scores(visual_score=None, description_score=0.6)
+        self.assertAlmostEqual(fused, 0.6)
+
+    def test_both_missing_returns_none(self):
+        self.assertIsNone(fuse_scores(visual_score=None, description_score=None))
+
+
+class TestToolDefinition(unittest.TestCase):
+    def test_find_similar_objects_is_registered(self):
+        tools = get_tool_definitions()
+        names = [t["function"]["name"] for t in tools]
+        self.assertIn("find_similar_objects", names)
+
+    def test_find_similar_objects_schema(self):
+        tools = get_tool_definitions()
+        tool = next(t for t in tools if t["function"]["name"] == "find_similar_objects")
+        params = tool["function"]["parameters"]["properties"]
+        self.assertIn("event_id", params)
+        self.assertIn("after", params)
+        self.assertIn("before", params)
+        self.assertIn("cameras", params)
+        self.assertIn("labels", params)
+        self.assertIn("sub_labels", params)
+        self.assertIn("zones", params)
+        self.assertIn("similarity_mode", params)
+        self.assertIn("min_score", params)
+        self.assertIn("limit", params)
+        self.assertEqual(tool["function"]["parameters"]["required"], ["event_id"])
+        self.assertEqual(
+            params["similarity_mode"]["enum"], ["visual", "semantic", "fused"]
+        )
+
+
+class TestExecuteFindSimilarObjects(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
+        self.tmp.close()
+        self.db = SqliteExtDatabase(self.tmp.name)
+        Event.bind(self.db, bind_refs=False, bind_backrefs=False)
+        self.db.connect()
+        self.db.create_tables([Event])
+
+        # Insert an anchor plus two candidates.
+        def make(event_id, label="car", camera="driveway", start=1_700_000_100):
+            Event.create(
+                id=event_id,
+                label=label,
+                sub_label=None,
+                camera=camera,
+                start_time=start,
+                end_time=start + 10,
+                top_score=0.9,
+                score=0.9,
+                false_positive=False,
+                zones=[],
+                thumbnail="",
+                has_clip=True,
+                has_snapshot=True,
+                region=[0, 0, 1, 1],
+                box=[0, 0, 1, 1],
+                area=1,
+                retain_indefinitely=False,
+                ratio=1.0,
+                plus_id="",
+                model_hash="",
+                detector_type="",
+                model_type="",
+                data={"description": "a green sedan"},
+            )
+
+        make("anchor", start=1_700_000_200)
+        make("cand_a", start=1_700_000_100)
+        make("cand_b", start=1_700_000_150)
+        self.make = make
+
+    def tearDown(self):
+        self.db.close()
+        os.unlink(self.tmp.name)
+
+    def _make_request(self, semantic_enabled=True, embeddings=None):
+        app = SimpleNamespace(
+            embeddings=embeddings,
+            frigate_config=SimpleNamespace(
+                semantic_search=SimpleNamespace(enabled=semantic_enabled),
+                cameras={"driveway": object()},
+                auth=SimpleNamespace(roles={"admin": [], "viewer": ["driveway"]}),
+                proxy=SimpleNamespace(separator=","),
+            ),
+        )
+        return SimpleNamespace(app=app, headers={})
+
+    def test_semantic_search_disabled_returns_error(self):
+        req = self._make_request(semantic_enabled=False)
+        result = _run(
+            _execute_find_similar_objects(
+                req,
+                {"event_id": "anchor"},
+                allowed_cameras=["driveway"],
+            )
+        )
+        self.assertEqual(result["error"], "semantic_search_disabled")
+
+    def test_anchor_not_found_returns_error(self):
+        embeddings = MagicMock()
+        req = self._make_request(embeddings=embeddings)
+        result = _run(
+            _execute_find_similar_objects(
+                req,
+                {"event_id": "nope"},
+                allowed_cameras=["driveway"],
+            )
+        )
+        self.assertEqual(result["error"], "anchor_not_found")
+
+    def test_empty_candidates_returns_empty_results(self):
+        embeddings = MagicMock()
+        req = self._make_request(embeddings=embeddings)
+        # Filter to a camera with no other events.
+        result = _run(
+            _execute_find_similar_objects(
+                req,
+                {"event_id": "anchor", "cameras": ["nonexistent_cam"]},
+                allowed_cameras=["driveway"],
+            )
+        )
+        self.assertEqual(result["results"], [])
+        self.assertFalse(result["candidate_truncated"])
+        self.assertEqual(result["anchor"]["id"], "anchor")
+
+    def test_fused_calls_both_searches_and_ranks(self):
+        embeddings = MagicMock()
+        # cand_a visually closer, cand_b semantically closer.
+        embeddings.search_thumbnail.return_value = [
+            ("cand_a", 0.10),
+            ("cand_b", 0.40),
+        ]
+        embeddings.search_description.return_value = [
+            ("cand_a", 0.50),
+            ("cand_b", 0.20),
+        ]
+        embeddings.thumb_stats = ZScoreNormalization()
+        embeddings.thumb_stats._update([0.1, 0.2, 0.3, 0.4, 0.5])
+        embeddings.desc_stats = ZScoreNormalization()
+        embeddings.desc_stats._update([0.1, 0.2, 0.3, 0.4, 0.5])
+
+        req = self._make_request(embeddings=embeddings)
+        result = _run(
+            _execute_find_similar_objects(
+                req,
+                {"event_id": "anchor"},
+                allowed_cameras=["driveway"],
+            )
+        )
+        embeddings.search_thumbnail.assert_called_once()
+        embeddings.search_description.assert_called_once()
+        # cand_a should rank first because visual is weighted higher.
+        self.assertEqual(result["results"][0]["id"], "cand_a")
+        self.assertIn("score", result["results"][0])
+        self.assertEqual(result["similarity_mode"], "fused")
+
+    def test_visual_mode_only_calls_thumbnail(self):
+        embeddings = MagicMock()
+        embeddings.search_thumbnail.return_value = [("cand_a", 0.1)]
+        embeddings.thumb_stats = ZScoreNormalization()
+        embeddings.thumb_stats._update([0.1, 0.2, 0.3])
+
+        req = self._make_request(embeddings=embeddings)
+        _run(
+            _execute_find_similar_objects(
+                req,
+                {"event_id": "anchor", "similarity_mode": "visual"},
+                allowed_cameras=["driveway"],
+            )
+        )
+        embeddings.search_thumbnail.assert_called_once()
+        embeddings.search_description.assert_not_called()
+
+    def test_semantic_mode_only_calls_description(self):
+        embeddings = MagicMock()
+        embeddings.search_description.return_value = [("cand_a", 0.1)]
+        embeddings.desc_stats = ZScoreNormalization()
+        embeddings.desc_stats._update([0.1, 0.2, 0.3])
+
+        req = self._make_request(embeddings=embeddings)
+        _run(
+            _execute_find_similar_objects(
+                req,
+                {"event_id": "anchor", "similarity_mode": "semantic"},
+                allowed_cameras=["driveway"],
+            )
+        )
+        embeddings.search_description.assert_called_once()
+        embeddings.search_thumbnail.assert_not_called()
+
+    def test_min_score_drops_low_scoring_results(self):
+        embeddings = MagicMock()
+        embeddings.search_thumbnail.return_value = [
+            ("cand_a", 0.10),
+            ("cand_b", 0.90),
+        ]
+        embeddings.search_description.return_value = []
+        embeddings.thumb_stats = ZScoreNormalization()
+        embeddings.thumb_stats._update([0.1, 0.2, 0.3, 0.4, 0.5])
+        embeddings.desc_stats = ZScoreNormalization()
+
+        req = self._make_request(embeddings=embeddings)
+        result = _run(
+            _execute_find_similar_objects(
+                req,
+                {"event_id": "anchor", "similarity_mode": "visual", "min_score": 0.6},
+                allowed_cameras=["driveway"],
+            )
+        )
+        ids = [r["id"] for r in result["results"]]
+        self.assertIn("cand_a", ids)
+        self.assertNotIn("cand_b", ids)
+
+    def test_labels_defaults_to_anchor_label(self):
+        self.make("person_a", label="person")
+        embeddings = MagicMock()
+        embeddings.search_thumbnail.return_value = [
+            ("cand_a", 0.1),
+            ("cand_b", 0.2),
+        ]
+        embeddings.search_description.return_value = []
+        embeddings.thumb_stats = ZScoreNormalization()
+        embeddings.thumb_stats._update([0.1, 0.2, 0.3])
+        embeddings.desc_stats = ZScoreNormalization()
+
+        req = self._make_request(embeddings=embeddings)
+        result = _run(
+            _execute_find_similar_objects(
+                req,
+                {"event_id": "anchor", "similarity_mode": "visual"},
+                allowed_cameras=["driveway"],
+            )
+        )
+        ids = [r["id"] for r in result["results"]]
+        self.assertNotIn("person_a", ids)
+
+
+if __name__ == "__main__":
+    unittest.main()

frigate/test/test_deferred_processor.py

@@ -0,0 +1,211 @@
+"""Tests for DeferredRealtimeProcessorApi."""
+
+import sys
+import time
+import unittest
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+
+from frigate.data_processing.real_time.api import DeferredRealtimeProcessorApi
+
+# Mock TFLite before importing classification module
+_MOCK_MODULES = [
+    "tflite_runtime",
+    "tflite_runtime.interpreter",
+    "ai_edge_litert",
+    "ai_edge_litert.interpreter",
+]
+for mod in _MOCK_MODULES:
+    if mod not in sys.modules:
+        sys.modules[mod] = MagicMock()
+
+from frigate.data_processing.real_time.custom_classification import (  # noqa: E402
+    CustomObjectClassificationProcessor,
+)
+
+
+class StubDeferredProcessor(DeferredRealtimeProcessorApi):
+    """Minimal concrete subclass for testing the deferred base."""
+
+    def __init__(self, max_queue: int = 8):
+        config = MagicMock()
+        metrics = MagicMock()
+        super().__init__(config, metrics, max_queue=max_queue)
+        self.processed_items: list[tuple] = []
+
+    def process_frame(self, obj_data: dict[str, Any], frame: np.ndarray) -> None:
+        """Enqueue every call — no gating logic in the stub."""
+        self._enqueue_task(("frame", obj_data, frame.copy()))
+
+    def _process_task(self, task: tuple) -> None:
+        kind = task[0]
+        if kind == "frame":
+            _, obj_data, frame = task
+            self.processed_items.append((obj_data["id"], frame.shape))
+            self._emit_result(
+                {
+                    "type": "test_result",
+                    "id": obj_data["id"],
+                    "label": "cat",
+                    "score": 0.95,
+                }
+            )
+        elif kind == "expire":
+            _, object_id = task
+            self.processed_items.append(("expired", object_id))
+
+    def handle_request(
+        self, topic: str, request_data: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        if topic == "reload":
+
+            def _do_reload(data):
+                return {"success": True, "model": data.get("name")}
+
+            return self._enqueue_request(_do_reload, request_data)
+        return None
+
+    def expire_object(self, object_id: str, camera: str) -> None:
+        self._enqueue_task(("expire", object_id))
+
+
+class TestDeferredProcessorBase(unittest.TestCase):
+    def test_enqueue_and_drain(self):
+        """Tasks enqueued on main thread are processed by worker, results are drainable."""
+        proc = StubDeferredProcessor()
+        frame = np.zeros((100, 100, 3), dtype=np.uint8)
+        proc.process_frame({"id": "obj1"}, frame)
+        proc.process_frame({"id": "obj2"}, frame)
+
+        # Give the worker time to process
+        time.sleep(0.1)
+
+        results = proc.drain_results()
+        self.assertEqual(len(results), 2)
+        self.assertEqual(results[0]["id"], "obj1")
+        self.assertEqual(results[1]["id"], "obj2")
+
+        # Second drain should be empty
+        self.assertEqual(len(proc.drain_results()), 0)
+
+    def test_backpressure_drops_tasks(self):
+        """When queue is full, new tasks are silently dropped."""
+        proc = StubDeferredProcessor(max_queue=2)
+
+        frame = np.zeros((10, 10, 3), dtype=np.uint8)
+        for i in range(10):
+            proc.process_frame({"id": f"obj{i}"}, frame)
+
+        time.sleep(0.2)
+        results = proc.drain_results()
+        # The key property: no crash, no unbounded growth
+        self.assertLessEqual(len(results), 10)
+        self.assertGreater(len(results), 0)
+
+    def test_handle_request_through_worker(self):
+        """handle_request blocks until the worker processes it and returns a response."""
+        proc = StubDeferredProcessor()
+        result = proc.handle_request("reload", {"name": "my_model"})
+        self.assertEqual(result, {"success": True, "model": "my_model"})
+
+    def test_expire_object_serialized_with_work(self):
+        """expire_object goes through the queue, serialized with inference work."""
+        proc = StubDeferredProcessor()
+        frame = np.zeros((10, 10, 3), dtype=np.uint8)
+        proc.process_frame({"id": "obj1"}, frame)
+        proc.expire_object("obj1", "front_door")
+
+        time.sleep(0.1)
+        # Both should have been processed in order
+        self.assertEqual(len(proc.processed_items), 2)
+        self.assertEqual(proc.processed_items[0][0], "obj1")
+        self.assertEqual(proc.processed_items[1], ("expired", "obj1"))
+
+    def test_shutdown_joins_worker(self):
+        """shutdown() signals the worker to stop and joins the thread."""
+        proc = StubDeferredProcessor()
+        proc.shutdown()
+        self.assertFalse(proc._worker.is_alive())
+
+    def test_drain_results_returns_list(self):
+        """drain_results returns a plain list, not a deque."""
+        proc = StubDeferredProcessor()
+        results = proc.drain_results()
+        self.assertIsInstance(results, list)
+
+
+class TestCustomObjectClassificationDeferred(unittest.TestCase):
+    """Test that CustomObjectClassificationProcessor uses the deferred pattern correctly."""
+
+    def _make_processor(self):
+        config = MagicMock()
+        model_config = MagicMock()
+        model_config.name = "test_breed"
+        model_config.object_config = MagicMock()
+        model_config.object_config.objects = ["dog"]
+        model_config.threshold = 0.5
+        model_config.save_attempts = 10
+        model_config.object_config.classification_type = "sub_label"
+        publisher = MagicMock()
+        requestor = MagicMock()
+        metrics = MagicMock()
+        metrics.classification_speeds = {}
+        metrics.classification_cps = {}
+
+        with patch.object(
+            CustomObjectClassificationProcessor,
+            "_CustomObjectClassificationProcessor__build_detector",
+        ):
+            proc = CustomObjectClassificationProcessor(
+                config, model_config, publisher, requestor, metrics
+            )
+        proc.interpreter = None
+        proc.tensor_input_details = [{"index": 0}]
+        proc.tensor_output_details = [{"index": 0}]
+        proc.labelmap = {0: "labrador", 1: "poodle", 2: "none"}
+        return proc
+
+    def test_is_deferred_processor(self):
+        """CustomObjectClassificationProcessor should be a DeferredRealtimeProcessorApi."""
+        proc = self._make_processor()
+        self.assertIsInstance(proc, DeferredRealtimeProcessorApi)
+
+    def test_expire_clears_history(self):
+        """expire_object should clear classification history for the object."""
+        proc = self._make_processor()
+        proc.classification_history["obj1"] = [("labrador", 0.9, 1.0)]
+
+        proc.expire_object("obj1", "front")
+        time.sleep(0.1)
+
+        self.assertNotIn("obj1", proc.classification_history)
+
+    def test_drain_results_empty_when_no_model(self):
+        """With no interpreter, process_frame saves training images but emits no results."""
+        proc = self._make_processor()
+        proc.interpreter = None
+
+        frame = np.zeros((150, 100), dtype=np.uint8)
+        obj_data = {
+            "id": "obj1",
+            "label": "dog",
+            "false_positive": False,
+            "end_time": None,
+            "box": [10, 10, 50, 50],
+            "camera": "front",
+        }
+
+        with patch(
+            "frigate.data_processing.real_time.custom_classification.write_classification_attempt"
+        ):
+            proc.process_frame(obj_data, frame)
+
+        time.sleep(0.1)
+        results = proc.drain_results()
+        self.assertEqual(len(results), 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

frigate/test/test_env.py

@@ -2,6 +2,7 @@
 
 import os
 import unittest
+from unittest.mock import MagicMock, patch
 
 from frigate.config.env import (
     FRIGATE_ENV_VARS,
@@ -10,6 +11,71 @@ from frigate.config.env import (
 )
 
 
+class TestGo2RtcAddStreamSubstitution(unittest.TestCase):
+    """Covers the API path: PUT /go2rtc/streams/{stream_name}.
+
+    The route shells out to go2rtc via `requests.put`; we mock the HTTP call
+    and assert that the substituted `src` parameter handles the same mixed
+    {FRIGATE_*} + literal-brace strings as the config-loading path.
+    """
+
+    def setUp(self):
+        self._original_env_vars = dict(FRIGATE_ENV_VARS)
+
+    def tearDown(self):
+        FRIGATE_ENV_VARS.clear()
+        FRIGATE_ENV_VARS.update(self._original_env_vars)
+
+    def _call_route(self, src: str) -> str:
+        """Invoke go2rtc_add_stream and return the substituted src param."""
+        from frigate.api import camera as camera_api
+
+        captured = {}
+
+        def fake_put(url, params=None, timeout=None):
+            captured["params"] = params
+            resp = MagicMock()
+            resp.ok = True
+            resp.text = ""
+            resp.status_code = 200
+            return resp
+
+        with patch.object(camera_api.requests, "put", side_effect=fake_put):
+            camera_api.go2rtc_add_stream(
+                request=MagicMock(), stream_name="cam1", src=src
+            )
+        return captured["params"]["src"]
+
+    def test_mixed_localtime_and_frigate_var(self):
+        """%{localtime\\:...} alongside {FRIGATE_USER} substitutes only the var."""
+        FRIGATE_ENV_VARS["FRIGATE_USER"] = "admin"
+        src = (
+            "ffmpeg:rtsp://host/s#raw=-vf "
+            "drawtext=text=%{localtime\\:%Y-%m-%d}:user={FRIGATE_USER}"
+        )
+        self.assertEqual(
+            self._call_route(src),
+            "ffmpeg:rtsp://host/s#raw=-vf "
+            "drawtext=text=%{localtime\\:%Y-%m-%d}:user=admin",
+        )
+
+    def test_unknown_var_falls_back_to_raw_src(self):
+        """Existing route behavior: unknown {FRIGATE_*} keeps raw src."""
+        src = "rtsp://host/{FRIGATE_NONEXISTENT}/stream"
+        self.assertEqual(self._call_route(src), src)
+
+    def test_malformed_placeholder_rejected_via_api(self):
+        """Malformed FRIGATE placeholders raise (not silently passed through).
+
+        Regression: previously camera.py caught any KeyError and fell back
+        to the raw src, so `{FRIGATE_FOO:>5}` was silently accepted via the
+        API while config loading rejected it. The helper now raises
+        ValueError for malformed syntax to keep the two paths consistent.
+        """
+        with self.assertRaises(ValueError):
+            self._call_route("rtsp://host/{FRIGATE_FOO:>5}/stream")
+
+
 class TestEnvString(unittest.TestCase):
     def setUp(self):
         self._original_env_vars = dict(FRIGATE_ENV_VARS)
@@ -43,6 +109,72 @@ class TestEnvString(unittest.TestCase):
         with self.assertRaises(KeyError):
             validate_env_string("{FRIGATE_NONEXISTENT_VAR}")
 
+    def test_non_frigate_braces_passthrough(self):
+        """Braces that are not {FRIGATE_*} placeholders pass through untouched.
+
+        Regression test for ffmpeg drawtext expressions like
+        "%{localtime\\:%Y-%m-%d}" being mangled by str.format().
+        """
+        expr = (
+            "ffmpeg:rtsp://127.0.0.1/src#raw=-vf "
+            "drawtext=text=%{localtime\\:%Y-%m-%d_%H\\:%M\\:%S}"
+            ":x=5:fontcolor=white"
+        )
+        self.assertEqual(validate_env_string(expr), expr)
+
+    def test_double_brace_escape_preserved(self):
+        """`{{output}}` collapses to `{output}` (documented go2rtc escape)."""
+        result = validate_env_string(
+            "exec:ffmpeg -i /media/file.mp4 -f rtsp {{output}}"
+        )
+        self.assertEqual(result, "exec:ffmpeg -i /media/file.mp4 -f rtsp {output}")
+
+    def test_double_brace_around_frigate_var(self):
+        """`{{FRIGATE_FOO}}` stays literal — escape takes precedence."""
+        FRIGATE_ENV_VARS["FRIGATE_FOO"] = "bar"
+        self.assertEqual(validate_env_string("{{FRIGATE_FOO}}"), "{FRIGATE_FOO}")
+
+    def test_mixed_frigate_var_and_braces(self):
+        """A FRIGATE_ var alongside literal single braces substitutes only the var."""
+        FRIGATE_ENV_VARS["FRIGATE_USER"] = "admin"
+        result = validate_env_string(
+            "drawtext=text=%{localtime}:user={FRIGATE_USER}:x=5"
+        )
+        self.assertEqual(result, "drawtext=text=%{localtime}:user=admin:x=5")
+
+    def test_triple_braces_around_frigate_var(self):
+        """`{{{FRIGATE_FOO}}}` collapses like str.format(): `{bar}`."""
+        FRIGATE_ENV_VARS["FRIGATE_FOO"] = "bar"
+        self.assertEqual(validate_env_string("{{{FRIGATE_FOO}}}"), "{bar}")
+
+    def test_trailing_double_brace_after_var(self):
+        """`{FRIGATE_FOO}}}` collapses like str.format(): `bar}`."""
+        FRIGATE_ENV_VARS["FRIGATE_FOO"] = "bar"
+        self.assertEqual(validate_env_string("{FRIGATE_FOO}}}"), "bar}")
+
+    def test_leading_double_brace_then_var(self):
+        """`{{{FRIGATE_FOO}` collapses like str.format(): `{bar`."""
+        FRIGATE_ENV_VARS["FRIGATE_FOO"] = "bar"
+        self.assertEqual(validate_env_string("{{{FRIGATE_FOO}"), "{bar")
+
+    def test_malformed_unterminated_placeholder_raises(self):
+        """`{FRIGATE_FOO` (no closing brace) raises like str.format() did."""
+        FRIGATE_ENV_VARS["FRIGATE_FOO"] = "bar"
+        with self.assertRaises(ValueError):
+            validate_env_string("prefix-{FRIGATE_FOO")
+
+    def test_malformed_format_spec_raises(self):
+        """`{FRIGATE_FOO:>5}` (format spec) raises like str.format() did."""
+        FRIGATE_ENV_VARS["FRIGATE_FOO"] = "bar"
+        with self.assertRaises(ValueError):
+            validate_env_string("{FRIGATE_FOO:>5}")
+
+    def test_malformed_conversion_raises(self):
+        """`{FRIGATE_FOO!r}` (conversion) raises like str.format() did."""
+        FRIGATE_ENV_VARS["FRIGATE_FOO"] = "bar"
+        with self.assertRaises(ValueError):
+            validate_env_string("{FRIGATE_FOO!r}")
+
 
 class TestEnvVars(unittest.TestCase):
     def setUp(self):

frigate/test/test_export_progress.py

@@ -0,0 +1,385 @@
+"""Tests for export progress tracking, broadcast, and FFmpeg parsing."""
+
+import io
+import unittest
+from unittest.mock import MagicMock, patch
+
+from frigate.jobs.export import (
+    PROGRESS_BROADCAST_MIN_INTERVAL,
+    ExportJob,
+    ExportJobManager,
+)
+from frigate.record.export import PlaybackSourceEnum, RecordingExporter
+from frigate.types import JobStatusTypesEnum
+
+
+def _make_exporter(
+    end_minus_start: int = 100,
+    ffmpeg_input_args=None,
+    ffmpeg_output_args=None,
+    on_progress=None,
+) -> RecordingExporter:
+    """Build a RecordingExporter without invoking its real __init__ side
+    effects (which create directories and require a full FrigateConfig)."""
+    exporter = RecordingExporter.__new__(RecordingExporter)
+    exporter.config = MagicMock()
+    exporter.export_id = "test_export"
+    exporter.camera = "front"
+    exporter.user_provided_name = None
+    exporter.user_provided_image = None
+    exporter.start_time = 1_000
+    exporter.end_time = 1_000 + end_minus_start
+    exporter.playback_source = PlaybackSourceEnum.recordings
+    exporter.export_case_id = None
+    exporter.ffmpeg_input_args = ffmpeg_input_args
+    exporter.ffmpeg_output_args = ffmpeg_output_args
+    exporter.cpu_fallback = False
+    exporter.on_progress = on_progress
+    return exporter
+
+
+class TestExportJobToDict(unittest.TestCase):
+    def test_to_dict_includes_progress_fields(self) -> None:
+        job = ExportJob(camera="front", request_start_time=0, request_end_time=10)
+        result = job.to_dict()
+
+        assert "current_step" in result
+        assert "progress_percent" in result
+        assert result["current_step"] == "queued"
+        assert result["progress_percent"] == 0.0
+
+    def test_to_dict_reflects_updated_progress(self) -> None:
+        job = ExportJob(camera="front", request_start_time=0, request_end_time=10)
+        job.current_step = "encoding"
+        job.progress_percent = 42.5
+
+        result = job.to_dict()
+
+        assert result["current_step"] == "encoding"
+        assert result["progress_percent"] == 42.5
+
+
+class TestExpectedOutputDuration(unittest.TestCase):
+    def test_normal_export_uses_input_duration(self) -> None:
+        exporter = _make_exporter(end_minus_start=600)
+        assert exporter._expected_output_duration_seconds() == 600.0
+
+    def test_timelapse_uses_setpts_factor(self) -> None:
+        exporter = _make_exporter(
+            end_minus_start=1000,
+            ffmpeg_input_args="-y",
+            ffmpeg_output_args="-vf setpts=0.04*PTS -r 30",
+        )
+        # 1000s input * 0.04 = 40s of output
+        assert exporter._expected_output_duration_seconds() == 40.0
+
+    def test_unknown_factor_falls_back_to_input_duration(self) -> None:
+        exporter = _make_exporter(
+            end_minus_start=300,
+            ffmpeg_input_args="-y",
+            ffmpeg_output_args="-c:v libx264 -preset veryfast",
+        )
+        assert exporter._expected_output_duration_seconds() == 300.0
+
+    def test_zero_factor_falls_back_to_input_duration(self) -> None:
+        exporter = _make_exporter(
+            end_minus_start=300,
+            ffmpeg_input_args="-y",
+            ffmpeg_output_args="-vf setpts=0*PTS",
+        )
+        assert exporter._expected_output_duration_seconds() == 300.0
+
+    def test_uses_actual_recorded_seconds_when_available(self) -> None:
+        """If the DB shows only 120s of saved recordings inside a 1h
+        requested range, progress should be computed against 120s."""
+        exporter = _make_exporter(end_minus_start=3600)
+        exporter._sum_source_duration_seconds = lambda: 120.0  # type: ignore[method-assign]
+        assert exporter._expected_output_duration_seconds() == 120.0
+
+    def test_actual_recorded_seconds_scaled_by_setpts(self) -> None:
+        """Recorded duration must still be scaled by the timelapse factor."""
+        exporter = _make_exporter(
+            end_minus_start=3600,
+            ffmpeg_input_args="-y",
+            ffmpeg_output_args="-vf setpts=0.04*PTS -r 30",
+        )
+        exporter._sum_source_duration_seconds = lambda: 600.0  # type: ignore[method-assign]
+        # 600s * 0.04 = 24s of output
+        assert exporter._expected_output_duration_seconds() == 24.0
+
+    def test_db_failure_falls_back_to_requested_range(self) -> None:
+        exporter = _make_exporter(end_minus_start=300)
+        exporter._sum_source_duration_seconds = lambda: None  # type: ignore[method-assign]
+        assert exporter._expected_output_duration_seconds() == 300.0
+
+
+class TestProgressFlagInjection(unittest.TestCase):
+    def test_inserts_before_output_path(self) -> None:
+        exporter = _make_exporter()
+        cmd = ["ffmpeg", "-i", "input.m3u8", "-c", "copy", "/tmp/output.mp4"]
+
+        result = exporter._inject_progress_flags(cmd)
+
+        assert result == [
+            "ffmpeg",
+            "-i",
+            "input.m3u8",
+            "-c",
+            "copy",
+            "-progress",
+            "pipe:2",
+            "-nostats",
+            "/tmp/output.mp4",
+        ]
+
+    def test_handles_empty_cmd(self) -> None:
+        exporter = _make_exporter()
+        assert exporter._inject_progress_flags([]) == []
+
+
+class TestFfmpegProgressParsing(unittest.TestCase):
+    """Verify percentage calculation from FFmpeg ``-progress`` output."""
+
+    def _run_with_stderr(
+        self,
+        stderr_text: str,
+        expected_duration_seconds: int = 90,
+    ) -> list[tuple[str, float]]:
+        """Helper: run _run_ffmpeg_with_progress against a mocked Popen
+        whose stderr emits the supplied text. Returns the list of
+        (step, percent) tuples that the on_progress callback received."""
+        captured: list[tuple[str, float]] = []
+
+        def on_progress(step: str, percent: float) -> None:
+            captured.append((step, percent))
+
+        exporter = _make_exporter(
+            end_minus_start=expected_duration_seconds,
+            on_progress=on_progress,
+        )
+
+        fake_proc = MagicMock()
+        fake_proc.stdin = io.StringIO()
+        fake_proc.stderr = io.StringIO(stderr_text)
+        fake_proc.returncode = 0
+        fake_proc.wait = MagicMock(return_value=0)
+
+        with patch("frigate.record.export.sp.Popen", return_value=fake_proc):
+            returncode, _stderr = exporter._run_ffmpeg_with_progress(
+                ["ffmpeg", "-i", "x.m3u8", "/tmp/out.mp4"], "playlist", step="encoding"
+            )
+
+        assert returncode == 0
+        return captured
+
+    def test_parses_out_time_us_into_percent(self) -> None:
+        # 90s duration; 45s out_time => 50%
+        stderr = "out_time_us=45000000\nprogress=continue\n"
+        captured = self._run_with_stderr(stderr, expected_duration_seconds=90)
+
+        # The first call is the synchronous 0.0 emit before Popen runs.
+        assert captured[0] == ("encoding", 0.0)
+        assert any(percent == 50.0 for step, percent in captured if step == "encoding")
+
+    def test_progress_end_emits_100_percent(self) -> None:
+        stderr = "out_time_us=10000000\nprogress=end\n"
+        captured = self._run_with_stderr(stderr, expected_duration_seconds=90)
+
+        assert captured[-1] == ("encoding", 100.0)
+
+    def test_clamps_overshoot_at_100(self) -> None:
+        # 150s of output reported against 90s expected duration.
+        stderr = "out_time_us=150000000\nprogress=continue\n"
+        captured = self._run_with_stderr(stderr, expected_duration_seconds=90)
+
+        encoding_values = [p for s, p in captured if s == "encoding" and p > 0]
+        assert all(p <= 100.0 for p in encoding_values)
+        assert encoding_values[-1] == 100.0
+
+    def test_ignores_garbage_lines(self) -> None:
+        stderr = (
+            "frame=  120 fps= 30 q=23.0 size=    512kB\n"
+            "out_time_us=not-a-number\n"
+            "out_time_us=30000000\n"
+            "progress=continue\n"
+        )
+        captured = self._run_with_stderr(stderr, expected_duration_seconds=90)
+
+        # We expect 0.0 (from initial emit) plus the 30s/90s = 33.33...% step
+        encoding_percents = sorted({round(p, 2) for s, p in captured})
+        assert 0.0 in encoding_percents
+        assert any(abs(p - (30 / 90 * 100)) < 0.01 for p in encoding_percents)
+
+
+class TestBroadcastAggregation(unittest.TestCase):
+    """Verify ExportJobManager broadcast payload shape and throttling."""
+
+    def _make_manager(self) -> tuple[ExportJobManager, MagicMock]:
+        """Build a manager with an injected mock publisher. Returns
+        ``(manager, publisher)`` so tests can assert on broadcast payloads
+        without touching ZMQ at all."""
+        config = MagicMock()
+        publisher = MagicMock()
+        manager = ExportJobManager(
+            config, max_concurrent=2, max_queued=10, publisher=publisher
+        )
+        return manager, publisher
+
+    @staticmethod
+    def _last_payload(publisher: MagicMock) -> dict:
+        return publisher.publish.call_args.args[0]
+
+    def test_empty_jobs_broadcasts_empty_list(self) -> None:
+        manager, publisher = self._make_manager()
+        manager._broadcast_all_jobs(force=True)
+
+        publisher.publish.assert_called_once()
+        payload = self._last_payload(publisher)
+        assert payload["job_type"] == "export"
+        assert payload["status"] == "queued"
+        assert payload["results"]["jobs"] == []
+
+    def test_single_running_job_payload(self) -> None:
+        manager, publisher = self._make_manager()
+        job = ExportJob(camera="front", request_start_time=0, request_end_time=10)
+        job.status = JobStatusTypesEnum.running
+        job.current_step = "encoding"
+        job.progress_percent = 75.0
+        manager.jobs[job.id] = job
+
+        manager._broadcast_all_jobs(force=True)
+
+        payload = self._last_payload(publisher)
+        assert payload["status"] == "running"
+        assert len(payload["results"]["jobs"]) == 1
+        broadcast_job = payload["results"]["jobs"][0]
+        assert broadcast_job["current_step"] == "encoding"
+        assert broadcast_job["progress_percent"] == 75.0
+
+    def test_multiple_jobs_broadcast(self) -> None:
+        manager, publisher = self._make_manager()
+        for i, status in enumerate(
+            (JobStatusTypesEnum.queued, JobStatusTypesEnum.running)
+        ):
+            job = ExportJob(
+                id=f"job_{i}",
+                camera="front",
+                request_start_time=0,
+                request_end_time=10,
+            )
+            job.status = status
+            manager.jobs[job.id] = job
+
+        manager._broadcast_all_jobs(force=True)
+
+        payload = self._last_payload(publisher)
+        assert payload["status"] == "running"
+        assert len(payload["results"]["jobs"]) == 2
+
+    def test_completed_jobs_are_excluded(self) -> None:
+        manager, publisher = self._make_manager()
+        active = ExportJob(id="active", camera="front")
+        active.status = JobStatusTypesEnum.running
+        finished = ExportJob(id="done", camera="front")
+        finished.status = JobStatusTypesEnum.success
+        manager.jobs[active.id] = active
+        manager.jobs[finished.id] = finished
+
+        manager._broadcast_all_jobs(force=True)
+
+        payload = self._last_payload(publisher)
+        ids = [j["id"] for j in payload["results"]["jobs"]]
+        assert ids == ["active"]
+
+    def test_throttle_skips_rapid_unforced_broadcasts(self) -> None:
+        manager, publisher = self._make_manager()
+        job = ExportJob(camera="front")
+        job.status = JobStatusTypesEnum.running
+        manager.jobs[job.id] = job
+
+        manager._broadcast_all_jobs(force=True)
+        # Immediately following non-forced broadcasts should be skipped.
+        for _ in range(5):
+            manager._broadcast_all_jobs(force=False)
+
+        assert publisher.publish.call_count == 1
+
+    def test_throttle_allows_broadcast_after_interval(self) -> None:
+        manager, publisher = self._make_manager()
+        job = ExportJob(camera="front")
+        job.status = JobStatusTypesEnum.running
+        manager.jobs[job.id] = job
+
+        with patch("frigate.jobs.export.time.monotonic") as mock_mono:
+            mock_mono.return_value = 100.0
+            manager._broadcast_all_jobs(force=True)
+
+            mock_mono.return_value = 100.0 + PROGRESS_BROADCAST_MIN_INTERVAL + 0.01
+            manager._broadcast_all_jobs(force=False)
+
+        assert publisher.publish.call_count == 2
+
+    def test_force_bypasses_throttle(self) -> None:
+        manager, publisher = self._make_manager()
+        job = ExportJob(camera="front")
+        job.status = JobStatusTypesEnum.running
+        manager.jobs[job.id] = job
+
+        manager._broadcast_all_jobs(force=True)
+        manager._broadcast_all_jobs(force=True)
+
+        assert publisher.publish.call_count == 2
+
+    def test_publisher_exceptions_do_not_propagate(self) -> None:
+        """A failing publisher must not break the manager: broadcasts are
+        best-effort since the dispatcher may not be available (tests,
+        startup races)."""
+        manager, publisher = self._make_manager()
+        publisher.publish.side_effect = RuntimeError("comms down")
+
+        job = ExportJob(camera="front")
+        job.status = JobStatusTypesEnum.running
+        manager.jobs[job.id] = job
+
+        # Swallow our own RuntimeError if the manager doesn't; the real
+        # JobStatePublisher handles its own exceptions internally, so the
+        # manager can stay naive. But if something bubbles up it should
+        # not escape _broadcast_all_jobs — enforce that contract here.
+        try:
+            manager._broadcast_all_jobs(force=True)
+        except RuntimeError:
+            self.fail("_broadcast_all_jobs must tolerate publisher failures")
+
+    def test_progress_callback_updates_job_and_broadcasts(self) -> None:
+        manager, _publisher = self._make_manager()
+        job = ExportJob(camera="front")
+        job.status = JobStatusTypesEnum.running
+        manager.jobs[job.id] = job
+
+        callback = manager._make_progress_callback(job)
+        callback("encoding", 33.0)
+
+        assert job.current_step == "encoding"
+        assert job.progress_percent == 33.0
+
+
+class TestSchedulesCleanup(unittest.TestCase):
+    def test_schedule_job_cleanup_removes_after_delay(self) -> None:
+        config = MagicMock()
+        manager = ExportJobManager(config, max_concurrent=1, max_queued=1)
+        job = ExportJob(id="cleanup_me", camera="front")
+        manager.jobs[job.id] = job
+
+        with patch("frigate.jobs.export.threading.Timer") as mock_timer:
+            manager._schedule_job_cleanup(job.id)
+            mock_timer.assert_called_once()
+            delay, fn = mock_timer.call_args.args
+            assert delay > 0
+
+            # Invoke the callback directly to confirm it removes the job.
+            fn()
+            assert job.id not in manager.jobs
+
+
+if __name__ == "__main__":
+    unittest.main()

frigate/test/test_maintainer.py

@@ -1,3 +1,4 @@
+import datetime
 import sys
 import unittest
 from unittest.mock import MagicMock, patch
@@ -74,6 +75,46 @@ class TestMaintainer(unittest.IsolatedAsyncioTestCase):
                             f"Expected a single warning for unexpected files, got {len(matching)}",
                         )
 
+    async def test_drops_quiet_segment_when_only_motion_retention(self):
+        # Regression: when motion retention is enabled but a segment has no
+        # motion and no review overlaps it, the segment must still be dropped.
+        # Otherwise it sits in cache forever, accumulates, and triggers the
+        # "Unable to keep up with recording segments in cache" warning every
+        # ~10s as the overflow trim in move_files discards the oldest one.
+        config = MagicMock(spec=FrigateConfig)
+
+        camera_config = MagicMock()
+        camera_config.record.enabled = True
+        camera_config.record.continuous.days = 0
+        camera_config.record.motion.days = 1
+        camera_config.record.event_pre_capture = 5
+        config.cameras = {"test_cam": camera_config}
+
+        stop_event = MagicMock()
+        maintainer = RecordingMaintainer(config, stop_event)
+
+        now = datetime.datetime.now(datetime.timezone.utc)
+        start_time = now - datetime.timedelta(seconds=20)
+        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)}
+        # 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"] = []
+
+        maintainer.drop_segment = MagicMock()
+        maintainer.recordings_publisher = MagicMock()
+
+        result = await maintainer.validate_and_move_segment(
+            "test_cam",
+            reviews=[],
+            recording={"start_time": start_time, "cache_path": cache_path},
+        )
+
+        self.assertIsNone(result)
+        maintainer.drop_segment.assert_called_once_with(cache_path)
+
 
 if __name__ == "__main__":
     unittest.main()

frigate/test/test_output_ws_auth.py

@@ -0,0 +1,57 @@
+"""Tests for JSMPEG websocket authorization."""
+
+import unittest
+from types import SimpleNamespace
+
+from frigate.config import FrigateConfig
+from frigate.output.ws_auth import ws_has_camera_access
+
+
+class TestWsHasCameraAccess(unittest.TestCase):
+    def setUp(self):
+        self.config = FrigateConfig(
+            mqtt={"host": "mqtt"},
+            auth={"roles": {"limited_user": ["front_door"]}},
+            cameras={
+                "front_door": {
+                    "ffmpeg": {
+                        "inputs": [
+                            {"path": "rtsp://10.0.0.1:554/video", "roles": ["detect"]}
+                        ]
+                    },
+                    "detect": {"height": 1080, "width": 1920, "fps": 5},
+                },
+                "back_door": {
+                    "ffmpeg": {
+                        "inputs": [
+                            {"path": "rtsp://10.0.0.2:554/video", "roles": ["detect"]}
+                        ]
+                    },
+                    "detect": {"height": 1080, "width": 1920, "fps": 5},
+                },
+            },
+        )
+
+    def _make_ws(self, role: str):
+        return SimpleNamespace(environ={"HTTP_REMOTE_ROLE": role})
+
+    def test_restricted_role_only_gets_allowed_camera(self):
+        ws = self._make_ws("limited_user")
+        self.assertTrue(ws_has_camera_access(ws, "front_door", self.config))
+        self.assertFalse(ws_has_camera_access(ws, "back_door", self.config))
+
+    def test_unrestricted_role_can_access_any_camera(self):
+        ws = self._make_ws("viewer")
+        self.assertTrue(ws_has_camera_access(ws, "front_door", self.config))
+        self.assertTrue(ws_has_camera_access(ws, "back_door", self.config))
+
+    def test_birdseye_requires_unrestricted_access(self):
+        self.assertTrue(
+            ws_has_camera_access(self._make_ws("admin"), "birdseye", self.config)
+        )
+        self.assertTrue(
+            ws_has_camera_access(self._make_ws("viewer"), "birdseye", self.config)
+        )
+        self.assertFalse(
+            ws_has_camera_access(self._make_ws("limited_user"), "birdseye", self.config)
+        )

frigate/test/test_webpush_camera_monitoring.py

@@ -0,0 +1,29 @@
+"""Tests for camera monitoring notification authorization."""
+
+import unittest
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from frigate.comms.webpush import WebPushClient
+
+
+class TestCameraMonitoringNotifications(unittest.TestCase):
+    def test_send_camera_monitoring_filters_by_camera_access(self):
+        client = WebPushClient.__new__(WebPushClient)
+        client.config = SimpleNamespace(
+            cameras={"front_door": SimpleNamespace(friendly_name=None)}
+        )
+        client.web_pushers = {"allowed": [], "denied": []}
+        client.user_cameras = {"allowed": {"front_door"}, "denied": set()}
+        client.check_registrations = MagicMock()
+        client.cleanup_registrations = MagicMock()
+        client.send_push_notification = MagicMock()
+
+        client.send_camera_monitoring(
+            {"camera": "front_door", "message": "Monitoring condition met"}
+        )
+
+        self.assertEqual(client.send_push_notification.call_count, 1)
+        self.assertEqual(
+            client.send_push_notification.call_args.kwargs["user"], "allowed"
+        )

frigate/timeline.py

@@ -116,6 +116,8 @@ class TimelineProcessor(threading.Thread):
                 ),
                 "attribute": "",
                 "score": event_data["score"],
+                "computed_score": event_data.get("computed_score"),
+                "top_score": event_data.get("top_score"),
             },
         }
 

frigate/track/tracked_object.py

@@ -400,6 +400,7 @@ class TrackedObject:
             "start_time": self.obj_data["start_time"],
             "end_time": self.obj_data.get("end_time", None),
             "score": self.obj_data["score"],
+            "computed_score": self.computed_score,
             "box": self.obj_data["box"],
             "area": self.obj_data["area"],
             "ratio": self.obj_data["ratio"],

frigate/util/classification.py

@@ -24,8 +24,12 @@ from frigate.log import redirect_output_to_logger, suppress_stderr_during
 from frigate.models import Event, Recordings, ReviewSegment
 from frigate.types import ModelStatusTypesEnum
 from frigate.util.downloader import ModelDownloader
-from frigate.util.file import get_event_thumbnail_bytes
-from frigate.util.image import get_image_from_recording
+from frigate.util.file import get_event_thumbnail_bytes, load_event_snapshot_image
+from frigate.util.image import (
+    calculate_region,
+    get_image_from_recording,
+    relative_box_to_absolute,
+)
 from frigate.util.process import FrigateProcess
 
 BATCH_SIZE = 16
@@ -713,7 +717,7 @@ def collect_object_classification_examples(
     This function:
     1. Queries events for the specified label
     2. Selects 100 balanced events across different cameras and times
-    3. Retrieves thumbnails for selected events (with 33% center crop applied)
+    3. Crops each event's clean snapshot around the object bounding box
     4. Selects 24 most visually distinct thumbnails
     5. Saves to dataset directory
 
@@ -832,66 +836,106 @@ def _select_balanced_events(
 
 def _extract_event_thumbnails(events: list[Event], output_dir: str) -> list[str]:
     """
-    Extract thumbnails from events and save to disk.
+    Extract a training image for each event.
+
+    Preferred path: load the full-frame clean snapshot and crop around the
+    stored bounding box with the same calculate_region(..., max(w, h), 1.0)
+    call the live ObjectClassificationProcessor uses, so wizard examples
+    are framed like inference-time inputs.
+
+    Fallback: if no clean snapshot exists (snapshots disabled, or only a
+    legacy annotated JPG is on disk), center-crop the stored thumbnail
+    using a step ladder sized from the box/region area ratio.
 
     Args:
         events: List of Event objects
-        output_dir: Directory to save thumbnails
+        output_dir: Directory to save crops
 
     Returns:
-        List of paths to successfully extracted thumbnail images
+        List of paths to successfully extracted images
     """
-    thumbnail_paths = []
+    image_paths = []
 
     for idx, event in enumerate(events):
         try:
-            thumbnail_bytes = get_event_thumbnail_bytes(event)
+            img = _load_event_classification_crop(event)
+            if img is None:
+                continue
 
-            if thumbnail_bytes:
-                nparr = np.frombuffer(thumbnail_bytes, np.uint8)
-                img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
-
-                if img is not None:
-                    height, width = img.shape[:2]
-
-                    crop_size = 1.0
-                    if event.data and "box" in event.data and "region" in event.data:
-                        box = event.data["box"]
-                        region = event.data["region"]
-
-                        if len(box) == 4 and len(region) == 4:
-                            box_w, box_h = box[2], box[3]
-                            region_w, region_h = region[2], region[3]
-
-                            box_area = (box_w * box_h) / (region_w * region_h)
-
-                            if box_area < 0.05:
-                                crop_size = 0.4
-                            elif box_area < 0.10:
-                                crop_size = 0.5
-                            elif box_area < 0.20:
-                                crop_size = 0.65
-                            elif box_area < 0.35:
-                                crop_size = 0.80
-                            else:
-                                crop_size = 0.95
-
-                    crop_width = int(width * crop_size)
-                    crop_height = int(height * crop_size)
-
-                    x1 = (width - crop_width) // 2
-                    y1 = (height - crop_height) // 2
-                    x2 = x1 + crop_width
-                    y2 = y1 + crop_height
-
-                    cropped = img[y1:y2, x1:x2]
-                    resized = cv2.resize(cropped, (224, 224))
-                    output_path = os.path.join(output_dir, f"thumbnail_{idx:04d}.jpg")
-                    cv2.imwrite(output_path, resized)
-                    thumbnail_paths.append(output_path)
+            resized = cv2.resize(img, (224, 224))
+            output_path = os.path.join(output_dir, f"thumbnail_{idx:04d}.jpg")
+            cv2.imwrite(output_path, resized)
+            image_paths.append(output_path)
 
         except Exception as e:
-            logger.debug(f"Failed to extract thumbnail for event {event.id}: {e}")
+            logger.debug(f"Failed to extract image for event {event.id}: {e}")
             continue
 
-    return thumbnail_paths
+    return image_paths
+
+
+def _load_event_classification_crop(event: Event) -> np.ndarray | None:
+    """Prefer a snapshot-based object crop; fall back to a center-cropped thumbnail."""
+    if event.data and "box" in event.data:
+        snapshot, _ = load_event_snapshot_image(event, clean_only=True)
+        if snapshot is not None:
+            abs_box = relative_box_to_absolute(snapshot.shape, event.data["box"])
+            if abs_box is not None:
+                xmin, ymin, xmax, ymax = abs_box
+                box_w = xmax - xmin
+                box_h = ymax - ymin
+                if box_w > 0 and box_h > 0:
+                    x1, y1, x2, y2 = calculate_region(
+                        snapshot.shape,
+                        xmin,
+                        ymin,
+                        xmax,
+                        ymax,
+                        max(box_w, box_h),
+                        1.0,
+                    )
+                    cropped = snapshot[y1:y2, x1:x2]
+                    if cropped.size > 0:
+                        return cropped
+
+    thumbnail_bytes = get_event_thumbnail_bytes(event)
+    if not thumbnail_bytes:
+        return None
+
+    nparr = np.frombuffer(thumbnail_bytes, np.uint8)
+    img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+    if img is None or img.size == 0:
+        return None
+
+    height, width = img.shape[:2]
+    crop_size = 1.0
+
+    if event.data and "box" in event.data and "region" in event.data:
+        box = event.data["box"]
+        region = event.data["region"]
+
+        if len(box) == 4 and len(region) == 4:
+            box_w, box_h = box[2], box[3]
+            region_w, region_h = region[2], region[3]
+            box_area = (box_w * box_h) / (region_w * region_h)
+
+            if box_area < 0.05:
+                crop_size = 0.4
+            elif box_area < 0.10:
+                crop_size = 0.5
+            elif box_area < 0.20:
+                crop_size = 0.65
+            elif box_area < 0.35:
+                crop_size = 0.80
+            else:
+                crop_size = 0.95
+
+    crop_width = int(width * crop_size)
+    crop_height = int(height * crop_size)
+    x1 = (width - crop_width) // 2
+    y1 = (height - crop_height) // 2
+    cropped = img[y1 : y1 + crop_height, x1 : x1 + crop_width]
+    if cropped.size == 0:
+        return None
+
+    return cropped

frigate/util/object.py

@@ -62,11 +62,12 @@ def get_camera_regions_grid(
         .where((Event.false_positive == None) | (Event.false_positive == False))
         .where(Event.start_time > last_update)
     )
-    valid_event_ids = [e["id"] for e in events.dicts()]
-    logger.debug(f"Found {len(valid_event_ids)} new events for {name}")
+
+    event_count = events.count()
+    logger.debug(f"Found {event_count} new events for {name}")
 
     # no new events, return as is
-    if not valid_event_ids:
+    if event_count == 0:
         return grid
 
     new_update = datetime.datetime.now().timestamp()
@@ -78,7 +79,7 @@ def get_camera_regions_grid(
                 Timeline.data,
             ]
         )
-        .where(Timeline.source_id << valid_event_ids)
+        .where(Timeline.source_id << events)
         .limit(10000)
         .dicts()
     )

frigate/util/services.py

@@ -711,23 +711,44 @@ def ffprobe_stream(ffmpeg, path: str, detailed: bool = False) -> sp.CompletedPro
     else:
         format_entries = None
 
-    ffprobe_cmd = [
-        ffmpeg.ffprobe_path,
-        "-timeout",
-        "1000000",
-        "-print_format",
-        "json",
-        "-show_entries",
-        f"stream={stream_entries}",
-    ]
+    def run(rtsp_transport: Optional[str] = None) -> sp.CompletedProcess:
+        cmd = [ffmpeg.ffprobe_path]
+        if rtsp_transport:
+            cmd += ["-rtsp_transport", rtsp_transport]
+        cmd += [
+            "-timeout",
+            "1000000",
+            "-print_format",
+            "json",
+            "-show_entries",
+            f"stream={stream_entries}",
+        ]
+        if detailed and format_entries:
+            cmd.extend(["-show_entries", f"format={format_entries}"])
+        cmd.extend(["-loglevel", "error", clean_path])
+        try:
+            return sp.run(cmd, capture_output=True, timeout=6)
+        except sp.TimeoutExpired as e:
+            logger.info(
+                "ffprobe timed out while probing %s (transport=%s)",
+                clean_camera_user_pass(path),
+                rtsp_transport or "default",
+            )
+            return sp.CompletedProcess(
+                args=cmd,
+                returncode=1,
+                stdout=e.stdout or b"",
+                stderr=(e.stderr or b"") + b"\nffprobe timed out",
+            )
 
-    # Add format entries for detailed mode
-    if detailed and format_entries:
-        ffprobe_cmd.extend(["-show_entries", f"format={format_entries}"])
+    result = run()
 
-    ffprobe_cmd.extend(["-loglevel", "error", clean_path])
+    # For RTSP: retry with explicit TCP transport if the first attempt failed
+    # (default UDP may be blocked)
+    if result.returncode != 0 and clean_path.startswith("rtsp://"):
+        result = run(rtsp_transport="tcp")
 
-    return sp.run(ffprobe_cmd, capture_output=True)
+    return result
 
 
 def vainfo_hwaccel(device_name: Optional[str] = None) -> sp.CompletedProcess:
@@ -807,10 +828,15 @@ async def get_video_properties(
 ) -> dict[str, Any]:
     async def probe_with_ffprobe(
         url: str,
+        rtsp_transport: Optional[str] = None,
     ) -> tuple[bool, int, int, Optional[str], float]:
         """Fallback using ffprobe: returns (valid, width, height, codec, duration)."""
-        cmd = [
-            ffmpeg.ffprobe_path,
+        cmd = [ffmpeg.ffprobe_path]
+        if rtsp_transport:
+            cmd += ["-rtsp_transport", rtsp_transport]
+        cmd += [
+            "-rw_timeout",
+            "5000000",
             "-v",
             "quiet",
             "-print_format",
@@ -819,11 +845,23 @@ async def get_video_properties(
             "-show_streams",
             url,
         ]
+        proc = None
         try:
             proc = await asyncio.create_subprocess_exec(
                 *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
             )
-            stdout, _ = await proc.communicate()
+            try:
+                stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=6)
+            except asyncio.TimeoutError:
+                logger.info(
+                    "ffprobe timed out while probing %s (transport=%s)",
+                    clean_camera_user_pass(url),
+                    rtsp_transport or "default",
+                )
+                proc.kill()
+                await proc.wait()
+                return False, 0, 0, None, -1
+
             if proc.returncode != 0:
                 return False, 0, 0, None, -1
 
@@ -872,12 +910,26 @@ async def get_video_properties(
         cap.release()
         return valid, width, height, fourcc, duration
 
-    # try cv2 first
-    has_video, width, height, fourcc, duration = probe_with_cv2(url)
+    is_rtsp = url.startswith("rtsp://")
 
-    # fallback to ffprobe if needed
-    if not has_video or (get_duration and duration < 0):
+    if is_rtsp:
+        # 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)
+    else:
+        # try cv2 first for local files, HTTP, RTMP
+        has_video, width, height, fourcc, duration = 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)
+
+    # 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"
+        )
 
     result: dict[str, Any] = {"has_valid_video": has_video}
     if has_video:

frigate/video/ffmpeg.py

@@ -24,7 +24,7 @@ from frigate.config.camera.updater import (
 )
 from frigate.const import PROCESS_PRIORITY_HIGH
 from frigate.log import LogPipe
-from frigate.util.builtin import EventsPerSecond
+from frigate.util.builtin import EventsPerSecond, get_ffmpeg_arg_list
 from frigate.util.ffmpeg import start_or_restart_ffmpeg, stop_ffmpeg
 from frigate.util.image import (
     FrameManager,
@@ -34,6 +34,23 @@ from frigate.util.process import FrigateProcess
 
 logger = logging.getLogger(__name__)
 
+# all built-in record presets use this segment_time
+DEFAULT_RECORD_SEGMENT_TIME = 10
+
+
+def _get_record_segment_time(config: CameraConfig) -> int:
+    """Extract -segment_time from the camera's record output args."""
+    record_args = get_ffmpeg_arg_list(config.ffmpeg.output_args.record)
+
+    if record_args and record_args[0].startswith("preset"):
+        return DEFAULT_RECORD_SEGMENT_TIME
+
+    try:
+        idx = record_args.index("-segment_time")
+        return int(record_args[idx + 1])
+    except (ValueError, IndexError):
+        return DEFAULT_RECORD_SEGMENT_TIME
+
 
 def capture_frames(
     ffmpeg_process: sp.Popen[Any],
@@ -164,6 +181,12 @@ class CameraWatchdog(threading.Thread):
         self.latest_cache_segment_time: float = 0
         self.record_enable_time: datetime | None = None
 
+        # `valid` segments are published with the segment's start time, so the
+        # gap between consecutive publishes can reach 2 * segment_time. Pad the
+        # staleness threshold so it's never tighter than that worst case.
+        segment_time = _get_record_segment_time(self.config)
+        self.record_stale_threshold = max(120, 2 * segment_time + 30)
+
         # Stall tracking (based on last processed frame)
         self._stall_timestamps: deque[float] = deque()
         self._stall_active: bool = False
@@ -317,16 +340,16 @@ class CameraWatchdog(threading.Thread):
                     if camera != self.config.name:
                         continue
 
-                    if topic.endswith(RecordingsDataTypeEnum.valid.value):
-                        self.logger.debug(
-                            f"Latest valid recording segment time on {camera}: {segment_time}"
-                        )
-                        self.latest_valid_segment_time = segment_time
-                    elif topic.endswith(RecordingsDataTypeEnum.invalid.value):
+                    if topic.endswith(RecordingsDataTypeEnum.invalid.value):
                         self.logger.warning(
                             f"Invalid recording segment detected for {camera} at {segment_time}"
                         )
                         self.latest_invalid_segment_time = segment_time
+                    elif topic.endswith(RecordingsDataTypeEnum.valid.value):
+                        self.logger.debug(
+                            f"Latest valid recording segment time on {camera}: {segment_time}"
+                        )
+                        self.latest_valid_segment_time = segment_time
                     elif topic.endswith(RecordingsDataTypeEnum.latest.value):
                         if segment_time is not None:
                             self.latest_cache_segment_time = segment_time
@@ -413,16 +436,17 @@ class CameraWatchdog(threading.Thread):
 
                     # ensure segments are still being created and that they have valid video data
                     # Skip checks during grace period to allow segments to start being created
+                    stale_window = timedelta(seconds=self.record_stale_threshold)
                     cache_stale = not in_grace_period and now_utc > (
-                        latest_cache_dt + timedelta(seconds=120)
+                        latest_cache_dt + stale_window
                     )
                     valid_stale = not in_grace_period and now_utc > (
-                        latest_valid_dt + timedelta(seconds=120)
+                        latest_valid_dt + stale_window
                     )
                     invalid_stale_condition = (
                         self.latest_invalid_segment_time > 0
                         and not in_grace_period
-                        and now_utc > (latest_invalid_dt + timedelta(seconds=120))
+                        and now_utc > (latest_invalid_dt + stale_window)
                         and self.latest_valid_segment_time
                         <= self.latest_invalid_segment_time
                     )
@@ -439,7 +463,7 @@ class CameraWatchdog(threading.Thread):
                             )
 
                         self.logger.error(
-                            f"{reason} for {self.config.name} in the last 120s. Restarting the ffmpeg record process..."
+                            f"{reason} for {self.config.name} in the last {self.record_stale_threshold}s. Restarting the ffmpeg record process..."
                         )
                         p["process"] = start_or_restart_ffmpeg(
                             p["cmd"],
@@ -471,8 +495,16 @@ class CameraWatchdog(threading.Thread):
                     p["cmd"], self.logger, p["logpipe"], ffmpeg_process=p["process"]
                 )
 
-            # Update stall metrics based on last processed frame timestamp
+            # Prune expired reconnect timestamps
             now = datetime.now().timestamp()
+            while (
+                self.reconnect_timestamps and self.reconnect_timestamps[0] < now - 3600
+            ):
+                self.reconnect_timestamps.popleft()
+            if self.reconnects:
+                self.reconnects.value = len(self.reconnect_timestamps)
+
+            # Update stall metrics based on last processed frame timestamp
             processed_ts = (
                 float(self.detection_frame.value) if self.detection_frame else 0.0
             )

frigate/watchdog.py

@@ -28,6 +28,7 @@ class MonitoredProcess:
     restart_timestamps: deque[float] = field(
         default_factory=lambda: deque(maxlen=MAX_RESTARTS)
     )
+    clean_exit_logged: bool = False
 
     def is_restarting_too_fast(self, now: float) -> bool:
         while (
@@ -72,7 +73,9 @@ class FrigateWatchdog(threading.Thread):
 
         exitcode = entry.process.exitcode
         if exitcode == 0:
-            logger.info("Process %s exited cleanly, not restarting", entry.name)
+            if not entry.clean_exit_logged:
+                logger.info("Process %s exited cleanly, not restarting", entry.name)
+                entry.clean_exit_logged = True
             return
 
         logger.warning(

testing-scripts/analyze_recording_keyframes.py

@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+"""Analyze keyframe and timestamp structure of Frigate recording segments.
+
+This is a diagnostic tool for investigating seek precision / GOP behavior on
+recorded segments. It does not modify anything.
+
+ffprobe is only available inside the Frigate container, at
+    /usr/lib/ffmpeg/$DEFAULT_FFMPEG_VERSION/bin/ffprobe
+This script auto-resolves that path from the DEFAULT_FFMPEG_VERSION env var
+(or falls back to scanning /usr/lib/ffmpeg/*/bin/ffprobe). Pass --ffprobe to
+override if needed.
+
+All recording segments on the filesystem are in UTC. The --timestamp flag
+expects a UTC Unix timestamp.
+
+Typical use:
+    # Inside the Frigate container (or wherever recordings are mounted)
+    python3 analyze_recording_keyframes.py <camera_name>
+
+    # Analyze 10 most recent segments
+    python3 analyze_recording_keyframes.py <camera_name> --count 10
+
+    # Locate the segment that contains a specific UTC Unix timestamp and
+    # show it plus surrounding segments
+    python3 analyze_recording_keyframes.py <camera> --timestamp 1713471234.567
+
+    # Custom recordings directory
+    python3 analyze_recording_keyframes.py <camera> --recordings-dir /media/frigate/recordings
+
+    # Override the ffprobe path explicitly
+    python3 analyze_recording_keyframes.py <camera> --ffprobe /usr/lib/ffmpeg/7.0/bin/ffprobe
+"""
+
+import argparse
+import datetime
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from statistics import mean, median, stdev
+
+
+def resolve_ffprobe_path(override: str | None) -> str:
+    """Resolve the ffprobe binary path.
+
+    Inside the Frigate container, ffprobe lives at
+    /usr/lib/ffmpeg/{DEFAULT_FFMPEG_VERSION}/bin/ffprobe — the exact version
+    depends on the image build and is exposed as an env var.
+    """
+    if override:
+        return override
+    version = os.environ.get("DEFAULT_FFMPEG_VERSION", "")
+    if version:
+        path = f"/usr/lib/ffmpeg/{version}/bin/ffprobe"
+        if Path(path).is_file():
+            return path
+    # Fall back to scanning the Frigate ffmpeg install root.
+    for candidate in sorted(Path("/usr/lib/ffmpeg").glob("*/bin/ffprobe")):
+        if candidate.is_file():
+            return str(candidate)
+    print(
+        "Could not locate ffprobe. Pass --ffprobe <path> or set "
+        "DEFAULT_FFMPEG_VERSION.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def find_recent_segments(recordings_dir: Path, camera: str, count: int) -> list[Path]:
+    """Return the N most recent .mp4 segments for the given camera.
+
+    Expected layout: <recordings_dir>/<YYYY-MM-DD>/<HH>/<camera>/<MM>.<SS>.mp4
+    """
+    pattern = f"*/*/{camera}/*.mp4"
+    segments = sorted(recordings_dir.glob(pattern))
+    return segments[-count:]
+
+
+def find_segments_near_timestamp(
+    recordings_dir: Path, camera: str, target_ts: float, count: int
+) -> tuple[list[Path], Path | None]:
+    """Return `count` segments centered on the one containing `target_ts`.
+
+    Also returns the specific segment that should contain the timestamp, so
+    callers can highlight it in output.
+    """
+    pattern = f"*/*/{camera}/*.mp4"
+    with_ts: list[tuple[float, Path]] = []
+    for seg in sorted(recordings_dir.glob(pattern)):
+        ts = filename_to_timestamp(seg)
+        if ts is not None:
+            with_ts.append((ts, seg))
+
+    if not with_ts:
+        return [], None
+
+    # Largest filename_ts that is <= target_ts — that's the segment that
+    # should contain the timestamp (Frigate catalogs segments by filename).
+    target_idx = -1
+    for i, (ts, _) in enumerate(with_ts):
+        if ts <= target_ts:
+            target_idx = i
+        else:
+            break
+
+    if target_idx < 0:
+        # target_ts is before the earliest segment we have — just return the
+        # first `count` segments so the user can see what's available.
+        window = with_ts[:count]
+        return [seg for _, seg in window], None
+
+    half = count // 2
+    start = max(0, target_idx - half)
+    end = min(len(with_ts), start + count)
+    start = max(0, end - count)
+
+    window = with_ts[start:end]
+    return [seg for _, seg in window], with_ts[target_idx][1]
+
+
+def filename_to_timestamp(segment: Path) -> float | None:
+    """Parse the wall-clock time from Frigate's segment path layout."""
+    try:
+        date = segment.parent.parent.parent.name  # YYYY-MM-DD
+        hour = segment.parent.parent.name  # HH
+        mm_ss = segment.stem  # MM.SS
+        minute, second = mm_ss.split(".")
+        dt = datetime.datetime.strptime(
+            f"{date} {hour}:{minute}:{second}",
+            "%Y-%m-%d %H:%M:%S",
+        ).replace(tzinfo=datetime.timezone.utc)
+        return dt.timestamp()
+    except (ValueError, IndexError):
+        return None
+
+
+def run_ffprobe(ffprobe: str, args: list[str]) -> dict:
+    """Run ffprobe and return parsed JSON, or empty dict on failure."""
+    result = subprocess.run(
+        [ffprobe, "-v", "error", *args, "-of", "json"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(f"  ffprobe error: {result.stderr.strip()}", file=sys.stderr)
+        return {}
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        return {}
+
+
+def get_format_info(ffprobe: str, segment: Path) -> tuple[dict, dict]:
+    """Return (format_dict, stream_dict) for the first video stream."""
+    data = run_ffprobe(
+        ffprobe,
+        [
+            "-show_entries",
+            "format=duration,start_time",
+            "-show_entries",
+            "stream=codec_name,profile,r_frame_rate,width,height",
+            "-select_streams",
+            "v:0",
+            str(segment),
+        ],
+    )
+    fmt = data.get("format", {})
+    streams = data.get("streams") or [{}]
+    return fmt, streams[0]
+
+
+def get_video_packets(ffprobe: str, segment: Path) -> list[dict]:
+    """Return video packets with pts_time and flags."""
+    data = run_ffprobe(
+        ffprobe,
+        [
+            "-select_streams",
+            "v",
+            "-show_entries",
+            "packet=pts_time,dts_time,flags",
+            str(segment),
+        ],
+    )
+    return data.get("packets", [])
+
+
+def analyze(ffprobe: str, segment: Path, highlight: bool = False) -> None:
+    marker = "  <-- contains target timestamp" if highlight else ""
+    print(f"\n=== {segment} ==={marker}")
+
+    fmt, stream = get_format_info(ffprobe, segment)
+    duration = float(fmt.get("duration", 0) or 0)
+    start_time = float(fmt.get("start_time", 0) or 0)
+    codec = stream.get("codec_name", "?")
+    profile = stream.get("profile", "?")
+    width = stream.get("width", "?")
+    height = stream.get("height", "?")
+    fps = stream.get("r_frame_rate", "?/1")
+
+    filename_ts = filename_to_timestamp(segment)
+    filename_iso = (
+        datetime.datetime.fromtimestamp(
+            filename_ts, tz=datetime.timezone.utc
+        ).isoformat()
+        if filename_ts is not None
+        else "?"
+    )
+
+    print(f"  Codec:           {codec} ({profile})  {width}x{height}  {fps}")
+    print(f"  Filename time:   {filename_ts}  ({filename_iso})")
+    print(f"  Format duration: {duration:.3f}s")
+    print(f"  Format start:    {start_time:.3f}s  (PTS offset of first packet)")
+
+    packets = get_video_packets(ffprobe, segment)
+    if not packets:
+        print("  (no video packets)")
+        return
+
+    keyframe_times: list[float] = []
+    first_pts: float | None = None
+    last_pts: float | None = None
+
+    for pkt in packets:
+        pts_str = pkt.get("pts_time")
+        if pts_str is None or pts_str == "N/A":
+            continue
+        pts = float(pts_str)
+        if first_pts is None:
+            first_pts = pts
+        last_pts = pts
+        if "K" in pkt.get("flags", ""):
+            keyframe_times.append(pts)
+
+    total_packets = len(packets)
+    kf_count = len(keyframe_times)
+
+    print(f"  Video packets:   {total_packets}")
+    print(f"  Keyframes:       {kf_count}")
+    if first_pts is not None and last_pts is not None:
+        print(
+            f"  Packet PTS:      first={first_pts:.3f}s  last={last_pts:.3f}s  "
+            f"span={last_pts - first_pts:.3f}s"
+        )
+
+    if keyframe_times:
+        print(
+            f"  Keyframe PTS:    first={keyframe_times[0]:.3f}s  "
+            f"last={keyframe_times[-1]:.3f}s"
+        )
+        formatted = ", ".join(f"{t:.3f}" for t in keyframe_times)
+        print(f"  Keyframe times:  [{formatted}]")
+
+    if len(keyframe_times) >= 2:
+        gaps = [b - a for a, b in zip(keyframe_times, keyframe_times[1:])]
+        avg_fps_estimate = (
+            total_packets / (last_pts - first_pts)
+            if last_pts and first_pts is not None and last_pts > first_pts
+            else 0
+        )
+        print(
+            f"  GOP gaps (s):    min={min(gaps):.3f}  max={max(gaps):.3f}  "
+            f"mean={mean(gaps):.3f}  median={median(gaps):.3f}"
+        )
+        if len(gaps) > 1:
+            print(f"                   stdev={stdev(gaps):.3f}")
+        print(
+            f"  Est. mean GOP:   ~{mean(gaps) * avg_fps_estimate:.1f} frames"
+            if avg_fps_estimate
+            else ""
+        )
+        if max(gaps) > 5:
+            print(
+                "  !! Max GOP > 5s — consistent with adaptive/smart codec "
+                "(even if 'Smart Codec' is off in the UI, some cameras still "
+                "produce irregular GOPs under specific encoder profiles)"
+            )
+    elif kf_count == 1:
+        print("  !! Only one keyframe in segment — very long GOP")
+
+    # Report how well filename time aligns with first-packet PTS.
+    # (Filename time is what Frigate uses as recording.start_time in the DB.)
+    if filename_ts is not None and first_pts is not None:
+        print(
+            f"  Notes: first packet PTS is {first_pts:.3f}s into the file; "
+            f"Frigate treats filename time as PTS=0 for seek math."
+        )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("camera", help="Camera name (matches the recordings subfolder)")
+    parser.add_argument(
+        "--count",
+        type=int,
+        default=5,
+        help="Number of most recent segments to analyze (default: 5)",
+    )
+    parser.add_argument(
+        "--recordings-dir",
+        default="/media/frigate/recordings",
+        help="Path to the recordings directory (default: /media/frigate/recordings)",
+    )
+    parser.add_argument(
+        "--ffprobe",
+        default=None,
+        help=(
+            "Full path to the ffprobe binary. Defaults to the Frigate-bundled "
+            "binary at /usr/lib/ffmpeg/$DEFAULT_FFMPEG_VERSION/bin/ffprobe."
+        ),
+    )
+    parser.add_argument(
+        "--timestamp",
+        type=float,
+        default=None,
+        help=(
+            "Unix timestamp (UTC seconds, decimals allowed) to locate. The "
+            "script finds the segment that should contain this time and "
+            "analyzes it plus surrounding segments (count controls the "
+            "window). All on-disk segments are stored in UTC, so pass a UTC "
+            "Unix timestamp."
+        ),
+    )
+    args = parser.parse_args()
+
+    ffprobe = resolve_ffprobe_path(args.ffprobe)
+
+    recordings_dir = Path(args.recordings_dir)
+    if not recordings_dir.is_dir():
+        print(
+            f"Recordings directory not found: {recordings_dir}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    target_segment: Path | None = None
+    if args.timestamp is not None:
+        segments, target_segment = find_segments_near_timestamp(
+            recordings_dir, args.camera, args.timestamp, args.count
+        )
+        target_iso = datetime.datetime.fromtimestamp(
+            args.timestamp, tz=datetime.timezone.utc
+        ).isoformat()
+        mode = f"around timestamp {args.timestamp} ({target_iso})"
+    else:
+        segments = find_recent_segments(recordings_dir, args.camera, args.count)
+        mode = "most recent"
+
+    if not segments:
+        print(
+            f"No segments found for camera '{args.camera}' under {recordings_dir}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if args.timestamp is not None and target_segment is None:
+        print(
+            f"!! Target timestamp {args.timestamp} is before the earliest "
+            f"segment on disk; showing the earliest available segments instead.",
+            file=sys.stderr,
+        )
+
+    print(
+        f"Analyzing {len(segments)} {mode} segment(s) for camera "
+        f"'{args.camera}' under {recordings_dir} (ffprobe: {ffprobe})"
+    )
+    for segment in segments:
+        analyze(ffprobe, segment, highlight=(segment == target_segment))
+
+
+if __name__ == "__main__":
+    main()