Hunk video pipeline
Source-checkout only: the pipeline lives in scripts/launch-video/, which never ships to npm.
It can be used for pull-request demos as well as maintainer release videos. 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 is a devDependency; ghostty-opentui arrives transitively)
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:
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
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
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.
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-feature-demo.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-feature-demo.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. If you added a capture scene only to make
PR evidence, revert that scene after encoding; retain it only when it is useful
checked-in demo coverage and belongs to the submitted change.
Full-release recipe
- 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.
- Rewrite the canonical storyboard's editorial surface (next section), adding
or adjusting capture scenes as needed (see "Authoring scenes").
- Capture every scene referenced by the full storyboard, composite it, and
encode both formats using the main workflow above.
- Verify the complete cut (see "Verification") and deliver both files. When
hunk-release invoked this workflow, return the approved MP4 and WebM to that skill for versioned naming and GitHub user-attachment embedding; do not upload or edit the public release without its confirmation gate.
Per-video editorial surface
The capture machinery is reusable, but the storyboard is editorial content for
one video. Rewrite it to match the video's scope. As of this writing, the
checked-in reference storyboard is the full 0.18.0 release video:
compose.mjs: the whole SHOTS table; OPEN_CARD (version badge);
OUTRO_CARD (headline, install commands, footer); EXTENSIONS_CARD; every
<span class="badge">NEW</span> in captions — a NEW badge is a claim about
this release, so drop or move them as features age.
capture.ts: the scene functions and the wants() guards in main() are
the current storyboard's scene list, plus hunk-side glue (launchHunk,
launchHunkShell, createDemoRepo, the keyboard probe).
Reusable machinery lives in @hunk/term-video (packages/term-video/) —
extend it there, don't fork it into the scripts: createKeyframer,
launchApp/launchShell, createCommandWrapper, typeCommand,
ensureKeyboardIsLive, makeSceneFilter (src/capture.ts); the unit-tested
storyboard planner with the caption/timing semantics (src/plan.mjs);
composeStoryboard with font/Chromium resolution and the missing-keyframe
preflight (src/compose.mjs); and the stage template (src/stage.html).
Environment gotchas
Sandbox-specific bullets are marked; each cost real debugging time.
Run capture.ts with bun from the repo root. tuistory uses subpath
self-imports (tuistory/pty) that only resolve inside this repo's
node_modules; running the script from elsewhere resolves tuistory from
bun's global cache and crashes. (Output location is unaffected — it defaults
to <repo>/.video-work/ via import.meta.url.)
ghostty-opentui is a transitive dep (via tuistory) with an exports map:
import "ghostty-opentui/image" (not .../dist/image.js), resolved
relative to tuistory — @hunk/term-video/capture's createKeyframer does
the Bun.resolveSync dance.
Playwright must match the Chromium it drives. The portable setup above
installs playwright and playwright-core together, then downloads their
matching Chromium build. It works on macOS and Linux and is preferred when
bandwidth and browser downloads are available; leave CHROMIUM_PATH unset
so Playwright uses that managed browser. On Linux, if Chromium reports
missing system libraries, run bunx playwright install-deps chromium (it
may require sudo) before retrying.
To reuse an existing system, CI, or sandbox Chromium instead, install the
playwright-core version provided by that environment and set its executable
explicitly:
cd .video-work
bun add playwright-core@<matching-version>
cd ..
CHROMIUM_PATH=/path/to/chromium node scripts/launch-video/compose.mjs .video-work
Common executable locations include $(command -v chromium) or
$(command -v google-chrome) on Linux and
/Applications/Google Chrome.app/Contents/MacOS/Google Chrome on macOS.
In an environment with a preinstalled Playwright toolchain, read that
toolchain's package.json to get the exact driver version. For example, the
Anthropic sandbox exposes it through /opt/pw-browsers/.links/*:
cat "$(cat /opt/pw-browsers/.links/* | head -1)/package.json" | grep '"version"'
# e.g. "1.56.1" -> bun add playwright-core@1.56.1
compose.mjs picks its browser as $CHROMIUM_PATH, then
/opt/pw-browsers/chromium when present, then Playwright's managed browser.
Give .video-work/ its own package.json before bun add. Without
one, bun walks up and installs into the repo's package.json — revert with
git checkout package.json bun.lock if that happens.
Chromium needs --allow-file-access-from-files (already in
compose.mjs): the stage samples each keyframe through a canvas to
color-match the window background, and file:// images taint the canvas
without it.
mp4 needs an ffmpeg with libx264. Sandbox: apt-get install ffmpeg
(run apt-get update first if packages 404). macOS: brew install ffmpeg.
Verify ffmpeg -encoders | grep -E 'libx264|libvpx-vp9' shows both before
encoding — playwright's bundled ffmpeg-*/ffmpeg-linux only does VP8/WebM
and cannot produce the mp4.
Caption font: JetBrains Mono ships inside ghostty-opentui;
findCaptionFont in packages/term-video/src/compose.mjs searches bun's
isolated layout (node_modules/.bun/node_modules/…) then a hoisted
node_modules/…. If it still throws caption font not found, locate the
file with find node_modules -name jetbrains-mono-nerd.ttf and pass it as
fontPath to composeStoryboard.
Authoring scenes (capture.ts)
- Shared geometry is 140x32 cells rendered at fontSize 16 / dpr 2 → 2688x1536
PNGs. Keep every scene at this size so all frames fit one window.
- Helpers:
createDemoRepo() and launchHunkShell() are hunk-side glue in
the script (git repo built from examples/2-mini-app-refactor; interactive
bash with a real hunk command on PATH and a clean ❯ prompt); snap,
typeCommand, launchApp/launchShell, and createCommandWrapper come
from @hunk/term-video/capture.
- Always
waitForText on scene-specific content before the first snap, and
call ensureKeyboardIsLive() before scripted keypresses — the first key
after startup can be dropped (real race, the helper toggles ? to prove
keys land).
- Animation = one snap per keypress. Cursor walks and typing effects are
just every
j/k/character captured as its own frame and played back at
0.2–0.3s per frame. Prefer this over sparse keyframes: three stills read as
a slideshow, per-press frames read as motion.
renderTerminalToImage auto-trims trailing blank rows, so short outputs
(CLI scenes) produce short PNGs — the stage handles this by sampling the
image's bottom-left pixel and painting the window body to match.
manifest.json is a capture-side inventory of the current run only;
compose.mjs ignores it (frames resolve by name from SHOTS), and after a
SCENES= run it is partial while frames/ stays cumulative.
- Demo content that must exist: STML notes come from
examples/9-agent-markup-notes (launch with --experimental), extension
scenes from examples/extensions/ loaded via --extension <path> (explicit
paths skip the repo trust prompt). The pager pipe is git diff | hunk pager
— bare hunk on piped stdin prints help. Sidebar toggle is s; comment
draft is c, save with Ctrl+S (\x13).
Storyboard model (compose.mjs)
SHOTS is the whole edit: one entry per shot, dur in seconds, played as
unique frames + per-frame durations in an ffmpeg concat list (holds cost one
frame, so runtime is dominated by transitions, not length).
capKey is caption identity: the caption slides in only when capKey
changes, and continuation shots that share a capKey without restating
caption keep the previous caption on screen. Sequences (walks, typing) are
generated with Array.from spreads.
- Sequence lengths must match capture loop bounds:
walk("j", 10) in
capture.ts produces review-walk-00..09, consumed by
Array.from({length: 9}) (+ the opening frame) in SHOTS. Change one side
and the other breaks — the preflight check names any frame that's missing.
enter: true fades/scales the surface in — use it for cards and the first
terminal shot only.
- Caption HTML vocabulary:
<span class="badge">NEW</span> amber pill,
<span class="hl"> amber highlight, <span class="dim"> muted. Cards use
badge / h1/h2 / sub / cmds+cmd / foot classes from
packages/term-video/src/stage.html.
- Target pacing: money shots hold 3–4s, context shots 2–3s, typing/walk frames
0.2–0.6s; keep the total near 60s.
Command and output legibility
Terminal commands and their results must be readable at normal playback size.
Never rely on a full-width terminal prompt or output region as the only way the
viewer can understand a command scene; text that looks acceptable in a 1080p
source frame is often illegible in an embedded player or social feed.
Use this default treatment:
- Present the exact command in large type. The easiest treatment is a
cmd card or an oversized editorial callout immediately before the real
terminal result. A typing animation may remain for motion, but it does not
replace the large command treatment.
- Zoom the real output. Crop or scale the captured terminal frame around
the meaningful result so both the command and the important output lines
are comfortably readable. A brief full-window establishing shot is fine,
but the result's main hold must use the focused view.
- Keep the evidence real. Never fabricate terminal output. Large command
text may reproduce the exact command as an editorial overlay; any enlarged
output must come from the captured PTY frame. If reusable crop/zoom controls
are missing, add them to
@hunk/term-video rather than baking one-off image
edits into a storyboard.
- Trim before shrinking. Prefer fewer relevant lines and a tighter crop
over fitting a long transcript into the frame. Split a workflow across
multiple focused shots when one crop cannot keep every important line
legible.
Treat command legibility as a release gate: if the command or its result cannot
be read when the 1920x1080 video is displayed at 50% size, revise the shot.
Content accuracy (learned the hard way)
- Verify install commands against reality, not the README: check
npm view hunkdiff dist-tags. A prerelease needs npm i -g hunkdiff@beta;
brew install hunk only serves stable (homebrew-core Autobump, lags npm) —
omit brew on prerelease cards.
- Label demo extensions as examples. The triage board, CSS palette, and
semver views are
examples/extensions/, not shipped features — caption them
with a dimmed example: prefix. The real features are the APIs (sidebars,
file views, commands, dialogs).
- Window titles are decorative but must not lie: the shell scenes run bash,
so keep their titles generic (
shell — …) rather than naming a shell the
capture doesn't launch.
- STML requires
--experimental; say so on the outro card.
- The video is silent — never imply audio in the video or its announcement copy.
Verification and delivery
Eyeball keyframes in .video-work/frames/ (Read renders PNGs) after
capture — especially new scenes — before compositing.
Inspect every command scene at 50% display size. Confirm the exact command is
shown in large type and the meaningful real output is zoomed tightly enough
to read; a readable caption does not compensate for unreadable terminal text.
After encoding, return to the repository root, set VIDEO to the produced
MP4, and inspect a mid-animation point, each new scene, and the outro:
VIDEO=.video-work/hunk-feature-demo.mp4 # or .video-work/launch.mp4
ffmpeg -y -ss 2 -i "$VIDEO" -frames:v 1 .video-work/check.png
ffprobe -show_entries format=duration "$VIDEO"
Captions must persist through the extracted animation frames.
Outputs stay under .video-work/: the full-release recipe creates
launch.mp4/launch.webm, while the single-feature recipe above creates
hunk-feature-demo.mp4/hunk-feature-demo.webm. .video-work/ is
gitignored — never commit the video or its frames. For a standalone video
request, send both files to the user directly (mp4: social/Slack; webm: web
embeds), report duration and file sizes, and flag if the mp4 exceeds ~10 MB
(Slack) or ~15 MB (X). When invoked by hunk-release, hand both files back
to that workflow instead; it owns versioned filenames, GitHub's
user-attachment limit, public embedding, and inline-player verification.
Copy them elsewhere only if the user names a destination.
1---
2name: hunk-launch-video
3description: 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.
4metadata:
5 source: https://skillmd.com/skills/modem-dev/hunk-launch-video
6---
7
8# Hunk video pipeline
9
10Source-checkout only: the pipeline lives in `scripts/launch-video/`, which never ships to npm.
11It can be used for pull-request demos as well as maintainer release videos. Unix-only — the
12capture scripts exec `/bin/bash`.
13
14Generates product videos where every terminal frame is the real Hunk TUI —
15no screen recording, no mockups. Three stages:
16
17```text
18capture.ts (bun) drive Hunk over a PTY, snap styled keyframes to PNG
19compose.mjs (node + Playwright) render each PNG on a 1920x1080 HTML stage in Chromium
20ffmpeg encode the composited PNGs at 30fps to mp4/webm
21```
22
23Playwright controls headless Chromium: for each planned frame it loads the
24terminal PNG onto the HTML stage, applies the window chrome, cards, captions,
25and transition state, then screenshots the completed stage back to PNG. ffmpeg
26sequences those composited screenshots into the final videos.
27
28The generic machinery (PTY driving, keyframe rendering, storyboard planning,
29Chromium compositing, the stage template) is the `@hunk/term-video` workspace
30package in `packages/term-video/`; `scripts/launch-video/` holds only Hunk's
31scenes, captions, and cards on top of it.
32
33## Choosing a recipe
34
35The pipeline is not release-specific. Choose the editorial scope, then use the
36same capture → composite → encode stages:
37
38- **Single feature:** a short demonstration of one capability or workflow. Use
39 the single-feature recipe below and capture only the required scene.
40- **Full release:** a multi-feature roundup based on a release's changelog or
41 highlights. Use the full-release recipe and update the canonical storyboard.
42- **Custom video:** author any set of scenes and `SHOTS` for tutorials,
43 comparisons, announcements, or workflow explainers; follow the scene and
44 storyboard rules below.
45
46## Creating a video
47
48Expect ~3–6 min for capture and ~2–4 min for compose — run both with a long
49timeout (or in the background); each logs per-snap / per-shot progress.
50`compose.mjs` needs node ≥ 18 on PATH (bun alone is not enough).
51
52```sh
53# 0. dependencies (tuistory is a devDependency; ghostty-opentui arrives transitively)
54bun install # if a postinstall hook fails in a sandbox, retry with --ignore-scripts
55
56# 1. capture keyframes. Output defaults to <repo>/.video-work/ regardless of
57# cwd (pass a path argument to override), but the PROCESS must run from the
58# repo root — see gotchas.
59bun run scripts/launch-video/capture.ts
60
61# 2. one-time portable compositor setup. Playwright installs a Chromium build
62# that exactly matches its browser driver (see gotchas to reuse a system or
63# sandbox browser instead).
64printf '{"name":"hunk-video-work","private":true}\n' > .video-work/package.json
65cd .video-work
66bun add playwright playwright-core
67bunx playwright install chromium
68cd ..
69
70# 3. composite the storyboard
71node scripts/launch-video/compose.mjs .video-work
72
73# 4. encode
74cd .video-work
75ffmpeg -y -f concat -safe 0 -i concat.txt -vf "fps=30,format=yuv420p" \
76 -c:v libx264 -preset slow -crf 18 -movflags +faststart launch.mp4
77ffmpeg -y -f concat -safe 0 -i concat.txt -vf "fps=30,format=yuv420p" \
78 -c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1 launch.webm
79```
80
81Iterate on one scene without re-capturing the rest:
82
83```sh
84SCENES=review bun run scripts/launch-video/capture.ts # comma-separated scene names
85```
86
87Scene names are the `wants("...")` guards in `capture.ts`'s `main()`. Note
88`SCENES=` only narrows _capture_; `compose.mjs` preflights that every frame its
89`SHOTS` table references exists in `frames/` and fails fast listing any missing
90ones, so a full composite still needs every scene captured at least once.
91
92## Single-feature recipe
93
94For a short test, demo, or one-feature announcement, capture and composite only
95the scene for that feature:
96
971. Pick one user-visible capability and find its scene name in the
98 `wants("...")` guards. If it does not have a scene, author one using the
99 guidance below. Capture only that scene:
100
101 ```sh
102 SCENES=review bun run scripts/launch-video/capture.ts
103 ```
104
1052. Make a scratch compositor beside the canonical one so its imports and
106 repo-relative paths continue to work:
107
108 ```sh
109 cp scripts/launch-video/compose.mjs scripts/launch-video/compose-one-feature.mjs
110 ```
111
1123. In the scratch copy, trim `SHOTS` to an opening card, only the selected
113 feature's frames, and an outro card. Rewrite those cards and captions for
114 the scoped cut. Sequence lengths must still match the captured frame names.
1154. Composite into the same work directory, then run the normal ffmpeg commands
116 with descriptive output names:
117
118 ```sh
119 node scripts/launch-video/compose-one-feature.mjs .video-work
120 cd .video-work
121 ffmpeg -y -f concat -safe 0 -i concat.txt -vf "fps=30,format=yuv420p" \
122 -c:v libx264 -preset slow -crf 18 -movflags +faststart hunk-feature-demo.mp4
123 ffmpeg -y -f concat -safe 0 -i concat.txt -vf "fps=30,format=yuv420p" \
124 -c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1 hunk-feature-demo.webm
125 cd ..
126 rm scripts/launch-video/compose-one-feature.mjs
127 ```
128
129Keep the scratch compositor uncommitted. The canonical `compose.mjs` remains
130the checked-in reference storyboard. If you added a capture scene only to make
131PR evidence, revert that scene after encoding; retain it only when it is useful
132checked-in demo coverage and belongs to the submitted change.
133
134## Full-release recipe
135
1361. Read the release section in `CHANGELOG.md`. If it has a hand-written
137 **Highlights** list (0.18.0 has one; Changesets does not generate them), use
138 that list as the storyboard. Otherwise distill 4–6 user-visible headlines
139 from the Minor Changes — per-PR entries are too granular to shoot — and
140 confirm the shortlist with the user before capturing.
1412. Rewrite the canonical storyboard's editorial surface (next section), adding
142 or adjusting capture scenes as needed (see "Authoring scenes").
1433. Capture every scene referenced by the full storyboard, composite it, and
144 encode both formats using the main workflow above.
1454. Verify the complete cut (see "Verification") and deliver both files. When `hunk-release` invoked this workflow, return the approved MP4 and WebM to that skill for versioned naming and GitHub user-attachment embedding; do not upload or edit the public release without its confirmation gate.
146
147## Per-video editorial surface
148
149The capture machinery is reusable, but the storyboard is editorial content for
150one video. Rewrite it to match the video's scope. As of this writing, the
151checked-in reference storyboard is the full 0.18.0 release video:
152
153- `compose.mjs`: the whole `SHOTS` table; `OPEN_CARD` (version badge);
154 `OUTRO_CARD` (headline, install commands, footer); `EXTENSIONS_CARD`; every
155 `<span class="badge">NEW</span>` in captions — a NEW badge is a claim about
156 _this_ release, so drop or move them as features age.
157- `capture.ts`: the scene functions and the `wants()` guards in `main()` are
158 the current storyboard's scene list, plus hunk-side glue (`launchHunk`,
159 `launchHunkShell`, `createDemoRepo`, the keyboard probe).
160
161Reusable machinery lives in `@hunk/term-video` (`packages/term-video/`) —
162extend it there, don't fork it into the scripts: `createKeyframer`,
163`launchApp`/`launchShell`, `createCommandWrapper`, `typeCommand`,
164`ensureKeyboardIsLive`, `makeSceneFilter` (`src/capture.ts`); the unit-tested
165storyboard planner with the caption/timing semantics (`src/plan.mjs`);
166`composeStoryboard` with font/Chromium resolution and the missing-keyframe
167preflight (`src/compose.mjs`); and the stage template (`src/stage.html`).
168
169## Environment gotchas
170
171Sandbox-specific bullets are marked; each cost real debugging time.
172
173- **Run `capture.ts` with bun from the repo root.** tuistory uses subpath
174 self-imports (`tuistory/pty`) that only resolve inside this repo's
175 `node_modules`; running the script from elsewhere resolves tuistory from
176 bun's global cache and crashes. (Output location is unaffected — it defaults
177 to `<repo>/.video-work/` via `import.meta.url`.)
178- **ghostty-opentui is a transitive dep** (via tuistory) with an exports map:
179 import `"ghostty-opentui/image"` (not `.../dist/image.js`), resolved
180 relative to tuistory — `@hunk/term-video/capture`'s `createKeyframer` does
181 the `Bun.resolveSync` dance.
182- **Playwright must match the Chromium it drives.** The portable setup above
183 installs `playwright` and `playwright-core` together, then downloads their
184 matching Chromium build. It works on macOS and Linux and is preferred when
185 bandwidth and browser downloads are available; leave `CHROMIUM_PATH` unset
186 so Playwright uses that managed browser. On Linux, if Chromium reports
187 missing system libraries, run `bunx playwright install-deps chromium` (it
188 may require sudo) before retrying.
189
190 To reuse an existing system, CI, or sandbox Chromium instead, install the
191 `playwright-core` version provided by that environment and set its executable
192 explicitly:
193
194 ```sh
195 cd .video-work
196 bun add playwright-core@<matching-version>
197 cd ..
198 CHROMIUM_PATH=/path/to/chromium node scripts/launch-video/compose.mjs .video-work
199 ```
200
201 Common executable locations include `$(command -v chromium)` or
202 `$(command -v google-chrome)` on Linux and
203 `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` on macOS.
204 In an environment with a preinstalled Playwright toolchain, read that
205 toolchain's `package.json` to get the exact driver version. For example, the
206 Anthropic sandbox exposes it through `/opt/pw-browsers/.links/*`:
207
208 ```sh
209 cat "$(cat /opt/pw-browsers/.links/* | head -1)/package.json" | grep '"version"'
210 # e.g. "1.56.1" -> bun add playwright-core@1.56.1
211 ```
212
213 `compose.mjs` picks its browser as `$CHROMIUM_PATH`, then
214 `/opt/pw-browsers/chromium` when present, then Playwright's managed browser.
215
216- **Give `.video-work/` its own `package.json` before `bun add`.** Without
217 one, bun walks up and installs into the repo's `package.json` — revert with
218 `git checkout package.json bun.lock` if that happens.
219- **Chromium needs `--allow-file-access-from-files`** (already in
220 `compose.mjs`): the stage samples each keyframe through a canvas to
221 color-match the window background, and file:// images taint the canvas
222 without it.
223- **mp4 needs an ffmpeg with libx264.** Sandbox: `apt-get install ffmpeg`
224 (run `apt-get update` first if packages 404). macOS: `brew install ffmpeg`.
225 Verify `ffmpeg -encoders | grep -E 'libx264|libvpx-vp9'` shows both before
226 encoding — playwright's bundled `ffmpeg-*/ffmpeg-linux` only does VP8/WebM
227 and cannot produce the mp4.
228- **Caption font**: JetBrains Mono ships inside ghostty-opentui;
229 `findCaptionFont` in `packages/term-video/src/compose.mjs` searches bun's
230 isolated layout (`node_modules/.bun/node_modules/…`) then a hoisted
231 `node_modules/…`. If it still throws `caption font not found`, locate the
232 file with `find node_modules -name jetbrains-mono-nerd.ttf` and pass it as
233 `fontPath` to `composeStoryboard`.
234
235## Authoring scenes (capture.ts)
236
237- Shared geometry is 140x32 cells rendered at fontSize 16 / dpr 2 → 2688x1536
238 PNGs. Keep every scene at this size so all frames fit one window.
239- Helpers: `createDemoRepo()` and `launchHunkShell()` are hunk-side glue in
240 the script (git repo built from `examples/2-mini-app-refactor`; interactive
241 bash with a real `hunk` command on PATH and a clean `❯` prompt); `snap`,
242 `typeCommand`, `launchApp`/`launchShell`, and `createCommandWrapper` come
243 from `@hunk/term-video/capture`.
244- Always `waitForText` on scene-specific content before the first snap, and
245 call `ensureKeyboardIsLive()` before scripted keypresses — the first key
246 after startup can be dropped (real race, the helper toggles `?` to prove
247 keys land).
248- **Animation = one snap per keypress.** Cursor walks and typing effects are
249 just every `j`/`k`/character captured as its own frame and played back at
250 0.2–0.3s per frame. Prefer this over sparse keyframes: three stills read as
251 a slideshow, per-press frames read as motion.
252- `renderTerminalToImage` auto-trims trailing blank rows, so short outputs
253 (CLI scenes) produce short PNGs — the stage handles this by sampling the
254 image's bottom-left pixel and painting the window body to match.
255- `manifest.json` is a capture-side inventory of the _current run_ only;
256 `compose.mjs` ignores it (frames resolve by name from `SHOTS`), and after a
257 `SCENES=` run it is partial while `frames/` stays cumulative.
258- Demo content that must exist: STML notes come from
259 `examples/9-agent-markup-notes` (launch with `--experimental`), extension
260 scenes from `examples/extensions/` loaded via `--extension <path>` (explicit
261 paths skip the repo trust prompt). The pager pipe is `git diff | hunk pager`
262 — bare `hunk` on piped stdin prints help. Sidebar toggle is `s`; comment
263 draft is `c`, save with Ctrl+S (`\x13`).
264
265## Storyboard model (compose.mjs)
266
267- `SHOTS` is the whole edit: one entry per shot, `dur` in seconds, played as
268 unique frames + per-frame durations in an ffmpeg concat list (holds cost one
269 frame, so runtime is dominated by transitions, not length).
270- `capKey` is caption identity: the caption slides in only when `capKey`
271 changes, and continuation shots that share a `capKey` without restating
272 `caption` keep the previous caption on screen. Sequences (walks, typing) are
273 generated with `Array.from` spreads.
274- **Sequence lengths must match capture loop bounds**: `walk("j", 10)` in
275 `capture.ts` produces `review-walk-00..09`, consumed by
276 `Array.from({length: 9})` (+ the opening frame) in `SHOTS`. Change one side
277 and the other breaks — the preflight check names any frame that's missing.
278- `enter: true` fades/scales the surface in — use it for cards and the first
279 terminal shot only.
280- Caption HTML vocabulary: `<span class="badge">NEW</span>` amber pill,
281 `<span class="hl">` amber highlight, `<span class="dim">` muted. Cards use
282 `badge` / `h1`/`h2` / `sub` / `cmds`+`cmd` / `foot` classes from
283 `packages/term-video/src/stage.html`.
284- Target pacing: money shots hold 3–4s, context shots 2–3s, typing/walk frames
285 0.2–0.6s; keep the total near 60s.
286
287## Command and output legibility
288
289Terminal commands and their results must be readable at normal playback size.
290Never rely on a full-width terminal prompt or output region as the only way the
291viewer can understand a command scene; text that looks acceptable in a 1080p
292source frame is often illegible in an embedded player or social feed.
293
294Use this default treatment:
295
2961. **Present the exact command in large type.** The easiest treatment is a
297 `cmd` card or an oversized editorial callout immediately before the real
298 terminal result. A typing animation may remain for motion, but it does not
299 replace the large command treatment.
3002. **Zoom the real output.** Crop or scale the captured terminal frame around
301 the meaningful result so both the command and the important output lines
302 are comfortably readable. A brief full-window establishing shot is fine,
303 but the result's main hold must use the focused view.
3043. **Keep the evidence real.** Never fabricate terminal output. Large command
305 text may reproduce the exact command as an editorial overlay; any enlarged
306 output must come from the captured PTY frame. If reusable crop/zoom controls
307 are missing, add them to `@hunk/term-video` rather than baking one-off image
308 edits into a storyboard.
3094. **Trim before shrinking.** Prefer fewer relevant lines and a tighter crop
310 over fitting a long transcript into the frame. Split a workflow across
311 multiple focused shots when one crop cannot keep every important line
312 legible.
313
314Treat command legibility as a release gate: if the command or its result cannot
315be read when the 1920x1080 video is displayed at 50% size, revise the shot.
316
317## Content accuracy (learned the hard way)
318
319- **Verify install commands against reality**, not the README: check
320 `npm view hunkdiff dist-tags`. A prerelease needs `npm i -g hunkdiff@beta`;
321 `brew install hunk` only serves stable (homebrew-core Autobump, lags npm) —
322 omit brew on prerelease cards.
323- **Label demo extensions as examples.** The triage board, CSS palette, and
324 semver views are `examples/extensions/`, not shipped features — caption them
325 with a dimmed `example:` prefix. The real features are the APIs (sidebars,
326 file views, commands, dialogs).
327- Window titles are decorative but must not lie: the shell scenes run bash,
328 so keep their titles generic (`shell — …`) rather than naming a shell the
329 capture doesn't launch.
330- STML requires `--experimental`; say so on the outro card.
331- The video is silent — never imply audio in the video or its announcement copy.
332
333## Verification and delivery
334
335- Eyeball keyframes in `.video-work/frames/` (Read renders PNGs) after
336 capture — especially new scenes — before compositing.
337- Inspect every command scene at 50% display size. Confirm the exact command is
338 shown in large type and the meaningful real output is zoomed tightly enough
339 to read; a readable caption does not compensate for unreadable terminal text.
340- After encoding, return to the repository root, set `VIDEO` to the produced
341 MP4, and inspect a mid-animation point, each new scene, and the outro:
342
343 ```sh
344 VIDEO=.video-work/hunk-feature-demo.mp4 # or .video-work/launch.mp4
345 ffmpeg -y -ss 2 -i "$VIDEO" -frames:v 1 .video-work/check.png
346 ffprobe -show_entries format=duration "$VIDEO"
347 ```
348
349 Captions must persist through the extracted animation frames.
350
351- Outputs stay under `.video-work/`: the full-release recipe creates
352 `launch.mp4`/`launch.webm`, while the single-feature recipe above creates
353 `hunk-feature-demo.mp4`/`hunk-feature-demo.webm`. `.video-work/` is
354 gitignored — never commit the video or its frames. For a standalone video
355 request, send both files to the user directly (mp4: social/Slack; webm: web
356 embeds), report duration and file sizes, and flag if the mp4 exceeds ~10 MB
357 (Slack) or ~15 MB (X). When invoked by `hunk-release`, hand both files back
358 to that workflow instead; it owns versioned filenames, GitHub's
359 user-attachment limit, public embedding, and inline-player verification.
360 Copy them elsewhere only if the user names a destination.