プラグインインストール: セットアップまたは更新コマンドの前に、このスキルがHyperFramesプラグイン内にある場合は、プラグインインストールルールに従ってください。スタンドアロンインストールの場合は、以下の更新手順を維持します。
最初に、このスキルを最新の状態に保ってください — ユーザーに確認してから実行:
npx hyperframes skills update music-to-video。すべてが最新の場合は高速なno-opです。それ以外の場合は、このスキルと依存するコアドメインスキルを、それらに依存する前に更新します。
music-to-video — 音楽ベース、ビート同期ビデオワークフロー
このスキルを使用して、音楽トラックをビート同期のHyperFramesビデオに変換します。トラックを一度分析し、フレームをレイアウトし、フレームごとの計画を記入し、各フレームをコンポジションとしてビルドします。入力は音楽トラックと、オプションでユーザー提供の画像または動画です — ナレーションやウェブサイトのキャプチャはありません。タイポグラフィとテンプレートが基本です(アセットがゼロでも完全なビデオが可能)。ユーザーが提供したメディアはすべて、同じビートグリッド上にカットされます。
あなたはオーケストレーターです。videos/<project>/ 内で作業します。ステップを順に実行し、各ゲートを通過してから次に進みます。2つのステップでユーザーが必要です:ステップ3(計画承認)とステップ6(レンダリング承認) — どちらも ../hyperframes/references/brief-contract.md に従ったチェックポイントゲートです(ステップ0の前に読んでください):自律モードでは、ステップ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) 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 は空でないディレクトリを拒否します)。編集リクエストはこれをすべてスキップします。
音楽は背骨です — 他のすべてに先立って1つのトラックを確立します。このスキルは高速で高エネルギーのBGMに調整されています:強力なビートグリッドがカットを駆動します(穏やかなトラックでも機能しますが、ビートではなくフレーズでペースを決めます)。ユーザーがオーディオを提供した場合 — 音楽ファイル、または音声を抽出する動画 — それを使用します。それ以外の場合はリクエストからムードを選択し、/media-use(audio/references/bgm.md)を通じてトラックを生成します。ホストアプリが独自の音楽ツールを提供する場合は、それを使用します。最初の認証済みプロバイダーアクションの前に、npx hyperframes auth status を実行し、その出力を一字一句そのまま中継します。サインアウトしている場合は、1つの分岐を適用します:
- 協調的: サインインするか、ローカルプロバイダーでオフラインで続行する明示的な選択を待ちます。
- 自律的: ステータスを伝え、利用可能なローカルプロバイダーで続行します。
必要な音楽機能を満たせるオフラインプロバイダーがない場合は、ブロッカーを表面化します。リポジトリごとの .env にキーを書き込まないでください。認証の所有権とオフラインフォールバックは、/media-use references/setup-providers.md § Providers にあります。結果のトラックは 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で行うものです。
前提条件: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に従う**アセットトリートメント。名前付きのルックをフリーコンポーズする前に、ライブカタログを検索する:ユーザーが要求したすべてのルック、エフェクト、トリートメント、またはトランジション(「CRTスキャンライン」、「グリッチ」、「フィルムグレイン」、「シャイマースイープ」)について、npx hyperframes catalog --query "<the look, in plain English>" --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
あなたのブロック: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を実行する — これが正しく、ビルド可能なユニットである。
cd "$PROJECT_DIR"
npx hyperframes render --output renders/video.mp4
レンダリングが成功したら、ユーザーにファイルを提示し、承認を求めます(BRIEF.md にはレンダリング承認が必要であると記載されていることに注意)。自律モードでは、このゲートをまだ尋ねます。承認されたら、renders/video.mp4 が最終成果物であることを確認します。
ゲート: renders/video.mp4 が存在する。ユーザーが承認した(自律モード:このゲートを尋ねる)。