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

package/src/elements/EFMedia/AssetMediaEngine.ts

@@ -0,0 +1,210 @@
+import type { TrackFragmentIndex } from "@editframe/assets";
+
+import type {
+  AudioRendition,
+  InitSegmentPaths,
+  MediaEngine,
+  SegmentTimeRange,
+} from "../../transcoding/types";
+import type { UrlGenerator } from "../../transcoding/utils/UrlGenerator";
+import type { EFMedia } from "../EFMedia";
+import { BaseMediaEngine } from "./BaseMediaEngine";
+
+export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
+  static async fetch(host: EFMedia, urlGenerator: UrlGenerator, src: string) {
+    const url = urlGenerator.generateTrackFragmentIndexUrl(src);
+    const response = await host.fetch(url);
+    const data = (await response.json()) as Record<number, TrackFragmentIndex>;
+    if (src.startsWith("/")) {
+      src = src.slice(1);
+    }
+    return new AssetMediaEngine(host, src, data);
+  }
+  durationMs: number;
+
+  constructor(
+    public host: EFMedia,
+    public src: string,
+    protected data: Record<number, TrackFragmentIndex>,
+  ) {
+    super();
+    const longestFragment = Object.values(data).reduce(
+      (max, fragment) => Math.max(max, fragment.duration / fragment.timescale),
+      0,
+    );
+    this.durationMs = longestFragment * 1000;
+  }
+
+  get audioTrackIndex() {
+    return Object.values(this.data).find((track) => track.type === "audio");
+  }
+
+  get videoTrackIndex() {
+    return Object.values(this.data).find((track) => track.type === "video");
+  }
+
+  get videoRendition() {
+    return {
+      trackId: this.videoTrackIndex?.track,
+      src: this.src,
+      startTimeOffsetMs: this.videoTrackIndex?.startTimeOffsetMs,
+    };
+  }
+
+  get audioRendition() {
+    return {
+      trackId: this.audioTrackIndex?.track,
+      src: this.src,
+    };
+  }
+
+  get initSegmentPaths() {
+    const paths: InitSegmentPaths = {};
+
+    if (this.audioTrackIndex !== undefined) {
+      paths.audio = {
+        path: `@ef-track/${this.audioTrackIndex.track}.m4s`,
+        pos: this.audioTrackIndex.initSegment.offset,
+        size: this.audioTrackIndex.initSegment.size,
+      };
+    }
+
+    if (this.videoTrackIndex !== undefined) {
+      paths.video = {
+        path: `/@ef-track/${this.videoTrackIndex.track}.m4s`,
+        pos: this.videoTrackIndex.initSegment.offset,
+        size: this.videoTrackIndex.initSegment.size,
+      };
+    }
+
+    return paths;
+  }
+
+  get templates() {
+    return {
+      initSegment: "/@ef-track/{src}?trackId={trackId}",
+      mediaSegment: "/@ef-track/{src}?trackId={trackId}",
+    };
+  }
+
+  buildInitSegmentUrl(trackId: number) {
+    return `/@ef-track/${this.src}?trackId=${trackId}`;
+  }
+
+  buildMediaSegmentUrl(trackId: number, segmentId: number) {
+    return `/@ef-track/${this.src}?trackId=${trackId}&segmentId=${segmentId}`;
+  }
+
+  async fetchInitSegment(
+    rendition: { trackId: number | undefined; src: string },
+    signal: AbortSignal,
+  ) {
+    if (!rendition.trackId) {
+      throw new Error("Track ID is required for asset metadata");
+    }
+    const url = this.buildInitSegmentUrl(rendition.trackId);
+    const initSegment = this.data[rendition.trackId]?.initSegment;
+    if (!initSegment) {
+      throw new Error("Init segment not found");
+    }
+
+    // Use shared caching mechanism with Range headers - same optimization as JitMediaEngine
+    const headers = {
+      Range: `bytes=${initSegment.offset}-${initSegment.offset + initSegment.size - 1}`,
+    };
+
+    return this.fetchMediaCacheWithHeaders(url, headers, signal);
+  }
+
+  async fetchMediaSegmentImpl(
+    segmentId: number,
+    rendition: { trackId: number | undefined; src: string },
+    signal?: AbortSignal,
+  ) {
+    if (!rendition.trackId) {
+      throw new Error("Track ID is required for asset metadata");
+    }
+    if (segmentId === undefined) {
+      throw new Error("Segment ID is not available");
+    }
+    const url = this.buildMediaSegmentUrl(rendition.trackId, segmentId);
+    const mediaSegment = this.data[rendition.trackId]?.segments[segmentId];
+    if (!mediaSegment) {
+      throw new Error("Media segment not found");
+    }
+
+    // Use shared caching mechanism with Range headers - same optimization as JitMediaEngine
+    const headers = {
+      Range: `bytes=${mediaSegment.offset}-${mediaSegment.offset + mediaSegment.size - 1}`,
+    };
+
+    return this.fetchMediaCacheWithHeaders(url, headers, signal);
+  }
+
+  /**
+   * Calculate audio segments for variable-duration segments using track fragment index
+   */
+  calculateAudioSegmentRange(
+    fromMs: number,
+    toMs: number,
+    rendition: AudioRendition,
+    _durationMs: number,
+  ): SegmentTimeRange[] {
+    if (fromMs >= toMs || !rendition.trackId) {
+      return [];
+    }
+
+    const track = this.data[rendition.trackId];
+    if (!track) {
+      return [];
+    }
+
+    const { timescale, segments } = track;
+    const segmentRanges: SegmentTimeRange[] = [];
+
+    for (let i = 0; i < segments.length; i++) {
+      // biome-ignore lint/style/noNonNullAssertion: we know the segment is not null
+      const segment = segments[i]!;
+      const segmentStartTime = segment.cts;
+      const segmentEndTime = segment.cts + segment.duration;
+
+      // Convert to milliseconds
+      const segmentStartMs = (segmentStartTime / timescale) * 1000;
+      const segmentEndMs = (segmentEndTime / timescale) * 1000;
+
+      // Check if segment overlaps with requested time range
+      if (segmentStartMs < toMs && segmentEndMs > fromMs) {
+        segmentRanges.push({
+          segmentId: i, // AssetMediaEngine uses 0-based segment IDs
+          startMs: segmentStartMs,
+          endMs: segmentEndMs,
+        });
+      }
+    }
+
+    return segmentRanges;
+  }
+
+  computeSegmentId(
+    desiredSeekTimeMs: number,
+    rendition: { trackId: number | undefined; src: string },
+  ) {
+    if (!rendition.trackId) {
+      throw new Error("Track ID is required for asset metadata");
+    }
+    const track = this.data[rendition.trackId];
+    if (!track) {
+      throw new Error("Track not found");
+    }
+    const { timescale, segments } = track;
+    const desiredSeekTime = (desiredSeekTimeMs / 1000) * timescale;
+    for (let i = segments.length - 1; i >= 0; i--) {
+      // biome-ignore lint/style/noNonNullAssertion: we know the segment is not null
+      const segment = segments[i]!;
+      if (segment.cts <= desiredSeekTime) {
+        return i;
+      }
+    }
+    return 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,170 @@
+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 segmentDurationMs = rendition.segmentDurationMs || 1000;
+    const segments: SegmentTimeRange[] = [];
+
+    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);
+
+      // Only include segments that overlap with requested time range
+      if (segmentStartMs < toMs && segmentEndMs > fromMs) {
+        segments.push({
+          segmentId,
+          startMs: segmentStartMs,
+          endMs: segmentEndMs,
+        });
+      }
+    }
+
+    return segments;
+  }
+}