@livepeer-frameworks/player-core 0.0.3

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

@@ -0,0 +1,395 @@
+/**
+ * WebCodecs Player Types
+ *
+ * Type definitions for the WebCodecs-based low-latency player.
+ */
+export type LatencyProfileName = 'ultra-low' | 'low' | 'balanced' | 'quality';
+export interface LatencyProfile {
+    name: string;
+    /** Base buffer before decoding (ms) */
+    keepAway: number;
+    /** Multiplier for jitter in buffer calculation */
+    jitterMultiplier: number;
+    /** Buffer ratio threshold to trigger speed up (e.g., 2.0 = 200%) */
+    speedUpThreshold: number;
+    /** Buffer ratio threshold to trigger slow down (e.g., 0.6 = 60%) */
+    speedDownThreshold: number;
+    /** Maximum playback speed for catchup */
+    maxSpeedUp: number;
+    /** Minimum playback speed for slowdown */
+    minSpeedDown: number;
+    /** AudioWorklet ring buffer duration (ms) */
+    audioBufferMs: number;
+    /** Whether to use optimizeForLatency hint for decoders */
+    optimizeForLatency: boolean;
+}
+export type ChunkType = 'key' | 'delta' | 'init';
+export interface RawChunk {
+    /** Track index from server */
+    trackIndex: number;
+    /** Frame type: key (keyframe), delta (P/B frame), init (codec init data) */
+    type: ChunkType;
+    /** Presentation timestamp in milliseconds */
+    timestamp: number;
+    /** Server-calculated offset in milliseconds (for A/V sync) */
+    offset: number;
+    /** Actual frame data */
+    data: Uint8Array;
+}
+export type TrackType = 'video' | 'audio' | 'meta';
+export interface TrackInfo {
+    idx: number;
+    type: TrackType;
+    codec: string;
+    codecstring?: string;
+    init?: string;
+    width?: number;
+    height?: number;
+    fpks?: number;
+    channels?: number;
+    rate?: number;
+    size?: number;
+}
+export type ControlMessageType = 'codec_data' | 'info' | 'on_time' | 'tracks' | 'set_speed' | 'pause' | 'on_stop' | 'error';
+export interface CodecDataMessage {
+    type: 'codec_data';
+    /** Current stream position in milliseconds */
+    current?: number;
+    /** List of WebCodecs-compatible codec strings (e.g., "avc1.42001f", "mp4a.40.2") */
+    codecs?: string[];
+    /** Track indices selected by server based on supported_combinations */
+    tracks?: number[];
+}
+/**
+ * Stream info message with track metadata
+ * Sent by MistServer with full stream information
+ */
+export interface InfoMessage {
+    type: 'info';
+    /** Stream metadata including tracks */
+    meta?: {
+        tracks?: Record<string, TrackInfo>;
+    };
+    /** Stream type ('live' or 'vod') */
+    type_?: string;
+}
+export interface OnTimeMessage {
+    type: 'on_time';
+    /** Current playback time (seconds) */
+    current: number;
+    /** Total duration (seconds, Infinity for live) */
+    total: number;
+    /** Available buffer end time (seconds) */
+    available?: number;
+    /** End time of available content (seconds) */
+    end?: number;
+    /** Server-reported jitter (ms) */
+    jitter?: number;
+    /** Current play rate */
+    play_rate?: number | 'auto';
+    /** Current play rate (alias) */
+    play_rate_curr?: number | 'auto' | 'fast-forward';
+    /** Active track indices */
+    tracks?: number[];
+}
+export interface TracksMessage {
+    type: 'tracks';
+    tracks: TrackInfo[];
+    codecs?: string[];
+}
+export interface SetSpeedMessage {
+    type: 'set_speed';
+    play_rate: number | 'auto';
+}
+export interface PauseMessage {
+    type: 'pause';
+}
+export interface OnStopMessage {
+    type: 'on_stop';
+}
+export interface ErrorMessage {
+    type: 'error';
+    message: string;
+}
+export type ControlMessage = CodecDataMessage | InfoMessage | OnTimeMessage | TracksMessage | SetSpeedMessage | PauseMessage | OnStopMessage | ErrorMessage;
+export interface PlayCommand {
+    type: 'play';
+}
+export interface HoldCommand {
+    type: 'hold';
+}
+export interface SeekCommand {
+    type: 'seek';
+    seek_time: number;
+    ff_add?: number;
+}
+export interface SetSpeedCommand {
+    type: 'set_speed';
+    play_rate: number | 'auto';
+}
+export interface RequestCodecDataCommand {
+    type: 'request_codec_data';
+    /** Supported codec combinations - array of [video codecs[], audio codecs[]] */
+    supported_combinations?: string[][][];
+}
+export interface FastForwardCommand {
+    type: 'fast_forward';
+    ff_add: number;
+}
+export type ControlCommand = PlayCommand | HoldCommand | SeekCommand | SetSpeedCommand | RequestCodecDataCommand | FastForwardCommand;
+export interface CreatePipelineMessage {
+    type: 'create';
+    idx: number;
+    track: TrackInfo;
+    opts: {
+        optimizeForLatency: boolean;
+    };
+    uid?: number;
+}
+export interface ConfigurePipelineMessage {
+    type: 'configure';
+    idx: number;
+    header: Uint8Array;
+    uid?: number;
+}
+export interface ReceiveChunkMessage {
+    type: 'receive';
+    idx: number;
+    chunk: {
+        type: 'key' | 'delta';
+        timestamp: number;
+        data: Uint8Array;
+    };
+    uid?: number;
+}
+export interface SetWritableMessage {
+    type: 'setwritable';
+    idx: number;
+    writable: WritableStream;
+    uid?: number;
+}
+export interface CreateGeneratorMessage {
+    type: 'creategenerator';
+    idx: number;
+    uid?: number;
+}
+export interface ClosePipelineMessage {
+    type: 'close';
+    idx: number;
+    waitEmpty?: boolean;
+    uid?: number;
+}
+export interface FrameTimingMessage {
+    type: 'frametiming';
+    action: 'setSpeed' | 'reset';
+    speed?: number;
+    tweak?: number;
+    uid?: number;
+}
+export interface SeekWorkerMessage {
+    type: 'seek';
+    seekTime: number;
+    uid?: number;
+}
+export interface DebuggingMessage {
+    type: 'debugging';
+    value: boolean | 'verbose';
+    uid?: number;
+}
+export type MainToWorkerMessage = CreatePipelineMessage | ConfigurePipelineMessage | ReceiveChunkMessage | SetWritableMessage | CreateGeneratorMessage | ClosePipelineMessage | FrameTimingMessage | SeekWorkerMessage | DebuggingMessage;
+export interface AddTrackMessage {
+    type: 'addtrack';
+    idx: number;
+    track?: MediaStreamTrack;
+    uid?: number;
+}
+export interface RemoveTrackMessage {
+    type: 'removetrack';
+    idx: number;
+    uid?: number;
+}
+export interface SetPlaybackRateMessage {
+    type: 'setplaybackrate';
+    speed: number;
+    uid?: number;
+}
+export interface ClosedMessage {
+    type: 'closed';
+    idx: number;
+    uid?: number;
+}
+export interface LogMessage {
+    type: 'log';
+    msg: string;
+    level?: 'info' | 'warn' | 'error';
+    uid?: number;
+}
+export interface SendEventMessage {
+    type: 'sendevent';
+    kind: string;
+    message?: string;
+    idx?: number;
+    uid?: number;
+}
+export interface StatsMessage {
+    type: 'stats';
+    stats: WorkerStats;
+    uid?: number;
+}
+export interface AckMessage {
+    type: 'ack';
+    idx?: number;
+    uid?: number;
+    status?: 'ok' | 'error';
+    error?: string;
+}
+export type WorkerToMainMessage = AddTrackMessage | RemoveTrackMessage | SetPlaybackRateMessage | ClosedMessage | LogMessage | SendEventMessage | StatsMessage | AckMessage;
+export interface FrameTimingStats {
+    /** Timestamp when frame entered decoder (microseconds) */
+    in: number;
+    /** Timestamp when frame exited decoder (microseconds) */
+    decoded: number;
+    /** Timestamp when frame reached trackwriter (microseconds) */
+    out: number;
+    speed: {
+        main: number;
+        tweak: number;
+        combined: number;
+    };
+    seeking: boolean;
+    paused: boolean;
+}
+export interface PipelineStats {
+    /** How early frames arrive at trackwriter (negative = late) */
+    early: number | null;
+    /** Duration between frames (ms) */
+    frameDuration: number | null;
+    frames: {
+        in: number;
+        decoded: number;
+        out: number;
+    };
+    queues: {
+        in: number;
+        decoder: number;
+        out: number;
+    };
+    timing: {
+        decoder: FrameTrackerStats;
+        writable: FrameTrackerStats;
+    };
+}
+export interface FrameTrackerStats {
+    lastIn: number | undefined;
+    lastOut: number | undefined;
+    delay: number | undefined;
+    delta: number | undefined;
+    shift: number | undefined;
+}
+export interface WorkerStats {
+    frameTiming: FrameTimingStats;
+    pipelines: Record<number, PipelineStats>;
+}
+export interface BufferState {
+    /** Current buffer level (ms) */
+    current: number;
+    /** Desired buffer level (ms) */
+    desired: number;
+    /** Ratio of current/desired */
+    ratio: number;
+}
+export interface JitterState {
+    /** Current jitter estimate (ms) */
+    current: number;
+    /** Peak jitter over sliding window (ms) */
+    peak: number;
+    /** Weighted average jitter (ms) */
+    weighted: number;
+}
+export interface SyncState {
+    buffer: BufferState;
+    jitter: JitterState;
+    /** Current playback speed (main * tweak) */
+    playbackSpeed: number;
+    /** Server-reported current time (seconds) */
+    serverTime: number;
+    /** Server delay estimate (ms) */
+    serverDelay: number;
+    /** A/V sync offset (ms, positive = audio ahead) */
+    avOffset: number;
+}
+export interface WebCodecsPlayerEvents {
+    ready: HTMLVideoElement;
+    error: string | Error;
+    play: void;
+    pause: void;
+    ended: void;
+    timeupdate: number;
+    waiting: void;
+    playing: void;
+    seeking: void;
+    seeked: void;
+    progress: void;
+    trackchange: {
+        trackIndex: number;
+        type: TrackType;
+    };
+    statsupdate: SyncState;
+}
+export interface WebCodecsPlayerOptions {
+    /** Latency profile preset */
+    latencyProfile?: LatencyProfileName;
+    /** Custom latency profile (overrides preset) */
+    customLatencyProfile?: Partial<LatencyProfile>;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable verbose frame logging */
+    verboseDebug?: boolean;
+    /** Stats update interval (ms), 0 to disable */
+    statsInterval?: number;
+}
+/**
+ * Comprehensive player statistics for monitoring and debugging
+ */
+export interface WebCodecsStats {
+    /** Latency/buffer statistics */
+    latency: {
+        /** Current buffer level (ms) */
+        buffer: number;
+        /** Target buffer level (ms) */
+        target: number;
+        /** Estimated network jitter (ms) */
+        jitter: number;
+    };
+    /** Audio/Video sync statistics */
+    sync: {
+        /** A/V drift (ms, positive = video ahead of audio) */
+        avDrift: number;
+        /** Current playback speed (including adjustments) */
+        playbackSpeed: number;
+    };
+    /** Decoder statistics */
+    decoder: {
+        /** Video decoder queue size */
+        videoQueueSize: number;
+        /** Audio decoder queue size */
+        audioQueueSize: number;
+        /** Total frames dropped */
+        framesDropped: number;
+        /** Total frames decoded */
+        framesDecoded: number;
+    };
+    /** Network statistics */
+    network: {
+        /** Total bytes received */
+        bytesReceived: number;
+        /** Total messages received */
+        messagesReceived: number;
+    };
+}
+export interface DeferredPromise<T> {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: any) => void;
+}
+export declare function createDeferredPromise<T>(): DeferredPromise<T>;

package/dist/types/players/WebCodecsPlayer/worker/decoder.worker.d.ts

@@ -0,0 +1,13 @@
+/**
+ * WebCodecs Decoder Worker
+ *
+ * Handles VideoDecoder and AudioDecoder in a dedicated worker thread.
+ * This keeps decoding off the main thread for better performance.
+ *
+ * Features:
+ * - Video/Audio pipeline management per track
+ * - Frame scheduling based on timestamps and playback speed
+ * - Stats collection and reporting
+ * - Seek handling with queue flush
+ */
+export {};

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

@@ -0,0 +1,197 @@
+/**
+ * Worker-specific Types for WebCodecs Player
+ *
+ * These types define the message protocol between main thread and worker.
+ */
+import type { TrackInfo, FrameTimingStats, PipelineStats } from '../types';
+export interface CreateMessage {
+    type: 'create';
+    idx: number;
+    track: TrackInfo;
+    opts: {
+        optimizeForLatency: boolean;
+    };
+    uid: number;
+}
+export interface ConfigureMessage {
+    type: 'configure';
+    idx: number;
+    header: Uint8Array;
+    uid: number;
+}
+export interface ReceiveMessage {
+    type: 'receive';
+    idx: number;
+    chunk: {
+        type: 'key' | 'delta';
+        timestamp: number;
+        data: Uint8Array;
+    };
+    uid: number;
+}
+export interface SetWritableMessage {
+    type: 'setwritable';
+    idx: number;
+    writable: WritableStream<VideoFrame | AudioData>;
+    uid: number;
+}
+export interface CreateGeneratorMessage {
+    type: 'creategenerator';
+    idx: number;
+    uid: number;
+}
+export interface CloseMessage {
+    type: 'close';
+    idx: number;
+    waitEmpty?: boolean;
+    uid: number;
+}
+export interface FrameTimingMessage {
+    type: 'frametiming';
+    action: 'setSpeed' | 'reset';
+    speed?: number;
+    tweak?: number;
+    uid: number;
+}
+export interface SeekMessage {
+    type: 'seek';
+    seekTime: number;
+    uid: number;
+}
+export interface DebuggingMessage {
+    type: 'debugging';
+    value: boolean | 'verbose';
+    uid: number;
+}
+export type MainToWorkerMessage = CreateMessage | ConfigureMessage | ReceiveMessage | SetWritableMessage | CreateGeneratorMessage | CloseMessage | FrameTimingMessage | SeekMessage | DebuggingMessage;
+export interface AddTrackMessage {
+    type: 'addtrack';
+    idx: number;
+    track?: MediaStreamTrack;
+    uid: number;
+    status: 'ok';
+}
+export interface RemoveTrackMessage {
+    type: 'removetrack';
+    idx: number;
+    uid: number;
+}
+export interface SetPlaybackRateMessage {
+    type: 'setplaybackrate';
+    speed: number;
+    uid: number;
+}
+export interface ClosedMessage {
+    type: 'closed';
+    idx: number;
+    uid: number;
+    status: 'ok';
+}
+export interface LogMessage {
+    type: 'log';
+    msg: string;
+    level?: 'info' | 'warn' | 'error';
+    uid: number;
+}
+export interface SendEventMessage {
+    type: 'sendevent';
+    kind: string;
+    message?: string;
+    idx?: number;
+    uid: number;
+}
+export interface StatsUpdateMessage {
+    type: 'stats';
+    stats: {
+        frameTiming: FrameTimingStats;
+        pipelines: Record<number, PipelineStats>;
+    };
+    uid: number;
+}
+export interface AckMessage {
+    type: 'ack';
+    idx?: number;
+    uid: number;
+    status: 'ok' | 'error';
+    error?: string;
+}
+/** Safari audio: worker sends frames to main thread for writing */
+export interface WriteFrameMessage {
+    type: 'writeframe';
+    idx: number;
+    frame: AudioData;
+    uid: number;
+}
+export type WorkerToMainMessage = AddTrackMessage | RemoveTrackMessage | SetPlaybackRateMessage | ClosedMessage | LogMessage | SendEventMessage | StatsUpdateMessage | AckMessage | WriteFrameMessage;
+export interface FrameTiming {
+    /** When frame entered decoder (microseconds, performance.now() * 1000) */
+    in: number;
+    /** When frame exited decoder (microseconds) */
+    decoded: number;
+    /** When frame was written to output (microseconds) */
+    out: number;
+    speed: {
+        main: number;
+        tweak: number;
+        combined: number;
+    };
+    seeking: boolean;
+    paused: boolean;
+    /** Server-sent current time */
+    serverTime: number;
+}
+export interface DecodedFrame {
+    frame: VideoFrame | AudioData;
+    timestamp: number;
+    decodedAt: number;
+}
+export interface PipelineState {
+    idx: number;
+    track: TrackInfo;
+    configured: boolean;
+    closed: boolean;
+    decoder: VideoDecoder | AudioDecoder | null;
+    writable: WritableStream<VideoFrame | AudioData> | null;
+    writer: WritableStreamDefaultWriter<VideoFrame | AudioData> | null;
+    inputQueue: Array<{
+        type: 'key' | 'delta';
+        timestamp: number;
+        data: Uint8Array;
+    }>;
+    outputQueue: DecodedFrame[];
+    stats: {
+        framesIn: number;
+        framesDecoded: number;
+        framesOut: number;
+        framesDropped: number;
+        lastInputTimestamp: number;
+        lastOutputTimestamp: number;
+        decoderQueueSize: number;
+        lastChunkType: string;
+        lastChunkSize: number;
+        lastChunkBytes: string;
+    };
+    optimizeForLatency: boolean;
+}
+export interface ScheduleResult {
+    /** Whether frame should be output now */
+    shouldOutput: boolean;
+    /** How early/late frame is (negative = late) in ms */
+    earliness: number;
+    /** Suggested delay before next check (ms) */
+    checkDelayMs: number;
+}
+export interface VideoDecoderInit {
+    codec: string;
+    codedWidth?: number;
+    codedHeight?: number;
+    description?: Uint8Array;
+    hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software';
+    optimizeForLatency?: boolean;
+}
+export interface AudioDecoderInit {
+    codec: string;
+    sampleRate: number;
+    numberOfChannels: number;
+    description?: Uint8Array;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Player Implementations
+ *
+ * Framework-agnostic player implementations that extend BasePlayer.
+ * These are used by PlayerRegistry for dynamic player selection.
+ */
+export { NativePlayerImpl, DirectPlaybackPlayerImpl } from './NativePlayer';
+export { HlsJsPlayerImpl } from './HlsJsPlayer';
+export { DashJsPlayerImpl } from './DashJsPlayer';
+export { VideoJsPlayerImpl } from './VideoJsPlayer';
+export { MistPlayerImpl } from './MistPlayer';
+export { MewsWsPlayerImpl } from './MewsWsPlayer';
+export { MistWebRTCPlayerImpl } from './MistWebRTCPlayer';
+export { WebCodecsPlayerImpl } from './WebCodecsPlayer';

package/dist/types/styles/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ensures the compiled player stylesheet is imported once. When bundling with
+ * tools that respect package `style` fields, simply importing the module is enough.
+ * For host environments that do not, calling this helper will inject a link tag.
+ */
+export declare function ensurePlayerStyles(): void;
+/**
+ * For SSR-first apps, inject the CSS manually and mark it as applied.
+ */
+export declare function injectPlayerStyles(href?: string): void;
+export default ensurePlayerStyles;