diff options
Diffstat (limited to 'DOCS/man/options.rst')
| -rw-r--r-- | DOCS/man/options.rst | 2727 |
1 files changed, 1881 insertions, 846 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 5ffc16cf89..bf1d55a294 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,16 +46,63 @@ 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:: + + The track selection options (``--aid`` but also ``--sid`` and the + others) sometimes expose behavior that may appear strange. Also, the + 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 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 + default). + + At mpv 0.32.0 (and some releases before), if you passed a track value + for which a corresponding track didn't exist (e.g. ``--aid=2`` and there + was only 1 audio track), the ``aid`` property returned ``no``. However if + another audio track was added during playback, and you tried to set the + ``aid`` property to ``2``, nothing happened, because the ``aid`` option + still had the value ``2``, and writing the same value has no effect. + + With mpv 0.33.0, the behavior was changed. Now track selection options + are reset to ``auto`` at playback initialization, if the option had + tries to select a track that does not exist. The same is done if the + track exists, but fails to initialize. The consequence is that unlike + before mpv 0.33.0, the user's track selection parameters are clobbered + in certain situations. + + Also since mpv 0.33.0, trying to select a track by number will strictly + select this track. Before this change, trying to select a track which + did not exist would fall back to track default selection at playback + initialization. The new behavior is more consistent. + + Setting a track selection property at runtime, and then playing a new + file might reset the track selection to defaults, if the fingerprint + of the track list of the new file is different. + + Be aware of tricky combinations of all of all of the above: for example, + ``mpv --aid=2 file_with_2_audio_tracks.mkv file_with_1_audio_track.mkv`` + would first play the correct track, and the second file without audio. + If you then go back the first file, its first audio track will be played, + and the second file is played with audio. If you do the same thing again + but instead of using ``--aid=2`` you run ``set aid 2`` while the file is + playing, then changing to the second file will play its audio track. + This is because runtime selection enables the fingerprint heuristic. + + Most likely this is not the end. + ``--sid=<ID|auto|no>`` Display the subtitle stream specified by ``<ID>``. ``auto`` selects the default, ``no`` disables subtitles. ``--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>`` @@ -63,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 @@ -88,6 +135,32 @@ Track Selection Note that if ``--lavfi-complex`` is set before playback is started, the referenced tracks are always selected. +``--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 ---------------- @@ -161,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`` @@ -184,27 +257,40 @@ Playback Control The value ``no`` is a deprecated alias for ``auto``. ``--playlist=<filename>`` - Play files according to a playlist file (Supports some common formats. If + Play files according to a playlist file. Supports some common formats. If no format is detected, it will be treated as list of files, separated by - newline characters. Note that XML playlist formats are not supported.) + newline characters. You may need this option to load plaintext files as + a playlist. Note that XML playlist formats are not supported. - You can play playlists directly and without this option, however, this - option disables any security mechanisms that might be in place. You may - also need this option to load plaintext files as playlist. + This option forces ``--demuxer=playlist`` to interpret the playlist file. + Some playlist formats, notably CUE and optical disc formats, need to use + different demuxers and will not work with this option. They still can be + played directly, without using this option. + + You can play playlists directly, without this option. Before mpv version + 0.31.0, this option disabled any security mechanisms that might be in + place, but since 0.31.0 it uses the same security mechanisms as playing a + playlist file directly. If you trust the playlist file, you can disable + any security checks with ``--load-unsafe-playlists``. Because playlists + can load other playlist entries, consider applying this option only to the + playlist itself and not its entries, using something along these lines: + + ``mpv --{ --playlist=filename --load-unsafe-playlists --}`` .. warning:: - The way mpv uses playlist files via ``--playlist`` is not safe against - maliciously constructed files. Such files may trigger harmful actions. - This has been the case for all mpv and MPlayer versions, but - unfortunately this fact was not well documented earlier, and some people - have even misguidedly recommended use of ``--playlist`` with untrusted - sources. Do NOT use ``--playlist`` with random internet sources or files - you do not trust! + 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 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 + sources. Do NOT use ``--playlist`` with random internet sources or + files you do not trust if you are not sure your mpv is at least 0.31.0. - Playlist can contain entries using other protocols, such as local files, - or (most severely), special protocols like ``avdevice://``, which are - inherently unsafe. + In particular, playlists can contain entries using protocols other than + local files, such as special protocols like ``avdevice://`` (which are + inherently unsafe). ``--chapter-merge-threshold=<number>`` Threshold for merging almost consecutive ordered chapter parts in @@ -222,7 +308,7 @@ Playback Control chapter instead. A negative value means always go back to the previous chapter. -``--hr-seek=<no|absolute|yes>`` +``--hr-seek=<no|absolute|yes|default>`` Select when to use precise seeks that are not limited to keyframes. Such seeks require decoding video from the previous keyframe up to the target position and so can take some time depending on decoding performance. For @@ -233,7 +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 (default). :yes: Use precise seeks whenever possible. :always: Same as ``yes`` (for compatibility). @@ -282,9 +371,6 @@ Playback Control location. (Instead, the behavior is as if the playlist entries were provided directly to mpv command line or ``loadfile`` command.) - Note that ``--playlist`` always loads all entries, so you use that instead - if you really have the need for this functionality. - ``--access-references=<yes|no>`` Follow any references in the file being opened (default: yes). Disabling this is helpful if the file is automatically scanned (e.g. thumbnail @@ -327,6 +413,13 @@ Playback Control difference between the two option is that this option performs a seek on loop, instead of reloading the file. + .. 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. ``--ab-loop-a=<time>``, ``--ab-loop-b=<time>`` @@ -354,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 @@ -393,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 @@ -511,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 @@ -520,14 +612,16 @@ Playback Control logged errors). - The demuxer cache is essential for backward demuxing. Make sure to set - ``--demuxer-seekable-cache`` (or just use ``--cache``). The cache size - might matter. If it's too small, a queue overflow will be logged, and - backward playback cannot continue, or it performs too many low level - seeks. If it's too large, implementation tradeoffs may cause general - performance issues. Use ``--demuxer-max-bytes`` to potentially increase - the amount of packets the demuxer layer can queue for reverse demuxing - (basically it's the ``--video-reversal-buffer`` equivalent for the - demuxer layer). + ``--cache=yes``. The cache size might matter. If it's too small, a queue + overflow will be logged, and backward playback cannot continue, or it + performs too many low level seeks. If it's too large, implementation + tradeoffs may cause general performance issues. Use + ``--demuxer-max-bytes`` to potentially increase the amount of packets the + demuxer layer can queue for reverse demuxing (basically it's the + ``--video-reversal-buffer`` equivalent for the demuxer layer). + + - Setting ``--vd-queue-enable=yes`` can help a lot to make playback smooth + (once it works). - ``--demuxer-backward-playback-step`` also factors into how many seeks may be performed, and whether backward demuxing could break due to queue @@ -608,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. @@ -634,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:: @@ -670,24 +765,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 @@ -730,18 +811,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. @@ -759,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. @@ -777,19 +842,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. @@ -802,48 +854,131 @@ 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. - The ``try_ytdl_first`` script option accepts a boolean 'yes' or 'no', and if - 'yes' will try parsing the URL with youtube-dl first, instead of the default - where it's only after mpv failed to open it. This mostly depends on whether - most of your URLs need youtube-dl parsing. + This accepts a set of options, which can be passed to it with the + ``--script-opts`` option (using ``ytdl_hook-`` as prefix): + + ``try_ytdl_first=<yes|no>`` + If 'yes' will try parsing the URL with youtube-dl first, instead of the + default where it's only after mpv failed to open it. This mostly depends + on whether most of your URLs need youtube-dl parsing. - The ``exclude`` script option accepts a ``|``-separated list of URL patterns - which mpv should not use with youtube-dl. The patterns are matched after - the ``http(s)://`` part of the URL. + ``exclude=<URL1|URL2|...`` + A ``|``-separated list of URL patterns which mpv should not use with + youtube-dl. The patterns are matched after the ``http(s)://`` part of + the URL. - ``^`` matches the beginning of the URL, ``$`` matches its end, and you - should use ``%`` before any of the characters ``^$()%|,.[]*+-?`` to match - that character. + ``^`` matches the beginning of the URL, ``$`` matches its end, and you + should use ``%`` before any of the characters ``^$()%|,.[]*+-?`` to + match that character. - .. admonition:: Examples + .. admonition:: Examples + + - ``--script-opts=ytdl_hook-exclude='^youtube%.com'`` + will exclude any URL that starts with ``http://youtube.com`` or + ``https://youtube.com``. + - ``--script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$'`` + will exclude any URL that ends with ``.mkv`` or ``.mp4``. + + See more lua patterns here: https://www.lua.org/manual/5.1/manual.html#5.4.1 + + ``all_formats=<yes|no>`` + If 'yes' will attempt to add all formats found reported by youtube-dl + (default: no). Each format is added as a separate track. In addition, + they are delay-loaded, and actually opened only when a track is selected + (this should keep load times as low as without this option). + + It adds average bitrate metadata, if available, which means you can use + ``--hls-bitrate`` to decide which track to select. (HLS used to be the + only format whose alternative quality streams were exposed in a similar + way, thus the option name.) + + Tracks which represent formats that were selected by youtube-dl as + default will have the default flag set. This means mpv should generally + still select formats chosen with ``--ytdl-format`` by default. + + Although this mechanism makes it possible to switch streams at runtime, + it's not suitable for this purpose for various technical reasons. (It's + slow, which can't be really fixed.) In general, this option is not + useful, and was only added to show that it's possible. + + There are two cases that must be considered when doing quality/bandwidth + selection: + + 1. Completely separate audio and video streams (DASH-like). Each of + these streams contain either only audio or video, so you can + mix and combine audio/video bandwidths without restriction. This + intuitively matches best with the concept of selecting quality + by track (what ``all_formats`` is supposed to do). + + 2. Separate sets of muxed audio and video streams. Each version of + the media contains both an audio and video stream, and they are + interleaved. In order not to waste bandwidth, you should only + select one of these versions (if, for example, you select an + audio stream, then video will be downloaded, even if you selected + video from a different stream). + + mpv will still represent them as separate tracks, but will set + the title of each track to ``muxed-N``, where ``N`` is replaced + with the youtube-dl format ID of the originating stream. - - ``--script-opts=ytdl_hook-exclude='^youtube%.com'`` - will exclude any URL that starts with ``http://youtube.com`` or - ``https://youtube.com``. - - ``--script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$'`` - will exclude any URL that ends with ``.mkv`` or ``.mp4``. + Some sites will mix 1. and 2., but we assume that they do so for + compatibility reasons, and there is no reason to use them at all. - See more lua patterns here: https://www.lua.org/manual/5.1/manual.html#5.4.1 + ``force_all_formats=<yes|no>`` + If set to 'yes', and ``all_formats`` is also set to 'yes', this will + try to represent all youtube-dl reported formats as tracks, even if + mpv would normally use the direct URL reported by it (default: yes). - The ``use_manifests`` script option makes mpv use the master manifest URL for - formats like HLS and DASH, if available, allowing for video/audio selection - in runtime. It's disabled ("no") by default for performance reasons. + It appears this normally makes a difference if youtube-dl works on a + master HLS playlist. -``--ytdl-format=<best|worst|mp4|webm|...>`` + If this is set to 'no', this specific kind of stream is treated like + ``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 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 ``-``? + + I have no idea. + +``--ytdl-format=<ytdl|best|worst|mp4|webm|...>`` Video format/quality that is directly passed to youtube-dl. The possible values are specific to the website and the video, for a given url the available formats can be found with the command ``youtube-dl --list-formats URL``. See youtube-dl's documentation for available aliases. - (Default: youtube-dl's default, currently ``bestvideo+bestaudio/best``) + (Default: ``bestvideo+bestaudio/best``) + + The ``ytdl`` value does not pass a ``--format`` option to youtube-dl at all, + and thus does not override its default. Note that sometimes youtube-dl + returns a format that mpv cannot use, and in these cases the mpv default + may work better. ``--ytdl-raw-options=<key>=<value>[,<key>=<value>[,...]]`` Pass arbitrary options to youtube-dl. Parameter and argument should be @@ -867,16 +1002,26 @@ 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 + `Conditional auto profiles`_ for details. ``auto`` will load the script, + but immediately unload it if there are no conditional profiles. ``--player-operation-mode=<cplayer|pseudo-gui>`` For enabling "pseudo GUI mode", which means that the defaults for some @@ -884,6 +1029,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/``). + +``--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 + 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 ----- @@ -904,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 @@ -965,12 +1185,13 @@ 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: - - Use the demuxer reported FPS for frame dropping. This avoids that the - player needs to decode 1 frame in advance, lowering total latency in + - Use the demuxer reported FPS for frame dropping. This avoids the + player needing to decode 1 frame in advance, lowering total latency in effect. This also means that if the demuxer reported FPS is wrong, or the video filter chain changes FPS (e.g. deinterlacing), then it could drop too many or not enough frames. @@ -980,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 @@ -990,34 +1211,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:: @@ -1032,40 +1264,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 ma |