Home / All Skills / Design & Motion / ascii-animation
English (EN)简体中文 (ZH)日本語 (JA)
Design & Motion · iart-ai/web-animation-skills

ascii-animation

This skill should be used when the user asks to "make an ASCII animation", "build a terminal/CLI intro or loader", "convert an image or video to ASCII art", "add an ASCII shader/post-effect to a canvas or Three.js scene", "create retro/hacker text-character motion", or "animate text characters with a brightness ramp". Covers generative ASCII fields, image/video/3D-to-ASCII, and animated character art for both web and terminal.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Author iart-aiGitHub iart-ai/web-animation-skills ↗Stars 28License MIT（仓库根 LICENSE 为 MIT License, Copyright (c) 2026 iart.ai；.claude-plugin/plugin.json 的 license 字段同为 MIT）Commit b6dba3eb75
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The foundation of the entire implementation is the brightness ramp: mapping sRGB perceived luminance (0..1) to character indices matched by ink density.

skills/ascii-animation/SKILL.md
Map luminance (0..1) to a character whose ink density matches. Order characters dark-to-light.
Provides three sets of ramps (10 levels / 16 levels / 70 levels by Paul Bourke) and sRGB weight formulas; whether the ASCII art looks faithful is determined by this step.

Identifies the character cell aspect ratio of ~0.5 as the #1 pitfall: sampled rows must be fewer than columns, or the image will stretch vertically.

skills/ascii-animation/SKILL.md
Correct by sampling **fewer rows than columns**: for a target of `cols` characters wide, use `rows = Math.round(cols * (imgH / imgW) * fontAspect)` where `fontAspect ≈ 0.5`.
Independent of browser or terminal, this is a geometric prerequisite of character grids; SKILL.md, references, and the Node script each provide an identical formula or constant.

Tiered rendering pipelines based on performance cost: <pre>+textContent (simple), canvas fillText (per-character coloring/large grids/60fps), and Three.js AsciiEffect (full-scene ASCII conversion).

skills/ascii-animation/SKILL.md
**Canvas `fillText`**: needed for per-character color, larger grids, or 60fps.
Image reading uses an offscreen canvas (cols×rows) plus getImageData; videos repeat the same process frame by frame.

Terminal-side uses ANSI escape codes for a self-drawn frame loop: hide cursor, home cursor, throttle to 12–24fps, restore upon exit, noting that homing the cursor is cheaper than clearing the screen.

skills/ascii-animation/SKILL.md
Use `ESC + '2J'` to clear the whole screen, `ESC + 'H'` for home (cheaper per frame than clearing).
Browser and terminal delivery paths are handled separately; terminal deliverables are verified via stdout or terminal screenshots, not HTML frozen frames.

Reproducibility: frames are driven by injectable time plus a fixed seed, where ?t=N renders only a single frame, turning screenshots into deterministic verification artifacts.

skills/ascii-animation/SKILL.md
Drive frames from an **injectable time** (not `Date.now()`/`performance.now()` directly) and seed any randomness, so a frame is reproducible.
Accompanied by the requirement to capture screenshots only after monospace fonts are fully loaded (fonts determine cell metrics; failure to load causes FOUC or stretching).

2Core Capabilities

01Generative ASCII fields (sine or noise mapped to ramps, including a complete, runnable plasma frame loop)
02Image and video conversion to ASCII (offscreen canvas with getImageData frame-by-frame sampling)
03Three.js AsciiEffect post-processing (rendering must go through effect.render instead of renderer.render)
04Terminal/CLI animations (ANSI frame loop, cursor hiding/restoring, truecolor coloring)
05Frozen-frame seek harness (?t=N single frame with a fixed seed, signaling readiness via window.__ready)
06Built-in Node CLI: image to ASCII text (--cols / --invert / --ramp)
07Ramp tables and sampling math (10-level / 70-level / 16-level extended, Unicode block characters, empirical cell aspect ratios)
08Zero-build delivery (single HTML with inlined ramps and rAF loop, explicitly avoiding bundlers)

3External Dependencies

KindDependency / Endpoint
packagesharp（自带脚本的依赖：解码 PNG/JPG/WebP 并缩放到字符网格）
packagethree（可选：AsciiEffect 走 three/addons，交付页可从 CDN 取）
api浏览器与终端原语：canvas 2D getImageData、requestAnimationFrame、ANSI 转义序列、process.stdout
clinpx / Playwright（宿主侧截图工具；SKILL.md 在 verify 段示范）
cliscripts/seek-shot.sh + scripts/contact-sheet.sh + ffmpeg（仓库根打包助手，被 SKILL.md 的 Packaged helper 段点名）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
  • scripts/: Execute local script or command: node skills/ascii-animation/scripts/img-to-ascii.mjs <image> [--cols N] [--
  • 网络端点: Declare external network access: The script itself makes zero outbound calls; npm i sharp (fetching from the npm registry during installation) and optional three CDN loading in delivery pages occur at host or artifact runtime and are not factored into the rating.
  • 本地工作目录: File I/O and artifact output: The built-in script writes no files (stdout only).
Audit Notes: Rating is based strictly on the skill's own directory: skills/ascii-animation/ contains SKILL.md, a 0-byte README.md, references/rendering.md, and scripts/img-to-ascii.mjs—one of only two skills across the repository's 9 skills with an executable entry point (includes shebang, usage, and is explicitly referenced for execution in SKILL.md's Reference files section). Basis for Blue tier (local script/CLI and local I/O only): The script is a purely local, read-only utility (sharp decoding → pixel-to-character mapping → stdout) with zero fetch/http/child_process/eval across the codebase, reads no environment variables or credentials, performs no disk writes, and executes no upstream input; its only third-party dependency is npm's sharp (retrieved during install). Optional three CDN references in delivery pages belong to artifact runtime and are excluded from rating.

5Second-Pass Verification

  • [ok] 自带脚本是否真的没有网络、凭证与写盘面 — img-to-ascii.mjs 全文 64 行逐行读过：import 只有 sharp；用 process.argv 解析参数；sharp(file).metadata() 与 .resize().removeAlpha().raw().toBuffer() 读像素；结果只经 process.stdout.write 输出。无 fetch、无 http 模块、无 fs 写、无 process.env，也无 shell 调用。
  • [discrepancy] 坡道「16 级中等坡道被截断」的指引是否自洽 — SKILL.md 的 Common ramps 段在 Medium (16) 之后写 truncated — see table below，但该段下方最近的表是 Quick reference（无坡道表）；完整 16 级坡道实际在 references/rendering.md 的 ### 16-level extended (balance)。指向错位，照抄 SKILL.md 拿不到完整坡道。
  • [discrepancy] Packaged helper 的路径基准与适用性 — SKILL.md 写 scripts/seek-shot.sh anim.html 0 1.5 3，scripts/ 实际在仓库根；且本 skill 的终端形态本就不适用 ?t=N 冻结（SKILL.md 自己注明终端件需另法验收），该 helper 只覆盖浏览器形态。
  • [ok] willReadFrequently 与 AsciiEffect 的取舍是否与参考文件一致 — SKILL.md 的 <pre> 与 canvas 取舍、willReadFrequently 用法、AsciiEffect 必须 effect.render 的注意事项，在 references/rendering.md 的 #### <pre> vs canvas 与 Three.js AsciiEffect 两节均可定位，前后无矛盾。

6Verdict & Scenarios

  • The only skill with a runnable CLI; converts images to ASCII offline in one go without browser dependencies
  • Encodes the most error-prone geometric constraint (character cell aspect ratio) into hardcoded formulas in three places
  • Offers three sets of ramps paired with sRGB perceptual weights, supporting both photo-realistic fidelity and compact generative approaches
  • Provides distinct freeze and verification mechanisms tailored separately for browser and terminal delivery paths
    • Best for: Best suited for: (1) Terminal or CLI intros, loaders, banners, and retro hacker-style interfaces; (2) Converting images, video frames, or 3D scenes into ASCII post-effects (canvas or Three.js AsciiEffect); (3) Generative character motion graphics that require an ultra-lightweight footprint without graphics library dependencies; (4) Command-line image-to-ASCII conversion tools that need to run completely offline.
    Not for: Not suited for: (1) Image representations requiring photo-realistic detail (character grids have inherently low resolution); (2) Formal interfaces requiring precise typography and high text readability (ASCII is a stylization choice); (3) Purely offline environments lacking Node, unable to install sharp, and unwilling to use a browser (the bundled script cannot run).
    Install Agent-Ready
    ① Verified Mirror 2026-09-28
    Option A · Direct DownloadDownload ascii-animation.tar.gz
    sha256: b1d5e8b21e57db26…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit b6dba3eb75.