Color

Grade a clip with wheels, exposure, white balance and tone, and check it with scopes: in the Color workspace, or from an agent with setGrade and fablecut_scopes.

A clip's color grade lives in props.grade on any video, image, svg or adjustment clip (an adjustment layer grades everything below it). It runs on the GPU (WebGL2; CPU fallback) before the clip is composited, in preview and export alike, so it comes before the Filter / color sliders and presets, which still apply on top. In the editor: the Color workspace (top bar) shows scopes beside the program monitor and the Color tab beside the Inspector has the wheels and sliders for the selected clip.

The grade is sparse: only keys that differ from neutral are stored.

keyneutralrangedoes
exposure0−5…5stops, in linear light
temp · tint0−100…100white balance in linear light: temp > 0 warmer, tint > 0 magenta (±100 ≈ ±1 stop per channel)
lift · gamma · gain · offset[0,0,0,0]each −1…1colour wheels, [r, g, b, master]; a channel's amount is its own value + master. offset adds, lift raises blacks keeping white (x + l·(1−x)), gain multiplies (x·(1+g)), gamma bends mids (x^(1/2^γ), > 0 brighter)
contrast · pivot1 · 0.4350…3 · 0.05…0.95log-style contrast pivot·(x/pivot)^c - blacks never crush
blacks shadows midtones highlights whites0−100…100tone bands on luma, darkest → brightest (smooth, overlapping)
lowSoft · highSoft00…100soft rolloff into black / white instead of a hard clip
saturation1000…200around Rec.709 luma
curves-{y?, r?, g?, b?}tone curves, each [[x, y], …] on 0…1 (see Curves below)
hueHue · hueSat · hueLuma · satLuma-[[x, value], …]hue / saturation curves (see Curves below)
layers-up to 8secondaries: grades limited by a qualifier and / or a mask (see Layers below)
ontrue-false bypasses the grade without losing it

Order: exposure + white balance → offset → lift → gain → gamma → contrast → tone bands → rolloff → saturation → curves (luma, then R G B) → hue curves → layers, in order.

Curves. Point lists drawn through a smooth curve that never overshoots (monotone cubic) - at most 24 points each.

keyxvalueneutraldoes
curves.ylevel 0…1level 0…1the diagonalluma curve: brightness only, the colour is kept
curves.r / .g / .blevel 0…1level 0…1the diagonalone channel
hueHuehue 0…360°shift −180…180°0rotate one hue toward another
hueSathue 0…360°factor 0…21saturate / desaturate one hue (0 = grey)
hueLumahue 0…360°−0.5…0.50brighten / darken one hue (scaled by its saturation, so greys never move)
satLumasaturation 0…1−0.5…0.50brighten / darken by how saturated a pixel is

Tone curves get [0, 0] and [1, 1] added when missing, so curves:{y:[[0.25, 0.2], [0.75, 0.8]]} is a gentle S. Hue curves wrap around 360°, and a hue curve with one point is a band: that value at the hue, easing back to neutral 40° either side - hueSat:[[220, 0.6]] mutes blues only. Hues: red 0, yellow 60, green 120, cyan 180, blue 240, magenta 300; skin sits near 20–30. A curve equal to neutral is dropped.

In the editor the Curves section of the Color tab edits them: tabs for Curves (Y / R / G / B) and the four hue curves; click to add a point on the curve, drag to move it, double-click to remove it, Pick then click the monitor to mark that colour's level or hue on the curve (new points snap to the mark), Reset clears the curve shown.

Layers (secondaries). Each layer is a grade of its own - any keys above except layers - mixed into the picture where its matte says: matte = qualifier × mask (either may be left out; with neither, the layer grades the whole frame). Layers run after the primary grade, in order, and each one's qualifier looks at the picture as it reaches that layer.

"layers": [
  { "name": "Skin", "qualifier": { "hue": [25, 40, 20], "sat": [0.15, 0.7, 0.1] },
    "saturation": 90, "hueHue": [[25, -4]] },
  { "name": "Vignette", "mask": { "shape": "ellipse", "x": 0.5, "y": 0.5, "w": 0.8, "h": 0.9, "feather": 0.25, "invert": true },
    "exposure": -0.6 }
]
keydoes
name · ona label; on:false turns the layer off
qualifier.hue[centre°, width°, soft°] - hues within ±width/2 of the centre, easing out over soft; wraps through red. Greys carry no hue, so a hue range leaves them out
qualifier.sat · qualifier.luma[low, high, soft] on 0…1 - saturation (HSV) / Rec.709 luma between low and high
qualifier.invertselect everything else
mask.shapeellipse · rect · poly · bezier (or freehand with a stroke, fitted into a bezier - see Masks)
mask.x · mask.ycentre, as fractions of the clip's picture (0…1, y down)
mask.w · mask.hsize, fractions of the picture's width / height (ellipse, rect)
mask.rotationdegrees, clockwise
mask.feathersoft edge, a fraction of the picture's height (0…0.5), centred on the outline
mask.pointspoly: 3–16 [dx, dy] corners around x, y (fractions of width / height); bezier: 3–24 anchors [dx, dy] or [dx, dy, inX, inY, outX, outY] with curve handles
mask.invertgrade outside the shape
mask.keysanimate it: [{t, x?, y?, w?, h?, rotation?, feather?, ease?}], t in seconds from the clip's start; each param eases between the keys that set it (ease on the arriving key, as for clip keyframes)

Masks live in the clip's own picture, so they follow the clip when it is moved, scaled, rotated, cropped or flipped. On an adjustment layer they are fractions of the canvas.

In the editor the strip under Copy / Paste lists Primary and the layers; + Layer adds one. With a layer picked, the wheels, sliders and curves edit that layer, and three more sections appear: the layer's name, On, Matte (the monitor shows what it selects, white = graded), ↑ ↓ to reorder, Delete; Qualifier - Pick then click a colour in the monitor to select its hue, saturation and luma, then tune the ranges; and Mask - pick a shape and drag it on the monitor (inside moves it, the handles resize it, the knob rotates it, Shift snaps to 15°; on a poly or bezier, Ctrl-click adds a point and double-click removes one), or Draw a free-hand outline on the monitor (it becomes a bezier). ◆ Key keys the shape at the playhead; once it has keys, every change to the shape keys.

Wheel colours. A wheel's r, g, b normally carry no brightness: they are a point on the vectorscope's Cb / Cr plane, so pushing a wheel toward a colour moves the picture's trace toward that colour's target. To tint shadows teal by about 0.03: lift: [-0.034, 0.008, 0.012, 0] (r = 1.5748·Cr, g = −0.1873·Cb − 0.4681·Cr, b = 1.8556·Cb, with Cb = 0.0065, Cr = −0.0216 here). Small values go a long way - ±0.02…0.05 on lift and offset, ±0.05…0.15 on gamma and gain.

Agents set a grade with the patch op setGrade and check it with fablecut_scopes:

Reading the numbers: a normally exposed shot has its median near 0.35–0.5; whitePct above ~1 means clipped highlights (lower highlights / whites, or add highSoft); blackPct above ~2 means crushed shadows. A cast strength above ~0.03 on a scene that should be neutral wants white balance: move temp against the cast (orange / yellow → lower temp; blue / cyan → raise it) and tint against green / magenta, then measure again.

Secondary workflow: grade the whole shot first (primary), then add a layer for the one thing that needs its own correction - e.g. skin: {op:"setGradeLayer", id, layer:"Skin", set:{qualifier:{hue:[25, 40, 20], sat:[0.12, 0.7, 0.1]}, saturation:92}}, then fablecut_scopes {matte:{clip:id, layer:0}} - expect a coverage that matches how much of the frame is skin and a cast near orange (hue ~25–35°). A sky: qualifier:{hue:[210, 50, 25], luma:[0.45, 1, 0.1]} with hueSat:[[210, 1.25]]. A vignette or a relight: a feathered ellipse mask with invert:true and exposure:-0.5, or without invert and exposure:+0.3 on a face; give it keys to follow a move.

Workflow for matching shots: grade the hero shot, measure it, then grade every other shot of the scene until its median and cast land near the hero's. In the editor, Copy / Paste on the Color tab pastes one clip's grade onto every selected clip.