Communitygithub.com

1345AbhishekKumar/starter-nextjs

將音樂曲目轉換為節奏同步的 HyperFrames 影片。適用於使用者提供音訊檔案或影片,並希望獲得從平靜到強烈、與節拍同步的 HyperFrames 影片。

starter-nextjs 是什麼?

此技能將音樂分析、框架編排和子代理組合到一個工作流程中,建立節拍同步的 HyperFrames 影片。它專注於音樂分析,使用單一分析器(`analyze-beatgrid.py`)讀取音軌,然後由協調器根據音樂結構(如能量變化、靜音和關鍵時刻)將音軌分割成框架。每個框架隨後由一個子代理構建,根據每個框架的規劃使用模板或動作基元。它支援縱向、橫向和方形格式,並能整合使用者提供的圖片或影片,將其與節拍網格同步剪輯。平台支援包括 HyperFrames CLI,並整合了 HeyGen 或本地 MusicGen 等音樂生成工具。工作流程包括六個步驟:設定、分析、框架骨架、規劃、構建框架、組裝和渲染,每個步驟都有必須通過的關卡。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-nextjs/tree/HEAD/.agents/skills/music-to-video

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

music-to-video — 單一音樂驅動、節拍同步的影片工作流程

使用此技能將音樂曲目轉換為節拍同步的 HyperFrames 影片。您分析曲目一次,佈局框架,填入每個框架的計劃,並將每個框架構建為一個組合。輸入是音樂曲目加上使用者可選的圖片或影片——沒有旁白,也沒有網站擷取。排版和範本是基礎(完整的影片不需要任何素材);使用者提供的任何媒體都會在同一個節拍網格上被剪輯進來。

您是協調者。在 videos/<project>/ 中工作。按順序執行步驟,並在繼續之前通過每個關卡。有兩個步驟需要使用者:步驟 3(計劃批准)和步驟 6(渲染批准)。除了步驟 4(您為每個框架分派一個子代理)之外,所有步驟都由您自己完成。將設計和動態規則保留在此檔案之外——它們位於 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。

塑造一切的兩個概念

  • 一個分析器,並且您信任它。 analyze-beatgrid.py 是唯一的節拍分析器——永遠不要使用其他工具或憑耳朵重新測量節拍。其能量/密度/滾奏/起始點/靜音始終可靠。其 bpm 和 beats_sec 僅在音樂確實具有節奏性時可靠;對於平靜的音樂,網格是追蹤器強加的節拍器,因此改為根據樂句和能量來定速,永遠不要硬切到它。判斷您處於哪種情況是每個框架的 pacing 的職責(步驟 2)。
  • 一個框架 = 一個檔案;群組存在於內部。 步驟 2 將曲目切割成框架,每個框架成為一個組合檔案 compositions/frames/NN-<frame_id>.html,由一個框架工作者構建。一個框架可以細分為群組(每個群組是一個範本或一個動作基元組合)。額外的密度進入群組_內部_,因此框架計數追蹤不同的處理方式,而不是節拍——快節奏的曲目不會增加子代理的數量。

步驟 0:設定、背景音樂和輸入

目標:建立音樂來源,建立 HyperFrames 專案,並記錄使用者提供的任何媒體。

音樂是主幹——在任何其他事情之前先確定一首曲目。此技能針對快速、高能量的背景音樂進行了調整:強大的節拍網格驅動剪輯(平靜的曲目也可以,但根據樂句而非節拍定速)。如果使用者給了您音訊——一個音樂檔案,或一個要從中提取音訊的影片——請使用它。如果沒有,則生成一個:從使用者的描述中選擇情緒(例如「強勁的合成器浪潮」、「陷阱節拍」、「歡快的企業風格」)並通過 /hyperframes-media(references/bgm.md——有憑證時使用 HeyGen 檢索,否則使用本機 Lyria / MusicGen;ElevenLabs 或其他生成器也可以)製作一個曲目。在生成之前,執行 npx hyperframes auth status 並逐字轉述其輸出(不要改寫或重寫它)——它顯示背景音樂是來自 HeyGen 還是本機 MusicGen,如果未登入,則顯示如何登入。如果未登入,請停止並等待使用者選擇——登入,或使用本機 MusicGen 離線繼續——然後再生成曲目;不要將金鑰寫入每個儲存庫的 .env 檔案中。(在自主模式下,記錄狀態並離線繼續。)有關規範指導,請參閱 /hyperframes-media → Preflight。無論哪種方式,曲目都會放在 assets/bgm.mp3。暫存使用者提供的任何圖片或影片,以便框架可以在節拍網格上將它們編織進來;否則排版承載整個影片。

僅在缺少 hyperframes.json 時初始化。從簡報中以 kebab-case 命名 <project>,例如 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 存在;記錄了寬高比/長度/幀率以及(如果有的話)素材清單。


步驟 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 和一行 feel(步驟 3 將範本與之匹配的純音樂情況)。此處僅進行分類和佈局:將每個框架的 ### Groups 保留為 TBD (Step 3),並將 frontmatter 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(僅當使用者提供了素材時)。就地編輯同一檔案,執行兩件事:

  1. 選擇品牌。 從 ../hyperframes-creative/frame-presets/ 中使用 ../hyperframes-creative/references/design-spec.md 中的表格選擇一個預設(匹配曲目的情緒;只有其字型和顏色重要——範本擁有構圖)。將其未經修改地複製到 frame.md 中,並從中填入 frontmatter style(字型 + 一個 ≤4-6 色板調色板)。
  2. 填入每個框架。 決定其群組並為每個群組指定處理方式:來自目錄的匹配範本(包含綁定參數和真實音訊地圖錨點)、來自基元目錄的自由組合,或一個遵循 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。為每個框架分派一個框架工作者,盡可能並行(否則分批進行)。每個工作者只獲得一個框架和以下上下文:

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 剪輯對其群組進行門控,並寫入一個安全的框架檔案。工作者永遠不會執行 hyperframes CLI——這些命令作用於組合後的專案,而該專案尚不存在,因此它們會報告錯誤的檔案。工作者只需按照合約寫入並停止;您在組裝後驗證(步驟 6)。當每個工作者返回時,您可以確認其檔案已存在於磁碟上。

關卡: 每個框架都有其 compositions/frames/NN-*.html 存在於磁碟上。


步驟 5:組裝

目標:將構建好的框架 + 背景音樂連接到可播放的 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。在 storyboard frontmatter 中設定一次畫布(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步驟 4:框架工作者合約
../hyperframes-core/references/determinism-rules.md步驟 4:框架工作者合約
references/bgm.md步驟 0:背景音樂來源決策
../hyperframes-creative/references/design-spec.md步驟 3:品牌選擇(字型 + 調色板)

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

1345AbhishekKumar/starter-nextjs

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

1345AbhishekKumar/starter-nextjs

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

1345AbhishekKumar/starter-nextjs

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

1345AbhishekKumar/starter-nextjs

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

1345AbhishekKumar/starter-nextjs

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

1345AbhishekKumar/starter-nextjs

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1345AbhishekKumar/starter-nextjs

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

1345AbhishekKumar/starter-nextjs

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1345AbhishekKumar/starter-nextjs

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

1345AbhishekKumar/starter-nextjs

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

1345AbhishekKumar/starter-nextjs

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

1345AbhishekKumar/starter-nextjs

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

1345AbhishekKumar/starter-nextjs

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相關技能