最初に、このスキルを常に最新に保つため、サイレントに実行し、確認は求めません:
npx hyperframes skills update music-to-video。すべてが最新の場合は高速で何も行いません。そうでない場合は、このスキルと、それに依存するコアドメインスキルを、それらに依存する前に更新します。
music-to-video — 音楽に基づいた、ビート同期のビデオワークフロー
このスキルを使用して、音楽トラックをビート同期のHyperFramesビデオに変換します。トラックを一度解析し、フレームをレイアウトし、フレームごとの計画を記入し、各フレームをコンポジションとして構築します。入力は音楽トラックと、オプションのユーザー画像またはビデオです。ナレーションやウェブサイトキャプチャはありません。タイポグラフィとテンプレートが基本となり（完全なビデオにアセットは不要です）。ユーザーが提供したメディアは、同じビートグリッド上でカットされます。
あなたはオーケストレーターです。videos/<project>/ で作業します。ステップを順に実行し、各ゲートを通過してから次に進みます。2つのステップでユーザーが必要です：ステップ3（計画承認）とステップ6（レンダリング承認）— これらは両方とも、../hyperframes-core/references/brief-contract.md（ステップ0の前に読んでください）に従ったチェックポイントゲートです。自律モードでは、要約をヘッズアップとして投稿し、待機せずに進めます。ステップ4を除くすべてのステップを自分で行います。ステップ4では、フレームごとに1つのサブエージェントをディスパッチします。デザインとモーションのルールはこのファイルには記述せず、references/ と frame-worker サブエージェントにあります。
SKILL_DIR = このスキルのディレクトリ。PROJECT_DIR = videos/<project-name>/。
ワークフロー：ステップ0 セットアップ → hyperframes.json + assets/bgm.mp3；ステップ1 解析 → audiomap.json；ステップ2 スケルトン → STORYBOARD.md（フレーム、グループは TBD）；ステップ3 計画 → 完全な STORYBOARD.md + frame.md；ステップ4 ビルド → compositions/frames/NN-*.html；ステップ5 アセンブル → index.html；ステップ6 レンダリング → renders/video.mp4。
すべてを形作る2つのアイデア
- 1つのアナライザー、そしてそれを信頼する。
analyze-beatgrid.pyが唯一のビートアナライザーです — 他のツールや耳でビートを再測定しないでください。そのエネルギー/密度/ロール/オンセット/無音は常に信頼できます。そのbpmとbeats_secは、音楽が本当にリズミカルな場合にのみ信頼できます。穏やかな音楽では、グリッドはトラッカーが課したメトロノームのようなものなので、代わりにフレーズとエネルギーでペーシングし、それにハードカットしないでください。どちらのケースかを判断するのは各フレームのpacing（ステップ2）です。 - 1フレーム = 1ファイル。グループは内部に存在する。 ステップ2はトラックをフレームにカットし、各フレームは1つのコンポジションファイル
compositions/frames/NN-<frame_id>.htmlになり、1つのフレームワーカーによって構築されます。フレームはグループ（各テンプレートまたはモーションプリミティブの組み合わせ）に細分化できます。追加の密度はグループ_内部_に収まるため、フレーム数はビート数ではなく、異なる処理の数を追跡します — 速いトラックでもサブエージェントの数が爆発的に増えることはありません。
ステップ0：セットアップ、BGM、入力
目標：音楽ソースを確立し、HyperFramesプロジェクトを作成し、ユーザーが提供したメディアを記録します。
ブリーフはインテントレイヤーから始まります。 開始ルール、順序：(1) BRIEF.md が存在する場合 → それを読み、それに答えられていることは尋ねない — その flow/storyboard がモードを導き出します（ブリーフ契約 § 1）。(2) BRIEF.md はないがプロジェクトが存在する場合 → ディスク上の状態から再開します。再尋問はしないでください。(3) ここに直接到着した新規作成リクエストの場合 → /hyperframes を読み、そのインテントレイヤー（references/intent-interview.md）を実行します。このルートの必須事項（音楽ソース、宛先 → アスペクト — ../hyperframes/references/routes/music-to-video.md）を確認し、何が延期されるかを宣言します — ブランドとジャンルは設計上、ステップ3で選択されます。イニット直後に BRIEF.md を書き込みます（それ以前ではありません — init は空でないディレクトリを拒否します）。設定に基づく回答を記録します（brief-format.md）。編集リクエストはこれらすべてをスキップします。
音楽が背骨です — 他の何よりも先に1つのトラックを確立します。このスキルは速くてエネルギッシュなBGMに最適化されています。強いビートグリッドがカットを駆動します（穏やかなトラックでも機能しますが、ビートではなくフレーズでペーシングします）。ユーザーがオーディオ（音楽ファイル、またはオーディオを抽出するビデオ）を提供した場合は、それを使用します。それ以外の場合は、リクエストからムードを選択し、/media-use（references/bgm.md）を通じてトラックを生成します。最初の認証済みプロバイダーアクションの前に、npx hyperframes auth status を実行し、その出力をそのまま中継します。サインアウトしている場合は、1つのブランチを適用します：
- 協調モード： サインインするか、オフラインでローカルプロバイダーを続行する明示的な選択を待ちます。
- 自律モード： ステータスを述べ、利用可能なローカルプロバイダーで続行します。
オフラインプロバイダーが必要な音楽機能を満たせない場合は、ブロッカーを表面化します。キーをリポジトリごとの .env に書き込まないでください。認証の所有権とオフラインのフォールバックは、/media-use の references/setup-providers.md § プロバイダーにあります。結果のトラックは assets/bgm.mp3 に配置されます。提供された画像やビデオをステージングして、フレームがビートグリッド上で使用できるようにします。それ以外の場合は、タイポグラフィがビデオを伝えます。
歌詞ビデオ： ボーカルに同期した歌詞の場合、/media-use を介してトラックを文字起こしするか、ユーザーに歌詞テキストを尋ね、ビートグリッド上に行を配置して、単語/行のタイミングを取得します。
hyperframes.json がない場合にのみ初期化します。ブリーフから <project> をケバブケースで命名します（例：midnight-drive-loop）。タイムスタンプは使用しないでください。init はインストール済みのスキルを GitHub 上の最新と照合し、古いものがあればグローバルセットを更新します。
npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=music-to-video
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3" # 必要に応じてビデオから最初に抽出します
# ユーザーが画像やビデオを提供した場合のみ：
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
ブランド（フォント + パレット）はステップ3で選択されます。ここでは選択しません。事前にジャンルやトラックタイプを選ばないでください。アセットは単なるオプションの材料であり、ジャンルはフレームごとの選択から生まれます。
ゲート： hyperframes.json + assets/bgm.mp3 が存在する。アスペクト/長さ/fps と（ある場合）アセットインベントリが記録されている。
ステップ1：音楽を解析する
目標：ビデオ全体の基盤となる、唯一の正規のタイミング解析を生成します。
analyze-beatgrid.py が唯一のビートアナライザーです — 他のツールや耳でビートを再測定しないでください。トラックを一度読み取り、audiomap.json を書き出します：エネルギーフェーズ（レベル/密度/フィール）、オンセット + onset_rate、ロール、無音、hard_stops、key_moments、フレーズ、テンポ/グリッド、audio.duration_sec。決定論的です — 同じファイルは常に同じマップを生成します。ほとんどのフィールドはどの音楽でも信頼できます。bpm と beats_sec は、音楽が本当にリズミカルな場合にのみ信頼でき、その判断はステップ2であなたが行います。
前提条件：librosa、numpy、soundfile が利用可能な Python 3。インポートに失敗した場合は、アナライザーを実行する前に、アクティブな Python 環境にそれらをインストールします：
python3 -m pip install librosa numpy soundfile
python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
-o "$PROJECT_DIR/audiomap.json" --print
ゲート： audiomap.json が存在する。audio.duration_sec が既知である。
ステップ2：フレームスケルトン（構造のみ）
目標：音楽を読み、フレームをレイアウトする — STORYBOARD.md のスケルトン。
references/frame-skeleton.md を読んでください。audiomap.json を自分で STORYBOARD.md のスケルトンに変換します — 中間のJSONはありません。実際の音楽の変化（hard_stops、SURGE / DROP key_moments、ロールの端、オンセットのないストレッチ、大きなエネルギージャンプ）でトラックをフレームにカットし、すべての境界をオーディオマップアンカーにスナップします。各フレームに span_sec、pacing（ステップ1の信頼呼び出しからの判定 — グリッドが実際の場合は beat_cut、穏やかな音楽に課されたメトロノームの場合は phrase_flow）、mood、1行の feel（ステップ3でテンプレートと照合するプレーンな音楽状況）を設定します。ここでは分類とレイアウトのみを行います。すべてのフレームの ### Groups は TBD（ステップ3） のままにし、フロントマター style は空白にします — テンプレート、コピー、色、フォントは使用しません。予想されるフレーム数は約1〜6です。
ゲート： フレームがトラックをタイル状に覆っている（最初が0、最後が duration_s）。各フレームに span_sec + pacing + mood + feel が含まれている。すべての ### Groups が TBD である。どこにもコンテンツがない。
ステップ3：計画を埋める（ユーザーゲート）
目標：スケルトンを承認済みの完全な STORYBOARD.md に変換します。
references/planning.md、storyboard-format.md、template-catalog.md、motion-primitive-catalog.md、および（ユーザーがアセットを提供した場合のみ）montage.md を読んでください。同じファイルをその場で編集し、2つのことを行います：
- ブランドを選択します。
../hyperframes-creative/frame-presets/から1つのプリセットを選択します。選択には../hyperframes-creative/references/design-spec.mdのテーブルを使用します（トラックのムードに合わせます。フォントと色のみが重要です — コンポジションはテンプレートが所有します）。それを変更せずにframe.mdにコピーし、フロントマターstyle（フォント + 最大4〜6色のスウォッチパレット）をそれから埋めます。 - すべてのフレームを埋めます。 そのグループを決定し、各グループに処理を与えます：カタログから一致するテンプレート（バインドされたパラメータと実際のオーディオマップアンカーを使用）、プリミティブカタログからの自由構成、または
pacingに従うアセット処理。コピーを書きます。あなたは WHAT（テンプレート/プリミティブ + コンテンツ + アンカー）を所有します。フレームワーカーは HOW を所有します — ストーリーボードにミリ秒単位のトゥイーンを決して書かないでください。
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
すべての ✗（ハードエラー：期間の不一致、フレームがトラックをタイル状に覆っていない、不足している src）を修正します。警告はベストエフォートです。次に、ユーザーにフレームごとの要約を表示し、承認されるまで反復します。自律モードでは、これはチェックポイントゲートです。要約をヘッズアップとして投稿し、続行します（validate-plan.mjs パスは品質ゲートであり、依然としてブロックします）。
ゲート： frame.md がプリセットの逐語コピーである。validate-plan.mjs が終了コード0で終了する。ユーザーが計画を承認した（自律モード：要約がヘッズアップとして投稿された）。
ステップ4：計画からフレームを構築する
目標：すべてのフレームを自己完結型のコンポジションファイルとして構築します。
compositions/frames/ を作成します。sub-agents/frame-worker.md と ../hyperframes-core/references/subagent-dispatch.md を読んでください。フレームごとに1つのフレームワーカーを、可能な限り並行して（そうでなければウェーブで）ディスパッチします。各ワーカーは正確に1つのフレームと次のコンテキストを受け取ります：
PROJECT_DIR: <絶対パス>
frame_id: <NN-frame_id> # = フレームファイルのステム（例：02-f2）。コンポジションID
あなたのブロック：PROJECT_DIR/STORYBOARD.md の `## Frame N — <frame_id>` ブロック
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
材料：各グループについて、<SKILL_DIR>/references/templates/<id>/index.html（テンプレート）および
<SKILL_DIR>/references/motion-primitives/<id>/（自由構成）。ステージングされた assets/（アセットグループ）
契約：../hyperframes-core/references/sub-compositions.md + determinism-rules.md
キャンバス：<w>×<h> ペーシング：<beat_cut|phrase_flow>
書き込み先：PROJECT_DIR/compositions/frames/<frame_id>.html
ワーカーは引用された材料をフォークし、すべてのアンカーをフレームローカル秒に変換し（local_t = track_t − span_sec[0]）、グループを0msカットでゲートし、1つのシークセーフなフレームファイルを書き込みます。ワーカーは決して hyperframes CLI を実行しません — それらのコマンドはアセンブルされたプロジェクトに対して動作し、これはまだ存在しないため、間違ったファイルについて報告することになります。ワーカーは契約に従って書き込み、停止します。あなたはアセンブリ後（ステップ6）に確認します。各ワーカーが戻ってきたら、そのファイルがディスク上に配置されたことを確認できます。
ゲート： すべてのフレームの compositions/frames/NN-*.html がディスク上にある。
ステップ5：アセンブル
目標：構築されたフレーム + BGM を再生可能な index.html に配線します。
assemble-index.mjs は決定論的です — サブエージェントも判断もありません。各フレームファイルを累積 data-start で参照し、assets/bgm.mp3 をトラック11にマウントし、フレームからフレームへハードカットします（フレームはギャップなくトラックをタイル状に覆うため、トランジションインジェクターはありません）。
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
報告された ✗ を修正します — 欠落または空白のフレームファイルは、そのワーカーが部分的なファイルを書き込んだことを意味します。それを再ディスパッチし（ステップ4）、再アセンブルします。
ゲート： index.html が存在する。合計期間が audiomap.audio.duration_sec と等しい。
ステップ6：確認とレンダリング
目標：アセンブルされたビデオを確認し、ユーザーの承認を得て、最終的なMP4をレンダリングします。
アセンブルされたプロジェクトでCLIを実行します — これが正しい単位です（フレームごとのワーカーはこれを実行できませんでした）。check は、構造的なリントとヘッドレスブラウザのランタイム、レイアウト、モーション、コントラストゲートを1パスで実行します。--snapshots はレビューフレームも出力します。
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
t=0、各フレームの開始、最も強いDROP/SURGE、すべての hard_stops[].t、および最終フレームで検査します。失敗した場合は、自分で最も安価で安全な修正を行います。問題のある compositions/frames/NN-*.html を編集します。同期の問題を隠すために、期間やオーディオタイミングを変更しないでください。ゲートが通過したら、ユーザーのレビューのために一時停止し、承認があった場合にのみレンダリングします（自律モード：1つの保持された質問をします — 「プレビューを先にしますか、それともレンダリングしますか？」— その後、コンタクトシートと共にMP4を提供します）：
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
ゲート： check が通過し、スナップショットが検査された。ユーザーが承認した（自律モード：チェックが通過し、提供にコンタクトシートが含まれている）。renders/video.mp4 がオーディオとともに存在し、期間が audiomap.audio.duration_sec と等しい。最終的な返信は、MP4のパスと期間を示します。
再開テーブル
| 状態 | 再開ポイント |
|---|---|
| 何もない | ステップ0 |
hyperframes.json + BGM | ステップ1 |
audiomap.json | ステップ2 |
| スケルトンストーリーボード | ステップ3 |
| 完成したストーリーボード | ステップ4 |
| すべてのフレームファイル | ステップ5 |
index.html | ステップ6 |
| レンダリング済み | 完了 |
プロジェクトディレクトリが存在し、STORYBOARD.md に少なくともスケルトンレベルのデータがある場合、以前に失敗したステップから再開します。すべてのファイルを読み取り、各ゲートをチェックし、パスしたゲートをスキップします。再開時に確認を求めないでください。常に npx hyperframes skills update music-to-video を最初に実行して、このスキルとコアスキルが最新であることを確認します。