@livepeer-frameworks/player-core 0.0.4 → 0.1.1

package/src/core/PlayerInterface.ts

@@ -1,6 +1,6 @@
 /**
  * Common Player Interface
- * 
+ *
  * All player implementations must implement this interface to ensure
  * consistent behavior and enable the PlayerManager selection system
  */
@@ -14,7 +14,7 @@ export interface StreamSource {
 }
 
 export interface StreamTrack {
-  type: 'video' | 'audio' | 'meta';
+  type: "video" | "audio" | "meta";
   codec: string;
   codecstring?: string;
   init?: string;
@@ -35,7 +35,7 @@ export interface StreamInfo {
   meta: {
     tracks: StreamTrack[];
   };
-  type?: 'live' | 'vod';
+  type?: "live" | "vod";
 }
 
 export interface PlayerOptions {
@@ -61,6 +61,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 {
@@ -93,26 +99,26 @@ export interface PlayerEvents {
 export interface IPlayer {
   /** Player metadata */
   readonly capability: PlayerCapability;
-  
+
   /**
    * Check if this player supports the given MIME type
    */
   isMimeSupported(mimetype: string): boolean;
-  
+
   /**
    * Check if this player can play in the current browser environment
    * @param mimetype - MIME type to test
    * @param source - Source information
    * @param streamInfo - Stream metadata
-   * @returns false if not supported, true if supported (no track info), 
+   * @returns false if not supported, true if supported (no track info),
    *          or array of supported track types
    */
   isBrowserSupported(
-    mimetype: string, 
-    source: StreamSource, 
+    mimetype: string,
+    source: StreamSource,
     streamInfo: StreamInfo
   ): boolean | string[];
-  
+
   /**
    * Initialize the player with given source and options
    * @param container - Container element to render in
@@ -127,33 +133,33 @@ export interface IPlayer {
     options: PlayerOptions,
     streamInfo?: StreamInfo
   ): Promise<HTMLVideoElement>;
-  
+
   /**
    * Clean up and destroy the player.
    * May be async if cleanup requires network requests (e.g., WHEP session DELETE).
    */
   destroy(): void | Promise<void>;
-  
+
   /**
    * Get the underlying video element (if available)
    */
   getVideoElement(): HTMLVideoElement | null;
-  
+
   /**
    * Set video size
    */
   setSize?(width: number, height: number): void;
-  
+
   /**
    * Add event listener
    */
   on<K extends keyof PlayerEvents>(event: K, listener: (data: PlayerEvents[K]) => void): void;
-  
+
   /**
    * Remove event listener
    */
   off<K extends keyof PlayerEvents>(event: K, listener: (data: PlayerEvents[K]) => void): void;
-  
+
   /**
    * Get current playback state
    */
@@ -165,7 +171,7 @@ export interface IPlayer {
   getSeekableRange?(): { start: number; end: number } | null;
   /** Optional: provide buffered ranges override */
   getBufferedRanges?(): TimeRanges | null;
-  
+
   /**
    * Control playback
    */
@@ -181,7 +187,15 @@ export interface IPlayer {
   selectTextTrack?(id: string | null): void;
 
   // Optional: quality/level selection
-  getQualities?(): Array<{ id: string; label: string; bitrate?: number; width?: number; height?: number; isAuto?: boolean; active?: boolean }>;
+  getQualities?(): Array<{
+    id: string;
+    label: string;
+    bitrate?: number;
+    width?: number;
+    height?: number;
+    isAuto?: boolean;
+    active?: boolean;
+  }>;
   selectQuality?(id: string): void; // use 'auto' to enable ABR
   getCurrentQuality?(): string | null;
 
@@ -210,37 +224,46 @@ export interface IPlayer {
  */
 export abstract class BasePlayer implements IPlayer {
   abstract readonly capability: PlayerCapability;
-  
+
   protected listeners: Map<string, Set<Function>> = new Map();
   protected videoElement: HTMLVideoElement | null = null;
-  
+
   abstract isMimeSupported(mimetype: string): boolean;
-  abstract isBrowserSupported(mimetype: string, source: StreamSource, streamInfo: StreamInfo): boolean | string[];
-  abstract initialize(container: HTMLElement, source: StreamSource, options: PlayerOptions, streamInfo?: StreamInfo): Promise<HTMLVideoElement>;
+  abstract isBrowserSupported(
+    mimetype: string,
+    source: StreamSource,
+    streamInfo: StreamInfo
+  ): boolean | string[];
+  abstract initialize(
+    container: HTMLElement,
+    source: StreamSource,
+    options: PlayerOptions,
+    streamInfo?: StreamInfo
+  ): Promise<HTMLVideoElement>;
   abstract destroy(): void | Promise<void>;
-  
+
   getVideoElement(): HTMLVideoElement | null {
     return this.videoElement;
   }
-  
+
   on<K extends keyof PlayerEvents>(event: K, listener: (data: PlayerEvents[K]) => void): void {
     if (!this.listeners.has(event)) {
       this.listeners.set(event, new Set());
     }
     this.listeners.get(event)!.add(listener);
   }
-  
+
   off<K extends keyof PlayerEvents>(event: K, listener: (data: PlayerEvents[K]) => void): void {
     const eventListeners = this.listeners.get(event);
     if (eventListeners) {
       eventListeners.delete(listener);
     }
   }
-  
+
   protected emit<K extends keyof PlayerEvents>(event: K, data: PlayerEvents[K]): void {
     const eventListeners = this.listeners.get(event);
     if (eventListeners) {
-      eventListeners.forEach(listener => {
+      eventListeners.forEach((listener) => {
         try {
           listener(data);
         } catch (e) {
@@ -249,7 +272,7 @@ export abstract class BasePlayer implements IPlayer {
       });
     }
   }
-  
+
   protected setupVideoEventListeners(video: HTMLVideoElement, options: PlayerOptions): void {
     const handleEvent = (eventName: keyof PlayerEvents, handler: () => void) => {
       const listener = () => {
@@ -260,46 +283,44 @@ export abstract class BasePlayer implements IPlayer {
     };
 
     // Core playback events
-    handleEvent('play', () => options.onPlay?.());
-    handleEvent('pause', () => options.onPause?.());
-    handleEvent('ended', () => options.onEnded?.());
+    handleEvent("play", () => options.onPlay?.());
+    handleEvent("pause", () => options.onPause?.());
+    handleEvent("ended", () => options.onEnded?.());
 
     // Buffering/state events (previously duplicated in Player.tsx onReady)
-    video.addEventListener('waiting', () => options.onWaiting?.());
-    video.addEventListener('playing', () => options.onPlaying?.());
-    video.addEventListener('canplay', () => options.onCanPlay?.());
+    video.addEventListener("waiting", () => options.onWaiting?.());
+    video.addEventListener("playing", () => options.onPlaying?.());
+    video.addEventListener("canplay", () => options.onCanPlay?.());
 
-    video.addEventListener('durationchange', () => {
+    video.addEventListener("durationchange", () => {
       options.onDurationChange?.(video.duration);
     });
 
-    video.addEventListener('timeupdate', () => {
+    video.addEventListener("timeupdate", () => {
       const currentTime = video.currentTime;
       options.onTimeUpdate?.(currentTime);
-      this.emit('timeupdate', currentTime);
+      this.emit("timeupdate", currentTime);
     });
 
-    video.addEventListener('error', () => {
-      const error = video.error ?
-        `Video error: ${video.error.message}` :
-        'Unknown video error';
+    video.addEventListener("error", () => {
+      const error = video.error ? `Video error: ${video.error.message}` : "Unknown video error";
       options.onError?.(error);
-      this.emit('error', error);
+      this.emit("error", error);
     });
 
     // Call onReady LAST - after all listeners are attached
     // This prevents race conditions where events fire before handlers exist
-    this.emit('ready', video);
+    this.emit("ready", video);
     if (options.onReady) {
       options.onReady(video);
     }
   }
-  
+
   // Default implementations for optional methods
   getCurrentTime(): number {
     return this.videoElement?.currentTime || 0;
   }
-  
+
   getDuration(): number {
     return this.videoElement?.duration || 0;
   }
@@ -311,37 +332,37 @@ export abstract class BasePlayer implements IPlayer {
   getBufferedRanges(): TimeRanges | null {
     return this.videoElement?.buffered ?? null;
   }
-  
+
   isPaused(): boolean {
     return this.videoElement?.paused ?? true;
   }
-  
+
   isMuted(): boolean {
     return this.videoElement?.muted ?? false;
   }
-  
+
   async play(): Promise<void> {
     if (this.videoElement) {
       return this.videoElement.play();
     }
   }
-  
+
   pause(): void {
     this.videoElement?.pause();
   }
-  
+
   seek(time: number): void {
     if (this.videoElement) {
       this.videoElement.currentTime = time;
     }
   }
-  
+
   setVolume(volume: number): void {
     if (this.videoElement) {
       this.videoElement.volume = Math.max(0, Math.min(1, volume));
     }
   }
-  
+
   setMuted(muted: boolean): void {
     if (this.videoElement) {
       this.videoElement.muted = muted;
@@ -352,7 +373,7 @@ export abstract class BasePlayer implements IPlayer {
       this.videoElement.playbackRate = rate;
     }
   }
-  
+
   // Default captions/text tracks using native TextTrack API
   getTextTracks(): Array<{ id: string; label: string; lang?: string; active: boolean }> {
     const video = this.videoElement;
@@ -361,7 +382,12 @@ export abstract class BasePlayer implements IPlayer {
     const list = video.textTracks as any as TextTrackList;
     for (let i = 0; i < list.length; i++) {
       const tt = list[i];
-      out.push({ id: String(i), label: tt.label || `CC ${i+1}`, lang: (tt as any).language, active: tt.mode === 'showing' });
+      out.push({
+        id: String(i),
+        label: tt.label || `CC ${i + 1}`,
+        lang: (tt as any).language,
+        active: tt.mode === "showing",
+      });
     }
     return out;
   }
@@ -373,9 +399,9 @@ export abstract class BasePlayer implements IPlayer {
     for (let i = 0; i < list.length; i++) {
       const tt = list[i];
       if (id !== null && String(i) === id) {
-        tt.mode = 'showing';
+        tt.mode = "showing";
       } else {
-        tt.mode = 'disabled';
+        tt.mode = "disabled";
       }
     }
   }
@@ -392,7 +418,9 @@ export abstract class BasePlayer implements IPlayer {
     if (!v) return;
     const seekable = v.seekable;
     if (seekable && seekable.length > 0) {
-      try { v.currentTime = seekable.end(seekable.length - 1); } catch {}
+      try {
+        v.currentTime = seekable.end(seekable.length - 1);
+      } catch {}
     }
   }
 
@@ -402,18 +430,20 @@ export abstract class BasePlayer implements IPlayer {
     if (!v) return;
     // Exit if already in PiP
     if (document.pictureInPictureElement === v) {
-      try { await (document as any).exitPictureInPicture?.(); } catch {}
+      try {
+        await (document as any).exitPictureInPicture?.();
+      } catch {}
       return;
     }
     try {
       if (v.requestPictureInPicture) {
         await v.requestPictureInPicture();
       } else if (v.webkitSetPresentationMode) {
-        v.webkitSetPresentationMode('picture-in-picture');
+        v.webkitSetPresentationMode("picture-in-picture");
       }
     } catch {}
   }
-  
+
   setSize(width: number, height: number): void {
     if (this.videoElement) {
       this.videoElement.style.width = `${width}px`;