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

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

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

@@ -0,0 +1,89 @@
+import { Task } from "@lit/task";
+import { EF_INTERACTIVE } from "../../../EF_INTERACTIVE";
+import type { MediaEngine, VideoRendition } from "../../../transcoding/types";
+import type { EFMedia } from "../../EFMedia";
+import { AssetIdMediaEngine } from "../AssetIdMediaEngine";
+import { AssetMediaEngine } from "../AssetMediaEngine";
+import { JitMediaEngine } from "../JitMediaEngine";
+
+export const getLatestMediaEngine = async (
+  host: EFMedia,
+  signal: AbortSignal,
+): Promise<MediaEngine> => {
+  const mediaEngine = await host.mediaEngineTask.taskComplete;
+  signal.throwIfAborted();
+  if (!mediaEngine) {
+    throw new Error("Media engine is not available");
+  }
+  return mediaEngine;
+};
+
+export const getVideoRendition = (mediaEngine: MediaEngine): VideoRendition => {
+  const videoRendition = mediaEngine.videoRendition;
+  if (!videoRendition) {
+    throw new Error("Video rendition is not available");
+  }
+  return videoRendition;
+};
+
+/**
+ * Core logic for creating a MediaEngine with explicit dependencies.
+ * Pure function that requires all dependencies to be provided.
+ */
+export const createMediaEngine = (host: EFMedia): Promise<MediaEngine> => {
+  const { src, assetId, urlGenerator, apiHost } = host;
+
+  // Check for AssetID mode first
+  if (assetId !== null && assetId !== undefined && assetId.trim() !== "") {
+    if (!apiHost) {
+      return Promise.reject(new Error("API host is required for AssetID mode"));
+    }
+    return AssetIdMediaEngine.fetchByAssetId(
+      host,
+      urlGenerator,
+      assetId,
+      apiHost,
+    );
+  }
+
+  // Check for null/undefined/empty/whitespace src
+  if (!src || typeof src !== "string" || src.trim() === "") {
+    console.error(`Unsupported media source: ${src}, assetId: ${assetId}`);
+    return Promise.reject(new Error("Unsupported media source"));
+  }
+
+  // Check for HTTP/HTTPS URLs (exactly "http://" or "https://")
+  const lowerSrc = src.toLowerCase();
+  if (lowerSrc.startsWith("http://") || lowerSrc.startsWith("https://")) {
+    const url = urlGenerator.generateManifestUrl(src);
+    return JitMediaEngine.fetch(host, urlGenerator, url);
+  }
+
+  return AssetMediaEngine.fetch(host, urlGenerator, src);
+};
+
+/**
+ * Handle completion of media engine task - triggers necessary updates.
+ * Extracted for testability.
+ */
+export const handleMediaEngineComplete = (host: EFMedia): void => {
+  host.requestUpdate("intrinsicDurationMs");
+  host.requestUpdate("ownCurrentTimeMs");
+  host.rootTimegroup?.requestUpdate("ownCurrentTimeMs");
+  host.rootTimegroup?.requestUpdate("durationMs");
+};
+
+type MediaEngineTask = Task<readonly [string, string | null], MediaEngine>;
+
+export const makeMediaEngineTask = (host: EFMedia): MediaEngineTask => {
+  return new Task(host, {
+    autoRun: EF_INTERACTIVE,
+    args: () => [host.src, host.assetId] as const,
+    task: async () => {
+      return createMediaEngine(host);
+    },
+    onComplete: (_value) => {
+      handleMediaEngineComplete(host);
+    },
+  });
+};