music-to-video — 音楽に基づくビート同期動画ワークフロー1本化
このスキルを使用して、音楽トラックをビートに同期した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つのフレームワーカーによって構築されます。フレームはさらにグループ(各テンプレートまたはモーションプリミティブの組み合わせ)に分割できます。追加の密度はグループの_内部_に配置するため、フレーム数は個別の処理単位を追跡し、ビート数は追跡しません — 速いトラックでもサブエージェントの数は増えません。
ステップ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 → プレフライトを参照してください。いずれの場合も、トラックは assets/bgm.mp3 に配置されます。ユーザー提供の画像や動画をステージングし、フレームがビートグリッド上でそれらを織り込めるようにします。それ以外の場合は、タイポグラフィが動画全体を支えます。
hyperframes.json が存在しない場合のみ初期化します。ブリーフからプロジェクト名をケバブケースで指定します(例: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:音楽を解析する
目標:動画全体の基盤となる、唯一の正規のタイミング解析を生成します。
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/から、../hyperframes-creative/references/design-spec.mdのテーブルを使用して1つのプリセットを選択します(トラックのムードに合わせます。フォントと色のみ重要 — テンプレートがコンポジションを所有します)。それを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>/(フリー);ステージングされたアセット/(アセットグループ)
契約:../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:サブエージェントのディスパッチ方法 |
../hyperframes-core/references/sub-compositions.md と determinism-rules.md | ステップ4:フレームワーカー契約の詳細 |
このスキルは、analyze-beatgrid.py(唯一のビート解析ツール)と frame-worker(フレームビルド用の決定論的サブエージェント)を中心に設計されています。デザインの選択はすべてストーリーボードに集中し、フレームワーカーは契約に厳密に従って実装します。