/launch-video

name: launch-video
description: Produces Hunk videos by driving the real TUI headlessly in a PTY, compositing captioned 1080p frames in Chromium, and encoding with ffmpeg. Use for feature demos, workflow explainers, announcements, launch videos, and full-release roundups.

Hunk video pipeline

Maintainer-only: requires a hunk source checkout (the pipeline lives in `scripts/launch-video/`, which never ships to npm). Unix-only — the capture scripts exec `/bin/bash`.

Generates product videos where every terminal frame is the real Hunk TUI — no screen recording, no mockups. Three stages:

capture.ts   (bun)               drive Hunk over a PTY, snap styled keyframes to PNG
compose.mjs  (node + Playwright) render each PNG on a 1920x1080 HTML stage in Chromium
ffmpeg                           encode the composited PNGs at 30fps to mp4/webm

Playwright controls headless Chromium: for each planned frame it loads the terminal PNG onto the HTML stage, applies the window chrome, cards, captions, and transition state, then screenshots the completed stage back to PNG. ffmpeg sequences those composited screenshots into the final videos.

The generic machinery (PTY driving, keyframe rendering, storyboard planning, Chromium compositing, the stage template) is the `@hunk/term-video` workspace package in `packages/term-video/`; `scripts/launch-video/` holds only Hunk's scenes, captions, and cards on top of it.

Choosing a recipe

The pipeline is not release-specific. Choose the editorial scope, then use the same capture → composite → encode stages:

• **Single feature:** a short demonstration of one capability or workflow. Use

the single-feature recipe below and capture only the required scene.

• **Full release:** a multi-feature roundup based on a release's changelog or

highlights. Use the full-release recipe and update the canonical storyboard.

• **Custom video:** author any set of scenes and `SHOTS` for tutorials,

comparisons, announcements, or workflow explainers; follow the scene and storyboard rules below.

Creating a video

Expect ~3–6 min for capture and ~2–4 min for compose — run both with a long timeout (or in the background); each logs per-snap / per-shot progress. `compose.mjs` needs node ≥ 18 on PATH (bun alone is not enough).

# 0. dependencies (tuistory + ghostty-opentui are devDependencies)
bun install    # if a postinstall hook fails in a sandbox, retry with --ignore-scripts

# 1. capture keyframes. Output defaults to <repo>/.video-work/ regardless of
#    cwd (pass a path argument to override), but the PROCESS must run from the
#    repo root — see gotchas.
bun run scripts/launch-video/capture.ts

# 2. one-time portable compositor setup. Playwright installs a Chromium build
#    that exactly matches its browser driver (see gotchas to reuse a system or
#    sandbox browser instead).
printf '{"name":"hunk-video-work","private":true}\n' > .video-work/package.json
cd .video-work
bun add playwright playwright-core
bunx playwright install chromium
cd ..

# 3. composite the storyboard
node scripts/launch-video/compose.mjs .video-work

# 4. encode
cd .video-work
ffmpeg -y -f concat -safe 0 -i concat.txt -vf "fps=30,format=yuv420p" \
  -c:v libx264 -preset slow -crf 18 -movflags +faststart launch.mp4
ffmpeg -y -f concat -safe 0 -i concat.txt -vf "fps=30,format=yuv420p" \
  -c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1 launch.webm

Iterate on one scene without re-capturing the rest:

SCENES=review bun run scripts/launch-video/capture.ts   # comma-separated scene names

Scene names are the `wants("...")` guards in `capture.ts`'s `main()`. Note `SCENES=` only narrows _capture_; `compose.mjs` preflights that every frame its `SHOTS` table references exists in `frames/` and fails fast listing any missing ones, so a full composite still needs every scene captured at least once.

Single-feature recipe

For a short test, demo, or one-feature announcement, capture and composite only the scene for that feature:

1. Pick one user-visible capability and find its scene name in the `wants("...")` guards. If it does not have a scene, author one using the guidance below. Capture only that scene:

   SCENES=review bun run scripts/launch-video/capture.ts

2. Make a scratch compositor beside the canonical one so its imports and repo-relative paths continue to work:

   cp scripts/launch-video/compose.mjs scripts/launch-video/compose-one-feature.mjs

3. In the scratch copy, trim `SHOTS` to an opening card, only the selected feature's frames, and an outro card. Rewrite those cards and captions for the scoped cut. Sequence lengths must still match the captured frame names. 4. Composite into the same work directory, then run the normal ffmpeg commands with descriptive output names:

   node scripts/launch-video/compose-one-feature.mjs .video-work
   cd .video-work
   ffmpeg -y -f concat -safe 0 -i concat.txt -vf "fps=30,format=yuv420p" \
     -c:v libx264 -preset slow -crf 18 -movflags +faststart hunk-0.18-line-review.mp4
   ffmpeg -y -f concat -safe 0 -i concat.txt -vf "fps=30,format=yuv420p" \
     -c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1 hunk-0.18-line-review.webm
   cd ..
   rm scripts/launch-video/compose-one-feature.mjs

Keep the scratch compositor uncommitted. The canonical `compose.mjs` remains the checked-in reference storyboard.

Full-release recipe

1. Read the release section in `CHANGELOG.md`. If it has a hand-written **Highlights** list (0.18.0 has one; Changesets does not generate them), use that list as the storyboard. Otherwise distill 4–6 user-visible headlines from the Minor Changes — per-PR entries are too granular to shoot — and confirm the shortlist with the user before capturing. 2. Rewrite the canonical storyboard's editorial surface (next section), adding or adjusting capture scenes as needed (see "Authoring scenes"). 3. Capture every scene referenced by the f