Communitygithub.com

avatar-studio

将一张插画肖像(卡通或手绘角色)配合脚本,在本机上生成该角色说话的 MP4 视频。

avatar-studio 是什么?

avatar-studio 是一个完整的本地化 AI 代理技能,用于快速制作会说话的虚拟角色视频。用户只需提供一张正面卡通或手绘肖像和一段脚本,即可自动生成带口型、眨眼、点头、头部摆动等动作的 MP4 视频。该技能构建或复用 3D 说话头模型,使用 Kokoro 本地语音合成生成语音,通过音频响度驱动口型,并利用无头 Chrome 确定性地渲染每一帧。输出支持横屏、竖屏和方形格式,并内置字幕、计算机生成标识、可选的标题、姓名条、侧边要点面板和结尾卡。适用于动画演示、虚拟主播、社交媒体讲解视频等场景。严禁用于未经授权的真实人物照片、深度伪造或冒名顶替。

兼容平台✓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. 标记它。 每一帧都带有屏幕标签(默认 "Computer-generated character";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>。在更改任何影响语音或时间的因素(台词、声音、语速、语言、发音、帧率、前导、间隔、尾部、暂停、添加或更改标题或结尾卡)后再次运行;渲染命令会拒绝过时的语音并给出提示。它会打印每行的开始时间和长度,以及单词时间是从模型测量("from the model's phoneme durations")还是估算的;对于估算的时间,渲染命令会警告要点和字幕可能略微不准确。目标长度为 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 + 循环预览)。它会打印从完成的文件中测量得到的 sync 行:绘制的口型与从 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。

相关技能