asciify-engine 1.0.48 → 1.0.50

package/dist/index.d.cts

@@ -224,7 +224,7 @@ declare function imageToAsciiFrame(source: HTMLImageElement | HTMLVideoElement |
 /**
  * Extract frames from a video element for ASCII animation.
  */
-declare function videoToAsciiFrames(video: HTMLVideoElement, options: AsciiOptions, targetWidth: number, targetHeight: number, targetFps?: number, maxDuration?: number, onProgress?: (progress: number) => void): Promise<{
+declare function videoToAsciiFrames(video: HTMLVideoElement, options: AsciiOptions, targetWidth: number, targetHeight: number, targetFps?: number, maxDuration?: number, onProgress?: (progress: number) => void, startTime?: number): Promise<{
     frames: AsciiFrame[];
     cols: number;
     rows: number;
@@ -288,6 +288,20 @@ interface AsciifyVideoOptions extends AsciifySimpleOptions {
      * ⚠️ Memory-intensive. Capped at 10 s / 300 frames.
      */
     preExtract?: boolean;
+    /**
+     * Trim the video to a specific time range (in seconds).
+     * - `start` — seek to this time before playback begins. Default: `0`
+     * - `end` — loop back to `start` when this time is reached.
+     *   In `preExtract` mode, only frames up to `end` are extracted.
+     *
+     * @example
+     * // Play only seconds 2–8, looping:
+     * asciifyVideo('/clip.mp4', canvas, { trim: { start: 2, end: 8 } });
+     */
+    trim?: {
+        start?: number;
+        end?: number;
+    };
     /**
      * Called once when the video metadata is loaded and playback has started.
      * Receives the backing video element.
@@ -341,7 +355,7 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * // Pre-extract frames (old behavior):
  * const stop = await asciifyVideo('/clip.mp4', canvas, { preExtract: true });
  */
-declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, fitTo, preExtract, onReady, onFrame }?: AsciifyVideoOptions): Promise<() => void>;
+declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, fitTo, preExtract, trim, onReady, onFrame }?: AsciifyVideoOptions): Promise<() => void>;
 /**
  * @deprecated Use {@link asciifyVideo} instead — it now defaults to live streaming
  * and accepts the same options including `fitTo` and `preExtract`.

package/dist/index.d.ts

@@ -224,7 +224,7 @@ declare function imageToAsciiFrame(source: HTMLImageElement | HTMLVideoElement |
 /**
  * Extract frames from a video element for ASCII animation.
  */
-declare function videoToAsciiFrames(video: HTMLVideoElement, options: AsciiOptions, targetWidth: number, targetHeight: number, targetFps?: number, maxDuration?: number, onProgress?: (progress: number) => void): Promise<{
+declare function videoToAsciiFrames(video: HTMLVideoElement, options: AsciiOptions, targetWidth: number, targetHeight: number, targetFps?: number, maxDuration?: number, onProgress?: (progress: number) => void, startTime?: number): Promise<{
     frames: AsciiFrame[];
     cols: number;
     rows: number;
@@ -288,6 +288,20 @@ interface AsciifyVideoOptions extends AsciifySimpleOptions {
      * ⚠️ Memory-intensive. Capped at 10 s / 300 frames.
      */
     preExtract?: boolean;
+    /**
+     * Trim the video to a specific time range (in seconds).
+     * - `start` — seek to this time before playback begins. Default: `0`
+     * - `end` — loop back to `start` when this time is reached.
+     *   In `preExtract` mode, only frames up to `end` are extracted.
+     *
+     * @example
+     * // Play only seconds 2–8, looping:
+     * asciifyVideo('/clip.mp4', canvas, { trim: { start: 2, end: 8 } });
+     */
+    trim?: {
+        start?: number;
+        end?: number;
+    };
     /**
      * Called once when the video metadata is loaded and playback has started.
      * Receives the backing video element.
@@ -341,7 +355,7 @@ declare function asciifyGif(source: string | ArrayBuffer, canvas: HTMLCanvasElem
  * // Pre-extract frames (old behavior):
  * const stop = await asciifyVideo('/clip.mp4', canvas, { preExtract: true });
  */
-declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, fitTo, preExtract, onReady, onFrame }?: AsciifyVideoOptions): Promise<() => void>;
+declare function asciifyVideo(source: HTMLVideoElement | string, canvas: HTMLCanvasElement, { fontSize, artStyle, options, fitTo, preExtract, trim, onReady, onFrame }?: AsciifyVideoOptions): Promise<() => void>;
 /**
  * @deprecated Use {@link asciifyVideo} instead — it now defaults to live streaming
  * and accepts the same options including `fitTo` and `preExtract`.

package/dist/index.js

@@ -692,15 +692,15 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
   }
   return { frame, cols, rows };
 }
-async function videoToAsciiFrames(video, options, targetWidth, targetHeight, targetFps = 12, maxDuration = 10, onProgress) {
-  const duration = Math.min(video.duration, maxDuration);
+async function videoToAsciiFrames(video, options, targetWidth, targetHeight, targetFps = 12, maxDuration = 10, onProgress, startTime = 0) {
+  const duration = Math.min(video.duration - startTime, maxDuration);
   const totalFrames = Math.ceil(duration * targetFps);
   const frames = [];
   let cols = 0;
   let rows = 0;
   for (let i = 0; i < totalFrames; i++) {
-    const time = i / targetFps;
-    if (time > duration) break;
+    const time = startTime + i / targetFps;
+    if (time > startTime + duration) break;
     video.currentTime = time;
     await new Promise((resolve) => {
       const handler = () => {
@@ -1087,7 +1087,9 @@ async function asciifyGif(source, canvas, { fontSize = 10, artStyle = "classic",
     cancelAnimationFrame(animId);
   };
 }
-async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {}, fitTo, preExtract = false, onReady, onFrame } = {}) {
+async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {}, fitTo, preExtract = false, trim, onReady, onFrame } = {}) {
+  const trimStart = trim?.start ?? 0;
+  const trimEnd = trim?.end;
   const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[artStyle], ...options, fontSize };
   const ctx = canvas.getContext("2d");
   if (!ctx) throw new Error("asciifyVideo: could not get 2d context from canvas.");
@@ -1108,9 +1110,10 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
       video2 = source;
     }
     if (container) sizeCanvasToContainer(canvas, container, video2.videoWidth / video2.videoHeight);
-    onReady?.(video2);
-    const { frames, fps } = await videoToAsciiFrames(video2, merged, canvas.width, canvas.height);
+    const maxDur = trimEnd !== void 0 ? trimEnd - trimStart : 10;
+    const { frames, fps } = await videoToAsciiFrames(video2, merged, canvas.width, canvas.height, void 0, maxDur, void 0, trimStart);
     let cancelled2 = false, animId2, i = 0, last = performance.now();
+    let firstFrame2 = true;
     const interval = 1e3 / fps;
     const tick2 = (now) => {
       if (cancelled2) return;
@@ -1118,6 +1121,10 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
         renderFrameToCanvas(ctx, frames[i], merged, canvas.width, canvas.height);
         i = (i + 1) % frames.length;
         last = now;
+        if (firstFrame2) {
+          firstFrame2 = false;
+          onReady?.(video2);
+        }
         onFrame?.();
       }
       animId2 = requestAnimationFrame(tick2);
@@ -1160,6 +1167,23 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
     if (video.paused) await video.play().catch(() => {
     });
   }
+  if (trimStart > 0) {
+    video.currentTime = trimStart;
+    await new Promise((resolve) => {
+      const h = () => {
+        video.removeEventListener("seeked", h);
+        resolve();
+      };
+      video.addEventListener("seeked", h);
+    });
+  }
+  let timeupdateHandler = null;
+  if (trimEnd !== void 0) {
+    timeupdateHandler = () => {
+      if (video.currentTime >= trimEnd) video.currentTime = trimStart;
+    };
+    video.addEventListener("timeupdate", timeupdateHandler);
+  }
   let ro = null;
   if (container) {
     const aspect = video.videoWidth / video.videoHeight;
@@ -1167,9 +1191,9 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
     ro = new ResizeObserver(() => sizeCanvasToContainer(canvas, container, aspect));
     ro.observe(container);
   }
-  onReady?.(video);
   let cancelled = false;
   let animId;
+  let firstFrame = true;
   const tick = () => {
     if (cancelled) return;
     animId = requestAnimationFrame(tick);
@@ -1177,6 +1201,10 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
     const { frame } = imageToAsciiFrame(video, merged, canvas.width, canvas.height);
     if (frame.length > 0) {
       renderFrameToCanvas(ctx, frame, merged, canvas.width, canvas.height, 0, null);
+      if (firstFrame) {
+        firstFrame = false;
+        onReady?.(video);
+      }
       onFrame?.();
     }
   };
@@ -1185,6 +1213,7 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
     cancelled = true;
     cancelAnimationFrame(animId);
     ro?.disconnect();
+    if (timeupdateHandler) video.removeEventListener("timeupdate", timeupdateHandler);
     if (ownedVideo) {
       video.pause();
       video.src = "";