asciify-engine 1.0.41 → 1.0.43

package/README.md

@@ -77,29 +77,38 @@ setInterval(() => {
 }, 1000 / fps);
 ```
 
-### Video
+### Video — live (recommended)
 
-`videoToAsciiFrames` extracts frames from an `HTMLVideoElement` at a given frame rate and returns the full frame sequence.
+`asciifyLiveVideo` streams a video as ASCII art in real time. Pass a URL and a canvas — it handles everything else.
 
-```ts
-import { videoToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+> ⚠️ 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.
 
-const video = document.createElement('video');
-video.src   = '/clip.mp4';
-video.muted = true;
-await new Promise(r => (video.onloadeddata = r));
+```ts
+import { asciifyLiveVideo } from 'asciify-engine';
 
 const canvas = document.getElementById('ascii') as HTMLCanvasElement;
-const opts   = { ...DEFAULT_OPTIONS, fontSize: 8 };
+const stop   = await asciifyLiveVideo('/clip.mp4', canvas);
 
-// videoToAsciiFrames(video, options, width, height, fps?, maxDurationSeconds?)
-const { frames, fps } = await videoToAsciiFrames(video, opts, canvas.width, canvas.height, 12, 10);
+// With options:
+const stop = await asciifyLiveVideo('/clip.mp4', canvas, {
+  fontSize: 6,
+  artStyle: 'matrix',
+});
 
-let frameIndex = 0;
-setInterval(() => {
-  renderFrameToCanvas(canvas.getContext('2d')!, frames[frameIndex], opts, canvas.width, canvas.height);
-  frameIndex = (frameIndex + 1) % frames.length;
-}, 1000 / fps);
+// 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();
 ```
 
 ---
@@ -245,11 +254,16 @@ 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>` |
+| `asciiBackground` | `(selector, options)` | `() => void` |
 | `imageToAsciiFrame` | `(source, options, w?, h?)` | `{ frame, cols, rows }` |
 | `renderFrameToCanvas` | `(ctx, frame, options, w, h, time?, hoverPos?)` | `void` |
 | `gifToAsciiFrames` | `(buffer, options, w, h, onProgress?)` | `Promise<{ frames, cols, rows, fps }>` |
 | `videoToAsciiFrames` | `(video, options, w, h, fps?, maxSec?, onProgress?)` | `Promise<{ frames, cols, rows, fps }>` |
-| `asciiBackground` | `(selector, options)` | `() => void` (cleanup) |
 | `generateEmbedCode` | `(frame, options)` | `string` |
 | `generateAnimatedEmbedCode` | `(frames, options, fps)` | `string` |
 

package/dist/index.cjs

@@ -1077,6 +1077,67 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
     cancelAnimationFrame(animId);
   };
 }
+async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {}, onReady, onFrame } = {}) {
+  let video;
+  let ownedVideo = false;
+  if (typeof source === "string") {
+    video = document.createElement("video");
+    video.src = source;
+    video.muted = true;
+    video.loop = true;
+    video.playsInline = true;
+    video.setAttribute("playsinline", "");
+    Object.assign(video.style, {
+      position: "fixed",
+      top: "0",
+      left: "0",
+      width: "1px",
+      height: "1px",
+      opacity: "0",
+      pointerEvents: "none",
+      zIndex: "-1"
+    });
+    document.body.appendChild(video);
+    ownedVideo = true;
+    await new Promise((resolve, reject) => {
+      video.onloadedmetadata = () => resolve();
+      video.onerror = () => reject(new Error(`asciifyLiveVideo: 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 cancelled = false;
+  let animId;
+  const tick = () => {
+    if (cancelled) return;
+    animId = requestAnimationFrame(tick);
+    if (video.readyState < 2 || canvas.width === 0 || canvas.height === 0) return;
+    const { frame } = imageToAsciiFrame(video, merged, canvas.width, canvas.height);
+    if (frame.length > 0) {
+      renderFrameToCanvas(ctx, frame, merged, canvas.width, canvas.height, 0, null);
+      onFrame?.();
+    }
+  };
+  animId = requestAnimationFrame(tick);
+  return () => {
+    cancelled = true;
+    cancelAnimationFrame(animId);
+    if (ownedVideo) {
+      video.pause();
+      video.src = "";
+      document.body.removeChild(video);
+    }
+  };
+}
 
 // src/backgrounds/rain.ts
 function renderRainBackground(ctx, width, height, time, options = {}) {
@@ -2468,6 +2529,7 @@ exports.asciiText = asciiText;
 exports.asciiTextAnsi = asciiTextAnsi;
 exports.asciify = asciify;
 exports.asciifyGif = asciifyGif;
+exports.asciifyLiveVideo = asciifyLiveVideo;
 exports.asciifyVideo = asciifyVideo;
 exports.asciifyWebcam = asciifyWebcam;
 exports.buildTextFrame = buildTextFrame;