asciify-engine 1.0.44 → 1.0.46

package/README.md

@@ -77,58 +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;
 
-// Sizes canvas to the video's native dimensions automatically:
-const stop = await asciifyLiveVideo('/clip.mp4', canvas, { autoSize: true });
+// Minimal
+const stop = await asciifyVideo('/clip.mp4', canvas);
 
-// With art style:
-const stop = await asciifyLiveVideo('/clip.mp4', canvas, {
-  autoSize: true,
-  fontSize: 6,
-  artStyle: 'matrix',
+// Fit canvas to a container and re-size automatically on resize:
+const stop = await asciifyVideo('/clip.mp4', canvas, {
+  fitTo: '#hero',  // or an HTMLElement
 });
 
-// With lifecycle hooks — useful for sizing the canvas, loading indicators, timers:
-const stop = await asciifyLiveVideo('/clip.mp4', canvas, {
+// Lifecycle hooks — ready state, timers, etc.:
+const stop = await asciifyVideo('/clip.mp4', canvas, {
+  fitTo: '#hero',
   fontSize: 6,
-  onReady: (video) => {
-    // Called once when metadata is loaded and playback has started.
-    // Resize the canvas to match the video here, update your UI, etc.
-    canvas.width  = video.videoWidth;
-    canvas.height = video.videoHeight;
-    setReady(true);
-  },
-  onFrame: () => {
-    // Called after every rendered frame.
-    setElapsed(Math.floor(performance.now() / 1000));
-  },
+  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();
-```
 
 ---
 
@@ -148,6 +131,47 @@ All conversion and render functions accept an `AsciiOptions` object. Spread `DEF
 | `hoverEffect` | `string` | `'none'` | Interactive effect driven by cursor position. See hover effects below. |
 | `hoverStrength` | `number` | `0.8` | Effect intensity (0–1). |
 | `hoverRadius` | `number` | `0.3` | Effect radius relative to canvas size (0–1). |
+| `chromaKey` | `{r,g,b} \| string \| null` | `null` | Remove a background colour (green/blue screen). Keyed pixels become transparent spaces. Accepts `{r,g,b}`, any CSS colour string, or `null` to disable. |
+| `chromaKeyTolerance` | `number` | `60` | Euclidean RGB distance threshold for chroma-key detection. `0` = exact match, higher = more pixels removed (max useful ~100). |
+
+### Chroma Key (Green/Blue Screen)
+
+Remove a solid background colour from any source — images, GIFs, or video — so the canvas background shows through keyed pixels.
+
+```ts
+import { asciify, DEFAULT_OPTIONS } from 'asciify-engine';
+
+// Green screen
+asciify(img, canvas, {
+  options: {
+    ...DEFAULT_OPTIONS,
+    chromaKey: '#00ff00',       // CSS colour string — hex, rgb(), named all work
+    chromaKeyTolerance: 60,     // tune to your footage (0 = exact, ~80 = loose)
+    colorMode: 'fullcolor',
+  },
+});
+
+// Blue screen
+asciify(img, canvas, {
+  options: { ...DEFAULT_OPTIONS, chromaKey: 'blue', chromaKeyTolerance: 70 },
+});
+
+// Custom RGB key
+asciify(img, canvas, {
+  options: { ...DEFAULT_OPTIONS, chromaKey: { r: 0, g: 180, b: 90 }, chromaKeyTolerance: 50 },
+});
+
+// Live video with green screen
+asciifyVideo('/footage.mp4', canvas, {
+  fitTo: '#container',
+  options: { ...DEFAULT_OPTIONS, chromaKey: '#00b140', chromaKeyTolerance: 65, colorMode: 'fullcolor' },
+});
+```
+
+**Tolerance guide:**
+- `40–60` — tight key, natural green screen under good lighting
+- `60–80` — broader key, wrinkled fabric or uneven lighting
+- `80–120` — aggressive; expect some spill into the subject
 
 ### Color Modes
 
@@ -274,7 +298,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>` |
@@ -286,6 +309,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

@@ -119,7 +119,9 @@ var DEFAULT_OPTIONS = {
   hoverEffect: "spotlight",
   hoverColor: "#ffffff",
   artStyle: "classic",
-  customText: ""
+  customText: "",
+  chromaKey: null,
+  chromaKeyTolerance: 60
 };
 var HOVER_PRESETS = {
   none: {
@@ -258,6 +260,17 @@ function getCellColorRGB(cell, colorMode, acR, acG, acB) {
   }
   return _colorRGB;
 }
+function parseChromaKeyColor(color) {
+  if (typeof color !== "string") return color;
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext("2d");
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, 1, 1);
+  const d = ctx.getImageData(0, 0, 1, 1).data;
+  return { r: d[0], g: d[1], b: d[2] };
+}
 
 // src/core/animation.ts
 function smoothstep(t) {
@@ -635,6 +648,12 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
     normRange = hi > lo ? hi - lo : 255;
   }
   const frame = [];
+  let ckRGB = null;
+  let ckTolSq = 0;
+  if (options.chromaKey != null) {
+    ckRGB = parseChromaKeyColor(options.chromaKey);
+    ckTolSq = (options.chromaKeyTolerance ?? 60) ** 2;
+  }
   for (let y = 0; y < rows; y++) {
     const row = [];
     for (let x = 0; x < cols; x++) {
@@ -643,6 +662,15 @@ function imageToAsciiFrame(source, options, targetWidth, targetHeight) {
       const g = pixels[i + 1];
       const b = pixels[i + 2];
       const a = pixels[i + 3];
+      if (ckRGB !== null) {
+        const dr = r - ckRGB.r;
+        const dg = g - ckRGB.g;
+        const db = b - ckRGB.b;
+        if (dr * dr + dg * dg + db * db <= ckTolSq) {
+          row.push({ char: " ", r: 0, g: 0, b: 0, a: 0 });
+          continue;
+        }
+      }
       const rawLum = 0.299 * r + 0.587 * g + 0.114 * b;
       const lum = options.normalize ? (rawLum - normMin) / normRange * 255 : rawLum;
       const adjustedLum = adjustLuminance(lum, options.brightness, options.contrast);
@@ -985,6 +1013,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 +1077,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 = {}, autoSize = false, 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,7 +1141,7 @@ 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(() => {
     });
@@ -1110,14 +1150,14 @@ async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "cla
     if (video.paused) await video.play().catch(() => {
     });
   }
-  if (autoSize) {
-    canvas.width = video.videoWidth;
-    canvas.height = video.videoHeight;
+  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);
-  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 = () => {
@@ -1134,6 +1174,7 @@ async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "cla
   return () => {
     cancelled = true;
     cancelAnimationFrame(animId);
+    ro?.disconnect();
     if (ownedVideo) {
       video.pause();
       video.src = "";
@@ -1141,6 +1182,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 = {}) {