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

package/src/elements/EFMedia/shared/RenditionHelpers.browsertest.ts

@@ -0,0 +1,247 @@
+import { test as baseTest, describe, vi } from "vitest";
+import type {
+  AudioRendition,
+  MediaEngine,
+  VideoRendition,
+} from "../../../transcoding/types";
+import {
+  calculateSegmentRange,
+  computeSegmentId,
+  getAudioRendition,
+  getVideoRendition,
+} from "./RenditionHelpers";
+
+const test = baseTest.extend<{
+  mockMediaEngine: MediaEngine;
+  mockVideoRendition: VideoRendition;
+  mockAudioRendition: AudioRendition;
+  mockMediaEngineWithoutAudio: MediaEngine;
+  mockMediaEngineWithoutVideo: MediaEngine;
+}>({
+  mockMediaEngine: async ({}, use) => {
+    const mockVideoRendition = {
+      trackId: 1,
+      src: "video-track.mp4",
+      segmentDurationMs: 1000,
+    } as VideoRendition;
+
+    const mockAudioRendition = {
+      trackId: 2,
+      src: "audio-track.mp4",
+      segmentDurationMs: 1000,
+    } as AudioRendition;
+
+    const mockMediaEngine = {
+      durationMs: 10000,
+      src: "https://example.com/media.mp4",
+      videoRendition: mockVideoRendition,
+      audioRendition: mockAudioRendition,
+      fetchMediaSegment: vi.fn(),
+    } as unknown as MediaEngine;
+    await use(mockMediaEngine);
+  },
+
+  mockVideoRendition: async ({}, use) => {
+    const mockVideoRendition = {
+      trackId: 1,
+      src: "video-track.mp4",
+      segmentDurationMs: 1000,
+    } as VideoRendition;
+    await use(mockVideoRendition);
+  },
+
+  mockAudioRendition: async ({}, use) => {
+    const mockAudioRendition = {
+      trackId: 2,
+      src: "audio-track.mp4",
+      segmentDurationMs: 1000,
+    } as AudioRendition;
+    await use(mockAudioRendition);
+  },
+
+  mockMediaEngineWithoutAudio: async ({}, use) => {
+    const mockMediaEngine = {
+      durationMs: 10000,
+      src: "https://example.com/media.mp4",
+      videoRendition: {
+        trackId: 1,
+        src: "video-track.mp4",
+        segmentDurationMs: 1000,
+      } as VideoRendition,
+      audioRendition: null,
+      fetchMediaSegment: vi.fn(),
+    } as unknown as MediaEngine;
+    await use(mockMediaEngine);
+  },
+
+  mockMediaEngineWithoutVideo: async ({}, use) => {
+    const mockMediaEngine = {
+      durationMs: 10000,
+      src: "https://example.com/media.mp4",
+      videoRendition: null,
+      audioRendition: {
+        trackId: 2,
+        src: "audio-track.mp4",
+        segmentDurationMs: 1000,
+      } as AudioRendition,
+      fetchMediaSegment: vi.fn(),
+    } as unknown as MediaEngine;
+    await use(mockMediaEngine);
+  },
+});
+
+describe("RenditionHelpers", () => {
+  describe("getAudioRendition", () => {
+    test("returns audio rendition when available", ({
+      mockMediaEngine,
+      expect,
+    }) => {
+      const result = getAudioRendition(mockMediaEngine);
+      expect(result).toBe(mockMediaEngine.audioRendition);
+      expect(result.trackId).toBe(2);
+      expect(result.src).toBe("audio-track.mp4");
+    });
+
+    test("throws error when audio rendition is not available", ({
+      mockMediaEngineWithoutAudio,
+      expect,
+    }) => {
+      expect(() => getAudioRendition(mockMediaEngineWithoutAudio)).toThrow(
+        "Audio rendition is not available",
+      );
+    });
+  });
+
+  describe("getVideoRendition", () => {
+    test("returns video rendition when available", ({
+      mockMediaEngine,
+      expect,
+    }) => {
+      const result = getVideoRendition(mockMediaEngine);
+      expect(result).toBe(mockMediaEngine.videoRendition);
+      expect(result.trackId).toBe(1);
+      expect(result.src).toBe("video-track.mp4");
+    });
+
+    test("throws error when video rendition is not available", ({
+      mockMediaEngineWithoutVideo,
+      expect,
+    }) => {
+      expect(() => getVideoRendition(mockMediaEngineWithoutVideo)).toThrow(
+        "Video rendition is not available",
+      );
+    });
+  });
+
+  describe("computeSegmentId", () => {
+    test("calculates segment ID correctly for audio rendition", ({
+      mockAudioRendition,
+      expect,
+    }) => {
+      // Test various time points
+      expect(computeSegmentId(0, mockAudioRendition)).toBe(1); // First segment
+      expect(computeSegmentId(500, mockAudioRendition)).toBe(1); // Still first segment
+      expect(computeSegmentId(999, mockAudioRendition)).toBe(1); // Still first segment
+      expect(computeSegmentId(1000, mockAudioRendition)).toBe(2); // Second segment
+      expect(computeSegmentId(1500, mockAudioRendition)).toBe(2); // Still second segment
+      expect(computeSegmentId(2000, mockAudioRendition)).toBe(3); // Third segment
+    });
+
+    test("calculates segment ID correctly for video rendition", ({
+      mockVideoRendition,
+      expect,
+    }) => {
+      // Test various time points
+      expect(computeSegmentId(0, mockVideoRendition)).toBe(1); // First segment
+      expect(computeSegmentId(999, mockVideoRendition)).toBe(1); // Still first segment
+      expect(computeSegmentId(1000, mockVideoRendition)).toBe(2); // Second segment
+      expect(computeSegmentId(2500, mockVideoRendition)).toBe(3); // Third segment
+    });
+
+    test("returns undefined when segmentDurationMs is not available", ({
+      expect,
+    }) => {
+      const renditionWithoutDuration = {
+        trackId: 1,
+        src: "test.mp4",
+        segmentDurationMs: undefined,
+      } as AudioRendition;
+
+      expect(computeSegmentId(1000, renditionWithoutDuration)).toBeUndefined();
+    });
+
+    test("handles edge case of negative time", ({
+      mockAudioRendition,
+      expect,
+    }) => {
+      expect(computeSegmentId(-100, mockAudioRendition)).toBe(1); // Should clamp to segment 1
+    });
+  });
+
+  describe("calculateSegmentRange", () => {
+    test("calculates segment range for single segment", ({
+      mockAudioRendition,
+      expect,
+    }) => {
+      const result = calculateSegmentRange(100, 800, mockAudioRendition);
+      expect(result).toEqual([1]);
+    });
+
+    test("calculates segment range spanning multiple segments", ({
+      mockAudioRendition,
+      expect,
+    }) => {
+      const result = calculateSegmentRange(500, 2500, mockAudioRendition);
+      expect(result).toEqual([1, 2, 3]);
+    });
+
+    test("calculates segment range for exact segment boundaries", ({
+      mockAudioRendition,
+      expect,
+    }) => {
+      const result = calculateSegmentRange(1000, 2000, mockAudioRendition);
+      expect(result).toEqual([2, 3]);
+    });
+
+    test("handles single time point (start equals end)", ({
+      mockAudioRendition,
+      expect,
+    }) => {
+      const result = calculateSegmentRange(1500, 1500, mockAudioRendition);
+      expect(result).toEqual([2]);
+    });
+
+    test("returns empty array when segmentDurationMs is not available", ({
+      expect,
+    }) => {
+      const renditionWithoutDuration = {
+        trackId: 1,
+        src: "test.mp4",
+        segmentDurationMs: undefined,
+      } as AudioRendition;
+
+      const result = calculateSegmentRange(
+        1000,
+        2000,
+        renditionWithoutDuration,
+      );
+      expect(result).toEqual([]);
+    });
+
+    test("works with video renditions too", ({
+      mockVideoRendition,
+      expect,
+    }) => {
+      const result = calculateSegmentRange(1500, 3500, mockVideoRendition);
+      expect(result).toEqual([2, 3, 4]);
+    });
+
+    test("handles edge case where start time is negative", ({
+      mockAudioRendition,
+      expect,
+    }) => {
+      const result = calculateSegmentRange(-500, 1500, mockAudioRendition);
+      expect(result).toEqual([1, 2]);
+    });
+  });
+});

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

@@ -0,0 +1,79 @@
+import type {
+  AudioRendition,
+  MediaEngine,
+  VideoRendition,
+} from "../../../transcoding/types";
+
+/**
+ * Get audio rendition from media engine, throwing if not available
+ */
+export const getAudioRendition = (mediaEngine: MediaEngine): AudioRendition => {
+  const audioRendition = mediaEngine.audioRendition;
+  if (!audioRendition) {
+    throw new Error("Audio rendition is not available");
+  }
+  return audioRendition;
+};
+
+/**
+ * Get video rendition from media engine, throwing if not available
+ */
+export const getVideoRendition = (mediaEngine: MediaEngine): VideoRendition => {
+  const videoRendition = mediaEngine.videoRendition;
+  if (!videoRendition) {
+    throw new Error("Video rendition is not available");
+  }
+  return videoRendition;
+};
+
+/**
+ * Calculate which segment contains a given timestamp
+ * Returns 1-based segment ID, or undefined if segmentDurationMs is not available
+ */
+export const computeSegmentId = (
+  timeMs: number,
+  rendition: AudioRendition | VideoRendition,
+): number | undefined => {
+  if (!rendition.segmentDurationMs) {
+    return undefined;
+  }
+
+  // Handle negative time by clamping to 0
+  const adjustedTimeMs = Math.max(0, timeMs);
+  const segmentIndex = Math.floor(adjustedTimeMs / rendition.segmentDurationMs);
+  return segmentIndex + 1; // Convert to 1-based segment ID
+};
+
+/**
+ * Calculate range of segment IDs that overlap with a time range
+ * Returns array of 1-based segment IDs, or empty array if segmentDurationMs is not available
+ */
+export const calculateSegmentRange = (
+  startTimeMs: number,
+  endTimeMs: number,
+  rendition: AudioRendition | VideoRendition,
+): number[] => {
+  if (!rendition.segmentDurationMs) {
+    return [];
+  }
+
+  // Handle edge case where start equals end
+  if (startTimeMs === endTimeMs) {
+    const segmentId = computeSegmentId(startTimeMs, rendition);
+    return segmentId ? [segmentId] : [];
+  }
+
+  const startSegmentId = computeSegmentId(startTimeMs, rendition);
+  const endSegmentId = computeSegmentId(endTimeMs, rendition);
+
+  if (startSegmentId === undefined || endSegmentId === undefined) {
+    return [];
+  }
+
+  const segments: number[] = [];
+  for (let segmentId = startSegmentId; segmentId <= endSegmentId; segmentId++) {
+    segments.push(segmentId);
+  }
+
+  return segments;
+};

package/src/elements/EFMedia/tasks/makeMediaEngineTask.browsertest.ts

@@ -0,0 +1,128 @@
+import { test as baseTest, describe, vi } from "vitest";
+import type { UrlGenerator } from "../../../transcoding/utils/UrlGenerator";
+import {
+  createMediaEngine,
+  handleMediaEngineComplete,
+} from "./makeMediaEngineTask";
+
+// Define test fixtures using test.extend
+const test = baseTest.extend<{
+  mockUrlGenerator: UrlGenerator;
+  mockHost: any;
+  mockTimegroup: any;
+}>({
+  mockUrlGenerator: async ({}, use) => {
+    const mockUrlGenerator = {
+      generateManifestUrl: vi
+        .fn()
+        .mockReturnValue("https://example.com/manifest.m3u8"),
+    } as any;
+    await use(mockUrlGenerator);
+  },
+
+  mockTimegroup: async ({}, use) => {
+    const mockTimegroup = {
+      currentTimeMs: 0,
+      requestUpdate: vi.fn(),
+    };
+    await use(mockTimegroup);
+  },
+
+  mockHost: async ({ mockTimegroup, mockUrlGenerator }, use) => {
+    const mockHost = {
+      src: "https://example.com/video.mp4",
+      assetId: null,
+      urlGenerator: mockUrlGenerator,
+      apiHost: "https://api.example.com",
+      requestUpdate: vi.fn(),
+      rootTimegroup: mockTimegroup,
+    };
+    await use(mockHost);
+  },
+});
+
+describe("createMediaEngine", () => {
+  describe("input validation", () => {
+    test("should reject when assetId provided but apiHost is missing", async ({
+      mockHost,
+      expect,
+    }) => {
+      // Set up host with assetId but no apiHost
+      mockHost.src = "test.mp4";
+      mockHost.assetId = "asset123";
+      mockHost.apiHost = null;
+
+      await expect(createMediaEngine(mockHost)).rejects.toThrow(
+        "API host is required for AssetID mode",
+      );
+    });
+
+    test("should reject with empty src", async ({ mockHost, expect }) => {
+      // Set up host with empty src
+      mockHost.src = "";
+      mockHost.assetId = null;
+
+      await expect(createMediaEngine(mockHost)).rejects.toThrow(
+        "Unsupported media source",
+      );
+    });
+
+    test("should reject with null src", async ({ mockHost, expect }) => {
+      // Set up host with null src
+      mockHost.src = null;
+      mockHost.assetId = null;
+
+      await expect(createMediaEngine(mockHost)).rejects.toThrow(
+        "Unsupported media source",
+      );
+    });
+
+    test("should reject with whitespace-only src", async ({
+      mockHost,
+      expect,
+    }) => {
+      // Set up host with whitespace-only src
+      mockHost.src = "   \t\n  ";
+      mockHost.assetId = null;
+
+      await expect(createMediaEngine(mockHost)).rejects.toThrow(
+        "Unsupported media source",
+      );
+    });
+  });
+});
+
+describe("handleMediaEngineComplete", () => {
+  test("should call requestUpdate on host", async ({ mockHost, expect }) => {
+    handleMediaEngineComplete(mockHost);
+
+    expect(mockHost.requestUpdate).toHaveBeenCalledWith("intrinsicDurationMs");
+    expect(mockHost.requestUpdate).toHaveBeenCalledWith("ownCurrentTimeMs");
+  });
+
+  test("should call requestUpdate on rootTimegroup when present", async ({
+    mockHost,
+    mockTimegroup,
+    expect,
+  }) => {
+    handleMediaEngineComplete(mockHost);
+
+    expect(mockTimegroup.requestUpdate).toHaveBeenCalledWith(
+      "ownCurrentTimeMs",
+    );
+    expect(mockTimegroup.requestUpdate).toHaveBeenCalledWith("durationMs");
+  });
+
+  test("should handle missing rootTimegroup gracefully", async ({
+    mockHost,
+    expect,
+  }) => {
+    mockHost.rootTimegroup = null;
+
+    // Should not throw
+    handleMediaEngineComplete(mockHost);
+
+    expect(mockHost.requestUpdate).toHaveBeenCalledWith("intrinsicDurationMs");
+    expect(mockHost.requestUpdate).toHaveBeenCalledWith("ownCurrentTimeMs");
+  });
+});

package/src/elements/EFMedia/tasks/makeMediaEngineTask.test.ts

@@ -0,0 +1,233 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { EFMedia } from "../../EFMedia";
+import { AssetIdMediaEngine } from "../AssetIdMediaEngine";
+import { AssetMediaEngine } from "../AssetMediaEngine";
+import { JitMediaEngine } from "../JitMediaEngine";
+import { createMediaEngine } from "./makeMediaEngineTask";
+
+// Mock the engine classes
+vi.mock("../AssetIdMediaEngine", () => ({
+  AssetIdMediaEngine: {
+    fetchByAssetId: vi.fn(),
+  },
+}));
+vi.mock("../AssetMediaEngine");
+vi.mock("../JitMediaEngine");
+
+describe("makeMediaEngineTask", () => {
+  const mockUrlGenerator = {
+    generateManifestUrl: vi.fn(),
+  };
+
+  const createMockHost = (overrides: Partial<EFMedia> = {}): EFMedia =>
+    ({
+      src: "",
+      assetId: null,
+      apiHost: "https://api.example.com",
+      urlGenerator: mockUrlGenerator,
+      ...overrides,
+    }) as EFMedia;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("createMediaEngine", () => {
+    it("should use AssetIdMediaEngine when assetId is provided", async () => {
+      const mockEngine = { durationMs: 15000 };
+      vi.mocked(AssetIdMediaEngine.fetchByAssetId).mockResolvedValue(
+        mockEngine as any,
+      );
+
+      const host = createMockHost({
+        assetId: "test-asset-123",
+        apiHost: "https://api.example.com",
+      });
+
+      const result = await createMediaEngine(host);
+
+      expect(AssetIdMediaEngine.fetchByAssetId).toHaveBeenCalledWith(
+        host,
+        mockUrlGenerator,
+        "test-asset-123",
+        "https://api.example.com",
+      );
+      expect(result).toBe(mockEngine);
+    });
+
+    it("should throw error when assetId is provided but apiHost is missing", async () => {
+      const host = createMockHost({
+        assetId: "test-asset-123",
+        apiHost: undefined,
+      });
+
+      await expect(createMediaEngine(host)).rejects.toThrow(
+        "API host is required for AssetID mode",
+      );
+    });
+
+    it("should ignore empty assetId and use src instead", async () => {
+      const mockEngine = { durationMs: 15000 };
+      vi.mocked(AssetMediaEngine.fetch).mockResolvedValue(mockEngine as any);
+
+      const host = createMockHost({
+        assetId: "",
+        src: "/path/to/asset",
+      });
+
+      const result = await createMediaEngine(host);
+
+      expect(AssetMediaEngine.fetch).toHaveBeenCalledWith(
+        host,
+        mockUrlGenerator,
+        "/path/to/asset",
+      );
+      expect(AssetIdMediaEngine.fetchByAssetId).not.toHaveBeenCalled();
+      expect(result).toBe(mockEngine);
+    });
+
+    it("should ignore whitespace-only assetId and use src instead", async () => {
+      const mockEngine = { durationMs: 15000 };
+      vi.mocked(AssetMediaEngine.fetch).mockResolvedValue(mockEngine as any);
+
+      const host = createMockHost({
+        assetId: "   ",
+        src: "/path/to/asset",
+      });
+
+      const result = await createMediaEngine(host);
+
+      expect(AssetMediaEngine.fetch).toHaveBeenCalledWith(
+        host,
+        mockUrlGenerator,
+        "/path/to/asset",
+      );
+      expect(AssetIdMediaEngine.fetchByAssetId).not.toHaveBeenCalled();
+      expect(result).toBe(mockEngine);
+    });
+
+    it("should use JitMediaEngine for HTTP URLs", async () => {
+      const mockEngine = { durationMs: 15000 };
+      const manifestUrl = "https://api.example.com/manifest.json";
+
+      vi.mocked(mockUrlGenerator.generateManifestUrl).mockReturnValue(
+        manifestUrl,
+      );
+      vi.mocked(JitMediaEngine.fetch).mockResolvedValue(mockEngine as any);
+
+      const host = createMockHost({
+        src: "https://example.com/video.mp4",
+      });
+
+      const result = await createMediaEngine(host);
+
+      expect(mockUrlGenerator.generateManifestUrl).toHaveBeenCalledWith(
+        "https://example.com/video.mp4",
+      );
+      expect(JitMediaEngine.fetch).toHaveBeenCalledWith(
+        host,
+        mockUrlGenerator,
+        manifestUrl,
+      );
+      expect(result).toBe(mockEngine);
+    });
+
+    it("should use JitMediaEngine for HTTPS URLs", async () => {
+      const mockEngine = { durationMs: 15000 };
+      const manifestUrl = "https://api.example.com/manifest.json";
+
+      vi.mocked(mockUrlGenerator.generateManifestUrl).mockReturnValue(
+        manifestUrl,
+      );
+      vi.mocked(JitMediaEngine.fetch).mockResolvedValue(mockEngine as any);
+
+      const host = createMockHost({
+        src: "https://example.com/video.mp4",
+      });
+
+      const result = await createMediaEngine(host);
+
+      expect(JitMediaEngine.fetch).toHaveBeenCalledWith(
+        host,
+        mockUrlGenerator,
+        manifestUrl,
+      );
+      expect(result).toBe(mockEngine);
+    });
+
+    it("should use AssetMediaEngine for local paths", async () => {
+      const mockEngine = { durationMs: 15000 };
+      vi.mocked(AssetMediaEngine.fetch).mockResolvedValue(mockEngine as any);
+
+      const host = createMockHost({
+        src: "/local/asset.mp4",
+      });
+
+      const result = await createMediaEngine(host);
+
+      expect(AssetMediaEngine.fetch).toHaveBeenCalledWith(
+        host,
+        mockUrlGenerator,
+        "/local/asset.mp4",
+      );
+      expect(result).toBe(mockEngine);
+    });
+
+    it("should throw error for empty src when no assetId", async () => {
+      const host = createMockHost({
+        src: "",
+        assetId: null,
+      });
+
+      await expect(createMediaEngine(host)).rejects.toThrow(
+        "Unsupported media source",
+      );
+    });
+
+    it("should throw error for whitespace-only src when no assetId", async () => {
+      const host = createMockHost({
+        src: "   ",
+        assetId: null,
+      });
+
+      await expect(createMediaEngine(host)).rejects.toThrow(
+        "Unsupported media source",
+      );
+    });
+
+    it("should throw error for null src when no assetId", async () => {
+      const host = createMockHost({
+        src: null as any,
+        assetId: null,
+      });
+
+      await expect(createMediaEngine(host)).rejects.toThrow(
+        "Unsupported media source",
+      );
+    });
+
+    it("should prioritize assetId over src when both are provided", async () => {
+      const mockEngine = { durationMs: 15000 };
+      vi.mocked(AssetIdMediaEngine.fetchByAssetId).mockResolvedValue(
+        mockEngine as any,
+      );
+
+      const host = createMockHost({
+        assetId: "test-asset-123",
+        src: "/local/asset.mp4",
+        apiHost: "https://api.example.com",
+      });
+
+      const result = await createMediaEngine(host);
+
+      expect(AssetIdMediaEngine.fetchByAssetId).toHaveBeenCalledWith(
+        host,
+        mockUrlGenerator,
+        "test-asset-123",
+        "https://api.example.com",
+      );
+      expect(AssetMediaEngine.fetch).not.toHaveBeenCalled();
+      expect(result).toBe(mockEngine);
+    });
+  });
+});