talking-clip は何をしますか？
クリップは4つのステップで構成されます：台詞作成、音声生成、演技計画、構築とレンダリング。 出力：HyperFramesプロジェクトとMP4ファイル（デフォルトは1080x1920の縦長）。
1. 台詞 あなたが書く、キャラクターの声で
2. 音声 scripts/tts.py (ElevenLabsはクレジット消費；sayとnoneは無料)
3. 計画 あなたがplan.jsonを書く (単語ごとのジェスチャーと表情)
4. 動画 scripts/build_clip.py -> scripts/verify.py -> scripts/render.py
パスはこのパッケージのルートを基準とします：.claude-plugin/ を含むフォルダ（このファイルの2階層上、シンボリックリンクは解決済み）。公開HyperFramesスキル（hyperframes、hyperframes-cli）が必要です：手動でコンポジションを編集する前に 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回に1つずつ短い質問、デフォルト値を提示）し、フラグを使用して書き込みます：
| 質問 | フラグ | オプション |
|---|---|---|
| どのパーツ？ | --features | character、explainer、または両方 |
| どのキャラクター？ | --character | バンドルサンプル（pkg:characters/host/character.json）またはユーザーのパス（絶対パスで保存） |
| ナレーション言語 | --language | ISOコード；say の場合、適切な音声が選択される（setup.py voices --lang <code> で一覧表示、--say-voice で上書き可） |
| どの音声？ | --voice | elevenlabs（ELEVENLABS_API_KEY 内のキー、--voice-id）、say（macOS、無料）、none |
| クレジットガード（ElevenLabs） | --max-chars、--max-seconds、--daily-credit-cap | ユーザーが選択する数値；空欄 = ガードなし |
| レンダリング方法？ | --render | local（無料、このマシン）、cloud（HyperFramesクラウド、npx hyperframes auth login が必要）、preview（Studioのみ） |
| サイズ | --size | 1080x1920、1920x1080、1080x1080 |
python3 scripts/setup.py init --features character --voice say --render local --yes
init は最初にdoctorを実行し、同じインストールを提案します。すでに設定が存在する場合、上書き前に確認を求めます。非対話モードの場合は --force が必要です。
ユーザー独自のキャラクター：python3 scripts/setup.py new-character --name "<name>" --out ./characters/<name> --activate でサンプルをコピーしてアクティブにします（2回目の init は不要）。その後、表示されるキーを埋めるのを手伝ってください：description、personality、speaking_style.rules、rig.colors（またはスプライト）、expressions / poses / gestures、set、voice_moods。
APIキーを尋ねたり、表示したり、書き込んだりしないでください。ELEVENLABS_API_KEY が不足している場合、ユーザーにシェルでエクスポートするよう指示します。設定スキーマは config/config.schema.json にあります。キャラクターファイルの形式はREADME（「あなた独自のキャラクター」）にあります。
このクリップのスタイルを選ぶ
固定の見た目はありません。クリップごとに、トピック、視聴者、ユーザーのブランドや好みに合わせてスタイルを選びます：セット（{"type": "color"|"gradient"|"image", ...}）、フレーミング（close、medium、wide）、モーション強度（calm、normal、lively）。選択が重要な場合（例：ブランド、公開チャンネル、シリーズ向けのクリップ）はユーザーに尋ねます。前回のクリップと繰り返しにならないよう、スタイルを変えてください。設定に brand キットがある場合、その background があなたの選択より優先されます。ファイルに書き込み、--style で渡します：
{"set": {"type": "gradient", "colors": ["#FFF4E6", "#FFD9B3"]}, "framing": "medium", "motion": "lively"}
台詞についても同様です：キャラクターの個性の範囲内で視聴者に合わせたトーンを選び、クリップ間で同じオープニングやクロージングラインを再利用しないでください。
1. 台詞を書く
設定（character キー）で指定されたキャラクターファイルを読んでください：personality と speaking_style.rules が声のガイドラインです。これらに従ってください。ただし、ユーザーの要求がこれらと矛盾する場合はユーザー要求を優先します。
- 長さ：最大
styles.talking_clip.max_seconds以内。speaking_style.chars_per_second（約14）で20秒のクリップなら約260文字以内。1つのアイデア、1つのクロージングライン。 - 言語：ユーザーの言語（別途指定がない限り）。
- ElevenLabs v3以降のモデル（オーディオタグ対応）は、英語の感情タグを角括弧内で対象単語の前に挿入することで解釈します：
[excited]、[calm]、[whispers]、[laughs]、[pause]。sayとnoneはこれらを無視します（削除されます）。代わりにジェスチャーで演技します。
2. 音声を作成する
python3 scripts/tts.py estimate --text "<line>" --max-seconds 20
python3 scripts/tts.py speak --text "<line>" --out out/voice.wav [--mood excited] [--confirm]
- ElevenLabs：必ず最初に
estimateを実行し、ユーザーにコストを伝えます。speakは--confirmなしでは拒否し、ユーザーが設定したガード（最大文字数、最大秒数、1日あたりのクレジット上限）を超える場合も拒否します。--takes 2で代替案を作成します。単語のタイミングはout/voice.wav.words.jsonに保存されます。 --moodはキャラクターのvoice_moods（ElevenLabs設定＋オプションのffmpegフィルター）からムードを選択します。say/none：無料です。noneの場合は音声がありません。代わりに--textをビルダーに渡します。
3. 演技を計画する
python3 scripts/timings.py out/voice.wav --text "<line>" で単語の開始時間を取得します。plan.json を書きます：
{"expression": "neutral",
"events": [{"t": 0.0, "gesture": "hello"},
{"t": 2.1, "gesture": "explain", "dur": 2.5},
{"t": 5.0, "expression": "happy"},
{"t": 6.2, "gesture": "wink"}]}
gestureとexpressionのIDはキャラクターファイル（gestures、expressions）から取得します。各ジェスチャーには説明と標準のdurがあります。計画前に読んでください。- 口、まばたき、呼吸、アイドル時の揺れは自動処理されます。あなたは演技のビートだけを配置します。
- 強いジェスチャーは、対応する単語の0.2～0.3秒前に配置します。1ビートにつき1つのリアクション。同じ秒に2つのジェスチャーを入れないでください。落ち着いた、保持されたジェスチャーで終了します（自動的に最後まで保持されます）。
4. 構築、確認、レンダリング
python3 scripts/build_clip.py --audio out/voice.wav --plan out/plan.json --style out/style.json --project out/clip
python3 scripts/render.py out/clip --out out/clip.mp4 --quality draft
python3 scripts/verify.py all --project out/clip --text "<line>" --video out/clip.mp4
確認は必須です（詳細はexplainerスキルの「確認」セクションを参照、同じループ）：build はエラーなしで完了する必要があります。render はコンタクトシートを生成するので、必ず確認してください（口が動いているか、ジェスチャーが計画通りか、何も切れていないか）。audio はASRで単語をチェックし、長さ制限を確認します。問題があれば修正し、失敗した段階から再実行します。各 verify.py all の実行が1イテレーションです。verify.max_iterations に達すると終了コード2で終了し、ユーザーに何がまだ失敗しているかを伝え、出荷しません。render は、あなたがコンタクトシートを確認し、verify.py mark render pass|fail --project out/clip --note "..." で記録するまで review 状態のままです。その後、再度 verify.py all を実行します（再構築するとマークは無効になります）。
その後、設定されたバックエンドで最終レンダリングします：python3 scripts/render.py out/clip --out out/clip.mp4（render.max_mb はアップロード制限に合わせて再エンコードします）。mp4やwavファイルは決してコミットしないでください。