ASCII Video Workshop Guide
Workshop & Embed Player

What Is the ASCII Video Workshop?

The ASCII Video Workshop is a set of pure front-end, single-file ASCII art tools with two versions: the full version (ASCIIplayer.html, for "production") and the Embed version (ASCIIplayer-embed.html, for "consumption"). Video / image / camera frames are converted into ASCII art frame sequences in real time and saved as a custom .ascii-video file; the Embed version reads that file and plays it in any web page.

This guide briefly covers using the full version first, then focuses on the Embed version's three external control methods: URL parameters (take effect on load), postMessage (real-time tuning inside an iframe embed), and a global API (direct calls from same-page scripts).

Features

Full Version (ASCIIplayer.html)

• Multiple input sources: upload video / image / GIF, or record live from the camera
• Real-time ASCII rendering: the WebGPU shader recomputes characters in real time based on the current parameters, so adjustments take effect instantly
• Timeline editing: split / reorder / delete / merge clips, drag an edge to change speed (0.1×–10×), double-click to split
• Per-clip picture settings: each clip can individually override display mode, glyph size, gamma, flip, and other parameters
• Multi-format export: .ascii-video (v6/v7 with audio), GIF, regular video (MP4/WebM), images
• Picture-in-picture: the original video is shown in a corner for easy comparison

Embed Version (ASCIIplayer-embed.html)

• Single file, zero build: about 67 KB, no parameter panel at all, ideal for embedding into third-party pages via iframe
• Multiple loading methods: local drag & drop / "Open File" button / ?src= remote URL
• 16+ URL parameters: mode, glyph, gamma, brightness, contrast, invert, flip, colors, aspect ratio, audio, UI level, and more
• External real-time control: postMessage messages and the window.AsciiEmbed global API
• GPU/CPU dual backends: WebGPU offscreen acceleration by default, automatically switching to CPU computation on failure (without interrupting the picture)
• v6/v7 playback: supports embedded audio tracks (Opus/WebM), strictly aligned to the source video's duration by frame timestamps

Full Version Quick Start

1. Generate an ASCII Art Video

Open the ASCII Video Workshop (ASCIIplayer.html):

• Click "Upload Video or Image", or drag a file straight into the preview area; you can also click "Record" to capture live from the camera.
• In the "Picture" panel on the right, adjust display mode, glyph size, gamma, invert, flip, aspect ratio, and other parameters — the preview updates instantly.
• Click "Save" to export a .ascii-video file (v6 without audio by default; once "Embed Audio" is enabled under "Processing & Export → Audio", saving produces v7 with sound).

2. Timeline Editing (Optional)

After selecting a loaded entry, click "Edit" to enter edit mode: double-click a clip to split it, drag to reorder and trim, drag an edge to change speed, select multiple clips to merge/delete them, and each clip can also have its own picture parameters (marked with an amber dot in the top-right corner). When you're done editing, use the export button on the timeline toolbar to output a .ascii-video or a regular video.

Tip: The Embed version only supports the v6 / v7 formats. Re-export older files (v1–v5) from the workshop.

Embed Version Tutorial

1. Quick Start

Open the Embed player (ASCIIplayer-embed.html) directly and it shows the drag-and-drop hint:

/ToolBase/ASCII/ASCIIplayer-embed.html

Specify a remote .ascii-video file via ?src= and it loads and plays automatically on open:

/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video

You can also drop a .ascii-video file onto the page, or click the "Open File" button to pick a local file.

2. URL Parameters (Effective at Load Time)

Examples:

# Grayscale + large glyphs
/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&mode=grayscale&glyph=24

# White characters + cyan foreground + high contrast
/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&mode=white&fg=%2322d3ee&contrast=1.6

# Canvas-only embed (click the canvas to play/pause, no controls at all)
/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&ui=none

# Uniform fill (scaled-up crop with no blank space, no distortion)
/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&aspect=cover

3. iframe Embedding

The Embed version has no parameter panel; ui=full keeps the playback control bar, while ui=none is a bare canvas (click the canvas to toggle play/pause; the keyboard Space/Esc/arrow keys work too).

<iframe
  src="/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&ui=full"
  width="960" height="540"
  allow="autoplay"
  style="border:0;border-radius:8px"
  title="ASCII Video Player"
></iframe>

Note: To autoplay embedded audio, the iframe must carry allow="autoplay", otherwise the browser may block it.

4. Real-Time Control via postMessage

The parent page controls the player through iframe.contentWindow.postMessage(), no page refresh needed:

const player = document.querySelector('iframe#player');

// Change parameters on the fly: grayscale + glyph 24
player.contentWindow.postMessage({
  type: 'ascii:params',
  params: { mode: 'grayscale', glyph: 24 },
}, '*');

// Transfer a local file (transferable zero-copy)
file.arrayBuffer().then((buf) => {
  player.contentWindow.postMessage(
    { type: 'ascii:loadBuffer', buffer: buf, name: file.name },
    '*', [buf]
  );
});

5. Global API (Same-Page Scripts)

Inside the player's own page (or the devtools console), you can call window.AsciiEmbed directly:

window.AsciiEmbed.setParams({ mode: 'white', invert: true });
window.AsciiEmbed.load('/ToolBase/ASCII/video/demo.ascii-video');
window.AsciiEmbed.loadFile(file);   // File object
window.AsciiEmbed.play();
window.AsciiEmbed.pause();
window.AsciiEmbed.stop();
window.AsciiEmbed.seekTo(0.5);
window.AsciiEmbed.getState();
// → { frames, cols, rows, fps, playIndex, isPlaying, hasAudio, renderMode }

6. Live Demo

Below is a live embed example (player /ToolBase/ASCII/ASCIIplayer-embed.html, sample data /ToolBase/ASCII/video/demo.ascii-video):

Note: The sample .ascii-video file lives at /ToolBase/ASCII/video/demo.ascii-video; you can also swap ?src= for your own file path.

Full Version vs. Embed Version

The .ascii-video File Format

Binary container: a 48-byte header plus a data section. The header contains the magic "ASCI", version number, flags (extended charset / color depth / has audio), column count, row count, fps, and frame count.

• v6: each frame carries a u32 real timestamp (source media time, playback strictly checks it against the source duration) + inter-frame residuals (compared after quantization, minor changes automatically ignored) + whole-file gzip. Playback is timestamp-driven, and the duration always equals the source video's duration.
• v7: v6 plus a trailing audio section (u32 video data length + gzipped video + u32 audio length + Opus/WebM audio); the player syncs the embedded audio automatically (audio=0 turns it off).

In memory, each cell takes 7 bytes (character slot + 8-bit RGB); at render time the GPU shader recomputes characters from the RGB values in real time according to the current parameters — so changing glyph size / gamma / invert and similar parameters after import takes effect in real time.

Browser Requirements

• WebGPU: Chrome 113+ / Edge 113+ (GPU compute rendering); Firefox requires manually enabling dom.webgpu.enabled.
• DecompressionStream('gzip'): Chrome 80+ / Edge 80+ / Safari 16.4+ (required to decompress v6/v7 files).
• Self-healing fallback: GPU computation by default (offscreen rendering → 2D display); when the GPU is unavailable, readback hangs, or the picture stays unchanged across consecutive frames, it automatically switches to CPU computation without interrupting the picture. Any browser can play.
• Diagnostics: render=cpu forces CPU computation; the badge in the top-right corner always shows the current backend; the "Debug" switch in the control bar displays real-time render status; getState() returns renderMode / renderErrorCount / gpuStaticCount to help locate problems.

FAQ

1. How do I generate a .ascii-video file?

Use the full-version ASCII Video Workshop: upload a video/image → adjust the picture parameters → click "Save". v6 is exported by default; once "Embed Audio" is enabled under "Processing & Export → Audio", saving produces v7 with sound.

2. The Embed version plays an old file and says "only v6/v7 supported"?

Compatibility with the v1–v5 legacy formats has been dropped (this keeps the decoding path as short and reliable as possible). Re-import the file with the full version and save it as a new version.

3. Can browsers without WebGPU still play?

Yes. The player automatically switches to CPU computation mode (without interrupting the picture), and the badge in the top-right corner shows CPU; you can also force it with render=cpu or the control-bar button.

4. No sound after embedding into a page?

Check two things: the file must be v7 (with audio); and the iframe needs the allow="autoplay" attribute, otherwise the browser blocks autoplay.

5. How do I control the aspect ratio?

aspect=original keeps the original ratio without distortion (default); aspect=cover scales up uniformly to fill (cropping the overflow, no blank space); aspect=stretch stretches to fill; aspect=custom&aw=…&ah=… is fully custom; fill=1 is equivalent to stretch.

6. Parameters not taking effect?

URL parameters apply at load time, and postMessage can override them at any moment; the two can be mixed, with the later one winning. For extended, if the file's embedded flag is already enabled, that flag is only used when the URL doesn't specify it explicitly. Changing startup-level parameters like ui= / render= requires a page refresh.

🤝 Related Resources

• Full-version workshop: /ToolBase/ASCII/ASCIIplayer.html
• Embed player: /ToolBase/ASCII/ASCIIplayer-embed.html
• Technical documentation: docs/ASCIIplayer-embed-doc.md (in the repository, with full parameter and API details)
• Live demo: ASCII Player Embed Demo (interactive parameter tuning and code generation)

Happy Hacking! 🎉