Configure FFmpeg Scroll Filter Speed and Loop Options

This guide explains how to configure the speed and looping options of the FFmpeg scroll video filter. You will learn how to use the horizontal and vertical speed parameters, set custom pixel limits, and control the loop behavior using command-line examples.

Understanding the Scroll Filter Parameters

The scroll filter in FFmpeg allows you to shift video frames horizontally, vertically, or both. As the video shifts, the content wraps around (loops) by default. The filter is configured using four primary parameters:

• horizontal (or h): Sets the horizontal scroll speed. The value represents the number of pixels shifted per frame. A positive value scrolls to the right, while a negative value scrolls to the left.
• vertical (or v): Sets the vertical scroll speed. The value represents the number of pixels shifted per frame. A positive value scrolls downward, while a negative value scrolls upward.
• limit_horizontal (or lh): Sets the maximum horizontal scroll limit in pixels before the content loops.
• limit_vertical (or lv): Sets the maximum vertical scroll limit in pixels before the content loops.

Setting Scroll Speed

To set the scroll speed, pass your desired pixel-per-frame value to the horizontal or vertical parameters.

Example 1: Scroll Left to Right To scroll the video horizontally to the right at a speed of 5 pixels per frame:

ffmpeg -i input.mp4 -vf "scroll=horizontal=5" output.mp4

Example 2: Scroll Upwards To scroll the video vertically upward at a speed of 3 pixels per frame (using negative values to reverse the direction):

ffmpeg -i input.mp4 -vf "scroll=vertical=-3" output.mp4

Example 3: Diagonal Scroll You can combine both parameters to scroll diagonally:

ffmpeg -i input.mp4 -vf "scroll=h=2:v=2" output.mp4

Configuring Loop and Limit Options

By default, when a video scrolls past its boundary, the edge of the frame immediately wraps around to the other side, creating an infinite loop across the entire width or height of the video.

You can modify this behavior by setting limits. If you set limit_horizontal or limit_vertical, the loop boundary wraps at the specified pixel width/height instead of the full size of the video.

Example 4: Horizontal Scroll with a Custom Loop Limit If you have a 1920x1080 video but want the horizontal scroll to loop every 960 pixels:

ffmpeg -i input.mp4 -vf "scroll=h=5:limit_horizontal=960" output.mp4

If you leave the limits at their default value of 0, FFmpeg automatically uses the input video’s full width and height as the wrap-around point.