@livepeer-frameworks/player-react 0.0.3

package/src/components/PlayerErrorBoundary.tsx

@@ -0,0 +1,70 @@
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+import { Button } from '../ui/button';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+  onRetry?: () => void;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+}
+
+/**
+ * Error boundary to catch and handle player errors gracefully.
+ * Prevents player errors from crashing the parent application.
+ */
+class PlayerErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    console.error('[PlayerErrorBoundary] Caught error:', error, errorInfo);
+    this.props.onError?.(error, errorInfo);
+  }
+
+  handleRetry = (): void => {
+    this.setState({ hasError: false, error: null });
+    this.props.onRetry?.();
+  };
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      return (
+        <div className="fw-player-error flex min-h-[280px] flex-col items-center justify-center gap-4 rounded-xl bg-slate-950 p-6 text-center text-white">
+          <div className="text-lg font-semibold text-red-400">
+            Playback Error
+          </div>
+          <p className="max-w-sm text-sm text-slate-400">
+            {this.state.error?.message || 'An unexpected error occurred while loading the player.'}
+          </p>
+          <Button
+            type="button"
+            variant="secondary"
+            onClick={this.handleRetry}
+            className="mt-2"
+          >
+            Try Again
+          </Button>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+export default PlayerErrorBoundary;

package/src/components/SeekBar.tsx

@@ -0,0 +1,291 @@
+import React, { useRef, useState, useCallback, useMemo } from "react";
+import { cn } from "@livepeer-frameworks/player-core";
+
+interface SeekBarProps {
+  /** Current playback time in seconds */
+  currentTime: number;
+  /** Total duration in seconds */
+  duration: number;
+  /** Buffered time ranges from video element */
+  buffered?: TimeRanges;
+  /** Whether seeking is allowed */
+  disabled?: boolean;
+  /** Called when user seeks to a new time */
+  onSeek?: (time: number) => void;
+  /** Additional class names */
+  className?: string;
+  /** Whether this is a live stream */
+  isLive?: boolean;
+  /** For live: start of seekable DVR window (seconds) */
+  seekableStart?: number;
+  /** For live: current live edge position (seconds) */
+  liveEdge?: number;
+  /** Defer seeking until drag release */
+  commitOnRelease?: boolean;
+}
+
+/**
+ * Industry-standard video seek bar with:
+ * - Track background
+ * - Buffer progress indicator
+ * - Playback progress indicator
+ * - Thumb on hover
+ * - Time tooltip on hover (relative for live: "-5:30")
+ */
+const SeekBar: React.FC<SeekBarProps> = ({
+  currentTime,
+  duration,
+  buffered,
+  disabled = false,
+  onSeek,
+  className,
+  isLive = false,
+  seekableStart = 0,
+  liveEdge,
+  commitOnRelease = false,
+}) => {
+  const trackRef = useRef<HTMLDivElement>(null);
+  const [isHovering, setIsHovering] = useState(false);
+  const [isDragging, setIsDragging] = useState(false);
+  const [dragTime, setDragTime] = useState<number | null>(null);
+  const dragTimeRef = useRef<number | null>(null);
+  const [hoverPosition, setHoverPosition] = useState(0);
+  const [hoverTime, setHoverTime] = useState(0);
+
+  // Effective live edge (use provided or fall back to duration)
+  const effectiveLiveEdge = liveEdge ?? duration;
+
+  // Seekable window size
+  const seekableWindow = effectiveLiveEdge - seekableStart;
+
+  // Calculate progress percentage
+  // For live streams: position within the DVR window
+  // For VOD: position within total duration
+  const displayTime = dragTime ?? currentTime;
+  const progressPercent = useMemo(() => {
+    if (isLive && seekableWindow > 0) {
+      const positionInWindow = displayTime - seekableStart;
+      return Math.min(100, Math.max(0, (positionInWindow / seekableWindow) * 100));
+    }
+    if (!Number.isFinite(duration) || duration <= 0) return 0;
+    return Math.min(100, Math.max(0, (displayTime / duration) * 100));
+  }, [displayTime, duration, isLive, seekableStart, seekableWindow]);
+
+  // Calculate buffered segments as array of {start%, end%} for accurate display
+  const bufferedSegments = useMemo(() => {
+    if (!buffered || buffered.length === 0) return [];
+
+    const rangeEnd = isLive ? effectiveLiveEdge : duration;
+    const rangeStart = isLive ? seekableStart : 0;
+    const rangeSize = rangeEnd - rangeStart;
+
+    if (!Number.isFinite(rangeSize) || rangeSize <= 0) return [];
+
+    const segments: Array<{ startPercent: number; endPercent: number }> = [];
+    for (let i = 0; i < buffered.length; i++) {
+      const start = buffered.start(i);
+      const end = buffered.end(i);
+
+      // Calculate position relative to the seekable range
+      const relativeStart = start - rangeStart;
+      const relativeEnd = end - rangeStart;
+
+      segments.push({
+        startPercent: Math.min(100, Math.max(0, (relativeStart / rangeSize) * 100)),
+        endPercent: Math.min(100, Math.max(0, (relativeEnd / rangeSize) * 100)),
+      });
+    }
+    return segments;
+  }, [buffered, duration, isLive, seekableStart, effectiveLiveEdge]);
+
+  // Format time as MM:SS or HH:MM:SS (for VOD)
+  const formatTime = useCallback((seconds: number): string => {
+    if (!Number.isFinite(seconds) || seconds < 0) return "0:00";
+    const total = Math.floor(seconds);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const secs = total % 60;
+    if (hours > 0) {
+      return `${hours}:${String(minutes).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
+    }
+    return `${minutes}:${String(secs).padStart(2, "0")}`;
+  }, []);
+
+  // Format relative time for live streams (e.g., "-5:30" = 5:30 behind live edge)
+  const formatLiveTime = useCallback((seconds: number, edge: number): string => {
+    const behindSeconds = edge - seconds;
+    if (behindSeconds < 1) return "LIVE";
+    const total = Math.floor(behindSeconds);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const secs = total % 60;
+    if (hours > 0) {
+      return `-${hours}:${String(minutes).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
+    }
+    return `-${minutes}:${String(secs).padStart(2, "0")}`;
+  }, []);
+
+  // Calculate time from mouse position
+  // For live: maps position to time within DVR window
+  const getTimeFromPosition = useCallback((clientX: number): number => {
+    if (!trackRef.current) return 0;
+    const rect = trackRef.current.getBoundingClientRect();
+    const x = clientX - rect.left;
+    const percent = Math.min(1, Math.max(0, x / rect.width));
+
+    // Live with valid seekable window
+    if (isLive && Number.isFinite(seekableWindow) && seekableWindow > 0) {
+      return seekableStart + (percent * seekableWindow);
+    }
+
+    // VOD with finite duration
+    if (Number.isFinite(duration) && duration > 0) {
+      return percent * duration;
+    }
+
+    // Fallback: If we have liveEdge, use it even if not marked as live
+    // This handles cases where duration is Infinity but we have valid seekable data
+    if (Number.isFinite(liveEdge) && liveEdge > 0) {
+      const start = Number.isFinite(seekableStart) ? seekableStart : 0;
+      const window = liveEdge - start;
+      if (window > 0) {
+        return start + (percent * window);
+      }
+    }
+
+    // Last resort: use currentTime as a baseline
+    return percent * (currentTime || 1);
+  }, [duration, isLive, seekableStart, seekableWindow, liveEdge, currentTime]);
+
+  // Handle mouse move for hover preview
+  const handleMouseMove = useCallback((e: React.MouseEvent) => {
+    if (!trackRef.current || disabled) return;
+    const rect = trackRef.current.getBoundingClientRect();
+    const x = e.clientX - rect.left;
+    const percent = Math.min(1, Math.max(0, x / rect.width));
+    setHoverPosition(percent * 100);
+    setHoverTime(getTimeFromPosition(e.clientX));
+  }, [disabled, getTimeFromPosition]);
+
+  // Handle click to seek
+  const handleClick = useCallback((e: React.MouseEvent) => {
+    if (disabled) return;
+    if (!isLive && !Number.isFinite(duration)) return;
+    const time = getTimeFromPosition(e.clientX);
+    onSeek?.(time);
+    setDragTime(null);
+    dragTimeRef.current = null;
+  }, [disabled, duration, isLive, getTimeFromPosition, onSeek]);
+
+  // Handle drag start
+  const handleMouseDown = useCallback((e: React.MouseEvent) => {
+    if (disabled) return;
+    if (!isLive && !Number.isFinite(duration)) return;
+    e.preventDefault();
+    setIsDragging(true);
+
+    const handleDragMove = (moveEvent: MouseEvent) => {
+      const time = getTimeFromPosition(moveEvent.clientX);
+      if (commitOnRelease) {
+        setDragTime(time);
+        dragTimeRef.current = time;
+      } else {
+        onSeek?.(time);
+      }
+    };
+
+    const handleDragEnd = () => {
+      setIsDragging(false);
+      document.removeEventListener("mousemove", handleDragMove);
+      document.removeEventListener("mouseup", handleDragEnd);
+      const pending = dragTimeRef.current;
+      if (commitOnRelease && pending !== null) {
+        onSeek?.(pending);
+        setDragTime(null);
+        dragTimeRef.current = null;
+      }
+    };
+
+    document.addEventListener("mousemove", handleDragMove);
+    document.addEventListener("mouseup", handleDragEnd);
+
+    // Initial seek
+    const time = getTimeFromPosition(e.clientX);
+    if (commitOnRelease) {
+      setDragTime(time);
+      dragTimeRef.current = time;
+    } else {
+      onSeek?.(time);
+    }
+  }, [disabled, duration, isLive, getTimeFromPosition, onSeek, commitOnRelease]);
+
+  const showThumb = isHovering || isDragging;
+  const canShowTooltip = isLive ? seekableWindow > 0 : Number.isFinite(duration);
+
+  return (
+    <div
+      ref={trackRef}
+      className={cn(
+        "group relative w-full h-6 flex items-center cursor-pointer",
+        disabled && "opacity-50 cursor-not-allowed",
+        className
+      )}
+      onMouseEnter={() => !disabled && setIsHovering(true)}
+      onMouseLeave={() => { setIsHovering(false); setIsDragging(false); }}
+      onMouseMove={handleMouseMove}
+      onClick={handleClick}
+      onMouseDown={handleMouseDown}
+      role="slider"
+      aria-label="Seek"
+      aria-valuemin={isLive ? seekableStart : 0}
+      aria-valuemax={isLive ? effectiveLiveEdge : (duration || 100)}
+      aria-valuenow={displayTime}
+      aria-valuetext={isLive ? formatLiveTime(displayTime, effectiveLiveEdge) : formatTime(displayTime)}
+      tabIndex={disabled ? -1 : 0}
+    >
+      {/* Track background */}
+      <div className={cn(
+        "fw-seek-track",
+        isDragging && "fw-seek-track--active"
+      )}>
+        {/* Buffered segments - show actual buffered ranges */}
+        {bufferedSegments.map((segment, index) => (
+          <div
+            key={index}
+            className="fw-seek-buffered"
+            style={{
+              left: `${segment.startPercent}%`,
+              width: `${segment.endPercent - segment.startPercent}%`,
+            }}
+          />
+        ))}
+        {/* Playback progress */}
+        <div
+          className="fw-seek-progress"
+          style={{ width: `${progressPercent}%` }}
+        />
+      </div>
+
+      {/* Thumb */}
+      <div
+        className={cn(
+          "fw-seek-thumb",
+          showThumb ? "fw-seek-thumb--active" : "fw-seek-thumb--hidden"
+        )}
+        style={{ left: `${progressPercent}%` }}
+      />
+
+      {/* Hover time tooltip */}
+      {isHovering && !isDragging && canShowTooltip && (
+        <div
+          className="fw-seek-tooltip"
+          style={{ left: `${hoverPosition}%` }}
+        >
+          {isLive ? formatLiveTime(hoverTime, effectiveLiveEdge) : formatTime(hoverTime)}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default SeekBar;

package/src/components/SkipIndicator.tsx

@@ -0,0 +1,113 @@
+import React, { useEffect, useState } from "react";
+import { cn } from "@livepeer-frameworks/player-core";
+
+export type SkipDirection = "back" | "forward" | null;
+
+interface SkipIndicatorProps {
+  direction: SkipDirection;
+  seconds?: number;
+  className?: string;
+  onHide?: () => void;
+}
+
+/**
+ * Skip indicator overlay that appears when double-tapping to skip.
+ * Shows the skip direction and amount (e.g., "-10s" or "+10s") with a ripple effect.
+ */
+const SkipIndicator: React.FC<SkipIndicatorProps> = ({
+  direction,
+  seconds = 10,
+  className,
+  onHide,
+}) => {
+  const [isAnimating, setIsAnimating] = useState(false);
+
+  useEffect(() => {
+    if (direction) {
+      setIsAnimating(true);
+      const timer = setTimeout(() => {
+        setIsAnimating(false);
+        onHide?.();
+      }, 600);
+      return () => clearTimeout(timer);
+    }
+  }, [direction, onHide]);
+
+  if (!direction) return null;
+
+  const isBack = direction === "back";
+
+  return (
+    <div
+      className={cn(
+        "fw-skip-indicator absolute inset-0 z-30 pointer-events-none",
+        "flex items-center",
+        isBack ? "justify-start pl-8" : "justify-end pr-8",
+        className
+      )}
+    >
+      {/* Ripple background */}
+      <div
+        className={cn(
+          "absolute top-0 bottom-0 w-1/3",
+          isBack ? "left-0" : "right-0",
+          "bg-white/10",
+          isAnimating && "animate-pulse"
+        )}
+      />
+
+      {/* Skip content */}
+      <div
+        className={cn(
+          "relative flex flex-col items-center gap-1 text-white",
+          "transition-all duration-200",
+          isAnimating ? "opacity-100 scale-100" : "opacity-0 scale-75"
+        )}
+      >
+        {/* Icon */}
+        <div className="flex">
+          {isBack ? (
+            <>
+              <RewindIcon className="w-8 h-8" />
+              <RewindIcon className="w-8 h-8 -ml-4" />
+            </>
+          ) : (
+            <>
+              <FastForwardIcon className="w-8 h-8" />
+              <FastForwardIcon className="w-8 h-8 -ml-4" />
+            </>
+          )}
+        </div>
+
+        {/* Text */}
+        <span className="text-sm font-semibold tabular-nums">
+          {isBack ? `-${seconds}s` : `+${seconds}s`}
+        </span>
+      </div>
+    </div>
+  );
+};
+
+const RewindIcon: React.FC<{ className?: string }> = ({ className }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    className={className}
+    aria-hidden="true"
+  >
+    <path d="M11 18V6l-8.5 6 8.5 6zm.5-6l8.5 6V6l-8.5 6z" />
+  </svg>
+);
+
+const FastForwardIcon: React.FC<{ className?: string }> = ({ className }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    className={className}
+    aria-hidden="true"
+  >
+    <path d="M4 18l8.5-6L4 6v12zm9-12v12l8.5-6L13 6z" />
+  </svg>
+);
+
+export default SkipIndicator;

package/src/components/SpeedIndicator.tsx

@@ -0,0 +1,57 @@
+import React from "react";
+import { cn } from "@livepeer-frameworks/player-core";
+
+interface SpeedIndicatorProps {
+  isVisible: boolean;
+  speed: number;
+  className?: string;
+}
+
+/**
+ * Speed indicator overlay that appears when holding for fast-forward.
+ * Shows the current playback speed (e.g., "2x") in a pill overlay.
+ */
+const SpeedIndicator: React.FC<SpeedIndicatorProps> = ({
+  isVisible,
+  speed,
+  className,
+}) => {
+  return (
+    <div
+      className={cn(
+        "fw-speed-indicator absolute top-3 right-3 z-30 pointer-events-none",
+        "transition-opacity duration-150",
+        isVisible ? "opacity-100" : "opacity-0",
+        className
+      )}
+    >
+      <div
+        className={cn(
+          "bg-black/60 text-white px-2.5 py-1 rounded-md",
+          "text-xs font-semibold tabular-nums",
+          "flex items-center gap-2",
+          "border border-white/15",
+          "transform transition-transform duration-150",
+          isVisible ? "scale-100" : "scale-90"
+        )}
+      >
+        <FastForwardIcon className="w-4 h-4" />
+        <span>{speed}x</span>
+      </div>
+    </div>
+  );
+};
+
+// Simple fast-forward icon
+const FastForwardIcon: React.FC<{ className?: string }> = ({ className }) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    className={className}
+    aria-hidden="true"
+  >
+    <path d="M4 18l8.5-6L4 6v12zm9-12v12l8.5-6L13 6z" />
+  </svg>
+);
+
+export default SpeedIndicator;

package/src/components/StatsPanel.tsx

@@ -0,0 +1,150 @@
+import React from "react";
+import { cn, type ContentMetadata, type PlaybackQuality } from "@livepeer-frameworks/player-core";
+
+interface StreamStateInfo {
+  status?: string;
+  viewers?: number;
+  tracks?: Array<{
+    type: string;
+    codec: string;
+    width?: number;
+    height?: number;
+    bps?: number;
+    channels?: number;
+  }>;
+}
+
+interface StatsPanelProps {
+  isOpen: boolean;
+  onClose: () => void;
+  metadata?: ContentMetadata | null;
+  streamState?: StreamStateInfo | null;
+  quality?: PlaybackQuality | null;
+  videoElement?: HTMLVideoElement | null;
+  protocol?: string;
+  nodeId?: string;
+  geoDistance?: number;
+}
+
+/**
+ * "Stats for nerds" panel showing detailed playback information.
+ * Toggleable overlay with technical details about the stream.
+ */
+const StatsPanel: React.FC<StatsPanelProps> = ({
+  isOpen,
+  onClose,
+  metadata,
+  streamState,
+  quality,
+  videoElement,
+  protocol,
+  nodeId,
+  geoDistance,
+}) => {
+  if (!isOpen) return null;
+
+  // Video element stats
+  const video = videoElement;
+  const currentRes = video ? `${video.videoWidth}x${video.videoHeight}` : "—";
+  const buffered = video && video.buffered.length > 0
+    ? (video.buffered.end(video.buffered.length - 1) - video.currentTime).toFixed(1)
+    : "—";
+  const playbackRate = video?.playbackRate?.toFixed(2) ?? "1.00";
+
+  // Quality monitor stats
+  const qualityScore = quality?.score?.toFixed(0) ?? "—";
+  const bitrateKbps = quality?.bitrate
+    ? `${(quality.bitrate / 1000).toFixed(0)} kbps`
+    : "—";
+  const frameDropRate = quality?.frameDropRate?.toFixed(1) ?? "—";
+  const stallCount = quality?.stallCount ?? 0;
+  const latency = quality?.latency ? `${Math.round(quality.latency)} ms` : "—";
+
+  // Stream state stats
+  const viewers = streamState?.viewers ?? metadata?.viewers ?? "—";
+  const streamStatus = streamState?.status ?? metadata?.status ?? "—";
+
+  // Format track info from metadata
+  const formatTracks = () => {
+    if (!streamState?.tracks?.length) return "—";
+    return streamState.tracks.map(t => {
+      if (t.type === "video") {
+        return `${t.codec} ${t.width}x${t.height}@${t.bps ? Math.round(t.bps / 1000) + "kbps" : "?"}`;
+      }
+      return `${t.codec} ${t.channels}ch`;
+    }).join(", ");
+  };
+
+  const stats = [
+    { label: "Resolution", value: currentRes },
+    { label: "Buffer", value: `${buffered}s` },
+    { label: "Latency", value: latency },
+    { label: "Bitrate", value: bitrateKbps },
+    { label: "Quality Score", value: `${qualityScore}/100` },
+    { label: "Frame Drop Rate", value: `${frameDropRate}%` },
+    { label: "Stalls", value: String(stallCount) },
+    { label: "Playback Rate", value: `${playbackRate}x` },
+    { label: "Protocol", value: protocol ?? "—" },
+    { label: "Node", value: nodeId ?? "—" },
+    { label: "Geo Distance", value: geoDistance ? `${geoDistance.toFixed(0)} km` : "—" },
+    { label: "Viewers", value: String(viewers) },
+    { label: "Status", value: streamStatus },
+    { label: "Tracks", value: formatTracks() },
+  ];
+
+  // Add metadata fields if available
+  if (metadata?.title) {
+    stats.unshift({ label: "Title", value: metadata.title });
+  }
+  if (metadata?.durationSeconds) {
+    const mins = Math.floor(metadata.durationSeconds / 60);
+    const secs = metadata.durationSeconds % 60;
+    stats.push({ label: "Duration", value: `${mins}:${String(secs).padStart(2, "0")}` });
+  }
+  if (metadata?.recordingSizeBytes) {
+    const mb = (metadata.recordingSizeBytes / (1024 * 1024)).toFixed(1);
+    stats.push({ label: "Size", value: `${mb} MB` });
+  }
+
+  return (
+    <div
+      className={cn(
+        "fw-stats-panel absolute top-2 right-2 z-30",
+        "bg-black border border-white/10 rounded",
+        "text-white text-xs font-mono",
+        "max-w-[320px] max-h-[80%] overflow-auto",
+        "shadow-lg"
+      )}
+      style={{ backgroundColor: '#000000' }} // Inline fallback for opaque background
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between px-3 py-2 border-b border-white/10">
+        <span className="text-white/70 text-[10px] uppercase tracking-wider">
+          Stats Overlay
+        </span>
+        <button
+          type="button"
+          onClick={onClose}
+          className="text-white/50 hover:text-white transition-colors p-1 -mr-1"
+          aria-label="Close stats panel"
+        >
+          <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5">
+            <path d="M2 2l8 8M10 2l-8 8" />
+          </svg>
+        </button>
+      </div>
+
+      {/* Stats grid */}
+      <div className="px-3 py-2 space-y-1">
+        {stats.map(({ label, value }) => (
+          <div key={label} className="flex justify-between gap-4">
+            <span className="text-white/50 shrink-0">{label}</span>
+            <span className="text-white/90 truncate text-right">{value}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export default StatsPanel;