music-to-video

music-to-video — 音楽に根ざした、ビート同期動画のワークフロー

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

あなたはオーケストレーターです。videos/<project>/ で作業します。手順を順番に実行し、次に進む前に各ゲートを通過してください。ユーザーの確認が必要な手順は、Step 3（プランの承認）とStep 6（レンダリングの承認）の2つです。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つ、またはモーションプリミティブの組み合わせです）。密度を増やす場合はグループの内部に追加するため、フレーム数はビート数ではなく、異なる処理の数に応じて決まります。テンポが速いトラックでも、サブエージェントの数が膨れ上がることはありません。

---

ステップ 0：セットアップ、BGM、入力

目標：音楽ソースを確定し、HyperFrames プロジェクトを作成して、ユーザーから提供されたメディアを記録します。

音楽が軸です。何よりも先に、1 曲を確定します。このスキルはテンポの速い、エネルギッシュな BGM向けに調整されています。強いビートのグリッドに合わせてカットを進めます（穏やかな曲でも使えますが、ビートではなくフレーズに合わせてペースを調整します）。ユーザーが音声（音楽ファイル、または音声を取り出す動画）を渡した場合は、それを使います。渡されていない場合は生成します。ユーザーの説明（例：「疾走感のあるシンセウェーブ」「トラップビート」「アップビートな企業向け」）からムードを選び、/hyperframes-media（references/bgm.md — 認証情報がある場合は HeyGen から取得し、ない場合はローカルの Lyria / MusicGen を使用）を通じてトラックを作成します。ElevenLabs など、別の生成ツールを使ってもかまいません。生成前に npx hyperframes auth status を実行し、その出力を一字一句そのまま伝えてください（言い換えたり書き換えたりしないでください）。出力には、BGM の取得元が HeyGen とローカル MusicGen のどちらか、また未ログインの場合はログイン方法が表示されます。未ログインの場合は、トラックを生成する前に作業を停止し、ユーザーがログインするか、ローカル MusicGen を使ってオフラインで続行するかを選ぶまで待ってください。リポジトリごとの .env にキーを書き込んではいけません。（自律モードでは、ステータスを記録してオフラインで続行します。）正式なガイダンスについては、/hyperframes-media → Preflight を参照してください。どちらの場合も、トラックは assets/bgm.mp3 に配置します。ユーザーから提供された画像や動画があれば、ビートのグリッドに合わせて映像に織り込めるように準備します。提供されていない場合は、動画全体をタイポグラフィで構成します。

hyperframes.json がない場合に限り、初期化します。<project> には概要から名前を付け、midnight-drive-loop のようなケバブケースにします。タイムスタンプは使用しません。init は GitHub 上の最新バージョンとインストール済みスキルを照合し、古いものがあればグローバルのセットを更新します。

npx hyperframes init "videos/<project>" --non-interactive --example=blank
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

ブランド（フォント＋パレット）を選ぶのはここではなく、ステップ 3 です。ジャンルやトラックの種類を事前に決めてはいけません。アセットは任意の素材にすぎず、ジャンルはフレームごとの選択によって生まれます。

ゲート： hyperframes.json と assets/bgm.mp3 が存在し、アスペクト比／長さ／fps、および（該当する場合は）アセットの一覧が記録されていること。

---

ステップ 1：音楽を分析

目標：動画全体の構成に使う、唯一の標準タイミング分析を作成します。

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

---

Step 2: フレームの骨組み（構造のみ）

目標：音楽を聴いてフレームを配置し、STORYBOARD.md の骨組みを作成します。

references/frame-skeleton.md を読みます。audiomap.json を使って、自分で STORYBOARD.md の骨組みを作成します。中間 JSON はありません。実際の音楽的な変化（hard_stops、SURGE / DROP の key_moments、ロールの端、オンセットのない区間、大きなエネルギーの跳躍）でトラックをフレームに分割し、すべての境界を audiomap のアンカーに合わせます。各フレームには、span_sec、pacing（Step 1 の信頼度判断に基づく判定。グリッドが実際にある場合は beat_cut、穏やかな音楽にメトロノームを当てはめた場合は phrase_flow）、mood、および 1 行の feel（Step 3 でテンプレートと照合する、飾らない音楽の状況）を設定します。ここでは分類と配置だけを行います。各フレームの ### Groups はすべて TBD (Step 3) のままにし、frontmatter の 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 つを行います。

1. ブランドを選びます。 ../hyperframes-creative/references/design-spec.md の表を使って、../hyperframes-creative/frame-presets/ からプリセットを 1 つ選びます（トラックのムードに合わせます。重要なのはフォントと色のみで、構成はテンプレートが担います）。それを frame.md に変更せずコピーし、プリセットから frontmatter の style（フォント＋色のスウォッチ 4～6 色以下のパレット）を設定します。
2. すべてのフレームを埋めます。 各フレームのグループを決め、それぞれに次のいずれかの処理を指定します。カタログから照合したテンプレート（パラメーターと実際の audiomap アンカーを設定）、プリミティブカタログを使った自由構成、または 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 の欠落）を修正します。警告への対応は可能な範囲で行います。その後、フレームごとの概要をユーザーに示し、承認されるまで調整を続けます。

ゲート： 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: <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 を実行しません。 これらのコマンドが対象とするのは組み立て済みのプロジェクトですが、その時点ではまだ存在しないため、誤ったファイルについての結果が報告されます。ワーカーは契約に沿ってファイルを書き込み、そこで停止します。組み立て後に確認します（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 は組み立てたプロジェクトに対して実行してください。これが正しい単位です（フレーム単位のワーカーでは実行できません）。lint は構造をチェックし、validate はヘッドレス Chrome を実行して（JS エラーやアセットの欠落を検出し）、inspect はフレームのスナップショットを取得します。

( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )

t=0、各フレームの開始位置、最も強い DROP / SURGE、すべての hard_stops[].t、および最終フレームを確認してください。失敗した場合は、問題のある compositions/frames/NN-*.html を編集して、最も低コストで安全な修正を行ってください。同期の問題を隠すために、再生時間や音声のタイミングを変更してはいけません。ゲートを通過したら、ユーザーのレビューのために一時停止し、承認後にのみレンダリングしてください。

( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )

ゲート： lint / validate / inspect が成功し、ユーザーの承認を得ており、音声付きの renders/video.mp4 が存在し、再生時間 == audiomap.audio.duration_sec。最終返信には MP4 のパスと再生時間を記載してください。

---

再開位置の表

手元にあるもの	再開するステップ
assets/bgm.mp3 のみ	Step 1
audiomap.json	Step 2
STORYBOARD.md（骨子）	Step 3
STORYBOARD.md（完成版）	Step 4
すべてのフレームファイル	Step 5
index.html	Step 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-core/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 } (+ ../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)