Communitygithub.com

Aseel1600/Edit01

當使用者擁有音樂曲目(音訊檔或可提取音訊的影片)並想要製作一個節奏同步的 HyperFrames 影片時使用,風格可從平靜到強烈。音樂驅動一切:一個分析器讀取一次,編排器規劃影格並填入每個影格的計劃,再由一個子代理構建每個影格。

Edit01 是什麼?

這個名為 music-to-video 的技能,旨在將任何音樂曲目轉換為節拍同步的 HyperFrames 影片。它是一個高度自動化的工作流程,核心設計圍繞著一個關鍵原則:**一個分析器,你信任它**。技能使用專用的 `analyze-beatgrid.py` 腳本,對音樂進行一次性的節拍分析,並將結果存儲在 `audiomap.json` 中,後續所有節奏相關的決策皆以此為準,避免重複測量。 工作流程從設定專案和音樂來源(`assets/bgm.mp3`)開始,接著分析音樂、建立影格骨架(`STORYBOARD.md`),然後由使用者審閱和填充計劃,包括選擇品牌(字體和調色盤)以及為每個影格指定模板或運動圖元。**每個影格由一個獨立的子代理(frame-worker)平行構建**,生成獨立的 HTML 組合文件。最後,技能會將所有影格組合起來,進行驗證,並在使用者批准後渲染成最終的 MP4 影片。 此技能支援 HyperFrames 平台。其核心價值在於其約束性設計:透過強制執行「單一分析器」和「一個影格一個檔案」的規則,它確保了可預測的輸出和高效的平行處理。此外,技能預設使用純排版和模板即可生成完整影片,使用者提供的任何媒體(圖片或影片)會自動以相同的節拍網格進行裁剪,極大地簡化了節奏同步影片的創作過程。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Aseel1600/Edit01/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,由一個 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 存在;已記下寬高比/長度/影格率以及(如果有)資產清單。


步驟 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/frame-presets/ 中選擇一個預設,使用 ../hyperframes-creative/references/design-spec.md 中的表格(匹配曲目的情緒;只有其字體和顏色重要 — 模板擁有構圖)。將其未經修改複製到 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 執行 headless 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:將一個影格分派給子代理
../hyperframes-core/references/subagent-dispatch.md步驟 4:如何分派子代理
../hyperframes-core/references/sub-compositions.md + determinism-rules.md步驟 4:每個影格檔案的合約

Individual skills in this repo

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

Aseel1600/Edit01

Generate AI videos from text prompts using multiple provider gateways. Use when: (1) Generating videos from text descriptions, (2) Creating AI-generated video clips for content production, (3) Image-to-video generation with a reference image, (4) Choosing between video generation providers (VEO, Kling, Sora, Runway, Seedance, MiniMax, Gemini Omni). Supports gateways: HeyGen API, fal.ai API, Kling official direct API, and the Gemini API (Gemini Omni Flash).

Aseel1600/Edit01

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Aseel1600/Edit01

Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

Aseel1600/Edit01

Review local character animation with schema checks, Playwright browser previews, frame sampling, and FFmpeg/ffprobe final output checks.

Aseel1600/Edit01

Create videos from a text prompt using HeyGen's Video Agent. Use when: (1) Creating a video from a description or idea, (2) Generating explainer, demo, or marketing videos from a prompt, (3) Making a video without specifying exact avatars, voices, or scenes, (4) Quick video prototyping or drafts, (5) One-shot prompt-to-video generation, (6) User says "make me a video" or "create a video about X".

Aseel1600/Edit01

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Aseel1600/Edit01

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Aseel1600/Edit01

Generate expressive, multilingual narration with fish.audio (S1 / S2-generation models) and reuse cloned voices via reference_id. Use when the user prefers fish.audio/Fish Audio TTS, wants a specific playground voice model, or needs high-emotion voice-clone narration.

Aseel1600/Edit01

Use when implementing Disney's 12 animation principles with Framer Motion in React applications

Aseel1600/Edit01

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.

Aseel1600/Edit01

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

Aseel1600/Edit01

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.

Aseel1600/Edit01

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

Aseel1600/Edit01

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.

Aseel1600/Edit01

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

Aseel1600/Edit01

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.

Aseel1600/Edit01

Best practices for Remotion - Video creation in React

Aseel1600/Edit01

Toolkit-specific Remotion patterns — custom transitions, shared components, and project conventions. For core Remotion framework knowledge (hooks, animations, rendering, etc.), see the `remotion-official` skill.

Aseel1600/Edit01

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.

Aseel1600/Edit01

Animate SVG character rigs with GSAP, CSS transforms, Remotion frame control, and HyperFrames-compatible browser previews.

相關技能