jpoz/make-video

make-video は何をしますか？

プロンプトからナレーション付き映像を生成します。すべてのフレームは時間 t の純粋関数として、キャンバス（@napi-rs/canvas）上に描画され、ffmpeg でエンコードされます。音声は Kokoro でローカル生成されます。音楽は Python で合成されます。すべての画像は、それを説明する音声の単語に合わせてタイミングが調整されます。

フローは固定です: プロンプト → ストーリーボード（実際の音声、実際の音楽、シーンごとに1枚の実フレーム）→ ユーザーがストーリーボードを反復改良 → フルレンダリング。ユーザーがストーリーボードを承認する前に、フル映像をレンダリングしないでください。各ステップで実際のフレームをサンプリングし、表示する前に問題を修正してください。

<skill> は、この SKILL.md が置かれているフォルダを意味します。

必要条件

node 20+、ffmpeg、uv（Python スクリプトを実行し依存関係をインストールするため）、および python3 が必要です。./make.sh setup でこれらがインストールされているか確認します。Kokoro モデル（約115 MB）は、最初の音声生成時に一度だけ ~/.cache/make-video/models にダウンロードされます。フォントは同梱されていません。references/fonts.md を参照してください。

1. 映像の内容を理解する（プロンプトから）

コードを書き始める前に、映像のテーマを把握してください。PR、リポジトリ、ドキュメント、アプリ、発表内容を読み込みます。映像に表示できる実物（実際の画面、実際のコード、実際の出力）を見つけてください。以下の項目を決定し、自分で調べられないことだけをユーザーに質問します。

• 種類と長さ。 機能紹介または発表：30～75秒、6～10シーン、実際のアプリ画面。解説：2～6分、タイトルカード、図、コードを含む章構成。目安：音声は1秒あたり2.5語。
• 視聴者と、最後に視聴者が知るべきこと・行うべきこと（the one thing）。
• 見た目。 theme.mjs の ink パレット（ほぼ黒、赤のアクセント）か navy（深い青、スカイとアンバー）、またはプロダクト自体の色とフォント。
• 音楽スタイル。 pop（明るくアップビート）、chip（静かなチップチューン）、または none。

2. プロジェクトを作成する

<skill>/scripts/new-project.sh ~/Developer/<topic>-video <topic>-video

これにより <skill>/template（動作する30秒のサンプル映像）がコピーされ、npm install が実行されます。フォントを入手してください（references/fonts.md）。プロジェクトは自己完結型です。以下のファイルを編集します。

ファイル	説明
video.json	スクリプト：シーン、音声ライン、キュー、タイミング、音楽、ストーリーボードの概要
scenes/*.mjs	シーンIDごとの描画関数
theme.mjs	パレット、フォント、背景
music.py	スコア（コード、フック、楽器）。デフォルトが合わない場合に使用
shots/plan.mjs	アプリ表示時にキャプチャする実際のアプリスクリーンショットの計画

timeline.json は編集しないでください。timeline.py が生成します。

3. スクリプトを書く（video.json）

まず references/script.md を読んでください。要点：シーンごとに1つのアイデア、短く平易な文章、フックで始め、次に何をすべきかで終わります。一行は文字列、または {"text", "say"}（キャプションと発音が異なる場合。例："video.json" は "video dot jason" と発音される）。キュー は画像が合致する単語を指定します：{"label": "badge", "at": "badge", "sound": "chime"}。重要な登場ごとにキューを設定します。brief（導入、アプローチ、未解決の質問）を記入します。ストーリーボードに表示されます。

4. シーンを描画する（scenes/*.mjs）

references/drawing.md（シーンAPI、ヘルパー、レイアウトとモーションのルール）を読んでください。各シーンは (ctx, t, S) を受け取ります。各登場を S.cue(label) または S.w('word') に配置し、各要素を S.tout で退場させます。実物素材を使用します。

• アプリ画面： shots/capture.mjs で実際のUIをキャプチャし、screens.mjs（カメラ、カーソル、リング）で表示します。references/screens.md を参照。
• コード： code.mjs は実際のファイルを行番号で読み込むため、引用が間違うことはありません。
• プログラム出力： 実際のプログラムを実行し、その実際の出力を描画します。見たことのない出力を描画しないでください。

描画しながらサンプリングします。 各シーンが終わったら ./make.sh scene <id> を実行し、次のシーンに進む前に out/sheet.jpg を確認します。トリッキーな動きやトランジションごとに ./make.sh clip A B を実行し、out/clip.mp4 を確認します。references/review.md にチェックリストがあります。

5. ストーリーボード：ユーザーがここで反復改良する

./make.sh storyboard

これにより、音声 → タイムライン → 音楽 → オーディオミックス → シーンごとに1フレーム → storyboard.html が生成されます。これは、実際の音声と音楽のミックス、各シーンのフレーム、各キュー単語がマークされたスクリプト、タイムコード、概要を含む自己完結型のページです。再生すると現在のシーンと行がハイライト表示されます。

表示する前に、out/board/ 内のすべてのフレームを確認し、問題を修正してください。その後、ユーザーにページを渡します。ハーネスがHTMLページやアーティファクトを公開できる場合は、storyboard.html を公開してリンクを共有してください。できない場合は、ブラウザで開くファイルパスを伝えます。

その後、ユーザーと反復改良を行います。各変更は小さく迅速です。video.json の1行を編集する（変更された行のみが再度音声化される）、キューを移動する、シーンのエネルギーを変更する、スタイルを変更する、シーンを再描画する。その後、再度 ./make.sh storyboard を実行します。概要の未解決の質問を最新に保ちます。ユーザーがストーリーボードを承認するまでこのループを続けます。

6. フルレンダリング

ユーザーが承認した場合のみ実行します。

./make.sh film            # または：./make.sh film --blur 4   （モーションブラー、約4倍遅い）

これにより out/<name>.mp4（1920×1080、60 fps、AAC、ラウドネス -16 LUFS）、out/<name>.srt、out/<name>.vtt が書き出されます。その後、コードではなく実際の出力を確認します（references/review.md「最終チェック」を参照）：エンコードされたMP4からフレームを抽出し、再生時間とストリームを確認し、変更されたポイントのミックスを聴きます。python3 storyboard.py --final を実行すると、ストーリーボードページに完成した映像が埋め込まれます。MP4、キャプション、ストーリーボードを納品します。映像が発表の場合は、同じスクリプトから短い記事を合わせて提案します。

コマンド

コマンド	機能
./make.sh storyboard	音声、タイムライン、音楽、ミックス、ボードフレーム、storyboard.html を生成
./make.sh scene ID [0.3,0.6,0.9]	1シーンの経過時間における静止画、out/sheet.jpg も出力
./make.sh samples [24]	映像全体から均等にサンプリングした静止画、out/sheet.jpg も出力
./make.sh stills 3,20.5	指定秒数の静止画、out/sheet.jpg も出力
./make.sh clip A B	out/clip.mp4：秒数AからBまでの映像の抜粋、音声付き
./make.sh voice / music / timeline	1ステップのみ実行
./make.sh film [--blur N]	フルレンダリングとミックス
uv run tts.py --voices	利用可能なKokoro音声一覧

参考文献

• references/script.md：ナレーションの書き方、video.json の全仕様
• references/drawing.md：シーンAPI、lib.mjs ヘルパー、レイアウト、モーション、シーンパターン
• references/screens.md：実際のアプリ画面のキャプチャとカメラ移動
• references/audio.md：音声、音楽スタイル、キューサウンド、ミックス、追加オーディオ
• references/review.md：サンプリング方法、調整チェックリスト、最終チェック
• references/fonts.md：フォントの入手先