@livepeer-frameworks/player-core 0.0.3

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

@@ -0,0 +1,149 @@
+/**
+ * Browser and Codec Detection
+ * Ported from MistMetaPlayer v3.1.0
+ *
+ * Detects browser capabilities and codec support
+ * Removes legacy IE/Flash detection code
+ */
+import { translateCodec } from './CodecUtils';
+export interface BrowserInfo {
+    isChrome: boolean;
+    isFirefox: boolean;
+    isSafari: boolean;
+    isEdge: boolean;
+    isAndroid: boolean;
+    isIOS: boolean;
+    isMobile: boolean;
+    supportsMediaSource: boolean;
+    supportsWebRTC: boolean;
+    supportsWebSocket: boolean;
+}
+export interface CodecSupport {
+    h264: boolean;
+    h265: boolean;
+    vp8: boolean;
+    vp9: boolean;
+    av1: boolean;
+    aac: boolean;
+    mp3: boolean;
+    opus: boolean;
+}
+/**
+ * Detect browser information
+ */
+export declare function getBrowserInfo(): BrowserInfo;
+export { translateCodec };
+/**
+ * Test codec support using MediaSource API
+ */
+export declare function testCodecSupport(mimeType: string, codec: string): boolean;
+/**
+ * Get comprehensive codec support info
+ */
+export declare function getCodecSupport(): CodecSupport;
+/**
+ * Check if tracks are playable by testing codecs
+ */
+export declare function checkTrackPlayability(tracks: Array<{
+    type: string;
+    codec: string;
+    codecstring?: string;
+    init?: string;
+}>, containerType: string): {
+    playable: string[];
+    supported: string[];
+};
+/**
+ * Check protocol/scheme mismatch (http/https)
+ */
+export declare function checkProtocolMismatch(sourceUrl: string): boolean;
+/**
+ * Check if current page is loaded over file://
+ */
+export declare function isFileProtocol(): boolean;
+/**
+ * Get Android version (returns null if not Android)
+ */
+export declare function getAndroidVersion(): number | null;
+/**
+ * Browser-specific compatibility checks
+ */
+export declare function getBrowserCompatibility(): {
+    supportsNativeHLS: boolean | 0 | null;
+    supportsMSE: boolean;
+    supportsWebSocket: boolean;
+    supportsWebRTC: boolean;
+    preferVideoJs: boolean | 0 | null;
+    avoidMEWSOnMac: boolean;
+    fileProtocolLimitations: boolean;
+};
+/**
+ * Codecs that are compatible with WebRTC (WHEP/MistServer native)
+ * These are the only codecs that can be used in RTP streams
+ */
+export declare const WEBRTC_COMPATIBLE_CODECS: {
+    readonly video: readonly ["H264", "VP8", "VP9", "AV1"];
+    readonly audio: readonly ["OPUS", "PCMU", "PCMA", "G711", "G722"];
+};
+/**
+ * Codecs that are explicitly incompatible with WebRTC
+ */
+export declare const WEBRTC_INCOMPATIBLE_CODECS: {
+    readonly video: readonly ["HEVC", "H265", "THEORA", "MPEG2"];
+    readonly audio: readonly ["AC3", "EAC3", "EC3", "MP3", "FLAC", "VORBIS", "DTS"];
+};
+export interface WebRTCCodecCompatibility {
+    /** Whether at least one video track is WebRTC-compatible */
+    videoCompatible: boolean;
+    /** Whether at least one audio track is WebRTC-compatible (or no audio tracks) */
+    audioCompatible: boolean;
+    /** Overall compatibility - both video and audio must be compatible */
+    compatible: boolean;
+    /** List of incompatible codecs found */
+    incompatibleCodecs: string[];
+    /** Detailed breakdown per track type */
+    details: {
+        videoTracks: number;
+        audioTracks: number;
+        compatibleVideoCodecs: string[];
+        compatibleAudioCodecs: string[];
+    };
+}
+/**
+ * Check if stream tracks are compatible with WebRTC playback
+ *
+ * Uses RTCRtpReceiver.getCapabilities() to dynamically query browser support,
+ * matching the reference MistServer implementation (webrtc.js:38-46).
+ *
+ * @param tracks - Array of track metadata from MistServer
+ * @returns Compatibility assessment
+ */
+export declare function checkWebRTCCodecCompatibility(tracks: Array<{
+    type: string;
+    codec: string;
+}>): WebRTCCodecCompatibility;
+export interface MSECodecCompatibility {
+    /** Whether at least one video track is MSE-compatible in this browser */
+    videoCompatible: boolean;
+    /** Whether at least one audio track is MSE-compatible in this browser */
+    audioCompatible: boolean;
+    /** Overall compatibility */
+    compatible: boolean;
+    /** Codecs that failed browser support test */
+    unsupportedCodecs: string[];
+}
+/**
+ * Check if stream tracks are compatible with MSE playback in this browser
+ *
+ * Unlike WebRTC, MSE compatibility varies by browser. HEVC works in Safari
+ * but not Firefox. This function actually tests MediaSource.isTypeSupported().
+ *
+ * @param tracks - Array of track metadata
+ * @param containerType - MIME type (e.g., 'video/mp4')
+ */
+export declare function checkMSECodecCompatibility(tracks: Array<{
+    type: string;
+    codec: string;
+    codecstring?: string;
+    init?: string;
+}>, containerType?: string): MSECodecCompatibility;

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

@@ -0,0 +1,49 @@
+/**
+ * Core Player Management System
+ *
+ * Exports all core functionality for the FrameWorks player system
+ */
+export * from './detector';
+export * from './scorer';
+export * from './PlayerInterface';
+export { PlayerManager, type PlayerSelection, type PlayerCombination, type PlayerManagerOptions, type PlayerManagerEvents, } from './PlayerManager';
+export * from './PlayerRegistry';
+export { globalPlayerManager, createPlayerManager, ensurePlayersRegistered } from './PlayerRegistry';
+export type { IPlayer, PlayerOptions } from './PlayerInterface';
+export { QualityMonitor, PROTOCOL_THRESHOLDS } from './QualityMonitor';
+export type { QualityMonitorOptions, QualityMonitorState, PlayerProtocol } from './QualityMonitor';
+export { TelemetryReporter } from './TelemetryReporter';
+export type { TelemetryReporterConfig } from './TelemetryReporter';
+export { ABRController } from './ABRController';
+export type { ABRControllerConfig, ABRDecision } from './ABRController';
+export { MetaTrackManager } from './MetaTrackManager';
+export type { MetaTrackManagerConfig, MetaTrackSubscription } from './MetaTrackManager';
+export { TypedEventEmitter } from './EventEmitter';
+export { GatewayClient } from './GatewayClient';
+export type { GatewayClientConfig, GatewayClientEvents, GatewayStatus } from './GatewayClient';
+export { StreamStateClient } from './StreamStateClient';
+export type { StreamStateClientConfig, StreamStateClientEvents } from './StreamStateClient';
+export { PlayerController, buildStreamInfoFromEndpoints, MIST_SOURCE_TYPES, PROTOCOL_TO_MIME, getMimeTypeForProtocol, getSourceTypeInfo, } from './PlayerController';
+export type { PlayerControllerConfig, PlayerControllerEvents } from './PlayerController';
+export { MistReporter } from './MistReporter';
+export type { MistReporterStats, MistReporterOptions, MistReporterInitialReport } from './MistReporter';
+export { MistSignaling } from './MistSignaling';
+export type { MistSignalingConfig, MistSignalingEvents, MistTimeUpdate, MistSignalingState } from './MistSignaling';
+export { LiveDurationProxy, createLiveVideoProxy } from './LiveDurationProxy';
+export type { LiveDurationProxyOptions, LiveDurationState } from './LiveDurationProxy';
+export { TimerManager } from './TimerManager';
+export { BaseDisposable, disposeAll, createCompositeDisposable } from './Disposable';
+export type { Disposable } from './Disposable';
+export { appendUrlParams, parseUrlParams, stripUrlParams, buildUrl, isSecureUrl, httpToWs, wsToHttp, matchPageProtocol, } from './UrlUtils';
+export { translateCodec, isCodecSupported, getBestSupportedTrack, } from './CodecUtils';
+export type { TrackInfo } from './CodecUtils';
+export { SubtitleManager } from './SubtitleManager';
+export type { SubtitleTrackInfo, SubtitleManagerConfig } from './SubtitleManager';
+export { InteractionController } from './InteractionController';
+export type { InteractionControllerConfig, InteractionState } from './InteractionController';
+export { ScreenWakeLockManager } from './ScreenWakeLockManager';
+export type { ScreenWakeLockConfig } from './ScreenWakeLockManager';
+export { LATENCY_TIERS, SPEED_PRESETS, DEFAULT_BUFFER_WINDOW_SEC, getLatencyTier, isMediaStreamSource, supportsPlaybackRate, calculateSeekableRange, canSeekStream, calculateLiveThresholds, calculateIsNearLive, isLiveContent, } from './SeekingUtils';
+export type { LatencyTier, LiveThresholds, SeekableRange, SeekableRangeParams, CanSeekParams, } from './SeekingUtils';
+export { formatTime, formatClockTime, formatTimeDisplay, formatTooltipTime, formatDuration, parseTime, } from './TimeFormat';
+export type { TimeDisplayParams } from './TimeFormat';

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

@@ -0,0 +1,167 @@
+/**
+ * Player Scoring System
+ * Enhanced from MistMetaPlayer v3.1.0 with reliability and mode-aware scoring
+ *
+ * Implements the scoring algorithm for player selection with:
+ * - Track type scoring
+ * - Player priority scoring
+ * - Source order scoring
+ * - Player reliability scoring (new)
+ * - Playback mode bonuses (new)
+ * - Protocol-specific routing (new)
+ */
+import type { PlaybackMode } from '../types';
+export interface TrackScore {
+    video: number;
+    audio: number;
+    subtitle: number;
+}
+export interface PlayerScore {
+    base: number;
+    trackTypes: string[];
+    total: number;
+    breakdown?: {
+        trackScore: number;
+        priorityScore: number;
+        sourceScore: number;
+        reliabilityScore: number;
+        modeBonus: number;
+        routingBonus: number;
+        protocolPenalty: number;
+    };
+}
+/**
+ * Default track type scores
+ */
+export declare const DEFAULT_TRACK_SCORES: TrackScore;
+/**
+ * Calculate score for supported track types
+ */
+export declare function calculateTrackScore(supportedTracks: string[] | boolean, scores?: TrackScore): number;
+/**
+ * Calculate maximum possible score for a stream
+ */
+export declare function calculateMaxScore(availableTracks: string[], scores?: TrackScore): number;
+/**
+ * Player priority scoring
+ */
+export declare function calculatePriorityScore(priority: number, maxPriority: number): number;
+/**
+ * Source preference scoring based on MistServer ordering
+ */
+export declare function calculateSourceScore(sourceIndex: number, totalSources: number): number;
+/**
+ * Bandwidth/quality scoring
+ */
+export declare function calculateQualityScore(bandwidth?: number, targetBandwidth?: number): number;
+/**
+ * Protocol blacklist - completely excluded from selection
+ * These protocols are truly broken and should never be considered.
+ *
+ * NOTE: Protocols that ARE supported by reference implementation but unreliable
+ * should be in PROTOCOL_PENALTIES instead (heavily penalized but still selectable).
+ */
+export declare const PROTOCOL_BLACKLIST: Set<string>;
+/**
+ * Check if a protocol is blacklisted
+ */
+export declare function isProtocolBlacklisted(mimeType: string): boolean;
+/**
+ * Protocol penalties for problematic protocols (not blacklisted, but deprioritized)
+ * These get subtracted from the total score to deprioritize certain protocols.
+ *
+ * Heavy penalties (0.50+): Reference-supported but consistently unreliable
+ * Medium penalties (0.20): Experimental or spotty support
+ */
+export declare const PROTOCOL_PENALTIES: Record<string, number>;
+/**
+ * Calculate protocol penalty based on known problematic protocols
+ */
+export declare function calculateProtocolPenalty(mimeType: string): number;
+/**
+ * Player reliability scores
+ * Based on library maturity, error recovery, and overall stability
+ */
+export declare const PLAYER_RELIABILITY: Record<string, number>;
+/**
+ * Calculate player reliability score
+ */
+export declare function calculateReliabilityScore(playerShortname: string): number;
+/**
+ * Protocol bonuses for each playback mode
+ *
+ * IMPORTANT: Track compatibility is enforced by trackScore (50% weight).
+ * Mode bonuses (12% weight) only affect ordering among compatible options.
+ * A protocol missing required tracks will never be selected regardless of mode bonus.
+ *
+ * Priority rationale:
+ * - Low-latency: WHEP/WebRTC first (<1s), then MP4/WS (2-5s), HLS last (10-30s)
+ * - Quality: MP4/WS first (stable + low latency), HLS fallback, WHEP minimal
+ * - VOD: MP4/HLS first (seekable), WHEP hard penalty (no seek support)
+ * - Auto: MP4/WS balanced choice, WHEP for low latency, HLS last resort
+ */
+export declare const MODE_PROTOCOL_BONUSES: Record<PlaybackMode, Record<string, number>>;
+/**
+ * Calculate mode-specific bonus for a protocol
+ */
+export declare function calculateModeBonus(mimeType: string, mode: PlaybackMode): number;
+/**
+ * Protocol routing rules - certain players are preferred for certain protocols
+ */
+export declare const PROTOCOL_ROUTING: Record<string, {
+    prefer: string[];
+    avoid?: string[];
+}>;
+/**
+ * Calculate routing bonus based on protocol+player pairing
+ */
+export declare function calculateRoutingBonus(mimeType: string, playerShortname: string): number;
+/**
+ * Comprehensive player scoring with enhanced factors
+ */
+export declare function scorePlayer(supportedTracks: string[] | boolean, priority: number, sourceIndex: number, options?: {
+    maxPriority?: number;
+    totalSources?: number;
+    trackScores?: Partial<TrackScore>;
+    bandwidth?: number;
+    targetBandwidth?: number;
+    playerShortname?: string;
+    mimeType?: string;
+    playbackMode?: PlaybackMode;
+    weights?: {
+        tracks: number;
+        priority: number;
+        source: number;
+        quality: number;
+        reliability?: number;
+        mode?: number;
+        routing?: number;
+        protocolPenalty?: number;
+    };
+}): PlayerScore;
+/**
+ * Compare two player scores
+ */
+export declare function compareScores(a: PlayerScore, b: PlayerScore): number;
+/**
+ * Batch score multiple players and return sorted by best score
+ */
+export declare function scoreAndRankPlayers<T extends {
+    priority: number;
+}>(players: Array<{
+    player: T;
+    supportedTracks: string[] | boolean;
+    sourceIndex: number;
+}>, options?: Parameters<typeof scorePlayer>[3]): Array<{
+    player: T;
+    score: PlayerScore;
+}>;
+/**
+ * Utility to check if a score meets minimum thresholds
+ */
+export declare function meetsMinimumScore(score: PlayerScore, requirements: {
+    minTotal?: number;
+    requireVideo?: boolean;
+    requireAudio?: boolean;
+    minTrackTypes?: number;
+}): boolean;

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

@@ -0,0 +1,9 @@
+/**
+ * Player Selection Types
+ *
+ * Re-exports from PlayerManager for backwards compatibility.
+ * All selection logic is now consolidated in PlayerManager.
+ */
+export type { PlayerSelection, PlayerCombination, PlayerManagerOptions, } from './PlayerManager';
+import type { PlayerManagerOptions } from './PlayerManager';
+export type SelectionOptions = PlayerManagerOptions;

package/dist/types/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @livepeer-frameworks/player-core
+ *
+ * Framework-agnostic core player logic for FrameWorks streaming.
+ * This package provides:
+ * - PlayerManager: Intelligent player/protocol selection
+ * - PlayerController: High-level player orchestration
+ * - GatewayClient: Gateway endpoint resolution
+ * - StreamStateClient: MistServer WebSocket/HTTP polling
+ * - Quality monitoring, ABR control, interaction handling
+ */
+export { PlayerManager } from './core/PlayerManager';
+export type { PlayerSelection, PlayerCombination, PlayerManagerOptions, PlayerManagerEvents, } from './core/PlayerManager';
+export { PlayerController, buildStreamInfoFromEndpoints } from './core/PlayerController';
+export type { PlayerControllerConfig, PlayerControllerEvents } from './core/PlayerController';
+export { ensurePlayersRegistered, registerAllPlayers, createPlayerManager, globalPlayerManager, globalPlayerManager as globalRegistry } from './core/PlayerRegistry';
+export { GatewayClient } from './core/GatewayClient';
+export * from './players';
+export { StreamStateClient } from './core/StreamStateClient';
+export { QualityMonitor } from './core/QualityMonitor';
+export { ABRController } from './core/ABRController';
+export { InteractionController } from './core/InteractionController';
+export { MistSignaling } from './core/MistSignaling';
+export { MistReporter } from './core/MistReporter';
+export { MetaTrackManager } from './core/MetaTrackManager';
+export type { MetaTrackSubscription } from './core/MetaTrackManager';
+export { SubtitleManager } from './core/SubtitleManager';
+export { LiveDurationProxy } from './core/LiveDurationProxy';
+export { TimerManager } from './core/TimerManager';
+export { TypedEventEmitter, TypedEventEmitter as EventEmitter } from './core/EventEmitter';
+export { TelemetryReporter } from './core/TelemetryReporter';
+export type { IPlayer, PlayerCapability, PlayerEvents } from './core/PlayerInterface';
+export { BasePlayer } from './core/PlayerInterface';
+export type { StreamSource, StreamTrack, StreamInfo, PlayerOptions as CorePlayerOptions } from './core/PlayerInterface';
+export * from './core/scorer';
+export * from './core/selector';
+export * from './core/detector';
+export * from './core/UrlUtils';
+export * from './core/SeekingUtils';
+export type { LatencyTier, LiveThresholds, SeekableRange, SeekableRangeParams, CanSeekParams } from './core/SeekingUtils';
+export * from './core/TimeFormat';
+export type { TimeDisplayParams } from './core/TimeFormat';
+export { ensurePlayerStyles, injectPlayerStyles } from './styles';
+export { cn } from './lib/utils';
+export * from './types';

package/dist/types/lib/utils.d.ts

@@ -0,0 +1,2 @@
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/types/players/DashJsPlayer.d.ts

@@ -0,0 +1,102 @@
+import { BasePlayer } from '../core/PlayerInterface';
+import type { StreamSource, StreamInfo, PlayerOptions, PlayerCapability } from '../core/PlayerInterface';
+export declare class DashJsPlayerImpl extends BasePlayer {
+    readonly capability: PlayerCapability;
+    private dashPlayer;
+    private container;
+    private destroyed;
+    private debugging;
+    private lastProgress;
+    private videoProxy;
+    private streamType;
+    private subsLoaded;
+    private pendingSubtitleId;
+    isMimeSupported(mimetype: string): boolean;
+    isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
+    /**
+     * Check if current stream is live.
+     * Ported from reference dashjs.js live detection.
+     */
+    private isLiveStream;
+    /**
+     * Create a Proxy wrapper for the video element that intercepts duration for live streams.
+     * Ported from reference dashjs.js:81-122.
+     *
+     * For live streams, returns synthetic duration = buffer_end + time_since_last_progress
+     * This makes the seek bar usable for live content.
+     */
+    private createVideoProxy;
+    /**
+     * Set up comprehensive event logging.
+     * Ported from reference dashjs.js:152-160.
+     */
+    private setupEventLogging;
+    /**
+     * Set up subtitle deferred loading.
+     * Ported from reference dashjs.js:173-197.
+     */
+    private setupSubtitleHandling;
+    /**
+     * Set up stalled indicator handling.
+     * Ported from reference dashjs.js:207-211.
+     */
+    private setupStalledHandling;
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions): Promise<HTMLVideoElement>;
+    /**
+     * Get DASH.js-specific stats for ABR and playback monitoring
+     * Updated for dashjs v5 API
+     */
+    getStats(): Promise<{
+        type: 'dash';
+        currentQuality: number;
+        bufferLevel: number;
+        bitrateInfoList: Array<{
+            bitrate: number;
+            width: number;
+            height: number;
+        }>;
+        currentBitrate: number;
+        playbackRate: number;
+    } | undefined>;
+    /**
+     * Set playback rate
+     */
+    setPlaybackRate(rate: number): void;
+    /**
+     * Set source URL for seamless source switching.
+     * Ported from reference dashjs.js:166-168.
+     */
+    setSource(url: string): void;
+    /**
+     * Get duration using proxy for live streams.
+     * Returns synthetic growing duration for live content.
+     */
+    getDuration(): number;
+    /**
+     * Jump to live edge for live streams.
+     * Uses DASH.js seekToLive API when available.
+     */
+    jumpToLive(): void;
+    /**
+     * Get latency from live edge (for live streams)
+     */
+    getLiveLatency(): number;
+    destroy(): Promise<void>;
+    getQualities(): Array<{
+        id: string;
+        label: string;
+        bitrate?: number;
+        width?: number;
+        height?: number;
+        isAuto?: boolean;
+        active?: boolean;
+    }>;
+    selectQuality(id: string): void;
+    getTextTracks(): Array<{
+        id: string;
+        label: string;
+        lang?: string;
+        active: boolean;
+    }>;
+    selectTextTrack(id: string | null): void;
+}

package/dist/types/players/HlsJsPlayer.d.ts

@@ -0,0 +1,70 @@
+import { BasePlayer } from '../core/PlayerInterface';
+import type { StreamSource, StreamInfo, PlayerOptions, PlayerCapability } from '../core/PlayerInterface';
+export declare class HlsJsPlayerImpl extends BasePlayer {
+    readonly capability: PlayerCapability;
+    private hls;
+    private container;
+    private failureCount;
+    private destroyed;
+    private liveDurationProxy;
+    isMimeSupported(mimetype: string): boolean;
+    isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions): Promise<HTMLVideoElement>;
+    destroy(): Promise<void>;
+    /**
+     * Get the calculated duration for live streams
+     * Falls back to native duration for VOD
+     */
+    getDuration(): number;
+    /**
+     * Check if the stream is live
+     */
+    isLiveStream(): boolean;
+    /**
+     * Seek to a position with live-aware constraints
+     */
+    seek(time: number): void;
+    /**
+     * Jump to live edge
+     * Uses HLS.js liveSyncPosition when available (more accurate)
+     */
+    jumpToLive(): void;
+    /**
+     * Get latency from live edge (for live streams)
+     */
+    getLiveLatency(): number;
+    getQualities(): Array<{
+        id: string;
+        label: string;
+        bitrate?: number;
+        width?: number;
+        height?: number;
+        isAuto?: boolean;
+        active?: boolean;
+    }>;
+    selectQuality(id: string): void;
+    getTextTracks(): Array<{
+        id: string;
+        label: string;
+        lang?: string;
+        active: boolean;
+    }>;
+    selectTextTrack(id: string | null): void;
+    /**
+     * Get HLS.js-specific stats for accurate bitrate and bandwidth
+     */
+    getStats(): Promise<{
+        type: 'hls';
+        bandwidthEstimate: number;
+        currentLevel: number;
+        currentBitrate: number;
+        loadLevel: number;
+        levels: Array<{
+            bitrate: number;
+            width: number;
+            height: number;
+        }>;
+        buffered: number;
+        latency?: number;
+    } | undefined>;
+}