@livepeer-frameworks/player-core 0.0.3

package/dist/types/players/WebCodecsPlayer/WebSocketController.d.ts

@@ -0,0 +1,164 @@
+/**
+ * WebSocketController - Control Channel & Binary Frame Routing
+ *
+ * Manages WebSocket connection to MistServer for raw frame streaming.
+ * Handles:
+ * - JSON control messages (play, hold, seek, etc.)
+ * - Binary frame routing to chunk parser
+ * - Reconnection with exponential backoff
+ * - Server delay estimation
+ *
+ * Based on MewsWsPlayer WebSocketManager with raw frame protocol support.
+ */
+import type { ControlCommand, CodecDataMessage, InfoMessage, OnTimeMessage, RawChunk, TrackInfo } from './types';
+/** Connection states */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/** Event types emitted by WebSocketController */
+export interface WebSocketControllerEvents {
+    statechange: ConnectionState;
+    codecdata: CodecDataMessage;
+    info: InfoMessage;
+    ontime: OnTimeMessage;
+    tracks: TrackInfo[];
+    chunk: RawChunk;
+    stop: void;
+    error: Error;
+}
+type EventListener<K extends keyof WebSocketControllerEvents> = (data: WebSocketControllerEvents[K]) => void;
+/** Options for WebSocketController */
+export interface WebSocketControllerOptions {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Maximum reconnection attempts (0 = unlimited) */
+    maxReconnectAttempts?: number;
+    /** Initial reconnection delay (ms) */
+    reconnectDelayMs?: number;
+    /** Maximum reconnection delay (ms) */
+    maxReconnectDelayMs?: number;
+    /** Connection timeout (ms) */
+    connectionTimeoutMs?: number;
+}
+/**
+ * WebSocketController - Manages raw frame WebSocket connection
+ */
+export declare class WebSocketController {
+    private ws;
+    private url;
+    private options;
+    private state;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private connectionTimer;
+    private listeners;
+    private serverDelay;
+    private intentionalClose;
+    constructor(url: string, options?: WebSocketControllerOptions);
+    /**
+     * Connect to WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Send a control command
+     */
+    send(command: ControlCommand): boolean;
+    /**
+     * Request playback start
+     */
+    play(): boolean;
+    /**
+     * Request playback pause
+     */
+    hold(): boolean;
+    /**
+     * Seek to position
+     * @param timeMs - Target time in milliseconds
+     * @param fastForwardMs - Additional buffer to request (ms)
+     */
+    seek(timeMs: number, fastForwardMs?: number): boolean;
+    /**
+     * Set playback speed
+     */
+    setSpeed(rate: number | 'auto'): boolean;
+    /**
+     * Request codec initialization data
+     * @param supportedCombinations - Array of codec combinations we can play
+     *   Format: [[ ["H264"], ["AAC"] ]] means "H264 video AND AAC audio"
+     *   Per MistServer rawws.js line 1544
+     */
+    requestCodecData(supportedCombinations?: string[][][]): boolean;
+    /**
+     * Request additional data (fast-forward for buffer recovery)
+     */
+    fastForward(ms: number): boolean;
+    /**
+     * Get current connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Get estimated server delay
+     */
+    getServerDelay(): number;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Add event listener
+     */
+    on<K extends keyof WebSocketControllerEvents>(event: K, listener: EventListener<K>): void;
+    /**
+     * Remove event listener
+     */
+    off<K extends keyof WebSocketControllerEvents>(event: K, listener: EventListener<K>): void;
+    /**
+     * Emit event to listeners
+     */
+    private emit;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    private lastDeltaLogTime;
+    private deltaLogInterval;
+    /**
+     * Handle binary frame data
+     */
+    private handleBinaryMessage;
+    /**
+     * Handle JSON control message
+     *
+     * Per MistServer util.js line 1301, we need to unwrap the `data` field:
+     * MistServer sends: { type: "codec_data", data: { codecs: [...], tracks: [...] } }
+     * We need to emit: { type: "codec_data", codecs: [...], tracks: [...] }
+     */
+    private handleControlMessage;
+    /**
+     * Set connection state and emit event
+     */
+    private setState;
+    /**
+     * Check if should attempt reconnection
+     */
+    private shouldReconnect;
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    private scheduleReconnect;
+    /**
+     * Clear reconnect timer
+     */
+    private clearReconnectTimer;
+    /**
+     * Clear connection timer
+     */
+    private clearConnectionTimer;
+    /**
+     * Log message (if debug enabled)
+     */
+    private log;
+}
+export {};

package/dist/types/players/WebCodecsPlayer/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * WebCodecs Player Implementation
+ *
+ * Low-latency WebSocket streaming using WebCodecs API for video/audio decoding.
+ * Decoding runs in a Web Worker for optimal performance.
+ *
+ * Features:
+ * - Ultra-low latency streaming (configurable via profiles)
+ * - Worker-based VideoDecoder/AudioDecoder
+ * - Adaptive playback speed for live catchup/slowdown
+ * - Jitter compensation
+ * - Firefox polyfill for MediaStreamTrackGenerator
+ *
+ * Protocol: MistServer raw WebSocket frames (12-byte header + data)
+ */
+import { BasePlayer } from '../../core/PlayerInterface';
+import type { StreamSource, StreamInfo, PlayerOptions, PlayerCapability } from '../../core/PlayerInterface';
+import type { TrackInfo, WebCodecsStats } from './types';
+/**
+ * WebCodecsPlayerImpl - WebCodecs-based low-latency player
+ */
+export declare class WebCodecsPlayerImpl extends BasePlayer {
+    readonly capability: PlayerCapability;
+    private wsController;
+    private syncController;
+    private worker;
+    private mediaStream;
+    private container;
+    private pipelines;
+    private tracks;
+    private tracksByIndex;
+    private queuedInitData;
+    private queuedChunks;
+    private isDestroyed;
+    private debugging;
+    private verboseDebugging;
+    private streamType;
+    private workerUidCounter;
+    private workerListeners;
+    private _duration;
+    private _currentTime;
+    private _bufferMs;
+    private _avDrift;
+    private _frameCallbackId;
+    private _statsInterval;
+    private _framesDropped;
+    private _framesDecoded;
+    private _bytesReceived;
+    private _messagesReceived;
+    private static codecCache;
+    /**
+     * Get cache key for a track's codec configuration
+     */
+    private static getCodecCacheKey;
+    /**
+     * Test if a track's codec is supported by WebCodecs
+     * Reference: rawws.js:75-137 - isTrackSupported()
+     */
+    static isTrackSupported(track: TrackInfo): Promise<{
+        supported: boolean;
+        config: any;
+    }>;
+    /**
+     * Validate all tracks and return which are supported
+     * Returns array of supported track types ('video', 'audio')
+     */
+    static validateTracks(tracks: TrackInfo[]): Promise<string[]>;
+    isMimeSupported(mimetype: string): boolean;
+    isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions, streamInfo?: StreamInfo): Promise<HTMLVideoElement>;
+    destroy(): Promise<void>;
+    /**
+     * Try to load a worker from a URL with proper async error detection.
+     * new Worker() doesn't throw on invalid URLs - it fires error events async.
+     */
+    private tryLoadWorker;
+    private initializeWorker;
+    private sendToWorker;
+    private handleWorkerMessage;
+    private setupWebSocketHandlers;
+    private handleCodecData;
+    /**
+     * Handle stream info message containing track metadata
+     * This is sent by MistServer with full track information
+     */
+    private handleInfo;
+    private handleOnTime;
+    private handleTracksChange;
+    private handleChunk;
+    private sendChunkToWorker;
+    private handleStop;
+    private handleError;
+    private createPipeline;
+    private configurePipeline;
+    private closePipeline;
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): void;
+    setPlaybackRate(rate: number): void;
+    isLive(): boolean;
+    jumpToLive(): void;
+    /**
+     * Check if seeking is supported.
+     * WebCodecs can seek via server commands when connected.
+     * Reference: rawws.js line 1294-1304 implements seeking via control channel
+     */
+    canSeek(): boolean;
+    /**
+     * Get stream duration (Infinity for live streams)
+     */
+    get duration(): number;
+    getDuration(): number;
+    /**
+     * Get current playback time (seconds)
+     * Uses requestVideoFrameCallback for accurate timing when available
+     */
+    get currentTime(): number;
+    getCurrentTime(): number;
+    /**
+     * Get buffered time ranges
+     * Returns single range from current time to current + buffer
+     */
+    get buffered(): TimeRanges;
+    /**
+     * Get comprehensive player statistics
+     */
+    getStats(): Promise<WebCodecsStats>;
+    /**
+     * Set up requestVideoFrameCallback for accurate frame timing
+     * This provides vsync-aligned frame metadata for A/V sync
+     */
+    private setupFrameCallback;
+    /**
+     * Handle video frame presentation callback
+     * Updates current time
+     */
+    private onVideoFrame;
+    /**
+     * Cancel frame callback on cleanup
+     */
+    private cancelFrameCallback;
+    private log;
+}
+export { WebSocketController } from './WebSocketController';
+export { SyncController } from './SyncController';
+export { JitterTracker, MultiTrackJitterTracker } from './JitterBuffer';
+export { getLatencyProfile, mergeLatencyProfile, LATENCY_PROFILES } from './LatencyProfiles';
+export { parseRawChunk, RawChunkParser } from './RawChunkParser';
+export * from './types';

package/dist/types/players/WebCodecsPlayer/polyfills/MediaStreamTrackGenerator.d.ts

@@ -0,0 +1,105 @@
+/**
+ * MediaStreamTrackGenerator Polyfill
+ *
+ * Provides fallback for browsers without native MediaStreamTrackGenerator (Firefox).
+ *
+ * Video: Uses Canvas2D + captureStream()
+ * Audio: Uses AudioWorklet + createMediaStreamDestination()
+ *
+ * Based on legacy rawws.js polyfill with improvements:
+ * - TypeScript types
+ * - Pull-based audio to prevent tin-can distortion
+ * - Better resource cleanup
+ */
+/**
+ * Check if native MediaStreamTrackGenerator is available
+ */
+export declare function hasNativeMediaStreamTrackGenerator(): boolean;
+/**
+ * Polyfill for MediaStreamTrackGenerator (video)
+ *
+ * Uses an offscreen canvas and captureStream() to create a MediaStreamTrack
+ * that can be fed VideoFrames via a WritableStream.
+ */
+export declare class VideoTrackGeneratorPolyfill {
+    private canvas;
+    private ctx;
+    private track;
+    private _writable;
+    private closed;
+    constructor();
+    /**
+     * Get the writable stream for writing VideoFrames
+     */
+    get writable(): WritableStream<VideoFrame>;
+    /**
+     * Get the MediaStreamTrack for adding to MediaStream
+     */
+    getTrack(): MediaStreamTrack;
+    /**
+     * Close and cleanup resources
+     */
+    close(): void;
+}
+/**
+ * Polyfill for MediaStreamTrackGenerator (audio)
+ *
+ * Uses AudioWorklet to create a pull-based audio output that prevents
+ * the "tin-can" distortion issue from the legacy implementation.
+ *
+ * Key improvement: Audio samples are pulled by the worklet at a fixed rate,
+ * and we feed samples proactively rather than pushing them as they arrive.
+ */
+export declare class AudioTrackGeneratorPolyfill {
+    private audioContext;
+    private destination;
+    private workletNode;
+    private track;
+    private _writable;
+    private closed;
+    private initialized;
+    private initPromise;
+    private sampleBuffer;
+    private maxBufferChunks;
+    constructor();
+    /**
+     * Initialize the AudioWorklet
+     */
+    private initializeWorklet;
+    /**
+     * Convert AudioData to mono Float32Array
+     */
+    private audioDataToSamples;
+    /**
+     * Feed samples to the worklet
+     */
+    private feedSamples;
+    /**
+     * Get the writable stream for writing AudioData
+     */
+    get writable(): WritableStream<AudioData>;
+    /**
+     * Get the MediaStreamTrack for adding to MediaStream
+     */
+    getTrack(): MediaStreamTrack;
+    /**
+     * Wait for initialization to complete
+     */
+    waitForInit(): Promise<void>;
+    /**
+     * Close and cleanup resources
+     */
+    close(): void;
+}
+/**
+ * Create appropriate track generator based on browser support
+ *
+ * @param kind - 'video' or 'audio'
+ * @returns Native generator or polyfill
+ */
+export declare function createTrackGenerator(kind: 'video' | 'audio'): {
+    writable: WritableStream<VideoFrame | AudioData>;
+    getTrack: () => MediaStreamTrack;
+    close: () => void;
+    waitForInit?: () => Promise<void>;
+};