Skip to content

Your own effects and transitions ​

The built-in effects and transitions cover the usual looks. When you need another, write it in GLSL in the file itself: declare it at the top with effect() or transition(), and pass what it returns as an <Effect> or <Transition> type.

tsx
import { z } from "zod";

import { Clip, Composition, Effect, effect, Keyframe, Track } from "@cutcraft/kit";

// A two-colour tone (the kit has one built in, `duotone`; this is how such an effect is written): each pixel's
// brightness picks a colour between `dark` and `light`. Colour params arrive in the shader as vec3; `strength` blends
// from the footage to the toned picture, and the keyframes animate it.
const navyGold = effect({
  name: "navy-gold",
  params: z.object({
    dark: z.string().default("#101421"),
    light: z.string().default("#e8a33d"),
    strength: z.number().min(0).max(1).default(1),
  }),
  shader: `vec4 effect(vec2 uv) {
    vec4 c = texture(image, uv);
    float l = dot(c.rgb, vec3(0.299, 0.587, 0.114));
    return vec4(mix(c.rgb, mix(params.dark, params.light, l), params.strength), c.a);
  }`,
});

export default function Video() {
  return (
    <Composition fps={30} width={960} height={540}>
      <Track id="main">
        <Clip id="fractal" src="asset:product" in={0} out={3} fit="cover">
          <Effect id="tone" type={navyGold} params={{ dark: "#0b1d3a", light: "#ffcf70" }}>
            <Keyframe id="k1" param="strength" at={0} value={0} />
            <Keyframe id="k2" param="strength" at={1.5} value={1} />
          </Effect>
        </Clip>
      </Track>
    </Composition>
  );
}

Declare an effect ​

An effect is a name, a zod schema of its params, and a shader. The example above is a two-colour tone (the built-in duotone does the same; this shows how it is written), with two colour params and a third that the keyframes animate from the plain footage to the full effect. TypeScript checks the params you write on <Effect> against the schema you declared, as it does for the built-in types.

An effect's shader defines vec4 effect(vec2 uv) and returns the colour at uv. It gets:

NameIs
imageThe element's picture.
params.<name>Each param, typed from the schema (Params).
resolutionThe frame in pixels.
timeSeconds into the element.

uv (0, 0) is the top left. Return plain colour; the player premultiplies it.

Keep declarations at the top ​

Keep effect() and transition() at the top of the file with a literal name and shader (or passes), where the editor and lint can read them; the declaration lint (Lint) says when one is not.

The player finds an effect on the element that uses it, and among the file's exports, so export const the ones the editor should offer before anything uses them. The editor's actions take the names too, for example effect/add and transition/update, and write type={glitch} back into the file.

A declaration is a value, not a registration

Each file's effects belong to it alone, so many players on one page never see each other's.

Params ​

The shader reads each param as params.<name>, so a param can take any name, length and image included. The types come from the schema, once:

SchemaIn the shader
A numberfloat
A booleanbool
An array of two, three or four numbersvec2, vec3, vec4
A colour string such as "#ff8800"vec3
A z.enumint, and the shader names its options: params.direction == params.direction.left
"asset:ID"A texture: an image as a sampler2D, a LUT (.cube) as a sampler3D

effect() refuses a shader that reads a param its schema does not declare, or one no uniform can carry.

The schema does the rest of the work too:

  • the zod schema checks the values and fills in defaults;
  • a <Keyframe> inside the <Effect> animates one with param="<name>", and the resolver checks the name and the values against the schema;
  • an editor can build its inspector from the schema.

A texture from an asset ​

A param that names an asset, "asset:ID", is read by the shader as a texture. The player loads it before the frame that needs it, and the resolver checks that the asset is in the manifest and is an image or a LUT. The built-in lut effect reads a LUT this way: see Colour and grading.

Textures and overlays

Textures reach effects on clips, nested sequences and adjustments. On an overlay, an effect with an asset param is not drawn yet.

Several passes ​

An effect that needs more than one pass (a blur in two directions, a glow drawn from a blurred copy) gives passes, a list of shaders, in place of shader. Each defines vec4 effect(vec2 uv), and they run in order:

NameIn each pass
imageThe pass before's result (the element's picture for the first).
originalThe element's picture, in every pass.
paramsThe same params in every pass.

A separable Gaussian blur, as an example, with radius its standard deviation in pixels as CSS blur() reads it (25 taps out to three deviations):

tsx
const soften = effect({
  name: "soften",
  params: z.object({ radius: z.number().min(0).max(40).default(4) }),
  passes: [
    `vec4 effect(vec2 uv) {
      float s = max(params.radius, 0.001);
      vec4 sum = vec4(0.0);
      float total = 0.0;
      for (int i = -12; i <= 12; i++) {
        float d = float(i) * s / 4.0;
        float w = exp(-d * d / (2.0 * s * s));
        sum += w * texture(image, uv + vec2(d / resolution.x, 0.0));
        total += w;
      }
      return sum / total;
    }`,
    `vec4 effect(vec2 uv) {
      float s = max(params.radius, 0.001);
      vec4 sum = vec4(0.0);
      float total = 0.0;
      for (int i = -12; i <= 12; i++) {
        float d = float(i) * s / 4.0;
        float w = exp(-d * d / (2.0 * s * s));
        sum += w * texture(image, uv + vec2(0.0, d / resolution.y));
        total += w;
      }
      return sum / total;
    }`,
  ],
});

Declare a transition ​

A transition is declared the same way with transition(). Here the incoming clip opens as a circle from the centre:

tsx
import { Clip, Composition, Track, Transition, transition } from "@cutcraft/kit";

// The incoming clip opens as a circle from the centre of the frame. (The built-in `iris` does this and more; this shows
// how a transition of your own is written.)
const circle = transition({
  name: "circle",
  shader: `vec4 transition(vec2 uv) {
    float d = distance(uv * resolution, resolution / 2.0) / length(resolution / 2.0);
    return d < progress ? texture(to, uv) : texture(from, uv);
  }`,
});

export default function Video() {
  return (
    <Composition fps={30} width={960} height={540}>
      <Track id="main">
        <Clip id="aurora" src="asset:aurora" in={0} out={2} fit="cover" />
        <Transition id="open" type={circle} duration={1} />
        <Clip id="fractal" src="asset:product" in={0} out={2} fit="cover" />
      </Track>
    </Composition>
  );
}

Its shader defines vec4 transition(vec2 uv) and gets:

NameIs
fromThe outgoing picture.
toThe incoming picture.
progressHow far it has got, from 0 to 1.
params.<name>, resolution, timeAs for an effect.

Effects on titles and layers ​

Overlays take the same effects: titles, shapes, SVG, stickers and any <Layer>, including <Three> and <Motion>. Write the <Effect> inside the element, next to its text or its free code. Here one colour-split effect runs on a title and, more gently, on a Motion badge, while the footage under them stays as it is:

tsx
import { z } from "zod";

import { Clip, Composition, Effect, effect, Motion, Title, Track } from "@cutcraft/kit";

// The same kind of effect a clip takes, on a title and on a Motion layer: the overlay's pixels only.
const split = effect({
  name: "split",
  params: z.object({ amount: z.number().min(0).max(0.05).default(0.008) }),
  shader: `vec4 effect(vec2 uv) {
    vec2 o = vec2(params.amount * (1.0 + sin(time * 8.0)), 0.0);
    vec4 c = texture(image, uv);
    float r = texture(image, uv + o).a;
    float b = texture(image, uv - o).a;
    return vec4(max(c.r, r), c.g * c.a, max(c.b, b), max(c.a, max(r, b)));
  }`,
});

export default function Video() {
  return (
    <Composition fps={30} width={960} height={540}>
      <Track id="main">
        <Clip id="bg" src="asset:product" in={0} out={3} fit="cover" />
      </Track>
      <Track id="text" layout="free">
        <Title id="name" start={0.2} duration={2.8} size={130} color="#ffffff">
          <Effect id="title-split" type={split} />
          Shed
        </Title>
        <Motion
          id="badge"
          start={0.8}
          duration={2.2}
          sequence={[[".badge", { opacity: [0, 1], scale: [0.7, 1] }, { duration: 0.4 }]]}
        >
          <Effect id="badge-split" type={split} params={{ amount: 0.004 }} />
          <div
            className="badge"
            style={{
              position: "absolute",
              left: 640,
              top: 140,
              padding: "10px 22px",
              borderRadius: 999,
              background: "#e8a33d",
              color: "#101421",
              font: "700 34px 'Space Grotesk', sans-serif",
            }}
          >
            New
          </div>
        </Motion>
      </Track>
    </Composition>
  );
}

An overlay is DOM, so the player draws it into a canvas with HTML-in-Canvas and runs its effects over that picture, in file order.

Overlay effects in the preview

HTML-in-Canvas is a Chrome feature that is still behind a flag: turn on chrome://flags/#canvas-draw-element to see overlay effects in the preview. Without it the preview draws the overlay's built-in effects as CSS, leaves out the ones only a shader draws, and warns once. The export always draws them all, because its browser has the feature on.

How effects are drawn ​

An element's effects run in the order they appear in the file, yours and the built-in ones alike, after its mask, vignette and grain. Here the same two effects in the opposite order give two different pictures:

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

// The same two effects in either order. Left: grayscale, then duotone, which maps the grey onto navy and amber.
// Right: duotone, then grayscale, which takes the colour back out. Effects run in the order the file lists them.
export default function Video() {
  return (
    <Composition fps={30} width={960} height={540}>
      <Track id="left">
        <Clip
          id="grey-first"
          src="asset:coffee"
          in={12}
          out={15}
          fit="cover"
          transform={{ position: { x: -240, y: 0 }, scale: { x: 0.5, y: 0.5 } }}
        >
          <Effect id="grey-a" type="grayscale" />
          <Effect id="tone-a" type="duotone" />
        </Clip>
      </Track>
      <Track id="right">
        <Clip
          id="tone-first"
          src="asset:coffee"
          in={12}
          out={15}
          fit="cover"
          transform={{ position: { x: 240, y: 0 }, scale: { x: 0.5, y: 0.5 } }}
        >
          <Effect id="tone-b" type="duotone" />
          <Effect id="grey-b" type="grayscale" />
        </Clip>
      </Track>
    </Composition>
  );
}
OnEffects run
<Clip>, <Nested>After its mask, vignette and grain.
<Adjustment>Over everything beneath it, its vignette and grain included.
An overlayIn order, but an overlay does not draw vignette or grain yet: the lint says so.
Each clip under a shader transitionBefore the two are blended.

The player draws these shaders with WebGL in any browser, and the export draws them the same way, in the Chrome it runs in.

Shaders, CSS filters and passes

Most built-in effects run as shaders, through the same pipeline as yours: the colour tools in Colour and grading, the footage tools, and the title looks, and so do the built-in shader transitions (Transitions). The simple adjustments (brightness, blur and the like) are CSS filters, and vignette and grain are painted.

When none of an element's effects needs a shader, its built-in ones draw as one CSS filter. Once one does, they all run as shader passes, so the order stays the one you wrote.

Consecutive built-in colour effects (exposure, white balance, curves, a LUT, brightness and the like) are drawn together as one pass, still in that order. A built-in whose params change nothing (an amount at 0) is not drawn at all.

Next ​

MIT licensed.