How to Visualize Motion Vectors with FFmpeg Mestimate

The mestimate filter in FFmpeg calculates motion vectors between consecutive video frames and exports them as frame metadata, allowing you to visualize motion directly on screen when paired with the codecview filter. This guide explains how to construct the command, choose estimation algorithms, and configure macroblock settings to generate a clear overlay of motion vectors on any video file.

Basic Command Syntax

Because mestimate calculates motion vectors and stores them as side data rather than rendering them directly onto the image, you must chain it with the codecview filter to draw the vectors.

Run the following command to visualize forward motion vectors:

ffmpeg -i input.mp4 -vf "mestimate,codecview=mv=pf" -c:a copy output.mp4

In this command:

  • mestimate analyzes the frames and computes the displacement vectors.
  • codecview=mv=pf renders forward predicted (pf) motion vectors as visual arrows overlaid on the frames.
  • -c:a copy preserves the original audio stream without re-encoding.

Customizing the mestimate Parameters

You can fine-tune the accuracy and performance of the motion estimation by passing specific arguments to the mestimate filter:

ffmpeg -i input.mp4 -vf "mestimate=method=epzs:mb_size=16:search_param=7,codecview=mv=pf" -c:a copy output.mp4
  • method: Specifies the motion estimation search method. Options include:
    • epzs (Enhanced Predictive Zonal Search, default): Fast and balanced.
    • esa (Exhaustive Search Algorithm): Highly accurate but computationally slow.
    • tss (Three Step Search): Faster alternative to exhaustive search.
    • tdls (Two Dimensional Logarithmic Search).
    • ntss (New Three Step Search).
    • fss (Four Step Search).
    • ds (Diamond Search).
    • hexbs (Hexagon-Based Search).
    • umh (Uneven Multi-Hexagon Search).
  • mb_size: Sets the macroblock size in pixels (default is 16). Lowering this value to 8 provides higher-density motion vector overlays at the cost of processing time.
  • search_param: Sets the search parameter radius (default is 7). A higher value expands the search area for finding motion between frames, which is useful for fast-moving scenes.

Advanced Visualization Options

You can modify codecview options to change how the motion vectors appear or to render both forward and backward vectors:

ffmpeg -i input.mp4 -vf "mestimate=method=hexbs:mb_size=8,codecview=mv=pf+bf" -c:v libx264 -crf 18 output.mp4
  • Setting mv=pf+bf renders both forward predicted (pf) and backward predicted (bf) vectors.
  • Pairing a smaller mb_size=8 with an efficient method like hexbs yields a fine-grained grid of arrows suitable for tracking complex movements.