Convert asciicast v3 recordings into sharp, compact animated SVGs.
Generated with --window from asciinema/agg's v3 demo recording. Source and attribution.
- Native asciicast v3 support. ASG understands v3 headers, relative event timing, resize events, embedded themes, and zstd-compressed recordings.
- README-ready output. The result is one self-contained SVG with no JavaScript, raster frames, or external player.
- Sharp at any scale. Pixel-native geometry, integer baselines, and SVG paths for terminal graphics avoid the blur and seams common in scaled terminal SVGs.
- Run it your way. Use the native Rust binary or the same CLI through the npm/WASI package.
Run once with npm:
npx --yes @kingsword/asg@latest recording.cast recording.svg --windowOr install either distribution:
# Native Rust binary
cargo install asg --locked
# Node.js / WASI CLI
npm install -g @kingsword/asgBoth install an asg command with the same interface:
asg recording.cast recording.svg --windowThis repository includes a portable ASG Agent Skill, built to the Agent Skills specification, for installing the CLI, choosing render options, validating output, and troubleshooting terminal SVGs. Install it with Vercel's Skills CLI:
npx skills add kingsword09/asg --skill asgUse -g -y for a non-interactive global install, then ask your agent to Use $asg to convert this asciicast v3 recording into a README-ready SVG.
| Tool | Output | Asciicast support | Best fit |
|---|---|---|---|
| ASG | Animated SVG | v3 only | Sharp, compact terminal demos in GitHub, npm, and documentation |
| svg-term-cli | Animated SVG | Legacy casts; no v3 parser | Existing pre-v3 svg-term workflows |
| agg | Animated GIF | v1, v2, v3 | Font-independent raster output and broad cast compatibility |
| asciinema player | Interactive HTML/JS | v3 | Playback controls and interactive web pages |
Choose ASG when the source is asciicast v3 and the destination accepts an image but not a JavaScript player. SVG text uses fonts installed on the viewer's system; choose agg when identical rasterized pixels across devices matter more than vector scaling and text sharpness.
By default the SVG only names fonts. Pass --font-file (repeatable) to embed local TrueType or OpenType faces as data-URI @font-face rules. TrueType outlines are subsetted to the codepoints the output actually uses and compressed to WOFF2; CFF/CFF2 fonts are embedded as complete OpenType data with a size warning. This lets SVG-capable browsers use those fonts without a local installation, including when the SVG is displayed as an image in a GitHub README:
asg demo.cast demo.svg \
--font-family "JetBrains Mono,Symbols Nerd Font Mono" \
--font-file JetBrainsMono-Regular.ttf \
--font-file JetBrainsMono-Bold.ttf \
--font-file SymbolsNerdFontMono-Regular.ttfFamily, style, and weight are read from each face's name/OS/2 tables, and the --font-family stack keeps choosing their order (ASG warns when an embedded family is missing from the stack). The renderer disables font-synthesis, so a recording that uses bold or italic needs the matching faces supplied. Bitmap emoji fonts (SBIX/CBDT) are rejected; leave them out to use the viewer's system emoji fallback. Added size depends on glyph coverage and font format; complete CFF fonts can be much larger than TrueType subsets. Confirm that each font's license permits embedding.
The cell width is measured from the first supplied font's advance rather than assumed: any monospace face works, not just 0.6 em ones like JetBrains Mono or Fira Code. When no font file is supplied (or the advance cannot be measured), ASG falls back to the classic 0.6 em cell.
ASG accepts:
- local
.castand zstd-compressed.cast.zstfiles; - stdin via
-; - HTTP(S) URLs;
- asciinema.org recording IDs;
- output paths or stdout via
-.
It implements ANSI/DEC terminal behavior through asciinema's avt virtual terminal, including 16/256/truecolor, text attributes, alternate screen, wide Unicode, cursor visibility, and terminal resize.
Important
ASG intentionally rejects asciicast v1 and v2. Convert old recordings before rendering:
asciinema convert old.cast recording-v3.cast# Local or compressed recording
asg recording.cast recording.svg
asg recording.cast.zst recording.svg
# Stream through stdin/stdout
cat recording.cast | asg - - > recording.svg
# Render directly from a URL
asg https://example.com/recording.cast recording.svg --window
# One static frame, or an animated excerpt (times are seconds)
asg recording.cast still.svg --at 4.5
asg recording.cast excerpt.svg --from 3 --to 12
# Resize, change speed, and hide the cursor
asg recording.cast demo.svg --cols 100 --rows 30 --speed 1.5 --no-cursorReproduce the README demo:
asg examples/demo.cast examples/demo.svg --window --from 0.1CLI options and built-in themes
--speed <N> playback speed multiplier
--fps <N> maximum visual frames per second (default 30)
--idle-time-limit <SECONDS> override the v3 header idle limit
--cols/--width <N> pin terminal columns
--rows/--height <N> pin terminal rows
--font-family <FAMILY> CSS font stack
--font-size <PX> output font size (default 16)
--font-file <PATH> font file to embed as a data-URI
@font-face (repeatable; e.g. regular, bold, and
a Nerd Font fallback)
--line-height <N> line-height multiplier (default 1.4)
--padding[-x|-y] <PX> output padding (default 0)
--theme <NAME|COLORS> named theme or custom 18-color palette
--at/--from/--to <SECONDS> static frame or animated range
--no-cursor --no-loop --window
--no-synthetic-symbols render block and box-drawing characters with
the font instead of crisp SVG paths
Built-in themes: svg-term, atom-one, asciinema, dracula, github-dark, github-light, monokai, solarized-dark, and solarized-light.
Run asg --help for the authoritative interface.
ASG uses a compact horizontal reel instead of duplicating complete screens:
- only visual changes become frames;
- identical states and repeated lines are reused;
- styles are shared through CSS classes;
- one discrete CSS animation moves the reel;
- box-drawing and block glyphs use crisp native SVG paths (opt out with
--no-synthetic-symbols).
The demo above was generated with --window --from 0.1:
| Source | Output | Frames | Duration | Canvas |
|---|---|---|---|---|
| 1,744,897-byte v3 cast | 986,999-byte SVG | 146 | 29.964s | 930×544 |
The SVG is 56.56% of the cast input while remaining vector-based and self-contained. Default terminal geometry uses a 16px font, 10px cells, 22px rows, a 1:1 physical-pixel viewBox, and zero padding.
For parser, timeline, terminal, and renderer design details, see the architecture document. The Rust library entry point is asg::generate.
cargo +nightly x lint
cargo +nightly x test
cargo build -p asg --target wasm32-wasip2 --releaseASG source code is licensed under Apache-2.0. The demo recording and derived SVG retain the upstream demo asset's GPL-3.0-or-later terms; see examples/README.md.