@editframe/elements 0.16.8-beta.0 → 0.18.3-beta.0

package/src/elements/EFMedia/services/MediaSourceService.ts

@@ -0,0 +1,102 @@
+import {
+  MediaSourceManager,
+  type MediaSourceManagerOptions,
+} from "../../../services/MediaSourceManager.js";
+
+export interface MediaSourceServiceOptions {
+  onError?: (error: Error) => void;
+  onReady?: () => void;
+  onUpdateEnd?: () => void;
+  timeout?: number;
+}
+
+/**
+ * Service for managing MediaSource lifecycle and audio element creation
+ * Extracted from EFMedia to improve separation of concerns and testability
+ */
+export class MediaSourceService {
+  private mediaSourceManager: MediaSourceManager | null = null;
+  private options: MediaSourceServiceOptions;
+
+  constructor(options: MediaSourceServiceOptions = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Initialize MediaSource if not already initialized
+   */
+  async ensureInitialized(): Promise<void> {
+    if (this.mediaSourceManager?.isReady()) {
+      return;
+    }
+
+    await this.initialize();
+  }
+
+  /**
+   * Initialize fresh MediaSource
+   */
+  async initialize(): Promise<void> {
+    // Clean up existing instance
+    this.cleanup();
+
+    // Create new MediaSourceManager
+    const managerOptions: MediaSourceManagerOptions = {
+      onError: this.options.onError,
+      onReady: this.options.onReady,
+      onUpdateEnd: this.options.onUpdateEnd,
+      timeout: this.options.timeout,
+    };
+
+    this.mediaSourceManager = new MediaSourceManager(managerOptions);
+    await this.mediaSourceManager.initialize();
+  }
+
+  /**
+   * Get audio element for MediaElementSource creation
+   */
+  getAudioElement(): HTMLAudioElement | null {
+    return this.mediaSourceManager?.getAudioElement() || null;
+  }
+
+  /**
+   * Feed audio segments to MediaSource
+   */
+  async feedSegment(segmentBuffer: ArrayBuffer): Promise<void> {
+    await this.ensureInitialized();
+    if (this.mediaSourceManager) {
+      await this.mediaSourceManager.feedSegment(segmentBuffer);
+    }
+  }
+
+  /**
+   * Check if MediaSource is ready
+   */
+  isReady(): boolean {
+    return this.mediaSourceManager?.isReady() ?? false;
+  }
+
+  /**
+   * Get buffered time ranges
+   */
+  getBuffered(): TimeRanges | null {
+    return this.mediaSourceManager?.getBuffered() || null;
+  }
+
+  /**
+   * Set audio element current time
+   */
+  setCurrentTime(timeMs: number): void {
+    this.mediaSourceManager?.setCurrentTime(timeMs);
+  }
+
+  /**
+   * Clean up MediaSource resources
+   */
+  cleanup(): void {
+    if (this.mediaSourceManager) {
+      this.mediaSourceManager.cleanup();
+      this.mediaSourceManager = null;
+    }
+  }
+}

package/src/elements/EFMedia/shared/AudioSpanUtils.ts

@@ -0,0 +1,128 @@
+import type {
+  AudioSpan,
+  MediaEngine,
+  SegmentTimeRange,
+} from "../../../transcoding/types";
+import type { EFMedia } from "../../EFMedia";
+
+/**
+ * Fetch audio segment data using MediaEngine
+ * Pure function with explicit dependencies
+ */
+const fetchAudioSegmentData = async (
+  segmentIds: number[],
+  mediaEngine: MediaEngine,
+  signal: AbortSignal,
+): Promise<Map<number, ArrayBuffer>> => {
+  const audioRendition = mediaEngine.audioRendition;
+  if (!audioRendition) {
+    throw new Error("Audio rendition not available");
+  }
+
+  const segmentData = new Map<number, ArrayBuffer>();
+
+  // Fetch all segments - MediaEngine handles deduplication internally
+  const fetchPromises = segmentIds.map(async (segmentId) => {
+    const arrayBuffer = await mediaEngine.fetchMediaSegment(
+      segmentId,
+      audioRendition,
+      signal,
+    );
+    return [segmentId, arrayBuffer] as [number, ArrayBuffer];
+  });
+
+  const fetchedSegments = await Promise.all(fetchPromises);
+  signal.throwIfAborted();
+
+  for (const [segmentId, arrayBuffer] of fetchedSegments) {
+    segmentData.set(segmentId, arrayBuffer);
+  }
+
+  return segmentData;
+};
+
+/**
+ * Create audio span blob from init segment and media segments
+ * Pure function for blob creation
+ */
+const createAudioSpanBlob = (
+  initSegment: ArrayBuffer,
+  mediaSegments: ArrayBuffer[],
+): Blob => {
+  const chunks = [initSegment, ...mediaSegments];
+  return new Blob(chunks, { type: "audio/mp4" });
+};
+
+/**
+ * Fetch audio spanning a time range
+ * Main function that orchestrates segment calculation, fetching, and blob creation
+ */
+export const fetchAudioSpanningTime = async (
+  host: EFMedia,
+  fromMs: number,
+  toMs: number,
+  signal: AbortSignal,
+): Promise<AudioSpan> => {
+  // Validate inputs
+  if (fromMs >= toMs || fromMs < 0) {
+    throw new Error(`Invalid time range: fromMs=${fromMs}, toMs=${toMs}`);
+  }
+
+  // Get dependencies from host
+  const mediaEngine = await host.mediaEngineTask.taskComplete;
+  const initSegment = await host.audioInitSegmentFetchTask.taskComplete;
+
+  if (!mediaEngine?.audioRendition) {
+    throw new Error("Audio rendition not available");
+  }
+
+  if (!initSegment) {
+    throw new Error("Audio init segment is not available");
+  }
+
+  // Calculate segments needed using the media engine's method
+  const segmentRanges = mediaEngine.calculateAudioSegmentRange(
+    fromMs,
+    toMs,
+    mediaEngine.audioRendition,
+    host.intrinsicDurationMs || 10000,
+  );
+
+  if (segmentRanges.length === 0) {
+    throw new Error(`No segments found for time range ${fromMs}-${toMs}ms`);
+  }
+
+  // Fetch segment data
+  const segmentIds = segmentRanges.map((r: SegmentTimeRange) => r.segmentId);
+  const segmentData = await fetchAudioSegmentData(
+    segmentIds,
+    mediaEngine,
+    signal,
+  );
+
+  // Create ordered array of segments
+  const orderedSegments = segmentIds.map((id: number) => {
+    const segment = segmentData.get(id);
+    if (!segment) {
+      throw new Error(`Missing segment data for segment ID ${id}`);
+    }
+    return segment;
+  });
+
+  // Create blob
+  const blob = createAudioSpanBlob(initSegment, orderedSegments);
+
+  // Calculate actual time boundaries
+  const actualStartMs = Math.min(
+    ...segmentRanges.map((r: SegmentTimeRange) => r.startMs),
+  );
+  const actualEndMs = Math.max(
+    ...segmentRanges.map((r: SegmentTimeRange) => r.endMs),
+  );
+
+  return {
+    startMs: actualStartMs,
+    endMs: actualEndMs,
+    blob,
+  };
+};

package/src/elements/EFMedia/shared/BufferUtils.ts

@@ -0,0 +1,310 @@
+import type {
+  AudioRendition,
+  VideoRendition,
+} from "../../../transcoding/types";
+
+/**
+ * State interface for media buffering - generic for both audio and video
+ */
+export interface MediaBufferState {
+  currentSeekTimeMs: number;
+  activeRequests: Set<number>;
+  cachedSegments: Set<number>;
+  requestQueue: number[];
+}
+
+/**
+ * Configuration interface for media buffering - generic for both audio and video
+ */
+export interface MediaBufferConfig {
+  bufferDurationMs: number;
+  maxParallelFetches: number;
+  enableBuffering: boolean;
+  enableContinuousBuffering?: boolean;
+}
+
+/**
+ * Dependencies interface for media buffering - generic for both audio and video
+ */
+export interface MediaBufferDependencies<
+  T extends AudioRendition | VideoRendition,
+> {
+  computeSegmentId: (
+    timeMs: number,
+    rendition: T,
+  ) => Promise<number | undefined>;
+  fetchSegment: (segmentId: number, rendition: T) => Promise<ArrayBuffer>;
+  getRendition: () => Promise<T>;
+  logError: (message: string, error: any) => void;
+}
+
+/**
+ * Compute segment range for a time window
+ * Pure function - determines which segments are needed for a time range
+ */
+export const computeSegmentRange = <T extends AudioRendition | VideoRendition>(
+  startTimeMs: number,
+  endTimeMs: number,
+  rendition: T,
+  computeSegmentId: (timeMs: number, rendition: T) => number | undefined,
+): number[] => {
+  const segments: number[] = [];
+  const segmentDurationMs = (rendition as any).segmentDurationMs || 1000;
+
+  // Calculate segment indices that overlap with [startTimeMs, endTimeMs]
+  const startSegmentIndex = Math.floor(startTimeMs / segmentDurationMs);
+  const endSegmentIndex = Math.floor(endTimeMs / segmentDurationMs);
+
+  for (let i = startSegmentIndex; i <= endSegmentIndex; i++) {
+    const segmentId = computeSegmentId(i * segmentDurationMs, rendition);
+    if (segmentId !== undefined) {
+      segments.push(segmentId);
+    }
+  }
+
+  return segments.filter((id, index, arr) => arr.indexOf(id) === index); // Remove duplicates
+};
+
+/**
+ * Async version of computeSegmentRange for when computeSegmentId is async
+ */
+export const computeSegmentRangeAsync = async <
+  T extends AudioRendition | VideoRendition,
+>(
+  startTimeMs: number,
+  endTimeMs: number,
+  durationMs: number,
+  rendition: T,
+  computeSegmentId: (
+    timeMs: number,
+    rendition: T,
+  ) => Promise<number | undefined>,
+): Promise<number[]> => {
+  const segments: number[] = [];
+  const segmentDurationMs = (rendition as any).segmentDurationMs || 1000;
+
+  // Calculate segment indices that overlap with [startTimeMs, endTimeMs]
+  const startSegmentIndex = Math.floor(startTimeMs / segmentDurationMs);
+  const endSegmentIndex = Math.floor(
+    Math.min(endTimeMs, durationMs) / segmentDurationMs,
+  );
+
+  for (let i = startSegmentIndex; i <= endSegmentIndex; i++) {
+    const timeMs = i * segmentDurationMs;
+    if (timeMs < durationMs) {
+      const segmentId = await computeSegmentId(timeMs, rendition);
+      if (segmentId !== undefined) {
+        segments.push(segmentId);
+      }
+    }
+  }
+
+  return segments.filter((id, index, arr) => arr.indexOf(id) === index); // Remove duplicates
+};
+
+/**
+ * Compute buffer queue based on current state and desired segments
+ * Pure function - determines what segments should be fetched
+ */
+export const computeBufferQueue = (
+  desiredSegments: number[],
+  activeRequests: Set<number>,
+  cachedSegments: Set<number>,
+): number[] => {
+  return desiredSegments.filter(
+    (segmentId) =>
+      !activeRequests.has(segmentId) && !cachedSegments.has(segmentId),
+  );
+};
+
+/**
+ * Handle seek time change and recompute buffer queue
+ * Pure function - computes new queue when seek time changes
+ */
+export const handleSeekTimeChange = <T extends AudioRendition | VideoRendition>(
+  newSeekTimeMs: number,
+  bufferDurationMs: number,
+  rendition: T,
+  currentState: MediaBufferState,
+  computeSegmentId: (timeMs: number, rendition: T) => number | undefined,
+): { newQueue: number[]; overlappingRequests: number[] } => {
+  const endTimeMs = newSeekTimeMs + bufferDurationMs;
+  const desiredSegments = computeSegmentRange(
+    newSeekTimeMs,
+    endTimeMs,
+    rendition,
+    computeSegmentId,
+  );
+
+  // Find segments that are already being requested
+  const overlappingRequests = desiredSegments.filter((segmentId) =>
+    currentState.activeRequests.has(segmentId),
+  );
+
+  const newQueue = computeBufferQueue(
+    desiredSegments,
+    currentState.activeRequests,
+    currentState.cachedSegments,
+  );
+
+  return { newQueue, overlappingRequests };
+};
+
+/**
+ * Check if a specific segment is cached in the buffer
+ * Pure function for accessing buffer cache state
+ */
+export const getCachedSegment = (
+  segmentId: number,
+  bufferState: MediaBufferState | undefined,
+): boolean => {
+  return bufferState?.cachedSegments.has(segmentId) ?? false;
+};
+
+/**
+ * Get cached segments from a list of segment IDs
+ * Pure function that returns which segments are available in cache
+ */
+export const getCachedSegments = (
+  segmentIds: number[],
+  bufferState: MediaBufferState | undefined,
+): Set<number> => {
+  if (!bufferState) {
+    return new Set();
+  }
+  return new Set(segmentIds.filter((id) => bufferState.cachedSegments.has(id)));
+};
+
+/**
+ * Get missing segments from a list of segment IDs
+ * Pure function that returns which segments need to be fetched
+ */
+export const getMissingSegments = (
+  segmentIds: number[],
+  bufferState: MediaBufferState | undefined,
+): number[] => {
+  if (!bufferState) {
+    return segmentIds;
+  }
+  return segmentIds.filter((id) => !bufferState.cachedSegments.has(id));
+};
+
+/**
+ * Core media buffering logic with explicit dependencies
+ * Generic implementation that works for both audio and video
+ */
+export const manageMediaBuffer = async <
+  T extends AudioRendition | VideoRendition,
+>(
+  seekTimeMs: number,
+  config: MediaBufferConfig,
+  currentState: MediaBufferState,
+  durationMs: number,
+  signal: AbortSignal,
+  deps: MediaBufferDependencies<T>,
+): Promise<MediaBufferState> => {
+  if (!config.enableBuffering) {
+    return currentState;
+  }
+
+  const rendition = await deps.getRendition();
+  const endTimeMs = seekTimeMs + config.bufferDurationMs;
+
+  const desiredSegments = await computeSegmentRangeAsync(
+    seekTimeMs,
+    endTimeMs,
+    durationMs,
+    rendition,
+    deps.computeSegmentId,
+  );
+
+  const newQueue = computeBufferQueue(
+    desiredSegments,
+    currentState.activeRequests,
+    currentState.cachedSegments,
+  );
+
+  // Start fetching segments up to maxParallelFetches limit
+  const segmentsToFetch = newQueue.slice(0, config.maxParallelFetches);
+  const newActiveRequests = new Set(currentState.activeRequests);
+  const newCachedSegments = new Set(currentState.cachedSegments);
+
+  // Function to start next individual segment when a slot becomes available
+  const startNextSegment = (remainingQueue: number[]): void => {
+    if (remainingQueue.length === 0 || signal.aborted) return;
+
+    const availableSlots = config.maxParallelFetches - newActiveRequests.size;
+    if (availableSlots <= 0) return;
+
+    const nextSegmentId = remainingQueue[0];
+    if (nextSegmentId === undefined) return;
+
+    if (
+      newActiveRequests.has(nextSegmentId) ||
+      newCachedSegments.has(nextSegmentId)
+    ) {
+      // Skip this segment and try the next
+      startNextSegment(remainingQueue.slice(1));
+      return;
+    }
+
+    newActiveRequests.add(nextSegmentId);
+
+    deps
+      .fetchSegment(nextSegmentId, rendition)
+      .then(() => {
+        if (signal.aborted) return;
+        newActiveRequests.delete(nextSegmentId);
+        newCachedSegments.add(nextSegmentId);
+        startNextSegment(remainingQueue.slice(1));
+      })
+      .catch((error) => {
+        if (signal.aborted) return;
+        newActiveRequests.delete(nextSegmentId);
+        deps.logError(`Failed to fetch segment ${nextSegmentId}`, error);
+        startNextSegment(remainingQueue.slice(1));
+      });
+  };
+
+  // Start fetch promises for new segments
+  for (const segmentId of segmentsToFetch) {
+    if (signal.aborted) break;
+
+    newActiveRequests.add(segmentId);
+
+    // Start fetch (don't await - let it run in background)
+    deps
+      .fetchSegment(segmentId, rendition)
+      .then(() => {
+        if (signal.aborted) return;
+        // On success, move from active to cached
+        newActiveRequests.delete(segmentId);
+        newCachedSegments.add(segmentId);
+
+        // Continue buffering if there are more segments needed and continuous buffering is enabled
+        if (config.enableContinuousBuffering ?? true) {
+          const remainingQueue = newQueue.slice(segmentsToFetch.length);
+          startNextSegment(remainingQueue);
+        }
+      })
+      .catch((error) => {
+        if (signal.aborted) return;
+        // On error, remove from active and continue
+        newActiveRequests.delete(segmentId);
+        deps.logError(`Failed to fetch segment ${segmentId}`, error);
+
+        // Continue buffering even after error if continuous buffering is enabled
+        if (config.enableContinuousBuffering ?? true) {
+          const remainingQueue = newQueue.slice(segmentsToFetch.length);
+          startNextSegment(remainingQueue);
+        }
+      });
+  }
+
+  return {
+    currentSeekTimeMs: seekTimeMs,
+    activeRequests: newActiveRequests,
+    cachedSegments: newCachedSegments,
+    requestQueue: newQueue.slice(segmentsToFetch.length), // Remaining queue
+  };
+};

package/src/elements/EFMedia/shared/MediaTaskUtils.ts

@@ -0,0 +1,44 @@
+import type { Task } from "@lit/task";
+import type {
+  AudioRendition,
+  MediaEngine,
+  VideoRendition,
+} from "../../../transcoding/types";
+import type { BufferedSeekingInput } from "../BufferedSeekingInput";
+
+/**
+ * Generic rendition type that can be either audio or video
+ */
+export type MediaRendition = AudioRendition | VideoRendition;
+
+/**
+ * Generic task type for init segment fetch
+ */
+export type InitSegmentFetchTask = Task<
+  readonly [MediaEngine | undefined],
+  ArrayBuffer
+>;
+
+/**
+ * Generic task type for segment ID calculation
+ */
+export type SegmentIdTask = Task<
+  readonly [MediaEngine | undefined, number],
+  number | undefined
+>;
+
+/**
+ * Generic task type for segment fetch
+ */
+export type SegmentFetchTask = Task<
+  readonly [MediaEngine | undefined, number | undefined],
+  ArrayBuffer
+>;
+
+/**
+ * Generic task type for input creation
+ */
+export type InputTask = Task<
+  readonly [ArrayBuffer, ArrayBuffer],
+  BufferedSeekingInput
+>;