From 658b0a064c327ebf6df57579571f506ecc5e2fbd Mon Sep 17 00:00:00 2001
From: Josh Hawkins <32435876+hawkeye217@users.noreply.github.com>
Date: Fri, 3 Oct 2025 07:37:18 -0500
Subject: [PATCH] Improve live view console errors (#20340)

* improve live view console errors

* more docs clarity
---
 docs/docs/configuration/live.md            | 1 +
 web/src/components/player/MsePlayer.tsx    | 7 +++++--
 web/src/components/player/WebRTCPlayer.tsx | 7 +++++--
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/docs/configuration/live.md b/docs/docs/configuration/live.md
index 313137591..79802b371 100644
--- a/docs/docs/configuration/live.md
+++ b/docs/docs/configuration/live.md
@@ -250,6 +250,7 @@ Note that disabling a camera through the config file (`enabled: False`) removes
    - Check go2rtc configuration for transcoding (e.g., audio to AAC/OPUS).
    - Test with a different stream via the UI dropdown (if `live -> streams` is configured).
    - For WebRTC-specific issues, ensure port 8555 is forwarded and candidates are set (see (WebRTC Extra Configuration)(#webrtc-extra-configuration)).
+   - If your cameras are streaming at a high resolution, your browser may be struggling to load all of the streams before the buffering timeout occurs. Frigate prioritizes showing a true live view as quickly as possible. If the fallback occurs often, change your live view settings to use a lower bandwidth substream.
 
 3. **It doesn't seem like my cameras are streaming on the Live dashboard. Why?**
 
diff --git a/web/src/components/player/MsePlayer.tsx b/web/src/components/player/MsePlayer.tsx
index f7a77393f..c4a30c7e6 100644
--- a/web/src/components/player/MsePlayer.tsx
+++ b/web/src/components/player/MsePlayer.tsx
@@ -88,7 +88,7 @@ function MSEPlayer({
     (error: LivePlayerError, description: string = "Unknown error") => {
       // eslint-disable-next-line no-console
       console.error(
-        `${camera} - MSE error '${error}': ${description} See the documentation: https://docs.frigate.video/configuration/live`,
+        `${camera} - MSE error '${error}': ${description} See the documentation: https://docs.frigate.video/configuration/live/#live-view-faq`,
       );
       onError?.(error);
     },
@@ -484,7 +484,10 @@ function MSEPlayer({
             videoRef.current
           ) {
             onDisconnect();
-            handleError("stalled", "Media playback has stalled.");
+            handleError(
+              "stalled",
+              `Media playback has stalled after ${timeoutDuration / 1000} seconds due to insufficient buffering or a network interruption.`,
+            );
           }
         }, timeoutDuration),
       );
diff --git a/web/src/components/player/WebRTCPlayer.tsx b/web/src/components/player/WebRTCPlayer.tsx
index dc3b24653..13a2a20ed 100644
--- a/web/src/components/player/WebRTCPlayer.tsx
+++ b/web/src/components/player/WebRTCPlayer.tsx
@@ -42,7 +42,7 @@ export default function WebRtcPlayer({
     (error: LivePlayerError, description: string = "Unknown error") => {
       // eslint-disable-next-line no-console
       console.error(
-        `${camera} - WebRTC error '${error}': ${description} See the documentation: https://docs.frigate.video/configuration/live`,
+        `${camera} - WebRTC error '${error}': ${description} See the documentation: https://docs.frigate.video/configuration/live/#live-view-faq`,
       );
       onError?.(error);
     },
@@ -339,7 +339,10 @@ export default function WebRtcPlayer({
                     document.visibilityState === "visible" &&
                     pcRef.current != undefined
                   ) {
-                    handleError("stalled", "WebRTC connection stalled.");
+                    handleError(
+                      "stalled",
+                      "Media playback has stalled after 3 seconds due to insufficient buffering or a network interruption.",
+                    );
                   }
                 }, 3000),
               );