video-to-layout

把一段口播内容变成成片和可编辑的剪映工程。五步流水线，每步都能独立调用。

输入 → ①提取视频/文案 → ②文案转时间轴 → ③Remotion 动态排版 → ⏸预览确认 → ④渲染成片 → ⑤剪映草稿

> 本技能是 all-platform-video-extract 的下游扩展，第 ① 步直接复用它的解析/下载能力。
> 动态排版基于 Remotion（React 视频框架）。

每一步的输入与产物

bash scripts/pipeline.sh extract    "<链接>" --out ./01-source
bash scripts/pipeline.sh transcribe ./01-source/*/audio.mp3 --out ./02-script
bash scripts/pipeline.sh voice      ./项目目录          # ← 要配音时：先配音，再让画面照着配音长
bash scripts/pipeline.sh design     ./02-script/文案.txt --out ./03-layout/design.json   # ← 只给 custom 用
bash scripts/pipeline.sh layout     ./02-script/文案.txt --out ./03-layout --aspect 16:9
bash scripts/pipeline.sh review     ./项目目录          # ← ① 先给审阅台（实况播放 + 直接改文案）
node review/check-wiring.mjs                           # ← 写回链路自检（pipeline review 已内置）
bash scripts/pipeline.sh storyboard ./项目目录          # ← 要「全片一览」存档时再给
bash scripts/pipeline.sh studio     ./项目目录          # ← 要逐帧拖拽/调参时再起，输出 STUDIO_URL
bash scripts/pipeline.sh render     ./项目目录 --go     # ← 弹窗确认后才加 --go
bash scripts/pipeline.sh cover      ./项目目录          # ← 要发抖音/视频号时，出封面挑图

> 两条硬约定
>
> 1. 生成动态排版后必须停下来询问用户是否渲染（--auto-render 可跳过）
> 2. 停下来的同时先起审阅台把 REVIEW_URL 直接给出来；需要全片一览再补 storyboard，
> 需要逐帧调参再起 studio。不要只说一句「可以预览了」

数据从哪来、到哪去（改代码前先看）

文案.txt ──tts.py──▶ voice/sc01.mp3 + manifest.json（真实时长）
                          │
                          ▼  gen-layout.py --voice（不给就走字数估算）
文案.txt ──gen-layout.py──▶ layout.json ──build_token_data.py──▶ remotion/src/data.ts
     │                          │                                    │
     │                          │                                    ├─▶ 成片（render）
     │                          │                                    ├─▶ 分镜联系表（storyboard）
     │                          │                                    └─▶ density 自检
     │                          │                        review.overrides.json（审阅台写回，唯一的文案改动面）
     │                          │
     │               mix_voice.py（按 t0 把配音摆进时间轴）
     │                          └──▶ mix.wav ──▶ public/audio/ + data.ts 的 AUDIO
     │
     └─ ⑤ make-draft.py 读 layout.resolved.json（由 data.ts dump，含审阅改动）──▶ 剪映草稿
                                  theme.json ──▶ Root.tsx 的 defaultProps（配色）

三条硬规则：

1. 改文案只走审阅台（写 src/review.overrides.json），不要手改 data.ts——重跑 layout 会重建它。
2. 结构字段锁死：id/start/end/kind 不会被 overrides 覆盖，时间轴永远以 data.ts 为准。
   （配音模式下 layout.json 的 t0/t1 来自 manifest.json，仍以 data.ts 为最终载体。）
3. 草稿与审阅同源：render 会在写回非空时自动 dump layout.resolved.json 给草稿用；只有 dump 失败才回退原始 layout.json。

六套视觉资产（先选对，再动手）

默认是 custom：每片的视觉语言由文案推导，不预设模板。 其余五套是「换风格」，
当用户明确说「用 token / 用 mint / 要竖屏」时才切。

> 画幅与默认的关系：custom 只按 1920×1080 排（字号写死，竖屏会溢出）。
> 不写 --style 而文案是 9:16 时，自动退到 token-v 并打印提示；
> 显式写 --style custom 又给竖屏，直接报错——用户明确要的东西不偷偷换掉。

wave（声学测量）适合什么

讲「过程 / 原理 / 数据」的片子，尤其是音频、节奏、剪辑工具这类题材。
它的差异化不在配色，在于波形是真的：

mix.wav ──extract_waveform.py──▶ src/waveform.ts（逐帧 RMS/峰值）
                                        │
                                        ▼
                        Video.tsx 的 <Wave> 按当前帧取窗口画柱状

每根柱子的高度都对应真实的采样能量。观众看到的起伏就是他们听到的声音——
如果片子本身在讲节奏，这个细节才站得住。

python scripts/gen-remotion.py layout.json --out ./wave --style wave --audio audio/mix.wav
bash scripts/pipeline.sh voice ./项目目录      # 混音后会顺手重算 waveform.ts

十个版式：open（大字报开场）/ line（居中单句+取景框）/ list（待办条目 +
右侧分量条）/ deny（否定句：红线划掉答案）/ metric（巨大数字 + 右侧渲染崩溃卡）/
splitBad（两条轨错位，红虚线标出永远对不上的区间）/ splitGood（两轨吸附对齐，绿连线锁住）/
speed（真实语速曲线）/ stack（四件产物依次点亮）/ outro。

另有背景代码流（CodeRain）：全片常驻，边缘飘的是这条片子自己的参数
（loudnorm=I=-16 / silence_start .284 / rate=+45%），不是乱码。
用 mask-image 把中心遮掉，文字区域保持干净。

> 装饰性动效的判断标准：它只对这一句话成立吗？
> 「加个粒子/加个光斑」放任何句子都成立，也就意味着放哪都没意义。
> 所以 deny 的红线只划否定句的答案，CrashCard 只出现在讲「耗时」的数据幕。

splitBad / splitGood 是这套风格的技术核心：用轨道对齐关系直接讲清
「为什么旧办法永远对不上」。路由靠文本语义（认得出「对不上」「先配音」），
不靠 kind——因为 dedupe_kinds 会把连续的 points 改写成 cards / rows。

speed 是第二个技术核心：横轴全片时间、纵轴字/秒，每幕一个点、
高度来自 manifest 的实测时长（cps = 汉字数 / 净配音时长）。
观众能看到讲原理的地方低下去、金句翘起来，虚线是平均值。
前提是 gen-remotion.py --style wave 能读到 voice/manifest.json
（它会在 layout.json 同目录自动找），否则显示占位提示。

stack 的四张卡不放代码图标，放真实产物：

python scripts/collect_shots.py --project ./wave \
    --video ../成片.mp4 --cover ../封面.png \
    --srt ../字幕.srt --draft "<剪映草稿>/draft_content.json"

成片抽帧、封面缩图、SRT 前 3 条、草稿轨道数——都是能核对的东西。
缺哪项就退回图标，不会因为某个产物没生成就报错。
生成的 src/shots.ts 里刻意不写时长：缩略图可能是从上一版成片抽的，
标上 35.5s 就是让卡片自己说谎。

审阅台的「整片预览」播的就是 WaveVideo（FullVideo 别名），
声音来自组件内部的 <Audio src={staticFile(AUDIO)} />——
审阅台服务需要把 public/ 挂到根路径，否则画面能播、声音 404。

配套：Cover.tsx 出 1080×1440 深色封面（REC 红点 + 测量网格 + 装饰波形），
字体用思源黑体 900 + JetBrains Mono（assets/fonts-wave/，woff2 共 2.3MB）。

custom（按文案定制）怎么用

前面五套是「换风格」，这套是换设计：它不预设品牌视觉，先由脚本读文案判气质，
产出一份 design.json（情绪 / 色板 / 字体 / 动效密度 / 每幕视觉隐喻），
再由 Agent 照着这份简报重写版式。

# ① 文案 → 视觉简报（不给 --style 时 pipeline 会自动做这一步）
bash scripts/pipeline.sh design 文案.txt --out 03-layout/design.json

# ② 生成工程并把简报塞进 src/design.json
bash scripts/pipeline.sh layout 文案.txt \
  --design 03-layout/design.json --out ./项目目录

# ③ 按 design.direction 重写 src/Video.tsx（这是重点，别跳过），再起审阅台
bash scripts/pipeline.sh review ./项目目录/remotion

简报怎么定的（scripts/design_brief.py）：

分幕认三种输入（design_brief.py 的 parse_script）：

1. 时间码：[00:06 - 00:13] 正文，后面紧跟的 #kicker: / #note: 归这一幕
2. 标签块（抖音项目实际写法）：#points + #kicker: 标题，空行之后再写正文
3. 纯文案：按句合并到 16 字以上一幕

连续三幕同一版式会被 smooth_layouts() 打散（第三次按内容换成 metric / quote），
避免「一套动画换个字」。想钉死某一幕的版式，直接在 design.json 里写 layout。

顺序很关键：先配音，再出工程。 layout 只给估算时长（按字数算），
没配音就没有音轨——AUDIO 是空串，渲出来是哑的。要声音就走：

bash pipeline.sh voice  ./项目目录     # 配音 + 重排时间轴 + 挂音轨 + 出字幕
bash pipeline.sh render ./项目目录 --go

配音后再 gen-remotion.py --force 重生成工程是安全的：它会沿用 public/audio/mix.wav
（--audio 不传也不清空），custom 的 src/Video.tsx 也会保留，不会被模板盖回去。

custom 执行准则（默认风格的硬要求）

这六条是 custom 的验收标准，不是建议。做 default 风格就必须逐条满足；
交付前自检时拿它对照，做不到就说清哪条没做到、为什么。

1. 风格由内容推导，不预设

先读文案，判断题材、情绪、信息密度、目标观众，再定视觉语言
（科技 / 纪实 / 温情 / 商务 / 复古 / 抽象几何…）。
配色、字体、构图、动效曲线整片统一，且这个统一是从这段文案里长出来的。
禁止套用固定模板——包括「上次那个效果不错，这次照抄」。

落地方式：design.json 的 palette / type / motion 必须有依据（写进 direction 字段），
不是随手挑的色值。换一条文案重跑，简报应该真的变。

2. 动态是主线，不是装饰

文案里的每个核心概念、数据、比喻、转折都要有对应的动态视觉表达，
不能是「静态图文 + 淡入淡出」。

判断标准还是那句：这个动效只对这一句话成立吗？ 放哪句都成立的，就是装饰。

3. 素材全原创，零外部依赖

所有图形、图标、纹理、背景、光效、转场、图表，一律在 Remotion 里
用 SVG / CSS / Canvas / Three.js 程序化生成。
不引外部图片、不用占位素材、不使用有版权风险的资源。
（字体走 assets/fonts* 里的开源字体 + staticFile()，这不算外部依赖。）

4. 先结构，后复杂

矛盾时按这个顺序：先完成分镜与节奏规划——每段讲什么、停多少帧、
信息如何递进、情绪如何起伏；确认格局合理后，再把复杂度拉满——
多层动效叠加、粒子 / 网格 / 线条氛围层、景深与镜头运动、细节微动。

反过来说：结构不清的时候加动效，只会让观众更看不懂。
design.json 的 scenes[] 就是结构层，先把它弄对，再改 Video.tsx 的表现层。

5. 不偷懒，且可验收

• 每个镜头至少两层独立动效（入场层 + 持续变化层 + 退场层，取其二以上）
• 每个章节至少 1 个独立视觉记忆点
• 不允许整片只有一个淡入淡出敷衍过场

验收方式（不靠感觉）：

bash scripts/pipeline.sh review  ./项目目录     # 逐幕看，每幕动效是否都在跑
bash scripts/pipeline.sh density ./项目目录     # 动效密度体检

画面必须铺满，不能「一行字裸放在渐变底上」。 这是最容易偷懒也最伤观感的一条：
2026-10-29 实测默认模板 8 幕里有 7 幕密度低于 3.0（最低 1.35），
渲缩略图看是文字只占左侧 20%、其余全是空渐变。

做法是给每个版式补有信息量的结构层（不是加噪点）：

注意 细线在小图上会被均值化掉：density 检测会把画面缩到 0.4 倍，
1~2px 的刻度线在那之后几乎不产生边缘。真正撑住密度的是成块的对比内容
（卡片、大字、实心条、环形仪表）。

6. 复杂度上限

• 单镜头动效层数 ≤ 5 层（超了就是堆砌）
• 整片代码模块化：每段一个组件、参数化，别写成一个巨型 Video.tsx
• 渲染时长控制在可接受范围

复杂是为了信息表达，不是为了堆砌导致卡顿与不可维护。

> 这六条和 motion.density（1~5）配合：密度低不等于可以只做淡入淡出，
> 而是「层数少但每层都算数」；密度高也不等于可以超过 5 层。

短幕要压缩入场节奏

配音会把句子变短——「便宜不是坏事」只有 1.4 秒。
入场动画的延迟若按 5 秒一幕写死（0.3s 起步、每项 +0.2s），
整幕都在做入场，观众看到的是还没排完版的画面。
内置版式用 ENT = min(1, 幕长/3.2) 压缩入场延迟，常驻动效不压缩
（breathe / pulse 是底噪，压缩了会抖）。自己重写版式时沿用这个约定。

契约（别破坏，审阅台和渲染都靠它）：

• 导出 CustomVideo（整片）+ SceneOnly（审阅台单幕），FullVideo 是别名
• 时间轴只读 data.ts 的 SCENES，start/end 由配音决定
• 动画是 useCurrentFrame() 的纯函数，不用 Date.now() / Math.random()
• 字体必须走 staticFile()——写死 /fonts/x.woff2 在渲染服务里会 404（这个坑踩过）
• 不新增 npm 依赖

内置版式是起点，design.json 的 scenes[].layout 会覆盖按 kind 的默认路由：

> 数据脏的时候别硬渲染：cards[].v 的占位 "0" 会被当成真数字（这个坑踩过）。
> 现在的规则是「占位值 = 没有数字」，再从标题里找真实那个；找不到就不摆仪表。

> 只支持 1920×1080（字号按这个基准写死）。不写 --style 给竖屏文案会自动退到 token-v；
> 显式 --style custom 给竖屏会直接报错，让你选清楚。

四个入口怎么选

🔗 启动编辑器（可选 —— 不主动起，用户要求时才给链接）

2026-10-28 用户改了口径：交付流程里不再自动启动 Remotion 编辑器。
只在用户明确说「我要逐帧调参 / 打开编辑器」时启动，并且必须把可点链接直接给出来
（2026-10-24 定的「不许口头描述」仍然有效）。

bash scripts/pipeline.sh studio <工作目录>        # 输出最后一行固定为 STUDIO_URL=http://localhost:xxxx
bash scripts/pipeline.sh studio <工作目录> --open # 顺手用默认浏览器打开
bash scripts/pipeline.sh studio <工作目录> --port 3200

它的行为：

交付纪律：把 STUDIO_URL 的值作为链接给出，不要凭印象写端口——上次给了一个自己已经退出的端口，用户点开只能看到白屏。

> 常驻靠 打开预览.cmd：双击 → 新窗口跑 npx remotion studio → 浏览器自动打开；关窗口即停。
> 这个文件每次跑 studio 都会按当前端口重写，不用手动维护。

> 启动器的 5 个 Windows 坑（.cmd 纯 ASCII、双栈探测、子进程回收、pwd -W、状态文件）见 references/decisions.md。

不想拆开就用 all，它会自动建 01~05 子目录 + manifest.json。

何时使用

• 用户给一个视频链接，想把它改造成自己的口播视频
• 用户给一段文案，想做动态排版视频
• 用户已有排版页面，想转成 mp4 或剪映工程
• 用户想一次性走完整流程

不适用：纯通用视频下载（用 all-platform-video-extract）、需要实拍或复杂视觉特效的片子。

环境依赖

cd remotion && npm install --registry=https://registry.npmmirror.com

> 产物放哪：样片、参考工程、成片这类大文件一律放 D:/ai renwu/video-to-layout-artifacts/，
> 不要写进技能目录（曾把技能撑到 1.6GB / 近 2 万个文件）。技能目录只有
> SKILL.md + assets/（模板与字体）+ scripts/ + references/，已纳入 git。
>
> 根目录可用环境变量覆盖：VTL_ARTIFACTS=<目录>（默认 D:/ai renwu/video-to-layout-artifacts，
> 该盘不存在时回落 ~/video-to-layout-artifacts）。剪映草稿是例外——必须在剪映草稿根目录里才能被识别，
> 归档副本在 D:/ai renwu/video-to-layout-artifacts/剪映草稿/。

五步概要

① 提取视频、文案

bash scripts/pipeline.sh extract "<链接>"          # 下载
bash scripts/pipeline.sh extract "<链接>" --parse  # 只要直链
python scripts/transcribe.py audio.mp3 --out 文案.txt --srt 字幕.srt --model small --lang zh

提取能力内联在 scripts/extract/（源自 all-platform-video-extract）。
转写结果必须人工校对——small 模型同音字错得很典型（短距→短剧、日军→日均、摩根大同→摩根大通）。
更省事的办法是剪映「智能字幕」导出 srt。视频号可解析但会限流，详见 references/troubleshooting.md。

② 文案转时间轴

python scripts/gen-layout.py 文案.txt --out layout.json            # 横屏 16:9
python scripts/gen-layout.py 文案.txt --out layout.json --aspect 9:16

规则匹配 + 结构化，切 8 种版式（hook / question / data / compare / steps / quote / points / outro）。
判定不对就用版式指令强制指定（见下「文案格式」）。layout.json 是唯一数据源。

②b 自动配音（★ 语音优先）

核心理念：时间轴的所有权归语音，不归画面。

旧做法是「按字数估时长 → 出画面 → 再把配音塞进去」，于是永远在给一个假时间轴打补丁：
补静音、局部调速、重排时间轴。而且估得根本不准——同一份文案实测每段落在
3.1~6.8 字/秒之间（Token 这类英文词更离谱），固定用 4.5 估必然错。

新做法反过来：先配音，量出每段真实时长，让画面照这个时长长出来。

文案.txt ──▶ tts.py ──▶ voice/sc01.mp3 + manifest.json（真实时长）
                              │
                              ▼
                    gen-layout.py --voice
                              │
                              ▼
              layout.json（t0/t1 = 配音时长 + 呼吸）──▶ 画面

bash scripts/pipeline.sh voice ./项目目录                    # 默认云健 + 1.5 倍速
bash scripts/pipeline.sh voice ./项目目录 --voice 晓晓        # 换音色
bash scripts/pipeline.sh voice ./项目目录 --rate +0%         # 回原速（1.0x）
bash scripts/pipeline.sh voice ./项目目录 --rate +70%        # 更快
bash scripts/pipeline.sh voice ./项目目录 --no-srt           # 不出字幕
bash scripts/pipeline.sh voice ./项目目录 --probe "试听这句话"   # 四音色对比，不出片
bash scripts/pipeline.sh voice ./项目目录 --reset             # 清缓存全部重配
# 一条龙时加 --voice：bash scripts/pipeline.sh all 文案.txt ./项目 --voice 云健

语速怎么定（不是拍脑袋）

全片一个语速是最粗的做法：讲原理的句子需要理解时间，念清单不需要。所以按信息负荷分配：

基准 +45%，结果夹在 +25~60%。实测同一份文案：痛点幕从 7.4 降到 5.1 字/秒，
讲原理幕从 7.6 降到 6.7，而钩子和金句保持 7 以上。

配音之后必须走 layout，别直接 gen-remotion

配音会在工作目录留下 voice/manifest.json。之后只要跑
pipeline.sh layout，它会自动沿用配音时间轴（不需要你再传 --voice）：

bash scripts/pipeline.sh voice  ./项目目录                 # ① 先配音（时间轴按真实时长排）
bash scripts/pipeline.sh layout ./文案.txt --out ./项目目录   # ② 出工程（沿用配音 + 补 design.json）
bash scripts/pipeline.sh density ./项目目录                # ③ 体检
bash scripts/pipeline.sh render ./项目目录 --go            # ④ 确认后出片

直接跑 gen-remotion.py 会跳过 design.json 生成，等于没做视觉设计；
而且一旦有人重跑 layout 时忘了 --voice，时间轴会被字数估算覆盖
（2026-10-29 实测：音轨 22s、画面 44s，音画直接错位）。
这两种情况现在都有防线：layout 自动沿用，render 两种目录结构都认，
gen-layout --voice 会在段数/文字不一致时拒绝生成而不是悄悄错位。

文案的两种写法都支持

# 写法 A：带时间码（一行一段，适合照着原视频节奏切）
[00:00 - 00:06] Token 流向了哪里？中国 55% 的算力，变成了短剧
#hook
#kicker: 开场 · 2026

# 写法 B：不带时间码（靠指令行收尾，适合先写文案再配音）
Token 流向了哪里？中国 55% 的算力，变成了短剧
#hook
#kicker: 开场 · 2026

两种写法都要切出同样的幕数与版式。#hook / #question 这类指令行
属于上面那一段，出现即表示那段写完了——这一点没处理时，
整篇会被并成 1 段再按句号硬切，结果是「第 3 幕念第 4 幕的话」（2026-10-29 修复）。

> 写法 A 不能和 --voice 同时用（手写时间码与配音时长必然冲突），
> 脚本会直接报错让你二选一。

> 「以前 / 现在」只在句首或标点后才算逻辑词。「你现在看的这条视频」里的
> 「现在」是时间词，按纯字符串匹配会白降 6%——踩过。

停顿怎么定（按语义距离，不是按幕类型）

另外有 1.2 秒最短幕时长兜底：短句幕（如「我换了个顺序」6 字）配音只有 0.66s，
不兜底会一闪而过；但补到 1.5s 反而显出 0.84s 的空白，1.2s 刚好。

自动体检（每次出片都会打）

  语速与停顿诊断：
  幕   版式          字     语速    字/秒     停顿  依据
  S3  question   26   +33%    5.1   0.28  长句·罗列
  S6  points     29   +31%    6.7   0.12  长句·逻辑词
  S7  points     22   +39%    6.3   0.28  逻辑词
  ...
  平均语速  381 字/分钟（知识类口播合理区间 350~420）  ✓
  停顿占比  13.1%（合理区间 12~20）  ✓
  单幕语速  全部在合理区间内（长句 ≤8.5、短句 ≤10.5 字/秒）  ✓

三个判定区间的来源：知识类短视频实测集中在 350~420 字/分钟；停顿占比
低于 12% 会赶、高于 20% 会拖；单幕阈值要按字数分档——短句的起音/收音
占比大，字/秒天然偏高，用统一 8.5 去卡只会把所有短句拖慢。

超限会自动校正（不是只报警）

分段变速是逐段的局部决策，逐段看都合理，合起来可能整体偏快。
实测一份 6 幕的短文案，每幕都命中「短句 +5%」，叠加后全片跑到 446 字/分钟。

所以 tts.py 合成完会做一次闭环校正：

  语速校正  实测 446 字/分钟超出 415，基准降到 +35% 重合成
  语速校正  基准 +35%，实测 415 字/分钟  ✓

做法：先按 tune_base() 预估一个初值（cpm ≈ 4.4 × (1+rate/100) × 60），
合成后用实测时长复核；超 415 就按 CPM_MAX / cpm 的比例降基准重合成，
最多两轮。

> 为什么不能只用预估：短句的起止音占比大，字/秒是非线性的。同一份文案
> 预估 372、实测 446，差了 20%。预估只配做初值，判定必须用实测。

代价是超限时多一轮合成（约 3 秒），换来的是「不用人回头调」。

三条硬规则：

1. 文案里有手写时间码时 --voice 直接报错，不许默默二选一。
   配音时长和 [00:06 - 00:13] 几乎不可能一致，随便选一个都是错的。
   （从视频转写来的文案天然带时间码——那种场景本来就有原声，不该再配音。）
2. 段数 / 每段文字必须与 manifest 一致，否则报错。文案改了就要重配，
   不然会出现「第 3 幕念第 4 幕的话」，而且渲染完才发现。
3. 单段超过 10s 会告警。画面要撑 10 秒不动，check-density 会报「长镜头无变化」。
   处理办法是手动断句（加空行），不要靠自动拆——自动拆会打乱版式指令的归属。

字幕走配音的时间戳，不走 Whisper：TTS 合成时引擎已经返回每句的起止时间，
那是生成时就已知的精确值；再跑一遍语音识别等于把确定的东西猜一遍，还可能听错字。
make_srt.py 会：

• 把段内相对时间 + 该幕 t0 换成绝对时间
• 超过 20 字的长句按标点二次切，时间按字数比例分配
• 合并 <12 字的碎片（引擎常把一句话按停顿拆成两段 boundary，不合并会九字一屏地闪）
• 中文之间的半角逗号转全角（引擎把停顿写成 ,，中文字幕里很难看）

已知限制：
- 中文只返回句子级时间戳（SentenceBoundary），没有逐词。够用（段级 + 句级字幕），但做不了逐字卡拉 OK。
- 数字/英文读法由微软引擎决定，API 不返回实际发音。遇到读错就改文案里的写法
（如「55%」写成「百分之五十五」），不要指望脚本能猜。
- edge-tts 是微软非官方接口，无 SLA。挂了就退回剪映「文本朗读」+ 无字底片。

③ Remotion 动态排版

python scripts/gen-remotion.py layout.json --out ./remotion --install   # 默认 custom：风格由文案推导（16:9 横屏）
python scripts/gen-remotion.py layout.json --out ./remotion --style token   # 定版浅色 20 版式（要稳定产出时）
python scripts/gen-remotion.py layout.json --out ./remotion --style mint    # Mint Dark：深色电影感 + 小公仔 + 底部字幕
python scripts/gen-remotion.py layout.json --out ./remotion --style mint --no-caption  # 不烧录底部字幕（外部队配音/剪映字幕时必须加）
python scripts/gen-remotion.py layout.json --out ./remotion --style basic   # 旧 8 版式（非常规画幅兜底）

默认是 custom，且默认画幅是 16:9 横屏（gen-layout.py --aspect 缺省即 16:9）。
这条默认是用户 2026-10-29 明确定的：

custom 的完整工作流和六条《执行准则》见上文 custom（按文案定制）怎么用。

什么时候用 --style mint：想要抖音/视频号那种「深色电影感 + 角色 IP + 逐句字幕」的口播片
（学习自参考片《WorkBuddy 6 个 Skills》）。它自带右下角小公仔（呼吸/眨眼/按场景换表情）、
章节条、玻璃卡片、底部字幕；版式为 hook / question / metric / cards / vs / rows / quote / outro。

--style token 产出定版 Token 视觉：内置模板 assets/remotion-token/，20 种版式，版式由
scripts/build_token_data.py 按文案特征自动挑（改 src/data.ts 的 kind 可手调）。
默认的 custom 走 assets/remotion-custom/，版式由 src/design.json 的 scenes[].layout 定。
合成 id 统一 Main；抖音封面是 Cover（1080×1440），两套模板都有。
Remotion 侧文档分两层：本站模板结构与踩坑在 references/remotion-project.md（自带完整），
官方规范（v4.0.538）入口是 references/remotion.md——
官方副本 remotion-official/ 有 152 个文件、会撑爆上传的体积/文件数限制，分发包里不含，
首次使用时跑 bash scripts/pipeline.sh sync-remotion 拉取（需先装 remotion-best-practices 技能）。

⏸ 检查点：生成后不要自动渲染，先给用户看联系表/编辑器，等确认。

③b 逐句字幕（可选，默认关闭）

画面文案是概括（标题 + 卡片 + 列表），字幕是逐字。两者来源与节奏都不同，所以分开管理：

bash scripts/pipeline.sh captions ./项目目录                    # 自动找 02-script/字幕.srt
bash scripts/pipeline.sh captions ./项目目录 --srt 我的字幕.srt   # 指定文件
bash scripts/pipeline.sh captions ./项目目录 --on               # 打开显示（theme.json）
bash scripts/pipeline.sh captions ./项目目录 --off              # 清空并关闭

• 产物 src/captions.ts，格式与 @remotion/captions 的 Caption 一致（毫秒），写成内联字面量——
  这样 Remotion 的 Caption 编辑器才能回写；走 fetch(JSON) 就变成「能看不能改」。
• 单条超长会按标点二次切分，时间按字数比例分配，不重叠。横屏上限 18 字、竖屏 12 字（按画幅自动）。
• 视觉是浅蓝青底的白色胶囊 + 数字/引号关键词青色高亮，与 Token 主题一致。
• 默认关闭：字幕烧进像素后，外部再配一遍音就会重复且挡画面。要开就 --on。
• 组件文件叫 Subtitles.tsx 而不是 Captions.tsx：Windows 文件名大小写不敏感，
  ./Captions 会解析到 captions.ts 自己，打包报 No matching export（已踩过）。

④ 渲染成片

bash scripts/pipeline.sh render <工作目录> --go   # 自动找空闲端口 + 探测浏览器（--go = 已确认）

Remotion 直接出片（几十帧/秒）；scripts/render.js 是 HTML 逐帧截图兜底（默认 JPEG，约 14 帧/秒）。
优先 Remotion 路径，别默认走 render.js。

⑤ 剪映草稿

# 成片已含文字 → 只建视频轨（用于加配音/BGM/字幕/剪辑）
python scripts/make-draft.py --out "D:/JianyingPro Drafts/我的项目" \
  --from-layout layout.json --bg "<成片.mp4>" --no-text

# 想要可改字的文字轨 → 背景必须是无文字底片（Remotion 侧 showText=false 另渲）
python scripts/make-draft.py --out "D:/JianyingPro Drafts/我的项目2" \
  --from-layout layout.json --bg "<无文字底片.mp4>"

必须先判断背景里有没有烧录文字：成片当背景就不要建文字轨，否则文字压文字。
必须直接生成到剪映草稿根目录（draft_fold_path 是绝对路径，事后拷贝会导致路径错）。
细节见 references/jianying.md。

⑥ 抖音封面（发出去之前最后一步）

bash scripts/pipeline.sh cover <工作目录>            # 抽帧候选 + 大字报版式，一次出齐
bash scripts/pipeline.sh cover <工作目录> --title "自定义标题" --hot "55%"
bash scripts/pipeline.sh cover <工作目录> --no-frames   # 只出版式封面
bash scripts/pipeline.sh cover <工作目录> --reset       # 重新猜文案（清掉手改）

产物在 <工程>/out/cover/，打开 cover-sheet.html 挑图，右键另存 → 上传到抖音创作服务平台的「选择封面」。

为什么不能直接从成片截一帧当封面：抖音信息流按 3:4 居中裁切，横屏成片会被切掉左右；
竖屏成片虽然能裁，但视频里的标题字号是按「全屏观看」定的，缩到 200px 宽的缩略图就看不清了。
封面需要的是「大字报」，与视频版式是两种设计——所以单独做了 Cover Composition（1080×1440）。

横屏素材不做 3:4 硬裁（试了三版后的结论）：16:9 = 1.78、3:4 = 0.75，差 2.4 倍，
任何「填满 3:4」的裁法都必然丢掉 58% 的横向内容。实测三种都切字：
居中裁 → 「这 500 万亿 Token 到底去哪了」变「到底去哪了」；模糊补白 → 画面只占中间 45%；
放大填满 → 「这 500 万亿」变「0 万亿」。所以横屏候选帧保持原比例，要 3:4 就用大字报版式。

文案优先级：命令行参数 > src/cover.json 里已有的值 > 自动猜。
自动猜按「适不适合做封面」打分（短句 + 对比词「不是…而是」+ 数字 + metric/vs 版式），
不取第一幕——第一幕通常是钩子，做封面太抽象。手改的文案不会被脚本覆盖，想重猜加 --reset。

一条龙

bash scripts/pipeline.sh all 文案.txt ./我的项目        # 从文案开始，跑到排版就停
bash scripts/pipeline.sh all "<链接>" ./我的项目        # 从链接开始：下载→转写→排版→停
bash scripts/pipeline.sh render ./我的项目 --go          # 弹窗确认后再出片 + 草稿
bash scripts/pipeline.sh all 文案.txt ./我的项目 --auto-render   # 一次跑完（慎用）

<工作目录>/
  01-source/  视频、封面、音频、info.json          ← ①
  02-script/  文案.txt、字幕.srt                   ← ②
  03-layout/  layout.json、layout-storyboard.html、remotion/  ← ③
  04-video/   成片.mp4                             ← ④
  05-draft/   剪映草稿                             ← ⑤
  manifest.json  产物清单（路径/大小/场景数/版式分布）

文案格式

纯文本，三种可选标注。两种写法别混用，混了不会报错，只会让版式静默错位。

A. 有时间码（从视频转写来的文案就是这样）——指令写在时间码之后的任意位置：

[00:23 - 00:49] 上线首月 PC 端访问量 885 万，7 月月活 1115 万
#kicker: 第二层 · 本质
#title: 它不是聊天机器人，是会干活的 AI
#note: 这一关讲清楚「干活」和「回答」的区别

B. 没有时间码（自己写的稿子、配音模式）——指令必须写在段落开头：

#hook
#kicker: 开场 · 2026
你现在看的这条视频，没有一个字是我剪的。

#quote
稿子写完，剩下的它自己做。

> ⚠ 指令归属规则（踩过）：段落靠空行切分，指令属于「它出现时正在编辑的那一段」。
> - 有时间码时，时间码会立刻新开一段，所以指令写在时间码后面任何位置都归这一段。
> - 没有时间码时，文字 + 空行 + #hook 会先在哪？——空行已经把上一段归档了，
> 所以 #hook 会挂到下一段，上一段变成无版式（自动判定）。
> 正确写法是「#hook 在前，文字紧跟其后」。
> - 写错的后果很隐蔽：不报错、不警告，只是版式分配和你预期的不一样。

「执行全部」这类指令怎么理解（防歧义，2026-10-28 用户提出）

审阅台右侧有「自定义待执行」，那是写给 Agent 的队列，不会自动跑。
用户写完常常只说一句「执行全部」，这句话本身有歧义——可以指：
跑待办、重跑整个流程、或者渲染出片。

规则：只要上一轮对话提到过审阅台 / 自定义 / 待办，这些说法一律先查待办队列。

标准动作：

bash scripts/pipeline.sh notes "<工作目录 | Remotion 工程>"          # 1. 读队列
# 2. 逐条执行（改 Video.tsx / data.ts / 工程配置）
bash scripts/pipeline.sh notes "<项目>" --clear                      # 3. 执行完清空
bash scripts/pipeline.sh review "<项目>"                             # 4. 重建审阅台，让用户看

• 有待办就执行待办，不有待办才问「你是想跑完整流程还是渲染」。
• 渲染永远单独弹窗确认（第 7 条），不能把「执行全部」当成渲染授权。
• pipeline.sh review 结束时会自动报「还有 N 条待执行」，别忽略这一行。

强制工作流：先给「所见即成片」的预览，确认后才出片

> ⚠ 渲染必须弹窗二次确认（第 7 条）：即使用户在对话里已经说了「出成片 / 渲染」，
> 也必须先弹窗问一次「是否现在开始渲染」。口头授权不算授权。

用户 2026-10-21 明确要求，每次都必须按这个顺序；2026-10-26 追加：走查默认用审阅台。

0. 先起分镜审阅台（pipeline.sh review，把 REVIEW_URL 给出来）——这是走查首选：
   每幕用 <Player> 实况播放（不是静帧），右侧表单直接改文案，改动写回
   src/review.overrides.json；src/data.ts 会自动合并它，所以「审完直接 render」就是审过的那版，
   不存在「确认的和渲出来的不是一回事」。零渲染成本，改二十轮也不花时间。
   这条链路必须自检：pipeline.sh review 的 ④ 步会跑 node review/check-wiring.mjs，
   确认 src/data.ts 真的 import 了 review.overrides.json；不通过会直接报错退出。
   2026-10-26 踩过：生成器读 review.overrides.json、审阅台却写 overrides.json，
   保存一切正常、overrides 也确实写盘，但渲染读的是原数据 —— 审了白审，比没接入更糟。
   用户想留结构性修改意见（「这页改成三张卡」）时用每幕的「自定义改动」，
   Agent 用 node review/list-notes.mjs 读走、改完 --clear 收工。
   审完可直接在页面右下角点「渲染成片」（本地补丁提供 /api/render，输出到工程 out/）。
   历史记录会自动轮转：review/history.jsonl 每条含整幕快照，官方只追加不裁剪，
   长期用会涨到几十 MB 且前段永远读不到（前端只取最近 40 条、回滚只查最近 400 条）。
   本地补丁改成超 2000 条保留尾部 + 原子替换（先写 .tmp 再 rename，防止写到一半崩了毁掉历史）。
1. 分镜联系表（pipeline.sh storyboard）降为存档/纵览——每幕一张静帧 + 时间码拼成
   layout-storyboard.html，适合「一眼看全片节奏」、贴给第三方、或留作每次的版本快照；
   它不能改文案，所以不再承担走查职责。
2. 整片预览就在审阅台最上面——常驻的播放器，播整片，和成片同一套组件。
   判断「整片节奏」用它。它就是个普通播放器：默认不自动播放，
   声音和音量全用播放器自带的控制条（别预置静音、别藏 showVolumeControls）。
   下面那套静音限制只针对分段卡片，不要套到整片上（用户 2026-10-28 明确）。

每张分段卡片默认静音，卡上有 🔊 开关（SceneOnly 的 <Audio startFrom/endAt>
把音轨裁到该幕区间）。需要听某一句时单独打开——十六张卡同时出声会糊成一片，
而且分不清是谁的。点任一张卡的播放，会自动暂停其他卡。

声音三条硬规矩（用户 2026-10-28 明确要求，改审阅台时必须守住）：
1. 分段卡默认静音：打开页面、滚动、点播放都不出声；
想听只能手动点卡片的 🔇 → 🔊。整片预览不受这条约束。
2. 卡片之间只允许一处出声：开一张卡的声音，其他卡全部静音。
3. 卡片离开视野自动停：滚出屏幕就 pause + 静音，按钮复位成 ▶ / 🔇。
看不见的卡片不许还在响。（整片预览不参与，保持普通播放器行为。）

实现上有三个坑（都踩过，别改回去）：
- 静音要走 PlayerRef.mute()/unmute()，不要直接改 <audio>.muted——
Player 每帧按自己的状态重设 muted/volume，手改会被覆盖，表现为「点了静音还在响」。
- 「离开视野」用滚动时按 getBoundingClientRect 扫描 + 700ms 心跳，
不用 IntersectionObserver：卡片会被整张重建（改文案/撤销），
观察器会漏掉重建后的那张，漏掉就是「看不见还在响」。
- redrawScene() 换卡之前必须先 pause + 静音旧播放器：React root 挂在
脱离文档的节点上时，画面没了声音还在跑，页面上根本没有按钮能关它。

时间轴草图（layout.html）已整步移除（2026-10-28 用户要求）：
它是另一套简化实现，颜色/版式都和成片不一样，看了反而误导。
要看画面只有审阅台（带整片预览 + 逐幕实况），不再生成任何 HTML 草图。
3. 自适应缩放必须用「占位盒」写法：transform: scale() 不改变布局占位，必须回填
WRAP.width/height，否则父容器按 1920×1080 撑开后会把画面裁掉（用户只看到中间一块）。
完整公式与 ResizeObserver 兜底见 references/decisions.md。
4. 交付前跑 pipeline.sh selftest（改过技能时），成片自身的校验交给 render。
5. 不要自动启动 Remotion 编辑器（2026-10-28 用户要求）：交付时不要跑
pipeline.sh studio / preview，也不要在收尾提示里引导用户去开。
用户明确说要逐帧调参时，才把命令给他。
6. 等用户确认，未经确认不得渲染成片，也不要「先渲一版给你看看」。
7. 渲染前必须弹窗二次确认（硬规则，2026-10-28 用户明确要求）：

不管用户在这条消息里写了什么——「出成片」「渲染吧」「直接渲」「不用再问了」——
一律先弹窗问「是否现在开始渲染」，拿到「现在渲染」才动手。
对话里的口头授权不算授权，只有弹窗里点的那一下算。

适用范围（只要产出 mp4 就算）：
- bash scripts/pipeline.sh render <项目>
- bash scripts/pipeline.sh all ... --auto-render
- 直接调 remotion render（包括只渲几十帧的冒烟验证）
- 审阅台右下角的「渲染成片」按钮由用户自己点，不在此列（那是用户亲手触发）

不受限：单帧 still（出 png）、storyboard、cover、review、studio。

弹窗至少给两个选项：「现在开始渲染」 和 「先看预览 / 再等等」。
用户选后者就停下，不要换个说法再问一遍。

> 为什么连明确授权也要再问：2026-10-27 用户说「展现能力」，我理解成「交付成品」，
> 直接渲了 1064 帧才发现跳过了整个走查流程。渲染是不可逆的时间成本
> （改一版要重渲几分钟），而审阅台改一版是零成本。
> 把最后一道闸交给用户在弹窗上点，比让我判断「他是不是真的想现在渲」可靠。

8. 确认后才出片，并做抽帧 / 音轨 / ffprobe 校验。

> 历史上真踩过这三条（案例与复盘见 references/decisions.md）：直接给 mp4、缩放裁切、预览与成片不是一套。

交付前必查

能自动化的已经进了 pipeline.sh render（ffprobe 核对时长/帧数/文件大小，失败非零退出）；剩下仍需人工确认：

1. 场景数 = 文案段数（曾因参数错位静默丢幕）。
2. 目标字体在 document.fonts 里为 loaded（路径错会静默回退系统字体）。
3. 抽帧看每幕 edge variance > 400（非空白）；空幕多半是「版式与数据不匹配」，见下节。
4. 给用户看画面只用审阅台 / 联系表；不要另造简化版 HTML（和成片不是一套画面）。

> 实现载体：定版风格 = assets/remotion-token/（Video.tsx 20 版式），
> gen-remotion.py --style token 铺出来并生成 src/data.ts。
> 原始样片工程在 D:/ai renwu/video-to-layout-artifacts/token-economy-remotion/，只作回归基线。
> 音频：音轨丢进 public/audio/，--audio audio/mix.wav 自动挂上。

可视化拖拽改版式

bash pipeline.sh edit <工作目录>        # 浏览器里直接拖画面元素，保存即写入 overrides.json

Remotion Studio 不能拖元素（代码优先），官方能拖的是付费的 Editor Starter。
本技能自带一个轻量编辑器：可拖标题/数字/卡片/左右栏/列表/金句，字幕与小公仔是全局的；
能改 dx/dy/缩放，不能加元素或改文字。改完 npx remotion render 即生效。
细节见 references/remotion-project.md。

画面「空不空 / 动不动」自检

bash scripts/pipeline.sh density <工作目录>              # 全片逐幕采样，缺省判据：密度≥3.0、长镜头变化≥0.6
bash scripts/pipeline.sh density <工作目录> --samples 5  # 采样更多时间点
bash scripts/pipeline.sh density <工作目录> --concurrency 6   # 渲染+分析并发（默认 4）

输出每一幕的 密度（边缘均值，越低越空）和 变化（同幕多点静帧的 PSNR 差，越低越"死画面"）。
低于阈值直接退出码 1，可接进 CI。

> 为什么需要它：判「页面太空」不能靠肉眼扫缩略图。实测有两个典型病灶——
> ① 单幕信息太少（15–29s 那幕原本只有一个问号和几个字，密度 1.51）；
> ② 长镜头只在前 3 秒有动画（17–50 秒的幕在入场动画结束后完全静止，变化值接近 0）。
> 定版模板已为此加了「分批揭示 + 常驻微动层」，见 references/remotion-project.md。

静帧渲染的并发（storyboard / density 共用）

两个脚本都走 scripts/lib/still-harness.js：一次 bundle、一次 selectComposition，
之后所有静帧并发渲染（默认 4 路）。

4 路是实测甜点：再高就被浏览器启动开销吃掉。--concurrency 可调。

> 坑：并发时不能给每个 renderStill 传同一个 port。每次渲染会自己起一个
> HTTP server，第二个就报 You specified port 3323 ... but it is not available。
> 串行时传 port 没问题，所以这个坑只在加并发后才暴露。harness 里已改成不传 port。

空幕定位（版式与数据不匹配）

某几秒画面「只有标题、没有内容」，多半是版式与数据不匹配（换版式时没带数据）。
生成阶段会打印 [错误] 版式与数据不匹配，pipeline.sh selftest 也有对应断言；
已经出片的，用下面这条定位到具体幕：

bash pipeline.sh density <工作目录> --samples 3    # 密度异常低的幕 = 空幕嫌疑

改技能后自测

bash scripts/pipeline.sh selftest           # 全量（末尾打印项数），约 60 秒
bash scripts/pipeline.sh selftest --quick   # 只跑解析/生成/自检，不渲帧（约 20 秒）

覆盖链路：文案解析（8 版式齐全、标题不截断「500 万亿」、steps/points ≥3 条、时间轴首尾相接）
→ 预览页 7 尺寸自检 → Token 工程 data.json 断言 → 分镜联系表 → 渲 2 帧 + ffprobe 校验帧数/时长。

2026-10-29 起还额外钉住这几条（都是踩过的真缺陷）：
无时间码文案必须切出同样的幕数与版式（指令行收尾）、
layout 必须沿用配音时间轴（不被字数估算覆盖）、
custom 必须有结构层与常驻动效（画面不能是「文字裸放在渐变底上」）、
steps 条目不带尾标点也不吃引导句。当前共 91 项。

自测目录 D:/ai renwu/video-to-layout-artifacts/selftest，复用 node_modules，第二次起很快。
改了 gen-layout.py / gen-remotion.py / 模板 / pipeline.sh 之后，先跑它再交付。

字体不随技能包分发

技能市场对上传包限制「≤200 个文件 / ≤10MB」且拦二进制字体文件，
所以 assets/fonts* 里的 .ttf / .woff2 不进包，只在本地开发时用。

三处 @font-face 的字族栈都带系统兜底（"Noto Sans SC", "Microsoft YaHei"），
缺字体时不会报错，只会静默回退系统黑体——文字能看，但那个「圆润」的气质会没。

想恢复原样，把字体放回对应位置即可（文件名必须一致）：

三款都是 SIL OFL 1.1，可从 Google Fonts 官方仓库取：
<https://github.com/google/fonts>（ofl/zcoolkuaile、ofl/notosanssc、ofl/jetbrainsmono）。

参考文件