@dsh-gis/dsh-video-studio-skill 0.0.0-stage → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +186 -3
- package/THIRD_PARTY_NOTICES.md +41 -0
- package/cordis.patch.yml +5 -0
- package/docs/demo-pil-sheet.png +0 -0
- package/icon.svg +19 -0
- package/index.js +96 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +66 -4
- package/skills/video-studio/SKILL.md +642 -0
- package/skills/video-studio/assets/film.json +97 -0
- package/skills/video-studio/assets/scenes.py +227 -0
- package/skills/video-studio/assets/score_demo.json +307 -0
- package/skills/video-studio/assets/web/engine.js +485 -0
- package/skills/video-studio/assets/web/film.js +223 -0
- package/skills/video-studio/assets/web/index.html +22 -0
- package/skills/video-studio/assets/web/qa_text.js +111 -0
- package/skills/video-studio/assets/web/style.css +22 -0
- package/skills/video-studio/references/audio.md +392 -0
- package/skills/video-studio/references/frame-qa.md +502 -0
- package/skills/video-studio/references/pipeline.md +153 -0
- package/skills/video-studio/references/pitfalls.md +83 -0
- package/skills/video-studio/references/quality-gates.md +225 -0
- package/skills/video-studio/references/scene-authoring.md +237 -0
- package/skills/video-studio/references/sfx-design.md +246 -0
- package/skills/video-studio/references/web-engine.md +175 -0
- package/skills/video-studio/requirements.txt +29 -0
- package/skills/video-studio/scripts/filmkit.py +1544 -0
- package/skills/video-studio/scripts/qa_frames.py +1886 -0
- package/skills/video-studio/scripts/render.py +1024 -0
- package/skills/video-studio/scripts/scorekit.py +1890 -0
- package/skills/video-studio/scripts/selfcheck.py +568 -0
- package/skills/video-studio/scripts/sfxkit.py +3310 -0
- package/skills/video-studio/scripts/webengine.py +1324 -0
|
@@ -0,0 +1,642 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: video-studio
|
|
3
|
+
description: 用代码从零生成中文视频(科普片/纪录片/宣传片/动画短片):写剧本→edge-tts 旁白→实测时长排时间轴→PIL 或 Canvas 逐帧渲染→ffmpeg 编码→numpy 采样级混音→自动质检。当用户要"做一个视频 / 生成宣传片 / 把报告变成视频 / 做动画 / 配音配字幕 / 出成片 / 修视频音画不同步 / 视频画质糊",或提到 ffmpeg、edge-tts、逐帧渲染、字幕、分镜、配乐、混音时使用。 | Code-generated video production (Chinese narration, deterministic frame rendering, ffmpeg, edge-tts, QA gates). Use when asked to make a video, turn a report into a video, animate a story, fix A/V sync or blurry text in a generated video.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 视频工作室(video-studio)
|
|
7
|
+
|
|
8
|
+
**一句话:视频 = 剧本 + 音频实测时长 + 确定性逐帧函数 + ffmpeg 编码 + 自动质检。**
|
|
9
|
+
画面与声音全部由代码生成,零素材、可复现、可断点续跑、可脚本化验收。
|
|
10
|
+
|
|
11
|
+
## 0. 铁律(违反任意一条,成片一定会出问题)
|
|
12
|
+
|
|
13
|
+
1. **音频先做,画面后做**。时间轴必须由 TTS 实测时长反推,**绝不按字数估算**。按字数排的时间轴会在第 20 句开始明显漂移。
|
|
14
|
+
2. **每帧是纯函数**:`draw(t, frame) -> Image`。禁 `random`/`time()`,要随机用 `filmkit.hash2/hash3/vnoise`。同一帧号必须永远画出同一张图。
|
|
15
|
+
3. **字幕与大字必须落在安全区**:正文 `y ∈ [58, 974]`,字幕带 `y ∈ [872, 1030]`,永不超过 1030。
|
|
16
|
+
4. **原始帧直通编码**:PIL 帧 → `rawvideo` 管道 → `libx264`。**不要**用 `cv2.VideoWriter` 做中间文件(慢 2 倍且二次有损)。
|
|
17
|
+
5. **混音用 numpy 采样级叠加**,不要用一条 ffmpeg 命令喂上百个输入(Windows 上会非确定性静音)。
|
|
18
|
+
6. **交付前必须跑质检脚本 + 亲眼看 3 张静帧**(用 `read_image`)。"能出图"不等于"没问题"。
|
|
19
|
+
7. **(v0.3)声音跟着画面走**:该响一下的地方在**场景代码里登记提示点**(`K.CueBus` / `scenes.py` 的 `cues()` 钩子),
|
|
20
|
+
不要事后手工对时间。画面改了(换停留窗口、调节奏),提示点自动跟着改。
|
|
21
|
+
8. **(v0.3)没看清就加停留,别整片放慢**:`film.json` 的 `hold`(全局)或 `lines[].hold`(单句)
|
|
22
|
+
在语音结束后加停留;配乐用 `bpm` 对齐小节。
|
|
23
|
+
|
|
24
|
+
## 1. 五步上手(最快路径)
|
|
25
|
+
|
|
26
|
+
> 下文的 `<SKILL_DIR>` 指**本次加载技能时 `skill` 工具回报的 `resourceBase.path`**。装成插件后它就是
|
|
27
|
+
> 本插件包内的 `skills/video-studio/`(profile 的 `node_modules/@dsh-gis/dsh-video-studio-skill` 是链接)。
|
|
28
|
+
> 找不到时按名字定位:`find ~ -path '*/skills/video-studio/scripts/filmkit.py'`。
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# 1) 建工作目录,拷模板
|
|
32
|
+
mkdir -p myfilm && cd myfilm
|
|
33
|
+
cp <SKILL_DIR>/assets/film.json . # 剧本模板(改文字即可)
|
|
34
|
+
cp <SKILL_DIR>/assets/scenes.py . # 场景模板(改画面即可)
|
|
35
|
+
cp <SKILL_DIR>/scripts/{filmkit.py,render.py,selfcheck.py} .
|
|
36
|
+
# 可选(v0.3):要程序化音效/配乐就一并拷;要走浏览器渲染再拷 webengine.py + assets/web/
|
|
37
|
+
cp <SKILL_DIR>/scripts/{sfxkit.py,scorekit.py,qa_frames.py} .
|
|
38
|
+
cp -r <SKILL_DIR>/assets/web ./web
|
|
39
|
+
|
|
40
|
+
# 2) 先跑一次自检:24 条回归护栏,20 秒内出结论(不联网;可选模块缺失会标 SKIP)
|
|
41
|
+
python selfcheck.py
|
|
42
|
+
|
|
43
|
+
# 3) 改 film.json 的 lines[].text / sub / big / items
|
|
44
|
+
# text = 朗读文本(自然口语);sub = 上屏字幕(短,一行优先)
|
|
45
|
+
|
|
46
|
+
# 4) 母版预览(P6):先只渲几张关键帧看构图/配色,别一上来渲全片
|
|
47
|
+
# 全新目录下的第一条命令也能跑:缺 tts.json / timeline.json 会自动补跑
|
|
48
|
+
# (tts 要联网合成一次旁白),并打印 [stills] 说明自己在补哪一步。
|
|
49
|
+
python render.py --script film.json --scenes scenes.py --work work --stage stills \
|
|
50
|
+
--stills "l01:3,l02:5,l03:2.5"
|
|
51
|
+
|
|
52
|
+
# 5) 一条命令出片(TTS→排版→混音→渲染→合成→质检)
|
|
53
|
+
python render.py --script film.json --scenes scenes.py --out out/film.mp4 --work work
|
|
54
|
+
|
|
55
|
+
# 6) 亲眼看质检抽出的帧
|
|
56
|
+
# work/qa/sheet.png 联系表(全片调性)
|
|
57
|
+
# work/qa/snap_*.png 全分辨率静帧
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
分阶段跑(**每个 stage 只做自己的事**,不会再顺手重渲全片):
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
python render.py ... --stage tts # 只合成旁白 + 实测时长(带输入校验的缓存)
|
|
64
|
+
python render.py ... --stage layout # 只排时间轴 -> timeline.json / sub.srt / sub.ass(含 hold 停留窗口)
|
|
65
|
+
python render.py ... --stage cues # 只出提示点 -> work/cues.json(声音跟着画面走)
|
|
66
|
+
python render.py ... --stage score # 只出配乐 -> work/music.wav(scorekit)
|
|
67
|
+
python render.py ... --stage sfx # 只出音效轨 -> work/sfx.wav(sfxkit,按 cues.json)
|
|
68
|
+
python render.py ... --stage audio # 只混音 -> audio.wav(旁白+配乐+音效,音效响时配乐让位)
|
|
69
|
+
python render.py ... --stage frames # 只渲染帧 -> silent.mp4(--engine pil|web,--jobs N 分块并行)
|
|
70
|
+
python render.py ... --stage mux # 只合成(视频流 copy,两遍 loudnorm)
|
|
71
|
+
python render.py ... --stage qa # 只质检(只读输入,只写 work/qa/)+ 帧级深检
|
|
72
|
+
python render.py ... --stage stills # 只渲母版静帧 + 联系表
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`--stage all` 的完整顺序:`tts → layout → cues → score → sfx → audio → frames → mux → qa`。
|
|
76
|
+
**任何一步出问题都会在该步停下**,不会带着坏输入继续往下跑。
|
|
77
|
+
|
|
78
|
+
长片渲染(分块并行 + 断点续跑):
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
python render.py ... --stage frames --jobs 4 # 4 进程按绝对帧号分块
|
|
82
|
+
python render.py ... --stage frames --jobs 4 --resume # 中断后只补缺块
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
> 分块落在 `work/segments/`,按 `seg_<起始帧>_<结束帧>.mp4` 命名;拼接前会**显式检测缺口**,
|
|
86
|
+
> 缺块直接报错,不允许"少一段也能出片"。默认 chunk 按 `总帧数 / jobs / 4` 向整秒取整(jobs=4、
|
|
87
|
+
> 900 帧时约 8 秒一段),可用 `film.json` 的 `chunk_frames` 覆盖。
|
|
88
|
+
>
|
|
89
|
+
> **改台词 / 改 scenes.py / 改编码参数之后,`--resume` 会拒绝复用旧分块**(`work/segments/_plan.json`
|
|
90
|
+
> 里存着计划指纹),并提示你 `rm -rf work/segments`——这是刻意的:旧分块配新时间轴会拼出
|
|
91
|
+
> "画面和旁白对不上"的片子,而且时长门禁查不出来。
|
|
92
|
+
|
|
93
|
+
## 2. 标准八阶段(P0–P7)
|
|
94
|
+
|
|
95
|
+
| 阶段 | 产出 | 关键动作 | 常见错误 |
|
|
96
|
+
|---|---|---|---|
|
|
97
|
+
| **P0 定基准** | `CONVENTIONS.md` | 分辨率/帧率/时长/BPM→帧换算一次算死,全项目引用同一份 | 各文件自己写 `150` 这种魔数 → 幕边界对不齐 |
|
|
98
|
+
| **P1 写剧本** | `film.json` | 每句拆 `text`(朗读)与 `sub`(字幕);每段一个 `kind` | 一个字段两头用 → 字幕太长或读起来生硬 |
|
|
99
|
+
| **P2 事实核查** | `FACTS.md` | 上屏的每个数字/年份有出处编号;建"不能上屏"黑名单 | 跳过这步 → 画面和旁白数字打架,评论区第一条就是你错了 |
|
|
100
|
+
| **P3 TTS** | `work/tts/*.mp3` + `tts.json` | edge-tts 逐句合成,`ffmpeg -f f32le` 实测时长,磁盘缓存 | 按字数估时长 → 字幕漂移 |
|
|
101
|
+
| **P4 排时间轴** | `work/timeline.json` + `sub.srt` | `dur = lead + 实测语音 + tail`,句读必须在本段内 | 段太短 → 旁白被下一段截断 |
|
|
102
|
+
| **P5 混音** | `work/audio.wav` | numpy 总线:旁白 + 配乐 + 音效按采样点叠加 | ffmpeg 多输入混流 → 非确定性静音 |
|
|
103
|
+
| **P6 母版** | 3 张静帧 | 先渲 3 帧看构图/配色/字重,定了再渲全片 | 直接渲全片 → 36000 帧后发现字体丑 |
|
|
104
|
+
| **P7 成片** | `out/film.mp4` | rawvideo→libx264 CRF18 + 两遍 loudnorm 到 -16 LUFS | 码率过低/响度 -25 LUFS → "像草稿" |
|
|
105
|
+
|
|
106
|
+
> 注:`filmkit` / `render.py` 的默认是 `crf=18`,但**自带模板 `assets/film.json` 写的是 17**。
|
|
107
|
+
> 自己写剧本时不写 `crf` 就是 18;追求更锐利的文字可以写 17(体积约 +30%)。
|
|
108
|
+
|
|
109
|
+
## 3. 渲染引擎怎么选
|
|
110
|
+
|
|
111
|
+
| 场景 | 选型 | 实测速度 | 适合 |
|
|
112
|
+
|---|---|---|---|
|
|
113
|
+
| 图文/数据/科普/UI 风 | **PIL(numpy+cv2 辅助)** — `filmkit` 默认 | 40–80 fps @1080p30(模板片 75) | 绝大多数中文科普片、报告转视频 |
|
|
114
|
+
| 需要流畅矢量/粒子/3D/纸纹质感 | **无头浏览器 Canvas2D/WebGL + CDP 截图 → image2pipe**(`webengine.py`) | 80–130 ms/帧(核显,PNG 截图) | 纪录片级长片、需要复杂视觉语言 |
|
|
115
|
+
|
|
116
|
+
> 上面两行是**本机空载**实测口径(换机、重负载画面都会变;详见 §12)。别把区间当保证。
|
|
117
|
+
| 纯数据动画 | **manim**(若已安装) | 视场景而定 | 数学/公式推导 |
|
|
118
|
+
|
|
119
|
+
**默认走 PIL**:依赖少(numpy+Pillow 就够)、启动快、确定性强、调试成本低。
|
|
120
|
+
需要"一镜到底的粒子形变 / 实时着色器质感"才上浏览器方案——**v0.3 起它是真的可用了**,不再是"文档里说有":
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
cp -r <SKILL_DIR>/assets/web ./web # 页面模板(原生 Canvas2D,零三方库)
|
|
124
|
+
pip install playwright && python -m playwright install chromium # 只在走 web 引擎时需要
|
|
125
|
+
python render.py ... --engine web --stage cues # 从页面导出提示点
|
|
126
|
+
python render.py ... --engine web --stage frames --jobs 3 --resume
|
|
127
|
+
python webengine.py textqa ./web/index.html # 文字重叠/出画/一闪而过/从没露面
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
两条路线的取舍(**先想清楚再选,换引擎要重做画面**):
|
|
131
|
+
|
|
132
|
+
| | PIL(`engine: pil`) | 浏览器(`engine: web`) |
|
|
133
|
+
|---|---|---|
|
|
134
|
+
| 依赖 | numpy + Pillow(+cv2 做锐度比) | + playwright + Chromium/Edge |
|
|
135
|
+
| 速度 | 40–80 帧/秒 | 8–12 帧/秒(逐帧截图+编码,慢一个数量级) |
|
|
136
|
+
| 画面语言 | 位图合成、渐变、几何、文字 | Canvas2D/WebGL:粒子、形变、着色器、矢量动画 |
|
|
137
|
+
| 确定性 | 天然(纯函数画图) | 靠"把时间轴精确 seek 到 f/FPS"保证(`window.renderFrame`) |
|
|
138
|
+
| 调试 | 改一帧跑一帧 | 浏览器里 `index.html?dev=1&t=秒` 直接看,出了 bug 好查 |
|
|
139
|
+
| 适合 | 图文/数据/科普/宣传片 | 纪录片级长片、需要一镜到底的视觉语言 |
|
|
140
|
+
|
|
141
|
+
**浏览器引擎的三条硬约束**(`webengine.py` 已实现,自己写页面时也要守):
|
|
142
|
+
1. 所有补间放在一条**暂停的**主时间轴上,渲染第 f 帧 = 把它 seek 到 `f / FPS` 秒;**不许依赖播放**。
|
|
143
|
+
2. 循环/粒子/波浪这类程序化内容用"按时间直算"的更新器(`update(fn)`),不许用 `setInterval` 累加。
|
|
144
|
+
3. 页面必须暴露 `window.ready / DURATION / renderFrame(f) / getCues()`;**不连 CDN、不请求网络**。
|
|
145
|
+
|
|
146
|
+
要**跨浏览器会话**的字节级可复现(崩溃重开、多次渲染做 diff、质检要比对两张图)时开确定性模式:
|
|
147
|
+
`--deterministic` 或环境变量 `WEBENGINE_DETERMINISTIC=1`(关 GPU 光栅,实测 8/8 会话一致,
|
|
148
|
+
代价约 +22%/帧)。默认不开:同一会话内本来就一致,跨会话只有 ≤4 像素、±1 级的抗锯齿差异。
|
|
149
|
+
|
|
150
|
+
## 4. 画质清单(这几项决定"像不像专业片")
|
|
151
|
+
|
|
152
|
+
- **亮度与层次**:暗底 (`#0a1420`) + 顶部亮 accent;不要纯黑纯白,用户屏幕会吃掉渐变。
|
|
153
|
+
- **字重与字号**:大字 84–96px、副标题 34–38px、字幕 46px;中文用 `msyhbd.ttc`(微软雅黑粗体)。
|
|
154
|
+
- **字幕**:≤ 2 行、单行约 24 个中文字、带半透明背板、`y ≥ 872`。
|
|
155
|
+
实际折行看的是**像素宽度**(`fit_sub_lines` 按 `max_w=1560 px` 自动折),24 字是"大致上限"并非硬校验
|
|
156
|
+
——`SUB_MAX_CHARS=24` 这个常量目前**没有被任何代码引用**,别指望它拦你。
|
|
157
|
+
- **节奏**:每 3–6 秒要有视觉变化(新卡片 / 位移 / 数字滚动);静止超过 6 秒观众就走。
|
|
158
|
+
- **镜头**:只做 3–15% 缓推,不要大幅拉远拉近。
|
|
159
|
+
- **调色**:整片一个主色 + 一个强调色,别超过 4 个色相。
|
|
160
|
+
- **音频**:母带 -16 LUFS / 真峰 ≤ -1 dBTP;旁白比间隙响 12 dB 以上;AAC 前留 1.4 dB 余量。
|
|
161
|
+
|
|
162
|
+
## 5. 声音:配乐 + 音效 + 提示点(v0.3.0)
|
|
163
|
+
|
|
164
|
+
> 这一节的思路来自一部真实成片(`ai-history-film`)的复盘:**声音不好不是"混得不够响",而是"声音不认识画面"**。
|
|
165
|
+
> 解决顺序永远是:先让声音知道画面上发生了什么(提示点),再谈音色,最后才是母带。
|
|
166
|
+
|
|
167
|
+
### 5.1 三层声音
|
|
168
|
+
|
|
169
|
+
| 层 | 谁做 | 落盘 | 说明 |
|
|
170
|
+
|---|---|---|---|
|
|
171
|
+
| 旁白 | `filmkit.tts`(edge-tts) | `work/tts/*.mp3` | **唯一的时长权威**:时间轴由它反推 |
|
|
172
|
+
| 配乐 | `scorekit.py`(程序化) | `work/music.wav` | 和弦表 + 律动层 + 分段能量;段落边界对齐小节线 |
|
|
173
|
+
| 音效 | `sfxkit.py`(物理建模) | `work/sfx.wav` | 按 `cues.json` 里登记的提示点逐条合成 |
|
|
174
|
+
|
|
175
|
+
三条总线在 `--stage audio` 里合成:**音效响起时配乐自动让位**(`duck_db`,默认 3 dB),
|
|
176
|
+
最后交给 ffmpeg 两遍 loudnorm 到 -16 LUFS / 真峰 ≤ -1 dBTP。**不要**自己在 numpy 里做最终响度标准化——
|
|
177
|
+
你有 `loudnorm`,它比手写归一化准得多,而且真峰才是门禁。
|
|
178
|
+
|
|
179
|
+
### 5.2 提示点:让声音跟着画面走
|
|
180
|
+
|
|
181
|
+
**这是 v0.3 最重要的一个概念。** 画面在该响一下的地方登记一个提示点,音频阶段按提示点合成音效:
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
# 方式一:写在 film.json 里(好改,适合少量关键音效)
|
|
185
|
+
"sfx": {"cues": [
|
|
186
|
+
{"at": "l03+0.05", "type": "impact", "size": 1.1},
|
|
187
|
+
{"at": "abs:12.5", "type": "whoosh", "dur": 0.9}
|
|
188
|
+
]}
|
|
189
|
+
|
|
190
|
+
# 方式二:写在 scenes.py 的 cues() 钩子里(推荐——画面改了声音自动跟着改)
|
|
191
|
+
def cues(tl, script):
|
|
192
|
+
out = []
|
|
193
|
+
for s in tl["scenes"]:
|
|
194
|
+
for i, _it in enumerate(s.get("items") or []):
|
|
195
|
+
out.append({"at": "%s+%.2f" % (s["id"], 0.48 + 0.32 * i), "type": "ui_blip"})
|
|
196
|
+
return out
|
|
197
|
+
|
|
198
|
+
# 方式三:web 引擎里由页面导出(提示点跟着动画代码走)
|
|
199
|
+
S.cue(t, 'impact', {size: 1.1}); // 页面里的时刻是"本幕局部秒"
|
|
200
|
+
python render.py ... --engine web --stage cues # 自动导出 work/cues.json
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
`at` 有三种写法:`"abs:12.5"`(绝对秒)、`12.5`(数字同义)、`"l03+0.35"` / `"l03-0.2"`(段 id ± 偏移)。
|
|
204
|
+
|
|
205
|
+
**为什么值得多写这一层**:改一句台词、加一个停留窗口、把 BPM 从 120 改成 100,
|
|
206
|
+
所有音效仍然贴着画面,不需要重新对时间。纯手工"在 12.5 秒放一声"的方案,改一次节奏就全废。
|
|
207
|
+
|
|
208
|
+
### 5.3 配乐(scorekit)
|
|
209
|
+
|
|
210
|
+
```json
|
|
211
|
+
"bpm": 120,
|
|
212
|
+
"music": {"enabled": true, "mode": "score", "key": "Dm", "gain_db": -1.5, "duck_db": 3.0,
|
|
213
|
+
"sections": [{"at": "l01", "name": "intro", "energy": 0.3},
|
|
214
|
+
{"at": "l03", "name": "drive", "energy": 0.8}]}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
- **一张和弦表贯穿全片**,段落之间只换"色彩与能量",不换调——这是"听起来像一首曲子"而不是"一堆配乐"的关键。
|
|
218
|
+
- `energy` 控制律动层数(pad / bass / kick / hat / arp)与亮度;安静段比律动段低 4–8 dB。
|
|
219
|
+
- 段落边界**对齐小节线**(按 `bpm` 算),画面重音才落在拍点上。
|
|
220
|
+
- 重击前用 `Score.suck()` 让配乐"吸一口气"(压低 3–8 dB、0.2 s 内恢复),落差立刻出来——
|
|
221
|
+
**不要**用静音断层,那会让声音像断了。
|
|
222
|
+
- `"mode": "bed"` 是 v0.2 的和弦床兜底;`"mode": "off"` 不要配乐。
|
|
223
|
+
|
|
224
|
+
### 5.4 音效(sfxkit)
|
|
225
|
+
|
|
226
|
+
`sfxkit` 是**物理建模**而不是"画波形":撞击 = 材质(衰减率)× 形状(模态比)× 敲击位置 × 接触时间;
|
|
227
|
+
风 = 噪声 + 时变滤波(参数由慢变控制曲线驱动);雨/火 = 泊松事件 + 幂律幅度 + 多核散布。
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
python sfxkit.py --list # 全部配方与参数
|
|
231
|
+
python sfxkit.py --render impact --seed 3 --set size=1.2 --out /tmp/i.wav
|
|
232
|
+
python -c "import sfxkit; print(sfxkit.render('whoosh', dur=1.2).shape)"
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
常用配方(**cue 的 `type` 就是这些名字**):
|
|
236
|
+
|
|
237
|
+
| 用途 | 配方 |
|
|
238
|
+
|---|---|
|
|
239
|
+
| 界面/提示 | `ui_blip` `ui_click` `relay_click` `roulette_tick` `answer_chime` |
|
|
240
|
+
| 文字 | `typing` `typing_at`(逐字对齐,`times` 是相对提示点的秒数组) `text_stream` |
|
|
241
|
+
| 转场 | `whoosh` `riser` `impact` `sub_drop` `reverse_swell` `glitch` `tape_rewind` |
|
|
242
|
+
| 环境 | `wind` `rain` `campfire` |
|
|
243
|
+
| 撞击 | `knock_wood` `metal_hit` `glass_clink` `go_stone` |
|
|
244
|
+
|
|
245
|
+
**音效设计的三条经验**(都是踩过坑才写下的):
|
|
246
|
+
|
|
247
|
+
1. **"叮叮咚咚"是头号污染源**:有音高的小提示音多了就变成八音盒。全片只留几个**关键**的叮
|
|
248
|
+
(开场任务完成、认出猫、片尾),其余换成不带音高的"咔嗒"。
|
|
249
|
+
2. **"嗖"要从物理出发**:多普勒 + 1/r 音量钟形 + 越远越闷 + 地面反射的梳状相位。
|
|
250
|
+
合成器式的扫频"咻"听起来像电子音,物理飞过模型才像"有东西飞过去"。
|
|
251
|
+
它的定位是**环境声**:基准电平要比同刻配乐低 10 dB 以上。
|
|
252
|
+
3. **音量一律在成片混音里量**,不要按配方内部音量推断——混音时每个音效会先按峰值归一,配方里的"响"是没用的。
|
|
253
|
+
|
|
254
|
+
### 5.5 混音链(照着做,别自创)
|
|
255
|
+
|
|
256
|
+
```
|
|
257
|
+
旁白(单声道, 居中) ─┐
|
|
258
|
+
配乐(立体声) ───────┼─> duck(音效包络, -3dB) ─> 求和 ─> 峰值保护(0.89) ─> ffmpeg loudnorm 两遍 ─> -16 LUFS / TP<=-1
|
|
259
|
+
音效(立体声) ───────┘
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
- **旁白优先**(听清台词是第一优先):`mix_film` 里旁白固定 `voice_gain=1.0` 居中,配乐默认
|
|
263
|
+
`music.gain_db=-1.5`、音效按 `CUE_BASE_DB` 逐条定电平。**"高 12 dB"是人耳经验值,代码不测量也不保证**——
|
|
264
|
+
交付前用 `filmkit.loudness` 或回听确认旁白压得住,别把它当门禁。
|
|
265
|
+
- 音效响时配乐自动让位 3 dB(`mix_film(duck_db=3.0)`;注意 `duck()` 函数自身默认是 4.0,
|
|
266
|
+
`mix_film` 传的是 3.0——看源码时别被两个默认值绕住)。让得太多会"音乐一抖一抖"。
|
|
267
|
+
- **本项目不做母带压缩**:链路是 求和 → duck → 峰值保护 0.89 → `ffmpeg loudnorm` 两遍。
|
|
268
|
+
代码里**没有压缩器**(想加请自行在 `mix_film` 之后接),所以也不存在"压太狠"的问题;
|
|
269
|
+
要让重击前后有能量差,靠的是配乐分段 energy 与 `suck()`,不是压缩。
|
|
270
|
+
- 成片音轨必须 48 kHz(`mux` 已显式 `-ar 48000`,selfcheck 第 12 条守着)。
|
|
271
|
+
|
|
272
|
+
## 6. 停留窗口:让观众看清楚,而不是整片放慢(v0.3.0)
|
|
273
|
+
|
|
274
|
+
> 来自同一部成片的复盘:"部分画面没看清就被切走了"。**解决办法不是把整片放慢,而是按内容加停留。**
|
|
275
|
+
|
|
276
|
+
```jsonc
|
|
277
|
+
"hold": 0.4, // 每句语音结束后统一多停 0.4 s
|
|
278
|
+
"lines": [{"id": "l03", "hold": 1.2, ...}] // 这一句单独停 1.2 s
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
- `hold` 只加在**语音结束后**,不影响旁白节奏;句子读得还是那么快,只是停在画面上的时间变长。
|
|
282
|
+
- 加长量取 `0.5 s`(120 BPM 下的**四分音符**=一拍)的整数倍,画面重音仍落在拍点上。
|
|
283
|
+
- 配乐 `sections` 用 `at: "l03"` 而不是绝对秒——停留窗口一改,段落边界自动跟着走。
|
|
284
|
+
- `bar` 字段可以让每段时长自动对齐小节(`"bar": 2.0` = 120 BPM 一小节),**代价是段落时长不再精确等于
|
|
285
|
+
语音+停留**,只在对齐更重要时才用。
|
|
286
|
+
|
|
287
|
+
**判断哪里需要停留**(按顺序看这三条):
|
|
288
|
+
1. 画面上出现了**要读的字**(数字滚完、卡片落定、字幕出齐)→ 至少留 `0.5 s + 字数/9`。
|
|
289
|
+
2. 出现了**要理解的结构**(网络层次、坐标轴、流程图)→ 留到能扫一眼看完。
|
|
290
|
+
3. 两个镜头之间**没有内容连续性**(黑一下、空一拍)→ 让下一幕提前开始,而不是加长黑场。
|
|
291
|
+
|
|
292
|
+
## 7. 质检门禁(error 必过 / warning 别当看不见)
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
python render.py ... --stage qa # 只读质检:分辨率/音轨/时长/响度/真峰/锐度比/黑帧/字幕条数 + 帧级深检
|
|
296
|
+
python selfcheck.py # 技能自身回归(24 条曾真的坏过的点)
|
|
297
|
+
python qa_frames.py out/film.mp4 --cues work/cues.json # 单独跑帧级深检,出 JSON + 图
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
**质检分三层**,一层比一层更接近"观众真的看到了什么":
|
|
301
|
+
|
|
302
|
+
| 层 | 查什么 | 工具 | 抓得住什么 |
|
|
303
|
+
|---|---|---|---|
|
|
304
|
+
| 容器层 | 分辨率/帧率/音轨/时长/码率 | `ffprobe`(`filmkit.probe`) | 参数写错、音轨丢了 |
|
|
305
|
+
| 信号层 | 响度/真峰/锐度比/黑帧/静音/字幕条数 | `filmkit.qa_report` | 像草稿、文字发虚、静默丢字幕 |
|
|
306
|
+
| **时间层(v0.3)** | **单帧闪烁 / 画面空窗 / 音画同步 / 响度曲线** | `qa_frames.py` | **"一帧白闪""两秒没东西看""重击没声音"** |
|
|
307
|
+
| 页面层(web 引擎) | 文字重叠/出画/一闪而过/从没露面 | `webengine.py textqa` | 页面里被别的元素压住的字 |
|
|
308
|
+
|
|
309
|
+
时间层需要单独说,因为它是**唯一靠"看完全片"才能发现**的一类问题:单看任何一帧都正常。
|
|
310
|
+
|
|
311
|
+
**先分清两档**(这张表以前混在一起,标题写"必过",实际 8 行里 5 行只是 warning):
|
|
312
|
+
|
|
313
|
+
- **error 档**:出现即 `qa` 返回非 0、CI 红。这些是"片子坏了"。
|
|
314
|
+
- **warning 档**:只提示,不阻断交付。这些是"能更好"或"门禁没跑"。
|
|
315
|
+
|
|
316
|
+
#### error 档(必须过)
|
|
317
|
+
|
|
318
|
+
| 判据 | 阈值 | 失败怎么办 |
|
|
319
|
+
|---|---|---|
|
|
320
|
+
| 分辨率/帧率 | 严格等于设定值 | 检查 FrameSink 参数;`strict=True` 会直接报错而不是静默缩放 |
|
|
321
|
+
| 音轨缺失 | 必须有音轨 | mux 参数漏了 `-i audio.wav` |
|
|
322
|
+
| 时长 | 与 `frames/FPS` 差 < 0.5 s | 断点续渲漏帧;分块模式检查缺口检测 |
|
|
323
|
+
| **真峰** | **> -1.0 dBTP**(-1.0 ~ -1.4 之间只 warn) | 混流前目标设 -1.5(AAC 会把真峰抬高 ~0.9 dB) |
|
|
324
|
+
| **编码锐度比** | **< 0.85**(0.85–0.92 只 warn;没装 cv2 则门禁跳过 + warn) | 降 CRF 或提 preset |
|
|
325
|
+
| **单帧闪烁(v0.3)** | **0 条** | 位移/推力没归零、粒子贴镜头过曝、转速突变;见 §8 故障速查 |
|
|
326
|
+
| **画面空窗(v0.3)** | 首尾以外 0 段(≥0.8 s 近黑) | 转场之间没有内容连续性:让下一幕提前开始 |
|
|
327
|
+
| **音画同步(v0.3)** | 判到超差(`dt > 60 ms`)即 error;**但默认可能根本没在查**(见下方两小节) | 要给 cue 写 `visual_at`,或设 `QA_REQUIRE_SYNC=1` 把"没查"也变成 error |
|
|
328
|
+
| **字幕条数** | **= 剧本句数** | 少一条就是静默丢字幕,查 `sub_window` 与 `write_srt` |
|
|
329
|
+
| **时长(时间层复核)** | 与预期差 > 0.5 s | `qa_frames` 会独立再查一次时长 |
|
|
330
|
+
|
|
331
|
+
#### warning 档(不阻断,但别当看不见)
|
|
332
|
+
|
|
333
|
+
| 判据 | 触发条件 | 怎么办 |
|
|
334
|
+
|---|---|---|
|
|
335
|
+
| 音轨采样率 | ≠ 48 kHz(**音轨缺失才是 error**) | mux 的 `-ar 48000` 被漏了 |
|
|
336
|
+
| 响度略偏 | -17.2 ~ -14.5 之外但仍在 -19 ~ -12 内 | 目标 -16 ± 1 是"舒适区";重跑 loudnorm |
|
|
337
|
+
| 真峰余量不足 | -1.4 ~ -1.0 dBTP | AAC 编码后可能更高,留 1.4 dB 余量 |
|
|
338
|
+
| 锐度比偏低 | 0.85 ~ 0.92 | 可接受但可更好 |
|
|
339
|
+
| 长黑帧 | 首尾以外出现 ≥0.4 s 黑帧 | 检查素材/淡入淡出 |
|
|
340
|
+
| 长静音 | 出现 ≥1.2 s 静音 | 确认是否有意留白 |
|
|
341
|
+
| 字幕安全区 | `qa_text_safe` 有警告(>2 行、越界、触底) | 缩短字幕或调 `SUB_BAND` |
|
|
342
|
+
| 缺字形 | `check_glyphs` 有警告 | 改文字或用矢量线条画(msyhbd 缺 ✓ × ↵ 等) |
|
|
343
|
+
| **画面长时间静止(v0.4)** | 连续 6 s 内最活跃 8×8 块的 0.5 s 漂移 ≤ 1.5 级灰度 | 加视觉变化(§4「每 3–6 秒要有变化」);确实要静止就接受它 |
|
|
344
|
+
| 门禁没执行 | 没装 cv2 / 测不到响度 / 找不到 sub.srt / 没 events 也没锚点 | **这一条最重要:它说明"看起来通过的项,其实没在查"** |
|
|
345
|
+
|
|
346
|
+
**三个 v0.2 才修对的坑(v0.1 的"门禁"其实是摆设):**
|
|
347
|
+
|
|
348
|
+
1. **锐度比的参考帧不能是成片自己抽的帧。** 那样 `sharp_ref` 与 `sharp_dec` 几乎相同,
|
|
349
|
+
ratio 恒 ≈ 1.0。必须用**场景函数重新渲染**同一时刻的原图(`st_qa` 已这么做)。
|
|
350
|
+
2. **真峰必须显式开 `ebur128=peak=true`。** 默认参数下解析不到 `Peak:`,
|
|
351
|
+
"真峰 ≤ -1 dBTP" 这条永远不触发。
|
|
352
|
+
3. **码率不是质量指标。** 暗底大字内容 0.5–1 Mbps 是正常的;把它当"下限"会天天误报。
|
|
353
|
+
|
|
354
|
+
**"不能有"和"必须有"两类都要查**:闪烁/重叠/出画/削波是"不能有";图名框/淡入/字幕/每段至少一个动态元素是"必须有"——后者最容易静默失效。
|
|
355
|
+
|
|
356
|
+
**时间层门禁怎么读**(`work/qa/deep.json`):
|
|
357
|
+
|
|
358
|
+
| 字段 | 意义 | 判据 |
|
|
359
|
+
|---|---|---|
|
|
360
|
+
| `flicker[]` | 只亮一帧的格子:`|F[t]-(F[t-1]+F[t+1])/2|` 分块超阈值 **且** `|F[t+1]-F[t-1]|` 很小("回到原位"——加速运动不满足这条) | 0 条;有的话 `bbox` 告诉你在画面哪个位置 |
|
|
361
|
+
| `black_windows[]` | ≥0.8 s 近黑(片头片尾不算) | 0 段;有就补内容连续性 |
|
|
362
|
+
| `sync[]` | cue 与视觉事件的时间差 | 全部 `|dt| ≤ 0.06 s` |
|
|
363
|
+
| `luma[]` / `loudness[]` | 逐帧亮度 / 短时响度曲线 | 看形状:有没有"该有起伏的地方一条直线" |
|
|
364
|
+
|
|
365
|
+
**别把"重击"当闪烁**:设计好的闪白/震屏会出现在 `events` 里(web 引擎由页面导出,pil 引擎写进 `cues.json`),
|
|
366
|
+
`qa_frames` 会先排除它们再报 `flicker`。没登记却又闪的,才是 bug。
|
|
367
|
+
|
|
368
|
+
**也别把"运动最快的一帧"当闪烁**:二阶差分对加速运动天生过敏(逐字入场、缓动推近、
|
|
369
|
+
交界黑场的起坡帧)。所以判据还有第三道闸——**单帧事件必须"回到原位"**:
|
|
370
|
+
`|F[t+1] - F[t-1]|` 要远小于中间帧的偏离量(`FLICKER_RETURN_RATIO = 1.6`)。
|
|
371
|
+
高分(≥10)但被判成运动的候选**会进 warning**("高分异常被判为运动,建议人工复核")——
|
|
372
|
+
**门禁可以保守,但不能静默**。
|
|
373
|
+
|
|
374
|
+
实测反例(本技能自带的 web 模板片):报了 3 处闪烁,逐一逐帧查下来**全部是**
|
|
375
|
+
"最后一个字入场"和"交界黑场起坡"这两类加速运动;加上这道闸后归零,
|
|
376
|
+
而 selftest 里注入的单帧白闪仍然能被检出——**没被削弱的门禁才叫门禁**。
|
|
377
|
+
调阈值之前先确认这条闸在不在:没有它,你会把正常运动当 bug,改到死。
|
|
378
|
+
|
|
379
|
+
### 音画同步的命名约定(门禁会不会静默失效就看这条)
|
|
380
|
+
|
|
381
|
+
`sync_check` **先按 `events.kind == cue 的配方名` 配对**。所以画面里"该响一下"的事件,
|
|
382
|
+
kind 要写成**同一个配方名**:
|
|
383
|
+
|
|
384
|
+
```js
|
|
385
|
+
S.cue(0.62, 'impact', {size: 1.15}); // 音频:配方名 impact
|
|
386
|
+
S.event(0.62, 'impact', {}); // 画面:同名的 visual event
|
|
387
|
+
S.event(0.62, 'ring', {}); // 纯装饰事件:用通用名,不参与配对
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
**不这么写会怎样**:页面只导出 `flash / shake / ring` 而 cue 是 `impact / whoosh` 时,
|
|
391
|
+
同 kind 永远配不上、跨 kind 又只做确认,`sync` 会恒为空 —— **看起来"零超差",其实一条都没在查**。
|
|
392
|
+
|
|
393
|
+
两道保护:
|
|
394
|
+
1. `qa_frames` 发现"cues 与 events 没有任何同名项"时**主动给 warning**("音画同步检查可能没生效");
|
|
395
|
+
2. 自查:故意把某个 cue 的时刻改错 0.3 s 重跑,**必须**能报出超差。不报就是没配上。
|
|
396
|
+
|
|
397
|
+
### PIL 路线的同步门禁怎么真的生效(v0.4 新增)
|
|
398
|
+
|
|
399
|
+
`--engine pil` 没有页面,也就没有 `events`,"同 kind 配对"永远配不上——**这条门禁默认是没在查的**。
|
|
400
|
+
v0.4 给了两条真正能用的路:
|
|
401
|
+
|
|
402
|
+
1. **给 cue 写画面锚点**(推荐):在 `film.json` 的 `sfx.cues` 或 `scenes.py` 的 `cues()` 里,
|
|
403
|
+
给每条 cue 加一个可选字段 `"visual_at"`(或 `"visual_t"`),值是**画面上那个事件真正发生的绝对秒数**:
|
|
404
|
+
|
|
405
|
+
```json
|
|
406
|
+
{ "at": "l03+0.05", "type": "impact", "visual_at": 15.77 }
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
`qa_frames` 会直接算 `|cue 时刻 - visual_at|` 并报超差,不依赖 events / 命名约定。
|
|
410
|
+
锚点必须写画面上的真实时刻——随便填一个等于自己骗自己。
|
|
411
|
+
|
|
412
|
+
2. **把"没查"变成失败**:设环境变量 `QA_REQUIRE_SYNC=1`(或 `qa_frames.py --require-sync`),
|
|
413
|
+
"音画同步门禁没执行"就从 warning 升级成 error。CI / 交付前建议开着。
|
|
414
|
+
|
|
415
|
+
两条都没做时,`deep.json` 里 `sync` 恒为 `[]`,同时会有一条 warning 明说"同步对照跳过"。
|
|
416
|
+
**看到 `sync: []` 先确认是"真的同步"还是"根本没查"**——`warnings` 里有没有那句话就是判据。
|
|
417
|
+
|
|
418
|
+
## 8. 常见故障速查
|
|
419
|
+
|
|
420
|
+
| 现象 | 根因 | 修法 |
|
|
421
|
+
|---|---|---|
|
|
422
|
+
| 后半段全程静音 | ffmpeg 多输入混流竞争 | 改 numpy 总线 `bus[i:i+n] += src*gain` |
|
|
423
|
+
| 混音爆音/削波 | 先 `astype(float32)` 再判 dtype,归一化分支不执行 | **先判 dtype 再转**,并打印中间峰值 |
|
|
424
|
+
| 字幕越出画面被裁 | 字幕带贴底 | `SUB_BAND` 上移到 872,`base_y` 夹紧 |
|
|
425
|
+
| 文字发虚 | cv2 中间文件二次压缩 | 改 rawvideo 直通 + CRF18,用锐度比验证 |
|
|
426
|
+
| 音画不同步 | 按字数估时长 | 改实测时长驱动 |
|
|
427
|
+
| 字幕交叠 | 按字符比例分配字幕时长 | 以 TTS 句边界为窗,窗内按标点切 |
|
|
428
|
+
| 全片该有的淡入/图名框消失 | 字段改名没跑冒烟 | 改名后必跑 `snap`;质检加"元素存在性" |
|
|
429
|
+
| 渲染越跑越慢 / 内存涨 | 每块开新浏览器没关 | 复用会话 + `finally` 关闭 |
|
|
430
|
+
| 拼出的片子缺一段还不报错 | 分块按"第几块"命名 | 按**绝对起始帧**命名 + 显式缺口检测 |
|
|
431
|
+
| **请求 524 帧却只出 488 帧** | `-shortest` 按较短一路(音频)截断 | 去掉 `-shortest`,显式 `-t <视频时长>` + 校验音视频时长差 < 0.05 s |
|
|
432
|
+
| 产出 13 小时的怪物文件 | `-stream_loop -1` 让 `-shortest` 失效 | 显式 `-t`,别依赖 `-shortest` |
|
|
433
|
+
| BGM 混音后掉 6 dB / 听不清 | `amix` 默认 `normalize=1` 会按输入数均分 | `amix=...:normalize=0` 再 `loudnorm=I=-16` |
|
|
434
|
+
| 旁白整体偏移 ~0.6 s | `adelay` 铺轨有系统性偏移 | 别用 adelay,改 numpy 按采样点写位 |
|
|
435
|
+
| 烧录字幕字号小得看不清 | SRT 交 libass 按 `PlayResY=288` 排版 | `FontSize/MarginV` 要 ×3.75,或直接用 ASS 指定 PlayRes |
|
|
436
|
+
| ASS 字幕位置全乱 | Format 行漏了 `MarginL/MarginR/MarginV` 字段 | ASS 头 Format 行字段顺序必须与 Dialogue 完全对应 |
|
|
437
|
+
| 渲染出上一部片的内容 | `sys.path` 顺序导致 import 到旧模块 | 用绝对路径 + 每次全新进程;子进程别继承父进程模块缓存 |
|
|
438
|
+
| 画面里 ✓ × ↵ 显示成方框 | msyhbd 缺这些字形 | 用矢量画(ImageDraw 线条),不要用符号字符;或先跑 `K.check_glyphs` |
|
|
439
|
+
| **改了台词但配音没变** | TTS 缓存只判断"文件存在" | v0.2 已把 text/voice/rate/pitch 哈希写进 `*.mp3.json`;旧缓存需 `--force-tts` 一次 |
|
|
440
|
+
| **长句字幕读到一半消失** | `sub_window` 把 t1 钳在 `voice_start+5.2` | v0.2 默认覆盖整句;要钳短显式传 `max_hold` |
|
|
441
|
+
| **--stage qa 也重渲全片** | stage 分发写成 `in ("all","frames","mux","qa")` | v0.2 每个 stage 独立;qa 只读成片 |
|
|
442
|
+
| **concatenation 打不开分块** | concat.txt 里写相对路径,ffmpeg 按自己 cwd 解析 | 写**绝对路径**(v0.2 已修) |
|
|
443
|
+
| 成片比 silent.mp4 慢一倍 | mux 对已编码视频又编一遍 | `-c:v copy`(v0.2 默认);只在要改分辨率时 `reencode_video=True` |
|
|
444
|
+
| 每帧渲染慢 2–3 倍 | 每帧重新 `wrap_cn`(中文逐字测宽) | 用 `K.wrap_cn_cached` / `K.text_w_cached` |
|
|
445
|
+
| 混音偶发爆表 | 归一化分支没执行 / 叠加峰值 >1 | `AudioBus.mix()` 会打印叠加峰值并软限幅,峰值 >0.97 报警 |
|
|
446
|
+
| **成片音轨变成 96kHz** | mux 没指定 `-ar`,loudnorm 内部升到 192kHz 后 AAC 取了 96k | mux 显式 `-ar 48000`(v0.2 已内置,selfcheck 第 12 条守着) |
|
|
447
|
+
|
|
448
|
+
## 9. 参考资料(按需加载)
|
|
449
|
+
|
|
450
|
+
- `references/pipeline.md` — 八阶段详细规格、契约 JSON 格式、目录约定、并行分工
|
|
451
|
+
- `references/scene-authoring.md` — 场景函数写法、构图规则、Canvas/CDP 方案、超采样与后处理
|
|
452
|
+
- `references/audio.md` — 采样级混音、程序化配乐/音效、响度链路、循环环境音、提示点系统
|
|
453
|
+
- `references/sfx-design.md` — **(v0.3)音效设计**:物理拆解流程、配方表、听感诊断表、QC 规则
|
|
454
|
+
- `references/web-engine.md` — **(v0.3)浏览器引擎**:页面契约、确定性时间轴、分块渲染、崩溃重开
|
|
455
|
+
- `references/frame-qa.md` — **(v0.3)帧级质检**:单帧闪烁判据、画面空窗、音画同步、报告怎么读
|
|
456
|
+
- `references/quality-gates.md` — G0–G6 全部门禁、可复制代码、验收清单
|
|
457
|
+
- `references/pitfalls.md` — 20 条最佳实践 + 16 条反模式 + 3 个非确定性 bug 复盘
|
|
458
|
+
|
|
459
|
+
## 10. 脚本资产
|
|
460
|
+
|
|
461
|
+
| 文件 | 作用 |
|
|
462
|
+
|---|---|
|
|
463
|
+
| `scripts/filmkit.py` | 生产内核:字体/字形自查/缓存排版/字幕安全区/缓动/确定性随机/音频总线/**CueBus 提示点**/**立体声混音 mix_film**/TTS/时间轴/**hold 停留窗口**/FrameSink/合成/质检 |
|
|
464
|
+
| `scripts/render.py` | 编排器:**10 个独立 stage**、两种引擎(`--engine pil\|web`)、分块并行(`--jobs`)、断点续跑(`--resume`)、母版预览(`stills`) |
|
|
465
|
+
| `scripts/selfcheck.py` | 回归自检:**24 条**"曾真的坏过"的断言,不联网 20 秒出结论(可选模块缺失标 SKIP) |
|
|
466
|
+
| `scripts/sfxkit.py` | **(v0.3)物理建模音效库**:模态合成/纹理/空间/动力学/母带 + 24 个配方 + `CUE_ALIASES` |
|
|
467
|
+
| `scripts/scorekit.py` | **(v0.3)程序化配乐**:和弦表/分段能量/律动层/吸气/自动电平,输出 `music.wav` |
|
|
468
|
+
| `scripts/webengine.py` | **(v0.3)浏览器逐帧渲染**:Edge/Chromium + CDP 截图、分块并行、崩溃重开、cue 导出、文字质检 |
|
|
469
|
+
| `scripts/qa_frames.py` | **(v0.3)帧级质检**:单帧闪烁/画面空窗/音画同步/亮度与响度曲线(JSON + PNG) |
|
|
470
|
+
| `assets/scenes.py` | 场景模板(开场/正文卡片/收尾 + **`cues()` 提示点钩子示范**),含缓存排版与预烘焙背景的正确写法 |
|
|
471
|
+
| `assets/film.json` | 剧本模板(含 `hold`/`bpm`/`music`/`sfx.cues`/`engine` 等新字段) |
|
|
472
|
+
| `assets/web/` | **(v0.3)浏览器页面模板**:原生 Canvas2D 确定性时间轴、场景示范、文字质检脚本 |
|
|
473
|
+
| `requirements.txt` | **(v0.4)Python 依赖清单**:必需(numpy/Pillow/edge-tts)/ 强烈建议(cv2)/ 可选(scipy、playwright)三档,带注释说明"缺了会怎样"。`pip install -r requirements.txt` 即可 |
|
|
474
|
+
|
|
475
|
+
### 关键内置能力(v0.2)
|
|
476
|
+
|
|
477
|
+
| API | 用途 |
|
|
478
|
+
|---|---|
|
|
479
|
+
| `K.tts(...)` | 逐句合成;缓存 key = text+voice+rate+pitch 哈希;网络重试 4 次;可选尾静音裁剪 |
|
|
480
|
+
| `K.loudnorm_two_pass(...)` | 两遍响度标准化,返回可给 `-af` 的滤镜串 |
|
|
481
|
+
| `K.loudness(path)` | 返回 `{I, LRA, TP}`(真峰已开 `ebur128=peak=true`) |
|
|
482
|
+
| `K.AudioBus.music_bed(...)` | 连续配乐床(和弦交叉淡化,无接缝爆点) |
|
|
483
|
+
| `K.AudioBus.mix()` | 归一化 + 软限幅,打印叠加峰值,>0.97 报警 |
|
|
484
|
+
| `K.wrap_cn_cached / text_w_cached` | 场景每帧排版必用(实测单帧 12ms → 4.6ms) |
|
|
485
|
+
| `K.glyph_missing_chars / check_glyphs` | 缺字形自查(✓ × ↵ 会画成方块) |
|
|
486
|
+
| `K.write_ass(...)` | 直接输出 ASS,头里声明 PlayResX/Y=1920/1080 |
|
|
487
|
+
| `K.encode_quality(film, ref_img=...)` | 锐度比;参考帧必须来自场景函数,不能是成片抽帧 |
|
|
488
|
+
|
|
489
|
+
## 11. 验收话术(不要自我宣称"做好了")
|
|
490
|
+
|
|
491
|
+
交付时必须能贴出:
|
|
492
|
+
1. `ffprobe` 的时长/分辨率/码率
|
|
493
|
+
2. `ebur128` 的积分响度与**真峰**(两个数都要,只有响度不算)
|
|
494
|
+
3. 编码锐度比(≥0.85)**并说明参考帧来自场景函数重新渲染**
|
|
495
|
+
4. 联系表路径 + "已用 read_image 亲眼确认"的**具体观察**(不是"看起来不错")
|
|
496
|
+
5. 字幕条目数 = 剧本句数(无静默丢失)
|
|
497
|
+
6. `python selfcheck.py` 的 PASS 计数
|
|
498
|
+
7. **(v0.3)帧级深检的三个数**:单帧闪烁 N 条 / 画面空窗 N 段 / 音画同步超差 N 条
|
|
499
|
+
(有 web 引擎时再加页面层的 文字重叠 / 出画 / 一闪而过 / 从没露面 四项)
|
|
500
|
+
|
|
501
|
+
> 完整示例(本技能自带模板片的实测,可以照这个格式抄;**数字每次跑会差一点**——
|
|
502
|
+
> TTS 实测时长、AAC 编码都会让真峰/响度/锐度在小范围内浮动,别 chasing 小数点):
|
|
503
|
+
> ```
|
|
504
|
+
> 容器:1920x1080 / 30 fps / h264+aac / 48 kHz / 时长 30.10 s / 1.00 Mbps
|
|
505
|
+
> 信号:-16.0 LUFS / 真峰 -1.2 dBTP / 锐度比 1.01 / 黑帧 0 / 字幕 4 条 = 剧本 4 句
|
|
506
|
+
> 时间:单帧闪烁 0 / 画面空窗 0 / 音画同步超差 0(本条为 web 引擎或写了 visual_at 时才有意义)
|
|
507
|
+
> 自检:selfcheck PASS 24 / FAIL 0 / SKIP 0;tools/ci_check.py PASS 11 / FAIL 0
|
|
508
|
+
> 目检:work/qa/sheet.png,四帧分别为开场星射线、五步成片卡片、画质三件事卡片、收尾居中大字;
|
|
509
|
+
> 字幕黑底白字不压正文,大字边距均匀,无空洞帧。
|
|
510
|
+
> ```
|
|
511
|
+
|
|
512
|
+
> 自查口令:如果一条门禁从来没失败过,先确认它是不是根本测不到。
|
|
513
|
+
|
|
514
|
+
## 12. 作者机器已验证的环境事实(2026-11-07 实测)
|
|
515
|
+
|
|
516
|
+
> **本节是作者机器(Windows 11 + Ryzen AI 9 HX 370 + OSGeo4W Python 3.12)的实测基准,不是跨机器承诺。**
|
|
517
|
+
> 换机后请先用 5 分钟重测:`ffmpeg -version`(是否有 libx264/aac/loudnorm)、
|
|
518
|
+
> `python -c "import numpy,PIL,cv2"`、`dir C:\Windows\Fonts\msyhbd.ttc`、`edge-tts --list-voices`。
|
|
519
|
+
> 任何一项不符,先改 `filmkit.FONT_CANDIDATES` / `FILMKIT_FFMPEG` 环境变量,别硬跑。
|
|
520
|
+
|
|
521
|
+
**这些数字是实测的,不是文档抄的。**
|
|
522
|
+
|
|
523
|
+
| 项 | 实测结论 |
|
|
524
|
+
|---|---|
|
|
525
|
+
| ffmpeg | **9.0.2 full_build**(gyan.dev),路径 `C:\Users\Administrator\AppData\Local\Microsoft\WinGet\Links\ffmpeg.exe` |
|
|
526
|
+
| 编码器 | 实测可用:libx264 / libx265 / libvpx-vp9 / **aac(native)** / h264_amf;**无 libfdk_aac**。ffmpeg 构建里**带 nvenc 编码器**(h264/hevc/av1_nvenc),但本机无 NVIDIA GPU,跑不起来——别看到 `ffmpeg -encoders` 里有就以为能用 |
|
|
527
|
+
| 滤镜 | drawtext(支持 fontfile)、subtitles/ass、zoompan、xfade、afade、amix、loudnorm 全在 |
|
|
528
|
+
| ⚠ 第二套 ffmpeg | `C:\Program Files\EVCapture\ffmpeg.exe` 是 2019 旧版且**没有 xfade**,别混用 |
|
|
529
|
+
| Python | OSGeo4W 3.12.16;numpy 2.5 / PIL 13 / cv2 5.0 / scipy 1.18 / edge-tts 7.3.1 / matplotlib / faster-whisper 已装 |
|
|
530
|
+
| Python 缺 | **moviepy / pydub / soundfile / librosa / manim 都没装** → 代码里别 import 它们 |
|
|
531
|
+
| 字体 | msyh/msyhbd/simhei/simsun/simkai/simfang/Deng + Noto Sans/Serif SC;**PIL 加载 ttc 必须带 `index=0`**(index=2 会抛 OSError) |
|
|
532
|
+
| 字形缺口 | msyhbd 缺 ✓ × ↵ → 用矢量线条画,不要用符号字符 |
|
|
533
|
+
| TTS | edge-tts 可用,zh-CN 8 个音色;单句 4 s 语音约 4 s 合成 |
|
|
534
|
+
| 硬件 | Ryzen AI 9 HX 370 / 12C24T / 59.6 GB / **Radeon 890M 无 CUDA** |
|
|
535
|
+
| 编码速度 | x264 `-preset medium -crf 17` = **141 fps(4.7× 实时)**;x265 94 fps;vp9 65 fps |
|
|
536
|
+
| 硬件编码 | h264_amf 127 fps —— **不比 x264 快,体积大 2.5 倍,不用** |
|
|
537
|
+
| 端到端 | 17.47 s 成片(524 帧 + 3 句旁白)编码 4.99 s = **3.5× 实时** |
|
|
538
|
+
| 实测渲染 | PIL 中等复杂度场景 **40–54 fps**(1080p30);自带模板片 **68–82 fps**(多次实测区间) |
|
|
539
|
+
| 磁盘 | 当时约 C 300 GB / D 520 GB(会持续变动,别当基准) |
|
|
540
|
+
|
|
541
|
+
### v0.3.0 各模块实测(同机,2026-11-07)
|
|
542
|
+
|
|
543
|
+
| 模块 | 实测数据 |
|
|
544
|
+
|---|---|
|
|
545
|
+
| `sfxkit` | 24 配方单次渲染 ≤ 1.5 s(**selftest 断言的门槛**;空载最慢 wind ≈0.8 s,并发负载下 ~1.3 s);**389 s 长环境声** wind 5.7–7.8 / rain 7.3–7.9 / campfire 6.3–6.7 s(预算 8 s,随负载浮动);真峰与 ffmpeg 差 **0.05 dB**;响度与 ebur128 差 **0.01 LU** |
|
|
546
|
+
| `scorekit` | 389 s 全片 **4–8 s**(v0.3 首测 6.7–8.2 s,v0.4 复测 3.9–5.8 s,随负载);60 s 实测 2–4 s;输出 -18.5 LUFS / -1.44 dBTP(母带交给 loudnorm)。**selftest 会打印当下实测**,以那个为准 |
|
|
547
|
+
| `webengine` | **80–130 ms/帧**(1080p30,Edge 无头,PNG 截图);12 s / 360 帧 **28–30 s**(2 workers,含启动);**同一页面会话内**同帧两次截图 byte 完全一致(跨会话默认 GPU 光栅有 ≤4 像素、±1 级抗锯齿差异,要跨会话字节级一致请开 `--deterministic`,代价约 +22%/帧) |
|
|
548
|
+
| `qa_frames` | 30 s 片全量深检 **约 1 s**(160×90 流式解码 903 帧);闪烁/空窗/静止/同步 |
|
|
549
|
+
| 端到端 | 30.10 s 模板片:TTS 4 句 → cues 13 条 → 配乐 3.3 s → 音效 13 条落位 → 混音 → PIL 75 fps 渲染 12 s → mux → 深检 PASS |
|
|
550
|
+
| Python 依赖 | **playwright 已装**(chromium + msedge 均可用);scipy 1.18 已装(sfxkit 可选,缺了走 FFT 兜底);`soundfile` **没装**(本技能不依赖它) |
|
|
551
|
+
|
|
552
|
+
### 排期公式(保守)
|
|
553
|
+
|
|
554
|
+
```
|
|
555
|
+
Pillow 路线: 墙钟秒数 ≈ 帧数 / 40 / 并行度 + 30% 余量
|
|
556
|
+
浏览器路线: 墙钟秒数 ≈ 帧数 × 0.3 / 并行度 + 30% 余量
|
|
557
|
+
重负载画面(多图/模糊/纹理):按 12–23 fps 估,而不是 40–54 fps
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
### 三条来自实战的"隐形坑"
|
|
561
|
+
|
|
562
|
+
1. **`-shortest` 会按较短一路截断**:音频比视频短 1.2 s 时,请求 524 帧只出 488 帧,且不报错。**永远显式 `-t` 并校验两路时长差 < 0.05 s**(`filmkit.mux` 已内置此检查)。
|
|
563
|
+
2. **`-stream_loop -1` 让 `-shortest` 失效**:会产生 13 小时的怪物文件。循环输入必须配显式 `-t`。
|
|
564
|
+
3. **`amix` 默认 `normalize=1`**:按输入数均分,2 路输入直接掉 6 dB。要么 `normalize=0`,要么走 numpy 总线(推荐)。
|
|
565
|
+
|
|
566
|
+
## 13. 升级须知(从旧版迁移要动的地方)
|
|
567
|
+
|
|
568
|
+
### 13.0 v0.3.0 → v0.4.0
|
|
569
|
+
|
|
570
|
+
**多数项目不用改任何东西**(默认行为向后兼容),但下面几处会**改变你看到的输出或报错**:
|
|
571
|
+
|
|
572
|
+
| 变更 | 影响 | 你要做什么 |
|
|
573
|
+
|---|---|---|
|
|
574
|
+
| `--resume` 增加计划指纹 | 改过台词 / scenes.py / crf·preset·chunk 之后再用 `--resume`,会**报错拒绝拼接**(旧行为是静默复用错画面) | 按提示 `rm -rf work/segments` 重渲;没改过东西时 `--resume` 照旧只补缺块 |
|
|
575
|
+
| `music.mode=off` 真的不混配乐 | 以前 `work/music.wav` 存在就会被混进去;现在 off 时既不读也不删 | 想用外部配乐:显式 `"mode": "file"`,或不写 `mode`/`bpm` 让兼容链生效 |
|
|
576
|
+
| `--stage qa` 报错更严 | 缺 `scenes.py` 时不再崩,改为丢参考帧 + 两条 WARN;锐度比参考帧按时刻配对 | 无(行为更合理) |
|
|
577
|
+
| 新增"画面长时间静止"WARN | 连续 6 s 无视觉变化会告警(默认不 fail) | 设计上确实要静止 >6 s 就接受它;误报可调 `FLAT_DRIFT_EPS` |
|
|
578
|
+
| 音画同步可真的生效 | cue 支持 `visual_at`;`QA_REQUIRE_SYNC=1` 把"没查"升级为 error | 想用门禁就加锚点 + 环境变量;不想要就保持默认(仅 warning) |
|
|
579
|
+
| `film.json` 校验变严 | 缺 `text` / `lines` 空 / id 重复 / bpm 非法 会直接报错 | 按提示修剧本 |
|
|
580
|
+
| 可选 peer 改成按需 import | 缺 `@deepseek-ai/dsh-skill-filesystem` 时插件不再整体加载失败,只是不挂载技能并打日志 | 想用技能就按日志里的命令装依赖 |
|
|
581
|
+
|
|
582
|
+
### 13.1 v0.2 → v0.3.0
|
|
583
|
+
|
|
584
|
+
**兼容性优先:老项目不做任何改动也能跑**(`engine` 默认 `pil`、`music.mode` 缺省时按老的和弦床走、`whoosh` 行为保留)。
|
|
585
|
+
|
|
586
|
+
| 变更 | v0.2 | v0.3.0 | 你要做什么 |
|
|
587
|
+
|---|---|---|---|
|
|
588
|
+
| stage 列表 | 7 个 | **10 个**(+cues/score/sfx) | `--stage all` 顺序变了;单独跑多阶段时补 `--stage cues sfx` |
|
|
589
|
+
| 渲染引擎 | 只有 PIL | `--engine pil\|web` | 想用浏览器就拷 `assets/web/` 并装 playwright |
|
|
590
|
+
| 配乐 | 只有和弦床 | 有 `bpm` 时用 scorekit | 想保留旧声音:`"music": {"mode": "bed"}` 或不写 `bpm` |
|
|
591
|
+
| 音效 | 每段一声 whoosh | 按 `cues.json` 合成 | 想保留旧行为:不写 `sfx.cues`、不写 `scenes.cues()`,且不跑 `--stage cues` |
|
|
592
|
+
| 混音 | 旁白+配乐两路 | 旁白+配乐+音效三路(带 duck) | 无(自动) |
|
|
593
|
+
| 时间轴 | lead/tail/min_dur | + `hold` / `bar` | 想加停留就写 `hold` |
|
|
594
|
+
| 质检 | 成片级 | + 帧级深检(有 `qa_frames.py` 时) | 无(自动;没这个文件就跳过) |
|
|
595
|
+
| qa 退出码 | 恒 0 | **有 FAIL 就返回 1** | CI 里会开始真的失败——这是故意的 |
|
|
596
|
+
|
|
597
|
+
**新增文件**:`sfxkit.py` / `scorekit.py` / `webengine.py` / `qa_frames.py` / `assets/web/`(都是可选,缺失时对应能力自动降级并打印 WARN)。
|
|
598
|
+
|
|
599
|
+
### 13.2 v0.1 → v0.2(历史)
|
|
600
|
+
|
|
601
|
+
| 变更 | v0.1 | v0.2 | 迁移动作 |
|
|
602
|
+
|---|---|---|---|
|
|
603
|
+
| 阶段语义 | `--stage mux/qa/frames` 都会重渲全片 | 每个 stage 只做自己的事 | 脚本里连续跑多阶段时去掉重复的 `--stage all` |
|
|
604
|
+
| TTS 缓存 | 只判断 mp3 存在 | text/voice/rate/pitch 哈希必须匹配 | 首次升级加 `--force-tts` 跑一次 |
|
|
605
|
+
| 字幕窗口 | 硬钳在 `voice_start+5.2` | 默认覆盖整句(`end-0.06` 封顶) | 确实要短字幕就传 `sub_max_hold` |
|
|
606
|
+
| 视频合成 | 对 silent.mp4 再编一遍 libx264 | `-c:v copy`(不重编码) | 要改分辨率时显式 `"reencode_video": true` |
|
|
607
|
+
| 帧尺寸 | 不符时静默 resize | `strict=True` 直接报错 | 场景函数必须返回 1920×1080 |
|
|
608
|
+
| 码率门禁 | `min_bitrate=3Mbps` 算错误 | 默认不当门禁,只做参考 | 需要就显式传 `min_bitrate` |
|
|
609
|
+
| 真峰门禁 | 解析不到 Peak → 永不触发 | `ebur128=peak=true`,真测 | 无(自动生效) |
|
|
610
|
+
| 锐度比 | 参考帧用成片抽帧 → 恒 ≈1.0 | 参考帧由场景函数重新渲染 | 无(`st_qa` 已改) |
|
|
611
|
+
| TTS 音频 | 保留 edge-tts 尾部 ~0.95s 静音 | 默认裁掉首尾静音 | 想保留:`"trim_silence": false` |
|
|
612
|
+
|
|
613
|
+
## 14. 换机 60 秒自检(比读文档快)
|
|
614
|
+
|
|
615
|
+
```bash
|
|
616
|
+
cd <SKILL_DIR>/scripts
|
|
617
|
+
python selfcheck.py # 24 条断言;FAIL 就照提示修环境
|
|
618
|
+
python sfxkit.py --selftest # 音效库(可选模块,装了才跑)
|
|
619
|
+
python scorekit.py --selftest # 配乐
|
|
620
|
+
python webengine.py --selftest # 浏览器引擎(24 项,会真起无头浏览器,约 15 秒)
|
|
621
|
+
python qa_frames.py --selftest # 帧级质检(自己造测试视频)
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
selfcheck 自己造测试信号、现场调 ffmpeg 编码,**不联网、不依赖任何成片**。
|
|
625
|
+
每条 FAIL 都对应一个具体环境缺口(缺字体 / ffmpeg 无 libx264 / 无 numpy / 缺 sfxkit),
|
|
626
|
+
报错信息直接写该改哪里。可选模块缺失时 selfcheck 标 `SKIP` 而不是 FAIL——
|
|
627
|
+
**别把"没装可选件"和"坏了"混为一谈**。
|
|
628
|
+
|
|
629
|
+
> **仓库级体检**(v0.4 起)是另一层,别和 selfcheck 搞混:
|
|
630
|
+
> `python tools/ci_check.py -v` 只查"这个仓库作为可分发包是否完整"(语法/JSON/依赖白名单/
|
|
631
|
+
> 打包卫生/文档路径引用),**不需要 ffmpeg、字体或网络**,任何机器都能跑;
|
|
632
|
+
> selfcheck 查的是"技能还能不能真的出片"。两层都在 CI 里跑。
|
|
633
|
+
|
|
634
|
+
### v0.2 在本机实测(2026-11-07,同一台机器)
|
|
635
|
+
|
|
636
|
+
| 项 | 数据 |
|
|
637
|
+
|---|---|
|
|
638
|
+
| 场景渲染(缓存排版 + 预烘焙背景) | **单帧 12.3ms → 4.6ms**;885 帧整片约 8s(103 fps) |
|
|
639
|
+
| 分块并行(--jobs 3,4 段) | 885 帧 **7s** 完成分段,拼接后时长误差 0 |
|
|
640
|
+
| mux(视频流 copy) | 两遍 loudnorm 后 −16.5 LUFS / 真峰 −1.5 dBTP,不二次编码 |
|
|
641
|
+
| 11 分钟真实片 | 帧渲染 69–80 fps |
|
|
642
|
+
| selfcheck | 14/14 PASS(含真峰、ASS PlayRes、尾静音裁剪、mux 48kHz) |
|