Communitygithub.com

1345AbhishekKumar/starter-supabase

將音樂曲目(音訊檔案或需要擷取音訊的影片)轉換為節拍同步的 HyperFrames 影片。分析音訊一次,規劃畫面,並由專屬子代理逐一建構,支援從平靜到強烈的多種風格。

starter-supabase 是什麼?

此技能提供一個完整的音樂驅動影片生成工作流程,專為 HyperFrames 平台設計。它將一支音樂曲目作為核心輸入,並可選用使用者提供的圖片或影片,自動產生節拍同步的影片。工作流程結構嚴謹:首先透過單一分析器(analyze-beatgrid.py)對音訊進行一次性分析,產生權威的音訊地圖(audiomap.json),確保節拍、能量、密度等數據的一致性。接著,玩家(或稱為協調者)根據分析結果將音樂切割成數個影格,並為每個影格規劃其分鏡、群組、模板與動畫原語,最後交由獨立的影格工作者(frame-worker)子代理平行建構每個影格的 HTML 合成檔。所有影格完成後,由組合腳本(assemble-index.mjs)將其與背景音樂無縫組合成可播放的 index.html,並經過驗證與審核後,最終渲染為 MP4 影片。此技能的核心優勢在於其自動化與確定性:整個流程從分析到建構皆由程式碼與腳本嚴格管控,無需人工干預或主觀節拍判斷,能穩定產出高品質、節拍精準的影片,特別適合需要快速大量產出音樂影片、歌詞影片或動態宣傳片的開發者與創作者。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-supabase/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 存在;記錄了長寬比、長度、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 以及一行 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
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>/(自由式);已整理素材/(素材群組)
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

工作者會 fork 引用的素材,將每個錨點轉換為影格本地秒數(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。在分鏡表 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:為素材群組挑選蒙太奇模式(僅限使用者提供了素材時)

Individual skills in this repo

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

1345AbhishekKumar/starter-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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.

相關技能