# terminal-animator

Adopt this skill: https://proskills.md/skills/other/jr2321-terminal-animator

Page: https://proskills.md/skills/other/jr2321-terminal-animator
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 5411
upstream: https://github.com/jr2321/terminal-animator/blob/HEAD/SKILL.md

````text
# Terminal Animator

Turn terminal screenshots into polished short video animations (15-30s) where commands type themselves and responses appear instantly.

## When to Use

Use this skill when a user asks to:
- Animate a terminal screenshot
- Create a CLI demo video
- Turn a command-line screenshot into a video/animation/GIF
- Make a terminal recording from a screenshot or text

## Requirements

The following must be available in the agent's environment:
- **Node.js** (v18+)
- **ffmpeg** (static binary works; needs libass for subtitle rendering)
- **canvas** npm package (`npm install canvas`)
- A monospace font (DejaVu Sans Mono or similar)

If ffmpeg is not installed, download a static arm64/amd64 binary from https://johnvansickle.com/ffmpeg/

## Workflow

### Step 1: Get the terminal content

If the user sends a **screenshot image**:
1. Use the `image` tool to transcribe every line of text, preserving prompts, commands, output, and special characters
2. Save the transcription to a text file

If the user sends **text** (copy-pasted terminal output):
1. Save directly to a text file

### Step 2: Identify the structure

Parse the content into **command/response blocks**:
- **User input lines**: what the user typed (may have a prompt like `$`, `>`, `❯`, or no prompt at all)
- **Response lines**: system output, including styled lines (arrows, status messages, ASCII art)
- **Special blocks**: ASCII art, logos, status lines that need special treatment

For each line, determine:
- **Style**: input (white), arrow/accent (green `▶` prefixed), normal response (gray), dim/muted, ASCII art (white)
- **Timing**: user inputs get typed character-by-character; responses appear instantly

### Step 3: Identify colors and theme

Sample the screenshot to determine:
- Background color (sample from empty areas)
- Text colors for each element type
- Whether there's window chrome (titlebar with traffic light dots) or plain terminal
- Font size relative to the content density

Common terminal themes:
- **Dark teal/slate**: bg `#292C35`, white input, green accents, gray responses
- **Catppuccin Mocha**: bg `#1e1e2e`, pastel accents
- **Dracula**: bg `#282a36`, purple/green accents

### Step 4: Handle ASCII art / logos

ASCII art with Unicode box-drawing characters (██╗║═╚╝) does NOT render correctly in ASS subtitles because libass doesn't maintain monospace character widths for these glyphs.

**Solution**: Render ASCII art as a PNG image using `node-canvas` (which handles monospace correctly), then overlay it on the video.

Use the script at `scripts/make-art-overlay.mjs`:
```bash
node scripts/make-art-overlay.mjs \
  --text "line1\nline2\nline3" \
  --bg "rgb(39,44,51)" \
  --fg "#FFFFFF" \
  --font-size 32 \
  --output .art-overlay.png
```

The background color MUST exactly match the video background after ffmpeg encoding. To find the exact color:
1. Render a test frame: `ffmpeg -f lavfi -i "color=c=#292C35:s=100x100:d=0.1:r=1" -frames:v 1 test.png`
2. Sample the pixel: `convert test.png -crop 1x1+50+50 -format "%[pixel:u.p{0,0}]" info:`
3. Use that exact RGB value for the art overlay background

### Step 5: Generate the ASS subtitle file

Create an ASS (Advanced SubStation Alpha) subtitle file with:
- Styles for each text type (Input, Arrow, Normal, Dim, Cursor)
- Alignment 7 (top-left) with MarginV for Y positioning
- Timed dialogue events for typing animation and response appearance
- Blinking cursor at the end

Key ASS settings:
- `PlayResX`/`PlayResY` must match the video dimensions
- Colors are in `&HBBGGRR&` format (BGR, not RGB!)
- Font: DejaVu Sans Mono (available on most Linux systems)

### Step 6: Render with ffmpeg

```bash
ffmpeg -y \
  -f lavfi -i "color=c=#292C35:s=960x920:d=6.0:r=30" \
  -filter_complex "[0:v]ass=demo.ass[bg];movie=.art-overlay.png[art];[bg][art]overlay=x=18:y=520:enable='gte(t,3.0)'" \
  -c:v libx264 -preset fast -crf 18 -pix_fmt yuv420p \
  output.mp4
```

If there's no ASCII art overlay, simplify to:
```bash
ffmpeg -y \
  -f lavfi -i "color=c=#292C35:s=960x920:d=6.0:r=30" \
  -vf "ass=demo.ass" \
  -c:v libx264 -preset fast -crf 18 -pix_fmt yuv420p \
  output.mp4
```

### Step 7: Review and iterate

Extract a frame to verify: `ffmpeg -i output.mp4 -ss 4.0 -frames:v 1 check.png`

Use the `image` tool to verify:
- All text is visible and not cut off
- Colors match the original screenshot
- ASCII art is properly aligned
- Background colors blend seamlessly (no visible rectangles)

Send the video to the user. Iterate on timing, colors, and content based on feedback.

## Timing Guidelines

| Element | Default | Range |
|---------|---------|-------|
| Typing speed | 35ms/char | 25-80ms |
| Response delay | 150ms | 100-300ms |
| Response line delay | 30ms | 20-50ms |
| Pause between commands | 500ms | 300-1000ms |
| Initial delay | 400ms | 200-600ms |
| Final pause | 2500ms | 1500-3000ms |

Target total duration: 15-30 seconds for social media clips.

## Output Formats

- **MP4**: Best for Twitter/LinkedIn/Telegram. Use `-c:v libx264 -crf 18`
- **GIF**: For README/docs. Use `ffmpeg ... -vf "fps=15,scale=480:-1" output.gif`
- **WebM**: For web embedding. Use `-c:v libvpx-vp9 -crf 30`

## Reference Files

- `references/ass-format.md` - ASS subtitle format reference
- `scripts/make-art-overlay.mjs` - Generate ASCII art PNG overlays
- `scripts/setup-deps.sh` - Install ffmpeg + ttyd + canvas
````

## File: README.md
upstream: https://github.com/jr2321/terminal-animator/blob/HEAD/README.md

````text
# 🎬 Terminal Animator

An OpenClaw skill that turns terminal screenshots into polished short video animations. Commands type themselves, responses appear instantly, ASCII art renders pixel-perfect.

## What it does

Send your OpenClaw agent a terminal screenshot and ask it to "animate this" or "turn this into a video." The agent will:

1. **OCR** the screenshot to extract terminal text
2. **Parse** into command/response blocks
3. **Generate** a timed subtitle file (ASS) with typing animations
4. **Render** ASCII art as pixel-perfect PNG overlays (bypasses subtitle font issues)
5. **Produce** an MP4/GIF video with ffmpeg

The result is a clean 15-30 second clip where commands type character-by-character and responses appear instantly, perfect for demos, social media, or documentation.

## Install

### As an OpenClaw Skill

```bash
# Copy to your OpenClaw skills directory
cp -r terminal-animator-skill ~/.openclaw/skills/terminal-animator

# Install Node.js dependencies
cd ~/.openclaw/skills/terminal-animator
bash scripts/setup-deps.sh
```

### Manual Dependencies

- Node.js 18+
- ffmpeg (with libass support for subtitles)
- `canvas` npm package: `npm install canvas`
- DejaVu Sans Mono font (most Linux distros have it)

## Usage

### With OpenClaw

Send your agent a terminal screenshot:

> "Animate this terminal screenshot into a short demo video"

Or paste terminal text:

> "Turn this into an animation:
> ```
> $ curl api.example.com/status
> {"status": "ok", "uptime": "99.99%"}
> $ echo "done"
> done
> ```"

### Standalone (Art Overlay Tool)

Generate a pixel-perfect ASCII art PNG for use in videos:

```bash
node scripts/make-art-overlay.mjs \
  --file my-ascii-art.txt \
  --bg "rgb(39,44,51)" \
  --fg "#FFFFFF" \
  --font-size 32 \
  --output art.png
```

## How it works

### Why not just use VHS/asciinema?

[VHS](https://github.com/charmbracelet/vhs) is great when you can script commands. But when you're starting from a **screenshot** of an existing terminal session, you need a different pipeline:

1. **Extract** text from the image
2. **Reconstruct** the command/response structure
3. **Re-render** with controlled timing

### The ASCII art problem

Unicode box-drawing characters (██╗║═╚╝) used in figlet/toilet-style logos don't render correctly in ASS subtitles because libass doesn't maintain consistent monospace character widths for these glyphs. The letters come out garbled.

**Solution**: Render ASCII art blocks separately using `node-canvas` (which handles monospace correctly), then overlay the resulting PNG on the video with ffmpeg's `overlay` filter. The background color is matched exactly to eliminate visible seams.

### Architecture

```
Screenshot/Text
      ↓
  Parse into command/response blocks
      ↓
  Generate ASS subtitle file (typing animations + response timing)
      ↓
  Generate ASCII art PNG overlays (node-canvas)
      ↓
  Render with ffmpeg (color background + ASS + PNG overlay)
      ↓
  MP4/GIF output
```

## Configuration

### Timing

| Parameter | Default | Description |
|-----------|---------|-------------|
| Typing speed | 35ms/char | How fast commands type |
| Response delay | 150ms | Pause before response appears |
| Line delay | 30ms | Stagger between response lines |
| Command pause | 500ms | Gap between command blocks |
| Initial delay | 400ms | Pause before first command |
| Final pause | 2500ms | Hold on last frame |

### Colors

Colors are set per-project to match the source terminal theme. Common setups:

| Element | Dark terminal | Catppuccin Mocha |
|---------|--------------|-----------------|
| Background | `#292C35` | `#1E1E2E` |
| User input | `#FFFFFF` | `#CDD6F4` |
| Accents (▶) | `#7CD9A6` | `#A6E3A1` |
| Response text | `#8A9BA8` | `#BAC2DE` |
| Muted text | `#5A6A72` | `#6C7086` |

### Output

- **MP4** (default): `-c:v libx264 -crf 18` for Twitter/LinkedIn/Telegram
- **GIF**: `ffmpeg -vf "fps=15,scale=480:-1" output.gif` for READMEs
- **WebM**: `-c:v libvpx-vp9 -crf 30` for web

## File Structure

```
terminal-animator-skill/
├── SKILL.md                          # OpenClaw skill instructions
├── README.md                         # This file
├── scripts/
│   ├── make-art-overlay.mjs          # ASCII art → PNG renderer
│   └── setup-deps.sh                 # Dependency installer
└── references/
    └── ass-format.md                 # ASS subtitle format reference
```

## Credits

Built by [OpenClaw](https://github.com/openclaw/openclaw) agents. Uses [ffmpeg](https://ffmpeg.org/), [node-canvas](https://github.com/Automattic/node-canvas), and [libass](https://github.com/libass/libass).

## License

MIT
````
