@goboss/web-video-player-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,463 @@
+import { default as default_2 } from 'react';
+
+export declare type AnalyticsCallback = (event: AnalyticsEvent) => void;
+
+export declare interface AnalyticsEvent {
+    eventType: 'play' | 'pause' | 'seek' | 'ended' | 'complete' | 'buffering_start' | 'buffering_end' | 'stall' | 'quality_change' | 'audio_track_change' | 'volume_change' | 'speed_change' | 'subtitle_change' | 'pip_toggle' | 'fullscreen_enter' | 'fullscreen_exit' | 'cast_start' | 'cast_stop' | 'error' | 'network_error' | 'session_start' | 'video_loaded' | 'first_quartile' | 'midpoint' | 'third_quartile' | 'heartbeat';
+    timestamp: number;
+    currentTime: number;
+    duration: number;
+    bitrate?: number;
+    rendition?: string;
+    fromRendition?: string;
+    volume?: number;
+    speed?: number;
+    errorMessage?: string;
+    errorCode?: number;
+    sessionId?: string;
+    videoId?: string;
+    deviceType?: string;
+    networkType?: string;
+    watchPercentage?: number;
+    totalWatchTime?: number;
+    bufferingCount?: number;
+    totalBufferingTime?: number;
+    seekFrom?: number;
+    pipState?: 'entered' | 'exited';
+}
+
+declare class AnalyticsModule {
+    private callback?;
+    private heartbeatInterval?;
+    private isBuffering;
+    private sessionId;
+    private videoId;
+    private deviceType;
+    private networkType;
+    private isFirstPlay;
+    private watchStartTime;
+    private totalWatchTime;
+    private bufferingCount;
+    private totalBufferingTime;
+    private bufferingStartTime;
+    private milestonesHit;
+    private lastHeartbeatPosition;
+    private lastHeartbeatAt;
+    constructor(callback?: AnalyticsCallback, src?: string);
+    registerCallback(callback: AnalyticsCallback): void;
+    track(eventType: AnalyticsEvent['eventType'], videoEl: HTMLVideoElement, extra?: Partial<AnalyticsEvent>): void;
+    startHeartbeat(videoEl: HTMLVideoElement, getExtra: () => Partial<AnalyticsEvent>): void;
+    stopHeartbeat(): void;
+    setBuffering(isBuffering: boolean, videoEl: HTMLVideoElement, getExtra: () => Partial<AnalyticsEvent>): void;
+    private checkMilestones;
+    private checkStall;
+    private dispatchRaw;
+    private generateSessionId;
+    private extractVideoId;
+    private getDeviceType;
+    private getNetworkType;
+}
+
+declare class CastingModule {
+    private isCasting;
+    private castDeviceName;
+    private onCastStateChangeCallback?;
+    private castContext;
+    private remotePlayer;
+    private remotePlayerController;
+    constructor();
+    private initCastApi;
+    getCastingState(): {
+        isCasting: boolean;
+        deviceName: string;
+    };
+    /**
+     * Prompts the native Google Cast device picker overlay.
+     */
+    requestSession(currentSrc: string, currentTime: number): Promise<void>;
+    /**
+     * Disconnects the current cast session.
+     */
+    stopCasting(): void;
+    onCastStateChange(callback: (isCasting: boolean, deviceName: string) => void): void;
+    requestAirPlaySession(videoElement: HTMLVideoElement): void;
+    stopAirPlay(videoElement: HTMLVideoElement): void;
+    isAirPlayAvailable(): boolean;
+}
+
+export declare interface Chapter {
+    title: string;
+    startTime: number;
+    endTime: number;
+    thumbnail?: string;
+}
+
+declare class ChaptersModule extends KeyMomentsModule {
+}
+
+/**
+ * Mounts the full video player (React UI + all controls) into any DOM element.
+ * Use this in Vue, Angular, Vanilla JS, or any environment where JSX is unavailable.
+ *
+ * @example Vanilla JS
+ *   const player = createPlayer(document.getElementById('player'), { src: 'https://...' });
+ *   player.destroy(); // cleanup
+ *
+ * @example Vue 3
+ *   const player = createPlayer(containerRef.value, { src: props.src });
+ *   onUnmounted(() => player.destroy());
+ *
+ * @example Angular
+ *   const player = createPlayer(this.containerRef.nativeElement, { src: this.src });
+ *   ngOnDestroy() { this.player.destroy(); }
+ */
+export declare function createPlayer(container: HTMLElement, props: PlayerProps): PlayerInstance;
+
+export declare interface DRMConfig {
+    widevineLicenseUrl?: string;
+    playreadyLicenseUrl?: string;
+    fairplayLicenseUrl?: string;
+    authToken?: string;
+    allowedDomains?: string[];
+    watermarkText?: string;
+}
+
+declare class DRMModule {
+    private config?;
+    private watermarkElement?;
+    private floatInterval?;
+    constructor(config?: DRMConfig);
+    /**
+     * Validates if the active origin domain is permitted to load this stream asset.
+     */
+    validateDomain(currentDomain: string): boolean;
+    getAuthToken(): string | undefined;
+    /**
+     * Injects an animated floating watermark on top of the media container to obstruct piracy or recording.
+     */
+    setupWatermark(container: HTMLElement): void;
+    /**
+     * Cleans up active watermarks.
+     */
+    removeWatermark(): void;
+    isDRMProtected(): boolean;
+    getDRMDetails(): {
+        widevine: string | null;
+        playready: string | null;
+        fairplay: string | null;
+        authTokenPresent: boolean;
+        allowedDomains: string[];
+    };
+}
+
+/**
+ * Sends all player analytics events to Firebase Analytics (GA4).
+ *
+ * Events appear in:
+ *   Firebase Console → Analytics → Events       (24-48 hr aggregated view)
+ *   Firebase Console → Analytics → DebugView    (real-time while testing)
+ *   Google Analytics 4 → Reports → Realtime     (within a few minutes)
+ *
+ * No Firestore / database setup required — Firebase Analytics handles all storage.
+ */
+export declare class FirebaseAnalyticsProvider {
+    private analytics;
+    constructor(config: FirebaseConfig);
+    private init;
+    createCallback(): AnalyticsCallback;
+    private handleEvent;
+    private buildParams;
+    destroy(): Promise<void>;
+}
+
+export declare interface FirebaseConfig {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+    storageBucket: string;
+    messagingSenderId: string;
+    appId: string;
+    measurementId?: string;
+}
+
+export declare type KeyMoment = Chapter;
+
+declare class KeyMomentsModule {
+    private keyMoments;
+    private currentMomentIndex;
+    private onMomentChangeCallback?;
+    constructor(keyMoments?: KeyMoment[]);
+    /**
+     * Sorts and stores the key moments.
+     */
+    setKeyMoments(keyMoments: KeyMoment[]): void;
+    getKeyMoments(): KeyMoment[];
+    /**
+     * Locates the key moment corresponding to the active playback timestamp.
+     */
+    getCurrentMoment(currentTime: number): {
+        keyMoment: KeyMoment | null;
+        index: number;
+    };
+    /**
+     * Evaluates if playback has crossed a key moment boundary.
+     */
+    updateTime(currentTime: number): void;
+    /**
+     * Subscribes a callback to change events.
+     */
+    onMomentChange(callback: (keyMoment: KeyMoment | null, index: number) => void): void;
+    setChapters(chapters: KeyMoment[]): void;
+    getChapters(): KeyMoment[];
+    getCurrentChapter(currentTime: number): {
+        chapter: KeyMoment | null;
+        index: number;
+    };
+    onChapterChange(callback: (chapter: KeyMoment | null, index: number) => void): void;
+}
+
+export declare interface PlayerInstance {
+    /** Re-render the player with updated props (src change, theme, etc.) */
+    update(props: Partial<PlayerProps>): void;
+    /** Unmounts the player and releases all resources */
+    destroy(): void;
+}
+
+/**
+ * Props accepted by createPlayer — mirrors WebVideoPlayerProps so all
+ * framework wrappers (Vue, Angular, Vanilla JS) share the same API surface.
+ */
+export declare interface PlayerProps {
+    src: string;
+    chapters?: Chapter[];
+    keyMoments?: KeyMoment[];
+    subtitles?: SubtitleTrack[];
+    watermark?: string;
+    themeColor?: string;
+    drmConfig?: any;
+    firebaseConfig?: FirebaseConfig;
+    onAnalyticsEvent?: (event: AnalyticsEvent) => void;
+    onKeyMomentsLoaded?: (keyMoments: KeyMoment[]) => void;
+    enableControls?: boolean;
+    enableChromecast?: boolean;
+    enableKeyMoments?: boolean;
+    enableSubtitles?: boolean;
+    enableQuality?: boolean;
+    enablePlaybackSpeed?: boolean;
+    enablePiP?: boolean;
+    enableFullscreen?: boolean;
+}
+
+export declare interface PlayerSDKOptions {
+    container: HTMLElement;
+    src: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+    chapters?: Chapter[];
+    keyMoments?: KeyMoment[];
+    subtitles?: SubtitleTrack[];
+    thumbnails?: ThumbnailConfig;
+    drm?: DRMConfig;
+    analyticsCallback?: AnalyticsCallback;
+    themeColor?: string;
+    watermark?: string;
+}
+
+declare class SubtitlesModule {
+    private tracks;
+    private activeTrackId;
+    private currentCues;
+    private activeText;
+    private onSubtitleChangeCallback?;
+    private onTrackSwitchCallback?;
+    constructor(tracks?: SubtitleTrack[]);
+    getTracks(): SubtitleTrack[];
+    getActiveTrackId(): string;
+    setHlsTracks(hlsTracks: SubtitleTrack[]): void;
+    addTrack(track: SubtitleTrack): void;
+    onTrackSwitch(callback: (track: SubtitleTrack | null) => void): void;
+    setCustomSubtitleText(text: string): void;
+    /**
+     * Switches the active track. Fetches external tracks if they need loading.
+     */
+    setActiveTrack(trackId: string): Promise<void>;
+    /**
+     * Scans the subtitle cues for the current playback position.
+     */
+    updateTime(currentTime: number): void;
+    /**
+     * Triggers the text update callback if a change in caption is detected.
+     */
+    private updateActiveText;
+    onSubtitleChange(callback: (text: string) => void): void;
+    /**
+     * Robust parser supporting WebVTT and SRT formats.
+     */
+    private parseVttOrSrt;
+}
+
+declare interface SubtitleStyle {
+    size?: 'small' | 'medium' | 'large';
+    background?: 'none' | 'dim' | 'solid';
+    color?: string;
+}
+
+export declare interface SubtitleTrack {
+    id: string;
+    label: string;
+    lang: string;
+    src?: string;
+    isDefault?: boolean;
+    cues?: Array<{
+        startTime: number;
+        endTime: number;
+        text: string;
+    }>;
+    isHls?: boolean;
+    hlsTrackId?: number;
+    isNative?: boolean;
+    nativeTrackIndex?: number;
+}
+
+export declare interface ThumbnailConfig {
+    spriteUrl: string;
+    tileWidth: number;
+    tileHeight: number;
+    columns: number;
+    rows: number;
+    interval: number;
+    totalCount: number;
+}
+
+declare class ThumbnailsModule {
+    private config?;
+    constructor(config?: ThumbnailConfig);
+    /**
+     * Calculates the position offset inside the sprite sheet for a given seek hover time.
+     */
+    getThumbnail(time: number): {
+        url: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    hasThumbnails(): boolean;
+}
+
+export declare class VideoPlayerSDK {
+    private options;
+    private videoElement;
+    private hlsInstance;
+    private dashInstance;
+    private activeQuality;
+    private qualityLevels;
+    analytics: AnalyticsModule;
+    keyMoments: KeyMomentsModule;
+    chapters: ChaptersModule;
+    subtitles: SubtitlesModule;
+    drm: DRMModule;
+    casting: CastingModule;
+    thumbnails: ThumbnailsModule;
+    private hlsSubtitleCues;
+    private hlsActiveSubtitleKey;
+    private audioTrackList;
+    private eventListeners;
+    constructor(options: PlayerSDKOptions);
+    /**
+     * Builds the video DOM hierarchy, binds events, validates domain restrictions, and mounts DRM watermarks.
+     */
+    private initializePlayer;
+    /**
+     * Binds direct event listeners to the native HTML5 Video tag, routing them to our sub-packages.
+     */
+    private bindMediaEvents;
+    private rewriteToProxy;
+    /**
+     * Initializes HLS adaptive streaming through Hls.js or falls back to native browser playback.
+     */
+    private loadSource;
+    /**
+     * Sets up global lock-screen metadata and media control keys (Media Session API).
+     */
+    private setupBackgroundControls;
+    play(): void;
+    pause(): void;
+    seek(seconds: number): void;
+    setVolume(volume: number): void;
+    setMute(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    /**
+     * Sets manual video quality rendition or switches back to auto bitrate scaling.
+     */
+    setQuality(qualityId: number): void;
+    /**
+     * Activates native Picture-in-Picture floating viewport.
+     */
+    togglePictureInPicture(): Promise<boolean>;
+    /**
+     * Requests element-level fullscreen.
+     */
+    toggleFullscreen(): void;
+    getVideoElement(): HTMLVideoElement;
+    getCurrentTime(): number;
+    getDuration(): number;
+    getVolume(): number;
+    isMuted(): boolean;
+    getPlaybackRate(): number;
+    getActiveQuality(): VideoQuality;
+    getQualityLevels(): VideoQuality[];
+    getBufferLength(): number;
+    getBufferedRanges(): Array<{
+        start: number;
+        end: number;
+    }>;
+    private getAnalyticsPayload;
+    on(event: string, callback: (...args: any[]) => void): void;
+    off(event: string, callback: (...args: any[]) => void): void;
+    private emit;
+    private extractSubtitlesFromManifest;
+    private extractKeyMomentsFromManifest;
+    getAudioTracks(): Array<{
+        id: number;
+        label: string;
+        lang: string;
+    }>;
+    setAudioTrack(id: number): void;
+    destroy(): void;
+}
+
+export declare interface VideoQuality {
+    id: number;
+    height: number;
+    width: number;
+    bitrate: number;
+    label: string;
+}
+
+export declare const WebVideoPlayer: default_2.FC<WebVideoPlayerProps>;
+
+declare interface WebVideoPlayerProps {
+    src: string;
+    chapters?: Chapter[];
+    keyMoments?: KeyMoment[];
+    subtitles?: SubtitleTrack[];
+    watermark?: string;
+    themeColor?: string;
+    drmConfig?: any;
+    firebaseConfig?: FirebaseConfig;
+    onAnalyticsEvent?: (event: AnalyticsEvent) => void;
+    onKeyMomentsLoaded?: (keyMoments: KeyMoment[]) => void;
+    enableControls?: boolean;
+    enableChromecast?: boolean;
+    enableKeyMoments?: boolean;
+    enableSubtitles?: boolean;
+    enableQuality?: boolean;
+    enablePlaybackSpeed?: boolean;
+    enablePiP?: boolean;
+    enableFullscreen?: boolean;
+    subtitleStyle?: SubtitleStyle;
+}
+
+export { }