@editframe/elements 0.17.6-beta.0 → 0.18.7-beta.0

package/src/elements/EFMedia/BaseMediaEngine.test.ts

@@ -0,0 +1,164 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { EFMedia } from "../EFMedia.js";
+import { BaseMediaEngine } from "./BaseMediaEngine.js";
+
+// Test implementation of BaseMediaEngine for testing
+class TestMediaEngine extends BaseMediaEngine {
+  fetchMediaSegmentImpl = vi.fn();
+
+  get host() {
+    return new EFMedia();
+  }
+
+  get videoRendition() {
+    return {
+      trackId: 1,
+      src: "test-video.mp4",
+      segmentDurationMs: 2000,
+    };
+  }
+
+  get audioRendition() {
+    return {
+      trackId: 2,
+      src: "test-audio.mp4",
+      segmentDurationMs: 1000,
+    };
+  }
+}
+
+describe("BaseMediaEngine deduplication", () => {
+  let engine: TestMediaEngine;
+  const mockSegmentData = new ArrayBuffer(1024);
+
+  beforeEach(() => {
+    engine = new TestMediaEngine();
+    engine.fetchMediaSegmentImpl.mockResolvedValue(mockSegmentData);
+  });
+
+  it("should fetch segment successfully", async () => {
+    const rendition = { trackId: 1, src: "test.mp4" };
+    const result = await engine.fetchMediaSegment(1, rendition);
+
+    expect(result).toBe(mockSegmentData);
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledWith(1, rendition);
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it("should deduplicate concurrent requests for same segment", async () => {
+    const rendition = { trackId: 1, src: "test.mp4" };
+
+    // Make two concurrent requests for the same segment
+    const [result1, result2] = await Promise.all([
+      engine.fetchMediaSegment(1, rendition),
+      engine.fetchMediaSegment(1, rendition),
+    ]);
+
+    // Both should return the same result
+    expect(result1).toBe(mockSegmentData);
+    expect(result2).toBe(mockSegmentData);
+
+    // But fetchMediaSegmentImpl should only be called once due to deduplication
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledTimes(1);
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledWith(1, rendition);
+  });
+
+  it("should handle different segments as separate requests", async () => {
+    const rendition = { trackId: 1, src: "test.mp4" };
+
+    // Make concurrent requests for different segments
+    const [result1, result2] = await Promise.all([
+      engine.fetchMediaSegment(1, rendition),
+      engine.fetchMediaSegment(2, rendition),
+    ]);
+
+    expect(result1).toBe(mockSegmentData);
+    expect(result2).toBe(mockSegmentData);
+
+    // Should call fetchMediaSegmentImpl twice for different segments
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledTimes(2);
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledWith(1, rendition);
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledWith(2, rendition);
+  });
+
+  it("should handle different renditions as separate requests", async () => {
+    const rendition1 = { trackId: 1, src: "test1.mp4" };
+    const rendition2 = { trackId: 2, src: "test2.mp4" };
+
+    // Make concurrent requests for same segment but different renditions
+    const [result1, result2] = await Promise.all([
+      engine.fetchMediaSegment(1, rendition1),
+      engine.fetchMediaSegment(1, rendition2),
+    ]);
+
+    expect(result1).toBe(mockSegmentData);
+    expect(result2).toBe(mockSegmentData);
+
+    // Should call fetchMediaSegmentImpl twice for different renditions
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledTimes(2);
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledWith(1, rendition1);
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledWith(1, rendition2);
+  });
+
+  it("should propagate errors correctly", async () => {
+    const error = new Error("Fetch failed");
+    engine.fetchMediaSegmentImpl.mockRejectedValue(error);
+
+    const rendition = { trackId: 1, src: "test.mp4" };
+
+    await expect(engine.fetchMediaSegment(1, rendition)).rejects.toThrow(
+      "Fetch failed",
+    );
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledWith(1, rendition);
+  });
+
+  it("should retry failed requests after error", async () => {
+    const rendition = { trackId: 1, src: "test.mp4" };
+    const error = new Error("First attempt failed");
+
+    // First request fails
+    engine.fetchMediaSegmentImpl.mockRejectedValueOnce(error);
+    await expect(engine.fetchMediaSegment(1, rendition)).rejects.toThrow(
+      "First attempt failed",
+    );
+
+    // Second request should succeed (not deduplicated since first failed)
+    engine.fetchMediaSegmentImpl.mockResolvedValue(mockSegmentData);
+    const result = await engine.fetchMediaSegment(1, rendition);
+
+    expect(result).toBe(mockSegmentData);
+    expect(engine.fetchMediaSegmentImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it("should track pending requests correctly", () => {
+    const rendition = { trackId: 1, src: "test.mp4" };
+
+    // Start a request but don't await it
+    const promise = engine.fetchMediaSegment(1, rendition);
+
+    // Should detect that segment is being fetched
+    expect(engine.isSegmentBeingFetched(1, rendition)).toBe(true);
+    expect(engine.getActiveSegmentRequestCount()).toBe(1);
+
+    // Different segment should not be detected as being fetched
+    expect(engine.isSegmentBeingFetched(2, rendition)).toBe(false);
+
+    return promise.then(() => {
+      // After completion, should no longer be detected as being fetched
+      expect(engine.isSegmentBeingFetched(1, rendition)).toBe(false);
+      expect(engine.getActiveSegmentRequestCount()).toBe(0);
+    });
+  });
+
+  it("should cancel all requests correctly", async () => {
+    const rendition = { trackId: 1, src: "test.mp4" };
+
+    // Start a request
+    engine.fetchMediaSegment(1, rendition);
+    expect(engine.getActiveSegmentRequestCount()).toBe(1);
+
+    // Cancel all requests
+    engine.cancelAllSegmentRequests();
+    expect(engine.getActiveSegmentRequestCount()).toBe(0);
+  });
+});

package/src/elements/EFMedia/BaseMediaEngine.ts

@@ -0,0 +1,219 @@
+import { RequestDeduplicator } from "../../transcoding/cache/RequestDeduplicator.js";
+import type {
+  AudioRendition,
+  SegmentTimeRange,
+  VideoRendition,
+} from "../../transcoding/types";
+import { SizeAwareLRUCache } from "../../utils/LRUCache.js";
+import type { EFMedia } from "../EFMedia.js";
+
+// 100MB cache limit
+const mediaCache = new SizeAwareLRUCache<string>(100 * 1024 * 1024);
+
+export abstract class BaseMediaEngine {
+  // Request deduplicator for in-flight segment fetches
+  private requestDeduplicator = new RequestDeduplicator();
+
+  abstract get videoRendition(): VideoRendition | undefined;
+  abstract get audioRendition(): AudioRendition | undefined;
+  abstract get host(): EFMedia;
+
+  getVideoRendition(): VideoRendition {
+    if (!this.videoRendition) {
+      throw new Error("No video rendition available");
+    }
+    return this.videoRendition;
+  }
+
+  getAudioRendition(): AudioRendition {
+    if (!this.audioRendition) {
+      throw new Error("No audio rendition available");
+    }
+    return this.audioRendition;
+  }
+
+  /**
+   * Generate cache key for segment requests
+   */
+  private getSegmentCacheKey(
+    segmentId: number,
+    rendition: { src: string; trackId: number | undefined; id?: string },
+  ): string {
+    return `${rendition.src}-${rendition.id}-${segmentId}-${rendition.trackId}`;
+  }
+
+  /**
+   * Abstract method for actual segment fetching - implemented by subclasses
+   */
+  abstract fetchMediaSegmentImpl(
+    segmentId: number,
+    rendition: { trackId: number | undefined; src: string },
+  ): Promise<ArrayBuffer>;
+
+  /**
+   * Fetch media segment with built-in deduplication
+   * Eliminates the need for separate coordinators - cleaner architecture
+   */
+  async fetchMediaSegment(
+    segmentId: number,
+    rendition: { trackId: number | undefined; src: string },
+    _signal?: AbortSignal,
+  ): Promise<ArrayBuffer> {
+    const cacheKey = this.getSegmentCacheKey(segmentId, rendition);
+
+    return this.requestDeduplicator.executeRequest(cacheKey, async () => {
+      return this.fetchMediaSegmentImpl(segmentId, rendition);
+    });
+  }
+
+  /**
+   * Check if a segment is currently being fetched
+   */
+  isSegmentBeingFetched(
+    segmentId: number,
+    rendition: { src: string; trackId: number | undefined },
+  ): boolean {
+    const cacheKey = this.getSegmentCacheKey(segmentId, rendition);
+    return this.requestDeduplicator.isPending(cacheKey);
+  }
+
+  /**
+   * Get count of active segment requests (for debugging/monitoring)
+   */
+  getActiveSegmentRequestCount(): number {
+    return this.requestDeduplicator.getPendingCount();
+  }
+
+  /**
+   * Cancel all active segment requests (for cleanup)
+   */
+  cancelAllSegmentRequests(): void {
+    this.requestDeduplicator.clear();
+  }
+
+  async fetchMediaCache(mediaUrl: string) {
+    const cached = mediaCache.get(mediaUrl);
+    if (cached) {
+      return cached;
+    }
+    const promise = this.host
+      .fetch(mediaUrl)
+      .then((response) => response.arrayBuffer());
+    mediaCache.set(mediaUrl, promise);
+    return promise;
+  }
+
+  /**
+   * Enhanced caching method that supports custom headers (e.g., Range requests)
+   * Cache key includes both URL and headers for proper cache isolation
+   */
+  async fetchMediaCacheWithHeaders(
+    mediaUrl: string,
+    headers?: Record<string, string>,
+    signal?: AbortSignal,
+  ) {
+    // Create a cache key that includes both URL and headers
+    const cacheKey = headers
+      ? `${mediaUrl}:${JSON.stringify(headers)}`
+      : mediaUrl;
+
+    const cached = mediaCache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const promise = this.host
+      .fetch(mediaUrl, { headers, signal })
+      .then((response) => response.arrayBuffer());
+    mediaCache.set(cacheKey, promise);
+    return promise;
+  }
+
+  /**
+   * Calculate audio segments needed for a time range
+   * Each media engine implements this based on their segment structure
+   */
+  calculateAudioSegmentRange(
+    fromMs: number,
+    toMs: number,
+    rendition: AudioRendition,
+    durationMs: number,
+  ): SegmentTimeRange[] {
+    // Default implementation for uniform segments (used by JitMediaEngine)
+    if (fromMs >= toMs) {
+      return [];
+    }
+
+    const segments: SegmentTimeRange[] = [];
+
+    // Use actual segment durations if available (more accurate)
+    if (
+      rendition.segmentDurationsMs &&
+      rendition.segmentDurationsMs.length > 0
+    ) {
+      let cumulativeTime = 0;
+
+      for (let i = 0; i < rendition.segmentDurationsMs.length; i++) {
+        const segmentDuration = rendition.segmentDurationsMs[i];
+        if (segmentDuration === undefined) {
+          continue; // Skip undefined segment durations
+        }
+        const segmentStartMs = cumulativeTime;
+        const segmentEndMs = Math.min(
+          cumulativeTime + segmentDuration,
+          durationMs,
+        );
+
+        // Don't include segments that start at or beyond the file duration
+        if (segmentStartMs >= durationMs) {
+          break;
+        }
+
+        // Only include segments that overlap with requested time range
+        if (segmentStartMs < toMs && segmentEndMs > fromMs) {
+          segments.push({
+            segmentId: i + 1, // Convert to 1-based
+            startMs: segmentStartMs,
+            endMs: segmentEndMs,
+          });
+        }
+
+        cumulativeTime += segmentDuration;
+
+        // If we've reached or exceeded file duration, stop
+        if (cumulativeTime >= durationMs) {
+          break;
+        }
+      }
+
+      return segments;
+    }
+
+    // Fall back to fixed duration calculation for backward compatibility
+    const segmentDurationMs = rendition.segmentDurationMs || 1000;
+    const startSegmentIndex = Math.floor(fromMs / segmentDurationMs);
+    const endSegmentIndex = Math.floor(toMs / segmentDurationMs);
+
+    for (let i = startSegmentIndex; i <= endSegmentIndex; i++) {
+      const segmentId = i + 1; // Convert to 1-based
+      const segmentStartMs = i * segmentDurationMs;
+      const segmentEndMs = Math.min((i + 1) * segmentDurationMs, durationMs);
+
+      // Don't include segments that start at or beyond the file duration
+      if (segmentStartMs >= durationMs) {
+        break;
+      }
+
+      // Only include segments that overlap with requested time range
+      if (segmentStartMs < toMs && segmentEndMs > fromMs) {
+        segments.push({
+          segmentId,
+          startMs: segmentStartMs,
+          endMs: segmentEndMs,
+        });
+      }
+    }
+
+    return segments;
+  }
+}