summaryrefslogtreecommitdiffstats
path: root/DOCS/man/vo.rst
diff options
context:
space:
mode:
Diffstat (limited to 'DOCS/man/vo.rst')
-rw-r--r--DOCS/man/vo.rst302
1 files changed, 170 insertions, 132 deletions
diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst
index 833fbddb1b..84c18f89bd 100644
--- a/DOCS/man/vo.rst
+++ b/DOCS/man/vo.rst
@@ -21,6 +21,47 @@ in the list.
Available video output drivers are:
+``gpu``
+ General purpose, customizable, GPU-accelerated video output driver. It
+ supports extended scaling methods, dithering, color management, custom
+ shaders, HDR, and more.
+
+ See `GPU renderer options`_ for options specific to this VO.
+
+ 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
+ ``--gpu-context`` options.
+
+ Hardware decoding over OpenGL-interop is supported to some degree. Note
+ that in this mode, some corner case might not be gracefully handled, and
+ color space conversion and chroma upsampling is generally in the hand of
+ the hardware decoder APIs.
+
+ ``gpu`` makes use of FBOs by default. Sometimes you can achieve better
+ quality or performance by changing the ``--fbo-format`` option to
+ ``rgb16f``, ``rgb32f`` or ``rgb``. Known problems include Mesa/Intel not
+ accepting ``rgb16``, Mesa sometimes not being compiled with float texture
+ support, and some macOS setups being very slow with ``rgb16`` but fast
+ with ``rgb32f``. If you have problems, you can also try enabling the
+ ``--gpu-dumb-mode=yes`` option.
+
+``gpu-next``
+ Experimental video renderer based on ``libplacebo``. This supports almost
+ the same set of features as ``--vo=gpu``. See `GPU renderer options`_ for a
+ list.
+
+ Should generally be faster and higher quality, but some features may still
+ be missing or misbehave. Expect (and report!) bugs. See here for a list of
+ known differences and bugs:
+
+ https://github.com/mpv-player/mpv/wiki/GPU-Next-vs-GPU
+
``xv`` (X11 only)
Uses the XVideo extension to enable hardware-accelerated display. This is
the most compatible VO on X, but may be low-quality, and has issues with
@@ -78,7 +119,9 @@ Available video output drivers are:
``vdpau`` (X11 only)
Uses the VDPAU interface to display and optionally also decode video.
- Hardware decoding is used with ``--hwdec=vdpau``.
+ Hardware decoding is used with ``--hwdec=vdpau``. Note that there is
+ absolutely no reason to use this, other than compatibility. We strongly
+ recommend that you use ``--vo=gpu`` with ``--hwdec=nvdec`` instead.
.. note::
@@ -228,35 +271,6 @@ Available video output drivers are:
``--vo-direct3d-exact-backbuffer``
Always resize the backbuffer to window size.
-``gpu``
- General purpose, customizable, GPU-accelerated video output driver. It
- supports extended scaling methods, dithering, color management, custom
- shaders, HDR, and more.
-
- 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``.
-
- This VO abstracts over several possible graphics APIs and windowing
- contexts, which can be influenced using the ``--gpu-api`` and
- ``--gpu-context`` options.
-
- Hardware decoding over OpenGL-interop is supported to some degree. Note
- that in this mode, some corner case might not be gracefully handled, and
- color space conversion and chroma upsampling is generally in the hand of
- the hardware decoder APIs.
-
- ``gpu`` makes use of FBOs by default. Sometimes you can achieve better
- quality or performance by changing the ``--fbo-format`` option to
- ``rgb16f``, ``rgb32f`` or ``rgb``. Known problems include Mesa/Intel not
- accepting ``rgb16``, Mesa sometimes not being compiled with float texture
- support, and some OS X setups being very slow with ``rgb16`` but fast
- with ``rgb32f``. If you have problems, you can also try enabling the
- ``--gpu-dumb-mode=yes`` option.
-
``sdl``
SDL 2.0+ Render video output driver, depending on system with or without
hardware acceleration. Should work on all platforms supported by SDL 2.0.
@@ -273,13 +287,23 @@ Available video output drivers are:
``--sdl-switch-mode``
Instruct SDL to switch the monitor video mode when going fullscreen.
+``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
that there is absolutely no reason to use this, other than compatibility.
- This is low quality, and has issues with OSD.
-
- .. note:: This driver is for compatibility with crappy systems. You can
- use vaapi hardware decoding with ``--vo=gpu`` too.
+ This is low quality, and has issues with OSD. We strongly recommend that
+ you use ``--vo=gpu`` with ``--hwdec=vaapi`` instead.
The following global options are supported by this video output:
@@ -293,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
@@ -336,7 +341,7 @@ Available video output drivers are:
``tct``
Color Unicode art video output driver that works on a text console.
By default depends on support of true color by modern terminals to display
- the images at full color range, but 256-colors outout is also supported (see
+ the images at full color range, but 256-colors output is also supported (see
below). On Windows it requires an ansi terminal such as mintty.
Since mpv 0.30.0, you may need to use ``--profile=sw-fast`` to get decent
@@ -363,13 +368,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.
@@ -413,18 +459,37 @@ 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-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>``
Selects the dither algorithm which libsixel should apply.
Can be one of the below list as per libsixel's documentation.
- auto
- Choose diffuse type automatically
+ auto (Default)
+ Let libsixel choose the dithering method.
none
Don't diffuse
atkinson
- Diffuse with Bill Atkinson's method. (Default)
+ Diffuse with Bill Atkinson's method.
fs
Diffuse with Floyd-Steinberg method
jajuni
@@ -444,20 +509,18 @@ Available video output drivers are:
using ``no`` (at the time of writing) will slow down ``xterm``.
``--vo-sixel-reqcolors=<colors>`` (default: 256)
- Set up libsixel to use required number of colors for dynamic palette.
- This value depends on the terminal emulator as well. Xterm supports
- 256 colors. Can set this to a lower value for faster performance.
- This option has no effect if fixed palette is used.
+ Has no effect with fixed palette. Set up libsixel to use required
+ number of colors for dynamic palette. This value depends on the
+ terminal emulator as well. Xterm supports 256 colors. Can set this to
+ a lower value for faster performance.
``--vo-sixel-threshold=<threshold>`` (default: -1)
- When using a dynamic palette, defines the threshold to change the
+ Has no effect with fixed palette. Defines the threshold to change the
palette - as percentage of the number of colors, e.g. 20 will change
the palette when the number of colors changed by 20%. It's a simple
measure to reduce the number of palette changes, because it can be slow
- in some terminals (``xterm``), however, it seems that in ``mlterm`` it
- causes image corruption. The default (-1) will change the palette
- on every frame and will have better quality, and no corruption in
- ``mlterm``.
+ in some terminals (``xterm``). The default (-1) will choose a palette
+ on every frame and will have better quality.
``image``
Output each frame into an image file in the current directory. Each file
@@ -496,7 +559,7 @@ Available video output drivers are:
Specify the directory to save the image files to (default: ``./``).
``libmpv``
- For use with libmpv direct embedding. As a special case, on OS X it
+ For use with libmpv direct embedding. As a special case, on macOS it
is used like a normal VO within mpv (cocoa-cb). Otherwise useless in any
other contexts.
(See ``<mpv/render.h>``.)
@@ -504,37 +567,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
@@ -546,13 +578,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. When using multiple graphic cards, use the ``<gpu_number>``
- argument to disambiguate.
- (default: empty)
+ connectors. (default: empty)
+
+ ``--drm-device=<path>``
+ Select the DRM device file to use. If specified this overrides automatic
+ card selection. (default: empty)
``--drm-mode=<preferred|highest|N|WxH[@R]>``
Mode to use (resolution and frame rate).
@@ -570,16 +604,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
@@ -588,11 +612,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)
@@ -603,32 +627,46 @@ 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>``
+ Toggle use of Variable Refresh Rate (VRR), aka Freesync or Adaptive Sync
+ on compatible systems. VRR allows for the display to be refreshed at any
+ rate within a range (usually ~40Hz-60Hz for 60Hz displays). This can help
+ with playback of 24/25/50fps content. Support depends on the use of a
+ compatible monitor, GPU, and a sufficiently new kernel with drivers
+ that support the feature.
+
+ :no: Do not attempt to enable VRR. (default)
+ :yes: Attempt to enable VRR, whether the capability is reported or not.
+ :auto: Attempt to enable VRR if support is reported.
+
``mediacodec_embed`` (Android)
Renders ``IMGFMT_MEDIACODEC`` frames directly to an ``android.view.Surface``.
Requires ``--hwdec=mediacodec`` for hardware decoding, along with
@@ -638,8 +676,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