scenario-video-color-grade

Scenario 视频调色

概述

这里的每项调色都是由 Agent 编写、测量和调校的数学运算；不会有生成式模型处理像素。逐像素颜色运算会烘焙到 33³ .cube LUT 中，再由 ffmpeg 应用。空间运算（重新布光、键控或蒙版选择性色彩）会在 LUT 处理前，使用 numpy 对每一帧分别执行。结果精确、每帧完全一致，且可编辑：LUT 可载入 Premiere、After Effects 和 Resolve。画面构图、运动和帧数均会保留，因此无缝循环仍能保持无缝。

Scenario 提供两个预设 LUT 工具模型，以及实现精准选择性色彩的分割蒙版。新素材不在适用范围内。连接和核心循环：scenario 技能。在长视频片段上运行 LUT 工具模型（费用随片段长度变化，wait=false）：scenario-video-editing。为短片配乐：scenario-audio。如果可用技能中缺少这里提到的同系列技能，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；在无人值守的情况下，请根据工具架构继续操作，并标明这一缺失。

脚本在本地使用 python3 运行，需要 ffmpeg、numpy、scipy 和 Pillow。不带参数运行时，每个脚本都会打印用法；如果没有 --force，则会拒绝覆盖输出文件，且绝不会调用 Scenario。以下路径均相对于此技能文件夹。

两种方案：使用 Scenario 预设，或编写自己的配方

Scenario 的 3D Color LUT 工具模型会以一定不透明度（lutIntensity）应用一个预设（编写时约有 150 种，参数为 lutStyle）：胶片模拟、常见相机 Log 格式转 Rec.709、印片胶片转换，以及创意风格。model_scenario-postprocessing-lut 用于为图像调色，model_scenario-postprocessing-lut-video 用于为视频调色。两个 ID 固定：Scenario 为该操作各提供一个确定性工具，因此发现工具只会重新推导出同一工具。视频工具会保留帧数和时间信息。

以下情况优先使用预设：

• 素材是 Log 格式。 选择适用于相机 Log 格式的预设。它支持的相机远多于本地 decode_log 运算（该运算仅处理 S-Log3）。
• 需要预设风格（胶片类型或印片模拟），或者调色必须在 Scenario 内完成：没有本地 ffmpeg 或 Python、需要在 Scenario 工作流中使用，或要处理大量图像。

如果需要调校或创造风格、进行位置相关处理（蒙版、重新布光、暗角、颗粒、晕光）、匹配参考图像、交付 .cube 文件，或用于短片，则应编写配方。工具模型只能使用自身的预设，不能使用自定义 .cube。两种方案可以串联：先在 Scenario 中转换 Log，再用移除了 decode_log 的配方为其 Rec.709 输出调色。

运行预设：

1. 对两个 ID 都调用 model_schema_get，并查看 lutStyle 的允许值；切勿猜测。仅选择视频工具也列出的值。
2. 用图像工具在一张静帧上测试两三个预设。预设名称并未说明其适用的输入，因此应将相似预设并排比较（例如同一款胶片的两种印片模拟）。
3. 使用 upload_asset 上传片段，通过 model_run 和 dry_run=true 估算费用，运行选定的预设，调用 jobs_wait，然后调用 asset_download。
4. 使用 ffprobe 检查结果：编写时，视频工具可能会返回 MPEG-4 Part 2。使用以下命令重新编码，以供 Web 使用： ffmpeg -i in.mp4 -c:v libx264 -crf 18 -pix_fmt yuv420p -movflags +faststart -c:a copy out.mp4。

快速参考

• render_looks.py：将外观应用到视频（每种外观生成一个 mp4，复制音频）或单帧（生成 PNG 静帧和带标签的 grid.jpg），并写入 luts/<key>.cube。
• inspect_frame.py：grid（像素坐标）、sample（矩形区域的色相、饱和度和亮度百分位数）、key（显示选择性键保留内容的红色叠加层，并标注色块大小）。
• match.py：测量参考图像，以供 match 操作使用；该操作是在 CIE Lab 中进行的 Reinhard 转换。
• showreel.py：展示每种外观的影片，带有标注名称的面板、同一连续片段上的擦除转场、网格结尾，以及可选的片尾卡和音乐。
• grade.py、spatial.py、media.py：色彩操作和 LUT 写入器、重新打光和键控、ffmpeg I/O。上述脚本会导入它们。
• looks_library.json：21 种经过调校的起始外观，包括昼夜转换、带键控的黑白效果、参考匹配和四种重新打光预设。
• looks.json：12 种经过调校的外观，包括基于蒙版的黑白效果、一种彩色效果，以及一种需要先运行 match.py 的参考匹配。
• ops.md、looks.md、keying.md、relight.md：所有操作、库中每种外观的构建方式、键控与蒙版、重新打光。

步骤

1. 查看素材。 用 ffprobe 检查素材，并从不同时间点提取三四帧。记下素材是 log（发灰、平淡）、正常，还是已经调过色。这些风格是针对柔和、略微低饱和的素材调校的；如果素材对比度较强，就把饱和度和对比度各降低约三分之一。记下光线方向和关键物体的颜色。
2. 设置 looks.json。 将库或示例集复制到片段旁边，然后保留、重命名、添加或删除风格。一个风格包含 name 和 settings（reel 上的两行标签），以及可选的 relight、可选的 selective、ops（烘焙进 LUT），还有可选的 vignette、grain 和 halation。它们按此顺序应用。键名决定输出的排序；以下划线 _ 开头的键是备注。
3. 先测试静帧，再处理视频。 python3 scripts/render_looks.py clip.mp4 --looks looks.json --out still_test --frame 40，然后打开 grid.jpg。检查每种风格是否都与原素材不同、没有发生裁切或让肤色变橙，且除了风格化效果外，肤色看起来都自然。在这里反复调整：静帧只需几秒，渲染则要几分钟。对动态片段测试两帧。
4. 键控风格：先测量，再预览。 使用 inspect_frame.py grid 获取全分辨率坐标（静帧测试的 grid.jpg 中的图块已缩小），在物体及与其颜色相近的区域（肤色、嘴唇、地面）上运行 sample，然后运行 key ... --frame 10 90 160 查看叠加效果：灰色画面上的红色标出保留的区域。用于区分的维度往往是亮度或饱和度，而不是色相。如需精确结果，请使用物体遮罩（参见已完成的示例）。
5. Relight 使用 0.3 到 1 档曝光，并从已有高光的一侧打光。它会改变光线特性，但不会改变几何形状或投射阴影：请向用户说明这一点。
6. 匹配参考效果，使用 python3 scripts/match.py clip.mp4 reference.jpg match/reference.json [--crop w:h:x:y]，然后使用 {"op": "match", "stats": "match/reference.json"}。每当素材发生变化时，都要重新测量。在一天中的另一个时段匹配同类场景，可以逼真地改变时段效果。
7. 渲染，使用 python3 scripts/render_looks.py clip.mp4 --looks looks.json --out renders [--only k1,k2]。
   • 纯色彩风格直接通过 ffmpeg 处理。
   • 在作者制作时，relight 和键控风格合计每个 1080p 帧约需 1 到 2 秒，因此长片段请在后台运行。
   • 如果某种风格缺少遮罩或匹配统计数据，就会跳过并显示提示。
   • 确认每个渲染的帧数与源素材相同，并逐帧检查键控和 relight 渲染是否有闪烁、肤色问题或边缘问题。
8. Reel（可选）： python3 scripts/showreel.py --renders renders --looks looks.json --source 00_ungraded --out reel.mp4 --order k1,k2 --music track.mp3。 将戏剧化风格（双色调、黑色电影）放在第二或第三位，并优先选择循环衔接自然的片段。Reel 会将音乐响度标准化到约 -18 LUFS。默认情况下，reel 不带品牌标识。只有用户要求时才添加片尾卡，并使用用户自己的 --credit 文本或 --logo（白色透明 PNG）。
9. 交付渲染文件、renders/luts/*.cube（在 Premiere 中使用：Lumetri、Creative、Look）、网格图和 reel。请在风格名称中注明空间部分：单独的 LUT 只有颜色，因此编辑人员还需要遮罩。

示例：黑白效果中保留一种颜色

调色在本地完成；只有遮罩来自 Scenario，而且遮罩任务绝不会更改任何像素。

1. 根据用户的原话调用 recommend，例如“在视频的每一帧中分割同一个物体”。选择一个视频分割模型，调用 model_schema_get 获取其架构，并根据架构构建参数。
2. 使用 upload_asset 上传要调色的确切片段。调用 model_run 并设置 dry_run=true 估价，然后针对每个物体分别运行一次，文本提示词使用简短的名词短语（“red leather jacket”“red fuel pump”）。调用 jobs_wait，然后通过 asset_download 将每个遮罩视频下载到 masks/。
3. 在两到三帧全分辨率画面上叠加每个遮罩的轮廓。遮罩的帧数必须与片段一致。
4. 为效果添加一个 selective 块。带有 key 的遮罩条目只会保留该物体内部键控的颜色，因此红色油泵的白色面板仍会保持灰色：

"selective": {
  "masks": [{"path": "masks/jacket.mp4"},
            {"path": "masks/pump.mp4", "key": {"center": 11, "width": 18, "min_sat": 0.28, "max_val": 0.62}}],
  "weights": [0.3, 0.55, 0.15], "sat": 1.7, "val": 1.05
}

5. 先测试静帧，再渲染。要替换颜色（从红色换成金色），在同一个块中添加 "shift": 34。

在创作时，为一个 8 秒循环制作十二种效果总共需要 112 CU：两个遮罩和视频的音乐。调色本身不产生费用。

常见错误

• 编写预设已有的配方。 日志转换和胶片模拟属于 lutStyle 预设：先检查它们。
• 未经检查就交付视频 LUT 工具的输出。 将 MPEG-4 Part 2 重新编码为适用于 Web 的 H.264。
• 只用颜色键来保留一种颜色。 肤色、嘴唇和暖色背景与物体颜色相近，边缘处会带上颜色。物体靠近皮肤时，请结合遮罩和物体内部的颜色键。
• 仅按色相设置颜色键。 反射暖色天空的青绿色汽车几乎没有青绿色像素，而嘴唇与红色夹克的色相相近。通过亮度或饱和度进行区分，设置 min_area，并预览。如果仍有颜色渗漏，请告诉用户需要使用遮罩。
• 使用启发式区域遮罩（“只修改天空”）。 头发、柱子和运动模糊都会造成渗漏。请改用渐变滤镜或参考匹配。
• 将一种素材的调校方案用于另一种素材。 每次使用新素材时都要重新进行静帧测试。
• 将商标用作效果名称。 公共名称中不要使用电影片名和胶片品牌；请使用描述性名称（“Scorched Desert”“Vintage Slide”）。
• 音频略短于视频时使用 -shortest。 ffmpeg 会丢弃最后一帧，导致循环中断。脚本已避免这种情况；在自定义命令中也要保持如此。
• 只做调色。 调色关乎审美：展示网格和短预览，并根据用户指出的内容反复调整。