@stinkycomputing/web-live-player 0.1.0

package/dist/scheduling/frame-scheduler.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Frame Scheduler
+ *
+ * Manages frame buffering and synchronization between stream framerate
+ * and display refresh rate.
+ */
+/**
+ * Frame timing information for latency tracking
+ */
+export interface FrameTiming {
+    /** When encoded data arrived (performance.now()) */
+    arrivalTime: number;
+    /** When decode completed (performance.now()) */
+    decodeTime: number;
+    /** When frame was displayed (performance.now()) */
+    displayTime?: number;
+}
+/**
+ * Latency statistics
+ */
+export interface LatencyStats {
+    /** Time from arrival to decode completion (ms) */
+    decodeLatency: number;
+    /** Time from decode to display (ms) */
+    bufferLatency: number;
+    /** Total time from arrival to display (ms) */
+    totalLatency: number;
+    /** Average latencies over recent frames */
+    avgDecodeLatency: number;
+    avgBufferLatency: number;
+    avgTotalLatency: number;
+}
+export interface SchedulerStatus {
+    currentBufferSize: number;
+    currentBufferMs: number;
+    avgBufferMs: number;
+    targetBufferMs: number;
+    streamFrameDurationUs: number | null;
+    droppedFrames: number;
+    totalEnqueuedFrames: number;
+    totalDequeuedFrames: number;
+    driftCorrections: number;
+    latency: LatencyStats | null;
+}
+export interface SchedulerConfig<T> {
+    /** Target buffer delay in milliseconds (0 = bypass mode, always return latest) */
+    bufferDelayMs?: number;
+    /** Maximum buffer size in frames before overflow */
+    maxBufferSize?: number;
+    /** How often to check drift (every N dequeues) */
+    driftCheckInterval?: number;
+    /** Drift threshold in milliseconds before correction */
+    driftCorrectionThresholdMs?: number;
+    /** Logger function */
+    logger?: (message: string) => void;
+    /** Callback when frame is dropped */
+    onFrameDropped?: (frame: T, reason: 'overflow' | 'skip') => void;
+}
+/**
+ * FrameScheduler - Simplified implementation
+ *
+ * Core algorithm:
+ * 1. On first dequeue with frames, record (realTime, streamTime) as start point
+ * 2. On each dequeue:
+ *    - Calculate expected stream time = startStreamTime + (currentRealTime - startRealTime) - bufferDelay
+ *    - Find frame with timestamp <= expectedStreamTime
+ *    - Drop old frames, return best match
+ * 3. Periodically adjust start point to correct drift
+ */
+export declare class FrameScheduler<T> {
+    private buffer;
+    private bufferDelayMs;
+    private maxBufferSize;
+    private startRealTimeUs;
+    private startStreamTimeUs;
+    private frameDurationUs;
+    private lastFrameTimestamp;
+    private bufferSizeHistory;
+    private driftCheckInterval;
+    private driftThresholdMs;
+    private dequeueCount;
+    private latencyHistory;
+    private latencyHistorySize;
+    private stats;
+    private logger;
+    private onFrameDropped?;
+    constructor(config?: SchedulerConfig<T>);
+    /** Buffer delay in microseconds */
+    private get bufferDelayUs();
+    /** Effective drift threshold - scales with buffer target for low-latency mode */
+    private get effectiveDriftThresholdMs();
+    /** Enqueue a decoded frame with timing information */
+    enqueue(frame: T, timestampUs: number, timing: FrameTiming): void;
+    /** Dequeue frame for rendering at given real time (milliseconds) */
+    dequeue(realTimeMs: number): T | null;
+    /** Bypass mode: return latest frame, drop rest */
+    private dequeueLatest;
+    /** Record latency for a frame */
+    private recordLatency;
+    /** Get current latency stats */
+    getLatencyStats(): LatencyStats | null;
+    /** Find index of last frame with timestamp <= target */
+    private findBestFrameIndex;
+    /** Drop N frames from front of buffer */
+    private dropFrames;
+    /** Track buffer size for drift detection */
+    private trackBufferSize;
+    /** Correct timing drift by adjusting start point */
+    private correctDrift;
+    /** Clear buffer */
+    clear(): void;
+    /** Set buffer delay in milliseconds */
+    setBufferDelay(delayMs: number): void;
+    /** Get current buffer delay in milliseconds */
+    getBufferDelay(): number;
+    /** Get status */
+    getStatus(): SchedulerStatus;
+    /** Log status */
+    logStatus(): void;
+    /** Reset statistics */
+    resetStats(): void;
+}

package/dist/scheduling/frame-scheduler.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * FrameScheduler Tests
+ *
+ * Tests for the critical frame scheduling and buffering logic.
+ * The scheduler is responsible for:
+ * - Buffering frames to handle network jitter
+ * - Synchronizing stream time to real time
+ * - Detecting and correcting drift
+ * - Dropping frames appropriately when falling behind
+ */
+export {};

package/dist/sources/mp4-file-source.d.ts

@@ -0,0 +1,143 @@
+/**
+ * MP4 File Source - Client-side MP4 demuxing using mp4box.js
+ *
+ * Loads MP4 files and extracts video/audio samples for decoding.
+ * Works entirely in the browser without a backend server.
+ */
+/**
+ * File metadata extracted from MP4
+ */
+export interface MP4FileInfo {
+    duration: number;
+    timescale: number;
+    width: number;
+    height: number;
+    videoCodec: string;
+    audioCodec?: string;
+    frameRate?: number;
+    bitrate?: number;
+    audioChannels?: number;
+    audioSampleRate?: number;
+}
+/**
+ * Sample ready for decoding
+ */
+export interface DecodableSample {
+    data: Uint8Array;
+    timestamp: number;
+    duration: number;
+    isKeyframe: boolean;
+    type: 'video' | 'audio';
+}
+/**
+ * Event handlers for MP4FileSource
+ */
+export interface MP4FileSourceEvents {
+    onReady?: (info: MP4FileInfo) => void;
+    onSamples?: (samples: DecodableSample[]) => void;
+    onError?: (error: Error) => void;
+    onProgress?: (loaded: number, total: number) => void;
+    onEnded?: () => void;
+}
+/**
+ * MP4 File Source - Demuxes MP4 files in the browser
+ */
+export declare class MP4FileSource {
+    private mp4File;
+    private fileInfo;
+    private videoTrackId;
+    private audioTrackId;
+    private videoTrack;
+    private audioTrack;
+    private nextVideoSampleIndex;
+    private nextAudioSampleIndex;
+    private totalVideoSamples;
+    private totalAudioSamples;
+    private samplesRequested;
+    private fileSize;
+    private loadedBytes;
+    private videoDescription;
+    private audioDescription;
+    private events;
+    constructor(events?: MP4FileSourceEvents);
+    /**
+     * Get the extracted file info
+     */
+    getFileInfo(): MP4FileInfo | null;
+    /**
+     * Get the video codec description (for VideoDecoder.configure)
+     */
+    getVideoDescription(): Uint8Array | null;
+    /**
+     * Get the audio codec description (for AudioDecoder.configure)
+     */
+    getAudioDescription(): Uint8Array | null;
+    /**
+     * Load an MP4 file from a URL
+     */
+    loadFromUrl(url: string): Promise<MP4FileInfo>;
+    /**
+     * Load an MP4 file from a File object (e.g., from file input)
+     */
+    loadFromFile(file: File): Promise<MP4FileInfo>;
+    /**
+     * Load from a ReadableStreamDefaultReader (for progressive loading)
+     * Uses WritableStream pattern for proper mp4box integration.
+     */
+    private loadFromStream;
+    /**
+     * Load from a complete ArrayBuffer
+     */
+    private loadFromArrayBuffer;
+    /**
+     * Initialize the mp4box ISOFile
+     */
+    private initMP4File;
+    /**
+     * Handle file ready event
+     */
+    private handleFileReady;
+    /**
+     * Request samples to be extracted
+     */
+    private requestSamples;
+    /**
+     * Handle samples from mp4box
+     */
+    private handleSamples;
+    /**
+     * Seek to a specific time in seconds
+     * Returns the actual seek time (may be different due to keyframe alignment)
+     */
+    seek(timeSeconds: number): number;
+    /**
+     * Get current position info
+     */
+    getPosition(): {
+        currentSample: number;
+        totalSamples: number;
+        progress: number;
+    };
+    /**
+     * Stop extraction
+     */
+    stop(): void;
+    /**
+     * Resume extraction
+     */
+    start(): void;
+    /**
+     * Dispose and clean up
+     */
+    dispose(): void;
+    /**
+     * Serialize avcC box content for WebCodecs description
+     * Format: AVCDecoderConfigurationRecord
+     */
+    private serializeAvcC;
+    /**
+     * Serialize hvcC box content for WebCodecs description
+     * Format: HEVCDecoderConfigurationRecord
+     */
+    private serializeHvcC;
+}

package/dist/sources/standalone-moq-source.d.ts

@@ -0,0 +1,44 @@
+import { BaseStreamSource } from './stream-source';
+
+/**
+ * Track configuration for standalone MoQ source
+ */
+export interface StandaloneMoQTrack {
+    trackName: string;
+    priority?: number;
+    streamType: 'video' | 'audio' | 'data';
+}
+/**
+ * Configuration for standalone MoQ source
+ */
+export interface StandaloneMoQConfig {
+    relayUrl: string;
+    namespace: string;
+    subscriptions: StandaloneMoQTrack[];
+    reconnectionDelay?: number;
+}
+/**
+ * Factory function to create a standalone MoQ source
+ */
+export declare function createStandaloneMoQSource(config: StandaloneMoQConfig): StandaloneMoQSource;
+/**
+ * Standalone MoQ stream source implementation
+ */
+export declare class StandaloneMoQSource extends BaseStreamSource {
+    private config;
+    private session;
+    private trackTypeMap;
+    private connecting;
+    constructor(config: StandaloneMoQConfig);
+    /**
+     * Connect to the MoQ relay
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the MoQ relay
+     */
+    disconnect(): Promise<void>;
+    private setupEventListeners;
+    private handleIncomingData;
+    dispose(): void;
+}

package/dist/sources/stream-source.d.ts

@@ -0,0 +1,73 @@
+import { ParsedData } from '../protocol/sesame-binary-protocol';
+
+/**
+ * Event data emitted when stream data is received
+ */
+export interface StreamDataEvent {
+    trackName: string;
+    streamType: 'video' | 'audio' | 'data';
+    data: ParsedData;
+}
+/**
+ * Handler type for stream data events
+ */
+export type StreamDataHandler = (event: StreamDataEvent) => void;
+/**
+ * Handler type for error events
+ */
+export type StreamErrorHandler = (error: Error) => void;
+/**
+ * Handler type for connection state events
+ */
+export type StreamConnectionHandler = () => void;
+/**
+ * Stream source event types
+ */
+export type StreamSourceEvent = 'data' | 'error' | 'connected' | 'disconnected';
+/**
+ * Interface for stream data sources.
+ * Implement this interface to provide video/audio data to the player
+ * from any transport mechanism.
+ */
+export interface IStreamSource {
+    /**
+     * Subscribe to stream events
+     */
+    on(event: 'data', handler: StreamDataHandler): void;
+    on(event: 'error', handler: StreamErrorHandler): void;
+    on(event: 'connected', handler: StreamConnectionHandler): void;
+    on(event: 'disconnected', handler: StreamConnectionHandler): void;
+    /**
+     * Unsubscribe from stream events
+     */
+    off(event: StreamSourceEvent, handler: Function): void;
+    /**
+     * Current connection state (optional)
+     */
+    readonly connected?: boolean;
+    /**
+     * Request a keyframe from the stream (for live streams)
+     */
+    requestKeyframe?(): void;
+    /**
+     * Dispose the stream source and clean up resources
+     */
+    dispose?(): void;
+}
+/**
+ * Base class for implementing stream sources with event handling
+ */
+export declare abstract class BaseStreamSource implements IStreamSource {
+    protected handlers: Map<string, Set<Function>>;
+    protected _connected: boolean;
+    get connected(): boolean;
+    on(event: 'data', handler: StreamDataHandler): void;
+    on(event: 'error', handler: StreamErrorHandler): void;
+    on(event: 'connected', handler: StreamConnectionHandler): void;
+    on(event: 'disconnected', handler: StreamConnectionHandler): void;
+    off(event: StreamSourceEvent, handler: Function): void;
+    protected emit(event: 'data', data: StreamDataEvent): void;
+    protected emit(event: 'error', error: Error): void;
+    protected emit(event: 'connected' | 'disconnected'): void;
+    dispose(): void;
+}

package/dist/sources/websocket-source.d.ts

@@ -0,0 +1,120 @@
+import { BaseStreamSource } from './stream-source';
+
+/**
+ * Configuration for WebSocket stream source
+ */
+export interface WebSocketSourceConfig {
+    /** WebSocket URL (ws:// or wss://) */
+    url?: string;
+    /** Auto-construct URL from current page location */
+    useCurrentHost?: boolean;
+    /** API path for video endpoint */
+    apiPath?: string;
+    /** Client ID for the connection */
+    clientId?: string;
+    /** Connection timeout in milliseconds */
+    timeout?: number;
+    /** Enable automatic reconnection */
+    autoReconnect?: boolean;
+    /** Reconnection delay in milliseconds */
+    reconnectDelay?: number;
+}
+/**
+ * Video metadata returned from the server
+ */
+export interface VideoMetadata {
+    width: number;
+    height: number;
+    frameRate?: number;
+    duration?: number;
+    codec?: string;
+}
+/**
+ * WebSocket-based stream source for live and file-based video playback.
+ *
+ * @example
+ * ```typescript
+ * const source = new WebSocketSource({ useCurrentHost: true });
+ * await source.connect();
+ * await source.loadLive('my-stream');
+ *
+ * source.on('data', (event) => {
+ *   if (event.streamType === 'video') {
+ *     // Handle video frame
+ *   }
+ * });
+ * ```
+ */
+export declare class WebSocketSource extends BaseStreamSource {
+    private webSocket;
+    private messageWaiters;
+    private requestId;
+    private timeoutCheckInterval;
+    private ignoreCmdsBelow;
+    private isLiveStream;
+    private config;
+    private lastKeyframeRequest;
+    private currentTrackName;
+    private reconnectTimeout;
+    private disposed;
+    constructor(config?: WebSocketSourceConfig);
+    /**
+     * Get the WebSocket URL based on configuration
+     */
+    private getWebSocketUrl;
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Load a live stream by ID
+     */
+    loadLive(streamId: string): Promise<VideoMetadata>;
+    /**
+     * Load a video file
+     */
+    loadFile(project: string, filename: string): Promise<VideoMetadata>;
+    /**
+     * Seek to a position in the video (file playback only)
+     */
+    seek(positionMs: number): Promise<void>;
+    /**
+     * Request more packets from the server (file playback)
+     */
+    read(packetCount: number): Promise<void>;
+    /**
+     * Unload the current stream
+     */
+    unload(): Promise<void>;
+    /**
+     * Request a keyframe (live streams only)
+     */
+    requestKeyframe(): void;
+    /**
+     * Flush pending requests (useful when seeking)
+     */
+    flush(): void;
+    /**
+     * Dispose the stream source
+     */
+    dispose(): void;
+    private request;
+    private waitForResponse;
+    private handleMessage;
+    private handleResponse;
+    private handleBinaryData;
+    private handleDisconnect;
+    private scheduleReconnect;
+    private stopReconnect;
+    private startTimeoutChecker;
+    private stopTimeoutChecker;
+    private clearWaiters;
+}
+/**
+ * Factory function to create a WebSocket stream source
+ */
+export declare function createWebSocketSource(config?: WebSocketSourceConfig): WebSocketSource;

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared type definitions for the video player library
+ */
+/**
+ * YUV frame data from WASM decoder
+ */
+export interface YUVFrame {
+    y: Uint8Array;
+    u: Uint8Array;
+    v: Uint8Array;
+    width: number;
+    height: number;
+    chromaStride: number;
+    chromaHeight: number;
+    timestamp: number;
+    /** Compatibility with VideoFrame interface */
+    close: () => void;
+}
+/**
+ * Stream metadata received from the source
+ */
+export interface StreamMetadata {
+    width: number;
+    height: number;
+    frameRate?: number;
+    codec?: string;
+    bitDepth?: number;
+}
+/**
+ * Decoder type preference
+ */
+export type PreferredDecoder = 'webcodecs-hw' | 'webcodecs-sw' | 'wasm';
+/**
+ * Logger interface for customizable logging
+ */
+export interface Logger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+/**
+ * Default console logger
+ */
+export declare const consoleLogger: Logger;
+/**
+ * Silent logger (no output)
+ */
+export declare const silentLogger: Logger;
+/**
+ * Augment WebCodecs VideoDecoderConfig with latencyMode
+ * (not yet in standard TypeScript DOM types)
+ */
+declare global {
+    interface VideoDecoderConfig {
+        latencyMode?: 'quality' | 'realtime';
+    }
+}

package/dist/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vite').UserConfig;
+export default _default;