Dynamic Lyric Video —— 动态歌词视频

适用场景

用户给出 一个模板视频（或只要这种风格）+ 一首歌(wav) + 歌词(txt，无时间轴) + 1~N 张插画，要求产出同款视频；以及后续的超分/补帧/4K 化需求。

典型画面（B 站动态歌词视频）：全屏模糊压暗背景 + 左侧霓虹圆角面板（滚动歌词、当前行高亮）+ 面板底部音频频谱柱 + 右侧圆角图片卡片（缓慢推拉）+ 上角水印 + 底部滚动感谢名单。

第一次使用：三步

# ① 体检 + 生成配置 + 建目录 + 素材自检（交互式，推荐）
python templates/setup_wizard.py

# ② 抽一帧看版式（最便宜，几秒出图，先确认配色和字形）
python templates/preview_frame.py 30 90 150

# ③ 正式渲染
python templates/align_lyrics.py medium        # 自动对轴
python templates/render_hires.py --workers 4   # 分块并行 → 拼接 → 混音
python templates/verify_song.py                # 12 项自动校验

引导会生成一个 dv.env（放在你执行命令的目录），里面是路径/歌名/规格。之后所有脚本都会自动读它，不需要每次 export 一堆环境变量。

完整步骤、目录约定、正常输出样例见 references/quickstart.md。
踩坑与排查见 references/troubleshooting.md。

素材目录约定

每首歌一个子文件夹（<素材根> 由 dv.env 的 DV_DL 指定，默认 ./songs）：

<素材根>/歌名A/
├── 歌名A.wav          # 必须是 16bit PCM WAV
├── 歌名A.jpg          # 配图，png/jpg/jpeg/webp 均可
└── 歌词.txt           # 纯文本，一行一句，无时间轴

文件名是宽容匹配的，不必严格叫 歌名A.wav：

> 若把配图路径写死成 <歌名>.png，用户改用「更正版」后旧图会被继续沿用而毫无提示。
> 所以一律走 paths_util，不要自己拼文件名。

六步流程

0. 拆解模板（有模板时必做，别猜）

ffprobe -v error -show_entries format=duration -show_entries stream=width,height,r_frame_rate,codec_name \
  -of default=noprint_wrappers=1 模板.mp4
ffmpeg -v error -y -i 模板.mp4 -vf "fps=1/6,scale=480:-1" -frames:v 24 build/tpl_%02d.jpg

Read 这些 jpg 目视确认：面板位置/圆角/描边色、歌词高亮样式、卡片比例、是否有水印/版头/感谢名单、频谱位置。
用 AskUserQuestion 一次问清 4 件事：① 配图（生成补图/只用现有图/用户再给）；② 对轴方式（自动/用户给 LRC）；③ 规格（16:9 / 9:16 / 都要）；④ 版头水印（完整模板结构 / 仅频道水印 / 精简只要歌词画面）。

1. 歌词自动对轴（核心，见 templates/align_lyrics.py）

首选 = faster-whisper 词级时间戳 + 已知歌词的拼音 DP 对齐（无需 torch，CPU 可跑）。
识别字序列 vs 已知歌词字序列，用拼音相似度（完全同音 +2.2 / 同声母 +0.9 / 同韵母 +0.5 / 否则 -1）做全局单调 DP（Needleman-Wunsch），回溯得每个歌词字的时间 → 行级起止 → 起点吸附到音频 onset。
- 副歌重复段靠「已知歌词本身按出现顺序含全部重复」+ 单调约束自动解决。
- 产出 timing.json + 人眼可核对的 timing_sheet.txt（含 conf）。conf<0.6 的行提示用户重点核对。

2. 音频分析（见 templates/analyze_audio.py）

stdlib wave + numpy：分帧 FFT → ~30 个对数频段 → dB 归一化 + 时间去 EMA → spectrum.npy；谱通量峰值 → onsets.npy。

3. 预烘焙 + 逐帧合成（见 templates/render_common.py）

• 背景：cover 裁切放大 → 高斯模糊 → 压暗 → 降饱和 → 暗角 → 光斑，一次性烘焙成数组；逐帧只做「预分配缓冲 memcpy + 缓慢漂移」。
• 面板：PIL 一次性画「多层描边→模糊出外发光 + 半透明内底 + 亮绿主描边」的 RGBA 覆盖层。
• 歌词：每行预渲染成 uint8 RGBA 位图（高亮=粗体亮色+外发光；普通=常规灰白；2× 超采样后缩小）；逐帧按「平滑活动行位置」滚动贴图 + 「距离高斯衰减 × 上下边缘 smoothstep」控 alpha；浮点版本走 LRU 缓存（>24 清空）省内存。
• 卡片：固定圆角 mask + 投影（预烘焙）；内部图片预存 1.22×，逐帧裁窗 → resize → 乘圆角 mask → 贴到固定位置，实现 Ken Burns 而不破坏圆角。
• 频谱：查表得柱高，画渐变竖条。

4. 渲染成片

• templates/render_hires.py（推荐）：多进程分块 → NVENC 单次编码 → concat -c copy → 源音频混流。4K60 走这条。
• templates/render.py：moviepy 单进程，用于 1080p 与快速样片（需装 moviepy）。
• 两者都支持 --start/--end 或 --sample-start/--sample-dur 出 10~16 秒样片给用户确认版式，再跑全片。

5. 高清化 / 补帧（4K60 等）—— 见 templates/render_hires.py

核心判断：本视频是程序化生成的，应"原生重渲染"而不是对成片做 AI 超分。

路线 A 的工程要点：
1. 参数化：config.py 用 DV_SCALE/DV_FPS 环境变量 + s(v)/sc(v) 统一缩放全部几何与字号，同一套设计可原生渲染任意倍率。
2. 多进程分块：总帧数 F=round(total*FPS) 切成 N 段，每段一个子进程，各自建 Stage，逐帧结果直接 frame.data 写进该段 ffmpeg 的 stdin（rawvideo rgb24）——不落中间帧文件（4K 全片原始帧约 350GB）。
3. 编码：-c:v h264_nvenc -rc vbr -cq 18 -b:v 40M -maxrate 60M -profile:v high -level:v 5.2 -g 2*FPS。各段参数必须完全一致。没有 NVENC 时用 --codec libx264 兜底。
4. 拼接：concat demuxer + -c copy（每段首帧必为 IDR ⇒ 接缝干净、不二次编码）。
5. 混音：用源 wav 重新混流 -c:v copy -c:a aac -b:a 320k -ar 48000 -ac 2 -movflags +faststart，保证音质。
- 并行数按内存定：4K 单 worker 常驻约 0.5–0.6GB；16 核/15GB 机器用 4–6 并行为宜。NVENC 并发会话在 Ada 消费卡上上限 8。
- 先跑 --sample-start 62 --sample-dur 2 冒烟验证 NVENC 通路与耗时，再整片。

6. 验证与交付

templates/verify_song.py 自动核对 分辨率 / 60fps / duration≈原曲长 / h264 + aac 48kHz stereo / 帧数 / 分块接缝 / 内容抽帧。
在分块接缝处抽帧确认无跳帧/花屏；抽 2–3 帧确认歌词高亮正确；present_files 交付。

配置（全部走环境变量 / dv.env）

主题自动匹配画面：DV_THEME=auto 会读配图算主色相，按扇区选调色板
（red 345–15° / gold 15–70° / green 70–170° / cyan 170–260° / magenta 260–345°；无彩图按亮度兜底）。
> 渲染前建议先跑 theme_auto.pick_theme() 打印一次并目视确认；批量时只算一次写入 build/<歌>/theme.txt，再以 DV_THEME=<名字> 传给所有子进程，保证同曲一致且不重复读图。

单曲四步：

# 设好 DV_SONG 后（或写进 dv.env）
python templates/analyze_audio.py        # 频谱 → build/<歌>/spectrum.npy（必须在对轴前，对轴要读 onsets）
python templates/align_lyrics.py medium  # 对轴 → timing.json + timing_sheet.txt
python templates/preview_frame.py 77     # 单帧校验（先看版式/配色/字形，便宜且能提前发现大问题）
python templates/render_hires.py --workers 6 --cq 18 --resume   # 并行 4K60 → 拼接 → 源音频混流
python templates/verify_song.py          # 12 项自动校验 → verify.json

批量（多首）：直接跑 templates/batch.py（见下节）。

主题调色板：config.py 的 PALETTES 定义 neon / active / near / far / bg_tint / panel_fill 六项，加主题只需加一条 dict。选色原则——跟画面主色调走：冷蓝画面用青绿、紫红画面用品红；panel_fill（面板底色）必须跟着换，否则高亮文字对比度不足。

换歌必查的 10 个坑

1. 源路径写死 → 旧素材一旦被删/覆盖就直接失败。用 DV_IMG/DV_WAV/DV_LYRICS。
2. 歌词标题行混入：用户给的歌词常把歌名放第 1 行，会被当成第 1 句歌词使整条时间轴错位。
3. ASR initial_prompt 未换：写死上一首的歌词会逆向干扰新歌识别。必须取新歌词前 2 行动态拼接。
4. 输出名写死：render*.py 默认输出若写死歌名，会覆盖上一首已交付的成片（4K 动辄 1GB）。按 SONG 派生文件名。
5. 中间件跨曲覆盖：timing.json / spectrum.npy / onsets.npy / chunk_* / concat_list 若共用同一目录会互相覆盖。按歌隔离到 build/<SONG>/。
6. 配色写死：主题色与面板底色要成对可切换。
7. 预览假时长写死：preview_frame.py 无 timing.json 时的兜底总时长应取音频实测值。
8. 配图扩展名被想当然：用户给的常是 .jpeg/.jpg/.webp → 必须自动探测扩展名。
9. "跳过首行标题"的启发式会误删正文（高危）：曾用「无空白且汉字数 ≤ 8」判定标题，结果把某首歌首行「正在删除……记忆……失败……」这类正文整行删掉，同一批里还有三首的首行也被误删。
   → 必须改成精确规则：仅当首行规范化后（去空白/标点/书名号）等于歌名才跳过（已实现在 lyrics_util）。
10. 非中文字符行会被整行丢弃：load_lyrics 若只按「含汉字」筛行，纯藏文行会整行消失；而中文字体不含藏文字形 → 渲染成豆腐块。
    → 歌词行字符集要扩到 汉字 + 藏文(U+0F00–0FFF)；渲染要按逐簇选字体。
    > 另：Whisper 模型目录与歌曲无关，必须放共享目录（build/whisper_<size>），否则每换一首歌都要重新下 1.5GB。

对轴后必做的合理性核查

不要只看"行数对、conf 高"就放行，要看时间分布：
- 某行时长明显长于同文本的其他出现（如 6.3s vs 3.6s）、或两行之间出现异常大空档 → 可能是歌曲本身的编曲（前奏/间奏/尾奏），也可能是对轴错位。
- 判定方法：直接对可疑片段做一次短 ASR 转写（只截该时间段，几秒出结果），看实际唱的是什么。
- 空档总量应能与「歌曲总长 − 各行时长之和」对上（前奏+间奏+尾奏）。

★ 歌词与实际演唱不一致的识别与处置（高频，务必先做）

歌词文本经常比实际演唱多（用户从别的版本复制、编曲改动、歌曲本身有多个演唱版本）。若不核对，成片会大面积对不上。

第一步：字数差是 quickest 的信号
align_lyrics.py 收尾会打印 [自检] 歌词 N 字 vs ASR M 字（差 ±X）。
- |N − M| < 10 → 基本对齐，可继续；
- N ≫ M（实测过 925 vs 673，差 252） → 歌词里必有整段未演唱的冗余行，必须逐段核查。
注意 ASR 有同音替字与吞字，故小幅误差属正常；但上百字的差不可能是识别误差。

第二步：找出「未唱 / 重复唱」的具体位置
不要靠肉眼扫时间轴。用行级拼音匹配把每行歌词定位到 ASR 字流：逐行在 ASR 拼音序列中滑窗找最佳位置，得分低于阈值即判「未唱」。

# 逐行 score = Σ sim(歌词字拼音, ASR 字拼音) / (行字数 × 2.2)，阈值 ~0.62
# sim: 同音 2.2 / 同声母 0.9 / 同韵母 0.5 / 否则 -1.0

该方法有假阴性：ASR 常把小词听错，导致明明唱了的行被判「未唱」。它只用于定位嫌疑区间，最终结论必须靠下面的实测。

第三步：实测定论（按可信度排序）
| 方法 | 用途 | 陷阱 |
|---|---|---|
| 切 mp3 交用户试听 | 唯一 100% 可靠 | 最快，优先用 |
| 短片段 ASR（截可疑区间） | 看实际唱什么 | 无提示时识别 0 字 ≠ 没人声 |
| RMS 能量分析 | 区分「无人声」与「有能量但无实词」 | 需选对照段（正常主歌）做基准 |
| ~~基频/变异系数判唱 vs 念白~~ | 已弃用 | 自相关被倍频程干扰，连正常副歌都误判 |

# 切可疑段（连同对照段）交用户听
ffmpeg -ss 84 -t 18 -i 源.wav -c:a libmp3lame -b:a 192k seg.mp3

两个必须知道的 ASR 陷阱：
1. ASR 识别 0 字 ≠ 该段没人声。实测某段 RMS −10dB（明显高于前后段 7dB）却识别 0 字 —— 是气声/念白/咬字不清段，按「未唱」处理（不显示歌词）通常比硬塞歌词更对。
2. 加歌词 initial_prompt 复识会产生幻觉复读：给一段无人声区间提示真实歌词后，模型输出无关内容，或把提示词本身复读回来。提示词复识结果一律不可信。

第四步：常见的三类不一致及修法
| 类型 | 症状 | 修法 |
|---|---|---|
| 整段未唱 | 该区间 conf 全 0、多行时间重叠、歌词凭空多出几十字 | 从歌词文件删除该段，空档留给画面 |
| 副歌重复唱 N 遍 | 同一文本出现 3 次但其中一次被拉长到 20s+ | 歌词文件补足第 2/3 份 |
| 尾奏歌词不符 | 最后几行唱的是另一段主歌 | 按尾奏实测内容替换 |

第五步：尾奏纯器乐留白属正常，不要强行填词。实测 288–300.6s 留白 12.5s 反而是对的。

验收标准（对齐的充分条件）：|歌词字数 − ASR 字数| < 10 且 conf < 0.6 的行数为 0 且 时间单调。

批量制作（多首歌）

templates/batch.py 串行编排「主题 → 频谱 → 对轴 → 4K60 渲染 → 校验」，幂等可续跑、单首失败不拖垮整批。

python templates/batch.py                        # 自动发现全部
python templates/batch.py --only 某歌 另一首       # 指定歌
python templates/batch.py --from render           # 从某阶段开始
python templates/batch.py --force                 # 忽略标记全重跑
python templates/batch.py --workers 6 --cq 18 --keep-intermediates

核心设计（都是踩过坑才有的）：
1. 可分阶段换解释器：对轴环境要 faster-whisper，渲染环境要 Pillow/moviepy。默认都用当前解释器；需要分离时设 DV_PY_RENDER / DV_PY_ALIGN。
2. 幂等判定 = 状态标记 ∧ 产物存在 ∧ size>0（三重，防残留空文件被当成已完成）。状态写 build/<歌>/batch_state.json。
3. 错误隔离：逐首逐阶段 try/except + 超时；失败只记录并继续，最后汇总。
4. 串行渲染（6 worker 已吃满 CPU/GPU，禁止并行多首）。
5. 渲染顺序 = fail-fast：按预估时长升序，让多数成片尽早产出。
6. 子进程统一 PYTHONUTF8=1（防 Windows GBK 下非中文报错）、HF_HUB_OFFLINE=1。
7. 校验通过后清理 chunk_*.mp4/video_concat.mp4；render_hires.py --resume 支持按分块续渲。
8. 分块渲染必须带重试：并发 NVENC 时偶发某块 ffmpeg 起不来就退出，worker 往管道写帧即抛 OSError: [Errno 22] Invalid argument。旧实现「任一 worker 非 0 就整体失败」→ 一首 25 分钟白跑。
→ 改成线程池 + 每块独立重试（默认 3 次），重试前用 _chunk_valid() 验时长。
⚠ _chunk_valid 必须按时长判定，不能用固定文件大小门槛——短片分块本来就可能小于 1MB，用 1MB 会把成功产物判失败，表现为「rc=0 却重试 3 次后放弃」。
9. 校验要区分「硬失败」与「软失败」：ASR 低置信度、藏文插值时间属于内容不确定性，只能标「需人工复核」，不能判成失败。用 add(..., soft=True) 标记软检查。
10. 校验的期望值别硬依赖环境变量：verify_song.py 若用 config.FPS（默认 30）当预期，手动复验 4K60 成片时会误报"帧率不符"。应「环境变量显式给了就用，没给就按成片自身推断」。
11. 报告要合并写入：--only <歌> 若直接覆盖报告，会抹掉其它歌的行。应读旧报告合并后再写；并留 --rebuild-report 从各 build/<歌>/verify.json 按事实重建。
12. 歌单不要硬编码：写死曲目清单会让「新增歌曲」必须手动 --only，且超时预估与预览图抽帧时刻会按默认时长算错。应自动发现——扫素材根下各子目录认「配图 + .wav + 歌词.txt」三件套。
13. 换图重出时必须清掉幂等标记：batch.py 会跳过「已完成」的阶段，改了配图后直接重跑不会重渲。要加 --force（或删 build/<歌>/batch_state.json 的对应项）。

自动校验 verify_song.py：规格 · 帧数 · 音频 · 行数一致 · 时间单调 · 空档占比与最大单空档 · 首句位置 · 藏文行区间 · conf 统计 · 分块接缝帧差 · 内容抽帧 · 体积/码率。
结论三态：通过 / 通过(需人工复核) / 失败；含藏文行、conf<0.6、接缝或抽帧异常 一律标"需人工复核"。
> 体积/帧率/分辨率的期望值必须随时长与自身规格缩放，写死阈值会把短片样片判失败。

验收：收尾自动拼 output/preview_contactsheet.jpg（每首抽 1 帧 4 宫格），一眼可查版式与配色。

合集模式（把多首曲子拼成一支长视频）

适用：纯音乐合集 / 歌单精选 / 串烧。面板不滚动歌词，改为固定文案 + 当前曲名，卡片按曲切换。

1) 先反解参考合集的编排结构 —— templates/build_compilation.py

python templates/build_compilation.py --ref "<参考合集.mp3>" --tracks "<单曲目录>" --out "build/<合集名>"

它会：归一化互相关定位每首起点（相关度接近 1.0 才算匹配成功）→ 反解曲序 / 曲间隔 / 淡入淡出时长 →
用无损 WAV 重新拼装（顺序与淡化复刻参考、母版音质更好）→ 输出 compilation.wav + segments.json + 合成 timing.json。
- 自检：打印「参考总长 vs 复刻总长」，差应为 0.000s。
- 想直接指定可加 --fade / --gap；不想分析可加 --no-analyze。

两个必踩的坑：
1. 互相关切片长度：irfft 结果要取 [L-1 : N]（长度 N-L+1，与局部能量数组一致）。取成 [L-1 : L-1+N] 会 broadcast 报错。
2. 淡入淡出反解符号：距曲尾 t 秒处衰减 att_mag（正值，dB）→ T = t · 10^(att_mag/20)。
写成 t / 10^(att_mag/20) 会把 T 算小一半以上（实测算出 0.59s，真相是 2.0s）。务必与「曲间隔」交叉印证。

2) 渲染：DV_MODE=compilation

python templates/analyze_audio.py                   # 对 compilation.wav 做频谱
DV_MODE=compilation DV_THEME=cyan DV_SCALE=2 DV_FPS=60 python templates/preview_frame.py 100 203.97
python templates/render_hires.py --workers 5 --cq 18 --resume --out "output/<合集>_4K60.mp4"
python templates/verify_song.py                     # 合集分支会跳过歌词类检查

关键环境变量：DV_MODE=compilation、DV_BUILD（含 segments.json）、DV_WAV（指向 compilation.wav）、
DV_COMPILE_TEXT（面板文案）、DV_XFADE（换图交叉淡化秒数，默认 1.2）。

实现要点（踩过的坑）：
- 背景每张 4200×2520×3，10 段全程驻留会到 1.27GB/进程 → 必须懒烘焙 + LRU 只留邻近 3 段，并用 float16 存储。
- 换图/换曲名放在曲间静音的中段切换：音乐最安静时切换，观感最自然。
- 曲名要「旧名先淡出 → 新名再淡入」顺序淡化，两段同时混叠会在同一位置出现双影。
- 交叉淡化权重方向极易写反：seg_state 应返回 (i=旧段, j=新段, u)，配合「i 权重 (1-u)、j 权重 u」的混色实现；返回顺序反了会导致淡化一开始就显示新图。
- 面板文案与曲名都是预渲染位图，逐帧只做混合，无字体开销。

性能优化（实测：单帧 322ms → 176ms，1.83×）

4K 渲染的成本几乎全在逐帧的大数组浮点运算上，GPU 只负责最后的 NVENC（每帧几毫秒，利用率长期 0~7%）。
所以加大显存/显卡占用没有意义——瓶颈在 numpy 的单线程元素级吞吐。

两个必须避开的「慢 5~13 倍」陷阱（实测数据）

规则：
1. 所有逐帧用到的掩码/色调数组都预先展开成 3 通道（np.repeat(mask[...,None],3,axis=2) + ascontiguousarray）。多占一点内存，换来 6.7 倍。
2. 背景层存 float32，不要存 float16。float16 省内存但每帧转换只有 4.6GB/s，反而成为首要瓶颈。代价是内存×2 → 把段缓存 LRU 压到 2 段。
3. 顺带把「归一化(×1/255) + 加描边 + 遮罩混合」融成固定几次遍历，并做面板预乘（sub*(1-a)+c*a → sub*inv_a + pre_c）。

判断瓶颈的方法（可复用）

# 逐段计时 + 测各操作的 GB/s，就能立刻看出是「内存带宽」「单线程吞吐」还是「GPU」
bench(lambda: a.__imul__(mask3), '广播乘', a.nbytes*2)   # 看 GB/s 是否异常低

• 单进程 3.11 fps，而 5 并发只有 8.5 fps（2.7×） → 已出现内存带宽争用，加 worker 收益递减；此时优化单帧成本比加并发更有效。
• 判断长任务存活：看产物是否在增长 / 文件是否被占用，不要只信 tasklist | grep 的进程计数。

特殊情形速查

歌词文件里的段落标记（务必先过滤）

很多歌词文件用整行括号标注写段落：[主歌1]、【副歌】、（间奏）、[副歌 - 升调]、[尾奏]。
它们不是唱词，若不过滤：① 会原样显示到画面上；② 会进入拼音对齐的 known 序列给 DP 添噪。
- 规则：整行仅为一个括号组（允许尾随少量标点）→ 丢弃；[你]好、[主歌1] 远古的风 这类括号后仍有正文的不误杀。
- 已实现在 lyrics_util.load_lyrics()（含 is_marker()），并打印丢弃了几行；verify_song.py 复用同一函数，行数校验自动一致。
> 经验：动手前先通读歌词。本次同一批素材里就同时存在「段落标记会被上屏」和「内容不适合制作」两类问题，都只能在读原文时发现。

多首歌共用同一份歌词

安全前提：中间件按 DV_BUILD=build/<歌名> 隔离 + 每首独立跑 align。唯一共享的是 Whisper 模型目录（只读），且批量是串行。
- 复用前先逐字节比对两份 歌词.txt（md5sum）确认确实相同——曾遇到「三份歌词同名但内容全是第一首的词」的复制失误。

粤语歌词对轴

pypinyin 取的是普通话读音，粤语专用字会系统性退化：

• 不要把 pinyin_of 改成粤拼映射：会破坏「同字 → 同拼音 → +2.2」的天然匹配。
• 实测规模很小：某粤语词歌里粤语专用字仅占 2.6%，且全在行中后段、无一行行首 → 不会平移行首锚点，靠 DP 的 GAP 兜底 + interpolate() 线性填补即可自愈。
• 含粤语字的行列人工复核重点（嘅/睇/系/唔/畀/咪/咁/冇/佢/乜/嘢）；这些行 conf 天然偏低，属正常，不必返工。

配图长宽比与裁切速查

卡片区比例 ≈ 0.856（774:904）；背景层 ≈ 1.667（4200×2520 @SCALE=2）。cover_crop 按 max(tw/sw, th/sh) 放大后居中裁切：

• 竖图最安全；横图左右各裁 26%，需确认人物居中。
• 卡片 cy=0.56 对竖图基本无感；该值是 render_common.py 里的写死常量，非必要不要改（改前先用 preview_frame.py 抽帧确认确实贴边）。

Windows 环境避坑（血泪，务必先看）

1. pydub 在 Python 3.13 不可用（No module named 'pyaudioop'）→ 一律用 stdlib wave + numpy 读 wav。
2. HF 镜像下载的模型在 Windows 下快照符号链接失效：snapshots/…/model.bin 变 0 字节（blobs 里其实完整）。解法：把 ~/.cache/huggingface/hub/models--Systran--faster-whisper-*/blobs/ 里按体积对号入座的 blob 硬链接成本地目录，再把该目录路径传给 DV_WHISPER_DIR。设 HF_ENDPOINT=https://hf-mirror.com。
3. PyAV 19 与 faster-whisper 不兼容（metadata_errors 参数）→ 绕开 PyAV：自己用 wave 读音频、重采样到 16kHz、把 numpy 数组直接喂给 model.transcribe()（已实现）。
4. moviepy 2.x 与 1.x API 不同：VideoClip(frame_function=…)、.with_audio()、.subclipped()。
5. 字体：中文用 msyhbd.ttc（粗）/msyh.ttc；.ttc 用 ImageFont.truetype(path, size)；符号（♪♫）用 seguisym.ttf，否则显示豆腐块。全部按候选列表探测，不写死某个用户目录。
6. moviepy 收尾偶发 OSError: [WinError 6] 句柄无效——文件通常已完整写出，用 ffprobe 校验时长即可。
7. wmic 在新 Windows 已移除，查硬件用 nvidia-smi 或 Python ctypes。

常见坑（逻辑类）

• smoothstep(a,b,x) 必须支持 b<a 的下降区间，否则边缘渐隐 alpha 恒为 0 → 歌词整片不可见。
• 频谱必须与渲染帧率解耦：频谱/onset 一律按固定 SPEC_FPS（100）分析，索引恒为 t*SPEC_FPS。若索引误用渲染帧率 FPS，则 60fps 渲染时会变成 2× 时间压缩 + 后半段被 clamp。
• 写文件名时别对整串做 .replace(".","_")，会把扩展名的点也替换掉。
• cover_crop 竖版卡片从横图取景时用 cy≈0.56 略偏下。
• 4K 下几何必须全部走 s()；漏一个（如模糊半径、发光半径、漂移幅度）就会版式走样。
• 复用 render_frame 的返回缓冲时，调用方必须立即消费（tobytes()/.data 写管道）再用下一帧。
• 改分辨率/帧率后务必用同一时刻对比新旧版本抽帧（尤其频谱、字幕高亮）。
• 判定渲染效果不要靠肉眼估小图：直接量像素（取频谱区域算亮色像素占比）比目视可靠。
• 改 from config import ... 的导入清单后，务必全局搜索仍被引用但已移除的名字（曾把 FPS 换成 SPEC_FPS 后 NameError，潜伏到下一首歌才暴露）。
• 中藏混排要逐「簇」选字体，不能逐字符：藏文的元音/下加字是组合记号，逐字符切会把 ཱུྃ 拆断导致字形错乱。用 unicodedata.category(ch) in ("Mn","Mc","Me") 判组合，并把藏文分句符 ་(U+0F0B)/།(U+0F0D) 并入前一簇。himalaya.ttf 无粗体 → 高亮行用 stroke_width 伪粗。
• 对轴插值的前段不能全置 0：否则开头是非中文行的歌会全部挤在 t≈0。应把前段从 0 线性铺到首个匹配点、后段铺到曲末。
• ASR 对「喊出来的短句」无能为力：一字一顿的嘶吼识别不到 → 该行 conf=0、时间靠插值，属正常，交给校验标记复核即可。
• 往子进程管道写大 buffer 会抛 OSError: [Errno 22]：这不是数据问题，而是子进程已死。真正的错误在子进程 stderr 里（常见是 NVENC 初始化偶发失败）。所以子进程 stderr 一定要合并进日志，并且必须有重试。

环境

• 渲染：pip install pillow numpy（4K 走 render_hires.py，仅需这两个 + ffmpeg）。
  可选 pip install moviepy 用于 render.py 的 1080p 单进程快渲。
• 对轴：pip install faster-whisper pypinyin（ctranslate2 后端，无需 torch）。
• 硬件加速：h264_nvenc/hevc_nvenc（ffmpeg -encoders | grep nvenc 确认）；无显卡用 --codec libx264。
• 模板脚本见本技能 templates/（config / paths_util / analyze_audio / align_lyrics / render_common / render / render_hires / preview_frame / verify_song / theme_auto / build_compilation / batch / setup_wizard）。复用时先改 config.py 的几何参数以匹配目标模板。