Skip to main content

Video Transitions

Complete guide to video transitions in the Zvid Package, including smooth transitions between video clips and advanced timing control.

Overview​

Video transitions create smooth visual changes between video clips using FFmpeg's xfade filter. Unlike animations that transition between transparent backgrounds and elements, transitions blend one video directly into another, creating professional video sequences.

How Transitions Work​

The transition system:

  1. Groups Related Videos: Videos with transition effects are grouped together
  2. Creates Base Canvas: Each video is overlaid on a transparent canvas
  3. Applies XFade Effects: Uses FFmpeg's xfade filter to blend between videos
  4. Manages Timing: Coordinates transition timing with video enter/exit times

Timing Properties​

PropertyTypeDefaultDescription
enterBeginnumber0Start time for entrance (seconds)
enterEndnumber0End time for entrance animation (seconds)
exitBeginnumberproject.durationStart time for exit animation (seconds)
exitEndnumberproject.durationEnd time for exit (seconds). Must equal the enterBegin of the next video element for transitions

Transition Feature for Video Elements​

To enable transitions between two video elements, specific properties must be defined in the JSON structure. Here’s how it works:

  • Applicable to Video Elements Only:
    The transition feature is available exclusively for elements with "type": "VIDEO". Other element types like IMAGES, TEXTS, or GIFS do not support transitions.

  • Defining the Transition:
    On the first video element:

    • transition: Specifies the type of transition effect (e.g., "fade", "wipe", "slide").
    • transitionId: The id of the next video element that will be used for the transition.
    • transitionDuration: Duration (in seconds) of the transition effect.
    • Important: The exitEnd of this video must equal the enterBegin of the next video.

  • Second Video Element Requirements:
    The second video, identified by transitionId, should be a standard video element with at least a type, src, and id.
    Example:

    {
      "type": "VIDEO",
      "src": "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
      "id": "clip1",
      "transition": "fade",
      "transitionId": "clip2",
      "transitionDuration": 2,
      "enterBegin": 0,
      "exitEnd": 5
    },
    {
      "type": "VIDEO",
      "src": "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
      "id": "clip2",
      "enterBegin": 5,
      "exitEnd": 10
    }
you can't have end animation with the first element of a transition, and you can't have an start animation with later element of a transtion

fadeblack - Fade through black

{
  transition: "fadeblack",
}

fadewhite - Fade through white

{
  transition: "fadewhite",
}

fadegrays - Fade through grayscale

{
  transition: "fadegrays",
}

Wipe Transitions​

wipeleft, wiperight, wipeup, wipedown - Directional wipes

{
  transition: "wiperight",  // Wipes from left to right
}

wipetl, wipetr, wipebl, wipebr - Diagonal wipes

{
  transition: "wipetl",     // Wipes from top-left
}

Slide Transitions​

slideleft, slideright, slideup, slidedown - Slide effects

{
  transition: "slideright", // Slides to the right
}

smoothleft, smoothright, smoothup, smoothdown - Smooth slides

{
  transition: "smoothleft",
}

Shape Transitions​

circlecrop - Circular transition

{
  transition: "circlecrop",
}

rectcrop - Rectangular transition

{
  transition: "rectcrop",
}

circleopen / circleclose - Circle opening/closing

{
  transition: "circleclose",
}

horzopen / horzclose - Horizontal opening/closing

{
  transition: "horzclose",
}

vertopen / vertclose - Vertical opening/closing

{
  transition: "vertopen",
}

Diagonal Transitions​

diagbl, diagbr, diagtl, diagtr - Diagonal effects

{
  transition: "diagbr",     // Diagonal bottom-right
}

Slice Transitions​

hlslice / hrslice - Horizontal slices

{
  transition: "hlslice",    // Horizontal slice left
}

vuslice / vdslice - Vertical slices

{
  transition: "vuslice",    // Vertical slice up
}

Creative Transitions​

dissolve - Dissolve effect

{
  transition: "dissolve",
}

pixelize - Pixelation transition

{
  transition: "pixelize",
}

radial - Radial wipe

{
  transition: "radial",
}

hblur - Horizontal blur

{
  transition: "hblur",
}

distance - Distance-based transition

{
  transition: "distance",
}
Unsupported Transitions

These transitions are not yet supported: squeezeh, squeezev, hlwind, hrwind, vuwind, vdwind, coverleft, coverright, coverup, coverdown, revealleft, revealright, revealup, revealdown, and zoomin

Examples​

Simple Fade Transition​

// First video
{
    type: "VIDEO",
    src: "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
    width: 1280,
    height: 720,
    exitEnd: 5,
    transition: "fade",
    transitionId: "main",
    transitionDuration: 2
},
{
    type: "VIDEO",
    src: "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
    width: 1280,
    height: 720,
    enterBegin: 5,
    enterEnd: 10,
    id: "main"
}

Wipe Transition​

// First video
{
    type: "VIDEO",
    src: "https://cdn.pixabay.com/video/2025/06/03/283533_large.mp4",
    width: 1280,
    height: 720,
    exitEnd: 5,
    transition: "wiperight",
    transitionId: "main",
    transitionDuration: 2
},
{
    type: "VIDEO",
    src: "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
    width: 1280,
    height: 720,
    enterBegin: 5,
    enterEnd: 10,
    id: "main"
}

Best Practices​

Transition Design​

  1. Consistency: Use similar transition styles for related content
  2. Duration: Match transition duration to content pace (0.3-2 seconds typical)
  3. Direction: Use logical directions that guide viewer attention
  4. Content Matching: Choose transitions that complement the video content

Technical Guidelines​

  1. Timing Coordination: Ensure that the exit of the previous item is the same as enter of the next item.
  2. Duration Matching: Exit and enter transition durations should match
  3. ID Management: Use clear, descriptive IDs for transition linking
  4. Performance: Longer transitions require more processing time

Visual Considerations​

  1. Content Continuity: Ensure transitions don't disrupt narrative flow
  2. Color Matching: Consider color relationships between transitioning videos
  3. Motion Direction: Align transition direction with video content motion
  4. Viewer Attention: Use transitions to guide where viewers should look

Common Transition Patterns​

News/Documentary Style​

// Professional, clean transitions
{
  transitionDuration: 1.5;
}

Music Video Style​

// Quick, rhythmic transitions
{
  transitionDuration: 0.3;
}

Corporate/Business​

// Smooth, professional transitions
{
  transitionDuration: 2;
}

Creative/Artistic​

// Unique, eye-catching transitions
{
  transitionDuration: 2.5;
}

Action/Sports​

// Dynamic, energetic transitions
{
  transitionDuration: 0.8;
}

Troubleshooting​

Common Issues​

  1. Transition Not Working: Check ID linking and timing coordination
  2. Choppy Transitions: Increase transition duration or check video quality
  3. Performance Issues: Reduce transition complexity or duration

Debugging Tips​

  1. ID Verification: Ensure transitionId matches the next source video's id
  2. Timing Check: Verify overlap between exit and enter times
  3. Duration Consistency: Match transition durations between linked videos
  4. Group Validation: Check that transition chains are properly formed

Transition vs Animation​

When to Use Transitions​

  • Video-to-Video: Smooth changes between video clips
  • Narrative Flow: Maintaining story continuity
  • Professional Look: Creating polished video sequences

When to Use Animations​

  • Element Entrance/Exit: Bringing elements in/out of frame
  • Text Effects: Animating text appearance
  • Overlay Elements: Animating graphics over video

Next Steps​