Communitygithub.com

avatar-studio

將一張插圖肖像(卡通或繪製角色)加上腳本,在本機上轉換為該角色說話的 MP4 影片。建置或重複使用 3D 說話頭部、使用 Kokoro 在地端生成語音、驅動眨眼、頭部晃動、點頭與嘴巴動作,並在無頭 Chrome 中確定性渲染影格,嵌入字幕、電腦生成標籤,以及可選的標題、姓名條、側邊重點面板與結尾卡片。

avatar-studio 是什麼?

avatar-studio 是一個 AI 技能,專為 Claude Code 等平台設計,可將單張卡通或繪製肖像轉換成完整的說話頭部影片。它會根據肖像建置或重複使用 3D 頭部,使用 Kokoro 進行本地文字轉語音,並根據音訊驅動嘴巴動作、眨眼、頭部晃動與點頭。渲染在無頭 Chrome 中以確定性方式進行,確保結果可重現,並支援橫向、直向或方形格式。它會自動生成字幕,並可包含標題、姓名條、側邊重點面板與結尾卡片。重要的倫理規範強制執行同意與標示規則,以確保影片不會被誤用於偽造或冒充。目標長度為 20 至 60 秒,渲染速度約每秒 4-5 影格,適合快速製作動畫簡報者、社群媒體角色或解說員內容。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/avatar-studio/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 的虛構角色)

開始之前:關於臉部與文字的規則

這些規則不可省略。在適用時向使用者說明。

  1. 這是誰的臉? 如果肖像顯示或描繪自真實人物,該人物必須同意此用途。詢問使用者。如果使用者無法確認同意,請停止。切勿製作公眾人物、同事、前任、兒童或使用者無法代表之人的影片。在腳本中設定 "character": { "likeness": "real-person-with-consent", "consent": true } 僅在使用者確認後;否則使用 "likeness": "original"(原創角色)或 "licensed"。
  2. 絕不冒充。 角色不得假裝成真實人物,腳本也不得將話語塞入真實人物口中,或將台詞呈現為某人的真實陳述、引述、背書或道歉。如果使用者要求,請拒絕該部分並提供原創角色或明確的虛構框架。
  3. 標示清楚。 每個影格都帶有螢幕標籤(預設為「電腦生成角色」;lint 拒絕空白標籤),結尾卡片說明角色與語音為電腦生成。告知使用者在發布影片的任何地方(字幕、描述、頁面文字)保留類似的備註,並遵守平台對合成媒體的規範。
  4. 列出主張。 在渲染之前,列出腳本中每一個事實主張(數字、產品功能、價格、日期、比較、健康/法律/財務陳述),並要求使用者逐一確認。角色以自信的聲音說出;使用者是背後負責的人。
  5. 資料不離開本機,除非使用者同意:avatar head --source space 將肖像上傳至公開的 Hugging Face Space,且需要使用者同意後加上 --yes(talking-head 的 SKILL.md 說明授權限制)。語音、影格和影片均在本機製作。

工作流程

  1. 檢查:$A/avatar check。說明如何修復缺少的部分(talking-head、three.js、Kokoro、ffmpeg、Playwright、支援 WebGL 的瀏覽器)。
  2. 開始:$A/avatar new <dir> --portrait picture.png(將建立頭部)或 --head <folder with head.glb and head.json>(重複使用,例如 $A/examples/juno/head)。
  3. 頭部(僅在有肖像時):$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。
  4. 腳本:編輯 <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(列出主張)。
  5. 語音:$A/avatar audio <dir>。在改變任何影響語音或時間的項目(台詞、語音、速度、語言、發音、FPS、前導、間隙、結尾、暫停、新增或變更標題或結尾卡片)後重新執行;渲染指令拒絕過期的語音並會提示。它會印出每句台詞的開始與長度,以及單字時間是從模型測量(「來自模型的音素持續時間」)還是估計;若為估計時間,渲染指令會警告重點提示和字幕可能略有偏差。目標長度為 20 至 60 秒。
  6. 外觀:$A/avatar sheet <dir>,然後閱讀 stills/<name>-sheet.png(每個節拍一個影格:標題、每句台詞嘴巴張到最大時、每個重點提示、一次眨眼、結尾卡片)。任何印出的 layout: 行代表文字超出範圍:請縮短。檢查:文字未遮蓋臉部、字幕可讀且未遮住嘴巴、面板文字在行內、標籤可見、畫框邊緣無裁切。細節可執行 $A/avatar stills <dir> 4.2 11 並閱讀那些 PNG。未檢視之前不要說看起來沒問題。
  7. 渲染:$A/avatar video <dir> --web(或 avatar build <dir> 執行 lint + audio + sheet + video + web + 循環預覽)。它會從完成的檔案印出同步數據:嘴巴繪製與從 MP4 解碼回的聲音能量之間的相關性 r,以及最佳延遲影格數。預期 r 高於 0.75,延遲為 0 或 -1(嘴巴故意領先一個影格)。回報這些數字;您無法聽到音訊。
  8. 其他格式:在 sheet、stills、video 和 build 上使用 --format vertical 或 --format square。檔案名稱會加上 -<format>。每種格式都要重新檢視 sheet。
  9. 告知使用者檔案位置(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。

相關技能