FFmpeg Colorlevels: Adjust Black, White, and Midtones

Adjusting the color profile of a video is a crucial step in post-production, and FFmpeg provides a precise tool for this called the colorlevels filter. This article explains how to use the colorlevels filter to modify the black point, white point, and overall contrast of your video files. We will cover the filter’s syntax, parameter ranges, and practical command-line examples, including how to combine it with other filters to achieve non-linear midtone (gamma) adjustments.

Understanding the colorlevels Parameters

The colorlevels filter works by mapping an input range of pixel intensities to an output range for each individual color channel: Red (R), Green (G), Blue (B), and Alpha (A).

The filter accepts 16 parameters in the following order, with value ranges from 0.0 to 1.0:

colorlevels=rimin:gimin:bimin:aimin:rimax:gimax:bimax:aimax:romin:gomin:bomin:aomin:romax:gomax:bomax:aomax

• Input Minimum (imin): Controls the black point. Input values at or below this level become the output minimum.
• Input Maximum (imax): Controls the white point. Input values at or above this level become the output maximum.
• Output Minimum (omin): The target level for the black point.
• Output Maximum (omax): The target level for the white point.

By default, all minimums are set to 0.0 and all maximums are set to 1.0 (no change).

Adjusting the Black and White Points

To modify the contrast, you manipulate the relationship between the input limits and output limits.

1. Increasing Contrast (Crushing Blacks & Brightening Whites)

To make shadows darker and highlights brighter, increase the input minimums and decrease the input maximums. This forces near-black pixels to pure black and near-white pixels to pure white.

ffmpeg -i input.mp4 -vf "colorlevels=rimin=0.05:gimin=0.05:bimin=0.05:rimax=0.95:gimax=0.95:bimax=0.95" -c:a copy output.mp4

In this example, any input value below 0.05 becomes pure black (0.0), and any value above 0.95 becomes pure white (1.0).

2. Decreasing Contrast (Lifting Blacks & Dimming Whites)

To achieve a faded, low-contrast, or vintage look, you can raise the output minimums and lower the output maximums.

ffmpeg -i input.mp4 -vf "colorlevels=romin=0.1:gomin=0.1:bomin=0.1:romax=0.9:gomax=0.9:bomax=0.9" -c:a copy output.mp4

Here, the darkest black will only go down to 0.1 (dark gray), and the brightest white will only reach 0.9 (light gray).

Adjusting Midtones (Gamma)

The colorlevels filter performs a linear scale between the minimum and maximum points. Because it does not have a dedicated, non-linear “gamma” parameter, adjusting midtones independently requires one of two approaches:

Option 1: Combine colorlevels with the eq filter

The most common way to adjust black/white points using colorlevels while precisely targeting midtones is to chain it with FFmpeg’s eq (evaluation/equation) filter using the gamma parameter.

ffmpeg -i input.mp4 -vf "colorlevels=rimin=0.05:rimax=0.95,eq=gamma=1.2" -c:a copy output.mp4

This command uses colorlevels to establish a clean black and white point, then uses eq to boost the midtones (gamma > 1.0 brightens midtones; gamma < 1.0 darkens them).

Option 2: Use the curves filter as an alternative

If you need complex, non-linear midtone adjustments along with black/white point mapping in a single filter, the curves filter is a stronger choice. It allows you to define points along a Photoshop-style curve.

ffmpeg -i input.mp4 -vf "curves=all='0/0 0.25/0.2 0.5/0.55 0.75/0.8 1/1'" -c:a copy output.mp4

Color Cast Correction

Because colorlevels allows you to target individual RGB channels, you can also use it to correct color temperatures or casts (e.g., removing an unwanted blue or yellow tint).

• To fix a warm/yellow cast: Slightly raise the input minimum or lower the input maximum of the blue channel to bring blue back into the shadows/highlights.
• To fix a cold/blue cast: Reduce the maximum output level of the blue channel.

ffmpeg -i input.mp4 -vf "colorlevels=bimax=0.9" -c:a copy output.mp4