# ascii.cafe: full agent and developer reference
> Browser workflows, settings keys, engine options and export limits. Generated from the product overview and the reference records used by /devs.
Read [the overview](https://ascii.cafe/llms.txt) for a shorter introduction or [the developer reference](https://ascii.cafe/devs) for interactive examples. The tables below share the website's reference data; implementation takes precedence if a description disagrees with runtime behavior. This document describes browser use, not a hosted rendering API.
## Product overview
> Turn images, video, your camera and your screen into living ASCII, glyph, halftone and dither art in the browser.
ascii.cafe is an interactive art workspace at /app, with a live playground, presets and curated artwork on the homepage. Rendering and file exports happen locally. Visitors do not need an account to create or export artwork. Optional feature submissions upload a rendered creation only after consent; original files are not uploaded, though enabled original backgrounds contribute rendered pixels.
### For AI agents
Agents are welcome to use ascii.cafe to create artwork for users. Agents with browser-control tools can operate the same /app workspace, edit settings, and export within the active plan's limits. No account is needed for the free workflow.
1. Read the [settings reference](https://ascii.cafe/devs#links) for supported keys and values.
2. Open a configured workspace. For example, [a Terminal-colored sphere](https://ascii.cafe/app?v=1&s=orbit-sphere&cw=terminal&lv=8) starts with a procedural source and requires no media file.
3. Use the labeled controls to adjust the look, or import a settings link or JSON through Configuration. For user media, choose a supplied file or load a CORS-enabled public address, then wait for the source to render.
4. Use Export PNG, Copy as Text, Make GIF or Make MP4 as available. Wait for export completion and retrieve the resulting download or clipboard content through your browser tools.
5. Return the artwork and, when useful, its settings link. Explain that the link preserves the look but does not include local source media.
A text-only agent can prepare a settings link for the user to open. Rendering and export require a browser with canvas and the relevant media capabilities. The engine API documented at /devs is a browser JavaScript API, not a hosted rendering endpoint. There is no documented public rendering REST API or MCP service.
Camera and screen capture still require browser permission and a user action. Purchases, license activation and optional feature submissions follow the user's authorization; a request to create or export artwork does not itself request publication.
### Sources and workspace
- Open or drag in an image or video, paste from the clipboard, or load a public media address. Remote media must allow browser access through CORS.
- Preview a webcam or screen share after a user action and browser permission. Screen share requires a supported desktop browser; images, clips and camera work on supported mobile browsers.
- Examples offer photo recipes, video clips and moving fields across all seven mark styles, with a suggested adjustment, Next Example and Reset Example. Loading one keeps your canvas size and replaces the look and animation.
- Start without a file using built-in examples or procedural fields: Sphere, Donut, Jellyfish, Galaxy, Contour terrain, Bloom, Vortex, Drape, Weather, Merge, Converge, Dispatch and Sweep. A thought phrase seeds procedural imagery; this is not an AI image-generation service.
- Images accept up to 32 MB and are scaled to a 2048-pixel long edge for rendering. Clips accept up to 512 MB. Playback performance depends on the device and source.
- The mobile workspace places the preview above scrolling controls, with Expand Preview, Show Controls and Export shortcuts. The shared stage stays mounted across workspace layout changes so active media can continue.
### Editing controls
The panel order is Configuration, Source, Examples, Algorithm, Colors, Knobs, Motion, Remove Colors, Layout, Developer, Animation and Export. Source-specific groups appear when applicable.
- Algorithm: Characters, Halftone, Dither or Lines. Characters offers Alphabet and Text Portrait; Text Portrait repeats up to 96 characters with size and weight shaped by source tone. Alphabet uses presets or a custom ramp of up to 16 characters, ordered darkest to brightest. Leading spaces matter. Lines offers Engraving, Flow and Contour, with vertical or horizontal strokes without rotating the source. Halftone can vary disc brightness as well as size.
- Colors: built-in colorways, custom ink, ink opacity, multitone palettes, foreground gradients, solid or gradient backgrounds, and Show Original Background with opacity.
- Knobs: cell density and aspect, levels, contrast, brightness, dither and inversion.
- Motion: source-dependent speed, pulse and redraw cadence. Clips also have playback controls.
- Remove Colors: remove colors from the effect, original background, or both, with independent effect and background color lists, per-color tolerance controls and a removal preview.
- Layout: Fit, Canvas Size, then Mat Inset. Canvas Size can follow the workspace (Auto) or use custom width and height in even pixels from 64 to 3840, with an area limit of 3840 x 2160. The preview scales to fit. Stage export uses the measured canvas pixels; export plan limits still apply. Settings links use cs=WIDTHxHEIGHT or cs=auto.
- Developer: freely preview cursor halo and click ripples, including halo radius and ripple color. These are interactive page effects; PNG, GIF and MP4 exports do not carry them.
- Animation: choose one motion at a time, adjust intensity and speed, and replay one-shot reveals. Groups are Motion, Color, Texture and Reveal. Options include Breathe, Jelly, Heartbeat, Shake, Wander, Color Cycle, Color Shimmer, Aurora, RGB Split, Shimmer, Flicker, Glow, Scanlines, Glitch, Code Glitch, Rain, Wave, Contour Wave Motion, Wavy Lines, Spotlight, Reveal, Focus, Typewriter and Wipe.
Supported animations carry into rendered exports. Wander is a stage-only simulated pointer. Reduced-motion preferences disable the workspace animations and omit them from exports.
### Settings and saved looks
Copy a settings link, import a link or query string, import/export settings as JSON, save one configuration on the current device, or reset the workspace. Pro adds multiple named Saved Looks.
Settings links reproduce a look, not the visitor's local image or video. A public media URL can be included with the u key. Links use v=1 and URL-encoded values; default settings are omitted. Settings files include defaults. Unknown keys are ignored and numeric values are clamped. The developer reference documents the supported keys and values.
### Exports and plans
- Forever Free ($0): all sources, built-in presets and alphabets; clean PNG up to 1080p; copy a frame as real text; GIF up to 1080p, six seconds and 30 fps with a small ascii.cafe stamp. Webcam and screen-share preview and stills are free; recording live sources requires Pro.
- Monthly Pro ($8 per month): clean MP4 up to two minutes and clean GIF up to 30 seconds, PNG and motion export up to 4K, up to 60 fps with 4K capped at 30 fps, webcam/screen recording, and Saved Looks. Cancel any time.
- Lifetime Pro (V1): $49 early bird, with an advertised $69 launch price. One payment for V1 Pro features and V1 updates, excluding major version upgrades.
- Day Pass ($4): 24 hours of Pro on one device. Offered at the export upgrade step rather than on the main pricing board.
Copy Image also places a PNG on the clipboard where the browser supports it. PNG and copied text never carry a watermark. Pro motion exports are clean. Exported artwork can be used commercially on every plan without attribution.
Export sizes are Stage, 720p, 1080p and 4K, subject to plan limits. Dimensions preserve the artwork's aspect ratio. Live recordings use the stage size. Live stills can downsample to 1080p to meet free export limits. Motion length is a frame budget rather than a flat number: one run may ask for at most 7200 frames, so a higher frame rate buys fewer seconds, and 4K is capped at 30 fps because two minutes of 4K at 60 fps does not encode reliably in a browser tab. A long export keeps running while its tab is in the background; closing the tab stops it. MP4 availability depends on browser encoder support; memory and device performance can lower practical export limits. PNG supports a transparent background; MP4 uses an opaque background. See the developer reference for exact export behavior.
Paid plans use hosted checkout and a license key pasted into the workspace. Checkout opens separately so an active camera or screen share can continue. Developer licenses and Pro export access are separate entitlements.
### Developer reference and availability
The /devs reference covers settings links, integration patterns, source handling, interaction and motion, the engine API and lifecycle, ASCII captures, export limits and troubleshooting. The rendering engine uses Canvas 2D and is a single JavaScript file with no runtime dependencies.
The documented Developer License is $39 once per website or project, for commercial embedding without required attribution. With an active validated Developer key, Developer > Download ZIP supplies Artwork.jsx, standalone index.html, the player modules, artwork.json, and Setup.pdf. Bake Frames captures 1 to 30 seconds at 32 fps. Include Original Asset bundles the full image or video and renders it live; generated fields and live feeds use baked frames. Keep all ZIP files together for React or module integration. The standalone HTML embeds its dependencies and artwork for offline playback. Halo and ripples stay interactive. Live baking requires a visible tab. Checkout availability depends on the selected catalogue. Example engine filenames in the reference are local package filenames, not public CDN URLs. Pro exports do not grant a license to embed the engine.
The setup guide documents the 128 MB original-asset limit, the 32-million-cell bake limit, transparent baked backgrounds, layout preservation and troubleshooting. Read [Setup.pdf](https://ascii.cafe/developer/Setup.pdf) before integrating. Include Original Asset places the original media in your exported package; only distribute media you are authorized to share.
### Privacy and measurement
Optional Google Analytics and performance measurement require consent. Developer ZIP attempts, successes, failures and cancellations are instrumented, along with reference copy outcomes and document-link clicks. Measurement distinguishes homepage and workspace activity, coarse device plan, preview visibility/selection/interaction, source attempts, export destinations, tool choices, help opens and observed route or visibility checkpoints. These signals do not prove confusion, abandonment or a new purchase. A document click is navigation intent, not confirmed download completion. Embedded developer players do not install the website analytics tag.
### Optional feature submissions
When submissions are enabled, Request to feature lets visitors submit an interactive creation from their current canvas. It includes a six-second loop of ASCII text grids, playback settings, a cover preview, chosen public name, optional website or social link, and explicit permission. Original files are not uploaded, but Show Original Background includes rendered source pixels as bounded JPEG frames. Review the preview before consenting. Static PNG submissions and arbitrary file uploads are not offered.
The captured grid retains its density in preview and pointer effects remain interactive. Submissions stay private until an administrator approves and publishes them. Declining a submission does not affect exports. Local export and optional publication are separate actions.
### Homepage and editorial content
The homepage combines a live art playground, a preset menu, feature demonstrations, plan comparisons, a developer section, FAQs and a curated showcase. House artwork and selected submissions can open in the workspace. Selected X and Pinterest posts are editorial choices, not an automatic social feed. An authenticated content studio manages the menu and showcased content.
The visual identity uses a lowercase monospace ascii.cafe wordmark, a contrasting pink dot, midnight and paper surfaces, and a capture-frame favicon. The homepage uses a playful cafe voice; the workspace uses plain tool labels and statuses. Reduced motion is respected.
### Links
- [Full agent and developer reference](https://ascii.cafe/llms-full.txt): settings keys, engine options and methods, workflows, and export limits.
- [Homepage](https://ascii.cafe/): live playground, preset menu, plans, FAQ and curated artwork.
- [Workspace](https://ascii.cafe/app): create, edit, save settings and export artwork.
- [Developer reference](https://ascii.cafe/devs): integration guides, settings keys, engine API, captures and export limits.
- [Developer setup PDF](https://ascii.cafe/developer/Setup.pdf): React, HTML, playback modes, backgrounds, limits and troubleshooting.
Mark motion: Shimmer, Spotlight, Code Glitch, Flicker, Scanlines, Breathe, Heartbeat, Focus and Wipe affect Characters with Alphabet style. Wave and Jelly bend Characters with Alphabet style and connected Lines, including Contour in either direction. Examples and Animation menus preview a candidate independently before selection. Plain text exports retain the base character grid; position changes and glow require a pixel or developer export.
Animation compatibility: unavailable choices stay visible but cannot be selected. Switching algorithm or alphabet clears an incompatible active animation. Glow works across all algorithms, lighting pockets of the existing marks. Flicker changes small glyph clusters; Scanlines sweeps through glyph rows without painting over the background.
Animation menu previews render the current artwork in a separate local renderer. Images and live media use current source frames; procedural sources retain their field and phase. Previewing never changes the stage or requests camera or screen permission.
Breathe changes individual character weight and size on a fixed grid. Jelly sends a spring motion through marks and connected lines. Heartbeat sends two outward pulses through glyph strokes. Wander uses local non-bubbling pointer events, so its simulated clicks do not dismiss menus or count as user input.
Contour Wave Motion sends one broad crest through existing contour strokes, left to right for vertical lines and bottom to top for horizontal lines. Wavy Lines sends rolling bends along those strokes. Contour Wave Motion requires Lines with Contour style; Wavy Lines also supports Characters with Alphabet style and other Lines. Focus settles displaced characters into the source picture; Wipe builds characters in staggered columns. Both are one-shot effects on Characters with Alphabet style.
## Workspace settings reference
Use https://ascii.cafe/app as the base. Build queries with URLSearchParams, including v=1 whenever settings are supplied. Spaces and literal plus signs in ramps must be encoded. Links omit defaults; JSON settings exports include them. Settings JSON uses these URL keys and string values, not engine option names. Local files and permission grants are never embedded in settings.
| Key | Purpose | Values | Default |
| --- | --- | --- | --- |
| v | The link's schema version. Present whenever any other key is. A link omits every key at its default; a settings file and the save on this device write every key that applies, defaults included, and the same reader takes both. | 1 | absent on a bare link |
| s | The moving field on the stage. | cafe-cup, orbit-sphere, cafe-donut, cafe-jellyfish, cafe-galaxy, cafe-terrain, cafe-bloom, cafe-vortex, drape, plasma, merge, converge, dispatch, sweep | none (the empty stage) |
| t | The seed phrase a field is drawn from. The same phrase always draws the same motion. | 1 to 80 characters | a slow tide |
| ex | A ready-made example: its source and its whole look. Any other key in the link lands on top of that look. A field example also writes s and t; a picture or video example is named by this key alone. | type-portrait, camera, paper-etching, prism-flow, coast-lines, photo-overlay, vinyl, moving-dots, terminal-donut, weather, jelly-glow, sweep, dispatch | none |
| u | A public address the picture or video is fetched from, by the visitor's browser. | an http or https address, URL-encoded | none |
| mk | The algorithm and line or text style. | g (Characters), d (Halftone), x (Dither), l (Engraving), f (Flow), t (Contour), w (Text Portrait) | g |
| r | The alphabet, darkest character first. One character fills every cell and the colors carry the picture; a leading space leaves the darkest cells empty. | 1 to 16 characters, URL-encoded | ·K■| |
| ld | Line direction | v (Vertical), h (Horizontal) | v |
| txt | Repeating portrait text | 1 to 96 characters | stay curious keep looking |
| lv | How many brightness levels the picture is cut into. | 2 to 16 | 5 |
| cw | A ready-made colorway for the marks and the background. | mocha, pink, matcha, blue, white, snow, paper, ocean, latte, amber, terminal, rose, violet, mint, slate, lava, arcade, solar, voltage, signal, cobalt, citrus, sherbet, thermal, prism | white |
| im | Foreground color mapping | t (brightness tones), g (spatial gradient) | t |
| ia | Foreground gradient angle | 0 to 360 degrees; 90 runs left to right | 90 |
| ink | A custom foreground color. Present instead of cw. | six hex digits, no # | the colorway's ink |
| fa | The foreground's opacity, single ink only. | 10 to 100, steps of 5 | 100 |
| bg | A custom background color. | six hex digits, no # | the colorway's ground |
| pal | Tones: one color per brightness level, darkest first. Present instead of cw. | 2 to 16 six-digit hex stops, comma separated, no # | none |
| cell | Density, as a multiplier on the cell size. Higher is finer. | 0.35 to 1.25, two decimals (the slider moves in steps of 0.05) | 0.62 |
| c | Contrast. | 0.6 to 2, steps of 0.05 | 1.15 |
| b | Brightness, applied before the levels are cut. | -0.5 to 0.5, steps of 0.01 | 0 for pictures and streams, -0.15 for fields, -0.12 for the empty stage |
| dt | Dither, an ordered pattern between levels. | 0 to 1, steps of 0.05 | 0 |
| inv | Invert: swap dark and bright. | 1 when on, 0 when off | off |
| sp | Speed of a moving field or a video. | 0.25 to 3, steps of 0.05 | 1 |
| pu | Pulse, a slow brightening and dimming of the whole picture. | 0 to 1, steps of 0.05 | 0 |
| loop | Whether a video loops. | 0 when off, 1 when on | on |
| an | A ready-made animation that runs on the stage and in GIF, MP4 and PNG files. One at a time. | breathe, jelly, beat, shake, wander, cycle, hues, aurora, split, shimmer, flicker, glow, scan, glitch, rain, cascade, contourwave, wave, spot, code, reveal, focus, type, wipe, center | none |
| ai | How far the animation moves from your settings. Only with an. | 0 to 100, steps of 5 | 60 |
| as | How fast the animation runs. Only with an. | 0.25 to 3, steps of 0.05 | 1 |
| key | Source colors to remove from the selected layers (kr). | up to 16 six-digit hex values, comma separated, no # | none |
| bk | Source colors removed from the original background independently of the effect | up to 16 six-digit hex values, comma separated, no # | none |
| kc | Per-color effect tolerance overrides | JSON object mapping six-digit hex colors to values from 0 to 0.6 | none |
| bc | Per-color original-background tolerance overrides | JSON object mapping six-digit hex colors to values from 0 to 0.6 | none |
| bt | Tolerance for colors removed from the original background | 0 to 0.6, steps of 0.005 | 0.18 |
| kt | How close a color has to be to a removed color to count. Only with key. | 0 to 0.6, steps of 0.005 | 0.18 |
| see | See-through background: empty and removed cells are transparent in PNG and GIF files. | 1 when on, 0 when off | off |
| asp | Cell aspect, the width of a cell relative to its height. | 0.5 to 1.6, steps of 0.05 | 1 |
| cs | Canvas size in pixels. Auto follows the workspace; custom dimensions scale to fit the preview. Stage export uses the canvas size. | auto or WIDTHxHEIGHT, even integers from 64 to 3840, at most 8294400 pixels | auto |
| mat | Mat inset, an empty margin around the picture in percent of the stage. | 0 to 14 | 0 |
| fit | How a picture fills the stage: fill it, or match its width or its height. | c (Fill), w (Width), h (Height) | fill |
| kr | Remove matching source colors from the effect, original background, or both | effect, background, both | effect |
| ob | Show the original image or video behind the marks, using the same crop and fit | 0 or 1 | 0 |
| bo | Opacity of the background color or gradient, independent of the marks | 0 to 1, steps of 0.01 | 1 |
| oa | Original background opacity over the solid or gradient background | 0 to 1, steps of 0.01 | 1 |
| bm | Background mode | solid, linear, radial | solid |
| bp | Background gradient stops, evenly spaced | 2 to 5 comma-separated six-digit hex colors | 101828,312e81 |
| ba | Linear background angle, clockwise from up | 0 to 360 degrees | 90 |
| fps | Cadence: how many times a second the stage redraws. | 4 to 60 | 16 |
| dv | Halftone only: brighter cells draw a brighter disc as well as a bigger one. | 1 when on, 0 when off | off |
| halo | Cursor halo, the brightening under the pointer. | 0 when off, 1 when on | on |
| hr | How far the halo reaches from the pointer. | 0.05 to 0.8, steps of 0.01 | 0.05 |
| rip | Click ripples. | 0 when off, 1 when on | on |
| rc | The ripple's own color instead of the colorway's stops. | six hex digits, no # | the colorway's ripple stops |
| rs | Click ripple size, relative to the base ring. | 0.05 to 4, steps of 0.05 | 1.5 |
| rp | Custom ripple colors, weak to strong. | 2 to 5 six-digit hex stops, comma separated, no # | the colorway ripple stops |
### Working settings examples
```javascript
const query = new URLSearchParams({
v: "1", s: "orbit-sphere", cw: "terminal", lv: "8",
});
const workspaceUrl = `https://ascii.cafe/app?${query}`;
```
[Open the sphere example](https://ascii.cafe/app?v=1&s=orbit-sphere&cw=terminal&lv=8). To prepare halftone for a user's own image, use [this look](https://ascii.cafe/app?v=1&mk=d&lv=8&cw=amber), then choose the image through Source.
## Engine integration
The documented constructor is GlyphRaster, with the local package filename glyph-raster.js. The Developer ZIP supplies this ES module and a captured-artwork player. These are local package paths, not a public CDN. Give the container a nonzero size and construct the engine only in a browser after mount.
### ANY PAGE
With a supplied licensed engine file, mount it in a sized element.
```html
```
### REACT COMPONENT
Download the Developer ZIP and import Artwork.jsx into a client component. Keep the complete folder together.
```jsx
// supplied licensed component
import Pour from "./Artwork.jsx";
export function Hero() {
return ;
}
```
### STANDALONE HTML
Open the exported index.html offline or host it alongside your site and give its iframe a descriptive title.
```html
```
### Developer download setup
#### Choose a download mode
Bake Frames samples 1 to 30 seconds at 32 fps. Files and generated fields are sampled offscreen at exact times; camera and screen feeds record in real time with the tab visible. Include Original Asset bundles an image or video up to 128 MB and renders the full media live. Generated fields and live feeds use Bake Frames.
#### Layout, backgrounds and motion
The player preserves the captured aspect ratio and scales to its container. Solid, linear and radial backgrounds retain their settings. Show Original Background includes rendered source pixels: baked backgrounds use JPEG or transparent PNG frames up to 960 pixels; original-asset mode retains source resolution. Halo and ripples remain interactive when enabled. Reduced motion holds the first frame and disables motion effects. Shimmer, Spotlight, Code Glitch, Flicker, Scanlines, Breathe, Heartbeat, Focus and Wipe operate on Characters with Alphabet style. Wave and Jelly bend Characters with Alphabet style and connected Lines. Contour Wave Motion sends one broad crest through whole contour strokes; Wavy Lines bends them with a rolling wave. Contour Wave Motion requires Contour Lines; Wavy Lines also supports Characters with Alphabet style and other Lines. Glow works across all algorithms. Baked frames retain their motion parameters; plain text has no position or glow channel.
#### Limits and troubleshooting
Baked captures are limited to 32 million grid cells across all frames and 128 MB of artwork JSON. Lower density or duration if a bake is too large. A repeating baked segment can have a visible seam. Speed 0 holds the source. To change a baked look, export again. Keep all ZIP files together for React or module integration; the standalone index.html embeds its dependencies and artwork for offline playback.
Download the setup PDF at https://ascii.cafe/developer/Setup.pdf. The PDF ships in every Developer ZIP. Public documentation does not grant an engine license.
### Source handling and lifecycle
Keep one instance and call update(options) when the look changes. For React, construct after mount in a client component and destroy from effect cleanup. Await setImage or setVideo and check success, then wait for onFrame to confirm a rendered frame before capturing. Loading success alone does not mean the canvas has redrawn. Remote media needs CORS access. For a host-owned video element, decode a frame before capture. Camera and screen capture require HTTPS or localhost and a direct user action; links cannot restore permission or a live session.
```javascript
import GlyphRaster from "./glyph-raster.js";
const stage = document.querySelector("#stage");
const art = new GlyphRaster(stage, { density: 90, sourceFit: "width" });
// file is a File supplied by the user.
const loaded = await art.setImage(file);
if (loaded) {
// Wait for a subsequent onFrame callback before calling snapshot() or toText().
}
// When this host is removed:
art.destroy();
```
### Engine options
Workspace query keys and engine options are different interfaces. For example, cell is a workspace density multiplier, while density is the engine's column count. The workspace accepts a one-character alphabet and expands it for the engine. The table lists documented engine defaults, with workspace differences noted.
| Group | Option | Purpose | Values | Default |
| --- | --- | --- | --- | --- |
| MARKS AND ALPHABET | markMotion | Mark-level animation. Wave and Jelly bend glyphs and connected lines; Shimmer, Spotlight, Code Glitch, Flicker, Scanlines, Breathe, Heartbeat, Focus and Wipe affect glyphs. Contour Wave Motion sends one broad crest through contour strokes; Wavy Lines bends glyphs and connected lines. The host supplies the phase. | none, wave, shimmer, spot, code, flicker, scan, breathe, jelly, beat, cascade, contourwave, focus, wipe | none |
| MARKS AND ALPHABET | markPhase | Position in one repeating motion cycle, recorded in frame appearance for replay. | 0 to 1 | 0 |
| MARKS AND ALPHABET | markAmount | Strength of mark motion; zero draws the unanimated marks. | 0 to 1 | 0 |
| SOURCE AND FIT | source | What is drawn: a built-in moving field by id, or image, video, webcam or screen once one is attached. | orbit-sphere, gallop, drape, plasma, merge, converge, dispatch, sweep, image, video, webcam, screen | orbit-sphere |
| SOURCE AND FIT | thought | The seed phrase the fields are drawn from. The same phrase always draws the same motion. | any short string | a slow tide |
| SOURCE AND FIT | sourceFit | How a picture with its own aspect fills the lattice: cover it, or match its width or its height and band the rest. | cover, width, height | cover |
| SOURCE AND FIT | matInset | An empty margin around the picture, in percent of the box. | 0 to 40 (workspace: 0 to 14) | 0 |
| MARKS AND ALPHABET | lineDirection | Direction of line strokes without rotating the source. | vertical, horizontal | vertical |
| MARKS AND ALPHABET | portraitText | Repeating text for typography; size and weight follow tone. | 1 to 96 characters | stay curious keep looking |
| MARKS AND ALPHABET | markType | How the image is drawn: characters, dots, lines, or repeating text. | glyph, dotRadius, ditherDot, engraving, flow, contour, typography | glyph |
| MARKS AND ALPHABET | ramp | The alphabet, darkest first. A literal string; a leading space leaves the darkest cells empty. | 2 to 16 characters | ·K■| |
| MARKS AND ALPHABET | levels | How many brightness levels the picture is cut into. Raised to the alphabet's length when it is longer. | 2 to 16 | 5 |
| MARKS AND ALPHABET | dotValue | Halftone only: the disc's alpha follows its level as well as its size. | true, false | false |
| MARKS AND ALPHABET | density | Cells across the box. The cell size follows from the box's width. | a positive integer (the workspace pins the cell size and derives this) | 90 |
| MARKS AND ALPHABET | cellAspect | The width of a cell relative to its height. | 0.2 to 4 (workspace: 0.5 to 1.6) | 1 |
| TONE | contrast | Stretches or flattens the difference between dark and bright. | 0.05 to 8 (the workspace uses 0.6 to 2) | 1 |
| TONE | brightness | Lifts or lowers the whole picture before it is cut into levels. | -1 to 1 (the workspace uses -0.5 to 0.5) | 0 |
| TONE | dither | An ordered pattern that breaks up flat bands between levels. | 0 to 1 | 0 |
| TONE | invert | Swaps dark and bright. | true, false | false |
| COLOR | ink | The color the marks are drawn in. An eight-digit value carries an alpha. | a CSS hex color | #ffffff |
| COLOR | ground | The color behind the marks. | a CSS hex color | #000000 |
| COLOR | groundFill | Paint the ground every frame, or clear to real alpha so exports carry transparency. | opaque, transparent | opaque |
| COLOR | inkMode | Map foreground colors by brightness or across the canvas. | tone, gradient | tone |
| COLOR | inkAngle | Foreground gradient angle. 90 runs left to right. | 0 to 360 | 90 |
| COLOR | inkPalette | One ink or custom palette stops; inkMode chooses brightness mapping or a spatial gradient. | single, custom | single |
| COLOR | palette | Custom colors: darkest first in tone mode, spatial stop order in gradient mode. | 2 to 16 hex stops, comma separated | #aa30be, #c742dd, #f3aeff, #ffffff |
| COLOR | keyColors | Removed colors: a cell whose source color matches one draws nothing. | up to 16 hex colors, comma separated; empty is off | empty |
| COLOR | keyTolerance | How close a source color has to be to a removed color to count. | 0 to 1 | 0.18 |
| COLOR | groundSource | Show the original source behind the marks. | true, false | false |
| COLOR | groundOpacity | Opacity of solid or gradient background paint, independent of marks. | 0 to 1 | 1 |
| COLOR | groundSourceOpacity | Original source opacity over the background. | 0 to 1 | 1 |
| COLOR | groundMode | Background fill shape. | solid, linear, radial | solid |
| COLOR | groundPalette | Background gradient stops. | 2 to 5 six-digit hex colors, comma separated | #101828, #312e81 |
| COLOR | groundAngle | Linear gradient angle in degrees. | 0 to 360 | 90 |
| COLOR | keyTarget | Layer affected by removed colors. | effect, background, both | effect |
| COLOR | keyTolerances | Per-color effect tolerance overrides. | JSON object mapping six-digit hex colors to 0 to 1 tolerances | empty |
| COLOR | backgroundKeyColors | Colors removed from the original background. | up to 16 hex colors, comma separated | empty |
| COLOR | backgroundKeyTolerance | Default background color-removal tolerance. | 0 to 1 | 0.18 |
| COLOR | backgroundKeyTolerances | Per-color background tolerance overrides. | JSON object mapping six-digit hex colors to 0 to 1 tolerances | empty |
| MOTION | speed | How fast a field or a clip the engine owns plays. | 0 to 8; 0 holds the source | 1 |
| MOTION | pulse | A slow, even brightening and dimming of the whole picture. | 0 to 1 | 0 |
| MOTION | holdFps | How many times a second the box redraws. | 1 to 240 (workspace default: 16) | 60 |
| INTERACTION | pointerAmount | How much the cells under the pointer brighten. | 0 to 1 | 0 |
| INTERACTION | pointerRadius | How far the halo reaches from the pointer, as a share of the box. | 0.02 to 2 (workspace: 0.05 to 0.8) | 0.25 |
| INTERACTION | pointerMask | Whether the halo lights empty cells too, or only cells that already carry a mark. | everywhere, foreground | everywhere |
| INTERACTION | rippleAmount | How strongly a click or a pointer trail sends a ripple. | 0 to 1 | 0 |
| INTERACTION | rippleSpeed | How fast a ripple travels. | 0.3 to 3 | 1 |
| INTERACTION | rippleMask | Whether a ripple crosses empty cells, or only cells that already carry a mark. | everywhere, foreground | foreground |
| INTERACTION | rippleInk | Whether a rippled cell keeps its own ink, takes one color, or takes a color from ripplePalette by strength. | inherit, single, palette | inherit |
| INTERACTION | rippleColor | The ripple's color when rippleInk is single. | a CSS hex color | #ff6fd8 |
| INTERACTION | ripplePalette | The ripple's colors, weak to strong, when rippleInk is palette. | 2 to 16 hex stops, comma separated | #c742dd, #ff6fd8, #ffd6f2, #ffffff |
| INTERACTION | rippleMoveScale | The size of a ripple sent by a moving pointer, relative to the base ring. | 0.05 to 4 | 1 |
| INTERACTION | ripplePressScale | The size of a ripple sent by a press, relative to the base ring. | 0.05 to 4 | 1 |
| ACCESSIBILITY AND CALLBACKS | description | The text alternative written onto the canvas for screen readers. | a sentence | a description of the turning form |
| ACCESSIBILITY AND CALLBACKS | onFrame | Called after every drawn frame with the time in milliseconds and the playback position in seconds. Constructor only. | a function (nowMs, seconds) | none |
| ACCESSIBILITY AND CALLBACKS | onStatus | The engine's one outbound channel: a line of text whenever something a host should know happens. Constructor only. | a function (message) | none |
### Engine methods
| Method | Signature | Behavior |
| --- | --- | --- |
| getSourceFrame | getSourceFrame(maxSide = 640) | Copies the current unprocessed image or media frame into a reused local canvas, capped at 1920 pixels. Returns null for procedural or unavailable sources. Does not acquire or control streams. |
| update | update(options) | Applies rendering settings in place. Set onFrame and onStatus callbacks in the constructor. |
| setSource | setSource(fieldIdOrFunctionOrElement) | A core built-in field id, custom luminance function, or image, video or canvas element you own. Workspace cafe-* field ids require the site's field functions; they are not core string ids. |
| setImage | setImage(fileOrAddress) | A File, a Blob or an address. Resolves true when it took and false with a status when not. Pictures up to 32 MB, scaled to 2048 px on the long edge. |
| setVideo | setVideo(fileOrAddress) | The same for a clip the engine then owns, up to 512 MB. |
| enableWebcam | enableWebcam() | Call it inside a click. Resolves true when the camera is live. |
| enableScreenShare | enableScreenShare() | The same for a window, a tab or a screen. screenShareSupport() says whether the browser can. |
| setPlaying | setPlaying(on) | Pauses or resumes playback. |
| seek | seek(seconds) | Renders the frame at that time without changing the play state. |
| snapshot | snapshot(type?) | The current frame as a data URL, PNG by default. |
| toText | toText() | The frame as real characters, one line per row. |
| destroy | destroy() | Stops everything, releases the camera and the clip, removes what it added. |
Additional readback/lifecycle method names: getParams, getGrid, getSourceState, getSourceFit, mediaRate, restart, screenShareSupport. Color-key method names: eyedropperSupport, armEyedropper, disarmEyedropper, addKeyColor, getKeyState. Consult the supplied engine declarations for their argument and return types.
### ASCII captures
A settings file describes a look. An ASCII capture contains rendered character-level grids. After onFrame confirms the source has been drawn, the documented frame capture is:
```javascript
const frame = art.captureAscii({ mode: "frame", text: true });
const json = JSON.stringify(frame);
```
Preserve the captured grid dimensions, alphabet, level rows and colors when building a player. Scale the complete canvas rather than reducing its density. A captured loop is not the editable source media. Interactive effects in a capture player may differ from the live source. Feature submission is a separate consent-based publishing workflow, not a generic capture-download endpoint.
## Export limits
| Format or feature | Free | Pro |
| --- | --- | --- |
| PNG | Clean, up to 1080p | Clean, up to 4K |
| Text | Clean | Clean |
| GIF | Up to 6 s at 30 fps, up to 1080p, small stamp | Up to 30 s, 60 fps up to 1080p and 30 fps at 4K, clean |
| MP4 | Unavailable | Up to 120 s, 60 fps up to 1080p and 30 fps at 4K, clean; browser encoder required |
| Webcam and screen | Preview and stills | Preview, stills and recording |
These are plan ceilings, not performance guarantees. Duration is a frame budget rather than a flat number: a run may ask for at most 7200 frames, so a higher frame rate buys fewer seconds, and 4K is capped at 30 fps because two minutes of 4K at 60 fps will not encode reliably in a browser tab. Long exports continue while the tab is in the background; closing the tab stops them. Live captures use the stage size. MP4 requires supported H.264 encoding and has an opaque background. Use GIF if MP4 is unavailable. PNG and GIF can carry transparency. Cursor halo and click ripples belong to interactive playback and are excluded from pixel exports; the phantom-cursor animations Wander and Center Click are stage-only and never reach a file. Reduced motion disables workspace animations in the stage and exports.
## License reference
| Plan | Price | Cadence | Scope |
| --- | --- | --- | --- |
| FOREVER FREE | $0 | forever | The whole counter, for good. No card, no account, no trial that runs out. |
| MONTHLY PRO | $8 | per month, cancel any time | Everything Pro does, for the month you need it. Stop when you are done and keep every file. |
| LIFETIME PRO (V1) | $49 | once, for V1* | Pay once for V1. Every V1 Pro feature, with no renewal to remember. |
| DAY PASS | $4 | for 24 hours | Everything Pro does, until this time tomorrow. One device, one key. |
| DEVELOPER LICENSE | $39 | once, per project | The engine that draws this page, as one file you can ship: no dependencies, no server and no attribution required. One license applied to a single website or project. |
* Excludes major version upgrades
A Developer License covers one website or project embedding the engine; Pro covers workspace export capabilities. Neither entitlement implies the other. Exported artwork is commercially usable on all plans without attribution. Do not remove the free GIF stamp. Use the user's authorization for purchases, keys and publication.
## Troubleshooting
| Symptom | Check |
| --- | --- |
| Empty canvas | Give the container a height, wait for source readiness and inspect getSourceState(). Check remote CORS headers. |
| Camera or screen unavailable | Use a supported browser on HTTPS or localhost and request access from a user action. |
| Image cropped | Choose Width or Height in the workspace; use sourceFit: width or height in the engine. |
| Unexpected alphabet | URL-encode the ramp, preserve leading spaces, and distinguish workspace r from engine ramp. |
| Repeated canvases | Create once after mount, update in place, destroy on unmount. |
| MP4 unavailable or slow export | Check encoder support and device limits; try GIF, lower dimensions, frame rate or duration. |
| Settings link lost the image | Local media is not in the link. Supply the file again or use a CORS-enabled public URL. |