API Reference

Three tiers: a one-call convenience API, a low-level frame API for custom render loops, and a recording API for exports.

One-call API

fnasciify(source, canvas, options?)

→ Promise<void>

Convert an image (URL string, HTMLImageElement, HTMLVideoElement, or HTMLCanvasElement) and render onto a canvas. Handles loading, conversion, and rendering in one call.

fnasciifyGif(source, canvas, options?)

→ Promise<() => void>

Fetch and animate an animated GIF as ASCII art. Source can be a URL string or ArrayBuffer. Returns a stop() function to cancel the animation loop.

fnasciifyVideo(source, canvas, options?)

→ Promise<() => void>

Stream a video as live ASCII art in real time. Defaults to live streaming (instant start, unlimited duration). Pass preExtract: true for frame-perfect pre-extracted loops. Pass fitTo to auto-size the canvas to a container. Use trim: { start, end } to play only a slice of the video. Use chromaKey: true to remove green screens. Returns a stop() function.

live vs pre-extracted

Live comparison

asciifyLiveVideo()

press run →

Streams live from the playing video — instant start, constant memory, unlimited duration. Best for hero sections, loops, webcam.

const stop = await asciifyLiveVideo(src, canvas);

asciifyVideo()

press run →

Pre-extracts every frame before playing — loading delay, memory-intensive, 10s cap. Best for short clips where you need frame-perfect control.

const stop = await asciifyVideo(src, canvas);

	asciifyLiveVideo	asciifyVideo
Startup	instant	seconds (extracts first)
Memory	constant	grows with clip length
Max duration	unlimited	10s cap
Seeking	✕	✓ frame-perfect
Best for	loops · hero · webcam	short clips · scrub

Shared options shape

{
  fontSize?: number;                // character size in px — default: 10
  artStyle?: ArtStyle;              // preset name — default: 'classic'
  options?: Partial<AsciiOptions>;  // any field from the full AsciiOptions object
  // asciifyVideo only:
  fitTo?: HTMLElement | string;     // fit canvas to container + auto-resize
  preExtract?: boolean;             // pre-decode all frames (default: false)
  trim?: { start?: number; end?: number }; // play a time slice (seconds)
  onReady?: (video) => void;        // called once when ready
  onFrame?: () => void;             // called after every frame
}

ASCII Background API

fnasciiBackground(target, options?)

→ { destroy: () => void }

Mount a live animated ASCII canvas behind any element. Target can be an HTMLElement or CSS selector string. The canvas is automatically sized, updated on window resize, and respects OS color scheme. Call destroy() to stop and remove the canvas.

Low-level API

Use these when you need full control — custom render loops, compositing, or embed code generation.

fnimageToAsciiFrame(source, options, targetWidth?, targetHeight?)

→ { frame: AsciiFrame; cols: number; rows: number }

Convert an image, video frame, or canvas to a single AsciiFrame. Reads pixel data including alpha. Returns a 2D cell grid indexed [row][col].

fnrenderFrameToCanvas(ctx, frame, options, canvasWidth, canvasHeight, time?, hoverPos?)

→ void

Render a single AsciiFrame onto a 2D canvas context. Supports ASCII and Dots render modes, animation effects, and interactive hover. Optimized for 60+ FPS.

fngifToAsciiFrames(buffer, options, targetWidth, targetHeight, onProgress?)

→ Promise<{ frames, cols, rows, fps }>

Parse an animated GIF (ArrayBuffer) and convert every frame to ASCII. Handles GIF disposal methods, compositing, and frame timing. Capped at 300 frames.

fnvideoToAsciiFrames(video, options, targetWidth, targetHeight, targetFps?, maxDuration?, onProgress?)

→ Promise<{ frames, cols, rows, fps }>

Seek through a video element at the given FPS rate and convert each frame to ASCII. maxDuration limits extraction (default: 10s).

Snapshot API

Capture a single frame from a live ASCII canvas as a PNG, JPEG, or WebP.

fncaptureSnapshot(canvas, options?)

→ Promise<Blob>

Capture a single frame from a canvas as a Blob. Supports png, jpeg, and webp formats with optional quality and scale.

fnsnapshotAndDownload(canvas, options?)

→ Promise<void>

Capture a single frame and immediately trigger a browser download. Combines captureSnapshot with a temporary object URL.

Snapshot example

import { captureSnapshot, snapshotAndDownload } from 'asciify-engine';

// Get a Blob you can upload or preview
const blob = await captureSnapshot(canvas, { format: 'png' });
const url = URL.createObjectURL(blob);

// Or trigger a download directly
await snapshotAndDownload(canvas, { format: 'jpeg', filename: 'my-art' });

Data types

types.d.ts

interface AsciiCell {
  char: string;  // Character mapped from luminance
  r: number;     // Red component   (0–255)
  g: number;     // Green component (0–255)
  b: number;     // Blue component  (0–255)
  a: number;     // Alpha channel   (0–255)
}

type AsciiFrame = AsciiCell[][];  // 2D grid [row][col]

interface AsciiResult {
  frames: AsciiFrame[];
  cols:   number;
  rows:   number;
  fps:    number;
}