mohamed-stifi/explainer-short

Explainer Short (アイデア → 完成動画)

リクエストごとに、以下の7ステップを順番に、1回だけ実行して、1本の完成動画を生成します。 各ステップにはコマンド、出力、停止条件があります。追加のステップを独自に作成しないでください。

パス: SKILL = このファイルが置かれているフォルダ。STUDIO = 動画ワークスペース (デフォルト: 現在のプロジェクト内の ./explainer-studio。既に存在する場合は再利用します)。SLUG = 動画のケバブケースID (例: how-https-works)。

ハードリミット (処理を短く、低コストに保つため)

• ユーザーに質問するのは最大1回まで。しかも、トピックがまったくない場合のみ。そうでなければ、以下のデフォルトを使って自分で判断し（長さ、フォーマット、ブランド）、最終応答で選択内容を記述してください。
• check.sh → 修正 → check.sh は最大 2回の修正サイクルまで。その後レンダリングし、残っている問題があれば応答にリストしてください。
• 音声の再生成は最大 2回まで（長さ調整または発音ミスの単語の修正のみ）。
• src/kit/ は編集しないでください（アイコンの追加を除く）。他のパッケージやツールをインストールしないでください。
• template/src/videos/example/ は1回だけ読んでください（これがリファレンス実装です）。キットのソースは読まないでください。references/kit-api.md にAPIが文書化されています。

「ショート」「リール」「解説ショート」 = 縦型フォーマットのことで、長さモードのことではありません。「ショート」長さモードは、ユーザーが「手短に」「とても短く」「1分未満」と明示的に要求した場合、または秒数を指定した場合にのみ使用してください。

デフォルト: 長さ 95–120 秒 (300–370 ワード。「ショート」= 55–70 秒、「フル」= リファレンス長 160–175 秒 — references/script-guide.md 参照)、音声 am_michael 速度 1.18、ブランド = ユーザーの名前/チャンネル（既知の場合）、そうでなければ "YourBrand"。 スタイルルールは23本のリファレンス動画の測定に基づいています。エビデンスは references/style-evidence/ にあります（人間のみ — 読む必要はありません）。

ステップ1 — セットアップ (マシンごとに1回、初回約3分、2回目以降約2秒)

bash SKILL/scripts/setup.sh STUDIO

停止条件: 最終行が READY: …。MISSING TOOLS と表示された場合は、インストールが必要なものを正確にユーザーに伝えて停止してください。 （音声モデルファイルがすでにどこかに存在する場合は、最初に KOKORO_MODELS=<dir> を設定すると、340 MBのダウンロードをスキップできます。）

ステップ2 — 企画 (まだコードは書かない)

references/script-guide.md を読んでください。次に、STUDIO/src/videos/SLUG/plan.md を書きます（≤ 25行。ステップ3でフォルダが作成されます):

1. タイトル: 以下のフォーマットのいずれか (How X works · X vs Y · Interview: … · System design: how does X)。
2. 実行例: 名前のある人物 + 具体的な製品/入力/値を最初から最後まで使用。
3. ビート (セクション): ID付き。6～9個。それぞれが1つのアイデア。
4. ステージ: references/visual-guide.md を読み、セクションごとに1行記述: section → added / moved / focus (spotlight ids) / leaves (「ステージの計画」の項を参照)。3～4つのアクセントを選び、それぞれを1つの要素に結びつけます。

ステップ3 — スクリプト

bash SKILL/scripts/new_video.sh STUDIO SLUG

STUDIO/src/videos/SLUG/script.json を記述します（フォーマット: サンプルの script.json を参照）。破壊的なルール:

• sections[].id はユニークでシンプルに (hook, scenario, mechanism, …)。最後のセクションはCTA。
• 数字や記号は表示したい形で記述し、発音される形に pronounce でマッピングします ("429": "four twenty nine", "API": "A P I", "SQL": "sequel", "k8s": "kubernetes")。
• 文は18ワード以内。. ! ? のみで文を終了（各文は個別に合成されます）。 次のステップに進む前に、script-guide.md 末尾のルールリストに基づいて自己チェックを行ってください。

ステップ4 — 音声

bash SKILL/scripts/voice.sh STUDIO SLUG

各セクションの開始/終了時刻、Done: <sec>s, <words> words, <wpm> wpm を表示します。停止条件: ターゲットの ±15 % 以内の長さ。長すぎる場合は、速度ではなく文を削減して、もう1回実行します。

ステップ5 — ビジュアル

references/kit-api.md とサンプル (STUDIO/src/videos/example/Video.tsx + stages/*.tsx) を読みます。 STUDIO/src/videos/SLUG/Video.tsx + 各ステージごとに stages/ 内のファイル1つを記述します。必須:

• すべての要素の at は cue(section, word) または sec(section).from から取得 — ハードコードされた秒数は不可。
• 1つの連続したキャンバス: 要素は持続し、移動し、暗くなり、再利用されます。ステージ間以外で全画面クリアは禁止。
• ナレーションの約3秒ごとに、何かが視覚的に変化すること（新しい要素、ハイライト、状態変更、移動）。
• フォーカス = Spotlight計画に基づく <Canvas focus>（その他を暗く） — このスタイルの主要な手法。
• 字幕なし。キャプション (Takeaway) は7ワード以内、動画1本あたり2～6個。
• コンテンツはセーフゾーン内に収める (x 60–1020, y 280–1480; タイトル約150; キャプションは図のすぐ下)。
• 横幅いっぱいに使用: メインパネルは幅960（または2×465）。26 px未満のものは不可。

ステップ6 — チェック (最大2回の修正サイクル)

check.sh と render.sh はローカルサーバー + ヘッドレスChromeを起動します。サンドボックス化されたエージェントでは、両方のコマンドをサンドボックスの外で実行してください。環境がまったく実行できない場合（No available ports found、Chromeが起動しない、サンドボックス外の呼び出しが拒否される）: ステップ5で停止し、ユーザーに check.sh と render.sh を自分で実行するように伝えてください（両方の完全なコマンドを提示）。回避策は試さないでください。

bash SKILL/scripts/check.sh STUDIO SLUG          # オプションの第3引数: "12.5,30,41" = 追加で検査する秒数

各 cue() を音声タイミングに対して lint し（即時）、型チェックを行い、セクションごとに約3フレーム＋エンドカードをレンダリングし、out/SLUG/check/sheet.jpg (+ NN.jpg 個別フレーム) を書き出します。シート画像（および2～3枚の個別フレームをフルサイズで）を確認してください。以下のチェックに失敗したものだけを修正します:

チェック	失敗条件
overlap	テキスト/ボックスが衝突する、または画面端で切れる
scale	図が横幅の80%未満である、または忙しいセクションでy 900–1400が空いている。540px幅のフレームで目を細めて見る必要があるテキスト
readability	約28px未満のラベル、またはテキストが込み入った領域の上にある
sync	要素が対応するワードより前に出現する、またはナレーションが何かを話している間に空/古いキャンバスが表示される
continuity	ストーリーが続いているのに、前のステージと無関係に見える（すべて置き換わっている）
focus	話されている要素がハイライトされていない (Focus / amber / dim others)
density	9個を超える可視要素があるフレーム、またはtakeawayテキストが2行を超える

型エラー / cue not found エラーは修正方法を表示します（有効なワードのリスト）。修正して再実行してください。

ステップ7 — レンダリング + 納品

bash SKILL/scripts/render.sh STUDIO SLUG

（ヘッドレスChromeがサンドボックスでブロックされる場合は、サンドボックス外でこのコマンドを再実行してください。） その後、STUDIO/out/SLUG/upload.md を記述します: タイトル（= 動画タイトル、≤ 60文字、末尾に絵文字1つ許可）、2文の説明、5つのハッシュタグ、および「確認すべき事実」リスト（記憶で述べたすべての数字/主張）。

最終応答 (簡潔に): MP4パス、長さ、SRT/カバー/upload.mdのパス、あなたが行った選択（フォーマット、長さ、実行例）、および残っている既知の問題。その後停止します。

トラブルシューティング

症状	修正
cue not found: "x" #1 in section "y". Words: …	表示されたリスト内の単語を使用するか、正しいセクションを使用する
単語の発音が間違っている	pronounce に追加し、ステップ4を再実行
Cannot find module './timing.json'	このSLUGに対してステップ4を実行していない
composition SLUG not found	voice.sh を実行（動画を登録します）
Chrome / SIGABRT / ENOTFOUND remotion.media / No available ports found	サンドボックスがブラウザ/ポートをブロック: コマンドをサンドボックス外で実行（ステップ6を参照）
failed to canonicalize path …/voice/.venv/bin/python3 またはその他のuv/venvエラー	STUDIO/voice/.venv を削除して setup.sh を再実行
フレームにテキストがパネルからはみ出して表示される	<El> の h を大きくする、行数を減らす、またはフォントを小さくする（≥ 26 px）
動画が長すぎる/短すぎる	スクリプトを編集（速度1.18で約3.1ワード/秒）、ステップ4を再実行