# explainer-video — full documentation bundle

> Generated by tools/build-llms-full.sh. Source: https://github.com/bobobo2026/explainer-video
> Canonical HTML: https://bobobo2026.github.io/explainer-video/

Contents:
- README.md
- README.zh-CN.md
- SKILL.md
- core/creative-method.md
- core/quality-rubric.md
- core/platform-copy.md
- styles/realistic/GUIDE.md
- styles/handdrawn/GUIDE.md
- examples/rea/README.md
- examples/rea/platform-copy.md



---

# >>> FILE: README.md

# explainer-video

**An Agent Skill that turns a topic, an open-source project, or an idea into a finished Chinese explainer short video** — narration, word-level captions, music, sound effects, a mixed master, a quality rubric, and per-platform copy included.

[English](README.md) · [简体中文](README.zh-CN.md) · [Docs site](https://bobobo2026.github.io/explainer-video/) · [llms.txt](https://bobobo2026.github.io/explainer-video/llms.txt)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-orange.svg)](SKILL.md)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-green.svg)](https://bobobo2026.github.io/explainer-video/)
![Version](https://img.shields.io/badge/version-v3-lightgrey.svg)

---

## What is explainer-video?

`explainer-video` is a reusable **Agent Skill**: a folder containing a `SKILL.md` entry point, a shared production pipeline, runnable Python/Shell scripts, and two complete art-style engines. Drop the folder into your agent's skills directory, and the agent can produce a publish-ready Chinese explainer video end to end — from topic research to the final mixed MP4 and the Douyin / Xiaohongshu / Bilibili / WeChat Channels / X captions.

It is **not** a text-to-video model. The visuals are real code (React/Remotion compositions and Canvas/whiteboard scenes) driven by a word-level narration timeline, so every frame is deterministic, editable, and re-renderable — swap the voice track and the animation, sound effects, and captions re-align automatically.

- **Two art styles, one pipeline:** hand-drawn whiteboard (16:9) and photoreal talking-head vertical (1080×1920).
- **Word-level timing is the spine:** a single `timeline.json` (`{scene, say, start, end, words[], mouth}`) drives captions, animation cues, SFX and mouth shapes.
- **Agent-native:** designed to be copied whole into a skills directory — no service, no API keys required (unless you want premium TTS).

## Two art styles

| | Hand-drawn whiteboard `styles/handdrawn/` | Photoreal talking-head `styles/realistic/` |
|---|---|---|
| Look | Paper, pen lines, marker fills; drawn while the narrator speaks | On-camera presenter (lip-synced) + real screenshots + hand-drawn callouts + handheld drift + film grain |
| Best for | Abstract concepts, methodology, "what is X" | Trending projects, product/tool intros, data-driven news |
| Aspect | 1920×1080 (vertical patch included) | **1080×1920 native vertical** |
| Engine | [dashi-animationstyle](https://github.com/chuspeeism/dashi-animationstyle) (Canvas) | [Remotion](https://github.com/remotion-dev/remotion) (React) — template renders as-is |

| Photoreal vertical · reference contact sheet (REA episode) |
|---|
| ![Photoreal vertical reference frames](styles/realistic/reference/00_联系表.jpg) |

| Hand-drawn whiteboard · reference contact sheet |
|---|
| ![Hand-drawn whiteboard reference frames](styles/handdrawn/assets/reference/00_整片联系表.jpg) |

## Key facts

| | |
|---|---|
| Skill version | v3 (single skill, two styles) |
| Reusable scenes in the vertical template | 13 (`hook` → `cta`) |
| Reference frames shipped | 16 photoreal + 19 hand-drawn |
| Target episode length | 60–120 s |
| Real-voice word alignment accuracy | ≈95% of characters matched, median error ≈0.04 s (faster-whisper, word-level) |
| Master loudness | −14 LUFS integrated, −1.5 dBTP, music ducked under voice |
| Music beds | `pluck96` (modern plucked) and `lofi84` (gentle lofi) |
| Render cost | ≈3.7 s wall-clock per 1 s of video (Remotion, concurrency 2) |
| Quality gate | 9-item rubric; any dimension below 2/5 does not ship |
| License | MIT |

## How it works

1. **Pick a style** — the agent asks, or recommends from your goal.
2. **Research and fact-check** — numbers, quotes and screenshots are collected with sources and dates before any writing.
3. **Write the script** — `script.json`, spoken-colloquial sentences (≤20 characters each), hook in the first 3 seconds.
4. **Narration → word-level timeline** — your own recording (`voice_to_timeline.py`), premium TTS, or `edge-tts` as a free fallback; output is `voice.wav` + `timeline.json`.
5. **Visuals** — one idea per shot, visuals cued to the exact word (`wf(sentence, 'word')` in Remotion, `M('word')` in whiteboard).
6. **Quality check** — stills from every scene are tiled into a contact sheet and really looked at; scored against `core/quality-rubric.md`.
7. **Music, SFX and mix** — SFX are anchored to "word *k* of sentence *i*" in `cues.json`, so replacing the narration never breaks the timing; `mix.sh` ducks music under voice and normalizes to −14 LUFS.
8. **Delivery** — final MP4 plus 抖音 / 小红书 / B站 (with chapter timestamps) / 视频号 / X copy.

## Install

Copy the **whole folder** (copying only `SKILL.md` will not work — the scripts and templates live in the sibling directories):

```bash
# Claude Code / Codex
cp -r explainer-video ~/.claude/skills/     # or ~/.codex/skills/

# DeepSeek Harness
cp -r explainer-video ~/.dsh/skills/
```

Then run the environment check — you must see ✓:

```bash
bash core/scripts/check_env.sh realistic   # or: handdrawn
```

One-time environment setup (re-run after a cloud sandbox reset):

```bash
pip3 install numpy edge-tts faster-whisper     # faster-whisper is optional: word-level alignment for real recordings
mkdir -p ~/.fonts && curl -L -o ~/.fonts/LXGWWenKai-Medium.ttf \
  https://github.com/lxgw/LxgwWenKai/releases/latest/download/LXGWWenKai-Medium.ttf && fc-cache -f
# also required: ffmpeg, node 18+, Noto Sans SC, Noto Color Emoji
```

Photoreal style: install the render dependencies (already declared in `styles/realistic/template/package.json`):

```bash
cd styles/realistic/template && npm install
```

## Usage

Once the folder sits in your skills directory, just tell the agent:

> Use explainer-video to make a vertical video about *<topic / repo>*.

The agent then follows the seven steps in `SKILL.md`. To swap the presenter, replace the SVG parts in the `Host` component (or supply a photo/AI avatar as one neutral mouth base plus three mouth-openness sprites and one blink sprite) — lip sync keeps working because it is driven by `timeline.mouth`.

## Repository layout

```
SKILL.md              entry point: style → research → script → voice+timeline → visuals → QA → mix → delivery
core/                 shared across both styles
  creative-method.md    structure, metaphor library, colloquial-writing rules
  quality-rubric.md     9-dimension scoring sheet
  platform-copy.md      per-platform caption templates
  scripts/              check_env.sh · tts_timeline.py · voice_to_timeline.py · audio_bed.py · mix.sh · contact_sheet.sh
styles/realistic/     GUIDE.md · template/ (complete Remotion project, 13 scenes) · reference/ (16 frames)
styles/handdrawn/     GUIDE.md · assets/ (widget library + reference frames) · examples/ · references/ · scripts/
examples/rea/         the reference photoreal episode: script.json + platform copy
tools/                repo tooling: docs generator helpers (not needed to make videos)
docs/                 GitHub Pages site
```

## FAQ

**What exactly is explainer-video?**
It is an Agent Skill — a folder with a `SKILL.md` plus scripts, templates and reference frames — that an AI coding agent loads to produce Chinese explainer short videos end to end.

**Which agents can run it?**
Any agent that supports skill folders, including Claude Code, Codex, and DeepSeek Harness (DSH). The reference episodes were produced with DeepSeek v4.1-flash running on DeepSeek Harness.

**Do I need a paid TTS service?**
No. `edge-tts` is the free fallback and ships word-level timestamps; premium TTS (MiniMax, Doubao/Volcano, ElevenLabs) or your own recording simply produces better "human feel".

**Can I use my own recorded narration?**
Yes, and it is the recommended option. `core/scripts/voice_to_timeline.py` aligns a phone recording to the word level. Measured on the reference episode: ≈95% of characters matched, median error ≈0.04 s. If `faster-whisper` is absent it falls back to silence-based sentence splitting with in-sentence distribution by character count.

**Does swapping the narration break the animation or the sound effects?**
No. Animation cues are anchored to *words* (`wf(sentence,'word')`) and SFX are anchored to *word k of sentence i* in `cues.json`, so a new take re-aligns automatically — no code edits.

**Is the video generated by a text-to-video model?**
No. Frames are rendered from real code: Remotion (React) compositions for the photoreal style, Canvas scenes for the whiteboard style. That makes output deterministic, reviewable and re-renderable, and it lets real screenshots and product UI appear pixel-accurate.

**What are the hard dependencies?**
`ffmpeg`, Node 18+, Python 3 with `numpy`, the Noto Sans SC and Noto Color Emoji fonts, and LXGW WenKai for handwriting annotations. The photoreal template additionally needs Remotion packages; the whiteboard style needs a clone of dashi-animationstyle. `core/scripts/check_env.sh` reports exactly what is missing.

**How long does rendering take?**
About 3.7 seconds of wall-clock per second of video with concurrency 2 — roughly 6 minutes for a 97-second episode. The first render downloads the Chrome Headless Shell (~114 MB).

**Which platforms is the output made for?**
Douyin, Xiaohongshu, Bilibili, WeChat Channels and X. The vertical template keeps content inside platform safe areas (right-side button column, bottom caption zone) and ships caption templates per platform.

**Is it free to use?**
Yes, MIT licensed. Note that Remotion has its own license terms for commercial use, and the fonts and dashi-animationstyle keep their original licenses.

**How is this different from a generic AI video generator?**
Generic generators synthesize pixels from a prompt. `explainer-video` writes and renders a real composition with a fact-checked script and exact word-level sync, so you can fix a single wrong frame, reuse the 13 scene components, and re-render after changing the narration.

## Limitations

- Narration: real recordings first, premium TTS second, `edge-tts` only as a fallback — it is free and word-timed but sounds synthetic, and the skill is instructed to say so at delivery.
- The first render downloads a Chrome Headless Shell (~114 MB) and needs network access.
- Cloud browser IPs are usually overseas, so logging in to Chinese platforms from a sandbox shows "IP location: overseas" and may trip risk control — publish from your own machine.
- For reverse-engineering, scraping or security topics, the script must include a compliance reminder and only analyze software you are allowed to analyze.

## Citation

If you use this work in writing, cite it via [`CITATION.cff`](CITATION.cff):

```bibtex
@software{explainer_video_2026,
  author  = {bobobo2026},
  title   = {explainer-video: an Agent Skill for Chinese explainer short videos},
  year    = {2026},
  version = {3.0.0},
  license = {MIT},
  url     = {https://github.com/bobobo2026/explainer-video}
}
```

## Credits and license

Released under the [MIT License](LICENSE).

- Whiteboard style depends on [chuspeeism/dashi-animationstyle](https://github.com/chuspeeism/dashi-animationstyle) (MIT). Its source is not bundled here — clone it as described in `styles/handdrawn/GUIDE.md`.
- Photoreal style is built on [Remotion](https://github.com/remotion-dev/remotion) (Remotion License — see its terms for commercial use).
- Fonts: LXGW WenKai, Noto Sans SC, Noto Color Emoji, each under its own license.

Summarized by Notion AI while producing two reference episodes: *《AI的三种形态》* (whiteboard) and *《REA 逆向一切》* (photoreal vertical).

If this skill saves you time, a ⭐ helps other creators find it.


---

# >>> FILE: README.zh-CN.md

# explainer-video

**一个把「话题 / 开源项目 / 知识点」做成中文科普短视频的 Agent Skill** —— 口播、逐字字幕、配乐、音效、混音母版、质检评分表、各平台文案，一次交付。

[English](README.md) · [简体中文](README.zh-CN.md) · [文档站](https://bobobo2026.github.io/explainer-video/zh.html) · [llms.txt](https://bobobo2026.github.io/explainer-video/llms.txt)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-orange.svg)](SKILL.md)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-green.svg)](https://bobobo2026.github.io/explainer-video/zh.html)
![Version](https://img.shields.io/badge/version-v3-lightgrey.svg)

---

## explainer-video 是什么？

`explainer-video` 是一个可复用的 **Agent Skill**：一个文件夹，里面是 `SKILL.md` 入口 + 一套共用制作流程 + 可直接运行的 Python/Shell 脚本 + 两种画风的完整渲染引擎。把整个文件夹复制进 Agent 的 skills 目录，它就能从选题研究一路做到成片 MP4 和各平台文案（抖音 / 小红书 / B站 / 视频号 / X）。

它**不是**文生视频模型。画面是真实代码（React/Remotion 合成、Canvas 白板场景），由逐字时间轴驱动，所以每一帧都是确定、可改、可重渲的 —— 换一版配音，动画、音效、字幕会自动重新对齐。

- **两种画风，一套流程**：手绘白板（16:9）与拟真出镜竖屏（1080×1920）。
- **逐字时间轴是骨架**：一份 `timeline.json`（`{scene, say, start, end, words[], mouth}`）同时驱动字幕、动画卡点、音效和口型。
- **为 Agent 设计**：整体拷进 skills 目录即可用；不需要服务、不需要 API key（除非你要用付费 TTS）。

## 两种画风

| | 手绘笔记 `styles/handdrawn/` | 拟真出镜 `styles/realistic/` |
|---|---|---|
| 样子 | 白纸、钢笔线、马克笔，边说边画 | 出镜主播（口型同步）+ 真实截图 + 手绘圈注 + 手持微晃 + 胶片颗粒 |
| 适合 | 抽象概念、方法论、「X 是什么」 | 热点项目、产品/工具介绍、带数据的新闻 |
| 画幅 | 1920×1080（含竖屏补丁） | **1080×1920 原生竖屏** |
| 引擎 | [dashi-animationstyle](https://github.com/chuspeeism/dashi-animationstyle)（Canvas） | [Remotion](https://github.com/remotion-dev/remotion)（React），模板可直接渲染 |

| 拟真竖屏 · 参考成片联系表（REA 那期） |
|---|
| ![拟真竖屏参考帧](styles/realistic/reference/00_联系表.jpg) |

| 手绘白板 · 参考成片联系表 |
|---|
| ![手绘白板参考帧](styles/handdrawn/assets/reference/00_整片联系表.jpg) |

## 关键事实

| | |
|---|---|
| Skill 版本 | v3（合并为一个 skill，两种画风） |
| 竖屏模板可复用场景 | 13 个（`hook` → `cta`） |
| 附带参考帧 | 拟真 16 张 + 手绘 19 张 |
| 目标片长 | 60–120 秒 |
| 真人录音字级对齐 | 匹配率约 95%，中位误差约 0.04 秒（faster-whisper 词级） |
| 母版响度 | 集成 −14 LUFS，真峰 −1.5 dBTP，音乐给人声让路 |
| 配乐 | `pluck96`（现代拨弦）/ `lofi84`（温柔 lofi）两种 |
| 渲染耗时 | 约 3.7 秒墙钟 / 1 秒视频（Remotion，并发 2） |
| 交付门禁 | 9 项质检评分表，任一项低于 2/5 不交付 |
| 许可 | MIT |

## 流程（七步）

1. **选画风** —— Agent 会问，或按目标推荐。
2. **研究 + 事实核查** —— 数字、原话、截图先带出处和日期收集，再动笔。
3. **写稿** —— `script.json`，口语短句（每句 ≤20 字），3 秒内给钩子。
4. **配音 → 逐字时间轴** —— 真人录音（`voice_to_timeline.py`）、高质量 TTS，或 `edge-tts` 兜底；产出 `voice.wav` + `timeline.json`。
5. **画面** —— 每个镜头只讲一个意思，元素出现的时刻对齐到关键词（拟真用 `wf(句号,'词')`，手绘用 `M('词')`）。
6. **质检** —— 每个场景抽一帧拼成联系表，真的看一遍，按 `core/quality-rubric.md` 打分。
7. **配乐音效 + 混音** —— 音效锚在「第 i 句的某个词」（`cues.json`），换配音不用重新卡点；`mix.sh` 自动闪避并归一化到 −14 LUFS。
8. **交付** —— 成片 + 抖音 / 小红书 / B站（带章节时间戳）/ 视频号 / X 文案。

## 安装

复制**整个文件夹**（只拷 `SKILL.md` 不行，脚本和模板都在别的目录里）：

```bash
# Claude Code / Codex
cp -r explainer-video ~/.claude/skills/     # 或 ~/.codex/skills/

# DeepSeek Harness
cp -r explainer-video ~/.dsh/skills/
```

然后跑一次环境检查，必须看到 ✓：

```bash
bash core/scripts/check_env.sh realistic   # 或 handdrawn
```

一次性环境准备（云端沙盒重置后要重跑）：

```bash
pip3 install numpy edge-tts faster-whisper     # faster-whisper 可选：真人录音字级对齐
mkdir -p ~/.fonts && curl -L -o ~/.fonts/LXGWWenKai-Medium.ttf \
  https://github.com/lxgw/LxgwWenKai/releases/latest/download/LXGWWenKai-Medium.ttf && fc-cache -f
# 还需要：ffmpeg、node 18+、Noto Sans SC、Noto Color Emoji
```

拟真风格装渲染依赖（已写在 `styles/realistic/template/package.json`）：

```bash
cd styles/realistic/template && npm install
```

## 用法

文件夹放进 skills 目录后，直接对 Agent 说：

> 用 explainer-video 做一条讲 <话题 / 项目> 的竖屏视频。

Agent 会按 `SKILL.md` 的七步走完。想换主播形象：改 `Host` 组件里的 SVG 部件，或者把形象切成「闭嘴底图 + 3 张张嘴程度 + 1 张闭眼」贴图 —— 口型同步照旧，因为它由 `timeline.mouth` 驱动。

## 目录结构

```
SKILL.md              入口：选画风 → 研究 → 写稿 → 配音时间轴 → 画面 → 质检 → 混音 → 交付
core/                 两种风格通用
  creative-method.md    结构与比喻库、口语化写法
  quality-rubric.md     9 项评分表
  platform-copy.md      各平台文案模板
  scripts/              check_env.sh · tts_timeline.py · voice_to_timeline.py · audio_bed.py · mix.sh · contact_sheet.sh
styles/realistic/     GUIDE.md · template/（完整 Remotion 工程，13 个场景）· reference/（16 张参考帧）
styles/handdrawn/     GUIDE.md · assets/（部件库 + 参考帧）· examples/ · references/ · scripts/
examples/rea/         拟真风格完整案例：script.json + 平台文案
tools/                仓库维护脚本（做视频用不到）
docs/                 GitHub Pages 文档站
```

## 常见问题

**explainer-video 到底是什么？**
是一个 Agent Skill：一个含 `SKILL.md`、脚本、模板和参考帧的文件夹，AI 编码 Agent 加载它之后就能端到端产出中文科普短视频。

**支持哪些 Agent？**
任何支持 skill 文件夹的 Agent：Claude Code、Codex、DeepSeek Harness（DSH）等。参考成片是用 DeepSeek v4.1-flash 在 DeepSeek Harness 上跑出来的。

**必须买 TTS 服务吗？**
不必。`edge-tts` 免费且自带字级时间戳；付费 TTS（MiniMax、豆包/火山、ElevenLabs）或自己录，真人感更好。

**可以用我自己录的口播吗？**
可以，而且这是首选。`core/scripts/voice_to_timeline.py` 把手机录音对齐到字级。本仓库实例实测：匹配率约 95%，中位误差约 0.04 秒。没装 `faster-whisper` 时会退化成静音切句 + 句内按字数均分。

**换配音会不会把动画和音效打乱？**
不会。动画卡的是「词」（`wf(句号,'词')`），音效锚在「第 i 句的第 k 个词」（`cues.json`），重新配音会自动对齐，不用改代码。

**画面是 AI 生成的吗？**
不是。画面由真实代码渲染：拟真是 Remotion（React）合成，手绘是 Canvas 场景。所以输出确定、可审、可重渲，真实截图和产品界面能像素级还原。

**硬性依赖有哪些？**
`ffmpeg`、Node 18+、Python 3 的 `numpy`、Noto Sans SC 与 Noto Color Emoji 字体，手写批注还需要霞鹜文楷。拟真模板额外需要 Remotion 依赖；手绘风格需要 clone dashi-animationstyle。缺什么，`core/scripts/check_env.sh` 会逐条报出来。

**渲染要多久？**
并发 2 时约 3.7 秒墙钟 / 1 秒视频，97 秒的片子大约 6 分钟。首次渲染会下载 Chrome Headless Shell（约 114MB）。

**适配哪些平台？**
抖音、小红书、B站、视频号、X。竖屏模板已经把内容避开平台安全区（右侧按钮列、底部文案区），并附各平台文案模板。

**免费吗？**
MIT 许可，免费。但 Remotion 商用需遵守它自己的条款，字体和 dashi-animationstyle 也各自遵循原许可。

**和常见的 AI 视频生成器有什么不同？**
生成器是从提示词合成像素；`explainer-video` 是先写事实核查过的稿子，再渲染一份真实合成，逐字对齐、可以只改错的那一帧、可以复用 13 个场景部件，换配音能直接重渲。

## 已知边界

- 配音优先级：真人录音 > 高质量 TTS > `edge-tts` 兜底；`edge-tts` 免费且有字级时间，但听感「太 AI」，交付时必须主动说明。
- 首次渲染要联网下载 Chrome Headless Shell（约 114MB）。
- 云端浏览器 IP 通常在海外，从沙盒登录国内平台会显示「IP属地：海外」还可能触发风控，建议在本机发布。
- 涉及逆向、爬虫、安全的选题，稿子里必须加合规提醒，只分析用户有权分析的对象。

## 引用

用于写作时请引用 [`CITATION.cff`](CITATION.cff)：

```bibtex
@software{explainer_video_2026,
  author  = {bobobo2026},
  title   = {explainer-video: an Agent Skill for Chinese explainer short videos},
  year    = {2026},
  version = {3.0.0},
  license = {MIT},
  url     = {https://github.com/bobobo2026/explainer-video}
}
```

## 致谢与许可

以 [MIT](LICENSE) 许可发布。

- 手绘风格依赖 [chuspeeism/dashi-animationstyle](https://github.com/chuspeeism/dashi-animationstyle)（MIT），本仓库不包含其源码，按其 `GUIDE.md` 自行 clone。
- 拟真风格基于 [Remotion](https://github.com/remotion-dev/remotion)（Remotion License，商用需遵守其条款）。
- 字体：霞鹜文楷 / Noto Sans SC / Noto Color Emoji，各自遵循原始许可。

> 由 Notion AI 在制作《AI的三种形态》（手绘）和《REA 逆向一切》（拟真竖屏）时总结而成。

如果这个 skill 帮你省了时间，点个 ⭐ 能让更多创作者看到它。


---

# >>> FILE: SKILL.md

---
name: explainer-video
description: 把一个话题/开源项目/知识点做成中文科普短视频，带口播、逐字字幕、配乐音效，可以直接发抖音/小红书/B站/视频号/X。两种画风：①「手绘笔记」白板动画（横屏 16:9 为主，适合概念讲解）；②「拟真出镜」竖屏 9:16（带口型同步的出镜主播 + 真实截图 + 手绘标注 + 手持镜头/颗粒，适合热点、产品、开源项目介绍）。包含：选题研究与事实核查、口语化写稿、配音→逐字时间轴（TTS 或真人录音自动对齐）、画面卡点、自动配乐音效与混音、静帧质检评分、各平台文案。
---

# 中文科普短视频（v3：一套流程，两种画风）

> **⚠️ 先读这四条**
> 1. **这是一个文件夹。** 安装时复制整个 `explainer-video/`。开工第一步：`bash core/scripts/check_env.sh realistic`（或 `handdrawn`）。缺东西就停下找用户要完整包。
> 2. **不要从零重写渲染器。** 拟真风格从 `styles/realistic/template/` 复制改；手绘风格用 dashi-animationstyle 管线 + `styles/handdrawn/`。画面品质大多来自这些已经调好的部件，重写一遍全会丢。
> 3. **先看参考帧**：`styles/*/reference/00_*联系表.jpg` 就是及格线。交付前按 `core/quality-rubric.md` 打分，任何一项低于 2 分都不交付。
> 4. **事实必须有出处**（README、官方文档、API 数据）。数字要注明截至哪天，不确定的内容不要写进稿子。

## 环境准备（一次性；云端沙盒重置后要重跑）
```bash
pip3 install numpy edge-tts faster-whisper          # faster-whisper 可选：真人录音字级对齐（首次运行会下载约 460MB 的 small 模型）
mkdir -p ~/.fonts && curl -L -o ~/.fonts/LXGWWenKai-Medium.ttf https://github.com/lxgw/LxgwWenKai/releases/latest/download/LXGWWenKai-Medium.ttf && fc-cache -f
# 还需要：ffmpeg、node 18+、Noto Sans SC、Noto Color Emoji
# 拟真风格：在工程目录 npm i remotion @remotion/bundler @remotion/renderer react react-dom
# 手绘风格：git clone --depth 1 https://github.com/chuspeeism/dashi-animationstyle /data/refs/dashi-animationstyle
bash core/scripts/check_env.sh realistic            # 必须看到 ✓
```

## 0. 先选画风（问用户，或者按下表推荐）

| | 手绘笔记 `styles/handdrawn/` | 拟真出镜 `styles/realistic/` |
|---|---|---|
| 样子 | 白纸、钢笔线、马克笔，边说边画 | 出镜主播（口型同步）+ 真实截图/界面 + 手绘圈注 + 镜头微晃 + 胶片颗粒 |
| 适合 | 抽象概念、方法论、「X 是什么」 | 热点项目、产品/工具介绍、带数据的新闻 |
| 画幅 | 1920×1080（有竖屏补丁） | **1080×1920 原生竖屏** |
| 引擎 | dashi-animationstyle（Canvas） | Remotion（React），模板在 `template/` |
| 指南 | `styles/handdrawn/GUIDE.md` | `styles/realistic/GUIDE.md` |

用户说「要像真人」「要拟真」「要竖屏/手机看」「抖音」→ 拟真；说「手绘」「白板」「B站横屏」→ 手绘。拿不准就各出一帧静帧给用户选。

## 1. 研究 + 事实核查
- 开源项目：用 GitHub API 取 stars/forks/创建时间/license/主页，读 README（中文 README 优先）。截图：GitHub 手机版页面、官方配图、产品界面。
- 记一份事实清单（数字、原话、出处 URL、日期），写稿只用清单里的东西。**凭记忆补的细节（年份、版本号）要么核实，要么删掉。**
- 涉及逆向、爬虫、安全这类话题时，稿子里加一句合规提醒。

## 2. 写稿 → `script.json`
```json
[{"scene":"hook","say":"半年时间，二十四万颗星。","show":"半年时间，24 万颗星","pause":0.35}, ...]
```
- `say` 是读出来的（数字写成汉字更自然：「二十四万」），`show` 是可选的显示稿。`scene` 是场景名，同一个场景的连续句子会被合成一个镜头。
- 结构（60–120 秒）：**钩子（数字/反差，3 秒内）→ 名字/定义 → 生活比喻 → 以前怎么做（痛点）→ 它做了什么 → 演示一次 → 结果/证据 → 范围/亮点 → 官方案例（硬数据）→ 怎么上手 → 提醒 → CTA（评论区提一个问题 + 关注）**。
- 口语短句：一句 ≤20 字，竖屏字幕一行 ≤13 字（会自动折成两行）。术语第一次出现马上配一句大白话或比喻。方法和比喻库见 `core/creative-method.md`。

## 3. 配音 → 逐字时间轴（两种风格通用，格式一致）
输出 `audio/voice.wav` 和 `public/timeline.json`：`{duration, fps, sentences[{scene,say,start,end,words[{t,s,e}]}], mouth[每帧 0..1]}`，其中 mouth 用来驱动主播口型。

配音按优先级选：
1. **真人录音（首选，最有真人感）**：手机录，每句之间停顿 0.5 秒。
   `python3 core/scripts/voice_to_timeline.py 录音.m4a script.json <项目>`
   装了 faster-whisper 就做字级对齐（实测匹配率约 95%，中位误差约 0.04 秒）；没装就靠静音切句 + 句内按字数均分。**换录音后画面和音效会自动重新对齐，不用改代码**，因为画面卡的是「某句里的某个词」。
2. **高质量 TTS**（MiniMax、豆包/火山、ElevenLabs）：需要用户的 key，或者用户自己生成好音频交给你，然后同样走 `voice_to_timeline.py`。
3. **兜底：edge-tts**：`python3 core/scripts/tts_timeline.py script.json <项目>`（`VOICE=zh-CN-YunxiNeural RATE=+8%`）。免费，自带字级时间，但用户普遍觉得「太 AI」。**交付时必须说明，并主动建议换真人录音。**
- 禁止使用 macOS `say`、espeak 这类机械合成音。

## 4. 画面（按所选风格的 GUIDE 做）
共同原则：
- **每个镜头只讲一个意思，并且有一个具体的视觉比喻或真实素材**；名词变成物件，动词变成动作，数字做成计数器或进度条。
- **画面跟着嘴走**：元素出现的时刻 = 关键词开始说的时刻（拟真用 `wf(句号,'词')`，手绘用 `M('词')`），提前 0.1–0.2 秒。
- 每个镜头至少有一个持续的小动作（漂浮、呼吸、转圈、计数、打字），否则像 PPT。
- 每段 2–4 个重音（印章 / 盖章 + 闷响），放在论点落点的词上。

## 5. 质检（必做，通常要改 2–3 轮）
- 取每个场景结束前的一帧作为静帧，拼成联系表，**用看图工具真的看一遍**，再和参考联系表并排对比。
- 按 `core/quality-rubric.md` 逐项打分并写下来，再改。重点查：压字幕、被裁切、文字折行难看（单字掉到下一行）、元素互相遮挡、小窗主播挡住内容、空等（说了一秒多屏幕上还没东西）。
- 成片后再用 `bash core/scripts/contact_sheet.sh 成片.mp4 /tmp/cs.png 4 8` 抽帧复查。

## 6. 配乐音效 + 混音（通用）
1. 写 `cues.json`，音效全部锚在「第 i 句的某个词」上（示例：`styles/realistic/template/cues.json`，格式写在 `audio_bed.py` 文件头）。
2. `python3 core/scripts/audio_bed.py public/timeline.json cues.json audio/` → `music.wav`（`pluck96` 现代拨弦 / `lofi84` 温柔 lofi）+ `sfx.wav`（场景切换自动加 whoosh）。
3. `bash core/scripts/mix.sh audio/voice.wav audio/music.wav audio/sfx.wav out/video.mp4 final/成片.mp4`：音乐会自动给人声让路，整体响度 -14 LUFS。
4. 响度看 ebur128 测出的 I 值（目标 -15~-14），不要看 mean_volume。

## 7. 交付
- 成片 + 一句话说明：用了什么配音、字体，以及数据截至哪天。**你听不到音频，请用户试听。**
- 附上**各平台文案**（模板见 `core/platform-copy.md`）：抖音 / 小红书 / B站（带章节时间戳）/ 视频号 / X。
- 发布：云端浏览器的 IP 通常在海外，登录国内平台发布会显示「IP属地：海外」，还可能触发风控，所以建议用户在本地发布。
- 提供下一步可选项：换真人录音（自动对齐）、换主播形象、做封面、改节奏。

## 文件地图
```
core/        creative-method.md · quality-rubric.md · platform-copy.md
core/scripts tts_timeline.py · voice_to_timeline.py · audio_bed.py · mix.sh · contact_sheet.sh · check_env.sh
styles/realistic/  GUIDE.md · template/（可直接渲染的完整工程 = REA 那期）· reference/（16 张参考帧 + 联系表）
styles/handdrawn/  GUIDE.md · assets/（widgets.js + 参考帧）· examples/ · references/api-cheatsheet.md · scripts/
examples/rea/      script.json + 平台文案（拟真风格完整案例）
```


---

# >>> FILE: core/creative-method.md

# 创作方法：把抽象概念画成一眼能懂的画面

## 1. 比喻翻译表（本项目实测好用）
| 抽象概念 | 画面 |
|---|---|
| 概念太多、分不清 | 名词纸条从天而降、乱抖，一个橙色大问号一笔描出 |
| 只能在对话框里 | 窗户（外框+十字窗棂），机器人从窗里探头；对话框被橙圈圈住，和电脑之间一道虚线墙 + 大叉 |
| 复制粘贴来回搬 | 纸片在两台设备间抛物线来回飞，旁边用「正」字计数 |
| 工具驾驭 AI | 马蹄铁=马具；机器人乱蹦=烈马；橙色缰绳连上后机器人安静微笑 |
| 能看见文件 | 放大镜扫过文件图标，扫到的变橙 |
| 能自己动手 | 鼠标把文件拖进文件夹，落点橙色涟漪 |
| 下命令等结果 | 深色终端里逐字打出命令 → 「✓ 已生成」→ 文件弹出 → 盖章「搞定」 |
| 什么都能做 | 任务卡片网格，按口播顺序逐个弹出+打勾，然后整体变淡，大字结论压上去 |
| 局限：被绑在电脑前 | 小人坐在桌前，被橙色椭圆圈住 + 一把锁，「出门了怎么办？」 |
| 24 小时在线 | 时钟指针快转 + 「24h」+ 闪烁的在线点 |
| 不用管环境配置 | 齿轮出现 → 橙叉划掉 |
| 当老板/团队 | 戴皇冠的小人 + 「去做事！」气泡，机器人 1→4→12 复制，右下「×12」计数 |
| 角色分工 | 一排卡片，每张一个机器人 + 道具（哑铃/日程/地球/手机） |
| 阶段进阶 | 台阶，每级一个图标+一句话，箭头往上，最高一级戴皇冠 |
| 迷雾变清晰 | 灰色波浪线盖住机器人，说到「清晰」时向两边散开，机器人笑 |

规律：**名词→物件，动词→动作，程度→数量/大小，对比→左右分屏+中间虚线，结论→印章**。

## 2. 镜头版式（手绘横屏 1920×1080，世界坐标每镜一块；拟真竖屏版式见 styles/realistic/GUIDE.md）
- 标题行：`y0+90~140`，左起 `tag('@B')` + 标题，核心词用 `blockWord`。
- 主体：左右两栏（对比/因果）或三栏卡片（并列）或中心大物件（定义）。
- 底部结论：`y0+760~830`，印章放右下或正下。`y0+860` 以下是字幕区，不放东西。
- 留白 ≥30%。一镜元素多于 6 个就拆镜。

## 3. 节奏规则
- 元素出现提前 0.1–0.3 秒于关键词（`M('词') - 0.2`），线稿描绘 0.3–0.8 秒，文字每字 0.06–0.08 秒。
- 每镜开头 0.1–0.5 秒内必须有东西开始画（不然像卡住）。
- 重音（印章+震屏+闷响）每段 2–4 个，放在每个论点的「落点」词上。
- 转场交替使用 zoom / scroll / curl（翻页）/ erase（橡皮擦），大段落切换用 curl 或 erase。
- 段尾留一句灰色预告「下一种：搬进云端 →」，把段与段串起来。

## 4. 质检清单（每次看静帧都过一遍）
1. 有没有字没写完（seq 的字数不对）、被裁、压字幕？
2. 元素重叠？中英文混排宽度用 tw() 算了吗？
3. 每镜能一句话说出画的是什么？比喻有没有歧义（像别的东西）？
4. 推镜（CAM z>1）有没有把边上元素推出画面？
5. 皇冠/帽子这类贴在头上的物件，位置按 `makePerson` 头顶 = 脚底 − 232×s − 40×s 算。
6. 每镜有没有持续小动作？

## 5. 拟真风格补充（REA 那期实测）
| 抽象概念 | 画面 |
|---|---|
| 爆火 / 增长 | 真实 GitHub 页面滚动到 stars → 推近 → 手绘圈注；大号计数器 0→239.4k |
| 名字缩写 | 三个橙色字母块砸下 → 各自展开成单词 → 盖章中文意译 |
| 逆向 / 倒推 | 菜（成品）+ 菜谱打叉 + 大厨尝一口 → 配料依次飞出；App 图标 ✓ / 源代码 🔒 → 弯箭头倒推 → 锁消失、代码变清晰 |
| 以前很难 | 真实专业软件截图慢慢平移 + 程序员流汗 + 日历「第 1→5 天」翻页 |
| 接入 / 插件 | 上中下三层：AI 助手卡 → 橙色插头块 → 工具卡，虚线 + 流动光点 |
| 一句话就能用 | 聊天窗口里跟着口播逐字打字 → 发送 → 「正在调用…」转圈 |
| 有证据、不瞎猜 | 步骤转圈 → ✓；结论/证据/不确定三张彩色边卡片；盖章「不靠猜」 |
| 隐私 / 本地 | 电脑 + 盾牌，云朵被红线划掉 |
| 案例硬数据 | 拍立得相框 + 声波环；计数器 + 进度条；63 个字节格子依次变绿；盖章「一模一样 ✓」 |
| 上手简单 | 终端逐字输入命令，输出逐行 ✓ |
规律：**能用真实截图就用真实截图，再用手绘圈注指给观众看**；emoji（Noto Color Emoji）当道具又快又真实。


---

# >>> FILE: core/quality-rubric.md

# 质量评分表（静帧联系表和成片出来后逐项打分，任何一项低于 2 分就改，不交付）

先把你的联系表和对应风格的参考联系表并排看：`styles/handdrawn/assets/reference/00_整片联系表.jpg` / `styles/realistic/reference/00_联系表.jpg`。

## 通用项（两种风格都打）
| 维度 | 0 分 | 2 分（及格） | 3 分（参考帧水平） |
|---|---|---|---|
| 事实 | 有凭记忆写的数字/细节 | 数字都有出处 | 出处 + 截至日期都写清，不确定的不说 |
| 比喻 / 素材 | 只有文字和图标堆砌 | 每镜一个物件比喻或真实素材 | 比喻带「动作」（被驯服、散开、倒推解锁），真实截图上有圈注 |
| 卡点 | 元素按镜头开始平均出现 | 主要元素卡关键词 | 每个名词/动词都对应一个出现时刻，听到就看到 |
| 持续运动 | 画完就静止 | 每镜一个小动作 | ≥2 种同时进行（漂浮 + 计数 + 光点流动…） |
| 角色 | 没有角色 | 有角色 | 角色有表情/口型，随剧情变化 |
| 重音 | 没有 / 每句都在强调 | 每段 2–4 个盖章 | 落在论点落点词上，配闷响 |
| 版式 | 压字、裁切、拥挤、单字掉行 | 不压字，留白 ≥30% | 主次清晰，字幕标黄词和画面强调色一致 |
| 字幕 | 没有 / 和读音对不上 | 和口播同步 | 逐字亮起，关键词标黄，断行自然 |
| 声音 | 机械 TTS / 没有音乐 | 自然 TTS + 音乐给人声让路 | 真人或高质量 TTS；音效和画面用同一个时钟 |
| 响度 | 忽大忽小 | -16~-14 LUFS | -14 LUFS，TP ≤ -1.5 dB |

## 手绘风格追加
| 手绘感 | 矢量图形一次性出现 | 线稿逐笔描出 | 笔尖/马克笔跟随（penOn），线条有抖动和排线 |
| 镜头 | 硬切 | 有转场 | zoom/scroll/curl/erase 交替 + 局部推近 |

## 拟真风格追加
| 真人感 | 静态头像 | 主播口型同步 + 眨眼 | 再加点头、呼吸、挑眉；开头/结尾大号出镜 |
| 真实素材 | 没有截图 | 有截图 | 截图放在设备外壳里，有镜头滚动/推近 + 手绘圈注 |
| 质感 | 纯平背景 | 有阴影/渐变 | 手持微晃 + 颗粒 + 暗角 + 转场模糊 |
| 竖屏安全区 | 内容被平台 UI / 小窗挡住 | 主要内容在安全区内 | 标题、主画面、字幕三区分明，底部只放氛围元素 |

自评要写出来，例如：「case 场景 卡点 1 分：拍立得等到 DX Ball 才出现，前 1.5 秒画面是空的 → 改成场景一开始就出现」。
**不要拿「时长对、文件能播、mean_volume 正常」当质量结论**，那只是能交付的最低技术条件。


---

# >>> FILE: core/platform-copy.md

# 各平台文案模板（交付时和成片一起给）

通用：只用事实清单里的数字，标注数据截至的日期；**抖音和小红书正文不放外链**（可能被限流），链接放 B站简介、评论区或 X。

## 抖音（标题 ≤30 字 + 3–4 行正文 + 6–8 个话题）
标题：数字 + 反差 + 一句话价值。例：半年 24 万星！GitHub 爆火项目 REA，让 AI 帮你“逆向一切”
正文：一个问题钩子 → 它做了什么（一句）→ 结果（一句）→ 评论区提问👇
话题：#AI #GitHub #开源项目 #<领域> #程序员 #AI工具 #<相关产品>

## 小红书（标题 ≤20 字，带 emoji；正文按 emoji 小标题分段）
🍳 是什么（比喻）/ 🔌 做了什么 / 💬 怎么用 / 📦 能做什么 / 🎮 案例数据 / ⚙️ 上手 / ⚠️ 提醒 → 结尾提问。标签 8–10 个。
封面：建议用视频里大数字那一帧，或主播出镜那一帧。

## B站（标题 ≤80 字，用【】标栏目；简介里放章节时间戳 + 项目链接 + 安装命令 + 数据日期）
章节时间戳直接从 timeline.json 各场景首句的 start 取，格式 mm:ss。标签 8–10 个。

## 视频号（2–3 行 + 3–4 个话题），偏稳重，少用网络梗。

## X（英文 ≤280 字符）
Hook line → 一句数字 → 怎么做（一句）→ 安装命令 → “Made a 90-sec explainer 👇”。


---

# >>> FILE: styles/realistic/GUIDE.md

# 拟真出镜风格（竖屏 1080×1920 · Remotion）

参考成片：REA「逆向一切」那期（97 秒）。先看 `reference/00_联系表.jpg` 和 01–16 号帧。

## 「拟真」靠的是这几层（缺一层就会显得廉价）
1. **出镜主播** `<Host/>`：嘴型由 `timeline.mouth`（每帧音量）驱动，会眨眼（随机间隔）、说话时点头、呼吸起伏、音量冲高时挑眉。内容场景里放在右上角小窗 `<FaceCam/>`（带 LIVE 标），开头/结尾等重点场景放大号出镜。
2. **真实素材**：GitHub 手机页面截图、产品界面、官方配图，放进 `<Phone/>` 外壳或带阴影的窗口/拍立得相框里；镜头滚动、推近到关键数字，再用 `<HandCircle/>` / `<HandArrow/>` 橙色手绘圈注。
3. **镜头语言**：全局手持微晃（`Video` 里的 dx/dy/rot）、每个场景缓慢推近、转场时模糊 + 位移 + 淡入淡出（`<Scene/>` 自带）。
4. **质感**：胶片颗粒（`grain.png` 每 2 帧随机偏移）+ 暗角 + 纸色渐变背景 + 点阵。
5. **短视频字幕** `<Subtitle/>`：Noto Sans SC Black + 12px 深色描边，逐字由半透明变亮（跟着发音走），`CFG.keywords` 里的词标黄，超过 13 字自动折成两行（优先在空格、「的/是/把/和/就/，/、」后断）。
6. **声音**：现代拨弦配乐 + 每个动作都有对应音效（打字 click、计数 tick、盖章 stamp、弹出 pop、完成 ding、切场 whoosh）。

## 开工
```bash
cp -r styles/realistic/template /data/work/myvideo && cd /data/work/myvideo
npm i remotion @remotion/bundler @remotion/renderer react react-dom   # 或者软链已有的 node_modules
# 写 script.json → 配音 + 时间轴（见 SKILL.md 第 3 步）
python3 <skill>/core/scripts/tts_timeline.py script.json .           # 或 voice_to_timeline.py 录音.m4a script.json .
# 把截图放进 public/，改 config.ts（栏目名、标黄关键词、哪些场景用大号主播）
# 改 Video.tsx：每个 scene 一个组件，最后在 <Video> 里按顺序挂上 <Scene name="xxx"><Xxx/></Scene>
node render.mjs stills 120 450 900 ...   # 静帧质检
node render.mjs video                    # 整片 → out/video.mp4
```
模板就是 REA 那期的完整工程，能直接渲染。**先改最接近的场景，不要从空白开始写**：
| 想表达 | 抄这个场景 |
|---|---|
| 大数字开场 + 真实网页截图滚动推近 + 圈注 | `Hook` |
| 名字拆解（字母 → 单词）+ 盖章 | `Name` |
| 生活比喻（物件 + 角色 + 元素依次飞出） | `Dish` |
| 有 / 没有对比 + 箭头倒推 + 解锁 | `AppScene` |
| 真实软件截图平移 + 痛点（流汗、日历翻页） | `Old` |
| 架构连线（上中下三层 + 流动光点） | `Plug` |
| 聊天界面里跟着口播逐字打字 → 发送 | `Chat` |
| 步骤转圈 → ✓，结果卡片，盖章 | `Work` |
| 能力清单芯片飞入 → 整体变淡 → 结论卡压上来 | `Scope` |
| 案例拍立得 + 计数器 + 字节格子填满 | `Case` |
| 终端逐字输入命令 + 输出 ✓ | `Install` |
| 合规提醒 | `Warn` |
| 大号主播 + 提问气泡 + 点赞收藏关注 | `CTA` |

## lib.tsx 速查
- 时间：`wf(i,'词',off秒)` 返回第 i 句说到「词」那一刻的**全局帧号**（最常用）；`WIN[scene]=[起,止]` 帧；`S[i].start/end` 秒；`F(秒)` 转帧；`CT[i]` 是逐字时间。
- 动画：`pop(f,起始帧,阻尼)` 弹簧值 0→1；`lin(f,a,b)` 缓动值 0→1。
- 组件：`<Pop start x y rot from>` 弹出容器；`<Title text start sub accent>` 场景标题（左上 x64 y236，**≤7 个字**，84px，否则会折行）；`<Card>`、`<Chip size bg color>`、`<Emoji c size>`（Noto Color Emoji 当道具，比自己画省事又真实）；`<HandCircle x y w h start>`、`<HandArrow x1 y1 x2 y2 start bend>`；`<Spinner done doneAt>`；`<Phone w h>`；`<Host size look energy>`。
- 配色：INK 墨黑、ORANGE 主强调、BLUE、GREEN（成功/证据）、YEL（字幕关键词/高亮底）、CREAM 背景；字体 SANS（Noto Sans SC）/ HAND（霞鹜文楷，手写批注）。

## 竖屏版式（坐标都是 1080×1920，`<Scene>` 内容整体下移了 50px）
| 区域 | y 范围 | 放什么 |
|---|---|---|
| 顶栏 | 150 | 栏目名（CFG.header），进度条在 y=0 |
| 标题 | 236–460 | 左侧 x64–760；右上 x806–1032 / y196–476 是小窗主播，**这块不要放东西** |
| 主画面 | 480–1260 | x 60–1020；抖音右侧按钮大约在 x>940、y 900–1500，重要内容尽量在 x<940 |
| 字幕 | 1395–1560 | CFG.subtitleTop |
| 底部 | >1560 | 会被平台的标题和文案盖住，只放氛围元素 |

## 踩过的坑
- **字幕切段**：按「，。？！：」切，所以「R，E，A」会被切成 3 段单字。lib 已经会把 ≤1 字的段并回前一段。显示文字和读音不一样时，在 `script.json` 里改 `say` 的写法（字幕显示的就是 say）。
- **单字掉行**：标题和卡片宽度要按字数算（84px 的字大约 85px 一个），宁可缩短文案也不要压字。
- **空等**：场景开始后 0.3 秒内就要有东西出现（至少有标题）；主物件不要等到很后面的关键词才出来（例如拍立得应该在场景一开始就出现，而不是等说到「DX Ball」）。
- **截图坐标**：截图缩放成宽 588 后，原图坐标 × (588/原宽) 就是屏幕内坐标；围绕 origin 放大 zoom 倍时，圈注的 x = ox + (x−ox)×zoom。
- **数字精度**：计数器只显示到有把握的精度（239.4k），不要显示「239,400」这种假精确。
- **小窗遮挡**：芯片、标签不要放在 y<480、x>760 的位置。
- **大号主播场景**要加进 `CFG.bigHostScenes`，否则小窗和大号会同时出现。
- 同一时间只跑一个渲染（静帧也算），并行跑会抢 Chrome。97 秒的片子大约渲染 6 分钟。
- 首次渲染会下载 Chrome Headless Shell（约 114MB），需要联网。

## 换主播形象
`Host` 是纯 SVG（viewBox 400×400）：头 / 头发 / 眼镜 / 眉 / 眼 / 嘴 / 卫衣都是独立的 path，改颜色、发型、加帽子都在这个组件里。嘴型逻辑（`mo` 张合、`blink`、`bob`、`brow`）不要动。想用用户的真人照片或 AI 生成的形象：把形象切成「闭嘴底图 + 3 张不同张嘴程度的嘴部贴图」，按 `mo` 选贴图，眨眼用 1 张闭眼贴图，这样口型同步照样能用。


---

# >>> FILE: styles/handdrawn/GUIDE.md

# 手绘笔记风格（dashi-animationstyle 管线 · 默认 1920×1080）

> 通用步骤（研究、写稿、配音与时间轴、质检原则、混音、交付、平台文案）见根目录 SKILL.md；这里只写手绘风格特有的部分。
> 配音：手绘管线自己的 `字幕.mjs` 吃 mp3 + 稿子；用 `core/scripts/voice_to_timeline.py` 生成的时间也可以拿来当 marks 的参考。
> 配乐：本目录的 `scripts/audio_bed.py`（events.json 格式，84BPM lofi + 纸张音效），或者通用的 `core/scripts/audio_bed.py`（`"music":"lofi84"`）。

## 0. 环境准备（一次性）

```bash
git clone --depth 1 https://github.com/chuspeeism/dashi-animationstyle /data/refs/dashi-animationstyle   # MIT
pip3 install edge-tts numpy
mkdir -p ~/.fonts && curl -L -o ~/.fonts/LXGWWenKai-Medium.ttf https://github.com/lxgw/LxgwWenKai/releases/latest/download/LXGWWenKai-Medium.ttf && fc-cache -f
bash styles/handdrawn/scripts/make_render_any.sh /data/refs/dashi-animationstyle    # 生成支持竖屏的 render_any.mjs
bash core/scripts/check_env.sh handdrawn                                # 必须看到 ✓
```
需要 node、ffmpeg、chromium。macOS 上用 `brew install whisper-cpp` 装上 whisper（真人录音对齐更准）。先读管线自带的 `SKILL.md` 和 `styles/手绘笔记`。

## 1. 稿子 → 分段

- 改成**口语短句**：一句 ≤20 字（竖屏 ≤16 字），多用逗号，少用长定语。术语第一次出现配一句大白话（「Harness，本意是马具」）。
- 按内容切段，每段 20–40 秒（一个论点一段）。每段单独做 timeline、单独调画面、单独渲染。
- **先做第一段给用户确认风格**，再做剩下的。
- 结尾固定：总结（把每段的比喻再串一遍，如台阶/清单）+ CTA（点赞收藏关注 + 评论区提问）。

## 2. 配音（最影响观感的一步，按优先级选）

1. **用户真人录音（首选）**：手机录即可，每句之间停顿半秒。有 whisper 就 `node pipeline/字幕.mjs <dir>`（字级时间最准）；没有就 `--no-whisper`（靠稿子 + 静音检测切句，所以停顿一定要清楚）。画面卡的是关键词，换录音后重跑 `生成timeline.mjs`，画面自动跟着走，不用改代码。
2. **高质量 TTS**：MiniMax 语音、豆包语音（火山引擎）、ElevenLabs 等，自然度远高于免费引擎。需要用户提供 API key，或用户在网页上生成好音频交给你。生成后同样走 `字幕.mjs`。
3. **兜底：edge-tts**（`bash styles/handdrawn/scripts/tts.sh 稿子.txt 口播.mp3 zh-CN-YunxiNeural +6%`）。免费，但用户会觉得「太 AI」。交付时要明确说明，并主动建议换录音。
- **禁止**：macOS `say`、espeak 这类机械合成音（量化严重，语速参数基本不起作用）。
- 字幕断句不好用 `styles/handdrawn/scripts/recue.py`；显示文字（标点、中英文空格）在 scenes.js 顶部用 `DISP` 覆盖。

```bash
cd /data/refs/dashi-animationstyle
node pipeline/新建作品.mjs /data/work/seg2 --style 手绘笔记 --audio /data/work/口播2.mp3 --script /data/work/稿子2.txt
node pipeline/字幕.mjs /data/work/seg2 [--no-whisper]
```

## 3. 分镜 + 关键词时间点

编辑 `分镜.json`（示例 `styles/handdrawn/examples/分镜_示例.json`）：
- `shots`：每个镜头包含哪些 cue（2–5 条字幕，约 4–10 秒一镜）。
- `高亮`：A（橙底）/B（墨蓝底）两个本段核心词，字幕自动上色；画面里 `blockWord` 用同色，形成记忆锚点。
- `字幕强调`：加橙色波浪线的词。
- `marks`：**每个要卡点的词**都写上——`python3 styles/handdrawn/scripts/add_marks.py <dir> '[["马具",5,"马具"],["马具2",9,"马具"]]'`。一镜通常 3–6 个 mark。
然后 `node pipeline/生成timeline.mjs <dir>`。

**写代码前先用表格写出每个镜头的「画面一句话」**，例如：
| 镜头 | 口播 | 画面 |
|---|---|---|
| 烈马与马具 | AI 就是那匹烈马，这些工具就是一套趁手的马具 | 左：机器人乱蹦+动作线「AI = 烈马」；右：笔记本里写 Codex/Claude Code「工具 = 马具」；说到第二个「马具」时橙色缰绳连上，机器人安静微笑，盖章「驾驭」 |

比喻库、版式、节奏规则见 `core/creative-method.md`。

## 4. 写场景 scenes.js

**从 `styles/handdrawn/examples/` 复制一个最接近的段落改**，不要从空白开始。结构：
```js
const DISP = {...}; TL.cues.forEach(c => { if (DISP[c.id]) c.text = DISP[c.id]; });
['zoom','scroll','curl','zoom','scroll','erase'].forEach((k,i)=>{ if (FX_CUTS[i]) FX_CUTS[i].kind = k; }); fxPlan();
const SEC = 1150, Y = i => i * SEC, ST = i => fxStart(i);   // 每个镜头占世界坐标里一块「纸面」
// @@WIDGETS@@        ← build.py 在这里插入 assets/widgets.js
const S1 = (() => { /* 预先构建 Sk 线稿（固定随机种子，帧间不抖） */ })();
function draw1(t, v) { if (!seen(v, y0-100, y0+SEC)) return; /* 按 M('词') 逐个出现 */ }
CAM0 / CAM（镜头运动）; SHAKES（重音震屏）; function fxBefore(t){...}; function drawScenes(t,v){ draw1(t,v); ... }
```
硬性要求（对应评分表）：
- 每镜 3–6 个元素，**至少一个角色**（`drawRobot` 带 `happy`/`look` 表情变化，或 `makePerson`）。
- **每镜至少一个持续的小动作**：漂浮 `Math.sin(t*1.5)*8`、乱蹦、复制 1→4→12、指针快转、迷雾散开、速度线。没有持续动作就像 PPT。
- 出现方式：线稿 `S.at(t,t0,d)` 逐笔描（大件加 `.penOn()`）；物件 `popIn`；文字 `writeText(..., seq(t0, str, 0.07))`；核心词 `blockWord`；结论 `drawStamp`。
- 安全区（横屏）：x 150–1800，y `y0+60`…`y0+860`。
- **不要在 scenes.js 里重复定义 widgets.js 已有的函数**：JS 后定义的同名函数会覆盖前面的，改了部件却看不到变化。改部件前先 `grep -n "function 名字" index.html` 确认只有一处。
- API 速查：`styles/handdrawn/references/api-cheatsheet.md`。

拼页面：首次 `python3 styles/handdrawn/scripts/patch_template.py <dir>/index.html base.html`，之后每次改完 `python3 styles/handdrawn/scripts/build.py base.html <dir>`。

## 5. 质检（批评回路，必须做，通常要 2–3 轮）

```bash
cd <dir> && node /data/refs/dashi-animationstyle/pipeline/render.mjs index.html --stills 3.5,9.3,13.5,19.5,28.5,39.8 --outdir 静帧 --prefix q
montage 静帧/q_静帧_*.png -tile 3x -geometry 640x360+4+4 /tmp/m.png    # 用看图工具真的看
```
每镜取「快结束时」一帧。逐张对照参考帧，按 `core/quality-rubric.md` 打分并写下来，再改：
- 字没写完（`seq(t0, n)` 字数写少）、被裁、压字幕、互相重叠？中英混排宽度用 `tw()` 算。
- 一眼能看懂吗？比喻有没有歧义（马蹄铁下加缰绳，结果像铃铛 → 删）？
- 镜头推近（z>1）有没有把边上的元素推出画面？
- 还要抽查**元素正在出现的时刻**（关键词 ±0.2 秒），确认是卡着嘴型出现的。

## 6. 渲染（一次只跑一个）

```bash
node /data/refs/dashi-animationstyle/pipeline/render.mjs index.html -o 画面.mp4 > render.log 2>&1   # 约 4.5 秒/秒视频，后台跑
```
**不要同时跑两个渲染（包括静帧）**，否则会 `Page.captureScreenshot 失败`。多段写成一个脚本顺序渲染。渲染速度快得离谱（例如 80 秒片 20 秒出完），通常说明画面太简单，或者没用这套模板。

## 7. 配乐音效 + 拼接 + 混音

1. 每段画面时长 = TL.duration；口播逐段 `apad=whole_dur=<段时长>,atrim` 补齐再 concat，保证音画逐段对齐。
2. 写 `events.json`，**音效时间全部从 TL.marks / TL.shots 算**（和画面同一个时钟）：纸条/卡片 pop、印章 stamp、打勾 ding、打字 click、切镜 whoosh = 各 shot.start。`python3 styles/handdrawn/scripts/audio_bed.py events.json` → 全长 lofi 音乐 + 音效轨。
3. `bash styles/handdrawn/scripts/concat.sh video.mp4 seg1/画面.mp4 seg2/画面.mp4 ...`
4. `bash core/scripts/mix.sh voice.wav audio_music.wav audio_sfx.wav video.mp4 成片.mp4`（音乐自动避让人声，loudnorm -14 LUFS）。
5. 响度用 `ffmpeg -i 成片.mp4 -af loudnorm=print_format=summary -f null -` 看 Input Integrated（目标 -16~-14 LUFS），不要用 mean_volume。
6. `bash core/scripts/contact_sheet.sh 成片.mp4 /tmp/cs.png 4 6`，和 `styles/handdrawn/assets/reference/00_整片联系表.jpg` 并排对比。

## 8. 竖屏 9:16（抖音/小红书/视频号）

模板默认 1920×1080，已提供竖屏补丁（舞台、画布、镜头焦点、字幕区都改好了，已实测能渲染）：
```bash
python3 styles/handdrawn/scripts/patch_template.py <dir>/index.html base_v.html --vertical
VW=1080 VH=1920 node /data/refs/dashi-animationstyle/pipeline/render_any.mjs index.html -o 画面.mp4
```
竖屏版式要**重新设计**，不能直接套横屏坐标：
- `SEC = 1900`；镜头中心 `CAM0/CAM` 用 `(540, Y(i)+863, 0.95)`。
- 安全区：x 60–1020，y `y0+60`…`y0+1580`（下面是字幕区）。
- 左右对比 → 上下对比；三栏卡片 → 2×2 或纵向列表；标题字号 72–90，正文 52–60。
- 每条字幕 ≤16 字（字号 56，宽 1080）。

## 交付（见 SKILL.md 第 7 步）
- 用了什么配音、什么字体（霞鹜文楷）；你听不到音频，请用户试听。用的是兜底 TTS 的话要主动建议换录音。
- 附上质量评分表的自评结果和联系表。
- 发布：云端浏览器 IP 通常在海外，国内平台用它登录发布会显示「IP属地：海外」，还可能触发风控。建议用户在本地发布。


---

# >>> FILE: examples/rea/README.md

# 案例：REA「逆向一切」（拟真出镜 · 竖屏 · 97 秒）
- 完整工程就是 `styles/realistic/template/`（Video.tsx 里的 13 个场景、config.ts、cues.json、public/ 素材和 timeline）。
- `script.json`：20 句口播稿（钩子 → 名字 → 比喻 → 痛点 → 方案 → 演示 → 证据 → 范围 → 案例 → 安装 → 提醒 → CTA）。
- 事实来源：github.com/morluto/rea 的 README 和 GitHub API（stars 239.4k、forks 59.6k，截至 2026-10-14）。
- 成片参考帧：`styles/realistic/reference/`。
- 平台文案：`platform-copy.md`。


---

# >>> FILE: examples/rea/platform-copy.md

# REA 那期实际交付的文案（节选）
抖音标题：半年 24 万星！GitHub 爆火项目 REA，让 AI 帮你“逆向一切”
小红书标题：半年24万星🔥AI帮你拆解任何App
B站标题：【GitHub 爆火】半年 24 万星！REA：让 AI 帮你“逆向一切”，一句话拆解任何 App
B站章节：00:00 半年 24 万星 / 00:08 名字的含义 / 00:11 逆向是什么 / 00:28 以前为什么难 / 00:33 REA 做了什么 / 00:43 一句话发起分析 / 00:50 结论+证据+不确定 / 00:58 能分析什么、本地运行 / 01:11 官方案例 / 01:21 一行命令安装 / 01:24 合规提醒
X：GitHub's hottest project right now: REA — Reverse Engineer Anything 🔍 240k stars in ~6 months. It connects your AI agent (Claude Code, Codex, Cursor…) to tools like Ghidra, IDA & Hopper. Ask one question, get findings + evidence + unknowns. Runs locally. `npx rea-agents setup`