@livepeer-frameworks/player-core 0.0.3

package/src/core/SubtitleManager.ts

@@ -0,0 +1,297 @@
+/**
+ * SubtitleManager - WebVTT subtitle track management
+ *
+ * Based on MistMetaPlayer's subtitle handling (wrappers/html5.js, webrtc.js).
+ * Manages text tracks on video elements with support for:
+ * - Loading WebVTT from MistServer URLs
+ * - Multiple subtitle track selection
+ * - Sync correction for WebRTC seek offsets
+ */
+
+export interface SubtitleTrackInfo {
+  /** Track ID (from MistServer) */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Language code (e.g., 'en', 'es') */
+  lang: string;
+  /** Source URL for WebVTT file */
+  src: string;
+  /** Whether this is the default track */
+  default?: boolean;
+}
+
+export interface SubtitleManagerConfig {
+  /** Base URL for MistServer (for constructing track URLs) */
+  mistBaseUrl?: string;
+  /** Stream name */
+  streamName?: string;
+  /** URL append string (auth tokens, etc.) */
+  urlAppend?: string;
+  /** Debug logging */
+  debug?: boolean;
+}
+
+/**
+ * SubtitleManager handles text track lifecycle on a video element
+ */
+export class SubtitleManager {
+  private video: HTMLVideoElement | null = null;
+  private config: SubtitleManagerConfig;
+  private currentTrackId: string | null = null;
+  private seekOffset = 0;
+  private debug: boolean;
+  private listeners: Array<() => void> = [];
+
+  constructor(config: SubtitleManagerConfig = {}) {
+    this.config = config;
+    this.debug = config.debug ?? false;
+  }
+
+  /**
+   * Attach to a video element
+   */
+  attach(video: HTMLVideoElement): void {
+    this.detach();
+    this.video = video;
+
+    // Listen for events that may require sync correction
+    const onLoadedData = () => this.correctSubtitleSync();
+    const onSeeked = () => this.correctSubtitleSync();
+
+    video.addEventListener('loadeddata', onLoadedData);
+    video.addEventListener('seeked', onSeeked);
+
+    this.listeners = [
+      () => video.removeEventListener('loadeddata', onLoadedData),
+      () => video.removeEventListener('seeked', onSeeked),
+    ];
+  }
+
+  /**
+   * Detach from video element
+   */
+  detach(): void {
+    this.listeners.forEach(fn => fn());
+    this.listeners = [];
+    this.removeAllTracks();
+    this.video = null;
+    this.currentTrackId = null;
+  }
+
+  /**
+   * Get available text tracks from the video element
+   */
+  getTextTracks(): TextTrack[] {
+    if (!this.video) return [];
+    return Array.from(this.video.textTracks);
+  }
+
+  /**
+   * Get all track elements from the video
+   */
+  getTrackElements(): HTMLTrackElement[] {
+    if (!this.video) return [];
+    return Array.from(this.video.querySelectorAll('track'));
+  }
+
+  /**
+   * Set the active subtitle track
+   * Pass null to disable subtitles
+   */
+  setSubtitle(track: SubtitleTrackInfo | null): void {
+    if (!this.video) {
+      this.log('Cannot set subtitle: no video element attached');
+      return;
+    }
+
+    // Remove existing subtitle tracks
+    this.removeAllTracks();
+
+    if (!track) {
+      this.currentTrackId = null;
+      this.log('Subtitles disabled');
+      return;
+    }
+
+    // Create new track element
+    const trackElement = document.createElement('track');
+    trackElement.kind = 'subtitles';
+    trackElement.label = track.label;
+    trackElement.srclang = track.lang;
+    trackElement.src = this.buildTrackUrl(track.src);
+    trackElement.default = true;
+
+    // Set up load handler for sync correction
+    trackElement.addEventListener('load', () => {
+      this.correctSubtitleSync();
+    });
+
+    this.video.appendChild(trackElement);
+    this.currentTrackId = track.id;
+
+    // Enable the track
+    const textTrack = this.video.textTracks[this.video.textTracks.length - 1];
+    if (textTrack) {
+      textTrack.mode = 'showing';
+    }
+
+    this.log(`Subtitle track set: ${track.label} (${track.lang})`);
+  }
+
+  /**
+   * Build track URL with base URL and append params
+   */
+  private buildTrackUrl(src: string): string {
+    let url = src;
+
+    // If relative URL and base URL provided, construct full URL
+    if (!url.startsWith('http') && this.config.mistBaseUrl) {
+      const base = this.config.mistBaseUrl.replace(/\/$/, '');
+      url = url.startsWith('/') ? `${base}${url}` : `${base}/${url}`;
+    }
+
+    // Append URL params if configured
+    if (this.config.urlAppend) {
+      const separator = url.includes('?') ? '&' : '?';
+      url = `${url}${separator}${this.config.urlAppend}`;
+    }
+
+    return url;
+  }
+
+  /**
+   * Create subtitle track info from MistServer track metadata
+   */
+  static createTrackInfo(
+    trackId: string,
+    label: string,
+    lang: string,
+    baseUrl: string,
+    streamName: string
+  ): SubtitleTrackInfo {
+    // MistServer WebVTT URL format
+    const src = `${baseUrl}/${streamName}.vtt?track=${trackId}`;
+    return { id: trackId, label, lang, src };
+  }
+
+  /**
+   * Remove all track elements from video
+   */
+  removeAllTracks(): void {
+    if (!this.video) return;
+
+    const tracks = this.video.querySelectorAll('track');
+    tracks.forEach(track => track.remove());
+  }
+
+  /**
+   * Get currently active track ID
+   */
+  getCurrentTrackId(): string | null {
+    return this.currentTrackId;
+  }
+
+  /**
+   * Set seek offset for WebRTC sync correction
+   * WebRTC playback has a seek offset that needs to be applied to subtitle timing
+   */
+  setSeekOffset(offset: number): void {
+    const oldOffset = this.seekOffset;
+    this.seekOffset = offset;
+
+    // Re-sync if offset changed significantly
+    if (Math.abs(oldOffset - offset) > 1) {
+      this.correctSubtitleSync();
+    }
+  }
+
+  /**
+   * Correct subtitle timing based on seek offset
+   * This is needed for WebRTC where video.currentTime doesn't match actual playback position
+   */
+  private correctSubtitleSync(): void {
+    if (!this.video || this.video.textTracks.length === 0) return;
+
+    const textTrack = this.video.textTracks[0];
+    if (!textTrack || !textTrack.cues) return;
+
+    const currentOffset = (textTrack as any).currentOffset || 0;
+
+    // Don't bother if change is small
+    if (Math.abs(this.seekOffset - currentOffset) < 1) return;
+
+    this.log(`Correcting subtitle sync: offset ${currentOffset} -> ${this.seekOffset}`);
+
+    // Collect and re-add cues with corrected timing
+    const newCues: VTTCue[] = [];
+
+    for (let i = textTrack.cues.length - 1; i >= 0; i--) {
+      const cue = textTrack.cues[i] as VTTCue;
+      textTrack.removeCue(cue);
+
+      // Store original timing if not already stored
+      if (!(cue as any).orig) {
+        (cue as any).orig = { start: cue.startTime, end: cue.endTime };
+      }
+
+      // Apply offset correction
+      cue.startTime = (cue as any).orig.start - this.seekOffset;
+      cue.endTime = (cue as any).orig.end - this.seekOffset;
+
+      newCues.push(cue);
+    }
+
+    // Re-add cues
+    for (const cue of newCues) {
+      try {
+        textTrack.addCue(cue);
+      } catch (e) {
+        // Ignore errors from invalid cue timing
+      }
+    }
+
+    (textTrack as any).currentOffset = this.seekOffset;
+  }
+
+  /**
+   * Parse subtitle tracks from MistServer stream info
+   */
+  static parseTracksFromStreamInfo(
+    streamInfo: { meta?: { tracks?: Record<string, { type: string; codec: string; lang?: string }> } },
+    baseUrl: string,
+    streamName: string
+  ): SubtitleTrackInfo[] {
+    const tracks: SubtitleTrackInfo[] = [];
+
+    if (!streamInfo.meta?.tracks) return tracks;
+
+    for (const [trackId, trackData] of Object.entries(streamInfo.meta.tracks)) {
+      if (trackData.type === 'meta' && trackData.codec === 'subtitle') {
+        const lang = trackData.lang || 'und';
+        const label = lang === 'und' ? `Subtitles ${trackId}` : lang.toUpperCase();
+        tracks.push(SubtitleManager.createTrackInfo(trackId, label, lang, baseUrl, streamName));
+      }
+    }
+
+    return tracks;
+  }
+
+  /**
+   * Debug logging
+   */
+  private log(message: string): void {
+    if (this.debug) {
+      console.debug(`[SubtitleManager] ${message}`);
+    }
+  }
+
+  /**
+   * Cleanup
+   */
+  destroy(): void {
+    this.detach();
+  }
+}
+
+export default SubtitleManager;

package/src/core/TelemetryReporter.ts

@@ -0,0 +1,308 @@
+import type { TelemetryPayload, TelemetryOptions, PlaybackQuality, ContentType } from '../types';
+
+/**
+ * Generate a unique session ID
+ */
+function generateSessionId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+export interface TelemetryReporterConfig {
+  /** Telemetry endpoint URL */
+  endpoint: string;
+  /** Auth token for endpoint */
+  authToken?: string;
+  /** Report interval in ms (default: 5000) */
+  interval?: number;
+  /** Batch size before flush (default: 1) */
+  batchSize?: number;
+  /** Content ID being played */
+  contentId: string;
+  /** Content type */
+  contentType: ContentType;
+  /** Player type name */
+  playerType: string;
+  /** Protocol being used */
+  protocol: string;
+}
+
+/**
+ * TelemetryReporter - Sends playback metrics to server
+ *
+ * Features:
+ * - Batched reporting at configurable interval
+ * - Retry with exponential backoff on failure
+ * - Uses navigator.sendBeacon() for reliable page unload reporting
+ * - Tracks errors during playback
+ */
+export class TelemetryReporter {
+  private config: Required<TelemetryReporterConfig>;
+  private sessionId: string;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private pendingPayloads: TelemetryPayload[] = [];
+  private errors: Array<{ code: string; message: string; timestamp: number }> = [];
+  private stallCount = 0;
+  private totalStallMs = 0;
+  private lastStallStart = 0;
+  private videoElement: HTMLVideoElement | null = null;
+  private qualityGetter: (() => PlaybackQuality | null) | null = null;
+  private listeners: Array<() => void> = [];
+
+  constructor(config: TelemetryReporterConfig) {
+    this.config = {
+      endpoint: config.endpoint,
+      authToken: config.authToken ?? '',
+      interval: config.interval ?? 5000,
+      batchSize: config.batchSize ?? 1,
+      contentId: config.contentId,
+      contentType: config.contentType,
+      playerType: config.playerType,
+      protocol: config.protocol,
+    };
+    this.sessionId = generateSessionId();
+  }
+
+  /**
+   * Start telemetry reporting
+   */
+  start(
+    videoElement: HTMLVideoElement,
+    qualityGetter?: () => PlaybackQuality | null
+  ): void {
+    this.stop();
+
+    this.videoElement = videoElement;
+    this.qualityGetter = qualityGetter ?? null;
+    this.stallCount = 0;
+    this.totalStallMs = 0;
+    this.errors = [];
+
+    // Track stalls
+    const onWaiting = () => {
+      this.stallCount++;
+      this.lastStallStart = performance.now();
+    };
+
+    const onPlaying = () => {
+      if (this.lastStallStart > 0) {
+        this.totalStallMs += performance.now() - this.lastStallStart;
+        this.lastStallStart = 0;
+      }
+    };
+
+    const onError = () => {
+      const error = videoElement.error;
+      if (error) {
+        this.errors.push({
+          code: String(error.code),
+          message: error.message || 'Unknown error',
+          timestamp: Date.now(),
+        });
+      }
+    };
+
+    videoElement.addEventListener('waiting', onWaiting);
+    videoElement.addEventListener('playing', onPlaying);
+    videoElement.addEventListener('error', onError);
+
+    this.listeners = [
+      () => videoElement.removeEventListener('waiting', onWaiting),
+      () => videoElement.removeEventListener('playing', onPlaying),
+      () => videoElement.removeEventListener('error', onError),
+    ];
+
+    // Setup unload handler for reliable final report
+    const onUnload = () => this.flushSync();
+    window.addEventListener('beforeunload', onUnload);
+    window.addEventListener('pagehide', onUnload);
+    this.listeners.push(
+      () => window.removeEventListener('beforeunload', onUnload),
+      () => window.removeEventListener('pagehide', onUnload)
+    );
+
+    // Start reporting interval
+    this.intervalId = setInterval(() => this.report(), this.config.interval);
+
+    // Take initial report
+    this.report();
+  }
+
+  /**
+   * Stop telemetry reporting
+   */
+  stop(): void {
+    // Final report before stopping
+    this.flushSync();
+
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+
+    this.listeners.forEach(cleanup => cleanup());
+    this.listeners = [];
+
+    this.videoElement = null;
+    this.qualityGetter = null;
+  }
+
+  /**
+   * Record a custom error
+   */
+  recordError(code: string, message: string): void {
+    this.errors.push({
+      code,
+      message,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Generate telemetry payload
+   */
+  private generatePayload(): TelemetryPayload | null {
+    const video = this.videoElement;
+    if (!video) return null;
+
+    // Get quality metrics if available
+    const quality = this.qualityGetter?.() ?? null;
+
+    // Get frame stats if available
+    let framesDecoded = 0;
+    let framesDropped = 0;
+
+    if ('getVideoPlaybackQuality' in video) {
+      const stats = video.getVideoPlaybackQuality();
+      framesDecoded = stats.totalVideoFrames;
+      framesDropped = stats.droppedVideoFrames;
+    }
+
+    // Calculate buffered seconds
+    let bufferedSeconds = 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) {
+          bufferedSeconds = video.buffered.end(i) - video.currentTime;
+          break;
+        }
+      }
+    }
+
+    return {
+      timestamp: Date.now(),
+      sessionId: this.sessionId,
+      contentId: this.config.contentId,
+      contentType: this.config.contentType,
+      metrics: {
+        currentTime: video.currentTime,
+        duration: isFinite(video.duration) ? video.duration : -1,
+        bufferedSeconds,
+        stallCount: this.stallCount,
+        totalStallMs: this.totalStallMs,
+        bitrate: quality?.bitrate ?? 0,
+        qualityScore: quality?.score ?? 100,
+        framesDecoded,
+        framesDropped,
+        playerType: this.config.playerType,
+        protocol: this.config.protocol,
+        resolution: video.videoWidth > 0 ? {
+          width: video.videoWidth,
+          height: video.videoHeight,
+        } : undefined,
+      },
+      errors: this.errors.length > 0 ? [...this.errors] : undefined,
+    };
+  }
+
+  /**
+   * Send telemetry report
+   */
+  private async report(): Promise<void> {
+    const payload = this.generatePayload();
+    if (!payload) return;
+
+    this.pendingPayloads.push(payload);
+
+    // Flush if batch size reached
+    if (this.pendingPayloads.length >= this.config.batchSize) {
+      await this.flush();
+    }
+  }
+
+  /**
+   * Flush pending payloads (async)
+   */
+  private async flush(): Promise<void> {
+    if (this.pendingPayloads.length === 0) return;
+
+    const payloads = [...this.pendingPayloads];
+    this.pendingPayloads = [];
+
+    try {
+      const headers: HeadersInit = {
+        'Content-Type': 'application/json',
+      };
+
+      if (this.config.authToken) {
+        headers['Authorization'] = `Bearer ${this.config.authToken}`;
+      }
+
+      const response = await fetch(this.config.endpoint, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(payloads.length === 1 ? payloads[0] : payloads),
+      });
+
+      if (!response.ok) {
+        console.warn('[TelemetryReporter] Report failed:', response.status);
+        // Re-queue failed payloads (up to a limit)
+        if (this.pendingPayloads.length < 10) {
+          this.pendingPayloads.unshift(...payloads);
+        }
+      } else {
+        // Clear reported errors
+        this.errors = [];
+      }
+    } catch (error) {
+      console.warn('[TelemetryReporter] Report error:', error);
+      // Re-queue failed payloads
+      if (this.pendingPayloads.length < 10) {
+        this.pendingPayloads.unshift(...payloads);
+      }
+    }
+  }
+
+  /**
+   * Flush synchronously using sendBeacon (for page unload)
+   */
+  private flushSync(): void {
+    const payload = this.generatePayload();
+    if (!payload) return;
+
+    const payloads = [...this.pendingPayloads, payload];
+    this.pendingPayloads = [];
+
+    try {
+      const data = JSON.stringify(payloads.length === 1 ? payloads[0] : payloads);
+      navigator.sendBeacon(this.config.endpoint, new Blob([data], { type: 'application/json' }));
+    } catch (error) {
+      console.warn('[TelemetryReporter] Beacon failed:', error);
+    }
+  }
+
+  /**
+   * Get session ID
+   */
+  getSessionId(): string {
+    return this.sessionId;
+  }
+
+  /**
+   * Check if reporting is active
+   */
+  isActive(): boolean {
+    return this.intervalId !== null;
+  }
+}
+
+export default TelemetryReporter;