serialize recording frame extraction for review descriptions

- Run frame gathering for finished review items on a thread so per-frame ffmpeg calls don't stall the embeddings maintainer
- Share one path between live and regenerated review descriptions
- Stop padding review start and end times in place, which widened the stored review item
- Lock timestamp expiry in EventsPerSecond since update() and eps() now run on different threads

.cspell/frigate-dictionary.txt

@@ -181,6 +181,7 @@ noninteractive
 noprint
 Norfair
 nptype
+NTFS
 NTSC
 numpy
 nvenc

.devcontainer/devcontainer-lock.json

@@ -0,0 +1,9 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "version": "2.7.1",
+      "resolved": "ghcr.io/devcontainers/features/common-utils@sha256:e76a6a8a35d1ad824daad1540725e0ec9f8ed2dc00d2850e990a9830013c7d08",
+      "integrity": "sha256:e76a6a8a35d1ad824daad1540725e0ec9f8ed2dc00d2850e990a9830013c7d08"
+    }
+  }
+}

.github/actions/setup/action.yml

@@ -4,6 +4,8 @@ inputs:
   GITHUB_TOKEN:
     required: true
 outputs:
+  image-repo:
+    value: ghcr.io/${{ steps.lowercaseRepo.outputs.lowercase }}
   image-name:
     value: ghcr.io/${{ steps.lowercaseRepo.outputs.lowercase }}:${{ steps.create-short-sha.outputs.SHORT_SHA }}
   cache-name:
@@ -42,7 +44,7 @@ runs:
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v4
     - name: Log in to the Container registry
-      uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f
+      uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550
       with:
         registry: ghcr.io
         username: ${{ github.actor }}

.github/dependabot.yml

@@ -55,6 +55,9 @@ updates:
       # Needs Python 3.12 and numpy 2
       - dependency-name: "librosa"
         versions: [">=1.0"]
+      # pandas 3.1 requires numpy 2
+      - dependency-name: "pandas"
+        versions: [">=3.1"]
       # Needs Python 3.12
       - dependency-name: "scipy"
         versions: [">=1.18"]
@@ -133,9 +136,6 @@ updates:
       # Later versions need Node 22 and extract false keys
       - dependency-name: "i18next-cli"
         versions: [">1.5.11"]
-      # 6.11.0 refills the saved model in the GenAI settings form
-      - dependency-name: "@rjsf/*"
-        versions: ["6.11.0"]
 
   - package-ecosystem: "npm"
     directory: "/docs"

.github/workflows/ci.yml

@@ -423,6 +423,11 @@ jobs:
         run: docker rm -f frigate || true
   arm64_build:
     runs-on: ubuntu-22.04-arm
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
     name: ARM Build
     steps:
       - name: Check out code
@@ -435,6 +440,7 @@ jobs:
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Build and push arm64 standard build
+        id: standard-arm64
         uses: docker/build-push-action@v7
         with:
           context: .
@@ -445,6 +451,13 @@ jobs:
           tags: |
             ${{ steps.setup.outputs.image-name }}-standard-arm64
           cache-from: type=registry,ref=${{ steps.setup.outputs.cache-name }}-arm64
+      - name: Attest arm64 standard build
+        uses: actions/attest@v4
+        with:
+          subject-name: ${{ steps.setup.outputs.image-repo }}
+          subject-digest: ${{ steps.standard-arm64.outputs.digest }}
+          push-to-registry: true
+          create-storage-record: false
       - name: Build and push RPi build
         uses: docker/bake-action@v7
         with:
@@ -458,6 +471,11 @@ jobs:
             *.cache-to=type=registry,ref=${{ steps.setup.outputs.cache-name }}-arm64,mode=max
   jetson_jp6_build:
     runs-on: ubuntu-22.04-arm
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
     name: Jetson Jetpack 6
     steps:
       - name: Check out code
@@ -470,6 +488,7 @@ jobs:
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Build and push TensorRT (Jetson, Jetpack 6)
+        id: tensorrt-jp6
         env:
           ARCH: arm64
           BASE_IMAGE: nvcr.io/nvidia/tensorrt:23.12-py3-igpu
@@ -485,8 +504,20 @@ jobs:
             tensorrt.tags=${{ steps.setup.outputs.image-name }}-tensorrt-jp6
             *.cache-from=type=registry,ref=${{ steps.setup.outputs.cache-name }}-jp6
             *.cache-to=type=registry,ref=${{ steps.setup.outputs.cache-name }}-jp6,mode=max
+      - name: Attest TensorRT (Jetson, Jetpack 6)
+        uses: actions/attest@v4
+        with:
+          subject-name: ${{ steps.setup.outputs.image-repo }}
+          subject-digest: ${{ fromJSON(steps.tensorrt-jp6.outputs.metadata)['tensorrt']['containerimage.digest'] }}
+          push-to-registry: true
+          create-storage-record: false
   amd64_extra_builds:
     runs-on: ubuntu-22.04
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
     name: AMD64 Extra Build
     needs:
       - amd64_build
@@ -501,6 +532,7 @@ jobs:
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Build and push TensorRT (x86 GPU)
+        id: tensorrt
         env:
           COMPUTE_LEVEL: "50 60 70 80 90"
         uses: docker/bake-action@v7
@@ -513,7 +545,15 @@ jobs:
             tensorrt.tags=${{ steps.setup.outputs.image-name }}-tensorrt
             *.cache-from=type=registry,ref=${{ steps.setup.outputs.cache-name }}-tensorrt
             *.cache-to=type=registry,ref=${{ steps.setup.outputs.cache-name }}-tensorrt,mode=max
+      - name: Attest TensorRT (x86 GPU)
+        uses: actions/attest@v4
+        with:
+          subject-name: ${{ steps.setup.outputs.image-repo }}
+          subject-digest: ${{ fromJSON(steps.tensorrt.outputs.metadata)['tensorrt']['containerimage.digest'] }}
+          push-to-registry: true
+          create-storage-record: false
       - name: AMD/ROCm general build
+        id: rocm
         env:
           HSA_OVERRIDE: 0
         uses: docker/bake-action@v7
@@ -526,8 +566,20 @@ jobs:
             rocm.tags=${{ steps.setup.outputs.image-name }}-rocm
             *.cache-to=type=registry,ref=${{ steps.setup.outputs.cache-name }}-rocm,mode=max
             *.cache-from=type=registry,ref=${{ steps.setup.outputs.cache-name }}-rocm
+      - name: Attest AMD/ROCm general build
+        uses: actions/attest@v4
+        with:
+          subject-name: ${{ steps.setup.outputs.image-repo }}
+          subject-digest: ${{ fromJSON(steps.rocm.outputs.metadata)['rocm']['containerimage.digest'] }}
+          push-to-registry: true
+          create-storage-record: false
   arm64_extra_builds:
     runs-on: ubuntu-22.04-arm
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
     name: ARM Extra Build
     needs:
       - arm64_build
@@ -542,6 +594,7 @@ jobs:
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Build and push Rockchip build
+        id: rk
         uses: docker/bake-action@v7
         with:
           source: .
@@ -551,8 +604,20 @@ jobs:
           set: |
             rk.tags=${{ steps.setup.outputs.image-name }}-rk
             *.cache-from=type=gha
+      - name: Attest Rockchip build
+        uses: actions/attest@v4
+        with:
+          subject-name: ${{ steps.setup.outputs.image-repo }}
+          subject-digest: ${{ fromJSON(steps.rk.outputs.metadata)['rk']['containerimage.digest'] }}
+          push-to-registry: true
+          create-storage-record: false
   synaptics_build:
     runs-on: ubuntu-22.04-arm
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
     name: Synaptics Build
     needs:
       - arm64_build
@@ -567,6 +632,7 @@ jobs:
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Build and push Synaptics build
+        id: synaptics
         uses: docker/bake-action@v7
         with:
           source: .
@@ -576,10 +642,22 @@ jobs:
           set: |
             synaptics.tags=${{ steps.setup.outputs.image-name }}-synaptics
             *.cache-from=type=gha
+      - name: Attest Synaptics build
+        uses: actions/attest@v4
+        with:
+          subject-name: ${{ steps.setup.outputs.image-repo }}
+          subject-digest: ${{ fromJSON(steps.synaptics.outputs.metadata)['synaptics']['containerimage.digest'] }}
+          push-to-registry: true
+          create-storage-record: false
   # The majority of users running arm64 are rpi users, so the rpi
   # build should be the primary arm64 image
   assemble_default_build:
     runs-on: ubuntu-22.04
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
     name: Assemble and push default build
     needs:
       - amd64_build
@@ -590,7 +668,7 @@ jobs:
         with:
           string: ${{ github.repository }}
       - name: Log in to the Container registry
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f
+        uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -598,8 +676,16 @@ jobs:
       - name: Create short sha
         run: echo "SHORT_SHA=${GITHUB_SHA::7}" >> $GITHUB_ENV
       - uses: int128/docker-manifest-create-action@v2
+        id: manifest
         with:
           tags: ghcr.io/${{ steps.lowercaseRepo.outputs.lowercase }}:${{ env.SHORT_SHA }}
           sources: |
             ghcr.io/${{ steps.lowercaseRepo.outputs.lowercase }}:${{ env.SHORT_SHA }}-amd64
             ghcr.io/${{ steps.lowercaseRepo.outputs.lowercase }}:${{ env.SHORT_SHA }}-rpi
+      - name: Attest default build
+        uses: actions/attest@v4
+        with:
+          subject-name: ghcr.io/${{ steps.lowercaseRepo.outputs.lowercase }}
+          subject-digest: ${{ steps.manifest.outputs.digest }}
+          push-to-registry: true
+          create-storage-record: false

.github/workflows/pull_request.yml

@@ -124,5 +124,7 @@ jobs:
         run: devcontainer exec --workspace-folder . bash -lc "python3 -u -m mypy --config-file frigate/mypy.ini frigate"
       - name: Check API spec is up to date
         run: devcontainer exec --workspace-folder . bash -lc "python3 generate_api_auth_spec.py --check"
+      - name: Check analytics schema is up to date
+        run: devcontainer exec --workspace-folder . bash -lc "python3 generate_analytics_schema.py --check"
       - name: Run unit tests in devcontainer
-        run: devcontainer exec --workspace-folder . bash -lc "python3 -u -m unittest"
+        run: devcontainer exec --workspace-folder . bash -lc "python3 -u -m frigate.test"

.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
         with:
           string: ${{ github.repository }}
       - name: Log in to the Container registry
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f
+        uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550
         with:
           registry: ghcr.io
           username: ${{ github.actor }}

AGENTS.md

@@ -36,7 +36,7 @@ When reviewing code, do NOT comment on:
 - **Formatting**: Ruff (configured in `pyproject.toml`)
 - **Linting**: Ruff with rules defined in project config
 - **Type Checking**: Use type hints consistently
-- **Testing**: unittest framework - use `python3 -u -m unittest` to run tests
+- **Testing**: unittest framework - use `python3 -u -m frigate.test` to run the suite in parallel groups
 - **Language**: American English for all code, comments, and documentation
 - **Punctuation**: Do not use em dashes in documentation, comments, or strings; reword with standard punctuation (commas, colons, parentheses, or separate sentences)
 
@@ -196,7 +196,7 @@ Key rules enforced:
 ### Backend Testing
 
 - **Framework**: Python unittest
-- **Run Command**: `python3 -u -m unittest`
+- **Run Command**: `python3 -u -m frigate.test` (parallel groups; plain `python3 -u -m unittest` runs serially)
 - **Location**: `frigate/test/`
 - **Coverage**: Aim for comprehensive test coverage of core functionality
 - **Pattern**: Use `TestCase` classes with descriptive test method names
@@ -219,8 +219,8 @@ Key rules enforced:
 ### Python Backend
 
 ```bash
-# Run all tests
-python3 -u -m unittest
+# Run all tests in parallel groups (-j to set the number of jobs)
+python3 -u -m frigate.test
 
 # Run specific test file
 python3 -u -m unittest frigate.test.test_ffmpeg_presets

CONTRIBUTING.md

@@ -64,7 +64,7 @@ Pull requests that appear to be unreviewed AI output will be closed without revi
 - **Python** — use modern language features (type hints, pattern matching, f-strings, dataclasses)
 - **Formatting**: Ruff (configured in `pyproject.toml`)
 - **Linting**: Ruff
-- **Testing**: `python3 -u -m unittest`
+- **Testing**: `python3 -u -m frigate.test` (runs the suite in parallel groups)
 - **Logging**: Use module-level `logger = logging.getLogger(__name__)` with lazy formatting
 - **Async**: All external I/O must be async. No blocking calls in async functions.
 - **Error handling**: Use specific exception types. Keep try blocks minimal.
@@ -82,7 +82,7 @@ Pull requests that appear to be unreviewed AI output will be closed without revi
 
 ```bash
 # Python
-python3 -u -m unittest                              # Run all tests
+python3 -u -m frigate.test                           # Run all tests in parallel groups
 python3 -u -m unittest frigate.test.test_ffmpeg_presets  # Run specific test
 ruff format frigate                                  # Format
 ruff check frigate                                   # Lint

Makefile

@@ -54,7 +54,7 @@ run: local
 
 run_tests: local
 	docker run --rm --workdir=/opt/frigate --entrypoint= frigate:latest \
-		python3 -u -m unittest
+		python3 -u -m frigate.test
 	docker run --rm --workdir=/opt/frigate --entrypoint= frigate:latest \
 		python3 -u -m mypy --config-file frigate/mypy.ini frigate
 

docker/main/Dockerfile

@@ -383,6 +383,7 @@ FROM deps AS frigate
 
 WORKDIR /opt/frigate/
 COPY --from=rootfs / /
+ENV FRIGATE_IMAGE_VARIANT=standard
 
 # Pre-compile bytecode so a read-only rootfs doesn't force re-parsing the
 # source tree on every boot (pip-installed packages are already compiled)

docker/main/build_intel_media_driver.sh

@@ -46,3 +46,4 @@ make -C /tmp/media-driver/build -j"$(nproc)"
 
 # Install driver to rootfs for COPY --from
 make -C /tmp/media-driver/build install DESTDIR=/rootfs
+strip --strip-unneeded /rootfs/usr/lib/x86_64-linux-gnu/dri/iHD_drv_video.so

docker/main/build_nginx.sh

@@ -4,7 +4,6 @@ set -euxo pipefail
 
 NGINX_VERSION="1.27.4"
 VOD_MODULE_VERSION="v1.9.1"
-SECURE_TOKEN_MODULE_VERSION="1.5"
 SET_MISC_MODULE_VERSION="v0.33"
 NGX_DEVEL_KIT_VERSION="v0.3.3"
 
@@ -52,11 +51,6 @@ patch -d /tmp/nginx-vod-module/ -p1 << 'EOF'
 EOF
 
 
-mkdir /tmp/nginx-secure-token-module
-wget https://github.com/kaltura/nginx-secure-token-module/archive/refs/tags/${SECURE_TOKEN_MODULE_VERSION}.tar.gz
-tar -zxf ${SECURE_TOKEN_MODULE_VERSION}.tar.gz -C /tmp/nginx-secure-token-module --strip-components=1
-rm ${SECURE_TOKEN_MODULE_VERSION}.tar.gz
-
 mkdir /tmp/ngx_devel_kit
 wget https://github.com/vision5/ngx_devel_kit/archive/refs/tags/${NGX_DEVEL_KIT_VERSION}.tar.gz
 tar -zxf ${NGX_DEVEL_KIT_VERSION}.tar.gz -C /tmp/ngx_devel_kit --strip-components=1
@@ -80,7 +74,6 @@ cd /tmp/nginx
     --add-module=../ngx_devel_kit \
     --add-module=../nginx-set-misc-module \
     --add-module=../nginx-vod-module \
-    --add-module=../nginx-secure-token-module \
     --with-cc-opt="-O3 -Wno-error=implicit-fallthrough"
 
 make CC="ccache gcc" -j$(nproc) && make install

docker/main/requirements-dev.txt

@@ -1,4 +1,4 @@
-ruff == 0.17.1
+ruff == 0.17.4
 
 # types
 types-peewee == 4.0.*

docker/main/requirements-wheels.txt

@@ -2,31 +2,31 @@ aiofiles == 25.1.*
 click == 8.5.*
 # FastAPI
 aiohttp == 3.14.*
-starlette == 1.9.*
+starlette == 1.10.*
 starlette-context == 0.5.*
-fastapi[standard-no-fastapi-cloud-cli] == 0.159.*
+fastapi[standard-no-fastapi-cloud-cli] == 0.162.*
 uvicorn == 0.54.*
 slowapi == 0.1.*
-joserfc == 1.7.*
+joserfc == 1.8.*
 cryptography == 50.0.*
 pathvalidate == 3.3.*
 markupsafe == 3.0.*
-python-multipart == 0.0.32
+python-multipart == 0.0.33
 # Classification Model Training
 tensorflow == 2.19.* ; platform_machine == 'aarch64'
 tensorflow-cpu == 2.21.* ; platform_machine == 'x86_64'
 # General
-mypy == 2.4.0
+mypy == 2.4.1
 onvif-zeep-async == 4.3.*
-paho-mqtt == 2.1.*
+paho-mqtt == 2.2.*
 pandas == 3.0.*
 peewee == 4.5.*
 peewee_migrate == 2.3.*
 psutil == 7.2.*
 pydantic == 2.14.*
 git+https://github.com/fbcotter/py3nvml#egg=py3nvml
-tzdata == 2026.5
-pyzmq == 27.2.*
+tzdata == 2026.6
+pyzmq == 27.3.*
 ruamel.yaml == 0.19.*
 tzlocal == 5.4.5
 requests == 2.34.*
@@ -45,11 +45,11 @@ scipy == 1.17.*
 openvino == 2026.4.*
 onnxruntime == 1.31.*
 # Embeddings
-transformers == 5.20.*
+transformers == 5.22.*
 # Generative AI
-google-genai == 2.32.*
+google-genai == 3.0.*
 ollama == 0.6.*
-openai == 3.36.*
+openai == 3.46.*
 # push notifications
 py-vapid == 1.9.6
 pywebpush == 2.5.*
@@ -68,7 +68,7 @@ prometheus-client == 0.26.*
 tflite_runtime @ https://github.com/frigate-nvr/TFlite-builds/releases/download/v2.17.1/tflite_runtime-2.17.1-cp311-cp311-linux_x86_64.whl; platform_machine == 'x86_64'
 tflite_runtime @ https://github.com/feranick/TFlite-builds/releases/download/v2.17.1/tflite_runtime-2.17.1-cp311-cp311-linux_aarch64.whl; platform_machine == 'aarch64'
 # audio transcription
-sherpa-onnx==1.13.*
+sherpa-onnx==2.0.*
 faster-whisper==1.2.*
 librosa==0.11.*
 soundfile==0.14.*

docker/main/rootfs/etc/s6-overlay/s6-rc.d/frigate/run

@@ -14,11 +14,17 @@ fi
 # Tell S6-Overlay not to restart this service
 s6-svc -O .
 
-# Runs as root with root's HOME and LD_LIBRARY_PATH; -I skips user site-packages
+# The helper runs as root (-I skips user site-packages). The probe runs as the
+# service user when the service drops privileges; a root probe relies on
+# resolve_ffmpeg_path refusing runtime-user-writable paths.
 function set_libva_version() {
     local ffmpeg_path
-    ffmpeg_path=$(python3 -I /usr/local/ffmpeg/get_ffmpeg_path.py)
-    LIBAVFORMAT_VERSION_MAJOR=$("$ffmpeg_path" -version | grep -Po "libavformat\W+\K\d+")
+    local probe_as=()
+    if [[ "$(id -u)" -eq 0 && "$runs_as_root" -eq 0 ]]; then
+        probe_as=(s6-setuidgid frigate)
+    fi
+    ffmpeg_path=$(python3 -I /usr/local/ffmpeg/get_ffmpeg_path.py frigate)
+    LIBAVFORMAT_VERSION_MAJOR=$("${probe_as[@]}" "$ffmpeg_path" -version | grep -Po "libavformat\W+\K\d+")
     export LIBAVFORMAT_VERSION_MAJOR
 }
 

docker/main/rootfs/etc/s6-overlay/s6-rc.d/go2rtc/run

@@ -57,10 +57,19 @@ function get_ip_and_port_from_supervisor() {
     export FRIGATE_GO2RTC_WEBRTC_CANDIDATE_INTERNAL="${ip_address}:${webrtc_port}"
 }
 
+# The probe runs as the service user when the service drops privileges; a root
+# probe relies on resolve_ffmpeg_path refusing runtime-user-writable paths
 function set_libva_version() {
     local ffmpeg_path
-    ffmpeg_path=$(python3 -I /usr/local/ffmpeg/get_ffmpeg_path.py)
-    LIBAVFORMAT_VERSION_MAJOR=$("$ffmpeg_path" -version | grep -Po "libavformat\W+\K\d+")
+    local probe_as=()
+    if [[ "$(id -u)" -eq 0 && "$runs_as_root" -eq 0 ]]; then
+        probe_as=(s6-setuidgid go2rtc)
+    fi
+    ffmpeg_path=$(python3 -I /usr/local/ffmpeg/get_ffmpeg_path.py go2rtc)
+    if ! LIBAVFORMAT_VERSION_MAJOR=$("${probe_as[@]}" "$ffmpeg_path" -version | grep -Po "libavformat\W+\K\d+"); then
+        echo "[WARN] Could not read the libavformat version from ${ffmpeg_path} as the go2rtc user; using the bundled build's version"
+        LIBAVFORMAT_VERSION_MAJOR=$("${probe_as[@]}" "/usr/lib/ffmpeg/${DEFAULT_FFMPEG_VERSION}/bin/ffmpeg" -version | grep -Po "libavformat\W+\K\d+")
+    fi
     export LIBAVFORMAT_VERSION_MAJOR
 }
 

docker/main/rootfs/etc/s6-overlay/s6-rc.d/nginx/run

@@ -80,6 +80,11 @@ cp -r /usr/local/nginx/conf/. /tmp/nginx/conf/
 
 set_worker_processes
 
+# A non-root master ignores `user` and warns on every start
+if [[ "$runs_as_root" -eq 0 ]]; then
+    sed -i '/^user root;$/d' /tmp/nginx/conf/nginx.conf
+fi
+
 # TLS certs: user-mounted certs at /etc/letsencrypt/live/frigate (documented
 # contract) always win; otherwise fall back to a self-signed cert persisted in
 # /config/tls, which stays writable under a read-only root filesystem.

docker/main/rootfs/usr/local/bin/fix-ownership

@@ -105,6 +105,8 @@ if [[ -n "$sentinel" ]]; then
     mismatch_expr+=(-a ! -path "$sentinel")
 fi
 
+exec 3>&1
+
 for path in "$@"; do
     # An absent root is an incomplete sweep, not a finished one: /media/frigate
     # is not in the image, so a boot before the volume is mounted would
@@ -121,7 +123,18 @@ for path in "$@"; do
     # stale mount. Tolerate it rather than aborting under errexit, but never
     # read a failed scan as "nothing to do": that would record the sweep as
     # complete without having looked.
-    if ! count=$(find "$path" -name lost+found -prune -o "${mismatch_expr[@]}" -printf '.' 2>/dev/null | wc -c); then
+    # The walk prints nothing until it ends, so report every 30s through fd 3
+    # (stdout) while the count itself comes back through the substitution.
+    if ! count=$(find "$path" -name lost+found -prune -o "(" "${mismatch_expr[@]}" ")" -printf 'm\n' -o -printf '.\n' 2>/dev/null \
+        | awk -v path="$path" '
+            BEGIN { next_report = systime() + 30 }
+            $0 == "m" { mismatched++ }
+            systime() >= next_report {
+                printf "[INFO] fix-ownership: still scanning %s, %d entries checked, %d need changes\n", path, NR, mismatched > "/dev/fd/3"
+                fflush("/dev/fd/3")
+                next_report = systime() + 30
+            }
+            END { print mismatched + 0 }'); then
         swept_clean=0
         echo "[WARN] fix-ownership: could not scan ${path}; will retry on next boot"
         continue

docker/main/rootfs/usr/local/ffmpeg/get_ffmpeg_path.py

@@ -25,4 +25,5 @@ except FileNotFoundError:
     config: dict[str, Any] = {}
 
 path = config.get("ffmpeg", {}).get("path", "default")
-print(resolve_ffmpeg_path(path, "ffmpeg"))
+service = sys.argv[1] if len(sys.argv) > 1 else "frigate"
+print(resolve_ffmpeg_path(path, "ffmpeg", service))

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

@@ -8,15 +8,17 @@ from typing import Any
 from ruamel.yaml import YAML
 
 sys.path.insert(0, "/opt/frigate")
-from frigate.const import (
-    BIRDSEYE_PIPE,
-    LIBAVFORMAT_VERSION_MAJOR,
-)
+from frigate.const import BIRDSEYE_PIPE
 from frigate.ffmpeg_presets import parse_preset_hardware_acceleration_encode
-from frigate.util.config import find_config_file, resolve_ffmpeg_path
+from frigate.util.config import (
+    find_config_file,
+    is_valid_ffmpeg_path,
+    resolve_ffmpeg_path,
+)
 from frigate.util.env import apply_config_env_vars, substitute_frigate_vars
 from frigate.util.live_streams import raw_transcode_streams
 from frigate.util.services import (
+    apply_go2rtc_ffmpeg_config,
     is_go2rtc_arbitrary_exec_allowed,
     is_restricted_go2rtc_source,
 )
@@ -38,16 +40,10 @@ try:
 except FileNotFoundError:
     config: dict[str, Any] = {}
 
-# No validator runs here, so install environment_vars ourselves. FRIGATE_
-# names only: anything else lands in os.environ, where the exec gate reads
-# GO2RTC_ALLOW_ARBITRARY_EXEC.
+# No validator runs here, so install environment_vars ourselves.
 config_env_vars = config.get("environment_vars")
 apply_config_env_vars(
-    {
-        key: value
-        for key, value in config_env_vars.items()
-        if str(key).startswith("FRIGATE_")
-    }
+    {str(key): value for key, value in config_env_vars.items()}
     if isinstance(config_env_vars, dict)
     else {}
 )
@@ -97,20 +93,17 @@ if go2rtc_config.get("rtsp", {}).get("password") is not None:
 
 # ensure ffmpeg path is set correctly
 path = config.get("ffmpeg", {}).get("path", "default")
-ffmpeg_path = resolve_ffmpeg_path(path, "ffmpeg")
+if not is_valid_ffmpeg_path(path):
+    print(
+        "[ERROR] ffmpeg path contains spaces, quotes or shell characters, using the default ffmpeg instead."
+    )
+ffmpeg_path = resolve_ffmpeg_path(path, "ffmpeg", "go2rtc")
 
-if go2rtc_config.get("ffmpeg") is None:
-    go2rtc_config["ffmpeg"] = {"bin": ffmpeg_path}
-elif go2rtc_config["ffmpeg"].get("bin") is None:
-    go2rtc_config["ffmpeg"]["bin"] = ffmpeg_path
-
-# need to replace ffmpeg command when using ffmpeg4
-if LIBAVFORMAT_VERSION_MAJOR < 59:
-    rtsp_args = "-fflags nobuffer -flags low_delay -stimeout 10000000 -user_agent go2rtc/ffmpeg -rtsp_transport tcp -i {input}"
-    if go2rtc_config.get("ffmpeg") is None:
-        go2rtc_config["ffmpeg"] = {"rtsp": rtsp_args}
-    elif go2rtc_config["ffmpeg"].get("rtsp") is None:
-        go2rtc_config["ffmpeg"]["rtsp"] = rtsp_args
+for key in apply_go2rtc_ffmpeg_config(go2rtc_config, ffmpeg_path):
+    print(
+        f"[ERROR] go2rtc option '{key}' was ignored because it is disabled by default for security. "
+        f"Set GO2RTC_ALLOW_ARBITRARY_EXEC=true to enable arbitrary exec."
+    )
 
 
 for name in list(go2rtc_config.get("streams", {})):
@@ -121,7 +114,7 @@ for name in list(go2rtc_config.get("streams", {})):
             formatted_stream = substitute_frigate_vars(stream)
             if is_restricted_go2rtc_source(formatted_stream):
                 print(
-                    f"[ERROR] Stream '{name}' uses a restricted source (echo/expr/exec) which is disabled by default for security. "
+                    f"[ERROR] Stream '{name}' uses a restricted source (echo/expr/exec or ${{VAR}}) which is disabled by default for security. "
                     f"Set GO2RTC_ALLOW_ARBITRARY_EXEC=true to enable arbitrary exec sources."
                 )
                 del go2rtc_config["streams"][name]
@@ -140,7 +133,7 @@ for name in list(go2rtc_config.get("streams", {})):
                 formatted_stream = substitute_frigate_vars(stream_item)
                 if is_restricted_go2rtc_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. "
+                        f"[ERROR] Stream '{name}' item {i + 1} uses a restricted source (echo/expr/exec or ${{VAR}}) which is disabled by default for security. "
                         f"Set GO2RTC_ALLOW_ARBITRARY_EXEC=true to enable arbitrary exec sources."
                     )
                     continue
@@ -156,7 +149,7 @@ for name in list(go2rtc_config.get("streams", {})):
             go2rtc_config["streams"][name] = filtered_streams
         else:
             print(
-                f"[ERROR] Stream '{name}' was removed because all sources were restricted (echo/expr/exec). "
+                f"[ERROR] Stream '{name}' was removed because all sources were restricted (echo/expr/exec or ${{VAR}}). "
                 f"Set GO2RTC_ALLOW_ARBITRARY_EXEC=true to enable arbitrary exec sources."
             )
             del go2rtc_config["streams"][name]

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

@@ -3,6 +3,8 @@ location /auth {
     ## Essential Proxy Configuration
     internal;
     proxy_pass http://frigate_api/auth;
+    # $go2rtc_stream_proxy is only set by the go2rtc stream locations
+    uninitialized_variable_warn off;
 
     ## Headers
 

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

@@ -2,7 +2,7 @@
 # file, all other path directives follow --prefix and must stay absolute.
 
 daemon off;
-# ignored by a non-root master; keeps workers root under FRIGATE_RUN_AS_ROOT
+# keeps workers root under FRIGATE_RUN_AS_ROOT; the run script strips it otherwise
 user root;
 worker_processes auto;
 
@@ -143,8 +143,14 @@ http {
             # version 6 (RFC 8216 section 7); the module default is 4
             vod_hls_version 6;
 
-            secure_token $args;
-            secure_token_types application/vnd.apple.mpegurl;
+            # Pass the playlist's query args (e.g. Home Assistant's authSig) on
+            # to every URL in it. These match the only URL endings vod writes
+            # with fmp4 and no subtitles.
+            sub_filter_types application/vnd.apple.mpegurl;
+            sub_filter_once off;
+            sub_filter '.m3u8' '.m3u8$is_args$args';
+            sub_filter '.m4s' '.m4s$is_args$args';
+            sub_filter '.mp4"' '.mp4$is_args$args"';
 
             include security_headers.conf;
             add_header Cache-Control "no-store";

docker/rockchip/Dockerfile

@@ -25,6 +25,7 @@ RUN --mount=type=bind,from=rk-wheels,source=/rk-wheels,target=/deps/rk-wheels \
 
 WORKDIR /opt/frigate/
 COPY --from=rootfs / /
+ENV FRIGATE_IMAGE_VARIANT=rk
 COPY docker/rockchip/COCO /COCO
 COPY docker/rockchip/conv2rknn.py /opt/conv2rknn.py
 

docker/rocm/Dockerfile

@@ -37,6 +37,7 @@ RUN --mount=type=bind,source=docker/rocm/prune_rocm.sh,target=/deps/prune_rocm.s
 
 WORKDIR /opt/frigate
 COPY --from=rootfs / /
+ENV FRIGATE_IMAGE_VARIANT=rocm
 
 #######################################################################
 FROM deps-prelim AS rocm-prelim-hsa-override0

docker/rpi/Dockerfile

@@ -15,3 +15,4 @@ ENV INCLUDED_FFMPEG_VERSIONS="${DEFAULT_FFMPEG_VERSION}:${INCLUDED_FFMPEG_VERSIO
 
 WORKDIR /opt/frigate/
 COPY --from=rootfs / /
+ENV FRIGATE_IMAGE_VARIANT=rpi

docker/synaptics/Dockerfile

@@ -22,6 +22,7 @@ pip3 install --no-deps -U /deps/synap-wheels/*.whl
 
 WORKDIR /opt/frigate/
 COPY --from=rootfs / /
+ENV FRIGATE_IMAGE_VARIANT=synaptics
 
 COPY --from=synap1680-wheels /rootfs/usr/local/lib/*.so /usr/lib
 

docker/tensorrt/Dockerfile.amd64

@@ -25,6 +25,7 @@ RUN --mount=type=bind,from=trt-wheels,source=/trt-wheels,target=/deps/trt-wheels
     && pip3 install -U /deps/trt-wheels/*.whl
 
 COPY --from=rootfs / /
+ENV FRIGATE_IMAGE_VARIANT=tensorrt
 COPY docker/tensorrt/detector/rootfs/etc/ld.so.conf.d /etc/ld.so.conf.d
 RUN ldconfig
 

docker/tensorrt/Dockerfile.arm64

@@ -151,6 +151,7 @@ RUN --mount=type=bind,from=trt-wheels,source=/trt-wheels,target=/deps/trt-wheels
 
 WORKDIR /opt/frigate/
 COPY --from=rootfs / /
+ENV FRIGATE_IMAGE_VARIANT=tensorrt-jp6
 
 # Fixes "Error importing detector runtime: /usr/lib/aarch64-linux-gnu/libstdc++.so.6: cannot allocate memory in static TLS block"
 ENV LD_PRELOAD /usr/lib/aarch64-linux-gnu/libstdc++.so.6

docker/tensorrt/requirements-models-arm64.txt

@@ -1,2 +1,2 @@
 onnx == 1.14.0; platform_machine == 'aarch64'
-protobuf == 3.20.3; platform_machine == 'aarch64'
+protobuf == 5.29.6; platform_machine == 'aarch64'

docs/docs/configuration/advanced/analytics.md

@@ -0,0 +1,41 @@
+---
+id: analytics
+title: Anonymous Analytics
+---
+
+import AnalyticsFields from "@site/src/components/AnalyticsFields";
+import NavPath from "@site/src/components/NavPath";
+
+Frigate can send one anonymous usage report a day. The reports show the maintainers which hardware to support, which features people use, and how releases perform. Sharing is off until you turn it on.
+
+## Turning it on
+
+Enable **Share anonymous analytics** at <NavPath path="Settings > System > Telemetry" />, or set it in your config:
+
+```yaml
+telemetry:
+  analytics: true
+```
+
+The same page has a **Preview the report** button that shows exactly what the next report contains.
+
+## How it's sent
+
+- Once a day, as a JSON POST to `https://analytics.frigate.video/report`
+- The server looks up your country and region from your IP address and never stores the address
+- Raw reports are kept for 60 days; only aggregate totals are published
+- A random install ID, stored in `/config/.analytics.json`, keeps your install from being counted twice. Turning sharing off deletes it
+
+## What's never sent
+
+- Camera, zone, group, profile, or user names
+- Object labels, face names, or license plate text
+- IP addresses, hostnames, URLs, or stream paths
+- Credentials or API keys
+- Events, recordings, or anything from them
+
+## Every field
+
+Fields marked public appear in the published totals. The machine-readable schema is [frigate-analytics-schema.json](pathname:///frigate-analytics-schema.json).
+
+<AnalyticsFields />

docs/docs/configuration/advanced/reference.md

@@ -240,7 +240,7 @@ logger:
 
 # Optional: set environment variables
 environment_vars:
-  EXAMPLE_VAR: value
+  LIBVA_DRIVER_NAME: i965
 
 # Optional: birdseye configuration
 # NOTE: Can (enabled, mode) be overridden at the camera level
@@ -578,6 +578,10 @@ notifications:
   email: "admin@example.com"
   # Optional: Cooldown time for notifications in seconds (default: shown below)
   cooldown: 0
+  # Optional: Delivery of notifications sent while an alert is active (default: shown below)
+  # Options are immediate (deliver right away or drop) and reliable (retry for up to 30 seconds)
+  # NOTE: reliable can deliver late notifications that still link to the live view
+  ttl: immediate
 
 # Optional: Record configuration
 # NOTE: Can be overridden at the camera level
@@ -1214,6 +1218,9 @@ ui:
 
 # Optional: Telemetry configuration
 telemetry:
+  # Optional: Share one anonymous usage report a day (default: shown below)
+  # NOTE: See https://docs.frigate.video/configuration/advanced/analytics for what is sent
+  analytics: False
   # Optional: Enabled network interfaces for bandwidth stats monitoring (default: empty list, let nethogs search all)
   network_interfaces:
     - eth

docs/docs/configuration/advanced/system.md

@@ -65,7 +65,16 @@ go2rtc:
 
 This section sets environment variables in the Frigate process for those unable to modify the environment of the container, like within Home Assistant OS. It's meant for process settings such as `LIBVA_DRIVER_NAME` or the TensorFlow thread counts below. Docker users should set environment variables in their `docker run` command (`-e LIBVA_DRIVER_NAME=i965`) or `docker-compose.yml` file (`environment:` section) instead. Values set here are stored in plain text in your config file, so credentials belong in `secrets.yaml`, Docker environment variables, or Docker secrets instead.
 
-Names prefixed with `FRIGATE_` set here also take part in `{FRIGATE_VARIABLE_NAME}` substitution (see [below](#substitution-sources-and-precedence)), but `secrets.yaml` is the better home for them.
+Besides `FRIGATE_` names, only these are accepted, and a variable already set in the container environment keeps its container value:
+
+- `LIBVA_DRIVER_NAME` and `HSA_OVERRIDE_GFX_VERSION`
+- `TF_INTRA_OP_PARALLELISM_THREADS`, `TF_INTER_OP_PARALLELISM_THREADS`, `TF_DATASET_THREAD_POOL_SIZE`, and `SHM_MAX_FRAMES`
+- `USE_FP16`, `HF_HUB_OFFLINE`, and `TRANSFORMERS_OFFLINE`
+- `HF_ENDPOINT`, `GITHUB_ENDPOINT`, `GITHUB_RAW_ENDPOINT`, and `TF_KERAS_MOBILENET_V2_WEIGHTS_URL` (an `http://` or `https://` URL)
+
+Any other name is ignored with a warning and must be set in the container environment.
+
+Names prefixed with `FRIGATE_` set here take part in `{FRIGATE_VARIABLE_NAME}` substitution (see [below](#substitution-sources-and-precedence)), but `secrets.yaml` is the better home for them. Of these, only `FRIGATE_JWT_SECRET` is also set in the process environment.
 
 <ConfigTabs>
 <TabItem value="ui">
@@ -398,9 +407,9 @@ To do this:
 2. Update the `ffmpeg.path` in your Frigate config to `/config/custom-ffmpeg`.
 3. Restart Frigate and the custom version will be used if the steps above were done correctly.
 
-Both binaries have to be executable by Frigate's unprivileged runtime user, so `chmod 755` them after extracting. The startup ownership sweep runs only once, so anything you add to `/config` later keeps whatever ownership and mode you gave it.
+Both binaries have to be executable by Frigate's unprivileged runtime user, so `chmod 755` them after extracting. go2rtc runs as its own user, so the build must be world-executable for go2rtc to use it (`ffmpeg:` sources, the birdseye restream and transcoded live streams). The startup ownership sweep runs only once, so anything you add to `/config` later keeps whatever ownership and mode you gave it.
 
-There is one exception, and it only affects [`FRIGATE_ROOT_SERVICES`](/configuration/non_root#keeping-individual-services-root) listing `frigate`. That mode runs Frigate as root while still handing `/config` to the unprivileged runtime user, so anything running as that user could swap the binary and gain root. A build inside any of Frigate's writable volumes (`/config`, `/media/frigate`, the cache and shm dirs) is ignored there and the bundled one is used, with a warning in the log. Keep the build somewhere root-owned (any absolute `ffmpeg.path` works, so a read-only bind mount such as `/opt/custom-ffmpeg` is enough) if you need both. The default mode and `FRIGATE_RUN_AS_ROOT=true` are unaffected and behave exactly as they always have.
+There is one exception, and it only affects [`FRIGATE_ROOT_SERVICES`](/configuration/non_root#keeping-individual-services-root) listing `frigate` or `go2rtc`. That mode runs the listed service as root while still handing `/config` to the unprivileged runtime user, so anything running as that user could swap the binary and gain root. A build inside any of Frigate's writable volumes (`/config`, `/media/frigate`, the cache and shm dirs) is ignored by the root service, which uses the bundled one and logs a warning. A service that is not listed keeps using the custom build. Keep the build somewhere root-owned (any absolute `ffmpeg.path` works, so a read-only bind mount such as `/opt/custom-ffmpeg` is enough) if you need both. The default mode and `FRIGATE_RUN_AS_ROOT=true` are unaffected and behave exactly as they always have.
 
 ### Custom go2rtc version
 

docs/docs/configuration/autotracking.md

@@ -28,7 +28,7 @@ Many cheaper or older PTZs may not support this standard. Frigate will report an
 
 The FeatureList on the [ONVIF Conformant Products Database](https://www.onvif.org/conformant-products/) can provide a starting point to determine a camera's compatibility with Frigate's autotracking. Look to see if a camera lists `PTZRelative`, `PTZRelativePanTilt` and/or `PTZRelativeZoom`. These features are required for autotracking, but some cameras still fail to respond even if they claim support.
 
-A growing list of cameras and brands that have been reported by users to work with Frigate's autotracking can be found [here](cameras.md).
+The [CCTV Camera Database](https://www.cctv-database.com/) is useful for researching a specific model.
 
 ## Configuration
 
@@ -192,7 +192,7 @@ In security and surveillance, it's common to use "spotter" cameras in combinatio
 
 <FaqItem id="which-ptz-camera-should-i-use-for-autotracking" question="Which PTZ camera should I use for autotracking?">
 
-See the community-maintained list of [ONVIF PTZ camera recommendations](cameras.md#onvif-ptz-camera-recommendations) for cameras and brands reported to work (and not work) with autotracking. This is not an exhaustive list that is frequently updated, so other cameras not listed may also work well. Frigate's autotracking was developed with a Dahua SD1A404XB-GNR (now sold as the EmpireTech PTZ1A4M-4X-S2), and Dahua / EmpireTech PTZs are the most consistently reported as working well.
+See [ONVIF PTZ camera recommendations](cameras.md#onvif-ptz-camera-recommendations) for how to check a camera's autotracking support before buying. Frigate's autotracking was developed with a Dahua SD1A404XB-GNR (now sold as the EmpireTech PTZ1A4M-4X-S2), and Dahua / EmpireTech PTZs are the most consistently reported as working well.
 
 When comparing models:
 
@@ -209,7 +209,7 @@ No. Reolink cameras (including the TrackMix series) lack the ONVIF FOV RelativeM
 
 <FaqItem id="im-seeing-an-error-in-the-logs-that-my-camera-is-still-in-onvif-moving-status-what-does-this-mean" question={"I'm seeing an error in the logs that my camera \"is still in ONVIF 'MOVING' status.\" What does this mean?"}>
 
-There are two possible known reasons for this (and perhaps others yet unknown): a slow PTZ motor or buggy camera firmware. Frigate uses an ONVIF parameter provided by the camera, `MoveStatus`, to determine when the PTZ's motor is moving or idle. According to some users, Hikvision PTZs (even with the latest firmware), are not updating this value after PTZ movement. Unfortunately there is no workaround to this bug in Hikvision firmware, so autotracking will not function correctly and should be disabled in your config. This may also be the case with other non-Hikvision cameras utilizing Hikvision firmware, such as some Annke models. In rare cases the vendor may provide fixed firmware on request; for example, Annke has supplied firmware that resolves this for the CZ504 (see the [camera recommendations list](cameras.md#onvif-ptz-camera-recommendations)).
+There are two possible known reasons for this (and perhaps others yet unknown): a slow PTZ motor or buggy camera firmware. Frigate uses an ONVIF parameter provided by the camera, `MoveStatus`, to determine when the PTZ's motor is moving or idle. According to some users, Hikvision PTZs (even with the latest firmware), are not updating this value after PTZ movement. Unfortunately there is no workaround to this bug in Hikvision firmware, so autotracking will not function correctly and should be disabled in your config. This may also be the case with other non-Hikvision cameras utilizing Hikvision firmware, such as some Annke models.
 
 </FaqItem>
 

docs/docs/configuration/cameras.md

@@ -225,36 +225,9 @@ An ONVIF-capable camera that supports relative movement within the field of view
 
 ## ONVIF PTZ camera recommendations
 
-This list of working and non-working PTZ cameras is based on user feedback. If you'd like to report specific quirks or issues with a manufacturer or camera that would be helpful for other users, open a pull request to add to this list.
+Before buying a PTZ camera, check its ONVIF support. The [ONVIF Conformant Products Database](https://www.onvif.org/conformant-products/) is the most reliable source. Look at a camera's FeatureList for `PTZRelative`, `PTZRelativePanTilt` and/or `PTZRelativeZoom`. Autotracking requires these features. If they are missing, autotracking will not work, though basic PTZ in the WebUI might. Some cameras still fail to respond even when they claim support. Avoid cameras with no database entry.
 
-The FeatureList on the [ONVIF Conformant Products Database](https://www.onvif.org/conformant-products/) can provide a starting point to determine a camera's compatibility with Frigate's autotracking. Look to see if a camera lists `PTZRelative`, `PTZRelativePanTilt` and/or `PTZRelativeZoom`. These features are required for autotracking, but some cameras still fail to respond even if they claim support. If they are missing, autotracking will not work (though basic PTZ in the WebUI might). Avoid cameras with no database entry unless they are confirmed as working below.
-
-| Brand or specific camera     | PTZ Controls | Autotracking | Notes                                                                                                                                                                                                                                                             |
-| ---------------------------- | :----------: | :----------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Amcrest                      |      ✅      |      ✅      | ⛔️ Generally, Amcrest should work, but some older models (like the common IP2M-841) don't support autotracking                                                                                                                                                    |
-| Amcrest ASH21                |      ✅      |      ❌      | ONVIF service port: 80                                                                                                                                                                                                                                            |
-| Amcrest IP4M-S2112EW-AI      |      ✅      |      ❌      | FOV relative movement not supported.                                                                                                                                                                                                                              |
-| Amcrest IP5M-1190EW          |      ✅      |      ❌      | ONVIF Port: 80. FOV relative movement not supported.                                                                                                                                                                                                              |
-| Annke CZ504                  |      ✅      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Axis Q-6155E                 |      ✅      |      ❌      | ONVIF service port: 80; Camera does not support MoveStatus.                                                                                                                                                                                                       |
-| Ctronics PTZ                 |      ✅      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Dahua                        |      ✅      |      ✅      | Some low-end Dahuas (lite series, picoo series (commonly), among others) have been reported to not support autotracking. These models usually don't have a four digit model number with chassis prefix and options postfix (e.g. DH-P5AE-PV vs DH-SD49825GB-HNR). |
-| Dahua DH-SD2A500HB           |      ✅      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Dahua DH-SD49825GB-HNR       |      ✅      |      ✅      |                                                                                                                                                                                                                                                                   |
-| Dahua DH-P5AE-PV             |      ❌      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Foscam                       |      ✅      |      ❌      | In general support PTZ, but not relative move. There are no official ONVIF certifications and tests available on the ONVIF Conformant Products Database                                                                                                           |
-| Foscam R5                    |      ✅      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Foscam SD4                   |      ✅      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Hanwha XNP-6550RH            |      ✅      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Hikvision                    |      ✅      |      ❌      | Incomplete ONVIF support (MoveStatus won't update even on latest firmware) - reported with HWP-N4215IH-DE and DS-2DE3304W-DE, but likely others                                                                                                                   |
-| Hikvision DS-2DE3A404IWG-E/W |      ✅      |      ✅      |                                                                                                                                                                                                                                                                   |
-| Reolink                      |      ✅      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Speco O8P32X                 |      ✅      |      ❌      |                                                                                                                                                                                                                                                                   |
-| Sunba 405-D20X               |      ✅      |      ❌      | Incomplete ONVIF support reported on original, and 4k models. All models are suspected incompatible.                                                                                                                                                              |
-| Tapo                         |      ✅      |      ❌      | Many models supported, ONVIF Service Port: 2020                                                                                                                                                                                                                   |
-| Uniview IPC672LR-AX4DUPK     |      ✅      |      ❌      | Firmware says FOV relative movement is supported, but camera doesn't actually move when sending ONVIF commands                                                                                                                                                    |
-| Uniview IPC6612SR-X33-VG     |      ✅      |      ✅      | Leave `calibrate_on_startup` as `False`. A user has reported that zooming with `absolute` is working.                                                                                                                                                             |
-| Vikylin PTZ-2804X-I2         |      ❌      |      ❌      | Incomplete ONVIF support                                                                                                                                                                                                                                          |
+The [CCTV Camera Database](https://www.cctv-database.com/) is an open database of IP camera specifications and is useful for researching a specific model.
 
 ## Setting up camera groups
 

docs/docs/configuration/genai/config.md

@@ -75,11 +75,12 @@ Running Generative AI models on CPU is not recommended, as high inference times
 
 You must use a vision-capable model with Frigate. The following models are recommended for local deployment of the `descriptions` and `chat` roles:
 
-| Model               | Review [frame mode](/configuration/genai/genai_review#frame-mode) | Notes                                                                                                                                                                |
-| ------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `qwen3-vl`          | `frames`                                                              | Strong visual and situational understanding, enhanced ability to identify smaller objects and interactions with object. Follows a sequence of frames on its own.     |
-| `qwen3.6`/`qwen3.8` | `frames`                                                              | Strong situational understanding, but missing DeepStack from qwen3-vl leading to worse performance for identifying objects in people's hand and other small details. |
-| `gemma4`            | `annotated_frames`                                                    | Strong situational understanding, sometimes resorts to more vague terms like 'interacts' instead of assigning a specific action. Loses track of activity that repeats or reverses, so it benefits from annotated frames. |
+| Model               | Review [frame mode](/configuration/genai/genai_review#frame-mode) | Review [response style](/configuration/genai/genai_review#response-style) | Notes                                                                                                                                                                                                                    |
+| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `qwen3-vl`          | `frames`                                                          | `natural`                                                                 | Strong visual and situational understanding, enhanced ability to identify smaller objects and interactions with object. Follows a sequence of frames on its own.                                                         |
+| `qwen3.6`/`qwen3.8` | `frames`                                                          | `natural`                                                                 | Strong situational understanding, but missing DeepStack from qwen3-vl leading to worse performance for identifying objects in people's hand and other small details.                                                     |
+| `gemma4`            | `annotated_frames`                                                | `default`                                                                 | Strong situational understanding, sometimes resorts to more vague terms like 'interacts' instead of assigning a specific action. Loses track of activity that repeats or reverses, so it benefits from annotated frames. |
+| `lfm3-vl`           | `annotated_frames`                                                | `concise`                                                                 | Very efficient with fast inference, making it a good choice for less powerful hardware or high volumes of review items.                                                                                                  |
 
 #### Embedding models
 
@@ -95,7 +96,7 @@ The `embeddings` role needs a different kind of model. Text queries are matched
 The `transcribe` role needs a model that accepts audio input. A text-only or vision-only model cannot serve this role. The following are recommended for local deployment of the `transcribe` role:
 
 | Model       | Notes                                                                                                                                                                                                      |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `qwen3-asr` | Dedicated speech recognition model covering 30 languages, and the better choice for transcription quality. It only transcribes, so it cannot be shared with the `descriptions` or `chat` roles.            |
 | `gemma4`    | General multimodal model that accepts audio as well as images, so one served model can cover `transcribe` alongside the other roles. Transcript quality is below `qwen3-asr`, particularly on noisy audio. |
 
@@ -343,7 +344,7 @@ To start using Gemini, you must first get an API key from [Google AI Studio](htt
 1. Navigate to <NavPath path="Settings > Enrichments > Generative AI" />.
    - Set **Provider** to `gemini`
    - Set **API key** to your Gemini API key (or use an environment variable such as `{FRIGATE_GEMINI_API_KEY}`)
-   - Set **Model** to the desired model (e.g., `gemini-2.5-flash`)
+   - Set **Model** to the desired model (e.g., `gemini-3.5-flash-lite`)
 
 </TabItem>
 <TabItem value="yaml">
@@ -353,12 +354,18 @@ genai:
   my_provider:
     provider: gemini
     api_key: "{FRIGATE_GEMINI_API_KEY}"
-    model: gemini-2.5-flash
+    model: gemini-3.5-flash-lite
 ```
 
 </TabItem>
 </ConfigTabs>
 
+:::tip
+
+Gemini 3.x models charge a (roughly) flat ~1,100 tokens per image regardless of resolution, so a 180p preview frame costs the same as a 480p recording frame. Set the review [image source](/configuration/genai/genai_review#image-source) to `recordings` to send higher quality frames at no extra cost, as long as recordings are enabled for the camera.
+
+:::
+
 :::note
 
 To use a different Gemini-compatible API endpoint, set the `provider_options` with the `base_url` key to your provider's API URL. For example:

docs/docs/configuration/live.md

@@ -392,7 +392,12 @@ When your browser runs into problems playing back your camera streams, it will l
 
 - **stalled**
   - What it means: Playback has stalled because the player has fallen too far behind live (extended buffering or no data arriving).
-  - What to try: This is usually indicative of the browser struggling to decode too many high-resolution streams at once. Try selecting a lower-bandwidth stream (substream), reduce the number of live streams open, improve the network connection, or lower the camera resolution. Also check your camera's keyframe (I-frame) interval: shorter intervals make playback start and recover faster. You can also try increasing the timeout value in <NavPath path="Settings > UI" /> .
+  - What to try:
+    - This is usually indicative of the browser struggling to decode too many high-resolution streams at once.
+    - Try selecting a lower-bandwidth stream (substream), reduce the number of live streams open, improve the network connection, or lower the camera resolution.
+    - Also check your camera's keyframe (I-frame) interval: shorter intervals make playback start and recover faster.
+    - You can also try increasing the timeout value in <NavPath path="Settings > UI" /> .
+    - Also ensure your browser doesn't have JavaScript V8 optimizations disabled ("JavaScript optimisation and security" setting in Chrome-based browsers).
 
   - Possible console messages from the player code:
     - `Buffer time (10 seconds) exceeded, browser may not be playing media correctly.`

docs/docs/configuration/non_root.md

@@ -71,13 +71,14 @@ Both the script and the boot sweep report progress, so you can tell a slow sweep
 
 ```
 [INFO] fix-ownership: scanning /media/frigate for ownership mismatches; this may take a while on large filesystems
+[INFO] fix-ownership: still scanning /media/frigate, 2481000 entries checked, 2390112 need changes
 [WARN] fix-ownership: adjusting ownership of 4823941 entries under /media/frigate
 [INFO] fix-ownership: /media/frigate 5% (241197/4823941 entries)
 [INFO] fix-ownership: /media/frigate 10% (482394/4823941 entries)
 [INFO] fix-ownership: finished /media/frigate in 12m 4s
 ```
 
-The scan has no percentage because the total isn't known until it finishes. Watch the boot sweep with `docker logs -f frigate`.
+The scan has no percentage because the total isn't known until it finishes, so it reports a running count every 30 seconds instead. Watch the boot sweep with `docker logs -f frigate`.
 
 Once the volumes are aligned, start Frigate normally. A file at `/config/.permissions_version` records what was done, so later boots skip the sweep unless you change `PUID`/`PGID`.
 

docs/docs/configuration/notifications.md

@@ -43,7 +43,7 @@ Notifications will be prevented if either:
 <ConfigTabs>
 <TabItem value="ui">
 
-1. Navigate to <NavPath path="Settings > Notifications > Notifications" />.
+1. Navigate to <NavPath path="Settings > Notifications" />.
    - Set **Email** to your email address
    - Enable notifications for the desired cameras
 
@@ -108,6 +108,29 @@ Currently, only Chrome supports images in notifications. Safari and Firefox will
 
 Different platforms handle notifications differently, some settings changes may be required to get optimal notification delivery.
 
+### Notification TTL
+
+By default, Frigate sends notifications for an active alert with a `ttl` of `immediate`, so the push service either delivers them immediately or drops them. If your device is briefly unreachable (asleep, switching from Wi-Fi to cellular, or on a weak signal), those notifications are lost and you only receive the notification sent when the alert ends, which is always kept for up to an hour.
+
+Setting `ttl` to `reliable` tells the push service to keep retrying these notifications for up to 30 seconds. This makes delivery more reliable, but a notification delivered late will still say an object is detected, even if the object has already left.
+
+<ConfigTabs>
+<TabItem value="ui">
+
+1. Navigate to <NavPath path="Settings > Notifications" />.
+   - Expand **Advanced Settings** and set **Notification TTL** to **Reliable**
+
+</TabItem>
+<TabItem value="yaml">
+
+```yaml
+notifications:
+  ttl: reliable # retry an undelivered notification for up to 30 seconds
+```
+
+</TabItem>
+</ConfigTabs>
+
 ### Android
 
 Most Android phones have battery optimization settings. To get reliable Notification delivery the browser (Chrome, Firefox) should have battery optimizations disabled. If Frigate is running as a PWA then the Frigate app should have battery optimizations disabled as well.

docs/docs/configuration/object_detectors.md

@@ -151,7 +151,7 @@ Along with picking a detector for your hardware, you will choose a model's **inp
 
 :::tip
 
-The best detection accuracy comes from a model trained on images that look like what Frigate actually sees: security camera footage cropped to regions of interest. You can train or fine-tune your own model on images like this and run it as a custom model (see the per-detector sections below), but [Frigate+](/plus) makes this much easier by handling the training for you on images submitted from your own cameras. For YOLOv9, the `s` (small) variant at `320x320` resolution is a good place to start.
+The best detection accuracy comes from a model trained on images that look like what Frigate actually sees: security camera footage cropped to regions of interest. You can train or fine-tune your own model on images like this and run it as a custom model (see the per-detector sections below), but [Frigate+](/plus) makes this much easier by handling the training for you on images submitted from your own cameras. For YOLOv9, the `s` (small) variant at `320x320` resolution is a good place to start, and the larger `c` variant is available for more powerful hardware.
 
 :::
 
@@ -361,7 +361,7 @@ The NPU firmware is loaded by the host kernel and is not part of the Frigate ima
 
 Frigate bundles a specific version of Intel's [linux-npu-driver](https://github.com/intel/linux-npu-driver/releases), and the host firmware must come from that release or a newer one. Firmware older than the bundled driver may fail with `MAPPED_INFERENCE_VERSION is NOT compatible with the ELF`, where `Expected` is the version the firmware supports and `received` is the version the bundled compiler produced. Distributions often package older firmware than the driver Frigate ships, so check the build date on the host with `sudo dmesg | grep -i vpu` and update it there if needed.
 
-Intel NPUs cannot be used under Home Assistant OS, which does not include the NPU firmware.
+Intel NPUs can be used under Home Assistant OS 18.4 or newer.
 
 ### Configuration {#configuration-openvino}
 

docs/docs/configuration/record.md

@@ -413,17 +413,18 @@ Avoid removing audio from only one of the two streams (for example with `-an`).
 
 As a general rule, features that read recordings prefer the main stream and fall back to the sub stream for time ranges where the main recordings have expired. Analytics features use only the main stream.
 
-| Feature                                                                                  | Stream used                                                                                                   |
-| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Recording playback (History and Review)                                                  | Both (main preferred with sub fallback by default), or exactly one stream when a quality is selected manually |
-| Tracking details and Explore clip playback                                               | Main, falling back to sub where the main recordings have expired                                              |
+| Feature                                                                                  | Stream used                                                                                                               |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Recording playback (History and Review)                                                  | Both (main preferred with sub fallback by default), or exactly one stream when a quality is selected manually             |
+| Tracking details and Explore clip playback                                               | Main, falling back to sub where the main recordings have expired                                                          |
 | Exports                                                                                  | Both (main preferred with sub fallback by default), or exactly one stream when a quality is selected in the export dialog |
-| Clip downloads                                                                           | Main; sub is used when no main recordings remain in the range (streams are never mixed in one file)           |
-| Frames grabbed from a recording in History (download snapshot, submit frame to Frigate+) | Main preferred, sub fallback                                                                                  |
-| Audio extraction (e.g., transcription)                                                   | Main preferred, sub fallback                                                                                  |
-| Motion search                                                                            | Main only                                                                                                     |
-| Review timeline motion data                                                              | Main only                                                                                                     |
-| Storage usage statistics                                                                 | Both streams counted, and listed separately per camera                                                        |
+| Clip downloads                                                                           | Main; sub is used when no main recordings remain in the range (streams are never mixed in one file)                       |
+| Debug replay                                                                             | Main; sub is used when no main recordings remain in the range (streams are never mixed in one file)                       |
+| Frames grabbed from a recording in History (download snapshot, submit frame to Frigate+) | Main preferred, sub fallback                                                                                              |
+| Audio extraction (e.g., transcription)                                                   | Main preferred, sub fallback                                                                                              |
+| Motion search                                                                            | Main only                                                                                                                 |
+| Review timeline motion data                                                              | Main only                                                                                                                 |
+| Storage usage statistics                                                                 | Both streams counted, and listed separately per camera                                                                    |
 
 This table covers only features that read recordings from disk. Tracked object snapshots and thumbnails (the images shown in Explore and sent with notifications, and the images submitted to Frigate+ from a tracked object) are captured live from the `detect` stream as the object is tracked, never from recordings, so sub stream recording does not affect them.
 

docs/docs/configuration/restream.md

@@ -221,6 +221,8 @@ Any `#` parameter on a bare `rtsp://` source disables the backchannel unless the
 
 For security reasons, the `echo:`, `expr:`, and `exec:` stream sources are disabled by default in go2rtc. These sources allow arbitrary command execution and can pose security risks if misconfigured.
 
+go2rtc's `${VAR:default}` variable syntax is also disabled by default in stream sources, since its default can name one of those sources. Use Frigate's [`{FRIGATE_*}` substitution](./config.md#environment-variable-substitution) instead.
+
 If you attempt to use these sources in your configuration, the streams will be removed and an error message will be printed in the logs.
 
 To enable these sources, you must set the environment variable `GO2RTC_ALLOW_ARBITRARY_EXEC=true`. This can be done in your Docker Compose file or container environment, or for Home Assistant App users with the `go2rtc_allow_arbitrary_exec` option in the App's configuration. The `environment_vars` section of the Frigate config can't enable it:

docs/docs/development/contributing.md

@@ -94,7 +94,7 @@ After closing VS Code, you may still have containers running. To close everythin
 GitHub will execute unit tests on new PRs. You must ensure that all tests pass.
 
 ```shell
-python3 -u -m unittest
+python3 -u -m frigate.test
 ```
 
 #### FFMPEG Hardware Acceleration
@@ -207,7 +207,7 @@ npm run lint
 - Ensure the backend [unit tests](#unit-tests) pass. Your PR cannot be merged unless tests pass.
 
 ```shell
-python3 -u -m unittest
+python3 -u -m frigate.test
 ```
 
 - Ensure the end-to-end tests pass. They run in Playwright against a production build with mocked API data, so they don't need a running Frigate instance. Add or update tests in `web/e2e/specs/` when you change UI behavior.

docs/docs/frigate/installation.md

@@ -763,20 +763,17 @@ The community supported docker image tags for the current stable version are:
 
 :::warning
 
-As of Home Assistant Operating System 10.2 and Home Assistant 2023.6 defining separate network storage for media is supported.
-
 There are important limitations in HA OS to be aware of:
 
-- Separate local storage for media is not yet supported by Home Assistant
 - AMD GPUs are not supported because HA OS does not include the mesa driver.
-- Intel NPUs are not supported because HA OS does not include the NPU firmware.
+- Intel NPUs require Home Assistant OS 18.4 or newer. Earlier releases do not include the NPU firmware.
 - Nvidia GPUs are not supported because HA Apps do not support the Nvidia runtime.
 
 :::
 
 :::tip
 
-See [the network storage guide](/guides/ha_network_storage.md) for instructions to setup network storage for frigate.
+Frigate's media can be kept on separate storage, either a network share (Home Assistant 2023.6 or newer) or a local disk such as a second internal drive or a USB drive (Home Assistant 2026.11 or newer). See [the storage guide](/guides/ha_network_storage.md) for setup instructions.
 
 :::
 

docs/docs/frigate/network_requirements.md

@@ -135,6 +135,15 @@ telemetry:
   version_check: false
 ```
 
+### Anonymous Analytics
+
+If [anonymous analytics](/configuration/advanced/analytics) sharing is turned on, Frigate sends one report a day to `https://analytics.frigate.video`. It's off by default, so no outbound connection happens unless you enable it:
+
+```yaml
+telemetry:
+  analytics: true
+```
+
 ### 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.
@@ -171,7 +180,7 @@ To run Frigate in an air-gapped or offline environment:
 2. **Pre-download the training base weights**: If you plan to train custom classification models, set `TF_KERAS_MOBILENET_V2_WEIGHTS_URL` before training, then run one training job while online. Without this variable the base weights are cached outside `/config/` and are lost whenever the container is recreated, so a later training run will fail offline. If the machine never has internet access, copy the weights in manually as described below.
 3. **Disable version check**: Set `telemetry.version_check: false` in your configuration.
 4. **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.
-5. **Avoid cloud features**: Do not configure Frigate+, Generative AI providers that require internet, or cloud MQTT brokers.
+5. **Avoid cloud features**: Do not configure Frigate+, Generative AI providers that require internet, or cloud MQTT brokers, and leave anonymous analytics off (its default).
 6. **Use local model mirrors**: If limited internet is available, set the `HF_ENDPOINT`, `GITHUB_ENDPOINT`, `GITHUB_RAW_ENDPOINT`, and `TF_KERAS_MOBILENET_V2_WEIGHTS_URL` environment variables to point to local mirrors.
 
 After these steps, Frigate will operate with no outbound internet connections.

docs/docs/guides/ha_network_storage.md

@@ -1,40 +1,48 @@
 ---
 id: ha_network_storage
-title: Home Assistant network storage
+title: Home Assistant storage
 ---
 
-As of Home Assistant 2023.6, Network Mounted Storage is supported for Apps.
+Frigate's media (`/media/frigate`) can be stored on a network share or a separate local disk (internal or USB) instead of the Home Assistant system disk.
 
-## Setting Up Remote Storage For Frigate
+## Prerequisites
 
-### Prerequisites
+### Network storage
 
 - Home Assistant 2023.6 or newer is installed
 - Running Home Assistant Operating System 10.2 or newer OR Running Supervised with latest os-agent installed (this is required for supervised install)
 
+### Local disk
+
+- Home Assistant 2026.11 or newer is installed
+- The disk is already formatted, ideally as ext4 (Home Assistant does not format disks). Avoid FAT32, exFAT, and NTFS, which do not support Linux file permissions.
+
+## Setting Up Storage For Frigate
+
 ### Initial Setup
 
 1. Stop the Frigate App
 
 ### Move current data
 
-Keeping the current data is optional, but the data will need to be moved regardless so the share can be created successfully.
+Keeping the current data is optional, but `/media/frigate` must be moved or deleted so Home Assistant can mount the storage there. The database and config are stored elsewhere and are not affected.
 
 #### If you want to keep the current data
 
-1. Move the frigate.db, frigate.db-shm, frigate.db-wal files to the /config directory
-2. Rename the /media/frigate folder to /media/frigate_tmp
+1. Rename the /media/frigate folder to /media/frigate_tmp
 
 #### If you don't want to keep the current data
 
 1. Delete the /media/frigate folder and all of its contents
 
-### Create the media share
+### Add the storage
 
-1. Go to **Settings -> System -> Storage -> Add Network Storage**
-2. Name the share `frigate` (this is required)
-3. Choose type `media`
-4. Fill out the additional required info for your particular NAS
+1. Go to **Settings -> System -> Storage -> Add storage**
+2. Name the storage `frigate` (this is required)
+3. Choose usage `media`
+4. Choose the type:
+   - For network storage, choose `Samba/Windows (CIFS)` or `Network File System (NFS)` and fill out the additional required info for your particular NAS
+   - For a local disk, choose `Local disk` and select the disk to use
 5. Connect
 6. Move files from `/media/frigate_tmp` to `/media/frigate` if they were kept in previous step
 7. Start the Frigate App

docs/docs/integrations/third_party_extensions.md

@@ -47,6 +47,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.
 
+## [FrigatePiP](https://github.com/maciejgornicz/frigate-pip)
+
+[FrigatePiP](https://github.com/maciejgornicz/frigate-pip) pops up a small picture-in-picture window with a camera's live video in a corner of the screen when Frigate detects an object, and closes it when the activity ends. It runs as a Windows tray app and on Linux (desktop windows, a console framebuffer, a terminal or tmux popups), receives events over Frigate's WebSocket or MQTT and plays the go2rtc RTSP stream with hardware decoding and camera audio.
+
 ## [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.
@@ -55,6 +59,10 @@ This is a fork (with fixed errors and new features) of [original Double Take](ht
 
 [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.
 
+## [reostream](https://github.com/VoltTech21/reostream)
+
+[reostream](https://github.com/VoltTech21/reostream) is a proxy for Reolink cameras that pulls video over Reolink's own protocol (the one the Reolink app and NVR use) instead of the camera's RTSP server, and serves it back as RTSP for go2rtc and Frigate. It helps models whose RTSP stream smears, drops frames or loses full resolution, and supports two-way talk.
+
 ## [Scrypted - Frigate bridge plugin](https://github.com/apocaliss92/scrypted-frigate-bridge)
 
 [Scrypted - Frigate bridge](https://github.com/apocaliss92/scrypted-frigate-bridge) is a plugin that allows you to ingest Frigate detections, motion, videoclips on Scrypted as well as provide templates to export rebroadcast configurations on Frigate.

docs/docs/plus/annotating.md

@@ -25,6 +25,12 @@ If you have an active Frigate+ subscription, new uploads will be scanned for the
 
 Suggestions are converted to labels when saving, so you should remove any errant suggestions. There is already some logic designed to avoid duplicate labels, but you may still occasionally see some duplicate suggestions. You should keep the most accurate bounding box and delete any duplicates so that you have just one label per object remaining.
 
+## Reviewing annotations with Patches
+
+The Patches tab on the Images page shows a cropped view of every annotation for a label in a grid. Scanning the crops makes it much easier to spot a mislabeled object than paging through full images one at a time. Pick a label to get started, and optionally narrow the results to a single camera. Clicking a patch opens that image in the editor so you can fix the annotation.
+
+Patches only include annotations from images you have already verified.
+
 ## False positive labels
 
 False positives will be shown with a red box and the label will have a strike through. These can't be adjusted, but they can be deleted if you accidentally submit a true positive as a false positive from Frigate.
@@ -51,3 +57,12 @@ Misidentified objects should have a correct label added. For example, if a perso
 | `scrollwheel`     | Zoom in/out                   |
 | `f`               | Hide/show all but current box |
 | `spacebar`        | Verify and save               |
+
+## Deleting images
+
+In most cases, you should keep your existing images. Removing training data usually makes accuracy worse, not better, so you shouldn't delete images just because you think you made some annotation mistakes. Deleting images makes sense when you move to a new location, or significantly upgrade or reposition your cameras.
+
+- To delete all images for a camera, use the **Delete Images** button for that camera on the Cameras page.
+- To delete all images in your account, use **Delete All Images** on the Settings page.
+
+Deletions run in the background, and their progress is shown in the bulk operations panel. Deleted images cannot be recovered and are no longer used to train your models.

docs/docs/plus/faq.md

@@ -26,7 +26,9 @@ Yes. Subscriptions to Frigate+ provide access to the infrastructure used to trai
 ### Can I use Frigate+ models commercially?
 
 A standard subscription covers use on camera systems you own or operate, including for your business. A shop, restaurant, warehouse, or office running Frigate+ at its own locations (including multiple locations) is exactly the kind of use the subscription is for.
+
 What the standard subscription does not cover is using Frigate+ models to provide a product or service to others. If you're deploying models at your customers' sites, bundling them with hardware you sell, or running them as part of a hosted or managed service, even if your customers never receive the model files themselves, you'll need a commercial license.
+
 Note that professional installers are fine under standard subscriptions when each customer holds their own Frigate+ subscription. The commercial license is for cases where your license powers your customers' sites.
 
 ### Why can't I submit images to Frigate+?

docs/docs/plus/first_model.md

@@ -17,7 +17,7 @@ For more detailed recommendations, you can refer to the docs on [annotating](./a
 
 ## Step 2: Submit a model request
 
-Once you have an initial set of verified images, you can request a model on the Models page. For guidance on choosing a model type, refer to [this part of the documentation](./index.md#available-model-types). If you are unsure which type to request, you can test the base model for each version from the "Base Models" tab. Each model request requires 1 of the 12 trainings that you receive with your annual subscription. This model will support all [label types available](./index.md#available-label-types) even if you do not submit any examples for those labels. Model creation can take up to 36 hours.
+Once you have an initial set of verified images, you can request a model on the Models page. For guidance on choosing a model type, refer to [this part of the documentation](./index.md#available-model-types). If you are unsure which type to request, you can test the base model for each version from the "Base Models" tab. For most hardware, `yolov9` is recommended; `mobiledet` is a legacy model type and will be removed in 2027. Each model request requires 1 of the 12 trainings that you receive with your annual subscription. This model will support all [label types available](./index.md#available-label-types) even if you do not submit any examples for those labels. Model creation can take up to 36 hours.
 ![Plus Models Page](/img/plus/plus-models.jpg)
 
 ## Step 3: Set your model

docs/docs/plus/index.md

@@ -5,25 +5,41 @@ title: Models
 
 <a href="https://frigate.video/plus" target="_blank" rel="nofollow">Frigate+</a> offers models trained on images submitted by Frigate+ users from their security cameras and is specifically designed for the way Frigate NVR analyzes video footage. These models offer higher accuracy with less resources. The images you upload are used to fine tune a base model trained from images uploaded by all Frigate+ users. This fine tuning process results in a model that is optimized for accuracy in your specific conditions.
 
-With a subscription, 12 model trainings to fine tune your model per year are included. In addition, you will have access to any base models published while your subscription is active. If you cancel your subscription, you will retain access to any trained and base models in your account. An active subscription is required to submit model requests or purchase additional trainings. New base models are published quarterly with target dates of January 15th, April 15th, July 15th, and October 15th.
+With a subscription, 12 model trainings to fine tune your model per year are included. In addition, you will have access to any base models published while your subscription is active. If you cancel your subscription, you will retain access to any trained and base models in your account. An active subscription is required to submit model requests or purchase additional trainings. New base models are published twice per year.
 
 Information on how to integrate Frigate+ with Frigate can be found in the [integration docs](../integrations/plus.md).
 
 ## Available model types
 
-There are three model types offered in Frigate+, `mobiledet`, `yolonas`, and `yolov9`. All of these models are object detection models and are trained to detect the same set of labels [listed below](#available-label-types).
+There are three model types offered in Frigate+, `yolov9`, `yolonas`, and `mobiledet` (legacy). All of these models are object detection models and are trained to detect the same set of labels [listed below](#available-label-types).
 
 Not all model types are supported by all detectors, so it's important to choose a model type to match your detector as shown in the table under [supported detector types](#supported-detector-types). You can test model types for compatibility and speed on your hardware by using the base models.
 
 | Model Type  | Description                                                                                                                                                    |
 | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mobiledet` | Based on the same architecture as the default model included with Frigate. Runs on Google Coral devices and CPUs.                                              |
-| `yolonas`   | A newer architecture that offers slightly higher accuracy and improved detection of small objects. Runs on Intel, NVidia GPUs, and AMD GPUs.                   |
 | `yolov9`    | A leading SOTA (state of the art) object detection model with similar performance to yolonas, but on a wider range of hardware options. Runs on most hardware. |
+| `yolonas`   | A newer architecture that offers slightly higher accuracy and improved detection of small objects. Runs on Intel, NVidia GPUs, and AMD GPUs.                   |
+| `mobiledet` | Legacy. Based on the same architecture as the default model included with Frigate. Runs on Google Coral devices and CPUs.                                      |
+
+:::warning
+
+`mobiledet` is a legacy model type. Base model 2026.3 is the last base model update for `mobiledet`, and it is planned to be removed from Frigate+ in 2027. If you are using `mobiledet` with a Google Coral, request a `yolov9` model with the `edgetpu` variant instead.
+
+:::
 
 ### YOLOv9 Details
 
-YOLOv9 models are available in `s`, `t`, `edgetpu` variants. When requesting a `yolov9` model, you will be prompted to choose a variant. If you want the model to be compatible with a Google Coral, you will need to choose the `edgetpu` variant. If you are unsure what variant to choose, you should perform some tests with the base models to find the performance level that suits you. The `s` size is most similar to the current `yolonas` models in terms of inference times and accuracy, and a good place to start is the `320x320` resolution model for `yolov9s`.
+YOLOv9 models are available in `t`, `s`, `c`, and `edgetpu` variants, and an `m` size is coming soon. When requesting a `yolov9` model, you will be prompted to choose a variant. If you want the model to be compatible with a Google Coral, you will need to choose the `edgetpu` variant, which requires Frigate 0.17 or later. If you are unsure what variant to choose, you should perform some tests with the base models to find the performance level that suits you. The `s` size is most similar to the current `yolonas` models in terms of inference times and accuracy, and a good place to start is the `320x320` resolution model for `yolov9s`. The `c` size is larger and offers higher accuracy at the cost of slower inference, so it is best suited to more powerful hardware such as GPUs.
+
+| Variant   | Size                 | Parameters | Speed and accuracy                                          | Best suited for                                    |
+| --------- | -------------------- | ---------- | ----------------------------------------------------------- | -------------------------------------------------- |
+| `t`       | Tiny                 | ~2.0M      | Fastest inference, lowest accuracy                          | Low power hardware or a large number of cameras    |
+| `s`       | Small                | ~7.1M      | Balanced. Similar inference times and accuracy to `yolonas` | Most users. Start with `320x320`                   |
+| `m`       | Medium (coming soon) | ~20.0M     | Slower than `s` with higher accuracy                        | Mid-range GPUs and NPUs                            |
+| `c`       | Compact              | ~25.3M     | Highest accuracy, slowest inference                         | More powerful hardware such as GPUs                |
+| `edgetpu` | N/A                  | N/A        | Optimized to run on the Coral's Edge TPU                    | Google Coral devices only (requires Frigate 0.17+) |
+
+Parameter counts are for the standard YOLOv9 architectures. Actual inference times depend on your hardware and the input resolution you choose, so test with the base models before requesting a model.
 
 :::info
 
@@ -33,7 +49,7 @@ When switching to YOLOv9, you may need to adjust your thresholds for some object
 
 #### Hailo Support
 
-If you have a Hailo device, you will need to specify the hardware you have when submitting a model request because they are not cross compatible. Please test using the available base models before submitting your model request.
+If you have a Hailo device, you will need to specify the hardware you have when submitting a model request because they are not cross compatible. Hailo models are available for the `t`, `s`, and `c` variants on Hailo8, Hailo8L, and Hailo8R devices. Please test using the available base models before submitting your model request.
 
 #### Rockchip (RKNN) Support
 
@@ -43,15 +59,15 @@ Rockchip models are automatically converted as of 0.17. For 0.16, YOLOv9 onnx mo
 
 Currently, Frigate+ models support CPU (`cpu`), Google Coral (`edgetpu`), OpenVino (`openvino`), ONNX (`onnx`), Hailo (`hailo`), and Rockchip (`rknn`) detectors.
 
-| Hardware                                                                         | Recommended Detector Type | Recommended Model Type |
-| -------------------------------------------------------------------------------- | ------------------------- | ---------------------- |
-| [CPU](/configuration/object_detectors.md#cpu-detector-not-recommended)           | `cpu`                     | `mobiledet`            |
-| [Coral (all form factors)](/configuration/object_detectors.md#edge-tpu-detector) | `edgetpu`                 | `yolov9`               |
-| [Intel](/configuration/object_detectors.md#openvino-detector)                    | `openvino`                | `yolov9`               |
-| [NVidia GPU](/configuration/object_detectors#onnx)                               | `onnx`                    | `yolov9`               |
-| [AMD ROCm GPU](/configuration/object_detectors#amdrocm-gpu-detector)             | `onnx`                    | `yolov9`               |
-| [Hailo8/Hailo8L/Hailo8R](/configuration/object_detectors#hailo)                  | `hailo`                   | `yolov9`               |
-| [Rockchip NPU](/configuration/object_detectors#rockchip-platform)                | `rknn`                    | `yolov9`               |
+| Hardware                                                                         | Recommended Detector Type   | Recommended Model Type |
+| -------------------------------------------------------------------------------- | --------------------------- | ---------------------- |
+| [CPU](/configuration/object_detectors.md#cpu-detector-not-recommended)           | `openvino (or alternative)` | `yolov9`               |
+| [Coral (all form factors)](/configuration/object_detectors.md#edge-tpu-detector) | `edgetpu`                   | `yolov9`               |
+| [Intel](/configuration/object_detectors.md#openvino-detector)                    | `openvino`                  | `yolov9`               |
+| [NVidia GPU](/configuration/object_detectors#onnx)                               | `onnx`                      | `yolov9`               |
+| [AMD ROCm GPU](/configuration/object_detectors#amdrocm-gpu-detector)             | `onnx`                      | `yolov9`               |
+| [Hailo8/Hailo8L/Hailo8R](/configuration/object_detectors#hailo)                  | `hailo`                     | `yolov9`               |
+| [Rockchip NPU](/configuration/object_detectors#rockchip-platform)                | `rknn`                      | `yolov9`               |
 
 ## Improving your model
 
@@ -66,7 +82,7 @@ Some users may find that Frigate+ models result in more false positives initiall
 Frigate+ models support a more relevant set of objects for security cameras. The labels for annotation in Frigate+ are configurable by editing the camera in the Cameras section of Frigate+. Currently, the following objects are supported:
 
 - **People**: `person`, `face`, `baby`
-- **Vehicles**: `car`, `motorcycle`, `bicycle`, `boat`, `school_bus`, `garbage truck`, `license_plate`
+- **Vehicles**: `car`, `motorcycle`, `bicycle`, `boat`, `school_bus`, `garbage_truck`, `license_plate`
 - **Delivery Logos**: `amazon`, `usps`, `ups`, `fedex`, `dhl`, `an_post`, `purolator`, `postnl`, `nzpost`, `postnord`, `gls`, `dpd`, `canada_post`, `royal_mail`
 - **Animals**: `dog`, `cat`, `deer`, `horse`, `bird`, `raccoon`, `fox`, `bear`, `cow`, `squirrel`, `goat`, `rabbit`, `skunk`, `kangaroo`, `possum`, `rodent`
 - **Other**: `package`, `waste_bin`, `bbq_grill`, `robot_lawnmower`, `umbrella`, `baby_stroller`
@@ -81,7 +97,7 @@ Where possible, these labels are mapped to existing labels during training. For
 
 - **Vehicles**: `tractor`, `golf_cart`, `bus`, `airplane`, `helicopter`, `rickshaw`, `scooter`
 - **Delivery Logos**: `bpost`, `auspost`, `aramex`, `transoflex`, `parcelforce`, `hermes`, `cargus`, `fan_courier`, `sameday`, `la_poste`
-- **Animals**: `badger`, `chicken`, `duck`, `turkey`, `groundhog`, `boar`, `hedgehog`, `wombat`, `bobcat`, `mustelid`, `mountain_lion`, `crocodile`, `monkey`, `coyote`, `porcupine`, `sheep`, `snake`, `lizard`, `heron`, `elk`, `moose`, `pig`, `donkey`, `civet`
+- **Animals**: `badger`, `chicken`, `duck`, `turkey`, `groundhog`, `boar`, `hedgehog`, `wombat`, `bobcat`, `mustelid`, `mountain_lion`, `crocodile`, `monkey`, `coyote`, `porcupine`, `sheep`, `snake`, `lizard`, `heron`, `elk`, `moose`, `pig`, `donkey`, `civet`, `chipmunk`
 - **Other**: `sports_ball`, `drone`, `lawnmower`
 
 Candidate labels are not available for automatic suggestions.

docs/docs/troubleshooting/faqs.md

@@ -170,7 +170,7 @@ Open one of the tracked objects in Explore → **Tracking Details**. If the dete
 What helps:
 
 - **Improve the view**: even a small angle change that gets more of the car visible could lift scores enough to stabilize tracking.
-- **Use a more accurate model**: switching from `mobiledet` to `yolov9`, or stepping up to a larger variant like `yolov9-s` over `yolov9-t`, can help (at the cost of inference time, and still on the COCO dataset). The biggest gains usually come from fine-tuning a model on images from your own cameras so it learns your specific scene. [Frigate+](https://frigate.video/plus) is a paid option that does this - models are trained on security-camera footage and can be fine-tuned on images you submit from your own setup.
+- **Use a more accurate model**: switching from `mobiledet` to `yolov9`, or stepping up to a larger variant like `yolov9-s` over `yolov9-t` (or `yolov9-c` on more powerful hardware), can help (at the cost of inference time, and still on the COCO dataset). The biggest gains usually come from fine-tuning a model on images from your own cameras so it learns your specific scene. [Frigate+](https://frigate.video/plus) is a paid option that does this - models are trained on security-camera footage and can be fine-tuned on images you submit from your own setup.
 - **Don't set `detect -> stationary -> max_frames` for `car`**: it artificially ends tracking and forces re-detection as a new object. See [Stationary Objects](../configuration/stationary_objects.md).
 - **Restrict alerts to the areas you care about** with `required_zones`. See [Zones](../configuration/zones.md#restricting-alerts-and-detections-to-specific-zones). Make sure those zones use the default `loitering_time: 0` unless you specifically want the review item to stay open until the car leaves.
 - **Filter impossible locations** with [object filter masks](../configuration/masks.md#object-filter-masks) if cars are being detected on rooftops, treetops, etc.

docs/docusaurus.config.ts

@@ -4,7 +4,7 @@ import type { Config, PluginConfig } from "@docusaurus/types";
 import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
 
 // Bump when a new stable release ships
-const STABLE_VERSION = "0.18";
+const STABLE_VERSION = "0.19";
 
 const config: Config = {
   title: "Frigate",

docs/sidebars.ts

@@ -130,6 +130,7 @@ const sidebars: SidebarsConfig = {
         label: "Advanced Configuration",
         items: [
           "configuration/advanced/system",
+          "configuration/advanced/analytics",
           "configuration/advanced/reference",
           {
             type: "link",

docs/src/components/AnalyticsFields/index.jsx

@@ -0,0 +1,60 @@
+import React from "react";
+import schema from "@site/static/frigate-analytics-schema.json";
+
+function resolve(node) {
+  if (!node) return node;
+  if (node.$ref) return schema.$defs[node.$ref.split("/").pop()];
+  if (node.anyOf) {
+    const inner = node.anyOf.find((option) => option.type !== "null");
+    return inner ? resolve(inner) : node;
+  }
+  return node;
+}
+
+function rows(properties, prefix = "") {
+  return Object.entries(properties).flatMap(([name, field]) => {
+    const path = prefix ? `${prefix}.${name}` : name;
+    const row = {
+      path,
+      description: field.description,
+      isPublic: field["x-public"],
+    };
+    const target = resolve(field);
+
+    if (target?.properties) return [row, ...rows(target.properties, path)];
+
+    const values = resolve(target?.additionalProperties);
+    if (values?.properties)
+      return [row, ...rows(values.properties, `${path}.<key>`)];
+
+    const items = resolve(target?.items);
+    if (items?.properties) return [row, ...rows(items.properties, `${path}[]`)];
+
+    return [row];
+  });
+}
+
+export default function AnalyticsFields() {
+  return (
+    <table>
+      <thead>
+        <tr>
+          <th>Field</th>
+          <th>Description</th>
+          <th>Public</th>
+        </tr>
+      </thead>
+      <tbody>
+        {rows(schema.properties).map((row) => (
+          <tr key={row.path}>
+            <td>
+              <code>{row.path}</code>
+            </td>
+            <td>{row.description}</td>
+            <td>{row.isPublic ? "Yes" : "No"}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

docs/static/frigate-api.yaml

@@ -10,6 +10,25 @@ servers:
   - url: https://demo.frigate.video/api
   - url: http://localhost:5001/api
 paths:
+  /analytics/preview:
+    get:
+      tags:
+        - Analytics
+      summary: Get Analytics Preview
+      description: |-
+        **Access:** Admin role required.
+
+        Get the analytics report Frigate would send next, without sending it.
+      operationId: get_analytics_preview_analytics_preview_get
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema: {}
+      security:
+        - frigateAdminAuth: []
+      x-required-role: admin
   /auth/first_time_login:
     get:
       tags:
@@ -3129,6 +3148,25 @@ paths:
         - frigateUserAuth: []
       x-required-role: any
       description: '**Access:** Any authenticated user.'
+  /plus/validate:
+    post:
+      tags:
+        - App
+      summary: Validate Plus Key
+      description: |-
+        **Access:** Admin role required.
+
+        Validate the configured Frigate+ API key with the Frigate+ server.
+      operationId: validate_plus_key_plus_validate_post
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema: {}
+      security:
+        - frigateAdminAuth: []
+      x-required-role: admin
   /recognized_license_plates:
     get:
       tags:
@@ -6371,6 +6409,7 @@ paths:
           required: false
           schema:
             type: integer
+            minimum: 0
             description: Padding to apply to the vod.
             default: 0
             title: Padding
@@ -7576,6 +7615,7 @@ paths:
           required: false
           schema:
             type: integer
+            minimum: 1
             default: 30
             title: Scale
       responses:

frigate/analytics/__init__.py

@@ -0,0 +1 @@
+"""Opt-in anonymous analytics reports."""

frigate/analytics/collectors/__init__.py

@@ -0,0 +1 @@
+"""One collector per report section."""

frigate/analytics/collectors/cameras.py

@@ -0,0 +1,238 @@
+"""Cameras section: counts and histograms across cameras, never per camera."""
+
+from collections import Counter
+from typing import Any
+from urllib.parse import urlsplit
+
+from frigate.analytics.collectors.common import closed, histogram
+from frigate.analytics.context import ReportContext
+from frigate.analytics.schema import (
+    CamerasSection,
+    ConnectionQuality,
+    FpsBucket,
+    HeightBucket,
+    HwaccelKey,
+    InputPresetKey,
+    RetainBucket,
+    RetainDays,
+)
+from frigate.config import CameraConfig
+from frigate.config.camera.camera import CameraTypeEnum
+from frigate.config.camera.ffmpeg import CameraInput, CameraRoleEnum
+from frigate.const import REPLAY_CAMERA_PREFIX
+
+# the upper edge of every height bucket but the last
+HEIGHT_BUCKETS = (
+    (360, HeightBucket.le_360),
+    (540, HeightBucket.h480),
+    (900, HeightBucket.h720),
+    (1260, HeightBucket.h1080),
+    (1800, HeightBucket.h1440),
+)
+RESTREAM_HOSTS = frozenset({"127.0.0.1", "localhost"})
+RESTREAM_PORT = 8554
+QUALITIES = frozenset(ConnectionQuality)
+
+
+def height_bucket(height: int) -> HeightBucket:
+    """The nearest standard resolution bucket for a detect height."""
+    for limit, bucket in HEIGHT_BUCKETS:
+        if height <= limit:
+            return bucket
+
+    return HeightBucket.ge_2160
+
+
+def fps_bucket(fps: int) -> FpsBucket:
+    """The bucket for a detect fps."""
+    if fps <= 5:
+        return FpsBucket.le_5
+
+    if fps <= 10:
+        return FpsBucket.f6_10
+
+    return FpsBucket.gt_10
+
+
+def retain_bucket(days: float) -> RetainBucket:
+    """The bucket for a retention period in days."""
+    if days <= 0:
+        return RetainBucket.zero
+
+    if days <= 7:
+        return RetainBucket.d1_7
+
+    if days <= 30:
+        return RetainBucket.d8_30
+
+    return RetainBucket.gt_30
+
+
+def preset_key(args: str | list[str], enum: Any) -> Any:
+    """The preset's name, custom for hand written args, or none."""
+    if not args:
+        return enum("none")
+
+    if isinstance(args, str) and args.startswith("preset-"):
+        return closed(enum, args.removeprefix("preset-"), enum("custom"))
+
+    return enum("custom")
+
+
+def is_restream(path: str) -> bool:
+    """Whether an input reads from the local go2rtc restream."""
+    try:
+        url = urlsplit(path)
+        return url.hostname in RESTREAM_HOSTS and url.port == RESTREAM_PORT
+    except ValueError:
+        return False
+
+
+def role_input(camera: CameraConfig, role: CameraRoleEnum) -> CameraInput | None:
+    """The camera's first input with the given role."""
+    return next((i for i in camera.ffmpeg.inputs if role in i.roles), None)
+
+
+def object_masks(camera: CameraConfig) -> int:
+    """Camera and per-label object masks, minus the global_<id> filter copies."""
+    own = sum(1 for mask in camera.objects.mask.values() if mask is not None)
+    per_label = sum(
+        1
+        for label_filter in camera.objects.filters.values()
+        for mask_id, mask in label_filter.mask.items()
+        if mask is not None and not mask_id.startswith("global_")
+    )
+    return own + per_label
+
+
+def collect(ctx: ReportContext) -> CamerasSection:
+    """Count camera settings across the cameras enabled in config."""
+    cameras = {
+        name: camera
+        for name, camera in ctx.config.cameras.items()
+        if not name.startswith(REPLAY_CAMERA_PREFIX)
+    }
+    camera_stats = ctx.stats.get("cameras", {})
+
+    # cameras disabled in config are parked, so they'd skew feature adoption
+    active = [
+        (name, camera) for name, camera in cameras.items() if camera.enabled_in_config
+    ]
+
+    flags: Counter[str] = Counter()
+    types: Counter[CameraTypeEnum] = Counter()
+    heights: Counter[HeightBucket] = Counter()
+    fps: Counter[FpsBucket] = Counter()
+    hwaccel: Counter[Any] = Counter()
+    input_presets: Counter[Any] = Counter()
+    quality: Counter[ConnectionQuality] = Counter()
+    retain: dict[str, Counter[RetainBucket]] = {
+        period: Counter() for period in ("continuous", "motion", "alerts", "detections")
+    }
+
+    for name, camera in active:
+        detect_input = role_input(camera, CameraRoleEnum.detect)
+        record_input = role_input(camera, CameraRoleEnum.record)
+
+        # config validation requires a detect input, so this never skips
+        if detect_input is None:
+            continue
+
+        types[camera.type] += 1
+        fps[fps_bucket(camera.detect.fps)] += 1
+        hwaccel[
+            preset_key(
+                detect_input.hwaccel_args or camera.ffmpeg.hwaccel_args, HwaccelKey
+            )
+        ] += 1
+        input_presets[
+            preset_key(
+                detect_input.input_args or camera.ffmpeg.input_args, InputPresetKey
+            )
+        ] += 1
+
+        if camera.detect.height:
+            heights[height_bucket(camera.detect.height)] += 1
+
+        state = camera_stats.get(name, {}).get("connection_quality")
+
+        # a camera turned off at runtime reports unusable
+        if camera.enabled and state in QUALITIES:
+            quality[ConnectionQuality(state)] += 1
+
+        if camera.record.enabled:
+            retain["continuous"][retain_bucket(camera.record.continuous.days)] += 1
+            retain["motion"][retain_bucket(camera.record.motion.days)] += 1
+            retain["alerts"][retain_bucket(camera.record.alerts.retain.days)] += 1
+            retain["detections"][
+                retain_bucket(camera.record.detections.retain.days)
+            ] += 1
+
+        zones = len(camera.zones)
+        flags["go2rtc_restream"] += any(
+            is_restream(i.path) for i in camera.ffmpeg.inputs
+        )
+        flags["separate_detect_stream"] += (
+            record_input is not None and record_input.path != detect_input.path
+        )
+        flags["detect"] += camera.detect.enabled
+        flags["record"] += camera.record.enabled
+        flags["sub_stream_record"] += (
+            camera.record.enabled and camera.record.sub.enabled
+        )
+        flags["snapshots"] += camera.snapshots.enabled
+        flags["audio"] += camera.audio.enabled
+        flags["audio_transcription"] += (
+            camera.audio.enabled and camera.audio_transcription.enabled
+        )
+        flags["birdseye"] += camera.birdseye.enabled
+        flags["onvif"] += bool(camera.onvif.host)
+        flags["autotracking"] += camera.onvif.autotracking.enabled
+        flags["face_recognition"] += camera.face_recognition.enabled
+        flags["lpr"] += camera.lpr.enabled
+        flags["review_genai"] += camera.review.genai.enabled
+        flags["object_genai"] += camera.objects.genai.enabled
+        flags["notifications"] += camera.notifications.enabled
+        flags["zones"] += zones
+        flags["cameras_with_zones"] += zones > 0
+        flags["motion_masks"] += sum(
+            1 for mask in camera.motion.mask.values() if mask is not None
+        )
+        flags["object_masks"] += object_masks(camera)
+
+    return CamerasSection(
+        total=len(cameras),
+        enabled=len(active),
+        types=histogram(types),
+        detect_height=histogram(heights),
+        detect_fps=histogram(fps),
+        hwaccel=histogram(hwaccel),
+        input_preset=histogram(input_presets),
+        go2rtc_restream=flags["go2rtc_restream"],
+        separate_detect_stream=flags["separate_detect_stream"],
+        detect=flags["detect"],
+        record=flags["record"],
+        sub_stream_record=flags["sub_stream_record"],
+        snapshots=flags["snapshots"],
+        audio=flags["audio"],
+        audio_transcription=flags["audio_transcription"],
+        birdseye=flags["birdseye"],
+        onvif=flags["onvif"],
+        autotracking=flags["autotracking"],
+        face_recognition=flags["face_recognition"],
+        lpr=flags["lpr"],
+        review_genai=flags["review_genai"],
+        object_genai=flags["object_genai"],
+        notifications=flags["notifications"],
+        zones=flags["zones"],
+        cameras_with_zones=flags["cameras_with_zones"],
+        motion_masks=flags["motion_masks"],
+        object_masks=flags["object_masks"],
+        connection_quality=histogram(quality),
+        retain_days=RetainDays(
+            continuous=histogram(retain["continuous"]),
+            motion=histogram(retain["motion"]),
+            alerts=histogram(retain["alerts"]),
+            detections=histogram(retain["detections"]),
+        ),
+    )

frigate/analytics/collectors/common.py

@@ -0,0 +1,37 @@
+"""Helpers the section collectors share."""
+
+import math
+from collections import Counter
+from enum import Enum
+from typing import Any, TypeVar
+
+E = TypeVar("E", bound=Enum)
+
+
+def closed(enum: type[E], value: Any, fallback: E) -> E:
+    """The member for a value, or the fallback for one the enum doesn't know."""
+    try:
+        return enum(str(value))
+    except ValueError:
+        return fallback
+
+
+def rate(value: Any) -> float:
+    """A finite, non-negative number rounded to 2 decimals, else 0.
+
+    A NaN would serialize as null and fail the schema's number type.
+    """
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+    if not math.isfinite(number):
+        return 0.0
+
+    return round(max(number, 0.0), 2)
+
+
+def histogram(counter: "Counter[E]") -> dict[E, int]:
+    """Drop the empty buckets, since an absent key means zero."""
+    return {key: total for key, total in counter.items() if total > 0}

frigate/analytics/collectors/detection.py

@@ -0,0 +1,69 @@
+"""Detection section: models, the detectors they run on, and inference speed."""
+
+import os
+
+from frigate.analytics.collectors.common import rate
+from frigate.analytics.context import ReportContext
+from frigate.analytics.schema import DetectionModel, DetectionSection, ModelSource
+from frigate.config.config import DEFAULT_MODEL
+from frigate.const import MODEL_CACHE_DIR
+from frigate.detectors.detector_config import DEFAULT_SCENE
+from frigate.detectors.detector_types import DetectorTypeEnum
+from frigate.detectors.device import runner_names
+
+# the paths FrigateConfig fills in for a model that sets none
+BUNDLED_MODEL_PATHS = frozenset(
+    {"/cpu_model.tflite", "/edgetpu_model.tflite", str(DEFAULT_MODEL["path"])}
+)
+
+
+def model_source(path: str | None) -> ModelSource:
+    """Default, Frigate+ (a cached model next to its info file), or custom.
+
+    Parsing rewrites plus://<id> to the model cache, so the prefix is gone by now.
+    """
+    if path is None or path in BUNDLED_MODEL_PATHS:
+        return ModelSource.default
+
+    if path.startswith(f"{MODEL_CACHE_DIR}/") and os.path.isfile(f"{path}.json"):
+        return ModelSource.plus
+
+    return ModelSource.custom
+
+
+def collect(ctx: ReportContext) -> DetectionSection:
+    """Describe each configured model and its measured inference speed."""
+    config = ctx.config
+    detectors = ctx.stats.get("detectors", {})
+    model_specs = [(model, config.devices_for_model(model)) for model in config.models]
+
+    # FrigateApp.start_detectors names the processes in this same order
+    names = iter(runner_names([spec for _, specs in model_specs for spec in specs]))
+    models: list[DetectionModel] = []
+
+    for model, specs in model_specs:
+        speeds: list[float] = []
+
+        for _ in specs:
+            speed = detectors.get(next(names), {}).get("inference_speed")
+
+            if isinstance(speed, int | float) and speed > 0:
+                speeds.append(float(speed))
+
+        models.append(
+            DetectionModel(
+                default=model.scene == DEFAULT_SCENE,
+                detector=DetectorTypeEnum(specs[0].detector),
+                devices=len(specs),
+                model_type=model.model_type,
+                input=f"{model.width}x{model.height}",
+                source=model_source(model.path),
+                inference_ms=rate(sum(speeds) / len(speeds)) if speeds else None,
+            )
+        )
+
+    return DetectionSection(
+        models=models,
+        detection_fps=rate(ctx.stats.get("detection_fps")),
+        skipped_fps=rate(ctx.stats.get("skipped_fps")),
+    )

frigate/analytics/collectors/features.py

@@ -0,0 +1,150 @@
+"""Features section: enrichments, GenAI, integrations, and users."""
+
+from collections import Counter
+
+from frigate.analytics.collectors.common import closed, histogram
+from frigate.analytics.context import ReportContext
+from frigate.analytics.schema import (
+    BirdseyeUsage,
+    ClassificationUsage,
+    EnrichmentDevice,
+    EnrichmentUsage,
+    FeaturesSection,
+    GenAIUsage,
+    SemanticSearchModel,
+    SemanticSearchUsage,
+    TranscriptionModel,
+    TranscriptionUsage,
+    UserRole,
+)
+from frigate.config.camera.genai import GenAIProviderEnum, GenAIRoleEnum
+from frigate.const import REPLAY_CAMERA_PREFIX
+from frigate.models import User
+
+RUNTIME_DEVICES = {
+    "cpu": EnrichmentDevice.cpu,
+    "cuda": EnrichmentDevice.cuda,
+    "tensorrt": EnrichmentDevice.tensorrt,
+    "migraphx": EnrichmentDevice.migraphx,
+}
+OPENVINO_DEVICES = {
+    "cpu": EnrichmentDevice.openvino_cpu,
+    "gpu": EnrichmentDevice.openvino_gpu,
+    "npu": EnrichmentDevice.openvino_npu,
+}
+
+
+def enrichment_device(label: object) -> EnrichmentDevice | None:
+    """Map a runner's device label, like "CUDA" or "OpenVINO GPU.0,CPU"."""
+    if not isinstance(label, str) or not label:
+        return None
+
+    runtime, _, target = label.partition(" ")
+
+    if runtime == "OpenVINO":
+        # AUTO reports "(CPU)" while it warms up on the CPU
+        first = target.split(",")[0].split(".")[0].strip("() ").lower()
+        return OPENVINO_DEVICES.get(first, EnrichmentDevice.other)
+
+    return RUNTIME_DEVICES.get(label.lower(), EnrichmentDevice.other)
+
+
+def model_name(model: object) -> str | None:
+    """The model's config value as a string."""
+    if model is None:
+        return None
+
+    return str(getattr(model, "value", model))
+
+
+def semantic_model(model: object) -> SemanticSearchModel | None:
+    """A built-in Jina model, or genai for any GenAI provider name."""
+    name = model_name(model)
+
+    if name is None:
+        return None
+
+    if name in ("jinav1", "jinav2"):
+        return SemanticSearchModel(name)
+
+    return SemanticSearchModel.genai
+
+
+def transcription_model(model: object) -> TranscriptionModel | None:
+    """Whisper, or genai for any GenAI provider name."""
+    name = model_name(model)
+
+    if name is None:
+        return None
+
+    return TranscriptionModel.whisper if name == "whisper" else TranscriptionModel.genai
+
+
+def users() -> dict[UserRole, int]:
+    """Count users by role, with any custom role counted as custom."""
+    roles: Counter[UserRole] = Counter(
+        closed(UserRole, user.role, UserRole.custom) for user in User.select(User.role)
+    )
+    return histogram(roles)
+
+
+def collect(ctx: ReportContext) -> FeaturesSection:
+    """Report which enrichments and integrations are configured."""
+    config = ctx.config
+    devices = ctx.stats.get("embeddings", {}).get("devices", {})
+    cameras = [
+        camera
+        for name, camera in config.cameras.items()
+        if not name.startswith(REPLAY_CAMERA_PREFIX)
+    ]
+    providers: Counter[GenAIProviderEnum] = Counter(
+        genai.provider for genai in config.genai.values()
+    )
+    roles: Counter[GenAIRoleEnum] = Counter(
+        role for genai in config.genai.values() for role in genai.roles
+    )
+    custom = list(config.classification.custom.values())
+
+    return FeaturesSection(
+        face_recognition=EnrichmentUsage(
+            enabled=config.face_recognition.enabled,
+            model_size=config.face_recognition.model_size,
+            device=enrichment_device(devices.get("face_recognition")),
+        ),
+        lpr=EnrichmentUsage(
+            enabled=config.lpr.enabled,
+            model_size=config.lpr.model_size,
+            device=enrichment_device(devices.get("lpr")),
+        ),
+        semantic_search=SemanticSearchUsage(
+            enabled=config.semantic_search.enabled,
+            model=semantic_model(config.semantic_search.model),
+            model_size=config.semantic_search.model_size,
+            device=enrichment_device(devices.get("semantic_search")),
+            triggers=sum(len(camera.semantic_search.triggers) for camera in cameras),
+        ),
+        audio_transcription=TranscriptionUsage(
+            enabled=config.audio_transcription.enabled,
+            model=transcription_model(config.audio_transcription.model),
+            model_size=config.audio_transcription.model_size,
+        ),
+        genai=GenAIUsage(providers=histogram(providers), roles=histogram(roles)),
+        classification_models=ClassificationUsage(
+            state=sum(1 for model in custom if model.state_config is not None),
+            object=sum(1 for model in custom if model.object_config is not None),
+        ),
+        birdseye=BirdseyeUsage(
+            enabled=config.birdseye.enabled,
+            modes=list(config.birdseye.modes),
+            restream=config.birdseye.restream,
+        ),
+        mqtt=config.mqtt.enabled,
+        notifications=config.notifications.enabled,
+        auth=config.auth.enabled,
+        proxy_auth=config.proxy.header_map.user is not None,
+        tls=config.tls.enabled,
+        users=users(),
+        camera_groups=len(config.camera_groups),
+        profiles=len(config.profiles),
+        plus_api_key=config.plus_api.is_active(),
+    )

frigate/analytics/collectors/hardware.py

@@ -0,0 +1,114 @@
+"""Hardware section: CPU, memory, GPUs, decode and detection hardware, storage."""
+
+import os
+from collections import Counter
+from typing import Any
+
+import psutil
+
+from frigate.analytics.collectors.common import closed, histogram
+from frigate.analytics.context import ReportContext
+from frigate.analytics.schema import (
+    DecodeFamily,
+    GpuInfo,
+    GpuVendor,
+    HardwareKey,
+    HardwareSection,
+    StorageInfo,
+)
+from frigate.const import RECORD_DIR
+from frigate.detectors.hardware import hardware_prober
+from frigate.util.hwaccel import hwaccel_options
+
+DEVICE_TREE_MODEL = "/proc/device-tree/model"
+CPUINFO = "/proc/cpuinfo"
+
+
+def cpu_model() -> str:
+    """The board model on ARM boards, else the CPU's model name."""
+    try:
+        with open(DEVICE_TREE_MODEL) as f:
+            board = f.read().strip("\x00\n ")
+
+        if board:
+            return board[:64]
+    except OSError:
+        pass
+
+    try:
+        with open(CPUINFO) as f:
+            for line in f:
+                key, _, value = line.partition(":")
+
+                if key.strip() == "model name" and value.strip():
+                    return value.strip()[:64]
+    except OSError:
+        pass
+
+    return "unknown"
+
+
+def gpus(stats: dict[str, Any]) -> list[GpuInfo]:
+    """GPUs with a stats entry, by vendor and capped name."""
+    found: list[GpuInfo] = []
+
+    for name, entry in stats.get("gpu_usages", {}).items():
+        vendor = entry.get("vendor") if isinstance(entry, dict) else None
+        found.append(
+            GpuInfo(
+                vendor=closed(GpuVendor, vendor, GpuVendor.other),
+                name=str(name)[:64],
+            )
+        )
+
+    return found
+
+
+def decode_families() -> list[DecodeFamily]:
+    """Hardware decode families the host supports."""
+    _, available = hwaccel_options()
+    families = [
+        closed(DecodeFamily, family.key, DecodeFamily.other) for family in available
+    ]
+    return list(dict.fromkeys(families))
+
+
+def detection_hardware() -> dict[HardwareKey, int]:
+    """Detection accelerators found by the hardware probe, by unit count."""
+    units: Counter[HardwareKey] = Counter()
+
+    for found in hardware_prober.probe():
+        units[closed(HardwareKey, found.key, HardwareKey.other)] += found.count
+
+    return histogram(units)
+
+
+def storage(stats: dict[str, Any]) -> StorageInfo:
+    """Filesystem, size, and usage of the recordings volume.
+
+    Stats report sizes in MB.
+    """
+    entry = stats.get("service", {}).get("storage", {}).get(RECORD_DIR) or {}
+    total_mb = float(entry.get("total") or 0)
+    used_mb = float(entry.get("used") or 0)
+
+    return StorageInfo(
+        record_fs=str(entry.get("mount_type") or "unknown")[:16],
+        record_total_gb=round(total_mb / 1024),
+        record_used_pct=min(round(used_mb / total_mb * 100), 100)
+        if total_mb > 0
+        else 0,
+    )
+
+
+def collect(ctx: ReportContext) -> HardwareSection:
+    """Describe the host: CPU, memory, GPUs, decoders, detectors, storage."""
+    return HardwareSection(
+        cpu_model=cpu_model(),
+        cpu_cores=os.cpu_count() or 0,
+        memory_gb=round(psutil.virtual_memory().total / 2**30),
+        gpus=gpus(ctx.stats),
+        decode_families=decode_families(),
+        detection_hardware=detection_hardware(),
+        storage=storage(ctx.stats),
+    )

frigate/analytics/collectors/health.py

@@ -0,0 +1,63 @@
+"""Health section: uptime, CPU, enrichment speed, and notice counts."""
+
+from typing import Any
+
+from frigate.analytics.collectors.common import rate
+from frigate.analytics.context import ReportContext
+from frigate.analytics.schema import (
+    EnrichmentTiming,
+    HealthSection,
+    NoticeCounts,
+    NoticeKindKey,
+)
+
+TIMING_STATS = {
+    EnrichmentTiming.face: "face_recognition_speed",
+    EnrichmentTiming.lpr: "plate_recognition_speed",
+    EnrichmentTiming.plate_detection: "yolov9_plate_detection_speed",
+    EnrichmentTiming.image_embedding: "image_embedding_speed",
+    EnrichmentTiming.text_embedding: "text_embedding_speed",
+    EnrichmentTiming.review_description: "review_description_speed",
+    EnrichmentTiming.object_description: "object_description_speed",
+}
+REPORTABLE_KINDS = frozenset(key.value for key in NoticeKindKey)
+
+
+def notice_counts(notice_stats: list[dict[str, Any]]) -> dict[Any, NoticeCounts]:
+    """Counts since the install ID was created, per reportable kind."""
+    counts: dict[Any, NoticeCounts] = {}
+
+    for row in notice_stats:
+        if row["kind"] not in REPORTABLE_KINDS:
+            continue
+
+        occurrences = max(row["occurrences"] - row["reported_occurrences"], 0)
+        acknowledgements = max(
+            row["acknowledgements"] - row["reported_acknowledgements"], 0
+        )
+        mutes = max(row["mutes"] - row["reported_mutes"], 0)
+
+        if occurrences or acknowledgements or mutes:
+            counts[NoticeKindKey(row["kind"])] = NoticeCounts(
+                occurrences=occurrences, acknowledgements=acknowledgements, mutes=mutes
+            )
+
+    return counts
+
+
+def collect(ctx: ReportContext) -> HealthSection:
+    """Read health figures from the latest stats and notice counts."""
+    service = ctx.stats.get("service", {})
+    embeddings = ctx.stats.get("embeddings", {})
+    cpu = ctx.stats.get("cpu_usages", {}).get("frigate.full_system", {}).get("cpu")
+    timings = {
+        timing: rate(embeddings.get(key)) for timing, key in TIMING_STATS.items()
+    }
+
+    return HealthSection(
+        uptime_hours=int(rate(service.get("uptime")) // 3600),
+        cpu_percent=min(round(rate(cpu)), 100),
+        enrichment_ms={timing: value for timing, value in timings.items() if value > 0},
+        retention_unmet=bool(service.get("retention_unmet", False)),
+        notices=notice_counts(ctx.notice_stats),
+    )

frigate/analytics/collectors/install.py

@@ -0,0 +1,87 @@
+"""Install section: version, image variant, install type, platform."""
+
+import os
+import platform
+import re
+
+from frigate.analytics.collectors.common import closed
+from frigate.analytics.context import ReportContext
+from frigate.analytics.schema import (
+    Arch,
+    FfmpegSource,
+    ImageVariant,
+    InstallSection,
+    InstallType,
+)
+from frigate.const import CONFIG_DIR, DEFAULT_FFMPEG_VERSION, INCLUDED_FFMPEG_VERSIONS
+from frigate.util.config import is_valid_ffmpeg_path
+from frigate.version import VERSION
+
+KERNEL_PATTERN = re.compile(r"^(\d{1,3})\.(\d{1,3})")
+
+
+def image_variant(value: str | None) -> ImageVariant:
+    """The published image from the build-time FRIGATE_IMAGE_VARIANT, dev when unset."""
+    if not value:
+        return ImageVariant.dev
+
+    return closed(ImageVariant, value, ImageVariant.other)
+
+
+def install_type() -> InstallType:
+    """How Frigate runs; the add-on is a container too, so it's checked first."""
+    if os.path.isfile("/data/options.json"):
+        return InstallType.ha_addon
+
+    if os.environ.get("KUBERNETES_SERVICE_HOST"):
+        return InstallType.kubernetes
+
+    if os.path.exists("/run/.containerenv"):
+        return InstallType.podman
+
+    if os.path.exists("/.dockerenv"):
+        return InstallType.docker
+
+    return InstallType.unknown
+
+
+def arch(machine: str) -> Arch:
+    """The CPU architecture for a platform.machine() value."""
+    match machine.lower():
+        case "x86_64" | "amd64":
+            return Arch.x86_64
+        case "aarch64" | "arm64":
+            return Arch.aarch64
+        case _:
+            return Arch.other
+
+
+def kernel(release: str) -> str:
+    """The major.minor of a kernel release string, or unknown."""
+    match = KERNEL_PATTERN.match(release)
+    return f"{match.group(1)}.{match.group(2)}" if match else "unknown"
+
+
+def ffmpeg_source(path: str) -> FfmpegSource:
+    """Classify the configured ffmpeg.path, applying resolve_ffmpeg_path's alias fallbacks."""
+    if path.startswith("/") and is_valid_ffmpeg_path(path):
+        return FfmpegSource.custom
+
+    if path != DEFAULT_FFMPEG_VERSION and path in INCLUDED_FFMPEG_VERSIONS:
+        return FfmpegSource.bundled
+
+    return FfmpegSource.default
+
+
+def collect(ctx: ReportContext) -> InstallSection:
+    """Describe the Frigate version, image, install method, and platform."""
+    return InstallSection(
+        version=VERSION[:32],
+        image_variant=image_variant(os.environ.get("FRIGATE_IMAGE_VARIANT")),
+        install_type=install_type(),
+        arch=arch(platform.machine()),
+        kernel=kernel(platform.release()),
+        run_as_root=os.geteuid() == 0,
+        custom_go2rtc=os.access(os.path.join(CONFIG_DIR, "go2rtc"), os.X_OK),
+        ffmpeg=ffmpeg_source(ctx.config.ffmpeg.path),
+    )

frigate/analytics/context.py

@@ -0,0 +1,13 @@
+"""What the collectors read, gathered once per report."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from frigate.config import FrigateConfig
+
+
+@dataclass(frozen=True)
+class ReportContext:
+    config: FrigateConfig
+    stats: dict[str, Any]
+    notice_stats: list[dict[str, Any]] = field(default_factory=list)

frigate/analytics/report.py

@@ -0,0 +1,91 @@
+"""Build a report from the section collectors."""
+
+import logging
+import time
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from frigate.analytics.collectors import (
+    cameras,
+    detection,
+    features,
+    hardware,
+    health,
+    install,
+)
+from frigate.analytics.context import ReportContext
+from frigate.analytics.schema import SCHEMA_VERSION, AnalyticsReport
+from frigate.analytics.state import load_state
+from frigate.config import FrigateConfig
+
+if TYPE_CHECKING:
+    from frigate.notices.registry import NoticeRegistry
+    from frigate.stats.emitter import StatsEmitter
+
+logger = logging.getLogger(__name__)
+
+COLLECTORS: dict[str, Callable[[ReportContext], BaseModel | None]] = {
+    "install": install.collect,
+    "hardware": hardware.collect,
+    "detection": detection.collect,
+    "cameras": cameras.collect,
+    "features": features.collect,
+    "health": health.collect,
+}
+
+# shown in the preview until the first report creates a real ID
+PREVIEW_INSTALL_ID = "0" * 32
+
+
+def build_report(
+    ctx: ReportContext, install_id: str, sent_at: int | None = None
+) -> AnalyticsReport:
+    """Run every collector; one that fails sends its section as null."""
+    sections: dict[str, Any] = {}
+
+    for name, collect in COLLECTORS.items():
+        try:
+            sections[name] = collect(ctx)
+        except Exception:
+            # a collector bug must cost one section, never the whole report
+            logger.debug("Analytics %s section failed", name, exc_info=True)
+            sections[name] = None
+
+    return AnalyticsReport.model_validate(
+        {
+            "schema_version": SCHEMA_VERSION,
+            "install_id": install_id,
+            "report_id": str(uuid4()),
+            "sent_at": int(time.time()) if sent_at is None else sent_at,
+            **sections,
+        }
+    )
+
+
+def gather_context(
+    config: FrigateConfig,
+    stats_emitter: "StatsEmitter | None",
+    notice_registry: "NoticeRegistry | None",
+) -> ReportContext:
+    """Snapshot the config, latest stats, and notice counts for one report."""
+    return ReportContext(
+        config=config,
+        stats=stats_emitter.get_latest_stats() if stats_emitter is not None else {},
+        notice_stats=notice_registry.stats() if notice_registry is not None else [],
+    )
+
+
+def preview_report(
+    config: FrigateConfig,
+    stats_emitter: "StatsEmitter | None",
+    notice_registry: "NoticeRegistry | None",
+) -> AnalyticsReport:
+    """The report the next send would carry, without sending it."""
+    state = load_state()
+
+    # an opt-in resets the baseline, so before one there are no notices to show
+    ctx = gather_context(config, stats_emitter, notice_registry if state else None)
+    return build_report(ctx, state.install_id if state else PREVIEW_INSTALL_ID)

frigate/analytics/reporter.py

@@ -0,0 +1,218 @@
+"""Send one analytics report a day while the admin has opted in."""
+
+import logging
+import random
+import threading
+import time
+from collections.abc import Callable
+from multiprocessing.synchronize import Event as MpEvent
+from typing import TYPE_CHECKING
+
+from pydantic import ValidationError
+from ruamel.yaml import YAML
+from ruamel.yaml.error import YAMLError
+
+from frigate.analytics.report import build_report, gather_context
+from frigate.analytics.state import (
+    STATE_PATH,
+    AnalyticsState,
+    delete_state,
+    load_state,
+    new_state,
+    save_state,
+)
+from frigate.analytics.transport import SendOutcome, send_report
+from frigate.config import FrigateConfig
+from frigate.config.holder import ConfigHolder
+from frigate.config.telemetry import TelemetryConfig
+from frigate.const import ANALYTICS_URL
+from frigate.notices import raise_notice, resolve_notice
+from frigate.util.config import find_config_file
+
+if TYPE_CHECKING:
+    from frigate.notices.registry import NoticeRegistry
+    from frigate.stats.emitter import StatsEmitter
+
+logger = logging.getLogger(__name__)
+
+WAKE_S = 10 * 60
+INTERVAL_S = 24 * 60 * 60
+JITTER_S = 60 * 60
+FIRST_DELAY_S = (15 * 60, 45 * 60)
+PROMPT_KIND = "analytics_prompt"
+
+
+def saved_consent(path: str) -> bool | None:
+    """telemetry.analytics as saved in the config file, or None if unreadable."""
+    try:
+        with open(path) as f:
+            raw = YAML(typ="safe").load(f)
+    except (OSError, ValueError, YAMLError):
+        return None
+
+    if not isinstance(raw, dict):
+        return None
+
+    # the live config's model, so yes, on, and 1 read as consent there too
+    try:
+        return TelemetryConfig.model_validate(raw.get("telemetry") or {}).analytics
+    except ValidationError:
+        return None
+
+
+class AnalyticsReporter(threading.Thread):
+    """Follows the live config, so a settings save needs no restart."""
+
+    def __init__(
+        self,
+        config_holder: ConfigHolder,
+        stats_emitter: "StatsEmitter",
+        notice_registry: "NoticeRegistry",
+        stop_event: MpEvent | threading.Event,
+        *,
+        state_path: str = STATE_PATH,
+        config_path: str | None = None,
+        url: str = ANALYTICS_URL,
+        send: Callable[[str, str], SendOutcome] = send_report,
+        clock: Callable[[], float] = time.time,
+        rng: random.Random | None = None,
+    ) -> None:
+        super().__init__(name="analytics_reporter", daemon=True)
+        self.config_holder = config_holder
+        self.stats_emitter = stats_emitter
+        self.notice_registry = notice_registry
+        self.stop_event = stop_event
+        self.state_path = state_path
+        self.config_path = config_path or find_config_file()
+        self.url = url
+        self.send = send
+        self.clock = clock
+        self.rng = rng or random.Random()
+        self.first_due = clock() + self.rng.uniform(*FIRST_DELAY_S)
+        self.interval = self._next_interval()
+        self.opted_in: bool | None = None
+        self.warned_unwritable = False
+        # a settings save runs on an API thread while a wake may be mid-attempt
+        self._lock = threading.Lock()
+        config_holder.subscribe(self._on_config)
+
+    def _next_interval(self) -> float:
+        return INTERVAL_S + self.rng.uniform(-JITTER_S, JITTER_S)
+
+    def run(self) -> None:
+        """Tick every wake until stopped; a failed tick never ends the thread."""
+        while True:
+            try:
+                self.tick()
+            except Exception:
+                logger.exception("Analytics reporter failed")
+
+            if self.stop_event.wait(WAKE_S):
+                break
+
+    def _on_config(self, config: FrigateConfig) -> None:
+        # a save can turn sharing off and back on between two wakes, so an
+        # opt-out is handled when it's saved rather than at the next wake
+        with self._lock:
+            if not config.safe_mode:
+                self._apply_consent(config.telemetry.analytics)
+
+    def _apply_consent(self, opted_in: bool) -> None:
+        # called with the lock held
+        if opted_in == self.opted_in:
+            return
+
+        self.opted_in = opted_in
+
+        if opted_in:
+            resolve_notice(PROMPT_KIND)
+
+            # the opt-in sets the notice baseline, so only notices raised with
+            # consent are counted; tick() retries a failed write
+            if load_state(self.state_path) is None:
+                save_state(self._new_identity(), self.state_path)
+        else:
+            raise_notice(PROMPT_KIND)
+            delete_state(self.state_path)
+
+    def _new_identity(self) -> AnalyticsState:
+        # called with the lock held; the baseline resets before the state file
+        # names the new ID, so a failed write only means another reset
+        self.notice_registry.reset_analytics_baseline()
+        return new_state()
+
+    def tick(self) -> None:
+        """Apply consent and send a report when one is due."""
+        with self._lock:
+            config = self.config_holder.config
+
+            # safe mode parses a default config where analytics reads as off,
+            # and handling that as an opt-out would delete the install ID
+            if config.safe_mode:
+                return
+
+            self._apply_consent(config.telemetry.analytics)
+
+            if not config.telemetry.analytics:
+                return
+
+            now = self.clock()
+
+            if now < self.first_due:
+                return
+
+            state = load_state(self.state_path)
+
+            if state is not None and not self._due(state.last_attempt_at, now):
+                return
+
+            # a YAML editor save or a hand edit reaches the live config only on
+            # restart, so an opt-out saved that way is read from the file
+            if saved_consent(self.config_path) is False:
+                delete_state(self.state_path)
+                return
+
+            state = AnalyticsState(
+                (state or self._new_identity()).install_id, last_attempt_at=now
+            )
+
+            # saved before sending, so a failing endpoint or a crash mid-send
+            # still waits a full interval; without saved state every boot would
+            # send under a new install ID
+            if not save_state(state, self.state_path):
+                if not self.warned_unwritable:
+                    logger.warning(
+                        "Analytics is on, but %s isn't writable, so no report is sent",
+                        self.state_path,
+                    )
+                    self.warned_unwritable = True
+
+                return
+
+            self.interval = self._next_interval()
+
+        # the lock stays free during the request, so a save never waits on it
+        self._send(state.install_id, now)
+
+    def _due(self, last_attempt_at: float, now: float) -> bool:
+        # a last attempt stamped in the future came from a wrong clock
+        return (
+            now >= last_attempt_at + self.interval or last_attempt_at > now + INTERVAL_S
+        )
+
+    def _send(self, install_id: str, now: float) -> None:
+        ctx = gather_context(
+            self.config_holder.config, self.stats_emitter, self.notice_registry
+        )
+        report = build_report(ctx, install_id, sent_at=int(now))
+        body = report.model_dump_json()
+
+        # consent can be withdrawn while the report builds
+        if not self.config_holder.config.telemetry.analytics:
+            return
+
+        if self.send(self.url, body) is not SendOutcome.accepted:
+            return
+
+        logger.info("Sent the daily analytics report")
+        logger.debug("Analytics report: %s", body)

frigate/analytics/schema.py

@@ -0,0 +1,429 @@
+"""Models for the analytics report, the contract with the ingest endpoint.
+
+Every field carries a description and an x-public flag, and no field accepts
+user-entered text, so a report can't carry camera names or other free text.
+"""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from frigate.config.camera.birdseye import BirdseyeModeEnum
+from frigate.config.camera.camera import CameraTypeEnum
+from frigate.config.camera.genai import GenAIProviderEnum, GenAIRoleEnum
+from frigate.config.classification import ModelSizeEnum
+from frigate.detectors.detector_config import ModelTypeEnum
+from frigate.detectors.detector_types import DetectorTypeEnum
+from frigate.ffmpeg_presets import PRESETS_HW_ACCEL_DECODE, PRESETS_INPUT
+from frigate.notices.types import NOTICE_KINDS
+
+SCHEMA_VERSION = 1
+
+
+class ImageVariant(StrEnum):
+    standard = "standard"
+    rpi = "rpi"
+    tensorrt = "tensorrt"
+    tensorrt_jp6 = "tensorrt-jp6"
+    rocm = "rocm"
+    rk = "rk"
+    synaptics = "synaptics"
+    dev = "dev"
+    other = "other"
+
+
+class InstallType(StrEnum):
+    ha_addon = "ha_addon"
+    docker = "docker"
+    podman = "podman"
+    kubernetes = "kubernetes"
+    unknown = "unknown"
+
+
+class Arch(StrEnum):
+    x86_64 = "x86_64"
+    aarch64 = "aarch64"
+    other = "other"
+
+
+class FfmpegSource(StrEnum):
+    default = "default"
+    bundled = "bundled"
+    custom = "custom"
+
+
+class GpuVendor(StrEnum):
+    intel = "intel"
+    amd = "amd"
+    nvidia = "nvidia"
+    rockchip = "rockchip"
+    rpi = "rpi"
+    apple_silicon = "apple-silicon"
+    other = "other"
+
+
+class DecodeFamily(StrEnum):
+    nvidia = "nvidia"
+    vaapi = "vaapi"
+    rkmpp = "rkmpp"
+    intel_qsv = "intel-qsv"
+    jetson = "jetson"
+    rpi = "rpi"
+    apple_silicon = "apple-silicon"
+    other = "other"
+
+
+class HardwareKey(StrEnum):
+    edgetpu_pci = "edgetpu:pci"
+    edgetpu_usb = "edgetpu:usb"
+    openvino_gpu = "openvino:GPU"
+    openvino_npu = "openvino:NPU"
+    onnx_amd = "onnx:amd"
+    onnx_nvidia = "onnx:nvidia"
+    onnx_lighter = "onnx:lighter"
+    tensorrt = "tensorrt"
+    hailo = "hailo"
+    memryx = "memryx"
+    deepx = "deepx"
+    rknn = "rknn"
+    axengine = "axengine"
+    axelera = "axelera"
+    synaptics = "synaptics"
+    cpu = "cpu"
+    other = "other"
+
+
+class ModelSource(StrEnum):
+    default = "default"
+    plus = "plus"
+    custom = "custom"
+
+
+class HeightBucket(StrEnum):
+    le_360 = "le_360"
+    h480 = "480"
+    h720 = "720"
+    h1080 = "1080"
+    h1440 = "1440"
+    ge_2160 = "ge_2160"
+
+
+class FpsBucket(StrEnum):
+    le_5 = "le_5"
+    f6_10 = "6_10"
+    gt_10 = "gt_10"
+
+
+class RetainBucket(StrEnum):
+    zero = "0"
+    d1_7 = "1_7"
+    d8_30 = "8_30"
+    gt_30 = "gt_30"
+
+
+class ConnectionQuality(StrEnum):
+    excellent = "excellent"
+    fair = "fair"
+    poor = "poor"
+    unusable = "unusable"
+
+
+class EnrichmentDevice(StrEnum):
+    cpu = "cpu"
+    cuda = "cuda"
+    tensorrt = "tensorrt"
+    migraphx = "migraphx"
+    openvino_cpu = "openvino_cpu"
+    openvino_gpu = "openvino_gpu"
+    openvino_npu = "openvino_npu"
+    other = "other"
+
+
+class SemanticSearchModel(StrEnum):
+    jinav1 = "jinav1"
+    jinav2 = "jinav2"
+    genai = "genai"
+
+
+class TranscriptionModel(StrEnum):
+    whisper = "whisper"
+    genai = "genai"
+
+
+class UserRole(StrEnum):
+    admin = "admin"
+    viewer = "viewer"
+    custom = "custom"
+
+
+class EnrichmentTiming(StrEnum):
+    face = "face"
+    lpr = "lpr"
+    plate_detection = "plate_detection"
+    image_embedding = "image_embedding"
+    text_embedding = "text_embedding"
+    review_description = "review_description"
+    object_description = "object_description"
+
+
+def _preset_keys(presets: dict[str, Any]) -> dict[str, str]:
+    keys = [name.removeprefix("preset-") for name in presets]
+    return {key: key for key in [*keys, "custom", "none"]}
+
+
+# built from the registries they mirror, so a new preset or notice kind reaches
+# the schema through generate_analytics_schema.py instead of a hand edit
+HwaccelKey = StrEnum("HwaccelKey", _preset_keys(PRESETS_HW_ACCEL_DECODE))  # type: ignore[misc]
+InputPresetKey = StrEnum("InputPresetKey", _preset_keys(PRESETS_INPUT))  # type: ignore[misc]
+NoticeKindKey = StrEnum(  # type: ignore[misc]
+    "NoticeKindKey",
+    {key: key for key, kind in NOTICE_KINDS.items() if kind.reportable},
+)
+
+
+class AnalyticsModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+def metric(description: str, *, public: bool = True, **kwargs: Any) -> Any:
+    """Declare a report field; the description and flag land in the schema."""
+    return Field(
+        description=description, json_schema_extra={"x-public": public}, **kwargs
+    )
+
+
+def count(description: str) -> Any:
+    """Declare a non-negative count field."""
+    return metric(description, ge=0)
+
+
+class InstallSection(AnalyticsModel):
+    version: str = metric("Frigate version string", max_length=32)
+    image_variant: ImageVariant = metric("Published image the install runs")
+    install_type: InstallType = metric("How Frigate is installed")
+    arch: Arch = metric("CPU architecture")
+    kernel: str = metric(
+        "Host kernel as major.minor", pattern=r"^(\d{1,3}\.\d{1,3}|unknown)$"
+    )
+    run_as_root: bool = metric("Whether the main process runs as root")
+    custom_go2rtc: bool = metric("Whether an executable /config/go2rtc build exists")
+    ffmpeg: FfmpegSource = metric(
+        "Configured global ffmpeg.path: the default build, another bundled version, or a custom path"
+    )
+
+
+class GpuInfo(AnalyticsModel):
+    vendor: GpuVendor = metric("GPU vendor")
+    name: str = metric("GPU name as the hardware reports it", max_length=64)
+
+
+class StorageInfo(AnalyticsModel):
+    record_fs: str = metric("Filesystem of the recordings volume", max_length=16)
+    record_total_gb: int = count("Size of the recordings volume in GB")
+    record_used_pct: int = metric(
+        "Percent of the recordings volume in use", ge=0, le=100
+    )
+
+
+class HardwareSection(AnalyticsModel):
+    cpu_model: str = metric(
+        "CPU or board model as the hardware reports it", max_length=64
+    )
+    cpu_cores: int = count("Logical CPU count")
+    memory_gb: int = count("Total memory in GB")
+    gpus: list[GpuInfo] = metric("GPUs the stats collector found")
+    decode_families: list[DecodeFamily] = metric(
+        "Hardware decode families this system can use"
+    )
+    detection_hardware: dict[HardwareKey, int] = metric(
+        "Detection hardware found, as unit counts by kind"
+    )
+    storage: StorageInfo = metric("Recordings storage")
+
+
+class DetectionModel(AnalyticsModel):
+    default: bool = metric("Whether the model serves cameras that set no scene")
+    detector: DetectorTypeEnum = metric("Detector type the model runs on")
+    devices: int = count("Devices the model runs on")
+    model_type: ModelTypeEnum = metric("Model architecture")
+    input: str = metric("Model input size as WxH", pattern=r"^\d{1,5}x\d{1,5}$")
+    source: ModelSource = metric("Where the model came from", public=False)
+    inference_ms: float | None = metric(
+        "Mean inference time across the model's detector processes, null before the first stats",
+        ge=0,
+    )
+
+
+class DetectionSection(AnalyticsModel):
+    models: list[DetectionModel] = metric("Detection models")
+    detection_fps: float = metric("Detections per second across cameras", ge=0)
+    skipped_fps: float = metric("Frames per second skipped across cameras", ge=0)
+
+
+class RetainDays(AnalyticsModel):
+    continuous: dict[RetainBucket, int] = metric(
+        "Recording cameras by continuous retention in days"
+    )
+    motion: dict[RetainBucket, int] = metric(
+        "Recording cameras by motion retention in days"
+    )
+    alerts: dict[RetainBucket, int] = metric(
+        "Recording cameras by alert retention in days"
+    )
+    detections: dict[RetainBucket, int] = metric(
+        "Recording cameras by detection retention in days"
+    )
+
+
+class CamerasSection(AnalyticsModel):
+    total: int = count("Configured cameras")
+    enabled: int = count(
+        "Cameras enabled in config; every count below covers only these"
+    )
+    types: dict[CameraTypeEnum, int] = metric("Cameras by type")
+    detect_height: dict[HeightBucket, int] = metric(
+        "Cameras by detect resolution height"
+    )
+    detect_fps: dict[FpsBucket, int] = metric("Cameras by detect fps")
+    hwaccel: dict[HwaccelKey, int] = metric(
+        "Cameras by the resolved hwaccel preset of the detect input"
+    )
+    input_preset: dict[InputPresetKey, int] = metric(
+        "Cameras by the input preset of the detect input"
+    )
+    go2rtc_restream: int = count("Cameras with an input from the go2rtc restream")
+    separate_detect_stream: int = count(
+        "Cameras whose detect input differs from their record input"
+    )
+    detect: int = count("Cameras with detection on")
+    record: int = count("Cameras with recording on")
+    sub_stream_record: int = count("Cameras with sub stream recording on")
+    snapshots: int = count("Cameras with snapshots on")
+    audio: int = count("Cameras with audio detection on")
+    audio_transcription: int = count(
+        "Cameras with audio detection and transcription on"
+    )
+    birdseye: int = count("Cameras in birdseye")
+    onvif: int = count("Cameras with an ONVIF host")
+    autotracking: int = count("Cameras with PTZ autotracking on")
+    face_recognition: int = count("Cameras with face recognition on")
+    lpr: int = count("Cameras with license plate recognition on")
+    review_genai: int = count("Cameras with GenAI review summaries on")
+    object_genai: int = count("Cameras with GenAI object descriptions on")
+    notifications: int = count("Cameras with notifications on")
+    zones: int = count("Zones across cameras")
+    cameras_with_zones: int = count("Cameras with at least one zone")
+    motion_masks: int = count("Motion masks across cameras")
+    object_masks: int = count("Object masks across cameras")
+    connection_quality: dict[ConnectionQuality, int] = metric(
+        "Cameras by connection quality at send time"
+    )
+    retain_days: RetainDays = metric("Recording retention")
+
+
+class EnrichmentUsage(AnalyticsModel):
+    enabled: bool = metric("Whether the enrichment is on")
+    model_size: ModelSizeEnum = metric("Configured model size")
+    device: EnrichmentDevice | None = metric(
+        "Device the model loaded on, null when it isn't loaded"
+    )
+
+
+class SemanticSearchUsage(AnalyticsModel):
+    enabled: bool = metric("Whether semantic search is on")
+    model: SemanticSearchModel | None = metric(
+        "Embedding model, genai for a GenAI provider"
+    )
+    model_size: ModelSizeEnum = metric("Configured model size")
+    device: EnrichmentDevice | None = metric(
+        "Device the model loaded on, null when it isn't loaded"
+    )
+    triggers: int = count("Semantic search triggers across cameras")
+
+
+class TranscriptionUsage(AnalyticsModel):
+    enabled: bool = metric("Whether audio transcription is on")
+    model: TranscriptionModel | None = metric(
+        "Transcription model, genai for a GenAI provider"
+    )
+    model_size: ModelSizeEnum = metric("Configured model size")
+
+
+class GenAIUsage(AnalyticsModel):
+    providers: dict[GenAIProviderEnum, int] = metric(
+        "Configured GenAI providers by type"
+    )
+    roles: dict[GenAIRoleEnum, int] = metric("Configured GenAI providers by role")
+
+
+class ClassificationUsage(AnalyticsModel):
+    state: int = count("Custom state classification models")
+    object: int = count("Custom object classification models")
+
+
+class BirdseyeUsage(AnalyticsModel):
+    enabled: bool = metric("Whether birdseye is on")
+    modes: list[BirdseyeModeEnum] = metric("Birdseye modes")
+    restream: bool = metric("Whether birdseye is restreamed")
+
+
+class FeaturesSection(AnalyticsModel):
+    face_recognition: EnrichmentUsage = metric("Face recognition")
+    lpr: EnrichmentUsage = metric("License plate recognition")
+    semantic_search: SemanticSearchUsage = metric("Semantic search")
+    audio_transcription: TranscriptionUsage = metric("Audio transcription")
+    genai: GenAIUsage = metric("Generative AI providers")
+    classification_models: ClassificationUsage = metric("Custom classification models")
+    birdseye: BirdseyeUsage = metric("Birdseye")
+    mqtt: bool = metric("Whether MQTT is on")
+    notifications: bool = metric("Whether web push notifications are on")
+    auth: bool = metric("Whether authentication is on")
+    proxy_auth: bool = metric("Whether a proxy supplies the user header")
+    tls: bool = metric("Whether TLS is on")
+    users: dict[UserRole, int] = metric("Users by role")
+    camera_groups: int = count("Camera groups")
+    profiles: int = count("Profiles")
+    plus_api_key: bool = metric("Whether a Frigate+ API key is set", public=False)
+
+
+class NoticeCounts(AnalyticsModel):
+    occurrences: int = count("Occurrences since the install ID was created")
+    acknowledgements: int = count("Acknowledgements since the install ID was created")
+    mutes: int = count("Mutes since the install ID was created")
+
+
+class HealthSection(AnalyticsModel):
+    uptime_hours: int = count("Hours since Frigate started")
+    cpu_percent: int = metric("System CPU use at send time", ge=0, le=100)
+    enrichment_ms: dict[EnrichmentTiming, float] = metric(
+        "Mean enrichment inference times in milliseconds"
+    )
+    retention_unmet: bool = metric(
+        "Whether storage can't keep the configured retention"
+    )
+    notices: dict[NoticeKindKey, NoticeCounts] = metric(
+        "Cumulative notice counts by kind since the install ID was created",
+        public=False,
+    )
+
+
+class AnalyticsReport(AnalyticsModel):
+    schema_version: int = metric("Report format version", ge=1)
+    install_id: str = metric(
+        "Random install identifier", public=False, pattern=r"^[0-9a-f]{32}$"
+    )
+    report_id: str = metric(
+        "Random identifier of this report",
+        public=False,
+        pattern=r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    )
+    sent_at: int = count("Unix time the report was built")
+    install: InstallSection | None = metric("Install, null if its collector failed")
+    hardware: HardwareSection | None = metric("Hardware, null if its collector failed")
+    detection: DetectionSection | None = metric(
+        "Object detection, null if its collector failed"
+    )
+    cameras: CamerasSection | None = metric("Cameras, null if its collector failed")
+    features: FeaturesSection | None = metric("Features, null if its collector failed")
+    health: HealthSection | None = metric("Health, null if its collector failed")

frigate/analytics/state.py

@@ -0,0 +1,86 @@
+"""The install's analytics identity and last attempt time, kept under /config."""
+
+import json
+import logging
+import os
+import re
+from dataclasses import dataclass
+from uuid import uuid4
+
+from frigate.const import CONFIG_DIR
+
+logger = logging.getLogger(__name__)
+
+STATE_PATH = os.path.join(CONFIG_DIR, ".analytics.json")
+INSTALL_ID_PATTERN = re.compile(r"[0-9a-f]{32}")
+
+
+@dataclass(frozen=True)
+class AnalyticsState:
+    install_id: str
+    last_attempt_at: float
+
+
+def new_state() -> AnalyticsState:
+    """A fresh install ID that has never attempted a report."""
+    return AnalyticsState(install_id=uuid4().hex, last_attempt_at=0.0)
+
+
+def load_state(path: str = STATE_PATH) -> AnalyticsState | None:
+    """The saved state, or None when the file is missing or unusable."""
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError):
+        logger.debug("Ignoring unreadable analytics state at %s", path)
+        return None
+
+    if not isinstance(data, dict):
+        return None
+
+    install_id = data.get("install_id")
+    last_attempt_at = data.get("last_attempt_at")
+
+    if (
+        not isinstance(install_id, str)
+        or not INSTALL_ID_PATTERN.fullmatch(install_id)
+        or isinstance(last_attempt_at, bool)
+        or not isinstance(last_attempt_at, int | float)
+    ):
+        logger.debug("Ignoring invalid analytics state at %s", path)
+        return None
+
+    return AnalyticsState(install_id=install_id, last_attempt_at=float(last_attempt_at))
+
+
+def save_state(state: AnalyticsState, path: str = STATE_PATH) -> bool:
+    """Write the state atomically, returning False when it can't be written."""
+    temp_path = f"{path}.tmp"
+
+    try:
+        with open(temp_path, "w") as f:
+            json.dump(
+                {
+                    "install_id": state.install_id,
+                    "last_attempt_at": state.last_attempt_at,
+                },
+                f,
+            )
+
+        os.replace(temp_path, path)
+    except OSError:
+        return False
+
+    return True
+
+
+def delete_state(path: str = STATE_PATH) -> None:
+    """Forget the install ID, so a later opt-in starts a fresh identity."""
+    try:
+        os.remove(path)
+    except FileNotFoundError:
+        pass
+    except OSError:
+        logger.warning("Unable to delete analytics state at %s", path)

frigate/analytics/transport.py

@@ -0,0 +1,54 @@
+"""POST a report to the ingest endpoint."""
+
+import logging
+from enum import Enum
+
+import requests
+
+from frigate.version import VERSION
+
+logger = logging.getLogger(__name__)
+
+TIMEOUT_S = 30
+
+
+class SendOutcome(Enum):
+    accepted = "accepted"
+    rejected = "rejected"
+    rate_limited = "rate_limited"
+    failed = "failed"
+
+
+def send_report(url: str, body: str) -> SendOutcome:
+    """Send one report. Never raises; the outcome says what happened."""
+    try:
+        # a redirect would turn the POST into a GET, so it counts as a failure
+        response = requests.post(
+            url,
+            data=body.encode(),
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": f"Frigate/{VERSION}",
+            },
+            timeout=TIMEOUT_S,
+            allow_redirects=False,
+        )
+    except requests.RequestException as err:
+        logger.debug("Unable to send the analytics report: %s", err)
+        return SendOutcome.failed
+
+    status = response.status_code
+
+    if 200 <= status < 300:
+        return SendOutcome.accepted
+
+    if status == 400:
+        logger.debug("The analytics report was rejected: %s", response.text[:200])
+        return SendOutcome.rejected
+
+    if status == 429:
+        logger.debug("The analytics endpoint is rate limiting this install")
+        return SendOutcome.rate_limited
+
+    logger.debug("The analytics endpoint returned %s", status)
+    return SendOutcome.failed

frigate/api/analytics.py

@@ -0,0 +1,25 @@
+"""Analytics APIs."""
+
+import logging
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import JSONResponse
+
+from frigate.analytics.report import preview_report
+from frigate.api.auth import require_role
+from frigate.api.defs.tags import Tags
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=[Tags.analytics])
+
+
+@router.get("/analytics/preview", dependencies=[Depends(require_role(["admin"]))])
+def get_analytics_preview(request: Request) -> JSONResponse:
+    """Get the analytics report Frigate would send next, without sending it."""
+    report = preview_report(
+        request.app.frigate_config,
+        request.app.stats_emitter,
+        request.app.notice_registry,
+    )
+    return JSONResponse(content=report.model_dump(mode="json"))

frigate/api/app.py

@@ -54,7 +54,7 @@ from frigate.jobs.media_sync import (
     start_media_sync_job,
 )
 from frigate.models import Event, Timeline
-from frigate.plus import load_plus_model_info
+from frigate.plus import PlusKeyStatus, load_plus_model_info
 from frigate.stats.prometheus import get_metrics, update_metrics
 from frigate.types import JobStatusTypesEnum
 from frigate.util.builtin import (
@@ -81,6 +81,7 @@ from frigate.util.object_names import get_categorized_object_names
 from frigate.util.schema import get_config_schema
 from frigate.util.services import (
     Go2rtcStreamIssue,
+    find_restricted_go2rtc_exec_changes,
     find_restricted_go2rtc_stream_changes,
     get_nvidia_driver_info,
     process_logs,
@@ -576,26 +577,26 @@ def config_raw():
         )
 
 
-def _go2rtc_streams(raw_config: str) -> Any:
-    """Load go2rtc.streams with the same loader Frigate and go2rtc startup use.
+def _go2rtc_config(raw_config: str) -> dict[str, Any]:
+    """Load the go2rtc section with the same loader Frigate and go2rtc startup use.
 
     Raises ruamel.yaml.YAMLError when the config cannot be parsed.
     """
     loaded = ruamel.yaml.YAML().load(raw_config)
     go2rtc = loaded.get("go2rtc") if isinstance(loaded, dict) else None
-    return go2rtc.get("streams") if isinstance(go2rtc, dict) else None
+    return go2rtc if isinstance(go2rtc, dict) else {}
 
 
-def _restricted_go2rtc_streams_response(
+def _restricted_go2rtc_response(
     old_raw_config: str, new_raw_config: str
 ) -> JSONResponse | None:
-    """Reject config changes that add restricted go2rtc stream sources.
+    """Reject config changes that add restricted go2rtc sources or options.
 
     The same sources are rejected by PUT /go2rtc/streams, and go2rtc would
     otherwise load them from the saved config on the next restart.
     """
     try:
-        new_streams = _go2rtc_streams(new_raw_config)
+        new_go2rtc = _go2rtc_config(new_raw_config)
     except ruamel.yaml.YAMLError:
         logger.warning("Rejected config change that could not be parsed")
         return JSONResponse(
@@ -604,16 +605,21 @@ def _restricted_go2rtc_streams_response(
         )
 
     try:
-        old_streams = _go2rtc_streams(old_raw_config)
+        old_go2rtc = _go2rtc_config(old_raw_config)
     except ruamel.yaml.YAMLError:
         # with no readable saved config, every source is treated as new
-        old_streams = None
+        old_go2rtc = {}
 
-    issues = find_restricted_go2rtc_stream_changes(old_streams, new_streams)
-    if not issues:
+    issues = find_restricted_go2rtc_stream_changes(
+        old_go2rtc.get("streams"), new_go2rtc.get("streams")
+    )
+    exec_keys = find_restricted_go2rtc_exec_changes(old_go2rtc, new_go2rtc)
+    if not issues and not exec_keys:
         return None
 
     messages = []
+    if exec_keys:
+        messages.append(f"Restricted go2rtc option: {', '.join(exec_keys)}")
     for issue, label in (
         (Go2rtcStreamIssue.restricted, "Restricted go2rtc stream source in"),
         (Go2rtcStreamIssue.unknown_variable, "Unknown variable in go2rtc stream"),
@@ -621,6 +627,7 @@ def _restricted_go2rtc_streams_response(
             Go2rtcStreamIssue.invalid_placeholder,
             "Invalid variable placeholder in go2rtc stream",
         ),
+        (Go2rtcStreamIssue.invalid_name, "Invalid go2rtc stream name"),
     ):
         names = [name for name, found in issues.items() if found == issue]
         if names:
@@ -717,9 +724,7 @@ def config_save(save_option: str, body: Any = Body(media_type="text/plain")):
     except OSError:
         old_raw_config = ""
 
-    restricted_response = _restricted_go2rtc_streams_response(
-        old_raw_config, new_config
-    )
+    restricted_response = _restricted_go2rtc_response(old_raw_config, new_config)
     if restricted_response is not None:
         return restricted_response
 
@@ -1172,7 +1177,7 @@ def config_set(request: Request, body: AppConfigSetBody):
                         ),
                         status_code=400,
                     )
-                restricted_response = _restricted_go2rtc_streams_response(
+                restricted_response = _restricted_go2rtc_response(
                     old_raw_config, new_raw_config
                 )
                 if restricted_response is not None:
@@ -1670,6 +1675,16 @@ def plusModels(request: Request, filterByCurrentModelDetector: bool = False):
     return JSONResponse(content=validModels)
 
 
+@router.post("/plus/validate", dependencies=[Depends(require_role(["admin"]))])
+async def validate_plus_key(request: Request):
+    """Validate the configured Frigate+ API key with the Frigate+ server."""
+    status = await request.app.frigate_config.plus_api.validate_key()
+
+    return JSONResponse(
+        content={"success": status == PlusKeyStatus.valid, "status": status.value}
+    )
+
+
 @router.get(
     "/recognized_license_plates", dependencies=[Depends(allow_any_authenticated())]
 )

frigate/api/auth.py

@@ -39,6 +39,7 @@ from frigate.config import AuthConfig, ProxyConfig
 from frigate.const import CONFIG_DIR, JWT_SECRET_ENV_VAR, PASSWORD_HASH_ALGORITHM
 from frigate.models import User
 from frigate.notices import raise_notice
+from frigate.util.live_streams import is_transcode_stream_name
 from frigate.util.origin import origin_allowed
 
 logger = logging.getLogger(__name__)
@@ -739,6 +740,13 @@ def auth(request: Request):
         int(request.headers.get("x-server-port", default=0))
         == request.app.auth_internal_port
     ):
+        # go2rtc runs the producer an unknown src describes for any caller
+        deny_status = deny_response_for_go2rtc_stream(
+            request.headers.get("x-original-url"), None, request
+        )
+        if deny_status is not None:
+            return Response("", status_code=deny_status)
+
         success_response.headers["remote-user"] = "anonymous"
         success_response.headers["remote-role"] = "admin"
         return success_response
@@ -934,7 +942,8 @@ def profile(request: Request):
 )
 def logout(request: Request):
     auth_config: AuthConfig = request.app.frigate_config.auth
-    response = RedirectResponse("/login", status_code=303)
+    base_path = request.headers.get("x-ingress-path", "").rstrip("/")
+    response = RedirectResponse(f"{base_path}/login", status_code=303)
     response.delete_cookie(auth_config.cookie_name)
     return response
 
@@ -965,6 +974,10 @@ def login(request: Request, body: AppPostLoginBody):
     try:
         db_user: User = User.get_by_id(user)
     except DoesNotExist:
+        # Hash anyway so response timing doesn't reveal which usernames exist
+        hash_password(
+            password, iterations=request.app.frigate_config.auth.hash_iterations
+        )
         logger.warning(f"Login failed for unknown user '{user}' from {remote_addr}")
         failed_logins.record(user, time.time())
         return JSONResponse(content={"message": "Login failed"}, status_code=401)
@@ -1270,7 +1283,12 @@ def _is_existing_go2rtc_stream(request: Request, stream_name: str) -> bool:
     """
     frigate_config = request.app.frigate_config
 
-    if _get_stream_owner_cameras(request, stream_name):
+    # live.streams values are free-form config, so only names Frigate controls
+    # skip the lookup
+    if any(
+        stream_name == camera or is_transcode_stream_name(camera, stream_name)
+        for camera in frigate_config.cameras
+    ):
         return True
 
     config_streams = getattr(frigate_config.go2rtc, "streams", None) or {}

frigate/api/chat.py

@@ -1,5 +1,6 @@
 """Chat and LLM tool calling APIs."""
 
+import asyncio
 import base64
 import json
 import logging
@@ -55,6 +56,7 @@ from frigate.genai.utils import (
 )
 from frigate.jobs.export import ExportQueueFullError, start_export_job
 from frigate.jobs.vlm_watch import (
+    VLMWatchJob,
     get_vlm_watch_job,
     start_vlm_watch_job,
     stop_vlm_watch_job,
@@ -998,7 +1000,7 @@ async def _execute_tool_internal(
     elif tool_name == "start_camera_watch":
         return await _execute_start_camera_watch(request, arguments)
     elif tool_name == "stop_camera_watch":
-        return _execute_stop_camera_watch()
+        return _execute_stop_camera_watch(request)
     elif tool_name == "get_profile_status":
         return _execute_get_profile_status(request)
     elif tool_name == "get_recap":
@@ -1059,6 +1061,7 @@ async def _execute_start_camera_watch(
             dispatcher=request.app.dispatcher,
             labels=labels,
             zones=zones,
+            username=request.headers.get("remote-user", ""),
         )
     except RuntimeError as e:
         logger.exception("Failed to start VLM watch job: %s", e)
@@ -1074,7 +1077,18 @@ async def _execute_start_camera_watch(
     }
 
 
-def _execute_stop_camera_watch() -> dict[str, Any]:
+def _can_cancel_watch_job(request: Request, job: VLMWatchJob) -> bool:
+    """Admins can cancel any watch job; other users only jobs they started."""
+    role = request.headers.get("remote-role", "viewer")
+    username = request.headers.get("remote-user", "")
+    return role == "admin" or username == job.username
+
+
+def _execute_stop_camera_watch(request: Request) -> dict[str, Any]:
+    job = get_vlm_watch_job()
+    if job is not None and not _can_cancel_watch_job(request, job):
+        return {"success": False, "message": "Not authorized to cancel this watch job."}
+
     cancelled = stop_vlm_watch_job()
     if cancelled:
         return {"success": True, "message": "Watch job cancelled."}
@@ -1653,7 +1667,8 @@ async def chat_completion(
                     f"Calling LLM (iteration {tool_iterations + 1}/{max_iterations}) "
                     f"with {len(conversation)} message(s) in conversation"
                 )
-                response = genai_client.chat_with_tools(
+                response = await asyncio.to_thread(
+                    genai_client.chat_with_tools,
                     messages=conversation,
                     tools=llm_tools if llm_tools else None,
                     tool_choice="auto",
@@ -1906,11 +1921,7 @@ async def cancel_vlm_monitor(request: Request) -> JSONResponse:
             status_code=404,
         )
 
-    role = request.headers.get("remote-role", "viewer")
-    username = request.headers.get("remote-user", "")
-
-    # Admin can cancel any job; other users can only cancel jobs they started.
-    if role != "admin" and username != job.username:
+    if not _can_cancel_watch_job(request, job):
         return JSONResponse(
             content={
                 "success": False,

frigate/api/defs/query/recordings_query_parameters.py

@@ -1,4 +1,4 @@
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from pydantic.json_schema import SkipJsonSchema
 
 
@@ -11,7 +11,7 @@ class MediaRecordingsAvailabilityQueryParams(BaseModel):
     cameras: str = "all"
     before: float | SkipJsonSchema[None] = None
     after: float | SkipJsonSchema[None] = None
-    scale: int = 30
+    scale: int = Field(default=30, ge=1)
 
 
 class RecordingsDeleteQueryParams(BaseModel):

frigate/api/defs/tags.py

@@ -2,6 +2,7 @@ from enum import Enum
 
 
 class Tags(Enum):
+    analytics = "Analytics"
     app = "App"
     auth = "Auth"
     camera = "Camera"

frigate/api/event.py

@@ -199,18 +199,14 @@ def events(
             sub_label_clauses.append(Event.sub_label.is_null())
 
         for label in filtered_sub_labels:
-            lowered = label.lower()
-            sub_label_clauses.append(
-                fn.LOWER(Event.sub_label.cast("text")) == lowered
-            )  # include exact matches (case-insensitive)
+            # SQLite LOWER() only folds ASCII, so lower both sides in SQL to
+            # keep non-ASCII names matching exactly
+            stored = fn.LOWER(Event.sub_label.cast("text"))
+            sub_label_clauses.append(stored == fn.LOWER(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}*"
-            )
+            # include this label when part of a list
+            sub_label_clauses.append(stored % fn.LOWER(f"*{label},*"))
+            sub_label_clauses.append(stored % fn.LOWER(f"*, {label}*"))
 
         sub_label_clause = reduce(operator.or_, sub_label_clauses)
         clauses.append(sub_label_clause)
@@ -291,12 +287,12 @@ def events(
             clauses.append(
                 reduce(
                     operator.or_,
-                    [(start_hour_fun > time_after), (start_hour_fun < time_before)],
+                    [(start_hour_fun >= time_after), (start_hour_fun < time_before)],
                 )
             )
         # all other cases should be and operator
         else:
-            clauses.append(start_hour_fun > time_after)
+            clauses.append(start_hour_fun >= time_after)
             clauses.append(start_hour_fun < time_before)
 
     if has_clip is not None:
@@ -633,18 +629,14 @@ 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(
-                fn.LOWER(Event.sub_label.cast("text")) == lowered
-            )  # include exact matches (case-insensitive)
+            # SQLite LOWER() only folds ASCII, so lower both sides in SQL to
+            # keep non-ASCII names matching exactly
+            stored = fn.LOWER(Event.sub_label.cast("text"))
+            sub_label_clauses.append(stored == fn.LOWER(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}*"
-            )
+            # include this label when part of a list
+            sub_label_clauses.append(stored % fn.LOWER(f"*{label},*"))
+            sub_label_clauses.append(stored % fn.LOWER(f"*, {label}*"))
 
         event_filters.append(reduce(operator.or_, sub_label_clauses))
 
@@ -749,12 +741,12 @@ def events_search(
             event_filters.append(
                 reduce(
                     operator.or_,
-                    [(start_hour_fun > time_after), (start_hour_fun < time_before)],
+                    [(start_hour_fun >= time_after), (start_hour_fun < time_before)],
                 )
             )
         # all other cases should be and operator
         else:
-            event_filters.append(start_hour_fun > time_after)
+            event_filters.append(start_hour_fun >= time_after)
             event_filters.append(start_hour_fun < time_before)
 
     # Perform semantic search

frigate/api/export.py

@@ -1227,7 +1227,7 @@ def bulk_delete_exports(body: ExportBulkDeleteBody):
     files_in_use = _get_files_in_use()
 
     for export in exports:
-        if export.video_path.split("/")[-1] in files_in_use:
+        if export.in_progress or export.video_path.split("/")[-1] in files_in_use:
             return JSONResponse(
                 content={
                     "success": False,

frigate/api/fastapi_app.py

@@ -13,8 +13,8 @@ from slowapi.middleware import SlowAPIMiddleware
 from starlette_context import middleware, plugins
 from starlette_context.plugins import Plugin
 
-from frigate.api import app as main_app
 from frigate.api import (
+    analytics,
     auth,
     camera,
     chat,
@@ -31,6 +31,7 @@ from frigate.api import (
     record,
     review,
 )
+from frigate.api import app as main_app
 from frigate.api.auth import get_jwt_secret, limiter, require_admin_by_default
 from frigate.comms.dispatcher import Dispatcher
 from frigate.comms.event_metadata_updater import (
@@ -143,6 +144,7 @@ def create_fastapi_app(
 
     # Routes
     # Order of include_router matters: https://fastapi.tiangolo.com/tutorial/path-params/#order-matters
+    app.include_router(analytics.router)
     app.include_router(auth.router)
     app.include_router(camera.router)
     app.include_router(chat.router)

frigate/api/media.py

@@ -862,7 +862,7 @@ async def vod_hour(
 async def vod_event(
     request: Request,
     event_id: str,
-    padding: int = Query(0, description="Padding to apply to the vod."),
+    padding: int = Query(0, ge=0, description="Padding to apply to the vod."),
 ):
     try:
         event: Event = Event.get(Event.id == event_id)
@@ -1521,6 +1521,7 @@ async def preview_gif(
                     | ((start_ts > Previews.start_time) & (end_ts < Previews.end_time))
                 )
                 .where(Previews.camera == camera_name)
+                .order_by(Previews.start_time.asc())
                 .limit(1)
                 .get()
             )
@@ -1530,7 +1531,8 @@ async def preview_gif(
                 status_code=404,
             )
 
-        diff = start_ts - preview.start_time
+        clip_start = max(start_ts, preview.start_time)
+        diff = clip_start - preview.start_time
         minutes = int(diff / 60)
         seconds = int(diff % 60)
         config: FrigateConfig = request.app.frigate_config
@@ -1542,7 +1544,7 @@ async def preview_gif(
             "-ss",
             f"00:{minutes}:{seconds}",
             "-t",
-            f"{end_ts - start_ts}",
+            f"{end_ts - clip_start}",
             "-i",
             preview.path,
             "-r",
@@ -1709,6 +1711,7 @@ async def preview_mp4(
                     | ((start_ts > Previews.start_time) & (end_ts < Previews.end_time))
                 )
                 .where(Previews.camera == camera_name)
+                .order_by(Previews.start_time.asc())
                 .limit(1)
                 .get()
             )
@@ -1721,7 +1724,8 @@ async def preview_mp4(
                 status_code=404,
             )
 
-        diff = start_ts - preview.start_time
+        clip_start = max(start_ts, preview.start_time)
+        diff = clip_start - preview.start_time
         minutes = int(diff / 60)
         seconds = int(diff % 60)
         config: FrigateConfig = request.app.frigate_config
@@ -1734,7 +1738,7 @@ async def preview_mp4(
             "-ss",
             f"00:{minutes}:{seconds}",
             "-t",
-            f"{end_ts - start_ts}",
+            f"{end_ts - clip_start}",
             "-i",
             preview.path,
             "-r",

frigate/api/review.py

@@ -163,8 +163,7 @@ async def review(
 
     # Apply ordering and limit
     review_query = (
-        review_query.order_by(ReviewSegment.severity.asc())
-        .order_by(ReviewSegment.start_time.desc())
+        review_query.order_by(ReviewSegment.start_time.desc())
         .limit(limit)
         .dicts()
         .iterator()

frigate/app.py

@@ -15,6 +15,7 @@ import uvicorn
 from peewee import SqliteDatabase
 from peewee_migrate import Router
 
+from frigate.analytics.reporter import AnalyticsReporter
 from frigate.api.auth import hash_password
 from frigate.api.fastapi_app import create_fastapi_app
 from frigate.camera import CameraMetrics, PTZMetrics
@@ -524,6 +525,15 @@ class FrigateApp:
         )
         self.stats_emitter.start()
 
+    def start_analytics_reporter(self) -> None:
+        self.analytics_reporter = AnalyticsReporter(
+            self.config_holder,
+            self.stats_emitter,
+            self.notice_registry,
+            self.stop_event,
+        )
+        self.analytics_reporter.start()
+
     def start_watchdog(self) -> None:
         self.frigate_watchdog = FrigateWatchdog(self.detectors, self.stop_event)
 
@@ -697,6 +707,7 @@ class FrigateApp:
         self.start_audio_processor()
         self.start_storage_maintainer()
         self.start_stats_emitter()
+        self.start_analytics_reporter()
         self.start_timeline_processor()
         self.start_event_processor()
         self.start_event_cleanup()
@@ -798,6 +809,8 @@ class FrigateApp:
         self.event_cleanup.join()
         self.record_cleanup.join()
         self.stats_emitter.join()
+        # a send in flight can hold the thread for the whole request timeout
+        self.analytics_reporter.join(timeout=5)
         self.frigate_watchdog.join()
         self.camera_maintainer.join()
         self.db.stop()

frigate/comms/webpush.py

@@ -7,6 +7,7 @@ import logging
 import os
 import queue
 import threading
+import time
 from collections.abc import Callable, Iterator
 from dataclasses import dataclass
 from multiprocessing.synchronize import Event as MpEvent
@@ -22,6 +23,7 @@ from frigate.comms.base_communicator import Communicator
 from frigate.comms.config_updater import ConfigSubscriber
 from frigate.config import FrigateConfig
 from frigate.config.auth import AuthConfig
+from frigate.config.camera.notification import NOTIFICATION_TTL_SECONDS
 from frigate.config.camera.updater import (
     CameraConfigUpdateEnum,
     CameraConfigUpdateSubscriber,
@@ -184,11 +186,13 @@ class WebPushClient(Communicator):
         }
         self.suspension_broadcaster: Callable[[str, Any, bool], None] | None = None
         self.config_lock = threading.Lock()
+        # monotonic times, so a backward wall clock step can't hold every
+        # notification in cooldown. -inf means none has been sent yet
         self.last_camera_notification_time: dict[str, float] = {
-            c.name: 0  # type: ignore[misc]
+            c.name: float("-inf")  # type: ignore[misc]
             for c in self.config.cameras.values()
         }
-        self.last_notification_time: float = 0
+        self.last_notification_time: float = float("-inf")
         self.user_cameras: dict[str, set[str]] = {}
         self.notification_queue: queue.Queue[PushNotification] = queue.Queue()
         self.notification_thread: threading.Thread | None = None
@@ -343,7 +347,7 @@ class WebPushClient(Communicator):
             if "add" in updates:
                 for camera in updates["add"]:
                     self.suspended_cameras[camera] = 0
-                    self.last_camera_notification_time[camera] = 0
+                    self.last_camera_notification_time[camera] = float("-inf")
 
                 self._refresh_user_cameras()
 
@@ -498,7 +502,7 @@ class WebPushClient(Communicator):
         return camera in allowed
 
     def _within_cooldown(self, camera: str) -> bool:
-        now = datetime.datetime.now().timestamp()
+        now = time.monotonic()
         if now - self.last_notification_time < self.config.notifications.cooldown:
             logger.debug(
                 f"Skipping notification for {camera} - in global cooldown period"
@@ -543,7 +547,7 @@ class WebPushClient(Communicator):
         camera_name: str = getattr(
             self.config.cameras[camera], "friendly_name", None
         ) or titlecase(camera.replace("_", " "))
-        current_time = datetime.datetime.now().timestamp()
+        current_time = time.monotonic()
 
         if self._within_cooldown(camera):
             return
@@ -623,7 +627,7 @@ class WebPushClient(Communicator):
 
         # if event is ongoing open to live view otherwise open to recordings view
         direct_url = f"/review?id={reviewId}" if ended else f"/#{camera}"
-        ttl = 3600 if ended else 0
+        ttl = 3600 if ended else NOTIFICATION_TTL_SECONDS[self.config.notifications.ttl]
 
         logger.debug(f"Sending push notification for {camera}, review ID {reviewId}")
 
@@ -656,7 +660,7 @@ class WebPushClient(Communicator):
         camera_name: str = getattr(
             self.config.cameras[camera], "friendly_name", None
         ) or titlecase(camera.replace("_", " "))
-        current_time = datetime.datetime.now().timestamp()
+        current_time = time.monotonic()
 
         if self._within_cooldown(camera):
             return

frigate/config/camera/birdseye.py

@@ -57,11 +57,6 @@ def birdseye_modes_to_mqtt_payload(modes: list[BirdseyeModeEnum]) -> str:
     return payload or MQTT_NO_MODES
 
 
-def default_birdseye_modes() -> list[BirdseyeModeEnum]:
-    """Return the default Birdseye activity modes."""
-    return [BirdseyeModeEnum.all_objects]
-
-
 class BirdseyeLayoutConfig(FrigateBaseModel):
     scaling_factor: float = Field(
         default=2.0,
@@ -84,7 +79,7 @@ class BirdseyeConfig(FrigateBaseModel):
         description="Enable or disable the Birdseye view feature.",
     )
     modes: list[BirdseyeModeEnum] = Field(
-        default_factory=default_birdseye_modes,
+        default=[BirdseyeModeEnum.all_objects],
         title="Activity types",
         description="Activity types that include cameras in Birdseye.",
     )
@@ -139,7 +134,7 @@ class BirdseyeCameraConfig(BaseModel):
         description="Enable or disable the Birdseye view feature.",
     )
     modes: list[BirdseyeModeEnum] = Field(
-        default_factory=default_birdseye_modes,
+        default=[BirdseyeModeEnum.all_objects],
         title="Activity types",
         description="Activity types that include cameras in Birdseye.",
     )

frigate/config/camera/ffmpeg.py

@@ -2,7 +2,7 @@ from enum import Enum
 
 from pydantic import Field, field_validator
 
-from frigate.util.config import resolve_ffmpeg_path
+from frigate.util.config import is_valid_ffmpeg_path, resolve_ffmpeg_path
 from frigate.util.env import EnvString
 
 from ..base import FrigateBaseModel
@@ -101,6 +101,16 @@ class FfmpegConfig(FrigateBaseModel):
         description="Default GPU index used for hardware acceleration if available.",
     )
 
+    @field_validator("path")
+    @classmethod
+    def validate_path(cls, v: str) -> str:
+        if not is_valid_ffmpeg_path(v):
+            raise ValueError(
+                "FFmpeg path must be a version alias or an absolute path without "
+                "spaces, quotes or shell characters"
+            )
+        return v
+
     @property
     def ffmpeg_path(self) -> str:
         return resolve_ffmpeg_path(self.path, "ffmpeg")

frigate/config/camera/notification.py

@@ -1,10 +1,23 @@
+from enum import Enum
+
 from pydantic import Field
 
 from frigate.util.env import EnvString
 
 from ..base import FrigateBaseModel
 
-__all__ = ["NotificationConfig"]
+__all__ = ["NotificationConfig", "NotificationTTLEnum", "NOTIFICATION_TTL_SECONDS"]
+
+
+class NotificationTTLEnum(str, Enum):
+    immediate = "immediate"
+    reliable = "reliable"
+
+
+NOTIFICATION_TTL_SECONDS = {
+    NotificationTTLEnum.immediate: 0,
+    NotificationTTLEnum.reliable: 30,
+}
 
 
 class NotificationConfig(FrigateBaseModel):
@@ -24,6 +37,11 @@ class NotificationConfig(FrigateBaseModel):
         title="Cooldown period",
         description="Cooldown (seconds) between notifications to avoid spamming recipients.",
     )
+    ttl: NotificationTTLEnum = Field(
+        default=NotificationTTLEnum.immediate,
+        title="Notification TTL",
+        description="How the push service handles a notification sent while an alert is active if your device can't be reached. Immediate delivers it right away or drops it. Reliable keeps retrying for up to 30 seconds. The notification sent when an alert ends is always kept for up to an hour.",
+    )
     enabled_in_config: bool | None = Field(
         default=None,
         title="Original notifications state",

frigate/config/config.py

@@ -39,6 +39,7 @@ from frigate.util.image import create_mask
 from frigate.util.live_streams import (
     default_transcode_source,
     is_transcode_stream_name,
+    is_valid_go2rtc_stream_name,
     transcode_stream_name,
     transcode_streams,
 )
@@ -314,6 +315,11 @@ def apply_live_transcode_streams(
                 f"Camera {camera_config.name} has transcoded streams enabled, but its source {transcode.source} is not a go2rtc stream."
             )
 
+        if not is_valid_go2rtc_stream_name(transcode.source):
+            raise ValueError(
+                f"Camera {camera_config.name} transcodes go2rtc stream {transcode.source}, whose name contains '#', whitespace or quotes."
+            )
+
         generated = transcode_streams(
             camera_config.name,
             transcode.source,

frigate/config/holder.py

@@ -1,9 +1,14 @@
 """Shared handle on the config object that is current for this instance."""
 
+import logging
+from collections.abc import Callable
+
 from .config import FrigateConfig
 
 __all__ = ["ConfigHolder"]
 
+logger = logging.getLogger(__name__)
+
 
 class ConfigHolder:
     """Indirection for the most recently parsed config.
@@ -23,12 +28,24 @@ class ConfigHolder:
 
     def __init__(self, config: FrigateConfig) -> None:
         self._config = config
+        self._listeners: list[Callable[[FrigateConfig], None]] = []
 
     @property
     def config(self) -> FrigateConfig:
         """The config as of the most recent successful save."""
         return self._config
 
+    def subscribe(self, listener: Callable[[FrigateConfig], None]) -> None:
+        """Call listener on the saving thread with each config installed later."""
+        self._listeners.append(listener)
+
     def set(self, config: FrigateConfig) -> None:
         """Install a freshly parsed config as the current one."""
         self._config = config
+
+        for listener in self._listeners:
+            try:
+                listener(config)
+            except Exception:
+                # a listener bug must not fail the save that has already applied
+                logger.exception("Config listener failed")

frigate/config/mqtt.py

@@ -84,3 +84,13 @@ class MqttConfig(FrigateBaseModel):
         if (self.user is None) != (self.password is None):
             raise ValueError("Password must be provided with username.")
         return self
+
+    @model_validator(mode="after")
+    def tls_insecure_requires_tls(self) -> Self:
+        """Reject TLS verification settings without TLS when MQTT is enabled."""
+        if self.enabled and self.tls_insecure is not None and self.tls_ca_certs is None:
+            raise ValueError(
+                "tls_insecure requires tls_ca_certs. Remove tls_insecure for plaintext "
+                "MQTT, or set tls_ca_certs to a CA certificate path to enable TLS."
+            )
+        return self

frigate/config/telemetry.py

@@ -29,6 +29,11 @@ class StatsConfig(FrigateBaseModel):
 
 
 class TelemetryConfig(FrigateBaseModel):
+    analytics: bool = Field(
+        default=False,
+        title="Share anonymous analytics",
+        description="Send one anonymous usage report a day to help the Frigate maintainers decide what to support. Nothing is sent until this is on.",
+    )
     network_interfaces: list[str] = Field(
         default=[],
         title="Network interfaces",

frigate/const.py

@@ -102,6 +102,9 @@ MAX_WAL_SIZE = 10  # MB
 
 DEFAULT_FFMPEG_VERSION = os.environ.get("DEFAULT_FFMPEG_VERSION", "")
 INCLUDED_FFMPEG_VERSIONS = os.environ.get("INCLUDED_FFMPEG_VERSIONS", "").split(":")
+ANALYTICS_URL = os.environ.get(
+    "FRIGATE_ANALYTICS_URL", "https://analytics.frigate.video/report"
+)
 LIBAVFORMAT_VERSION_MAJOR = int(os.environ.get("LIBAVFORMAT_VERSION_MAJOR", "59"))
 FFMPEG_HWACCEL_NVIDIA = "preset-nvidia"
 FFMPEG_HWACCEL_VAAPI = "preset-vaapi"

frigate/data_processing/post/review_annotations.py

@@ -12,6 +12,8 @@ import math
 from collections.abc import Sequence
 from typing import Any
 
+from titlecase import titlecase
+
 from frigate.models import Event, Timeline
 
 logger = logging.getLogger(__name__)
@@ -84,12 +86,16 @@ def event_name(event: dict[str, Any]) -> str:
     tracked object whenever a subject is re-detected, so the tracking data
     cannot say whether two entries are the same subject, and the notes stay
     ambiguous rather than implying either answer.
+
+    Names are formatted the same way as in the prompt's "Objects in Scene"
+    list. Small models otherwise copy the raw lowercase sub label into their
+    response instead of the name they were told to use.
     """
     label = str(event["label"]).replace("_", " ").replace("-verified", "")
     sub_label = event.get("sub_label")
 
     if sub_label:
-        return f'{label} "{sub_label}"'
+        return f'{label} "{titlecase(str(sub_label).replace("_", " "))}"'
 
     article = "an" if label[:1].lower() in "aeiou" else "a"
     return f"{article} {label}"
@@ -213,6 +219,7 @@ def build_timeline(
     events: list[dict[str, Any]],
     span_end: float,
     state_changes: Sequence[dict[str, Any]] = (),
+    span_start: float | None = None,
 ) -> list[tuple[float, str]]:
     """All annotated moments across every event, in time order.
 
@@ -222,6 +229,12 @@ def build_timeline(
     describe nothing the model can see. A track ending means the object
     stopped being detected, which may or may not mean it left the frame.
 
+    `span_start` is the timestamp of the first sampled frame. An object
+    tracked since before it gets a single "already in view" note instead of
+    its earlier history: those moments would otherwise land on the first
+    frame and read as happening during the clip, turning a car that parked
+    minutes ago into one pulling in.
+
     `state_changes` are timeline rows (timestamp, source_id, class_type); the
     stationary and active ones become "has stopped moving" / "starts moving
     again". Frigate only marks an object stationary after it has been still
@@ -249,6 +262,13 @@ def build_timeline(
         if event["start_time"] > span_end:
             continue
 
+        if (
+            span_start is not None
+            and event["end_time"]
+            and event["end_time"] < span_start
+        ):
+            continue
+
         points = path_points(event.get("path_data") or [])
         legs = path_legs(points) if len(points) >= 2 else []
         name = event_name(event)
@@ -259,8 +279,33 @@ def build_timeline(
         )
         remaining = list(enumerate(legs))
         moments: list[tuple[float, str]] = []
+        event_changes = sorted(
+            (timestamp, phrase)
+            for timestamp, phrase in changes_by_event.get(event["id"], [])
+            if timestamp >= detected_at
+        )
 
-        if merges:
+        if span_start is not None and detected_at < span_start:
+            # Only whether it had come to rest is noted; where it is and which
+            # way it is heading are visible in the first frame.
+            earlier = [phrase for t, phrase in event_changes if t < span_start]
+            not_moving = (
+                bool(earlier) and earlier[-1] == STATE_CHANGE_PHRASES["stationary"]
+            )
+            timeline.append(
+                (
+                    span_start,
+                    f"{name} already in view when the sequence begins"
+                    + (", not moving" if not_moving else ""),
+                )
+            )
+            remaining = [
+                (index, leg)
+                for index, leg in remaining
+                if leg_start_time(points, leg) >= span_start
+            ]
+            event_changes = [(t, p) for t, p in event_changes if t >= span_start]
+        elif merges:
             heading = leg_heading(points, legs[0])
             timeline.append(
                 (detected_at, f"{name} first detected at {where}, moving {heading}")
@@ -277,11 +322,7 @@ def build_timeline(
                 )
             )
 
-        moments.extend(
-            (timestamp, phrase)
-            for timestamp, phrase in changes_by_event.get(event["id"], [])
-            if timestamp >= detected_at
-        )
+        moments.extend(event_changes)
 
         for timestamp, phrase in moments:
             if timestamp <= span_end:
@@ -390,7 +431,10 @@ def build_frame_captions(
         timeline.extend(
             (timestamp, f"[tracker] {note}")
             for timestamp, note in build_timeline(
-                events, span_end, get_state_changes(detection_ids)
+                events,
+                span_end,
+                get_state_changes(detection_ids),
+                span_start=frame_times[0],
             )
         )
 

frigate/data_processing/post/review_descriptions.py

@@ -34,7 +34,7 @@ from frigate.const import (
 from frigate.data_processing.types import PostProcessDataEnum
 from frigate.genai import GenAIClient
 from frigate.genai.manager import GenAIClientManager
-from frigate.models import Recordings, ReviewSegment
+from frigate.models import Event, Recordings, ReviewSegment
 from frigate.util.builtin import EventsPerSecond, InferenceSpeed
 from frigate.util.image import get_image_from_recording
 from frigate.util.recording_coverage import recording_overlap
@@ -68,6 +68,9 @@ class ReviewDescriptionProcessor(PostProcessorApi):
         self.review_desc_dps = EventsPerSecond()
         self.review_desc_dps.start()
 
+        # one review's ffmpeg extraction at a time, as on the maintainer loop
+        self._frame_extraction_lock = threading.Lock()
+
     def calculate_frame_count(
         self,
         camera: str,
@@ -179,53 +182,72 @@ class ReviewDescriptionProcessor(PostProcessorApi):
             ):
                 return
 
-            image_source = camera_config.review.genai.image_source
-            frame_mode = camera_config.review.genai.frame_mode
+            threading.Thread(
+                target=self._describe_finished_review,
+                name=f"review_description_{id}",
+                daemon=True,
+                args=(
+                    camera_config,
+                    final_data,
+                    camera_config.review.genai.image_source,
+                ),
+            ).start()
 
-            if image_source == ImageSourceEnum.recordings:
-                buffer_extension = get_recording_buffer_extension(
-                    final_data["end_time"] - final_data["start_time"]
-                )
-                final_data["start_time"] -= buffer_extension
-                final_data["end_time"] += buffer_extension
+    def _describe_finished_review(
+        self,
+        camera_config: CameraConfig,
+        final_data: dict[str, Any],
+        image_source: ImageSourceEnum,
+        preview_fallback: bool = True,
+        named_objects: list[tuple[str, str]] | None = None,
+    ) -> None:
+        """Gather frames for a finished review item and start its description.
 
+        Runs off the maintainer loop since recording frames shell out to ffmpeg
+        once per frame.
+        """
+        camera = final_data["camera"]
+        id = final_data["id"]
+        genai_config = camera_config.review.genai
+        frames: list[tuple[bytes, float]] = []
+
+        if image_source == ImageSourceEnum.recordings:
+            buffer_extension = get_recording_buffer_extension(
+                final_data["end_time"] - final_data["start_time"]
+            )
+            with self._frame_extraction_lock:
                 frames = self.get_recording_frames(
                     camera,
-                    final_data["start_time"],
-                    final_data["end_time"],
+                    final_data["start_time"] - buffer_extension,
+                    final_data["end_time"] + buffer_extension,
                     height=480,  # Use 480p for good balance between quality and token usage
-                    frame_mode=frame_mode,
+                    frame_mode=genai_config.frame_mode,
                 )
 
-                if not frames:
-                    # Fallback to preview frames if no recordings available
-                    logger.warning(
-                        f"No recording frames found for {camera}, falling back to preview frames"
-                    )
-                    frames = self.get_preview_frames_as_bytes(
-                        camera,
-                        final_data["start_time"],
-                        final_data["end_time"],
-                        final_data["thumb_path"],
-                        id,
-                        camera_config.review.genai.debug_save_thumbnails,
-                        frame_mode,
-                    )
-                elif camera_config.review.genai.debug_save_thumbnails:
+            if frames:
+                if genai_config.debug_save_thumbnails:
                     self.save_debug_recording_frames(id, frames)
+            elif not preview_fallback:
+                logger.error("No recording frames are available for review item %s", id)
+                return
             else:
-                # Use preview frames
-                frames = self.get_preview_frames_as_bytes(
+                logger.warning(
+                    "No recording frames found for %s, falling back to preview frames",
                     camera,
-                    final_data["start_time"],
-                    final_data["end_time"],
-                    final_data["thumb_path"],
-                    id,
-                    camera_config.review.genai.debug_save_thumbnails,
-                    frame_mode,
                 )
 
-            self.start_analysis(camera_config, final_data, frames)
+        if not frames:
+            frames = self.get_preview_frames_as_bytes(
+                camera,
+                final_data["start_time"],
+                final_data["end_time"],
+                final_data["thumb_path"],
+                id,
+                genai_config.debug_save_thumbnails,
+                genai_config.frame_mode,
+            )
+
+        self.start_analysis(camera_config, final_data, frames, named_objects)
 
     def handle_request(self, topic: str, request_data: dict[str, Any]) -> str | None:
         if topic == EmbeddingsRequestEnum.regenerate_review_description.value:
@@ -419,33 +441,23 @@ class ReviewDescriptionProcessor(PostProcessorApi):
             logger.error("Review item %s has not ended yet", review_id)
             return
 
-        buffer_extension = get_recording_buffer_extension(
-            final_data["end_time"] - final_data["start_time"]
+        self._describe_finished_review(
+            camera_config,
+            final_data,
+            ImageSourceEnum.recordings,
+            preview_fallback=False,
+            named_objects=get_named_objects(
+                final_data["data"].get("detections") or [],
+                self.config.all_attributes,
+            ),
         )
-        frames = self.get_recording_frames(
-            str(review.camera),
-            final_data["start_time"] - buffer_extension,
-            final_data["end_time"] + buffer_extension,
-            height=480,
-            frame_mode=camera_config.review.genai.frame_mode,
-        )
-
-        if not frames:
-            logger.error(
-                "No recording frames are available for review item %s", review_id
-            )
-            return
-
-        if camera_config.review.genai.debug_save_thumbnails:
-            self.save_debug_recording_frames(review_id, frames)
-
-        self.start_analysis(camera_config, final_data, frames)
 
     def start_analysis(
         self,
         camera_config: CameraConfig,
         final_data: dict[str, Any],
         frames: list[tuple[bytes, float]],
+        named_objects: list[tuple[str, str]] | None = None,
     ) -> None:
         """Kick off description generation for a review item in the background."""
         thumbs = [frame for frame, _ in frames]
@@ -481,6 +493,7 @@ class ReviewDescriptionProcessor(PostProcessorApi):
                 camera_config.review.genai,
                 sorted(self.config.all_labels),
                 self.config.all_attributes,
+                named_objects,
             ),
         ).start()
 
@@ -741,6 +754,29 @@ def format_classification_state_changes(
     return lines
 
 
+def get_named_objects(
+    detection_ids: list[str], attribute_labels: list[str]
+) -> list[tuple[str, str]]:
+    """Get the label and sub label of each named tracked object in a review item.
+
+    Editing a sub label after a review item ends rebuilds the stored sub_labels
+    without verified_objects, so the stored lists can't be paired by position.
+    """
+    events = (
+        Event.select(Event.label, Event.sub_label)
+        .where(Event.id.in_(detection_ids), Event.sub_label.is_null(False))
+        .order_by(Event.start_time)
+    )
+
+    # attribute sub labels (eg, delivery logos) are not names, which matches
+    # how the review maintainer records them
+    return [
+        (event.label, event.sub_label)
+        for event in events
+        if event.sub_label and event.sub_label not in attribute_labels
+    ]
+
+
 def run_analysis(
     requestor: InterProcessRequestor,
     genai_client: GenAIClient,
@@ -752,6 +788,7 @@ def run_analysis(
     genai_config: GenAIReviewConfig,
     labelmap_objects: list[str],
     attribute_labels: list[str],
+    named_objects: list[tuple[str, str]] | None,
 ) -> None:
     start = datetime.datetime.now().timestamp()
 
@@ -776,11 +813,20 @@ def run_analysis(
     unified_objects = []
 
     objects_list = final_data["data"]["objects"]
-    sub_labels_list = final_data["data"]["sub_labels"]
 
-    for i, verified_label in enumerate(final_data["data"]["verified_objects"]):
-        object_type = verified_label.replace("-verified", "").replace("_", " ")
-        name = titlecase(sub_labels_list[i].replace("_", " "))
+    if named_objects is None:
+        # live review items record a sub label for every verified object
+        named_objects = [
+            (verified_label.replace("-verified", ""), sub_label)
+            for verified_label, sub_label in zip(
+                final_data["data"]["verified_objects"],
+                final_data["data"]["sub_labels"],
+            )
+        ]
+
+    for label, sub_label in named_objects:
+        object_type = label.replace("_", " ")
+        name = titlecase(sub_label.replace("_", " "))
         unified_objects.append(f"{name} ← {object_type}")
 
     for label in objects_list:

frigate/data_processing/real_time/custom_classification.py

@@ -3,6 +3,7 @@
 import datetime
 import logging
 import os
+import time
 from typing import Any
 
 import cv2
@@ -67,7 +68,8 @@ class CustomStateClassificationProcessor(DeferredRealtimeProcessorApi):
         else:
             self.inference_speed = None
 
-        self.last_run = datetime.datetime.now().timestamp()
+        # monotonic so a backward wall clock step can't pause classification
+        self.last_run = time.monotonic()
         self.__build_detector()
 
     def __build_detector(self) -> None:
@@ -215,11 +217,12 @@ class CustomStateClassificationProcessor(DeferredRealtimeProcessorApi):
         should_run = False
 
         now = datetime.datetime.now().timestamp()
+        mono_now = time.monotonic()
         if (
             self.model_config.state_config.interval
-            and now > self.last_run + self.model_config.state_config.interval
+            and mono_now > self.last_run + self.model_config.state_config.interval
         ):
-            self.last_run = now
+            self.last_run = mono_now
             should_run = True
 
         if (
@@ -228,8 +231,8 @@ class CustomStateClassificationProcessor(DeferredRealtimeProcessorApi):
             and any([box_overlaps(crop, mb) for mb in frame_data.get("motion", [])])
         ):
             # classification should run at most once per second
-            if now > self.last_run + 1:
-                self.last_run = now
+            if mono_now > self.last_run + 1:
+                self.last_run = mono_now
                 should_run = True
 
         # Shortcut: always run if we have a pending state verification to complete
@@ -237,9 +240,9 @@ class CustomStateClassificationProcessor(DeferredRealtimeProcessorApi):
             not should_run
             and camera in self.state_history
             and self.state_history[camera]["pending_state"] is not None
-            and now > self.last_run + 0.5
+            and mono_now > self.last_run + 0.5
         ):
-            self.last_run = now
+            self.last_run = mono_now
             should_run = True
             logger.debug(
                 f"Running verification check for pending state: {self.state_history[camera]['pending_state']} ({self.state_history[camera]['consecutive_count']}/3)"

frigate/detectors/detector_utils.py

@@ -1,8 +1,13 @@
 import logging
+import math
 import os
 
+import cv2
 import numpy as np
 
+from frigate.detectors.detector_config import ModelConfig, ModelTypeEnum
+from frigate.util.model import xyxy_to_xywh_for_nms
+
 try:
     from tflite_runtime.interpreter import Interpreter, load_delegate
 except ModuleNotFoundError:
@@ -12,39 +17,324 @@ except ModuleNotFoundError:
 logger = logging.getLogger(__name__)
 
 
-def tflite_init(self, interpreter):
-    self.interpreter = interpreter
+class TFLiteDetectionModel:
+    """Object detection pre and post processing for a TFLite interpreter.
 
-    self.interpreter.allocate_tensors()
+    Every TFLite detector shares this, differing only in how it builds the
+    interpreter (on the CPU, or with the EdgeTPU or Teflon delegate).
+    """
 
-    self.tensor_input_details = self.interpreter.get_input_details()
-    self.tensor_output_details = self.interpreter.get_output_details()
+    supported_models = [
+        ModelTypeEnum.ssd,
+        ModelTypeEnum.yologeneric,
+    ]
 
+    def __init__(
+        self, interpreter: Interpreter, model_config: ModelConfig, detector_key: str
+    ):
+        """Prepare the interpreter and work out the model's output layout.
 
-def tflite_detect_raw(self, tensor_input):
-    self.interpreter.set_tensor(self.tensor_input_details[0]["index"], tensor_input)
-    self.interpreter.invoke()
+        Args:
+            interpreter: The TFLite interpreter, with any delegate loaded
+            model_config: The model being run
+            detector_key: The detector's type, for error messages
+        """
+        self.model_type = model_config.model_type
 
-    boxes = self.interpreter.tensor(self.tensor_output_details[0]["index"])()[0]
-    class_ids = self.interpreter.tensor(self.tensor_output_details[1]["index"])()[0]
-    scores = self.interpreter.tensor(self.tensor_output_details[2]["index"])()[0]
-    count = int(self.interpreter.tensor(self.tensor_output_details[3]["index"])()[0])
+        if self.model_type not in self.supported_models:
+            raise ValueError(
+                f"{self.model_type.value} is currently not supported for {detector_key}. See the docs for more info on supported models."
+            )
 
-    detections = np.zeros((20, 6), np.float32)
+        self.interpreter = interpreter
 
-    for i in range(count):
-        if scores[i] < 0.4 or i == 20:
-            break
-        detections[i] = [
-            class_ids[i],
-            float(scores[i]),
-            boxes[i][0],
-            boxes[i][1],
-            boxes[i][2],
-            boxes[i][3],
-        ]
+        try:
+            self.interpreter.allocate_tensors()
+        except RuntimeError as e:
+            # an EdgeTPU compiled model wraps its graph in a custom op that only
+            # the EdgeTPU delegate can run
+            if "edgetpu-custom-op" in str(e):
+                logger.error(
+                    "%s is compiled for the EdgeTPU and can only be run by an edgetpu detector",
+                    model_config.path,
+                )
+            raise
 
-    return detections
+        self.tensor_input_details = self.interpreter.get_input_details()
+        self.tensor_output_details = self.interpreter.get_output_details()
+        self.model_width = model_config.width
+        self.model_height = model_config.height
+
+        self.min_score = 0.4
+        self.max_detections = 20
+
+        self.model_requires_int8 = self.tensor_input_details[0]["dtype"] == np.int8
+
+        if self.model_type == ModelTypeEnum.yologeneric:
+            logger.debug("Using YOLO preprocessing/postprocessing")
+
+            if len(self.tensor_output_details) not in [2, 3]:
+                raise ValueError(
+                    f"Invalid count of output tensors in YOLO model. Found {len(self.tensor_output_details)}, expecting 2 or 3."
+                )
+
+            self.reg_max = 16  # = 64 dfl_channels // 4 # YOLO standard
+            self.min_logit_value = np.log(
+                self.min_score / (1 - self.min_score)
+            )  # for filtering
+            self._generate_anchors_and_strides()  # decode bounding box DFL
+            self.project = np.arange(
+                self.reg_max, dtype=np.float32
+            )  # for decoding bounding box DFL information
+
+            # Determine YOLO tensor indices and quantization scales for
+            # boxes and class_scores the tensor ordering and names are
+            # not reliable, so use tensor shape to detect which tensor
+            # holds boxes or class scores.
+            # The tensors have shapes (B, N, C)
+            # where N is the number of candidates (=2100 for 320x320)
+            # this may guess wrong if the number of classes is exactly 64
+            output_boxes_index = None
+            output_classes_index = None
+            for i, x in enumerate(self.tensor_output_details):
+                # the nominal index seems to start at 1 instead of 0
+                if len(x["shape"]) == 3 and x["shape"][2] == 64:
+                    output_boxes_index = i
+                elif len(x["shape"]) == 3 and x["shape"][2] > 1:
+                    # require the number of classes to be more than 1
+                    # to differentiate from (not used) max score tensor
+                    output_classes_index = i
+            if output_boxes_index is None or output_classes_index is None:
+                logger.warning("Unrecognized model output, unexpected tensor shapes.")
+                output_classes_index = (
+                    0
+                    if (output_boxes_index is None or output_classes_index == 1)
+                    else 1
+                )  # 0 is default guess
+                output_boxes_index = 1 if (output_boxes_index == 0) else 0
+
+            scores_details = self.tensor_output_details[output_classes_index]
+            boxes_details = self.tensor_output_details[output_boxes_index]
+
+            # post processing works on the raw quantized values, which a float
+            # model doesn't have
+            if np.issubdtype(scores_details["dtype"], np.floating) or np.issubdtype(
+                boxes_details["dtype"], np.floating
+            ):
+                raise ValueError(
+                    f"{model_config.path} has float outputs. YOLO models for TFLite must be int8 quantized."
+                )
+
+            self.scores_tensor_index = scores_details["index"]
+            self.scores_scale, self.scores_zero_point = scores_details["quantization"]
+            # calculate the quantized version of the min_score
+            self.min_score_quantized = int(
+                (self.min_logit_value / self.scores_scale) + self.scores_zero_point
+            )
+            self.logit_shift_to_positive_values = (
+                max(0, math.ceil((128 + self.scores_zero_point) * self.scores_scale))
+                + 1
+            )  # round up
+
+            self.boxes_tensor_index = boxes_details["index"]
+            self.boxes_scale, self.boxes_zero_point = boxes_details["quantization"]
+
+        elif self.model_type == ModelTypeEnum.ssd:
+            logger.debug("Using SSD preprocessing/postprocessing")
+
+            # SSD models end in TFLite_Detection_PostProcess, which outputs
+            # boxes, class ids, scores and count
+            if len(self.tensor_output_details) < 4:
+                raise ValueError(
+                    f"Invalid count of output tensors in SSD model. Found {len(self.tensor_output_details)}, expecting 4. YOLO models need a model_type of yolo-generic."
+                )
+
+    def _generate_anchors_and_strides(self):
+        # for decoding the bounding box DFL information into xy coordinates
+        all_anchors = []
+        all_strides = []
+        strides = (8, 16, 32)  # YOLO's small, medium, large detection heads
+
+        for stride in strides:
+            feat_h, feat_w = self.model_height // stride, self.model_width // stride
+
+            grid_y, grid_x = np.meshgrid(
+                np.arange(feat_h, dtype=np.float32),
+                np.arange(feat_w, dtype=np.float32),
+                indexing="ij",
+            )
+
+            grid_coords = np.stack((grid_x.flatten(), grid_y.flatten()), axis=1)
+            anchor_points = grid_coords + 0.5
+
+            all_anchors.append(anchor_points)
+            all_strides.append(np.full((feat_h * feat_w, 1), stride, dtype=np.float32))
+
+        self.anchors = np.concatenate(all_anchors, axis=0)
+        self.anchor_strides = np.concatenate(all_strides, axis=0)
+
+    def pre_process(self, tensor_input):
+        if self.model_requires_int8:
+            tensor_input = np.bitwise_xor(tensor_input, 128).view(
+                np.int8
+            )  # shift by -128
+        return tensor_input
+
+    def detect_raw(self, tensor_input):
+        """Run the model on a frame.
+
+        Args:
+            tensor_input: The frame, already resized to the model's input
+
+        Returns:
+            Up to 20 detections as [class_id, score, ymin, xmin, ymax, xmax],
+            padded with zeros
+        """
+        tensor_input = self.pre_process(tensor_input)
+
+        self.interpreter.set_tensor(self.tensor_input_details[0]["index"], tensor_input)
+        self.interpreter.invoke()
+
+        if self.model_type == ModelTypeEnum.yologeneric:
+            return self._post_process_yolo()
+
+        return self._post_process_ssd()
+
+    def _post_process_yolo(self):
+        # Multi-tensor YOLO model with (non-standard B(H*W)C output format).
+        # (the comments indicate the shape of tensors,
+        # using "2100" as the anchor count (for image size of 320x320),
+        # "NC" as number of classes,
+        # "N" as the count that survive after min-score filtering)
+        # TENSOR A) class scores (1, 2100, NC) with logit values
+        # TENSOR B) box coordinates (1, 2100, 64) encoded as dfl scores
+        # Recommend that the model clamp the logit values in tensor (A)
+        # to the range [-4,+4] to preserve precision from [2%,98%]
+        # and because NMS requires the min_score parameter to be >= 0
+
+        # don't dequantize scores data yet, wait until the low-confidence
+        # candidates are filtered out from the overall result set.
+        # This reduces the work and makes post-processing faster.
+        # this method works with raw quantized numbers when possible,
+        # which relies on the value of the scale factor to be >0.
+        # This speeds up max and argmax operations.
+        # Get max confidence for each detection and create the mask
+        detections = np.zeros(
+            (self.max_detections, 6), np.float32
+        )  # initialize zero results
+        scores_output_quantized = self.interpreter.get_tensor(self.scores_tensor_index)[
+            0
+        ]  # (2100, NC)
+        max_scores_quantized = np.max(scores_output_quantized, axis=1)  # (2100,)
+        mask = max_scores_quantized >= self.min_score_quantized  # (2100,)
+
+        if not np.any(mask):
+            return detections  # empty results
+
+        max_scores_filtered_shiftedpositive = (
+            (max_scores_quantized[mask] - self.scores_zero_point) * self.scores_scale
+        ) + self.logit_shift_to_positive_values  # (N,1) shifted logit values
+        scores_output_quantized_filtered = scores_output_quantized[mask]
+
+        # dequantize boxes. NMS needs them to be in float format
+        # remove candidates with probabilities < threshold
+        boxes_output_quantized_filtered = (
+            self.interpreter.get_tensor(self.boxes_tensor_index)[0]
+        )[mask]  # (N, 64)
+        boxes_output_filtered = (
+            boxes_output_quantized_filtered.astype(np.float32) - self.boxes_zero_point
+        ) * self.boxes_scale
+
+        # 2. Decode DFL to distances (ltrb)
+        dfl_distributions = boxes_output_filtered.reshape(
+            -1, 4, self.reg_max
+        )  # (N, 4, 16)
+
+        # Softmax over the 16 bins
+        dfl_max = np.max(dfl_distributions, axis=2, keepdims=True)
+        dfl_exp = np.exp(dfl_distributions - dfl_max)
+        dfl_probs = dfl_exp / np.sum(dfl_exp, axis=2, keepdims=True)  # (N, 4, 16)
+
+        # Weighted sum: (N, 4, 16) * (16,) -> (N, 4)
+        distances = np.einsum("pcr,r->pc", dfl_probs, self.project)
+
+        # Calculate box corners in pixel coordinates
+        anchors_filtered = self.anchors[mask]
+        anchor_strides_filtered = self.anchor_strides[mask]
+        x1y1 = (
+            anchors_filtered - distances[:, [0, 1]]
+        ) * anchor_strides_filtered  # (N, 2)
+        x2y2 = (
+            anchors_filtered + distances[:, [2, 3]]
+        ) * anchor_strides_filtered  # (N, 2)
+        boxes_filtered_decoded = np.concatenate((x1y1, x2y2), axis=-1)  # (N, 4)
+
+        # 9. Apply NMS. Use logit scores here to defer sigmoid()
+        # until after filtering out redundant boxes
+        # Shift the logit scores to be non-negative (required by cv2)
+        indices = cv2.dnn.NMSBoxes(
+            bboxes=xyxy_to_xywh_for_nms(boxes_filtered_decoded),
+            scores=max_scores_filtered_shiftedpositive,
+            score_threshold=(
+                self.min_logit_value + self.logit_shift_to_positive_values
+            ),
+            nms_threshold=0.4,  # should this be a model config setting?
+        )
+        num_detections = len(indices)
+        if num_detections == 0:
+            return detections  # empty results
+
+        nms_indices = np.array(indices, dtype=np.int32).ravel()  # or .flatten()
+        if num_detections > self.max_detections:
+            nms_indices = nms_indices[: self.max_detections]
+            num_detections = self.max_detections
+        kept_logits_quantized = scores_output_quantized_filtered[nms_indices]
+        class_ids_post_nms = np.argmax(kept_logits_quantized, axis=1)
+
+        # Extract the final boxes and scores using fancy indexing
+        final_boxes = boxes_filtered_decoded[nms_indices]
+        final_scores_logits = (
+            max_scores_filtered_shiftedpositive[nms_indices]
+            - self.logit_shift_to_positive_values
+        )  # Unshifted logits
+
+        # Detections array format: [class_id, score, ymin, xmin, ymax, xmax]
+        detections[:num_detections, 0] = class_ids_post_nms
+        detections[:num_detections, 1] = 1.0 / (
+            1.0 + np.exp(-final_scores_logits)
+        )  # sigmoid
+        detections[:num_detections, 2] = final_boxes[:, 1] / self.model_height
+        detections[:num_detections, 3] = final_boxes[:, 0] / self.model_width
+        detections[:num_detections, 4] = final_boxes[:, 3] / self.model_height
+        detections[:num_detections, 5] = final_boxes[:, 2] / self.model_width
+        return detections
+
+    def _post_process_ssd(self):
+        boxes = self.interpreter.tensor(self.tensor_output_details[0]["index"])()[0]
+        class_ids = self.interpreter.tensor(self.tensor_output_details[1]["index"])()[0]
+        scores = self.interpreter.tensor(self.tensor_output_details[2]["index"])()[0]
+        count = int(
+            self.interpreter.tensor(self.tensor_output_details[3]["index"])()[0]
+        )
+
+        detections = np.zeros((self.max_detections, 6), np.float32)
+
+        for i in range(count):
+            if scores[i] < self.min_score:
+                break
+            if i == self.max_detections:
+                logger.debug("Too many detections (%s)", count)
+                break
+            detections[i] = [
+                class_ids[i],
+                float(scores[i]),
+                boxes[i][0],
+                boxes[i][1],
+                boxes[i][2],
+                boxes[i][3],
+            ]
+
+        return detections
 
 
 def tflite_load_delegate_interpreter(

frigate/detectors/plugins/cpu_tfl.py

@@ -7,7 +7,7 @@ from frigate.detectors.detection_api import DetectionApi
 from frigate.detectors.detector_config import BaseDetectorConfig
 from frigate.log import suppress_stderr_during
 
-from ..detector_utils import tflite_detect_raw, tflite_init
+from ..detector_utils import TFLiteDetectionModel
 
 try:
     from tflite_runtime.interpreter import Interpreter
@@ -40,6 +40,7 @@ class CpuDetectorConfig(BaseDetectorConfig):
 
 class CpuTfl(DetectionApi):
     type_key = DETECTOR_KEY
+    supported_models = TFLiteDetectionModel.supported_models
 
     def __init__(self, detector_config: CpuDetectorConfig):
         # Suppress TFLite delegate creation messages that bypass Python logging
@@ -49,7 +50,9 @@ class CpuTfl(DetectionApi):
                 num_threads=detector_config.num_threads or 3,
             )
 
-        tflite_init(self, interpreter)
+        self.tflite_model = TFLiteDetectionModel(
+            interpreter, detector_config.model, DETECTOR_KEY
+        )
 
     def detect_raw(self, tensor_input):
-        return tflite_detect_raw(self, tensor_input)
+        return self.tflite_model.detect_raw(tensor_input)

frigate/detectors/plugins/edgetpu_tfl.py

@@ -1,15 +1,13 @@
 import logging
-import math
 import os
 from typing import ClassVar, Literal
 
-import cv2
-import numpy as np
 from pydantic import ConfigDict, Field
 
 from frigate.detectors.detection_api import DetectionApi
-from frigate.detectors.detector_config import BaseDetectorConfig, ModelTypeEnum
-from frigate.util.model import xyxy_to_xywh_for_nms
+from frigate.detectors.detector_config import BaseDetectorConfig
+
+from ..detector_utils import TFLiteDetectionModel
 
 try:
     from tflite_runtime.interpreter import Interpreter, load_delegate
@@ -41,10 +39,7 @@ class EdgeTpuDetectorConfig(BaseDetectorConfig):
 
 class EdgeTpuTfl(DetectionApi):
     type_key = DETECTOR_KEY
-    supported_models = [
-        ModelTypeEnum.ssd,
-        ModelTypeEnum.yologeneric,
-    ]
+    supported_models = TFLiteDetectionModel.supported_models
 
     def __init__(self, detector_config: EdgeTpuDetectorConfig):
         device_config = {}
@@ -60,7 +55,7 @@ class EdgeTpuTfl(DetectionApi):
             logger.info(f"Attempting to load TPU as {device_type}")
             edge_tpu_delegate = load_delegate("libedgetpu.so.1.0", device_config)
             logger.info("TPU found")
-            self.interpreter = Interpreter(
+            interpreter = Interpreter(
                 model_path=detector_config.model.path,
                 experimental_delegates=[edge_tpu_delegate],
             )
@@ -78,298 +73,9 @@ class EdgeTpuTfl(DetectionApi):
 
             raise
 
-        self.interpreter.allocate_tensors()
-
-        self.tensor_input_details = self.interpreter.get_input_details()
-        self.tensor_output_details = self.interpreter.get_output_details()
-        self.model_width = detector_config.model.width
-        self.model_height = detector_config.model.height
-
-        self.min_score = 0.4
-        self.max_detections = 20
-
-        self.model_type = detector_config.model.model_type
-        self.model_requires_int8 = self.tensor_input_details[0]["dtype"] == np.int8
-
-        if self.model_type == ModelTypeEnum.yologeneric:
-            logger.debug("Using YOLO preprocessing/postprocessing")
-
-            if len(self.tensor_output_details) not in [2, 3]:
-                logger.error(
-                    f"Invalid count of output tensors in YOLO model. Found {len(self.tensor_output_details)}, expecting 2 or 3."
-                )
-                raise
-
-            self.reg_max = 16  # = 64 dfl_channels // 4 # YOLO standard
-            self.min_logit_value = np.log(
-                self.min_score / (1 - self.min_score)
-            )  # for filtering
-            self._generate_anchors_and_strides()  # decode bounding box DFL
-            self.project = np.arange(
-                self.reg_max, dtype=np.float32
-            )  # for decoding bounding box DFL information
-
-            # Determine YOLO tensor indices and quantization scales for
-            # boxes and class_scores the tensor ordering and names are
-            # not reliable, so use tensor shape to detect which tensor
-            # holds boxes or class scores.
-            # The tensors have shapes (B, N, C)
-            # where N is the number of candidates (=2100 for 320x320)
-            # this may guess wrong if the number of classes is exactly 64
-            output_boxes_index = None
-            output_classes_index = None
-            for i, x in enumerate(self.tensor_output_details):
-                # the nominal index seems to start at 1 instead of 0
-                if len(x["shape"]) == 3 and x["shape"][2] == 64:
-                    output_boxes_index = i
-                elif len(x["shape"]) == 3 and x["shape"][2] > 1:
-                    # require the number of classes to be more than 1
-                    # to differentiate from (not used) max score tensor
-                    output_classes_index = i
-            if output_boxes_index is None or output_classes_index is None:
-                logger.warning("Unrecognized model output, unexpected tensor shapes.")
-                output_classes_index = (
-                    0
-                    if (output_boxes_index is None or output_classes_index == 1)
-                    else 1
-                )  # 0 is default guess
-                output_boxes_index = 1 if (output_boxes_index == 0) else 0
-
-            scores_details = self.tensor_output_details[output_classes_index]
-            self.scores_tensor_index = scores_details["index"]
-            self.scores_scale, self.scores_zero_point = scores_details["quantization"]
-            # calculate the quantized version of the min_score
-            self.min_score_quantized = int(
-                (self.min_logit_value / self.scores_scale) + self.scores_zero_point
-            )
-            self.logit_shift_to_positive_values = (
-                max(0, math.ceil((128 + self.scores_zero_point) * self.scores_scale))
-                + 1
-            )  # round up
-
-            boxes_details = self.tensor_output_details[output_boxes_index]
-            self.boxes_tensor_index = boxes_details["index"]
-            self.boxes_scale, self.boxes_zero_point = boxes_details["quantization"]
-
-        elif self.model_type == ModelTypeEnum.ssd:
-            logger.debug("Using SSD preprocessing/postprocessing")
-
-            # SSD model indices (4 outputs: boxes, class_ids, scores, count)
-            for x in self.tensor_output_details:
-                if len(x["shape"]) == 3:
-                    self.output_boxes_index = x["index"]
-                elif len(x["shape"]) == 1:
-                    self.output_count_index = x["index"]
-
-            self.output_class_ids_index = None
-            self.output_class_scores_index = None
-
-        else:
-            raise Exception(
-                f"{self.model_type} is currently not supported for edgetpu. See the docs for more info on supported models."
-            )
-
-    def _generate_anchors_and_strides(self):
-        # for decoding the bounding box DFL information into xy coordinates
-        all_anchors = []
-        all_strides = []
-        strides = (8, 16, 32)  # YOLO's small, medium, large detection heads
-
-        for stride in strides:
-            feat_h, feat_w = self.model_height // stride, self.model_width // stride
-
-            grid_y, grid_x = np.meshgrid(
-                np.arange(feat_h, dtype=np.float32),
-                np.arange(feat_w, dtype=np.float32),
-                indexing="ij",
-            )
-
-            grid_coords = np.stack((grid_x.flatten(), grid_y.flatten()), axis=1)
-            anchor_points = grid_coords + 0.5
-
-            all_anchors.append(anchor_points)
-            all_strides.append(np.full((feat_h * feat_w, 1), stride, dtype=np.float32))
-
-        self.anchors = np.concatenate(all_anchors, axis=0)
-        self.anchor_strides = np.concatenate(all_strides, axis=0)
-
-    def determine_indexes_for_non_yolo_models(self):
-        """Legacy method for SSD models."""
-        if (
-            self.output_class_ids_index is None
-            or self.output_class_scores_index is None
-        ):
-            for i in range(4):
-                index = self.tensor_output_details[i]["index"]
-                if (
-                    index != self.output_boxes_index
-                    and index != self.output_count_index
-                ):
-                    if (
-                        np.mod(np.float32(self.interpreter.tensor(index)()[0][0]), 1)
-                        == 0.0
-                    ):
-                        self.output_class_ids_index = index
-                    else:
-                        self.output_scores_index = index
-
-    def pre_process(self, tensor_input):
-        if self.model_requires_int8:
-            tensor_input = np.bitwise_xor(tensor_input, 128).view(
-                np.int8
-            )  # shift by -128
-        return tensor_input
+        self.tflite_model = TFLiteDetectionModel(
+            interpreter, detector_config.model, DETECTOR_KEY
+        )
 
     def detect_raw(self, tensor_input):
-        tensor_input = self.pre_process(tensor_input)
-
-        self.interpreter.set_tensor(self.tensor_input_details[0]["index"], tensor_input)
-        self.interpreter.invoke()
-
-        if self.model_type == ModelTypeEnum.yologeneric:
-            # Multi-tensor YOLO model with (non-standard B(H*W)C output format).
-            # (the comments indicate the shape of tensors,
-            # using "2100" as the anchor count (for image size of 320x320),
-            # "NC" as number of classes,
-            # "N" as the count that survive after min-score filtering)
-            # TENSOR A) class scores (1, 2100, NC) with logit values
-            # TENSOR B) box coordinates (1, 2100, 64) encoded as dfl scores
-            # Recommend that the model clamp the logit values in tensor (A)
-            # to the range [-4,+4] to preserve precision from [2%,98%]
-            # and because NMS requires the min_score parameter to be >= 0
-
-            # don't dequantize scores data yet, wait until the low-confidence
-            # candidates are filtered out from the overall result set.
-            # This reduces the work and makes post-processing faster.
-            # this method works with raw quantized numbers when possible,
-            # which relies on the value of the scale factor to be >0.
-            # This speeds up max and argmax operations.
-            # Get max confidence for each detection and create the mask
-            detections = np.zeros(
-                (self.max_detections, 6), np.float32
-            )  # initialize zero results
-            scores_output_quantized = self.interpreter.get_tensor(
-                self.scores_tensor_index
-            )[0]  # (2100, NC)
-            max_scores_quantized = np.max(scores_output_quantized, axis=1)  # (2100,)
-            mask = max_scores_quantized >= self.min_score_quantized  # (2100,)
-
-            if not np.any(mask):
-                return detections  # empty results
-
-            max_scores_filtered_shiftedpositive = (
-                (max_scores_quantized[mask] - self.scores_zero_point)
-                * self.scores_scale
-            ) + self.logit_shift_to_positive_values  # (N,1) shifted logit values
-            scores_output_quantized_filtered = scores_output_quantized[mask]
-
-            # dequantize boxes. NMS needs them to be in float format
-            # remove candidates with probabilities < threshold
-            boxes_output_quantized_filtered = (
-                self.interpreter.get_tensor(self.boxes_tensor_index)[0]
-            )[mask]  # (N, 64)
-            boxes_output_filtered = (
-                boxes_output_quantized_filtered.astype(np.float32)
-                - self.boxes_zero_point
-            ) * self.boxes_scale
-
-            # 2. Decode DFL to distances (ltrb)
-            dfl_distributions = boxes_output_filtered.reshape(
-                -1, 4, self.reg_max
-            )  # (N, 4, 16)
-
-            # Softmax over the 16 bins
-            dfl_max = np.max(dfl_distributions, axis=2, keepdims=True)
-            dfl_exp = np.exp(dfl_distributions - dfl_max)
-            dfl_probs = dfl_exp / np.sum(dfl_exp, axis=2, keepdims=True)  # (N, 4, 16)
-
-            # Weighted sum: (N, 4, 16) * (16,) -> (N, 4)
-            distances = np.einsum("pcr,r->pc", dfl_probs, self.project)
-
-            # Calculate box corners in pixel coordinates
-            anchors_filtered = self.anchors[mask]
-            anchor_strides_filtered = self.anchor_strides[mask]
-            x1y1 = (
-                anchors_filtered - distances[:, [0, 1]]
-            ) * anchor_strides_filtered  # (N, 2)
-            x2y2 = (
-                anchors_filtered + distances[:, [2, 3]]
-            ) * anchor_strides_filtered  # (N, 2)
-            boxes_filtered_decoded = np.concatenate((x1y1, x2y2), axis=-1)  # (N, 4)
-
-            # 9. Apply NMS. Use logit scores here to defer sigmoid()
-            # until after filtering out redundant boxes
-            # Shift the logit scores to be non-negative (required by cv2)
-            indices = cv2.dnn.NMSBoxes(
-                bboxes=xyxy_to_xywh_for_nms(boxes_filtered_decoded),
-                scores=max_scores_filtered_shiftedpositive,
-                score_threshold=(
-                    self.min_logit_value + self.logit_shift_to_positive_values
-                ),
-                nms_threshold=0.4,  # should this be a model config setting?
-            )
-            num_detections = len(indices)
-            if num_detections == 0:
-                return detections  # empty results
-
-            nms_indices = np.array(indices, dtype=np.int32).ravel()  # or .flatten()
-            if num_detections > self.max_detections:
-                nms_indices = nms_indices[: self.max_detections]
-                num_detections = self.max_detections
-            kept_logits_quantized = scores_output_quantized_filtered[nms_indices]
-            class_ids_post_nms = np.argmax(kept_logits_quantized, axis=1)
-
-            # Extract the final boxes and scores using fancy indexing
-            final_boxes = boxes_filtered_decoded[nms_indices]
-            final_scores_logits = (
-                max_scores_filtered_shiftedpositive[nms_indices]
-                - self.logit_shift_to_positive_values
-            )  # Unshifted logits
-
-            # Detections array format: [class_id, score, ymin, xmin, ymax, xmax]
-            detections[:num_detections, 0] = class_ids_post_nms
-            detections[:num_detections, 1] = 1.0 / (
-                1.0 + np.exp(-final_scores_logits)
-            )  # sigmoid
-            detections[:num_detections, 2] = final_boxes[:, 1] / self.model_height
-            detections[:num_detections, 3] = final_boxes[:, 0] / self.model_width
-            detections[:num_detections, 4] = final_boxes[:, 3] / self.model_height
-            detections[:num_detections, 5] = final_boxes[:, 2] / self.model_width
-            return detections
-
-        elif self.model_type == ModelTypeEnum.ssd:
-            self.determine_indexes_for_non_yolo_models()
-            boxes = self.interpreter.tensor(self.tensor_output_details[0]["index"])()[0]
-            class_ids = self.interpreter.tensor(
-                self.tensor_output_details[1]["index"]
-            )()[0]
-            scores = self.interpreter.tensor(self.tensor_output_details[2]["index"])()[
-                0
-            ]
-            count = int(
-                self.interpreter.tensor(self.tensor_output_details[3]["index"])()[0]
-            )
-
-            detections = np.zeros((self.max_detections, 6), np.float32)
-
-            for i in range(count):
-                if scores[i] < self.min_score:
-                    break
-                if i == self.max_detections:
-                    logger.debug(f"Too many detections ({count})!")
-                    break
-                detections[i] = [
-                    class_ids[i],
-                    float(scores[i]),
-                    boxes[i][0],
-                    boxes[i][1],
-                    boxes[i][2],
-                    boxes[i][3],
-                ]
-
-            return detections
-
-        else:
-            raise Exception(
-                f"{self.model_type} is currently not supported for edgetpu. See the docs for more info on supported models."
-            )
+        return self.tflite_model.detect_raw(tensor_input)

frigate/detectors/plugins/teflon_tfl.py

@@ -7,8 +7,7 @@ from frigate.detectors.detection_api import DetectionApi
 from frigate.detectors.detector_config import BaseDetectorConfig
 
 from ..detector_utils import (
-    tflite_detect_raw,
-    tflite_init,
+    TFLiteDetectionModel,
     tflite_load_delegate_interpreter,
 )
 
@@ -30,6 +29,7 @@ class TeflonDetectorConfig(BaseDetectorConfig):
 
 class TeflonTfl(DetectionApi):
     type_key = DETECTOR_KEY
+    supported_models = TFLiteDetectionModel.supported_models
 
     def __init__(self, detector_config: TeflonDetectorConfig):
         # Location in Debian's mesa-teflon-delegate
@@ -39,7 +39,9 @@ class TeflonTfl(DetectionApi):
         interpreter = tflite_load_delegate_interpreter(
             delegate_library, detector_config, device_config
         )
-        tflite_init(self, interpreter)
+        self.tflite_model = TFLiteDetectionModel(
+            interpreter, detector_config.model, DETECTOR_KEY
+        )
 
     def detect_raw(self, tensor_input):
-        return tflite_detect_raw(self, tensor_input)
+        return self.tflite_model.detect_raw(tensor_input)