How to Use FFmpeg Mestimate for Motion Vectors

This guide explains how to use FFmpeg's mestimate filter to calculate motion vectors between consecutive video frames. You will learn the filter's core syntax, available motion estimation algorithms, essential parameters, and how to combine mestimate with the codecview filter to visualize the generated vector data directly on your video.

Understanding the mestimate Filter

The mestimate (Motion Estimation) filter generates motion vector metadata directly from raw video frames instead of extracting preexisting vectors from an encoded bitstream. It evaluates displacement between blocks in adjacent frames and attaches the calculated vectors as side data. Because mestimate only calculates the data, it is typically paired with the codecview filter to render the motion vectors visually on screen.

Basic Syntax and Visualization

To run motion estimation and draw the resulting vectors onto an output file, chain mestimate with codecview in your filtergraph:

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

In this command:

  • mestimate=method=epzs calculates the motion vectors using the Enhanced Predictive Zonal Search algorithm.
  • codecview=mv=pf instructs FFmpeg to draw forward predicted motion vectors (P-frames) generated by the estimation process.

Filter Parameters

The mestimate filter supports several tuning options to balance calculation speed and accuracy:

  • method: Specifies the motion search algorithm.
    • esa: Exhaustive Search Algorithm. Checks every possible match within the search area; the most accurate but extremely slow.
    • tss: Three-Step Search. Fast, heuristic-based search.
    • tdls: Two-Dimensional Logarithmic Search.
    • ntss: New Three-Step Search. Optimized for smaller motions.
    • fss: Four-Step Search.
    • ds: Diamond Search.
    • hexbs: Hexagon-Based Search.
    • epzs: Enhanced Predictive Zonal Search (default). Offers the best balance of speed and tracking accuracy.
    • umh: Uneven Multi-Hexagon Search.
  • mb_size: Sets the macroblock size in pixels for estimation (typically 16 or 8). The default is 16.
  • search_param: Sets the search radius or range parameter. Higher values allow detection of faster-moving objects across larger distances at the cost of processing time. The default is 7.

Practical Examples

High-Speed Motion Estimation

For fast processing when tracking general motion, use the default EPZS algorithm with standard 16x16 macroblocks:

ffmpeg -i input.mp4 -vf "mestimate=method=epzs:mb_size=16:search_param=7,codecview=mv=pf" output.mp4

For detailed motion analysis on complex scenes, reduce the block size to 8, expand the search window, and use exhaustive search:

ffmpeg -i input.mp4 -vf "mestimate=method=esa:mb_size=8:search_param=16,codecview=mv=pf" output.mp4

Displaying Bidirectional Vectors

If working with B-frame sequences where forward and backward vectors exist, enable both forward and backward visualization flags in codecview:

ffmpeg -i input.mp4 -vf "mestimate=method=epzs,codecview=mv=pf+bf+bb" output.mp4
  • pf: Forward predicted MVs of P-frames.
  • bf: Forward predicted MVs of B-frames.
  • bb: Backward predicted MVs of B-frames.