@lightbird/core 0.3.1 → 0.5.0

package/dist/index.cjs

@@ -611,6 +611,78 @@ _MKVPlayer._canPlayNatively = canPlayNatively;
 _MKVPlayer._workerFactory = null;
 var MKVPlayer = _MKVPlayer;
 
+// src/players/hls-player.ts
+var HLS_MIME_HINTS = ["application/x-mpegurl", "application/vnd.apple.mpegurl"];
+function isHlsUrl(url) {
+  if (typeof url !== "string" || url.length === 0) return false;
+  const lower = url.toLowerCase();
+  if (HLS_MIME_HINTS.some((hint) => lower.includes(hint))) return true;
+  return lower.split(/[?#]/)[0].endsWith(".m3u8");
+}
+var HLSPlayer = class {
+  constructor(url) {
+    this.hls = null;
+    this.url = url;
+    this.playerFile = { url, qualityLevels: [] };
+  }
+  async initialize(videoElement) {
+    const { default: HlsCtor } = await import('hls.js');
+    if (!HlsCtor.isSupported()) {
+      videoElement.src = this.url;
+      return this.playerFile;
+    }
+    const hls = new HlsCtor();
+    this.hls = hls;
+    hls.loadSource(this.url);
+    hls.attachMedia(videoElement);
+    return this.playerFile;
+  }
+  getAudioTracks() {
+    if (!this.hls) return [];
+    return this.hls.audioTracks.map((track) => ({
+      id: String(track.id),
+      name: track.name,
+      lang: track.lang || "unknown"
+    }));
+  }
+  getSubtitles() {
+    return [];
+  }
+  switchAudioTrack(trackId) {
+    if (this.hls) {
+      const id = Number(trackId);
+      if (!Number.isNaN(id)) this.hls.audioTrack = id;
+    }
+    return Promise.resolve();
+  }
+  switchSubtitle() {
+    return Promise.resolve();
+  }
+  /** Quality renditions — not on `VideoPlayer`; read directly by the quality hook. */
+  getQualityLevels() {
+    if (!this.hls) return [];
+    return this.hls.levels.map((level, index) => ({
+      index,
+      height: level.height,
+      bitrate: level.bitrate,
+      name: level.name || (level.height > 0 ? `${level.height}p` : `Level ${index + 1}`)
+    }));
+  }
+  /** Pins a quality level; `-1` restores automatic (ABR) selection. */
+  setQualityLevel(levelIndex) {
+    if (this.hls) this.hls.currentLevel = levelIndex;
+  }
+  destroy() {
+    if (this.hls) {
+      this.hls.destroy();
+      this.hls = null;
+    }
+  }
+  static isCompatible(url) {
+    return isHlsUrl(url);
+  }
+};
+
 // src/video-processor.ts
 var SimplePlayerAdapter = class {
   constructor(file, externalSubtitles = []) {
@@ -667,13 +739,21 @@ var MKVPlayerAdapter = class {
     return this.player.tracksReady;
   }
 };
-function createVideoPlayer(file, externalSubtitles = [], onProgress) {
-  if (MKVPlayer.isCompatible(file)) {
-    return new MKVPlayerAdapter(file, onProgress);
-  } else if (SimplePlayer.isCompatible(file)) {
-    return new SimplePlayerAdapter(file, externalSubtitles);
+function createVideoPlayer(source, externalSubtitles = [], onProgress) {
+  if (typeof source === "string") {
+    if (isHlsUrl(source)) {
+      return new HLSPlayer(source);
+    }
+    throw new Error(
+      `createVideoPlayer: unsupported URL "${source}" \u2014 only HLS (.m3u8) stream URLs are supported; pass a File for other formats.`
+    );
+  }
+  if (MKVPlayer.isCompatible(source)) {
+    return new MKVPlayerAdapter(source, onProgress);
+  } else if (SimplePlayer.isCompatible(source)) {
+    return new SimplePlayerAdapter(source, externalSubtitles);
   } else {
-    return new SimplePlayerAdapter(file, externalSubtitles);
+    return new SimplePlayerAdapter(source, externalSubtitles);
   }
 }
 
@@ -1332,6 +1412,61 @@ async function captureVideoThumbnail(videoEl, atSeconds = 5) {
     }
   });
 }
+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/utils/keyboard-shortcuts.ts
 var DEFAULT_SHORTCUTS = [
@@ -1466,6 +1601,7 @@ exports.DEFAULT_SHORTCUTS = DEFAULT_SHORTCUTS;
 exports.DEFAULT_TRACKERS = DEFAULT_TRACKERS;
 exports.DISCLAIMER_KEY = DISCLAIMER_KEY;
 exports.FLAG_MAGNET_LINK = FLAG_MAGNET_LINK;
+exports.HLSPlayer = HLSPlayer;
 exports.MKVPlayer = MKVPlayer;
 exports.ProgressEstimator = ProgressEstimator;
 exports.SimplePlayer = SimplePlayer;
@@ -1474,6 +1610,7 @@ exports.UniversalSubtitleManager = UniversalSubtitleManager;
 exports.VIDEO_EXTENSIONS = VIDEO_EXTENSIONS;
 exports.acceptDisclaimer = acceptDisclaimer;
 exports.applyOffsetToVtt = applyOffsetToVtt;
+exports.captureFrameAt = captureFrameAt;
 exports.captureVideoThumbnail = captureVideoThumbnail;
 exports.configureLightBird = configureLightBird;
 exports.createOffsetVttUrl = createOffsetVttUrl;
@@ -1487,6 +1624,7 @@ exports.getVideoFiles = getVideoFiles;
 exports.getWebTorrentClient = getWebTorrentClient;
 exports.hasAcceptedDisclaimer = hasAcceptedDisclaimer;
 exports.initFeatureFlags = initFeatureFlags;
+exports.isHlsUrl = isHlsUrl;
 exports.isInteractiveElement = isInteractiveElement;
 exports.isMagnetUri = isMagnetUri;
 exports.isVideoFile = isVideoFile;

package/dist/index.d.cts

@@ -83,6 +83,18 @@ interface SubtitleTrackMeta {
     format: string | null;
     language: string | null;
 }
+/** A single HLS quality rendition (e.g. 1080p, 720p). */
+interface QualityLevel {
+    index: number;
+    height: number;
+    bitrate: number;
+    name: string;
+}
+/** Result of initialising an HLS stream via `HLSPlayer`. */
+interface HLSPlayerFile {
+    url: string;
+    qualityLevels: QualityLevel[];
+}
 
 interface SimplePlayerFile {
     name: string;
@@ -168,7 +180,7 @@ declare class MKVPlayer {
     static isCompatible(file: File): boolean;
 }
 
-type ProcessedFile = SimplePlayerFile | MKVPlayerFile;
+type ProcessedFile = SimplePlayerFile | MKVPlayerFile | HLSPlayerFile;
 interface VideoPlayer {
     initialize(videoElement: HTMLVideoElement): Promise<ProcessedFile>;
     getAudioTracks(): AudioTrack[];
@@ -185,7 +197,28 @@ interface VideoPlayer {
      */
     tracksReady?: Promise<void>;
 }
-declare function createVideoPlayer(file: File, externalSubtitles?: File[], onProgress?: (progress: number) => void): VideoPlayer;
+declare function createVideoPlayer(source: File | string, externalSubtitles?: File[], onProgress?: (progress: number) => void): VideoPlayer;
+
+/** True for HLS playlist URLs — a `.m3u8` path or an HLS MIME hint. */
+declare function isHlsUrl(url: string): boolean;
+/** Plays HLS (`.m3u8`) streams via hls.js, falling back to native HLS (Safari). */
+declare class HLSPlayer implements VideoPlayer {
+    private readonly url;
+    private readonly playerFile;
+    private hls;
+    constructor(url: string);
+    initialize(videoElement: HTMLVideoElement): Promise<HLSPlayerFile>;
+    getAudioTracks(): AudioTrack[];
+    getSubtitles(): Subtitle[];
+    switchAudioTrack(trackId: string): Promise<void>;
+    switchSubtitle(): Promise<void>;
+    /** Quality renditions — not on `VideoPlayer`; read directly by the quality hook. */
+    getQualityLevels(): QualityLevel[];
+    /** Pins a quality level; `-1` restores automatic (ABR) selection. */
+    setQualityLevel(levelIndex: number): void;
+    destroy(): void;
+    static isCompatible(url: string): boolean;
+}
 
 declare class UniversalSubtitleManager {
     private records;
@@ -339,6 +372,21 @@ declare function validateFile(file: File): {
 declare function extractNativeMetadata(videoEl: HTMLVideoElement, file?: File): Partial<VideoMetadata>;
 
 declare function captureVideoThumbnail(videoEl: HTMLVideoElement, atSeconds?: number): Promise<string | null>;
+/**
+ * Capture a single video frame at a specific timestamp.
+ *
+ * Unlike {@link captureVideoThumbnail}, this does not save/restore
+ * `currentTime` — it is built for a dedicated, offscreen preview video so the
+ * main playback element is never disturbed. Powers seek-bar hover previews.
+ *
+ * @param videoEl - A video element (typically offscreen) to seek and capture.
+ * @param timeSeconds - Timestamp to capture, clamped to the video duration.
+ * @param width - Output thumbnail width in pixels.
+ * @param height - Output thumbnail height in pixels.
+ * @returns A JPEG data URL, or `null` if capture failed (no 2d context, a
+ *          tainted canvas, or a media error).
+ */
+declare function captureFrameAt(videoEl: HTMLVideoElement, timeSeconds: number, width?: number, height?: number): Promise<string | null>;
 
 type ShortcutAction = 'play-pause' | 'seek-forward-5' | 'seek-backward-5' | 'seek-forward-30' | 'seek-backward-30' | 'volume-up' | 'volume-down' | 'mute' | 'fullscreen' | 'next-item' | 'prev-item' | 'screenshot' | 'show-shortcuts' | 'next-chapter' | 'prev-chapter';
 interface ShortcutBinding {
@@ -393,4 +441,4 @@ declare class ProgressEstimator {
 declare function getFFmpeg(): Promise<FFmpeg>;
 declare function resetFFmpeg(): void;
 
-export { ASSRenderer, type AudioTrack, type AudioTrackMeta, CancellationError, type Chapter, DEFAULT_SHORTCUTS, DEFAULT_TRACKERS, DISCLAIMER_KEY, FLAG_MAGNET_LINK, type LightBirdConfig, MKVPlayer, type MKVPlayerFile, type MediaErrorType, type ParsedMediaError, type PlaylistItem, type ProcessedFile, ProgressEstimator, type ShortcutAction, type ShortcutBinding, SimplePlayer, type SimplePlayerFile, type Subtitle, SubtitleConverter, type SubtitleCue, type SubtitleTrackMeta, type TorrentStatus, UniversalSubtitleManager, VIDEO_EXTENSIONS, type VideoFilters, type VideoMetadata, type VideoPlayer, acceptDisclaimer, applyOffsetToVtt, captureVideoThumbnail, configureLightBird, createOffsetVttUrl, createVideoPlayer, destroyWebTorrentClient, exportPlaylist, extractNativeMetadata, formatShortcutKey, getFFmpeg, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };
+export { ASSRenderer, type AudioTrack, type AudioTrackMeta, CancellationError, type Chapter, DEFAULT_SHORTCUTS, DEFAULT_TRACKERS, DISCLAIMER_KEY, FLAG_MAGNET_LINK, HLSPlayer, type HLSPlayerFile, type LightBirdConfig, MKVPlayer, type MKVPlayerFile, type MediaErrorType, type ParsedMediaError, type PlaylistItem, type ProcessedFile, ProgressEstimator, type QualityLevel, type ShortcutAction, type ShortcutBinding, SimplePlayer, type SimplePlayerFile, type Subtitle, SubtitleConverter, type SubtitleCue, type SubtitleTrackMeta, type TorrentStatus, UniversalSubtitleManager, VIDEO_EXTENSIONS, type VideoFilters, type VideoMetadata, type VideoPlayer, acceptDisclaimer, applyOffsetToVtt, captureFrameAt, captureVideoThumbnail, configureLightBird, createOffsetVttUrl, createVideoPlayer, destroyWebTorrentClient, exportPlaylist, extractNativeMetadata, formatShortcutKey, getFFmpeg, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };

package/dist/index.d.ts

@@ -83,6 +83,18 @@ interface SubtitleTrackMeta {
     format: string | null;
     language: string | null;
 }
+/** A single HLS quality rendition (e.g. 1080p, 720p). */
+interface QualityLevel {
+    index: number;
+    height: number;
+    bitrate: number;
+    name: string;
+}
+/** Result of initialising an HLS stream via `HLSPlayer`. */
+interface HLSPlayerFile {
+    url: string;
+    qualityLevels: QualityLevel[];
+}
 
 interface SimplePlayerFile {
     name: string;
@@ -168,7 +180,7 @@ declare class MKVPlayer {
     static isCompatible(file: File): boolean;
 }
 
-type ProcessedFile = SimplePlayerFile | MKVPlayerFile;
+type ProcessedFile = SimplePlayerFile | MKVPlayerFile | HLSPlayerFile;
 interface VideoPlayer {
     initialize(videoElement: HTMLVideoElement): Promise<ProcessedFile>;
     getAudioTracks(): AudioTrack[];
@@ -185,7 +197,28 @@ interface VideoPlayer {
      */
     tracksReady?: Promise<void>;
 }
-declare function createVideoPlayer(file: File, externalSubtitles?: File[], onProgress?: (progress: number) => void): VideoPlayer;
+declare function createVideoPlayer(source: File | string, externalSubtitles?: File[], onProgress?: (progress: number) => void): VideoPlayer;
+
+/** True for HLS playlist URLs — a `.m3u8` path or an HLS MIME hint. */
+declare function isHlsUrl(url: string): boolean;
+/** Plays HLS (`.m3u8`) streams via hls.js, falling back to native HLS (Safari). */
+declare class HLSPlayer implements VideoPlayer {
+    private readonly url;
+    private readonly playerFile;
+    private hls;
+    constructor(url: string);
+    initialize(videoElement: HTMLVideoElement): Promise<HLSPlayerFile>;
+    getAudioTracks(): AudioTrack[];
+    getSubtitles(): Subtitle[];
+    switchAudioTrack(trackId: string): Promise<void>;
+    switchSubtitle(): Promise<void>;
+    /** Quality renditions — not on `VideoPlayer`; read directly by the quality hook. */
+    getQualityLevels(): QualityLevel[];
+    /** Pins a quality level; `-1` restores automatic (ABR) selection. */
+    setQualityLevel(levelIndex: number): void;
+    destroy(): void;
+    static isCompatible(url: string): boolean;
+}
 
 declare class UniversalSubtitleManager {
     private records;
@@ -339,6 +372,21 @@ declare function validateFile(file: File): {
 declare function extractNativeMetadata(videoEl: HTMLVideoElement, file?: File): Partial<VideoMetadata>;
 
 declare function captureVideoThumbnail(videoEl: HTMLVideoElement, atSeconds?: number): Promise<string | null>;
+/**
+ * Capture a single video frame at a specific timestamp.
+ *
+ * Unlike {@link captureVideoThumbnail}, this does not save/restore
+ * `currentTime` — it is built for a dedicated, offscreen preview video so the
+ * main playback element is never disturbed. Powers seek-bar hover previews.
+ *
+ * @param videoEl - A video element (typically offscreen) to seek and capture.
+ * @param timeSeconds - Timestamp to capture, clamped to the video duration.
+ * @param width - Output thumbnail width in pixels.
+ * @param height - Output thumbnail height in pixels.
+ * @returns A JPEG data URL, or `null` if capture failed (no 2d context, a
+ *          tainted canvas, or a media error).
+ */
+declare function captureFrameAt(videoEl: HTMLVideoElement, timeSeconds: number, width?: number, height?: number): Promise<string | null>;
 
 type ShortcutAction = 'play-pause' | 'seek-forward-5' | 'seek-backward-5' | 'seek-forward-30' | 'seek-backward-30' | 'volume-up' | 'volume-down' | 'mute' | 'fullscreen' | 'next-item' | 'prev-item' | 'screenshot' | 'show-shortcuts' | 'next-chapter' | 'prev-chapter';
 interface ShortcutBinding {
@@ -393,4 +441,4 @@ declare class ProgressEstimator {
 declare function getFFmpeg(): Promise<FFmpeg>;
 declare function resetFFmpeg(): void;
 
-export { ASSRenderer, type AudioTrack, type AudioTrackMeta, CancellationError, type Chapter, DEFAULT_SHORTCUTS, DEFAULT_TRACKERS, DISCLAIMER_KEY, FLAG_MAGNET_LINK, type LightBirdConfig, MKVPlayer, type MKVPlayerFile, type MediaErrorType, type ParsedMediaError, type PlaylistItem, type ProcessedFile, ProgressEstimator, type ShortcutAction, type ShortcutBinding, SimplePlayer, type SimplePlayerFile, type Subtitle, SubtitleConverter, type SubtitleCue, type SubtitleTrackMeta, type TorrentStatus, UniversalSubtitleManager, VIDEO_EXTENSIONS, type VideoFilters, type VideoMetadata, type VideoPlayer, acceptDisclaimer, applyOffsetToVtt, captureVideoThumbnail, configureLightBird, createOffsetVttUrl, createVideoPlayer, destroyWebTorrentClient, exportPlaylist, extractNativeMetadata, formatShortcutKey, getFFmpeg, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };
+export { ASSRenderer, type AudioTrack, type AudioTrackMeta, CancellationError, type Chapter, DEFAULT_SHORTCUTS, DEFAULT_TRACKERS, DISCLAIMER_KEY, FLAG_MAGNET_LINK, HLSPlayer, type HLSPlayerFile, type LightBirdConfig, MKVPlayer, type MKVPlayerFile, type MediaErrorType, type ParsedMediaError, type PlaylistItem, type ProcessedFile, ProgressEstimator, type QualityLevel, type ShortcutAction, type ShortcutBinding, SimplePlayer, type SimplePlayerFile, type Subtitle, SubtitleConverter, type SubtitleCue, type SubtitleTrackMeta, type TorrentStatus, UniversalSubtitleManager, VIDEO_EXTENSIONS, type VideoFilters, type VideoMetadata, type VideoPlayer, acceptDisclaimer, applyOffsetToVtt, captureFrameAt, captureVideoThumbnail, configureLightBird, createOffsetVttUrl, createVideoPlayer, destroyWebTorrentClient, exportPlaylist, extractNativeMetadata, formatShortcutKey, getFFmpeg, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };

package/dist/index.js

@@ -608,6 +608,78 @@ _MKVPlayer._canPlayNatively = canPlayNatively;
 _MKVPlayer._workerFactory = null;
 var MKVPlayer = _MKVPlayer;
 
+// src/players/hls-player.ts
+var HLS_MIME_HINTS = ["application/x-mpegurl", "application/vnd.apple.mpegurl"];
+function isHlsUrl(url) {
+  if (typeof url !== "string" || url.length === 0) return false;
+  const lower = url.toLowerCase();
+  if (HLS_MIME_HINTS.some((hint) => lower.includes(hint))) return true;
+  return lower.split(/[?#]/)[0].endsWith(".m3u8");
+}
+var HLSPlayer = class {
+  constructor(url) {
+    this.hls = null;
+    this.url = url;
+    this.playerFile = { url, qualityLevels: [] };
+  }
+  async initialize(videoElement) {
+    const { default: HlsCtor } = await import('hls.js');
+    if (!HlsCtor.isSupported()) {
+      videoElement.src = this.url;
+      return this.playerFile;
+    }
+    const hls = new HlsCtor();
+    this.hls = hls;
+    hls.loadSource(this.url);
+    hls.attachMedia(videoElement);
+    return this.playerFile;
+  }
+  getAudioTracks() {
+    if (!this.hls) return [];
+    return this.hls.audioTracks.map((track) => ({
+      id: String(track.id),
+      name: track.name,
+      lang: track.lang || "unknown"
+    }));
+  }
+  getSubtitles() {
+    return [];
+  }
+  switchAudioTrack(trackId) {
+    if (this.hls) {
+      const id = Number(trackId);
+      if (!Number.isNaN(id)) this.hls.audioTrack = id;
+    }
+    return Promise.resolve();
+  }
+  switchSubtitle() {
+    return Promise.resolve();
+  }
+  /** Quality renditions — not on `VideoPlayer`; read directly by the quality hook. */
+  getQualityLevels() {
+    if (!this.hls) return [];
+    return this.hls.levels.map((level, index) => ({
+      index,
+      height: level.height,
+      bitrate: level.bitrate,
+      name: level.name || (level.height > 0 ? `${level.height}p` : `Level ${index + 1}`)
+    }));
+  }
+  /** Pins a quality level; `-1` restores automatic (ABR) selection. */
+  setQualityLevel(levelIndex) {
+    if (this.hls) this.hls.currentLevel = levelIndex;
+  }
+  destroy() {
+    if (this.hls) {
+      this.hls.destroy();
+      this.hls = null;
+    }
+  }
+  static isCompatible(url) {
+    return isHlsUrl(url);
+  }
+};
+
 // src/video-processor.ts
 var SimplePlayerAdapter = class {
   constructor(file, externalSubtitles = []) {
@@ -664,13 +736,21 @@ var MKVPlayerAdapter = class {
     return this.player.tracksReady;
   }
 };
-function createVideoPlayer(file, externalSubtitles = [], onProgress) {
-  if (MKVPlayer.isCompatible(file)) {
-    return new MKVPlayerAdapter(file, onProgress);
-  } else if (SimplePlayer.isCompatible(file)) {
-    return new SimplePlayerAdapter(file, externalSubtitles);
+function createVideoPlayer(source, externalSubtitles = [], onProgress) {
+  if (typeof source === "string") {
+    if (isHlsUrl(source)) {
+      return new HLSPlayer(source);
+    }
+    throw new Error(
+      `createVideoPlayer: unsupported URL "${source}" \u2014 only HLS (.m3u8) stream URLs are supported; pass a File for other formats.`
+    );
+  }
+  if (MKVPlayer.isCompatible(source)) {
+    return new MKVPlayerAdapter(source, onProgress);
+  } else if (SimplePlayer.isCompatible(source)) {
+    return new SimplePlayerAdapter(source, externalSubtitles);
   } else {
-    return new SimplePlayerAdapter(file, externalSubtitles);
+    return new SimplePlayerAdapter(source, externalSubtitles);
   }
 }
 
@@ -1329,6 +1409,61 @@ async function captureVideoThumbnail(videoEl, atSeconds = 5) {
     }
   });
 }
+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/utils/keyboard-shortcuts.ts
 var DEFAULT_SHORTCUTS = [
@@ -1457,4 +1592,4 @@ function resetFFmpeg() {
   loading = null;
 }
 
-export { ASSRenderer, CancellationError, DEFAULT_SHORTCUTS, DEFAULT_TRACKERS, DISCLAIMER_KEY, FLAG_MAGNET_LINK, MKVPlayer, ProgressEstimator, SimplePlayer, SubtitleConverter, UniversalSubtitleManager, VIDEO_EXTENSIONS, acceptDisclaimer, applyOffsetToVtt, captureVideoThumbnail, configureLightBird, createOffsetVttUrl, createVideoPlayer, destroyWebTorrentClient, exportPlaylist, extractNativeMetadata, formatShortcutKey, getFFmpeg, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };
+export { ASSRenderer, CancellationError, DEFAULT_SHORTCUTS, DEFAULT_TRACKERS, DISCLAIMER_KEY, FLAG_MAGNET_LINK, HLSPlayer, MKVPlayer, ProgressEstimator, SimplePlayer, SubtitleConverter, UniversalSubtitleManager, VIDEO_EXTENSIONS, acceptDisclaimer, applyOffsetToVtt, captureFrameAt, captureVideoThumbnail, configureLightBird, createOffsetVttUrl, createVideoPlayer, destroyWebTorrentClient, exportPlaylist, extractNativeMetadata, formatShortcutKey, getFFmpeg, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };