Craft Music Video (FilmCraft + EffectCraft)
可重複使用的工作流程,用於製作與音軌同步的音樂影片,結合了 EffectCraft(2D 場景、動態圖形、視覺特效、獨立的透明歌詞圖層)與 FilmCraft(多軌道主剪輯、節奏同步、音訊混音/母帶、全域調色、雙版本輸出:含歌詞版 + 純淨版)。
常見的 2D 動畫方法(構圖、附帶預備動作的角色姿勢變換、角色/攝影機錨點、EffectCraft 的連結陷阱、圖層疊加順序與文字可讀性):請遵循 craft-2d-animation。
完整的 MCP 參考、經過驗證的引擎指令與 Flatpak 配置:references/mcp-and-commands.md。
0. MCP 與沙盒前置檢查(開始前請先確認)
- 確認當前工作階段已啟用
effectcraft與filmcraft的 MCP 伺服器(或能順利切換至其 CLI 版本effectcraft-cli/filmcraft-cli)。- 若缺少這些伺服器,請勿自行發明 API 呼叫:應查閱 references/mcp-and-commands.md 以取得確切的配置方式(Linux Flatpak 的
ai.storyteller.filmcraft/ai.storyteller.effectcraft,或是原生二進位檔,並以 headless 或 bridge 模式執行)。
- 若缺少這些伺服器,請勿自行發明 API 呼叫:應查閱 references/mcp-and-commands.md 以取得確切的配置方式(Linux Flatpak 的
- Linux Flatpak 注意事項:預設情況下,
ai.storyteller.effectcraft僅能存取xdg-documents、xdg-pictures與xdg-videos。若專案位於其他位置(例如~/.t3/projects/...),請傳遞--filesystem=<專案根目錄>參數或設定覆蓋:flatpak override --user --filesystem=home ai.storyteller.effectcraft - 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)。
- 建議使用(單一檔案):QuickTime Apple ProRes 4444 (
- 從 EffectCraft 輸出的不透明視覺場景 (
V1):format: "prores"、proresProfile: "hq"、channels: "rgb"、audio: "off"。
- FilmCraft 的最終交付輸出:
- 網路/串流:
format: "h264"(.mp4,預設值"High Quality 1080p HD")。 - 歸檔母帶:
format: "prores"。(注意:在沒有硬體編碼器的 Linux 系統上,hevc與av1可能無法使用。)
- 網路/串流:
解析度、影格率 (FPS) 與色彩管理一致性
- 從一開始就鎖定一組在 EffectCraft (
comp.new) 與 FilmCraft (file.newSequence) 之間共享的唯一(width, height, fps)組合,例如1920×1080且30或24fps。 - 精確對齊影格:計算每個樂段的邊界為整數影格數(
f0 / fps .. f1 / fps),確保所有樂段的總和完全符合音軌的實際長度,不會產生偏移或間隙。 - 色彩空間:兩個軟體在 SDR 模式下都使用
workingSpace: "rec709"(在 EffectCraft 中使用file.projectSettings,在 FilmCraft 中使用sequence.colorSettings;若原始素材為 HDR/Log,則啟用autoToneMap: true)。 - 時間單位轉換:EffectCraft 以秒 (
f64) 為單位;FilmCraft 使用tick(254016000000ticks =1秒),並在timeline.place中接受frame/seconds參數。
3. 關鍵音樂方法(聽覺校準、可編輯時序、獨立歌詞與器樂段落)
A. 聽覺校準與在主音軌上準確測量結尾
- 務必透過
audio_cues.py analyze以 44.1 kHz 取樣率測量原始音軌(hop = 441= 精確的 10,000 毫秒),絕對不要使用 22.05 kHz 的取樣步長,否則在 3 分鐘的音樂中會產生數百毫秒的偏移。 - 在鎖定剪輯之前,先在 MP3/WAV 上確認準確的結尾位置:找出最後一個強拍、最後一個鼓/樂器聲(例如黑畫面剪切點),以及最後殘響直至完全無聲的實際結束時間。
- 實際分段聆聽音軌:將歌曲切成有重疊的片段(例如 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) 與雙版本輸出(含歌詞版 / 純淨版)
- 避免永久黑邊:將每個樂句放置在畫面的空白區域中(請參閱 craft-2d-animation §5),搭配柔和的陰影、安全邊距,以及當
display_end_ms跨越片段的剪切點時實現自動延續(isContIn/isContOut)。 - 專用透明軌道:將歌詞生成到獨立的合成片段
L01..Lnn中(排除純器樂段落),並渲染為 ProRes 4444 RGBA 格式,然後放置在 FilmCraft 的V2軌道上。 - 將場景內文字保留在
V1:標誌、螢幕、文字、圖表等,應保留在視覺場景V01..Vnn中。 - 嚴格一致的雙版本輸出:先導出 含歌詞版(啟用
V2),然後禁用V2(timeline.setTrack {"track": "V2", "enabled": false})以導出 純淨版,確保兩版本的剪輯與音訊 100% 相同,最後在儲存最終.fcproj前重新啟用V2。
D. 器樂段落期間的視覺動作(禁止通用音訊曲線)
- 禁止使用通用的視覺輔助工具:不得使用音訊曲線、示波器波形、裝飾性浮動圓圈等來處理前奏、獨奏或間奏。
- 為用耳朵選擇的重拍設計繪製動作:例如門砰地關上、一排天花板燈依序亮起、佈景在吉他獨奏時以紙板/3D 紙藝方式展開、物體滑動,或角色帶有預備動作與停頓的姿勢變換。
- 在重拍之間保持畫面穩定:在兩個強拍之間保持清晰穩定的畫面,確保動作易於理解。
- 套用常見的 2D 規則:多變的構圖(廣角 / 過肩鏡頭 / 側面 / 特寫)、實心剪影、在進行變換前設置中性的錨點層級(請參閱 craft-2d-animation)。
4. 逐步工作流程
步驟 1 — 聽覺音訊分析與時序骨架
- 以 44.1 kHz 取樣率分析主音軌(
audio_cues.py analyze),取得準確時長、10 毫秒精度的瞬態資訊以及音軌結尾的細節。 - 提取聆聽片段(
audio_cues.py slice)並實際聆聽,以確定準確的 BPM、對齊至影格的樂段邊界、樂句、回聲以及最終剪切點。 - 初始化並填寫
audio/lyrics_timing.json,對有疑問的標記加上"uncertain": true+"review_note",然後驗證 JSON 格式(lyrics_overlay.py --validate)。
步驟 2 — 簡短分鏡 / 故事板(在所有大規模渲染之前)
- 撰寫一份簡短的剪輯計畫(時間 / 樂段 / 地點與構圖 / 繪製的視覺動作 / 歌詞處理方式)。
- 在使用者啟動完整渲染之前,先向其展示此分鏡(以及器樂段落的重點拍點選擇)。
步驟 3 — 在 EffectCraft 中建立場景 (V01..Vnn) 與歌詞 (L01..Lnn)
- 按照 craft-2d-animation 的錨點、中性連結與圖層疊加規則,使用
ec_runtime.py建立 2D 場景 (V01..Vnn)。 - 透過
lyrics_overlay.py,直接從audio/lyrics_timing.json生成透明的歌詞合成片段(L01..Lnn,排除器樂段落)。 - 對關鍵畫面進行快速預覽擷取(
render-frame --max-side 960),並對歌詞使用--transparent參數,以便在影片渲染前立即修正任何重疊或錨點偏移。 - 含音效的短 MP4 預覽(例如 1 段副歌 + 1 段獨奏):僅渲染這 1-2 個段落,並與主音軌的準確片段進行混流,觀看並聆聽它們,以根據需要重新調整回聲的入點、歌詞在畫面切換間的保持效果以及獨奏的可讀性。
- 透過
render_ec_batch.sh執行低功耗完整渲染,輸出至./renders_vfx/資料夾(每次僅執行一個渲染任務,V*使用 ProRes HQ RGB,L*使用 ProRes 4444 RGBA,並透過ffprobe自動斷點續傳)。 - 儲存
projects/<clip>.ecproj。
步驟 4 — 在 FilmCraft 中進行組裝與雙版本輸出
- 透過
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)
- 驗證序列(
inspect sequence)+ 渲染幾格V1+V2合成的影格以及僅V1的影格,以確認 Alpha 通道裁切是否正確,以及純淨版本中場景內文字是否存在。 - 導出含歌詞版 (
*_lyrics.mp4),禁用V2,導出純淨版 (*_clean.mp4),然後重新啟用V2並儲存projects/<clip>.fcproj。
步驟 5 — 強制性最終審查(含音效 + 無音效)
- 含音效審查:觀看
*_lyrics.mp4的導出版本,確認樂句結尾、副歌剪切點、回聲入點、精確的黑畫面剪切點以及原始音軌的乾淨結尾。 - 無音效(靜音)審查:從
*_clean.mp4觀看器樂段落(獨奏、間奏),確認角色的目標與視覺進展在沒有音訊的情況下 100% 可理解,沒有任何殘留的音訊曲線,且場景內文字完好無損。 - 呈現交付檔案,並明確列出
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.sh | VFX 與歌詞圖層的單一專案批次渲染 |
| 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 可能看不到專案資料夾。