skill-motion：動畫影片生成 是做什麼的？
此類影片是一個 JavaScript 檔案，可在 <canvas> 上繪製任何時間點 (seek(t))、包含音軌 (banda.mp3：語音 + 音樂 + 特效)，並渲染成 MP4。約需兩小時工作時間，成本僅為 ElevenLabs 的幾分錢，可逐幀修正，並可在無網路環境下於簡報中即時播放。
兩種模式。 故事（角色、漫畫或柔和風格，用於情感觸動、問候或邀請）與商業（真實產品、節奏、承諾，用於讓觀眾想購買）。開始前先決定模式：若提及「行銷」、「商業」、「專業」、「展示」或「給客戶看」，請閱讀 references/promo.md 並使用 assets/motor-promo.js。
| 需求 | 引擎 | 閱讀文件 |
|---|---|---|
| 生日、家庭、邀請、有角色的故事 | motor-base.js（漫畫）或 motor-suave.js | guion.md、chispa.md |
| 商業廣告、網頁或應用程式展示、給買家的影片、Reels | motor-promo.js + filmar_web.py | promo.md |
| 品牌或產品發表，需科技感、紀錄片風格的鏡頭 | motor-tech.js | motor-visual.md 第 9 節 |
| 傾斜地圖、飛越鏡頭（無需真實網頁） | motor-3d.js | chispa.md |
| 解釋數據或機制：註解、標籤、讀數、技術圖面 | motor-acotaciones.js（可與任何引擎搭配） | motor-visual.md 第 12 節 |
| 環繞或遍歷 3D 場景的鏡頭 | Orbita3D（位於 motor-3d.js 末尾） | motor-visual.md 第 13 節 |
讓它運作的關鍵並非技術，而是三個習慣：所說皆為事實、使用 Deepgram 聆聽而非假設、渲染前以網格圖表檢查。Claude 無法看到或聽到正在播放的影片；這兩個檢查就是它的眼睛和耳朵。
必要條件
Node 18 或更高版本、Python 3、ffmpeg 與 Chrome。語音與音樂需要 ElevenLabs 帳戶 (ELEVENLABS_API_KEY)。「聆聽」結果需要 Deepgram 帳戶 (DEEPGRAM_API_KEY，可選)。請參閱 INSTALAR.md。
各項資源位置
| 我需要 | 檔案 |
|---|---|
| 靈感：達到「驚豔」而非僅「良好」的檢查清單（寫劇本前閱讀） | references/chispa.md |
| 概念、測試過的風格、台詞、角色分配、時間表 | references/guion.md |
| 語音、音樂、特效、混音、使用 Deepgram 聆聽 | references/sonido.md |
| 繪圖引擎、角色與姿勢、漫畫風格、構圖規則 | references/motor-visual.md |
| 渲染、輕量版、簡報、發布、git | references/entrega.md |
| .js 的起點：漫畫風格或柔和風格 | assets/motor-base.js（漫畫）、assets/motor-suave.js（柔和，角色會老化） |
| 觀看影片與網格圖表的頁面 | assets/pelicula.html、assets/hoja.html |
| 在簡報中嵌入影片（投影片 + 控制器）與建構工具 | assets/pelicula-en-presentacion.html、assets/construir.py |
| 腳本 | scripts/（金鑰、語音、音樂、旁白、特效、混音、Deepgram、渲染、輕量版） |
| 內含 CC0 音效 | sfx/（版權聲明在 sfx/LICENSES.md） |
| Canvas 上的偽 3D（傾斜地圖、飛越鏡頭、霓虹地板） | assets/motor-3d.js |
| 品牌與產品發布的「科技專業」風格：紀錄片鏡頭 (HUD)、對焦框、警示、掃描、介面卡片、儀表板、網格地板 | assets/motor-tech.js 與 references/motor-visual.md 第 9 節 |
| 專業商業廣告、產品展示、16:9、9:16 與 1:1 格式 | references/promo.md、assets/motor-promo.js |
| 逐幀擷取真實網頁畫面（含 GPU 加速） | assets/filmar_web.py |
| 客戶簡報與固定影格分鏡表（繪製商業廣告前使用） | assets/brief-cliente.md、assets/storyboard-plantilla.md、references/promo.md |
弧線滑鼠移動、點擊、輸入、彈跳、偏移、漂移與鏡頭推近。商業廣告中所有滑鼠移動皆須為弧線且點擊前有停頓 (cursorPro)；直線移動禁止 | motor-promo.js (cursorPro、cursor、tecleo、entra、escalonar、deriva、empuje)、references/motor-visual.md 第 11 節 |
| 安全區域、向量介面、「渲染前檢查清單」與打磨庫 | references/promo.md |
劇本中的數據以 DATOS 區塊呈現，便於單行修改；無音訊渲染 | references/entrega.md 第 11 節 |
劇本註解（[VISUAL]、停頓）、螢幕上每個數字連同對應文字 | references/guion.md 第 8 節 |
| 鏡頭詞彙（含比例與時間凍結） | references/chispa.md |
| 測量 BPM 並按小節重新排列音樂 | scripts/pulso.py、scripts/cortar_musica.py、references/sonido.md 第 13 節 |
| 測試段落、分段組裝、無需重新渲染即可替換音訊 | references/entrega.md 第 8 節 |
| 因產品變更而修正已交付的影片 | references/entrega.md 第 10 節 |
| 使用真人語音問候與附傳單的邀請 | references/sonido.md 第 9 節、references/entrega.md 第 7 節 |
製作流程
請依序執行以下步驟；每個步驟都有其控制點，完成後才能進入下一步。
0. 現在適合製作影片嗎？ 如果影片將提及商業數據（利潤、價格、客戶數、期限），則在編寫劇本前必須有這些數據的官方聲明來源。若存在兩個模型給出不同數字，或數字仍在討論中，則不製作影片：應告知對方，並提議打開試算表進行討論。一部影片耗時兩小時，並會在觀看者腦中固定一個數字。詳細說明請見 references/guion.md 第 9 節。
1. 概念（與委託人共同決定）。 決定模式（見上文）。首先閱讀 references/chispa.md：格式包含可打破的規則、轉折、以名字稱呼人物、重複出現的角色以及「驚豔」時刻。明確目標受眾、應產生的感受、影片長度與放映場合。提出三個概念，每個以兩三句話說明並附文字預覽，以及調性（已測試的風格列於 references/guion.md）。若委託人已提供想法，請完全遵循：其需求中的每個元素都是一個場景。
2. 驗證將陳述的內容。 影片中關於產品的每一項陳述，都應在其程式碼中找到依據。找不到的內容，不應提及；存在但被隱藏的功能，可以提及並告知委託人。這同樣適用於尚未存在的業務或專案：每個數字都應在 GUION.md 中標註來源，並歸類為事實、假設或提議；具有法律約束力的詞語（「保證」、「已存在」、「數秒內」、「符合法規」、價格）只有在已決定並有書面記錄時才能使用（見 references/guion.md 第 9 節）。
3. 劇本。 在影片專案資料夾中建立 GUION.md：包含委託人的原始需求、語音、音樂，以及一個包含秒數、說話者、台詞與畫面的表格。台詞應簡短、每句獨立、使用中性語言、避免長破折號。
4. 語音。 執行 source scripts/llaves.sh 與 scripts/voces.py frases.json。使用 Deepgram 聆聽；對不滿意的語音以 --solo 重新生成。若旁白來自委託人的語音備忘錄，則無需台詞檔案：見 references/sonido.md 第 9 與 10 節。
5. 時間。 執行 scripts/armar_narracion.py <inicios> --total <s>：在語句之間保留空白，讓畫面自行敘事。使用 Deepgram 產生 palabras.json（每個詞的秒數）以進行同步。
6. 音樂。 根據場景規劃音樂段落（scripts/musica.py）；使用 scripts/pulso.py 測量節拍與音量。若段落位置不理想，使用 scripts/cortar_musica.py 重新排列。
7. 混音。 使用內含的 CC0 音效庫（sfx/）與合成特效（scripts/efectos_sinteticos.py），執行 scripts/mezclar.py efectos.json 將音訊調整至 -16 LUFS。控制點： 執行 oir_con_deepgram.py --comparar 比較純旁白與完整音軌：不得遺漏任何詞語。若有遺漏，降低該時間點的音效音量或在音樂中開出空隙。
8. 繪圖。 商業廣告中，先完成簡報與固定影格分鏡表（assets/brief-cliente.md），並拍攝產品畫面（references/promo.md）。複製對應風格的引擎（assets/motor-base.js 漫畫、assets/motor-suave.js 柔和或 assets/motor-promo.js 商業）至 mi-pelicula/pelicula.js，更改全域變數名稱，根據時間表為每個場景編寫函數。從 assets/ 複製 pelicula.html 與 hoja.html（修改 .js 與全域變數名稱；若使用其他字型則需新增）。使用通用角色，切勿使用真實人物。
9. 網格圖表。 執行 source scripts/preparar_render.sh 與 node $R/render.mjs pelicula.html fotos.png --stills ...，為每張圖表選取 9 個瞬間，涵蓋整部影片。檢查圖表，修正任何被遮擋、裁切、過小、錯位或難以辨識的內容（常見錯誤清單見 references/motor-visual.md），然後再次檢查。商業廣告中，設定 SEGURAS=1 可繪製安全區域，promo.md 則提供「渲染前檢查清單」。
10. 渲染。 在背景執行 node $R/render.mjs pelicula.html <路徑>.mp4 30 1 6；將 MP4 複製到影片專案資料夾；執行 scripts/liviano.sh 製作可透過即時通訊傳送的輕量版本。檢查輕量版的某一幀。若風格變動較大，可先渲染測試段落讓委託人預覽動態效果（見 references/entrega.md 第 8 節）。若僅音訊變更，無需重新渲染：直接將新音軌與無聲影片合併。
10.b 讀取影片文字。 執行 scripts/revisar_texto.sh <路徑>.mp4 "詞語1|詞語2"：對最終 MP4 進行 OCR（每秒 1 幀），比對產品中已移除的詞語（需安裝 tesseract）。按鈕上的文字會保留在影片專案檔案中：若產品詞彙變更，需重新要求並重新拍攝（見 references/entrega.md 第 10 節）。
11. 交付。 交付 MP4 並附上逐場景摘要、已驗證的項目以及委託人的決定。可從同一影片產生傳單（references/entrega.md 第 6 與 7 節）。若需嵌入簡報：使用 data-peli 屬性的投影片、控制器、字型、construir.py，並在瀏覽器中測試。
12. 儲存。 將 GUION、.js、頁面、音訊 mp3 與 json 提交至 git（wav 與 mp4 除外）；在專案資料夾的 README 中加入條目。
不可協商的規則
- 真實： 不得編造關於產品或真實人物的內容。敏感話題（跌倒、健康）需以樸實、誠實的小字呈現。
- 金鑰： 透過
llaves.sh從環境變數讀取，絕不輸出或寫入檔案。 - 不抄襲作品： 可參考知名影片的調性（「像《天外奇蹟》」、「超級英雄預告片」），但絕不能使用其角色、場景、音樂或名稱。
- 純時間函數：
seek(t)不得有狀態、不得使用Math.random()（改用rng）、不得使用setTimeout。若某幀依賴前一幀，渲染結果將與即時播放不同。 - 一部影片固定一個數字： 無官方數據來源則不製作影片。每部影片應在其資料夾的 README 中記錄狀態（草稿、已批准、觀看者與版本），若在第三方觀看後重新製作，需告知委託人哪個數字已變更（
references/entrega.md第 12 節）。 - 測量，而非假設： 「聽起來不錯」與「看起來不錯」僅在通過 Deepgram 與網格圖表檢查後成立。
參考時間（一分鐘影片）
劇本與語音 20 分鐘；時間、音樂與混音 20 分鐘；繪圖 40 至 60 分鐘；網格圖表與修正 20 分鐘；渲染與輕量版 5 分鐘；簡報與發布 15 分鐘。視覺修正屬正常情況：每部影片約有 5 至 10 處。一段 97 秒的網頁拍攝商業廣告：渲染 48 秒，含動態模糊約 3 分鐘。若修正發生在渲染之後，則需重新渲染。
若應用程式中途關閉
所有重要資料（音訊、.js、GUION）已存在於影片專案資料夾中，渲染器可透過 ~/.cache/skill-motion-render 中的 preparar_render.sh 自動重建。請在每次較長任務前記錄目前的步驟。