GitHub - tool3/dvd-cli

Create animated SVG terminal recordings from simple scripts

DVD lets you create animated SVG terminal recordings from declarative .cd scripts. Write what you want to happen, run dvd, and get a beautiful, infinitely-scalable animation.

No ffmpeg. No browser. No dependencies. Just SVG.

Installation

npm install -g dvdr

Or use directly with npx:

npx dvdr demo.cd

Quick Start

Create a new script:

dvd new demo

Edit demo.cd:

Output demo.svg

Set Template macos
Set Theme dracula
Set Title "My Terminal"

Type "echo 'Hello World!'"
Sleep 500ms
Enter
Sleep 1s

Render it:

dvd demo.cd

Your animated SVG works in GitHub READMEs, documentation sites, blogs - anywhere that supports images:

![Demo](demo.svg)

Pipe Mode

Capture any command output directly:

# Capture a command's output
ls -la --color | dvd -o listing.svg

# Pipe animated output
lolcat -a -d 2 <<< "Hello World" | dvd -o rainbow.svg

# Capture neofetch
neofetch | dvd -o system-info.svg --title "System Info"

# simple chartscii chart with gradient and animation - dvd reverses and pauses between cycles
chartscii $(seq 1 5) -c "gradient(pink,cyan)" --animate | dvd -L reverse -P 1000 -w "made with dvd"

Syntax

DVD scripts use a simple declarative syntax. Lines starting with # are comments.

Commands

Type

Type text with realistic timing. Control speed with @<ms>ms suffix.

Type "echo 'Hello World'"
Type@100ms "Slow typing..."
Type@10ms "Speed typing!"

Enter

Execute the current command.

Type "neofetch"
Enter

Sleep

Pause the recording.

Sleep 500ms
Sleep 2s

Backspace

Delete characters. Supports a count parameter.

Type "Hello Wrold"
Backspace 4
Type "orld!"

Arrow Keys

Navigate with arrow keys. Supports a count parameter.

Left          # Move cursor left
Right         # Move cursor right
Left 5        # Move cursor left 5 times
Right 10      # Move cursor right 10 times

Keyboard Shortcuts

Full keyboard navigation with selection support.

Shift+Left           # Select character left
Shift+Right          # Select character right
Alt+Left             # Move word left
Alt+Right            # Move word right
Alt+Shift+Left       # Select word left
Alt+Shift+Right      # Select word right
Cmd+Left             # Move to line start
Cmd+Right            # Move to line end
Cmd+Backspace        # Delete word

Screenshot

Capture a static frame at any point.

Type "npm test"
Enter
Screenshot test-results.svg

Settings

All settings use the Set command: Set <Setting> <value>

Output

Output demo.svg
Output path/to/output.svg

Theme

Set Theme dracula

See the full Themes gallery below.

Template

Window chrome style.

Set Template macos     # macOS traffic lights
Set Template windows   # Windows-style buttons
Set Template minimal   # No window decorations

See Templates section for examples.

Title

Set Title "My Terminal"

Dimensions

Omit for auto-sizing based on content.

Set Width 800
Set Height 600

Font

# System font (viewer must have it installed)
Set FontFamily "Fira Code"
Set FontSize 14
Set LineHeight 1.4

# Embedded font (guaranteed to render correctly)
Set EmbedFont path/to/font.woff2

Cursor

Set CursorStyle block      # block, bar, underline
Set CursorColor #ffffff
Set CursorBlink true

Typing Speed

Default milliseconds per character.

Set TypingSpeed 50

Prompt

Supports ANSI escape codes for colors.

Set PromptPrefix "$ "
Set PromptPrefix "❯ "
Set PromptPrefix "\x1b[95m❯\x1b[0m "    # Colored prompt

Border

Set BorderRadius 8
Set BorderWidth 2
Set BorderColor #ff0000

Padding

Set Padding 16

Header & Footer

Set HeaderHeight 40
Set HeaderBackground #333333
Set HeaderBorder true
Set HeaderBorderColor #444444
Set HeaderBorderWidth 1

Set FooterHeight 30
Set FooterBackground #333333
Set FooterBorder true

Watermark

Set Watermark "Made with DVD"
Set WatermarkStyle "opacity: 0.5; padding: 10"

For SVG markup watermarks (e.g., clickable links):

Set Watermark `<a href="https://github.com/tool3/dvd">
  <text text-anchor="end">DVD</text>
</a>`

Shell

Set the shell for executing commands.

Set Shell /bin/zsh
Set Shell /bin/bash

Working Directory

Set the working directory for command execution.

Set WorkingDirectory $PWD           # Use current directory
Set WorkingDirectory /path/to/dir   # Use absolute path

Background & Gradient

Add a colored or gradient background around your terminal window.

# Solid color background
Set Background #1a1a2e
Set BackgroundPadding 40

# Vertical background (default)
Set Background gradient(#667eea, #764ba2)
Set BackgroundPadding 40

# Diagonal gradient (diagonal reversed)
Set Background gradient(#667eea, #764ba2)
Set BackgroundPadding 40

# Horizontal gradient
Set Background gradient(#f093fb, #f5576c:horizontal)
Set BackgroundPadding 40

# Multi-color gradient
Set Background gradient(#ff6b6b, #feca57, #48dbfb, #ff9ff3)
Set BackgroundPadding 60

Playback Speed

Control animation playback speed.

Set PlaybackSpeed 2      # 2x faster
Set PlaybackSpeed 0.5    # Half speed

Themes

37 built-in themes.

Set Theme <theme-name>

a11yDark	base16Dark	base16Light
blackboard	catppuccinMocha	cobalt
dark	dracula	draculaPro
duotoneDark	githubDark	githubLight
gruvboxDark	gruvboxLight	hopscotch
lucario	material	monokai
night3024	nord	oceanicNext
oneDark	oneLight	pandaSyntax
paraisoDark	seti	shadesOfPurple
solarizedDark	solarizedLight	synthwave84
terminal	tokyoNight	twilight
verminal	vscode	yeti
zenburn

Custom Themes

Create your own theme with a JSON object. Only specify the colors you want to override - unspecified colors inherit from the current theme.

# Full custom theme
Set Theme {"background": "#1a1a2e", "foreground": "#eaeaea", "cursor": "#f39c12", "red": "#e74c3c", "green": "#2ecc71", "blue": "#3498db"}

# Partial theme - just change background and foreground
Set Theme {"background": "#0d1117", "foreground": "#c9d1d9"}

# Retro green terminal
Set Theme {"background": "#0a0a0a", "foreground": "#00ff00", "cursor": "#00ff00"}

Available theme properties:

Property	Description
`name`	Theme name (optional)
`background`	Terminal background color
`foreground`	Default text color
`cursor`	Cursor color
`selection`	Selection highlight color
`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`	Standard ANSI colors
`brightBlack`, `brightRed`, `brightGreen`, `brightYellow`, `brightBlue`, `brightMagenta`, `brightCyan`, `brightWhite`	Bright ANSI colors

Templates

Window chrome styles for your terminal.

Set Template <template-name>

macos macOS traffic lights	windows Windows-style buttons	minimal No window decorations

Loop Styles

Control how animations behave when they reach the end.

Default Loop

Animation restarts from the beginning.

Set LoopStyle loop

Reverse

Animation plays forward, then backward at the same speed.

Set LoopStyle reverse

Rewind

Fast reverse playback - like rewinding a tape.

Set LoopStyle rewind
Set RewindSpeed 10       # Speed multiplier (default: 5)

Fade

Fade to black before restarting.

Set LoopStyle fade
Set FadeDuration 1500    # Fade duration in ms (default: 1500)

Loop Pause

Add a pause between animation cycles.

Set LoopPause 2000       # Pause 2 seconds before restarting

Animation Engines

DVD ships with two animation engines. Filmstrip is the default and is the right choice for most recordings — SMIL is an opt-in alternative when you specifically need smoother playback on high-refresh-rate mobile displays.

Filmstrip (default)

Each unique row in the recording is emitted once as an SVG <symbol> and referenced from every frame that uses it via <use>. Frame cadence is driven by CSS @keyframes with step-end visibility switching.

Smaller files. Size scales with the number of unique rows, not frames. Repetitive output (prompts, ASCII art, mostly-static screens) compresses dramatically.
Great on desktop and modern browsers. The CSS animation path is well-optimized where it matters for README/docs use.
Can stutter at 120Hz on mobile Safari. Each frame switch goes through the browser's CSS style-resolution pipeline, which adds per-tick overhead on some devices.

No flag needed — this is what runs by default.

dvd script.cd

SMIL

Each frame is emitted as its own <g> group, and visibility is switched by a native SVG <animate attributeName="visibility"> tag. The SVG engine pre-computes the schedule and only paints the active frame.

Smoother on 120Hz / mobile Safari / iOS Chrome. The native SVG animation path skips CSS style resolution entirely, so frame switches are cheaper per tick.
Larger files. Size scales with total frame count rather than unique rows. Expect typically 2–4× the filmstrip output, more for long/highly-varied recordings.
SMIL is less actively maintained in browser specs than CSS animations, so this engine is a targeted tool rather than a future-proof default.

Enable with the --smil flag:

dvd script.cd --smil

Which one should I use?

You want…	Use
A README/docs embed on desktop	Filmstrip
The smallest possible file	Filmstrip
Buttery-smooth playback on iOS / 120Hz screens	SMIL
Long recordings with lots of repeated prompt lines	Filmstrip
Short, high-FPS animations where smoothness matters	SMIL

CLI Reference

Basic Usage

dvd script.cd                          # Render to script.svg
dvd script.cd -o output.svg            # Custom output path
dvd script.cd --verbose                # Show detailed output

Loop Options

dvd script.cd --loop-style reverse     # Reverse animation
dvd script.cd --loop-style rewind      # Fast rewind
dvd script.cd --loop-style fade        # Fade to black
dvd script.cd --rewind-speed 10        # Rewind speed multiplier
dvd script.cd --fade-duration 2000     # Fade duration (ms)
dvd script.cd --loop-pause 1500        # Pause between loops (ms)
dvd script.cd --no-loop                # Play once, don't loop
dvd script.cd --pause-at-end 2000      # Pause at end before looping

Styling Options

dvd script.cd --theme dracula
dvd script.cd --template macos
dvd script.cd --title "My Demo"
dvd script.cd --font-size 16
dvd script.cd --cursor-style bar
dvd script.cd --width 800 --height 600

Pipe Mode

command | dvd -o output.svg
ls -la | dvd -o listing.svg --theme nord

Utilities

dvd new my-demo                        # Create new script
dvd new my-demo --template showcase    # Use template
dvd themes                             # List themes
dvd validate script.cd                 # Validate without rendering

All Options

Option	Alias	Description	Default
`--output`	`-o`	Output file path	`<input>.svg`
`--verbose`	`-v`	Show detailed output	`false`
`--optimize`	`-O`	Optimize SVG output	`true`
`--smil`		Use SMIL engine (see Animation Engines)	`false`
`--loop`	`-l`	Loop the animation	`true`
`--loop-style`	`-L`	`loop`, `reverse`, `rewind`, `fade`	`loop`
`--loop-pause`	`-P`	Pause before loop restarts (ms)	`0`
`--pause-at-end`	`-p`	Pause at end before looping (ms)	`1000`
`--fade-duration`	`-F`	Fade duration for fade style (ms)	`1500`
`--rewind-speed`	`-r`	Speed multiplier for rewind	`5`
`--fps`	`-f`	Frames per second
`--playback-speed`	`-S`	Animation playback speed multiplier	`1`
`--theme`	`-T`	Color theme	`dark`
`--template`	`-m`	`macos`, `windows`, `minimal`	`macos`
`--title`	`-t`	Window title
`--width`	`-W`	Width in pixels	auto
`--height`	`-H`	Height in pixels	auto
`--font-size`	`-s`	Font size in pixels	`14`
`--font-family`	`-y`	Font family name
`--line-height`	`-Y`	Line height multiplier	`1.4`
`--letter-spacing`	`-a`	Letter spacing in pixels	`0`
`--padding`	`-d`	Content padding (px)	`16`
`--border-radius`	`-R`	Border radius (px)	`8`
`--border-color`	`-C`	Border color (hex)
`--border-width`	`-B`	Border width (px)
`--background`	`-A`	Outer background color or gradient
`--background-padding`	`-n`	Padding around terminal window (px)	`0`
`--cursor-style`	`-c`	`block`, `bar`, `underline`	`block`
`--cursor-color`	`-k`	Cursor color (hex)
`--cursor-blink`	`-K`	Enable cursor blink	`true`
`--header-background`	`-b`	Header background color (hex)
`--header-height`	`-e`	Header height in pixels
`--header-border`	`-D`	Show header border
`--header-border-color`	`-E`	Header border color (hex)
`--header-border-width`	`-G`	Header border width (px)
`--footer-background`	`-g`	Footer background color (hex)
`--footer-height`	`-i`	Footer height in pixels
`--footer-border`	`-I`	Show footer border
`--footer-border-color`	`-J`	Footer border color (hex)
`--footer-border-width`	`-j`	Footer border width (px)
`--watermark`	`-w`	Watermark text

Examples

Hello World

Output demo.svg

Set Template minimal
Set FontSize 46

Type "echo 'Hello world'"
Sleep 500ms
Enter
Type "Welcome to DVD!"
Sleep 1s

ANSI Colors

Full 256-color and truecolor support.

ASCII Art with Figlet

Charts with Chartscii

Rainbow Animation

Animated command output is captured frame-by-frame.

Git Log

System Info

Text Selection

Word Navigation

Color Tables

Directory Listing

See the examples/ directory for all scripts and outputs.

Why DVD?

	DVD	VHS	asciinema
Output	SVG	GIF/MP4	asciicast
Dependencies	None	ffmpeg, ttyd	Player embed
Scalable	Yes	No	Yes
GitHub README	Perfect	Works	Embed only
Editable	Yes (XML)	No	Yes (JSON)
Offline	Yes	Yes	No
Print quality	Yes	No	No
Loop styles	4 modes	Basic	Basic

Related Projects

VHS - GIF/MP4 terminal recordings
shellfie - Terminal screenshots in code
shellfie-cli - Terminal screenshots CLI
shellfied - Terminal screenshots web service

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 189 Commits
.github/workflows		.github/workflows
examples		examples
scripts		scripts
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
FORMAT.md		FORMAT.md
README.md		README.md
ansi.svg		ansi.svg
demo.cd		demo.cd
demo.gif		demo.gif
demo.tape		demo.tape
package-lock.json		package-lock.json
package.json		package.json
test.cast		test.cast
tsconfig.json		tsconfig.json
v3.cast		v3.cast
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Contents

Installation

Quick Start

Pipe Mode

Syntax

Commands

Type

Enter

Sleep

Backspace

Arrow Keys

Keyboard Shortcuts

Screenshot

Settings

Output

Theme

Template

Title

Dimensions

Font

Cursor

Typing Speed

Prompt

Border

Padding

Header & Footer

Watermark

Shell

Working Directory

Background & Gradient

Playback Speed

Themes

Custom Themes

Templates

Loop Styles

Default Loop

Reverse

Rewind

Fade

Loop Pause

Animation Engines

Filmstrip (default)

SMIL

Which one should I use?

CLI Reference

Basic Usage

Loop Options

Styling Options

Pipe Mode

Utilities

All Options

Examples

Hello World

ANSI Colors

ASCII Art with Figlet

Charts with Chartscii

Rainbow Animation

Git Log

System Info

Text Selection

Word Navigation

Color Tables

Directory Listing

Why DVD?

Related Projects

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Packages