@livepeer-frameworks/player-react 0.0.3

package/src/components/StreamStateOverlay.tsx

@@ -0,0 +1,200 @@
+import React from 'react';
+import type { StreamStatus } from '../types';
+
+export interface StreamStateOverlayProps {
+  /** Current stream status */
+  status: StreamStatus;
+  /** Human-readable message */
+  message: string;
+  /** Processing percentage (for INITIALIZING state) */
+  percentage?: number;
+  /** Callback for retry button */
+  onRetry?: () => void;
+  /** Whether to show the overlay */
+  visible?: boolean;
+  /** Additional className */
+  className?: string;
+}
+
+/**
+ * Get status icon based on stream state
+ */
+function StatusIcon({ status }: { status: StreamStatus }) {
+  const iconClass = "w-5 h-5";
+
+  switch (status) {
+    case 'ONLINE':
+      return (
+        <svg className={`${iconClass} fw-status-online`} fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+        </svg>
+      );
+
+    case 'OFFLINE':
+      return (
+        <svg className={`${iconClass} fw-status-offline`} fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M18.364 5.636a9 9 0 010 12.728m0 0l-2.829-2.829m2.829 2.829L21 21M15.536 8.464a5 5 0 010 7.072m0 0l-2.829-2.829m-4.243 2.829a4.978 4.978 0 01-1.414-2.83m-1.414 5.658a9 9 0 01-2.167-9.238m7.824 2.167a1 1 0 111.414 1.414m-1.414-1.414L3 3m8.293 8.293l1.414 1.414" />
+        </svg>
+      );
+
+    case 'INITIALIZING':
+    case 'BOOTING':
+    case 'WAITING_FOR_DATA':
+      return (
+        <svg className={`${iconClass} fw-status-warning animate-spin`} fill="none" viewBox="0 0 24 24">
+          <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+          <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+        </svg>
+      );
+
+    case 'SHUTTING_DOWN':
+      return (
+        <svg className={`${iconClass} fw-status-warning`} fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
+        </svg>
+      );
+
+    case 'ERROR':
+    case 'INVALID':
+    default:
+      return (
+        <svg className={`${iconClass} fw-status-offline`} fill="none" viewBox="0 0 24 24" stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+        </svg>
+      );
+  }
+}
+
+/**
+ * Get status label for header
+ */
+function getStatusLabel(status: StreamStatus): string {
+  switch (status) {
+    case 'ONLINE': return 'ONLINE';
+    case 'OFFLINE': return 'OFFLINE';
+    case 'INITIALIZING': return 'INITIALIZING';
+    case 'BOOTING': return 'STARTING';
+    case 'WAITING_FOR_DATA': return 'WAITING';
+    case 'SHUTTING_DOWN': return 'ENDING';
+    case 'ERROR': return 'ERROR';
+    case 'INVALID': return 'INVALID';
+    default: return 'STATUS';
+  }
+}
+
+/**
+ * StreamStateOverlay - Shows stream status when not playable
+ *
+ * Slab-based design with header/body/actions zones.
+ * Uses Tokyo Night color palette and seam-based layout.
+ */
+export const StreamStateOverlay: React.FC<StreamStateOverlayProps> = ({
+  status,
+  message,
+  percentage,
+  onRetry,
+  visible = true,
+  className = '',
+}) => {
+  if (!visible || status === 'ONLINE') {
+    return null;
+  }
+
+  const showRetry = status === 'ERROR' || status === 'INVALID' || status === 'OFFLINE';
+  const showProgress = status === 'INITIALIZING' && percentage !== undefined;
+
+  return (
+    <div
+      className={`absolute inset-0 z-20 flex items-center justify-center ${className}`}
+      style={{ backgroundColor: 'hsl(var(--tn-bg-dark) / 0.8)', backdropFilter: 'blur(4px)' }}
+      role="status"
+      aria-live="polite"
+    >
+      {/* Slab container - no rounded corners, seam borders */}
+      <div
+        className="fw-slab w-[280px] max-w-[90%]"
+        style={{ backgroundColor: 'hsl(var(--tn-bg) / 0.95)' }}
+      >
+        {/* Slab header - status label with icon */}
+        <div className="fw-slab-header flex items-center gap-2">
+          <StatusIcon status={status} />
+          <span>{getStatusLabel(status)}</span>
+        </div>
+
+        {/* Slab body - message and progress */}
+        <div className="fw-slab-body">
+          <p className="text-sm" style={{ color: 'hsl(var(--tn-fg))' }}>
+            {message}
+          </p>
+
+          {showProgress && (
+            <div className="mt-3">
+              {/* Progress bar - no rounded corners */}
+              <div
+                className="h-1.5 w-full overflow-hidden"
+                style={{ backgroundColor: 'hsl(var(--tn-bg-visual))' }}
+              >
+                <div
+                  className="h-full transition-all duration-300"
+                  style={{
+                    width: `${Math.min(100, percentage)}%`,
+                    backgroundColor: 'hsl(var(--tn-yellow))',
+                  }}
+                />
+              </div>
+              <p
+                className="mt-1.5 text-xs font-mono"
+                style={{ color: 'hsl(var(--tn-fg-dark))' }}
+              >
+                {Math.round(percentage)}%
+              </p>
+            </div>
+          )}
+
+          {status === 'OFFLINE' && (
+            <p className="mt-2 text-xs" style={{ color: 'hsl(var(--tn-fg-dark))' }}>
+              The stream will start when the broadcaster goes live
+            </p>
+          )}
+
+          {(status === 'BOOTING' || status === 'WAITING_FOR_DATA') && (
+            <p className="mt-2 text-xs" style={{ color: 'hsl(var(--tn-fg-dark))' }}>
+              Please wait while the stream prepares...
+            </p>
+          )}
+
+          {/* Polling indicator for non-error states */}
+          {!showRetry && (
+            <div
+              className="mt-3 flex items-center gap-2 text-xs"
+              style={{ color: 'hsl(var(--tn-fg-dark))' }}
+            >
+              <span
+                className="h-1.5 w-1.5 animate-pulse"
+                style={{ backgroundColor: 'hsl(var(--tn-cyan))' }}
+              />
+              <span>Checking stream status...</span>
+            </div>
+          )}
+        </div>
+
+        {/* Slab actions - flush retry button */}
+        {showRetry && onRetry && (
+          <div className="fw-slab-actions">
+            <button
+              type="button"
+              onClick={onRetry}
+              className="fw-btn-flush py-2.5 text-xs font-medium uppercase tracking-wide"
+              style={{ color: 'hsl(var(--tn-blue))' }}
+              aria-label="Retry connection"
+            >
+              Retry Connection
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default StreamStateOverlay;

package/src/components/SubtitleRenderer.tsx

@@ -0,0 +1,235 @@
+import React, { useEffect, useState, useRef, useCallback } from 'react';
+import type { SubtitleCue, MetaTrackEvent } from '../types';
+
+export interface SubtitleRendererProps {
+  /** Current video playback time in seconds */
+  currentTime: number;
+  /** Whether subtitles are enabled */
+  enabled?: boolean;
+  /** Subtitle cues to render (static or from meta track) */
+  cues?: SubtitleCue[];
+  /** Subscribe to meta track function (for live subtitles) */
+  subscribeToMetaTrack?: (trackId: string, callback: (event: MetaTrackEvent) => void) => () => void;
+  /** Meta track ID for live subtitles */
+  metaTrackId?: string;
+  /** Custom styles */
+  style?: SubtitleStyle;
+  /** Container class name */
+  className?: string;
+}
+
+export interface SubtitleStyle {
+  /** Font size (default: '1.5rem') */
+  fontSize?: string;
+  /** Font family (default: system) */
+  fontFamily?: string;
+  /** Text color (default: 'white') */
+  color?: string;
+  /** Background color (default: 'rgba(0,0,0,0.75)') */
+  backgroundColor?: string;
+  /** Text shadow for readability */
+  textShadow?: string;
+  /** Bottom offset from video (default: '5%') */
+  bottom?: string;
+  /** Max width (default: '90%') */
+  maxWidth?: string;
+  /** Padding (default: '0.5em 1em') */
+  padding?: string;
+  /** Border radius (default: '4px') */
+  borderRadius?: string;
+}
+
+const DEFAULT_STYLE: SubtitleStyle = {
+  fontSize: '1.5rem',
+  fontFamily: 'system-ui, -apple-system, sans-serif',
+  color: 'white',
+  backgroundColor: 'rgba(0, 0, 0, 0.75)',
+  textShadow: '2px 2px 4px rgba(0, 0, 0, 0.5)',
+  bottom: '5%',
+  maxWidth: '90%',
+  padding: '0.5em 1em',
+  borderRadius: '4px',
+};
+
+/**
+ * Parse subtitle cue from meta track event data
+ */
+function parseSubtitleCue(data: unknown): SubtitleCue | null {
+  if (typeof data !== 'object' || data === null) return null;
+
+  const obj = data as Record<string, unknown>;
+
+  // Extract text
+  const text = typeof obj.text === 'string' ? obj.text : String(obj.text ?? '');
+  if (!text) return null;
+
+  // Extract timing
+  let startTime = 0;
+  let endTime = Infinity;
+
+  if ('startTime' in obj) startTime = Number(obj.startTime);
+  else if ('start' in obj) startTime = Number(obj.start);
+
+  if ('endTime' in obj) endTime = Number(obj.endTime);
+  else if ('end' in obj) endTime = Number(obj.end);
+
+  // Extract ID
+  const id = typeof obj.id === 'string' ? obj.id : String(Date.now());
+
+  return {
+    id,
+    text,
+    startTime,
+    endTime,
+    lang: typeof obj.lang === 'string' ? obj.lang : undefined,
+  };
+}
+
+/**
+ * SubtitleRenderer - Renders live or static subtitles over video
+ *
+ * Supports:
+ * - Static cue list (pre-loaded)
+ * - Live cues from meta track subscription
+ * - Customizable styling (font, colors, position)
+ * - Automatic timing synchronization with video
+ *
+ * @example
+ * ```tsx
+ * // Static subtitles
+ * <SubtitleRenderer
+ *   currentTime={videoElement.currentTime}
+ *   enabled={showSubtitles}
+ *   cues={subtitleCues}
+ * />
+ *
+ * // Live subtitles from meta track
+ * const { subscribe } = useMetaTrack({ mistBaseUrl, streamName });
+ *
+ * <SubtitleRenderer
+ *   currentTime={videoElement.currentTime}
+ *   enabled={showSubtitles}
+ *   subscribeToMetaTrack={subscribe}
+ *   metaTrackId="subtitle-track"
+ * />
+ * ```
+ */
+export const SubtitleRenderer: React.FC<SubtitleRendererProps> = ({
+  currentTime,
+  enabled = true,
+  cues: staticCues,
+  subscribeToMetaTrack,
+  metaTrackId,
+  style: customStyle,
+  className = '',
+}) => {
+  const [liveCues, setLiveCues] = useState<SubtitleCue[]>([]);
+  const [displayedText, setDisplayedText] = useState<string>('');
+  const lastCueIdRef = useRef<string | null>(null);
+
+  const style = { ...DEFAULT_STYLE, ...customStyle };
+
+  // All available cues (static + live)
+  const allCues = [...(staticCues ?? []), ...liveCues];
+
+  // Subscribe to live subtitles if meta track is configured
+  useEffect(() => {
+    if (!enabled || !subscribeToMetaTrack || !metaTrackId) {
+      return;
+    }
+
+    const handleMetaEvent = (event: MetaTrackEvent) => {
+      if (event.type === 'subtitle') {
+        const cue = parseSubtitleCue(event.data);
+        if (cue) {
+          setLiveCues(prev => {
+            // Deduplicate by ID
+            const existing = prev.find(c => c.id === cue.id);
+            if (existing) return prev;
+
+            // Keep last 50 cues max
+            const updated = [...prev, cue];
+            return updated.slice(-50);
+          });
+        }
+      }
+    };
+
+    const unsubscribe = subscribeToMetaTrack(metaTrackId, handleMetaEvent);
+
+    return () => {
+      unsubscribe();
+    };
+  }, [enabled, subscribeToMetaTrack, metaTrackId]);
+
+  // Find active cue based on current time
+  useEffect(() => {
+    if (!enabled) {
+      setDisplayedText('');
+      return;
+    }
+
+    // Find cue that matches current time
+    const currentTimeMs = currentTime * 1000; // Convert to ms if needed
+    const activeCue = allCues.find(cue => {
+      const start = cue.startTime;
+      const end = cue.endTime;
+      return currentTimeMs >= start && currentTimeMs < end;
+    });
+
+    if (activeCue) {
+      setDisplayedText(activeCue.text);
+      lastCueIdRef.current = activeCue.id;
+    } else {
+      setDisplayedText('');
+      lastCueIdRef.current = null;
+    }
+  }, [enabled, currentTime, allCues]);
+
+  // Clean up expired cues
+  useEffect(() => {
+    const currentTimeMs = currentTime * 1000;
+
+    setLiveCues(prev => {
+      // Remove cues that are more than 30 seconds old
+      return prev.filter(cue => {
+        const endTime = cue.endTime === Infinity ? cue.startTime + 10000 : cue.endTime;
+        return endTime >= currentTimeMs - 30000;
+      });
+    });
+  }, [currentTime]);
+
+  if (!enabled || !displayedText) {
+    return null;
+  }
+
+  return (
+    <div
+      className={`fw-absolute fw-left-1/2 fw-transform fw--translate-x-1/2 fw-z-30 fw-text-center fw-pointer-events-none ${className}`}
+      style={{
+        bottom: style.bottom,
+        maxWidth: style.maxWidth,
+      }}
+      aria-live="polite"
+      role="region"
+      aria-label="Subtitles"
+    >
+      <span
+        className="fw-inline-block fw-whitespace-pre-wrap"
+        style={{
+          fontSize: style.fontSize,
+          fontFamily: style.fontFamily,
+          color: style.color,
+          backgroundColor: style.backgroundColor,
+          textShadow: style.textShadow,
+          padding: style.padding,
+          borderRadius: style.borderRadius,
+        }}
+      >
+        {displayedText}
+      </span>
+    </div>
+  );
+};
+
+export default SubtitleRenderer;

package/src/components/ThumbnailOverlay.tsx

@@ -0,0 +1,90 @@
+import React from "react";
+import { cn } from "@livepeer-frameworks/player-core";
+import { Button } from "../ui/button";
+import type { ThumbnailOverlayProps } from "../types";
+
+const ThumbnailOverlay: React.FC<ThumbnailOverlayProps> = ({
+  thumbnailUrl,
+  onPlay,
+  message,
+  showUnmuteMessage = false,
+  style,
+  className
+}) => {
+  const handleClick = (e: React.MouseEvent | React.KeyboardEvent) => {
+    e.stopPropagation();
+    onPlay?.();
+  };
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      onClick={handleClick}
+      onKeyDown={(event) => {
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault();
+          handleClick(event);
+        }
+      }}
+      style={style}
+      className={cn(
+        "fw-player-thumbnail relative flex h-full min-h-[280px] w-full cursor-pointer items-center justify-center overflow-hidden rounded-xl bg-slate-950 text-foreground outline-none transition focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+      , className)}
+    >
+      {thumbnailUrl && (
+        <div
+          className="absolute inset-0 bg-cover bg-center"
+          style={{ backgroundImage: `url(${thumbnailUrl})` }}
+        />
+      )}
+
+      <div
+        className={cn(
+          "absolute inset-0 bg-slate-950/70",
+          !thumbnailUrl && "bg-gradient-to-br from-slate-900 via-slate-950 to-slate-900"
+        )}
+      />
+
+      <div className="relative z-10 flex max-w-[320px] flex-col items-center gap-4 px-6 text-center text-sm sm:gap-6">
+        {showUnmuteMessage ? (
+          <div className="w-full rounded-lg border border-white/15 bg-black/80 p-4 text-sm text-white shadow-lg backdrop-blur">
+            <div className="mb-1 flex items-center justify-center gap-2 text-base font-semibold text-primary">
+              <span aria-hidden="true">🔇</span> Click to unmute
+            </div>
+            <p className="text-xs text-white/80">Stream is playing muted — tap to enable sound.</p>
+          </div>
+        ) : (
+          <>
+            <Button
+              type="button"
+              size="icon"
+              variant="secondary"
+              className="h-20 w-20 rounded-full bg-primary/90 text-primary-foreground shadow-lg shadow-primary/40 transition hover:bg-primary focus-visible:bg-primary"
+              aria-label="Play stream"
+            >
+              <svg
+                viewBox="0 0 24 24"
+                fill="currentColor"
+                className="ml-0.5 h-8 w-8"
+                aria-hidden="true"
+              >
+                <path d="M8 5v14l11-7z" />
+              </svg>
+            </Button>
+            <div className="w-full rounded-lg border border-white/10 bg-black/70 p-5 text-white shadow-inner backdrop-blur">
+              <p className="text-base font-semibold text-primary">
+                {message ?? "Click to play"}
+              </p>
+              <p className="mt-1 text-xs text-white/70">
+                {message ? "Start streaming instantly" : "Jump into the live feed"}
+              </p>
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default ThumbnailOverlay;

package/src/components/TitleOverlay.tsx

@@ -0,0 +1,48 @@
+import React from "react";
+import { cn } from "@livepeer-frameworks/player-core";
+
+interface TitleOverlayProps {
+  title?: string | null;
+  description?: string | null;
+  isVisible: boolean;
+  className?: string;
+}
+
+/**
+ * Title/description overlay that appears at the top of the player.
+ * Visible on hover or when paused - controlled by parent via isVisible prop.
+ */
+const TitleOverlay: React.FC<TitleOverlayProps> = ({
+  title,
+  description,
+  isVisible,
+  className,
+}) => {
+  // Don't render if no content
+  if (!title && !description) return null;
+
+  return (
+    <div
+      className={cn(
+        "fw-title-overlay absolute inset-x-0 top-0 z-20 pointer-events-none",
+        "bg-gradient-to-b from-black/70 via-black/40 to-transparent",
+        "px-4 py-3 transition-opacity duration-300",
+        isVisible ? "opacity-100" : "opacity-0",
+        className
+      )}
+    >
+      {title && (
+        <h2 className="text-white text-sm font-medium truncate max-w-[80%]">
+          {title}
+        </h2>
+      )}
+      {description && (
+        <p className="text-white/70 text-xs mt-0.5 line-clamp-2 max-w-[70%]">
+          {description}
+        </p>
+      )}
+    </div>
+  );
+};
+
+export default TitleOverlay;

package/src/components/players/DashJsPlayer.tsx

@@ -0,0 +1,56 @@
+/**
+ * DASH.js Player - React Wrapper
+ *
+ * MPEG-DASH streaming via dash.js library.
+ * The implementation is in @livepeer-frameworks/player-core.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import { DashJsPlayerImpl } from '@livepeer-frameworks/player-core';
+
+// Re-export the implementation from core for backwards compatibility
+export { DashJsPlayerImpl };
+
+type Props = {
+  src: string;
+  muted?: boolean;
+  autoPlay?: boolean;
+  controls?: boolean;
+  onError?: (e: Error) => void;
+};
+
+// React component wrapper
+const DashJsPlayer: React.FC<Props> = ({
+  src,
+  muted = true,
+  autoPlay = true,
+  controls = true,
+  onError
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<DashJsPlayerImpl | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const player = new DashJsPlayerImpl();
+    playerRef.current = player;
+
+    player.initialize(
+      containerRef.current,
+      { url: src, type: 'dash/video/mp4' },
+      { 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 DashJsPlayer;

package/src/components/players/HlsJsPlayer.tsx

@@ -0,0 +1,56 @@
+/**
+ * HLS.js Player - React Wrapper
+ *
+ * Adaptive HLS streaming via hls.js library.
+ * The implementation is in @livepeer-frameworks/player-core.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import { HlsJsPlayerImpl } from '@livepeer-frameworks/player-core';
+
+// Re-export the implementation from core for backwards compatibility
+export { HlsJsPlayerImpl };
+
+type Props = {
+  src: string;
+  muted?: boolean;
+  autoPlay?: boolean;
+  controls?: boolean;
+  onError?: (e: Error) => void;
+};
+
+// React component wrapper
+const HlsJsPlayer: React.FC<Props> = ({
+  src,
+  muted = true,
+  autoPlay = true,
+  controls = true,
+  onError
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<HlsJsPlayerImpl | null>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const player = new HlsJsPlayerImpl();
+    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 HlsJsPlayer;