music-to-video — 1つの音楽に基づいたビート同期動画ワークフロー
このスキルを使用して、音楽トラックをビート同期のHyperFrames動画に変換します。トラックを一度分析し、フレームをレイアウトし、フレームごとの計画を埋め、各フレームをコンポジションとして構築します。入力は音楽トラックと、オプションのユーザー画像または動画です — ナレーションはなく、ウェブサイトのキャプチャもありません。タイポグラフィとテンプレートが基盤です(アセットがゼロでも完全な動画を作成できます)。ユーザーが提供したメディアはすべて、同じビートグリッド上でカットインされます。
あなたはオーケストレーターです。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つのフレームワーカーによって構築されます。フレームはグループ(それぞれがテンプレートまたはモーションプリミティブの組み合わせ)に細分化できます。追加の密度はグループの_内部_に収まるため、フレーム数はビートではなく、異なる処理の数を示します — 速いトラックでもサブエージェントの数が爆発的に増えることはありません。
ステップ0:セットアップ、BGM、および入力
目標:音楽ソースを確立し、HyperFramesプロジェクトを作成し、ユーザーが提供したメディアを記録します。
音楽が背骨です — 他のすべての前に1つのトラックを確立します。このスキルは、速くてエネルギッシュなBGMに調整されています。強力なビートグリッドがカットを駆動します(落ち着いたトラックでも機能しますが、ビートではなくフレーズでペースを調整します)。ユーザーからオーディオ(音楽ファイル、または音声を抽出するための動画)が提供された場合は、それを使用します。そうでない場合は、生成します。ユーザーの説明に合わせてムードを選択し(例:「ドライビングなシンセウェーブ」、「トラップビート」、「アップビートなコーポレート」)、/hyperframes-media を介してトラックを生成します(references/bgm.md — 認証情報がある場合はHeyGen検索、そうでない場合はローカルのLyria / MusicGen;ElevenLabsまたは別のジェネレーターも機能します)。生成する前に、npx hyperframes auth status を実行し、その出力をそのまま中継します(言い換えたり書き換えたりしないでください) — これにより、BGMがHeyGenから来るのかローカルのMusicGenから来るのか、そしてサインインしていない場合のサインイン方法が示されます。サインインしていない場合は、STOPしてユーザーが選択するのを待ちます — サインインするか、ローカルの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" # 必要に応じて最初に動画から抽出
# ユーザーが画像や動画を提供した場合のみ:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
ブランド(フォント + パレット)はステップ3で選択されます。ここでは選択しません。事前にジャンルやトラックタイプを選択しないでください — アセットは単なるオプションの材料であり、ジャンルはフレームごとの選択から自然に決定されます。
ゲート: hyperframes.json + assets/bgm.mp3 が存在する;アスペクト比 / 長さ / FPS、および(もしあれば)アセットのインベントリが記録されていること。
ステップ1:音楽を分析する
目標:動画全体の基礎となる、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_sec);各フレームに 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
Materials: 各グループについて、<SKILL_DIR>/references/templates/<id>/index.html(テンプレート)および
<SKILL_DIR>/references/motion-primitives/<id>/(フリー);ステージングされた assets/(アセットグループ)
Contracts: ../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:フレームワーカーをディスパッチする前に |
../hyperframes-core/references/subagent-dispatch.md | ステップ4:ワーカーのディスパッチプロトコル |
スキルディレクトリ構造
<SKILL_DIR>/
├── skill.md # このファイル
├── scripts/
│ ├── analyze-beatgrid.py
│ ├── validate-plan.mjs
│ ├── assemble-index.mjs
│ ├── stage-assets.mjs
│ └── lib/
│ └── storyboard.mjs
├── references/
│ ├── bgm.md
│ ├── frame-skeleton.md
│ ├── planning.md
│ ├── storyboard-format.md
│ ├── template-catalog.md
│ ├── motion-primitive-catalog.md
│ ├── montage.md
│ └── templates/
│ └── (テンプレートIDごとのサブディレクトリ)
└── sub-agents/
└── frame-worker.md