How to Use the FFmpeg lutyuv Filter

This article provides a practical guide on how to use the lutyuv filter in FFmpeg to manipulate video colors and brightness. You will learn the basic syntax of the filter, the key variables available for custom expressions, and see step-by-step examples of how to adjust luminance, saturation, and contrast directly in the YUV color space.

Understanding the lutyuv Filter

The lutyuv filter applies a Look-Up Table (LUT) to the YUV channels of an input video. YUV is a color space where Y represents luminance (brightness), while U and V represent chrominance (color blue and color red differences). By modifying these channels individually using mathematical expressions, you can perform precise color grading, color correction, and artistic effects.

Basic Syntax

The basic syntax for the lutyuv filter is:

ffmpeg -i input.mp4 -vf "lutyuv=y='expression':u='expression':v='expression'" output.mp4

You do not need to specify all three channels. If you omit a channel, it will remain unchanged.

Key Variables for Expressions

When writing expressions for y, u, or v, you can use several built-in variables:

• val: The input value of the current pixel (typically 0 to 255 for 8-bit video).
• w / h: The width and height of the video.
• minval: The minimum allowed value for the channel (usually 0).
• maxval: The maximum allowed value for the channel (usually 255 for 8-bit video).

Practical Examples

Here are some of the most common ways to use the lutyuv filter.

1. Adjusting Video Brightness (Luminance)

To make a video brighter or darker, you modify the Y channel. Adding a value increases brightness, while subtracting decreases it.

Increase brightness by 30:

ffmpeg -i input.mp4 -vf "lutyuv=y='val+30'" output.mp4

Decrease brightness by 30:

ffmpeg -i input.mp4 -vf "lutyuv=y='val-30'" output.mp4

2. Converting Video to Grayscale

In YUV, the color information is stored entirely in the U and V channels. Setting both of these channels to their midpoint value (128 for 8-bit video) removes all color, resulting in a black-and-white video.

ffmpeg -i input.mp4 -vf "lutyuv=u=128:v=128" output.mp4

3. Modifying Contrast

To increase contrast, you can stretch the luminance values away from the midpoint (128). This makes light areas lighter and dark areas darker. The clip function is used to ensure the values do not go below 0 or above 255.

ffmpeg -i input.mp4 -vf "lutyuv=y='clip((val-128)*1.5+128, 0, 255)'" output.mp4

To decrease contrast, scale the values closer to the midpoint:

ffmpeg -i input.mp4 -vf "lutyuv=y='clip((val-128)*0.5+128, 0, 255)'" output.mp4

4. Inverting Video Colors (Negate Effect)

To completely invert the colors and brightness of a video, subtract the current pixel value from the maximum channel value (255).

ffmpeg -i input.mp4 -vf "lutyuv=y='255-val':u='255-val':v='255-val'" output.mp4

5. Color Tinting

You can tint the video by shifting the U (blue-difference) or V (red-difference) channels.

Give the video a warm, reddish tint:

ffmpeg -i input.mp4 -vf "lutyuv=v='val+30'" output.mp4

Give the video a cool, bluish tint:

ffmpeg -i input.mp4 -vf "lutyuv=u='val+30'" output.mp4