@lightbird/core 0.4.0 → 0.6.0

package/dist/react/index.d.cts

@@ -284,4 +284,104 @@ interface UseMagnetReturn {
 }
 declare function useMagnet(): UseMagnetReturn;
 
-export { type ShortcutHandlers, type UseMagnetReturn, type UseMediaSessionOptions, type UseSubtitlesOptions, useChapters, useFullscreen, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSubtitles, useVideoFilters, useVideoInfo, useVideoPlayback };
+interface SeekPreviewState {
+    /** Data URL of the captured frame for the hovered position, or `null`. */
+    thumbnail: string | null;
+    /** Hovered timestamp (seconds) the preview corresponds to, or `null`. */
+    time: number | null;
+    /** Request a preview at a hovered timestamp. Debounced and cached. */
+    requestPreview: (timeSeconds: number) => void;
+    /** Dismiss the preview, e.g. when the pointer leaves the seek bar. */
+    clearPreview: () => void;
+}
+interface UseSeekPreviewOptions {
+    /** Debounce window in ms before a frame is captured. Default `120`. */
+    debounceMs?: number;
+    /** Captured thumbnail width in pixels. Default `160`. */
+    width?: number;
+    /** Captured thumbnail height in pixels. Default `90`. */
+    height?: number;
+}
+/**
+ * Generates thumbnail previews for seek-bar hover.
+ *
+ * Captures frames from a dedicated offscreen video element kept in sync with
+ * the main player's source, so scrubbing the preview never disturbs playback.
+ * Captures are debounced and cached per whole second.
+ */
+declare function useSeekPreview(videoRef: RefObject<HTMLVideoElement | null>, options?: UseSeekPreviewOptions): SeekPreviewState;
+
+interface ABLoopState {
+    /** Loop start point in seconds, or `null` when unset. */
+    pointA: number | null;
+    /** Loop end point in seconds, or `null` when unset. */
+    pointB: number | null;
+    /** True when both points are set and playback loops between them. */
+    isLooping: boolean;
+    /** Capture the current playback time as point A. */
+    setPointA: () => void;
+    /** Capture the current playback time as point B (requires A, must be after A). */
+    setPointB: () => void;
+    /** Clear both points and stop looping. */
+    clear: () => void;
+}
+/**
+ * A-B loop: repeat playback between two user-set points.
+ *
+ * `setPointA` captures the current time as the loop start; `setPointB`
+ * captures the loop end (accepted only once A is set and the playhead is past
+ * it). While both points are set, the playhead is kept within `[A, B]` and
+ * jumps back to A whenever it reaches B. Points reset when a new source loads.
+ */
+declare function useABLoop(videoRef: RefObject<HTMLVideoElement | null>): ABLoopState;
+
+interface TouchGestureHandlers {
+    /** Seek relative to the current time by a signed number of seconds. */
+    seekBy?: (seconds: number) => void;
+    /** Read the current volume as a 0..1 value. */
+    getVolume?: () => number;
+    /** Set the volume to a 0..1 value. */
+    setVolume?: (value: number) => void;
+    /** Read the current brightness as a 0..1 fraction. */
+    getBrightness?: () => number;
+    /** Set the brightness to a 0..1 fraction. */
+    setBrightness?: (value: number) => void;
+}
+type TouchGestureFeedback = {
+    type: "seek";
+    direction: "forward" | "backward";
+    seconds: number;
+} | {
+    type: "volume";
+    value: number;
+} | {
+    type: "brightness";
+    value: number;
+};
+interface UseTouchGesturesOptions {
+    /** Disable the gesture listeners entirely. Default `true` (enabled). */
+    enabled?: boolean;
+    /** Seconds to seek on a double-tap. Default `10`. */
+    seekSeconds?: number;
+    /** Time window in ms for a second tap to count as a double-tap. Default `300`. */
+    doubleTapMs?: number;
+    /** How long the feedback indicator stays visible, in ms. Default `700`. */
+    feedbackMs?: number;
+}
+interface TouchGesturesState {
+    /** The most recent gesture for a transient on-screen indicator, or `null`. */
+    feedback: TouchGestureFeedback | null;
+}
+/**
+ * Touch gesture controls for the player surface.
+ *
+ * - Double-tap the left/right half to seek backward/forward.
+ * - Vertical swipe on the right half to adjust volume.
+ * - Vertical swipe on the left half to adjust brightness.
+ *
+ * Returns transient `feedback` describing the latest gesture so a UI overlay
+ * can show what changed.
+ */
+declare function useTouchGestures(targetRef: RefObject<HTMLElement | null>, handlers: TouchGestureHandlers, options?: UseTouchGesturesOptions): TouchGesturesState;
+
+export { type ABLoopState, type SeekPreviewState, type ShortcutHandlers, type TouchGestureFeedback, type TouchGestureHandlers, type TouchGesturesState, type UseMagnetReturn, type UseMediaSessionOptions, type UseSeekPreviewOptions, type UseSubtitlesOptions, type UseTouchGesturesOptions, useABLoop, useChapters, useFullscreen, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSeekPreview, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };

package/dist/react/index.d.ts

@@ -284,4 +284,104 @@ interface UseMagnetReturn {
 }
 declare function useMagnet(): UseMagnetReturn;
 
-export { type ShortcutHandlers, type UseMagnetReturn, type UseMediaSessionOptions, type UseSubtitlesOptions, useChapters, useFullscreen, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSubtitles, useVideoFilters, useVideoInfo, useVideoPlayback };
+interface SeekPreviewState {
+    /** Data URL of the captured frame for the hovered position, or `null`. */
+    thumbnail: string | null;
+    /** Hovered timestamp (seconds) the preview corresponds to, or `null`. */
+    time: number | null;
+    /** Request a preview at a hovered timestamp. Debounced and cached. */
+    requestPreview: (timeSeconds: number) => void;
+    /** Dismiss the preview, e.g. when the pointer leaves the seek bar. */
+    clearPreview: () => void;
+}
+interface UseSeekPreviewOptions {
+    /** Debounce window in ms before a frame is captured. Default `120`. */
+    debounceMs?: number;
+    /** Captured thumbnail width in pixels. Default `160`. */
+    width?: number;
+    /** Captured thumbnail height in pixels. Default `90`. */
+    height?: number;
+}
+/**
+ * Generates thumbnail previews for seek-bar hover.
+ *
+ * Captures frames from a dedicated offscreen video element kept in sync with
+ * the main player's source, so scrubbing the preview never disturbs playback.
+ * Captures are debounced and cached per whole second.
+ */
+declare function useSeekPreview(videoRef: RefObject<HTMLVideoElement | null>, options?: UseSeekPreviewOptions): SeekPreviewState;
+
+interface ABLoopState {
+    /** Loop start point in seconds, or `null` when unset. */
+    pointA: number | null;
+    /** Loop end point in seconds, or `null` when unset. */
+    pointB: number | null;
+    /** True when both points are set and playback loops between them. */
+    isLooping: boolean;
+    /** Capture the current playback time as point A. */
+    setPointA: () => void;
+    /** Capture the current playback time as point B (requires A, must be after A). */
+    setPointB: () => void;
+    /** Clear both points and stop looping. */
+    clear: () => void;
+}
+/**
+ * A-B loop: repeat playback between two user-set points.
+ *
+ * `setPointA` captures the current time as the loop start; `setPointB`
+ * captures the loop end (accepted only once A is set and the playhead is past
+ * it). While both points are set, the playhead is kept within `[A, B]` and
+ * jumps back to A whenever it reaches B. Points reset when a new source loads.
+ */
+declare function useABLoop(videoRef: RefObject<HTMLVideoElement | null>): ABLoopState;
+
+interface TouchGestureHandlers {
+    /** Seek relative to the current time by a signed number of seconds. */
+    seekBy?: (seconds: number) => void;
+    /** Read the current volume as a 0..1 value. */
+    getVolume?: () => number;
+    /** Set the volume to a 0..1 value. */
+    setVolume?: (value: number) => void;
+    /** Read the current brightness as a 0..1 fraction. */
+    getBrightness?: () => number;
+    /** Set the brightness to a 0..1 fraction. */
+    setBrightness?: (value: number) => void;
+}
+type TouchGestureFeedback = {
+    type: "seek";
+    direction: "forward" | "backward";
+    seconds: number;
+} | {
+    type: "volume";
+    value: number;
+} | {
+    type: "brightness";
+    value: number;
+};
+interface UseTouchGesturesOptions {
+    /** Disable the gesture listeners entirely. Default `true` (enabled). */
+    enabled?: boolean;
+    /** Seconds to seek on a double-tap. Default `10`. */
+    seekSeconds?: number;
+    /** Time window in ms for a second tap to count as a double-tap. Default `300`. */
+    doubleTapMs?: number;
+    /** How long the feedback indicator stays visible, in ms. Default `700`. */
+    feedbackMs?: number;
+}
+interface TouchGesturesState {
+    /** The most recent gesture for a transient on-screen indicator, or `null`. */
+    feedback: TouchGestureFeedback | null;
+}
+/**
+ * Touch gesture controls for the player surface.
+ *
+ * - Double-tap the left/right half to seek backward/forward.
+ * - Vertical swipe on the right half to adjust volume.
+ * - Vertical swipe on the left half to adjust brightness.
+ *
+ * Returns transient `feedback` describing the latest gesture so a UI overlay
+ * can show what changed.
+ */
+declare function useTouchGestures(targetRef: RefObject<HTMLElement | null>, handlers: TouchGestureHandlers, options?: UseTouchGesturesOptions): TouchGesturesState;
+
+export { type ABLoopState, type SeekPreviewState, type ShortcutHandlers, type TouchGestureFeedback, type TouchGestureHandlers, type TouchGesturesState, type UseMagnetReturn, type UseMediaSessionOptions, type UseSeekPreviewOptions, type UseSubtitlesOptions, type UseTouchGesturesOptions, useABLoop, useChapters, useFullscreen, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSeekPreview, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };

package/dist/react/index.js

@@ -1141,4 +1141,314 @@ function useMagnet() {
   return { torrentStatus, addMagnet, destroyMagnet };
 }
 
-export { useChapters, useFullscreen, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSubtitles, useVideoFilters, useVideoInfo, useVideoPlayback };
+// src/utils/video-thumbnail.ts
+async function captureFrameAt(videoEl, timeSeconds, width = 160, height = 90) {
+  return new Promise((resolve) => {
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) {
+      resolve(null);
+      return;
+    }
+    let settled = false;
+    const cleanup = () => {
+      videoEl.removeEventListener("seeked", onSeeked);
+      videoEl.removeEventListener("error", onError);
+      videoEl.removeEventListener("loadedmetadata", onLoadedMetadata);
+    };
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+    const draw = () => {
+      try {
+        ctx.drawImage(videoEl, 0, 0, width, height);
+        finish(canvas.toDataURL("image/jpeg", 0.6));
+      } catch {
+        finish(null);
+      }
+    };
+    const seekTo = () => {
+      const duration = videoEl.duration || 0;
+      const target = duration > 0 ? Math.max(0, Math.min(timeSeconds, duration)) : Math.max(0, timeSeconds);
+      if (Math.abs(videoEl.currentTime - target) < 0.05) {
+        draw();
+        return;
+      }
+      try {
+        videoEl.currentTime = target;
+      } catch {
+        finish(null);
+      }
+    };
+    const onSeeked = () => draw();
+    const onError = () => finish(null);
+    const onLoadedMetadata = () => seekTo();
+    videoEl.addEventListener("seeked", onSeeked);
+    videoEl.addEventListener("error", onError);
+    if (videoEl.readyState >= 1) {
+      seekTo();
+    } else {
+      videoEl.addEventListener("loadedmetadata", onLoadedMetadata, { once: true });
+    }
+  });
+}
+
+// src/react/use-seek-preview.ts
+function useSeekPreview(videoRef, options = {}) {
+  const { debounceMs = 120, width = 160, height = 90 } = options;
+  const [thumbnail, setThumbnail] = useState(null);
+  const [time, setTime] = useState(null);
+  const offscreenRef = useRef(null);
+  const loadedSrcRef = useRef("");
+  const cacheRef = useRef(/* @__PURE__ */ new Map());
+  const timerRef = useRef(null);
+  const requestSeqRef = useRef(0);
+  const syncOffscreenSource = useCallback(() => {
+    const main = videoRef.current;
+    const src = main?.currentSrc || main?.src || "";
+    if (!src) return null;
+    if (!offscreenRef.current) {
+      const v = document.createElement("video");
+      v.muted = true;
+      v.preload = "metadata";
+      v.crossOrigin = "anonymous";
+      v.setAttribute("playsinline", "");
+      offscreenRef.current = v;
+    }
+    const offscreen = offscreenRef.current;
+    if (loadedSrcRef.current !== src) {
+      loadedSrcRef.current = src;
+      cacheRef.current.clear();
+      offscreen.src = src;
+    }
+    return offscreen;
+  }, [videoRef]);
+  const clearPreview = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    requestSeqRef.current += 1;
+    setThumbnail(null);
+    setTime(null);
+  }, []);
+  const requestPreview = useCallback(
+    (timeSeconds) => {
+      const main = videoRef.current;
+      if (!main) return;
+      const duration = main.duration;
+      const hasDuration = !!duration && !Number.isNaN(duration);
+      const clamped = hasDuration ? Math.max(0, Math.min(timeSeconds, duration)) : Math.max(0, timeSeconds);
+      setTime(clamped);
+      if (!hasDuration) return;
+      const seq = ++requestSeqRef.current;
+      const bucket = Math.round(clamped);
+      const cached = cacheRef.current.get(bucket);
+      if (cached) {
+        setThumbnail(cached);
+        return;
+      }
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        const offscreen = syncOffscreenSource();
+        if (!offscreen) return;
+        captureFrameAt(offscreen, bucket, width, height).then((dataUrl) => {
+          if (seq !== requestSeqRef.current) return;
+          if (dataUrl) {
+            cacheRef.current.set(bucket, dataUrl);
+            setThumbnail(dataUrl);
+          }
+        });
+      }, debounceMs);
+    },
+    [videoRef, syncOffscreenSource, debounceMs, width, height]
+  );
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      const offscreen = offscreenRef.current;
+      if (offscreen) offscreen.removeAttribute("src");
+    };
+  }, []);
+  return { thumbnail, time, requestPreview, clearPreview };
+}
+function useABLoop(videoRef) {
+  const [pointA, setA] = useState(null);
+  const [pointB, setB] = useState(null);
+  const setPointA = useCallback(() => {
+    const el = videoRef.current;
+    if (!el) return;
+    const t = el.currentTime;
+    setA(t);
+    setB((b) => b !== null && b <= t ? null : b);
+  }, [videoRef]);
+  const setPointB = useCallback(() => {
+    const el = videoRef.current;
+    if (!el || pointA === null) return;
+    const t = el.currentTime;
+    if (t <= pointA) return;
+    setB(t);
+  }, [videoRef, pointA]);
+  const clear = useCallback(() => {
+    setA(null);
+    setB(null);
+  }, []);
+  useEffect(() => {
+    const el = videoRef.current;
+    if (!el || pointA === null || pointB === null) return;
+    const onTimeUpdate = () => {
+      if (el.currentTime >= pointB || el.currentTime < pointA) {
+        el.currentTime = pointA;
+      }
+    };
+    el.addEventListener("timeupdate", onTimeUpdate);
+    return () => el.removeEventListener("timeupdate", onTimeUpdate);
+  }, [videoRef, pointA, pointB]);
+  useEffect(() => {
+    const el = videoRef.current;
+    if (!el) return;
+    const onReset = () => clear();
+    el.addEventListener("loadstart", onReset);
+    el.addEventListener("emptied", onReset);
+    return () => {
+      el.removeEventListener("loadstart", onReset);
+      el.removeEventListener("emptied", onReset);
+    };
+  }, [videoRef, clear]);
+  return {
+    pointA,
+    pointB,
+    isLooping: pointA !== null && pointB !== null,
+    setPointA,
+    setPointB,
+    clear
+  };
+}
+var SWIPE_THRESHOLD = 10;
+var DOUBLE_TAP_DISTANCE = 40;
+function useTouchGestures(targetRef, handlers, options = {}) {
+  const { enabled = true, seekSeconds = 10, doubleTapMs = 300, feedbackMs = 700 } = options;
+  const [feedback, setFeedback] = useState(null);
+  const handlersRef = useRef(handlers);
+  useEffect(() => {
+    handlersRef.current = handlers;
+  });
+  const startRef = useRef(null);
+  const phaseRef = useRef("idle");
+  const swipeBaseRef = useRef(0);
+  const lastTapRef = useRef(null);
+  const feedbackTimerRef = useRef(null);
+  const showFeedback = useCallback(
+    (fb) => {
+      setFeedback(fb);
+      if (feedbackTimerRef.current) clearTimeout(feedbackTimerRef.current);
+      feedbackTimerRef.current = setTimeout(() => setFeedback(null), feedbackMs);
+    },
+    [feedbackMs]
+  );
+  useEffect(() => {
+    const el = targetRef.current;
+    if (!el || !enabled) return;
+    const onTouchStart = (e) => {
+      if (e.touches.length !== 1) {
+        startRef.current = null;
+        phaseRef.current = "ignore";
+        return;
+      }
+      const t = e.touches[0];
+      const rect = el.getBoundingClientRect();
+      const relX = t.clientX - rect.left;
+      startRef.current = {
+        x: t.clientX,
+        y: t.clientY,
+        zone: relX < rect.width / 2 ? "left" : "right",
+        height: rect.height || 1
+      };
+      phaseRef.current = "pending";
+    };
+    const onTouchMove = (e) => {
+      const start = startRef.current;
+      if (!start || phaseRef.current === "ignore" || phaseRef.current === "idle") return;
+      const t = e.touches[0];
+      if (!t) return;
+      const dx = t.clientX - start.x;
+      const dy = t.clientY - start.y;
+      if (phaseRef.current === "pending") {
+        if (Math.hypot(dx, dy) < SWIPE_THRESHOLD) return;
+        if (Math.abs(dy) > Math.abs(dx)) {
+          phaseRef.current = "swipe";
+          const h = handlersRef.current;
+          swipeBaseRef.current = start.zone === "left" ? h.getBrightness?.() ?? 1 : h.getVolume?.() ?? 1;
+        } else {
+          phaseRef.current = "ignore";
+          return;
+        }
+      }
+      if (phaseRef.current === "swipe") {
+        if (e.cancelable) e.preventDefault();
+        const fraction = -dy / start.height;
+        const next = Math.max(0, Math.min(1, swipeBaseRef.current + fraction));
+        const h = handlersRef.current;
+        if (start.zone === "left") {
+          h.setBrightness?.(next);
+          showFeedback({ type: "brightness", value: next });
+        } else {
+          h.setVolume?.(next);
+          showFeedback({ type: "volume", value: next });
+        }
+      }
+    };
+    const onTouchEnd = (e) => {
+      const start = startRef.current;
+      const phase = phaseRef.current;
+      startRef.current = null;
+      phaseRef.current = "idle";
+      if (!start || phase === "ignore") return;
+      if (phase === "swipe") {
+        lastTapRef.current = null;
+        return;
+      }
+      const point = e.changedTouches[0];
+      const px = point ? point.clientX : start.x;
+      const py = point ? point.clientY : start.y;
+      const now = Date.now();
+      const last = lastTapRef.current;
+      if (last && last.zone === start.zone && now - last.time < doubleTapMs && Math.hypot(px - last.x, py - last.y) < DOUBLE_TAP_DISTANCE) {
+        lastTapRef.current = null;
+        if (e.cancelable) e.preventDefault();
+        const h = handlersRef.current;
+        if (start.zone === "left") {
+          h.seekBy?.(-seekSeconds);
+          showFeedback({ type: "seek", direction: "backward", seconds: seekSeconds });
+        } else {
+          h.seekBy?.(seekSeconds);
+          showFeedback({ type: "seek", direction: "forward", seconds: seekSeconds });
+        }
+      } else {
+        lastTapRef.current = { x: px, y: py, time: now, zone: start.zone };
+      }
+    };
+    el.addEventListener("touchstart", onTouchStart, { passive: true });
+    el.addEventListener("touchmove", onTouchMove, { passive: false });
+    el.addEventListener("touchend", onTouchEnd, { passive: false });
+    return () => {
+      el.removeEventListener("touchstart", onTouchStart);
+      el.removeEventListener("touchmove", onTouchMove);
+      el.removeEventListener("touchend", onTouchEnd);
+    };
+  }, [targetRef, enabled, seekSeconds, doubleTapMs, showFeedback]);
+  useEffect(() => {
+    return () => {
+      if (feedbackTimerRef.current) clearTimeout(feedbackTimerRef.current);
+    };
+  }, []);
+  return { feedback };
+}
+
+export { useABLoop, useChapters, useFullscreen, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSeekPreview, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightbird/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Client-side video player engine. Plays MKV, MP4, WebM with full subtitle, audio track, and chapter support. No server required.",
   "license": "MIT",
   "author": "Punyam Singh",