@livepeer-frameworks/player-core 0.1.0 → 0.1.2

package/src/core/PlayerRegistry.ts

@@ -1,110 +1,262 @@
 /**
  * Player Registry
  *
- * Central registration of all available player implementations
+ * Lazy registration of player implementations. Capabilities are declared
+ * statically so MIME-based filtering happens without importing any player
+ * modules. Only the players matching the stream's source types are loaded.
  */
 
-import { PlayerManager } from './PlayerManager';
-import type { IPlayer } from './PlayerInterface';
+import { PlayerManager } from "./PlayerManager";
+import type { IPlayer, PlayerCapability } from "./PlayerInterface";
+
+// ============================================================================
+// Lazy Player Entry
+// ============================================================================
+
+interface LazyPlayerEntry {
+  capability: PlayerCapability;
+  load: () => Promise<IPlayer>;
+}
 
 /**
- * Shared registration state per manager instance. Ensures that we only
- * dynamically import and attach transport adapters once per manager.
+ * Static capability registry. Each entry declares its capabilities (MIME types,
+ * priority) and a lazy loader that dynamically imports the implementation.
+ * No player code is loaded until `load()` is called.
  */
-const managerRegistrationPromises = new WeakMap<PlayerManager, Promise<void>>();
+const PLAYER_ENTRIES: LazyPlayerEntry[] = [
+  {
+    capability: {
+      name: "Native Player",
+      shortname: "native",
+      priority: 1,
+      mimes: [
+        "html5/video/mp4",
+        "html5/video/webm",
+        "html5/video/ogg",
+        "html5/audio/mp3",
+        "html5/audio/webm",
+        "html5/audio/ogg",
+        "html5/audio/wav",
+        "html5/application/vnd.apple.mpegurl",
+        "html5/application/vnd.apple.mpegurl;version=7",
+        "whep",
+      ],
+    },
+    load: () => import("../players/NativePlayer").then((m) => new m.NativePlayerImpl()),
+  },
+  {
+    capability: {
+      name: "WebCodecs Player",
+      shortname: "webcodecs",
+      priority: 0,
+      mimes: ["ws/video/raw", "wss/video/raw", "ws/video/h264", "wss/video/h264"],
+    },
+    load: () => import("../players/WebCodecsPlayer").then((m) => new m.WebCodecsPlayerImpl()),
+  },
+  {
+    capability: {
+      name: "MistServer WebRTC",
+      shortname: "mist-webrtc",
+      priority: 2,
+      mimes: ["webrtc", "mist/webrtc"],
+    },
+    load: () => import("../players/MistWebRTCPlayer").then((m) => new m.MistWebRTCPlayerImpl()),
+  },
+  {
+    capability: {
+      name: "Video.js Player",
+      shortname: "videojs",
+      priority: 2,
+      mimes: [
+        "html5/application/vnd.apple.mpegurl",
+        "html5/application/vnd.apple.mpegurl;version=7",
+      ],
+    },
+    load: () => import("../players/VideoJsPlayer").then((m) => new m.VideoJsPlayerImpl()),
+  },
+  {
+    capability: {
+      name: "HLS.js Player",
+      shortname: "hlsjs",
+      priority: 3,
+      mimes: [
+        "html5/application/vnd.apple.mpegurl",
+        "html5/application/vnd.apple.mpegurl;version=7",
+      ],
+    },
+    load: () => import("../players/HlsJsPlayer").then((m) => new m.HlsJsPlayerImpl()),
+  },
+  {
+    capability: {
+      name: "Dash.js Player",
+      shortname: "dashjs",
+      priority: 100,
+      mimes: ["dash/video/mp4"],
+    },
+    load: () => import("../players/DashJsPlayer").then((m) => new m.DashJsPlayerImpl()),
+  },
+  {
+    capability: {
+      name: "Legacy",
+      shortname: "mist-legacy",
+      priority: 99,
+      mimes: ["mist/legacy"],
+    },
+    load: () => import("../players/MistPlayer").then((m) => new m.MistPlayerImpl()),
+  },
+  {
+    capability: {
+      name: "MEWS WebSocket Player",
+      shortname: "mews",
+      priority: 2,
+      mimes: ["ws/video/mp4", "wss/video/mp4", "ws/video/webm", "wss/video/webm"],
+    },
+    load: () => import("../players/MewsWsPlayer").then((m) => new m.MewsWsPlayerImpl()),
+  },
+];
+
+// ============================================================================
+// Loading State
+// ============================================================================
+
+/** Track which players have been loaded per manager */
+const loadedPlayersMap = new WeakMap<PlayerManager, Set<string>>();
 
-async function registerPlayersForManager(manager: PlayerManager): Promise<void> {
-  console.log('[PlayerRegistry] registerPlayersForManager starting...');
-  if (manager.getRegisteredPlayers().length > 0) {
-    console.log('[PlayerRegistry] Players already registered');
-    return;
+function getLoadedSet(manager: PlayerManager): Set<string> {
+  let set = loadedPlayersMap.get(manager);
+  if (!set) {
+    set = new Set();
+    loadedPlayersMap.set(manager, set);
   }
+  return set;
+}
+
+/**
+ * Load only players whose capabilities match the given source MIME types.
+ * Already-loaded players are skipped. Safe to call multiple times with
+ * different MIME types — new players are added incrementally.
+ */
+async function loadMatchingPlayers(manager: PlayerManager, sourceMimes: string[]): Promise<void> {
+  const loaded = getLoadedSet(manager);
+
+  const toLoad = PLAYER_ENTRIES.filter((entry) => {
+    if (loaded.has(entry.capability.shortname)) return false;
+    return entry.capability.mimes.some((m) => sourceMimes.includes(m));
+  });
+
+  if (toLoad.length === 0) return;
 
-  console.log('[PlayerRegistry] Dynamically importing player modules...');
-  const [
-    nativeModule,
-    videoModule,
-    hlsModule,
-    dashModule,
-    mistModule,
-    mewsModule,
-    mistWebRTCModule,
-    webCodecsModule
-  ] = await Promise.all([
-    import('../players/NativePlayer'),
-    import('../players/VideoJsPlayer'),
-    import('../players/HlsJsPlayer'),
-    import('../players/DashJsPlayer'),
-    import('../players/MistPlayer'),
-    import('../players/MewsWsPlayer'),
-    import('../players/MistWebRTCPlayer'),
-    import('../players/WebCodecsPlayer')
-  ]);
-
-  console.log('[PlayerRegistry] All player modules imported, instantiating...');
-  const instantiatedPlayers: IPlayer[] = [
-    new nativeModule.NativePlayerImpl(),
-    new webCodecsModule.WebCodecsPlayerImpl(), // Priority 1 - lowest latency
-    new mistWebRTCModule.MistWebRTCPlayerImpl(), // Priority 2
-    new videoModule.VideoJsPlayerImpl(),
-    new hlsModule.HlsJsPlayerImpl(),
-    new dashModule.DashJsPlayerImpl(),
-    new mistModule.MistPlayerImpl(),
-    new mewsModule.MewsWsPlayerImpl()
-  ];
-
-  for (const player of instantiatedPlayers) {
+  const players = await Promise.all(toLoad.map((e) => e.load()));
+  for (const player of players) {
+    loaded.add(player.capability.shortname);
     const alreadyRegistered = manager
       .getRegisteredPlayers()
-      .some(existing => existing.capability.shortname === player.capability.shortname);
-
+      .some((p) => p.capability.shortname === player.capability.shortname);
     if (!alreadyRegistered) {
       manager.registerPlayer(player);
     }
   }
-  console.log(`[PlayerRegistry] Registration complete. ${manager.getRegisteredPlayers().length} players registered.`);
 }
 
-export function ensurePlayersRegistered(manager: PlayerManager = globalPlayerManager): Promise<void> {
-  console.log('[PlayerRegistry] ensurePlayersRegistered called');
-  if (manager.getRegisteredPlayers().length > 0) {
-    console.log('[PlayerRegistry] Already registered, returning');
-    return Promise.resolve();
+/**
+ * Load a specific player by shortname. Used for forcePlayer support.
+ */
+async function loadPlayerByShortname(manager: PlayerManager, shortname: string): Promise<void> {
+  const loaded = getLoadedSet(manager);
+  if (loaded.has(shortname)) return;
+
+  const entry = PLAYER_ENTRIES.find((e) => e.capability.shortname === shortname);
+  if (!entry) return;
+
+  const player = await entry.load();
+  loaded.add(player.capability.shortname);
+  const alreadyRegistered = manager
+    .getRegisteredPlayers()
+    .some((p) => p.capability.shortname === player.capability.shortname);
+  if (!alreadyRegistered) {
+    manager.registerPlayer(player);
   }
+}
+
+/**
+ * Load all players. Used for backwards compatibility (createPlayerManager,
+ * registerAllPlayers) and when no MIME filter is available.
+ */
+async function loadAllPlayers(manager: PlayerManager): Promise<void> {
+  const allMimes = PLAYER_ENTRIES.flatMap((e) => e.capability.mimes);
+  return loadMatchingPlayers(manager, allMimes);
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/** Deduplication promises for full registration (loadAllPlayers) */
+const fullRegistrationPromises = new WeakMap<PlayerManager, Promise<void>>();
 
-  const existing = managerRegistrationPromises.get(manager);
-  if (existing) {
-    console.log('[PlayerRegistry] Using existing registration promise');
-    return existing;
+/**
+ * Ensure all players are registered. Backwards-compatible API that loads
+ * every player module. Prefer the MIME-filtered path via initializePlayer.
+ */
+export function ensurePlayersRegistered(
+  manager: PlayerManager = globalPlayerManager
+): Promise<void> {
+  const loaded = getLoadedSet(manager);
+  if (loaded.size === PLAYER_ENTRIES.length) {
+    return Promise.resolve();
   }
 
-  console.log('[PlayerRegistry] Starting new registration...');
-  const registrationPromise = registerPlayersForManager(manager).catch(error => {
-    console.error('[PlayerRegistry] Registration failed:', error);
-    managerRegistrationPromises.delete(manager);
+  const existing = fullRegistrationPromises.get(manager);
+  if (existing) return existing;
+
+  const promise = loadAllPlayers(manager).catch((error) => {
+    console.error("[PlayerRegistry] Registration failed:", error);
+    fullRegistrationPromises.delete(manager);
     throw error;
   });
 
-  managerRegistrationPromises.set(manager, registrationPromise);
-  return registrationPromise;
+  fullRegistrationPromises.set(manager, promise);
+  return promise;
 }
 
+/**
+ * Monkey-patch initializePlayer to lazily load only matching players.
+ * Extracts source MIME types from streamInfo and loads the subset of
+ * player modules that can handle those types.
+ */
 const originalInitialize = PlayerManager.prototype.initializePlayer;
-PlayerManager.prototype.initializePlayer = async function (...args: Parameters<PlayerManager['initializePlayer']>) {
-  console.log('[PlayerRegistry] initializePlayer wrapper - calling ensurePlayersRegistered...');
-  await ensurePlayersRegistered(this);
-  console.log('[PlayerRegistry] ensurePlayersRegistered done, calling original initializePlayer...');
+PlayerManager.prototype.initializePlayer = async function (
+  ...args: Parameters<PlayerManager["initializePlayer"]>
+) {
+  const [_container, streamInfo, _playerOptions, managerOptions] = args;
+  const sourceMimes = streamInfo?.source?.map((s) => s.type) ?? [];
+
+  if (sourceMimes.length > 0) {
+    // Load only players matching the stream's source types
+    await loadMatchingPlayers(this, sourceMimes);
+
+    // Also load a forced player if specified
+    if (managerOptions?.forcePlayer) {
+      await loadPlayerByShortname(this, managerOptions.forcePlayer);
+    }
+  } else {
+    // No source info — fall back to loading all
+    await ensurePlayersRegistered(this);
+  }
+
   return originalInitialize.apply(this, args);
 };
 
-/**
- * Global PlayerManager instance with deferred registration
- */
+// ============================================================================
+// Global Instance
+// ============================================================================
+
 const isDev = (() => {
   try {
-    // In browser builds, process may be undefined; guard access
-    // @ts-ignore
-    return typeof process !== 'undefined' && process && process.env && process.env.NODE_ENV === 'development';
+    const g = globalThis as Record<string, unknown>;
+    const p = g.process as Record<string, unknown> | undefined;
+    const env = p?.env as Record<string, unknown> | undefined;
+    return env?.NODE_ENV === "development";
   } catch {
     return false;
   }
@@ -113,37 +265,36 @@ const isDev = (() => {
 export const globalPlayerManager = new PlayerManager({
   debug: isDev,
   autoFallback: true,
-  maxFallbackAttempts: 3
+  maxFallbackAttempts: 3,
 });
 
 /**
  * Register all available players (async for backwards compatibility)
  */
-export async function registerAllPlayers(manager: PlayerManager = globalPlayerManager): Promise<void> {
+export async function registerAllPlayers(
+  manager: PlayerManager = globalPlayerManager
+): Promise<void> {
   await ensurePlayersRegistered(manager);
 }
 
 /**
  * Create a new PlayerManager instance with all players registered
  */
-export function createPlayerManager(options?: ConstructorParameters<typeof PlayerManager>[0]): PlayerManager {
+export function createPlayerManager(
+  options?: ConstructorParameters<typeof PlayerManager>[0]
+): PlayerManager {
   const manager = new PlayerManager(options);
-  ensurePlayersRegistered(manager).catch(error => {
+  ensurePlayersRegistered(manager).catch((error) => {
     if (isDev) {
-      console.warn('Player registration failed:', error);
+      console.warn("Player registration failed:", error);
     }
   });
   return manager;
 }
 
 /**
- * Export individual player classes for direct use
+ * Get the static capability registry (for UI display without loading modules)
  */
-export { NativePlayerImpl, DirectPlaybackPlayerImpl } from '../players/NativePlayer';
-export { HlsJsPlayerImpl } from '../players/HlsJsPlayer';
-export { DashJsPlayerImpl } from '../players/DashJsPlayer';
-export { VideoJsPlayerImpl } from '../players/VideoJsPlayer';
-export { MistPlayerImpl } from '../players/MistPlayer';
-export { MewsWsPlayerImpl } from '../players/MewsWsPlayer';
-export { MistWebRTCPlayerImpl } from '../players/MistWebRTCPlayer';
-export { WebCodecsPlayerImpl } from '../players/WebCodecsPlayer';
+export function getAvailablePlayerCapabilities(): PlayerCapability[] {
+  return PLAYER_ENTRIES.map((e) => e.capability);
+}

package/src/core/QualityMonitor.ts

@@ -1,5 +1,5 @@
-import type { PlaybackQuality, QualityThresholds } from '../types';
-import { TimerManager } from './TimerManager';
+import type { PlaybackQuality, QualityThresholds } from "../types";
+import { TimerManager } from "./TimerManager";
 
 /**
  * Default quality thresholds
@@ -19,21 +19,21 @@ const ROLLING_WINDOW_SIZE = 20;
  * Playback score history entry (for MistPlayer-style 0-2.0 score)
  */
 interface PlaybackScoreEntry {
-  clock: number;  // Wall clock time in seconds
-  video: number;  // Video currentTime
-  score: number;  // Calculated score for this sample
+  clock: number; // Wall clock time in seconds
+  video: number; // Video currentTime
+  score: number; // Calculated score for this sample
 }
 
 /** Protocol type for threshold selection */
-export type PlayerProtocol = 'webrtc' | 'hls' | 'dash' | 'html5' | 'unknown';
+export type PlayerProtocol = "webrtc" | "hls" | "dash" | "html5" | "unknown";
 
 /** Protocol-specific playback score thresholds (MistMetaPlayer reference) */
 export const PROTOCOL_THRESHOLDS: Record<PlayerProtocol, number> = {
-  webrtc: 0.95,   // Very strict for low-latency
-  hls: 0.75,      // More lenient for adaptive streaming
-  dash: 0.75,     // More lenient for adaptive streaming
-  html5: 0.75,    // Standard threshold
-  unknown: 0.75,  // Default
+  webrtc: 0.95, // Very strict for low-latency
+  hls: 0.75, // More lenient for adaptive streaming
+  dash: 0.75, // More lenient for adaptive streaming
+  html5: 0.75, // Standard threshold
+  unknown: 0.75, // Default
 };
 
 export interface QualityMonitorOptions {
@@ -82,7 +82,7 @@ export interface QualityMonitorState {
  */
 export class QualityMonitor {
   private videoElement: HTMLVideoElement | null = null;
-  private options: Required<Omit<QualityMonitorOptions, 'protocol' | 'playbackScoreThreshold'>> & {
+  private options: Required<Omit<QualityMonitorOptions, "protocol" | "playbackScoreThreshold">> & {
     protocol: PlayerProtocol;
     playbackScoreThreshold: number | null;
   };
@@ -112,7 +112,7 @@ export class QualityMonitor {
       thresholds: options.thresholds ?? {},
       onQualityDegraded: options.onQualityDegraded ?? (() => {}),
       onSample: options.onSample ?? (() => {}),
-      protocol: options.protocol ?? 'unknown',
+      protocol: options.protocol ?? "unknown",
       playbackScoreThreshold: options.playbackScoreThreshold ?? null,
       onFallbackRequest: options.onFallbackRequest ?? (() => {}),
       poorSamplesBeforeFallback: options.poorSamplesBeforeFallback ?? 5,
@@ -190,18 +190,18 @@ export class QualityMonitor {
       }
     };
 
-    videoElement.addEventListener('waiting', onWaiting);
-    videoElement.addEventListener('playing', onPlaying);
-    videoElement.addEventListener('canplay', onCanPlay);
+    videoElement.addEventListener("waiting", onWaiting);
+    videoElement.addEventListener("playing", onPlaying);
+    videoElement.addEventListener("canplay", onCanPlay);
 
     this.listeners = [
-      () => videoElement.removeEventListener('waiting', onWaiting),
-      () => videoElement.removeEventListener('playing', onPlaying),
-      () => videoElement.removeEventListener('canplay', onCanPlay),
+      () => videoElement.removeEventListener("waiting", onWaiting),
+      () => videoElement.removeEventListener("playing", onPlaying),
+      () => videoElement.removeEventListener("canplay", onCanPlay),
     ];
 
     // Start sampling interval
-    this.timers.startInterval(() => this.sample(), this.options.sampleInterval, 'sampling');
+    this.timers.startInterval(() => this.sample(), this.options.sampleInterval, "sampling");
 
     // Take initial sample
     this.sample();
@@ -213,7 +213,7 @@ export class QualityMonitor {
   stop(): void {
     this.timers.destroy();
 
-    this.listeners.forEach(cleanup => cleanup());
+    this.listeners.forEach((cleanup) => cleanup());
     this.listeners = [];
 
     this.videoElement = null;
@@ -241,9 +241,11 @@ export class QualityMonitor {
     this.options.onSample(quality);
 
     // Check for quality degradation
-    if (quality.score < this.thresholds.minScore ||
-        quality.stallCount > this.thresholds.maxStalls ||
-        quality.bufferedAhead < this.thresholds.minBuffer) {
+    if (
+      quality.score < this.thresholds.minScore ||
+      quality.stallCount > this.thresholds.maxStalls ||
+      quality.bufferedAhead < this.thresholds.minBuffer
+    ) {
       this.options.onQualityDegraded(quality);
     }
 
@@ -254,13 +256,15 @@ export class QualityMonitor {
 
       // Trigger fallback after sustained poor quality
       // Only trigger once until quality improves or reset
-      if (!this.fallbackTriggered &&
-          this.consecutivePoorSamples >= this.options.poorSamplesBeforeFallback) {
+      if (
+        !this.fallbackTriggered &&
+        this.consecutivePoorSamples >= this.options.poorSamplesBeforeFallback
+      ) {
         this.fallbackTriggered = true;
         console.warn(
           `[QualityMonitor] Poor playback detected: ${Math.round(this.playbackScore * 100)}% ` +
-          `(threshold: ${Math.round(this.getPlaybackScoreThreshold() * 100)}%, ` +
-          `protocol: ${this.options.protocol})`
+            `(threshold: ${Math.round(this.getPlaybackScoreThreshold() * 100)}%, ` +
+            `protocol: ${this.options.protocol})`
         );
         this.options.onFallbackRequest({
           score: this.playbackScore,
@@ -284,7 +288,10 @@ export class QualityMonitor {
     let bufferedAhead = 0;
     if (video.buffered.length > 0) {
       for (let i = 0; i < video.buffered.length; i++) {
-        if (video.buffered.start(i) <= video.currentTime && video.buffered.end(i) > video.currentTime) {
+        if (
+          video.buffered.start(i) <= video.currentTime &&
+          video.buffered.end(i) > video.currentTime
+        ) {
           bufferedAhead = video.buffered.end(i) - video.currentTime;
           break;
         }
@@ -296,7 +303,7 @@ export class QualityMonitor {
     let framesDropped = 0;
     let frameDropRate = 0;
 
-    if ('getVideoPlaybackQuality' in video) {
+    if ("getVideoPlaybackQuality" in video) {
       const stats = video.getVideoPlaybackQuality();
       framesDecoded = stats.totalVideoFrames;
       framesDropped = stats.droppedVideoFrames;
@@ -505,7 +512,7 @@ export class QualityMonitor {
 
     if (clockDelta <= 0) return 1.0;
 
-    return (videoDelta / clockDelta) / rate;
+    return videoDelta / clockDelta / rate;
   }
 
   /**

package/src/core/ScreenWakeLockManager.ts

@@ -32,13 +32,13 @@ export class ScreenWakeLockManager {
 
   constructor(config: ScreenWakeLockConfig = {}) {
     this.config = config;
-    this.isSupported = 'wakeLock' in navigator;
+    this.isSupported = "wakeLock" in navigator;
 
     this.boundVisibilityChange = this.handleVisibilityChange.bind(this);
 
     // Re-acquire wake lock when page becomes visible again
     if (this.isSupported) {
-      document.addEventListener('visibilitychange', this.boundVisibilityChange);
+      document.addEventListener("visibilitychange", this.boundVisibilityChange);
     }
   }
 
@@ -46,7 +46,7 @@ export class ScreenWakeLockManager {
    * Check if Screen Wake Lock API is supported
    */
   static isSupported(): boolean {
-    return 'wakeLock' in navigator;
+    return "wakeLock" in navigator;
   }
 
   /**
@@ -85,8 +85,8 @@ export class ScreenWakeLockManager {
     if (this.wakeLock) return;
 
     try {
-      this.wakeLock = await navigator.wakeLock.request('screen');
-      this.wakeLock.addEventListener('release', this.handleRelease.bind(this));
+      this.wakeLock = await navigator.wakeLock.request("screen");
+      this.wakeLock.addEventListener("release", this.handleRelease.bind(this));
       this.config.onAcquire?.();
     } catch (err) {
       // Wake lock request can fail if:
@@ -119,7 +119,7 @@ export class ScreenWakeLockManager {
     this.release();
 
     if (this.isSupported) {
-      document.removeEventListener('visibilitychange', this.boundVisibilityChange);
+      document.removeEventListener("visibilitychange", this.boundVisibilityChange);
     }
   }
 
@@ -127,8 +127,7 @@ export class ScreenWakeLockManager {
    * Update wake lock based on current state
    */
   private updateWakeLock(): void {
-    const shouldHold =
-      this.isPlaying && (this.isFullscreen || this.config.acquireOnPlay);
+    const shouldHold = this.isPlaying && (this.isFullscreen || this.config.acquireOnPlay);
 
     if (shouldHold && !this.wakeLock) {
       this.acquire();
@@ -154,7 +153,7 @@ export class ScreenWakeLockManager {
    * Handle visibility change - re-acquire if page becomes visible
    */
   private handleVisibilityChange(): void {
-    if (document.visibilityState === 'visible' && !this.wakeLock) {
+    if (document.visibilityState === "visible" && !this.wakeLock) {
       this.updateWakeLock();
     }
   }