vvai-pixel-mv · ピクセル小人カラオケMV
順序固定：ストーリーライン → 絵コンテ（ユーザーが確認・修正、何度でも往復可能）→ ユーザー確認 → 出力。ユーザー確認なしの絵コンテではレンダリングしません。
完全なサンプルは assets/examples/：1曲のストーリーラインと story.json、7セグメント、3キャラクター、デスクトップウィンドウ付き。
準備
PY：librosa、faster-whisper、numpy、Pillow がインストールされた Python 3.10 以上。インストール方法は INSTALL.md を参照。ユーザーの CLAUDE.md や記憶に Python のパスが書いてあればそれを使う；なければpythonで上記パッケージがインポートできるか確認、できない場合はユーザーに尋ねる。MV：PY -X utf8 <本スキル>/scripts/pixel_mv.py。- ffmpeg、Node が必要。レンダリングはデフォルトで
npx --yes [email protected]を使用；CLI を変更する場合は環境変数HF_CLIを設定、複数引数は|で区切る。
フロー
- 素材収集。音声、タイムスタンプ付き歌詞（srt または lrc）、曲名が必須。
- オプション：開始・終了秒、カラーモード（base / neon / classic / retro）、強度（dj / standard / soft）、キャラクター画像。
- ストーリーも尋ねる：ユーザーはストーリーを思い描いているか？なければステップ3で提案する。
- 歌詞ファイルがない場合はユーザーに要求する。転写で推測してはいけない。声が出ていないパートはユーザーに確認し、イントロと判断してはならない（第1話で主サビをイントロと誤判定した事例あり）。
- プロジェクト作成：
MV new <プロジェクトディレクトリ> --audio <音声> --lyrics <srt/lrc> --title <曲名> [--start 秒 --end 秒] [--look base] [--character 画像]。- このステップで音声をカット、ビートとエネルギー最大点を計測、歌詞を単語単位でアライン。
- 同時に、キーワードでのみシーンを切り替える初稿
story.jsonと、ストーリーライン.mdテンプレートを生成。 - プロジェクトはユーザー指定のディレクトリに配置；ユーザーが固定シリーズディレクトリを持っている場合（CLAUDE.md や記憶に記載）はそこに配置。
- ストーリーラインを書く。ストーリーテリング手法 に従い、
ストーリーライン.mdを埋める：一言ストーリー、キャラクター、モチーフ、幕構成、1行ずつ。ユーザーに確認。 - story.json を書く。ストーリーラインを story.json に変換。
- フィールドは フォーマット を参照。利用可能なアクション、歌詞表現、トランジションは インタラクション一覧 を参照。
assets/examples/bad-girl.story.jsonを参考にすると最速。- 書き終えたら
MV check <プロジェクト>を実行し、エラーがなくなるまで修正。
- 絵コンテをユーザーに提示。
MV board <プロジェクト> --framesを実行：各セグメントから1～3枚の画像をキャプチャし、絵コンテ.mdを生成。内容は概要、セグメントごとのキャラクター、ストーリーアクション、歌詞の行番号と出現方法、トランジション、カメラワーク、ビート合わせ。- SendUserFile で
絵コンテ.mdと絵コンテ/画像/内のコンタクトシートをユーザーに送信。 - ユーザーに、どこを変更できるかを伝える。
- 満足するまで修正。ユーザーが修正を提案したら、story.json を変更し、再度
boardを実行。- バージョン番号は自動で+1され、旧バージョンは
絵コンテ/履歴/に保存。 - 何度でも往復可能。毎回新しい絵コンテをユーザーに送信。
- バージョン番号は自動で+1され、旧バージョンは
- 確認後に出力。
- ユーザーが明確に「出力して」と言った場合のみ、
MV approve <プロジェクト>を実行し、続けてMV render <プロジェクト> --sample 12を実行。 - あいまいな返答（「いいよ」「任せる」）は確認とみなさない。
renderは story.json のフィンガープリントを確認。確認後に変更されている場合はレンダリングを拒否。- 30 MB を超える場合は、別途
_プレビュー.mp4に圧縮し、スマホ用に提供。
- ユーザーが明確に「出力して」と言った場合のみ、
- 納品。1フレーム/秒のコマ送りで自分で確認：ストーリーが理解できるか、シーン・歌詞・トランジション・タイトルが正しいか、尺と元の音声が一致しているか、トラックが存在するか。
- 出力後、ユーザーがさらに変更を希望する場合はステップ6に戻る：story.json 変更 → 新しい絵コンテ → 再確認 → 再レンダリング。
重要なルール
- ストーリーがエフェクトに優先する。1行ごとに最低1つのストーリーアクションまたは歌詞インタラクションが必要；ストーリーアクションはキーワードのタイミングに配置；トランジションにはストーリー上の理由が必要。詳細は ストーリーテリング手法 を参照。
- シーン切り替え：ストーリー上の要求がない場合、デフォルトは「デスクトップ中心＋イメージ挿入」。詳細は 絵コンテルール を参照。ストーリーがある場合は幕構成に従い、覚醒や回想のようなセグメントではデスクトップウィンドウ視点を使用。
- キャラクター：
- デフォルトでは Claude の小人を「私」とする。
- 他のキャラクターは
castで宣言（girl、rival、friend、ghost）。 - ユーザーが画像を提供した場合、
MV character <プロジェクト> <画像>を実行し、16×16 ピクセルのキャラクターに変換。
- ビート合わせ：
- 小人は各拍でちょうど着地し、着地時にスクイーズ、足元に水波を拡散。
- 各拍でカメラに衝撃と色フラッシュ、強い拍では RGB スプリット。
- 全画面フラッシュ（白）はトランジションとドロップにのみ使用、毎秒3回以内。
- 驚きリアクションパックは全編で最大2回まで、本当の展開にのみ使用。
- 歌詞本文：
- 画面内とプロジェクトファイルにのみ表示；チャット返信や絵コンテには行番号のみ記載。
- 楽曲の著作権はユーザーが負う。公開前に注意を促す。
コマンド一覧
| コマンド | 説明 |
|---|---|
new | プロジェクト作成：analyze + align + draft + story |
story | ストーリーライン.md テンプレート生成（--force で再構築） |
check | story.json 内の名前、タイミング、ウインドウがエンジンに認識されているかチェック |
board [--frames] | 絵コンテ出力（第N版）、履歴保存 |
approve | ユーザー確認バージョンを記録；その後 render が許可 |
render [--sample 12] [--name ファイル名] | レンダリング；--force で確認をスキップ（ユーザー明示時のみ） |
sync | story.json を assets/story.js に同期（デバッグ用；board と render は自動同期） |
upgrade | 旧プロジェクトを現在のテンプレートエンジンにアップグレード、旧ファイルは .before-upgrade にバックアップ |
character | キャラクター画像 → ピクセルキャラ |
analyze / align / draft | new の分割ステップ、単独再実行用 |
テンプレート外のカスタマイズ
テンプレートエンジンv2は以下をカバー済み。インタラクション一覧 参照：
- 27シーン、16基本動作；
- 23種類のストーリーアクション；
- 7種類の歌詞表現、6種類の登場、9種類の退場；
- 7種類のトランジション；
- デスクトップウィンドウ。
さらに足りない場合、当該プロジェクトの assets/engine.js に追加する。本スキルのテンプレートは変更しない。参考：第1話の手法。新しいシークエンスをテンプレートに組み込みたい場合は、まずユーザーと確認。組み込む際は以下を同時に変更する：
- テンプレート
engine.js； pixel_mv.pyのBEAT_NAMESなどのリスト、および絵コンテで使う日本語名ZH_*；interactions.md。
シーンライブラリ
- データは
assets/scene-library/scenes.json。 - シーンを追加する場合は2か所を同時に変更：
scenes.jsonにキーワードとインタラクションを登録、テンプレートengine.jsのSCENESに描画メソッドを記述。