asciify-engine 1.0.43 → 1.0.45

package/README.md

@@ -77,39 +77,41 @@ setInterval(() => {
 }, 1000 / fps);
 ```
 
-### Video — live (recommended)
+### Video
 
-`asciifyLiveVideo` streams a video as ASCII art in real time. Pass a URL and a canvas — it handles everything else.
+`asciifyVideo` streams video as live ASCII art in real time. Instant start, constant memory, unlimited duration.
 
-> ⚠️ Never set the `<video>` element to `display: none`. Browsers skip GPU frame decoding for hidden elements — you get a blank canvas. `asciifyLiveVideo` handles this automatically.
+> ⚠️ Never set the backing `<video>` element to `display: none` — browsers skip GPU frame decoding. When given a URL string, `asciifyVideo` handles this automatically.
 
 ```ts
-import { asciifyLiveVideo } from 'asciify-engine';
+import { asciifyVideo } from 'asciify-engine';
 
 const canvas = document.getElementById('ascii') as HTMLCanvasElement;
-const stop   = await asciifyLiveVideo('/clip.mp4', canvas);
 
-// With options:
-const stop = await asciifyLiveVideo('/clip.mp4', canvas, {
+// Minimal
+const stop = await asciifyVideo('/clip.mp4', canvas);
+
+// Fit canvas to a container and re-size automatically on resize:
+const stop = await asciifyVideo('/clip.mp4', canvas, {
+  fitTo: '#hero',  // or an HTMLElement
+});
+
+// Lifecycle hooks — ready state, timers, etc.:
+const stop = await asciifyVideo('/clip.mp4', canvas, {
+  fitTo: '#hero',
   fontSize: 6,
-  artStyle: 'matrix',
+  onReady: () => setLoading(false),
+  onFrame: () => setElapsed(t => t + 1),
 });
 
+// Pre-extract all frames before playback (frame-perfect loops, short clips):
+const stop = await asciifyVideo('/clip.mp4', canvas, { preExtract: true });
+
 // Clean up:
 stop();
 ```
 
-### Video — pre-extracted frames
 
-`asciifyVideo` seeks through the clip frame by frame and returns a frame sequence. Good for short clips where you want frame-perfect control, but requires up-front processing time.
-
-```ts
-import { asciifyVideo } from 'asciify-engine';
-
-const canvas = document.getElementById('ascii') as HTMLCanvasElement;
-const stop   = await asciifyVideo('/clip.mp4', canvas, { fontSize: 8 });
-stop();
-```
 
 ---
 
@@ -255,7 +257,6 @@ const animatedHtml = generateAnimatedEmbedCode(frames, options, fps);
 | Function | Signature | Returns |
 |---|---|---|
 | `asciify` | `(source, canvas, options?)` | `Promise<void>` |
-| `asciifyLiveVideo` | `(source, canvas, options?)` | `Promise<() => void>` |
 | `asciifyVideo` | `(source, canvas, options?)` | `Promise<() => void>` |
 | `asciifyGif` | `(source, canvas, options?)` | `Promise<() => void>` |
 | `asciifyWebcam` | `(canvas, options?)` | `Promise<() => void>` |
@@ -267,6 +268,8 @@ const animatedHtml = generateAnimatedEmbedCode(frames, options, fps);
 | `generateEmbedCode` | `(frame, options)` | `string` |
 | `generateAnimatedEmbedCode` | `(frames, options, fps)` | `string` |
 
+`asciifyVideo` options: `fitTo` (HTMLElement/selector — fits canvas to container + ResizeObserver), `preExtract` (pre-decode all frames, default false), `onReady(video)`, `onFrame()`
+
 ---
 
 ## License

package/dist/index.cjs

@@ -985,6 +985,17 @@ function renderFrameToCanvas(ctx, frame, options, canvasWidth, canvasHeight, tim
 }
 
 // src/core/simple-api.ts
+function sizeCanvasToContainer(canvas, container, aspect) {
+  const { width, height } = container.getBoundingClientRect();
+  if (!width || !height) return;
+  let w = width, h = w / aspect;
+  if (h > height) {
+    h = height;
+    w = h * aspect;
+  }
+  canvas.width = Math.round(w);
+  canvas.height = Math.round(h);
+}
 async function asciify(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
   let el;
   if (typeof source === "string") {
@@ -1038,46 +1049,47 @@ async function asciifyGif(source, canvas, { fontSize = 10, artStyle = "classic",
     cancelAnimationFrame(animId);
   };
 }
-async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
-  let video;
-  if (typeof source === "string") {
-    video = document.createElement("video");
-    video.crossOrigin = "anonymous";
-    video.src = source;
-    if (video.readyState < 2) {
-      await new Promise((resolve, reject) => {
-        video.onloadeddata = () => resolve();
-        video.onerror = () => reject(new Error(`Failed to load video: ${source}`));
-      });
-    }
-  } else {
-    video = source;
-  }
+async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {}, fitTo, preExtract = false, onReady, onFrame } = {}) {
   const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[artStyle], ...options, fontSize };
   const ctx = canvas.getContext("2d");
-  if (!ctx) throw new Error("Could not get 2d context from canvas");
-  const { frames, fps } = await videoToAsciiFrames(video, merged, canvas.width, canvas.height);
-  let cancelled = false;
-  let animId;
-  let i = 0;
-  let last = performance.now();
-  const interval = 1e3 / fps;
-  const tick = (now) => {
-    if (cancelled) return;
-    if (now - last >= interval) {
-      renderFrameToCanvas(ctx, frames[i], merged, canvas.width, canvas.height);
-      i = (i + 1) % frames.length;
-      last = now;
-    }
-    animId = requestAnimationFrame(tick);
-  };
-  animId = requestAnimationFrame(tick);
-  return () => {
-    cancelled = true;
-    cancelAnimationFrame(animId);
-  };
-}
-async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {}, onReady, onFrame } = {}) {
+  if (!ctx) throw new Error("asciifyVideo: could not get 2d context from canvas.");
+  const container = typeof fitTo === "string" ? document.querySelector(fitTo) : fitTo instanceof HTMLElement ? fitTo : null;
+  if (preExtract) {
+    let video2;
+    if (typeof source === "string") {
+      video2 = document.createElement("video");
+      video2.crossOrigin = "anonymous";
+      video2.src = source;
+      if (video2.readyState < 2) {
+        await new Promise((resolve, reject) => {
+          video2.onloadeddata = () => resolve();
+          video2.onerror = () => reject(new Error(`asciifyVideo: failed to load "${source}"`));
+        });
+      }
+    } else {
+      video2 = source;
+    }
+    if (container) sizeCanvasToContainer(canvas, container, video2.videoWidth / video2.videoHeight);
+    onReady?.(video2);
+    const { frames, fps } = await videoToAsciiFrames(video2, merged, canvas.width, canvas.height);
+    let cancelled2 = false, animId2, i = 0, last = performance.now();
+    const interval = 1e3 / fps;
+    const tick2 = (now) => {
+      if (cancelled2) return;
+      if (now - last >= interval) {
+        renderFrameToCanvas(ctx, frames[i], merged, canvas.width, canvas.height);
+        i = (i + 1) % frames.length;
+        last = now;
+        onFrame?.();
+      }
+      animId2 = requestAnimationFrame(tick2);
+    };
+    animId2 = requestAnimationFrame(tick2);
+    return () => {
+      cancelled2 = true;
+      cancelAnimationFrame(animId2);
+    };
+  }
   let video;
   let ownedVideo = false;
   if (typeof source === "string") {
@@ -1101,20 +1113,23 @@ async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "cla
     ownedVideo = true;
     await new Promise((resolve, reject) => {
       video.onloadedmetadata = () => resolve();
-      video.onerror = () => reject(new Error(`asciifyLiveVideo: failed to load "${source}"`));
+      video.onerror = () => reject(new Error(`asciifyVideo: failed to load "${source}"`));
     });
     await video.play().catch(() => {
     });
-    onReady?.(video);
   } else {
     video = source;
     if (video.paused) await video.play().catch(() => {
     });
-    onReady?.(video);
   }
-  const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[artStyle], ...options, fontSize };
-  const ctx = canvas.getContext("2d");
-  if (!ctx) throw new Error("asciifyLiveVideo: could not get 2d context from canvas.");
+  let ro = null;
+  if (container) {
+    const aspect = video.videoWidth / video.videoHeight;
+    sizeCanvasToContainer(canvas, container, aspect);
+    ro = new ResizeObserver(() => sizeCanvasToContainer(canvas, container, aspect));
+    ro.observe(container);
+  }
+  onReady?.(video);
   let cancelled = false;
   let animId;
   const tick = () => {
@@ -1131,6 +1146,7 @@ async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "cla
   return () => {
     cancelled = true;
     cancelAnimationFrame(animId);
+    ro?.disconnect();
     if (ownedVideo) {
       video.pause();
       video.src = "";
@@ -1138,6 +1154,9 @@ async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "cla
     }
   };
 }
+function asciifyLiveVideo(source, canvas, opts) {
+  return asciifyVideo(source, canvas, opts);
+}
 
 // src/backgrounds/rain.ts
 function renderRainBackground(ctx, width, height, time, options = {}) {