mpv Tone Mapping Looks Wrong: How to Fix It

When mpv tone mapping looks wrong, HDR video converted for an SDR display may appear washed out, excessively dark, oversaturated, gray, or stripped of highlight detail. The usual causes are an incorrect SDR target, unsuitable peak-brightness assumptions, gamut mapping, a conflicting profile or shader, hardware-decoding behavior, inaccurate display settings, or HDR metadata that does not describe the video well. The safest approach is to reproduce the symptom with one known HDR sample and a clean mpv command, then restore custom features one at a time. This guide focuses specifically on HDR-to-SDR tone mapping in mpv on Windows, Linux, and macOS.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing mpv.conf, changing GPU drivers, or replacing shaders, determine whether the problem survives without your normal configuration. Use a local HDR file whose appearance you can compare against another trustworthy HDR-capable player or a correctly configured HDR display. A local file removes network, yt-dlp, buffering, and server-side transcoding variables from the first test.

1.1 Verify that the source is actually HDR

Open the file in mpv and display the track information or statistics overlay. Depending on the mpv build and active output driver, the overlay may report a PQ or HLG transfer function, BT.2020 primaries, and 10-bit video. PQ is also commonly identified as SMPTE ST 2084. These properties are strong indicators of HDR, although metadata quality varies between files.

If the source is SDR, tone-mapping adjustments are not the correct fix. Stop and investigate ordinary color-management, range, shader, or display problems instead. Also confirm that you selected the intended video track when a file contains several versions or angles.

1.2 Start mpv without the normal configuration

Run a minimal test from a terminal. Replace the sample path with the real path to your file and keep the quotation marks when it contains spaces.

mpv --no-config --vo=gpu-next "HDR-sample.mkv"

On Windows, the executable may be named mpv.exe. In PowerShell, Command Prompt, Bash, and Zsh, quoting rules differ slightly, but a normally quoted local path is sufficient for this test. Do not paste typographic quotation marks copied from a formatted document.

If the clean test looks correct, mpv itself, the file, and the basic rendering path are probably functional. The fault is likely in mpv.conf, an automatically selected profile, an input binding, a script, or a user shader. Stop changing operating-system components and compare the clean test with your normal setup.

If the clean test is still wrong, continue with an explicit SDR target. This tells mpv that it should render for a conventional SDR display rather than relying entirely on automatic output assumptions:

mpv --no-config --vo=gpu-next --target-trc=bt.1886 --target-prim=bt.709 --target-peak=100 --tone-mapping=auto --gamut-mapping-mode=auto "HDR-sample.mkv"

Success means that faces and midtones have plausible brightness, bright objects retain visible structure, neutral areas do not have an obvious tint, and saturated colors remain strong without looking fluorescent. If that result is stable, stop adding options. More tone-mapping controls do not automatically produce a more accurate image.

2. Check Tone Mapping and Its Direct Configuration Dependencies

Tone mapping compresses an HDR signal into the smaller brightness range available to an SDR display. It cannot preserve every aspect of the HDR master. A correct result should look balanced and watchable, but it will not reproduce the absolute brightness of an HDR television operating in HDR mode.

2.1 Review tone-mapping options

Search mpv.conf for options containing tone-mapping, target-peak, target-trc, target-prim, gamut, hdr, peak, or sigmoid. Temporarily comment out custom values by placing a hash character at the beginning of each relevant line. Then test again.

Start with tone-mapping=auto rather than choosing an algorithm because of a screenshot or another person's configuration. Tone-mapping algorithms make different compromises between average brightness, contrast, and highlight preservation. A setting that benefits one unusually mastered film can make ordinary HDR files look flat or dim.

If automatic behavior looks natural, keep it. Change the algorithm only when you can identify a repeatable defect in multiple known-good HDR samples. Evaluate actual scenes containing faces, shadows, clouds, lamps, and saturated objects rather than relying on a title screen.

2.2 Choose a realistic target peak

target-peak describes the intended output peak in candelas per square metre, commonly called nits. For an SDR-targeted test, 100 is a useful controlled baseline because traditional reference SDR is associated with a 100-nit white level. It is not a universal measurement of every desktop monitor.

A target that is too low or inappropriate for the viewing environment can produce an image that feels constrained. A poorly chosen high value can also lead to unexpected brightness allocation because mpv is mapping the source into a different assumed output range. Do not set the value equal to an advertised HDR peak if the operating system and display are actually running in SDR mode.

Begin at 100 for diagnosis. If the display has been measured and your SDR workflow intentionally uses another peak, use the measured or calibrated value afterward. Success is a natural image with preserved bright detail, not the brightest possible picture. Once highlights and midtones look consistent across several scenes, stop adjusting the peak by eye.

2.3 Check gamut mapping

HDR commonly uses BT.2020 signaling, while normal SDR desktop output is usually treated as BT.709 or an equivalent display space. Tone mapping handles luminance, while gamut mapping deals with colors that the smaller target gamut cannot reproduce.

If colors look neon, clipped, or unnaturally shifted, remove any forced gamut-mapping mode and test gamut-mapping-mode=auto. Also remove custom target primaries unless you know the display pipeline expects them. For a controlled SDR test, target-prim=bt.709 is a sensible explicit target.

Success means saturated reds, greens, and blues retain distinctions instead of collapsing into uniform patches. Skin should not become intensely orange merely because the source is HDR. Avoid judging gamut mapping through an untagged screenshot viewed in software that may ignore its color information.

2.4 Inspect profiles, input bindings, scripts, and shaders

mpv can alter properties after startup. A clean launch may look correct until an input binding changes tone mapping, a conditional profile activates, or a script modifies video parameters. Search these locations and features:

• mpv.conf for global video settings and profile declarations
• input.conf for commands that cycle or set tone-mapping properties
• Named and automatic profiles that match HDR files, protocols, extensions, or display conditions
• The scripts directory for Lua or JavaScript files that set video-output properties
• glsl-shaders and shader toggle bindings
• Include directives that load settings from another file

Temporarily disable only the relevant line, profile, script, or shader. Do not delete the entire configuration folder. If removing one shader restores normal contrast or highlights, leave that shader disabled for HDR-to-SDR playback or create a narrowly scoped profile after confirming its intended color assumptions.

Subtitle styling and audio-track selection do not normally change tone mapping. However, a profile that activates for a subtitle, audio, file, or protocol condition can also contain video options. Check those conditions if the picture changes when selecting tracks. An ASS subtitle can additionally make surrounding video appear perceptually darker when it introduces a large bright area, but it does not rewrite the underlying HDR transfer function by itself.

3. Check the Rendering Path, Display, and Source

3.1 Compare video-output and hardware-decoding paths

Use vo=gpu-next for the controlled test when your installed mpv build supports it. Then compare hardware decoding with software decoding:

mpv --no-config --vo=gpu-next --hwdec=no --target-trc=bt.1886 --target-prim=bt.709 --target-peak=100 "HDR-sample.mkv"

If software decoding looks correct but your usual hardware-decoding mode does not, the issue is associated with the hardware decode or hardware-frame interoperation path. Try hwdec=auto-safe or the default automatic behavior rather than forcing a platform-specific decoder. Confirm that the terminal reports successful decoding without format-conversion or device errors.

Software decoding can be demanding for 4K, high-frame-rate, or high-bitrate media. Use it as a diagnostic control, not necessarily as the permanent solution. Success is identical color and contrast between the stable hardware and software paths, with smooth playback and no repeated decode errors.

3.2 Verify operating-system HDR state and display calibration

Know whether the desktop is running in SDR or HDR mode. An SDR-targeted command is intended for an SDR output path. If Windows, macOS, or the Linux display stack is already sending HDR and mpv is also forced to produce SDR, the result may not match an HDR passthrough workflow. Conversely, sending HDR values through an SDR-assumed path can make the image pale or dark.

Temporarily disable monitor picture enhancements such as dynamic contrast, black equalizers, vivid modes, and automatic HDR effects. Select a neutral or calibrated display preset. Confirm that the operating system uses the intended ICC profile and that no night-light or color-temperature feature is active during comparison.

On Linux, compare behavior under your available Wayland or X11 session only if the clean test points to the presentation path. Color management and HDR support depend on the compositor, driver, protocol support, and display. On every operating system, update the GPU driver through the GPU vendor or operating-system mechanism rather than downloading random driver or codec bundles.

Audio backends do not perform tone mapping. Investigate audio only if playback stalls, synchronization failures interrupt rendering, or a profile tied to the selected audio device changes video settings.

3.3 Separate local-file problems from stream problems

First prove that one local HDR sample works. Then test the online URL, playlist, or network stream. yt-dlp may select a different representation than expected, and a service may provide separate SDR and HDR formats. Inspect mpv's track and format information rather than assuming that a high resolution is HDR.

If only online playback looks wrong, update yt-dlp through its official installation method and verify that mpv can find the intended executable. Check shell quoting for URLs containing ampersands or question marks. Also determine whether a media server is transcoding HDR to SDR before mpv receives it. In that case, applying another HDR-to-SDR transformation is not the right remedy.

Network access, buffering, and bitrate limits can cause dropped frames or fallback format selection, but they do not directly alter a correctly decoded local HDR signal. A malformed file, incorrect mastering metadata, missing metadata, or unusual encode can still defeat automatic choices. If every known-good sample works except one file, stop changing global mpv settings and treat that file as the exception.

3.4 Treat screenshots as a separate test

A screenshot may pass through different color-management assumptions than the displayed window. Its tagged or untagged pixel values can also be interpreted differently by browsers, image editors, messaging platforms, and operating-system preview tools. Therefore, a screenshot that looks washed out does not prove that live mpv rendering is wrong.

Compare the live image first. If only screenshots are wrong, inspect mpv's screenshot options and the color-management behavior of the viewing application. Do not tune tone mapping until a screenshot matches an uncalibrated image viewer, because that can damage correct live playback.

4. Use mpv Diagnostics Instead of Guessing

4.1 Capture useful terminal output

Launch mpv from a terminal so startup and rendering messages remain visible. Increase relevant logging and write it to a file when the normal output is insufficient:

mpv --no-config --vo=gpu-next --msg-level=vo=debug,vd=debug --log-file=mpv-tone-map.log "HDR-sample.mkv"

Look for the selected video output, decoder, pixel format, color primaries, transfer function, hardware-decoding status, shader compilation failures, and fallback messages. A log is most useful when comparing one working command with one failing command. Avoid enabling maximum verbosity for every subsystem unless requested, because unrelated output can hide the important difference.

4.2 Inspect profiles and runtime properties

If you suspect a named profile, use --show-profile=PROFILE_NAME to inspect what it contains. Review automatic profile conditions in the configuration manually as well. Remember that later settings can override earlier ones, so an included file or profile near the end of the configuration may win over an apparently correct global option.

Open mpv's statistics overlay during playback to inspect video and rendering information. Use the track list to verify that the intended video stream is active. When an option changes at runtime, the on-screen display may reveal the current property value, while the log may identify the script or command responsible.

Success means you can point to one concrete difference between the good and bad run, such as a forced target peak, active shader, unexpected profile, different decoder path, or non-HDR stream. Once identified, correct that difference instead of rebuilding the whole configuration.

5. Run a Clean Temporary Test Before Permanent Changes

Create a short sequence of repeatable tests using the same file, scene, display mode, window size, and room lighting. Restart mpv between tests so runtime property changes do not carry through your comparison.

1. Run --no-config --vo=gpu-next and record the result.
2. Add the explicit SDR target using BT.1886, BT.709, and a 100-nit target peak.
3. Compare hwdec=no with your normal hardware-decoding setting.
4. Restore mpv.conf without scripts, shaders, or automatic profiles.
5. Restore one relevant profile, script, or shader at a time.
6. Repeat with a second known-good HDR sample before making a global rule.

Change only one variable per run. Use recognizable timestamps containing dark detail, normal skin, saturated colors, and intense highlights. If a clean explicit SDR target produces a balanced image in two known-good samples, preserve that result and stop experimenting unless another repeatable problem appears.

After finding the cause, make the smallest permanent edit possible. For example, remove one obsolete forced option, correct one profile, or limit a shader to the content for which it was designed. Keep a comment beside the change explaining why it exists. This makes future mpv troubleshooting much easier.

6. Quick Fix Checklist

• Confirm the source reports PQ or HLG characteristics and uses the intended video track.
• Test one known-good local HDR sample before diagnosing URLs or network streams.
• Run mpv with --no-config --vo=gpu-next.
• For an SDR test, set BT.1886, BT.709, a 100-nit target, and automatic mapping.
• Remove forced tone-mapping algorithms before comparing alternatives.
• Use automatic gamut mapping when wide-gamut colors look clipped or fluorescent.
• Compare software decoding with the normal hardware-decoding path.
• Check mpv.conf, input.conf, profiles, includes, scripts, and shaders individually.
• Verify whether the operating-system desktop is in SDR or HDR mode.
• Disable dynamic contrast and vivid monitor processing during diagnosis.
• Use terminal logs and the statistics overlay to identify the active rendering path.
• Do not judge live tone mapping solely from an image-viewer screenshot.
• If only one file fails, suspect its mastering metadata or encode before changing global settings.
• If only a URL fails, verify the selected stream and whether a server is transcoding it.
• Stop when multiple known-good samples have natural midtones, colors, and highlight detail.

7. Frequently Asked Questions

7.1 Why does HDR video look washed out in mpv?

A washed-out image often means HDR values are being presented without the expected HDR display path, the output target has been described incorrectly, or a profile or shader is interfering with conversion. Test with --no-config and an explicit SDR target. Also confirm that the operating system is not unexpectedly switching between HDR and SDR modes.

7.2 What target peak should I use for HDR-to-SDR playback?

Use 100 nits as a controlled SDR troubleshooting baseline. If you have a calibrated SDR workflow with a measured peak, use that value after confirming the basic conversion. Do not copy the source video's mastering peak or the monitor's advertised HDR peak into an SDR configuration without understanding the full output pipeline.

7.3 Should I force a specific tone-mapping algorithm?

Not initially. Start with automatic selection and test known-good material. Force an algorithm only when it solves a repeatable problem and does not create worse midtone, contrast, or highlight behavior in other files. The best choice depends on source characteristics and the target display rather than a universal ranking.

7.4 Can custom shaders make mpv tone mapping look wrong?

Yes. A shader may expect linear-light input, SDR input, a particular gamut, or a specific position in the rendering chain. Shader stacks can also interact with scaling, debanding, and color conversion. Disable all user shaders, confirm correct tone mapping, and then restore them one at a time.

7.5 Why does the local HDR file work while an online URL does not?

The online service, yt-dlp, or media server may select an SDR representation, a different codec, or a transcoded stream. Inspect the selected video track and its color properties. Confirm that mpv can access the official yt-dlp executable and that the URL is quoted correctly. If the received stream is already SDR, do not troubleshoot it as though it still contains HDR.

7.6 Is mpv not working if one HDR file still looks bad?

Not necessarily. If several trusted HDR samples look correct with the same clean command, the remaining file may contain unusual or inaccurate mastering metadata, missing color tags, or an encode-specific limitation. Keep the global configuration that works and use a narrowly scoped per-file or conditional profile only when you have verified what that exceptional file requires.