diff options
Diffstat (limited to 'DOCS/man/options.rst')
| -rw-r--r-- | DOCS/man/options.rst | 508 |
1 files changed, 356 insertions, 152 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index db3a8db500..35f2b8862c 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -56,7 +56,7 @@ Track Selection behavior tends to change around with each mpv release. The track selection properties will return the option value outside of - playback (as expected), but during playbac, the affective track + playback (as expected), but during playback, the affective track selection is returned. For example, with ``--aid=auto``, the ``aid`` property will suddenly return ``2`` after playback initialization (assuming the file has at least 2 audio tracks, and the second is the @@ -213,7 +213,7 @@ Playback Control Slow down or speed up playback by the factor given as parameter. If ``--audio-pitch-correction`` (on by default) is used, playing with a - speed higher than normal automatically inserts the ``scaletempo`` audio + speed higher than normal automatically inserts the ``scaletempo2`` audio filter. ``--pause`` @@ -392,6 +392,13 @@ Playback Control difference between the two option is that this option performs a seek on loop, instead of reloading the file. + .. note:: + + ``--loop-file`` counts the number of times it causes the player to + seek to the beginning of the file, not the number of full playthroughs. This + means ``--loop-file=1`` will end up playing the file twice. Contrast with + ``--loop-playlist``, which counts the number of full playthroughs. + ``--loop`` is an alias for this option. ``--ab-loop-a=<time>``, ``--ab-loop-b=<time>`` @@ -844,6 +851,29 @@ Program Behavior - ``--reset-on-next-file=all`` Try to reset all settings that were changed during playback. +``--watch-later-options=option1,option2,...`` + The options that are saved in "watch later" files if they have been changed + since when mpv started. These values will be restored the next time the + files are played. The playback position is always saved as ``start``, so + adding ``start`` to this list has no effect. + + When removing options, existing watch later data won't be modified and will + still be applied fully, but new watch later data won't contain these + options. + + This is a string list option. See `List Options`_ for details. + + .. admonition:: Examples + + - ``--watch-later-options-remove=fullscreen`` + The fullscreen state won't be saved to watch later files. + - ``--watch-later-options-remove=volume`` + ``--watch-later-options-remove=mute`` + The volume and mute state won't be saved to watch later files. + - ``--watch-later-options-clr`` + No option will be saved to watch later files except the starting + position. + ``--write-filename-in-watch-later-config`` Prepend the watch later config files with the name of the file they refer to. This is simply written as comment on the top of the file. @@ -965,9 +995,11 @@ Program Behavior no). It's disabled ("no") by default for performance reasons. ``ytdl_path=youtube-dl`` - Configure path to youtube-dl executable or a compatible fork's. - The default "youtube-dl" looks for the executable in PATH. In a Windows - environment the suffix extension ".exe" is always appended. + Configure paths to youtube-dl's executable or a compatible fork's. The + paths should be separated by : on Unix and ; on Windows. mpv looks in + order for the configured paths in PATH and in mpv's config directory. + The defaults are "yt-dlp", "yt-dlp_x86" and "youtube-dl". On Windows + the suffix extension ".exe" is always appended. .. admonition:: Why do the option names mix ``_`` and ``-``? @@ -1196,9 +1228,9 @@ Video :vdpau-copy: copies video back into system RAM (Linux with some GPUs only) :vaapi: requires ``--vo=gpu`` or ``--vo=vaapi`` (Linux only) :vaapi-copy: copies video back into system RAM (Linux with some GPUs only) - :videotoolbox: requires ``--vo=gpu`` (OS X 10.8 and up), + :videotoolbox: requires ``--vo=gpu`` (macOS 10.8 and up), or ``--vo=libmpv`` (iOS 9.0 and up) - :videotoolbox-copy: copies video back into system RAM (OS X 10.8 or iOS 9.0 and up) + :videotoolbox-copy: copies video back into system RAM (macOS 10.8 or iOS 9.0 and up) :dxva2: requires ``--vo=gpu`` with ``--gpu-context=d3d11``, ``--gpu-context=angle`` or ``--gpu-context=dxinterop`` (Windows only) @@ -1477,11 +1509,14 @@ Video This option is disabled if the ``--no-keepaspect`` option is used. ``--video-rotate=<0-359|no>`` - Rotate the video clockwise, in degrees. Currently supports 90° steps only. - If ``no`` is given, the video is never rotated, even if the file has - rotation metadata. (The rotation value is added to the rotation metadata, - which means the value ``0`` would rotate the video according to the - rotation metadata.) + Rotate the video clockwise, in degrees. If ``no`` is given, the video is + never rotated, even if the file has rotation metadata. (The rotation value + is added to the rotation metadata, which means the value ``0`` would rotate + the video according to the rotation metadata.) + + When using hardware decoding without copy-back, only 90° steps work, while + software decoding and hardware decoding methods that copy the video back to + system memory support all values between 0 and 359. ``--video-zoom=<value>`` Adjust the video display scale factor by the given value. The parameter is @@ -1497,7 +1532,7 @@ Video video will be either cut off, or black bars are added. This value is multiplied with the value derived from ``--video-zoom`` and - the normal video aspect aspect ratio. This option is disabled if the + the normal video aspect ratio. This option is disabled if the ``--no-keepaspect`` option is used. ``--video-align-x=<-1-1>``, ``--video-align-y=<-1-1>`` @@ -1606,7 +1641,7 @@ Video You can get the list of allowed codecs with ``mpv --vd=help``. Remove the prefix, e.g. instead of ``lavc:h264`` use ``h264``. - By default, this is set to ``h264,vc1,hevc,vp9,av1``. Note that + By default, this is set to ``h264,vc1,hevc,vp8,vp9,av1``. Note that the hardware acceleration special codecs like ``h264_vdpau`` are not relevant anymore, and in fact have been removed from Libav in this form. @@ -1642,9 +1677,7 @@ Video slow hardware. This works only with the following VOs: - ``gpu``: requires at least OpenGL 4.4 or Vulkan. - - (In particular, this can't be made work with ``opengl-cb``, but the libmpv - render API has optional support.) + - ``libmpv``: The libmpv render API has optional support. Using video filters of any kind that write to the image data (or output newly allocated frames) will silently disable the DR code path. @@ -1739,7 +1772,7 @@ Audio ``--audio-pitch-correction=<yes|no>`` If this is enabled (default), playing with a speed different from normal - automatically inserts the ``scaletempo`` audio filter. For details, see + automatically inserts the ``scaletempo2`` audio filter. For details, see audio filter section. ``--audio-device=<name>`` @@ -2003,14 +2036,17 @@ Audio want. For example, most A/V receivers connected via HDMI and that can do 7.1 would be served by: ``--audio-channels=7.1,5.1,stereo`` -``--audio-display=<no|attachment>`` - Setting this option to ``attachment`` (default) will display image - attachments (e.g. album cover art) when playing audio files. It will - display the first image found, and additional images are available as - video tracks. +``--audio-display=<no|embedded-first|external-first>`` + Determines whether to display cover art when playing audio files and with + what priority. It will display the first image found, and additional images + are available as video tracks. - Setting this option to ``no`` disables display of video entirely when - playing audio files. + :no: Disable display of video entirely when playing audio + files. + :embedded-first: Display embedded images and external cover art, giving + priority to embedded images (default). + :external-first: Display embedded images and external cover art, giving + priority to external files. This option has no influence on files with normal video tracks. @@ -2091,7 +2127,7 @@ Audio :no: Don't automatically load external audio files (default). :exact: Load the media filename with audio file extension. - :fuzzy: Load all audio files containing media filename. + :fuzzy: Load all audio files containing the media filename. :all: Load all audio files in the current and ``--audio-file-paths`` directories. @@ -2471,7 +2507,7 @@ Subtitles :no: Don't automatically load external subtitle files. :exact: Load the media filename with subtitle file extension and possibly language suffixes (default). - :fuzzy: Load all subs containing media filename. + :fuzzy: Load all subs containing the media filename. :all: Load all subs in the current and ``--sub-file-paths`` directories. ``--sub-codepage=<codepage>`` @@ -2575,6 +2611,10 @@ Subtitles Can be used to disable display of subtitles, but still select and decode them. +``--secondary-sub-visibility``, ``--no-secondary-sub-visibility`` + Can be used to disable display of secondary subtitles, but still select and + decode them. + ``--sub-clear-on-seek`` (Obscure, rarely useful.) Can be used to play broken mkv files with duplicate ReadOrder fields. ReadOrder is the first field in a @@ -2587,6 +2627,13 @@ Subtitles This works for ``dvb_teletext`` subtitle streams, and if FFmpeg has been compiled with support for it. +``--sub-past-video-end`` + After the last frame of video, if this option is enabled, subtitles will + continue to update based on audio timestamps. Otherwise, the subtitles + for the last video frame will stay onscreen. + + Default: disabled + ``--sub-font=<name>`` Specify font to use for subtitles that do not themselves specify a particular font. The default is ``sans-serif``. @@ -2752,7 +2799,7 @@ Subtitles List items are matched in order. If a regular expression matches, the process is stopped, and the subtitle line is discarded. The text matched - against is, currently, always the ``Text`` field of ASS events (if the + against is, by default, the ``Text`` field of ASS events (if the subtitle format is different, it is always converted). This may include formatting tags. Matching is case-insensitive, but how this is done depends on the libc, and most likely works in ASCII only. It does not work on @@ -2774,6 +2821,17 @@ Subtitles include replacing the regexes with a very primitive and small subset of sed, or some method to control case-sensitivity. +``--sub-filter-jsre-...=...`` + Same as ``--sub-filter-regex`` but with JavaScript regular expressions. + Shares/affected-by all ``--sub-filter-regex-*`` control options (see below), + and also experimental. Requires only JavaScript support. + +``--sub-filter-regex-plain=<yes|no>`` + Whether to first convert the ASS "Text" field to plain-text (default: no). + This strips ASS tags and applies ASS directives, like ``\N`` to new-line. + If the result is multi-line then the regexp anchors ``^`` and ``$`` match + each line, but still any match discards all lines. + ``--sub-filter-regex-warn=<yes|no>`` Log dropped lines with warning log level, instead of verbose (default: no). Helpful for testing. @@ -2799,7 +2857,7 @@ Subtitles ``--sub-font-provider=<auto|none|fontconfig>`` Which libass font provider backend to use (default: auto). ``auto`` will attempt to use the native font provider: fontconfig on Linux, CoreText on - OSX, DirectWrite on Windows. ``fontconfig`` forces fontconfig, if libass + macOS, DirectWrite on Windows. ``fontconfig`` forces fontconfig, if libass was built with support (if not, it behaves like ``none``). The ``none`` font provider effectively disables system fonts. It will still @@ -2859,9 +2917,9 @@ Window This option works properly only with window managers which understand the EWMH ``_NET_WM_FULLSCREEN_MONITORS`` hint. - .. admonition:: Note (OS X) + .. admonition:: Note (macOS) - ``all`` does not work on OS X and will behave like ``current``. + ``all`` does not work on macOS and will behave like ``current``. See also ``--screen``. @@ -2968,7 +3026,7 @@ Window Manager. ``--ontop-level=<window|system|desktop|level>`` - (OS X only) + (macOS only) Sets the level of an ontop window (default: window). :window: On top of all other windows. @@ -2985,14 +3043,8 @@ Window Play video with window border and decorations. Since this is on by default, use ``--no-border`` to disable the standard window decorations. -``--fit-border``, ``--no-fit-border`` - (Windows only) Fit the whole window with border and decorations on the - screen. Since this is on by default, use ``--no-fit-border`` to make mpv - try to only fit client area with video on the screen. This behavior only - applied to window/video with size exceeding size of the screen. - ``--on-all-workspaces`` - (X11 only) + (X11 and macOS only) Show the video window on all virtual desktops. ``--geometry=<[W[xH]][+-x+-y][/WS]>``, ``--geometry=<x:y>`` @@ -3018,9 +3070,9 @@ Window Generally only supported by GUI VOs. Ignored for encoding. - .. admonition: Note (OS X) + .. admonition: Note (macOS) - On Mac OS X the origin of the screen coordinate system is located on the + On macOS, the origin of the screen coordinate system is located on the bottom-left corner. For instance, ``0:0`` will place the window at the bottom-left of the screen. @@ -3188,14 +3240,14 @@ Window - ``--monitoraspect=16:9`` or ``--monitoraspect=1.7777`` ``--hidpi-window-scale``, ``--no-hidpi-window-scale`` - (OS X, Windows, X11, and Wayland only) + (macOS, Windows, X11, and Wayland only) Scale the window size according to the backing scale factor (default: yes). On regular HiDPI resolutions the window opens with double the size but appears - as having the same size as on non-HiDPI resolutions. This is the default OS X - behavior. + as having the same size as on non-HiDPI resolutions. This is enabled by + default on macOS. ``--native-fs``, ``--no-native-fs`` - (OS X only) + (macOS only) Uses the native fullscreen mechanism of the OS (default: yes). ``--monitorpixelaspect=<ratio>`` @@ -3228,8 +3280,8 @@ Window ``intptr_t``. mpv will create its own window, and set the wid window as parent, like with X11. - On OSX/Cocoa, the ID is interpreted as ``NSView*``. Pass it as value cast - to ``intptr_t``. mpv will create its own sub-view. Because OSX does not + On macOS/Cocoa, the ID is interpreted as ``NSView*``. Pass it as value cast + to ``intptr_t``. mpv will create its own sub-view. Because macOS does not support window embedding of foreign processes, this works only with libmpv, and will crash when used from the command line. @@ -3778,7 +3830,15 @@ Input configuration directory (usually ``~/.config/mpv/input.conf``). ``--no-input-default-bindings`` - Disable mpv default (built-in) key bindings. + Disable default-level ("weak") key bindings. These are bindings which config + files like ``input.conf`` can override. It currently affects the builtin key + bindings, and keys which scripts bind using ``mp.add_key_binding`` (but not + ``mp.add_forced_key_binding`` because this overrides ``input.conf``). + +``--no-input-builtin-bindings`` + Disable loading of built-in key bindings during start-up. This option is + applied only during (lib)mpv initialization, and if used then it will not + be not possible to enable them later. May be useful to libmpv clients. ``--input-cmdlist`` Prints all commands that can be bound to keys. @@ -3866,8 +3926,15 @@ Input Support depends on the VO in use. ``--input-media-keys=<yes|no>`` - (OS X and Windows only) - Enable/disable media keys support. Enabled by default (except for libmpv). + On systems where mpv can choose between receiving media keys or letting + the system handle them - this option controls whether mpv should receive + them. + + Default: yes (except for libmpv). macOS and Windows only, because elsewhere + mpv doesn't have a choice - the system decides whether to send media keys + to mpv. For instance, on X11 or Wayland, system-wide media keys are not + implemented. Whether media keys work when the mpv window is focused is + implementation-defined. ``--input-right-alt-gr``, ``--no-input-right-alt-gr`` (Cocoa and Windows only) @@ -4569,12 +4636,6 @@ Cache Turn off input stream caching. See ``--cache``. ``--cache-secs=<seconds>`` - Deprecated. Once this option is removed, there will be no way to limit the - cache size by time (only by size with ``--demuxer-max-bytes``). This option - is considered useless, since there is no good reason to limit the cache by - time, and the default value of this option is already something very high. - The interaction with the other cache options is also confusing. - How many seconds of audio/video to prefetch if the cache is active. This overrides the ``--demuxer-readahead-secs`` option if and only if the cache is enabled and the value is larger. The default value is set to something @@ -4945,8 +5006,9 @@ ALSA audio output options GPU renderer options ----------------------- -The following video options are currently all specific to ``--vo=gpu`` and -``--vo=libmpv`` only, which are the only VOs that implement them. +The following video options are currently all specific to ``--vo=gpu``, +``--vo=libmpv`` and ``--vo=gpu-next``, which are the only VOs that implement +them. ``--scale=<filter>`` The filter function to use when upscaling video. @@ -5173,21 +5235,41 @@ The following video options are currently all specific to ``--vo=gpu`` and ``--interpolation-threshold=<0..1,-1>`` Threshold below which frame ratio interpolation gets disabled (default: - ``0.0001``). This is calculated as ``abs(disphz/vfps - 1) < threshold``, + ``0.01``). This is calculated as ``abs(disphz/vfps - 1) < threshold``, where ``vfps`` is the speed-adjusted video FPS, and ``disphz`` the display refresh rate. (The speed-adjusted video FPS is roughly equal to the normal video FPS, but with slowdown and speedup applied. This matters if you use ``--video-sync=display-resample`` to make video run synchronously to the display FPS, or if you change the ``speed`` property.) - The default is intended to almost always enable interpolation if the - playback rate is even slightly different from the display refresh rate. But - note that if you use e.g. ``--video-sync=display-vdrop``, small deviations - in the rate can disable interpolation and introduce a discontinuity every - other minute. + The default is intended to enable interpolation in scenarios where + retiming with the ``--video-sync=display-*`` cannot adjust the speed of + the video sufficiently for smooth playback. For example if a video is + 60.00 FPS and your display refresh rate is 59.94 Hz, interpolation will + never be activated, since the mismatch is within 1% of the refresh + rate. The default also handles the scenario when mpv cannot determine the + container FPS, such as during certain live streams, and may dynamically + toggle interpolation on and off. In this scenario, the default would be to + not use interpolation but rather to allow ``--video-sync=display-*`` to + retime the video to match display refresh rate. See + ``--video-sync-max-video-change`` for more information about how mpv + will retime video. + + Also note that if you use e.g. ``--video-sync=display-vdrop``, small + deviations in the rate can disable interpolation and introduce a + discontinuity every other minute. Set this to ``-1`` to disable this logic. +``--interpolation-preserve`` + Preserve the previous frames' interpolated results even when renderer + parameters are changed - with the exception of options related to + cropping and video placement, which always invalidate the cache. Enabling + this option makes dynamic updates of renderer settings slightly smoother at + the cost of slightly higher latency in response to such changes. Defaults + to on. (Only affects ``--vo=gpu-next``, note that ``-vo=gpu`` always + invalidates interpolated frames) + ``--opengl-pbo`` Enable use of PBOs. On some drivers this can be faster, especially if the source video size is huge (e.g. so called "4K" video). On other drivers it @@ -5277,6 +5359,12 @@ The following video options are currently all specific to ``--vo=gpu`` and results, as can missing or incorrect display FPS information (see ``--override-display-fps``). +``--vulkan-device=<device name>`` + The name of the Vulkan device to use for rendering and presentation. Use + ``--vulkan-device=help`` to see the list of available devices and their + names. If left unspecified, the first enumerated hardware Vulkan device will + be used. + ``--vulkan-swap-mode=<mode>`` Controls the presentation mode of the vulkan swapchain. This is similar to the ``--opengl-swapinterval`` option. @@ -5321,6 +5409,25 @@ The following video options are currently all specific to ``--vo=gpu`` and with some older drivers / vulkan portability layers that don't provide working VkEvent support. +``--vulkan-display-display=<n>`` + The index of the display, on the selected Vulkan device, to present on when + using the ``displayvk`` GPU context. Use ``--vulkan-display-display=help`` + to see the list of available displays. If left unspecified, the first + enumerated display will be used. + + +``--vulkan-display-mode=<n>`` + The index of the display mode, of the selected Vulkan display, to use when + using the ``displayvk`` GPU context. Use ``--vulkan-display-mode=help`` + to see the list of available modes. If left unspecified, the first + enumerated mode will be used. + +``--vulkan-display-plane=<n>`` + The index of the plane, on the selected Vulkan device, to present on when + using the ``displayvk`` GPU context. Use ``--vulkan-display-plane=help`` + to see the list of available planes. If left unspecified, the first + enumerated plane will be used. + ``--d3d11-exclusive-fs=<yes|no>`` Switches the D3D11 swap chain fullscreen state to 'fullscreen' when fullscreen video is requested. Also known as "exclusive fullscreen" or @@ -5402,8 +5509,7 @@ The following video options are currently all specific to ``--vo=gpu`` and Currently only relevant for ``--gpu-api=d3d11``. ``--wayland-app-id=<string>`` - Set the client app id for Wayland-based video output methods. By default, "mpv" - is used. + Set the client app id for Wayland-based video output methods (default: ``mpv``). ``--wayland-disable-vsync=<yes|no>`` Disable vsync for the wayland contexts (default: no). Useful for benchmarking @@ -5417,7 +5523,7 @@ The following video options are currently all specific to ``--vo=gpu`` and there are no server side decorations from the compositor. ``--wayland-edge-pixels-touch=<value>`` - Defines the size of an edge border (default: 64) to initiate client side + Defines the size of an edge border (default: 32) to initiate client side resizes events in the wayland contexts with touch events. ``--spirv-compiler=<compiler>`` @@ -5565,7 +5671,7 @@ The following video options are currently all specific to ``--vo=gpu`` and Specifies that this shader should be treated as a compute shader, with the block size bw and bh. The compute shader will be dispatched with however many blocks are necessary to completely tile over the output. - Within each block, there will bw tw*th threads, forming a single work + Within each block, there will be tw*th threads, forming a single work group. In other words: tw and th specify the work group size, which can be different from the block size. So for example, a compute shader with bw, bh = 32 and tw, th = 8 running on a 500x500 texture would dispatch @@ -5698,7 +5804,7 @@ The following video options are currently all specific to ``--vo=gpu`` and ``--deband-threshold=<0..4096>`` The debanding filter's cut-off threshold. Higher numbers increase the debanding strength dramatically but progressively diminish image details. - (Default 64) + (Default 32) ``--deband-range=<1..64>`` The debanding filter's initial radius. The radius increases linearly for @@ -5718,7 +5824,7 @@ The following video options are currently all specific to ``--vo=gpu`` and values will sharpen the image (but add more ringing and aliasing). Negative values will blur the image. If your GPU is powerful enough, consider alternatives like the ``ewa_lanczossharp`` scale filter, or the - ``--scale-blur`` option. + ``--scale-blur`` option. (Only for ``--vo=gpu``) ``--opengl-glfinish`` Call ``glFinish()`` before swapping buffers (default: disabled). Slower, @@ -5808,7 +5914,7 @@ The following video options are currently all specific to ``--vo=gpu`` and Deactivates the automatic graphics switching and forces the dedicated GPU. (default: no) - OS X only. + macOS only. ``--cocoa-cb-sw-renderer=<yes|no|auto>`` Use the Apple Software Renderer when using cocoa-cb (default: auto). If set @@ -5817,14 +5923,14 @@ The following video options are currently all specific to ``--vo=gpu`` and software renderer, and ``auto`` only falls back to the software renderer when the usual pixel format couldn't be created. - OS X only. + macOS only. ``--cocoa-cb-10bit-context=<yes|no>`` Creates a 10bit capable pixel format for the context creation (default: yes). Instead of 8bit integer framebuffer a 16bit half-float framebuffer is requested. - OS X only. + macOS only. ``--macos-title-bar-appearance=<appearance>`` Sets the appearance of the title bar (default: auto). Not all combinations @@ -5905,7 +6011,7 @@ The following video options are currently all specific to ``--vo=gpu`` and 1000ms since it's possible that Apple or the user changes the system defaults. Anything higher than 1000ms though seems too long and shouldn't be set anyway. - OS X and cocoa-cb only + (macOS and cocoa-cb only) ``--macos-app-activation-policy=<regular|accessory|prohibited>`` @@ -5914,6 +6020,16 @@ The following video options are currently all specific to ``--vo=gpu`` and macOS only. +``--macos-geometry-calculation=<visible|whole>`` + This changes the rectangle which is used to calculate the screen position + and size of the window (default: visible). ``visible`` takes the the menu + bar and Dock into account and the window is only positioned/sized within the + visible screen frame rectangle, ``whole`` takes the whole screen frame + rectangle and ignores the menu bar and Dock. Other previous restrictions + still apply, like the window can't be placed on top of the menu bar etc. + + macOS only. + ``--android-surface-size=<WxH>`` Set dimensions of the rendering surface used by the Android gpu context. Needs to be set by the embedding application if the dimensions change during @@ -5932,7 +6048,7 @@ The following video options are currently all specific to ``--vo=gpu`` and auto auto-select (default) cocoa - Cocoa/OS X (deprecated, use --vo=libmpv instead) + Cocoa/macOS (deprecated, use --vo=libmpv instead) win Win32/WGL winvk @@ -5957,6 +6073,10 @@ The following video options are currently all specific to ``--vo=gpu`` and VK_KHR_wayland_surface drm DRM/EGL + displayvk + VK_KHR_display. This backend is roughly the Vukan equivalent of + DRM/EGL, allowing for direct rendering via Vulkan without a display + manager. x11egl X11/EGL android @@ -5984,13 +6104,6 @@ The following video options are currently all specific to ``--vo=gpu`` and no Only allow desktop/core GL -``--opengl-restrict=<version>`` - Restricts all OpenGL versions above a certain version. Versions are encoded - in hundreds, i.e. OpenGL 4.5 -> 450. As an example, --opengl-restrict=300 - would restrict OpenGL 3.0 and higher, effectively only allowing 2.x - contexts. Note that this only imposes a limit on context creation APIs, the - actual OpenGL context may still have a higher OpenGL version. (Default: 0) - ``--fbo-format=<fmt>`` Selects the internal format of textures used for FBOs. The format can influence performance and quality of the video output. ``fmt`` can be one @@ -6027,7 +6140,35 @@ The following video options are currently all specific to ``--vo=gpu`` and With ambient illuminance of 16 lux, mpv will pick the 1.0 gamma value (no boost), and slightly increase the boost up until 1.2 for 256 lux. - NOTE: Only implemented on OS X. + NOTE: Only implemented on macOS. + +``--image-lut=<file>`` + Specifies a custom LUT file (in Adobe .cube format) to apply to the colors + during image decoding. The exact interpretation of the LUT depends on + the value of ``--image-lut-type``. (Only for ``--vo=gpu-next``) + +``--image-lut-type=<value>`` + Controls the interpretation of color values fed to and from the LUT + specified as ``--image-lut``. Valid values are: + + auto + Chooses the interpretation of the LUT automatically from tagged + metadata, and otherwise falls back to ``native``. (Default) + native + Applied to the raw image contents in its native colorspace, before + decoding to RGB. For example, for a HDR10 image, this would be fed + PQ-encoded YCbCr values in the range 0.0 - 1.0. + normalized + Applied to the normalized RGB image contents, after decoding from + its native color encoding, but before linearization. + conversion + Fully replaces the color decoding. A LUT of this type should ingest the + image's native colorspace and output normalized non-linear RGB. + +``--target-colorspace-hint`` + Automatically configure the output colorspace of the display to pass + through the input values of the stream (e.g. for HDR passthrough), if + possible. Requires a supporting driver and ``--vo=gpu-next``. ``--target-prim=<value>`` Specifies the primaries of the display. Video colors will be adapted to @@ -6144,12 +6285,20 @@ The following video options are currently all specific to ``--vo=gpu`` and In such a configuration, we highly recommend setting ``--tone-mapping`` to ``mobius`` or even ``clip``. +``--target-lut=<file>`` + Specifies a custom LUT file (in Adobe .cube format) to apply to the colors + before display on-screen. This LUT is fed values in normalized RGB, after + encoding into the target colorspace, so after the application of + ``--target-trc``. (Only for ``--vo=gpu-next``) + ``--tone-mapping=<value>`` Specifies the algorithm used for tone-mapping images onto the target display. This is relevant for both HDR->SDR conversion as well as gamut reduction (e.g. playing back BT.2020 content on a standard gamut display). Valid values are: + auto + Choose the best curve according to internal heuristics. (Default) clip Hard-clip any out-of-range values. Use this when you care about perfect color accuracy for in-range values at the cost of completely @@ -6175,13 +6324,17 @@ The following video options are currently all specific to ``--vo=gpu`` and you should also enable ``--hdr-compute-peak`` for the best results. bt.2390 Perceptual tone mapping curve (EETF) specified in ITU-R Report BT.2390. - This is the recommended curve to use for typical HDR-mastered content. - (Default) gamma Fits a logarithmic transfer between the tone curves. linear Linearly stretches the entire reference gamut to (a linear multiple of) the display. + spline + Perceptually linear single-pivot polynomial. (``--vo=gpu-next`` only) + bt.2446a + HDR<->SDR mapping specified in ITU-R Report BT.2446, method A. This is + the recommended curve for well-mastered content. (``--vo=gpu-next`` + only) ``--tone-mapping-param=<value>`` Set tone mapping parameters. By default, this is set to the special string @@ -6206,6 +6359,17 @@ The following video options are currently all specific to ``--vo=gpu`` and Specifies the exponent of the function. Defaults to 1.8. linear Specifies the scale factor to use while stretching. Defaults to 1.0. + spline + Specifies the knee point (in PQ space). Defaults to 0.30. + +``--inverse-tone-mapping`` + If set, allows inverse tone mapping (expanding SDR to HDR). Not supported + by all tone mapping curves. Use with caution. (``--vo=gpu-next`` only) + +``--tone-mapping-crosstalk=<0.0..0.30>`` + If nonzero, apply an extra crosstalk matrix before tone mapping. Can help + improve the appearance of strongly saturated monochromatic highlights. + (Default: 0.04, only affects ``--vo=gpu-next``) ``--tone-mapping-max-boost=<1.0..10.0>`` Upper limit for how much the tone mapping algorithm is allowed to boost @@ -6213,7 +6377,48 @@ The following video options are currently all specific to ``--vo=gpu`` and allows no additional brightness boost. A value of 2.0 would allow over-exposing by a factor of 2, and so on. Raising this setting can help reveal details that would otherwise be hidden in dark scenes, but raising - it too high will make dark scenes appear unnaturally bright. + it too high will make dark scenes appear unnaturally bright. (``-vo=gpu`` + only) + +``--tone-mapping-mode`` + Controls how the tone mapping function is applied to colors. + + auto + Choose the best mode automatically. (Default) + rgb + Tone-map per-channel (RGB). Has a tendency to severely distort colors, + desaturate highlights, and is generally not very recommended. However, + this is the mode used in many displays and TVs (especially early ones), + and so sometimes it's needed to reproduce the artistic intent a film + was mastered with. + max + Tone-map on the brightest component in the video. Has a tendency to + lead to weirdly oversaturated colors, and loss of dark details. + hybrid + A hybrid approach that uses linear tone-mapping for midtones and + per-channel tone mapping for highlights. + luma + Luminance-based method from ITU-R BT.2446a, including fixed gamut + reductions to account for brightness-related perceptual nonuniformity. + (``--vo=gpu-next`` only) + +``--gamut-mapping-mode`` + Specifies the algorithm used for reducing the gamut of images for the + target display, after any tone mapping is done. + + auto + Choose the best mode automatically. (Default) + clip + Hard-clip to the gamut (per-channel). + warn + Simply highlight out-of-gamut pixels. + desaturate + Chromatically desaturate out-of-gamut colors towards white. + darken + Linearly darken the entire image, then clip to the color volume. Unlike + ``clip``, this does not destroy detail in saturated regions, but comes + at the cost of sometimes significantly lowering output brightness. + (``--vo=gpu-next`` only) ``--hdr-compute-peak=<auto|yes|no>`` Compute the HDR peak and frame average brightness per-frame instead of @@ -6225,6 +6430,14 @@ The following video options are currently all specific to ``--vo=gpu`` and The special value ``auto`` (default) will enable HDR peak computation automatically if compute shaders and SSBOs are supported. +``--allow-delayed-peak-detect`` + When using ``--hdr-compute-peak``, allow delaying the detected peak by a + frame when beneficial for performance. In particular, this is required to + avoid an unnecessary FBO indirection when no advanced rendering is required + otherwise. Has no effect if there already is an indirect pass, such as when + advanced scaling is enabled. Defaults to on. (Only affects + ``--vo=gpu-next``, note that ``--vo=gpu`` always delays the peak.) + ``--hdr-peak-decay-rate=<1.0..1000.0>`` The decay rate used for the HDR peak detection algorithm (default: 100.0). This is only relevant when ``--hdr-compute-peak`` is enabled. Higher values @@ -6249,46 +6462,6 @@ The following video options are currently all specific to ``--vo=gpu`` and aggressive, up to the limit of the high threshold (at which point the filter becomes instant). -``--tone-mapping-desaturate=<0.0..1.0>`` - Apply desaturation for highlights (default: 0.75). The parameter controls - the strength of the desaturation curve. A value of 0.0 completely disables - it, while a value of 1.0 means that overly bright colors will tend towards - white. (This is not always the case, especially not for highlights that are - near primary colors) - - Values in between apply progressively more/less aggressive desaturation. - This setting helps prevent unnaturally oversaturated colors for - super-highlights, by (smoothly) turning them into less saturated (per - channel tone mapped) colors instead. This makes images feel more natural, - at the cost of chromatic distortions for out-of-range colors. The default - value of 0.75 provides a good balance. Setting this to 0.0 preserves the - chromatic accuracy of the tone mapping process. - -``--tone-mapping-desaturate-exponent=<0.0..20.0>`` - This setting controls the exponent of the desaturation curve, which - controls how bright a color needs to be in order to start being - desaturated. The default of 1.5 provides a reasonable balance. Decreasing - this exponent makes the curve more aggressive. - -``--gamut-warning`` - If enabled, mpv will mark all clipped/out-of-gamut pixels that exceed a - given threshold (currently hard-coded to 101%). The affected pixels will be - inverted to make them stand out. Note: This option applies after the - effects of all of mpv's color space transformation / tone mapping options, - so it's a good idea to combine this with ``--tone-mapping=clip`` and use - ``--target-prim`` to set the gamut to simulate. For example, - ``--target-prim=bt.709`` would make mpv highlight all pixels that exceed the - gamut of a standard gamut (sRGB) display. This option also does not work - well with ICC profiles, since the 3DLUTs are always generated against the - source color space and have chromatically-accurate clipping built in. - -``--gamut-clipping`` - If enabled (default: yes), mpv will colorimetrically clip out-of-gamut - colors |