summaryrefslogtreecommitdiffstats
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
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.
-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
+ found, and additional images are available as video tracks.
- If ``--no-sub-ass`` is specified, all tags and style declarations are