@livepeer-frameworks/player-core 0.0.3

package/dist/types/core/SeekingUtils.d.ts

@@ -0,0 +1,142 @@
+/**
+ * SeekingUtils.ts
+ *
+ * Centralized seeking and live detection logic for player controls.
+ * Used by React, Svelte, and Vanilla wrappers to ensure consistent behavior.
+ *
+ * Key concepts:
+ * - Seekable range: The portion of the stream that can be seeked to
+ * - Live edge: The furthest point in time that can be played (live point)
+ * - Near live: Whether playback is close enough to live edge to show "LIVE" badge
+ * - Latency tier: Protocol-based classification affecting live detection thresholds
+ */
+import type { MistStreamInfo } from '../types';
+export type LatencyTier = 'ultra-low' | 'low' | 'medium' | 'high';
+export interface LiveThresholds {
+    /** Seconds behind live edge to exit "LIVE" state (become clickable) */
+    exitLive: number;
+    /** Seconds behind live edge to enter "LIVE" state (become non-clickable) */
+    enterLive: number;
+}
+export interface SeekableRange {
+    /** Start of seekable range in seconds */
+    seekableStart: number;
+    /** End of seekable range (live edge) in seconds */
+    liveEdge: number;
+}
+export interface SeekableRangeParams {
+    isLive: boolean;
+    video: HTMLVideoElement | null;
+    mistStreamInfo?: MistStreamInfo;
+    currentTime: number;
+    duration: number;
+}
+export interface CanSeekParams {
+    video: HTMLVideoElement | null;
+    isLive: boolean;
+    duration: number;
+    bufferWindowMs?: number;
+    playerCanSeek?: () => boolean;
+}
+/**
+ * Latency tier thresholds for "near live" detection.
+ * Different protocols have vastly different latency expectations.
+ *
+ * exitLive: How far behind (seconds) before we show "behind live" indicator
+ * enterLive: How close to live (seconds) before we show "LIVE" badge again
+ *
+ * The gap between exitLive and enterLive creates hysteresis to prevent flicker.
+ */
+export declare const LATENCY_TIERS: Record<LatencyTier, LiveThresholds>;
+/**
+ * Playback speed presets for UI controls.
+ */
+export declare const SPEED_PRESETS: readonly [0.5, 1, 1.5, 2];
+/**
+ * Default fallback buffer window when no other info available (in seconds).
+ * Aligned with MistServer reference player's 60-second default.
+ */
+export declare const DEFAULT_BUFFER_WINDOW_SEC = 60;
+/**
+ * Detect latency tier from source type string.
+ *
+ * @param sourceType - MIME type or protocol identifier (e.g., 'whep', 'ws/video/mp4')
+ * @returns Latency tier classification
+ */
+export declare function getLatencyTier(sourceType?: string): LatencyTier;
+/**
+ * Check if video element is using WebRTC/MediaStream source.
+ * WebRTC streams have special constraints (no seeking, no playback rate changes).
+ *
+ * @param video - HTML video element
+ * @returns true if source is a MediaStream
+ */
+export declare function isMediaStreamSource(video: HTMLVideoElement | null): boolean;
+/**
+ * Check if playback rate adjustment is supported.
+ * WebRTC/MediaStream sources don't support playback rate changes.
+ *
+ * @param video - HTML video element
+ * @returns true if playback rate can be changed
+ */
+export declare function supportsPlaybackRate(video: HTMLVideoElement | null): boolean;
+/**
+ * Calculate seekable range for live or VOD streams.
+ *
+ * Priority order:
+ * 1. Browser's video.seekable ranges (most accurate for MSE-based players)
+ * 2. Track firstms/lastms from MistServer metadata
+ * 3. buffer_window from MistServer signaling
+ * 4. Fallback (only for non-WebRTC sources)
+ *
+ * @param params - Calculation parameters
+ * @returns Seekable range with start and live edge
+ */
+export declare function calculateSeekableRange(params: SeekableRangeParams): SeekableRange;
+/**
+ * Determine if seeking is supported for the current stream.
+ *
+ * @param params - Check parameters
+ * @returns true if seeking is available
+ */
+export declare function canSeekStream(params: CanSeekParams): boolean;
+/**
+ * Calculate live detection thresholds, optionally scaled by buffer_window.
+ *
+ * For medium/high latency tiers, scales thresholds based on the actual
+ * buffer window to provide more appropriate "near live" detection.
+ *
+ * @param sourceType - Protocol/MIME type for tier detection
+ * @param isWebRTC - Whether source is WebRTC (overrides tier to ultra-low)
+ * @param bufferWindowMs - Optional buffer window in milliseconds
+ * @returns Thresholds for entering/exiting "LIVE" state
+ */
+export declare function calculateLiveThresholds(sourceType?: string, isWebRTC?: boolean, bufferWindowMs?: number): LiveThresholds;
+/**
+ * Calculate whether playback is "near live" using hysteresis.
+ *
+ * Hysteresis prevents flip-flopping when hovering near the threshold:
+ * - To EXIT "LIVE" state: must be > exitLive + margin behind
+ * - To ENTER "LIVE" state: must be < enterLive - margin behind
+ *
+ * @param currentTime - Current playback position in seconds
+ * @param liveEdge - Live edge position in seconds
+ * @param thresholds - Enter/exit thresholds
+ * @param currentState - Current isNearLive state
+ * @returns New isNearLive state
+ */
+export declare function calculateIsNearLive(currentTime: number, liveEdge: number, thresholds: LiveThresholds, currentState: boolean): boolean;
+/**
+ * Determine if content is live based on available metadata.
+ *
+ * Priority:
+ * 1. Explicit isContentLive flag (highest priority)
+ * 2. MistServer stream type
+ * 3. Duration check (non-finite = live)
+ *
+ * @param isContentLive - Explicit live flag from content metadata
+ * @param mistStreamInfo - MistServer stream info
+ * @param duration - Video duration
+ * @returns true if content is live
+ */
+export declare function isLiveContent(isContentLive?: boolean, mistStreamInfo?: MistStreamInfo, duration?: number): boolean;

package/dist/types/core/StreamStateClient.d.ts

@@ -0,0 +1,108 @@
+/**
+ * StreamStateClient.ts
+ *
+ * Framework-agnostic client for polling MistServer stream status via WebSocket or HTTP.
+ * Extracted from useStreamState.ts for use in headless core.
+ */
+import { TypedEventEmitter } from './EventEmitter';
+import type { StreamState } from '../types';
+export interface StreamStateClientConfig {
+    /** MistServer base URL (e.g., https://mist.example.com) */
+    mistBaseUrl: string;
+    /** Stream name to poll */
+    streamName: string;
+    /** Poll interval in ms for HTTP fallback (default: 3000) */
+    pollInterval?: number;
+    /** Use WebSocket if available (default: true) */
+    useWebSocket?: boolean;
+}
+export interface StreamStateClientEvents {
+    /** Emitted when stream state changes */
+    stateChange: {
+        state: StreamState;
+    };
+    /** Emitted when stream comes online */
+    online: void;
+    /** Emitted when stream goes offline */
+    offline: void;
+    /** Emitted on connection error */
+    error: {
+        error: string;
+    };
+}
+/**
+ * Client for polling MistServer stream status via WebSocket or HTTP.
+ *
+ * @example
+ * ```typescript
+ * const client = new StreamStateClient({
+ *   mistBaseUrl: 'https://mist.example.com',
+ *   streamName: 'my-stream',
+ * });
+ *
+ * client.on('stateChange', ({ state }) => console.log('State:', state));
+ * client.on('online', () => console.log('Stream is online!'));
+ * client.on('offline', () => console.log('Stream is offline'));
+ *
+ * client.start();
+ * // ...later
+ * client.stop();
+ * ```
+ */
+export declare class StreamStateClient extends TypedEventEmitter<StreamStateClientEvents> {
+    private config;
+    private state;
+    private ws;
+    private timers;
+    private isRunning;
+    private wasOnline;
+    private connectionId;
+    private static readonly CONNECTION_DEBOUNCE_MS;
+    constructor(config: StreamStateClientConfig);
+    /**
+     * Start polling/WebSocket connection.
+     * Always does initial HTTP poll to get full stream info (including sources),
+     * then connects WebSocket for real-time status updates.
+     *
+     * Debounced to prevent orphaned connections during rapid mount/unmount cycles.
+     */
+    start(): void;
+    /**
+     * Stop polling and close connections.
+     */
+    stop(): void;
+    /**
+     * Manual refresh - trigger an immediate poll.
+     */
+    refresh(): void;
+    /**
+     * Get the underlying WebSocket connection (for MistReporter integration).
+     * Returns null if WebSocket is not connected.
+     */
+    getSocket(): WebSocket | null;
+    /**
+     * Check if the WebSocket is connected and ready.
+     */
+    isSocketReady(): boolean;
+    /**
+     * Get current stream state.
+     */
+    getState(): StreamState;
+    /**
+     * Check if stream is online.
+     */
+    isOnline(): boolean;
+    /**
+     * Update configuration (stops and restarts if running).
+     */
+    updateConfig(config: Partial<StreamStateClientConfig>): void;
+    /**
+     * Clean up resources.
+     */
+    destroy(): void;
+    private connectWebSocket;
+    private pollHttp;
+    private processStreamInfo;
+    private setState;
+}
+export default StreamStateClient;

package/dist/types/core/SubtitleManager.d.ts

@@ -0,0 +1,111 @@
+/**
+ * SubtitleManager - WebVTT subtitle track management
+ *
+ * Based on MistMetaPlayer's subtitle handling (wrappers/html5.js, webrtc.js).
+ * Manages text tracks on video elements with support for:
+ * - Loading WebVTT from MistServer URLs
+ * - Multiple subtitle track selection
+ * - Sync correction for WebRTC seek offsets
+ */
+export interface SubtitleTrackInfo {
+    /** Track ID (from MistServer) */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Language code (e.g., 'en', 'es') */
+    lang: string;
+    /** Source URL for WebVTT file */
+    src: string;
+    /** Whether this is the default track */
+    default?: boolean;
+}
+export interface SubtitleManagerConfig {
+    /** Base URL for MistServer (for constructing track URLs) */
+    mistBaseUrl?: string;
+    /** Stream name */
+    streamName?: string;
+    /** URL append string (auth tokens, etc.) */
+    urlAppend?: string;
+    /** Debug logging */
+    debug?: boolean;
+}
+/**
+ * SubtitleManager handles text track lifecycle on a video element
+ */
+export declare class SubtitleManager {
+    private video;
+    private config;
+    private currentTrackId;
+    private seekOffset;
+    private debug;
+    private listeners;
+    constructor(config?: SubtitleManagerConfig);
+    /**
+     * Attach to a video element
+     */
+    attach(video: HTMLVideoElement): void;
+    /**
+     * Detach from video element
+     */
+    detach(): void;
+    /**
+     * Get available text tracks from the video element
+     */
+    getTextTracks(): TextTrack[];
+    /**
+     * Get all track elements from the video
+     */
+    getTrackElements(): HTMLTrackElement[];
+    /**
+     * Set the active subtitle track
+     * Pass null to disable subtitles
+     */
+    setSubtitle(track: SubtitleTrackInfo | null): void;
+    /**
+     * Build track URL with base URL and append params
+     */
+    private buildTrackUrl;
+    /**
+     * Create subtitle track info from MistServer track metadata
+     */
+    static createTrackInfo(trackId: string, label: string, lang: string, baseUrl: string, streamName: string): SubtitleTrackInfo;
+    /**
+     * Remove all track elements from video
+     */
+    removeAllTracks(): void;
+    /**
+     * Get currently active track ID
+     */
+    getCurrentTrackId(): string | null;
+    /**
+     * Set seek offset for WebRTC sync correction
+     * WebRTC playback has a seek offset that needs to be applied to subtitle timing
+     */
+    setSeekOffset(offset: number): void;
+    /**
+     * Correct subtitle timing based on seek offset
+     * This is needed for WebRTC where video.currentTime doesn't match actual playback position
+     */
+    private correctSubtitleSync;
+    /**
+     * Parse subtitle tracks from MistServer stream info
+     */
+    static parseTracksFromStreamInfo(streamInfo: {
+        meta?: {
+            tracks?: Record<string, {
+                type: string;
+                codec: string;
+                lang?: string;
+            }>;
+        };
+    }, baseUrl: string, streamName: string): SubtitleTrackInfo[];
+    /**
+     * Debug logging
+     */
+    private log;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+export default SubtitleManager;

package/dist/types/core/TelemetryReporter.d.ts

@@ -0,0 +1,79 @@
+import type { PlaybackQuality, ContentType } from '../types';
+export interface TelemetryReporterConfig {
+    /** Telemetry endpoint URL */
+    endpoint: string;
+    /** Auth token for endpoint */
+    authToken?: string;
+    /** Report interval in ms (default: 5000) */
+    interval?: number;
+    /** Batch size before flush (default: 1) */
+    batchSize?: number;
+    /** Content ID being played */
+    contentId: string;
+    /** Content type */
+    contentType: ContentType;
+    /** Player type name */
+    playerType: string;
+    /** Protocol being used */
+    protocol: string;
+}
+/**
+ * TelemetryReporter - Sends playback metrics to server
+ *
+ * Features:
+ * - Batched reporting at configurable interval
+ * - Retry with exponential backoff on failure
+ * - Uses navigator.sendBeacon() for reliable page unload reporting
+ * - Tracks errors during playback
+ */
+export declare class TelemetryReporter {
+    private config;
+    private sessionId;
+    private intervalId;
+    private pendingPayloads;
+    private errors;
+    private stallCount;
+    private totalStallMs;
+    private lastStallStart;
+    private videoElement;
+    private qualityGetter;
+    private listeners;
+    constructor(config: TelemetryReporterConfig);
+    /**
+     * Start telemetry reporting
+     */
+    start(videoElement: HTMLVideoElement, qualityGetter?: () => PlaybackQuality | null): void;
+    /**
+     * Stop telemetry reporting
+     */
+    stop(): void;
+    /**
+     * Record a custom error
+     */
+    recordError(code: string, message: string): void;
+    /**
+     * Generate telemetry payload
+     */
+    private generatePayload;
+    /**
+     * Send telemetry report
+     */
+    private report;
+    /**
+     * Flush pending payloads (async)
+     */
+    private flush;
+    /**
+     * Flush synchronously using sendBeacon (for page unload)
+     */
+    private flushSync;
+    /**
+     * Get session ID
+     */
+    getSessionId(): string;
+    /**
+     * Check if reporting is active
+     */
+    isActive(): boolean;
+}
+export default TelemetryReporter;

package/dist/types/core/TimeFormat.d.ts

@@ -0,0 +1,97 @@
+/**
+ * TimeFormat.ts
+ *
+ * Time formatting utilities for player controls.
+ * Used by React, Svelte, and Vanilla wrappers.
+ */
+export interface TimeDisplayParams {
+    isLive: boolean;
+    currentTime: number;
+    duration: number;
+    liveEdge: number;
+    seekableStart: number;
+    /** Unix timestamp (ms) at stream time 0 - for wall-clock display */
+    unixoffset?: number;
+}
+/**
+ * Format seconds as MM:SS or HH:MM:SS.
+ *
+ * @param seconds - Time in seconds
+ * @returns Formatted time string, or "LIVE" for invalid input
+ *
+ * @example
+ * formatTime(65)    // "01:05"
+ * formatTime(3665)  // "1:01:05"
+ * formatTime(-1)    // "LIVE"
+ * formatTime(NaN)   // "LIVE"
+ */
+export declare function formatTime(seconds: number): string;
+/**
+ * Format a Date as wall-clock time (HH:MM:SS).
+ *
+ * @param date - Date object
+ * @returns Formatted time string in HH:MM:SS format
+ *
+ * @example
+ * formatClockTime(new Date('2024-01-15T14:30:45'))  // "14:30:45"
+ */
+export declare function formatClockTime(date: Date): string;
+/**
+ * Format time display for player controls.
+ *
+ * For live streams:
+ * - With unixoffset: Shows actual wall-clock time (HH:MM:SS)
+ * - With seekable window: Shows time behind live (-MM:SS) or "LIVE"
+ * - Fallback: Shows elapsed time
+ *
+ * For VOD:
+ * - Shows "current / duration" (MM:SS / MM:SS)
+ *
+ * @param params - Display parameters
+ * @returns Formatted time display string
+ *
+ * @example
+ * // Live with unixoffset
+ * formatTimeDisplay({ isLive: true, currentTime: 60, unixoffset: 1705330245000, ... })
+ * // "14:30:45"
+ *
+ * // Live behind
+ * formatTimeDisplay({ isLive: true, currentTime: 50, liveEdge: 60, ... })
+ * // "-00:10"
+ *
+ * // VOD
+ * formatTimeDisplay({ isLive: false, currentTime: 65, duration: 300, ... })
+ * // "01:05 / 05:00"
+ */
+export declare function formatTimeDisplay(params: TimeDisplayParams): string;
+/**
+ * Format time for seek bar tooltip.
+ * For live streams, can show time relative to live edge.
+ *
+ * @param time - Time position in seconds
+ * @param isLive - Whether stream is live
+ * @param liveEdge - Live edge position (for relative display)
+ * @returns Formatted tooltip time
+ */
+export declare function formatTooltipTime(time: number, isLive: boolean, liveEdge?: number): string;
+/**
+ * Format duration for display (e.g., in stats panel).
+ * Handles edge cases like infinite duration for live streams.
+ *
+ * @param duration - Duration in seconds
+ * @param isLive - Whether content is live
+ * @returns Formatted duration string
+ */
+export declare function formatDuration(duration: number, isLive?: boolean): string;
+/**
+ * Parse time string (HH:MM:SS or MM:SS) to seconds.
+ *
+ * @param timeStr - Time string to parse
+ * @returns Time in seconds, or NaN if invalid
+ *
+ * @example
+ * parseTime("01:30")     // 90
+ * parseTime("1:30:45")   // 5445
+ * parseTime("invalid")   // NaN
+ */
+export declare function parseTime(timeStr: string): number;

package/dist/types/core/TimerManager.d.ts

@@ -0,0 +1,83 @@
+/**
+ * TimerManager - Centralized timer management for memory leak prevention
+ *
+ * Tracks all setTimeout/setInterval calls and provides bulk cleanup.
+ * Based on MistMetaPlayer's MistVideo.timers pattern.
+ *
+ * Usage:
+ * ```ts
+ * const timers = new TimerManager();
+ *
+ * // Start a timeout
+ * const id = timers.start(() => console.log('fired'), 1000);
+ *
+ * // Start an interval
+ * const intervalId = timers.startInterval(() => console.log('tick'), 500);
+ *
+ * // Stop a specific timer
+ * timers.stop(id);
+ *
+ * // Stop all timers (on cleanup/destroy)
+ * timers.stopAll();
+ * ```
+ */
+export declare class TimerManager {
+    private timers;
+    private nextId;
+    private debug;
+    constructor(options?: {
+        debug?: boolean;
+    });
+    /**
+     * Start a timeout
+     * @param callback Function to call after delay
+     * @param delay Delay in milliseconds
+     * @param label Optional label for debugging
+     * @returns Timer ID (internal, not the native timeout ID)
+     */
+    start(callback: () => void, delay: number, label?: string): number;
+    /**
+     * Start an interval
+     * @param callback Function to call repeatedly
+     * @param interval Interval in milliseconds
+     * @param label Optional label for debugging
+     * @returns Timer ID (internal, not the native interval ID)
+     */
+    startInterval(callback: () => void, interval: number, label?: string): number;
+    /**
+     * Stop a specific timer
+     * @param internalId The timer ID returned by start() or startInterval()
+     */
+    stop(internalId: number): boolean;
+    /**
+     * Stop all active timers
+     * Call this on component unmount/destroy to prevent memory leaks
+     */
+    stopAll(): void;
+    /**
+     * Get count of active timers
+     */
+    get activeCount(): number;
+    /**
+     * Check if a timer is active
+     */
+    isActive(internalId: number): boolean;
+    /**
+     * Get remaining time for a timeout (0 for intervals or expired)
+     */
+    getRemainingTime(internalId: number): number;
+    /**
+     * Get debug info about all active timers
+     */
+    getDebugInfo(): Array<{
+        id: number;
+        type: 'timeout' | 'interval';
+        label?: string;
+        remainingMs?: number;
+    }>;
+    /**
+     * Cleanup - alias for stopAll()
+     */
+    destroy(): void;
+}
+export default TimerManager;

package/dist/types/core/UrlUtils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * UrlUtils - URL manipulation utilities
+ *
+ * Based on MistMetaPlayer's urlappend functionality.
+ * Provides helpers for appending query parameters to URLs.
+ */
+/**
+ * Append query parameters to a URL
+ * Handles URLs that already have query parameters
+ *
+ * @param url - Base URL
+ * @param params - Parameters to append (string or object)
+ * @returns URL with appended parameters
+ *
+ * @example
+ * ```ts
+ * appendUrlParams('https://example.com/video.m3u8', 'token=abc&session=123')
+ * // => 'https://example.com/video.m3u8?token=abc&session=123'
+ *
+ * appendUrlParams('https://example.com/video.m3u8?existing=param', 'token=abc')
+ * // => 'https://example.com/video.m3u8?existing=param&token=abc'
+ *
+ * appendUrlParams('https://example.com/video.m3u8', { token: 'abc', session: '123' })
+ * // => 'https://example.com/video.m3u8?token=abc&session=123'
+ * ```
+ */
+export declare function appendUrlParams(url: string, params: string | Record<string, string | number | boolean | undefined | null>): string;
+/**
+ * Parse query parameters from a URL
+ *
+ * @param url - URL to parse
+ * @returns Object with query parameters
+ */
+export declare function parseUrlParams(url: string): Record<string, string>;
+/**
+ * Remove query parameters from a URL
+ *
+ * @param url - URL to strip
+ * @returns URL without query parameters
+ */
+export declare function stripUrlParams(url: string): string;
+/**
+ * Build a URL with query parameters
+ *
+ * @param baseUrl - Base URL
+ * @param params - Query parameters
+ * @returns Complete URL
+ */
+export declare function buildUrl(baseUrl: string, params: Record<string, string | number | boolean | undefined | null>): string;
+/**
+ * Check if URL uses secure protocol (https/wss)
+ */
+export declare function isSecureUrl(url: string): boolean;
+/**
+ * Convert HTTP URL to WebSocket URL
+ * http:// -> ws://
+ * https:// -> wss://
+ */
+export declare function httpToWs(url: string): string;
+/**
+ * Convert WebSocket URL to HTTP URL
+ * ws:// -> http://
+ * wss:// -> https://
+ */
+export declare function wsToHttp(url: string): string;
+/**
+ * Ensure URL uses the same protocol as the current page
+ * Useful for avoiding mixed content issues
+ */
+export declare function matchPageProtocol(url: string): string;
+declare const _default: {
+    appendUrlParams: typeof appendUrlParams;
+    parseUrlParams: typeof parseUrlParams;
+    stripUrlParams: typeof stripUrlParams;
+    buildUrl: typeof buildUrl;
+    isSecureUrl: typeof isSecureUrl;
+    httpToWs: typeof httpToWs;
+    wsToHttp: typeof wsToHttp;
+    matchPageProtocol: typeof matchPageProtocol;
+};
+export default _default;