FFmpeg Overlay Move Across Screen Over Time

Moving an image or video overlay across the screen in FFmpeg is achieved by using mathematical expressions within the overlay filter. This guide demonstrates how to program dynamic movement—such as linear, diagonal, or restricted motion—by leveraging FFmpeg’s internal variables like time (t) and frame count (n). You will learn the exact command syntax and formulas needed to animate your overlays smoothly.

The Core Concept: Using Variables

To make an overlay move, you must define its x (horizontal) and y (vertical) coordinates as functions of time. FFmpeg provides several built-in variables for this:

• t: The current timestamp in seconds.
• n: The sequential frame number.
• W and H: The width and height of the main (background) video.
• w and h: The width and height of the overlay input.

Example 1: Constant Horizontal Movement (Left to Right)

To move an overlay horizontally across the screen at a constant speed, multiply the time variable t by the desired speed in pixels per second.

The following command moves the overlay from the left edge (\(x=0\)) to the right at a speed of 150 pixels per second, while keeping it vertically centered:

ffmpeg -i background.mp4 -i overlay.png -filter_complex "[0:v][1:v]overlay=x='t*150':y=(H-h)/2" -codec:a copy output.mp4

Example 2: Diagonal Movement

To move the overlay diagonally, apply time-based math to both the x and y coordinates. This command moves the overlay 100 pixels per second horizontally and 50 pixels per second vertically:

ffmpeg -i background.mp4 -i overlay.png -filter_complex "[0:v][1:v]overlay=x='t*100':y='t*50'" -codec:a copy output.mp4

Example 3: Scrolling Across the Entire Screen and Repeating

If you want the overlay to scroll off the right edge of the screen and immediately reappear on the left edge, use the modulo operator (mod).

ffmpeg -i background.mp4 -i overlay.png -filter_complex "[0:v][1:v]overlay=x='mod(t*200, W)':y=(H-h)/2" -codec:a copy output.mp4

In this command, mod(t*200, W) resets the horizontal position to 0 once the calculated coordinate exceeds the background width (W).

Example 4: Moving and Stopping at a Specific Position

If you want the overlay to slide into the frame and then stop at a specific coordinate (for example, the center of the screen), use the min or max mathematical functions.

The following command slides the overlay from the left and stops it precisely in the center of the screen:

ffmpeg -i background.mp4 -i overlay.png -filter_complex "[0:v][1:v]overlay=x='min(t*300, (W-w)/2)':y=(H-h)/2" -codec:a copy output.mp4

Here, min(t*300, (W-w)/2) ensures that the x coordinate increases until it reaches (W-w)/2 (the horizontal center), at which point the min function caps the value, stopping the movement.