Terminal to GIF: Capturing Command-Line Magic¶

Objective: Master terminal recording and GIF conversion to create engaging documentation, tutorials, and demonstrations. When you need to show command-line workflows, when you want to create animated documentation, when you're building interactive tutorials—terminal recording becomes your weapon of choice.

Terminal output is the heartbeat of system administration and development. This tutorial shows you how to capture that magic and convert it into shareable, animated GIFs that bring your command-line workflows to life.

0) Prerequisites (Read Once, Live by Them)¶

The Five Commandments¶

Understand recording tools
Terminal recording with asciinema and ttyrec
Screen recording with ffmpeg and gifify
Manual capture with script and replay
Interactive recording with ttyd and asciinema
Master conversion workflows
ASCII to GIF conversion
Video to GIF optimization
Color scheme preservation
Frame rate and quality tuning
Know your terminal environments
Terminal emulator compatibility
Font and color scheme requirements
Screen resolution considerations
Cross-platform recording
Validate everything
Test recording quality and clarity
Verify GIF playback and compatibility
Check file size and optimization
Monitor conversion performance
Plan for production
Design for clear, readable output
Enable consistent recording environments
Create reusable recording scripts
Document conversion workflows

Why These Principles: Terminal recording requires understanding both capture techniques and conversion optimization. Understanding these patterns prevents poor quality recordings and enables professional documentation.

1) Setup and Dependencies¶

Required Tools¶

# Install recording tools
# macOS
brew install asciinema ffmpeg gifify

# Ubuntu/Debian
sudo apt update
sudo apt install asciinema ffmpeg imagemagick

# CentOS/RHEL
sudo yum install asciinema ffmpeg ImageMagick

# Install additional tools
pip install asciinema-edit
npm install -g gifify

Why Tool Setup Matters: Proper dependencies enable high-quality recording and conversion. Understanding these patterns prevents installation issues and enables professional output.

Project Structure¶

terminal-gif/
├── recordings/
│   ├── raw/
│   ├── processed/
│   └── gifs/
├── scripts/
│   ├── record.sh
│   ├── convert.sh
│   └── optimize.sh
└── configs/
    ├── asciinema.json
    └── ffmpeg.conf

Why Structure Matters: Organized project structure enables systematic recording and conversion workflows. Understanding these patterns prevents file chaos and enables efficient production.

2) ASCII Recording with asciinema¶

Basic Recording¶

# Start recording session
asciinema rec demo.cast

# Your terminal session is now being recorded
echo "Hello, World!"
ls -la
git status
git log --oneline -5

# Stop recording with Ctrl+D or type 'exit'

Why ASCII Recording Matters: ASCII recording captures exact terminal output with timing information. Understanding these patterns prevents poor quality captures and enables precise reproduction.

Advanced Recording Options¶

# Record with specific options
asciinema rec --title "Git Workflow Demo" \
              --command "bash" \
              --max-wait 2 \
              --idle-time-limit 5 \
              demo.cast

# Record with custom theme
asciinema rec --theme solarized-dark demo.cast

Why Advanced Options Matter: Custom recording options enable professional output and better user experience. Understanding these patterns prevents generic recordings and enables branded content.

Recording Configuration¶

# ~/.config/asciinema/config
{
  "record": {
    "maxWait": 2,
    "idleTimeLimit": 5,
    "command": "bash"
  },
  "play": {
    "speed": 1,
    "loop": false
  },
  "upload": {
    "url": "https://asciinema.org"
  }
}

Why Configuration Matters: Proper configuration enables consistent recording behavior. Understanding these patterns prevents recording inconsistencies and enables professional workflows.

3) Converting ASCII to GIF¶

Basic Conversion¶

# Convert ASCII recording to GIF
asciinema play demo.cast | asciinema-edit speed 2 | asciinema-edit cut 0,30 | asciinema-edit quantize 16 > demo.gif

Why Basic Conversion Matters: Simple conversion enables quick GIF creation. Understanding these patterns prevents conversion failures and enables rapid prototyping.

Advanced Conversion with asciinema-edit¶

# Install asciinema-edit
pip install asciinema-edit

# Convert with custom settings
asciinema-edit speed 1.5 demo.cast | \
asciinema-edit cut 10,60 | \
asciinema-edit quantize 16 | \
asciinema-edit add-marker 30 "Important Step" | \
asciinema-edit add-marker 45 "Next Step" > demo.gif

Why Advanced Conversion Matters: Advanced editing enables professional output with custom timing and markers. Understanding these patterns prevents basic conversions and enables sophisticated editing.

Custom Conversion Script¶

#!/bin/bash
# convert-to-gif.sh
INPUT_FILE=$1
OUTPUT_FILE=$2
SPEED=${3:-1.5}
START_TIME=${4:-0}
END_TIME=${5:-60}

asciinema-edit speed $SPEED $INPUT_FILE | \
asciinema-edit cut $START_TIME,$END_TIME | \
asciinema-edit quantize 16 | \
asciinema-edit add-marker 30 "Key Point" | \
asciinema-edit add-marker 45 "Next Step" > $OUTPUT_FILE

echo "Converted $INPUT_FILE to $OUTPUT_FILE"

Why Custom Scripts Matter: Automated conversion enables consistent output and batch processing. Understanding these patterns prevents manual conversion and enables efficient workflows.

4) Screen Recording with ffmpeg¶

Direct Screen Recording¶

# Record screen directly to GIF
ffmpeg -f x11grab -r 15 -s 1920x1080 -i :0.0 -vf "fps=15,scale=800:-1:flags=lanczos,palettegen" palette.png
ffmpeg -f x11grab -r 15 -s 1920x1080 -i :0.0 -i palette.png -lavfi "fps=15,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse" output.gif

Why Screen Recording Matters: Direct screen recording captures exact visual output. Understanding these patterns prevents recording issues and enables precise visual capture.

Terminal-Focused Recording¶

# Record specific terminal window
ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0+100,100 -vf "fps=15,scale=800:-1:flags=lanczos,palettegen" palette.png
ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0+100,100 -i palette.png -lavfi "fps=15,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse" terminal.gif

Why Terminal-Focused Recording Matters: Focused recording captures only relevant terminal content. Understanding these patterns prevents unnecessary content and enables clean output.

High-Quality Recording¶

# High-quality recording with optimization
ffmpeg -f x11grab -r 30 -s 1920x1080 -i :0.0 \
  -vf "fps=15,scale=800:-1:flags=lanczos,palettegen=reserve_transparent=0" \
  palette.png

ffmpeg -f x11grab -r 30 -s 1920x1080 -i :0.0 \
  -i palette.png \
  -lavfi "fps=15,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer" \
  -t 30 \
  high-quality.gif

Why High-Quality Recording Matters: Optimized recording enables professional output with minimal file size. Understanding these patterns prevents poor quality and enables efficient distribution.

5) Manual Terminal Capture¶

Using script and replay¶

# Record terminal session
script -t 2>timing.log -a output.log

# Your terminal session
echo "Hello, World!"
ls -la
git status

# Stop recording
exit

# Replay the session
scriptreplay timing.log output.log

Why Manual Capture Matters: Manual capture enables precise control over recording content. Understanding these patterns prevents automated recording issues and enables custom workflows.

Converting script output to GIF¶

# Convert script output to GIF
scriptreplay timing.log output.log | \
ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0 \
  -vf "fps=15,scale=800:-1:flags=lanczos,palettegen" \
  palette.png

scriptreplay timing.log output.log | \
ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0 \
  -i palette.png \
  -lavfi "fps=15,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse" \
  script-output.gif

Why Script Conversion Matters: Script-based conversion enables precise terminal reproduction. Understanding these patterns prevents timing issues and enables accurate replay.

6) Interactive Recording with ttyd¶

Web-based Terminal Recording¶

# Install ttyd
brew install ttyd  # macOS
sudo apt install ttyd  # Ubuntu

# Start web terminal
ttyd -p 8080 bash

# Access at http://localhost:8080
# Record the web terminal with screen recording tools

Why Web Terminal Recording Matters: Web-based recording enables cross-platform compatibility. Understanding these patterns prevents platform-specific issues and enables universal access.

Recording Web Terminal¶

# Record web terminal with ffmpeg
ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0 \
  -vf "fps=15,scale=800:-1:flags=lanczos,palettegen" \
  palette.png

ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0 \
  -i palette.png \
  -lavfi "fps=15,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse" \
  web-terminal.gif

Why Web Terminal Recording Matters: Web-based recording enables consistent cross-platform output. Understanding these patterns prevents platform-specific issues and enables universal compatibility.

7) Optimization and Quality Control¶

GIF Optimization¶

# Optimize GIF file size
gifsicle -O3 --colors 256 --lossy=80 input.gif -o optimized.gif

# Further optimization
gifsicle -O3 --colors 128 --lossy=80 input.gif -o highly-optimized.gif

Why Optimization Matters: Optimized GIFs enable faster loading and better user experience. Understanding these patterns prevents large file sizes and enables efficient distribution.

Quality Control Script¶

#!/bin/bash
# quality-control.sh
INPUT_FILE=$1
MAX_SIZE=${2:-5MB}
MAX_DIMENSIONS=${3:-800x600}

# Check file size
FILE_SIZE=$(stat -f%z "$INPUT_FILE" 2>/dev/null || stat -c%s "$INPUT_FILE")
MAX_SIZE_BYTES=$(echo $MAX_SIZE | sed 's/MB/*1024*1024/' | bc)

if [ $FILE_SIZE -gt $MAX_SIZE_BYTES ]; then
    echo "Warning: File size ($FILE_SIZE bytes) exceeds limit ($MAX_SIZE)"
fi

# Check dimensions
DIMENSIONS=$(identify -format "%wx%h" "$INPUT_FILE")
if [[ "$DIMENSIONS" > "$MAX_DIMENSIONS" ]]; then
    echo "Warning: Dimensions ($DIMENSIONS) exceed limit ($MAX_DIMENSIONS)"
fi

echo "Quality check complete for $INPUT_FILE"

Why Quality Control Matters: Quality control ensures consistent output standards. Understanding these patterns prevents poor quality output and enables professional results.

8) Automation and Batch Processing¶

Batch Conversion Script¶

#!/bin/bash
# batch-convert.sh
INPUT_DIR=$1
OUTPUT_DIR=$2
SPEED=${3:-1.5}

mkdir -p $OUTPUT_DIR

for file in $INPUT_DIR/*.cast; do
    filename=$(basename "$file" .cast)
    echo "Converting $file to $OUTPUT_DIR/$filename.gif"

    asciinema-edit speed $SPEED "$file" | \
    asciinema-edit quantize 16 > "$OUTPUT_DIR/$filename.gif"
done

echo "Batch conversion complete"

Why Batch Processing Matters: Automated batch processing enables efficient workflow management. Understanding these patterns prevents manual conversion and enables scalable production.

Automated Recording Script¶

#!/bin/bash
# auto-record.sh
SESSION_NAME=$1
COMMANDS_FILE=$2
OUTPUT_FILE=$3

# Start recording
asciinema rec $OUTPUT_FILE &
RECORD_PID=$!

# Wait for recording to start
sleep 2

# Execute commands
while IFS= read -r command; do
    echo "Executing: $command"
    eval "$command"
    sleep 1
done < "$COMMANDS_FILE"

# Stop recording
kill $RECORD_PID
wait $RECORD_PID

echo "Recording complete: $OUTPUT_FILE"

Why Automated Recording Matters: Automated recording enables consistent, repeatable captures. Understanding these patterns prevents manual recording errors and enables systematic documentation.

9) Advanced Techniques¶

Multi-terminal Recording¶

# Record multiple terminals simultaneously
tmux new-session -d -s recording
tmux split-window -h
tmux split-window -v

# Start recording in each pane
tmux send-keys -t 0 "asciinema rec pane1.cast" Enter
tmux send-keys -t 1 "asciinema rec pane2.cast" Enter
tmux send-keys -t 2 "asciinema rec pane3.cast" Enter

# Your multi-terminal workflow
# ...

# Stop all recordings
tmux send-keys -t 0 C-d
tmux send-keys -t 1 C-d
tmux send-keys -t 2 C-d

Why Multi-terminal Recording Matters: Multi-terminal recording captures complex workflows. Understanding these patterns prevents single-terminal limitations and enables comprehensive documentation.

Synchronized Recording¶

# Synchronized recording with timestamps
timestamp=$(date +%s)
asciinema rec "session-$timestamp.cast" &
asciinema rec "session-$timestamp-pane2.cast" &

# Synchronized commands
echo "Starting synchronized session at $(date)"
# ... your synchronized workflow ...

# Stop synchronized recording
pkill asciinema

Why Synchronized Recording Matters: Synchronized recording enables coordinated multi-terminal workflows. Understanding these patterns prevents timing issues and enables complex documentation.

10) Best Practices¶

Recording Best Practices¶

# Recording best practices
recording_best_practices = {
    "terminal_size": "Use consistent terminal dimensions (80x24 or 120x30)",
    "font_choice": "Use monospace fonts (Fira Code, JetBrains Mono)",
    "color_scheme": "Use high-contrast color schemes for better visibility",
    "typing_speed": "Type at moderate speed for better readability",
    "pauses": "Add strategic pauses for emphasis and comprehension",
    "cleanup": "Clean up terminal history and sensitive information"
}

Why Best Practices Matter: Consistent practices enable professional output. Understanding these patterns prevents poor quality recordings and enables professional documentation.

Conversion Best Practices¶

# Conversion best practices
conversion_best_practices = {
    "frame_rate": "Use 15-20 FPS for smooth playback",
    "color_reduction": "Reduce colors to 256 or fewer for smaller files",
    "dimensions": "Keep width under 800px for web compatibility",
    "duration": "Keep recordings under 60 seconds for engagement",
    "optimization": "Use gifsicle for further optimization",
    "testing": "Test playback on different devices and browsers"
}

Why Conversion Best Practices Matter: Optimized conversion enables better user experience. Understanding these patterns prevents poor quality output and enables professional results.

11) TL;DR Runbook¶

Essential Commands¶

# Record terminal session
asciinema rec demo.cast

# Convert to GIF
asciinema-edit speed 1.5 demo.cast | asciinema-edit quantize 16 > demo.gif

# Optimize GIF
gifsicle -O3 --colors 256 --lossy=80 demo.gif -o optimized.gif

# Record screen directly
ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0 -vf "fps=15,scale=800:-1:flags=lanczos,palettegen" palette.png
ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0 -i palette.png -lavfi "fps=15,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse" output.gif

Essential Patterns¶

# Essential terminal recording patterns
recording_patterns = {
    "ascii_recording": "Use asciinema for precise terminal capture",
    "screen_recording": "Use ffmpeg for visual screen capture",
    "optimization": "Optimize GIFs for web distribution",
    "automation": "Automate recording and conversion workflows",
    "quality_control": "Implement quality checks and standards",
    "batch_processing": "Process multiple recordings efficiently"
}

Quick Reference¶

# Essential terminal recording operations
# 1. Record ASCII session
asciinema rec session.cast

# 2. Convert to GIF
asciinema-edit speed 1.5 session.cast | asciinema-edit quantize 16 > session.gif

# 3. Optimize GIF
gifsicle -O3 --colors 256 --lossy=80 session.gif -o optimized.gif

# 4. Record screen directly
ffmpeg -f x11grab -r 15 -s 800x600 -i :0.0 -vf "fps=15,scale=800:-1:flags=lanczos,palettegen" palette.png

# 5. Batch convert
for file in *.cast; do asciinema-edit speed 1.5 "$file" | asciinema-edit quantize 16 > "${file%.cast}.gif"; done

Why This Runbook: These patterns cover 90% of terminal recording needs. Master these before exploring advanced techniques.

12) The Machine's Summary¶

Terminal recording requires understanding both capture techniques and conversion optimization. When used correctly, terminal recording enables engaging documentation, interactive tutorials, and professional demonstrations. The key is understanding recording tools, mastering conversion workflows, and following quality best practices.

The Dark Truth: Without proper terminal recording understanding, your documentation is static and boring. Terminal recording is your weapon. Use it wisely.

The Machine's Mantra: "In the terminal we trust, in the GIF we share, and in the optimization we find the path to engaging documentation."

Why This Matters: Terminal recording enables efficient documentation creation that can handle complex workflows, maintain visual quality, and provide engaging user experiences while ensuring performance and accessibility.

This tutorial provides the complete machinery for terminal recording and GIF conversion. The patterns scale from simple ASCII capture to complex multi-terminal workflows, from basic conversion to advanced optimization.