Clawreel

ClawReel - AI 短视频语义对齐流水线

声音、字幕、画面三同步。图片切换时机由 TTS 逐词时间戳精确驱动，每张图内容由对应语句语义生成。

流程总览

Phase 2  format            →  script.json（title, sentences, hooks, cta）
Phase 3  Agent 编辑         →  script.json（+ image_prompts, style_prompt）
Phase 4  align              →  tts_output.mp3 + segments.json
Phase 5  assets             →  seg_*.jpg
Phase 6  compose            →  composed.mp4
Phase 7  burn-subs + post   →  final_composed.mp4
Phase 8  Agent 文案 + publish → 平台发布

核心规则

分工：Agent 做创意决策和内容生成，CLI 做格式化/合成/发布，生图模型无记忆需每帧独立完整 Prompt。

约定：CLI 路径用绝对路径 | 每个项目独立目录 assets/<topic>_<YYYYMMDD>/ | topic 用简短英文（如 claude-mem、parrot） | 默认根目录 assets/（中间）/ output/（最终）

断点续传：用户中断时保留当前阶段产物，下次从断点 Phase 继续。检查 assets/<topic>_<date>/ 判断进度：

• 有 script.json → 从 Phase 3 继续
• 有 segments.json → 从 Phase 5 继续
• 有 images/seg_*.jpg → 从 Phase 6 继续
• 有 output/<topic>_<date>/composed.mp4 → 从 Phase 7 继续

严禁反模式

已知限制

STOP GATES（成本防护）

每个 Gate 展示关键信息表格，等用户确认后才继续。

Phase 1: 资源检查 + 背景音乐

clawreel check --topic "主题" [--llm-suggest]
clawreel music --topic "主题" --duration 60

• --llm-suggest：LLM 复用建议（需 MINIMAX_API_KEY）
• 自定义风格：clawreel music --prompt "风格描述" --duration 90 --output /abs/path/$PROJECT/bg_music.mp3
• 风格推荐：宠物→轻快活泼、科技→电子感、美食→温馨治愈、知识科普→清新自然

Phase 2: 脚本生成 + 格式化

Step 1: 生成口播内容

格式：# 标题 + 用 | 分隔句子。开头钩子 → 分段展开 → 总结 → CTA（5-40 句），每句一个核心信息点。# 标题 format 自动剥离，不会被 TTS 读出。

Step 2: 格式化 + 保存

clawreel format --content "# 标题\n句1 | 句2 | ..." --title "标题"

CLI 输出 JSON 到 stdout，用 Write 工具保存为 assets/<topic>_<YYYYMMDD>/script.json。

⛔ GATE 1 — 展示 title + sentences 表格，确认后继续。

涉及具体数字（星数、百分比等）时，优先从 GitHub API / 官方来源获取实时数据。

Phase 3: 构建生图 Prompt

决定视频质量的关键步骤。 必须在 Phase 4 之前完成（align 从 script JSON 读取 image_prompts）。

Prompt 公式（每帧独立完整）：[style_prompt], [global_visual_context], [本帧画面描述]

Step 1: 全局视觉基调

在 script JSON 根级添加：

• global_visual_context（80-120字）：场景、光源、氛围
• style_prompt（40-60字）：画质与构图

Step 2: 逐帧 Prompt（英文，50-80字/帧）

实体一致性：品牌/角色在所有帧保持相同视觉符号（如 OpenClaw → "red lobster icon"）。首帧定义，后续帧复用。

关键：image_prompts 数组长度 必须等于 sentences 数组长度。

⛔ GATE 2 — 展示全局基调 + Prompt 概要表格，确认后继续。

Phase 4: TTS + 对齐

PROJECT=assets/<topic>_<YYYYMMDD>  # 例: assets/claude-mem_20260412
clawreel align \
  --text "正文（空格分隔，保留标点，不含 hooks/标题）" \
  --script /abs/path/$PROJECT/script.json \
  --provider minimax \
  [--voice <音色ID>] \
  --output /abs/path/$PROJECT/segments.json

• --text：保留标点符号（逗号、句号、感叹号），TTS 依赖标点控制语调和停顿
• --provider：minimax（自然）/ edge（免费但机械）
• --split-long：拆分 >5s 段落（会重置 index，慎用）

hooks 拼接陷阱：--text 不含 hooks 时，CLI 会插入 hooks 到 sentences 前面但 image_prompts 不同步偏移。最佳实践：--text 包含 hooks 文本，让 CLI 跳过拼接逻辑。

MiniMax 音色

试听：clawreel tts --text "测试文本" --provider minimax --voice presenter_male

数据完整性校验（Phase 4 后必做）

PROJECT = "assets/<topic>_<YYYYMMDD>"
python3 -c "
import json
segs = json.load(open('${PROJECT}/segments.json'))
script = json.load(open('${PROJECT}/script.json'))
errors = []
for i, seg in enumerate(segs['segments']):
    if seg['index'] != i:
        errors.append(f'seg[{i}] index={seg[\"index\"]} ≠ {i}')
    if seg['image_prompt'].startswith('Professional Short Video Scene:'):
        errors.append(f'seg[{i}] prompt 是 CLI 默认模板')
if len(segs['segments']) != len(script.get('sentences', [])):
    print(f'⚠️ 段数不等，TTS 合并短句，正常')
if errors:
    print('❌ 问题：')
    for e in errors: print(f'  - {e}')
else:
    print('✅ 校验通过')
"

修复：index 不连续 → 遍历重写 seg['index'] = i；prompt 被覆盖 → 从 script JSON 回填。

Phase 5: 素材生成

PROJECT=assets/<topic>_<YYYYMMDD>
clawreel assets --segments /abs/path/$PROJECT/segments.json [--video]

图片保存到 $PROJECT/images/seg_*.jpg。--video 同时生成 6 秒片头视频。

⛔ GATE 3 — 展示 6-8 张关键帧图片，确认后继续。

缺图检查：遍历 segments 中每个 index，检查 seg_{index:03d}_0.jpg 是否存在。缺图少时手动补或全量重跑。

Phase 6: 视频合成

PROJECT=assets/<topic>_<YYYYMMDD>
clawreel compose \
  --tts /abs/path/$PROJECT/tts.mp3 \
  --segments /abs/path/$PROJECT/segments.json \
  --music /abs/path/$PROJECT/bg_music.mp3 \
  --transition fade \
  [--hook-video /abs/path/$PROJECT/video_head.mp4]

转场：fade（默认）/ slide_left / slide_right / zoom / none

OOM 降级（30+ 帧时 exit 254，body_xfade.mp4 已生成）：

PROJECT=assets/<topic>_<YYYYMMDD>
OUTDIR=output/<topic>_<YYYYMMDD>
ffmpeg -y \
  -i /abs/path/assets/body_xfade.mp4 \
  -i /abs/path/$PROJECT/tts.mp3 \
  -i /abs/path/$PROJECT/bg_music.mp3 \
  -filter_complex "[2:a]volume=0.15[bg];[1:a][bg]amix=inputs=2:duration=first:dropout_transition=2,aresample=44100" \
  -c:v libx264 -preset fast -crf 23 -pix_fmt yuv420p -b:v 6M \
  -c:a aac -b:a 128000 -ar 44100 \
  -t <时长> /abs/path/$OUTDIR/composed.mp4

Phase 7: 后期处理

PROJECT=assets/<topic>_<YYYYMMDD>
OUTDIR=output/<topic>_<YYYYMMDD>

选项 A：不加字幕

clawreel post --video /abs/path/$OUTDIR/composed.mp4 --title "标题" --no-subtitles

选项 B：加字幕

# Step 1: Whisper 烧录
clawreel burn-subs --video /abs/path/$OUTDIR/composed.mp4 --model medium --language zh --margin-v 550

# Step 2: 标题 + 水印
clawreel post --video /abs/path/$OUTDIR/composed.subtitled.mp4 --title "标题" --no-subtitles

--margin-v 参考（9:16 竖屏）：0 底部 | 550 抖音推荐 | 700 中央偏下

产出：output/<topic>_<YYYYMMDD>/final.mp4

Phase 8: 发布

Step 1: 生成发布文案（Agent 生成）

为每个平台生成适配的发布文案。

平台适配：

展示文案表格，确认后发布。

Step 2: 发布

OUTDIR=output/<topic>_<YYYYMMDD>
clawreel publish --video /abs/path/$OUTDIR/final.mp4 --title "标题" --platforms douyin xiaohongshu

支持：douyin、xiaohongshu、bilibili

辅助命令

# 音色试听
clawreel tts --text "测试" --provider minimax --voice presenter_male

# 批量试听（保存到 /tmp 对比）
for v in presenter_male male-qn-jingying male-qn-badao; do
  clawreel tts --text "${v}测试" --provider minimax --voice "$v" 2>/dev/null \
    && cp assets/tts_output.mp3 "/tmp/voice_${v}.mp3"
done
open /tmp/voice_*.mp3

文件约定

项目目录 P = assets/<topic>_<YYYYMMDD>/，输出目录 O = output/<topic>_<YYYYMMDD>/。

兜底背景音乐：assets/bg_music_default.mp3（首次运行时生成）