Skip to content

Colour and grading ​

Footage rarely comes out of the camera looking the way the video should: too dark, a little blue, flat. This page shows how to fix that in the file and then give the picture a look, with colour effects on a clip.

tsx
<Clip id="interview" src="asset:interview">
  <Effect id="expose" type="exposure" params={{ stops: 0.5 }} />
  <Effect id="balance" type="whiteBalance" params={{ temperature: 0.15 }} />
  <Effect id="tone" type="curves" params={{ rgb: [[0, 0.03], [0.25, 0.22], [0.75, 0.8], [1, 1]] }} />
  <Effect id="pop" type="vibrance" params={{ amount: 0.3 }} />
</Clip>

Each colour effect is an <Effect> child. Put it on a clip to grade that clip, or on an <Adjustment> to grade everything beneath it for a stretch of time. The effects run as shaders, the same in the preview and the export.

Work in a colourist's order ​

Effects run in the order they appear in the file. Write them in the order a colourist works:

  1. Correct the light and the white.
  2. Shape the tones.
  3. Give it a look.

Here is that grade on a real shot, laid over it from halfway through by an <Adjustment>:

tsx
import { Adjustment, Clip, Composition, Effect, Track } from "@cutcraft/kit";

// The shot as it came from the camera, then, from 1.5 s, a grade over it: exposure, white balance, curves and
// vibrance, written in the order a colourist works. An <Adjustment> grades everything beneath it for its own time.
export default function Video() {
  return (
    <Composition fps={30} width={960} height={540}>
      <Track id="main">
        <Clip id="pour" src="asset:coffee" in={11} out={14} fit="cover" />
      </Track>
      <Track id="looks" layout="free">
        <Adjustment id="grade" start={1.5} duration={1.5}>
          <Effect id="expose" type="exposure" params={{ stops: 0.5 }} />
          <Effect id="balance" type="whiteBalance" params={{ temperature: 0.3 }} />
          <Effect
            id="tone"
            type="curves"
            params={{
              rgb: [
                [0, 0.03],
                [0.25, 0.2],
                [0.75, 0.84],
                [1, 1],
              ],
            }}
          />
          <Effect id="pop" type="vibrance" params={{ amount: 0.6 }} />
        </Adjustment>
      </Track>
    </Composition>
  );
}

Each effect also has its own page with a demo: see Effects and transitions.

Animate a grade ​

Every param can be animated by a <Keyframe> inside the effect, naming the param:

tsx
<Keyframe id="k1" param="stops" at={0} value={0} />

Correct ​

These effects fix what the camera got wrong: too dark or bright, a colour cast, crushed shadows.

EffectDoesParams
exposureBrightens or darkens, the way a camera's exposure does.stops, -5 to 5: +1 doubles the light
whiteBalanceRemoves a colour cast.temperature, -1 to 1: warms toward amber or cools toward blue, a stop of colour temperature each way. tint, -1 to 1: toward magenta or green
levelsSets the black point and the white point, and bends the midtones.black, white, 0 to 1. gamma: above 1 lifts the midtones
shadowsHighlightsLifts the shadows or holds back the highlights.shadows, highlights, -1 to 1, up to two stops each way. radius, 10 by default
tsx
import { Clip, Composition, Effect, Track } from "@cutcraft/kit";

// One shot cooled toward blue, then warmed toward amber, by white balance.
export default function Video() {
  return (
    <Composition fps={30} width={960} height={540}>
      <Track id="main">
        <Clip id="cool" src="asset:product" in={0} out={1.5} fit="cover">
          <Effect id="cold" type="whiteBalance" params={{ temperature: -0.6 }} />
        </Clip>
        <Clip id="warm" src="asset:product" in={1.5} out={3} fit="cover">
          <Effect id="hot" type="whiteBalance" params={{ temperature: 0.6 }} />
        </Clip>
      </Track>
    </Composition>
  );
}
How they work
  • exposure works where light is linear, so highlights keep their colour instead of washing out as they would under a plain brightness filter.
  • whiteBalance adapts the picture as if it had been lit by a different daylight, so greys stay grey while the cast goes. Where WebGL is missing it falls back on a CSS approximation.
  • shadowsHighlights judges each pixel by the light around it (radius is the blur's standard deviation in pixels), so a dark area lifts as a whole and keeps its detail and contrast.

Shape the tones ​

curves maps input brightness to output brightness through points you give. Use rgb for all channels, or red, green and blue for each one.

tsx
// A gentle S: deeper shadows, brighter highlights, and slightly warmer whites.
<Effect id="s" type="curves" params={{ rgb: [[0, 0], [0.25, 0.2], [0.75, 0.82], [1, 1]], blue: [[0, 0], [1, 0.95]] }} />

A point is [input, output], both 0 to 1, written left to right. Two points [[0, 0], [1, 1]] change nothing, which is each curve's default. The curve is a smooth monotone spline through the points, so it never overshoots between them.

vibrance adds saturation to muted colours and leaves strong ones nearly alone (amount, -1 to 1). It is kinder to skin than saturation.

Give it a look ​

duotone maps the picture's brightness from one colour (dark) to another (light), mixed with the original by amount.

A look from a LUT ​

A look made in a grading tool usually leaves it as a 3D LUT in a .cube file. Add it to the manifest like media, then grade with the built-in lut effect:

bash
npx cutcraft add teal-orange.cube
tsx
<Effect id="look" type="lut" params={{ src: "asset:teal-orange", amount: 0.8 }} />

amount mixes the graded colour with the original, from 0 to 1.

How the LUT is read

The LUT is read with trilinear filtering. A table whose DOMAIN_MIN and DOMAIN_MAX are not 0 and 1 is resampled onto 0 to 1 when it loads. 1D tables are not read.

Where there is no WebGL ​

The colour effects need WebGL, which every browser the player runs in has, and the export always has. Where it is missing, exposure, vibrance, levels and whiteBalance fall back on a CSS filter that comes close, and the others are left out with a warning.

WARNING

Effects that read a file (lut) work on clips, nested sequences and adjustments, not yet on overlays.

Next ​

MIT licensed.