fix(app): refetch the livestream on error while a protocol run isn't terminal (#20023)

Closes RQA-4812

Author: mjhuff

app/src/pages/Desktop/LivestreamViewer/LivestreamInfoScreen.tsx

@@ -4,7 +4,8 @@ import { InfoScreen } from '@opentrons/components'
 import { useCamera } from '@opentrons/react-api-client'
 
 import { isTerminalRunStatus } from '/app/organisms/Desktop/Devices/ProtocolRun/ProtocolRunHeader/utils'
-import { useNotifyRunQuery } from '/app/resources/runs'
+
+import type { RunStatus } from '@opentrons/api-client'
 
 const CAMERA_POLLING_INTERVAL_MS = 5000
 
@@ -16,22 +17,21 @@ type LiveStreamInfoScreenType =
   | null
 
 export function useLivestreamInfoScreen(
-  runId: string,
+  runStatus: RunStatus | null,
+  isRunLoading: boolean,
   videoError: string | null
 ): LiveStreamInfoScreenType {
-  const { data: runData, isLoading: isRunLoading } = useNotifyRunQuery(runId)
   const { data: cameraData, isLoading: isCameraSettingsLoading } = useCamera({
     refetchInterval: CAMERA_POLLING_INTERVAL_MS,
   })
-  const runStatus = runData?.data.status ?? null
   const isCameraEnabled = cameraData?.cameraEnabled ?? false
 
-  if (videoError != null) {
+  if (isTerminalRunStatus(runStatus)) {
+    return 'run-terminal'
+  } else if (videoError != null) {
     return 'error'
   } else if (isRunLoading || isCameraSettingsLoading) {
     return 'loading'
-  } else if (isTerminalRunStatus(runStatus)) {
-    return 'run-terminal'
   } else if (!isCameraEnabled) {
     return 'disabled'
   } else {

app/src/pages/Desktop/LivestreamViewer/hooks/useHlsVideo.ts

@@ -3,24 +3,37 @@ import Hls from 'hls.js'
 
 import { useHost } from '@opentrons/react-api-client'
 
+import { isTerminalRunStatus } from '/app/organisms/Desktop/Devices/ProtocolRun/ProtocolRunHeader/utils'
+
 import type { RefObject } from 'react'
+import type { RunStatus } from '@opentrons/api-client'
 
 // TODO(jh, 09-05-25): /GET this from the /stream endpoint eventually.
 const STREAM_URL = (robotIp: string): string =>
   `http://${robotIp}:31950/hls/stream.m3u8`
 
+const RETRY_DELAY_MS = 3000
+
 export interface UseHlsVideoResult {
   videoRef: RefObject<HTMLVideoElement>
   videoError: string | null
 }
 
-// Sets up and manages an HLS video stream player that receives
-// camera stream URLs from the main Electron process and displays them.
-export function useHlsVideo(): UseHlsVideoResult {
+export function useHlsVideo(runStatus: RunStatus | null): UseHlsVideoResult {
   const host = useHost()
   const videoRef = useRef<HTMLVideoElement>(null)
   const hlsRef = useRef<Hls | null>(null)
   const [error, setError] = useState<string | null>(null)
+  const retryCountRef = useRef(0)
+  const retryTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+
+  const setupHls = useRef<() => void>()
+
+  useEffect(() => {
+    if (error) {
+      console.error(error)
+    }
+  }, [error])
 
   useEffect(() => {
     if (videoRef.current == null || host == null) {
@@ -29,7 +42,12 @@ export function useHlsVideo(): UseHlsVideoResult {
 
     const video = videoRef.current
 
-    if (Hls.isSupported()) {
+    setupHls.current = () => {
+      if (!Hls.isSupported()) {
+        setError('HLS streaming not supported in this browser.')
+        return
+      }
+
       if (hlsRef.current) {
         hlsRef.current.destroy()
       }
@@ -54,28 +72,25 @@ export function useHlsVideo(): UseHlsVideoResult {
       hls.attachMedia(video)
 
       hls.on(Hls.Events.MANIFEST_PARSED, () => {
+        retryCountRef.current = 0
+        setError(null)
         video.play().catch(e => {
           console.error('Auto-play failed:', e)
           setError('Auto-play failed. Please close and reopen the stream.')
         })
       })
 
-      hls.on(Hls.Events.ERROR, (event, data) => {
-        console.error('HLS error:', event, data)
-        if (data.fatal) {
-          switch (data.type) {
-            case Hls.ErrorTypes.NETWORK_ERROR:
-              setError(
-                `Network error: Cannot connect to ${STREAM_URL(host.hostname)}`
-              )
-              break
-            case Hls.ErrorTypes.MEDIA_ERROR:
-              setError('Media error in stream')
-              break
-            default:
-              setError('Fatal error loading stream')
-              break
-          }
+      hls.on(Hls.Events.ERROR, (_, data) => {
+        // `fatal` prevents refetching over-aggressively, ex, when the buffer is temporarily depleted.
+        if (data.fatal && !isTerminalRunStatus(runStatus)) {
+          retryCountRef.current++
+          setError(
+            `Service unavailable. Retrying (${retryCountRef.current})...`
+          )
+
+          retryTimeoutRef.current = setTimeout(() => {
+            setupHls.current?.()
+          }, RETRY_DELAY_MS)
         }
       })
 
@@ -84,18 +99,23 @@ export function useHlsVideo(): UseHlsVideoResult {
       }
 
       video.addEventListener('error', handleVideoError)
+    }
 
-      return () => {
-        video.removeEventListener('error', handleVideoError)
-        if (hlsRef.current) {
-          hlsRef.current.destroy()
-          hlsRef.current = null
-        }
+    setupHls.current()
+
+    return () => {
+      if (retryTimeoutRef.current) {
+        clearTimeout(retryTimeoutRef.current)
+      }
+
+      if (hlsRef.current) {
+        hlsRef.current.destroy()
+        hlsRef.current = null
       }
-    } else {
-      setError('HLS streaming not supported in this browser.')
+
+      retryCountRef.current = 0
     }
-  }, [host])
+  }, [host, runStatus])
 
   return { videoRef, videoError: error }
 }

app/src/pages/Desktop/LivestreamViewer/index.tsx

@@ -2,6 +2,8 @@ import { useTranslation } from 'react-i18next'
 import { useSearchParams } from 'react-router-dom'
 
 import { Chip } from '@opentrons/components'
+// eslint-disable-next-line no-restricted-imports
+import { useRunQuery } from '@opentrons/react-api-client'
 
 import { useHlsVideo } from '/app/pages/Desktop/LivestreamViewer/hooks/useHlsVideo'
 import {
@@ -11,11 +13,22 @@ import {
 
 import styles from './livestream.module.css'
 
+const RUN_POLLING_INTERVAL_MS = 5000
+
 export function LivestreamViewer(): JSX.Element {
-  const { videoRef, videoError } = useHlsVideo()
   const [searchParams] = useSearchParams()
   const runId = searchParams.get('runId') ?? ''
-  const infoScreenType = useLivestreamInfoScreen(runId, videoError)
+  // TODO(jh, 11-04-25): Notifications are not working in secondary windows. Investigate further.
+  const { data: runData, isLoading: isRunLoading } = useRunQuery(runId, {
+    refetchInterval: RUN_POLLING_INTERVAL_MS,
+  })
+  const runStatus = runData?.data.status ?? null
+  const { videoRef, videoError } = useHlsVideo(runStatus)
+  const infoScreenType = useLivestreamInfoScreen(
+    runStatus,
+    isRunLoading,
+    videoError
+  )
 
   return (
     <div className={styles.container}>