---
title: "Video Transitions"
canonical_url: https://docs.zvid.io/docs/structure/transitions/
source: docs/structure/transitions.md
content_revision: 6338386a1dd87e4a
---

# Video Transitions

Video transitions blend one `VIDEO` element into another using FFmpeg xfade. They are separate from enter/exit animations, which animate an element against transparency.

> **Transitioning between scenes?**
This page covers **element-level** VIDEO-to-VIDEO transitions on a single
timeline. For transitions between [scenes](https://docs.zvid.io/docs/structure/scenes/), set `transition` on
the scene itself — see [Transitions Between Scenes](https://docs.zvid.io/docs/structure/scenes/#transitions-between-scenes).
Both use the same [xfade effects](https://docs.zvid.io/docs/structure/properties/xfade-effects/).

## Requirements

Transitions apply only to `VIDEO` elements.

On the first clip:

- Set `id`.
- Set `transition` to a supported xfade effect.
- Set `transitionDuration`.
- Set `transitionId` to the next clip's `id`.
- Coordinate timing so the first clip's `exitEnd` aligns with the next clip's `enterBegin`.

On the next clip:

- Set a matching `id`.
- Set `enterBegin` at the handoff time.

Avoid combining an exit animation on the first transition clip or an enter animation on the later transition clip in the same handoff, because that competes with the transition.

## Supported Effects

Transitions use the [`XFadeEffect`](https://docs.zvid.io/docs/structure/properties/xfade-effects/) source list, including `fade`, `fadeblack`, `fadewhite`, `wipeleft`, `slideright`, `smoothleft`, `circlecrop`, `dissolve`, `pixelize`, `radial`, `hblur`, and `fadegrays`.

## Examples

These arrays are **visual fragments** for `payload.visuals`, not complete
render requests. All times are seconds. The recorded preview below uses a
smaller canvas and an eight-second project to demonstrate the same one-second
fade; its full payload is available with the preview.

### Fade Transition

```json
[
  {
    "type": "VIDEO",
    "id": "clip1",
    "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
    "width": 1280,
    "height": 720,
    "enterBegin": 0,
    "exitEnd": 5,
    "transition": "fade",
    "transitionId": "clip2",
    "transitionDuration": 1
  },
  {
    "type": "VIDEO",
    "id": "clip2",
    "src": "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
    "width": 1280,
    "height": 720,
    "enterBegin": 5,
    "exitEnd": 10
  }
]
```


```json
{
  "name": "docs-video-transition",
  "width": 960,
  "height": 540,
  "duration": 8,
  "backgroundColor": "#000000",
  "visuals": [
    {
      "type": "VIDEO",
      "id": "intro",
      "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
      "resize": "cover",
      "width": 960,
      "height": 540,
      "volume": 0,
      "enterBegin": 0,
      "exitEnd": 4,
      "transition": "fade",
      "transitionId": "main",
      "transitionDuration": 1
    },
    {
      "type": "VIDEO",
      "id": "main",
      "src": "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
      "resize": "cover",
      "width": 960,
      "height": 540,
      "volume": 0,
      "enterBegin": 4,
      "exitEnd": 8
    }
  ]
}
```

Recorded fixture: an eight-second project with a one-second fade

[Watch rendered example](https://cdn.zvid.io/library/docs/video-transition.mp4)


### Wipe Transition

```json
[
  {
    "type": "VIDEO",
    "id": "intro",
    "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
    "resize": "cover",
    "enterBegin": 0,
    "exitEnd": 5,
    "transition": "wiperight",
    "transitionId": "main",
    "transitionDuration": 1
  },
  {
    "type": "VIDEO",
    "id": "main",
    "src": "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
    "resize": "cover",
    "enterBegin": 5,
    "exitEnd": 10
  }
]
```

## Best Practices

- Keep transition durations between `0.3` and `2` seconds for most videos.
- Use clear IDs such as `intro`, `scene-2`, and `outro`.
- Keep transition chains simple before adding many simultaneous overlays.
- Use `volume: 0` on scene clips when a separate narration or music track should drive the audio.

## Related Pages

- [Video Elements](https://docs.zvid.io/docs/structure/video-elements/)
- [Animation Effects](https://docs.zvid.io/docs/structure/animations/)
- [Audio Elements](https://docs.zvid.io/docs/structure/audio-elements/)
- [XFadeEffect](https://docs.zvid.io/docs/structure/properties/xfade-effects/)