@livepeer-frameworks/player-core 0.0.3

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

@@ -0,0 +1,143 @@
+import { BasePlayer } from '../core/PlayerInterface';
+import type { StreamSource, StreamInfo, PlayerOptions, PlayerCapability } from '../core/PlayerInterface';
+/**
+ * Native Player Implementation
+ *
+ * Handles direct playback using native browser APIs:
+ * - HTML5 video element for direct media
+ * - WHEP (WebRTC HTTP Egress Protocol) for WebRTC streams
+ *
+ * Ported from reference html5.js with:
+ * - Live duration proxy for meaningful seek bar
+ * - Auto-recovery on long pause (reload after 5s)
+ * - MP3 seeking restriction
+ * - Dynamic source switching via setSource()
+ */
+export declare class NativePlayerImpl extends BasePlayer {
+    readonly capability: PlayerCapability;
+    private peerConnection;
+    private sessionUrl;
+    private lastInboundStats;
+    private reconnectEnabled;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectTimer;
+    private currentWhepUrl;
+    private currentHeaders;
+    private currentIceServers;
+    private container;
+    private destroyed;
+    private liveDurationProxy;
+    private pausedAt;
+    private currentSourceUrl;
+    private currentMimeType;
+    private isMP3Source;
+    private liveSeekEnabled;
+    private liveSeekOffsetSec;
+    private liveSeekBaseUrl;
+    private liveSeekListeners;
+    private liveSeekTimer;
+    private pendingLiveSeekOffset;
+    private static readonly PAUSE_RECOVERY_THRESHOLD;
+    private static readonly LIVE_SEEK_DEBOUNCE_MS;
+    isMimeSupported(mimetype: string): boolean;
+    isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
+    private translateCodecForHtml5;
+    private getAndroidVersion;
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions, streamInfo?: StreamInfo): Promise<HTMLVideoElement>;
+    /**
+     * Setup live duration proxy for meaningful seek bar on live streams
+     * Ported from reference html5.js:194-202
+     */
+    private setupLiveDurationProxy;
+    /**
+     * Setup auto-recovery on long pause
+     * Ported from reference html5.js:227-239
+     *
+     * If the stream has been paused for more than 5 seconds,
+     * reload the stream on play to recover from stale buffer.
+     */
+    private setupAutoRecovery;
+    /**
+     * Set a new source URL dynamically
+     * Ported from reference html5.js:276-281
+     */
+    setSource(url: string): void;
+    /**
+     * Override seek for MP3 files (seeking not supported)
+     * Ported from reference html5.js:185-191
+     */
+    seek(time: number): void;
+    /**
+     * Get the calculated duration (live-aware)
+     */
+    getDuration(): number;
+    getCurrentTime(): number;
+    getSeekableRange(): {
+        start: number;
+        end: number;
+    } | null;
+    getBufferedRanges(): TimeRanges | null;
+    /**
+     * Check if current stream is live
+     */
+    isLive(): boolean;
+    /**
+     * Get live latency in seconds
+     */
+    getLiveLatency(): number;
+    /**
+     * Jump to live edge
+     */
+    jumpToLive(): void;
+    destroy(): Promise<void>;
+    private stripStartUnixParam;
+    private buildLiveSeekUrl;
+    private applyLiveSeekOffset;
+    private createTimeRanges;
+    private scheduleLiveSeekOffset;
+    /**
+     * Get WebRTC-specific stats including RTT, packet loss, jitter, bitrate
+     */
+    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>;
+    private startWhep;
+}
+export { NativePlayerImpl as DirectPlaybackPlayerImpl };

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

@@ -0,0 +1,59 @@
+import { BasePlayer } from '../core/PlayerInterface';
+import type { StreamSource, StreamInfo, PlayerOptions, PlayerCapability } from '../core/PlayerInterface';
+export declare class VideoJsPlayerImpl extends BasePlayer {
+    readonly capability: PlayerCapability;
+    private videojsPlayer;
+    private container;
+    private destroyed;
+    private timeCorrection;
+    private proxyElement;
+    private currentStreamInfo;
+    private liveDurationProxy;
+    isMimeSupported(mimetype: string): boolean;
+    isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions, streamInfo?: StreamInfo): Promise<HTMLVideoElement>;
+    /**
+     * Creates a Proxy wrapper around the video element that corrects
+     * currentTime/duration/buffered using the firstms offset from MistServer.
+     * This ensures timestamps align with MistServer's track metadata.
+     */
+    private createTimeCorrectedProxy;
+    private getVideoJsType;
+    setPlaybackRate(rate: number): void;
+    getCurrentTime(): number;
+    getSeekableRange(): {
+        start: number;
+        end: number;
+    } | null;
+    /**
+     * Seek to time using VideoJS API (fixes backwards seeking in HLS).
+     * Time should be in the corrected coordinate space (with firstms offset applied).
+     */
+    seek(time: number): void;
+    /**
+     * Get VideoJS-specific stats for playback monitoring
+     */
+    getStats(): Promise<{
+        type: 'videojs';
+        buffered: number;
+        currentTime: number;
+        duration: number;
+        readyState: number;
+        networkState: number;
+        playbackRate: number;
+    } | undefined>;
+    /**
+     * Check if the stream is live
+     */
+    isLiveStream(): boolean;
+    /**
+     * Jump to live edge
+     * Uses VideoJS liveTracker when available, otherwise LiveDurationProxy
+     */
+    jumpToLive(): void;
+    /**
+     * Get latency from live edge (for live streams)
+     */
+    getLiveLatency(): number;
+    destroy(): Promise<void>;
+}

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

@@ -0,0 +1,118 @@
+/**
+ * JitterBuffer - Network Jitter Estimation
+ *
+ * Tracks network jitter to inform buffer sizing decisions.
+ * Ported from legacy rawws.js JitterTracker with improvements:
+ * - Per-track jitter tracking (audio/video can differ)
+ * - TypeScript types
+ * - Better edge case handling
+ *
+ * Algorithm:
+ * 1. Track arrival time vs media time for last N chunks
+ * 2. Calculate jitter = (mediaTimePassed / speed) - clockTimePassed
+ * 3. Maintain sliding window of peak jitter per second
+ * 4. Weighted average: (avgPeak + maxPeak * 2) / 3 + 1ms
+ * 5. Limit lowering rate to prevent oscillation
+ */
+import type { JitterState } from './types';
+export interface JitterTrackerOptions {
+    /** Initial jitter estimate (ms) */
+    initialJitter?: number;
+    /** Sliding window size for chunks */
+    chunkWindowSize?: number;
+    /** Sliding window size for peaks */
+    peakWindowSize?: number;
+}
+/**
+ * JitterTracker - Estimates network jitter for a single track
+ */
+export declare class JitterTracker {
+    /** Sliding window of chunk timings */
+    private chunks;
+    /** Current playback speed (1 = realtime) */
+    private speed;
+    /** Last time a peak was recorded */
+    private lastPeakTime;
+    /** Maximum jitter observed in current interval */
+    private currentPeak;
+    /** Sliding window of peak jitter values */
+    private peaks;
+    /** Weighted average jitter estimate */
+    private maxJitter;
+    /** Configuration */
+    private readonly chunkWindowSize;
+    private readonly peakWindowSize;
+    constructor(options?: JitterTrackerOptions);
+    /**
+     * Add a received chunk to jitter calculation
+     *
+     * @param mediaTime - Media timestamp from chunk (ms)
+     * @param receiveTime - Wall clock time (performance.now())
+     */
+    addChunk(mediaTime: number, receiveTime?: number): void;
+    /**
+     * Calculate current instantaneous jitter
+     */
+    private calculateJitter;
+    /**
+     * Record current peak and update weighted average
+     */
+    private recordPeak;
+    /**
+     * Get current jitter estimate (ms)
+     */
+    get(): number;
+    /**
+     * Get detailed jitter state
+     */
+    getState(): JitterState;
+    /**
+     * Set playback speed for jitter calculation
+     */
+    setSpeed(speed: number | 'auto'): void;
+    /**
+     * Reset jitter tracking (e.g., after seek)
+     */
+    reset(): void;
+    /**
+     * Full reset including learned jitter estimate
+     */
+    fullReset(): void;
+}
+/**
+ * MultiTrackJitterTracker - Manages jitter tracking for multiple tracks
+ */
+export declare class MultiTrackJitterTracker {
+    private trackers;
+    private globalSpeed;
+    private options;
+    constructor(options?: JitterTrackerOptions);
+    /**
+     * Add a chunk for a specific track
+     */
+    addChunk(trackIndex: number, mediaTime: number, receiveTime?: number): void;
+    /**
+     * Get maximum jitter across all tracks
+     */
+    getMax(): number;
+    /**
+     * Get jitter for a specific track
+     */
+    getForTrack(trackIndex: number): number;
+    /**
+     * Set playback speed for all trackers
+     */
+    setSpeed(speed: number | 'auto'): void;
+    /**
+     * Reset all trackers
+     */
+    reset(): void;
+    /**
+     * Remove a track's tracker
+     */
+    removeTrack(trackIndex: number): void;
+    /**
+     * Clear all trackers
+     */
+    clear(): void;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Latency Profiles for WebCodecs Player
+ *
+ * Presets for trading off latency vs stability.
+ *
+ * Buffer calculation: desiredBuffer = keepAway + serverDelay + (jitter * jitterMultiplier)
+ *
+ * Speed tweaking:
+ *   - If buffer > desired * speedUpThreshold → speed up to maxSpeedUp
+ *   - If buffer < desired * speedDownThreshold → slow down to minSpeedDown
+ */
+import type { LatencyProfile, LatencyProfileName } from './types';
+/**
+ * Ultra-low latency profile
+ * Target: <200ms end-to-end latency
+ * Use case: Real-time conferencing, remote control
+ * Trade-offs: May stutter on poor networks
+ */
+export declare const ULTRA_LOW_PROFILE: LatencyProfile;
+/**
+ * Low latency profile
+ * Target: ~300-500ms end-to-end latency
+ * Use case: Live sports, gaming streams
+ * Trade-offs: Balanced latency/stability
+ */
+export declare const LOW_PROFILE: LatencyProfile;
+/**
+ * Balanced profile
+ * Target: ~500-1000ms end-to-end latency
+ * Use case: General live streaming
+ * Trade-offs: Prioritizes stability over latency
+ */
+export declare const BALANCED_PROFILE: LatencyProfile;
+/**
+ * Quality priority profile
+ * Target: ~1-2s end-to-end latency
+ * Use case: VOD, recorded content, poor networks
+ * Trade-offs: Maximum stability, higher latency
+ */
+export declare const QUALITY_PROFILE: LatencyProfile;
+/**
+ * All available latency profiles
+ */
+export declare const LATENCY_PROFILES: Record<LatencyProfileName, LatencyProfile>;
+/**
+ * Get a latency profile by name
+ * @param name - Profile name
+ * @returns The profile, or 'low' as default
+ */
+export declare function getLatencyProfile(name?: LatencyProfileName): LatencyProfile;
+/**
+ * Merge a custom partial profile with a base profile
+ * @param base - Base profile name or profile object
+ * @param custom - Partial overrides
+ * @returns Merged profile
+ */
+export declare function mergeLatencyProfile(base: LatencyProfileName | LatencyProfile, custom?: Partial<LatencyProfile>): LatencyProfile;
+/**
+ * Select appropriate profile based on stream type
+ * @param isLive - Whether the stream is live
+ * @param preferLowLatency - Whether to prefer low latency (e.g., WebRTC source)
+ * @returns Recommended profile name
+ */
+export declare function selectDefaultProfile(isLive: boolean, preferLowLatency?: boolean): LatencyProfileName;

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

@@ -0,0 +1,63 @@
+/**
+ * RawChunkParser - Binary Frame Header Parser
+ *
+ * Parses the 12-byte binary header from MistServer's raw WebSocket stream.
+ *
+ * Header format:
+ *   Byte 0:     Track index (uint8)
+ *   Byte 1:     Chunk type: 0=delta, 1=key, 2=init
+ *   Bytes 2-9:  Timestamp in milliseconds (uint64 big-endian)
+ *   Bytes 10-11: Offset in milliseconds (int16 big-endian, signed)
+ *
+ * The offset is server-calculated and used for A/V synchronization.
+ * Combined presentation time = timestamp + offset
+ */
+import type { RawChunk } from './types';
+/**
+ * Parse a raw binary chunk from MistServer
+ *
+ * @param data - ArrayBuffer containing header + frame data
+ * @returns Parsed RawChunk object
+ * @throws Error if data is too short
+ */
+export declare function parseRawChunk(data: ArrayBuffer): RawChunk;
+/**
+ * Calculate the presentation timestamp for a chunk
+ * This combines the server timestamp with the sync offset
+ *
+ * @param chunk - Parsed raw chunk
+ * @returns Presentation timestamp in microseconds (for WebCodecs API)
+ */
+export declare function getPresentationTimestamp(chunk: RawChunk): number;
+/**
+ * Check if this chunk is a keyframe
+ */
+export declare function isKeyframe(chunk: RawChunk): boolean;
+/**
+ * Check if this chunk contains codec initialization data
+ */
+export declare function isInitData(chunk: RawChunk): boolean;
+/**
+ * Format chunk for debug logging
+ */
+export declare function formatChunkForLog(chunk: RawChunk): string;
+/**
+ * RawChunkParser class for stateful parsing with validation
+ */
+export declare class RawChunkParser {
+    private debug;
+    constructor(options?: {
+        debug?: boolean;
+    });
+    /**
+     * Parse binary data from WebSocket
+     *
+     * @param data - ArrayBuffer from WebSocket message
+     * @returns Parsed chunk or null if invalid
+     */
+    parse(data: ArrayBuffer): RawChunk | null;
+    /**
+     * Set debug mode
+     */
+    setDebug(enabled: boolean | 'verbose'): void;
+}

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

@@ -0,0 +1,174 @@
+/**
+ * SyncController - Buffer Management & Playback Timing
+ *
+ * Orchestrates:
+ * - Buffer level monitoring
+ * - Adaptive playback speed (catchup/slowdown)
+ * - Jitter tracking integration
+ * - Server delay estimation
+ * - Seek coordination
+ *
+ * Based on legacy rawws.js FrameTiming + buffer management with improvements:
+ * - Post-decode drift correction
+ * - Better seek cancellation
+ * - TypeScript types
+ */
+import type { LatencyProfile, SyncState, TrackInfo } from './types';
+/** Events emitted by SyncController */
+export interface SyncControllerEvents {
+    speedchange: {
+        speed: number;
+        reason: 'catchup' | 'slowdown' | 'normal';
+    };
+    bufferlow: {
+        current: number;
+        desired: number;
+    };
+    bufferhigh: {
+        current: number;
+        desired: number;
+    };
+    underrun: void;
+    livecatchup: {
+        fastForwardMs: number;
+    };
+    seekstart: {
+        seekId: number;
+        time: number;
+    };
+    seekcomplete: {
+        seekId: number;
+    };
+}
+type EventListener<K extends keyof SyncControllerEvents> = (data: SyncControllerEvents[K]) => void;
+/**
+ * SyncController - Manages playback synchronization
+ */
+export declare class SyncController {
+    private profile;
+    private jitterTracker;
+    private listeners;
+    private mainSpeed;
+    private tweakSpeed;
+    private lastBufferCheck;
+    private bufferCheckInterval;
+    private serverDelays;
+    private maxServerDelaysSamples;
+    private lastLiveCatchup;
+    private liveCatchupCooldown;
+    private liveCatchupThresholdMs;
+    private liveCatchupRequestMs;
+    private serverTime;
+    private localTimeAtServerUpdate;
+    private seekState;
+    private isLive;
+    private onSpeedChange?;
+    private onFastForwardRequest?;
+    constructor(options?: {
+        profile?: LatencyProfile;
+        isLive?: boolean;
+        onSpeedChange?: (main: number, tweak: number) => void;
+        onFastForwardRequest?: (ms: number) => void;
+    });
+    /**
+     * Update latency profile
+     */
+    setProfile(profile: LatencyProfile): void;
+    /**
+     * Update stream type (live vs VOD)
+     */
+    setLive(isLive: boolean): void;
+    /**
+     * Record a chunk arrival for jitter tracking
+     */
+    recordChunkArrival(trackIndex: number, mediaTimeMs: number): void;
+    /**
+     * Update server time from on_time message
+     */
+    updateServerTime(currentTime: number): void;
+    /**
+     * Record server delay measurement
+     */
+    recordServerDelay(delayMs: number): void;
+    /**
+     * Get current server delay estimate
+     */
+    getServerDelay(): number;
+    /**
+     * Get estimated current server time (interpolated)
+     */
+    getEstimatedServerTime(): number;
+    /**
+     * Calculate desired buffer size based on profile + jitter + server delay
+     * Matches MistServer mews.js pattern with Chrome-specific handling
+     */
+    getDesiredBuffer(): number;
+    /**
+     * Evaluate buffer state and adjust playback speed if needed
+     *
+     * @param currentBufferMs - Current buffer level in milliseconds
+     * @returns Updated sync state
+     */
+    evaluateBuffer(currentBufferMs: number): SyncState;
+    /**
+     * Get current sync state
+     */
+    getState(currentBufferMs?: number): SyncState;
+    /**
+     * Get combined playback speed (main * tweak)
+     */
+    getCombinedSpeed(): number;
+    /**
+     * Set main playback speed (user-controlled)
+     */
+    setMainSpeed(speed: number): void;
+    /**
+     * Set tweak speed (automatic adjustment)
+     */
+    private setTweakSpeed;
+    /**
+     * Notify external listeners of speed change
+     */
+    private notifySpeedChange;
+    /**
+     * Request additional data from server
+     */
+    private requestFastForward;
+    /**
+     * Start a seek operation
+     * Returns a seek ID that can be used to check if seek is still active
+     */
+    startSeek(targetTimeMs: number): number;
+    /**
+     * Check if a seek is still the active one
+     */
+    isSeekActive(seekId: number): boolean;
+    /**
+     * Complete a seek operation
+     */
+    completeSeek(seekId: number): void;
+    /**
+     * Cancel any active seek
+     */
+    cancelSeek(): void;
+    /**
+     * Check if currently seeking
+     */
+    isSeeking(): boolean;
+    /**
+     * Register a new track
+     */
+    addTrack(trackIndex: number, track: TrackInfo): void;
+    /**
+     * Remove a track
+     */
+    removeTrack(trackIndex: number): void;
+    /**
+     * Reset all state
+     */
+    reset(): void;
+    on<K extends keyof SyncControllerEvents>(event: K, listener: EventListener<K>): void;
+    off<K extends keyof SyncControllerEvents>(event: K, listener: EventListener<K>): void;
+    private emit;
+}
+export {};