MPV HDR Direct Playback via Script (Auto Switch HDR)

[yosh-wang]

Since mpv currently does not support automatically toggling the Windows HDR switch based on video content, developer dyphore created a script to implement this functionality — automatically turning the system HDR mode on/off and enabling HDR passthrough. The script is integrated into: mpv-config https://github.com/dyphire/mpv-config/releases — ready to use out of the box, just configure hdr_mode.conf with your display parameters.

mpv.conf settings:
vo=gpu-next

hdr_mode.conf settings:

# Specify the script working mode, options: noth, pass, switch. Default: noth
## noth: Do nothing
## pass: Pass HDR signals for HDR content when the monitor is already in HDR mode
## switch: Automatically switch between HDR and SDR modes based on video content, available on Windows 10 and later
hdr_mode=switch

# Specify whether to switch HDR mode only when fullscreen or window maximized. Only works with hdr_mode=switch, default: no
fullscreen_only=no

# Specify the target peak brightness of your HDR display, default: 203
#! Reminder: Must be set to your display's true peak brightness, otherwise HDR content will display incorrectly. The default value 203 treats it as an SDR display
target_peak=400

# Specify the maximum contrast ratio of your HDR display, default: auto (infinite contrast for OLED)
#! Reminder: Must be set to your display's true maximum contrast, otherwise black point compensation will not work correctly
## Example: 100000 means display max contrast ratio is 100000:1
## OLED displays can leave this as default (auto)
target_contrast=auto

These three files are indispensable:

\portable_config\script-opts\hdr_mode.conf 【hdr_mode.conf】
\portable_config\scripts\hdr-mode.lua 【hdr-mode.lua】
\portable_config\scripts\display-info.dll 【display-info.dll】

How it works:

File Path	Purpose
hdr_mode.conf	Script configuration file: Stores user-defined parameters such as hdr_mode=switch, target_peak=400, etc. The script reads this file at startup to apply your settings.
hdr-mode.lua	Core script: Implements the main logic for automatic HDR switching. Detects whether the video is HDR → reads the display's HDR status → decides whether to switch → calls the system API to toggle HDR → adjusts mpv rendering parameters.
display-info.dll	Dependency plugin: Allows the script to read and write Windows HDR status. Without this DLL, the script cannot detect whether HDR is currently enabled or automatically toggle the system HDR switch.

---

由于mpv目前不支持根据视频内容自动切换Windows HDR开关，开发者 dyphire 编写了一个脚本来实现此功能——通过脚本自动开关系统HDR模式及实现HDR直通。该脚本已整合至：mpv-config https://github.com/dyphire/mpv-config/releases ，开箱即用，只需根据你的显示器参数配置hdr_mode.conf即可。

mpv.conf设置如下：

vo=gpu-next

hdr_mode.conf设置如下：

# 指定脚本的工作方式，有三种模式可选：noth、pass、switch。默认值：noth
## noth：什么也不做
## pass：当显示器处于 HDR 模式时，为 HDR 内容传递 HDR 信号
## switch：根据 mpv 播放的视频内容在显示器的 HDR 模式和 SDR 模式之间自动切换，在 Windows 10 及更高版本的系统上可用
hdr_mode=switch
# 指定是否仅在全屏或窗口最大化时自动切换 HDR 模式。仅在 hdr_mode=switch 时生效，默认值：no
fullscreen_only=no
# 用于指定你的 HDR 显示器的目标峰值，默认值：203
#! 提醒：此项必须指定显示器的真实峰值亮度，否则会导致 HDR 内容显示不正确。默认值 203 会视为 SDR 显示器处理
target_peak=400
# 用于指定你的 HDR 显示器的最大对比度数值，默认值：auto，即无限对比度（OLED）
#! 提醒：此项必须指定为显示器的最大对比度，否则无法正确实施黑位补偿
## 例如 100000 表示显示器最大对比度为 100000:1
## OLED 显示器无需更改此项，使用默认值即可
target_contrast=auto

以下三个文件缺一不可：
\portable_config\script-opts\hdr_mode.conf 【hdr_mode.conf】
\portable_config\scripts\hdr-mode.lua 【hdr-mode.lua】
\portable_config\scripts\display-info.dll 【display-info.dll】

工作原理：

文件路径	作用
hdr_mode.conf	脚本配置文件：存放用户自定义参数，如 hdr_mode=switch、target_peak=400 等。脚本启动时会读取此文件中的设置。
hdr-mode.lua	核心脚本：实现 HDR 自动切换的主要逻辑。检测视频是否为 HDR → 读取显示器 HDR 状态 → 决策是否切换 → 调用系统 API 开关 HDR → 调整 mpv 渲染参数。
display-info.dll	依赖插件：让脚本能够读写 Windows HDR 状态。没有这个 dll，脚本无法获取当前 HDR 是否开启，也无法自动切换系统 HDR 开关。