從程式碼製作影片產生可編輯的 After Effects 專案
目標是產生一個動態設計師可以開啟並像親手建構一樣直接編輯的專案。文字是真實的文字，路徑是形狀圖層，每個物件都是一個具名的預先合成，而攝影機是一個可重新設定關鍵影格的空物件。與之相反的是將渲染完成的幀序列放入合成中，這種方式無法編輯，因此絕不要將其作為主要動畫交付。
此方法包含三個步驟：
- 從渲染器繪製所使用的相同資料匯出場景。
- 將其寫成
scene.json。 - 讓 After Effects 透過執行產生的 ExtendScript 來自行建構專案。
您永遠不會手動撰寫二進位的 .aep 檔案。
renderer data ──export──▶ scene.json + assets/ ──make_jsx.js──▶ build.jsx ──After Effects──▶ project.aep (+ check stills)
隨附腳本（位於 scripts/ 中）：
aelib.jsx：在 After Effects 內部執行的建構器。它讀取場景並建立合成、圖層、關鍵影格、遮罩、效果、遮色片、標記和音訊，然後儲存 .aep 和建構記錄。make_jsx.js：node make_jsx.js [--portable] scene.json build.jsx。檢查場景（遺失資產、錯誤的父層、預先合成順序）並撰寫一個自包含的build.jsx。使用--portable時，路徑會相對於build.jsx，因此資料夾可以壓縮並在另一台電腦上執行，包括 Windows。用於您交付的任何內容。run_in_ae.sh：run_in_ae.sh build.jsx /abs/path/Project.aep [timeout]。在 macOS 上，於已安裝的 After Effects 中執行建構，等待它完成，並輸出記錄。
在撰寫匯出器之前，請先閱讀 references/scene-spec.md。它定義了每個欄位、緩動、已檢查的效果符合名稱和數值範圍，以及會耗費時間的常見陷阱。
工作流程
1. 盤點影片繪製的內容
閱讀渲染器並列出螢幕上出現的所有內容及其移動方式：
- 世界或背景。
- 每個物件或文件。
- 每段文字。
- 攝影機移動。
- 與語詞或節拍同步的時刻。
- 視覺風格：顆粒感、光暈、暗角、動態模糊、淡入淡出。
- 音訊。
對於每個項目，記下其數值的來源（常數、幾何函數、時間檔案）。
2. 將每個元素對應到其 AE 原生形式
選擇動態設計師會手動建構的形式：
| 在程式碼中 | 在 After Effects 中 |
|---|---|
| 在世界中的攝影機移動（平移、縮放、旋轉） | 一個 CAMERA 空物件。錨點 = 攝影機在世界座標中注視的點。縮放 = 變焦。旋轉 = 滾轉。位置 = 合成中心。將所有世界圖層設為其子層。然後 screen = position + R·scale·(p − anchor)，這正是畫布攝影機的變換，因此世界圖層保留程式碼所使用的座標。 |
| 手持抖動、撞擊震動 | 空物件位置和旋轉上的表達式，由以其作用命名的滑桿控制驅動（"手持抖動量"、"撞擊強度"） |
| 物體或文件（印刷品、紙張、卡片、書籍） | 其自身的預先合成，包含邊框、照片、文字、接觸陰影和一個"暗化"實色圖層。以 2 倍尺寸製作，然後將圖層縮放設為 50%。開啟折疊。在預先合成圖層上為其入場動畫設定關鍵影格。 |
| 向量路徑（海岸線、標尺、圓形、線條） | 形狀圖層，每個邏輯片段一個群組，並賦予名稱 |
| 文字 | 文字圖層，使用真實字串和 PostScript 字型名稱。絕不使用預渲染的文字影像。 |
| 程式碼產生的點陣圖（佔位照片、紙張紋理） | 將其匯出為 PNG/JPG 資產，命名以便於替換（"PHOTO — replace me"） |
| 隨著旁白逐字出現的文字 | 一個帶有 reveal: { times: [...] } 的文字圖層。建構器會為每個字設定寫入遮罩的關鍵影格（在 AE 中測量），且文字保持可編輯。 |
| 線條自行繪製 | Trim Paths end 關鍵影格從 0→100 |
| 蓋章或重擊 | 縮放/不透明度關鍵影格，加上攝影機撞擊清單中的一個條目 |
| 主角聚焦/暗化其他 | 每個預先合成內一個帶有保留透明度屬性的黑色"暗化"實色圖層，加上背景上方的一個畫面空間暗化實色圖層，帶有不透明度關鍵影格 |
| 電影風格 | 具名的調整圖層（"LOOK — Soft glow"、"LOOK — Film grain"），一個帶有羽化反向遮罩的暗角實色圖層，一個淡入淡出實色圖層，以及在世界圖層上啟用合成動態模糊。全部取名以便於關閉。 |
| 音訊 | 分開的主幹（人聲、音樂/音效）作為音訊圖層，加上旁白行作為合成標記 |
3. 從真實來源匯出
在現有渲染器中加入匯出路徑，而不是重新輸入數值。例如，暴露其內部結構（module.exports、一個 --export 旗標，或匯入其模組）並撰寫 export_ae.js / export_ae.py。它應產生 scene.json 和一個 assets/ 資料夾。這樣 AE 專案和 MP4 就不會產生偏差，而且故事變更後重新匯出只需一個指令。
讓動畫相符：
- 攝影機和其他曲線。 在有意義的時刻（保持開始和結束、著陸點）放置關鍵影格，而不是每幀都放。為每個關鍵影格賦予該點曲線的真實速度，並使用 33.333% 影響力：這能精確重現三次埃爾米特曲線。如果移動在中途也做了某事（拉近變焦、對數空間變焦），則在移動的 ¼、½ 和 ¾ 處加入關鍵影格及其各自的導數。從渲染器自身的攝影機函數以數值方式取得導數。
- 有符號的速度。 旋轉、縮放和不透明度的速度是有符號的。空間屬性（位置、錨點）僅取大小。
- 逐幀關鍵影格 僅適用於真正不規則的事物，例如閃爍。其他所有內容都應易於抓取和移動。
- 重新計時。 從渲染器使用的同一個檔案（例如
timings.json）讀取時間，因此重新計時旁白也會重新計時專案。
為開啟專案的人設想：
- 每個圖層都以其實際內容命名（"Ink circle (draws on 'Kestrel Point')"、"Map dim (hero focus)"）。
- 在不直觀的內容上加一行
comment。 - 使用標籤進行分組，並為攝影機空物件指定一個獨特的標籤。
- 旁白行以合成標記的形式加入。
4. 建構與檢查
node <skill>/scripts/make_jsx.js --portable --quiet scene.json build.jsx # build.jsx 位於 assets/ 旁邊
<skill>/scripts/run_in_ae.sh build.jsx "/abs/path/My Project.aep" 1500
- 必要條件（一次性，在 AE 中設定）： 設定 → 腳本與表達式 → 啟用"允許腳本寫入檔案和存取網路"。若無此設定，儲存和建構記錄會失敗。如果執行器超時，此設定（或 AE 中開啟的對話框）通常是原因；請使用者檢查。
- 它不會捨棄工作。 如果開啟的 AE 專案有未儲存的變更，建構會停止並在記錄中說明。永遠不要透過捨棄使用者專案來繞過此問題；請他們儲存或關閉專案。對於自動化建構使用
--quiet，這樣訊息會進入記錄，而不是封鎖 AE 的對話框。對於您交付的build.jsx，請在沒有--quiet的情況下重新產生，這樣手動執行它的人會看到訊息。 - 建構記錄（
<專案>.build-log.txt）會列出每個失敗的圖層、效果或屬性。將任何問題視為場景中的錯誤，並在匯出器中修復，而非在 AE 中。 - 檢查靜止幀。 將
project.stills設定為 5–8 個關鍵時間點：一個詞語同步的時刻、著陸中途、一個主角保持、標題。建構器會從主合成渲染它們。它們在儲存後非同步渲染，執行器會等待它們。它們是 16 位元 PNG，ffmpeg 不一定能讀取，因此請使用sips -s format jpeg -Z 1920 in.png --out out.jpg檢視。 - 並排比較 與相同時間點原始渲染的幀。檢查取景、哪個物件是主角、文字顯示是否與詞語同步，以及顏色和亮度。然後修復匯出器並重新建構。AE 中的光暈比畫布的"模糊副本的螢幕"強烈得多，因此從高閾值（約 200/255）和低強度（約 0.2）開始。
如果此機器上未安裝 After Effects，或者編輯者位於另一台電腦上，請勿嘗試啟動它。交付可攜帶資料夾（build.jsx、assets/、scene.json、README）。他們透過 檔案 → 腳本 → 執行腳本檔案… 執行它，.aep 會儲存在 build.jsx 旁邊。README 必須告訴他們先啟用腳本檔案寫入設定，並且必須安裝字型。
5. 交付
交付一個包含以下內容的資料夾：
<名稱>.aepassets/build.jsx和scene.json，以便可以重新建構專案- 匯出器腳本
- 一個簡短的
README.md，說明如何：- 移動攝影機：為 CAMERA 空物件的錨點（注視點）和縮放（變焦）設定關鍵影格
- 更換照片：在專案面板中選擇資產，使用檔案 → 取代素材
- 重新計時詞語：拖曳該圖層的寫入關鍵影格，或在變更時間後重新匯出
- 切換視覺效果圖層
- 變更文字：雙擊它
- 必須安裝哪些字型
清楚告知使用者：
- 哪些是完全匹配的（佈局、時間、關鍵影格）
- 哪些是近似匹配的（AE 的光暈、顆粒感和顏色與畫布合成略有不同）
- 您使用靜止幀檢查了哪些內容，以及哪些內容您沒有檢查（例如完整長度的播放）
過去曾出錯的事項
以下是上述約定背後的原因：
- 形狀或文字圖層上的陰影和模糊不會隨攝影機縮放，因為它們的效果在變換後應用。對於世界空間的光暈和陰影，請使用帶遮罩的實色圖層。
- 預先合成在攝影機放大時會變模糊。 使用折疊變換來解決，並以 2 倍尺寸製作。
- 羽化遮罩會在實色圖層邊緣被切斷。 使光暈實色圖層遠大於光暈本身。
- 字型必須是 PostScript 名稱。 在 AE 中透過快速探測來檢查未知字型：設定
textDocument.font並讀回它。 - ExtendScript 是 ES3，而且它會誤讀鏈式三元運算子（
a ? b : c ? d : e）：改用查詢表或if/else。如果您更改了aelib.jsx，請先在小場景上測試（一個文字圖層、一個形狀、一個預先合成），然後再執行完整建構。