Guides

Colour and grading

Grading with the filter stack, from exposure and curves to lift, gamma and gain, plus legible type over footage and palettes.

Colour in Ymotion is a stack of filters on a layer, applied in order, as in After Effects' Effect Controls. This page covers how the stack works, an order to grade in, what each filter is for, and keeping type readable over a graded shot. There are 42 filters; ymotion_find {"catalogue":"filters"} lists them by group, and ymotion_find {"catalogue":"filters","id":"lift"} gives one filter's amount and knobs with their ranges and defaults.

How the stack works

Every visual layer carries an ordered list of filters, and the order is part of the picture. Neighbouring simple adjustments such as exposure, contrast and saturation combine into one exact pass; the rest, such as curves, grain and blur, each run as a step of their own, in the order you stacked them. So grain placed after a blur stays crisp, and grain placed before it gets softened. Every filter at its resting catalogue defaults leaves the picture exactly as it was. Those defaults are used to open existing rows; a newly requested row has separate authoring defaults. ymotion_find labels the initial amount separately and gives a ready-to-use add call with the initial controls.

A filter only changes the layer it's on. To grade several layers at once, add an adjustment layer above them: its filters apply to everything beneath it.

ymotion_edit {"ops":[{"verb":"addLayer","args":{"trackId":"<track above the footage>","content":{"kind":"adjustment"},"start":0,"duration":4,"name":"Grade"}}]}

Anything on a track above the adjustment layer is left alone, which is usually what you want for titles and captions.

Adding and adjusting filters

addFilter appends a filter to the end of the stack:

ymotion_edit {"label":"grade","ops":[{"verb":"addFilter","args":{"layerId":"<layer id>","id":"lift","amount":1,"params":{"blue":0.05}}},{"verb":"addFilter","args":{"layerId":"<layer id>","id":"gain","amount":1,"params":{"red":0.05,"blue":-0.05}}}]}

The amount is how much of the filter you get: 0 to 1 for most, −1 to 1 for the ones that go both ways, such as exposure, contrast and temperature. Left out, it uses the filter's initial strength: full invert, mono, sepia and curve; full strength for curves, levels and the other filters whose resting strength is 1; neutral 0 for brightness, contrast and other bipolar corrections. Brightness and contrast at 0 deliberately leave the picture alone. A new photo filter has warm orange colour and density 0.25; a new tritone maps black through a warm brown middle to white. Supplied amounts and knobs override these new-row values. Existing saved rows retain their stored controls and old missing-field defaults.

To change one knob afterwards, address the row by its index:

ymotion_edit {"ops":[{"verb":"setParam","args":{"layerId":"<layer id>","what":"filters","index":1,"param":"red","value":0.1}}]}

Every amount and knob is an ordinary property with a path, filters.<index>.amount and filters.<index>.params.<knob>, so a grade can be keyed like anything else. Here the second filter fades in over two seconds:

ymotion_edit {"ops":[{"verb":"keyRamp","args":{"layerId":"<layer id>","path":"filters.1.amount","from":0,"to":1,"opts":{"start":0,"end":2}}}]}

ymotion_read {"what":"properties","layerId":"<layer id>"} lists every filter row's paths, with the values that have been set.

The rest of the row verbs work like After Effects' Effect Controls:

moveFilter reorders, and removeFilterAt removes one row by index. Keys move with their row.
setEffectEnabled with "what":"filters" is the fx switch: off keeps the settings and keys, so you can compare with and without.
duplicateEffect copies a row with its keys; resetEffect restores its static amount and knobs to the new-row defaults, preserving its place, switch and keys.
setFilter changes the first row with that id in place, preserving its omitted knobs and its keys. With no match, a nonzero amount appends. At zero it removes that first row and carries later rows' keys down; other copies stay. removeFilter removes the first matching row the same way, while removeFilterAt selects a particular row by index.
pasteAttributes with "what":{"filters":true} appends one shot's stack to the targets, keeping their existing rows. It copies rows without keys; "keyframes":true also copies source keyed properties, with filter paths shifted to the appended rows and unrelated target properties retained.

A good order to work in

This mirrors Lumetri, and it's a starting point rather than a rule. Correct the shot before styling it, because a look laid over an unbalanced shot exaggerates whatever is off.

Balance: exposure, then temperature and tint.
Tone: contrast, highlights and shadows, then levels or curves.
The three-way corrector: lift, gamma and gain.
Secondaries: hueBands for one range of colour.
The look: saturation or vibrance, tritone, photoFilter, fade, mono.
Finishing: vignette, sharpen, and grain last, so nothing softens it.

This is an order of decisions, not a stack to add in full. Inspect the source and identify what needs correction: a dark face, a colour cast, weak separation or inconsistent shots. Use only the adjustments that address what is visible, then choose a look that suits the footage and the person's reference. Skin, a product's colour, food and a genuine before-and-after are part of the source's meaning, so a dramatic look should not change what the viewer is meant to judge.

Compare at the same moment. setEffectEnabled switches a filter row off without losing its values or keys; render that frame with the row off and on, then leave it in the intended state. Compare a bright and a dark moment too. A richer still frame is not an improvement if the moving shot loses highlight detail, changes skin or makes captions disappear. Across shots, aim for a coherent viewing experience while keeping deliberate changes of light or mood. The comparison is by the pictures you inspect, not an automatic match.

What each filter is for

Light and tone

exposure is in stops: an amount of 1 doubles the light and −1 halves it, which is the whole of its range.
brightness adds or removes light evenly, so it lifts black along with everything else.
contrast pivots about mid grey and is strong: 0.1 to 0.2 is usually plenty.
highlights and shadows act only on bright or dark areas. A negative highlights holds back a bright sky; a positive shadows opens up a dark face.
levels takes inBlack, inWhite, gamma, outBlack and outWhite.
curves has five handles, y0 to y4, at input 0, 0.25, 0.5, 0.75 and 1. curvesRed, curvesGreen and curvesBlue are separate filters, so a red curve and a master curve are two rows in the order you stack them. curve, without the s, is a different filter: a ready-made S-curve for contrast, with a pivot and a number of passes.

The three-way corrector

lift, gamma and gain are the shadows, midtones and highlights — the three wheels of every grading panel. Each has master, red, green and blue knobs from −1 to 1:

gain scales the highlights, pivoting on black.
gamma bends the midtones and leaves black and white where they are.
lift raises the shadows, weighted so it fades out towards white. A lifted black still has a white, which a plain add wouldn't.

Warm highlights with cool shadows is one possible look, shown in the example above: lift blue +0.05, then gain red +0.05 and blue −0.05. On a grey ramp that takes black to (0, 0, 12) and white to (255, 255, 242), and leaves mid grey close to neutral at (133, 127, 126). Small numbers go a long way here, because each knob reaches the midtones too: gain red +0.2 with lift blue +0.15 turns mid grey a pinkish mauve, (152, 127, 146), and runs red out at full from about 83% grey up. Choose the separation only when it helps this shot; neutral footage can already be the right finish.

Colour

saturation scales colour evenly. vibrance is gentler: it moves skies and foliage more than skin, which still moves about half as far as under saturation.
temperature is the white balance, pivoting each channel on mid grey: positive raises red and lowers blue in the light tones and does the reverse in the dark ones, so a strong warm turns black blue. tint is the other axis, on the same pivot: positive leans the light tones magenta and the dark ones green, negative the reverse.
hue rotates every hue by amount × span degrees.
hueBands is a hue qualifier, for changing one range of colour. centre is a position round the colour wheel from 0 to 1 (0 is red, about 0.07 orange and skin, 0.33 green, 0.53 teal, 0.67 blue), width is how much of the wheel it takes (1 is Master), and falloff softens the edge. hue shifts it in degrees. Saturation multiplies existing chroma: −1 removes it and +1 doubles it up to full saturation, while grey stays neutral. lightness pushes toward black or white.
channelMixer sets where each output channel's light comes from, with nine knobs rr, rg, rb through bb. Giving all three rows the same weights makes a black and white you control — for example 0.5, 0.4 and 0.1 of red, green and blue.

Looks and finishing

tritone maps brightness onto three colours, each given as three channels from 0 to 1 (shadowR to highB). The amount mixes that with the original picture, and at 1 every pixel's colour comes from its brightness alone, so somewhere around 0.3 to 0.6 keeps some of the shot's own colour.
photoFilter is a coloured gel: red, green and blue from 0 to 1 and a density. It keeps neutral greys at their own brightness. A newly requested row starts warm orange with density 0.25; an existing saved row with no density still reads as 0. Density 0.2 to 0.4 is a gentle gel.
mono, sepia, invert and fade do nothing at 0 and their full effect at 1.
posterize (levels) and threshold (level) flatten tone into bands or into black and white. Their knobs start where they change nothing (256 levels, and a level of 0), so set them: 4 to 8 levels for a poster look, a level around 0.5 for a clean black and white.
vignette darkens towards the frame's edges at positive amounts and brightens existing corner colour at negative amounts, within −1 to 1. It never adds opacity to empty pixels and belongs on full-frame footage or an adjustment layer. grain moves over time; its rate is how many times a second it changes, 24 by default, and 0 holds it still.
sharpen adds back the difference from a blur, at amount × gain through the full gain range 0 to 6. Its radius is 0.2/1080 to 8/1080 of the short edge; legal fractional values are retained, independently of the slider step. More gain can produce edge halos, so compare the actual footage.

Grade presets

The presets in the Grades folder add ordinary rows to the end of the stack, so they're a quick start and a good reference for sensible magnitudes: warm adds temperature 0.28, contrast 0.1 and highlights −0.12. List them with ymotion_find {"catalogue":"presets","group":"Grades"}:

ymotion_edit {"ops":[{"verb":"applyPreset","args":{"layerId":"<layer id>","preset":"film"}}]}

Read the existing stack before adding a preset. Applying another grade appends another treatment, which can compound contrast and colour rather than refine the first. Inspect the rows it wrote and adjust or remove the ones that do not suit the source; its name is a starting point, not evidence that the film improved.

Type over footage

White type disappears over a bright sky. Here are four ways to help it, from the lightest touch to the heaviest:

A soft shadow on the type itself, a blur of about 0.25 and a y of about 0.04 in black at 60%. Type and titles has the details.
Darken the footage under the words. A masked adjustment layer darkens the picture itself rather than laying grey over it. Here everything below about 60% of the frame's height loses 0.8 of a stop, with a soft edge:

ymotion_edit {"ops":[{"verb":"addFilter","args":{"layerId":"<adjustment layer id>","id":"exposure","amount":-0.8}},{"verb":"addMask","args":{"layerId":"<adjustment layer id>","mask":{"kind":"rect","y":0.35,"width":1.2,"height":0.5,"feather":0.15}}}]}

A gradient scrim: a full-frame solid that fades to black at the bottom. Stops given without a position are evenly spaced, so repeating the transparent stop pushes the fade further down:

ymotion_edit {"ops":[{"verb":"addLayer","args":{"trackId":"<track id>","content":{"kind":"solid","fill":"grad:#00000000,#00000000,#00000000,#00000066,#000000CC"},"start":0,"duration":4,"name":"Scrim"}}]}

A solid plate behind the words, drawn as a shape. See Shapes, icons, masks and mattes.

Palettes and paints

A palette is the handful of paint strings you reuse for type, accents and the background; Units, paints and time lists every form a paint can take. A few verbs help keep one consistent:

Set the film's own ground with setCanvas and {"patch":{"background":"#0E0E10"}}.
Restyle many text layers at once with restyleAll.
Change a colour over time with paintRamp or keyPaint. Numeric writers refuse a colour row and name the paint verbs.

ymotion_edit {"ops":[{"verb":"paintRamp","args":{"layerId":"<layer id>","path":"content.shape.fill","from":"#FF3B30","to":"#4C8DFF","opts":{"start":0,"end":2}}}]}

Good to know

Colour knobs are numbers from 0 to 1 per channel, not hex strings. To use #FF9933 in a tritone or photo filter, write it as 1, 0.6 and 0.2.
A filter can't take a colour or a table yet, so there's no .cube LUT and no Tint with chosen colours. A tritone, a photo filter or a pair of hueBands usually gets you there.
Grade first and choose type colours afterwards, looking at a rendered frame. A colour that reads well over the raw shot can disappear over the graded one.