summaryrefslogtreecommitdiffstats
path: root/DOCS/man/options.rst
diff options
context:
space:
mode:
Diffstat (limited to 'DOCS/man/options.rst')
-rw-r--r--DOCS/man/options.rst2019
1 files changed, 1306 insertions, 713 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 16625fe0c4..1b6e1465de 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -5,10 +5,11 @@ Track Selection
---------------
``--alang=<languagecode[,languagecode,...]>``
- Specify a priority list of audio languages to use. Different container
- formats employ different language codes. DVDs use ISO 639-1 two-letter
- language codes, Matroska, MPEG-TS and NUT use ISO 639-2 three-letter
- language codes, while OGM uses a free-form identifier. See also ``--aid``.
+ Specify a priority list of audio languages to use, as IETF language tags.
+ Equivalent ISO 639-1 two-letter and ISO 639-2 three-letter codes are treated the same.
+ The first tag in the list whose language matches a track in the file will be used.
+ A track that matches more subtags will be preferred over one that matches fewer,
+ with preference given to earlier subtags over later ones. See also ``--aid``.
This is a string list option. See `List Options`_ for details.
@@ -20,10 +21,7 @@ Track Selection
audio.
``--slang=<languagecode[,languagecode,...]>``
- Specify a priority list of subtitle languages to use. Different container
- formats employ different language codes. DVDs use ISO 639-1 two letter
- language codes, Matroska uses ISO 639-2 three letter language codes while
- OGM uses a free-form identifier. See also ``--sid``.
+ Equivalent to ``--alang``, for subtitle tracks.
This is a string list option. See `List Options`_ for details.
@@ -33,6 +31,8 @@ Track Selection
a DVD and falls back on English if Hungarian is not available.
- ``mpv --slang=jpn example.mkv`` plays a Matroska file with Japanese
subtitles.
+ - ``mpv --slang=pt-BR example.mkv`` plays a Matroska file with Brazilian
+ Portuguese subtitles if available, and otherwise any Portuguese subtitles.
``--vlang=<...>``
Equivalent to ``--alang`` and ``--slang``, for video tracks.
@@ -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
@@ -135,10 +135,31 @@ Track Selection
Note that if ``--lavfi-complex`` is set before playback is started, the
referenced tracks are always selected.
-``--subs-with-matching-audio=<yes|no>``
- When autoselecting a subtitle track, select a non-forced one even if the selected
- audio stream matches your preferred subtitle language (default: yes). Disable this
- if you'd like to only show subtitles for foreign audio or onscreen text.
+``--subs-with-matching-audio=<yes|forced|no>``
+ When autoselecting a subtitle track, select it even if the selected audio
+ stream matches you preferred subtitle language (default: yes). If this
+ option is set to ``no``, then no subtitle track that matches the audio
+ language will ever be autoselected by mpv regardless of ``--slang`` or
+ ``subs-fallback``. If set to ``forced``, then only forced subtitles
+ will be selected.
+
+``--subs-match-os-language=<yes|no>``
+ When autoselecting a subtitle track, select the track that matches the language of your OS
+ if the audio stream is in a different language if suitable (default track or a forced track
+ under the right conditions). Note that if ``-slang`` is set, this will be completely ignored
+ (default: yes).
+
+``--subs-fallback=<yes|default|no>``
+ When autoselecting a subtitle track, if no tracks match your preferred languages,
+ select a full track even if it doesn't match your preferred subtitle language (default: default).
+ Setting this to `default` means that only streams flagged as `default` will be selected.
+
+``--subs-fallback-forced=<yes|no|always>``
+ When autoselecting a subtitle track, the default value of `yes` will prefer using a forced
+ subtitle track if the subtitle language matches the audio language and matches your list of
+ preferred languages. The special value `always` will only select forced subtitle tracks and
+ never fallback on a non-forced track. Conversely, `no` will never select a forced subtitle
+ track.
Playback Control
@@ -213,7 +234,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``
@@ -260,7 +281,7 @@ Playback Control
The way older versions of mpv played playlist files via ``--playlist``
was not safe against maliciously constructed files. Such files may
- trigger harmful actions. This has been the case for all verions of
+ trigger harmful actions. This has been the case for all versions of
mpv prior to 0.31.0, and all MPlayer versions, but unfortunately this
fact was not well documented earlier, and some people have even
misguidedly recommended the use of ``--playlist`` with untrusted
@@ -298,10 +319,10 @@ Playback Control
:no: Never use precise seeks.
:absolute: Use precise seeks if the seek is to an absolute position in the
file, such as a chapter seek, but not for relative seeks like
- the default behavior of arrow keys (default).
+ the default behavior of arrow keys.
:default: Like ``absolute``, but enable hr-seeks in audio-only cases. The
exact behavior is implementation specific and may change with
- new releases.
+ new releases (default).
:yes: Use precise seeks whenever possible.
:always: Same as ``yes`` (for compatibility).
@@ -392,10 +413,12 @@ Playback Control
difference between the two option is that this option performs a seek on
loop, instead of reloading the file.
- Note that ``--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.
+ .. 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.
@@ -463,7 +486,7 @@ Playback Control
of them fails. This doesn't affect playback of audio-only or video-only
files.
-``--play-dir=<forward|+|backward|->``
+``--play-direction=<forward|+|backward|->``
Control the playback direction (default: forward). Setting ``backward``
will attempt to play the file in reverse direction, with decreasing
playback time. If this is set on playback starts, playback will start from
@@ -581,7 +604,7 @@ Playback Control
Tuning:
- Remove all ``--vf``/``--af`` filters you have set. Disable hardware
- decoding. Disable idiotic nonsense like SPDIF passthrough.
+ decoding. Disable functions like SPDIF passthrough.
- Increasing ``--video-reversal-buffer`` might help if reversal queue
overflow is reported, which may happen in high bitrate video, or video
@@ -680,7 +703,7 @@ Playback Control
``--demuxer-backward-playback-step=<seconds>``
Number of seconds the demuxer should seek back to get new packets during
backward playback (default: 60). This is useful for tuning backward
- playback, see ``--play-dir`` for details.
+ playback, see ``--play-direction`` for details.
Setting this to a very low value or 0 may make the player think seeking is
broken, or may make it perform multiple seeks.
@@ -706,9 +729,10 @@ Program Behavior
Print version string and exit.
``--no-config``
- Do not load default configuration files. This prevents loading of both the
- user-level and system-wide ``mpv.conf`` and ``input.conf`` files. Other
- configuration files are blocked as well, such as resume playback files.
+ Do not load default configuration or any user files. This prevents loading of
+ both the user-level and system-wide ``mpv.conf`` and ``input.conf`` files. Other
+ user files are blocked as well, such as resume playback files and cache files.
+ This option only takes effect when used as a command line flag.
.. note::
@@ -742,24 +766,10 @@ Program Behavior
as well as per-user directories are ignored, and overrides through
environment variables (``MPV_HOME``) are also ignored.
- Note that the ``--no-config`` option takes precedence over this option.
-
-``--save-position-on-quit``
- Always save the current playback position on quit. When this file is
- played again later, the player will seek to the old playback position on
- start. This does not happen if playback of a file is stopped in any other
- way than quitting. For example, going to the next file in the playlist
- will not save the position, and start playback at beginning the next time
- the file is played.
-
- This behavior is disabled by default, but is always available when quitting
- the player with Shift+Q.
-
-``--watch-later-directory=<path>``
- The directory in which to store the "watch later" temporary files.
+ Note that the cache and state paths (``~~/cache``, ``~~/state``) are not
+ considered "configuration" and keep their auto-detection logic.
- The default is a subdirectory named "watch_later" underneath the
- config directory (usually ``~/.config/mpv/``).
+ Note that the ``--no-config`` option takes precedence over this option.
``--dump-stats=<filename>``
Write certain statistics to the given file. The file is truncated on
@@ -802,18 +812,6 @@ Program Behavior
Pretend that all files passed to mpv are concatenated into a single, big
file. This uses timeline/EDL support internally.
-``--no-resume-playback``
- Do not restore playback position from the ``watch_later`` configuration
- subdirectory (usually ``~/.config/mpv/watch_later/``).
- See ``quit-watch-later`` input command.
-
-``--resume-playback-check-mtime``
- Only restore the playback position from the ``watch_later`` configuration
- subdirectory (usually ``~/.config/mpv/watch_later/``) if the file's
- modification time is the same as at the time of saving. This may prevent
- skipping forward in files with the same name which have different content.
- (Default: ``no``)
-
``--profile=<profile1,profile2,...>``
Use the given profile(s), ``--profile=help`` displays a list of the
defined profiles.
@@ -831,10 +829,6 @@ Program Behavior
value. The initial value is either the default value, or as set by the
config file or command line.
- In some cases, this might not work as expected. For example, ``--volume``
- will only be reset if it is explicitly set in the config file or the
- command line.
-
The special name ``all`` resets as many options as possible.
This is a string list option. See `List Options`_ for details.
@@ -849,19 +843,6 @@ Program Behavior
- ``--reset-on-next-file=all``
Try to reset all settings that were changed during playback.
-``--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.
-
- .. warning::
-
- This option may expose privacy-sensitive information and is thus
- disabled by default.
-
-``--ignore-path-in-watch-later-config``
- Ignore path (i.e. use filename only) when using watch later feature.
- (Default: disabled)
-
``--show-profile=<profile>``
Show the description and content of a profile. Lists all profiles if no
parameter is provided.
@@ -964,15 +945,24 @@ Program Behavior
``all_formats`` is set to 'no', and the stream selection as done by
youtube-dl (via ``--ytdl-format``) is used.
+ ``thumbnails=<all|best|none>``
+ Add thumbnails as video tracks (default: none).
+
+ Thumbnails get downloaded when they are added as tracks, so 'all' can
+ have a noticable impact on how long it takes to open the video when
+ there are a lot of thumbnails.
+
``use_manifests=<yes|no>``
Make mpv use the master manifest URL for formats like HLS and DASH,
if available, allowing for video/audio selection in runtime (default:
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 is not necessary, but only ".exe" is acceptable.
.. admonition:: Why do the option names mix ``_`` and ``-``?
@@ -1013,16 +1003,21 @@ Program Behavior
- ``--ytdl-raw-options=proxy=[http://127.0.0.1:3128]``
- ``--ytdl-raw-options-append=proxy=http://127.0.0.1:3128``
+``--js-memory-report=<yes|no>``
+ Enable memory reporting for javascript scripts in the stats overlay.
+ This is disabled by default because it has an overhead and increases
+ memory usage. This option will only work if it is enabled before mpv is
+ started.
+
``--load-stats-overlay=<yes|no>``
Enable the builtin script that shows useful playback information on a key
binding (default: yes). By default, the ``i`` key is used (``I`` to make
the overlay permanent).
``--load-osd-console=<yes|no>``
- Enable the builtin script that shows a console on a key binding and lets
- you enter commands (default: yes). By default,. The ``´`` key is used to
- show the console, and ``ESC`` to hide it again. (This is based on a user
- script called ``repl.lua``.)
+ Enable the built-in script that shows a console on a key binding and lets
+ you enter commands (default: yes). The ````` key is used to show the
+ console by default, and ``ESC`` to hide it again.
``--load-auto-profiles=<yes|no|auto>``
Enable the builtin script that does auto profiles (default: auto). See
@@ -1035,6 +1030,81 @@ Program Behavior
only by mpv internally, or mpv-provided scripts, config files, or .desktop
files. See `PSEUDO GUI MODE`_ for details.
+Watch Later
+-----------
+
+``--save-position-on-quit``
+ Always save the current playback position on quit. When this file is
+ played again later, the player will seek to the old playback position on
+ start. This does not happen if playback of a file is stopped in any other
+ way than quitting. For example, going to the next file in the playlist
+ will not save the position, and start playback at beginning the next time
+ the file is played.
+
+ This behavior is disabled by default, but is always available when quitting
+ the player with Shift+Q.
+
+ See `RESUMING PLAYBACK`_.
+
+``--watch-later-dir=<path>``
+ The directory in which to store the "watch later" temporary files.
+
+ ``--watch-later-directory`` is an alias for ``--watch-later-dir``.
+
+ If this option is unset, the files will be stored in a subdirectory
+ named "watch_later" underneath the local state directory
+ (usually ``~/.local/state/mpv/``).
+
+``--no-resume-playback``
+ Do not restore playback position from the ``watch_later`` configuration
+ subdirectory (usually ``~/.config/mpv/watch_later/``).
+
+``--resume-playback-check-mtime``
+ Only restore the playback position from the ``watch_later`` configuration
+ subdirectory (usually ``~/.config/mpv/watch_later/``) if the file's
+ modification time is the same as at the time of saving. This may prevent
+ skipping forward in files with the same name which have different content.
+ (Default: ``no``)
+
+``--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. Note that the playback position is saved via the ``start``
+ option.
+
+ 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.
+
+ See ``--help=watch-later-options`` for the list of the properties that are
+ restored by default.
+
+ This is a string list option. See `List Options`_ for details.
+
+ .. admonition:: Examples
+
+ - ``--watch-later-options-remove=sid``
+ The subtitle track selection will not be restored.
+ - ``--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=start``
+ No option will be saved to watch later files, except the playback
+ 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.
+
+ .. warning::
+
+ This option may expose privacy-sensitive information and is thus
+ disabled by default.
+
+``--ignore-path-in-watch-later-config``
+ Ignore path (i.e. use filename only) when using watch later feature.
+ (Default: disabled)
+
Video
-----
@@ -1055,9 +1125,9 @@ Video
``--vf=<filter1[=parameter1:parameter2:...],filter2,...>``
Specify a list of video filters to apply to the video stream. See
`VIDEO FILTERS`_ for details and descriptions of the available filters.
- The option variants ``--vf-add``, ``--vf-pre``, ``--vf-del`` and
- ``--vf-clr`` exist to modify a previously specified list, but you
- should not need these for typical use.
+ The option variants ``--vf-add``, ``--vf-pre``, and ``--vf-clr`` exist
+ to modify a previously specified list, but you should not need these for
+ typical use.
``--untimed``
Do not sleep when outputting video frames. Useful for benchmarks when used
@@ -1116,7 +1186,8 @@ Video
Enable some things which tend to reduce video latency by 1 or 2 frames
(default: no). Note that this option might be removed without notice once
the player's timing code does not inherently need to do these things
- anymore.
+ anymore. Using this option is known to break other options such as
+ interpolation, so it is not recommended to enable this.
This does:
@@ -1131,7 +1202,7 @@ Video
frame, so if this is not done, there is some likeliness that the VO has
to drop some frames if rendering the first frame takes longer than needed.
-``--override-display-fps=<fps>``
+``--display-fps-override=<fps>``
Set the display FPS used with the ``--video-sync=display-*`` modes. By
default, a detected value is used. Keep in mind that setting an incorrect
value (even if slightly incorrect) can ruin video playback. On multi-monitor
@@ -1141,34 +1212,45 @@ Video
Set this option only if you have reason to believe the automatically
determined value is wrong.
-``--display-fps=<fps>``
- Deprecated alias for ``--override-display-fps``.
-
-``--hwdec=<api>``
+``--hwdec=<api1,api2,...|no|auto|auto-safe|auto-copy>``
Specify the hardware video decoding API that should be used if possible.
Whether hardware decoding is actually done depends on the video codec. If
hardware decoding is not possible, mpv will fall back on software decoding.
- Hardware decoding is not enabled by default, because it is typically an
- additional source of errors. It is worth using only if your CPU is too
- slow to decode a specific video.
+ Hardware decoding is not enabled by default, to keep the out-of-the-box
+ configuration as reliable as possible. However, when using modern hardware,
+ hardware video decoding should work correctly, offering reduced CPU usage,
+ and possibly lower power consumption. On older systems, it may be necessary
+ to use hardware decoding due to insufficient CPU resources; and even on
+ modern systems, sufficiently complex content (eg: 4K60 AV1) may require it.
.. note::
Use the ``Ctrl+h`` shortcut to toggle hardware decoding at runtime. It
- toggles this option between ``auto`` and ``no``.
-
- Always enabling HW decoding by putting it into the config file is
- discouraged. If you use the Ubuntu package, delete ``/etc/mpv/mpv.conf``,
- as the package tries to enable HW decoding by default by setting
- ``hwdec=vaapi`` (which is less than ideal, and may even cause
- sub-optimal wrappers to be used). Or at least change it to
- ``hwdec=auto-safe``.
-
- Use one of the auto modes if you want to enable hardware decoding.
- Explicitly selecting the mode is mostly meant for testing and debugging.
- It's a bad idea to put explicit selection into the config file if you
- want thing to just keep working after updates and so on.
+ toggles this option between ``auto-safe`` and ``no``.
+
+ If you decide you want to use hardware decoding by default, the general
+ recommendation is to try out decoding with the command line option, and
+ prove to yourself that it works as desired for the content you care
+ about. After that, you can add it to your config file.
+
+ When testing, you should start by using ``hwdec=auto-safe`` as it will
+ limit itself to choosing from hwdecs that are actively supported by the
+ development team. If that doesn't result in working hardware decoding,
+ you can try ``hwdec=auto`` to have it attempt to load every possible
+ hwdec, but if ``auto-safe`` didn't work, you will probably need to know
+ exactly which hwdec matches your hardware and read up on that entry
+ below.
+
+ If ``auto-safe`` or ``auto`` produced the desired results, we recommend
+ just sticking with that and only setting a specific hwdec in your config
+ file if it is really necessary.
+
+ If you use the Ubuntu package, keep in mind that their
+ ``/etc/mpv/mpv.conf`` contains ``hwdec=vaapi``, which is less than
+ ideal as it may not be the right choice for your system, and it may end
+ up using an inefficient wrapper library under the covers. We recommend
+ removing this line or deleting the file altogether.
.. note::
@@ -1183,40 +1265,56 @@ Video
``Ctrl+h`` default binding to enable it at runtime.
- If you're not sure, but want hardware decoding always enabled by
default, put ``hwdec=auto-safe`` into your ``mpv.conf``, and
- acknowledge that this use case is not "really" supported and may cause
- problems.
+ acknowledge that this may cause problems.
- If you want to test available hardware decoding methods, pass
``--hwdec=auto --hwdec-codecs=all`` and look at the terminal output.
- If you're a developer, or want to perform elaborate tests, you may
need any of the other possible option values.
- ``<api>`` can be one of the following:
+ This option accepts a comma delimited list of ``api`` types, along with certain
+ special values:
:no: always use software decoding (default)
- :auto: forcibly enable any hw decoder found (see below)
- :yes: exactly the same as ``auto``
:auto-safe: enable any whitelisted hw decoder (see below)
+ :auto: forcibly enable any hw decoder found (see below)
+ :yes: exactly the same as ``auto-safe``
:auto-copy: enable best hw decoder with copy-back (see below)
- :vdpau: requires ``--vo=gpu`` with X11, or ``--vo=vdpau`` (Linux only)
- :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)
+
+ .. note::
+
+ Special values can be mixed with api names. eg: ``vaapi,auto`` will try
+ and use the ``vaapi`` hwdec, and if that fails, will run through the
+ normal ``auto`` logic.
+
+ Actively supported hwdecs:
+
+ :d3d11va: requires ``--vo=gpu`` with ``--gpu-context=d3d11`` or
+ ``--gpu-context=angle`` (Windows 8+ only)
+ :d3d11va-copy: copies video back to system RAM (Windows 8+ only)
: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 (macOS 10.8 or iOS 9.0 and up)
+ :vaapi: requires ``--vo=gpu``, ``--vo=vaapi`` or ``--vo=dmabuf-wayland`` (Linux only)
+ :vaapi-copy: copies video back into system RAM (Linux with some GPUs or Windows)
+ :nvdec: requires ``--vo=gpu`` (Any platform CUDA is available)
+ :nvdec-copy: copies video back to system RAM (Any platform CUDA is available)
+ :drm: requires ``--vo=gpu`` (Linux only)
+ :drm-copy: copies video back to system RAM (Linux only)
+ :vulkan: requires ``--vo=gpu-next`` (Any platform with Vulkan Video Decoding)
+ :vulkan-copy: copies video back to system RAM (Any platform with Vulkan Video Decoding)
+
+ Other hwdecs (only use if you know you have to):
+
:dxva2: requires ``--vo=gpu`` with ``--gpu-context=d3d11``,
``--gpu-context=angle`` or ``--gpu-context=dxinterop``
(Windows only)
:dxva2-copy: copies video back to system RAM (Windows only)
- :d3d11va: requires ``--vo=gpu`` with ``--gpu-context=d3d11`` or
- ``--gpu-context=angle`` (Windows 8+ only)
- :d3d11va-copy: copies video back to system RAM (Windows 8+ only)
- :mediacodec: requires ``--vo=mediacodec_embed`` (Android only)
+ :vdpau: requires ``--vo=gpu`` with ``--gpu-context=x11``, or
+ ``--vo=vdpau`` (Linux only)
+ :vdpau-copy: copies video back into system RAM (Linux with some GPUs only)
+ :mediacodec: requires ``--vo=gpu --gpu-context=android``
+ or ``--vo=mediacodec_embed`` (Android only)
:mediacodec-copy: copies video back to system RAM (Android only)
- :mmal: requires ``--vo=gpu`` (Raspberry Pi only - default if available)
- :mmal-copy: copies video back to system RAM (Raspberry Pi only)
- :nvdec: requires ``--vo=gpu`` (Any platform CUDA is available)
- :nvdec-copy: copies video back to system RAM (Any platform CUDA is available)
:cuda: requires ``--vo=gpu`` (Any platform CUDA is available)
:cuda-copy: copies video back to system RAM (Any platform CUDA is available)
:crystalhd: copies video back to system RAM (Any platform supported by hardware)
@@ -1253,12 +1351,13 @@ Video
Because these copy the decoded video back to system RAM, they're often less
efficient than the direct modes, and may not help too much over software
- decoding.
+ decoding if you are short on CPU resources.
.. note::
Most non-copy methods only work with the OpenGL GPU backend. Currently,
- only the ``vaapi``, ``nvdec`` and ``cuda`` methods work with Vulkan.
+ only the ``vaapi``, ``nvdec``, ``cuda`` and ``vulkan`` methods work with
+ Vulkan.
The ``vaapi`` mode, if used with ``--vo=gpu``, requires Mesa 11, and most
likely works with Intel and AMD GPUs only. It also requires the opengl EGL
@@ -1282,7 +1381,12 @@ Video
In theory, hardware decoding does not reduce video quality (at least
for the codecs h264 and HEVC). However, due to restrictions in video
output APIs, as well as bugs in the actual hardware decoders, there can
- be some loss, or even blatantly incorrect results.
+ be some loss, or even blatantly incorrect results. This has largely
+ ceased to be a problem with modern hardware, but there is a lot of
+ hardware out there, so caveat emptor. Known problems are discussed
+ below, but the list cannot be considered exhaustive, as even hwdecs that
+ work well on certain hardware generations may be problematic on other
+ ones.
In some cases, RGB conversion is forced, which means the RGB conversion
is performed by the hardware decoding API, instead of the shaders
@@ -1298,10 +1402,6 @@ Video
doesn't support 10 bit or HDR encodings, so these limitations are
unlikely to be relevant.
- ``vaapi`` and ``d3d11va`` are safe. Enabling deinterlacing (or simply
- their respective post-processing filters) will possibly at least reduce
- color quality by converting the output to a 8 bit format.
-
``dxva2`` is not safe. It appears to always use BT.601 for forced RGB
conversion, but actual behavior depends on the GPU drivers. Some drivers
appear to convert to limited range RGB, which gives a faded appearance.
@@ -1309,8 +1409,10 @@ Video
affect this additionally. This can give incorrect results even with
completely ordinary video sources.
- ``rpi`` always uses the hardware overlay renderer, even with
- ``--vo=gpu``.
+ ``mediacodec`` is not safe. It forces RGB conversion (not with ``-copy``)
+ and how well it handles non-standard colorspaces is not known.
+ In the rare cases where 10-bit is supported the bit depth of the output
+ will be reduced to 8.
``cuda`` should usually be safe, but depending on how a file/stream
has been mixed, it has been reported to corrupt the timestamps causing
@@ -1323,20 +1425,9 @@ Video
conversion. It also discards the top left pixel of each frame for
some reason.
- All other methods, in particular the copy-back methods (like
- ``dxva2-copy`` etc.) should hopefully be safe, although they can still
- cause random decoding issues. At the very least, they shouldn't affect
- the colors of the image.
-
- In particular, ``auto-copy`` will only select "safe" modes
- (although potentially slower than other methods), but there's still no
- guarantee the chosen hardware decoder will actually work correctly.
-
- In general, it's very strongly advised to avoid hardware decoding
- unless **absolutely** necessary, i.e. if your CPU is insufficient to
- decode the file in questions. If you run into any weird decoding issues,
- frame glitches or discoloration, and you have ``--hwdec`` turned on,
- the first thing you should try is disabling it.
+ If you run into any weird decoding issues, frame glitches or
+ discoloration, and you have ``--hwdec`` turned on, the first thing you
+ should try is disabling it.
``--gpu-hwdec-interop=<auto|all|no|name>``
This option is for troubleshooting hwdec interop issues. Since it's a
@@ -1362,10 +1453,6 @@ Video
Runtime changes to this are ignored (the current option value is used
whenever the renderer is created).
- The old aliases ``--opengl-hwdec-interop`` and ``--hwdec-preload`` are
- barely related to this anymore, but will be somewhat compatible in some
- cases.
-
``--hwdec-extra-frames=<N>``
Number of GPU frames hardware decoding should preallocate (default: see
``--list-options`` output). If this is too low, frame allocation may fail
@@ -1407,10 +1494,13 @@ Video
For the Vulkan GPU backend, decoding must always happen on the display
device, and this option has no effect.
-``--vaapi-device=<device file>``
+``--vaapi-device=<device file|adapter name>``
Choose the DRM device for ``vaapi-copy``. This should be the path to a
DRM device file. (Default: ``/dev/dri/renderD128``)
+ On Windows this takes adapter name as an input. Will pick the default adapter
+ if unset. Alternatives are listed when the name "help" is given.
+
``--panscan=<0.0-1.0>``
Enables pan-and-scan functionality (cropping the sides of e.g. a 16:9
video to make it fit a 4:3 display without black bands). The range
@@ -1475,18 +1565,31 @@ Video
full size, even if parts of the video are not visible due to panscan or
other options).
- For example, displaying a 1280x720 video fullscreen on a 1680x1050 screen
- with ``--video-pan-x=-0.1`` would move the video 168 pixels to the left
- (making 128 pixels of the source video invisible).
+ For example, displaying a video fullscreen on a 1920x1080 screen with
+ ``--video-pan-x=-0.1`` would move the video 192 pixels to the left and
+ ``--video-pan-y=-0.1`` would move the video 108 pixels up.
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-crop=<[W[xH]][+x+y]>``, ``--video-crop=<x:y>``
+ Crop the video by starting at the x, y offset for w, h pixels. The crop is
+ applied to the source video rectangle (before anamorphic stretch) by the VO.
+ A crop rectangle that is not within the video rectangle will be ignored.
+ This works with hwdec, unlike the equivalent 'lavfi-crop'. When offset is
+ omitted, the central area will be cropped. Setting the crop to empty one
+ ``--video-crop=0x0+0+0`` overrides container crop and disables cropping.
+ Setting the crop to ``--video-crop=""`` disables manual cropping and restores
+ the container crop if it's specified.
``--video-zoom=<value>``
Adjust the video display scale factor by the given value. The parameter is
@@ -1502,7 +1605,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>``
@@ -1543,36 +1646,46 @@ Video
``--correct-pts``, ``--no-correct-pts``
``--no-correct-pts`` switches mpv to a mode where video timing is
- determined using a fixed framerate value (either using the ``--fps``
- option, or using file information). Sometimes, files with very broken
- timestamps can be played somewhat well in this mode. Note that video
- filters, subtitle rendering, seeking (including hr-seeks and backstepping),
- and audio synchronization can be completely broken in this mode.
+ determined using a fixed framerate value (either using the
+ ``--container-fps-override`` option, or using file information). Sometimes,
+ files with very broken timestamps can be played somewhat well in this mode.
+ Note that video filters, subtitle rendering, seeking (including hr-seeks and
+ backstepping), and audio synchronization can be completely broken in this mode.
-``--fps=<float>``
+``--container-fps-override=<float>``
Override video framerate. Useful if the original value is wrong or missing.
.. note::
Works in ``--no-correct-pts`` mode only.
-``--deinterlace=<yes|no>``
+``--deinterlace=<yes|no|auto>``
Enable or disable interlacing (default: no).
Interlaced video shows ugly comb-like artifacts, which are visible on
- fast movement. Enabling this typically inserts the yadif video filter in
+ fast movement. Enabling this typically inserts the bwdif video filter in
order to deinterlace the video, or lets the video output apply deinterlacing
if supported.
- This behaves exactly like the ``deinterlace`` input property (usually
- mapped to ``d``).
+ When using ``auto``, mpv will insert a deinterlacing filter if ffmpeg
+ detects that the video frame is interlaced. Be aware that there can be false
+ positives in certain cases, such as when files are encoded as interlaced
+ despite the video not actually being so. This is why ``auto`` is not the
+ default value.
+
+ Keep in mind that using this filter **will** conflict with any manually
+ inserted deinterlacing filters, and that this will make video look worse if
+ it's not actually interlaced.
- Keep in mind that this **will** conflict with manually inserted
- deinterlacing filters, unless you take care. (Since mpv 0.27.0, even the
- hardware deinterlace filters will conflict. Also since that version,
- ``--deinterlace=auto`` was removed, which used to mean that the default
- interlacing option of possibly inserted video filters was used.)
+``--deinterlace-field-parity=<tff|bff|auto>``
+ Specify the field parity/order when deinterlacing(default: auto)
+ Each frame of an interlaced video is divided into two fields, which are
+ then separately transmitted. Top field represents even lines while bottom
+ field represents odd lines. When deinterlacing the deinterlacer needs to
+ know the correct temporal order of the fields else the video will appear
+ jittery.
- Note that this will make video look worse if it's not actually interlaced.
+ ``auto`` will automatically try to detect the field order of the video,
+ ``tff`` forces top field first while ``bff`` forces bottom field first.
``--frames=<number>``
Play/convert only first ``<number>`` video frames, then quit.
@@ -1613,7 +1726,7 @@ Video
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.
+ relevant anymore, and in fact have been removed from FFmpeg in this form.
This is usually only needed with broken GPUs, where a codec is reported
as supported, but decoding causes more problems than it solves.
@@ -1640,16 +1753,29 @@ Video
the number of packets that could not be decoded. Values below an unspecified
count will not have this problem, because mpv retains the packets.
-``--vd-lavc-dr=<yes|no>``
- Enable direct rendering (default: yes). If this is set to ``yes``, the
+``--vd-lavc-film-grain=<auto|cpu|gpu>``
+ Enables film grain application on the GPU. If video decoding is done on
+ the CPU, doing film grain application on the GPU can speed up decoding.
+ This option can also help hardware decoding, as it can reduce the number
+ of frame copies done.
+
+ By default, it's set to ``auto``, so if the VO supports film grain
+ application, then it will be treated as ``gpu``. If the VO does not
+ support this, then it will be treated as ``cpu``, regardless of the setting.