calibrate.lua: add script for target parameters adjustment

DOCS/interface-changes/calibrate.txt

@@ -0,0 +1,2 @@
+add `calibrate.lua` builtin script for visual display calibration
+add `--load-calibrate` option

DOCS/man/calibrate.rst

@@ -0,0 +1,140 @@
+CALIBRATE
+=========
+
+This script finds values of ``--target-peak``, ``--target-contrast``,
+``--hdr-reference-white`` and ``--treat-srgb-as-power22`` that match the
+display in its viewing environment, by adjusting test patterns by eye. It
+requires ``--vo=gpu-next``.
+
+Usage
+-----
+
+Run ``script-binding calibrate/start``, or select "Calibrate display" in the
+Tools submenu of the context menu. Playback is replaced by the test patterns,
+in fullscreen by default, and resumes at the same position afterwards.
+
+The pages shown depend on whether the output is SDR or HDR. Each page shows
+instructions and the value found. The text hides while a level is being
+adjusted and returns when the input is idle.
+
+The last page lists the results, which are also written to the log. They can
+be applied to the running player with ``a``. Nothing is saved, add the values
+to ``mpv.conf`` to keep them.
+
+Calibrate in the lighting the display is normally watched in, the black level
+includes the ambient light it reflects.
+
+The following keys are active while calibrating:
+
+================================  ============================================
+Up, Down, mouse wheel             Adjust the level
+PgUp, PgDn, Shift+Up, Shift+Down  Adjust the level in coarse steps
+Enter                             Go to the next page, finish on the last one
+Left, Right                       Go to the previous or next page
+w                                 Cycle the size of the pattern window
+r                                 Reset the level of the current page
+h                                 Hide or show the instructions
+a                                 Apply the results, on the last page
+Esc, q                            Finish
+================================  ============================================
+
+Pages
+-----
+
+Transfer function
+    Only with sRGB or gamma 2.2 SDR output. Adjust the disc until it blends
+    into the stripes around it when viewed from a normal distance, then
+    continue. It may blend in without any adjustment. This tells whether the
+    display decodes with the sRGB piecewise curve or a pure 2.2 power
+    function, and gives ``--treat-srgb-as-power22``. The stripes have to reach
+    the panel unscaled, use the native resolution and disable sharpening in
+    the display.
+
+Peak luminance
+    Only with HDR output. Raise the level until the disc is no longer visible
+    inside the white window, which is where the display clips. This gives
+    ``--target-peak``. The peak of many displays depends on the size of the
+    bright area, ``w`` changes the size of the window.
+
+Black level
+    Lower the level until the patch is no longer visible against the black
+    around it. Raise it first if the patch is not visible. This gives
+    ``--target-contrast``. With SDR output the value is an estimate, derived
+    from the darkest visible level with the ``black_threshold`` options.
+
+White luminance
+    Only with SDR output. The white luminance of a display cannot be found by
+    eye. Enter a value measured with a meter or taken from the specification
+    of the display, or continue to keep the current one. This gives
+    ``--hdr-reference-white``, which is used when HDR content is mapped to the
+    SDR output. The contrast ratio measured before does not depend on it.
+
+SDR reference white
+    Only with HDR output and ``--target-colorspace-hint-mode=target``, the
+    default. Set the brightness of the SDR picture shown to a comfortable
+    level. This gives ``--hdr-reference-white``. It is a preference rather
+    than a measurement.
+
+Script bindings
+---------------
+
+``start``
+    Start the calibration, or finish it if it is running.
+
+Script messages
+---------------
+
+``start [hdr|sdr]``
+    Like the ``start`` binding. With ``--target-colorspace-hint-mode=source``
+    the output follows the content, and the argument selects whether HDR or
+    SDR output is calibrated, e.g. ``script-message-to calibrate start hdr``.
+    Without it the mode of the current output is used.
+
+Configuration
+-------------
+
+This script can be customized through a config file
+``script-opts/calibrate.conf`` placed in mpv's user directory and through the
+``--script-opts`` command-line option. The configuration syntax is described in
+`mp.options functions`_.
+
+Configurable Options
+~~~~~~~~~~~~~~~~~~~~
+
+``fullscreen``
+    Default: yes
+
+    Whether to switch to fullscreen while calibrating. What surrounds the
+    pattern affects the perceived black level and, on displays that limit
+    their brightness, the peak luminance.
+
+``black_window``
+    Default: 20
+
+    Initial size of the pattern window on the transfer function and black
+    level pages, in percent of the screen area.
+
+``peak_window``
+    Default: 10
+
+    Initial size of the pattern window on the peak and white luminance pages,
+    in percent of the screen area.
+
+``hide_time``
+    Default: 1
+
+    Seconds without input after which the text hidden while adjusting returns.
+
+``black_threshold``
+    Default: 0.03
+
+    With SDR output the black level is estimated from the darkest visible
+    level above it, taken as
+    ``black_threshold_min + black_threshold * black``. Lower values give a
+    higher black level and a lower contrast ratio for the same level found.
+
+``black_threshold_min``
+    Default: 0.005
+
+    Absolute visibility threshold in cd/m² for the same estimate. A darkest
+    visible level at or below it gives infinite contrast.

DOCS/man/mpv.rst

@@ -1617,6 +1617,8 @@ works like in older mpv releases:
 
 .. include:: positioning.rst
 
+.. include:: calibrate.rst
+
 .. include:: lua.rst
 
 .. include:: javascript.rst

DOCS/man/options.rst

@@ -1115,6 +1115,10 @@ Program Behavior
     Enable the builtin script that provides various keybindings to pan videos
     and images (default: yes).
 
+``--load-calibrate=<yes|no>``
+    Enable the builtin script for visual display calibration (default: yes).
+    See the `CALIBRATE`_ section for details.
+
 ``--player-operation-mode=<cplayer|pseudo-gui>``
     For enabling "pseudo GUI mode", which means that the defaults for some
     options are changed. This option should not normally be used directly, but

etc/menu.conf

@@ -141,6 +141,7 @@ T&ools
 	Copy &title		set clipboard/text ${media-title}	disabled=idle_active
 
 	&Hardware decoding	cycle-values hwdec no auto	checked=hwdec_current and hwdec_current ~= "no"	disabled=p["current-tracks/video/image"] ~= false
+	Calibrate &display	script-binding calibrate/start
 	&Key bindings		script-binding select/select-binding
 	P&roperties			script-binding select/show-properties
 	&Console			script-binding commands/open

options/options.c

@@ -584,6 +584,7 @@ static const m_option_t mp_opts[] = {
     {"load-positioning", OPT_BOOL(lua_load_positioning), .flags = UPDATE_BUILTIN_SCRIPTS},
     {"load-commands", OPT_BOOL(lua_load_commands), .flags = UPDATE_BUILTIN_SCRIPTS},
     {"load-context-menu", OPT_BOOL(lua_load_context_menu), .flags = UPDATE_BUILTIN_SCRIPTS},
+    {"load-calibrate", OPT_BOOL(lua_load_calibrate), .flags = UPDATE_BUILTIN_SCRIPTS},
 #endif
 
 // ------------------------- stream options --------------------
@@ -1038,6 +1039,7 @@ static const struct MPOpts mp_default_opts = {
 #ifndef _WIN32
     .lua_load_context_menu = true,
 #endif
+    .lua_load_calibrate = true,
 #endif
     .auto_load_scripts = true,
     .loop_times = 1,

options/options.h

@@ -198,6 +198,7 @@ typedef struct MPOpts {
     bool lua_load_positioning;
     bool lua_load_commands;
     bool lua_load_context_menu;
+    bool lua_load_calibrate;
 
     bool auto_load_scripts;
 

player/core.h

@@ -456,7 +456,7 @@ typedef struct MPContext {
 
     struct mp_ipc_ctx *ipc_ctx;
 
-    int64_t builtin_script_ids[9];
+    int64_t builtin_script_ids[10];
 
     mp_mutex abort_lock;
 

player/lua.c

@@ -94,6 +94,9 @@ static const char * const builtin_lua_scripts[][2] = {
     },
     {"@context_menu.lua",
 #   include "player/lua/context_menu.lua.inc"
+    },
+    {"@calibrate.lua",
+#   include "player/lua/calibrate.lua.inc"
     },
     {0}
 };