What is the mpv target-peak option in HDR mapping?

The target-peak option in the mpv media player is a critical setting used during HDR (High Dynamic Range) to SDR (Standard Dynamic Range) tone mapping, determining the brightness level the video player targets when compressing high-luminance highlights. When playing HDR content on a display that does not support the full brightness range of the video file, tone mapping adapts the video to fit the screen’s capabilities. By adjusting target-peak, users can manually control the balance between preserving bright details and maintaining the overall brightness of the scene, preventing the washed-out or overly dark images that often occur during automatic conversion.

Understanding HDR Tone Mapping in mpv

HDR content often features peak brightness levels reaching \(1000\text{ nits}\) or even \(4000\text{ nits}\). However, standard computer monitors and older televisions typically max out between \(250\text{ nits}\) and \(400\text{ nits}\). When mpv plays an HDR video on an SDR display, it must compress the dynamic range so the display can handle it without clipping the highlights into pure, detail-less white. This process is called tone mapping.

By default, mpv attempts to automatically detect the display’s capabilities and the video’s metadata to perform this conversion. However, automatic detection is not always accurate, which is where the target-peak option becomes essential for manual override.

How the Target-Peak Option Works

The target-peak option allows you to explicitly define the maximum brightness (in nits) that the tone-mapping algorithm should target. It essentially tells mpv, “Treat my display as if its maximum brightness capability is exactly this value.”

The setting alters the playback behavior based on how you configure it:

• Setting a Higher Target-Peak: If you set target-peak to a higher value (e.g., \(500\text{ nits}\) or more), mpv assumes the display can handle brighter highlights. As a result, the algorithm compresses the mid-tones more heavily to leave room for high-brightness details. This preserves specular highlights (like sunlight glinting off metal or explosions) but makes the overall image look darker.
• Setting a Lower Target-Peak: If you set target-peak to a lower value (e.g., \(200\text{ to }300\text{ nits}\)), mpv assumes the display has limited brightness capability. The overall image will appear brighter and closer to standard SDR levels, but the brightest highlights may clip, losing texture and detail in very bright areas.

When Should You Adjust Target-Peak?

Modifying target-peak is highly beneficial when you are unhappy with mpv’s automatic HDR-to-SDR conversion. You should consider manually adjusting it in the following scenarios:

• Viewing in a Dark Room: If you watch movies in a dark environment, you can afford a higher target-peak value. The overall image will be darker, but your eyes will adapt, allowing you to enjoy the rich highlight details without losing perceived contrast.
• Viewing in a Bright Room: In a well-lit room, a dark image is difficult to see. Lowering the target-peak value raises the average picture level (APL), making the movie watchable even with ambient glare, despite some loss in highlight fidelity.
• Mismatched Mastering Metadata: Some HDR videos contain incorrect or missing mastering metadata (like MaxCLL or MaxFALL). Manually setting target-peak bypasses the broken metadata, forcing mpv to render the video consistently.