Configure MB-Tree Rate Control in FFmpeg libx264

This article explains how to configure the Macroblock Tree (MB-Tree) rate control option within the libx264 encoder in FFmpeg. You will learn what MB-Tree does, why you might want to enable or disable it, and the precise FFmpeg commands and parameters required to control its behavior to optimize your video encoding quality and file size.

What is MB-Tree Rate Control?

Macroblock Tree (MB-Tree) is a temporary rate control algorithm in the libx264 encoder. It analyzes the propagation of data across video frames over time. By tracking which macroblocks (blocks of pixels) are referenced repeatedly across multiple frames—such as a static background—MB-Tree allocates more bitrate to these “source” blocks. Conversely, it reduces the bitrate for blocks that are quickly replaced or rarely referenced (like fast-moving objects).

By default, MB-Tree is enabled in libx264 when using Constant Rate Factor (CRF) or Average Bitrate (ABR) encoding. While it generally improves compression efficiency by 10% to 20%, it can occasionally cause visual issues like color banding or blockiness in dark, flat, or high-motion scenes.

How to Disable MB-Tree in FFmpeg

If you notice pulsing artifacts, quality degradation in dark scenes, or excessive compression artifacts in detailed textures, you can disable MB-Tree. To turn off MB-Tree, pass the no-mbtree=1 flag inside the -x264-params or -x264opts private option flags.

Here is the standard FFmpeg command to disable MB-Tree:

ffmpeg -i input.mp4 -c:v libx264 -crf 20 -x264-params no-mbtree=1 -c:a copy output.mp4

How to Enable MB-Tree

Because MB-Tree is active by default, you do not need to explicitly declare it. However, if you want to ensure it is active—especially when overriding previous presets or configurations—you can explicitly enable it using:

ffmpeg -i input.mp4 -c:v libx264 -crf 20 -x264-params mbtree=1 -c:a copy output.mp4

Fine-Tuning MB-Tree with Lookahead

MB-Tree relies heavily on the “lookahead” buffer, which dictates how many frames the encoder analyzes ahead of the current frame to map macroblock propagation. The default lookahead value is 40 frames.

To make MB-Tree more effective (at the cost of higher RAM usage and slight latency), you can increase the lookahead frame count:

ffmpeg -i input.mp4 -c:v libx264 -crf 20 -x264-params mbtree=1:rc-lookahead=60 -c:a copy output.mp4

To decrease memory usage or latency, you can lower the lookahead value:

ffmpeg -i input.mp4 -c:v libx264 -crf 20 -x264-params mbtree=1:rc-lookahead=20 -c:a copy output.mp4

When to Keep MB-Tree Enabled vs. Disabled