add docs note about privacy masks

The wizard grouped tracked objects by camera and 6 hour block, oldest first, then kept the first 100. With more than 100 groups that was always the oldest objects, which often have no snapshot or thumbnail left on disk, so no examples were generated. Shuffle the selection before truncating, and keep extracting from the remaining tracked objects until 100 usable images are found.

docs/docs/troubleshooting/faqs.md

@@ -53,6 +53,14 @@ go2rtc:
 
 Point the camera's inputs at the restream as described in the [restream docs](/configuration/restream.md), and swap `detect -> width` and `detect -> height` to match the rotated resolution.
 
+### Can I add a privacy mask to hide part of my camera's view?
+
+Frigate does not have privacy masks. [Motion masks and object filter masks](../configuration/masks.md) only affect detection, they don't hide anything in live view, recordings, or snapshots.
+
+Privacy masks are best configured in the camera's firmware settings so the area is blacked out before the video ever leaves the camera and no extra processing is needed. Check there first.
+
+If your camera does not support privacy masks, there is no efficient alternative. Frigate copies the camera's video into recordings and live view without decoding it, so part of the image can't be hidden without transcoding (re-encoding) the stream. This can be done with a custom ffmpeg filter in go2rtc, but it is not recommended. Every masked camera needs a continuous re-encode, which significantly increases CPU usage, especially for high resolution streams.
+
 ### My mjpeg stream or snapshots look green and crazy
 
 This almost always means that the width/height defined for your camera are not correct. Double check the resolution with VLC or another player. Also make sure you don't have the width and height values backwards.

frigate/util/classification.py

@@ -747,8 +747,14 @@ def collect_object_classification_examples(
     selected_events = _select_balanced_events(events, target_count=100)
     logger.debug(f"Selected {len(selected_events)} events")
 
-    # Step 3: Extract thumbnails from events
-    thumbnails = _extract_event_thumbnails(selected_events, temp_dir)
+    # Step 3: Extract thumbnails from events, falling back to the remaining
+    # events when the selected ones have no image on disk
+    selected_ids = {e.id for e in selected_events}
+    remaining_events = [e for e in events if e.id not in selected_ids]
+    random.shuffle(remaining_events)
+    thumbnails = _extract_event_thumbnails(
+        selected_events + remaining_events, temp_dir, target_count=100
+    )
     logger.debug(f"Successfully extracted {len(thumbnails)} thumbnails")
 
     # Step 4: Select 24 most visually distinct thumbnails
@@ -833,10 +839,16 @@ def _select_balanced_events(
         else:
             selected.extend(remaining)
 
+    # groups are ordered oldest first, so truncating unshuffled keeps only the
+    # oldest events, which are the least likely to still have images on disk
+    random.shuffle(selected)
+
     return selected[:target_count]
 
 
-def _extract_event_thumbnails(events: list[Event], output_dir: str) -> list[str]:
+def _extract_event_thumbnails(
+    events: list[Event], output_dir: str, target_count: int = 100
+) -> list[str]:
     """
     Extract a training image for each event.
 
@@ -850,8 +862,9 @@ def _extract_event_thumbnails(events: list[Event], output_dir: str) -> list[str]
     using a step ladder sized from the box/region area ratio.
 
     Args:
-        events: List of Event objects
+        events: List of Event objects, in order of preference
         output_dir: Directory to save crops
+        target_count: Number of images to extract before stopping
 
     Returns:
         List of paths to successfully extracted images
@@ -859,6 +872,9 @@ def _extract_event_thumbnails(events: list[Event], output_dir: str) -> list[str]
     image_paths = []
 
     for idx, event in enumerate(events):
+        if len(image_paths) >= target_count:
+            break
+
         try:
             img = _load_event_classification_crop(event)
             if img is None:

web/e2e/specs/system-health.spec.ts

@@ -14,6 +14,17 @@ const NOW = Math.floor(Date.now() / 1000);
 // the fixture detector runs at 75.5 ms, above the live warning threshold
 const QUIET_STATS = { detectors: { cpu: { inference_speed: 10 } } };
 
+// the fixture has no go2rtc streams, which gives every camera a live view hint
+const RESTREAMED = {
+  go2rtc: {
+    streams: {
+      front_door: ["rtsp://x"],
+      backyard: ["rtsp://x"],
+      garage: ["rtsp://x"],
+    },
+  },
+};
+
 const ERROR_NOTICE = {
   id: "model_download_failed:yolo/model.onnx",
   kind: "model_download_failed",
@@ -51,6 +62,7 @@ test.describe("System — Health tab @medium", () => {
     frigateApp,
   }) => {
     await frigateApp.installDefaults({
+      config: RESTREAMED,
       stats: QUIET_STATS,
       notices: [ERROR_NOTICE, EVENT_NOTICE],
     });
@@ -84,6 +96,7 @@ test.describe("System — Health tab @medium", () => {
   for (const action of ["acknowledge", "mute"] as const) {
     test(`${action} posts and removes the row`, async ({ frigateApp }) => {
       await frigateApp.installDefaults({
+        config: RESTREAMED,
         stats: QUIET_STATS,
         notices: [EVENT_NOTICE],
       });
@@ -126,7 +139,10 @@ test.describe("System — Health tab @medium", () => {
   }
 
   test("empty state with no notices", async ({ frigateApp }) => {
-    await frigateApp.installDefaults({ stats: QUIET_STATS });
+    await frigateApp.installDefaults({
+      config: RESTREAMED,
+      stats: QUIET_STATS,
+    });
     await frigateApp.goto("/system#health");
 
     await expect(
@@ -329,6 +345,7 @@ test.describe("System — Health tab @medium", () => {
     frigateApp,
   }) => {
     await frigateApp.installDefaults({
+      config: RESTREAMED,
       stats: QUIET_STATS,
       notices: [ERROR_NOTICE, EVENT_NOTICE],
     });
@@ -765,6 +782,7 @@ test.describe("System — Health notices sources @medium", () => {
   test("status bar problems stay out of the list", async ({ frigateApp }) => {
     test.skip(frigateApp.isMobile, "Status bar is desktop-only");
     await frigateApp.installDefaults({
+      config: RESTREAMED,
       stats: {
         service: { retention_unmet: true },
         cameras: { front_door: { camera_fps: 0 } },
@@ -829,6 +847,28 @@ test.describe("System — Health notices sources @medium", () => {
     ).toBeVisible({ timeout: 15_000 });
   });
 
+  test("a camera without a go2rtc stream gets a live view hint", async ({
+    frigateApp,
+  }) => {
+    await frigateApp.installDefaults({
+      config: { go2rtc: { streams: { front_door: ["rtsp://x"] } } },
+      stats: QUIET_STATS,
+    });
+    await frigateApp.goto("/system#health");
+
+    const row = frigateApp.page.getByTestId(
+      "health-problem-config:live:no-go2rtc-stream:camera.backyard",
+    );
+    await expect(row).toBeVisible({ timeout: 15_000 });
+    await expect(row).toHaveAttribute("data-severity", "info");
+    await expect(row).toContainText("lower frame rate and no audio");
+    await expect(
+      frigateApp.page.getByTestId(
+        "health-problem-config:live:no-go2rtc-stream:camera.front_door",
+      ),
+    ).toHaveCount(0);
+  });
+
   test("a global config problem is not repeated per camera", async ({
     frigateApp,
   }) => {
@@ -893,7 +933,10 @@ test.describe("System — Health notices sources @medium", () => {
   test("empty state when stats, config, and registry are clean", async ({
     frigateApp,
   }) => {
-    await frigateApp.installDefaults({ stats: QUIET_STATS });
+    await frigateApp.installDefaults({
+      config: RESTREAMED,
+      stats: QUIET_STATS,
+    });
     await frigateApp.goto("/system#health");
 
     await expect(
@@ -1130,6 +1173,7 @@ test.describe("System — Health notices sources @medium", () => {
   }) => {
     test.skip(frigateApp.isMobile, "Status bar is desktop-only");
     await frigateApp.installDefaults({
+      config: RESTREAMED,
       stats: QUIET_STATS,
       notices: [EVENT_NOTICE],
     });

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

@@ -1997,6 +1997,9 @@
       "genaiImageSourceRecordingsRecordDisabled": "Image source is set to 'recordings', but recording is disabled. Frigate will fall back to preview images.",
       "genaiImageSourceRecordingsRecordRuntimeDisabled": "Image source is set to 'recordings', but recording is currently turned off for this camera even though your config enables it. Frigate will fall back to preview images."
     },
+    "live": {
+      "noGo2rtcStream": "Live view for this camera is using a basic player with a lower frame rate and no audio. Set up a go2rtc stream for this camera to get smoother video and audio."
+    },
     "audio": {
       "noAudioRole": "No streams have the audio role defined. You must enable the audio role for audio detection to function."
     },

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

@@ -1,8 +1,24 @@
+import { isRestreamedStream } from "@/utils/liveTranscode";
 import type { SectionConfigOverrides } from "./types";
 
 const live: SectionConfigOverrides = {
   base: {
     sectionDocs: "/configuration/live",
+    messages: [
+      {
+        key: "no-go2rtc-stream",
+        health: true,
+        messageKey: "configMessages.live.noGo2rtcStream",
+        severity: "info",
+        docLink: "/configuration/live",
+        condition: (ctx) => {
+          if (ctx.level !== "camera" || !ctx.fullCameraConfig) return false;
+          return !Object.values(ctx.fullCameraConfig.live.streams).some(
+            (name) => isRestreamedStream(ctx.fullConfig, name),
+          );
+        },
+      },
+    ],
     restartRequired: [],
     fieldOrder: ["streams", "transcode", "height", "quality"],
     fieldGroups: {},