summaryrefslogtreecommitdiffstats
path: root/DOCS/man
diff options
context:
space:
mode:
authorAlexander Preisinger <alexander.preisinger@gmail.com>2014-07-31 16:32:37 +0200
committerAlexander Preisinger <alexander.preisinger@gmail.com>2014-08-08 08:30:06 +0200
commitb6b8bffd2d4438e007da4cbf9b50e9305016bd73 (patch)
tree030c35ea64d3d9873c660cab5c50b4df902c0037 /DOCS/man
parentb4f72b46e5a5d804e52e1e8fdbebe7493509ba73 (diff)
downloadmpv-b6b8bffd2d4438e007da4cbf9b50e9305016bd73.tar.bz2
mpv-b6b8bffd2d4438e007da4cbf9b50e9305016bd73.tar.xz
manpage: add sections and order by usage
Split the options into the following sections: * Playback Control * Program Behaviour * Video * Audio * Subtitles * Window * Disc Devices * Equalizer * Demuxer * Input * OSD * Screenshot * Software Scaler * Terminal * TV * Cache * Network * DVB * PVR * Miscellaneous Most options are sorted by usefullness and how often they're used or how important they are. This makes finding the right options easier and adds some sort of structure.
Diffstat (limited to 'DOCS/man')
-rw-r--r--DOCS/man/options.rst3487
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
<