music-to-video — 音楽駆動型ビート同期動画ワークフロー
このスキルは、音楽トラックをビート同期のHyperFrames動画に変換するために使用します。トラックを一度解析し、フレームをレイアウトして、各フレームの計画を埋め、各フレームをコンポジションとして構築します。入力は音楽トラックと、オプションのユーザー画像または動画です — ナレーションやWebサイトキャプチャはありません。タイポグラフィとテンプレートが基本です(完全な動画にアセットは不要)。ユーザーが提供したメディアはすべて同じビートグリッド上でカットインされます。
あなたはオーケストレーターです。videos/<project>/ 内で作業します。ステップを順に実行し、各ゲートを通過してから次に進みます。2つのステップでユーザーの介入が必要です:ステップ3(プラン承認)とステップ6(レンダリング承認)。ステップ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つのframe-workerによって構築されます。フレームはグループ(それぞれテンプレートまたはモーションプリミティブの組み合わせ)に細分化できます。追加の密度はグループの_内部_に配置されるため、フレーム数は異なる処理を追跡し、ビート数は追跡しません — 速いトラックでもサブエージェントの数が増えることはありません。
ステップ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 が欠落している場合のみ初期化します。ケバブケース(例:midnight-drive-loop)で <project> に名前を付けます — タイムスタンプは使用しないでください。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" # 必要に応じて動画から先に抽出
# ユーザーが画像/動画を提供した場合のみ:
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で行う判断です。
前提条件: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、ロールの端、オンセットのないストレッチ、大きなエネルギージャンプ)でトラックをフレームにカットし、すべての境界をオーディオマップのアンカーにスナップします。各フレームに span_sec、pacing(ステップ1の信頼判断の結果 — グリッドが本物の場合は beat_cut、穏やかな音楽に課されたメトロノームの場合は phrase_flow)、mood、および1行の feel(ステップ3でテンプレートを照合するためのプレーンな音楽状況)を設定します。ここでは分類とレイアウトのみを行います。すべてのフレームの ### 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つのことを行います。
- ブランドを選択します。
../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)を修正します。警告はベストエフォートです。その後、フレームごとのサマリーをユーザーに表示し、承認されるまで繰り返します。
ゲート: 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を実行します — それが正しい単位です(フレームごとのワーカーは実行できませんでした)。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 のみ | ステップ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:グループに自由構成を選択する |
references/montage.md | ステップ3(ユーザーがアセットを提供した場合のみ):モンタージュ処理 |
フレームワークーサブエージェント: sub-agents/frame-worker.md は、各フレームワーカーが従う正確な契約を定義します。これはステップ4で必須です。
素材参照: references/ ディレクトリには、ストーリーボード形式、テンプレートカタログ、モーションプリミティブの仕様が含まれています。これらはステップ2および3で参照されます。