diff options
-rw-r--r-- | DOCS/man/options.rst | 3487 |
1 files changed, 1810 insertions, 1677 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 17257844b5..eaab0c48e7 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -1,6 +1,733 @@ OPTIONS ======= +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``. + + .. admonition:: Examples + + ``mpv dvd://1 --alang=hu,en`` + Chooses the Hungarian language track on a DVD and falls back on + English if Hungarian is not available. + ``mpv --alang=jpn example.mkv`` + Plays a Matroska file in Japanese. + +``--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``. + + .. admonition:: Examples + + - ``mpv dvd://1 --slang=hu,en`` chooses the Hungarian subtitle track on + a DVD and falls back on English if Hungarian is not available. + - ``mpv --slang=jpn example.mkv`` plays a Matroska file with Japanese + subtitles. + +``--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 + terminal when starting playback of a file. + +``--sid=<ID|auto|no>`` + Display the subtitle stream specified by ``<ID>``. ``auto`` selects + the default, ``no`` disables subtitles. + + See also ``--slang``, ``--no-sub``. + +``--vid=<ID|auto|no>`` + Select video channel. ``auto`` selects the default, ``no`` disables video. + +``--edition=<ID|auto>`` + (Matroska files only) + Specify the edition (set of chapters) to use, where 0 is the first. If set + to ``auto`` (the default), mpv will choose the first edition declared as a + default, or if there is no default, the first edition defined. + + +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. + + ``pp%`` seeks to percent position pp (0-100). + + ``#c`` seeks to chapter number c. (Chapters start from 1.) + + .. admonition:: Examples + + ``--start=+56``, ``--start=+00:56`` + Seeks to the start time + 56 seconds. + ``--start=-56``, ``--start=-00:56`` + Seeks to the end time - 56 seconds. + ``--start=01:10:00`` + Seeks to 1 hour 10 min. + ``--start=50%`` + Seeks to the middle of the file. + ``--start=30 --end=40`` + Seeks to 30 seconds, plays 10 seconds, and exits. + ``--start=-3:20 --length=10`` + Seeks to 3 minutes and 20 seconds before the end of the file, plays + 10 seconds, and exits. + ``--start='#2' --end='#4'`` + Plays chapters 2 and 3, and exits. + +``--end=<time>`` + Stop at given absolute time. Use ``--length`` if the time should be relative + to ``--start``. See ``--start`` for valid option values and examples. + +``--length=<relative time>`` + Stop after a given time relative to the start time. + See ``--start`` for valid option values and examples. + +``--speed=<0.01-100>`` + Slow down or speed up playback by the factor given as parameter. + +``--loop=<N|inf|no>`` + Loops playback ``N`` times. A value of ``1`` plays it one time (default), + ``2`` two times, etc. ``inf`` means forever. ``no`` is the same as ``1`` and + disables looping. If several files are specified on command line, the + entire playlist is looped. + +``--pause`` + Start the player in paused state. + +``--shuffle`` + Play files in random order. + +``--chapter=<start[-end]>`` + Specify which chapter to start playing at. Optionally specify which + chapter to end playing at. Also see ``--start``. + +``--playlist=<filename>`` + Play files according to a playlist file (Supports some common formats.If + no format is detected, t will be treated as list of files, separated by + newline characters. Note that XML playlist formats are not supported.) + + .. warning:: + + The way mpv uses playlist files 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 main problem is that playlists can point to arbitrary network + addresses (including local addresses inside of your LAN), and thus + can't be considered secure. Playlists also can contain entries using + other protocols, such as local files, or (most severely), special + protocols like ``avdevice://``, which are inherently unsafe. + +``--chapter-merge-threshold=<number>`` + Threshold for merging almost consecutive ordered chapter parts in + milliseconds (default: 100). Some Matroska files with ordered chapters + have inaccurate chapter end timestamps, causing a small gap between the + end of one chapter and the start of the next one when they should match. + If the end of one playback part is less than the given threshold away from + the start of the next one then keep playing video normally over the + chapter change instead of doing a seek. + +``--chapter-seek-threshold=<seconds>`` + Distance in seconds from the beginning of a chapter within which a backward + chapter seek will go to the previous chapter (default: 5.0). Past this + threshold, a backward chapter seek will go to the beginning of the current + chapter instead. A negative value means always go back to the previous + chapter. + +``--hr-seek=<no|absolute|yes>`` + 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 + some video formats, precise seeks are disabled. This option selects the + default choice to use for seeks; it is possible to explicitly override that + default in the definition of key bindings and in slave mode commands. + + :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). + :yes: Use precise seeks whenever possible. + +``--hr-seek-demuxer-offset=<seconds>`` + This option exists to work around failures to do precise seeks (as in + ``--hr-seek``) caused by bugs or limitations in the demuxers for some file + formats. Some demuxers fail to seek to a keyframe before the given target + position, going to a later position instead. The value of this option is + subtracted from the time stamp given to the demuxer. Thus, if you set this + option to 1.5 and try to do a precise seek to 60 seconds, the demuxer is + told to seek to time 58.5, which hopefully reduces the chance that it + erroneously goes to some time later than 60 seconds. The downside of + setting this option is that precise seeks become slower, as video between + the earlier demuxer position and the real target may be unnecessarily + decoded. + +``--hr-seek-framedrop=<yes|no>`` + Allow the video decoder to drop frames during seek, if these frames are + before the seek target. If this is enabled, precise seeking can be faster, + but if you're using video filters which modify timestamps or add new + frames, it can lead to precise seeking skipping the target frame. This + e.g. can break frame backstepping when deinterlacing is enabled. + + Default: ``yes`` + +``--index=<mode>`` + Controls how to seek in files. Note that if the index is missing from a + file, it will be built on the fly by default, so you don't need to change + this. But it might help with some broken files. + + :default: use an index if the file has one, or build it if missing + :recreate: don't read or use the file's index + + .. note:: + + This option only works if the underlying media supports seeking + (i.e. not with stdin, pipe, etc). + +``--load-unsafe-playlists`` + Normally, something like ``mpv playlist.m3u`` won't load the playlist. This + is because the playlist code is unsafe. (This is the same in all other + variations of MPlayer.) + + See ``--playlist`` for details. + + Note: this option will allow opening playlists using the ``playlist`` + special demuxer. The ``--playlist`` uses different code, and supports more + playlist formats than the playlist demuxer. This means that for now, the + ``--playlist`` option should always be used if you intend to open playlists. + Background: the special demuxer contains newly written code, while the + ``--playlist`` option uses the old MPlayer code. Adding support for more + playlist formats to the special demuxer is work in progress, and eventually + the old code should disappear. + +``--loop-file`` + Loop a single file. The difference to ``--loop=inf`` is that this doesn't + loop the playlist, just the file itself. If the playlist contains only a + single file, the difference between the two option is that this option + performs a seek on loop, instead of reloading the file. + +``--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-files=<playlist-file>`` + Loads the given file as playlist, and tries to use the files contained in + it as reference files when opening a Matroska file that uses ordered + chapters. This overrides the normal mechanism for loading referenced + files by scanning the same directory the main file is located in. + + Useful for loading ordered chapter files that are not located on the local + filesystem, or if the referenced files are in different directories. + + Note: a playlist can be as simple as a text file containing filenames + separated by newlines. + +``--sstep=<sec>`` + Skip <sec> seconds after every frame. + + .. note:: + + Without ``--hr-seek``, skipping will snap to keyframes. + + +Program Behaviour +----------------- + +``--help`` + Show short summary of options. + +``-v`` + Increment verbosity level, one level for each ``-v`` found on the command + line. + +``--version, -V`` + Print version string and exit. + +``--no-config`` + Do not load default configuration files. This prevents loading of + ``~/.config/mpv/mpv.conf`` and ``~/.config/mpv/input.conf``, as well as + loading the same files from system wide configuration directories. Other + configuration files are blocked as well, such as resume playback files. + + .. note:: + + Files explicitly requested by command line options, like + ``--include`` or ``--use-filedir-conf``, will still be loaded. + + Also see ``--config-dir``. + +``--list-options`` + Prints all available options. + +``--list-properties`` + Print a list of the available properties. + +``--list-protocols`` + Print a list of the supported protocols. + +``--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 + directories are ignored. This means the global mpv configuration directory + 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. + +``--dump-stats=<filename>`` + Write certain statistics to the given file. The file is truncated on + opening. The file will contain raw samples, each with a timestamp. To + make this file into a readable, the script ``TOOLS/stats-conv.py`` can be + used (which currently displays it as a graph). + + This option is useful for debugging only. + +``--idle`` + Makes mpv wait idly instead of quitting when there is no file to play. + Mostly useful in slave mode, where mpv can be controlled through input + commands (see also ``--slave-broken``). + +``--include=<configuration-file>`` + Specify configuration file to be parsed after the default ones. + +``--load-scripts=<yes|no>`` + If set to ``no``, don't auto-load scripts from ``~/.mpv/lua/``. + (Default: ``yes``) + +``--lua=<filename>`` + Load a Lua script. You can load multiple scripts by separating them with + commas (``,``). + +``--lua-opts=key1=value1,key2=value2,...`` + Set options for scripts. A Lua script can query an option by key. If an + option is used and what semantics the option value has depends entirely on + the loaded Lua scripts. Values not claimed by any scripts are ignored. + +``--merge-files`` + Pretend that all files passed to mpv are concatenated into a single, big + file. This uses timeline/EDL support internally. Note that this won't work + for ordered chapter files or quvi-resolved URLs (such as youtube links). + + This option is interpreted at program start, and doesn't affect for + example files or playlists loaded with the ``loadfile`` or ``loadlist`` + commands. + +``--no-resume-playback`` + Do not restore playback position from ``~/.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. + +``--reset-on-next-file=<all|option1,option2,...>`` + Normally, mpv will try to keep all settings when playing the next file on + the playlist, even if they were changed by the user during playback. (This + behavior is the opposite of MPlayer's, which tries to reset all settings + when starting next file.) + + Default: Do not reset anything. + + This can be changed with this option. It accepts a list of options, and + mpv will reset the value of these options on playback start to the initial + 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. + + .. admonition:: Examples + + - ``--reset-on-next-file=pause`` + Reset pause mode when switching to the next file. + - ``--reset-on-next-file=fullscreen,speed`` + Reset fullscreen and playback speed settings if they were changed + during playback. + - ``--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. + +``--show-profile=<profile>`` + Show the description and content of a profile. + +``--use-filedir-conf`` + Look for a file-specific configuration file in the same directory as the + file that is being played. See `File-specific Configuration Files`_. + + .. warning:: + + May be dangerous if playing from untrusted media. + + +Video +----- + +``--vo=<driver1[:suboption1[=value]:...],driver2,...[,]>`` + Specify a priority list of video output drivers to be used. For + interactive use, one would normally specify a single one to use, but in + configuration files, specifying a list of fallbacks may make sense. See + `VIDEO OUTPUT DRIVERS`_ for details and descriptions of available drivers. + +``--vd=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>`` + Specify a priority list of video decoders to be used, according to their + family and name. See ``--ad`` for further details. Both of these options + use the same syntax and semantics; the only difference is that they + operate on different codec lists. + + .. note:: + + See ``--vd=help`` for a full list of available decoders. + +``--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. + +``--no-video`` + Do not play video. With some demuxers this may not work. In those cases + you can try ``--vo=null`` instead. + +``--untimed`` + Do not sleep when outputting video frames. Useful for benchmarks when used + with ``--no-audio.`` + +``--framedrop=<no|yes|hard>`` + Skip displaying some frames to maintain A/V sync on slow systems. Video + filters are not applied to such frames. For B-frames even decoding is + skipped completely. May produce unwatchably choppy output. With ``hard``, + decoding and output of any frame can be skipped, and will lead to an even + worse playback experience. + + .. note:: + + Practical use of this feature is questionable. Disabled by default. + +``--hwdec=<api>`` + 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. + + ``<api>`` can be one of the following: + + :no: always use software decoding (default) + :auto: see below + :vdpau: requires ``--vo=vdpau`` or ``--vo=opengl`` (Linux only) + :vaapi: requires ``--vo=opengl`` or ``--vo=vaapi`` (Linux with Intel GPUs only) + :vaapi-copy: copies video back into system RAM (Linux with Intel GPUs only) + :vda: requires ``--vo=opengl`` or ``--vo=corevideo`` (OSX only) + + ``auto`` tries to automatically enable hardware decoding using the first + available method. This still depends what VO you are using. For example, + if you are not using ``--vo=vdpau``, vdpau decoding will never be enabled. + Also note that if the first found method doesn't actually work, it will + always fall back to software decoding, instead of trying the next method. + + The ``vaapi-copy`` function allows you to use vaapi with any VO. Because + this copies the decoded video back to system RAM, it's quite inefficient. + + .. note:: + + When using this switch, hardware decoding is still only done for some + codecs. See ``--hwdec-codecs`` to enable hardware decoding for more + codecs. + +``--panscan=<0.0-1.0>`` + Enables pan-and-scan functionality (cropping the sides of e.g. a 16:9 + video to make it fit a 4:3 display without black bands). The range + controls how much of the image is cropped. May not work with all video + output drivers. + +``--video-aspect=<ratio>`` + Override video aspect ratio, in case aspect information is incorrect or + missing in the file being played. See also ``--no-video-aspect``. + + Two values have special meaning: + + :0: disable aspect ratio handling, pretend the video has square pixels + :-1: use the video stream or container aspect (default) + + But note that handling of these special values might change in the future. + + .. admonition:: Examples + + - ``--video-aspect=4:3`` or ``--video-aspect=1.3333`` + - ``--video-aspect=16:9`` or ``--video-aspect=1.7777`` + +``--no-video-aspect`` + Ignore aspect ratio information from video file and assume the video has + square pixels. See also ``--video-aspect``. + +``--video-unscaled`` + Disable scaling of the video. If the window is larger than the video, + black bars are added. Otherwise, the video is cropped. The video still + can be influenced by the other ``--video-...`` options. (If the + ``--video-zoom`` option is set to a value other than ``1``, scaling is + enabled, but the video isn't automatically scaled to the window size.) + + The video and monitor aspects aspect will be ignored. Aspect correction + would require to scale the video in the X or Y direction, but this option + disables scaling, disabling all aspect correction. + + Note that the scaler algorithm may still be used, even if the video isn't + scaled. For example, this can influence chroma conversion. + + This option is disabled if the ``--no-keepaspect`` option is used. + +``--video-pan-x=<value>``, ``--video-pan-y=<value>`` + Moves the displayed video rectangle by the given value in the X or Y + direction. The unit is in fractions of the size of the scaled video (the + full size, even if parts of the video are not visible due to panscan or + other options). + + For example, displaying a 1280x720 video fullscreen on a 1680x1050 screen + with ``--video-pan-x=-0.1`` would move the video 168 pixels to the left + (making 128 pixels of the source video invisible). + + This option is disabled if the ``--no-keepaspect`` option is used. + +``--video-rotate=<0-359|no>`` + Rotate the video clockwise, in degrees. Currently supports 90° steps only. + If ``no`` is given, the video is never rotated, even if the file has + rotation metadata. (The rotation value is added to the rotation metadata, + which means the value ``0`` would rotate the video according to the + rotation metadata.) + +``--video-zoom=<value>`` + Adjust the video display scale factor by the given value. The unit is in + fractions of the (scaled) window video size. + + For example, given a 1280x720 video shown in a 1280x720 window, + ``--video-zoom=-0.1`` would make the video by 128 pixels smaller in + X direction, and 72 pixels in Y direction. + + This option is disabled if the ``--no-keepaspect`` option is used. + +``--video-align-x=<-1-1>``, ``--video-align-y=<-1-1>`` + Moves the video rectangle within the black borders, which are usually added + to pad the video to screen if video and screen aspect ratios are different. + ``--video-align-y=-1`` would move the video to the top of the screen + (leaving a border only on the bottom), a value of ``0`` centers it + (default), and a value of ``1`` would put the video at the bottom of the + screen. + + If video and screen aspect match perfectly, these options do nothing. + + This option is disabled if the ``--no-keepaspect`` option is used. + +``--correct-pts``, ``--no-correct-pts`` + ``--no-correct-pts`` switches mpv to a mode where video timing is + determined using a fixed framerate value (either using the ``--fps`` + option, or using file information). Sometimes, files with very broken + timestamps can be played somewhat well in this mode. Note that video + filters, subtitle rendering and audio synchronization can be completely + broken in this mode. + +``--fps=<float>`` + Override video framerate. Useful if the original value is wrong or missing. + + .. note:: + + Works in ``--no-correct-pts`` mode only. + +``--deinterlace=<yes|no|auto>`` + Enable or disable interlacing (default: auto, which usually means no). + Interlaced video shows ugly comb-like artifacts, which are visible on + fast movement. Enabling this typically inserts the yadif video filter in + order to deinterlace the video, or lets the video output apply deinterlacing + if supported. + + This behaves exactly like the ``deinterlace`` input property (usually + mapped to ``Shift+D``). + + ``auto`` is a technicality. Strictly speaking, the default for this option + is deinterlacing disabled, but the ``auto`` case is needed if ``yadif`` was + added to the filter chain manually with ``--vf``. Then the core shouldn't + disable deinterlacing just because the ``--deinterlace`` was not set. + +``--field-dominance=<auto|top|bottom>`` + Set first field for interlaced content. Useful for deinterlacers that + double the framerate: ``--vf=yadif=field`` and ``--vo=vdpau:deint``. + + :auto: (default) If the decoder does not export the appropriate + information, it falls back on ``top`` (top field first). + :top: top field first + :bottom: bottom field first + +``--frames=<number>`` + Play/convert only first ``<number>`` video frames, then quit. + + ``--frames=0`` loads the file, but immediately quits before initializing + playback. (Might be useful for scripts which just want to determine some + file properties.) + + For audio-only playback, any value greater than 0 will quit playback + immediately after initialization. The value 0 works as with video. + +``--hwdec-codecs=<codec1,codec2,...|all>`` + Allow hardware decoding for a given list of codecs only. The special value + ``all`` always allows all codecs. + + You can get the list of allowed codecs with ``mpv --vd=help``. Remove the + prefix, e.g. instead of ``lavc:h264`` use ``h264``. + + By default this is set to ``h264,vc1,wmv3``. Note that the hardware + acceleration special codecs like ``h264_vdpau`` are not relevant anymore, + and in fact have been removed from Libav in this form. + + This is usually only needed with broken GPUs, where a codec is reported + as supported, but decoding causes more problems than it solves. + + .. admonition:: Example + + ``mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video`` + Enable vdpau decoding for h264 and mpeg2 only. + +``--quvi-format=<best|default|...>`` + Video format/quality that is directly passed to libquvi (default: ``best``). + This is used when opening links to streaming sites like YouTube. The + interpretation of this value is highly specific to the streaming site and + the video. + + libquvi 0.4.x: + + The only well-defined values that work on all sites are ``best`` + (best quality/highest bandwidth, default), and ``default`` (lowest + quality). + + The quvi command line tool can be used to find out which formats are + supported for a given URL: ``quvi --query-formats URL``. + + libquvi 0.9.x: + + The following explanations are relevant: + `<http://quvi.sourceforge.net/r/api/0.9/glossary_termino.html#m_stream_id>`_ + + The ``quvi-format`` property can be used at runtime to cycle through the + list of formats. Unfortunately, this is slow. On libquvi 0.4.x, this + functionality is limited to switching between ``best`` and ``default`` if + the ``cycle`` input command is used. + +``--vd-lavc-check-hw-profile=<yes|no>`` + Check hardware decoder profile (default: yes). If ``no`` is set, the + highest profile of the hardware decoder is unconditionally selected, and + decoding is forced even if the profile of the video is higher than that. + The result is most likely broken decoding, but may also help if the + detected or reported profiles are somehow incorrect. + +``--vd-lavc-bitexact`` + Only use bit-exact algorithms in all decoding steps (for codec testing). + +``--vd-lavc-fast`` (MPEG-2, MPEG-4, and H.264 only) + Enable optimizations which do not comply with the format specification and + potentially cause problems, like simpler dequantization, simpler motion + compensation, assuming use of the default quantization matrix, assuming YUV + 4:2:0 and skipping a few checks to detect damaged bitstreams. + +``--vd-lavc-o=<key>=<value>[,<key>=<value>[,...]]`` + Pass AVOptions to libavcodec decoder. Note, a patch to make the ``o=`` + unneeded and pass all unknown options through the AVOption system is + welcome. A full list of AVOptions can be found in the FFmpeg manual. + + Some options which used to be direct options can be set with this + mechanism, like ``bug``, ``gray``, ``idct``, ``ec``, ``vismv``, + ``skip_top`` (was ``st``), ``skip_bottom`` (was ``sb``), ``debug``. + + .. admonition:: Example + + ``--vd--lavc-o=debug=pict`` + +``--vd-lavc-show-all=<yes|no>`` + Show even broken/corrupt frames (default: no). If this option is set to + no, libavcodec won't output frames that were either decoded before an + initial keyframe was decoded, or frames that are recognized as corrupted. + +``--vd-lavc-skiploopfilter=<skipvalue> (H.264 only)`` + Skips the loop filter (AKA deblocking) during H.264 decoding. Since + the filtered frame is supposed to be used as reference for decoding + dependent frames, this has a worse effect on quality than not doing + deblocking on e.g. MPEG-2 video. But at least for high bitrate HDTV, + this provides a big speedup with little visible quality loss. + + ``<skipvalue>`` can be one of the following: + + :none: Never skip. + :default: Skip useless processing steps (e.g. 0 size packets in AVI). + :nonref: Skip frames that are not referenced (i.e. not used for + decoding other frames, the error cannot "build up"). + :bidir: Skip B-Frames. + :nonkey: Skip all frames except keyframes. + :all: Skip all frames. + +``--vd-lavc-skipidct=<skipvalue> (MPEG-1/2 only)`` + Skips the IDCT step. This degrades quality a lot in almost all cases + (see skiploopfilter for available skip values). + +``--vd-lavc-skipframe=<skipvalue>`` + Skips decoding of frames completely. Big speedup, but jerky motion and + sometimes bad artifacts (see skiploopfilter for available skip values). + +``--vd-lavc-threads=<0-16>`` + Number of threads to use for decoding. Whether threading is actually + supported depends on codec. 0 means autodetect number of cores on the + machine and use that, up to the maximum of 16 (default: 0). + + + +Audio +----- + +``--ao=<driver1[:suboption1[=value]:...],driver2,...[,]>`` + Specify a priority list of audio output drivers to be used. For + interactive use one would normally specify a single one to use, but in + configuration files specifying a list of fallbacks may make sense. See + `AUDIO OUTPUT DRIVERS`_ for details and descriptions of available drivers. + +``--af=<filter1[=parameter1:parameter2:...],filter2,...>`` + Specify a list of audio filters to apply to the audio stream. See + `AUDIO FILTERS`_ for details and descriptions of the available filters. + The option variants ``--af-add``, ``--af-pre``, ``--af-del`` and + ``--af-clr`` exist to modify a previously specified list, but you + should not need these for typical use. + ``--ad=<[+|-]family1:(*|decoder1),[+|-]family2:(*|decoder2),...[-]>`` Specify a priority list of audio decoders to be used, according to their family and decoder name. Entries like ``family:*`` prioritize all decoders @@ -28,6 +755,42 @@ OPTIONS ``--ad=help`` List all available decoders. +``--volume=<-1-100>`` + Set the startup volume. A value of -1 (the default) will not change the + volume. See also ``--softvol``. + +``--audio-delay=<sec>`` + Audio delay in seconds (positive or negative float value). Positive values + delay the audio, and negative values delay the video. + +``--no-audio`` + Do not play sound. With some demuxers this may not work. In those cases + you can try ``--ao=null`` instead. + +``--mute=<auto|yes|no>`` + Set startup audio mute status. ``auto`` (default) will not change the mute + status. Also see ``--volume``. + +``--softvol=<mode>`` + Control whether to use the volume controls of the audio output driver or + the internal mpv volume filter. + + :no: prefer audio driver controls, use the volume filter only if + absolutely needed + :yes: always use the volume filter + :auto: prefer the volume filter if the audio driver uses the system mixer + (default) + + The intention of ``auto`` is to avoid changing system mixer settings from + within mpv with default settings. mpv is a video player, not a mixer panel. + On the other hand, mixer controls are enabled for sound servers like + PulseAudio, which provide per-application volume. + +``--audio-demuxer=<[+]name>`` + Use this audio demuxer type when using ``--audio-file``. Use a '+' before + the name to force it; this will skip some checks. Give the demuxer name as + printed by ``--audio-demuxer=help``. + ``--ad-lavc-ac3drc=<level>`` Select the Dynamic Range Compression level for AC-3 audio streams. ``<level>`` is a float value ranging from 0 to 1, where 0 means no @@ -66,54 +829,217 @@ OPTIONS ``--dtshd`` and ``--no-dtshd`` are deprecated aliases. -``--af=<filter1[=parameter1:parameter2:...],filter2,...>`` - Specify a list of audio filters to apply to the audio stream. See - `AUDIO FILTERS`_ for details and descriptions of the available filters. - The option variants ``--af-add``, ``--af-pre``, ``--af-del`` and - ``--af-clr`` exist to modify a previously specified list, but you - should not need these for typical use. +``--audio-channels=<number|layout>`` + Request a channel layout for audio output (default: stereo). This will ask + the AO to open a device with the given channel layout. It's up to the AO + to accept this layout, or to pick a fallback or to error out if the + requested layout is not supported. -``--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 - terminal when starting playback of a file. + The ``--audio-channels`` option either takes a channel number or an explicit + channel layout. Channel numbers refer to default layouts, e.g. 2 channels + refer to stereo, 6 refers to 5.1. -``--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``. + See ``--audio-channels=help`` output for defined default layouts. This also + lists speaker names, which can be used to express arbitrary channel + layouts (e.g. ``fl-fr-lfe`` is 2.1). - .. admonition:: Examples + You can use ``--audio-channels=empty`` to disable this. In this case, the AO + use the channel layout as the audio filter chain indicates. - ``mpv dvd://1 --alang=hu,en`` - Chooses the Hungarian language track on a DVD and falls back on - English if Hungarian is not available. - ``mpv --alang=jpn example.mkv`` - Plays a Matroska file in Japanese. + This will also request the channel layout from the decoder. If the decoder + does not support the layout, it will fall back to its native channel layout. + (You can use ``--ad-lavc-downmix=no`` to make the decoder always output + its native layout.) Note that only some decoders support remixing audio. + Some that do include AC-3, AAC or DTS audio. -``--ao=<driver1[:suboption1[=value]:...],driver2,...[,]>`` - Specify a priority list of audio output drivers to be used. For - interactive use one would normally specify a single one to use, but in - configuration files specifying a list of fallbacks may make sense. See - `AUDIO OUTPUT DRIVERS`_ for details and descriptions of available drivers. + If the channel layout of the media file (i.e. the decoder) and the AO's + channel layout don't match, mpv will attempt to insert a conversion filter. -``--sub-ass``, ``--no-sub-ass`` - Render ASS subtitles natively (enabled by default). +``--audio-display=<no|attachment>`` + Setting this option to ``attachment`` (default) will display image + attachments when playing audio files. It will display the first image + found, and additional images are available as video tracks. - If ``--no-sub-ass`` is specified, all tags and style declarations are - stripped and ignored on display. The subtitle renderer uses the font style - as specified by the ``--sub-text-`` options instead. + Setting this option to ``no`` disables display of video entirely when + playing audio files. + + This option has no influence on files with normal video tracks. + +``--audio-file=<filename>`` + Play audio from an external file while viewing a video. Each use of this + option will add a new audio track. The details are similar to how + ``--sub-file`` works. + +``--audio-format=<format>`` + Select the sample format used for output from the audio filter layer to + the sound card. The values that ``<format>`` can adopt are listed below in + the description of the ``format`` audio filter. + +``--audio-samplerate=<Hz>`` + Select the output sample rate to be used (of course sound cards have + limits on this). If the sample frequency selected is different from that + of the current media, the lavrresample audio filter will be inserted into + the audio filter layer to compensate for the difference. + +``--gapless-audio=<no|yes|weak`` + Try to play consecutive audio files with no silence or disruption at the + point of file change. Default: ``weak``. + + :no: Disable gapless audio. + :yes: The |