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"。 - 绝不冒名顶替。 角色不得假装是真实人物,脚本不得将话语放入真实人物口中,也不得将台词呈现为某人的真实陈述、引用、背书或道歉。如果用户要求这样做,请拒绝该部分,并提供原创角色或明确的虚构框架。
- 标记它。 每一帧都带有屏幕标签(默认 "Computer-generated character";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>。在更改任何影响语音或时间的因素(台词、声音、语速、语言、发音、帧率、前导、间隔、尾部、暂停、添加或更改标题或结尾卡)后再次运行;渲染命令会拒绝过时的语音并给出提示。它会打印每行的开始时间和长度,以及单词时间是从模型测量("from the model's phoneme durations")还是估算的;对于估算的时间,渲染命令会警告要点和字幕可能略微不准确。目标长度为 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 + 循环预览)。它会打印从完成的文件中测量得到的 sync 行:绘制的口型与从 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。