add description to api endpoint

frigate/api/media.py

@@ -42,6 +42,7 @@ from frigate.const import (
     PREVIEW_FRAME_TYPE,
 )
 from frigate.models import Event, Previews, Recordings, Regions, ReviewSegment
+from frigate.output.preview import get_most_recent_preview_frame
 from frigate.track.object_processing import TrackedObjectProcessor
 from frigate.util.file import get_event_thumbnail_bytes
 from frigate.util.image import get_image_from_recording
@@ -125,7 +126,9 @@ async def camera_ptz_info(request: Request, camera_name: str):
 
 
 @router.get(
-    "/{camera_name}/latest.{extension}", dependencies=[Depends(require_camera_access)]
+    "/{camera_name}/latest.{extension}",
+    dependencies=[Depends(require_camera_access)],
+    description="Returns the latest frame from the specified camera in the requested format (jpg, png, webp). Falls back to preview frames if the camera is offline.",
 )
 async def latest_frame(
     request: Request,
@@ -159,20 +162,37 @@ async def latest_frame(
             or 10
         )
 
+        is_offline = False
         if frame is None or datetime.now().timestamp() > (
             frame_processor.get_current_frame_time(camera_name) + retry_interval
         ):
-            if request.app.camera_error_image is None:
-                error_image = glob.glob(
-                    os.path.join(INSTALL_DIR, "frigate/images/camera-error.jpg")
-                )
+            last_frame_time = frame_processor.get_current_frame_time(camera_name)
+            preview_path = get_most_recent_preview_frame(
+                camera_name, before=last_frame_time
+            )
 
-                if len(error_image) > 0:
-                    request.app.camera_error_image = cv2.imread(
-                        error_image[0], cv2.IMREAD_UNCHANGED
+            if preview_path:
+                logger.debug(f"Using most recent preview frame for {camera_name}")
+                frame = cv2.imread(preview_path, cv2.IMREAD_UNCHANGED)
+
+                if frame is not None:
+                    is_offline = True
+
+            if frame is None or not is_offline:
+                logger.debug(
+                    f"No live or preview frame available for {camera_name}. Using error image."
+                )
+                if request.app.camera_error_image is None:
+                    error_image = glob.glob(
+                        os.path.join(INSTALL_DIR, "frigate/images/camera-error.jpg")
                     )
 
-            frame = request.app.camera_error_image
+                    if len(error_image) > 0:
+                        request.app.camera_error_image = cv2.imread(
+                            error_image[0], cv2.IMREAD_UNCHANGED
+                        )
+
+                frame = request.app.camera_error_image
 
         height = int(params.height or str(frame.shape[0]))
         width = int(height * frame.shape[1] / frame.shape[0])
@@ -194,14 +214,18 @@ async def latest_frame(
         frame = cv2.resize(frame, dsize=(width, height), interpolation=cv2.INTER_AREA)
 
         _, img = cv2.imencode(f".{extension.value}", frame, quality_params)
+
+        headers = {
+            "Cache-Control": "no-store" if not params.store else "private, max-age=60",
+        }
+
+        if is_offline:
+            headers["X-Frigate-Offline"] = "true"
+
         return Response(
             content=img.tobytes(),
             media_type=extension.get_mime_type(),
-            headers={
-                "Cache-Control": "no-store"
-                if not params.store
-                else "private, max-age=60",
-            },
+            headers=headers,
         )
     elif (
         camera_name == "birdseye"

frigate/output/preview.py

@@ -57,6 +57,51 @@ def get_cache_image_name(camera: str, frame_time: float) -> str:
     )
 
 
+def get_most_recent_preview_frame(camera: str, before: float = None) -> str | None:
+    """Get the most recent preview frame for a camera."""
+    if not os.path.exists(PREVIEW_CACHE_DIR):
+        return None
+
+    try:
+        # files are named preview_{camera}-{timestamp}.webp
+        # we want the largest timestamp that is less than or equal to before
+        preview_files = [
+            f
+            for f in os.listdir(PREVIEW_CACHE_DIR)
+            if f.startswith(f"preview_{camera}-")
+            and f.endswith(f".{PREVIEW_FRAME_TYPE}")
+        ]
+
+        if not preview_files:
+            return None
+
+        # sort by timestamp in descending order
+        # filenames are like preview_front-1712345678.901234.webp
+        preview_files.sort(reverse=True)
+
+        if before is None:
+            return os.path.join(PREVIEW_CACHE_DIR, preview_files[0])
+
+        for file_name in preview_files:
+            try:
+                # Extract timestamp: preview_front-1712345678.901234.webp
+                # Split by dash and extension
+                timestamp_part = file_name.split("-")[-1].split(
+                    f".{PREVIEW_FRAME_TYPE}"
+                )[0]
+                timestamp = float(timestamp_part)
+
+                if timestamp <= before:
+                    return os.path.join(PREVIEW_CACHE_DIR, file_name)
+            except (ValueError, IndexError):
+                continue
+
+        return None
+    except Exception as e:
+        logger.error(f"Error searching for most recent preview frame: {e}")
+        return None
+
+
 class FFMpegConverter(threading.Thread):
     """Convert a list of still frames into a vfr mp4."""
 

frigate/test/http_api/test_http_latest_frame.py

@@ -0,0 +1,107 @@
+import os
+import shutil
+from unittest.mock import MagicMock
+
+import cv2
+import numpy as np
+
+from frigate.output.preview import PREVIEW_CACHE_DIR, PREVIEW_FRAME_TYPE
+from frigate.test.http_api.base_http_test import AuthTestClient, BaseTestHttp
+
+
+class TestHttpLatestFrame(BaseTestHttp):
+    def setUp(self):
+        super().setUp([])
+        self.app = super().create_app()
+        self.app.detected_frames_processor = MagicMock()
+
+        if os.path.exists(PREVIEW_CACHE_DIR):
+            shutil.rmtree(PREVIEW_CACHE_DIR)
+        os.makedirs(PREVIEW_CACHE_DIR)
+
+    def tearDown(self):
+        if os.path.exists(PREVIEW_CACHE_DIR):
+            shutil.rmtree(PREVIEW_CACHE_DIR)
+        super().tearDown()
+
+    def test_latest_frame_fallback_to_preview(self):
+        camera = "front_door"
+        # 1. Mock frame processor to return None (simulating offline/missing frame)
+        self.app.detected_frames_processor.get_current_frame.return_value = None
+        # Return a timestamp that is after our dummy preview frame
+        self.app.detected_frames_processor.get_current_frame_time.return_value = (
+            1234567891.0
+        )
+
+        # 2. Create a dummy preview file
+        dummy_frame = np.zeros((180, 320, 3), np.uint8)
+        cv2.putText(
+            dummy_frame,
+            "PREVIEW",
+            (50, 50),
+            cv2.FONT_HERSHEY_SIMPLEX,
+            1,
+            (255, 255, 255),
+            2,
+        )
+        preview_path = os.path.join(
+            PREVIEW_CACHE_DIR, f"preview_{camera}-1234567890.0.{PREVIEW_FRAME_TYPE}"
+        )
+        cv2.imwrite(preview_path, dummy_frame)
+
+        with AuthTestClient(self.app) as client:
+            response = client.get(f"/{camera}/latest.webp")
+            assert response.status_code == 200
+            assert response.headers.get("X-Frigate-Offline") == "true"
+            # Verify we got an image (webp)
+            assert response.headers.get("content-type") == "image/webp"
+
+    def test_latest_frame_no_fallback_when_live(self):
+        camera = "front_door"
+        # 1. Mock frame processor to return a live frame
+        dummy_frame = np.zeros((180, 320, 3), np.uint8)
+        self.app.detected_frames_processor.get_current_frame.return_value = dummy_frame
+        self.app.detected_frames_processor.get_current_frame_time.return_value = (
+            2000000000.0  # Way in the future
+        )
+
+        with AuthTestClient(self.app) as client:
+            response = client.get(f"/{camera}/latest.webp")
+            assert response.status_code == 200
+            assert "X-Frigate-Offline" not in response.headers
+
+    def test_latest_frame_stale_falls_back_to_preview(self):
+        camera = "front_door"
+        # 1. Mock frame processor to return a stale frame
+        dummy_frame = np.zeros((180, 320, 3), np.uint8)
+        self.app.detected_frames_processor.get_current_frame.return_value = dummy_frame
+        # Return a timestamp that is after our dummy preview frame, but way in the past
+        self.app.detected_frames_processor.get_current_frame_time.return_value = 1000.0
+
+        # 2. Create a dummy preview file
+        preview_path = os.path.join(
+            PREVIEW_CACHE_DIR, f"preview_{camera}-999.0.{PREVIEW_FRAME_TYPE}"
+        )
+        cv2.imwrite(preview_path, dummy_frame)
+
+        with AuthTestClient(self.app) as client:
+            response = client.get(f"/{camera}/latest.webp")
+            assert response.status_code == 200
+            assert response.headers.get("X-Frigate-Offline") == "true"
+
+    def test_latest_frame_no_preview_found(self):
+        camera = "front_door"
+        # 1. Mock frame processor to return None
+        self.app.detected_frames_processor.get_current_frame.return_value = None
+
+        # 2. No preview file created
+
+        with AuthTestClient(self.app) as client:
+            response = client.get(f"/{camera}/latest.webp")
+            # Should fall back to camera-error.jpg (which might not exist in test env, but let's see)
+            # If camera-error.jpg is not found, it returns 500 "Unable to get valid frame" in latest_frame
+            # OR it uses request.app.camera_error_image if already loaded.
+
+            # Since we didn't provide camera-error.jpg, it might 500 if glob fails or return 500 if frame is None.
+            assert response.status_code in [200, 500]
+            assert "X-Frigate-Offline" not in response.headers

frigate/test/test_preview_loader.py

@@ -0,0 +1,80 @@
+import os
+import shutil
+import unittest
+
+from frigate.output.preview import (
+    PREVIEW_CACHE_DIR,
+    PREVIEW_FRAME_TYPE,
+    get_most_recent_preview_frame,
+)
+
+
+class TestPreviewLoader(unittest.TestCase):
+    def setUp(self):
+        if os.path.exists(PREVIEW_CACHE_DIR):
+            shutil.rmtree(PREVIEW_CACHE_DIR)
+        os.makedirs(PREVIEW_CACHE_DIR)
+
+    def tearDown(self):
+        if os.path.exists(PREVIEW_CACHE_DIR):
+            shutil.rmtree(PREVIEW_CACHE_DIR)
+
+    def test_get_most_recent_preview_frame_missing(self):
+        self.assertIsNone(get_most_recent_preview_frame("test_camera"))
+
+    def test_get_most_recent_preview_frame_exists(self):
+        camera = "test_camera"
+        # create dummy preview files
+        for ts in ["1000.0", "2000.0", "1500.0"]:
+            with open(
+                os.path.join(
+                    PREVIEW_CACHE_DIR, f"preview_{camera}-{ts}.{PREVIEW_FRAME_TYPE}"
+                ),
+                "w",
+            ) as f:
+                f.write(f"test_{ts}")
+
+        expected_path = os.path.join(
+            PREVIEW_CACHE_DIR, f"preview_{camera}-2000.0.{PREVIEW_FRAME_TYPE}"
+        )
+        self.assertEqual(get_most_recent_preview_frame(camera), expected_path)
+
+    def test_get_most_recent_preview_frame_before(self):
+        camera = "test_camera"
+        # create dummy preview files
+        for ts in ["1000.0", "2000.0"]:
+            with open(
+                os.path.join(
+                    PREVIEW_CACHE_DIR, f"preview_{camera}-{ts}.{PREVIEW_FRAME_TYPE}"
+                ),
+                "w",
+            ) as f:
+                f.write(f"test_{ts}")
+
+        # Test finding frame before or at 1500
+        expected_path = os.path.join(
+            PREVIEW_CACHE_DIR, f"preview_{camera}-1000.0.{PREVIEW_FRAME_TYPE}"
+        )
+        self.assertEqual(
+            get_most_recent_preview_frame(camera, before=1500.0), expected_path
+        )
+
+        # Test finding frame before or at 999
+        self.assertIsNone(get_most_recent_preview_frame(camera, before=999.0))
+
+    def test_get_most_recent_preview_frame_other_camera(self):
+        camera = "test_camera"
+        other_camera = "other_camera"
+        with open(
+            os.path.join(
+                PREVIEW_CACHE_DIR, f"preview_{other_camera}-3000.0.{PREVIEW_FRAME_TYPE}"
+            ),
+            "w",
+        ) as f:
+            f.write("test")
+
+        self.assertIsNone(get_most_recent_preview_frame(camera))
+
+    def test_get_most_recent_preview_frame_no_directory(self):
+        shutil.rmtree(PREVIEW_CACHE_DIR)
+        self.assertIsNone(get_most_recent_preview_frame("test_camera"))

web/src/components/player/LivePlayer.tsx

@@ -81,6 +81,11 @@ export default function LivePlayer({
   const internalContainerRef = useRef<HTMLDivElement | null>(null);
 
   const cameraName = useCameraFriendlyName(cameraConfig);
+
+  // player is showing on a dashboard if containerRef is not provided
+
+  const inDashboard = containerRef?.current == null;
+
   // stats
 
   const [stats, setStats] = useState<PlayerStatsType>({
@@ -408,6 +413,28 @@ export default function LivePlayer({
         />
       </div>
 
+      {offline && inDashboard && (
+        <>
+          <div className="absolute inset-0 rounded-lg bg-black/50 md:rounded-2xl" />
+          <div className="absolute inset-0 left-1/2 top-1/2 flex -translate-x-1/2 -translate-y-1/2 items-center justify-center">
+            <div className="flex flex-col items-center justify-center gap-2 rounded-lg bg-background/50 p-3 text-center">
+              <div className="text-md">{t("streamOffline.title")}</div>
+              <TbExclamationCircle className="size-6" />
+              <p className="text-center text-sm">
+                <Trans
+                  ns="components/player"
+                  values={{
+                    cameraName: cameraName,
+                  }}
+                >
+                  streamOffline.desc
+                </Trans>
+              </p>
+            </div>
+          </div>
+        </>
+      )}
+
       {offline && !showStillWithoutActivity && cameraEnabled && (
         <div className="absolute inset-0 left-1/2 top-1/2 flex h-96 w-96 -translate-x-1/2 -translate-y-1/2">
           <div className="flex flex-col items-center justify-center rounded-lg bg-background/50 p-5">