2.3 KiB
Tier: Screenshot Reel
Render styled terminal frames from text and stitch into an animated GIF. Each frame shows one step of a CLI demo (command + output).
Best for: CLI tools shown as discrete steps (command -> output -> next command -> output). Also useful when VHS breaks on quoting or special characters. Output: GIF (silicon PNGs stitched via ffmpeg) Label: "Demo" Required tools: silicon, ffmpeg
Step 1: Write Demo Content
Create a text file with --- delimiters between frames. Each frame shows the terminal state for one step:
Write to [RUN_DIR]/demo-steps.txt:
$ your-cli-command --flag value
Output line 1
Output line 2
Success: feature works correctly
---
$ your-cli-command --another-flag
Different output showing another aspect
Result: 42 items processed
---
$ your-cli-command --verify
All checks passed
Tips:
- Include the
$prompt to show what the user types - Keep each frame under ~80 characters wide for readability
- 3-5 frames is ideal -- enough to tell the story, not so many the GIF is huge
- Strip unicode characters that silicon's default font can't render (checkmarks, fancy arrows)
Step 2: Split into Frame Files
Split the demo content on --- lines into separate text files, one per frame:
[RUN_DIR]/frame-001.txt[RUN_DIR]/frame-002.txt[RUN_DIR]/frame-003.txt- etc.
Step 3: Render and Stitch
Use the capture pipeline script to render each text frame through silicon and stitch into an animated GIF in a single call:
python3 scripts/capture-demo.py screenshot-reel --output [RUN_DIR]/demo.gif --duration 2.5 --text [RUN_DIR]/frame-001.txt [RUN_DIR]/frame-002.txt [RUN_DIR]/frame-003.txt
The script handles silicon rendering, dimension normalization, two-pass palette generation, and automatic frame reduction if the GIF exceeds limits. Default duration is 2.5 seconds per frame (faster than browser reels since terminal frames are quicker to read).
If the script fails (silicon rendering error, stitching error, empty output): fall back to static screenshots tier. Include the raw terminal output as a code block in the PR description instead. Label as "Terminal output", not "Screenshots".
Step 4: Cleanup
Remove individual PNGs and text files. Keep only the final GIF for upload.
Proceed to references/upload-and-approval.md.