mpv HDR Washed Out: How to Fix It

When HDR video looks washed out in mpv, the picture usually has lifted blacks, weak contrast, muted color, or highlights that seem dull instead of bright. This symptom generally points to a mismatch between the video's HDR signal, mpv's output settings, the operating system's HDR state, and the display's actual capabilities. The most important first step is to decide whether you want HDR passthrough to an HDR display or tone mapping for an SDR display. Those are different output paths, and combining settings from both often makes the problem harder to diagnose.

This guide begins with a clean playback test, then examines configuration files, GPU output, target color settings, operating system behavior, scripts, streams, and screenshots. Change one variable at a time. Once the image has appropriate blacks, natural saturation, visible highlight detail, and consistent results across test files, stop changing settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing mpv.conf, establish whether the problem survives without your normal configuration. This distinguishes a basic output problem from an option, profile, shader, script, or input binding that is altering playback.

1.1 Run mpv Without User Configuration

Open a terminal and run one of the following commands, replacing the example path with a known local HDR file:

mpv --no-config "/path/to/hdr-video.mkv"

On Windows, the command may look like this:

mpv.exe --no-config "C:\Videos\hdr-video.mkv"

Keep the path in quotes if it contains spaces, parentheses, ampersands, or other characters interpreted by the shell. The --no-config option temporarily bypasses your regular mpv configuration. It does not delete or modify any files.

If HDR looks correct in this test, mpv itself, the file, and the basic GPU path are probably functional. The cause is likely inside your configuration, profiles, scripts, shaders, or bindings. Stop changing operating system settings and proceed to the configuration checks.

If the clean test remains washed out, compare the same file in another color-managed or HDR-capable player. This comparison is not meant to declare one player correct automatically. It helps determine whether the symptom is specific to mpv or present throughout the system.

1.2 Verify That the Source Is Actually HDR

Do not diagnose a file from its filename alone. During playback, press i to open mpv's statistics overlay. Depending on the build and active output driver, the overlay can show video properties such as primaries, transfer characteristics, pixel format, hardware decoding, and display output details.

Typical HDR10 material uses BT.2020 primaries with the PQ transfer function, also called SMPTE ST 2084. HLG content uses a different transfer function. Dolby Vision files can contain profiles or enhancement data that a particular playback chain may not process in the same way as base HDR10. A mislabeled, poorly encoded, or incorrectly tagged file can look wrong even when mpv is behaving as instructed.

Test more than one legitimate HDR sample. If only one file appears flat while other HDR files look correct, stop changing global settings. The outlier probably has unusual metadata, incorrect tags, or mastering characteristics that require file-specific handling.

2. Choose HDR Passthrough or SDR Tone Mapping

The central troubleshooting decision is whether mpv should preserve HDR for an HDR-capable display or convert HDR into an SDR image. HDR passthrough depends on the complete output chain, including mpv, its video output driver, the graphics API, GPU driver, operating system, cable or adapter, display input, and display mode. Tone mapping asks mpv to transform HDR into the smaller brightness and color range expected by SDR displays.

2.1 Test HDR Passthrough on an HDR Display

If your monitor or television supports HDR, enable HDR in the operating system before launching the test. On Windows, open Settings, go to System, select Display, choose the intended monitor, and enable the HDR setting if available. Confirm that you changed the setting for the correct display in a multi-monitor setup.

Then try a clean GPU-rendering test:

mpv --no-config --vo=gpu-next --target-colorspace-hint=yes "/path/to/hdr-video.mkv"

The --target-colorspace-hint option asks mpv to provide output color-space information through supported APIs. Whether the complete HDR signaling path works depends on the operating system, graphics API, driver, and display. It is not a universal switch that forces every platform into HDR.

Success means that the operating system and display remain in HDR mode, blacks are not gray, colors are plausible rather than fluorescent, and bright details have intensity without turning into featureless white patches. If this result is correct, do not add SDR target settings such as a 100-nit target peak.

2.2 Test SDR Tone Mapping Separately

If the display is SDR, or if you deliberately keep operating system HDR disabled, mpv must tone-map HDR. Test that path independently:

mpv --no-config --vo=gpu-next --target-prim=bt.709 --target-trc=bt.1886 --target-peak=100 --tone-mapping=auto "/path/to/hdr-video.mkv"

This test declares an SDR-like target using BT.709 primaries, a BT.1886 transfer curve, and a nominal 100-nit peak. It is a diagnostic baseline, not a mandatory permanent configuration for every screen or viewing environment.

Success means that black levels look appropriately dark, faces retain believable color, saturated objects are not gray, and highlight detail remains visible even though an SDR display cannot reproduce full HDR brightness. If this test fixes the picture, keep troubleshooting within the tone-mapping path rather than trying to activate passthrough.

2.3 Avoid Conflicting Target Settings

Review your configuration for these options:

• target-prim
• target-trc
• target-peak
• target-colorspace-hint
• tone-mapping
• hdr-compute-peak
• icc-profile or automatic ICC profile options

A common mpv HDR washed out cause is a target that does not match the active display mode. For example, forcing SDR output parameters while expecting HDR passthrough can produce an inappropriate conversion or signaling result. Conversely, preserving an HDR transfer curve while the operating system and display expect SDR can make the image appear flat or incorrectly bright.

Temporarily comment out custom target options, then add back only the settings required for the selected path. Do not copy a large HDR configuration from an unknown display setup because peak brightness, operating system behavior, and GPU APIs differ.

3. Inspect Configurations, Profiles, Scripts, and Bindings

If --no-config fixes the picture, inspect your customizations methodically. Do not delete the entire configuration folder. Rename or comment individual settings, or create a temporary empty configuration location for controlled tests.

3.1 Search mpv.conf and Profiles

Look in mpv.conf for video output, GPU, shader, color, and HDR options. Pay particular attention to conditional profiles that activate based on file properties, protocol, resolution, or other criteria. A profile may be applying only to HDR files, which explains why SDR playback remains normal.

Use the following command to print a named profile's contents:

mpv --show-profile=profile-name

Replace profile-name with the actual profile name. Check included configuration files as well as the main file. If the profile contains several color controls, disable them as a group, confirm the result, and then restore one option at a time.

3.2 Check input.conf and Runtime Changes

An input.conf binding can change properties during playback. Search for commands involving gamma, brightness, contrast, saturation, video output, tone mapping, target peak, profiles, shaders, and ICC settings. A key used for another application may unknowingly activate one of these commands in mpv.

Also consider IPC clients and controller applications. A frontend, remote-control script, or JSON IPC program can set properties after mpv launches. Run mpv directly from a terminal with those tools closed. If the direct session is correct, inspect the commands sent by the external controller.

3.3 Disable Shaders and Scripts Temporarily

Custom GLSL shaders can change transfer functions, gamut mapping, contrast, and perceived sharpness. Remove shader options from the test command or temporarily prevent the relevant script from loading. Scripts that automatically select profiles based on HDR metadata deserve special attention.

Subtitle settings and audio-track selection normally do not alter HDR color. However, scripts that react to subtitle visibility, track changes, or media type can load a profile or shader indirectly. Test with scripts disabled rather than assuming that a script's name describes every action it performs.

Success is a clean playback session that remains correct when subtitles and audio tracks are switched. Once achieved, restore scripts one at a time until the exact trigger is found.

4. Check the Operating System, GPU, and Display Chain

If washed-out HDR persists with --no-config, inspect the environment below mpv. The same command can produce different results under Windows HDR, macOS display management, X11, Wayland, and different graphics APIs.

4.1 Verify the Display HDR Mode

On Windows, confirm the HDR toggle before each passthrough test. If SDR desktop content looks unusually pale after enabling HDR, use the Windows SDR content brightness control rather than compensating with mpv's gamma or contrast controls. Those controls solve different problems.

On macOS, verify that the connected display and current mode support HDR. Adapters, docks, refresh rates, and display modes can affect available capabilities. On Linux, HDR support varies with the compositor, display server, graphics stack, driver, and output protocol. An HDR-capable panel does not guarantee that every desktop session can signal HDR correctly.

Check the display's own information panel. Many televisions and monitors show an HDR indicator when receiving an HDR signal. If the display never enters HDR mode during a passthrough test, changing tone-mapping curves inside mpv will not repair missing system-level signaling.

4.2 Compare Video Output and Hardware Decoding

Test software decoding and hardware decoding separately:

mpv --no-config --hwdec=no "/path/to/hdr-video.mkv"

mpv --no-config --hwdec=auto "/path/to/hdr-video.mkv"

If only hardware decoding looks wrong, the issue may involve the decoder, pixel format, bit depth, GPU driver, or hardware-to-renderer transfer path. Keep --hwdec=no as a diagnostic workaround if the CPU can decode the file smoothly, then investigate the platform-specific hardware decoder rather than altering unrelated color controls.

High-bitrate video may stutter under software decoding, but stuttering is separate from washed-out color. Do not mistake dropped frames for an HDR conversion failure.

4.3 Update Drivers From Trusted Sources

Use the operating system's update mechanism or the GPU manufacturer's official support channel. Avoid random codec packs and unofficial binary download sites. mpv generally brings the decoding components its build requires, and a codec pack is unlikely to fix a GPU color-space or HDR-signaling mismatch.

After changing a GPU driver, restart the system and repeat the same clean command. Success means that the image is corrected without adding compensating brightness, contrast, or saturation values.

4.4 Check ICC and Color Management Interference

An ICC profile describes display color behavior, but HDR and SDR color-management paths do not always use profiles identically. A profile created for an SDR display mode may produce unexpected results if forced into an HDR path.

Check mpv.conf for explicit ICC profile options and temporarily remove them from the clean test. Also inspect operating system color-management settings for duplicate, obsolete, or incorrectly assigned profiles. Do not permanently discard a calibrated profile based on one test. Instead, compare controlled playback with and without mpv ICC handling.

If disabling an explicit ICC option fixes HDR while SDR becomes less accurate, use separate HDR and SDR profiles or conditions rather than applying one global setting.

5. Separate Local Files, Streams, yt-dlp, and Screenshots

The source path can change what mpv receives. A local file removes network selection, manifests, and external download tools from the test, so it should be your baseline.

5.1 Compare Streams With a Local HDR File

If local HDR files look correct but a URL does not, inspect the selected stream. Adaptive services may offer several video representations with different codecs, resolutions, bit depths, or dynamic-range formats. Network restrictions can also force a fallback representation.

yt-dlp helps mpv resolve supported online URLs, but it does not fix incorrect HDR output after decoding. Confirm that mpv can find the intended yt-dlp executable through the trusted system path or an explicit configuration. Use terminal output to determine which format was selected instead of assuming that a high resolution is necessarily HDR.

For direct network streams and playlists, verify that the server is delivering the expected file and that no transcoding layer is converting HDR incorrectly. If a downloaded or locally copied version of the same legitimate media looks correct, focus on format selection or server transcoding.

5.2 Do Not Judge HDR Solely From Screenshots

An HDR screenshot may be saved, tagged, tone-mapped, or displayed differently from the live video. Image viewers, browsers, and operating systems vary in how they interpret wide-gamut and HDR image data. A screenshot that looks washed out in an SDR application does not prove that mpv's on-screen output is wrong.

Evaluate the live image first. If screenshot accuracy matters, inspect the saved file's format and color metadata in an application that supports that format. Keep screenshot troubleshooting separate from playback troubleshooting unless both fail in the same controlled way.

6. Use Logs and Runtime Information to Find the Cause

When visual tests are inconclusive, capture mpv's own output. Logs can reveal the selected video output, hardware decoder, pixel format, detected color properties, script activity, and failed options.

6.1 Create a Detailed Log

Run:

mpv --no-config --log-file=mpv-hdr.log --msg-level=all=v "/path/to/hdr-video.mkv"

Reproduce the problem briefly, close mpv normally, and inspect the log. Search for terms such as primaries, transfer, hdr, peak, icc, hwdec, gpu, d3d11, vulkan, and wayland. Warnings are clues, not automatic proof of the root cause.

Then create a second log with your normal configuration. Compare the active options and output initialization. This is often faster than visually testing dozens of lines in mpv.conf.

6.2 Use the Stats Overlay and Track Information

Open the stats overlay with i during the clean and configured tests. Confirm that both sessions select the same video track, decoder, resolution, pixel format, and hardware-decoding state. For files containing multiple video tracks, make sure mpv has not selected a compatibility or preview track.

Audio selection does not directly wash out video, but track-selection scripts can reload profiles. If the color changes immediately after selecting audio or subtitle tracks, reproduce that sequence with scripts disabled and record a log.

7. Run a Clean Temporary Test Before Making Permanent Changes

Use a small test matrix instead of changing many options simultaneously. Choose one known HDR file and run these tests in order:

1. Run --no-config with the operating system in its normal display mode.
2. For an HDR display, enable system HDR and test --target-colorspace-hint=yes.
3. For an SDR target, disable HDR passthrough expectations and test explicit BT.709, BT.1886, and 100-nit tone mapping.
4. Compare --hwdec=no with --hwdec=auto.
5. Run the winning command with your normal configuration, then disable profiles, scripts, shaders, and ICC overrides selectively.
6. Confirm the result with a second known HDR file.

Record which command works. Make only the smallest permanent change needed to reproduce it. If a clean SDR tone-mapping test succeeds, there is no benefit in simultaneously experimenting with passthrough. If passthrough succeeds and the display confirms HDR input, do not force SDR target values.

8. Quick Fix Checklist

• Test a known local HDR file with mpv --no-config.
• Decide whether the goal is HDR passthrough or SDR tone mapping.
• Enable the Windows HDR toggle before testing passthrough.
• Confirm that the correct monitor is in HDR mode.
• Remove conflicting target-prim, target-trc, and target-peak values.
• Temporarily disable ICC overrides, shaders, scripts, and automatic profiles.
• Compare software decoding with --hwdec=auto.
• Use the stats overlay to inspect transfer characteristics and primaries.
• Compare local playback with the selected online stream format.
• Do not use screenshots alone to judge live HDR output.
• Capture a verbose log and compare clean versus configured playback.
• Stop when two known HDR files display correctly through the intended output path.

9. Frequently Asked Questions

9.1 Why Does HDR Look Washed Out in mpv?

The most common reason is a mismatch between HDR video and the expected display output. mpv may be preserving an HDR signal while the operating system or display expects SDR, or it may be applying SDR-oriented target settings while you expect HDR passthrough. Configuration profiles, ICC handling, shaders, GPU drivers, and incorrect media metadata can also contribute.

9.2 Should I Enable Windows HDR for mpv?

Enable Windows HDR when testing HDR passthrough to a compatible display. If you want mpv to tone-map HDR into SDR, you can keep Windows HDR disabled and use an SDR target. Avoid switching between these goals without also reviewing mpv's target settings.

9.3 What Target Peak Should I Use?

For a basic SDR diagnostic test, 100 nits is a useful reference. It is not necessarily the ideal final value for every monitor or room. HDR passthrough should not be configured as though the display were a 100-nit SDR target. Start with the output path, then refine peak behavior only if the baseline conversion is correct.

9.4 Can Hardware Decoding Cause Washed-Out HDR?

It can expose a decoder, driver, pixel-format, or GPU-transfer problem. Compare --hwdec=no and --hwdec=auto using the same file and otherwise identical options. If only one path fails, troubleshoot that path rather than compensating with saturation or gamma.

9.5 Why Does the mpv Screenshot Look Flat When Playback Looks Correct?

The screenshot may contain HDR or wide-gamut data that the image viewer does not interpret correctly. It may also follow a different conversion path from the displayed frame. Check the file in an HDR-aware viewer and inspect its metadata before changing working playback settings.

9.6 When Should I Stop Troubleshooting?

Stop when two or more known HDR files show appropriate blacks, believable colors, controlled highlights, and stable playback through your intended path. If only one file or stream remains wrong, treat it as a source-specific metadata, format-selection, or transcoding issue rather than rewriting a configuration that already works.