Use FFmpeg colorconstancy for Gray-World Color Balance

This guide explains how to use the colorconstancy video filter in FFmpeg to automatically correct color casts in your videos using the gray-world algorithm. You will learn the correct command syntax, key parameters, and practical examples to achieve natural-looking color balance in your video processing workflows.

Understanding the Gray-World Algorithm

The gray-world color constancy hypothesis assumes that the average color of a scene in a natural image is a neutral gray. When a video has an unnatural color cast—such as being too blue due to daylight shadows or too orange due to indoor tungsten lighting—the colorconstancy filter estimates the light source color and shifts the color channels to restore a neutral balance.

Basic Command Syntax

To apply the gray-world color balance using the default settings, use the following FFmpeg command:

ffmpeg -i input.mp4 -vf "colorconstancy=diffuse=0" output.mp4

In this command: * -i input.mp4 specifies your source video file. * -vf "colorconstancy=diffuse=0" applies the video filter. The diffuse=0 parameter explicitly selects the gray-world algorithm. * output.mp4 is the color-corrected output video.

Key Parameters

You can fine-tune the color correction by adjusting the filter’s parameters:

• diffuse: Specifies the algorithm used for color constancy.
  • 0: Gray-world algorithm (default).
  • 1: Max-RGB algorithm (assumes the maximum value of each channel should be equal).
• gauss: Sets the size of the Gaussian blur kernel (sigma) used to smooth the image before estimating the illuminant. This helps prevent digital noise or compression artifacts from skewing the color correction. The default is 0 (disabled).

Practical Examples

Example 1: Gray-World with Noise Filtering

If your video has low-light noise that interferes with the color balance estimation, apply a small Gaussian blur during the estimation phase:

ffmpeg -i input.mp4 -vf "colorconstancy=diffuse=0:gauss=2.0" output.mp4

Example 2: Side-by-Side Comparison

To compare the original video directly with the color-corrected version, you can split the input video and stack them side-by-side using the hstack filter:

ffmpeg -i input.mp4 -filter_complex "[0:v]split[orig][to_correct]; [to_correct]colorconstancy=diffuse=0[corrected]; [orig][corrected]hstack" output.mp4