最初に、このスキルを最新の状態に保つために、確認せずに実行してください:
npx hyperframes skills update music-to-video。すべてが最新の場合は高速なno-opです。それ以外の場合は、このスキルとそれが依存するコアドメインスキルを更新してから使用します。
music-to-video — 音楽に基づいた、ビート同期動画ワークフロー
このスキルを使用して、音楽トラックをビート同期のHyperFrames動画に変換します。トラックを一度分析し、フレームをレイアウトし、フレームごとの計画を作成し、各フレームをコンポジションとして構築します。入力は音楽トラックと、ユーザーが任意で提供する画像または動画です。ナレーションやWebサイトキャプチャはありません。タイポグラフィとテンプレートが基本となり(完全な動画にはアセットは不要です)。ユーザーが提供したメディアは、同じビートグリッド上にカットインされます。
あなたはオーケストレーターです。videos/<project>/ ディレクトリで作業します。手順を順番に実行し、各ゲートを通過してから次に進みます。ユーザー介入が必要な2つのステップは、ステップ3(計画承認)とステップ6(レンダリング承認)です。これらは、../hyperframes-core/references/brief-contract.md(ステップ0の前に読んでください)に従ったチェックポイントゲートです。自動モードの場合、概要を通知として投稿し、待たずに続行します。ステップ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) BRIEF.md が存在する → それを読み、それが答えていることは質問しない。その flow/storyboard はモードを導き出します(ブリーフ契約 § 1)。(2) BRIEF.md はないがプロジェクトが存在する → ディスク上のものから再開し、再質問しない。(3) ここに直接到着した新しい作成リクエスト → /hyperframes を読み、その意図レイヤー(references/intent-interview.md)を実行します。このルートの必須事項(音楽ソース、出力先 → アスペクト — ../hyperframes/references/routes/music-to-video.md)を確認し、何が延期されるかを通知します(ブランドとジャンルは設計上ステップ3で選択されます)。BRIEF.md をinitの_直後_に書き込みます(initは空でないディレクトリを拒否するため、決してその前ではありません)。設定ベースの回答(brief-format.md)を記録します。編集リクエストはこれらすべてをスキップします。
音楽は背骨です — 他の何よりも先に1つのトラックを確立します。このスキルは高速で高エネルギーのBGMに最適化されています。強力なビートグリッドがカットを駆動します(穏やかなトラックでも機能しますが、ビートではなくフレーズでペースを調整します)。ユーザーがオーディオ(音楽ファイル、またはオーディオを抽出するための動画)を提供した場合は、それを使用します。それ以外の場合は、リクエストから雰囲気を選択し、/media-use(references/bgm.md)を通じてトラックを生成します。最初の認証済みプロバイダーアクションの前に、npx hyperframes auth status を実行し、その出力をそのまま伝えます。サインアウトしている場合は、次のいずれかの分岐を適用します。
- 協調モード: サインインするか、オフラインでローカルプロバイダーを続行する明示的な選択を待ちます。
- 自動モード: ステータスを通知し、利用可能なローカルプロバイダーで続行します。
必要な音楽機能を満たすオフラインプロバイダーがない場合は、ブロッカーを表面化します。リポジトリごとの .env にキーを書き込まないでください。認証の所有権とオフラインフォールバックは、/media-use references/setup-providers.md § プロバイダーにあります。結果のトラックは assets/bgm.mp3 に配置されます。提供された画像や動画をステージングして、フレームがビートグリッド上で使用できるようにします。それ以外の場合は、タイポグラフィが動画を支えます。
歌詞動画: ボーカルに同期された歌詞の場合、/media-use を介してトラックを文字起こしするか、ユーザーに歌詞テキストを依頼し、ビートグリッド上に行を配置して、ワード/ラインのタイミングを取得します。
hyperframes.json がない場合にのみ初期化します。プロジェクト名をブリーフからkebab-case(例: 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" # 必要に応じて最初に動画から抽出
# ユーザーが画像や動画を提供した場合のみ:
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で行います。
前提条件: 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 (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(テンプレート/プリミティブ + コンテンツ + アンカー)を所有します。frame-workerはHOWを所有します — ストーリーボードにミリ秒単位のトゥイーンを決して書かないでください。
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
すべての ✗(ハードエラー: 期間の不一致、トラックをタイル状に並べていないフレーム、欠落している src)を修正します。警告はベストエフォートです。次に、フレームごとの概要をユーザーに表示し、承認されるまで繰り返します。自動モードでは、これはチェックポイントゲートです。概要を通知として投稿して続行します(validate-plan.mjs パスは品質ゲートであり、依然としてブロックします)。
ゲート: frame.md がプリセットの逐語的なコピーである。validate-plan.mjs が終了コード0で終了する。ユーザーが計画を承認した(自動モード: 概要が通知として投稿された)。
ステップ4: 計画からフレームを構築する
目標: すべてのフレームを自己完結型のコンポジションファイルとして構築します。
compositions/frames/ を作成します。sub-agents/frame-worker.md と ../hyperframes-core/references/subagent-dispatch.md を読んでください。フレームごとに1つのframe-workerを、可能な限り並行して(そうでない場合はウェーブで)ディスパッチします。各ワーカーは正確に1つのフレームと次のコンテキストを取得します。
PROJECT_DIR: <絶対パス>
frame_id: <NN-frame_id> # = フレームファイルのステム(例: 02-f2); コンポジションID
your block: 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
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 は、構造的リントとヘッドレスブラウザのランタイム、レイアウト、モーション、コントラストゲートを1回のパスで実行します。--snapshots はレビューフレームも出力します。
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
t=0、各フレームの開始、最も強いDROP/SURGE、すべての hard_stops[].t、および最終フレームを検査します。失敗した場合は、自分で最も安価で安全な修正を行います。該当する compositions/frames/NN-*.html を編集します。同期の問題を隠すために期間やオーディオタイミングを変更しないでください。ゲートに合格したら、ユーザーレビューのために一時停止し、承認後にのみレンダリングします(自動モード: 保持する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のパスと期間を示す。
再開テーブル
| 現在の状態 | 続行する場所 |
|---|
…(翻訳のため省略)
}