Metadata

name: mv-playbook
description: The entry point to the accumulated MV skill family: a map of which skill governs what, plus the cross-cutting hard rules that were paid for with real mistakes (a parameter tweak invisible on 8-bit footage, a metric poisoned by grain, a metric that answers the wrong question, three different sharpness metrics all pointing the wrong way on the same batch, how to prove your own pipeline did not soften a deliverable). Use this before starting any MV task, when unsure which skill applies, or when adding a new lesson and deciding where it belongs.
metadata: {"slug":"mv-playbook","displayName":"MV Playbook (MV 知识库入口·累积规则)","category":"video","version":"1.1.0","description_zh":"MV 技能家族的入口：哪条线归哪个技能管，加上跨项目通用的硬教训（8bit 素材上看不见的参数微调、被颗粒污染的指标、问错问题的判据、同一天三把清晰度尺子全部指反、怎么证明不是自己的后处理把交付图弄糊的）。开工前先读，不确定该用哪个技能时读，或者学到新东西要决定写进哪里时读。","agent_created":"true"}

MV Playbook · 知识库入口

1. 索引：哪条线归谁

什么时候用	用哪个 skill
开工前、不确定用哪个	`mv-playbook`（本文件）
整片结构怎么组织（几族镜头 / 文字几段 / 世界连不连）	`mv-pv-arrangement`
要出多少张角色/背景图、怎么不漂脸	`mv-character-assets`
图糊了 / 怀疑是自己处理弄糊的	`mv-image-forensics`
日文字幕断句 / 出字时刻 / 排版参数	`mv-jp-lyrics-subtitle`
从零做一支 MV 的流水线	`mv-code-driven-pipeline`
审一支成片 / 反解参考片	`mv-shot-audit`
角色跨帧/跨姿势保持一致	`consistent-character-mv-anchor`
派单给美术端 / 裁决回传	`pet-asset-pipeline`
交付一个客户自己能改的工程	`blender-editable-timeline`
方法论随笔	`mv-methodology-notes`（GitHub）

找东西的三条路

按"我要做什么"找 → 上面这张表
按"我遇到了什么症状"找 → 本文件 §2 铁律（症状都写成了标题，搜关键词如"闪""不同步""发灰"）
按"是哪一步"找 → mv-code-driven-pipeline 的流水线顺序：概念 → 测量 → 分镜 → 资产 → 排版 → 渲染 → 审片 → 交付

研究纪要在哪

每轮 research 的原始纪要落在项目根，文件名 Research纪要-<主题>-<日期>.md。技能里只留结论；要看出处、撤回记录、未查项，回纪要。

2. ⛔ 铁律（每条都是花钱或返工换来的）

铁律 1：参数微调在 8bit 素材上肉眼不可见

量化步长 = 1/base（base 200/220/240 ⇒ 0.005/0.0045/0.00417）。 τ5 vs τ6 只差 1 个量化级；peak 1.06 只抬 1–2 级。 ⇒ 任何"提升观感"的改动，先问：这一改动在成片上肉眼可见吗？ 不可见 ⇒ 不做。观感问题改画面层（构图/运镜/景深/光影/调色/字幕系统/事件密度），⛔ 不是改参数。

铁律 2：判据只管"做没做对"，不管"好不好看"

9 条参数判据全绿 ≠ 片子好看。 ⛔ 不许拿判据通过当审美达标的证据。审美只能由人目检。

铁律 3：指标会被污染，先问"它测的是我以为的东西吗"

拉普拉斯方差判糊不糊：颗粒（σ2.8）会把方差抬高 ⇒ 有颗粒的画面不能用它判清晰度。
整体 bbox 量角色高：漂浮的装饰件会拉大 bbox ⇒ 必须用最大连通域。
能量峰数音节：一个长音里的颤音产生多个峰 ⇒ 16 个音节数出 33 个峰。 ⇒ 换判据前先做阳性对照：拿一个已知异常的样本，判据必须命中。

⭐ 2026-10-28 升级（这条比上面三条更狠）：单图绝对量测不出两图相对判断。 同一天三把原理完全不同的清晰度尺子同时崩，方向全反：

尺子	报了什么	病根
归一化拉普拉斯方差	最糊的 F2 = 1.64× 锚图（"最清晰"）	高饱和橘发 + 纯绿幕撑起方差
径向频谱悬崖	锚图 0.126 ＞新图 0.077	锚图 2.07MP ＞新图 1.57MP ⇒ 测的是"图多大"
内线锐边%	新图 43% vs 锚图 12%（"更锐"）	量到的是键控噪点

⇒ 两张图不是同一条处理链出来的，任何指标比的都是"处理链差异"，不是"锐度差异"。 ⇒ 想让自动指标可用：同一张源图分别过两条待比较的处理链，再比指标。 ⇒ 细节与可复用脚本见 mv-image-forensics。

铁律 4：动手前先 grep 项目里的既定规格

字号、色板、线宽、有无底板——这些往往早就裁定过，躺在 02_文档/ 或 docs/ 里。

grep -rn -E "字幕|字体|排版|几何|字高|描边|底板|色板" docs/ 02_文档/ | head -40

⛔ 不要"我觉得这样更好看"就自己定一套 —— 一定和已裁定规格冲突，返工成本是整片重渲。

铁律 5：素材默认可无限重复用

⛔ 不要给素材/效果设配额（"最多用 1 次""用过的置灰"）。约束要落在观感上（crop / 镜像 / 合成模式 / 视差），不是素材计数上。另外："某个转场用了两次" ≠ 单调。单调的真根因是「各段变化方式像同一个模子」。

铁律 6：字幕不要用「逐段出字」

逐段弹出 = 请观众核对每个字的时刻。时间戳有 0.2s 误差就暴露。 ⇒ 整句一次性出（断句靠版面表达），或者用「唱到时强调」代替。

铁律 7：歌词时间轴文件多半不可信

lyrics.ts / SRT / LRC 的 start/end 常常是按行数线性切或手工估的。 ⇒ 先用人声换气间隔（静音段）验证每句的真实起止，再谈句内断句。实测案例：某句标 19.50 起，真起点 23.63，早 4.1 秒。

铁律 8：agent 起的进程活不过 turn

要想让用户看到软件，只能给他一个双击启动器（.cmd，CRLF，用字节写）。 ⛔ 不要用 printf 拼 Windows 路径（\U、\b 会被当转义吃掉）。

铁律 9：中文路径一律 `np.fromfile` + `cv2.imdecode`

cv2.imread 读中文路径会静默返回 None。

铁律 10：派单里的路径要逐条核验

"我以为路径对" 和 "路径真的对" 是两件事。今天就是这么发现同一个错路径出现在两份派单里的。

铁律 11：宁可写「有 N 项待修」，不写「基本完成」

⛔ "基本完成"是自欺。列出不合格项，逐项给实测值。

3. 累积流程（学到新东西往哪写）

每学到一条，走这三步：

归位：它属于哪个 skill？
- 结构/编排 → mv-pv-arrangement
- 字幕/文字 → mv-jp-lyrics-subtitle
- 一致性/素材 → consistent-character-mv-anchor
- 交付/工程 → blender-editable-timeline
- 派单/裁决 → pet-asset-pipeline
- 跨线通用 → 本文件 §2 铁律
变成可执行：写成「症状 → 根因 → 修法 → 实测数字」。 ⛔ 不写「注意 XX 可能有问题」这种没用的提醒。
进反面清单：凡是我试过且失败的，写进对应 skill 的「别再试」区。失败的经验比成功的更值钱，因为它能省掉下一次的重复踩。

判断标准：一条好条目长什么样

差	好
「注意通道可能冲突」	「给 ch3 赋值时 char 被静默推到 89..177 帧，整段消失」
「字幕可能不同步」	「句标 19.50 起，实测 23.63，早 4.1 秒」
「颗粒会影响判据」	「σ2.8 颗粒把拉普拉斯方差抬高，B1 647 vs 原片 382，判据失效」

没有数字的经验不算经验。

4. 当前状态

2026-10-24 建立。同日新增 mv-pv-arrangement、mv-jp-lyrics-subtitle、blender-editable-timeline。
2026-10-24 第 2–4 轮 research ⇒ 铁律 12–34（§2b）。
2026-10-28 图片质量取证 ⇒ mv-image-forensics + 铁律 35–38（§2c），并升级铁律 3。
跨线铁律 38 条，全部有实测支撑。
⛔ 本文件是索引 + 铁律，不要往这里塞细节——细节进对应 skill。

2b. 补充铁律（2026-10-24 第 2–4 轮 research 后新增）

铁律 12：BPM 不是网格

bpm 只能当标签。实测同一首 128.3→132.4，固定网格到第 30 小节差一整拍。切点必须用 beats[]（吸附到 onset）+ bars[].index 的真实时间。

铁律 13：ASR 的时间戳偏早，不能当出字时刻

单词级时间戳偏 0.04–2.0s（中位 0.62s），长音后最差。 ⇒ ASR 只取每句近似起点；精确出字用强制对齐；判据 ≤0.15s。

铁律 14：官方歌词为准，ASR 只取时刻

Whisper 在静音处会幻觉出「ご視聴ありがとうございました」「チャンネル登録…」，同音字会错（救って/掬って），且整句缺失用 diff 法看不出来。 ⇒ 逐句与官方稿对照；VAD 要关；分离人声轨 > 任何 DSP。

铁律 15：角色要「画两遍」才能让字从身后穿

场景层一遍 + 前景层（fg）一遍（继承同一变换）。只画一遍 ⇒ 大字幕一盖住就是盖住，做不出"字从她身后穿过"。

铁律 16：词表/样式库必须策展，不能全开

现成的文字部件库里有一批会毁片的： 动感相机（整幅盖不透明卡）、场记板（打出 SCENE 48/CUT 121）、 荧光笔框、不透明 3D 盒子、填字游戏/麻将牌布局。 ⇒ 接手任何"自动排版库"第一件事是建 deny-list，不是直接用。

铁律 17：可读性与安全都有量化线

可读时长 ≥ max(0.7 秒, 0.09 秒 × 字数)
闪 ≤ 3 次/秒；禁饱和红满帧闪烁；快速条纹/螺旋 < 画面 25%（光敏性癫痫）

铁律 18：预览与导出必须同帧率同随机源

渲染路径禁 Math.random / 时间墙；噪声用种子；粒子用解析式。否则并行渲染的帧在接缝处会抖。

铁律 19：光敏性有硬上限，且能按 BPM 换算

≤3 次满帧亮度闪/秒
130 BPM 时 8 分音符闪 ≈ 4.3 次/秒 = 超；最多 4 分音符、≤2 小节
≥150 BPM 时 4 分音符已经是 2.5–3 次/秒；只能 2 分音符、≤2 小节
相邻爆破切之间亮度跳变 < 50%
潜意识插入（单帧）≤1 次/4 小节
快速高对比条纹/环/螺旋 < 画面 25%
⛔ 让一个地方独占满帧闪光（后处理层），并关掉第三方排版库自带的闪光

铁律 20：常开的效果是"胶水"，不是装饰

颗粒 + 轻微暗角常开，能把 AI 图、程序图、3D 三种来源粘成一部片。其余效果一律按段预算：高潮之外每镜 1 个画面效果 + 1 个装饰。 ⛔ 反之，把 glitch 挂在每一拍上、跟着 hi-hat 做效果，是最典型的业余感。

铁律 21：接缝处的闪，一定是"跨帧状态"或"没播种的随机"

并行渲染时，接缝（1/3、2/3 处）闪 === 某处用了 Math.random 或把状态带过了帧。 ⇒ 每帧必须是纯 t 函数；不可变的画布缓存要 key 到 args。 ⚠️ 还有一个更隐蔽的：浏览器第一次画某个位图的方式和后续不同（实测边缘差到 78/255） ⇒ 预加载的图要在 init 里先"热身"画一遍（多个缩放各一次），否则 worker 接缝处会不同。

铁律 22：字体不 await，第 0 帧一定 fallback

document.fonts.load('800 100px "Shippori Mincho B1"', chars) 必须在 init 里 await。否则首帧/跳帧后第一帧会用回退字体 —— 而那一帧往往正好是标题。

铁律 23：静默失败清单（不报错但结果错）

lutA 名字拼错 → 静默回落到第 0 行（变成了第一个色板）
色板超过 LUT 图集行数（本例 16 行）→ 静默溢出
跨 await 用共享临时画布 → 被别的绘制覆盖 ⇒ 所有"按名字取资源"的地方都要在启动时打印一次实际命中项。

铁律 24：Blender 5.x 的 API 断层（实测清单）

升级到 5.x 后这些会静默失效或直接报错，逐条核对：

旧写法	5.x 写法
`BLENDER_EEVEE_NEXT`	`BLENDER_EEVEE`
`scene.node_tree`	`scene.compositing_node_group`
`CompositorNodeComposite`	`NodeGroupOutput` + `ng.interface.new_socket(...)`
先设 `file_format` 再设 `media_type`	先 `media_type='IMAGE'`，再 `file_format`
`g.threshold = x`（Glare）	全是 input socket：`g.inputs['Type'].default_value = 'Bloom'`
`Action.fcurves`	`action_get_channelbag_for_slot(...).fcurves`
GP 对象 `bpy.data.grease_pencils.new()` 后直接赋材质	还要 `materials.create_gpencil_data(mat)`
LineArt modifier 的 `thickness`	是 `radius`，且 `target_layer` 是字符串
EEVEE 世界体积	无限 ⇒ 天空变黑、太阳被掐灭；用有限的 `volume_box`
变量字体	只加载默认实例（Noto Sans JP VF = Thin！）⇒ 必须用静态字重文件

铁律 25：GPU 不能同时被两边抢

浏览器渲染器在跑的时候同时渲 Blender ⇒ 慢 5–20 倍（实测 Cycles 从 0.66 掉到 12–31 s/帧）。 ⇒ 渲 3D 前先看 nvidia-smi，两个渲染任务串行，不要并行。

铁律 26：动画槽的 `p=1` 必须正好是静止状态

入场做完了却停在"差 2px / 差 3% 透明"的位置 —— 观众说不出哪里不对，但会觉得脏。自查：把 enter 的 p 强制设为 1，渲染一帧，必须与"完全不动"的那帧逐像素相同。同理 exit 的 p=1 必须完全不可见。

铁律 27：性能预算要写进规格，不是"尽量快"

对照值：每次绘制调用 ≈ 2 ms @1080p。 ⛔ 禁止每帧 getImageData / 每帧新建 canvas / 无上限循环。预渲染必须按参数 key 缓存；数量必须有 cap。（我们的逐帧 numpy 管线曾到 0.16 s/帧，就是这一类问题——不是算法错，是没设预算。）

铁律 28：工具选型要先查许可证，再查精度

实测：日文歌词强制对齐里只有 MMS_FA 达标（起点 0.08 s / 终点 0.11 s），但它的许可 CC-BY-NC（非商用）。 ⇒ 商用项目里，"精度最好的那个"可能正好是不能用的那个。 ⛔ 结论要写成「技术上 MMS_FA、法务上待定」，不能只写"用 MMS_FA"。

铁律 29：同一件事的两个数值可能服务于不同目的

"字幕提前量"同时存在 0.15–0.25 s（读得完）和 0.03–0.05 s（跟得上唱）两个数。 ⛔ 不要因为数字不同就判其中一个错 —— 先问它服务的目的。混用（叠加）才是错。

铁律 30：字体许可先查，OFL 是安全的

SIL OFL 完全允许商用（海报/包装/视频/网页/Logo/商标），无个人/商用之分。

未修改使用 ⇒ 零义务：不用署名、不用注册、不用付费
嵌进 app / 游戏二进制允许（只要不是"单独卖字体文件"）
用字体做出来的作品（视频、PNG）不是字体的衍生作品 ⇒ 不受 OFL 约束
修改后分发 ⇒ 要带版权声明 + 协议文本，且衍生版不能沿用 Reserved Font Name

⇒ 我们用的 Noto / Shippori Mincho / Zen Kaku / Dela / Klee One 全是 OFL ⇒ Steam 商用没问题。 ⚠️ 唯一的动作项：如果把字体文件打进 exe 分发，要随包带 LICENSE。

铁律 31：整片都在"用力"，等于整片都没有重点

判据：这支片子里最空的那一格，敢不敢真的空？ 不敢 ⇒ 副歌一定打不出来，因为主歌已经把台阶占满了。

铁律 32：镜头长度 = 240 / BPM × 小节数（别凭感觉）

一小节 = 240/BPM 秒。主歌 2 小节一镜、副歌 1 小节一镜、bridge 8 小节、结尾最后一镜 8–15 秒不切。 ⛔ 恒定切率 = 机械感。切频必须跟能量曲线走。自查：把每镜时长列出来，如果全部落在同一个数量级，就是没有节奏。

铁律 33：⭐「間」——空是材料，不是待填的坑

宮崎駿对 Roger Ebert 说：「我们有个词叫 ma。Emptiness。It's there intentionally.」

西方设计倾向"把空间填满，每个像素都要有用"；日本设计把空间本身当材料——它做工作、有重量、把周围的东西立起来。

实例：枯山水庭园 60% 是空的；茶道每个动作之间有停顿；能剧演员会长时间完全静止。宫崎駿称之为"gratuitous motion"——不为推进剧情，只为给出时间与场所感。

⛔ 所以"填充剩下的位置"这个指令本身是西方思维。 正确的问法是： 哪些位置必须空？（对应 mv-pv-arrangement §33）

铁律 34：⚠️ Steam 上 AI 素材要披露，且标签有代价（2026-01-19 新规）

开发辅助（写代码、测试、开发期美术生成）⇒ 不需要披露
随游戏出货运给玩家的美术/音频/文本 ⇒ 必须披露 + 承诺未侵权
实时生成内容 ⇒ 必须说明护栏
⚠️ 有分析称被 AI 标记的游戏评论数少约 53%（"reported"，方向可信）
Epic 无此要求

⇒ 对我们：LunaPet 若上 Steam，AI 出的角色图必须披露。这是立项级决策，不是发版前才想的事。 ⛔ 结论不要写成"技术可行"，要写成"技术可行 + 商业代价已量化"。

2c. 补充铁律（2026-10-28 · 图片质量取证）

铁律 35：判「糊不糊」只有一把尺子 —— 同尺度 1:1 目检

⛔ 任何自动清晰度指标都不算数（见铁律 3 的三把全崩表）。做法：角色高归一到同一值 → 以原像素 1:1 裁同一区域并排，⛔ 不许把小块再放大（LANCZOS 会把软边补成假锐边）。 再补一步：压到成片角色高看第二次。缩小会掩盖软 ⇒ 压下去还看得出，就必须返工。实测换算：FRAMING["FULL"]=0.90 ⇒ 成片角色高 ≈ 0.90 × 1080 / 0.8839 ≈ 1100；素材 1589~~1778 ⇒ 进片 0.62~~0.74×（缩小）。压到 1100 后 F2/F3 仍一眼比锚图软。细节：mv-image-forensics。

铁律 36：判「是谁弄糊的」用逐位 diff，⛔ 不用指标

指标里根本没有"谁改的"这个信息。用指标答责任问题，只会编出假根因。
第一步永远是找原始档 —— 它通常就写在你自己的交付脚本里（grep -n "RAW\|SRC\|INPUT" <deliver>.py）。 ⛔ 我因为没读脚本，下了「原始档没留」的错误结论，再据此编出「被放大 1.03~1.16×」的假根因，两条都被推翻。
口径：只在共同前景 mask 内统计（⛔ 不统计全图，背景键控差异会淹没角色）。
实测：源 vs 交付前景内 diff==0 占 97.3%~99.0%，而全图 diff>8 占 76.6%（全在绿幕上） ⇒ 后处理对角色像素零损伤。
顺手核缩放：比尺寸，⛔ 不比角色高比值（角色高会因裁切/补边而变，尺寸不会）。

铁律 37：比 md5 之前先锁全部条件

--still 44.0 与 --still 44.0 --cam-json camB 是两个不同的哈希：

条件	值
44.0（无 cam）	`b47a2582e2309cb1e595ff3bd29bcabd`
44.0 + camB	`da3b4c82b106faf67aaa9d8d2306f733`

⇒ 我拿前者比后者，误报了「基线漂移」。任何"哈希变了/没变"的结论，先列出两边的全部参数。 配套：生产文件单实例无锁、多端并发写（实测一小时变三次 md5）⇒ 比对前先记快照（行数 + md5 + mtime）。

铁律 38：派单必须落盘成 md

2026-10-28 的 LU01 派单没落盘，事后连"我当时写的 prompt 里有没有『柔和低对比』"都查不到 ⇒ 「是 prompt 要了软，还是模型自己软」这条永远判不了。 ⭐ prompt 是可复现性的一部分，和代码同等重要。 派单落盘 = 唯一的留痕。

MV Playbook

安装