mcpField
H
heygen-digital-avatar

heygen-digital-avatar

github.com/pluviobyte创意与媒体1.7k175 次安装5 周前更新
代码仓库

关于 heygen-digital-avatar

用于 HeyGen 数字人口播制作的技能，负责身份验证、数字人选择、生成及布局，并将完整视频制作交给其他流程。它通过旁白审批、引擎限制和画面质检约束生成步骤。

主要功能

  1. 01HeyGen OAuth 与订阅状态检查
  2. 02固定档案与数字人引擎选择
  3. 03旁白试听及明确审批门槛
  4. 04生成数字人视频并下载母版
  5. 05自适应人脸定位与圆形合成
  6. 06字幕避让及成片质检

适用场景

  1. 01按审批后的旁白生成数字人口播
  2. 02将数字人母版合成为角落圆形头像
  3. 03检查头像居中、字幕间距和媒体信息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pluviobyte/rnskill --skill heygen-digital-avatar

安装后在 Claude Code 中输入/heygen-digital-avatar确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
pluviobyte-profile.json
scripts/
build_request.py
compose_circle_avatar.py
measure_face_center.swift

详细介绍

HeyGen 数字人口播

为视频创建数字人图层。让 ra-video-production-director 负责整个制作流程、字幕、质检和归档；本技能负责 HeyGen 身份验证、数字人选择、生成和已批准的数字人布局。

在编写或批准任何 HeyGen motion_prompt 之前，加载并应用 heygen-avatar-motion。除非用户明确要求其他动作，否则必须使用其动作类别和验证关卡。验证关卡未通过时，绝不提交付费生成任务。

固定配置

构建前读取 references/pluviobyte-profile.json。将其视为机器可读的默认配置。不得替换为同一数字人组中的其他外观。

  • 使用 HeyGen CLI OAuth 和 Creator 订阅额度进行身份验证。运行 HeyGen 命令时，从子进程环境中移除 HEYGEN_API_KEY，以免 shell 变量悄悄切换计费渠道。
  • 使用 references/pluviobyte-profile.json 中指定的横屏 Digital Twin 外观。对于未指定的数字人，使用 Avatar III。精确命名的预设 数字人5 始终表示 Avatar V，并视为明确请求使用高级引擎；不得将其解析为 Avatar III。不得悄悄替换为旧版肖像外观，或替换为同一数字人组中生成的西装／场景外观。
  • 通过 tts-skill 在本地使用 IndexTTS2，语音为 pluvio-indextts2-calm-v1。绝不要求 HeyGen 合成语音，也不得在本地制作时使用 MiniMax 或其他备用方案。
  • 将旁白批准视为付费生成的硬性门槛。首先生成完整的 IndexTTS2 试听版本，将确切的音频文件交给用户，并等待用户明确批准该版本后，才能将音频上传至 HeyGen。如果用户要求制作数字人但没有提到音频批准，提醒用户并停留在试听阶段。任何音频编辑都会使先前的批准失效。
  • 默认使用已批准的 headroom_08 圆形数字人，放置于左下角。只有用户明确表示 全屏数字人 或给出含义明确的同等指示时，才使用全屏／主画布数字人。
  • 使用配置文件中的紧凑中性色圆形样式：240px 肖像内容，带一圈纯白边框，不加彩色强调环。改变画布比例时，保持底部对齐位置稳定。除非用户明确要求更大的数字人或强调数字人，否则不要恢复旧版 300px 肖像或深红色外环。
  • 不要认为所有生成的成片都能使用同一固定裁剪。标准合成器必须采样 5 帧，使用 macOS Vision 测量脸部中心，然后应用配置文件中经人工审核的视觉偏移。对于已批准的黑色 T 恤圆形样式，候选方案 06 将肖像置于数学计算的脸部中心下方 20px，并将水平偏移保持为 0px。重新测量最终圆形图像，并要求脸部中心的平均位置与此偏移目标的误差不超过 2px。配置文件中的裁剪方案是经审核的备用方案，不能证明新的成片已居中。
  • 字幕和重要内容不得进入数字人避让区域。
  • 只有在用户要求更高画质、指定命名预设 数字人5，或 Avatar III 未通过审核后，才能使用 Avatar IV/V。生成前说明预计增加的额度消耗／成本。由于 数字人5 本身就是明确使用 Avatar V 的指令，告知成本后无需再次询问用户是否确认使用该引擎。

工作流

  1. 运行 env -u HEYGEN_API_KEY heygen auth status。要求凭据类型为 oauth、计费类型为 subscription，且套餐为 creator。如任一条件不符， 请在付费生成前停止。

  2. 使用 tts-skill 生成完整的旁白试听；要求提供规范 WAV 文件和 voice_manifest.json，其中 used_fallback=false 且 minimax_used=false。在 提供试听前，检查混合语言的人名和技术术语。

  3. 向用户提供确切的试听 WAV 文件（也可提供便于携带的 MP3），并等待用户明确 确认，例如“音频确认，可以生成数字人”。将获批 WAV 的 SHA-256 记录在 media/audio-approval.json 中。在该记录生成前，不得上传音频、构建 HeyGen 请求或消耗积分。

  4. 上传前立即重新计算 WAV 的 SHA-256。如果与已批准的哈希不同，则撤销批准、 提醒用户，并返回第 3 步。用户要求“继续”“直接制作”或“制作数字人”并不 等同于音频批准，除非用户明确确认了试听音频本身。

  5. 使用 ra-audio-to-subtitles 根据获批的锁定音频生成正式字幕。最终合成前， 必须确保 caption-qc.json 检查通过。

  6. 使用 env -u HEYGEN_API_KEY heygen asset create --file <narration.wav> 上传 获批的锁定 WAV，并将 JSON 响应保存在项目中。提取其资源 ID，不要将凭据复制 到文件或日志中。

  7. 使用 heygen-avatar-motion 对每个语义段落进行分类，保存确切的可执行动作 提示词，并通过验证关卡。说明性正文段落默认要求双手完全不出现在画面中； 仅在有实质意义的结果或结论部分展示手部动作。

  8. 构建请求前，根据指定预设确定引擎。对于未指定的数字人，生成一个 16:9、 1080p 的数字人母版，设置 fit=contain 和 engine.type=avatar_iii。对于 数字人5，生成相同的单个母版，设置 engine.type=avatar_v，并通过高级引擎 防护检查：

    python3 scripts/build_request.py \
  --audio-asset-id '<asset-id>' \
  --title '<project title>' \
  --engine avatar_v \
  --allow-premium-engine \
  --output media/heygen-create-request.json
env -u HEYGEN_API_KEY heygen video create \
  -d media/heygen-create-request.json --wait \
  > media/heygen-create-response.json

  9. 使用 heygen video download 下载完成的母版。所有要求的宽高比均复用这一个 母版。不要仅为更改裁剪、圆形位置、背景或画布比例而额外消耗一次生成额度。

  10. 对于默认布局，使用 scripts/compose_circle_avatar.py 叠加母版。其默认的 --center-mode auto 会对当前母版采样，应用测得的裁剪和经审核的视觉偏移， 然后根据该目标验证渲染后的圆形。归档生成的居中报告。Remotion/HyperFrames 实现必须复现相同的测量值、视觉偏移和 2px 关卡，不得盲目照搬备用方案的 坐标。

  11. 对于明确指定的全屏模式，将 HeyGen 母版用作主视觉，并跳过圆形合成器。在 制作说明中记录 layout=fullscreen_explicit。

  12. 检查媒体流、时长、有代表性的帧、字幕留白、头发完整性、顶部留白缩减、语音 来源和字幕质检。然后按照 ra-video-production-director 完成最终归档交付。

标准合成器

当基础剪辑已符合所需输出尺寸时，使用此方法：

python3 scripts/compose_circle_avatar.py \
  --base <base-video.mp4> \
  --avatar <heygen-master.mp4> \
  --output <final.mp4> \
  --layout auto \
  --audio-source avatar \
  --centering-report <centering-report.json>

auto 支持经批准的 1920x1080 和 1080x1920 布局。对于仅含旁白的合成，数字人 音频为准。仅当锁定旁白已存在于基础剪辑中时，才使用 --audio-source base。 不要混入两份旁白音频。

对于新生成的母版，必须执行自适应面部测量步骤。--center-mode profile 仅在 诊断时使用经审核的黑色 T 形备用裁剪，且仍须通过渲染后的 2px 检查，确保符合 经审核的视觉偏移目标。只有在明确审核通过的手动修正中，才可同时使用 --crop-x 和 --crop-y。切勿仅为修正本地画面构图而重新生成或消耗另一笔 HeyGen 积分。

积分保护

生成前，说明将创建多少个 HeyGen 主版本。默认数量为 1。版式实验必须使用本地重新合成，且不得消耗额外的 HeyGen 积分。将请求/响应 JSON 和下载的主版本保存在项目中，以便重试时能够检测并复用已完成的工作。

输出约定

在工程项目中保留以下产物：

  • media/narration.wav 和 media/voice_manifest.json
  • media/audio-approval.json，其中包含明确获批音频的 SHA-256
  • media/heygen-asset-response.json
  • media/heygen-create-request.json
  • media/heygen-create-response.json
  • media/pluviobyte-avatar-master.mp4
  • 生产用字幕产物和 caption-qc.json
  • 最终 MP4、媒体探测结果、联系表和 SHA-256 记录
  • 居中报告，其中包含采样帧的测量值、审核通过的视觉偏移目标、应用的源裁剪、最终平均中心、各轴目标偏差、容差以及 status: pass

切勿在项目产物中存储 OAuth 令牌或 API 密钥。

评论

支持 Markdown