ttyvid

Complete terminal recording and video generation tool. Record terminal sessions directly to .cast files, then convert to GIF/WebM with themes, animations, and custom fonts. High-performance Rust implementation with built-in PTY recording, full terminal emulation, TrueType font support, and 56+ embedded classic bitmap fonts.

Example: fdwm-x theme with animated window decoration overlay and 9-slice frame scaling

Example: Full-size terminal recording

Features

✅ Built-in recording - Direct PTY-based terminal capture to .cast files
✅ Full terminal emulation - ANSI/VT100 escape sequences
✅ Multiple output formats - .cast (asciicast v2), GIF, and WebM (with AV1)
✅ 56 embedded fonts - IBM, ATI, Verite, Tandy, Phoenix, and more
✅ TrueType font support - Load system fonts with full UTF-8 rendering
✅ Terminal cloning - Auto-detect terminal size, colors, and font with --clone
✅ UTF-8 character support - 310+ box-drawing, braille, and special characters
✅ Theme system - Customizable layouts with layers and animations
✅ MCP server integration - Built-in Model Context Protocol server with 11 tools for AI assistants
✅ Platform optimization - One-command optimization for Twitter, YouTube, TikTok, etc. with time controls
✅ GPU acceleration - wgpu support for dramatically faster rendering with automatic CPU fallback
✅ Asciicast compatibility - .cast files work with asciinema players
✅ Speed control - Adjust playback speed and FPS
✅ Frame optimization - Full frame encoding for perfect rendering

Installation

From crates.io

cargo install ttyvid

From Source

git clone https://github.com/watkinslabs/ttyvid.git
cd ttyvid
cargo build --release

The binary will be at target/release/ttyvid.

MCP Integration (Model Context Protocol)

Use ttyvid directly from Claude Code and other AI assistants! The MCP server is built directly into ttyvid - no separate installation needed.

Configure Claude Code:

Add to your MCP settings (e.g., ~/.config/claude/mcp.json):

{
  "mcpServers": {
    "ttyvid": {
      "command": "ttyvid",
      "args": ["--mcp"]
    }
  }
}

Or if installed via cargo:

{
  "mcpServers": {
    "ttyvid": {
      "command": "/path/to/ttyvid",
      "args": ["--mcp"]
    }
  }
}

Start MCP server manually (for testing):

ttyvid --mcp

The server runs on stdio and implements the Model Context Protocol 2025-06-18, exposing these tools:

Core Tools:

record - Record terminal sessions directly to .cast, GIF, or WebM
convert_recording - Convert .cast files to GIF/WebM with full customization
- Supports: themes, fonts (bitmap & TrueType), custom dimensions, speed control, multi-format output
get_version - Get ttyvid version information

Discovery Tools:

list_themes - List all 10 available themes
list_fonts - List all 56+ embedded bitmap fonts
list_system_fonts - List all available system TrueType fonts (monospace recommended)

Analysis Tools:

inspect_recording - Analyze .cast files (dimensions, duration, event count, metadata)
preview_frame - Generate single frame preview at specific timestamp
preview_theme - Generate theme preview showing color palette

Batch Tools:

batch_convert - Convert multiple .cast files in one operation

Platform Optimization:

optimize_for_platform - Auto-optimize for Twitter, YouTube, LinkedIn, TikTok, GitHub, Instagram, Slack, DEV.to
- Platform-specific presets (dimensions, FPS, themes, compression)
- Time control: fit_to_time - automatically speed up video to fit target duration
- Trimming: start_time / end_time - trim video to specific time range
- One command for perfect social media output

Use it naturally in Claude:

User: "List available system fonts"
Claude: [Uses list_system_fonts tool]
Claude: "Found 116 fonts including Liberation Mono, Noto Sans Mono, Source Code Pro..."

User: "Convert my recording.cast to GIF with fdwm-x theme at 30fps using JetBrains Mono"
Claude: [Automatically converts using ttyvid MCP tool]
Claude: "Done! Created output.gif with fdwm-x theme at 30fps using JetBrains Mono font"

User: "What's in this demo.cast file?"
Claude: [Uses inspect_recording tool]
Claude: "This recording is 80x24, runs for 45.2 seconds, and has 1,234 events"

User: "Optimize this for Twitter"
Claude: [Uses optimize_for_platform with platform='twitter']
Claude: "Optimized for Twitter! Created square 680x680 GIF at 10fps with simple theme. Ready to tweet!"

User: "Fit this 60 second demo into 30 seconds for Instagram"
Claude: [Uses optimize_for_platform with platform='instagram', fit_to_time=30]
Claude: "Optimized for Instagram! Sped up 2.0x to fit 60s into 30s, square 1080x1080 at 12fps."

User: "Trim the first 5 seconds and last 10 seconds, then optimize for YouTube"
Claude: [Uses optimize_for_platform with platform='youtube', start_time=5.0, end_time=-10]
Claude: "Optimized for YouTube! Trimmed to 5.0s-50.0s (45s total), 720p at 15fps."

Quick Start

Complete workflow:

# Step 1: Record a terminal session to .cast file
ttyvid record demo.cast
# ... interact with your terminal ...
# Exit shell (Ctrl+D or 'exit') to stop recording

# Step 2: Convert .cast to GIF or WebM
ttyvid convert -i demo.cast -o demo.gif

Direct conversion (without recording):

# Convert live terminal output via pipe
echo "Hello World" | ttyvid convert -o hello.gif

# Convert existing asciicast file
ttyvid convert -i recording.cast -o output.gif

Output formats:

# .cast file - Asciicast v2 format (compatible with asciinema)
ttyvid record output.cast

# GIF - Animated GIF with themes and effects
ttyvid convert -i recording.cast -o output.gif

# WebM - AV1-encoded video (requires --features webm)
ttyvid convert -i recording.cast -o output.webm

Advanced options:

# Clone your terminal appearance (auto-detect size, colors, and font)
ttyvid convert -i recording.cast -o output.gif --clone

# Use system font with UTF-8 support
ttyvid convert -i recording.cast -o output.gif --system-font "JetBrains Mono"

# Apply theme with custom settings
ttyvid convert -i recording.cast -o output.gif --theme fdwm-x --fps 30 --speed 1.5

Advanced Features

TrueType Font Support

Use system fonts instead of bitmap fonts for better UTF-8 character support:

# Use a specific system font
ttyvid convert -i recording.cast -o output.gif --system-font "JetBrains Mono"

# Use system default monospace font
ttyvid convert -i recording.cast -o output.gif --system-font monospace

# Keywords: "monospace", "default", or "system" all use system default
ttyvid convert -i recording.cast -o output.gif --system-font default

# Specify font size (in pixels, default: 16)
ttyvid convert -i recording.cast -o output.gif --system-font monospace --font-size 20

# Load font from file path
ttyvid convert -i recording.cast -o output.gif --system-font /path/to/font.ttf

List available fonts:

# List all system TrueType fonts
ttyvid list-fonts --system

# List embedded bitmap fonts
ttyvid list-fonts --bitmap

# List both
ttyvid list-fonts

Font features:

Full Unicode/UTF-8 rendering with proper baseline alignment
Automatic cell sizing based on font metrics
Supports font files (.ttf, .otf) or font names
Note: Use monospace fonts designed for terminals for best results
Non-monospace fonts will work but may not look ideal

Font fallback chain:

If specified font not found, tries system default monospace
Finally falls back to embedded bitmap fonts
Supports loading from file paths or system font directories

Font Conversion

Convert TrueType/OpenType fonts to .fd bitmap format with full UTF-8 support and emoji:

# Convert a system font to .fd format
ttyvid convert-font --font "JetBrains Mono" --size 16 --output my_font.fd

# Convert with specific size
ttyvid convert-font --font "Liberation Mono" --size 20 --output liberation_20.fd

# Convert from font file
ttyvid convert-font --font /path/to/font.ttf --size 16 --output custom.fd

Font converter features:

Automatic fallback fonts: Loads Symbola, Noto Emoji, DejaVu Sans for emoji/symbol coverage
Smart character enumeration: Includes all printable ASCII, Unicode blocks, box drawing, emoji
Deduplication: Uses blank and sameas directives to reduce file size by 50-80%
Proper glyph positioning: Uses natural font metrics (xmin/ymin) for accurate rendering
UTF-8 support: Full Unicode coverage including emoji (✨ 🚀 💻) and special characters

Pre-converted fonts are available in themes/font_Ext/:

Adwaita Mono 16px (with emoji fallback)
Liberation Mono 16px
Noto Sans Mono 16px
Source Code Pro 16px
Symbola 16px (emoji/symbol font)
Noto Emoji 16px

Rebuild all fonts:

make -f Makefile.fonts

Character coverage:

All 256 ASCII/CP437 characters
Latin Extended (À Ñ ü ö ä)
Greek/Cyrillic (α β γ Д Ж И)
Box Drawing (─ │ ┌ ┐ └ ┘ ╔ ╗ ╚ ╝)
Block Elements (█ ▓ ▒ ░ ▀ ▄ ▌ ▐)
Arrows (← ↑ → ↓ ⇐ ⇑ ⇒ ⇓)
Math Symbols (∀ ∂ ∈ ∇ ∏ ∑ √ ∞)
Emoji & Symbols (✨ ✓ ✗ ❤ ★ ☀ ☁ 🚀 💻)

Terminal Cloning

Clone your current terminal's appearance for authentic recordings:

# Auto-detect terminal size, colors, and font
ttyvid convert -i recording.cast -o output.gif --clone

# Just use terminal colors (with theme or bitmap font)
ttyvid convert -i recording.cast -o output.gif --terminal-colors

What gets cloned:

Terminal dimensions (width × height)
Full 16-color palette
Default foreground/background colors
System font (with TrueType support)

Color Support

ttyvid supports full 256-color terminal palettes with automatic terminal color detection:

256-Color Palette:

System colors (0-15): Standard ANSI colors (black, red, green, yellow, blue, magenta, cyan, white + bright variants)
Color cube (16-231): 6×6×6 RGB color cube for extended color support
Grayscale (232-255): 24-level grayscale ramp for smooth gradients

Color modes:

# Use theme's predefined palette
ttyvid convert -i recording.cast -o output.gif --theme fdwm-x

# Query and use your terminal's actual colors
ttyvid convert -i recording.cast -o output.gif --terminal-colors

# Clone terminal appearance (includes colors, size, and font)
ttyvid convert -i recording.cast -o output.gif --clone

Terminal color querying:

Automatically detects your terminal's 16 ANSI colors
Queries default foreground/background colors via OSC sequences
Falls back to standard palette if querying fails
Works with most modern terminal emulators

Implementation:

src/renderer/colors.rs:60-108 - Full 256-color palette with system/cube/grayscale
src/renderer/colors.rs:19-58 - Live terminal color querying via OSC 4/10/11

UTF-8 Character Support

310+ Unicode characters supported for TUI applications like bpytop, htop, etc.:

Box-drawing: Single/double line, rounded corners, mixed styles
Block elements: Full, half, quarter blocks in all orientations
Braille patterns: All 256 patterns (⠀ through ⣿) for graphs
Arrows and symbols: ←↑→↓, ▲▼◀▶, •◆■□, and more
Math symbols: ≈≥≤≠±×÷°, fractions, superscripts

Rendering modes:

Bitmap fonts: UTF-8 → CP437 mapping for compatibility
TrueType fonts: Native UTF-8 rendering with full Unicode support

Recording

ttyvid includes built-in PTY-based terminal recording, eliminating the need for external tools like asciinema.

Basic Recording

# Start recording - launches your default shell
ttyvid record output.cast

# Record with custom shell
ttyvid record output.cast --shell /bin/zsh

# Record with specific dimensions
ttyvid record output.cast --columns 120 --rows 30

Recording Options

ttyvid record [OPTIONS] <OUTPUT>

Arguments:
  <OUTPUT>  Output .cast file path

Options:
  -s, --shell <SHELL>      Shell to execute [default: $SHELL or /bin/sh]
  -c, --columns <COLS>     Terminal width [default: 80]
  -r, --rows <ROWS>        Terminal height [default: 24]
  -h, --help               Print help

How Recording Works

Spawns a PTY (pseudo-terminal) with the specified shell
Captures all output with precise microsecond timing
Saves to .cast v2 format (compatible with asciinema)
Automatically records terminal resize events
Exit the shell (Ctrl+D or exit) to stop recording

Usage

Convert: From stdin (pipe)

echo -e "Hello \e[31mRed\e[0m World" | ttyvid convert -o hello.gif

Convert: From asciicast file

ttyvid convert -i recording.cast -o output.gif

Convert: With custom theme and font

ttyvid convert -i recording.cast -o output.gif \
  --theme windows7 \
  --font IBM_VGA8 \
  --fps 30 \
  --speed 1.5

Convert: Advanced options

ttyvid convert \
  --input recording.cast \
  --output output.gif \
  --theme mac \
  --font Verite_9x16 \
  --fps 30 \
  --speed 2.0 \
  --columns 80 \
  --rows 25 \
  --title "My Demo" \
  --no-gaps \
  --trailer

The --trailer option adds 1.5 seconds of the final frame at the end before looping, creating a pause effect for better viewing.

Command Reference

ttyvid record

ttyvid record [OPTIONS] <OUTPUT>

Arguments:
  <OUTPUT>  Output .cast file path

Options:
  -s, --shell <SHELL>      Shell to execute [default: $SHELL or /bin/sh]
  -c, --columns <COLS>     Terminal width [default: 80]
  -r, --rows <ROWS>        Terminal height [default: 24]
  -h, --help               Print help

ttyvid convert

ttyvid convert [OPTIONS] --output <FILE>

Options:
  -i, --input <FILE>          Input asciicast file (reads from stdin if not provided)
  -o, --output <FILE>         Output file (.gif or .webm)
  -t, --theme <THEME>         Theme name or path [default: default]
  -f, --font <FONT>           Font name (bitmap font)
      --system-font <FONT>    System font name, file path, or TrueType/OpenType
                              Use "monospace", "default", or "system" for system default
      --font-size <SIZE>      Font size in pixels for TrueType fonts [default: 16]
      --clone                 Auto-detect terminal size, colors, and font
      --terminal-colors       Use terminal's color palette
      --fps <FPS>             Frames per second (3-100) [default: 10]
      --speed <SPEED>         Speed multiplier [default: 1.0]
  -c, --columns <COLUMNS>     Terminal width in columns
  -r, --rows <ROWS>           Terminal height in rows
  -l, --loop <LOOP>           Number of loops (0 = infinite) [default: 0]
  -d, --delay <DELAY>         Delay before loop restart (milliseconds) [default: 100]
  -g, --no-gaps               Remove gaps in recording
      --trailer               Add trailer at end
      --title <TITLE>         Title text
      --no-autowrap           Disable auto line wrap
      --no-cursor             Hide cursor in output
      --underlay <UNDERLAY>   Underlay image path
      --quality <QUALITY>     WebM quality 0-100 [default: 50]
  -h, --help                  Print help
  -V, --version               Print version

ttyvid list-fonts

ttyvid list-fonts [OPTIONS]

Options:
      --system                Show system TrueType fonts
      --bitmap                Show embedded bitmap fonts
  -h, --help                  Print help

Examples:
  ttyvid list-fonts --system      # List all system fonts
  ttyvid list-fonts --bitmap      # List embedded bitmap fonts
  ttyvid list-fonts               # List both

ttyvid --mcp

ttyvid --mcp

Start the Model Context Protocol (MCP) server for AI assistant integration.
The server runs on stdio and implements MCP version 2025-06-18.

Available MCP Tools (11 total):

Core Tools:
  - record                Record terminal sessions to .cast/GIF/WebM
  - convert_recording     Convert .cast files to GIF/WebM with full options
                         (themes, fonts, dimensions, speed, multi-format)
  - get_version          Get ttyvid version information

Discovery Tools:
  - list_themes          List all 10 available themes
  - list_fonts           List all 56+ embedded bitmap fonts
  - list_system_fonts    List all system TrueType fonts

Analysis Tools:
  - inspect_recording    Analyze .cast metadata (dimensions, duration, events)
  - preview_frame        Generate single frame preview at timestamp
  - preview_theme        Generate theme preview with color palette

Batch Tools:
  - batch_convert        Convert multiple .cast files at once

Platform Optimization:
  - optimize_for_platform  Auto-optimize for social media platforms
                          Platforms: twitter, youtube, linkedin, tiktok,
                                    github, instagram, slack, devto
                          Parameters:
                            - input: Path to .cast file (required)
                            - output: Output file path (required)
                            - platform: Target platform name (required)
                            - theme: Custom theme override (optional)
                            - fit_to_time: Target duration in seconds (optional)
                                          Automatically speeds up video to fit
                            - start_time: Trim start in seconds (optional)
                            - end_time: Trim end in seconds (optional)
                          Example: {"platform": "twitter"} → 680x680, 10fps, simple theme

Example:
  ttyvid --mcp            # Start MCP server on stdio

Integration:
  Add to ~/.config/claude/mcp.json:
  {
    "mcpServers": {
      "ttyvid": {
        "command": "ttyvid",
        "args": ["--mcp"]
      }
    }
  }

Performance

This Rust implementation is significantly faster than the original Python/Cython version:

Startup time: ~50-100ms
Frame generation: Highly optimized with GPU batch rendering
Memory usage: Efficient with object pooling
Binary size: ~5-8 MB (release build with LTO)
Progress tracking: Live ETA display and total time reporting

Architecture

Modules

cli: Command-line argument parsing with record and convert subcommands (clap)
recorder: PTY-based terminal session recording with .cast output
input: stdin and asciicast file readers
terminal: Full VT100/ANSI terminal emulator (vte)
renderer: Text to pixel conversion with bitmap fonts
encoder: GIF and WebM encoding with optimizations
theme: Layer-based theme system with animations
assets: Embedded fonts, themes, and layer images
mcp_server: Model Context Protocol server for AI assistant integration

Data Flow

Recording:

Shell → PTY → Recorder → .cast file

Converting:

Input (stdin/cast) → Terminal Emulator →
Renderer → Encoder → Output (GIF/WebM)

Available Fonts

All fonts are automatically embedded at compile time from themes/fonts/:

IBM: BIOS, CGA, EGA, VGA, MDA, PS/2, 3270pc, Conv, ISO8/9
ATI: 8x8, 8x14, 8x16, 9x14, 9x16, SmallW_6x8
Phoenix: BIOS, EGA_8x8, EGA_8x14, EGA_8x16, EGA_9x14
Compaq: Thin_8x8, Thin_8x14, Thin_8x16
Tandy: New/Old TV, New/Old 225, New Mono
Toshiba: LCD_8x8, LCD_8x16
Verite: 8x8, 8x14, 8x16, 9x14, 9x16 (default)
Wyse: 700a, 700a-2y, 700b-2y
Others: AMI_BIOS, DTK_BIOS, ITT_BIOS, VTech_BIOS, ATT_PC6300, AmstradPC1512, Kaypro2K, VGA_SquarePx

Available Themes

Built-in themes in themes/:

default - Classic terminal look
windows7 - Windows 7 CMD style with dialog frame
mac - macOS Terminal style with window controls
fdwm - Floating window manager theme
fdwm-x - Extended window manager with animations
game - Retro gaming console frame
bar - Status bar theme
opensource - Open source branding banner
scripted - Script demonstration with annotations
simple - Minimal theme (terminal only)

Theme System

ttyvid features a powerful layer-based theme system that allows extensive customization of the final output with support for animated components, flexible positioning, and multiple scaling modes.

Layer-Based Architecture

Themes are built from layers - individual image files (GIF/PNG) that are composited together:

Underlays (depth < 0): Rendered behind the terminal output (backgrounds, frames)
Overlays (depth ≥ 0): Rendered on top of the terminal output (window controls, decorations)

Each layer can be:

Static or animated (multi-frame GIF)
Positioned anywhere on the canvas
Scaled using different algorithms
Animated with custom speed and looping

Layer Rendering Modes

Layers support multiple rendering modes for different visual effects:

Copy Mode

mode: copy

Direct pixel-perfect copying from source to destination. Ideal for static decorative elements.

Tile Mode

mode: tile

Repeats the layer image across the entire canvas. Perfect for textured backgrounds or patterns.

Center Mode

mode: center

Centers the layer on the canvas. Useful for logos or centered decorative elements.

Scale Mode

mode: scale

Scales the layer to fit the destination bounds using nearest-neighbor interpolation.

9-Slice Scaling

mode: 9slice
nineslice:
  outer_left: 10
  outer_top: 10
  outer_right: 10
  outer_bottom: 10
  inner_left: 20
  inner_top: 20
  inner_right: 20
  inner_bottom: 20

Advanced scaling that preserves corners and edges while stretching the center. Essential for window frames and dialogs that need to resize without distorting decorative borders.

How it works:

Divides the source image into 9 regions (4 corners, 4 edges, 1 center)
Corners remain fixed size
Edges stretch in one direction only
Center stretches in both directions

3-Slice Scaling

mode: 3slice

Similar to 9-slice but for horizontal or vertical stretching only. Useful for title bars and status bars.

Animated Layers

Layers support animated GIF files with full control over playback:

layers:
  - depth: -1
    file: layers/animated-background.gif
    mode: center
    animation:
      speed: 1.5        # 1.5x speed multiplier
      loop: true        # Loop animation
      start_frame: 0    # Start at first frame

Animation features:

Multi-frame GIF support
Independent speed control per layer
Optional looping
Frame timing preserved from source GIF
Synchronized with video output timeline

Layer Positioning

Flexible positioning system with support for absolute and relative coordinates:

layers:
  - depth: 1
    file: layers/window-controls.gif
    mode: copy
    dst_bounds:
      left: 10          # 10 pixels from left
      top: 10           # 10 pixels from top
      right: -110       # 110 pixels from right edge (negative = from right)
      bottom: auto      # Auto-calculate based on image size

Positioning options:

Absolute pixel coordinates
Negative values offset from opposite edge
auto for automatic sizing
Per-layer bounds control

Custom Theme Example

Create a custom theme with window frame and animated decorations:

name: my-custom-theme
background: 0           # Black background
foreground: 7           # White text
transparent: 0          # Transparency color index

padding:
  left: 20
  top: 40
  right: 20
  bottom: 20

title:
  foreground: 15        # Bright white
  background: 4         # Red
  x: 30
  y: 10
  font_size: 1.5

layers:
  # Background frame (underlay)
  - depth: -1
    file: layers/my-frame.gif
    mode: 9slice
    nineslice:
      outer_left: 0
      outer_top: 0
      outer_right: auto
      outer_bottom: auto
      inner_left: 30
      inner_top: 30
      inner_right: auto
      inner_bottom: auto

  # Animated decoration (overlay)
  - depth: 1
    file: layers/spinner.gif
    mode: copy
    animation:
      speed: 2.0
      loop: true
    dst_bounds:
      left: -50
      top: 10
      right: auto
      bottom: auto

Embedded vs Custom Layers

Embedded layers (included in binary):

11 pre-built layer images
Loaded automatically by filename
No external files needed

Custom layers (filesystem):

Place images in themes/layers/ or specify full path
Falls back to embedded if not found
Supports both GIF and PNG formats

Creating Custom Layers

Design your layer in any image editor
Export as GIF (with animation if desired)
Save to themes/layers/your-layer.gif

Reference in theme YAML:

layers:
  - depth: -1
    file: layers/your-layer.gif
    mode: 9slice

Theme Customization Workflow

Start with an existing theme as template
Modify colors, padding, and positioning
Add or replace layer images
Adjust animation speeds and rendering modes
Test with: ttyvid -i test.cast -o output.gif --theme my-theme

The theme system is fully extensible - you can mix embedded assets with custom images, create complex multi-layer compositions, and animate individual components independently for professional-looking terminal recordings.

GPU Acceleration

ttyvid includes GPU acceleration by default using wgpu for dramatically faster frame rendering with GPU batch processing.

Installation

# Default installation includes GPU support
cargo install ttyvid

# Build from source (includes GPU by default)
cargo build --release

# CPU-only build (opt-out of GPU for minimal binary)
cargo install ttyvid --no-default-features --features webm

How It Works

GPU Batch Rendering: Renders all frames in a single GPU operation with minimal CPU↔GPU syncs
Automatic Chunking: Intelligently splits large frame counts to respect GPU buffer limits
Automatic CPU Fallback: Seamlessly uses CPU if GPU unavailable or initialization fails
No External Dependencies: wgpu compiles directly into the binary
Cross-Platform: Works on Windows (DX12), macOS (Metal), Linux (Vulkan)
Enabled by Default: GPU support included in standard installation with transparent fallback

Performance Gains

GPU batch rendering provides significant speedups:

2-5x faster on typical recordings (200-300 frames)
5-10x faster on large recordings (1000+ frames, high resolution)
Single sync point for all frames vs per-frame CPU syncs
Parallel frame processing utilizing GPU compute units

Progress Tracking

Both CPU and GPU modes feature enhanced progress display:

Live ETA: Shows estimated time to completion ("ETA: 14.5s" or "ETA: 2.3m")
Total Time: Displays elapsed time when complete ("total time: 1m 23s")
Clean Output: Minimal logging during encoding

When to Use GPU

✅ Large output dimensions (1280x720+, 1080p, 4K)
✅ High FPS videos (30+ fps)
✅ Long recordings (500+ frames)
✅ Batch processing many videos
✅ Local workstation with GPU

When CPU-Only Is Fine

✅ Headless servers / Docker containers
✅ Small dimensions (640x480, 680x680)
✅ Low FPS (8-15 fps) - typical GIF range
✅ Short recordings (<200 frames)
✅ Single video conversions

TODO

SIMD optimizations for CPU path
True color (24-bit RGB) support
Additional output formats (MP4, APNG)

Comparison with Original

Feature	Original (Python)	ttyvid (Rust)	Status
Terminal Emulation	Custom	Full ANSI/VT100	✅
GIF Encoding	Custom	gif crate	✅
WebM Encoding	N/A	rav1e (AV1)	✅
Font Support	50+ .fd fonts	56 bitmap + TrueType	✅
UTF-8 Characters	Limited	310+ characters	✅
Terminal Cloning	N/A	Full (size/colors/font)	✅
Theme System	Full with layers	Full with layers	✅
GPU Acceleration	N/A	Default (wgpu batch)	✅
Progress Tracking	Basic	ETA + Total Time	✅
Performance	Good	Excellent	✅
Binary Size	N/A (Python)	~5-8 MB	✅
Dependencies	Python + libs	None (static)	✅

Building from Source

Requirements

Rust 1.70+ (2021 edition)
Cargo

Build Commands

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Build with WebM support (requires rav1e)
cargo build --release --features webm

# Run tests
cargo test

# Run with example
echo "Test" | cargo run --release -- -o test.gif

Build System

The project uses build.rs to automatically:

Scan themes/fonts/ directory
Generate font embedding code at compile time
Create font lookup tables

To add new fonts, simply place .fd files in themes/fonts/ and rebuild.

License

MIT

Credits

Original ttygif concept and fonts
Rust implementation with modern architecture
gif crate for GIF encoding
rav1e for WebM/AV1 encoding

Contributing

Contributions welcome! Areas of interest:

Performance optimizations (SIMD, GPU, parallel)
Additional output formats
Extended color support (true color)
Bug fixes and documentation

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
assets		assets
src		src
test_output		test_output
themes		themes
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
GPU_ACCELERATION_ANALYSIS.md		GPU_ACCELERATION_ANALYSIS.md
GPU_IMPLEMENTATION_SUMMARY.md		GPU_IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
Makefile.fonts		Makefile.fonts
README.md		README.md
demo-preview.gif		demo-preview.gif
test_batch_gpu.sh		test_batch_gpu.sh
test_font_debug.mk		test_font_debug.mk

License

watkinslabs/ttyvid

Folders and files

Latest commit

History

Repository files navigation

ttyvid

Features

Installation

From crates.io

From Source

MCP Integration (Model Context Protocol)

Quick Start

Advanced Features

TrueType Font Support

Font Conversion

Terminal Cloning

Color Support

UTF-8 Character Support

Recording

Basic Recording

Recording Options

How Recording Works

Usage

Convert: From stdin (pipe)

Convert: From asciicast file

Convert: With custom theme and font

Convert: Advanced options

Command Reference

ttyvid record

ttyvid convert

ttyvid list-fonts

ttyvid --mcp

Performance

Architecture

Modules

Data Flow

Available Fonts

Available Themes

Theme System

Layer-Based Architecture

Layer Rendering Modes

Copy Mode

Tile Mode

Center Mode

Scale Mode

9-Slice Scaling

3-Slice Scaling

Animated Layers

Layer Positioning

Custom Theme Example

Embedded vs Custom Layers

Creating Custom Layers

Theme Customization Workflow

GPU Acceleration

Installation

How It Works

Performance Gains

Progress Tracking

When to Use GPU

When CPU-Only Is Fine

TODO

Comparison with Original

Building from Source

Requirements

Build Commands

Build System

License

Credits

Contributing

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Contributors 2

Packages