How to Use Duration and Offset in FFmpeg xfade

The FFmpeg xfade (crossfade) filter allows you to apply smooth transition effects between two video streams. Configuring the duration and offset parameters is essential for controlling how long the transition lasts and the exact timestamp when it starts. This guide explains the core formula for calculating the offset, details the parameters, and provides ready-to-use command examples.

Understanding duration and offset

  • duration: Sets the length of the transition effect in seconds (or fractional seconds, such as 0.5). The default is 1 second.
  • offset: Sets the start time of the transition relative to the first video’s timeline. It tells FFmpeg at what second on the primary video the crossfade should begin.

The Offset Calculation Formula

Because the second video overlaps the end of the first video, the transition must start before the first video finishes. Calculate the offset using this formula:

\[\text{offset} = \text{duration of first video} - \text{transition duration}\]

For example, if the first video is 10 seconds long and you want a 2-second transition:

\[\text{offset} = 10 - 2 = 8\]

If the offset is set greater than or equal to the first video's length, the transition will fail because the first video will have already ended.

Basic Command Example

Here is how to join input1.mp4 (10 seconds long) and input2.mp4 with a 2-second fade transition starting at second 8:

ffmpeg -i input1.mp4 -i input2.mp4 -filter_complex \
"[0:v][1:v]xfade=transition=fade:duration=2:offset=8[v]" \
-map "[v]" output.mp4

Chaining Multiple Transitions

When chaining three or more videos, each subsequent offset depends on the running length of the merged timeline. Each transition shortens the total output by the transition duration.

For three 10-second videos with 1-second transitions:

  • First transition offset: \(10 - 1 = 9\) seconds.
  • Second transition offset: \((10 + 10 - 1) - 1 = 18\) seconds.
ffmpeg -i input1.mp4 -i input2.mp4 -i input3.mp4 -filter_complex \
"[0:v][1:v]xfade=transition=wipeleft:duration=1:offset=9[v1]; \
 [v1][2:v]xfade=transition=wiperight:duration=1:offset=18[v]" \
-map "[v]" output.mp4

Synchronizing Audio

The xfade filter only processes video streams. To prevent audio from desynchronizing, use the acrossfade filter with the matching duration:

ffmpeg -i input1.mp4 -i input2.mp4 -filter_complex \
"[0:v][1:v]xfade=transition=fade:duration=2:offset=8[v]; \
 [0:a][1:a]acrossfade=d=2[a]" \
-map "[v]" -map "[a]" output.mp4