62 lines
2.3 KiB
Markdown
62 lines
2.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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`.
|