抖音竖版口播短视频生成技能

概述

本技能将选题/笔记/文字内容转化为抖音风格的竖版口播短视频。整条流水线在本地完成，不依赖云端剪辑平台。

前置依赖

视频工程位于：projects/video-pipeline/

端到端流程

一共 6 步，按顺序执行。整个流程大约 3-8 分钟（取决于配图数量和渲染帧数）。

第 1 步：选题分析 & 口播文案

输入：用户提供的选题来源（Obsidian 笔记路径、文章 URL、直接文字）

操作：

1. 读取原始素材，提取核心观点和传播点
2. 撰写口播文案，写入 input/videos.json

口播文案写作要求（这些很重要，直接决定完播率）：

• 口语化：像朋友聊天一样说话，不要书面腔。"这玩意儿"比"这项技术"好。
• Hook 开头：3 秒内抛出最吸引人的点，制造好奇或冲突。不要"大家好今天我来聊聊"。
• 每段一个点：script 数组里每个元素对应一个分镜 + 一段话，一段只讲一个事。
• CTA 收尾：最后一句引导关注/评论/下一条预告。
• 总时长控制在 45-90 秒：6-8 段 script，每段 1-3 句。超过 90 秒完播率暴跌。

input/videos.json 结构：

{
  "defaults": {
    "voiceId": "Chinese (Mandarin)_Lyrical_Voice",
    "ttsModel": "speech-2.8-turbo",
    "speed": 1, "volume": 1, "pitch": 0, "emotion": "calm"
  },
  "videos": [{
    "id": "video-slug-YYYYMMDD",
    "title": "视频标题",
    "hook": "开头 hook 文案",
    "script": ["第 1 段正文", "第 2 段正文", "..."],
    "cta": "结尾 CTA 文案",
    "cover": "assets/images/<id>/cover.png",
    "theme": {
      "primary": "#FFDE59",
      "background": "#0F172A",
      "text": "#FFFFFF"
    }
  }]
}

第 2 步：准备 manifest

cd projects/video-pipeline
node scripts/prepare-input.mjs

这会读取 input/videos.json，为每条视频生成 build/manifests/.json。manifest 包含 scenes 数组（hook → body × N → cta）、narrationText 等。

第 3 步：生成配图（并行）

每个 scene 需要一张配图。封面 + 每段正文至少各一张，总共 4-8 张。

关键教训：串行生成容易超时/卡死，一定要并行生成。

# 并行启动多个生成任务
python3 skills/venus-gemini-image/scripts/generate_image.py \
  --model gemini-3.1-flash-image \
  --aspect-ratio 9:16 \
  --prompt "<场景描述 prompt>" \
  --output projects/video-pipeline/assets/images/<id>/<name>.png

配图 prompt 写法：

• 竖版 9:16，加 vertical 9:16
• 不要文字：加 no text, no watermark
• 场景化：描述具体视觉画面而非抽象概念
• 风格一致：同一视频的图用相似的色调/风格描述
• 中文内容场景偏好：cinematic tech, dark aesthetic, creator workspace 等

容错策略：

• 并行 4 张起步，不要一次串行 7 张
• 如果部分图生成失败或超时，用相邻成功的图临时替代
• 完美主义不如先出片：3 张独立图 + 复用 > 7 张全失败

生成完成后，更新 manifest 中每个 scene 的 image 字段：

# 用 python 脚本更新 manifest 的 scene.image
import json
from pathlib import Path
p = Path('build/manifests/<id>.json')
data = json.loads(p.read_text())
for i, scene in enumerate(data['scenes']):
    scene['image'] = f'assets/images/<id>/scene-{i}.png'
p.write_text(json.dumps(data, ensure_ascii=False, indent=2))

同时可以给 scene 加 kind（hook/core/statement/compare/data/cta）、accent、detail 字段来丰富视觉层次。参见 references/scene-kinds.md。

第 4 步：TTS 配音 + 字幕

cd projects/video-pipeline
node scripts/synthesize-tts.mjs <video-id>

这会：

1. 调用 macOS say -v Tingting 生成 .m4a 音频（fallback 模式）
2. 用 afinfo 获取真实时长
3. 按字符比例均匀分配每句字幕的 startMs/endMs
4. 生成 build/subtitles//subtitle.json
5. 更新 manifest 中的 narration、subtitle、subtitleItems、durationInFrames

TTS 注意事项：

• 音频格式必须是 .m4a（不能用 .aiff，Remotion 不认 AIFF-C 压缩格式）
• 如果需要更好音质，可接入 MiniMax API（需 MINIMAX_API_KEY）

第 5 步：渲染成片

cd projects/video-pipeline
node scripts/render-one.mjs <video-id>

渲染过程：

1. 将 manifest 中引用的资源（图片、音频）复制到 public/render-assets//
2. 生成 .tmp/.props.json
3. 调用 npx remotion render src/index.ts DouyinVideo
   --props
4. 成片输出到 renders/.mp4

渲染时间约 1-2 分钟（90 秒视频 ≈ 2700-2800 帧，6 并发）。

第 6 步：发送给用户

成片路径：projects/video-pipeline/renders/.mp4

用 message tool 发送：

message action=send media=<mp4_path> caption="<标题>" channel=telegram target=<chat_id>

Remotion 组件说明

详细的组件结构参见 references/remotion-components.md。简要说明：

Scene Kind 系统

通过 kind 字段控制 scene 的视觉呈现：

每个 scene 还可以带：

• accent：左上角标签文字
• detail：主文字下方的辅助说明

常见问题 & 踩坑

渲染失败：AIFF 音频格式不识别

Remotion 的 ffprobe 不认 macOS say 默认的 AIFF-C 压缩格式。解决：TTS 脚本已改为直接输出 .m4a。

图片生成串行超时

Venus API 通过代理调用 Gemini，单张图 30-120 秒不等。串行 7 张可能要 10+ 分钟且容易中途断。解决：并行 4 张起步。

字幕为空

如果 TTS provider 返回的字幕数据为空，fallback 逻辑会从 narrationText 按 \n 分句、按字符比例均匀分配时间。

node_modules 提交到 git

记得在 .gitignore 里加上 node_modules/。

快速参考命令

# 完整流程（在 projects/video-pipeline 目录下）
node scripts/prepare-input.mjs              # 1. 准备 manifest
node scripts/synthesize-tts.mjs <id>        # 2. TTS + 字幕
node scripts/render-one.mjs <id>            # 3. 渲染

# 图片生成（在 workspace 根目录）
python3 skills/venus-gemini-image/scripts/generate_image.py \
  --model gemini-3.1-flash-image \
  --aspect-ratio 9:16 \
  --prompt "..." \
  --output projects/video-pipeline/assets/images/<id>/<name>.png

# 查看可用 compositions
cd projects/video-pipeline && npx remotion compositions src/index.ts