Demo Video Studio
実行中のウェブアプリを、洗練されたデモフィルムに変換します。実際の操作録画（スライドショーやモックではなく）+ ローカル TTS ナレーション + ワード同期キャプション + 控えめな BGM を、HyperFrames で決定論的に合成します。
使用する場面
ウェブアプリのデモ/ウォークスルー/製品/ローンチ/ハッカソンビデオを作成するとき、特に実際の製品を動作させながらナレーションとキャプションを付けたい場合。デプロイされたURLまたはローカル開発サーバーを録画します。
パイプライン
① 録画 3つのエンジン（下記）のいずれか → out/*.mp4|webm
② ナレーション シーンごとにVOを書き、Kokoro TTS（ローカル）で生成 → narration/*.wav
③ 文字起こし Whisper でワードレベルタイムスタンプ → *.transcript.json
④ キャプション フレーズにグループ化 + ブランド名の誤認識を修正 → captions.js
⑤ 音楽 ffmpeg アンビエントBGM（音声の下にミックス） → music/bed.wav
⑥ 合成 HyperFrames HTML ワンタイムライン: クリップ+音声+キャプション+音楽 → MP4
① は3つのエンジン — 目的に応じて選択 （references/screen-studio-look.md）:
| 対象 | エンジン | 見た目 |
|---|---|---|
| Web/デスクトップアプリ、macOS | Cap CLI — scripts/record-cap.mjs | Screen Studio ネイティブ: 実際のクリックからの自動ズーム、スプリングカーソル+モーションブラー、壁紙/角丸/シャドウ、GPUレンダリング |
| CLI ツール | VHS テープ → mp4 | スタイル指定可能なターミナル（パディング、マージン塗りつぶし、角丸、ウィンドウバー）、決定論的 |
| ヘッドレス / CI / Linux | Playwright — scripts/record.mjs | 合成カーソル+リップル効果; <scene>.events.json（タイムスタンプ+座標）を出力し、後でズーム合成可能 |
どのエンジンで録画しても、出力はあくまで②〜⑥に供給されるクリップです。録画と合成は独立しており、1つのシーンを再録画したり、ナレーションを再実行したりしても、他の作業をやり直す必要はありません。コード生成されたGIFトラック（HTMLシーンを録画せず直接MP4にレンダリング）は、ドキュメントページ用のオプションのサイドパスです。
ワークフロー
- ユーザーと一緒にエンジンを選びます — 黙って決めないでください。 実際のプロジェクト（ウェブアプリ？CLI？デスクトップ？このマシンにGUIセッションはある？CIで実行する必要がある？）を確認し、エンジンの選択肢をこのプロジェクト固有のメリット/デメリットとともに提示し、ユーザーに選んでもらいます。例：Mac上のウェブアプリの場合：「Cap CLIはScreen Studioの見た目をネイティブで提供しますが、画面収録の許可と初回キャリブレーションが必要です。Playwrightはどこでも実行でき、1シーンの再録画が高速ですが、自動ズームはありません。VHSはここでは該当しません。」エンジンの詳細: references/screen-studio-look.md。
- まず製品を理解します。 README / デモドキュメントを読みます。ツールに触れる前にデモフローを書きます：問題 → 製品ウォークスルー → 証拠 → 結論。推奨するクリックパスと、各シーンで表示するべき結果を決めます。 references/templates.md を参照。
- 録画します。
scripts/record.mjsをコピーし、APPとSIZEを設定し、scenesをあなたの振り付けに置き換えます（移動 → 一時停止 → 操作 → 保持）。デバイススケール1:1で録画します。node scripts/record.mjs [scene]。エンジンと実例: references/recording.md。 - ナレーション → キャプション。 シーンごとに
assets/narration/NN-*.txtをVOの声で書きます（視聴者に話しかけるように。READMEを読んでいるわけではありません — これはマーケティングコピーとは異なる技術です。マーケティングスキルがトピック/フック/ストーリーボードを提供し、このスキルが話す言葉を書きます）。次に:bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjsbuild-captions.mjs内のPHRASE_FIXをブランド名用に編集します。 音声は契約により交換可能です: ナレーションはシーンごとに1つのwavファイル（narration/NN-*.wav）です。任意のwavを人間のテイク、剪映の吹き替え、別のTTSに置き換え、transcribe+captionsを再実行し、再合成するだけです。他は何も変わりません。Kokoro（ローカル、Apache-2.0）がデフォルトで、中国語の音声もあります。edge-tts は無料のオンライン代替手段です。ガイド: references/narration-and-captions.md。 - 合成 & レンダリング。 references/composition-skeleton.html（1クリップ + キャプショントラック + 音声）から始め、タイムラインを拡張し、次に
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality highを実行します。1:1でレンダリングします（1080pで作成 → 1080pで出力）。4Kにアップスケールしないでください。UIがぼやけます。 references/composition.md。 - 出荷前にQCします。 ffprobe で長さ/音声を確認し、1〜2フレームをサンプリングします（黒画面や空でないこと）、キャプションがフレーム内にあること、ナレーションが途切れていないこと、主要な結果ページが実際に見えること。フロー/タイミングを修正し、再レンダリングします。
クイックスタート
# システム依存関係
brew install node ffmpeg
npx playwright install chromium
# ローカルTTS + 文字起こし用 Python venv（1回のみ）
python3 -m venv .ttsvenv && .ttsvenv/bin/pip install kokoro-onnx soundfile
export PATH="$(pwd)/.ttsvenv/bin:$PATH"
# 1) 録画 2) ナレーション 3) キャプション 4) 合成+レンダリング
node scripts/record.mjs
bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high --output out/demo.mp4
初回のTTSは約340MB（Kokoro）、初回の文字起こしは約466MB（Whisper small.en）をダウンロードします。どちらも ~/.cache/hyperframes/ にキャッシュされます。
苦労して得られたルール
- 実際の操作がスライドに勝る — 実際に動作している製品を録画すること。
- 1:1、決して2倍にアップスケールしない — 2倍のDPRで録画し4Kでレンダリングすると、すべてのUIクリップがぼやけます。1080pで作成・レンダリングすること。
- 決定論的な合成 — HTML内で
Date.now()、Math.random()、ネットワークを使用しない。HyperFramesはフレームをシークするため、モーションは再現可能でなければなりません。 - カーソルを可視化し、結果で停止する — 意図的に移動し、見せ場で一時停止すること。
- VOであって、ドキュメントではない — ナレーションは映像に沿うものであり、READMEを読み上げるものではない。
- ビデオはナレーション以上に — クリップ時間に余裕を持たせ、映像が音声より先に終わらないようにすること。
依存関係
Node 22+、FFmpeg、Playwright（Chromium）、および HyperFrames CLI（npx hyperframes、スキルは npx skills add heygen-com/hyperframes でインストール）。ローカルTTS/Whisperには Python + kokoro-onnx が必要です。エンジン別（オプション）: Capルートには cap（curl -fsSL https://cap.so/install-cli.sh | sh）+ cliclick（brew install cliclick）+ 画面収録許可が必要です。ターミナルルートには vhs（brew install vhs）が必要です。すべて無料 — ライセンス表は references/screen-studio-look.md を参照。HyperFramesのセットアップについては references/composition.md を参照。
リファレンス
- references/pipeline.md — 6つのステージとデータフロー
- references/screen-studio-look.md — 3つの録画エンジン; Cap CLIのライフサイクル、ズームクラスタリング、VHSテープ、構築すべきでないもの
- references/recording.md — Directorエンジン + 実例 + 録画の落とし穴
- references/narration-and-captions.md — VO作成、TTS、Whisper、キャプション修正
- references/composition.md — HyperFramesタイムライン、クロスフェード、1080p、レンダリング
- references/composition-skeleton.html — index.htmlとしてコピーする最小限のレンダリング可能な構成
- references/templates.md — ハッカソン + 製品デモの構造とVOの骨組み
- references/troubleshooting.md — キャプション、白画面、音声、フォント