record-tui

Record TUI — VHS ターミナル録画

概要

Charmbracelet VHS は、.tape スクリプトを GIF／MP4／WebM／ASCII にレンダリングします。画面をキャプチャするのではなく、デモをコードとして記述してください。アプリに変更があっても .tape は手を加えずに再レンダリングでき、CI でも同じように実行できるためです。再実行する予定のない使い捨ての録画なら、asciinema のほうが軽量です。

セットアップ

# macOS
brew install charmbracelet/tap/vhs ffmpeg ttyd
# Debian/Ubuntu
sudo apt install ffmpeg && sudo snap install ttyd --classic && go install github.com/charmbracelet/vhs@latest

vhs --version && ffmpeg -version && ttyd --version   # all three are required

Tape ファイルの構造

すべての Set は、最初の操作コマンドより前に配置してください。それより後に置かれた Set は無視されます。Gotchas を参照してください。

Output demo.gif              # 1. output (gif/mp4/webm/ascii)
Require my-app               # 2. fail fast if the app is missing

Set Shell "bash"             # 3. settings, all grouped before any command
Set FontSize 20
Set Width 1200
Set Height 600
Set Theme "Catppuccin Frappe"
Set WindowBar Colorful
Set Padding 20
Set TypingSpeed 75ms

Hide                         # 4. hidden setup — Ctrl+L before Show
Type "export TERM=xterm-256color"
Enter
Sleep 500ms
Ctrl+L
Show

Type "my-app --demo"         # 5. visible interactions, with deliberate pauses
Sleep 500ms
Enter
Sleep 2s
Down 3                       # 6. app interaction
Enter
Sleep 3s                     # generous final frame before the loop restarts

クイックリファレンス

コマンド	用途
Output file.gif	出力ファイルと形式（gif/mp4/webm/ascii）。複数の形式を出力する場合は繰り返します
Require app	プログラムが PATH 上にない場合に失敗します
Set Key Value	ターミナル設定（FontSize、Width、Height、Theme、Framerate など）
Type "text" / Type@100ms "text"	入力をエミュレートします（1 行あたりの速度を指定することもできます）
Enter / Tab / Space / Escape	キー入力
Up/Down/Left/Right（Down 3）	回数を指定できるナビゲーション
Ctrl+key、Alt+key、Shift+key	修飾キーとの組み合わせ
Sleep 2s	固定時間の一時停止（ミリ秒または秒）
Wait+Screen@30s /regex/	タイムアウト付きで、画面の内容が一致するまで待機します
Hide / Show	録画の表示／非表示を切り替えます（どちらの場合も実行は続行されます）
Screenshot file.png	現在のフレームをキャプチャします
Env VAR "val" / Source other.tape	環境変数を設定／別の tape を読み込みます

vhs validate demo.tape    # parse-check, no rendering
vhs demo.tape             # record
vhs themes                # list themes
vhs new demo.tape         # scaffold from template

コマンドと設定の詳細：reference/COMMAND-REFERENCE.md。

用途	幅	高さ	フォントサイズ
README の GIF	1200	600	20
ドキュメント／チュートリアル	1400	800	18
ソーシャルメディア	1200	630	22
フルサイズの TUI アプリ	1600	900	16
コンパクトな CLI	800	400	20

アプリ用の tape を録画する

アプリの --help 出力またはソースを確認し、起動方法、対応するキー、表示する価値のある状態を把握してください。それらの状態を含む tape を作成し、vhs validate demo.tape → vhs demo.tape → レンダリングされたファイルを視聴 → 調整、の順に進めます。重要なのは視聴することです。検証で構文は解析できますが、デモの進行が速すぎて視聴者が追いつけないかどうかは判断できません。

作成前にデモの範囲を決めてください。README の GIF では、10～30 秒で 1 つのワークフローを見せます。3～5 個の状態を、それぞれ読めるだけの時間（Sleep 2s～3s）表示します。30 秒を超える場合は、シーンを追加するのではなく、状態を削るか 2 つ目の tape に分割してください。すべてを見せるデモは何も伝えず、GIF のサイズも大きくなります。

コピーして使えるひな形（Basic CLI、Interactive TUI、Build-and-Run、Multi-Panel、CI golden file、組み合わせ可能な Source tape）：reference/TEMPLATES.md。

例

✅ Output を先頭に置き、設定をコマンドの前にまとめ、Require でバイナリの有無を確認し、入力後に一時停止して最後のフレームを長めに表示しています。

Output demo.gif
Require my-app

Set Shell "bash"
Set FontSize 20
Set Width 1200
Set Height 600

Type "my-app status"
Sleep 500ms
Enter
Sleep 3s

❌ 同じ tape に 3 つの問題があります。Set Width が Type の後にあり無視されること、入力と実行の間に区切りがないこと、バイナリがない場合にエラーではなく、原因の分かりにくい空の GIF が生成されることです。

Output demo.gif

Type "my-app status"
Enter
Set Width 1200

✅ 起動時間が変動する TUI のペース調整では、Sleep の時間を推測するのではなく、画面の一致を待ちます。

Type "my-tui"
Enter
Wait+Screen@30s /Ready/
Down 3
Sleep 500ms
Enter
Sleep 3s

注意点

• 最初のコマンドより後にある Set は黙って無視されますが、vhs validate は終了コード 0 を返します。 vhs 0.11.0 で確認済みです。Type の後にある Set FontSize 40 はデフォルトのサイズで描画され、Set TypingSpeed も同様です。設定ごとの例外はありません。すべての Set を最初の Type／キーコマンドより前に置き、出力を見て確認してください。ツールチェーンからは何も報告されないためです。テープの途中で入力速度を変えるには、行ごとの Type@100ms "…" 形式を使用してください。
• vhs validate が行うのは解析だけです。 アプリを起動しないため、バイナリがない、キー割り当てが間違っている、デモがアプリより先に進んでしまう、といった場合もすべて検証を通過します。依存関係がないときに空のターミナルを録画するのではなく、明確に失敗するように Require <app> を追加してください。
• Type "cmd" は Enter キーを押しません。 明示的な Enter を続けて入力し、その間に Sleep 500ms を挟んで、実行前に閲覧者がコマンドを読めるようにしてください。
• Hide は出力を隠しますが、コマンドの実行は隠しません。 Hide ブロック内のコマンドも実行されます。残ったセットアップ出力が録画の冒頭に表示されないよう、Show の前に Ctrl+L でブロックを終了してください。
• Wait はタイムアウトします。 起動に時間のかかる TUI では、長めの Sleep を挟むのではなく、コマンドごとに Wait+Screen@30s /ready/ を指定するか、全体に Set WaitTimeout 30s を設定してください。長めの Sleep では、動作の遅いマシンで適切に対応できません。
• VHS は新しいシェルで録画するため、プロンプトのカスタマイズは反映されません。 自分のマシンと CI で同じプロンプトを使うには、Set Shell "bash" を固定してください。
• TUI の色や折り返しが正しく表示されない場合、たいていはターミナルの設定が原因です。 Hide ブロック内で、Env TERM "xterm-256color" と Type "stty rows 50 cols 120" を指定してください。
• GIF のサイズはすぐに 5 MB を超えます。 GitHub ではインライン表示されますが、README の読み込みが遅くなります。まず Set Framerate 15 を試してください。手軽に効果が得られ、体感の滑らかさへの影響もわずかです。次に gifsicle -O3 --lossy=80 を試し、読みやすさを損なうほど寸法を縮小する前に MP4 に切り替えてください。

最適化と CI

サイズの縮小、再生の調整、GIF・MP4・WebM の選択手順については、reference/OPTIMIZATION.md を参照してください。GitHub Actions での録画と、UI 回帰テスト用の正解ファイルとしての ASCII 出力については、reference/CI-INTEGRATION.md を参照してください。

統合

build-tui と組み合わせて、TUI のビルド直後に録画し、アプリと一緒に GIF を再生成できるよう、.tape をソースの隣にコミットしてください。対象が localhost 上のウェブ UI の場合は、代わりに screenshot-local を使用してください。

外部リンク：VHS · VHS Action · examples · themes · gifsicle。