color-grading

按照调色师的顺序进行调色，先看示波器——绝不要直接跳到风格化效果，因为在偏色之上叠加风格化效果，只会把偏色固定下来。每次调用 apply_color 都会在当前调色基础上合并参数（只更改你传入的参数），因此应通过多次调用逐步调整，并在各阶段之间用 inspect_color 验证。取值范围见下方参考表；正文只说明要调整哪个参数，不列具体数值。

工作流

- [ ] 1. inspect_color — read scopes BEFORE touching anything
- [ ] 2. Normalize — exposure + white balance to neutral
- [ ] 3. Primary — black/white points, contrast, saturation
- [ ] 4. Match — pull each shot toward the reference (if matching)
- [ ] 5. Secondary — hue curves for skin/sky/foliage
- [ ] 6. Look — wheels split-tone and/or LUT
- [ ] 7. inspect_color again — confirm scopes moved as intended

1. 先读取。 调用 inspect_color(clipId)。检查 luma.black/luma.white（是否接近 0/1？clipLowPct/clipHighPct 是否标记了黑位压死或高光溢出）、balance.warmCool + balance.greenMagenta（非零表示存在需要中和的偏色）、zones（偏色所在区域），以及 hueHistogram12（第 1–2 个橙色区间 = 肤色，第 6–8 个青色/蓝色区间 = 天空）。

2. 校正。 用 exposure 调整全局亮度（优先于 gamma）。用 temperature 校正 warmCool——数值越高越暖，因此画面太暖时应调低。用 tint 校正 greenMagenta，朝偏色的反方向调整。重新检查：继续之前，两项平衡值都应接近 0。

3. 基础调整。 用 blacks/whites 设置黑白场，用 contrast + highlights/shadows 调整滚降曲线，用 saturation 调整整体饱和度——如果想增强低饱和颜色而不损伤肤色，优先使用 vibrance。

4. 匹配镜头。 先完整调好主镜头，然后对每个其他镜头调用 inspect_color(clipId, reference: <hero>)，读取返回的 gap 及其 hints（例如“比参考镜头更暖 → 降低色温”），应用调整后重复操作，直到 gap 足够小。用数值缩小差距——不要凭目测。

5. 二级调整。 通过 hueCurves.targets 调整特定色相（每个 targetHue 的影响范围约为 ±22°）：hueShift 旋转色相，satScale 降低或增强饱和度，lumShift 调暗或提亮——例如加深天空而不影响肤色。按通道设置的 redCurve/greenCurve/blueCurve 可选择性调整色调：用 blueCurve: [[0,0],[0.7,0.7],[1,0.85]] 压低过曝的天空。

6. 风格化。 用色轮进行分离色调（每个区域设置 *Hue+*Amount，例如青橙色调 = shadowsHue:210,shadowsAmount:0.2 + highsHue:30,highsAmount:0.15）；通过 masterCurve 添加胶片趾部（[[0,0.06],[1,0.95]]）；或叠加 lut:{path,strength}（.cube，绝对路径；会复制到项目存储中；重新混合时只传入 strength 即可）。要模拟特定胶片，请手动构建效果——见下方的 胶片风格。

7. 确认。 再次调用 inspect_color：黑白场接近 0/1，且没有明显溢出；除非有意调色，否则色彩平衡应保持中性；肤色应位于橙色区间。

apply_color 参考

在当前调色基础上合并；reset:true 会恢复为中性状态。必须提供 clipIds（仅限视频/图像）。

分组	参数	范围	说明
色调	exposure / contrast	−3…3 EV / 0.5–1.5	1 = 中性对比度
	highlights shadows blacks whites	−1…1	黑白场与滚降
白平衡	temperature / tint	2000–11000 K / −100…100	数值越高越暖；tint 为正偏绿，为负偏洋红
饱和度	saturation / vibrance	0–2 / −1…1	1 = 中性；vibrance 可保护肤色
色轮（按区域）	shadowsHue/midsHue/highsHue + 对应的 *Amount	0–360° / 0–1	色相偏移 + 强度
	shadowsLum / midsGamma / highsGain	−0.5…0.5 / 0.5–2 / 0.5–1.5	按区域调整亮度
曲线	masterCurve redCurve greenCurve blueCurve	[[x,y],…] 0–1	主曲线可保留色度
色相曲线	hueCurves.targets[] = {targetHue, hueShift, satScale, lumShift}	±30° / 0–2 / ±0.5	选择性范围约为 ±22°
LUT	lut = {path, strength}	strength 0–1	.cube，绝对路径

色相：0 红 · 30 橙/肤色 · 60 黄 · 120 绿 · 180 青 · 210 天蓝 · 240 蓝 · 300 洋红。

inspect_color(clipId | mediaRef, atFrame?, reference?) — clipId 读取片段的已调色效果，mediaRef 读取原始素材。返回示波器数据（luma、meanRGB、zones、saturation、balance、hueHistogram12、colorfulPct）以及帧画面；提供 reference 时，还会返回 gap 和可执行的 hints（这是镜头匹配的核心）。

胶片风格（无需 LUT）

LUT 只是将一组曲线／色轮／饱和度调整固定下来——按以下顺序手动构建即可：

1. 色调曲线（暗部 + 高光）。 最显著的特征：胶片不会呈现纯黑，也不会让白色溢出。抬高 masterCurve 的暗部，并用柔和的中间 S 曲线平滑其高光，例如 [[0,0.04],[0.25,0.22],[0.75,0.82],[1,0.97]]。
2. 通道间串扰。 色相会随亮度变化——这是区分真实仿真与“S 曲线 + 色调”的关键。抬高蓝色暗部并压低其高光 → 青绿色阴影 + 暖色高光（blueCurve: [[0,0.05],[0.5,0.5],[1,0.92]]）；微调绿色中间调，呈现 Fuji 风格。
3. 对色轮进行分离色调（阴影→青绿色，高光→琥珀色）。
4. 雕琢饱和度——优先使用 vibrance 而非单纯的 saturation，再用 hueCurves satScale 降低／增强单个色相的饱和度。
5. 色相旋转——进行小幅度的色相对色相偏移（≤8°）：Kodak 让橙色更暖，Fuji 让绿色偏移。

以下配方是预设好参数的上述方法——应用于已归一化的片段，然后重新运行 inspect_color 并根据镜头微调（降低强度时，将 *Amount 和曲线偏离中性值的程度缩小）。如果用户有实际的 .cube 文件，优先使用 lut:{path,strength:0.85}；这些配方只是近似呈现胶片的特性，并非还原其科学原理。

Kodak 2383 — 好莱坞印片（温暖、高反差；黑位浓郁，青绿色阴影，琥珀色高光）：

{ "contrast": 1.25, "saturation": 1.15, "vibrance": 0.1, "temperature": 6800, "blacks": -0.1, "whites": 0.05,
  "shadowsHue": 195, "shadowsAmount": 0.12, "highsHue": 40, "highsAmount": 0.12, "masterCurve": [[0,0.02],[0.25,0.21],[0.75,0.83],[1,0.98]] }

Kodak 2389 — 低反差印片（干净、中性；胶片式高光渐变，色调变化较少）：

{ "contrast": 1.08, "saturation": 1.03, "temperature": 6550, "blacks": -0.04, "highsHue": 45, "highsAmount": 0.06, "masterCurve": [[0,0.015],[0.3,0.29],[0.7,0.72],[1,0.99]] }

Fuji Eterna / 类似 3513（柔和、绿色粉彩；黑位乳白且抬高）。抬高暗部是其标志——不要将其压平：

{ "contrast": 1.05, "saturation": 0.95, "vibrance": 0.12, "temperature": 6300, "blacks": 0.08, "shadows": 0.1, "highlights": -0.15, "whites": -0.04,
  "midsHue": 120, "midsAmount": 0.08, "shadowsHue": 185, "shadowsAmount": 0.1, "masterCurve": [[0,0.06],[0.25,0.27],[0.8,0.82],[1,0.95]] }

Kodak Portra — 暖调负片（柔和、适合肤色）。−tint + 橙色曲线能修饰肤色——确认增长的是橙色色阶，而不是红色色阶：

{ "contrast": 1.05, "saturation": 1.0, "vibrance": 0.15, "temperature": 6900, "tint": -3, "blacks": 0.06, "highlights": -0.1, "highsHue": 38, "highsAmount": 0.08,
  "hueCurves": { "targets": [ { "targetHue": 30, "satScale": 1.08, "hueShift": -4 } ] } }

漂白旁路（低饱和、高反差、金属质感）。将 saturation 调至 0.4–0.7，以控制强度：

{ "contrast": 1.35, "saturation": 0.55, "temperature": 6300, "tint": 5, "blacks": -0.15, "whites": 0.1, "masterCurve": [[0,0.0],[0.2,0.13],[0.8,0.9],[1,1.0]] }

青橙色调 — 商业大片风格（冷调阴影，暖调肤色）。橙色曲线要保持适度，以免人脸呈现不自然的荧光色：

{ "contrast": 1.2, "saturation": 1.1, "vibrance": 0.15, "shadowsHue": 210, "shadowsAmount": 0.2, "highsHue": 30, "highsAmount": 0.15,
  "hueCurves": { "targets": [ { "targetHue": 30, "satScale": 1.15 } ] } }

复古／褪色（乳白黑位、低饱和、泛黄的暖调旧化效果）。高暗部值是整体风格的关键——黑色永远不会达到 0：

{ "contrast": 0.95, "saturation": 0.8, "temperature": 6700, "tint": 4, "blacks": 0.12, "highlights": -0.1, "masterCurve": [[0,0.1],[0.5,0.52],[1,0.92]] }

注意事项

• apply_color 是调色专用路径，会将 LUT + 曲线 + 色相曲线作为实时可编辑效果应用。apply_effect 用于通用的非色彩特效——不要用它调色。
• get_timeline 会以相同的术语公开每个已调色片段的 color 对象——将该对象传入 apply_color({ clipIds, color }) 即可复制完整调色（会替换现有调色；不能与参数旋钮／reset 同时使用）。
• 修改操作会返回时间线增量（包括更新后的 color）——根据这些结果进行补丁修改；每次微调后无需重新读取整个时间线。
• 判断平衡时应相信示波器范围，而非预览画面——监视器和 JPEG 会掩盖细微偏色；使用画面来判断构图和整体观感。
• lumShift 是显示空间中的加性 HSV 明度偏移，不是线性亮度除法，因此按色相压暗不会放大阴影宏块。
• 曲线点之间采用分段线性插值，超出范围时会平坦钳制——除非有意裁切，否则请在 [0,0]／[1,1] 附近加入端点。