asciify-engine 1.0.34 → 1.0.35

package/README.md

@@ -9,6 +9,385 @@
 
 > Convert images, videos, and GIFs into ASCII art on HTML canvas. 13 art styles, 4 color modes, 10 animated backgrounds, interactive hover effects — zero dependencies.
 
+**[▶ Live Playground](https://asciify.org) · [npm](https://www.npmjs.com/package/asciify-engine) · [Support the project ☕](https://www.buymeacoffee.com/asciify)**
+
+## Features
+
+- **Media → ASCII** — images, videos, and animated GIFs
+- **13 art styles** — Standard, Blocks, Circles, Braille, Katakana, Dense, and more
+- **4 color modes** — Grayscale, Full Color, Matrix, Accent
+- **10 animated backgrounds** — Wave, Rain, Stars, Pulse, Noise, Grid, Aurora, Silk, Void, Morph
+- **Interactive hover effects** — Spotlight, Flashlight, Magnifier, Force Field, Neon, Fire, Ice, Gravity, Shatter, Ghost
+- **Light & dark mode** — via `colorScheme: 'auto'` or explicit `light` / `dark`
+- **Embed generation** — self-contained HTML output (static or animated)
+- **Zero dependencies** — works with React, Vue, Angular, Svelte, Next.js, or vanilla JS
+
+## Install
+
+```bash
+npm install asciify-engine
+```
+
+> **90% of use cases need only two functions:** `asciify()` to convert images/video/GIFs to ASCII art, and `asciiBackground()` for animated backgrounds. Start there.
+
+## Quick Start
+
+### Image → ASCII
+
+```ts
+import { asciify } from 'asciify-engine';
+
+const canvas = document.querySelector('canvas')!;
+
+// Minimal — just a URL and a canvas, no img.onload boilerplate needed
+await asciify('https://example.com/photo.jpg', canvas);
+
+// With an art style preset
+await asciify('photo.jpg', canvas, { artStyle: 'letters' });
+
+// Full control
+await asciify('photo.jpg', canvas, {
+  fontSize: 8,
+  artStyle: 'art',
+  options: {
+    colorMode: 'fullcolor',
+    invert: true,
+    hoverEffect: 'spotlight',
+    hoverStrength: 0.5,
+  },
+});
+```
+
+### GIF Animation
+
+```ts
+import { asciifyGif } from 'asciify-engine';
+
+// Fetches, converts, and starts the animation loop — returns a stop() function
+const stop = await asciifyGif('animation.gif', canvas);
+
+// Clean up the animation loop when done
+stop();
+```
+
+### Video
+
+```ts
+import { asciifyVideo } from 'asciify-engine';
+
+// Accepts a URL string or an existing HTMLVideoElement
+const stop = await asciifyVideo('/my-video.mp4', canvas, { artStyle: 'terminal' });
+
+// Cancel when unmounting / navigating away
+stop();
+```
+
+### React
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { asciify } from 'asciify-engine';
+
+export function AsciiImage({ src }: { src: string }) {
+  const ref = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    if (ref.current) asciify(src, ref.current, { artStyle: 'art' });
+  }, [src]);
+
+  return <canvas ref={ref} width={800} height={600} />;
+}
+```
+
+### Animated GIF or video in React
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { asciifyGif } from 'asciify-engine';
+
+export function AsciiGif({ src }: { src: string }) {
+  const ref = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    let stop: (() => void) | undefined;
+    asciifyGif(src, ref.current!).then(fn => { stop = fn; });
+    return () => stop?.();  // cancels the rAF loop on unmount
+  }, [src]);
+
+  return <canvas ref={ref} width={800} height={600} />;
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <canvas ref="canvasRef" width="800" height="600" />
+</template>
+
+<script setup lang="ts">
+import { useTemplateRef, onMounted } from 'vue';
+import { asciify } from 'asciify-engine';
+
+const props = defineProps<{ src: string; artStyle?: string }>();
+const canvasRef = useTemplateRef<HTMLCanvasElement>('canvasRef');
+
+onMounted(() => asciify(props.src, canvasRef.value!, { artStyle: props.artStyle as any }));
+</script>
+```
+
+### Angular
+
+```typescript
+import { Component, ElementRef, ViewChild, AfterViewInit, Input } from '@angular/core';
+import { asciify } from 'asciify-engine';
+
+@Component({
+  selector: 'app-ascii',
+  template: `<canvas #canvas width="800" height="600"></canvas>`,
+})
+export class AsciiComponent implements AfterViewInit {
+  @ViewChild('canvas') canvasRef!: ElementRef<HTMLCanvasElement>;
+  @Input() src = '';
+  @Input() artStyle = 'classic';
+
+  ngAfterViewInit() {
+    asciify(this.src, this.canvasRef.nativeElement, { artStyle: this.artStyle as any });
+  }
+}
+```
+
+## Animated Backgrounds
+
+Drop a live ASCII animation into any element with one call.
+
+```ts
+import { asciiBackground } from 'asciify-engine';
+
+// Attach to any selector — animates the element's background
+asciiBackground('#hero', { type: 'rain' });
+
+// Follows OS dark/light mode automatically
+asciiBackground('#hero', { type: 'aurora', colorScheme: 'auto' });
+
+// Force light mode (dark characters on light background)
+asciiBackground('#hero', { type: 'wave', colorScheme: 'light' });
+
+// Stop / clean up
+const stop = asciiBackground('#hero', { type: 'stars' });
+stop();
+```
+
+### Background Types
+
+| Type | Description |
+|---|---|
+| `wave` | Flowing sine-wave field with noise turbulence |
+| `rain` | Matrix-style vertical column rain with glowing head and fading tail |
+| `stars` | Parallax star field that reacts to cursor position |
+| `pulse` | Concentric ripple bursts that emanate from the cursor |
+| `noise` | Smooth value-noise field with organic flow |
+| `grid` | Geometric grid that warps and glows at cursor proximity |
+| `aurora` | Sweeping borealis-style colour bands |
+| `silk` | Silky fluid swirls following the cursor |
+| `void` | Gravitational singularity — characters spiral inward toward cursor |
+| `morph` | Characters morph between shapes driven by noise |
+
+### `asciiBackground` Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | `'wave'` | Which background renderer to use |
+| `colorScheme` | `'auto' \| 'light' \| 'dark'` | `'dark'` | `'auto'` follows OS theme live; `'light'` = dark chars on light bg |
+| `fontSize` | `number` | `13` | Character size in px |
+| `accentColor` | `string` | varies | Head/highlight colour (CSS colour string) |
+| `color` | `string` | — | Override body character colour |
+| `speed` | `number` | `1` | Global animation speed multiplier |
+| `density` | `number` | `0.55` | Fraction of cells active (0–1) |
+| `lightMode` | `boolean` | `false` | Dark characters on light background |
+
+Each background type also accepts its own specific options — see the individual type exports (e.g. `RainBackgroundOptions`, `WaveBackgroundOptions`, etc.) for the full list.
+
+### Low-level background renderers
+
+All renderers are also exported individually for direct canvas use:
+
+```ts
+import { renderRainBackground } from 'asciify-engine';
+
+const canvas = document.getElementById('canvas') as HTMLCanvasElement;
+const ctx = canvas.getContext('2d')!;
+let t = 0;
+
+function tick() {
+  renderRainBackground(ctx, canvas.width, canvas.height, t, {
+    speed: 1.2,
+    density: 0.6,
+    accentColor: '#00ffcc',
+    lightMode: false,
+  });
+  t += 0.016;
+  requestAnimationFrame(tick);
+}
+tick();
+```
+
+## Low-level API
+
+For cases where the one-call API is too limiting — direct frame manipulation, custom render loops, progress callbacks, etc.
+
+### GIF (low-level)
+
+```ts
+import { gifToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+
+const buffer = await fetch('animation.gif').then(r => r.arrayBuffer());
+const options = { ...DEFAULT_OPTIONS, fontSize: 8 };
+const { frames, fps } = await gifToAsciiFrames(buffer, options, canvas.width, canvas.height);
+
+const ctx = canvas.getContext('2d')!;
+let i = 0;
+let last = performance.now();
+const interval = 1000 / fps;
+
+let animId: number;
+const tick = (now: number) => {
+  if (now - last >= interval) {
+    renderFrameToCanvas(ctx, frames[i], options, canvas.width, canvas.height);
+    i = (i + 1) % frames.length;
+    last = now;
+  }
+  animId = requestAnimationFrame(tick);
+};
+animId = requestAnimationFrame(tick);
+
+// Clean up → cancelAnimationFrame(animId);
+```
+
+### Video (low-level)
+
+```ts
+import { videoToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+
+const video = document.createElement('video');
+video.crossOrigin = 'anonymous';
+video.src = '/my-video.mp4';
+// Guard against cached video where onloadeddata already fired
+if (video.readyState < 2) {
+  await new Promise<void>(r => { video.onloadeddata = () => r(); });
+}
+
+const options = { ...DEFAULT_OPTIONS, fontSize: 8 };
+const { frames, fps } = await videoToAsciiFrames(video, options, canvas.width, canvas.height, 12, 10);
+
+const ctx = canvas.getContext('2d')!;
+let i = 0;
+let last = performance.now();
+const interval = 1000 / fps;
+
+let animId: number;
+const tick = (now: number) => {
+  if (now - last >= interval) {
+    renderFrameToCanvas(ctx, frames[i], options, canvas.width, canvas.height);
+    i = (i + 1) % frames.length;
+    last = now;
+  }
+  animId = requestAnimationFrame(tick);
+};
+animId = requestAnimationFrame(tick);
+
+// Clean up → cancelAnimationFrame(animId);
+```
+
+### Vanilla JS (low-level image)
+
+```html
+<canvas id="ascii" width="800" height="600"></canvas>
+<script type="module">
+  import { imageToAsciiFrame, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+
+  const canvas = document.getElementById('ascii');
+  const ctx = canvas.getContext('2d');
+  const options = { ...DEFAULT_OPTIONS, fontSize: 10 };
+
+  const img = new Image();
+  img.crossOrigin = 'anonymous';
+  img.src = 'https://picsum.photos/600/400';
+  img.onload = () => {
+    const { frame } = imageToAsciiFrame(img, options, canvas.width, canvas.height);
+    renderFrameToCanvas(ctx, frame, options, canvas.width, canvas.height);
+  };
+</script>
+```
+
+## API Reference
+
+### Core Functions
+
+| Function | Returns | Description |
+|---|---|---|
+| `asciify(source, canvas, opts?)` | `Promise<void>` | Convert an image/video/canvas (or URL) to ASCII and render — handles loading automatically |
+| `asciifyGif(source, canvas, opts?)` | `Promise<() => void>` | Fetch a GIF, convert, and start an animation loop — returns `stop()` |
+| `asciifyVideo(source, canvas, opts?)` | `Promise<() => void>` | Convert a video and start an animation loop — returns `stop()` |
+| `imageToAsciiFrame(source, options, w?, h?)` | `{ frame, cols, rows }` | Convert an image, video frame, or canvas to a raw ASCII frame |
+| `renderFrameToCanvas(ctx, frame, options, w, h, time?, hoverPos?)` | `void` | Render a raw ASCII frame to a 2D canvas context |
+| `gifToAsciiFrames(buffer, options, w, h, onProgress?)` | `{ frames, cols, rows, fps }` | Parse an animated GIF `ArrayBuffer` into ASCII frames |
+| `videoToAsciiFrames(video, options, w, h, fps?, maxDuration?, onProgress?)` | `{ frames, cols, rows, fps }` | Extract and convert video frames to ASCII |
+| `asciiBackground(selector, options)` | `() => void` | Mount a live animated ASCII background; returns a cleanup function |
+| `generateEmbedCode(frame, options)` | `string` | Self-contained static HTML embed |
+| `generateAnimatedEmbedCode(frames, options, fps)` | `string` | Self-contained animated HTML embed |
+
+### Simple API Options (`AsciifySimpleOptions`)
+
+Used by `asciify()`, `asciifyGif()`, and `asciifyVideo()`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fontSize` | `number` | `10` | Character cell size in px |
+| `artStyle` | `ArtStyle` | `'classic'` | Art style preset — sets charset, render mode, and color mode together |
+| `options` | `Partial<AsciiOptions>` | `{}` | Fine-grained overrides applied on top of the preset |
+
+### Key Options (`AsciiOptions`)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fontSize` | `number` | `10` | Character cell size in px |
+| `colorMode` | `'grayscale' \| 'fullcolor' \| 'matrix' \| 'accent'` | `'grayscale'` | Color output mode |
+| `renderMode` | `'ascii' \| 'dots'` | `'ascii'` | Render as characters or dot particles |
+| `charset` | `string` | `' .:-=+*#%@'` | Custom character density ramp (light → dark) |
+| `brightness` | `number` | `0` | Brightness adjustment (−1 → 0 → 1) |
+| `contrast` | `number` | `0` | Contrast boost (0 = unchanged, positive = more contrast) |
+| `invert` | `boolean` | `false` | Invert luminance mapping |
+| `animationStyle` | `AnimationStyle` | `'none'` | Per-character animation driven over time |
+| `hoverEffect` | `HoverEffect` | `'spotlight'` | Cursor interaction style |
+| `hoverStrength` | `number` | `0` | Effect intensity (0 = disabled) |
+| `hoverRadius` | `number` | `0.2` | Effect radius as a fraction of canvas size |
+| `artStyle` | `ArtStyle` | `'classic'` | Art style preset (see `ART_STYLE_PRESETS`) |
+| `ditherStrength` | `number` | `0` | Floyd-Steinberg dither intensity (0–1) |
+| `dotSizeRatio` | `number` | `0.8` | Dot size when `renderMode === 'dots'` (fraction of cell) |
+
+### Background Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | `'wave'` | Background renderer |
+| `colorScheme` | `'auto' \| 'light' \| 'dark'` | `'dark'` | Theme; `'auto'` follows OS preference |
+| `fontSize` | `number` | `13` | Character size |
+| `speed` | `number` | `1` | Animation speed multiplier |
+| `density` | `number` | `0.55` | Fraction of cells active (0–1) |
+| `accentColor` | `string` | varies | Highlight / head colour |
+
+## License
+
+MIT © [asciify.org](https://asciify.org)
+
+---
+
+<p align="left">
+  <a href="https://www.buymeacoffee.com/asciify">☕ Buy me a coffee — if this saved you time, I'd appreciate it!</a>
+</p>
+
+
 **[▶ Live Playground](https://asciify.org) · [npm](https://www.npmjs.com/package/asciify-engine) · [Support the project ☕](https://www.buymeacoffee.com/asciify)**
 
 ## Features

package/dist/index.cjs

@@ -970,7 +970,7 @@ function renderFrameToCanvas(ctx, frame, options, canvasWidth, canvasHeight, tim
 }
 
 // src/core/simple-api.ts
-async function asciify(source, canvas, { fontSize = 10, style = "classic", options = {} } = {}) {
+async function asciify(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
   let el;
   if (typeof source === "string") {
     const img = new Image();
@@ -990,16 +990,16 @@ async function asciify(source, canvas, { fontSize = 10, style = "classic", optio
   } else {
     el = source;
   }
-  const preset = ART_STYLE_PRESETS[style];
+  const preset = ART_STYLE_PRESETS[artStyle];
   const merged = { ...DEFAULT_OPTIONS, ...preset, ...options, fontSize };
   const ctx = canvas.getContext("2d");
   if (!ctx) throw new Error("Could not get 2d context from canvas");
   const { frame } = imageToAsciiFrame(el, merged, canvas.width, canvas.height);
   renderFrameToCanvas(ctx, frame, merged, canvas.width, canvas.height);
 }
-async function asciifyGif(source, canvas, { fontSize = 10, style = "classic", options = {} } = {}) {
+async function asciifyGif(source, canvas, { fontSize = 10, artStyle = "classic", options = {} } = {}) {
   const buffer = typeof source === "string" ? await fetch(source).then((r) => r.arrayBuffer()) : source;
-  const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[style], ...options, fontSize };
+  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 gifToAsciiFrames(buffer, merged, canvas.width, canvas.height);
@@ -1023,20 +1023,22 @@ async function asciifyGif(source, canvas, { fontSize = 10, style = "classic", op
     cancelAnimationFrame(animId);
   };
 }
-async function asciifyVideo(source, canvas, { fontSize = 10, style = "classic", options = {} } = {}) {
+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;
-    await new Promise((resolve, reject) => {
-      video.onloadeddata = () => resolve();
-      video.onerror = () => reject(new Error(`Failed to load video: ${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;
   }
-  const merged = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[style], ...options, fontSize };
+  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);