@lightbird/core 0.7.0 → 0.9.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,50 @@ var HLSPlayer = class {
   setQualityLevel(levelIndex) {
     if (this.hls) this.hls.currentLevel = levelIndex;
   }
+  /**
+   * 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();
@@ -1614,6 +1676,36 @@ async function captureFrameAt(videoEl, timeSeconds, width = 160, height = 90) {
   });
 }
 
+// src/utils/frame-export.ts
+function exportVideoFrame(videoEl, options = {}) {
+  const { type = "image/png", quality, filter } = options;
+  const width = videoEl.videoWidth;
+  const height = videoEl.videoHeight;
+  if (!width || !height) return null;
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return null;
+  try {
+    if (filter) ctx.filter = filter;
+    ctx.drawImage(videoEl, 0, 0, width, height);
+    return canvas.toDataURL(type, quality);
+  } catch {
+    return null;
+  }
+}
+function downloadDataUrl(dataUrl, filename) {
+  const a = document.createElement("a");
+  a.href = dataUrl;
+  a.download = filename;
+  a.click();
+}
+function frameExportFilename(extension = "png") {
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-");
+  return `lightbird-screenshot-${stamp}.${extension}`;
+}
+
 // src/utils/keyboard-shortcuts.ts
 var DEFAULT_SHORTCUTS = [
   { action: "play-pause", label: "Play / Pause", defaultKey: " ", key: " " },
@@ -1773,9 +1865,12 @@ exports.configureLightBird = configureLightBird;
 exports.createOffsetVttUrl = createOffsetVttUrl;
 exports.createVideoPlayer = createVideoPlayer;
 exports.destroyWebTorrentClient = destroyWebTorrentClient;
+exports.downloadDataUrl = downloadDataUrl;
 exports.exportPlaylist = exportPlaylist;
+exports.exportVideoFrame = exportVideoFrame;
 exports.extractNativeMetadata = extractNativeMetadata;
 exports.formatShortcutKey = formatShortcutKey;
+exports.frameExportFilename = frameExportFilename;
 exports.getFFmpeg = getFFmpeg;
 exports.getLanguageName = getLanguageName;
 exports.getVideoFiles = getVideoFiles;
@@ -1790,6 +1885,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,18 @@ declare class HLSPlayer implements VideoPlayer {
     getQualityLevels(): QualityLevel[];
     /** Pins a quality level; `-1` restores automatic (ABR) selection. */
     setQualityLevel(levelIndex: number): void;
+    /**
+     * 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;
 }
@@ -388,6 +413,51 @@ declare function captureVideoThumbnail(videoEl: HTMLVideoElement, atSeconds?: nu
  */
 declare function captureFrameAt(videoEl: HTMLVideoElement, timeSeconds: number, width?: number, height?: number): Promise<string | null>;
 
+/**
+ * Frame / screenshot export.
+ *
+ * Captures the currently displayed frame of a playing video element to an
+ * image and (optionally) triggers a browser download. Unlike the seek-hover
+ * preview in {@link ./video-thumbnail}, this grabs the frame *in place* at the
+ * video's native resolution without seeking, so it never disturbs playback.
+ */
+interface ExportFrameOptions {
+    /** Output image MIME type. Defaults to `"image/png"`. */
+    type?: string;
+    /** Quality (0–1) for lossy formats such as jpeg/webp. Ignored for png. */
+    quality?: number;
+    /**
+     * CSS `filter` string to bake into the exported image (e.g. the
+     * brightness/contrast filters applied to the video element). When omitted,
+     * the raw frame is captured.
+     */
+    filter?: string;
+}
+/**
+ * Capture the current frame of a video element at its native resolution.
+ *
+ * @param videoEl - The video element to capture from.
+ * @param options - Output format and an optional CSS filter to bake in.
+ * @returns An image data URL, or `null` if capture failed — no 2d context, the
+ *          video has no decoded dimensions yet, or the canvas is tainted by a
+ *          cross-origin source.
+ */
+declare function exportVideoFrame(videoEl: HTMLVideoElement, options?: ExportFrameOptions): string | null;
+/**
+ * Trigger a browser download of a data URL by synthesizing an anchor click.
+ *
+ * @param dataUrl - The data (or object) URL to download.
+ * @param filename - The suggested filename for the saved file.
+ */
+declare function downloadDataUrl(dataUrl: string, filename: string): void;
+/**
+ * Build a timestamped default filename for an exported frame.
+ *
+ * @param extension - File extension without a leading dot. Defaults to `"png"`.
+ * @returns e.g. `lightbird-screenshot-2026-05-30T12-00-00-000Z.png`.
+ */
+declare function frameExportFilename(extension?: string): string;
+
 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' | 'frame-step-forward' | 'frame-step-backward' | 'loop-toggle' | 'ab-loop-cycle';
 interface ShortcutBinding {
     action: ShortcutAction;
@@ -450,4 +520,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, 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, 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,18 @@ declare class HLSPlayer implements VideoPlayer {
     getQualityLevels(): QualityLevel[];
     /** Pins a quality level; `-1` restores automatic (ABR) selection. */
     setQualityLevel(levelIndex: number): void;
+    /**
+     * 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;
 }
@@ -388,6 +413,51 @@ declare function captureVideoThumbnail(videoEl: HTMLVideoElement, atSeconds?: nu
  */
 declare function captureFrameAt(videoEl: HTMLVideoElement, timeSeconds: number, width?: number, height?: number): Promise<string | null>;
 
+/**
+ * Frame / screenshot export.
+ *
+ * Captures the currently displayed frame of a playing video element to an
+ * image and (optionally) triggers a browser download. Unlike the seek-hover
+ * preview in {@link ./video-thumbnail}, this grabs the frame *in place* at the
+ * video's native resolution without seeking, so it never disturbs playback.
+ */
+interface ExportFrameOptions {
+    /** Output image MIME type. Defaults to `"image/png"`. */
+    type?: string;
+    /** Quality (0–1) for lossy formats such as jpeg/webp. Ignored for png. */
+    quality?: number;
+    /**
+     * CSS `filter` string to bake into the exported image (e.g. the
+     * brightness/contrast filters applied to the video element). When omitted,
+     * the raw frame is captured.
+     */
+    filter?: string;
+}
+/**
+ * Capture the current frame of a video element at its native resolution.
+ *
+ * @param videoEl - The video element to capture from.
+ * @param options - Output format and an optional CSS filter to bake in.
+ * @returns An image data URL, or `null` if capture failed — no 2d context, the
+ *          video has no decoded dimensions yet, or the canvas is tainted by a
+ *          cross-origin source.
+ */
+declare function exportVideoFrame(videoEl: HTMLVideoElement, options?: ExportFrameOptions): string | null;
+/**
+ * Trigger a browser download of a data URL by synthesizing an anchor click.
+ *
+ * @param dataUrl - The data (or object) URL to download.
+ * @param filename - The suggested filename for the saved file.
+ */
+declare function downloadDataUrl(dataUrl: string, filename: string): void;
+/**
+ * Build a timestamped default filename for an exported frame.
+ *
+ * @param extension - File extension without a leading dot. Defaults to `"png"`.
+ * @returns e.g. `lightbird-screenshot-2026-05-30T12-00-00-000Z.png`.
+ */
+declare function frameExportFilename(extension?: string): string;
+
 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' | 'frame-step-forward' | 'frame-step-backward' | 'loop-toggle' | 'ab-loop-cycle';
 interface ShortcutBinding {
     action: ShortcutAction;
@@ -450,4 +520,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, 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, 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,50 @@ var HLSPlayer = class {
   setQualityLevel(levelIndex) {
     if (this.hls) this.hls.currentLevel = levelIndex;
   }
+  /**
+   * 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();
@@ -1611,6 +1673,36 @@ async function captureFrameAt(videoEl, timeSeconds, width = 160, height = 90) {
   });
 }
 
+// src/utils/frame-export.ts
+function exportVideoFrame(videoEl, options = {}) {
+  const { type = "image/png", quality, filter } = options;
+  const width = videoEl.videoWidth;
+  const height = videoEl.videoHeight;
+  if (!width || !height) return null;
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return null;
+  try {
+    if (filter) ctx.filter = filter;
+    ctx.drawImage(videoEl, 0, 0, width, height);
+    return canvas.toDataURL(type, quality);
+  } catch {
+    return null;
+  }
+}
+function downloadDataUrl(dataUrl, filename) {
+  const a = document.createElement("a");
+  a.href = dataUrl;
+  a.download = filename;
+  a.click();
+}
+function frameExportFilename(extension = "png") {
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-");
+  return `lightbird-screenshot-${stamp}.${extension}`;
+}
+
 // src/utils/keyboard-shortcuts.ts
 var DEFAULT_SHORTCUTS = [
   { action: "play-pause", label: "Play / Pause", defaultKey: " ", key: " " },
@@ -1749,4 +1841,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, exportPlaylist, extractNativeMetadata, formatShortcutKey, 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.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;
@@ -264,6 +266,10 @@ 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 useChapters(videoRef: RefObject<HTMLVideoElement>, playerRef: RefObject<VideoPlayer | null>): {

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;
@@ -264,6 +266,10 @@ 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 useChapters(videoRef: RefObject<HTMLVideoElement>, playerRef: RefObject<VideoPlayer | null>): {

package/package.json

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