Configure FFmpeg Zoompan Zoom, Pan, and Frames

This article provides a practical guide on how to configure the zoom expression, frame count, and coordinate panning using the FFmpeg zoompan filter. You will learn the core syntax, how to control zoom speed, how to calculate coordinates for smooth panning, and how to set the exact duration of the effect using frame counts.

The Zoompan Filter Syntax

The zoompan filter works by cropping a portion of the input frame and scaling it back to the output resolution. The basic syntax is:

zoompan=z='zoom_expression':x='x_expression':y='y_expression':d=frame_count:s=output_resolution
  • z (Zoom): Sets the zoom factor (default is 1).
  • x & y (Panning): Sets the top-left coordinate of the cropped zoom box.
  • d (Duration/Frame Count): Sets the number of frames the effect lasts per input frame (default is 90).
  • s (Size): Sets the output resolution (default is 1280x720).

1. Configuring the Zoom Expression (z)

The zoom expression z is evaluated for every frame. To create a gradual zoom, you must reference the current zoom state using the variable zoom.

  • Zoom In: To increase zoom over time, add a small decimal value to the current zoom on each frame:

    z='zoom+0.002'

  • Zoom Out: Start with a maximum zoom level and subtract a small value, using on (the current frame number) to initiate the calculation, or use if conditions to cap the limit:

    z='if(eq(on,1),1.5,zoom-0.002)'

  • Static Zoom: To apply a fixed zoom without motion, set a constant value:

    z='1.5'

2. Configuring Coordinate Panning (x and y)

Panning is controlled by defining the top-left x and y coordinates of the zoom box. The maximum range for these coordinates depends on the input width (iw), input height (ih), output width (ow), and output height (oh).

  • Keep Centered (No Pan): To keep the zoom centered on the image, use this formula:

    x='(iw-ow)/2':y='(ih-oh)/2'

  • Pan from Left to Right: Move the x coordinate relative to the current frame number (on) and total duration (d):

    x='(iw-ow)*(on/d)':y='(ih-oh)/2'

  • Pan from Top to Bottom: Move the y coordinate while keeping the horizontal axis centered:

    x='(iw-ow)/2':y='(ih-oh)*(on/d)'

  • Diagonal Ken Burns Effect (Pan and Zoom): Zoom in while panning from top-left to bottom-right:

    zoompan=z='zoom+0.0015':x='(iw-ow)*(on/d)':y='(ih-oh)*(on/d)'

3. Configuring the Frame Count (d)

The d parameter defines the duration of the effect in frames.

  • For Static Images: If your input is a single image, d determines the total length of the generated video clip. For example, if your output frame rate is 25 fps and you want a 6-second video, set d to 150:

    d=150

  • For Videos: When applying zoompan to a video, set d=1 to process the input frame-by-frame continuously, otherwise the filter will duplicate each input frame d times, causing a stuttering effect.

Practical Example

To apply a smooth 5-second zoom-in to the center of a static image at 30 fps (150 frames total) and output at 1920x1080, use the following FFmpeg command:

ffmpeg -i input.jpg -vf "zoompan=z='zoom+0.0015':x='(iw-ow)/2':y='(ih-oh)/2':d=150:s=1920x1080" -c:v libx264 -pix_fmt yuv420p output.mp4