Scroll Video Horizontally and Vertically in FFmpeg

This article provides a concise guide on using the FFmpeg scroll video filter to continuously pan video streams horizontally, vertically, or in both directions simultaneously. You will learn the filter's syntax, primary parameters, and practical command-line examples for common motion effects.

The Scroll Filter Syntax and Parameters

The scroll filter continuously moves the video frame along the X or Y axis, wrapping around the edges to create a seamless looping movement.

The filter accepts four primary options:

  • horizontal (or h): Sets the horizontal scrolling speed. Accepts values from -1.0 to 1.0. Positive values shift the image to the right, and negative values shift it to the left.
  • vertical (or v): Sets the vertical scrolling speed. Accepts values from -1.0 to 1.0. Positive values shift the image downward, and negative values shift it upward.
  • hpos: Sets the initial horizontal starting offset, ranging from 0.0 to 1.0.
  • vpos: Sets the initial vertical starting offset, ranging from 0.0 to 1.0.

The speed value represents the fraction of the frame's dimension shifted per output frame. For smooth playback, keep these values small (typically between 0.001 and 0.01).

Horizontal Scrolling

To scroll a video horizontally from right to left, supply a negative value to the horizontal parameter:

ffmpeg -i input.mp4 -vf "scroll=horizontal=-0.005" -c:a copy output.mp4

To scroll from left to right, use a positive value:

ffmpeg -i input.mp4 -vf "scroll=horizontal=0.005" -c:a copy output.mp4

Vertical Scrolling

To create a vertical scroll (similar to moving credits or an upward ticker), apply a negative value to the vertical parameter:

ffmpeg -i input.mp4 -vf "scroll=vertical=-0.003" -c:a copy output.mp4

To scroll the video downward from top to bottom, use a positive vertical value:

ffmpeg -i input.mp4 -vf "scroll=vertical=0.003" -c:a copy output.mp4

Simultaneous Diagonal Scrolling

You can combine both horizontal and vertical scrolling to move the content diagonally across the frame:

ffmpeg -i input.mp4 -vf "scroll=h=0.002:v=0.002" -c:a copy output.mp4

Setting an Initial Offset

If you want the scroll to begin from a specific offset instead of the default top-left origin (0.0), use hpos and vpos:

ffmpeg -i input.mp4 -vf "scroll=h=0.005:hpos=0.5" -c:a copy output.mp4

In this command, the video starts horizontally centered (hpos=0.5) before progressing with the horizontal scrolling animation.