Communitygithub.com

craft-music-video

教導 AI Agent 如何規劃、建構與剪輯「音樂影片」,最終產出可逐鏡辯護的動態成品。流程涵蓋 Craft Music Video (`FilmCraft` + `EffectCraft`)、0. MCP 與沙盒前置檢查、1. 角色分工:EffectCraft 與 FilmCraft。適用於接到此類製作任務時。

craft-music-video 是什麼?

此技能「craft-music-video」是專為 AI Agent 設計的詳細工作流程,用於製作音樂影片。它結合了兩個主要領域:EffectCraft(負責 2D 動畫場景、動態圖形、視覺特效以及帶有獨立透明通道的歌詞圖層)與 FilmCraft(負責多軌道主剪輯、節奏同步、音訊混音/母帶、全域調色,以及最終的「含歌詞」與「純淨版」雙版本輸出)。工作流程從 MCP 伺服器與沙盒環境的必要性檢查開始,明確區分 EffectCraft 與 FilmCraft 的職責,確保檔案交換的技術一致性(如強制使用 ProRes 4444 保留透明通道),並提供一套以聽覺為核心的音樂校準方法,包含可人工編輯的 `lyrics_timing.json` 時序檔案。此技能高度依賴共享工具庫(如 `audio_cues.py`、`lyrics_overlay.py`、`ec_runtime.py`),支援 Linux Flatpak 環境,並特別強調避免泛用視覺特效,改以繪製於特定音樂重拍上的自訂動作來充實器樂段落。最終輸出必須經過有聲與無聲的雙重審查,以確保影片在沒有音訊的情況下仍能被充分理解。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NelaBDV/craft-video-kit/tree/HEAD/skills/craft-music-video

在你喜歡的 AI 中提問

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

說明文件

Craft Music Video (FilmCraft + EffectCraft)

可重複使用的工作流程,用於製作與音軌同步的音樂影片,結合了 EffectCraft(2D 場景、動態圖形、視覺特效、獨立的透明歌詞圖層)與 FilmCraft(多軌道主剪輯、節奏同步、音訊混音/母帶、全域調色、雙版本輸出:含歌詞版 + 純淨版)。

常見的 2D 動畫方法(構圖、附帶預備動作的角色姿勢變換、角色/攝影機錨點、EffectCraft 的連結陷阱、圖層疊加順序與文字可讀性):請遵循 craft-2d-animation。

完整的 MCP 參考、經過驗證的引擎指令與 Flatpak 配置:references/mcp-and-commands.md。


0. MCP 與沙盒前置檢查(開始前請先確認)

  1. 確認當前工作階段已啟用 effectcraft 與 filmcraft 的 MCP 伺服器(或能順利切換至其 CLI 版本 effectcraft-cli / filmcraft-cli)。
    • 若缺少這些伺服器,請勿自行發明 API 呼叫:應查閱 references/mcp-and-commands.md 以取得確切的配置方式(Linux Flatpak 的 ai.storyteller.filmcraft / ai.storyteller.effectcraft,或是原生二進位檔,並以 headless 或 bridge 模式執行)。
  2. Linux Flatpak 注意事項:預設情況下,ai.storyteller.effectcraft 僅能存取 xdg-documents、xdg-pictures 與 xdg-videos。若專案位於其他位置(例如 ~/.t3/projects/...),請傳遞 --filesystem=<專案根目錄> 參數或設定覆蓋: flatpak override --user --filesystem=home ai.storyteller.effectcraft
  3. GUI 與 Headless 衝突:絕對不要在圖形介面應用程式與 headless MCP/CLI 中同時開啟同一個 .ecproj 或 .fcproj 檔案。應使用 --bridge 模式來控制已開啟的視窗。

1. 角色分工:EffectCraft 與 FilmCraft

領域EffectCraft (.ecproj)FilmCraft (.fcproj)
主要用途製作 2D 動畫場景 (V01..Vnn)、獨立的透明歌詞圖層 (L01..Lnn)、動態標題、粒子特效、2D/3D 合成多軌道主剪輯(V1 場景 + V2 RGBA 歌詞 + A1 主音訊)、逐格同步、轉場效果、全域調色、雙版本輸出(含歌詞版 + 純淨版)
建立方式comp.new、layer.newText、layer.newShape、layer.newSolid、layer.newAdjustment、add_effect,以及 JSX 腳本 (ec_runtime.py)file.newSequence、timeline.place、timeline.setTrack、timeline.razor、timeline.trim、timeline.move、clip.speedDuration
音樂同步以 audio/lyrics_timing.json 為精確參考點 + 人工聽覺校準;選擇性使用 keys.audioToKeyframes,僅在需要特定測量反應式效果時使用在每個樂段、最後一個重音與黑畫面剪切點添加 markers.add;精確對齊至影格(frame: f0)
外觀設計與色彩圖層樣式、遮罩、貝茲曲線、發光效果、陰影、預先合成 (layer.precompose)Lumetri Color(lumetri.applyPreset、lumetri.setLook、lumetri.applyMatch)、sequence.colorSettings、sequence.applyVideoTransition
音訊中間渲染輸出不包含音訊 (--audio off)原始主音軌保留在 A1 上(預設維持 0.0 dB 以保留原始母帶;僅在要求時才使用 essentialSound.* 或 sequence.normalizeMixTrack)

2. 檔案交換流程與技術一致性

專案資料夾慣例

<project_root>/
├── audio/           # 主音軌 (WAV/FLAC/MP3) + lyrics_timing.json (唯一可編輯的來源)
├── footage/         # 原始影片素材、照片、可能的 Logo
├── renders_vfx/     # EffectCraft 的中間渲染輸出:V01..Vnn.mov (RGB) + L01..Lnn.mov (RGBA)
├── previews/        # PNG 預覽圖 (render-frame) + 含預覽音效的短 MP4 (例如副歌、獨奏)
├── projects/        # .ecproj 與 .fcproj 檔案
├── scripts/         # 特定於此音樂影片的產生器腳本 (重要的 T3 Code 共享工具)
└── exports/         # 最終 1080p 交付檔案:*_lyrics.mp4 與 *_clean.mp4

相容的交換格式

  • 從 EffectCraft 到 FilmCraft 的透明歌詞與疊加層 (V2):
    • 建議使用(單一檔案):QuickTime Apple ProRes 4444 (.mov),設定 format: "prores"、proresProfile: "4444"、channels: "rgba"、audio: "off"。
    • 無損替代方案:PNG 序列或 OpenEXR 序列(channels: "rgba"),在 FilmCraft 中以 image_sequence: true 匯入。
    • 禁止用於 Alpha 通道:H264、Hevc 與 Av1 不支援 Alpha 通道(alpha: false)。
  • 從 EffectCraft 輸出的不透明視覺場景 (V1):
    • format: "prores"、proresProfile: "hq"、channels: "rgb"、audio: "off"。
  • FilmCraft 的最終交付輸出:
    • 網路/串流:format: "h264" (.mp4,預設值 "High Quality 1080p HD")。
    • 歸檔母帶:format: "prores"。(注意:在沒有硬體編碼器的 Linux 系統上,hevc 與 av1 可能無法使用。)

解析度、影格率 (FPS) 與色彩管理一致性

  1. 從一開始就鎖定一組在 EffectCraft (comp.new) 與 FilmCraft (file.newSequence) 之間共享的唯一 (width, height, fps) 組合,例如 1920×1080 且 30 或 24 fps。
  2. 精確對齊影格:計算每個樂段的邊界為整數影格數(f0 / fps .. f1 / fps),確保所有樂段的總和完全符合音軌的實際長度,不會產生偏移或間隙。
  3. 色彩空間:兩個軟體在 SDR 模式下都使用 workingSpace: "rec709"(在 EffectCraft 中使用 file.projectSettings,在 FilmCraft 中使用 sequence.colorSettings;若原始素材為 HDR/Log,則啟用 autoToneMap: true)。
  4. 時間單位轉換:EffectCraft 以秒 (f64) 為單位;FilmCraft 使用tick(254016000000 ticks = 1 秒),並在 timeline.place 中接受 frame / seconds 參數。

3. 關鍵音樂方法(聽覺校準、可編輯時序、獨立歌詞與器樂段落)

A. 聽覺校準與在主音軌上準確測量結尾

  1. 務必透過 audio_cues.py analyze 以 44.1 kHz 取樣率測量原始音軌(hop = 441 = 精確的 10,000 毫秒),絕對不要使用 22.05 kHz 的取樣步長,否則在 3 分鐘的音樂中會產生數百毫秒的偏移。
  2. 在鎖定剪輯之前,先在 MP3/WAV 上確認準確的結尾位置:找出最後一個強拍、最後一個鼓/樂器聲(例如黑畫面剪切點),以及最後殘響直至完全無聲的實際結束時間。
  3. 實際分段聆聽音軌:將歌曲切成有重疊的片段(例如 18 秒長,含 2 秒重疊),然後圍繞轉折點、副歌、和聲與樂句結尾提取較短的片段(使用 audio_cues.py slice),用耳朵聽以鎖定準確的 BPM 與每個人聲的入點。

B. 單一可編輯時序檔 (audio/lyrics_timing.json) 與不確定標記

將所有歌詞時序集中到一個可由人工編輯的 JSON 檔案 (audio/lyrics_timing.json),由 EffectCraft 的產生器腳本讀取:

  • meta:音訊檔案、音訊/影片時長(毫秒)、fps、bpm、first_drum_hit_ms、last_accent_ms、black_cut_ms。
  • sections:邊界 start_ms / end_ms,對齊至影格。
  • phrases:
    • start_ms、end_ms,以及 display_end_ms(必要時延長 +250 至 +600 ms,讓最後一個單詞在畫面或樂段切換時仍保持可讀)。
    • type: "lead" 表示主唱,type: "echo" 則作為獨立條目用於和聲、回應與即興插入。
    • words(逐詞/詞組分割)僅在需要逐詞動畫或視覺重音時使用;否則應完整且清晰地顯示整個樂句。
    • "uncertain": true + "review_note": "..." 應標註於任何不明確的標記上(和聲、回聲、重疊的裝飾音、短促的叫喊),讓使用者能輕鬆手動調整這些標記,無需修改程式碼。

C. 獨立歌詞圖層 (V2 RGBA) 與雙版本輸出(含歌詞版 / 純淨版)

  1. 避免永久黑邊:將每個樂句放置在畫面的空白區域中(請參閱 craft-2d-animation §5),搭配柔和的陰影、安全邊距,以及當 display_end_ms 跨越片段的剪切點時實現自動延續(isContIn / isContOut)。
  2. 專用透明軌道:將歌詞生成到獨立的合成片段 L01..Lnn 中(排除純器樂段落),並渲染為 ProRes 4444 RGBA 格式,然後放置在 FilmCraft 的 V2 軌道上。
  3. 將場景內文字保留在 V1:標誌、螢幕、文字、圖表等,應保留在視覺場景 V01..Vnn 中。
  4. 嚴格一致的雙版本輸出:先導出 含歌詞版(啟用 V2),然後禁用 V2(timeline.setTrack {"track": "V2", "enabled": false})以導出 純淨版,確保兩版本的剪輯與音訊 100% 相同,最後在儲存最終 .fcproj 前重新啟用 V2。

D. 器樂段落期間的視覺動作(禁止通用音訊曲線)

  1. 禁止使用通用的視覺輔助工具:不得使用音訊曲線、示波器波形、裝飾性浮動圓圈等來處理前奏、獨奏或間奏。
  2. 為用耳朵選擇的重拍設計繪製動作:例如門砰地關上、一排天花板燈依序亮起、佈景在吉他獨奏時以紙板/3D 紙藝方式展開、物體滑動,或角色帶有預備動作與停頓的姿勢變換。
  3. 在重拍之間保持畫面穩定:在兩個強拍之間保持清晰穩定的畫面,確保動作易於理解。
  4. 套用常見的 2D 規則:多變的構圖(廣角 / 過肩鏡頭 / 側面 / 特寫)、實心剪影、在進行變換前設置中性的錨點層級(請參閱 craft-2d-animation)。

4. 逐步工作流程

步驟 1 — 聽覺音訊分析與時序骨架

  1. 以 44.1 kHz 取樣率分析主音軌(audio_cues.py analyze),取得準確時長、10 毫秒精度的瞬態資訊以及音軌結尾的細節。
  2. 提取聆聽片段(audio_cues.py slice)並實際聆聽,以確定準確的 BPM、對齊至影格的樂段邊界、樂句、回聲以及最終剪切點。
  3. 初始化並填寫 audio/lyrics_timing.json,對有疑問的標記加上 "uncertain": true + "review_note",然後驗證 JSON 格式(lyrics_overlay.py --validate)。

步驟 2 — 簡短分鏡 / 故事板(在所有大規模渲染之前)

  1. 撰寫一份簡短的剪輯計畫(時間 / 樂段 / 地點與構圖 / 繪製的視覺動作 / 歌詞處理方式)。
  2. 在使用者啟動完整渲染之前,先向其展示此分鏡(以及器樂段落的重點拍點選擇)。

步驟 3 — 在 EffectCraft 中建立場景 (V01..Vnn) 與歌詞 (L01..Lnn)

  1. 按照 craft-2d-animation 的錨點、中性連結與圖層疊加規則,使用 ec_runtime.py 建立 2D 場景 (V01..Vnn)。
  2. 透過 lyrics_overlay.py,直接從 audio/lyrics_timing.json 生成透明的歌詞合成片段(L01..Lnn,排除器樂段落)。
  3. 對關鍵畫面進行快速預覽擷取(render-frame --max-side 960),並對歌詞使用 --transparent 參數,以便在影片渲染前立即修正任何重疊或錨點偏移。
  4. 含音效的短 MP4 預覽(例如 1 段副歌 + 1 段獨奏):僅渲染這 1-2 個段落,並與主音軌的準確片段進行混流,觀看並聆聽它們,以根據需要重新調整回聲的入點、歌詞在畫面切換間的保持效果以及獨奏的可讀性。
  5. 透過 render_ec_batch.sh 執行低功耗完整渲染,輸出至 ./renders_vfx/ 資料夾(每次僅執行一個渲染任務,V* 使用 ProRes HQ RGB,L* 使用 ProRes 4444 RGBA,並透過 ffprobe 自動斷點續傳)。
  6. 儲存 projects/<clip>.ecproj。

步驟 4 — 在 FilmCraft 中進行組裝與雙版本輸出

  1. 透過 assemble_filmcraft.py(或透過 MCP 的操作 file.newProject、file.newSequence、media_import、timeline.place、markers.add)組裝 Rec.709 序列:
    • A1:保持原始主音軌不變(volumeDb: 0.0)
    • V1:將 V01..Vnn.mov 放置在其精確的影格位置(frame: f0)
    • V2:將 L01..Lnn.mov (ProRes 4444 RGBA) 放置於相同的精確影格位置(audio: false)
  2. 驗證序列(inspect sequence)+ 渲染幾格 V1+V2 合成的影格以及僅 V1 的影格,以確認 Alpha 通道裁切是否正確,以及純淨版本中場景內文字是否存在。
  3. 導出含歌詞版 (*_lyrics.mp4),禁用 V2,導出純淨版 (*_clean.mp4),然後重新啟用 V2 並儲存 projects/<clip>.fcproj。

步驟 5 — 強制性最終審查(含音效 + 無音效)

  1. 含音效審查:觀看 *_lyrics.mp4 的導出版本,確認樂句結尾、副歌剪切點、回聲入點、精確的黑畫面剪切點以及原始音軌的乾淨結尾。
  2. 無音效(靜音)審查:從 *_clean.mp4 觀看器樂段落(獨奏、間奏),確認角色的目標與視覺進展在沒有音訊的情況下 100% 可理解,沒有任何殘留的音訊曲線,且場景內文字完好無損。
  3. 呈現交付檔案,並明確列出 lyrics_timing.json 中標記為 "uncertain": true 的參考點。

5. 共享 T3 Code 工具與依賴項目

可重複使用的工具位於 ~/.t3/shared/craft-video/ 目錄下:

工具路徑用於音樂影片的場景
44.1 kHz 音訊分析與切割~/.t3/shared/craft-video/audio_cues.py分析、切片、聆聽、標記瞬態點與樂段(參見步驟 1)
歌詞疊加層產生器~/.t3/shared/craft-video/lyrics_overlay.py從 lyrics_timing.json 在 EffectCraft 中建立 L01..Lnn 合成
EffectCraft 執行器 (JSX 橋接)~/.t3/shared/craft-video/ec_runtime.py在 EffectCraft 中腳本化 2D 場景建立
EffectCraft 批次渲染~/.t3/shared/craft-video/render_ec_batch.shVFX 與歌詞圖層的單一專案批次渲染
FilmCraft 序列組裝~/.t3/shared/craft-video/assemble_filmcraft.py在 FilmCraft 中腳本化最終組裝(V1 + V2 + A1 + 標記點)
EffectCraft 專案建立精靈~/.t3/shared/craft-video/ec_project_wizard.py初始化 .ecproj,設定解析度、影格率與色彩空間
JSON 驗證器~/.t3/shared/craft-video/validate_timing.py在生成歌詞前檢查 lyrics_timing.json 的結構與邊界

6. 常見注意事項與防錯措施

  • 不要強迫餵食音訊曲線。器樂段落中的視覺動作(獨奏、間奏)必須是可敘事的、有目的的拍攝,而不是對波形產生的反應式垃圾。
  • 永遠不要假設使用者的顯示器或專案工作空間。EffectCraft 的中間渲染必須使用 ProRes 4444 或無損序列以保留 Alpha 通道。H.264/HEVC 會破壞透明通道。
  • 永遠不要讓系統在沒有 display_end_ms 的情況下剪切歌詞:始終讓樂句最後一個單詞的持續時間比畫面剪切點長約 300–600 毫秒,以避免詞語在視覺上被「切斷」。
  • 如果 MCP 伺服器未回應,永遠不要回退到虛構的 API。正確的解決方案是查閱 references/mcp-and-commands.md 以取得 CLI 指令或其 Flatpak 配置。
  • 在 Linux 上務必檢查 flatpak 覆蓋,否則 EffectCraft 可能看不到專案資料夾。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能