diff options
Diffstat (limited to 'DOCS/man/options.rst')
| -rw-r--r-- | DOCS/man/options.rst | 4150 |
1 files changed, 2956 insertions, 1194 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index a675d9259d..bf1d55a294 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -5,10 +5,13 @@ 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. .. admonition:: Examples @@ -18,10 +21,9 @@ 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. .. admonition:: Examples @@ -29,10 +31,14 @@ 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. + This is a string list option. See `List Options`_ for details. + ``--aid=<ID|auto|no>`` Select audio track. ``auto`` selects the default, ``no`` disables audio. See also ``--alang``. mpv normally prints available audio tracks on the @@ -40,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>`` @@ -57,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 @@ -82,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 ---------------- @@ -89,10 +168,12 @@ Playback Control ``--start=<relative time>`` Seek to given time position. - The general format for absolute times is ``[[hh:]mm:]ss[.ms]``. If the time - is given with a prefix of ``+`` or ``-``, the seek is relative from the start - or end of the file. (Since mpv 0.14, the start of the file is always - considered 0.) + The general format for times is ``[+|-][[hh:]mm:]ss[.ms]``. If the time is + prefixed with ``-``, the time is considered relative from the end of the + file (as signaled by the demuxer/the file). A ``+`` is usually ignored (but + see below). + + The following alternative time specifications are recognized: ``pp%`` seeks to percent position pp (0-100). @@ -100,9 +181,17 @@ Playback Control ``none`` resets any previously set option (useful for libmpv). + If ``--rebase-start-time=no`` is given, then prefixing times with ``+`` + makes the time relative to the start of the file. A timestamp without + prefix is considered an absolute time, i.e. should seek to a frame with a + timestamp as the file contains it. As a bug, but also a hidden feature, + putting 1 or more spaces before the ``+`` or ``-`` always interprets the + time as absolute, which can be used to seek to negative timestamps (useful + for debugging at most). + .. admonition:: Examples - ``--start=+56``, ``--start=+00:56`` + ``--start=+56``, ``--start=00:56`` Seeks to the start time + 56 seconds. ``--start=-56``, ``--start=-00:56`` Seeks to the end time - 56 seconds. @@ -129,6 +218,10 @@ Playback Control If both ``--end`` and ``--length`` are provided, playback will stop when it reaches either of the two endpoints. + Obscurity note: this does not work correctly if ``--rebase-start-time=no``, + and the specified time is not an "absolute" time, as defined in the + ``--start`` option description. + ``--rebase-start-time=<yes|no>`` Whether to move the file start time to ``00:00:00`` (default: yes). This is less awkward for files which start at a random timestamp, such as @@ -141,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`` @@ -150,12 +243,6 @@ Playback Control ``--shuffle`` Play files in random order. -``--chapter=<start[-end]>`` - Specify which chapter to start playing at. Optionally specify which - chapter to end playing at. - - See also: ``--start``. - ``--playlist-start=<auto|index>`` Set which file on the internal playlist to start playback with. The index is an integer, with 0 meaning the first file. The value ``auto`` means that @@ -170,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. + + 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: - 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. + ``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 @@ -208,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 @@ -219,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). @@ -263,8 +366,10 @@ Playback Control includes special protocols and anything that doesn't refer to normal files. Local files and HTTP links on the other hand are always considered safe. - Note that ``--playlist`` always loads all entries, so you use that instead - if you really have the need for this functionality. + In addition, if a playlist is loaded while this is set, the added playlist + entries are not marked as originating from network or potentially unsafe + location. (Instead, the behavior is as if the playlist entries were provided + directly to mpv command line or ``loadfile`` command.) ``--access-references=<yes|no>`` Follow any references in the file being opened (default: yes). Disabling @@ -308,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>`` @@ -315,18 +427,30 @@ Playback Control the ``a`` timestamp. Seeking past the ``b`` point doesn't loop (this is intentional). - If both options are set to ``no`` or unset, looping is disabled. - Otherwise, the start/end of playback is used if one of the options - is set to ``no`` or unset. + If ``a`` is after ``b``, the behavior is as if the points were given in + the right order, and the player will seek to ``b`` after crossing through + ``a``. This is different from old behavior, where looping was disabled (and + as a bug, looped back to ``a`` on the end of the file). + + If either options are set to ``no`` (or unset), looping is disabled. This + is different from old behavior, where an unset ``a`` implied the start of + the file, and an unset ``b`` the end of the file. The loop-points can be adjusted at runtime with the corresponding properties. See also ``ab-loop`` command. -``--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. +``--ab-loop-count=<N|inf>`` + Run A-B loops only N times, then ignore the A-B loop points (default: inf). + Every finished loop iteration will decrement this option by 1 (unless it is + set to ``inf`` or 0). ``inf`` means that looping goes on forever. If this + option is set to 0, A-B looping is ignored, and even the ``ab-loop`` command + 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=<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 @@ -361,6 +485,230 @@ Playback Control of them fails. This doesn't affect playback of audio-only or video-only files. +``--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 + the end of the file. If this is changed at during playback, a hr-seek will + be issued to change the direction. + + ``+`` and ``-`` are aliases for ``forward`` and ``backward``. + + The rest of this option description pertains to the ``backward`` mode. + + .. note:: + + Backward playback is extremely fragile. It may not always work, is much + slower than forward playback, and breaks certain other features. How + well it works depends mainly on the file being played. Generally, it + will show good results (or results at all) only if the stars align. + + mpv, as well as most media formats, were designed for forward playback + only. Backward playback is bolted on top of mpv, and tries to make a medium + effort to make backward playback work. Depending on your use-case, another + tool may work much better. + + Backward playback is not exactly a 1st class feature. Implementation + tradeoffs were made, that are bad for backward playback, but in turn do not + cause disadvantages for normal playback. Various possible optimizations are + not implemented in order to keep the complexity down. Normally, a media + player is highly pipelined (future data is prepared in separate threads, so + it is available in realtime when the next stage needs it), but backward + playback will essentially stall the pipeline at various random points. + + For example, for intra-only codecs are trivially backward playable, and + tools built around them may make efficient use of them (consider video + editors or camera viewers). mpv won't be efficient in this case, because it + uses its generic backward playback algorithm, that on top of it is not very + optimized. + + If you just want to quickly go backward through the video and just show + "keyframes", just use forward playback, and hold down the left cursor key + (which on CLI with default config sends many small relative seek commands). + + The implementation consists of mostly 3 parts: + + - Backward demuxing. This relies on the demuxer cache, so the demuxer cache + should (or must, didn't test it) be enabled, and its size will affect + performance. If the cache is too small or too large, quadratic runtime + behavior may result. + + - Backward decoding. The decoder library used (libavcodec) does not support + this. It is emulated by feeding bits of data in forward, putting the + result in a queue, returning the queue data to the VO in reverse, and + then starting over at an earlier position. This can require buffering an + extreme amount of decoded data, and also completely breaks pipelining. + + - Backward output. This is relatively simple, because the decoder returns + the frames in the needed order. However, this may cause various problems + because filters see audio and video going backward. + + Known problems: + + - It's fragile. If anything doesn't work, random non-useful behavior may + occur. In simple cases, the player will just play nonsense and artifacts. + In other cases, it may get stuck or heat the CPU. (Exceeding memory usage + significantly beyond the user-set limits would be a bug, though.) + + - Performance and resource usage isn't good. In part this is inherent to + backward playback of normal media formats, and in parts due to + implementation choices and tradeoffs. + + - This is extremely reliant on good demuxer behavior. Although backward + demuxing requires no special demuxer support, it is required that the + demuxer performs seeks reliably, fulfills some specific requirements + about packet metadata, and has deterministic behavior. + + - Starting playback exactly from the end may or may not work, depending on + seeking behavior and file duration detection. + + - Some container formats, audio, and video codecs are not supported due to + their behavior. There is no list, and the player usually does not detect + them. Certain live streams (including TV captures) may exhibit problems + in particular, as well as some lossy audio codecs. h264 intra-refresh is + known not to work due to problems with libavcodec. WAV and some other raw + audio formats tend to have problems - there are hacks for dealing with + them, which may or may not work. + + - Backward demuxing of subtitles is not supported. Subtitle display still + works for some external text subtitle formats. (These are fully read into + memory, and only backward display is needed.) Text subtitles that are + cached in the subtitle renderer also have a chance to be displayed + correctly. + + - Some features dealing with playback of broken or hard to deal with files + will not work fully (such as timestamp correction). + + - If demuxer low level seeks (i.e. seeking the actual demuxer instead of + just within the demuxer cache) are performed by backward playback, the + created seek ranges may not join, because not enough overlap is achieved. + + - Trying to use this with hardware video decoding will probably exhaust all + your GPU memory and then crash a thing or two. Or it will fail because + ``--hwdec-extra-frames`` will certainly be set too low. + + - Stream recording is broken. ``--stream-record`` may keep working if you + backward play within a cached region only. + + - Relative seeks may behave weird. Small seeks backward (towards smaller + time, i.e. ``seek -1``) may not really seek properly, and audio will + remain muted for a while. Using hr-seek is recommended, which should have + none of these problems. + + - Some things are just weird. For example, while seek commands manipulate + playback time in the expected way (provided they work correctly), the + framestep commands are transposed. Backstepping will perform very + expensive work to step forward by 1 frame. + + Tuning: + + - Remove all ``--vf``/``--af`` filters you have set. Disable hardware + 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 + with large GOP. Hardware decoding mostly ignores this, and you need to + increase ``--hwdec-extra-frames`` instead (until you get playback without + logged errors). + + - The demuxer cache is essential for backward demuxing. Make sure to set + ``--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 + overflow. If it's set too high, the backstep operation needs to search + through more packets all the time, even if the cache is large enough. + + - Setting ``--demuxer-cache-wait`` may be useful to cache the entire file + into the demuxer cache. Set ``--demuxer-max-bytes`` to a large size to + make sure it can read the entire cache; ``--demuxer-max-back-bytes`` + should also be set to a large size to prevent that tries to trim the + cache. + + - If audio artifacts are audible, even though the AO does not underrun, + increasing ``--audio-backward-overlap`` might help in some cases. + +``--video-reversal-buffer=<bytesize>``, ``--audio-reversal-buffer=<bytesize>`` + For backward decoding. Backward decoding decodes forward in steps, and then + reverses the decoder output. These options control the approximate maximum + amount of bytes that can be buffered. The main use of this is to avoid + unbounded resource usage; during normal backward playback, it's not supposed + to hit the limit, and if it does, it will drop frames and complain about it. + + Use this option if you get reversal queue overflow errors during backward + playback. Increase the size until the warning disappears. Usually, the video + buffer will overflow first, especially if it's high resolution video. + + This does not work correctly if video hardware decoding is used. The video + frame size will not include the referenced GPU and driver memory. Some + hardware decoders may also be limited by ``--hwdec-extra-frames``. + + How large the queue size needs to be depends entirely on the way the media + was encoded. Audio typically requires a very small buffer, while video can + require excessively large buffers. + + (Technically, this allows the last frame to exceed the limit. Also, this + does not account for other buffered frames, such as inside the decoder or + the video output.) + + This does not affect demuxer cache behavior at all. + + See ``--list-options`` for defaults and value range. ``<bytesize>`` options + accept suffixes such as ``KiB`` and ``MiB``. + +``--video-backward-overlap=<auto|number>``, ``--audio-backward-overlap=<auto|number>`` + Number of overlapping keyframe ranges to use for backward decoding (default: + auto) ("keyframe" to be understood as in the mpv/ffmpeg specific meaning). + Backward decoding works by forward decoding in small steps. Some codecs + cannot restart decoding from any packet (even if it's marked as seek point), + which becomes noticeable with backward decoding (in theory this is a problem + with seeking too, but ``--hr-seek-demuxer-offset`` can fix it for seeking). + In particular, MDCT based audio codecs are affected. + + The solution is to feed a previous packet to the decoder each time, and then + discard the output. This option controls how many packets to feed. The + ``auto`` choice is currently hardcoded to 0 for video, and uses 1 for lossy + audio, 0 for lossless audio. For some specific lossy audio codecs, this is + set to 2. + + ``--video-backward-overlap`` can potentially handle intra-refresh video, + depending on the exact conditions. You may have to use the + ``--vd-lavc-show-all`` option as well. + +``--video-backward-batch=<number>``, ``--audio-backward-batch=<number>`` + Number of keyframe ranges to decode at once when backward decoding (default: + 1 for video, 10 for audio). Another pointless tuning parameter nobody should + use. This should affect performance only. In theory, setting a number higher + than 1 for audio will reduce overhead due to less frequent backstep + operations and less redundant decoding work due to fewer decoded overlap + frames (see ``--audio-backward-overlap``). On the other hand, it requires + a larger reversal buffer, and could make playback less smooth due to + breaking pipelining (e.g. by decoding a lot, and then doing nothing for a + while). + + It probably never makes sense to set ``--video-backward-batch``. But in + theory, it could help with intra-only video codecs by reducing backstep + operations. + +``--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-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. + + Setting this to a high value may lead to quadratic runtime behavior. + Program Behavior ---------------- @@ -380,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:: @@ -406,6 +755,9 @@ Program Behavior can be raised via ``--msg-level`` (the option cannot lower it below the forced minimum log level). + A special case is the macOS bundle, it will create a log file at + ``~/Library/Logs/mpv.log`` by default. + ``--config-dir=<path>`` Force a different configuration directory. If this is set, the given directory is used to load configuration files, and all other configuration @@ -413,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 @@ -456,24 +794,23 @@ Program Behavior configuration subdirectory (usually ``~/.config/mpv/scripts/``). (Default: ``yes``) -``--script=<filename>`` - Load a Lua script. You can load multiple scripts by separating them with - commas (``,``). +``--script=<filename>``, ``--scripts=file1.lua:file2.lua:...`` + Load a Lua script. The second option allows you to load multiple scripts by + separating them with the path separator (``:`` on Unix, ``;`` on Windows). + + ``--scripts`` is a path list option. See `List Options`_ for details. ``--script-opts=key1=value1,key2=value2,...`` Set options for scripts. A script can query an option by key. If an option is used and what semantics the option value has depends entirely on the loaded scripts. Values not claimed by any scripts are ignored. + This is a key/value list option. See `List Options`_ for details. + ``--merge-files`` 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. - ``--profile=<profile1,profile2,...>`` Use the given profile(s), ``--profile=help`` displays a list of the defined profiles. @@ -491,12 +828,10 @@ 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. + .. admonition:: Examples - ``--reset-on-next-file=pause`` @@ -507,21 +842,9 @@ 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. + Show the description and content of a profile. Lists all profiles if no + parameter is provided. ``--use-filedir-conf`` Look for a file-specific configuration file in the same directory as the @@ -531,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: - - ``--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 |