@uploadbox/video 0.4.0

package/src/react/use-video-player.ts

@@ -0,0 +1,444 @@
+"use client";
+
+import { useRef, useState, useEffect, useCallback } from "react";
+import type { RefObject } from "react";
+
+/** A single HLS quality level. */
+export interface QualityLevel {
+  index: number;
+  width: number;
+  height: number;
+  bitrate: number;
+  label: string;
+}
+
+/** Sprite position for scrub preview. */
+export interface SpritePosition {
+  url: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Options for the useVideoPlayer hook. */
+export interface UseVideoPlayerOptions {
+  /** Auto-play the video when ready. @default false */
+  autoPlay?: boolean;
+  /** Initial volume (0–1). @default 1 */
+  initialVolume?: number;
+  /** URL to the WebVTT sprite sheet file. */
+  spriteVttUrl?: string;
+}
+
+/** Return value of the useVideoPlayer hook. */
+export interface VideoPlayerState {
+  /** Ref to attach to the <video> element. */
+  videoRef: RefObject<HTMLVideoElement | null>;
+  /** Whether the video is currently playing. */
+  isPlaying: boolean;
+  /** Current playback position in seconds. */
+  currentTime: number;
+  /** Total duration in seconds. */
+  duration: number;
+  /** Current volume (0–1). */
+  volume: number;
+  /** Whether audio is muted. */
+  isMuted: boolean;
+  /** Current playback rate. */
+  playbackRate: number;
+  /** Available quality levels. */
+  qualities: QualityLevel[];
+  /** Index of the current quality level (-1 for auto). */
+  currentQuality: number;
+  /** Whether adaptive quality selection is active. */
+  isAutoQuality: boolean;
+  /** Whether fullscreen is active. */
+  isFullscreen: boolean;
+  /** Whether the video is buffering. */
+  isBuffering: boolean;
+  /** Start playback. */
+  play: () => void;
+  /** Pause playback. */
+  pause: () => void;
+  /** Toggle play/pause. */
+  toggle: () => void;
+  /** Seek to a position in seconds. */
+  seek: (time: number) => void;
+  /** Set volume (0–1). */
+  setVolume: (vol: number) => void;
+  /** Toggle mute/unmute. */
+  toggleMute: () => void;
+  /** Set playback rate. */
+  setPlaybackRate: (rate: number) => void;
+  /** Set quality level by index. Pass -1 for auto. */
+  setQuality: (index: number) => void;
+  /** Enter fullscreen. */
+  enterFullscreen: () => void;
+  /** Exit fullscreen. */
+  exitFullscreen: () => void;
+  /** Toggle fullscreen. */
+  toggleFullscreen: () => void;
+  /** Get sprite position for a given time (for scrub preview). */
+  getSpriteForTime: (time: number) => SpritePosition | null;
+}
+
+interface VttCue {
+  startTime: number;
+  endTime: number;
+  url: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Headless React hook for HLS video playback.
+ *
+ * Provides playback controls, quality switching, fullscreen, and sprite preview
+ * without any UI — you build your own player controls.
+ *
+ * Uses `hls.js` for adaptive streaming with a fallback to native `<video>` HLS
+ * support (Safari).
+ *
+ * @param src - URL to the HLS master playlist (.m3u8) or a regular video file.
+ * @param options - Configuration options.
+ *
+ * @example
+ * ```tsx
+ * import { useVideoPlayer } from "@uploadbox/video/react";
+ *
+ * function Player({ url }: { url: string }) {
+ *   const player = useVideoPlayer(url);
+ *
+ *   return (
+ *     <div>
+ *       <video ref={player.videoRef} />
+ *       <button onClick={player.toggle}>
+ *         {player.isPlaying ? "Pause" : "Play"}
+ *       </button>
+ *       <span>{player.currentTime} / {player.duration}</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useVideoPlayer(
+  src: string,
+  options: UseVideoPlayerOptions = {}
+): VideoPlayerState {
+  const { autoPlay = false, initialVolume = 1, spriteVttUrl } = options;
+
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  const hlsRef = useRef<any>(null);
+
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [volume, setVolumeState] = useState(initialVolume);
+  const [isMuted, setIsMuted] = useState(false);
+  const [playbackRate, setPlaybackRateState] = useState(1);
+  const [qualities, setQualities] = useState<QualityLevel[]>([]);
+  const [currentQuality, setCurrentQualityState] = useState(-1);
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const [isBuffering, setIsBuffering] = useState(false);
+  const [spriteCues, setSpriteCues] = useState<VttCue[]>([]);
+
+  // Parse sprite VTT
+  useEffect(() => {
+    if (!spriteVttUrl) return;
+
+    fetch(spriteVttUrl)
+      .then((res) => res.text())
+      .then((text) => {
+        const cues = parseVtt(text, spriteVttUrl);
+        setSpriteCues(cues);
+      })
+      .catch(() => {});
+  }, [spriteVttUrl]);
+
+  // Setup HLS or native playback
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !src) return;
+
+    let hls: any = null;
+
+    async function setup() {
+      const isHls = src.endsWith(".m3u8");
+
+      if (isHls && !video!.canPlayType("application/vnd.apple.mpegurl")) {
+        // Use hls.js
+        try {
+          const HlsModule = await (Function('return import("hls.js")')() as Promise<any>);
+          const Hls = HlsModule.default ?? HlsModule;
+
+          if (!Hls.isSupported()) {
+            console.warn("[uploadbox/video] HLS.js is not supported in this browser");
+            video!.src = src;
+            return;
+          }
+
+          hls = new Hls({ enableWorker: true });
+          hlsRef.current = hls;
+
+          hls.loadSource(src);
+          hls.attachMedia(video!);
+
+          hls.on(Hls.Events.MANIFEST_PARSED, () => {
+            const levels = hls.levels.map((level: any, index: number) => ({
+              index,
+              width: level.width,
+              height: level.height,
+              bitrate: level.bitrate,
+              label: `${level.height}p`,
+            }));
+            setQualities(levels);
+
+            if (autoPlay) video!.play().catch(() => {});
+          });
+
+          hls.on(Hls.Events.LEVEL_SWITCHED, (_: any, data: any) => {
+            setCurrentQualityState(data.level);
+          });
+        } catch {
+          // hls.js not available, try native
+          video!.src = src;
+        }
+      } else {
+        // Native HLS (Safari) or regular video
+        video!.src = src;
+        if (autoPlay) video!.play().catch(() => {});
+      }
+    }
+
+    setup();
+
+    return () => {
+      if (hls) {
+        hls.destroy();
+        hlsRef.current = null;
+      }
+    };
+  }, [src, autoPlay]);
+
+  // Video event listeners
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video) return;
+
+    const onPlay = () => setIsPlaying(true);
+    const onPause = () => setIsPlaying(false);
+    const onTimeUpdate = () => setCurrentTime(video.currentTime);
+    const onDurationChange = () => setDuration(video.duration || 0);
+    const onVolumeChange = () => {
+      setVolumeState(video.volume);
+      setIsMuted(video.muted);
+    };
+    const onWaiting = () => setIsBuffering(true);
+    const onPlaying = () => setIsBuffering(false);
+    const onCanPlay = () => setIsBuffering(false);
+
+    video.addEventListener("play", onPlay);
+    video.addEventListener("pause", onPause);
+    video.addEventListener("timeupdate", onTimeUpdate);
+    video.addEventListener("durationchange", onDurationChange);
+    video.addEventListener("volumechange", onVolumeChange);
+    video.addEventListener("waiting", onWaiting);
+    video.addEventListener("playing", onPlaying);
+    video.addEventListener("canplay", onCanPlay);
+
+    // Set initial volume
+    video.volume = initialVolume;
+
+    return () => {
+      video.removeEventListener("play", onPlay);
+      video.removeEventListener("pause", onPause);
+      video.removeEventListener("timeupdate", onTimeUpdate);
+      video.removeEventListener("durationchange", onDurationChange);
+      video.removeEventListener("volumechange", onVolumeChange);
+      video.removeEventListener("waiting", onWaiting);
+      video.removeEventListener("playing", onPlaying);
+      video.removeEventListener("canplay", onCanPlay);
+    };
+  }, [initialVolume]);
+
+  // Fullscreen change listener
+  useEffect(() => {
+    const onFullscreenChange = () => {
+      setIsFullscreen(!!document.fullscreenElement);
+    };
+    document.addEventListener("fullscreenchange", onFullscreenChange);
+    return () => document.removeEventListener("fullscreenchange", onFullscreenChange);
+  }, []);
+
+  const play = useCallback(() => {
+    videoRef.current?.play().catch(() => {});
+  }, []);
+
+  const pause = useCallback(() => {
+    videoRef.current?.pause();
+  }, []);
+
+  const toggle = useCallback(() => {
+    const video = videoRef.current;
+    if (!video) return;
+    if (video.paused) video.play().catch(() => {});
+    else video.pause();
+  }, []);
+
+  const seek = useCallback((time: number) => {
+    const video = videoRef.current;
+    if (video) video.currentTime = time;
+  }, []);
+
+  const setVolume = useCallback((vol: number) => {
+    const video = videoRef.current;
+    if (video) {
+      video.volume = Math.max(0, Math.min(1, vol));
+      if (vol > 0) video.muted = false;
+    }
+  }, []);
+
+  const toggleMute = useCallback(() => {
+    const video = videoRef.current;
+    if (video) video.muted = !video.muted;
+  }, []);
+
+  const setPlaybackRate = useCallback((rate: number) => {
+    const video = videoRef.current;
+    if (video) {
+      video.playbackRate = rate;
+      setPlaybackRateState(rate);
+    }
+  }, []);
+
+  const setQuality = useCallback((index: number) => {
+    const hls = hlsRef.current;
+    if (hls) {
+      hls.currentLevel = index; // -1 = auto
+      setCurrentQualityState(index);
+    }
+  }, []);
+
+  const enterFullscreen = useCallback(() => {
+    const video = videoRef.current;
+    const container = video?.parentElement;
+    if (container?.requestFullscreen) {
+      container.requestFullscreen().catch(() => {});
+    }
+  }, []);
+
+  const exitFullscreen = useCallback(() => {
+    if (document.fullscreenElement) {
+      document.exitFullscreen().catch(() => {});
+    }
+  }, []);
+
+  const toggleFullscreen = useCallback(() => {
+    if (document.fullscreenElement) exitFullscreen();
+    else enterFullscreen();
+  }, [enterFullscreen, exitFullscreen]);
+
+  const getSpriteForTime = useCallback(
+    (time: number): SpritePosition | null => {
+      const cue = spriteCues.find((c) => time >= c.startTime && time < c.endTime);
+      if (!cue) return null;
+      return {
+        url: cue.url,
+        x: cue.x,
+        y: cue.y,
+        width: cue.width,
+        height: cue.height,
+      };
+    },
+    [spriteCues]
+  );
+
+  return {
+    videoRef,
+    isPlaying,
+    currentTime,
+    duration,
+    volume,
+    isMuted,
+    playbackRate,
+    qualities,
+    currentQuality,
+    isAutoQuality: currentQuality === -1,
+    isFullscreen,
+    isBuffering,
+    play,
+    pause,
+    toggle,
+    seek,
+    setVolume,
+    toggleMute,
+    setPlaybackRate,
+    setQuality,
+    enterFullscreen,
+    exitFullscreen,
+    toggleFullscreen,
+    getSpriteForTime,
+  };
+}
+
+/** Parse a WebVTT sprite sheet file. */
+function parseVtt(text: string, baseUrl: string): VttCue[] {
+  const cues: VttCue[] = [];
+  const lines = text.split("\n");
+  const baseDir = baseUrl.substring(0, baseUrl.lastIndexOf("/") + 1);
+
+  let i = 0;
+  // Skip header
+  while (i < lines.length && !lines[i]!.includes("-->")) i++;
+
+  while (i < lines.length) {
+    const line = lines[i]!.trim();
+
+    if (line.includes("-->")) {
+      const [startStr, endStr] = line.split("-->").map((s) => s.trim());
+      const startTime = parseVttTimestamp(startStr!);
+      const endTime = parseVttTimestamp(endStr!);
+
+      i++;
+      const dataLine = lines[i]?.trim() ?? "";
+
+      // Parse: sprite-sheet.jpg#xywh=0,0,160,90
+      const hashIndex = dataLine.indexOf("#xywh=");
+      if (hashIndex !== -1) {
+        const file = dataLine.substring(0, hashIndex);
+        const coords = dataLine.substring(hashIndex + 6).split(",").map(Number);
+
+        if (coords.length === 4) {
+          cues.push({
+            startTime,
+            endTime,
+            url: file.startsWith("http") ? file : `${baseDir}${file}`,
+            x: coords[0]!,
+            y: coords[1]!,
+            width: coords[2]!,
+            height: coords[3]!,
+          });
+        }
+      }
+    }
+    i++;
+  }
+
+  return cues;
+}
+
+function parseVttTimestamp(ts: string): number {
+  const parts = ts.split(":");
+  if (parts.length === 3) {
+    const [h, m, s] = parts;
+    return parseInt(h!) * 3600 + parseInt(m!) * 60 + parseFloat(s!);
+  }
+  if (parts.length === 2) {
+    const [m, s] = parts;
+    return parseInt(m!) * 60 + parseFloat(s!);
+  }
+  return parseFloat(ts);
+}

package/src/types.ts

@@ -0,0 +1,130 @@
+/** Extracted metadata from a video file. */
+export interface VideoMetadata {
+  /** Video width in pixels. */
+  width: number;
+  /** Video height in pixels. */
+  height: number;
+  /** Duration in seconds. */
+  durationSeconds: number;
+  /** Video codec (e.g. "h264", "vp9"). */
+  codec: string;
+  /** Frame rate (e.g. 30, 60). */
+  frameRate: number;
+  /** Video bitrate in bits per second. */
+  bitrate: number;
+  /** Audio stream information, if present. */
+  audio?: {
+    codec: string;
+    sampleRate: number;
+    channels: number;
+    bitrate: number;
+  };
+}
+
+/** Status of a transcoding job. */
+export type TranscodingStatus = "pending" | "processing" | "completed" | "failed";
+
+/** A quality preset for HLS adaptive bitrate streaming. */
+export interface QualityPreset {
+  /** Human-readable label (e.g. "720p"). */
+  label: string;
+  /** Output width in pixels. */
+  width: number;
+  /** Output height in pixels. */
+  height: number;
+  /** Target video bitrate in bits per second. */
+  videoBitrate: number;
+  /** Target audio bitrate in bits per second. */
+  audioBitrate: number;
+  /** Maximum frame rate. Source frame rate is used if lower. */
+  maxFrameRate: number;
+}
+
+/** Built-in quality presets for HLS transcoding. */
+export const QUALITY_PRESETS: Record<string, QualityPreset> = {
+  "360p": {
+    label: "360p",
+    width: 640,
+    height: 360,
+    videoBitrate: 600_000,
+    audioBitrate: 64_000,
+    maxFrameRate: 30,
+  },
+  "480p": {
+    label: "480p",
+    width: 854,
+    height: 480,
+    videoBitrate: 1_500_000,
+    audioBitrate: 128_000,
+    maxFrameRate: 30,
+  },
+  "720p": {
+    label: "720p",
+    width: 1280,
+    height: 720,
+    videoBitrate: 3_000_000,
+    audioBitrate: 128_000,
+    maxFrameRate: 60,
+  },
+  "1080p": {
+    label: "1080p",
+    width: 1920,
+    height: 1080,
+    videoBitrate: 5_000_000,
+    audioBitrate: 192_000,
+    maxFrameRate: 60,
+  },
+};
+
+/** State of a transcoding job. */
+export interface TranscodingJob {
+  /** Unique identifier for this job. */
+  jobId: string;
+  /** Current status. */
+  status: TranscodingStatus;
+  /** Progress percentage (0–100). */
+  progress: number;
+  /** S3 keys for generated outputs (playlists, segments, thumbnails). */
+  outputKeys: string[];
+  /** Error message if status is "failed". */
+  error?: string;
+}
+
+/** Options controlling the transcoding output. */
+export interface TranscodingOptions {
+  /** Quality presets to generate. Defaults to all QUALITY_PRESETS. */
+  qualities?: QualityPreset[];
+  /** HLS segment duration in seconds. @default 6 */
+  segmentDuration?: number;
+  /** Whether to generate a poster thumbnail. @default true */
+  generateThumbnail?: boolean;
+  /** Whether to generate a sprite sheet with WebVTT. @default true */
+  generateSpriteSheet?: boolean;
+  /** S3 key prefix for output files. */
+  s3OutputPrefix: string;
+}
+
+/** Progress callback payload. */
+export interface TranscodingProgress {
+  /** Job identifier. */
+  jobId: string;
+  /** Overall progress percentage (0–100). */
+  percent: number;
+  /** Quality preset currently being transcoded. */
+  currentQuality?: string;
+  /** Human-readable status message. */
+  message?: string;
+}
+
+/** Callback invoked during transcoding to report progress. */
+export type TranscodingProgressCallback = (progress: TranscodingProgress) => void;
+
+/** CDN cache header presets for HLS content. */
+export const CDN_CACHE_HEADERS = {
+  /** HLS segments (.ts): immutable, cache for 1 year. */
+  segment: "public, max-age=31536000, immutable",
+  /** HLS playlists (.m3u8): short TTL for live-like updates. */
+  playlist: "public, max-age=60",
+  /** Thumbnails and sprite sheets: cache for 1 day. */
+  thumbnail: "public, max-age=86400",
+} as const;