[crux-commits] ports/contrib (3.5): mpv: make docutils optional

commit 3d01a034860d60d58bcf1d7a5489701dca8276b3 Author: Danny Rawlins <monster.romster@gmail.com> Date: Sun Dec 1 12:39:02 2019 +1100 mpv: make docutils optional diff --git a/mpv/.signature b/mpv/.signature index a97261766..2030a79fb 100644 --- a/mpv/.signature +++ b/mpv/.signature @@ -1,6 +1,7 @@ untrusted comment: verify with /etc/ports/contrib.pub -RWSagIOpLGJF3+jD1Ec1EpaiWa99Tuoo47gNJMKFvEtO/QAXIzOWdpCKw8Zqlbh/hwryhH7OPvtZ92/6Y3ZGJQEj2pIqqp9OJwQ= -SHA256 (Pkgfile) = 3cb8c54bfa8e8a52cf694291e994b6f3e134dbaf31674a0bc1443059e502d1fc +RWSagIOpLGJF32sQuXRp4wgz/vwI5E/PTpukSBmJHMluyhl2x3Ec6NxHL3EfR8pKvTOLuRgQT62N+qupvphTYxetMJ8u3Yez5Ac= +SHA256 (Pkgfile) = 5af956bbf47cee573ec7f8d7fd4abb62399e73dd9ddc920263edfb95c3c2e017 SHA256 (.footprint) = eb826b2c48e4c78958a593e46f99dbeb1f0dd3faf963b8c16a5209ef4bc0939c SHA256 (mpv-v0.30.0.tar.gz) = 33a1bcb7e74ff17f070e754c15c52228cf44f2cefbfd8f34886ae81df214ca35 SHA256 (waf-2.0.9) = 2a8e0816f023995e557f79ea8940d322bec18f286917c8f9a6fa2dc3875dfa48 +SHA256 (mpv.1) = e2c8c722447909b9ab08725a0dc479330caaab51f5058912bebbef9688ef241d diff --git a/mpv/Pkgfile b/mpv/Pkgfile index 5ba95d596..562e275c2 100644 --- a/mpv/Pkgfile +++ b/mpv/Pkgfile @@ -1,14 +1,15 @@ # Description: General Purpose video player based on MPlayer and mplayer2 # URL: https://mpv.io/ # Maintainer: Danny Rawlins, crux at romster dot me -# Depends on: docutils ffmpeg libass libplacebo util-linux xorg-libxscrnsaver -# Optional: youtube-dl libquvi libdvdnav libbluray libcdio-paranoia libvdpau rubberband +# Depends on: ffmpeg libass libplacebo util-linux xorg-libxscrnsaver +# Optional: docutils youtube-dl libquvi libdvdnav libbluray libcdio-paranoia libvdpau rubberband name=mpv version=0.30.0 release=2 source=(https://github.com/$name-player/$name/archive/v$version/$name-v$version.tar.... - https://waf.io/waf-2.0.9) + https://waf.io/waf-2.0.9 + mpv.1) build() { cd $name-$version @@ -27,4 +28,6 @@ build() { ./waf build ./waf install --destdir=$PKG rm -r $PKG/usr/share/doc + + [ -e '/usr/bin/rst2man.py' ] || install -D -m 0644 -t $PKG/usr/share/man/man1 $SRC/mpv.1 } diff --git a/mpv/mpv.1 b/mpv/mpv.1 new file mode 100644 index 000000000..d41da81fe --- /dev/null +++ b/mpv/mpv.1 @@ -0,0 +1,16444 @@ +.\" Man page generated from reStructuredText. +. +.TH MPV 1 "" "" "multimedia" +.SH NAME +mpv \- a media player +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.nf +\fBmpv\fP [options] [file|URL|PLAYLIST|\-] +\fBmpv\fP [options] files +.fi +.sp +.SH DESCRIPTION +.sp +\fBmpv\fP is a media player based on MPlayer and mplayer2. It supports a wide variety of video +file formats, audio and video codecs, and subtitle types. Special input URL +types are available to read input from a variety of sources other than disk +files. Depending on platform, a variety of different video and audio output +methods are supported. +.sp +Usage examples to get you started quickly can be found at the end of this man +page. +.SH INTERACTIVE CONTROL +.sp +mpv has a fully configurable, command\-driven control layer which allows you +to control mpv using keyboard, mouse, or remote control (there is no +LIRC support \- configure remotes as input devices instead). +.sp +See the \fB\-\-input\-\fP options for ways to customize it. +.sp +The following listings are not necessarily complete. See \fBetc/input.conf\fP for +a list of default bindings. User \fBinput.conf\fP files and Lua scripts can +define additional key bindings. +.SS Keyboard Control +.INDENT 0.0 +.TP +.B LEFT and RIGHT +Seek backward/forward 5 seconds. Shift+arrow does a 1 second exact seek +(see \fB\-\-hr\-seek\fP). +.TP +.B UP and DOWN +Seek forward/backward 1 minute. Shift+arrow does a 5 second exact seek (see +\fB\-\-hr\-seek\fP). +.TP +.B Ctrl+LEFT and Ctrl+RIGHT +Seek to the previous/next subtitle. Subject to some restrictions and +might not always work; see \fBsub\-seek\fP command. +.TP +.B Ctrl+Shift+Left and Ctrl+Shift+Right +Adjust subtitle delay so that the next or previous subtitle is displayed +now. This is especially useful to sync subtitles to audio. +.TP +.B [ and ] +Decrease/increase current playback speed by 10%. +.TP +.B { and } +Halve/double current playback speed. +.TP +.B BACKSPACE +Reset playback speed to normal. +.TP +.B Shift+BACKSPACE +Undo the last seek. This works only if the playlist entry was not changed. +Hitting it a second time will go back to the original position. +See \fBrevert\-seek\fP command for details. +.TP +.B Shift+Ctrl+BACKSPACE +Mark the current position. This will then be used by \fBShift+BACKSPACE\fP +as revert position (once you seek back, the marker will be reset). You can +use this to seek around in the file and then return to the exact position +where you left off. +.TP +.B < and > +Go backward/forward in the playlist. +.TP +.B ENTER +Go forward in the playlist. +.TP +.B p / SPACE +Pause (pressing again unpauses). +.TP +.B \&. +Step forward. Pressing once will pause, every consecutive press will +play one frame and then go into pause mode again. +.UNINDENT +.INDENT 0.0 +.TP +.B , +Step backward. Pressing once will pause, every consecutive press will +play one frame in reverse and then go into pause mode again. +.TP +.B q +Stop playing and quit. +.TP +.B Q +Like \fBq\fP, but store the current playback position. Playing the same file +later will resume at the old playback position if possible. +.TP +.B / and * +Decrease/increase volume. +.TP +.B 9 and 0 +Decrease/increase volume. +.TP +.B m +Mute sound. +.TP +.B _ +Cycle through the available video tracks. +.TP +.B # +Cycle through the available audio tracks. +.TP +.B f +Toggle fullscreen (see also \fB\-\-fs\fP). +.TP +.B ESC +Exit fullscreen mode. +.TP +.B T +Toggle stay\-on\-top (see also \fB\-\-ontop\fP). +.TP +.B w and W +Decrease/increase pan\-and\-scan range. The \fBe\fP key does the same as +\fBW\fP currently, but use is discouraged. +.TP +.B o (also P) +Show progression bar, elapsed time and total duration on the OSD. +.TP +.B O +Toggle OSD states between normal and playback time/duration. +.TP +.B v +Toggle subtitle visibility. +.TP +.B j and J +Cycle through the available subtitles. +.TP +.B z and Z +Adjust subtitle delay by +/\- 0.1 seconds. The \fBx\fP key does the same as +\fBZ\fP currently, but use is discouraged. +.TP +.B l +Set/clear A\-B loop points. See \fBab\-loop\fP command for details. +.TP +.B L +Toggle infinite looping. +.TP +.B Ctrl + and Ctrl \- +Adjust audio delay (A/V sync) by +/\- 0.1 seconds. +.TP +.B u +Switch between applying no style overrides to SSA/ASS subtitles, and +overriding them almost completely with the normal subtitle style. See +\fB\-\-sub\-ass\-override\fP for more info. +.TP +.B V +Toggle subtitle VSFilter aspect compatibility mode. See +\fB\-\-sub\-ass\-vsfilter\-aspect\-compat\fP for more info. +.TP +.B r and R +Move subtitles up/down. The \fBt\fP key does the same as \fBR\fP currently, but +use is discouraged. +.TP +.B s +Take a screenshot. +.TP +.B S +Take a screenshot, without subtitles. (Whether this works depends on VO +driver support.) +.TP +.B Ctrl s +Take a screenshot, as the window shows it (with subtitles, OSD, and scaled +video). +.TP +.B PGUP and PGDWN +Seek to the beginning of the previous/next chapter. In most cases, +"previous" will actually go to the beginning of the current chapter; see +\fB\-\-chapter\-seek\-threshold\fP\&. +.TP +.B Shift+PGUP and Shift+PGDWN +Seek backward or forward by 10 minutes. (This used to be mapped to +PGUP/PGDWN without Shift.) +.TP +.B d +Activate/deactivate deinterlacer. +.TP +.B A +Cycle aspect ratio override. +.TP +.B Ctrl h +Toggle hardware video decoding on/off. +.TP +.B Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN +Move the video rectangle (panning). +.TP +.B Alt + and Alt \- +Combining \fBAlt\fP with the \fB+\fP or \fB\-\fP keys changes video zoom. +.TP +.B Alt+BACKSPACE +Reset the pan/zoom settings. +.TP +.B F8 +Show the playlist and the current position in it (useful only if a UI window +is used, broken on the terminal). +.TP +.B F9 +Show the list of audio and subtitle streams (useful only if a UI window is +used, broken on the terminal). +.TP +.B i and I +Show/toggle an overlay displaying statistics about the currently playing +file such as codec, framerate, number of dropped frames and so on. See +\fI\%STATS\fP for more information. +.UNINDENT +.sp +(The following keys are valid only when using a video output that supports the +corresponding adjustment.) +.INDENT 0.0 +.TP +.B 1 and 2 +Adjust contrast. +.TP +.B 3 and 4 +Adjust brightness. +.TP +.B 5 and 6 +Adjust gamma. +.TP +.B 7 and 8 +Adjust saturation. +.TP +.B Alt+0 (and command+0 on OSX) +Resize video window to half its original size. +.TP +.B Alt+1 (and command+1 on OSX) +Resize video window to its original size. +.TP +.B Alt+2 (and command+2 on OSX) +Resize video window to double its original size. +.TP +.B command + f (OSX only) +Toggle fullscreen (see also \fB\-\-fs\fP). +.UNINDENT +.sp +(The following keys are valid if you have a keyboard with multimedia keys.) +.INDENT 0.0 +.TP +.B PAUSE +Pause. +.TP +.B STOP +Stop playing and quit. +.TP +.B PREVIOUS and NEXT +Seek backward/forward 1 minute. +.UNINDENT +.sp +If you miss some older key bindings, look at \fBetc/restore\-old\-bindings.conf\fP +in the mpv git repository. +.SS Mouse Control +.INDENT 0.0 +.TP +.B button 3 and button 4 +Seek backward/forward 1 minute. +.TP +.B button 5 and button 6 +Decrease/increase volume. +.UNINDENT +.SH USAGE +.sp +Command line arguments starting with \fB\-\fP are interpreted as options, +everything else as filenames or URLs. All options except \fIflag\fP options (or +choice options which include \fByes\fP) require a parameter in the form +\fB\-\-option=value\fP\&. +.sp +One exception is the lone \fB\-\fP (without anything else), which means media data +will be read from stdin. Also, \fB\-\-\fP (without anything else) will make the +player interpret all following arguments as filenames, even if they start with +\fB\-\fP\&. (To play a file named \fB\-\fP, you need to use \fB\&./\-\fP\&.) +.sp +Every \fIflag\fP option has a \fIno\-flag\fP counterpart, e.g. the opposite of the +\fB\-\-fs\fP option is \fB\-\-no\-fs\fP\&. \fB\-\-fs=yes\fP is same as \fB\-\-fs\fP, \fB\-\-fs=no\fP +is the same as \fB\-\-no\-fs\fP\&. +.sp +If an option is marked as \fI(XXX only)\fP, it will only work in combination with +the \fIXXX\fP option or if \fIXXX\fP is compiled in. +.SS Legacy option syntax +.sp +The \fB\-\-option=value\fP syntax is not strictly enforced, and the alternative +legacy syntax \fB\-option value\fP and \fB\-\-option value\fP will also work. This is +mostly for compatibility with MPlayer. Using these should be avoided. Their +semantics can change any time in the future. +.sp +For example, the alternative syntax will consider an argument following the +option a filename. \fBmpv \-fs no\fP will attempt to play a file named \fBno\fP, +because \fB\-\-fs\fP is a flag option that requires no parameter. If an option +changes and its parameter becomes optional, then a command line using the +alternative syntax will break. +.sp +Currently, the parser makes no difference whether an option starts with \fB\-\-\fP +or a single \fB\-\fP\&. This might also change in the future, and \fB\-\-option value\fP +might always interpret \fBvalue\fP as filename in order to reduce ambiguities. +.SS Escaping spaces and other special characters +.sp +Keep in mind that the shell will partially parse and mangle the arguments you +pass to mpv. For example, you might need to quote or escape options and +filenames: +.INDENT 0.0 +.INDENT 3.5 +\fBmpv "filename with spaces.mkv" \-\-title="window title"\fP +.UNINDENT +.UNINDENT +.sp +It gets more complicated if the suboption parser is involved. The suboption +parser puts several options into a single string, and passes them to a +component at once, instead of using multiple options on the level of the +command line. +.sp +The suboption parser can quote strings with \fB"\fP and \fB[...]\fP\&. +Additionally, there is a special form of quoting with \fB%n%\fP described below. +.sp +For example, assume the hypothetical \fBfoo\fP filter can take multiple options: +.INDENT 0.0 +.INDENT 3.5 +\fBmpv test.mkv \-\-vf=foo:option1=value1:option2:option3=value3,bar\fP +.UNINDENT +.UNINDENT +.sp +This passes \fBoption1\fP and \fBoption3\fP to the \fBfoo\fP filter, with \fBoption2\fP +as flag (implicitly \fBoption2=yes\fP), and adds a \fBbar\fP filter after that. If +an option contains spaces or characters like \fB,\fP or \fB:\fP, you need to quote +them: +.INDENT 0.0 +.INDENT 3.5 +\fBmpv \(aq\-\-vf=foo:option1="option value with spaces",bar\(aq\fP +.UNINDENT +.UNINDENT +.sp +Shells may actually strip some quotes from the string passed to the commandline, +so the example quotes the string twice, ensuring that mpv receives the \fB"\fP +quotes. +.sp +The \fB[...]\fP form of quotes wraps everything between \fB[\fP and \fB]\fP\&. It\(aqs +useful with shells that don\(aqt interpret these characters in the middle of +an argument (like bash). These quotes are balanced (since mpv 0.9.0): the \fB[\fP +and \fB]\fP nest, and the quote terminates on the last \fB]\fP that has no matching +\fB[\fP within the string. (For example, \fB[a[b]c]\fP results in \fBa[b]c\fP\&.) +.sp +The fixed\-length quoting syntax is intended for use with external +scripts and programs. +.sp +It is started with \fB%\fP and has the following format: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +%n%string_of_length_n +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.IP "Examples" +.sp +\fBmpv \(aq\-\-vf=foo:option1=%11%quoted text\(aq test.avi\fP +.sp +Or in a script: +.sp +\fBmpv \-\-vf=foo:option1=%\(gaexpr length "$NAME"\(ga%"$NAME" test.avi\fP +.UNINDENT +.UNINDENT +.sp +Suboptions passed to the client API are also subject to escaping. Using +\fBmpv_set_option_string()\fP is exactly like passing \fB\-\-name=data\fP to the +command line (but without shell processing of the string). Some options +support passing values in a more structured way instead of flat strings, and +can avoid the suboption parsing mess. For example, \fB\-\-vf\fP supports +\fBMPV_FORMAT_NODE\fP, which lets you pass suboptions as a nested data structure +of maps and arrays. +.SS Paths +.sp +Some care must be taken when passing arbitrary paths and filenames to mpv. For +example, paths starting with \fB\-\fP will be interpreted as options. Likewise, +if a path contains the sequence \fB://\fP, the string before that might be +interpreted as protocol prefix, even though \fB://\fP can be part of a legal +UNIX path. To avoid problems with arbitrary paths, you should be sure that +absolute paths passed to mpv start with \fB/\fP, and prefix relative paths with +\fB\&./\fP\&. +.sp +Using the \fBfile://\fP pseudo\-protocol is discouraged, because it involves +strange URL unescaping rules. +.sp +The name \fB\-\fP itself is interpreted as stdin, and will cause mpv to disable +console controls. (Which makes it suitable for playing data piped to stdin.) +.sp +The special argument \fB\-\-\fP can be used to stop mpv from interpreting the +following arguments as options. +.sp +When using the client API, you should strictly avoid using \fBmpv_command_string\fP +for invoking the \fBloadfile\fP command, and instead prefer e.g. \fBmpv_command\fP +to avoid the need for filename escaping. +.sp +For paths passed to suboptions, the situation is further complicated by the +need to escape special characters. To work this around, the path can be +additionally wrapped in the fixed\-length syntax, e.g. \fB%n%string_of_length_n\fP +(see above). +.sp +Some mpv options interpret paths starting with \fB~\fP\&. Currently, the prefix +\fB~~/\fP expands to the mpv configuration directory (usually \fB~/.config/mpv/\fP). +\fB~/\fP expands to the user\(aqs home directory. (The trailing \fB/\fP is always +required.) There are the following paths as well: +.TS +center; +|l|l|. +_ +T{ +Name +T} T{ +Meaning +T} +_ +T{ +\fB~~home/\fP +T} T{ +same as \fB~~/\fP +T} +_ +T{ +\fB~~global/\fP +T} T{ +the global config path, if available (not on win32) +T} +_ +T{ +\fB~~osxbundle/\fP +T} T{ +the OSX bundle resource path (OSX only) +T} +_ +T{ +\fB~~desktop/\fP +T} T{ +the path to the desktop (win32, OSX) +T} +_ +.TE +.SS Per\-File Options +.sp +When playing multiple files, any option given on the command line usually +affects all files. Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-a file1.mkv \-\-b file2.mkv \-\-c +.ft P +.fi +.UNINDENT +.UNINDENT +.TS +center; +|l|l|. +_ +T{ +File +T} T{ +Active options +T} +_ +T{ +file1.mkv +T} T{ +\fB\-\-a \-\-b \-\-c\fP +T} +_ +T{ +file2.mkv +T} T{ +\fB\-\-a \-\-b \-\-c\fP +T} +_ +.TE +.sp +(This is different from MPlayer and mplayer2.) +.sp +Also, if any option is changed at runtime (via input commands), they are not +reset when a new file is played. +.sp +Sometimes, it is useful to change options per\-file. This can be achieved by +adding the special per\-file markers \fB\-\-{\fP and \fB\-\-}\fP\&. (Note that you must +escape these on some shells.) Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-a file1.mkv \-\-b \-\-\e{ \-\-c file2.mkv \-\-d file3.mkv \-\-e \-\-\e} file4.mkv \-\-f +.ft P +.fi +.UNINDENT +.UNINDENT +.TS +center; +|l|l|. +_ +T{ +File +T} T{ +Active options +T} +_ +T{ +file1.mkv +T} T{ +\fB\-\-a \-\-b \-\-f\fP +T} +_ +T{ +file2.mkv +T} T{ +\fB\-\-a \-\-b \-\-f \-\-c \-\-d \-\-e\fP +T} +_ +T{ +file3.mkv +T} T{ +\fB\-\-a \-\-b \-\-f \-\-c \-\-d \-\-e\fP +T} +_ +T{ +file4.mkv +T} T{ +\fB\-\-a \-\-b \-\-f\fP +T} +_ +.TE +.sp +Additionally, any file\-local option changed at runtime is reset when the current +file stops playing. If option \fB\-\-c\fP is changed during playback of +\fBfile2.mkv\fP, it is reset when advancing to \fBfile3.mkv\fP\&. This only affects +file\-local options. The option \fB\-\-a\fP is never reset here. +.SS List Options +.sp +Some options which store lists of option values can have action suffixes. For +example, you can set a \fB,\fP\-separated list of filters with \fB\-\-vf\fP, but the +option also allows you to append filters with \fB\-\-vf\-append\fP\&. +.sp +Options for filenames do not use \fB,\fP as separator, but \fB:\fP (Unix) or \fB;\fP +(Windows). +.TS +center; +|l|l|. +_ +T{ +Suffix +T} T{ +Meaning +T} +_ +T{ +\-add +T} T{ +Append 1 or more items (may become alias for \-append) +T} +_ +T{ +\-append +T} T{ +Append single item (avoids need for escaping) +T} +_ +T{ +\-clr +T} T{ +Clear the option +T} +_ +T{ +\-del +T} T{ +Delete an existing item by integer index +T} +_ +T{ +\-pre +T} T{ +Prepend 1 or more items +T} +_ +T{ +\-set +T} T{ +Set a list of items +T} +_ +T{ +\-toggle +T} T{ +Append an item, or remove if if it already exists +T} +_ +.TE +.sp +Although some operations allow specifying multiple \fB,\fP\-separated items, using +this is strongly discouraged and deprecated, except for \fB\-set\fP\&. +.sp +Without suffix, the action taken is normally \fB\-set\fP\&. +.sp +Some options (like \fB\-\-sub\-file\fP, \fB\-\-audio\-file\fP, \fB\-\-glsl\-shader\fP) are +aliases for the proper option with \fB\-append\fP action. For example, +\fB\-\-sub\-file\fP is an alias for \fB\-\-sub\-files\-append\fP\&. +.sp +Some options only support a subset of the above. +.sp +Options of this type can be changed at runtime using the \fBchange\-list\fP +command, which takes the suffix as separate operation parameter. +.SS Playing DVDs +.sp +DVDs can be played with the \fBdvd://[title]\fP syntax. The optional +title specifier is a number which selects between separate video +streams on the DVD. If no title is given (\fBdvd://\fP) then the longest +title is selected automatically by the library. This is usually what +you want. mpv does not support DVD menus. +.sp +DVDs which have been copied on to a hard drive or other mounted +filesystem (by e.g. the \fBdvdbackup\fP tool) are accommodated by +specifying the path to the local copy: \fB\-\-dvd\-device=PATH\fP\&. +Alternatively, running \fBmpv PATH\fP should auto\-detect a DVD directory +tree and play the longest title. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +DVD subtitles +.sp +DVDs use image\-based subtitles. Image subtitles are implemented as +a bitmap video stream which can be superimposed over the main +movie. mpv\(aqs subtitle styling and positioning options and keyboard +shortcuts generally do not work with image\-based subtitles. +Exceptions include options like \fB\-\-stretch\-dvd\-subs\fP and +\fB\-\-stretch\-image\-subs\-to\-screen\fP\&. +.UNINDENT +.UNINDENT +.SH CONFIGURATION FILES +.SS Location and Syntax +.sp +You can put all of the options in configuration files which will be read every +time mpv is run. The system\-wide configuration file \(aqmpv.conf\(aq is in your +configuration directory (e.g. \fB/etc/mpv\fP or \fB/usr/local/etc/mpv\fP), the +user\-specific one is \fB~/.config/mpv/mpv.conf\fP\&. For details and platform +specifics (in particular Windows paths) see the \fI\%FILES\fP section. +.sp +User\-specific options override system\-wide options and options given on the +command line override either. The syntax of the configuration files is +\fBoption=value\fP\&. Everything after a \fI#\fP is considered a comment. Options +that work without values can be enabled by setting them to \fIyes\fP and disabled by +setting them to \fIno\fP\&. Even suboptions can be specified in this way. +.INDENT 0.0 +.INDENT 3.5 +.IP "Example configuration file" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Use GPU\-accelerated video output by default. +vo=gpu +# Use quotes for text that can contain spaces: +status\-msg="Time: ${time\-pos}" +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.SS Escaping spaces and special characters +.sp +This is done like with command line options. The shell is not involved here, +but option values still need to be quoted as a whole if it contains certain +characters like spaces. A config entry can be quoted with \fB"\fP, +as well as with the fixed\-length syntax (\fB%n%\fP) mentioned before. This is like +passing the exact contents of the quoted string as command line option. C\-style +escapes are currently _not_ interpreted on this level, although some options do +this manually. (This is a mess and should probably be changed at some point.) +.SS Putting Command Line Options into the Configuration File +.sp +Almost all command line options can be put into the configuration file. Here +is a small guide: +.TS +center; +|l|l|. +_ +T{ +Option +T} T{ +Configuration file entry +T} +_ +T{ +\fB\-\-flag\fP +T} T{ +\fBflag\fP +T} +_ +T{ +\fB\-opt val\fP +T} T{ +\fBopt=val\fP +T} +_ +T{ +\fB\-\-opt=val\fP +T} T{ +\fBopt=val\fP +T} +_ +T{ +\fB\-opt "has spaces"\fP +T} T{ +\fBopt="has spaces"\fP +T} +_ +.TE +.SS File\-specific Configuration Files +.sp +You can also write file\-specific configuration files. If you wish to have a +configuration file for a file called \(aqvideo.avi\(aq, create a file named +\(aqvideo.avi.conf\(aq with the file\-specific options in it and put it in +\fB~/.config/mpv/\fP\&. You can also put the configuration file in the same directory +as the file to be played. Both require you to set the \fB\-\-use\-filedir\-conf\fP +option (either on the command line or in your global config file). If a +file\-specific configuration file is found in the same directory, no +file\-specific configuration is loaded from \fB~/.config/mpv\fP\&. In addition, the +\fB\-\-use\-filedir\-conf\fP option enables directory\-specific configuration files. +For this, mpv first tries to load a mpv.conf from the same directory +as the file played and then tries to load any file\-specific configuration. +.SS Profiles +.sp +To ease working with different configurations, profiles can be defined in the +configuration files. A profile starts with its name in square brackets, +e.g. \fB[my\-profile]\fP\&. All following options will be part of the profile. A +description (shown by \fB\-\-profile=help\fP) can be defined with the +\fBprofile\-desc\fP option. To end the profile, start another one or use the +profile name \fBdefault\fP to continue with normal options. +.sp +You can list profiles with \fB\-\-profile=help\fP, and show the contents of a +profile with \fB\-\-show\-profile=<name>\fP (replace \fB<name>\fP with the profile +name). You can apply profiles on start with the \fB\-\-profile=<name>\fP option, +or at runtime with the \fBapply\-profile <name>\fP command. +.INDENT 0.0 +.INDENT 3.5 +.IP "Example mpv config file with profiles" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# normal top\-level option +fullscreen=yes + +# a profile that can be enabled with \-\-profile=big\-cache +[big\-cache] +cache=yes +demuxer\-max\-bytes=123400KiB +demuxer\-readahead\-secs=20 + +[slow] +profile\-desc="some profile name" +# reference a builtin profile +profile=gpu\-hq + +[fast] +vo=vdpau + +# using a profile again extends it +[slow] +framedrop=no +# you can also include other profiles +profile=big\-cache +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.SS Auto profiles +.sp +Some profiles are loaded automatically. The following example demonstrates this: +.INDENT 0.0 +.INDENT 3.5 +.IP "Auto profile loading" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[protocol.dvd] +profile\-desc="profile for dvd:// streams" +alang=en + +[extension.flv] +profile\-desc="profile for .flv files" +vf=flip +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +The profile name follows the schema \fBtype.name\fP, where type can be +\fBprotocol\fP for the input/output protocol in use (see \fB\-\-list\-protocols\fP), +and \fBextension\fP for the extension of the path of the currently played file +(\fInot\fP the file format). +.sp +This feature is very limited, and there are no other auto profiles. +.SH TAKING SCREENSHOTS +.sp +Screenshots of the currently played file can be taken using the \(aqscreenshot\(aq +input mode command, which is by default bound to the \fBs\fP key. Files named +\fBmpv\-shotNNNN.jpg\fP will be saved in the working directory, using the first +available number \- no files will be overwritten. In pseudo\-GUI mode, the +screenshot will be saved somewhere else. See \fI\%PSEUDO GUI MODE\fP\&. +.sp +A screenshot will usually contain the unscaled video contents at the end of the +video filter chain and subtitles. By default, \fBS\fP takes screenshots without +subtitles, while \fBs\fP includes subtitles. +.sp +Unlike with MPlayer, the \fBscreenshot\fP video filter is not required. This +filter was never required in mpv, and has been removed. +.SH TERMINAL STATUS LINE +.sp +During playback, mpv shows the playback status on the terminal. It looks like +something like this: +.INDENT 0.0 +.INDENT 3.5 +\fBAV: 00:03:12 / 00:24:25 (13%) A\-V: \-0.000\fP +.UNINDENT +.UNINDENT +.sp +The status line can be overridden with the \fB\-\-term\-status\-msg\fP option. +.sp +The following is a list of things that can show up in the status line. Input +properties, that can be used to get the same information manually, are also +listed. +.INDENT 0.0 +.IP \(bu 2 +\fBAV:\fP or \fBV:\fP (video only) or \fBA:\fP (audio only) +.IP \(bu 2 +The current time position in \fBHH:MM:SS\fP format (\fBplayback\-time\fP property) +.IP \(bu 2 +The total file duration (absent if unknown) (\fBlength\fP property) +.IP \(bu 2 +Playback speed, e.g. \(ga\(ga x2.0\(ga\(ga. Only visible if the speed is not normal. This +is the user\-requested speed, and not the actual speed (usually they should +be the same, unless playback is too slow). (\fBspeed\fP property.) +.IP \(bu 2 +Playback percentage, e.g. \fB(13%)\fP\&. How much of the file has been played. +Normally calculated out of playback position and duration, but can fallback +to other methods (like byte position) if these are not available. +(\fBpercent\-pos\fP property.) +.IP \(bu 2 +The audio/video sync as \fBA\-V: 0.000\fP\&. This is the difference between +audio and video time. Normally it should be 0 or close to 0. If it\(aqs growing, +it might indicate a playback problem. (\fBavsync\fP property.) +.IP \(bu 2 +Total A/V sync change, e.g. \fBct: \-0.417\fP\&. Normally invisible. Can show up +if there is audio "missing", or not enough frames can be dropped. Usually +this will indicate a problem. (\fBtotal\-avsync\-change\fP property.) +.IP \(bu 2 +Encoding state in \fB{...}\fP, only shown in encoding mode. +.IP \(bu 2 +Display sync state. If display sync is active (\fBdisplay\-sync\-active\fP +property), this shows \fBDS: 2.500/13\fP, where the first number is average +number of vsyncs per video frame (e.g. 2.5 when playing 24Hz videos on 60Hz +screens), which might jitter if the ratio doesn\(aqt round off, or there are +mistimed frames (\fBvsync\-ratio\fP), and the second number of estimated number +of vsyncs which took too long (\fBvo\-delayed\-frame\-count\fP property). The +latter is a heuristic, as it\(aqs generally not possible to determine this with +certainty. +.IP \(bu 2 +Dropped frames, e.g. \fBDropped: 4\fP\&. Shows up only if the count is not 0. Can +grow if the video framerate is higher than that of the display, or if video +rendering is too slow. May also be incremented on "hiccups" and when the video +frame couldn\(aqt be displayed on time. (\fBvo\-drop\-frame\-count\fP property.) +If the decoder drops frames, the number of decoder\-dropped frames is appended +to the display as well, e.g.: \fBDropped: 4/34\fP\&. This happens only if +decoder frame dropping is enabled with the \fB\-\-framedrop\fP options. +(\fBdrop\-frame\-count\fP property.) +.IP \(bu 2 +Cache state, e.g. \fBCache: 2s/134KB\fP\&. Visible if the stream cache is enabled. +The first value shows the amount of video buffered in the demuxer in seconds, +the second value shows the estimated size of the buffered amount in kilobytes. +(\fBdemuxer\-cache\-duration\fP and \fBdemuxer\-cache\-state\fP properties.) +.UNINDENT +.SH LOW LATENCY PLAYBACK +.sp +mpv is optimized for normal video playback, meaning it actually tries to buffer +as much data as it seems to make sense. This will increase latency. Reducing +latency is possible only by specifically disabling features which increase +latency. +.sp +The builtin \fBlow\-latency\fP profile tries to apply some of the options which can +reduce latency. You can use \fB\-\-profile=low\-latency\fP to apply all of them. You +can list the contents with \fB\-\-show\-profile=low\-latency\fP (some of the options +are quite obscure, and may change every mpv release). +.sp +Be aware that some of the options can reduce playback quality. +.sp +Most latency is actually caused by inconvenient timing behavior. You can disable +this with \fB\-\-untimed\fP, but it will likely break, unless the stream has no +audio, and the input feeds data to the player at a constant rate. +.sp +Another common problem is with MJPEG streams. These do not signal the correct +framerate. Using \fB\-\-untimed\fP or \fB\-\-no\-correct\-pts \-\-fps=60\fP might help. +.sp +For livestreams, data can build up due to pausing the stream, due to slightly +lower playback rate, or "buffering" pauses. If the demuxer cache is enabled, +these can be skipped manually. The experimental \fBdrop\-buffers\fP command can +be used to discard any buffered data, though it\(aqs very disruptive. +.sp +In some cases, manually tuning TCP buffer sizes and such can help to reduce +latency. +.sp +Additional options that can be tried: +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-opengl\-glfinish=yes\fP, can reduce buffering in the graphics driver +.IP \(bu 2 +\fB\-\-opengl\-swapinterval=0\fP, same +.IP \(bu 2 +\fB\-\-vo=xv\fP, same +.IP \(bu 2 +without audio \fB\-\-framedrop=no \-\-speed=1.01\fP may help for live sources +(results can be mixed) +.UNINDENT +.SH PROTOCOLS +.sp +\fBhttp://...\fP, \fBhttps://\fP, ... +.INDENT 0.0 +.INDENT 3.5 +Many network protocols are supported, but the protocol prefix must always +be specified. mpv will never attempt to guess whether a filename is +actually a network address. A protocol prefix is always required. +.sp +Note that not all prefixes are documented here. Undocumented prefixes are +either aliases to documented protocols, or are just redirections to +protocols implemented and documented in FFmpeg. +.sp +\fBdata:\fP is supported in FFmpeg (not in Libav), but needs to be in the +format \fBdata://\fP\&. This is done to avoid ambiguity with filenames. You +can also prefix it with \fBlavf://\fP or \fBffmpeg://\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBytdl://...\fP +.INDENT 0.0 +.INDENT 3.5 +By default, the youtube\-dl hook script (enabled by default for mpv CLI) +only looks at http URLs. Prefixing an URL with \fBytdl://\fP forces it to +be always processed by the script. This can also be used to invoke special +youtube\-dl functionality like playing a video by ID or invoking search. +.sp +Keep in mind that you can\(aqt pass youtube\-dl command line options by this, +and you have to use \fB\-\-ytdl\-raw\-options\fP instead. +.UNINDENT +.UNINDENT +.sp +\fB\-\fP +.INDENT 0.0 +.INDENT 3.5 +Play data from stdin. +.UNINDENT +.UNINDENT +.sp +\fBsmb://PATH\fP +.INDENT 0.0 +.INDENT 3.5 +Play a path from Samba share. +.UNINDENT +.UNINDENT +.sp +\fBbd://[title][/device]\fP \fB\-\-bluray\-device=PATH\fP +.INDENT 0.0 +.INDENT 3.5 +Play a Blu\-ray disc. Since libbluray 1.0.1, you can read from ISO files +by passing them to \fB\-\-bluray\-device\fP\&. +.sp +\fBtitle\fP can be: \fBlongest\fP or \fBfirst\fP (selects the default +playlist); \fBmpls/<number>\fP (selects <number>.mpls playlist); +\fB<number>\fP (select playlist with the same index). mpv will list +the available playlists on loading. +.sp +\fBbluray://\fP is an alias. +.UNINDENT +.UNINDENT +.sp +\fBdvd://[title|[starttitle]\-endtitle][/device]\fP \fB\-\-dvd\-device=PATH\fP +.INDENT 0.0 +.INDENT 3.5 +Play a DVD. DVD menus are not supported. If no title is given, the longest +title is auto\-selected. +.sp +\fBdvdnav://\fP is an old alias for \fBdvd://\fP and does exactly the same +thing. +.UNINDENT +.UNINDENT +.sp +\fBdvdread://...:\fP +.INDENT 0.0 +.INDENT 3.5 +Play a DVD using the old libdvdread code. This is what MPlayer and +older mpv versions used for \fBdvd://\fP\&. Use is discouraged. It\(aqs +provided only for compatibility and for transition, and to work +around outstanding dvdnav bugs (see "DVD library choices" above). +.UNINDENT +.UNINDENT +.sp +\fBtv://[channel][/input_id]\fP \fB\-\-tv\-...\fP +.INDENT 0.0 +.INDENT 3.5 +Analogue TV via V4L. Also useful for webcams. (Linux only.) +.UNINDENT +.UNINDENT +.sp +\fBpvr://\fP \fB\-\-pvr\-...\fP +.INDENT 0.0 +.INDENT 3.5 +PVR. (Linux only.) +.UNINDENT +.UNINDENT +.sp +\fBdvb://[cardnumber@]channel\fP \fB\-\-dvbin\-...\fP +.INDENT 0.0 +.INDENT 3.5 +Digital TV via DVB. (Linux only.) +.UNINDENT +.UNINDENT +.sp +\fBmf://[filemask|@listfile]\fP \fB\-\-mf\-...\fP +.INDENT 0.0 +.INDENT 3.5 +Play a series of images as video. +.UNINDENT +.UNINDENT +.sp +\fBcdda://[device]\fP \fB\-\-cdrom\-device=PATH\fP \fB\-\-cdda\-...\fP +.INDENT 0.0 +.INDENT 3.5 +Play CD. +.UNINDENT +.UNINDENT +.sp +\fBlavf://...\fP +.INDENT 0.0 +.INDENT 3.5 +Access any FFmpeg/Libav libavformat protocol. Basically, this passed the +string after the \fB//\fP directly to libavformat. +.UNINDENT +.UNINDENT +.sp +\fBav://type:options\fP +.INDENT 0.0 +.INDENT 3.5 +This is intended for using libavdevice inputs. \fBtype\fP is the libavdevice +demuxer name, and \fBoptions\fP is the (pseudo\-)filename passed to the +demuxer. +.sp +For example, \fBmpv av://lavfi:mandelbrot\fP makes use of the libavfilter +wrapper included in libavdevice, and will use the \fBmandelbrot\fP source +filter to generate input data. +.sp +\fBavdevice://\fP is an alias. +.UNINDENT +.UNINDENT +.sp +\fBfile://PATH\fP +.INDENT 0.0 +.INDENT 3.5 +A local path as URL. Might be useful in some special use\-cases. Note that +\fBPATH\fP itself should start with a third \fB/\fP to make the path an +absolute path. +.UNINDENT +.UNINDENT +.sp +\fBappending://PATH\fP +.INDENT 0.0 +.INDENT 3.5 +Play a local file, but assume it\(aqs being appended to. This is useful for +example for files that are currently being downloaded to disk. This will +block playback, and stop playback only if no new data was appended after +a timeout of about 2 seconds. +.sp +Using this is still a bit of a bad idea, because there is no way to detect +if a file is actually being appended, or if it\(aqs still written. If you\(aqre +trying to play the output of some program, consider using a pipe +(\fBsomething | mpv \-\fP). If it really has to be a file on disk, use tail to +make it wait forever, e.g. \fBtail \-f \-c +0 file.mkv | mpv \-\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBfd://123\fP +.INDENT 0.0 +.INDENT 3.5 +Read data from the given file descriptor (for example 123). This is similar +to piping data to stdin via \fB\-\fP, but can use an arbitrary file descriptor. +mpv may modify some file descriptor properties when the stream layer "opens" +it. +.UNINDENT +.UNINDENT +.sp +\fBfdclose://123\fP +.INDENT 0.0 +.INDENT 3.5 +Like \fBfd://\fP, but the file descriptor is closed after use. When using this +you need to ensure that the same fd URL will only be used once. +.UNINDENT +.UNINDENT +.sp +\fBedl://[edl specification as in edl\-mpv.rst]\fP +.INDENT 0.0 +.INDENT 3.5 +Stitch together parts of multiple files and play them. +.UNINDENT +.UNINDENT +.sp +\fBnull://\fP +.INDENT 0.0 +.INDENT 3.5 +Simulate an empty file. If opened for writing, it will discard all data. +The \fBnull\fP demuxer will specifically pass autoprobing if this protocol +is used (while it\(aqs not automatically invoked for empty files). +.UNINDENT +.UNINDENT +.sp +\fBmemory://data\fP +.INDENT 0.0 +.INDENT 3.5 +Use the \fBdata\fP part as source data. +.UNINDENT +.UNINDENT +.sp +\fBhex://data\fP +.INDENT 0.0 +.INDENT 3.5 +Like \fBmemory://\fP, but the string is interpreted as hexdump. +.UNINDENT +.UNINDENT +.SH PSEUDO GUI MODE +.sp +mpv has no official GUI, other than the OSC (\fI\%ON SCREEN CONTROLLER\fP), which +is not a full GUI and is not meant to be. However, to compensate for the lack +of expected GUI behavior, mpv will in some cases start with some settings +changed to behave slightly more like a GUI mode. +.sp +Currently this happens only in the following cases: +.INDENT 0.0 +.IP \(bu 2 +if started using the \fBmpv.desktop\fP file on Linux (e.g. started from menus +or file associations provided by desktop environments) +.IP \(bu 2 +if started from explorer.exe on Windows (technically, if it was started on +Windows, and all of the stdout/stderr/stdin handles are unset) +.IP \(bu 2 +started out of the bundle on OSX +.IP \(bu 2 +if you manually use \fB\-\-player\-operation\-mode=pseudo\-gui\fP on the command line +.UNINDENT +.sp +This mode applies options from the builtin profile \fBbuiltin\-pseudo\-gui\fP, but +only if these haven\(aqt been set in the user\(aqs config file or on the command line. +Also, for compatibility with the old pseudo\-gui behavior, the options in the +\fBpseudo\-gui\fP profile are applied unconditionally. In addition, the profile +makes sure to enable the pseudo\-GUI mode, so that \fB\-\-profile=pseudo\-gui\fP +works like in older mpv releases. The profiles are currently defined as follows: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[builtin\-pseudo\-gui] +terminal=no +force\-window=yes +idle=once +screenshot\-directory=~~desktop/ +[pseudo\-gui] +player\-operation\-mode=pseudo\-gui +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Currently, you can extend the \fBpseudo\-gui\fP profile in the config file the +normal way. This is deprecated. In future mpv releases, the behavior might +change, and not apply your additional settings, and/or use a different +profile name. +.UNINDENT +.UNINDENT +.SH OPTIONS +.SS Track Selection +.INDENT 0.0 +.TP +.B \fB\-\-alang=<languagecode[,languagecode,...]>\fP +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 \fB\-\-aid\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fBmpv dvd://1 \-\-alang=hu,en\fP chooses the Hungarian language track +on a DVD and falls back on English if Hungarian is not available. +.IP \(bu 2 +\fBmpv \-\-alang=jpn example.mkv\fP plays a Matroska file with Japanese +audio. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-slang=<languagecode[,languagecode,...]>\fP +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 \fB\-\-sid\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fBmpv dvd://1 \-\-slang=hu,en\fP chooses the Hungarian subtitle track on +a DVD and falls back on English if Hungarian is not available. +.IP \(bu 2 +\fBmpv \-\-slang=jpn example.mkv\fP plays a Matroska file with Japanese +subtitles. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-vlang=<...>\fP +Equivalent to \fB\-\-alang\fP and \fB\-\-slang\fP, for video tracks. +.TP +.B \fB\-\-aid=<ID|auto|no>\fP +Select audio track. \fBauto\fP selects the default, \fBno\fP disables audio. +See also \fB\-\-alang\fP\&. mpv normally prints available audio tracks on the +terminal when starting playback of a file. +.sp +\fB\-\-audio\fP is an alias for \fB\-\-aid\fP\&. +.sp +\fB\-\-aid=no\fP or \fB\-\-audio=no\fP or \fB\-\-no\-audio\fP disables audio playback. +(The latter variant does not work with the client API.) +.TP +.B \fB\-\-sid=<ID|auto|no>\fP +Display the subtitle stream specified by \fB<ID>\fP\&. \fBauto\fP selects +the default, \fBno\fP disables subtitles. +.sp +\fB\-\-sub\fP is an alias for \fB\-\-sid\fP\&. +.sp +\fB\-\-sid=no\fP or \fB\-\-sub=no\fP or \fB\-\-no\-sub\fP disables subtitle decoding. +(The latter variant does not work with the client API.) +.TP +.B \fB\-\-vid=<ID|auto|no>\fP +Select video channel. \fBauto\fP selects the default, \fBno\fP disables video. +.sp +\fB\-\-video\fP is an alias for \fB\-\-vid\fP\&. +.sp +\fB\-\-vid=no\fP or \fB\-\-video=no\fP or \fB\-\-no\-video\fP disables video playback. +(The latter variant does not work with the client API.) +.sp +If video is disabled, mpv will try to download the audio only if media is +streamed with youtube\-dl, because it saves bandwidth. This is done by +setting the ytdl_format to "bestaudio/best" in the ytdl_hook.lua script. +.TP +.B \fB\-\-edition=<ID|auto>\fP +(Matroska files only) +Specify the edition (set of chapters) to use, where 0 is the first. If set +to \fBauto\fP (the default), mpv will choose the first edition declared as a +default, or if there is no default, the first edition defined. +.TP +.B \fB\-\-track\-auto\-selection=<yes|no>\fP +Enable the default track auto\-selection (default: yes). Enabling this will +make the player select streams according to \fB\-\-aid\fP, \fB\-\-alang\fP, and +others. If it is disabled, no tracks are selected. In addition, the player +will not exit if no tracks are selected, and wait instead (this wait mode +is similar to pausing, but the pause option is not set). +.sp +This is useful with \fB\-\-lavfi\-complex\fP: you can start playback in this +mode, and then set select tracks at runtime by setting the filter graph. +Note that if \fB\-\-lavfi\-complex\fP is set before playback is started, the +referenced tracks are always selected. +.UNINDENT +.SS Playback Control +.INDENT 0.0 +.TP +.B \fB\-\-start=<relative time>\fP +Seek to given time position. +.sp +The general format for times is \fB[+|\-][[hh:]mm:]ss[.ms]\fP\&. If the time is +prefixed with \fB\-\fP, the time is considered relative from the end of the +file (as signaled by the demuxer/the file). A \fB+\fP is usually ignored (but +see below). +.sp +The following alternative time specifications are recognized: +.sp +\fBpp%\fP seeks to percent position pp (0\-100). +.sp +\fB#c\fP seeks to chapter number c. (Chapters start from 1.) +.sp +\fBnone\fP resets any previously set option (useful for libmpv). +.sp +If \fB\-\-rebase\-start\-time=no\fP is given, then prefixing times with \fB+\fP +makes the time relative to the start of the file. A timestamp without +prefix is considered an absolute time, i.e. should seek to a frame with a +timestamp as the file contains it. As a bug, but also a hidden feature, +putting 1 or more spaces before the \fB+\fP or \fB\-\fP always interprets the +time as absolute, which can be used to seek to negative timestamps (useful +for debugging at most). +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fB\-\-start=+56\fP, \fB\-\-start=00:56\fP +Seeks to the start time + 56 seconds. +.TP +.B \fB\-\-start=\-56\fP, \fB\-\-start=\-00:56\fP +Seeks to the end time \- 56 seconds. +.TP +.B \fB\-\-start=01:10:00\fP +Seeks to 1 hour 10 min. +.TP +.B \fB\-\-start=50%\fP +Seeks to the middle of the file. +.TP +.B \fB\-\-start=30 \-\-end=40\fP +Seeks to 30 seconds, plays 10 seconds, and exits. +.TP +.B \fB\-\-start=\-3:20 \-\-length=10\fP +Seeks to 3 minutes and 20 seconds before the end of the file, plays +10 seconds, and exits. +.TP +.B \fB\-\-start=\(aq#2\(aq \-\-end=\(aq#4\(aq\fP +Plays chapters 2 and 3, and exits. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-end=<relative time>\fP +Stop at given time. Use \fB\-\-length\fP if the time should be relative +to \fB\-\-start\fP\&. See \fB\-\-start\fP for valid option values and examples. +.TP +.B \fB\-\-length=<relative time>\fP +Stop after a given time relative to the start time. +See \fB\-\-start\fP for valid option values and examples. +.sp +If both \fB\-\-end\fP and \fB\-\-length\fP are provided, playback will stop when it +reaches either of the two endpoints. +.sp +Obscurity note: this does not work correctly if \fB\-\-rebase\-start\-time=no\fP, +and the specified time is not an "absolute" time, as defined in the +\fB\-\-start\fP option description. +.TP +.B \fB\-\-rebase\-start\-time=<yes|no>\fP +Whether to move the file start time to \fB00:00:00\fP (default: yes). This +is less awkward for files which start at a random timestamp, such as +transport streams. On the other hand, if there are timestamp resets, the +resulting behavior can be rather weird. For this reason, and in case you +are actually interested in the real timestamps, this behavior can be +disabled with \fBno\fP\&. +.TP +.B \fB\-\-speed=<0.01\-100>\fP +Slow down or speed up playback by the factor given as parameter. +.sp +If \fB\-\-audio\-pitch\-correction\fP (on by default) is used, playing with a +speed higher than normal automatically inserts the \fBscaletempo\fP audio +filter. +.TP +.B \fB\-\-pause\fP +Start the player in paused state. +.TP +.B \fB\-\-shuffle\fP +Play files in random order. +.TP +.B \fB\-\-playlist\-start=<auto|index>\fP +Set which file on the internal playlist to start playback with. The index +is an integer, with 0 meaning the first file. The value \fBauto\fP means that +the selection of the entry to play is left to the playback resume mechanism +(default). If an entry with the given index doesn\(aqt exist, the behavior is +unspecified and might change in future mpv versions. The same applies if +the playlist contains further playlists (don\(aqt expect any reasonable +behavior). Passing a playlist file to mpv should work with this option, +though. E.g. \fBmpv playlist.m3u \-\-playlist\-start=123\fP will work as expected, +as long as \fBplaylist.m3u\fP does not link to further playlists. +.sp +The value \fBno\fP is a deprecated alias for \fBauto\fP\&. +.TP +.B \fB\-\-playlist=<filename>\fP +Play files according to a playlist file (Supports some common formats. If +no format is detected, it will be treated as list of files, separated by +newline characters. Note that XML playlist formats are not supported.) +.sp +You can play playlists directly and without this option, however, this +option disables any security mechanisms that might be in place. You may +also need this option to load plaintext files as playlist. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +The way mpv uses playlist files via \fB\-\-playlist\fP 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 \fB\-\-playlist\fP with untrusted +sources. Do NOT use \fB\-\-playlist\fP with random internet sources or files +you do not trust! +.sp +Playlist can contain entries using other protocols, such as local files, +or (most severely), special protocols like \fBavdevice://\fP, which are +inherently unsafe. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-chapter\-merge\-threshold=<number>\fP +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. +.TP +.B \fB\-\-chapter\-seek\-threshold=<seconds>\fP +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. +.TP +.B \fB\-\-hr\-seek=<no|absolute|yes>\fP +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 input commands. +.INDENT 7.0 +.TP +.B no +Never use precise seeks. +.TP +.B 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). +.TP +.B yes +Use precise seeks whenever possible. +.TP +.B always +Same as \fByes\fP (for compatibility). +.UNINDENT +.TP +.B \fB\-\-hr\-seek\-demuxer\-offset=<seconds>\fP +This option exists to work around failures to do precise seeks (as in +\fB\-\-hr\-seek\fP) 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. +.TP +.B \fB\-\-hr\-seek\-framedrop=<yes|no>\fP +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\(aqre 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. +.sp +Default: \fByes\fP +.TP +.B \fB\-\-index=<mode>\fP +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\(aqt need to change +this. But it might help with some broken files. +.INDENT 7.0 +.TP +.B default +use an index if the file has one, or build it if missing +.TP +.B recreate +don\(aqt read or use the file\(aqs index +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This option only works if the underlying media supports seeking +(i.e. not with stdin, pipe, etc). +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-load\-unsafe\-playlists\fP +Load URLs from playlists which are considered unsafe (default: no). This +includes special protocols and anything that doesn\(aqt refer to normal files. +Local files and HTTP links on the other hand are always considered safe. +.sp +In addition, if a playlist is loaded while this is set, the added playlist +entries are not marked as originating from network or potentially unsafe +location. (Instead, the behavior is as if the playlist entries were provided +directly to mpv command line or \fBloadfile\fP command.) +.sp +Note that \fB\-\-playlist\fP always loads all entries, so you use that instead +if you really have the need for this functionality. +.TP +.B \fB\-\-access\-references=<yes|no>\fP +Follow any references in the file being opened (default: yes). Disabling +this is helpful if the file is automatically scanned (e.g. thumbnail +generation). If the thumbnail scanner for example encounters a playlist +file, which contains network URLs, and the scanner should not open these, +enabling this option will prevent it. This option also disables ordered +chapters, mov reference files, opening of archives, and a number of other +features. +.sp +On older FFmpeg versions, this will not work in some cases. Some FFmpeg +demuxers might not respect this option. +.sp +This option does not prevent opening of paired subtitle files and such. Use +\fB\-\-autoload\-files=no\fP to prevent this. +.sp +This option does not always work if you open non\-files (for example using +\fBdvd://directory\fP would open a whole bunch of files in the given +directory). Prefixing the filename with \fB\&./\fP if it doesn\(aqt start with +a \fB/\fP will avoid this. +.TP +.B \fB\-\-loop\-playlist=<N|inf|force|no>\fP, \fB\-\-loop\-playlist\fP +Loops playback \fBN\fP times. A value of \fB1\fP plays it one time (default), +\fB2\fP two times, etc. \fBinf\fP means forever. \fBno\fP is the same as \fB1\fP and +disables looping. If several files are specified on command line, the +entire playlist is looped. \fB\-\-loop\-playlist\fP is the same as +\fB\-\-loop\-playlist=inf\fP\&. +.sp +The \fBforce\fP mode is like \fBinf\fP, but does not skip playlist entries +which have been marked as failing. This means the player might waste CPU +time trying to loop a file that doesn\(aqt exist. But it might be useful for +playing webradios under very bad network conditions. +.TP +.B \fB\-\-loop\-file=<N|inf|no>\fP, \fB\-\-loop=<N|inf|no>\fP +Loop a single file N times. \fBinf\fP means forever, \fBno\fP means normal +playback. For compatibility, \fB\-\-loop\-file\fP and \fB\-\-loop\-file=yes\fP are +also accepted, and are the same as \fB\-\-loop\-file=inf\fP\&. +.sp +The difference to \fB\-\-loop\-playlist\fP is that this doesn\(aqt 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. +.sp +\fB\-\-loop\fP is an alias for this option. +.TP +.B \fB\-\-ab\-loop\-a=<time>\fP, \fB\-\-ab\-loop\-b=<time>\fP +Set loop points. If playback passes the \fBb\fP timestamp, it will seek to +the \fBa\fP timestamp. Seeking past the \fBb\fP point doesn\(aqt loop (this is +intentional). +.sp +If \fBa\fP is after \fBb\fP, the behavior is as if the points were given in +the right order, and the player will seek to \fBb\fP after crossing through +\fBa\fP\&. This is different from old behavior, where looping was disabled (and +as a bug, looped back to \fBa\fP on the end of the file). +.sp +If either options are set to \fBno\fP (or unset), looping is disabled. This +is different from old behavior, where an unset \fBa\fP implied the start of +the file, and an unset \fBb\fP the end of the file. +.sp +The loop\-points can be adjusted at runtime with the corresponding +properties. See also \fBab\-loop\fP command. +.TP +.B \fB\-\-ordered\-chapters\fP, \fB\-\-no\-ordered\-chapters\fP +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. +.TP +.B \fB\-\-ordered\-chapters\-files=<playlist\-file>\fP +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. +.sp +Useful for loading ordered chapter files that are not located on the local +filesystem, or if the referenced files are in different directories. +.sp +Note: a playlist can be as simple as a text file containing filenames +separated by newlines. +.TP +.B \fB\-\-chapters\-file=<filename>\fP +Load chapters from this file, instead of using the chapter metadata found +in the main file. +.sp +This accepts a media file (like mkv) or even a pseudo\-format like ffmetadata +and uses its chapters to replace the current file\(aqs chapters. This doesn\(aqt +work with OGM or XML chapters directly. +.TP +.B \fB\-\-sstep=<sec>\fP +Skip <sec> seconds after every frame. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Without \fB\-\-hr\-seek\fP, skipping will snap to keyframes. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-stop\-playback\-on\-init\-failure=<yes|no>\fP +Stop playback if either audio or video fails to initialize (default: no). +With \fBno\fP, playback will continue in video\-only or audio\-only mode if one +of them fails. This doesn\(aqt affect playback of audio\-only or video\-only +files. +.TP +.B \fB\-\-play\-dir=<forward|+|backward|\->\fP +Control the playback direction (default: forward). Setting \fBbackward\fP +will attempt to play the file in reverse direction, with decreasing +playback time. If this is set on playback starts, playback will start from +the end of the file. If this is changed at during playback, a hr\-seek will +be issued to change the direction. +.sp +\fB+\fP and \fB\-\fP are aliases for \fBforward\fP and \fBbackward\fP\&. +.sp +The rest of this option description pertains to the \fBbackward\fP mode. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Backward playback is extremely fragile. It may not always work, is much +slower than forward playback, and breaks certain other features. How +well it works depends mainly on the file being played. Generally, it +will show good results (or results at all) only if the stars align. +.UNINDENT +.UNINDENT +.sp +mpv, as well as most media formats, were designed for forward playback +only. Backward playback is bolted on top of mpv, and tries to make a medium +effort to make backward playback work. Depending on your use\-case, another +tool may work much better. +.sp +Backward playback is not exactly a 1st class feature. Implementation +tradeoffs were made, that are bad for backward playback, but in turn do not +cause disadvantages for normal playback. Various possible optimizations are +not implemented in order to keep the complexity down. Normally, a media +player is highly pipelined (future data is prepared in separate threads, so +it is available in realtime when the next stage needs it), but backward +playback will essentially stall the pipeline at various random points. +.sp +For example, for intra\-only codecs are trivially backward playable, and +tools built around them may make efficient use of them (consider video +editors or camera viewers). mpv won\(aqt be efficient in this case, because it +uses its generic backward playback algorithm, that on top of it is not very +optimized. +.sp +If you just want to quickly go backward through the video and just show +"keyframes", just use forward playback, and hold down the left cursor key +(which on CLI with default config sends many small relative seek commands). +.sp +The implementation consists of mostly 3 parts: +.INDENT 7.0 +.IP \(bu 2 +Backward demuxing. This relies on the demuxer cache, so the demuxer cache +should (or must, didn\(aqt test it) be enabled, and its size will affect +performance. If the cache is too small or too large, quadratic runtime +behavior may result. +.IP \(bu 2 +Backward decoding. The decoder library used (libavcodec) does not support +this. It is emulated by feeding bits of data in forward, putting the +result in a queue, returning the queue data to the VO in reverse, and +then starting over at an earlier position. This can require buffering an +extreme amount of decoded data, and also completely breaks pipelining. +.IP \(bu 2 +Backward output. This is relatively simple, because the decoder returns +the frames in the needed order. However, this may cause various problems +because filters see audio and video going backward. +.UNINDENT +.sp +Known problems: +.INDENT 7.0 +.IP \(bu 2 +It\(aqs fragile. If anything doesn\(aqt work, random non\-useful behavior may +occur. In simple cases, the player will just play nonsense and artifacts. +In other cases, it may get stuck or heat the CPU. (Exceeding memory usage +significantly beyond the user\-set limits would be a bug, though.) +.IP \(bu 2 +Performance and resource usage isn\(aqt good. In part this is inherent to +backward playback of normal media formats, and in parts due to +implementation choices and tradeoffs. +.IP \(bu 2 +This is extremely reliant on good demuxer behavior. Although backward +demuxing requires no special demuxer support, it is required that the +demuxer performs seeks reliably, fulfills some specific requirements +about packet metadata, and has deterministic behavior. +.IP \(bu 2 +Starting playback exactly from the end may or may not work, depending on +seeking behavior and file duration detection. +.IP \(bu 2 +Some container formats, audio, and video codecs are not supported due to +their behavior. There is no list, and the player usually does not detect +them. Certain live streams (including TV captures) may exhibit problems +in particular, as well as some lossy audio codecs. h264 intra\-refresh is +known not to work due to problems with libavcodec. WAV and some other raw +audio formats tend to have problems \- there are hacks for dealing with +them, which may or may not work. +.IP \(bu 2 +Backward demuxing of subtitles is not supported. Subtitle display still +works for some external text subtitle formats. (These are fully read into +memory, and only backward display is needed.) Text subtitles that are +cached in the subtitle renderer also have a chance to be displayed +correctly. +.IP \(bu 2 +Some features dealing with playback of broken or hard to deal with files +will not work fully (such as timestamp correction). +.IP \(bu 2 +If demuxer low level seeks (i.e. seeking the actual demuxer instead of +just within the demuxer cache) are performed by backward playback, the +created seek ranges may not join, because not enough overlap is achieved. +.IP \(bu 2 +Trying to use this with hardware video decoding will probably exhaust all +your GPU memory and then crash a thing or two. Or it will fail because +\fB\-\-hwdec\-extra\-frames\fP will certainly be set too low. +.IP \(bu 2 +Stream recording is broken. \fB\-\-stream\-record\fP may keep working if you +backward play within a cached region only. +.IP \(bu 2 +Relative seeks may behave weird. Small seeks backward (towards smaller +time, i.e. \fBseek \-1\fP) may not really seek properly, and audio will +remain muted for a while. Using hr\-seek is recommended, which should have +none of these problems. +.IP \(bu 2 +Some things are just weird. For example, while seek commands manipulate +playback time in the expected way (provided they work correctly), the +framestep commands are transposed. Backstepping will perform very +expensive work to step forward by 1 frame. +.UNINDENT +.sp +Tuning: +.INDENT 7.0 +.IP \(bu 2 +Remove all \fB\-\-vf\fP/\fB\-\-af\fP filters you have set. Disable hardware +decoding. Disable idiotic nonsense like SPDIF passthrough. +.IP \(bu 2 +Increasing \fB\-\-video\-reversal\-buffer\fP might help if reversal queue +overflow is reported, which may happen in high bitrate video, or video +with large GOP. Hardware decoding mostly ignores this, and you need to +increase \fB\-\-hwdec\-extra\-frames\fP instead (until you get playback without +logged errors). +.IP \(bu 2 +The demuxer cache is essential for backward demuxing. Make sure to set +\fB\-\-demuxer\-seekable\-cache\fP (or just use \fB\-\-cache\fP). The cache size +might matter. If it\(aqs too small, a queue overflow will be logged, and +backward playback cannot continue, or it performs too many low level +seeks. If it\(aqs too large, implementation tradeoffs may cause general +performance issues. Use \fB\-\-demuxer\-max\-bytes\fP to potentially increase +the amount of packets the demuxer layer can queue for reverse demuxing +(basically it\(aqs the \fB\-\-video\-reversal\-buffer\fP equivalent for the +demuxer layer). +.IP \(bu 2 +\fB\-\-demuxer\-backward\-playback\-step\fP also factors into how many seeks may +be performed, and whether backward demuxing could break due to queue +overflow. If it\(aqs set too high, the backstep operation needs to search +through more packets all the time, even if the cache is large enough. +.IP \(bu 2 +Setting \fB\-\-demuxer\-cache\-wait\fP may be useful to cache the entire file +into the demuxer cache. Set \fB\-\-demuxer\-max\-bytes\fP to a large size to +make sure it can read the entire cache; \fB\-\-demuxer\-max\-back\-bytes\fP +should also be set to a large size to prevent that tries to trim the +cache. +.IP \(bu 2 +If audio artifacts are audible, even though the AO does not underrun, +increasing \fB\-\-audio\-backward\-overlap\fP might help in some cases. +.UNINDENT +.TP +.B \fB\-\-video\-reversal\-buffer=<bytesize>\fP, \fB\-\-audio\-reversal\-buffer=<bytesize>\fP +For backward decoding. Backward decoding decodes forward in steps, and then +reverses the decoder output. These options control the approximate maximum +amount of bytes that can be buffered. The main use of this is to avoid +unbounded resource usage; during normal backward playback, it\(aqs not supposed +to hit the limit, and if it does, it will drop frames and complain about it. +.sp +Use this option if you get reversal queue overflow errors during backward +playback. Increase the size until the warning disappears. Usually, the video +buffer will overflow first, especially if it\(aqs high resolution video. +.sp +This does not work correctly if video hardware decoding is used. The video +frame size will not include the referenced GPU and driver memory. Some +hardware decoders may also be limited by \fB\-\-hwdec\-extra\-frames\fP\&. +.sp +How large the queue size needs to be depends entirely on the way the media +was encoded. Audio typically requires a very small buffer, while video can +require excessively large buffers. +.sp +(Technically, this allows the last frame to exceed the limit. Also, this +does not account for other buffered frames, such as inside the decoder or +the video output.) +.sp +This does not affect demuxer cache behavior at all. +.sp +See \fB\-\-list\-options\fP for defaults and value range. \fB<bytesize>\fP options +accept suffixes such as \fBKiB\fP and \fBMiB\fP\&. +.TP +.B \fB\-\-video\-backward\-overlap=<auto|number>\fP, \fB\-\-audio\-backward\-overlap=<auto|number>\fP +Number of overlapping keyframe ranges to use for backward decoding (default: +auto) ("keyframe" to be understood as in the mpv/ffmpeg specific meaning). +Backward decoding works by forward decoding in small steps. Some codecs +cannot restart decoding from any packet (even if it\(aqs marked as seek point), +which becomes noticeable with backward decoding (in theory this is a problem +with seeking too, but \fB\-\-hr\-seek\-demuxer\-offset\fP can fix it for seeking). +In particular, MDCT based audio codecs are affected. +.sp +The solution is to feed a previous packet to the decoder each time, and then +discard the output. This option controls how many packets to feed. The +\fBauto\fP choice is currently hardcoded to 0 for video, and uses 1 for lossy +audio, 0 for lossless audio. For some specific lossy audio codecs, this is +set to 2. +.sp +\fB\-\-video\-backward\-overlap\fP can potentially handle intra\-refresh video, +depending on the exact conditions. You may have to use the +\fB\-\-vd\-lavc\-show\-all\fP option as well. +.TP +.B \fB\-\-video\-backward\-batch=<number>\fP, \fB\-\-audio\-backward\-batch=<number>\fP +Number of keyframe ranges to decode at once when backward decoding (default: +1 for video, 10 for audio). Another pointless tuning parameter nobody should +use. This should affect performance only. In theory, setting a number higher +than 1 for audio will reduce overhead due to less frequent backstep +operations and less redundant decoding work due to fewer decoded overlap +frames (see \fB\-\-audio\-backward\-overlap\fP). On the other hand, it requires +a larger reversal buffer, and could make playback less smooth due to +breaking pipelining (e.g. by decoding a lot, and then doing nothing for a +while). +.sp +It probably never makes sense to set \fB\-\-video\-backward\-batch\fP\&. But in +theory, it could help with intra\-only video codecs by reducing backstep +operations. +.TP +.B \fB\-\-demuxer\-backward\-playback\-step=<seconds>\fP +Number of seconds the demuxer should seek back to get new packets during +backward playback (default: 60). This is useful for tuning backward +playback, see \fB\-\-play\-dir\fP for details. +.sp +Setting this to a very low value or 0 may make the player think seeking is +broken, or may make it perform multiple seeks. +.sp +Setting this to a high value may lead to quadratic runtime behavior. +.UNINDENT +.SS Program Behavior +.INDENT 0.0 +.TP +.B \fB\-\-help\fP, \fB\-\-h\fP +Show short summary of options. +.sp +You can also pass a string to this option, which will list all top\-level +options which contain the string in the name, e.g. \fB\-\-h=scale\fP for all +options that contain the word \fBscale\fP\&. The special string \fB*\fP lists +all top\-level options. +.TP +.B \fB\-v\fP +Increment verbosity level, one level for each \fB\-v\fP found on the command +line. +.TP +.B \fB\-\-version, \-V\fP +Print version string and exit. +.TP +.B \fB\-\-no\-config\fP +Do not load default configuration files. This prevents loading of both the +user\-level and system\-wide \fBmpv.conf\fP and \fBinput.conf\fP files. Other +configuration files are blocked as well, such as resume playback files. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Files explicitly requested by command line options, like +\fB\-\-include\fP or \fB\-\-use\-filedir\-conf\fP, will still be loaded. +.UNINDENT +.UNINDENT +.sp +See also: \fB\-\-config\-dir\fP\&. +.TP +.B \fB\-\-list\-options\fP +Prints all available options. +.TP +.B \fB\-\-list\-properties\fP +Print a list of the available properties. +.TP +.B \fB\-\-list\-protocols\fP +Print a list of the supported protocols. +.TP +.B \fB\-\-log\-file=<path>\fP +Opens the given path for writing, and print log messages to it. Existing +files will be truncated. The log level is at least \fB\-v \-v\fP, but +can be raised via \fB\-\-msg\-level\fP (the option cannot lower it below the +forced minimum log level). +.TP +.B \fB\-\-config\-dir=<path>\fP +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 (\fBMPV_HOME\fP) are also ignored. +.sp +Note that the \fB\-\-no\-config\fP option takes precedence over this option. +.TP +.B \fB\-\-save\-position\-on\-quit\fP +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. +.sp +This behavior is disabled by default, but is always available when quitting +the player with Shift+Q. +.TP +.B \fB\-\-watch\-later\-directory=<path>\fP +The directory in which to store the "watch later" temporary files. +.sp +The default is a subdirectory named "watch_later" underneath the +config directory (usually \fB~/.config/mpv/\fP). +.TP +.B \fB\-\-dump\-stats=<filename>\fP +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 \fBTOOLS/stats\-conv.py\fP can be +used (which currently displays it as a graph). +.sp +This option is useful for debugging only. +.TP +.B \fB\-\-idle=<no|yes|once>\fP +Makes mpv wait idly instead of quitting when there is no file to play. +Mostly useful in input mode, where mpv can be controlled through input +commands. (Default: \fBno\fP) +.sp +\fBonce\fP will only idle at start and let the player close once the +first playlist has finished playing back. +.TP +.B \fB\-\-include=<configuration\-file>\fP +Specify configuration file to be parsed after the default ones. +.TP +.B \fB\-\-load\-scripts=<yes|no>\fP +If set to \fBno\fP, don\(aqt auto\-load scripts from the \fBscripts\fP +configuration subdirectory (usually \fB~/.config/mpv/scripts/\fP). +(Default: \fByes\fP) +.TP +.B \fB\-\-script=<filename>\fP, \fB\-\-scripts=file1.lua:file2.lua:...\fP +Load a Lua script. The second option allows you to load multiple scripts by +separating them with the path separator (\fB:\fP on Unix, \fB;\fP on Windows). +.TP +.B \fB\-\-script\-opts=key1=value1,key2=value2,...\fP +Set options for scripts. A script can query an option by key. If an +option is used and what semantics the option value has depends entirely on +the loaded scripts. Values not claimed by any scripts are ignored. +.TP +.B \fB\-\-merge\-files\fP +Pretend that all files passed to mpv are concatenated into a single, big +file. This uses timeline/EDL support internally. +.TP +.B \fB\-\-no\-resume\-playback\fP +Do not restore playback position from the \fBwatch_later\fP configuration +subdirectory (usually \fB~/.config/mpv/watch_later/\fP). +See \fBquit\-watch\-later\fP input command. +.TP +.B \fB\-\-profile=<profile1,profile2,...>\fP +Use the given profile(s), \fB\-\-profile=help\fP displays a list of the +defined profiles. +.TP +.B \fB\-\-reset\-on\-next\-file=<all|option1,option2,...>\fP +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\(aqs, which tries to reset all settings +when starting next file.) +.sp +Default: Do not reset anything. +.sp +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. +.sp +In some cases, this might not work as expected. For example, \fB\-\-volume\fP +will only be reset if it is explicitly set in the config file or the +command line. +.sp +The special name \fBall\fP resets as many options as possible. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-reset\-on\-next\-file=pause\fP +Reset pause mode when switching to the next file. +.IP \(bu 2 +\fB\-\-reset\-on\-next\-file=fullscreen,speed\fP +Reset fullscreen and playback speed settings if they were changed +during playback. +.IP \(bu 2 +\fB\-\-reset\-on\-next\-file=all\fP +Try to reset all settings that were changed during playback. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-write\-filename\-in\-watch\-later\-config\fP +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. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This option may expose privacy\-sensitive information and is thus +disabled by default. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-ignore\-path\-in\-watch\-later\-config\fP +Ignore path (i.e. use filename only) when using watch later feature. +(Default: disabled) +.TP +.B \fB\-\-show\-profile=<profile>\fP +Show the description and content of a profile. +.TP +.B \fB\-\-use\-filedir\-conf\fP +Look for a file\-specific configuration file in the same directory as the +file that is being played. See \fI\%File\-specific Configuration Files\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +May be dangerous if playing from untrusted media. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-ytdl\fP, \fB\-\-no\-ytdl\fP +Enable the youtube\-dl hook\-script. It will look at the input URL, and will +play the video located on the website. This works with many streaming sites, +not just the one that the script is named after. This requires a recent +version of youtube\-dl to be installed on the system. (Enabled by default.) +.sp +If the script can\(aqt do anything with an URL, it will do nothing. +.sp +The \fBtry_ytdl_first\fP script option accepts a boolean \(aqyes\(aq or \(aqno\(aq, and if +\(aqyes\(aq will try parsing the URL with youtube\-dl first, instead of the default +where it\(aqs only after mpv failed to open it. This mostly depends on whether +most of your URLs need youtube\-dl parsing. +.sp +The \fBexclude\fP script option accepts a \fB|\fP\-separated list of URL patterns +which mpv should not use with youtube\-dl. The patterns are matched after +the \fBhttp(s)://\fP part of the URL. +.sp +\fB^\fP matches the beginning of the URL, \fB$\fP matches its end, and you +should use \fB%\fP before any of the characters \fB^$()%|,.[]*+\-?\fP to match +that character. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-script\-opts=ytdl_hook\-exclude=\(aq^youtube%.com\(aq\fP +will exclude any URL that starts with \fBhttp://youtube.com\fP or +\fBhttps://youtube.com\fP\&. +.IP \(bu 2 +\fB\-\-script\-opts=ytdl_hook\-exclude=\(aq%.mkv$|%.mp4$\(aq\fP +will exclude any URL that ends with \fB\&.mkv\fP or \fB\&.mp4\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +See more lua patterns here: \fI\%https://www.lua.org/manual/5.1/manual.html#5.4.1\fP +.sp +The \fBuse_manifests\fP script option makes mpv use the master manifest URL for +formats like HLS and DASH, if available, allowing for video/audio selection +in runtime. It\(aqs disabled ("no") by default for performance reasons. +.TP +.B \fB\-\-ytdl\-format=<best|worst|mp4|webm|...>\fP +Video format/quality that is directly passed to youtube\-dl. The possible +values are specific to the website and the video, for a given url the +available formats can be found with the command +\fByoutube\-dl \-\-list\-formats URL\fP\&. See youtube\-dl\(aqs documentation for +available aliases. +(Default: youtube\-dl\(aqs default, currently \fBbestvideo+bestaudio/best\fP) +.TP +.B \fB\-\-ytdl\-raw\-options=<key>=<value>[,<key>=<value>[,...]]\fP +Pass arbitrary options to youtube\-dl. Parameter and argument should be +passed as a key\-value pair. Options without argument must include \fB=\fP\&. +.sp +There is no sanity checking so it\(aqs possible to break things (i.e. +passing invalid parameters to youtube\-dl). +.sp +A proxy URL can be passed for youtube\-dl to use it in parsing the website. +This is useful for geo\-restricted URLs. After youtube\-dl parsing, some +URLs also require a proxy for playback, so this can pass that proxy +information to mpv. Take note that SOCKS proxies aren\(aqt supported and +https URLs also bypass the proxy. This is a limitation in FFmpeg. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-ytdl\-raw\-options=username=user,password=pass\fP +.IP \(bu 2 +\fB\-\-ytdl\-raw\-options=force\-ipv6=\fP +.IP \(bu 2 +\fB\-\-ytdl\-raw\-options=proxy=[http://127.0.0.1:3128]\fP +.IP \(bu 2 +\fB\-\-ytdl\-raw\-options\-append=proxy=http://127.0.0.1:3128\fP +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-load\-stats\-overlay=<yes|no>\fP +Enable the builtin script that shows useful playback information on a key +binding (default: yes). By default, the \fBi\fP key is used (\fBI\fP to make +the overlay permanent). +.TP +.B \fB\-\-player\-operation\-mode=<cplayer|pseudo\-gui>\fP +For enabling "pseudo GUI mode", which means that the defaults for some +options are changed. This option should not normally be used directly, but +only by mpv internally, or mpv\-provided scripts, config files, or .desktop +files. +.UNINDENT +.SS Video +.INDENT 0.0 +.TP +.B \fB\-\-vo=<driver>\fP +Specify the video output backend to be used. See \fI\%VIDEO OUTPUT DRIVERS\fP for +details and descriptions of available drivers. +.TP +.B \fB\-\-vd=<...>\fP +Specify a priority list of video decoders to be used, according to their +family and name. See \fB\-\-ad\fP for further details. Both of these options +use the same syntax and semantics; the only difference is that they +operate on different codec lists. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +See \fB\-\-vd=help\fP for a full list of available decoders. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-vf=<filter1[=parameter1:parameter2:...],filter2,...>\fP +Specify a list of video filters to apply to the video stream. See +\fI\%VIDEO FILTERS\fP for details and descriptions of the available filters. +The option variants \fB\-\-vf\-add\fP, \fB\-\-vf\-pre\fP, \fB\-\-vf\-del\fP and +\fB\-\-vf\-clr\fP exist to modify a previously specified list, but you +should not need these for typical use. +.TP +.B \fB\-\-untimed\fP +Do not sleep when outputting video frames. Useful for benchmarks when used +with \fB\-\-no\-audio.\fP +.TP +.B \fB\-\-framedrop=<mode>\fP +Skip displaying some frames to maintain A/V sync on slow systems, or +playing high framerate video on video outputs that have an upper framerate +limit. +.sp +The argument selects the drop methods, and can be one of the following: +.INDENT 7.0 +.TP +.B <no> +Disable any framedropping. +.TP +.B <vo> +Drop late frames on video output (default). This still decodes and +filters all frames, but doesn\(aqt render them on the VO. It tries to query +the display FPS (X11 only, not correct on multi\-monitor systems), or +assumes infinite display FPS if that fails. Drops are indicated in +the terminal status line as \fBDropped:\fP field. If the decoder is too slow, +in theory all frames would have to be dropped (because all frames are +too late) \- to avoid this, frame dropping stops if the effective +framerate is below 10 FPS. +.TP +.B <decoder> +Old, decoder\-based framedrop mode. (This is the same as \fB\-\-framedrop=yes\fP +in mpv 0.5.x and before.) This tells the decoder to skip frames (unless +they are needed to decode future frames). May help with slow systems, +but can produce unwatchable choppy output, or even freeze the display +completely. Not recommended. +The \fB\-\-vd\-lavc\-framedrop\fP option controls what frames to drop. +.TP +.B <decoder+vo> +Enable both modes. Not recommended. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fB\-\-vo=vdpau\fP has its own code for the \fBvo\fP framedrop mode. Slight +differences to other VOs are possible. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-video\-latency\-hacks=<yes|no>\fP +Enable some things which tend to reduce video latency by 1 or 2 frames +(default: no). Note that this option might be removed without notice once +the player\(aqs timing code does not inherently need to do these things +anymore. +.sp +This does: +.INDENT 7.0 +.IP \(bu 2 +Use the demuxer reported FPS for frame dropping. This avoids that the +player needs to decode 1 frame in advance, lowering total latency in +effect. This also means that if the demuxer reported FPS is wrong, or +the video filter chain changes FPS (e.g. deinterlacing), then it could +drop too many or not enough frames. +.IP \(bu 2 +Disable waiting for the first video frame. Normally the player waits for +the first video frame to be fully rendered before starting playback +properly. Some VOs will lazily initialize stuff when rendering the first +frame, so if this is not done, there is some likeliness that the VO has +to drop some frames if rendering the first frame takes longer than needed. +.UNINDENT +.TP +.B \fB\-\-display\-fps=<fps>\fP +Set the display FPS used with the \fB\-\-video\-sync=display\-*\fP modes. By +default, a detected value is used. Keep in mind that setting an incorrect +value (even if slightly incorrect) can ruin video playback. On multi\-monitor +systems, there is a chance that the detected value is from the wrong +monitor. +.sp +Set this option only if you have reason to believe the automatically +determined value is wrong. +.TP +.B \fB\-\-hwdec=<api>\fP +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. +.sp +\fB<api>\fP can be one of the following: +.INDENT 7.0 +.TP +.B no +always use software decoding (default) +.TP +.B auto +enable best hw decoder (see below) +.TP +.B yes +exactly the same as \fBauto\fP +.TP +.B auto\-copy +enable best hw decoder with copy\-back (see below) +.TP +.B vdpau +requires \fB\-\-vo=gpu\fP with \fB\-\-gpu\-context=x11\fP, +or \fB\-\-vo=vdpau\fP (Linux only) +.TP +.B vdpau\-copy +copies video back into system RAM (Linux with some GPUs only) +.TP +.B vaapi +requires \fB\-\-vo=gpu\fP or \fB\-\-vo=vaapi\fP (Linux only) +.TP +.B vaapi\-copy +copies video back into system RAM (Linux with some GPUs only) +.TP +.B videotoolbox +requires \fB\-\-vo=gpu\fP (OS X 10.8 and up), +or \fB\-\-vo=opengl\-cb\fP (iOS 9.0 and up) +.TP +.B videotoolbox\-copy +copies video back into system RAM (OS X 10.8 or iOS 9.0 and up) +.TP +.B dxva2 +requires \fB\-\-vo=gpu\fP with \fB\-\-gpu\-context=d3d11\fP, +\fB\-\-gpu\-context=angle\fP or \fB\-\-gpu\-context=dxinterop\fP +(Windows only) +.TP +.B dxva2\-copy +copies video back to system RAM (Windows only) +.TP +.B d3d11va +requires \fB\-\-vo=gpu\fP with \fB\-\-gpu\-context=d3d11\fP or +\fB\-\-gpu\-context=angle\fP (Windows 8+ only) +.TP +.B d3d11va\-copy +copies video back to system RAM (Windows 8+ only) +.TP +.B mediacodec +requires \fB\-\-vo=mediacodec_embed\fP (Android only) +.TP +.B mediacodec\-copy +copies video back to system RAM (Android only) +.TP +.B mmal +requires \fB\-\-vo=gpu\fP (Raspberry Pi only \- default if available) +.TP +.B mmal\-copy +copies video back to system RAM (Raspberry Pi only) +.TP +.B cuda +requires \fB\-\-vo=gpu\fP (Any platform CUDA is available) +.TP +.B cuda\-copy +copies video back to system RAM (Any platform CUDA is available) +.TP +.B nvdec +requires \fB\-\-vo=gpu\fP (Any platform CUDA is available) +.TP +.B nvdec\-copy +copies video back to system RAM (Any platform CUDA is available) +.TP +.B crystalhd +copies video back to system RAM (Any platform supported by hardware) +.TP +.B rkmpp +requires \fB\-\-vo=gpu\fP (some RockChip devices only) +.UNINDENT +.sp +\fBauto\fP 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 \fB\-\-vo=gpu\fP or \fB\-\-vo=vdpau\fP, vdpau decoding will +never be enabled. Also note that if the first found method doesn\(aqt actually +work, it will always fall back to software decoding, instead of trying the +next method (might matter on some Linux systems). +.sp +\fBauto\-copy\fP selects only modes that copy the video data back to system +memory after decoding. This selects modes like \fBvaapi\-copy\fP (and so on). +If none of these work, hardware decoding is disabled. This mode is always +guaranteed to incur no additional loss compared to software decoding, and +will allow CPU processing with video filters. +.sp +The \fBvaapi\fP mode, if used with \fB\-\-vo=gpu\fP, requires Mesa 11 and most +likely works with Intel GPUs only. It also requires the opengl EGL backend. +.sp +The \fBcuda\fP and \fBcuda\-copy\fP modes provides deinterlacing in the decoder +which is useful as there is no other deinterlacing mechanism in the gpu +output path. To use this deinterlacing you must pass the option: +\fBvd\-lavc\-o=deint=[weave|bob|adaptive]\fP\&. +Pass \fBweave\fP (or leave the option unset) to not attempt any +deinterlacing. \fBcuda\fP should always be preferred unless the \fBgpu\fP +vo is not being used or filters are required. +.sp +\fBnvdec\fP is a newer implementation of CUVID/CUDA decoding, which uses the +FFmpeg decoders for file parsing. Experimental, is known not to correctly +check whether decoding is supported by the hardware at all. Deinterlacing +is not supported. Since this uses FFmpeg\(aqs codec parsers, it is expected +that this generally causes fewer issues than \fBcuda\fP\&. +.sp +Most video filters will not work with hardware decoding as they are +primarily implemented on the CPU. Some exceptions are \fBvdpaupp\fP, +\fBvdpaurb\fP and \fBvavpp\fP\&. See \fI\%VIDEO FILTERS\fP for more details. +.sp +The \fB\&...\-copy\fP modes (e.g. \fBdxva2\-copy\fP) allow you to use hardware +decoding with any VO, backend or filter. Because these copy the decoded +video back to system RAM, they\(aqre likely less efficient than the direct +modes (like e.g. \fBdxva2\fP), and probably not more efficient than software +decoding except for some codecs (e.g. HEVC). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +When using this switch, hardware decoding is still only done for some +codecs. See \fB\-\-hwdec\-codecs\fP to enable hardware decoding for more +codecs. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Most non\-copy methods only work with the OpenGL GPU backend. Currently, +only the \fBnvdec\fP and \fBcuda\fP methods work with Vulkan. +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Quality reduction with hardware decoding" +.sp +In theory, hardware decoding does not reduce video quality (at least +for the codecs h264 and HEVC). However, due to restrictions in video +output APIs, as well as bugs in the actual hardware decoders, there can +be some loss, or even blatantly incorrect results. +.sp +In some cases, RGB conversion is forced, which means the RGB conversion +is performed by the hardware decoding API, instead of the shaders +used by \fB\-\-vo=gpu\fP\&. This means certain colorspaces may not display +correctly, and certain filtering (such as debanding) cannot be applied +in an ideal way. This will also usually force the use of low quality +chroma scalers instead of the one specified by \fB\-\-cscale\fP\&. In other +cases, hardware decoding can also reduce the bit depth of the decoded +image, which can introduce banding or precision loss for 10\-bit files. +.sp +\fBvdpau\fP is usually safe, except for 10 bit video. If deinterlacing +enabled (or the \fBvdpaupp\fP video filter is active in general), it +forces RGB conversion. The latter currently does not treat certain +colorspaces like BT.2020 correctly. +.sp +\fBvaapi\fP and \fBd3d11va\fP are safe. Enabling deinterlacing (or simply +their respective post\-processing filters) will possibly at least reduce +color quality by converting the output to a 8 bit format. +.sp +\fBdxva2\fP is not safe. It appears to always use BT.601 for forced RGB +conversion, but actual behavior depends on the GPU drivers. Some drivers +appear to convert to limited range RGB, which gives a faded appearance. +In addition to driver\-specific behavior, global system settings might +affect this additionally. This can give incorrect results even with +completely ordinary video sources. +.sp +\fBrpi\fP always uses the hardware overlay renderer, even with +\fB\-\-vo=gpu\fP\&. +.sp +\fBcuda\fP should be safe, but it has been reported to corrupt the +timestamps causing glitched, flashing frames on some files. It can also +sometimes cause massive framedrops for unknown reasons. Caution is +advised. +.sp +\fBcrystalhd\fP is not safe. It always converts to 4:2:2 YUV, which +may be lossy, depending on how chroma sub\-sampling is done during +conversion. It also discards the top left pixel of each frame for +some reason. +.sp +All other methods, in particular the copy\-back methods (like +\fBdxva2\-copy\fP etc.) should hopefully be safe, although they can still +cause random decoding issues. At the very least, they shouldn\(aqt affect +the colors of the image. +.sp +In particular, \fBauto\-copy\fP will only select "safe" modes +(although potentially slower than other methods), but there\(aqs still no +guarantee the chosen hardware decoder will actually work correctly. +.sp +In general, it\(aqs very strongly advised to avoid hardware decoding +unless \fBabsolutely\fP necessary, i.e. if your CPU is insufficient to +decode the file in questions. If you run into any weird decoding issues, +frame glitches or discoloration, and you have \fB\-\-hwdec\fP turned on, +the first thing you should try is disabling it. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-gpu\-hwdec\-interop=<auto|all|no|name>\fP +This option is for troubleshooting hwdec interop issues. Since it\(aqs a +debugging option, its semantics may change at any time. +.sp +This is useful for the \fBgpu\fP and \fBopengl\-cb\fP VOs for selecting which +hwdec interop context to use exactly. Effectively it also can be used +to block loading of certain backends. +.sp +If set to \fBauto\fP (default), the behavior depends on the VO: for \fBgpu\fP, +it does nothing, and the interop context is loaded on demand (when the +decoder probes for \fB\-\-hwdec\fP support). For \fBopengl\-cb\fP, which has +has no on\-demand loading, this is equivalent to \fBall\fP\&. +.sp +The empty string is equivalent to \fBauto\fP\&. +.sp +If set to \fBall\fP, it attempts to load all interop contexts at GL context +creation time. +.sp +Other than that, a specific backend can be set, and the list of them can +be queried with \fBhelp\fP (mpv CLI only). +.sp +Runtime changes to this are ignored (the current option value is used +whenever the renderer is created). +.sp +The old aliases \fB\-\-opengl\-hwdec\-interop\fP and \fB\-\-hwdec\-preload\fP are +barely related to this anymore, but will be somewhat compatible in some +cases. +.TP +.B \fB\-\-hwdec\-extra\-frames=<N>\fP +Number of GPU frames hardware decoding should preallocate (default: see +\fB\-\-list\-options\fP output). If this is too low, frame allocation may fail +during decoding, and video frames might get dropped and/or corrupted. +Setting it too high simply wastes GPU memory and has no advantages. +.sp +This value is used only for hardware decoding APIs which require +preallocating surfaces (known examples include \fBd3d11va\fP and \fBvaapi\fP). +For other APIs, frames are allocated as needed. The details depend on the +libavcodec implementations of the hardware decoders. +.sp +The required number of surfaces depends on dynamic runtime situations. The +default is a fixed value that is thought to be sufficient for most uses. But +in certain situations, it may not be enough. +.TP +.B \fB\-\-hwdec\-image\-format=<name>\fP +Set the internal pixel format used by hardware decoding via \fB\-\-hwdec\fP +(default \fBno\fP). The special value \fBno\fP selects an implementation +specific standard format. Most decoder implementations support only one +format, and will fail to initialize if the format is not supported. +.sp +Some implementations might support multiple formats. In particular, +videotoolbox is known to require \fBuyvy422\fP for good performance on some +older hardware. d3d11va can always use \fByuv420p\fP, which uses an opaque +format, with likely no advantages. +.TP +.B \fB\-\-cuda\-decode\-device=<auto|0..>\fP +Choose the GPU device used for decoding when using the \fBcuda\fP or +\fBnvdec\fP hwdecs with the OpenGL GPU backend. +.sp +By default, the device that is being used to provide \fBgpu\fP output will +also be used for decoding (and in the vast majority of cases, only one +GPU will be present). +.sp +Note that when using the \fBcuda\-copy\fP or \fBnvdec\-copy\fP hwdec, a +different option must be passed: \fB\-\-vd\-lavc\-o=gpu=<0..>\fP\&. +.sp +Note that this option is not available with the Vulkan GPU backend. With +Vulkan, decoding must always happen on the display device. +.TP +.B \fB\-\-vaapi\-device=<device file>\fP +Choose the DRM device for \fBvaapi\-copy\fP\&. This should be the path to a +DRM device file. (Default: \fB/dev/dri/renderD128\fP) +.TP +.B \fB\-\-panscan=<0.0\-1.0>\fP +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. +.sp +This option has no effect if \fB\-\-video\-unscaled\fP option is used. +.TP +.B \fB\-\-video\-aspect\-override=<ratio|no>\fP +Override video aspect ratio, in case aspect information is incorrect or +missing in the file being played. +.sp +These values have special meaning: +.INDENT 7.0 +.TP +.B 0 +disable aspect ratio handling, pretend the video has square pixels +.TP +.B no +same as \fB0\fP +.TP +.B \-1 +use the video stream or container aspect (default) +.UNINDENT +.sp +But note that handling of these special values might change in the future. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-video\-aspect\-override=4:3\fP or \fB\-\-video\-aspect\-override=1.3333\fP +.IP \(bu 2 +\fB\-\-video\-aspect\-override=16:9\fP or \fB\-\-video\-aspect\-override=1.7777\fP +.IP \(bu 2 +\fB\-\-no\-video\-aspect\-override\fP or \fB\-\-video\-aspect\-override=no\fP +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-video\-aspect\-method=<bitstream|container>\fP +This sets the default video aspect determination method (if the aspect is +_not_ overridden by the user with \fB\-\-video\-aspect\-override\fP or others). +.INDENT 7.0 +.TP +.B container +Strictly prefer the container aspect ratio. This is apparently +the default behavior with VLC, at least with Matroska. Note that +if the container has no aspect ratio set, the behavior is the +same as with bitstream. +.TP +.B bitstream +Strictly prefer the bitstream aspect ratio, unless the bitstream +aspect ratio is not set. This is apparently the default behavior +with XBMC/kodi, at least with Matroska. +.UNINDENT +.sp +The current default for mpv is \fBcontainer\fP\&. +.sp +Normally you should not set this. Try the various choices if you encounter +video that has the wrong aspect ratio in mpv, but seems to be correct in +other players. +.TP +.B \fB\-\-video\-unscaled=<no|yes|downscale\-big>\fP +Disable scaling of the video. If the window is larger than the video, +black bars are added. Otherwise, the video is cropped, unless the option +is set to \fBdownscale\-big\fP, in which case the video is fit to window. The +video still can be influenced by the other \fB\-\-video\-...\fP options. This +option disables the effect of \fB\-\-panscan\fP\&. +.sp +Note that the scaler algorithm may still be used, even if the video isn\(aqt +scaled. For example, this can influence chroma conversion. The video will +also still be scaled in one dimension if the source uses non\-square pixels +(e.g. anamorphic widescreen DVDs). +.sp +This option is disabled if the \fB\-\-no\-keepaspect\fP option is used. +.TP +.B \fB\-\-video\-pan\-x=<value>\fP, \fB\-\-video\-pan\-y=<value>\fP +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). +.sp +For example, displaying a 1280x720 video fullscreen on a 1680x1050 screen +with \fB\-\-video\-pan\-x=\-0.1\fP would move the video 168 pixels to the left +(making 128 pixels of the source video invisible). +.sp +This option is disabled if the \fB\-\-no\-keepaspect\fP option is used. +.TP +.B \fB\-\-video\-rotate=<0\-359|no>\fP +Rotate the video clockwise, in degrees. Currently supports 90° steps only. +If \fBno\fP 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 \fB0\fP would rotate the video according to the +rotation metadata.) +.TP +.B \fB\-\-video\-zoom=<value>\fP +Adjust the video display scale factor by the given value. The parameter is +given log 2. For example, \fB\-\-video\-zoom=0\fP is unscaled, +\fB\-\-video\-zoom=1\fP is twice the size, \fB\-\-video\-zoom=\-2\fP is one fourth of +the size, and so on. +.sp +This option is disabled if the \fB\-\-no\-keepaspect\fP option is used. +.TP +.B \fB\-\-video\-align\-x=<\-1\-1>\fP, \fB\-\-video\-align\-y=<\-1\-1>\fP +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. +\fB\-\-video\-align\-y=\-1\fP would move the video to the top of the screen +(leaving a border only on the bottom), a value of \fB0\fP centers it +(default), and a value of \fB1\fP would put the video at the bottom of the +screen. +.sp +If video and screen aspect match perfectly, these options do nothing. +.sp +This option is disabled if the \fB\-\-no\-keepaspect\fP option is used. +.TP +.B \fB\-\-video\-margin\-ratio\-left=<val>\fP, \fB\-\-video\-margin\-ratio\-right=<val>\fP, \fB\-\-video\-margin\-ratio\-top=<val>\fP, \fB\-\-video\-margin\-ratio\-bottom=<val>\fP +Set extra video margins on each border (default: 0). Each value is a ratio +of the window size, using a range 0.0\-1.0. For example, setting the option +\fB\-\-video\-margin\-ratio\-right=0.2\fP at a window size of 1000 pixels will add +a 200 pixels border on the right side of the window. +.sp +The video is "boxed" by these margins. The window size is not changed. In +particular it does not enlarge the window, and the margins will cause the +video to be downscaled by default. This may or may not change in the future. +.sp +The margins are applied after 90° video rotation, but before any other video +transformations. +.sp +This option is disabled if the \fB\-\-no\-keepaspect\fP option is used. +.sp +Subtitles still may use the margins, depending on \fB\-\-sub\-use\-margins\fP and +similar options. +.sp +These options were created for the OSC. Some odd decisions, such as making +the margin values a ratio (instead of pixels), were made for the sake of +the OSC. It\(aqs possible that these options may be replaced by ones that are +more generally useful. The behavior of these options may change to fit +OSC requirements better, too. +.TP +.B \fB\-\-correct\-pts\fP, \fB\-\-no\-correct\-pts\fP +\fB\-\-no\-correct\-pts\fP switches mpv to a mode where video timing is +determined using a fixed framerate value (either using the \fB\-\-fps\fP +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, seeking (including hr\-seeks and backstepping), +and audio synchronization can be completely broken in this mode. +.TP +.B \fB\-\-fps=<float>\fP +Override video framerate. Useful if the original value is wrong or missing. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Works in \fB\-\-no\-correct\-pts\fP mode only. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-deinterlace=<yes|no>\fP +Enable or disable interlacing (default: 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. +.sp +This behaves exactly like the \fBdeinterlace\fP input property (usually +mapped to \fBd\fP). +.sp +Keep in mind that this \fBwill\fP conflict with manually inserted +deinterlacing filters, unless you take care. (Since mpv 0.27.0, even the +hardware deinterlace filters will conflict. Also since that version, +\fB\-\-deinterlace=auto\fP was removed, which used to mean that the default +interlacing option of possibly inserted video filters was used.) +.sp +Note that this will make video look worse if it\(aqs not actually interlaced. +.TP +.B \fB\-\-frames=<number>\fP +Play/convert only first \fB<number>\fP video frames, then quit. +.sp +\fB\-\-frames=0\fP loads the file, but immediately quits before initializing +playback. (Might be useful for scripts which just want to determine some +file properties.) +.sp +For audio\-only playback, any value greater than 0 will quit playback +immediately after initialization. The value 0 works as with video. +.TP +.B \fB\-\-video\-output\-levels=<outputlevels>\fP +RGB color levels used with YUV to RGB conversion. Normally, output devices +such as PC monitors use full range color levels. However, some TVs and +video monitors expect studio RGB levels. Providing full range output to a +device expecting studio level input results in crushed blacks and whites, +the reverse in dim gray blacks and dim whites. +.sp +Not all VOs support this option. Some will silently ignore it. +.sp +Available color ranges are: +.INDENT 7.0 +.TP +.B auto +automatic selection (equals to full range) (default) +.TP +.B limited +limited range (16\-235 per component), studio levels +.TP +.B full +full range (0\-255 per component), PC levels +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +It is advisable to use your graphics driver\(aqs color range option +instead, if available. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-hwdec\-codecs=<codec1,codec2,...|all>\fP +Allow hardware decoding for a given list of codecs only. The special value +\fBall\fP always allows all codecs. +.sp +You can get the list of allowed codecs with \fBmpv \-\-vd=help\fP\&. Remove the +prefix, e.g. instead of \fBlavc:h264\fP use \fBh264\fP\&. +.sp +By default, this is set to \fBh264,vc1,hevc,vp9\fP\&. Note that +the hardware acceleration special codecs like \fBh264_vdpau\fP are not +relevant anymore, and in fact have been removed from Libav in this form. +.sp +This is usually only needed with broken GPUs, where a codec is reported +as supported, but decoding causes more problems than it solves. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.TP +.B \fBmpv \-\-hwdec=vdpau \-\-vo=vdpau \-\-hwdec\-codecs=h264,mpeg2video\fP +Enable vdpau decoding for h264 and mpeg2 only. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-vd\-lavc\-check\-hw\-profile=<yes|no>\fP +Check hardware decoder profile (default: yes). If \fBno\fP 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. +.TP +.B \fB\-\-vd\-lavc\-software\-fallback=<yes|no|N>\fP +Fallback to software decoding if the hardware\-accelerated decoder fails +(default: 3). If this is a number, then fallback will be triggered if +N frames fail to decode in a row. 1 is equivalent to \fByes\fP\&. +.TP +.B \fB\-\-vd\-lavc\-dr=<yes|no>\fP +Enable direct rendering (default: yes). If this is set to \fByes\fP, the +video will be decoded directly to GPU video memory (or staging buffers). +This can speed up video upload, and may help with large resolutions or +slow hardware. This works only with the following VOs: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +\fBgpu\fP: requires at least OpenGL 4.4 or Vulkan. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +(In particular, this can\(aqt be made work with \fBopengl\-cb\fP, but the libmpv +render API has optional support.) +.sp +Using video filters of any kind that write to the image data (or output +newly allocated frames) will silently disable the DR code path. +.TP +.B \fB\-\-vd\-lavc\-bitexact\fP +Only use bit\-exact algorithms in all decoding steps (for codec testing). +.TP +.B \fB\-\-vd\-lavc\-fast\fP (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. +.TP +.B \fB\-\-vd\-lavc\-o=<key>=<value>[,<key>=<value>[,...]]\fP +Pass AVOptions to libavcodec decoder. Note, a patch to make the \fBo=\fP +unneeded and pass all unknown options through the AVOption system is +welcome. A full list of AVOptions can be found in the FFmpeg manual. +.sp +Some options which used to be direct options can be set with this +mechanism, like \fBbug\fP, \fBgray\fP, \fBidct\fP, \fBec\fP, \fBvismv\fP, +\fBskip_top\fP (was \fBst\fP), \fBskip_bottom\fP (was \fBsb\fP), \fBdebug\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +\fB\-\-vd\-lavc\-o=debug=pict\fP +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-vd\-lavc\-show\-all=<yes|no>\fP +Show even broken/corrupt frames (default: no). If this option is set to +no, libavcodec won\(aqt output frames that were either decoded before an +initial keyframe was decoded, or frames that are recognized as corrupted. +.TP +.B \fB\-\-vd\-lavc\-skiploopfilter=<skipvalue> (H.264 only)\fP +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. +.sp +\fB<skipvalue>\fP can be one of the following: +.INDENT 7.0 +.TP +.B none +Never skip. +.TP +.B default +Skip useless processing steps (e.g. 0 size packets in AVI). +.TP +.B nonref +Skip frames that are not referenced (i.e. not used for +decoding other frames, the error cannot "build up"). +.TP +.B bidir +Skip B\-Frames. +.TP +.B nonkey +Skip all frames except keyframes. +.TP +.B all +Skip all frames. +.UNINDENT +.TP +.B \fB\-\-vd\-lavc\-skipidct=<skipvalue> (MPEG\-1/2 only)\fP +Skips the IDCT step. This degrades quality a lot in almost all cases +(see skiploopfilter for available skip values). +.TP +.B \fB\-\-vd\-lavc\-skipframe=<skipvalue>\fP +Skips decoding of frames completely. Big speedup, but jerky motion and +sometimes bad artifacts (see skiploopfilter for available skip values). +.TP +.B \fB\-\-vd\-lavc\-framedrop=<skipvalue>\fP +Set framedropping mode used with \fB\-\-framedrop\fP (see skiploopfilter for +available skip values). +.TP +.B \fB\-\-vd\-lavc\-threads=<N>\fP +Number of threads to use for decoding. Whether threading is actually +supported depends on codec (default: 0). 0 means autodetect number of cores +on the machine and use that, up to the maximum of 16. You can set more than +16 threads manually. +.TP +.B \fB\-\-vd\-lavc\-assume\-old\-x264=<yes|no>\fP +Assume the video was encoded by an old, buggy x264 version (default: no). +Normally, this is autodetected by libavcodec. But if the bitstream contains +no x264 version info (or it was somehow skipped), and the stream was in fact +encoded by an old x264 version (build 150 or earlier), and if the stream +uses \fB4:4:4\fP chroma, then libavcodec will by default show corrupted video. +This option sets the libavcodec \fBx264_build\fP option to \fB150\fP, which +means that if the stream contains no version info, or was not encoded by +x264 at all, it assumes it was encoded by the old version. Enabling this +option is pretty safe if you want your broken files to work, but in theory +this can break on streams not encoded by x264, or if a stream encoded by a +newer x264 version contains no version info. +.TP +.B \fB\-\-swapchain\-depth=<N>\fP +Allow up to N in\-flight frames. This essentially controls the frame +latency. Increasing the swapchain depth can improve pipelining and prevent +missed vsyncs, but increases visible latency. This option only mandates an +upper limit, the implementation can use a lower latency than requested +internally. A setting of 1 means that the VO will wait for every frame to +become visible before starting to render the next frame. (Default: 3) +.UNINDENT +.SS Audio +.INDENT 0.0 +.TP +.B \fB\-\-audio\-pitch\-correction=<yes|no>\fP +If this is enabled (default), playing with a speed different from normal +automatically inserts the \fBscaletempo\fP audio filter. For details, see +audio filter section. +.TP +.B \fB\-\-audio\-device=<name>\fP +Use the given audio device. This consists of the audio output name, e.g. +\fBalsa\fP, followed by \fB/\fP, followed by the audio output specific device +name. The default value for this option is \fBauto\fP, which tries every audio +output in preference order with the default device. +.sp +You can list audio devices with \fB\-\-audio\-device=help\fP\&. This outputs the +device name in quotes, followed by a description. The device name is what +you have to pass to the \fB\-\-audio\-device\fP option. The list of audio devices +can be retrieved by API by using the \fBaudio\-device\-list\fP property. +.sp +While the option normally takes one of the strings as indicated by the +methods above, you can also force the device for most AOs by building it +manually. For example \fBname/foobar\fP forces the AO \fBname\fP to use the +device \fBfoobar\fP\&. However, the \fB\-\-ao\fP option will strictly force a +specific AO. To avoid confusion, don\(aqt use \fB\-\-ao\fP and \fB\-\-audio\-device\fP +together. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example for ALSA" +.sp +MPlayer and mplayer2 required you to replace any \(aq,\(aq with \(aq.\(aq and +any \(aq:\(aq with \(aq=\(aq in the ALSA device name. For example, to use the +device named \fBdmix:default\fP, you had to do: +.INDENT 0.0 +.INDENT 3.5 +\fB\-ao alsa:device=dmix=default\fP +.UNINDENT +.UNINDENT +.sp +In mpv you could instead use: +.INDENT 0.0 +.INDENT 3.5 +\fB\-\-audio\-device=alsa/dmix:default\fP +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-audio\-exclusive=<yes|no>\fP +Enable exclusive output mode. In this mode, the system is usually locked +out, and only mpv will be able to output audio. +.sp +This only works for some audio outputs, such as \fBwasapi\fP and +\fBcoreaudio\fP\&. Other audio outputs silently ignore this options. They either +have no concept of exclusive mode, or the mpv side of the implementation is +missing. +.TP +.B \fB\-\-audio\-fallback\-to\-null=<yes|no>\fP +If no audio device can be opened, behave as if \fB\-\-ao=null\fP was given. This +is useful in combination with \fB\-\-audio\-device\fP: instead of causing an +error if the selected device does not exist, the client API user (or a +Lua script) could let playback continue normally, and check the +\fBcurrent\-ao\fP and \fBaudio\-device\-list\fP properties to make high\-level +decisions about how to continue. +.TP +.B \fB\-\-ao=<driver>\fP +Specify the audio output drivers to be used. See \fI\%AUDIO OUTPUT DRIVERS\fP for +details and descriptions of available drivers. +.TP +.B \fB\-\-af=<filter1[=parameter1:parameter2:...],filter2,...>\fP +Specify a list of audio filters to apply to the audio stream. See +\fI\%AUDIO FILTERS\fP for details and descriptions of the available filters. +The option variants \fB\-\-af\-add\fP, \fB\-\-af\-pre\fP, \fB\-\-af\-del\fP and +\fB\-\-af\-clr\fP exist to modify a previously specified list, but you +should not need these for typical use. +.TP +.B \fB\-\-audio\-spdif=<codecs>\fP +List of codecs for which compressed audio passthrough should be used. This +works for both classic S/PDIF and HDMI. +.sp +Possible codecs are \fBac3\fP, \fBdts\fP, \fBdts\-hd\fP, \fBeac3\fP, \fBtruehd\fP\&. +Multiple codecs can be specified by separating them with \fB,\fP\&. \fBdts\fP +refers to low bitrate DTS core, while \fBdts\-hd\fP refers to DTS MA (receiver +and OS support varies). If both \fBdts\fP and \fBdts\-hd\fP are specified, it +behaves equivalent to specifying \fBdts\-hd\fP only. +.sp +In earlier mpv versions you could use \fB\-\-ad\fP to force the spdif wrapper. +This does not work anymore. +.INDENT 7.0 +.INDENT 3.5 +.IP "Warning" +.sp +There is not much reason to use this. HDMI supports uncompressed +multichannel PCM, and mpv supports lossless DTS\-HD decoding via +FFmpeg\(aqs new DCA decoder (based on libdcadec). +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-ad=<decoder1,decoder2,...[\-]>\fP +Specify a priority list of audio decoders to be used, according to their +decoder name. When determining which decoder to use, the first decoder that +matches the audio format is selected. If that is unavailable, the next +decoder is used. Finally, it tries all other decoders that are not +explicitly selected or rejected by the option. +.sp +\fB\-\fP at the end of the list suppresses fallback on other available +decoders not on the \fB\-\-ad\fP list. \fB+\fP in front of an entry forces the +decoder. Both of these should not normally be used, because they break +normal decoder auto\-selection! Both of these methods are deprecated. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fB\-\-ad=mp3float\fP +Prefer the FFmpeg/Libav \fBmp3float\fP decoder over all other MP3 +decoders. +.TP +.B \fB\-\-ad=help\fP +List all available decoders. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Warning" +.sp +Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with +this option is not possible. Use \fB\-\-audio\-spdif\fP instead. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-volume=<value>\fP +Set the startup volume. 0 means silence, 100 means no volume reduction or +amplification. Negative values can be passed for compatibility, but are +treated as 0. +.sp +Since mpv 0.18.1, this always controls the internal mixer (aka "softvol"). +.TP +.B \fB\-\-replaygain=<no|track|album>\fP +Adjust volume gain according to replaygain values stored in the file +metadata. With \fB\-\-replaygain=no\fP (the default), perform no adjustment. +With \fB\-\-replaygain=track\fP, apply track gain. With \fB\-\-replaygain=album\fP, +apply album gain if present and fall back to track gain otherwise. +.TP +.B \fB\-\-replaygain\-preamp=<db>\fP +Pre\-amplification gain in dB to apply to the selected replaygain gain +(default: 0). +.TP +.B \fB\-\-replaygain\-clip=<yes|no>\fP +Prevent clipping caused by replaygain by automatically lowering the +gain (default). Use \fB\-\-replaygain\-clip=no\fP to disable this. +.TP +.B \fB\-\-replaygain\-fallback=<db>\fP +Gain in dB to apply if the file has no replay gain tags. This option +is always applied if the replaygain logic is somehow inactive. If this +is applied, no other replaygain options are applied. +.TP +.B \fB\-\-audio\-delay=<sec>\fP +Audio delay in seconds (positive or negative float value). Positive values +delay the audio, and negative values delay the video. +.TP +.B \fB\-\-mute=<yes|no|auto>\fP +Set startup audio mute status (default: no). +.sp +\fBauto\fP is a deprecated possible value that is equivalent to \fBno\fP\&. +.sp +See also: \fB\-\-volume\fP\&. +.TP +.B \fB\-\-softvol=<no|yes|auto>\fP +Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether +to use the volume controls of the audio output driver or the internal mpv +volume filter. +.sp +The current behavior is that softvol is always enabled, i.e. as if this +option is set to \fByes\fP\&. The other behaviors are not available anymore, +although \fBauto\fP almost matches current behavior in most cases. +.sp +The \fBno\fP behavior is still partially available through the \fBao\-volume\fP +and \fBao\-mute\fP properties. But there are no options to reset these. +.TP +.B \fB\-\-audio\-demuxer=<[+]name>\fP +Use this audio demuxer type when using \fB\-\-audio\-file\fP\&. Use a \(aq+\(aq before +the name to force it; this will skip some checks. Give the demuxer name as +printed by \fB\-\-audio\-demuxer=help\fP\&. +.TP +.B \fB\-\-ad\-lavc\-ac3drc=<level>\fP +Select the Dynamic Range Compression level for AC\-3 audio streams. +\fB<level>\fP is a float value ranging from 0 to 1, where 0 means no +compression (which is the default) and 1 means full compression (make loud +passages more silent and vice versa). Values up to 6 are also accepted, but +are purely experimental. This option only shows an effect if the AC\-3 stream +contains the required range compression information. +.sp +The standard mandates that DRC is enabled by default, but mpv (and some +other players) ignore this for the sake of better audio quality. +.TP +.B \fB\-\-ad\-lavc\-downmix=<yes|no>\fP +Whether to request audio channel downmixing from the decoder (default: yes). +Some decoders, like AC\-3, AAC and DTS, can remix audio on decoding. The +requested number of output channels is set with the \fB\-\-audio\-channels\fP option. +Useful for playing surround audio on a stereo system. +.TP +.B \fB\-\-ad\-lavc\-threads=<0\-16>\fP +Number of threads to use for decoding. Whether threading is actually +supported depends on codec. As of this writing, it\(aqs supported for some +lossless codecs only. 0 means autodetect number of cores on the +machine and use that, up to the maximum of 16 (default: 1). +.TP +.B \fB\-\-ad\-lavc\-o=<key>=<value>[,<key>=<value>[,...]]\fP +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. +.TP +.B \fB\-\-ad\-spdif\-dtshd=<yes|no>\fP, \fB\-\-dtshd\fP, \fB\-\-no\-dtshd\fP +If DTS is passed through, use DTS\-HD. +.INDENT 7.0 +.INDENT 3.5 +.IP "Warning" +.sp +This and enabling passthrough via \fB\-\-ad\fP are deprecated in favor of +using \fB\-\-audio\-spdif=dts\-hd\fP\&. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-audio\-channels=<auto\-safe|auto|layouts>\fP +Control which audio channels are output (e.g. surround vs. stereo). There +are the following possibilities: +.INDENT 7.0 +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fB\-\-audio\-channels=auto\-safe\fP +Use the system\(aqs preferred channel layout. If there is none (such +as when accessing a hardware device instead of the system mixer), +force stereo. Some audio outputs might simply accept any layout and +do downmixing on their own. +.sp +This is the default. +.UNINDENT +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fB\-\-audio\-channels=auto\fP +Send the audio device whatever it accepts, preferring the audio\(aqs +original channel layout. Can cause issues with HDMI (see the warning +below). +.UNINDENT +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fB\-\-audio\-channels=layout1,layout2,...\fP +List of \fB,\fP\-separated channel layouts which should be allowed. +Technically, this only adjusts the filter chain output to the best +matching layout in the list, and passes the result to the audio API. +It\(aqs possible that the audio API will select a different channel +layout. +.sp +Using this mode is recommended for direct hardware output, especially +over HDMI (see HDMI warning below). +.UNINDENT +.IP \(bu 2 +.INDENT 2.0 +.TP +.B \fB\-\-audio\-channels=stereo\fP +Force a plain stereo downmix. This is a special\-case of the previous +item. (See paragraphs below for implications.) +.UNINDENT +.UNINDENT +.sp +If a list of layouts is given, each item can be either an explicit channel +layout name (like \fB5.1\fP), or a channel number. Channel numbers refer to +default layouts, e.g. 2 channels refer to stereo, 6 refers to 5.1. +.sp +See \fB\-\-audio\-channels=help\fP output for defined default layouts. This also +lists speaker names, which can be used to express arbitrary channel +layouts (e.g. \fBfl\-fr\-lfe\fP is 2.1). +.sp +If the list of channel layouts has only 1 item, the decoder is asked to +produce according output. This sometimes triggers decoder\-downmix, which +might be different from the normal mpv downmix. (Only some decoders support +remixing audio, like AC\-3, AAC or DTS. You can use \fB\-\-ad\-lavc\-downmix=no\fP +to make the decoder always output its native layout.) One consequence is +that \fB\-\-audio\-channels=stereo\fP triggers decoder downmix, while \fBauto\fP +or \fBauto\-safe\fP never will, even if they end up selecting stereo. This +happens because the decision whether to use decoder downmix happens long +before the audio device is opened. +.sp +If the channel layout of the media file (i.e. the decoder) and the AO\(aqs +channel layout don\(aqt match, mpv will attempt to insert a conversion filter. +You may need to change the channel layout of the system mixer to achieve +your desired output as mpv does not have control over it. Another +work\-around for this on some AOs is to use \fB\-\-audio\-exclusive=yes\fP to +circumvent the system mixer entirely. +.INDENT 7.0 +.INDENT 3.5 +.IP "Warning" +.sp +Using \fBauto\fP can cause issues when using audio over HDMI. The OS will +typically report all channel layouts that _can_ go over HDMI, even if +the receiver does not support them. If a receiver gets an unsupported +channel layout, random things can happen, such as dropping the +additional channels, or adding noise. +.sp +You are recommended to set an explicit whitelist of the layouts you +want. For example, most A/V receivers connected via HDMI and that can +do 7.1 would be served by: \fB\-\-audio\-channels=7.1,5.1,stereo\fP +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-audio\-display=<no|attachment>\fP +Setting this option to \fBattachment\fP (default) will display image +attachments (e.g. album cover art) when playing audio files. It will +display the first image found, and additional images are available as +video tracks. +.sp +Setting this option to \fBno\fP disables display of video entirely when +playing audio files. +.sp +This option has no influence on files with normal video tracks. +.TP +.B \fB\-\-audio\-files=<files>\fP +Play audio from an external file while viewing a video. +.sp +This is a list option. See \fI\%List Options\fP for details. +.TP +.B \fB\-\-audio\-file=<file>\fP +CLI/config file only alias for \fB\-\-audio\-files\-append\fP\&. Each use of this +option will add a new audio track. The details are similar to how +\fB\-\-sub\-file\fP works. +.TP +.B \fB\-\-audio\-format=<format>\fP +Select the sample format used for output from the audio filter layer to +the sound card. The values that \fB<format>\fP can adopt are listed below in +the description of the \fBformat\fP audio filter. +.TP +.B \fB\-\-audio\-samplerate=<Hz>\fP +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. +.TP +.B \fB\-\-gapless\-audio=<no|yes|weak>\fP +Try to play consecutive audio files with no silence or disruption at the +point of file change. Default: \fBweak\fP\&. +.INDENT 7.0 +.TP +.B no +Disable gapless audio. +.TP +.B yes +The audio device is opened using parameters chosen for the first +file played and is then kept open for gapless playback. This +means that if the first file for example has a low sample rate, then +the following files may get resampled to the same low sample rate, +resulting in reduced sound quality. If you play files with different +parameters, consider using options such as \fB\-\-audio\-samplerate\fP +and \fB\-\-audio\-format\fP to explicitly select what the shared output +format will be. +.TP +.B weak +Normally, the audio device is kept open (using the format it was +first initialized with). If the audio format the decoder output +changes, the audio device is closed and reopened. This means that +you will normally get gapless audio with files that were encoded +using the same settings, but might not be gapless in other cases. +The exact conditions under which the audio device is kept open is +an implementation detail, and can change from version to version. +Currently, the device is kept even if the sample format changes, +but the sample formats are convertible. +If video is still going on when there is still audio, trying to use +gapless is also explicitly given up. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This feature is implemented in a simple manner and relies on audio +output device buffering to continue playback while moving from one file +to another. If playback of the new file starts slowly, for example +because it is played from a remote network location or because you have +specified cache settings that require time for the initial cache fill, +then the buffered audio may run out before playback of the new file +can start. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-initial\-audio\-sync\fP, \fB\-\-no\-initial\-audio\-sync\fP +When starting a video file or after events such as seeking, mpv will by +default modify the audio stream to make it start from the same timestamp +as video, by either inserting silence at the start or cutting away the +first samples. Disabling this option makes the player behave like older +mpv versions did: video and audio are both started immediately even if +their start timestamps differ, and then video timing is gradually adjusted +if necessary to reach correct synchronization later. +.TP +.B \fB\-\-volume\-max=<100.0\-1000.0>\fP, \fB\-\-softvol\-max=<...>\fP +Set the maximum amplification level in percent (default: 130). A value of +130 will allow you to adjust the volume up to about double the normal level. +.sp +\fB\-\-softvol\-max\fP is a deprecated alias and should not be used. +.TP +.B \fB\-\-audio\-file\-auto=<no|exact|fuzzy|all>\fP, \fB\-\-no\-audio\-file\-auto\fP +Load additional audio files matching the video filename. The parameter +specifies how external audio files are matched. +.INDENT 7.0 +.TP +.B no +Don\(aqt automatically load external audio files (default). +.TP +.B exact +Load the media filename with audio file extension. +.TP +.B fuzzy +Load all audio files containing media filename. +.TP +.B all +Load all audio files in the current and \fB\-\-audio\-file\-paths\fP +directories. +.UNINDENT +.TP +.B \fB\-\-audio\-file\-paths=<path1:path2:...>\fP +Equivalent to \fB\-\-sub\-file\-paths\fP option, but for auto\-loaded audio files. +.TP +.B \fB\-\-audio\-client\-name=<name>\fP +The application name the player reports to the audio API. Can be useful +if you want to force a different audio profile (e.g. with PulseAudio), +or to set your own application name when using libmpv. +.TP +.B \fB\-\-audio\-buffer=<seconds>\fP +Set the audio output minimum buffer. The audio device might actually create +a larger buffer if it pleases. If the device creates a smaller buffer, +additional audio is buffered in an additional software buffer. +.sp +Making this larger will make soft\-volume and other filters react slower, +introduce additional issues on playback speed change, and block the +player on audio format changes. A smaller buffer might lead to audio +dropouts. +.sp +This option should be used for testing only. If a non\-default value helps +significantly, the mpv developers should be contacted. +.sp +Default: 0.2 (200 ms). +.TP +.B \fB\-\-audio\-stream\-silence=<yes|no>\fP +Cash\-grab consumer audio hardware (such as A/V receivers) often ignore +initial audio sent over HDMI. This can happen every time audio over HDMI +is stopped and resumed. In order to compensate for this, you can enable +this option to not to stop and restart audio on seeks, and fill the gaps +with silence. Likewise, when pausing playback, audio is not stopped, and +silence is played while paused. Note that if no audio track is selected, +the audio device will still be closed immediately. +.sp +Not all AOs support this. +.TP +.B \fB\-\-audio\-wait\-open=<secs>\fP +This makes sense for use with \fB\-\-audio\-stream\-silence=yes\fP\&. If this option +is given, the player will wait for the given amount of seconds after opening +the audio device before sending actual audio data to it. Useful if your +expensive hardware discards the first 1 or 2 seconds of audio data sent to +it. If \fB\-\-audio\-stream\-silence=yes\fP is not set, this option will likely +just waste time. +.UNINDENT +.SS Subtitles +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Changing styling and position does not work with all subtitles. Image\-based +subtitles (DVD, Bluray/PGS, DVB) cannot changed for fundamental reasons. +Subtitles in ASS format are normally not changed intentionally, but +overriding them can be controlled with \fB\-\-sub\-ass\-override\fP\&. +.sp +Previously some options working on text subtitles were called +\fB\-\-sub\-text\-*\fP, they are now named \fB\-\-sub\-*\fP, and those specifically +for ASS have been renamed from \fB\-\-ass\-*\fP to \fB\-\-sub\-ass\-*\fP\&. +They are now all in this section. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fB\-\-sub\-demuxer=<[+]name>\fP +Force subtitle demuxer type for \fB\-\-sub\-file\fP\&. Give the demuxer name as +printed by \fB\-\-sub\-demuxer=help\fP\&. +.TP +.B \fB\-\-sub\-delay=<sec>\fP +Delays subtitles by \fB<sec>\fP seconds. Can be negative. +.TP +.B \fB\-\-sub\-files=<file\-list>\fP, \fB\-\-sub\-file=<filename>\fP +Add a subtitle file to the list of external subtitles. +.sp +If you use \fB\-\-sub\-file\fP only once, this subtitle file is displayed by +default. +.sp +If \fB\-\-sub\-file\fP is used multiple times, the subtitle to use can be +switched at runtime by cycling subtitle tracks. It\(aqs possible to show +two subtitles at once: use \fB\-\-sid\fP to select the first subtitle index, +and \fB\-\-secondary\-sid\fP to select the second index. (The index is printed +on the terminal output after the \fB\-\-sid=\fP in the list of streams.) +.sp +\fB\-\-sub\-files\fP is a list option (see \fI\%List Options\fP for details), and +can take multiple file names separated by \fB:\fP (Unix) or \fB;\fP (Windows), +while \fB\-\-sub\-file\fP takes a single filename, but can be used multiple +times to add multiple files. Technically, \fB\-\-sub\-file\fP is a CLI/config +file only alias for \fB\-\-sub\-files\-append\fP\&. +.TP +.B \fB\-\-secondary\-sid=<ID|auto|no>\fP +Select a secondary subtitle stream. This is similar to \fB\-\-sid\fP\&. If a +secondary subtitle is selected, it will be rendered as toptitle (i.e. on +the top of the screen) alongside the normal subtitle, and provides a way +to render two subtitles at once. +.sp +There are some caveats associated with this feature. For example, bitmap +subtitles will always be rendered in their usual position, so selecting a +bitmap subtitle as secondary subtitle will result in overlapping subtitles. +Secondary subtitles are never shown on the terminal if video is disabled. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Styling and interpretation of any formatting tags is disabled for the +secondary subtitle. Internally, the same mechanism as \fB\-\-no\-sub\-ass\fP +is used to strip the styling. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If the main subtitle stream contains formatting tags which display the +subtitle at the top of the screen, it will overlap with the secondary +subtitle. To prevent this, you could use \fB\-\-no\-sub\-ass\fP to disable +styling in the main subtitle stream. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-scale=<0\-100>\fP +Factor for the text subtitle font size (default: 1). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This affects ASS subtitles as well, and may lead to incorrect subtitle +rendering. Use with care, or use \fB\-\-sub\-font\-size\fP instead. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-scale\-by\-window=<yes|no>\fP +Whether to scale subtitles with the window size (default: yes). If this is +disabled, changing the window size won\(aqt change the subtitle font size. +.sp +Like \fB\-\-sub\-scale\fP, this can break ASS subtitles. +.TP +.B \fB\-\-sub\-scale\-with\-window=<yes|no>\fP +Make the subtitle font size relative to the window, instead of the video. +This is useful if you always want the same font size, even if the video +doesn\(aqt cover the window fully, e.g. because screen aspect and window +aspect mismatch (and the player adds black bars). +.sp +Default: yes. +.sp +This option is misnamed. The difference to the confusingly similar sounding +option \fB\-\-sub\-scale\-by\-window\fP is that \fB\-\-sub\-scale\-with\-window\fP still +scales with the approximate window size, while the other option disables +this scaling. +.sp +Affects plain text subtitles only (or ASS if \fB\-\-sub\-ass\-override\fP is set +high enough). +.TP +.B \fB\-\-sub\-ass\-scale\-with\-window=<yes|no>\fP +Like \fB\-\-sub\-scale\-with\-window\fP, but affects subtitles in ASS format only. +Like \fB\-\-sub\-scale\fP, this can break ASS subtitles. +.sp +Default: no. +.TP +.B \fB\-\-embeddedfonts=<yes|no>\fP +Use fonts embedded in Matroska container files and ASS scripts (default: +yes). These fonts can be used for SSA/ASS subtitle rendering. +.TP +.B \fB\-\-sub\-pos=<0\-100>\fP +Specify the position of subtitles on the screen. The value is the vertical +position of the subtitle in % of the screen height. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This affects ASS subtitles as well, and may lead to incorrect subtitle +rendering. Use with care, or use \fB\-\-sub\-margin\-y\fP instead. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-speed=<0.1\-10.0>\fP +Multiply the subtitle event timestamps with the given value. Can be used +to fix the playback speed for frame\-based subtitle formats. Affects text +subtitles only. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +\fB\-\-sub\-speed=25/23.976\fP plays frame based subtitles which have been +loaded assuming a framerate of 23.976 at 25 FPS. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-ass\-force\-style=<[Style.]Param=Value[,...]>\fP +Override some style or script info parameters. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-sub\-ass\-force\-style=FontName=Arial,Default.Bold=1\fP +.IP \(bu 2 +\fB\-\-sub\-ass\-force\-style=PlayResY=768\fP +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Using this option may lead to incorrect subtitle rendering. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-ass\-hinting=<none|light|normal|native>\fP +Set font hinting type. <type> can be: +.INDENT 7.0 +.TP +.B none +no hinting (default) +.TP +.B light +FreeType autohinter, light mode +.TP +.B normal +FreeType autohinter, normal mode +.TP +.B native +font native hinter +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Warning" +.sp +Enabling hinting can lead to mispositioned text (in situations it\(aqs +supposed to match up video background), or reduce the smoothness +of animations with some badly authored ASS scripts. It is recommended +to not use this option, unless really needed. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-ass\-line\-spacing=<value>\fP +Set line spacing value for SSA/ASS renderer. +.TP +.B \fB\-\-sub\-ass\-shaper=<simple|complex>\fP +Set the text layout engine used by libass. +.INDENT 7.0 +.TP +.B simple +uses Fribidi only, fast, doesn\(aqt render some languages correctly +.TP +.B complex +uses HarfBuzz, slower, wider language support +.UNINDENT +.sp +\fBcomplex\fP is the default. If libass hasn\(aqt been compiled against HarfBuzz, +libass silently reverts to \fBsimple\fP\&. +.TP +.B \fB\-\-sub\-ass\-styles=<filename>\fP +Load all SSA/ASS styles found in the specified file and use them for +rendering text subtitles. The syntax of the file is exactly like the \fB[V4 +Styles]\fP / \fB[V4+ Styles]\fP section of SSA/ASS. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Using this option may lead to incorrect subtitle rendering. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-ass\-override=<yes|no|force|scale|strip>\fP +Control whether user style overrides should be applied. Note that all of +these overrides try to be somewhat smart about figuring out whether or not +a subtitle is considered a "sign". +.INDENT 7.0 +.TP +.B no +Render subtitles as specified by the subtitle scripts, without +overrides. +.TP +.B yes +Apply all the \fB\-\-sub\-ass\-*\fP style override options. Changing the +default for any of these options can lead to incorrect subtitle +rendering (default). +.TP +.B force +Like \fByes\fP, but also force all \fB\-\-sub\-*\fP options. Can break +rendering easily. +.TP +.B scale +Like \fByes\fP, but also apply \fB\-\-sub\-scale\fP\&. +.TP +.B strip +Radically strip all ASS tags and styles from the subtitle. This +is equivalent to the old \fB\-\-no\-ass\fP / \fB\-\-no\-sub\-ass\fP options. +.UNINDENT +.sp +This also controls some bitmap subtitle overrides, as well as HTML tags in +formats like SRT, despite the name of the option. +.TP +.B \fB\-\-sub\-ass\-force\-margins\fP +Enables placing toptitles and subtitles in black borders when they are +available, if the subtitles are in the ASS format. +.sp +Default: no. +.TP +.B \fB\-\-sub\-use\-margins\fP +Enables placing toptitles and subtitles in black borders when they are +available, if the subtitles are in a plain text format (or ASS if +\fB\-\-sub\-ass\-override\fP is set high enough). +.sp +Default: yes. +.sp +Renamed from \fB\-\-sub\-ass\-use\-margins\fP\&. To place ASS subtitles in the borders +too (like the old option did), also add \fB\-\-sub\-ass\-force\-margins\fP\&. +.TP +.B \fB\-\-sub\-ass\-vsfilter\-aspect\-compat=<yes|no>\fP +Stretch SSA/ASS subtitles when playing anamorphic videos for compatibility +with traditional VSFilter behavior. This switch has no effect when the +video is stored with square pixels. +.sp +The renderer historically most commonly used for the SSA/ASS subtitle +formats, VSFilter, had questionable behavior that resulted in subtitles +being stretched too if the video was stored in anamorphic format that +required scaling for display. This behavior is usually undesirable and +newer VSFilter versions may behave differently. However, many existing +scripts compensate for the stretching by modifying things in the opposite +direction. Thus, if such scripts are displayed "correctly", they will not +appear as intended. This switch enables emulation of the old VSFilter +behavior (undesirable but expected by many existing scripts). +.sp +Enabled by default. +.TP +.B \fB\-\-sub\-ass\-vsfilter\-blur\-compat=<yes|no>\fP +Scale \fB\eblur\fP tags by video resolution instead of script resolution +(enabled by default). This is bug in VSFilter, which according to some, +can\(aqt be fixed anymore in the name of compatibility. +.sp +Note that this uses the actual video resolution for calculating the +offset scale factor, not what the video filter chain or the video output +use. +.TP +.B \fB\-\-sub\-ass\-vsfilter\-color\-compat=<basic|full|force\-601|no>\fP +Mangle colors like (xy\-)vsfilter do (default: basic). Historically, VSFilter +was not color space aware. This was no problem as long as the color space +used for SD video (BT.601) was used. But when everything switched to HD +(BT.709), VSFilter was still converting RGB colors to BT.601, rendered +them into the video frame, and handled the frame to the video output, which +would use BT.709 for conversion to RGB. The result were mangled subtitle +colors. Later on, bad hacks were added on top of the ASS format to control +how colors are to be mangled. +.INDENT 7.0 +.TP +.B basic +Handle only BT.601\->BT.709 mangling, if the subtitles seem to +indicate that this is required (default). +.TP +.B full +Handle the full \fBYCbCr Matrix\fP header with all video color spaces +supported by libass and mpv. This might lead to bad breakages in +corner cases and is not strictly needed for compatibility +(hopefully), which is why this is not default. +.TP +.B force\-601 +Force BT.601\->BT.709 mangling, regardless of subtitle headers +or video color space. +.TP +.B no +Disable color mangling completely. All colors are RGB. +.UNINDENT +.sp +Choosing anything other than \fBno\fP will make the subtitle color depend on +the video color space, and it\(aqs for example in theory not possible to reuse +a subtitle script with another video file. The \fB\-\-sub\-ass\-override\fP +option doesn\(aqt affect how this option is interpreted. +.TP +.B \fB\-\-stretch\-dvd\-subs=<yes|no>\fP +Stretch DVD subtitles when playing anamorphic videos for better looking +fonts on badly mastered DVDs. This switch has no effect when the +video is stored with square pixels \- which for DVD input cannot be the case +though. +.sp +Many studios tend to use bitmap fonts designed for square pixels when +authoring DVDs, causing the fonts to look stretched on playback on DVD +players. This option fixes them, however at the price of possibly +misaligning some subtitles (e.g. sign translations). +.sp +Disabled by default. +.TP +.B \fB\-\-stretch\-image\-subs\-to\-screen=<yes|no>\fP +Stretch DVD and other image subtitles to the screen, ignoring the video +margins. This has a similar effect as \fB\-\-sub\-use\-margins\fP for text +subtitles, except that the text itself will be stretched, not only just +repositioned. (At least in general it is unavoidable, as an image bitmap +can in theory consist of a single bitmap covering the whole screen, and +the player won\(aqt know where exactly the text parts are located.) +.sp +This option does not display subtitles correctly. Use with care. +.sp +Disabled by default. +.TP +.B \fB\-\-image\-subs\-video\-resolution=<yes|no>\fP +Override the image subtitle resolution with the video resolution +(default: no). Normally, the subtitle canvas is fit into the video canvas +(e.g. letterboxed). Setting this option uses the video size as subtitle +canvas size. Can be useful to test broken subtitles, which often happen +when the video was trancoded, while attempting to keep the old subtitles. +.TP +.B \fB\-\-sub\-ass\fP, \fB\-\-no\-sub\-ass\fP +Render ASS subtitles natively (enabled by default). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This has been deprecated by \fB\-\-sub\-ass\-override=strip\fP\&. You also +may need \fB\-\-embeddedfonts=no\fP to get the same behavior. Also, +using \fB\-\-sub\-ass\-override=style\fP should give better results +without breaking subtitles too much. +.UNINDENT +.UNINDENT +.sp +If \fB\-\-no\-sub\-ass\fP is specified, all tags and style declarations are +stripped and ignored on display. The subtitle renderer uses the font style +as specified by the \fB\-\-sub\-\fP options instead. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Using \fB\-\-no\-sub\-ass\fP may lead to incorrect or completely broken +rendering of ASS/SSA subtitles. It can sometimes be useful to forcibly +override the styling of ASS subtitles, but should be avoided in general. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-auto=<no|exact|fuzzy|all>\fP, \fB\-\-no\-sub\-auto\fP +Load additional subtitle files matching the video filename. The parameter +specifies how external subtitle files are matched. \fBexact\fP is enabled by +default. +.INDENT 7.0 +.TP +.B no +Don\(aqt automatically load external subtitle files. +.TP +.B exact +Load the media filename with subtitle file extension (default). +.TP +.B fuzzy +Load all subs containing media filename. +.TP +.B all +Load all subs in the current and \fB\-\-sub\-file\-paths\fP directories. +.UNINDENT +.TP +.B \fB\-\-sub\-codepage=<codepage>\fP +You can use this option to specify the subtitle codepage. uchardet will be +used to guess the charset. (If mpv was not compiled with uchardet, then +\fButf\-8\fP is the effective default.) +.sp +The default value for this option is \fBauto\fP, which enables autodetection. +.sp +The following steps are taken to determine the final codepage, in order: +.INDENT 7.0 +.IP \(bu 2 +if the specific codepage has a \fB+\fP, use that codepage +.IP \(bu 2 +if the data looks like UTF\-8, assume it is UTF\-8 +.IP \(bu 2 +if \fB\-\-sub\-codepage\fP is set to a specific codepage, use that +.IP \(bu 2 +run uchardet, and if successful, use that +.IP \(bu 2 +otherwise, use \fBUTF\-8\-BROKEN\fP +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-sub\-codepage=latin2\fP Use Latin 2 if input is not UTF\-8. +.IP \(bu 2 +\fB\-\-sub\-codepage=+cp1250\fP Always force recoding to cp1250. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +The pseudo codepage \fBUTF\-8\-BROKEN\fP is used internally. If it\(aqs set, +subtitles are interpreted as UTF\-8 with "Latin 1" as fallback for bytes +which are not valid UTF\-8 sequences. iconv is never involved in this mode. +.sp +This option changed in mpv 0.23.0. Support for the old syntax was fully +removed in mpv 0.24.0. +.TP +.B \fB\-\-sub\-fix\-timing=<yes|no>\fP +Adjust subtitle timing is to remove minor gaps or overlaps between +subtitles (if the difference is smaller than 210 ms, the gap or overlap +is removed). +.TP +.B \fB\-\-sub\-forced\-only\fP +Display only forced subtitles for the DVD subtitle stream selected by e.g. +\fB\-\-slang\fP\&. +.TP +.B \fB\-\-sub\-fps=<rate>\fP +Specify the framerate of the subtitle file (default: video fps). Affects +text subtitles only. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fB<rate>\fP > video fps speeds the subtitles up for frame\-based +subtitle files and slows them down for time\-based ones. +.UNINDENT +.UNINDENT +.sp +See also: \fB\-\-sub\-speed\fP\&. +.TP +.B \fB\-\-sub\-gauss=<0.0\-3.0>\fP +Apply Gaussian blur to image subtitles (default: 0). This can help to make +pixelated DVD/Vobsubs look nicer. A value other than 0 also switches to +software subtitle scaling. Might be slow. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Never applied to text subtitles. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-gray\fP +Convert image subtitles to grayscale. Can help to make yellow DVD/Vobsubs +look nicer. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Never applied to text subtitles. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-paths=<path1:path2:...>\fP +Deprecated, use \fB\-\-sub\-file\-paths\fP\&. +.TP +.B \fB\-\-sub\-file\-paths=<path\-list>\fP +Specify extra directories to search for subtitles matching the video. +Multiple directories can be separated by ":" (";" on Windows). +Paths can be relative or absolute. Relative paths are interpreted relative +to video file directory. +If the file is a URL, only absolute paths and \fBsub\fP configuration +subdirectory will be scanned. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +Assuming that \fB/path/to/video/video.avi\fP is played and +\fB\-\-sub\-file\-paths=sub:subtitles\fP is specified, mpv +searches for subtitle files in these directories: +.INDENT 0.0 +.IP \(bu 2 +\fB/path/to/video/\fP +.IP \(bu 2 +\fB/path/to/video/sub/\fP +.IP \(bu 2 +\fB/path/to/video/subtitles/\fP +.IP \(bu 2 +the \fBsub\fP configuration subdirectory (usually \fB~/.config/mpv/sub/\fP) +.UNINDENT +.UNINDENT +.UNINDENT +.sp +This is a list option. See \fI\%List Options\fP for details. +.TP +.B \fB\-\-sub\-visibility\fP, \fB\-\-no\-sub\-visibility\fP +Can be used to disable display of subtitles, but still select and decode +them. +.TP +.B \fB\-\-sub\-clear\-on\-seek\fP +(Obscure, rarely useful.) Can be used to play broken mkv files with +duplicate ReadOrder fields. ReadOrder is the first field in a +Matroska\-style ASS subtitle packets. It should be unique, and libass +uses it for fast elimination of duplicates. This option disables caching +of subtitles across seeks, so after a seek libass can\(aqt eliminate subtitle +packets with the same ReadOrder as earlier packets. +.TP +.B \fB\-\-teletext\-page=<1\-999>\fP +This works for \fBdvb_teletext\fP subtitle streams, and if FFmpeg has been +compiled with support for it. +.TP +.B \fB\-\-sub\-font=<name>\fP +Specify font to use for subtitles that do not themselves +specify a particular font. The default is \fBsans\-serif\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-sub\-font=\(aqBitstream Vera Sans\(aq\fP +.IP \(bu 2 +\fB\-\-sub\-font=\(aqComic Sans MS\(aq\fP +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +The \fB\-\-sub\-font\fP option (and many other style related \fB\-\-sub\-\fP +options) are ignored when ASS\-subtitles are rendered, unless the +\fB\-\-no\-sub\-ass\fP option is specified. +.sp +This used to support fontconfig patterns. Starting with libass 0.13.0, +this stopped working. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-font\-size=<size>\fP +Specify the sub font size. The unit is the size in scaled pixels at a +window height of 720. The actual pixel size is scaled with the window +height: if the window height is larger or smaller than 720, the actual size +of the text increases or decreases as well. +.sp +Default: 55. +.TP +.B \fB\-\-sub\-back\-color=<color>\fP +See \fB\-\-sub\-color\fP\&. Color used for sub text background. You can use +\fB\-\-sub\-shadow\-offset\fP to change its size relative to the text. +.TP +.B \fB\-\-sub\-blur=<0..20.0>\fP +Gaussian blur factor. 0 means no blur applied (default). +.TP +.B \fB\-\-sub\-bold=<yes|no>\fP +Format text on bold. +.TP +.B \fB\-\-sub\-italic=<yes|no>\fP +Format text on italic. +.TP +.B \fB\-\-sub\-border\-color=<color>\fP +See \fB\-\-sub\-color\fP\&. Color used for the sub font border. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +ignored when \fB\-\-sub\-back\-color\fP is +specified (or more exactly: when that option is not set to completely +transparent). +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-border\-size=<size>\fP +Size of the sub font border in scaled pixels (see \fB\-\-sub\-font\-size\fP +for details). A value of 0 disables borders. +.sp +Default: 3. +.TP +.B \fB\-\-sub\-color=<color>\fP +Specify the color used for unstyled text subtitles. +.sp +The color is specified in the form \fBr/g/b\fP, where each color component +is specified as number in the range 0.0 to 1.0. It\(aqs also possible to +specify the transparency by using \fBr/g/b/a\fP, where the alpha value 0 +means fully transparent, and 1.0 means opaque. If the alpha component is +not given, the color is 100% opaque. +.sp +Passing a single number to the option sets the sub to gray, and the form +\fBgray/a\fP lets you specify alpha additionally. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-sub\-color=1.0/0.0/0.0\fP set sub to opaque red +.IP \(bu 2 +\fB\-\-sub\-color=1.0/0.0/0.0/0.75\fP set sub to opaque red with 75% alpha +.IP \(bu 2 +\fB\-\-sub\-color=0.5/0.75\fP set sub to 50% gray with 75% alpha +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Alternatively, the color can be specified as a RGB hex triplet in the form +\fB#RRGGBB\fP, where each 2\-digit group expresses a color value in the +range 0 (\fB00\fP) to 255 (\fBFF\fP). For example, \fB#FF0000\fP is red. +This is similar to web colors. Alpha is given with \fB#AARRGGBB\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-sub\-color=\(aq#FF0000\(aq\fP set sub to opaque red +.IP \(bu 2 +\fB\-\-sub\-color=\(aq#C0808080\(aq\fP set sub to 50% gray with 75% alpha +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-sub\-margin\-x=<size>\fP +Left and right screen margin for the subs in scaled pixels (see +\fB\-\-sub\-font\-size\fP for details). +.sp +This option specifies the distance of the sub to the left, as well as at +which distance from the right border long sub text will be broken. +.sp +Default: 25. +.TP +.B \fB\-\-sub\-margin\-y=<size>\fP +Top and bottom screen margin for the subs in scaled pixels (see +\fB\-\-sub\-font\-size\fP for details). +.sp +This option specifies the vertical margins of unstyled text subtitles. +If you just want to raise the vertical subtitle position, use \fB\-\-sub\-pos\fP\&. +.sp +Default: 22. +.TP +.B \fB\-\-sub\-align\-x=<left|center|right>\fP +Control to which corner of the screen text subtitles should be +aligned to (default: \fBcenter\fP). +.sp +Never applied to ASS subtitles, except in \fB\-\-no\-sub\-ass\fP mode. Likewise, +this does not apply to image subtitles. +.TP +.B \fB\-\-sub\-align\-y=<top|center|bottom>\fP +Vertical position (default: \fBbottom\fP). +Details see \fB\-\-sub\-align\-x\fP\&. +.TP +.B \fB\-\-sub\-justify=<auto|left|center|right>\fP +Control how multi line subs are justified irrespective of where they +are aligned (default: \fBauto\fP which justifies as defined by +\fB\-\-sub\-align\-y\fP). +Left justification is recommended to make the subs easier to read +as it is easier for the eyes. +.TP +.B \fB\-\-sub\-ass\-justify=<yes|no>\fP +Applies justification as defined by \fB\-\-sub\-justify\fP on ASS subtitles +if \fB\-\-sub\-ass\-override\fP is not set to \fBno\fP\&. +Default: \fBno\fP\&. +.TP +.B \fB\-\-sub\-shadow\-color=<color>\fP +See \fB\-\-sub\-color\fP\&. Color used for sub text shadow. +.TP +.B \fB\-\-sub\-shadow\-offset=<size>\fP +Displacement of the sub text shadow in scaled pixels (see +\fB\-\-sub\-font\-size\fP for details). A value of 0 disables shadows. +.sp +Default: 0. +.TP +.B \fB\-\-sub\-spacing=<size>\fP +Horizontal sub font spacing in scaled pixels (see \fB\-\-sub\-font\-size\fP +for details). This value is added to the normal letter spacing. Negative +values are allowed. +.sp +Default: 0. +.TP +.B \fB\-\-sub\-filter\-sdh=<yes|no>\fP +Applies filter removing subtitle additions for the deaf or hard\-of\-hearing (SDH). +This is intended for English, but may in part work for other languages too. +The intention is that it can be always enabled so may not remove +all parts added. +It removes speaker labels (like MAN:), upper case text in parentheses and +any text in brackets. +.sp +Default: \fBno\fP\&. +.TP +.B \fB\-\-sub\-filter\-sdh\-harder=<yes|no>\fP +Do harder SDH filtering (if enabled by \fB\-\-sub\-filter\-sdh\fP). +Will also remove speaker labels and text within parentheses using both +lower and upper case letters. +.sp +Default: \fBno\fP\&. +.TP +.B \fB\-\-sub\-create\-cc\-track=<yes|no>\fP +For every video stream, create a closed captions track (default: no). The +only purpose is to make the track available for selection at the start of +playback, instead of creating it lazily. This applies only to +\fBATSC A53 Part 4 Closed Captions\fP (displayed by mpv as subtitle tracks +using the codec \fBeia_608\fP). The CC track is marked "default" and selected +according to the normal subtitle track selection rules. You can then use +\fB\-\-sid\fP to explicitly select the correct track too. +.sp +If the video stream contains no closed captions, or if no video is being +decoded, the CC track will remain empty and will not show any text. +.TP +.B \fB\-\-sub\-font\-provider=<auto|none|fontconfig>\fP +Which libass font provider backend to use (default: auto). \fBauto\fP will +attempt to use the native font provider: fontconfig on Linux, CoreText on +OSX, DirectWrite on Windows. \fBfontconfig\fP forces fontconfig, if libass +was built with support (if not, it behaves like \fBnone\fP). +.sp +The \fBnone\fP font provider effectively disables system fonts. It will still +attempt to use embedded fonts (unless \fB\-\-embeddedfonts=no\fP is set; this is +the same behavior as with all other font providers), \fBsubfont.ttf\fP if +provided, and fonts in the \fBfonts\fP sub\-directory if provided. (The +fallback is more strict than that of other font providers, and if a font +name does not match, it may prefer not to render any text that uses the +missing font.) +.UNINDENT +.SS Window +.INDENT 0.0 +.TP +.B \fB\-\-title=<string>\fP +Set the window title. This is used for the video window, and if possible, +also sets the audio stream title. +.sp +Properties are expanded. (See \fI\%Property Expansion\fP\&.) +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +There is a danger of this causing significant CPU usage, depending on +the properties used. Changing the window title is often a slow +operation, and if the title changes every frame, playback can be ruined. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-screen=<default|0\-32>\fP +In multi\-monitor configurations (i.e. a single desktop that spans across +multiple displays), this option tells mpv which screen to display the +video on. +.INDENT 7.0 +.INDENT 3.5 +.IP "Note (X11)" +.sp +This option does not work properly with all window managers. In these +cases, you can try to use \fB\-\-geometry\fP to position the window +explicitly. It\(aqs also possible that the window manager provides native +features to control which screens application windows should use. +.UNINDENT +.UNINDENT +.sp +See also \fB\-\-fs\-screen\fP\&. +.TP +.B \fB\-\-fullscreen\fP, \fB\-\-fs\fP +Fullscreen playback. +.TP +.B \fB\-\-fs\-screen=<all|current|0\-32>\fP +In multi\-monitor configurations (i.e. a single desktop that spans across +multiple displays), this option tells mpv which screen to go fullscreen to. +If \fBdefault\fP is provided mpv will fallback on using the behavior +depending on what the user provided with the \fBscreen\fP option. +.INDENT 7.0 +.INDENT 3.5 +.IP "Note (X11)" +.sp +This option works properly only with window managers which +understand the EWMH \fB_NET_WM_FULLSCREEN_MONITORS\fP hint. +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Note (OS X)" +.sp +\fBall\fP does not work on OS X and will behave like \fBcurrent\fP\&. +.UNINDENT +.UNINDENT +.sp +See also \fB\-\-screen\fP\&. +.TP +.B \fB\-\-keep\-open=<yes|no|always>\fP +Do not terminate when playing or seeking beyond the end of the file, and +there is not next file to be played (and \fB\-\-loop\fP is not used). +Instead, pause the player. When trying to seek beyond end of the file, the +player will attempt to seek to the last frame. +.sp +Normally, this will act like \fBset pause yes\fP on EOF, unless the +\fB\-\-keep\-open\-pause=no\fP option is set. +.sp +The following arguments can be given: +.INDENT 7.0 +.TP +.B no +If the current file ends, go to the next file or terminate. +(Default.) +.TP +.B yes +Don\(aqt terminate if the current file is the last playlist entry. +Equivalent to \fB\-\-keep\-open\fP without arguments. +.TP +.B always +Like \fByes\fP, but also applies to files before the last playlist +entry. This means playback will never automatically advance to +the next file. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This option is not respected when using \fB\-\-frames\fP\&. Explicitly +skipping to the next file if the binding uses \fBforce\fP will terminate +playback as well. +.sp +Also, if errors or unusual circumstances happen, the player can quit +anyway. +.UNINDENT +.UNINDENT +.sp +Since mpv 0.6.0, this doesn\(aqt pause if there is a next file in the playlist, +or the playlist is looped. Approximately, this will pause when the player +would normally exit, but in practice there are corner cases in which this +is not the case (e.g. \fBmpv \-\-keep\-open file.mkv /dev/null\fP will play +file.mkv normally, then fail to open \fB/dev/null\fP, then exit). (In +mpv 0.8.0, \fBalways\fP was introduced, which restores the old behavior.) +.TP +.B \fB\-\-keep\-open\-pause=<yes|no>\fP +If set to \fBno\fP, instead of pausing when \fB\-\-keep\-open\fP is active, just +stop at end of file and continue playing forward when you seek backwards +until end where it stops again. Default: \fByes\fP\&. +.TP +.B \fB\-\-image\-display\-duration=<seconds|inf>\fP +If the current file is an image, play the image for the given amount of +seconds (default: 1). \fBinf\fP means the file is kept open forever (until +the user stops playback manually). +.sp +Unlike \fB\-\-keep\-open\fP, the player is not paused, but simply continues +playback until the time has elapsed. (It should not use any resources +during "playback".) +.sp +This affects image files, which are defined as having only 1 video frame +and no audio. The player may recognize certain non\-images as images, for +example if \fB\-\-length\fP is used to reduce the length to 1 frame, or if +you seek to the last frame. +.sp +This option does not affect the framerate used for \fBmf://\fP or +\fB\-\-merge\-files\fP\&. For that, use \fB\-\-mf\-fps\fP instead. +.sp +Setting \fB\-\-image\-display\-duration\fP hides the OSC and does not track +playback time on the command\-line output, and also does not duplicate +the image frame when encoding. To force the player into "dumb mode" +and actually count out seconds, or to duplicate the image when +encoding, you need to use \fB\-\-demuxer=lavf \-\-demuxer\-lavf\-o=loop=1\fP, +and use \fB\-\-length\fP or \fB\-\-frames\fP to stop after a particular time. +.TP +.B \fB\-\-force\-window=<yes|no|immediate>\fP +Create a video output window even if there is no video. This can be useful +when pretending that mpv is a GUI application. Currently, the window +always has the size 640x480, and is subject to \fB\-\-geometry\fP, +\fB\-\-autofit\fP, and similar options. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +The window is created only after initialization (to make sure default +window placement still works if the video size is different from the +\fB\-\-force\-window\fP default window size). This can be a problem if +initialization doesn\(aqt work perfectly, such as when opening URLs with +bad network connection, or opening broken video files. The \fBimmediate\fP +mode can be used to create the window always on program start, but this +may cause other issues. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-taskbar\-progress\fP, \fB\-\-no\-taskbar\-progress\fP +(Windows only) +Enable/disable playback progress rendering in taskbar (Windows 7 and above). +.sp +Enabled by default. +.TP +.B \fB\-\-snap\-window\fP +(Windows only) Snap the player window to screen edges. +.TP +.B \fB\-\-ontop\fP +Makes the player window stay on top of other windows. +.sp +On Windows, if combined with fullscreen mode, this causes mpv to be +treated as exclusive fullscreen window that bypasses the Desktop Window +Manager. +.TP +.B \fB\-\-ontop\-level=<window|system|level>\fP +(OS X only) +Sets the level of an ontop window (default: window). +.INDENT 7.0 +.TP +.B window +On top of all other windows. +.TP +.B system +On top of system elements like Taskbar, Menubar and Dock. +.TP +.B level +A level as integer. +.UNINDENT +.TP +.B \fB\-\-border\fP, \fB\-\-no\-border\fP +Play video with window border and decorations. Since this is on by +default, use \fB\-\-no\-border\fP to disable the standard window decorations. +.TP +.B \fB\-\-fit\-border\fP, \fB\-\-no\-fit\-border\fP +(Windows only) Fit the whole window with border and decorations on the +screen. Since this is on by default, use \fB\-\-no\-fit\-border\fP to make mpv +try to only fit client area with video on the screen. This behavior only +applied to window/video with size exceeding size of the screen. +.TP +.B \fB\-\-on\-all\-workspaces\fP +(X11 only) +Show the video window on all virtual desktops. +.TP +.B \fB\-\-geometry=<[W[xH]][+\-x+\-y]>\fP, \fB\-\-geometry=<x:y>\fP +Adjust the initial window position or size. \fBW\fP and \fBH\fP set the window +size in pixels. \fBx\fP and \fBy\fP set the window position, measured in pixels +from the top\-left corner of the screen to the top\-left corner of the image +being displayed. If a percentage sign (\fB%\fP) is given after the argument, +it turns the value into a percentage of the screen size in that direction. +Positions are specified similar to the standard X11 \fB\-\-geometry\fP option +format, in which e.g. +10\-50 means "place 10 pixels from the left border and +50 pixels from the lower border" and "\-\-20+\-10" means "place 20 pixels +beyond the right and 10 pixels beyond the top border". +.sp +If an external window is specified using the \fB\-\-wid\fP option, this +option is ignored. +.sp +The coordinates are relative to the screen given with \fB\-\-screen\fP for the +video output drivers that fully support \fB\-\-screen\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Generally only supported by GUI VOs. Ignored for encoding. +.UNINDENT +.UNINDENT +.\" admonition: Note (OS X) +.\" +.\" On Mac OS X the origin of the screen coordinate system is located on the +.\" bottom-left corner. For instance, ``0:0`` will place the window at the +.\" bottom-left of the screen. +. +.INDENT 7.0 +.INDENT 3.5 +.IP "Note (X11)" +.sp +This option does not work properly with all window managers. +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fB50:40\fP +Places the window at x=50, y=40. +.TP +.B \fB50%:50%\fP +Places the window in the middle of the screen. +.TP +.B \fB100%:100%\fP +Places the window at the bottom right corner of the screen. +.TP +.B \fB50%\fP +Sets the window width to half the screen width. Window height is set +so that the window has the video aspect ratio. +.TP +.B \fB50%x50%\fP +Forces the window width and height to half the screen width and +height. Will show black borders to compensate for the video aspect +ratio (with most VOs and without \fB\-\-no\-keepaspect\fP). +.TP +.B \fB50%+10+10\fP +Sets the window to half the screen widths, and positions it 10 +pixels below/left of the top left corner of the screen. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +See also \fB\-\-autofit\fP and \fB\-\-autofit\-larger\fP for fitting the window into +a given size without changing aspect ratio. +.TP +.B \fB\-\-autofit=<[W[xH]]>\fP +Set the initial window size to a maximum size specified by \fBWxH\fP, without +changing the window\(aqs aspect ratio. The size is measured in pixels, or if +a number is followed by a percentage sign (\fB%\fP), in percents of the +screen size. +.sp +This option never changes the aspect ratio of the window. If the aspect +ratio mismatches, the window\(aqs size is reduced until it fits into the +specified size. +.sp +Window position is not taken into account, nor is it modified by this +option (the window manager still may place the window differently depending +on size). Use \fB\-\-geometry\fP to change the window position. Its effects +are applied after this option. +.sp +See \fB\-\-geometry\fP for details how this is handled with multi\-monitor +setups. +.sp +Use \fB\-\-autofit\-larger\fP instead if you just want to limit the maximum size +of the window, rather than always forcing a window size. +.sp +Use \fB\-\-geometry\fP if you want to force both window width and height to a +specific size. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Generally only supported by GUI VOs. Ignored for encoding. +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fB70%\fP +Make the window width 70% of the screen size, keeping aspect ratio. +.TP +.B \fB1000\fP +Set the window width to 1000 pixels, keeping aspect ratio. +.TP +.B \fB70%x60%\fP +Make the window as large as possible, without being wider than 70% +of the screen width, or higher than 60% of the screen height. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-autofit\-larger=<[W[xH]]>\fP +This option behaves exactly like \fB\-\-autofit\fP, except the window size is +only changed if the window would be larger than the specified size. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.TP +.B \fB90%x80%\fP +If the video is larger than 90% of the screen width or 80% of the +screen height, make the window smaller until either its width is 90% +of the screen, or its height is 80% of the screen. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-autofit\-smaller=<[W[xH]]>\fP +This option behaves exactly like \fB\-\-autofit\fP, except that it sets the +minimum size of the window (just as \fB\-\-autofit\-larger\fP sets the maximum). +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.TP +.B \fB500x500\fP +Make the window at least 500 pixels wide and 500 pixels high +(depending on the video aspect ratio, the width or height will be +larger than 500 in order to keep the aspect ratio the same). +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-window\-scale=<factor>\fP +Resize the video window to a multiple (or fraction) of the video size. This +option is applied before \fB\-\-autofit\fP and other options are applied (so +they override this option). +.sp +For example, \fB\-\-window\-scale=0.5\fP would show the window at half the +video size. +.TP +.B \fB\-\-cursor\-autohide=<number|no|always>\fP +Make mouse cursor automatically hide after given number of milliseconds. +\fBno\fP will disable cursor autohide. \fBalways\fP means the cursor will stay +hidden. +.TP +.B \fB\-\-cursor\-autohide\-fs\-only\fP +If this option is given, the cursor is always visible in windowed mode. In +fullscreen mode, the cursor is shown or hidden according to +\fB\-\-cursor\-autohide\fP\&. +.TP +.B \fB\-\-no\-fixed\-vo\fP, \fB\-\-fixed\-vo\fP +\fB\-\-no\-fixed\-vo\fP enforces closing and reopening the video window for +multiple files (one (un)initialization for each file). +.TP +.B \fB\-\-force\-rgba\-osd\-rendering\fP +Change how some video outputs render the OSD and text subtitles. This +does not change appearance of the subtitles and only has performance +implications. For VOs which support native ASS rendering (like \fBgpu\fP, +\fBvdpau\fP, \fBdirect3d\fP), this can be slightly faster or slower, +depending on GPU drivers and hardware. For other VOs, this just makes +rendering slower. +.TP +.B \fB\-\-force\-window\-position\fP +Forcefully move mpv\(aqs video output window to default location whenever +there is a change in video parameters, video stream or file. This used to +be the default behavior. Currently only affects X11 VOs. +.TP +.B \fB\-\-no\-keepaspect\fP, \fB\-\-keepaspect\fP +\fB\-\-no\-keepaspect\fP will always stretch the video to window size, and will +disable the window manager hints that force the window aspect ratio. +(Ignored in fullscreen mode.) +.TP +.B \fB\-\-no\-keepaspect\-window\fP, \fB\-\-keepaspect\-window\fP +\fB\-\-keepaspect\-window\fP (the default) will lock the window size to the +video aspect. \fB\-\-no\-keepaspect\-window\fP disables this behavior, and will +instead add black bars if window aspect and video aspect mismatch. Whether +this actually works depends on the VO backend. +(Ignored in fullscreen mode.) +.TP +.B \fB\-\-monitoraspect=<ratio>\fP +Set the aspect ratio of your monitor or TV screen. A value of 0 disables a +previous setting (e.g. in the config file). Overrides the +\fB\-\-monitorpixelaspect\fP setting if enabled. +.sp +See also \fB\-\-monitorpixelaspect\fP and \fB\-\-video\-aspect\-override\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-monitoraspect=4:3\fP or \fB\-\-monitoraspect=1.3333\fP +.IP \(bu 2 +\fB\-\-monitoraspect=16:9\fP or \fB\-\-monitoraspect=1.7777\fP +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-hidpi\-window\-scale\fP, \fB\-\-no\-hidpi\-window\-scale\fP +(OS X and X11 only) +Scale the window size according to the backing scale factor (default: yes). +On regular HiDPI resolutions the window opens with double the size but appears +as having the same size as on none\-HiDPI resolutions. This is the default OS X +behavior. +.TP +.B \fB\-\-native\-fs\fP, \fB\-\-no\-native\-fs\fP +(OS X only) +Uses the native fullscreen mechanism of the OS (default: yes). +.TP +.B \fB\-\-monitorpixelaspect=<ratio>\fP +Set the aspect of a single pixel of your monitor or TV screen (default: +1). A value of 1 means square pixels (correct for (almost?) all LCDs). See +also \fB\-\-monitoraspect\fP and \fB\-\-video\-aspect\-override\fP\&. +.TP +.B \fB\-\-stop\-screensaver\fP, \fB\-\-no\-stop\-screensaver\fP +Turns off the screensaver (or screen blanker and similar mechanisms) at +startup and turns it on again on exit (default: yes). The screensaver is +always re\-enabled when the player is paused. +.sp +This is not supported on all video outputs or platforms. Sometimes it is +implemented, but does not work (especially with Linux "desktops"). +.TP +.B \fB\-\-wid=<ID>\fP +This tells mpv to attach to an existing window. If a VO is selected that +supports this option, it will use that window for video output. mpv will +scale the video to the size of this window, and will add black bars to +compensate if the aspect ratio of the video is different. +.sp +On X11, the ID is interpreted as a \fBWindow\fP on X11. Unlike +MPlayer/mplayer2, mpv always creates its own window, and sets the wid +window as parent. The window will always be resized to cover the parent +window fully. The value \fB0\fP is interpreted specially, and mpv will +draw directly on the root window. +.sp +On win32, the ID is interpreted as \fBHWND\fP\&. Pass it as value cast to +\fBintptr_t\fP\&. mpv will create its own window, and set the wid window as +parent, like with X11. +.sp +On OSX/Cocoa, the ID is interpreted as \fBNSView*\fP\&. Pass it as value cast +to \fBintptr_t\fP\&. mpv will create its own sub\-view. Because OSX does not +support window embedding of foreign processes, this works only with libmpv, +and will crash when used from the command line. +.sp +On Android, the ID is interpreted as \fBandroid.view.Surface\fP\&. Pass it as a +value cast to \fBintptr_t\fP\&. Use with \fB\-\-vo=mediacodec_embed\fP and +\fB\-\-hwdec=mediacodec\fP for direct rendering using MediaCodec, or with +\fB\-\-vo=gpu \-\-gpu\-context=android\fP (with or without \fB\-\-hwdec=mediacodec\-copy\fP). +.TP +.B \fB\-\-no\-window\-dragging\fP +Don\(aqt move the window when clicking on it and moving the mouse pointer. +.TP +.B \fB\-\-x11\-name\fP +Set the window class name for X11\-based video output methods. +.TP +.B \fB\-\-x11\-netwm=<yes|no|auto>\fP +(X11 only) +Control the use of NetWM protocol features. +.sp +This may or may not help with broken window managers. This provides some +functionality that was implemented by the now removed \fB\-\-fstype\fP option. +Actually, it is not known to the developers to which degree this option +was needed, so feedback is welcome. +.sp +Specifically, \fByes\fP will force use of NetWM fullscreen support, even if +not advertised by the WM. This can be useful for WMs that are broken on +purpose, like XMonad. (XMonad supposedly doesn\(aqt advertise fullscreen +support, because Flash uses it. Apparently, applications which want to +use fullscreen anyway are supposed to either ignore the NetWM support hints, +or provide a workaround. Shame on XMonad for deliberately breaking X +protocols (as if X isn\(aqt bad enough already). +.sp +By default, NetWM support is autodetected (\fBauto\fP). +.sp +This option might be removed in the future. +.TP +.B \fB\-\-x11\-bypass\-compositor=<yes|no|fs\-only|never>\fP +If set to \fByes\fP, then ask the compositor to unredirect the mpv window +(default: \fBfs\-only\fP). This uses the \fB_NET_WM_BYPASS_COMPOSITOR\fP hint. +.sp +\fBfs\-only\fP asks the window manager to disable the compositor only in +fullscreen mode. +.sp +\fBno\fP sets \fB_NET_WM_BYPASS_COMPOSITOR\fP to 0, which is the default value +as declared by the EWMH specification, i.e. no change is done. +.sp +\fBnever\fP asks the window manager to never disable the compositor. +.UNINDENT +.SS Disc Devices +.INDENT 0.0 +.TP +.B \fB\-\-cdrom\-device=<path>\fP +Specify the CD\-ROM device (default: \fB/dev/cdrom\fP). +.TP +.B \fB\-\-dvd\-device=<path>\fP +Specify the DVD device or .iso filename (default: \fB/dev/dvd\fP). You can +also specify a directory that contains files previously copied directly +from a DVD (with e.g. vobcopy). +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +\fBmpv dvd:// \-\-dvd\-device=/path/to/dvd/\fP +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-bluray\-device=<path>\fP +(Blu\-ray only) +Specify the Blu\-ray disc location. Must be a directory with Blu\-ray +structure. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +\fBmpv bd:// \-\-bluray\-device=/path/to/bd/\fP +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-cdda\-...\fP +These options can be used to tune the CD Audio reading feature of mpv. +.TP +.B \fB\-\-cdda\-speed=<value>\fP +Set CD spin speed. +.TP +.B \fB\-\-cdda\-paranoia=<0\-2>\fP +Set paranoia level. Values other than 0 seem to break playback of +anything but the first track. +.INDENT 7.0 +.TP +.B 0 +disable checking (default) +.TP +.B 1 +overlap checking only +.TP +.B 2 +full data correction and verification +.UNINDENT +.TP +.B \fB\-\-cdda\-sector\-size=<value>\fP +Set atomic read size. +.TP +.B \fB\-\-cdda\-overlap=<value>\fP +Force minimum overlap search during verification to <value> sectors. +.TP +.B \fB\-\-cdda\-toc\-bias\fP +Assume that the beginning offset of track 1 as reported in the TOC +will be addressed as LBA 0. Some discs need this for getting track +boundaries correctly. +.TP +.B \fB\-\-cdda\-toc\-offset=<value>\fP +Add \fB<value>\fP sectors to the values reported when addressing tracks. +May be negative. +.TP +.B \fB\-\-cdda\-skip=<yes|no>\fP +(Never) accept imperfect data reconstruction. +.TP +.B \fB\-\-cdda\-cdtext=<yes|no>\fP +Print CD text. This is disabled by default, because it ruins performance +with CD\-ROM drives for unknown reasons. +.TP +.B \fB\-\-dvd\-speed=<speed>\fP +Try to limit DVD speed (default: 0, no change). DVD base speed is 1385 +kB/s, so an 8x drive can read at speeds up to 11080 kB/s. Slower speeds +make the drive more quiet. For watching DVDs, 2700 kB/s should be quiet and +fast enough. mpv resets the speed to the drive default value on close. +Values of at least 100 mean speed in kB/s. Values less than 100 mean +multiples of 1385 kB/s, i.e. \fB\-\-dvd\-speed=8\fP selects 11080 kB/s. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +You need write access to the DVD device to change the speed. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-dvd\-angle=<ID>\fP +Some DVDs contain scenes that can be viewed from multiple angles. +This option tells mpv which angle to use (default: 1). +.UNINDENT +.SS Equalizer +.INDENT 0.0 +.TP +.B \fB\-\-brightness=<\-100\-100>\fP +Adjust the brightness of the video signal (default: 0). Not supported by +all video output drivers. +.TP +.B \fB\-\-contrast=<\-100\-100>\fP +Adjust the contrast of the video signal (default: 0). Not supported by all +video output drivers. +.TP +.B \fB\-\-saturation=<\-100\-100>\fP +Adjust the saturation of the video signal (default: 0). You can get +grayscale output with this option. Not supported by all video output +drivers. +.TP +.B \fB\-\-gamma=<\-100\-100>\fP +Adjust the gamma of the video signal (default: 0). Not supported by all +video output drivers. +.TP +.B \fB\-\-hue=<\-100\-100>\fP +Adjust the hue of the video signal (default: 0). You can get a colored +negative of the image with this option. Not supported by all video output +drivers. +.UNINDENT +.SS Demuxer +.INDENT 0.0 +.TP +.B \fB\-\-demuxer=<[+]name>\fP +Force demuxer type. Use a \(aq+\(aq before the name to force it; this will skip +some checks. Give the demuxer name as printed by \fB\-\-demuxer=help\fP\&. +.TP +.B \fB\-\-demuxer\-lavf\-analyzeduration=<value>\fP +Maximum length in seconds to analyze the stream properties. +.TP +.B \fB\-\-demuxer\-lavf\-probe\-info=<yes|no|auto|nostreams>\fP +Whether to probe stream information (default: auto). Technically, this +controls whether libavformat\(aqs \fBavformat_find_stream_info()\fP function +is called. Usually it\(aqs safer to call it, but it can also make startup +slower. +.sp +The \fBauto\fP choice (the default) tries to skip this for a few know\-safe +whitelisted formats, while calling it for everything else. +.sp +The \fBnostreams\fP choice only calls it if and only if the file seems to +contain no streams after opening (helpful in cases when calling the function +is needed to detect streams at all, such as with FLV files). +.TP +.B \fB\-\-demuxer\-lavf\-probescore=<1\-100>\fP +Minimum required libavformat probe score. Lower values will require +less data to be loaded (makes streams start faster), but makes file +format detection less reliable. Can be used to force auto\-detected +libavformat demuxers, even if libavformat considers the detection not +reliable enough. (Default: 26.) +.TP +.B \fB\-\-demuxer\-lavf\-allow\-mimetype=<yes|no>\fP +Allow deriving the format from the HTTP MIME type (default: yes). Set +this to no in case playing things from HTTP mysteriously fails, even +though the same files work from local disk. +.sp +This is default in order to reduce latency when opening HTTP streams. +.TP +.B \fB\-\-demuxer\-lavf\-format=<name>\fP +Force a specific libavformat demuxer. +.TP +.B \fB\-\-demuxer\-lavf\-hacks=<yes|no>\fP +By default, some formats will be handled differently from other formats +by explicitly checking for them. Most of these compensate for weird or +imperfect behavior from libavformat demuxers. Passing \fBno\fP disables +these. For debugging and testing only. +.TP +.B \fB\-\-demuxer\-lavf\-o=<key>=<value>[,<key>=<value>[,...]]\fP +Pass AVOptions to libavformat demuxer. +.sp +Note, a patch to make the \fIo=\fP unneeded and pass all unknown options +through the AVOption system is welcome. A full list of AVOptions can +be found in the FFmpeg manual. Note that some options may conflict +with mpv options. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +\fB\-\-demuxer\-lavf\-o=fflags=+ignidx\fP +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-demuxer\-lavf\-probesize=<value>\fP +Maximum amount of data to probe during the detection phase. In the +case of MPEG\-TS this value identifies the maximum number of TS packets +to scan. +.TP +.B \fB\-\-demuxer\-lavf\-buffersize=<value>\fP +Size of the stream read buffer allocated for libavformat in bytes +(default: 32768). Lowering the size could lower latency. Note that +libavformat might reallocate the buffer internally, or not fully use all +of it. +.TP +.B \fB\-\-demuxer\-lavf\-linearize\-timestamps=<yes|no|auto>\fP +Attempt to linearize timestamp resets in demuxed streams (default: auto). +This was tested only for single audio streams. It\(aqs unknown whether it +works correctly for video (but likely won\(aqt). Note that the implementation +is slightly incorrect either way, and will introduce a discontinuity by +about 1 codec frame size. +.sp +The \fBauto\fP mode enables this for OGG audio stream. This covers the common +and annoying case of OGG web radio streams. Some of these will reset +timestamps to 0 every time a new song begins. This breaks the mpv seekable +cache, which can\(aqt deal with timestamp resets. Note that FFmpeg/libavformat\(aqs +seeking API can\(aqt deal with this either; it\(aqs likely that if this option +breaks this even more, while if it\(aqs disabled, you can at least seek within +the first song in the stream. Well, you won\(aqt get anything useful either +way if the seek is outside of mpv\(aqs cache. +.TP +.B \fB\-\-demuxer\-mkv\-subtitle\-preroll=<yes|index|no>\fP, \fB\-\-mkv\-subtitle\-preroll\fP +Try harder to show embedded soft subtitles when seeking somewhere. Normally, +it can happen that the subtitle at the seek target is not shown due to how +some container file formats are designed. The subtitles appear only if +seeking before or exactly to the position a subtitle first appears. To +make this worse, subtitles are often timed to appear a very small amount +before the associated video frame, so that seeking to the video frame +typically does not demux the subtitle at that position. +.sp +Enabling this option makes the demuxer start reading data a bit before the +seek target, so that subtitles appear correctly. Note that this makes +seeking slower, and is not guaranteed to always work. It only works if the +subtitle is close enough to the seek target. +.sp +Works with the internal Matroska demuxer only. Always enabled for absolute +and hr\-seeks, and this option changes behavior with relative or imprecise +seeks only. +.sp +You can use the \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\fP option to specify +how much data the demuxer should pre\-read at most in order to find subtitle +packets that may overlap. Setting this to 0 will effectively disable this +preroll mechanism. Setting a very large value can make seeking very slow, +and an extremely large value would completely reread the entire file from +start to seek target on every seek \- seeking can become slower towards the +end of the file. The details are messy, and the value is actually rounded +down to the cluster with the previous video keyframe. +.sp +Some files, especially files muxed with newer mkvmerge versions, have +information embedded that can be used to determine what subtitle packets +overlap with a seek target. In these cases, mpv will reduce the amount +of data read to a minimum. (Although it will still read \fIall\fP data between +the cluster that contains the first wanted subtitle packet, and the seek +target.) If the \fBindex\fP choice (which is the default) is specified, then +prerolling will be done only if this information is actually available. If +this method is used, the maximum amount of data to skip can be additionally +controlled by \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\-index\fP (it still uses +the value of the option without \fB\-index\fP if that is higher). +.sp +See also \fB\-\-hr\-seek\-demuxer\-offset\fP option. This option can achieve a +similar effect, but only if hr\-seek is active. It works with any demuxer, +but makes seeking much slower, as it has to decode audio and video data +instead of just skipping over it. +.sp +\fB\-\-mkv\-subtitle\-preroll\fP is a deprecated alias. +.TP +.B \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs=<value>\fP +See \fB\-\-demuxer\-mkv\-subtitle\-preroll\fP\&. +.TP +.B \fB\-\-demuxer\-mkv\-subtitle\-preroll\-secs\-index=<value>\fP +See \fB\-\-demuxer\-mkv\-subtitle\-preroll\fP\&. +.TP +.B \fB\-\-demuxer\-mkv\-probe\-video\-duration=<yes|no|full>\fP +When opening the file, seek to the end of it, and check what timestamp the +last video packet has, and report that as file duration. This is strictly +for compatibility with Haali only. In this mode, it\(aqs possible that opening +will be slower (especially when playing over http), or that behavior with +broken files is much worse. So don\(aqt use this option. +.sp +The \fByes\fP mode merely uses the index and reads a small number of blocks +from the end of the file. The \fBfull\fP mode actually traverses the entire +file and can make a reliable estimate even without an index present (such +as partial files). +.TP +.B \fB\-\-demuxer\-rawaudio\-channels=<value>\fP +Number of channels (or channel layout) if \fB\-\-demuxer=rawaudio\fP is used +(default: stereo). +.TP +.B \fB\-\-demuxer\-rawaudio\-format=<value>\fP +Sample format for \fB\-\-demuxer=rawaudio\fP (default: s16le). +Use \fB\-\-demuxer\-rawaudio\-format=help\fP to get a list of all formats. +.TP +.B \fB\-\-demuxer\-rawaudio\-rate=<value>\fP +Sample rate for \fB\-\-demuxer=rawaudio\fP (default: 44 kHz). +.TP +.B \fB\-\-demuxer\-rawvideo\-fps=<value>\fP +Rate in frames per second for \fB\-\-demuxer=rawvideo\fP (default: 25.0). +.TP +.B \fB\-\-demuxer\-rawvideo\-w=<value>\fP, \fB\-\-demuxer\-rawvideo\-h=<value>\fP +Image dimension in pixels for \fB\-\-demuxer=rawvideo\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +Play a raw YUV sample: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv sample\-720x576.yuv \-\-demuxer=rawvideo \e +\-\-demuxer\-rawvideo\-w=720 \-\-demuxer\-rawvideo\-h=576 +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-demuxer\-rawvideo\-format=<value>\fP +Color space (fourcc) in hex or string for \fB\-\-demuxer=rawvideo\fP +(default: \fBYV12\fP). +.TP +.B \fB\-\-demuxer\-rawvideo\-mp\-format=<value>\fP +Color space by internal video format for \fB\-\-demuxer=rawvideo\fP\&. Use +\fB\-\-demuxer\-rawvideo\-mp\-format=help\fP for a list of possible formats. +.TP +.B \fB\-\-demuxer\-rawvideo\-codec=<value>\fP +Set the video codec instead of selecting the rawvideo codec when using +\fB\-\-demuxer=rawvideo\fP\&. This uses the same values as codec names in +\fB\-\-vd\fP (but it does not accept decoder names). +.TP +.B \fB\-\-demuxer\-rawvideo\-size=<value>\fP +Frame size in bytes when using \fB\-\-demuxer=rawvideo\fP\&. +.TP +.B \fB\-\-demuxer\-cue\-codepage=<codepage>\fP +Specify the CUE sheet codepage. (See \fB\-\-sub\-codepage\fP for details.) +.TP +.B \fB\-\-demuxer\-max\-bytes=<bytesize>\fP +This controls how much the demuxer is allowed to buffer ahead. The demuxer +will normally try to read ahead as much as necessary, or as much is +requested with \fB\-\-demuxer\-readahead\-secs\fP\&. The option can be used to +restrict the maximum readahead. This limits excessive readahead in case of +broken files or desynced playback. The demuxer will stop reading additional +packets as soon as one of the limits is reached. (The limits still can be +slightly overstepped due to technical reasons.) +.sp +Set these limits higher if you get a packet queue overflow warning, and +you think normal playback would be possible with a larger packet queue. +.sp +See \fB\-\-list\-options\fP for defaults and value range. \fB<bytesize>\fP options +accept suffixes such as \fBKiB\fP and \fBMiB\fP\&. +.TP +.B \fB\-\-demuxer\-max\-back\-bytes=<bytesize>\fP +This controls how much past data the demuxer is allowed to preserve. This +is useful only if the \fB\-\-demuxer\-seekable\-cache\fP option is enabled. +Unlike the forward cache, there is no control how many seconds are actually +cached \- it will simply use as much memory this option allows. Setting this +option to 0 will strictly disable any back buffer, but this will lead to +the situation that the forward seek range starts after the current playback +position (as it removes past packets that are seek points). +.sp +If the end of the file is reached, the remaining unused forward buffer space +is "donated" to the backbuffer (unless the backbuffer size is set to 0). +This still limits the total cache usage to the sum of the forward and +backward cache, and effectively makes better use of the total allowed memory +budget. (The opposite does not happen: free backward buffer is never +"donated" to the forward buffer.) +.sp +Keep in mind that other buffers in the player (like decoders) will cause the +demuxer to cache "future" frames in the back buffer, which can skew the +impression about how much data the backbuffer contains. +.sp +See \fB\-\-list\-options\fP for defaults and value range. +.TP +.B \fB\-\-demuxer\-seekable\-cache=<yes|no|auto>\fP +This controls whether seeking can use the demuxer cache (default: auto). If +enabled, short seek offsets will not trigger a low level demuxer seek +(which means for example that slow network round trips or FFmpeg seek bugs +can be avoided). If a seek cannot happen within the cached range, a low +level seek will be triggered. Seeking outside of the cache will start a new +cached range, but can discard the old cache range if the demuxer exhibits +certain unsupported behavior. +.sp +Keep in mind that some events can flush the cache or force a low level +seek anyway, such as switching tracks, or attempting to seek before the +start or after the end of the file. +.sp +The special value \fBauto\fP means \fByes\fP in the same situation as +\fB\-\-cache\-secs\fP is used (i.e. when the stream appears to be a network +stream or the stream cache is enabled). +.TP +.B \fB\-\-demuxer\-thread=<yes|no>\fP +Run the demuxer in a separate thread, and let it prefetch a certain amount +of packets (default: yes). Having this enabled leads to smoother playback, +enables features like prefetching, and prevents that stuck network freezes +the player. On the other hand, it can add overhead, or the background +prefetching can hog CPU resources. +.sp +Disabling this option is not recommended. Use it for debugging only. +.TP +.B \fB\-\-demuxer\-termination\-timeout=<seconds>\fP +Number of seconds the player should wait to shutdown the demuxer (default: +0.1). The player will wait up to this much time before it closes the +stream layer forcefully. Forceful closing usually means the network I/O is +given no chance to close its connections gracefully (of course the OS can +still close TCP connections properly), and might result in annoying messages +being logged, and in some cases, confused remote servers. +.sp +This timeout is usually only applied when loading has finished properly. If +loading is aborted by the user, or in some corner cases like removing +external tracks sourced from network during playback, forceful closing is +always used. +.TP +.B \fB\-\-demuxer\-readahead\-secs=<seconds>\fP +If \fB\-\-demuxer\-thread\fP is enabled, this controls how much the demuxer +should buffer ahead in seconds (default: 1). As long as no packet has +a timestamp difference higher than the readahead amount relative to the +last packet returned to the decoder, the demuxer keeps reading. +.sp +Note that the \fB\-\-cache\-secs\fP option will override this value if a cache +is enabled, and the value is larger. +.sp +(This value tends to be fuzzy, because many file formats don\(aqt store linear +timestamps.) +.TP +.B \fB\-\-prefetch\-playlist=<yes|no>\fP +Prefetch next playlist entry while playback of the current entry is ending +(default: no). This merely opens the URL of the next playlist entry as soon +as the current URL is fully read. +.sp +This does \fBnot\fP work with URLs resolved by the \fByoutube\-dl\fP wrapper, +and it won\(aqt. +.sp +This does not affect HLS (\fB\&.m3u8\fP URLs) \- HLS prefetching depends on the +demuxer cache settings and is on by default. +.sp +This can give subtly wrong results if per\-file options are used, or if +options are changed in the time window between prefetching start and next +file played. +.sp +This can occasionally make wrong prefetching decisions. For example, it +can\(aqt predict whether you go backwards in the playlist, and assumes you +won\(aqt edit the playlist. +.sp +Highly experimental. +.TP +.B \fB\-\-force\-seekable=<yes|no>\fP +If the player thinks that the media is not seekable (e.g. playing from a +pipe, or it\(aqs an http stream with a server that doesn\(aqt support range +requests), seeking will be disabled. This option can forcibly enable it. +For seeks within the cache, there\(aqs a good chance of success. +.TP +.B \fB\-\-demuxer\-cache\-wait=<yes|no>\fP +Before starting playback, read data until either the end of the file was +reached, or the demuxer cache has reached maximum capacity. Only once this +is done, playback starts. This intentionally happens before the initial +seek triggered with \fB\-\-start\fP\&. This does not change any runtime behavior +after the initial caching. This option is useless if the file cannot be +cached completely. +.UNINDENT +.SS Input +.INDENT 0.0 +.TP +.B \fB\-\-native\-keyrepeat\fP +Use system settings for keyrepeat delay and rate, instead of +\fB\-\-input\-ar\-delay\fP and \fB\-\-input\-ar\-rate\fP\&. (Whether this applies +depends on the VO backend and how it handles keyboard input. Does not +apply to terminal input.) +.TP +.B \fB\-\-input\-ar\-delay\fP +Delay in milliseconds before we start to autorepeat a key (0 to disable). +.TP +.B \fB\-\-input\-ar\-rate\fP +Number of key presses to generate per second on autorepeat. +.TP +.B \fB\-\-input\-conf=<filename>\fP +Specify input configuration file other than the default location in the mpv +configuration directory (usually \fB~/.config/mpv/input.conf\fP). +.TP +.B \fB\-\-no\-input\-default\-bindings\fP +Disable mpv default (built\-in) key bindings. +.TP +.B \fB\-\-input\-cmdlist\fP +Prints all commands that can be bound to keys. +.TP +.B \fB\-\-input\-doubleclick\-time=<milliseconds>\fP +Time in milliseconds to recognize two consecutive button presses as a +double\-click (default: 300). +.TP +.B \fB\-\-input\-keylist\fP +Prints all keys that can be bound to commands. +.TP +.B \fB\-\-input\-key\-fifo\-size=<2\-65000>\fP +Specify the size of the FIFO that buffers key events (default: 7). If it +is too small, some events may be lost. The main disadvantage of setting it +to a very large value is that if you hold down a key triggering some +particularly slow command then the player may be unresponsive while it +processes all the queued commands. +.TP +.B \fB\-\-input\-test\fP +Input test mode. Instead of executing commands on key presses, mpv +will show the keys and the bound commands on the OSD. Has to be used +with a dummy video, and the normal ways to quit the player will not +work (key bindings that normally quit will be shown on OSD only, just +like any other binding). See \fI\%INPUT.CONF\fP\&. +.TP +.B \fB\-\-input\-file=<filename>\fP +Read commands from the given file. Mostly useful with a FIFO. Since +mpv 0.7.0 also understands JSON commands (see \fI\%JSON IPC\fP), but you can\(aqt +get replies or events. Use \fB\-\-input\-ipc\-server\fP for something +bi\-directional. On MS Windows, JSON commands are not available. +.sp +This can also specify a direct file descriptor with \fBfd://N\fP (UNIX only). +In this case, JSON replies will be written if the FD is writable. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +When the given file is a FIFO mpv opens both ends, so you can do several +\fIecho "seek 10" > mp_pipe\fP and the pipe will stay valid. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-input\-terminal\fP, \fB\-\-no\-input\-terminal\fP +\fB\-\-no\-input\-terminal\fP prevents the player from reading key events from +standard input. Useful when reading data from standard input. This is +automatically enabled when \fB\-\fP is found on the command line. There are +situations where you have to set it manually, e.g. if you open +\fB/dev/stdin\fP (or the equivalent on your system), use stdin in a playlist +or intend to read from stdin later on via the loadfile or loadlist input +commands. +.TP +.B \fB\-\-input\-ipc\-server=<filename>\fP +Enable the IPC support and create the listening socket at the given path. +.sp +On Linux and Unix, the given path is a regular filesystem path. On Windows, +named pipes are used, so the path refers to the pipe namespace +(\fB\e\e.\epipe\e<name>\fP). If the \fB\e\e.\epipe\e\fP prefix is missing, mpv will add +it automatically before creating the pipe, so +\fB\-\-input\-ipc\-server=/tmp/mpv\-socket\fP and +\fB\-\-input\-ipc\-server=\e\e.\epipe\etmp\empv\-socket\fP are equivalent for IPC on +Windows. +.sp +See \fI\%JSON IPC\fP for details. +.TP +.B \fB\-\-input\-appleremote=<yes|no>\fP +(OS X only) +Enable/disable Apple Remote support. Enabled by default (except for libmpv). +.TP +.B \fB\-\-input\-gamepad=<yes|no>\fP +Enable/disable SDL2 Gamepad support. Enabled by default (except for libmpv). +.TP +.B \fB\-\-input\-cursor\fP, \fB\-\-no\-input\-cursor\fP +Permit mpv to receive pointer events reported by the video output +driver. Necessary to use the OSC, or to select the buttons in DVD menus. +Support depends on the VO in use. +.TP +.B \fB\-\-input\-media\-keys=<yes|no>\fP +(OS X and Windows only) +Enable/disable media keys support. Enabled by default (except for libmpv). +.TP +.B \fB\-\-input\-right\-alt\-gr\fP, \fB\-\-no\-input\-right\-alt\-gr\fP +(Cocoa and Windows only) +Use the right Alt key as Alt Gr to produce special characters. If disabled, +count the right Alt as an Alt modifier key. Enabled by default. +.TP +.B \fB\-\-input\-vo\-keyboard=<yes|no>\fP +Disable all keyboard input on for VOs which can\(aqt participate in proper +keyboard input dispatching. May not affect all VOs. Generally useful for +embedding only. +.sp +On X11, a sub\-window with input enabled grabs all keyboard input as long +as it is 1. a child of a focused window, and 2. the mouse is inside of +the sub\-window. It can steal away all keyboard input from the +application embedding the mpv window, and on the other hand, the mpv +window will receive no input if the mouse is outside of the mpv window, +even though mpv has focus. Modern toolkits work around this weird X11 +behavior, but naively embedding foreign windows breaks it. +.sp +The only way to handle this reasonably is using the XEmbed protocol, which +was designed to solve these problems. GTK provides \fBGtkSocket\fP, which +supports XEmbed. Qt doesn\(aqt seem to provide anything working in newer +versions. +.sp +If the embedder supports XEmbed, input should work with default settings +and with this option disabled. Note that \fBinput\-default\-bindings\fP is +disabled by default in libmpv as well \- it should be enabled if you want +the mpv default key bindings. +.sp +(This option was renamed from \fB\-\-input\-x11\-keyboard\fP\&.) +.UNINDENT +.SS OSD +.INDENT 0.0 +.TP +.B \fB\-\-osc\fP, \fB\-\-no\-osc\fP +Whether to load the on\-screen\-controller (default: yes). +.TP +.B \fB\-\-no\-osd\-bar\fP, \fB\-\-osd\-bar\fP +Disable display of the OSD bar. +.sp +You can configure this on a per\-command basis in input.conf using \fBosd\-\fP +prefixes, see \fBInput Command Prefixes\fP\&. If you want to disable the OSD +completely, use \fB\-\-osd\-level=0\fP\&. +.TP +.B \fB\-\-osd\-on\-seek=<no,bar,msg,msg\-bar>\fP +Set what is displayed on the OSD during seeks. The default is \fBbar\fP\&. +.sp +You can configure this on a per\-command basis in input.conf using \fBosd\-\fP +prefixes, see \fBInput Command Prefixes\fP\&. +.TP +.B \fB\-\-osd\-duration=<time>\fP +Set the duration of the OSD messages in ms (default: 1000). +.TP +.B \fB\-\-osd\-font=<name>\fP +Specify font to use for OSD. The default is \fBsans\-serif\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-osd\-font=\(aqBitstream Vera Sans\(aq\fP +.IP \(bu 2 +\fB\-\-osd\-font=\(aqComic Sans MS\(aq\fP +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-osd\-font\-size=<size>\fP +Specify the OSD font size. See \fB\-\-sub\-font\-size\fP for details. +.sp +Default: 55. +.TP +.B \fB\-\-osd\-msg1=<string>\fP +Show this string as message on OSD with OSD level 1 (visible by default). +The message will be visible by default, and as long as no other message +covers it, and the OSD level isn\(aqt changed (see \fB\-\-osd\-level\fP). +Expands properties; see \fI\%Property Expansion\fP\&. +.TP +.B \fB\-\-osd\-msg2=<string>\fP +Similar to \fB\-\-osd\-msg1\fP, but for OSD level 2. If this is an empty string +(default), then the playback time is shown. +.TP +.B \fB\-\-osd\-msg3=<string>\fP +Similar to \fB\-\-osd\-msg1\fP, but for OSD level 3. If this is an empty string +(default), then the playback time, duration, and some more information is +shown. +.sp +This is used for the \fBshow\-progress\fP command (by default mapped to \fBP\fP), +and when seeking if enabled with \fB\-\-osd\-on\-seek\fP or by \fBosd\-\fP prefixes +in input.conf (see \fBInput Command Prefixes\fP). +.sp +\fB\-\-osd\-status\-msg\fP is a legacy equivalent (but with a minor difference). +.TP +.B \fB\-\-osd\-status\-msg=<string>\fP +Show a custom string during playback instead of the standard status text. +This overrides the status text used for \fB\-\-osd\-level=3\fP, when using the +\fBshow\-progress\fP command (by default mapped to \fBP\fP), and when seeking if +enabled with \fB\-\-osd\-on\-seek\fP or \fBosd\-\fP prefixes in input.conf (see +\fBInput Command Prefixes\fP). Expands properties. See \fI\%Property Expansion\fP\&. +.sp +This option has been replaced with \fB\-\-osd\-msg3\fP\&. The only difference is +that this option implicitly includes \fB${osd\-sym\-cc}\fP\&. This option is +ignored if \fB\-\-osd\-msg3\fP is not empty. +.TP +.B \fB\-\-osd\-playing\-msg=<string>\fP +Show a message on OSD when playback starts. The string is expanded for +properties, e.g. \fB\-\-osd\-playing\-msg=\(aqfile: ${filename}\(aq\fP will show the +message \fBfile:\fP followed by a space and the currently played filename. +.sp +See \fI\%Property Expansion\fP\&. +.TP +.B \fB\-\-osd\-bar\-align\-x=<\-1\-1>\fP +Position of the OSD bar. \-1 is far left, 0 is centered, 1 is far right. +Fractional values (like 0.5) are allowed. +.TP +.B \fB\-\-osd\-bar\-align\-y=<\-1\-1>\fP +Position of the OSD bar. \-1 is top, 0 is centered, 1 is bottom. +Fractional values (like 0.5) are allowed. +.TP +.B \fB\-\-osd\-bar\-w=<1\-100>\fP +Width of the OSD bar, in percentage of the screen width (default: 75). +A value of 50 means the bar is half the screen wide. +.TP +.B \fB\-\-osd\-bar\-h=<0.1\-50>\fP +Height of the OSD bar, in percentage of the screen height (default: 3.125). +.TP +.B \fB\-\-osd\-back\-color=<color>\fP +See \fB\-\-osd\-color\fP\&. Color used for OSD text background. +.TP +.B \fB\-\-osd\-blur=<0..20.0>\fP +Gaussian blur factor. 0 means no blur applied (default). +.TP +.B \fB\-\-osd\-bold=<yes|no>\fP +Format text on bold. +.TP +.B \fB\-\-osd\-italic=<yes|no>\fP +Format text on italic. +.TP +.B \fB\-\-osd\-border\-color=<color>\fP +See \fB\-\-osd\-color\fP\&. Color used for the OSD font border. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +ignored when \fB\-\-osd\-back\-color\fP is +specified (or more exactly: when that option is not set to completely +transparent). +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-osd\-border\-size=<size>\fP +Size of the OSD font border in scaled pixels (see \fB\-\-sub\-font\-size\fP +for details). A value of 0 disables borders. +.sp +Default: 3. +.TP +.B \fB\-\-osd\-color=<color>\fP +Specify the color used for OSD. +See \fB\-\-sub\-color\fP for details. +.TP +.B \fB\-\-osd\-fractions\fP +Show OSD times with fractions of seconds (in millisecond precision). Useful +to see the exact timestamp of a video frame. +.TP +.B \fB\-\-osd\-level=<0\-3>\fP +Specifies which mode the OSD should start in. +.INDENT 7.0 +.TP +.B 0 +OSD completely disabled (subtitles only) +.TP +.B 1 +enabled (shows up only on user interaction) +.TP +.B 2 +enabled + current time visible by default +.TP +.B 3 +enabled + \fB\-\-osd\-status\-msg\fP (current time and status by default) +.UNINDENT +.TP +.B \fB\-\-osd\-margin\-x=<size>\fP +Left and right screen margin for the OSD in scaled pixels (see +\fB\-\-sub\-font\-size\fP for details). +.sp +This option specifies the distance of the OSD to the left, as well as at +which distance from the right border long OSD text will be broken. +.sp +Default: 25. +.TP +.B \fB\-\-osd\-margin\-y=<size>\fP +Top and bottom screen margin for the OSD in scaled pixels (see +\fB\-\-sub\-font\-size\fP for details). +.sp +This option specifies the vertical margins of the OSD. +.sp +Default: 22. +.TP +.B \fB\-\-osd\-align\-x=<left|center|right>\fP +Control to which corner of the screen OSD should be +aligned to (default: \fBleft\fP). +.TP +.B \fB\-\-osd\-align\-y=<top|center|bottom>\fP +Vertical position (default: \fBtop\fP). +Details see \fB\-\-osd\-align\-x\fP\&. +.TP +.B \fB\-\-osd\-scale=<factor>\fP +OSD font size multiplier, multiplied with \fB\-\-osd\-font\-size\fP value. +.TP +.B \fB\-\-osd\-scale\-by\-window=<yes|no>\fP +Whether to scale the OSD with the window size (default: yes). If this is +disabled, \fB\-\-osd\-font\-size\fP and other OSD options that use scaled pixels +are always in actual pixels. The effect is that changing the window size +won\(aqt change the OSD font size. +.TP +.B \fB\-\-osd\-shadow\-color=<color>\fP +See \fB\-\-sub\-color\fP\&. Color used for OSD shadow. +.TP +.B \fB\-\-osd\-shadow\-offset=<size>\fP +Displacement of the OSD shadow in scaled pixels (see +\fB\-\-sub\-font\-size\fP for details). A value of 0 disables shadows. +.sp +Default: 0. +.TP +.B \fB\-\-osd\-spacing=<size>\fP +Horizontal OSD/sub font spacing in scaled pixels (see \fB\-\-sub\-font\-size\fP +for details). This value is added to the normal letter spacing. Negative +values are allowed. +.sp +Default: 0. +.TP +.B \fB\-\-video\-osd=<yes|no>\fP +Enabled OSD rendering on the video window (default: yes). This can be used +in situations where terminal OSD is preferred. If you just want to disable +all OSD rendering, use \fB\-\-osd\-level=0\fP\&. +.sp +It does not affect subtitles or overlays created by scripts (in particular, +the OSC needs to be disabled with \fB\-\-no\-osc\fP). +.sp +This option is somewhat experimental and could be replaced by another +mechanism in the future. +.TP +.B \fB\-\-osd\-font\-provider=<...>\fP +See \fB\-\-sub\-font\-provider\fP for details and accepted values. Note that +unlike subtitles, OSD never uses embedded fonts from media files. +.UNINDENT +.SS Screenshot +.INDENT 0.0 +.TP +.B \fB\-\-screenshot\-format=<type>\fP +Set the image file type used for saving screenshots. +.sp +Available choices: +.INDENT 7.0 +.TP +.B png +PNG +.TP +.B jpg +JPEG (default) +.TP +.B jpeg +JPEG (alias for jpg) +.TP +.B webp +WebP +.UNINDENT +.TP +.B \fB\-\-screenshot\-tag\-colorspace=<yes|no>\fP +Tag screenshots with the appropriate colorspace. +.sp +Note that not all formats are supported. +.sp +Default: \fBno\fP\&. +.TP +.B \fB\-\-screenshot\-high\-bit\-depth=<yes|no>\fP +If possible, write screenshots with a bit depth similar to the source +video (default: yes). This is interesting in particular for PNG, as this +sometimes triggers writing 16 bit PNGs with huge file sizes. This will also +include an unused alpha channel in the resulting files if 16 bit is used. +.TP +.B \fB\-\-screenshot\-template=<template>\fP +Specify the filename template used to save screenshots. The template +specifies the filename without file extension, and can contain format +specifiers, which will be substituted when taking a screenshot. +By default, the template is \fBmpv\-shot%n\fP, which results in filenames like +\fBmpv\-shot0012.png\fP for example. +.sp +The template can start with a relative or absolute path, in order to +specify a directory location where screenshots should be saved. +.sp +If the final screenshot filename points to an already existing file, the +file will not be overwritten. The screenshot will either not be saved, or if +the template contains \fB%n\fP, saved using different, newly generated +filename. +.sp +Allowed format specifiers: +.INDENT 7.0 +.TP +.B \fB%[#][0X]n\fP +A sequence number, padded with zeros to length X (default: 04). E.g. +passing the format \fB%04n\fP will yield \fB0012\fP on the 12th screenshot. +The number is incremented every time a screenshot is taken or if the +file already exists. The length \fBX\fP must be in the range 0\-9. With +the optional # sign, mpv will use the lowest available number. For +example, if you take three screenshots\-\-0001, 0002, 0003\-\-and delete +the first two, the next two screenshots will not be 0004 and 0005, but +0001 and 0002 again. +.TP +.B \fB%f\fP +Filename of the currently played video. +.TP +.B \fB%F\fP +Same as \fB%f\fP, but strip the file extension, including the dot. +.TP +.B \fB%x\fP +Directory path of the currently played video. If the video is not on +the filesystem (but e.g. \fBhttp://\fP), this expand to an empty string. +.TP +.B \fB%X{fallback}\fP +Same as \fB%x\fP, but if the video file is not on the filesystem, return +the fallback string inside the \fB{...}\fP\&. +.TP +.B \fB%p\fP +Current playback time, in the same format as used in the OSD. The +result is a string of the form "HH:MM:SS". For example, if the video is +at the time position 5 minutes and 34 seconds, \fB%p\fP will be replaced +with "00:05:34". +.TP +.B \fB%P\fP +Similar to \fB%p\fP, but extended with the playback time in milliseconds. +It is formatted as "HH:MM:SS.mmm", with "mmm" being the millisecond +part of the playback time. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This is a simple way for getting unique per\-frame timestamps. (Frame +numbers would be more intuitive, but are not easily implementable +because container formats usually use time stamps for identifying +frames.) +.UNINDENT +.UNINDENT +.TP +.B \fB%wX\fP +Specify the current playback time using the format string \fBX\fP\&. +\fB%p\fP is like \fB%wH:%wM:%wS\fP, and \fB%P\fP is like \fB%wH:%wM:%wS.%wT\fP\&. +.INDENT 7.0 +.TP +.B Valid format specifiers: +.INDENT 7.0 +.TP +.B \fB%wH\fP +hour (padded with 0 to two digits) +.TP +.B \fB%wh\fP +hour (not padded) +.TP +.B \fB%wM\fP +minutes (00\-59) +.TP +.B \fB%wm\fP +total minutes (includes hours, unlike \fB%wM\fP) +.TP +.B \fB%wS\fP +seconds (00\-59) +.TP +.B \fB%ws\fP +total seconds (includes hours and minutes) +.TP +.B \fB%wf\fP +like \fB%ws\fP, but as float +.TP +.B \fB%wT\fP +milliseconds (000\-999) +.UNINDENT +.UNINDENT +.TP +.B \fB%tX\fP +Specify the current local date/time using the format \fBX\fP\&. This format +specifier uses the UNIX \fBstrftime()\fP function internally, and inserts +the result of passing "%X" to \fBstrftime\fP\&. For example, \fB%tm\fP will +insert the number of the current month as number. You have to use +multiple \fB%tX\fP specifiers to build a full date/time string. +.TP +.B \fB%{prop[:fallback text]}\fP +Insert the value of the input property \(aqprop\(aq. E.g. \fB%{filename}\fP is +the same as \fB%f\fP\&. If the property does not exist or is not available, +an error text is inserted, unless a fallback is specified. +.TP +.B \fB%%\fP +Replaced with the \fB%\fP character itself. +.UNINDENT +.TP +.B \fB\-\-screenshot\-directory=<path>\fP +Store screenshots in this directory. This path is joined with the filename +generated by \fB\-\-screenshot\-template\fP\&. If the template filename is already +absolute, the directory is ignored. +.sp +If the directory does not exist, it is created on the first screenshot. If +it is not a directory, an error is generated when trying to write a +screenshot. +.sp +This option is not set by default, and thus will write screenshots to the +directory from which mpv was started. In pseudo\-gui mode +(see \fI\%PSEUDO GUI MODE\fP), this is set to the desktop. +.TP +.B \fB\-\-screenshot\-jpeg\-quality=<0\-100>\fP +Set the JPEG quality level. Higher means better quality. The default is 90. +.TP +.B \fB\-\-screenshot\-jpeg\-source\-chroma=<yes|no>\fP +Write JPEG files with the same chroma subsampling as the video +(default: yes). If disabled, the libjpeg default is used. +.TP +.B \fB\-\-screenshot\-png\-compression=<0\-9>\fP +Set the PNG compression level. Higher means better compression. This will +affect the file size of the written screenshot file and the time it takes +to write a screenshot. Too high compression might occupy enough CPU time to +interrupt playback. The default is 7. +.TP +.B \fB\-\-screenshot\-png\-filter=<0\-5>\fP +Set the filter applied prior to PNG compression. 0 is none, 1 is "sub", 2 is +"up", 3 is "average", 4 is "Paeth", and 5 is "mixed". This affects the level +of compression that can be achieved. For most images, "mixed" achieves the +best compression ratio, hence it is the default. +.TP +.B \fB\-\-screenshot\-webp\-lossless=<yes|no>\fP +Write lossless WebP files. \fB\-\-screenshot\-webp\-quality\fP is ignored if this +is set. The default is no. +.TP +.B \fB\-\-screenshot\-webp\-quality=<0\-100>\fP +Set the WebP quality level. Higher means better quality. The default is 75. +.TP +.B \fB\-\-screenshot\-webp\-compression=<0\-6>\fP +Set the WebP compression level. Higher means better compression, but takes +more CPU time. Note that this also affects the screenshot quality when used +with lossy WebP files. The default is 4. +.UNINDENT +.SS Software Scaler +.INDENT 0.0 +.TP +.B \fB\-\-sws\-scaler=<name>\fP +Specify the software scaler algorithm to be used with \fB\-\-vf=scale\fP\&. This +also affects video output drivers which lack hardware acceleration, +e.g. \fBx11\fP\&. See also \fB\-\-vf=scale\fP\&. +.sp +To get a list of available scalers, run \fB\-\-sws\-scaler=help\fP\&. +.sp +Default: \fBbicubic\fP\&. +.TP +.B \fB\-\-sws\-lgb=<0\-100>\fP +Software scaler Gaussian blur filter (luma). See \fB\-\-sws\-scaler\fP\&. +.TP +.B \fB\-\-sws\-cgb=<0\-100>\fP +Software scaler Gaussian blur filter (chroma). See \fB\-\-sws\-scaler\fP\&. +.TP +.B \fB\-\-sws\-ls=<\-100\-100>\fP +Software scaler sharpen filter (luma). See \fB\-\-sws\-scaler\fP\&. +.TP +.B \fB\-\-sws\-cs=<\-100\-100>\fP +Software scaler sharpen filter (chroma). See \fB\-\-sws\-scaler\fP\&. +.TP +.B \fB\-\-sws\-chs=<h>\fP +Software scaler chroma horizontal shifting. See \fB\-\-sws\-scaler\fP\&. +.TP +.B \fB\-\-sws\-cvs=<v>\fP +Software scaler chroma vertical shifting. See \fB\-\-sws\-scaler\fP\&. +.TP +.B \fB\-\-sws\-allow\-zimg=<yes|no>\fP +Allow using zimg (if the component using the internal swscale wrapper +explicitly allows so). In this case, zimg \fImay\fP be used, if the internal +zimg wrapper supports the input and output formats. It will silently +fall back to libswscale if one of these conditions does not apply. +.sp +If zimg is used, the other \fB\-\-sws\-\fP options are ignored, and the +\fB\-\-zimg\-\fP options are used instead. +.sp +If the internal component using the swscale wrapper hooks up logging +correctly, a verbose priority log message will indicate whether zimg is +being used. +.sp +Currently, barely anything uses this. +.TP +.B \fB\-\-zimg\-\-scaler=<point|bilinear|bicubic|spline16|lanczos>\fP +Zimg luma scaler to use (default: bilinear). +.TP +.B \fB\-\-zimg\-fast=<yes|no>\fP +Allow optimizations that help with performance, but reduce quality (default: +yes). Currently, this may simplify gamma conversion operations. +.UNINDENT +.SS Audio Resampler +.sp +This controls the default options of any resampling done by mpv (but not within +libavfilter, within the system audio API resampler, or any other places). +.sp +It also sets the defaults for the \fBlavrresample\fP audio filter. +.INDENT 0.0 +.TP +.B \fB\-\-audio\-resample\-filter\-size=<length>\fP +Length of the filter with respect to the lower sampling rate. (default: +16) +.TP +.B \fB\-\-audio\-resample\-phase\-shift=<count>\fP +Log2 of the number of polyphase entries. (..., 10\->1024, 11\->2048, +12\->4096, ...) (default: 10\->1024) +.TP +.B \fB\-\-audio\-resample\-cutoff=<cutoff>\fP +Cutoff frequency (0.0\-1.0), default set depending upon filter length. +.TP +.B \fB\-\-audio\-resample\-linear=<yes|no>\fP +If set then filters will be linearly interpolated between polyphase +entries. (default: no) +.TP +.B \fB\-\-audio\-normalize\-downmix=<yes|no>\fP +Enable/disable normalization if surround audio is downmixed to stereo +(default: no). If this is disabled, downmix can cause clipping. If it\(aqs +enabled, the output might be too quiet. It depends on the source audio. +.sp +Technically, this changes the \fBnormalize\fP suboption of the +\fBlavrresample\fP audio filter, which performs the downmixing. +.sp +If downmix happens outside of mpv for some reason, or in the decoder +(decoder downmixing), or in the audio output (system mixer), this has no +effect. +.TP +.B \fB\-\-audio\-resample\-max\-output\-size=<length>\fP +Limit maximum size of audio frames filtered at once, in ms (default: 40). +The output size size is limited in order to make resample speed changes +react faster. This is necessary especially if decoders or filters output +very large frame sizes (like some lossless codecs or some DRC filters). +This option does not affect the resampling algorithm in any way. +.sp +For testing/debugging only. Can be removed or changed any time. +.TP +.B \fB\-\-audio\-swresample\-o=<string>\fP +Set AVOptions on the SwrContext or AVAudioResampleContext. These should +be documented by FFmpeg or Libav. +.UNINDENT +.SS Terminal +.INDENT 0.0 +.TP +.B \fB\-\-quiet\fP +Make console output less verbose; in particular, prevents the status line +(i.e. AV: 3.4 (00:00:03.37) / 5320.6 ...) from being displayed. +Particularly useful on slow terminals or broken ones which do not properly +handle carriage return (i.e. \fB\er\fP). +.sp +See also: \fB\-\-really\-quiet\fP and \fB\-\-msg\-level\fP\&. +.TP +.B \fB\-\-really\-quiet\fP +Display even less output and status messages than with \fB\-\-quiet\fP\&. +.TP +.B \fB\-\-no\-terminal\fP, \fB\-\-terminal\fP +Disable any use of the terminal and stdin/stdout/stderr. This completely +silences any message output. +.sp +Unlike \fB\-\-really\-quiet\fP, this disables input and terminal initialization +as well. +.TP +.B \fB\-\-no\-msg\-color\fP +Disable colorful console output on terminals. +.TP +.B \fB\-\-msg\-level=<module1=level1,module2=level2,...>\fP +Control verbosity directly for each module. The \fBall\fP module changes the +verbosity of all the modules. The verbosity changes from this option are +applied in order from left to right, and each item can override a previous +one. +.sp +Run mpv with \fB\-\-msg\-level=all=trace\fP to see all messages mpv outputs. You +can use the module names printed in the output (prefixed to each line in +\fB[...]\fP) to limit the output to interesting modules. +.sp +This also affects \fB\-\-log\-file\fP, and in certain cases libmpv API logging. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Some messages are printed before the command line is parsed and are +therefore not affected by \fB\-\-msg\-level\fP\&. To control these messages, +you have to use the \fBMPV_VERBOSE\fP environment variable; see +\fI\%ENVIRONMENT VARIABLES\fP for details. +.UNINDENT +.UNINDENT +.sp +Available levels: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B no +complete silence +.TP +.B fatal +fatal messages only +.TP +.B error +error messages +.TP +.B warn +warning messages +.TP +.B info +informational messages +.TP +.B status +status messages (default) +.TP +.B v +verbose messages +.TP +.B debug +debug messages +.TP +.B trace +very noisy debug messages +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-msg\-level=ao/sndio=no +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Completely silences the output of ao_sndio, which uses the log +prefix \fB[ao/sndio]\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-msg\-level=all=warn,ao/alsa=error +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Only show warnings or worse, and let the ao_alsa output show errors +only. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-term\-osd=<auto|no|force>\fP +Control whether OSD messages are shown on the console when no video output +is available (default: auto). +.INDENT 7.0 +.TP +.B auto +use terminal OSD if no video output active +.TP +.B no +disable terminal OSD +.TP +.B force +use terminal OSD even if video output active +.UNINDENT +.sp +The \fBauto\fP mode also enables terminal OSD if \fB\-\-video\-osd=no\fP was set. +.TP +.B \fB\-\-term\-osd\-bar\fP, \fB\-\-no\-term\-osd\-bar\fP +Enable printing a progress bar under the status line on the terminal. +(Disabled by default.) +.TP +.B \fB\-\-term\-osd\-bar\-chars=<string>\fP +Customize the \fB\-\-term\-osd\-bar\fP feature. The string is expected to +consist of 5 characters (start, left space, position indicator, +right space, end). You can use Unicode characters, but note that double\- +width characters will not be treated correctly. +.sp +Default: \fB[\-+\-]\fP\&. +.TP +.B \fB\-\-term\-playing\-msg=<string>\fP +Print out a string after starting playback. The string is expanded for +properties, e.g. \fB\-\-term\-playing\-msg=\(aqfile: ${filename}\(aq\fP will print the string +\fBfile:\fP followed by a space and the currently played filename. +.sp +See \fI\%Property Expansion\fP\&. +.TP +.B \fB\-\-term\-status\-msg=<string>\fP +Print out a custom string during playback instead of the standard status +line. Expands properties. See \fI\%Property Expansion\fP\&. +.TP +.B \fB\-\-msg\-module\fP +Prepend module name to each console message. +.TP +.B \fB\-\-msg\-time\fP +Prepend timing information to each console message. +.UNINDENT +.SS Cache +.INDENT 0.0 +.TP +.B \fB\-\-cache=<yes|no|auto>\fP +Decide whether to use network cache settings (default: auto). +.sp +If enabled, use up to \fB\-\-cache\-secs\fP for the cache size (but still limited +to \fB\-\-demuxer\-max\-bytes\fP). \fB\-\-demuxer\-seekable\-cache=auto\fP behaves as if +it was set to \fByes\fP\&. If disabled, \fB\-\-cache\-pause\fP and related are +implicitly disabled. +.sp +The \fBauto\fP choice enables this depending on whether the stream is thought +to involve network accesses or other slow media (this is an imperfect +heuristic). +.sp +Before mpv 0.30.0, this used to accept a number, which specified the size +of the cache in kilobytes. Use e.g. \fB\-\-cache \-\-demuxer\-max\-bytes=123k\fP +instead. +.TP +.B \fB\-\-no\-cache\fP +Turn off input stream caching. See \fB\-\-cache\fP\&. +.TP +.B \fB\-\-cache\-secs=<seconds>\fP +How many seconds of audio/video to prefetch if the cache is active. This +overrides the \fB\-\-demuxer\-readahead\-secs\fP option if and only if the cache +is enabled and the value is larger. The default value is set to something +very high, so the actually achieved readahead will usually be limited by +the value of the \fB\-\-demuxer\-max\-bytes\fP option. Setting this option is +usually only useful for limiting readahead. +.TP +.B \fB\-\-cache\-on\-disk=<yes|no>\fP +Write packet data to a temporary file, instead of keeping them in memory. +This makes sense only with \fB\-\-cache\fP\&. If the normal cache is disabled, +this option is ignored. +.sp +You need to set \fB\-\-cache\-dir\fP to use this. +.sp +The cache file is append\-only. Even if the player appears to prune data, the +file space freed by it is not reused. The cache file is deleted when +playback is closed. +.sp +Note that packet metadata is still kept in memory. \fB\-\-demuxer\-max\-bytes\fP +and related options are applied to metadata \fIonly\fP\&. The size of this +metadata varies, but 50 MB per hour of media is typical. The cache +statistics will report this metadats size, instead of the size of the cache +file. If the metadata hits the size limits, the metadata is pruned (but not +the cache file). +.sp +When the media is closed, the cache file is deleted. A cache file is +generally worthless after the media is closed, and it\(aqs hard to retrieve +any media data from it (it\(aqs not supported by design). +.sp +If the option is enabled at runtime, the cache file is created, but old data +will remain in the memory cache. If the option is disabled at runtime, old +data remains in the disk cache, and the cache file is not closed until the +media is closed. If the option is disabled and enabled again, it will +continue to use the cache file that was opened first. +.TP +.B \fB\-\-cache\-dir=<path>\fP +Directory where to create temporary files (default: none). +.sp +Currently, this is used for \fB\-\-cache\-on\-disk\fP only. +.TP +.B \fB\-\-cache\-pause=<yes|no>\fP +Whether the player should automatically pause when the cache runs out of +data and stalls decoding/playback (default: yes). If enabled, it will +pause and unpause once more data is available, aka "buffering". +.TP +.B \fB\-\-cache\-pause\-wait=<seconds>\fP +Number of seconds the packet cache should have buffered before starting +playback again if "buffering" was entered (default: 1). This can be used +to control how long the player rebuffers if \fB\-\-cache\-pause\fP is enabled, +and the demuxer underruns. If the given time is higher than the maximum +set with \fB\-\-cache\-secs\fP or \fB\-\-demuxer\-readahead\-secs\fP, or prefetching +ends before that for some other reason (like file end or maximum configured +cache size reached), playback resumes earlier. +.TP +.B \fB\-\-cache\-pause\-initial=<yes|no>\fP +Enter "buffering" mode before starting playback (default: no). This can be +used to ensure playback starts smoothly, in exchange for waiting some time +to prefetch network data (as controlled by \fB\-\-cache\-pause\-wait\fP). For +example, some common behavior is that playback starts, but network caches +immediately underrun when trying to decode more data as playback progresses. +.sp +Another thing that can happen is that the network prefetching is so CPU +demanding (due to demuxing in the background) that playback drops frames +at first. In these cases, it helps enabling this option, and setting +\fB\-\-cache\-secs\fP and \fB\-\-cache\-pause\-wait\fP to roughly the same value. +.sp +This option also triggers when playback is restarted after seeking. +.TP +.B \fB\-\-cache\-unlink\-files=<immediate|whendone|no>\fP +Whether or when to unlink cache files (default: immediate). This affects +cache files which are inherently temporary, and which make no sense to +remain on disk after the player terminates. This is a debugging option. +.INDENT 7.0 +.TP +.B \fBimmediate\fP +Unlink cache file after they were created. The cache files won\(aqt be +visible anymore, even though they\(aqre in use. This ensures they are +guaranteed to be removed from disk when the player terminates, even if +it crashes. +.TP +.B \fBwhendone\fP +Delete cache files after they are closed. +.TP +.B \fBno\fP +Don\(aqt delete cache files. They will consume disk space without having a +use. +.UNINDENT +.sp +Currently, this is used for \fB\-\-cache\-on\-disk\fP only. +.UNINDENT +.SS Network +.INDENT 0.0 +.TP +.B \fB\-\-user\-agent=<string>\fP +Use \fB<string>\fP as user agent for HTTP streaming. +.TP +.B \fB\-\-cookies\fP, \fB\-\-no\-cookies\fP +Support cookies when making HTTP requests. Disabled by default. +.TP +.B \fB\-\-cookies\-file=<filename>\fP +Read HTTP cookies from <filename>. The file is assumed to be in Netscape +format. +.TP +.B \fB\-\-http\-header\-fields=<field1,field2>\fP +Set custom HTTP fields when accessing HTTP stream. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-http\-header\-fields=\(aqField1: value1\(aq,\(aqField2: value2\(aq \e +http://localhost:1234 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Will generate HTTP request: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +GET / HTTP/1.0 +Host: localhost:1234 +User\-Agent: MPlayer +Icy\-MetaData: 1 +Field1: value1 +Field2: value2 +Connection: close +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-http\-proxy=<proxy>\fP +URL of the HTTP/HTTPS proxy. If this is set, the \fBhttp_proxy\fP environment +is ignored. The \fBno_proxy\fP environment variable is still respected. This +option is silently ignored if it does not start with \fBhttp://\fP\&. Proxies +are not used for https URLs. Setting this option does not try to make the +ytdl script use the proxy. +.TP +.B \fB\-\-tls\-ca\-file=<filename>\fP +Certificate authority database file for use with TLS. (Silently fails with +older FFmpeg or Libav versions.) +.TP +.B \fB\-\-tls\-verify\fP +Verify peer certificates when using TLS (e.g. with \fBhttps://...\fP). +(Silently fails with older FFmpeg or Libav versions.) +.TP +.B \fB\-\-tls\-cert\-file\fP +A file containing a certificate to use in the handshake with the +peer. +.TP +.B \fB\-\-tls\-key\-file\fP +A file containing the private key for the certificate. +.TP +.B \fB\-\-referrer=<string>\fP +Specify a referrer path or URL for HTTP requests. +.TP +.B \fB\-\-network\-timeout=<seconds>\fP +Specify the network timeout in seconds. This affects at least HTTP. The +special value 0 (default) uses the FFmpeg/Libav defaults. If a protocol +is used which does not support timeouts, this option is silently ignored. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This breaks the RTSP protocol, because of inconsistent FFmpeg API +regarding its internal timeout option. Not only does the RTSP timeout +option accept different units (seconds instead of microseconds, causing +mpv to pass it huge values), it will also overflow FFmpeg internal +calculations. The worst is that merely setting the option will put RTSP +into listening mode, which breaks any client uses. Do not use this +option with RTSP URLs. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-rtsp\-transport=<lavf|udp|tcp|http>\fP +Select RTSP transport method (default: tcp). This selects the underlying +network transport when playing \fBrtsp://...\fP URLs. The value \fBlavf\fP +leaves the decision to libavformat. +.TP +.B \fB\-\-hls\-bitrate=<no|min|max|<rate>>\fP +If HLS streams are played, this option controls what streams are selected +by default. The option allows the following parameters: +.INDENT 7.0 +.TP +.B no +Don\(aqt do anything special. Typically, this will simply pick the +first audio/video streams it can find. +.TP +.B min +Pick the streams with the lowest bitrate. +.TP +.B max +Same, but highest bitrate. (Default.) +.UNINDENT +.sp +Additionally, if the option is a number, the stream with the highest rate +equal or below the option value is selected. +.sp +The bitrate as used is sent by the server, and there\(aqs no guarantee it\(aqs +actually meaningful. +.UNINDENT +.SS DVB +.INDENT 0.0 +.TP +.B \fB\-\-dvbin\-prog=<string>\fP +This defines the program to tune to. Usually, you may specify this +by using a stream URI like \fB"dvb://ZDF HD"\fP, but you can tune to a +different channel by writing to this property at runtime. +Also see \fBdvbin\-channel\-switch\-offset\fP for more useful channel +switching functionality. +.TP +.B \fB\-\-dvbin\-card=<0\-15>\fP +Specifies using card number 0\-15 (default: 0). +.TP +.B \fB\-\-dvbin\-file=<filename>\fP +Instructs mpv to read the channels list from \fB<filename>\fP\&. The default is +in the mpv configuration directory (usually \fB~/.config/mpv\fP) with the +filename \fBchannels.conf.{sat,ter,cbl,atsc}\fP (based on your card type) or +\fBchannels.conf\fP as a last resort. +For DVB\-S/2 cards, a VDR 1.7.x format channel list is recommended +as it allows tuning to DVB\-S2 channels, enabling subtitles and +decoding the PMT (which largely improves the demuxing). +Classic mplayer format channel lists are still supported (without +these improvements), and for other card types, only limited VDR +format channel list support is implemented (patches welcome). +For channels with dynamic PID switching or incomplete +\fBchannels.conf\fP, \fB\-\-dvbin\-full\-transponder\fP or the magic PID +\fB8192\fP are recommended. +.TP +.B \fB\-\-dvbin\-timeout=<1\-30>\fP +Maximum number of seconds to wait when trying to tune a frequency before +giving up (default: 30). +.TP +.B \fB\-\-dvbin\-full\-transponder=<yes|no>\fP +Apply no filters on program PIDs, only tune to frequency and pass full +transponder to demuxer. +The player frontend selects the streams from the full TS in this case, +so the program which is shown initially may not match the chosen channel. +Switching between the programs is possible by cycling the \fBprogram\fP +property. +This is useful to record multiple programs on a single transponder, +or to work around issues in the \fBchannels.conf\fP\&. +It is also recommended to use this for channels which switch PIDs +on\-the\-fly, e.g. for regional news. +.sp +Default: \fBno\fP +.TP +.B \fB\-\-dvbin\-channel\-switch\-offset=<integer>\fP +This value is not meant for setting via configuration, but used in channel +switching. An \fBinput.conf\fP can \fBcycle\fP this value \fBup\fP and \fBdown\fP +to perform channel switching. This number effectively gives the offset +to the initially tuned to channel in the channel list. +.sp +An example \fBinput.conf\fP could contain: +\fBH cycle dvbin\-channel\-switch\-offset up\fP, \fBK cycle dvbin\-channel\-switch\-offset down\fP +.UNINDENT +.SS ALSA audio output options +.INDENT 0.0 +.TP +.B \fB\-\-alsa\-device=<device>\fP +Deprecated, use \fB\-\-audio\-device\fP (requires \fBalsa/\fP prefix). +.TP +.B \fB\-\-alsa\-resample=yes\fP +Enable ALSA resampling plugin. (This is disabled by default, because +some drivers report incorrect audio delay in some cases.) +.TP +.B \fB\-\-alsa\-mixer\-device=<device>\fP +Set the mixer device used with \fBao\-volume\fP (default: \fBdefault\fP). +.TP +.B \fB\-\-alsa\-mixer\-name=<name>\fP +Set the name of the mixer element (default: \fBMaster\fP). This is for +example \fBPCM\fP or \fBMaster\fP\&. +.TP +.B \fB\-\-alsa\-mixer\-index=<number>\fP +Set the index of the mixer channel (default: 0). Consider the output of +"\fBamixer scontrols\fP", then the index is the number that follows the +name of the element. +.TP +.B \fB\-\-alsa\-non\-interleaved\fP +Allow output of non\-interleaved formats (if the audio decoder uses +this format). Currently disabled by default, because some popular +ALSA plugins are utterly broken with non\-interleaved formats. +.TP +.B \fB\-\-alsa\-ignore\-chmap\fP +Don\(aqt read or set the channel map of the ALSA device \- only request the +required number of channels, and then pass the audio as\-is to it. This +option most likely should not be used. It can be useful for debugging, +or for static setups with a specially engineered ALSA configuration (in +this case you should always force the same layout with \fB\-\-audio\-channels\fP, +or it will work only for files which use the layout implicit to your +ALSA device). +.TP +.B \fB\-\-alsa\-buffer\-time=<microseconds>\fP +Set the requested buffer time in microseconds. A value of 0 skips requesting +anything from the ALSA API. This and the \fB\-\-alsa\-periods\fP option uses the +ALSA \fBnear\fP functions to set the requested parameters. If doing so results +in an empty configuration set, setting these parameters is skipped. +.sp +Both options control the buffer size. A low buffer size can lead to higher +CPU usage and audio dropouts, while a high buffer size can lead to higher +latency in volume changes and other filtering. +.TP +.B \fB\-\-alsa\-periods=<number>\fP +Number of periods requested from the ALSA API. See \fB\-\-alsa\-buffer\-time\fP +for further remarks. +.UNINDENT +.SS GPU renderer options +.sp +The following video options are currently all specific to \fB\-\-vo=gpu\fP and +\fB\-\-vo=opengl\-cb\fP only, which are the only VOs that implement them. +.INDENT 0.0 +.TP +.B \fB\-\-scale=<filter>\fP +The filter function to use when upscaling video. +.INDENT 7.0 +.TP +.B \fBbilinear\fP +Bilinear hardware texture filtering (fastest, very low quality). This +is the default for compatibility reasons. +.TP +.B \fBspline36\fP +Mid quality and speed. This is the default when using \fBgpu\-hq\fP\&. +.TP +.B \fBlanczos\fP +Lanczos scaling. Provides mid quality and speed. Generally worse than +\fBspline36\fP, but it results in a slightly sharper image which is good +for some content types. The number of taps can be controlled with +\fBscale\-radius\fP, but is best left unchanged. +.sp +(This filter is an alias for \fBsinc\fP\-windowed \fBsinc\fP) +.TP +.B \fBewa_lanczos\fP +Elliptic weighted average Lanczos scaling. Also known as Jinc. +Relatively slow, but very good quality. The radius can be controlled +with \fBscale\-radius\fP\&. Increasing the radius makes the filter sharper +but adds more ringing. +.sp +(This filter is an alias for \fBjinc\fP\-windowed \fBjinc\fP) +.TP +.B \fBewa_lanczossharp\fP +A slightly sharpened version of ewa_lanczos, preconfigured to use an +ideal radius and parameter. If your hardware can run it, this is +probably what you should use by default. +.TP +.B \fBmitchell\fP +Mitchell\-Netravali. The \fBB\fP and \fBC\fP parameters can be set with +\fB\-\-scale\-param1\fP and \fB\-\-scale\-param2\fP\&. This filter is very good at +downscaling (see \fB\-\-dscale\fP). +.TP +.B \fBoversample\fP +A version of nearest neighbour that (naively) oversamples pixels, so +that pixels overlapping edges get linearly interpolated instead of +rounded. This essentially removes the small imperfections and judder +artifacts caused by nearest\-neighbour interpolation, in exchange for +adding some blur. This filter is good at temporal interpolation, and +also known as "smoothmotion" (see \fB\-\-tscale\fP). +.TP +.B \fBlinear\fP +A \fB\-\-tscale\fP filter. +.UNINDENT +.sp +There are some more filters, but most are not as useful. For a complete +list, pass \fBhelp\fP as value, e.g.: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-scale=help +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-cscale=<filter>\fP +As \fB\-\-scale\fP, but for interpolating chroma information. If the image is +not subsampled, this option is ignored entirely. +.TP +.B \fB\-\-dscale=<filter>\fP +Like \fB\-\-scale\fP, but apply these filters on downscaling instead. If this +option is unset, the filter implied by \fB\-\-scale\fP will be applied. +.TP +.B \fB\-\-tscale=<filter>\fP +The filter used for interpolating the temporal axis (frames). This is only +used if \fB\-\-interpolation\fP is enabled. The only valid choices for +\fB\-\-tscale\fP are separable convolution filters (use \fB\-\-tscale=help\fP to +get a list). The default is \fBmitchell\fP\&. +.sp +Common \fB\-\-tscale\fP choices include \fBoversample\fP, \fBlinear\fP, +\fBcatmull_rom\fP, \fBmitchell\fP, \fBgaussian\fP, or \fBbicubic\fP\&. These are +listed in increasing order of smoothness/blurriness, with \fBbicubic\fP +being the smoothest/blurriest and \fBoversample\fP being the sharpest/least +smooth. +.TP +.B \fB\-\-scale\-param1=<value>\fP, \fB\-\-scale\-param2=<value>\fP, \fB\-\-cscale\-param1=<value>\fP, \fB\-\-cscale\-param2=<value>\fP, \fB\-\-dscale\-param1=<value>\fP, \fB\-\-dscale\-param2=<value>\fP, \fB\-\-tscale\-param1=<value>\fP, \fB\-\-tscale\-param2=<value>\fP +Set filter parameters. By default, these are set to the special string +\fBdefault\fP, which maps to a scaler\-specific default value. Ignored if the +filter is not tunable. Currently, this affects the following filter +parameters: +.INDENT 7.0 +.TP +.B bcspline +Spline parameters (\fBB\fP and \fBC\fP). Defaults to 0.5 for both. +.TP +.B gaussian +Scale parameter (\fBt\fP). Increasing this makes the result blurrier. +Defaults to 1. +.TP +.B oversample +Minimum distance to an edge before interpolation is used. Setting this +to 0 will always interpolate edges, whereas setting it to 0.5 will +never interpolate, thus behaving as if the regular nearest neighbour +algorithm was used. Defaults to 0.0. +.UNINDENT +.TP +.B \fB\-\-scale\-blur=<value>\fP, \fB\-\-scale\-wblur=<value>\fP, \fB\-\-cscale\-blur=<value>\fP, \fB\-\-cscale\-wblur=<value>\fP, \fB\-\-dscale\-blur=<value>\fP, \fB\-\-dscale\-wblur=<value>\fP, \fB\-\-tscale\-blur=<value>\fP, \fB\-\-tscale\-wblur=<value>\fP +Kernel/window scaling factor (also known as a blur factor). Decreasing this +makes the result sharper, increasing it makes it blurrier (default 0). If +set to 0, the kernel\(aqs preferred blur factor is used. Note that setting +this too low (eg. 0.5) leads to bad results. It\(aqs generally recommended to +stick to values between 0.8 and 1.2. +.TP +.B \fB\-\-scale\-clamp=<0.0\-1.0>\fP, \fB\-\-cscale\-clamp\fP, \fB\-\-dscale\-clamp\fP, \fB\-\-tscale\-clamp\fP +Specifies a weight bias to multiply into negative coefficients. Specifying +\fB\-\-scale\-clamp=1\fP has the effect of removing negative weights completely, +thus effectively clamping the value range to [0\-1]. Values between 0.0 and +1.0 can be specified to apply only a moderate diminishment of negative +weights. This is especially useful for \fB\-\-tscale\fP, where it reduces +excessive ringing artifacts in the temporal domain (which typically +manifest themselves as short flashes or fringes of black, mostly around +moving edges) in exchange for potentially adding more blur. The default for +\fB\-\-tscale\-clamp\fP is 1.0, the others default to 0.0. +.TP +.B \fB\-\-scale\-cutoff=<value>\fP, \fB\-\-cscale\-cutoff=<value>\fP, \fB\-\-dscale\-cutoff=<value>\fP +Cut off the filter kernel prematurely once the value range drops below +this threshold. Doing so allows more aggressive pruning of skippable +coefficients by disregarding parts of the LUT which are effectively zeroed +out by the window function. Only affects polar (EWA) filters. The default +is 0.001 for each, which is perceptually transparent but provides a 10%\-20% +speedup, depending on the exact radius and filter kernel chosen. +.TP +.B \fB\-\-scale\-taper=<value>\fP, \fB\-\-scale\-wtaper=<value>\fP, \fB\-\-dscale\-taper=<value>\fP, \fB\-\-dscale\-wtaper=<value>\fP, \fB\-\-cscale\-taper=<value>\fP, \fB\-\-cscale\-wtaper=<value>\fP, \fB\-\-tscale\-taper=<value>\fP, \fB\-\-tscale\-wtaper=<value>\fP +Kernel/window taper factor. Increasing this flattens the filter function. +Value range is 0 to 1. A value of 0 (the default) means no flattening, a +value of 1 makes the filter completely flat (equivalent to a box function). +Values in between mean that some portion will be flat and the actual filter +function will be squeezed into the space in between. +.TP +.B \fB\-\-scale\-radius=<value>\fP, \fB\-\-cscale\-radius=<value>\fP, \fB\-\-dscale\-radius=<value>\fP, \fB\-\-tscale\-radius=<value>\fP +Set radius for tunable filters, must be a float number between 0.5 and +16.0. Defaults to the filter\(aqs preferred radius if not specified. Doesn\(aqt +work for every scaler and VO combination. +.sp +Note that depending on filter implementation details and video scaling +ratio, the radius that actually being used might be different (most likely +being increased a bit). +.TP +.B \fB\-\-scale\-antiring=<value>\fP, \fB\-\-cscale\-antiring=<value>\fP, \fB\-\-dscale\-antiring=<value>\fP, \fB\-\-tscale\-antiring=<value>\fP +Set the antiringing strength. This tries to eliminate ringing, but can +introduce other artifacts in the process. Must be a float number between +0.0 and 1.0. The default value of 0.0 disables antiringing entirely. +.sp +Note that this doesn\(aqt affect the special filters \fBbilinear\fP and +\fBbicubic_fast\fP, nor does it affect any polar (EWA) scalers. +.TP +.B \fB\-\-scale\-window=<window>\fP, \fB\-\-cscale\-window=<window>\fP, \fB\-\-dscale\-window=<window>\fP, \fB\-\-tscale\-window=<window>\fP +(Advanced users only) Choose a custom windowing function for the kernel. +Defaults to the filter\(aqs preferred window if unset. Use +\fB\-\-scale\-window=help\fP to get a list of supported windowing functions. +.TP +.B \fB\-\-scale\-wparam=<window>\fP, \fB\-\-cscale\-wparam=<window>\fP, \fB\-\-cscale\-wparam=<window>\fP, \fB\-\-tscale\-wparam=<window>\fP +(Advanced users only) Configure the parameter for the window function given +by \fB\-\-scale\-window\fP etc. By default, these are set to the special string +\fBdefault\fP, which maps to a window\-specific default value. Ignored if the +window is not tunable. Currently, this affects the following window +parameters: +.INDENT 7.0 +.TP +.B kaiser +Window parameter (alpha). Defaults to 6.33. +.TP +.B blackman +Window parameter (alpha). Defaults to 0.16. +.TP +.B gaussian +Scale parameter (t). Increasing this makes the window wider. Defaults +to 1. +.UNINDENT +.TP +.B \fB\-\-scaler\-lut\-size=<4..10>\fP +Set the size of the lookup texture for scaler kernels (default: 6). The +actual size of the texture is \fB2^N\fP for an option value of \fBN\fP\&. So the +lookup texture with the default setting uses 64 samples. +.sp +All weights are linearly interpolated from those samples, so increasing +the size of lookup table might improve the accuracy of scaler. +.TP +.B \fB\-\-scaler\-resizes\-only\fP +Disable the scaler if the video image is not resized. In that case, +\fBbilinear\fP is used instead of whatever is set with \fB\-\-scale\fP\&. Bilinear +will reproduce the source image perfectly if no scaling is performed. +Enabled by default. Note that this option never affects \fB\-\-cscale\fP\&. +.TP +.B \fB\-\-correct\-downscaling\fP +When using convolution based filters, extend the filter size when +downscaling. Increases quality, but reduces performance while downscaling. +.sp +This will perform slightly sub\-optimally for anamorphic video (but still +better than without it) since it will extend the size to match only the +milder of the scale factors between the axes. +.TP +.B \fB\-\-linear\-downscaling\fP +Scale in linear light when downscaling. It should only be used with a +\fB\-\-fbo\-format\fP that has at least 16 bit precision. This option +has no effect on HDR content. +.TP +.B \fB\-\-linear\-upscaling\fP +Scale in linear light when upscaling. Like \fB\-\-linear\-downscaling\fP, it +should only be used with a \fB\-\-fbo\-format\fP that has at least 16 bits +precisions. This is not usually recommended except for testing/specific +purposes. Users are advised to either enable \fB\-\-sigmoid\-upscaling\fP or +keep both options disabled (i.e. scaling in gamma light). +.TP +.B \fB\-\-sigmoid\-upscaling\fP +When upscaling, use a sigmoidal color transform to avoid emphasizing +ringing artifacts. This is incompatible with and replaces +\fB\-\-linear\-upscaling\fP\&. (Note that sigmoidization also requires +linearization, so the \fBLINEAR\fP rendering step fires in both cases) +.TP +.B \fB\-\-sigmoid\-center\fP +The center of the sigmoid curve used for \fB\-\-sigmoid\-upscaling\fP, must be a +float between 0.0 and 1.0. Defaults to 0.75 if not specified. +.TP +.B \fB\-\-sigmoid\-slope\fP +The slope of the sigmoid curve used for \fB\-\-sigmoid\-upscaling\fP, must be a +float between 1.0 and 20.0. Defaults to 6.5 if not specified. +.TP +.B \fB\-\-interpolation\fP +Reduce stuttering caused by mismatches in the video fps and display refresh +rate (also known as judder). +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This requires setting the \fB\-\-video\-sync\fP option to one +of the \fBdisplay\-\fP modes, or it will be silently disabled. +This was not required before mpv 0.14.0. +.UNINDENT +.UNINDENT +.sp +This essentially attempts to interpolate the missing frames by convoluting +the video along the temporal axis. The filter used can be controlled using +the \fB\-\-tscale\fP setting. +.TP +.B \fB\-\-interpolation\-threshold=<0..1,\-1>\fP +Threshold below which frame ratio interpolation gets disabled (default: +\fB0.0001\fP). This is calculated as \fBabs(disphz/vfps \- 1) < threshold\fP, +where \fBvfps\fP is the speed\-adjusted video FPS, and \fBdisphz\fP the +display refresh rate. (The speed\-adjusted video FPS is roughly equal to +the normal video FPS, but with slowdown and speedup applied. This matters +if you use \fB\-\-video\-sync=display\-resample\fP to make video run synchronously +to the display FPS, or if you change the \fBspeed\fP property.) +.sp +The default is intended to almost always enable interpolation if the +playback rate is even slightly different from the display refresh rate. But +note that if you use e.g. \fB\-\-video\-sync=display\-vdrop\fP, small deviations +in the rate can disable interpolation and introduce a discontinuity every +other minute. +.sp +Set this to \fB\-1\fP to disable this logic. +.TP +.B \fB\-\-opengl\-pbo\fP +Enable use of PBOs. On some drivers this can be faster, especially if the +source video size is huge (e.g. so called "4K" video). On other drivers it +might be slower or cause latency issues. +.TP +.B \fB\-\-dither\-depth=<N|no|auto>\fP +Set dither target depth to N. Default: no. +.INDENT 7.0 +.TP +.B no +Disable any dithering done by mpv. +.TP +.B auto +Automatic selection. If output bit depth cannot be detected, 8 bits per +component are assumed. +.TP +.B 8 +Dither to 8 bit output. +.UNINDENT +.sp +Note that the depth of the connected video display device cannot be +detected. Often, LCD panels will do dithering on their own, which conflicts +with this option and leads to ugly output. +.TP +.B \fB\-\-dither\-size\-fruit=<2\-8>\fP +Set the size of the dither matrix (default: 6). The actual size of the +matrix is \fB(2^N) x (2^N)\fP for an option value of \fBN\fP, so a value of 6 +gives a size of 64x64. The matrix is generated at startup time, and a large +matrix can take rather long to compute (seconds). +.sp +Used in \fB\-\-dither=fruit\fP mode only. +.TP +.B \fB\-\-dither=<fruit|ordered|error\-diffusion|no>\fP +Select dithering algorithm (default: fruit). (Normally, the +\fB\-\-dither\-depth\fP option controls whether dithering is enabled.) +.sp +The \fBerror\-diffusion\fP option requires compute shader support. It also +requires large amount of shared memory to run, the size of which depends on +both the kernel (see \fB\-\-error\-diffusion\fP option below) and the height of +video window. It will fallback to \fBfruit\fP dithering if there is no enough +shared memory to run the shader. +.TP +.B \fB\-\-temporal\-dither\fP +Enable temporal dithering. (Only active if dithering is enabled in +general.) This changes between 8 different dithering patterns on each frame +by changing the orientation of the tiled dithering matrix. Unfortunately, +this can lead to flicker on LCD displays, since these have a high reaction +time. +.TP +.B \fB\-\-temporal\-dither\-period=<1\-128>\fP +Determines how often the dithering pattern is updated when +\fB\-\-temporal\-dither\fP is in use. 1 (the default) will update on every video +frame, 2 on every other frame, etc. +.TP +.B \fB\-\-error\-diffusion=<kernel>\fP +The error diffusion kernel to use when \fB\-\-dither=error\-diffusion\fP is set. +.INDENT 7.0 +.TP +.B \fBsimple\fP +Propagate error to only two adjacent pixels. Fastest but low quality. +.TP +.B \fBsierra\-lite\fP +Fast with reasonable quality. This is the default. +.TP +.B \fBfloyd\-steinberg\fP +Most notable error diffusion kernel. +.TP +.B \fBatkinson\fP +Looks different from other kernels because only fraction of errors will +be propagated during dithering. A typical use case of this kernel is +saving dithered screenshot (in window mode). This kernel produces +slightly smaller file, with still reasonable dithering quality. +.UNINDENT +.sp +There are other kernels (use \fB\-\-error\-diffusion=help\fP to list) but most of +them are much slower and demanding even larger amount of shared memory. +Among these kernels, \fBburkes\fP achieves a good balance between performance +and quality, and probably is the one you want to try first. +.TP +.B \fB\-\-gpu\-debug\fP +Enables GPU debugging. What this means depends on the API type. For OpenGL, +it calls \fBglGetError()\fP, and requests a debug context. For Vulkan, it +enables validation layers. +.TP +.B \fB\-\-opengl\-swapinterval=<n>\fP +Interval in displayed frames between two buffer swaps. 1 is equivalent to +enable VSYNC, 0 to disable VSYNC. Defaults to 1 if not specified. +.sp +Note that this depends on proper OpenGL vsync support. On some platforms +and drivers, this only works reliably when in fullscreen mode. It may also +require driver\-specific hacks if using multiple monitors, to ensure mpv +syncs to the right one. Compositing window managers can also lead to bad +results, as can missing or incorrect display FPS information (see +\fB\-\-display\-fps\fP). +.TP +.B \fB\-\-vulkan\-swap\-mode=<mode>\fP +Controls the presentation mode of the vulkan swapchain. This is similar +to the \fB\-\-opengl\-swapinterval\fP option. +.INDENT 7.0 +.TP +.B auto +Use the preferred swapchain mode for the vulkan context. (Default) +.TP +.B fifo +Non\-tearing, vsync blocked. Similar to "VSync on". +.TP +.B fifo\-relaxed +Tearing, vsync blocked. Late frames will tear instead of stuttering. +.TP +.B mailbox +Non\-tearing, not vsync blocked. Similar to "triple buffering". +.TP +.B immediate +Tearing, not vsync blocked. Similar to "VSync off". +.UNINDENT +.TP +.B \fB\-\-vulkan\-queue\-count=<1..8>\fP +Controls the number of VkQueues used for rendering (limited by how many +your device supports). In theory, using more queues could enable some +parallelism between frames (when using a \fB\-\-swapchain\-depth\fP higher than +1), but it can also slow things down on hardware where there\(aqs no true +parallelism between queues. (Default: 1) +.TP +.B \fB\-\-vulkan\-async\-transfer\fP +Enables the use of async transfer queues on supported vulkan devices. Using +them allows transfer operations like texture uploads and blits to happen +concurrently with the actual rendering, thus improving overall throughput +and power consumption. Enabled by default, and should be relatively safe. +.TP +.B \fB\-\-vulkan\-async\-compute\fP +Enables the use of async compute queues on supported vulkan devices. Using +this, in theory, allows out\-of\-order scheduling of compute shaders with +graphics shaders, thus enabling the hardware to do more effective work while +waiting for pipeline bubbles and memory operations. Not beneficial on all +GPUs. It\(aqs worth noting that if async compute is enabled, and the device +supports more compute queues than graphics queues (bound by the restrictions +set by \fB\-\-vulkan\-queue\-count\fP), mpv will internally try and prefer the +use of compute shaders over fragment shaders wherever possible. Not enabled +by default, since it seems to cause issues with some drivers. +.TP +.B \fB\-\-d3d11\-warp=<yes|no|auto>\fP +Use WARP (Windows Advanced Rasterization Platform) with the D3D11 GPU +backend (default: auto). This is a high performance software renderer. By +default, it is only used when the system has no hardware adapters that +support D3D11. While the extended GPU features will work with WARP, they +can be very slow. +.TP +.B \fB\-\-d3d11\-feature\-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1>\fP +Select a specific feature level when using the D3D11 GPU backend. By +default, the highest available feature level is used. This option can be +used to select a lower feature level, which is mainly useful for debugging. +Most extended GPU features will not work at 9_x feature levels. +.TP +.B \fB\-\-d3d11\-flip=<yes|no>\fP +Enable flip\-model presentation, which avoids unnecessarily copying the +backbuffer by sharing surfaces with the DWM (default: yes). This may cause +performance issues with older drivers. If flip\-model presentation is not +supported (for example, on Windows 7 without the platform update), mpv will +automatically fall back to the older bitblt presentation model. +.TP +.B \fB\-\-d3d11\-sync\-interval=<0..4>\fP +Schedule each frame to be presented for this number of VBlank intervals. +(default: 1) Setting to 1 will enable VSync, setting to 0 will disable it. +.TP +.B \fB\-\-d3d11\-adapter=<adapter name|help>\fP +Select a specific D3D11 adapter to utilize for D3D11 rendering. +Will pick the default adapter if unset. Alternatives are listed +when the name "help" is given. +.sp +Checks for matches based on the start of the string, case +insensitive. Thus, if the description of the adapter starts with +the vendor name, that can be utilized as the selection parameter. +.sp +Hardware decoders utilizing the D3D11 rendering abstraction\(aqs helper +functionality to receive a device, such as D3D11VA or DXVA2\(aqs DXGI +mode, will be affected by this choice. +.TP +.B \fB\-\-d3d11\-output\-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f>\fP +Select a specific D3D11 output format to utilize for D3D11 rendering. +"auto" is the default, which will pick either rgba8 or rgb10_a2 depending +on the configured desktop bit depth. rgba16f and bgra8 are left out of +the autodetection logic, and are available for manual testing. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Desktop bit depth querying is only available from an API available +from Windows 10. Thus on older systems it will only automatically +utilize the rgba8 output format. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-d3d11va\-zero\-copy=<yes|no>\fP +By default, when using hardware decoding with \fB\-\-gpu\-api=d3d11\fP, the +video image will be copied (GPU\-to\-GPU) from the decoder surface to a +shader resource. Set this option to avoid that copy by sampling directly +from the decoder image. This may increase performance and reduce power +usage, but can cause the image to be sampled incorrectly on the bottom and +right edges due to padding, and may invoke driver bugs, since Direct3D 11 +technically does not allow sampling from a decoder surface (though most +drivers support it.) +.sp +Currently only relevant for \fB\-\-gpu\-api=d3d11\fP\&. +.TP +.B \fB\-\-wayland\-frame\-wait\-offset=<\-100..3000>\fP +Control the amount of offset (in microseconds) to add to wayland\(aqs frame wait +(default 1000). The wayland context assumes that if frame callback or presentation +feedback isn\(aqt received within a certain amount of time then the video is being +rendered offscreen. The time it waits is equal to how long it takes your monitor +to display a frame (i.e. 1/refresh rate) plus the offset. In general, staying +close to your monitor\(aqs refresh rate is preferred, but with a small offset in +case a frame takes a little long to display. +.TP +.B \fB\-\-wayland\-disable\-vsync=<yes|no>\fP +Disable vsync for the wayland contexts (default: no). Useful for benchmarking +the wayland context when combined with \fBvideo\-sync=display\-desync\fP, +\fB\-\-no\-audio\fP, and \fB\-\-untimed=yes\fP\&. Only works with \fB\-\-gpu\-context=wayland\fP +and \fB\-\-gpu\-context=waylandvk\fP\&. +.TP +.B \fB\-\-spirv\-compiler=<compiler>\fP +Controls which compiler is used to translate GLSL to SPIR\-V. This is +(currently) only relevant for \fB\-\-gpu\-api=vulkan\fP and \fI\-\-gpu\-api=d3d11\fP\&. +The possible choices are currently only: +.INDENT 7.0 +.TP +.B auto +Use the first available compiler. (Default) +.TP +.B shaderc +Use libshaderc, which is an API wrapper around glslang. This is +generally the most preferred, if available. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This option is deprecated, since there is only one reasonable value. +It may be removed in the future. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-glsl\-shaders=<file\-list>\fP +Custom GLSL hooks. These are a flexible way to add custom fragment shaders, +which can be injected at almost arbitrary points in the rendering pipeline, +and access all previous intermediate textures. Each use of the option will +add another file to the internal list of shaders (see \fI\%List Options\fP). +.INDENT 7.0 +.INDENT 3.5 +.IP "Warning" +.sp +The syntax is not stable yet and may change any time. +.UNINDENT +.UNINDENT +.sp +The general syntax of a user shader looks like this: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +//!METADATA ARGS... +//!METADATA ARGS... + +vec4 hook() { + ... + return something; +} + +//!METADATA ARGS... +//!METADATA ARGS... + +\&... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Each section of metadata, along with the non\-metadata lines after it, +defines a single block. There are currently two types of blocks, HOOKs and +TEXTUREs. +.sp +A \fBTEXTURE\fP block can set the following options: +.INDENT 7.0 +.TP +.B TEXTURE <name> (required) +The name of this texture. Hooks can then bind the texture under this +name using BIND. This must be the first option of the texture block. +.TP +.B SIZE <width> [<height>] [<depth>] (required) +The dimensions of the texture. The height and depth are optional. The +type of texture (1D, 2D or 3D) depends on the number of components +specified. +.TP +.B FORMAT <name> (required) +The texture format for the samples. Supported texture formats are listed +in debug logging when the \fBgpu\fP VO is initialized (look for +\fBTexture formats:\fP). Usually, this follows OpenGL naming conventions. +For example, \fBrgb16\fP provides 3 channels with normalized 16 bit +components. One oddity are float formats: for example, \fBrgba16f\fP has +16 bit internal precision, but the texture data is provided as 32 bit +floats, and the driver converts the data on texture upload. +.sp +Although format names follow a common naming convention, not all of them +are available on all hardware, drivers, GL versions, and so on. +.TP +.B FILTER <LINEAR|NEAREST> +The min/magnification filter used when sampling from this texture. +.TP +.B BORDER <CLAMP|REPEAT|MIRROR> +The border wrapping mode used when sampling from this texture. +.UNINDENT +.sp +Following the metadata is a string of bytes in hexadecimal notation that +define the raw texture data, corresponding to the format specified by +\fIFORMAT\fP, on a single line with no extra whitespace. +.sp +A \fBHOOK\fP block can set the following options: +.INDENT 7.0 +.TP +.B HOOK <name> (required) +The texture which to hook into. May occur multiple times within a +metadata block, up to a predetermined limit. See below for a list of +hookable textures. +.TP +.B DESC <title> +User\-friendly description of the pass. This is the name used when +representing this shader in the list of passes for property +\fIvo\-passes\fP\&. +.TP +.B BIND <name> +Loads a texture (either coming from mpv or from a \fBTEXTURE\fP block) +and makes it available to the pass. When binding textures from mpv, +this will also set up macros to facilitate accessing it properly. See +below for a list. By default, no textures are bound. The special name +HOOKED can be used to refer to the texture that triggered this pass. +.TP +.B SAVE <name> +Gives the name of the texture to save the result of this pass into. By +default, this is set to the special name HOOKED which has the effect of +overwriting the hooked texture. +.TP +.B WIDTH <szexpr>, HEIGHT <szexpr> +Specifies the size of the resulting texture for this pass. \fBszexpr\fP +refers to an expression in RPN (reverse polish notation), using the +operators + \- * / > < !, floating point literals, and references to +sizes of existing texture (such as MAIN.width or CHROMA.height), +OUTPUT, or NATIVE_CROPPED (size of an input texture cropped after +pan\-and\-scan, video\-align\-x/y, video\-pan\-x/y, etc. and possibly +prescaled). By default, these are set to HOOKED.w and HOOKED.h, +espectively. +.TP +.B WHEN <szexpr> +Specifies a condition that needs to be true (non\-zero) for the shader +stage to be evaluated. If it fails, it will silently be omitted. (Note +that a shader stage like this which has a dependency on an optional +hook point can still cause that hook point to be saved, which has some +minor overhead) +.TP +.B OFFSET <ox oy | ALIGN> +Indicates a pixel shift (offset) introduced by this pass. These pixel +offsets will be accumulated and corrected during the next scaling pass +(\fBcscale\fP or \fBscale\fP). The default values are 0 0 which correspond +to no shift. Note that offsets are ignored when not overwriting the +hooked texture. +.sp +A special value of \fBALIGN\fP will attempt to fix existing offset of +HOOKED by align it with reference. It requires HOOKED to be resizable +(see below). It works transparently with fragment shader. For compute +shader, the predefined \fBtexmap\fP macro is required to handle coordinate +mapping. +.TP +.B COMPONENTS <n> +Specifies how many components of this pass\(aqs output are relevant and +should be stored in the texture, up to 4 (rgba). By default, this value +is equal to the number of components in HOOKED. +.TP +.B COMPUTE <bw> <bh> [<tw> <th>] +Specifies that this shader should be treated as a compute shader, with +the block size bw and bh. The compute shader will be dispatched with +however many blocks are necessary to completely tile over the output. +Within each block, there will bw tw*th threads, forming a single work +group. In other words: tw and th specify the work group size, which can +be different from the block size. So for example, a compute shader with +bw, bh = 32 and tw, th = 8 running on a 500x500 texture would dispatch +16x16 blocks (rounded up), each with 8x8 threads. +.sp +Compute shaders in mpv are treated a bit different from fragment +shaders. Instead of defining a \fBvec4 hook\fP that produces an output +sample, you directly define \fBvoid hook\fP which writes to a fixed +writeonly image unit named \fBout_image\fP (this is bound by mpv) using +\fIimageStore\fP\&. To help translate texture coordinates in the absence of +vertices, mpv provides a special function \fBNAME_map(id)\fP to map from +the texel space of the output image to the texture coordinates for all +bound textures. In particular, \fBNAME_pos\fP is equivalent to +\fBNAME_map(gl_GlobalInvocationID)\fP, although using this only really +makes sense if (tw,th) == (bw,bh). +.UNINDENT +.sp +Each bound mpv texture (via \fBBIND\fP) will make available the following +definitions to that shader pass, where NAME is the name of the bound +texture: +.INDENT 7.0 +.TP +.B vec4 NAME_tex(vec2 pos) +The sampling function to use to access the texture at a certain spot +(in texture coordinate space, range [0,1]). This takes care of any +necessary normalization conversions. +.TP +.B vec4 NAME_texOff(vec2 offset) +Sample the texture at a certain offset in pixels. This works like +NAME_tex but additionally takes care of necessary rotations, so that +sampling at e.g. vec2(\-1,0) is always one pixel to the left. +.TP +.B vec2 NAME_pos +The local texture coordinate of that texture, range [0,1]. +.TP +.B vec2 NAME_size +The (rotated) size in pixels of the texture. +.TP +.B mat2 NAME_rot +The rotation matrix associated with this texture. (Rotates pixel space +to texture coordinates) +.TP +.B vec2 NAME_pt +The (unrotated) size of a single pixel, range [0,1]. +.TP +.B float NAME_mul +The coefficient that needs to be multiplied into the texture contents +in order to normalize it to the range [0,1]. +.TP +.B sampler NAME_raw +The raw bound texture itself. The use of this should be avoided unless +absolutely necessary. +.UNINDENT +.sp +Normally, users should use either NAME_tex or NAME_texOff to read from the +texture. For some shaders however , it can be better for performance to do +custom sampling from NAME_raw, in which case care needs to be taken to +respect NAME_mul and NAME_rot. +.sp +In addition to these parameters, the following uniforms are also globally +available: +.INDENT 7.0 +.TP +.B float random +A random number in the range [0\-1], different per frame. +.TP +.B int frame +A simple count of frames rendered, increases by one per frame and never +resets (regardless of seeks). +.TP +.B vec2 input_size +The size in pixels of the input image (possibly cropped and prescaled). +.TP +.B vec2 target_size +The size in pixels of the visible part of the scaled (and possibly +cropped) image. +.TP +.B vec2 tex_offset +Texture offset introduced by user shaders or options like panscan, video\-align\-x/y, video\-pan\-x/y. +.UNINDENT +.sp +Internally, vo_gpu may generate any number of the following textures. +Whenever a texture is rendered and saved by vo_gpu, all of the passes +that have hooked into it will run, in the order they were added by the +user. This is a list of the legal hook points: +.INDENT 7.0 +.TP +.B RGB, LUMA, CHROMA, ALPHA, XYZ (resizable) +Source planes (raw). Which of these fire depends on the image format of +the source. +.TP +.B CHROMA_SCALED, ALPHA_SCALED (fixed) +Source planes (upscaled). These only fire on subsampled content. +.TP +.B NATIVE (resizable) +The combined image, in the source colorspace, before conversion to RGB. +.TP +.B MAINPRESUB (resizable) +The image, after conversion to RGB, but before +\fB\-\-blend\-subtitles=video\fP is applied. +.TP +.B MAIN (resizable) +The main image, after conversion to RGB but before upscaling. +.TP +.B LINEAR (fixed) +Linear light image, before scaling. This only fires when +\fB\-\-linear\-upscaling\fP, \fB\-\-linear\-downscaling\fP or +\fB\-\-sigmoid\-upscaling\fP is in effect. +.TP +.B SIGMOID (fixed) +Sigmoidized light, before scaling. This only fires when +\fB\-\-sigmoid\-upscaling\fP is in effect. +.TP +.B PREKERNEL (fixed) +The image immediately before the scaler kernel runs. +.TP +.B POSTKERNEL (fixed) +The image immediately after the scaler kernel runs. +.TP +.B SCALED (fixed) +The final upscaled image, before color management. +.TP +.B OUTPUT (fixed) +The final output image, after color management but before dithering and +drawing to screen. +.UNINDENT +.sp +Only the textures labelled with \fBresizable\fP may be transformed by the +pass. When overwriting a texture marked \fBfixed\fP, the WIDTH, HEIGHT and +OFFSET must be left at their default values. +.TP +.B \fB\-\-glsl\-shader=<file>\fP +CLI/config file only alias for \fB\-\-glsl\-shaders\-append\fP\&. +.TP +.B \fB\-\-deband\fP +Enable the debanding algorithm. This greatly reduces the amount of visible +banding, blocking and other quantization artifacts, at the expense of +very slightly blurring some of the finest details. In practice, it\(aqs +virtually always an improvement \- the only reason to disable it would be +for performance. +.TP +.B \fB\-\-deband\-iterations=<1..16>\fP +The number of debanding steps to perform per sample. Each step reduces a +bit more banding, but takes time to compute. Note that the strength of each +step falls off very quickly, so high numbers (>4) are practically useless. +(Default 1) +.TP +.B \fB\-\-deband\-threshold=<0..4096>\fP +The debanding filter\(aqs cut\-off threshold. Higher numbers increase the +debanding strength dramatically but progressively diminish image details. +(Default 64) +.TP +.B \fB\-\-deband\-range=<1..64>\fP +The debanding filter\(aqs initial radius. The radius increases linearly for +each iteration. A higher radius will find more gradients, but a lower +radius will smooth more aggressively. (Default 16) +.sp +If you increase the \fB\-\-deband\-iterations\fP, you should probably decrease +this to compensate. +.TP +.B \fB\-\-deband\-grain=<0..4096>\fP +Add some extra noise to the image. This significantly helps cover up +remaining quantization artifacts. Higher numbers add more noise. (Default +48) +.TP +.B \fB\-\-sharpen=<value>\fP +If set to a value other than 0, enable an unsharp masking filter. Positive +values will sharpen the image (but add more ringing and aliasing). Negative +values will blur the image. If your GPU is powerful enough, consider +alternatives like the \fBewa_lanczossharp\fP scale filter, or the +\fB\-\-scale\-blur\fP option. +.TP +.B \fB\-\-opengl\-glfinish\fP +Call \fBglFinish()\fP before swapping buffers (default: disabled). Slower, +but might improve results when doing framedropping. Can completely ruin +performance. The details depend entirely on the OpenGL driver. +.TP +.B \fB\-\-opengl\-waitvsync\fP +Call \fBglXWaitVideoSyncSGI\fP after each buffer swap (default: disabled). +This may or may not help with video timing accuracy and frame drop. It\(aqs +possible that this makes video output slower, or has no effect at all. +.sp +X11/GLX only. +.TP +.B \fB\-\-opengl\-dwmflush=<no|windowed|yes|auto>\fP +Calls \fBDwmFlush\fP after swapping buffers on Windows (default: auto). It +also sets \fBSwapInterval(0)\fP to ignore the OpenGL timing. Values are: no +(disabled), windowed (only in windowed mode), yes (also in full screen). +.sp +The value \fBauto\fP will try to determine whether the compositor is active, +and calls \fBDwmFlush\fP only if it seems to be. +.sp +This may help to get more consistent frame intervals, especially with +high\-fps clips \- which might also reduce dropped frames. Typically, a value +of \fBwindowed\fP should be enough, since full screen may bypass the DWM. +.sp +Windows only. +.TP +.B \fB\-\-angle\-d3d11\-feature\-level=<11_0|10_1|10_0|9_3>\fP +Selects a specific feature level when using the ANGLE backend with D3D11. +By default, the highest available feature level is used. This option can be +used to select a lower feature level, which is mainly useful for debugging. +Note that OpenGL ES 3.0 is only supported at feature level 10_1 or higher. +Most extended OpenGL features will not work at lower feature levels +(similar to \fB\-\-gpu\-dumb\-mode\fP). +.sp +Windows with ANGLE only. +.TP +.B \fB\-\-angle\-d3d11\-warp=<yes|no|auto>\fP +Use WARP (Windows Advanced Rasterization Platform) when using the ANGLE +backend with D3D11 (default: auto). This is a high performance software +renderer. By default, it is used when the Direct3D hardware does not +support Direct3D 11 feature level 9_3. While the extended OpenGL features +will work with WARP, they can be very slow. +.sp +Windows with ANGLE only. +.TP +.B \fB\-\-angle\-egl\-windowing=<yes|no|auto>\fP +Use ANGLE\(aqs built in EGL windowing functions to create a swap chain +(default: auto). If this is set to \fBno\fP and the D3D11 renderer is in use, +ANGLE\(aqs built in swap chain will not be used and a custom swap chain that +is optimized for video rendering will be created instead. If set to +\fBauto\fP, a custom swap chain will be used for D3D11 and the built in swap +chain will be used for D3D9. This option is mainly for debugging purposes, +in case the custom swap chain has poor performance or does not work. +.sp +If set to \fByes\fP, the \fB\-\-angle\-max\-frame\-latency\fP, +\fB\-\-angle\-swapchain\-length\fP and \fB\-\-angle\-flip\fP options will have no +effect. +.sp +Windows with ANGLE only. +.TP +.B \fB\-\-angle\-flip=<yes|no>\fP +Enable flip\-model presentation, which avoids unnecessarily copying the +backbuffer by sharing surfaces with the DWM (default: yes). This may cause +performance issues with older drivers. If flip\-model presentation is not +supported (for example, on Windows 7 without the platform update), mpv will +automatically fall back to the older bitblt presentation model. +.sp +If set to \fBno\fP, the \fB\-\-angle\-swapchain\-length\fP option will have no +effect. +.sp +Windows with ANGLE only. +.TP +.B \fB\-\-angle\-renderer=<d3d9|d3d11|auto>\fP +Forces a specific renderer when using the ANGLE backend (default: auto). In +auto mode this will pick D3D11 for systems that support Direct3D 11 feature +level 9_3 or higher, and D3D9 otherwise. This option is mainly for +debugging purposes. Normally there is no reason to force a specific +renderer, though \fB\-\-angle\-renderer=d3d9\fP may give slightly better +performance on old hardware. Note that the D3D9 renderer only supports +OpenGL ES 2.0, so most extended OpenGL features will not work if this +renderer is selected (similar to \fB\-\-gpu\-dumb\-mode\fP). +.sp +Windows with ANGLE only. +.TP +.B \fB\-\-cocoa\-force\-dedicated\-gpu=<yes|no>\fP +Deactivates the automatic graphics switching and forces the dedicated GPU. +(default: no) +.sp +OS X only. +.TP +.B \fB\-\-cocoa\-cb\-sw\-renderer=<yes|no|auto>\fP +Use the Apple Software Renderer when using cocoa\-cb (default: auto). If set +to \fBno\fP the software renderer is never used and instead fails when a the +usual pixel format could not be created, \fByes\fP will always only use the +software renderer, and \fBauto\fP only falls back to the software renderer +when the usual pixel format couldn\(aqt be created. +.sp +OS X only. +.TP +.B \fB\-\-cocoa\-cb\-10bit\-context=<yes|no>\fP +Creates a 10bit capable pixel format for the context creation (default: yes). +Instead of 8bit integer framebuffer a 16bit half\-float framebuffer is +requested. +.sp +OS X only. +.TP +.B \fB\-\-macos\-title\-bar\-appearance=<appearance>\fP +Sets the appearance of the title bar (default: auto). Not all combinations +of appearances and \fB\-\-macos\-title\-bar\-material\fP materials make sense or +are unique. Appearances that are not supported by you current macOS version +fall back to the default value. +macOS and cocoa\-cb only +.sp +\fB<appearance>\fP can be one of the following: +.INDENT 7.0 +.TP +.B auto +Detects the system settings and sets the title +bar appearance appropriately. On macOS 10.14 it +also detects run time changes. +.TP +.B aqua +The standard macOS Light appearance. +.TP +.B darkAqua +The standard macOS Dark appearance. (macOS 10.14+) +.TP +.B vibrantLight +Light vibrancy appearance with. +.TP +.B vibrantDark +Dark vibrancy appearance with. +.TP +.B aquaHighContrast +Light Accessibility appearance. (macOS 10.14+) +.TP +.B darkAquaHighContrast +Dark Accessibility appearance. (macOS 10.14+) +.TP +.B vibrantLightHighContrast +Light vibrancy Accessibility appearance. +(macOS 10.14+) +.TP +.B vibrantDarkHighContrast +Dark vibrancy Accessibility appearance. +(macOS 10.14+) +.UNINDENT +.TP +.B \fB\-\-macos\-title\-bar\-material=<material>\fP +Sets the material of the title bar (default: titlebar). All deprecated +materials should not be used on macOS 10.14+ because their functionality +is not guaranteed. Not all combinations of materials and +\fB\-\-macos\-title\-bar\-appearance\fP appearances make sense or are unique. +Materials that are not supported by you current macOS version fall back to +the default value. +macOS and cocoa\-cb only +.sp +\fB<material>\fP can be one of the following: +.INDENT 7.0 +.TP +.B titlebar +The standard macOS titel bar material. +.TP +.B selection +The standard macOS selection material. +.TP +.B menu +The standard macOS menu material. (macOS 10.11+) +.TP +.B popover +The standard macOS popover material. (macOS 10.11+) +.TP +.B sidebar +The standard macOS sidebar material. (macOS 10.11+) +.TP +.B headerView +The standard macOS header view material. +(macOS 10.14+) +.TP +.B sheet +The standard macOS sheet material. (macOS 10.14+) +.TP +.B windowBackground +The standard macOS window background material. +(macOS 10.14+) +.TP +.B hudWindow +The standard macOS hudWindow material. (macOS 10.14+) +.TP +.B fullScreen +The standard macOS full screen material. +(macOS 10.14+) +.TP +.B toolTip +The standard macOS tool tip material. (macOS 10.14+) +.TP +.B contentBackground +The standard macOS content background material. +(macOS 10.14+) +.TP +.B underWindowBackground +The standard macOS under window background material. +(macOS 10.14+) +.TP +.B underPageBackground +The standard macOS under page background material. +(deprecated in macOS 10.14+) +.TP +.B dark +The standard macOS dark material. +(deprecated in macOS 10.14+) +.TP +.B light +The standard macOS light material. +(macOS 10.14+) +.TP +.B mediumLight +The standard macOS mediumLight material. +(macOS 10.11+, deprecated in macOS 10.14+) +.TP +.B ultraDark +The standard macOS ultraDark material. +(macOS 10.11+ deprecated in macOS 10.14+) +.UNINDENT +.TP +.B \fB\-\-macos\-title\-bar\-color=<color>\fP +Sets the color of the title bar (default: completely transparent). Is +influenced by \fB\-\-macos\-title\-bar\-appearance\fP and +\fB\-\-macos\-title\-bar\-material\fP\&. +See \fB\-\-sub\-color\fP for color syntax. +.TP +.B \fB\-\-macos\-fs\-animation\-duration=<default|0\-1000>\fP +Sets the fullscreen resize animation duration in ms (default: default). +The default value is slightly less than the system\(aqs animation duration +(500ms) to prevent some problems when the end of an async animation happens +at the same time as the end of the system wide fullscreen animation. Setting +anything higher than 500ms will only prematurely cancel the resize animation +after the system wide animation ended. The upper limit is still set at +1000ms since it\(aqs possible that Apple or the user changes the system +defaults. Anything higher than 1000ms though seems too long and shouldn\(aqt be +set anyway. +OS X and cocoa\-cb only +.TP +.B \fB\-\-android\-surface\-size=<WxH>\fP +Set dimensions of the rendering surface used by the Android gpu context. +Needs to be set by the embedding application if the dimensions change during +runtime (i.e. if the device is rotated), via the surfaceChanged callback. +.sp +Android with \fB\-\-gpu\-context=android\fP only. +.TP +.B \fB\-\-gpu\-sw\fP +Continue even if a software renderer is detected. +.TP +.B \fB\-\-gpu\-context=<sys>\fP +The value \fBauto\fP (the default) selects the GPU context. You can also pass +\fBhelp\fP to get a complete list of compiled in backends (sorted by +autoprobe order). +.INDENT 7.0 +.TP +.B auto +auto\-select (default) +.TP +.B cocoa +Cocoa/OS X (deprecated, use \-\-vo=opengl\-cb instead) +.TP +.B win +Win32/WGL +.TP +.B winvk +VK_KHR_win32_surface +.TP +.B angle +Direct3D11 through the OpenGL ES translation layer ANGLE. This supports +almost everything the \fBwin\fP backend does (if the ANGLE build is new +enough). +.TP +.B dxinterop (experimental) +Win32, using WGL for rendering and Direct3D 9Ex for presentation. Works +on Nvidia and AMD. Newer Intel chips with the latest drivers may also +work. +.TP +.B d3d11 +Win32, with native Direct3D 11 rendering. +.TP +.B x11 +X11/GLX +.TP +.B x11vk +VK_KHR_xlib_surface +.TP +.B wayland +Wayland/EGL +.TP +.B waylandvk +VK_KHR_wayland_surface +.TP +.B drm +DRM/EGL +.TP +.B x11egl +X11/EGL +.TP +.B android +Android/EGL. Requires \fB\-\-wid\fP be set to an \fBandroid.view.Surface\fP\&. +.TP +.B vdpauglx +Use vdpau presentation with GLX as backing. Experimental use only. +Using this will have no advantage (other than additional bugs or +performance problems), and is for doing experiments only. Will not +be used automatically. +.UNINDENT +.TP +.B \fB\-\-gpu\-api=<type>\fP +Controls which type of graphics APIs will be accepted: +.INDENT 7.0 +.TP +.B auto +Use any available API (default) +.TP +.B opengl +Allow only OpenGL (requires OpenGL 2.1+ or GLES 2.0+) +.TP +.B vulkan +Allow only Vulkan (requires a valid/working \fB\-\-spirv\-compiler\fP) +.TP +.B d3d11 +Allow only \fB\-\-gpu\-context=d3d11\fP +.UNINDENT +.TP +.B \fB\-\-opengl\-es=<mode>\fP +Controls which type of OpenGL context will be accepted: +.INDENT 7.0 +.TP +.B auto +Allow all types of OpenGL (default) +.TP +.B yes +Only allow GLES +.TP +.B no +Only allow desktop/core GL +.UNINDENT +.TP +.B \fB\-\-opengl\-restrict=<version>\fP +Restricts all OpenGL versions above a certain version. Versions are encoded +in hundreds, i.e. OpenGL 4.5 \-> 450. As an example, \-\-opengl\-restrict=300 +would restrict OpenGL 3.0 and higher, effectively only allowing 2.x +contexts. Note that this only imposes a limit on context creation APIs, the +actual OpenGL context may still have a higher OpenGL version. (Default: 0) +.TP +.B \fB\-\-fbo\-format=<fmt>\fP +Selects the internal format of textures used for FBOs. The format can +influence performance and quality of the video output. \fBfmt\fP can be one +of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f, rgba12, rgba16, rgba16f, +rgba16hf, rgba32f. +.sp +Default: \fBauto\fP, which first attempts to utilize 16bit float +(rgba16f, rgba16hf), and falls back to rgba16 if those are not available. +Finally, attempts to utilize rgb10_a2 or rgba8 if all of the previous formats +are not available. +.TP +.B \fB\-\-gamma\-factor=<0.1..2.0>\fP +Set an additional raw gamma factor (default: 1.0). If gamma is adjusted in +other ways (like with the \fB\-\-gamma\fP option or key bindings and the +\fBgamma\fP property), the value is multiplied with the other gamma value. +.sp +Recommended values based on the environmental brightness: +.INDENT 7.0 +.TP +.B 1.0 +Pitch black or dimly lit room (default) +.TP +.B 1.1 +Moderately lit room, home +.TP +.B 1.2 +Brightly illuminated room, office +.UNINDENT +.sp +NOTE: This is based around the assumptions of typical movie content, which +contains an implicit end\-to\-end of about 0.8 from scene to display. For +bright environments it can be useful to cancel that out. +.TP +.B \fB\-\-gamma\-auto\fP +Automatically corrects the gamma value depending on ambient lighting +conditions (adding a gamma boost for bright rooms). +.sp +With ambient illuminance of 16 lux, mpv will pick the 1.0 gamma value (no +boost), and slightly increase the boost up until 1.2 for 256 lux. +.sp +NOTE: Only implemented on OS X. +.TP +.B \fB\-\-target\-prim=<value>\fP +Specifies the primaries of the display. Video colors will be adapted to +this colorspace when ICC color management is not being used. Valid values +are: +.INDENT 7.0 +.TP +.B auto +Disable any adaptation, except for atypical color spaces. Specifically, +wide/unusual gamuts get automatically adapted to BT.709, while standard +gamut (i.e. BT.601 and BT.709) content is not touched. (default) +.TP +.B bt.470m +ITU\-R BT.470 M +.TP +.B bt.601\-525 +ITU\-R BT.601 (525\-line SD systems, eg. NTSC), SMPTE 170M/240M +.TP +.B bt.601\-625 +ITU\-R BT.601 (625\-line SD systems, eg. PAL/SECAM), ITU\-R BT.470 B/G +.TP +.B bt.709 +ITU\-R BT.709 (HD), IEC 61966\-2\-4 (sRGB), SMPTE RP177 Annex B +.TP +.B bt.2020 +ITU\-R BT.2020 (UHD) +.TP +.B apple +Apple RGB +.TP +.B adobe +Adobe RGB (1998) +.TP +.B prophoto +ProPhoto RGB (ROMM) +.TP +.B cie1931 +CIE 1931 RGB (not to be confused with CIE XYZ) +.TP +.B dci\-p3 +DCI\-P3 (Digital Cinema Colorspace), SMPTE RP431\-2 +.TP +.B v\-gamut +Panasonic V\-Gamut (VARICAM) primaries +.TP +.B s\-gamut +Sony S\-Gamut (S\-Log) primaries +.UNINDENT +.TP +.B \fB\-\-target\-trc=<value>\fP +Specifies the transfer characteristics (gamma) of the display. Video colors +will be adjusted to this curve when ICC color management is not being used. +Valid values are: +.INDENT 7.0 +.TP +.B auto +Disable any adaptation, except for atypical transfers. Specifically, +HDR or linear light source material gets automatically converted to +gamma 2.2, while SDR content is not touched. (default) +.TP +.B bt.1886 +ITU\-R BT.1886 curve (assuming infinite contrast) +.TP +.B srgb +IEC 61966\-2\-4 (sRGB) +.TP +.B linear +Linear light output +.TP +.B gamma1.8 +Pure power curve (gamma 1.8), also used for Apple RGB +.TP +.B gamma2.0 +Pure power curve (gamma 2.0) +.TP +.B gamma2.2 +Pure power curve (gamma 2.2) +.TP +.B gamma2.4 +Pure power curve (gamma 2.4) +.TP +.B gamma2.6 +Pure power curve (gamma 2.6) +.TP +.B gamma2.8 +Pure power curve (gamma 2.8), also used for BT.470\-BG +.TP +.B prophoto +ProPhoto RGB (ROMM) +.TP +.B pq +ITU\-R BT.2100 PQ (Perceptual quantizer) curve, aka SMPTE ST2084 +.TP +.B hlg +ITU\-R BT.2100 HLG (Hybrid Log\-gamma) curve, aka ARIB STD\-B67 +.TP +.B v\-log +Panasonic V\-Log (VARICAM) curve +.TP +.B s\-log1 +Sony S\-Log1 curve +.TP +.B s\-log2 +Sony S\-Log2 curve +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +When using HDR output formats, mpv will encode to the specified +curve but it will not set any HDMI flags or other signalling that might +be required for the target device to correctly display the HDR signal. +The user should independently guarantee this before using these signal +formats for display. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-target\-peak=<auto|nits>\fP +Specifies the measured peak brightness of the output display, in cd/m^2 +(AKA nits). The interpretation of this brightness depends on the configured +\fB\-\-target\-trc\fP\&. In all cases, it imposes a limit on the signal values +that will be sent to the display. If the source exceeds this brightness +level, a tone mapping filter will be inserted. For HLG, it has the +additional effect of parametrizing the inverse OOTF, in order to get +colorimetrically consistent results with the mastering display. For SDR, or +when using an ICC (profile (\fB\-\-icc\-profile\fP), setting this to a value +above 100 essentially causes the display to be treated as if it were an HDR +display in disguise. (See the note below) +.sp +In \fBauto\fP mode (the default), the chosen peak is an appropriate value +based on the TRC in use. For SDR curves, it uses 100. For HDR curves, it +uses 100 * the transfer function\(aqs nominal peak. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +When using an SDR transfer function, this is normally not needed, and +setting it may lead to very unexpected results. The one time it \fIis\fP +useful is if you want to calibrate a HDR display using traditional +transfer functions and calibration equipment. In such cases, you can +set your HDR display to a high brightness such as 800 cd/m^2, and then +calibrate it to a standard curve like gamma2.8. Setting this value to +800 would then instruct mpv to essentially treat it as an HDR display +with the given peak. This may be a good alternative in environments +where PQ or HLG input to the display is not possible, and makes it +possible to use HDR displays with mpv regardless of operating system +support for HDMI HDR metadata. +.sp +In such a configuration, we highly recommend setting \fB\-\-tone\-mapping\fP +to \fBmobius\fP or even \fBclip\fP\&. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-tone\-mapping=<value>\fP +Specifies the algorithm used for tone\-mapping images onto the target +display. This is relevant for both HDR\->SDR conversion as well as gamut +reduction (e.g. playing back BT.2020 content on a standard gamut display). +Valid values are: +.INDENT 7.0 +.TP +.B clip +Hard\-clip any out\-of\-range values. Use this when you care about +perfect color accuracy for in\-range values at the cost of completely +distorting out\-of\-range values. Not generally recommended. +.TP +.B mobius +Generalization of Reinhard to a Möbius transform with linear section. +Smoothly maps out\-of\-range values while retaining contrast and colors +for in\-range material as much as possible. Use this when you care about +color accuracy more than detail preservation. This is somewhere in +between \fBclip\fP and \fBreinhard\fP, depending on the value of +\fB\-\-tone\-mapping\-param\fP\&. +.TP +.B reinhard +Reinhard tone mapping algorithm. Very simple continuous curve. +Preserves overall image brightness but uses nonlinear contrast, which +results in flattening of details and degradation in color accuracy. +.TP +.B hable +Similar to \fBreinhard\fP but preserves both dark and bright details +better (slightly sigmoidal), at the cost of slightly darkening / +desaturating everything. Developed by John Hable for use in video +games. Use this when you care about detail preservation more than +color/brightness accuracy. This is roughly equivalent to +\fB\-\-tone\-mapping=reinhard \-\-tone\-mapping\-param=0.24\fP\&. If possible, +you should also enable \fB\-\-hdr\-compute\-peak\fP for the best results. +(Default) +.TP +.B gamma +Fits a logarithmic transfer between the tone curves. +.TP +.B linear +Linearly stretches the entire reference gamut to (a linear multiple of) +the display. +.UNINDENT +.TP +.B \fB\-\-tone\-mapping\-param=<value>\fP +Set tone mapping parameters. By default, this is set to the special string +\fBdefault\fP, which maps to an algorithm\-specific default value. Ignored if +the tone mapping algorithm is not tunable. This affects the following tone +mapping algorithms: +.INDENT 7.0 +.TP +.B clip +Specifies an extra linear coefficient to multiply into the signal +before clipping. Defaults to 1.0. +.TP +.B mobius +Specifies the transition point from linear to mobius transform. Every +value below this point is guaranteed to be mapped 1:1. The higher the +value, the more accurate the result will be, at the cost of losing +bright details. Defaults to 0.3, which due to the steep initial slope +still preserves in\-range colors fairly accurately. +.TP +.B reinhard +Specifies the local contrast coefficient at the display peak. Defaults +to 0.5, which means that in\-gamut values will be about half as bright +as when clipping. +.TP +.B gamma +Specifies the exponent of the function. Defaults to 1.8. +.TP +.B linear +Specifies the scale factor to use while stretching. Defaults to 1.0. +.UNINDENT +.TP +.B \fB\-\-tone\-mapping\-max\-boost=<1.0..10.0>\fP +Upper limit for how much the tone mapping algorithm is allowed to boost +the average brightness by over\-exposing the image. The default value of 1.0 +allows no additional brightness boost. A value of 2.0 would allow +over\-exposing by a factor of 2, and so on. Raising this setting can help +reveal details that would otherwise be hidden in dark scenes, but raising +it too high will make dark scenes appear unnaturally bright. +.TP +.B \fB\-\-hdr\-compute\-peak=<auto|yes|no>\fP +Compute the HDR peak and frame average brightness per\-frame instead of +relying on tagged metadata. These values are averaged over local regions as +well as over several frames to prevent the value from jittering around too +much. This option basically gives you dynamic, per\-scene tone mapping. +Requires compute shaders, which is a fairly recent OpenGL feature, and will +probably also perform horribly on some drivers, so enable at your own risk. +The special value \fBauto\fP (default) will enable HDR peak computation +automatically if compute shaders and SSBOs are supported. +.TP +.B \fB\-\-hdr\-peak\-decay\-rate=<1.0..1000.0>\fP +The decay rate used for the HDR peak detection algorithm (default: 100.0). +This is only relevant when \fB\-\-hdr\-compute\-peak\fP is enabled. Higher values +make the peak decay more slowly, leading to more stable values at the cost +of more "eye adaptation"\-like effects (although this is mitigated somewhat +by \fB\-\-hdr\-scene\-threshold\fP). A value of 1.0 (the lowest possible) disables +all averaging, meaning each frame\(aqs value is used directly as measured, +but doing this is not recommended for "noisy" sources since it may lead +to excessive flicker. (In signal theory terms, this controls the time +constant "tau" of an IIR low pass filter) +.TP +.B \fB\-\-hdr\-scene\-threshold\-low=<0.0..100.0>\fP, \fB\-\-hdr\-scene\-threshold\-high=<0.0..100.0>\fP +The lower and upper thresholds (in dB) for a brightness difference +to be considered a scene change (default: 5.5 low, 10.0 high). This is only +relevant when \fB\-\-hdr\-compute\-peak\fP is enabled. Normally, small +fluctuations in the frame brightness are compensated for by the peak +averaging mechanism, but for large jumps in the brightness this can result +in the frame remaining too bright or too dark for up to several seconds, +depending on the value of \fB\-\-hdr\-peak\-decay\-rate\fP\&. To counteract this, +when the brightness between the running average and the current frame +exceeds the low threshold, mpv will make the averaging filter more +aggressive, up to the limit of the high threshold (at which point the +filter becomes instant). +.TP +.B \fB\-\-tone\-mapping\-desaturate=<0.0..1.0>\fP +Apply desaturation for highlights (default: 0.75). The parameter controls +the strength of the desaturation curve. A value of 0.0 completely disables +it, while a value of 1.0 means that overly bright colors will tend towards +white. (This is not always the case, especially not for highlights that are +near primary colors) +.sp +Values in between apply progressively more/less aggressive desaturation. +This setting helps prevent unnaturally oversaturated colors for +super\-highlights, by (smoothly) turning them into less saturated (per +channel tone mapped) colors instead. This makes images feel more natural, +at the cost of chromatic distortions for out\-of\-range colors. The default +value of 0.75 provides a good balance. Setting this to 0.0 preserves the +chromatic accuracy of the tone mapping process. +.TP +.B \fB\-\-tone\-mapping\-desaturate\-exponent=<0.0..20.0>\fP +This setting controls the exponent of the desaturation curve, which +controls how bright a color needs to be in order to start being +desaturated. The default of 1.5 provides a reasonable balance. Decreasing +this exponent makes the curve more aggressive. +.TP +.B \fB\-\-gamut\-warning\fP +If enabled, mpv will mark all clipped/out\-of\-gamut pixels that exceed a +given threshold (currently hard\-coded to 101%). The affected pixels will be +inverted to make them stand out. Note: This option applies after the +effects of all of mpv\(aqs color space transformation / tone mapping options, +so it\(aqs a good idea to combine this with \fB\-\-tone\-mapping=clip\fP and use +\fB\-\-target\-prim\fP to set the gamut to simulate. For example, +\fB\-\-target\-prim=bt.709\fP would make mpv highlight all pixels that exceed the +gamut of a standard gamut (sRGB) display. This option also does not work +well with ICC profiles, since the 3DLUTs are always generated against the +source color space and have chromatically\-accurate clipping built in. +.TP +.B \fB\-\-use\-embedded\-icc\-profile\fP +Load the embedded ICC profile contained in media files such as PNG images. +(Default: yes). Note that this option only works when also using a display +ICC profile (\fB\-\-icc\-profile\fP or \fB\-\-icc\-profile\-auto\fP), and also +requires LittleCMS 2 support. +.TP +.B \fB\-\-icc\-profile=<file>\fP +Load an ICC profile and use it to transform video RGB to screen output. +Needs LittleCMS 2 support compiled in. This option overrides the +\fB\-\-target\-prim\fP, \fB\-\-target\-trc\fP and \fB\-\-icc\-profile\-auto\fP options. +.TP +.B \fB\-\-icc\-profile\-auto\fP +Automatically select the ICC display profile currently specified by the +display settings of the operating system. +.sp +NOTE: On Windows, the default profile must be an ICC profile. WCS profiles +are not supported. +.sp +Applications using libmpv with the render API need to provide the ICC +profile via \fBMPV_RENDER_PARAM_ICC_PROFILE\fP\&. +.TP +.B \fB\-\-icc\-cache\-dir=<dirname>\fP +Store and load the 3D LUTs created from the ICC profile in this directory. +This can be used to speed up loading, since LittleCMS 2 can take a while to +create a 3D LUT. Note that these files contain uncompressed LUTs. Their +size depends on the \fB\-\-icc\-3dlut\-size\fP, and can be very big. +.sp +NOTE: This is not cleaned automatically, so old, unused cache files may +stick around indefinitely. +.TP +.B \fB\-\-icc\-intent=<value>\fP +Specifies the ICC intent used for the color transformation (when using +\fB\-\-icc\-profile\fP). +.INDENT 7.0 +.TP +.B 0 +perceptual +.TP +.B 1 +relative colorimetric (default) +.TP +.B 2 +saturation +.TP +.B 3 +absolute colorimetric +.UNINDENT +.TP +.B \fB\-\-icc\-3dlut\-size=<r>x<g>x<b>\fP +Size of the 3D LUT generated from the ICC profile in each dimension. +Default is 64x64x64. Sizes may range from 2 to 512. +.TP +.B \fB\-\-icc\-contrast=<0\-1000000|inf>\fP +Specifies an upper limit on the target device\(aqs contrast ratio. This is +detected automatically from the profile if possible, but for some profiles +it might be missing, causing the contrast to be assumed as infinite. As a +result, video may appear darker than intended. This only affects BT.1886 +content. The default of 0 means no limit if the detected contrast is less +than 100000, and limits to 1000 otherwise. Use \fB\-\-icc\-contrast=inf\fP to +preserve the infinite contrast (most likely when using OLED displays). +.TP +.B \fB\-\-blend\-subtitles=<yes|video|no>\fP +Blend subtitles directly onto upscaled video frames, before interpolation +and/or color management (default: no). Enabling this causes subtitles to be +affected by \fB\-\-icc\-profile\fP, \fB\-\-target\-prim\fP, \fB\-\-target\-trc\fP, +\fB\-\-interpolation\fP, \fB\-\-gamma\-factor\fP and \fB\-\-glsl\-shaders\fP\&. It also +increases subtitle performance when using \fB\-\-interpolation\fP\&. +.sp +The downside of enabling this is that it restricts subtitles to the visible +portion of the video, so you can\(aqt have subtitles exist in the black +margins below a video (for example). +.sp +If \fBvideo\fP is selected, the behavior is similar to \fByes\fP, but subs are +drawn at the video\(aqs native resolution, and scaled along with the video. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +This changes the way subtitle colors are handled. Normally, +subtitle colors are assumed to be in sRGB and color managed as +such. Enabling this makes them treated as being in the video\(aqs +color space instead. This is good if you want things like +softsubbed ASS signs to match the video colors, but may cause +SRT subtitles or similar to look slightly off. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-alpha=<blend\-tiles|blend|yes|no>\fP +Decides what to do if the input has an alpha component. +.INDENT 7.0 +.TP +.B blend\-tiles +Blend the frame against a 16x16 gray/white tiles background (default). +.TP +.B blend +Blend the frame against the background color (\fB\-\-background\fP, normally +black). +.TP +.B yes +Try to create a framebuffer with alpha component. This only makes sense +if the video contains alpha information (which is extremely rare). May +not be supported on all platforms. If alpha framebuffers are +unavailable, it silently falls back on a normal framebuffer. Note that +if you set the \fB\-\-fbo\-format\fP option to a non\-default value, a +format with alpha must be specified, or this won\(aqt work. +This does not work on X11 with EGL and Mesa (freedesktop bug 67676). +.TP +.B no +Ignore alpha component. +.UNINDENT +.TP +.B \fB\-\-opengl\-rectangle\-textures\fP +Force use of rectangle textures (default: no). Normally this shouldn\(aqt have +any advantages over normal textures. Note that hardware decoding overrides +this flag. Could be removed any time. +.TP +.B \fB\-\-background=<color>\fP +Color used to draw parts of the mpv window not covered by video. See +\fB\-\-osd\-color\fP option how colors are defined. +.TP +.B \fB\-\-gpu\-tex\-pad\-x\fP, \fB\-\-gpu\-tex\-pad\-y\fP +Enlarge the video source textures by this many pixels. For debugging only +(normally textures are sized exactly, but due to hardware decoding interop +we may have to deal with additional padding, which can be tested with these +options). Could be removed any time. +.TP +.B \fB\-\-opengl\-early\-flush=<yes|no|auto>\fP +Call \fBglFlush()\fP after rendering a frame and before attempting to display +it (default: auto). Can fix stuttering in some cases, in other cases +probably causes it. The \fBauto\fP mode will call \fBglFlush()\fP only if +the renderer is going to wait for a while after rendering, instead of +flipping GL front and backbuffers immediately (i.e. it doesn\(aqt call it +in display\-sync mode). +.sp +On OSX this is always deactivated because it only causes performance +problems and other regressions. +.TP +.B \fB\-\-gpu\-dumb\-mode=<yes|no|auto>\fP +This mode is extremely restricted, and will disable most extended +features. That includes high quality scalers and custom shaders! +.sp +It is intended for hardware that does not support FBOs (including GLES, +which supports it insufficiently), or to get some more performance out of +bad or old hardware. +.sp +This mode is forced automatically if needed, and this option is mostly +useful for debugging. The default of \fBauto\fP will enable it automatically +if nothing uses features which require FBOs. +.sp +This option might be silently removed in the future. +.TP +.B \fB\-\-gpu\-shader\-cache\-dir=<dirname>\fP +Store and load compiled GLSL shaders in this directory. Normally, shader +compilation is very fast, so this is usually not needed. It mostly matters +for GPU APIs that require internally recompiling shaders to other languages, +for example anything based on ANGLE or Vulkan. Enabling this can improve +startup performance on these platforms. +.sp +NOTE: This is not cleaned automatically, so old, unused cache files may +stick around indefinitely. +.UNINDENT +.SS Miscellaneous +.INDENT 0.0 +.TP +.B \fB\-\-display\-tags=tag1,tags2,...\fP +Set the list of tags that should be displayed on the terminal. Tags that +are in the list, but are not present in the played file, will not be shown. +If a value ends with \fB*\fP, all tags are matched by prefix (though there +is no general globbing). Just passing \fB*\fP essentially filtering. +.sp +The default includes a common list of tags, call mpv with \fB\-\-list\-options\fP +to see it. +.TP +.B \fB\-\-mc=<seconds/frame>\fP +Maximum A\-V sync correction per frame (in seconds) +.TP +.B \fB\-\-autosync=<factor>\fP +Gradually adjusts the A/V sync based on audio delay measurements. +Specifying \fB\-\-autosync=0\fP, the default, will cause frame timing to be +based entirely on audio delay measurements. Specifying \fB\-\-autosync=1\fP +will do the same, but will subtly change the A/V correction algorithm. An +uneven video framerate in a video which plays fine with \fB\-\-no\-audio\fP can +often be helped by setting this to an integer value greater than 1. The +higher the value, the closer the timing will be to \fB\-\-no\-audio\fP\&. Try +\fB\-\-autosync=30\fP to smooth out problems with sound drivers which do not +implement a perfect audio delay measurement. With this value, if large A/V +sync offsets occur, they will only take about 1 or 2 seconds to settle +out. This delay in reaction time to sudden A/V offsets should be the only +side effect of turning this option on, for all sound drivers. +.TP +.B \fB\-\-video\-timing\-offset=<seconds>\fP +Control how long before video display target time the frame should be +rendered (default: 0.050). If a video frame should be displayed at a +certain time, the VO will start rendering the frame earlier, and then will +perform a blocking wait until the display time, and only then "swap" the +frame to display. The rendering cannot start before the previous frame is +displayed, so this value is implicitly limited by the video framerate. With +normal video frame rates, the default value will ensure that rendering is +always immediately started after the previous frame was displayed. On the +other hand, setting a too high value can reduce responsiveness with low +FPS value. +.sp +For client API users using the render API (or the deprecated \fBopengl\-cb\fP +API), this option is interesting, because you can stop the render API +from limiting your FPS (see \fBmpv_render_context_render()\fP documentation). +.sp +This applies only to audio timing modes (e.g. \fB\-\-video\-sync=audio\fP). In +other modes (\fB\-\-video\-sync=display\-...\fP), video timing relies on vsync +blocking, and this option is not used. +.TP +.B \fB\-\-video\-sync=<audio|...>\fP +How the player synchronizes audio and video. +.sp +If you use this option, you usually want to set it to \fBdisplay\-resample\fP +to enable a timing mode that tries to not skip or repeat frames when for +example playing 24fps video on a 24Hz screen. +.sp +The modes starting with \fBdisplay\-\fP try to output video frames completely +synchronously to the display, using the detected display vertical refresh +rate as a hint how fast frames will be displayed on average. These modes +change video speed slightly to match the display. See \fB\-\-video\-sync\-...\fP +options for fine tuning. The robustness of this mode is further reduced by +making a some idealized assumptions, which may not always apply in reality. +Behavior can depend on the VO and the system\(aqs video and audio drivers. +Media files must use constant framerate. Section\-wise VFR might work as well +with some container formats (but not e.g. mkv). +.sp +Under some circumstances, the player automatically reverts to \fBaudio\fP mode +for some time or permanently. This can happen on very low framerate video, +or if the framerate cannot be detected. +.sp +Also in display\-sync modes it can happen that interruptions to video +playback (such as toggling fullscreen mode, or simply resizing the window) +will skip the video frames that should have been displayed, while \fBaudio\fP +mode will display them after the renderer has resumed (typically resulting +in a short A/V desync and the video "catching up"). +.sp +Before mpv 0.30.0, there was a fallback to \fBaudio\fP mode on severe A/V +desync. This was changed for the sake of not sporadically stopping. Now, +\fBdisplay\-desync\fP does what it promises and may desync with audio by an +arbitrary amount, until it is manually fixed with a seek. +.sp +These modes also require a vsync blocked presentation mode. For OpenGL, this +translates to \fB\-\-opengl\-swapinterval=1\fP\&. For Vulkan, it translates to +\fB\-\-vulkan\-swap\-mode=fifo\fP (or \fBfifo\-relaxed\fP). +.sp +The modes with \fBdesync\fP in their names do not attempt to keep audio/video +in sync. They will slowly (or quickly) desync, until e.g. the next seek +happens. These modes are meant for testing, not serious use. +.INDENT 7.0 +.TP +.B audio +Time video frames to audio. This is the most robust +mode, because the player doesn\(aqt have to assume anything +about how the display behaves. The disadvantage is that +it can lead to occasional frame drops or repeats. If +audio is disabled, this uses the system clock. This is +the default mode. +.TP +.B display\-resample +Resample audio to match the video. This mode will also +try to adjust audio speed to compensate for other drift. +(This means it will play the audio at a different speed +every once in a while to reduce the A/V difference.) +.TP +.B display\-resample\-vdrop +Resample audio to match the video. Drop video +frames to compensate for drift. +.TP +.B display\-resample\-desync +Like the previous mode, but no A/V compensation. +.TP +.B display\-vdrop +Drop or repeat video frames to compensate desyncing +video. (Although it should have the same effects as +\fBaudio\fP, the implementation is very different.) +.TP +.B display\-adrop +Drop or repeat audio data to compensate desyncing +video. See \fB\-\-video\-sync\-adrop\-size\fP\&. This mode will +cause severe audio artifacts if the real monitor +refresh rate is too different from the reported or +forced rate. +.TP +.B display\-desync +Sync video to display, and let audio play on its own. +.TP +.B desync +Sync video according to system clock, and let audio play +on its own. +.UNINDENT +.TP +.B \fB\-\-video\-sync\-max\-video\-change=<value>\fP +Maximum speed difference in percent that is applied to video with +\fB\-\-video\-sync=display\-...\fP (default: 1). Display sync mode will be +disabled if the monitor and video refresh way do not match within the +given range. It tries multiples as well: playing 30 fps video on a 60 Hz +screen will duplicate every second frame. Playing 24 fps video on a 60 Hz +screen will play video in a 2\-3\-2\-3\-... pattern. +.sp +The default settings are not loose enough to speed up 23.976 fps video to +25 fps. We consider the pitch change too extreme to allow this behavior +by default. Set this option to a value of \fB5\fP to enable it. +.sp +Note that in the \fB\-\-video\-sync=display\-resample\fP mode, audio speed will +additionally be changed by a small amount if necessary for A/V sync. See +\fB\-\-video\-sync\-max\-audio\-change\fP\&. +.TP +.B \fB\-\-video\-sync\-max\-audio\-change=<value>\fP +Maximum \fIadditional\fP speed difference in percent that is applied to audio +with \fB\-\-video\-sync=display\-...\fP (default: 0.125). Normally, the player +plays the audio at the speed of the video. But if the difference between +audio and video position is too high, e.g. due to drift or other timing +errors, it will attempt to speed up or slow down audio by this additional +factor. Too low values could lead to video frame dropping or repeating if +the A/V desync cannot be compensated, too high values could lead to chaotic +frame dropping due to the audio "overshooting" and skipping multiple video +frames before the sync logic can react. +.TP +.B \fB\-\-video\-sync\-adrop\-size=<value>\fP +For the \fB\-\-video\-sync=display\-adrop\fP mode. This mode duplicates/drops +audio data to keep audio in sync with video. To avoid audio artifacts on +jitter (which would add/remove samples all the time), this is done in +relatively large, fixed units, controlled by this option. The unit is +seconds. +.TP +.B \fB\-\-mf\-fps=<value>\fP +Framerate used when decoding from multiple PNG or JPEG files with \fBmf://\fP +(default: 1). +.TP +.B \fB\-\-mf\-type=<value>\fP +Input file type for \fBmf://\fP (available: jpeg, png, tga, sgi). By default, +this is guessed from the file extension. +.TP +.B \fB\-\-stream\-dump=<destination\-filename>\fP +Instead of playing a file, read its byte stream and write it to the given +destination file. The destination is overwritten. Can be useful to test +network\-related behavior. +.TP +.B \fB\-\-stream\-lavf\-o=opt1=value1,opt2=value2,...\fP +Set AVOptions on streams opened with libavformat. Unknown or misspelled +options are silently ignored. (They are mentioned in the terminal output +in verbose mode, i.e. \fB\-\-v\fP\&. In general we can\(aqt print errors, because +other options such as e.g. user agent are not available with all protocols, +and printing errors for unknown options would end up being too noisy.) +.TP +.B \fB\-\-vo\-mmcss\-profile=<name>\fP +(Windows only.) +Set the MMCSS profile for the video renderer thread (default: \fBPlayback\fP). +.TP +.B \fB\-\-priority=<prio>\fP +(Windows only.) +Set process priority for mpv according to the predefined priorities +available under Windows. +.sp +Possible values of \fB<prio>\fP: +idle|belownormal|normal|abovenormal|high|realtime +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Using realtime priority can cause system lockup. +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-force\-media\-title=<string>\fP +Force the contents of the \fBmedia\-title\fP property to this value. Useful +for scripts which want to set a title, without overriding the user\(aqs +setting in \fB\-\-title\fP\&. +.TP +.B \fB\-\-external\-files=<file\-list>\fP +Load a file and add all of its tracks. This is useful to play different +files together (for example audio from one file, video from another), or +for advanced \fB\-\-lavfi\-complex\fP used (like playing two video files at +the same time). +.sp +Unlike \fB\-\-sub\-files\fP and \fB\-\-audio\-files\fP, this includes all tracks, and +does not cause default stream selection over the "proper" file. This makes +it slightly less intrusive. (In mpv 0.28.0 and before, this was not quite +strictly enforced.) +.sp +This is a list option. See \fI\%List Options\fP for details. +.TP +.B \fB\-\-external\-file=<file>\fP +CLI/config file only alias for \fB\-\-external\-files\-append\fP\&. Each use of this +option will add a new external files. +.TP +.B \fB\-\-autoload\-files=<yes|no>\fP +Automatically load/select external files (default: yes). +.sp +If set to \fBno\fP, then do not automatically load external files as specified +by \fB\-\-sub\-auto\fP and \fB\-\-audio\-file\-auto\fP\&. If external files are forcibly +added (like with \fB\-\-sub\-files\fP), they will not be auto\-selected. +.sp +This does not affect playlist expansion, redirection, or other loading of +referenced files like with ordered chapters. +.TP +.B \fB\-\-record\-file=<file>\fP +Deprecated, use \fB\-\-stream\-record\fP, or the \fBdump\-cache\fP command. +.sp +Record the current stream to the given target file. The target file will +always be overwritten without asking. +.sp +This was deprecated because it isn\(aqt very nice to use. For one, seeking +while this is enabled will be directly reflected in the output, which was +not useful and annoying. +.TP +.B \fB\-\-stream\-record=<file>\fP +Write received/read data from the demuxer to the given output file. The +output file will always be overwritten without asking. The output format +is determined by the extension of the output file. +.sp +Switching streams or seeking during recording might result in recording +being stopped and/or broken files. Use with care. +.sp +Seeking outside of the demuxer cache will result in "skips" in the output +file, but seeking within the demuxer cache should not affect recording. One +exception is when you seek back far enough to exceed the forward buffering +size, in which case the cache stops actively reading. This will return in +dropped data if it\(aqs a live stream. +.sp +If this is set at runtime, the old file is closed, and the new file is +opened. Note that this will write only data that is appended at the end of +the cache, and the already cached data cannot be written. You can try the +\fBdump\-cache\fP command as an alternative. +.sp +External files (\fB\-\-audio\-file\fP etc.) are ignored by this, it works on the +"main" file only. Using this with files using ordered chapters or EDL files +will also not work correctly in general. +.sp +There are some glitches with this because it uses FFmpeg\(aqs libavformat for +writing the output file. For example, it\(aqs typical that it will only work if +the output format is the same as the input format. This is the case even if +it works with the \fBffmpeg\fP tool. One reason for this is that \fBffmpeg\fP +and its libraries contain certain hacks and workarounds for these issues, +that are unavailable to outside users. +.sp +This replaces \fB\-\-record\-file\fP\&. It is similar to the ancient/removed +\fB\-\-stream\-capture\fP/\fB\-capture\fP options, and provides better behavior in +most cases (i.e. actually works). +.TP +.B \fB\-\-lavfi\-complex=<string>\fP +Set a "complex" libavfilter filter, which means a single filter graph can +take input from multiple source audio and video tracks. The graph can result +in a single audio or video output (or both). +.sp +Currently, the filter graph labels are used to select the participating +input tracks and audio/video output. The following rules apply: +.INDENT 7.0 +.IP \(bu 2 +A label of the form \fBaidN\fP selects audio track N as input (e.g. +\fBaid1\fP). +.IP \(bu 2 +A label of the form \fBvidN\fP selects video track N as input. +.IP \(bu 2 +A label named \fBao\fP will be connected to the audio output. +.IP \(bu 2 +A label named \fBvo\fP will be connected to the video output. +.UNINDENT +.sp +Each label can be used only once. If you want to use e.g. an audio stream +for multiple filters, you need to use the \fBasplit\fP filter. Multiple +video or audio outputs are not possible, but you can use filters to merge +them into one. +.sp +It\(aqs not possible to change the tracks connected to the filter at runtime, +unless you explicitly change the \fBlavfi\-complex\fP property and set new +track assignments. When the graph is changed, the track selection is changed +according to the used labels as well. +.sp +Other tracks, as long as they\(aqre not connected to the filter, and the +corresponding output is not connected to the filter, can still be freely +changed with the normal methods. +.sp +Note that the normal filter chains (\fB\-\-af\fP, \fB\-\-vf\fP) are applied between +the complex graphs (e.g. \fBao\fP label) and the actual output. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-lavfi\-complex=\(aq[aid1] [aid2] amix [ao]\(aq\fP +Play audio track 1 and 2 at the same time. +.IP \(bu 2 +\fB\-\-lavfi\-complex=\(aq[vid1] [vid2] vstack [vo]\(aq\fP +Stack video track 1 and 2 and play them at the same time. Note that +both tracks need to have the same width, or filter initialization +will fail (you can add \fBscale\fP filters before the \fBvstack\fP filter +to fix the size). +To load a video track from another file, you can use +\fB\-\-external\-file=other.mkv\fP\&. +.IP \(bu 2 +\fB\-\-lavfi\-complex=\(aq[aid1] asplit [t1] [ao] ; [t1] showvolume [t2] ; [vid1] [t2] overlay [vo]\(aq\fP +Play audio track 1, and overlay the measured volume for each speaker +over video track 1. +.IP \(bu 2 +\fBnull:// \-\-lavfi\-complex=\(aqlife [vo]\(aq\fP +A libavfilter source\-only filter (Conways\(aq Life Game). +.UNINDENT +.UNINDENT +.UNINDENT +.sp +See the FFmpeg libavfilter documentation for details on the available +filters. +.UNINDENT +.SH AUDIO OUTPUT DRIVERS +.sp +Audio output drivers are interfaces to different audio output facilities. The +syntax is: +.INDENT 0.0 +.TP +.B \fB\-\-ao=<driver1,driver2,...[,]>\fP +Specify a priority list of audio output drivers to be used. +.UNINDENT +.sp +If the list has a trailing \(aq,\(aq, mpv will fall back on drivers not contained +in the list. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +See \fB\-\-ao=help\fP for a list of compiled\-in audio output drivers. The +driver \fB\-\-ao=alsa\fP is preferred. \fB\-\-ao=pulse\fP is preferred on systems +where PulseAudio is used. On BSD systems, \fB\-\-ao=oss\fP or \fB\-\-ao=sndio\fP +may work (the latter being experimental). +.UNINDENT +.UNINDENT +.sp +Available audio output drivers are: +.INDENT 0.0 +.TP +.B \fBalsa\fP (Linux only) +ALSA audio output driver +.sp +See \fI\%ALSA audio output options\fP for options specific to this AO. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +To get multichannel/surround audio, use \fB\-\-audio\-channels=auto\fP\&. The +default for this option is \fBauto\-safe\fP, which makes this audio output +explicitly reject multichannel output, as there is no way to detect +whether a certain channel layout is actually supported. +.sp +You can also try \fI\%using the upmix plugin\fP\&. +This setup enables multichannel audio on the \fBdefault\fP device +with automatic upmixing with shared access, so playing stereo +and multichannel audio at the same time will work as expected. +.UNINDENT +.UNINDENT +.TP +.B \fBoss\fP +OSS audio output driver +.sp +The following global options are supported by this audio output: +.INDENT 7.0 +.TP +.B \fB\-\-oss\-mixer\-device\fP +Sets the audio mixer device (default: \fB/dev/mixer\fP). +.TP +.B \fB\-\-oss\-mixer\-channel\fP +Sets the audio mixer channel (default: \fBpcm\fP). Other valid values +include \fBvol, pcm, line\fP\&. For a complete list of options look for +\fBSOUND_DEVICE_NAMES\fP in \fB/usr/include/linux/soundcard.h\fP\&. +.UNINDENT +.TP +.B \fBjack\fP +JACK (Jack Audio Connection Kit) audio output driver. +.sp +The following global options are supported by this audio output: +.INDENT 7.0 +.TP +.B \fB\-\-jack\-port=<name>\fP +Connects to the ports with the given name (default: physical ports). +.TP +.B \fB\-\-jack\-name=<client>\fP +Client name that is passed to JACK (default: \fBmpv\fP). Useful +if you want to have certain connections established automatically. +.TP +.B \fB\-\-jack\-autostart=<yes|no>\fP +Automatically start jackd if necessary (default: disabled). Note that +this tends to be unreliable and will flood stdout with server messages. +.TP +.B \fB\-\-jack\-connect=<yes|no>\fP +Automatically create connections to output ports (default: enabled). +When enabled, the maximum number of output channels will be limited to +the number of available output ports. +.TP +.B \fB\-\-jack\-std\-channel\-layout=<waveext|any>\fP +Select the standard channel layout (default: waveext). JACK itself has no +notion of channel layouts (i.e. assigning which speaker a given +channel is supposed to map to) \- it just takes whatever the application +outputs, and reroutes it to whatever the user defines. This means the +user and the application are in charge of dealing with the channel +layout. \fBwaveext\fP uses WAVE_FORMAT_EXTENSIBLE order, which, even +though it was defined by Microsoft, is the standard on many systems. +The value \fBany\fP makes JACK accept whatever comes from the audio +filter chain, regardless of channel layout and without reordering. This +mode is probably not very useful, other than for debugging or when used +with fixed setups. +.UNINDENT +.TP +.B \fBcoreaudio\fP (Mac OS X only) +Native Mac OS X audio output driver using AudioUnits and the CoreAudio +sound server. +.sp +Automatically redirects to \fBcoreaudio_exclusive\fP when playing compressed +formats. +.sp +The following global options are supported by this audio output: +.INDENT 7.0 +.TP +.B \fB\-\-coreaudio\-change\-physical\-format=<yes|no>\fP +Change the physical format to one similar to the requested audio format +(default: no). This has the advantage that multichannel audio output +will actually work. The disadvantage is that it will change the +system\-wide audio settings. This is equivalent to changing the \fBFormat\fP +setting in the \fBAudio Devices\fP dialog in the \fBAudio MIDI Setup\fP +utility. Note that this does not affect the selected speaker setup. +.TP +.B \fB\-\-coreaudio\-spdif\-hack=<yes|no>\fP +Try to pass through AC3/DTS data as PCM. This is useful for drivers +which do not report AC3 support. It converts the AC3 data to float, +and assumes the driver will do the inverse conversion, which means +a typical A/V receiver will pick it up as compressed IEC framed AC3 +stream, ignoring that it\(aqs marked as PCM. This disables normal AC3 +passthrough (even if the device reports it as supported). Use with +extreme care. +.UNINDENT +.TP +.B \fBcoreaudio_exclusive\fP (Mac OS X only) +Native Mac OS X audio output driver using direct device access and +exclusive mode (bypasses the sound server). +.TP +.B \fBopenal\fP +OpenAL audio output driver +.INDENT 7.0 +.TP +.B \fB\-\-openal\-num\-buffers=<2\-128>\fP +Specify the number of audio buffers to use. Lower values are better for +lower CPU usage. Default: 4. +.TP +.B \fB\-\-openal\-num\-samples=<256\-32768>\fP +Specify the number of complete samples to use for each buffer. Higher +values are better for lower CPU usage. Default: 8192. +.TP +.B \fB\-\-openal\-direct\-channels=<yes|no>\fP +Enable OpenAL Soft\(aqs direct channel extension when available to avoid +tinting the sound with ambisonics or HRTF. +Channels are dropped when when they are not available as downmixing +will be disabled. Default: no. +.UNINDENT +.TP +.B \fBpulse\fP +PulseAudio audio output driver +.sp +The following global options are supported by this audio output: +.INDENT 7.0 +.TP +.B \fB\-\-pulse\-host=<host>\fP +Specify the host to use. An empty <host> string uses a local connection, +"localhost" uses network transfer (most likely not what you want). +.TP +.B \fB\-\-pulse\-buffer=<1\-2000|native>\fP +Set the audio buffer size in milliseconds. A higher value buffers +more data, and has a lower probability of buffer underruns. A smaller +value makes the audio stream react faster, e.g. to playback speed +changes. +.TP +.B \fB\-\-pulse\-latency\-hacks=<yes|no>\fP +Enable hacks to workaround PulseAudio timing bugs (default: no). If +enabled, mpv will do elaborate latency calculations on its own. If +disabled, it will use PulseAudio automatically updated timing +information. Disabling this might help with e.g. networked audio or +some plugins, while enabling it might help in some unknown situations +(it used to be required to get good behavior on old PulseAudio versions). +.sp +If you have stuttering video when using pulse, try to enable this +option. (Or try to update PulseAudio.) +.TP +.B \fB\-\-pulse\-allow\-suspended=<yes|no>\fP +Allow mpv to use PulseAudio even if the sink is suspended (default: no). +Can be useful if PulseAudio is running as a bridge to jack and mpv has its sink\-input set to the one jack is using. +.UNINDENT +.TP +.B \fBsdl\fP +SDL 1.2+ audio output driver. Should work on any platform supported by SDL +1.2, but may require the \fBSDL_AUDIODRIVER\fP environment variable to be set +appropriately for your system. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This driver is for compatibility with extremely foreign +environments, such as systems where none of the other drivers +are available. +.UNINDENT +.UNINDENT +.sp +The following global options are supported by this audio output: +.INDENT 7.0 +.TP +.B \fB\-\-sdl\-buflen=<length>\fP +Sets the audio buffer length in seconds. Is used only as a hint by the +sound system. Playing a file with \fB\-v\fP will show the requested and +obtained exact buffer size. A value of 0 selects the sound system +default. +.TP +.B \fB\-\-sdl\-bufcnt=<count>\fP +Sets the number of extra audio buffers in mpv. Usually needs not be +changed. +.UNINDENT +.TP +.B \fBnull\fP +Produces no audio output but maintains video playback speed. You can use +\fB\-\-ao=null \-\-ao\-null\-untimed\fP for benchmarking. +.sp +The following global options are supported by this audio output: +.INDENT 7.0 +.TP +.B \fB\-\-ao\-null\-untimed\fP +Do not simulate timing of a perfect audio device. This means audio +decoding will go as fast as possible, instead of timing it to the +system clock. +.TP +.B \fB\-\-ao\-null\-buffer\fP +Simulated buffer length in seconds. +.TP +.B \fB\-\-ao\-null\-outburst\fP +Simulated chunk size in samples. +.TP +.B \fB\-\-ao\-null\-speed\fP +Simulated audio playback speed as a multiplier. Usually, a real audio +device will not go exactly as fast as the system clock. It will deviate +just a little, and this option helps to simulate this. +.TP +.B \fB\-\-ao\-null\-latency\fP +Simulated device latency. This is additional to EOF. +.TP +.B \fB\-\-ao\-null\-broken\-eof\fP +Simulate broken audio drivers, which always add the fixed device +latency to the reported audio playback position. +.TP +.B \fB\-\-ao\-null\-broken\-delay\fP +Simulate broken audio drivers, which don\(aqt report latency correctly. +.TP +.B \fB\-\-ao\-null\-channel\-layouts\fP +If not empty, this is a \fB,\fP separated list of channel layouts the +AO allows. This can be used to test channel layout selection. +.TP +.B \fB\-\-ao\-null\-format\fP +Force the audio output format the AO will accept. If unset accepts any. +.UNINDENT +.TP +.B \fBpcm\fP +Raw PCM/WAVE file writer audio output +.sp +The following global options are supported by this audio output: +.INDENT 7.0 +.TP +.B \fB\-\-ao\-pcm\-waveheader=<yes|no>\fP +Include or do not include the WAVE header (default: included). When +not included, raw PCM will be generated. +.TP +.B \fB\-\-ao\-pcm\-file=<filename>\fP +Write the sound to \fB<filename>\fP instead of the default +\fBaudiodump.wav\fP\&. If \fBno\-waveheader\fP is specified, the default is +\fBaudiodump.pcm\fP\&. +.TP +.B \fB\-\-ao\-pcm\-append=<yes|no>\fP +Append to the file, instead of overwriting it. Always use this with the +\fBno\-waveheader\fP option \- with \fBwaveheader\fP it\(aqs broken, because +it will write a WAVE header every time the file is opened. +.UNINDENT +.TP +.B \fBrsound\fP +Audio output to an RSound daemon. Use \fB\-\-audio\-device=rsound/<hostname>\fP +to set the host name (with \fB<hostname>\fP replaced, without the \fB< >\fP). +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Completely useless, unless you intend to run RSound. Not to be +confused with RoarAudio, which is something completely +different. +.UNINDENT +.UNINDENT +.TP +.B \fBsndio\fP +Audio output to the OpenBSD sndio sound system +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Experimental. There are known bugs and issues. +.UNINDENT +.UNINDENT +.sp +(Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel +layouts.) +.TP +.B \fBwasapi\fP +Audio output to the Windows Audio Session API. +.UNINDENT +.SH VIDEO OUTPUT DRIVERS +.sp +Video output drivers are interfaces to different video output facilities. The +syntax is: +.INDENT 0.0 +.TP +.B \fB\-\-vo=<driver1,driver2,...[,]>\fP +Specify a priority list of video output drivers to be used. +.UNINDENT +.sp +If the list has a trailing \fB,\fP, mpv will fall back on drivers not contained +in the list. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +See \fB\-\-vo=help\fP for a list of compiled\-in video output drivers. +.sp +The recommended output driver is \fB\-\-vo=gpu\fP, which is the default. All +other drivers are for compatibility or special purposes. If the default +does not work, it will fallback to other drivers (in the same order as +listed by \fB\-\-vo=help\fP). +.UNINDENT +.UNINDENT +.sp +Available video output drivers are: +.INDENT 0.0 +.TP +.B \fBxv\fP (X11 only) +Uses the XVideo extension to enable hardware\-accelerated display. This is +the most compatible VO on X, but may be low\-quality, and has issues with +OSD and subtitle display. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This driver is for compatibility with old systems. +.UNINDENT +.UNINDENT +.sp +The following global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-xv\-adaptor=<number>\fP +Select a specific XVideo adapter (check xvinfo results). +.TP +.B \fB\-\-xv\-port=<number>\fP +Select a specific XVideo port. +.TP +.B \fB\-\-xv\-ck=<cur|use|set>\fP +Select the source from which the color key is taken (default: cur). +.INDENT 7.0 +.TP +.B cur +The default takes the color key currently set in Xv. +.TP +.B use +Use but do not set the color key from mpv (use the \fB\-\-colorkey\fP +option to change it). +.TP +.B set +Same as use but also sets the supplied color key. +.UNINDENT +.TP +.B \fB\-\-xv\-ck\-method=<none|man|bg|auto>\fP +Sets the color key drawing method (default: man). +.INDENT 7.0 +.TP +.B none +Disables color\-keying. +.TP +.B man +Draw the color key manually (reduces flicker in some cases). +.TP +.B bg +Set the color key as window background. +.TP +.B auto +Let Xv draw the color key. +.UNINDENT +.TP +.B \fB\-\-xv\-colorkey=<number>\fP +Changes the color key to an RGB value of your choice. \fB0x000000\fP is +black and \fB0xffffff\fP is white. +.TP +.B \fB\-\-xv\-buffers=<number>\fP +Number of image buffers to use for the internal ringbuffer (default: 2). +Increasing this will use more memory, but might help with the X server +not responding quickly enough if video FPS is close to or higher than +the display refresh rate. +.UNINDENT +.TP +.B \fBx11\fP (X11 only) +Shared memory video output driver without hardware acceleration that works +whenever X11 is present. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This is a fallback only, and should not be normally used. +.UNINDENT +.UNINDENT +.TP +.B \fBvdpau\fP (X11 only) +Uses the VDPAU interface to display and optionally also decode video. +Hardware decoding is used with \fB\-\-hwdec=vdpau\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Earlier versions of mpv (and MPlayer, mplayer2) provided sub\-options +to tune vdpau post\-processing, like \fBdeint\fP, \fBsharpen\fP, \fBdenoise\fP, +\fBchroma\-deint\fP, \fBpullup\fP, \fBhqscaling\fP\&. These sub\-options are +deprecated, and you should use the \fBvdpaupp\fP video filter instead. +.UNINDENT +.UNINDENT +.sp +The following global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-vo\-vdpau\-sharpen=<\-1\-1>\fP +(Deprecated. See note about \fBvdpaupp\fP\&.) +.sp +For positive values, apply a sharpening algorithm to the video, for +negative values a blurring algorithm (default: 0). +.TP +.B \fB\-\-vo\-vdpau\-denoise=<0\-1>\fP +(Deprecated. See note about \fBvdpaupp\fP\&.) +.sp +Apply a noise reduction algorithm to the video (default: 0; no noise +reduction). +.TP +.B \fB\-\-vo\-vdpau\-deint=<\-4\-4>\fP +(Deprecated. See note about \fBvdpaupp\fP\&.) +.sp +Select deinterlacing mode (default: 0). In older versions (as well as +MPlayer/mplayer2) you could use this option to enable deinterlacing. +This doesn\(aqt work anymore, and deinterlacing is enabled with either +the \fBd\fP key (by default mapped to the command \fBcycle deinterlace\fP), +or the \fB\-\-deinterlace\fP option. Also, to select the default deint mode, +you should use something like \fB\-\-vf\-defaults=vdpaupp:deint\-mode=temporal\fP +instead of this sub\-option. +.INDENT 7.0 +.TP +.B 0 +Pick the \fBvdpaupp\fP video filter default, which corresponds to 3. +.TP +.B 1 +Show only first field. +.TP +.B 2 +Bob deinterlacing. +.TP +.B 3 +Motion\-adaptive temporal deinterlacing. May lead to A/V desync +with slow video hardware and/or high resolution. +.TP +.B 4 +Motion\-adaptive temporal deinterlacing with edge\-guided spatial +interpolation. Needs fast video hardware. +.UNINDENT +.TP +.B \fB\-\-vo\-vdpau\-chroma\-deint\fP +(Deprecated. See note about \fBvdpaupp\fP\&.) +.sp +Makes temporal deinterlacers operate both on luma and chroma (default). +Use no\-chroma\-deint to solely use luma and speed up advanced +deinterlacing. Useful with slow video memory. +.TP +.B \fB\-\-vo\-vdpau\-pullup\fP +(Deprecated. See note about \fBvdpaupp\fP\&.) +.sp +Try to apply inverse telecine, needs motion adaptive temporal +deinterlacing. +.TP +.B \fB\-\-vo\-vdpau\-hqscaling=<0\-9>\fP +(Deprecated. See note about \fBvdpaupp\fP\&.) +.INDENT 7.0 +.TP +.B 0 +Use default VDPAU scaling (default). +.TP +.B 1\-9 +Apply high quality VDPAU scaling (needs capable hardware). +.UNINDENT +.TP +.B \fB\-\-vo\-vdpau\-fps=<number>\fP +Override autodetected display refresh rate value (the value is needed +for framedrop to allow video playback rates higher than display +refresh rate, and for vsync\-aware frame timing adjustments). Default 0 +means use autodetected value. A positive value is interpreted as a +refresh rate in Hz and overrides the autodetected value. A negative +value disables all timing adjustment and framedrop logic. +.TP +.B \fB\-\-vo\-vdpau\-composite\-detect\fP +NVIDIA\(aqs current VDPAU implementation behaves somewhat differently +under a compositing window manager and does not give accurate frame +timing information. With this option enabled, the player tries to +detect whether a compositing window manager is active. If one is +detected, the player disables timing adjustments as if the user had +specified \fBfps=\-1\fP (as they would be based on incorrect input). This +means timing is somewhat less accurate than without compositing, but +with the composited mode behavior of the NVIDIA driver, there is no +hard playback speed limit even without the disabled logic. Enabled by +default, use \fB\-\-vo\-vdpau\-composite\-detect=no\fP to disable. +.TP +.B \fB\-\-vo\-vdpau\-queuetime\-windowed=<number>\fP and \fBqueuetime\-fs=<number>\fP +Use VDPAU\(aqs presentation queue functionality to queue future video +frame changes at most this many milliseconds in advance (default: 50). +See below for additional information. +.TP +.B \fB\-\-vo\-vdpau\-output\-surfaces=<2\-15>\fP +Allocate this many output surfaces to display video frames (default: +3). See below for additional information. +.TP +.B \fB\-\-vo\-vdpau\-colorkey=<#RRGGBB|#AARRGGBB>\fP +Set the VDPAU presentation queue background color, which in practice +is the colorkey used if VDPAU operates in overlay mode (default: +\fB#020507\fP, some shade of black). If the alpha component of this value +is 0, the default VDPAU colorkey will be used instead (which is usually +green). +.TP +.B \fB\-\-vo\-vdpau\-force\-yuv\fP +Never accept RGBA input. This means mpv will insert a filter to convert +to a YUV format before the VO. Sometimes useful to force availability +of certain YUV\-only features, like video equalizer or deinterlacing. +.UNINDENT +.sp +Using the VDPAU frame queuing functionality controlled by the queuetime +options makes mpv\(aqs frame flip timing less sensitive to system CPU load and +allows mpv to start decoding the next frame(s) slightly earlier, which can +reduce jitter caused by individual slow\-to\-decode frames. However, the +NVIDIA graphics drivers can make other window behavior such as window moves +choppy if VDPAU is using the blit queue (mainly happens if you have the +composite extension enabled) and this feature is active. If this happens on +your system and it bothers you then you can set the queuetime value to 0 to +disable this feature. The settings to use in windowed and fullscreen mode +are separate because there should be no reason to disable this for +fullscreen mode (as the driver issue should not affect the video itself). +.sp +You can queue more frames ahead by increasing the queuetime values and the +\fBoutput_surfaces\fP count (to ensure enough surfaces to buffer video for a +certain time ahead you need at least as many surfaces as the video has +frames during that time, plus two). This could help make video smoother in +some cases. The main downsides are increased video RAM requirements for +the surfaces and laggier display response to user commands (display +changes only become visible some time after they\(aqre queued). The graphics +driver implementation may also have limits on the length of maximum +queuing time or number of queued surfaces that work well or at all. +.TP +.B \fBdirect3d\fP (Windows only) +Video output driver that uses the Direct3D interface. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This driver is for compatibility with systems that don\(aqt provide +proper OpenGL drivers, and where ANGLE does not perform well. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Before to 0.21.0, \fBdirect3d_shaders\fP and \fBdirect3d\fP were +different, with \fBdirect3d\fP not using shader by default. Now +both use shaders by default, and \fBdirect3d_shaders\fP is a +deprecated alias. Use the \fB\-\-vo\-direct3d\-prefer\-stretchrect\fP +or the \fB\-\-vo\-direct3d\-disable\-shaders\fP options to get the old +behavior of \fBdirect3d\fP\&. +.UNINDENT +.UNINDENT +.sp +The following global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-vo\-direct3d\-prefer\-stretchrect\fP +Use \fBIDirect3DDevice9::StretchRect\fP over other methods if possible. +.TP +.B \fB\-\-vo\-direct3d\-disable\-stretchrect\fP +Never render the video using \fBIDirect3DDevice9::StretchRect\fP\&. +.TP +.B \fB\-\-vo\-direct3d\-disable\-textures\fP +Never render the video using D3D texture rendering. Rendering with +textures + shader will still be allowed. Add \fBdisable\-shaders\fP to +completely disable video rendering with textures. +.TP +.B \fB\-\-vo\-direct3d\-disable\-shaders\fP +Never use shaders when rendering video. +.TP +.B \fB\-\-vo\-direct3d\-only\-8bit\fP +Never render YUV video with more than 8 bits per component. +Using this flag will force software conversion to 8\-bit. +.TP +.B \fB\-\-vo\-direct3d\-disable\-texture\-align\fP +Normally texture sizes are always aligned to 16. With this option +enabled, the video texture will always have exactly the same size as +the video itself. +.UNINDENT +.sp +Debug options. These might be incorrect, might be removed in the future, +might crash, might cause slow downs, etc. Contact the developers if you +actually need any of these for performance or proper operation. +.INDENT 7.0 +.TP +.B \fB\-\-vo\-direct3d\-force\-power\-of\-2\fP +Always force textures to power of 2, even if the device reports +non\-power\-of\-2 texture sizes as supported. +.TP +.B \fB\-\-vo\-direct3d\-texture\-memory=<mode>\fP +Only affects operation with shaders/texturing enabled, and (E)OSD. +Possible values: +.INDENT 7.0 +.TP +.B \fBdefault\fP (default) +Use \fBD3DPOOL_DEFAULT\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for +locking. If the driver supports \fBD3DDEVCAPS_TEXTURESYSTEMMEMORY\fP, +\fBD3DPOOL_SYSTEMMEM\fP is used directly. +.TP +.B \fBdefault\-pool\fP +Use \fBD3DPOOL_DEFAULT\fP\&. (Like \fBdefault\fP, but never use a +shadow\-texture.) +.TP +.B \fBdefault\-pool\-shadow\fP +Use \fBD3DPOOL_DEFAULT\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for +locking. (Like \fBdefault\fP, but always force the shadow\-texture.) +.TP +.B \fBmanaged\fP +Use \fBD3DPOOL_MANAGED\fP\&. +.TP +.B \fBscratch\fP +Use \fBD3DPOOL_SCRATCH\fP, with a \fBD3DPOOL_SYSTEMMEM\fP texture for +locking. +.UNINDENT +.TP +.B \fB\-\-vo\-direct3d\-swap\-discard\fP +Use \fBD3DSWAPEFFECT_DISCARD\fP, which might be faster. +Might be slower too, as it must(?) clear every frame. +.TP +.B \fB\-\-vo\-direct3d\-exact\-backbuffer\fP +Always resize the backbuffer to window size. +.UNINDENT +.TP +.B \fBgpu\fP +General purpose, customizable, GPU\-accelerated video output driver. It +supports extended scaling methods, dithering, color management, custom +shaders, HDR, and more. +.sp +See \fI\%GPU renderer options\fP for options specific to this VO. +.sp +By default, it tries to use fast and fail\-safe settings. Use the +\fBgpu\-hq\fP profile to use this driver with defaults set to high quality +rendering. The profile can be applied with \fB\-\-profile=gpu\-hq\fP and its +contents can be viewed with \fB\-\-show\-profile=gpu\-hq\fP\&. +.sp +This VO abstracts over several possible graphics APIs and windowing +contexts, which can be influenced using the \fB\-\-gpu\-api\fP and +\fB\-\-gpu\-context\fP options. +.sp +Hardware decoding over OpenGL\-interop is supported to some degree. Note +that in this mode, some corner case might not be gracefully handled, and +color space conversion and chroma upsampling is generally in the hand of +the hardware decoder APIs. +.sp +\fBgpu\fP makes use of FBOs by default. Sometimes you can achieve better +quality or performance by changing the \fB\-\-gpu\-fbo\-format\fP option to +\fBrgb16f\fP, \fBrgb32f\fP or \fBrgb\fP\&. Known problems include Mesa/Intel not +accepting \fBrgb16\fP, Mesa sometimes not being compiled with float texture +support, and some OS X setups being very slow with \fBrgb16\fP but fast +with \fBrgb32f\fP\&. If you have problems, you can also try enabling the +\fB\-\-gpu\-dumb\-mode=yes\fP option. +.TP +.B \fBsdl\fP +SDL 2.0+ Render video output driver, depending on system with or without +hardware acceleration. Should work on all platforms supported by SDL 2.0. +For tuning, refer to your copy of the file \fBSDL_hints.h\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This driver is for compatibility with systems that don\(aqt provide +proper graphics drivers. +.UNINDENT +.UNINDENT +.sp +The following global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-sdl\-sw\fP +Continue even if a software renderer is detected. +.TP +.B \fB\-\-sdl\-switch\-mode\fP +Instruct SDL to switch the monitor video mode when going fullscreen. +.UNINDENT +.TP +.B \fBvaapi\fP +Intel VA API video output driver with support for hardware decoding. Note +that there is absolutely no reason to use this, other than compatibility. +This is low quality, and has issues with OSD. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This driver is for compatibility with crappy systems. You can +use vaapi hardware decoding with \fB\-\-vo=gpu\fP too. +.UNINDENT +.UNINDENT +.sp +The following global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-vo\-vaapi\-scaling=<algorithm>\fP +.INDENT 7.0 +.TP +.B default +Driver default (mpv default as well). +.TP +.B fast +Fast, but low quality. +.TP +.B hq +Unspecified driver dependent high\-quality scaling, slow. +.TP +.B nla +\fBnon\-linear anamorphic scaling\fP +.UNINDENT +.TP +.B \fB\-\-vo\-vaapi\-deint\-mode=<mode>\fP +Select deinterlacing algorithm. Note that by default deinterlacing is +initially always off, and needs to be enabled with the \fBd\fP key +(default key binding for \fBcycle deinterlace\fP). +.sp +This option doesn\(aqt apply if libva supports video post processing (vpp). +In this case, the default for \fBdeint\-mode\fP is \fBno\fP, and enabling +deinterlacing via user interaction using the methods mentioned above +actually inserts the \fBvavpp\fP video filter. If vpp is not actually +supported with the libva backend in use, you can use this option to +forcibly enable VO based deinterlacing. +.INDENT 7.0 +.TP +.B no +Don\(aqt allow deinterlacing (default for newer libva). +.TP +.B first\-field +Show only first field. +.TP +.B bob +bob deinterlacing (default for older libva). +.UNINDENT +.TP +.B \fB\-\-vo\-vaapi\-scaled\-osd=<yes|no>\fP +If enabled, then the OSD is rendered at video resolution and scaled to +display resolution. By default, this is disabled, and the OSD is +rendered at display resolution if the driver supports it. +.UNINDENT +.TP +.B \fBnull\fP +Produces no video output. Useful for benchmarking. +.sp +Usually, it\(aqs better to disable video with \fB\-\-no\-video\fP instead. +.sp +The following global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-vo\-null\-fps=<value>\fP +Simulate display FPS. This artificially limits how many frames the +VO accepts per second. +.UNINDENT +.TP +.B \fBcaca\fP +Color ASCII art video output driver that works on a text console. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This driver is a joke. +.UNINDENT +.UNINDENT +.TP +.B \fBtct\fP +Color Unicode art video output driver that works on a text console. +Depends on support of true color by modern terminals to display the images +at full color range. On Windows it requires an ansi terminal such as mintty. +.INDENT 7.0 +.TP +.B \fB\-\-vo\-tct\-algo=<algo>\fP +Select how to write the pixels to the terminal. +.INDENT 7.0 +.TP +.B half\-blocks +Uses unicode LOWER HALF BLOCK character to achieve higher vertical +resolution. (Default.) +.TP +.B plain +Uses spaces. Causes vertical resolution to drop twofolds, but in +theory works in more places. +.UNINDENT +.TP +.B \fB\-\-vo\-tct\-width=<width>\fP \fB\-\-vo\-tct\-height=<height>\fP +Assume the terminal has the specified character width and/or height. +These default to 80x25 if the terminal size cannot be determined. +.TP +.B \fB\-\-vo\-tct\-256=<yes|no>\fP (default: no) +Use 256 colors \- for terminals which don\(aqt support true color. +.UNINDENT +.TP +.B \fBimage\fP +Output each frame into an image file in the current directory. Each file +takes the frame number padded with leading zeros as name. +.sp +The following global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-vo\-image\-format=<format>\fP +Select the image file format. +.INDENT 7.0 +.TP +.B jpg +JPEG files, extension .jpg. (Default.) +.TP +.B jpeg +JPEG files, extension .jpeg. +.TP +.B png +PNG files. +.TP +.B webp +WebP files. +.UNINDENT +.TP +.B \fB\-\-vo\-image\-png\-compression=<0\-9>\fP +PNG compression factor (speed vs. file size tradeoff) (default: 7) +.TP +.B \fB\-\-vo\-image\-png\-filter=<0\-5>\fP +Filter applied prior to PNG compression (0 = none; 1 = sub; 2 = up; +3 = average; 4 = Paeth; 5 = mixed) (default: 5) +.TP +.B \fB\-\-vo\-image\-jpeg\-quality=<0\-100>\fP +JPEG quality factor (default: 90) +.TP +.B \fB\-\-vo\-image\-jpeg\-optimize=<0\-100>\fP +JPEG optimization factor (default: 100) +.TP +.B \fB\-\-vo\-image\-webp\-lossless=<yes|no>\fP +Enable writing lossless WebP files (default: no) +.TP +.B \fB\-\-vo\-image\-webp\-quality=<0\-100>\fP +WebP quality (default: 75) +.TP +.B \fB\-\-vo\-image\-webp\-compression=<0\-6>\fP +WebP compression factor (default: 4) +.TP +.B \fB\-\-vo\-image\-outdir=<dirname>\fP +Specify the directory to save the image files to (default: \fB\&./\fP). +.UNINDENT +.TP +.B \fBlibmpv\fP +For use with libmpv direct embedding. As a special case, on OS X it +is used like a normal VO within mpv (cocoa\-cb). Otherwise useless in any +other contexts. +(See \fB<mpv/render.h>\fP\&.) +.sp +This also supports many of the options the \fBgpu\fP VO has, depending on the +backend. +.TP +.B \fBrpi\fP (Raspberry Pi) +Native video output on the Raspberry Pi using the MMAL API. +.sp +This is deprecated. Use \fB\-\-vo=gpu\fP instead, which is the default and +provides the same functionality. The \fBrpi\fP VO will be removed in +mpv 0.23.0. Its functionality was folded into \-\-vo=gpu, which now uses +RPI hardware decoding by treating it as a hardware overlay (without applying +GL filtering). Also to be changed in 0.23.0: the \-\-fs flag will be reset to +"no" by default (like on the other platforms). +.sp +The following deprecated global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-rpi\-display=<number>\fP +Select the display number on which the video overlay should be shown +(default: 0). +.TP +.B \fB\-\-rpi\-layer=<number>\fP +Select the dispmanx layer on which the video overlay should be shown +(default: \-10). Note that mpv will also use the 2 layers above the +selected layer, to handle the window background and OSD. Actual video +rendering will happen on the layer above the selected layer. +.TP +.B \fB\-\-rpi\-background=<yes|no>\fP +Whether to render a black background behind the video (default: no). +Normally it\(aqs better to kill the console framebuffer instead, which +gives better performance. +.TP +.B \fB\-\-rpi\-osd=<yes|no>\fP +Enabled by default. If disabled with \fBno\fP, no OSD layer is created. +This also means there will be no subtitles rendered. +.UNINDENT +.TP +.B \fBdrm\fP (Direct Rendering Manager) +Video output driver using Kernel Mode Setting / Direct Rendering Manager. +Should be used when one doesn\(aqt want to install full\-blown graphical +environment (e.g. no X). Does not support hardware acceleration (if you +need this, check the \fBdrm\fP backend for \fBgpu\fP VO). +.sp +The following global options are supported by this video output: +.INDENT 7.0 +.TP +.B \fB\-\-drm\-connector=[<gpu_number>.]<name>\fP +Select the connector to use (usually this is a monitor.) If \fB<name>\fP +is empty or \fBauto\fP, mpv renders the output on the first available +connector. Use \fB\-\-drm\-connector=help\fP to get a list of available +connectors. When using multiple graphic cards, use the \fB<gpu_number>\fP +argument to disambiguate. +(default: empty) +.TP +.B \fB\-\-drm\-mode=<preferred|highest|N|WxH[@R]>\fP +Mode to use (resolution and frame rate). +Possible values: +.INDENT 7.0 +.TP +.B preferred +Use the preferred mode for the screen on the selected +connector. (default) +.TP +.B highest +Use the mode with the highest resolution available on the +selected connector. +.TP +.B N +Select mode by index. +.TP +.B WxH[@R] +Specify mode by width, height, and optionally refresh rate. +In case several modes match, selects the mode that comes +first in the EDID list of modes. +.UNINDENT +.sp +Use \fB\-\-drm\-mode=help\fP to get a list of available modes for all active +connectors. +.TP +.B \fB\-\-drm\-atomic=<no|auto>\fP +Toggle use of atomic modesetting. Mostly useful for debugging. +.INDENT 7.0 +.TP +.B no +Use legacy modesetting. +.TP +.B auto +Use atomic modesetting, falling back to legacy modesetting if +not available. (default) +.UNINDENT +.sp +Note: Only affects \fBgpu\-context=drm\fP\&. \fBvo=drm\fP supports legacy +modesetting only. +.TP +.B \fB\-\-drm\-draw\-plane=<primary|overlay|N>\fP +Select the DRM plane to which video and OSD is drawn to, under normal +circumstances. The plane can be specified as \fBprimary\fP, which will +pick the first applicable primary plane; \fBoverlay\fP, which will pick +the first applicable overlay plane; or by index. The index is zero +based, and related to the CRTC. +(default: primary) +.sp +When using this option with the drmprime\-drm hwdec interop, only the OSD +is rendered to this plane. +.TP +.B \fB\-\-drm\-drmprime\-video\-plane=<primary|overlay|N>\fP +Select the DRM plane to use for video with the drmprime\-drm hwdec +interop (used by e.g. the rkmpp hwdec on RockChip SoCs, and v4l2 hwdec:s +on various other SoC:s). The plane is unused otherwise. This option +accepts the same values as \fB\-\-drm\-draw\-plane\fP\&. (default: overlay) +.sp +To be able to successfully play 4K video on various SoCs you might need +to set \fB\-\-drm\-draw\-plane=overlay \-\-drm\-drmprime\-video\-plane=primary\fP +and setting \fB\-\-drm\-draw\-surface\-size=1920x1080\fP, to render the OSD at a +lower resolution (the video when handled by the hwdec will be on the +drmprime\-video plane and at full 4K resolution) +.TP +.B \fB\-\-drm\-format=<xrgb8888|xrgb2101010>\fP +Select the DRM format to use (default: xrgb8888). This allows you to +choose the bit depth of the DRM mode. xrgb8888 is your usual 24 bit per +pixel/8 bits per channel packed RGB format with 8 bits of padding. +xrgb2101010 is a packed 30 bits per pixel/10 bits per channel packed RGB +format with 2 bits of padding. +.sp +There are cases when xrgb2101010 will work with the \fBdrm\fP VO, but not +with the \fBdrm\fP backend for the \fBgpu\fP VO. This is because with the +\fBgpu\fP VO, in addition to requiring support in your DRM driver, +requires support for xrgb2101010 in your EGL driver +.TP +.B \fB\-\-drm\-draw\-surface\-size=<[WxH]>\fP +Sets the size of the surface used on the draw plane. The surface will +then be upscaled to the current screen resolution. This option can be +useful when used together with the drmprime\-drm hwdec interop at high +resolutions, as it allows scaling the draw plane (which in this case +only handles the OSD) down to a size the GPU can handle. +.sp +When used without the drmprime\-drm hwdec interop this option will just +cause the video to get rendered at a different resolution and then +scaled to screen size. +.sp +Note: this option is only available with DRM atomic support. +(default: display resolution) +.UNINDENT +.TP +.B \fBmediacodec_embed\fP (Android) +Renders \fBIMGFMT_MEDIACODEC\fP frames directly to an \fBandroid.view.Surface\fP\&. +Requires \fB\-\-hwdec=mediacodec\fP for hardware decoding, along with +\fB\-\-vo=mediacodec_embed\fP and \fB\-\-wid=(intptr_t)(*android.view.Surface)\fP\&. +.sp +Since this video output driver uses native decoding and rendering routines, +many of mpv\(aqs features (subtitle rendering, OSD/OSC, video filters, etc) +are not available with this driver. +.sp +To use hardware decoding with \fB\-\-vo=gpu\fP instead, use +\fB\-\-hwdec=mediacodec\-copy\fP along with \fB\-\-gpu\-context=android\fP\&. +.TP +.B \fBwlshm\fP (Wayland only) +Shared memory video output driver without hardware acceleration that works +whenever Wayland is present. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This is a fallback only, and should not be normally used. +.UNINDENT +.UNINDENT +.UNINDENT +.SH AUDIO FILTERS +.sp +Audio filters allow you to modify the audio stream and its properties. The +syntax is: +.INDENT 0.0 +.TP +.B \fB\-\-af=...\fP +Setup a chain of audio filters. See \fB\-\-vf\fP (\fI\%VIDEO FILTERS\fP) for the +full syntax. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +To get a full list of available audio filters, see \fB\-\-af=help\fP\&. +.sp +Also, keep in mind that most actual filters are available via the \fBlavfi\fP +wrapper, which gives you access to most of libavfilter\(aqs filters. This +includes all filters that have been ported from MPlayer to libavfilter. +.sp +The \fB\-\-vf\fP description describes how libavfilter can be used and how to +workaround deprecated mpv filters. +.UNINDENT +.UNINDENT +.sp +See \fB\-\-vf\fP group of options for info on how \fB\-\-af\-defaults\fP, \fB\-\-af\-add\fP, +\fB\-\-af\-pre\fP, \fB\-\-af\-del\fP, \fB\-\-af\-clr\fP, and possibly others work. +.sp +Available filters are: +.INDENT 0.0 +.TP +.B \fBlavcac3enc[=options]\fP +Encode multi\-channel audio to AC\-3 at runtime using libavcodec. Supports +16\-bit native\-endian input format, maximum 6 channels. The output is +big\-endian when outputting a raw AC\-3 stream, native\-endian when +outputting to S/PDIF. If the input sample rate is not 48 kHz, 44.1 kHz or +32 kHz, it will be resampled to 48 kHz. +.INDENT 7.0 +.TP +.B \fBtospdif=<yes|no>\fP +Output raw AC\-3 stream if \fBno\fP, output to S/PDIF for +pass\-through if \fByes\fP (default). +.TP +.B \fBbitrate=<rate>\fP +The bitrate use for the AC\-3 stream. Set it to 384 to get 384 kbps. +.sp +The default is 640. Some receivers might not be able to handle this. +.sp +Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128, +160, 192, 224, 256, 320, 384, 448, 512, 576, 640. +.sp +The special value \fBauto\fP selects a default bitrate based on the +input channel number: +.INDENT 7.0 +.TP +.B 1ch +96 +.TP +.B 2ch +192 +.TP +.B 3ch +224 +.TP +.B 4ch +384 +.TP +.B 5ch +448 +.TP +.B 6ch +448 +.UNINDENT +.TP +.B \fBminch=<n>\fP +If the input channel number is less than \fB<minch>\fP, the filter will +detach itself (default: 3). +.TP +.B \fBencoder=<name>\fP +Select the libavcodec encoder used. Currently, this should be an AC\-3 +encoder, and using another codec will fail horribly. +.UNINDENT +.TP +.B \fBformat=format:srate:channels:out\-srate:out\-channels\fP +Does not do any format conversion itself. Rather, it may cause the +filter system to insert necessary conversion filters before or after this +filter if needed. It is primarily useful for controlling the audio format +going into other filters. To specify the format for audio output, see +\fB\-\-audio\-format\fP, \fB\-\-audio\-samplerate\fP, and \fB\-\-audio\-channels\fP\&. This +filter is able to force a particular format, whereas \fB\-\-audio\-*\fP +may be overridden by the ao based on output compatibility. +.sp +All parameters are optional. The first 3 parameters restrict what the filter +accepts as input. They will therefore cause conversion filters to be +inserted before this one. The \fBout\-\fP parameters tell the filters or audio +outputs following this filter how to interpret the data without actually +doing a conversion. Setting these will probably just break things unless you +really know you want this for some reason, such as testing or dealing with +broken media. +.INDENT 7.0 +.TP +.B \fB<format>\fP +Force conversion to this format. Use \fB\-\-af=format=format=help\fP to get +a list of valid formats. +.TP +.B \fB<srate>\fP +Force conversion to a specific sample rate. The rate is an integer, +48000 for example. +.TP +.B \fB<channels>\fP +Force mixing to a specific channel layout. See \fB\-\-audio\-channels\fP option +for possible values. +.UNINDENT +.sp +\fB<out\-srate>\fP +.sp +\fB<out\-channels>\fP +.sp +\fINOTE\fP: this filter used to be named \fBforce\fP\&. The old \fBformat\fP filter +used to do conversion itself, unlike this one which lets the filter system +handle the conversion. +.TP +.B \fBscaletempo[=option1:option2:...]\fP +Scales audio tempo without altering pitch, optionally synced to playback +speed (default). +.sp +This works by playing \(aqstride\(aq ms of audio at normal speed then consuming +\(aqstride*scale\(aq ms of input audio. It pieces the strides together by +blending \(aqoverlap\(aq% of stride with audio following the previous stride. It +optionally performs a short statistical analysis on the next \(aqsearch\(aq ms +of audio to determine the best overlap position. +.INDENT 7.0 +.TP +.B \fBscale=<amount>\fP +Nominal amount to scale tempo. Scales this amount in addition to +speed. (default: 1.0) +.TP +.B \fBstride=<amount>\fP +Length in milliseconds to output each stride. Too high of a value will +cause noticeable skips at high scale amounts and an echo at low scale +amounts. Very low values will alter pitch. Increasing improves +performance. (default: 60) +.TP +.B \fBoverlap=<percent>\fP +Percentage of stride to overlap. Decreasing improves performance. +(default: .20) +.TP +.B \fBsearch=<amount>\fP +Length in milliseconds to search for best overlap position. Decreasing +improves performance greatly. On slow systems, you will probably want +to set this very low. (default: 14) +.TP +.B \fBspeed=<tempo|pitch|both|none>\fP +Set response to speed change. +.INDENT 7.0 +.TP +.B tempo +Scale tempo in sync with speed (default). +.TP +.B pitch +Reverses effect of filter. Scales pitch without altering tempo. +Add this to your \fBinput.conf\fP to step by musical semi\-tones: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +[ multiply speed 0.9438743126816935 +] multiply speed 1.059463094352953 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Loses sync with video. +.UNINDENT +.UNINDENT +.TP +.B both +Scale both tempo and pitch. +.TP +.B none +Ignore speed changes. +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fBmpv \-\-af=scaletempo \-\-speed=1.2 media.ogg\fP +Would play media at 1.2x normal speed, with audio at normal +pitch. Changing playback speed would change audio tempo to match. +.TP +.B \fBmpv \-\-af=scaletempo=scale=1.2:speed=none \-\-speed=1.2 media.ogg\fP +Would play media at 1.2x normal speed, with audio at normal +pitch, but changing playback speed would have no effect on audio +tempo. +.TP +.B \fBmpv \-\-af=scaletempo=stride=30:overlap=.50:search=10 media.ogg\fP +Would tweak the quality and performance parameters. +.TP +.B \fBmpv \-\-af=scaletempo=scale=1.2:speed=pitch audio.ogg\fP +Would play media at 1.2x normal speed, with audio at normal pitch. +Changing playback speed would change pitch, leaving audio tempo at +1.2x. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fBrubberband\fP +High quality pitch correction with librubberband. This can be used in place +of \fBscaletempo\fP, and will be used to adjust audio pitch when playing +at speed different from normal. It can also be used to adjust audio pitch +without changing playback speed. +.INDENT 7.0 +.TP +.B \fB<pitch\-scale>\fP +Sets the pitch scaling factor. Frequencies are multiplied by this value. +.UNINDENT +.sp +This filter has a number of additional sub\-options. You can list them with +\fBmpv \-\-af=rubberband=help\fP\&. This will also show the default values +for each option. The options are not documented here, because they are +merely passed to librubberband. Look at the librubberband documentation +to learn what each option does: +\fI\%http://breakfastquay.com/rubberband/code\-doc/classRubberBand_1_1RubberBandStretcher.html\fP +(The mapping of the mpv rubberband filter sub\-option names and values to +those of librubberband follows a simple pattern: \fB"Option" + Name + Value\fP\&.) +.sp +This filter supports the following \fBaf\-command\fP commands: +.INDENT 7.0 +.TP +.B \fBset\-pitch\fP +Set the \fB<pitch\-scale>\fP argument dynamically. This can be used to +change the playback pitch at runtime. Note that speed is controlled +using the standard \fBspeed\fP property, not \fBaf\-command\fP\&. +.TP +.B \fBmultiply\-pitch <factor>\fP +Multiply the current value of \fB<pitch\-scale>\fP dynamically. For +example: 0.5 to go down by an octave, 1.5 to go up by a perfect fifth. +If you want to go up or down by semi\-tones, use 1.059463094352953 and +0.9438743126816935 +.UNINDENT +.TP +.B \fBlavfi=graph\fP +Filter audio using FFmpeg\(aqs libavfilter. +.INDENT 7.0 +.TP +.B \fB<graph>\fP +Libavfilter graph. See \fBlavfi\fP video filter for details \- the graph +syntax is the same. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Don\(aqt forget to quote libavfilter graphs as described in the lavfi +video filter section. +.UNINDENT +.UNINDENT +.TP +.B \fBo=<string>\fP +AVOptions. +.TP +.B \fBfix\-pts=<yes|no>\fP +Determine PTS based on sample count (default: no). If this is enabled, +the player won\(aqt rely on libavfilter passing through PTS accurately. +Instead, it pass a sample count as PTS to libavfilter, and compute the +PTS used by mpv based on that and the input PTS. This helps with filters +which output a recomputed PTS instead of the original PTS (including +filters which require the PTS to start at 0). mpv normally expects +filters to not touch the PTS (or only to the extent of changing frame +boundaries), so this is not the default, but it will be needed to use +broken filters. In practice, these broken filters will either cause slow +A/V desync over time (with some files), or break playback completely if +you seek or start playback from the middle of a file. +.UNINDENT +.UNINDENT +.SH VIDEO FILTERS +.sp +Video filters allow you to modify the video stream and its properties. All of +the information described in this section applies to audio filters as well +(generally using the prefix \fB\-\-af\fP instead of \fB\-\-vf\fP). +.sp +The exact syntax is: +.INDENT 0.0 +.TP +.B \fB\-\-vf=<filter1[=parameter1:parameter2:...],filter2,...>\fP +Setup a chain of video filters. This consists on the filter name, and an +option list of parameters after \fB=\fP\&. The parameters are separated by +\fB:\fP (not \fB,\fP, as that starts a new filter entry). +.sp +Before the filter name, a label can be specified with \fB@name:\fP, where +name is an arbitrary user\-given name, which identifies the filter. This +is only needed if you want to toggle the filter at runtime. +.sp +A \fB!\fP before the filter name means the filter is disabled by default. It +will be skipped on filter creation. This is also useful for runtime filter +toggling. +.sp +See the \fBvf\fP command (and \fBtoggle\fP sub\-command) for further explanations +and examples. +.sp +The general filter entry syntax is: +.INDENT 7.0 +.INDENT 3.5 +\fB["@"<label\-name>":"] ["!"] <filter\-name> [ "=" <filter\-parameter\-list> ]\fP +.UNINDENT +.UNINDENT +.sp +or for the special "toggle" syntax (see \fBvf\fP command): +.INDENT 7.0 +.INDENT 3.5 +\fB"@"<label\-name>\fP +.UNINDENT +.UNINDENT +.sp +and the \fBfilter\-parameter\-list\fP: +.INDENT 7.0 +.INDENT 3.5 +\fB<filter\-parameter> | <filter\-parameter> "," <filter\-parameter\-list>\fP +.UNINDENT +.UNINDENT +.sp +and \fBfilter\-parameter\fP: +.INDENT 7.0 +.INDENT 3.5 +\fB( <param\-name> "=" <param\-value> ) | <param\-value>\fP +.UNINDENT +.UNINDENT +.sp +\fBparam\-value\fP can further be quoted in \fB[\fP / \fB]\fP in case the value +contains characters like \fB,\fP or \fB=\fP\&. This is used in particular with +the \fBlavfi\fP filter, which uses a very similar syntax as mpv (MPlayer +historically) to specify filters and their parameters. +.UNINDENT +.sp +Filters can be manipulated at run time. You can use \fB@\fP labels as described +above in combination with the \fBvf\fP command (see \fI\%COMMAND INTERFACE\fP) to get +more control over this. Initially disabled filters with \fB!\fP are useful for +this as well. +.sp +You can also set defaults for each filter. The defaults are applied before the +normal filter parameters. This is deprecated and never worked for the +libavfilter bridge. +.INDENT 0.0 +.TP +.B \fB\-\-vf\-defaults=<filter1[=parameter1:parameter2:...],filter2,...>\fP +Set defaults for each filter. (Deprecated. \fB\-\-af\-defaults\fP is deprecated +as well.) +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +To get a full list of available video filters, see \fB\-\-vf=help\fP and +\fI\%http://ffmpeg.org/ffmpeg\-filters.html\fP . +.sp +Also, keep in mind that most actual filters are available via the \fBlavfi\fP +wrapper, which gives you access to most of libavfilter\(aqs filters. This +includes all filters that have been ported from MPlayer to libavfilter. +.sp +Most builtin filters are deprecated in some ways, unless they\(aqre only available +in mpv (such as filters which deal with mpv specifics, or which are +implemented in mpv only). +.sp +If a filter is not builtin, the \fBlavfi\-bridge\fP will be automatically +tried. This bridge does not support help output, and does not verify +parameters before the filter is actually used. Although the mpv syntax +is rather similar to libavfilter\(aqs, it\(aqs not the same. (Which means not +everything accepted by vf_lavfi\(aqs \fBgraph\fP option will be accepted by +\fB\-\-vf\fP\&.) +.sp +You can also prefix the filter name with \fBlavfi\-\fP to force the wrapper. +This is helpful if the filter name collides with a deprecated mpv builtin +filter. For example \fB\-\-vf=lavfi\-scale=args\fP would use libavfilter\(aqs +\fBscale\fP filter over mpv\(aqs deprecated builtin one. +.UNINDENT +.UNINDENT +.sp +Video filters are managed in lists. There are a few commands to manage the +filter list. +.INDENT 0.0 +.TP +.B \fB\-\-vf\-add=filter\fP +Appends the filter given as arguments to the filter list. (Passing multiple +filters is currently still possible, but deprecated.) +.TP +.B \fB\-\-vf\-pre=filter\fP +Prepends the filters given as arguments to the filter list. (Passing +multiple filters is currently still possible, but deprecated.) +.TP +.B \fB\-\-vf\-del=filter\fP +Deletes the filter. The filter can even given the way it was added (filter +name and its full argument list), by label (prefixed with \fB@\fP), or as +index number. Index numbers start at 0, negative numbers address the end of +the list (\-1 is the last). (Passing multiple filters is currently still +possible, but deprecated.) +.TP +.B \fB\-\-vf\-clr\fP +Completely empties the filter list. +.UNINDENT +.sp +With filters that support it, you can access parameters by their name. +.INDENT 0.0 +.TP +.B \fB\-\-vf=<filter>=help\fP +Prints the parameter names and parameter value ranges for a particular +filter. +.UNINDENT +.sp +Available mpv\-only filters are: +.INDENT 0.0 +.TP +.B \fBformat=fmt=<value>:colormatrix=<value>:...\fP +Applies video parameter overrides, with optional conversion. By default, +this overrides the video\(aqs parameters without conversion (except for the +\fBfmt\fP parameter), but can be made to perform an appropriate conversion +with \fBconvert=yes\fP for parameters for which conversion is supported. +.INDENT 7.0 +.TP +.B \fB<fmt>\fP +Image format name, e.g. rgb15, bgr24, 420p, etc. (default: don\(aqt change). +.sp +This filter always performs conversion to the given format. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +For a list of available formats, use \fB\-\-vf=format=fmt=help\fP\&. +.UNINDENT +.UNINDENT +.TP +.B \fB<convert=yes|no>\fP +Force conversion of color parameters (default: no). +.sp +If this is disabled (the default), the only conversion that is possibly +performed is format conversion if \fB<fmt>\fP is set. All other parameters +(like \fB<colormatrix>\fP) are forced without conversion. This mode is +typically useful when files have been incorrectly tagged. +.sp +If this is enabled, libswscale or zimg is used if any of the parameters +mismatch. zimg is used of the input/output image formats are supported +by mpv\(aqs zimg wrapper, and if \fB\-\-sws\-allow\-zimg=yes\fP is used. Both +libraries may not support all kinds of conversions. This typically +results in silent incorrect conversion. zimg has in many cases a better +chance of performing the conversion correctly. +.sp +In both cases, the color parameters are set on the output stage of the +image format conversion (if \fBfmt\fP was set). The difference is that +with \fBconvert=no\fP, the color parameters are not passed on to the +converter. +.sp +If input and output video parameters are the same, conversion is always +skipped. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fBmpv test.mkv \-\-vf=format:colormatrix=ycgco\fP +Results in incorrect colors (if test.mkv was tagged correctly). +.TP +.B \fBmpv test.mkv \-\-vf=format:colormatrix=ycgco:convert=yes \-\-sws\-allow\-zimg\fP +Results in true conversion to \fBycgco\fP, assuming the renderer +supports it (\fB\-\-vo=gpu\fP normally does). You can add \fB\-\-vo=xv\fP +to force a VO which definitely does not support it, which should +show incorrect colors as confirmation. +.sp +Using \fB\-\-sws\-allow\-zimg=no\fP (or disabling zimg at build time) +will use libswscale, which cannot perform this conversion as +of this writing. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB<colormatrix>\fP +Controls the YUV to RGB color space conversion when playing video. There +are various standards. Normally, BT.601 should be used for SD video, and +BT.709 for HD video. (This is done by default.) Using incorrect color space +results in slightly under or over saturated and shifted colors. +.sp +These options are not always supported. Different video outputs provide +varying degrees of support. The \fBgpu\fP and \fBvdpau\fP video output +drivers usually offer full support. The \fBxv\fP output can set the color +space if the system video driver supports it, but not input and output +levels. The \fBscale\fP video filter can configure color space and input +levels, but only if the output format is RGB (if the video output driver +supports RGB output, you can force this with \fB\-vf scale,format=rgba\fP). +.sp +If this option is set to \fBauto\fP (which is the default), the video\(aqs +color space flag will be used. If that flag is unset, the color space +will be selected automatically. This is done using a simple heuristic that +attempts to distinguish SD and HD video. If the video is larger than +1279x576 pixels, BT.709 (HD) will be used; otherwise BT.601 (SD) is +selected. +.sp +Available color spaces are: +.INDENT 7.0 +.TP +.B auto +automatic selection (default) +.TP +.B bt.601 +ITU\-R BT.601 (SD) +.TP +.B bt.709 +ITU\-R BT.709 (HD) +.TP +.B bt.2020\-ncl +ITU\-R BT.2020 non\-constant luminance system +.TP +.B bt.2020\-cl +ITU\-R BT.2020 constant luminance system +.TP +.B smpte\-240m +SMPTE\-240M +.UNINDENT +.TP +.B \fB<colorlevels>\fP +YUV color levels used with YUV to RGB conversion. This option is only +necessary when playing broken files which do not follow standard color +levels or which are flagged wrong. If the video does not specify its +color range, it is assumed to be limited range. +.sp +The same limitations as with \fB<colormatrix>\fP apply. +.sp +Available color ranges are: +.INDENT 7.0 +.TP +.B auto +automatic selection (normally limited range) (default) +.TP +.B limited +limited range (16\-235 for luma, 16\-240 for chroma) +.TP +.B full +full range (0\-255 for both luma and chroma) +.UNINDENT +.TP +.B \fB<primaries>\fP +RGB primaries the source file was encoded with. Normally this should be set +in the file header, but when playing broken or mistagged files this can be +used to override the setting. +.sp +This option only affects video output drivers that perform color +management, for example \fBgpu\fP with the \fBtarget\-prim\fP or +\fBicc\-profile\fP suboptions set. +.sp +If this option is set to \fBauto\fP (which is the default), the video\(aqs +primaries flag will be used. If that flag is unset, the color space will +be selected automatically, using the following heuristics: If the +\fB<colormatrix>\fP is set or determined as BT.2020 or BT.709, the +corresponding primaries are used. Otherwise, if the video height is +exactly 576 (PAL), BT.601\-625 is used. If it\(aqs exactly 480 or 486 (NTSC), +BT.601\-525 is used. If the video resolution is anything else, BT.709 is +used. +.sp +Available primaries are: +.INDENT 7.0 +.TP +.B auto +automatic selection (default) +.TP +.B bt.601\-525 +ITU\-R BT.601 (SD) 525\-line systems (NTSC, SMPTE\-C) +.TP +.B bt.601\-625 +ITU\-R BT.601 (SD) 625\-line systems (PAL, SECAM) +.TP +.B bt.709 +ITU\-R BT.709 (HD) (same primaries as sRGB) +.TP +.B bt.2020 +ITU\-R BT.2020 (UHD) +.TP +.B apple +Apple RGB +.TP +.B adobe +Adobe RGB (1998) +.TP +.B prophoto +ProPhoto RGB (ROMM) +.TP +.B cie1931 +CIE 1931 RGB +.TP +.B dci\-p3 +DCI\-P3 (Digital Cinema) +.TP +.B v\-gamut +Panasonic V\-Gamut primaries +.UNINDENT +.TP +.B \fB<gamma>\fP +Gamma function the source file was encoded with. Normally this should be set +in the file header, but when playing broken or mistagged files this can be +used to override the setting. +.sp +This option only affects video output drivers that perform color management. +.sp +If this option is set to \fBauto\fP (which is the default), the gamma will +be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for +XYZ content. +.sp +Available gamma functions are: +.INDENT 7.0 +.TP +.B auto +automatic selection (default) +.TP +.B bt.1886 +ITU\-R BT.1886 (EOTF corresponding to BT.601/BT.709/BT.2020) +.TP +.B srgb +IEC 61966\-2\-4 (sRGB) +.TP +.B linear +Linear light +.TP +.B gamma1.8 +Pure power curve (gamma 1.8) +.TP +.B gamma2.0 +Pure power curve (gamma 2.0) +.TP +.B gamma2.2 +Pure power curve (gamma 2.2) +.TP +.B gamma2.4 +Pure power curve (gamma 2.4) +.TP +.B gamma2.6 +Pure power curve (gamma 2.6) +.TP +.B gamma2.8 +Pure power curve (gamma 2.8) +.TP +.B prophoto +ProPhoto RGB (ROMM) curve +.TP +.B pq +ITU\-R BT.2100 PQ (Perceptual quantizer) curve +.TP +.B hlg +ITU\-R BT.2100 HLG (Hybrid Log\-gamma) curve +.TP +.B v\-log +Panasonic V\-Log transfer curve +.TP +.B s\-log1 +Sony S\-Log1 transfer curve +.TP +.B s\-log2 +Sony S\-Log2 transfer curve +.UNINDENT +.TP +.B \fB<sig\-peak>\fP +Reference peak illumination for the video file, relative to the +signal\(aqs reference white level. This is mostly interesting for HDR, but +it can also be used tone map SDR content to simulate a different +exposure. Normally inferred from tags such as MaxCLL or mastering +metadata. +.sp +The default of 0.0 will default to the source\(aqs nominal peak luminance. +.TP +.B \fB<light>\fP +.INDENT 7.0 +.INDENT 3.5 +Light type of the scene. This is mostly correctly inferred based on the +gamma function, but it can be useful to override this when viewing raw +camera footage (e.g. V\-Log), which is normally scene\-referred instead +of display\-referred. +.sp +Available light types are: +.UNINDENT +.UNINDENT +.INDENT 7.0 +.TP +.B auto +Automatic selection (default) +.TP +.B display +Display\-referred light (most content) +.TP +.B hlg +Scene\-referred using the HLG OOTF (e.g. HLG content) +.TP +.B 709\-1886 +Scene\-referred using the BT709+BT1886 interaction +.TP +.B gamma1.2 +Scene\-referred using a pure power OOTF (gamma=1.2) +.UNINDENT +.TP +.B \fB<stereo\-in>\fP +Set the stereo mode the video is assumed to be encoded in. Use +\fB\-\-vf format:stereo\-in=help\fP to list all available modes. Check with +the \fBstereo3d\fP filter documentation to see what the names mean. +.TP +.B \fB<stereo\-out>\fP +Set the stereo mode the video should be displayed as. Takes the +same values as the \fBstereo\-in\fP option. +.TP +.B \fB<rotate>\fP +Set the rotation the video is assumed to be encoded with in degrees. +The special value \fB\-1\fP uses the input format. +.TP +.B \fB<dw>\fP, \fB<dh>\fP +Set the display size. Note that setting the display size such that +the video is scaled in both directions instead of just changing the +aspect ratio is an implementation detail, and might change later. +.TP +.B \fB<dar>\fP +Set the display aspect ratio of the video frame. This is a float, +but values such as \fB[16:9]\fP can be passed too (\fB[...]\fP for quoting +to prevent the option parser from interpreting the \fB:\fP character). +.UNINDENT +.TP +.B \fBlavfi=graph[:sws\-flags[:o=opts]]\fP +Filter video using FFmpeg\(aqs libavfilter. +.INDENT 7.0 +.TP +.B \fB<graph>\fP +The libavfilter graph string. The filter must have a single video input +pad and a single video output pad. +.sp +See \fI\%https://ffmpeg.org/ffmpeg\-filters.html\fP for syntax and available +filters. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +If you want to use the full filter syntax with this option, you have +to quote the filter graph in order to prevent mpv\(aqs syntax and the +filter graph syntax from clashing. To prevent a quoting and escaping +mess, consider using \fB\-\-lavfi\-complex\fP if you know which video +track you want to use from the input file. (There is only one video +track for nearly all video files anyway.) +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fB\-\-vf=lavfi=[gradfun=20:30,vflip]\fP +\fBgradfun\fP filter with nonsense parameters, followed by a +\fBvflip\fP filter. (This demonstrates how libavfilter takes a +graph and not just a single filter.) The filter graph string is +quoted with \fB[\fP and \fB]\fP\&. This requires no additional quoting +or escaping with some shells (like bash), while others (like +zsh) require additional \fB"\fP quotes around the option string. +.TP +.B \fB\(aq\-\-vf=lavfi="gradfun=20:30,vflip"\(aq\fP +Same as before, but uses quoting that should be safe with all +shells. The outer \fB\(aq\fP quotes make sure that the shell does not +remove the \fB"\fP quotes needed by mpv. +.TP +.B \fB\(aq\-\-vf=lavfi=graph="gradfun=radius=30:strength=20,vflip"\(aq\fP +Same as before, but uses named parameters for everything. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB<sws\-flags>\fP +If libavfilter inserts filters for pixel format conversion, this +option gives the flags which should be passed to libswscale. This +option is numeric and takes a bit\-wise combination of \fBSWS_\fP flags. +.sp +See \fBhttp://git.videolan.org/?p=ffmpeg.git;a=blob;f=libswscale/swscale.h\fP\&. +.TP +.B \fB<o>\fP +Set AVFilterGraph options. These should be documented by FFmpeg. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.TP +.B \fB\(aq\-\-vf=lavfi=yadif:o="threads=2,thread_type=slice"\(aq\fP +forces a specific threading configuration. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fBsub=[=bottom\-margin:top\-margin]\fP +Moves subtitle rendering to an arbitrary point in the filter chain, or force +subtitle rendering in the video filter as opposed to using video output OSD +support. +.INDENT 7.0 +.TP +.B \fB<bottom\-margin>\fP +Adds a black band at the bottom of the frame. The SSA/ASS renderer can +place subtitles there (with \fB\-\-sub\-use\-margins\fP). +.TP +.B \fB<top\-margin>\fP +Black band on the top for toptitles (with \fB\-\-sub\-use\-margins\fP). +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fB\-\-vf=sub,eq\fP +Moves sub rendering before the eq filter. This will put both +subtitle colors and video under the influence of the video equalizer +settings. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fBvapoursynth=file:buffered\-frames:concurrent\-frames\fP +Loads a VapourSynth filter script. This is intended for streamed +processing: mpv actually provides a source filter, instead of using a +native VapourSynth video source. The mpv source will answer frame +requests only within a small window of frames (the size of this window +is controlled with the \fBbuffered\-frames\fP parameter), and requests outside +of that will return errors. As such, you can\(aqt use the full power of +VapourSynth, but you can use certain filters. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Do not use this filter, unless you have expert knowledge in VapourSynth, +and know how to fix bugs in the mpv VapourSynth wrapper code. +.UNINDENT +.UNINDENT +.sp +If you just want to play video generated by VapourSynth (i.e. using +a native VapourSynth video source), it\(aqs better to use \fBvspipe\fP and a +pipe or FIFO to feed the video to mpv. The same applies if the filter script +requires random frame access (see \fBbuffered\-frames\fP parameter). +.INDENT 7.0 +.TP +.B \fBfile\fP +Filename of the script source. Currently, this is always a python +script (\fB\&.vpy\fP in VapourSynth convention). +.sp +The variable \fBvideo_in\fP is set to the mpv video source, and it is +expected that the script reads video from it. (Otherwise, mpv will +decode no video, and the video packet queue will overflow, eventually +leading to only audio playing, or worse.) +.sp +The filter graph created by the script is also expected to pass through +timestamps using the \fB_DurationNum\fP and \fB_DurationDen\fP frame +properties. +.sp +See the end of the option list for a full list of script variables +defined by mpv. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example:" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +import vapoursynth as vs +core = vs.get_core() +core.std.AddBorders(video_in, 10, 10, 20, 20).set_output() +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +The script will be reloaded on every seek. This is done to reset +the filter properly on discontinuities. +.UNINDENT +.UNINDENT +.TP +.B \fBbuffered\-frames\fP +Maximum number of decoded video frames that should be buffered before +the filter (default: 4). This specifies the maximum number of frames +the script can request in backward direction. +.sp +E.g. if \fBbuffered\-frames=5\fP, and the script just requested frame 15, +it can still request frame 10, but frame 9 is not available anymore. +If it requests frame 30, mpv will decode 15 more frames, and keep only +frames 25\-30. +.sp +The only reason why this buffer exists is to serve the random access +requests the VapourSynth filter can make. +.sp +The VapourSynth API has a \fBgetFrameAsync\fP function, which takes an +absolute frame number. Source filters must respond to all requests. For +example, a source filter can request frame 2432, and then frame 3. +Source filters typically implement this by pre\-indexing the entire +file. +.sp +mpv on the other hand is stream oriented, and does not allow filters to +seek. (And it would not make sense to allow it, because it would ruin +performance.) Filters get frames sequentially in playback direction, and +cannot request them out of order. +.sp +To compensate for this mismatch, mpv allows the filter to access frames +within a certain window. \fBbuffered\-frames\fP controls the size of this +window. Most VapourSynth filters happen to work with this, because mpv +requests frames sequentially increasing from it, and most filters only +require frames "close" to the requested frame. +.sp +If the filter requests a frame that has a higher frame number than the +highest buffered frame, new frames will be decoded until the requested +frame number is reached. Excessive frames will be flushed out in a FIFO +manner (there are only at most \fBbuffered\-frames\fP in this buffer). +.sp +If the filter requests a frame that has a lower frame number than the +lowest buffered frame, the request cannot be satisfied, and an error +is returned to the filter. This kind of error is not supposed to happen +in a "proper" VapourSynth environment. What exactly happens depends on +the filters involved. +.sp +Increasing this buffer will not improve performance. Rather, it will +waste memory, and slow down seeks (when enough frames to fill the buffer +need to be decoded at once). It is only needed to prevent the error +described in the previous paragraph. +.sp +How many frames a filter requires depends on filter implementation +details, and mpv has no way of knowing. A scale filter might need only +1 frame, an interpolation filter may require a small number of frames, +and the \fBReverse\fP filter will require an infinite number of frames. +.sp +If you want reliable operation to the full extend VapourSynth is +capable, use \fBvspipe\fP\&. +.sp +The actual number of buffered frames also depends on the value of the +\fBconcurrent\-frames\fP option. Currently, both option values are +multiplied to get the final buffer size. +.TP +.B \fBconcurrent\-frames\fP +Number of frames that should be requested in parallel. The +level of concurrency depends on the filter and how quickly mpv can +decode video to feed the filter. This value should probably be +proportional to the number of cores on your machine. Most time, +making it higher than the number of cores can actually make it +slower. +.sp +Technically, mpv will call the VapourSynth \fBgetFrameAsync\fP function +in a loop, until there are \fBconcurrent\-frames\fP frames that have not +been returned by the filter yet. This also assumes that the rest of the +mpv filter chain reads the output of the \fBvapoursynth\fP filter quickly +enough. (For example, if you pause the player, filtering will stop very +soon, because the filtered frames are waiting in a queue.) +.sp +Actual concurrency depends on many other factors. +.sp +By default, this uses the special value \fBauto\fP, which sets the option +to the number of detected logical CPU cores. +.UNINDENT +.sp +The following \fB\&.vpy\fP script variables are defined by mpv: +.INDENT 7.0 +.TP +.B \fBvideo_in\fP +The mpv video source as vapoursynth clip. Note that this has an +incorrect (very high) length set, which confuses many filters. This is +necessary, because the true number of frames is unknown. You can use the +\fBTrim\fP filter on the clip to reduce the length. +.TP +.B \fBvideo_in_dw\fP, \fBvideo_in_dh\fP +Display size of the video. Can be different from video size if the +video does not use square pixels (e.g. DVD). +.TP +.B \fBcontainer_fps\fP +FPS value as reported by file headers. This value can be wrong or +completely broken (e.g. 0 or NaN). Even if the value is correct, +if another filter changes the real FPS (by dropping or inserting +frames), the value of this variable will not be useful. Note that +the \fB\-\-fps\fP command line option overrides this value. +.sp +Useful for some filters which insist on having a FPS. +.TP +.B \fBdisplay_fps\fP +Refresh rate of the current display. Note that this value can be 0. +.UNINDENT +.TP +.B \fBvavpp\fP +VA\-API video post processing. Requires the system to support VA\-API, +i.e. Linux/BSD only. Works with \fB\-\-vo=vaapi\fP and \fB\-\-vo=gpu\fP only. +Currently deinterlaces. This filter is automatically inserted if +deinterlacing is requested (either using the \fBd\fP key, by default mapped to +the command \fBcycle deinterlace\fP, or the \fB\-\-deinterlace\fP option). +.INDENT 7.0 +.TP +.B \fBdeint=<method>\fP +Select the deinterlacing algorithm. +.INDENT 7.0 +.TP +.B no +Don\(aqt perform deinterlacing. +.TP +.B auto +Select the best quality deinterlacing algorithm (default). This +goes by the order of the options as documented, with +\fBmotion\-compensated\fP being considered best quality. +.TP +.B first\-field +Show only first field. +.TP +.B bob +bob deinterlacing. +.TP +.B weave, motion\-adaptive, motion\-compensated +Advanced deinterlacing algorithms. Whether these actually work +depends on the GPU hardware, the GPU drivers, driver bugs, and +mpv bugs. +.UNINDENT +.TP +.B \fB<interlaced\-only>\fP +.INDENT 7.0 +.TP +.B no +Deinterlace all frames (default). +.TP +.B yes +Only deinterlace frames marked as interlaced. +.UNINDENT +.TP +.B \fBreversal\-bug=<yes|no>\fP +.INDENT 7.0 +.TP +.B no +Use the API as it was interpreted by older Mesa drivers. While +this interpretation was more obvious and inuitive, it was +apparently wrong, and not shared by Intel driver developers. +.TP +.B yes +Use Intel interpretation of surface forward and backwards +references (default). This is what Intel drivers and newer Mesa +drivers expect. Matters only for the advanced deinterlacing +algorithms. +.UNINDENT +.UNINDENT +.TP +.B \fBvdpaupp\fP +VDPAU video post processing. Works with \fB\-\-vo=vdpau\fP and \fB\-\-vo=gpu\fP +only. This filter is automatically inserted if deinterlacing is requested +(either using the \fBd\fP key, by default mapped to the command +\fBcycle deinterlace\fP, or the \fB\-\-deinterlace\fP option). When enabling +deinterlacing, it is always preferred over software deinterlacer filters +if the \fBvdpau\fP VO is used, and also if \fBgpu\fP is used and hardware +decoding was activated at least once (i.e. vdpau was loaded). +.INDENT 7.0 +.TP +.B \fBsharpen=<\-1\-1>\fP +For positive values, apply a sharpening algorithm to the video, for +negative values a blurring algorithm (default: 0). +.TP +.B \fBdenoise=<0\-1>\fP +Apply a noise reduction algorithm to the video (default: 0; no noise +reduction). +.TP +.B \fBdeint=<yes|no>\fP +Whether deinterlacing is enabled (default: no). If enabled, it will use +the mode selected with \fBdeint\-mode\fP\&. +.TP +.B \fBdeint\-mode=<first\-field|bob|temporal|temporal\-spatial>\fP +Select deinterlacing mode (default: temporal). +.sp +Note that there\(aqs currently a mechanism that allows the \fBvdpau\fP VO to +change the \fBdeint\-mode\fP of auto\-inserted \fBvdpaupp\fP filters. To avoid +confusion, it\(aqs recommended not to use the \fB\-\-vo=vdpau\fP suboptions +related to filtering. +.INDENT 7.0 +.TP +.B first\-field +Show only first field. +.TP +.B bob +Bob deinterlacing. +.TP +.B temporal +Motion\-adaptive temporal deinterlacing. May lead to A/V desync +with slow video hardware and/or high resolution. +.TP +.B temporal\-spatial +Motion\-adaptive temporal deinterlacing with edge\-guided spatial +interpolation. Needs fast video hardware. +.UNINDENT +.TP +.B \fBchroma\-deint\fP +Makes temporal deinterlacers operate both on luma and chroma (default). +Use no\-chroma\-deint to solely use luma and speed up advanced +deinterlacing. Useful with slow video memory. +.TP +.B \fBpullup\fP +Try to apply inverse telecine, needs motion adaptive temporal +deinterlacing. +.TP +.B \fBinterlaced\-only=<yes|no>\fP +If \fByes\fP, only deinterlace frames marked as interlaced (default: no). +.TP +.B \fBhqscaling=<0\-9>\fP +.INDENT 7.0 +.TP +.B 0 +Use default VDPAU scaling (default). +.TP +.B 1\-9 +Apply high quality VDPAU scaling (needs capable hardware). +.UNINDENT +.UNINDENT +.TP +.B \fBd3d11vpp\fP +Direct3D 11 video post processing. Currently requires D3D11 hardware +decoding for use. +.INDENT 7.0 +.TP +.B \fBdeint=<yes|no>\fP +Whether deinterlacing is enabled (default: no). +.TP +.B \fBinterlaced\-only=<yes|no>\fP +If \fByes\fP, only deinterlace frames marked as interlaced (default: no). +.TP +.B \fBmode=<blend|bob|adaptive|mocomp|ivctc|none>\fP +Tries to select a video processor with the given processing capability. +If a video processor supports multiple capabilities, it is not clear +which algorithm is actually selected. \fBnone\fP always falls back. On +most if not all hardware, this option will probably do nothing, because +a video processor usually supports all modes or none. +.UNINDENT +.TP +.B \fBfingerprint=...\fP +Compute video frame fingerprints and provide them as metadata. Actually, it +currently barely deserved to be called \fBfingerprint\fP, because it does not +compute "proper" fingerprints, only tiny downscaled images (but which can be +used to compute image hashes or for similarity matching). +.sp +The main purpose of this filter is to support the \fBskip\-logo.lua\fP script. +If this script is dropped, or mpv ever gains a way to load user\-defined +filters (other than VapourSynth), this filter will be removed. Due to the +"special" nature of this filter, it will be removed without warning. +.sp +The intended way to read from the filter is using \fBvf\-metadata\fP (also +see \fBclear\-on\-query\fP filter parameter). The property will return a list +of key/value pairs as follows: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +fp0.pts = 1.2345 +fp0.hex = 1234abcdef...bcde +fp1.pts = 1.4567 +fp1.hex = abcdef1234...6789 +\&... +fpN.pts = ... +fpN.hex = ... +type = gray\-hex\-16x16 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Each \fBfp<N>\fP entry is for a frame. The \fBpts\fP entry specifies the +timestamp of the frame (within the filter chain; in simple cases this is +the same as the display timestamp). The \fBhex\fP field is the hex encoded +fingerprint, whose size and meaning depend on the \fBtype\fP filter option. +The \fBtype\fP field has the same value as the option the filter was created +with. +.sp +This returns the frames that were filtered since the last query of the +property. If \fBclear\-on\-query=no\fP was set, a query doesn\(aqt reset the list +of frames. In both cases, a maximum of 10 frames is returned. If there are +more frames, the oldest frames are discarded. Frames are returned in filter +order. +.sp +(This doesn\(aqt return a structured list for the per\-frame details because the +internals of the \fBvf\-metadata\fP mechanism suck. The returned format may +change in the future.) +.sp +This filter uses zimg for speed and profit. However, it will fallback to +libswscale in a number of situations: lesser pixel formats, unaligned data +pointers or strides, or if zimg fails to initialize for unknown reasons. In +these cases, the filter will use more CPU. Also, it will output different +fingerprints, because libswscale cannot perform the full range expansion we +normally request from zimg. As a consequence, the filter may be slower and +not work correctly in random situations. +.INDENT 7.0 +.TP +.B \fBtype=...\fP +What fingerprint to compute. Available types are: +.INDENT 7.0 +.TP +.B gray\-hex\-8x8 +grayscale, 8 bit, 8x8 size +.TP +.B gray\-hex\-16x16 +grayscale, 8 bit, 16x16 size (default) +.UNINDENT +.sp +Both types simply remove all colors, downscale the image, concatenate +all pixel values to a byte array, and convert the array to a hex string. +.TP +.B \fBclear\-on\-query=yes|no\fP +Clear the list of frame fingerprints if the \fBvf\-metadata\fP property for +this filter is queried (default: yes). This requires some care by the +user. Some types of accesses might query the filter multiple times, +which leads to lost frames. +.TP +.B \fBprint=yes|no\fP +Print computed fingerprints the the terminal (default: no). This is +mostly for testing and such. Scripts should use \fBvf\-metadata\fP to +read information from this filter instead. +.UNINDENT +.UNINDENT +.SH ENCODING +.sp +You can encode files from one format/codec to another using this facility. +.INDENT 0.0 +.TP +.B \fB\-\-o=<filename>\fP +Enables encoding mode and specifies the output file name. +.TP +.B \fB\-\-of=<format>\fP +Specifies the output format (overrides autodetection by the file name +extension of the file specified by \fB\-o\fP). See \fB\-\-of=help\fP for a full +list of supported formats. +.TP +.B \fB\-\-ofopts=<options>\fP +Specifies the output format options for libavformat. +See \fB\-\-ofopts=help\fP for a full list of supported options. +.sp +Options are managed in lists. There are a few commands to manage the +options list. +.INDENT 7.0 +.TP +.B \fB\-\-ofopts\-add=<options1[,options2,...]>\fP +Appends the options given as arguments to the options list. +.TP +.B \fB\-\-ofopts=""\fP +Completely empties the options list. +.UNINDENT +.TP +.B \fB\-\-oac=<codec>\fP +Specifies the output audio codec. See \fB\-\-oac=help\fP for a full list of +supported codecs. +.TP +.B \fB\-\-oaoffset=<value>\fP +Shifts audio data by the given time (in seconds) by adding/removing +samples at the start. Deprecated. +.TP +.B \fB\-\-oacopts=<options>\fP +Specifies the output audio codec options for libavcodec. +See \fB\-\-oacopts=help\fP for a full list of supported options. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.TP +.B "\fB\-\-oac=libmp3lame \-\-oacopts=b=128000\fP" +selects 128 kbps MP3 encoding. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Options are managed in lists. There are a few commands to manage the +options list. +.INDENT 7.0 +.TP +.B \fB\-\-oacopts\-add=<options1[,options2,...]>\fP +Appends the options given as arguments to the options list. +.TP +.B \fB\-\-oacopts=""\fP +Completely empties the options list. +.UNINDENT +.TP +.B \fB\-\-oafirst\fP +Force the audio stream to become the first stream in the output. +By default, the order is unspecified. Deprecated. +.TP +.B \fB\-\-ovc=<codec>\fP +Specifies the output video codec. See \fB\-\-ovc=help\fP for a full list of +supported codecs. +.TP +.B \fB\-\-ovoffset=<value>\fP +Shifts video data by the given time (in seconds) by shifting the pts +values. Deprecated. +.TP +.B \fB\-\-ovcopts=<options>\fP +Specifies the output video codec options for libavcodec. +See \-\-ovcopts=help for a full list of supported options. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fB"\-\-ovc=mpeg4 \-\-ovcopts=qscale=5"\fP +selects constant quantizer scale 5 for MPEG\-4 encoding. +.TP +.B \fB"\-\-ovc=libx264 \-\-ovcopts=crf=23"\fP +selects VBR quality factor 23 for H.264 encoding. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Options are managed in lists. There are a few commands to manage the +options list. +.INDENT 7.0 +.TP +.B \fB\-\-ovcopts\-add=<options1[,options2,...]>\fP +Appends the options given as arguments to the options list. +.TP +.B \fB\-\-ovcopts=""\fP +Completely empties the options list. +.UNINDENT +.TP +.B \fB\-\-ovfirst\fP +Force the video stream to become the first stream in the output. +By default, the order is unspecified. Deprecated. +.TP +.B \fB\-\-orawts\fP +Copies input pts to the output video (not supported by some output +container formats, e.g. AVI). In this mode, discontinuities are not fixed +and all pts are passed through as\-is. Never seek backwards or use multiple +input files in this mode! +.TP +.B \fB\-\-no\-ocopy\-metadata\fP +Turns off copying of metadata from input files to output files when +encoding (which is enabled by default). +.TP +.B \fB\-\-oset\-metadata=<metadata\-tag[,metadata\-tag,...]>\fP +Specifies metadata to include in the output file. +Supported keys vary between output formats. For example, Matroska (MKV) and +FLAC allow almost arbitrary keys, while support in MP4 and MP3 is more +limited. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.TP +.B "\fB\-\-oset\-metadata=title="Output title",comment="Another tag"\fP" +adds a title and a comment to the output file. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-oremove\-metadata=<metadata\-tag[,metadata\-tag,...]>\fP +Specifies metadata to exclude from the output file when copying from the +input file. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.TP +.B "\fB\-\-oremove\-metadata=comment,genre\fP" +excludes copying of the the comment and genre tags to the output +file. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.SH COMMAND INTERFACE +.sp +The mpv core can be controlled with commands and properties. A number of ways +to interact with the player use them: key bindings (\fBinput.conf\fP), OSD +(showing information with properties), JSON IPC, the client API (\fBlibmpv\fP), +and the classic slave mode. +.SS input.conf +.sp +The input.conf file consists of a list of key bindings, for example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +s screenshot # take a screenshot with the s key +LEFT seek 15 # map the left\-arrow key to seeking forward by 15 seconds +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Each line maps a key to an input command. Keys are specified with their literal +value (upper case if combined with \fBShift\fP), or a name for special keys. For +example, \fBa\fP maps to the \fBa\fP key without shift, and \fBA\fP maps to \fBa\fP +with shift. +.sp +The file is located in the mpv configuration directory (normally at +\fB~/.config/mpv/input.conf\fP depending on platform). The default bindings are +defined here: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +https://github.com/mpv\-player/mpv/blob/master/etc/input.conf +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +A list of special keys can be obtained with +.INDENT 0.0 +.INDENT 3.5 +\fBmpv \-\-input\-keylist\fP +.UNINDENT +.UNINDENT +.sp +In general, keys can be combined with \fBShift\fP, \fBCtrl\fP and \fBAlt\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ctrl+q quit +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBmpv\fP can be started in input test mode, which displays key bindings and the +commands they\(aqre bound to on the OSD, instead of executing the commands: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-input\-test \-\-force\-window \-\-idle +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +(Only closing the window will make \fBmpv\fP exit, pressing normal keys will +merely display the binding, even if mapped to quit.) +.SS input.conf syntax +.sp +\fB[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*\fP +.sp +Note that by default, the right Alt key can be used to create special +characters, and thus does not register as a modifier. The option +\fB\-\-no\-input\-right\-alt\-gr\fP changes this behavior. +.sp +Newlines always start a new binding. \fB#\fP starts a comment (outside of quoted +string arguments). To bind commands to the \fB#\fP key, \fBSHARP\fP can be used. +.sp +\fB<key>\fP is either the literal character the key produces (ASCII or Unicode +character), or a symbolic name (as printed by \fB\-\-input\-keylist\fP). +.sp +\fB<section>\fP (braced with \fB{\fP and \fB}\fP) is the input section for this +command. +.sp +\fB<command>\fP is the command itself. It consists of the command name and +multiple (or none) commands, all separated by whitespace. String arguments +need to be quoted with \fB"\fP\&. Details see \fBFlat command syntax\fP\&. +.sp +You can bind multiple commands to one key. For example: +.nf +a show\-text "command 1" ; show\-text "command 2" +.fi +.sp +.sp +It\(aqs also possible to bind a command to a sequence of keys: +.nf +a\-b\-c show\-text "command run after a, b, c have been pressed" +.fi +.sp +.sp +(This is not shown in the general command syntax.) +.sp +If \fBa\fP or \fBa\-b\fP or \fBb\fP are already bound, this will run the first command +that matches, and the multi\-key command will never be called. Intermediate keys +can be remapped to \fBignore\fP in order to avoid this issue. The maximum number +of (non\-modifier) keys for combinations is currently 4. +.SS Flat command syntax +.sp +This is the syntax used in input.conf, and referred to "input.conf syntax" in +a number of other places. +.sp +\fB<command> ::= [<prefixes>] <command_name> (<argument>)*\fP +\fB<argument> ::= (<string> | " <quoted_string> " )\fP +.sp +\fBcommand_name\fP is an unquoted string with the command name itself. See +\fI\%List of Input Commands\fP for a list. +.sp +Arguments are separated by whitespace. This applies even to string arguments. +For this reason, string arguments should be quoted with \fB"\fP\&. If a string +argument contains spaces or certain special characters, quoting and possibly +escaping is mandatory, or the command cannot be parsed correctly. +.sp +Inside quotes, C\-style escaping can be used. JSON escapes according to RFC 8259, +minus surrogate pair escapes, should be a safe subset that can be used. +.SS Commands specified as arrays +.sp +This applies to certain APIs, such as \fBmp.commandv()\fP or +\fBmp.command_native()\fP (with array parameters) in Lua scripting, or +\fBmpv_command()\fP or \fBmpv_command_node()\fP (with MPV_FORMAT_NODE_ARRAY) in the +C libmpv client API. +.sp +The command as well as all arguments are passed as a single array. Similar to +the \fI\%Flat command syntax\fP, you can first pass prefixes as strings (each as +separate array item), then the command name as string, and then each argument +as string or a native value. +.sp +Since these APIs pass arguments as separate strings or native values, they do +not expect quotes, and do support escaping. Technically, there is the input.conf +parser, which first splits the command string into arguments, and then invokes +argument parsers for each argument. The input.conf parser normally handles +quotes and escaping. The array command APIs mentioned above pass strings +directly to the argument parsers, or can sidestep them by the ability to pass +non\-string values. +.sp +Sometimes commands have string arguments, that in turn are actually parsed by +other components (e.g. filter strings with \fBvf add\fP) \- in these cases, you +you would have to double\-escape in input.conf, but not with the array APIs. +.sp +For complex commands, consider using \fI\%Named arguments\fP instead, which should +give slightly more compatibility. Some commands do not support named arguments +and inherently take an array, though. +.SS Named arguments +.sp +This applies to certain APIs, such as \fBmp.command_native()\fP (with tables that +have string keys) in Lua scripting, or \fBmpv_command_node()\fP (with +MPV_FORMAT_NODE_MAP) in the C libmpv client API. +.sp +Like with array commands, quoting and escaping is inherently not needed in the +normal case. +.sp +The name of each command is defined in each command description in the +\fI\%List of Input Commands\fP\&. \fB\-\-input\-cmdlist\fP also lists them. +.sp +Some commands do not support named arguments (e.g. \fBrun\fP command). You need +to use APIs that pass arguments as arrays. +.sp +Named arguments are not supported in the "flat" input.conf syntax, which means +you cannot use them for key bindings in input.conf at all. +.SS List of Input Commands +.sp +Commands with parameters have the parameter name enclosed in \fB<\fP / \fB>\fP\&. +Don\(aqt add those to the actual command. Optional arguments are enclosed in +\fB[\fP / \fB]\fP\&. If you don\(aqt pass them, they will be set to a default value. +.sp +Remember to quote string arguments in input.conf (see \fI\%Flat command syntax\fP). +.INDENT 0.0 +.TP +.B \fBignore\fP +Use this to "block" keys that should be unbound, and do nothing. Useful for +disabling default bindings, without disabling all bindings with +\fB\-\-no\-input\-default\-bindings\fP\&. +.TP +.B \fBseek <target> [<flags>]\fP +Change the playback position. By default, seeks by a relative amount of +seconds. +.sp +The second argument consists of flags controlling the seek mode: +.INDENT 7.0 +.TP +.B relative (default) +Seek relative to current position (a negative value seeks backwards). +.TP +.B absolute +Seek to a given time (a negative value starts from the end of the file). +.TP +.B absolute\-percent +Seek to a given percent position. +.TP +.B relative\-percent +Seek relative to current position in percent. +.TP +.B keyframes +Always restart playback at keyframe boundaries (fast). +.TP +.B exact +Always do exact/hr/precise seeks (slow). +.UNINDENT +.sp +Multiple flags can be combined, e.g.: \fBabsolute+keyframes\fP\&. +.sp +By default, \fBkeyframes\fP is used for \fBrelative\fP, \fBrelative\-percent\fP, +and \fBabsolute\-percent\fP seeks, while \fBexact\fP is used for \fBabsolute\fP +seeks. +.sp +Before mpv 0.9, the \fBkeyframes\fP and \fBexact\fP flags had to be passed as +3rd parameter (essentially using a space instead of \fB+\fP). The 3rd +parameter is still parsed, but is considered deprecated. +.TP +.B \fBrevert\-seek [<flags>]\fP +Undoes the \fBseek\fP command, and some other commands that seek (but not +necessarily all of them). Calling this command once will jump to the +playback position before the seek. Calling it a second time undoes the +\fBrevert\-seek\fP command itself. This only works within a single file. +.sp +The first argument is optional, and can change the behavior: +.INDENT 7.0 +.TP +.B mark +Mark the current time position. The next normal \fBrevert\-seek\fP command +will seek back to this point, no matter how many seeks happened since +last time. +.UNINDENT +.sp +Using it without any arguments gives you the default behavior. +.TP +.B \fBframe\-step\fP +Play one frame, then pause. Does nothing with audio\-only playback. +.TP +.B \fBframe\-back\-step\fP +Go back by one frame, then pause. Note that this can be very slow (it tries +to be precise, not fast), and sometimes fails to behave as expected. How +well this works depends on whether precise seeking works correctly (e.g. +see the \fB\-\-hr\-seek\-demuxer\-offset\fP option). Video filters or other video +post\-processing that modifies timing of frames (e.g. deinterlacing) should +usually work, but might make backstepping silently behave incorrectly in +corner cases. Using \fB\-\-hr\-seek\-framedrop=no\fP should help, although it +might make precise seeking slower. +.sp +This does not work with audio\-only playback. +.TP +.B \fBset <name> <value>\fP +Set the given property or option to the given value. +.TP +.B \fBadd <name> [<value>]\fP +Add the given value to the property or option. On overflow or underflow, +clamp the property to the maximum. If \fB<value>\fP is omitted, assume \fB1\fP\&. +.TP +.B \fBcycle <name> [<value>]\fP +Cycle the given property or option. The second argument can be \fBup\fP or +\fBdown\fP to set the cycle direction. On overflow, set the property back to +the minimum, on underflow set it to the maximum. If \fBup\fP or \fBdown\fP is +omitted, assume \fBup\fP\&. +.TP +.B \fBmultiply <name> <value>\fP +Similar to \fBadd\fP, but multiplies the property or option with the numeric +value. +.TP +.B \fBscreenshot <flags>\fP +Take a screenshot. +.sp +Multiple flags are available (some can be combined with \fB+\fP): +.INDENT 7.0 +.TP +.B <subtitles> (default) +Save the video image, in its original resolution, and with subtitles. +Some video outputs may still include the OSD in the output under certain +circumstances. +.TP +.B <video> +Like \fBsubtitles\fP, but typically without OSD or subtitles. The exact +behavior depends on the selected video output. +.TP +.B <window> +Save the contents of the mpv window. Typically scaled, with OSD and +subtitles. The exact behavior depends on the selected video output, and +if no support is available, this will act like \fBvideo\fP\&. +.TP +.B <each\-frame> +Take a screenshot each frame. Issue this command again to stop taking +screenshots. Note that you should disable frame\-dropping when using +this mode \- or you might receive duplicate images in cases when a +frame was dropped. This flag can be combined with the other flags, +e.g. \fBvideo+each\-frame\fP\&. +.UNINDENT +.sp +Older mpv versions required passing \fBsingle\fP and \fBeach\-frame\fP as +second argument (and did not have flags). This syntax is still understood, +but deprecated and might be removed in the future. +.sp +If you combine this command with another one using \fB;\fP, you can use the +\fBasync\fP flag to make encoding/writing the image file asynchronous. For +normal standalone commands, this is always asynchronous, and the flag has +no effect. (This behavior changed with mpv 0.29.0.) +.TP +.B \fBscreenshot\-to\-file <filename> <flags>\fP +Take a screenshot and save it to a given file. The format of the file will +be guessed by the extension (and \fB\-\-screenshot\-format\fP is ignored \- the +behavior when the extension is missing or unknown is arbitrary). +.sp +The second argument is like the first argument to \fBscreenshot\fP and +supports \fBsubtitles\fP, \fBvideo\fP, \fBwindow\fP\&. +.sp +If the file already exists, it\(aqs overwritten. +.sp +Like all input command parameters, the filename is subject to property +expansion as described in \fI\%Property Expansion\fP\&. +.TP +.B \fBplaylist\-next <flags>\fP +Go to the next entry on the playlist. +.sp +First argument: +.INDENT 7.0 +.TP +.B weak (default) +If the last file on the playlist is currently played, do nothing. +.TP +.B force +Terminate playback if there are no more files on the playlist. +.UNINDENT +.TP +.B \fBplaylist\-prev <flags>\fP +Go to the previous entry on the playlist. +.sp +First argument: +.INDENT 7.0 +.TP +.B weak (default) +If the first file on the playlist is currently played, do nothing. +.TP +.B force +Terminate playback if the first file is being played. +.UNINDENT +.TP +.B \fBloadfile <url> [<flags> [<options>]]\fP +Load the given file or URL and play it. +.sp +Second argument: +.INDENT 7.0 +.TP +.B <replace> (default) +Stop playback of the current file, and play the new file immediately. +.TP +.B <append> +Append the file to the playlist. +.TP +.B <append\-play> +Append the file, and if nothing is currently playing, start playback. +(Always starts with the added file, even if the playlist was not empty +before running this command.) +.UNINDENT +.sp +The third argument is a list of options and values which should be set +while the file is playing. It is of the form \fBopt1=value1,opt2=value2,..\fP\&. +Not all options can be changed this way. Some options require a restart +of the player. +.TP +.B \fBloadlist <url> [<flags>]\fP +Load the given playlist file or URL (like \fB\-\-playlist\fP). +.sp +Second argument: +.INDENT 7.0 +.TP +.B <replace> (default) +Stop playback and replace the internal playlist with the new one. +.TP +.B <append> +Append the new playlist at the end of the current internal playlist. +.UNINDENT +.TP +.B \fBplaylist\-clear\fP +Clear the playlist, except the currently played file. +.TP +.B \fBplaylist\-remove <index>\fP +Remove the playlist entry at the given index. Index values start counting +with 0. The special value \fBcurrent\fP removes the current entry. Note that +removing the current entry also stops playback and starts playing the next +entry. +.TP +.B \fBplaylist\-move <index1> <index2>\fP +Move the playlist entry at index1, so that it takes the place of the +entry index2. (Paradoxically, the moved playlist entry will not have +the index value index2 after moving if index1 was lower than index2, +because index2 refers to the target entry, not the index the entry +will have after moving.) +.TP +.B \fBplaylist\-shuffle\fP +Shuffle the playlist. This is similar to what is done on start if the +\fB\-\-shuffle\fP option is used. +.TP +.B \fBrun <command> [<arg1> [<arg2> [...]]]\fP +Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of +mpv (0.2.x and older), this doesn\(aqt call the shell. Instead, the command +is run directly, with each argument passed separately. Each argument is +expanded like in \fI\%Property Expansion\fP\&. +.sp +This command has a variable number of arguments, and cannot be used with +named arguments. +.sp +The program is run in a detached way. mpv doesn\(aqt wait until the command +is completed, but continues playback right after spawning it. +.sp +To get the old behavior, use \fB/bin/sh\fP and \fB\-c\fP as the first two +arguments. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +\fBrun "/bin/sh" "\-c" "echo ${title} > /tmp/playing"\fP +.sp +This is not a particularly good example, because it doesn\(aqt handle +escaping, and a specially prepared file might allow an attacker to +execute arbitrary shell commands. It is recommended to write a small +shell script, and call that with \fBrun\fP\&. +.UNINDENT +.UNINDENT +.TP +.B \fBsubprocess\fP +Similar to \fBrun\fP, but gives more control about process execution to the +caller, and does does not detach the process. +.sp +You can avoid blocking until the process terminates by running this command +asynchronously. (For example \fBmp.command_native_async()\fP in Lua scripting.) +.sp +This has the following named arguments. The order of them is not guaranteed, +so you should always call them with named arguments, see \fI\%Named arguments\fP\&. +.INDENT 7.0 +.TP +.B \fBargs\fP (\fBMPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]\fP) +Array of strings with the command as first argument, and subsequent +command line arguments following. This is just like the \fBrun\fP command +argument list. +.sp +The first array entry is either an absolute path to the executable, or +a filename with no path components, in which case the \fBPATH\fP +environment variable. On Unix, this is equivalent to \fBposix_spawnp\fP +and \fBexecvp\fP behavior. +.TP +.B \fBplayback_only\fP (\fBMPV_FORMAT_FLAG\fP) +Boolean indicating whether the process should be killed when playback +terminates (optional, default: yes). If enabled, stopping playback +will automatically kill the process, and you can\(aqt start it outside of +playback. +.TP +.B \fBcapture_size\fP (\fBMPV_FORMAT_INT64\fP) +Integer setting the maximum number of stdout plus stderr bytes that can +be captured (optional, default: 64MB). If the number of bytes exceeds +this, capturing is stopped. The limit is per captured stream. +.TP +.B \fBcapture_stdout\fP (\fBMPV_FORMAT_FLAG\fP) +Capture all data the process outputs to stdout and return it once the +process ends (optional, default: no). +.TP +.B \fBcapture_stderr\fP (\fBMPV_FORMAT_FLAG\fP) +Same as \fBcapture_stdout\fP, but for stderr. +.UNINDENT +.sp +The command returns the following result (as \fBMPV_FORMAT_NODE_MAP\fP): +.INDENT 7.0 +.TP +.B \fBstatus\fP (\fBMPV_FORMAT_INT64\fP) +The raw exit status of the process. It will be negative on error. The +meaning of negative values is undefined, other than meaning error (and +does not necessarily correspond to OS low level exit status values). +.sp +On Windows, it can happen that a negative return value is returned +even if the process exits gracefully, because the win32 \fBUINT\fP exit +code is assigned to an \fBint\fP variable before being set as \fBint64_t\fP +field in the result map. This might be fixed later. +.TP +.B \fBstdout\fP (\fBMPV_FORMAT_BYTE_ARRAY\fP) +Captured stdout stream, limited to \fBcapture_size\fP\&. +.TP +.B \fBstderr\fP (\fBMPV_FORMAT_BYTE_ARRAY\fP) +Same as \fBstdout\fP, but for stderr. +.TP +.B \fBerror_string\fP (\fBMPV_FORMAT_STRING\fP) +Empty string if the process exited gracefully. The string \fBkilled\fP if +the process was terminated in an unusual way. The string \fBinit\fP if the +process could not be started. +.sp +On Windows, \fBkilled\fP is only returned when the process has been +killed by mpv as a result of \fBplayback_only\fP being set to \fByes\fP\&. +.TP +.B \fBkilled_by_us\fP (\fBMPV_FORMAT_FLAG\fP) +Set to \fByes\fP if the process has been killed by mpv, for example as a +result of \fBplayback_only\fP being set to \fByes\fP, aborting the command +(e.g. by \fBmp.abort_async_command()\fP), or if the player is about to +exit. +.UNINDENT +.sp +Note that the command itself will always return success as long as the +parameters are correct. Whether the process could be spawned or whether +it was somehow killed or returned an error status has to be queried from +the result value. +.sp +This command can be asynchronously aborted via API. +.sp +In all cases, the subprocess will be terminated on player exit. Also see +\fI\%Asynchronous command details\fP\&. Only the \fBrun\fP command can start +processes in a truly detached way. +.INDENT 7.0 +.INDENT 3.5 +.IP "Warning" +.sp +Don\(aqt forget to set the \fBplayback_only\fP field if you want the command +run while the player is in idle mode, or if you don\(aqt want that end of +playback kills the command. +.UNINDENT +.UNINDENT +.TP +.B \fBquit [<code>]\fP +Exit the player. If an argument is given, it\(aqs used as process exit code. +.TP +.B \fBquit\-watch\-later [<code>]\fP +Exit player, and store current playback position. Playing that file later +will seek to the previous position on start. The (optional) argument is +exactly as in the \fBquit\fP command. +.TP +.B \fBsub\-add <url> [<flags> [<title> [<lang>]]]\fP +Load the given subtitle file or stream. By default, it is selected as +current subtitle after loading. +.sp +The \fBflags\fP argument is one of the following values: +.sp +<select> +.INDENT 7.0 +.INDENT 3.5 +Select the subtitle immediately (default). +.UNINDENT +.UNINDENT +.sp +<auto> +.INDENT 7.0 +.INDENT 3.5 +Don\(aqt select the subtitle. (Or in some special situations, let the +default stream selection mechanism decide.) +.UNINDENT +.UNINDENT +.sp +<cached> +.INDENT 7.0 +.INDENT 3.5 +Select the subtitle. If a subtitle with the same filename was already +added, that one is selected, instead of loading a duplicate entry. +(In this case, title/language are ignored, and if the was changed since +it was loaded, these changes won\(aqt be reflected.) +.UNINDENT +.UNINDENT +.sp +The \fBtitle\fP argument sets the track title in the UI. +.sp +The \fBlang\fP argument sets the track language, and can also influence +stream selection with \fBflags\fP set to \fBauto\fP\&. +.TP +.B \fBsub\-remove [<id>]\fP +Remove the given subtitle track. If the \fBid\fP argument is missing, remove +the current track. (Works on external subtitle files only.) +.TP +.B \fBsub\-reload [<id>]\fP +Reload the given subtitle tracks. If the \fBid\fP argument is missing, reload +the current track. (Works on external subtitle files only.) +.sp +This works by unloading and re\-adding the subtitle track. +.TP +.B \fBsub\-step <skip>\fP +Change subtitle timing such, that the subtitle event after the next +\fB<skip>\fP subtitle events is displayed. \fB<skip>\fP can be negative to step +backwards. +.TP +.B \fBsub\-seek <skip>\fP +Seek to the next (skip set to 1) or the previous (skip set to \-1) subtitle. +This is similar to \fBsub\-step\fP, except that it seeks video and audio +instead of adjusting the subtitle delay. +.sp +For embedded subtitles (like with Matroska), this works only with subtitle +events that have already been displayed, or are within a short prefetch +range. +.TP +.B \fBprint\-text <text>\fP +Print text to stdout. The string can contain properties (see +\fI\%Property Expansion\fP). Take care to put the argument in quotes. +.TP +.B \fBshow\-text <text> [<duration>|\-1 [<level>]]\fP +Show text on the OSD. The string can contain properties, which are expanded +as described in \fI\%Property Expansion\fP\&. This can be used to show playback +time, filename, and so on. +.INDENT 7.0 +.TP +.B <duration> +The time in ms to show the message for. By default, it uses the same +value as \fB\-\-osd\-duration\fP\&. +.TP +.B <level> +The minimum OSD level to show the text at (see \fB\-\-osd\-level\fP). +.UNINDENT +.TP +.B \fBexpand\-text <string>\fP +Property\-expand the argument and return the expanded string. This can be +used only through the client API or from a script using +\fBmp.command_native\fP\&. (see \fI\%Property Expansion\fP). +.TP +.B \fBexpand\-path "<string>"\fP +Expand a path\(aqs double\-tilde placeholders into a platform\-specific path. +As \fBexpand\-text\fP, this can only be used through the client API or from +a script using \fBmp.command_native\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +\fBmp.osd_message(mp.command_native({"expand\-path", "~~home/"}))\fP +.sp +This line of Lua would show the location of the user\(aqs mpv +configuration directory on the OSD. +.UNINDENT +.UNINDENT +.TP +.B \fBshow\-progress\fP +Show the progress bar, the elapsed time and the total duration of the file +on the OSD. +.TP +.B \fBwrite\-watch\-later\-config\fP +Write the resume config file that the \fBquit\-watch\-later\fP command writes, +but continue playback normally. +.TP +.B \fBstop\fP +Stop playback and clear playlist. With default settings, this is +essentially like \fBquit\fP\&. Useful for the client API: playback can be +stopped without terminating the player. +.TP +.B \fBmouse <x> <y> [<button> [<mode>]]\fP +Send a mouse event with given coordinate (\fB<x>\fP, \fB<y>\fP). +.sp +Second argument: +.INDENT 7.0 +.TP +.B <button> +The button number of clicked mouse button. This should be one of 0\-19. +If \fB<button>\fP is omitted, only the position will be updated. +.UNINDENT +.sp +Third argument: +.INDENT 7.0 +.TP +.B <single> (default) +The mouse event represents regular single click. +.TP +.B <double> +The mouse event represents double\-click. +.UNINDENT +.TP +.B \fBkeypress <name>\fP +Send a key event through mpv\(aqs input handler, triggering whatever +behavior is configured to that key. \fBname\fP uses the \fBinput.conf\fP +naming scheme for keys and modifiers. Useful for the client API: key events +can be sent to libmpv to handle internally. +.TP +.B \fBkeydown <name>\fP +Similar to \fBkeypress\fP, but sets the \fBKEYDOWN\fP flag so that if the key is +bound to a repeatable command, it will be run repeatedly with mpv\(aqs key +repeat timing until the \fBkeyup\fP command is called. +.TP +.B \fBkeyup [<name>]\fP +Set the \fBKEYUP\fP flag, stopping any repeated behavior that had been +triggered. \fBname\fP is optional. If \fBname\fP is not given or is an +empty string, \fBKEYUP\fP will be set on all keys. Otherwise, \fBKEYUP\fP will +only be set on the key specified by \fBname\fP\&. +.TP +.B \fBkeybind <name> <command>\fP +Binds a key to an input command. \fBcommand\fP must be a complete command +containing all the desired arguments and flags. Both \fBname\fP and +\fBcommand\fP use the \fBinput.conf\fP naming scheme. This is primarily +useful for the client API. +.TP +.B \fBaudio\-add <url> [<flags> [<title> [<lang>]]]\fP +Load the given audio file. See \fBsub\-add\fP command. +.TP +.B \fBaudio\-remove [<id>]\fP +Remove the given audio track. See \fBsub\-remove\fP command. +.TP +.B \fBaudio\-reload [<id>]\fP +Reload the given audio tracks. See \fBsub\-reload\fP command. +.TP +.B \fBvideo\-add <url> [<flags> [<title> [<lang>]]]\fP +Load the given video file. See \fBsub\-add\fP command. +.TP +.B \fBvideo\-remove [<id>]\fP +Remove the given video track. See \fBsub\-remove\fP command. +.TP +.B \fBvideo\-reload [<id>]\fP +Reload the given video tracks. See \fBsub\-reload\fP command. +.TP +.B \fBrescan\-external\-files [<mode>]\fP +Rescan external files according to the current \fB\-\-sub\-auto\fP and +\fB\-\-audio\-file\-auto\fP settings. This can be used to auto\-load external +files \fIafter\fP the file was loaded. +.sp +The \fBmode\fP argument is one of the following: +.INDENT 7.0 +.TP +.B <reselect> (default) +Select the default audio and subtitle streams, which typically selects +external files with the highest preference. (The implementation is not +perfect, and could be improved on request.) +.TP +.B <keep\-selection> +Do not change current track selections. +.UNINDENT +.UNINDENT +.SS Input Commands that are Possibly Subject to Change +.INDENT 0.0 +.TP +.B \fBaf <operation> <value>\fP +Change audio filter chain. See \fBvf\fP command. +.TP +.B \fBvf <operation> <value>\fP +Change video filter chain. +.sp +The first argument decides what happens: +.INDENT 7.0 +.TP +.B <set> +Overwrite the previous filter chain with the new one. +.TP +.B <add> +Append the new filter chain to the previous one. +.TP +.B <toggle> +Check if the given filter (with the exact parameters) is already +in the video chain. If yes, remove the filter. If no, add the filter. +(If several filters are passed to the command, this is done for +each filter.) +.sp +A special variant is combining this with labels, and using \fB@name\fP +without filter name and parameters as filter entry. This toggles the +enable/disable flag. +.TP +.B <del> +Remove the given filters from the video chain. Unlike in the other +cases, the second parameter is a comma separated list of filter names +or integer indexes. \fB0\fP would denote the first filter. Negative +indexes start from the last filter, and \fB\-1\fP denotes the last +filter. +.TP +.B <clr> +Remove all filters. Note that like the other sub\-commands, this does +not control automatically inserted filters. +.UNINDENT +.sp +The argument is always needed. E.g. in case of \fBclr\fP use \fBvf clr ""\fP\&. +.sp +You can assign labels to filter by prefixing them with \fB@name:\fP (where +\fBname\fP is a user\-chosen arbitrary identifier). Labels can be used to +refer to filters by name in all of the filter chain modification commands. +For \fBadd\fP, using an already used label will replace the existing filter. +.sp +The \fBvf\fP command shows the list of requested filters on the OSD after +changing the filter chain. This is roughly equivalent to +\fBshow\-text ${vf}\fP\&. Note that auto\-inserted filters for format conversion +are not shown on the list, only what was requested by the user. +.sp +Normally, the commands will check whether the video chain is recreated +successfully, and will undo the operation on failure. If the command is run +before video is configured (can happen if the command is run immediately +after opening a file and before a video frame is decoded), this check can\(aqt +be run. Then it can happen that creating the video chain fails. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example for input.conf" +.INDENT 0.0 +.IP \(bu 2 +\fBa vf set flip\fP turn video upside\-down on the \fBa\fP key +.IP \(bu 2 +\fBb vf set ""\fP remove all video filters on \fBb\fP +.IP \(bu 2 +\fBc vf toggle gradfun\fP toggle debanding on \fBc\fP +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.IP "Example how to toggle disabled filters at runtime" +.INDENT 0.0 +.IP \(bu 2 +Add something like \fBvf\-add=@deband:!gradfun\fP to \fBmpv.conf\fP\&. +The \fB@deband:\fP is the label, an arbitrary, user\-given name for this +filter entry. The \fB!\fP before the filter name disables the filter by +default. Everything after this is the normal filter name and possibly +filter parameters, like in the normal \fB\-\-vf\fP syntax. +.IP \(bu 2 +Add \fBa vf toggle @deband\fP to \fBinput.conf\fP\&. This toggles the +"disabled" flag for the filter with the label \fBdeband\fP when the +\fBa\fP key is hit. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fBcycle\-values [<"!reverse">] <property> <value1> [<value2> [...]]\fP +Cycle through a list of values. Each invocation of the command will set the +given property to the next value in the list. The command will use the +current value of the property/option, and use it to determine the current +position in the list of values. Once it has found it, it will set the +next value in the list (wrapping around to the first item if needed). +.sp +This command has a variable number of arguments, and cannot be used with +named arguments. +.sp +The special argument \fB!reverse\fP can be used to cycle the value list in +reverse. The only advantage is that you don\(aqt need to reverse the value +list yourself when adding a second key binding for cycling backwards. +.TP +.B \fBenable\-section <name> [<flags>]\fP +Enable all key bindings in the named input section. +.sp +The enabled input sections form a stack. Bindings in sections on the top of +the stack are preferred to lower sections. This command puts the section +on top of the stack. If the section was already on the stack, it is +implicitly removed beforehand. (A section cannot be on the stack more than +once.) +.sp +The \fBflags\fP parameter can be a combination (separated by \fB+\fP) of the +following flags: +.INDENT 7.0 +.TP +.B <exclusive> +All sections enabled before the newly enabled section are disabled. +They will be re\-enabled as soon as all exclusive sections above them +are removed. In other words, the new section shadows all previous +sections. +.TP +.B <allow\-hide\-cursor> +This feature can\(aqt be used through the public API. +.TP +.B <allow\-vo\-dragging> +Same. +.UNINDENT +.TP +.B \fBdisable\-section <name>\fP +Disable the named input section. Undoes \fBenable\-section\fP\&. +.TP +.B \fBdefine\-section <name> <contents> [<flags>]\fP +Create a named input section, or replace the contents of an already existing +input section. The \fBcontents\fP parameter uses the same syntax as the +\fBinput.conf\fP file (except that using the section syntax in it is not +allowed), including the need to separate bindings with a newline character. +.sp +If the \fBcontents\fP parameter is an empty string, the section is removed. +.sp +The section with the name \fBdefault\fP is the normal input section. +.sp +In general, input sections have to be enabled with the \fBenable\-section\fP +command, or they are ignored. +.sp +The last parameter has the following meaning: +.INDENT 7.0 +.TP +.B <default> (also used if parameter omitted) +Use a key binding defined by this section only if the user hasn\(aqt +already bound this key to a command. +.TP +.B <force> +Always bind a key. (The input section that was made active most recently +wins if there are ambiguities.) +.UNINDENT +.sp +This command can be used to dispatch arbitrary keys to a script or a client +API user. If the input section defines \fBscript\-binding\fP commands, it is +also possible to get separate events on key up/down, and relatively detailed +information about the key state. The special key name \fBunmapped\fP can be +used to match any unmapped key. +.TP +.B \fBoverlay\-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>\fP +Add an OSD overlay sourced from raw data. This might be useful for scripts +and applications controlling mpv, and which want to display things on top +of the video window. +.sp +Overlays are usually displayed in screen resolution, but with some VOs, +the resolution is reduced to that of the video\(aqs. You can read the +\fBosd\-width\fP and \fBosd\-height\fP properties. At least with \fB\-\-vo\-xv\fP and +anamorphic video (such as DVD), \fBosd\-par\fP should be read as well, and the +overlay should be aspect\-compensated. +.sp +This has the following named arguments. The order of them is not guaranteed, +so you should always call them with named arguments, see \fI\%Named arguments\fP\&. +.sp +\fBid\fP is an integer between 0 and 63 identifying the overlay element. The +ID can be used to add multiple overlay parts, update a part by using this +command with an already existing ID, or to remove a part with +\fBoverlay\-remove\fP\&. Using a previously unused ID will add a new overlay, +while reusing an ID will update it. +.sp +\fBx\fP and \fBy\fP specify the position where the OSD should be displayed. +.sp +\fBfile\fP specifies the file the raw image data is read from. It can be +either a numeric UNIX file descriptor prefixed with \fB@\fP (e.g. \fB@4\fP), +or a filename. The file will be mapped into memory with \fBmmap()\fP, +copied, and unmapped before the command returns (changed in mpv 0.18.1). +.sp +It is also possible to pass a raw memory address for use as bitmap memory +by passing a memory address as integer prefixed with an \fB&\fP character. +Passing the wrong thing here will crash the player. This mode might be +useful for use with libmpv. The \fBoffset\fP parameter is simply added to the +memory address (since mpv 0.8.0, ignored before). +.sp +\fBoffset\fP is the byte offset of the first pixel in the source file. +(The current implementation always mmap\(aqs the whole file from position 0 to +the end of the image, so large offsets should be avoided. Before mpv 0.8.0, +the offset was actually passed directly to \fBmmap\fP, but it was changed to +make using it easier.) +.sp +\fBfmt\fP is a string identifying the image format. Currently, only \fBbgra\fP +is defined. This format has 4 bytes per pixels, with 8 bits per component. +The least significant 8 bits are blue, and the most significant 8 bits +are alpha (in little endian, the components are B\-G\-R\-A, with B as first +byte). This uses premultiplied alpha: every color component is already +multiplied with the alpha component. This means the numeric value of each +component is equal to or smaller than the alpha component. (Violating this +rule will lead to different results with different VOs: numeric overflows +resulting from blending broken alpha values is considered something that +shouldn\(aqt happen, and consequently implementations don\(aqt ensure that you +get predictable behavior in this case.) +.sp +\fBw\fP, \fBh\fP, and \fBstride\fP specify the size of the overlay. \fBw\fP is the +visible width of the overlay, while \fBstride\fP gives the width in bytes in +memory. In the simple case, and with the \fBbgra\fP format, \fBstride==4*w\fP\&. +In general, the total amount of memory accessed is \fBstride * h\fP\&. +(Technically, the minimum size would be \fBstride * (h \- 1) + w * 4\fP, but +for simplicity, the player will access all \fBstride * h\fP bytes.) +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Before mpv 0.18.1, you had to do manual "double buffering" when updating +an overlay by replacing it with a different memory buffer. Since mpv +0.18.1, the memory is simply copied and doesn\(aqt reference any of the +memory indicated by the command\(aqs arguments after the commend returns. +If you want to use this command before mpv 0.18.1, reads the old docs +to see how to handle this correctly. +.UNINDENT +.UNINDENT +.TP +.B \fBoverlay\-remove <id>\fP +Remove an overlay added with \fBoverlay\-add\fP and the same ID. Does nothing +if no overlay with this ID exists. +.TP +.B \fBscript\-message [<arg1> [<arg2> [...]]]\fP +Send a message to all clients, and pass it the following list of arguments. +What this message means, how many arguments it takes, and what the arguments +mean is fully up to the receiver and the sender. Every client receives the +message, so be careful about name clashes (or use \fBscript\-message\-to\fP). +.sp +This command has a variable number of arguments, and cannot be used with +named arguments. +.TP +.B \fBscript\-message\-to <target> [<arg1> [<arg2> [...]]]\fP +Same as \fBscript\-message\fP, but send it only to the client named +\fB<target>\fP\&. Each client (scripts etc.) has a unique name. For example, +Lua scripts can get their name via \fBmp.get_script_name()\fP\&. +.sp +This command has a variable number of arguments, and cannot be used with +named arguments. +.TP +.B \fBscript\-binding <name>\fP +Invoke a script\-provided key binding. This can be used to remap key +bindings provided by external Lua scripts. +.sp +The argument is the name of the binding. +.sp +It can optionally be prefixed with the name of the script, using \fB/\fP as +separator, e.g. \fBscript\-binding scriptname/bindingname\fP\&. +.sp +For completeness, here is how this command works internally. The details +could change any time. On any matching key event, \fBscript\-message\-to\fP +or \fBscript\-message\fP is called (depending on whether the script name is +included), with the following arguments: +.INDENT 7.0 +.IP 1. 3 +The string \fBkey\-binding\fP\&. +.IP 2. 3 +The name of the binding (as established above). +.IP 3. 3 +The key state as string (see below). +.IP 4. 3 +The key name (since mpv 0.15.0). +.UNINDENT +.sp +The key state consists of 2 letters: +.INDENT 7.0 +.IP 1. 3 +One of \fBd\fP (key was pressed down), \fBu\fP (was released), \fBr\fP (key +is still down, and was repeated; only if key repeat is enabled for this +binding), \fBp\fP (key was pressed; happens if up/down can\(aqt be tracked). +.IP 2. 3 +Whether the event originates from the mouse, either \fBm\fP (mouse button) +or \fB\-\fP (something else). +.UNINDENT +.TP +.B \fBab\-loop\fP +Cycle through A\-B loop states. The first command will set the \fBA\fP point +(the \fBab\-loop\-a\fP property); the second the \fBB\fP point, and the third +will clear both points. +.TP +.B \fBdrop\-buffers\fP +Drop audio/video/demuxer buffers, and restart from fresh. Might help with +unseekable streams that are going out of sync. +This command might be changed or removed in the future. +.TP +.B \fBscreenshot\-raw [<flags>]\fP +Return a screenshot in memory. This can be used only through the client +API. The MPV_FORMAT_NODE_MAP returned by this command has the \fBw\fP, \fBh\fP, +\fBstride\fP fields set to obvious contents. The \fBformat\fP field is set to +\fBbgr0\fP by default. This format is organized as \fBB8G8R8X8\fP (where \fBB\fP +is the LSB). The contents of the padding \fBX\fP are undefined. The \fBdata\fP +field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image +is freed as soon as the result mpv_node is freed. As usual with client API +semantics, you are not allowed to write to the image data. +.sp +The \fBstride\fP is the number of bytes from a pixel at \fB(x0, y0)\fP to the +pixel at \fB(x0, y0 + 1)\fP\&. This can be larger than \fBw * 4\fP if the image +was cropped, or if there is padding. This number can be negative as well. +You access a pixel with \fBbyte_index = y * stride + x * 4\fP (assuming the +\fBbgr0\fP format). +.sp +The \fBflags\fP argument is like the first argument to \fBscreenshot\fP and +supports \fBsubtitles\fP, \fBvideo\fP, \fBwindow\fP\&. +.TP +.B \fBvf\-command <label> <command> <argument>\fP +Send a command to the filter with the given \fB<label>\fP\&. Use \fBall\fP to send +it to all filters at once. The command and argument string is filter +specific. Currently, this only works with the \fBlavfi\fP filter \- see +the libavfilter documentation for which commands a filter supports. +.sp +Note that the \fB<label>\fP is a mpv filter label, not a libavfilter filter +name. +.TP +.B \fBaf\-command <label> <command> <argument>\fP +Same as \fBvf\-command\fP, but for audio filters. +.TP +.B \fBapply\-profile <name>\fP +Apply the contents of a named profile. This is like using \fBprofile=name\fP +in a config file, except you can map it to a key binding to change it at +runtime. +.sp +There is no such thing as "unapplying" a profile \- applying a profile +merely sets all option values listed within the profile. +.TP +.B \fBload\-script <filename>\fP +Load a script, similar to the \fB\-\-script\fP option. Whether this waits for +the script to finish initialization or not changed multiple times, and the +future behavior is left undefined. +.TP +.B \fBchange\-list <name> <operation> <value>\fP +This command changes list options as described in \fI\%List Options\fP\&. The +\fB<name>\fP parameter is the normal option name, while \fB<operation>\fP is +the suffix or action used on the option. +.sp +Some operations take no value, but the command still requires the value +parameter. In these cases, the value must be an empty string. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +\fBchange\-list glsl\-shaders append file.glsl\fP +.sp +Add a filename to the \fBglsl\-shaders\fP list. The command line +equivalent is \fB\-\-glsl\-shaders\-append=file.glsl\fP or alternatively +\fB\-\-glsl\-shader=file.glsl\fP\&. +.UNINDENT +.UNINDENT +.TP +.B \fBdump\-cache <start> <end> <filename>\fP +Dump the current cache to the given filename. The \fB<filename>\fP file is +overwritten if it already exists. \fB<start>\fP and \fB<end>\fP give the +time range of what to dump. If no data is cached at the given time range, +nothing may be dumped (creating a file with no packets). +.sp +Dumping a larger part of the cache will freeze the player. No effort was +made to fix this, as this feature was meant mostly for creating small +excerpts. +.sp +See \fB\-\-stream\-record\fP for various caveats that mostly apply to this +command too, as both use the same underlying code for writing the output +file. +.sp +If \fB<filename>\fP is an empty string, an ongoing \fBdump\-cache\fP is stopped. +.sp +If \fB<end>\fP is \fBno\fP, then continuous dumping is enabled. Then, after +dumping the existing parts of the cache, anything read from network is +appended to the cache as well. This behaves similar to \fB\-\-stream\-record\fP +(although it does not conflict with that option, and they can be both active +at the same time). +.sp +If the \fB<end>\fP time is after the cache, the command will _not_ wait and +write newly received data to it. +.sp +The end of the resulting file may be slightly damaged or incomplete at the +end. (Not enough effort was made to ensure that the end lines up properly.) +.sp +Note that this command will finish only once dumping ends. That means it +works similar to the \fBscreenshot\fP command, just that it can block much +longer. If continuous dumping is used, the command will not finish until +playback is stopped, an error happens, another \fBdump\-cache\fP command is +run, or an API like \fBmp.abort_async_command\fP was called to explicitly stop +the command. See \fI\%Synchronous vs. Asynchronous\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This was mostly created for network streams. For local files, there may +be much better methods to create excerpts and such. There are tons of +much more user\-friendly Lua scripts, that will reencode parts of a file +by spawning a separate instance of \fBffmpeg\fP\&. With network streams, +this is not that easily possible, as the stream would have to be +downloaded again. Even if \fB\-\-stream\-record\fP is used to record the +stream to the local filesystem, there may be problems, because the +recorded file is still written to. +.UNINDENT +.UNINDENT +.sp +This command is experimental, and all details about it may change in the +future. +.TP +.B \fBab\-loop\-dump\-cache <filename>\fP +Essentially calls \fBdump\-cache\fP with the current AB\-loop points as +arguments. Like \fBdump\-cache\fP, this will overwrite the file at +\fB<filename>\fP\&. Likewise, if the B point is set to \fBno\fP, it will enter +continuous dumping after the existing cache was dumped. +.sp +The author reserves the right to remove this command if enough motivation +is found to move this functionality to a trivial Lua script. +.TP +.B \fBab\-loop\-align\-cache\fP +Re\-adjust the A/B loop points to the start and end within the cache the +\fBab\-loop\-dump\-cache\fP command will (probably) dump. Basically, it aligns +the times on keyframes. The guess might be off especially at the end (due to +granularity issues due to remuxing). If the cache shrinks in the meantime, +the points set by the command will not be the effective parameters either. +.sp +This command has an even more uncertain future than \fBab\-loop\-dump\-cache\fP +and might disappear without replacement if the author decides it\(aqs useless. +.UNINDENT +.sp +Undocumented commands: \fBao\-reload\fP (experimental/internal). +.SS Hooks +.sp +Hooks are synchronous events between player core and a script or similar. This +applies to client API (including the Lua scripting interface). Normally, +events are supposed to be asynchronous, and the hook API provides an awkward +and obscure way to handle events that require stricter coordination. There are +no API stability guarantees made. Not following the protocol exactly can make +the player freeze randomly. Basically, nobody should use this API. +.sp +The C API is described in the header files. The Lua API is described in the +Lua section. +.sp +The following hooks are currently defined: +.INDENT 0.0 +.TP +.B \fBon_load\fP +Called when a file is to be opened, before anything is actually done. +For example, you could read and write the \fBstream\-open\-filename\fP +property to redirect an URL to something else (consider support for +streaming sites which rarely give the user a direct media URL), or +you could set per\-file options with by setting the property +\fBfile\-local\-options/<option name>\fP\&. The player will wait until all +hooks are run. +.TP +.B \fBon_load_fail\fP +Called after after a file has been opened, but failed to. This can be +used to provide a fallback in case native demuxers failed to recognize +the file, instead of always running before the native demuxers like +\fBon_load\fP\&. Demux will only be retried if \fBstream\-open\-filename\fP +was changed. +.TP +.B \fBon_preloaded\fP +Called after a file has been opened, and before tracks are selected and +decoders are created. This has some usefulness if an API users wants +to select tracks manually, based on the set of available tracks. It\(aqs +also useful to initialize \fB\-\-lavfi\-complex\fP in a specific way by API, +without having to "probe" the available streams at first. +.sp +Note that this does not yet apply default track selection. Which operations +exactly can be done and not be done, and what information is available and +what is not yet available yet, is all subject to change. +.TP +.B \fBon_unload\fP +Run before closing a file, and before actually uninitializing +everything. It\(aqs not possible to resume playback in this state. +.UNINDENT +.SS Legacy hook API +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +The legacy API is deprecated and will be removed soon. +.UNINDENT +.UNINDENT +.sp +There are two special commands involved. Also, the client must listen for +client messages (\fBMPV_EVENT_CLIENT_MESSAGE\fP in the C API). +.INDENT 0.0 +.TP +.B \fBhook\-add <hook\-name> <id> <priority>\fP +Subscribe to the hook identified by the first argument (basically, the +name of event). The \fBid\fP argument is an arbitrary integer chosen by the +user. \fBpriority\fP is used to sort all hook handlers globally across all +clients. Each client can register multiple hook handlers (even for the +same hook\-name). Once the hook is registered, it cannot be unregistered. +.sp +When a specific event happens, all registered handlers are run serially. +This uses a protocol every client has to follow explicitly. When a hook +handler is run, a client message (\fBMPV_EVENT_CLIENT_MESSAGE\fP) is sent to +the client which registered the hook. This message has the following +arguments: +.INDENT 7.0 +.IP 1. 3 +the string \fBhook_run\fP +.IP 2. 3 +the \fBid\fP argument the hook was registered with as string (this can be +used to correctly handle multiple hooks registered by the same client, +as long as the \fBid\fP argument is unique in the client) +.IP 3. 3 +something undefined, used by the hook mechanism to track hook execution +.UNINDENT +.sp +Upon receiving this message, the client can handle the event. While doing +this, the player core will still react to requests, but playback will +typically be stopped. +.sp +When the client is done, it must continue the core\(aqs hook execution by +running the \fBhook\-ack\fP command. +.TP +.B \fBhook\-ack <string>\fP +Run the next hook in the global chain of hooks. The argument is the 3rd +argument of the client message that starts hook execution for the +current client. +.UNINDENT +.SS Input Command Prefixes +.sp +These prefixes are placed between key name and the actual command. Multiple +prefixes can be specified. They are separated by whitespace. +.INDENT 0.0 +.TP +.B \fBosd\-auto\fP +Use the default behavior for this command. This is the default for +\fBinput.conf\fP commands. Some libmpv/scripting/IPC APIs do not use this as +default, but use \fBno\-osd\fP instead. +.TP +.B \fBno\-osd\fP +Do not use any OSD for this command. +.TP +.B \fBosd\-bar\fP +If possible, show a bar with this command. Seek commands will show the +progress bar, property changing commands may show the newly set value. +.TP +.B \fBosd\-msg\fP +If possible, show an OSD message with this command. Seek command show +the current playback time, property changing commands show the newly set +value as text. +.TP +.B \fBosd\-msg\-bar\fP +Combine osd\-bar and osd\-msg. +.TP +.B \fBraw\fP +Do not expand properties in string arguments. (Like \fB"${property\-name}"\fP\&.) +This is the default for some libmpv/scripting/IPC APIs. +.TP +.B \fBexpand\-properties\fP +All string arguments are expanded as described in \fI\%Property Expansion\fP\&. +This is the default for \fBinput.conf\fP commands. +.TP +.B \fBrepeatable\fP +For some commands, keeping a key pressed doesn\(aqt run the command repeatedly. +This prefix forces enabling key repeat in any case. +.TP +.B \fBasync\fP +Allow asynchronous execution (if possible). Note that only a few commands +will support this (usually this is explicitly documented). Some commands +are asynchronous by default (or rather, their effects might manifest +after completion of the command). The semantics of this flag might change +in the future. Set it only if you don\(aqt rely on the effects of this command +being fully realized when it returns. See \fI\%Synchronous vs. Asynchronous\fP\&. +.TP +.B \fBsync\fP +Allow synchronous execution (if possible). Normally, all commands are +synchronous by default, but some are asynchronous by default for +compatibility with older behavior. +.UNINDENT +.sp +All of the osd prefixes are still overridden by the global \fB\-\-osd\-level\fP +settings. +.SS Synchronous vs. Asynchronous +.sp +The \fBasync\fP and \fBsync\fP prefix matter only for how the issuer of the command +waits on the completion of the command. Normally it does not affect how the +command behaves by itself. There are the following cases: +.INDENT 0.0 +.IP \(bu 2 +Normal input.conf commands are always run asynchronously. Slow running +commands are queued up or run in parallel. +.IP \(bu 2 +"Multi" input.conf commands (1 key binding, concatenated with \fB;\fP) will be +executed in order, except for commands that are async (either prefixed with +\fBasync\fP, or async by default for some commands). The async commands are +run in a detached manner, possibly in parallel to the remaining sync commands +in the list. +.IP \(bu 2 +Normal Lua and libmpv commands (e.g. \fBmpv_command()\fP) are run in a blocking +manner, unless the \fBasync\fP prefix is used, or the command is async by +default. This means in the sync case the caller will block, even if the core +continues playback. Async mode runs the command in a detached manner. +.IP \(bu 2 +Async libmpv command API (e.g. \fBmpv_command_async()\fP) never blocks the +caller, and always notify their completion with a message. The \fBsync\fP and +\fBasync\fP prefixes make no difference. +.IP \(bu 2 +Lua also provides APIs for running async commands, which behave similar to the +C counterparts. +.IP \(bu 2 +In all cases, async mode can still run commands in a synchronous manner, even +in detached mode. This can for example happen in cases when a command does not +have an asynchronous implementation. The async libmpv API still never blocks +the caller in these cases. +.UNINDENT +.sp +Before mpv 0.29.0, the \fBasync\fP prefix was only used by screenshot commands, +and made them run the file saving code in a detached manner. This is the +default now, and \fBasync\fP changes behavior only in the ways mentioned above. +.sp +Currently the following commands have different waiting characteristics with +sync vs. async: sub\-add, audio\-add, sub\-reload, audio\-reload, +rescan\-external\-files, screenshot, screenshot\-to\-file, dump\-cache, +ab\-loop\-dump\-cache. +.SS Asynchronous command details +.sp +On the API level, every asynchronous command is bound to the context which +started it. For example, an asynchronous command started by \fBmpv_command_async\fP +is bound to the \fBmpv_handle\fP passed to the function. Only this \fBmpv_handle\fP +receives the completion notification (\fBMPV_EVENT_COMMAND_REPLY\fP), and only +this handle can abort a still running command directly. If the \fBmpv_handle\fP is +destroyed, any still running async. commands started by it are terminated. +.sp +The scripting APIs and JSON IPC give each script/connection its own implicit +\fBmpv_handle\fP\&. +.sp +If the player is closed, the core may abort all pending async. commands on its +own (like a forced \fBmpv_abort_async_command()\fP call for each pending command +on behalf of the API user). This happens at the same time \fBMPV_EVENT_SHUTDOWN\fP +is sent, and there is no way to prevent this. +.SS Input Sections +.sp +Input sections group a set of bindings, and enable or disable them at once. +In \fBinput.conf\fP, each key binding is assigned to an input section, rather +than actually having explicit text sections. +.sp +See also: \fBenable\-section\fP and \fBdisable\-section\fP commands. +.sp +Predefined bindings: +.INDENT 0.0 +.TP +.B \fBdefault\fP +Bindings without input section are implicitly assigned to this section. It +is enabled by default during normal playback. +.TP +.B \fBencode\fP +Section which is active in encoding mode. It is enabled exclusively, so +that bindings in the \fBdefault\fP sections are ignored. +.UNINDENT +.SS Properties +.sp +Properties are used to set mpv options during runtime, or to query arbitrary +information. They can be manipulated with the \fBset\fP/\fBadd\fP/\fBcycle\fP +commands, and retrieved with \fBshow\-text\fP, or anything else that uses property +expansion. (See \fI\%Property Expansion\fP\&.) +.sp +The property name is annotated with RW to indicate whether the property is +generally writable. +.sp +If an option is referenced, the property will normally take/return exactly the +same values as the option. In these cases, properties are merely a way to change +an option at runtime. +.SS Property list +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Most options can be set as runtime via properties as well. Just remove the +leading \fB\-\-\fP from the option name. These are not documented. Only +properties which do not exist as option with the same name, or which have +very different behavior from the options are documented below. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fBaudio\-speed\-correction\fP, \fBvideo\-speed\-correction\fP +Factor multiplied with \fBspeed\fP at which the player attempts to play the +file. Usually it\(aqs exactly 1. (Display sync mode will make this useful.) +.sp +OSD formatting will display it in the form of \fB+1.23456%\fP, with the number +being \fB(raw \- 1) * 100\fP for the given raw property value. +.TP +.B \fBdisplay\-sync\-active\fP +Return whether \fB\-\-video\-sync=display\fP is actually active. +.TP +.B \fBfilename\fP +Currently played file, with path stripped. If this is an URL, try to undo +percent encoding as well. (The result is not necessarily correct, but +looks better for display purposes. Use the \fBpath\fP property to get an +unmodified filename.) +.sp +This has a sub\-property: +.INDENT 7.0 +.TP +.B \fBfilename/no\-ext\fP +Like the \fBfilename\fP property, but if the text contains a \fB\&.\fP, strip +all text after the last \fB\&.\fP\&. Usually this removes the file extension. +.UNINDENT +.TP +.B \fBfile\-size\fP +Length in bytes of the source file/stream. (This is the same as +\fB${stream\-end}\fP\&. For segmented/multi\-part files, this will return the +size of the main or manifest file, whatever it is.) +.TP +.B \fBestimated\-frame\-count\fP +Total number of frames in current file. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This is only an estimate. (It\(aqs computed from two unreliable +quantities: fps and stream length.) +.UNINDENT +.UNINDENT +.TP +.B \fBestimated\-frame\-number\fP +Number of current frame in current stream. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +This is only an estimate. (It\(aqs computed from two unreliable +quantities: fps and possibly rounded timestamps.) +.UNINDENT +.UNINDENT +.TP +.B \fBpath\fP +Full path of the currently played file. Usually this is exactly the same +string you pass on the mpv command line or the \fBloadfile\fP command, even +if it\(aqs a relative path. If you expect an absolute path, you will have to +determine it yourself, for example by using the \fBworking\-directory\fP +property. +.TP +.B \fBstream\-open\-filename\fP +The full path to the currently played media. This is different only from +\fBpath\fP in special cases. In particular, if \fB\-\-ytdl=yes\fP is used, and +the URL is detected by \fByoutube\-dl\fP, then the script will set this +property to the actual media URL. This property should be set only during +the \fBon_load\fP or \fBon_load_fail\fP hooks, otherwise it will have no effect +(or may do something implementation defined in the future). The property is +reset if playback of the current media ends. +.TP +.B \fBmedia\-title\fP +If the currently played file has a \fBtitle\fP tag, use that. +.sp +Otherwise, return the \fBfilename\fP property. +.TP +.B \fBfile\-format\fP +Symbolic name of the file format. In some cases, this is a comma\-separated +list of format names, e.g. mp4 is \fBmov,mp4,m4a,3gp,3g2,mj2\fP (the list +may grow in the future for any format). +.TP +.B \fBcurrent\-demuxer\fP +Name of the current demuxer. (This is useless.) +.sp +(Renamed from \fBdemuxer\fP\&.) +.TP +.B \fBstream\-path\fP +Filename (full path) of the stream layer filename. (This is probably +useless and is almost never different from \fBpath\fP\&.) +.TP +.B \fBstream\-pos\fP +Raw byte position in source stream. Technically, this returns the position +of the most recent packet passed to a decoder. +.TP +.B \fBstream\-end\fP +Raw end position in bytes in source stream. +.TP +.B \fBduration\fP +Duration of the current file in seconds. If the duration is unknown, the +property is unavailable. Note that the file duration is not always exactly +known, so this is an estimate. +.sp +This replaces the \fBlength\fP property, which was deprecated after the +mpv 0.9 release. (The semantics are the same.) +.TP +.B \fBavsync\fP +Last A/V synchronization difference. Unavailable if audio or video is +disabled. +.TP +.B \fBtotal\-avsync\-change\fP +Total A\-V sync correction done. Unavailable if audio or video is +disabled. +.TP +.B \fBdecoder\-frame\-drop\-count\fP +Video frames dropped by decoder, because video is too far behind audio (when +using \fB\-\-framedrop=decoder\fP). Sometimes, this may be incremented in other +situations, e.g. when video packets are damaged, or the decoder doesn\(aqt +follow the usual rules. Unavailable if video is disabled. +.sp +\fBdrop\-frame\-count\fP is a deprecated alias. +.TP +.B \fBframe\-drop\-count\fP +Frames dropped by VO (when using \fB\-\-framedrop=vo\fP). +.sp +\fBvo\-drop\-frame\-count\fP is a deprecated alias. +.TP +.B \fBmistimed\-frame\-count\fP +Number of video frames that were not timed correctly in display\-sync mode +for the sake of keeping A/V sync. This does not include external +circumstances, such as video rendering being too slow or the graphics +driver somehow skipping a vsync. It does not include rounding errors either +(which can happen especially with bad source timestamps). For example, +using the \fBdisplay\-desync\fP mode should never change this value from 0. +.TP +.B \fBvsync\-ratio\fP +For how many vsyncs a frame is displayed on average. This is available if +display\-sync is active only. For 30 FPS video on a 60 Hz screen, this will +be 2. This is the moving average of what actually has been scheduled, so +24 FPS on 60 Hz will never remain exactly on 2.5, but jitter depending on +the last frame displayed. +.TP +.B \fBvo\-delayed\-frame\-count\fP +Estimated number of frames delayed due to external circumstances in +display\-sync mode. Note that in general, mpv has to guess that this is +happening, and the guess can be inaccurate. +.TP +.B \fBpercent\-pos\fP (RW) +Position in current file (0\-100). The advantage over using this instead of +calculating it out of other properties is that it properly falls back to +estimating the playback position from the byte position, if the file +duration is not known. +.TP +.B \fBtime\-pos\fP (RW) +Position in current file in seconds. +.TP +.B \fBtime\-start\fP +Deprecated. Always returns 0. Before mpv 0.14, this used to return the start +time of the file (could affect e.g. transport streams). See +\fB\-\-rebase\-start\-time\fP option. +.TP +.B \fBtime\-remaining\fP +Remaining length of the file in seconds. Note that the file duration is not +always exactly known, so this is an estimate. +.TP +.B \fBaudio\-pts\fP (R) +Current audio playback position in current file in seconds. Unlike time\-pos, +this updates more often than once per frame. For audio\-only files, it is +mostly equivalent to time\-pos, while for video\-only files this property is +not available. +.TP +.B \fBplaytime\-remaining\fP +\fBtime\-remaining\fP scaled by the current \fBspeed\fP\&. +.TP +.B \fBplayback\-time\fP (RW) +Position in current file in seconds. Unlike \fBtime\-pos\fP, the time is +clamped to the range of the file. (Inaccurate file durations etc. could +make it go out of range. Useful on attempts to seek outside of the file, +as the seek target time is considered the current position during seeking.) +.TP +.B \fBchapter\fP (RW) +Current chapter number. The number of the first chapter is 0. +.TP +.B \fBedition\fP (RW) +Current MKV edition number. Setting this property to a different value will +restart playback. The number of the first edition is 0. +.TP +.B \fBchapters\fP +Number of chapters. +.TP +.B \fBeditions\fP +Number of MKV editions. +.TP +.B \fBedition\-list\fP +List of editions, current entry marked. Currently, the raw property value +is useless. +.sp +This has a number of sub\-properties. Replace \fBN\fP with the 0\-based edition +index. +.INDENT 7.0 +.TP +.B \fBedition\-list/count\fP +Number of editions. If there are no editions, this can be 0 or 1 (1 +if there\(aqs a useless dummy edition). +.TP +.B \fBedition\-list/N/id\fP +Edition ID as integer. Use this to set the \fBedition\fP property. +Currently, this is the same as the edition index. +.TP +.B \fBedition\-list/N/default\fP +\fByes\fP if this is the default edition, \fBno\fP otherwise. +.TP +.B \fBedition\-list/N/title\fP +Edition title as stored in the file. Not always available. +.UNINDENT +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each edition) + "id" MPV_FORMAT_INT64 + "title" MPV_FORMAT_STRING + "default" MPV_FORMAT_FLAG +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBmetadata\fP +Metadata key/value pairs. +.sp +If the property is accessed with Lua\(aqs \fBmp.get_property_native\fP, this +returns a table with metadata keys mapping to metadata values. If it is +accessed with the client API, this returns a \fBMPV_FORMAT_NODE_MAP\fP, +with tag keys mapping to tag values. +.sp +For OSD, it returns a formatted list. Trying to retrieve this property as +a raw string doesn\(aqt work. +.sp +This has a number of sub\-properties: +.INDENT 7.0 +.TP +.B \fBmetadata/by\-key/<key>\fP +Value of metadata entry \fB<key>\fP\&. +.TP +.B \fBmetadata/list/count\fP +Number of metadata entries. +.TP +.B \fBmetadata/list/N/key\fP +Key name of the Nth metadata entry. (The first entry is \fB0\fP). +.TP +.B \fBmetadata/list/N/value\fP +Value of the Nth metadata entry. +.TP +.B \fBmetadata/<key>\fP +Old version of \fBmetadata/by\-key/<key>\fP\&. Use is discouraged, because +the metadata key string could conflict with other sub\-properties. +.UNINDENT +.sp +The layout of this property might be subject to change. Suggestions are +welcome how exactly this property should work. +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_MAP + (key and string value for each metadata entry) +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBfiltered\-metadata\fP +Like \fBmetadata\fP, but includes only fields listed in the \fB\-\-display\-tags\fP +option. This is the same set of tags that is printed to the terminal. +.TP +.B \fBchapter\-metadata\fP +Metadata of current chapter. Works similar to \fBmetadata\fP property. It +also allows the same access methods (using sub\-properties). +.sp +Per\-chapter metadata is very rare. Usually, only the chapter name +(\fBtitle\fP) is set. +.sp +For accessing other information, like chapter start, see the +\fBchapter\-list\fP property. +.TP +.B \fBvf\-metadata/<filter\-label>\fP +Metadata added by video filters. Accessed by the filter label, +which, if not explicitly specified using the \fB@filter\-label:\fP syntax, +will be \fB<filter\-name>NN\fP\&. +.sp +Works similar to \fBmetadata\fP property. It allows the same access +methods (using sub\-properties). +.sp +An example of this kind of metadata are the cropping parameters +added by \fB\-\-vf=lavfi=cropdetect\fP\&. +.TP +.B \fBaf\-metadata/<filter\-label>\fP +Equivalent to \fBvf\-metadata/<filter\-label>\fP, but for audio filters. +.TP +.B \fBidle\-active\fP +Return \fByes\fP if no file is loaded, but the player is staying around +because of the \fB\-\-idle\fP option. +.sp +(Renamed from \fBidle\fP\&.) +.TP +.B \fBcore\-idle\fP +Return \fByes\fP if the playback core is paused, otherwise \fBno\fP\&. This can +be different \fBpause\fP in special situations, such as when the player +pauses itself due to low network cache. +.sp +This also returns \fByes\fP if playback is restarting or if nothing is +playing at all. In other words, it\(aqs only \fBno\fP if there\(aqs actually +video playing. (Behavior since mpv 0.7.0.) +.TP +.B \fBcache\-speed\fP (R) +Current I/O read speed between the cache and the lower layer (like network). +This gives the number bytes per seconds over a 1 second window (using +the type \fBMPV_FORMAT_INT64\fP for the client API). +.TP +.B \fBdemuxer\-cache\-duration\fP +Approximate duration of video buffered in the demuxer, in seconds. The +guess is very unreliable, and often the property will not be available +at all, even if data is buffered. +.TP +.B \fBdemuxer\-cache\-time\fP +Approximate time of video buffered in the demuxer, in seconds. Same as +\fBdemuxer\-cache\-duration\fP but returns the last timestamp of buffered +data in demuxer. +.TP +.B \fBdemuxer\-cache\-idle\fP +Returns \fByes\fP if the demuxer is idle, which means the demuxer cache is +filled to the requested amount, and is currently not reading more data. +.TP +.B \fBdemuxer\-cache\-state\fP +Various undocumented or half\-documented things. +.sp +Each entry in \fBseekable\-ranges\fP represents a region in the demuxer cache +that can be seeked to. If there are multiple demuxers active, this only +returns information about the "main" demuxer, but might be changed in +future to return unified information about all demuxers. The ranges are in +arbitrary order. Often, ranges will overlap for a bit, before being joined. +In broken corner cases, ranges may overlap all over the place. +.sp +The end of a seek range is usually smaller than the value returned by the +\fBdemuxer\-cache\-time\fP property, because that property returns the guessed +buffering amount, while the seek ranges represent the buffered data that +can actually be used for cached seeking. +.sp +\fBbof\-cached\fP indicates whether the seek range with the lowest timestamp +points to the beginning of the stream (BOF). This implies you cannot seek +before this position at all. \fBeof\-cached\fP indicates whether the seek range +with the highest timestamp points to the end of the stream (EOF). If both +\fBbof\-cached\fP and \fBeof\-cached\fP are set to \fByes\fP, and there\(aqs only 1 +cache range, the entire stream is cached. +.sp +\fBfw\-bytes\fP is the number of bytes of packets buffered in the range +starting from the current decoding position. This is a rough estimate +(may not account correctly for various overhead), and stops at the +demuxer position (it ignores seek ranges after it). +.sp +\fBfile\-cache\-bytes\fP is the number of bytes stored in the file cache. This +includes all overhead, and possibly unused data (like pruned data). This +member is missing if the file cache is not active. +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_MAP + "seekable\-ranges" MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP + "start" MPV_FORMAT_DOUBLE + "end" MPV_FORMAT_DOUBLE + "bof\-cached" MPV_FORMAT_FLAG + "eof\-cached" MPV_FORMAT_FLAG + "fw\-bytes" MPV_FORMAT_INT64 + "file\-cache\-bytes" MPV_FORMAT_INT64 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Other fields (might be changed or removed in the future): +.INDENT 7.0 +.TP +.B \fBeof\fP +True if the reader thread has hit the end of the file. +.TP +.B \fBunderrun\fP +True if the reader thread could not satisfy a decoder\(aqs request for a +new packet. +.TP +.B \fBidle\fP +True if the thread is currently not reading. +.TP +.B \fBtotal\-bytes\fP +Sum of packet bytes (plus some overhead estimation) of the entire packet +queue, including cached seekable ranges. +.UNINDENT +.TP +.B \fBdemuxer\-via\-network\fP +Returns \fByes\fP if the stream demuxed via the main demuxer is most likely +played via network. What constitutes "network" is not always clear, might +be used for other types of untrusted streams, could be wrong in certain +cases, and its definition might be changing. Also, external files (like +separate audio files or streams) do not influence the value of this +property (currently). +.TP +.B \fBdemuxer\-start\-time\fP (R) +Returns the start time reported by the demuxer in fractional seconds. +.TP +.B \fBpaused\-for\-cache\fP +Returns \fByes\fP when playback is paused because of waiting for the cache. +.TP +.B \fBcache\-buffering\-state\fP +Return the percentage (0\-100) of the cache fill status until the player +will unpause (related to \fBpaused\-for\-cache\fP). +.TP +.B \fBeof\-reached\fP +Returns \fByes\fP if end of playback was reached, \fBno\fP otherwise. Note +that this is usually interesting only if \fB\-\-keep\-open\fP is enabled, +since otherwise the player will immediately play the next file (or exit +or enter idle mode), and in these cases the \fBeof\-reached\fP property will +logically be cleared immediately after it\(aqs set. +.TP +.B \fBseeking\fP +Returns \fByes\fP if the player is currently seeking, or otherwise trying +to restart playback. (It\(aqs possible that it returns \fByes\fP while a file +is loaded. This is because the same underlying code is used for seeking and +resyncing.) +.TP +.B \fBmixer\-active\fP +Return \fByes\fP if the audio mixer is active, \fBno\fP otherwise. +.sp +This option is relatively useless. Before mpv 0.18.1, it could be used to +infer behavior of the \fBvolume\fP property. +.TP +.B \fBao\-volume\fP (RW) +System volume. This property is available only if mpv audio output is +currently active, and only if the underlying implementation supports volume +control. What this option does depends on the API. For example, on ALSA +this usually changes system\-wide audio, while with PulseAudio this controls +per\-application volume. +.TP +.B \fBao\-mute\fP (RW) +Similar to \fBao\-volume\fP, but controls the mute state. May be unimplemented +even if \fBao\-volume\fP works. +.TP +.B \fBaudio\-codec\fP +Audio codec selected for decoding. +.TP +.B \fBaudio\-codec\-name\fP +Audio codec. +.TP +.B \fBaudio\-params\fP +Audio format as output by the audio decoder. +This has a number of sub\-properties: +.INDENT 7.0 +.TP +.B \fBaudio\-params/format\fP +The sample format as string. This uses the same names as used in other +places of mpv. +.TP +.B \fBaudio\-params/samplerate\fP +Samplerate. +.TP +.B \fBaudio\-params/channels\fP +The channel layout as a string. This is similar to what the +\fB\-\-audio\-channels\fP accepts. +.TP +.B \fBaudio\-params/hr\-channels\fP +As \fBchannels\fP, but instead of the possibly cryptic actual layout +sent to the audio device, return a hopefully more human readable form. +(Usually only \fBaudio\-out\-params/hr\-channels\fP makes sense.) +.TP +.B \fBaudio\-params/channel\-count\fP +Number of audio channels. This is redundant to the \fBchannels\fP field +described above. +.UNINDENT +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_MAP + "format" MPV_FORMAT_STRING + "samplerate" MPV_FORMAT_INT64 + "channels" MPV_FORMAT_STRING + "channel\-count" MPV_FORMAT_INT64 + "hr\-channels" MPV_FORMAT_STRING +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBaudio\-out\-params\fP +Same as \fBaudio\-params\fP, but the format of the data written to the audio +API. +.TP +.B \fBcolormatrix\fP (R) +Redirects to \fBvideo\-params/colormatrix\fP\&. This parameter (as well as +similar ones) can be overridden with the \fBformat\fP video filter. +.TP +.B \fBcolormatrix\-input\-range\fP (R) +See \fBcolormatrix\fP\&. +.TP +.B \fBcolormatrix\-primaries\fP (R) +See \fBcolormatrix\fP\&. +.TP +.B \fBhwdec\fP (RW) +Reflects the \fB\-\-hwdec\fP option. +.sp +Writing to it may change the currently used hardware decoder, if possible. +(Internally, the player may reinitialize the decoder, and will perform a +seek to refresh the video properly.) You can watch the other hwdec +properties to see whether this was successful. +.sp +Unlike in mpv 0.9.x and before, this does not return the currently active +hardware decoder. Since mpv 0.18.0, \fBhwdec\-current\fP is available for +this purpose. +.TP +.B \fBhwdec\-current\fP +Return the current hardware decoding in use. If decoding is active, return +one of the values used by the \fBhwdec\fP option/property. \fBno\fP indicates +software decoding. If no decoder is loaded, the property is unavailable. +.TP +.B \fBhwdec\-interop\fP +This returns the currently loaded hardware decoding/output interop driver. +This is known only once the VO has opened (and possibly later). With some +VOs (like \fBgpu\fP), this might be never known in advance, but only when +the decoder attempted to create the hw decoder successfully. (Using +\fB\-\-gpu\-hwdec\-interop\fP can load it eagerly.) If there are multiple +drivers loaded, they will be separated by \fB,\fP\&. +.sp +If no VO is active or no interop driver is known, this property is +unavailable. +.sp +This does not necessarily use the same values as \fBhwdec\fP\&. There can be +multiple interop drivers for the same hardware decoder, depending on +platform and VO. +.TP +.B \fBvideo\-format\fP +Video format as string. +.TP +.B \fBvideo\-codec\fP +Video codec selected for decoding. +.TP +.B \fBwidth\fP, \fBheight\fP +Video size. This uses the size of the video as decoded, or if no video +frame has been decoded yet, the (possibly incorrect) container indicated +size. +.TP +.B \fBvideo\-params\fP +Video parameters, as output by the decoder (with overrides like aspect +etc. applied). This has a number of sub\-properties: +.INDENT 7.0 +.TP +.B \fBvideo\-params/pixelformat\fP +The pixel format as string. This uses the same names as used in other +places of mpv. +.TP +.B \fBvideo\-params/average\-bpp\fP +Average bits\-per\-pixel as integer. Subsampled planar formats use a +different resolution, which is the reason this value can sometimes be +odd or confusing. Can be unavailable with some formats. +.TP +.B \fBvideo\-params/plane\-depth\fP +Bit depth for each color component as integer. This is only exposed +for planar or single\-component formats, and is unavailable for other +formats. +.TP +.B \fBvideo\-params/w\fP, \fBvideo\-params/h\fP +Video size as integers, with no aspect correction applied. +.TP +.B \fBvideo\-params/dw\fP, \fBvideo\-params/dh\fP +Video size as integers, scaled for correct aspect ratio. +.TP +.B \fBvideo\-params/aspect\fP +Display aspect ratio as float. +.TP +.B \fBvideo\-params/par\fP +Pixel aspect ratio. +.TP +.B \fBvideo\-params/colormatrix\fP +The colormatrix in use as string. (Exact values subject to change.) +.TP +.B \fBvideo\-params/colorlevels\fP +The colorlevels as string. (Exact values subject to change.) +.TP +.B \fBvideo\-params/primaries\fP +The primaries in use as string. (Exact values subject to change.) +.TP +.B \fBvideo\-params/gamma\fP +The gamma function in use as string. (Exact values subject to change.) +.TP +.B \fBvideo\-params/sig\-peak\fP +The video file\(aqs tagged signal peak as float. +.TP +.B \fBvideo\-params/light\fP +The light type in use as a string. (Exact values subject to change.) +.TP +.B \fBvideo\-params/chroma\-location\fP +Chroma location as string. (Exact values subject to change.) +.TP +.B \fBvideo\-params/rotate\fP +Intended display rotation in degrees (clockwise). +.TP +.B \fBvideo\-params/stereo\-in\fP +Source file stereo 3D mode. (See the \fBformat\fP video filter\(aqs +\fBstereo\-in\fP option.) +.UNINDENT +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_MAP + "pixelformat" MPV_FORMAT_STRING + "w" MPV_FORMAT_INT64 + "h" MPV_FORMAT_INT64 + "dw" MPV_FORMAT_INT64 + "dh" MPV_FORMAT_INT64 + "aspect" MPV_FORMAT_DOUBLE + "par" MPV_FORMAT_DOUBLE + "colormatrix" MPV_FORMAT_STRING + "colorlevels" MPV_FORMAT_STRING + "primaries" MPV_FORMAT_STRING + "gamma" MPV_FORMAT_STRING + "sig\-peak" MPV_FORMAT_DOUBLE + "light" MPV_FORMAT_STRING + "chroma\-location" MPV_FORMAT_STRING + "rotate" MPV_FORMAT_INT64 + "stereo\-in" MPV_FORMAT_STRING +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBdwidth\fP, \fBdheight\fP +Video display size. This is the video size after filters and aspect scaling +have been applied. The actual video window size can still be different +from this, e.g. if the user resized the video window manually. +.sp +These have the same values as \fBvideo\-out\-params/dw\fP and +\fBvideo\-out\-params/dh\fP\&. +.TP +.B \fBvideo\-dec\-params\fP +Exactly like \fBvideo\-params\fP, but no overrides applied. +.TP +.B \fBvideo\-out\-params\fP +Same as \fBvideo\-params\fP, but after video filters have been applied. If +there are no video filters in use, this will contain the same values as +\fBvideo\-params\fP\&. Note that this is still not necessarily what the video +window uses, since the user can change the window size, and all real VOs +do their own scaling independently from the filter chain. +.sp +Has the same sub\-properties as \fBvideo\-params\fP\&. +.TP +.B \fBvideo\-frame\-info\fP +Approximate information of the current frame. Note that if any of these +are used on OSD, the information might be off by a few frames due to OSD +redrawing and frame display being somewhat disconnected, and you might +have to pause and force a redraw. +.sp +Sub\-properties: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +video\-frame\-info/picture\-type +video\-frame\-info/interlaced +video\-frame\-info/tff +video\-frame\-info/repeat +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBcontainer\-fps\fP +Container FPS. This can easily contain bogus values. For videos that use +modern container formats or video codecs, this will often be incorrect. +.sp +(Renamed from \fBfps\fP\&.) +.TP +.B \fBestimated\-vf\-fps\fP +Estimated/measured FPS of the video filter chain output. (If no filters +are used, this corresponds to decoder output.) This uses the average of +the 10 past frame durations to calculate the FPS. It will be inaccurate +if frame\-dropping is involved (such as when framedrop is explicitly +enabled, or after precise seeking). Files with imprecise timestamps (such +as Matroska) might lead to unstable results. +.TP +.B \fBwindow\-scale\fP (RW) +Window size multiplier. Setting this will resize the video window to the +values contained in \fBdwidth\fP and \fBdheight\fP multiplied with the value +set with this property. Setting \fB1\fP will resize to original video size +(or to be exact, the size the video filters output). \fB2\fP will set the +double size, \fB0.5\fP halves the size. +.TP +.B \fBwindow\-minimized\fP +Return whether the video window is minimized or not. +.TP +.B \fBdisplay\-names\fP +Names of the displays that the mpv window covers. On X11, these +are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these +are the GDI names (\e.DISPLAY1, \e.DISPLAY2, etc.) and the first display +in the list will be the one that Windows considers associated with the +window (as determined by the MonitorFromWindow API.) On macOS these are the +Display Product Names as used in the System Information and only one display +name is returned since a window can only be on one screen. +.TP +.B \fBdisplay\-fps\fP (RW) +The refresh rate of the current display. Currently, this is the lowest FPS +of any display covered by the video, as retrieved by the underlying system +APIs (e.g. xrandr on X11). It is not the measured FPS. It\(aqs not necessarily +available on all platforms. Note that any of the listed facts may change +any time without a warning. +.TP +.B \fBestimated\-display\-fps\fP +Only available if display\-sync mode (as selected by \fB\-\-video\-sync\fP) is +active. Returns the actual rate at which display refreshes seem to occur, +measured by system time. +.TP +.B \fBvsync\-jitter\fP +Estimated deviation factor of the vsync duration. +.TP +.B \fBvideo\-aspect\fP (RW) +Deprecated. This is tied to \fB\-\-video\-aspect\-override\fP, but always +reports the current video aspect if video is active. +.sp +The read and write components of this option can be split up into +\fBvideo\-params/aspect\fP and \fBvideo\-aspect\-override\fP respectively. +.TP +.B \fBosd\-width\fP, \fBosd\-height\fP +Last known OSD width (can be 0). This is needed if you want to use the +\fBoverlay\-add\fP command. It gives you the actual OSD size, which can be +different from the window size in some cases. +.TP +.B \fBosd\-par\fP +Last known OSD display pixel aspect (can be 0). +.TP +.B \fBsub\-text\fP +Return the current subtitle text regardless of sub visibility. +Formatting is stripped. If the subtitle is not text\-based +(i.e. DVD/BD subtitles), an empty string is returned. +.sp +This property is experimental and might be removed in the future. +.TP +.B \fBsub\-start\fP +Return the current subtitle start time (in seconds). If there\(aqs multiple +current subtitles, returns the first start time. If no current subtitle is +present null is returned instead. +.TP +.B \fBsub\-end\fP +Return the current subtitle start time (in seconds). If there\(aqs multiple +current subtitles, return the last end time. If no current subtitle is +present, or if it\(aqs present but has unknown or incorrect duration, null +is returned instead. +.TP +.B \fBplaylist\-pos\fP (RW) +Current position on playlist. The first entry is on position 0. Writing +to the property will restart playback at the written entry. +.TP +.B \fBplaylist\-pos\-1\fP (RW) +Same as \fBplaylist\-pos\fP, but 1\-based. +.TP +.B \fBplaylist\-count\fP +Number of total playlist entries. +.TP +.B \fBplaylist\fP +Playlist, current entry marked. Currently, the raw property value is +useless. +.sp +This has a number of sub\-properties. Replace \fBN\fP with the 0\-based playlist +entry index. +.INDENT 7.0 +.TP +.B \fBplaylist/count\fP +Number of playlist entries (same as \fBplaylist\-count\fP). +.TP +.B \fBplaylist/N/filename\fP +Filename of the Nth entry. +.TP +.B \fBplaylist/N/current\fP, \fBplaylist/N/playing\fP +\fByes\fP if this entry is currently playing (or being loaded). +Unavailable or \fBno\fP otherwise. When changing files, \fBcurrent\fP and +\fBplaying\fP can be different, because the currently playing file hasn\(aqt +been unloaded yet; in this case, \fBcurrent\fP refers to the new +selection. (Since mpv 0.7.0.) +.TP +.B \fBplaylist/N/title\fP +Name of the Nth entry. Only available if the playlist file contains +such fields, and only if mpv\(aqs parser supports it for the given +playlist format. +.UNINDENT +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each playlist entry) + "filename" MPV_FORMAT_STRING + "current" MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0) + "playing" MPV_FORMAT_FLAG (same) + "title" MPV_FORMAT_STRING (optional) +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBtrack\-list\fP +List of audio/video/sub tracks, current entry marked. Currently, the raw +property value is useless. +.sp +This has a number of sub\-properties. Replace \fBN\fP with the 0\-based track +index. +.INDENT 7.0 +.TP +.B \fBtrack\-list/count\fP +Total number of tracks. +.TP +.B \fBtrack\-list/N/id\fP +The ID as it\(aqs used for \fB\-sid\fP/\fB\-\-aid\fP/\fB\-\-vid\fP\&. This is unique +within tracks of the same type (sub/audio/video), but otherwise not. +.TP +.B \fBtrack\-list/N/type\fP +String describing the media type. One of \fBaudio\fP, \fBvideo\fP, \fBsub\fP\&. +.TP +.B \fBtrack\-list/N/src\-id\fP +Track ID as used in the source file. Not always available. +.TP +.B \fBtrack\-list/N/title\fP +Track title as it is stored in the file. Not always available. +.TP +.B \fBtrack\-list/N/lang\fP +Track language as identified by the file. Not always available. +.TP +.B \fBtrack\-list/N/albumart\fP +\fByes\fP if this is a video track that consists of a single picture, +\fBno\fP or unavailable otherwise. This is used for video tracks that are +really attached pictures in audio files. +.TP +.B \fBtrack\-list/N/default\fP +\fByes\fP if the track has the default flag set in the file, \fBno\fP +otherwise. +.TP +.B \fBtrack\-list/N/forced\fP +\fByes\fP if the track has the forced flag set in the file, \fBno\fP +otherwise. +.TP +.B \fBtrack\-list/N/codec\fP +The codec name used by this track, for example \fBh264\fP\&. Unavailable +in some rare cases. +.TP +.B \fBtrack\-list/N/external\fP +\fByes\fP if the track is an external file, \fBno\fP otherwise. This is +set for separate subtitle files. +.TP +.B \fBtrack\-list/N/external\-filename\fP +The filename if the track is from an external file, unavailable +otherwise. +.TP +.B \fBtrack\-list/N/selected\fP +\fByes\fP if the track is currently decoded, \fBno\fP otherwise. +.TP +.B \fBtrack\-list/N/ff\-index\fP +The stream index as usually used by the FFmpeg utilities. Note that +this can be potentially wrong if a demuxer other than libavformat +(\fB\-\-demuxer=lavf\fP) is used. For mkv files, the index will usually +match even if the default (builtin) demuxer is used, but there is +no hard guarantee. +.TP +.B \fBtrack\-list/N/decoder\-desc\fP +If this track is being decoded, the human\-readable decoder name, +.TP +.B \fBtrack\-list/N/demux\-w\fP, \fBtrack\-list/N/demux\-h\fP +Video size hint as indicated by the container. (Not always accurate.) +.TP +.B \fBtrack\-list/N/demux\-channel\-count\fP +Number of audio channels as indicated by the container. (Not always +accurate \- in particular, the track could be decoded as a different +number of channels.) +.TP +.B \fBtrack\-list/N/demux\-channels\fP +Channel layout as indicated by the container. (Not always accurate.) +.TP +.B \fBtrack\-list/N/demux\-samplerate\fP +Audio sample rate as indicated by the container. (Not always accurate.) +.TP +.B \fBtrack\-list/N/demux\-fps\fP +Video FPS as indicated by the container. (Not always accurate.) +.TP +.B \fBtrack\-list/N/demux\-bitrate\fP +Audio average bitrate, in bits per second. (Not always accurate.) +.TP +.B \fBtrack\-list/N/demux\-rotation\fP +Video clockwise rotation metadata, in degrees. +.TP +.B \fBtrack\-list/N/demux\-par\fP +Pixel aspect ratio. +.TP +.B \fBtrack\-list/N/audio\-channels\fP (deprecated) +Deprecated alias for \fBtrack\-list/N/demux\-channel\-count\fP\&. +.TP +.B \fBtrack\-list/N/replaygain\-track\-peak\fP, \fBtrack\-list/N/replaygain\-track\-gain\fP +Per\-track replaygain values. Only available for audio tracks with +corresponding information stored in the source file. +.TP +.B \fBtrack\-list/N/replaygain\-album\-peak\fP, \fBtrack\-list/N/replaygain\-album\-gain\fP +Per\-album replaygain values. If the file has per\-track but no per\-album +information, the per\-album values will be copied from the per\-track +values currently. It\(aqs possible that future mpv versions will make +these properties unavailable instead in this case. +.UNINDENT +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each track) + "id" MPV_FORMAT_INT64 + "type" MPV_FORMAT_STRING + "src\-id" MPV_FORMAT_INT64 + "title" MPV_FORMAT_STRING + "lang" MPV_FORMAT_STRING + "albumart" MPV_FORMAT_FLAG + "default" MPV_FORMAT_FLAG + "forced" MPV_FORMAT_FLAG + "selected" MPV_FORMAT_FLAG + "external" MPV_FORMAT_FLAG + "external\-filename" MPV_FORMAT_STRING + "codec" MPV_FORMAT_STRING + "ff\-index" MPV_FORMAT_INT64 + "decoder\-desc" MPV_FORMAT_STRING + "demux\-w" MPV_FORMAT_INT64 + "demux\-h" MPV_FORMAT_INT64 + "demux\-channel\-count" MPV_FORMAT_INT64 + "demux\-channels" MPV_FORMAT_STRING + "demux\-samplerate" MPV_FORMAT_INT64 + "demux\-fps" MPV_FORMAT_DOUBLE + "demux\-bitrate" MPV_FORMAT_INT64 + "demux\-rotation" MPV_FORMAT_INT64 + "demux\-par" MPV_FORMAT_DOUBLE + "audio\-channels" MPV_FORMAT_INT64 + "replaygain\-track\-peak" MPV_FORMAT_DOUBLE + "replaygain\-track\-gain" MPV_FORMAT_DOUBLE + "replaygain\-album\-peak" MPV_FORMAT_DOUBLE + "replaygain\-album\-gain" MPV_FORMAT_DOUBLE +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBchapter\-list\fP +List of chapters, current entry marked. Currently, the raw property value +is useless. +.sp +This has a number of sub\-properties. Replace \fBN\fP with the 0\-based chapter +index. +.INDENT 7.0 +.TP +.B \fBchapter\-list/count\fP +Number of chapters. +.TP +.B \fBchapter\-list/N/title\fP +Chapter title as stored in the file. Not always available. +.TP +.B \fBchapter\-list/N/time\fP +Chapter start time in seconds as float. +.UNINDENT +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each chapter) + "title" MPV_FORMAT_STRING + "time" MPV_FORMAT_DOUBLE +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBaf\fP, \fBvf\fP (RW) +See \fB\-\-vf\fP/\fB\-\-af\fP and the \fBvf\fP/\fBaf\fP command. +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each filter entry) + "name" MPV_FORMAT_STRING + "label" MPV_FORMAT_STRING [optional] + "enabled" MPV_FORMAT_FLAG [optional] + "params" MPV_FORMAT_NODE_MAP [optional] + "key" MPV_FORMAT_STRING + "value" MPV_FORMAT_STRING +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +It\(aqs also possible to write the property using this format. +.TP +.B \fBseekable\fP +Return whether it\(aqs generally possible to seek in the current file. +.TP +.B \fBpartially\-seekable\fP +Return \fByes\fP if the current file is considered seekable, but only because +the cache is active. This means small relative seeks may be fine, but larger +seeks may fail anyway. Whether a seek will succeed or not is generally not +known in advance. +.sp +If this property returns true, \fBseekable\fP will also return true. +.TP +.B \fBplayback\-abort\fP +Return whether playback is stopped or is to be stopped. (Useful in obscure +situations like during \fBon_load\fP hook processing, when the user can +stop playback, but the script has to explicitly end processing.) +.TP +.B \fBcursor\-autohide\fP (RW) +See \fB\-\-cursor\-autohide\fP\&. Setting this to a new value will always update +the cursor, and reset the internal timer. +.TP +.B \fBosd\-sym\-cc\fP +Inserts the current OSD symbol as opaque OSD control code (cc). This makes +sense only with the \fBshow\-text\fP command or options which set OSD messages. +The control code is implementation specific and is useless for anything else. +.TP +.B \fBosd\-ass\-cc\fP +\fB${osd\-ass\-cc/0}\fP disables escaping ASS sequences of text in OSD, +\fB${osd\-ass\-cc/1}\fP enables it again. By default, ASS sequences are +escaped to avoid accidental formatting, and this property can disable +this behavior. Note that the properties return an opaque OSD control +code, which only makes sense for the \fBshow\-text\fP command or options +which set OSD messages. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-osd\-status\-msg=\(aqThis is ${osd\-ass\-cc/0}{\e\eb1}bold text\(aq\fP +.IP \(bu 2 +\fBshow\-text "This is ${osd\-ass\-cc/0}{\eb1}bold text"\fP +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Any ASS override tags as understood by libass can be used. +.sp +Note that you need to escape the \fB\e\fP character, because the string is +processed for C escape sequences before passing it to the OSD code. +.sp +A list of tags can be found here: \fI\%http://docs.aegisub.org/latest/ASS_Tags/\fP +.TP +.B \fBvo\-configured\fP +Return whether the VO is configured right now. Usually this corresponds to +whether the video window is visible. If the \fB\-\-force\-window\fP option is +used, this is usually always returns \fByes\fP\&. +.TP +.B \fBvo\-passes\fP +Contains introspection about the VO\(aqs active render passes and their +execution times. Not implemented by all VOs. +.sp +This is further subdivided into two frame types, \fBvo\-passes/fresh\fP for +fresh frames (which have to be uploaded, scaled, etc.) and +\fBvo\-passes/redraw\fP for redrawn frames (which only have to be re\-painted). +The number of passes for any given subtype can change from frame to frame, +and should not be relied upon. +.sp +Each frame type has a number of further sub\-properties. Replace \fBTYPE\fP +with the frame type, \fBN\fP with the 0\-based pass index, and \fBM\fP with the +0\-based sample index. +.INDENT 7.0 +.TP +.B \fBvo\-passes/TYPE/count\fP +Number of passes. +.TP +.B \fBvo\-passes/TYPE/N/desc\fP +Human\-friendy description of the pass. +.TP +.B \fBvo\-passes/TYPE/N/last\fP +Last measured execution time, in nanoseconds. +.TP +.B \fBvo\-passes/TYPE/N/avg\fP +Average execution time of this pass, in nanoseconds. The exact +timeframe varies, but it should generally be a handful of seconds. +.TP +.B \fBvo\-passes/TYPE/N/peak\fP +The peak execution time (highest value) within this averaging range, in +nanoseconds. +.TP +.B \fBvo\-passes/TYPE/N/count\fP +The number of samples for this pass. +.TP +.B \fBvo\-passes/TYPE/N/samples/M\fP +The raw execution time of a specific sample for this pass, in +nanoseconds. +.UNINDENT +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_MAP +"TYPE" MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP + "desc" MPV_FORMAT_STRING + "last" MPV_FORMAT_INT64 + "avg" MPV_FORMAT_INT64 + "peak" MPV_FORMAT_INT64 + "count" MPV_FORMAT_INT64 + "samples" MPV_FORMAT_NODE_ARRAY + MP_FORMAT_INT64 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Note that directly accessing this structure via subkeys is not supported, +the only access is through aforementioned \fBMPV_FORMAT_NODE\fP\&. +.TP +.B \fBvideo\-bitrate\fP, \fBaudio\-bitrate\fP, \fBsub\-bitrate\fP +Bitrate values calculated on the packet level. This works by dividing the +bit size of all packets between two keyframes by their presentation +timestamp distance. (This uses the timestamps are stored in the file, so +e.g. playback speed does not influence the returned values.) In particular, +the video bitrate will update only per keyframe, and show the "past" +bitrate. To make the property more UI friendly, updates to these properties +are throttled in a certain way. +.sp +The unit is bits per second. OSD formatting turns these values in kilobits +(or megabits, if appropriate), which can be prevented by using the +raw property value, e.g. with \fB${=video\-bitrate}\fP\&. +.sp +Note that the accuracy of these properties is influenced by a few factors. +If the underlying demuxer rewrites the packets on demuxing (done for some +file formats), the bitrate might be slightly off. If timestamps are bad +or jittery (like in Matroska), even constant bitrate streams might show +fluctuating bitrate. +.sp +How exactly these values are calculated might change in the future. +.sp +In earlier versions of mpv, these properties returned a static (but bad) +guess using a completely different method. +.TP +.B \fBpacket\-video\-bitrate\fP, \fBpacket\-audio\-bitrate\fP, \fBpacket\-sub\-bitrate\fP +Old and deprecated properties for \fBvideo\-bitrate\fP, \fBaudio\-bitrate\fP, +\fBsub\-bitrate\fP\&. They behave exactly the same, but return a value in +kilobits. Also, they don\(aqt have any OSD formatting, though the same can be +achieved with e.g. \fB${=video\-bitrate}\fP\&. +.sp +These properties shouldn\(aqt be used anymore. +.TP +.B \fBaudio\-device\-list\fP +Return the list of discovered audio devices. This is mostly for use with +the client API, and reflects what \fB\-\-audio\-device=help\fP with the command +line player returns. +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each device entry) + "name" MPV_FORMAT_STRING + "description" MPV_FORMAT_STRING +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBname\fP is what is to be passed to the \fB\-\-audio\-device\fP option (and +often a rather cryptic audio API\-specific ID), while \fBdescription\fP is +human readable free form text. The description is set to the device name +(minus mpv\-specific \fB<driver>/\fP prefix) if no description is available +or the description would have been an empty string. +.sp +The special entry with the name set to \fBauto\fP selects the default audio +output driver and the default device. +.sp +The property can be watched with the property observation mechanism in +the client API and in Lua scripts. (Technically, change notification is +enabled the first time this property is read.) +.TP +.B \fBaudio\-device\fP (RW) +Set the audio device. This directly reads/writes the \fB\-\-audio\-device\fP +option, but on write accesses, the audio output will be scheduled for +reloading. +.sp +Writing this property while no audio output is active will not automatically +enable audio. (This is also true in the case when audio was disabled due to +reinitialization failure after a previous write access to \fBaudio\-device\fP\&.) +.sp +This property also doesn\(aqt tell you which audio device is actually in use. +.sp +How these details are handled may change in the future. +.TP +.B \fBcurrent\-vo\fP +Current video output driver (name as used with \fB\-\-vo\fP). +.TP +.B \fBcurrent\-ao\fP +Current audio output driver (name as used with \fB\-\-ao\fP). +.TP +.B \fBworking\-directory\fP +Return the working directory of the mpv process. Can be useful for JSON IPC +users, because the command line player usually works with relative paths. +.TP +.B \fBprotocol\-list\fP +List of protocol prefixes potentially recognized by the player. They are +returned without trailing \fB://\fP suffix (which is still always required). +In some cases, the protocol will not actually be supported (consider +\fBhttps\fP if ffmpeg is not compiled with TLS support). +.TP +.B \fBdecoder\-list\fP +List of decoders supported. This lists decoders which can be passed to +\fB\-\-vd\fP and \fB\-\-ad\fP\&. +.INDENT 7.0 +.TP +.B \fBcodec\fP +Canonical codec name, which identifies the format the decoder can +handle. +.TP +.B \fBdriver\fP +The name of the decoder itself. Often, this is the same as \fBcodec\fP\&. +Sometimes it can be different. It is used to distinguish multiple +decoders for the same codec. +.TP +.B \fBdescription\fP +Human readable description of the decoder and codec. +.UNINDENT +.sp +When querying the property with the client API using \fBMPV_FORMAT_NODE\fP, +or with Lua \fBmp.get_property_native\fP, this will return a mpv_node with +the following contents: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (for each decoder entry) + "codec" MPV_FORMAT_STRING + "driver" MPV_FORMAT_STRING + "description" MPV_FORMAT_STRING +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBencoder\-list\fP +List of libavcodec encoders. This has the same format as \fBdecoder\-list\fP\&. +The encoder names (\fBdriver\fP entries) can be passed to \fB\-\-ovc\fP and +\fB\-\-oac\fP (without the \fBlavc:\fP prefix required by \fB\-\-vd\fP and \fB\-\-ad\fP). +.TP +.B \fBdemuxer\-lavf\-list\fP +List of available libavformat demuxers\(aq names. This can be used to check +for support for a specific format or use with \fB\-\-demuxer\-lavf\-format\fP\&. +.TP +.B \fBmpv\-version\fP +Return the mpv version/copyright string. Depending on how the binary was +built, it might contain either a release version, or just a git hash. +.TP +.B \fBmpv\-configuration\fP +Return the configuration arguments which were passed to the build system +(typically the way \fB\&./waf configure ...\fP was invoked). +.TP +.B \fBffmpeg\-version\fP +Return the contents of the \fBav_version_info()\fP API call. This is a string +which identifies the build in some way, either through a release version +number, or a git hash. This applies to Libav as well (the property is +still named the same.) This property is unavailable if mpv is linked against +older FFmpeg and Libav versions. +.TP +.B \fBoptions/<name>\fP (RW) +Read\-only access to value of option \fB\-\-<name>\fP\&. Most options can be +changed at runtime by writing to this property. Note that many options +require reloading the file for changes to take effect. If there is an +equivalent property, prefer setting the property instead. +.sp +There shouldn\(aqt be any reason to access \fBoptions/<name>\fP instead of +\fB<name>\fP, except in situations in which the properties have different +behavior or conflicting semantics. +.TP +.B \fBfile\-local\-options/<name>\fP +Similar to \fBoptions/<name>\fP, but when setting an option through this +property, the option is reset to its old value once the current file has +stopped playing. Trying to write an option while no file is playing (or +is being loaded) results in an error. +.sp +(Note that if an option is marked as file\-local, even \fBoptions/\fP will +access the local value, and the \fBold\fP value, which will be restored on +end of playback, cannot be read or written until end of playback.) +.TP +.B \fBoption\-info/<name>\fP +Additional per\-option information. +.sp +This has a number of sub\-properties. Replace \fB<name>\fP with the name of +a top\-level option. No guarantee of stability is given to any of these +sub\-properties \- they may change radically in the feature. +.INDENT 7.0 +.TP +.B \fBoption\-info/<name>/name\fP +Returns the name of the option. +.TP +.B \fBoption\-info/<name>/type\fP +Return the name of the option type, like \fBString\fP or \fBInteger\fP\&. +For many complex types, this isn\(aqt very accurate. +.TP +.B \fBoption\-info/<name>/set\-from\-commandline\fP +Return \fByes\fP if the option was set from the mpv command line, +\fBno\fP otherwise. What this is set to if the option is e.g. changed +at runtime is left undefined (meaning it could change in the future). +.TP +.B \fBoption\-info/<name>/set\-locally\fP +Return \fByes\fP if the option was set per\-file. This is the case with +automatically loaded profiles, file\-dir configs, and other cases. It +means the option value will be restored to the value before playback +start when playback ends. +.TP +.B \fBoption\-info/<name>/default\-value\fP +The default value of the option. May not always be available. +.TP +.B \fBoption\-info/<name>/min\fP, \fBoption\-info/<name>/max\fP +Integer minimum and maximum values allowed for the option. Only +available if the options are numeric, and the minimum/maximum has been +set internally. It\(aqs also possible that only one of these is set. +.TP +.B \fBoption\-info/<name>/choices\fP +If the option is a choice option, the possible choices. Choices that +are integers may or may not be included (they can be implied by \fBmin\fP +and \fBmax\fP). Note that options which behave like choice options, but +are not actual choice options internally, may not have this info +available. +.UNINDENT +.TP +.B \fBproperty\-list\fP +Return the list of top\-level properties. +.TP +.B \fBprofile\-list\fP +Return the list of profiles and their contents. This is highly +implementation\-specific, and may change any time. Currently, it returns +an array of options for each profile. Each option has a name and a value, +with the value currently always being a string. Note that the options array +is not a map, as order matters and duplicate entries are possible. Recursive +profiles are not expanded, and show up as special \fBprofile\fP options. +.UNINDENT +.SS Inconsistencies between options and properties +.sp +You can access (almost) all options as properties, though there are some +caveats with some properties (due to historical reasons): +.INDENT 0.0 +.TP +.B \fBvid\fP, \fBaid\fP, \fBsid\fP +While playback is active, you can set existing tracks only. (The option +allows setting any track ID, and which tracks to enable is chosen at +loading time.) +.sp +Option changes at runtime are affected by this as well. +.TP +.B \fBdisplay\-fps\fP +If a VO is created, this will return either the actual display FPS, or +an invalid value, instead of the option value. +.TP +.B \fBvf\fP, \fBaf\fP +If you set the properties during playback, and the filter chain fails to +reinitialize, the new value will be rejected. Setting the option or +setting the property outside of playback will always succeed/fail in the +same way. Also, there are no \fBvf\-add\fP etc. properties, but you can use +the \fBvf\fP/\fBaf\fP group of commands to achieve the same. +.sp +Option changes at runtime are affected by this as well. +.TP +.B \fBedition\fP +While a file is loaded, the property will always return the effective +edition, and setting the \fBauto\fP value will show somewhat strange behavior +(the property eventually switching to whatever is the default edition). +.TP +.B \fBplaylist\fP +The property is read\-only and returns the current internal playlist. The +option is for loading playlist during command line parsing. For client API +uses, you should use the \fBloadlist\fP command instead. +.TP +.B \fBwindow\-scale\fP +Might verify the set value when setting while a window is created. +.TP +.B \fBaudio\-file\fP, \fBsub\-file\fP, \fBexternal\-file\fP +These options/properties are actually lists of filenames. To make the +command\-line interface easier, each \fB\-\-audio\-file=...\fP option appends +the full string to the internal list. However, when used as properties, +every time you set the property as a string the internal list will be +replaced with a single entry containing the string you set. \fB,\fP or other +separators are never used. You have to use \fBMPV_FORMAT_NODE_ARRAY\fP (or +corresponding API, e.g. \fBmp.set_property_native()\fP with a table in Lua) +to set multiple entries. +.sp +Strictly speaking, option access via API (e.g. \fBmpv_set_option_string()\fP) +has the same problem, and it\(aqs only a difference between CLI/API. +.TP +.B \fBplaylist\-pos\fP, \fBchapter\fP +These properties behave different from the deprecated options with the same +names. +.TP +.B \fBprofile\fP, \fBinclude\fP +These are write\-only, and will perform actions as they are written to, +exactly as if they were used on the mpv CLI commandline. Their only use is +when using libmpv before \fBmpv_initialize()\fP, which in turn is probably +only useful in encoding mode. Normal libmpv users should use other +mechanisms, such as the \fBapply\-profile\fP command, and the +\fBmpv_load_config_file\fP API function. Avoid these properties. +.UNINDENT +.SS Property Expansion +.sp +All string arguments to input commands as well as certain options (like +\fB\-\-term\-playing\-msg\fP) are subject to property expansion. Note that property +expansion does not work in places where e.g. numeric parameters are expected. +(For example, the \fBadd\fP command does not do property expansion. The \fBset\fP +command is an exception and not a general rule.) +.INDENT 0.0 +.INDENT 3.5 +.IP "Example for input.conf" +.INDENT 0.0 +.TP +.B \fBi show\-text "Filename: ${filename}"\fP +shows the filename of the current file when pressing the \fBi\fP key +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Within \fBinput.conf\fP, property expansion can be inhibited by putting the +\fBraw\fP prefix in front of commands. +.sp +The following expansions are supported: +.INDENT 0.0 +.TP +.B \fB${NAME}\fP +Expands to the value of the property \fBNAME\fP\&. If retrieving the property +fails, expand to an error string. (Use \fB${NAME:}\fP with a trailing +\fB:\fP to expand to an empty string instead.) +If \fBNAME\fP is prefixed with \fB=\fP, expand to the raw value of the property +(see section below). +.TP +.B \fB${NAME:STR}\fP +Expands to the value of the property \fBNAME\fP, or \fBSTR\fP if the +property cannot be retrieved. \fBSTR\fP is expanded recursively. +.TP +.B \fB${?NAME:STR}\fP +Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP is available. +.TP +.B \fB${!NAME:STR}\fP +Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP cannot be +retrieved. +.TP +.B \fB${?NAME==VALUE:STR}\fP +Expands to \fBSTR\fP (recursively) if the property \fBNAME\fP expands to a +string equal to \fBVALUE\fP\&. You can prefix \fBNAME\fP with \fB=\fP in order to +compare the raw value of a property (see section below). If the property +is unavailable, or other errors happen when retrieving it, the value is +never considered equal. +Note that \fBVALUE\fP can\(aqt contain any of the characters \fB:\fP or \fB}\fP\&. +Also, it is possible that escaping with \fB"\fP or \fB%\fP might be added in +the future, should the need arise. +.TP +.B \fB${!NAME==VALUE:STR}\fP +Same as with the \fB?\fP variant, but \fBSTR\fP is expanded if the value is +not equal. (Using the same semantics as with \fB?\fP\&.) +.TP +.B \fB$$\fP +Expands to \fB$\fP\&. +.TP +.B \fB$}\fP +Expands to \fB}\fP\&. (To produce this character inside recursive +expansion.) +.TP +.B \fB$>\fP +Disable property expansion and special handling of \fB$\fP for the rest +of the string. +.UNINDENT +.sp +In places where property expansion is allowed, C\-style escapes are often +accepted as well. Example: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +\fB\en\fP becomes a newline character +.IP \(bu 2 +\fB\e\e\fP expands to \fB\e\fP +.UNINDENT +.UNINDENT +.UNINDENT +.SS Raw and Formatted Properties +.sp +Normally, properties are formatted as human\-readable text, meant to be +displayed on OSD or on the terminal. It is possible to retrieve an unformatted +(raw) value from a property by prefixing its name with \fB=\fP\&. These raw values +can be parsed by other programs and follow the same conventions as the options +associated with the properties. +.INDENT 0.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fB${time\-pos}\fP expands to \fB00:14:23\fP (if playback position is at 14 +minutes 23 seconds) +.IP \(bu 2 +\fB${=time\-pos}\fP expands to \fB863.4\fP (same time, plus 400 milliseconds \- +milliseconds are normally not shown in the formatted case) +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Sometimes, the difference in amount of information carried by raw and formatted +property values can be rather big. In some cases, raw values have more +information, like higher precision than seconds with \fBtime\-pos\fP\&. Sometimes +it is the other way around, e.g. \fBaid\fP shows track title and language in the +formatted case, but only the track number if it is raw. +.SH ON SCREEN CONTROLLER +.sp +The On Screen Controller (short: OSC) is a minimal GUI integrated with mpv to +offer basic mouse\-controllability. It is intended to make interaction easier +for new users and to enable precise and direct seeking. +.sp +The OSC is enabled by default if mpv was compiled with Lua support. It can be +disabled entirely using the \fB\-\-osc=no\fP option. +.SS Using the OSC +.sp +By default, the OSC will show up whenever the mouse is moved inside the +player window and will hide if the mouse is not moved outside the OSC for +0.5 seconds or if the mouse leaves the window. +.SS The Interface +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C ++\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+ +| pl prev | pl next | title | cache | ++\-\-\-\-\-\-+\-\-+\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-+ +| play | skip | skip | time | seekbar | time | audio | sub | vol | fs | +| | back | frwd | elapsed | | left | | | | | ++\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-+ +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B pl prev +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +play previous file in playlist +T} +_ +T{ +right\-click +T} T{ +show playlist +T} +_ +T{ +shift+L\-click +T} T{ +show playlist +T} +_ +.TE +.TP +.B pl next +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +play next file in playlist +T} +_ +T{ +right\-click +T} T{ +show playlist +T} +_ +T{ +shift+L\-click +T} T{ +show playlist +T} +_ +.TE +.TP +.B title +.nf +Displays current media\-title, filename, or custom title +.fi +.sp +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +show playlist position and length and full title +T} +_ +T{ +right\-click +T} T{ +show filename +T} +_ +.TE +.TP +.B cache +.nf +Shows current cache fill status +.fi +.sp +.TP +.B play +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +toggle play/pause +T} +_ +.TE +.TP +.B skip back +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +go to beginning of chapter / previous chapter +T} +_ +T{ +right\-click +T} T{ +show chapters +T} +_ +T{ +shift+L\-click +T} T{ +show chapters +T} +_ +.TE +.TP +.B skip frwd +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +go to next chapter +T} +_ +T{ +right\-click +T} T{ +show chapters +T} +_ +T{ +shift+L\-click +T} T{ +show chapters +T} +_ +.TE +.TP +.B time elapsed +.nf +Shows current playback position timestamp +.fi +.sp +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +toggle displaying timecodes with milliseconds +T} +_ +.TE +.TP +.B seekbar +.nf +Indicates current playback position and position of chapters +.fi +.sp +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +seek to position +T} +_ +.TE +.TP +.B time left +.nf +Shows remaining playback time timestamp +.fi +.sp +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +toggle between total and remaining time +T} +_ +.TE +.TP +.B audio and sub +.nf +Displays selected track and amount of available tracks +.fi +.sp +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +cycle audio/sub tracks forward +T} +_ +T{ +right\-click +T} T{ +cycle audio/sub tracks backwards +T} +_ +T{ +shift+L\-click +T} T{ +show available audio/sub tracks +T} +_ +.TE +.TP +.B vol +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +toggle mute +T} +_ +T{ +mouse wheel +T} T{ +volume up/down +T} +_ +.TE +.TP +.B fs +.TS +center; +|l|l|. +_ +T{ +left\-click +T} T{ +toggle fullscreen +T} +_ +.TE +.UNINDENT +.SS Key Bindings +.sp +These key bindings are active by default if nothing else is already bound to +these keys. In case of collision, the function needs to be bound to a +different key. See the \fI\%Script Commands\fP section. +.TS +center; +|l|l|. +_ +T{ +del +T} T{ +Cycles visibility between never / auto (mouse\-move) / always +T} +_ +.TE +.SS Configuration +.sp +The OSC offers limited configuration through a config file +\fBscript\-opts/osc.conf\fP placed in mpv\(aqs user dir and through the +\fB\-\-script\-opts\fP command\-line option. Options provided through the command\-line +will override those from the config file. +.SS Config Syntax +.sp +The config file must exactly follow the following syntax: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# this is a comment +optionA=value1 +optionB=value2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fB#\fP can only be used at the beginning of a line and there may be no +spaces around the \fB=\fP or anywhere else. +.SS Command\-line Syntax +.sp +To avoid collisions with other scripts, all options need to be prefixed with +\fBosc\-\fP\&. +.sp +Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\-\-script\-opts=osc\-optionA=value1,osc\-optionB=value2 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Configurable Options +.INDENT 0.0 +.TP +.B \fBlayout\fP +Default: bottombar +.sp +The layout for the OSC. Currently available are: box, slimbox, +bottombar and topbar. Default pre\-0.21.0 was \(aqbox\(aq. +.TP +.B \fBseekbarstyle\fP +Default: bar +.sp +Sets the style of the playback position marker and overall shape +of the seekbar: \fBbar\fP, \fBdiamond\fP or \fBknob\fP\&. +.TP +.B \fBseekbarhandlesize\fP +Default: 0.6 +.sp +Size ratio of the seek handle if \fBseekbarstyle\fP is set to \fBdimaond\fP +or \fBknob\fP\&. This is relative to the full height of the seekbar. +.TP +.B \fBseekbarkeyframes\fP +Default: yes +.sp +Controls the mode used to seek when dragging the seekbar. By default, +keyframes are used. If set to false, exact seeking on mouse drags +will be used instead. Keyframes are preferred, but exact seeks may be +useful in cases where keyframes cannot be found. Note that using exact +seeks can potentially make mouse dragging much slower. +.TP +.B \fBseekrangestyle\fP +Default: inverted +.sp +Display seekable ranges on the seekbar. \fBbar\fP shows them on the full +height of the bar, \fBline\fP as a thick line and \fBinverted\fP as a thin +line that is inverted over playback position markers. \fBnone\fP will hide +them. Additionally, \fBslider\fP will show a permanent handle inside the seekbar +with cached ranges marked inside. Note that these will look differently +based on the seekbarstyle option. Also, \fBslider\fP does not work with +\fBseekbarstyle\fP set to \fBbar\fP\&. +.TP +.B \fBseekrangeseparate\fP +Default: yes +.sp +Controls whether to show line\-style seekable ranges on top of the +seekbar or separately if \fBseekbarstyle\fP is set to \fBbar\fP\&. +.TP +.B \fBseekrangealpha\fP +Default: 200 +.sp +Alpha of the seekable ranges, 0 (opaque) to 255 (fully transparent). +.TP +.B \fBdeadzonesize\fP +Default: 0.5 +.sp +Size of the deadzone. The deadzone is an area that makes the mouse act +like leaving the window. Movement there won\(aqt make the OSC show up and +it will hide immediately if the mouse enters it. The deadzone starts +at the window border opposite to the OSC and the size controls how much +of the window it will span. Values between 0.0 and 1.0, where 0 means the +OSC will always popup with mouse movement in the window, and 1 means the +OSC will only show up when the mouse hovers it. Default pre\-0.21.0 was 0. +.TP +.B \fBminmousemove\fP +Default: 0 +.sp +Minimum amount of pixels the mouse has to move between ticks to make +the OSC show up. Default pre\-0.21.0 was 3. +.TP +.B \fBshowwindowed\fP +Default: yes +.sp +Enable the OSC when windowed +.TP +.B \fBshowfullscreen\fP +Default: yes +.sp +Enable the OSC when fullscreen +.TP +.B \fBscalewindowed\fP +Default: 1.0 +.sp +Scale factor of the OSC when windowed. +.TP +.B \fBscalefullscreen\fP +Default: 1.0 +.sp +Scale factor of the OSC when fullscreen +.TP +.B \fBscaleforcedwindow\fP +Default: 2.0 +.sp +Scale factor of the OSC when rendered on a forced (dummy) window +.TP +.B \fBvidscale\fP +Default: yes +.sp +Scale the OSC with the video +\fBno\fP tries to keep the OSC size constant as much as the window size allows +.TP +.B \fBvalign\fP +Default: 0.8 +.sp +Vertical alignment, \-1 (top) to 1 (bottom) +.TP +.B \fBhalign\fP +Default: 0.0 +.sp +Horizontal alignment, \-1 (left) to 1 (right) +.TP +.B \fBbarmargin\fP +Default: 0 +.sp +Margin from bottom (bottombar) or top (topbar), in pixels +.TP +.B \fBboxalpha\fP +Default: 80 +.sp +Alpha of the background box, 0 (opaque) to 255 (fully transparent) +.TP +.B \fBhidetimeout\fP +Default: 500 +.sp +Duration in ms until the OSC hides if no mouse movement, must not be +negative +.TP +.B \fBfadeduration\fP +Default: 200 +.sp +Duration of fade out in ms, 0 = no fade +.TP +.B \fBtitle\fP +Default: ${media\-title} +.sp +String that supports property expansion that will be displayed as +OSC title. +ASS tags are escaped, and newlines and trailing slashes are stripped. +.TP +.B \fBtooltipborder\fP +Default: 1 +.sp +Size of the tooltip outline when using bottombar or topbar layouts +.TP +.B \fBtimetotal\fP +Default: no +.sp +Show total time instead of time remaining +.TP +.B \fBtimems\fP +Default: no +.sp +Display timecodes with milliseconds +.TP +.B \fBvisibility\fP +Default: auto (auto hide/show on mouse move) +.sp +Also supports \fBnever\fP and \fBalways\fP +.TP +.B \fBboxmaxchars\fP +Default: 80 +.sp +Max chars for the osc title at the box layout. mpv does not measure the +text width on screen and so it needs to limit it by number of chars. The +default is conservative to allow wide fonts to be used without overflow. +However, with many common fonts a bigger number can be used. YMMV. +.TP +.B \fBboxvideo\fP +Default: no +.sp +Whether to overlay the osc over the video (\fBno\fP), or to box the video +within the areas not covered by the osc (\fByes\fP). If this option is set, +the osc may overwrite the \fB\-\-video\-margin\-ratio\-*\fP options, even if the +user has set them. (It will not overwrite them if all of them are set to +default values.) +.sp +Currently, this is supported for the \fBbottombar\fP layout only. The other +layouts do not change if this option is set. +.sp +The border is static and appears even if the OSC is configured to appear +only on mouse interaction. If the OSC is invisible, the border is simply +filled with the background color (black by default). +.sp +This currently still makes the OSC overlap with subtitles (if the +\fB\-\-sub\-use\-margins\fP option is set to \fByes\fP, the default). This may be +fixed later. +.UNINDENT +.SS Script Commands +.sp +The OSC script listens to certain script commands. These commands can bound +in \fBinput.conf\fP, or sent by other scripts. +.INDENT 0.0 +.TP +.B \fBosc\-message\fP +Show a message on screen using the OSC. First argument is the message, +second the duration in seconds. +.TP +.B \fBosc\-visibility\fP +Controls visibility mode \fBnever\fP / \fBauto\fP (on mouse move) / \fBalways\fP +and also \fBcycle\fP to cycle between the modes +.UNINDENT +.sp +Example +.sp +You could put this into \fBinput.conf\fP to hide the OSC with the \fBa\fP key and +to set auto mode (the default) with \fBb\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +a script\-message osc\-visibility never +b script\-message osc\-visibility auto +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \fBosc\-playlist\fP, \fBosc\-chapterlist\fP, \fBosc\-tracklist\fP +Shows a limited view of the respective type of list using the OSC. First +argument is duration in seconds. +.UNINDENT +.SH STATS +.sp +This builtin script displays information and statistics for the currently +played file. It is enabled by default if mpv was compiled with Lua support. +It can be disabled entirely using the \fB\-\-load\-stats\-overlay=no\fP option. +.SS Usage +.sp +The following key bindings are active by default unless something else is +already bound to them: +.TS +center; +|l|l|. +_ +T{ +i +T} T{ +Show stats for a fixed duration +T} +_ +T{ +I +T} T{ +Toggle stats (shown until toggled again) +T} +_ +.TE +.sp +While the stats are visible on screen the following key bindings are active, +regardless of existing bindings. They allow you to switch between \fIpages\fP of +stats: +.TS +center; +|l|l|. +_ +T{ +1 +T} T{ +Show usual stats +T} +_ +T{ +2 +T} T{ +Show frame timings +T} +_ +.TE +.SS Font +.sp +For optimal visual experience, a font with support for many font weights and +monospaced digits is recommended. By default, the open source font +\fI\%Source Sans Pro\fP is used. +.SS Configuration +.sp +This script can be customized through a config file \fBscript\-opts/stats.conf\fP +placed in mpv\(aqs user directory and through the \fB\-\-script\-opts\fP command\-line +option. The configuration syntax is described in \fI\%ON SCREEN CONTROLLER\fP\&. +.SS Configurable Options +.INDENT 0.0 +.TP +.B \fBkey_oneshot\fP +Default: i +.TP +.B \fBkey_toggle\fP +Default: I +.sp +Key bindings to display stats. +.TP +.B \fBkey_page_1\fP +Default: 1 +.TP +.B \fBkey_page_2\fP +Default: 2 +.sp +Key bindings for page switching while stats are displayed. +.TP +.B \fBduration\fP +Default: 4 +.sp +How long the stats are shown in seconds (oneshot). +.TP +.B \fBredraw_delay\fP +Default: 1 +.sp +How long it takes to refresh the displayed stats in seconds (toggling). +.TP +.B \fBpersistent_overlay\fP +Default: no +.sp +When \fIno\fP, other scripts printing text to the screen can overwrite the +displayed stats. When \fIyes\fP, displayed stats are persistently shown for the +respective duration. This can result in overlapping text when multiple +scripts decide to print text at the same time. +.TP +.B \fBplot_perfdata\fP +Default: yes +.sp +Show graphs for performance data (page 2). +.TP +.B \fBplot_vsync_ratio\fP +Default: yes +.TP +.B \fBplot_vsync_jitter\fP +Default: yes +.sp +Show graphs for vsync and jitter values (page 1). Only when toggled. +.TP +.B \fBflush_graph_data\fP +Default: yes +.sp +Clear data buffers used for drawing graphs when toggling. +.TP +.B \fBfont\fP +Default: Source Sans Pro +.sp +Font name. Should support as many font weights as possible for optimal +visual experience. +.TP +.B \fBfont_mono\fP +Default: Source Sans Pro +.sp +Font name for parts where monospaced characters are necessary to align +text. Currently, monospaced digits are sufficient. +.TP +.B \fBfont_size\fP +Default: 8 +.sp +Font size used to render text. +.TP +.B \fBfont_color\fP +Default: FFFFFF +.sp +Font color. +.TP +.B \fBborder_size\fP +Default: 0.8 +.sp +Size of border drawn around the font. +.TP +.B \fBborder_color\fP +Default: 262626 +.sp +Color of drawn border. +.TP +.B \fBalpha\fP +Default: 11 +.sp +Transparency for drawn text. +.TP +.B \fBplot_bg_border_color\fP +Default: 0000FF +.sp +Border color used for drawing graphs. +.TP +.B \fBplot_bg_color\fP +Default: 262626 +.sp +Background color used for drawing graphs. +.TP +.B \fBplot_color\fP +Default: FFFFFF +.sp +Color used for drawing graphs. +.UNINDENT +.sp +Note: colors are given as hexadecimal values and use ASS tag order: BBGGRR +(blue green red). +.SS Different key bindings +.sp +A different key binding can be defined with the aforementioned options +\fBkey_oneshot\fP and \fBkey_toggle\fP but also with commands in \fBinput.conf\fP, +for example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +e script\-binding stats/display\-stats +E script\-binding stats/display\-stats\-toggle +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Using \fBinput.conf\fP, it is also possible to directly display a certain page: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +i script\-binding stats/display\-page\-1 +e script\-binding stats/display\-page\-2 +.ft P +.fi +.UNINDENT +.UNINDENT +.SH LUA SCRIPTING +.sp +mpv can load Lua scripts. Scripts passed to the \fB\-\-script\fP option, or found in +the \fBscripts\fP subdirectory of the mpv configuration directory (usually +\fB~/.config/mpv/scripts/\fP) will be loaded on program start. mpv also appends the +\fBscripts\fP subdirectory to the end of Lua\(aqs path so you can import scripts from +there too. Since it\(aqs added to the end, don\(aqt name scripts you want to import +the same as Lua libraries because they will be overshadowed by them. +.sp +mpv provides the built\-in module \fBmp\fP, which contains functions to send +commands to the mpv core and to retrieve information about playback state, user +settings, file information, and so on. +.sp +These scripts can be used to control mpv in a similar way to slave mode. +Technically, the Lua code uses the client API internally. +.SS Example +.sp +A script which leaves fullscreen mode when the player is paused: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +function on_pause_change(name, value) + if value == true then + mp.set_property("fullscreen", "no") + end +end +mp.observe_property("pause", "bool", on_pause_change) +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Details on the script initialization and lifecycle +.sp +Your script will be loaded by the player at program start from the \fBscripts\fP +configuration subdirectory, or from a path specified with the \fB\-\-script\fP +option. Some scripts are loaded internally (like \fB\-\-osc\fP). Each script runs in +its own thread. Your script is first run "as is", and once that is done, the event loop +is entered. This event loop will dispatch events received by mpv and call your +own event handlers which you have registered with \fBmp.register_event\fP, or +timers added with \fBmp.add_timeout\fP or similar. Note that since the +script starts execution concurrently with player initialization, some properties +may not be populated with meaningful values until the relevant subsystems have +initialized. +.sp +When the player quits, all scripts will be asked to terminate. This happens via +a \fBshutdown\fP event, which by default will make the event loop return. If your +script got into an endless loop, mpv will probably behave fine during playback, +but it won\(aqt terminate when quitting, because it\(aqs waiting on your script. +.sp +Internally, the C code will call the Lua function \fBmp_event_loop\fP after +loading a Lua script. This function is normally defined by the default prelude +loaded before your script (see \fBplayer/lua/defaults.lua\fP in the mpv sources). +The event loop will wait for events and dispatch events registered with +\fBmp.register_event\fP\&. It will also handle timers added with \fBmp.add_timeout\fP +and similar (by waiting with a timeout). +.sp +Since mpv 0.6.0, the player will wait until the script is fully loaded before +continuing normal operation. The player considers a script as fully loaded as +soon as it starts waiting for mpv events (or it exits). In practice this means +the player will more or less hang until the script returns from the main chunk +(and \fBmp_event_loop\fP is called), or the script calls \fBmp_event_loop\fP or +\fBmp.dispatch_events\fP directly. This is done to make it possible for a script +to fully setup event handlers etc. before playback actually starts. In older +mpv versions, this happened asynchronously. With mpv 0.29.0, this changes +slightly, and it merely waits for scripts to be loaded in this manner before +starting playback as part of the player initialization phase. Scripts run though +initialization in parallel. This might change again. +.SS mp functions +.sp +The \fBmp\fP module is preloaded, although it can be loaded manually with +\fBrequire \(aqmp\(aq\fP\&. It provides the core client API. +.INDENT 0.0 +.TP +.B \fBmp.command(string)\fP +Run the given command. This is similar to the commands used in input.conf. +See \fI\%List of Input Commands\fP\&. +.sp +By default, this will show something on the OSD (depending on the command), +as if it was used in \fBinput.conf\fP\&. See \fI\%Input Command Prefixes\fP how +to influence OSD usage per command. +.sp +Returns \fBtrue\fP on success, or \fBnil, error\fP on error. +.TP +.B \fBmp.commandv(arg1, arg2, ...)\fP +Similar to \fBmp.command\fP, but pass each command argument as separate +parameter. This has the advantage that you don\(aqt have to care about +quoting and escaping in some cases. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mp.command("loadfile " .. filename .. " append") +mp.commandv("loadfile", filename, "append") +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +These two commands are equivalent, except that the first version breaks +if the filename contains spaces or certain special characters. +.sp +Note that properties are \fInot\fP expanded. You can use either \fBmp.command\fP, +the \fBexpand\-properties\fP prefix, or the \fBmp.get_property\fP family of +functions. +.sp +Unlike \fBmp.command\fP, this will not use OSD by default either (except +for some OSD\-specific commands). +.TP +.B \fBmp.command_native(table [,def])\fP +Similar to \fBmp.commandv\fP, but pass the argument list as table. This has +the advantage that in at least some cases, arguments can be passed as +native types. It also allows you to use named argument. +.sp +If the table is an array, each array item is like an argument in +\fBmp.commandv()\fP (but can be a native type instead of a string). +.sp +If the table contains string keys, it\(aqs interpreted as command with named +arguments. This requires at least an entry with the key \fBname\fP to be +present, which must be a string, and contains the command name. The special +entry \fB_flags\fP is optional, and if present, must be an array of +\fI\%Input Command Prefixes\fP to apply. All other entries are interpreted as +arguments. +.sp +Returns a result table on success (usually empty), or \fBdef, error\fP on +error. \fBdef\fP is the second parameter provided to the function, and is +nil if it\(aqs missing. +.TP +.B \fBmp.command_native_async(table [,fn])\fP +Like \fBmp.command_native()\fP, but the command is ran asynchronously (as far +as possible), and upon completion, fn is called. fn has two arguments: +\fBfn(success, result, error)\fP\&. \fBsuccess\fP is always a Boolean and is true +if the command was successful, otherwise false. The second parameter is +the result value (can be nil) in case of success, nil otherwise (as returned +by \fBmp.command_native()\fP). The third parameter is the error string in case +of an error, nil otherwise. +.sp +Returns a table with undefined contents, which can be used as argument for +\fBmp.abort_async_command\fP\&. +.sp +If starting the command failed for some reason, \fBnil, error\fP is returned, +and \fBfn\fP is called indicating failure, using the same error value. +.TP +.B \fBmp.abort_async_command(t)\fP +Abort a \fBmp.command_native_async\fP call. The argument is the return value +of that command (which starts asynchronous execution of the command). +Whether this works and how long it takes depends on the command and the +situation. The abort call itself is asynchronous. Does not return anything. +.TP +.B \fBmp.get_property(name [,def])\fP +Return the value of the given property as string. These are the same +properties as used in input.conf. See \fI\%Properties\fP for a list of +properties. The returned string is formatted similar to \fB${=name}\fP +(see \fI\%Property Expansion\fP). +.sp +Returns the string on success, or \fBdef, error\fP on error. \fBdef\fP is the +second parameter provided to the function, and is nil if it\(aqs missing. +.TP +.B \fBmp.get_property_osd(name [,def])\fP +Similar to \fBmp.get_property\fP, but return the property value formatted for +OSD. This is the same string as printed with \fB${name}\fP when used in +input.conf. +.sp +Returns the string on success, or \fBdef, error\fP on error. \fBdef\fP is the +second parameter provided to the function, and is an empty string if it\(aqs +missing. Unlike \fBget_property()\fP, assigning the return value to a variable +will always result in a string. +.TP +.B \fBmp.get_property_bool(name [,def])\fP +Similar to \fBmp.get_property\fP, but return the property value as Boolean. +.sp +Returns a Boolean on success, or \fBdef, error\fP on error. +.TP +.B \fBmp.get_property_number(name [,def])\fP +Similar to \fBmp.get_property\fP, but return the property value as number. +.sp +Note that while Lua does not distinguish between integers and floats, +mpv internals do. This function simply request a double float from mpv, +and mpv will usually convert integer property values to float. +.sp +Returns a number on success, or \fBdef, error\fP on error. +.TP +.B \fBmp.get_property_native(name [,def])\fP +Similar to \fBmp.get_property\fP, but return the property value using the best +Lua type for the property. Most time, this will return a string, Boolean, +or number. Some properties (for example \fBchapter\-list\fP) are returned as +tables. +.sp +Returns a value on success, or \fBdef, error\fP on error. Note that \fBnil\fP +might be a possible, valid value too in some corner cases. +.TP +.B \fBmp.set_property(name, value)\fP +Set the given property to the given string value. See \fBmp.get_property\fP +and \fI\%Properties\fP for more information about properties. +.sp +Returns true on success, or \fBnil, error\fP on error. +.TP +.B \fBmp.set_property_bool(name, value)\fP +Similar to \fBmp.set_property\fP, but set the given property to the given +Boolean value. +.TP +.B \fBmp.set_property_number(name, value)\fP +Similar to \fBmp.set_property\fP, but set the given property to the given +numeric value. +.sp +Note that while Lua does not distinguish between integers and floats, +mpv internals do. This function will test whether the number can be +represented as integer, and if so, it will pass an integer value to mpv, +otherwise a double float. +.TP +.B \fBmp.set_property_native(name, value)\fP +Similar to \fBmp.set_property\fP, but set the given property using its native +type. +.sp +Since there are several data types which cannot represented natively in +Lua, this might not always work as expected. For example, while the Lua +wrapper can do some guesswork to decide whether a Lua table is an array +or a map, this would fail with empty tables. Also, there are not many +properties for which it makes sense to use this, instead of +\fBset_property\fP, \fBset_property_bool\fP, \fBset_property_number\fP\&. +For these reasons, this function should probably be avoided for now, except +for properties that use tables natively. +.TP +.B \fBmp.get_time()\fP +Return the current mpv internal time in seconds as a number. This is +basically the system time, with an arbitrary offset. +.TP +.B \fBmp.add_key_binding(key, name|fn [,fn [,flags]])\fP +Register callback to be run on a key binding. The binding will be mapped to +the given \fBkey\fP, which is a string describing the physical key. This uses +the same key names as in input.conf, and also allows combinations +(e.g. \fBctrl+a\fP). If the key is empty or \fBnil\fP, no physical key is +registered, but the user still can create own bindings (see below). +.sp +After calling this function, key presses will cause the function \fBfn\fP to +be called (unless the user remapped the key with another binding). +.sp +The \fBname\fP argument should be a short symbolic string. It allows the user +to remap the key binding via input.conf using the \fBscript\-message\fP +command, and the name of the key binding (see below for +an example). The name should be unique across other bindings in the same +script \- if not, the previous binding with the same name will be +overwritten. You can omit the name, in which case a random name is generated +internally. +.sp +The last argument is used for optional flags. This is a table, which can +have the following entries: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBrepeatable\fP +If set to \fBtrue\fP, enables key repeat for this specific binding. +.TP +.B \fBcomplex\fP +If set to \fBtrue\fP, then \fBfn\fP is called on both key up and down +events (as well as key repeat, if enabled), with the first +argument being a table. This table has an \fBevent\fP entry, which +is set to one of the strings \fBdown\fP, \fBrepeat\fP, \fBup\fP or +\fBpress\fP (the latter if key up/down can\(aqt be tracked). It further +has an \fBis_mouse\fP entry, which tells whether the event was caused +by a mouse button. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Internally, key bindings are dispatched via the \fBscript\-message\-to\fP or +\fBscript\-binding\fP input commands and \fBmp.register_script_message\fP\&. +.sp +Trying to map multiple commands to a key will essentially prefer a random +binding, while the other bindings are not called. It is guaranteed that +user defined bindings in the central input.conf are preferred over bindings +added with this function (but see \fBmp.add_forced_key_binding\fP). +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +function something_handler() + print("the key was pressed") +end +mp.add_key_binding("x", "something", something_handler) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This will print the message \fBthe key was pressed\fP when \fBx\fP was pressed. +.sp +The user can remap these key bindings. Then the user has to put the +following into their input.conf to remap the command to the \fBy\fP key: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +y script\-binding something +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This will print the message when the key \fBy\fP is pressed. (\fBx\fP will +still work, unless the user remaps it.) +.sp +You can also explicitly send a message to a named script only. Assume the +above script was using the filename \fBfooscript.lua\fP: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +y script\-binding fooscript/something +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBmp.add_forced_key_binding(...)\fP +This works almost the same as \fBmp.add_key_binding\fP, but registers the +key binding in a way that will overwrite the user\(aqs custom bindings in their +input.conf. (\fBmp.add_key_binding\fP overwrites default key bindings only, +but not those by the user\(aqs input.conf.) +.TP +.B \fBmp.remove_key_binding(name)\fP +Remove a key binding added with \fBmp.add_key_binding\fP or +\fBmp.add_forced_key_binding\fP\&. Use the same name as you used when adding +the bindings. It\(aqs not possible to remove bindings for which you omitted +the name. +.TP +.B \fBmp.register_event(name, fn)\fP +Call a specific function when an event happens. The event name is a string, +and the function fn is a Lua function value. +.sp +Some events have associated data. This is put into a Lua table and passed +as argument to fn. The Lua table by default contains a \fBname\fP field, +which is a string containing the event name. If the event has an error +associated, the \fBerror\fP field is set to a string describing the error, +on success it\(aqs not set. +.sp +If multiple functions are registered for the same event, they are run in +registration order, which the first registered function running before all +the other ones. +.sp +Returns true if such an event exists, false otherwise. +.sp +See \fI\%Events\fP and \fI\%List of events\fP for details. +.TP +.B \fBmp.unregister_event(fn)\fP +Undo \fBmp.register_event(..., fn)\fP\&. This removes all event handlers that +are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP comparison, +so be careful when dealing with closures. +.TP +.B \fBmp.observe_property(name, type, fn)\fP +Watch a property for changes. If the property \fBname\fP is changed, then +the function \fBfn(name)\fP will be called. \fBtype\fP can be \fBnil\fP, or be +set to one of \fBnone\fP, \fBnative\fP, \fBbool\fP, \fBstring\fP, or \fBnumber\fP\&. +\fBnone\fP is the same as \fBnil\fP\&. For all other values, the new value of +the property will be passed as second argument to \fBfn\fP, using +\fBmp.get_property_<type>\fP to retrieve it. This means if \fBtype\fP is for +example \fBstring\fP, \fBfn\fP is roughly called as in +\fBfn(name, mp.get_property_string(name))\fP\&. +.sp +If possible, change events are coalesced. If a property is changed a bunch +of times in a row, only the last change triggers the change function. (The +exact behavior depends on timing and other things.) +.sp +In some cases the function is not called even if the property changes. +This depends on the property, and it\(aqs a valid feature request to ask for +better update handling of a specific property. +.sp +If the \fBtype\fP is \fBnone\fP or \fBnil\fP, sporadic property change events are +possible. This means the change function \fBfn\fP can be called even if the +property doesn\(aqt actually change. +.sp +You always get an initial change notification. This is meant to initialize +the user\(aqs state to the current value of the property. +.TP +.B \fBmp.unobserve_property(fn)\fP +Undo \fBmp.observe_property(..., fn)\fP\&. This removes all property handlers +that are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP +comparison, so be careful when dealing with closures. +.TP +.B \fBmp.add_timeout(seconds, fn)\fP +Call the given function fn when the given number of seconds has elapsed. +Note that the number of seconds can be fractional. For now, the timer\(aqs +resolution may be as low as 50 ms, although this will be improved in the +future. +.sp +This is a one\-shot timer: it will be removed when it\(aqs fired. +.sp +Returns a timer object. See \fBmp.add_periodic_timer\fP for details. +.TP +.B \fBmp.add_periodic_timer(seconds, fn)\fP +Call the given function periodically. This is like \fBmp.add_timeout\fP, but +the timer is re\-added after the function fn is run. +.INDENT 7.0 +.TP +.B Returns a timer object. The timer object provides the following methods: +.INDENT 7.0 +.TP +.B \fBstop()\fP +Disable the timer. Does nothing if the timer is already disabled. +This will remember the current elapsed time when stopping, so that +\fBresume()\fP essentially unpauses the timer. +.TP +.B \fBkill()\fP +Disable the timer. Resets the elapsed time. \fBresume()\fP will +restart the timer. +.TP +.B \fBresume()\fP +Restart the timer. If the timer was disabled with \fBstop()\fP, this +will resume at the time it was stopped. If the timer was disabled +with \fBkill()\fP, or if it\(aqs a previously fired one\-shot timer (added +with \fBadd_timeout()\fP), this starts the timer from the beginning, +using the initially configured timeout. +.TP +.B \fBis_enabled()\fP +Whether the timer is currently enabled or was previously disabled +(e.g. by \fBstop()\fP or \fBkill()\fP). +.TP +.B \fBtimeout\fP (RW) +This field contains the current timeout period. This value is not +updated as time progresses. It\(aqs only used to calculate when the +timer should fire next when the timer expires. +.sp +If you write this, you can call \fBt:kill() ; t:resume()\fP to reset +the current timeout to the new one. (\fBt:stop()\fP won\(aqt use the +new timeout.) +.TP +.B \fBoneshot\fP (RW) +Whether the timer is periodic (\fBfalse\fP) or fires just once +(\fBtrue\fP). This value is used when the timer expires (but before +the timer callback function fn is run). +.UNINDENT +.UNINDENT +.sp +Note that these are methods, and you have to call them using \fB:\fP instead +of \fB\&.\fP (Refer to \fI\%http://www.lua.org/manual/5.2/manual.html#3.4.9\fP .) +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +seconds = 0 +timer = mp.add_periodic_timer(1, function() + print("called every second") + # stop it after 10 seconds + seconds = seconds + 1 + if seconds >= 10 then + timer:kill() + end +end) +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBmp.get_opt(key)\fP +Return a setting from the \fB\-\-script\-opts\fP option. It\(aqs up to the user and +the script how this mechanism is used. Currently, all scripts can access +this equally, so you should be careful about collisions. +.TP +.B \fBmp.get_script_name()\fP +Return the name of the current script. The name is usually made of the +filename of the script, with directory and file extension removed. If +there are several scripts which would have the same name, it\(aqs made unique +by appending a number. +.INDENT 7.0 +.INDENT 3.5 +.IP "Example" +.sp +The script \fB/path/to/fooscript.lua\fP becomes \fBfooscript\fP\&. +.UNINDENT +.UNINDENT +.TP +.B \fBmp.osd_message(text [,duration])\fP +Show an OSD message on the screen. \fBduration\fP is in seconds, and is +optional (uses \fB\-\-osd\-duration\fP by default). +.UNINDENT +.SS Advanced mp functions +.sp +These also live in the \fBmp\fP module, but are documented separately as they +are useful only in special situations. +.INDENT 0.0 +.TP +.B \fBmp.suspend()\fP +This function has been deprecated in mpv 0.21.0 and does nothing starting +with mpv 0.23.0 (no replacement). +.TP +.B \fBmp.resume()\fP +This function has been deprecated in mpv 0.21.0 and does nothing starting +with mpv 0.23.0 (no replacement). +.TP +.B \fBmp.resume_all()\fP +This function has been deprecated in mpv 0.21.0 and does nothing starting +with mpv 0.23.0 (no replacement). +.TP +.B \fBmp.get_wakeup_pipe()\fP +Calls \fBmpv_get_wakeup_pipe()\fP and returns the read end of the wakeup +pipe. This is deprecated, but still works. (See \fBclient.h\fP for details.) +.TP +.B \fBmp.get_next_timeout()\fP +Return the relative time in seconds when the next timer (\fBmp.add_timeout\fP +and similar) expires. If there is no timer, return \fBnil\fP\&. +.TP +.B \fBmp.dispatch_events([allow_wait])\fP +This can be used to run custom event loops. If you want to have direct +control what the Lua script does (instead of being called by the default +event loop), you can set the global variable \fBmp_event_loop\fP to your +own function running the event loop. From your event loop, you should call +\fBmp.dispatch_events()\fP to dequeue and dispatch mpv events. +.sp +If the \fBallow_wait\fP parameter is set to \fBtrue\fP, the function will block +until the next event is received or the next timer expires. Otherwise (and +this is the default behavior), it returns as soon as the event loop is +emptied. It\(aqs strongly recommended to use \fBmp.get_next_timeout()\fP and +\fBmp.get_wakeup_pipe()\fP if you\(aqre interested in properly working +notification of new events and working timers. +.TP +.B \fBmp.register_idle(fn)\fP +Register an event loop idle handler. Idle handlers are called before the +script goes to sleep after handling all new events. This can be used for +example to delay processing of property change events: if you\(aqre observing +multiple properties at once, you might not want to act on each property +change, but only when all change notifications have been received. +.TP +.B \fBmp.unregister_idle(fn)\fP +Undo \fBmp.register_idle(fn)\fP\&. This removes all idle handlers that +are equal to the \fBfn\fP parameter. This uses normal Lua \fB==\fP comparison, +so be careful when dealing with closures. +.TP +.B \fBmp.enable_messages(level)\fP +Set the minimum log level of which mpv message output to receive. These +messages are normally printed to the terminal. By calling this function, +you can set the minimum log level of messages which should be received with +the \fBlog\-message\fP event. See the description of this event for details. +The level is a string, see \fBmsg.log\fP for allowed log levels. +.TP +.B \fBmp.register_script_message(name, fn)\fP +This is a helper to dispatch \fBscript\-message\fP or \fBscript\-message\-to\fP +invocations to Lua functions. \fBfn\fP is called if \fBscript\-message\fP or +\fBscript\-message\-to\fP (with this script as destination) is run +with \fBname\fP as first parameter. The other parameters are passed to \fBfn\fP\&. +If a message with the given name is already registered, it\(aqs overwritten. +.sp +Used by \fBmp.add_key_binding\fP, so be careful about name collisions. +.TP +.B \fBmp.unregister_script_message(name)\fP +Undo a previous registration with \fBmp.register_script_message\fP\&. Does +nothing if the \fBname\fP wasn\(aqt registered. +.UNINDENT +.SS mp.msg functions +.sp +This module allows outputting messages to the terminal, and can be loaded +with \fBrequire \(aqmp.msg\(aq\fP\&. +.INDENT 0.0 +.TP +.B \fBmsg.log(level, ...)\fP +The level parameter is the message priority. It\(aqs a string and one of +\fBfatal\fP, \fBerror\fP, \fBwarn\fP, \fBinfo\fP, \fBv\fP, \fBdebug\fP, \fBtrace\fP\&. The +user\(aqs settings will determine which of these messages will be +visible. Normally, all messages are visible, except \fBv\fP, \fBdebug\fP and +\fBtrace\fP\&. +.sp +The parameters after that are all converted to strings. Spaces are inserted +to separate multiple parameters. +.sp +You don\(aqt need to add newlines. +.TP +.B \fBmsg.fatal(...)\fP, \fBmsg.error(...)\fP, \fBmsg.warn(...)\fP, \fBmsg.info(...)\fP, \fBmsg.verbose(...)\fP, \fBmsg.debug(...)\fP, \fBmsg.trace(...)\fP +All of these are shortcuts and equivalent to the corresponding +\fBmsg.log(level, ...)\fP call. +.UNINDENT +.SS mp.options functions +.sp +mpv comes with a built\-in module to manage options from config\-files and the +command\-line. All you have to do is to supply a table with default options to +the read_options function. The function will overwrite the default values +with values found in the config\-file and the command\-line (in that order). +.INDENT 0.0 +.TP +.B \fBoptions.read_options(table [, identifier])\fP +A \fBtable\fP with key\-value pairs. The type of the default values is +important for converting the values read from the config file or +command\-line back. Do not use \fBnil\fP as a default value! +.sp +The \fBidentifier\fP is used to identify the config\-file and the command\-line +options. These needs to unique to avoid collisions with other scripts. +Defaults to \fBmp.get_script_name()\fP\&. +.UNINDENT +.sp +Example implementation: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +require \(aqmp.options\(aq +local options = { + optionA = "defaultvalueA", + optionB = \-0.5, + optionC = true, +} +read_options(options, "myscript") +print(options.optionA) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The config file will be stored in \fBscript\-opts/identifier.conf\fP in mpv\(aqs user +folder. Comment lines can be started with # and stray spaces are not removed. +Boolean values will be represented with yes/no. +.sp +Example config: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# comment +optionA=Hello World +optionB=9999 +optionC=no +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Command\-line options are read from the \fB\-\-script\-opts\fP parameter. To avoid +collisions, all keys have to be prefixed with \fBidentifier\-\fP\&. +.sp +Example command\-line: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\-\-script\-opts=myscript\-optionA=TEST,myscript\-optionB=0,myscript\-optionC=yes +.ft P +.fi +.UNINDENT +.UNINDENT +.SS mp.utils functions +.sp +This built\-in module provides generic helper functions for Lua, and have +strictly speaking nothing to do with mpv or video/audio playback. They are +provided for convenience. Most compensate for Lua\(aqs scarce standard library. +.sp +Be warned that any of these functions might disappear any time. They are not +strictly part of the guaranteed API. +.INDENT 0.0 +.TP +.B \fButils.getcwd()\fP +Returns the directory that mpv was launched from. On error, \fBnil, error\fP +is returned. +.TP +.B \fButils.readdir(path [, filter])\fP +Enumerate all entries at the given path on the filesystem, and return them +as array. Each entry is a directory entry (without the path). +The list is unsorted (in whatever order the operating system returns it). +.sp +If the \fBfilter\fP argument is given, it must be one of the following +strings: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBfiles\fP +List regular files only. This excludes directories, special files +(like UNIX device files or FIFOs), and dead symlinks. It includes +UNIX symlinks to regular files. +.TP +.B \fBdirs\fP +List directories only, or symlinks to directories. \fB\&.\fP and \fB\&..\fP +are not included. +.TP +.B \fBnormal\fP +Include the results of both \fBfiles\fP and \fBdirs\fP\&. (This is the +default.) +.TP +.B \fBall\fP +List all entries, even device files, dead symlinks, FIFOs, and the +\fB\&.\fP and \fB\&..\fP entries. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +On error, \fBnil, error\fP is returned. +.TP +.B \fButils.file_info(path)\fP +Stats the given path for information and returns a table with the +following entries: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBmode\fP +protection bits (on Windows, always 755 (octal) for directories +and 644 (octal) for files) +.TP +.B \fBsize\fP +size in bytes +.TP +.B \fBatime\fP +time of last access +.TP +.B \fBmtime\fP +time of last modification +.TP +.B \fBctime\fP +time of last metadata change (Linux) / time of creation (Windows) +.TP +.B \fBis_file\fP +Whether \fBpath\fP is a regular file (boolean) +.TP +.B \fBis_dir\fP +Whether \fBpath\fP is a directory (boolean) +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBmode\fP and \fBsize\fP are integers. +Timestamps (\fBatime\fP, \fBmtime\fP and \fBctime\fP) are integer seconds since +the Unix epoch (Unix time). +The booleans \fBis_file\fP and \fBis_dir\fP are provided as a convenience; +they can be and are derived from \fBmode\fP\&. +.sp +On error (eg. path does not exist), \fBnil, error\fP is returned. +.TP +.B \fButils.split_path(path)\fP +Split a path into directory component and filename component, and return +them. The first return value is always the directory. The second return +value is the trailing part of the path, the directory entry. +.TP +.B \fButils.join_path(p1, p2)\fP +Return the concatenation of the 2 paths. Tries to be clever. For example, +if \fB\(gap2\fP is an absolute path, p2 is returned without change. +.TP +.B \fButils.subprocess(t)\fP +Runs an external process and waits until it exits. Returns process status +and the captured output. This is a legacy wrapper around calling the +\fBsubprocess\fP command with \fBmp.command_native\fP\&. It does the following +things: +.INDENT 7.0 +.IP \(bu 2 +copy the table \fBt\fP +.IP \(bu 2 +rename \fBcancellable\fP field to \fBplayback_only\fP +.IP \(bu 2 +rename \fBmax_size\fP to \fBcapture_size\fP +.IP \(bu 2 +set \fBcapture_stdout\fP field to \fBtrue\fP if unset +.IP \(bu 2 +set \fBname\fP field to \fBsubprocess\fP +.IP \(bu 2 +call \fBmp.command_native(copied_t)\fP +.IP \(bu 2 +if the command failed, create a dummy result table +.IP \(bu 2 +copy \fBerror_string\fP to \fBerror\fP field if the string is non\-empty +.IP \(bu 2 +return the result table +.UNINDENT +.sp +It is recommended to use \fBmp.command_native\fP or \fBmp.command_native_async\fP +directly, instead of calling this legacy wrapper. It is for compatibility +only. +.sp +See the \fBsubprocess\fP documentation for semantics and further parameters. +.TP +.B \fButils.subprocess_detached(t)\fP +Runs an external process and detaches it from mpv\(aqs control. +.sp +The parameter \fBt\fP is a table. The function reads the following entries: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBargs\fP +Array of strings of the same semantics as the \fBargs\fP used in the +\fBsubprocess\fP function. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +The function returns \fBnil\fP\&. +.sp +This is a legacy wrapper around calling the \fBrun\fP command with +\fBmp.commandv\fP and other functions. +.TP +.B \fButils.getpid()\fP +Returns the process ID of the running mpv process. This can be used to identify +the calling mpv when launching (detached) subprocesses. +.TP +.B \fButils.parse_json(str [, trail])\fP +Parses the given string argument as JSON, and returns it as a Lua table. On +error, returns \fBnil, error\fP\&. (Currently, \fBerror\fP is just a string +reading \fBerror\fP, because there is no fine\-grained error reporting of any +kind.) +.sp +The returned value uses similar conventions as \fBmp.get_property_native()\fP +to distinguish empty objects and arrays. +.sp +If the \fBtrail\fP parameter is \fBtrue\fP (or any value equal to \fBtrue\fP), +then trailing non\-whitespace text is tolerated by the function, and the +trailing text is returned as 3rd return value. (The 3rd return value is +always there, but with \fBtrail\fP set, no error is raised.) +.TP +.B \fButils.format_json(v)\fP +Format the given Lua table (or value) as a JSON string and return it. On +error, returns \fBnil, error\fP\&. (Errors usually only happen on value types +incompatible with JSON.) +.sp +The argument value uses similar conventions as \fBmp.set_property_native()\fP +to distinguish empty objects and arrays. +.TP +.B \fButils.to_string(v)\fP +Turn the given value into a string. Formats tables and their contents. This +doesn\(aqt do anything special; it is only needed because Lua is terrible. +.UNINDENT +.SS Events +.sp +Events are notifications from player core to scripts. You can register an +event handler with \fBmp.register_event\fP\&. +.sp +Note that all scripts (and other parts of the player) receive events equally, +and there\(aqs no such thing as blocking other scripts from receiving events. +.sp +Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +function my_fn(event) + print("start of playback!") +end + +mp.register_event("file\-loaded", my_fn) +.ft P +.fi +.UNINDENT +.UNINDENT +.SS List of events +.INDENT 0.0 +.TP +.B \fBstart\-file\fP +Happens right before a new file is loaded. When you receive this, the +player is loading the file (or possibly already done with it). +.TP +.B \fBend\-file\fP +Happens after a file was unloaded. Typically, the player will load the +next file right away, or quit if this was the last file. +.sp +The event has the \fBreason\fP field, which takes one of these values: +.INDENT 7.0 +.TP +.B \fBeof\fP +The file has ended. This can (but doesn\(aqt have to) include +incomplete files or broken network connections under +circumstances. +.TP +.B \fBstop\fP +Playback was ended by a command. +.TP +.B \fBquit\fP +Playback was ended by sending the quit command. +.TP +.B \fBerror\fP +An error happened. In this case, an \fBerror\fP field is present with +the error string. +.TP +.B \fBredirect\fP +Happens with playlists and similar. Details see +\fBMPV_END_FILE_REASON_REDIRECT\fP in the C API. +.TP +.B \fBunknown\fP +Unknown. Normally doesn\(aqt happen, unless the Lua API is out of sync +with the C API. (Likewise, it could happen that your script gets +reason strings that did not exist yet at the time your script was +written.) +.UNINDENT +.TP +.B \fBfile\-loaded\fP +Happens after a file was loaded and begins playback. +.TP +.B \fBseek\fP +Happens on seeking. (This might include cases when the player seeks +internally, even without user interaction. This includes e.g. segment +changes when playing ordered chapters Matroska files.) +.TP +.B \fBplayback\-restart\fP +Start of playback after seek or after file was loaded. +.TP +.B \fBidle\fP +Idle mode is entered. This happens when playback ended, and the player was +started with \fB\-\-idle\fP or \fB\-\-force\-window\fP\&. This mode is implicitly ended +when the \fBstart\-file\fP or \fBshutdown\fP events happen. +.TP +.B \fBtick\fP +Called after a video frame was displayed. This is a hack, and you should +avoid using it. Use timers instead and maybe watch pausing/unpausing events +to avoid wasting CPU when the player is paused. +.TP +.B \fBshutdown\fP +Sent when the player quits, and the script should terminate. Normally +handled automatically. See \fI\%Details on the script initialization and lifecycle\fP\&. +.TP +.B \fBlog\-message\fP +Receives messages enabled with \fBmp.enable_messages\fP\&. The message data +is contained in the table passed as first parameter to the event handler. +The table contains, in addition to the default event fields, the following +fields: +.INDENT 7.0 +.TP +.B \fBprefix\fP +The module prefix, identifies the sender of the message. This is what +the terminal player puts in front of the message text when using the +\fB\-\-v\fP option, and is also what is used for \fB\-\-msg\-level\fP\&. +.TP +.B \fBlevel\fP +The log level as string. See \fBmsg.log\fP for possible log level names. +Note that later versions of mpv might add new levels or remove +(undocumented) existing ones. +.TP +.B \fBtext\fP +The log message. The text will end with a newline character. Sometimes +it can contain multiple lines. +.UNINDENT +.sp +Keep in mind that these messages are meant to be hints for humans. You +should not parse them, and prefix/level/text of messages might change +any time. +.TP +.B \fBget\-property\-reply\fP +Undocumented (not useful for Lua scripts). +.TP +.B \fBset\-property\-reply\fP +Undocumented (not useful for Lua scripts). +.TP +.B \fBcommand\-reply\fP +Undocumented (not useful for Lua scripts). +.TP +.B \fBclient\-message\fP +Undocumented (used internally). +.TP +.B \fBvideo\-reconfig\fP +Happens on video output or filter reconfig. +.TP +.B \fBaudio\-reconfig\fP +Happens on audio output or filter reconfig. +.UNINDENT +.sp +The following events also happen, but are deprecated: \fBtracks\-changed\fP, +\fBtrack\-switched\fP, \fBpause\fP, \fBunpause\fP, \fBmetadata\-update\fP, +\fBchapter\-change\fP\&. Use \fBmp.observe_property()\fP instead. +.SS Extras +.sp +This documents experimental features, or features that are "too special" to +guarantee a stable interface. +.INDENT 0.0 +.TP +.B \fBmp.add_hook(type, priority, fn)\fP +Add a hook callback for \fBtype\fP (a string identifying a certain kind of +hook). These hooks allow the player to call script functions and wait for +their result (normally, the Lua scripting interface is asynchronous from +the point of view of the player core). \fBpriority\fP is an arbitrary integer +that allows ordering among hooks of the same kind. Using the value 50 is +recommended as neutral default value. \fBfn\fP is the function that will be +called during execution of the hook. +.sp +See \fI\%Hooks\fP for currently existing hooks and what they do \- only the hook +list is interesting; handling hook execution is done by the Lua script +function automatically. +.UNINDENT +.SH JAVASCRIPT +.sp +JavaScript support in mpv is near identical to its Lua support. Use this section +as reference on differences and availability of APIs, but otherwise you should +refer to the Lua documentation for API details and general scripting in mpv. +.SS Example +.sp +JavaScript code which leaves fullscreen mode when the player is paused: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +function on_pause_change(name, value) { + if (value == true) + mp.set_property("fullscreen", "no"); +} +mp.observe_property("pause", "bool", on_pause_change); +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Similarities with Lua +.sp +mpv tries to load a script file as JavaScript if it has a \fB\&.js\fP extension, but +otherwise, the documented Lua options, script directories, loading, etc apply to +JavaScript files too. +.sp +Script initialization and lifecycle is the same as with Lua, and most of the Lua +functions at the modules \fBmp\fP, \fBmp.utils\fP, \fBmp.msg\fP and \fBmp.options\fP are +available to JavaScript with identical APIs \- including running commands, +getting/setting properties, registering events/key\-bindings/hooks, etc. +.SS Differences from Lua +.sp +No need to load modules. \fBmp\fP, \fBmp.utils\fP, \fBmp.msg\fP and \fBmp.options\fP +are preloaded, and you can use e.g. \fBvar cwd = mp.utils.getcwd();\fP without +prior setup. +.sp +Errors are slightly different. Where the Lua APIs return \fBnil\fP for error, +the JavaScript ones return \fBundefined\fP\&. Where Lua returns \fBsomething, error\fP +JavaScript returns only \fBsomething\fP \- and makes \fBerror\fP available via +\fBmp.last_error()\fP\&. Note that only some of the functions have this additional +\fBerror\fP value \- typically the same ones which have it in Lua. +.sp +Standard APIs are preferred. For instance \fBsetTimeout\fP and \fBJSON.stringify\fP +are available, but \fBmp.add_timeout\fP and \fBmp.utils.format_json\fP are not. +.sp +No standard library. This means that interaction with anything outside of mpv is +limited to the available APIs, typically via \fBmp.utils\fP\&. However, some file +functions were added, and CommonJS \fBrequire\fP is available too \- where the +loaded modules have the same privileges as normal scripts. +.SS Language features \- ECMAScript 5 +.sp +The scripting backend which mpv currently uses is MuJS \- a compatible minimal +ES5 interpreter. As such, \fBString.substring\fP is implemented for instance, +while the common but non\-standard \fBString.substr\fP is not. Please consult the +MuJS pages on language features and platform support \- \fI\%http://mujs.com\fP . +.SS Unsupported Lua APIs and their JS alternatives +.sp +\fBmp.add_timeout(seconds, fn)\fP JS: \fBid = setTimeout(fn, ms)\fP +.sp +\fBmp.add_periodic_timer(seconds, fn)\fP JS: \fBid = setInterval(fn, ms)\fP +.sp +\fButils.parse_json(str [, trail])\fP JS: \fBJSON.parse(str)\fP +.sp +\fButils.format_json(v)\fP JS: \fBJSON.stringify(v)\fP +.sp +\fButils.to_string(v)\fP see \fBdump\fP below. +.sp +\fBmp.suspend()\fP JS: none (deprecated). +.sp +\fBmp.resume()\fP JS: none (deprecated). +.sp +\fBmp.resume_all()\fP JS: none (deprecated). +.sp +\fBmp.get_next_timeout()\fP see event loop below. +.sp +\fBmp.dispatch_events([allow_wait])\fP see event loop below. +.SS Scripting APIs \- identical to Lua +.sp +(LE) \- Last\-Error, indicates that \fBmp.last_error()\fP can be used after the +call to test for success (empty string) or failure (non empty reason string). +Where the Lua APIs use \fBnil\fP to indicate error, JS APIs use \fBundefined\fP\&. +.sp +\fBmp.command(string)\fP (LE) +.sp +\fBmp.commandv(arg1, arg2, ...)\fP (LE) +.sp +\fBmp.command_native(table [,def])\fP (LE) +.sp +\fBid = mp.command_native_async(table [,fn])\fP (LE) Notes: \fBid\fP is true\-thy on +success, \fBfn\fP is called always a\-sync, \fBerror\fP is empty string on success. +.sp +\fBmp.abort_async_command(id)\fP +.sp +\fBmp.get_property(name [,def])\fP (LE) +.sp +\fBmp.get_property_osd(name [,def])\fP (LE) +.sp +\fBmp.get_property_bool(name [,def])\fP (LE) +.sp +\fBmp.get_property_number(name [,def])\fP (LE) +.sp +\fBmp.get_property_native(name [,def])\fP (LE) +.sp +\fBmp.set_property(name, value)\fP (LE) +.sp +\fBmp.set_property_bool(name, value)\fP (LE) +.sp +\fBmp.set_property_number(name, value)\fP (LE) +.sp +\fBmp.set_property_native(name, value)\fP (LE) +.sp +\fBmp.get_time()\fP +.sp +\fBmp.add_key_binding(key, name|fn [,fn [,flags]])\fP +.sp +\fBmp.add_forced_key_binding(...)\fP +.sp +\fBmp.remove_key_binding(name)\fP +.sp +\fBmp.register_event(name, fn)\fP +.sp +\fBmp.unregister_event(fn)\fP +.sp +\fBmp.observe_property(name, type, fn)\fP +.sp +\fBmp.unobserve_property(fn)\fP +.sp +\fBmp.get_opt(key)\fP +.sp +\fBmp.get_script_name()\fP +.sp +\fBmp.osd_message(text [,duration])\fP +.sp +\fBmp.get_wakeup_pipe()\fP +.sp +\fBmp.register_idle(fn)\fP +.sp +\fBmp.unregister_idle(fn)\fP +.sp +\fBmp.enable_messages(level)\fP +.sp +\fBmp.register_script_message(name, fn)\fP +.sp +\fBmp.unregister_script_message(name)\fP +.sp +\fBmp.msg.log(level, ...)\fP +.sp +\fBmp.msg.fatal(...)\fP +.sp +\fBmp.msg.error(...)\fP +.sp +\fBmp.msg.warn(...)\fP +.sp +\fBmp.msg.info(...)\fP +.sp +\fBmp.msg.verbose(...)\fP +.sp +\fBmp.msg.debug(...)\fP +.sp +\fBmp.msg.trace(...)\fP +.sp +\fBmp.utils.getcwd()\fP (LE) +.sp +\fBmp.utils.readdir(path [, filter])\fP (LE) +.sp +\fBmp.utils.file_info(path)\fP (LE) +.sp +\fBmp.utils.split_path(path)\fP +.sp +\fBmp.utils.join_path(p1, p2)\fP +.sp +\fBmp.utils.subprocess(t)\fP +.sp +\fBmp.utils.subprocess_detached(t)\fP +.sp +\fBmp.utils.getpid()\fP (LE) +.sp +\fBmp.add_hook(type, priority, fn)\fP +.sp +\fBmp.options.read_options(obj [, identifier])\fP (types: string/boolean/number) +.SS Additional utilities +.INDENT 0.0 +.TP +.B \fBmp.last_error()\fP +If used after an API call which updates last error, returns an empty string +if the API call succeeded, or a non\-empty error reason string otherwise. +.TP +.B \fBError.stack\fP (string) +When using \fBtry { ... } catch(e) { ... }\fP, then \fBe.stack\fP is the stack +trace of the error \- if it was created using the \fBError(...)\fP constructor. +.TP +.B \fBprint\fP (global) +A convenient alias to \fBmp.msg.info\fP\&. +.TP +.B \fBdump\fP (global) +Like \fBprint\fP but also expands objects and arrays recursively. +.TP +.B \fBmp.utils.getenv(name)\fP +Returns the value of the host environment variable \fBname\fP, or +\fBundefined\fP if the variable is not defined. +.TP +.B \fBmp.utils.get_user_path(path)\fP +Expands (mpv) meta paths like \fB~/x\fP, \fB~~/y\fP, \fB~~desktop/z\fP etc. +\fBread_file\fP, \fBwrite_file\fP and \fBrequire\fP already use this internaly. +.TP +.B \fBmp.utils.read_file(fname [,max])\fP +Returns the content of file \fBfname\fP as string. If \fBmax\fP is provided and +not negative, limit the read to \fBmax\fP bytes. +.TP +.B \fBmp.utils.write_file(fname, str)\fP +(Over)write file \fBfname\fP with text content \fBstr\fP\&. \fBfname\fP must be +prefixed with \fBfile://\fP as simple protection against accidental arguments +switch, e.g. \fBmp.utils.write_file("file://~/abc.txt", "hello world")\fP\&. +.UNINDENT +.sp +Note: \fBread_file\fP and \fBwrite_file\fP throw on errors, allow text content only. +.INDENT 0.0 +.TP +.B \fBmp.get_time_ms()\fP +Same as \fBmp.get_time()\fP but in ms instead of seconds. +.TP +.B \fBmp.get_script_file()\fP +Returns the file name of the current script. +.TP +.B \fBexit()\fP (global) +Make the script exit at the end of the current event loop iteration. +Note: please remove added key bindings before calling \fBexit()\fP\&. +.TP +.B \fBmp.utils.compile_js(fname, content_str)\fP +Compiles the JS code \fBcontent_str\fP as file name \fBfname\fP (without loading +anything from the filesystem), and returns it as a function. Very similar +to a \fBFunction\fP constructor, but shows at stack traces as \fBfname\fP\&. +.UNINDENT +.SS Timers (global) +.sp +The standard HTML/node.js timers are available: +.sp +\fBid = setTimeout(fn [,duration [,arg1 [,arg2...]]])\fP +.sp +\fBid = setTimeout(code_string [,duration])\fP +.sp +\fBclearTimeout(id)\fP +.sp +\fBid = setInterval(fn [,duration [,arg1 [,arg2...]]])\fP +.sp +\fBid = setInterval(code_string [,duration])\fP +.sp +\fBclearInterval(id)\fP +.sp +\fBsetTimeout\fP and \fBsetInterval\fP return id, and later call \fBfn\fP (or execute +\fBcode_string\fP) after \fBduration\fP ms. Interval also repeat every \fBduration\fP\&. +.sp +\fBduration\fP has a minimum and default value of 0, \fBcode_string\fP is +a plain string which is evaluated as JS code, and \fB[,arg1 [,arg2..]]\fP are used +as arguments (if provided) when calling back \fBfn\fP\&. +.sp +The \fBclear...(id)\fP functions cancel timer \fBid\fP, and are irreversible. +.sp +Note: timers always call back asynchronously, e.g. \fBsetTimeout(fn)\fP will never +call \fBfn\fP before returning. \fBfn\fP will be called either at the end of this +event loop iteration or at a later event loop iteration. This is true also for +intervals \- which also never call back twice at the same event loop iteration. +.sp +Additionally, timers are processed after the event queue is empty, so it\(aqs valid +to use \fBsetTimeout(fn)\fP as a one\-time idle observer. +.SS CommonJS modules and \fBrequire(id)\fP +.sp +CommonJS Modules are a standard system where scripts can export common functions +for use by other scripts. A module is a script which adds properties (functions, +etc) to its invisible \fBexports\fP object, which another script can access by +loading it with \fBrequire(module\-id)\fP \- which returns that \fBexports\fP object. +.sp +Modules and \fBrequire\fP are supported, standard compliant, and generally similar +to node.js. However, most node.js modules won\(aqt run due to missing modules such +as \fBfs\fP, \fBprocess\fP, etc, but some node.js modules with minimal dependencies +do work. In general, this is for mpv modules and not a node.js replacement. +.sp +A \fB\&.js\fP file extension is always added to \fBid\fP, e.g. \fBrequire("./foo")\fP +will load the file \fB\&./foo.js\fP and return its \fBexports\fP object. +.sp +An id is relative (to the script which \fBrequire\fP\(aqd it) if it starts with +\fB\&./\fP or \fB\&../\fP\&. Otherwise, it\(aqs considered a "top\-level id" (CommonJS term). +.sp +Top level id is evaluated as absolute filesystem path if possible (e.g. \fB/x/y\fP +or \fB~/x\fP). Otherwise, it\(aqs searched at \fBscripts/modules.js/\fP in mpv config +dirs \- in normal config search order. E.g. \fBrequire("x")\fP is searched as file +\fBx.js\fP at those dirs, and id \fBfoo/x\fP is searched as file \fBfoo/x.js\fP\&. +.sp +No \fBglobal\fP variable, but a module\(aqs \fBthis\fP at its top lexical scope is the +global object \- also in strict mode. If you have a module which needs \fBglobal\fP +as the global object, you could do \fBthis.global = this;\fP before \fBrequire\fP\&. +.sp +Functions and variables declared at a module don\(aqt pollute the global object. +.SS The event loop +.sp +The event loop poll/dispatch mpv events as long as the queue is not empty, then +processes the timers, then waits for the next event, and repeats this forever. +.sp +You could put this code at your script to replace the built\-in event loop, and +also print every event which mpv sends to your script: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +function mp_event_loop() { + var wait = 0; + do { + var e = mp.wait_event(wait); + dump(e); // there could be a lot of prints... + if (e.event != "none") { + mp.dispatch_event(e); + wait = 0; + } else { + wait = mp.process_timers() / 1000; + if (wait != 0) { + mp.notify_idle_observers(); + wait = mp.peek_timers_wait() / 1000; + } + } + } while (mp.keep_running); +} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBmp_event_loop\fP is a name which mpv tries to call after the script loads. +The internal implementation is similar to this (without \fBdump\fP though..). +.sp +\fBe = mp.wait_event(wait)\fP returns when the next mpv event arrives, or after +\fBwait\fP seconds if positive and no mpv events arrived. \fBwait\fP value of 0 +returns immediately (with \fBe.event == "none"\fP if the queue is empty). +.sp +\fBmp.dispatch_event(e)\fP calls back the handlers registered for \fBe.event\fP, +if there are such (event handlers, property observers, script messages, etc). +.sp +\fBmp.process_timers()\fP calls back the already\-added, non\-canceled due timers, +and returns the duration in ms till the next due timer (possibly 0), or \-1 if +there are no pending timers. Must not be called recursively. +.sp +\fBmp.notify_idle_observers()\fP calls back the idle observers, which we do when +we\(aqre about to sleep (wait != 0), but the observers may add timers or take +non\-negligible duration to complete, so we re\-calculate \fBwait\fP afterwards. +.sp +\fBmp.peek_timers_wait()\fP returns the same values as \fBmp.process_timers()\fP +but without doing anything. Invalid result if called from a timer callback. +.sp +Note: \fBexit()\fP is also registered for the \fBshutdown\fP event, and its +implementation is a simple \fBmp.keep_running = false\fP\&. +.SH JSON IPC +.sp +mpv can be controlled by external programs using the JSON\-based IPC protocol. +It can be enabled by specifying the path to a unix socket or a named pipe using +the option \fB\-\-input\-ipc\-server\fP\&. Clients can connect to this socket and send +commands to the player or receive events from it. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This is not intended to be a secure network protocol. It is explicitly +insecure: there is no authentication, no encryption, and the commands +themselves are insecure too. For example, the \fBrun\fP command is exposed, +which can run arbitrary system commands. The use\-case is controlling the +player locally. This is not different from the MPlayer slave protocol. +.UNINDENT +.UNINDENT +.SS Socat example +.sp +You can use the \fBsocat\fP tool to send commands (and receive replies) from the +shell. Assuming mpv was started with: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv file.mkv \-\-input\-ipc\-server=/tmp/mpvsocket +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Then you can control it using socat: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +> echo \(aq{ "command": ["get_property", "playback\-time"] }\(aq | socat \- /tmp/mpvsocket +{"data":190.482000,"error":"success"} +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +In this case, socat copies data between stdin/stdout and the mpv socket +connection. +.sp +See the \fB\-\-idle\fP option how to make mpv start without exiting immediately or +playing a file. +.sp +It\(aqs also possible to send input.conf style text\-only commands: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +> echo \(aqshow\-text ${playback\-time}\(aq | socat \- /tmp/mpvsocket +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +But you won\(aqt get a reply over the socket. (This particular command shows the +playback time on the player\(aqs OSD.) +.SS Command Prompt example +.sp +Unfortunately, it\(aqs not as easy to test the IPC protocol on Windows, since +Windows ports of socat (in Cygwin and MSYS2) don\(aqt understand named pipes. In +the absence of a simple tool to send and receive from bidirectional pipes, the +\fBecho\fP command can be used to send commands, but not receive replies from the +command prompt. +.sp +Assuming mpv was started with: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv file.mkv \-\-input\-ipc\-server=\e\e.\epipe\empvsocket +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +You can send commands from a command prompt: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +echo show\-text ${playback\-time} >\e\e.\epipe\empvsocket +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To be able to simultaneously read and write from the IPC pipe, like on Linux, +it\(aqs necessary to write an external program that uses overlapped file I/O (or +some wrapper like .NET\(aqs NamedPipeClientStream.) +.SS Protocol +.sp +The protocol uses UTF\-8\-only JSON as defined by RFC\-8259. Unlike standard JSON, +"u" escape sequences are not allowed to construct surrogate pairs. To avoid +getting conflicts, encode all text characters including and above codepoint +U+0020 as UTF\-8. mpv might output broken UTF\-8 in corner cases (see "UTF\-8" +section below). +.sp +Clients can execute commands on the player by sending JSON messages of the +following form: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "command": ["command_name", "param1", "param2", ...] } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where \fBcommand_name\fP is the name of the command to be executed, followed by a +list of parameters. Parameters must be formatted as native JSON values +(integers, strings, booleans, ...). Every message \fBmust\fP be terminated with +\fB\en\fP\&. Additionally, \fB\en\fP must not appear anywhere inside the message. In +practice this means that messages should be minified before being sent to mpv. +.sp +mpv will then send back a reply indicating whether the command was run +correctly, and an additional field holding the command\-specific return data (it +can also be null). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "error": "success", "data": null } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +mpv will also send events to clients with JSON messages of the following form: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "event": "event_name" } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +where \fBevent_name\fP is the name of the event. Additional event\-specific fields +can also be present. See \fI\%List of events\fP for a list of all supported events. +.sp +Because events can occur at any time, it may be difficult at times to determine +which response goes with which command. Commands may optionally include a +\fBrequest_id\fP which, if provided in the command request, will be copied +verbatim into the response. mpv does not intrepret the \fBrequest_id\fP in any +way; it is solely for the use of the requester. The only requirement is that +the \fBrequest_id\fP field must be an integer (a number without fractional parts +in the range \fB\-2^63..2^63\-1\fP). Using other types is deprecated and will +currently show a warning. In the future, this will raise an error. +.sp +For example, this request: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "command": ["get_property", "time\-pos"], "request_id": 100 } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Would generate this response: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "error": "success", "data": 1.468135, "request_id": 100 } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If you don\(aqt specify a \fBrequest_id\fP, command replies will set it to 0. +.sp +Commands may run asynchronously in the future, instead of blocking the socket +until a reply is sent. +.sp +All commands, replies, and events are separated from each other with a line +break character (\fB\en\fP). +.sp +If the first character (after skipping whitespace) is not \fB{\fP, the command +will be interpreted as non\-JSON text command, as they are used in input.conf +(or \fBmpv_command_string()\fP in the client API). Additionally, lines starting +with \fB#\fP and empty lines are ignored. +.sp +Currently, embedded 0 bytes terminate the current line, but you should not +rely on this. +.SS Commands +.sp +In addition to the commands described in \fI\%List of Input Commands\fP, a few +extra commands can also be used as part of the protocol: +.INDENT 0.0 +.TP +.B \fBclient_name\fP +Return the name of the client as string. This is the string \fBipc\-N\fP with +N being an integer number. +.TP +.B \fBget_time_us\fP +Return the current mpv internal time in microseconds as a number. This is +basically the system time, with an arbitrary offset. +.TP +.B \fBget_property\fP +Return the value of the given property. The value will be sent in the data +field of the replay message. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "command": ["get_property", "volume"] } +{ "data": 50.0, "error": "success" } +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBget_property_string\fP +Like \fBget_property\fP, but the resulting data will always be a string. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "command": ["get_property_string", "volume"] } +{ "data": "50.000000", "error": "success" } +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBset_property\fP +Set the given property to the given value. See \fI\%Properties\fP for more +information about properties. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "command": ["set_property", "pause", true] } +{ "error": "success" } +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBset_property_string\fP +Alias for \fBset_property\fP\&. Both commands accept native values and strings. +.TP +.B \fBobserve_property\fP +Watch a property for changes. If the given property is changed, then an +event of type \fBproperty\-change\fP will be generated +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "command": ["observe_property", 1, "volume"] } +{ "error": "success" } +{ "event": "property\-change", "id": 1, "data": 52.0, "name": "volume" } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +If the connection is closed, the IPC client is destroyed internally, +and the observed properties are unregistered. This happens for example +when sending commands to a socket with separate \fBsocat\fP invocations. +This can make it seem like property observation does not work. You must +keep the IPC connection open to make it work. +.UNINDENT +.UNINDENT +.TP +.B \fBobserve_property_string\fP +Like \fBobserve_property\fP, but the resulting data will always be a string. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "command": ["observe_property_string", 1, "volume"] } +{ "error": "success" } +{ "event": "property\-change", "id": 1, "data": "52.000000", "name": "volume" } +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBunobserve_property\fP +Undo \fBobserve_property\fP or \fBobserve_property_string\fP\&. This requires the +numeric id passed to the observed command as argument. +.sp +Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "command": ["unobserve_property", 1] } +{ "error": "success" } +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \fBrequest_log_messages\fP +Enable output of mpv log messages. They will be received as events. The +parameter to this command is the log\-level (see \fBmpv_request_log_messages\fP +C API function). +.sp +Log message output is meant for humans only (mostly for debugging). +Attempting to retrieve information by parsing these messages will just +lead to breakages with future mpv releases. Instead, make a feature request, +and ask for a proper event that returns the information you need. +.TP +.B \fBenable_event\fP, \fBdisable_event\fP +Enables or disables the named event. Mirrors the \fBmpv_request_event\fP C +API function. If the string \fBall\fP is used instead of an event name, all +events are enabled or disabled. +.sp +By default, most events are enabled, and there is not much use for this +command. +.TP +.B \fBget_version\fP +Returns the client API version the C API of the remote mpv instance +provides. +.sp +See also: \fBDOCS/client\-api\-changes.rst\fP\&. +.UNINDENT +.SS UTF\-8 +.sp +Normally, all strings are in UTF\-8. Sometimes it can happen that strings are +in some broken encoding (often happens with file tags and such, and filenames +on many Unixes are not required to be in UTF\-8 either). This means that mpv +sometimes sends invalid JSON. If that is a problem for the client application\(aqs +parser, it should filter the raw data for invalid UTF\-8 sequences and perform +the desired replacement, before feeding the data to its JSON parser. +.sp +mpv will not attempt to construct invalid UTF\-8 with broken "u" escape +sequences. This includes surrogate pairs. +.SS JSON extensions +.sp +The following non\-standard extensions are supported: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +a list or object item can have a trailing "," +.IP \(bu 2 +object syntax accepts "=" in addition of ":" +.IP \(bu 2 +object keys can be unquoted, if they start with a character in "A\-Za\-z_" +and contain only characters in "A\-Za\-z0\-9_" +.IP \(bu 2 +byte escapes with "xAB" are allowed (with AB being a 2 digit hex number) +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ objkey = "value\ex0A" } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Is equivalent to: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "objkey": "value\en" } +.ft P +.fi +.UNINDENT +.UNINDENT +.SH CHANGELOG +.sp +There is no real changelog, but you can look at the following things: +.INDENT 0.0 +.IP \(bu 2 +The release changelog, which should contain most user\-visible changes, +including new features and bug fixes: +.sp +\fI\%https://github.com/mpv\-player/mpv/releases\fP +.IP \(bu 2 +The git log, which is the "real" changelog +.IP \(bu 2 +The files \fBclient\-api\-changes.rst\fP and \fBinterface\-changes.rst\fP in the +\fBDOCS\fP sub directoryon the git repository, which document API and user +interface changes (the latter usually documents breaking changes only, rather +than additions). +.IP \(bu 2 +The file \fBmplayer\-changes.rst\fP in the \fBDOCS\fP sub directory on the git +repository, which used to be in place of this section. It documents some +changes that happened since mplayer2 forked off MPlayer. (Not updated +anymore.) +.UNINDENT +.SH EMBEDDING INTO OTHER PROGRAMS (LIBMPV) +.sp +mpv can be embedded into other programs as video/audio playback backend. The +recommended way to do so is using libmpv. See \fBlibmpv/client.h\fP in the mpv +source code repository. This provides a C API. Bindings for other languages +might be available (see wiki). +.sp +Since libmpv merely allows access to underlying mechanisms that can control +mpv, further documentation is spread over a few places: +.INDENT 0.0 +.IP \(bu 2 +\fI\%https://github.com/mpv\-player/mpv/blob/master/libmpv/client.h\fP +.IP \(bu 2 +\fI\%http://mpv.io/manual/master/#options\fP +.IP \(bu 2 +\fI\%http://mpv.io/manual/master/#list\-of\-input\-commands\fP +.IP \(bu 2 +\fI\%http://mpv.io/manual/master/#properties\fP +.IP \(bu 2 +\fI\%https://github.com/mpv\-player/mpv\-examples/tree/master/libmpv\fP +.UNINDENT +.SH C PLUGINS +.sp +You can write C plugins for mpv. These use the libmpv API, although they do not +use the libmpv library itself. +.sp +Currently, they must be explicitly enabled at build time with +\fB\-\-enable\-cplugins\fP\&. They are available on Linux/BSD platforms only. +.SS C plugins location +.sp +C plugins are put into the mpv scripts directory in its config directory +(see the \fI\%FILES\fP section for details). They must have a \fB\&.so\fP file extension. +They can also be explicitly loaded with the \fB\-\-script\fP option. +.SS API +.sp +A C plugin must export the following function: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +int mpv_open_cplugin(mpv_handle *handle) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The plugin function will be called on loading time. This function does not +return as long as your plugin is loaded (it runs in its own thread). The +\fBhandle\fP will be deallocated as soon as the plugin function returns. +.sp +The return value is interpreted as error status. A value of \fB0\fP is +interpreted as success, while \fB\-1\fP signals an error. In the latter case, +the player prints an uninformative error message that loading failed. +.sp +Return values other than \fB0\fP and \fB\-1\fP are reserved, and trigger undefined +behavior. +.sp +Within the plugin function, you can call libmpv API functions. The \fBhandle\fP +is created by \fBmpv_create_client()\fP (or actually an internal equivalent), +and belongs to you. You can call \fBmpv_wait_event()\fP to wait for things +happening, and so on. +.sp +Note that the player might block until your plugin calls \fBmpv_wait_event()\fP +for the first time. This gives you a chance to install initial hooks etc. +before playback begins. +.sp +The details are quite similar to Lua scripts. +.SS Linkage to libmpv +.sp +The current implementation requires that your plugins are \fBnot\fP linked against +libmpv. What your plugins uses are not symbols from a libmpv binary, but +symbols from the mpv host binary. +.SS Examples +.sp +See: +.INDENT 0.0 +.IP \(bu 2 +\fI\%https://github.com/mpv\-player/mpv\-examples/tree/master/cplugins\fP +.UNINDENT +.SH ENVIRONMENT VARIABLES +.sp +There are a number of environment variables that can be used to control the +behavior of mpv. +.INDENT 0.0 +.TP +.B \fBHOME\fP, \fBXDG_CONFIG_HOME\fP +Used to determine mpv config directory. If \fBXDG_CONFIG_HOME\fP is not set, +\fB$HOME/.config/mpv\fP is used. +.sp +\fB$HOME/.mpv\fP is always added to the list of config search paths with a +lower priority. +.TP +.B \fBXDG_CONFIG_DIRS\fP +If set, XDG\-style system configuration directories are used. Otherwise, +the UNIX convention (\fBPREFIX/etc/mpv/\fP) is used. +.TP +.B \fBMPV_HOME\fP +Directory where mpv looks for user settings. Overrides \fBHOME\fP, and mpv +will try to load the config file as \fB$MPV_HOME/mpv.conf\fP\&. +.TP +.B \fBMPV_VERBOSE\fP (see also \fB\-v\fP and \fB\-\-msg\-level\fP) +Set the initial verbosity level across all message modules (default: 0). +This is an integer, and the resulting verbosity corresponds to the number +of \fB\-\-v\fP options passed to the command line. +.TP +.B \fBMPV_LEAK_REPORT\fP +If set to \fB1\fP, enable internal talloc leak reporting. +.TP +.B \fBLADSPA_PATH\fP +Specifies the search path for LADSPA plugins. If it is unset, fully +qualified path names must be used. +.TP +.B \fBDISPLAY\fP +Standard X11 display name to use. +.TP +.B FFmpeg/Libav: +This library accesses various environment variables. However, they are not +centrally documented, and documenting them is not our job. Therefore, this +list is incomplete. +.sp +Notable environment variables: +.INDENT 7.0 +.TP +.B \fBhttp_proxy\fP +URL to proxy for \fBhttp://\fP and \fBhttps://\fP URLs. +.TP +.B \fBno_proxy\fP +List of domain patterns for which no proxy should be used. +List entries are separated by \fB,\fP\&. Patterns can include \fB*\fP\&. +.UNINDENT +.TP +.B libdvdcss: +.INDENT 7.0 +.TP +.B \fBDVDCSS_CACHE\fP +Specify a directory in which to store title key values. This will +speed up descrambling of DVDs which are in the cache. The +\fBDVDCSS_CACHE\fP directory is created if it does not exist, and a +subdirectory is created named after the DVD\(aqs title or manufacturing +date. If \fBDVDCSS_CACHE\fP is not set or is empty, libdvdcss will use +the default value which is \fB${HOME}/.dvdcss/\fP under Unix and +the roaming application data directory (\fB%APPDATA%\fP) under +Windows. The special value "off" disables caching. +.TP +.B \fBDVDCSS_METHOD\fP +Sets the authentication and decryption method that libdvdcss will use +to read scrambled discs. Can be one of \fBtitle\fP, \fBkey\fP or \fBdisc\fP\&. +.INDENT 7.0 +.TP +.B key +is the default method. libdvdcss will use a set of calculated +player keys to try to get the disc key. This can fail if the drive +does not recognize any of the player keys. +.TP +.B disc +is a fallback method when key has failed. Instead of using player +keys, libdvdcss will crack the disc key using a brute force +algorithm. This process is CPU intensive and requires 64 MB of +memory to store temporary data. +.TP +.B title +is the fallback when all other methods have failed. It does not +rely on a key exchange with the DVD drive, but rather uses a crypto +attack to guess the title key. On rare cases this may fail because +there is not enough encrypted data on the disc to perform a +statistical attack, but on the other hand it is the only way to +decrypt a DVD stored on a hard disc, or a DVD with the wrong region +on an RPC2 drive. +.UNINDENT +.TP +.B \fBDVDCSS_RAW_DEVICE\fP +Specify the raw device to use. Exact usage will depend on your +operating system, the Linux utility to set up raw devices is raw(8) +for instance. Please note that on most operating systems, using a raw +device requires highly aligned buffers: Linux requires a 2048 bytes +alignment (which is the size of a DVD sector). +.TP +.B \fBDVDCSS_VERBOSE\fP +Sets the libdvdcss verbosity level. +.INDENT 7.0 +.TP +.B 0 +Outputs no messages at all. +.TP +.B 1 +Outputs error messages to stderr. +.TP +.B 2 +Outputs error messages and debug messages to stderr. +.UNINDENT +.TP +.B \fBDVDREAD_NOKEYS\fP +Skip retrieving all keys on startup. Currently disabled. +.TP +.B \fBHOME\fP +FIXME: Document this. +.UNINDENT +.UNINDENT +.SH EXIT CODES +.sp +Normally \fBmpv\fP returns 0 as exit code after finishing playback successfully. +If errors happen, the following exit codes can be returned: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B 1 +Error initializing mpv. This is also returned if unknown options are +passed to mpv. +.TP +.B 2 +The file passed to mpv couldn\(aqt be played. This is somewhat fuzzy: +currently, playback of a file is considered to be successful if +initialization was mostly successful, even if playback fails +immediately after initialization. +.TP +.B 3 +There were some files that could be played, and some files which +couldn\(aqt (using the definition of success from above). +.TP +.B 4 +Quit due to a signal, Ctrl+c in a VO window (by default), or from the +default quit key bindings in encoding mode. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Note that quitting the player manually will always lead to exit code 0, +overriding the exit code that would be returned normally. Also, the \fBquit\fP +input command can take an exit code: in this case, that exit code is returned. +.SH FILES +.sp +For Windows\-specifics, see \fI\%FILES ON WINDOWS\fP section. +.INDENT 0.0 +.TP +.B \fB/usr/local/etc/mpv/mpv.conf\fP +mpv system\-wide settings (depends on \fB\-\-prefix\fP passed to configure \- mpv +in default configuration will use \fB/usr/local/etc/mpv/\fP as config +directory, while most Linux distributions will set it to \fB/etc/mpv/\fP). +.TP +.B \fB~/.config/mpv/mpv.conf\fP +mpv user settings (see \fI\%CONFIGURATION FILES\fP section) +.TP +.B \fB~/.config/mpv/input.conf\fP +key bindings (see \fI\%INPUT.CONF\fP section) +.TP +.B \fB~/.config/mpv/fonts.conf\fP +Fontconfig fonts.conf that is customized for mpv. You should include system +fonts.conf in this file or mpv would not know about fonts that you already +have in the system. +.sp +Only available when libass is built with fontconfig. +.TP +.B \fB~/.config/mpv/subfont.ttf\fP +fallback subtitle font +.TP +.B \fB~/.config/mpv/fonts/\fP +Font files in this directory are used by mpv/libass for subtitles. Useful +if you do not want to install fonts to your system. Note that files in this +directory are loaded into memory before being used by mpv. If you have a +lot of fonts, consider using fonts.conf (see above) to include additional +fonts, which is more memory\-efficient. +.TP +.B \fB~/.config/mpv/scripts/\fP +All files in this directory are loaded as if they were passed to the +\fB\-\-script\fP option. They are loaded in alphabetical order, and sub\-directories +and files with no \fB\&.lua\fP extension are ignored. The \fB\-\-load\-scripts=no\fP +option disables loading these files. +.TP +.B \fB~/.config/mpv/watch_later/\fP +Contains temporary config files needed for resuming playback of files with +the watch later feature. See for example the \fBQ\fP key binding, or the +\fBquit\-watch\-later\fP input command. +.sp +Each file is a small config file which is loaded if the corresponding media +file is loaded. It contains the playback position and some (not necessarily +all) settings that were changed during playback. The filenames are hashed +from the full paths of the media files. It\(aqs in general not possible to +extract the media filename from this hash. However, you can set the +\fB\-\-write\-filename\-in\-watch\-later\-config\fP option, and the player will +add the media filename to the contents of the resume config file. +.TP +.B \fB~/.config/mpv/script\-opts/osc.conf\fP +This is loaded by the OSC script. See the \fI\%ON SCREEN CONTROLLER\fP docs +for details. +.sp +Other files in this directory are specific to the corresponding scripts +as well, and the mpv core doesn\(aqt touch them. +.UNINDENT +.sp +Note that the environment variables \fB$XDG_CONFIG_HOME\fP and \fB$MPV_HOME\fP can +override the standard directory \fB~/.config/mpv/\fP\&. +.sp +Also, the old config location at \fB~/.mpv/\fP is still read, and if the XDG +variant does not exist, will still be preferred. +.SH FILES ON WINDOWS +.sp +On win32 (if compiled with MinGW, but not Cygwin), the default config file +locations are different. They are generally located under \fB%APPDATA%/mpv/\fP\&. +For example, the path to mpv.conf is \fB%APPDATA%/mpv/mpv.conf\fP, which maps to +a system and user\-specific path, for example +.INDENT 0.0 +.INDENT 3.5 +\fBC:\eusers\eUSERNAME\eAppData\eRoaming\empv\empv.conf\fP +.UNINDENT +.UNINDENT +.sp +You can find the exact path by running \fBecho %APPDATA%\empv\empv.conf\fP in cmd.exe. +.sp +Other config files (such as \fBinput.conf\fP) are in the same directory. See the +\fI\%FILES\fP section above. +.sp +The environment variable \fB$MPV_HOME\fP completely overrides these, like on +UNIX. +.sp +If a directory named \fBportable_config\fP next to the mpv.exe exists, all +config will be loaded from this directory only. Watch later config files are +written to this directory as well. (This exists on Windows only and is redundant +with \fB$MPV_HOME\fP\&. However, since Windows is very scripting unfriendly, a +wrapper script just setting \fB$MPV_HOME\fP, like you could do it on other +systems, won\(aqt work. \fBportable_config\fP is provided for convenience to get +around this restriction.) +.sp +Config files located in the same directory as \fBmpv.exe\fP are loaded with +lower priority. Some config files are loaded only once, which means that +e.g. of 2 \fBinput.conf\fP files located in two config directories, only the +one from the directory with higher priority will be loaded. +.sp +A third config directory with the lowest priority is the directory named \fBmpv\fP +in the same directory as \fBmpv.exe\fP\&. This used to be the directory with the +highest priority, but is now discouraged to use and might be removed in the +future. +.sp +Note that mpv likes to mix \fB/\fP and \fB\e\fP path separators for simplicity. +kernel32.dll accepts this, but cmd.exe does not. +.SH COPYRIGHT +GPLv2+ +.\" Generated by docutils manpage writer. +.