@kingsword/asg

Convert asciicast v3 recordings into sharp, compact animated SVGs from Node.js.

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

Quick start

Run without installing:

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

Or install the asg command globally:

npm install -g @kingsword/asg
asg recording.cast recording.svg --window

The package runs the Rust CLI as a precompiled wasm32-wasip2 component. It does not compile Rust on the user's machine.

Inputs

• local .cast and zstd-compressed .cast.zst files;
• stdin and stdout via -;
• HTTP(S) URLs;
• asciinema.org recording IDs.

ASG intentionally supports asciicast v3 only. Convert older recordings first:

asciinema convert old.cast recording-v3.cast

Common commands

# 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

# Static frame or animated excerpt; times are seconds
asg recording.cast still.svg --at 4.5
asg recording.cast excerpt.svg --from 3 --to 12

# Window decorations, fixed geometry, and faster playback
asg recording.cast demo.svg --window --cols 100 --rows 30 --speed 1.5

Useful options:

--speed <N>                  playback speed multiplier
--fps <N>                    maximum visual frames per second
--idle-time-limit <SECONDS>  cap idle gaps
--cols/--width <N>           pin terminal columns
--rows/--height <N>          pin terminal rows
--font-family <FAMILY>       CSS font stack
--font-size <PX>             output font size
--line-height <N>            line-height multiplier
--padding[-x|-y] <PX>        output padding
--theme <NAME|COLORS>        named or custom 18-color theme
--at/--from/--to <SECONDS>   static frame or animated range
--no-cursor --no-loop --window

Run asg --help for the full interface.

Why SVG?

The output is a single image with no JavaScript player. Pixel-native geometry and SVG paths for terminal graphics stay sharp when scaled, while frame, line, and style reuse keep the animation compact.

Use ASG for v3-to-SVG README demos. For rasterized, font-independent output or v1/v2 input, consider agg. svg-term-cli produces SVG but cannot parse asciicast v3.

Documentation

• English README
• 中文文档
• Architecture and measured trade-offs

License

ASG is Apache-2.0. The demo recording and derived SVG retain the upstream demo asset's GPL-3.0-or-later terms.