1仕組みと動作原理
エンドツーエンドの7段階ゲート付きワークフロースキル：Step 0 プロジェクト作成（hyperframes.json + assets/bgm.mp3）→ Step 1 音楽解析（audiomap.json）→ Step 2 フレーム骨格（STORYBOARD.md）→ Step 3 ユーザーゲート付き計画入力 → Step 4 フレームごとに1つの frame-worker サブエージェントによる並列ビルド → Step 5 index.html への決定論的アセンブリ → Step 6 ユーザーゲート付き check + render。
skills/music-to-video/SKILL.md
Workflow: Step 0 setup → `hyperframes.json` + `assets/bgm.mp3`; Step 1 analyze → `audiomap.json`; Step 2 skeleton → `STORYBOARD.md` (frames, groups `TBD`); Step 3 plan → complete `STORYBOARD.md` + `frame.md`; Step 4 build → `compositions/frames/NN-*.html`; Step 5 assemble → `index.html`; Step 6 render → `renders/video.mp4`.
2つのユーザーゲート：Step 3 の計画承認と Step 6 のレンダリング承認（autonomous モードでは通知を出して続行）；「Do every step yourself except **Step 4**, where you dispatch **one sub-agent per frame**.」
ビート解析は単一の権威あるスクリプトによって実行：analyze-beatgrid.py（Python：librosa beat tracker + 16分音符バーグリッド + ドラムキット帯域分割分類 + ライザー/グリッチ/ハードストップイベント + エネルギーナラティブ）が決定論的な audiomap.json を生成。SKILL において他のツールや耳コピによるビートの再検出は禁止。
skills/music-to-video/SKILL.md
`analyze-beatgrid.py` is the **only** beat analyzer — never re-measure beats with another tool or by ear. Its energy / density / rolls / onsets / silences are always reliable.
スクリプト先頭 docstring：「Turns a BGM track directly into a deterministic `audiomap.json`… merges: reliable tempo + beat grid + downbeat (librosa beat tracker), metrical position per event, drum-element classification (band-split), special audio events, energy narrative, phrase layer + density budgets」；依存関係：ffmpeg/ffprobe + librosa/numpy/soundfile。
スクリプトは信頼性の低いフィールドに対して実直である：bpm/beats_sec は音楽に明確なリズムが存在する場合のみ信頼可能であり、静かな音楽におけるグリッドはトラッカーによって強制されたメトロノームにすぎない。各フレームのペーシング（beat_cut/phrase_flow）は Step 2 で orchestrator により裁定される。
skills/music-to-video/SKILL.md
Its `bpm` and `beats_sec` are reliable **only when the music is genuinely rhythmic**; on calm music the grid is a metronome the tracker imposed, so pace by phrases and energy instead and never hard-cut to it.
pacing は Step 2 以降の各フレームで必須のフィールドであり、Step 3/4 においてアセットの処理やテンプレート選択を制約する（asset treatment は pacing に従う必要がある）——音楽の知覚的判断をデータ構造として明示的にモデル化。
リソース配分モデル：orchestrator（本スキル）は計画とアセンブリのみを担当し、各フレームは固定のコンテキスト（PROJECT_DIR、frame_id、Storyboard ブロック、audiomap、frame.md、アセットパス、規約）に基づいて単一の composition ファイルを構築する frame-worker サブエージェントに割り当てられる。フレーム数はビート数ではなく「異なる表現処理」に連動（フレーム内で密度を調整）させ、テンポの速い音楽によるサブエージェント数の爆発を防ぐ。
skills/music-to-video/SKILL.md
Extra density goes _inside_ a group, so **frame count tracks distinct treatments, not beats** — a fast track does not blow up the number of sub-agents.
frame-worker.md の検証結果：worker はファイル書き込みのみを行い、hyperframes CLI は実行しない（「those commands operate on the assembled project, which doesn't exist yet」）。Step 6 で orchestrator が一括して check/snapshot/render を実施——明確な規約によりサブエージェントが誤った対象単位で検証を実行するのを防止。
決定論的アセンブリはスクリプトによって担保：assemble-index.mjs はサブエージェントや主観的判断なしに動作し、STORYBOARD の累積 data-start に基づいて各フレームを配置、BGM を track 11 に設定、フレーム間はハードカット（トランジションインジェクター不要——フレームが隙間なくトラックを埋める）；validate-plan.mjs は Step 3 で計画を検証（尺の不一致、フレームの未網羅、src 欠落はハードエラー）。
skills/music-to-video/SKILL.md
`assemble-index.mjs` is deterministic — no subagent, no judgment. It references each frame file at its cumulative `data-start`, mounts `assets/bgm.mp3` on track 11, and hard-cuts frame → frame (frames tile the track with no gaps, so there is **no transition injector**).
「Frame count tracks distinct treatments」+ ハードカットアセンブリ = 検証可能な単純なタイムライン計算：合計時間は audiomap.audio.duration_sec と完全に一致する必要がある（Gate 判定基準）。
明確なアセット/BGM 来歴チェーン：ユーザー提供の音声/動画 → 抽出；未提供 → /media-use を経由した mood→track 生成（プロバイダー認証は media-use に帰属、SKILL は `npx hyperframes auth status` の出力を中継するのみであり「Never write keys into a per-repo .env」と宣言）；オフライン時はローカルプロバイダーがフォールバック。
skills/music-to-video/SKILL.md
If signed out, apply one branch: - **Collaborative:** wait for sign-in or an explicit choice to continue offline with the local provider. - **Autonomous:** state the status and continue through the available local provider.
実行責任の境界：本ワークフロー自体はキーを保持しない；「Auth ownership and offline fallbacks live in `/media-use` `references/setup-providers.md` § Providers.」
2コア機能
01権威あるビート/エネルギー/イベント解析（analyze-beatgrid.py → 決定論的 audiomap.json）
02音楽構造に基づくフレーム骨格設計（hard_stops、key_moments、ロール端、オンセット空白でのフレーム分割、audiomap アンカーへのスナップ）
03テンプレートおよびモーションプリミティブの二層カタログ：L1 templates（card-flyby、held-text-strobe-burst など、program.json 付き）+ L0 motion-primitives（42種の index.html レシピ）
04計画検証（validate-plan.mjs：尺不一致、未網羅、src 欠落のハードエラー検知）と決定論的アセンブリ（assemble-index.mjs）
05アセットのステージング（stage-assets.mjs によりユーザーの画像/動画をフレーム単位で同一ビートグリッドにカット）
06フレーム単位の並列構築（フレームごとに1つの frame-worker サブエージェント）とレジュームテーブル（任意の中間状態からの再開）
07納品前検証ループ：check . --snapshots による t=0、フレーム開始点、DROP-SURGE、hard_stops、最終フレームの目視確認 + ユーザー承認後の render
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| package | Python3 + librosa/numpy/soundfile（analyze-beatgrid.py；缺失时 pip install） |
| cli | ffmpeg/ffprobe（analyze-beatgrid.py 解码） |
| cli | hyperframes CLI（init/update/auth status/check/render；render 带 --skill=music-to-video） |
| network | （间接）pip/npm 官方注册表首次拉包；BGM 生成走 /media-use provider（HeyGen/Lyria 等，auth 属 media-use） |
| network | 产物运行期 CDN（模板引用 jsdelivr gsap/three；作品级依赖） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: python3 analyze-beatgrid.py assets/bgm.mp3 -o audiomap.json（ローカルでのデコード・解析、ffmpeg s
- scripts/ 或 SKILL.md: 外部言語パッケージ依存関係の動的インストールを宣言
- 网络端点: 外部ネットワークアクセスの宣言: pip install（PyPI 公式パッケージ、依存関係欠落時のみ）、npx hyperframes の初回/更新パッケージ取得（npm/GitHub 公式チャネル）
- 本地工作目录: ファイル入出力および成果物出力: videos/<project>/ 配下の一連のプロジェクト成果物：hyperframes.json、assets/bgm.mp3、audiomap.json、STOR
監査ノート： 本ワークフロー自体はクレデンシャルに直接アクセスしません（キーの書き込みを行わないことを明示し、認証は /media-use に帰属）。ただし以下の操作を行います：① ローカル Python 解析の実行（依存関係不足時に PyPI 公式パッケージから `pip install librosa numpy soundfile` を実行）；② 公式 hyperframes CLI の実行（init/update/check/render、render にはユーザー承認が必要）および npm/GitHub 公式チャネル経由のパッケージ取得；③ `npx hyperframes auth status` を実行してアカウントログイン/利用状況を中継（アカウント単位のステータス読み取りであり、平文トークンではない——クレデンシャル接触とみなす場合も統一基準に基づき寛容に説明。キーを読み取らず、外部送信もせず、送信先が公式かつ予測可能であるため orange への引き上げは不要）；④ BGM 生成を /media-use に委譲（クレデンシャル管理は media-use 側で行われ、orange 相当）。外部送信先はすべて公式かつ予測可能なエンドポイントであるため → yellow。
5二重目の独立検証
- [ok] 『analyze-beatgrid.py 是唯一分析器』 — SKILL.md Step 1/Two ideas 两处声明 + 目录实测无其它分析脚本；audio 相关生成/转写均指向 media-use。
- [ok] 帧数与子代理数解耦声称 — SKILL.md 'frame count tracks distinct treatments, not beats' + frame-worker.md 'One frame = one file; groups live inside' 复核一致。
- [ok] worker 不跑 CLI 的纪律 — SKILL.md Step 4 'The worker never runs the `hyperframes` CLI…' + frame-worker.md 'Writing the file is your terminal action; the orchestrator runs lint/check' 双重复核。
- [discrepancy] auth status 是否触碰凭证 — 首轮注记『无凭证面』需细化：Step 0 确实运行 `npx hyperframes auth status` 并中继输出（登录/用量状态，账户级而非明文 token），且 BGM 生成委托 media-use 时其凭证面在 media-use。已在 credential_reads/reason 如实表述并维持 yellow。
- [ok] 渲染门禁与时长一致性判据 — Gate 文本 'the user approved … `renders/video.mp4` exists with audio, duration == audiomap.audio.duration_sec' 与 assemble 的确定性设计自洽。
6結論
最適な用途： 音楽（ファイル、抽出、またはムードから生成）をビート同期した完成動画（リリックビデオ、スライドショー、キネティックプロモーション）に変換するクリエイティブセッションに最適。特にリズムが明確で、ナレーションがなく、アセットゼロでの納品が求められるシナリオに適しており、「決定論的アセンブリ + サブエージェント並列構築 + Gate ワークフロー」の研究における完全な規範モデルでもある。
不向きな用途： ナレーションや解説を含むコンテンツには不向き（→ faceless-explainer や general-video などの /hyperframes 入力一致ワークフローを参照）；音楽がビートを駆動せず単なるBGMとして敷かれているコンテンツには不向き；音楽ファイルがなく生成やログインも拒否されるシナリオには不向き（ローカルプロバイダーを使用しない限り、BGM 不足で Step 0 が停止）。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload music-to-video.tar.gz
sha256:
Option B · Copy Guide for Agent7806505645ff0114…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.