@livepeer-frameworks/player-core 0.0.3

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

@@ -0,0 +1,164 @@
+import type { ABRMode, ABROptions, PlaybackQuality, QualityLevel } from '../types';
+export interface ABRControllerConfig {
+    /** ABR options */
+    options?: Partial<ABROptions>;
+    /** Callback to get available qualities */
+    getQualities: () => QualityLevel[];
+    /** Callback to select a quality */
+    selectQuality: (id: string | 'auto') => void;
+    /** Callback to get current quality */
+    getCurrentQuality?: () => QualityLevel | null;
+    /** Callback to get bandwidth estimate (bits per second) - typically from player stats */
+    getBandwidthEstimate?: () => Promise<number>;
+    /** Debug logging */
+    debug?: boolean;
+}
+export type ABRDecision = 'upgrade' | 'downgrade' | 'maintain' | 'none';
+/**
+ * ABRController - Adaptive Bitrate Controller
+ *
+ * Manages automatic quality selection based on:
+ * - ABR_resize: Matches video resolution to viewport size
+ * - ABR_bitrate: Switches quality based on playback performance
+ * - auto: Combines both modes
+ * - manual: No automatic switching
+ *
+ * @example
+ * ```ts
+ * const abr = new ABRController({
+ *   options: { mode: 'auto' },
+ *   getQualities: () => player.getQualities(),
+ *   selectQuality: (id) => player.selectQuality(id),
+ * });
+ *
+ * abr.start(videoElement);
+ * abr.onQualityChange((quality) => console.log('Quality:', quality.score));
+ * ```
+ */
+export declare class ABRController {
+    private options;
+    private config;
+    private videoElement;
+    private currentQualityId;
+    private lastDecision;
+    private lastDecisionTime;
+    private resizeObserver;
+    private qualityChangeCallbacks;
+    private debug;
+    private timers;
+    private bandwidthHistory;
+    private static readonly BANDWIDTH_HISTORY_SIZE;
+    private static readonly MONITORING_INTERVAL_MS;
+    private static readonly UPGRADE_COOLDOWN_MS;
+    private static readonly DOWNGRADE_COOLDOWN_MS;
+    private lastUpgradeTime;
+    private lastDowngradeTime;
+    private static readonly UPGRADE_HEADROOM;
+    private static readonly UPGRADE_HOLD_THRESHOLD;
+    private static readonly DOWNGRADE_THRESHOLD;
+    private currentQualityBitrate;
+    constructor(config: ABRControllerConfig);
+    /**
+     * Start ABR control
+     */
+    start(videoElement: HTMLVideoElement): void;
+    /**
+     * Stop ABR control
+     */
+    stop(): void;
+    /**
+     * Start active bandwidth monitoring loop
+     * Continuously monitors bandwidth and proactively switches quality
+     */
+    private startActiveMonitoring;
+    /**
+     * Check current bandwidth and switch quality if needed
+     *
+     * Uses hysteresis (D2) and separate cooldowns (D3) to prevent oscillation:
+     * - Downgrade: immediate response (0ms cooldown), triggers at 0.8x
+     * - Upgrade: 5s cooldown, requires 1.5x headroom, holds until 1.2x
+     */
+    private checkBandwidthAndSwitch;
+    /**
+     * Get bandwidth estimate from player stats
+     */
+    private getBandwidthEstimate;
+    /**
+     * Get smoothed bandwidth from history
+     */
+    private getSmoothedBandwidth;
+    /**
+     * Get current bandwidth estimate (for external use)
+     */
+    getCurrentBandwidth(): number;
+    /**
+     * Setup resize observer for viewport-based quality selection
+     */
+    private setupResizeObserver;
+    /**
+     * Handle viewport resize (ABR_resize mode)
+     */
+    private handleResize;
+    /**
+     * Handle quality degradation (ABR_bitrate mode)
+     *
+     * Called by QualityMonitor when playback quality drops
+     */
+    handleQualityDegraded(quality: PlaybackQuality): void;
+    /**
+     * Handle quality improvement opportunity
+     *
+     * Called when conditions are good enough to try higher quality
+     */
+    handleQualityImproved(quality: PlaybackQuality): void;
+    /**
+     * Find best quality level for given resolution
+     */
+    private findBestQualityForResolution;
+    /**
+     * Find a lower quality level
+     */
+    private findLowerQuality;
+    /**
+     * Find a higher quality level
+     */
+    private findHigherQuality;
+    /**
+     * Check if quality is within configured constraints
+     */
+    private isWithinConstraints;
+    /**
+     * Select a quality level
+     */
+    private selectQuality;
+    /**
+     * Register callback for quality changes
+     */
+    onQualityChange(callback: (level: QualityLevel) => void): () => void;
+    /**
+     * Manually set quality (switches to manual mode temporarily)
+     */
+    setQuality(id: string | 'auto'): void;
+    /**
+     * Get current ABR mode
+     */
+    getMode(): ABRMode;
+    /**
+     * Set ABR mode at runtime.
+     * Restarts monitoring if video element is attached.
+     */
+    setMode(mode: ABRMode): void;
+    /**
+     * Update ABR options
+     */
+    updateOptions(options: Partial<ABROptions>): void;
+    /**
+     * Get last ABR decision
+     */
+    getLastDecision(): ABRDecision;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+export default ABRController;

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

@@ -0,0 +1,54 @@
+/**
+ * CodecUtils - Codec string translation utilities
+ *
+ * Based on MistMetaPlayer's MistUtil.tracks.translateCodec functionality.
+ * Translates MistServer codec names to browser-compatible codec strings.
+ */
+export interface TrackInfo {
+    type: string;
+    codec: string;
+    init?: string;
+    codecstring?: string;
+    width?: number;
+    height?: number;
+    bps?: number;
+    fpks?: number;
+}
+/**
+ * Translate a MistServer codec name to a browser-compatible codec string
+ *
+ * @param track - Track info from MistServer
+ * @returns Browser-compatible codec string (e.g., "avc1.64001f")
+ *
+ * @example
+ * ```ts
+ * translateCodec({ codec: 'H264', type: 'video' })
+ * // => 'avc1.42E01E' (baseline profile, level 3.0 default)
+ *
+ * translateCodec({ codec: 'AAC', type: 'audio' })
+ * // => 'mp4a.40.2'
+ * ```
+ */
+export declare function translateCodec(track: TrackInfo): string;
+/**
+ * Check if a codec is supported by the browser via MediaSource
+ *
+ * @param codecString - Codec string to check
+ * @param containerType - Container type (default: 'video/mp4')
+ * @returns true if supported
+ */
+export declare function isCodecSupported(codecString: string, containerType?: string): boolean;
+/**
+ * Get the best supported codec from a list of tracks
+ *
+ * @param tracks - Array of track info
+ * @param type - Track type to filter ('video' or 'audio')
+ * @returns Best supported track or null
+ */
+export declare function getBestSupportedTrack(tracks: TrackInfo[], type: 'video' | 'audio'): TrackInfo | null;
+declare const _default: {
+    translateCodec: typeof translateCodec;
+    isCodecSupported: typeof isCodecSupported;
+    getBestSupportedTrack: typeof getBestSupportedTrack;
+};
+export default _default;

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

@@ -0,0 +1,61 @@
+/**
+ * Disposable interface for consistent cleanup across all core classes.
+ *
+ * All classes that manage resources (timers, event listeners, WebSockets, etc.)
+ * should implement this interface to ensure proper cleanup.
+ */
+/**
+ * Interface for objects that need cleanup
+ */
+export interface Disposable {
+    /**
+     * Clean up all resources held by this object.
+     * Safe to call multiple times - subsequent calls should be no-ops.
+     */
+    dispose(): void;
+    /**
+     * Whether this object has been disposed
+     */
+    readonly disposed: boolean;
+}
+/**
+ * Base class for disposable objects that provides:
+ * - disposed flag tracking
+ * - Double-dispose protection
+ * - Template method for subclass cleanup
+ */
+export declare abstract class BaseDisposable implements Disposable {
+    private _disposed;
+    /**
+     * Whether this object has been disposed
+     */
+    get disposed(): boolean;
+    /**
+     * Dispose of this object, releasing all resources.
+     * Safe to call multiple times.
+     */
+    dispose(): void;
+    /**
+     * Subclasses implement this to clean up their resources.
+     * Called exactly once when dispose() is first called.
+     */
+    protected abstract onDispose(): void;
+    /**
+     * Throw if this object has been disposed.
+     * Use at the start of methods that shouldn't run after disposal.
+     */
+    protected throwIfDisposed(operation?: string): void;
+    /**
+     * Check if disposed without throwing - useful for conditional guards
+     */
+    protected guardDisposed(): boolean;
+}
+/**
+ * Utility to dispose multiple disposables at once
+ */
+export declare function disposeAll(...disposables: (Disposable | null | undefined)[]): void;
+/**
+ * Create a composite disposable that disposes multiple items
+ */
+export declare function createCompositeDisposable(...disposables: (Disposable | (() => void))[]): Disposable;
+export default BaseDisposable;

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

@@ -0,0 +1,73 @@
+/**
+ * EventEmitter.ts
+ *
+ * A lightweight, typed event emitter for framework-agnostic components.
+ * Used by GatewayClient, StreamStateClient, and PlayerController.
+ */
+type Listener<T> = (data: T) => void;
+/**
+ * Typed event emitter that provides type-safe event handling.
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   stateChange: { state: string };
+ *   error: { message: string };
+ * }
+ *
+ * class MyClass extends TypedEventEmitter<MyEvents> {
+ *   doSomething() {
+ *     this.emit('stateChange', { state: 'ready' });
+ *   }
+ * }
+ *
+ * const instance = new MyClass();
+ * const unsub = instance.on('stateChange', ({ state }) => console.log(state));
+ * unsub(); // unsubscribe
+ * ```
+ */
+export declare class TypedEventEmitter<Events extends Record<string, any>> {
+    private listeners;
+    /**
+     * Subscribe to an event.
+     * @param event - The event name to listen for
+     * @param listener - Callback function invoked when the event is emitted
+     * @returns Unsubscribe function
+     */
+    on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /**
+     * Subscribe to an event only once.
+     * The listener is automatically removed after the first invocation.
+     * @param event - The event name to listen for
+     * @param listener - Callback function invoked when the event is emitted
+     * @returns Unsubscribe function
+     */
+    once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /**
+     * Unsubscribe from an event.
+     * @param event - The event name
+     * @param listener - The callback to remove
+     */
+    off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void;
+    /**
+     * Emit an event to all subscribers.
+     * @param event - The event name
+     * @param data - The event payload
+     */
+    protected emit<K extends keyof Events>(event: K, data: Events[K]): void;
+    /**
+     * Remove all listeners for all events.
+     */
+    removeAllListeners(): void;
+    /**
+     * Remove all listeners for a specific event.
+     * @param event - The event name
+     */
+    removeListeners<K extends keyof Events>(event: K): void;
+    /**
+     * Check if there are any listeners for an event.
+     * @param event - The event name
+     */
+    hasListeners<K extends keyof Events>(event: K): boolean;
+}
+export default TypedEventEmitter;

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

@@ -0,0 +1,144 @@
+/**
+ * GatewayClient.ts
+ *
+ * Framework-agnostic client for resolving viewer endpoints from the Gateway GraphQL API.
+ * Extracted from useViewerEndpoints.ts for use in headless core.
+ */
+import { TypedEventEmitter } from './EventEmitter';
+import type { ContentEndpoints, ContentType } from '../types';
+export type GatewayStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface GatewayClientConfig {
+    /** Gateway GraphQL endpoint URL */
+    gatewayUrl: string;
+    /** Content type to resolve */
+    contentType: ContentType;
+    /** Content identifier (stream name) */
+    contentId: string;
+    /** Optional auth token for private streams */
+    authToken?: string;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial retry delay in ms (default: 500) */
+    initialDelayMs?: number;
+}
+export interface GatewayClientEvents {
+    /** Emitted when status changes */
+    statusChange: {
+        status: GatewayStatus;
+        error?: string;
+    };
+    /** Emitted when endpoints are successfully resolved */
+    endpointsResolved: {
+        endpoints: ContentEndpoints;
+    };
+}
+type CircuitBreakerState = 'closed' | 'open' | 'half-open';
+/**
+ * Client for resolving viewer endpoints from the Gateway GraphQL API.
+ *
+ * @example
+ * ```typescript
+ * const client = new GatewayClient({
+ *   gatewayUrl: 'https://gateway.example.com/graphql',
+ *   contentType: 'live',
+ *   contentId: 'my-stream',
+ * });
+ *
+ * client.on('statusChange', ({ status }) => console.log('Status:', status));
+ * client.on('endpointsResolved', ({ endpoints }) => console.log('Endpoints:', endpoints));
+ *
+ * const endpoints = await client.resolve();
+ * ```
+ */
+export declare class GatewayClient extends TypedEventEmitter<GatewayClientEvents> {
+    private config;
+    private status;
+    private endpoints;
+    private error;
+    private abortController;
+    private inFlightRequest;
+    private cacheTimestamp;
+    private cacheTtlMs;
+    private circuitState;
+    private consecutiveFailures;
+    private circuitOpenedAt;
+    constructor(config: GatewayClientConfig);
+    /**
+     * Resolve endpoints from the gateway.
+     * F2: Returns cached result if still valid, deduplicates concurrent requests.
+     * F3: Respects circuit breaker state.
+     * @param forceRefresh - If true, bypasses cache and fetches fresh data
+     * @returns Promise resolving to ContentEndpoints
+     * @throws Error if resolution fails after retries or circuit is open
+     */
+    resolve(forceRefresh?: boolean): Promise<ContentEndpoints>;
+    /**
+     * F2: Check if cache is still valid
+     */
+    private isCacheValid;
+    /**
+     * F2: Set cache TTL (for testing or custom requirements)
+     */
+    setCacheTtl(ttlMs: number): void;
+    /**
+     * F2: Invalidate the cache manually
+     */
+    invalidateCache(): void;
+    /**
+     * F3: Check if a request can be attempted based on circuit state
+     */
+    private canAttemptRequest;
+    /**
+     * F3: Record a successful request
+     */
+    private onSuccess;
+    /**
+     * F3: Record a failed request
+     */
+    private onFailure;
+    /**
+     * F3: Get current circuit breaker state (for monitoring/debugging)
+     */
+    getCircuitState(): {
+        state: CircuitBreakerState;
+        failures: number;
+        openedAt: number | null;
+    };
+    /**
+     * F3: Manually reset the circuit breaker
+     */
+    resetCircuitBreaker(): void;
+    /**
+     * Internal method to perform the actual resolution.
+     * @returns Promise resolving to ContentEndpoints
+     */
+    private doResolve;
+    /**
+     * Abort any in-flight request.
+     */
+    abort(): void;
+    /**
+     * Get current status.
+     */
+    getStatus(): GatewayStatus;
+    /**
+     * Get resolved endpoints (null if not yet resolved).
+     */
+    getEndpoints(): ContentEndpoints | null;
+    /**
+     * Get error message (null if no error).
+     */
+    getError(): string | null;
+    /**
+     * Update configuration and reset state.
+     * F2: Also clears cache and in-flight request
+     * F3: Resets circuit breaker (new config = fresh start)
+     */
+    updateConfig(config: Partial<GatewayClientConfig>): void;
+    /**
+     * Clean up resources.
+     */
+    destroy(): void;
+    private setStatus;
+}
+export default GatewayClient;

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

@@ -0,0 +1,121 @@
+/**
+ * InteractionController - Unified keyboard and gesture handling for video players
+ *
+ * Features:
+ * - Hold space for 2x speed (VOD/clips only, tap = play/pause)
+ * - Click/touch and hold for 2x speed
+ * - Comprehensive keyboard shortcuts
+ * - Double-tap to skip on mobile
+ * - All interactions disabled for live streams (where applicable)
+ */
+export interface InteractionControllerConfig {
+    container: HTMLElement;
+    videoElement: HTMLVideoElement;
+    isLive: boolean;
+    onPlayPause: () => void;
+    onSeek: (delta: number) => void;
+    onVolumeChange: (delta: number) => void;
+    onMuteToggle: () => void;
+    onFullscreenToggle: () => void;
+    onCaptionsToggle?: () => void;
+    onLoopToggle?: () => void;
+    onSpeedChange: (speed: number, isHolding: boolean) => void;
+    onSeekPercent?: (percent: number) => void;
+    speedHoldValue?: number;
+    /** Idle timeout in ms (default 5000). Set to 0 to disable. */
+    idleTimeout?: number;
+    /** Callback fired when user becomes idle */
+    onIdle?: () => void;
+    /** Callback fired when user becomes active after being idle */
+    onActive?: () => void;
+}
+export interface InteractionState {
+    isHoldingSpeed: boolean;
+    previousSpeed: number;
+    holdSpeed: number;
+    /** Whether the user is currently idle (no interaction for idleTimeout) */
+    isIdle: boolean;
+}
+export declare class InteractionController {
+    private config;
+    private state;
+    private isAttached;
+    private spaceKeyDownTime;
+    private spaceIsHeld;
+    private holdCheckTimeout;
+    private pointerDownTime;
+    private pointerIsHeld;
+    private pointerHoldTimeout;
+    private lastTapTime;
+    private lastTapX;
+    private pendingTapTimeout;
+    private idleTimeout;
+    private lastInteractionTime;
+    private boundKeyDown;
+    private boundKeyUp;
+    private boundPointerDown;
+    private boundPointerUp;
+    private boundPointerCancel;
+    private boundContextMenu;
+    private boundMouseMove;
+    constructor(config: InteractionControllerConfig);
+    /**
+     * Attach event listeners to container
+     */
+    attach(): void;
+    /**
+     * Detach event listeners and cleanup
+     */
+    detach(): void;
+    /**
+     * Check if currently holding for speed boost
+     */
+    isHoldingSpeed(): boolean;
+    /**
+     * Check if user is currently idle (no interaction for idleTimeout)
+     */
+    isIdle(): boolean;
+    /**
+     * Get current interaction state
+     */
+    getState(): InteractionState;
+    /**
+     * Update config (e.g., when isLive changes)
+     */
+    updateConfig(updates: Partial<InteractionControllerConfig>): void;
+    private handleKeyDown;
+    private handleKeyUp;
+    private handleSpaceDown;
+    private handleSpaceUp;
+    private handlePointerDown;
+    private handlePointerUp;
+    private handlePointerCancel;
+    private cancelPointerHold;
+    private handleContextMenu;
+    private engageSpeedHold;
+    private releaseSpeedHold;
+    private adjustPlaybackSpeed;
+    private handleMouseMove;
+    /**
+     * Record that an interaction occurred and reset idle timer
+     */
+    recordInteraction(): void;
+    /**
+     * Reset the idle timer
+     */
+    private resetIdleTimer;
+    /**
+     * Manually mark as active (e.g., when controls become visible)
+     */
+    markActive(): void;
+    /**
+     * Pause idle tracking (e.g., when controls are visible)
+     */
+    pauseIdleTracking(): void;
+    /**
+     * Resume idle tracking
+     */
+    resumeIdleTracking(): void;
+    private isInputElement;
+    private isControlElement;
+}