Clawreel

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

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

流程总览

| Phase | 做什么 | CLI 命令 | 产出 | |-------|--------|----------|------| | 1 | 资源检查 + 背景音乐 | check / music | 资源清单 + bg_music_*.mp3 | | 2 | 生成口播 → 格式化 → 保存 | format | script_*.json | | 3 | 构建生图 Prompt | — | 含 image_prompts 的 script | | 4 | TTS 配音 + 时间戳对齐 | align | 音频 + segments_*.json | | 5 | 批量生成图片 + 可选片头视频 | assets / video | seg_*.jpg + 可选 video_head.mp4 | | 6 | FFmpeg 合成视频 | compose | composed.mp4 | | 7 | Whisper 字幕 + 标题 + 水印 | burn-subs / post | final_composed.mp4 | | 8 | 生成发布文案 + 多平台发布 | publish | 文案 + 抖音/小红书 |

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 用简短英文（如 claude-mem、parrot） | 默认根目录 assets/（中间）/ output/（最终）

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

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

严禁反模式

| 反模式 | 后果 | 正确做法 | |--------|------|----------| | sentences 含 # title | TTS 读出 "hashtag title" | title 单独存储 | | sentences[0:2] 与 hooks 重复 | TTS 读两遍 | format 自动分离 | | --text 含 hook 文本 | TTS 重复 | --text = body only | | 用 segments JSON 生成字幕 | 声音-字幕不同步 | Whisper burn-subs | | 图片 Prompt 含中文文字 | 生图乱码 | 英文 | | align 后不校验 segments | index 错乱 + prompt 丢失 | Phase 4 后必校验 | | 字幕默认底部位置 | 抖音 UI 遮挡 | --margin-v 550 |

已知限制

| 限制 | 规避 | |------|------| | MiniMax 无词级时间戳（字符加权估算） | Edge TTS 或接受估算 | | clawreel assets 无增量模式 | 缺图少时手动补或全量重跑 |

STOP GATES（成本防护）

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

| Gate | 时机 | 展示内容 | |------|------|---------| | G1 | Phase 2 后 | title + 全部 sentences（编号 + 文本） | | G2 | Phase 3 后 | 全局基调 + Prompt 概要（编号 + 画面描述） | | G3 | Phase 5 后 | 6-8 张关键帧图片 |

---

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

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

• --llm-suggest：LLM 复用建议（需 MINIMAXAPIKEY）
• 自定义风格：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/_/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字）：画质与构图

| 类型 | style_prompt | |------|-------------| | 宠物/动物 | Cinematic 4K wildlife photography, 9:16 vertical portrait, shallow depth of field with bokeh, warm golden side-lighting, high contrast, shot on 85mm lens. | | 科技/数码 | Cinematic 4K tech photography, 9:16 vertical portrait, shallow depth of field, cool blue-white studio lighting, clean modern aesthetic, high contrast. | | 生活/美食 | Cinematic 4K lifestyle photography, 9:16 vertical portrait, shallow depth of field, warm natural window light, cozy atmosphere, food magazine quality. |

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

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

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

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

Phase 4: TTS + 对齐

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

| voice_id | 风格 | 适用场景 | |----------|------|---------| | presenter_male | 男主持人 | 科技/知识科普 | | presenter_women | 女主持人 | 温和专业感 | | male-qn-qingse | 青涩男声 | 年轻化内容 | | male-qn-jingying | 精英男声 | 商务/专业 | | male-qn-badao | 霸道男声 | 强调型 | | male-qn-daxuesheng | 大学生男声 | 校园/轻松 | | female-shaonv | 少女音（默认） | 通用 |

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

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

PROJECT = "assets/_"
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/_
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/_
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/_
OUTDIR=output/_
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/_
OUTDIR=output/_

选项 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/_/final.mp4

Phase 8: 发布

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

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

| 字段 | 说明 | |------|------| | title | 视频标题（平台显示） | | description | 正文，含 hook + 核心卖点 + CTA | | tags | 话题标签，5-10 个 |

平台适配：

| 平台 | 标题 | 正文 | 标签 | |------|------|------|------| | 抖音 | 口语化、悬念感、emoji | 短平快、痛点 | 5-8 个，含热点 | | 小红书 | 笔记体、信息密度 | 分点罗列、干货 | 8-10 个，长尾词 | | B站 | 信息型、偏专业 | 稍长可接受 | 5-8 个，技术标签 |

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

Step 2: 发布

OUTDIR=output/_
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/_/，输出目录 O = output/_/。

| 类型 | 路径 | |------|------| | 脚本 | $P/script.json | | 片段 | $P/segments.json | | 图片 | $P/images/seg_*.jpg | | 背景音乐 | $P/bg_music.mp3 | | TTS 音频 | $P/tts.mp3 | | 合成视频 | $O/composed.mp4 | | 最终视频 | $O/final.mp4 |

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hrygo
• Source: hrygo/clawreel
• License: MIT

Install and usage instructions live in the source repository linked above.