diff options
Diffstat (limited to 'DOCS/man/options.rst')
| -rw-r--r-- | DOCS/man/options.rst | 2507 |
1 files changed, 1884 insertions, 623 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index b7ffda9a8c..35f2b8862c 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -10,6 +10,8 @@ Track Selection 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``. + This is a string list option. See `List Options`_ for details. + .. admonition:: Examples - ``mpv dvd://1 --alang=hu,en`` chooses the Hungarian language track @@ -23,6 +25,8 @@ Track Selection language codes, Matroska uses ISO 639-2 three letter language codes while OGM uses a free-form identifier. See also ``--sid``. + This is a string list option. See `List Options`_ for details. + .. admonition:: Examples - ``mpv dvd://1 --slang=hu,en`` chooses the Hungarian subtitle track on @@ -33,6 +37,8 @@ Track Selection ``--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 @@ -43,6 +49,53 @@ Track Selection ``--aid=no`` or ``--audio=no`` or ``--no-audio`` 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. @@ -82,6 +135,11 @@ 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. + Playback Control ---------------- @@ -89,10 +147,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 +160,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 +197,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 +213,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 +222,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 +236,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 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. + 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 verions 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 +287,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 @@ -220,6 +299,9 @@ Playback Control :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). + :default: Like ``absolute``, but enable hr-seeks in audio-only cases. The + exact behavior is implementation specific and may change with + new releases. :yes: Use precise seeks whenever possible. :always: Same as ``yes`` (for compatibility). @@ -263,8 +345,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 +392,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,13 +406,26 @@ 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. +``--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``, ``--no-ordered-chapters`` Enabled by default. Disable support for Matroska ordered chapters. mpv will not load or @@ -361,6 +465,230 @@ Playback Control of them fails. This doesn't affect playback of audio-only or video-only files. +``--play-dir=<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 idiotic nonsense 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-dir`` 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 ---------------- @@ -406,6 +734,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 @@ -456,15 +787,19 @@ 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. @@ -474,6 +809,13 @@ Program Behavior 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. @@ -497,6 +839,8 @@ Program Behavior 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,6 +851,29 @@ Program Behavior - ``--reset-on-next-file=all`` Try to reset all settings that were changed during playback. +``--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. + + 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. + + 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=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 + 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. @@ -521,7 +888,8 @@ Program Behavior (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 @@ -539,40 +907,116 @@ Program Behavior 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. - - 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. - - ``^`` matches the beginning of the URL, ``$`` matches its end, and you - should use ``%`` before any of the characters ``^$()%|,.[]*+-?`` to match - that character. - - .. 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 - - 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. - -``--ytdl-format=<best|worst|mp4|webm|...>`` + 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. + + ``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. + + .. 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. + + 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. + + ``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). + + It appears this normally makes a difference if youtube-dl works on a + master HLS playlist. + + 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. + + ``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 ".exe" is always appended. + + .. 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 @@ -587,6 +1031,8 @@ Program Behavior information to mpv. Take note that SOCKS proxies aren't supported and https URLs also bypass the proxy. This is a limitation in FFmpeg. + This is a key/value list option. See `List Options`_ for details. + .. admonition:: Example - ``--ytdl-raw-options=username=user,password=pass`` @@ -599,11 +1045,22 @@ Program Behavior 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``.) + +``--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 options are changed. This option should not normally be used directly, but only by mpv in |