@twick/media-utils 0.15.0 → 0.15.2

package/dist/index.d.ts

@@ -5,10 +5,12 @@ import { Dimensions } from './types';
 import { downloadFile } from './file-helper';
 import { extractAudio } from './audio-utils';
 import { getAudioDuration } from './get-audio-duration';
+import { getDefaultVideoFrameExtractor } from './video-frame-extractor';
 import { getImageDimensions } from './get-image-dimensions';
 import { getObjectFitSize } from './dimension-handler';
 import { getScaledDimensions } from './dimension-handler';
 import { getThumbnail } from './get-thumbnail';
+import { getThumbnailCached } from './video-frame-extractor';
 import { getVideoMeta } from './get-video-metadata';
 import { hasAudio } from './audio-utils';
 import { limit } from './limit';
@@ -16,6 +18,8 @@ import { loadFile } from './file-helper';
 import { Position } from './types';
 import { saveAsFile } from './file-helper';
 import { stitchAudio } from './audio-utils';
+import { VideoFrameExtractor } from './video-frame-extractor';
+import { VideoFrameExtractorOptions } from './video-frame-extractor';
 import { VideoMeta } from './types';
 
 export { AudioSegment }
@@ -32,6 +36,8 @@ export { extractAudio }
 
 export { getAudioDuration }
 
+export { getDefaultVideoFrameExtractor }
+
 export { getImageDimensions }
 
 export { getObjectFitSize }
@@ -40,6 +46,8 @@ export { getScaledDimensions }
 
 export { getThumbnail }
 
+export { getThumbnailCached }
+
 export { getVideoMeta }
 
 export { hasAudio }
@@ -54,6 +62,10 @@ export { saveAsFile }
 
 export { stitchAudio }
 
+export { VideoFrameExtractor }
+
+export { VideoFrameExtractorOptions }
+
 export { VideoMeta }
 
 export { }

package/dist/index.js

@@ -86,36 +86,258 @@ const getVideoMeta = (videoSrc) => {
     return Promise.resolve(videoMetaCache[videoSrc]);
   }
   return new Promise((resolve, reject) => {
-    const video = document.createElement("video");
-    video.preload = "metadata";
     const isSafeUrl = /^(https?:|blob:|data:video\/)/i.test(videoSrc);
     if (!isSafeUrl) {
       reject(new Error("Unsafe video source URL"));
       return;
     }
-    video.src = videoSrc;
-    video.onloadedmetadata = () => {
-      const meta = {
-        width: video.videoWidth,
-        height: video.videoHeight,
-        duration: video.duration
+    const tryLoadVideo = (useCors) => {
+      const video = document.createElement("video");
+      video.preload = "metadata";
+      video.crossOrigin = useCors ? "anonymous" : null;
+      video.src = videoSrc;
+      video.onloadedmetadata = () => {
+        const meta = {
+          width: video.videoWidth,
+          height: video.videoHeight,
+          duration: video.duration
+        };
+        videoMetaCache[videoSrc] = meta;
+        resolve(meta);
+      };
+      video.onerror = () => {
+        if (useCors) {
+          video.src = "";
+          tryLoadVideo(false);
+        } else {
+          reject(new Error("Failed to load video metadata. This may be due to CORS restrictions or an invalid video URL."));
+        }
       };
-      videoMetaCache[videoSrc] = meta;
-      resolve(meta);
     };
-    video.onerror = () => reject(new Error("Failed to load video metadata"));
+    tryLoadVideo(true);
   });
 };
 
 const getThumbnail = async (videoUrl, seekTime = 0.1, playbackRate = 1) => {
   return new Promise((resolve, reject) => {
+    const tryLoadThumbnail = (useCors) => {
+      const video = document.createElement("video");
+      video.crossOrigin = useCors ? "anonymous" : null;
+      video.muted = true;
+      video.playsInline = true;
+      video.autoplay = false;
+      video.preload = "auto";
+      video.playbackRate = playbackRate;
+      video.style.position = "absolute";
+      video.style.left = "-9999px";
+      video.style.top = "-9999px";
+      video.style.width = "1px";
+      video.style.height = "1px";
+      video.style.opacity = "0";
+      video.style.pointerEvents = "none";
+      video.style.zIndex = "-1";
+      let timeoutId;
+      const cleanup = () => {
+        if (video.parentNode) video.remove();
+        if (timeoutId) clearTimeout(timeoutId);
+      };
+      const handleError = () => {
+        cleanup();
+        if (useCors) {
+          tryLoadThumbnail(false);
+        } else {
+          reject(new Error(`Failed to load video: ${video.error?.message || "Unknown error. This may be due to CORS restrictions or an invalid video URL."}`));
+        }
+      };
+      const handleSeeked = () => {
+        try {
+          video.pause();
+          const canvas = document.createElement("canvas");
+          const width = video.videoWidth || 640;
+          const height = video.videoHeight || 360;
+          canvas.width = width;
+          canvas.height = height;
+          const ctx = canvas.getContext("2d");
+          if (!ctx) {
+            cleanup();
+            reject(new Error("Failed to get canvas context"));
+            return;
+          }
+          ctx.drawImage(video, 0, 0, width, height);
+          try {
+            const dataUrl = canvas.toDataURL("image/jpeg", 0.8);
+            cleanup();
+            resolve(dataUrl);
+          } catch {
+            canvas.toBlob((blob) => {
+              if (!blob) {
+                cleanup();
+                reject(new Error("Failed to create Blob"));
+                return;
+              }
+              const blobUrl = URL.createObjectURL(blob);
+              cleanup();
+              resolve(blobUrl);
+            }, "image/jpeg", 0.8);
+          }
+        } catch (err) {
+          cleanup();
+          reject(new Error(`Error creating thumbnail: ${err}`));
+        }
+      };
+      video.addEventListener("error", handleError, { once: true });
+      video.addEventListener("seeked", handleSeeked, { once: true });
+      video.addEventListener("loadedmetadata", () => {
+        const playPromise = video.play();
+        if (playPromise !== void 0) {
+          playPromise.then(() => {
+            video.currentTime = seekTime;
+          }).catch(() => {
+            video.currentTime = seekTime;
+          });
+        } else {
+          video.currentTime = seekTime;
+        }
+      }, { once: true });
+      timeoutId = window.setTimeout(() => {
+        cleanup();
+        reject(new Error("Video loading timed out"));
+      }, 15e3);
+      video.src = videoUrl;
+      document.body.appendChild(video);
+    };
+    tryLoadThumbnail(true);
+  });
+};
+
+class LRUCache {
+  constructor(maxSize = 100) {
+    if (maxSize <= 0) {
+      throw new Error("maxSize must be greater than 0");
+    }
+    this.maxSize = maxSize;
+    this.cache = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Get a value from the cache.
+   * Moves the item to the end (most recently used).
+   */
+  get(key) {
+    const value = this.cache.get(key);
+    if (value === void 0) {
+      return void 0;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    return value;
+  }
+  /**
+   * Set a value in the cache.
+   * If cache is full, removes the least recently used item.
+   */
+  set(key, value) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== void 0) {
+        this.cache.delete(firstKey);
+      }
+    }
+    this.cache.set(key, value);
+  }
+  /**
+   * Check if a key exists in the cache.
+   */
+  has(key) {
+    return this.cache.has(key);
+  }
+  /**
+   * Delete a key from the cache.
+   */
+  delete(key) {
+    return this.cache.delete(key);
+  }
+  /**
+   * Clear all entries from the cache.
+   */
+  clear() {
+    this.cache.clear();
+  }
+  /**
+   * Get the current size of the cache.
+   */
+  get size() {
+    return this.cache.size;
+  }
+}
+
+class VideoFrameExtractor {
+  constructor(options = {}) {
+    this.frameCache = new LRUCache(
+      options.maxCacheSize ?? 50
+    );
+    this.videoElements = /* @__PURE__ */ new Map();
+    this.maxVideoElements = options.maxVideoElements ?? 5;
+    this.loadTimeout = options.loadTimeout ?? 15e3;
+    this.jpegQuality = options.jpegQuality ?? 0.8;
+    this.playbackRate = options.playbackRate ?? 1;
+  }
+  /**
+   * Get a frame thumbnail from a video at a specific time.
+   * Uses caching and reuses video elements for optimal performance.
+   * 
+   * @param videoUrl - The URL of the video
+   * @param seekTime - The time in seconds to extract the frame
+   * @returns Promise resolving to a thumbnail image URL (data URL or blob URL)
+   */
+  async getFrame(videoUrl, seekTime = 0.1) {
+    const cacheKey = this.getCacheKey(videoUrl, seekTime);
+    const cached = this.frameCache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+    const videoState = await this.getVideoElement(videoUrl);
+    const thumbnail = await this.extractFrame(videoState.video, seekTime);
+    this.frameCache.set(cacheKey, thumbnail);
+    return thumbnail;
+  }
+  /**
+   * Get or create a video element for the given URL.
+   * Reuses existing elements and manages cleanup.
+   */
+  async getVideoElement(videoUrl) {
+    let videoState = this.videoElements.get(videoUrl);
+    if (videoState && videoState.isReady) {
+      videoState.lastUsed = Date.now();
+      return videoState;
+    }
+    if (videoState && videoState.isLoading && videoState.loadPromise) {
+      await videoState.loadPromise;
+      if (videoState.isReady) {
+        videoState.lastUsed = Date.now();
+        return videoState;
+      }
+    }
+    if (this.videoElements.size >= this.maxVideoElements) {
+      this.cleanupOldVideoElements();
+    }
+    videoState = await this.createVideoElement(videoUrl);
+    this.videoElements.set(videoUrl, videoState);
+    videoState.lastUsed = Date.now();
+    return videoState;
+  }
+  /**
+   * Create and initialize a new video element.
+   */
+  async createVideoElement(videoUrl) {
     const video = document.createElement("video");
     video.crossOrigin = "anonymous";
     video.muted = true;
     video.playsInline = true;
     video.autoplay = false;
     video.preload = "auto";
-    video.playbackRate = playbackRate;
+    video.playbackRate = this.playbackRate;
     video.style.position = "absolute";
     video.style.left = "-9999px";
     video.style.top = "-9999px";
@@ -124,54 +346,127 @@ const getThumbnail = async (videoUrl, seekTime = 0.1, playbackRate = 1) => {
     video.style.opacity = "0";
     video.style.pointerEvents = "none";
     video.style.zIndex = "-1";
-    let timeoutId;
-    const cleanup = () => {
-      if (video.parentNode) video.remove();
-      if (timeoutId) clearTimeout(timeoutId);
+    const state = {
+      video,
+      isReady: false,
+      isLoading: true,
+      loadPromise: null,
+      lastUsed: Date.now()
     };
-    const handleError = () => {
-      cleanup();
-      reject(new Error(`Failed to load video: ${video.error?.message || "Unknown error"}`));
-    };
-    const handleSeeked = () => {
-      try {
-        video.pause();
-        const canvas = document.createElement("canvas");
-        const width = video.videoWidth || 640;
-        const height = video.videoHeight || 360;
-        canvas.width = width;
-        canvas.height = height;
-        const ctx = canvas.getContext("2d");
-        if (!ctx) {
-          cleanup();
-          reject(new Error("Failed to get canvas context"));
+    state.loadPromise = new Promise((resolve, reject) => {
+      let timeoutId;
+      const cleanup = () => {
+        if (timeoutId) clearTimeout(timeoutId);
+      };
+      const handleError = () => {
+        cleanup();
+        state.isLoading = false;
+        reject(new Error(`Failed to load video: ${video.error?.message || "Unknown error"}`));
+      };
+      const handleLoadedMetadata = () => {
+        cleanup();
+        state.isReady = true;
+        state.isLoading = false;
+        resolve();
+      };
+      video.addEventListener("error", handleError, { once: true });
+      video.addEventListener("loadedmetadata", handleLoadedMetadata, { once: true });
+      timeoutId = window.setTimeout(() => {
+        cleanup();
+        state.isLoading = false;
+        reject(new Error("Video loading timed out"));
+      }, this.loadTimeout);
+      video.src = videoUrl;
+      document.body.appendChild(video);
+    });
+    try {
+      await state.loadPromise;
+    } catch (error) {
+      if (video.parentNode) {
+        video.remove();
+      }
+      throw error;
+    }
+    return state;
+  }
+  /**
+   * Extract a frame from a video at the specified time.
+   */
+  async extractFrame(video, seekTime) {
+    return new Promise((resolve, reject) => {
+      video.pause();
+      const timeThreshold = 0.1;
+      if (Math.abs(video.currentTime - seekTime) < timeThreshold) {
+        try {
+          const canvas = document.createElement("canvas");
+          const width = video.videoWidth || 640;
+          const height = video.videoHeight || 360;
+          canvas.width = width;
+          canvas.height = height;
+          const ctx = canvas.getContext("2d");
+          if (!ctx) {
+            reject(new Error("Failed to get canvas context"));
+            return;
+          }
+          ctx.drawImage(video, 0, 0, width, height);
+          try {
+            const dataUrl = canvas.toDataURL("image/jpeg", this.jpegQuality);
+            resolve(dataUrl);
+          } catch {
+            canvas.toBlob(
+              (blob) => {
+                if (!blob) {
+                  reject(new Error("Failed to create Blob"));
+                  return;
+                }
+                const blobUrl = URL.createObjectURL(blob);
+                resolve(blobUrl);
+              },
+              "image/jpeg",
+              this.jpegQuality
+            );
+          }
+          return;
+        } catch (err) {
+          reject(new Error(`Error creating thumbnail: ${err}`));
           return;
         }
-        ctx.drawImage(video, 0, 0, width, height);
+      }
+      const handleSeeked = () => {
         try {
-          const dataUrl = canvas.toDataURL("image/jpeg", 0.8);
-          cleanup();
-          resolve(dataUrl);
-        } catch {
-          canvas.toBlob((blob) => {
-            if (!blob) {
-              cleanup();
-              reject(new Error("Failed to create Blob"));
-              return;
-            }
-            const blobUrl = URL.createObjectURL(blob);
-            cleanup();
-            resolve(blobUrl);
-          }, "image/jpeg", 0.8);
+          const canvas = document.createElement("canvas");
+          const width = video.videoWidth || 640;
+          const height = video.videoHeight || 360;
+          canvas.width = width;
+          canvas.height = height;
+          const ctx = canvas.getContext("2d");
+          if (!ctx) {
+            reject(new Error("Failed to get canvas context"));
+            return;
+          }
+          ctx.drawImage(video, 0, 0, width, height);
+          try {
+            const dataUrl = canvas.toDataURL("image/jpeg", this.jpegQuality);
+            resolve(dataUrl);
+          } catch {
+            canvas.toBlob(
+              (blob) => {
+                if (!blob) {
+                  reject(new Error("Failed to create Blob"));
+                  return;
+                }
+                const blobUrl = URL.createObjectURL(blob);
+                resolve(blobUrl);
+              },
+              "image/jpeg",
+              this.jpegQuality
+            );
+          }
+        } catch (err) {
+          reject(new Error(`Error creating thumbnail: ${err}`));
         }
-      } catch (err) {
-        cleanup();
-        reject(new Error(`Error creating thumbnail: ${err}`));
-      }
-    };
-    video.addEventListener("error", handleError, { once: true });
-    video.addEventListener("seeked", handleSeeked, { once: true });
-    video.addEventListener("loadedmetadata", () => {
+      };
+      video.addEventListener("seeked", handleSeeked, { once: true });
       const playPromise = video.play();
       if (playPromise !== void 0) {
         playPromise.then(() => {
@@ -182,15 +477,80 @@ const getThumbnail = async (videoUrl, seekTime = 0.1, playbackRate = 1) => {
       } else {
         video.currentTime = seekTime;
       }
-    }, { once: true });
-    timeoutId = window.setTimeout(() => {
-      cleanup();
-      reject(new Error("Video loading timed out"));
-    }, 15e3);
-    video.src = videoUrl;
-    document.body.appendChild(video);
-  });
-};
+    });
+  }
+  /**
+   * Generate cache key for a video URL and seek time.
+   */
+  getCacheKey(videoUrl, seekTime) {
+    const roundedTime = Math.round(seekTime * 100) / 100;
+    return `${videoUrl}:${roundedTime}`;
+  }
+  /**
+   * Cleanup least recently used video elements.
+   */
+  cleanupOldVideoElements() {
+    if (this.videoElements.size < this.maxVideoElements) {
+      return;
+    }
+    const entries = Array.from(this.videoElements.entries());
+    entries.sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+    const toRemove = entries.slice(0, entries.length - this.maxVideoElements + 1);
+    for (const [url, state] of toRemove) {
+      if (state.video.parentNode) {
+        state.video.remove();
+      }
+      this.videoElements.delete(url);
+    }
+  }
+  /**
+   * Clear the frame cache.
+   */
+  clearCache() {
+    this.frameCache.clear();
+  }
+  /**
+   * Remove a specific video element and clear its cached frames.
+   */
+  removeVideo(videoUrl) {
+    const state = this.videoElements.get(videoUrl);
+    if (state) {
+      if (state.video.parentNode) {
+        state.video.remove();
+      }
+      this.videoElements.delete(videoUrl);
+    }
+    this.frameCache.clear();
+  }
+  /**
+   * Dispose of all video elements and clear caches.
+   * Removes all video elements from the DOM and clears both the frame cache
+   * and video element cache. Call this when the extractor is no longer needed
+   * to prevent memory leaks.
+   */
+  dispose() {
+    for (const state of this.videoElements.values()) {
+      if (state.video.parentNode) {
+        state.video.remove();
+      }
+    }
+    this.videoElements.clear();
+    this.frameCache.clear();
+  }
+}
+let defaultExtractor = null;
+function getDefaultVideoFrameExtractor(options) {
+  if (!defaultExtractor) {
+    defaultExtractor = new VideoFrameExtractor(options);
+  }
+  return defaultExtractor;
+}
+async function getThumbnailCached(videoUrl, seekTime = 0.1, playbackRate) {
+  const extractor = getDefaultVideoFrameExtractor(
+    playbackRate !== void 0 ? { playbackRate } : void 0
+  );
+  return extractor.getFrame(videoUrl, seekTime);
+}
 
 const extractAudio = async ({
   src,
@@ -609,15 +969,18 @@ const detectMediaTypeFromUrl = async (url) => {
   }
 };
 
+exports.VideoFrameExtractor = VideoFrameExtractor;
 exports.blobUrlToFile = blobUrlToFile;
 exports.detectMediaTypeFromUrl = detectMediaTypeFromUrl;
 exports.downloadFile = downloadFile;
 exports.extractAudio = extractAudio;
 exports.getAudioDuration = getAudioDuration;
+exports.getDefaultVideoFrameExtractor = getDefaultVideoFrameExtractor;
 exports.getImageDimensions = getImageDimensions;
 exports.getObjectFitSize = getObjectFitSize;
 exports.getScaledDimensions = getScaledDimensions;
 exports.getThumbnail = getThumbnail;
+exports.getThumbnailCached = getThumbnailCached;
 exports.getVideoMeta = getVideoMeta;
 exports.hasAudio = hasAudio;
 exports.limit = limit;