Display Motion Vectors in FFmpeg Using Codecview

This guide demonstrates how to extract and visualize motion vectors on a video stream using FFmpeg's built-in codecview filter. You will learn the required input flags to export motion vector data during decoding, the filter syntax to customize the vector overlay, and practical commands for both previewing and exporting the annotated video.

Required FFmpeg Flags

By default, FFmpeg decodes video frames without storing motion vector data to save memory and processing power. To make this data available to the codecview filter, you must instruct the decoder to export it using the -flags2 +export_mvs option placed before the input flag (-i).

Visualizing Vectors in Real Time with FFplay

To preview motion vectors immediately without rendering a new file, use ffplay:

ffplay -flags2 +export_mvs -vf "codecview=mv=pf+bf+bb" input.mp4

Rendering Motion Vectors to a New Video File

To burn the motion vectors into a new video file, run the ffmpeg command with an appropriate video encoder:

ffmpeg -flags2 +export_mvs -i input.mp4 -vf "codecview=mv=pf+bf+bb" -c:a copy output.mp4

Understanding codecview Motion Vector Types

The mv parameter accepts combinations of motion vector types joined by the + operator:

  • pf: Forward predicted motion vectors of P-frames (rendered in green by default).
  • bf: Forward predicted motion vectors of B-frames (rendered in blue by default).
  • bb: Backward predicted motion vectors of B-frames (rendered in red by default).

To display only forward-predicted motion vectors across P-frames, simplify the filter:

-vf "codecview=mv=pf"

Additional Options

You can adjust how the vectors are drawn by appending options to the filter string:

  • mv_type: Specifies whether to draw macroblock-level vectors (fp for frame, or bp for field).
  • block: Visualizes macroblock subdivisions alongside the vector arrows:
ffmpeg -flags2 +export_mvs -i input.mp4 -vf "codecview=mv=pf+bf+bb:block=1" -c:a copy output.mp4

Codec Compatibility Notes

  • Supported Formats: Motion vector export works reliably with codecs that use block-based motion compensation, such as H.264 (AVC) and MPEG-4 Part 2.
  • Hardware Acceleration: Disable hardware decoding (do not use -hwaccel) when running these commands, as hardware decoders do not expose motion vector side data to software filters.