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

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

@@ -0,0 +1,222 @@
+import type { TrackFragmentIndex } from "@editframe/assets";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { UrlGenerator } from "../../transcoding/utils/UrlGenerator";
+import type { EFMedia } from "../EFMedia";
+import { AssetIdMediaEngine } from "./AssetIdMediaEngine";
+
+describe("AssetIdMediaEngine", () => {
+  const mockApiHost = "https://api.example.com";
+  const mockAssetId = "test-asset-123";
+  const mockUrlGenerator = new UrlGenerator(() => "https://api.example.com");
+
+  const mockTrackFragmentData: Record<number, TrackFragmentIndex> = {
+    1: {
+      track: 1,
+      type: "audio",
+      duration: 15000,
+      timescale: 1000,
+      channel_count: 2,
+      sample_rate: 44100,
+      sample_size: 16,
+      sample_count: 1000,
+      codec: "mp4a.40.2",
+      initSegment: {
+        offset: 0,
+        size: 1024,
+      },
+      segments: [
+        {
+          cts: 0,
+          dts: 0,
+          duration: 1000,
+          offset: 1024,
+          size: 2048,
+        },
+        {
+          cts: 1000,
+          dts: 1000,
+          duration: 1000,
+          offset: 3072,
+          size: 2048,
+        },
+      ],
+    },
+    2: {
+      track: 2,
+      type: "video",
+      duration: 15000,
+      timescale: 1000,
+      width: 1920,
+      height: 1080,
+      sample_count: 1500,
+      codec: "avc1.640029",
+      initSegment: {
+        offset: 0,
+        size: 2048,
+      },
+      segments: [
+        {
+          cts: 0,
+          dts: 0,
+          duration: 1000,
+          offset: 7168,
+          size: 4096,
+        },
+        {
+          cts: 1000,
+          dts: 1000,
+          duration: 1000,
+          offset: 11264,
+          size: 4096,
+        },
+      ],
+    },
+  };
+
+  let engine: AssetIdMediaEngine;
+  let host: EFMedia;
+
+  beforeEach(() => {
+    // Create a mock host instead of instantiating EFMedia directly
+    host = {
+      fetch: vi.fn().mockResolvedValue({
+        json: vi.fn().mockResolvedValue(mockTrackFragmentData),
+      }),
+    } as any;
+    engine = new AssetIdMediaEngine(
+      host,
+      mockAssetId,
+      mockTrackFragmentData,
+      mockApiHost,
+    );
+  });
+
+  describe("constructor", () => {
+    it("should initialize with correct duration", () => {
+      expect(engine.durationMs).toBe(15000);
+    });
+
+    it("should set assetId correctly", () => {
+      expect(engine.assetId).toBe(mockAssetId);
+    });
+
+    it("should expose assetId as src for MediaEngine interface compatibility", () => {
+      expect(engine.src).toBe(mockAssetId);
+    });
+  });
+
+  describe("track access", () => {
+    it("should find audio track", () => {
+      const audioTrack = engine.audioTrackIndex;
+      expect(audioTrack).toBeDefined();
+      expect(audioTrack?.type).toBe("audio");
+      expect(audioTrack?.track).toBe(1);
+    });
+
+    it("should find video track", () => {
+      const videoTrack = engine.videoTrackIndex;
+      expect(videoTrack).toBeDefined();
+      expect(videoTrack?.type).toBe("video");
+      expect(videoTrack?.track).toBe(2);
+    });
+
+    it("should return correct audio rendition", () => {
+      const audioRendition = engine.audioRendition;
+      expect(audioRendition.trackId).toBe(1);
+      expect(audioRendition.src).toBe(mockAssetId);
+    });
+
+    it("should return correct video rendition", () => {
+      const videoRendition = engine.videoRendition;
+      expect(videoRendition.trackId).toBe(2);
+      expect(videoRendition.src).toBe(mockAssetId);
+    });
+  });
+
+  describe("URL generation", () => {
+    it("should generate correct init segment URLs", () => {
+      const url = engine.buildInitSegmentUrl(1);
+      expect(url).toBe(`${mockApiHost}/api/v1/isobmff_tracks/${mockAssetId}/1`);
+    });
+
+    it("should generate correct media segment URLs", () => {
+      const url = engine.buildMediaSegmentUrl(1, 0);
+      expect(url).toBe(`${mockApiHost}/api/v1/isobmff_tracks/${mockAssetId}/1`);
+    });
+
+    it("should return correct templates", () => {
+      const templates = engine.templates;
+      expect(templates.initSegment).toBe(
+        `${mockApiHost}/api/v1/isobmff_tracks/${mockAssetId}/{trackId}`,
+      );
+      expect(templates.mediaSegment).toBe(
+        `${mockApiHost}/api/v1/isobmff_tracks/${mockAssetId}/{trackId}`,
+      );
+    });
+
+    it("should return correct init segment paths", () => {
+      const paths = engine.initSegmentPaths;
+      expect(paths.audio?.path).toBe(
+        `${mockApiHost}/api/v1/isobmff_tracks/${mockAssetId}/1`,
+      );
+      expect(paths.video?.path).toBe(
+        `${mockApiHost}/api/v1/isobmff_tracks/${mockAssetId}/2`,
+      );
+    });
+  });
+
+  describe("segment calculations", () => {
+    it("should calculate audio segment ranges correctly", () => {
+      const ranges = engine.calculateAudioSegmentRange(
+        500,
+        1500,
+        { trackId: 1, src: mockAssetId },
+        15000,
+      );
+      expect(ranges).toHaveLength(2);
+      expect(ranges[0]?.segmentId).toBe(0);
+      expect(ranges[1]?.segmentId).toBe(1);
+    });
+
+    it("should compute segment ID correctly", () => {
+      const segmentId = engine.computeSegmentId(500, {
+        trackId: 1,
+        src: mockAssetId,
+      });
+      expect(segmentId).toBe(0);
+
+      const segmentId2 = engine.computeSegmentId(1500, {
+        trackId: 1,
+        src: mockAssetId,
+      });
+      expect(segmentId2).toBe(1);
+    });
+  });
+
+  describe("static fetch method", () => {
+    it("should create engine from API response", async () => {
+      // Mock the host's fetch method
+      const mockFetch = vi.fn().mockResolvedValue({
+        json: vi.fn().mockResolvedValue(mockTrackFragmentData),
+      });
+
+      const mockHost = {
+        fetch: mockFetch,
+      } as any;
+
+      const fetchedEngine = await AssetIdMediaEngine.fetchByAssetId(
+        mockHost,
+        mockUrlGenerator,
+        mockAssetId,
+        mockApiHost,
+      );
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        `${mockApiHost}/api/v1/isobmff_files/${mockAssetId}/index`,
+      );
+      expect(fetchedEngine.assetId).toBe(mockAssetId);
+      expect(fetchedEngine.durationMs).toBe(15000);
+      expect(fetchedEngine.audioTrackIndex?.track).toBe(1);
+    });
+  });
+});

package/src/elements/EFMedia/AssetIdMediaEngine.ts

@@ -0,0 +1,70 @@
+import type { TrackFragmentIndex } from "@editframe/assets";
+import type { InitSegmentPaths, MediaEngine } from "../../transcoding/types";
+import type { UrlGenerator } from "../../transcoding/utils/UrlGenerator";
+import type { EFMedia } from "../EFMedia";
+import { AssetMediaEngine } from "./AssetMediaEngine";
+
+export class AssetIdMediaEngine
+  extends AssetMediaEngine
+  implements MediaEngine
+{
+  static async fetchByAssetId(
+    host: EFMedia,
+    _urlGenerator: UrlGenerator,
+    assetId: string,
+    apiHost: string,
+  ) {
+    const url = `${apiHost}/api/v1/isobmff_files/${assetId}/index`;
+    const response = await host.fetch(url);
+    const data = (await response.json()) as Record<number, TrackFragmentIndex>;
+    return new AssetIdMediaEngine(host, assetId, data, apiHost);
+  }
+
+  constructor(
+    host: EFMedia,
+    public assetId: string,
+    data: Record<number, TrackFragmentIndex>,
+    private apiHost: string,
+  ) {
+    // Pass assetId as src to parent constructor for compatibility
+    super(host, assetId, data);
+  }
+
+  // Override URL-building methods to use API endpoints instead of file paths
+  get initSegmentPaths() {
+    const paths: InitSegmentPaths = {};
+
+    if (this.audioTrackIndex !== undefined) {
+      paths.audio = {
+        path: `${this.apiHost}/api/v1/isobmff_tracks/${this.assetId}/${this.audioTrackIndex.track}`,
+        pos: this.audioTrackIndex.initSegment.offset,
+        size: this.audioTrackIndex.initSegment.size,
+      };
+    }
+
+    if (this.videoTrackIndex !== undefined) {
+      paths.video = {
+        path: `${this.apiHost}/api/v1/isobmff_tracks/${this.assetId}/${this.videoTrackIndex.track}`,
+        pos: this.videoTrackIndex.initSegment.offset,
+        size: this.videoTrackIndex.initSegment.size,
+      };
+    }
+
+    return paths;
+  }
+
+  get templates() {
+    return {
+      initSegment: `${this.apiHost}/api/v1/isobmff_tracks/${this.assetId}/{trackId}`,
+      mediaSegment: `${this.apiHost}/api/v1/isobmff_tracks/${this.assetId}/{trackId}`,
+    };
+  }
+
+  buildInitSegmentUrl(trackId: number) {
+    return `${this.apiHost}/api/v1/isobmff_tracks/${this.assetId}/${trackId}`;
+  }
+
+  buildMediaSegmentUrl(trackId: number, _segmentId: number) {
+    return `${this.apiHost}/api/v1/isobmff_tracks/${this.assetId}/${trackId}`;
+  }
+}

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);
+  });
+});