EffectCraft 動態工具包

一個經過測試的工作流程，用於在 EffectCraft 中製作 60 秒的企業動態圖形影片，使其看起來經過設計、同步無誤，且沒有經典的錯誤：場景之間的空格、重疊的語音、被裝飾遮蓋的文字、消失的數字以及與節拍不符的音效。

設計來自於外觀與佈局，而非從頭開始。 從五種經過測試的外觀中選擇一種，將每個場景寫成一個 scene() 呼叫，並包含你的內容和單詞時間，佈局會處理大小、網格、顏色和動態。自行發明風格的代理最終會得到深色漸層、發光模糊和置中的小文字；這是導致生成的宣傳片看起來廉價的最主要原因。

任何代理都可以使用。 所有操作都從 shell 執行（透過 scripts/ec.py 執行 effectcraft-cli）。MCP 為選用。工具包位置：包含此檔案的資料夾（稱之為 $KIT）。

不適用此工具包： 火柴人/角色故事影片（分割畫面「錯誤方式 vs 正確方式」）請改用 stick-figure-story 技能。

黃金法則（原因請參閱 references/）

時間來自資料，而非猜測。 場景計畫存在 timeline.json 中。場景腳本使用 SC("s3") 和 W("s3", "word")（一個單詞被說出的絕對時間）。切勿鍵入像 23.6 這樣的時間。
檢查你建立的每一個場景。 渲染預覽影格（ec.py frames）並開啟 PNG 檔案。能夠無錯誤執行的程式碼仍然可能渲染錯誤。
「完成」代表通過了關卡。 timeline.py check 有 0 個 FAIL，ec.py qa 有 0 個 FAIL，ec.py qa-video 有 0 個 FAIL，並且你已經看過聯絡表。誠實地報告結果，包括警告在內。
使用一種外觀和佈局（references/looks.md）。在選擇之前比較兩種外觀。至少三分之一的場景必須是可視化的（手機/圖示/流程/長條圖，或帶有物件的自訂場景）。自訂場景程式碼用於佈局無法涵蓋的內容（地圖、產品模擬），並且它仍然使用外觀的調色板 P(S.bg) 和字型大小 LOOK.type。
在編寫任何 EffectCraft 腳本之前，請閱讀 references/pitfalls.md。在設計場景之前，請閱讀 references/motion-design.md、references/looks.md 和 references/techniques.md（節拍網格、峰值對齊音效、連續變形、禁用清單）。
品牌不屬於你可以編輯的範圍（references/brand.md）。顯示真實的 Logo 檔案，切勿鍵入名稱作為文字標記。逐字寫入標語。不要發明產品名稱、按鈕標籤或統計資料。填寫 timeline.json 中的 "brand" 區塊，以便 ec.py qa 檢查此項。
通過 QA 並不等同於好的設計。 在編寫場景之前，規劃色彩腳本、視覺效果和標誌性時刻，並在渲染之前以創意總監審查的方式為影片評分（references/design-review.md，與 references/benchmark_sheet.png 比較）。 7b. 真實產品 UI（SaaS、應用程式影片）：請遵循 references/ui-footage.md：僅擷取範例資料，裁切為一個面板，使其可讀（寬度 55% 以上）或將其重建為動畫 UI，每個畫面一個鏡頭，不要有色調統一的縮圖牆，不要發明數字，並在此處建置，以便 QA 關卡能夠執行。
高能量 / 超動感廣告（TikTok 風格，每個口說單詞都有強烈節奏）：請遵循 references/high-energy.md 和 templates/hyper.jsx，而不是使用平靜的佈局。
報告渲染結果，而非你的計畫。 在撰寫報告或交接之前，從最終 MP4（而非預覽）中提取每個場景中間和最後半秒的影格，並檢查每一個聲明：每個台詞在畫面上停留的時間是否足夠長到可以閱讀？每一個繪製的步驟是否確實可見？螢幕截圖是否清晰？長度是否符合簡報和檔案名稱？閱讀每個語音轉錄稿與腳本的比對，並聆聽品牌名稱。在測試中，一個代理的交接描述了四個圖表步驟、三個承諾和「BridgeAxis Technologies」；而影片顯示最後一個步驟在剪輯前 0.3 秒出現，承諾只顯示了半秒鐘，螢幕截圖無法閱讀，並且語音說的是「Bridge Access」。timeline.py check 和 ec.py qa 現在會對未被讀出的語音錯誤以及文字可讀時間少於 min_read 秒的情況發出警告：修正這些警告，不要為它們找藉口。使用你的代理可用的最高推理設定來執行：那個草率的執行是在「低」設定下進行的。

專案佈局

<project>/
  timeline.json        場景計劃 + 音效提示 + 音樂（從 $KIT/templates/timeline.example.json 開始）
  audio_meta.json      語音檔案 + 單詞時間戳記（來自語音步驟）
  soundtrack.wav       由 timeline.py mix 產生
  assets/voice|sfx|bgm|icons|fonts
  scripts/lib.jsx      複製 $KIT/templates/lib.jsx（設定 COMP；外觀提供顏色和字型）
  scripts/look.jsx     由 `ec.py look NAME --accent HEX` 寫入
  scripts/timing.jsx   已產生（timeline.py emit）- 切勿編輯
  scripts/wipes.jsx    已產生（timeline.py emit）- 最後執行
  scripts/reset.jsx, s1.jsx ... s8.jsx
  qa/                  預覽和聯絡表

從 <project>/ 目錄執行每個指令。ec.py 從 timeline.json 讀取專案路徑和合成名稱。

工作流程 A：新影片

0. 簡報。 在建立之前詢問：要匹配的品牌/網站、情緒（大聲 / 平靜 / 技術性 / 豪華）、長度和長寬比、語音（性別/語調），以及是否需要音樂/音效。猜測創意方向是第一個剪輯被拒絕的最常見原因。

1. 設定

mkdir -p <project>/{scripts,assets/{voice,sfx,bgm,icons},qa} && cd <project>
cp $KIT/templates/lib.jsx $KIT/templates/reset.jsx $KIT/templates/s1.jsx scripts/
cp $KIT/templates/timeline.example.json timeline.json   # 編輯專案/合成/輸出名稱
python3 $KIT/scripts/ec.py fonts                         # 安裝外觀的字型（每台機器一次）

將 scripts/lib.jsx 中的 COMP 設定為時間軸的合成名稱。記下品牌的重點色（Logo、網站 CSS、產品）。如果品牌有網站，請閱讀其 CSS 以取得重點色和字型。將 Logo 檔案放入 assets/logo/，並在 timeline.json 中填寫 "brand" 區塊：名稱、精確標語、Logo 檔案，以及任何已核准的產品名稱或 URL（references/brand.md）。

2. 腳本和語音。 寫下 8 行（鉤子、問題、品牌、2-3 個優點、證明、結尾卡片）；60 秒約可容納 110–130 個口說單詞。為每一行產生一個音訊檔案，並將單詞時間戳記放入 audio_meta.json，格式如下：

{"voices": [{"id": "s1", "path": "assets/voice/s1.wav", "duration_s": 6.45,
             "words": [{"word": "Every", "start": 0.30, "end": 0.59}, ...]}]}

首先執行 python3 $KIT/scripts/ec.py doctor。 它會列出這台機器擁有的東西以及如何安裝缺少的內容。當它顯示 ready 時，不要研究或安裝替代方案（edge-tts, Whisper, piper, Playwright）：下面的工具是經過測試的。如果完全沒有語音，請使用 "in+0.5" 偏移量（而非單詞）來計時場景；$KIT/demo/ 是一個完整的無聲範例（ec.py demo 渲染它）。

語音（預設）：本機 Kokoro，女性聲音 af_heart。免費，無需帳戶。模型快取在 ~/.cache/hyperframes/tts/（第一次執行時下載一次）：
```
export HYPERFRAMES_PYTHON=~/.venvs/kokoro/bin/python   # 必要：包含 kokoro-onnx 的虛擬環境
npx hyperframes tts "第一行文字。" -v af_heart -o assets/voice/s1.wav   # 每個檔案一行
```
如果沒有 HYPERFRAMES_PYTHON，它會失敗並顯示「未安裝 kokoro-onnx 套件」。不要使用 pip 安裝任何東西：設定變數即可。
單詞時間戳記：npx hyperframes transcribe assets/voice/s1.wav --json。它使用 Parakeet 模型，在第一次執行後快取於 ~/.cache/hyperframes/parakeet（引擎 auto 會自動選取它）。Parakeet 適用於像 Kokoro 這樣的清晰 TTS 語音。不要在此處傳遞 -e whisper：hyperframes 的 Whisper 引擎（whisper.cpp）尚未設定。對於帶有口音的真人錄音，素材剪輯技能會改用 faster-whisper large-v3-turbo（~/.venvs/asr）。將單詞及其開始和結束時間複製到 audio_meta.json。
音樂和音效：媒體使用音訊引擎（node <skills>/media-use/audio/scripts/audio.mjs --request audio_request.json --out audio_meta.json --only bgm,sfx）。它透過描述從 HeyGen 目錄中檢索，例如 "bgm": {"mode": "retrieve", "query": "warm calm piano"}。<skills> 對於 Claude Code 是 ~/.claude/skills，對於 Codex/OpenCode/DeepSeek 是 ~/.agents/skills。
HeyGen 文字轉語音（透過引擎或 heygen CLI）是替代的語音方案，但免費配額會用完。當配額用完時，請使用 Kokoro。音樂和音效檢索也需要 heygen CLI 已登入（heygen auth login --oauth），除非設定了 HEYGEN_API_BASE；如果沒有，sfx 仍然可以從 media-use 的內建庫中回應，並且使用者可以提供自己的音樂檔案。

記下你實際使用的提供者和語音。

3. 時間軸

python3 $KIT/scripts/timeline.py beats      # 音樂節奏、節拍、小節開始、落點 -> beats.json（需要 "music"）
python3 $KIT/scripts/timeline.py suggest    # 建議場景進/出點 + voice_at；使用 beats.json，場景在節拍處結束
# 貼上到 timeline.json，設定每個場景的 "bg"（light/dark/accent），添加錨定到單詞的音效提示
python3 $KIT/scripts/timeline.py words      # 每個單詞及其絕對時間
python3 $KIT/scripts/timeline.py check      # 必須為 0 FAIL
python3 $KIT/scripts/timeline.py emit       # 寫入 scripts/timing.jsx + scripts/wipes.jsx
python3 $KIT/scripts/timeline.py mix        # 寫入 soundtrack.wav（-14 LUFS）

在節拍上進行剪輯：timeline.py snap 會將現有剪輯點移動到語音仍然合適的節拍上；在場景中，BEAT(n)、DOWNBEAT(n)、nearBeat(t) 和 T.drop 會將時間衝擊和爆破聲與音樂對齊（references/techniques.md）。音效 "at" 可以是一個數字、"beat:12"、"downbeat:3"、"drop"、"s2:late"（s2 語音中的 "late" 一詞；"s2:the#2" = 第二個 "the"）、"wipe:s3"（進入 s3 的轉場）、"in:s3" 或 "out:s3"。添加 "offset"、"vol"、"max"（修剪長度）和 "align": "peak"（聲音的最大音量點落在錨點上：用於撞擊聲和爆破聲）。

4. 規劃，然後編寫場景。 首先在 qa/design_review.md 中撰寫計畫（references/design-review.md，第 1-6 部分）：每行一個場景的色彩腳本、顯示每行內容的視覺效果、每個場景的主角，以及一個標誌性時刻。在 timeline.json 中為每個場景指定一個背景（"bg": "light" | "dark" | "accent"），然後重新執行 timeline.py emit。交替使用它們，使每個剪輯看起來像一個新的章節。為 1-2 個最具衝擊力的時刻（通常是情感高峰）使用 "accent"。將品牌揭露和結尾卡片放在真實 Logo 閱讀效果最好的背景上（通常是淺色），而不是重點色背景上。然後編寫 scripts/s1.jsx ... sN.jsx，每個都是一個帶有佈局的 scene() 呼叫（規格：templates/layouts.jsx 頂部；指南：references/looks.md）：

// scripts/s2.jsx
scene("s2", "list", { label: "問題",
  items: [["抵達延遲。", "late"], ["海關驚喜。", "customs"], ["什麼都*不*告訴你的追蹤。", "tracking", "nothing"]],
  punch: ["太遲了。", "too"] });

*word* 標記一行中的重點部分。時間是來自 timeline.py words 的單詞（"word"、"word#2"、"word+0.3"、"in+0.2"），書寫時不含標點符號。佈局會自動放大或縮小文字以填滿畫面，因此請寫下你想要的文案，讓佈局來決定大小。保持畫面上的台詞簡短：它們是標題，而不是旁白。僅用於佈局無法涵蓋的內容（地圖、產品模擬），請改為複製 $KIT/templates/scene_template.jsx。

確保至少三分之一的場景是可視化的。 僅包含背景文字的影片讀起來像幻燈片，無論字型多好。視覺化佈局會在螢幕上放置一個與旁白相關的物體：phone（手機螢幕上的產品：付款登陸頁、訂單、追蹤更新）、icons（2-4 個帶有標籤的繪製象形圖）、flow（由一條線連接的站點，該線段在每個站點被說出時填滿：客戶 → 手機 → 銀行，倉庫 → 港口 → 門口）和 bars（2-4 個增長的長條：費用、等待時間、之前/之後）。選擇那些旁白描述事物或過程（而非聲明）的場景。

scene("s4", "flow", { label: "運作方式", title: ["*當天*入帳。", "money", "same"],
  nodes: [{ icon: "shop", label: "你賣出", at: "sell" }, { icon: "phone", label: "Tapnest", at: "app" },
          { icon: "bank", label: "你的帳戶", at: "account", note: "當天" }] });

圖示由工具包繪製（無需檔案）：phone card bank cash clock check tick shop bolt chart truck box pin lock user people chat globe send star plane doc。當自訂視覺場景的圖片/物體圖層名稱中包含 "VIS" 時（例如 "s5 VIS map"），它也會被計入；當少於三分之一的場景是可視化時，ec.py qa 會發出警告。不要將 layouts.jsx 複製到專案中：ec.py 會從工具包載入它，而複製會凍結舊版本。

5. 選擇外觀（先閱讀 references/looks.md）。篩選出兩種以不同方式適合品牌的外觀，採用品牌的重點色，並在你的場景上進行比較：

python3 $KIT/scripts/ec.py new
python3 $KIT/scripts/ec.py import soundtrack.wav assets/icons/*.png
python3 $KIT/scripts/ec.py compare editorial swiss --accent FF5B1F   # -> qa/look_compare.png：開啟它
python3 $KIT/scripts/ec.py look editorial --accent FF5B1F             # 套用勝出的外觀

6. 建置和預覽

python3 $KIT/scripts/ec.py run s1 s2 s3 s4 s5 s6 s7 s8 wipes   # s1 建立合成 + 配樂
python3 $KIT/scripts/ec.py frames 2 4 6.5                      # 開啟 qa/frames.png 並查看

預覽每個場景的兩三個時刻。要修復一個場景，請編輯它並執行 ec.py rebuild sN（僅清除該場景，重建它，重新執行轉場）。要重建所有內容（例如更改外觀後）：執行 ec.py run reset s1 ... sN wipes。外觀提供轉場效果；要取代它，請在沒有 "GENERATED" 標題行的情況下編寫你自己的 scripts/wipes.jsx（然後 emit 會保留它）。

7. 調整和最終確定

python3 $KIT/scripts/ec.py qa               # 檢查間距、重疊、品牌、未註冊的圖示等
python3 $KIT/scripts/ec.py render            # -> 最終 MP4
python3 $KIT/scripts/ec.py qa-video          # 檢查最終影片（持續時間、黑畫面、音量）
python3 $KIT/scripts/ec.py contact-sheet     # 從最終 MP4 中的每個場景中間影格產生聯絡表（qa/contact_sheet_final.png）

在繼續之前，執行視覺檢查（規則 9）。

8. 報告

# 動態圖形交付報告

**專案**：<name>
**長度**：<duration>（簡報：<requested>）
**外觀**：<look-name>（重點色 #<hex>）
**語音**：<provider/voice> | **音樂**：<source> | **音效**：<source>

## 場景（#frames_from_final_mp4）
| # | 時間 | 台詞 | 可視化 | 可讀性 | 注意事項 |
|---|---|---|---|---|---|
| 1 | 0.0–6.5 | 鉤子 | 手機動畫 | 完整 6.5 秒 | — |
...

## 品質檢查結果
- `timeline.py check`：PASS（X 個警告，關於 ___）
- `ec.py qa`：PASS（X 個警告，關於 ___）
- `ec.py qa-video`：PASS

## 設計審查評分
- 色彩腳本：___/5
- 視覺化場景：___/5
- 標誌性時刻：___/5
- 旁白同步：___/5

## 注意事項和決策
- 選擇了 <look> 而不是 <other>，因為 ___。
- 品牌要求 ___，因此 ___ 場景被替換。

akdavid4real/effectcraft-motion

effectcraft-motion 是什麼？

在你喜歡的 AI 中提問

說明文件

EffectCraft 動態工具包

黃金法則（原因請參閱 references/）

專案佈局

工作流程 A：新影片

相關技能

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code