How to Use the FFmpeg Codecview Filter

The FFmpeg codecview filter is a powerful diagnostic tool used to visualize internal codec information, such as motion vectors, directly on top of the decoded video frames. This article provides a straightforward guide on how to use the codecview filter to analyze video compression, troubleshoot motion estimation issues, and visualize how video decoders process motion.

Understanding the Codecview Filter

Modern video codecs (like H.264, HEVC, and MPEG-4) achieve high compression rates by predicting motion between frames. The codecview filter allows you to see these hidden prediction decisions—specifically motion vectors—by overlaying colored arrows on your video.

To use this filter, you must explicitly tell the FFmpeg decoder to export this motion data. If you omit the export flag, the filter will have no data to visualize, resulting in a standard video output.

Visualizing Motion Vectors

The most common use case for codecview is displaying motion vectors. To do this, you must pass the -flags2 +export_mvs option to the input, followed by the codecview filter graph.

Using FFplay for Real-Time Viewing

If you want to quickly analyze a video without saving a new file, ffplay is the most efficient tool. Run the following command:

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

Saving the Visualized Video with FFmpeg

To render the visualization into a new video file, use the ffmpeg command:

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

Explanation of the Options

-flags2 +export_mvs: This is a global input flag that tells the demuxer/decoder to export motion vector frames. This must be placed before the input file (-i).
codecview=mv=...: This activates the filter. The mv parameter defines which motion vectors to draw.
pf (P-frame forward predicted): Shows motion estimation in P-frames (represented by green arrows).
bf (B-frame forward predicted): Shows forward motion estimation in B-frames (represented by blue arrows).
bb (B-frame backward predicted): Shows backward motion estimation in B-frames (represented by red arrows).

You can combine these options using the + sign (e.g., mv=pf+bf+bb) or isolate a single type (e.g., codecview=mv=pf to see only P-frame forward vectors).