Transitions

Canonical docs now live at videoml.org/docs/standard.

Transitions are first-class timeline items that sit between scenes. They can overlap scenes (crossfade, wipe, slide) or insert time between them. Transitions are containers, so they can include visuals, layers, and audio cues.

Start here: The videos below are the primary documentation. Each example is also a full integration test.

Integration test gallery

Each example below is a full integration test. Add new transitions here as the library grows.

Crossfade baseline

Classic overlap dissolve. Use this when you want two scenes to blend without a cut.

View XML (crossfade)

<vml id="transitions-crossfade" fps="30" width="1920" height="1080">
  <scene id="crossfade-a" styles="{"background":"#7a1f1f"}">
    <layer id="bg"><video-background props="{"color":"#7a1f1f"}" /></layer>
    <layer id="title"><video-title props="{"text":"Scene A","textAlign":"center","position":{"y":540}}" /></layer>
  </scene>
  <transition id="crossfade-1" effect="crossfade" duration="18f" ease="power2.inOut" />
  <scene id="crossfade-b" styles="{"background":"#1f3a7a"}">
    <layer id="bg"><video-background props="{"color":"#1f3a7a"}" /></layer>
    <layer id="title"><video-title props="{"text":"Scene B","textAlign":"center","position":{"y":540}}" /></layer>
  </scene>
</vml>

Slide + push directions

Directional moves. Slide brings the next scene in; push moves both scenes to emphasize momentum.

View XML (slide + push)

<vml id="transitions-slide-push" fps="30" width="1920" height="1080">
  <scene id="slide-a" styles="{"background":"#7a1f1f"}">...</scene>
  <transition id="slide-left" effect="slide" duration="16f" ease="power3.inOut" props="{"direction":"left"}" />
  <scene id="slide-b" styles="{"background":"#1f7a3a"}">...</scene>
  <transition id="push-up" effect="push" duration="18f" ease="power2.inOut" props="{"direction":"up"}" />
  <scene id="slide-c" styles="{"background":"#1f3a7a"}">...</scene>
</vml>

Wipe + custom easing

Hard-edge reveal with a custom ease curve for sharper, more graphic motion.

View XML (wipe)

<vml id="transitions-wipe" fps="30" width="1920" height="1080">
  <scene id="wipe-a" styles="{"background":"#7a1f1f"}">...</scene>
  <transition id="wipe-right" effect="wipe" duration="20f" ease="expo.inOut" props="{"direction":"right"}" />
  <scene id="wipe-b" styles="{"background":"#1f3a7a"}">...</scene>
</vml>

Insert mode gap + audio

Creates a deliberate gap between scenes (no overlap). Useful for beats, pauses, or SFX hits.

View XML (insert + audio)

<vml id="transitions-insert-audio" fps="30" width="1920" height="1080">
  <scene id="insert-a" styles="{"background":"#7a1f1f"}">...</scene>
  <transition id="insert-gap" mode="insert" effect="fade" duration="1.5s" overflow-audio="clip">
    <sfx id="transition-hit" start="6f" clip-duration="0.6s" prompt="short impact" />
  </transition>
  <scene id="insert-b" styles="{"background":"#1f7a3a"}">...</scene>
</vml>

Custom brand/logo transition

Use this when you want a company logo or any custom graphic to appear during transitions. You can add audio, layers, or completely custom motion here.

View XML (branded)

<vml id="transitions-branded" fps="30" width="1920" height="1080">
  <scene id="brand-a" styles="{"background":"#7a1f1f"}">...</scene>
  <transition id="brand-overlay" effect="fade" duration="20f" ease="power2.inOut">
    <icon props="{"kind":"lucide","name":"star","size":180,"strokeWidth":8,"position":{"x":1240,"y":420}}" />
  </transition>
  <scene id="brand-b" styles="{"background":"#1f3a7a"}">...</scene>
</vml>

Core concepts

Transition element: Use <transition> for scene-to-scene effects and custom branded motion.
Scene enter/exit: Convenience attributes for fade in/out on a single scene (not a crossfade).
Overlap vs insert: Overlap blends scenes; insert creates a gap and shifts later scenes forward.
Audio in transitions: Use <sfx>, <music>, or <audio kind=...> inside a transition.
GSAP easing: Use GSAP ease strings (e.g. power2.inOut).

Transition element (XML)

<transition id="crossfade-1" effect="crossfade" duration="18f" ease="power2.inOut">
  <sfx id="whoosh" start="0f" />
</transition>

Attributes

Attribute	Type	Notes
`id`	string	Required unique id.
`start` / `end` / `duration`	time	Optional. Explicit timing for the transition window.
`effect`	string	Named transition preset (e.g. `crossfade`, `fade`, `wipe`, `slide`).
`ease`	string	GSAP ease string (e.g. `power2.inOut`).
`mode`	string	`overlap` (default) or `insert`.
`overflow`	string	Visual overflow behavior: `clip`, `extend`, `allow`.
`overflow-audio`	string	Audio overflow behavior: `clip`, `extend`, `allow`.

Scene enter/exit (XML)

Enter/exit transitions are simple helpers for a single scene. They do not crossfade.

<scene
  id="intro"
  enter="fade"
  enter-duration="12f"
  exit="fade"
  exit-duration="12f"
>
  <cue id="intro">Welcome to the video.</cue>
</scene>

Overlap vs insert (XML)

Overlap blends adjacent scenes over the transition window. Insert shifts later scenes forward, creating a gap between scenes.

<transition id="gap" mode="insert" duration="1.5s" effect="fade"/>

Audio cues in transitions (XML)

Audio clips inside a transition are timed relative to the transition start. Use overflow-audio to clip, extend, or allow audio beyond the transition window.

<transition id="audio-test" duration="24f" overflow-audio="clip">
  <sfx id="impact" start="8f" clip-duration="1s" />
</transition>

Checklist for new transition videos

Shows the transition in isolation with strong contrast.
Includes a timing edge case (short/long duration).
Includes audio if relevant.
Uses a GSAP ease string (non-linear).