tools-comparison

Purpose

Evaluate terminal recording tools for creating high-quality demos of the lattice CLI tool for website documentation and README files.

Top Tools for Terminal Recording

1. asciinema (Recommended for Web)

Best for: Web players with copy-paste text, lightweight recordings

Key Features

• Records terminal sessions as lightweight JSON (asciicast format)
• Web player embeds in documentation with <script> tags
• Users can pause, copy text from recordings (major advantage over GIF)
• Sharp rendering on all displays
• Active development (updated Nov 2025)

Components

• asciinema (recorder): brew install asciinema
• asciinema-player (web): Embed in HTML with NPM package or standalone JS
• agg (GIF generator): brew install agg - replaces deprecated asciicast2gif

Workflow

# Record
asciinema rec demo.cast

# Generate GIF
agg demo.cast demo.gif

# Or embed web player in HTML
<script src="asciinema-player.min.js"></script>
<asciinema-player src="demo.cast"></asciinema-player>

Pros

• Lightweight (text-based format)
• Selectable text in web player
• High-quality GIF output via agg
• Free hosting at asciinema.org
• Active community (16,383 GitHub stars)

Cons

• Web player requires <script> tags (not compatible with all platforms)
• GIF generation requires separate tool (agg)

2. VHS by Charmbracelet (Recommended for Automation)

Best for: Scripted demos, CI/CD integration, multiple formats

Key Features

• Write terminal GIFs as code (tape files)
• Outputs: GIF, MP4, WebM, PNG frames
• Fully scriptable and reproducible
• GitHub Actions integration
• Customizable: themes, fonts, typing speed, colors

Installation

brew install vhs       # Also requires ttyd and ffmpeg

Workflow

# Create tape file (script)
cat > demo.tape <<'EOF'
Output demo.gif
Set FontSize 24
Set Width 1200
Set Height 600

Type "lattice search 'knowledge graph'"
Sleep 500ms
Enter
Sleep 2s
EOF

# Generate GIF
vhs demo.tape

Tape File Format

VHS uses declarative “tape” files to script terminal sessions:

# Settings
Output demo.gif
Set Theme "Catppuccin Mocha"
Set FontSize 32
Set Width 1200
Set Height 600
Set TypingSpeed 100ms

# Actions
Type "lattice init"
Sleep 500ms
Enter
Sleep 2s

Type "lattice search 'semantic search'"
Enter
Sleep 3s

Pros

• Fully automated - perfect for CI/CD
• Multiple output formats
• Reproducible (version control tape files)
• Integration testing capabilities
• Custom themes and styling

Cons

• Requires scripting (not interactive recording)
• Larger file sizes than asciinema
• Dependencies: ttyd, ffmpeg

3. Terminalizer

Best for: Quick recordings with web player links

Key Features

• Record and generate animated GIFs
• Web player at terminalizer.com
• Edit frames and adjust delays
• Customize with CSS styles

Workflow

# Install
npm install -g terminalizer

# Record
terminalizer record demo

# Generate GIF
terminalizer render demo

# Upload for web player
terminalizer share demo

Pros

• Simple recording workflow
• Built-in web player hosting
• Frame editing capability

Cons

• Less active development than asciinema/VHS
• Larger GIF files

4. termtosvg

Best for: SVG animations

• Renders sessions as standalone SVG animations
• Scalable vector graphics
• Good for embedding in documentation

pip install termtosvg
termtosvg output.svg

5. ttygif

Best for: Simple ttyrec to GIF conversion

• Converts ttyrec files to GIFs
• Screenshots every frame
• Minimal dependencies

Linux-Specific Screen Recorders

Peek (X11 & Wayland)

• Intuitive UI for screen captures
• Quick visualizations
• Less control, simpler workflow

Gifine

• Thin UI over ffmpeg and gifsicle
• Simple and reliable
• Good for quick captures

Byzanz

• GNOME project tool
• Records X desktop as animated GIF
• Lightweight

Comparison Table

Recommendations for Lattice Demos

For README.md (GitHub)

Use asciinema + agg (GIF)

• GitHub supports embedded GIFs
• Generate with agg demo.cast demo.gif
• High quality, optimized file size

![Lattice Demo](demo.gif)

For Documentation Website

Use asciinema-player (Web)

• Interactive player with pause/copy
• Lightweight text-based format
• Professional appearance

<script src="https://unpkg.com/asciinema-player@latest/dist/bundle/asciinema-player.min.js"></script>
<link rel="stylesheet" type="text/css" href="https://unpkg.com/asciinema-player@latest/dist/bundle/asciinema-player.css" />

<asciinema-player src="demos/lattice-search.cast" cols="120" rows="30"></asciinema-player>

For Automated Demos (CI/CD)

Use VHS

• Version control tape files
• Auto-generate on releases
• Keep demos up-to-date

- name: Generate Demo GIFs
  run: |
    brew install vhs
    vhs demos/search.tape
    vhs demos/sync.tape

Example Workflow for Lattice

1. Record with asciinema

asciinema rec demos/lattice-search.cast
# Perform demo
# Ctrl+D to stop

2. Generate GIF for README

agg demos/lattice-search.cast demos/lattice-search.gif

3. Embed in Documentation

Use the .cast file directly in web player for docs site, use .gif in README.

4. Version Control

git add demos/*.cast demos/*.gif
git commit -m "docs: add lattice search demo"

Best Practices

Recording Quality

• Terminal size: Use consistent dimensions (e.g., 120x30)
• Font size: 16-24pt for readability
• Typing speed: Slow enough to follow (use VHS Set TypingSpeed)
• Pauses: Add delays after commands to show output

File Optimization

• GIFs: Use agg (optimized) or gifsicle for compression
• asciicast: Already optimized (text-based)
• MP4/WebM: Better than GIF for longer demos (use VHS)

Demo Content

• Show real workflows: Actual lattice commands
• Keep it short: 30-60 seconds per demo
• Clear output: Wait for commands to complete
• Add context: Show prompts and results

Accessibility

• Provide text alternatives: Include command listings
• Use captions: For complex demos
• High contrast: Choose readable themes

Installation Reference

# asciinema + agg (recommended)
brew install asciinema agg

# VHS (for scripting)
brew install vhs
brew install ttyd ffmpeg  # dependencies

# Terminalizer (Node.js)
npm install -g terminalizer

# termtosvg (Python)
pip install termtosvg

Sources

1. asciinema Documentation
2. asciinema GitHub
3. agg - asciinema gif generator
4. asciinema-player GitHub
5. VHS by Charmbracelet GitHub
6. Beyond Screenshots: Capture CLI Magic with VHS
7. Terminalizer GitHub
8. Terminalizer Website
9. awesome-terminal-recorder
10. Terminal Recorders: A Comprehensive Guide