@livepeer-frameworks/player-react 0.1.0 → 0.1.2

package/src/hooks/usePlayerController.ts

@@ -5,7 +5,7 @@
  * Manages the complete player lifecycle and provides reactive state.
  */
 
-import { useState, useEffect, useRef, useCallback } from 'react';
+import { useState, useEffect, useRef, useCallback } from "react";
 import {
   PlayerController,
   type PlayerControllerConfig,
@@ -15,13 +15,14 @@ import {
   type PlaybackQuality,
   type ContentEndpoints,
   type ContentMetadata,
-} from '@livepeer-frameworks/player-core';
+  type ClassifiedError,
+} from "@livepeer-frameworks/player-core";
 
 // ============================================================================
 // Types
 // ============================================================================
 
-export interface UsePlayerControllerConfig extends Omit<PlayerControllerConfig, 'playerManager'> {
+export interface UsePlayerControllerConfig extends Omit<PlayerControllerConfig, "playerManager"> {
   /** Enable/disable the hook */
   enabled?: boolean;
   /** Callback when state changes */
@@ -32,6 +33,20 @@ export interface UsePlayerControllerConfig extends Omit<PlayerControllerConfig,
   onError?: (error: string) => void;
   /** Callback when ready */
   onReady?: (videoElement: HTMLVideoElement) => void;
+  /** Callback when protocol is swapped (for toast notification) */
+  onProtocolSwapped?: (data: {
+    fromPlayer: string;
+    toPlayer: string;
+    fromProtocol: string;
+    toProtocol: string;
+    reason: string;
+  }) => void;
+  /** Callback when playback fails after all recovery attempts (for error modal) */
+  onPlaybackFailed?: (error: {
+    code: string;
+    message: string;
+    details?: ClassifiedError["details"];
+  }) => void;
 }
 
 export interface PlayerControllerState {
@@ -61,6 +76,8 @@ export interface PlayerControllerState {
   volume: number;
   /** Error text */
   error: string | null;
+  /** Error details for debugging */
+  errorDetails: ClassifiedError["details"] | null;
   /** Is passive error */
   isPassiveError: boolean;
   /** Has playback ever started */
@@ -92,11 +109,21 @@ export interface PlayerControllerState {
   /** Subtitles enabled */
   subtitlesEnabled: boolean;
   /** Available quality levels */
-  qualities: Array<{ id: string; label: string; bitrate?: number; width?: number; height?: number; isAuto?: boolean; active?: boolean }>;
+  qualities: Array<{
+    id: string;
+    label: string;
+    bitrate?: number;
+    width?: number;
+    height?: number;
+    isAuto?: boolean;
+    active?: boolean;
+  }>;
   /** Available text/caption tracks */
   textTracks: Array<{ id: string; label: string; language?: string; active: boolean }>;
   /** Stream info for player selection (sources + tracks) */
   streamInfo: StreamInfo | null;
+  /** Toast message to display (auto-dismisses) */
+  toast: { message: string; timestamp: number } | null;
 }
 
 export interface UsePlayerControllerReturn {
@@ -132,6 +159,8 @@ export interface UsePlayerControllerReturn {
   toggleSubtitles: () => void;
   /** Clear error */
   clearError: () => void;
+  /** Dismiss toast notification */
+  dismissToast: () => void;
   /** Retry playback */
   retry: () => Promise<void>;
   /** Reload player */
@@ -153,7 +182,7 @@ export interface UsePlayerControllerReturn {
     forcePlayer?: string;
     forceType?: string;
     forceSource?: number;
-    playbackMode?: 'auto' | 'low-latency' | 'quality' | 'vod';
+    playbackMode?: "auto" | "low-latency" | "quality" | "vod";
   }) => Promise<void>;
 }
 
@@ -162,7 +191,7 @@ export interface UsePlayerControllerReturn {
 // ============================================================================
 
 const initialState: PlayerControllerState = {
-  state: 'booting',
+  state: "booting",
   streamState: null,
   endpoints: null,
   metadata: null,
@@ -175,6 +204,7 @@ const initialState: PlayerControllerState = {
   isMuted: true,
   volume: 1,
   error: null,
+  errorDetails: null,
   isPassiveError: false,
   hasPlaybackStarted: false,
   isHoldingSpeed: false,
@@ -193,16 +223,24 @@ const initialState: PlayerControllerState = {
   qualities: [],
   textTracks: [],
   streamInfo: null,
+  toast: null,
 };
 
 // ============================================================================
 // Hook
 // ============================================================================
 
-export function usePlayerController(
-  config: UsePlayerControllerConfig
-): UsePlayerControllerReturn {
-  const { enabled = true, onStateChange, onStreamStateChange, onError, onReady, ...controllerConfig } = config;
+export function usePlayerController(config: UsePlayerControllerConfig): UsePlayerControllerReturn {
+  const {
+    enabled = true,
+    onStateChange,
+    onStreamStateChange,
+    onError,
+    onReady,
+    onProtocolSwapped,
+    onPlaybackFailed,
+    ...controllerConfig
+  } = config;
 
   const containerRef = useRef<HTMLDivElement>(null);
   const controllerRef = useRef<PlayerController | null>(null);
@@ -243,7 +281,7 @@ export function usePlayerController(
     const syncState = () => {
       if (!controllerRef.current) return;
       const c = controllerRef.current;
-      setState(prev => ({
+      setState((prev) => ({
         ...prev,
         isPlaying: c.isPlaying(),
         isPaused: c.isPaused(),
@@ -261,135 +299,192 @@ export function usePlayerController(
       }));
     };
 
-    unsubs.push(controller.on('stateChange', ({ state: newState }) => {
-      setState(prev => ({ ...prev, state: newState }));
-      onStateChange?.(newState);
-    }));
-
-    unsubs.push(controller.on('streamStateChange', ({ state: streamState }) => {
-      setState(prev => ({
-        ...prev,
-        streamState,
-        metadata: controller.getMetadata(),
-        isEffectivelyLive: controller.isEffectivelyLive(),
-        shouldShowIdleScreen: controller.shouldShowIdleScreen(),
-      }));
-      onStreamStateChange?.(streamState);
-    }));
-
-    unsubs.push(controller.on('timeUpdate', ({ currentTime, duration }) => {
-      setState(prev => ({ ...prev, currentTime, duration }));
-    }));
-
-    unsubs.push(controller.on('error', ({ error }) => {
-      setState(prev => ({
-        ...prev,
-        error,
-        isPassiveError: controller.isPassiveError(),
-      }));
-      onError?.(error);
-    }));
-
-    unsubs.push(controller.on('errorCleared', () => {
-      setState(prev => ({ ...prev, error: null, isPassiveError: false }));
-    }));
-
-    unsubs.push(controller.on('ready', ({ videoElement }) => {
-      setState(prev => ({
-        ...prev,
-        videoElement,
-        endpoints: controller.getEndpoints(),
-        metadata: controller.getMetadata(),
-        streamInfo: controller.getStreamInfo(),
-        isEffectivelyLive: controller.isEffectivelyLive(),
-        shouldShowIdleScreen: controller.shouldShowIdleScreen(),
-        currentPlayerInfo: controller.getCurrentPlayerInfo(),
-        currentSourceInfo: controller.getCurrentSourceInfo(),
-        qualities: controller.getQualities(),
-      }));
-      onReady?.(videoElement);
-
-      // Set up video event listeners AFTER video is ready
-      // syncState is defined below - this closure captures it
-      const handleVideoEvent = () => {
-        if (controllerRef.current?.shouldSuppressVideoEvents?.()) return;
-        syncState();
-      };
-      videoElement.addEventListener('play', handleVideoEvent);
-      videoElement.addEventListener('pause', handleVideoEvent);
-      videoElement.addEventListener('waiting', handleVideoEvent);
-      videoElement.addEventListener('playing', handleVideoEvent);
-      unsubs.push(() => {
-        videoElement.removeEventListener('play', handleVideoEvent);
-        videoElement.removeEventListener('pause', handleVideoEvent);
-        videoElement.removeEventListener('waiting', handleVideoEvent);
-        videoElement.removeEventListener('playing', handleVideoEvent);
-      });
-    }));
-
-    unsubs.push(controller.on('playerSelected', ({ player: _player, source }) => {
-      setState(prev => ({
-        ...prev,
-        currentPlayerInfo: controller.getCurrentPlayerInfo(),
-        currentSourceInfo: { url: source.url, type: source.type },
-        qualities: controller.getQualities(),
-      }));
-    }));
-
-    unsubs.push(controller.on('volumeChange', ({ volume, muted }) => {
-      setState(prev => ({ ...prev, volume, isMuted: muted }));
-    }));
-
-    unsubs.push(controller.on('loopChange', ({ isLoopEnabled }) => {
-      setState(prev => ({ ...prev, isLoopEnabled }));
-    }));
-
-    unsubs.push(controller.on('fullscreenChange', ({ isFullscreen }) => {
-      setState(prev => ({ ...prev, isFullscreen }));
-    }));
-
-    unsubs.push(controller.on('pipChange', ({ isPiP }) => {
-      setState(prev => ({ ...prev, isPiPActive: isPiP }));
-    }));
-
-    unsubs.push(controller.on('holdSpeedStart', ({ speed }) => {
-      setState(prev => ({ ...prev, isHoldingSpeed: true, holdSpeed: speed }));
-    }));
-
-    unsubs.push(controller.on('holdSpeedEnd', () => {
-      setState(prev => ({ ...prev, isHoldingSpeed: false }));
-    }));
-
-    unsubs.push(controller.on('hoverStart', () => {
-      setState(prev => ({ ...prev, isHovering: true, shouldShowControls: true }));
-    }));
-
-    unsubs.push(controller.on('hoverEnd', () => {
-      setState(prev => ({
-        ...prev,
-        isHovering: false,
-        shouldShowControls: controller.shouldShowControls(),
-      }));
-    }));
-
-    unsubs.push(controller.on('captionsChange', ({ enabled }) => {
-      setState(prev => ({ ...prev, subtitlesEnabled: enabled }));
-    }));
+    unsubs.push(
+      controller.on("stateChange", ({ state: newState }) => {
+        setState((prev) => ({ ...prev, state: newState }));
+        onStateChange?.(newState);
+      })
+    );
+
+    unsubs.push(
+      controller.on("streamStateChange", ({ state: streamState }) => {
+        setState((prev) => ({
+          ...prev,
+          streamState,
+          metadata: controller.getMetadata(),
+          isEffectivelyLive: controller.isEffectivelyLive(),
+          shouldShowIdleScreen: controller.shouldShowIdleScreen(),
+        }));
+        onStreamStateChange?.(streamState);
+      })
+    );
+
+    unsubs.push(
+      controller.on("timeUpdate", ({ currentTime, duration }) => {
+        setState((prev) => ({ ...prev, currentTime, duration }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("error", ({ error }) => {
+        setState((prev) => ({
+          ...prev,
+          error,
+          isPassiveError: controller.isPassiveError(),
+        }));
+        onError?.(error);
+      })
+    );
+
+    unsubs.push(
+      controller.on("errorCleared", () => {
+        setState((prev) => ({ ...prev, error: null, isPassiveError: false }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("ready", ({ videoElement }) => {
+        setState((prev) => ({
+          ...prev,
+          videoElement,
+          endpoints: controller.getEndpoints(),
+          metadata: controller.getMetadata(),
+          streamInfo: controller.getStreamInfo(),
+          isEffectivelyLive: controller.isEffectivelyLive(),
+          shouldShowIdleScreen: controller.shouldShowIdleScreen(),
+          currentPlayerInfo: controller.getCurrentPlayerInfo(),
+          currentSourceInfo: controller.getCurrentSourceInfo(),
+          qualities: controller.getQualities(),
+        }));
+        onReady?.(videoElement);
+
+        // Set up video event listeners AFTER video is ready
+        // syncState is defined below - this closure captures it
+        const handleVideoEvent = () => {
+          if (controllerRef.current?.shouldSuppressVideoEvents?.()) return;
+          syncState();
+        };
+        videoElement.addEventListener("play", handleVideoEvent);
+        videoElement.addEventListener("pause", handleVideoEvent);
+        videoElement.addEventListener("waiting", handleVideoEvent);
+        videoElement.addEventListener("playing", handleVideoEvent);
+        unsubs.push(() => {
+          videoElement.removeEventListener("play", handleVideoEvent);
+          videoElement.removeEventListener("pause", handleVideoEvent);
+          videoElement.removeEventListener("waiting", handleVideoEvent);
+          videoElement.removeEventListener("playing", handleVideoEvent);
+        });
+      })
+    );
+
+    unsubs.push(
+      controller.on("playerSelected", ({ player: _player, source }) => {
+        setState((prev) => ({
+          ...prev,
+          currentPlayerInfo: controller.getCurrentPlayerInfo(),
+          currentSourceInfo: { url: source.url, type: source.type },
+          qualities: controller.getQualities(),
+        }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("volumeChange", ({ volume, muted }) => {
+        setState((prev) => ({ ...prev, volume, isMuted: muted }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("loopChange", ({ isLoopEnabled }) => {
+        setState((prev) => ({ ...prev, isLoopEnabled }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("fullscreenChange", ({ isFullscreen }) => {
+        setState((prev) => ({ ...prev, isFullscreen }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("pipChange", ({ isPiP }) => {
+        setState((prev) => ({ ...prev, isPiPActive: isPiP }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("holdSpeedStart", ({ speed }) => {
+        setState((prev) => ({ ...prev, isHoldingSpeed: true, holdSpeed: speed }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("holdSpeedEnd", () => {
+        setState((prev) => ({ ...prev, isHoldingSpeed: false }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("hoverStart", () => {
+        setState((prev) => ({ ...prev, isHovering: true, shouldShowControls: true }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("hoverEnd", () => {
+        setState((prev) => ({
+          ...prev,
+          isHovering: false,
+          shouldShowControls: controller.shouldShowControls(),
+        }));
+      })
+    );
+
+    unsubs.push(
+      controller.on("captionsChange", ({ enabled }) => {
+        setState((prev) => ({ ...prev, subtitlesEnabled: enabled }));
+      })
+    );
+
+    // Error handling events - show toasts/modals
+    unsubs.push(
+      controller.on("protocolSwapped", (data) => {
+        const message = `Switched to ${data.toProtocol}`;
+        setState((prev) => ({ ...prev, toast: { message, timestamp: Date.now() } }));
+        onProtocolSwapped?.(data);
+      })
+    );
+
+    unsubs.push(
+      controller.on("playbackFailed", (data) => {
+        setState((prev) => ({
+          ...prev,
+          error: data.message,
+          errorDetails: data.details ?? null,
+          isPassiveError: false,
+        }));
+        onPlaybackFailed?.({
+          code: data.code,
+          message: data.message,
+          details: data.details,
+        });
+      })
+    );
 
     // Attach controller to container
     // Note: Video event listeners are set up in the 'ready' handler above
-    controller.attach(container).catch(err => {
-      console.warn('[usePlayerController] Attach failed:', err);
+    controller.attach(container).catch((err) => {
+      console.warn("[usePlayerController] Attach failed:", err);
     });
 
     // Set initial state
-    setState(prev => ({
+    setState((prev) => ({
       ...prev,
       isLoopEnabled: controller.isLoopEnabled(),
     }));
 
     return () => {
-      unsubs.forEach(fn => fn());
+      unsubs.forEach((fn) => fn());
       controller.destroy();
       controllerRef.current = null;
       setState(initialState);
@@ -443,7 +538,16 @@ export function usePlayerController(
 
   const clearError = useCallback(() => {
     controllerRef.current?.clearError();
-    setState(prev => ({ ...prev, error: null, isPassiveError: false }));
+    setState((prev) => ({
+      ...prev,
+      error: null,
+      errorDetails: null,
+      isPassiveError: false,
+    }));
+  }, []);
+
+  const dismissToast = useCallback(() => {
+    setState((prev) => ({ ...prev, toast: null }));
   }, []);
 
   const jumpToLive = useCallback(() => {
@@ -482,14 +586,17 @@ export function usePlayerController(
     controllerRef.current?.handleTouchStart();
   }, []);
 
-  const setDevModeOptions = useCallback(async (options: {
-    forcePlayer?: string;
-    forceType?: string;
-    forceSource?: number;
-    playbackMode?: 'auto' | 'low-latency' | 'quality' | 'vod';
-  }) => {
-    await controllerRef.current?.setDevModeOptions(options);
-  }, []);
+  const setDevModeOptions = useCallback(
+    async (options: {
+      forcePlayer?: string;
+      forceType?: string;
+      forceSource?: number;
+      playbackMode?: "auto" | "low-latency" | "quality" | "vod";
+    }) => {
+      await controllerRef.current?.setDevModeOptions(options);
+    },
+    []
+  );
 
   return {
     containerRef,
@@ -508,6 +615,7 @@ export function usePlayerController(
     togglePiP,
     toggleSubtitles,
     clearError,
+    dismissToast,
     retry,
     reload,
     getQualities,

package/src/hooks/usePlayerSelection.ts

@@ -5,14 +5,14 @@
  * Uses event-driven updates instead of polling - no render spam.
  */
 
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback } from "react";
 import type {
   PlayerManager,
   PlayerSelection,
   PlayerCombination,
   StreamInfo,
   PlaybackMode,
-} from '@livepeer-frameworks/player-core';
+} from "@livepeer-frameworks/player-core";
 
 export interface UsePlayerSelectionOptions {
   /** Stream info to compute selections for */
@@ -67,16 +67,16 @@ export function usePlayerSelection(
 
   // Subscribe to events
   useEffect(() => {
-    const unsubSelection = manager.on('selection-changed', (sel) => {
+    const unsubSelection = manager.on("selection-changed", (sel) => {
       if (debug) {
-        console.log('[usePlayerSelection] Selection changed:', sel?.player, sel?.source?.type);
+        console.log("[usePlayerSelection] Selection changed:", sel?.player, sel?.source?.type);
       }
       setSelection(sel);
     });
 
-    const unsubCombos = manager.on('combinations-updated', (combos) => {
+    const unsubCombos = manager.on("combinations-updated", (combos) => {
       if (debug) {
-        console.log('[usePlayerSelection] Combinations updated:', combos.length);
+        console.log("[usePlayerSelection] Combinations updated:", combos.length);
       }
       setCombinations(combos);
       setReady(true);