How to Configure FFmpeg v360 Yaw Pitch and Roll

The FFmpeg v360 filter provides a powerful way to transform, project, and orient 360-degree video footage. By configuring the yaw, pitch, and roll parameters, you can correct tilted horizons, re-center the default viewing angle, or rotate equirectangular and fisheye media along three distinct axes. This guide explains how the rotational parameters operate, how rotation order affects your output, and how to execute practical orientation adjustments from the command line.

Rotational Axes in v360

Rotations are expressed in degrees, accepting both positive and negative values (typically between -180.0 and 180.0):

  • yaw: Rotates the camera horizontally around the vertical axis.
    • Positive values pan the view to the right.
    • Negative values pan the view to the left.
  • pitch: Tilts the camera vertically around the lateral axis.
    • Positive values tilt the camera upward.
    • Negative values tilt the camera downward.
  • roll: Tilts the camera sideways along the optical (depth) axis.
    • Positive values rotate clockwise.
    • Negative values rotate counterclockwise (ideal for leveling crooked horizons).

Basic Command Syntax

To modify rotation while keeping the original projection (for instance, equirectangular to equirectangular), specify the input and output formats alongside your orientation parameters:

ffmpeg -i input.mp4 -vf "v360=input=equirect:output=equirect:yaw=45:pitch=-10:roll=3.5" -c:a copy output.mp4

Rotation Order (rorder)

The sequence in which transformations are evaluated is vital in 3D rotation to prevent gimbal lock or unintended angular shifts. FFmpeg controls this via the rorder option.

  • Default order: ypr (Yaw, Pitch, Roll).
  • Syntax: v360=...:rorder=pyr

If you are leveling a horizon before changing the viewing direction, changing the order to roll first (e.g., rorder=rpy or rorder=ryp) can yield more intuitive corrections.

Practical Examples

1. Shifting the Front Direction (Yaw Adjustment)

Rotate the primary view 90 degrees to the right to re-center the main subject:

ffmpeg -i input.mp4 -vf "v360=e:e:yaw=90" -c:a copy output.mp4

(Note: e:e is shorthand for input=equirect:output=equirect)

2. Leveling a Crooked Horizon (Roll Adjustment)

Fix a camera mount that was tilted 4 degrees counter-clockwise:

ffmpeg -i input.mp4 -vf "v360=e:e:roll=4" -c:a copy output.mp4

3. Correcting Downward Tilt and Horizon Level

Adjust a camera pointing 15 degrees too far down and skewed 2 degrees right, processing the roll adjustment first:

ffmpeg -i input.mp4 -vf "v360=e:e:pitch=15:roll=-2:rorder=rpy" -c:a copy output.mp4

4. Continuous Rotation Over Time

The v360 filter accepts dynamic evaluation expressions. You can use the timestamp variable t (in seconds) to pan the camera continuously at a constant speed:

ffmpeg -i input.mp4 -vf "v360=e:e:yaw='t*10'" -c:a copy output.mp4

This command continuously rotates the camera clockwise at a rate of 10 degrees per second.