Display Motion Vectors in FFmpeg Using codecview

This article explains how to visualize motion vectors overlayed on a video using FFmpeg’s codecview filter. You will learn the specific command-line flags required to extract and draw motion vectors from H.264, MPEG-4, or other supported codecs, along with a breakdown of the visualization options.

To display motion vectors on a video, you must tell the decoder to export the motion vector data before passing the video stream to the codecview filter. This is achieved using the -flags2 +export_mvs option placed before the input file.

The Basic Command

Use the following command to overlay all available motion vectors onto your video:

ffmpeg -flags2 +export_mvs -i input.mp4 -vf codecview=mv=pf+bf+bb output.mp4

Command Breakdown

• -flags2 +export_mvs: This is an input option that forces the decoder to export motion vector frame side data. Without this flag, the codecview filter will have no motion data to draw.
• -i input.mp4: Specifies your source video file.
• -vf codecview=mv=pf+bf+bb: Applies the video filter. The mv parameter defines which motion vectors to display:
  • pf: Forward predicted motion vectors of P-frames (predicted frames).
  • bf: Forward predicted motion vectors of B-frames (bi-directional frames).
  • bb: Backward predicted motion vectors of B-frames.
• output.mp4: The resulting video file showing the visual arrows representing motion direction and magnitude.

Real-Time Preview

If you want to view the motion vectors in real-time without saving to a file, you can play the video directly using ffplay:

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

Customizing the Visualization

You can refine what type of motion vectors are displayed by changing the values assigned to the mv parameter:

• Show only P-frame motion vectors:

  ffmpeg -flags2 +export_mvs -i input.mp4 -vf codecview=mv=pf output.mp4

• Show only B-frame motion vectors (forward and backward):

  ffmpeg -flags2 +export_mvs -i input.mp4 -vf codecview=mv=bf+bb output.mp4

This visualization tool is highly useful for analyzing codec behavior, understanding motion estimation, or debugging video compression issues.