How does mpv handle color management when using an ICC display profile?

The mpv media player leverages its advanced GPU rendering pipeline (via the vo=gpu or vo=gpu-next video outputs) to convert video colors from the source format to your monitor’s native hardware space using an International Color Consortium (ICC) display profile. Instead of passing the entire image parsing process to external operating system hooks, mpv uses the LittleCMS (lcms2) library or internal libplacebo routines to interpret the ICC profile file. It then generates a highly accurate 3D Lookup Table (3D LUT) dynamically on the GPU. This pipeline maps the source video’s color characteristics (such as Rec. 709, DCI-P3, or BT.2020) and transfer characteristics directly to the measured color primaries and gamma curve of the display, preventing oversaturation on wide-gamut monitors and ensuring color accuracy.

Direct ICC Profile Loading

Users can explicitly configure mpv to use an ICC profile by using the --icc-profile flag and pointing it directly to the .icc or .icm file path. Alternatively, the --icc-profile-auto option allows mpv to query the host operating system (such as Windows, macOS, or compatible X11/Wayland desktop environments) to automatically fetch the default display profile currently assigned to the active monitor.

The Conversion Pipeline

When color management is active, the video frames bypass the generic assumptions of standard sRGB display outputs. Instead, the color transform logic takes the following steps:

• Source Decoding: The video’s native color space, color primaries, and transfer characteristics (gamma or Electro-Optical Transfer Function) are identified from the file metadata.
• 3D LUT Generation: mpv computes a precise matrix mathematical transformation that maps the source color coordinates into the target coordinates described by the monitor’s ICC profile.
• Precision Rendering: The transformation is applied at high bit-depth directly on the GPU shader level, preventing banding or clipping artifacts that typically happen when doing software-based color alterations.

Intent, Contrast, and Black Point Adjustments

By default, mpv applies a relative colorimetric rendering intent, which ensures that colors within the display’s physical capability remain perfectly accurate while out-of-gamut colors are mapped to the closest reproducible boundary. Additionally, because some ICC profiles include measured black-level depths that do not fall to absolute zero, mpv estimates the display’s actual contrast ratio to automatically adjust tone mapping (such as adapting BT.1886 target curves) to prevent “grayish” blacks or unwanted black crushing during playback. Users can fine-tune these properties using specific parameters like --icc-contrast or configuring fallback parameters within the mpv.conf file.