@livepeer-frameworks/player-core 0.0.3

package/dist/types/players/MewsWsPlayer/SourceBufferManager.d.ts

@@ -0,0 +1,119 @@
+/**
+ * SourceBuffer Manager for MEWS Player
+ *
+ * Handles MediaSource Extension (MSE) buffer operations.
+ * Ported from reference: mews.js:206-384
+ *
+ * Key features:
+ * - Buffer creation and codec configuration
+ * - Append queue management with _append/_do/_doNext pattern
+ * - QuotaExceededError handling
+ * - Buffer cleanup (_clean)
+ * - Track switch msgqueue handling
+ */
+import type { SourceBufferManagerOptions } from './types';
+export declare class SourceBufferManager {
+    private mediaSource;
+    private videoElement;
+    private sourceBuffer;
+    private onError;
+    private queue;
+    private _busy;
+    private do_on_updateend;
+    private msgqueue;
+    private _codecs;
+    private fragmentCount;
+    paused: boolean;
+    private debugging;
+    constructor(options: SourceBufferManagerOptions);
+    /**
+     * Initialize the SourceBuffer with the given codecs.
+     * Ported from mews.js:206-384 (sbinit function)
+     */
+    initWithCodecs(codecs: string[]): boolean;
+    /**
+     * Get current codecs
+     */
+    getCodecs(): string[];
+    /**
+     * Queue data for appending to the buffer.
+     * If a track switch is in progress (msgqueue active), data goes to the latest queue.
+     * Ported from mews.js:809-824
+     */
+    append(data: Uint8Array): void;
+    /**
+     * Internal append with error handling.
+     * Ported from mews.js:292-339
+     */
+    private _append;
+    /**
+     * Schedule an operation to run on next updateend.
+     * Ported from mews.js:281-283
+     */
+    _doNext(func: () => void): void;
+    /**
+     * Run operation now if not busy, otherwise schedule for updateend.
+     * Ported from mews.js:284-291
+     */
+    _do(func: (remaining?: Array<() => void>) => void): void;
+    /**
+     * Schedule an operation to run after the current SourceBuffer update completes.
+     * Public API for external callers.
+     */
+    scheduleAfterUpdate(fn: () => void): void;
+    /**
+     * Change codecs mid-stream (track switch).
+     * Uses message queue to prevent data loss during rapid switches.
+     * Ported from mews.js:623-788
+     */
+    changeCodecs(codecs: string[], switchPointMs?: number): void;
+    /**
+     * Check if two codec arrays are equivalent (order-independent)
+     */
+    private codecsEqual;
+    /**
+     * Find which buffer range contains the given position.
+     * Ported from mews.js:947-956
+     */
+    findBufferIndex(position: number): number | false;
+    /**
+     * Remove buffer content before keepaway seconds from current position.
+     * Ported from mews.js:370-379
+     */
+    _clean(keepaway?: number): void;
+    /**
+     * Clear buffer and reinitialize with new codecs.
+     * Ported from mews.js:696-730
+     */
+    private clearAndReinit;
+    /**
+     * Reinitialize buffer with new codecs.
+     * Ported from mews.js:703-724
+     */
+    private reinitBuffer;
+    /**
+     * Wait for playback to reach switch point, then clear and reinit.
+     * Ported from mews.js:751-785
+     */
+    private awaitSwitchingPoint;
+    /**
+     * Drain the oldest message queue and append its data.
+     * Called after source buffer reinit to flush queued track switch data.
+     * Ported from mews.js:341-367
+     */
+    private drainMessageQueue;
+    /**
+     * Install event handlers on the sourceBuffer.
+     * Ported from mews.js:224-279
+     */
+    private installEventHandlers;
+    /**
+     * Flush any pending queue data.
+     */
+    private flushQueue;
+    /**
+     * Check if there's an active message queue (track switch in progress)
+     */
+    hasActiveMessageQueue(): boolean;
+    destroy(): void;
+}

package/dist/types/players/MewsWsPlayer/WebSocketManager.d.ts

@@ -0,0 +1,60 @@
+/**
+ * WebSocket Manager for MEWS Player
+ *
+ * Handles WebSocket connection, reconnection with exponential backoff,
+ * message sending, and typed message listeners.
+ *
+ * Ported from reference: mews.js:387-883
+ */
+import type { WebSocketManagerOptions, MewsMessage, MewsMessageListener } from './types';
+export declare class WebSocketManager {
+    private ws;
+    private url;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private wasConnected;
+    private isDestroyed;
+    private pendingRetryTimers;
+    private listeners;
+    private onMessage;
+    private onOpen;
+    private onClose;
+    private onError;
+    constructor(options: WebSocketManagerOptions);
+    connect(): void;
+    /**
+     * Send a command with retry logic (3.3.6).
+     * If not connected, will retry up to 5 times with 500ms delay.
+     * If connection is closing/closed, will attempt reconnect then retry.
+     */
+    send(cmd: object, retry?: number): boolean;
+    private clearReconnectTimer;
+    destroy(): void;
+    isConnected(): boolean;
+    /**
+     * Add a listener for a specific message type.
+     * Ported from mews.js:441-444
+     *
+     * @param type - Message type to listen for (e.g., 'on_time', 'codec_data', 'seek')
+     * @param callback - Function to call when message is received
+     */
+    addListener(type: string, callback: MewsMessageListener): void;
+    /**
+     * Remove a listener for a specific message type.
+     * Ported from mews.js:445-450
+     *
+     * @param type - Message type
+     * @param callback - The exact callback function to remove
+     * @returns true if listener was found and removed
+     */
+    removeListener(type: string, callback: MewsMessageListener): boolean;
+    /**
+     * Notify all listeners for a given message type.
+     * Called internally when a JSON message is received.
+     * Ported from mews.js:795-799
+     *
+     * @param msg - Parsed message object
+     */
+    notifyListeners(msg: MewsMessage): void;
+}

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

@@ -0,0 +1,220 @@
+/**
+ * MEWS WebSocket Player Implementation
+ *
+ * Low-latency WebSocket MP4 streaming using MediaSource Extensions.
+ * Protocol: Custom MEWS (MistServer Extended WebSocket)
+ *
+ * Ported from reference: mews.js (MistMetaPlayer)
+ */
+import { BasePlayer } from '../../core/PlayerInterface';
+import type { StreamSource, StreamInfo, PlayerOptions, PlayerCapability } from '../../core/PlayerInterface';
+export declare class MewsWsPlayerImpl extends BasePlayer {
+    readonly capability: PlayerCapability;
+    private wsManager;
+    private sbManager;
+    private mediaSource;
+    private objectUrl;
+    private container;
+    private isDestroyed;
+    private debugging;
+    private serverDelays;
+    private pendingDelayTypes;
+    private supportedCodecs;
+    private isReady;
+    private readyResolvers;
+    private lastDuration;
+    private streamType;
+    private currentTracks;
+    private lastCodecs;
+    private requestedRate;
+    private bitCounter;
+    private bitsSince;
+    private currentBps;
+    private nWaiting;
+    private nWaitingThreshold;
+    private seeking;
+    private analyticsConfig;
+    private analyticsTimer;
+    isMimeSupported(mimetype: string): boolean;
+    isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions): Promise<HTMLVideoElement>;
+    /**
+     * Handle MediaSource sourceopen event.
+     * Ported from mews.js:143-148, 198-204, 885-902
+     */
+    private handleSourceOpen;
+    /**
+     * Handle MediaSource sourceclose event.
+     * Ported from mews.js:150-153
+     */
+    private handleSourceClose;
+    /**
+     * Handle MediaSource sourceended event.
+     * Ported from mews.js:154-194
+     */
+    private handleSourceEnded;
+    /**
+     * Handle WebSocket open event.
+     * Ported from mews.js:401-403, 885-902
+     */
+    private handleWsOpen;
+    /**
+     * Handle WebSocket close event with reconnection logic.
+     * Ported from mews.js:408-431
+     */
+    private handleWsClose;
+    /**
+     * Handle incoming WebSocket message.
+     * Routes to binary append or JSON control message handler.
+     * Ported from mews.js:456-830
+     */
+    private handleMessage;
+    /**
+     * Handle JSON control messages.
+     * Ported from mews.js:461-799
+     */
+    private handleControlMessage;
+    /**
+     * Handle on_stop message - stream ended (VoD).
+     * Ported from mews.js:462-471
+     */
+    private handleOnStop;
+    /**
+     * Handle on_time message - playback time sync.
+     * Ported from mews.js:473-621
+     */
+    private handleOnTime;
+    /**
+     * Tune playback rate for live streams.
+     * Ported from mews.js:508-545
+     *
+     * Fixed: Use direct assignment instead of multiplication to prevent
+     * compounding rate adjustments on each on_time message.
+     */
+    private tuneLivePlaybackRate;
+    /**
+     * Tune server delivery speed for VoD.
+     * Ported from mews.js:547-586
+     */
+    private tuneVodDeliverySpeed;
+    /**
+     * Handle tracks message - codec switch.
+     * Ported from mews.js:623-788
+     */
+    private handleTracks;
+    /**
+     * Handle pause message.
+     * Ported from mews.js:790-792
+     */
+    private handlePause;
+    /**
+     * Set video currentTime with retry logic.
+     * Ported from mews.js:635-672
+     */
+    private setSeekingPosition;
+    /**
+     * Check if two codec arrays are equivalent (order-independent)
+     */
+    private codecsEqual;
+    /**
+     * Play with optional skip to live edge.
+     * Ported from mews.js:959-1023
+     */
+    play(): Promise<void>;
+    /**
+     * Pause playback and server delivery.
+     * Ported from mews.js:1025-1029
+     */
+    pause(): void;
+    /**
+     * Seek to position with server sync.
+     * Ported from mews.js:1071-1111
+     */
+    seek(time: number): void;
+    /**
+     * Try to set currentTime with retry logic.
+     * Ported from mews.js:1092-1103
+     */
+    private trySetCurrentTime;
+    getCurrentTime(): number;
+    getDuration(): number;
+    /**
+     * Set playback rate.
+     * Ported from mews.js:1119-1129
+     */
+    setPlaybackRate(rate: number): void;
+    getQualities(): Array<{
+        id: string;
+        label: string;
+        isAuto?: boolean;
+        active?: boolean;
+    }>;
+    selectQuality(id: string): void;
+    /**
+     * Set tracks for ABR or quality selection.
+     * Ported from mews.js:1030-1037
+     */
+    setTracks(obj: {
+        video?: string;
+        audio?: string;
+        subtitle?: string;
+    }): void;
+    /**
+     * Select a subtitle track.
+     */
+    selectTextTrack(id: string | null): void;
+    isLive(): boolean;
+    /**
+     * Jump to live edge.
+     */
+    jumpToLive(): void;
+    getStats(): Promise<any>;
+    /**
+     * Install waiting event handler.
+     * Handles buffer gaps and ABR.
+     * Ported from mews.js:1177-1186, 1272-1278
+     */
+    private installWaitingHandler;
+    /**
+     * Install seeking event handlers.
+     * Ported from mews.js:1169-1175
+     */
+    private installSeekingHandler;
+    /**
+     * Install pause event handler for browser pause detection.
+     * Ported from mews.js:1188-1200
+     */
+    private installPauseHandler;
+    /**
+     * Install loop handler for VoD content.
+     * Ported from mews.js:1157-1167
+     */
+    private installLoopHandler;
+    /**
+     * Send command to server with retry.
+     * Ported from mews.js:904-944
+     */
+    private send;
+    /**
+     * Log delay for server RTT estimation.
+     * Ported from mews.js:835-862
+     */
+    private logDelay;
+    /**
+     * Resolve delay measurement.
+     * Ported from mews.js:855-861, 863-867
+     */
+    private resolveDelay;
+    /**
+     * Get average server delay.
+     * Ported from mews.js:869-881
+     */
+    private getServerDelay;
+    /**
+     * Track bandwidth for ABR.
+     * Ported from mews.js:1280-1303
+     */
+    private trackBits;
+    private startTelemetry;
+    destroy(): Promise<void>;
+}

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

@@ -0,0 +1,89 @@
+/**
+ * MEWS WebSocket Player Types
+ */
+export interface MewsMessage {
+    type: string;
+    data?: any;
+}
+export interface CodecDataMessage extends MewsMessage {
+    type: 'codec_data';
+    data: {
+        codecs: string[];
+    };
+}
+export interface OnTimeMessage extends MewsMessage {
+    type: 'on_time';
+    data: {
+        current: number;
+        end?: number;
+        begin?: number;
+        play_rate_curr?: 'auto' | number;
+        jitter?: number;
+        tracks?: string[];
+    };
+}
+export interface TracksMessage extends MewsMessage {
+    type: 'tracks';
+    data: {
+        codecs: string[];
+        current?: number;
+    };
+}
+export interface OnStopMessage extends MewsMessage {
+    type: 'on_stop';
+}
+export interface SeekAckMessage extends MewsMessage {
+    type: 'seek';
+}
+export interface SetSpeedAckMessage extends MewsMessage {
+    type: 'set_speed';
+    data?: {
+        play_rate_curr?: 'auto' | number;
+    };
+}
+export interface PauseMessage extends MewsMessage {
+    type: 'pause';
+}
+export interface MewsCommand {
+    type: 'request_codec_data' | 'play' | 'hold' | 'seek' | 'set_speed' | 'tracks';
+    [key: string]: any;
+}
+export interface RequestCodecDataCommand extends MewsCommand {
+    type: 'request_codec_data';
+    supported_codecs: string[];
+}
+export interface SeekCommand extends MewsCommand {
+    type: 'seek';
+    seek_time: number;
+}
+export interface SetSpeedCommand extends MewsCommand {
+    type: 'set_speed';
+    play_rate: number | 'auto';
+}
+export interface TracksCommand extends MewsCommand {
+    type: 'tracks';
+    video?: string;
+    subtitle?: string;
+}
+/**
+ * Callback for WebSocket message listeners.
+ * Listeners are registered per message type and receive parsed MewsMessage objects.
+ */
+export type MewsMessageListener = (msg: MewsMessage) => void;
+export interface WebSocketManagerOptions {
+    url: string;
+    maxReconnectAttempts?: number;
+    onMessage: (data: ArrayBuffer | string) => void;
+    onOpen: () => void;
+    onClose: () => void;
+    onError: (message: string) => void;
+}
+export interface SourceBufferManagerOptions {
+    mediaSource: MediaSource;
+    videoElement: HTMLVideoElement;
+    onError: (message: string) => void;
+}
+export interface AnalyticsConfig {
+    enabled: boolean;
+    endpoint: string | null;
+}

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

@@ -0,0 +1,25 @@
+import { BasePlayer } from '../core/PlayerInterface';
+import type { StreamSource, StreamInfo, PlayerOptions, PlayerCapability } from '../core/PlayerInterface';
+/**
+ * MistPlayerImpl - Legacy fallback player
+ *
+ * Simple passthrough to MistServer's native player.js embed.
+ * No codec preferences or fancy params - just let MistServer handle everything.
+ * This is the final fallback when other players fail.
+ */
+export declare class MistPlayerImpl extends BasePlayer {
+    readonly capability: PlayerCapability;
+    private container;
+    private mistDiv;
+    private proxyVideo;
+    private previousContainerOverflow;
+    private destroyed;
+    isMimeSupported(mimetype: string): boolean;
+    isBrowserSupported(mimetype: string, _source: StreamSource, _streamInfo: StreamInfo): boolean | string[];
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions): Promise<HTMLVideoElement>;
+    private getPlayerJsUrl;
+    private loadAndPlay;
+    private findVideoElement;
+    private createProxyVideo;
+    destroy(): Promise<void>;
+}

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

@@ -0,0 +1,133 @@
+/**
+ * MistWebRTCPlayerImpl - IPlayer implementation for MistServer native WebRTC
+ *
+ * Uses MistServer's WebSocket signaling protocol instead of WHEP.
+ * Key advantages over WHEP:
+ * - Server-side track selection via signaling
+ * - Playback speed control (including "auto" for live catch-up)
+ * - Seeking via signaling (DVR support)
+ * - Real-time buffer_window updates
+ * - DataChannel for timed metadata
+ */
+import { BasePlayer } from '../../core/PlayerInterface';
+import type { StreamSource, StreamInfo, PlayerOptions, PlayerCapability } from '../../core/PlayerInterface';
+export declare class MistWebRTCPlayerImpl extends BasePlayer {
+    readonly capability: PlayerCapability;
+    private signaling;
+    private peerConnection;
+    private dataChannel;
+    private container;
+    private destroyed;
+    private seekOffset;
+    private durationMs;
+    private isLiveStream;
+    private playRate;
+    private bufferWindow;
+    private currentTracks;
+    private currentSource;
+    private currentOptions;
+    private lastInboundStats;
+    /**
+     * Chrome on Android has a bug where H264 is not available immediately
+     * after the tab is opened. Retry up to 5 times with 100ms intervals.
+     * https://bugs.chromium.org/p/webrtc/issues/detail?id=11620
+     */
+    private checkH264Available;
+    /**
+     * Load MistServer's WebRTC browser equalizer script for browser-specific fixes.
+     * This is non-fatal if it fails to load.
+     */
+    private loadBrowserEqualizer;
+    /**
+     * Compare two arrays for equality (order-independent)
+     */
+    private arraysEqual;
+    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>;
+    seek(time: number): void;
+    setPlaybackRate(rate: number): void;
+    jumpToLive(): void;
+    isLive(): boolean;
+    getDuration(): number;
+    getCurrentTime(): number;
+    /**
+     * Get available quality levels from signaling
+     */
+    getQualities(): Array<{
+        id: string;
+        label: string;
+        isAuto?: boolean;
+        active?: boolean;
+    }>;
+    selectQuality(id: string): void;
+    selectTextTrack(id: string | null): void;
+    getStats(): Promise<{
+        type: 'webrtc';
+        video?: {
+            bytesReceived: number;
+            packetsReceived: number;
+            packetsLost: number;
+            packetLossRate: number;
+            jitter: number;
+            framesDecoded: number;
+            framesDropped: number;
+            frameDropRate: number;
+            frameWidth: number;
+            frameHeight: number;
+            framesPerSecond: number;
+            bitrate: number;
+            jitterBufferDelay: number;
+        };
+        audio?: {
+            bytesReceived: number;
+            packetsReceived: number;
+            packetsLost: number;
+            packetLossRate: number;
+            jitter: number;
+            bitrate: number;
+        };
+        network?: {
+            rtt: number;
+            availableOutgoingBitrate: number;
+            availableIncomingBitrate: number;
+            bytesSent: number;
+            bytesReceived: number;
+        };
+        timestamp: number;
+    } | undefined>;
+    getLatency(): Promise<{
+        estimatedMs: number;
+        jitterBufferMs: number;
+        rttMs: number;
+    } | undefined>;
+    /**
+     * Get the current buffer window in milliseconds (P2)
+     * This is the difference between buffer end and begin from on_time messages.
+     */
+    getBufferWindow(): number;
+    /**
+     * Request video track matching the given player size (P2 - ABR_resize)
+     * Uses MistServer's ~widthxheight track selection syntax.
+     */
+    setQualityForSize(size: {
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Get the metadata DataChannel for timed metadata (P2)
+     * Returns the RTCDataChannel or null if not available.
+     */
+    getMetaDataChannel(): RTCDataChannel | null;
+    /**
+     * Override to add WebRTC-specific event handling:
+     * - Loop reconnect for VoD (P1)
+     * - Proper autoplay disable (P2)
+     */
+    protected setupVideoEventListeners(video: HTMLVideoElement, options: PlayerOptions): void;
+    private setupWebRTC;
+    private setupSignalingHandlers;
+    private handleTimeUpdate;
+    private createAndSendOffer;
+}