@livepeer-frameworks/player-react 0.0.3

package/src/hooks/useStreamState.ts

@@ -0,0 +1,381 @@
+import { useEffect, useState, useRef, useCallback } from 'react';
+import type {
+  UseStreamStateOptions,
+  StreamState,
+  StreamStatus,
+  MistStreamInfo,
+} from '../types';
+
+/**
+ * Parse MistServer error string into StreamStatus enum
+ */
+function parseErrorToStatus(error: string): StreamStatus {
+  const lowerError = error.toLowerCase();
+
+  if (lowerError.includes('offline')) return 'OFFLINE';
+  if (lowerError.includes('initializing')) return 'INITIALIZING';
+  if (lowerError.includes('booting')) return 'BOOTING';
+  if (lowerError.includes('waiting for data')) return 'WAITING_FOR_DATA';
+  if (lowerError.includes('shutting down')) return 'SHUTTING_DOWN';
+  if (lowerError.includes('invalid')) return 'INVALID';
+
+  return 'ERROR';
+}
+
+/**
+ * Get human-readable message for stream status
+ */
+function getStatusMessage(status: StreamStatus, percentage?: number): string {
+  switch (status) {
+    case 'ONLINE':
+      return 'Stream is online';
+    case 'OFFLINE':
+      return 'Stream is offline';
+    case 'INITIALIZING':
+      return percentage !== undefined
+        ? `Initializing... ${Math.round(percentage * 10) / 10}%`
+        : 'Stream is initializing';
+    case 'BOOTING':
+      return 'Stream is starting up';
+    case 'WAITING_FOR_DATA':
+      return 'Waiting for stream data';
+    case 'SHUTTING_DOWN':
+      return 'Stream is shutting down';
+    case 'INVALID':
+      return 'Stream status is invalid';
+    case 'ERROR':
+    default:
+      return 'Stream error';
+  }
+}
+
+/**
+ * Initial stream state
+ */
+const initialState: StreamState = {
+  status: 'OFFLINE',
+  isOnline: false,
+  message: 'Connecting...',
+  lastUpdate: 0,
+};
+
+/**
+ * Hook to poll MistServer for stream status via WebSocket or HTTP
+ *
+ * Uses native MistServer protocol:
+ * - WebSocket: ws://{baseUrl}/json_{streamName}.js
+ * - HTTP fallback: GET {baseUrl}/json_{streamName}.js
+ *
+ * @example
+ * ```tsx
+ * const { status, isOnline, message } = useStreamState({
+ *   mistBaseUrl: 'https://mist.example.com',
+ *   streamName: 'my-stream',
+ *   pollInterval: 3000,
+ * });
+ * ```
+ */
+export interface UseStreamStateReturn extends StreamState {
+  /** Manual refetch function */
+  refetch: () => void;
+  /** WebSocket reference for sharing with MistReporter */
+  socketRef: React.RefObject<WebSocket | null>;
+  /** True when WebSocket is connected and ready (triggers re-render) */
+  socketReady: boolean;
+}
+
+export function useStreamState(options: UseStreamStateOptions): UseStreamStateReturn {
+  const {
+    mistBaseUrl,
+    streamName,
+    pollInterval = 3000,
+    enabled = true,
+    useWebSocket = true,
+    debug = false,
+  } = options;
+
+  const [state, setState] = useState<StreamState>(initialState);
+  const [socketReady, setSocketReady] = useState(false);
+  const wsRef = useRef<WebSocket | null>(null);
+  const pollTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const wsTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const mountedRef = useRef(true);
+
+  // MistPlayer-style WebSocket timeout (5 seconds)
+  const WS_TIMEOUT_MS = 5000;
+
+  /**
+   * Process MistServer response data
+   */
+  const processStreamInfo = useCallback((data: MistStreamInfo) => {
+    if (!mountedRef.current) return;
+
+    if (data.error) {
+      // Stream has an error state - preserve previous streamInfo (track data)
+      const status = parseErrorToStatus(data.error);
+      const message = data.on_error || getStatusMessage(status, data.perc);
+
+      setState(prev => ({
+        status,
+        isOnline: false,
+        message,
+        percentage: data.perc,
+        lastUpdate: Date.now(),
+        error: data.error,
+        streamInfo: prev.streamInfo, // Preserve track data through error states
+      }));
+    } else {
+      // Stream is online with valid metadata
+      // Merge new data with existing streamInfo to preserve source/tracks from initial fetch
+      // WebSocket updates may not include source array - only status updates
+      setState(prev => {
+        const mergedStreamInfo: MistStreamInfo = {
+          ...prev.streamInfo,  // Keep existing source/meta if present
+          ...data,             // Override with new data
+          // Explicitly preserve source if not in new data
+          source: data.source || prev.streamInfo?.source,
+          // Merge meta to preserve tracks
+          meta: {
+            ...prev.streamInfo?.meta,
+            ...data.meta,
+            // Preserve tracks if not in new data
+            tracks: data.meta?.tracks || prev.streamInfo?.meta?.tracks,
+          },
+        };
+
+        return {
+          status: 'ONLINE',
+          isOnline: true,
+          message: 'Stream is online',
+          lastUpdate: Date.now(),
+          streamInfo: mergedStreamInfo,
+        };
+      });
+    }
+  }, []);
+
+  /**
+   * HTTP polling fallback
+   * Adds metaeverywhere=1 and inclzero=1 like MistPlayer
+   */
+  const pollHttp = useCallback(async () => {
+    if (!mountedRef.current || !enabled) return;
+
+    try {
+      // Build URL with MistPlayer-style params
+      const baseUrl = `${mistBaseUrl.replace(/\/$/, '')}/json_${encodeURIComponent(streamName)}.js`;
+      const url = `${baseUrl}?metaeverywhere=1&inclzero=1`;
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: { 'Accept': 'application/json' },
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      // MistServer returns JSON with potential JSONP wrapper
+      let text = await response.text();
+      // Strip JSONP callback if present (use [\s\S]* instead of /s flag for ES5 compat)
+      const jsonpMatch = text.match(/^[^(]+\(([\s\S]*)\);?$/);
+      if (jsonpMatch) {
+        text = jsonpMatch[1];
+      }
+
+      const data = JSON.parse(text) as MistStreamInfo;
+      processStreamInfo(data);
+    } catch (error) {
+      if (!mountedRef.current) return;
+
+      setState(prev => ({
+        ...prev,
+        status: 'ERROR',
+        isOnline: false,
+        message: error instanceof Error ? error.message : 'Connection failed',
+        lastUpdate: Date.now(),
+        error: error instanceof Error ? error.message : 'Unknown error',
+      }));
+    }
+
+    // Schedule next poll
+    if (mountedRef.current && enabled && !useWebSocket) {
+      pollTimeoutRef.current = setTimeout(pollHttp, pollInterval);
+    }
+  }, [mistBaseUrl, streamName, enabled, useWebSocket, pollInterval, processStreamInfo]);
+
+  /**
+   * WebSocket connection with MistPlayer-style 5-second timeout
+   */
+  const connectWebSocket = useCallback(() => {
+    if (!mountedRef.current || !enabled || !useWebSocket) return;
+
+    // Clean up existing connection and timeout
+    if (wsTimeoutRef.current) {
+      clearTimeout(wsTimeoutRef.current);
+      wsTimeoutRef.current = null;
+    }
+    if (wsRef.current) {
+      wsRef.current.close();
+      wsRef.current = null;
+    }
+
+    try {
+      // Convert http(s) to ws(s)
+      const wsUrl = mistBaseUrl
+        .replace(/^http:/, 'ws:')
+        .replace(/^https:/, 'wss:')
+        .replace(/\/$/, '');
+
+      // Build URL with MistPlayer-style params
+      const url = `${wsUrl}/json_${encodeURIComponent(streamName)}.js?metaeverywhere=1&inclzero=1`;
+      const ws = new WebSocket(url);
+      wsRef.current = ws;
+
+      // MistPlayer-style timeout: if no message within 5 seconds, fall back to HTTP
+      wsTimeoutRef.current = setTimeout(() => {
+        if (ws.readyState <= WebSocket.OPEN) {
+          if (debug) {
+            console.debug('[useStreamState] WebSocket timeout (5s), falling back to HTTP polling');
+          }
+          ws.close();
+          pollHttp();
+        }
+      }, WS_TIMEOUT_MS);
+
+      ws.onopen = () => {
+        if (debug) {
+          console.debug('[useStreamState] WebSocket connected');
+        }
+        setSocketReady(true);
+      };
+
+      ws.onmessage = (event) => {
+        // Clear timeout on first message
+        if (wsTimeoutRef.current) {
+          clearTimeout(wsTimeoutRef.current);
+          wsTimeoutRef.current = null;
+        }
+
+        try {
+          const data = JSON.parse(event.data) as MistStreamInfo;
+          processStreamInfo(data);
+        } catch (e) {
+          console.warn('[useStreamState] Failed to parse WebSocket message:', e);
+        }
+      };
+
+      ws.onerror = (event) => {
+        console.warn('[useStreamState] WebSocket error, falling back to HTTP polling');
+        if (wsTimeoutRef.current) {
+          clearTimeout(wsTimeoutRef.current);
+          wsTimeoutRef.current = null;
+        }
+        ws.close();
+      };
+
+      ws.onclose = () => {
+        wsRef.current = null;
+        setSocketReady(false);
+
+        if (!mountedRef.current || !enabled) return;
+
+        // Fallback to HTTP polling or reconnect
+        if (debug) {
+          console.debug('[useStreamState] WebSocket closed, starting HTTP polling');
+        }
+        pollHttp();
+      };
+    } catch (error) {
+      console.warn('[useStreamState] WebSocket connection failed:', error);
+      // Fallback to HTTP polling
+      pollHttp();
+    }
+  }, [mistBaseUrl, streamName, enabled, useWebSocket, debug, processStreamInfo, pollHttp]);
+
+  /**
+   * Manual refetch function
+   */
+  const refetch = useCallback(() => {
+    if (useWebSocket && wsRef.current?.readyState === WebSocket.OPEN) {
+      // WebSocket will receive updates automatically
+      return;
+    }
+    pollHttp();
+  }, [useWebSocket, pollHttp]);
+
+  /**
+   * Setup connection on mount and when options change
+   * Always do initial HTTP poll to get full stream info (including sources),
+   * then connect WebSocket for real-time status updates.
+   * MistServer WebSocket updates may not include source array.
+   */
+  useEffect(() => {
+    mountedRef.current = true;
+
+    if (!enabled || !mistBaseUrl || !streamName) {
+      setState(initialState);
+      return;
+    }
+
+    // Reset state when stream changes
+    setState({
+      ...initialState,
+      message: 'Connecting...',
+      lastUpdate: Date.now(),
+    });
+
+    // Always do initial HTTP poll to get full data (including sources)
+    // Then connect WebSocket for real-time updates
+    const initializeConnection = async () => {
+      // First HTTP poll to get complete stream info
+      await pollHttp();
+
+      // Then connect WebSocket for status updates (if enabled)
+      if (useWebSocket && mountedRef.current) {
+        connectWebSocket();
+      }
+    };
+
+    initializeConnection();
+
+    return () => {
+      // Set mounted=false FIRST before any other cleanup
+      mountedRef.current = false;
+      if (debug) {
+        console.debug('[useStreamState] cleanup starting, mountedRef set to false');
+      }
+
+      // Cleanup WebSocket timeout
+      if (wsTimeoutRef.current) {
+        clearTimeout(wsTimeoutRef.current);
+        wsTimeoutRef.current = null;
+      }
+
+      // Cleanup WebSocket - remove handlers BEFORE closing to prevent onclose callback
+      if (wsRef.current) {
+        // Detach handlers first to prevent onclose from triggering pollHttp
+        wsRef.current.onclose = null;
+        wsRef.current.onerror = null;
+        wsRef.current.onmessage = null;
+        wsRef.current.onopen = null;
+        wsRef.current.close();
+        wsRef.current = null;
+      }
+
+      // Cleanup polling timeout
+      if (pollTimeoutRef.current) {
+        clearTimeout(pollTimeoutRef.current);
+        pollTimeoutRef.current = null;
+      }
+    };
+  }, [enabled, mistBaseUrl, streamName, useWebSocket, debug, connectWebSocket, pollHttp]);
+
+  return {
+    ...state,
+    refetch,
+    socketRef: wsRef,
+    socketReady,
+  };
+}
+
+export default useStreamState;

package/src/hooks/useTelemetry.ts

@@ -0,0 +1,138 @@
+import { useEffect, useRef, useCallback } from 'react';
+import { TelemetryReporter, type TelemetryOptions, type PlaybackQuality, type ContentType } from '@livepeer-frameworks/player-core';
+
+export interface UseTelemetryOptions extends TelemetryOptions {
+  /** Video element to monitor */
+  videoElement: HTMLVideoElement | null;
+  /** Content ID being played */
+  contentId: string;
+  /** Content type */
+  contentType: ContentType;
+  /** Player type name */
+  playerType: string;
+  /** Protocol being used */
+  protocol: string;
+  /** Optional quality getter function */
+  getQuality?: () => PlaybackQuality | null;
+}
+
+/**
+ * Hook to send telemetry data to a server
+ *
+ * Reports playback metrics at configurable intervals:
+ * - Current time and duration
+ * - Buffer health
+ * - Stall count and duration
+ * - Quality score and bitrate
+ * - Frame decode/drop stats
+ * - Errors encountered
+ *
+ * Uses navigator.sendBeacon() for reliable reporting on page unload.
+ *
+ * @example
+ * ```tsx
+ * const { sessionId, recordError } = useTelemetry({
+ *   enabled: true,
+ *   endpoint: '/api/telemetry',
+ *   interval: 5000,
+ *   videoElement,
+ *   contentId: 'my-stream',
+ *   contentType: 'live',
+ *   playerType: 'hlsjs',
+ *   protocol: 'HLS',
+ *   getQuality: () => qualityMonitor.getCurrentQuality(),
+ * });
+ *
+ * // Record custom error
+ * recordError('NETWORK_ERROR', 'Connection lost');
+ * ```
+ */
+export function useTelemetry(options: UseTelemetryOptions) {
+  const {
+    enabled,
+    endpoint,
+    interval,
+    authToken,
+    batchSize,
+    videoElement,
+    contentId,
+    contentType,
+    playerType,
+    protocol,
+    getQuality,
+  } = options;
+
+  const reporterRef = useRef<TelemetryReporter | null>(null);
+
+  // Create reporter instance
+  useEffect(() => {
+    if (!enabled || !endpoint || !contentId) {
+      reporterRef.current?.stop();
+      reporterRef.current = null;
+      return;
+    }
+
+    reporterRef.current = new TelemetryReporter({
+      endpoint,
+      authToken,
+      interval,
+      batchSize,
+      contentId,
+      contentType,
+      playerType,
+      protocol,
+    });
+
+    return () => {
+      reporterRef.current?.stop();
+      reporterRef.current = null;
+    };
+  }, [enabled, endpoint, authToken, interval, batchSize, contentId, contentType, playerType, protocol]);
+
+  // Start/stop reporting when video element changes
+  useEffect(() => {
+    if (!enabled || !videoElement || !reporterRef.current) {
+      return;
+    }
+
+    reporterRef.current.start(videoElement, getQuality);
+
+    return () => {
+      reporterRef.current?.stop();
+    };
+  }, [enabled, videoElement, getQuality]);
+
+  /**
+   * Record a custom error
+   */
+  const recordError = useCallback((code: string, message: string) => {
+    reporterRef.current?.recordError(code, message);
+  }, []);
+
+  /**
+   * Get current session ID
+   */
+  const getSessionId = useCallback((): string | null => {
+    return reporterRef.current?.getSessionId() ?? null;
+  }, []);
+
+  /**
+   * Check if telemetry is active
+   */
+  const isActive = useCallback((): boolean => {
+    return reporterRef.current?.isActive() ?? false;
+  }, []);
+
+  return {
+    /** Session ID for this playback session */
+    sessionId: reporterRef.current?.getSessionId() ?? null,
+    /** Record a custom error */
+    recordError,
+    /** Get current session ID */
+    getSessionId,
+    /** Check if telemetry is active */
+    isActive,
+  };
+}
+
+export default useTelemetry;

package/src/hooks/useViewerEndpoints.ts

@@ -0,0 +1,120 @@
+import { useEffect, useState, useRef } from 'react';
+import type { ContentType } from '@livepeer-frameworks/player-core';
+import type { ContentEndpoints } from '../types';
+
+const MAX_RETRIES = 3;
+const INITIAL_DELAY_MS = 500;
+
+interface Params {
+  gatewayUrl: string;
+  contentType: ContentType;
+  contentId: string;
+  authToken?: string;
+}
+
+async function fetchWithRetry(
+  url: string,
+  options: RequestInit,
+  maxRetries: number = MAX_RETRIES,
+  initialDelay: number = INITIAL_DELAY_MS
+): Promise<Response> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, options);
+      return response;
+    } catch (e) {
+      lastError = e instanceof Error ? e : new Error('Fetch failed');
+
+      // Don't retry on abort
+      if (options.signal?.aborted) {
+        throw lastError;
+      }
+
+      // Wait before retrying (exponential backoff)
+      if (attempt < maxRetries - 1) {
+        const delay = initialDelay * Math.pow(2, attempt);
+        console.warn(`[useViewerEndpoints] Retry ${attempt + 1}/${maxRetries - 1} after ${delay}ms`);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw lastError ?? new Error('Gateway unreachable after retries');
+}
+
+export function useViewerEndpoints({ gatewayUrl, contentType, contentId, authToken }: Params) {
+  const [endpoints, setEndpoints] = useState<ContentEndpoints | null>(null);
+  const [status, setStatus] = useState<'idle' | 'loading' | 'ready' | 'error'>('idle');
+  const [error, setError] = useState<string | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    if (!gatewayUrl || !contentType || !contentId) return;
+    setStatus('loading');
+    setError(null);
+    abortRef.current?.abort();
+    const ac = new AbortController();
+    abortRef.current = ac;
+
+    (async () => {
+      try {
+        const graphqlEndpoint = gatewayUrl.replace(/\/$/, '');
+        const query = `
+          query ResolveViewer($contentType: String!, $contentId: String!) {
+            resolveViewerEndpoint(contentType: $contentType, contentId: $contentId) {
+              primary { nodeId baseUrl protocol url geoDistance loadScore outputs }
+              fallbacks { nodeId baseUrl protocol url geoDistance loadScore outputs }
+              metadata { contentType contentId title description durationSeconds status isLive viewers recordingSizeBytes clipSource createdAt }
+            }
+          }
+        `;
+        const res = await fetchWithRetry(graphqlEndpoint, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+          },
+          body: JSON.stringify({ query, variables: { contentType, contentId } }),
+          signal: ac.signal,
+        });
+        if (!res.ok) throw new Error(`Gateway GQL error ${res.status}`);
+        const payload = await res.json();
+        if (payload.errors?.length) throw new Error(payload.errors[0]?.message || 'GraphQL error');
+        const resp = payload.data?.resolveViewerEndpoint;
+        const primary = resp?.primary;
+        const fallbacks = Array.isArray(resp?.fallbacks) ? resp.fallbacks : [];
+        if (!primary) throw new Error('No endpoints');
+
+        // Parse outputs JSON string (GraphQL returns JSON scalar as string)
+        if (primary.outputs && typeof primary.outputs === 'string') {
+          try { primary.outputs = JSON.parse(primary.outputs); } catch {}
+        }
+        if (fallbacks) {
+          fallbacks.forEach((fb: any) => {
+            if (fb.outputs && typeof fb.outputs === 'string') {
+              try { fb.outputs = JSON.parse(fb.outputs); } catch {}
+            }
+          });
+        }
+
+        setEndpoints({ primary, fallbacks, metadata: resp?.metadata });
+        setStatus('ready');
+      } catch (e) {
+        if (ac.signal.aborted) return;
+        const message = e instanceof Error ? e.message : 'Unknown gateway error';
+        console.error('[useViewerEndpoints] Gateway resolution failed:', message);
+        setError(message);
+        setStatus('error');
+      }
+    })();
+
+    return () => ac.abort();
+  }, [gatewayUrl, contentType, contentId, authToken]);
+
+  return { endpoints, status, error };
+}
+
+export default useViewerEndpoints;
+