diff options
Diffstat (limited to 'DOCS/man/options.rst')
| -rw-r--r-- | DOCS/man/options.rst | 1598 |
1 files changed, 995 insertions, 603 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index ed4505fb00..e40e7d2c6d 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. @@ -46,7 +46,7 @@ Track Selection ``--audio`` is an alias for ``--aid``. - ``--aid=no`` or ``--audio=no`` or ``--no-audio`` disables audio playback. + ``--aid=no`` or ``--audio=no`` disables audio playback. (The latter variant does not work with the client API.) .. note:: @@ -102,7 +102,7 @@ Track Selection ``--sub`` is an alias for ``--sid``. - ``--sid=no`` or ``--sub=no`` or ``--no-sub`` disables subtitle decoding. + ``--sid=no`` or ``--sub=no`` disables subtitle decoding. (The latter variant does not work with the client API.) ``--vid=<ID|auto|no>`` @@ -110,7 +110,7 @@ Track Selection ``--video`` is an alias for ``--vid``. - ``--vid=no`` or ``--video=no`` or ``--no-video`` disables video playback. + ``--vid=no`` or ``--video=no`` disables video playback. (The latter variant does not work with the client API.) If video is disabled, mpv will try to download the audio only if media is @@ -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 @@ -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 @@ -426,11 +447,10 @@ Playback Control will not enable looping again (the command will show ``(disabled)`` on the OSD message if both loop points are set, but ``ab-loop-count`` is 0). -``--ordered-chapters``, ``--no-ordered-chapters`` - Enabled by default. - Disable support for Matroska ordered chapters. mpv will not load or - search for video segments from other files, and will also ignore any - chapter order specified for the main file. +``--ordered-chapters=<yes|no>`` + Enable support for Matroska ordered chapters. mpv will load and + search for video segments from other files, and will also respect any + chapter order specified for the main file (default: yes). ``--ordered-chapters-files=<playlist-file>`` Loads the given file as playlist, and tries to use the files contained in @@ -465,7 +485,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 @@ -583,7 +603,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 @@ -682,7 +702,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. @@ -708,9 +728,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:: @@ -744,6 +765,9 @@ Program Behavior as well as per-user directories are ignored, and overrides through environment variables (``MPV_HOME``) are also ignored. + Note that the cache and state paths (``~~/cache``, ``~~/state``) are not + considered "configuration" and keep their auto-detection logic. + Note that the ``--no-config`` option takes precedence over this option. ``--dump-stats=<filename>`` @@ -804,10 +828,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. @@ -834,11 +854,11 @@ Program Behavior May be dangerous if playing from untrusted media. -``--ytdl``, ``--no-ytdl`` +``--ytdl=<yes|no>`` Enable the youtube-dl hook-script. It will look at the input URL, and will play the video located on the website. This works with many streaming sites, not just the one that the script is named after. This requires a recent - version of youtube-dl to be installed on the system. (Enabled by default.) + version of youtube-dl to be installed on the system (default: yes). If the script can't do anything with an URL, it will do nothing. @@ -924,6 +944,13 @@ 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: @@ -934,7 +961,7 @@ Program Behavior 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. + the suffix extension is not necessary, but only ".exe" is acceptable. .. admonition:: Why do the option names mix ``_`` and ``-``? @@ -975,6 +1002,12 @@ 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 @@ -1012,17 +1045,20 @@ Watch Later See `RESUMING PLAYBACK`_. -``--watch-later-directory=<path>`` +``--watch-later-dir=<path>`` The directory in which to store the "watch later" temporary files. - The default is a subdirectory named "watch_later" underneath the - config directory (usually ``~/.config/mpv/``). + ``--watch-later-directory`` is an alias for ``--watch-later-dir``. -``--no-resume-playback`` - Do not restore playback position from the ``watch_later`` configuration - subdirectory (usually ``~/.config/mpv/watch_later/``). + 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/``). -``--resume-playback-check-mtime`` +``--resume-playback=<yes|no>`` + Restore playback position from the ``watch_later`` configuration + subdirectory, usually ``~/.config/mpv/watch_later/`` (default: yes). + +``--resume-playback-check-mtime=<yes|no>`` 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 @@ -1032,24 +1068,27 @@ Watch Later ``--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. + 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=fullscreen`` - The fullscreen state won't be saved to watch later files. + - ``--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-clr`` - No option will be saved to watch later files except the starting + - ``--watch-later-options=start`` + No option will be saved to watch later files, except the playback position. ``--write-filename-in-watch-later-config`` @@ -1085,13 +1124,13 @@ 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 - with ``--no-audio.`` + with ``--audio=no``. ``--framedrop=<mode>`` Skip displaying some frames to maintain A/V sync on slow systems, or @@ -1146,7 +1185,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: @@ -1161,7 +1201,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 @@ -1171,10 +1211,7 @@ 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. @@ -1189,7 +1226,7 @@ Video .. note:: Use the ``Ctrl+h`` shortcut to toggle hardware decoding at runtime. It - toggles this option between ``auto`` and ``no``. + 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 @@ -1233,14 +1270,21 @@ Video - 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) + .. 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 @@ -1250,11 +1294,13 @@ Video 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 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 ony) + :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): @@ -1262,13 +1308,12 @@ Video ``--gpu-context=angle`` or ``--gpu-context=dxinterop`` (Windows only) :dxva2-copy: copies video back to system RAM (Windows only) - :vdpau: requires ``--vo=gpu`` with X11, or ``--vo=vdpau`` (Linux 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) :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) @@ -1310,7 +1355,8 @@ Video .. 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 @@ -1362,9 +1408,6 @@ 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 @@ -1409,10 +1452,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 @@ -1454,10 +1493,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 @@ -1514,7 +1556,7 @@ Video also still be scaled in one dimension if the source uses non-square pixels (e.g. anamorphic widescreen DVDs). - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. ``--video-pan-x=<value>``, ``--video-pan-y=<value>`` Moves the displayed video rectangle by the given value in the X or Y @@ -1522,11 +1564,11 @@ 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. + This option is disabled if ``--keepaspect=no`` is used. ``--video-rotate=<0-359|no>`` Rotate the video clockwise, in degrees. If ``no`` is given, the video is @@ -1538,13 +1580,23 @@ Video 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 given log 2. For example, ``--video-zoom=0`` is unscaled, ``--video-zoom=1`` is twice the size, ``--video-zoom=-2`` is one fourth of the size, and so on. - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. ``--video-scale-x=<value>``, ``--video-scale-y=<value>`` Multiply the video display size with the given value (default: 1.0). If a @@ -1552,8 +1604,8 @@ 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 ratio. This option is disabled if the - ``--no-keepaspect`` option is used. + the normal video aspect ratio. This option is disabled if + ``--keepaspect=no`` is used. ``--video-align-x=<-1-1>``, ``--video-align-y=<-1-1>`` Moves the video rectangle within the black borders, which are usually added @@ -1565,7 +1617,7 @@ Video If video and screen aspect match perfectly, these options do nothing. - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. ``--video-margin-ratio-left=<val>``, ``--video-margin-ratio-right=<val>``, ``--video-margin-ratio-top=<val>``, ``--video-margin-ratio-bottom=<val>`` Set extra video margins on each border (default: 0). Each value is a ratio @@ -1580,7 +1632,7 @@ Video The margins are applied after 90° video rotation, but before any other video transformations. - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. Subtitles still may use the margins, depending on ``--sub-use-margins`` and similar options. @@ -1591,38 +1643,48 @@ Video more generally useful. The behavior of these options may change to fit OSC requirements better, too. -``--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. +``--correct-pts=<yes|no>`` + ``--correct-pts=no`` switches mpv to a mode where video timing is + 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. + Works in ``--correct-pts=no`` 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. @@ -1663,14 +1725,21 @@ 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. + .. note:: + + On some broken drivers (e.g. NVIDIA on Linux), probing for codecs which + the GPU does not support can unnecessarily slow down video playback + initialization. To alleviate this, explicitly specify a list which + only includes the codecs supported on the setup. + .. admonition:: Example - ``mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video`` + ``mpv --hwdec=vdpau --hwdec-codecs=h264,mpeg2video`` Enable vdpau decoding for h264 and mpeg2 only. ``--vd-lavc-check-hw-profile=<yes|no>`` @@ -1701,8 +1770,8 @@ Video support this, then it will be treated as ``cpu``, regardless of the setting. Currently, only ``gpu-next`` supports film grain application. -``--vd-lavc-dr=<yes|no>`` - Enable direct rendering (default: yes). If this is set to ``yes``, the +``--vd-lavc-dr=<auto|yes|no>`` + Enable direct rendering (default: auto). If this is set to ``yes``, the video will be decoded directly to GPU video memory (or staging buffers). This can speed up video upload, and may help with large resolutions or slow hardware. This works only with the following VOs: @@ -1710,6 +1779,10 @@ Video - ``gpu``: requires at least OpenGL 4.4 or Vulkan. - ``libmpv``: The libmpv render API has optional support. + The ``auto`` option will try to guess whether DR can improve performance + on your particular hardware. Currently this enables it on AMD or NVIDIA + if using OpenGL or unconditionally if using Vulkan. + Using video filters of any kind that write to the image data (or output newly allocated frames) will silently disable the DR code path. @@ -1792,6 +1865,13 @@ Video this can break on streams not encoded by x264, or if a stream encoded by a newer x264 version contains no version info. +``--vd-apply-cropping`` + Certain video codecs support cropping, meaning that only a sub-rectangle of + the decoded frame is intended for display. This option controls how cropping + is handled by libavcodec. Cropping during decoding has certain limitations + with regards to alignment and hardware decoding. If this option is enabled, + decoder will apply the crop, else VO will handle it. Enabled by default. + ``--swapchain-depth=<N>`` Allow up to N in-flight frames. This essentially controls the frame latency. Increasing the swapchain depth can improve pipelining and prevent @@ -1805,8 +1885,22 @@ Audio ``--audio-pitch-correction=<yes|no>`` If this is enabled (default), playing with a speed different from normal - automatically inserts the ``scaletempo2`` audio filter. For details, see - audio filter section. + automatically inserts the ``scaletempo2`` audio filter. You can insert + filters besides ``scaletempo2`` and modify their params using + `Conditional auto profiles`: + + :: + + [af_insert] + profile-cond=speed ~= 1 + profile-restore=copy + af-add=scaletempo2=search-interval=50 # Insert filter and params here. + + Filters set this way replace the ``scaletempo2`` default, instead of + overlapping with it. If there are multiple audio filters inserted that can do + pitch correction, then only the last one in the filter chain is used. + For details on the specifics of each available filter, see the audio filter + section. ``--audio-device=<name>`` Use the given audio device. This consists of the audio output name, e.g. @@ -1843,10 +1937,10 @@ Audio Enable exclusive output mode. In this mode, the system is usually locked out, and only mpv will be able to output audio. - This only works for some audio outputs, such as ``wasapi`` and - ``coreaudio``. Other audio outputs silently ignore this options. They either - have no concept of exclusive mode, or the mpv side of the implementation is - missing. + This only works for some audio outputs, such as ``wasapi``, ``coreaudio`` + and ``pipewire``. Other audio outputs silently ignore this option. + They either have no concept of exclusive mode, or the mpv side of the + implementation is missing. ``--audio-fallback-to-null=<yes|no>`` If no audio device can be opened, behave as if ``--ao=null`` was given. This @@ -1863,9 +1957,9 @@ Audio ``--af=<filter1[=parameter1:parameter2:...],filter2,...>`` Specify a list of audio filters to apply to the audio stream. See `AUDIO FILTERS`_ for details and descriptions of the available filters. - The option variants ``--af-add``, ``--af-pre``, ``--af-del`` and - ``--af-clr`` exist to modify a previously specified list, but you - should not need these for typical use. + The option variants ``--af-add``, ``--af-pre``, and ``--af-clr`` exist + to modify a previously specified list, but you should not need these for + typical use. ``--audio-spdif=<codecs>`` List of codecs for which compressed audio passthrough should be used. This @@ -1880,7 +1974,7 @@ Audio In earlier mpv versions you could use ``--ad`` to force the spdif wrapper. This does not work anymore. - .. admonition:: Warning + .. warning:: There is not much reason to use this. HDMI supports uncompressed multichannel PCM, and mpv supports lossless DTS-HD decoding via @@ -1901,13 +1995,13 @@ Audio .. admonition:: Examples ``--ad=mp3float`` - Prefer the FFmpeg/Libav ``mp3float`` decoder over all other MP3 + Prefer the FFmpeg ``mp3float`` decoder over all other MP3 decoders. ``--ad=help`` List all available decoders. - .. admonition:: Warning + .. warning:: Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with this option is not possible. Use ``--audio-spdif`` instead. @@ -1917,7 +2011,19 @@ Audio amplification. Negative values can be passed for compatibility, but are treated as 0. - Since mpv 0.18.1, this always controls the internal mixer (aka "softvol"). + Since mpv 0.18.1, this always controls the internal mixer (aka software + volume). + +``--volume-max=<100.0-1000.0>`` + Set the maximum amplification level in percent (default: 130). A value of + 130 will allow you to adjust the volume up to about double the normal level. + +``--volume-gain=<db>`` + Set the volume gain in dB. This is applied on top of other volume and gain + settings. + +``--volume-gain-max=<0.0-150.0>``, ``--volume-gain-min=<-150.0-0.0>`` + Set the volume gain range in dB (default: -96 dB min, 12 dB max). ``--replaygain=<no|track|album>`` Adjust volume gain according to replaygain values stored in the file @@ -1930,8 +2036,8 @@ Audio (default: 0). ``--replaygain-clip=<yes|no>`` - Prevent clipping caused by replaygain by automatically lowering the - gain (default). Use ``--replaygain-clip=no`` to disable this. + Allow the volume gain to clip (default: no). If this option is not + enabled, mpv automatically will prevent clipping by lowering the gain. ``--replaygain-fallback=<db>`` Gain in dB to apply if the file has no replay gain tags. This option @@ -1949,18 +2055,6 @@ Audio See also: ``--volume``. -``--softvol=<no|yes|auto>`` - Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether - to use the volume controls of the audio output driver or the internal mpv - volume filter. - - The current behavior is that softvol is always enabled, i.e. as if this - option is set to ``yes``. The other behaviors are not available anymore, - although ``auto`` almost matches current behavior in most cases. - - The ``no`` behavior is still partially available through the ``ao-volume`` - and ``ao-mute`` properties. But there are no options to reset these. - ``--audio-demuxer=<[+]name>`` Use this audio demuxer type when using ``--audio-file``. Use a '+' before the name to force it; this will skip some checks. Give the demuxer name as @@ -1996,10 +2090,10 @@ Audio This is a key/value list option. See `List Options`_ for details. -``--ad-spdif-dtshd=<yes|no>``, ``--dtshd``, ``--no-dtshd`` +``--ad-spdif-dtshd=<yes|no>``, ``--dtshd=<yes|no>`` If DTS is passed through, use DTS-HD. - .. admonition:: Warning + .. warning:: This and enabling passthrough via ``--ad`` are deprecated in favor of using ``--audio-spdif=dts-hd``. @@ -2057,7 +2151,7 @@ Audio work-around for this on some AOs is to use ``--audio-exclusive=yes`` to circumvent the system mixer entirely. - .. admonition:: Warning + .. warning:: Using ``auto`` can cause issues when using audio over HDMI. The OS will typically report all channel layouts that _can_ go over HDMI, even if @@ -2101,8 +2195,8 @@ Audio ``--audio-samplerate=<Hz>`` Select the output sample rate to be used (of course sound cards have limits on this). If the sample frequency selected is different from that - of the current media, the lavrresample audio filter will be inserted into - the audio filter layer to compensate for the difference. + of the current media, the internal swresample audio filter will be inserted + into the audio filter layer to c |