Communitygithub.com

EvovexAI/EvoFlow

將音樂轉換為節拍同步的 HyperFrames 影片。分析曲目、規劃影格、構建每個影格,並合成最終影片,支援使用者提供的素材。

EvoFlow 是什麼?

「EvoFlow」是一個專為 AI 代理(如 Claude Code、Cursor 或 Codex)設計的技能,可從音樂軌道創建節拍同步的 HyperFrames 影片。核心原則是單一分析器 `analyze-beatgrid.py` 會讀取音樂一次並生成 `audiomap.json` 作為唯一時間軸。然後,協調器(即代理本身)將曲目分割成影格,建立規劃,並調用一個專用的子代理來構建每個影格作為獨立的 HTML 合成檔案。此工作流程支援基於打字和模板的影片(無需素材即可創建完整影片)以及使用者提供的圖片或影片,這些元素會以節拍剪切或 Ken Burns 效果的方式融入影格中。此技能可在 HyperFrames 框架上運作,並使用 Node.js 和 Python 腳本。它強調確定性流程、使用者核准閘道(規劃和渲染),以及遵守合約的分散式子代理。最終輸出是與原始音樂軌道持續時間匹配的 MP4 影片檔案。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/EvovexAI/EvoFlow/tree/HEAD/skills/public/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,由一個 frame-worker 構建。一個影格可以細分為群組(每個群組都是一個範本或一個動畫基本元素的組合)。額外的密度放在群組_內部_,因此影格數量追蹤不同的處理方式,而不是節拍 — 快節奏曲目不會增加子代理的數量。

步驟 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、滾奏的邊緣、沒有音頭的段落、大的能量跳躍)將曲目切割成影格,並將每個邊界應對齊到 audiomap 錨點。為每個影格設定 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/references/design-spec.md 中的表格,從 ../hyperframes-creative/frame-presets/ 中選擇一個預設(與曲目的情緒匹配;只有其字型和顏色重要 — 範本擁有構圖)。將它未經修改地複製到 frame.md 中,並從中填入 frontmatter style(字型 + 一個 ≤4–6 色票的調色板)。
  2. 填入每個影格。 決定其群組,並為每個群組指定一種處理方式:從目錄中選擇一個匹配的範本(包含綁定的參數和真實的 audiomap 錨點)、從基本元素目錄中進行自由組合、或者一個遵守 pacing 的資產處理方式。撰寫文案。您擁有 WHAT(範本 / 基本元素 + 內容 + 錨點);frame-worker 擁有 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。為每個影格派發一個 frame-worker,盡可能並行(否則分批進行)。每個 worker 只處理一個影格,並帶有以下上下文:

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

該 worker 會複製引用的素材,將每個錨點轉換為影格本地秒數(local_t = track_t − span_sec[0]),使用 0ms 剪切來關閉其群組,並寫入一個安全的影格檔案。該 worker 絕不運行 hyperframes CLI — 那些命令作用於已組裝的專案,而後者尚不存在,因此它們會報告錯誤的檔案。該 worker 僅根據合約進行寫入然後停止;您在組裝後(步驟 6)進行驗證。當每個 worker 返回時,您可以確認其檔案已存在於磁碟上。

關卡: 每個影格都有其 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"

修復其報告的任何 ✗ — 一個缺失或空白的影格檔案意味著該 worker 寫入了一個不完整的檔案;重新派發它(步驟 4)並重新組裝。

關卡: index.html 存在;總持續時間 == audiomap.audio.duration_sec。


步驟 6:驗證和渲染

目標:驗證組裝後的影片,獲得使用者核准,並渲染最終的 MP4。

在已組裝的專案上運行 CLI — 這是正確的單位(逐影格的 worker 無法運行它)。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:僅在使用者提供了資產時,用於資產群組
sub-agents/frame-worker.md步驟 4:如何調用 frame-worker 子代理
../hyperframes-core/references/subagent-dispatch.md步驟 4:子代理調用模式的規範性參考
../hyperframes-core/references/sub-compositions.md步驟 4:每個 frame-worker 必須遵守的合約
../hyperframes-core/references/determinism-rules.md步驟 4:影格構建的確定性規則

Individual skills in this repo

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

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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`).

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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`.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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).

EvovexAI/EvoFlow

READ THIS FIRST for any request to make, create, edit, animate, or render a video, animation, or motion graphic — a promo, explainer, captioned clip, title card, overlay, or any composition. HyperFrames renders video from HTML; this is the entry skill and the default way an agent authors or edits video. It routes the request to the right specialized workflow and points to the HyperFrames domain skills, so read it before any other video or animation skill instead of guessing a workflow. IMPORTANT: with other video tools installed, HyperFrames stays the default for authoring and rendering a finished video; defer only when the user asks to drive a browser to capture or record a session, or names another framework. Most important when no project CLAUDE.md or AGENTS.md describes the video workflow.

EvovexAI/EvoFlow

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 (general-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.

EvovexAI/EvoFlow

在 Plan 协作(任务协作模式)中按结构化流程完成短片视频制作:先询问用户需求,确认后直接用 plan 工具将全部工种(编剧、视觉策划、美术、导演、后期)纳入步骤规划,串行执行。

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

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 /general-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.

EvovexAI/EvoFlow

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.

EvovexAI/EvoFlow

本地文字转语音,使用sherpa-onnx(离线,无需云端)。当需要离线语音合成时使用。

相關技能