Merge 36c61a3607 into 5f6043aa92

* honor enabled flag for custom classification models

for both startup and dynamically, even though the UI doesn't currently have a way to toggle dynamically

* add test

docs/docs/configuration/advanced/system.md

@@ -72,10 +72,10 @@ Variables prefixed with `FRIGATE_` can be referenced in config fields that suppo
 
 Navigate to <NavPath path="Settings > System > Environment variables" /> to add or edit environment variables.
 
-| Field     | Description                                               |
-| --------- | --------------------------------------------------------- |
-| **Key**   | The environment variable name (e.g., `FRIGATE_MQTT_USER`) |
-| **Value** | The value for the variable                                |
+| Field             | Description                                               |
+| ----------------- | --------------------------------------------------------- |
+| **Variable name** | The environment variable name (e.g., `FRIGATE_MQTT_USER`) |
+| **Value**         | The value for the variable                                |
 
 Variables defined here can be referenced elsewhere in your configuration using the `{FRIGATE_VARIABLE_NAME}` syntax.
 

frigate/embeddings/maintainer.py

@@ -200,6 +200,9 @@ class EmbeddingMaintainer(threading.Thread):
             )
 
         for model_config in self.config.classification.custom.values():
+            if not model_config.enabled:
+                continue
+
             self.realtime_processors.append(
                 CustomStateClassificationProcessor(
                     self.config, model_config, self.requestor, self.metrics
@@ -332,6 +335,25 @@ class EmbeddingMaintainer(threading.Thread):
         for processor in self.post_processors:
             processor.update_config(topic, payload)
 
+    def _remove_custom_classification_processor(self, model_name: str) -> None:
+        """Shut down and drop any running processor for a custom model."""
+        remaining = []
+        for processor in self.realtime_processors:
+            if (
+                isinstance(
+                    processor,
+                    (
+                        CustomStateClassificationProcessor,
+                        CustomObjectClassificationProcessor,
+                    ),
+                )
+                and processor.model_config.name == model_name
+            ):
+                processor.shutdown()
+            else:
+                remaining.append(processor)
+        self.realtime_processors = remaining
+
     def _handle_custom_classification_update(
         self, topic: str, model_config: Any
     ) -> None:
@@ -339,23 +361,7 @@ class EmbeddingMaintainer(threading.Thread):
         model_name = topic.split("/")[-1]
 
         if model_config is None:
-            remaining = []
-            for processor in self.realtime_processors:
-                if (
-                    isinstance(
-                        processor,
-                        (
-                            CustomStateClassificationProcessor,
-                            CustomObjectClassificationProcessor,
-                        ),
-                    )
-                    and processor.model_config.name == model_name
-                ):
-                    processor.shutdown()
-                else:
-                    remaining.append(processor)
-            self.realtime_processors = remaining
-
+            self._remove_custom_classification_processor(model_name)
             logger.info(
                 f"Successfully removed classification processor for model: {model_name}"
             )
@@ -363,6 +369,13 @@ class EmbeddingMaintainer(threading.Thread):
 
         self.config.classification.custom[model_name] = model_config
 
+        # A disabled model must not run; tear down any existing processor and
+        # do not register a new one.
+        if not model_config.enabled:
+            self._remove_custom_classification_processor(model_name)
+            logger.info(f"Disabled classification processor for model: {model_name}")
+            return
+
         # Check if processor already exists
         for processor in self.realtime_processors:
             if isinstance(
@@ -702,7 +715,11 @@ class EmbeddingMaintainer(threading.Thread):
             and "license_plate" not in camera_config.objects.track
         )
 
-        if not dedicated_lpr_enabled and len(self.config.classification.custom) == 0:
+        has_enabled_custom = any(
+            c.enabled for c in self.config.classification.custom.values()
+        )
+
+        if not dedicated_lpr_enabled and not has_enabled_custom:
             # no active features that use this data
             return
 

frigate/test/test_classification_enabled.py

@@ -0,0 +1,106 @@
+"""Tests that disabled custom classification models are not registered or run."""
+
+import sys
+import unittest
+from unittest.mock import MagicMock
+
+# Mock TFLite before importing the maintainer / classification modules
+_MOCK_MODULES = [
+    "tflite_runtime",
+    "tflite_runtime.interpreter",
+    "ai_edge_litert",
+    "ai_edge_litert.interpreter",
+]
+for mod in _MOCK_MODULES:
+    if mod not in sys.modules:
+        sys.modules[mod] = MagicMock()
+
+from frigate.data_processing.real_time.custom_classification import (  # noqa: E402
+    CustomObjectClassificationProcessor,
+)
+from frigate.embeddings.maintainer import EmbeddingMaintainer  # noqa: E402
+
+
+class TestCustomClassificationEnabledGating(unittest.TestCase):
+    """A model with enabled: false must not keep a processor registered."""
+
+    def _make_maintainer(self) -> EmbeddingMaintainer:
+        # Bypass the heavy __init__; only the attributes touched by the
+        # config update path are needed for these tests.
+        maintainer = EmbeddingMaintainer.__new__(EmbeddingMaintainer)
+        maintainer.realtime_processors = []
+        maintainer.config = MagicMock()
+        maintainer.config.classification.custom = {}
+        maintainer.requestor = MagicMock()
+        maintainer.metrics = MagicMock()
+        maintainer.event_metadata_publisher = MagicMock()
+        return maintainer
+
+    def _make_model_config(self, name: str, enabled: bool) -> MagicMock:
+        model_config = MagicMock()
+        model_config.name = name
+        model_config.enabled = enabled
+        model_config.state_config = None
+        return model_config
+
+    def _make_processor(self, name: str) -> MagicMock:
+        processor = MagicMock(spec=CustomObjectClassificationProcessor)
+        processor.model_config = MagicMock()
+        processor.model_config.name = name
+        return processor
+
+    def test_disabled_update_tears_down_existing_processor(self):
+        """Toggling a running model to disabled shuts down and drops its processor."""
+        maintainer = self._make_maintainer()
+        processor = self._make_processor("atli")
+        maintainer.realtime_processors = [processor]
+
+        maintainer._handle_custom_classification_update(
+            "config/classification/custom/atli",
+            self._make_model_config("atli", enabled=False),
+        )
+
+        processor.shutdown.assert_called_once()
+        self.assertEqual(maintainer.realtime_processors, [])
+
+    def test_disabled_update_does_not_register_processor(self):
+        """A disabled model that has no processor is never registered."""
+        maintainer = self._make_maintainer()
+
+        maintainer._handle_custom_classification_update(
+            "config/classification/custom/atli",
+            self._make_model_config("atli", enabled=False),
+        )
+
+        self.assertEqual(maintainer.realtime_processors, [])
+
+    def test_disabled_update_leaves_other_processors_untouched(self):
+        """Disabling one model must not affect other running processors."""
+        maintainer = self._make_maintainer()
+        other = self._make_processor("simbi")
+        maintainer.realtime_processors = [other]
+
+        maintainer._handle_custom_classification_update(
+            "config/classification/custom/atli",
+            self._make_model_config("atli", enabled=False),
+        )
+
+        other.shutdown.assert_not_called()
+        self.assertEqual(maintainer.realtime_processors, [other])
+
+    def test_removed_model_tears_down_processor(self):
+        """A None payload (model deleted) still shuts down its processor."""
+        maintainer = self._make_maintainer()
+        processor = self._make_processor("atli")
+        maintainer.realtime_processors = [processor]
+
+        maintainer._handle_custom_classification_update(
+            "config/classification/custom/atli", None
+        )
+
+        processor.shutdown.assert_called_once()
+        self.assertEqual(maintainer.realtime_processors, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

frigate/video/ffmpeg.py

@@ -9,6 +9,7 @@ from collections import deque
 from datetime import UTC, datetime, timedelta
 from multiprocessing import Queue, Value
 from multiprocessing.synchronize import Event as MpEvent
+from pathlib import Path
 from typing import Any
 
 from frigate.camera import CameraMetrics
@@ -22,7 +23,7 @@ from frigate.config.camera.updater import (
     CameraConfigUpdateEnum,
     CameraConfigUpdateSubscriber,
 )
-from frigate.const import PROCESS_PRIORITY_HIGH
+from frigate.const import CACHE_DIR, PROCESS_PRIORITY_HIGH
 from frigate.log import LogPipe
 from frigate.util.builtin import EventsPerSecond, get_record_segment_time
 from frigate.util.ffmpeg import start_or_restart_ffmpeg, stop_ffmpeg
@@ -447,6 +448,38 @@ class CameraWatchdog(threading.Thread):
                     invalid_stale = invalid_stale_condition
 
                     if cache_stale or valid_stale or invalid_stale:
+                        # The staleness above is measured from the recording
+                        # maintainer's IPC heartbeat, which lags whenever the
+                        # maintainer falls behind (e.g. "Unable to keep up with
+                        # recording segments in cache"). A late message is not
+                        # a dead recorder: corroborate against the cache dir
+                        # before restarting, otherwise every camera restarts
+                        # together on maintainer lag and the resulting segment
+                        # churn makes the overload worse.
+                        if not invalid_stale:
+                            newest_on_disk = max(
+                                (
+                                    f.stat().st_mtime
+                                    for f in Path(CACHE_DIR).glob(
+                                        f"{self.config.name}@*"
+                                    )
+                                ),
+                                default=0.0,
+                            )
+                            if (
+                                newest_on_disk > 0
+                                and now_utc.timestamp() - newest_on_disk
+                                < self.record_stale_threshold
+                            ):
+                                self.logger.warning(
+                                    f"Recording heartbeat for {self.config.name} is stale but a cache "
+                                    f"segment is only {now_utc.timestamp() - newest_on_disk:.0f}s old — "
+                                    "skipping the record process restart (maintainer heartbeat lag, "
+                                    "not a recording failure)."
+                                )
+                                self.latest_cache_segment_time = newest_on_disk
+                                continue
+
                         if cache_stale:
                             reason = "No new recording segments were created"
                         elif valid_stale:

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

@@ -1490,7 +1490,14 @@
       "keyLabel": "Key",
       "valueLabel": "Value",
       "keyPlaceholder": "New key",
-      "remove": "Remove"
+      "remove": "Remove",
+      "providerNameLabel": "Provider name",
+      "providerNamePlaceholder": "e.g., openai",
+      "variableNameLabel": "Variable name",
+      "variableNamePlaceholder": "e.g., MY_VARIABLE",
+      "loggerNameLabel": "Logger name",
+      "loggerNamePlaceholder": "e.g., frigate.record",
+      "keyPatternError": "Use only letters, numbers, hyphens, and underscores (no spaces)"
     },
     "knownPlates": {
       "namePlaceholder": "e.g., Wife's Car",

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

@@ -7,7 +7,13 @@ const environmentVars: SectionConfigOverrides = {
     advancedFields: [],
     uiSchema: {
       additionalProperties: {
-        "ui:options": { size: "lg" },
+        "ui:options": {
+          size: "lg",
+          additionalPropertyKeyLabel:
+            "configForm.additionalProperties.variableNameLabel",
+          additionalPropertyKeyPlaceholder:
+            "configForm.additionalProperties.variableNamePlaceholder",
+        },
       },
     },
   },

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

@@ -9,7 +9,15 @@ const genai: SectionConfigOverrides = {
     uiSchema: {
       "ui:options": { disableNestedCard: true },
       "*": {
-        "ui:options": { disableNestedCard: true },
+        "ui:options": {
+          disableNestedCard: true,
+          additionalPropertyKeyLabel:
+            "configForm.additionalProperties.providerNameLabel",
+          additionalPropertyKeyPlaceholder:
+            "configForm.additionalProperties.providerNamePlaceholder",
+          additionalPropertyKeyPattern: "^[a-zA-Z0-9_-]+$",
+          preventKeyRename: true,
+        },
         "ui:order": [
           "provider",
           "api_key",

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

@@ -12,7 +12,13 @@ const logger: SectionConfigOverrides = {
       },
       logs: {
         additionalProperties: {
-          "ui:options": { enumI18nPrefix: "logger.logLevel" },
+          "ui:options": {
+            enumI18nPrefix: "logger.logLevel",
+            additionalPropertyKeyLabel:
+              "configForm.additionalProperties.loggerNameLabel",
+            additionalPropertyKeyPlaceholder:
+              "configForm.additionalProperties.loggerNamePlaceholder",
+          },
         },
       },
     },

web/src/components/config-form/theme/templates/WrapIfAdditionalTemplate.tsx

@@ -6,12 +6,14 @@ import {
   StrictRJSFSchema,
   WrapIfAdditionalTemplateProps,
 } from "@rjsf/utils";
+import { useEffect, useMemo, useState, type FocusEvent } from "react";
 import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
 import { Label } from "@/components/ui/label";
 import { cn } from "@/lib/utils";
 import { useTranslation } from "react-i18next";
 import { LuTrash2 } from "react-icons/lu";
+import type { ConfigFormContext } from "@/types/configForm";
 
 export function WrapIfAdditionalTemplate<
   T = unknown,
@@ -30,6 +32,7 @@ export function WrapIfAdditionalTemplate<
     onKeyRenameBlur,
     readonly,
     required,
+    registry,
     schema,
     uiSchema,
   } = props;
@@ -38,6 +41,55 @@ export function WrapIfAdditionalTemplate<
 
   const additional = ADDITIONAL_PROPERTY_FLAG in schema;
 
+  const uiOptions = getUiOptions(uiSchema);
+  const keyIsReadonly = uiOptions.additionalPropertyKeyReadonly === true;
+
+  const keyLabelKey =
+    typeof uiOptions.additionalPropertyKeyLabel === "string"
+      ? uiOptions.additionalPropertyKeyLabel
+      : undefined;
+  const keyPlaceholderKey =
+    typeof uiOptions.additionalPropertyKeyPlaceholder === "string"
+      ? uiOptions.additionalPropertyKeyPlaceholder
+      : undefined;
+  const keyPattern =
+    typeof uiOptions.additionalPropertyKeyPattern === "string"
+      ? uiOptions.additionalPropertyKeyPattern
+      : undefined;
+  const preventKeyRename = uiOptions.preventKeyRename === true;
+
+  const formContext = registry?.formContext as ConfigFormContext | undefined;
+
+  // optionally, lock the key once it's been saved
+  const baseline = formContext?.baselineFormData;
+  const keyLocked =
+    preventKeyRename &&
+    typeof label === "string" &&
+    !!baseline &&
+    Object.prototype.hasOwnProperty.call(baseline, label);
+
+  // controlled key value so we can validate live and block invalid renames.
+  const [keyValue, setKeyValue] = useState<string>(label ?? "");
+  useEffect(() => {
+    setKeyValue(label ?? "");
+  }, [label]);
+
+  const keyRegex = useMemo(
+    () => (keyPattern ? new RegExp(keyPattern) : undefined),
+    [keyPattern],
+  );
+  const keyError = useMemo(() => {
+    if (!keyRegex || keyLocked) return null;
+    if (!keyRegex.test(keyValue)) {
+      return t("configForm.additionalProperties.keyPatternError", {
+        ns: "views/settings",
+        defaultValue:
+          "Use only letters, numbers, hyphens, and underscores (no spaces)",
+      });
+    }
+    return null;
+  }, [keyRegex, keyLocked, keyValue, t]);
+
   if (!additional) {
     return (
       <div className={classNames} style={style}>
@@ -47,20 +99,26 @@ export function WrapIfAdditionalTemplate<
   }
 
   const keyId = `${id}-key`;
-  const keyLabel = t("configForm.additionalProperties.keyLabel", {
-    ns: "views/settings",
-  });
+  const keyLabel = keyLabelKey
+    ? t(keyLabelKey, { ns: "views/settings" })
+    : t("configForm.additionalProperties.keyLabel", { ns: "views/settings" });
   const valueLabel = t("configForm.additionalProperties.valueLabel", {
     ns: "views/settings",
   });
-  const keyPlaceholder = t("configForm.additionalProperties.keyPlaceholder", {
-    ns: "views/settings",
-  });
+  const keyPlaceholder = keyPlaceholderKey
+    ? t(keyPlaceholderKey, { ns: "views/settings" })
+    : t("configForm.additionalProperties.keyPlaceholder", {
+        ns: "views/settings",
+      });
   const removeLabel = t("configForm.additionalProperties.remove", {
     ns: "views/settings",
   });
-  const uiOptions = getUiOptions(uiSchema);
-  const keyIsReadonly = uiOptions.additionalPropertyKeyReadonly === true;
+
+  const commitKeyRename = (e: FocusEvent<HTMLInputElement>) => {
+    if (readonly) return;
+    if (keyError) return;
+    onKeyRenameBlur?.(e);
+  };
 
   return (
     <div
@@ -70,23 +128,30 @@ export function WrapIfAdditionalTemplate<
       {!keyIsReadonly && (
         <div className="col-span-12 space-y-2 md:col-span-2">
           {displayLabel && <Label htmlFor={keyId}>{keyLabel}</Label>}
-          {keyIsReadonly ? (
+          {keyLocked ? (
             <div
               id={keyId}
-              className="flex items-center text-sm text-muted-foreground"
+              className="flex items-center break-all text-sm text-primary-variant"
             >
               {label}
             </div>
           ) : (
-            <Input
-              id={keyId}
-              name={keyId}
-              required={required}
-              defaultValue={label}
-              placeholder={keyPlaceholder}
-              disabled={disabled || readonly}
-              onBlur={!readonly ? onKeyRenameBlur : undefined}
-            />
+            <>
+              <Input
+                id={keyId}
+                name={keyId}
+                required={required}
+                value={keyValue}
+                placeholder={keyPlaceholder}
+                disabled={disabled || readonly}
+                onChange={(e) => setKeyValue(e.target.value)}
+                onBlur={!readonly ? commitKeyRename : undefined}
+                aria-invalid={keyError ? true : undefined}
+              />
+              {keyError && (
+                <p className="text-xs text-destructive">{keyError}</p>
+              )}
+            </>
           )}
         </div>
       )}