jdrurka/explainer-skill

Explainer（解説動画スキル）

顔出しなし解説動画は、一つの継続的なコードで構築されたアニメーションの世界（断面図、拡大されたメカニズム、物体を手に持っている様子など）にナレーションを乗せ、上部にキャプションを表示し、音楽は使用しない動画です。出力は 1080×1920 の mp4 ファイルです。

作成前に以下のファイルを読んでください。

• script-craft.md：スクリプトの構成方法（フック、ひねり、想像、メカニズム、反転、CTA）とテンポについて
• craft-rules.md：ビジュアルを生き生きと立体的に見せるためのルール。最初の段階ではこれらのルールのほとんどを満たせていないことが普通です。

難しいのは、各ビートに対応する視覚的メタファーです。次に難しいのは、すべてのフレームを動きのある、奥行きのある照明で保つことです。コードは比較的簡単な部分です。

モード

• ワンショット（デフォルト）：コンセプトから最終動画まで一気に作成します。判断はスキル自身で行い、最後にその判断を報告します。
• レビュー：ユーザーがレビューや承認を要求した場合、スクリプト作成後とストーリーボード作成後の2回停止します。ユーザーの指摘に基づいて修正し、続行します。

セットアップ確認（初回のみ）

ffmpeg が PATH に存在すること、remotion/node_modules が存在すること（存在しない場合は remotion/ で npm install を実行）、.env ファイルに FISH_API_KEY が設定されていること（.env.example をコピー）。キーがない場合は、voice --placeholder ですべてを構築し、最終ステップとして voice の再実行とレンダリングが必要であることをユーザーに伝えます。

レイアウト

projects/<コンセプト>/（コンセプトはスラッグ形式、例：how-fridges-work）：

• script.txt、storyboard.md
• composition.tsx（レイヤースタック）、timeline.ts（TL）、captions.ts、words.ts（生成される）、scenes/S01.tsx …
• public/vo.wav、vo/（生テイクとアライメントデータ）、out/（レンダリング結果、スチル）

コアライブラリは remotion/src/core（シーンからは ../../../remotion/src/core としてインポート）：

• makeTimeline → TL.at("phrase")、TL.end("phrase")
• Captions、Drift、Bokeh、Vignette、handheld、Backdrop、Dust、Footnote
• Camera（WorldSvg、camAt、toScreen）、Label、Sparks、Snow / Rain
• イージング関数、ramp、keys、rand、フォント SANS / MONO

ツール：python3 bin/explainer.py …（-h でヘルプ表示）

コマンド	説明
new <c>	プロジェクトをスキャフォールディングします
voice <c> [--voice-id ID] [--speed 1.0]	Fish Audio で音声を生成し、単語のタイムスタンプを含む words.ts と、-14 LUFS にノーマライズされた public/vo.wav を作成します。wpm を出力します
voice <c> --placeholder [--wpm 200]	API コールなしで、無音の音声と合成タイミングを生成します
stills <c> <秒>…	指定された秒数のフレームを取得し、out/ にコンタクトシートとして出力します。内容を確認します
studio <c>	Remotion Studio でライブプレビューを開きます（ユーザー向け）
render <c> [--blur]	60 fps の mp4 を out/ に出力します。--blur は 240 fps でレンダリングし、60 fps に平均化することでモーションブラーを適用します（約4倍遅い）
qa <c>	ライブネスチェック：停止フレームが 10% 未満、0.3秒以上の停止ランなし。FAIL の場合は終了コード 1 で終了し、各停止区間を特定します

ワークフロー

1. スクリプト。 new <c> を実行します。

   • ユーザーがスクリプトを提供した場合は、それをそのまま使用します（数字や記号は単語に修正するのみ）。
   • それ以外の場合は script-craft.md に従って script.txt を作成します：デフォルトでは日常的な物体形式（270〜320語）、製品やネットワークの場合はシステム形式。チェックリストを実行します。
   • レビューモード：承認のために停止します。

2. 音声。 voice <c> を実行し、表示された wpm を確認します（目標は190〜215。ずれている場合は、提案された --speed を指定して再実行します）。

   • 音声は --voice-id、次に FISH_VOICE_ID、最後に Fish のデフォルトが使用されます。クローンボイスの ID も同様に機能します。
   • モデルは --model、次に FISH_MODEL、最後に s2.1-pro が使用されます。
   • script.txt ではなく words.ts を基準に作成します。 音声は数字を読み上げるため、TL.at() やキャプションのフレーズは実際の発話単語と一致する必要があります。

3. ストーリーボード（storyboard.md）。 最初に World セクションを記入し、その後ビートごとに1行ずつ記入します。ビートのメタファーを考案するには、視聴者が何を見るかを考えます：

   • 拡大： 断面図や展開図。
   • X線： 物体の内部。
   • 時間を遅く： 進行する波、切り替わる部品。
   • 測定： 上昇または下降する表示値。

   「想像」のシナリオは「外出先の世界」となり、各メカニズムビートはホーム図に戻ります。ストーリーボードのチェックを実行します。

   • レビューモード：承認のために停止します。

4. ビルド。 ストーリーボードの各ショットに対応するシーンファイルを scenes/ に作成し、それぞれを composition.tsx に追加します。

   • 各シーンは t の純関数であり、自身の時間範囲外では null を返します。
   • タイミング： すべてのイベントは TL.at("exact words") に連動させます。生の秒数は使用しません。
   • 連続性： 同じ図を共有するビートは、1つのカメラパス（A4）を持つ1つのシーンにまとめます。
   • 移動： 各シーンは移動しながら登場し、前のシーンの終了と重なります（A2）。
   • SVG ID にはシーンごとにプレフィックスを付けます。

5. 反復。 各ショットのキーワードの時点で stills を実行し、クラフトレール A と B に照らして確認します。次に render と qa を実行します。FROZEN と判定された区間は、そのショット内で動きのキャリア（A1b）を与えて修正します。captions.ts のフレーズは手動で作成します：各フレーズに1つずつ、発話時にポップするキー名詞（アンバー色でハイライト）を設定します。

6. 納品。 最終的な render は qa に合格する必要があります（ユーザーが最大限の品質を求める場合は --blur を使用）。ユーザーに以下を提供します：

   • mp4 のパス
   • スクリプト
   • ストーリーボードのビートごとの1行要約
   • まだ実際のテイクが必要なプレースホルダー音声がある場合はその情報

レッドフラグ：停止して修正

考え	ルール
「このビートのために新しい設定をすれば新鮮さが保たれる」	C1：ホーム図1つ＋外出先の世界は1〜2つ。数を数える
「決定的な瞬間に完全に静止してサスペンスを演出する」	A1c：被写体は止めても、カメラと環境は動かし続ける
「決定的な瞬間に音楽、グレイン、またはドロップを追加する」	D、B8：音声のみ。グレインなし。奥行きは照明で表現する
「フェードイン」／「次のシーンにクロスフェード」	A2：移動によって登場、退場、トランジションを行う
「グローバルドリフトで動きを保つ」	A1b：各ショットには 10〜60 px/s の中程度の動きを持つ要素が必要
「このビートのためにカメラを近づける」（同じ図の場合）	A4：1つの世界、1つのカメラ。キーフレームを引き継ぐ
「均一な照明で問題ない、図だから」	B1：暗がりへの減衰、リムライト、ビネット
「作動時に全体を色味で統一する」	B4：原因から伝播させ、前面と流れを作る
「物体は長方形で十分」	B2：1回の解剖パス。引き出したときに何が見えるかを考えて構築する
「問題なさそうなので、qa はスキップ」	E：qa は PASS しなければならない。人間の目は停止を見逃す