Transitions

A transition blends one clip into the next where they overlap on a track. This page covers how to set the overlap up, what the engine checks, and how easing and parameters work. After reading it you can join any two clips with any of the built-in transitions.

The overlap

A track shows one clip at a time, so two clips on one track may overlap only where a transition joins them. To join clip a to clip b, make them overlap and add a ClipTransition to the track’s transitions:

{
  "id": "v1",
  "name": "Picture",
  "kind": "video",
  "clips": [
    {
      "id": "a",
      "source_id": "platform",
      "timeline_range": { "start": 0, "end": 300000 },
      "source_range": { "start": 0, "end": 300000 }
    },
    {
      "id": "b",
      "source_id": "coast",
      "timeline_range": { "start": 180000, "end": 480000 },
      "source_range": { "start": 0, "end": 300000 }
    }
  ],
  "transitions": [
    {
      "from_clip": "a",
      "to_clip": "b",
      "timeline_range": { "start": 180000, "end": 300000 },
      "easing": { "type": "cubic_bezier", "x1": 0.42, "y1": 0, "x2": 0.58, "y2": 1 },
      "effect": {
        "id": "alpha2.transition.circle-open",
        "version": 1,
        "params": { "smoothness": { "mode": "constant", "value": { "type": "float", "value": 0.3 } } }
      }
    }
  ]
}

Here a runs from 0 to 2.5 s and b from 1.5 to 4 s, so they overlap from 1.5 s to 2.5 s, and the transition’s timeline_range is that second.

from_clip is shown at progress 0 and to_clip at progress 1.
timeline_range is the half-open interval the transition runs over. Both clips must be active for all of it, and it must cover their whole overlap, so in practice it is exactly the overlap.
easing shapes the progress (below).
effect is the transition to run: a ClipEffect naming a transition definition, such as alpha2.transition.circle-open, version 1.

What the engine checks

When the project loads, the engine refuses:

clips on one track that overlap without a transition covering the overlap (clips a and b overlap without a covering transition on track v1);
a transition on a track that is not a video track, between a clip and itself, with an empty range, or whose range is not inside both clips (track v1 has an invalid clip transition);
two transitions between the same two clips, in either direction;
transitions active at one instant that lead from clip to clip in a circle.

The linter also warns about a transition no frame shows: one shorter than a frame, or one frame long and off the frame grid (short_transition).

Easing

The transition’s linear progress runs from 0 at the start of its range to 1 at its end. easing maps it to eased progress, which is clamped to 0..1:

{ "type": "linear" }: progress advances at a constant rate.
{ "type": "cubic_bezier", "x1": 0.42, "y1": 0, "x2": 0.58, "y2": 1 }: progress follows a CSS cubic-bezier() curve, here ease-in-out.

Unlike keyframe interpolation, easing has no hold.

Parameters

Transition parameters are named, animatable values, as for effects. In a timeline transition their keyframes are in timeline time. Parameters you leave out take their defaults.

The preset below joins three photos with alpha2.transition.directional-wipe and alpha2.transition.fade:

Pick any built-in transition in the explorer to see its parameters:

The full list, with every parameter’s range and default, is in the transition reference.

Transition referenceEvery built-in transition and its parameters.

Effects and compositionsEffect invocations and composition graphs.

Time and ticksHalf-open ranges and the frame grid.