feat(player): add debug logs (#730)

Show debug logs for delay, current time and buffered end.

player/README.md

@@ -155,6 +155,19 @@ where you specify the IP of the camera you want to proxy as the `MSP_CAMERA`
 environment variable (default is `192.168.0.90`). The vite dev server will
 proxy requests to the camera, so that you'll have no CORS issues for any format.
 
+## Debugging
+
+In the browser, you can set `localStorage.debug = 'msp:*'` to log everything
+related to just this library (make sure to reload the page after setting the
+value). You can also debug a specific component by using one of the following from the table below.
+
+| Detailed debugging |
+| ----- |
+| `msp:http-mp4-video` |
+| `msp:ws-rtsp-video` |
+| `msp:still-image` |
+| `msp:api` |
+
 ## FAQ
 
 **Does this library support audio?**

player/src/HttpMp4Video.tsx

@@ -6,6 +6,7 @@ import styled from 'styled-components'
 
 import { FORMAT_SUPPORTS_AUDIO } from './constants'
 import { useEventState } from './hooks/useEventState'
+import { useVideoDebug } from './hooks/useVideoDebug'
 import { MetadataHandler } from './metadata'
 import { VideoProperties } from './PlaybackArea'
 import { Format } from './types'
@@ -95,6 +96,8 @@ export const HttpMp4Video: React.FC<HttpMp4VideoProps> = ({
 
   const __sensorTmRef = useRef<TransformationMatrix>()
 
+  useVideoDebug(videoRef.current, debugLog)
+
   useEffect(() => {
     const videoEl = videoRef.current
 
@@ -107,6 +110,12 @@ export const HttpMp4Video: React.FC<HttpMp4VideoProps> = ({
       videoEl.play().catch((err) => {
         console.error('VideoElement error: ', err.message)
       })
+
+      const { videoHeight, videoWidth } = videoEl
+      debugLog('%o', {
+        videoHeight,
+        videoWidth,
+      })
     } else if (!play && playing === true) {
       debugLog('pause')
       videoEl.pause()

player/src/WsRtspCanvas.tsx

@@ -107,6 +107,24 @@ export const WsRtspCanvas: React.FC<WsRtspCanvasProps> = ({
   const __offsetRef = useRef(offset)
   const __rangeRef = useRef<Range>([offset, undefined])
 
+  /**
+   * Show debug log for current time.
+   * currentTime: current playback time
+   */
+  const timeout = useRef<number | undefined>(undefined)
+  useEffect(() => {
+    if (pipeline === null) {
+      return
+    }
+
+    timeout.current = window.setInterval(() => {
+      const { currentTime } = pipeline
+      debugLog('%o', { currentTime })
+    }, 1000)
+
+    return () => window.clearTimeout(timeout.current)
+  }, [pipeline])
+
   useEffect(() => {
     __offsetRef.current = offset
     const canvas = canvasRef.current

player/src/WsRtspVideo.tsx

@@ -14,6 +14,7 @@ import styled from 'styled-components'
 
 import { FORMAT_SUPPORTS_AUDIO } from './constants'
 import { useEventState } from './hooks/useEventState'
+import { useVideoDebug } from './hooks/useVideoDebug'
 import {
   attachMetadataHandler,
   MetadataHandler,
@@ -137,6 +138,8 @@ export const WsRtspVideo: React.FC<WsRtspVideoProps> = ({
 
   const __sensorTmRef = useRef<TransformationMatrix>()
 
+  useVideoDebug(videoRef.current, debugLog)
+
   useEffect(() => {
     const videoEl = videoRef.current
 
@@ -149,6 +152,12 @@ export const WsRtspVideo: React.FC<WsRtspVideoProps> = ({
       videoEl.play().catch((err) => {
         console.error('VideoElement error: ', err.message)
       })
+
+      const { videoHeight, videoWidth } = videoEl
+      debugLog('%o', {
+        videoHeight,
+        videoWidth,
+      })
     } else if (!play && playing === true) {
       debugLog('pause')
       videoEl.pause()

player/src/hooks/useVideoDebug.ts

@@ -0,0 +1,45 @@
+import { useEffect } from 'react'
+
+import { Debugger } from 'debug'
+
+/**
+ * Show debug logs with information received from
+ * 'progress' & 'timeupdate' events including the current
+ * up time, delay and end time of last buffer.
+ * bufferedEnd: the last buffered time
+ * currentTime: current playback time
+ * delay: the last buffered time - current playback time
+ */
+export const useVideoDebug = (
+  videoEl: HTMLVideoElement | null,
+  debugLog: Debugger
+) => {
+  useEffect(() => {
+    if (videoEl === null) {
+      return
+    }
+
+    const onUpdate = () => {
+      try {
+        const currentTime = videoEl.currentTime
+        const bufferedEnd = videoEl.buffered.end(videoEl.buffered.length - 1)
+
+        debugLog('%o', {
+          delay: bufferedEnd - currentTime,
+          currentTime,
+          bufferedEnd,
+        })
+      } catch (err) {
+        debugLog('%o', err)
+      }
+    }
+
+    videoEl.addEventListener('timeupdate', onUpdate)
+    videoEl.addEventListener('progress', onUpdate)
+
+    return () => {
+      videoEl.removeEventListener('timeupdate', onUpdate)
+      videoEl.removeEventListener('progress', onUpdate)
+    }
+  }, [debugLog, videoEl])
+}