How to Use the FFmpeg Zoompan Filter

The FFmpeg zoompan filter is a powerful tool used to apply dynamic zoom and pan effects to video streams and still images, commonly used to create the "Ken Burns" effect. This article provides a clear, step-by-step guide on how to understand the zoompan syntax, configure its key parameters, and apply practical examples to your video editing projects.

Understanding the Zoompan Filter

The zoompan filter works by cropping a portion of the input frame and scaling it back up to the output resolution. By changing the crop size (zoom) and crop position (pan) on a frame-by-frame basis, you create the illusion of camera movement.

The basic syntax is:

-vf "zoompan=z='zoom_expr':x='pan_x_expr':y='pan_y_expr':d=duration:s=size"

Key Parameters

  • z (Zoom): Sets the zoom factor. A value of 1 is no zoom, while 2 is 2x zoom. The range is 1.0 to 10.0.
  • x & y (Pan coordinates): Specifies the top-left coordinate of the crop box.
  • d (Duration): The number of frames the effect will last (default is 90 frames).
  • s (Size): The output resolution of the video (default is hd720 or 1280x720).
  • fps (Frames per Second): The output frame rate (default is 25).

Helpful Variables

  • iw / ih: Input width and height.
  • zoom: The current zoom factor.
  • on: The current frame number (starting at 0).

Practical Examples

1. Zoom into the Center of the Frame

To zoom smoothly into the exact center of a video or image, you must adjust the x and y coordinates dynamically so the crop area remains centered as the zoom factor increases.

ffmpeg -i input.mp4 -vf "zoompan=z='zoom+0.002':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=150:s=1280x720" output.mp4
  • How it works: z='zoom+0.002' increases the zoom factor by 0.002 every frame. iw/2-(iw/zoom/2) calculates the shifting x-coordinate required to keep the zoom box perfectly centered.

2. Create a Ken Burns Effect from a Still Image

When converting a static image into a moving video, you must loop the input image and define the output frame rate.

ffmpeg -loop 1 -i image.jpg -vf "zoompan=z='min(zoom+0.0015,1.5)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=300:s=1920x1080" -c:v libx264 -t 10 -pix_fmt yuv420p output.mp4
  • How it works: min(zoom+0.0015,1.5) caps the maximum zoom at 1.5x. The duration d=300 combined with -t 10 creates a smooth 10-second video at 30 frames per second.

3. Pan from Left to Right (No Zoom)

To slide the camera view horizontally across an image without changing the scale, keep the zoom constant and slide the x coordinate.

ffmpeg -loop 1 -i panoramic.jpg -vf "zoompan=z=1.5:x='(iw-iw/zoom)*(on/300)':y='(ih-ih/zoom)/2':d=300:s=1920x1080" -c:v libx264 -t 10 -pix_fmt yuv420p output.mp4
  • How it works: Setting z=1.5 zooms in to create extra space on the sides. (iw-iw/zoom)*(on/300) gradually shifts the visible frame from the far left (x=0) to the far right as the frame index (on) reaches 300.

Essential Tip: Avoiding Jittery Playback

The zoompan filter performs calculations using integers by default, which can cause the camera motion to look shaky or jittery. To fix this, upscale your input to a higher resolution (such as 4K) using the scale filter before applying zoompan, then scale it back down to your desired output size.

ffmpeg -i input.mp4 -vf "scale=3840x2160,zoompan=z='zoom+0.001':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=120:s=3840x2160,scale=1920x1080" output.mp4

This forces FFmpeg to calculate the sub-pixel panning steps at a higher resolution, resulting in a perfectly smooth motion blur and transition.