koubo git:20261006.35f859bC

Immutable. This exact content never changes and is served at /api/v1/blob/4a2b26199384402e.

# 口播短视频制作（koubo）

把一条口播素材做成一条包装好的剪映草稿。五步按顺序做，每一步有产出、有检查，上一步没过不做下一步。

```
1 对齐声画 → 2 转写 → 3 写脚本 → 4 找证据和素材 → 5 包装出草稿 → 看预览自查
```

命令是 `koubo`（Windows 上是本文件夹里的 `koubo.cmd`）。所有文件放在视频旁边的 `<视频名>.koubo` 文件夹（下面叫「工作文件夹」）。
出的是剪映草稿，不是成片：人在剪映里看过、导出。不要说「成片已完成」。

长什么样由**风格文件**定（字体、配色、字号、什么角色用什么包装、音效、美颜）。你只负责判断内容：留哪些句子、每句是什么角色、哪里分章节、哪些词是重点。不要自己发明包装。

---

## 第 1 步　对齐声画

口播常常另外用领夹麦或录音笔录人声。有单独的人声文件就必须用它。

```
koubo align "<视频>" --audio "<人声文件>"
```

- 输出 `AUDIO_MATCH_SCORE`（对得上的把握）和 `AUDIO_OFFSET`（差几秒）。
- 报 `audio-does-not-match-video`：这条录音不是这条视频的。停下来问用户，不要换一条硬对。
- 文件夹里有几条视频、几条录音，按文件名和时长配对；配不上就问。
- 没有单独的人声文件：跳过这步。但如果转写后发现现场有两个人的声音混在一起（见第 2 步），回来问用户要录音。

**过关**：有人声文件时，对齐成功。

## 第 2 步　转写

```
koubo transcribe "<视频>" [--audio "<人声文件>"]
```
转写用这台机器上的识别模型，四分钟的口播大约一分钟，长素材按比例等，不要中途重跑。


工作文件夹里得到 `transcript.txt`（给你读）和 `transcript.json`（给工具用）。每行一句：

```
[12] 00:19.75–00:20.61 近 -11dB  衰老评估
[14] 00:22.07–00:23.57 远 -24dB  持续寻访监呃
```

- `[12]` 句子编号，后面都用它。
- `近` 是出镜的人自己说的；`远` 是镜头外的人说的（提词的人先念一句、出镜的人再复述一句，是最常见的录法；也可能是提问或现场其他人）。工具先用声纹把声音分开，再看哪个声音响起时画面里的人在动。输出里 `VOICES=` 一行是结果；出现「分不出哪个是出镜的人」的 WARN 时，先问用户再往下做。
- `⏸2.1s` 这句前面停了多久。

**过关**：完整读完 `transcript.txt`，知道这条素材讲了什么、哪些是提词、哪些是重说。

## 第 3 步　写脚本

脚本就是 `plan.json`：把留下的句子排成有结构的一条片子。在工作文件夹里写。

### 3.1 选句

1. 只留 `近`。`远` 的句子播出来时画面里的人是闭着嘴的，**留了会直接报错 `offscreen-voice-kept`**。提词式的素材里，同一句话会先有一遍 `远`（提词）再有一遍或几遍 `近`（复述）：要的是 `近` 里最后一遍说完整的那一句。
2. 同一句说了几遍，只留最后说顺的那一遍。同一个意思全片只出现一次。
3. 说顺的那遍里夹了「呃」或口吃多出来的字，用 `cut` 剪掉那几个字。说错、说半截的整句不要。
4. 「再来一遍」「继续」这类现场对话、开拍前的闲聊不要。
5. 不改写、不合并、不编造。只能从已有编号里选。
6. **默认出完整版**：把出镜的人讲的内容按原顺序完整留下，每句话只留说得最好的一遍，不压缩成短视频，也不为了凑时长删内容。用户明确要短版（比如「剪一条 60 秒的」）才精选。

### 3.2 排结构

把留下的句子分成几个章节（`sections`），每章 3–10 句。顺序就是成片顺序，可以和素材顺序不同。

- **第一章是钩子**，不写标题。第一句必须自己能听懂、能留住人：一个问题、一个反常识的结论、一个痛点。素材开头如果是接着上文说的，从后面挑一句挪上来。
- **中间每章讲一件事**，写 2–6 个字的 `title`。默认不显示在画面上（章节卡和角标都关着），只用来分段和拆分集，仍然要像栏目名：名词短语，不带标点，不要写成一句话。
- **最后一章是行动**：提问、引导评论，不写标题。
- 全片 3–5 章。把所有句子按顺序默读一遍，读不通就改。

### 3.3 标角色

给关键句标 `role`。版式是按角色自动出的，你不用管样式，但角色标得准不准直接决定片子好不好看。不标的句子是普通过渡。

| 角色 | 是什么 | 会变成什么 | 全片大约 |
|---|---|---|---|
| `钩子` | 开头第一句 | 人名条就落在它上面 | 1 句，必须有 |
| `观点` | 引出一个新话题或主张的短句 | 聚焦：周围柔和压暗，轻微推近 | 每 20 秒 1 句 |
| `列举` | 并列几项里的一项，一项一句，**连着标** | 默认当普通句子（分屏清单关着） | 有并列内容就用 |
| `金句` | 一句短的结论或反问，16 个字以内 | **引言版式**：整屏，像杂志上的引言，关键词变金色 | 每 30–40 秒 1 句 |
| `举例` `解释` | 例子、展开 | 主要用来决定哪里配空镜 | 按需 |
| `行动` | 让观众去做什么 | 普通画面（片尾卡关着） | 1 句 |

**分屏清单怎么才能出来**：至少连着两句都是 `列举`，每句是清单里的一项，每项不超过 10 个字（「衰老评估」「个性化干预」）。清单的小标题用这一章的 `title`。只有一项、或者某一项是一长句，就不会出清单。讲「三个原因」「四个环节」「几种方法」这类内容时，一定这样标。

**引言版式**：选全片最值得截图的那一句。超过 16 个字的会自动降级成聚焦。配一个 `big` 关键词（这句里的词），它会变成金色。

### 3.4 标重点词

这是包装里最要紧的一项，参考成片平均每 7 秒一个。

- `big`：**关键词**，`[{"id": 105, "text": "闭环"}]`。它会从字幕里拿出来，在说到的那一刻以强调色大字弹在字幕下方。
  - 每 6–8 秒一个，一条 1 分钟的片子 8–10 个。
  - 必须是这句话里**原样出现**的词，2–5 个字，最好是这句的**最后一个词**：结论、数字、名词（「不一样的」「6 项」「卵巢」「准确」「亲民」）。
  - 一句只能有一个。
- `highlight`：字幕里原地变色的词，不放大。术语和次一级的重点，全片 8–15 个。同一个词不要既在 `big` 又在 `highlight`。

### 3.5 计划文件

```json
{
  "name": "草稿名",
  "transcript": "transcript.json",
  "style": "默认",
  "title": {"name": "姓名", "lines": ["头衔一", "头衔二"]},
  "sections": [
    {"keep": [{"id": 107, "role": "钩子"}, {"id": 101, "role": "观点"}, 103, {"id": 105, "role": "金句"}]},
    {"title": "四大环节", "keep": [{"id": 9, "role": "观点"}, {"id": 12, "role": "列举"}, {"id": 13, "role": "列举"}, {"id": 25, "role": "解释"}]},
    {"title": "搜索思路", "keep": [{"id": 32, "role": "观点"}, {"id": 35, "cut": ["关"]}, {"id": 45, "role": "举例"}]},
    {"keep": [{"id": 110, "role": "行动"}, 111, 114]}
  ],
  "highlight": ["长寿管理", "闭环"],
  "big": [{"id": 105, "text": "闭环"}]
}
```

`keep` 里每一项是一个编号，或 `{"id": 编号, ...}`，可带：

| 字段 | 说明 |
|---|---|
| `role` | 角色，见上表 |
| `cut` | 从这句里剪掉的字：`["呃"]`、`["关"]`（把「关关键词」剪成「关键词」）。按第一次出现的位置剪 |
| `look` | 指定包装样式，盖过风格文件。一般不用写 |
| `zoom` | 指定画面放大倍数。一般不用写 |

`title`（人名条）只在用户给了姓名和头衔时写，不要编。

**转写里的错别字**（医学名词最常见）写在计划的 `fix` 里，工具会在字幕、关键词、清单、引言上显示改正后的字：

```
"fix": {"促卵细胞激素": "促卵泡激素", "花纯": "孕酮", "公能医学": "功能医学"}
```

左边照抄转写里的错字，右边是对的。**不要去改 `transcript.json` / `transcript.txt`，也不要写脚本改它们**：那里的字和时间是一一对应的，改了会让剪辑点错位。`big`、`highlight`、`cut` 里仍然照转写原样写（错字也照抄），显示时会自动换成对的。

**过关**：先不加素材跑一次 `koubo draft`（见第 5 步），`WARNINGS=0`。

## 第 4 步　找证据和素材

### 4.1 证据

口播里的事实说法要有出处，尤其是医疗、健康、数据、功效。逐句看留下的句子：

- 含数字、「研究表明」「临床」「最有效」这类断言的，用搜索工具查权威来源（指南、教科书、官方机构、论文）。
- 搜索工具有两档：普通查询走境内搜索引擎，一秒出结果，适合查常识和找网页；查询词以「深搜 」开头（如 `深搜 老年综合评估 中国专家共识 出处`）走 Grok 联网检索，要 40–70 秒，会读页面、给结论和来源。**查出处用深搜**，一条断言搜一次，不要一句话反复搜。

深搜要一两分钟，而一次搜索最多等 40 秒：没查完时会先给普通搜索的结果，并提示「深搜还在查」。这时**用一模一样的查询再搜一次**就能取到深搜的答案（最多再搜两次）；一次只问一个说法，查得更快。
- 在计划里加 `evidence`：

```json
"evidence": [
  {"id": 54, "claim": "老年综合评估是老年医学的标准评估方法", "source": "来源名称 + 网址", "note": "可选"}
]
```

- 查不到就写 `"source": "未查到"`，并在交付时告诉用户这句没有出处。不要编来源。
- 查到和口播说的**相反**或明显夸大：把这句从脚本里拿掉，或告诉用户由他决定。不要替说话人改口。
- 工具会生成 `证据清单.md`，并对没给出处的断言报 `WARN`。

### 4.2 空镜素材

空镜是盖在人物画面上的补充画面，让观众**看到正在说的那个东西**。参考成片每 15–20 秒一段，一条 1 分钟的片子 3–4 段。少而准，不凑数。

**放在哪**

- 只给**正在讲一个看得见的东西**的句子配：体检、抽血、化验、量血压、医生问诊、老人、吃饭、睡觉、走路。
- 空镜从这句话**开始时出现、说完时结束**，画面和话是一对。一句太短（不到 2 秒）就用 `"to"` 让它盖住连着的一组句子，这一组必须都在讲同一个东西。
- `钩子`、`金句`、`行动` 不配，工具会拦。讲道理、下结论、提问、让观众评论的句子不配。
- 两段空镜之间至少隔 5 秒；开头 5 秒不放。

**怎么找**，每一段都走完这四步：

```
koubo stock "elderly blood pressure"              ① 列候选
koubo stock "elderly blood pressure" --pick 49815  ③ 下载挑中的
```

1. **列候选。** 英文，2–4 个词，写画面里有什么：「给父母做慢性病风险评估」搜 `elderly doctor checkup`，不搜 `risk assessment`。只会列出竖屏或 4K 的（别的裁成竖屏会糊）。输出 `NO_USABLE_CANDIDATE` 就换词。
2. **看候选图。** 打开 `CANDIDATE_SHEET` 那张拼图，对照标签。排除：动画、图标、示意图；人物明显对不上的；血腥、手术、针头特写、患者痛苦；艺术片、抽象画面；食物或器官的大特写；带水印的。
3. **下载。** `--pick <编号>`。
4. **看预览图。** 下载后输出的 `PREVIEW` 是这条素材裁成竖屏之后的样子（三个时刻）。主体被裁掉、看不出是什么、画面脏乱的，**不用**，回到第 1 步换一条。

一句话最多试两个搜索词，都没有合适的，这句就不配。**对不上的空镜比没有空镜糟得多。**

在计划里加：

```json
"broll": [
  {"id": 45, "file": "<FETCHED 那一行里的路径>"},
  {"id": 82, "to": 86, "file": "…"}
]
```

`to` 是这段空镜盖到哪一句为止（含）。时长由句子决定，不用写秒数。
报 `STOCK_KEY_MISSING`：没设图库密钥，这次不配，交付时告诉用户。

**过关**：断言都有出处或标了未查到；空镜文件都真实存在。

## 第 5 步　包装出草稿

```
koubo draft "<plan.json>"
```

工具按风格文件自动做：

这套包装叫「墨金」：暖象牙白的字、哑金的点缀、墨绿黑的底板；宋体管观点（人名、章节、关键词、金句），黑体管信息（字幕、头衔）；用细线不用色块；出现是淡入并上移一点，消失是淡出。全部由工具渲染，剪映只负责摆放，所以画出来什么样成片就是什么样。

| 内容 | 规则 |
|---|---|
| 人名条 | 开头 5 秒：金色竖线、宋体名字、黑体头衔 |
| 章节 | 默认不出章节卡、不放角标（风格文件里可以开） |
| 进度线 | 顶部一条极细的金线随播放前进，每章一个刻度 |
| 关键词 | `big` 的词从字幕里拿出来，说到时以宋体大字出现在字幕下方，下面一道短金线 |
| 分屏清单 | 默认关 |
| 引言版式 | `金句`：画面虚化压暗，整屏引言 |
| 聚焦 | `观点`：周围柔和压暗，轻微推近 |
| 卡片 | 画面缩成圆角卡片，浮在虚化的同一画面上。和聚焦一起用于节奏：画面素超过 6 秒就给一个短句换一下 |
| 片尾 | 默认关：最后一句就是正常画面，所以最后一句必须是一句说完了的结论或号召 |
| 字幕 | 工具直接画成图片叠在画面上：得意黑（有棱角的斜体黑），象牙白字、细墨边、软阴影，按词断行，每行不超过 10 字，`highlight` 的词变浅金色。人名条始终排在字幕上方，不会压在一起 |
| 镜头稳定 | 每个片段剪进草稿前先去抖：对着背景把画面锁住，放大 5% 裁掉边。第一次生成每分钟成片要多等三四分钟，输出里 `STABILISED=` 是做成的片段数 |
| 镜头 | 素镜头极慢地往里推一点；全片四周有一层很淡的暗角增加层次 |
| 音效 | 关键词、章节卡、金句各一个，音量很低 |
| 配乐 | 风格文件里固定了就自动铺，音量压在人声下面，结尾淡出 |
| 美颜美型 | 按风格文件的滑杆数值，每个片段都开 |
| 空镜 | 静音、铺满画面，从句子开始到句子结束；整屏版式期间不放 |

### 出草稿后自己先看一遍

```
koubo preview "<plan.json>"
```

输出几张 `PREVIEW_SHEET` 拼图（每秒 4 帧，按剪映的图层规则合成）。**用看图工具把每一张都打开看**，逐项检查：

- 开头 5 秒人名条有没有、有没有挡住脸；
- 有没有哪一段画面里的人闭着嘴、却有字幕在走（说明留了镜头外的声音）；
- 最后一句是不是一句说完了的话；
- 引言版式那一句选得值不值、断行顺不顺；
- 关键词有没有压到别的字；空镜和画面里说的话对不对得上；
- 有没有连续十几秒都是同一个素画面。

有问题就改 `plan.json` 重跑 `draft` 再看。预览里剪映自己渲染的字（字幕）只是近似，位置和内容是准的。

同名草稿会被覆盖，改完计划重跑即可。

**输出里的 `WARN` 必须处理**：语气词、口吃、重复句、留了远处的声音、断言没出处、时长超出、第一句不是钩子。每条都给了改法。改到 `WARNINGS=0`。确实是误报的，交付时逐条说明。

### 配乐和音效从哪来

用的是剪映自己的音乐库和音效库。工具能读到剪映在本机留下的曲库目录（真实名称、作者、风格、是否可商用），并能用登录会员自己的下载链接把曲子和音效取到本机。

```
koubo music                 本机能直接用的配乐和音效
koubo music 钢琴            按名称、作者或风格搜（加 --all 连没下载的一起列）
koubo fetch                 把曲库目录里还没有的取到本机（默认最多 30 首可商用配乐、60 个音效）
koubo fetch 钢琴 --songs 10  只取名称、作者、风格里带「钢琴」的
```

每次做片子按这个顺序：

1. 先 `koubo music`。本机配乐不到 10 首或音效不到 10 个，就先跑一次 `koubo fetch` 补库，不用问用户。
2. 风格文件的「音乐」里固定了曲目：直接用，不用选。
3. 没固定：跑 `koubo music --suggest`。它按风格文件的偏好（每分钟 100–130 拍、鼓点明显、名称带动感／时尚／商务／律动这类）把本机配乐排好，抒情温柔的已经筛掉。从上往下挑第一首**名称调性合适**的：营销口播要自信、利落、有往前推的节奏；搞笑、紧张、悬疑、舞曲健身这类跳过。只用可商用的。在计划里写 `"music": {"file": "<名称>"}`。
4. 本机没有合适的：`koubo fetch <关键词>`（动感、节奏、商务、时尚、律动、励志……）再挑。这是营销口播，配乐要有明确的鼓点和往前走的劲，**不要抒情、温柔、治愈、钢琴独奏这一类**；选了这类，生成时会给 WARN。
5. 音效不用你挑，风格文件按名称指定了，工具用本机有的第一个。
6. `fetch` 输出 `CATALOGUE_STALE`：曲库目录旧了或是空的。这次用本机已有的；交付时请用户在剪映「音频」里把音乐库和音效库的分类各往下滑几屏，下次就能取到。
7. 交付时说明用了哪首配乐、为什么选它，请用户试听。你听不到声音，选得不合适很正常，用户说换就换。

---

## 交付时告诉用户

1. 草稿名。在剪映「草稿」里找，看不到就重启剪映。
2. 从多长剪到多长，分了哪几章，每章一句话说讲了什么。
3. 你拿不准的地方：哪句两遍都不顺、哪里顺序是你调的。
4. 证据：几条有出处，哪几条没查到。
5. 空镜配了几段，配乐用了没有。
6. 还要他在剪映里做的：看美颜美型和包装效果、核对字幕错字、试听配乐、导出。

## 风格文件

在本文件夹的 `style/` 里，一个风格一个 json。计划里用 `"style": "<名称>"` 选，不写就是 `默认`。
用户说「字幕大一点」「强调色换成红色」「金句不要圆形窗口」这类要求，改的是风格文件，不是某一条片子的计划。改之前告诉用户这会影响以后所有片子；只想改这一条，就另存一个风格文件。

| 项 | 管什么 |
|---|---|
| `配色` | 正文、强调、描边、人名、头衔的颜色 |
| `字体` | 大字、标题卡、人名用哪个剪映字体。空着用默认字体 |
| `字幕` | `字体`：得意黑 / 思源黑体 / 思源宋体；`像素`：字的大小；`位置`；`每行最多`。`方式` 写 `文字` 则改回剪映自己的文字轨（能在剪映里改字，但字体不保证） |
| `防抖` | `开`、`裁切`（放大多少来藏边）、`平滑秒`（镜头本来在移动时保留多慢的移动） |
| `字幕` `大字` `标题卡` `人名条` | 字号、位置、时长、动画 |
| `景别` | 剪辑点交替的放大倍数 |
| `角色包装` | 每种角色用哪种样式：`plain` 不加、`spot` 压暗四角、`frame` 缩框、`circle` 圆形窗口、`cutout` 抠像标题画面 |
| `节奏` | 画面最多素几秒、自动轮换哪些样式、多长的句子才算短句 |
| `章节转场` `章节角标`（默认关） `分屏清单` `进度线` `片尾` `氛围暗角` | 这几样的开关和强度 |
| `章节开头` `章节标题卡` | 有标题的章节第一句用哪种样式、出不出标题卡 |
| `上限` | 各样式最多出现几次或占多少 |
| `空镜` | 每段多长、最短间隔、开头几秒不放 |
| `音乐` | 固定曲目和音量 |
| `音效` | 关键词、标题画面、章节、金句各用哪个音效（按剪映音效库里的名称写，可以写几个备选，用本机有的第一个），和音量 |
| `美颜` | 各滑杆数值（0–100，同剪映面板）。美颜：磨皮、美白、匀肤、祛法令纹、祛黑眼圈、亮眼、白牙、丰盈。美型：瘦脸、小脸、V脸、短脸、颧骨、下颌骨、开眼角、大眼、瘦鼻。写 0 就是不开 |
| `时长` | 成片最短最长 |

## 做不了的

- 调色：在剪映里做。
- 没有单独人声文件，而现场有人提词并且和出镜的人声音重叠：转写会乱。问用户要录音。
- 剪映云端的音乐、音效、贴纸、花字：只能用本机已下载的。
- 听不到声音、看不到画面：配乐合不合适、空镜好不好看，由用户判断。

## 运行命令时

- `transcribe`、`draft`、`fetch`、`stock --pick` 可能要几分钟。运行命令的超时写 600000（毫秒），不要写 0，也不要省略成很短。
- `draft` 第一次要给每个片段去抖，最慢。如果超时了，**原样再跑一遍**：做好的片段都留着，不会重做，第二遍很快。
- 路径带中文或空格时整个用英文双引号括起来。
- 证据要用搜索工具查。搜索工具报错用不了时：不要凭记忆写出处。能确定的写「凭记忆，未联网核对」，不能确定的写「未查到」，并在交付时告诉用户搜索这次没通。

## 出错时

| 输出 | 意思 |
|---|---|
| `KOUBO_FAIL audio-does-not-match-video` | 人声文件和视频不是同一条 |
| `KOUBO_FAIL keep-id-unknown N` | 计划里的编号在转写里不存在 |
| `KOUBO_FAIL cut-word-not-in-sentence N 字` | 要剪的字不在这句里，照转写原文写 |
| `KOUBO_FAIL role-unknown` / `look-unknown` | 角色或样式写错了，看上面的表 |
| `KOUBO_FAIL style-missing` | 没有这个风格文件 |
| `KOUBO_FAIL draft-in-use` | 同名草稿正在剪映里开着，改不了。请用户退回剪映首页再重跑，或在计划里给草稿换个名字 |
| `KOUBO_FAIL draft-root-missing` | 没找到剪映草稿文件夹。在计划里加 `"draft_root": "<剪映设置里的草稿位置>"` |
| `koubo check` | 检查环境是否齐全 |