Crypto Kol Video

---
name: crypto-kol-video
description: 为 Twitter/X 上的 crypto 和 AI 博主制作 9:16 竖屏中文科普短视频（抖音、视频号、X），全片带博主自己的头像 IP 和 @账号（封面第一帧、开头、角标、结尾关注卡）。画面为仿交易界面风格的代码动画（Remotion），配 MiniMax 配音、逐句高亮字幕、代码合成 BGM 和音效。适用于：「帮我做一个讲 XX 的币圈视频」「做个合约/现货/资金费率/交易所产品科普短视频」「把这个脚本做成视频」「给我的抖音/推特做个 crypto 教学视频」。第一次使用会先问博主的 Twitter 账号，抓取头像后再开始。
---

# Crypto KOL 竖屏科普视频

把一个选题做成 60–130 秒的竖屏讲解视频，分镜按口播逐句卡点，品牌元素用博主自己的头像和 @账号。
代码出片：`template/` 是 Remotion 工程，`scripts/kol.py` 负责字幕对齐、混音等流水线，`scripts/render.sh` 出成片。

先读这一页；做到对应步骤时再读：`references/scene-recipes.md`（分镜动画套路）、`references/design-system.md`（版式坐标和配色）、`references/fact-check.md`（核实和合规）、`references/tts.md`（配音）。

## 0. 第一次使用：确认博主品牌（必做）

1. **问用户的 Twitter/X 账号**（例如 `@james_x`）。不要猜，也不要沿用示例里的账号。同时问一句结尾关注卡上的 slogan（默认「币圈 · AI 交易干货」）。
2. 保存品牌并抓取头像：
   ```bash
   python3 scripts/kol.py brand @handle --tagline "币圈 · AI 交易干货"
   ```
   脚本会依次尝试 `api.fxtwitter.com` 和 `unavatar.io` 抓取公开头像，裁成 400×400 方图，存进 `~/.config/kol-video/brand/`。
3. **把抓到的头像给用户看，确认是本人。** 抓取失败（网络被拦、账号私密）或用户想换图时，请用户上传头像，然后执行：
   `python3 scripts/kol.py brand @handle --avatar /path/to/avatar.png`
4. 之后用 `kol.py new` 新建的每个项目都会自动套用这个品牌。用户换账号时重新跑一次 `brand`。

头像和账号会出现在 4 个地方（`template/src/brand.tsx` 已实现，不需要再写）：
- **封面 = 视频第一帧**（停留 0.45 秒，抖音直接选第一帧做封面），封面底部是头像 + @账号
- **开头**：钩子开始时，大头像 + 名牌在画面中央弹出，约 1.1 秒后飞进右上角
- **角标**：全片右上角显示小圆头像 + @账号
- **结尾**：关注卡，包括大头像、@账号、slogan，以及「+ 关注」被点成「已关注 ✓」

## 1. 环境准备（每台机器一次）

```bash
bash scripts/setup.sh            # Python 依赖 + 离线 ASR 模型（SenseVoice，用于字幕对齐）
```
还需要 Node 18+ 和 ffmpeg。Remotion 第一次渲染会自动下载 headless Chrome；已有 Chrome 时可以设 `BROWSER=/path/to/chrome-headless-shell`。

## 2. 工作流

### ① 澄清（一次问完，最多 3 个问题）
选题和角度、时长（60–90 秒 / 约 2 分钟）、画面风格（默认仿交易界面）、配音方式、是否系列化。用户已经给了脚本时，直接进入核实。

### ② 调研和核实：先查，再写
- 费率、规则、上线时间、杠杆上限这类事实，**以交易所官方帮助中心或公告为准**，记下页面的更新日期。第三方文章只用来找线索。
- 用户给的脚本也要核对。发现官方没有依据的说法，就改成能算出来或能查到的说法，并在交付时说明改了哪里、为什么改。
- 估算值（比如维持保证金率按 0.4% 估算）要在画面脚注里写「估算 / 以官方为准」。
- 不编造统计数字（如「90% 的人不知道」）、不编造引言；没核实到的数字口播不报（例如只说「可以开杠杆」，不说「最高 10 倍」）。
- 详细清单见 `references/fact-check.md`。

### ③ 写口播稿 → `video.json`
用 `python3 scripts/kol.py new <proj>` 新建项目（`video.json` 预填了示例，照着改）。结构：
- 钩子（约 10 秒，同样条件下的结果反差、一个反常识数字）→ 3–5 个知识段 → 「怎么选 / 怎么做」→ 结尾（一句话总结，加风险提示）。
- 每个场景有两部分：`tts` 是整段口播，带标点；`chunks` 是字幕分句，每句 ≤ 16 字，拼起来要和 tts 去掉标点后完全一致。
- **口播里的数字写成中文读法**（「百分之二十七」「一千U」），由 `replace` 把字幕换成阿拉伯数字（「27%」「1000U」），`highlight` 指定要标黄的关键词。替换顺序要先长后短，例如「两三倍」要排在「三倍」前面。
- 容易读错的字放进 `pronunciations`，比如 `强平/(qiang2)(ping2)`、`逐仓/(zhu2)(cang1)`、`做空/(zuo4)(kong1)`。
- `chip`、`title`、`titleParts` 是每个场景顶部的章节标签和大标题；`cover` 配置封面；`sfx` 是 `[分句序号, 音效类型, 帧偏移]`，音效类型有 pop / thud / ding / coin。
- 系列化（可选，用户要的话）：开头说「上期讲了 X，这期讲 Y」，结尾预告下期。
- 写完跑 `python3 scripts/kol.py check <proj>`，修到显示 OK；它还会估算时长。
- **把口播稿发给用户确认**，再进入配音。

### ④ 配音
默认 MiniMax speech-2.8-hd，`male-qn-jingying`，1.15 倍速，通过用户本机的 `mmx` CLI 生成，需要用户自己的 API Key：
```bash
python3 scripts/kol.py voicekit <proj> <用户电脑上的目录>
```
生成每段的文本、`gen_fill.sh` 和 macOS 上可以双击运行的 `双击生成配音.command`，请用户运行。脚本只补缺失的段落，失败自动重试。
要重配某一段：把那段的 wav 挪走（不要删除），改文本，再运行一次。
没有 MiniMax 的用户，可以用任何 TTS 或真人录音，只要每段一个音频文件、按场景 id 命名。见 `references/tts.md`。

### ⑤ 分镜动画（这一步决定成片质量）
改 `<proj>/video/src/scenes.tsx`：每个场景 id 一个组件，最后注册到 `SCENES`。用 `useBeat(k)` 拿到第 k 句的起音帧，让画面元素在说到它的那一刻出现。
- 画面不要只是字幕的复述，要把机制画出来：对比卡、温度计、阶梯柱状图、时间线、表格逐行点亮、盖章。套路见 `references/scene-recipes.md`。
- 画面区域固定在 960×700（位于 y=548），顶部是进度条、章节标签和大标题，y≈1290 是字幕，y>1450 留给平台文案区。见 `references/design-system.md`。
- 没拿到配音前，先跑 `kol.py timeline <proj>`（不带音频目录，按字数估算时间轴），再用 `bash scripts/stills.sh <proj>` 出静帧排版。
- 第三方品牌 Logo **只用用户提供的官方原图**：放进 `video/public/`，登记在 `src/logos.json`；没有原图时显示虚线占位框。**不要自己画仿制 Logo。**

### ⑥ 对齐、混音、渲染
```bash
python3 scripts/kol.py timeline <proj> <配音目录>   # ASR 逐句对齐 → timeline.json + build/voice.wav
python3 scripts/kol.py mix <proj>                  # BGM + 音效 + 侧链压低 → −14 LUFS
bash scripts/stills.sh <proj>                      # 每个场景出一张静帧拼成总览，先检查排版
bash scripts/render.sh <proj> <输出名>             # 成片 out/<输出名>.mp4 + 封面 PNG
```
小改动只重渲染一段时，用 `render.sh <proj> <名> 0-338` 出局部预览。整片约 3000 帧，2 核机器大约 10 分钟。

### ⑦ 质检
- 打开 `stills/sheet.png` 逐张看：有没有文字溢出、遮挡、盖章挡住关键数字、卡片越界。
- `timeline` 会打印每段的 ASR 转写和匹配率。匹配率 < 0.85 说明音频和稿子对不上。转写里的错字要区分两种情况：同音字（爆 / 报）没关系；声调或读音错了（如「深夜 → 商业」「拿得久 → 拿到酒」）要提醒用户试听，必要时加 `pronunciations` 重配。
- 抽几帧检查：第一帧是封面、2 秒左右头像正在飞向角标、最后 2 秒是关注卡。

### ⑧ 交付
- 成片和封面放到用户的文件夹，用一句话说明内容，并列出：改了哪些事实、哪些数字是估算、哪几处需要试听。
- 需要的话，再给一版发推或抖音的文案：简体中文，按 X 计重规则（中文算 2）控制在 280 以内，抓眼球但不编数据。
- 如果是商业合作内容，提醒用户发布时按平台规则标注广告或合作。

## 3. 硬规则
- 署名只用用户自己的 @账号和头像；示例里的 `@your_handle` 和测试头像不能出现在成片里。
- 结尾或画面脚注必须带风险提示：「不构成投资建议」，以及「以官方为准」的估算说明。
- 不仿冒交易所官方：画面风格可以「仿交易界面」，但不放对方 Logo，除非用户提供了官方原图并明确要求。
- 推广类视频（例如替交易所宣传）可以突出产品亮点，但每个亮点都要有公开出处，风险点保留在脚注里。

## 4. 踩过的坑
- 后台渲染判断是否完成时，用 `grep "Stitched N/N"` 看日志。不要用 `pgrep -f "remotion render"`，它会匹配到自己所在的 shell，导致等待循环卡死。
- 币安的 `fapi` 接口在部分地区返回 451。查不到实时数据时，退回官方帮助中心的说明，并告诉用户。
- 标题超过 9 个字会自动缩小字号。中英混排的标题（如「股票 · bStocks · 合约」）用 `titleParts`，每段可以单独设颜色和字号。
- 字幕分句太短会切错，太长会换行；10–14 字最稳。