@lightbird/core 0.3.1 → 0.4.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);
   }
 }
 
@@ -1466,6 +1546,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;
@@ -1487,6 +1568,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;
@@ -393,4 +426,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, 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;
@@ -393,4 +426,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, 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);
   }
 }
 
@@ -1457,4 +1537,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, 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/react/index.d.cts

@@ -95,6 +95,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[];
+}
 
 declare function useVideoFilters(videoRef: RefObject<HTMLVideoElement | null>): {
     filters: VideoFilters;
@@ -236,7 +248,7 @@ interface MKVPlayerFile {
     activeSubtitleTrack: string;
 }
 
-type ProcessedFile = SimplePlayerFile | MKVPlayerFile;
+type ProcessedFile = SimplePlayerFile | MKVPlayerFile | HLSPlayerFile;
 interface VideoPlayer {
     initialize(videoElement: HTMLVideoElement): Promise<ProcessedFile>;
     getAudioTracks(): AudioTrack[];

package/dist/react/index.d.ts

@@ -95,6 +95,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[];
+}
 
 declare function useVideoFilters(videoRef: RefObject<HTMLVideoElement | null>): {
     filters: VideoFilters;
@@ -236,7 +248,7 @@ interface MKVPlayerFile {
     activeSubtitleTrack: string;
 }
 
-type ProcessedFile = SimplePlayerFile | MKVPlayerFile;
+type ProcessedFile = SimplePlayerFile | MKVPlayerFile | HLSPlayerFile;
 interface VideoPlayer {
     initialize(videoElement: HTMLVideoElement): Promise<ProcessedFile>;
     getAudioTracks(): AudioTrack[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightbird/core",
-  "version": "0.3.1",
+  "version": "0.4.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",
@@ -57,6 +57,7 @@
     "@openfeature/unleash-web-provider": "^0.1.1",
     "@openfeature/web-sdk": "^1.6.0",
     "ass-compiler": "^0.1.16",
+    "hls.js": "^1.6.16",
     "webtorrent": "^2.8.5"
   },
   "optionalDependencies": {