@lightbird/core 0.8.0 → 0.10.0

package/dist/index.cjs

@@ -765,14 +765,32 @@ function isHlsUrl(url) {
   if (HLS_MIME_HINTS.some((hint) => lower.includes(hint))) return true;
   return lower.split(/[?#]/)[0].endsWith(".m3u8");
 }
+function parseHlsCodec(codec) {
+  if (!codec) return null;
+  switch (codec.slice(0, 4).toLowerCase()) {
+    case "avc1":
+      return "H.264 (AVC)";
+    case "hvc1":
+    case "hev1":
+      return "H.265 (HEVC)";
+    case "vp09":
+      return "VP9";
+    case "av01":
+      return "AV1";
+    default:
+      return codec;
+  }
+}
 var HLSPlayer = class {
   constructor(url) {
     this.hls = null;
+    this.hlsCtor = null;
     this.url = url;
     this.playerFile = { url, qualityLevels: [] };
   }
   async initialize(videoElement) {
     const { default: HlsCtor } = await import('hls.js');
+    this.hlsCtor = HlsCtor;
     if (!HlsCtor.isSupported()) {
       videoElement.src = this.url;
       return this.playerFile;
@@ -818,6 +836,57 @@ var HLSPlayer = class {
   setQualityLevel(levelIndex) {
     if (this.hls) this.hls.currentLevel = levelIndex;
   }
+  /**
+   * Index of the active rendition, or `-1` for automatic (ABR) selection /
+   * before the manifest loads / on the native-HLS path.
+   */
+  getCurrentLevel() {
+    return this.hls?.currentLevel ?? -1;
+  }
+  /**
+   * HLS-specific metadata for the video info panel, derived from the active
+   * rendition. Returns an empty object before the manifest loads or on the
+   * native-HLS path (where hls.js is never instantiated).
+   */
+  getMetadata() {
+    const hls = this.hls;
+    if (!hls) return {};
+    const levels = hls.levels ?? [];
+    const activeIndex = hls.currentLevel >= 0 && hls.currentLevel < levels.length ? hls.currentLevel : 0;
+    const active = levels[activeIndex];
+    return {
+      container: "HLS",
+      videoCodec: parseHlsCodec(active?.videoCodec),
+      videoBitrate: active?.bitrate ?? null,
+      streamRenditions: levels.length,
+      audioTracks: (hls.audioTracks ?? []).map((track, index) => ({
+        index,
+        codec: track.audioCodec ?? null,
+        channels: null,
+        sampleRate: null,
+        language: track.lang ?? null,
+        bitrate: null
+      }))
+    };
+  }
+  /**
+   * Subscribe to HLS events that change the info-panel metadata (manifest
+   * parsed, quality level switched, audio tracks updated). Returns an
+   * unsubscribe function. A no-op on the native-HLS path.
+   */
+  onMetadataChange(callback) {
+    const hls = this.hls;
+    const HlsCtor = this.hlsCtor;
+    if (!hls || !HlsCtor) return () => {
+    };
+    const events = [
+      HlsCtor.Events.MANIFEST_PARSED,
+      HlsCtor.Events.LEVEL_SWITCHED,
+      HlsCtor.Events.AUDIO_TRACKS_UPDATED
+    ];
+    events.forEach((event) => hls.on(event, callback));
+    return () => events.forEach((event) => hls.off(event, callback));
+  }
   destroy() {
     if (this.hls) {
       this.hls.destroy();
@@ -1823,6 +1892,7 @@ exports.loadShortcuts = loadShortcuts;
 exports.matchesShortcut = matchesShortcut;
 exports.parseChaptersFromFFmpegLog = parseChaptersFromFFmpegLog;
 exports.parseChaptersFromVtt = parseChaptersFromVtt;
+exports.parseHlsCodec = parseHlsCodec;
 exports.parseM3U8 = parseM3U8;
 exports.parseMediaError = parseMediaError;
 exports.resetFFmpeg = resetFFmpeg;

package/dist/index.d.cts

@@ -69,6 +69,8 @@ interface VideoMetadata {
     colorSpace: string | null;
     audioTracks: AudioTrackMeta[];
     subtitleTracks: SubtitleTrackMeta[];
+    /** Number of HLS/adaptive renditions, when playing an adaptive stream. */
+    streamRenditions?: number | null;
 }
 interface AudioTrackMeta {
     index: number;
@@ -196,16 +198,27 @@ interface VideoPlayer {
      * For all other players/paths this is already resolved when initialize() returns.
      */
     tracksReady?: Promise<void>;
+    /** HLS-only: metadata derived from the active rendition (see HLSPlayer). */
+    getMetadata?(): Partial<VideoMetadata>;
+    /** HLS-only: subscribe to stream events that change metadata. Returns an unsubscribe fn. */
+    onMetadataChange?(callback: () => void): () => void;
 }
 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;
+/**
+ * Map an hls.js MIME codec string (e.g. `avc1.640028`) to a human-friendly
+ * label by inspecting the leading four-character codec family. Unknown
+ * families fall back to the raw string; empty input yields `null`.
+ */
+declare function parseHlsCodec(codec: string | null | undefined): string | null;
 /** 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;
+    private hlsCtor;
     constructor(url: string);
     initialize(videoElement: HTMLVideoElement): Promise<HLSPlayerFile>;
     getAudioTracks(): AudioTrack[];
@@ -216,6 +229,23 @@ declare class HLSPlayer implements VideoPlayer {
     getQualityLevels(): QualityLevel[];
     /** Pins a quality level; `-1` restores automatic (ABR) selection. */
     setQualityLevel(levelIndex: number): void;
+    /**
+     * Index of the active rendition, or `-1` for automatic (ABR) selection /
+     * before the manifest loads / on the native-HLS path.
+     */
+    getCurrentLevel(): number;
+    /**
+     * HLS-specific metadata for the video info panel, derived from the active
+     * rendition. Returns an empty object before the manifest loads or on the
+     * native-HLS path (where hls.js is never instantiated).
+     */
+    getMetadata(): Partial<VideoMetadata>;
+    /**
+     * Subscribe to HLS events that change the info-panel metadata (manifest
+     * parsed, quality level switched, audio tracks updated). Returns an
+     * unsubscribe function. A no-op on the native-HLS path.
+     */
+    onMetadataChange(callback: () => void): () => void;
     destroy(): void;
     static isCompatible(url: string): boolean;
 }
@@ -495,4 +525,4 @@ declare function resetFFmpeg(): void;
  */
 declare function getLanguageName(code?: string | null): string | undefined;
 
-export { ASSRenderer, type AudioTrack, type AudioTrackMeta, CancellationError, type Chapter, DEFAULT_SHORTCUTS, DEFAULT_TRACKERS, DISCLAIMER_KEY, type ExportFrameOptions, 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, downloadDataUrl, exportPlaylist, exportVideoFrame, extractNativeMetadata, formatShortcutKey, frameExportFilename, getFFmpeg, getLanguageName, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, 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, type ExportFrameOptions, 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, downloadDataUrl, exportPlaylist, exportVideoFrame, extractNativeMetadata, formatShortcutKey, frameExportFilename, getFFmpeg, getLanguageName, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseHlsCodec, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };

package/dist/index.d.ts

@@ -69,6 +69,8 @@ interface VideoMetadata {
     colorSpace: string | null;
     audioTracks: AudioTrackMeta[];
     subtitleTracks: SubtitleTrackMeta[];
+    /** Number of HLS/adaptive renditions, when playing an adaptive stream. */
+    streamRenditions?: number | null;
 }
 interface AudioTrackMeta {
     index: number;
@@ -196,16 +198,27 @@ interface VideoPlayer {
      * For all other players/paths this is already resolved when initialize() returns.
      */
     tracksReady?: Promise<void>;
+    /** HLS-only: metadata derived from the active rendition (see HLSPlayer). */
+    getMetadata?(): Partial<VideoMetadata>;
+    /** HLS-only: subscribe to stream events that change metadata. Returns an unsubscribe fn. */
+    onMetadataChange?(callback: () => void): () => void;
 }
 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;
+/**
+ * Map an hls.js MIME codec string (e.g. `avc1.640028`) to a human-friendly
+ * label by inspecting the leading four-character codec family. Unknown
+ * families fall back to the raw string; empty input yields `null`.
+ */
+declare function parseHlsCodec(codec: string | null | undefined): string | null;
 /** 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;
+    private hlsCtor;
     constructor(url: string);
     initialize(videoElement: HTMLVideoElement): Promise<HLSPlayerFile>;
     getAudioTracks(): AudioTrack[];
@@ -216,6 +229,23 @@ declare class HLSPlayer implements VideoPlayer {
     getQualityLevels(): QualityLevel[];
     /** Pins a quality level; `-1` restores automatic (ABR) selection. */
     setQualityLevel(levelIndex: number): void;
+    /**
+     * Index of the active rendition, or `-1` for automatic (ABR) selection /
+     * before the manifest loads / on the native-HLS path.
+     */
+    getCurrentLevel(): number;
+    /**
+     * HLS-specific metadata for the video info panel, derived from the active
+     * rendition. Returns an empty object before the manifest loads or on the
+     * native-HLS path (where hls.js is never instantiated).
+     */
+    getMetadata(): Partial<VideoMetadata>;
+    /**
+     * Subscribe to HLS events that change the info-panel metadata (manifest
+     * parsed, quality level switched, audio tracks updated). Returns an
+     * unsubscribe function. A no-op on the native-HLS path.
+     */
+    onMetadataChange(callback: () => void): () => void;
     destroy(): void;
     static isCompatible(url: string): boolean;
 }
@@ -495,4 +525,4 @@ declare function resetFFmpeg(): void;
  */
 declare function getLanguageName(code?: string | null): string | undefined;
 
-export { ASSRenderer, type AudioTrack, type AudioTrackMeta, CancellationError, type Chapter, DEFAULT_SHORTCUTS, DEFAULT_TRACKERS, DISCLAIMER_KEY, type ExportFrameOptions, 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, downloadDataUrl, exportPlaylist, exportVideoFrame, extractNativeMetadata, formatShortcutKey, frameExportFilename, getFFmpeg, getLanguageName, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, 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, type ExportFrameOptions, 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, downloadDataUrl, exportPlaylist, exportVideoFrame, extractNativeMetadata, formatShortcutKey, frameExportFilename, getFFmpeg, getLanguageName, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseHlsCodec, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };

package/dist/index.js

@@ -762,14 +762,32 @@ function isHlsUrl(url) {
   if (HLS_MIME_HINTS.some((hint) => lower.includes(hint))) return true;
   return lower.split(/[?#]/)[0].endsWith(".m3u8");
 }
+function parseHlsCodec(codec) {
+  if (!codec) return null;
+  switch (codec.slice(0, 4).toLowerCase()) {
+    case "avc1":
+      return "H.264 (AVC)";
+    case "hvc1":
+    case "hev1":
+      return "H.265 (HEVC)";
+    case "vp09":
+      return "VP9";
+    case "av01":
+      return "AV1";
+    default:
+      return codec;
+  }
+}
 var HLSPlayer = class {
   constructor(url) {
     this.hls = null;
+    this.hlsCtor = null;
     this.url = url;
     this.playerFile = { url, qualityLevels: [] };
   }
   async initialize(videoElement) {
     const { default: HlsCtor } = await import('hls.js');
+    this.hlsCtor = HlsCtor;
     if (!HlsCtor.isSupported()) {
       videoElement.src = this.url;
       return this.playerFile;
@@ -815,6 +833,57 @@ var HLSPlayer = class {
   setQualityLevel(levelIndex) {
     if (this.hls) this.hls.currentLevel = levelIndex;
   }
+  /**
+   * Index of the active rendition, or `-1` for automatic (ABR) selection /
+   * before the manifest loads / on the native-HLS path.
+   */
+  getCurrentLevel() {
+    return this.hls?.currentLevel ?? -1;
+  }
+  /**
+   * HLS-specific metadata for the video info panel, derived from the active
+   * rendition. Returns an empty object before the manifest loads or on the
+   * native-HLS path (where hls.js is never instantiated).
+   */
+  getMetadata() {
+    const hls = this.hls;
+    if (!hls) return {};
+    const levels = hls.levels ?? [];
+    const activeIndex = hls.currentLevel >= 0 && hls.currentLevel < levels.length ? hls.currentLevel : 0;
+    const active = levels[activeIndex];
+    return {
+      container: "HLS",
+      videoCodec: parseHlsCodec(active?.videoCodec),
+      videoBitrate: active?.bitrate ?? null,
+      streamRenditions: levels.length,
+      audioTracks: (hls.audioTracks ?? []).map((track, index) => ({
+        index,
+        codec: track.audioCodec ?? null,
+        channels: null,
+        sampleRate: null,
+        language: track.lang ?? null,
+        bitrate: null
+      }))
+    };
+  }
+  /**
+   * Subscribe to HLS events that change the info-panel metadata (manifest
+   * parsed, quality level switched, audio tracks updated). Returns an
+   * unsubscribe function. A no-op on the native-HLS path.
+   */
+  onMetadataChange(callback) {
+    const hls = this.hls;
+    const HlsCtor = this.hlsCtor;
+    if (!hls || !HlsCtor) return () => {
+    };
+    const events = [
+      HlsCtor.Events.MANIFEST_PARSED,
+      HlsCtor.Events.LEVEL_SWITCHED,
+      HlsCtor.Events.AUDIO_TRACKS_UPDATED
+    ];
+    events.forEach((event) => hls.on(event, callback));
+    return () => events.forEach((event) => hls.off(event, callback));
+  }
   destroy() {
     if (this.hls) {
       this.hls.destroy();
@@ -1779,4 +1848,4 @@ function resetFFmpeg() {
   loading = null;
 }
 
-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, downloadDataUrl, exportPlaylist, exportVideoFrame, extractNativeMetadata, formatShortcutKey, frameExportFilename, getFFmpeg, getLanguageName, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, 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, downloadDataUrl, exportPlaylist, exportVideoFrame, extractNativeMetadata, formatShortcutKey, frameExportFilename, getFFmpeg, getLanguageName, getVideoFiles, getWebTorrentClient, hasAcceptedDisclaimer, initFeatureFlags, isHlsUrl, isInteractiveElement, isMagnetUri, isVideoFile, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseHlsCodec, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };

package/dist/react/index.cjs

@@ -836,6 +836,177 @@ function useVideoInfo(videoRef, currentFile) {
   }, []);
   return { metadata, enrichMetadata };
 }
+
+// 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");
+}
+function parseHlsCodec(codec) {
+  if (!codec) return null;
+  switch (codec.slice(0, 4).toLowerCase()) {
+    case "avc1":
+      return "H.264 (AVC)";
+    case "hvc1":
+    case "hev1":
+      return "H.265 (HEVC)";
+    case "vp09":
+      return "VP9";
+    case "av01":
+      return "AV1";
+    default:
+      return codec;
+  }
+}
+var HLSPlayer = class {
+  constructor(url) {
+    this.hls = null;
+    this.hlsCtor = null;
+    this.url = url;
+    this.playerFile = { url, qualityLevels: [] };
+  }
+  async initialize(videoElement) {
+    const { default: HlsCtor } = await import('hls.js');
+    this.hlsCtor = HlsCtor;
+    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;
+  }
+  /**
+   * Index of the active rendition, or `-1` for automatic (ABR) selection /
+   * before the manifest loads / on the native-HLS path.
+   */
+  getCurrentLevel() {
+    return this.hls?.currentLevel ?? -1;
+  }
+  /**
+   * HLS-specific metadata for the video info panel, derived from the active
+   * rendition. Returns an empty object before the manifest loads or on the
+   * native-HLS path (where hls.js is never instantiated).
+   */
+  getMetadata() {
+    const hls = this.hls;
+    if (!hls) return {};
+    const levels = hls.levels ?? [];
+    const activeIndex = hls.currentLevel >= 0 && hls.currentLevel < levels.length ? hls.currentLevel : 0;
+    const active = levels[activeIndex];
+    return {
+      container: "HLS",
+      videoCodec: parseHlsCodec(active?.videoCodec),
+      videoBitrate: active?.bitrate ?? null,
+      streamRenditions: levels.length,
+      audioTracks: (hls.audioTracks ?? []).map((track, index) => ({
+        index,
+        codec: track.audioCodec ?? null,
+        channels: null,
+        sampleRate: null,
+        language: track.lang ?? null,
+        bitrate: null
+      }))
+    };
+  }
+  /**
+   * Subscribe to HLS events that change the info-panel metadata (manifest
+   * parsed, quality level switched, audio tracks updated). Returns an
+   * unsubscribe function. A no-op on the native-HLS path.
+   */
+  onMetadataChange(callback) {
+    const hls = this.hls;
+    const HlsCtor = this.hlsCtor;
+    if (!hls || !HlsCtor) return () => {
+    };
+    const events = [
+      HlsCtor.Events.MANIFEST_PARSED,
+      HlsCtor.Events.LEVEL_SWITCHED,
+      HlsCtor.Events.AUDIO_TRACKS_UPDATED
+    ];
+    events.forEach((event) => hls.on(event, callback));
+    return () => events.forEach((event) => hls.off(event, callback));
+  }
+  destroy() {
+    if (this.hls) {
+      this.hls.destroy();
+      this.hls = null;
+    }
+  }
+  static isCompatible(url) {
+    return isHlsUrl(url);
+  }
+};
+
+// src/react/use-hls-quality.ts
+function useHlsQuality(playerRef) {
+  const [qualityLevels, setQualityLevels] = react.useState([]);
+  const [currentLevel, setCurrentLevel] = react.useState(-1);
+  const player = playerRef.current;
+  react.useEffect(() => {
+    if (!(player instanceof HLSPlayer)) {
+      setQualityLevels([]);
+      setCurrentLevel(-1);
+      return;
+    }
+    const refresh = () => {
+      setQualityLevels(player.getQualityLevels());
+      setCurrentLevel(player.getCurrentLevel());
+    };
+    refresh();
+    return player.onMetadataChange(refresh);
+  }, [player]);
+  const setLevel = react.useCallback(
+    (idx) => {
+      const current = playerRef.current;
+      if (!(current instanceof HLSPlayer)) return;
+      current.setQualityLevel(idx);
+      setCurrentLevel(idx);
+    },
+    [playerRef]
+  );
+  return { qualityLevels, currentLevel, setLevel };
+}
 function useMediaSession(options) {
   const { title, artwork, onPlay, onPause, onNext, onPrev, onSeekForward, onSeekBackward } = options;
   react.useEffect(() => {
@@ -1523,6 +1694,7 @@ function useTouchGestures(targetRef, handlers, options = {}) {
 exports.useABLoop = useABLoop;
 exports.useChapters = useChapters;
 exports.useFullscreen = useFullscreen;
+exports.useHlsQuality = useHlsQuality;
 exports.useKeyboardShortcuts = useKeyboardShortcuts;
 exports.useMagnet = useMagnet;
 exports.useMediaSession = useMediaSession;

package/dist/react/index.d.cts

@@ -81,6 +81,8 @@ interface VideoMetadata {
     colorSpace: string | null;
     audioTracks: AudioTrackMeta[];
     subtitleTracks: SubtitleTrackMeta[];
+    /** Number of HLS/adaptive renditions, when playing an adaptive stream. */
+    streamRenditions?: number | null;
 }
 interface AudioTrackMeta {
     index: number;
@@ -219,18 +221,6 @@ declare function useVideoInfo(videoRef: RefObject<HTMLVideoElement | null>, curr
     enrichMetadata: (extra: Partial<VideoMetadata>) => void;
 };
 
-interface UseMediaSessionOptions {
-    title: string | null;
-    artwork?: string | null;
-    onPlay: () => void;
-    onPause: () => void;
-    onNext: () => void;
-    onPrev: () => void;
-    onSeekForward: () => void;
-    onSeekBackward: () => void;
-}
-declare function useMediaSession(options: UseMediaSessionOptions): void;
-
 interface SimplePlayerFile {
     name: string;
     file: File;
@@ -264,7 +254,42 @@ interface VideoPlayer {
      * For all other players/paths this is already resolved when initialize() returns.
      */
     tracksReady?: Promise<void>;
+    /** HLS-only: metadata derived from the active rendition (see HLSPlayer). */
+    getMetadata?(): Partial<VideoMetadata>;
+    /** HLS-only: subscribe to stream events that change metadata. Returns an unsubscribe fn. */
+    onMetadataChange?(callback: () => void): () => void;
+}
+
+interface UseHlsQualityReturn {
+    /** Available renditions. Empty unless an HLS stream with levels is loaded. */
+    qualityLevels: QualityLevel[];
+    /** Index of the active level, or -1 for automatic (ABR) selection. */
+    currentLevel: number;
+    /** Switch to a level by index (-1 = auto). No-op when not playing HLS. */
+    setLevel: (idx: number) => void;
 }
+/**
+ * Exposes the quality levels of the currently loaded HLS stream and lets the
+ * caller switch between them. Returns an empty list and a no-op `setLevel` when
+ * the player is not an {@link HLSPlayer}.
+ *
+ * The list and the active level are kept in sync via
+ * {@link HLSPlayer.onMetadataChange}, which fires on manifest parse and on
+ * every `LEVEL_SWITCHED` event.
+ */
+declare function useHlsQuality(playerRef: RefObject<VideoPlayer | null>): UseHlsQualityReturn;
+
+interface UseMediaSessionOptions {
+    title: string | null;
+    artwork?: string | null;
+    onPlay: () => void;
+    onPause: () => void;
+    onNext: () => void;
+    onPrev: () => void;
+    onSeekForward: () => void;
+    onSeekBackward: () => void;
+}
+declare function useMediaSession(options: UseMediaSessionOptions): void;
 
 declare function useChapters(videoRef: RefObject<HTMLVideoElement>, playerRef: RefObject<VideoPlayer | null>): {
     chapters: Chapter[];
@@ -398,4 +423,4 @@ interface TouchGesturesState {
  */
 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, useSmoothProgress, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };
+export { type ABLoopState, type SeekPreviewState, type ShortcutHandlers, type TouchGestureFeedback, type TouchGestureHandlers, type TouchGesturesState, type UseHlsQualityReturn, type UseMagnetReturn, type UseMediaSessionOptions, type UseSeekPreviewOptions, type UseSubtitlesOptions, type UseTouchGesturesOptions, useABLoop, useChapters, useFullscreen, useHlsQuality, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSeekPreview, useSmoothProgress, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };

package/dist/react/index.d.ts

@@ -81,6 +81,8 @@ interface VideoMetadata {
     colorSpace: string | null;
     audioTracks: AudioTrackMeta[];
     subtitleTracks: SubtitleTrackMeta[];
+    /** Number of HLS/adaptive renditions, when playing an adaptive stream. */
+    streamRenditions?: number | null;
 }
 interface AudioTrackMeta {
     index: number;
@@ -219,18 +221,6 @@ declare function useVideoInfo(videoRef: RefObject<HTMLVideoElement | null>, curr
     enrichMetadata: (extra: Partial<VideoMetadata>) => void;
 };
 
-interface UseMediaSessionOptions {
-    title: string | null;
-    artwork?: string | null;
-    onPlay: () => void;
-    onPause: () => void;
-    onNext: () => void;
-    onPrev: () => void;
-    onSeekForward: () => void;
-    onSeekBackward: () => void;
-}
-declare function useMediaSession(options: UseMediaSessionOptions): void;
-
 interface SimplePlayerFile {
     name: string;
     file: File;
@@ -264,7 +254,42 @@ interface VideoPlayer {
      * For all other players/paths this is already resolved when initialize() returns.
      */
     tracksReady?: Promise<void>;
+    /** HLS-only: metadata derived from the active rendition (see HLSPlayer). */
+    getMetadata?(): Partial<VideoMetadata>;
+    /** HLS-only: subscribe to stream events that change metadata. Returns an unsubscribe fn. */
+    onMetadataChange?(callback: () => void): () => void;
+}
+
+interface UseHlsQualityReturn {
+    /** Available renditions. Empty unless an HLS stream with levels is loaded. */
+    qualityLevels: QualityLevel[];
+    /** Index of the active level, or -1 for automatic (ABR) selection. */
+    currentLevel: number;
+    /** Switch to a level by index (-1 = auto). No-op when not playing HLS. */
+    setLevel: (idx: number) => void;
 }
+/**
+ * Exposes the quality levels of the currently loaded HLS stream and lets the
+ * caller switch between them. Returns an empty list and a no-op `setLevel` when
+ * the player is not an {@link HLSPlayer}.
+ *
+ * The list and the active level are kept in sync via
+ * {@link HLSPlayer.onMetadataChange}, which fires on manifest parse and on
+ * every `LEVEL_SWITCHED` event.
+ */
+declare function useHlsQuality(playerRef: RefObject<VideoPlayer | null>): UseHlsQualityReturn;
+
+interface UseMediaSessionOptions {
+    title: string | null;
+    artwork?: string | null;
+    onPlay: () => void;
+    onPause: () => void;
+    onNext: () => void;
+    onPrev: () => void;
+    onSeekForward: () => void;
+    onSeekBackward: () => void;
+}
+declare function useMediaSession(options: UseMediaSessionOptions): void;
 
 declare function useChapters(videoRef: RefObject<HTMLVideoElement>, playerRef: RefObject<VideoPlayer | null>): {
     chapters: Chapter[];
@@ -398,4 +423,4 @@ interface TouchGesturesState {
  */
 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, useSmoothProgress, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };
+export { type ABLoopState, type SeekPreviewState, type ShortcutHandlers, type TouchGestureFeedback, type TouchGestureHandlers, type TouchGesturesState, type UseHlsQualityReturn, type UseMagnetReturn, type UseMediaSessionOptions, type UseSeekPreviewOptions, type UseSubtitlesOptions, type UseTouchGesturesOptions, useABLoop, useChapters, useFullscreen, useHlsQuality, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSeekPreview, useSmoothProgress, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };

package/dist/react/index.js

@@ -834,6 +834,177 @@ function useVideoInfo(videoRef, currentFile) {
   }, []);
   return { metadata, enrichMetadata };
 }
+
+// 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");
+}
+function parseHlsCodec(codec) {
+  if (!codec) return null;
+  switch (codec.slice(0, 4).toLowerCase()) {
+    case "avc1":
+      return "H.264 (AVC)";
+    case "hvc1":
+    case "hev1":
+      return "H.265 (HEVC)";
+    case "vp09":
+      return "VP9";
+    case "av01":
+      return "AV1";
+    default:
+      return codec;
+  }
+}
+var HLSPlayer = class {
+  constructor(url) {
+    this.hls = null;
+    this.hlsCtor = null;
+    this.url = url;
+    this.playerFile = { url, qualityLevels: [] };
+  }
+  async initialize(videoElement) {
+    const { default: HlsCtor } = await import('hls.js');
+    this.hlsCtor = HlsCtor;
+    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;
+  }
+  /**
+   * Index of the active rendition, or `-1` for automatic (ABR) selection /
+   * before the manifest loads / on the native-HLS path.
+   */
+  getCurrentLevel() {
+    return this.hls?.currentLevel ?? -1;
+  }
+  /**
+   * HLS-specific metadata for the video info panel, derived from the active
+   * rendition. Returns an empty object before the manifest loads or on the
+   * native-HLS path (where hls.js is never instantiated).
+   */
+  getMetadata() {
+    const hls = this.hls;
+    if (!hls) return {};
+    const levels = hls.levels ?? [];
+    const activeIndex = hls.currentLevel >= 0 && hls.currentLevel < levels.length ? hls.currentLevel : 0;
+    const active = levels[activeIndex];
+    return {
+      container: "HLS",
+      videoCodec: parseHlsCodec(active?.videoCodec),
+      videoBitrate: active?.bitrate ?? null,
+      streamRenditions: levels.length,
+      audioTracks: (hls.audioTracks ?? []).map((track, index) => ({
+        index,
+        codec: track.audioCodec ?? null,
+        channels: null,
+        sampleRate: null,
+        language: track.lang ?? null,
+        bitrate: null
+      }))
+    };
+  }
+  /**
+   * Subscribe to HLS events that change the info-panel metadata (manifest
+   * parsed, quality level switched, audio tracks updated). Returns an
+   * unsubscribe function. A no-op on the native-HLS path.
+   */
+  onMetadataChange(callback) {
+    const hls = this.hls;
+    const HlsCtor = this.hlsCtor;
+    if (!hls || !HlsCtor) return () => {
+    };
+    const events = [
+      HlsCtor.Events.MANIFEST_PARSED,
+      HlsCtor.Events.LEVEL_SWITCHED,
+      HlsCtor.Events.AUDIO_TRACKS_UPDATED
+    ];
+    events.forEach((event) => hls.on(event, callback));
+    return () => events.forEach((event) => hls.off(event, callback));
+  }
+  destroy() {
+    if (this.hls) {
+      this.hls.destroy();
+      this.hls = null;
+    }
+  }
+  static isCompatible(url) {
+    return isHlsUrl(url);
+  }
+};
+
+// src/react/use-hls-quality.ts
+function useHlsQuality(playerRef) {
+  const [qualityLevels, setQualityLevels] = useState([]);
+  const [currentLevel, setCurrentLevel] = useState(-1);
+  const player = playerRef.current;
+  useEffect(() => {
+    if (!(player instanceof HLSPlayer)) {
+      setQualityLevels([]);
+      setCurrentLevel(-1);
+      return;
+    }
+    const refresh = () => {
+      setQualityLevels(player.getQualityLevels());
+      setCurrentLevel(player.getCurrentLevel());
+    };
+    refresh();
+    return player.onMetadataChange(refresh);
+  }, [player]);
+  const setLevel = useCallback(
+    (idx) => {
+      const current = playerRef.current;
+      if (!(current instanceof HLSPlayer)) return;
+      current.setQualityLevel(idx);
+      setCurrentLevel(idx);
+    },
+    [playerRef]
+  );
+  return { qualityLevels, currentLevel, setLevel };
+}
 function useMediaSession(options) {
   const { title, artwork, onPlay, onPause, onNext, onPrev, onSeekForward, onSeekBackward } = options;
   useEffect(() => {
@@ -1518,4 +1689,4 @@ function useTouchGestures(targetRef, handlers, options = {}) {
   return { feedback };
 }
 
-export { useABLoop, useChapters, useFullscreen, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSeekPreview, useSmoothProgress, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };
+export { useABLoop, useChapters, useFullscreen, useHlsQuality, useKeyboardShortcuts, useMagnet, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSeekPreview, useSmoothProgress, useSubtitles, useTouchGestures, useVideoFilters, useVideoInfo, useVideoPlayback };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightbird/core",
-  "version": "0.8.0",
+  "version": "0.10.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",