Configure FFmpeg Perspective Filter Coordinates

This article provides a practical guide on how to configure the eight coordinate points of the perspective filter in FFmpeg. You will learn the exact syntax for mapping source coordinates to destination coordinates, enabling you to correct camera tilt, simulate 3D angles, or warp video frames to fit specific shapes.

Understanding the Coordinate Points

The FFmpeg perspective filter relies on defining four corners of the source image and mapping them to four corners of the destination image. This requires configuring a total of 8 coordinate pairs (16 individual values).

The coordinate pairs are grouped into source (x, y) and destination (tx, ty) points.

1. Source Coordinates (Inputs)

These represent the four corners of the input video frame, usually defined by the video width (\(W\)) and height (\(H\)): * Top-Left (\(x_0, y_0\)): Usually 0:0 * Top-Right (\(x_1, y_1\)): Usually W:0 (e.g., 1920:0 for 1080p) * Bottom-Left (\(x_2, y_2\)): Usually 0:H (e.g., 0:1080 for 1080p) * Bottom-Right (\(x_3, y_3\)): Usually W:H (e.g., 1920:1080 for 1080p)

2. Destination Coordinates (Outputs)

These define where the four source corners should be placed in the final output frame: * Top-Left (\(tx_0, ty_0\)): New position of the top-left corner. * Top-Right (\(tx_1, ty_1\)): New position of the top-right corner. * Bottom-Left (\(tx_2, ty_2\)): New position of the bottom-left corner. * Bottom-Right (\(tx_3, ty_3\)): New position of the bottom-right corner.

Filter Syntax

The basic syntax for the perspective filter is structured as follows:

perspective=x0:y0:x1:y1:x2:y2:x3:y3:tx0:ty0:tx1:ty1:tx2:ty2:tx3:ty3[:sense][:interpolation]

Alternatively, you can use named parameters for better readability:

perspective=x0=val:y0=val:x1=val:y1=val:x2=val:y2=val:x3=val:y3=val:tx0=val:ty0=val:tx1=val:ty1=val:tx2=val:ty2=val:tx3=val:ty3=val

Practical Example

To squeeze the top of a \(1280 \times 720\) video inward to create a trapezoid effect, map the corners as follows:

  1. Define Source Coordinates (\(1280 \times 720\)):
    • Top-Left: 0:0
    • Top-Right: 1280:0
    • Bottom-Left: 0:720
    • Bottom-Right: 1280:720
  2. Define Destination Coordinates:
    • Top-Left: Shift right by 200px \(\rightarrow\) 200:0
    • Top-Right: Shift left by 200px \(\rightarrow\) 1080:0
    • Bottom-Left: Keep original \(\rightarrow\) 0:720
    • Bottom-Right: Keep original \(\rightarrow\) 1280:720

FFmpeg Command

Combine these parameters into the video filter (-vf) argument:

ffmpeg -i input.mp4 -vf "perspective=0:0:1280:0:0:720:1280:720:200:0:1080:0:0:720:1280:720" -c:a copy output.mp4

Important Parameters