zhengmike/ai-short-video-factory

AI 短视频工厂（ai-short-video-factory）

一句话：人只做三件事——定选题、改脚本、验收成片；其余全部由 Agent 完成。

这套流程是在 20+ 期真实视频号作品上迭代出来的。最大的教训只有一条： "静态罚站"是完播率杀手。早期模板视频 66–73% 的帧是静止的，最长定格 5.5 秒； 改成"每 1–1.4 秒一个微动作 + 全片 MP4 静止检测门禁"之后，静止帧降到 0–5%。

flowchart LR
  A[1 选题] --> B{{Gate 1 人工: 定选题+角度}}
  B --> C[2 口播脚本] --> D{{Gate 2 人工: 改脚本+分镜}}
  D --> E[3 TTS 配音 + timeline.json]
  E --> F[4 HyperFrames 动效编码]
  E --> G[5 音效+BGM 混音 -14 LUFS]
  F --> H[6 封面烧进首帧 + 渲染]
  G --> H
  H --> I[7 自动质检 x3]
  I -->|FAIL| F
  I --> J{{Gate 3 人工: 看成片验收}}
  J --> K[9 发布文案] --> L[10 发布到 Cloud Run 手机交付页]
  L --> M[数据复盘]

---

0. 一次性环境准备

依赖	用途	安装 / 检查
gcloud + ADC	调 Vertex AI（TTS / Lyria / 质检模型）	gcloud auth application-default login
GCP 项目	需开通 Vertex AI，能访问 gemini-3.8-flash-tts、lyria-3-pro-preview	export GCP_PROJECT=<你的项目ID>
Node ≥ 20	HyperFrames 渲染	node -v；npx hyperframes --help
ffmpeg / ffprobe	剪辑、混音、编码	ffmpeg -version
Python 3 + numpy + scipy	音效合成、质检	pip install numpy scipy
Cloud Run（第 10 步）	手机交付页	项目开通 Cloud Run + Cloud Build API；你需要 Owner 或 Cloud Run Admin
中文字体	画面字体	Noto Sans SC Bold（正文）、ZCOOL KuaiLe / LXGW WenKai（手写感）
HyperFrames skill（推荐）	让编码 Agent 掌握 HTML→MP4 写法	git clone https://github.com/heygen-com/hyperframes，把其中 skills 复制到你的 skills 目录
impeccable（可选）	反 AI 味设计检测	git clone https://github.com/pbakaus/impeccable，CLI 放进 PATH 命名为 impeccable

[!IMPORTANT] 所有脚本都通过环境变量取项目 ID，不要把任何人的项目 ID / 个人素材硬编码进 skill。

工作目录约定（每期一个文件夹）：

episodes/<slug>/
  script.json          # 口播脚本（Gate 2 确认后的版本）
  shared/              # TTS 分句 wav、voice.wav、timeline.json、bgm.mp3
  p9x16/index.html     # HyperFrames 合成页（由 work/*.py 生成）
  p9x16/assets/        # 字体、图片、audio/mix.wav
  work/                # 模块化生成器 base.py / s1_6.py / s7_12.py / tail.py
  out/cover_9x16.png   # 封面
  out/<slug>_9x16.mp4  # 成片
  publish.json         # 标题 + 视频号描述 + 朋友圈文案（第 10 步发布用）

---

1. 选题（Agent 调研 → Gate 1 人工拍板）

• 每天扫 10 个候选（海外 5 + 国内 5）：HackerNews、GitHub Trending、YouTube、X、行业媒体、公司官方博客。
• 每个候选给出：事件事实（附原始链接）+ 反常识点 + 3 个切入角度 A/B/C + ≤15 字钩子。
• 选题打分优先级：可转发性（能被转进工作群的"一图结论"）> 反常识 > 时效。
• 🛑 Gate 1：把候选发给用户，等用户选定"选题 + 角度 + 视觉风格"后才写脚本。

[!CAUTION] 事实准确性是红线：每个数字、公司、产品能力都必须能追溯到一手来源；绝不把 A 厂商的能力安到 B 厂商身上。 搬运/改编外部视频时，在后台剥掉原作者广告，脚本 100% 用第一人称原创视角写，绝不出现"原视频""翻译自"等字样。

2. 口播脚本（→ Gate 2 人工确认）

详见 references/script_formula.md。硬指标：

• 12–14 句，每句 18–26 个汉字、念出来 ≤ 3–4.2 秒，全片 45–65 秒。
• 结构：钩子(L1-L2) → 证据/数字(L3-L5) → 拆解底层逻辑(L6-L9) → 3 条可截图的结论(L10-L12) → 个人 IP 收尾(最后一句)。
• 第 1 秒必须有冲突或数字，零铺垫；结尾放"一图总结表"驱动截图和转发。
• 每句标 2–4 个 keywords（用于画面强调和音效卡点）。
• 输出 script.json（格式见 templates/script.example.json），同时给 2 个备选钩子。
• 🛑 Gate 2：脚本 + 分镜表一起给用户逐句确认。用户明确说"开始制作"之前，绝不生成 TTS、绝不渲染视频。

3. 分镜（与脚本一起过 Gate 2）

详见 references/storyboard_motion.md。核心规则：

1. 一屏一焦点：任意时刻屏幕上 ≤ 12–15 个汉字，留白 ≥ 60%。
2. 零静态罚站：每句拆 3 个微节拍（句首 / +36% / +68%），每 1.0–1.4 秒必须有一个可见变化（逐个弹入、荧光笔划过、红线划掉、数字滚动、印章砸下、镜头推拉）。
3. 安全区：1080×1920 画布，关键内容只放在 y = 290–1640px（避开灵动岛、平台顶栏和底部文案区）。
4. 浅色背景（米白 / 纸张 / 浅蓝），不要深色仪表盘；按选题换风格模板，别期期一个样。
5. 不加底部滚动字幕；关键词以大字形式出现在画面中央。

4. 配音：Gemini TTS + timeline.json

export GCP_PROJECT=<你的项目ID>
python3 scripts/synth_voice.py episodes/<slug>/script.json episodes/<slug>/shared
#   可选环境变量: TTS_VOICE=Orus  ATEMPO=1.26  GAP=0.14

• 逐句合成 → 用 gemini-2.5-flash 听写校验（漏字/读错自动重试 3 次）→ 去首尾静音 → atempo 提速 → 拼接。
• 产出 voice.wav + timeline.json（每句 start_s/end_s 和关键词估算时刻）+ Lyria 3 Pro 定制 BGM（bgm.mp3）。
• 语速建议：男声 Orus ATEMPO=1.26（稳）；追求快节奏可以到 1.40–1.48。句间停顿 0.12–0.14s，段落停顿 0.20–0.28s。
• timeline.json 是后续所有动效和音效的唯一时间轴，脚本改了必须重新跑。

5. 动效编码：HyperFrames（交给最强的编码模型）

• 引擎选型：在盲测里 HyperFrames（HTML + GSAP → PNG 序列）比 Remotion 更受欢迎，作为默认引擎。
• 把编码交给专门的 worker Agent（用你所用 Agent 的 subagent / 多 Agent 功能起一个强编码模型 worker，例如 Claude Code subagent），brief 模板见 references/worker_brief.md。brief 里必须包含：完整分镜表、timeline.json、安全区、风格色板、质检门禁阈值。
• 生成器必须模块化：base.py（CSS/SVG 工具函数）+ s1_6.py + s7_12.py + tail.py（拼装 + GSAP 时间轴），每个文件 < 300 行。
  • 原因：一次让模型写 1000+ 行文件会触发流式超时；一次设计 3 个场景会把输出 token 耗在思考里。一次 write 只写 1 个场景。
• 所有动画挂在同一个 GSAP tl 上，时间点从 timeline.json 读取，每个微节拍都对齐到一个口播关键词。

6. 音效 + BGM 混音

python3 scripts/sfx_mix.py --timeline episodes/<slug>/shared/timeline.json \
  --bgm episodes/<slug>/shared/bgm.mp3 --out episodes/<slug>/p9x16/assets/audio/mix.wav

• numpy 程序化合成 whoosh / pop / 手写沙沙声 / 落锤 / chime / click，按"每句 3 个微节拍 + 每个关键词一个 click"自动排布。
• BGM 挖掉 400–2600Hz 人声频段 + 侧链压缩（人说话时自动压低 9.5dB）。
• 三轨必须齐全：人声 + 音效 + BGM，最终响度 -14 LUFS / ≤ -1.5 dBTP（各平台通用标准）。

7. 封面 + 渲染

封面规则见 references/cover_rules.md：浅色背景、人物表情夸张、≤10 个巨字、主体放在视频号 6:7 裁切安全区内（1080×1920 的 y=330–1590）。 封面直接烧进成片第 1 帧，不用单独上传。

bash scripts/build.sh episodes/<slug>   # 渲染 PNG 序列 → 替换首帧为封面 → 混入 mix.wav → x264 编码 → motion_qa

编码参数：-crf 23 -maxrate 2200k -bufsize 4400k -pix_fmt yuv420p -movflags +faststart，60 秒视频约 15–19 MB，适合手机传输和网页托管（很多 Serverless 平台单响应上限 32 MiB）。

8. 三道自动质检门禁（全部 PASS 才能给用户看）

门禁	命令 / 方式	通过标准
① 全片静止检测	python3 scripts/motion_qa.py out.mp4	静止帧 ≤ 40%，最长定格 ≤ 1.5s（实际做到 0–5%）
② 反 AI 味设计检测	python3 scripts/impeccable_qa.py p9x16/index.html	0 个主要反模式（彩条左边框、发光阴影、卡片套卡片、低对比灰字、渐变文字、回弹动画…）
③ 独立审片 Agent	另起一个只能看 MP4 的 reviewer Agent，按 references/qa_checklist.md 逐秒审	0 blocker

[!WARNING] 抽几张关键帧截图看"挺好看"不算质检——那正是早期视频藏住 5 秒定格的原因。 必须跑全片 motion_qa，并由一个没看过代码、只看成片的 Agent 从头看到尾。 审片 Agent 曾抓到 motion_qa 看不出的问题：第 0 帧没有标题、1.35 秒的空场、近乎全空的画面、结尾标题被 CTA 盖住。

🛑 Gate 3：质检全过后把成片给用户；用户验收通过才进入发布。

9. 发布文案 + 数据复盘

• 视频号描述：1–2 句 + 4–5 个 #标签，简短有力；朋友圈文案 ≤ 12 字，像跟朋友说话。
• YouTube：不放内部链接，不搞"评论关键词领资料"；置顶评论写成同行之间的技术讨论。
• 复盘（T+24h / T+72h / T+7d）：北极星 = 转发率 × 完播率；同时看 3 秒留存、平均观看占比、点赞、收藏、涨粉。爆款判定 = 播放 ≥ 近 10 条中位数 × 5 且转发率 ≥ 3%。 实测经验：3 秒留存靠第 0 帧强钩子（无淡入）；转发率靠结尾"一图选型表"；60 秒视频平均只看 23 秒 → 45 秒左右最好。
• 写好后存成 episodes/<slug>/publish.json：{"title": "...", "description": "...", "moments": "..."}，第 10 步直接读它。

10. 一键发布到 Cloud Run 手机交付页（默认交付方式）

成片不要只留在 Agent 所在机器上——发布成一个手机能直接打开的页面，用户在手机上点开链接就能看、存相册、复制文案。

export GCP_PROJECT=<你的项目ID>        # 必填
export ACCESS_KEY=<随便一串口令>        # 推荐：页面需要 ?k=口令 才能打开（首次后记住 90 天）
bash scripts/publish.sh episodes/<slug>
# → ✅ 手机打开: https://short-video-hub-xxxx.a.run.app/<slug>/?k=口令

页面内容（scripts/deliver/，Flask + gunicorn，约 100 行）：

• 视频播放器（支持 Range 请求，iPhone Safari 可拖动进度）
• 📲 存入手机相册：页面打开即后台预载 MP4，点按钮调起系统分享菜单 → 选「存储视频」直接进相册（不是进"文件"App）
• ⬇️ 直接下载 MP4（电脑用）
• 📋 一键复制描述 / 📋 一键复制朋友圈
• 首页 / 列出所有已发布的期数（SITE_DIR 本地目录保留历史期，每次发布追加一期再整体部署）

可选环境变量：REGION（默认 asia-east1）、SERVICE（默认 short-video-hub）、SITE_DIR（默认 ./video-hub-site）、SITE_TITLE、PUBLIC_MODE=iam。

发布后 Agent 必须自己验收再把链接给用户：脚本会自动检查页面返回 200、视频 Range 请求返回 206；有浏览器工具时再真实点一遍播放、拖进度、点每个按钮。

[!WARNING]

• 32 MiB 上限：Cloud Run 单个非流式响应不能超过 32 MiB，超了点播放/存相册会 500。publish.sh 会拦截 > 30 MiB 的文件；按第 7 步参数编码，60 秒视频约 15–19 MB。
• 公开访问权限：脚本默认用 --no-invoker-iam-check（不需要给 allUsers 授权，很多公司组织策略禁止 allUsers），但它要求你对项目有 run.services.setIamPolicy 权限（项目 Owner / Cloud Run Admin 都有）。 报错 require run.services.setIamPolicy 时：找项目管理员授权，或把这条 gcloud run services update <SERVICE> --no-invoker-iam-check 放进 Cloud Build 里由 Cloud Build 服务账号执行。 组织策略禁止 ingress=all 时（smoke check 返回 403/404），换一个个人项目部署。
• 链接拿到就能看，不要放机密内容；设置 ACCESS_KEY 可以挡住随手转发的陌生人。

---

已踩过的坑（Gotchas）

• 后台 shell 里跑 ffmpeg 一定加 -nostdin（或 stdin=DEVNULL），否则会永远卡住。
• HyperFrames 直接出 MP4 在部分 ffmpeg 版本下右侧 8px 发黑、AAC 被压到 -24 LUFS → 用 --format png-sequence 自己混流。
• 不要在网络文件系统（FUSE）上直接 -movflags +faststart 输出，先写本地盘再拷贝。
• 编码 Agent 打开任一边 > 2000px 的图片可能导致对话 400 报错永久损坏 → 预览图一律 ≤ 2000px。
• 派活给后台 worker 时，同时起一个 5–6 分钟的定时器巡检 worker 状态，worker 因配额崩溃时自动替换。
• 手写字体（ZCOOL KuaiLe）缺部分字形（如数字 0），数字用粗黑体单独渲染。
• npx skills add ... --yes 无 TTY 会卡在交互提示，直接 git clone 再复制。

个性化（分享给别人时必须改的地方）

在 script.json 的 brand 字段里配置你自己的：账号名、一句话定位、结尾口播语、头像/卡通形象路径。 最后一句口播 + 画面上的个人 IP 收尾卡必须同时出现，不要只有静音的结尾卡。