Visualize Macroblocks in FFmpeg with codecview

This guide explains how to use the FFmpeg codecview filter to visualize macroblock allocations and motion vectors in video streams. You will learn the specific command-line syntax, understand the different visualization options available, and see how this diagnostic tool helps analyze video compression efficiency.

The codecview filter in FFmpeg is a powerful tool for analyzing how video encoders partition frames into macroblocks and predict motion. To visualize macroblock allocations (such as intra-coded, predicted, or bi-directional blocks), you use the block_type (or bt) option within the filter.

Visualizing Macroblock Types

To view macroblock allocations in real-time using ffplay, use the following command:

ffplay -i input.mp4 -vf codecview=block_type=mb

If you want to render this visualization directly into a new video file using ffmpeg, use this command:

ffmpeg -i input.mp4 -vf codecview=block_type=mb output.mp4

When you run this filter, the video will display an overlay grid. The colors represent different macroblock types: * Red / Reddish tones: Intra-coded macroblocks (I-blocks), which contain complete spatial image data. * Green / Greenish tones: Predicted macroblocks (P-blocks), which reference previous frames. * Blue / Blueish tones: Bi-directionally predicted macroblocks (B-blocks), which reference both past and future frames.

Visualizing Partition Types

If you want to see the smaller sub-pixel partitions within the macroblocks instead of the standard macroblock boundaries, change the block_type value to partition:

ffplay -i input.mp4 -vf codecview=block_type=partition

Combining Macroblocks with Motion Vectors

For a complete diagnostic analysis, you can combine macroblock visualization with motion vectors. Because motion vectors require explicit decoding export flags, you must include the -flags2 +export_mvs option in your command:

ffplay -flags2 +export_mvs -i input.mp4 -vf codecview=block_type=mb:mv=pf+bf+bb

In this combined view, arrows will indicate the direction and magnitude of motion estimation across the P-frames (pf), forward B-frames (bf), and backward B-frames (bb) alongside the color-coded macroblock grid.

Note: The codecview filter relies on the CPU software decoder. It will not display correctly if hardware-accelerated decoding (such as NVDEC or DXVA2) is active.