最初に、このスキルを最新の状態に保ちます — ユーザーに確認してから実行:
npx hyperframes skills update music-to-video。すべてが最新の場合は高速なno-op、そうでない場合はこのスキルと、それが依存するコアドメインスキルを更新してから使用します。
music-to-video — 音楽に基づくビート同期ビデオワークフロー
このスキルを使用して、音楽トラックをビート同期のHyperFramesビデオに変換します。トラックを一度分析し、フレームをレイアウトし、フレームごとの計画を埋め、各フレームをコンポジションとして構築します。入力は音楽トラックと、オプションでユーザーが提供する画像または動画です — ナレーションやウェブサイトのキャプチャはありません。タイポグラフィとテンプレートが基本となります(完全なビデオにはゼロアセットが必要);ユーザーが提供するメディアはすべて同じビートグリッド上でカットされます。
あなたはオーケストレーターです。videos/<project>/ で作業します。ステップを順番に実行し、各ゲートを通過してから次に進みます。2つのステップでユーザーが必要です:ステップ3(計画承認)とステップ6(レンダリング承認) — どちらも../hyperframes/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で選択されます。init の直後に BRIEF.md を書き込みます(それ以前ではありません — init は空でないディレクトリを拒否します)そして、設定に基づいた回答(brief-format.md)を記録します。編集リクエストはこれらすべてをスキップします。
音楽は背骨です — 何よりも先に1つのトラックを確立します。このスキルは高速で高エネルギーのBGM向けに調整されています:強いビートグリッドがカットを駆動します(穏やかなトラックでも機能しますが、ビートではなくフレーズでペーシングします)。ユーザーがオーディオ(音楽ファイル、または音声を抽出する動画)を提供した場合は、それを使用します。それ以外の場合は、リクエストからムードを選択し、/media-use(references/bgm.md)を通じてトラックを生成します。最初の認証済みプロバイダーアクションの前に、npx hyperframes auth status を実行し、その出力をそのまま中継します。サインアウトしている場合は、1つのブランチを適用します:
- 協力的: サインインするか、ローカルプロバイダーでオフラインを続行する明示的な選択を待ちます。
- 自律的: ステータスを述べ、利用可能なローカルプロバイダーで続行します。
必要な音楽機能を満たせるオフラインプロバイダーがない場合は、ブロッカーを表面化します。リポジトリごとの .env にキーを書き込まないでください。認証の所有権とオフラインフォールバックは、/media-use references/setup-providers.md § プロバイダーにあります。結果のトラックは assets/bgm.mp3 に配置されます。提供された画像または動画をステージングして、フレームがビートグリッド上でそれらを使用できるようにします。そうでない場合、タイポグラフィがビデオを支えます。
歌詞ビデオ: ボーカルに同期された歌詞の場合、/media-use を通じてトラックを文字起こしして単語/行のタイミングを取得するか、ユーザーに歌詞テキストを依頼し、ビートグリッド上に行を配置します。
hyperframes.json がない場合のみ初期化します。ブリーフからkebab-caseで <project> に名前を付けます(例: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で行います。
前提条件: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、ロールの端、オンセットのないストレッチ、大きなエネルギージャンプ)でトラックをフレームにカットし、すべての境界をaudiomapのアンカーにスナップします。各フレームについて、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スウォッチパレット)をそれから埋めます。 - 各フレームを埋めます。 そのグループを決定し、それぞれに処理を適用します:カタログから一致するテンプレート(バインドされたパラメーターと実際のaudiomapアンカーを使用)、プリミティブカタログからの自由構成、または
pacingに従うアセット処理。名前付きのルックを自由構成する前に、ライブカタログを検索します:ユーザーが要求したすべてのルック、エフェクト、処理、トランジション(「CRTスキャンライン」、「グリッチ」、「フィルムグレイン」、「きらめきスイープ」など)について、npx hyperframes catalog --query "<ルック名、簡単な英語で>" --jsonを実行し、上位の結果を読みます。template-catalog.mdとmotion-primitive-catalog.mdにはこのスキル独自のローカルマテリアルのみがリストされ、検索はホストされたレジストリ全体(約400のブロックとコンポーネント)をランク付けし、何もインストールする必要はありません — プロジェクト、事前のadd、アカウントは不要。検索で適合するものが見つからなかった場合にのみ、ルックを自由構成します。コピーを書きます。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)を修正します;警告はベストエフォートです。その後、チャットでフレームごとの要約を提案として提示し(../hyperframes/references/review-loop.md § 1)、ユーザーが承認するまで返信を繰り返します;storyboard: yes の場合は、それを storyboard.html(../hyperframes-creative/references/storyboard-recipe.md § 3)として書き込み、ユーザーが開けるようにします。自律モードでは、これはチェックポイントゲートです:要約を事前通知として投稿し、続行します(validate-plan.mjs パスは品質ゲートであり、依然としてブロックします)。
ゲート: frame.md がそのままのプリセットコピーである;validate-plan.mjs が終了コード0で終了する;ユーザーが計画を承認した(自律モード:要約が事前通知として投稿された)。
ステップ4:計画からフレームを構築する
目標:すべてのフレームを自己完結型のコンポジションファイルとして構築します。
compositions/frames/ を作成します。sub-agents/frame-worker.md と ../hyperframes/references/subagent-dispatch.md を読んでください。フレームごとに1つのフレームワーカーを、可能な限り並列に派遣します(そうでなければ波状に)。各ワーカーは正確に1つのフレームとこのコンテキストを取得します:
PROJECT_DIR: <絶対パス>
frame_id: <NN-frame_id> # = フレームファイルのステム、例:02-f2;コンポジションID
Your block: `## Frame N — <frame_id>` ブロック 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 (テンプレート)、および
<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 は構造的lintとヘッドレスブラウザのランタイム、レイアウト、モーション、コントラストゲートを1パスで実行します;--snapshots はレビューフレームも出力します。
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
t=0、各フレームの開始、最も強いDROP / SURGE、すべての hard_stops[].t、key_moments[].t で検査します。