various: define builtin options and key bindings for images

This makes mpv usable as an image viewer out of the box, as it is
currently hard to setup. Using mpv as an image viewer has several
advantages, the biggest one is that it's the best program at browsing
directories of mixed videos and images.

This adds a builtin-image profile that users can extend in mpv.conf. It
doesn't restore and reapply the options on each image change, because
that is slow for certain options (e.g. --d3d11-flip=no restarts the VO),
and causes visible flicker when options like gamma are unapplied before
changing image and reapplied on the next image. But it still restores
the previous options after switching to a video or audio file.

Default image key bindings are defined in the image input section which
gets enabled with the profile. sxiv is their main inspiration.

Closes #7983, closes #12496.

Author: guidocella

DOCS/interface-changes/apply-image-profile.txt

@@ -0,0 +1 @@
+add `--apply-image-profile` option

DOCS/man/mpv.rst

@@ -399,6 +399,83 @@ To use this feature, you need to fill the ``menu-data`` property with menu
 definition data, and add a keybinding to run the ``context-menu`` command,
 which can be done with a user script.
 
+Image Bindings
+--------------
+
+When viewing images, the following key bindings optimized for image viewing are
+added. Key bindings not listed here, or those configured by the user in
+``input.conf``, keep behaving like with non-image files.
+
+LEFT, RIGHT, UP, DOWN, h, j, k, l
+    Pan the image when it is larger than the window.
+
+Shift+LEFT, Shift+RIGHT, Shift+UP, Shift+DOWN, H, J, K, L
+    Slowly pan the image when it is larger than the window.
+
+Ctrl+LEFT, Ctrl+RIGHT, Ctrl+UP, Ctrl+DOWN, Ctrl+h, Ctrl+j, Ctrl+k, Ctrl+l
+    Align the image to one of the boundaries of the window when it is larger
+    than the window.
+
+= and -
+    Change the zoom.
+
++ and _
+    Change the zoom slowly.
+
+0
+    Reset zoom and panscan.
+
+u
+    Toggle between showing the image unscaled in its original dimensions and
+    fitting it to the window.
+
+o
+    Fill the window with the image. This makes the image scaled to the window,
+    resets zoom and sets ``--panscan`` to 1. See ``-panscan`` for more info.
+
+r
+    Rotate counterclockwise.
+
+R and t
+    Rotate clockwise.
+
+v
+    Rotate by 180 degrees.
+
+SPACE
+    Toggle between showing images for 5 seconds in a slideshow and keeping them
+    open forever.
+
+[ and ]
+    Decrease/increase the image display duration by 1.
+
+{ and }
+    Halve/double the image display duration.
+
+n
+    Go to the next playlist entry.
+
+p
+    Go to the previous playlist entry.
+
+N
+    Go to the next sub-playlist (e.g. directory or archive).
+
+P
+    Go to the previous sub-playlist.
+
+HOME and g-g
+    Go to the first playlist entry.
+
+END and G
+    Go to the last playlist entry.
+
+Wheel up/down
+    Change the zoom while keeping the part of the image hovered by the cursor
+    under it.
+
+See `Image profile`_ for image viewing tips.
+
 USAGE
 =====
 
@@ -1057,6 +1134,77 @@ example, ``math`` is defined and gives access to the Lua standard math library.
     This feature is subject to change indefinitely. You might be forced to
     adjust your profiles on mpv updates.
 
+Image profile
+-------------
+
+mpv has a builtin profile called ``builtin-image`` that is automatically applied
+to images and restored when switching to a video or audio file. It enables
+options optimal for image viewing, such as a smaller OSC layout optimized for
+images. Its full contents can be listed with ``mpv
+--show-profile=builtin-image``. It can be disabled with
+``--apply-image-profile=no``.
+
+It can be extended in mpv.conf without overwriting it completely:
+
+.. admonition:: Example to loop image playlists
+
+    ::
+
+        [builtin-image]
+        loop-playlist
+
+``--apply-image-profile`` also enables the image specific key bindings listed in
+`Keyboard Control`_. Additional image key bindings can be specified in the
+``image`` section in ``input.conf``, for example:
+
+    SPACE {image} repeatable playlist-next force
+
+See the `INPUT.CONF`_ section for more information on how to define key
+bindings.
+
+To reset zoom, alignment and rotation between images, it is recommended to place
+``reset-on-next-file=video-zoom,panscan,video-unscaled,video-align-x,video-align-y,video-rotate``
+in the top level of mpv.conf, as enabling it in the conditional profile makes it
+take effect only from the second file.
+
+To start viewing images and videos bigger than the window from the top left
+corner, these options can be set in the top level of mpv.conf along with
+``--reset-on-next-file``:
+
+.. admonition:: Start from the top left:
+
+    ::
+
+        video-align-x=-1
+        video-align-y=-1
+        video-recenter
+
+To enable the screensaver only when images are kept open forever, this profile
+can be added to mpv.conf:
+
+.. admonition:: Example to enable the screensaver:
+
+    ::
+
+        [screensaver]
+        profile-cond=p['current-tracks/video/image'] and not p['current-tracks/video/albumart'] and image_display_duration == math.huge
+        profile-restore=copy
+        stop-screensaver=no
+
+``--vo=gpu-next`` is recommended for better performance with large images,
+except images larger than the max texture size of the GPU API, for which a VO
+with software rendering can be used as fallback:
+
+.. admonition:: Example to display huge images on Wayland:
+
+    ::
+
+        [huge]
+        profile-cond=width > 16384 or height > 16384
+        vo=wlshm
+
+maxImageExtent may be 8192 instead on old iGPUs.
+
 Legacy auto profiles
 --------------------
 

DOCS/man/options.rst

@@ -877,6 +877,11 @@ Program Behavior
     Show the description and content of a profile. Lists all profiles if no
     parameter is provided.
 
+``--apply-image-profile=<yes|no>``
+    Whether to apply the ``builtin-image`` profile and enable the ``image``
+    input section when viewing an image without audio, and to restore them when
+    switching to a video or audio file (default: yes).
+
 ``--use-filedir-conf``
     Look for a file-specific configuration file in the same directory as the
     file that is being played. See `File-specific Configuration Files`_.
@@ -1584,7 +1589,7 @@ Video
     These values have special meaning:
 
     :0:  disable aspect ratio handling, pretend the video has square pixels
-    :no: same as ``0``
+    :no: same as ``0`` (default for images)
     :-1: use the video stream or container aspect (default)
 
     But note that handling of these special values might change in the future.
@@ -1702,11 +1707,11 @@ Video
     when the video becomes smaller than the window in the respective direction
 
     After zooming in until the video is bigger the window, panning with
-    `--video-align-x` and/or `--video-align-y`, and zooming out until the video
-    is smaller than the window, this is useful to recenter the video in the
-    window.
+    ``--video-align-x`` and/or ``--video-align-y``, and zooming out until the
+    video is smaller than the window, this is useful to recenter the video in
+    the window.
 
-    Default: no.
+    Default: no. The default is changed to yes for images.
 
 ``--video-margin-ratio-left=<val>``, ``--video-margin-ratio-right=<val>``, ``--video-margin-ratio-top=<val>``, ``--video-margin-ratio-bottom=<val>``
     Set extra video margins on each border (default: 0). Each value is a ratio
@@ -3363,7 +3368,7 @@ Window
     (Windows only)
     Enable/disable playback progress rendering in taskbar (Windows 7 and above).
 
-    Enabled by default.
+    Enabled by default, except for images.
 
 ``--snap-window``
     (Windows only) Snap the player window to screen edges.
@@ -4445,6 +4450,9 @@ Input
     Note that disabling the preprocessing does not affect any filtering done
     by the OS/driver before these events are delivered to mpv, if any.
 
+    This defaults to no for images to allow dialog panning when the touchpad is
+    bound to pan commands.
+
 ``--input-right-alt-gr=<yes|no>``
     (macOS and Windows only)
     Use the right Alt key as Alt Gr to produce special characters. If disabled,

DOCS/man/osc.rst

@@ -178,6 +178,8 @@ Configurable Options
     bottombar, topbar, slimbottombar and slimtopbar. Default pre-0.21.0 was
     'box'.
 
+    slimbottombar is the default for images.
+
 ``seekbarstyle``
     Default: bar
 
@@ -240,6 +242,8 @@ Configurable Options
     OSC will always popup with mouse movement in the window, and 1 means the
     OSC will only show up when the mouse hovers it. Default pre-0.21.0 was 0.
 
+    0.9 is the default for images.
+
 ``minmousemove``
     Default: 0
 

etc/builtin.conf

@@ -94,3 +94,13 @@ sub-shadow-offset=4
 [box]
 profile=osd-box
 profile=sub-box
+
+[builtin-image]
+profile-restore=copy-equal
+script-opt=osc-layout=slimbottombar
+script-opt=osc-deadzonesize=0.9
+prefetch-playlist
+video-recenter
+video-aspect-override=no
+input-preprocess-wheel=no
+taskbar-progress=no

etc/input.conf

@@ -238,3 +238,72 @@
 
 # ? cycle sub-forced-events-only        # display only DVD/PGS forced subtitle events
 # ? stop                                # stop playback (quit or enter idle mode)
+
+#
+# Image bindings
+#
+#LEFT        {image} script-binding positioning/pan-x -0.1 # pan left
+#DOWN        {image} script-binding positioning/pan-y  0.1 # pan down
+#UP          {image} script-binding positioning/pan-y -0.1 # pan up
+#RIGHT       {image} script-binding positioning/pan-x  0.1 # pan right
+#h           {image} script-binding positioning/pan-x -0.1 # pan left
+#j           {image} script-binding positioning/pan-y  0.1 # pan down
+#k           {image} script-binding positioning/pan-y -0.1 # pan up
+#l           {image} script-binding positioning/pan-x  0.1 # pan right
+#Shift+LEFT  {image} script-binding positioning/pan-x -0.01 # pan left slowly
+#Shift+DOWN  {image} script-binding positioning/pan-y  0.01 # pan down slowly
+#Shift+UP    {image} script-binding positioning/pan-y -0.01 # pan up slowly
+#Shift+RIGHT {image} script-binding positioning/pan-x  0.01 # pan right slowly
+#H           {image} script-binding positioning/pan-x -0.01 # pan left slowly
+#J           {image} script-binding positioning/pan-y  0.01 # pan down slowly
+#K           {image} script-binding positioning/pan-y -0.01 # pan up slowly
+#L           {image} script-binding positioning/pan-x  0.01 # pan right slowly
+
+# Recommended on a touchpad:
+# WHEEL_UP    {image} script-binding positioning/pan-y -0.1 # pan up
+# WHEEL_DOWN  {image} script-binding positioning/pan-y  0.1 # pan down
+# WHEEL_LEFT  {image} script-binding positioning/pan-x -0.1 # pan left
+# WHEEL_RIGHT {image} script-binding positioning/pan-x  0.1 # pan right
+
+#Ctrl+LEFT   {image} no-osd set video-align-x -1 # align to the left
+#Ctrl+DOWN   {image} no-osd set video-align-y  1 # align to the bottom
+#Ctrl+UP     {image} no-osd set video-align-y -1 # align to the top
+#Ctrl+RIGHT  {image} no-osd set video-align-x  1 # align to the right
+#Ctrl+h      {image} no-osd set video-align-x -1 # align to the left
+#Ctrl+j      {image} no-osd set video-align-y  1 # align to the bottom
+#Ctrl+k      {image} no-osd set video-align-y -1 # align to the top
+#Ctrl+l      {image} no-osd set video-align-x  1 # align to the right
+
+#= {image} add video-zoom  0.1  # zoom in
+#- {image} add video-zoom -0.1  # zoom out
+#+ {image} add video-zoom  0.01 # zoom in slowly
+#_ {image} add video-zoom -0.01 # zoom out slowly
+#0 {image} no-osd set video-zoom 0; no-osd set panscan 0 # reset zoom
+
+#WHEEL_UP   {image} script-binding cursor-centric-zoom  0.1 # zoom in towards the cursor
+#WHEEL_DOWN {image} script-binding cursor-centric-zoom -0.1 # zoom out towards the cursor
+
+#u {image} no-osd cycle-values video-unscaled yes no; no-osd set video-zoom 0; no-osd set panscan 0 # toggle scaling the image to the window.
+
+#o {image} no-osd set panscan 1; no-osd set video-unscaled no; no-osd set video-zoom 0 # fill black bars
+
+#r {image} cycle-values video-rotate 270 180 90 0 # rotate counterclockwise
+#R {image} cycle-values video-rotate 90 180 270 0 # rotate clockwise
+#t {image} cycle-values video-rotate 90 180 270 0 # rotate clockwise
+#v {image} cycle-values video-rotate 0 180        # rotate by 180 degrees
+
+#SPACE {image} cycle-values image-display-duration inf 5; no-osd set pause no # toggle slideshow
+#[ {image} add image-display-duration -1 # decrease the slideshow duration
+#] {image} add image-display-duration  1 # increment the slideshow duration
+#{ {image} multiply image-display-duration 0.5 # halve the slideshow duration
+#} {image} multiply image-display-duration 2   # double the slideshow duration
+
+#n {image} repeatable playlist-next # go to the next file
+#p {image} repeatable playlist-prev # go to the previous file
+#N {image} playlist-next-playlist   # go to the next sub-playlist
+#P {image} playlist-prev-playlist   # go to the previous sub-playlist
+
+#HOME {image} no-osd set playlist-pos 0                   # go to the first playlist entry
+#g-g  {image} no-osd set playlist-pos 0                   # go to the first playlist entry
+#END  {image} no-osd set playlist-pos-1 ${playlist-count} # go to the last playlist entry
+#G    {image} no-osd set playlist-pos-1 ${playlist-count} # go to the last playlist entry

options/options.c

@@ -474,6 +474,7 @@ static const m_option_t mp_opts[] = {
     {"profile", CONF_TYPE_STRING_LIST, 0, .offset = -1},
     {"show-profile", CONF_TYPE_STRING, M_OPT_NOCFG | M_OPT_NOPROP |
         M_OPT_OPTIONAL_PARAM,  .offset = -1},
+    {"apply-image-profile", OPT_BOOL(apply_image_profile)},
     {"list-options", &m_option_type_dummy_flag, M_OPT_NOCFG | M_OPT_NOPROP,
         .offset = -1},
     {"list-properties", OPT_BOOL(property_print_help),
@@ -1012,6 +1013,7 @@ static const struct MPOpts mp_default_opts = {
     .rebase_start_time = true,
     .keep_open_pause = true,
     .image_display_duration = 5.0,
+    .apply_image_profile = true,
     .stream_id = { { [STREAM_AUDIO] = -1,
                      [STREAM_VIDEO] = -1,
                      [STREAM_SUB] = -1, },

options/options.h

@@ -283,6 +283,7 @@ typedef struct MPOpts {
     int keep_open;
     bool keep_open_pause;
     double image_display_duration;
+    bool apply_image_profile;
     char *lavfi_complex;
     int stream_id[2][STREAM_TYPE_COUNT];
     char **stream_lang[STREAM_TYPE_COUNT];

player/core.h

@@ -437,6 +437,8 @@ typedef struct MPContext {
     // playback rate. Used to avoid showing it multiple times.
     bool drop_message_shown;
 
+    bool image_profile_applied;
+
     struct screenshot_ctx *screenshot_ctx;
     struct command_ctx *command_ctx;
     struct encode_lavc_context *encode_lavc_ctx;

player/loadfile.c

@@ -1519,6 +1519,29 @@ static void load_external_opts(struct MPContext *mpctx)
     mp_waiter_wait(&wait);
 }
 
+static void toggle_image_profile(struct MPContext *mpctx)
+{
+    if (!mpctx->opts->apply_image_profile)
+        return;
+
+    if (!mpctx->image_profile_applied &&
+        mpctx->current_track[0][STREAM_VIDEO] &&
+        mpctx->current_track[0][STREAM_VIDEO]->image &&
+        !mpctx->current_track[0][STREAM_AUDIO]) {
+        m_config_set_profile(mpctx->mconfig, "builtin-image", 0);
+        mp_input_enable_section(mpctx->input, "image",
+                                MP_INPUT_ALLOW_HIDE_CURSOR|MP_INPUT_ALLOW_VO_DRAGGING);
+        mpctx->image_profile_applied = true;
+    } else if (mpctx->image_profile_applied &&
+        (!mpctx->current_track[0][STREAM_VIDEO] ||
+         !mpctx->current_track[0][STREAM_VIDEO]->image ||
+         mpctx->current_track[0][STREAM_AUDIO])) {
+        m_config_restore_profile(mpctx->mconfig, "builtin-image");
+        mp_input_disable_section(mpctx->input, "image");
+        mpctx->image_profile_applied = false;
+    }
+}
+
 static void append_to_watch_history(struct MPContext *mpctx)
 {
     if (!mpctx->opts->save_watch_history)
@@ -1837,6 +1860,8 @@ static void play_current_file(struct MPContext *mpctx)
     if (!mpctx->vo_chain)
         handle_force_window(mpctx, true);
 
+    toggle_image_profile(mpctx);
+
     MP_VERBOSE(mpctx, "Starting playback...\n");
 
     mpctx->playback_initialized = true;