Debug replay (#22212)

* debug replay implementation

* fix masks after dev rebase

* fix squash merge issues

* fix

* fix

* fix

* no need to write debug replay camera to config

* camera and filter button and dropdown

* add filters

* add ability to edit motion and object config for debug replay

* add debug draw overlay to debug replay

* add guard to prevent crash when camera is no longer in camera_states

* fix overflow due to radix absolutely positioned elements

* increase number of messages

* ensure deep_merge replaces existing list values when override is true

* add back button

* add debug replay to explore and review menus

* clean up

* clean up

* update instructions to prevent exposing exception info

* fix typing

* refactor output logic

* refactor with helper function

* move init to function for consistency

web/src/hooks/use-allowed-cameras.ts

@@ -2,6 +2,7 @@ import { useContext } from "react";
 import { AuthContext } from "@/context/auth-context";
 import useSWR from "swr";
 import { FrigateConfig } from "@/types/frigateConfig";
+import { isReplayCamera } from "@/utils/cameraUtil";
 
 export function useAllowedCameras() {
   const { auth } = useContext(AuthContext);
@@ -14,9 +15,11 @@ export function useAllowedCameras() {
     auth.user?.role === "admin" ||
     !auth.isAuthenticated // anonymous internal port
   ) {
-    // return all cameras
-    return config?.cameras ? Object.keys(config.cameras) : [];
+    // return all cameras, excluding replay cameras
+    return config?.cameras
+      ? Object.keys(config.cameras).filter((name) => !isReplayCamera(name))
+      : [];
   }
 
-  return auth.allowedCameras || [];
+  return (auth.allowedCameras || []).filter((name) => !isReplayCamera(name));
 }

web/src/hooks/use-camera-activity.ts

@@ -26,7 +26,7 @@ type useCameraActivityReturn = {
 };
 
 export function useCameraActivity(
-  camera: CameraConfig,
+  camera: CameraConfig | undefined,
   revalidateOnFocus: boolean = true,
 ): useCameraActivityReturn {
   const { data: config } = useSWR<FrigateConfig>("config", {
@@ -47,7 +47,7 @@ export function useCameraActivity(
   // init camera activity
 
   const { payload: updatedCameraState } = useInitialCameraState(
-    camera.name,
+    camera?.name ?? "",
     revalidateOnFocus,
   );
   useEffect(() => {
@@ -60,7 +60,7 @@ export function useCameraActivity(
   const memoizedAudioState = useDeepMemo(updatedAudioState);
 
   useEffect(() => {
-    if (memoizedAudioState) {
+    if (memoizedAudioState && camera?.name) {
       setAudioDetections(memoizedAudioState[camera.name]);
     }
   }, [memoizedAudioState, camera]);
@@ -72,8 +72,8 @@ export function useCameraActivity(
     [objects],
   );
 
-  const { payload: cameraEnabled } = useEnabledState(camera.name);
-  const { payload: detectingMotion } = useMotionActivity(camera.name);
+  const { payload: cameraEnabled } = useEnabledState(camera?.name ?? "");
+  const { payload: detectingMotion } = useMotionActivity(camera?.name ?? "");
   const { payload: event } = useFrigateEvents();
   const updatedEvent = useDeepMemo(event);
 
@@ -91,7 +91,7 @@ export function useCameraActivity(
       return;
     }
 
-    if (updatedEvent.after.camera !== camera.name) {
+    if (!camera?.name || updatedEvent.after.camera !== camera.name) {
       return;
     }
 
@@ -158,6 +158,10 @@ export function useCameraActivity(
       return false;
     }
 
+    if (!camera?.name) {
+      return false;
+    }
+
     return (
       cameras[camera.name]?.camera_fps == 0 && stats["service"].uptime > 60
     );

web/src/hooks/use-stats.ts

@@ -9,6 +9,7 @@ import { useMemo } from "react";
 import useSWR from "swr";
 import useDeepMemo from "./use-deep-memo";
 import { capitalizeAll, capitalizeFirstLetter } from "@/utils/stringUtil";
+import { isReplayCamera } from "@/utils/cameraUtil";
 import { useFrigateStats } from "@/api/ws";
 
 import { useTranslation } from "react-i18next";
@@ -16,6 +17,9 @@ import { useTranslation } from "react-i18next";
 export default function useStats(stats: FrigateStats | undefined) {
   const { t } = useTranslation(["views/system"]);
   const { data: config } = useSWR<FrigateConfig>("config");
+  const { data: debugReplayStatus } = useSWR("debug_replay/status", {
+    revalidateOnFocus: false,
+  });
 
   const memoizedStats = useDeepMemo(stats);
 
@@ -74,6 +78,11 @@ export default function useStats(stats: FrigateStats | undefined) {
         return;
       }
 
+      // Skip replay cameras
+      if (isReplayCamera(name)) {
+        return;
+      }
+
       const cameraName = config.cameras?.[name]?.friendly_name ?? name;
       if (config.cameras[name].enabled && cam["camera_fps"] == 0) {
         problems.push({
@@ -96,7 +105,15 @@ export default function useStats(stats: FrigateStats | undefined) {
       );
 
       const cameraName = config?.cameras?.[name]?.friendly_name ?? name;
-      if (!isNaN(ffmpegAvg) && ffmpegAvg >= CameraFfmpegThreshold.error) {
+
+      // Skip ffmpeg warnings for replay cameras when debug replay is active
+      if (
+        !isNaN(ffmpegAvg) &&
+        ffmpegAvg >= CameraFfmpegThreshold.error &&
+        !(
+          debugReplayStatus?.active && debugReplayStatus?.replay_camera === name
+        )
+      ) {
         problems.push({
           text: t("stats.ffmpegHighCpuUsage", {
             camera: capitalizeFirstLetter(capitalizeAll(cameraName)),
@@ -119,8 +136,19 @@ export default function useStats(stats: FrigateStats | undefined) {
       }
     });
 
+    // Add message if debug replay is active
+    if (debugReplayStatus?.active) {
+      problems.push({
+        text: t("stats.debugReplayActive", {
+          defaultValue: "Debug replay session is active",
+        }),
+        color: "text-selected",
+        relevantLink: "/replay",
+      });
+    }
+
     return problems;
-  }, [config, memoizedStats, t]);
+  }, [config, memoizedStats, t, debugReplayStatus]);
 
   return { potentialProblems };
 }

web/src/hooks/use-ws-message-buffer.ts

@@ -0,0 +1,99 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useWsMessageSubscribe, WsFeedMessage } from "@/api/ws";
+import { extractCameraName } from "@/utils/wsUtil";
+
+type UseWsMessageBufferReturn = {
+  messages: WsFeedMessage[];
+  clear: () => void;
+};
+
+type MessageFilter = {
+  cameraFilter?: string | string[]; // "all", specific camera name, or array of camera names (undefined in array = all)
+};
+
+export function useWsMessageBuffer(
+  maxSize: number = 2000,
+  paused: boolean = false,
+  filter?: MessageFilter,
+): UseWsMessageBufferReturn {
+  const bufferRef = useRef<WsFeedMessage[]>([]);
+  const [version, setVersion] = useState(0);
+  const pausedRef = useRef(paused);
+  const filterRef = useRef(filter);
+
+  pausedRef.current = paused;
+  filterRef.current = filter;
+
+  const batchTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const dirtyRef = useRef(false);
+
+  useEffect(() => {
+    batchTimerRef.current = setInterval(() => {
+      if (dirtyRef.current) {
+        dirtyRef.current = false;
+        setVersion((v) => v + 1);
+      }
+    }, 200);
+
+    return () => {
+      if (batchTimerRef.current) {
+        clearInterval(batchTimerRef.current);
+      }
+    };
+  }, []);
+
+  const shouldIncludeMessage = useCallback((msg: WsFeedMessage): boolean => {
+    const currentFilter = filterRef.current;
+    if (!currentFilter) return true;
+
+    // Check camera filter
+    const cf = currentFilter.cameraFilter;
+    if (cf !== undefined) {
+      if (Array.isArray(cf)) {
+        // Array of cameras: include messages matching any camera in the list
+        const msgCamera = extractCameraName(msg);
+        if (msgCamera && !cf.includes(msgCamera)) {
+          return false;
+        }
+      } else if (cf !== "all") {
+        // Single string camera filter
+        const msgCamera = extractCameraName(msg);
+        if (msgCamera !== cf) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }, []);
+
+  useWsMessageSubscribe(
+    useCallback(
+      (msg: WsFeedMessage) => {
+        if (pausedRef.current) return;
+        if (!shouldIncludeMessage(msg)) return;
+
+        const buf = bufferRef.current;
+        buf.push(msg);
+        if (buf.length > maxSize) {
+          buf.splice(0, buf.length - maxSize);
+        }
+        dirtyRef.current = true;
+      },
+      [shouldIncludeMessage, maxSize],
+    ),
+  );
+
+  const clear = useCallback(() => {
+    bufferRef.current = [];
+    setVersion((v) => v + 1);
+  }, []);
+
+  // version is used to trigger re-renders; we spread the buffer
+  // into a new array so that downstream useMemo dependencies
+  // see a new reference and recompute.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const messages = useMemo(() => [...bufferRef.current], [version]);
+
+  return { messages, clear };
+}