diff options
Diffstat (limited to 'DOCS/man/vo.rst')
-rw-r--r-- | DOCS/man/vo.rst | 236 |
1 files changed, 135 insertions, 101 deletions
diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index 13d4050dc4..41fcb71a1b 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -28,10 +28,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 @@ -286,13 +287,17 @@ Available video output drivers are: ``--sdl-switch-mode`` Instruct SDL to switch the monitor video mode when going fullscreen. -``vaapi-wayland`` - Experimental Wayland output driver designed for use with 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`` driver; - OSD is also not supported. Supported compositors : Weston and Sway. +``dmabuf-wayland`` + Experimental Wayland output driver designed for use with either drm stateless + 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. + 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 @@ -312,25 +317,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 @@ -339,7 +325,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: @@ -350,6 +336,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`` @@ -362,7 +363,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>`` @@ -375,6 +376,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. @@ -382,13 +402,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. @@ -432,10 +493,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>`` @@ -525,37 +601,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 @@ -567,18 +612,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). @@ -596,16 +638,6 @@ Available video output drivers are: Use ``--drm-mode=help`` to get a list of available modes for all active connectors. - ``--drm-atomic=<no|auto>`` - Toggle use of atomic modesetting. Mostly useful for debugging. - - :no: Use legacy modesetting. - :auto: Use atomic modesetting, falling back to legacy modesetting if - not available. (default) - - Note: Only affects ``gpu-context=drm``. ``vo=drm`` supports legacy - modesetting only. - ``--drm-draw-plane=<primary|overlay|N>`` Select the DRM plane to which video and OSD is drawn to, under normal circumstances. The plane can be specified as ``primary``, which will @@ -614,11 +646,11 @@ Available video output drivers are: based, and related to the CRTC. (default: primary) - When using this option with the drmprime-drm hwdec interop, only the OSD - is rendered to this plane. + When using this option with the drmprime-overlay hwdec interop, only the + OSD is rendered to this plane. ``--drm-drmprime-video-plane=<primary|overlay|N>`` - Select the DRM plane to use for video with the drmprime-drm hwdec + Select the DRM plane to use for video with the drmprime-overlay hwdec interop (used by e.g. the rkmpp hwdec on RockChip SoCs, and v4l2 hwdec:s on various other SoC:s). The plane is unused otherwise. This option accepts the same values as ``--drm-draw-plane``. (default: overlay) @@ -629,30 +661,32 @@ 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 then be upscaled to the current screen resolution. This option can be - useful when used together with the drmprime-drm hwdec interop at high - resolutions, as it allows scaling the draw plane (which in this case - only handles the OSD) down to a size the GPU can handle. + useful when used together with the drmprime-overlay hwdec interop at + high resolutions, as it allows scaling the draw plane (which in this + case only handles the OSD) down to a size the GPU can handle. - When used without the drmprime-drm hwdec interop this option will just - cause the video to get rendered at a different resolution and then + When used without the drmprime-overlay hwdec interop this option will + just cause the video to get rendered at a different resolution and then scaled to screen size. - Note: this option is only available with DRM atomic support. (default: display resolution) ``--drm-vrr-enabled=<no|yes|auto>`` @@ -676,8 +710,8 @@ Available video output drivers are: many of mpv's features (subtitle rendering, OSD/OSC, video filters, etc) are not available with this driver. - To use hardware decoding with ``--vo=gpu`` instead, use - ``--hwdec=mediacodec-copy`` along with ``--gpu-context=android``. + To use hardware decoding with ``--vo=gpu`` instead, use ``--hwdec=mediacodec`` + or ``mediacodec-copy`` along with ``--gpu-context=android``. ``wlshm`` (Wayland only) Shared memory video output driver without hardware acceleration that works |