@livepeer-frameworks/player-core 0.0.3

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

@@ -0,0 +1,230 @@
+/**
+ * Common Player Interface
+ *
+ * All player implementations must implement this interface to ensure
+ * consistent behavior and enable the PlayerManager selection system
+ */
+export interface StreamSource {
+    url: string;
+    type: string;
+    index?: number;
+    streamName?: string;
+    mistPlayerUrl?: string;
+}
+export interface StreamTrack {
+    type: 'video' | 'audio' | 'meta';
+    codec: string;
+    codecstring?: string;
+    init?: string;
+    /** Track index from MistServer (used for binary chunk routing) */
+    idx?: number;
+    width?: number;
+    height?: number;
+    fpks?: number;
+    channels?: number;
+    rate?: number;
+    size?: number;
+}
+export interface StreamInfo {
+    source: StreamSource[];
+    meta: {
+        tracks: StreamTrack[];
+    };
+    type?: 'live' | 'vod';
+}
+export interface PlayerOptions {
+    autoplay?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+    loop?: boolean;
+    poster?: string;
+    width?: number;
+    height?: number;
+    /** Enable dev mode - for Legacy player, uses MistServer's dev skin with source selection */
+    devMode?: boolean;
+    onReady?: (element: HTMLVideoElement) => void;
+    onError?: (error: string | Error) => void;
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onTimeUpdate?: (currentTime: number) => void;
+    onWaiting?: () => void;
+    onPlaying?: () => void;
+    onCanPlay?: () => void;
+    onDurationChange?: (duration: number) => void;
+}
+export interface PlayerCapability {
+    /** Player name for display */
+    name: string;
+    /** Unique identifier */
+    shortname: string;
+    /** Priority (lower number = higher priority) */
+    priority: number;
+    /** MIME types this player can handle */
+    mimes: string[];
+}
+export interface PlayerEvents {
+    ready: HTMLVideoElement;
+    error: string | Error;
+    play: void;
+    pause: void;
+    ended: void;
+    timeupdate: number;
+    /** Request to reload the player (e.g., Firefox segment error recovery) */
+    reloadrequested: {
+        reason: string;
+    };
+    /** Seekable range changed */
+    seekablechange: {
+        start: number;
+        end: number;
+        bufferWindow: number;
+    };
+}
+/**
+ * Base interface all players must implement
+ */
+export interface IPlayer {
+    /** Player metadata */
+    readonly capability: PlayerCapability;
+    /**
+     * Check if this player supports the given MIME type
+     */
+    isMimeSupported(mimetype: string): boolean;
+    /**
+     * Check if this player can play in the current browser environment
+     * @param mimetype - MIME type to test
+     * @param source - Source information
+     * @param streamInfo - Stream metadata
+     * @returns false if not supported, true if supported (no track info),
+     *          or array of supported track types
+     */
+    isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
+    /**
+     * Initialize the player with given source and options
+     * @param container - Container element to render in
+     * @param source - Source to play
+     * @param options - Player options
+     * @param streamInfo - Full stream metadata (optional, for players that need track details)
+     * @returns Promise resolving to video element
+     */
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions, streamInfo?: StreamInfo): Promise<HTMLVideoElement>;
+    /**
+     * Clean up and destroy the player.
+     * May be async if cleanup requires network requests (e.g., WHEP session DELETE).
+     */
+    destroy(): void | Promise<void>;
+    /**
+     * Get the underlying video element (if available)
+     */
+    getVideoElement(): HTMLVideoElement | null;
+    /**
+     * Set video size
+     */
+    setSize?(width: number, height: number): void;
+    /**
+     * Add event listener
+     */
+    on<K extends keyof PlayerEvents>(event: K, listener: (data: PlayerEvents[K]) => void): void;
+    /**
+     * Remove event listener
+     */
+    off<K extends keyof PlayerEvents>(event: K, listener: (data: PlayerEvents[K]) => void): void;
+    /**
+     * Get current playback state
+     */
+    getCurrentTime?(): number;
+    getDuration?(): number;
+    isPaused?(): boolean;
+    isMuted?(): boolean;
+    /** Optional: provide an override seekable range (seconds) */
+    getSeekableRange?(): {
+        start: number;
+        end: number;
+    } | null;
+    /** Optional: provide buffered ranges override */
+    getBufferedRanges?(): TimeRanges | null;
+    /**
+     * Control playback
+     */
+    play?(): Promise<void>;
+    pause?(): void;
+    seek?(time: number): void;
+    setVolume?(volume: number): void;
+    setMuted?(muted: boolean): void;
+    setPlaybackRate?(rate: number): void;
+    getTextTracks?(): Array<{
+        id: string;
+        label: string;
+        lang?: string;
+        active: boolean;
+    }>;
+    selectTextTrack?(id: string | null): void;
+    getQualities?(): Array<{
+        id: string;
+        label: string;
+        bitrate?: number;
+        width?: number;
+        height?: number;
+        isAuto?: boolean;
+        active?: boolean;
+    }>;
+    selectQuality?(id: string): void;
+    getCurrentQuality?(): string | null;
+    isLive?(): boolean;
+    jumpToLive?(): void;
+    requestPiP?(): Promise<void>;
+    /**
+     * Optional: Retrieve player-specific stats (e.g., WebRTC inbound-rtp)
+     */
+    getStats?(): Promise<any>;
+    /**
+     * Optional: Retrieve approximate playback latency stats
+     */
+    getLatency?(): Promise<any>;
+}
+/**
+ * Base class providing common functionality
+ */
+export declare abstract class BasePlayer implements IPlayer {
+    abstract readonly capability: PlayerCapability;
+    protected listeners: Map<string, Set<Function>>;
+    protected videoElement: HTMLVideoElement | null;
+    abstract isMimeSupported(mimetype: string): boolean;
+    abstract isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
+    abstract initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions, streamInfo?: StreamInfo): Promise<HTMLVideoElement>;
+    abstract destroy(): void | Promise<void>;
+    getVideoElement(): HTMLVideoElement | null;
+    on<K extends keyof PlayerEvents>(event: K, listener: (data: PlayerEvents[K]) => void): void;
+    off<K extends keyof PlayerEvents>(event: K, listener: (data: PlayerEvents[K]) => void): void;
+    protected emit<K extends keyof PlayerEvents>(event: K, data: PlayerEvents[K]): void;
+    protected setupVideoEventListeners(video: HTMLVideoElement, options: PlayerOptions): void;
+    getCurrentTime(): number;
+    getDuration(): number;
+    getSeekableRange(): {
+        start: number;
+        end: number;
+    } | null;
+    getBufferedRanges(): TimeRanges | null;
+    isPaused(): boolean;
+    isMuted(): boolean;
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): void;
+    setVolume(volume: number): void;
+    setMuted(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    getTextTracks(): Array<{
+        id: string;
+        label: string;
+        lang?: string;
+        active: boolean;
+    }>;
+    selectTextTrack(id: string | null): void;
+    isLive(): boolean;
+    jumpToLive(): void;
+    requestPiP(): Promise<void>;
+    setSize(width: number, height: number): void;
+    getStats(): Promise<any>;
+    getLatency(): Promise<any>;
+}

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

@@ -0,0 +1,182 @@
+/**
+ * PlayerManager
+ *
+ * Central orchestrator for player selection and lifecycle management.
+ * Single source of truth for all scoring logic.
+ *
+ * Architecture:
+ * - `getAllCombinations()` is THE single function that computes player+source scores
+ * - Results are cached by content (source types + track codecs), not object identity
+ * - Events fire only when selection actually changes (no render spam)
+ * - `selectBestPlayer()` returns cached winner without recomputation
+ */
+import { IPlayer, StreamSource, StreamInfo, PlayerOptions } from './PlayerInterface';
+import type { PlaybackMode } from '../types';
+export interface PlayerSelection {
+    score: number;
+    player: string;
+    source: StreamSource;
+    source_index: number;
+}
+export interface PlayerManagerOptions {
+    /** Force a specific player */
+    forcePlayer?: string;
+    /** Force a specific source index */
+    forceSource?: number;
+    /** Force a specific MIME type */
+    forceType?: string;
+    /** Enable debug logging (logs selection changes only, not every render) */
+    debug?: boolean;
+    /** Automatic fallback on player failure */
+    autoFallback?: boolean;
+    /** Maximum fallback attempts */
+    maxFallbackAttempts?: number;
+    /** Playback mode for protocol selection */
+    playbackMode?: PlaybackMode;
+}
+export interface PlayerManagerEvents {
+    playerSelected: {
+        player: string;
+        source: StreamSource;
+        score: number;
+    };
+    playerInitialized: {
+        player: IPlayer;
+        videoElement: HTMLVideoElement;
+    };
+    playerFailed: {
+        player: string;
+        error: string;
+    };
+    fallbackAttempted: {
+        fromPlayer: string;
+        toPlayer: string;
+    };
+    /** Fires when selection changes (different player+source than before) */
+    'selection-changed': PlayerSelection | null;
+    /** Fires when combinations are recomputed (cache miss) */
+    'combinations-updated': PlayerCombination[];
+}
+/** Full combination info including scoring breakdown */
+export interface PlayerCombination {
+    player: string;
+    playerName: string;
+    source: StreamSource;
+    sourceIndex: number;
+    sourceType: string;
+    score: number;
+    compatible: boolean;
+    incompatibleReason?: string;
+    /** True when player supports MIME but codec is incompatible */
+    codecIncompatible?: boolean;
+    scoreBreakdown?: {
+        trackScore: number;
+        trackTypes: string[];
+        priorityScore: number;
+        sourceScore: number;
+        reliabilityScore?: number;
+        modeBonus?: number;
+        routingBonus?: number;
+        weights: {
+            tracks: number;
+            priority: number;
+            source: number;
+            reliability?: number;
+            mode?: number;
+            routing?: number;
+        };
+    };
+}
+export declare class PlayerManager {
+    private players;
+    private currentPlayer;
+    private listeners;
+    private fallbackAttempts;
+    private options;
+    private cachedCombinations;
+    private cachedSelection;
+    private cacheKey;
+    private lastLoggedWinner;
+    private lastContainer;
+    private lastStreamInfo;
+    private lastPlayerOptions;
+    private lastManagerOptions;
+    private excludedPlayers;
+    private opQueue;
+    constructor(options?: PlayerManagerOptions);
+    registerPlayer(player: IPlayer): void;
+    unregisterPlayer(shortname: string): void;
+    getRegisteredPlayers(): IPlayer[];
+    /**
+     * Compute cache key based on CONTENT, not object identity.
+     * Prevents recalculation when streamInfo is a new object with same data.
+     */
+    private computeCacheKey;
+    /** Invalidate cache (called when player registrations change) */
+    invalidateCache(): void;
+    /** Get cached selection without recomputing */
+    getCurrentSelection(): PlayerSelection | null;
+    /** Get cached combinations without recomputing */
+    getCachedCombinations(): PlayerCombination[] | null;
+    /**
+     * THE single source of truth for player+source scoring.
+     * Returns ALL combinations (compatible and incompatible) with scores.
+     * Results are cached - won't recompute if source types/tracks haven't changed.
+     */
+    getAllCombinations(streamInfo: StreamInfo, playbackMode?: PlaybackMode): PlayerCombination[];
+    /**
+     * Select the best player for given stream info.
+     * Uses cached combinations - won't recompute if data hasn't changed.
+     */
+    selectBestPlayer(streamInfo: StreamInfo, options?: PlayerManagerOptions): PlayerSelection | false;
+    /**
+     * Internal: compute all combinations (no caching)
+     */
+    private computeAllCombinations;
+    /**
+     * Pick best compatible combination
+     */
+    private pickBestFromCombinations;
+    /**
+     * Check if selection changed
+     */
+    private hasSelectionChanged;
+    private enqueueOp;
+    initializePlayer(container: HTMLElement, streamInfo: StreamInfo, playerOptions?: PlayerOptions, managerOptions?: PlayerManagerOptions): Promise<HTMLVideoElement>;
+    private tryInitializePlayer;
+    tryPlaybackFallback(): Promise<boolean>;
+    getRemainingFallbackAttempts(): number;
+    canAttemptFallback(): boolean;
+    getCurrentPlayer(): IPlayer | null;
+    getBrowserCapabilities(): {
+        browser: import("./detector").BrowserInfo;
+        compatibility: {
+            supportsNativeHLS: boolean | 0 | null;
+            supportsMSE: boolean;
+            supportsWebSocket: boolean;
+            supportsWebRTC: boolean;
+            preferVideoJs: boolean | 0 | null;
+            avoidMEWSOnMac: boolean;
+            fileProtocolLimitations: boolean;
+        };
+        supportedMimeTypes: string[];
+        availablePlayers: {
+            name: string;
+            shortname: string;
+            priority: number;
+            mimes: string[];
+        }[];
+    };
+    private getSupportedMimeTypes;
+    private getAvailablePlayerInfo;
+    destroy(): Promise<void>;
+    removeAllListeners(): void;
+    on<K extends keyof PlayerManagerEvents>(event: K, listener: (data: PlayerManagerEvents[K]) => void): () => void;
+    off<K extends keyof PlayerManagerEvents>(event: K, listener: (data: PlayerManagerEvents[K]) => void): void;
+    private emit;
+    private log;
+    testSource(source: StreamSource, streamInfo: StreamInfo): Promise<{
+        canPlay: boolean;
+        players: string[];
+    }>;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Player Registry
+ *
+ * Central registration of all available player implementations
+ */
+import { PlayerManager } from './PlayerManager';
+export declare function ensurePlayersRegistered(manager?: PlayerManager): Promise<void>;
+export declare const globalPlayerManager: PlayerManager;
+/**
+ * Register all available players (async for backwards compatibility)
+ */
+export declare function registerAllPlayers(manager?: PlayerManager): Promise<void>;
+/**
+ * Create a new PlayerManager instance with all players registered
+ */
+export declare function createPlayerManager(options?: ConstructorParameters<typeof PlayerManager>[0]): PlayerManager;
+/**
+ * Export individual player classes for direct use
+ */
+export { NativePlayerImpl, DirectPlaybackPlayerImpl } from '../players/NativePlayer';
+export { HlsJsPlayerImpl } from '../players/HlsJsPlayer';
+export { DashJsPlayerImpl } from '../players/DashJsPlayer';
+export { VideoJsPlayerImpl } from '../players/VideoJsPlayer';
+export { MistPlayerImpl } from '../players/MistPlayer';
+export { MewsWsPlayerImpl } from '../players/MewsWsPlayer';
+export { MistWebRTCPlayerImpl } from '../players/MistWebRTCPlayer';
+export { WebCodecsPlayerImpl } from '../players/WebCodecsPlayer';

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

@@ -0,0 +1,184 @@
+import type { PlaybackQuality, QualityThresholds } from '../types';
+/** Protocol type for threshold selection */
+export type PlayerProtocol = 'webrtc' | 'hls' | 'dash' | 'html5' | 'unknown';
+/** Protocol-specific playback score thresholds (MistMetaPlayer reference) */
+export declare const PROTOCOL_THRESHOLDS: Record<PlayerProtocol, number>;
+export interface QualityMonitorOptions {
+    /** Sample interval in ms */
+    sampleInterval?: number;
+    /** Quality thresholds */
+    thresholds?: Partial<QualityThresholds>;
+    /** Callback when quality degrades */
+    onQualityDegraded?: (quality: PlaybackQuality) => void;
+    /** Callback on every sample */
+    onSample?: (quality: PlaybackQuality) => void;
+    /** Current player protocol for threshold selection */
+    protocol?: PlayerProtocol;
+    /** Custom playback score threshold (overrides protocol default) */
+    playbackScoreThreshold?: number;
+    /**
+     * Callback when sustained poor quality triggers a fallback request
+     * Reference: player.js:654-665 - "nextCombo" action
+     */
+    onFallbackRequest?: (reason: {
+        score: number;
+        consecutivePoorSamples: number;
+    }) => void;
+    /**
+     * Number of consecutive poor samples before requesting fallback
+     * Default: 5 (2.5 seconds at 500ms sample interval)
+     */
+    poorSamplesBeforeFallback?: number;
+}
+export interface QualityMonitorState {
+    isMonitoring: boolean;
+    quality: PlaybackQuality | null;
+    history: PlaybackQuality[];
+}
+/**
+ * QualityMonitor - Tracks playback quality metrics
+ *
+ * Monitors:
+ * - Buffer health (seconds ahead)
+ * - Stall count (waiting events)
+ * - Frame drop rate (via video.getVideoPlaybackQuality())
+ * - Estimated bitrate
+ * - Latency (for live streams)
+ *
+ * Calculates a composite quality score (0-100) and triggers
+ * callbacks when quality degrades below thresholds.
+ */
+export declare class QualityMonitor {
+    private videoElement;
+    private options;
+    private thresholds;
+    private timers;
+    private stallCount;
+    private lastStallTime;
+    private totalStallMs;
+    private history;
+    private lastBytesLoaded;
+    private lastBytesTime;
+    private listeners;
+    private playbackScoreHistory;
+    private playbackScore;
+    private readonly PLAYBACK_SCORE_AVERAGING_STEPS;
+    private consecutivePoorSamples;
+    private fallbackTriggered;
+    constructor(options?: QualityMonitorOptions);
+    /**
+     * Set the current player protocol for threshold selection
+     */
+    setProtocol(protocol: PlayerProtocol): void;
+    /**
+     * Get the current player protocol
+     */
+    getProtocol(): PlayerProtocol;
+    /**
+     * Get the playback score threshold for the current protocol
+     */
+    getPlaybackScoreThreshold(): number;
+    /**
+     * Set a custom playback score threshold (overrides protocol default)
+     */
+    setPlaybackScoreThreshold(threshold: number | null): void;
+    /**
+     * Start monitoring a video element
+     */
+    start(videoElement: HTMLVideoElement): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Take a quality sample
+     */
+    private sample;
+    /**
+     * Calculate current quality metrics
+     */
+    private calculateQuality;
+    /**
+     * Calculate composite quality score
+     *
+     * D4: Duration-weighted stall tracking - stall penalty considers both
+     * count AND duration. 10x 0.1s stalls (1s total) weighs less than 1x 1s stall.
+     */
+    private calculateScore;
+    /**
+     * Get current quality metrics
+     */
+    getCurrentQuality(): PlaybackQuality | null;
+    /**
+     * Get rolling average quality
+     */
+    getAverageQuality(): PlaybackQuality | null;
+    /**
+     * Get quality history
+     */
+    getHistory(): PlaybackQuality[];
+    /**
+     * Reset stall counters
+     */
+    resetStallCounters(): void;
+    /**
+     * Get total stall time in ms
+     */
+    getTotalStallMs(): number;
+    /**
+     * Check if currently monitoring
+     */
+    isMonitoring(): boolean;
+    /**
+     * Calculate playback score entry value
+     * Compares video time progress vs wall clock time
+     */
+    private getPlaybackScoreValue;
+    /**
+     * Calculate score between two entries
+     * Returns 1.0 for normal playback, >1.0 if faster, <1.0 if stalled, <0 if backwards
+     */
+    private calculatePlaybackScoreFromEntries;
+    /**
+     * Calculate and update the playback score
+     * Like MistPlayer's calcScore function
+     */
+    private updatePlaybackScore;
+    /**
+     * Get current playback score (MistPlayer-style 0-2.0 scale)
+     *
+     * - 1.0 = normal playback (video progresses at expected rate)
+     * - > 1.0 = faster than expected (catching up)
+     * - < 1.0 = slower than expected (stalling/buffering)
+     * - < 0 = video went backwards
+     *
+     * Threshold recommendations:
+     * - WebRTC: warn below 0.95
+     * - HLS/DASH: warn below 0.75
+     */
+    getPlaybackScore(): number;
+    /**
+     * Check if playback quality is poor based on score
+     * Uses protocol-specific thresholds (MistPlayer-style)
+     * WebRTC: 0.95 (strict), HLS/DASH/HTML5: 0.75 (lenient)
+     */
+    isPlaybackPoor(): boolean;
+    /**
+     * Reset playback score tracking
+     */
+    resetPlaybackScore(): void;
+    /**
+     * Reset fallback state
+     * Call after a player switch to allow fallback to trigger again
+     */
+    resetFallbackState(): void;
+    /**
+     * Get consecutive poor sample count (for debugging)
+     */
+    getConsecutivePoorSamples(): number;
+    /**
+     * Check if fallback has been triggered (for debugging)
+     */
+    hasFallbackTriggered(): boolean;
+}
+export default QualityMonitor;

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

@@ -0,0 +1,70 @@
+/**
+ * ScreenWakeLockManager - Prevents device sleep during video playback
+ *
+ * Uses the Screen Wake Lock API to keep the screen awake during:
+ * - Fullscreen video playback
+ * - Active video playback (optional)
+ *
+ * Gracefully falls back to no-op on unsupported browsers.
+ */
+export interface ScreenWakeLockConfig {
+    /** Acquire wake lock on any playback, not just fullscreen (default: false) */
+    acquireOnPlay?: boolean;
+    /** Callback when wake lock is acquired */
+    onAcquire?: () => void;
+    /** Callback when wake lock is released */
+    onRelease?: () => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+export declare class ScreenWakeLockManager {
+    private wakeLock;
+    private config;
+    private isSupported;
+    private isPlaying;
+    private isFullscreen;
+    private isDestroyed;
+    private boundVisibilityChange;
+    constructor(config?: ScreenWakeLockConfig);
+    /**
+     * Check if Screen Wake Lock API is supported
+     */
+    static isSupported(): boolean;
+    /**
+     * Update playing state
+     */
+    setPlaying(isPlaying: boolean): void;
+    /**
+     * Update fullscreen state
+     */
+    setFullscreen(isFullscreen: boolean): void;
+    /**
+     * Check if wake lock is currently held
+     */
+    isHeld(): boolean;
+    /**
+     * Manually acquire wake lock
+     */
+    acquire(): Promise<void>;
+    /**
+     * Manually release wake lock
+     */
+    release(): void;
+    /**
+     * Destroy the manager and release wake lock
+     */
+    destroy(): void;
+    /**
+     * Update wake lock based on current state
+     */
+    private updateWakeLock;
+    /**
+     * Handle wake lock release event
+     */
+    private handleRelease;
+    /**
+     * Handle visibility change - re-acquire if page becomes visible
+     */
+    private handleVisibilityChange;
+}
+export default ScreenWakeLockManager;