diff options
Diffstat (limited to 'DOCS/man/vo.rst')
-rw-r--r-- | DOCS/man/vo.rst | 200 |
1 files changed, 124 insertions, 76 deletions
diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index 213699fc64..d259cad907 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -19,6 +19,10 @@ in the list. does not work, it will fallback to other drivers (in the same order as listed by ``--vo=help``). + Note that the default video output driver is subject to change, and must + not be relied upon. If a certain VO needs to be used (e.g. for ``libmpv`` + rendering API), it must be explicitly specified. + Available video output drivers are: ``gpu`` @@ -28,10 +32,11 @@ Available video output drivers are: See `GPU renderer options`_ for options specific to this VO. - By default, it tries to use fast and fail-safe settings. Use the - ``gpu-hq`` profile to use this driver with defaults set to high quality - rendering. The profile can be applied with ``--profile=gpu-hq`` and its - contents can be viewed with ``--show-profile=gpu-hq``. + By default, mpv utilizes settings that balance quality and performance. + Additionally, two predefined profiles are available: ``fast`` for maximum + performance and ``high-quality`` for superior rendering quality. You can + apply a specific profile using the ``--profile=<name>`` option and inspect + its contents using ``--show-profile=<name>``. This VO abstracts over several possible graphics APIs and windowing contexts, which can be influenced using the ``--gpu-api`` and @@ -291,9 +296,12 @@ Available video output drivers are: or VA API hardware decoding. The driver is designed to avoid any GPU to CPU copies, and to perform scaling and color space conversion using fixed-function hardware, if available, rather than GPU shaders. This frees up GPU resources for other tasks. - Currently this driver is experimental and only works with the ``--hwdec=vaapi`` - or ``hwdec=drm`` drivers; - OSD is also not supported. Supported compositors : Weston and Sway. + It is highly recommended to use this VO with the appropriate ``--hwdec`` option such + as ``auto-safe``. It can still work in some circumstances without ``--hwdec`` due to + mpv's internal conversion filters, but this is not recommended as it's a needless + extra step. Correct output depends on support from your GPU, drivers, and compositor. + Weston and wlroots-based compositors like Sway and Intel GPUs are known to generally + work. ``vaapi`` Intel VA API video output driver with support for hardware decoding. Note @@ -313,25 +321,6 @@ Available video output drivers are: nla ``non-linear anamorphic scaling`` - ``--vo-vaapi-deint-mode=<mode>`` - Select deinterlacing algorithm. Note that by default deinterlacing is - initially always off, and needs to be enabled with the ``d`` key - (default key binding for ``cycle deinterlace``). - - This option doesn't apply if libva supports video post processing (vpp). - In this case, the default for ``deint-mode`` is ``no``, and enabling - deinterlacing via user interaction using the methods mentioned above - actually inserts the ``vavpp`` video filter. If vpp is not actually - supported with the libva backend in use, you can use this option to - forcibly enable VO based deinterlacing. - - no - Don't allow deinterlacing (default for newer libva). - first-field - Show only first field. - bob - bob deinterlacing (default for older libva). - ``--vo-vaapi-scaled-osd=<yes|no>`` If enabled, then the OSD is rendered at video resolution and scaled to display resolution. By default, this is disabled, and the OSD is @@ -340,7 +329,7 @@ Available video output drivers are: ``null`` Produces no video output. Useful for benchmarking. - Usually, it's better to disable video with ``--no-video`` instead. + Usually, it's better to disable video with ``--video=no`` instead. The following global options are supported by this video output: @@ -351,6 +340,21 @@ Available video output drivers are: ``caca`` Color ASCII art video output driver that works on a text console. + This driver reserves some keys for runtime configuration. These keys are + hardcoded and cannot be bound: + + d and D + Toggle dithering algorithm. + + a and A + Toggle antialiasing method. + + h and H + Toggle charset method. + + c and C + Toggle color method. + .. note:: This driver is a joke. ``tct`` @@ -363,7 +367,7 @@ Available video output drivers are: performance. Note: the TCT image output is not synchronized with other terminal output - from mpv, which can lead to broken images. The options ``--no-terminal`` or + from mpv, which can lead to broken images. The options ``--terminal=no`` or ``--really-quiet`` can help with that. ``--vo-tct-algo=<algo>`` @@ -376,6 +380,25 @@ Available video output drivers are: Uses spaces. Causes vertical resolution to drop twofolds, but in theory works in more places. + ``--vo-tct-buffering=<pixel|line|frame>`` + Specifies the size of data batches buffered before being sent to the + terminal. + + TCT image output is not synchronized with other terminal output from mpv, + which can lead to broken images. Sending data to the terminal in small + batches may improve parallelism between terminal processing and mpv + processing but incurs a static overhead of generating tens of thousands + of small writes. Also, depending on the terminal used, sending frames in + one chunk might help with tearing of the output, especially if not used + with ``--really-quiet`` and other logs interrupt the data stream. + + pixel + Send data to terminal for each pixel. + line + Send data to terminal for each line. (Default) + frame + Send data to terminal for each frame. + ``--vo-tct-width=<width>`` ``--vo-tct-height=<height>`` Assume the terminal has the specified character width and/or height. These default to 80x25 if the terminal size cannot be determined. @@ -383,13 +406,54 @@ Available video output drivers are: ``--vo-tct-256=<yes|no>`` (default: no) Use 256 colors - for terminals which don't support true color. +``kitty`` + Graphical output for the terminal, using the kitty graphics protocol. + Tested with kitty and Konsole. + + You may need to use ``--profile=sw-fast`` to get decent performance. + + Kitty size and alignment options: + + ``--vo-kitty-cols=<columns>``, ``--vo-kitty-rows=<rows>`` (default: 0) + Specify the terminal size in character cells, otherwise (0) read it + from the terminal, or fall back to 80x25. + + ``--vo-kitty-width=<width>``, ``--vo-kitty-height=<height>`` (default: 0) + Specify the available size in pixels, otherwise (0) read it from the + terminal, or fall back to 320x240. + + ``--vo-kitty-left=<col>``, ``--vo-kitty-top=<row>`` (default: 0) + Specify the position in character cells where the image starts (1 is + the first column or row). If 0 (default) then try to automatically + determine it according to the other values and the image aspect ratio + and zoom. + + ``--vo-kitty-config-clear=<yes|no>`` (default: yes) + Whether or not to clear the terminal whenever the output is + reconfigured (e.g. when video size changes). + + ``--vo-kitty-alt-screen=<yes|no>`` (default: yes) + Whether or not to use the alternate screen buffer and return the + terminal to its previous state on exit. When set to no, the last + kitty image stays on screen after quit, with the cursor following it. + + ``--vo-kitty-use-shm=<yes|no>`` (default: no) + Use shared memory objects to transfer image data to the terminal. + This is much faster than sending the data as escape codes, but is not + supported by as many terminals. It also only works on the local machine + and not via e.g. SSH connections. + + This option is not implemented on Windows. + ``sixel`` Graphical output for the terminal, using sixels. Tested with ``mlterm`` and ``xterm``. - Note: the Sixel image output is not synchronized with other terminal output - from mpv, which can lead to broken images. The option ``--really-quiet`` - can help with that, and is recommended. + Note: the Sixel image output is not synchronized with other terminal + output from mpv, which can lead to broken images. + The option ``--really-quiet`` can help with that, and is recommended. + On some platforms, using the ``--vo-sixel-buffered`` option may work as + well. You may need to use ``--profile=sw-fast`` to get decent performance. @@ -433,10 +497,25 @@ Available video output drivers are: to take into account padding at the report - this only works correctly when the overall padding per axis is smaller than the number of cells. - ``--vo-sixel-exit-clear=<yes|no>`` (default: yes) - Whether or not to clear the terminal on quit. When set to no - the last + ``--vo-sixel-config-clear=<yes|no>`` (default: yes) + Whether or not to clear the terminal whenever the output is + reconfigured (e.g. when video size changes). + + ``--vo-sixel-alt-screen=<yes|no>`` (default: yes) + Whether or not to use the alternate screen buffer and return the + terminal to its previous state on exit. When set to no, the last sixel image stays on screen after quit, with the cursor following it. + ``--vo-sixel-exit-clear`` is a deprecated alias for this option and + may be removed in the future. + + ``--vo-sixel-buffered=<yes|no>`` (default: no) + Buffers the full output sequence before writing it to the terminal. + On POSIX platforms, this can help prevent interruption (including from + other applications) and thus broken images, but may come at a + performance cost with some terminals and is subject to implementation + details. + Sixel image quality options: ``--vo-sixel-dither=<algo>`` @@ -526,37 +605,6 @@ Available video output drivers are: This also supports many of the options the ``gpu`` VO has, depending on the backend. -``rpi`` (Raspberry Pi) - Native video output on the Raspberry Pi using the MMAL API. - - This is deprecated. Use ``--vo=gpu`` instead, which is the default and - provides the same functionality. The ``rpi`` VO will be removed in - mpv 0.23.0. Its functionality was folded into --vo=gpu, which now uses - RPI hardware decoding by treating it as a hardware overlay (without applying - GL filtering). Also to be changed in 0.23.0: the --fs flag will be reset to - "no" by default (like on the other platforms). - - The following deprecated global options are supported by this video output: - - ``--rpi-display=<number>`` - Select the display number on which the video overlay should be shown - (default: 0). - - ``--rpi-layer=<number>`` - Select the dispmanx layer on which the video overlay should be shown - (default: -10). Note that mpv will also use the 2 layers above the - selected layer, to handle the window background and OSD. Actual video - rendering will happen on the layer above the selected layer. - - ``--rpi-background=<yes|no>`` - Whether to render a black background behind the video (default: no). - Normally it's better to kill the console framebuffer instead, which - gives better performance. - - ``--rpi-osd=<yes|no>`` - Enabled by default. If disabled with ``no``, no OSD layer is created. - This also means there will be no subtitles rendered. - ``drm`` (Direct Rendering Manager) Video output driver using Kernel Mode Setting / Direct Rendering Manager. Should be used when one doesn't want to install full-blown graphical @@ -568,18 +616,15 @@ Available video output drivers are: The following global options are supported by this video output: - ``--drm-connector=[<gpu_number>.]<name>`` + ``--drm-connector=<name>`` Select the connector to use (usually this is a monitor.) If ``<name>`` is empty or ``auto``, mpv renders the output on the first available connector. Use ``--drm-connector=help`` to get a list of available - connectors. The ``<gpu_number>`` argument can be used to disambiguate - multiple graphic cards, but is deprecated in favor of ``--drm-device``. - (default: empty) + connectors. (default: empty) ``--drm-device=<path>`` Select the DRM device file to use. If specified this overrides automatic - card selection and any card number specified ``--drm-connector``. - (default: empty) + card selection. (default: empty) ``--drm-mode=<preferred|highest|N|WxH[@R]>`` Mode to use (resolution and frame rate). @@ -620,17 +665,20 @@ Available video output drivers are: lower resolution (the video when handled by the hwdec will be on the drmprime-video plane and at full 4K resolution) - ``--drm-format=<xrgb8888|xrgb2101010>`` + ``--drm-format=<xrgb8888|xbgr8888|xrgb2101010|xbgr2101010|yuyv>`` Select the DRM format to use (default: xrgb8888). This allows you to - choose the bit depth of the DRM mode. xrgb8888 is your usual 24 bit per - pixel/8 bits per channel packed RGB format with 8 bits of padding. - xrgb2101010 is a packed 30 bits per pixel/10 bits per channel packed RGB - format with 2 bits of padding. + choose the bit depth and color type of the DRM mode. + + xrgb8888 is your usual 24bpp packed RGB format with 8 bits of padding. + xrgb2101010 is a 30bpp packed RGB format with 2 bits of padding. + yuyv is a 32bpp packed YUV 4:2:2 format. No planar formats are currently + supported. There are cases when xrgb2101010 will work with the ``drm`` VO, but not with the ``drm`` backend for the ``gpu`` VO. This is because with the ``gpu`` VO, in addition to requiring support in your DRM driver, - requires support for xrgb2101010 in your EGL driver + requires support for xrgb2101010 in your EGL driver. + yuyv only ever works with the ``drm`` VO. ``--drm-draw-surface-size=<[WxH]>`` Sets the size of the surface used on the draw plane. The surface will |