@livepeer-frameworks/player-core 0.0.3

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

@@ -0,0 +1,102 @@
+/**
+ * LiveDurationProxy - Wraps video element to provide meaningful duration for live streams
+ *
+ * Live streams report `Infinity` or `NaN` for duration, breaking seek bars and time display.
+ * This proxy intercepts the duration getter and returns a calculated value based on:
+ * - Buffer end position
+ * - Elapsed time since last progress event
+ *
+ * Based on MistMetaPlayer reference implementation (wrappers/html5.js, dashjs.js)
+ */
+export interface LiveDurationProxyOptions {
+    /** Whether to constrain seeking to buffered range (default: true) */
+    constrainSeek?: boolean;
+    /** Live offset from buffer end in seconds (default: 0) */
+    liveOffset?: number;
+    /** Callback when duration changes */
+    onDurationChange?: (duration: number) => void;
+}
+export interface LiveDurationState {
+    /** Calculated duration */
+    duration: number;
+    /** Whether stream is live */
+    isLive: boolean;
+    /** Buffer end position */
+    bufferEnd: number;
+    /** Time since last progress */
+    elapsed: number;
+}
+/**
+ * Creates a proxy wrapper around a video element that provides meaningful
+ * duration values for live streams.
+ */
+export declare class LiveDurationProxy {
+    private video;
+    private options;
+    private lastProgressTime;
+    private lastBufferEnd;
+    private listeners;
+    private _calculatedDuration;
+    constructor(video: HTMLVideoElement, options?: LiveDurationProxyOptions);
+    /**
+     * Check if the stream is live
+     */
+    isLive(): boolean;
+    /**
+     * Get the calculated duration
+     * For live: bufferEnd + elapsedSinceLastProgress
+     * For VOD: native duration
+     */
+    getDuration(): number;
+    /**
+     * Get the current buffer end position
+     */
+    getBufferEnd(): number;
+    /**
+     * Get the live edge position (where live is)
+     */
+    getLiveEdge(): number;
+    /**
+     * Get the current latency (distance from live edge)
+     */
+    getLatency(): number;
+    /**
+     * Seek to a position, respecting live constraints
+     */
+    seek(time: number): void;
+    /**
+     * Jump to live edge
+     */
+    jumpToLive(): void;
+    /**
+     * Check if currently at live edge (within threshold)
+     */
+    isAtLiveEdge(threshold?: number): boolean;
+    /**
+     * Get current state
+     */
+    getState(): LiveDurationState;
+    /**
+     * Update the calculated duration
+     */
+    private updateDuration;
+    /**
+     * Setup event listeners for tracking
+     */
+    private setupListeners;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Create a Proxy wrapper for a video element that intercepts duration/currentTime
+ * This allows existing code to work transparently with live streams.
+ *
+ * Note: This is an advanced feature - for most cases, use LiveDurationProxy directly.
+ */
+export declare function createLiveVideoProxy(video: HTMLVideoElement, options?: LiveDurationProxyOptions): {
+    proxy: HTMLVideoElement;
+    controller: LiveDurationProxy;
+};
+export default LiveDurationProxy;

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

@@ -0,0 +1,220 @@
+import type { MetaTrackEvent } from '../types';
+export interface MetaTrackSubscription {
+    trackId: string;
+    callback: (event: MetaTrackEvent) => void;
+}
+export interface MetaTrackManagerConfig {
+    /** MistServer base URL */
+    mistBaseUrl: string;
+    /** Stream name */
+    streamName: string;
+    /** Initial subscriptions */
+    subscriptions?: MetaTrackSubscription[];
+    /** Debug logging */
+    debug?: boolean;
+    /** Buffer ahead duration in seconds (default: 5) */
+    bufferAhead?: number;
+    /** Max age for messages in seconds before filtering (default: 5) */
+    maxMessageAge?: number;
+    /** Fast-forward interval in seconds for catching up (default: 5) */
+    fastForwardInterval?: number;
+}
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * MetaTrackManager - Handles real-time metadata subscriptions via MistServer WebSocket
+ *
+ * Uses native MistServer WebSocket protocol (from embed/player.js):
+ * - Connect: ws://{baseUrl}/json_{streamName}.js?rate=1
+ * - Set tracks: {type:"tracks", meta:"1,2,3"} (comma-separated indices)
+ * - Seek: {type:"seek", seek_time:<ms>, ff_to:<ms>}
+ * - Receive: {time:<ms>, track:<index>, data:{...}}
+ * - Control: {type:"hold"}, {type:"play"}, {type:"fast_forward", ff_to:<ms>}
+ *
+ * Features:
+ * - Automatic reconnection with exponential backoff
+ * - Message buffering during reconnection
+ * - Type detection for subtitle/score/event/chapter data
+ * - Stay-ahead buffering for smooth playback
+ *
+ * @example
+ * ```ts
+ * const manager = new MetaTrackManager({
+ *   mistBaseUrl: 'https://mist.example.com',
+ *   streamName: 'my-stream',
+ * });
+ *
+ * manager.subscribe('1', (event) => {
+ *   if (event.type === 'subtitle') {
+ *     console.log('Subtitle:', event.data);
+ *   }
+ * });
+ *
+ * manager.connect();
+ * ```
+ */
+export declare class MetaTrackManager {
+    private config;
+    private ws;
+    private state;
+    private subscriptions;
+    private pendingSubscriptions;
+    private reconnectAttempt;
+    private timers;
+    private messageBuffer;
+    private debug;
+    private connectionId;
+    private static readonly CONNECTION_DEBOUNCE_MS;
+    private static readonly MAX_RECONNECT_ATTEMPTS;
+    private static readonly INITIAL_RECONNECT_DELAY;
+    private static readonly MAX_RECONNECT_DELAY;
+    private static readonly MESSAGE_BUFFER_SIZE;
+    private currentPlaybackTime;
+    private bufferAhead;
+    private maxMessageAge;
+    private fastForwardInterval;
+    private lastFastForwardTime;
+    private timedEventBuffer;
+    constructor(config: MetaTrackManagerConfig);
+    /**
+     * Connect to MistServer WebSocket
+     * Debounced to prevent orphaned connections during rapid mount/unmount cycles.
+     */
+    connect(): void;
+    /**
+     * Internal method to create WebSocket after debounce
+     */
+    private createWebSocket;
+    /**
+     * Disconnect from MistServer
+     */
+    disconnect(): void;
+    /**
+     * Subscribe to a meta track
+     * @param trackId Track index (number as string) or "all" for all meta tracks
+     */
+    subscribe(trackId: string, callback: (event: MetaTrackEvent) => void): () => void;
+    /**
+     * Unsubscribe from a meta track
+     */
+    unsubscribe(trackId: string, callback: (event: MetaTrackEvent) => void): void;
+    /**
+     * Get list of subscribed track IDs
+     */
+    getSubscribedTracks(): string[];
+    /**
+     * Get connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Update current playback time
+     * Call this on video timeupdate events to keep buffer in sync
+     */
+    setPlaybackTime(timeInSeconds: number): void;
+    /**
+     * Get current playback time
+     */
+    getPlaybackTime(): number;
+    /**
+     * Handle seek event - clears buffer and sends seek command to MistServer
+     * Call this when video seeks to a new position
+     */
+    onSeek(newTimeInSeconds: number): void;
+    /**
+     * Process buffered events up to current playback time
+     * Dispatches events that are ready to be shown
+     */
+    private processTimedEvents;
+    /**
+     * Add event to timed buffer (sorted by timestamp)
+     * Used for events that should be dispatched at specific playback times
+     */
+    private addToTimedBuffer;
+    /**
+     * Check if we need to request more data (stay bufferAhead seconds ahead)
+     * Returns true if buffer is running low
+     */
+    needsMoreData(trackId: string): boolean;
+    /**
+     * Fast-forward through buffered events (rate-limited)
+     * Used when playback jumps ahead and needs to catch up
+     * Also notifies MistServer to fast-forward its metadata stream
+     */
+    fastForward(): void;
+    /**
+     * Get buffer status for debugging
+     */
+    getBufferStatus(): Record<string, {
+        count: number;
+        oldestMs: number;
+        newestMs: number;
+    }>;
+    /**
+     * Build WebSocket URL for MistServer meta track subscription
+     * Uses the same endpoint as JSON info polling, just over WebSocket
+     */
+    private buildWsUrl;
+    /**
+     * Send tracks update to MistServer
+     * MistServer protocol: {type:"tracks", meta:"1,2,3"} (comma-separated track indices)
+     */
+    private sendTracksUpdate;
+    /**
+     * Send seek command to MistServer
+     * MistServer protocol: {type:"seek", seek_time:<ms>, ff_to:<ms>}
+     */
+    private sendSeek;
+    /**
+     * Send hold command (pause metadata delivery)
+     */
+    private sendHold;
+    /**
+     * Send play command (resume metadata delivery)
+     */
+    private sendPlay;
+    /**
+     * Send fast-forward command
+     */
+    private sendFastForward;
+    /**
+     * Handle incoming WebSocket message
+     * MistServer format:
+     * - Metadata: {time:<ms>, track:<index>, data:{...}}
+     * - Status: {type:"on_time", data:{current:<ms>}}
+     * - Seek complete: {type:"seek", ...}
+     */
+    private handleMessage;
+    /**
+     * Parse meta track event from MistServer message
+     * MistServer format: {time:<ms>, track:<index>, data:{...}}
+     */
+    private parseMetaTrackEvent;
+    /**
+     * Detect event type from data shape
+     */
+    private detectEventType;
+    /**
+     * Dispatch event to subscribers
+     */
+    private dispatchEvent;
+    /**
+     * Schedule reconnection attempt
+     */
+    private scheduleReconnect;
+    /**
+     * Buffer message for later delivery
+     */
+    private bufferMessage;
+    /**
+     * Flush buffered messages to subscribers
+     */
+    private flushMessageBuffer;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+export default MetaTrackManager;

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

@@ -0,0 +1,163 @@
+/**
+ * MistReporter - Reports playback stats to MistServer
+ *
+ * Implements the same reporting protocol as MistPlayer reference:
+ * - Sends initial report on player selection (player, sourceType, sourceUrl, pageUrl)
+ * - Reports deltas every 5 seconds
+ * - Tracks waiting/stalled events and durations
+ * - Integrates with QualityMonitor for playbackScore
+ * - Sends final report on unload
+ *
+ * Reports are sent over the same WebSocket used for stream state.
+ */
+export interface MistReporterStats {
+    nWaiting: number;
+    timeWaiting: number;
+    nStalled: number;
+    timeStalled: number;
+    timeUnpaused: number;
+    nError: number;
+    lastError: string | null;
+    firstPlayback: number | null;
+    playbackScore: number;
+    autoplay: 'success' | 'muted' | 'failed' | null;
+    videoHeight: number | null;
+    videoWidth: number | null;
+    playerHeight: number | null;
+    playerWidth: number | null;
+    tracks: string | null;
+    nLog: number;
+}
+export interface MistReporterInitialReport {
+    player: string;
+    sourceType: string;
+    sourceUrl: string;
+    pageUrl: string;
+}
+export interface MistReporterOptions {
+    /** WebSocket to send reports through (shared with stream state) */
+    socket?: WebSocket | null;
+    /** Report interval in ms (default: 5000) */
+    reportInterval?: number;
+    /** E2: Batch flush interval in ms (default: 1000) - max rate for non-critical reports */
+    batchFlushInterval?: number;
+    /** Boot timestamp for firstPlayback calculation */
+    bootMs?: number;
+    /** Log array reference for including logs in reports */
+    logs?: string[];
+}
+type StatsKey = keyof MistReporterStats;
+/**
+ * MistReporter - Playback telemetry to MistServer
+ */
+export declare class MistReporter {
+    private socket;
+    private videoElement;
+    private containerElement;
+    private reportInterval;
+    private batchFlushInterval;
+    private bootMs;
+    private logs;
+    private _stats;
+    private waitingSince;
+    private stalledSince;
+    private unpausedSince;
+    private timeWaitingAccum;
+    private timeStalledAccum;
+    private timeUnpausedAccum;
+    private lastReported;
+    private timers;
+    private listeners;
+    private firstPlaybackRecorded;
+    private pendingBatch;
+    private hasPendingBatch;
+    private lastFlushTime;
+    private batchFlushTimerId;
+    private offlineQueue;
+    private static readonly MAX_OFFLINE_QUEUE_SIZE;
+    constructor(options?: MistReporterOptions);
+    /**
+     * Set the WebSocket to use for reporting
+     * E3: Flushes offline queue when socket becomes available
+     */
+    setSocket(socket: WebSocket | null): void;
+    /**
+     * E3: Flush queued reports that were collected while offline
+     */
+    private flushOfflineQueue;
+    /**
+     * Get current stats object with computed getters
+     * E1: Uses performance.now() for sub-millisecond precision in duration tracking
+     */
+    getStats(): MistReporterStats;
+    /**
+     * Set a stat value
+     */
+    set<K extends StatsKey>(key: K, value: MistReporterStats[K]): void;
+    /**
+     * Increment a counter stat
+     */
+    add(key: 'nWaiting' | 'nStalled' | 'nError', amount?: number): void;
+    /**
+     * Initialize reporting for a video element
+     */
+    init(videoElement: HTMLVideoElement, containerElement?: HTMLElement): void;
+    /**
+     * Send initial report when player is selected
+     */
+    sendInitialReport(info: MistReporterInitialReport): void;
+    /**
+     * Update playback score (call from QualityMonitor)
+     */
+    setPlaybackScore(score: number): void;
+    /**
+     * Update autoplay status
+     */
+    setAutoplayStatus(status: 'success' | 'muted' | 'failed'): void;
+    /**
+     * Update current tracks
+     */
+    setTracks(tracks: string[]): void;
+    /**
+     * Send a report over WebSocket immediately
+     * E3: Queues reports when socket is unavailable (up to MAX_OFFLINE_QUEUE_SIZE)
+     */
+    private sendReport;
+    /**
+     * E2: Queue data for batched reporting
+     * Merges with pending batch, schedules flush if not already pending
+     */
+    private report;
+    /**
+     * E2: Flush pending batch immediately
+     * Used for critical events (error, first play, unload)
+     */
+    flushBatch(): void;
+    /**
+     * Report stats delta (only changed values)
+     * E2: Now queues to batch instead of sending immediately
+     */
+    reportStats(): void;
+    /**
+     * Start periodic reporting
+     */
+    private startReporting;
+    /**
+     * Schedule the next report
+     */
+    private scheduleNextReport;
+    /**
+     * Send final report and cleanup
+     * E2: Flushes immediately since this is a critical event
+     */
+    sendFinalReport(reason?: string): void;
+    /**
+     * Stop reporting and cleanup
+     */
+    destroy(): void;
+    /**
+     * Add a log entry
+     */
+    log(message: string): void;
+}
+export default MistReporter;

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

@@ -0,0 +1,148 @@
+/**
+ * MistSignaling - WebSocket signaling for MistServer's native WebRTC protocol
+ *
+ * Protocol messages (from MistServer):
+ * - on_connected: WebSocket opened successfully
+ * - on_disconnected: WebSocket closed
+ * - on_answer_sdp: SDP answer received, { result: boolean, answer_sdp: string }
+ * - on_time: Time update { current: ms, end: ms, begin: ms, tracks: string[] }
+ * - on_stop: Stream ended
+ * - on_error: Error occurred { message: string }
+ *
+ * Protocol messages (to MistServer):
+ * - offer_sdp: SDP offer { offer_sdp: string }
+ * - seek: Seek to position { seek_time: number | "live" }
+ * - hold: Pause playback
+ * - stop: Stop playback
+ * - tracks: Select tracks { video: string, audio: string }
+ * - set_speed: Set playback rate { play_rate: number | "auto" }
+ */
+import { TypedEventEmitter } from './EventEmitter';
+export interface MistSignalingConfig {
+    /** WebSocket URL (will convert http to ws) */
+    url: string;
+    /** Connection timeout in ms (default: 5000) */
+    timeout?: number;
+    /** Callback for debug logging */
+    onLog?: (message: string) => void;
+}
+export interface MistTimeUpdate {
+    /** Current playback position in ms */
+    current: number;
+    /** End position in ms (0 for live) */
+    end: number;
+    /** Begin position in ms (buffer start) */
+    begin: number;
+    /** Currently active track IDs */
+    tracks?: string[];
+    /** Whether playback is paused */
+    paused?: boolean;
+    /** Whether at live point */
+    live_point?: boolean;
+}
+export interface MistSignalingEvents {
+    /** Connection established */
+    'connected': void;
+    /** Connection closed */
+    'disconnected': {
+        code: number;
+    };
+    /** SDP answer received */
+    'answer_sdp': {
+        result: boolean;
+        answer_sdp: string;
+    };
+    /** Time/track update */
+    'time_update': MistTimeUpdate;
+    /** Seek completed */
+    'seeked': {
+        live_point?: boolean;
+    };
+    /** Playback speed changed */
+    'speed_changed': {
+        play_rate: number;
+        play_rate_curr: number;
+    };
+    /** Stream ended */
+    'stopped': void;
+    /** Error occurred */
+    'error': {
+        message: string;
+    };
+}
+export type MistSignalingState = 'connecting' | 'connected' | 'disconnected' | 'closed';
+/**
+ * MistSignaling handles WebSocket communication with MistServer for WebRTC
+ */
+export declare class MistSignaling extends TypedEventEmitter<MistSignalingEvents> {
+    private ws;
+    private url;
+    private timeout;
+    private timeoutId;
+    private onLog;
+    private _state;
+    seekPromise: {
+        resolve: (msg: string) => void;
+        reject: (msg: string) => void;
+    } | null;
+    constructor(config: MistSignalingConfig);
+    /**
+     * Get current connection state
+     */
+    get state(): MistSignalingState;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Connect to MistServer WebSocket
+     */
+    connect(): void;
+    /**
+     * Handle incoming message from MistServer
+     */
+    private handleMessage;
+    /**
+     * Send a message to MistServer
+     */
+    send(cmd: Record<string, unknown>): boolean;
+    /**
+     * Send SDP offer to MistServer
+     */
+    sendOfferSDP(sdp: string): boolean;
+    /**
+     * Seek to position (in seconds or "live")
+     */
+    seek(time: number | 'live'): Promise<string>;
+    /**
+     * Pause playback (hold)
+     */
+    pause(): boolean;
+    /**
+     * Stop playback
+     */
+    stop(): boolean;
+    /**
+     * Set track selection
+     * @param video - Video track selection (e.g., "~1080x720", "|500000", "none")
+     * @param audio - Audio track selection (e.g., "eng", "none")
+     */
+    setTracks(options: {
+        video?: string;
+        audio?: string;
+    }): boolean;
+    /**
+     * Set playback speed
+     * @param rate - Playback rate (1.0 normal, "auto" for live catch-up)
+     */
+    setSpeed(rate: number | 'auto'): boolean;
+    /**
+     * Close the connection
+     */
+    close(): void;
+    /**
+     * Destroy and cleanup
+     */
+    destroy(): void;
+}
+export default MistSignaling;