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

package/src/transcoding/cache/RequestDeduplicator.ts

@@ -0,0 +1,65 @@
+/**
+ * Request deduplication utility
+ * Manages pending requests to prevent concurrent duplicate requests
+ */
+
+export class RequestDeduplicator {
+  private pendingRequests = new Map<string, Promise<any>>();
+
+  /**
+   * Execute a request with deduplication
+   * If a request with the same key is already pending, return the existing promise
+   * Otherwise, execute the request factory and track the promise
+   */
+  async executeRequest<T>(
+    key: string,
+    requestFactory: () => Promise<T>,
+  ): Promise<T> {
+    // Check if there's already a pending request for this key
+    const existingRequest = this.pendingRequests.get(key);
+    if (existingRequest) {
+      return existingRequest;
+    }
+
+    // Create and track the new request
+    const requestPromise = requestFactory();
+    this.pendingRequests.set(key, requestPromise);
+
+    try {
+      const result = await requestPromise;
+      this.pendingRequests.delete(key);
+      return result;
+    } catch (error) {
+      this.pendingRequests.delete(key);
+      throw error;
+    }
+  }
+
+  /**
+   * Clear all pending requests (used in cache clearing)
+   */
+  clear(): void {
+    this.pendingRequests.clear();
+  }
+
+  /**
+   * Get number of pending requests
+   */
+  getPendingCount(): number {
+    return this.pendingRequests.size;
+  }
+
+  /**
+   * Check if a request is pending
+   */
+  isPending(key: string): boolean {
+    return this.pendingRequests.has(key);
+  }
+
+  /**
+   * Get all pending request keys
+   */
+  getPendingKeys(): string[] {
+    return Array.from(this.pendingRequests.keys());
+  }
+}

package/src/transcoding/types/index.ts

@@ -0,0 +1,265 @@
+/**
+ * Core types and interfaces for JIT Transcoding System
+ */
+
+export interface QualityPreset {
+  name: string;
+  width: number;
+  height: number;
+  videoBitrate: number;
+  audioBitrate: number;
+  audioChannels: number;
+  audioSampleRate: number;
+  audioCodec: "aac";
+}
+
+export type RenditionId = "high" | "medium" | "low" | "audio" | "scrub";
+
+export interface VideoMetadata {
+  url: string;
+  durationMs: number;
+  streams: Array<{
+    index: number;
+    type: "video" | "audio" | "subtitle" | "other";
+    codecName: string;
+    duration: number;
+    durationMs: number;
+    width?: number;
+    height?: number;
+    frameRate?: { num: number; den: number };
+    channels?: number;
+    sampleRate?: number;
+  }>;
+  presets: string[];
+  segmentDuration: number;
+  supportedFormats: string[];
+  extractedAt: string;
+}
+
+export interface JitTranscodingConfig {
+  baseUrl: string;
+  defaultQuality: keyof QualityPresets;
+  segmentCacheSize: number;
+  enableNetworkAdaptation: boolean;
+  enablePrefetch: boolean;
+  prefetchSegments: number;
+}
+
+export interface QualityPresets {
+  low: QualityPreset;
+  medium: QualityPreset;
+  high: QualityPreset;
+  scrub: QualityPreset;
+}
+
+export interface NetworkCondition {
+  bandwidth: number; // bits per second
+  rtt: number; // round trip time in ms
+  connectionType: string;
+}
+
+export interface SegmentInfo {
+  url: string;
+  startTimeMs: number;
+  durationMs: number;
+  quality: string;
+  cached: boolean;
+}
+
+export interface ManifestVideoRendition {
+  /** Unique identifier for the video rendition */
+  id: string; // "high", "medium", "low", "scrub"
+  /** Duration of each segment in milliseconds */
+  segmentDuration: number;
+  /** Duration of each segment in milliseconds */
+  segmentDurationMs: number;
+  /** Video width in pixels */
+  width: number;
+  /** Video height in pixels */
+  height: number;
+  /** Target bitrate in bits per second */
+  bitrate: number;
+  /** Video codec string (e.g., "avc1.640029") */
+  codec: string;
+  /** Container format (e.g., "video/mp4") */
+  container: string;
+  /** Complete MIME type with codecs */
+  mimeType: string; // 'video/mp4; codecs="avc1.640029,mp4a.40.2"'
+  /** Optional frame rate */
+  frameRate?: number;
+  /** Optional profile indication */
+  profile?: string;
+  /** Optional level indication */
+  level?: string;
+}
+
+export interface ManifestAudioRendition {
+  /** Unique identifier for the audio rendition */
+  id: string; // "audio"
+  /** Duration of each segment in milliseconds */
+  segmentDuration: number;
+  /** Duration of each segment in milliseconds */
+  segmentDurationMs: number;
+  /** Number of audio channels */
+  channels: number;
+  /** Sample rate in Hz */
+  sampleRate: number;
+  /** Target bitrate in bits per second */
+  bitrate: number;
+  /** Audio codec string (e.g., "mp4a.40.2") */
+  codec: string;
+  /** Container format (e.g., "audio/mp4") */
+  container: string;
+  /** Complete MIME type with codecs */
+  mimeType: string; // 'audio/mp4; codecs="mp4a.40.2"'
+  /** Optional language code */
+  language?: string;
+}
+
+/**
+ * CMAF Manifest Response Structure
+ * Matches the server response from /api/v1/transcode/manifest.json
+ */
+export interface ManifestResponse {
+  /** Manifest version for compatibility tracking */
+  version: string;
+  /** Type of manifest (e.g., "cmaf", "dash", "hls") */
+  type: string;
+  /** Original source URL for the media */
+  sourceUrl: string;
+  /** Total duration of the content in milliseconds */
+  duration: number;
+  /** Total duration of the content in milliseconds */
+  durationMs: number;
+  /** Duration of each segment in milliseconds */
+  segmentDuration: number;
+  /** Base URL for all relative URLs */
+  baseUrl: string;
+  /** Video renditions available for adaptive streaming */
+  videoRenditions: ManifestVideoRendition[];
+  /** Audio renditions available for adaptive streaming */
+  audioRenditions: ManifestAudioRendition[];
+  /** URL templates for segment access */
+  endpoints: {
+    /** Initialization segment URL template with {rendition} placeholder */
+    initSegment: string;
+    /** Media segment URL template with {rendition} and {segmentId} placeholders */
+    mediaSegment: string;
+  };
+  /** JIT transcoding specific information */
+  jitInfo: {
+    /** Whether parallel transcoding is supported */
+    parallelTranscodingSupported: boolean;
+    /** Expected transcoding latency in milliseconds */
+    expectedTranscodeLatency: number;
+    /** Total number of segments */
+    segmentCount: number;
+  };
+  /** Optional timescale for the media timeline */
+  timescale?: number;
+  /** Optional start number for segments */
+  startNumber?: number;
+  /** Optional minimum buffer time in milliseconds */
+  minBufferTime?: number;
+  /** Optional suggested presentation delay in milliseconds */
+  suggestedPresentationDelay?: number;
+}
+
+/**
+ * Cache statistics interface
+ */
+export interface CacheStats {
+  size: number;
+  maxSize: number;
+  hitRate: number;
+  efficiency: number;
+  totalRequests: number;
+  recentKeys: string[];
+}
+
+// TODO: JitTranscodingClient interface removed - will return in a later release
+export interface AudioRendition {
+  id?: RenditionId;
+  trackId: number | undefined;
+  src: string;
+  segmentDurationMs?: number;
+}
+export interface VideoRendition {
+  id?: RenditionId;
+  trackId: number | undefined;
+  src: string;
+  segmentDurationMs?: number;
+  startTimeOffsetMs?: number;
+}
+export interface MediaEngine {
+  durationMs: number;
+  src: string;
+  audioRendition?: AudioRendition;
+  videoRendition?: VideoRendition;
+  templates: {
+    initSegment: string;
+    mediaSegment: string;
+  };
+  fetchInitSegment: (
+    rendition: {
+      id?: RenditionId;
+      trackId: number | undefined;
+      src: string;
+    },
+    signal: AbortSignal,
+  ) => Promise<ArrayBuffer>;
+  fetchMediaSegment: (
+    segmentId: number,
+    rendition: { id?: RenditionId; trackId: number | undefined; src: string },
+    signal?: AbortSignal,
+  ) => Promise<ArrayBuffer>;
+  computeSegmentId: (
+    desiredSeekTimeMs: number,
+    rendition: {
+      id?: RenditionId;
+      trackId: number | undefined;
+      src: string;
+      segmentDurationMs?: number;
+    },
+  ) => number | undefined;
+
+  /**
+   * Get the video rendition, or throws if no video rendition is available
+   */
+  getVideoRendition: () => VideoRendition;
+
+  /**
+   * Get the audio rendition, or throws if no audio rendition is available
+   */
+  getAudioRendition: () => AudioRendition;
+
+  /**
+   * 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[];
+}
+interface InitSegmentPath {
+  path: string;
+  pos: number;
+  size: number;
+}
+export interface InitSegmentPaths {
+  audio?: InitSegmentPath;
+  video?: InitSegmentPath;
+}
+export interface AudioSpan {
+  startMs: number;
+  endMs: number;
+  blob: Blob;
+}
+export interface SegmentTimeRange {
+  segmentId: number;
+  startMs: number;
+  endMs: number;
+}

package/src/transcoding/utils/MediaUtils.ts

@@ -0,0 +1,63 @@
+/**
+ * Media type detection utilities
+ */
+
+export function isAudioUrl(url: string): boolean {
+  if (!url) return false;
+
+  // Extract the pathname from URL, handling both full URLs and simple paths
+  let pathname: string;
+  try {
+    const urlObj = new URL(url);
+    pathname = urlObj.pathname;
+  } catch {
+    // If URL parsing fails, treat as simple path
+    pathname = url;
+  }
+
+  // Remove query parameters and get file extension
+  const pathWithoutQuery = pathname.split("?")[0] || "";
+  const extension = pathWithoutQuery.split(".").pop()?.toLowerCase();
+
+  // Check for audio file extensions
+  const audioExtensions = ["mp3", "wav", "flac", "aac", "m4a", "ogg", "wma"];
+  return extension ? audioExtensions.includes(extension) : false;
+}
+
+export function isVideoUrl(url: string): boolean {
+  if (!url) return false;
+
+  // Extract the pathname from URL, handling both full URLs and simple paths
+  let pathname: string;
+  try {
+    const urlObj = new URL(url);
+    pathname = urlObj.pathname;
+  } catch {
+    // If URL parsing fails, treat as simple path
+    pathname = url;
+  }
+
+  // Remove query parameters and get file extension
+  const pathWithoutQuery = pathname.split("?")[0] || "";
+  const extension = pathWithoutQuery.split(".").pop()?.toLowerCase();
+
+  // Check for video file extensions
+  const videoExtensions = [
+    "mp4",
+    "avi",
+    "mov",
+    "wmv",
+    "flv",
+    "webm",
+    "mkv",
+    "m4v",
+  ];
+  return extension ? videoExtensions.includes(extension) : false;
+}
+
+/**
+ * Check if URL is eligible for JIT transcoding
+ */
+export function isJitTranscodeEligible(url: string): boolean {
+  return url.startsWith("http://") || url.startsWith("https://");
+}

package/src/transcoding/utils/UrlGenerator.ts

@@ -0,0 +1,68 @@
+/**
+ * URL generation utilities for transcoding endpoints
+ */
+
+import type { RenditionId } from "../types/index.js";
+import type { MediaEngine } from "../types/index.ts";
+
+export class UrlGenerator {
+  constructor(private baseUrl: () => string) {}
+
+  /**
+   * Generate video segment URL
+   */
+  generateSegmentUrl(
+    segmentId: "init" | number,
+    renditionId: RenditionId,
+    metadata: MediaEngine,
+  ): string {
+    const audioRendition = metadata.audioRendition;
+    const videoRendition = metadata.videoRendition;
+    const rendition = audioRendition ?? videoRendition;
+    if (!rendition) {
+      console.error("Rendition not found", metadata);
+      throw new Error(`Rendition ${renditionId} not found`);
+    }
+
+    const template =
+      segmentId === "init"
+        ? metadata.templates.initSegment
+        : metadata.templates.mediaSegment;
+    return template
+      .replace("{rendition}", renditionId)
+      .replace("{segmentId}", segmentId.toString())
+      .replace("{src}", metadata.src)
+      .replace("{trackId}", rendition.trackId?.toString() ?? "");
+  }
+
+  /**
+   * Generate init segment URL
+   */
+  generateInitSegmentUrl(mediaUrl: string, rendition: string): string {
+    return `${this.baseUrl()}/api/v1/transcode/${rendition}/init.m4s?url=${encodeURIComponent(mediaUrl)}`;
+  }
+
+  /**
+   * Generate manifest URL
+   */
+  generateManifestUrl(mediaUrl: string): string {
+    return `${this.baseUrl()}/api/v1/transcode/manifest.json?url=${encodeURIComponent(mediaUrl)}`;
+  }
+
+  /**
+   * Generate track fragment index URL
+   */
+  generateTrackFragmentIndexUrl(mediaUrl: string): string {
+    const normalizedSrc = mediaUrl.startsWith("/")
+      ? mediaUrl.slice(1)
+      : mediaUrl;
+    return `/@ef-track-fragment-index/${normalizedSrc}`;
+  }
+
+  /**
+   * Generate quality presets URL
+   */
+  generatePresetsUrl(): string {
+    return `${this.baseUrl()}/api/v1/transcode/presets`;
+  }
+}

package/src/transcoding/utils/constants.ts

@@ -0,0 +1,36 @@
+/**
+ * Constants for JIT transcoding system
+ */
+
+import type { QualityPresets } from "../types/index.js";
+
+/**
+ * Segment duration constants (in milliseconds)
+ */
+export const SEGMENT_DURATION_VIDEO_MS = 2000; // 2 seconds
+export const SEGMENT_DURATION_AUDIO_MS = 15000; // 15 seconds
+export const SEGMENT_DURATION_SCRUB_MS = 30000; // 30 seconds
+
+/**
+ * Default cache sizes for different media types
+ */
+export const DEFAULT_CACHE_SIZE_VIDEO = 50;
+export const DEFAULT_CACHE_SIZE_AUDIO = 20;
+
+/**
+ * Default prefetch settings
+ */
+export const DEFAULT_PREFETCH_SEGMENTS_VIDEO = 3;
+export const DEFAULT_PREFETCH_SEGMENTS_AUDIO = 2;
+
+/**
+ * Retry configuration
+ */
+export const RETRY_MAX_ATTEMPTS = 3;
+export const RETRY_BASE_DELAY_MS = 500;
+
+/**
+ * Default service configuration
+ */
+export const DEFAULT_BASE_URL = "http://localhost:3000";
+export const DEFAULT_QUALITY: keyof QualityPresets = "medium";

package/src/utils/LRUCache.ts

@@ -0,0 +1,153 @@
+/**
+ * A simple LRU (Least Recently Used) cache implementation
+ */
+export class LRUCache<K, V> {
+  private cache = new Map<K, V>();
+  private readonly maxSize: number;
+
+  constructor(maxSize: number) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: K): V | undefined {
+    const value = this.cache.get(key);
+    if (value) {
+      // Refresh position by removing and re-adding
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      // Remove oldest entry (first item in map)
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+      }
+    }
+    this.cache.set(key, value);
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  delete(key: K): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+/**
+ * Size-aware LRU cache that tracks memory usage in bytes
+ * Evicts entries when total size exceeds the maximum
+ */
+export class SizeAwareLRUCache<K> {
+  private cache = new Map<K, Promise<ArrayBuffer>>();
+  private sizes = new Map<K, number>();
+  private currentSize = 0;
+  private readonly maxSizeBytes: number;
+
+  constructor(maxSizeBytes: number) {
+    this.maxSizeBytes = maxSizeBytes;
+  }
+
+  get(key: K): Promise<ArrayBuffer> | undefined {
+    const value = this.cache.get(key);
+    if (value) {
+      // Refresh position by removing and re-adding
+      const size = this.sizes.get(key) || 0;
+      this.cache.delete(key);
+      this.cache.set(key, value);
+      this.sizes.delete(key);
+      this.sizes.set(key, size);
+    }
+    return value;
+  }
+
+  set(key: K, value: Promise<ArrayBuffer>): void {
+    // If key already exists, remove it first
+    if (this.cache.has(key)) {
+      const oldSize = this.sizes.get(key) || 0;
+      this.currentSize -= oldSize;
+      this.cache.delete(key);
+      this.sizes.delete(key);
+    }
+
+    // Track the size when the promise resolves
+    const sizeTrackingPromise = value
+      .then((buffer) => {
+        const bufferSize = buffer.byteLength;
+        this.sizes.set(key, bufferSize);
+        this.currentSize += bufferSize;
+
+        // Evict oldest entries if we exceed the size limit
+        this.evictIfNecessary();
+
+        return buffer;
+      })
+      .catch((error) => {
+        // If the promise fails, clean up the entry
+        this.cache.delete(key);
+        this.sizes.delete(key);
+        throw error;
+      });
+
+    this.cache.set(key, sizeTrackingPromise);
+  }
+
+  private evictIfNecessary(): void {
+    while (this.currentSize > this.maxSizeBytes && this.cache.size > 0) {
+      // Remove oldest entry (first item in map)
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        const size = this.sizes.get(firstKey) || 0;
+        this.currentSize -= size;
+        this.cache.delete(firstKey);
+        this.sizes.delete(firstKey);
+      } else {
+        break;
+      }
+    }
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  delete(key: K): boolean {
+    const size = this.sizes.get(key) || 0;
+    this.currentSize -= size;
+    this.sizes.delete(key);
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+    this.sizes.clear();
+    this.currentSize = 0;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  get currentSizeBytes(): number {
+    return this.currentSize;
+  }
+
+  get maxSize(): number {
+    return this.maxSizeBytes;
+  }
+}