avatar-studio 是做什麼的?
流程:head(說話頭部:肖像轉換為 head.glb + head.json)→ audio(Kokoro 語音、測量單字時間、每個影格的音量)→ plan(根據音量產生嘴巴動作、種子隨機眨眼與晃動、重音單字點頭、側邊面板視線、時間軸佈局)→ render(每個影格作為 t 的純函數,在無頭 Chrome 中繪製,傳送給 ffmpeg)→ MP4 + 字幕 + 網頁複本。
技能資料夾:~/.claude/skills/avatar-studio/(以下簡稱 $A)。所有指令為 $A/avatar <command> <project>。$A/avatar help 列出指令。需要安裝 talking-head 技能(預設 ~/.claude/skills/talking-head;設定 TALKING_HEAD_DIR 來使用其他資料夾)。
$A/avatar 指令列(check, new, lint, head, audio, sheet, stills, video, build, test)
$A/engine/gen_audio.py 語音、單字時間、每個影格音量(由 "avatar audio" 執行)
$A/engine/lib/ 純粹、經過單元測試的模組:envelope(嘴巴)、motion、layout、plan、lint、captions
$A/engine/page/frame.js 繪製一個影格:背景、頭部(talking-head 的檢視器)、標題、面板、字幕、標籤
$A/references/script.md 每個腳本欄位說明
$A/examples/juno/ 一個完成的範例(Juno,來自 talking-head 的虛構角色)
開始之前:關於臉部與文字的規則
這些規則不可省略。在適用時向使用者說明。
- 這是誰的臉? 如果肖像顯示或描繪自真實人物,該人物必須同意此用途。詢問使用者。如果使用者無法確認同意,請停止。切勿製作公眾人物、同事、前任、兒童或使用者無法代表之人的影片。在腳本中設定
"character": { "likeness": "real-person-with-consent", "consent": true }僅在使用者確認後;否則使用"likeness": "original"(原創角色)或"licensed"。 - 絕不冒充。 角色不得假裝成真實人物,腳本也不得將話語塞入真實人物口中,或將台詞呈現為某人的真實陳述、引述、背書或道歉。如果使用者要求,請拒絕該部分並提供原創角色或明確的虛構框架。
- 標示清楚。 每個影格都帶有螢幕標籤(預設為「電腦生成角色」;lint 拒絕空白標籤),結尾卡片說明角色與語音為電腦生成。告知使用者在發布影片的任何地方(字幕、描述、頁面文字)保留類似的備註,並遵守平台對合成媒體的規範。
- 列出主張。 在渲染之前,列出腳本中每一個事實主張(數字、產品功能、價格、日期、比較、健康/法律/財務陳述),並要求使用者逐一確認。角色以自信的聲音說出;使用者是背後負責的人。
- 資料不離開本機,除非使用者同意:
avatar head --source space將肖像上傳至公開的 Hugging Face Space,且需要使用者同意後加上--yes(talking-head 的 SKILL.md 說明授權限制)。語音、影格和影片均在本機製作。
工作流程
- 檢查:
$A/avatar check。說明如何修復缺少的部分(talking-head、three.js、Kokoro、ffmpeg、Playwright、支援 WebGL 的瀏覽器)。 - 開始:
$A/avatar new <dir> --portrait picture.png(將建立頭部)或--head <folder with head.glb and head.json>(重複使用,例如$A/examples/juno/head)。 - 頭部(僅在有肖像時):
$A/avatar head <dir>。在<dir>/build/head中執行 talking-head(new、mark --auto、shape --source inflate、build、preview),並將結果複製到<dir>/head/。如果肖像自標記後已變更則會停止:以--force(新的自動標記)或--marks FILE重新執行。一次一個 Blender 程序;約需一至兩分鐘。然後閱讀<dir>/build/head/out/preview.png,並依照 talking-head 的 SKILL.md 判斷(眨眼時眼睛遮蓋、嘴巴沿唇線張開)。使用 talking-head 的mark --page修正標記,或傳遞--marks FILE,並再次執行avatar head。 - 腳本:編輯
<dir>/script.json(欄位說明見references/script.md)。保持台詞一至兩句。重點提示為 2 至 6 個單字,附著在同一句台詞中的一個單字上("at": "word")。在每個句子中以*this*標記一個重音單字以觸發點頭。然後執行$A/avatar lint <dir>,直到沒有錯誤(sheet、stills、video和build會自行執行 lint,並拒絕在錯誤存在時渲染:缺少character.likeness、真實人物無consent: true、空白或過長的標籤、專案外的頭部資料夾)。現在執行規則 4(列出主張)。 - 語音:
$A/avatar audio <dir>。在改變任何影響語音或時間的項目(台詞、語音、速度、語言、發音、FPS、前導、間隙、結尾、暫停、新增或變更標題或結尾卡片)後重新執行;渲染指令拒絕過期的語音並會提示。它會印出每句台詞的開始與長度,以及單字時間是從模型測量(「來自模型的音素持續時間」)還是估計;若為估計時間,渲染指令會警告重點提示和字幕可能略有偏差。目標長度為 20 至 60 秒。 - 外觀:
$A/avatar sheet <dir>,然後閱讀stills/<name>-sheet.png(每個節拍一個影格:標題、每句台詞嘴巴張到最大時、每個重點提示、一次眨眼、結尾卡片)。任何印出的layout:行代表文字超出範圍:請縮短。檢查:文字未遮蓋臉部、字幕可讀且未遮住嘴巴、面板文字在行內、標籤可見、畫框邊緣無裁切。細節可執行$A/avatar stills <dir> 4.2 11並閱讀那些 PNG。未檢視之前不要說看起來沒問題。 - 渲染:
$A/avatar video <dir> --web(或avatar build <dir>執行 lint + audio + sheet + video + web + 循環預覽)。它會從完成的檔案印出同步數據:嘴巴繪製與從 MP4 解碼回的聲音能量之間的相關性r,以及最佳延遲影格數。預期 r 高於 0.75,延遲為 0 或 -1(嘴巴故意領先一個影格)。回報這些數字;您無法聽到音訊。 - 其他格式:在
sheet、stills、video和build上使用--format vertical或--format square。檔案名稱會加上-<format>。每種格式都要重新檢視 sheet。 - 告知使用者檔案位置(
out/<name>.mp4、.vtt、.srt、out/web/)、同步數字、下列限制,以及規則 3 和 4。
誠實告知預期效果
- 嘴巴跟隨音量,而非音素:在聲音大時張開,停頓時閉合。適合卡通,不適合唇讀。
- 僅有插圖、正面頭部效果良好(talking-head 的限制適用:使用離線形狀時側面會膨脹,超過約 35 度時側邊會變平)。因此頭部轉動幅度保持很小。
- 實際使用上每部影片只有一個語音(一行台詞可以設定自己的
voice,但螢幕上只有一個角色)。 - 渲染為軟體 WebGL:使用 2 個頁面時約每秒 4 到 5 影格,因此 30 秒橫向影片約需 3 分鐘。
規則
- 最多 2 個瀏覽器頁面(
--workers 1|2),一次一個 Blender 程序。 - 除非使用者希望保留渲染結果,否則不要提交專案的
build/、stills/或out/資料夾。 - 在變更
engine/lib/中的任何內容後,執行$A/avatar test。