@livepeer-frameworks/player-core 0.0.4 → 0.1.1

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

@@ -10,10 +10,10 @@ 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 content type (no longer required for resolution) */
+    contentType?: ContentType;
     /** Optional auth token for private streams */
     authToken?: string;
     /** Maximum retry attempts (default: 3) */
@@ -40,8 +40,7 @@ type CircuitBreakerState = 'closed' | 'open' | 'half-open';
  * ```typescript
  * const client = new GatewayClient({
  *   gatewayUrl: 'https://gateway.example.com/graphql',
- *   contentType: 'live',
- *   contentId: 'my-stream',
+ *   contentId: 'pk_...', // playbackId (view key)
  * });
  *
  * client.on('statusChange', ({ status }) => console.log('Status:', status));

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

@@ -12,6 +12,7 @@ export interface InteractionControllerConfig {
     container: HTMLElement;
     videoElement: HTMLVideoElement;
     isLive: boolean;
+    isPaused?: () => boolean;
     onPlayPause: () => void;
     onSeek: (delta: number) => void;
     onVolumeChange: (delta: number) => void;
@@ -21,7 +22,11 @@ export interface InteractionControllerConfig {
     onLoopToggle?: () => void;
     onSpeedChange: (speed: number, isHolding: boolean) => void;
     onSeekPercent?: (percent: number) => void;
+    /** Optional: player-specific frame stepping (return true if handled) */
+    onFrameStep?: (direction: -1 | 1, seconds: number) => boolean | void;
     speedHoldValue?: number;
+    /** Frame step duration in seconds (for prev/next frame shortcuts) */
+    frameStepSeconds?: number;
     /** Idle timeout in ms (default 5000). Set to 0 to disable. */
     idleTimeout?: number;
     /** Callback fired when user becomes idle */
@@ -58,6 +63,9 @@ export declare class InteractionController {
     private boundPointerCancel;
     private boundContextMenu;
     private boundMouseMove;
+    private boundDoubleClick;
+    private boundDocumentKeyDown;
+    private boundDocumentKeyUp;
     constructor(config: InteractionControllerConfig);
     /**
      * Attach event listeners to container
@@ -85,8 +93,11 @@ export declare class InteractionController {
     updateConfig(updates: Partial<InteractionControllerConfig>): void;
     private handleKeyDown;
     private handleKeyUp;
+    private shouldHandleKeyboard;
     private handleSpaceDown;
     private handleSpaceUp;
+    private handleDoubleClick;
+    private stepFrame;
     private handlePointerDown;
     private handlePointerUp;
     private handlePointerCancel;
@@ -118,4 +129,5 @@ export declare class InteractionController {
     resumeIdleTracking(): void;
     private isInputElement;
     private isControlElement;
+    private getFrameStepSeconds;
 }

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

@@ -40,7 +40,7 @@ type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecti
  * ```ts
  * const manager = new MetaTrackManager({
  *   mistBaseUrl: 'https://mist.example.com',
- *   streamName: 'my-stream',
+ *   streamName: 'pk_...', // playbackId (view key)
  * });
  *
  * manager.subscribe('1', (event) => {

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

@@ -17,7 +17,7 @@ export interface PlayerControllerConfig {
     /** Content identifier (stream name) */
     contentId: string;
     /** Content type */
-    contentType: ContentType;
+    contentType?: ContentType;
     /** Pre-resolved endpoints (skip gateway) */
     endpoints?: ContentEndpoints;
     /** Gateway URL (for FrameWorks Gateway resolution) */
@@ -219,7 +219,7 @@ export declare function buildStreamInfoFromEndpoints(endpoints: ContentEndpoints
  * @example
  * ```typescript
  * const controller = new PlayerController({
- *   contentId: 'my-stream',
+ *   contentId: 'pk_...', // playbackId (view key)
  *   contentType: 'live',
  *   gatewayUrl: 'https://gateway.example.com/graphql',
  * });
@@ -238,6 +238,7 @@ export declare class PlayerController extends TypedEventEmitter<PlayerController
     private config;
     private state;
     private lastEmittedState;
+    private suppressPlayPauseEventsUntil;
     private gatewayClient;
     private streamStateClient;
     private playerManager;
@@ -249,6 +250,10 @@ export declare class PlayerController extends TypedEventEmitter<PlayerController
     private streamState;
     /** Tracks parsed from MistServer JSON response (used for direct MistServer mode) */
     private mistTracks;
+    /** Gateway-seeded metadata (used as base for Mist enrichment) */
+    private metadataSeed;
+    /** Merged metadata (gateway seed + Mist enrichment) */
+    private metadata;
     private cleanupFns;
     private isDestroyed;
     private isAttached;
@@ -319,6 +324,10 @@ export declare class PlayerController extends TypedEventEmitter<PlayerController
     getEndpoints(): ContentEndpoints | null;
     /** Get content metadata (title, description, duration, etc.) */
     getMetadata(): ContentMetadata | null;
+    private setMetadataSeed;
+    private refreshMergedMetadata;
+    private buildMetadataTracks;
+    private sanitizeMistInfo;
     /** Get stream info (sources + tracks for player selection) */
     getStreamInfo(): StreamInfo | null;
     /** Get video element (null if not ready) */
@@ -381,6 +390,8 @@ export declare class PlayerController extends TypedEventEmitter<PlayerController
     hasAudioTrack(): boolean;
     /** Check if playback rate adjustment is supported */
     canAdjustPlaybackRate(): boolean;
+    /** Resolve content type from config override or Gateway metadata */
+    private getResolvedContentType;
     /** Check if source is WebRTC/MediaStream */
     isWebRTCSource(): boolean;
     /** Check if currently in fullscreen mode */
@@ -494,6 +505,7 @@ export declare class PlayerController extends TypedEventEmitter<PlayerController
     private getEffectiveCurrentTime;
     private getEffectiveDuration;
     private getPlayerSeekableRange;
+    private getFrameStepSecondsFromTracks;
     private deriveBufferWindowMsFromTracks;
     /** Get current time */
     getCurrentTime(): number;
@@ -501,6 +513,10 @@ export declare class PlayerController extends TypedEventEmitter<PlayerController
     getDuration(): number;
     /** Check if paused */
     isPaused(): boolean;
+    /** Suppress play/pause-driven UI updates for a short window */
+    suppressPlayPauseEvents(ms?: number): void;
+    /** Check if play/pause UI updates should be suppressed */
+    shouldSuppressVideoEvents(): boolean;
     /** Check if muted */
     isMuted(): boolean;
     /** Skip backward by specified seconds (default 10) */

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

@@ -42,6 +42,8 @@ export interface PlayerOptions {
     height?: number;
     /** Enable dev mode - for Legacy player, uses MistServer's dev skin with source selection */
     devMode?: boolean;
+    /** Enable debug logging in player implementations */
+    debug?: boolean;
     onReady?: (element: HTMLVideoElement) => void;
     onError?: (error: string | Error) => void;
     onPlay?: () => void;
@@ -52,6 +54,12 @@ export interface PlayerOptions {
     onPlaying?: () => void;
     onCanPlay?: () => void;
     onDurationChange?: (duration: number) => void;
+    /** HLS.js configuration override (merged with defaults) */
+    hlsConfig?: Record<string, unknown>;
+    /** DASH.js configuration override (merged with defaults) */
+    dashConfig?: Record<string, unknown>;
+    /** Video.js VHS configuration override (merged with defaults) */
+    vhsConfig?: Record<string, unknown>;
 }
 export interface PlayerCapability {
     /** Player name for display */
@@ -173,6 +181,8 @@ export interface IPlayer {
     getCurrentQuality?(): string | null;
     isLive?(): boolean;
     jumpToLive?(): void;
+    /** Optional: frame step (direction -1/1, optional step seconds) */
+    frameStep?(direction: -1 | 1, seconds?: number): void;
     requestPiP?(): Promise<void>;
     /**
      * Optional: Retrieve player-specific stats (e.g., WebRTC inbound-rtp)

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

@@ -30,6 +30,8 @@ export interface SeekableRangeParams {
     mistStreamInfo?: MistStreamInfo;
     currentTime: number;
     duration: number;
+    /** Allow Mist track metadata for MediaStream sources (e.g., WebCodecs DVR) */
+    allowMediaStreamDvr?: boolean;
 }
 export interface CanSeekParams {
     video: HTMLVideoElement | null;
@@ -87,7 +89,7 @@ export declare function supportsPlaybackRate(video: HTMLVideoElement | null): bo
  * 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)
+ * 4. No fallback (treat as live-only when no reliable data)
  *
  * @param params - Calculation parameters
  * @returns Seekable range with start and live edge

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

@@ -37,7 +37,7 @@ export interface StreamStateClientEvents {
  * ```typescript
  * const client = new StreamStateClient({
  *   mistBaseUrl: 'https://mist.example.com',
- *   streamName: 'my-stream',
+ *   streamName: 'pk_...', // playbackId (view key)
  * });
  *
  * client.on('stateChange', ({ state }) => console.log('State:', state));

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

@@ -29,6 +29,14 @@ export declare class HlsJsPlayerImpl extends BasePlayer {
      * Uses HLS.js liveSyncPosition when available (more accurate)
      */
     jumpToLive(): void;
+    /**
+     * Provide a seekable range override for live streams.
+     * Uses liveSyncPosition as the live edge to avoid waiting for the absolute end.
+     */
+    getSeekableRange(): {
+        start: number;
+        end: number;
+    } | null;
     /**
      * Get latency from live edge (for live streams)
      */

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

@@ -37,7 +37,7 @@ export declare class MewsWsPlayerImpl extends BasePlayer {
     private analyticsTimer;
     isMimeSupported(mimetype: string): boolean;
     isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
-    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions): Promise<HTMLVideoElement>;
+    initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions, streamInfo?: StreamInfo): Promise<HTMLVideoElement>;
     /**
      * Handle MediaSource sourceopen event.
      * Ported from mews.js:143-148, 198-204, 885-902

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

@@ -21,10 +21,6 @@ export declare class VideoJsPlayerImpl extends BasePlayer {
     private getVideoJsType;
     setPlaybackRate(rate: number): void;
     getCurrentTime(): number;
-    getSeekableRange(): {
-        start: number;
-        end: number;
-    } | null;
     /**
      * Seek to time using VideoJS API (fixes backwards seeking in HLS).
      * Time should be in the corrected coordinate space (with firstms offset applied).
@@ -46,11 +42,23 @@ export declare class VideoJsPlayerImpl extends BasePlayer {
      * Check if the stream is live
      */
     isLiveStream(): boolean;
+    /**
+     * Get the calculated duration for live streams
+     */
+    getDuration(): number;
     /**
      * Jump to live edge
      * Uses VideoJS liveTracker when available, otherwise LiveDurationProxy
      */
     jumpToLive(): void;
+    /**
+     * Provide a seekable range override for live streams.
+     * Uses VideoJS liveTracker seekableEnd as the live edge when available.
+     */
+    getSeekableRange(): {
+        start: number;
+        end: number;
+    } | null;
     /**
      * Get latency from live edge (for live streams)
      */

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

@@ -158,7 +158,7 @@ export declare class SyncController {
     /**
      * Register a new track
      */
-    addTrack(trackIndex: number, track: TrackInfo): void;
+    addTrack(_trackIndex: number, _track: TrackInfo): void;
     /**
      * Remove a track
      */

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

@@ -35,6 +35,8 @@ export declare class WebCodecsPlayerImpl extends BasePlayer {
     private debugging;
     private verboseDebugging;
     private streamType;
+    /** Payload format: 'avcc' for ws/video/raw, 'annexb' for ws/video/h264 */
+    private payloadFormat;
     private workerUidCounter;
     private workerListeners;
     private _duration;
@@ -47,6 +49,12 @@ export declare class WebCodecsPlayerImpl extends BasePlayer {
     private _framesDecoded;
     private _bytesReceived;
     private _messagesReceived;
+    private _isPaused;
+    private _suppressPlayPauseSync;
+    private _onVideoPlay?;
+    private _onVideoPause?;
+    private _pendingStepPause;
+    private _stepPauseTimeout;
     private static codecCache;
     /**
      * Get cache key for a track's codec configuration
@@ -95,8 +103,11 @@ export declare class WebCodecsPlayerImpl extends BasePlayer {
     private closePipeline;
     play(): Promise<void>;
     pause(): void;
+    private finishStepPause;
+    frameStep(direction: -1 | 1, _seconds?: number): void;
     seek(time: number): void;
     setPlaybackRate(rate: number): void;
+    isPaused(): boolean;
     isLive(): boolean;
     jumpToLive(): void;
     /**

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

@@ -143,6 +143,8 @@ export interface CreatePipelineMessage {
     track: TrackInfo;
     opts: {
         optimizeForLatency: boolean;
+        /** Payload format: 'avcc' (length-prefixed) or 'annexb' (start-code delimited) */
+        payloadFormat?: 'avcc' | 'annexb';
     };
     uid?: number;
 }
@@ -181,9 +183,10 @@ export interface ClosePipelineMessage {
 }
 export interface FrameTimingMessage {
     type: 'frametiming';
-    action: 'setSpeed' | 'reset';
+    action: 'setSpeed' | 'reset' | 'setPaused';
     speed?: number;
     tweak?: number;
+    paused?: boolean;
     uid?: number;
 }
 export interface SeekWorkerMessage {
@@ -196,7 +199,19 @@ export interface DebuggingMessage {
     value: boolean | 'verbose';
     uid?: number;
 }
-export type MainToWorkerMessage = CreatePipelineMessage | ConfigurePipelineMessage | ReceiveChunkMessage | SetWritableMessage | CreateGeneratorMessage | ClosePipelineMessage | FrameTimingMessage | SeekWorkerMessage | DebuggingMessage;
+export interface FrameStepMessage {
+    type: 'framestep';
+    direction: -1 | 1;
+    uid?: number;
+}
+export interface WriteFrameResponseMessage {
+    type: 'writeframe';
+    idx: number;
+    uid?: number;
+    status: 'ok' | 'error';
+    error?: string;
+}
+export type MainToWorkerMessage = CreatePipelineMessage | ConfigurePipelineMessage | ReceiveChunkMessage | SetWritableMessage | CreateGeneratorMessage | ClosePipelineMessage | FrameTimingMessage | SeekWorkerMessage | DebuggingMessage | FrameStepMessage | WriteFrameResponseMessage;
 export interface AddTrackMessage {
     type: 'addtrack';
     idx: number;
@@ -228,6 +243,7 @@ export interface SendEventMessage {
     type: 'sendevent';
     kind: string;
     message?: string;
+    time?: number;
     idx?: number;
     uid?: number;
 }
@@ -243,7 +259,13 @@ export interface AckMessage {
     status?: 'ok' | 'error';
     error?: string;
 }
-export type WorkerToMainMessage = AddTrackMessage | RemoveTrackMessage | SetPlaybackRateMessage | ClosedMessage | LogMessage | SendEventMessage | StatsMessage | AckMessage;
+export interface WriteFrameMessage {
+    type: 'writeframe';
+    idx: number;
+    frame: AudioData;
+    uid?: number;
+}
+export type WorkerToMainMessage = AddTrackMessage | RemoveTrackMessage | SetPlaybackRateMessage | ClosedMessage | LogMessage | SendEventMessage | StatsMessage | AckMessage | WriteFrameMessage;
 export interface FrameTimingStats {
     /** Timestamp when frame entered decoder (microseconds) */
     in: number;

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

@@ -10,6 +10,8 @@ export interface CreateMessage {
     track: TrackInfo;
     opts: {
         optimizeForLatency: boolean;
+        /** Payload format: 'avcc' (length-prefixed) or 'annexb' (start-code delimited) */
+        payloadFormat?: 'avcc' | 'annexb';
     };
     uid: number;
 }
@@ -48,9 +50,10 @@ export interface CloseMessage {
 }
 export interface FrameTimingMessage {
     type: 'frametiming';
-    action: 'setSpeed' | 'reset';
+    action: 'setSpeed' | 'reset' | 'setPaused';
     speed?: number;
     tweak?: number;
+    paused?: boolean;
     uid: number;
 }
 export interface SeekMessage {
@@ -58,12 +61,17 @@ export interface SeekMessage {
     seekTime: number;
     uid: number;
 }
+export interface FrameStepMessage {
+    type: 'framestep';
+    direction: -1 | 1;
+    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 type MainToWorkerMessage = CreateMessage | ConfigureMessage | ReceiveMessage | SetWritableMessage | CreateGeneratorMessage | CloseMessage | FrameTimingMessage | SeekMessage | FrameStepMessage | DebuggingMessage;
 export interface AddTrackMessage {
     type: 'addtrack';
     idx: number;
@@ -97,6 +105,7 @@ export interface SendEventMessage {
     type: 'sendevent';
     kind: string;
     message?: string;
+    time?: number;
     idx?: number;
     uid: number;
 }
@@ -159,6 +168,13 @@ export interface PipelineState {
         data: Uint8Array;
     }>;
     outputQueue: DecodedFrame[];
+    /** Recent video frames for backward/forward stepping (video only) */
+    frameHistory?: Array<{
+        frame: VideoFrame;
+        timestamp: number;
+    }>;
+    /** Cursor into frameHistory for step navigation */
+    historyCursor?: number | null;
     stats: {
         framesIn: number;
         framesDecoded: number;
@@ -172,6 +188,8 @@ export interface PipelineState {
         lastChunkBytes: string;
     };
     optimizeForLatency: boolean;
+    /** Payload format: 'avcc' (length-prefixed) or 'annexb' (start-code delimited) */
+    payloadFormat: 'avcc' | 'annexb';
 }
 export interface ScheduleResult {
     /** Whether frame should be output now */

package/dist/types/types.d.ts

@@ -50,6 +50,8 @@ export interface PlayerOptions {
     hlsConfig?: HlsJsConfig;
     /** DASH.js configuration override (merged with defaults) */
     dashConfig?: DashJsConfig;
+    /** Video.js VHS configuration override (merged with defaults) */
+    vhsConfig?: VhsConfig;
     /** WebRTC configuration (ICE servers, etc.) */
     rtcConfig?: RTCConfiguration;
     /** String to append to all request URLs (auth tokens, tracking params) */
@@ -98,6 +100,21 @@ export interface DashJsConfig {
     };
     [key: string]: unknown;
 }
+/** Video.js VHS (http-streaming) configuration subset */
+export interface VhsConfig {
+    /** Start with lowest quality for faster initial playback */
+    enableLowInitialPlaylist?: boolean;
+    /** Initial bandwidth estimate in bits per second (e.g., 5_000_000 for 5 Mbps) */
+    bandwidth?: number;
+    /** Persist bandwidth estimate in localStorage across sessions */
+    useBandwidthFromLocalStorage?: boolean;
+    /** Enable partial segment appends for lower latency */
+    handlePartialData?: boolean;
+    /** Time delta for live range safety calculations (seconds) */
+    liveRangeSafeTimeDelta?: number;
+    /** Pass-through for other VHS options */
+    [key: string]: unknown;
+}
 export type StreamProtocol = 'WHEP' | 'HLS' | 'DASH' | 'MP4' | 'WEBM' | 'RTMP' | 'MIST_HTML';
 export interface OutputCapabilities {
     supportsSeek: boolean;
@@ -138,7 +155,7 @@ export interface ContentMetadata {
     durationSeconds?: number;
     thumbnailUrl?: string;
     createdAt?: string;
-    status?: 'AVAILABLE' | 'PROCESSING' | 'ERROR' | 'OFFLINE';
+    status?: 'AVAILABLE' | 'PROCESSING' | 'ERROR' | 'OFFLINE' | 'ONLINE' | 'INITIALIZING' | 'BOOTING' | 'WAITING_FOR_DATA' | 'SHUTTING_DOWN' | 'INVALID';
     viewers?: number;
     isLive?: boolean;
     recordingSizeBytes?: number;
@@ -147,6 +164,19 @@ export interface ContentMetadata {
     dvrStatus?: 'recording' | 'completed';
     /** Native container format: mp4, m3u8, webm, etc. */
     format?: string;
+    /** MistServer authoritative snapshot (merged into this metadata) */
+    mist?: MistStreamInfo;
+    /** Parsed track summary (derived from Mist metadata when available) */
+    tracks?: Array<{
+        type: 'video' | 'audio' | 'meta';
+        codec?: string;
+        width?: number;
+        height?: number;
+        bitrate?: number;
+        fps?: number;
+        channels?: number;
+        sampleRate?: number;
+    }>;
 }
 export interface ContentEndpoints {
     primary: EndpointInfo;
@@ -360,4 +390,5 @@ export interface PlayerMetadata {
         channels?: number;
         sampleRate?: number;
     }>;
+    mist?: MistStreamInfo;
 }

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

@@ -6,11 +6,11 @@
  *
  * @example
  * ```typescript
- * import { FrameWorksPlayer } from '@livepeer-frameworks/player/vanilla';
- * import '@livepeer-frameworks/player/player.css';
+ * import { FrameWorksPlayer } from '@livepeer-frameworks/player-core/vanilla';
+ * import '@livepeer-frameworks/player-core/player.css';
  *
  * const player = new FrameWorksPlayer('#player', {
- *   contentId: 'my-stream',
+ *   contentId: 'pk_...',
  *   contentType: 'live',
  *   gatewayUrl: 'https://gateway.example.com/graphql',
  *   onStateChange: (state) => console.log('State:', state),
@@ -30,7 +30,7 @@ export interface FrameWorksPlayerOptions {
     /** Content identifier (stream name) */
     contentId: string;
     /** Content type */
-    contentType: ContentType;
+    contentType?: ContentType;
     /** Pre-resolved endpoints (skip gateway) */
     endpoints?: ContentEndpoints;
     /** Gateway URL (required if endpoints not provided) */
@@ -57,7 +57,7 @@ export interface FrameWorksPlayerOptions {
 }
 interface LegacyConfig {
     contentId: string;
-    contentType: ContentType;
+    contentType?: ContentType;
     thumbnailUrl?: string | null;
     options?: {
         gatewayUrl?: string;

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

@@ -3,11 +3,11 @@
  *
  * @example
  * ```typescript
- * import { FrameWorksPlayer } from '@livepeer-frameworks/player/vanilla';
- * import '@livepeer-frameworks/player/player.css';
+ * import { FrameWorksPlayer } from '@livepeer-frameworks/player-core/vanilla';
+ * import '@livepeer-frameworks/player-core/player.css';
  *
  * const player = new FrameWorksPlayer('#player', {
- *   contentId: 'my-stream',
+ *   contentId: 'pk_...',
  *   contentType: 'live',
  *   gatewayUrl: 'https://gateway.example.com/graphql',
  * });