From b731d70496f70fc8e5b039c5049fa71150c58fa2 Mon Sep 17 00:00:00 2001 From: Guido Cella Date: Thu, 16 Jan 2025 15:50:07 +0100 Subject: [PATCH] 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 conditional profile that users can extend in mpv.conf. It is written to not 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. sxiv is their main inspiration. Closes #7983, closes #12496. --- DOCS/man/mpv.rst | 158 +++++++++++++++++++++++++++++++++++++++++++++++ etc/builtin.conf | 16 +++++ etc/input.conf | 69 +++++++++++++++++++++ 3 files changed, 243 insertions(+) diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index a16930b5f83ad..ec5491acded3f 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -380,6 +380,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 ===== @@ -1038,6 +1115,87 @@ 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 conditional 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 extended in mpv.conf without overwriting it completely: + +.. admonition:: Example to loop image playlists + + :: + + [builtin-image] + loop-playlist + +You can stop applying it automatically by specifying an empty ``profile-cond``: + +.. admonition:: Example to disable the image conditional profile + + :: + + [builtin-image] + profile-cond= + +This profile uses ``--input-commands`` to enable image specific key bindings. +This can be disabled with ``input-commands-clr``. Extra commands should be +specified with ``input-commands-append`` to keep enabling the image key +bindings. 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 -------------------- diff --git a/etc/builtin.conf b/etc/builtin.conf index 6108cc71d546a..a5d969276e054 100644 --- a/etc/builtin.conf +++ b/etc/builtin.conf @@ -97,3 +97,19 @@ sub-shadow-offset=4 [box] profile=osd-box profile=sub-box + +[builtin-image] +profile-cond=(get('current-tracks/video', {}).image and not get('current-tracks/video', {}).albumart) or (not get('current-tracks/video') and get('user-data/mpv/image')) +profile-restore=copy-equal +input-commands-append=no-osd set user-data/mpv/image 1; enable-section image allow-hide-cursor+allow-vo-dragging +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 + +[builtin-non-image] +profile-cond=get('user-data/mpv/image') and (not get('current-tracks/video', {image = true}).image or get('current-tracks/audio')) +input-commands=no-osd del user-data/mpv/image; disable-section image diff --git a/etc/input.conf b/etc/input.conf index ed05bbd4148c6..51fcf744dcf12 100644 --- a/etc/input.conf +++ b/etc/input.conf @@ -234,3 +234,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.25 # zoom in +#- {image} add video-zoom -0.25 # zoom out +#+ {image} add video-zoom 0.05 # zoom in slowly +#_ {image} add video-zoom -0.05 # 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