@lightbird/core 0.1.0

package/dist/react/index.d.cts

@@ -0,0 +1,252 @@
+import * as react from 'react';
+import { RefObject } from 'react';
+
+declare function useVideoPlayback(videoRef: RefObject<HTMLVideoElement | null>): {
+    isPlaying: boolean;
+    progress: number;
+    duration: number;
+    volume: number;
+    isMuted: boolean;
+    playbackRate: number;
+    loop: boolean;
+    togglePlay: () => void;
+    seek: (t: number) => void;
+    setVolume: (v: number) => void;
+    toggleMute: () => void;
+    setPlaybackRate: (r: number) => void;
+    frameStep: (direction: "forward" | "backward") => void;
+    toggleLoop: () => 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;
+}
+
+declare function useVideoFilters(videoRef: RefObject<HTMLVideoElement | null>): {
+    filters: VideoFilters;
+    zoom: number;
+    setFilters: react.Dispatch<react.SetStateAction<VideoFilters>>;
+    setZoom: react.Dispatch<react.SetStateAction<number>>;
+    resetFilters: () => void;
+};
+
+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;
+}
+
+interface UseSubtitlesOptions {
+    onError?: (message: string) => void;
+    onSuccess?: (message: string) => void;
+}
+declare function useSubtitles(options?: UseSubtitlesOptions): {
+    subtitles: Subtitle[];
+    activeSubtitle: string;
+    managerRef: react.MutableRefObject<UniversalSubtitleManager | null>;
+    initManager: (videoEl: HTMLVideoElement) => void;
+    importSubtitles: (subs: Subtitle[]) => void;
+    reset: () => void;
+    addSubtitleFiles: (files: File[]) => Promise<void>;
+    removeSubtitle: (id: string) => void;
+    switchSubtitle: (id: string) => void;
+};
+
+declare function usePlaylist(): {
+    playlist: PlaylistItem[];
+    currentIndex: number | null;
+    currentItem: PlaylistItem | null;
+    selectItem: (index: number) => void;
+    appendItem: (item: PlaylistItem) => void;
+    removeItem: (index: number) => void;
+    reorderItems: (newPlaylist: PlaylistItem[]) => void;
+    addFiles: (files: File[]) => Promise<{
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        name: string;
+        url: string;
+        type: "video";
+        file: File;
+        duration: number;
+    }[]>;
+    replaceWithFile: (file: File) => void;
+    nextItem: () => void;
+    prevItem: () => void;
+    parseFiles: (files: FileList) => {
+        videoFiles: File[];
+        subtitleFiles: File[];
+    };
+    setPlaylist: react.Dispatch<react.SetStateAction<PlaylistItem[]>>;
+    setCurrentIndex: react.Dispatch<react.SetStateAction<number | 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;
+    };
+}
+
+type ShortcutHandlers = Partial<Record<ShortcutAction, () => void>>;
+declare function useKeyboardShortcuts(shortcuts: ShortcutBinding[], handlers: ShortcutHandlers): void;
+
+declare function useFullscreen(containerRef: RefObject<HTMLDivElement | null>): {
+    isFullscreen: boolean;
+    toggle: () => void;
+};
+
+declare function usePictureInPicture(videoRef: RefObject<HTMLVideoElement | null>): {
+    isPiP: boolean;
+    isSupported: boolean;
+    enter: () => Promise<void>;
+    exit: () => Promise<void>;
+    toggle: () => Promise<void>;
+};
+
+declare function useProgressPersistence(videoRef: RefObject<HTMLVideoElement | null>, currentVideoName: string | null): void;
+
+declare function useVideoInfo(videoRef: RefObject<HTMLVideoElement | null>, currentFile: File | null): {
+    metadata: VideoMetadata | null;
+    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;
+    url: string;
+    externalSubtitles?: Subtitle[];
+}
+
+interface MKVPlayerFile {
+    name: string;
+    file: File;
+    videoUrl?: string;
+    audioTracks: AudioTrack[];
+    subtitleTracks: Subtitle[];
+    activeAudioTrack: string;
+    activeSubtitleTrack: string;
+}
+
+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 useChapters(videoRef: RefObject<HTMLVideoElement>, playerRef: RefObject<VideoPlayer | null>): {
+    chapters: Chapter[];
+    currentChapter: Chapter | null;
+    goToChapter: (index: number) => void;
+};
+
+export { type ShortcutHandlers, type UseMediaSessionOptions, type UseSubtitlesOptions, useChapters, useFullscreen, useKeyboardShortcuts, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSubtitles, useVideoFilters, useVideoInfo, useVideoPlayback };

package/dist/react/index.d.ts

@@ -0,0 +1,252 @@
+import * as react from 'react';
+import { RefObject } from 'react';
+
+declare function useVideoPlayback(videoRef: RefObject<HTMLVideoElement | null>): {
+    isPlaying: boolean;
+    progress: number;
+    duration: number;
+    volume: number;
+    isMuted: boolean;
+    playbackRate: number;
+    loop: boolean;
+    togglePlay: () => void;
+    seek: (t: number) => void;
+    setVolume: (v: number) => void;
+    toggleMute: () => void;
+    setPlaybackRate: (r: number) => void;
+    frameStep: (direction: "forward" | "backward") => void;
+    toggleLoop: () => 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;
+}
+
+declare function useVideoFilters(videoRef: RefObject<HTMLVideoElement | null>): {
+    filters: VideoFilters;
+    zoom: number;
+    setFilters: react.Dispatch<react.SetStateAction<VideoFilters>>;
+    setZoom: react.Dispatch<react.SetStateAction<number>>;
+    resetFilters: () => void;
+};
+
+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;
+}
+
+interface UseSubtitlesOptions {
+    onError?: (message: string) => void;
+    onSuccess?: (message: string) => void;
+}
+declare function useSubtitles(options?: UseSubtitlesOptions): {
+    subtitles: Subtitle[];
+    activeSubtitle: string;
+    managerRef: react.MutableRefObject<UniversalSubtitleManager | null>;
+    initManager: (videoEl: HTMLVideoElement) => void;
+    importSubtitles: (subs: Subtitle[]) => void;
+    reset: () => void;
+    addSubtitleFiles: (files: File[]) => Promise<void>;
+    removeSubtitle: (id: string) => void;
+    switchSubtitle: (id: string) => void;
+};
+
+declare function usePlaylist(): {
+    playlist: PlaylistItem[];
+    currentIndex: number | null;
+    currentItem: PlaylistItem | null;
+    selectItem: (index: number) => void;
+    appendItem: (item: PlaylistItem) => void;
+    removeItem: (index: number) => void;
+    reorderItems: (newPlaylist: PlaylistItem[]) => void;
+    addFiles: (files: File[]) => Promise<{
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        name: string;
+        url: string;
+        type: "video";
+        file: File;
+        duration: number;
+    }[]>;
+    replaceWithFile: (file: File) => void;
+    nextItem: () => void;
+    prevItem: () => void;
+    parseFiles: (files: FileList) => {
+        videoFiles: File[];
+        subtitleFiles: File[];
+    };
+    setPlaylist: react.Dispatch<react.SetStateAction<PlaylistItem[]>>;
+    setCurrentIndex: react.Dispatch<react.SetStateAction<number | 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;
+    };
+}
+
+type ShortcutHandlers = Partial<Record<ShortcutAction, () => void>>;
+declare function useKeyboardShortcuts(shortcuts: ShortcutBinding[], handlers: ShortcutHandlers): void;
+
+declare function useFullscreen(containerRef: RefObject<HTMLDivElement | null>): {
+    isFullscreen: boolean;
+    toggle: () => void;
+};
+
+declare function usePictureInPicture(videoRef: RefObject<HTMLVideoElement | null>): {
+    isPiP: boolean;
+    isSupported: boolean;
+    enter: () => Promise<void>;
+    exit: () => Promise<void>;
+    toggle: () => Promise<void>;
+};
+
+declare function useProgressPersistence(videoRef: RefObject<HTMLVideoElement | null>, currentVideoName: string | null): void;
+
+declare function useVideoInfo(videoRef: RefObject<HTMLVideoElement | null>, currentFile: File | null): {
+    metadata: VideoMetadata | null;
+    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;
+    url: string;
+    externalSubtitles?: Subtitle[];
+}
+
+interface MKVPlayerFile {
+    name: string;
+    file: File;
+    videoUrl?: string;
+    audioTracks: AudioTrack[];
+    subtitleTracks: Subtitle[];
+    activeAudioTrack: string;
+    activeSubtitleTrack: string;
+}
+
+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 useChapters(videoRef: RefObject<HTMLVideoElement>, playerRef: RefObject<VideoPlayer | null>): {
+    chapters: Chapter[];
+    currentChapter: Chapter | null;
+    goToChapter: (index: number) => void;
+};
+
+export { type ShortcutHandlers, type UseMediaSessionOptions, type UseSubtitlesOptions, useChapters, useFullscreen, useKeyboardShortcuts, useMediaSession, usePictureInPicture, usePlaylist, useProgressPersistence, useSubtitles, useVideoFilters, useVideoInfo, useVideoPlayback };