mpv HDR Too Dark: How to Fix It

When mpv HDR is too dark, the cause is usually not a damaged video or a simple brightness-control problem. The more likely explanations are incorrect tone mapping, an inaccurate display peak-brightness assumption, missing HDR metadata, an unexpected profile or script, a mismatch between mpv and the operating system's HDR mode, or a hardware-decoding and video-output combination that handles the signal differently. The safest approach is to reproduce the symptom without your normal configuration, identify whether mpv is tone-mapping or sending HDR to the display, and change one relevant option at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start with the exact file that looks dark, preferably a local HDR video rather than an online URL. A local file removes yt-dlp, network behavior, manifests, and server-selected formats from the first test.

Open a terminal and run:

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

On Windows, replace the example with a fully quoted path such as:

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

The --no-config option temporarily prevents mpv from loading the normal configuration. It does not delete or modify your files. It also provides a clean comparison against custom profiles, scripts, shaders, input bindings, and persistent video settings.

1.1 Interpret the clean test

If the picture looks correct with --no-config, your media, display, and basic mpv installation can probably produce an acceptable result. The problem is likely inside mpv.conf, a profile, an auto profile, a script, a shader, or a command-line alias. Stop changing operating system settings and compare your configuration against the clean test.

If the clean test is still too dark, the issue is more likely connected to tone mapping, HDR metadata, the selected video output, GPU behavior, display mode, or the file itself. Continue with a second controlled test rather than adding a large collection of suggested options.

1.2 Verify that the symptom is specifically HDR darkness

Check whether normal SDR videos look reasonable in the same player and display environment. If both SDR and HDR are equally dark, investigate display brightness, color controls, shaders, ICC or color-management behavior, and operating system settings before treating this as an HDR-only problem.

Do not expect an HDR master and an SDR version to look identical. They may use different grades, black levels, highlight treatment, and creative intent. A useful comparison asks whether faces, midtones, and shadow detail are unusually difficult to see, not whether every frame has the same average brightness.

2. Check Tone Mapping and the Target Peak

Tone mapping compresses HDR luminance into the range your current output can display. A dark result can occur when mpv assumes a target peak that does not reflect the display or viewing setup, or when a selected tone-mapping curve preserves highlights by pushing ordinary scene brightness too low.

2.1 Understand the target peak assumption

The target peak represents the output display's usable peak brightness in nits. It is not necessarily the largest number printed in a monitor specification. Real peak brightness can depend on window size, picture mode, automatic brightness limiting, local dimming, operating system HDR calibration, and whether the display is receiving SDR or HDR.

First test mpv's automatic behavior:

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

If you are deliberately tone-mapping HDR for an SDR display, you can perform controlled tests with plausible target values:

mpv --no-config --target-peak=200 "path/to/hdr-video.mkv"
mpv --no-config --target-peak=300 "path/to/hdr-video.mkv"

These are diagnostic examples, not universal recommendations. Do not copy a value merely because another user has the same monitor brand. Compare the same representative scene and keep the value that produces visible shadow detail, natural midtones, and controlled highlights without obvious clipping.

Success means the image no longer looks persistently underexposed while bright objects retain useful detail. Once that balance is reached, stop increasing values or adding unrelated color options.

2.2 Compare tone-mapping curves carefully

mpv supports multiple tone-mapping algorithms, although exact availability and behavior can depend on the video output and build. Test only curves listed by your installed mpv manual. For example:

mpv --no-config --tone-mapping=bt.2390 "path/to/hdr-video.mkv"
mpv --no-config --tone-mapping=mobius "path/to/hdr-video.mkv"
mpv --no-config --tone-mapping=reinhard "path/to/hdr-video.mkv"

Use the same scene for every comparison. Some curves prioritize highlight detail, while others produce brighter midtones or a different roll-off. A curve is not better merely because it makes the entire image brighter. Watch for flattened contrast, gray blacks, clipped clouds, glowing skin, and lost color saturation.

If one curve fixes the darkness without introducing distracting artifacts, keep it as a temporary command-line option. Add it to a dedicated HDR profile only after confirming it works across more than one file.

2.3 Test dynamic peak analysis

HDR files may contain mastering metadata, content light-level metadata, both, or neither. Static metadata also cannot describe every individual scene. Depending on the selected output path, mpv can analyze image content when HDR peak computation is enabled.

mpv --no-config --hdr-compute-peak=yes "path/to/hdr-video.mkv"

Compare that result with:

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

If enabling analysis improves midtones and highlight handling, it may be useful for files with incomplete or unhelpful metadata. If there is no meaningful difference, leave the default behavior alone rather than assuming the option must be forced.

3. Inspect Configuration, Profiles, Scripts, and Output Options

A clean test that works normally is strong evidence that a customization causes the mpv player issue. Search your configuration for HDR, color, scaling, shader, video-output, and hardware-decoding directives.

3.1 Review mpv.conf and profile-specific HDR options

Look for options containing terms such as:

• tone-mapping
• target-peak
• hdr-compute-peak
• vo
• gpu-api or gpu-context
• target-colorspace-hint
• icc-profile or automatic ICC handling
• glsl-shader or shader chains
• brightness, gamma, contrast, or saturation controls
• hwdec

Comment out one suspicious line at a time, restart mpv, and replay the same scene. Do not remove the entire configuration folder. Keeping the scope narrow preserves unrelated subtitle, audio, IPC, playlist, and input settings.

Pay special attention to named profiles and conditional auto profiles. An HDR profile can activate only for particular color properties, codecs, resolutions, file paths, or display names. A command that appears harmless in the general section may also be overridden later.

3.2 Use show-profile to expose hidden overrides

Run the following with a profile name from your configuration:

mpv --show-profile=profile-name

This displays the options associated with that profile. If a profile contains an old target peak, forced transfer characteristic, shader, or video output, test without the profile. Success means removing or correcting that single override makes normal playback match the clean command.

3.3 Check input bindings and scripts

An input binding can alter brightness, gamma, contrast, or a shader while mpv is running. A script can also restore saved properties on startup. Review input.conf for commands that change video properties and inspect scripts that manage profiles, displays, shaders, or playback state.

Test scripts safely by launching with --no-config. If you need a narrower test, temporarily disable only the suspected script according to your platform's configuration layout. Do not download replacement scripts or binaries from unknown sources.

3.4 Separate subtitles and tracks from picture brightness

Bright subtitles can make a correctly rendered HDR image appear darker because your eyes adapt to the subtitle luminance. Test a dark scene with subtitles hidden. If the underlying picture is unchanged but feels easier to view, reduce subtitle brightness or choose a less intense subtitle color rather than altering HDR tone mapping.

Use the track list to confirm that mpv selected the expected video stream. Some files contain multiple video tracks, alternative grades, or attached artwork. Audio-track selection does not normally change HDR brightness, so do not troubleshoot the audio backend unless playback synchronization, device initialization, or a profile tied to an audio device is also involved.

4. Check the Video Output, Hardware Decoder, and Operating System

4.1 Compare video outputs without assuming one is universally best

Use mpv's documented GPU outputs and test what your installed build supports. A useful comparison may be:

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

If one command is unsupported, mpv will report it. Do not install an untrusted build simply to obtain an option. If one output produces correct luminance consistently, use it while investigating whether the difference comes from tone-mapping defaults, GPU APIs, or display integration.

4.2 Test hardware decoding

Hardware decoding can interact with pixel formats, bit depth, GPU drivers, and zero-copy paths. Compare the default clean test with hardware decoding disabled:

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

You can also test mpv's automatic hardware-decoding selection:

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

If software decoding fixes the darkness, the likely area is the hardware decoder, GPU driver, pixel-format path, or selected video output. It does not automatically mean the file is bad. Stop once you have a stable working path, especially if CPU usage and playback performance remain acceptable.

4.3 Align mpv with the operating system's HDR mode

Decide whether you are tone-mapping HDR into an SDR desktop or trying to use an HDR-capable display path. Mixing assumptions can make the result too dark, washed out, or incorrectly saturated.

• On Windows, verify whether Use HDR is enabled for the actual display running mpv. Check the display's HDR calibration and SDR content brightness controls.
• On macOS, confirm that the connected display, cable, adapter, and selected display mode support HDR. External-display behavior can differ from the built-in screen.
• On Linux, HDR support depends on the compositor, display server, graphics stack, driver, and mpv output path. An HDR-capable monitor alone does not guarantee end-to-end HDR signaling.

After changing an operating system HDR setting, close and reopen mpv. Success means the desktop mode and mpv output agree, producing stable blacks, readable midtones, and highlights that do not look abruptly clipped.

4.4 Check ambient light and the display picture mode

HDR masters are often harder to watch in a bright room, particularly on displays with limited full-screen brightness. Reduce direct light and reflections before forcing aggressive tone mapping. Confirm that the monitor or television has not entered an energy-saving, eco, eye-comfort, or low-power mode.

Use a neutral or accurate picture mode as a baseline. Dynamic contrast and black-enhancement controls can crush shadows, while automatic brightness controls can change during testing. If correcting the display mode restores detail across multiple applications, stop changing mpv.

5. Verify Metadata, Streams, External Tools, and Screenshots

5.1 Inspect HDR metadata and pixel format

Open mpv's statistics overlay, commonly available through a default key binding, and inspect the video properties. Look for a 10-bit format and HDR-related transfer characteristics such as PQ or HLG. The exact labels depend on the build and active output.

You can also use a trusted FFmpeg installation and run:

ffprobe -hide_banner "path/to/hdr-video.mkv"

Missing mastering or content-light metadata does not prove the video is invalid. It means automatic tone mapping may have less guidance. Conversely, metadata can exist without being ideal for every scene. Treat metadata as evidence, not a guarantee.

5.2 Eliminate online-stream variables

If the problem appears with an online URL, first play a known local HDR file. Streaming sites can provide different formats based on yt-dlp availability, account state, manifest information, codec support, or bandwidth. Use a current yt-dlp obtained from its official project or your trusted package manager, and confirm that mpv can find it.

Inspect the selected video track and resolution. A stream may differ from the local file in codec, bit depth, transfer function, or metadata. Network access problems normally cause loading or buffering, not consistent darkness, but a fallback format may have a different grade.

5.3 Do not judge output solely from screenshots

An mpv screenshot may contain HDR or high-bit-depth pixel values that an SDR image viewer displays incorrectly. The screenshot can therefore look darker or washed out even when playback is acceptable. Compare the live image first, then inspect the screenshot with software that understands its color characteristics.

If only screenshots are dark, avoid changing playback tone mapping. Review mpv's screenshot format and color handling instead. Success means the live video remains correct and the captured image is evaluated through an appropriate viewing path.

6. Use Logs to Find the Active Playback Path

Terminal output can reveal the selected decoder, pixel format, video output, GPU context, color properties, and failed options. Run a verbose but targeted test:

mpv --no-config --msg-level=vo=debug,vd=debug "path/to/hdr-video.mkv"

For a persistent log:

mpv --no-config --log-file=mpv-hdr-test.log "path/to/hdr-video.mkv"

Read the log for warnings about unsupported formats, unavailable outputs, failed GPU initialization, ignored options, and color-property detection. Do not treat every warning as the cause. Match each message to the visible symptom and the playback path actually in use.

If mpv is not working at all after adding a test option, remove that option and check the terminal message. An unknown option may simply reflect differences between builds. Consult the manual bundled with your installed version rather than copying settings intended for another environment.

7. Run a Clean Temporary Test Before Making Permanent Changes

Use a short test matrix and record the result of each command:

1. Play the local file with --no-config.
2. Compare automatic and one plausible manual target peak.
3. Compare one alternative tone-mapping curve.
4. Test --hwdec=no.
5. Compare supported GPU video outputs.
6. Repeat the best command with your normal configuration enabled.

Change only one variable between commands. Use the same scene, display mode, room lighting, window size, and subtitle state. This prevents a false conclusion caused by several simultaneous changes.

When you identify a successful command, add only the necessary option to a dedicated profile. Test several HDR files, including both bright and dark scenes. Stop changing settings when shadow detail is visible, midtones look natural, highlights retain reasonable structure, colors are stable, and SDR playback remains unaffected.

8. Quick Fix Checklist

• Run mpv --no-config with a local HDR file.
• Confirm SDR files are not equally dark.
• Check whether the operating system and display are in the intended HDR mode.
• Test --target-peak=auto and one realistic manual value.
• Compare one supported tone-mapping curve at a time.
• Test HDR peak computation if metadata appears incomplete.
• Review HDR-specific profiles, shaders, scripts, and input bindings.
• Hide bright subtitles during visual comparisons.
• Compare --hwdec=no with the normal decoder path.
• Compare supported GPU video outputs.
• Use the statistics overlay and track list to verify the selected stream.
• Capture a log and look for color, decoder, and output warnings.
• Do not use an SDR screenshot viewer as the sole test of HDR brightness.
• Make one permanent configuration change only after repeated success.

9. Frequently Asked Questions

9.1 Why is HDR dark in mpv but normal in another player?

The players may use different tone-mapping curves, target-peak assumptions, metadata handling, GPU APIs, hardware decoders, or operating system HDR paths. Compare mpv with --no-config first. If that fixes the image, a customization is responsible. If it does not, compare the output and decoding paths.

9.2 What target peak should I use?

There is no universal value. Start with automatic behavior, then test values that plausibly represent your display in its current mode. Choose the lowest-complexity setting that gives natural midtones and visible shadows without destroying highlights. Manufacturer peak claims may not represent sustained real-world output.

9.3 Can missing HDR metadata make a video too dark?

Yes, incomplete metadata can reduce the information available to tone mapping, but it is not the only cause. Content analysis may help, depending on the output path. Inspect the stream properties before assuming the file is defective.

9.4 Should I increase mpv brightness or gamma?

Not as the first fix. Global brightness and gamma controls can lift blacks, distort the intended transfer function, and conceal the real tone-mapping problem. Correct the output mode, target peak, and tone-mapping path first. Use manual picture controls only for a deliberate final adjustment.

9.5 Why is only the mpv screenshot too dark?

The screenshot may preserve color or luminance information that an SDR viewer cannot interpret correctly. If live playback looks normal, investigate screenshot format and viewer color management instead of changing the video-output settings.

9.6 Should HDR and SDR versions look identical?

No. They can have different creative grades and highlight ranges. Compare important visual features such as face brightness, shadow visibility, black level, and clipping. The goal is a usable, coherent image, not a pixel-for-pixel match.