@livepeer-frameworks/player-core 0.0.3

package/src/core/CodecUtils.ts

@@ -0,0 +1,257 @@
+/**
+ * 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; // 'video' | 'audio' | 'meta' - loosened for compatibility
+  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 function translateCodec(track: TrackInfo): string {
+  const codec = track.codec.toUpperCase();
+
+  // Use codecstring if available (MistServer provides this for some tracks)
+  if (track.codecstring) {
+    return track.codecstring;
+  }
+
+  // Audio codecs
+  if (track.type === 'audio') {
+    switch (codec) {
+      case 'AAC':
+      case 'MP4A':
+        return 'mp4a.40.2'; // AAC-LC
+      case 'MP3':
+        return 'mp4a.40.34'; // MP3 in MP4 container
+      case 'AC3':
+      case 'AC-3':
+        return 'ac-3';
+      case 'EAC3':
+      case 'EC3':
+      case 'E-AC3':
+      case 'EC-3':
+        return 'ec-3';
+      case 'OPUS':
+        return 'opus';
+      case 'VORBIS':
+        return 'vorbis';
+      case 'FLAC':
+        return 'flac';
+      case 'PCM':
+      case 'PCMS16LE':
+        return 'pcm';
+      default:
+        return codec.toLowerCase();
+    }
+  }
+
+  // Video codecs
+  if (track.type === 'video') {
+    switch (codec) {
+      case 'H264':
+      case 'AVC':
+      case 'AVC1': {
+        // Try to extract profile/level from init data
+        const profileLevel = extractH264Profile(track.init);
+        return profileLevel || 'avc1.42E01E'; // Default: Baseline Profile, Level 3.0
+      }
+      case 'H265':
+      case 'HEVC':
+      case 'HEV1':
+      case 'HVC1': {
+        // Try to extract profile/level from init data
+        const profileLevel = extractHEVCProfile(track.init);
+        return profileLevel || 'hev1.1.6.L93.B0'; // Default: Main Profile, Level 3.1
+      }
+      case 'VP8':
+        return 'vp8';
+      case 'VP9':
+        return 'vp09.00.10.08'; // Profile 0, Level 1.0, 8-bit
+      case 'AV1':
+        return 'av01.0.01M.08'; // Main Profile, Level 2.1, 8-bit
+      case 'THEORA':
+        return 'theora';
+      default:
+        return codec.toLowerCase();
+    }
+  }
+
+  return codec.toLowerCase();
+}
+
+/**
+ * Extract H264 profile and level from init data (SPS)
+ * The init data contains the SPS NAL unit which has profile/level info
+ *
+ * @param init - Base64 encoded init data from MistServer
+ * @returns Codec string like "avc1.64001f" or null
+ */
+function extractH264Profile(init?: string): string | null {
+  if (!init) return null;
+
+  try {
+    // Decode base64 init data
+    const bytes = base64ToBytes(init);
+
+    // Look for SPS NAL unit (starts with 0x67 for H264)
+    // Format: NAL type (1 byte) + profile_idc (1 byte) + constraint flags (1 byte) + level_idc (1 byte)
+    for (let i = 0; i < bytes.length - 4; i++) {
+      // Check for NAL start code (0x00 0x00 0x01 or 0x00 0x00 0x00 0x01)
+      if (bytes[i] === 0x00 && bytes[i + 1] === 0x00) {
+        let offset = i + 2;
+        if (bytes[offset] === 0x00) offset++;
+        if (bytes[offset] === 0x01) offset++;
+
+        // Check if this is SPS (NAL type 7)
+        const nalType = bytes[offset] & 0x1f;
+        if (nalType === 7 && offset + 3 < bytes.length) {
+          const profileIdc = bytes[offset + 1];
+          const constraintFlags = bytes[offset + 2];
+          const levelIdc = bytes[offset + 3];
+
+          return `avc1.${toHex(profileIdc)}${toHex(constraintFlags)}${toHex(levelIdc)}`;
+        }
+      }
+    }
+
+    // If no NAL start code found, try raw format
+    if (bytes.length >= 4) {
+      // Assume first bytes are profile/constraint/level
+      const profileIdc = bytes[0];
+      const constraintFlags = bytes[1];
+      const levelIdc = bytes[2];
+
+      // Validate reasonable values
+      if (profileIdc > 0 && profileIdc < 255 && levelIdc > 0 && levelIdc < 100) {
+        return `avc1.${toHex(profileIdc)}${toHex(constraintFlags)}${toHex(levelIdc)}`;
+      }
+    }
+  } catch {
+    // Ignore parsing errors
+  }
+
+  return null;
+}
+
+/**
+ * Extract HEVC profile and level from init data (VPS/SPS)
+ *
+ * @param init - Base64 encoded init data from MistServer
+ * @returns Codec string like "hev1.1.6.L93.B0" or null
+ */
+function extractHEVCProfile(init?: string): string | null {
+  if (!init) return null;
+
+  try {
+    // Decode base64 init data
+    const bytes = base64ToBytes(init);
+
+    // HEVC profile/level extraction is more complex
+    // For now, return a sensible default based on data presence
+    if (bytes.length > 0) {
+      // Look for profile_tier_level in VPS/SPS
+      // This is a simplified extraction - full parsing would be more complex
+      for (let i = 0; i < bytes.length - 3; i++) {
+        // Look for general_profile_idc (usually in first few bytes after NAL header)
+        const profileIdc = bytes[i];
+        if (profileIdc >= 1 && profileIdc <= 5) {
+          // Valid profile IDC (1=Main, 2=Main10, 3=MainStill, 4=Range Extensions, 5=High Throughput)
+          const tierFlag = 0; // Assume main tier
+          const levelIdc = bytes[i + 1] || 93; // Default to level 3.1
+
+          // Format: hev1.{profile}.{tier_flag}{compatibility}.L{level}.{constraints}
+          return `hev1.${profileIdc}.6.L${levelIdc}.B0`;
+        }
+      }
+    }
+  } catch {
+    // Ignore parsing errors
+  }
+
+  return null;
+}
+
+/**
+ * Convert byte to 2-digit hex string
+ */
+function toHex(byte: number): string {
+  return byte.toString(16).padStart(2, '0').toUpperCase();
+}
+
+/**
+ * Decode base64 string to Uint8Array
+ */
+function base64ToBytes(base64: string): Uint8Array {
+  const binaryString = atob(base64);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes;
+}
+
+/**
+ * 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 function isCodecSupported(codecString: string, containerType = 'video/mp4'): boolean {
+  if (typeof MediaSource === 'undefined' || !MediaSource.isTypeSupported) {
+    return false;
+  }
+
+  const mimeType = `${containerType}; codecs="${codecString}"`;
+  return MediaSource.isTypeSupported(mimeType);
+}
+
+/**
+ * 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 function getBestSupportedTrack(tracks: TrackInfo[], type: 'video' | 'audio'): TrackInfo | null {
+  const filteredTracks = tracks.filter(t => t.type === type);
+
+  for (const track of filteredTracks) {
+    const codecString = translateCodec(track);
+    if (isCodecSupported(codecString)) {
+      return track;
+    }
+  }
+
+  return null;
+}
+
+export default {
+  translateCodec,
+  isCodecSupported,
+  getBestSupportedTrack,
+};

package/src/core/Disposable.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 abstract class BaseDisposable implements Disposable {
+  private _disposed = false;
+
+  /**
+   * Whether this object has been disposed
+   */
+  get disposed(): boolean {
+    return this._disposed;
+  }
+
+  /**
+   * Dispose of this object, releasing all resources.
+   * Safe to call multiple times.
+   */
+  dispose(): void {
+    if (this._disposed) return;
+    this._disposed = true;
+    this.onDispose();
+  }
+
+  /**
+   * 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 = 'operation'): void {
+    if (this._disposed) {
+      throw new Error(`Cannot perform ${operation} on disposed object`);
+    }
+  }
+
+  /**
+   * Check if disposed without throwing - useful for conditional guards
+   */
+  protected guardDisposed(): boolean {
+    return this._disposed;
+  }
+}
+
+/**
+ * Utility to dispose multiple disposables at once
+ */
+export function disposeAll(...disposables: (Disposable | null | undefined)[]): void {
+  for (const d of disposables) {
+    if (d && !d.disposed) {
+      try {
+        d.dispose();
+      } catch (err) {
+        console.warn('[Disposable] Error during disposal:', err);
+      }
+    }
+  }
+}
+
+/**
+ * Create a composite disposable that disposes multiple items
+ */
+export function createCompositeDisposable(
+  ...disposables: (Disposable | (() => void))[]
+): Disposable {
+  let disposed = false;
+
+  return {
+    get disposed() {
+      return disposed;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+
+      for (const d of disposables) {
+        try {
+          if (typeof d === 'function') {
+            d();
+          } else if (d && !d.disposed) {
+            d.dispose();
+          }
+        } catch (err) {
+          console.warn('[CompositeDisposable] Error during disposal:', err);
+        }
+      }
+    },
+  };
+}
+
+export default BaseDisposable;

package/src/core/EventEmitter.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 class TypedEventEmitter<Events extends Record<string, any>> {
+  private listeners = new Map<keyof Events, Set<Function>>();
+
+  /**
+   * 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 {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(listener);
+
+    // Return unsubscribe function
+    return () => this.off(event, listener);
+  }
+
+  /**
+   * 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 {
+    const onceListener = (data: Events[K]) => {
+      this.off(event, onceListener);
+      listener(data);
+    };
+    return this.on(event, onceListener);
+  }
+
+  /**
+   * 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 {
+    this.listeners.get(event)?.delete(listener);
+  }
+
+  /**
+   * 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 {
+    this.listeners.get(event)?.forEach(listener => {
+      try {
+        listener(data);
+      } catch (e) {
+        console.error(`[EventEmitter] Error in ${String(event)} listener:`, e);
+      }
+    });
+  }
+
+  /**
+   * Remove all listeners for all events.
+   */
+  removeAllListeners(): void {
+    this.listeners.clear();
+  }
+
+  /**
+   * Remove all listeners for a specific event.
+   * @param event - The event name
+   */
+  removeListeners<K extends keyof Events>(event: K): void {
+    this.listeners.delete(event);
+  }
+
+  /**
+   * Check if there are any listeners for an event.
+   * @param event - The event name
+   */
+  hasListeners<K extends keyof Events>(event: K): boolean {
+    return (this.listeners.get(event)?.size ?? 0) > 0;
+  }
+}
+
+export default TypedEventEmitter;