How to Use transpose_vaapi in FFmpeg

The transpose_vaapi filter in FFmpeg provides hardware-accelerated video rotation and flipping by utilizing the Video Acceleration API (VA-API), primarily on Intel and AMD graphics hardware under Linux. Using this filter offloads computationally expensive transformation tasks from the CPU directly to the GPU. This guide covers the required initialization parameters, available rotation directions, and complete command-line examples for processing video streams.

Prerequisites and Device Initialization

To use transpose_vaapi, you must specify a VA-API device and ensure the video frames are in a hardware surface format (vaapi).

Hardware initialization requires the -vaapi_device option pointing to your DRI render node (typically /dev/dri/renderD128):

-vaapi_device /dev/dri/renderD128

If the input is decoded in software, frames must be uploaded to the GPU using hwupload and converted to a compatible pixel format (usually nv12) using format=nv12|vaapi.

Available Transpose Directions

The transpose_vaapi filter accepts the dir parameter, which determines the rotation and flip behavior. The values correspond to standard FFmpeg transpose values:

  • cclock_flip (or 0): Rotate 90 degrees counter-clockwise and flip vertically.
  • clock (or 1): Rotate 90 degrees clockwise.
  • cclock (or 2): Rotate 90 degrees counter-clockwise.
  • clock_flip (or 3): Rotate 90 degrees clockwise and flip vertically.

Additionally, you can pass passthrough=none (default) or passthrough=portrait/passthrough=landscape to skip processing if the input geometry already matches the desired orientation.

Complete Command Examples

1. Software Decode, Hardware Transpose, and Hardware Encode

When working with standard files where hardware decoding is not explicitly defined, upload the video frames to the GPU, apply transpose_vaapi, and encode using a VA-API encoder such as h264_vaapi:

ffmpeg -vaapi_device /dev/dri/renderD128 -i input.mp4 \
  -vf "format=nv12,hwupload,transpose_vaapi=dir=clock" \
  -c:v h264_vaapi -c:a copy output.mp4

This rotates the video 90 degrees clockwise.

2. Full Hardware Pipeline (Hardware Decode to Encode)

For maximum performance, decode the input directly into hardware surfaces using -hwaccel vaapi:

ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi \
  -i input.mp4 \
  -vf "transpose_vaapi=dir=cclock" \
  -c:v h264_vaapi -c:a copy output.mp4

This rotates the video 90 degrees counter-clockwise entirely within GPU memory, avoiding CPU-GPU memory copy overhead.

3. 180-Degree Rotation

The transpose_vaapi filter rotates by 90-degree increments. To achieve a 180-degree rotation, chain the filter twice:

ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi \
  -i input.mp4 \
  -vf "transpose_vaapi=dir=clock,transpose_vaapi=dir=clock" \
  -c:v h264_vaapi -c:a copy output.mp4

4. Hardware Transpose with Software Output

If you need to encode using a software encoder (such as libx264), download the frames back to system memory after transposing:

ffmpeg -vaapi_device /dev/dri/renderD128 -i input.mp4 \
  -vf "format=nv12,hwupload,transpose_vaapi=dir=clock,hwdownload,format=nv12" \
  -c:v libx264 -crf 20 -c:a copy output.mp4