@lightbird/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,317 @@
+import { FFmpeg } from '@ffmpeg/ffmpeg';
+
+interface LightBirdConfig {
+    ffmpegCDN?: string;
+}
+declare function configureLightBird(options: LightBirdConfig): void;
+
+interface Chapter {
+    index: number;
+    title: string;
+    startTime: number;
+    endTime: number;
+}
+interface PlaylistItem {
+    id: string;
+    name: string;
+    url: string;
+    type: 'video' | 'stream';
+    file?: File;
+    duration?: number;
+}
+interface SubtitleCue {
+    startTime: number;
+    endTime: number;
+    text: string;
+}
+interface Subtitle {
+    id: string;
+    name: string;
+    lang: string;
+    url?: string;
+    type: 'embedded' | 'external';
+    /** Detected source format (vtt, srt, ass, ssa). Defaults to 'vtt'. */
+    format?: 'vtt' | 'srt' | 'ass' | 'ssa';
+}
+interface AudioTrack {
+    id: string;
+    name: string;
+    lang: string;
+}
+interface VideoFilters {
+    brightness: number;
+    contrast: number;
+    saturate: number;
+    hue: number;
+}
+interface VideoMetadata {
+    filename: string;
+    fileSize: number | null;
+    duration: number;
+    container: string;
+    width: number;
+    height: number;
+    frameRate: number | null;
+    videoBitrate: number | null;
+    videoCodec: string | null;
+    colorSpace: string | null;
+    audioTracks: AudioTrackMeta[];
+    subtitleTracks: SubtitleTrackMeta[];
+}
+interface AudioTrackMeta {
+    index: number;
+    codec: string | null;
+    channels: number | null;
+    sampleRate: number | null;
+    language: string | null;
+    bitrate: number | null;
+}
+interface SubtitleTrackMeta {
+    index: number;
+    format: string | null;
+    language: string | null;
+}
+
+interface SimplePlayerFile {
+    name: string;
+    file: File;
+    url: string;
+    externalSubtitles?: Subtitle[];
+}
+declare class SimplePlayer {
+    private file;
+    private videoElement;
+    private currentSubtitleTrackIndex;
+    constructor(file: File, externalSubtitles?: File[]);
+    private processExternalSubtitles;
+    initialize(videoElement: HTMLVideoElement): Promise<SimplePlayerFile>;
+    getAudioTracks(): AudioTrack[];
+    getSubtitles(): Subtitle[];
+    switchAudioTrack(trackId: string): Promise<void>;
+    switchSubtitle(trackId: string): Promise<void>;
+    destroy(): void;
+    static isCompatible(file: File): boolean;
+}
+
+declare class CancellationError extends Error {
+    constructor();
+}
+interface MKVPlayerFile {
+    name: string;
+    file: File;
+    videoUrl?: string;
+    audioTracks: AudioTrack[];
+    subtitleTracks: Subtitle[];
+    activeAudioTrack: string;
+    activeSubtitleTrack: string;
+}
+declare class MKVPlayer {
+    /**
+     * Overrideable in tests to avoid real browser playback probes.
+     * @internal
+     */
+    static _canPlayNatively: (url: string, timeoutMs?: number) => Promise<boolean>;
+    /**
+     * Overrideable factory for creating the FFmpeg worker. Tests override this
+     * to avoid `import.meta.url` (not available in CJS Jest).
+     * @internal
+     */
+    static _workerFactory: (() => Worker) | null;
+    private file;
+    private playerFile;
+    private videoElement;
+    private objectUrl;
+    private _cancelled;
+    private subtitleTrackMap;
+    private subtitleBlobUrls;
+    private onProgress?;
+    private chapters;
+    private remuxCache;
+    private worker;
+    private pendingOperations;
+    /**
+     * Resolves when track metadata (audio + subtitle) is fully populated.
+     * On the FFmpeg path this resolves after initialize() itself. On the native
+     * path the probe runs in the background so initialize() returns first —
+     * callers that need the real track list should await this promise.
+     */
+    tracksReady: Promise<void>;
+    constructor(file: File, onProgress?: (progress: number) => void);
+    private getWorker;
+    private _handleWorkerMessage;
+    private sendToWorker;
+    initialize(videoElement: HTMLVideoElement): Promise<MKVPlayerFile>;
+    private _probeForTracks;
+    private _remux;
+    private _extractSubtitle;
+    getAudioTracks(): AudioTrack[];
+    getSubtitles(): Subtitle[];
+    getChapters(): Chapter[];
+    switchAudioTrack(trackId: string): Promise<void>;
+    switchSubtitle(trackId: string): Promise<void>;
+    getActiveAudioTrack(): string;
+    getActiveSubtitleTrack(): string;
+    cancel(): void;
+    destroy(): void;
+    static isCompatible(file: File): boolean;
+}
+
+type ProcessedFile = SimplePlayerFile | MKVPlayerFile;
+interface VideoPlayer {
+    initialize(videoElement: HTMLVideoElement): Promise<ProcessedFile>;
+    getAudioTracks(): AudioTrack[];
+    getSubtitles(): Subtitle[];
+    getChapters?(): Chapter[];
+    switchAudioTrack(trackId: string): Promise<void>;
+    switchSubtitle(trackId: string): Promise<void>;
+    destroy(): void;
+    cancel?(): void;
+    /**
+     * Resolves when track metadata is fully populated. Only meaningful for
+     * MKVPlayer on the native path (where the probe runs after initialize()).
+     * For all other players/paths this is already resolved when initialize() returns.
+     */
+    tracksReady?: Promise<void>;
+}
+declare function createVideoPlayer(file: File, externalSubtitles?: File[], onProgress?: (progress: number) => void): VideoPlayer;
+
+declare class UniversalSubtitleManager {
+    private records;
+    private videoElement;
+    private nextId;
+    constructor(videoElement?: HTMLVideoElement);
+    setVideoElement(videoElement: HTMLVideoElement): void;
+    addSubtitleFiles(files: File[]): Promise<Subtitle[]>;
+    removeSubtitle(id: string): boolean;
+    switchSubtitle(id: string): void;
+    /**
+     * Sets a time offset (in seconds) for a VTT/SRT subtitle.
+     * Regenerates the blob URL with shifted timestamps and updates the track element.
+     */
+    setOffset(id: string, offsetSeconds: number): Promise<void>;
+    /** Returns parsed cue index for a subtitle (empty array for ASS/SSA). */
+    getCues(id: string): SubtitleCue[];
+    /** Returns cues for all loaded VTT/SRT subtitles merged, for global search. */
+    getAllCues(): SubtitleCue[];
+    getSubtitles(): Subtitle[];
+    clearSubtitles(): void;
+    destroy(): void;
+    importSubtitles(subtitles: Subtitle[]): void;
+}
+
+declare class SubtitleConverter {
+    static convertSrtToVtt(srtContent: string): Promise<string>;
+    static convertFileToVtt(file: File): Promise<File>;
+}
+
+/**
+ * Applies a time offset (in seconds) to all cue timestamps in a VTT string.
+ * Returns the modified VTT text.
+ */
+declare function applyOffsetToVtt(vttText: string, offsetSeconds: number): string;
+/** Re-encodes a VTT blob URL with an applied time offset. Returns a new blob URL. */
+declare function createOffsetVttUrl(originalUrl: string, offsetSeconds: number): Promise<string>;
+
+declare class ASSRenderer {
+    private canvas;
+    private ctx;
+    private compiled;
+    private animFrame;
+    constructor(canvas: HTMLCanvasElement);
+    load(assText: string): void;
+    start(videoEl: HTMLVideoElement): void;
+    stop(): void;
+    renderAt(currentTimeSec: number): void;
+    private syncCanvasSize;
+    private drawDialogue;
+}
+
+/**
+ * Parses chapter data from an FFmpeg probe/log output.
+ *
+ * Looks for blocks like:
+ *   Chapter #0:0: start 0.000000, end 142.500000
+ *     Metadata:
+ *       title           : Introduction
+ *
+ * Returns [] (never throws) on malformed or missing input.
+ */
+declare function parseChaptersFromFFmpegLog(log: string, totalDuration: number): Chapter[];
+/**
+ * Parses chapter data from a WebVTT chapters file.
+ *
+ * Each cue's identifier is the chapter title; start/end come from the
+ * VTT timestamp line "HH:MM:SS.mmm --> HH:MM:SS.mmm".
+ *
+ * Returns [] (never throws) on malformed or empty input.
+ */
+declare function parseChaptersFromVtt(vttText: string): Chapter[];
+
+/** Export a playlist as an M3U8 file and trigger a browser download. */
+declare function exportPlaylist(items: PlaylistItem[]): void;
+/** Parse an M3U / M3U8 text file into playlist item descriptors (without id). */
+declare function parseM3U8(text: string): Omit<PlaylistItem, "id">[];
+
+type MediaErrorType = 'aborted' | 'network' | 'decode' | 'unsupported' | 'unknown';
+interface ParsedMediaError {
+    type: MediaErrorType;
+    message: string;
+    recoverable: boolean;
+    retryable: boolean;
+}
+declare function parseMediaError(error: MediaError | null): ParsedMediaError;
+declare function validateFile(file: File): {
+    valid: boolean;
+    reason?: string;
+};
+
+declare function extractNativeMetadata(videoEl: HTMLVideoElement, file?: File): Partial<VideoMetadata>;
+
+declare function captureVideoThumbnail(videoEl: HTMLVideoElement, atSeconds?: 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 {
+    action: ShortcutAction;
+    label: string;
+    defaultKey: string;
+    key: string;
+    modifiers?: {
+        ctrl?: boolean;
+        shift?: boolean;
+        alt?: boolean;
+    };
+}
+declare const DEFAULT_SHORTCUTS: ShortcutBinding[];
+declare function loadShortcuts(): ShortcutBinding[];
+declare function saveShortcuts(bindings: ShortcutBinding[]): void;
+declare function matchesShortcut(e: KeyboardEvent, binding: ShortcutBinding): boolean;
+declare function isInteractiveElement(el: EventTarget | null): boolean;
+declare function formatShortcutKey(binding: ShortcutBinding): string;
+
+/**
+ * Estimates remux speed and ETA from a stream of progress values [0, 1].
+ *
+ * startTime is initialized lazily on the first update() call with progress > 0
+ * to avoid capturing bootstrap latency from the constructor.
+ *
+ * Usage:
+ *   const est = new ProgressEstimator(fileSizeBytes);
+ *   est.update(0.42); // call on each progress event
+ *   const { speedMBps, etaSeconds } = est.getEstimate();
+ */
+declare class ProgressEstimator {
+    private readonly fileSizeBytes;
+    private startTime;
+    private lastProgress;
+    constructor(fileSizeBytes: number);
+    update(progress: number): void;
+    getEstimate(): {
+        speedMBps: number;
+        etaSeconds: number | null;
+    };
+}
+
+declare function getFFmpeg(): Promise<FFmpeg>;
+declare function resetFFmpeg(): void;
+
+export { ASSRenderer, type AudioTrack, type AudioTrackMeta, CancellationError, type Chapter, DEFAULT_SHORTCUTS, 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, UniversalSubtitleManager, type VideoFilters, type VideoMetadata, type VideoPlayer, applyOffsetToVtt, captureVideoThumbnail, configureLightBird, createOffsetVttUrl, createVideoPlayer, exportPlaylist, extractNativeMetadata, formatShortcutKey, getFFmpeg, isInteractiveElement, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+import { FFmpeg } from '@ffmpeg/ffmpeg';
+
+interface LightBirdConfig {
+    ffmpegCDN?: string;
+}
+declare function configureLightBird(options: LightBirdConfig): void;
+
+interface Chapter {
+    index: number;
+    title: string;
+    startTime: number;
+    endTime: number;
+}
+interface PlaylistItem {
+    id: string;
+    name: string;
+    url: string;
+    type: 'video' | 'stream';
+    file?: File;
+    duration?: number;
+}
+interface SubtitleCue {
+    startTime: number;
+    endTime: number;
+    text: string;
+}
+interface Subtitle {
+    id: string;
+    name: string;
+    lang: string;
+    url?: string;
+    type: 'embedded' | 'external';
+    /** Detected source format (vtt, srt, ass, ssa). Defaults to 'vtt'. */
+    format?: 'vtt' | 'srt' | 'ass' | 'ssa';
+}
+interface AudioTrack {
+    id: string;
+    name: string;
+    lang: string;
+}
+interface VideoFilters {
+    brightness: number;
+    contrast: number;
+    saturate: number;
+    hue: number;
+}
+interface VideoMetadata {
+    filename: string;
+    fileSize: number | null;
+    duration: number;
+    container: string;
+    width: number;
+    height: number;
+    frameRate: number | null;
+    videoBitrate: number | null;
+    videoCodec: string | null;
+    colorSpace: string | null;
+    audioTracks: AudioTrackMeta[];
+    subtitleTracks: SubtitleTrackMeta[];
+}
+interface AudioTrackMeta {
+    index: number;
+    codec: string | null;
+    channels: number | null;
+    sampleRate: number | null;
+    language: string | null;
+    bitrate: number | null;
+}
+interface SubtitleTrackMeta {
+    index: number;
+    format: string | null;
+    language: string | null;
+}
+
+interface SimplePlayerFile {
+    name: string;
+    file: File;
+    url: string;
+    externalSubtitles?: Subtitle[];
+}
+declare class SimplePlayer {
+    private file;
+    private videoElement;
+    private currentSubtitleTrackIndex;
+    constructor(file: File, externalSubtitles?: File[]);
+    private processExternalSubtitles;
+    initialize(videoElement: HTMLVideoElement): Promise<SimplePlayerFile>;
+    getAudioTracks(): AudioTrack[];
+    getSubtitles(): Subtitle[];
+    switchAudioTrack(trackId: string): Promise<void>;
+    switchSubtitle(trackId: string): Promise<void>;
+    destroy(): void;
+    static isCompatible(file: File): boolean;
+}
+
+declare class CancellationError extends Error {
+    constructor();
+}
+interface MKVPlayerFile {
+    name: string;
+    file: File;
+    videoUrl?: string;
+    audioTracks: AudioTrack[];
+    subtitleTracks: Subtitle[];
+    activeAudioTrack: string;
+    activeSubtitleTrack: string;
+}
+declare class MKVPlayer {
+    /**
+     * Overrideable in tests to avoid real browser playback probes.
+     * @internal
+     */
+    static _canPlayNatively: (url: string, timeoutMs?: number) => Promise<boolean>;
+    /**
+     * Overrideable factory for creating the FFmpeg worker. Tests override this
+     * to avoid `import.meta.url` (not available in CJS Jest).
+     * @internal
+     */
+    static _workerFactory: (() => Worker) | null;
+    private file;
+    private playerFile;
+    private videoElement;
+    private objectUrl;
+    private _cancelled;
+    private subtitleTrackMap;
+    private subtitleBlobUrls;
+    private onProgress?;
+    private chapters;
+    private remuxCache;
+    private worker;
+    private pendingOperations;
+    /**
+     * Resolves when track metadata (audio + subtitle) is fully populated.
+     * On the FFmpeg path this resolves after initialize() itself. On the native
+     * path the probe runs in the background so initialize() returns first —
+     * callers that need the real track list should await this promise.
+     */
+    tracksReady: Promise<void>;
+    constructor(file: File, onProgress?: (progress: number) => void);
+    private getWorker;
+    private _handleWorkerMessage;
+    private sendToWorker;
+    initialize(videoElement: HTMLVideoElement): Promise<MKVPlayerFile>;
+    private _probeForTracks;
+    private _remux;
+    private _extractSubtitle;
+    getAudioTracks(): AudioTrack[];
+    getSubtitles(): Subtitle[];
+    getChapters(): Chapter[];
+    switchAudioTrack(trackId: string): Promise<void>;
+    switchSubtitle(trackId: string): Promise<void>;
+    getActiveAudioTrack(): string;
+    getActiveSubtitleTrack(): string;
+    cancel(): void;
+    destroy(): void;
+    static isCompatible(file: File): boolean;
+}
+
+type ProcessedFile = SimplePlayerFile | MKVPlayerFile;
+interface VideoPlayer {
+    initialize(videoElement: HTMLVideoElement): Promise<ProcessedFile>;
+    getAudioTracks(): AudioTrack[];
+    getSubtitles(): Subtitle[];
+    getChapters?(): Chapter[];
+    switchAudioTrack(trackId: string): Promise<void>;
+    switchSubtitle(trackId: string): Promise<void>;
+    destroy(): void;
+    cancel?(): void;
+    /**
+     * Resolves when track metadata is fully populated. Only meaningful for
+     * MKVPlayer on the native path (where the probe runs after initialize()).
+     * For all other players/paths this is already resolved when initialize() returns.
+     */
+    tracksReady?: Promise<void>;
+}
+declare function createVideoPlayer(file: File, externalSubtitles?: File[], onProgress?: (progress: number) => void): VideoPlayer;
+
+declare class UniversalSubtitleManager {
+    private records;
+    private videoElement;
+    private nextId;
+    constructor(videoElement?: HTMLVideoElement);
+    setVideoElement(videoElement: HTMLVideoElement): void;
+    addSubtitleFiles(files: File[]): Promise<Subtitle[]>;
+    removeSubtitle(id: string): boolean;
+    switchSubtitle(id: string): void;
+    /**
+     * Sets a time offset (in seconds) for a VTT/SRT subtitle.
+     * Regenerates the blob URL with shifted timestamps and updates the track element.
+     */
+    setOffset(id: string, offsetSeconds: number): Promise<void>;
+    /** Returns parsed cue index for a subtitle (empty array for ASS/SSA). */
+    getCues(id: string): SubtitleCue[];
+    /** Returns cues for all loaded VTT/SRT subtitles merged, for global search. */
+    getAllCues(): SubtitleCue[];
+    getSubtitles(): Subtitle[];
+    clearSubtitles(): void;
+    destroy(): void;
+    importSubtitles(subtitles: Subtitle[]): void;
+}
+
+declare class SubtitleConverter {
+    static convertSrtToVtt(srtContent: string): Promise<string>;
+    static convertFileToVtt(file: File): Promise<File>;
+}
+
+/**
+ * Applies a time offset (in seconds) to all cue timestamps in a VTT string.
+ * Returns the modified VTT text.
+ */
+declare function applyOffsetToVtt(vttText: string, offsetSeconds: number): string;
+/** Re-encodes a VTT blob URL with an applied time offset. Returns a new blob URL. */
+declare function createOffsetVttUrl(originalUrl: string, offsetSeconds: number): Promise<string>;
+
+declare class ASSRenderer {
+    private canvas;
+    private ctx;
+    private compiled;
+    private animFrame;
+    constructor(canvas: HTMLCanvasElement);
+    load(assText: string): void;
+    start(videoEl: HTMLVideoElement): void;
+    stop(): void;
+    renderAt(currentTimeSec: number): void;
+    private syncCanvasSize;
+    private drawDialogue;
+}
+
+/**
+ * Parses chapter data from an FFmpeg probe/log output.
+ *
+ * Looks for blocks like:
+ *   Chapter #0:0: start 0.000000, end 142.500000
+ *     Metadata:
+ *       title           : Introduction
+ *
+ * Returns [] (never throws) on malformed or missing input.
+ */
+declare function parseChaptersFromFFmpegLog(log: string, totalDuration: number): Chapter[];
+/**
+ * Parses chapter data from a WebVTT chapters file.
+ *
+ * Each cue's identifier is the chapter title; start/end come from the
+ * VTT timestamp line "HH:MM:SS.mmm --> HH:MM:SS.mmm".
+ *
+ * Returns [] (never throws) on malformed or empty input.
+ */
+declare function parseChaptersFromVtt(vttText: string): Chapter[];
+
+/** Export a playlist as an M3U8 file and trigger a browser download. */
+declare function exportPlaylist(items: PlaylistItem[]): void;
+/** Parse an M3U / M3U8 text file into playlist item descriptors (without id). */
+declare function parseM3U8(text: string): Omit<PlaylistItem, "id">[];
+
+type MediaErrorType = 'aborted' | 'network' | 'decode' | 'unsupported' | 'unknown';
+interface ParsedMediaError {
+    type: MediaErrorType;
+    message: string;
+    recoverable: boolean;
+    retryable: boolean;
+}
+declare function parseMediaError(error: MediaError | null): ParsedMediaError;
+declare function validateFile(file: File): {
+    valid: boolean;
+    reason?: string;
+};
+
+declare function extractNativeMetadata(videoEl: HTMLVideoElement, file?: File): Partial<VideoMetadata>;
+
+declare function captureVideoThumbnail(videoEl: HTMLVideoElement, atSeconds?: 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 {
+    action: ShortcutAction;
+    label: string;
+    defaultKey: string;
+    key: string;
+    modifiers?: {
+        ctrl?: boolean;
+        shift?: boolean;
+        alt?: boolean;
+    };
+}
+declare const DEFAULT_SHORTCUTS: ShortcutBinding[];
+declare function loadShortcuts(): ShortcutBinding[];
+declare function saveShortcuts(bindings: ShortcutBinding[]): void;
+declare function matchesShortcut(e: KeyboardEvent, binding: ShortcutBinding): boolean;
+declare function isInteractiveElement(el: EventTarget | null): boolean;
+declare function formatShortcutKey(binding: ShortcutBinding): string;
+
+/**
+ * Estimates remux speed and ETA from a stream of progress values [0, 1].
+ *
+ * startTime is initialized lazily on the first update() call with progress > 0
+ * to avoid capturing bootstrap latency from the constructor.
+ *
+ * Usage:
+ *   const est = new ProgressEstimator(fileSizeBytes);
+ *   est.update(0.42); // call on each progress event
+ *   const { speedMBps, etaSeconds } = est.getEstimate();
+ */
+declare class ProgressEstimator {
+    private readonly fileSizeBytes;
+    private startTime;
+    private lastProgress;
+    constructor(fileSizeBytes: number);
+    update(progress: number): void;
+    getEstimate(): {
+        speedMBps: number;
+        etaSeconds: number | null;
+    };
+}
+
+declare function getFFmpeg(): Promise<FFmpeg>;
+declare function resetFFmpeg(): void;
+
+export { ASSRenderer, type AudioTrack, type AudioTrackMeta, CancellationError, type Chapter, DEFAULT_SHORTCUTS, 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, UniversalSubtitleManager, type VideoFilters, type VideoMetadata, type VideoPlayer, applyOffsetToVtt, captureVideoThumbnail, configureLightBird, createOffsetVttUrl, createVideoPlayer, exportPlaylist, extractNativeMetadata, formatShortcutKey, getFFmpeg, isInteractiveElement, loadShortcuts, matchesShortcut, parseChaptersFromFFmpegLog, parseChaptersFromVtt, parseM3U8, parseMediaError, resetFFmpeg, saveShortcuts, validateFile };