music-to-video

プラグインのインストール： このスキルが HyperFrames プラグイン内にある場合は、セットアップコマンドや最新状態の確認コマンドを実行する前に、プラグインの実行ルールに従ってください。スタンドアロンでインストールした場合は、以下の更新手順をそのまま使います。

まず、このスキルを最新の状態に保ってください。実行する前にユーザーに確認します： npx hyperframes skills update music-to-video。すべて最新であればすぐに何もせず終了します。そうでなければ、このスキルと、依存するコアドメインスキルを更新してから使用します。

music-to-video — 音楽を基盤にビートと同期した動画を作るワークフロー

このスキルを使って、音楽トラックをビートと同期した HyperFrames 動画に変換します。トラックを一度分析し、フレームを配置して、フレームごとのプランを作成し、各フレームをコンポジションとして構築します。入力は音楽トラックと、任意のユーザー提供画像または動画です。ナレーションもウェブサイトのキャプチャもありません。 タイポグラフィとテンプレートが基本となるため、アセットがなくても動画を完成できます。ユーザーが提供したメディアは、同じビートグリッドに沿って挿入します。

あなたはオーケストレーターです。videos/<project>/ で作業します。手順は順番に進め、次に移る前に各ゲートを通過してください。ユーザーの確認が必要なのは Step 3（プランの承認）と Step 6（レンダリングの承認）の2か所です。どちらも ../hyperframes/references/brief-contract.md に定められたチェックポイントゲートです（Step 0 の前に読んでください）。自律モードでは、Step 3 の要約を事前通知として投稿して先に進みます。Step 6 のレンダリング承認は、最後に残す確認事項として引き続きユーザーに尋ねます。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 が信頼できるのは、音楽に本当にリズムがある場合に限ります。穏やかな音楽では、グリッドはトラッカーが当てはめたメトロノームにすぎないため、フレーズやエネルギーに合わせてテンポを取り、グリッドに合わせて急にカットしてはいけません。どちらに当たるかは、Step 2 の各フレームの pacing で判断します。
• 1フレームにつき1ファイル、グループはフレーム内に配置します。 Step 2 ではトラックをフレームに分割します。各フレームは compositions/frames/NN-<frame_id>.html というコンポジションファイルになり、1つの frame-worker が構築します。フレームはグループに分割できます。各グループはテンプレート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 は空でないディレクトリでは実行できないため、初期化より前には書きません）。好みに基づく回答を記録します（brief-format.md）。編集リクエストでは、これらすべてを省略します。

音楽が軸です — 何よりも先に 1 曲を決めます。このスキルはテンポが速く、エネルギッシュな BGM 向けに調整されています。強いビートグリッドに合わせてカットを組み立てます（落ち着いた曲にも対応しますが、ビートではなくフレーズに合わせてペースを調整します）。ユーザーが音声（音楽ファイル、または音声を取り出す動画）を提供した場合は、それを使用します。そうでない場合は、リクエストからムードを選び、/media-use（audio/references/bgm.md）を通じて曲を生成します。ホストアプリに独自の音楽ツールがある場合は、それを使用します。認証が必要なプロバイダーを初めて利用する前に、npx hyperframes auth status を実行し、その出力を一字一句そのまま伝えます。サインアウト状態の場合は、次のいずれかに従います。

• 共同作業の場合： サインインするか、ローカルプロバイダーを使ってオフラインで続行するか、明示的な選択を待ちます。
• 自律実行の場合： 状態を伝え、利用可能なローカルプロバイダーで続行します。

必要な音楽機能を満たせるオフラインプロバイダーがない場合は、阻害要因を伝えます。リポジトリごとの .env にキーを書き込んではいけません。認証の管理とオフライン時の代替手段については、/media-use の references/setup-providers.md § Providers を参照してください。生成されたトラックは 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"   # extract from a video first if needed
# only if the user gave you images/videos:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public

ブランド（フォント＋パレット）はここではなく Step 3 で選びます。ジャンルやトラックの種類を先に決めてはいけません。素材は任意の要素にすぎず、ジャンルはフレームごとの選択から決まります。

完了条件： hyperframes.json と assets/bgm.mp3 が存在し、アスペクト比／長さ／fps、および（あれば）素材の一覧が記録されていること。

---

Step 1: 音楽を分析する

目標：動画全体の制作基盤となる、唯一の正式なタイミング分析を作成します。

analyze-beatgrid.py は唯一のビート分析ツールです。他のツールや耳でビートを再測定してはいけません。トラックを 1 回読み込み、エネルギーフェーズ（レベル／密度／雰囲気）、オンセットと onset_rate、ロール、無音区間、hard_stops、key_moments、フレーズ、テンポ／グリッド、および audio.duration_sec を含む audiomap.json を書き出します。処理は決定論的で、同じファイルからは常に同じマップが生成されます。ほとんどのフィールドはどのような音楽でも信頼できますが、bpm と beats_sec が信頼できるのは、音楽に実際のリズムがある場合だけです。リズムがあるかどうかは Step 2 で判断します。

前提条件：Python 3 と、librosa、numpy、soundfile が利用可能であることです。インポートに失敗した場合は、分析ツールを実行する前に、現在有効な 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、ロールの端、オンセットのない区間、大きなエネルギーの跳ね上がり）でトラックをフレームに分割し、すべての境界を audiomap のアンカーに合わせます。各フレームに span_sec、pacing（ステップ 1 の信頼性判断の結論。グリッドが実際のものなら beat_cut、穏やかな音楽にメトロノームを当てはめたものなら phrase_flow）、mood、そしてステップ 3 でテンプレートと照合する、音楽の状況を平易に記した一行の feel を設定します。ここでは分類と配置のみを行い、各フレームの ### Groups は TBD (Step 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 つを行います。

1. ブランドを選びます。 ../hyperframes-creative/references/design-spec.md の表を使って、../hyperframes-creative/frame-presets/ からプリセットを 1 つ選びます（トラックのムードに合わせます。重要なのはフォントと色のみです。 構成はテンプレートが担います）。その内容を変更せず frame.md にコピーし、そこからフロントマターの style（フォント + 4～6 色以下のスウォッチパレット）を設定します。
2. すべてのフレームを完成させます。 各フレームのグループを決め、それぞれに処理方法を指定します。カタログから一致するテンプレート（設定値と実際の audiomap アンカー付き）、プリミティブカタログを使った自由構成、または pacing に従うアセット処理のいずれかを選びます。名前の付いた表現を自由構成する前に、現在のカタログを検索してください。 ユーザーが指定した表現、エフェクト、処理、トランジション（「CRT スキャンライン」「グリッチ」「フィルムグレイン」「シマーのスイープ」など）ごとに、npx hyperframes catalog --query "<the look, in plain English>" --json を実行し、上位の結果を読みます。template-catalog.md と motion-primitive-catalog.md に載っているのは、このスキル独自のローカル素材のみです。検索ではホスト全体のレジストリ（約 400 個のブロックとコンポーネント）が順位付けされ、インストールは一切不要です。プロジェクトも、事前の add も、アカウントも必要ありません。検索結果に適合するものがなかった場合に限り、その表現を自由構成します。コピーを記述します。WHAT（テンプレート／プリミティブ + コンテンツ + アンカー）はあなたが決め、HOW は frame-worker が担当します。ストーリーボードにミリ秒単位のトゥイーンを書いてはいけません。

node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
  --audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates

すべての ✗（重大なエラー：デュレーションの不一致、フレームがトラックを隙間なく覆っていない、src の欠落）を修正します。警告は可能な範囲で対処します。次に、フレームごとの概要をチャットで提案として提示し（../hyperframes/references/review-loop.md § 1）、ユーザーの返信に応じて承認されるまで調整します。storyboard: yes の場合は、ボード boards/storyboard.html としても表示します（../hyperframes-creative/references/storyboard-recipe.md）。自律モードでは、これはチェックポイントのゲートです。概要を事前通知として投稿してから進めます（validate-plan.mjs の検証は品質ゲートであり、引き続き進行を阻止します）。

ゲート： frame.md がプリセットの完全なコピーであること。validate-plan.mjs が終了コード 0 で終了すること。ユーザーがプランを承認していること（自律モード：概要が事前通知として投稿されていること）。

---

ステップ 4：プランからフレームを作成する

目標：各フレームを、単独で完結するコンポジションファイルとして作成します。

compositions/frames/ を作成します。sub-agents/frame-worker.md と ../hyperframes/references/subagent-dispatch.md を読みます。可能な場合は並列で（そうでない場合は複数回に分けて）、フレームごとに 1 つの frame-worker を割り当てます。各ワーカーに渡すフレームは 1 つだけとし、次のコンテキストを共有します。

PROJECT_DIR: <abs path>
frame_id: <NN-frame_id>              # = the frame file stem, e.g. 02-f2; the composition id
Your block: the `## Frame N — <frame_id>` block in PROJECT_DIR/STORYBOARD.md
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
Materials: for each group, <SKILL_DIR>/references/templates/<id>/index.html (templates) and
           <SKILL_DIR>/references/motion-primitives/<id>/ (free); staged assets/ (asset groups)
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 を実行しません。これらのコマンドは、まだ存在しない組み立て済みプロジェクトに対して動作するため、誤ったファイルが報告されます。ワーカーは契約に沿ってファイルを書き出したら終了します。組み立て後に確認します（ステップ 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 は構造のリントと、ヘッドレスブラウザーでの実行時、レイアウト、モーション、コントラストの各ゲートを一度に実行します。--snapshots を付けると、レビュー用フレームも出力します。

( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )

t=0、各フレームの開始時刻、最も強い DROP / SURGE、すべての hard_stops[].t、および最終フレームを確認します。失敗した場合は、最も手軽で安全な修正を自分で行います。該当する compositions/frames/NN-*.html を編集してください。同期の問題を隠すために尺やオーディオのタイミングを変更してはいけません。ゲートに合格したら、最終版の Studio プレビュー（( cd "$PROJECT_DIR" && npx hyperframes preview --background )）を開いて、ユーザーのレビューを待ちます。今すぐレンダリングしますか、それとも変更しますか？承認を得てからレンダリングします（自律モードでも同じです。確認事項はこの 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 のパスと尺を記載します。

---

再開テーブル

手元にあるもの	続行するステップ
assets/bgm.mp3 のみ	ステップ 1
audiomap.json	ステップ 2
STORYBOARD.md（骨組み）	ステップ 3
STORYBOARD.md（完成版）	ステップ 4
すべてのフレームファイル	ステップ 5
index.html	ステップ 6

クイックリファレンス

形式： デフォルトは横長の 1920x1080、縦長は 1080x1920、正方形は 1080x1080 です。ストーリーボードのフロントマターでキャンバスを一度設定します（canvas: { w, h, fps }）。

スクリプトは scripts/ にあります：analyze-beatgrid.py（唯一のアナライザー）、validate-plan.mjs（プランのチェック）、assemble-index.mjs（インデックスの組み立て）、stage-assets.mjs（ユーザーメディアのステージング）、lib/storyboard.mjs（同梱パーサー）。それ以外はすべて hyperframes CLI です。

参照	用途
references/frame-skeleton.md	ステップ 2：音楽を読み取り、フレームを配置し、ペース配分を設定する
references/planning.md · storyboard-format.md	ステップ 3：ブランドを選び、各フレームを埋めて、プランを作成する
references/template-catalog.md	ステップ 3：グループごとにテンプレートを選ぶ
references/motion-primitive-catalog.md	ステップ 3/4：フリーコンポーズ用の L0 レシピ
references/montage.md	ステップ 3/4：アセットの処理（ビートカット／ケン・バーンズ）
sub-agents/frame-worker.md	ステップ 4：ディスパッチして 1 つのフレームを構築する
../hyperframes/references/subagent-dispatch.md	ステップ 4：サブエージェントを安全にディスパッチする
../hyperframes-creative/references/design-spec.md	ステップ 3：プリセット（ブランド）を選ぶ

ディレクトリ構成

music-to-video/
  SKILL.md
  references/   frame-skeleton.md · planning.md · storyboard-format.md
                template-catalog.md · motion-primitive-catalog.md · montage.md
                templates/<id>/          { index.html (+ assets/ · program.json) }  ← L1 catalog impls
                motion-primitives/<id>/  { index.html (mounts the scene), scene.html (the sub-composition) } (+ ../assets/gsap.min.js shared by recipes) ← L0 catalog impls
  scripts/      analyze-beatgrid.py · assemble-index.mjs · validate-plan.mjs · stage-assets.mjs · lib/storyboard.mjs
  sub-agents/   frame-worker.md   ← the one subagent (one per frame)