@livepeer-frameworks/player-react 0.0.3

package/src/components/players/MewsWsPlayer/index.tsx

@@ -0,0 +1,56 @@
+/**
+ * MEWS WebSocket Player - React Wrapper
+ *
+ * Low-latency WebSocket MP4 streaming using MediaSource Extensions.
+ * The implementation is in @livepeer-frameworks/player-core.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import { MewsWsPlayerImpl } from '@livepeer-frameworks/player-core';
+
+// Re-export the implementation from core for backwards compatibility
+export { MewsWsPlayerImpl };
+
+type Props = {
+  wsUrl: string;
+  muted?: boolean;
+  autoPlay?: boolean;
+  controls?: boolean;
+  onError?: (e: Error) => void;
+};
+
+// React component wrapper
+const MewsWsPlayer: React.FC<Props> = ({
+  wsUrl,
+  muted = true,
+  autoPlay = true,
+  controls = true,
+  onError
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<MewsWsPlayerImpl | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const player = new MewsWsPlayerImpl();
+    playerRef.current = player;
+
+    player.initialize(
+      containerRef.current,
+      { url: wsUrl, type: 'ws/video/mp4' },
+      { autoplay: autoPlay, muted, controls }
+    ).catch((e) => {
+      onError?.(e instanceof Error ? e : new Error(String(e)));
+    });
+
+    return () => {
+      player.destroy();
+      playerRef.current = null;
+    };
+  }, [wsUrl, muted, autoPlay, controls, onError]);
+
+  return <div ref={containerRef} style={{ width: '100%', height: '100%' }} />;
+};
+
+export default MewsWsPlayer;

package/src/components/players/MistPlayer.tsx

@@ -0,0 +1,60 @@
+/**
+ * MistServer Legacy Player - React Wrapper
+ *
+ * Fallback player using MistServer's native player.js.
+ * The implementation is in @livepeer-frameworks/player-core.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import { MistPlayerImpl } from '@livepeer-frameworks/player-core';
+
+// Re-export the implementation from core for backwards compatibility
+export { MistPlayerImpl };
+
+type Props = {
+  src: string;
+  streamName?: string;
+  muted?: boolean;
+  autoPlay?: boolean;
+  controls?: boolean;
+  devMode?: boolean;
+  onError?: (e: Error) => void;
+};
+
+// React component wrapper
+const MistPlayer: React.FC<Props> = ({
+  src,
+  streamName,
+  muted = true,
+  autoPlay = true,
+  controls = true,
+  devMode = false,
+  onError
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<MistPlayerImpl | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const player = new MistPlayerImpl();
+    playerRef.current = player;
+
+    player.initialize(
+      containerRef.current,
+      { url: src, type: 'mist/legacy', streamName },
+      { autoplay: autoPlay, muted, controls, devMode }
+    ).catch((e) => {
+      onError?.(e instanceof Error ? e : new Error(String(e)));
+    });
+
+    return () => {
+      player.destroy();
+      playerRef.current = null;
+    };
+  }, [src, streamName, muted, autoPlay, controls, devMode, onError]);
+
+  return <div ref={containerRef} style={{ width: '100%', height: '100%' }} />;
+};
+
+export default MistPlayer;

package/src/components/players/MistWebRTCPlayer/index.tsx

@@ -0,0 +1,59 @@
+/**
+ * MistWebRTC Player - React Wrapper
+ *
+ * MistServer native WebRTC with signaling for DVR support.
+ * The implementation is in @livepeer-frameworks/player-core.
+ */
+
+import React, { useRef, useEffect } from 'react';
+import { MistWebRTCPlayerImpl } from '@livepeer-frameworks/player-core';
+
+// Re-export the implementation from core for backwards compatibility
+export { MistWebRTCPlayerImpl };
+
+interface Props {
+  src: string;
+  autoPlay?: boolean;
+  muted?: boolean;
+  controls?: boolean;
+  poster?: string;
+  onReady?: (video: HTMLVideoElement) => void;
+  onError?: (error: Error) => void;
+}
+
+export const MistWebRTCPlayer: React.FC<Props> = ({
+  src,
+  autoPlay = true,
+  muted = true,
+  controls = true,
+  poster,
+  onReady,
+  onError,
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<MistWebRTCPlayerImpl | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const player = new MistWebRTCPlayerImpl();
+    playerRef.current = player;
+
+    player.initialize(
+      containerRef.current,
+      { url: src, type: 'webrtc' },
+      { autoplay: autoPlay, muted, controls, poster, onReady, onError: (e) => onError?.(typeof e === 'string' ? new Error(e) : e) }
+    ).catch((e) => {
+      onError?.(e instanceof Error ? e : new Error(String(e)));
+    });
+
+    return () => {
+      player.destroy();
+      playerRef.current = null;
+    };
+  }, [src, autoPlay, muted, controls, poster, onReady, onError]);
+
+  return <div ref={containerRef} style={{ width: '100%', height: '100%' }} />;
+};
+
+export default MistWebRTCPlayerImpl;

package/src/components/players/NativePlayer.tsx

@@ -0,0 +1,58 @@
+/**
+ * Native Player - React Wrapper
+ *
+ * HTML5 video and WHEP WebRTC playback.
+ * The implementation is in @livepeer-frameworks/player-core.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import { NativePlayerImpl, DirectPlaybackPlayerImpl } from '@livepeer-frameworks/player-core';
+
+// Re-export the implementations from core for backwards compatibility
+export { NativePlayerImpl, DirectPlaybackPlayerImpl };
+
+type Props = {
+  src: string;
+  type?: string;
+  muted?: boolean;
+  autoPlay?: boolean;
+  controls?: boolean;
+  onError?: (e: Error) => void;
+};
+
+// React component wrapper
+const NativePlayer: React.FC<Props> = ({
+  src,
+  type = 'html5/video/mp4',
+  muted = true,
+  autoPlay = true,
+  controls = true,
+  onError
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<NativePlayerImpl | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const player = new NativePlayerImpl();
+    playerRef.current = player;
+
+    player.initialize(
+      containerRef.current,
+      { url: src, type },
+      { autoplay: autoPlay, muted, controls }
+    ).catch((e) => {
+      onError?.(e instanceof Error ? e : new Error(String(e)));
+    });
+
+    return () => {
+      player.destroy();
+      playerRef.current = null;
+    };
+  }, [src, type, muted, autoPlay, controls, onError]);
+
+  return <div ref={containerRef} style={{ width: '100%', height: '100%' }} />;
+};
+
+export default NativePlayer;

package/src/components/players/VideoJsPlayer.tsx

@@ -0,0 +1,56 @@
+/**
+ * Video.js Player - React Wrapper
+ *
+ * HLS streaming via Video.js with VHS (videojs-http-streaming).
+ * The implementation is in @livepeer-frameworks/player-core.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import { VideoJsPlayerImpl } from '@livepeer-frameworks/player-core';
+
+// Re-export the implementation from core for backwards compatibility
+export { VideoJsPlayerImpl };
+
+type Props = {
+  src: string;
+  muted?: boolean;
+  autoPlay?: boolean;
+  controls?: boolean;
+  onError?: (e: Error) => void;
+};
+
+// React component wrapper
+const VideoJsPlayer: React.FC<Props> = ({
+  src,
+  muted = true,
+  autoPlay = true,
+  controls = true,
+  onError
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<VideoJsPlayerImpl | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const player = new VideoJsPlayerImpl();
+    playerRef.current = player;
+
+    player.initialize(
+      containerRef.current,
+      { url: src, type: 'html5/application/vnd.apple.mpegurl' },
+      { autoplay: autoPlay, muted, controls }
+    ).catch((e) => {
+      onError?.(e instanceof Error ? e : new Error(String(e)));
+    });
+
+    return () => {
+      player.destroy();
+      playerRef.current = null;
+    };
+  }, [src, muted, autoPlay, controls, onError]);
+
+  return <div ref={containerRef} style={{ width: '100%', height: '100%' }} />;
+};
+
+export default VideoJsPlayer;

package/src/context/PlayerContext.tsx

@@ -0,0 +1,71 @@
+/**
+ * PlayerContext
+ *
+ * React context for sharing PlayerController state across components.
+ * Follows the "context wraps hook" pattern (same as npm_studio).
+ *
+ * Usage:
+ * ```tsx
+ * <PlayerProvider config={{ contentId: 'stream-1', contentType: 'live' }}>
+ *   <PlayerControls />
+ * </PlayerProvider>
+ * ```
+ */
+
+import React, { createContext, useContext, type ReactNode } from 'react';
+import {
+  usePlayerController,
+  type UsePlayerControllerConfig,
+  type UsePlayerControllerReturn,
+} from '../hooks/usePlayerController';
+
+// Context holds the full hook return value
+const PlayerContext = createContext<UsePlayerControllerReturn | null>(null);
+
+export interface PlayerProviderProps {
+  children: ReactNode;
+  /** Configuration for the player controller */
+  config: UsePlayerControllerConfig;
+}
+
+/**
+ * Provider component that wraps Player and its controls.
+ * Calls usePlayerController internally and shares state via context.
+ */
+export function PlayerProvider({ children, config }: PlayerProviderProps) {
+  const playerController = usePlayerController(config);
+
+  return (
+    <PlayerContext.Provider value={playerController}>
+      {children}
+    </PlayerContext.Provider>
+  );
+}
+
+/**
+ * Hook to access player context.
+ * Must be used within a PlayerProvider.
+ */
+export function usePlayerContext(): UsePlayerControllerReturn {
+  const context = useContext(PlayerContext);
+  if (!context) {
+    throw new Error('usePlayerContext must be used within a PlayerProvider');
+  }
+  return context;
+}
+
+/**
+ * Hook to optionally access player context.
+ * Returns null if not within a PlayerProvider (no error thrown).
+ * Use this when component may or may not be within a PlayerProvider.
+ */
+export function usePlayerContextOptional(): UsePlayerControllerReturn | null {
+  return useContext(PlayerContext);
+}
+
+// Export context for advanced use cases
+export { PlayerContext };
+
+// Type exports
+export type { UsePlayerControllerReturn as PlayerContextValue };
+export type { UsePlayerControllerConfig };

package/src/context/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Context exports
+ */
+
+export {
+  PlayerProvider,
+  usePlayerContext,
+  usePlayerContextOptional,
+  PlayerContext
+} from './PlayerContext';
+export type { PlayerContextValue, UsePlayerControllerConfig } from './PlayerContext';

package/src/global.d.ts

@@ -0,0 +1,4 @@
+declare module "*.svg" {
+  const content: string;
+  export default content;
+}

package/src/hooks/useMetaTrack.ts

@@ -0,0 +1,187 @@
+import { useEffect, useState, useRef, useCallback } from 'react';
+import { MetaTrackManager, type MetaTrackSubscription, type MetaTrackEvent } from '@livepeer-frameworks/player-core';
+import type { UseMetaTrackOptions } from '../types';
+
+export interface UseMetaTrackReturn {
+  /** Whether connected to MistServer WebSocket */
+  isConnected: boolean;
+  /** Connection state */
+  connectionState: 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+  /** List of subscribed track IDs */
+  subscribedTracks: string[];
+  /** Subscribe to a meta track */
+  subscribe: (trackId: string, callback: (event: MetaTrackEvent) => void) => () => void;
+  /** Unsubscribe from a meta track */
+  unsubscribe: (trackId: string, callback: (event: MetaTrackEvent) => void) => void;
+  /** Manually connect */
+  connect: () => void;
+  /** Manually disconnect */
+  disconnect: () => void;
+  /** Update playback time for timed event dispatch (call on video timeupdate) */
+  setPlaybackTime: (timeInSeconds: number) => void;
+  /** Handle seek event (call on video seeking/seeked) */
+  onSeek: (newTimeInSeconds: number) => void;
+}
+
+/**
+ * Hook for subscribing to real-time metadata from MistServer
+ *
+ * Uses native MistServer WebSocket protocol for low-latency metadata delivery:
+ * - Subtitles/captions
+ * - Live scores
+ * - Timed events
+ * - Chapter markers
+ *
+ * @example
+ * ```tsx
+ * const { isConnected, subscribe } = useMetaTrack({
+ *   mistBaseUrl: 'https://mist.example.com',
+ *   streamName: 'my-stream',
+ *   enabled: true,
+ * });
+ *
+ * useEffect(() => {
+ *   if (!isConnected) return;
+ *
+ *   const unsubscribe = subscribe('1', (event) => {
+ *     if (event.type === 'subtitle') {
+ *       setSubtitle(event.data as SubtitleCue);
+ *     }
+ *   });
+ *
+ *   return unsubscribe;
+ * }, [isConnected, subscribe]);
+ * ```
+ */
+export function useMetaTrack(options: UseMetaTrackOptions): UseMetaTrackReturn {
+  const {
+    mistBaseUrl,
+    streamName,
+    subscriptions: initialSubscriptions,
+    enabled = true,
+  } = options;
+
+  const [isConnected, setIsConnected] = useState(false);
+  const [connectionState, setConnectionState] = useState<'disconnected' | 'connecting' | 'connected' | 'reconnecting'>('disconnected');
+  const [subscribedTracks, setSubscribedTracks] = useState<string[]>([]);
+  const managerRef = useRef<MetaTrackManager | null>(null);
+
+  // Create manager instance
+  useEffect(() => {
+    if (!enabled || !mistBaseUrl || !streamName) {
+      if (managerRef.current) {
+        managerRef.current.disconnect();
+        managerRef.current = null;
+      }
+      setIsConnected(false);
+      setConnectionState('disconnected');
+      return;
+    }
+
+    managerRef.current = new MetaTrackManager({
+      mistBaseUrl,
+      streamName,
+      subscriptions: initialSubscriptions,
+      debug: false,
+    });
+
+    // Start polling connection state
+    const pollState = () => {
+      if (managerRef.current) {
+        const state = managerRef.current.getState();
+        setConnectionState(state);
+        setIsConnected(state === 'connected');
+        setSubscribedTracks(managerRef.current.getSubscribedTracks());
+      }
+    };
+
+    const pollInterval = setInterval(pollState, 500);
+
+    // Connect
+    managerRef.current.connect();
+    pollState();
+
+    return () => {
+      clearInterval(pollInterval);
+      if (managerRef.current) {
+        managerRef.current.disconnect();
+        managerRef.current = null;
+      }
+      setIsConnected(false);
+      setConnectionState('disconnected');
+    };
+  }, [enabled, mistBaseUrl, streamName, initialSubscriptions]);
+
+  /**
+   * Subscribe to a meta track
+   */
+  const subscribe = useCallback((trackId: string, callback: (event: MetaTrackEvent) => void): () => void => {
+    if (!managerRef.current) {
+      return () => {};
+    }
+
+    const unsubscribe = managerRef.current.subscribe(trackId, callback);
+    setSubscribedTracks(managerRef.current.getSubscribedTracks());
+
+    return () => {
+      unsubscribe();
+      if (managerRef.current) {
+        setSubscribedTracks(managerRef.current.getSubscribedTracks());
+      }
+    };
+  }, []);
+
+  /**
+   * Unsubscribe from a meta track
+   */
+  const unsubscribe = useCallback((trackId: string, callback: (event: MetaTrackEvent) => void) => {
+    if (managerRef.current) {
+      managerRef.current.unsubscribe(trackId, callback);
+      setSubscribedTracks(managerRef.current.getSubscribedTracks());
+    }
+  }, []);
+
+  /**
+   * Manually connect
+   */
+  const connect = useCallback(() => {
+    managerRef.current?.connect();
+  }, []);
+
+  /**
+   * Manually disconnect
+   */
+  const disconnect = useCallback(() => {
+    managerRef.current?.disconnect();
+  }, []);
+
+  /**
+   * Update playback time for timed event dispatch
+   * Call this on video timeupdate events to keep subtitle/chapter timing in sync
+   */
+  const setPlaybackTime = useCallback((timeInSeconds: number) => {
+    managerRef.current?.setPlaybackTime(timeInSeconds);
+  }, []);
+
+  /**
+   * Handle seek event - clears buffered events and resets state
+   * Call this on video seeking/seeked events
+   */
+  const onSeek = useCallback((newTimeInSeconds: number) => {
+    managerRef.current?.onSeek(newTimeInSeconds);
+  }, []);
+
+  return {
+    isConnected,
+    connectionState,
+    subscribedTracks,
+    subscribe,
+    unsubscribe,
+    connect,
+    disconnect,
+    setPlaybackTime,
+    onSeek,
+  };
+}
+
+export default useMetaTrack;

package/src/hooks/usePlaybackQuality.ts

@@ -0,0 +1,126 @@
+import { useEffect, useState, useRef, useCallback } from 'react';
+import { QualityMonitor, type PlaybackQuality } from '@livepeer-frameworks/player-core';
+import type { UsePlaybackQualityOptions } from '../types';
+
+/**
+ * Hook to monitor video playback quality
+ *
+ * Tracks:
+ * - Buffer health (seconds ahead)
+ * - Stall count
+ * - Frame drop rate
+ * - Estimated bitrate
+ * - Latency (live streams)
+ * - Composite quality score (0-100)
+ *
+ * @example
+ * ```tsx
+ * const { quality, isMonitoring } = usePlaybackQuality({
+ *   videoElement,
+ *   enabled: true,
+ *   thresholds: { minScore: 60 },
+ *   onQualityDegraded: (q) => console.log('Quality dropped:', q.score),
+ * });
+ *
+ * return <div>Quality: {quality?.score ?? '--'}</div>;
+ * ```
+ */
+export function usePlaybackQuality(options: UsePlaybackQualityOptions) {
+  const {
+    videoElement,
+    enabled = true,
+    sampleInterval = 500,
+    thresholds,
+    onQualityDegraded,
+  } = options;
+
+  const [quality, setQuality] = useState<PlaybackQuality | null>(null);
+  const [isMonitoring, setIsMonitoring] = useState(false);
+  const monitorRef = useRef<QualityMonitor | null>(null);
+
+  // Create/update monitor instance
+  useEffect(() => {
+    monitorRef.current = new QualityMonitor({
+      sampleInterval,
+      thresholds,
+      onQualityDegraded,
+      onSample: setQuality,
+    });
+
+    return () => {
+      monitorRef.current?.stop();
+      monitorRef.current = null;
+    };
+  }, [sampleInterval, thresholds, onQualityDegraded]);
+
+  // Start/stop monitoring based on videoElement and enabled state
+  useEffect(() => {
+    if (!enabled || !videoElement || !monitorRef.current) {
+      monitorRef.current?.stop();
+      setIsMonitoring(false);
+      return;
+    }
+
+    monitorRef.current.start(videoElement);
+    setIsMonitoring(true);
+
+    return () => {
+      monitorRef.current?.stop();
+      setIsMonitoring(false);
+    };
+  }, [videoElement, enabled]);
+
+  /**
+   * Get current quality snapshot
+   */
+  const getCurrentQuality = useCallback((): PlaybackQuality | null => {
+    return monitorRef.current?.getCurrentQuality() ?? null;
+  }, []);
+
+  /**
+   * Get rolling average quality
+   */
+  const getAverageQuality = useCallback((): PlaybackQuality | null => {
+    return monitorRef.current?.getAverageQuality() ?? null;
+  }, []);
+
+  /**
+   * Get quality history
+   */
+  const getHistory = useCallback((): PlaybackQuality[] => {
+    return monitorRef.current?.getHistory() ?? [];
+  }, []);
+
+  /**
+   * Reset stall counters
+   */
+  const resetStallCounters = useCallback(() => {
+    monitorRef.current?.resetStallCounters();
+  }, []);
+
+  /**
+   * Get total stall time
+   */
+  const getTotalStallMs = useCallback((): number => {
+    return monitorRef.current?.getTotalStallMs() ?? 0;
+  }, []);
+
+  return {
+    /** Current quality metrics */
+    quality,
+    /** Whether monitoring is active */
+    isMonitoring,
+    /** Get current quality snapshot */
+    getCurrentQuality,
+    /** Get rolling average quality */
+    getAverageQuality,
+    /** Get quality history */
+    getHistory,
+    /** Reset stall counters */
+    resetStallCounters,
+    /** Get total stall time in ms */
+    getTotalStallMs,
+  };
+}
+
+export default usePlaybackQuality;