/ray-explainer

name: ray-explainer
description: 把文章或观点做成知识解说视频（默认竖屏，要求时出横屏；1.5–3 分钟，用 Ray 的复刻音色配音 + 字幕）：真实画面优先（录屏、实拍、截图），近几期主要走 HyperFrames 按内容定制风格（配乐、左下角数字人、发布包），也能用代码逐帧绘制的手绘套路。用于“做成解说视频”“做一期科普视频”“知识科普短片”“用我的声音配音”；Ray 的解说、科普视频优先用本 skill，不直接走通用的 hyperframes 或 faceless-explainer（本 skill 内部会调 HyperFrames）。只要口播稿转 ray-kb，要封面转 ray-cover；给已录好的整条真人口播加字幕或图卡转 embedded-captions / talking-head-recut（按本 skill 的 IP 规范带风格）；口播要剪成课程片（口播打底 + 全屏画板页 + 截图录屏）留在本 skill，用风格库（如 `ali`）。

Ray Explainer

把一篇文章压成一条“开头吸引人、看完有收获”的解说片。Claude 同时当导演和程序员：写稿、分镜、给每一幕选画法、写每一帧的绘制代码、看截图返工；浏览器和 FFmpeg 只负责把代码变成像素和文件。

核心约束：**每一帧只由时间 t 决定**。不读当前时间，不用 `Math.random`（用 `rng(seed)`），渲染时不联网。守住这三条，同一份代码每次都渲染出完全一样的视频，改一处只影响一处。

链路

素材 ─▶ ① 解说稿 script.json ─▶ ①b 分镜表 storyboard.py【Ray 确认】
     ─▶ ② 配音 tts.py（默认 Ray 复刻音色；没注册时用 Gemini 预置音色）
     ─▶ ③ Whisper 校对 qa_tts.py（合格判定 + 逐字时间写入 timeline）
     ─▶ ③c 原声插入 splice_clips.py【有原声时】
     ─▶ ③b 数字人主持人 host.py（左下角口型默认带；大机位用户确认后才做）
     ─▶ ④ 分镜：kit 场景写 scenes.js；语法场景只写 cues
     ─▶ ⑤ 静帧检查 render.js sheet ─▶ ⑥ 出片 render.js video + 听感检查 audio_check.py ─▶ ⑧ 发布包 publish.py

**专属风格模式**（HyperFrames，近几期的主要做法）：要适合这期内容的风格、要有录屏 / 真实画面 / 截图时（按下面「真实画面优先」，多数科普片都是这样），②③ 照旧，④⑤⑥ 换成 HyperFrames 合成，流程、骨架、取材要点和安全区见 [hyperframes.md](references/hyperframes.md)。这个模式自带：按章节分段的进度条顶栏、原声插入（`splice_clips.py`）、本地生成配乐（`gen_bgm.py` / `mix_bgm.py`）、用锚点定位的少量音效。会动的网页（交互图解、WebGL 演示）用 `scripts/record_clip.mjs` 按虚拟时钟录成确定的片段。

**真实画面优先**（Ray 2026-10-15）：观众愿意看的是真实的东西，手绘、代码动画看久了审美疲劳。每一幕先找真实素材，**动态的优先于静态的**：录屏、本机实跑、产品官方演示片段、新闻 / 发布会画面、别人视频里被讨论到的那一段、Ray 自己的视频和后台数据；其次才是真实截图、原文、照片。代码动画只做两件事：把真实素材串起来（转场、标注、计数、对比），以及真实画面拍不到的抽象机制。别人的作品可以作为引用进成片，画面上标「来源 · 日期」。分镜关每幕写 `footage`（用什么真实素材、从哪来、是不是动态），`storyboard.py` 会列出来，整片动态真实素材太少会提醒。**真实视频默认全屏**（Ray 2026-10-15，《Roadster 真能飞》复盘：素材装在小机位窗口里冲击力不够）：科普 / 解说片里的真实视频素材默认用 `.fullshot` 铺满整个画面播放——竖屏原片直接铺满，横屏素材裁成竖屏、跟着主体走（`object-position`）；不装进机位窗口。窗口只留给截图、原帖、静态图和需要并排对比的场合。提问句之后可以用 `splice_clips.py` 插一段带原声的全屏插片，播完切回画板。分镜关每条 `footage` 写 `fullscreen: true/false`。**静态图不能直接当画面**（2026-10-22 起，学 Peter Yang）：照片、截图、文件要动起来，可以慢慢推近、平移、逐行高亮，或用作 AI 视频的首帧。成片检查列出「3 秒以上没有明显变化」的段落要回看；整块画面匀速慢推几个百分点不算动（检查也把它算作没变化），要在讲到那一处时有目的地动。**网页按画面宽度截成长图，再从上往下慢慢移**：`python3 $SK/scripts/capture_page.py <网址> out.png [--landscape]`。页面按画面宽度排版，文字不会在画面边缘被切断；挑完整的一段来移。遇到要登录或有人机验证的页面，改用 Ray 的 Chrome 截。**主体是整台设备或宽画面时整幅横放**（Ray 2026-10-16，宝可梦那期：双手横握 iPhone 的横屏素材被裁成竖屏，手机被切掉，返工）：`footage` 写 `"framing": "band"`，横屏原片按原比例横贯舞台中部，上下用同一段视频虚化压暗垫底（`.bandshot`）；`storyboard.py` 见到手机、掌机、超宽屏一类素材没写 `framing` 会提醒。

**两道确认关口**：稿子关（只看旁白）和分镜关（看每幕画什么、用什么画法）。两关都在配音和写画面之前，这时改动不花钱，过了这两关再开始做，可以避免返工。用户说“直接做”时两关都跳过；说“稿子我看过了”时只过分镜关。

**画幅**：默认竖屏 1080×1920（抖音、视频号）。Ray 要横屏时（YouTube、视频号 / 抖音横屏）才出 1920×1080：`new_project.sh <slug> --landscape`，即 `script.json` 顶层 `"aspect": "landscape"`。一个项目只出一种画幅，不同时出两版。横屏只能用语法片段或 HyperFrames 模式（手绘套路是竖屏坐标，`render.js` 会拒绝）；没有进度条，字幕白字黑描边，主持人是只在关键句出现的小圆窗、按幕在左下 / 右下之间换（[host.md](references/host.md)「横屏」）。尺寸、安全区、字幕和主持人版位都在 `assets/canvas.json`，各脚本从那里读。

**整条真人出镜的口播不走本 skill 的链路**（Ray 2026-10-20 定）：Ray 录好的口播视频本身就是成片画面，只要加字幕或图卡时，交给 HyperFrames 的两个通用 skill，原片不剪、不调色——只加字幕（含字幕嵌到人身后、特效字）用 `embedded-captions`，加标题、人名条、数据卡、金句卡、画中画用 `talking-head-recut`。用 Ray 的录音给解说片配音、脸只在小圆窗里出现的，仍按「2. 配音」的 `recording` 走本 skill。这两个 skill 不认识 Ray 的风格，调用时要把签名层带过去：颜色、墨绿用法照 [ip-style.md](references/ip-style.md)（黑白灰 + 一处墨绿，不加别的色相；结尾导流卡可用整屏墨绿签名幕）；字体用思源黑体 / 霞鹜文楷；竖屏信息只放 y 200–1680、横屏四周留 5%，数字从 `assets/canvas.json` 取。这两个 skill 是 HyperFrames 上游的，不在 rayskills 里，没装时用 `npx hyperframes skills update embedded-captions talking-head-recut` 装（本机 10-20 已装）。

**例外：口播要剪成课程片、长视频时，用风格库**（Ray 2026-10-21 定）。这种片子以口播打底，中间切到全屏画板页、截图和录屏，人像卡跟着口播同步。这时不交给上面那两个 skill，用 [styles/README.md](references/styles/README.md) 里的风格来做。课程片用 `ali`（[ali.md](references/styles/ali.md)，模板 `assets/styles/ali/`）。

**横屏科普解说片默认用风格库的 `xiaolin`**（Ray 2026-10-21 定）：深色底、新闻画面快切，加玻璃气泡图、盖章、引语卡，见 [xiaolin.md](references/styles/xiaolin.md)，模板 `assets/styles/xiaolin/`。配音照 ②③ 走，拿到 `timeline.json` 以后，画面用这个模板做，不再走专属风格模式的通用骨架。

**Ray 录的口播先剪重说和长停顿，再去吸气音**（2026-10-22 起，剪法学 Peter Yang 的 video-short）：

python3 $SK/scripts/cut_retakes.py scan <原片> -o work

1. **扫描**：用 Whisper 拿到逐字时间，用能量找出真正的停顿，写出 `work/transcript_raw.md` 和建议的 `work/cuts.txt`。逐字稿里标好了停顿、整句重说和句内重说。 2. **默认剪法**：

• 重说只留最后完整的那一遍。
• 超过 0.6 秒的停顿缩到 0.3 秒。
• 切点贴在真实停顿上。
• 不变速。

3. **看稿改剪辑决定**：通读逐字稿，改 `cuts.txt`。标「没找到停顿，未剪」的几处要你决定：可以把那 4 秒单独重转写一遍来定切点，拿不准就问 Ray。 4. **应用**：`cut_retakes.py apply <原片> work/cuts.txt -o clean.mp4`。它会写出剪后逐字稿；切点处声音还很响的会单独列出，说明可能切进了字里，要挪。 5. **复核**：重转写一遍剪后的成片，确认没丢字。

10-14 那条 345 秒的录音，自动剪到 273 秒；另有 8 处要人工确认。

之后对 `clean.mp4` 去吸气音。

**Ray 录的口播先去吸气音**（Ray 2026-10-20 定，所有他自己录的口播都要做）：句子之间的吸气声要压掉。动画面之前先跑 `python3 $SK/scripts/gate_breaths.py <原片> -o voice.wav --verify`：按能量、过零率、频谱重心找出句间吸气，压到 −45 dB、两头 20 ms 淡入淡出，停在下一个字起音前 30 ms（不吃「所以 / 先 / 从 / 写」的声母），时间轴不变、不剪画面。成片里把原片 `<video>` 设成 `muted`，另加 `<audio id="voice" src="voice.wav">` 同起同止。`--verify` 会重新转写对比：Whisper 每次跑都有零星差异，只有紧挨 `voice.cuts.json` 里某个时间点的字变了才算剪坏，去那一处听一下。第 1 节课程视频实测：190 秒里 27 处、7.4 秒，没有丢字。

脚本都在本 skill 的 `scripts/` 下，下文用 `$SK` 指代本 skill 目录。

0. 环境自检

$SK/scripts/check_setup.sh

必须看到 `READY`。缺 `GEMINI_API_KEY` 就向用户要 key，不要换别的服务凑合。输出里会列出已注册的复刻音色。

1. 读素材，写解说稿

读完整素材（剪藏、候选选题卡、已有口播稿都算）。库里有 Ray 的已录口播稿时，先读一篇找语感。

$SK/scripts/new_project.sh <英文-slug>      # 默认建在 ~/Movies/ray-explainer/YYYY-MM-DD-<slug>/；横屏加 --landscape

视频文件不要放进 Obsidian vault：vault 带 git 自动快照，大文件会进历史。

按 [script-rules.md](references/script-rules.md) 写 `script.json`：按场景分组，每场景 1–4 句，每句是一次配音调用，也是一个画面节拍。顶层写 `title`、`central_judgment`、`header`（顶部小标题）、`theme`（全片色板，见 [grammars.md](references/grammars.md)「全片色板」；新项目默认 `"ray-ip"`，即 Ray 的 IP 规范，见 [ip-style.md](references/ip-style.md)：开场和结尾那一幕写 `"sig": true`）、`voice`、`to_confirm`。

1b. 分镜关

稿子定了以后，先按 [grammars.md](references/grammars.md) 给**这一期**定一种画法（一期只用一种），再从 [style-refs.md](references/style-refs.md) 挑一张参考卡定风格（参考卡只借版式；Ray 认可过、带模板的整套做法在[风格库](references/styles/README.md)）（Ray 指定了就用他的；他丢来新链接就按那里的方法抽帧建卡），`script.json` 顶层写 `"style_ref"`，再给每一幕补三个字段，并用这种画法写好 `gram