最初に、このスキルを最新に保ってください——確認はせずに、静かに実行：
npx hyperframes skills update music-to-video。すべてが最新のときは高速なno-opですが、そうでない場合は、このスキルと、それが依存するコアドメインスキルを、それらに依存する前に更新します。
music-to-video — 音楽に基づいた、ビート同期の動画ワークフロー
このスキルは、音楽トラックをビート同期の HyperFrames 動画に変換するために使用します。あなたはトラックを一度解析し、フレームをレイアウトし、フレームごとの計画を記入し、各フレームをコンポジションとして構築します。入力は音楽トラックと、オプションのユーザー提供画像または動画です——ナレーションやウェブサイトキャプチャはありません。タイポグラフィとテンプレートがベース（完全な動画にはアセットは不要）。ユーザーが提供したメディアはすべて同じビートグリッド上にカットされます。
あなたはオーケストレーターです。videos/<project>/ で作業します。手順を順番に実行し、各ゲートを通過してから次に進みます。ユーザーが必要なステップは2つ：Step 3（計画承認）とStep 6（レンダリング承認）——どちらも ../hyperframes-core/references/brief-contract.md に従ったチェックポイントゲートです（Step 0の前に読んでください）。自律モードでは、サマリーを先出しとして投稿し、待たずに進めます。自分で全てのステップを実行しますが、Step 4では、フレームごとに1つのサブエージェントをディスパッチします。設計とモーションのルールはこのファイルではなく、references/ と frame-worker サブエージェントにあります。
SKILL_DIR = このスキルディレクトリ。PROJECT_DIR = videos/<project-name>/。
ワークフロー：Step 0 セットアップ → hyperframes.json + assets/bgm.mp3；Step 1 解析 → audiomap.json；Step 2 スケルトン → STORYBOARD.md（フレーム、グループ TBD）；Step 3 計画 → 完成 STORYBOARD.md + frame.md；Step 4 ビルド → compositions/frames/NN-*.html；Step 5 アセンブル → index.html；Step 6 レンダリング → renders/video.mp4。
すべてを形作る2つの考え方
- 1つのアナライザー、そしてそれを信頼する。
analyze-beatgrid.pyが唯一のビートアナライザーです——他のツールや耳でビートを再計測しないでください。そのエネルギー、密度、ロール、オンセット、サイレンスは常に信頼できます。そのbpmとbeats_secは、音楽が本当にリズミカルな場合にのみ信頼できます。穏やかな音楽では、グリッドはトラッカーが強制したメトロノームなので、代わりにフレーズとエネルギーでペースを決め、それにハードカットしないでください。どちらのケースかを判断することは、各フレームのpacing（Step 2）です。 - 1フレーム＝1ファイル。グループは内部に存在する。 Step 2では、トラックをフレームに分割し、各フレームは1つのコンポジションファイル
compositions/frames/NN-<frame_id>.htmlになり、1つのフレームワーカーによって構築されます。フレームはさらにグループ（それぞれがテンプレートまたはモーションプリミティブの組み合わせ）に細分化できます。追加の密度はグループの_内部_に入るため、フレーム数は異なる処理の数を追跡し、ビート数は追跡しません——速いトラックでもサブエージェントの数が爆発的に増えることはありません。
Step 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）を確認し、延期されるもの（ブランドとジャンルは意図的にStep 3で選択）を通知する。BRIEF.md は init の直後に書き込む（決して前には書き込まない——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
ブランド（フォント＋パレット）はStep 3で選択され、ここではありません。事前にジャンルやトラックタイプを選ばないでください——アセットは単なる任意の材料であり、ジャンルはフレームごとの選択から生まれます。
ゲート： hyperframes.json + assets/bgm.mp3 が存在し、アスペクト、長さ、fps、および（もしあれば）アセットの在庫が確認されている。
Step 1: 音楽を解析する
目的：動画全体が構築される、1つの正準的なタイミング分析を生成する。
analyze-beatgrid.py が唯一のビートアナライザーです——他のツールや耳でビートを再計測しないでください。トラックを1回読み取り、audiomap.json を書き出します：エネルギーフェーズ（レベル/密度/感触）、オンセット + onset_rate、ロール、サイレンス、hard_stops、key_moments、フレーズ、テンポ/グリッド、audio.duration_sec。決定論的です——同じファイルからは常に同じマップが得られます。ほとんどのフィールドはあらゆる音楽で信頼できます。bpm と beats_sec は、音楽が本当にリズミカルな場合のみ信頼でき、その判断はStep 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 が既知である。
Step 2: フレームスケルトン（構造のみ）
目的：音楽を読み、フレームをレイアウトする——STORYBOARD.md のスケルトン。
references/frame-skeleton.md を読む。audiomap.json を自分で STORYBOARD.md のスケルトンに変換します——中間JSONはありません。トラックを実際の音楽的変化（hard_stops、SURGE/DROP key_moments、ロールの端、オンセットのないストレッチ、大きなエネルギージャンプ）でフレームに分割し、すべての境界をオーディオマップのアンカーにスナップします。各フレームに対して、span_sec、pacing（Step 1の信頼呼び出しからの判定——グリッドが本物の場合は beat_cut、穏やかな音楽に強制されたメトロノームの場合は phrase_flow）、mood、および1行の feel（Step 3がテンプレートと照合するプレーンな音楽状況）を設定します。ここでは分類とレイアウトのみを行います：各フレームの ### Groups を TBD (Step 3) のままにし、フロントマター style を空白のままにします——テンプレート、コピー、色、フォントはなし。予想されるフレーム数は約1～6です。
ゲート： フレームがトラックをタイル状に並べている（最初は0、最後はduration_s）。各フレームは span_sec + pacing + mood + feel を持つ。すべての ### Groups は TBD。どこにもコンテンツなし。
Step 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で終了する。ユーザーが計画を承認した（自律モード：サマリーが先出しとして投稿された）。
Step 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
Your block: `## Frame N — <frame_id>` ブロック (PROJECT_DIR/STORYBOARD.md 内)
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
Materials: 各グループについて、<SKILL_DIR>/references/templates/<id>/index.html (テンプレート) と
<SKILL_DIR>/references/motion-primitives/<id>/ (自由形式); staged assets/ (アセットグループ)
Contracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Canvas: <w>×<h> Pacing: <beat_cut|phrase_flow>
Write to: PROJECT_DIR/compositions/frames/<frame_id>.html
ワーカーは引用されたマテリアルをフォークし、すべてのアンカーをフレームローカル秒（local_t = track_t − span_sec[0]）に変換し、そのグループを0msカットでゲートし、1つのシークセーフなフレームファイルを書き込みます。ワーカーは決して hyperframes CLI を実行しません——これらのコマンドはアセンブルされたプロジェクト上で動作し、それはまだ存在しないため、間違ったファイルについて報告することになります。ワーカーは契約に従って書き込み、停止します。アセンブリ後（Step 6）に確認します。各ワーカーが戻ったら、そのファイルがディスク上にあることを確認できます。
ゲート： すべてのフレームが compositions/frames/NN-*.html としてディスク上にある。
Step 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"
報告された ✗ を修正します——欠落または空のフレームファイルは、そのワーカーが部分的なファイルを書き込んだことを意味します。それを再ディスパッチし（Step 4）、再アセンブルします。
ゲート： index.html が存在する。合計期間 == audiomap.audio.duration_sec。
Step 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のパスと期間を記載する。
再開テーブル
| あなたが持っているもの | 続行先 |
|---|
…
[翻訳用に切り詰められました]