@livepeer-frameworks/player-core 0.0.3

package/dist/types/types.d.ts

@@ -0,0 +1,363 @@
+/**
+ * Core types for FrameWorks player - framework agnostic
+ */
+/** High-level player state machine for UI */
+export type PlayerState = 'booting' | 'gateway_loading' | 'gateway_ready' | 'gateway_error' | 'no_endpoint' | 'selecting_player' | 'connecting' | 'buffering' | 'playing' | 'paused' | 'ended' | 'error' | 'destroyed';
+/**
+ * Content type (used for Gateway resolution + UI presets).
+ *
+ * Notes:
+ * - `dvr` can be effectively-live when `metadata.dvrStatus === 'recording'`
+ * - `vod`/`clip`/completed `dvr` should use VOD-like presets and controls
+ */
+export type ContentType = 'live' | 'dvr' | 'clip' | 'vod';
+export interface PlayerStateContext {
+    reason?: string;
+    gatewayStatus?: 'idle' | 'loading' | 'ready' | 'error';
+    selectedPlayer?: string;
+    selectedProtocol?: string;
+    nodeId?: string;
+    endpointUrl?: string;
+    error?: string;
+}
+export interface PlayerOptions {
+    gatewayUrl?: string;
+    /** Direct MistServer base URL (e.g. "http://localhost:8080") - bypasses Gateway resolution */
+    mistUrl?: string;
+    authToken?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+    stockControls?: boolean;
+    debug?: boolean;
+    /** Show dev mode overlay panel (player/source selection, stats) */
+    devMode?: boolean;
+    /** Force a specific player (e.g., 'videojs', 'hlsjs', 'dashjs', 'direct', 'mist') */
+    forcePlayer?: string;
+    /** Force a specific MIME type (e.g., 'html5/application/vnd.apple.mpegurl') */
+    forceType?: string;
+    /** Force a specific source index */
+    forceSource?: number;
+    /**
+     * Playback mode affects protocol selection:
+     * - 'low-latency': Prefer WebRTC/WHEP for minimal delay
+     * - 'quality': Prefer HLS/DASH for ABR and quality
+     * - 'dvr': Prefer protocols that support seeking in live buffer
+     * - 'auto': Score-based selection (default)
+     */
+    playbackMode?: PlaybackMode;
+    /** HLS.js configuration override (merged with defaults) */
+    hlsConfig?: HlsJsConfig;
+    /** DASH.js configuration override (merged with defaults) */
+    dashConfig?: DashJsConfig;
+    /** WebRTC configuration (ICE servers, etc.) */
+    rtcConfig?: RTCConfiguration;
+    /** String to append to all request URLs (auth tokens, tracking params) */
+    urlAppend?: string;
+    /** Low latency mode for HLS (enables LL-HLS features) */
+    lowLatencyMode?: boolean;
+}
+/** HLS.js configuration subset */
+export interface HlsJsConfig {
+    debug?: boolean;
+    autoStartLoad?: boolean;
+    startPosition?: number;
+    maxBufferLength?: number;
+    maxBufferSize?: number;
+    maxMaxBufferLength?: number;
+    lowLatencyMode?: boolean;
+    abrEwmaDefaultEstimate?: number;
+    abrEwmaFastLive?: number;
+    abrEwmaSlowLive?: number;
+    fragLoadingMaxRetry?: number;
+    fragLoadingTimeOut?: number;
+    levelLoadingTimeOut?: number;
+    manifestLoadingTimeOut?: number;
+    [key: string]: unknown;
+}
+/** DASH.js configuration subset */
+export interface DashJsConfig {
+    debug?: boolean;
+    autoPlay?: boolean;
+    streaming?: {
+        lowLatencyEnabled?: boolean;
+        liveDelay?: number;
+        liveDelayFragmentCount?: number;
+        buffer?: {
+            stableBufferTime?: number;
+            fastSwitchEnabled?: boolean;
+        };
+        abr?: {
+            autoSwitchBitrate?: {
+                video: boolean;
+                audio: boolean;
+            };
+            ABRStrategy?: 'abrDynamic' | 'abrBola' | 'abrL2A' | 'abrLoLP' | 'abrThroughput';
+            useDefaultABRRules?: boolean;
+        };
+    };
+    [key: string]: unknown;
+}
+export type StreamProtocol = 'WHEP' | 'HLS' | 'DASH' | 'MP4' | 'WEBM' | 'RTMP' | 'MIST_HTML';
+export interface OutputCapabilities {
+    supportsSeek: boolean;
+    supportsQualitySwitch: boolean;
+    maxBitrate?: number;
+    hasAudio: boolean;
+    hasVideo: boolean;
+    codecs?: string[];
+}
+export interface QualityLevel {
+    id: string;
+    label: string;
+    width?: number;
+    height?: number;
+    bitrate?: number;
+}
+export interface OutputEndpoint {
+    protocol: StreamProtocol | string;
+    url: string;
+    capabilities?: OutputCapabilities;
+}
+export interface EndpointInfo {
+    nodeId: string;
+    baseUrl?: string;
+    protocol: StreamProtocol | string;
+    url: string;
+    quality?: QualityLevel;
+    capabilities?: OutputCapabilities;
+    outputs?: Record<string, OutputEndpoint>;
+    geoDistance?: number;
+    loadScore?: number;
+}
+export interface ContentMetadata {
+    title?: string;
+    description?: string;
+    contentId?: string;
+    contentType?: ContentType;
+    durationSeconds?: number;
+    thumbnailUrl?: string;
+    createdAt?: string;
+    status?: 'AVAILABLE' | 'PROCESSING' | 'ERROR' | 'OFFLINE';
+    viewers?: number;
+    isLive?: boolean;
+    recordingSizeBytes?: number;
+    clipSource?: string;
+    /** DVR recording status: 'recording' = in progress (treat as live), 'completed' = finished (treat as VOD) */
+    dvrStatus?: 'recording' | 'completed';
+    /** Native container format: mp4, m3u8, webm, etc. */
+    format?: string;
+}
+export interface ContentEndpoints {
+    primary: EndpointInfo;
+    fallbacks: EndpointInfo[];
+    metadata?: ContentMetadata;
+}
+export type StreamStatus = 'ONLINE' | 'OFFLINE' | 'INITIALIZING' | 'BOOTING' | 'WAITING_FOR_DATA' | 'SHUTTING_DOWN' | 'INVALID' | 'ERROR';
+export interface MistStreamInfo {
+    error?: string;
+    on_error?: string;
+    perc?: number;
+    type?: 'live' | 'vod';
+    hasVideo?: boolean;
+    hasAudio?: boolean;
+    unixoffset?: number;
+    lastms?: number;
+    source?: MistStreamSource[];
+    meta?: MistStreamMeta;
+}
+export interface MistStreamMeta {
+    tracks?: Record<string, MistTrackInfo>;
+    buffer_window?: number;
+    duration?: number;
+    /** Optional MistServer base URL hint (present in some gateway-merged payloads) */
+    mistUrl?: string;
+}
+export interface MistStreamSource {
+    url: string;
+    type: string;
+    priority?: number;
+    simul_tracks?: number;
+    relurl?: string;
+    RTCIceServers?: RTCIceServer[];
+}
+export interface MistTrackInfo {
+    type: 'video' | 'audio' | 'meta';
+    codec: string;
+    width?: number;
+    height?: number;
+    bps?: number;
+    fpks?: number;
+    init?: string;
+    codecstring?: string;
+    firstms?: number;
+    lastms?: number;
+    lang?: string;
+    idx?: number;
+    channels?: number;
+    rate?: number;
+    /** Track payload size in bytes (present on some MistServer builds) */
+    size?: number;
+}
+export interface StreamStateOptions {
+    mistBaseUrl: string;
+    streamName: string;
+    pollInterval?: number;
+    enabled?: boolean;
+    useWebSocket?: boolean;
+}
+export interface StreamState {
+    status: StreamStatus;
+    isOnline: boolean;
+    message: string;
+    percentage?: number;
+    lastUpdate: number;
+    streamInfo?: MistStreamInfo;
+    error?: string;
+}
+export interface PlaybackQuality {
+    score: number;
+    bitrate: number;
+    bufferedAhead: number;
+    stallCount: number;
+    frameDropRate: number;
+    latency: number;
+    timestamp: number;
+}
+export interface QualityThresholds {
+    minScore: number;
+    maxStalls: number;
+    minBuffer: number;
+}
+export type PlaybackThresholds = QualityThresholds;
+export interface PlaybackQualityOptions {
+    videoElement: HTMLVideoElement | null;
+    enabled?: boolean;
+    sampleInterval?: number;
+    thresholds?: Partial<QualityThresholds>;
+    onQualityDegraded?: (quality: PlaybackQuality) => void;
+}
+export type MetaTrackEventType = 'subtitle' | 'score' | 'event' | 'chapter' | 'unknown';
+export interface MetaTrackEvent {
+    type: MetaTrackEventType;
+    timestamp: number;
+    trackId: string;
+    data: unknown;
+}
+export interface SubtitleCue {
+    id: string;
+    startTime: number;
+    endTime: number;
+    text: string;
+    lang?: string;
+}
+export interface ScoreUpdate {
+    key: string;
+    value: number | string;
+    team?: string;
+}
+export interface TimedEvent {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface ChapterMarker {
+    id: string;
+    title: string;
+    startTime: number;
+    endTime?: number;
+    thumbnailUrl?: string;
+}
+export interface MetaTrackOptions {
+    mistBaseUrl: string;
+    streamName: string;
+    subscriptions?: Array<{
+        trackId: string;
+        callback: (event: MetaTrackEvent) => void;
+    }>;
+    enabled?: boolean;
+}
+export interface TelemetryPayload {
+    timestamp: number;
+    sessionId: string;
+    contentId: string;
+    contentType: ContentType;
+    metrics: {
+        currentTime: number;
+        duration: number;
+        bufferedSeconds: number;
+        stallCount: number;
+        totalStallMs: number;
+        bitrate: number;
+        qualityScore: number;
+        framesDecoded: number;
+        framesDropped: number;
+        playerType: string;
+        protocol: string;
+        resolution?: {
+            width: number;
+            height: number;
+        };
+    };
+    errors?: Array<{
+        code: string;
+        message: string;
+        timestamp: number;
+    }>;
+}
+export interface TelemetryOptions {
+    enabled: boolean;
+    endpoint: string;
+    interval?: number;
+    authToken?: string;
+    batchSize?: number;
+}
+/**
+ * Playback mode affects protocol selection:
+ * - 'low-latency': Prefer WebRTC/WHEP for minimal delay (sub-second)
+ * - 'quality': Prefer MP4/WS for stable playback, HLS/DASH as fallback
+ * - 'vod': VOD/clip content - prefer seekable protocols (HLS/MP4), exclude WHEP
+ * - 'auto': Balanced selection (MP4/WS → WHEP → HLS)
+ */
+export type PlaybackMode = 'low-latency' | 'quality' | 'vod' | 'auto';
+/** ABR mode configuration */
+export type ABRMode = 'auto' | 'resize' | 'bitrate' | 'manual';
+/** ABR controller options */
+export interface ABROptions {
+    mode: ABRMode;
+    maxResolution?: {
+        width: number;
+        height: number;
+    };
+    maxBitrate?: number;
+    minBufferForUpgrade?: number;
+    downgradeThreshold?: number;
+}
+/**
+ * Combined metadata from Gateway and MistServer
+ * Emitted via onMetadata callback when player resolves content
+ */
+export interface PlayerMetadata {
+    title?: string;
+    description?: string;
+    contentId?: string;
+    contentType?: ContentType;
+    isLive?: boolean;
+    viewers?: number;
+    durationSeconds?: number;
+    status?: string;
+    createdAt?: string;
+    nodeId?: string;
+    protocol?: string;
+    geoDistance?: number;
+    tracks?: Array<{
+        type: 'video' | 'audio' | 'meta';
+        codec?: string;
+        width?: number;
+        height?: number;
+        bitrate?: number;
+        fps?: number;
+        channels?: number;
+        sampleRate?: number;
+    }>;
+}

package/dist/types/vanilla/FrameWorksPlayer.d.ts

@@ -0,0 +1,143 @@
+/**
+ * FrameWorksPlayer.ts
+ *
+ * Vanilla JavaScript wrapper for PlayerController.
+ * Use this class in non-React environments (Svelte, Vue, plain HTML, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { FrameWorksPlayer } from '@livepeer-frameworks/player/vanilla';
+ * import '@livepeer-frameworks/player/player.css';
+ *
+ * const player = new FrameWorksPlayer('#player', {
+ *   contentId: 'my-stream',
+ *   contentType: 'live',
+ *   gatewayUrl: 'https://gateway.example.com/graphql',
+ *   onStateChange: (state) => console.log('State:', state),
+ * });
+ *
+ * // Control playback
+ * player.play();
+ * player.setVolume(0.5);
+ *
+ * // Clean up
+ * player.destroy();
+ * ```
+ */
+import { PlayerControllerEvents } from '../core/PlayerController';
+import type { PlayerState, PlayerStateContext, StreamState, ContentEndpoints, ContentType } from '../types';
+export interface FrameWorksPlayerOptions {
+    /** Content identifier (stream name) */
+    contentId: string;
+    /** Content type */
+    contentType: ContentType;
+    /** Pre-resolved endpoints (skip gateway) */
+    endpoints?: ContentEndpoints;
+    /** Gateway URL (required if endpoints not provided) */
+    gatewayUrl?: string;
+    /** Auth token for private streams */
+    authToken?: string;
+    /** Playback options */
+    autoplay?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+    poster?: string;
+    /** Debug logging */
+    debug?: boolean;
+    /** Called when player state changes */
+    onStateChange?: (state: PlayerState, context?: PlayerStateContext) => void;
+    /** Called when stream state changes (for live streams) */
+    onStreamStateChange?: (state: StreamState) => void;
+    /** Called on time update during playback */
+    onTimeUpdate?: (currentTime: number, duration: number) => void;
+    /** Called on error */
+    onError?: (error: string) => void;
+    /** Called when player is ready */
+    onReady?: (videoElement: HTMLVideoElement) => void;
+}
+interface LegacyConfig {
+    contentId: string;
+    contentType: ContentType;
+    thumbnailUrl?: string | null;
+    options?: {
+        gatewayUrl?: string;
+        autoplay?: boolean;
+        muted?: boolean;
+        controls?: boolean;
+        debug?: boolean;
+        authToken?: string;
+    };
+}
+/**
+ * Vanilla JavaScript player class.
+ *
+ * This is a thin wrapper around PlayerController that provides a
+ * constructor-based API suitable for non-React frameworks.
+ */
+export declare class FrameWorksPlayer {
+    private controller;
+    private container;
+    private cleanupFns;
+    private isDestroyed;
+    /**
+     * Create a new player instance.
+     *
+     * @param container - DOM element or CSS selector to mount the player
+     * @param options - Player options and callbacks
+     */
+    constructor(container: HTMLElement | string | null, options: FrameWorksPlayerOptions | LegacyConfig);
+    /** Start playback */
+    play(): Promise<void>;
+    /** Pause playback */
+    pause(): void;
+    /** Seek to time in seconds */
+    seek(time: number): void;
+    /** Set volume (0-1) */
+    setVolume(volume: number): void;
+    /** Set muted state */
+    setMuted(muted: boolean): void;
+    /** Set playback rate */
+    setPlaybackRate(rate: number): void;
+    /** Jump to live edge (for live streams) */
+    jumpToLive(): void;
+    /** Request fullscreen */
+    requestFullscreen(): Promise<void>;
+    /** Request Picture-in-Picture */
+    requestPiP(): Promise<void>;
+    /** Get current player state */
+    getState(): PlayerState;
+    /** Get current stream state (for live streams) */
+    getStreamState(): StreamState | null;
+    /** Get video element (null if not ready) */
+    getVideoElement(): HTMLVideoElement | null;
+    /** Check if player is ready */
+    isReady(): boolean;
+    /** Get current time in seconds */
+    getCurrentTime(): number;
+    /** Get duration in seconds */
+    getDuration(): number;
+    /** Check if paused */
+    isPaused(): boolean;
+    /** Check if muted */
+    isMuted(): boolean;
+    /** Retry playback after error */
+    retry(): Promise<void>;
+    /** Get content metadata (title, description, duration, viewers, etc.) */
+    getMetadata(): import("..").ContentMetadata | null;
+    /** Get playback statistics */
+    getStats(): Promise<unknown>;
+    /** Get current latency (for live streams) */
+    getLatency(): Promise<unknown>;
+    /**
+     * Subscribe to a player event.
+     * @param event - Event name
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    on<K extends keyof PlayerControllerEvents>(event: K, listener: (data: PlayerControllerEvents[K]) => void): () => void;
+    /** Destroy the player and clean up resources */
+    destroy(): void;
+    private normalizeOptions;
+    private setupCallbacks;
+}
+export default FrameWorksPlayer;

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

@@ -0,0 +1,19 @@
+/**
+ * Vanilla JS exports for non-React environments.
+ *
+ * @example
+ * ```typescript
+ * import { FrameWorksPlayer } from '@livepeer-frameworks/player/vanilla';
+ * import '@livepeer-frameworks/player/player.css';
+ *
+ * const player = new FrameWorksPlayer('#player', {
+ *   contentId: 'my-stream',
+ *   contentType: 'live',
+ *   gatewayUrl: 'https://gateway.example.com/graphql',
+ * });
+ * ```
+ */
+export { FrameWorksPlayer, default } from './FrameWorksPlayer';
+export type { FrameWorksPlayerOptions } from './FrameWorksPlayer';
+export type { PlayerControllerEvents } from '../core/PlayerController';
+export type { PlayerState, PlayerStateContext, StreamState, ContentEndpoints } from '../types';