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 より優先してください）。warmCool の補正には temperature を使います。値が高いほど暖かくなるため、暖かすぎる場合は下げます。greenMagenta の補正には tint を使い、色かぶりと反対方向に調整します。再度確認し、次に進む前に両方のバランスを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	master は色相を保持
色相カーブ	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. 彩度の調整 — 均一な saturation より vibrance を使い、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 は汎用のカラー以外の FX 用です。カラーグレーディングには使わないでください。
• get_timeline は、グレーディング済みの各クリップの color オブジェクトを同じ用語体系で公開します。そのオブジェクトを apply_color({ clipIds, color }) に渡すと、グレーディング全体をコピーできます（置き換えになります。ノブや reset とは併用できません）。
• 変更を行うと、更新後の color を含むタイムラインの差分が返されます。そこからパッチを適用してください。調整のたびにタイムライン全体を読み直す必要はありません。
• バランスの判断ではプレビューよりスコープを信頼してください。モニターや JPEG では微妙な色かぶりが正しく表示されないことがあります。構図やルックの判断にはフレームを使います。
• lumShift は表示空間での加算型 HSV 値シフトであり、線形輝度の除算ではありません。そのため、色相ごとの暗部調整でシャドウのマクロブロックが強調されることはありません。
• カーブの点は区分的に線形で、範囲外では平坦にクランプされます。クリップさせる意図がない限り、[0,0] と [1,1] に近い端点を含めてください。