视频调色（评估 → 校正 → 风格化 → 选择 → 生成并应用 LUT）

从零开始以代码方式编写调色方案，在真实素材上生成若干个明确命名的 风格化效果（looks），再通过人工显式选择或交由代理（agent）判断来选定其一，最后烘焙出一个便携式的 .cube LUT 并将其完整应用于整段视频。不使用任何预设包（preset packs）。

核心理念 —— 先校正，再风格化。 每一种风格均由 校正基础层 + 创意叠加层 构成：

• 校正基础层 使画面保持 真实性：对平面 LOG/HLG 素材，即完成 log→Rec.709 转换；对已为 Rec.709 的素材，则执行白平衡中性化 + 曝光调整 + 轻度对比度增强。所有风格共享此基础层，因此“中性”始终具有明确意义，各风格差异仅体现于 创作意图。
• 创意叠加层 是叠加在基础层之上的风格部分（如暖调 / 冷调 / 青橙配色 / 饱满有力 / 褪色感等）。

肤色是质量基准线。 对人物（尤其是深色肤色者），teal_orange 和 cool_desat 常导致肤色偏绿/灰。务必首先在人脸区域评估每种风格；保留中间调的暖感，将色调倾向推至阴影/高光/背景区域；优先使用 vibrance 而非原始 saturation。切勿将白平衡完全拉至中性，否则肤色会失去生气。

依赖项：PATH 中需存在 ffmpeg/ffprobe，Python 环境需安装 numpy + Pillow。

契约规范（Contract）

• 每种风格 = 基础层 + 创意层；所有风格共用同一基础层。
• 所有风格均渲染于 同一张 具代表性的帧上（确保公平、可控的横向对比），带标签且为全分辨率输出。
• 最终全片应用时必须使用 -c:a copy（音频永不重编码 → 音画同步完全一致），并保持源文件的 时长、帧率、分辨率 不变。
• 交付前须完成全部风格选择流程。当用户明确要求自行选择时，启用 human 模式；当用户委托决策或请求全自动运行时，则启用 agent 模式且不暂停。两种模式下，均须将选择依据持久化写入计划文件（durable plan）。

项目协议工作流

将持久化决策存于 work/color-grade/grade-plan.json：

{
  "schema_version": 1,
  "target": "base-video",
  "base": "eq=contrast=1.05",
  "looks": [{"name": "clean", "chain": "null"}],
  "selected_look": "clean",
  "selection_mode": "agent",
  "selection_rationale": "Neutral correction preserves natural skin and source lighting.",
  "selected_lut": "../../final/selected-color-look.cube",
  "evidence_refs": ["media:source"]
}

默认使用 base-video，以避免内容卡片与字幕被重新着色。composite 仅在明确需要对已合成像素进行调色时才有效。读取共享的 work/understand/media.json 及视觉证据。生成 review/02-color-grade/choose-color-look.jpg 和 review/02-color-grade/skin-tone-check.jpg；可选生成短片 selected-look-preview.mp4。将最终决策及依据记录于 review/02-color-grade/selected-look.md。

在用户做出显式选择后，将 selection_mode 设为 human；当用户委托决策或要求无中断流程时，则设为 agent，并以肤色还原度、高光保留能力、白平衡中性为首要考量进行保守选择。始终填写非空的 selection_rationale；agent 模式下不得暂停。

将选定风格烘焙为 final/selected-color-look.cube。该 LUT 一旦交付，须在调色计划中设置 selected_lut 字段，以便共享渲染器精确加载该文件。已烘焙的全风格 LUT 已内含校正基础层；渲染器仅需应用 lut3d 滤镜，**不可**再叠加额外的 base 层（即禁止 base + lut3d）。

在 based_on 字段中精确记录本次操作所依赖的输入版本；当计划或选定输入发生变更时，递增其整型 revision 字段；仅当所有审查文件（review files）均已完备后，方可将操作检查状态设为 pass；并提交完整的协议字段：

{
"target": {"sequence": "main", "scope": "base-video"},
"effects": {
  "changes_timeline": false,
  "changes_geometry": false,
  "changes_video_pixels": true,
  "changes_audio": false,
  "adds_track": null
},
"check": {
  "status": "pass",
  "report": "../review/02-color-grade/selected-look.md"
},
"render": {
  "kind": "video-filter",
  "target": "base-video",
  "plan": "color-grade/grade-plan.json"
}
}

共享渲染器将验证 selected_look 是否存在，确保在时间线变换之后、图层叠加之前应用调色，并对最终视频仅编码一次：

python skills/video-understand/scripts/build_render_plan.py .
python skills/video-understand/scripts/render_project.py work/render/render-plan.json

独立兼容性输入

• 源视频文件。
• looks.json 文件（含 base 及命名的 looks）；建议从 looks.example.json 启动，并根据 assess.py 的报告 重新调优 base。

所有现有脚本继续支持旧版 looks.json。同时 gradelib.load_spec() 也支持标准格式的 grade-plan.json，因此样张生成（contact-sheet）、片段裁剪（clip）、LUT 烘焙及独立应用（standalone apply）等命令在迁移期间仍保持兼容。

looks.json 结构定义

{
  "base": "<校正基础层：log→Rec.709 转换；或普通素材的 WB+曝光+对比度调整>",
  "looks": [
    { "name": "clean_neutral", "label": "1 · CLEAN NEUTRAL", "desc": "仅校正", "chain": "eq=contrast=1.02" },
    { "name": "teal_orange",   "label": "4 · TEAL & ORANGE", "desc": "电影感",      "chain": "colorbalance=...,eq=..." }
    // 单个风格的完整 ffmpeg 滤镜链 = base + "," + chain。若设 "prepend_base": false，则 chain 将独立使用。
  ]
}

工作流

1. 评估 —— 绝不盲目调色。

   python scripts/assess.py SOURCE.mp4 --out work/
   

   报告素材是否为 LOG 或 Rec.709 格式、白平衡偏色情况（signalstats U/V 值 vs 128）、亮度（Y 值），选取一张代表性帧（work/assess/frame.png），并建议基础层调优方向。据此重新调优 looks.json 中的 base（例如：检测到暖偏色 → 加入少量蓝色补偿；检测为 LOG → 将 log→709 转换写入 base）。

   • 代表性帧按中位亮度（median luma）选取，而非基于人脸检测。 对单镜头人像口播类素材，通常能落在合适的人脸帧上；但在 B-roll 占比高或多镜头素材中，可能选中无人脸的帧 — 此时 face_skin_check.png 将失效（而肤色正是质量基准）。可通过 --frame-time SECONDS 强制指定已知含人脸的时间点。
   • 白平衡/曝光统计值来源于 时长约为 10 秒、位于总时长 10% 处的 signalstats 分析窗口 —— 适用于光照恒定场景；若素材光照变化明显，请使用 --win-start SECONDS / --win-dur SECONDS 手动调整窗口位置与时长。

2. 渲染风格样张用于选择。

   python scripts/render_looks.py work/assess/frame.png looks.json --out work/looks
   

   生成 work/looks/looks_compare.png（原始帧 + 所有风格，带标签、全分辨率）和 face_skin_check.png（局部放大肤色条）。请务必同时查看这两张图。 肤色是唯一基准线 —— 任何导致肤色发灰/发绿的风格均需重新调优或剔除，然后重新渲染。若主体偏离画面中心？添加参数 --face-crop W:H:X:Y。将这些 PNG 视为中间工作产物；经确认后发布的审查副本应为 review/02-color-grade/choose-color-look.jpg 和 review/02-color-grade/skin-tone-check.jpg。

3. （可选） 动态预览：针对排名前 2–3 的风格生成带音频的运动片段：

   python scripts/make_clips.py SOURCE.mp4 looks.json --out work/clips 
     --pick clean_neutral,warm_filmic,teal_orange --with-original --ss 148 --t 8
   

4. 选定一种风格。 展示样张图，仅当用户明确要求自行选择时才等待；其余情况在 agent 模式下自动完成选择并继续流程，无需暂停。交付前须完成 selected_look、selection_mode 和 selection_rationale 的填写。

5. 选定后 —— 烘焙 LUT 并全片应用。

   python scripts/bake_lut.py looks.json --name CHOSEN 
     --out final/selected-color-look.cube --verify-frame work/assess/frame.png
   python scripts/apply_grade.py SOURCE.mp4 --looks looks.json --name CHOSEN --out out/graded.mp4
   #   或直接应用已交付的 LUT：--lut final/selected-color-look.cube
   

   apply_grade.py 将校验时长与音频是否保持不变，打印白平衡偏移量（U/V 向 128 的偏移），并输出一帧采样图像供目视核查。

   • 应用过程仅对视频重编码一次（有损）；音频始终使用 -c:a copy。 画质与耗时由 --crf（默认 18）和 --preset（默认 slow）控制。slow 对于小/短片适用，但对 1080p/4K、时长一小时的素材而言，将带来显著且无声的时间开销 —— 发布交付时请降级为 --preset medium（快速预览可用 veryfast），仅最终成片使用 slow。
   • 确保交付视频与交付 LUT 完全匹配： 滤镜链（--name）与烘焙生成的 33³ .cube（--lut）在陡峭曲线区域可能存在最多约 5/255 的偏差（bake_lut.py 会报告该 max|d| 值）。多数场景下不可见，但若你 需交付 .cube 文件 并要求渲染视频与其严格一致，请务必使用 --lut final/selected-color-look.cube 进行应用，而非 --name。

设计说明 / 注意事项（Design notes / gotchas）

• 先对 CLEAN 版本调色，再将图层叠加于已调色的画面上。 若必须对已烧录字幕/卡片的视频进行调色，请 切勿信任 assess.py：其白平衡/曝光统计与代表性帧选取均会被图形元素干扰（顶部/底部暗边会拉低 Y 值，明亮字幕文本或青色点缀会扭曲 U/V，代表性帧也可能落在字幕密集帧上）—— 此时你校正的将是叠加层，而非原始画面。应复用在 CLEAN 版本上调优过的 base，并接受调色对叠加层的染色效应，因此仅可选用细微/校正型风格（如 clean_neutral）；teal_orange/vintage_faded 将明显改变文字/点缀色。
• 一种风格/LUT 覆盖所有关联片段。 选定风格后，请在所有相关片段（例如 CLEAN 版本 + 已叠加字幕版本）中复用同一份 looks.json / .cube —— 切勿 对每个片段单独重复两阶段选择流程。
• 先校正，再风格化。 base 是对 S-Log3→Rec.709 标准转换步骤的泛化表达。对普通素材，base 即白平衡+曝光+对比度；对 LOG 素材，则应将转换逻辑置于其中。
• 肤色优先。 teal_orange/cool_desat 在深色肤色主体上最易引发问题 —— 保持中间调暖感，将色调倾向施加于阴影/高光/背景，善用 vibrance；切勿将 U/V 完全中性化。
• 标签（Labels）由 PIL 生成 PNG 后经 ffmpeg 叠加 —— 绝不使用 drawtext。 Windows 下 drawtext 的 fontfile 路径（含盘符冒号）不可靠。字体配置统一在 gradelib.py 顶部设定。
• 含盘符路径（drive-colon paths）会导致 ffmpeg filtergraph 中路径型选项（如 lut3d、metadata=print:file=）失效。 所有脚本均以目标文件所在目录为当前工作路径（cwd），并在 filter 中仅引用 文件名（basename）。新增任何路径型 filter 时，请延续此模式。
• 输出均落于你传入的 --out 目录下（持久化存储），而非系统临时目录。
• 人脸/肤色条采用固定居中上中部裁剪，不依赖人脸检测。 若主体未大致居中，请向 render_looks.py 传入 --face-crop W:H:X:Y，否则肤色条将显示错误区域。
• apply_grade.py 的校验采样帧位于总时长的 20% —— 与风格选择所用帧为 不同 帧。若该 20% 时间点无人脸，请手动另选一帧观察肤色（或在 assess.py 中使用 --frame-time 确保选择帧为已知含人脸时刻）。
• LUT 烘焙是精确的，因本流程中所有滤镜均为逐像素点运算（point op）：bake_lut.py 将 33³ 单位网格（identity grid）送入实际滤镜链，并自我校验（mean|d| 应远低于 1/255；数级 max|d| 仅为插值误差）。
• 交付前必须完成选择，且始终如此。 人工选择与代理选择均属有效，但计划文件必须如实记录发生的是哪一种，以及原因。