explainer - 解説動画生成スキルは何をしますか？

スペックファイルにシーンを定義します。スクリプト群が素材のキャプチャ、ナレーションの音声生成、各シーンのHyperFramesサブコンポジション作成、そして出荷前の全検証を行います。

1. understand  対象のコード/ドキュメント/アプリを理解する
2. capture     scripts/capture.py      スクリーンショット、要素ボックス、録画、秘匿処理
3. spec        あなたが explainer.json を書く（シーン + ナレーション + ソース付きクレーム）
4. verify facts scripts/verify.py facts（ゲート: 検証通過まで発声不可）
5. build        scripts/build_explainer.py（音声、キャプション、シーン; デフォルトはキャラ無し）
6. verify       scripts/verify.py all（アセット、ビルド、レンダリング、音声）- クリーンになるまでループ
7. render       scripts/render.py

パスはこのパッケージのルートを基準とします: .claude-plugin/ を含むフォルダ、このファイルから2階層上（シンボリックリンクは事前に解決）。公開HyperFramesスキル（hyperframes、hyperframes-cli、追加で hyperframes-registry、media-use）が必要です。生成されたコンポジションを手動編集する前に hyperframes を一度読んでください。

0. 事前チェック（常に最初に実行）

python3 scripts/setup.py doctor を実行します（--json を追加して解析可能に）。すべての依存関係、その用途、このマシン用の正確なインストールコマンドを一覧表示し、必須項目が不足している場合は終了コード1で終了します。

必須不足（ffmpeg、Node.js 18+、HyperFramesスキル、ElevenLabsキーまたは設定された音声用の say）: それぞれの用途を1行で説明し、表示されたコマンドを提案します。ユーザーが承諾した場合のみ実行します。APIキーを自分で入力したり尋ねたりせず、ユーザーにシェルで ELEVENLABS_API_KEY をエクスポートするよう伝えてください。
任意不足: 一度だけ提案し、それぞれで何が可能になるかを説明します。Playwrightは要素ズームボックスと全ページショットを含むWebキャプチャを提供、tesseract（OCR）はスクリーンショットのシークレットスキャンを提供、ASR（mlx-whisper / openai-whisper）は音声チェックと正確な単語タイミングを提供します。ユーザーが辞退した場合はスキップし、該当するチェックは手動の review ステップになります。
HyperFramesスキル（hyperframes、hyperframes-cli、hyperframes-registry、media-use）: 不足している場合、npx hyperframes skills を推奨します。コンポジションのビルドや編集を行う前に hyperframes（レンダリング問題の場合は hyperframes-cli）を読んでください。

セットアップ（初回実行時、またはユーザーが何かを変更したい場合）

python3 scripts/setup.py show で現在の設定を表示します。設定がない場合、ユーザーにインタビュー（一度に1つの短い質問、デフォルト値を提示）して書き込みます。

質問	フラグ	オプション
どの機能？	`--features`	`explainer` 単体（キャラクターファイル不要）、または `character,explainer`（プレゼンター有効）
ナレーション言語	`--language`	ISOコード（`en`、`es`...）: 明確な `say` 音声を選択し、ASRに期待値を伝える
ナレーション音声	`--narration-voice`	`voice`（設定されたプロバイダー）、`say`（無料、macOS）、`none`（キャプションのみ）
音声プロバイダー	`--voice`	`elevenlabs`（環境変数 `ELEVENLABS_API_KEY` + `--voice-id`）、`say`、`none`
クレジット上限	`--max-chars`、`--max-seconds`、`--daily-credit-cap`	ユーザーの数値
レンダリング	`--render`	`local`、`cloud`、`preview`
サイズ	`--size`	`1080x1920`（デフォルト）、`1920x1080`、`1080x1080`

python3 scripts/setup.py init --features explainer --voice say --render local --yes

init は最初に doctor を実行し、同じインストールを提案します。設定が既に存在する場合は上書き前に確認します（非対話的に実行する場合は --force を渡します）。setup.py voices --lang <code> で言語に対応するmacOS音声とユーザーのElevenLabs音声を一覧表示します。--say-voice "<name>" で選択します。APIキーを尋ねたり、表示したり、書き込んだりしないでください。

1. 理解してからスクリプト作成

最初にソースから事実を取得します: コード、PR、ドキュメント、またはアプリを読んでください。間違った解説動画は無いより悪いです。詳細の前に全体像を示し、実際のケース（実際の名前、実際の値）を1つ説明し、各シーンは単一のアイデアに留めてください。
全体の長さ（styles.explainer.max_seconds 以下）: 3〜5シーン、各約6〜12秒 + クロージングタイトル。TTSは約2.4語/秒で読み上げます: シーンのナレーションは約25語以下に抑えてください。

動画のスタイルを選択

パッケージはニュートラルなデフォルトのみを提供します。トピック、視聴者、ユーザーのブランドや好みに基づいて動画ごとにスタイルを選択し、重要な場合（ブランド、公開チャンネル、シリーズ）はユーザーに尋ねてください。前の動画の外観を習慣的に繰り返さないでください。スペックの style ブロックに記述します:

キー	値
palette	`background`、`panel`、`ink`、`muted`、`accent`、`highlight`（CSSカラー; テキストのコントラスト比は4.5:1以上を維持）
typography	`font`、`mono`（HyperFramesバンドルフォント）、`title_scale`（0.6〜1.6）
layout	`align`（`left`、`center`）、`radius`（0-60）、`background_style`（`solid`、`gradient`）
motion	`motion`（`calm`、`normal`、`lively`）: すべての動作の継続時間とイージング
captions	`caption_style`（`box`、`outline`、`plain`、`none`）、`caption_position`（`bottom`、`top`）

設定内の brand キット（同じキー）は、キーごとにあなたの選択を上書きします。プレゼンターのセットは、ブロックに独自の style がない限り、動画の背景に従います（talking-clip 参照）。

2. 素材をキャプチャ

python3 scripts/capture.py url http://localhost:3000/login --name login
python3 scripts/capture.py url http://localhost:3000/login --name login --box "#submit"   # Playwrightが必要
python3 scripts/capture.py screen --name settings --interactive
python3 scripts/capture.py record --name signup --seconds 12          # macOS
python3 scripts/capture.py add --name diagram --file ./docs/arch.png
python3 scripts/capture.py redact --name login --box 820,410,360,48   # または --blur
python3 scripts/capture.py list

url はPlaywrightがインストールされている場合に使用します（--box と --full-page に必要）。なければヘッドレスChromeを使用します。Playwrightがない場合、フォーカスボックスはPNGから読み取ったピクセル矩形 [x, y, w, h]（デフォルトスケールのCSSピクセルの2倍）として指定します。Playwrightが仮想環境にある場合は、そのインタープリターでスクリプトを実行してください（.venv/bin/python scripts/capture.py ...）。--box は要素のボックスを画像ピクセル単位で記録し、シーンでそこに直接ズームできるようにします。デフォルト --scale 2 はズーム時にテキストをシャープに保ちます。
ストーリーを伝える最小の領域をキャプチャしてください。フルデスクトップをスマートフォンフレームに縮めると読めなくなります。フォーカスボックスを使用してズームしてください。
単一ショットではなくプロジェクト全体としてのWebサイト: npx hyperframes capture <url>（hyperframes-cli）。

3. スペックを書く

examples/explainer/explainer.json は完全で動作する例です。スペックは素材のルートに配置してください。それが参照するコードファイルとキャプチャはスペックのフォルダ内にある必要があります。シーンタイプ:

type	必須	表示内容
`screen`	`capture`、オプションで `focus: [{"box": "#sel" または [x,y,w,h], "label": "...", "at": s}]`	スクリーンショット、次に各ボックスへのカメラ移動（ハイライトとラベル付き）
`recording`	`capture`（動画）、オプションで `focus`	画面録画（ミュート）、同じカメラ移動とラベル
`code`	`file`、`lines: "a-b"`（24行以下、各行約49文字以下、縦方向）、`highlight: [{"lines": [a, b], "at": s}]`	カード上のコード、行が出現、キーラインにバンド
`diagram`	`nodes: [{"id","label","sub"?,"highlight"?}]`、`edges: [[a, b]]`、オプションで `flow: [ids]`	ボックスと矢印が構築され、`flow` に沿ってトークンが移動
`title`	`text`、オプションで `sub`、`dur`	クロージングまたはセクションカード

モーション、任意のシーンで（オプション; 色とタイミングはスタイルから取得するので、ビデオごとに他のルックと同様に変化させてください）:

キー	説明
`callouts: [{"type": "circle" または "arrow", "box": [x,y,w,h] または "#sel", "at": s, "note": "..."}]`	手描きのループまたは矢印が描画される; 画面/録画シーンでは画像ピクセル、それ以外ではフレームピクセル
`kinetic: [{"text", "at", "dur", "y"?, "from"?}]`	強調のために単語が勢いよく飛び込む; 控えめに使用（動画あたり1つまたは2つ）
`counter: {"to", "from"?, "at", "dur", "prefix"?, "suffix"?, "label"?}`	正確な値に到達するカウントアップ
トップレベルの `transition: "wipe" または "fade"`	各カットでのトランジション（デフォルト `none`）

これらはレジストリアイテム count-up、caption-kinetic-slam、hw-callout-circle、hw-arrow に従います（/hyperframes-registry 参照）。style.hand_font: "Caveat" で npx hyperframes add を使用してその手書きフォントを取得します。すべての動画ですべての機能を使うのではなく、ストーリーに必要なものを選択してください。

ナレーションのあるすべてのシーンには claims が必要です: 各技術的記述に source（スペックからの相対パス path:lines、capture:<name>、https://...、doc:<name>）と、そのソースに対して確認済みであることを示す status: "supported" を持たせます。"claims": [] はナレーションが技術的クレームを行わないことを意味します。未サポートのクレームは修正されるか削除され、決して音声化されません。

デフォルトではキャラクターなし。 解説動画はナレーション、キャプション、ビジュアルです。ユーザーが明示的に要求した場合、または価値が追加されると判断した場合（ホスト付きシリーズ、フレンドリーなオンボーディング）にのみプレゼンターとしてキャラクターを追加し、その理由をユーザーに伝えてください。次に presenter ブロック（intro / outro、それぞれ {"text", "plan"?, "mood"?, "style"?, "claims"}; プランはtalking-clip形式に従う）を追加し、--presenter 付きでビルドします。また features.character も必要です。プレゼンターシーンもキャプションを取得します（スペックが "captions": false を設定しない限り）。examples/explainer/explainer-with-presenter.json が例です。

4-5. 事実ゲート、次にビルド

python3 scripts/verify.py facts --spec explainer.json
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer --estimate
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer [--confirm] [--presenter]

--estimate は長さとElevenLabsクレジットを表示します。支出前にユーザーに伝え、その後 --confirm でビルドします。ビルダーは事実ゲートも実行し、失敗した場合は停止します。キャプションはスクリプトの実際の単語（大文字小文字、句読点、数字）をElevenLabsのアライメント、ASR、または推定値からタイミングを取って表示します。

6. 検証（必須ループ）

python3 scripts/render.py out/explainer --out out/explainer.mp4 --quality draft
python3 scripts/verify.py all --project out/explainer --spec explainer.json --video out/explainer.mp4

ステージ	合格条件	失敗時
facts	すべてのナレーション付きクレームが既存のソースを持ち、ステータスが `supported`	ソースを確認; クレームを修正または削除
assets	キャプチャとコードが出力サイズで判読可能; OCR（tesseract）/テキストスキャンでメール、キー、トークン、カード番号を検出しない	フォーカスボックスを追加するか、より小さく再キャプチャ; `capture.py redact`; コード内のシークレットをプレースホルダーに置き換え
build	`npx hyperframes check --json` にエラーや警告がない（`verify.ignore_rules` を除く）	スペックまたは生成されたコンポジションを修正
render	コンタクトシート（開始、各シーンチェンジ、シーン中間、終了）を確認: あふれ、重なり、途切れ、判読不能なテキストがない; ビジュアルがナレーションと一致	修正、再ビルド、再レンダリング
audio	レンダリングされた音声のASRがスクリプトと一致（`verify.min_asr_similarity`）し、時間制限内である	音声を再生成するか短縮

ループの進め方:

verify.py all を実行します。各実行が1回のイテレーションとしてカウントされます（<project>/.verify/state.json に記録）。
render は常に最初は review として戻ります: リストされたコンタクトシートを開き、すべてのフレームを確認し、確認内容を記録します: python3 scripts/verify.py mark render pass --project out/explainer --note "<確認した内容>"（または fail、その後修正）。マークはそれらの正確なファイルに紐付けられます。再ビルドすると無効になります。
OCRまたはASRがインストールされていない場合、assets / audio も review になります: 目視または聴覚で確認し、レポートでその旨を伝えてください。
失敗したものを修正し、再ビルドまたは再レンダリングし、再度 verify.py all を実行します。終了コード0 = 出荷可能。
イテレーション数が verify.max_iterations（デフォルト3）に達すると、終了コード2で終了します: 停止し、まだ失敗しているものをユーザーに伝えてください。問題を黙って出荷しないでください。大きな変更後は .verify/state.json を削除してカウントをリセットしてください。

VERIFY.md に数値が表示されます: OCRスキャン画像数とヒット数、ASR類似度（聞き取られた単語と期待された単語）、制限に対する時間。報告する際はこれらを引用してください。最後のキャプションが読みやすいようにシーンは自動的に長くなります。line_unread 警告が残る場合は、そのシーンに長い min_dur を設定してください。

スクリプトを実行するときは、ユーザーの通常の HOME を維持してください: 一時的な HOME だとnpx、Playwright、whisperがすべてを再ダウンロードし、gh/npx の認証が壊れます。

数字、略語、外国語での音声ミスマッチ: 設定で language を設定し、ナレーション内のそれらの単語を発音どおりに書いてください（"fifteen"、"A P I"）。プロジェクト内の VERIFY.md がチェックリストレポートです。動画を引き渡す際にそのサマリーを含めてください。

7. レンダリング

python3 scripts/render.py out/explainer --out out/explainer.mp4 は render.backend（local、cloud、preview）を使用します。render.max_mb はアップロード制限に合わせて再エンコードします。mp4やwavファイルをコミットしないでください。

explainer - 解説動画生成スキル