@livepeer-frameworks/player-core 0.0.3

package/dist/types/core/PlayerController.d.ts

@@ -0,0 +1,665 @@
+/**
+ * PlayerController.ts
+ *
+ * Main headless orchestrator for the player. This class encapsulates all business logic
+ * (gateway resolution, stream state polling, player selection/initialization) in a
+ * framework-agnostic manner.
+ *
+ * Both React and Vanilla wrappers use this class internally.
+ */
+import { TypedEventEmitter } from './EventEmitter';
+import { PlayerManager } from './PlayerManager';
+import { type LatencyTier, type LiveThresholds } from './SeekingUtils';
+import type { ABRMode, PlaybackQuality, ContentType } from '../types';
+import type { ContentEndpoints, ContentMetadata, PlayerState, PlayerStateContext, StreamState } from '../types';
+import type { StreamInfo, StreamSource, IPlayer } from './PlayerInterface';
+export interface PlayerControllerConfig {
+    /** Content identifier (stream name) */
+    contentId: string;
+    /** Content type */
+    contentType: ContentType;
+    /** Pre-resolved endpoints (skip gateway) */
+    endpoints?: ContentEndpoints;
+    /** Gateway URL (for FrameWorks Gateway resolution) */
+    gatewayUrl?: string;
+    /** Direct MistServer base URL (bypasses Gateway, fetches json_{contentId}.js directly) */
+    mistUrl?: string;
+    /** Auth token for private streams */
+    authToken?: string;
+    /** Playback options */
+    autoplay?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+    poster?: string;
+    /** Debug logging */
+    debug?: boolean;
+    /** Custom PlayerManager instance (optional, uses global by default) */
+    playerManager?: PlayerManager;
+    /** Force a specific player (e.g., 'hlsjs', 'dashjs', 'native') */
+    forcePlayer?: string;
+    /** Force a specific MIME type (e.g., 'html5/application/vnd.apple.mpegurl') */
+    forceType?: string;
+    /** Force a specific source index */
+    forceSource?: number;
+    /** Playback mode preference */
+    playbackMode?: 'auto' | 'low-latency' | 'quality' | 'vod';
+}
+export interface PlayerControllerEvents {
+    /** Player state changed */
+    stateChange: {
+        state: PlayerState;
+        context?: PlayerStateContext;
+    };
+    /** Stream state changed (for live streams) */
+    streamStateChange: {
+        state: StreamState;
+    };
+    /** Time update during playback */
+    timeUpdate: {
+        currentTime: number;
+        duration: number;
+    };
+    /** Error occurred */
+    error: {
+        error: string;
+        code?: string;
+    };
+    /** Error was cleared (auto-cleared or manually) */
+    errorCleared: void;
+    /** Player ready with video element */
+    ready: {
+        videoElement: HTMLVideoElement;
+    };
+    /** Controller destroyed */
+    destroyed: void;
+    /** Player/source was selected */
+    playerSelected: {
+        player: string;
+        source: StreamSource;
+        score: number;
+    };
+    /** Quality level changed (ABR switch) */
+    qualityChanged: {
+        fromLevel?: string;
+        toLevel: string;
+    };
+    /** Volume or mute state changed */
+    volumeChange: {
+        volume: number;
+        muted: boolean;
+    };
+    /** Fullscreen state changed */
+    fullscreenChange: {
+        isFullscreen: boolean;
+    };
+    /** Picture-in-Picture state changed */
+    pipChange: {
+        isPiP: boolean;
+    };
+    /** Loop mode changed */
+    loopChange: {
+        isLoopEnabled: boolean;
+    };
+    /** Playback rate changed */
+    speedChange: {
+        rate: number;
+    };
+    /** User skipped forward */
+    skipForward: {
+        seconds: number;
+    };
+    /** User skipped backward */
+    skipBackward: {
+        seconds: number;
+    };
+    /** Speed hold started (hold-for-2x gesture) */
+    holdSpeedStart: {
+        speed: number;
+    };
+    /** Speed hold ended */
+    holdSpeedEnd: void;
+    /** Captions/subtitles toggled */
+    captionsChange: {
+        enabled: boolean;
+    };
+    /** Seeking/live state changed - emitted on timeupdate when values change */
+    seekingStateChange: {
+        seekableStart: number;
+        liveEdge: number;
+        canSeek: boolean;
+        isNearLive: boolean;
+        isLive: boolean;
+        isWebRTC: boolean;
+        latencyTier: LatencyTier;
+        buffered: TimeRanges | null;
+        hasAudio: boolean;
+        supportsPlaybackRate: boolean;
+    };
+    /** User started hovering over player */
+    hoverStart: void;
+    /** User stopped hovering (after timeout) */
+    hoverEnd: void;
+    /** User became idle (no interaction for N seconds) */
+    interactionIdle: void;
+    /** User resumed interaction after being idle */
+    interactionActive: void;
+    /** Playback metadata updated */
+    metadataUpdate: {
+        currentTime: number;
+        duration: number;
+        bufferedAhead: number;
+        qualityScore?: number;
+        playerInfo?: {
+            name: string;
+            shortname: string;
+        };
+        sourceInfo?: {
+            url: string;
+            type: string;
+        };
+        isLive: boolean;
+        isBuffering: boolean;
+        isPaused: boolean;
+        volume: number;
+        muted: boolean;
+    };
+}
+/**
+ * Complete MistServer source type mapping
+ * Maps MistServer's `source[].type` field to player selection info
+ *
+ * type field = MIME type used for player selection
+ * hrn = human readable name for UI
+ * player = recommended player implementation
+ * supported = whether we have a working player for it
+ */
+export declare const MIST_SOURCE_TYPES: Record<string, {
+    hrn: string;
+    player: string;
+    supported: boolean;
+}>;
+/**
+ * Map Gateway protocol names to MistServer MIME types
+ * Gateway outputs use simplified protocol names like "HLS", "WHEP"
+ * while MistServer uses full MIME types
+ */
+export declare const PROTOCOL_TO_MIME: Record<string, string>;
+/**
+ * Get the MIME type for a Gateway protocol name
+ */
+export declare function getMimeTypeForProtocol(protocol: string): string;
+/**
+ * Get source type info for a MIME type
+ */
+export declare function getSourceTypeInfo(mimeType: string): {
+    hrn: string;
+    player: string;
+    supported: boolean;
+} | undefined;
+/**
+ * Build StreamInfo from Gateway ContentEndpoints.
+ *
+ * This function extracts playback sources and track information from
+ * the Gateway's resolved endpoint data. It handles:
+ * - Parsing `outputs` JSON string (GraphQL returns JSON scalar as string)
+ * - Converting output protocols to StreamSource format
+ * - Deriving track info from capabilities
+ *
+ * Use this for VOD/clip content where Gateway data is sufficient,
+ * without waiting for MistServer to load the stream.
+ *
+ * @param endpoints - ContentEndpoints from Gateway resolution
+ * @param contentId - Stream/content identifier
+ * @returns StreamInfo with sources and tracks, or null if no valid data
+ */
+export declare function buildStreamInfoFromEndpoints(endpoints: ContentEndpoints, contentId: string): StreamInfo | null;
+/**
+ * Headless player controller that manages the entire player lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const controller = new PlayerController({
+ *   contentId: 'my-stream',
+ *   contentType: 'live',
+ *   gatewayUrl: 'https://gateway.example.com/graphql',
+ * });
+ *
+ * controller.on('stateChange', ({ state }) => console.log('State:', state));
+ * controller.on('ready', ({ videoElement }) => console.log('Ready!'));
+ *
+ * const container = document.getElementById('player');
+ * await controller.attach(container);
+ *
+ * // Later...
+ * controller.destroy();
+ * ```
+ */
+export declare class PlayerController extends TypedEventEmitter<PlayerControllerEvents> {
+    private config;
+    private state;
+    private lastEmittedState;
+    private gatewayClient;
+    private streamStateClient;
+    private playerManager;
+    private currentPlayer;
+    private videoElement;
+    private container;
+    private endpoints;
+    private streamInfo;
+    private streamState;
+    /** Tracks parsed from MistServer JSON response (used for direct MistServer mode) */
+    private mistTracks;
+    private cleanupFns;
+    private isDestroyed;
+    private isAttached;
+    private _isBuffering;
+    private _hasPlaybackStarted;
+    private _errorText;
+    private _isPassiveError;
+    private _isHoldingSpeed;
+    private _holdSpeed;
+    private _isLoopEnabled;
+    private _currentPlayerInfo;
+    private _currentSourceInfo;
+    private _pendingForceOptions;
+    private _errorShownAt;
+    private _errorCleared;
+    private _isTransitioning;
+    private _errorCount;
+    private _lastErrorTime;
+    private _prevStreamIsOnline;
+    private _isHovering;
+    private _hoverTimeout;
+    private static readonly HOVER_HIDE_DELAY_MS;
+    private static readonly HOVER_LEAVE_DELAY_MS;
+    private _subtitlesEnabled;
+    private _stallStartTime;
+    private static readonly HARD_FAILURE_STALL_THRESHOLD_MS;
+    private _seekableStart;
+    private _liveEdge;
+    private _canSeek;
+    private _isNearLive;
+    private _latencyTier;
+    private _liveThresholds;
+    private _buffered;
+    private _hasAudio;
+    private _supportsPlaybackRate;
+    private _isWebRTC;
+    private static readonly AUTO_CLEAR_ERROR_DELAY_MS;
+    private static readonly HARD_FAILURE_ERROR_THRESHOLD;
+    private static readonly HARD_FAILURE_ERROR_WINDOW_MS;
+    private static readonly FATAL_ERROR_KEYWORDS;
+    private abrController;
+    private interactionController;
+    private mistReporter;
+    private qualityMonitor;
+    private metaTrackManager;
+    private _playbackQuality;
+    private bootMs;
+    constructor(config: PlayerControllerConfig);
+    /**
+     * Attach to a container element and start the player lifecycle.
+     * This is the main entry point after construction.
+     */
+    attach(container: HTMLElement): Promise<void>;
+    /**
+     * Detach from the current container and clean up resources.
+     * The controller can be re-attached to a new container.
+     */
+    detach(): void;
+    /**
+     * Fully destroy the controller. Cannot be reused after this.
+     */
+    destroy(): void;
+    /** Get current player state */
+    getState(): PlayerState;
+    /** Get current stream state (for live streams) */
+    getStreamState(): StreamState | null;
+    /** Get resolved endpoints */
+    getEndpoints(): ContentEndpoints | null;
+    /** Get content metadata (title, description, duration, etc.) */
+    getMetadata(): ContentMetadata | null;
+    /** Get stream info (sources + tracks for player selection) */
+    getStreamInfo(): StreamInfo | null;
+    /** Get video element (null if not ready) */
+    getVideoElement(): HTMLVideoElement | null;
+    /** Get current player instance */
+    getPlayer(): IPlayer | null;
+    /** Check if player is ready */
+    isReady(): boolean;
+    /** Check if video is currently playing (not paused) */
+    isPlaying(): boolean;
+    /** Check if currently buffering */
+    isBuffering(): boolean;
+    /** Get current error message (null if no error) */
+    getError(): string | null;
+    /** Check if error is passive (video still playing despite error) */
+    isPassiveError(): boolean;
+    /** Check if playback has ever started (for idle screen logic) */
+    hasPlaybackStarted(): boolean;
+    /** Check if currently holding for speed boost */
+    isHoldingSpeed(): boolean;
+    /** Get current hold speed value */
+    getHoldSpeed(): number;
+    /** Get current player implementation info */
+    getCurrentPlayerInfo(): {
+        name: string;
+        shortname: string;
+    } | null;
+    /** Get current source info (URL and type) */
+    getCurrentSourceInfo(): {
+        url: string;
+        type: string;
+    } | null;
+    /** Get current volume (0-1) */
+    getVolume(): number;
+    /** Check if loop mode is enabled */
+    isLoopEnabled(): boolean;
+    /** Check if subtitles/captions are enabled */
+    isSubtitlesEnabled(): boolean;
+    /** Set subtitles/captions enabled state */
+    setSubtitlesEnabled(enabled: boolean): void;
+    /** Toggle subtitles/captions */
+    toggleSubtitles(): void;
+    /** Get start of seekable range (seconds) */
+    getSeekableStart(): number;
+    /** Get live edge / end of seekable range (seconds) */
+    getLiveEdge(): number;
+    /** Check if seeking is currently available */
+    canSeekStream(): boolean;
+    /** Check if playback is near the live edge (for live badge display) */
+    isNearLive(): boolean;
+    /** Get buffered ranges, preferring player override when available */
+    getBufferedRanges(): TimeRanges | null;
+    /** Get current latency tier based on protocol */
+    getLatencyTier(): LatencyTier;
+    /** Get live thresholds for entering/exiting "LIVE" state */
+    getLiveThresholds(): LiveThresholds;
+    /** Get buffered time ranges */
+    getBuffered(): TimeRanges | null;
+    /** Check if stream has audio track */
+    hasAudioTrack(): boolean;
+    /** Check if playback rate adjustment is supported */
+    canAdjustPlaybackRate(): boolean;
+    /** Check if source is WebRTC/MediaStream */
+    isWebRTCSource(): boolean;
+    /** Check if currently in fullscreen mode */
+    isFullscreen(): boolean;
+    /** Check if content is effectively live (live or DVR still recording) */
+    isEffectivelyLive(): boolean;
+    /** Check if content is strictly live (not DVR/clip/vod) */
+    isLive(): boolean;
+    /**
+     * Check if content needs cold start (VOD-like loading).
+     * True for: clips, DVR (recording OR completed) - any stored/VOD content
+     * False for: live streams only (real-time MistServer stream)
+     * DVR-while-recording needs cold start because MistServer may not be serving the VOD yet
+     */
+    needsColdStart(): boolean;
+    /**
+     * Check if we should show idle/loading screen.
+     * Logic:
+     * - For cold start content (VOD/DVR): Show loading only while waiting for Gateway sources
+     * - For live streams: Show loading while waiting for MistServer to come online
+     * - Never show idle after playback has started (unless explicit error)
+     */
+    shouldShowIdleScreen(): boolean;
+    /**
+     * Get the effective content type for playback mode selection.
+     * This ensures WHEP/WebRTC gets penalized for VOD content (no seek support)
+     * while HLS/MP4 are preferred for clips and completed DVR recordings.
+     */
+    getEffectiveContentType(): 'live' | 'vod';
+    /** Check if user is currently hovering over the player */
+    isHovering(): boolean;
+    /**
+     * Check if controls should be visible.
+     * Controls are visible when:
+     * - User is hovering over the player
+     * - Video is paused
+     * - There's an error
+     */
+    shouldShowControls(): boolean;
+    /**
+     * Handle mouse enter event - show controls immediately.
+     * Call this from your UI wrapper's onMouseEnter handler.
+     */
+    handleMouseEnter(): void;
+    /**
+     * Handle mouse leave event - hide controls after delay.
+     * Call this from your UI wrapper's onMouseLeave handler.
+     */
+    handleMouseLeave(): void;
+    /**
+     * Handle mouse move event - show controls and reset hide timer.
+     * Call this from your UI wrapper's onMouseMove handler.
+     */
+    handleMouseMove(): void;
+    /**
+     * Handle touch start event - show controls.
+     * Call this from your UI wrapper's onTouchStart handler.
+     */
+    handleTouchStart(): void;
+    /** Clear hover timeout */
+    private clearHoverTimeout;
+    /** Get current playback rate */
+    getPlaybackRate(): number;
+    /** Get playback quality metrics from QualityMonitor */
+    getPlaybackQuality(): PlaybackQuality | null;
+    /** Get current ABR mode */
+    getABRMode(): ABRMode;
+    /** Set ABR mode at runtime */
+    setABRMode(mode: ABRMode): void;
+    /** Start playback */
+    play(): Promise<void>;
+    /** Pause playback */
+    pause(): void;
+    /** Seek to time */
+    seek(time: number): void;
+    /** Set volume (0-1) */
+    setVolume(volume: number): void;
+    /** Set muted state */
+    setMuted(muted: boolean): void;
+    /** Set playback rate */
+    setPlaybackRate(rate: number): void;
+    /** Jump to live edge (for live streams) */
+    jumpToLive(): void;
+    /** Emit current seeking state */
+    private emitSeekingState;
+    /** Request fullscreen */
+    requestFullscreen(): Promise<void>;
+    /** Request Picture-in-Picture */
+    requestPiP(): Promise<void>;
+    /** Get available quality levels */
+    getQualities(): Array<{
+        id: string;
+        label: string;
+        bitrate?: number;
+        width?: number;
+        height?: number;
+        isAuto?: boolean;
+        active?: boolean;
+    }>;
+    /** Select a quality level */
+    selectQuality(id: string): void;
+    /** Get available text tracks */
+    getTextTracks(): Array<{
+        id: string;
+        label: string;
+        lang?: string;
+        active: boolean;
+    }>;
+    /** Select a text track */
+    selectTextTrack(id: string | null): void;
+    private getEffectiveCurrentTime;
+    private getEffectiveDuration;
+    private getPlayerSeekableRange;
+    private deriveBufferWindowMsFromTracks;
+    /** Get current time */
+    getCurrentTime(): number;
+    /** Get duration */
+    getDuration(): number;
+    /** Check if paused */
+    isPaused(): boolean;
+    /** Check if muted */
+    isMuted(): boolean;
+    /** Skip backward by specified seconds (default 10) */
+    skipBack(seconds?: number): void;
+    /** Skip forward by specified seconds (default 10) */
+    skipForward(seconds?: number): void;
+    /** Toggle play/pause */
+    togglePlay(): void;
+    /** Toggle mute */
+    toggleMute(): void;
+    /** Seek relative to current position */
+    seekBy(delta: number): void;
+    /** Seek to percentage (0-1) of duration */
+    seekPercent(percent: number): void;
+    /** Toggle loop mode */
+    toggleLoop(): void;
+    /** Set loop mode */
+    setLoopEnabled(enabled: boolean): void;
+    /** Clear current error */
+    clearError(): void;
+    /**
+     * Update seeking and live detection state.
+     * Called on timeupdate and progress events.
+     * Emits seekingStateChange event when values change.
+     */
+    private updateSeekingState;
+    /**
+     * Detect audio tracks on the video element.
+     * Called after video metadata is loaded.
+     */
+    private detectAudioTracks;
+    /**
+     * Attempt to clear error automatically if playback is progressing.
+     * Called on timeupdate, playing, and canplay events.
+     */
+    private attemptClearError;
+    /**
+     * Check if we should attempt playback fallback due to hard failure.
+     * Returns true if:
+     * - Error count exceeds threshold (5+) within time window (60s)
+     * - Error contains fatal keywords
+     * - Sustained stall for 30+ seconds
+     */
+    private shouldAttemptFallback;
+    /**
+     * Set error with passive mode support.
+     * - Ignores errors during player transitions
+     * - Marks error as passive if video is still playing
+     * - Attempts automatic fallback on hard failures
+     */
+    setPassiveError(error: string): Promise<void>;
+    /**
+     * Retry playback with fallback to next player/source.
+     * Returns true if a fallback option was available and attempted.
+     */
+    retryWithFallback(): Promise<boolean>;
+    /** Toggle fullscreen */
+    toggleFullscreen(): Promise<void>;
+    /** Toggle Picture-in-Picture */
+    togglePictureInPicture(): Promise<void>;
+    /** Check if Picture-in-Picture is supported */
+    isPiPSupported(): boolean;
+    /** Check if currently in Picture-in-Picture mode */
+    isPiPActive(): boolean;
+    /** Force a retry of the current playback */
+    retry(): Promise<void>;
+    /** Get playback statistics */
+    getStats(): Promise<unknown>;
+    /** Get current latency (for live streams) */
+    getLatency(): Promise<unknown>;
+    /**
+     * Update configuration at runtime without full re-initialization.
+     * Only certain options can be updated without re-init.
+     */
+    updateConfig(partialConfig: Partial<Pick<PlayerControllerConfig, 'debug' | 'autoplay' | 'muted'>>): void;
+    /**
+     * Force a complete re-initialization with current config.
+     * Stops and re-initializes the entire player.
+     */
+    reload(): Promise<void>;
+    /**
+     * Select a specific player/source combination (one-shot).
+     * Used by DevModePanel to manually pick a combo.
+     *
+     * Note: This is a ONE-SHOT selection. The force settings are used for
+     * the next initialization only. If that player fails, normal fallback
+     * logic proceeds without the force settings.
+     */
+    selectCombo(options: {
+        forcePlayer?: string;
+        forceType?: string;
+        forceSource?: number;
+    }): Promise<void>;
+    /**
+     * Set playback mode preference.
+     * Unlike selectCombo, this is a persistent preference that affects scoring.
+     */
+    setPlaybackMode(mode: 'auto' | 'low-latency' | 'quality' | 'vod'): void;
+    /**
+     * @deprecated Use selectCombo() for one-shot selection or setPlaybackMode() for mode changes.
+     * This method exists for backwards compatibility but may override fallback behavior.
+     */
+    setDevModeOptions(options: {
+        forcePlayer?: string;
+        forceType?: string;
+        forceSource?: number;
+        playbackMode?: 'auto' | 'low-latency' | 'quality' | 'vod';
+    }): Promise<void>;
+    /**
+     * Get metadata update payload for external consumers.
+     * Combines current state into a single metadata object.
+     */
+    getMetadataPayload(): PlayerControllerEvents['metadataUpdate'];
+    /**
+     * Emit a metadata update event with current state.
+     * Useful for periodic telemetry/reporting.
+     */
+    emitMetadataUpdate(): void;
+    private resolveEndpoints;
+    /**
+     * Resolve endpoints directly from MistServer (bypasses Gateway)
+     * Fetches json_{contentId}.js and builds ContentEndpoints from source array
+     */
+    private resolveFromMistServer;
+    /**
+     * Map MistServer type to protocol identifier
+     */
+    private mapMistTypeToProtocol;
+    /**
+     * Select best source based on protocol priority
+     */
+    private selectBestSource;
+    /**
+     * Resolve endpoints from Gateway GraphQL API
+     */
+    private resolveFromGateway;
+    private startStreamStatePolling;
+    /**
+     * Initialize player late when stream comes online after initial attach failed.
+     * Uses MistStreamInfo from stream state polling instead of re-fetching.
+     */
+    private initializeLateFromStreamState;
+    private buildStreamInfo;
+    /**
+     * Parse MistServer track metadata from the tracks object.
+     * MistServer returns tracks as a Record keyed by track name (e.g., "video_H264_800x600_25fps_1").
+     * This converts to our StreamTrack[] format with codecstring and init data.
+     */
+    private parseMistTracks;
+    private initializePlayer;
+    private setupVideoEventListeners;
+    private initializeSubControllers;
+    private initializeABRController;
+    private initializeQualityMonitor;
+    private initializeInteractionController;
+    private initializeMistReporter;
+    private initializeMetaTrackManager;
+    private cleanup;
+    private setState;
+    private log;
+}
+export default PlayerController;