Skip to content
kingsword09Public

About

Convert asciicast v3 recordings to compact animated SVG.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

ASG

Convert asciicast v3 recordings into sharp, compact animated SVGs.

CI crates.io npm License

简体中文

Animated terminal SVG generated by ASG

Generated with --window from asciinema/agg's v3 demo recording. Source and attribution.

Why ASG?

  • 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.

Quick start

Run once with npm:

npx --yes @kingsword/asg@latest recording.cast recording.svg --window

Or install either distribution:

# Native Rust binary
cargo install asg --locked

# Node.js / WASI CLI
npm install -g @kingsword/asg

Both install an asg command with the same interface:

asg recording.cast recording.svg --window

Agent Skill

This 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 asg

Use -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.

Which terminal renderer should I use?

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.

Embedding fonts

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.ttf

Family, 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.

Inputs and compatibility

ASG accepts:

  • local .cast and zstd-compressed .cast.zst files;
  • 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

Common workflows

# 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-cursor

Reproduce the README demo:

asg examples/demo.cast examples/demo.svg --window --from 0.1
CLI 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.

Rendering model and size

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.

Development

cargo +nightly x lint
cargo +nightly x test
cargo build -p asg --target wasm32-wasip2 --release

License

ASG 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.

About

Convert asciicast v3 recordings to compact animated SVG.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages