asciify-engine 1.0.40 → 1.0.42

package/README.md

@@ -4,201 +4,268 @@
   <a href="https://www.npmjs.com/package/asciify-engine"><img src="https://img.shields.io/npm/v/asciify-engine?color=d4ff00&labelColor=0a0a0a&style=flat-square" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/asciify-engine"><img src="https://img.shields.io/npm/dm/asciify-engine?color=d4ff00&labelColor=0a0a0a&style=flat-square" alt="downloads" /></a>
   <a href="https://github.com/ayangabryl/asciify-engine/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-d4ff00?labelColor=0a0a0a&style=flat-square" alt="MIT license" /></a>
-  <a href="https://www.buymeacoffee.com/asciify"><img src="https://img.shields.io/badge/buy_me_a_coffee-☕-d4ff00?labelColor=0a0a0a&style=flat-square" alt="Buy Me A Coffee" /></a>
+  <a href="https://www.buymeacoffee.com/asciify"><img src="https://img.shields.io/badge/buy_me_a_coffee-%E2%98%95-d4ff00?labelColor=0a0a0a&style=flat-square" alt="Buy Me A Coffee" /></a>
 </p>
 
-Turn any image, video, or GIF into ASCII art on an HTML canvas — with live animated backgrounds, hover effects, and zero dependencies.
+A framework-agnostic ASCII art rendering engine for the browser. Convert images, animated GIFs, and video into character-based art rendered onto an HTML canvas — with full color support, animated backgrounds, interactive hover effects, and embed generation. Zero runtime dependencies.
 
-**[▶ Try the live playground](https://asciify.org) · [npm](https://www.npmjs.com/package/asciify-engine)**
+**[&#9654; Live Playground](https://asciify.org) &middot; [npm](https://www.npmjs.com/package/asciify-engine)**
 
 ---
 
-## Install
+## Overview
+
+asciify-engine works in two stages:
+
+1. **Convert** — a source (image, GIF buffer, video element) is sampled and converted into an `AsciiFrame`: a 2D array of character cells, each carrying a character and RGBA color data.
+2. **Render** — the frame is drawn onto a `<canvas>` element via a 2D context, with full support for color modes, font sizes, hover effects, and time-based animations.
+
+This separation means you can pre-compute frames once and render them at any frame rate, making it efficient for both static images and smooth animations.
+
+---
+
+## Installation
 
 ```bash
 npm install asciify-engine
 ```
 
+Works with any modern bundler (Vite, webpack, esbuild, Rollup) and any framework — React, Vue, Svelte, Angular, Next.js, or vanilla JS.
+
 ---
 
-## The 30-second version
+## Converting Media to ASCII
+
+### Images
+
+`imageToAsciiFrame` accepts any `HTMLImageElement`, `HTMLVideoElement`, or `HTMLCanvasElement` and returns a single ASCII frame.
 
 ```ts
 import { imageToAsciiFrame, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
 
 const img = new Image();
-img.src = 'your-image.jpg';
+img.crossOrigin = 'anonymous';
+img.src = 'photo.jpg';
+
 img.onload = () => {
   const canvas = document.getElementById('ascii') as HTMLCanvasElement;
-  const { frame } = imageToAsciiFrame(img, DEFAULT_OPTIONS, canvas.width, canvas.height);
-  renderFrameToCanvas(canvas.getContext('2d')!, frame, DEFAULT_OPTIONS, canvas.width, canvas.height);
+  const ctx    = canvas.getContext('2d')!;
+  const opts   = { ...DEFAULT_OPTIONS, fontSize: 10, colorMode: 'fullcolor' as const };
+
+  const { frame } = imageToAsciiFrame(img, opts, canvas.width, canvas.height);
+  renderFrameToCanvas(ctx, frame, opts, canvas.width, canvas.height);
 };
 ```
 
-That's it — one function to convert, one to draw. Everything else is optional.
+### Animated GIFs
 
----
+`gifToAsciiFrames` parses a GIF `ArrayBuffer` and returns one `AsciiFrame` per GIF frame, preserving the original frame rate.
 
-## Animated backgrounds
+```ts
+import { gifToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
 
-Add a living ASCII animation to any element with one line:
+const buffer = await fetch('animation.gif').then(r => r.arrayBuffer());
+const canvas = document.getElementById('ascii') as HTMLCanvasElement;
+const opts   = { ...DEFAULT_OPTIONS, fontSize: 8 };
 
-```ts
-import { asciiBackground } from 'asciify-engine';
+const { frames, fps } = await gifToAsciiFrames(buffer, opts, canvas.width, canvas.height);
 
-asciiBackground('#hero', { type: 'rain' });
+let frameIndex = 0;
+setInterval(() => {
+  renderFrameToCanvas(canvas.getContext('2d')!, frames[frameIndex], opts, canvas.width, canvas.height);
+  frameIndex = (frameIndex + 1) % frames.length;
+}, 1000 / fps);
 ```
 
-Returns a cleanup function when you're done:
+### Video — live (recommended)
+
+`asciifyLiveVideo` streams a video as ASCII art in real time. Pass a URL and a canvas — it handles everything else.
+
+> ⚠️ 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.
 
 ```ts
-const stop = asciiBackground('#hero', { type: 'aurora', colorScheme: 'auto' });
-// later…
+import { asciifyLiveVideo } 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, {
+  fontSize: 6,
+  artStyle: 'matrix',
+});
+
+// Clean up:
 stop();
 ```
 
-**Available types:** `wave` · `rain` · `stars` · `pulse` · `noise` · `grid` · `aurora` · `silk` · `void` · `morph`
+### Video — pre-extracted frames
 
-**Common options:**
+`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
-asciiBackground('#el', {
-  type: 'stars',
-  colorScheme: 'auto',   // 'auto' | 'light' | 'dark' — 'auto' follows OS theme
-  fontSize: 13,          // character size in px
-  speed: 1.2,            // animation speed multiplier
-  density: 0.6,          // how many cells are active (0–1)
-  accentColor: '#d4ff00' // highlight colour
-});
+import { asciifyVideo } from 'asciify-engine';
+
+const canvas = document.getElementById('ascii') as HTMLCanvasElement;
+const stop   = await asciifyVideo('/clip.mp4', canvas, { fontSize: 8 });
+stop();
 ```
 
 ---
 
-## More recipes
+## Rendering Options
 
-### React
+All conversion and render functions accept an `AsciiOptions` object. Spread `DEFAULT_OPTIONS` as a base and override what you need.
 
-```tsx
-import { useEffect, useRef } from 'react';
-import { imageToAsciiFrame, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fontSize` | `number` | `10` | Character cell size in pixels. Smaller values increase density and detail. |
+| `colorMode` | `'grayscale' \| 'fullcolor' \| 'matrix' \| 'accent'` | `'grayscale'` | Determines how pixel color is mapped to character color. |
+| `charset` | `string` | Standard ramp | Characters ordered from dense to sparse, representing brightness levels. |
+| `brightness` | `number` | `0` | Brightness adjustment from `-1` (darker) to `1` (lighter). |
+| `contrast` | `number` | `1` | Contrast multiplier applied before character mapping. |
+| `invert` | `boolean` | `false` | Inverts the luminance mapping — light areas become dense, dark areas sparse. |
+| `renderMode` | `'ascii' \| 'dots'` | `'ascii'` | Render as text characters or circular dot particles. |
+| `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). |
 
-export function AsciiImage({ src }: { src: string }) {
-  const ref = useRef<HTMLCanvasElement>(null);
+### Color Modes
 
-  useEffect(() => {
-    const img = new Image();
-    img.crossOrigin = 'anonymous';
-    img.src = src;
-    img.onload = () => {
-      const canvas = ref.current!;
-      const opts = { ...DEFAULT_OPTIONS, fontSize: 10, colorMode: 'fullcolor' as const };
-      const { frame } = imageToAsciiFrame(img, opts, canvas.width, canvas.height);
-      renderFrameToCanvas(canvas.getContext('2d')!, frame, opts, canvas.width, canvas.height);
-    };
-  }, [src]);
+| Mode | Description |
+|---|---|
+| `grayscale` | Classic monochrome ASCII. Character brightness maps to source luminance. |
+| `fullcolor` | Each character inherits the original pixel color from the source. |
+| `matrix` | Monochrome green — inspired by classic terminal aesthetics. |
+| `accent` | Single accent color applied uniformly across all characters. |
 
-  return <canvas ref={ref} width={800} height={600} />;
-}
-```
+### Hover Effects
 
-### Animated GIF
+Interactive effects that respond to cursor movement. Pass the effect name to `hoverEffect` and supply the cursor position to `renderFrameToCanvas` at render time.
 
-```ts
-import { gifToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+Available effects: `spotlight` · `flashlight` · `magnifier` · `force-field` · `neon` · `fire` · `ice` · `gravity` · `shatter` · `ghost`
 
-const buf = await fetch('animation.gif').then(r => r.arrayBuffer());
-const canvas = document.getElementById('ascii') as HTMLCanvasElement;
-const opts = { ...DEFAULT_OPTIONS, fontSize: 8 };
+```ts
+canvas.addEventListener('mousemove', (e) => {
+  const rect = canvas.getBoundingClientRect();
+  renderFrameToCanvas(ctx, frame, opts, canvas.width, canvas.height, Date.now() / 1000, {
+    x: e.clientX - rect.left,
+    y: e.clientY - rect.top,
+  });
+});
+```
 
-const { frames, fps } = await gifToAsciiFrames(buf, opts, canvas.width, canvas.height);
+---
 
-let i = 0;
-setInterval(() => {
-  renderFrameToCanvas(canvas.getContext('2d')!, frames[i], opts, canvas.width, canvas.height);
-  i = (i + 1) % frames.length;
-}, 1000 / fps);
-```
+## Animated Backgrounds
 
-### Video
+`asciiBackground` mounts a self-animating ASCII renderer onto any DOM element — ideal for hero sections, banners, or full-page backgrounds. It manages its own canvas, animation loop, and resize handling internally.
 
 ```ts
-import { videoToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+import { asciiBackground } from 'asciify-engine';
 
-const video = document.createElement('video');
-video.src = '/clip.mp4';
-await new Promise(r => (video.onloadeddata = r));
+const stop = asciiBackground('#hero', {
+  type: 'rain',
+  colorScheme: 'auto', // follows OS dark/light mode
+  speed: 1.0,
+  density: 0.55,
+  accentColor: '#d4ff00',
+});
 
-const canvas = document.getElementById('ascii') as HTMLCanvasElement;
-const opts = { ...DEFAULT_OPTIONS, fontSize: 8 };
+// Stop and clean up when no longer needed
+stop();
+```
 
-const { frames, fps } = await videoToAsciiFrames(video, opts, canvas.width, canvas.height);
+### Available Background Types
 
-let i = 0;
-setInterval(() => {
-  renderFrameToCanvas(canvas.getContext('2d')!, frames[i], opts, canvas.width, canvas.height);
-  i = (i + 1) % frames.length;
-}, 1000 / fps);
-```
+| Type | Description |
+|---|---|
+| `wave` | Flowing sine-wave field with layered noise turbulence |
+| `rain` | Vertical column rain with a glowing leading character and fading trail |
+| `stars` | Parallax star field that reacts to cursor position |
+| `pulse` | Concentric ripple bursts emanating from the cursor |
+| `noise` | Smooth value-noise field with organic, fluid motion |
+| `grid` | Geometric grid that warps and brightens near the cursor |
+| `aurora` | Sweeping borealis-style color bands drifting across the field |
+| `silk` | Fluid swirl simulation following cursor movement |
+| `void` | Gravitational singularity — characters spiral inward toward the cursor |
+| `morph` | Characters morph between shapes over time, driven by noise |
+
+### Background Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | `'wave'` | Which background renderer to use. |
+| `colorScheme` | `'auto' \| 'light' \| 'dark'` | `'dark'` | `'auto'` reacts to OS theme changes in real time. |
+| `fontSize` | `number` | `13` | Character size in pixels. |
+| `speed` | `number` | `1` | Global animation speed multiplier. |
+| `density` | `number` | `0.55` | Fraction of grid cells that are active (0–1). |
+| `accentColor` | `string` | varies | Highlight or leading-character color (any CSS color string). |
+| `color` | `string` | — | Override the body character color. |
 
 ---
 
-## Tweaking the output
+## React Integration
 
-Pass options to any function to change the look:
+```tsx
+import { useEffect, useRef } from 'react';
+import { imageToAsciiFrame, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
 
-```ts
-const opts = {
-  ...DEFAULT_OPTIONS,
-  fontSize: 8,                // smaller = more detail
-  colorMode: 'matrix',        // 'grayscale' | 'fullcolor' | 'matrix' | 'accent'
-  charset: '@#S%?*+;:,. ',   // custom brightness ramp (dense → light)
-  brightness: 0.1,            // -1 to 1
-  contrast: 1.2,
-  invert: false,
-  hoverEffect: 'spotlight',   // interactive effect on cursor move
-};
-```
+export function AsciiImage({ src }: { src: string }) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
 
-**Color modes at a glance:**
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
 
-| Mode | What it does |
-|---|---|
-| `grayscale` | Classic monochrome ASCII |
-| `fullcolor` | Preserves original pixel colours |
-| `matrix` | Everything in green, like the film |
-| `accent` | Single highlight colour |
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+    img.src = src;
+    img.onload = () => {
+      const opts = { ...DEFAULT_OPTIONS, fontSize: 10, colorMode: 'fullcolor' as const };
+      const { frame } = imageToAsciiFrame(img, opts, canvas.width, canvas.height);
+      renderFrameToCanvas(canvas.getContext('2d')!, frame, opts, canvas.width, canvas.height);
+    };
+  }, [src]);
 
-**Hover effects:** `spotlight` · `flashlight` · `magnifier` · `force-field` · `neon` · `fire` · `ice` · `gravity` · `shatter` · `ghost`
+  return <canvas ref={canvasRef} width={800} height={600} />;
+}
+```
 
 ---
 
-## Embed generation
+## Embed Generation
 
-Export your ASCII art as a self-contained HTML file:
+Generate self-contained HTML that can be hosted anywhere or dropped directly into a page — no runtime dependency required.
 
 ```ts
 import { generateEmbedCode, generateAnimatedEmbedCode } from 'asciify-engine';
 
-// Static image
-const html = generateEmbedCode(frame, options);
+// Static — produces a single-file HTML with the ASCII art baked in
+const staticHtml = generateEmbedCode(frame, options);
 
-// Animated
-const html = generateAnimatedEmbedCode(frames, options, fps);
+// Animated — produces a self-running HTML animation
+const animatedHtml = generateAnimatedEmbedCode(frames, options, fps);
 ```
 
 ---
 
-## API summary
-
-| Function | Description |
-|---|---|
-| `imageToAsciiFrame(img, opts, w, h)` | Convert an image/video/canvas element to an ASCII frame |
-| `renderFrameToCanvas(ctx, frame, opts, w, h, time?, pos?)` | Draw an ASCII frame onto a canvas 2D context |
-| `gifToAsciiFrames(buffer, opts, w, h)` | Parse an animated GIF into ASCII frames |
-| `videoToAsciiFrames(video, opts, w, h, fps?, maxSec?)` | Extract video frames and convert them to ASCII |
-| `asciiBackground(selector, opts)` | Mount a live animated ASCII background |
-| `generateEmbedCode(frame, opts)` | Self-contained static HTML snippet |
-| `generateAnimatedEmbedCode(frames, opts, fps)` | Self-contained animated HTML snippet |
+## API Reference
+
+| 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 }>` |
+| `generateEmbedCode` | `(frame, options)` | `string` |
+| `generateAnimatedEmbedCode` | `(frames, options, fps)` | `string` |
 
 ---
 

package/dist/index.cjs

@@ -1077,6 +1077,62 @@ async function asciifyVideo(source, canvas, { fontSize = 10, artStyle = "classic
     cancelAnimationFrame(animId);
   };
 }
+async function asciifyLiveVideo(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
+  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}"`));
+    });
+    video.play().catch(() => {
+    });
+  } else {
+    video = source;
+    if (video.paused) video.play().catch(() => {
+    });
+  }
+  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);
+  };
+  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 +2524,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;