scriptcast

Generate terminal demos (asciinema casts & GIFs) from annotated shell scripts.

scriptcast turns a shell script into a reproducible, polished terminal demo — with typing animations, multiple scenes, mocked commands, interactive sessions, output filtering, and more.

Table of Contents

• Background
• Install
• Usage
• Examples
• Script Syntax
• Similar Projects
• Contributing
• License

Background

Terminal demos are hard to reproduce. Screen recordings drift, manual re-runs produce different output, and polishing timing or hiding sensitive paths requires video editing.

scriptcast treats demos as code. You write a shell script annotated with SC directives — controlling scenes, typing speed, mocked commands, interactive expect sessions, and output filters — then run a two-stage pipeline:

1. Record — the script executes with shell tracing enabled; raw output is captured and written to a JSONL .sc file containing timestamped cmd, output, input, and directive events.
2. Generate — the .sc file is read by a streaming renderer that synthesises a polished asciinema .cast file with typing animations and timing.

The .sc file is plain text, version-controllable, and diffable. Re-generating a cast from an existing .sc is instant.

Install

pip install scriptcast

Requires Python 3.10+. For GIF output, install agg.

From source

git clone https://github.com/dacrystal/scriptcast.git
cd scriptcast
pip install -e .

Usage

scriptcast demo.sh          # record → generate → export (PNG by default)
scriptcast demo.sc          # generate → export (skip record)
scriptcast demo.cast        # export only

scriptcast --no-export demo.sh   # record + generate only, no image
scriptcast --format gif demo.sh  # export as GIF (requires agg)
scriptcast install               # install agg binary and fonts

Key flags:

Examples

examples/showcase.sh — a realistic three-scene demo: interactive login, mocked deploy, status check with filter.

examples/tutorial.sh — one scene per directive: mock, expect, filter, comment, sleep, word_speed, record pause/resume.

Themes

Built-in themes: dark (default), aurora, light. Pass --theme <name> or a path to a custom .sh theme file.

--theme dark	--theme aurora	--theme light

Script Syntax

Scripts are valid shell scripts. SC directives are embedded as shell no-ops (: SC ...) so they execute harmlessly but appear in the xtrace output for the recorder to process.

#!/usr/bin/env scriptcast

# Global config — applied before any scene
: SC set type_speed 40
: SC set width 80
: SC set height 24

# ── Scene: intro ──────────────────────────────
: SC scene intro

echo "Hello from scriptcast"

# ── Scene: mock ───────────────────────────────
: SC scene mock

: SC mock deploy <<'EOF'
Deploying to production...
Build: OK
Tests: OK
Deploy: OK
EOF

deploy

# ── Scene: expect ─────────────────────────────
: SC scene expect

: SC expect ./my-app <<'EOF'
expect "Password:"
send "secret\r"
expect "prompt>"
send "quit\r"
expect eof
EOF

# ── Scene: filter ─────────────────────────────
: SC scene filter

: SC filter sed 's#/home/user/projects#<project>#g'

pwd

# ── Scene: comment ────────────────────────────
: SC scene comment

: SC '\' This is a visual comment
echo "comments appear as prompt lines in the cast"

# ── Scene: setup (not recorded) ───────────────
: SC scene setup

: SC record pause
DB_URL="postgres://localhost/mydb"
: SC record resume

echo "Connecting to $DB_URL"

Recorder directives

These are consumed during recording and never appear in the .sc file.

SC expect syntax

The heredoc body is a standard expect script. scriptcast preprocesses it to capture typed input and clean up spawn noise. Inputs sent with send are recorded as input events; silent inputs (e.g. passwords read with read -rs) produce silent animations.

: SC expect ./fake-db <<'EOF'
expect "Password:"
send "secret\r"
expect "mysql>"
send "show databases;\r"
expect eof
EOF

Generator directives

These are stored in the .sc file and interpreted during cast generation.

Config keys (SC set)

When using ANSI escape sequences in prompt, use ANSI-C quoting so the shell interprets the escapes before scriptcast sees them:

: SC set prompt $'\033[92m> \033[0m'

Similar Projects

• VHS — declarative .tape DSL for scripted terminal recordings; outputs GIF, MP4, WebM
• Terminalizer — record a live terminal session and render it as a GIF or HTML player
• asciinema_automation — automate asciinema recordings using pexpect and comment directives
• demo-magic — bash function library for simulated typing in live terminal presentations

What makes scriptcast different:

• Shell-script-native — the demo source is a real, runnable .sh file, not a DSL or config format. Directives are no-op shell comments that execute harmlessly.
• Two-stage pipeline — record and generate are separate. Re-rendering with different timing or themes is instant, no re-recording needed.
• Version-controllable — the .sc file is plain JSONL, diffable and reviewable in git.
• Mocking and expect — SC mock and SC expect let you script slow, side-effectful, or interactive commands without running the real thing.
• Output filters — SC filter pipes captured output through any shell command to scrub paths, tokens, or hostnames before they reach the cast.

Contributing

Issues and pull requests are welcome at github.com/dacrystal/scriptcast.

Before opening a PR, ensure:

• All tests pass: uv run pytest
• New behaviour is covered by tests

License

MIT © dacrystal