Debugging Macroblocks and Motion Vectors

You can use ffmpeg or ffplay to analyze the macroblocks / coding tree units and motion vectors in a video file.

Analyzing Motion Vectors

The ​`codecview` filter can be used to show motion vectors as small arrows for each macroblock. It takes one option called mv, which specifies the type of motion vector to be drawn:

• pf – forward predicted motion vectors of P pictures
• bf – forward predicted motion vectors of B pictures
• bb – backward predicted motion vectors of B pictures

For example, you can use:

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

Example:

Caveats:

• Earlier versions of ffmpeg do not have this filter, but support the now deprecated -vismv option.
• This option does not work for codecs which do not export motion vectors (most non-MPEG based codecs)

---

The following sections apply to ffmpeg versions older than October 21 2017.

Analyzing Macroblock Types

MPEG videos use various macroblock types, depending on whether they are intra- or inter-predicted and what specific prediction type or partitioning is used. In order to show them, you need to specify the -debug vis_mb_type option. For example:

ffplay -debug vis_mb_type input.mp4
ffmpeg -debug vis_mb_type -i input.mp4 output.mp4

The output would look something like this:

In the output video, each macroblock will be colored according to its type. Additionally, you can see the macroblock partitions as small lines. The following table lists the possible colors and the associated macroblock types. Note that these are parsed in order (from top to bottom), and if one condition matches, the color will be chosen.

Color	Macroblock Type Condition	Explanation	Output of -debug mb_type
	IS_PCM (MB_TYPE_INTRA_PCM)	Lossless (raw samples without prediction)	P
	(IS_INTRA && IS_ACPRED) || IS_INTRA16x16	16x16 Intra prediction	A
	IS_INTRA4x4	4x4 Intra prediction	i
	IS_DIRECT	No motion vectors are sent (B slices)	D
	IS_GMC && IS_SKIP	16x16 Skip macroblock (P or B slices)	g
	IS_GMC	Global motion compensation (not relevant for H.264)	G
	!USES_LIST(1)	Reference to past (List 0, P or B slices)	>
	!USES_LIST(0)	Reference to future (List 1, B slices)	<
	USES_LIST(0) && USES_LIST(1)	Reference to past and future (List 1 & 2, B slices)	X

If none matches, the macroblock will be rendered as grey. Note that the decoding of macroblock types is MPEG-specific, so this option will not work for VP8 video, for example.

Analyzing QP Values

The QP (quantization parameter) of a macroblock is a main factor in controlling the quality. Lower QPs result in higher quality and are tinted greener using this filter. Use the -vis_qp option to show the macroblock QPs:

ffplay -debug vis_qp input.mp4
ffmpeg  -debug vis_qp -i input.mp4 output.mp4

For example: