vhs-demo

分类: 运维与交付 | 上传者: babarot | 下载: 0 | 版本: v1.0（最新）

在运行演示录制、诊断录制失败或从现有 MP4 重新生成 GIF 时使用。涵盖了 Docker + VHS + ffmpeg 管道。 --- # VHS 演示录制使用此技能来运行、调试或重新生成 gh-infra 演示 GIF 录制。 ## 何时使用 - 直接运行 `make demo` 或 `docs/tapes/vhs.sh` - 诊断录制失败或生成 0 字节 GIF 的原因 - 从现有 MP4 重新生成 GIF，无需重新录制 - 了解录制管道 ## 先决条件 - Docker 必须运行 - Go 工具链（用于交叉编译 Linux 二进制文件） ## 管道 ```text make demo 1. go build -o docs/tapes/.gh-infra (GOOS=linux GOARCH=amd64) 2. docs/tapes/vhs.sh docker 构建 → gh-infra-vhs 映像 (VHS + vim)对于并行的每个 *.tape： docker run --memory=1g --cpus=2 → 生成 .mp4 c．对于每个 .mp4 按顺序： docker run jrottenberg/ffmpeg:7-alpine → 生成 .gif 3. 将 GIF 复制到 docs/public/ 4. 清理 .gh-infra 二进制文件 ``` ## 为什么 MP4 → GIF 而不是直接 GIF 当多个容器在 macOS 上并行运行时，VHS 的内置 GIF 输出不可靠。解决方法是仅从 VHS 输出 MP4，然后通过 ffmpeg 使用高质量设置（lanczos 缩放、sierra2_4a 抖动、256 色）转换为 GIF。 ## 关键文件 |文件|角色 | |------|------| | `docs/tapes/vhs.sh` | Orchestrator：并行录制+顺序GIF转换| | `文档/磁带/Dockerfile` | `ghcr.io/charmbracelet/vhs` + vim | | `docs/tapes/*.tape` | VHS 场景文件 | | `docs/tapes/setup*.sh` |每个演示设置脚本（模拟数据、gh 包装器）| | `文档/磁带/mock-gh` | `gh` CLI 的通用模拟 | | `docs/tapes/.gh-infra` |交叉编译的 Linux 二进制文件（临时）| ## 输出位置 - 原始录音：`docs/tapes/*.mp4` 和 `docs/tapes/*.gif` - 已发布资源：`docs/public/demo*.gif`（由 Makefile 复制） ## 环境变量 `make demo` 通过 `-e` 标志将 `DEMO_ENV` 变量转发到 Docker。使用它来将环境覆盖（例如`GH_INFRA_OUTPUT`）传递到

更新日志: Source: GitHub https://github.com/babarot/gh-infra

目录结构

当前层级: tree/main/.claude/skills/vhs-demo/

📄 SKILL.md 4.7 KB

SKILL.md

---
name: vhs-demo
description: >
  Use when running demo recordings, diagnosing recording failures,
  or regenerating GIFs from existing MP4s. Covers the Docker + VHS + ffmpeg pipeline.
---

# VHS Demo Recording

Use this skill to run, debug, or regenerate gh-infra demo GIF recordings.

## When To Use

- Running `make demo` or `docs/tapes/vhs.sh` directly
- Diagnosing why a recording failed or produced a 0-byte GIF
- Regenerating GIFs from existing MP4s without re-recording
- Understanding the recording pipeline

## Prerequisites

- Docker must be running
- Go toolchain (for cross-compiling the Linux binary)

## Pipeline

```text
make demo
  1. go build -o docs/tapes/.gh-infra  (GOOS=linux GOARCH=amd64)
  2. docs/tapes/vhs.sh
     a. docker build → gh-infra-vhs image (VHS + vim)
     b. For each *.tape in parallel:
        docker run --memory=1g --cpus=2 → produces .mp4
     c. For each .mp4 sequentially:
        docker run jrottenberg/ffmpeg:7-alpine → produces .gif
  3. Copy GIFs to docs/public/
  4. Clean up .gh-infra binary
```

## Why MP4 → GIF Instead of Direct GIF

VHS's built-in GIF output is unreliable when multiple containers run in parallel on macOS. The workaround is to output MP4 only from VHS, then convert to GIF via ffmpeg with high-quality settings (lanczos scaling, sierra2_4a dithering, 256 colors).

## Key Files

| File | Role |
|------|------|
| `docs/tapes/vhs.sh` | Orchestrator: parallel recording + sequential GIF conversion |
| `docs/tapes/Dockerfile` | `ghcr.io/charmbracelet/vhs` + vim |
| `docs/tapes/*.tape` | VHS scenario files |
| `docs/tapes/setup*.sh` | Per-demo setup scripts (mock data, gh wrapper) |
| `docs/tapes/mock-gh` | Generic mock for `gh` CLI |
| `docs/tapes/.gh-infra` | Cross-compiled Linux binary (ephemeral) |

## Output Locations

- Raw recordings: `docs/tapes/*.mp4` and `docs/tapes/*.gif`
- Published assets: `docs/public/demo*.gif` (copied by Makefile)

## Environment Variables

`make demo` forwards `DEMO_ENV` variables into Docker via `-e` flags. Use this to pass environment overrides (e.g. `GH_INFRA_OUTPUT`) into the recording containers.

## Resource Planning

All tapes run in parallel. Each container requests `--memory` and `--cpus` (see `vhs.sh`). The total resource demand is:

```
total memory = number_of_tapes × per-container memory
total CPUs   = number_of_tapes × per-container CPUs
```

For example, 6 tapes × `--memory=2g --cpus=2` = 12 GB / 12 CPUs.

**This is constrained by Docker Desktop's resource allocation, not host RAM.** Docker Desktop defaults are often low (e.g. 7.6 GB on a 24 GB machine). If total demand exceeds Docker Desktop's allocation, containers will OOM or produce 0-byte outputs.

### When Adding New Tapes

Adding a tape increases parallel resource demand. Before adding, check:

1. Count existing tapes: `ls docs/tapes/*.tape | wc -l`
2. Calculate total: `count × per-container memory`
3. Compare against Docker Desktop memory allocation

If the total exceeds Docker Desktop's limit, you have two options:

- **Increase Docker Desktop memory** — Open Docker Desktop → Settings → Resources → Memory. On an M-series Mac with 24+ GB RAM, allocating 16 GB is safe and is the recommended approach since it's a one-time setting.
- **Reduce per-container resources** — Lower `--memory` in `vhs.sh`. This is a last resort since it may cause recording failures for complex tapes.

### Recommended Docker Desktop Settings

For comfortable parallel recording of 6+ tapes:

| Setting | Recommended |
|---------|-------------|
| Memory | 16 GB (minimum: number_of_tapes × 2 GB) |
| CPUs | 8+ |

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| 0-byte GIF | MP4 was also 0-byte or missing | Check the tape's setup script and mock data |
| 0-byte MP4 | VHS crashed or setup script failed | Run the single tape manually: `docker run --rm -v docs/tapes:/data -w /data gh-infra-vhs <name>.tape` |
| `gh-infra: not found` in recording | Binary not copied or wrong arch | Verify `GOOS=linux GOARCH=amd64 go build` succeeded |
| Docker OOM | Container hit memory limit | Check Docker Desktop memory allocation (see Resource Planning above) |
| Multiple tapes fail simultaneously | Docker Desktop memory too low for parallel count | Increase Docker Desktop memory or reduce tape count |
| "Docker is not running" | Docker daemon not started | Start Docker Desktop or `dockerd` |

## Regenerating GIFs Only

To re-convert existing MP4s without re-recording, run the ffmpeg step manually:

```bash
docker run --rm -v docs/tapes:/data -w /data jrottenberg/ffmpeg:7-alpine \
  -y -i <name>.mp4 \
  -vf "fps=10,scale=1200:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=256[p];[s1][p]paletteuse=dither=sierra2_4a" \
  <name>.gif
```

登录后下载/点赞/收藏 ❤ 102 | ★ 0

vhs-demo

目录结构

SKILL.md

举报内容

提示