@livepeer-frameworks/player-core 0.0.3

package/src/core/TimeFormat.ts

@@ -0,0 +1,205 @@
+/**
+ * TimeFormat.ts
+ *
+ * Time formatting utilities for player controls.
+ * Used by React, Svelte, and Vanilla wrappers.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface TimeDisplayParams {
+  isLive: boolean;
+  currentTime: number;
+  duration: number;
+  liveEdge: number;
+  seekableStart: number;
+  /** Unix timestamp (ms) at stream time 0 - for wall-clock display */
+  unixoffset?: number;
+}
+
+// ============================================================================
+// Pure Functions
+// ============================================================================
+
+/**
+ * Format seconds as MM:SS or HH:MM:SS.
+ *
+ * @param seconds - Time in seconds
+ * @returns Formatted time string, or "LIVE" for invalid input
+ *
+ * @example
+ * formatTime(65)    // "01:05"
+ * formatTime(3665)  // "1:01:05"
+ * formatTime(-1)    // "LIVE"
+ * formatTime(NaN)   // "LIVE"
+ */
+export function formatTime(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    return 'LIVE';
+  }
+
+  const total = Math.floor(seconds);
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const secs = total % 60;
+
+  if (hours > 0) {
+    return `${hours}:${String(minutes).padStart(2, '0')}:${String(secs).padStart(2, '0')}`;
+  }
+
+  return `${String(minutes).padStart(2, '0')}:${String(secs).padStart(2, '0')}`;
+}
+
+/**
+ * Format a Date as wall-clock time (HH:MM:SS).
+ *
+ * @param date - Date object
+ * @returns Formatted time string in HH:MM:SS format
+ *
+ * @example
+ * formatClockTime(new Date('2024-01-15T14:30:45'))  // "14:30:45"
+ */
+export function formatClockTime(date: Date): string {
+  const hours = String(date.getHours()).padStart(2, '0');
+  const minutes = String(date.getMinutes()).padStart(2, '0');
+  const seconds = String(date.getSeconds()).padStart(2, '0');
+  return `${hours}:${minutes}:${seconds}`;
+}
+
+/**
+ * Format time display for player controls.
+ *
+ * For live streams:
+ * - With unixoffset: Shows actual wall-clock time (HH:MM:SS)
+ * - With seekable window: Shows time behind live (-MM:SS) or "LIVE"
+ * - Fallback: Shows elapsed time
+ *
+ * For VOD:
+ * - Shows "current / duration" (MM:SS / MM:SS)
+ *
+ * @param params - Display parameters
+ * @returns Formatted time display string
+ *
+ * @example
+ * // Live with unixoffset
+ * formatTimeDisplay({ isLive: true, currentTime: 60, unixoffset: 1705330245000, ... })
+ * // "14:30:45"
+ *
+ * // Live behind
+ * formatTimeDisplay({ isLive: true, currentTime: 50, liveEdge: 60, ... })
+ * // "-00:10"
+ *
+ * // VOD
+ * formatTimeDisplay({ isLive: false, currentTime: 65, duration: 300, ... })
+ * // "01:05 / 05:00"
+ */
+export function formatTimeDisplay(params: TimeDisplayParams): string {
+  const { isLive, currentTime, duration, liveEdge, seekableStart, unixoffset } = params;
+
+  if (isLive) {
+    // For live: show actual wall-clock time using unixoffset
+    if (unixoffset && unixoffset > 0) {
+      // unixoffset is Unix timestamp in ms at timestamp 0 of the stream
+      // currentTime is playback position in seconds
+      const actualTimeMs = unixoffset + (currentTime * 1000);
+      const actualDate = new Date(actualTimeMs);
+      return formatClockTime(actualDate);
+    }
+
+    // Fallback: show relative time if no unixoffset
+    const seekableWindow = liveEdge - seekableStart;
+    if (seekableWindow > 0) {
+      const behindSeconds = liveEdge - currentTime;
+      if (behindSeconds < 1) {
+        return 'LIVE';
+      }
+      return `-${formatTime(Math.abs(behindSeconds))}`;
+    }
+
+    // No DVR window: show LIVE instead of a misleading timestamp
+    return 'LIVE';
+  }
+
+  // VOD: show current / total
+  if (Number.isFinite(duration) && duration > 0) {
+    return `${formatTime(currentTime)} / ${formatTime(duration)}`;
+  }
+
+  return formatTime(currentTime);
+}
+
+/**
+ * Format time for seek bar tooltip.
+ * For live streams, can show time relative to live edge.
+ *
+ * @param time - Time position in seconds
+ * @param isLive - Whether stream is live
+ * @param liveEdge - Live edge position (for relative display)
+ * @returns Formatted tooltip time
+ */
+export function formatTooltipTime(
+  time: number,
+  isLive: boolean,
+  liveEdge?: number
+): string {
+  if (isLive && liveEdge !== undefined && Number.isFinite(liveEdge)) {
+    const behindSeconds = liveEdge - time;
+    if (behindSeconds < 1) {
+      return 'LIVE';
+    }
+    return `-${formatTime(Math.abs(behindSeconds))}`;
+  }
+
+  return formatTime(time);
+}
+
+/**
+ * Format duration for display (e.g., in stats panel).
+ * Handles edge cases like infinite duration for live streams.
+ *
+ * @param duration - Duration in seconds
+ * @param isLive - Whether content is live
+ * @returns Formatted duration string
+ */
+export function formatDuration(duration: number, isLive?: boolean): string {
+  if (isLive || !Number.isFinite(duration)) {
+    return 'LIVE';
+  }
+
+  return formatTime(duration);
+}
+
+/**
+ * Parse time string (HH:MM:SS or MM:SS) to seconds.
+ *
+ * @param timeStr - Time string to parse
+ * @returns Time in seconds, or NaN if invalid
+ *
+ * @example
+ * parseTime("01:30")     // 90
+ * parseTime("1:30:45")   // 5445
+ * parseTime("invalid")   // NaN
+ */
+export function parseTime(timeStr: string): number {
+  const parts = timeStr.split(':').map(Number);
+
+  if (parts.some(isNaN)) {
+    return NaN;
+  }
+
+  if (parts.length === 2) {
+    // MM:SS
+    const [minutes, seconds] = parts;
+    return minutes * 60 + seconds;
+  }
+
+  if (parts.length === 3) {
+    // HH:MM:SS
+    const [hours, minutes, seconds] = parts;
+    return hours * 3600 + minutes * 60 + seconds;
+  }
+
+  return NaN;
+}

package/src/core/TimerManager.ts

@@ -0,0 +1,209 @@
+/**
+ * TimerManager - Centralized timer management for memory leak prevention
+ *
+ * Tracks all setTimeout/setInterval calls and provides bulk cleanup.
+ * Based on MistMetaPlayer's MistVideo.timers pattern.
+ *
+ * Usage:
+ * ```ts
+ * const timers = new TimerManager();
+ *
+ * // Start a timeout
+ * const id = timers.start(() => console.log('fired'), 1000);
+ *
+ * // Start an interval
+ * const intervalId = timers.startInterval(() => console.log('tick'), 500);
+ *
+ * // Stop a specific timer
+ * timers.stop(id);
+ *
+ * // Stop all timers (on cleanup/destroy)
+ * timers.stopAll();
+ * ```
+ */
+
+interface TimerEntry {
+  /** Timer ID from setTimeout/setInterval */
+  id: ReturnType<typeof setTimeout>;
+  /** Expected end time (for timeouts) */
+  endTime: number;
+  /** Whether this is an interval */
+  isInterval: boolean;
+  /** Optional label for debugging */
+  label?: string;
+}
+
+export class TimerManager {
+  private timers: Map<number, TimerEntry> = new Map();
+  private nextId = 1;
+  private debug: boolean;
+
+  constructor(options?: { debug?: boolean }) {
+    this.debug = options?.debug ?? false;
+  }
+
+  /**
+   * Start a timeout
+   * @param callback Function to call after delay
+   * @param delay Delay in milliseconds
+   * @param label Optional label for debugging
+   * @returns Timer ID (internal, not the native timeout ID)
+   */
+  start(callback: () => void, delay: number, label?: string): number {
+    const internalId = this.nextId++;
+    const endTime = Date.now() + delay;
+
+    const nativeId = setTimeout(() => {
+      this.timers.delete(internalId);
+      try {
+        callback();
+      } catch (e) {
+        console.error('[TimerManager] Callback error:', e);
+      }
+    }, delay);
+
+    this.timers.set(internalId, {
+      id: nativeId,
+      endTime,
+      isInterval: false,
+      label,
+    });
+
+    if (this.debug) {
+      console.debug(`[TimerManager] Started timeout ${internalId}${label ? ` (${label})` : ''} for ${delay}ms`);
+    }
+
+    return internalId;
+  }
+
+  /**
+   * Start an interval
+   * @param callback Function to call repeatedly
+   * @param interval Interval in milliseconds
+   * @param label Optional label for debugging
+   * @returns Timer ID (internal, not the native interval ID)
+   */
+  startInterval(callback: () => void, interval: number, label?: string): number {
+    const internalId = this.nextId++;
+
+    const nativeId = setInterval(() => {
+      try {
+        callback();
+      } catch (e) {
+        console.error('[TimerManager] Interval callback error:', e);
+      }
+    }, interval);
+
+    this.timers.set(internalId, {
+      id: nativeId,
+      endTime: Infinity, // Intervals don't have an end time
+      isInterval: true,
+      label,
+    });
+
+    if (this.debug) {
+      console.debug(`[TimerManager] Started interval ${internalId}${label ? ` (${label})` : ''} every ${interval}ms`);
+    }
+
+    return internalId;
+  }
+
+  /**
+   * Stop a specific timer
+   * @param internalId The timer ID returned by start() or startInterval()
+   */
+  stop(internalId: number): boolean {
+    const entry = this.timers.get(internalId);
+    if (!entry) {
+      return false;
+    }
+
+    if (entry.isInterval) {
+      clearInterval(entry.id);
+    } else {
+      clearTimeout(entry.id);
+    }
+
+    this.timers.delete(internalId);
+
+    if (this.debug) {
+      console.debug(`[TimerManager] Stopped ${entry.isInterval ? 'interval' : 'timeout'} ${internalId}${entry.label ? ` (${entry.label})` : ''}`);
+    }
+
+    return true;
+  }
+
+  /**
+   * Stop all active timers
+   * Call this on component unmount/destroy to prevent memory leaks
+   */
+  stopAll(): void {
+    const count = this.timers.size;
+
+    for (const [internalId, entry] of this.timers) {
+      if (entry.isInterval) {
+        clearInterval(entry.id);
+      } else {
+        clearTimeout(entry.id);
+      }
+    }
+
+    this.timers.clear();
+
+    if (this.debug && count > 0) {
+      console.debug(`[TimerManager] Stopped all ${count} timers`);
+    }
+  }
+
+  /**
+   * Get count of active timers
+   */
+  get activeCount(): number {
+    return this.timers.size;
+  }
+
+  /**
+   * Check if a timer is active
+   */
+  isActive(internalId: number): boolean {
+    return this.timers.has(internalId);
+  }
+
+  /**
+   * Get remaining time for a timeout (0 for intervals or expired)
+   */
+  getRemainingTime(internalId: number): number {
+    const entry = this.timers.get(internalId);
+    if (!entry || entry.isInterval) {
+      return 0;
+    }
+    return Math.max(0, entry.endTime - Date.now());
+  }
+
+  /**
+   * Get debug info about all active timers
+   */
+  getDebugInfo(): Array<{ id: number; type: 'timeout' | 'interval'; label?: string; remainingMs?: number }> {
+    const info: Array<{ id: number; type: 'timeout' | 'interval'; label?: string; remainingMs?: number }> = [];
+
+    for (const [internalId, entry] of this.timers) {
+      info.push({
+        id: internalId,
+        type: entry.isInterval ? 'interval' : 'timeout',
+        label: entry.label,
+        remainingMs: entry.isInterval ? undefined : Math.max(0, entry.endTime - Date.now()),
+      });
+    }
+
+    return info;
+  }
+
+  /**
+   * Cleanup - alias for stopAll()
+   */
+  destroy(): void {
+    this.stopAll();
+  }
+}
+
+export default TimerManager;

package/src/core/UrlUtils.ts

@@ -0,0 +1,179 @@
+/**
+ * UrlUtils - URL manipulation utilities
+ *
+ * Based on MistMetaPlayer's urlappend functionality.
+ * Provides helpers for appending query parameters to URLs.
+ */
+
+/**
+ * Append query parameters to a URL
+ * Handles URLs that already have query parameters
+ *
+ * @param url - Base URL
+ * @param params - Parameters to append (string or object)
+ * @returns URL with appended parameters
+ *
+ * @example
+ * ```ts
+ * appendUrlParams('https://example.com/video.m3u8', 'token=abc&session=123')
+ * // => 'https://example.com/video.m3u8?token=abc&session=123'
+ *
+ * appendUrlParams('https://example.com/video.m3u8?existing=param', 'token=abc')
+ * // => 'https://example.com/video.m3u8?existing=param&token=abc'
+ *
+ * appendUrlParams('https://example.com/video.m3u8', { token: 'abc', session: '123' })
+ * // => 'https://example.com/video.m3u8?token=abc&session=123'
+ * ```
+ */
+export function appendUrlParams(
+  url: string,
+  params: string | Record<string, string | number | boolean | undefined | null>
+): string {
+  if (!params) {
+    return url;
+  }
+
+  // Convert object to query string
+  let queryString: string;
+  if (typeof params === 'object') {
+    const entries = Object.entries(params)
+      .filter(([, value]) => value !== undefined && value !== null)
+      .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+
+    if (entries.length === 0) {
+      return url;
+    }
+    queryString = entries.join('&');
+  } else {
+    queryString = params;
+    // Strip leading ? or & if present
+    if (queryString.startsWith('?') || queryString.startsWith('&')) {
+      queryString = queryString.slice(1);
+    }
+  }
+
+  if (!queryString) {
+    return url;
+  }
+
+  // Determine separator (? or &)
+  const separator = url.includes('?') ? '&' : '?';
+  return `${url}${separator}${queryString}`;
+}
+
+/**
+ * Parse query parameters from a URL
+ *
+ * @param url - URL to parse
+ * @returns Object with query parameters
+ */
+export function parseUrlParams(url: string): Record<string, string> {
+  const params: Record<string, string> = {};
+
+  try {
+    const urlObj = new URL(url);
+    urlObj.searchParams.forEach((value, key) => {
+      params[key] = value;
+    });
+  } catch {
+    // If URL parsing fails, try manual parsing
+    const queryIndex = url.indexOf('?');
+    if (queryIndex === -1) {
+      return params;
+    }
+
+    const queryString = url.slice(queryIndex + 1);
+    const pairs = queryString.split('&');
+    for (const pair of pairs) {
+      const [key, value] = pair.split('=');
+      if (key) {
+        params[decodeURIComponent(key)] = value ? decodeURIComponent(value) : '';
+      }
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Remove query parameters from a URL
+ *
+ * @param url - URL to strip
+ * @returns URL without query parameters
+ */
+export function stripUrlParams(url: string): string {
+  const queryIndex = url.indexOf('?');
+  return queryIndex === -1 ? url : url.slice(0, queryIndex);
+}
+
+/**
+ * Build a URL with query parameters
+ *
+ * @param baseUrl - Base URL
+ * @param params - Query parameters
+ * @returns Complete URL
+ */
+export function buildUrl(baseUrl: string, params: Record<string, string | number | boolean | undefined | null>): string {
+  return appendUrlParams(stripUrlParams(baseUrl), params);
+}
+
+/**
+ * Check if URL uses secure protocol (https/wss)
+ */
+export function isSecureUrl(url: string): boolean {
+  return url.startsWith('https://') || url.startsWith('wss://');
+}
+
+/**
+ * Convert HTTP URL to WebSocket URL
+ * http:// -> ws://
+ * https:// -> wss://
+ */
+export function httpToWs(url: string): string {
+  return url.replace(/^http/, 'ws');
+}
+
+/**
+ * Convert WebSocket URL to HTTP URL
+ * ws:// -> http://
+ * wss:// -> https://
+ */
+export function wsToHttp(url: string): string {
+  return url.replace(/^ws/, 'http');
+}
+
+/**
+ * Ensure URL uses the same protocol as the current page
+ * Useful for avoiding mixed content issues
+ */
+export function matchPageProtocol(url: string): string {
+  if (typeof window === 'undefined') {
+    return url;
+  }
+
+  const pageIsSecure = window.location.protocol === 'https:';
+  const urlIsSecure = isSecureUrl(url);
+
+  if (pageIsSecure && !urlIsSecure) {
+    // Upgrade to secure
+    return url.replace(/^http:/, 'https:').replace(/^ws:/, 'wss:');
+  }
+
+  if (!pageIsSecure && urlIsSecure) {
+    // Downgrade to insecure (not recommended, but avoids issues)
+    return url.replace(/^https:/, 'http:').replace(/^wss:/, 'ws:');
+  }
+
+  return url;
+}
+
+export default {
+  appendUrlParams,
+  parseUrlParams,
+  stripUrlParams,
+  buildUrl,
+  isSecureUrl,
+  httpToWs,
+  wsToHttp,
+  matchPageProtocol,
+};