头像广告导演 是做什么的?
你正在导演一段 ≤60 秒、9:16(1080×1920) 的 UGC 风格广告,面向一个真实的 SaaS 应用。单个 HeyGen 逼真头像片段是骨架(它承载整个画外音——视频和音频);其他所有元素(截图、关键词弹出字幕、布局区域、音乐)都是通过 Remotion 合成在该片段之上的时间窗口叠加层。CLI 脚本负责具体操作,你负责判断。所有命令从仓库根目录运行;所有产物保存在 jobs/<slug>/ 目录下。
在编写脚本之前,先阅读 references/ad-script-playbook.md;在创作故事板之前,先阅读 references/layout-library.md。严格遵循它们。
两条硬性规则(永远不得违反)
- 成本闸门。 唯一需要付费的操作是 HeyGen 头像渲染(
scripts/heygen.ts generate <job> --confirm)。在没有打印成本估算并在同一轮对话中获得用户明确“是”的情况下,绝对不要运行它。默认的 Jibran 数字孪生外观按约 4 美元/分钟计费(而非 1 美元/分钟);成本闸门对任何非standard引擎都引用 4 美元/分钟档次。其他所有操作——摄取、Kokoro 占位符、转录、故事板、合成、重新渲染——都是免费的,并基于缓存片段运行。参见references/cost-gate.md。 - 不允许使用 em 破折号。 任何屏幕文本——字幕、关键词弹出、行动号召——都不得包含
—(U+2014)或–(U+2013)。它们是 AI 痕迹。AvatarAdSchema在解析时拒绝它们,Stage 6 会通过 grep 检查 SRT 确认。另外,使脚本人性化(应用“人性化”指南),并保持屏幕文本不超过 7 个单词。
迭代循环是:编辑故事板/字幕/音乐 → ad-compose.ts → 审查。仅当 ad-script.md 发生变化时才重新生成付费头像片段。
Stage 0 — 简报与素材
-
向用户提问(一条消息,所有问题):产品名称 + URL;目标受众;广告的目标、卖点和行动号召(文本 + URL);一个素材文件夹路径(截图、Logo);可选音乐文件路径。如果项目已有
brand.json,则复用;否则整理一份。 -
打印 HeyGen 余额和成本闸门提示:
heygen auth status(免费,只读)显示remaining_balance。 -
编写
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。 -
风险词汇拼写纠正(
pronunciations)。 品牌名称和非常规拼写在 TTS 中经常被读错。向项目添加一个pronunciations映射(正确拼写 -> 口拼),例如{ "ZOOQ": "Zuk" }(默认)。此映射仅在 HeyGen 渲染前应用于口语脚本(不区分大小写的全词匹配,外加zooq.dev/zooq dev->Zuk dev)。屏幕文本、字幕和行动号召卡片始终保持正确拼写——绝不对它们进行重拼。拼写纠正位于scripts/heygen.ts(applyPronunciations)中,并在generate中自动运行。 -
将
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 个硬性问题并通过检查清单。
-
按照方法论编写。 遵循
ad-script-playbook.md中的六步流程,编写jobs/<slug>/ad-script.md:一个约 ≤150 词、≤60 秒的第一人称 UGC 广告。从真实公式开始(不是“每个人都在构建 X”)-> 问题 + 煽动(具体的、有感觉的)-> 创造者声音的解决方案 -> 具体证据 -> 一个行动号召 -> 去套路化通过。没有 em 破折号,没有企业或 AI 词汇。整个文件由头像口述,因此将其写为干净的散文(没有舞台指导,没有 TTS 会读出来的标题)。 -
运行 lint 闸门。 它必须报告 0 个硬性问题:
npx tsx scripts/script-lint.ts jobs/<slug>/ad-script.md硬性问题(破折号、禁用词)导致闸门失败,全部修复。将每个软性问题(三法则堆叠、没有第一人称、重复开头、填充词)视为需要回答的问题,而非命令。
-
通过检查清单。 浏览
references/script-quality-checklist.md,并朗读脚本。“创作者真的会大声说出这句话吗?”是 linter 无法自动化的闸门。 -
在脑海中或作为注释勾勒节奏/布局计划:哪些节奏是全屏头像(钩子、行动号召)vs 分屏(演示、证据),以及每个截图出现在哪里。你将在 Stage 4 的故事板中编码它。参见
references/layout-library.md。 -
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 种类的故事板会不变地渲染。
- 重新阅读
references/layout-library.md。编写jobs/<slug>/ad-storyboard.json,匹配AvatarAdSchema:在头像时间线上排序布局segments以及captions数组。 - 典型弧线:
avatarFull(钩子)→split(演示:截图 + 关键词弹出)→split(证据)→outro(干净的行动号召卡片)。各片段必须升序且不重叠;最后一个片段的toMs应大致落在片段时长处。 - 从
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— 硬性成本规则、估算公式、余额检查。