Communitygithub.com

AvatarAdDirector / 头像广告导演

将 SaaS 项目的品牌和截图转化为 ≤60 秒的 9:16 UGC 风格广告——以 HeyGen 逼真头像片段为骨架,在 Remotion 中合成截图、关键词弹出字幕和轻柔背景音乐,本地渲染为带字幕和无字幕的 MP4 文件。唯一付费步骤(HeyGen 头像渲染)有硬性闸门。

头像广告导演 是什么?

AvatarAdDirector 是一个 AI 驱动的技能,用于为真实 SaaS 应用制作≤60 秒、9:16 竖屏 UGC 风格广告。它以单个 HeyGen 逼真头像片段为核心(承载整个画外音,包括视频和音频),所有其他元素(截图、关键词弹出字幕、布局区域、音乐)都是通过 Remotion 合成的时间窗口叠加层。该技能严格遵循成本闸门:HeyGen 头像渲染是唯一需要付费的步骤,默认 Jibran 数字孪生风格约需 4 美元/分钟,必须获得用户明确许可后才能执行。所有其他操作(包括使用 Kokoro 占位符、转录、故事板、合成和重新渲染)都是免费的,并基于缓存片段运行。工作流程分为多个阶段:从收集品牌资产和截图开始,然后根据六步去套路化流程编写脚本,通过脚本质量检查清单,使用 HeyGen 或 Kokoro 占位符生成头像,转录字幕时间码,布局包含截图和关键词弹出字幕的故事板,最后合成并输出带字幕的 MP4、无字幕的 MP4 和 SRT 文件。该技能还包含风险词汇拼写纠正机制,确保品牌名称在 TTS 中正确发音,但屏幕文本保持正确拼写。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/baldiga/headless-studio/tree/HEAD/skills/avatar-ad-director

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

头像广告导演 是做什么的?

你正在导演一段 ≤60 秒、9:16(1080×1920) 的 UGC 风格广告,面向一个真实的 SaaS 应用。单个 HeyGen 逼真头像片段是骨架(它承载整个画外音——视频和音频);其他所有元素(截图、关键词弹出字幕、布局区域、音乐)都是通过 Remotion 合成在该片段之上的时间窗口叠加层。CLI 脚本负责具体操作,你负责判断。所有命令从仓库根目录运行;所有产物保存在 jobs/<slug>/ 目录下。

在编写脚本之前,先阅读 references/ad-script-playbook.md;在创作故事板之前,先阅读 references/layout-library.md。严格遵循它们。

两条硬性规则(永远不得违反)

  1. 成本闸门。 唯一需要付费的操作是 HeyGen 头像渲染(scripts/heygen.ts generate <job> --confirm)。在没有打印成本估算并在同一轮对话中获得用户明确“是”的情况下,绝对不要运行它。默认的 Jibran 数字孪生外观按约 4 美元/分钟计费(而非 1 美元/分钟);成本闸门对任何非 standard 引擎都引用 4 美元/分钟档次。其他所有操作——摄取、Kokoro 占位符、转录、故事板、合成、重新渲染——都是免费的,并基于缓存片段运行。参见 references/cost-gate.md。
  2. 不允许使用 em 破折号。 任何屏幕文本——字幕、关键词弹出、行动号召——都不得包含 —(U+2014)或 –(U+2013)。它们是 AI 痕迹。AvatarAdSchema 在解析时拒绝它们,Stage 6 会通过 grep 检查 SRT 确认。另外,使脚本人性化(应用“人性化”指南),并保持屏幕文本不超过 7 个单词。

迭代循环是:编辑故事板/字幕/音乐 → ad-compose.ts → 审查。仅当 ad-script.md 发生变化时才重新生成付费头像片段。

Stage 0 — 简报与素材

  1. 向用户提问(一条消息,所有问题):产品名称 + URL;目标受众;广告的目标、卖点和行动号召(文本 + URL);一个素材文件夹路径(截图、Logo);可选音乐文件路径。如果项目已有 brand.json,则复用;否则整理一份。

  2. 打印 HeyGen 余额和成本闸门提示:heygen auth status(免费,只读)显示 remaining_balance。

  3. 编写 jobs/<slug>/ad-project.json,匹配 AdProjectSchema(参见 src/ad-schemas.ts)。Slug 使用小写短横线格式。你通常保留的默认值:heygen.group 为 YOUR_AVATAR_GROUP_ID(Jibran),heygen.voiceId 为 YOUR_VOICE_ID(Jibran 自己的默认声音——Jibran 外观优先选择此声音,使声音与面部匹配),resolution 为 1080p,music.gain 为 0.2,music.duckRatio 为 16,viewport 为 1080×1920,fps 为 30。从品牌背景(头像渲染所用的纯色背景)设置 brandBgHex。

  4. 风险词汇拼写纠正(pronunciations)。 品牌名称和非常规拼写在 TTS 中经常被读错。向项目添加一个 pronunciations 映射(正确拼写 -> 口拼),例如 { "ZOOQ": "Zuk" }(默认)。此映射仅在 HeyGen 渲染前应用于口语脚本(不区分大小写的全词匹配,外加 zooq.dev/zooq dev -> Zuk dev)。屏幕文本、字幕和行动号召卡片始终保持正确拼写——绝不对它们进行重拼。拼写纠正位于 scripts/heygen.ts(applyPronunciations)中,并在 generate 中自动运行。

  5. 将 brand/brand.json 和选定的截图复制到作业目录。然后编目素材:

    npx tsx scripts/ingest-assets.ts <job>
    

    这会写入 <assetDir>/asset-catalog.json(路径、尺寸、透明度、种类、usable)。任何 usable: false 的素材在其短边低于 600 像素——标记它并提供清晰的 Playwright 重新捕获(scripts/capture.ts),而不是放大低分辨率截图直到文字被裁剪。

Stage 1 — 脚本(然后通过 Gate 1)

首先阅读所有三个脚本编写参考:references/scriptwriting-methodology.md(权威的 DR / PAS / 钩子 / 行动号召参考)、references/ad-script-playbook.md(在此应用它的六步流程)和 references/script-quality-checklist.md(人工闸门)。去套路化闸门是强制性的:脚本不能到达头像,直到 script-lint.ts 报告 0 个硬性问题并通过检查清单。

  1. 按照方法论编写。 遵循 ad-script-playbook.md 中的六步流程,编写 jobs/<slug>/ad-script.md:一个约 ≤150 词、≤60 秒的第一人称 UGC 广告。从真实公式开始(不是“每个人都在构建 X”)-> 问题 + 煽动(具体的、有感觉的)-> 创造者声音的解决方案 -> 具体证据 -> 一个行动号召 -> 去套路化通过。没有 em 破折号,没有企业或 AI 词汇。整个文件由头像口述,因此将其写为干净的散文(没有舞台指导,没有 TTS 会读出来的标题)。

  2. 运行 lint 闸门。 它必须报告 0 个硬性问题:

    npx tsx scripts/script-lint.ts jobs/<slug>/ad-script.md
    

    硬性问题(破折号、禁用词)导致闸门失败,全部修复。将每个软性问题(三法则堆叠、没有第一人称、重复开头、填充词)视为需要回答的问题,而非命令。

  3. 通过检查清单。 浏览 references/script-quality-checklist.md,并朗读脚本。“创作者真的会大声说出这句话吗?”是 linter 无法自动化的闸门。

  4. 在脑海中或作为注释勾勒节奏/布局计划:哪些节奏是全屏头像(钩子、行动号召)vs 分屏(演示、证据),以及每个截图出现在哪里。你将在 Stage 4 的故事板中编码它。参见 references/layout-library.md。

  5. Gate 1 — 脚本批准。 向用户展示完整脚本和节奏/布局计划。获得明确批准。只有到那时才生成头像。在此闸门之前不会发生任何付费操作。

Stage 2 — 头像

你有两条路径。始终先干运行。

干运行占位符($0,迭代默认):

npx tsx scripts/heygen.ts placeholder <job>

Kokoro TTS 朗读脚本,生成一个纯品牌背景的 9:16 视频,并写入 jobs/<slug>/avatar/clip.mp4 + jobs/<slug>/avatar/clip.timing.json。不需要 HeyGen 调用。使用此片段免费构建和验证整个合成路径。占位符已经发出时间码,因此你可以在干运行时跳过 Stage 3。

付费真实渲染(Gate — 需要用户明确同意):

npx tsx scripts/heygen.ts generate <job>            # 打印估算,然后退出 2(无支出)
npx tsx scripts/heygen.ts generate <job> --confirm  # 实际支出——仅当用户说“是”之后

没有 --confirm 时,它会解析外观,打印 estimated cost: $N,并拒绝(退出 2)。估算是 ceil(durationSec / 60) × rate,其中 rate 仅对明确的 standard 引擎为 1;默认的 Jibran 数字孪生外观按约 4 美元/分钟档次计费,因此任何未设置/默认的引擎报价为 4 美元/分钟(绝不报低)。在此渲染之前,口语脚本通过 pronunciations 进行了重拼;屏幕文本保持不变。重新打印估算和剩余余额,获得用户明确的“是”,然后添加 --confirm。脚本下载到 jobs/<slug>/avatar/clip.mp4。参见 references/heygen-cli.md 和 references/cost-gate.md。缓存片段;除非脚本更改,否则绝不重新生成。

Stage 3 — 字幕时间码(仅限真实片段)

在付费渲染后,将真实头像音频转录为单词时间戳:

npx tsx scripts/transcribe.ts <job>

这会提取片段的音频,运行 whisper.cpp(@remotion/install-whisper-cpp,令牌级别时间戳),并写入 jobs/<slug>/avatar/clip.timing.json(TimingSchema,sceneId: "avatar")。Kokoro 占位符已经写入此文件,因此在干运行时可跳过转录。

Stage 4 — 组装故事板(免费)

对于更丰富的 V2 视觉系统——关键词 B-roll、大标题卡片、纸效显示以及广告 3D 粗体 3D 单词弹出——请阅读 references/v2-assets-layer.md 并使用 scripts/build-v2-storyboard.ts 构建(它将节奏映射到 V2 种类并通过 scripts/media.ts 获取 B-roll)。V2 是附加的:仅使用 V1 种类的故事板会不变地渲染。

  1. 重新阅读 references/layout-library.md。编写 jobs/<slug>/ad-storyboard.json,匹配 AvatarAdSchema:在头像时间线上排序布局 segments 以及 captions 数组。
  2. 典型弧线:avatarFull(钩子)→ split(演示:截图 + 关键词弹出)→ split(证据)→ outro(干净的行动号召卡片)。各片段必须升序且不重叠;最后一个片段的 toMs 应大致落在片段时长处。
  3. 从 clip.timing.json 的单词 startMs 创作短语关键词弹出字幕:1–4 个单词的短语,每个带一个重音词,不重叠,没有 em 破折号。不要凭空编造 atMs——从时间码文件中读取。字幕贯穿所有片段并显示在顶层。

Stage 5 — 合成(预览,然后最终)

npx tsx scripts/ad-compose.ts <job>           # 快速半尺寸预览,不混音音乐
npx tsx scripts/ad-compose.ts <job> --final   # 完整渲染 + 闪避音乐 + 干净变体 + SRT

--final 渲染 1080×1920,混入背景音乐(music.gain ≈ 0.2,music.duckRatio 侧链闪避,loudnorm I=-14:TP=-1),并输出:

  • jobs/<slug>/render/ad-captioned.mp4 — 字幕已烧录
  • jobs/<slug>/render/ad-clean.mp4 — 无字幕(SRT 侧载),音乐相同
  • jobs/<slug>/render/ad-captions.srt

在此可以自由迭代:编辑故事板、字幕或音乐,然后重新运行合成,成本为 0 美元。

Stage 6 — 交付与验证

在报告之前运行验收检查:

ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 jobs/<job>/render/ad-captioned.mp4   # 1080,1920
ffmpeg -i jobs/<job>/render/ad-captioned.mp4 -af volumedetect -f null - 2>&1 | grep mean_volume                          # 非静音
grep -P "[\x{2013}\x{2014}]" jobs/<job>/render/ad-captions.srt && echo "发现 EM 破折号(失败)" || echo "无 em 破折号,正常"

提取几帧并查看:分屏是否存在,截图是否没有裁剪字幕文本,字幕是否与语音对齐,结尾是否干净。报告两个 MP4、SRT、缓存的头像片段(用于复用)以及总支出。

参考文件

  • references/scriptwriting-methodology.md — 权威的 DR / PAS / AIDA / 钩子 / 行动号召参考。
  • references/ad-script-playbook.md — 六步去套路化流程 + 硬性规则 + em 破折号禁令。
  • references/script-quality-checklist.md — 人工闸门(“创作者会大声说出这句话吗?”)。
  • references/layout-library.md — 动态混合片段语法 + 竖屏安全区域。
  • references/v2-assets-layer.md — V2 增强种类(B-roll、标题卡片、纸效、3D 单词弹出)、学习到的编辑规则、动态图形强调方向(药丸/印章/结尾)以及 GSAP FX 词汇表。
  • references/zooq-video-runbook.md — 对于 ZOOQ 视频,从这里开始。 强化的端到端流程,每个决策都已锁定:脚手架(npx tsx scripts/new-zooq-job.ts <slug>)→ 脚本 + Gate 1 → 付费 Terry 渲染 → 使用品牌场景 B-roll 的 Remotion 基础(assets/zooq/manifest.json)→ HyperFrames 叠加 + GSAP FX → 审查 + 交付。
  • references/heygen-cli.md — 确切的 HeyGen 创建/轮询/下载 + 只读命令。
  • references/cost-gate.md — 硬性成本规则、估算公式、余额检查。

相关技能