@stinkycomputing/web-live-player 0.1.0

package/dist/player/base-player.d.ts

@@ -0,0 +1,54 @@
+import { Logger } from '../types';
+
+/**
+ * Base player configuration
+ */
+export interface BasePlayerConfig {
+    /** Enable debug logging */
+    debugLogging?: boolean;
+}
+/**
+ * Create a logger with configurable debug output
+ */
+export declare function createLogger(debugLogging: boolean): Logger;
+/**
+ * Base class for video players providing common event handling and state management
+ */
+export declare abstract class BasePlayer<TState extends string> {
+    protected eventHandlers: Map<string, Set<Function>>;
+    protected logger: Logger;
+    protected _state: TState;
+    constructor(initialState: TState, debugLogging?: boolean);
+    /**
+     * Current player state
+     */
+    get state(): TState;
+    /**
+     * Update player state and emit statechange event
+     */
+    protected setState(state: TState): void;
+    /**
+     * Enable/disable debug logging
+     */
+    setDebugLogging(enabled: boolean): void;
+    /**
+     * Subscribe to an event
+     */
+    on(event: string, handler: Function): void;
+    /**
+     * Unsubscribe from an event
+     */
+    off(event: string, handler: Function): void;
+    /**
+     * Emit an event to all subscribers
+     */
+    protected emit(event: string, ...args: any[]): void;
+    /**
+     * Clear all event handlers (called during dispose)
+     */
+    protected clearEventHandlers(): void;
+    /**
+     * Dispose the player and release resources
+     */
+    abstract dispose(): void;
+}

package/dist/player/base-player.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * BasePlayer Tests
+ *
+ * Tests for the shared player base class functionality:
+ * - Event handling (on/off/emit)
+ * - State management
+ */
+export {};

package/dist/player/file-player.d.ts

@@ -0,0 +1,200 @@
+import { MP4FileInfo } from '../sources/mp4-file-source';
+import { PreferredDecoder } from '../types';
+import { BasePlayer } from './base-player';
+
+/**
+ * Play mode for file playback
+ */
+export type FilePlayMode = 'once' | 'loop';
+/**
+ * File player configuration
+ */
+export interface FilePlayerConfig {
+    preferredDecoder?: PreferredDecoder;
+    /** Enable audio playback */
+    enableAudio?: boolean;
+    /** Audio context to use (creates one if not provided) */
+    audioContext?: AudioContext;
+    /** Enable debug logging */
+    debugLogging?: boolean;
+    /** Play mode: 'once' plays to end, 'loop' seamlessly loops (default: 'once') */
+    playMode?: FilePlayMode;
+    /** @deprecated Use playMode instead */
+    loop?: boolean;
+}
+/**
+ * File player state
+ */
+export type FilePlayerState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'ended' | 'error';
+/**
+ * File player statistics
+ */
+export interface FilePlayerStats {
+    duration: number;
+    position: number;
+    bufferSize: number;
+    width: number;
+    height: number;
+    frameRate: number;
+    codec: string;
+    state: FilePlayerState;
+}
+/**
+ * File Video Player
+ */
+export declare class FileVideoPlayer extends BasePlayer<FilePlayerState> {
+    private config;
+    private fileSource;
+    private decoder;
+    private audioContext;
+    private audioPlayer;
+    private ownsAudioContext;
+    private audioInitialized;
+    private fileInfo;
+    private frameBuffer;
+    private minBufferSize;
+    private sampleQueue;
+    private audioSampleQueue;
+    private nextSampleIndex;
+    private nextAudioSampleIndex;
+    private maxDecoderQueue;
+    private bufferReadyResolve;
+    private playStartTime;
+    private playStartPosition;
+    private currentPosition;
+    private lastVideoFrame;
+    private isSeeking;
+    constructor(config?: FilePlayerConfig);
+    /**
+     * Get file info
+     */
+    getFileInfo(): MP4FileInfo | null;
+    /**
+     * Get current position in seconds
+     */
+    getPosition(): number;
+    /**
+     * Get duration in seconds
+     */
+    getDuration(): number;
+    /**
+     * Get player statistics
+     */
+    getStats(): FilePlayerStats;
+    /**
+     * Set play mode ('once' or 'loop')
+     */
+    setPlayMode(mode: FilePlayMode): void;
+    /**
+     * Get current play mode
+     */
+    getPlayMode(): FilePlayMode;
+    /**
+     * Set looping (convenience method, equivalent to setPlayMode)
+     * @deprecated Use setPlayMode instead
+     */
+    setLoop(loop: boolean): void;
+    /**
+     * Enable/disable debug logging
+     */
+    setDebugLogging(enabled: boolean): void;
+    /**
+     * Set audio volume (0-1)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Get current audio volume (0-1)
+     */
+    getVolume(): number;
+    /**
+     * Load a video file from URL
+     */
+    loadFromUrl(url: string): Promise<MP4FileInfo>;
+    /**
+     * Load a video file from File object
+     */
+    loadFromFile(file: File): Promise<MP4FileInfo>;
+    /**
+     * Initialize the video decoder
+     */
+    private initDecoder;
+    /**
+     * Initialize the audio decoder
+     */
+    private initAudioDecoder;
+    /**
+     * Wait for the frame buffer to have enough frames for smooth playback
+     */
+    private waitForBuffer;
+    /**
+     * Handle samples from mp4box - queue them for gradual decoding
+     */
+    private handleSamples;
+    /**
+     * Feed video samples to decoder gradually (don't overflow the queue)
+     */
+    private feedDecoder;
+    private maxAudioBufferMs;
+    /**
+     * Feed audio samples to decoder - gradually based on playback position
+     */
+    private feedAudioDecoder;
+    /**
+     * Handle decoded frame from decoder
+     */
+    private handleDecodedFrame;
+    /**
+     * Handle source ended (all samples extracted)
+     */
+    private handleSourceEnded;
+    /**
+     * Perform a seamless loop back to the start
+     * This resets timing and decoder state for looping
+     */
+    private performSeamlessLoop;
+    /**
+     * Start playback
+     */
+    play(): void;
+    /**
+     * Pause playback
+     */
+    pause(): void;
+    /**
+     * Seek to a specific time in seconds
+     */
+    seek(timeSeconds: number): Promise<void>;
+    /**
+     * Clear the frame buffer
+     */
+    private clearFrameBuffer;
+    /**
+     * Get a video frame for rendering
+     *
+     * Call this in your render loop. Returns the appropriate frame for the current time.
+     */
+    getVideoFrame(): VideoFrame | null;
+    /**
+     * Subscribe to events (typed overloads)
+     */
+    on(event: 'statechange', handler: (state: FilePlayerState) => void): void;
+    on(event: 'ready', handler: (info: MP4FileInfo) => void): void;
+    on(event: 'progress', handler: (loaded: number, total: number) => void): void;
+    on(event: 'error', handler: (error: Error) => void): void;
+    on(event: 'ended', handler: () => void): void;
+    on(event: 'loop', handler: () => void): void;
+    on(event: 'seeked', handler: (time: number) => void): void;
+    /**
+     * Unsubscribe from events
+     */
+    off(event: string, handler: Function): void;
+    /**
+     * Dispose and clean up resources
+     * @param full - If true, also disposes the AudioContext (default: false for reload)
+     */
+    dispose(full?: boolean): void;
+}
+/**
+ * Factory function to create a file player
+ */
+export declare function createFilePlayer(config?: FilePlayerConfig): FileVideoPlayer;

package/dist/player/live-player.d.ts

@@ -0,0 +1,219 @@
+import { IStreamSource } from '../sources/stream-source';
+import { PreferredDecoder } from '../types';
+import { LatencyStats } from '../scheduling/frame-scheduler';
+import { BasePlayer } from './base-player';
+
+/**
+ * Player configuration
+ */
+export interface PlayerConfig {
+    preferredDecoder?: PreferredDecoder;
+    /** Buffer delay in milliseconds (default: 100ms) */
+    bufferDelayMs?: number;
+    enableAudio?: boolean;
+    /** Video track name for MoQ streams (default: 'video'). Set to null to accept video from any track. */
+    videoTrackName?: string | null;
+    /** Audio track name for MoQ streams (default: 'audio'). Set to null to accept audio from any track. */
+    audioTrackName?: string | null;
+    debugLogging?: boolean;
+}
+/**
+ * Player state
+ */
+export type PlayerState = 'idle' | 'playing' | 'paused' | 'error';
+/**
+ * Player statistics
+ */
+export interface PlayerStats {
+    bufferSize: number;
+    bufferMs: number;
+    avgBufferMs: number;
+    targetBufferMs: number;
+    droppedFrames: number;
+    totalFrames: number;
+    decoderState: string;
+    streamWidth: number;
+    streamHeight: number;
+    frameRate: number;
+    latency: LatencyStats | null;
+}
+/**
+ * Player event types
+ */
+type PlayerEventMap = {
+    'frame': (frame: VideoFrame) => void;
+    'statechange': (state: PlayerState) => void;
+    'error': (error: Error) => void;
+    'metadata': (metadata: {
+        width: number;
+        height: number;
+        codec: string;
+    }) => void;
+};
+/**
+ * Factory function to create a player instance
+ */
+export declare function createPlayer(config?: PlayerConfig): LiveVideoPlayer;
+/**
+ * Live Video Player - Main class
+ */
+export declare class LiveVideoPlayer extends BasePlayer<PlayerState> {
+    private config;
+    private streamSource;
+    private trackFilter;
+    private boundDataHandler;
+    private decoder;
+    private currentCodecData;
+    private useWasmDecoder;
+    private waitingForKeyframe;
+    private lastWaitingForKeyframeLog;
+    private lastKeyframeRequest;
+    private statusLogCounter;
+    private isConfiguring;
+    private pendingDuringConfig;
+    private frameScheduler;
+    private lastVideoFrame;
+    private consecutiveDrops;
+    private totalDrops;
+    private lastDropLogTime;
+    private streamWidth;
+    private streamHeight;
+    private estimatedFrameRate;
+    private audioContext;
+    private audioPlayer;
+    private ownsAudioContext;
+    private audioCodecData;
+    private arrivalTimes;
+    constructor(config?: PlayerConfig);
+    /**
+     * Enable or disable debug logging at runtime
+     */
+    setDebugLogging(enabled: boolean): void;
+    /**
+     * Set audio volume (0-1)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Get current audio volume (0-1)
+     */
+    getVolume(): number;
+    /**
+     * Set the stream source (dependency injection)
+     */
+    setStreamSource(source: IStreamSource): void;
+    /**
+     * Set the track name to filter for
+     */
+    setTrackFilter(trackName: string): void;
+    /**
+     * Convenience method to connect to a MoQ-like session
+     *
+     * Note: For audio support, the MoQ session must also be subscribed to the audio track.
+     * When using StandaloneMoQSource, include both 'video' and 'audio' in subscriptions.
+     * When using Elmo's MoQSessionNode, add an audio track to the session config.
+     *
+     * @param session - MoQ session implementing IStreamSource (e.g., Elmo's MoQSessionNode)
+     * @param videoTrackName - Video track name (defaults to config.videoTrackName or 'video')
+     */
+    connectToMoQSession(session: IStreamSource, videoTrackName?: string): void;
+    /**
+     * Connect to a MoQ relay directly with video and optional audio tracks
+     *
+     * @param relayUrl - URL of the MoQ relay (e.g., 'https://relay.example.com/moq')
+     * @param namespace - MoQ namespace/broadcast name
+     * @param options - Optional configuration for track names
+     */
+    connectToMoQRelay(relayUrl: string, namespace: string, options?: {
+        videoTrack?: string;
+        audioTrack?: string | false;
+    }): Promise<void>;
+    /**
+     * Start playback
+     */
+    play(): void;
+    /**
+     * Pause playback
+     */
+    pause(): void;
+    /**
+     * Get a video frame for rendering
+     *
+     * Call this in your render loop with the current timestamp.
+     * The returned VideoFrame should be closed after use if you're done with it.
+     */
+    getVideoFrame(timestampMs: number): VideoFrame | null;
+    /**
+     * Set buffer delay in milliseconds (syncs both video and audio)
+     */
+    setBufferDelay(delayMs: number): void;
+    /**
+     * Get current buffer delay in milliseconds
+     */
+    getBufferDelay(): number;
+    /**
+     * Set preferred decoder type
+     * If decoder type changes while playing, dispose old decoder and request keyframe
+     */
+    setPreferredDecoder(type: PreferredDecoder): void;
+    /**
+     * Flush the player pipeline (decoder, frame buffer)
+     * Used to recover from queue overflow or when seeking
+     */
+    flush(): void;
+    /**
+     * Get player statistics
+     */
+    getStats(): PlayerStats;
+    /**
+     * Subscribe to player events (typed overload)
+     */
+    on<K extends keyof PlayerEventMap>(event: K, handler: PlayerEventMap[K]): void;
+    /**
+     * Unsubscribe from player events (typed overload)
+     */
+    off<K extends keyof PlayerEventMap>(event: K, handler: PlayerEventMap[K]): void;
+    /**
+     * Handle incoming stream data
+     */
+    private handleStreamData;
+    /**
+     * Handle incoming audio frame data
+     */
+    private handleAudioData;
+    /**
+     * Configure the decoder for a specific codec
+     */
+    private configureDecoder;
+    private getCodecName;
+    /**
+     * Handle decoded video frame (from WebCodecs)
+     */
+    private handleDecodedFrame;
+    /**
+     * Handle decoded YUV frame (from WASM decoder)
+     * Converts YUV to VideoFrame using canvas
+     */
+    private handleDecodedYUVFrame;
+    /**
+     * Convert YUV frame to VideoFrame using native I420 support
+     * Much faster than manual pixel-by-pixel conversion
+     *
+     * @param yuv - YUV frame data from decoder (may have padded dimensions)
+     * @param visibleWidth - Actual video width (unpadded)
+     * @param visibleHeight - Actual video height (unpadded)
+     */
+    private convertYUVToVideoFrame;
+    /**
+     * Handle decoder error
+     */
+    private handleDecoderError;
+    /**
+     * Handle decoder queue overflow - flush and request keyframe
+     */
+    private handleQueueOverflow;
+    /**
+     * Dispose the player and release resources
+     */
+    dispose(): void;
+}
+export {};

package/dist/protocol/codec-utils.d.ts

@@ -0,0 +1,25 @@
+import { HeaderCodecData } from './sesame-binary-protocol';
+
+/**
+ * Timebase structure for timestamp conversion
+ */
+export interface Timebase {
+    num: number;
+    den: number;
+}
+/**
+ * Rescale a timestamp from one timebase to another
+ */
+export declare function rescaleTime(pts: bigint, source: Timebase, target: Timebase): number;
+/**
+ * Check if codec data has changed
+ */
+export declare function codecDataChanged(current: HeaderCodecData | undefined, newData: HeaderCodecData | undefined): boolean;
+/**
+ * Get human-readable codec name
+ */
+export declare function getCodecName(codecType: number): string;
+/**
+ * Get WebCodecs codec string for a given codec data
+ */
+export declare function getCodecString(codecData: HeaderCodecData): string | null;

package/dist/protocol/sesame-binary-protocol.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Sesame Binary Protocol - TypeScript Implementation
+ *
+ * This module provides TypeScript implementation of the Sesame binary protocol
+ * for serializing and deserializing multimedia data packets.
+ */
+export declare const PROTOCOL_MAGIC = 1297302867;
+export declare const PROTOCOL_VERSION = 1;
+export declare const HEADER_DATA_SIZE = 32;
+export declare const HEADER_CODEC_DATA_SIZE = 24;
+export declare const HEADER_METADATA_SIZE = 64;
+export declare const FLAG_HAS_CODEC_DATA: number;
+export declare const FLAG_HAS_METADATA: number;
+export declare const FLAG_IS_KEYFRAME: number;
+export declare enum PacketType {
+    VIDEO_FRAME = 1,
+    AUDIO_FRAME = 2,
+    RPC = 3,
+    MUXED_DATA = 4,
+    DECODER_DATA = 5
+}
+export declare enum CodecType {
+    VIDEO_VP8 = 1,
+    VIDEO_VP9 = 2,
+    VIDEO_AVC = 3,
+    VIDEO_HEVC = 4,
+    VIDEO_AV1 = 5,
+    AUDIO_OPUS = 64,
+    AUDIO_AAC = 65,
+    AUDIO_PCM = 66
+}
+export interface HeaderData {
+    magic: number;
+    flags: number;
+    pts: bigint;
+    id: bigint;
+    version: number;
+    header_size: number;
+    type: PacketType;
+    reserved: number;
+}
+export interface HeaderCodecData {
+    sample_rate: number;
+    timebase_num: number;
+    timebase_den: number;
+    codec_profile: number;
+    codec_level: number;
+    width: number;
+    height: number;
+    codec_type: CodecType;
+    channels: number;
+    bit_depth: number;
+    reserved: number;
+}
+export interface HeaderMetadata {
+    metadata: string;
+}
+export interface ParsedData {
+    valid: boolean;
+    header: HeaderData | null;
+    metadata: HeaderMetadata | null;
+    codec_data: HeaderCodecData | null;
+    payload: Uint8Array | null;
+    payload_size: number;
+}
+/**
+ * Main binary protocol class with static methods for serialization/deserialization
+ */
+export declare class SesameBinaryProtocol {
+    /**
+     * Initialize a header data structure with proper defaults
+     */
+    static initHeader(type: PacketType, flags: number, pts: bigint, id: bigint): HeaderData;
+    /**
+     * Calculate the total header size based on flags
+     */
+    static calculateHeaderSize(flags: number): number;
+    /**
+     * Validate a header structure
+     */
+    static validateHeader(header: HeaderData, totalSize: number): boolean;
+    /**
+     * Serialize data into a Uint8Array buffer
+     */
+    static serialize(header: HeaderData, metadata?: HeaderMetadata | null, codecData?: HeaderCodecData | null, payload?: Uint8Array | null): Uint8Array | null;
+    /**
+     * Parse incoming binary data
+     */
+    static parseData(data: Uint8Array): ParsedData;
+    /**
+     * Helper: Convert string to fixed-size byte array (null-terminated)
+     */
+    private static stringToFixedBytes;
+    /**
+     * Helper: Convert fixed-size byte array to string (null-terminated)
+     */
+    private static fixedBytesToString;
+}