[crux-commits] ports/contrib (3.7): mpv: switched to current master checkout to fix build/runtime issues

commit 1813837af53e61e80eed9ba125639a231f4f5d92 Author: Tim Biermann <tbier@posteo.de> Date: Tue Nov 1 14:11:05 2022 +0000 mpv: switched to current master checkout to fix build/runtime issues diff --git a/mpv/.footprint b/mpv/.footprint index 26ca4c7e6..b59d8e25e 100644 --- a/mpv/.footprint +++ b/mpv/.footprint @@ -1,28 +1,21 @@ +drwxr-xr-x root/root etc/ +drwxr-xr-x root/root etc/mpv/ +-rw-r--r-- root/root etc/mpv/encoding-profiles.conf drwxr-xr-x root/root usr/ drwxr-xr-x root/root usr/bin/ -rwxr-xr-x root/root usr/bin/mpv -drwxr-xr-x root/root usr/etc/ -drwxr-xr-x root/root usr/etc/mpv/ --rw-r--r-- root/root usr/etc/mpv/encoding-profiles.conf -drwxr-xr-x root/root usr/include/ -drwxr-xr-x root/root usr/include/mpv/ --rw-r--r-- root/root usr/include/mpv/client.h --rw-r--r-- root/root usr/include/mpv/opengl_cb.h --rw-r--r-- root/root usr/include/mpv/render.h --rw-r--r-- root/root usr/include/mpv/render_gl.h --rw-r--r-- root/root usr/include/mpv/stream_cb.h -drwxr-xr-x root/root usr/lib/ -lrwxrwxrwx root/root usr/lib/libmpv.so -> libmpv.so.1.109.0 -lrwxrwxrwx root/root usr/lib/libmpv.so.1 -> libmpv.so.1.109.0 --rwxr-xr-x root/root usr/lib/libmpv.so.1.109.0 -drwxr-xr-x root/root usr/lib/pkgconfig/ --rw-r--r-- root/root usr/lib/pkgconfig/mpv.pc drwxr-xr-x root/root usr/share/ drwxr-xr-x root/root usr/share/applications/ -rw-r--r-- root/root usr/share/applications/mpv.desktop drwxr-xr-x root/root usr/share/bash-completion/ drwxr-xr-x root/root usr/share/bash-completion/completions/ -rw-r--r-- root/root usr/share/bash-completion/completions/mpv +drwxr-xr-x root/root usr/share/doc/ +drwxr-xr-x root/root usr/share/doc/mpv/ +-rw-r--r-- root/root usr/share/doc/mpv/input.conf +-rw-r--r-- root/root usr/share/doc/mpv/mplayer-input.conf +-rw-r--r-- root/root usr/share/doc/mpv/mpv.conf +-rw-r--r-- root/root usr/share/doc/mpv/restore-old-bindings.conf drwxr-xr-x root/root usr/share/icons/ drwxr-xr-x root/root usr/share/icons/hicolor/ drwxr-xr-x root/root usr/share/icons/hicolor/128x128/ @@ -43,9 +36,8 @@ drwxr-xr-x root/root usr/share/icons/hicolor/scalable/apps/ drwxr-xr-x root/root usr/share/icons/hicolor/symbolic/ drwxr-xr-x root/root usr/share/icons/hicolor/symbolic/apps/ -rw-r--r-- root/root usr/share/icons/hicolor/symbolic/apps/mpv-symbolic.svg -drwxr-xr-x root/root usr/share/man/ -drwxr-xr-x root/root usr/share/man/man1/ --rw-r--r-- root/root usr/share/man/man1/mpv.1.gz +drwxr-xr-x root/root usr/share/metainfo/ +-rw-r--r-- root/root usr/share/metainfo/mpv.metainfo.xml drwxr-xr-x root/root usr/share/zsh/ drwxr-xr-x root/root usr/share/zsh/site-functions/ -rw-r--r-- root/root usr/share/zsh/site-functions/_mpv diff --git a/mpv/.signature b/mpv/.signature index c8f3e980d..401af7039 100644 --- a/mpv/.signature +++ b/mpv/.signature @@ -1,7 +1,5 @@ untrusted comment: verify with /etc/ports/contrib.pub -RWSagIOpLGJF37D7C1RHKhfYX1RZIDcCKhvXe8fwrE49ORyy9kAVoTYqWoBH82tR8ukfincjC0rRn6S21NeDC9WagsL6Fq+/rgs= -SHA256 (Pkgfile) = e0eff13ae4c9623514c1296539418e257a42f01ea4161eb33fc586cda024df7a -SHA256 (.footprint) = f14555b474f5c94353678e03ba77450f3c745c12b1786ae3740039d17fa35bcd -SHA256 (mpv-v0.34.1.tar.gz) = 32ded8c13b6398310fa27767378193dc1db6d78b006b70dbcbd3123a1445e746 -SHA256 (waf-2.0.9) = 2a8e0816f023995e557f79ea8940d322bec18f286917c8f9a6fa2dc3875dfa48 -SHA256 (mpv.1) = eedccbc958ac9f8d95b2973a6a7452680ee99503c8c87d8221fe0581d95ae592 +RWSagIOpLGJF3x0jARRjITc8RFds9hx8/9amfL7bdNxYy0+eyKoW3qOFH7a+tBKcGd3N3UxbsldVOXNR1DOTUboed24rmy5rSAY= +SHA256 (Pkgfile) = 3a1776f11780ee522153e215eed648f2f27ff9ff4add41767a4d239249728402 +SHA256 (.footprint) = 7b618425e174a11bfbe920d45e584211150b692f5a17f09839ab2ff8e7ce4d03 +SHA256 (mpv-v0.34.1-4.tar.gz) = 041ed375835ab38f4a73d99f5bc7419cba402cab13cc18b834994969ea4a932f diff --git a/mpv/Pkgfile b/mpv/Pkgfile index 8451fe3b6..c0c13c9e1 100644 --- a/mpv/Pkgfile +++ b/mpv/Pkgfile @@ -6,28 +6,18 @@ name=mpv version=0.34.1 -release=2 -source=(https://github.com/$name-player/$name/archive/v$version/$name-v$version.tar.... - https://waf.io/waf-2.0.9 - mpv.1) +release=4 +_commit=d3a28f12c9ced29982fc831722075bd0c73fb821 +source=(https://github.com/mpv-player/mpv/archive/$_commit/$name-v$version-$release....) build() { - cd $name-$version + meson setup $name-$_commit build \ + --prefix=/usr \ + --buildtype=plain \ + --wrap-mode nodownload \ + -D b_lto=true \ + -D b_pie=true - install -m0755 $SRC/waf-2.0.9 waf - - [[ -e '/usr/lib/pkgconfig/libcdio_cdda.pc' ]] && PKGMK_MPV+=' --enable-cdda' - [[ -e '/usr/lib/pkgconfig/dvdnav.pc' ]] && PKGMK_MPV+=' --enable-dvdnav' - - /usr/bin/python3 waf configure ${PKGMK_MPV} \ - --prefix=/usr \ - --enable-libarchive \ - --enable-libmpv-shared \ - -j ${JOBS-1} - - /usr/bin/python3 waf build - /usr/bin/python3 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 + meson compile -C build + DESTDIR=$PKG meson install -C build } diff --git a/mpv/mpv.1 b/mpv/mpv.1 deleted file mode 100644 index 9d1cda3ed..000000000 --- a/mpv/mpv.1 +++ /dev/null @@ -1,19522 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.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 -.. -.TH "MPV" 1 "" "" "multimedia" -.SH NAME -mpv \- a media player -.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. -.sp -See also \fB\-\-input\-test\fP for interactive binding details by key, and the -\fI\%stats\fP built\-in script for key bindings list (including print to terminal). -.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 Shift+g and Shift+f -Adjust subtitle font size by +/\- 10%. -.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. -.TP -.B del -Cycle OSC visibility between never / auto (mouse\-move) / always -.TP -.B \(ga -Show the console. (ESC closes it again. See \fI\%CONSOLE\fP\&.) -.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 macOS) -Resize video window to half its original size. -.TP -.B Alt+1 (and command+1 on macOS) -Resize video window to its original size. -.TP -.B Alt+2 (and command+2 on macOS) -Resize video window to double its original size. -.TP -.B command + f (macOS 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 Left double click -Toggle fullscreen on/off. -.TP -.B Right click -Toggle pause on/off. -.TP -.B Forward/Back button -Skip to next/previous entry in playlist. -.TP -.B Wheel up/down -Seek forward/backward 10 seconds. -.TP -.B Wheel left/right -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 -Until mpv 0.31.0, there was no difference whether an option started with \fB\-\-\fP -or a single \fB\-\fP\&. Newer mpv releases strictly expect that you pass the option -value after a \fB=\fP\&. For example, before \fBmpv \-\-log\-file f.txt\fP would write -a log to \fBf.txt\fP, but now this command line fails, as \fB\-\-log\-file\fP expects -an option value, and \fBf.txt\fP is simply considered a normal file to be played -(as in \fBmpv f.txt\fP). -.sp -The future plan is that \fB\-option value\fP will not work anymore, and options -with a single \fB\-\fP behave the same as \fB\-\-\fP options. -.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 -Note: where applicable with JSON\-IPC, \fB%n%\fP is the length in UTF\-8 bytes, -after decoding the JSON data. -.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~~home/\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.) The following paths are currently recognized: -.TS -center; -|l|l|. -_ -T{ -Name -T} T{ -Meaning -T} -_ -T{ -\fB~~/\fP -T} T{ -If the subpath exists in any of the mpv\(aqs config directories -the path of the existing file/dir is returned. Otherwise this -is equivalent to \fB~~home/\fP\&. -Note that if \-\-no\-config is used \fB~~/foobar\fP will resolve to -\fBfoobar\fP which can be unexpected. -T} -_ -T{ -\fB~/\fP -T} T{ -user home directory root (similar to shell, \fB$HOME\fP) -T} -_ -T{ -\fB~~home/\fP -T} T{ -mpv config dir (for example \fB~/.config/mpv/\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 macOS bundle resource path (macOS only) -T} -_ -T{ -\fB~~desktop/\fP -T} T{ -the path to the desktop (win32, macOS) -T} -_ -T{ -\fB~~exe_dir/\fP -T} T{ -win32 only: the path to the directory containing the exe (for -config file purposes; \fB$MPV_HOME\fP overrides it) -T} -_ -T{ -\fB~~old_home/\fP -T} T{ -do not use -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, the \fB\-\-display\-tags\fP option takes a \fB,\fP\-separated list of tags, but -the option also allows you to append a single tag with \fB\-\-display\-tags\-append\fP, -and the tag name can for example contain a literal \fB,\fP without the need for -escaping. -.SS String list and path list options -.sp -String lists are separated by \fB,\fP\&. The strings are not parsed or interpreted -by the option system itself. However, most -.sp -Path or file list options use \fB:\fP (Unix) or \fB;\fP (Windows) as separator, -instead of \fB,\fP\&. -.sp -They support the following operations: -.TS -center; -|l|l|. -_ -T{ -Suffix -T} T{ -Meaning -T} -_ -T{ -\-set -T} T{ -Set a list of items (using the list separator, escaped with backslash) -T} -_ -T{ -\-append -T} T{ -Append single item (does not interpret escapes) -T} -_ -T{ -\-add -T} T{ -Append 1 or more items (same syntax as \-set) -T} -_ -T{ -\-pre -T} T{ -Prepend 1 or more items (same syntax as \-set) -T} -_ -T{ -\-clr -T} T{ -Clear the option (remove all items) -T} -_ -T{ -\-remove -T} T{ -Delete item if present (does not interpret escapes) -T} -_ -T{ -\-del -T} T{ -Delete 1 or more items by integer index (deprecated) -T} -_ -T{ -\-toggle -T} T{ -Append an item, or remove if if it already exists (no escapes) -T} -_ -.TE -.sp -\fB\-append\fP is meant as a simple way to append a single item without having -to escape the argument (you may still need to escape on the shell level). -.SS Key/value list options -.sp -A key/value list is a list of key/value string pairs. In programming languages, -this type of data structure is often called a map or a dictionary. The order -normally does not matter, although in some cases the order might matter. -.sp -They support the following operations: -.TS -center; -|l|l|. -_ -T{ -Suffix -T} T{ -Meaning -T} -_ -T{ -\-set -T} T{ -Set a list of items (using \fB,\fP as separator) -T} -_ -T{ -\-append -T} T{ -Append a single item (escapes for the key, no escapes for the value) -T} -_ -T{ -\-add -T} T{ -Append 1 or more items (same syntax as \-set) -T} -_ -T{ -\-remove -T} T{ -Delete item by key if present (does not interpret escapes) -T} -_ -.TE -.sp -Keys are unique within the list. If an already present key is set, the existing -key is removed before the new value is appended. -.sp -If you want to pass a value without interpreting it for escapes or \fB,\fP, it is -recommended to use the \fB\-add\fP variant. When using libmpv, prefer using -\fBMPV_FORMAT_NODE_MAP\fP; when using a scripting backend or the JSON IPC, use an -appropriate structured data type. -.sp -Prior to mpv 0.33, \fB:\fP was also recognized as separator by \fB\-set\fP\&. -.SS Filter options -.sp -This is a very complex option type for the \fB\-\-af\fP and \fB\-\-vf\fP options only. -They often require complicated escaping. See \fI\%VIDEO FILTERS\fP for details. They -support the following operations: -.TS -center; -|l|l|. -_ -T{ -Suffix -T} T{ -Meaning -T} -_ -T{ -\-set -T} T{ -Set a list of filters (using \fB,\fP as separator) -T} -_ -T{ -\-append -T} T{ -Append single filter -T} -_ -T{ -\-add -T} T{ -Append 1 or more filters (same syntax as \-set) -T} -_ -T{ -\-pre -T} T{ -Prepend 1 or more filters (same syntax as \-set) -T} -_ -T{ -\-clr -T} T{ -Clear the option (remove all filters) -T} -_ -T{ -\-remove -T} T{ -Delete filter if present -T} -_ -T{ -\-del -T} T{ -Delete 1 or more filters by integer index or filter label (deprecated) -T} -_ -T{ -\-toggle -T} T{ -Append a filter, or remove if if it already exists -T} -_ -T{ -\-help -T} T{ -Pseudo operation that prints a help text to the terminal -T} -_ -.TE -.SS General -.sp -Without suffix, the operation used is normally \fB\-set\fP\&. -.sp -Although some operations allow specifying multiple items, using this is strongly -discouraged and deprecated, except for \fB\-set\fP\&. There is a chance that -operations like \fB\-add\fP and \fB\-pre\fP will work like \fB\-append\fP and accept a -single, unescaped item only (so the \fB,\fP separator will not be interpreted and -is passed on as part of the value). -.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 -Options of this type can be changed at runtime using the \fBchange\-list\fP -command, which takes the suffix (without the \fB\-\fP) as separate operation -parameter. -.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: -term\-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 Runtime profiles -.sp -Profiles can be set at runtime with \fBapply\-profile\fP command. Since this -operation is "destructive" (every item in a profile is simply set as an -option, overwriting the previous value), you can\(aqt just enable and disable -profiles again. -.sp -As a partial remedy, there is a way to make profiles save old option values -before overwriting them with the profile values, and then restoring the old -values at a later point using \fBapply\-profile <profile\-name> restore\fP\&. -.sp -This can be enabled with the \fBprofile\-restore\fP option, which takes one of -the following options: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.TP -.B \fBdefault\fP -Does nothing, and nothing can be restored (default). -.TP -.B \fBcopy\fP -When applying a profile, copy the old values of all profile options to a -backup before setting them from the profile. These options are reset to -their old values using the backup when restoring. -.sp -Every profile has its own list of backed up values. If the backup -already exists (e.g. if \fBapply\-profile name\fP was called more than -once in a row), the existing backup is no changed. The restore operation -will remove the backup. -.sp -It\(aqs important to know that restoring does not "undo" setting an option, -but simply copies the old option value. Consider for example \fBvf\-add\fP, -appends an entry to \fBvf\fP\&. This mechanism will simply copy the entire -\fBvf\fP list, and does _not_ execute the inverse of \fBvf\-add\fP (that -would be \fBvf\-remove\fP) on restoring. -.sp -Note that if a profile contains recursive profiles (via the \fBprofile\fP -option), the options in these recursive profiles are treated as if they -were part of this profile. The referenced profile\(aqs backup list is not -used when creating or using the backup. Restoring a profile does not -restore referenced profiles, only the options of referenced profiles (as -if they were part of the main profile). -.TP -.B \fBcopy\-equal\fP -Similar to \fBcopy\fP, but restore an option only if it has the same value -as the value effectively set by the profile. This tries to deal with -the situation when the user does not want the option to be reset after -interactively changing it. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.INDENT 3.5 -.IP "Example" -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[something] -profile\-restore=copy\-equal -vf\-add=rotate=90 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Then running these commands will result in behavior as commented: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -set vf vflip -apply\-profile something -vf\-add=hflip -apply\-profile something -# vf == vflip,rotate=90,hflip,rotate=90 -apply\-profile something restore -# vf == vflip -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.SS Conditional auto profiles -.sp -Profiles which have the \fBprofile\-cond\fP option set are applied automatically -if the associated condition matches (unless auto profiles are disabled). The -option takes a string, which is interpreted as Lua condition. If evaluating the -expression returns true, the profile is applied, if it returns false, it is -ignored. This Lua code execution is not sandboxed. -.sp -Any variables in condition expressions can reference properties. If an -identifier is not already defined by Lua or mpv, it is interpreted as property. -For example, \fBpause\fP would return the current pause status. You cannot -reference properties with \fB\-\fP this way since that would denote a subtraction, -but if the variable name contains any \fB_\fP characters, they are turned into -\fB\-\fP\&. For example, \fBplayback_time\fP would return the property -\fBplayback\-time\fP\&. -.sp -A more robust way to access properties is using \fBp.property_name\fP or -\fBget("property\-name", default_value)\fP\&. The automatic variable to property -magic will break if a new identifier with the same name is introduced (for -example, if a function named \fBpause()\fP were added, \fBpause\fP would return a -function value instead of the value of the \fBpause\fP property). -.sp -Note that if a property is not available, it will return \fBnil\fP, which can -cause errors if used in expressions. These are logged in verbose mode, and the -expression is considered to be false. -.sp -Whenever a property referenced by a profile condition changes, the condition -is re\-evaluated. If the return value of the condition changes from false or -error to true, the profile is applied. -.sp -This mechanism tries to "unapply" profiles once the condition changes from true -to false. If you want to use this, you need to set \fBprofile\-restore\fP for the -profile. Another possibility it to create another profile with an inverse -condition to undo the other profile. -.sp -Recursive profiles can be used. But it is discouraged to reference other -conditional profiles in a conditional profile, since this can lead to tricky -and unintuitive behavior. -.INDENT 0.0 -.INDENT 3.5 -.IP "Example" -.sp -Make only HD video look funny: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[something] -profile\-desc=HD video sucks -profile\-cond=width >= 1280 -hue=\-50 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -If you want the profile to be reverted if the condition goes to false again, -you can set \fBprofile\-restore\fP: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[something] -profile\-desc=Mess up video when entering fullscreen -profile\-cond=fullscreen -profile\-restore=copy -vf\-add=rotate=90 -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This appends the \fBrotate\fP filter to the video filter chain when entering -fullscreen. When leaving fullscreen, the \fBvf\fP option is set to the value -it had before entering fullscreen. Note that this would also remove any -other filters that were added during fullscreen mode by the user. Avoiding -this is trickier, and could for example be solved by adding a second profile -with an inverse condition and operation: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[something] -profile\-cond=fullscreen -vf\-add=@rot:rotate=90 - -[something\-inv] -profile\-cond=not fullscreen -vf\-remove=@rot -.ft P -.fi -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -Every time an involved property changes, the condition is evaluated again. -If your condition uses \fBp.playback_time\fP for example, the condition is -re\-evaluated approximately on every video frame. This is probably slow. -.UNINDENT -.UNINDENT -.sp -This feature is managed by an internal Lua script. Conditions are executed as -Lua code within this script. Its environment contains at least the following -things: -.INDENT 0.0 -.TP -.B \fB(function environment table)\fP -Every Lua function has an environment table. This is used for identifier -access. There is no named Lua symbol for it; it is implicit. -.sp -The environment does "magic" accesses to mpv properties. If an identifier -is not already defined in \fB_G\fP, it retrieves the mpv property of the same -name. Any occurrences of \fB_\fP in the name are replaced with \fB\-\fP before -reading the property. The returned value is as retrieved by -\fBmp.get_property_native(name)\fP\&. Internally, a cache of property values, -updated by observing the property is used instead, so properties that are -not observable will be stuck at the initial value forever. -.sp -If you want to access properties, that actually contain \fB_\fP in the name, -use \fBget()\fP (which does not perform transliteration). -.sp -Internally, the environment table has a \fB__index\fP meta method set, which -performs the access logic. -.TP -.B \fBp\fP -A "magic" table similar to the environment table. Unlike the latter, this -does not prefer accessing variables defined in \fB_G\fP \- it always accesses -properties. -.TP -.B \fBget(name [, def])\fP -Read a property and return its value. If the property value is \fBnil\fP (e.g. -if the property does not exist), \fBdef\fP is returned. -.sp -This is superficially similar to \fBmp.get_property_native(name)\fP\&. An -important difference is that this accesses the property cache, and enables -the change detection logic (which is essential to the dynamic runtime -behavior of auto profiles). Also, it does not return an error value as -second return value. -.sp -The "magic" tables mentioned above use this function as backend. It does not -perform the \fB_\fP transliteration. -.UNINDENT -.sp -In addition, the same environment as in a blank mpv Lua script is present. For -example, \fBmath\fP is defined and gives access to the Lua standard math library. -.sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -This feature is subject to change indefinitely. You might be forced to -adjust your profiles on mpv updates. -.UNINDENT -.UNINDENT -.SS Legacy auto profiles -.sp -Some profiles are loaded automatically using a legacy mechanism. 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 -[extension.mkv] -profile\-desc="profile for .mkv files" -vf=vflip -.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 is considered soft\-deprecated. Use conditional -auto profiles. -.SH USING MPV FROM OTHER PROGRAMS OR SCRIPTS -.sp -There are three choices for using mpv from other programs or scripts: -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP 1. 3 -Calling it as UNIX process. If you do this, \fIdo not parse terminal output\fP\&. -The terminal output is intended for humans, and may change any time. In -addition, terminal behavior itself may change any time. Compatibility -cannot be guaranteed. -.sp -Your code should work even if you pass \fB\-\-no\-terminal\fP\&. Do not attempt -to simulate user input by sending terminal control codes to mpv\(aqs stdin. -If you need interactive control, using \fB\-\-input\-ipc\-server\fP is -recommended. This gives you access to the \fI\%JSON IPC\fP over unix domain -sockets (or named pipes on Windows). -.sp -Depending on what you do, passing \fB\-\-no\-config\fP or \fB\-\-config\-dir\fP may -be a good idea to avoid conflicts with the normal mpv user configuration -intended for CLI playback. -.sp -Using \fB\-\-input\-ipc\-server\fP is also suitable for purposes like remote -control (however, the IPC protocol itself is not "secure" and not -intended to be so). -.IP 2. 3 -Using libmpv. This is generally recommended when mpv is used as playback -backend for a completely different application. The provided C API is -very close to CLI mechanisms and the scripting API. -.sp -Note that even though libmpv has different defaults, it can be configured -to work exactly like the CLI player (except command line parsing is -unavailable). -.sp -See \fI\%EMBEDDING INTO OTHER PROGRAMS (LIBMPV)\fP\&. -.IP 3. 3 -As a user script (\fI\%LUA SCRIPTING\fP, \fI\%JAVASCRIPT\fP, \fI\%C PLUGINS\fP). This is -recommended when the goal is to "enhance" the CLI player. Scripts get -access to the entire client API of mpv. -.sp -This is the standard way to create third\-party extensions for the player. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -All these access the client API, which is the sum of the various mechanisms -provided by the player core, as documented here: \fI\%OPTIONS\fP, -\fI\%List of Input Commands\fP, \fI\%Properties\fP, \fI\%List of events\fP (also see C API), -\fI\%Hooks\fP\&. -.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) (\fBduration\fP property) -.IP \(bu 2 -Playback speed, e.g. \fBx2.0\fP\&. 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. (\fBframe\-drop\-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. -(\fBdecoder\-frame\-drop\-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 only looks at http(s) 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. (Requires FFmpeg support.) -.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][/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. Without \fB\-\-dvd\-device\fP, it will probably try -to open an actual optical drive, if available and implemented for the OS. -.sp -\fBdvdnav://\fP is an old alias for \fBdvd://\fP and does exactly the same -thing. -.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. -.INDENT 0.0 -.INDENT 3.5 -.IP "Example" -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mpv av://v4l2:/dev/video0 \-\-profile=low\-latency \-\-untimed -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This plays video from the first v4l input with nearly the lowest latency -possible. It\(aqs a good replacement for the removed \fBtv://\fP input. -Using \fB\-\-untimed\fP is a hack to output a captured frame immediately, -instead of respecting the input framerate. (There may be better ways to -handle this in the future.) -.UNINDENT -.UNINDENT -.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 -\fBslice://start[\-end]@URL\fP -.INDENT 0.0 -.INDENT 3.5 -Read a slice of a stream. -.sp -\fBstart\fP and \fBend\fP represent a byte range and accept -suffixes such as \fBKiB\fP and \fBMiB\fP\&. \fBend\fP is optional. -.sp -if \fBend\fP starts with \fB+\fP, it is considered as offset from \fBstart\fP\&. -.sp -Only works with seekable streams. -.sp -Examples: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -mpv slice://1g\-2g@cap.ts - -This starts reading from cap.ts after seeking 1 GiB, then -reads until reaching 2 GiB or end of file. - -mpv slice://1g\-+2g@cap.ts - -This starts reading from cap.ts after seeking 1 GiB, then -reads until reaching 3 GiB or end of file. - -mpv slice://100m@appending://cap.ts - -This starts reading from cap.ts after seeking 100MiB, then -reads until end of file. -.ft P -.fi -.UNINDENT -.UNINDENT -.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 macOS -.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, -which is the main difference to using \fB\-\-profile=builtin\-pseudo\-gui\fP\&. -.sp -The profile is 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/ -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The \fBpseudo\-gui\fP profile exists for compatibility. 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: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -[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 LINUX DESKTOP ISSUES -.sp -This subsection describes common problems on the Linux desktop. None of these -problems exist on systems like Windows or macOS. -.SS Disabling Screensaver -.sp -By default, mpv tries to disable the OS screensaver during playback (only if -a VO using the OS GUI API is active). \fB\-\-stop\-screensaver=no\fP disables this. -.sp -A common problem is that Linux desktop environments ignore the standard -screensaver APIs on which mpv relies. In particular, mpv uses the Screen Saver -extension (XSS) on X11, and the idle\-inhibit on Wayland. -.sp -GNOME is one of the worst offenders, and ignores even the now widely supported -idle\-inhibit protocol. (This is either due to a combination of malice and -incompetence, but since implementing this protocol would only take a few lines -of code, it is most likely the former. You will also notice how GNOME advocates -react offended whenever their sabotage is pointed out, which indicates either -hypocrisy, or even worse ignorance.) -.sp -Such incompatible desktop environments (i.e. which ignore standards) typically -require using a DBus API. This is ridiculous in several ways. The immediate -practical problem is that it would require adding a quite unwieldy dependency -for a DBus library, somehow integrating its mainloop into mpv, and other -generally unacceptable things. -.sp -However, since mpv does not officially support GNOME, this is not much of a -problem. If you are one of those miserable users who want to use mpv on GNOME, -report a bug on the GNOME issue tracker: -\fI\%https://gitlab.gnome.org/groups/GNOME/\-/issues\fP -.sp -Alternatively, you may be able to write a Lua script that calls the -\fBxdg\-screensaver\fP command line program. (By the way, this a command line -program is an utterly horrible kludge that tries to identify your DE, and then -tries to send the correct DBus command via a DBus CLI tool.) If you find the -idea of having to write a script just so your screensaver doesn\(aqt kick in -ridiculous, do not use GNOME, or use GNOME video software instead of mpv (good -luck). -.sp -Before mpv 0.33.0, the X11 backend ran \fBxdg\-screensaver reset\fP in 10 second -intervals when not paused. This hack was removed in 0.33.0. -.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\&. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.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\&. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.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. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.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.) -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -The track selection options (\fB\-\-aid\fP but also \fB\-\-sid\fP and the -others) sometimes expose behavior that may appear strange. Also, the -behavior tends to change around with each mpv release. -.sp -The track selection properties will return the option value outside of -playback (as expected), but during playback, the affective track -selection is returned. For example, with \fB\-\-aid=auto\fP, the \fBaid\fP -property will suddenly return \fB2\fP after playback initialization -(assuming the file has at least 2 audio tracks, and the second is the -default). -.sp -At mpv 0.32.0 (and some releases before), if you passed a track value -for which a corresponding track didn\(aqt exist (e.g. \fB\-\-aid=2\fP and there -was only 1 audio track), the \fBaid\fP property returned \fBno\fP\&. However if -another audio track was added during playback, and you tried to set the -\fBaid\fP property to \fB2\fP, nothing happened, because the \fBaid\fP option -still had the value \fB2\fP, and writing the same value has no effect. -.sp -With mpv 0.33.0, the behavior was changed. Now track selection options -are reset to \fBauto\fP at playback initialization, if the option had -tries to select a track that does not exist. The same is done if the -track exists, but fails to initialize. The consequence is that unlike -before mpv 0.33.0, the user\(aqs track selection parameters are clobbered -in certain situations. -.sp -Also since mpv 0.33.0, trying to select a track by number will strictly -select this track. Before this change, trying to select a track which -did not exist would fall back to track default selection at playback -initialization. The new behavior is more consistent. -.sp -Setting a track selection property at runtime, and then playing a new -file might reset the track selection to defaults, if the fingerprint -of the track list of the new file is different. -.sp -Be aware of tricky combinations of all of all of the above: for example, -\fBmpv \-\-aid=2 file_with_2_audio_tracks.mkv file_with_1_audio_track.mkv\fP -would first play the correct track, and the second file without audio. -If you then go back the first file, its first audio track will be played, -and the second file is played with audio. If you do the same thing again -but instead of using \fB\-\-aid=2\fP you run \fBset aid 2\fP while the file is -playing, then changing to the second file will play its audio track. -This is because runtime selection enables the fingerprint heuristic. -.sp -Most likely this is not the end. -.UNINDENT -.UNINDENT -.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. -.TP -.B \fB\-\-subs\-with\-matching\-audio=<yes|no>\fP -When autoselecting a subtitle track, select a non\-forced one even if the selected -audio stream matches your preferred subtitle language (default: yes). Disable this -if you\(aqd like to only show subtitles for foreign audio or onscreen text. -.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 \fBscaletempo2\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. You may need this option to load plaintext files as -a playlist. Note that XML playlist formats are not supported. -.sp -This option forces \fB\-\-demuxer=playlist\fP to interpret the playlist file. -Some playlist formats, notably CUE and optical disc formats, need to use -different demuxers and will not work with this option. They still can be -played directly, without using this option. -.sp -You can play playlists directly, without this option. Before mpv version -0.31.0, this option disabled any security mechanisms that might be in -place, but since 0.31.0 it uses the same security mechanisms as playing a -playlist file directly. If you trust the playlist file, you can disable -any security checks with \fB\-\-load\-unsafe\-playlists\fP\&. Because playlists -can load other playlist entries, consider applying this option only to the -playlist itself and not its entries, using something along these lines: -.INDENT 7.0 -.INDENT 3.5 -\fBmpv \-\-{ \-\-playlist=filename \-\-load\-unsafe\-playlists \-\-}\fP -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -The way older versions of mpv played playlist files via \fB\-\-playlist\fP -was not safe against maliciously constructed files. Such files may -trigger harmful actions. This has been the case for all verions of -mpv prior to 0.31.0, and all MPlayer versions, but unfortunately this -fact was not well documented earlier, and some people have even -misguidedly recommended the use of \fB\-\-playlist\fP with untrusted -sources. Do NOT use \fB\-\-playlist\fP with random internet sources or -files you do not trust if you are not sure your mpv is at least 0.31.0. -.sp -In particular, playlists can contain entries using protocols other than -local files, such as 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|default>\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 default -Like \fBabsolute\fP, but enable hr\-seeks in audio\-only cases. The -exact behavior is implementation specific and may change with -new releases. -.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.) -.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 -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -\fB\-\-loop\-file\fP counts the number of times it causes the player to -seek to the beginning of the file, not the number of full playthroughs. This -means \fB\-\-loop\-file=1\fP will end up playing the file twice. Contrast with -\fB\-\-loop\-playlist\fP, which counts the number of full playthroughs. -.UNINDENT -.UNINDENT -.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\-\-ab\-loop\-count=<N|inf>\fP -Run A\-B loops only N times, then ignore the A\-B loop points (default: inf). -Every finished loop iteration will decrement this option by 1 (unless it is -set to \fBinf\fP or 0). \fBinf\fP means that looping goes on forever. If this -option is set to 0, A\-B looping is ignored, and even the \fBab\-loop\fP command -will not enable looping again (the command will show \fB(disabled)\fP on the -OSD message if both loop points are set, but \fBab\-loop\-count\fP is 0). -.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\-\-cache=yes\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 -Setting \fB\-\-vd\-queue\-enable=yes\fP can help a lot to make playback smooth -(once it works). -.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). -.sp -A special case is the macOS bundle, it will create a log file at -\fB~/Library/Logs/mpv.log\fP by default. -.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). -.sp -\fB\-\-scripts\fP is a path list option. See \fI\%List Options\fP for details. -.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. -.sp -This is a key/value list option. See \fI\%List Options\fP for details. -.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\-\-resume\-playback\-check\-mtime\fP -Only restore the playback position from the \fBwatch_later\fP configuration -subdirectory (usually \fB~/.config/mpv/watch_later/\fP) if the file\(aqs -modification time is the same as at the time of saving. This may prevent -skipping forward in files with the same name which have different content. -(Default: \fBno\fP) -.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. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.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\-\-watch\-later\-options=option1,option2,...\fP -The options that are saved in "watch later" files if they have been changed -since when mpv started. These values will be restored the next time the -files are played. The playback position is always saved as \fBstart\fP, so -adding \fBstart\fP to this list has no effect. -.sp -When removing options, existing watch later data won\(aqt be modified and will -still be applied fully, but new watch later data won\(aqt contain these -options. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.INDENT 7.0 -.INDENT 3.5 -.IP "Examples" -.INDENT 0.0 -.IP \(bu 2 -\fB\-\-watch\-later\-options\-remove=fullscreen\fP -The fullscreen state won\(aqt be saved to watch later files. -.IP \(bu 2 -\fB\-\-watch\-later\-options\-remove=volume\fP -\fB\-\-watch\-later\-options\-remove=mute\fP -The volume and mute state won\(aqt be saved to watch later files. -.IP \(bu 2 -\fB\-\-watch\-later\-options\-clr\fP -No option will be saved to watch later files except the starting -position. -.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. Lists all profiles if no -parameter is provided. -.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 -This accepts a set of options, which can be passed to it with the -\fB\-\-script\-opts\fP option (using \fBytdl_hook\-\fP as prefix): -.INDENT 7.0 -.TP -.B \fBtry_ytdl_first=<yes|no>\fP -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. -.TP -.B \fBexclude=<URL1|URL2|...\fP -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 -.TP -.B \fBall_formats=<yes|no>\fP -If \(aqyes\(aq will attempt to add all formats found reported by youtube\-dl -(default: no). Each format is added as a separate track. In addition, -they are delay\-loaded, and actually opened only when a track is selected -(this should keep load times as low as without this option). -.sp -It adds average bitrate metadata, if available, which means you can use -\fB\-\-hls\-bitrate\fP to decide which track to select. (HLS used to be the -only format whose alternative quality streams were exposed in a similar -way, thus the option name.) -.sp -Tracks which represent formats that were selected by youtube\-dl as -default will have the default flag set. This means mpv should generally -still select formats chosen with \fB\-\-ytdl\-format\fP by default. -.sp -Although this mechanism makes it possible to switch streams at runtime, -it\(aqs not suitable for this purpose for various technical reasons. (It\(aqs -slow, which can\(aqt be really fixed.) In general, this option is not -useful, and was only added to show that it\(aqs possible. -.sp -There are two cases that must be considered when doing quality/bandwidth -selection: -.INDENT 7.0 -.INDENT 3.5 -.INDENT 0.0 -.IP 1. 3 -Completely separate audio and video streams (DASH\-like). Each of -these streams contain either only audio or video, so you can -mix and combine audio/video bandwidths without restriction. This -intuitively matches best with the concept of selecting quality -by track (what \fBall_formats\fP is supposed to do). -.IP 2. 3 -Separate sets of muxed audio and video streams. Each version of -the media contains both an audio and video stream, and they are -interleaved. In order not to waste bandwidth, you should only -select one of these versions (if, for example, you select an -audio stream, then video will be downloaded, even if you selected -video from a different stream). -.sp -mpv will still represent them as separate tracks, but will set -the title of each track to \fBmuxed\-N\fP, where \fBN\fP is replaced -with the youtube\-dl format ID of the originating stream. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -Some sites will mix 1. and 2., but we assume that they do so for -compatibility reasons, and there is no reason to use them at all. -.TP -.B \fBforce_all_formats=<yes|no>\fP -If set to \(aqyes\(aq, and \fBall_formats\fP is also set to \(aqyes\(aq, this will -try to represent all youtube\-dl reported formats as tracks, even if -mpv would normally use the direct URL reported by it (default: yes). -.sp -It appears this normally makes a difference if youtube\-dl works on a -master HLS playlist. -.sp -If this is set to \(aqno\(aq, this specific kind of stream is treated like -\fBall_formats\fP is set to \(aqno\(aq, and the stream selection as done by -youtube\-dl (via \fB\-\-ytdl\-format\fP) is used. -.TP -.B \fBuse_manifests=<yes|no>\fP -Make mpv use the master manifest URL for formats like HLS and DASH, -if available, allowing for video/audio selection in runtime (default: -no). It\(aqs disabled ("no") by default for performance reasons. -.TP -.B \fBytdl_path=youtube\-dl\fP -Configure paths to youtube\-dl\(aqs executable or a compatible fork\(aqs. The -paths should be separated by : on Unix and ; on Windows. mpv looks in -order for the configured paths in PATH and in mpv\(aqs config directory. -The defaults are "yt\-dlp", "yt\-dlp_x86" and "youtube\-dl". On Windows -the suffix extension ".exe" is always appended. -.UNINDENT -.INDENT 7.0 -.INDENT 3.5 -.IP "Why do the option names mix \fB_\fP and \fB\-\fP?" -.sp -I have no idea. -.UNINDENT -.UNINDENT -.TP -.B \fB\-\-ytdl\-format=<ytdl|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: \fBbestvideo+bestaudio/best\fP) -.sp -The \fBytdl\fP value does not pass a \fB\-\-format\fP option to youtube\-dl at all, -and thus does not override its default. Note that sometimes youtube\-dl -returns a format that mpv cannot use, and in these cases the mpv default -may work better. -.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. -.sp -This is a key/value list option. See \fI\%List Options\fP for details. -.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\-\-load\-osd\-console=<yes|no>\fP -Enable the builtin script that shows a console on a key binding and lets -you enter commands (default: yes). By default,. The \fB\'\fP key is used to -show the console, and \fBESC\fP to hide it again. (This is based on a user -script called \fBrepl.lua\fP\&.) -.TP -.B \fB\-\-load\-auto\-profiles=<yes|no|auto>\fP -Enable the builtin script that does auto profiles (default: auto). See -\fI\%Conditional auto profiles\fP for details. \fBauto\fP will load the script, -but immediately unload it if there are no conditional profiles. -.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. See \fI\%PSEUDO GUI MODE\fP for details. -.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 frame dropping. Not recommended, for testing only. -.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. Drops are -indicated in the terminal status line as \fBDropped:\fP field. -.sp -In audio sync. mode, this drops frames that are outdated at the time of -display. 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. -.sp -In display\-sync. modes (see \fB\-\-video\-sync\fP), this affects only how -A/V drops or repeats frames. If this mode is disabled, A/V desync will -in theory not affect video scheduling anymore (much like the -\fBdisplay\-resample\-desync\fP mode). However, even if disabled, frames -will still be skipped (i.e. dropped) according to the ratio between -video and display frequencies. -.sp -This is the recommended mode, and the default. -.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. -.sp -This uses a heuristic which may not make sense, and in general cannot -achieve good results, because the decoder\(aqs frame dropping cannot be -controlled in a predictable manner. Not recommended. -.sp -Even if you want to use this, prefer \fBdecoder+vo\fP for better results. -.sp -The \fB\-\-vd\-lavc\-framedrop\fP option controls what frames to drop. -.TP -.B <decoder+vo> -Enable both modes. Not recommended. Better than just \fBdecoder\fP mode. -.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 the -player needing 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\-\-override\-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\-\-display\-fps=<fps>\fP -Deprecated alias for \fB\-\-override\-display\-fps\fP\&. -.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 -Hardware decoding is not enabled by default, because it is typically an -additional source of errors. It is worth using only if your CPU is too -slow to decode a specific video. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Use the \fBCtrl+h\fP shortcut to toggle hardware decoding at runtime. It -toggles this option between \fBauto\fP and \fBno\fP\&. -.sp -Always enabling HW decoding by putting it into the config file is -discouraged. If you use the Ubuntu package, delete \fB/etc/mpv/mpv.conf\fP, -as the package tries to enable HW decoding by default by setting -\fBhwdec=vaapi\fP (which is less than ideal, and may even cause -sub\-optimal wrappers to be used). Or at least change it to -\fBhwdec=auto\-safe\fP\&. -.UNINDENT -.UNINDENT -.sp -Use one of the auto modes if you want to enable hardware decoding. -Explicitly selecting the mode is mostly meant for testing and debugging. -It\(aqs a bad idea to put explicit selection into the config file if you -want thing to just keep working after updates and so on. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Even if enabled, hardware decoding is still only white\-listed for some -codecs. See \fB\-\-hwdec\-codecs\fP to enable hardware decoding in more cases. -.UNINDENT -.UNINDENT -.INDENT 7.0 -.INDENT 3.5 -.IP "Which method to choose?" -.INDENT 0.0 -.IP \(bu 2 -If you only want to enable hardware decoding at runtime, don\(aqt set the -parameter, or put \fBhwdec=no\fP into your \fBmpv.conf\fP (relevant on -distros which force\-enable it by default, such as on Ubuntu). Use the -\fBCtrl+h\fP default binding to enable it at runtime. -.IP \(bu 2 -If you\(aqre not sure, but want hardware decoding always enabled by -default, put \fBhwdec=auto\-safe\fP into your \fBmpv.conf\fP, and -acknowledge that this use case is not "really" supported and may cause -problems. -.IP \(bu 2 -If you want to test available hardware decoding methods, pass -\fB\-\-hwdec=auto \-\-hwdec\-codecs=all\fP and look at the terminal output. -.IP \(bu 2 -If you\(aqre a developer, or want to perform elaborate tests, you may -need any of the other possible option values. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -\fB<api>\fP can be one of the following: -.INDENT 7.0 -.TP -.B no -always use software decoding (default) -.TP -.B auto -forcibly enable any hw decoder found (see below) -.TP -.B yes -exactly the same as \fBauto\fP -.TP -.B auto\-safe -enable any whitelisted hw decoder (see below) -.TP -.B auto\-copy -enable best hw decoder with copy\-back (see below) -.TP -.B vdpau -requires \fB\-\-vo=gpu\fP with X11, 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 (macOS 10.8 and up), -or \fB\-\-vo=libmpv\fP (iOS 9.0 and up) -.TP -.B videotoolbox\-copy -copies video back into system RAM (macOS 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 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 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 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\-safe\fP is similar to \fBauto\fP, but allows only whitelisted methods -that are considered "safe". This is supposed to be a reasonable way to -enable hardware decdoding by default in a config file (even though you -shouldn\(aqt do that anyway; prefer runtime enabling with \fBCtrl+h\fP). Unlike -\fBauto\fP, this will not try to enable unknown or known\-to\-be\-bad methods. In -addition, this may disable hardware decoding in other situations when it\(aqs -known to cause problems, but currently this mechanism is quite primitive. -(As an example for something that still causes problems: certain -combinations of HEVC and Intel chips on Windows tend to cause mpv to crash, -most likely due to driver bugs.) -.sp -\fBauto\-copy\-safe\fP selects the union of methods selected with \fBauto\-safe\fP -and \fBauto\-copy\fP\&. -.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 usually -guaranteed to incur no additional quality loss compared to software -decoding (assuming modern codecs and an error free video stream), and will -allow CPU processing with video filters. This mode works with all video -filters and VOs. -.sp -Because these copy the decoded video back to system RAM, they\(aqre often less -efficient than the direct modes, and may not help too much over software -decoding. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Most non\-copy methods only work with the OpenGL GPU backend. Currently, -only the \fBvaapi\fP, \fBnvdec\fP and \fBcuda\fP methods work with Vulkan. -.UNINDENT -.UNINDENT -.sp -The \fBvaapi\fP mode, if used with \fB\-\-vo=gpu\fP, requires Mesa 11, and most -likely works with Intel and AMD GPUs only. It also requires the opengl EGL -backend. -.sp -\fBnvdec\fP and \fBnvdec\-copy\fP are the newest, and recommended method to do -hardware decoding on Nvidia GPUs. -.sp -\fBcuda\fP and \fBcuda\-copy\fP are an older implementation of hardware decoding -on Nvidia GPUs that uses Nvidia\(aqs bitstream parsers rather than FFmpeg\(aqs. -This can lead to feature deficiencies, such as incorrect playback of HDR -content, and \fBnvdec\fP/\fBnvdec\-copy\fP should always be preferred unless you -specifically need Nvidia\(aqs deinterlacing algorithms. 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. -.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 always does RGB conversion in hardware, which does not -support newer colorspaces like BT.2020 correctly. However, \fBvdpau\fP -doesn\(aqt support 10 bit or HDR encodings, so these limitations are -unlikely to be relevant. -.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 usually be safe, but depending on how a file/stream -has been mixed, it has been reported to corrupt the timestamps causing -glitched, flashing frames. It can also sometimes cause massive -framedrops for unknown reasons. Caution is advised, and \fBnvdec\fP -should always be preferred. -.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 \fBlibmpv\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 \fBlibmpv\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, and with the \fBcuda\-copy\fP -or \fBnvdec\-copy\fP hwdecs in all cases. -.sp -For the OpenGL GPU backend, the default device used for decoding is the one -being used to provide \fBgpu\fP output (and in the vast majority of cases, -only one GPU will be present). -.sp -For the \fBcopy\fP hwdecs, the default device will be the first device -enumerated by the CUDA libraries \- however that is done. -.sp -For the Vulkan GPU backend, decoding must always happen on the display -device, and this option has no effect. -.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. 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.) -.sp -When using hardware decoding without copy\-back, only 90° steps work, while -software decoding and hardware decoding methods that copy the video back to -system memory support all values between 0 and 359. -.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\-scale\-x=<value>\fP, \fB\-\-video\-scale\-y=<value>\fP -Multiply the video display size with the given value (default: 1.0). If a -non\-default value is used, this will be different from the window size, so -video will be either cut off, or black bars are added. -.sp -This value is multiplied with the value derived from \fB\-\-video\-zoom\fP and -the normal video aspect aspect ratio. 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,vp8,vp9,av1\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\&. -.sp -Setting this to a higher number might break the playback start fallback: if -a fallback happens, parts of the file will be skipped, approximately by to -the number of packets that could not be decoded. Values below an unspecified -count will not have this problem, because mpv retains the packets. -.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\&. -.sp -This is a key/value list option. See \fI\%List Options\fP for details. -.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 \fBscaletempo2\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: no). -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. -.sp -This is a key/value list option. See \fI\%List Options\fP for details. -.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|embedded\-first|external\-first>\fP -Determines whether to display cover art when playing audio files and with -what priority. It will display the first image found, and additional images -are available as video tracks. -.INDENT 7.0 -.TP -.B no -Disable display of video entirely when playing audio -files. -.TP -.B embedded\-first -Display embedded images and external cover art, giving -priority to embedded images (default). -.TP -.B external\-first -Display embedded images and external cover art, giving -priority to external files. -.UNINDENT -.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 path 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 the 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. -.sp -This is a path list option. See \fI\%List Options\fP for details. -.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. -.INDENT 7.0 -.INDENT 3.5 -.IP "Warning" -.sp -This modifies certain subtle player behavior, like A/V\-sync and underrun -handling. Enabling this option is strongly discouraged. -.UNINDENT -.UNINDENT -.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 path 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\-150>\fP -Specify the position of subtitles on the screen. The value is the vertical -position of the subtitle in % of the screen height. 100 is the original -position, which is often not the absolute bottom of the screen, but with -some margin between the bottom and the subtitle. Values above 100 move the -subtitle further down. -.INDENT 7.0 -.INDENT 3.5 -.IP "Warning" -.sp -Text subtitles (as opposed to image subtitles) may be cut off if the -value of the option is above 100. This is a libass restriction. -.sp -This affects ASS subtitles as well, and may lead to incorrect subtitle -rendering in addition to the problem above. -.sp -Using \fB\-\-sub\-margin\-y\fP can achieve this in a better way. -.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. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.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 and possibly -language suffixes (default). -.TP -.B fuzzy -Load all subs containing the 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. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -This works for text subtitle files only. Other types of subtitles (in -particular subtitles in mkv files) are always assumed to be UTF\-8. -.UNINDENT -.UNINDENT -.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=<auto|yes|no>\fP -Display only forced subtitles for the DVD subtitle stream selected by e.g. -\fB\-\-slang\fP (default: \fBauto\fP). When set to \fBauto\fP, enabled when the -\fB\-\-subs\-with\-matching\-audio\fP option is on and a non\-forced stream is selected. -Enabling this will hide all subtitles in streams that don\(aqt make a distinction -between forced and unforced events within a stream. -.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 path 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\-\-secondary\-sub\-visibility\fP, \fB\-\-no\-secondary\-sub\-visibility\fP -Can be used to disable display of secondary subtitles, but still select and -decode them. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -If \fB\-\-sub\-visibility=no\fP, secondary subtitles are hidden regardless of -\fB\-\-secondary\-sub\-visibility\fP\&. -.UNINDENT -.UNINDENT -.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\-past\-video\-end\fP -After the last frame of video, if this option is enabled, subtitles will -continue to update based on audio timestamps. Otherwise, the subtitles -for the last video frame will stay onscreen. -.sp -Default: disabled -.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\-filter\-regex\-...=...\fP -Set a list of regular expressions to match on text subtitles, and remove any -lines that match (default: empty). This is a string list option. See -\fI\%List Options\fP for details. Normally, you should use -\fB\-\-sub\-filter\-regex\-append=<regex>\fP, where each option use will append a -new regular expression, without having to fight escaping problems. -.sp -List items are matched in order. If a regular expression matches, the -process is stopped, and the subtitle line is discarded. The text matched -against is, by default, the \fBText\fP field of ASS events (if the -subtitle format is different, it is always converted). This may include -formatting tags. Matching is case\-insensitive, but how this is done depends -on the libc, and most likely works in ASCII only. It does not work on -bitmap/image subtitles. Unavailable on inferior OSes (requires POSIX regex -support). -.INDENT 7.0 -.INDENT 3.5 -.IP "Example" -.sp -\fB\-\-sub\-filter\-regex\-append=opensubtitles\e.org\fP filters some ads. -.UNINDENT -.UNINDENT -.sp -Technically, using a list for matching is redundant, since you could just -use a single combined regular expression. But it helps with diagnosis, -ease of use, and temporarily disabling or enabling individual filters. -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -This is experimental. The semantics most likely will change, and if you -use this, you should be prepared to update the option later. Ideas -include replacing the regexes with a very primitive and small subset of -sed, or some method to control case\-sensitivity. -.UNINDENT -.UNINDENT -.TP -.B \fB\-\-sub\-filter\-jsre\-...=...\fP -Same as \fB\-\-sub\-filter\-regex\fP but with JavaScript regular expressions. -Shares/affected\-by all \fB\-\-sub\-filter\-regex\-*\fP control options (see below), -and also experimental. Requires only JavaScript support. -.TP -.B \fB\-\-sub\-filter\-regex\-plain=<yes|no>\fP -Whether to first convert the ASS "Text" field to plain\-text (default: no). -This strips ASS tags and applies ASS directives, like \fB\eN\fP to new\-line. -If the result is multi\-line then the regexp anchors \fB^\fP and \fB$\fP match -each line, but still any match discards all lines. -.TP -.B \fB\-\-sub\-filter\-regex\-warn=<yes|no>\fP -Log dropped lines with warning log level, instead of verbose (default: no). -Helpful for testing. -.TP -.B \fB\-\-sub\-filter\-regex\-enable=<yes|no>\fP -Whether to enable regex filtering (default: yes). Note that if no regexes -are added to the \fB\-\-sub\-filter\-regex\fP list, setting this option to \fByes\fP -has no effect. It\(aqs meant to easily disable or enable filtering -temporarily. -.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 -macOS, 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\-\-screen\-name=<string>\fP -In multi\-monitor configurations, this option tells mpv which screen to -display the video on based on the screen name from the video backend. The -same caveats in the \fB\-\-screen\fP option also apply here. This option is -ignored and does nothing if \fB\-\-screen\fP is explicitly set. -.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 \fBcurrent\fP is used mpv will fallback 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 (macOS)" -.sp -\fBall\fP does not work on macOS and will behave like \fBcurrent\fP\&. -.UNINDENT -.UNINDENT -.sp -See also \fB\-\-screen\fP\&. -.TP -.B \fB\-\-fs\-screen\-name=<string>\fP -In multi\-monitor configurations, this option tells mpv which screen to go -fullscreen to based on the screen name from the video backend. The same -caveats in the \fB\-\-fs\-screen\fP option also apply here. This option is -ignored and does nothing if \fB\-\-fs\-screen\fP is explicitly set. -.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|desktop|level>\fP -(macOS 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 desktop -On top of the Dekstop behind windows and Desktop icons. -.TP -.B level -A level as integer. -.UNINDENT -.TP -.B \fB\-\-focus\-on\-open\fP, \fB\-\-no\-focus\-on\-open\fP -(macOS only) -Focus the video window on creation and makes it the front most window. This -is on by default. -.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\-\-on\-all\-workspaces\fP -(X11 and macOS only) -Show the video window on all virtual desktops. -.TP -.B \fB\-\-geometry=<[W[xH]][+\-x+\-y][/WS]>\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". A trailing \fB/\fP -followed by an integer denotes on which workspace (virtual desktop) the -window should appear (X11 only). -.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 (macOS) -.\" -.\" On macOS, 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/2\fP -Sets the window to half the screen widths, and positions it 10 -pixels below/left of the top left corner of the screen, on the -second workspace. -.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\-\-window\-minimized=<yes|no>\fP -Whether the video window is minimized or not. Setting this will minimize, -or unminimize, the video window if the current VO supports it. Note that -some VOs may support minimization while not supporting unminimization -(eg: Wayland). -.sp -Whether this option and \fB\-\-window\-maximized\fP work on program start or -at runtime, and whether they\(aqre (at runtime) updated to reflect the actual -window state, heavily depends on the VO and the windowing system. Some VOs -simply do not implement them or parts of them, while other VOs may be -restricted by the windowing systems (especially Wayland). -.TP -.B \fB\-\-window\-maximized=<yes|no>\fP -Whether the video window is maximized or not. Setting this will maximize, -or unmaximize, the video window if the current VO supports it. See -\fB\-\-window\-minimized\fP for further remarks. -.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 -(macOS, Windows, X11, and Wayland 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 non\-HiDPI resolutions. This is enabled by -default on macOS. -.TP -.B \fB\-\-native\-fs\fP, \fB\-\-no\-native\-fs\fP -(macOS 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"). Read the -\fI\%Disabling Screensaver\fP section very carefully. -.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 macOS/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 macOS 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. -.sp -This is a key/value list option. See \fI\%List Options\fP for details. -.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\-lavf\-propagate\-opts=<yes|no>\fP -Propagate FFmpeg\-level options to recursively opened connections (default: -yes). This is needed because FFmpeg will apply these settings to nested -AVIO contexts automatically. On the other hand, this could break in certain -situations \- it\(aqs the FFmpeg API, you just can\(aqt win. -.sp -This affects in particular the \fB\-\-timeout\fP option and anything passed -with \fB\-\-demuxer\-lavf\-o\fP\&. -.sp -If this option is deemed unnecessary at some point in the future, it will -be removed without notice. -.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\-start\-time=<yes|no>\fP -Check the start time of Matroska files (default: yes). This simply reads the -first cluster timestamps and assumes it is the start time. Technically, this -also reads the first timestamp, which may increase latency by one frame -(which may be relevant for live streams). -.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 cache is enabled. -.sp -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, or -\fB\-\-demuxer\-donate\-buffer\fP is set to \fBno\fP). -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\-donate\-buffer=<yes|no>\fP -Whether to let the back buffer use part of the forward buffer (default: yes). -If set to \fByes\fP, the "donation" behavior described in the option -description for \fB\-\-demuxer\-max\-back\-bytes\fP is enabled. This means the -back buffer may use up memory up to the sum of the forward and back buffer -options, minus the active size of the forward buffer. If set to \fBno\fP, the -options strictly limit the forward and back buffer sizes separately. -.sp -Note that if the end of the file is reached, the buffered data stays the -same, even if you seek back within the cache. This is because the back -buffer is only reduced when new data is read. -.TP -.B \fB\-\-demuxer\-seekable\-cache=<yes|no|auto>\fP -Debugging option to control whether seeking can use the demuxer cache -(default: auto). Normally you don\(aqt ever need to set this; the default -\fBauto\fP does the right thing and enables cache seeking it if \fB\-\-cache\fP -is set to \fByes\fP (or is implied \fByes\fP if \fB\-\-cache=auto\fP). -.sp -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 -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\-force\-retry\-on\-eof=<yes|no>\fP -Whether to keep retrying making the demuxer thread read more packets each -time the decoder dequeues a packet, even if the end of the file was reached -(default: no). This does not really make sense, but was the default behavior -in mpv 0.32.0 and earlier. This option will be silently removed after a -while, and exists only to restore the old behavior for testing, in case this -was actually needed somewhere. This does _not_ help with files that are -being appended to (in these cases use \fBappending://\fP, or disable the -cache). -.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 enabling the cache (such as \fB\-\-cache=yes\fP, or if the input -is considered a network stream, and \fB\-\-cache=auto\fP is used), this option -is mostly ignored. (\fB\-\-cache\-secs\fP will override this. Technically, the -maximum of both options is used.) -.sp -The main purpose of this option is to limit the readhead for local playback, -since a large readahead value is not overly useful in this case. -.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). -.sp -This does not prefill the cache with the video data of the next URL. -Prefetching video data is supported only for the current playlist entry, -and depends on the demuxer cache settings (on by default). This merely -opens the URL of the next playlist entry as soon 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 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. -.TP -.B \fB\-\-rar\-list\-all\-volumes=<yes|no>\fP -When opening multi\-volume rar files, open all volumes to create a full list -of contained files (default: no). If disabled, only the archive entries -whose headers are located within the first volume are listed (and thus -played when opening a .rar file with mpv). Doing so speeds up opening, and -the typical idiotic use\-case of playing uncompressed multi\-volume rar files -that contain a single media file is made faster. -.sp -Opening is still slow, because for unknown, idiotic, and unnecessary reasons -libarchive opens all volumes anyway when playing the main file, even though -mpv iterated no archive entries yet. -.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 default\-level ("weak") key bindings. These are bindings which config -files like \fBinput.conf\fP can override. It currently affects the builtin key -bindings, and keys which scripts bind using \fBmp.add_key_binding\fP (but not -\fBmp.add_forced_key_binding\fP because this overrides \fBinput.conf\fP). -.TP -.B \fB\-\-no\-input\-builtin\-bindings\fP -Disable loading of built\-in key bindings during start\-up. This option is -applied only during (lib)mpv initialization, and if used then it will not -be not possible to enable them later. May be useful to libmpv clients. -.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\-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\-ipc\-client=fd://<N>\fP -Connect a single IPC client to the given FD. This is somewhat similar to -\fB\-\-input\-ipc\-server\fP, except no socket is created, and instead the passed -FD is treated like a socket connection received from \fBaccept()\fP\&. In -practice, you could pass either a FD created by \fBsocketpair()\fP, or a pipe. -In both cases, you must sure the FD is actually inherited by mpv (do not -set the POSIX \fBCLOEXEC\fP flag). -.sp -The player quits when the connection is closed. -.sp -This is somewhat similar to the removed \fB\-\-input\-file\fP option, except it -supports only integer FDs, and cannot open actual paths. -.INDENT 7.0 -.INDENT 3.5 -.IP "Example" -.sp -\fB\-\-input\-ipc\-client=fd://123\fP -.UNINDENT -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Does not and will not work on Windows. -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -Writing to the \fBinput\-ipc\-server\fP option at runtime will start another -instance of an IPC client handler for the \fBinput\-ipc\-client\fP option, -because initialization is bundled, and this thing is stupid. This is a -bug. Writing to \fBinput\-ipc\-client\fP at runtime will start another IPC -client handler for the new value, without stopping the old one, even if -the FD value is the same (but the string is different e.g. due to -whitespace). This is not a bug. -.UNINDENT -.UNINDENT -.TP -.B \fB\-\-input\-gamepad=<yes|no>\fP -Enable/disable SDL2 Gamepad support. Disabled by default. -.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 -On systems where mpv can choose between receiving media keys or letting -the system handle them \- this option controls whether mpv should receive -them. -.sp -Default: yes (except for libmpv). macOS and Windows only, because elsewhere -mpv doesn\(aqt have a choice \- the system decides whether to send media keys -to mpv. For instance, on X11 or Wayland, system\-wide media keys are not -implemented. Whether media keys work when the mpv window is focused is -implementation\-defined. -.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\-\-sub\-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\-\-sub\-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. -.TP -.B \fB\-\-screenshot\-sw=<yes|no>\fP -Whether to use software rendering for screenshots (default: no). -.sp -If set to no, the screenshot will be rendered by the current VO if possible -(only vo_gpu currently). The advantage is that this will (probably) always -show up as in the video window, because the same code is used for rendering. -But since the renderer needs to be reinitialized, this can be slow and -interrupt playback. (Unless the \fBwindow\fP mode is used with the -\fBscreenshot\fP command.) -.sp -If set to yes, the software scaler is used to convert the video to RGB (or -whatever the target screenshot requires). In this case, conversion will -run in a separate thread and will probably not interrupt playback. The -software renderer may lack some capabilities, such as HDR rendering. -.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\-bitexact=<yes|no>\fP -Unknown functionality (default: no). Consult libswscale source code. The -primary purpose of this, as far as libswscale API goes), is to produce -exactly the same output for the same input on all platforms (output has the -same "bits" everywhere, thus "bitexact"). Typically disables optimizations. -.TP -.B \fB\-\-sws\-fast=<yes|no>\fP -Allow optimizations that help with performance, but reduce quality (default: -no). -.sp -VOs like \fBdrm\fP and \fBx11\fP will benefit a lot from using \fB\-\-sws\-fast\fP\&. -You may need to set other options, like \fB\-\-sws\-scaler\fP\&. The builtin -\fBsws\-fast\fP profile sets this option and some others to gain performance -for reduced quality. Also see \fB\-\-sws\-allow\-zimg\fP\&. -.TP -.B \fB\-\-sws\-allow\-zimg=<yes|no>\fP -Allow using zimg (if the component using the internal swscale wrapper -explicitly allows so) (default: yes). In this case, zimg \fImay\fP be used, if -the internal zimg wrapper supports the input and output formats. It will -silently or noisily 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 -Most things which need software conversion can make use of this. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Do note that zimg \fImay\fP be slower than libswscale. Usually, -it\(aqs faster on x86 platforms, but slower on ARM (due to lack of ARM -specific optimizations). The mpv zimg wrapper uses unoptimized repacking -for some formats, for which zimg cannot be blamed. -.UNINDENT -.UNINDENT -.TP -.B \fB\-\-zimg\-scaler=<point|bilinear|bicubic|spline16|spline36|lanczos>\fP -Zimg luma scaler to use (default: lanczos). -.TP -.B \fB\-\-zimg\-scaler\-param\-a=<default|float>\fP, \fB\-\-zimg\-scaler\-param\-b=<default|float>\fP -Set scaler parameters. By default, these are set to the special string -\fBdefault\fP, which maps to a scaler\-specific default value. Ignored if the -scaler is not tunable. -.INDENT 7.0 -.TP -.B \fBlanczos\fP -\fB\-\-zimg\-scaler\-param\-a\fP is the number of taps. -.TP -.B \fBbicubic\fP -a and b are the bicubic b and c parameters. -.UNINDENT -.TP -.B \fB\-\-zimg\-scaler\-chroma=...\fP -Same as \fB\-\-zimg\-scaler\fP, for for chroma interpolation (default: bilinear). -.TP -.B \fB\-\-zimg\-scaler\-chroma\-param\-a\fP, \fB\-\-zimg\-scaler\-chroma\-param\-b\fP -Same as \fB\-\-zimg\-scaler\-param\-a\fP / \fB\-\-zimg\-scaler\-param\-b\fP, for chroma. -.TP -.B \fB\-\-zimg\-dither=<no|ordered|random|error\-diffusion>\fP -Dithering (default: random). -.TP -.B \fB\-\-zimg\-threads=<auto|integer>\fP -Set the maximum number of threads to use for scaling (default: auto). -\fBauto\fP uses the number of logical cores on the current machine. Note that -the scaler may use less threads (or even just 1 thread) depending on stuff. -Passing a value of 1 disables threading and always scales the image in a -single operation. Higher thread counts waste resources, but make it -typically faster. -.sp -Note that some zimg git versions had bugs that will corrupt the output if -threads are used. -.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. -.sp -This is a key/value list option. See \fI\%List Options\fP for details. -.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\-\-term\-title=<string>\fP -Set the terminal title. Currently, this simply concatenates the escape -sequence setting the window title with the provided (property expanded) -string. This will mess up if the expanded string contain bytes that end the -escape sequence, or if the terminal does not understand the sequence. The -latter probably includes the regrettable win32. -.sp -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. The time is in -seconds since the player process was started (technically, slightly -later actually), using a monotonic time source depending on the OS. This -is \fBCLOCK_MONOTONIC\fP on sane UNIX variants. -.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), and make the cached data seekable (if possible). -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. -.TP -.B \fB\-\-stream\-buffer\-size=<bytesize>\fP -Size of the low level stream byte buffer (default: 128KB). This is used as -buffer between demuxer and low level I/O (e.g. sockets). Generally, this -can be very small, and the main purpose is similar to the internal buffer -FILE in the C standard library will have. -.sp -Half of the buffer is always used for guaranteed seek back, which is -important for unseekable input. -.sp -There are known cases where this can help performance to set a large buffer: -.INDENT 7.0 -.INDENT 3.5 -.INDENT 0.0 -.IP 1. 3 -mp4 files. libavformat may trigger many small seeks in both -directions, depending on how the file was muxed. -.IP 2. 3 -Certain network filesystems, which do not have a cache, and where -small reads can be inefficient. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -In other cases, setting this to a large value can reduce performance. -.sp -Usually, read accesses are at half the buffer size, but it may happen that -accesses are done alternating with smaller and larger sizes (this is due to -the internal ring buffer wrap\-around). -.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\-\-vd\-queue\-enable=<yes|no>, \-\-ad\-queue\-enable\fP -Enable running the video/audio decoder on a separate thread (default: no). -If enabled, the decoder is run on a separate thread, and a frame queue is -put between decoder and higher level playback logic. The size of the frame -queue is defined by the other options below. -.sp -This is probably quite pointless. libavcodec already has multithreaded -decoding (enabled by default), which makes this largely unnecessary. It -might help in some corner cases with high bandwidth video that is slow to -decode (in these cases libavcodec would block the playback logic, while -using a decoding thread would distribute the decoding time evenly without -affecting the playback logic). In other situations, it will simply make -seeking slower and use significantly more memory. -.sp -The queue size is restricted by the other \fB\-\-vd\-queue\-...\fP options. The -final queue size is the minimum as indicated by the option with the lowest -limit. Each decoder/track has its own queue that may use the full configured -queue size. -.sp -Most queue options can be changed at runtime. \fB\-\-vd\-queue\-enable\fP itself -(and the audio equivalent) update only if decoding is completely -reinitialized. However, setting \fB\-\-vd\-queue\-max\-samples=1\fP should almost -lead to the same behavior as \fB\-\-vd\-queue\-enable=no\fP, so that value can -be used for effectively runtime enabling/disabling the queue. -.sp -This should not be used with hardware decoding. It is possible to enable -this for audio, but it makes even less sense. -.TP -.B \fB\-\-vd\-queue\-max\-bytes=<bytesize>\fP, \fB\-\-ad\-queue\-max\-bytes\fP -Maximum approximate allowed size of the queue. If exceeded, decoding will -be stopped. The maximum size can be exceeded by about 1 frame. -.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\-\-vd\-queue\-max\-samples=<int>\fP, \fB\-\-ad\-queue\-max\-samples\fP -Maximum number of frames (video) or samples (audio) of the queue. The audio -size may be exceeded by about 1 frame. -.sp -See \fB\-\-list\-options\fP for defaults and value range. -.TP -.B \fB\-\-vd\-queue\-max\-secs=<seconds>\fP, \fB\-\-ad\-queue\-max\-secs\fP -Maximum number of seconds of media in the queue. The special value 0 means -no limit is set. The queue size may be exceeded by about 2 frames. Timestamp -resets may lead to random queue size usage. -.sp -See \fB\-\-list\-options\fP for defaults and value range. -.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. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.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 (default: 60 seconds). This affects -at least HTTP. The special value 0 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. At time of this -writing, the fix was not made effective yet. For this reason, this -option is ignored (or should be ignored) on RTSP URLs. You can still -set the timeout option directly with \fB\-\-demuxer\-lavf\-o\fP\&. -.UNINDENT -.UNINDENT -.TP -.B \fB\-\-rtsp\-transport=<lavf|udp|udp_multicast|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=libmpv\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. -.sp -Note: this option is ignored when using bilinear downscaling (the default). -.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.01\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 enable interpolation in scenarios where -retiming with the \fB\-\-video\-sync=display\-*\fP cannot adjust the speed of -the video sufficiently for smooth playback. For example if a video is -60.00 FPS and your display refresh rate is 59.94 Hz, interpolation will -never be activated, since the mismatch is within 1% of the refresh -rate. The default also handles the scenario when mpv cannot determine the -container FPS, such as during certain live streams, and may dynamically -toggle interpolation on and off. In this scenario, the default would be to -not use interpolation but rather to allow \fB\-\-video\-sync=display\-*\fP to -retime the video to match display refresh rate. See -\fB\-\-video\-sync\-max\-video\-change\fP for more information about how mpv -will retime video. -.sp -Also 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\-\-override\-display\-fps\fP). -.TP -.B \fB\-\-vulkan\-device=<device name>\fP -The name of the Vulkan device to use for rendering and presentation. Use -\fB\-\-vulkan\-device=help\fP to see the list of available devices and their -names. If left unspecified, the first enumerated hardware Vulkan device will -be used. -.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. Enabled by -default, although Nvidia users may want to disable it. -.TP -.B \fB\-\-vulkan\-disable\-events\fP -Disable the use of VkEvents, for debugging purposes or for compatibility -with some older drivers / vulkan portability layers that don\(aqt provide -working VkEvent support. -.TP -.B \fB\-\-vulkan\-display\-display=<n>\fP -The index of the display, on the selected Vulkan device, to present on when -using the \fBdisplayvk\fP GPU context. Use \fB\-\-vulkan\-display\-display=help\fP -to see the list of available displays. If left unspecified, the first -enumerated display will be used. -.TP -.B \fB\-\-vulkan\-display\-mode=<n>\fP -The index of the display mode, of the selected Vulkan display, to use when -using the \fBdisplayvk\fP GPU context. Use \fB\-\-vulkan\-display\-mode=help\fP -to see the list of available modes. If left unspecified, the first -enumerated mode will be used. -.TP -.B \fB\-\-vulkan\-display\-plane=<n>\fP -The index of the plane, on the selected Vulkan device, to present on when -using the \fBdisplayvk\fP GPU context. Use \fB\-\-vulkan\-display\-plane=help\fP -to see the list of available planes. If left unspecified, the first -enumerated plane will be used. -.TP -.B \fB\-\-d3d11\-exclusive\-fs=<yes|no>\fP -Switches the D3D11 swap chain fullscreen state to \(aqfullscreen\(aq when -fullscreen video is requested. Also known as "exclusive fullscreen" or -"D3D fullscreen" in other applications. Gives mpv full control of -rendering on the swap chain\(aqs screen. Off by default. -.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\-\-d3d11\-output\-csp=<auto|srgb|linear|pq|bt.2020>\fP -Select a specific D3D11 output color space to utilize for D3D11 rendering. -"auto" is the default, which will select the color space of the desktop -on which the swap chain is located. -.sp -Values other than "srgb" and "pq" have had issues in testing, so they -are mostly available for manual testing. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Swap chain color space configuration is only available from an API -available from Windows 10. Thus on older systems it will not work. -.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\-app\-id=<string>\fP -Set the client app id for Wayland\-based video output methods (default: \fBmpv\fP). -.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\-\-wayland\-edge\-pixels\-pointer=<value>\fP -Defines the size of an edge border (default: 10) to initiate client side -resize events in the wayland contexts with the mouse. This is only active if -there are no server side decorations from the compositor. -.TP -.B \fB\-\-wayland\-edge\-pixels\-touch=<value>\fP -Defines the size of an edge border (default: 32) to initiate client side -resizes events in the wayland contexts with touch events. -.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\-shader=<file>\fP, \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. -.sp -Each use of the \fB\-\-glsl\-shader\fP option will add another file to the -internal list of shaders, while \fB\-\-glsl\-shaders\fP takes a list of files, -and overwrites the internal list with it. The latter is a path list option -(see \fI\%List Options\fP for details). -.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 be 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 32) -.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\-\-macos\-force\-dedicated\-gpu=<yes|no>\fP -Deactivates the automatic graphics switching and forces the dedicated GPU. -(default: no) -.sp -macOS 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 -macOS 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 -macOS 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. -(macOS and cocoa\-cb only) -.TP -.B \fB\-\-macos\-app\-activation\-policy=<regular|accessory|prohibited>\fP -Changes the App activation policy. With accessory the mpv icon in the Dock -can be hidden. (default: regular) -.sp -macOS only. -.TP -.B \fB\-\-macos\-geometry\-calculation=<visible|whole>\fP -This changes the rectangle which is used to calculate the screen position -and size of the window (default: visible). \fBvisible\fP takes the the menu -bar and Dock into account and the window is only positioned/sized within the -visible screen frame rectangle, \fBwhole\fP takes the whole screen frame -rectangle and ignores the menu bar and Dock. Other previous restrictions -still apply, like the window can\(aqt be placed on top of the menu bar etc. -.sp -macOS 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/macOS (deprecated, use \-\-vo=libmpv 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 displayvk -VK_KHR_display. This backend is roughly the Vukan equivalent of -DRM/EGL, allowing for direct rendering via Vulkan without a display -manager. -.TP -.B x11egl -X11/EGL -.TP -.B android -Android/EGL. Requires \fB\-\-wid\fP be set to an \fBandroid.view.Surface\fP\&. -.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\-\-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 macOS. -.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 203 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 203. For HDR curves, it -uses 203 * 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. -.TP -.B bt.2390 -Perceptual tone mapping curve (EETF) specified in ITU\-R Report BT.2390. -This is the recommended curve to use for typical HDR\-mastered content. -(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\-\-gamut\-clipping\fP -If enabled (default: yes), mpv will colorimetrically clip out\-of\-gamut -colors by desaturating them (preserving luma), rather than hard\-clipping -each component individually. This should make playback of wide gamut -content on typical (standard gamut) monitors look much more aesthetically -pleasing and less blown\-out. -.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\-force\-contrast=<no|0\-1000000|inf>\fP -Override the target device\(aqs detected contrast ratio by a specific value. -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. If this is -the case, setting this option might help. This only affects BT.1886 -content. The default of \fBno\fP means to use the profile values. The special -value \fBinf\fP causes the BT.1886 curve to be treated as a pure power gamma -2.4 function. -.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) or if -you make the background color transparent. 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. Whether this really works depends on the windowing -system and desktop environment. -.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 the -\fB\-\-sub\-color\fP option for 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 macOS 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. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.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. This mode will cause severe audio artifacts if -the real monitor refresh rate is too different from -the reported or forced rate. Since mpv 0.33.0, this -acts on entire audio frames, instead of single samples. -.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\-factor=<value>\fP -Maximum multiple for which to try to fit the video\(aqs FPS to the display\(aqs -FPS (default: 5). -.sp -For example, if this is set to 1, the video FPS is forced to an integer -multiple of the display FPS, as long as the speed change does not exceed -the value set by \fB\-\-video\-sync\-max\-video\-change\fP\&. -.sp -See \fB\-\-interpolation\-threshold\fP for how this option affects -interpolation. -.sp -This is mostly for testing, and the option may be randomly changed in the -future without notice. -.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\-\-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.) -.sp -This is a key/value list option. See \fI\%List Options\fP for details. -.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 path 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 file. -.TP -.B \fB\-\-cover\-art\-files=<file\-list>\fP -Use an external file as cover art while playing audio. This makes it appear -on the track list and subject to automatic track selection. Options like -\fB\-\-audio\-display\fP control whether such tracks are supposed to be selected. -.sp -(The difference to loading a file with \fB\-\-external\-files\fP is that video -tracks will be marked as being pictures, which affects the auto\-selection -method. If the passed file is a video, only the first frame will be decoded -and displayed. Enabling the cover art track during playback may show a -random frame if the source file is a video. Normally you\(aqre not supposed to -pass videos to this option, so this paragraph describes the behavior -coincidentally resulting from implementation details.) -.sp -This is a path list option. See \fI\%List Options\fP for details. -.TP -.B \fB\-\-cover\-art\-file=<file>\fP -CLI/config file only alias for \fB\-\-cover\-art\-files\-append\fP\&. Each use of this -option will add a new external file. -.TP -.B \fB\-\-cover\-art\-auto=<no|exact|fuzzy|all>\fP -Whether to load _external_ cover art automatically. Similar to -\fB\-\-sub\-auto\fP and \fB\-\-audio\-file\-auto\fP\&. If a video already has tracks -(which are not marked as cover art), external cover art will not be loaded. -.INDENT 7.0 -.TP -.B no -Don\(aqt automatically load cover art. -.TP -.B exact -Load the media filename with an image file extension. -.TP -.B fuzzy -Load all cover art containing the media filename and filenames -in an internal whitelist, such as \fBcover.jpg\fP (default). -.TP -.B all -Load all images in the current directory. -.UNINDENT -.sp -See \fB\-\-cover\-art\-files\fP for details about what constitutes cover art. -.sp -See \fB\-\-audio\-display\fP how to control display of cover art (this can be -used to disable cover art that is part of the file). -.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, \fB\-\-audio\-file\-auto\fP and \fB\-\-cover\-art\-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. -.TP -.B \fB\-\-metadata\-codepage=<codepage>\fP -Codepage for various input metadata (default: \fButf\-8\fP). This affects how -file tags, chapter titles, etc. are interpreted. You can for example set -this to \fBauto\fP to enable autodetection of the codepage. (This is not the -default because non\-UTF\-8 codepages are an obscure fringe use\-case.) -.sp -See \fB\-\-sub\-codepage\fP option on how codepages are specified and further -details regarding autodetection and codepage conversion. (The underlying -code is the same.) -.sp -Conversion is not applied to metadata that is updated at runtime. -.UNINDENT -.SS Debugging -.INDENT 0.0 -.TP -.B \fB\-\-unittest=<name>\fP -Run an internal unit test. There are multiple, and the name specifies which. -.sp -The special value \fBall\-simple\fP runs all tests which do not need further -setup (other arguments and such). Some tests may need additional arguments -to do anything useful. -.sp -On success, the player binary exits with exit status 0, otherwise it returns -with an undefined non\-0 exit status (it may crash or abort itself on test -failures). -.sp -This is only enabled if built with \fB\-\-enable\-tests\fP, and should normally -be enabled and used by developers only. -.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 is preferred. -.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 -.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 (macOS only) -Native macOS 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 (macOS only) -Native macOS audio output driver using direct device access and -exclusive mode (bypasses the sound server). -.TP -.B \fBopenal\fP -OpenAL audio output driver. This is broken and does not work. -.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. -.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 \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 -Since mpv 0.30.0, you may need to use \fB\-\-profile=sw\-fast\fP to get decent -performance. -.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\-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 -The following global options are supported by this video output: -.INDENT 7.0 -.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\-\-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 macOS 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. -By default depends on support of true color by modern terminals to display -the images at full color range, but 256\-colors output is also supported (see -below). On Windows it requires an ansi terminal such as mintty. -.sp -Since mpv 0.30.0, you may need to use \fB\-\-profile=sw\-fast\fP to get decent -performance. -.sp -Note: the TCT image output is not synchronized with other terminal output -from mpv, which can lead to broken images. The options \fB\-\-no\-terminal\fP or -\fB\-\-really\-quiet\fP can help with that. -.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 \fBsixel\fP -Graphical output for the terminal, using sixels. Tested with \fBmlterm\fP and -\fBxterm\fP\&. -.sp -Note: the Sixel image output is not synchronized with other terminal output -from mpv, which can lead to broken images. The option \fB\-\-really\-quiet\fP -can help with that, and is recommended. -.sp -You may need to use \fB\-\-profile=sw\-fast\fP to get decent performance. -.sp -Note: at the time of writing, \fBxterm\fP does not enable sixel by default \- -launching it as \fBxterm \-ti 340\fP is one way to enable it. Also, \fBxterm\fP -does not display images bigger than 1000x1000 pixels by default. -.sp -To render and align sixel images correctly, mpv needs to know the terminal -size both in cells and in pixels. By default it tries to use values which -the terminal reports, however, due to differences between terminals this is -an error\-prone process which cannot be automated with certainty \- some -terminals report the size in pixels including the padding \- e.g. \fBxterm\fP, -while others report the actual usable number of pixels \- like \fBmlterm\fP\&. -Additionally, they may behave differently when maximized or in fullscreen, -and mpv cannot detect this state using standard methods. -.sp -Sixel size and alignment options: -.INDENT 7.0 -.TP -.B \fB\-\-vo\-sixel\-cols=<columns>\fP, \fB\-\-vo\-sixel\-rows=<rows>\fP (default: 0) -Specify the terminal size in character cells, otherwise (0) read it -from the terminal, or fall back to 80x25. Note that mpv doesn\(aqt use the -the last row with sixel because this seems to result in scrolling. -.TP -.B \fB\-\-vo\-sixel\-width=<width>\fP, \fB\-\-vo\-sixel\-height=<height>\fP (default: 0) -Specify the available size in pixels, otherwise (0) read it from the -terminal, or fall back to 320x240. Other than excluding the last line, -the height is also further rounded down to a multiple of 6 (sixel unit -height) to avoid overflowing below the designated size. -.TP -.B \fB\-\-vo\-sixel\-left=<col>\fP, \fB\-\-vo\-sixel\-top=<row>\fP (default: 0) -Specify the position in character cells where the image starts (1 is -the first column or row). If 0 (default) then try to automatically -determine it according to the other values and the image aspect ratio -and zoom. -.TP -.B \fB\-\-vo\-sixel\-pad\-x=<pad_x>\fP, \fB\-\-vo\-sixel\-pad\-y=<pad_y>\fP (default: \-1) -Used only when mpv reads the size in pixels from the terminal. -Specify the number of padding pixels (on one side) which are included -at the size which the terminal reports. If \-1 (default) then the number -of pixels is rounded down to a multiple of number of cells (per axis), -to take into account padding at the report \- this only works correctly -when the overall padding per axis is smaller than the number of cells. -.TP -.B \fB\-\-vo\-sixel\-exit\-clear=<yes|no>\fP (default: yes) -Whether or not to clear the terminal on quit. When set to no \- the last -sixel image stays on screen after quit, with the cursor following it. -.UNINDENT -.sp -Sixel image quality options: -.INDENT 7.0 -.TP -.B \fB\-\-vo\-sixel\-dither=<algo>\fP -Selects the dither algorithm which libsixel should apply. -Can be one of the below list as per libsixel\(aqs documentation. -.INDENT 7.0 -.TP -.B auto (Default) -Let libsixel choose the dithering method. -.TP -.B none -Don\(aqt diffuse -.TP -.B atkinson -Diffuse with Bill Atkinson\(aqs method. -.TP -.B fs -Diffuse with Floyd\-Steinberg method -.TP -.B jajuni -Diffuse with Jarvis, Judice & Ninke method -.TP -.B stucki -Diffuse with Stucki\(aqs method -.TP -.B burkes -Diffuse with Burkes\(aq method -.TP -.B arithmetic -Positionally stable arithmetic dither -.TP -.B xor -Positionally stable arithmetic xor based dither -.UNINDENT -.TP -.B \fB\-\-vo\-sixel\-fixedpalette=<yes|no>\fP (default: yes) -Use libsixel\(aqs built\-in static palette using the XTERM256 profile -for dither. Fixed palette uses 256 colors for dithering. Note that -using \fBno\fP (at the time of writing) will slow down \fBxterm\fP\&. -.TP -.B \fB\-\-vo\-sixel\-reqcolors=<colors>\fP (default: 256) -Has no effect with fixed palette. Set up libsixel to use required -number of colors for dynamic palette. This value depends on the -terminal emulator as well. Xterm supports 256 colors. Can set this to -a lower value for faster performance. -.TP -.B \fB\-\-vo\-sixel\-threshold=<threshold>\fP (default: \-1) -Has no effect with fixed palette. Defines the threshold to change the -palette \- as percentage of the number of colors, e.g. 20 will change -the palette when the number of colors changed by 20%. It\(aqs a simple -measure to reduce the number of palette changes, because it can be slow -in some terminals (\fBxterm\fP). The default (\-1) will choose a palette -on every frame and will have better quality. -.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 macOS 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 -Since mpv 0.30.0, you may need to use \fB\-\-profile=sw\-fast\fP to get decent -performance. -.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. The \fB<gpu_number>\fP argument can be used to disambiguate -multiple graphic cards, but is deprecated in favor of \fB\-\-drm\-device\fP\&. -(default: empty) -.TP -.B \fB\-\-drm\-device=<path>\fP -Select the DRM device file to use. If specified this overrides automatic -card selection and any card number specified \fB\-\-drm\-connector\fP\&. -(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 -Since mpv 0.30.0, you may need to use \fB\-\-profile=sw\-fast\fP to get decent -performance. -.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 \fBscaletempo2[=option1:option2:...]\fP -Scales audio tempo without altering pitch. -The algorithm is ported from chromium and uses the -Waveform Similarity Overlap\-and\-add (WSOLA) method. -It seems to achieve a higher audio quality than scaletempo and rubberband. -.sp -By default, the \fBsearch\-interval\fP and \fBwindow\-size\fP parameters -have the same values as in chromium. -.INDENT 7.0 -.TP -.B \fBmin\-speed=<speed>\fP -Mute audio if the playback speed is below \fB<speed>\fP\&. (default: 0.25) -.TP -.B \fBmax\-speed=<speed>\fP -Mute audio if the playback speed is above \fB<speed>\fP -and \fB<speed> != 0\fP\&. (default: 4.0) -.TP -.B \fBsearch\-interval=<amount>\fP -Length in milliseconds to search for best overlap position. (default: 30) -.TP -.B \fBwindow\-size=<amount>\fP -Length in milliseconds of the overlap\-and\-add window. (default: 20) -.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\%https://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 -.TP -.B \fBdrop\fP -This filter drops or repeats audio frames to adapt to playback speed. It -always operates on full audio frames, because it was made to handle SPDIF -(compressed audio passthrough). This is used automatically if the -\fB\-\-video\-sync=display\-adrop\fP option is used. Do not use this filter (or -the given option); they are extremely low quality. -.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\%https://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\-append=filter\fP -Appends the filter given as arguments to the filter list. -.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\-remove=filter\fP -Deletes the filter from the list. The filter can be either given the way it -was added (filter name and its full argument list), or by label (prefixed -with \fB@\fP). Matching of filters works as follows: if either of the compared -filters has a label set, only the labels are compared. If none of the -filters have a label, the filter name, arguments, and argument order are -compared. (Passing multiple filters is currently still possible, but -deprecated.) -.TP -.B \fB\-vf\-toggle=filter\fP -Add the given filter to the list if it was not present yet, or remove it -from the list if it was present. Matching of filters works as described in -\fB\-\-vf\-remove\fP\&. -.TP -.B \fB\-\-vf\-del=filter\fP -Sort of like \fB\-\-vf\-remove\fP, but also accepts an index number. Index -numbers start at 0, negative numbers address the end of the list (\-1 is the -last). 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<w>\fP, \fB<h>\fP -If not 0, perform conversion to the given size. Ignored if -\fBconvert=yes\fP is not set. -.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). -.TP -.B \fB<force\-scaler=auto|zimg|sws>\fP -Force a specific scaler backend, if applicable. This is a debug option -and could go away any time. -.TP -.B \fB<alpha=auto|straight|premul>\fP -Set the kind of alpha the video uses. Undefined effect if the image -format has no alpha channel (could be ignored or cause an error, -depending on how mpv internals evolve). Setting this may or may not -cause downstream image processing to treat alpha differently, depending -on support. With \fBconvert\fP and zimg used, this will convert the alpha. -libswscale and other FFmpeg components completely ignore this. -.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 \fBhttps://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 intuitive, 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 to 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 -.TP -.B \fBgpu=...\fP -Convert video to RGB using the OpenGL renderer normally used with -\fB\-\-vo=gpu\fP\&. This requires that the EGL implementation supports off\-screen -rendering on the default display. (This is the case with Mesa.) -.sp -Sub\-options: -.INDENT 7.0 -.TP -.B \fBw=<pixels>\fP, \fBh=<pixels>\fP -Size of the output in pixels (default: 0). If not positive, this will -use the size of the first filtered input frame. -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -This is highly experimental. Performance is bad, and it will not work -everywhere in the first place. Some features are not supported. -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -This does not do OSD rendering. If you see OSD, then it has been -rendered by the VO backend. (Subtitles are rendered by the \fBgpu\fP -filter, if possible.) -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -If you use this with encoding mode, keep in mind that encoding mode will -convert the RGB filter\(aqs output back to yuv420p in software, using the -configured software scaler. Using \fBzimg\fP might improve this, but in -any case it might go against your goals when using this filter. -.UNINDENT -.UNINDENT -.sp -\fBWARNING:\fP -.INDENT 7.0 -.INDENT 3.5 -Do not use this with \fB\-\-vo=gpu\fP\&. It will apply filtering twice, since -most \fB\-\-vo=gpu\fP options are unconditionally applied to the \fBgpu\fP -filter. There is no mechanism in mpv to prevent this. -.UNINDENT -.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 -This is a key/value list option. See \fI\%List Options\fP for details. -.INDENT 7.0 -.TP -.B \fB\-\-ofopts\-add=<option>\fP -Appends the option given as an argument to the options list. (Passing -multiple options is currently still possible, but deprecated.) -.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 -This is a key/value list option. See \fI\%List Options\fP for details. -.INDENT 7.0 -.TP -.B \fB\-\-oacopts\-add=<option>\fP -Appends the option given as an argument to the options list. (Passing -multiple options is currently still possible, but deprecated.) -.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 -This is a key/value list option. See \fI\%List Options\fP for details. -.INDENT 7.0 -.TP -.B \fB\-\-ovcopts\-add=<option>\fP -Appends the option given as an argument to the options list. (Passing -multiple options is currently still possible, but deprecated.) -.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. -.sp -This is a key/value list option. See \fI\%List Options\fP for details. -.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. -.sp -This is a string list option. See \fI\%List Options\fP for details. -.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.) -.sp -Also see \fI\%Key names\fP\&. -.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) arguments, all separated by whitespace. String arguments -should be quoted, typically with \fB"\fP\&. 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 Key names -.sp -All mouse and keyboard input is to converted to mpv\-specific key names. Key -names are either special symbolic identifiers representing a physical key, or a -text key names, which are unicode code points encoded as UTF\-8. These are what -keyboard input would normally produce, for example \fBa\fP for the A key. As a -consequence, mpv uses input translated by the current OS keyboard layout, rather -than physical scan codes. -.sp -Currently there is the hardcoded assumption that every text key can be -represented as a single unicode code point (in NFKC form). -.sp -All key names can be combined with the modifiers \fBShift\fP, \fBCtrl\fP, \fBAlt\fP, -\fBMeta\fP\&. They must be prefixed to the actual key name, where each modifier -is followed by a \fB+\fP (for example \fBctrl+q\fP). -.sp -The \fBShift\fP modifier requires some attention. For instance \fBShift+2\fP should -usually be specified as key\-name \fB@\fP at \fBinput.conf\fP, and similarly the -combination \fBAlt+Shift+2\fP is usually \fBAlt+@\fP, etc. Special key names like -\fBShift+LEFT\fP work as expected. If in doubt \- use \fB\-\-input\-test\fP to check -how a key/combination is seen by mpv. -.sp -Symbolic key names and modifier names are case\-insensitive. Unicode key names -are case\-sensitive because input bindings typically respect the shift key. -.sp -Another type of key names are hexadecimal key names, that serve as fallback -for special keys that are neither unicode, nor have a special mpv defined name. -They will break as soon as mpv adds proper names for them, but can enable you -to use a key at all if that does not happen. -.sp -All symbolic names are listed by \fB\-\-input\-keylist\fP\&. \fB\-\-input\-test\fP is a -special mode that prints all input on the OSD. -.sp -Comments on some symbolic names: -.INDENT 0.0 -.TP -.B \fBKP*\fP -Keypad names. Behavior varies by backend (whether they implement this, and -on how they treat numlock), but typically, mpv tries to map keys on the -keypad to separate names, even if they produce the same text as normal keys. -.TP -.B \fBMOUSE_BTN*\fP, \fBMBTN*\fP -Various mouse buttons. -.sp -Depending on backend, the mouse wheel might also be represented as a button. -In addition, \fBMOUSE_BTN3\fP to \fBMOUSE_BTN6\fP are deprecated aliases for -\fBWHEEL_UP\fP, \fBWHEEL_DOWN\fP, \fBWHEEL_LEFT\fP, \fBWHEEL_RIGHT\fP\&. -.sp -\fBMBTN*\fP are aliases for \fBMOUSE_BTN*\fP\&. -.TP -.B \fBWHEEL_*\fP -Mouse wheels (typically). -.TP -.B \fBAXIS_*\fP -Deprecated aliases for \fBWHEEL_*\fP\&. -.TP -.B \fB*_DBL\fP -Mouse button double clicks. -.TP -.B \fBMOUSE_MOVE\fP, \fBMOUSE_ENTER\fP, \fBMOUSE_LEAVE\fP -Emitted by mouse move events. Enter/leave happens when the mouse enters or -leave the mpv window (or the current mouse region, using the deprecated -mouse region input section mechanism). -.TP -.B \fBCLOSE_WIN\fP -Pseudo key emitted when closing the mpv window using the OS window manager -(for example, by clicking the close button in the window title bar). -.TP -.B \fBGAMEPAD_*\fP -Keys emitted by the SDL gamepad backend. -.TP -.B \fBUNMAPPED\fP -Pseudo\-key that matches any unmapped key. (You should probably avoid this -if possible, because it might change behavior or get removed in the future.) -.TP -.B \fBANY_UNICODE\fP -Pseudo\-key that matches any key that produces text. (You should probably -avoid this if possible, because it might change behavior or get removed in -the future.) -.UNINDENT -.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. -.nf - -\fB<command> ::= [<prefixes>] <command_name> (<argument>)*\fP -\fB<argument> ::= (<unquoted> | " <double_quoted> " | \(aq <single_quoted> \(aq | \(gaX <custom_quoted> X\(ga)\fP -.fi -.sp -.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 whitespaces even if the command expects only one -argument. Arguments with whitespaces or other special characters must be quoted, -or the command cannot be parsed correctly. -.sp -Double quotes interpret JSON/C\-style escaping, like \fB\et\fP or \fB\e"\fP or \fB\e\e\fP\&. -JSON escapes according to RFC 8259, minus surrogate pair escapes. This is the -only form which allows newlines at the value \- as \fB\en\fP\&. -.sp -Single quotes take the content literally, and cannot include the single\-quote -character at the value. -.sp -Custom quotes also take the content literally, but are more flexible than single -quotes. They start with \fB\(ga\fP (back\-quote) followed by any ASCII character, -and end at the first occurance of the same pair in reverse order, e.g. -\fB\(ga\-foo\-\(ga\fP or \fB\(ga\(gabar\(ga\(ga\fP\&. The final pair sequence is not allowed at the -value \- in these examples \fB\-\(ga\fP and \fB\(ga\(ga\fP respectively. In the second -example the last character of the value also can\(aqt be a back\-quote. -.sp -Mixed quoting at the same argument, like \fB\(aqfoo\(aq"bar"\fP, is not supported. -.sp -Note that argument parsing and property expansion happen at different stages. -First, arguments are determined as described above, and then, where applicable, -properties are expanded \- regardless of argument quoting. However, expansion -can still be prevented with the \fBraw\fP prefix or \fB$>\fP\&. See \fI\%Input Command -Prefixes\fP and \fI\%Property Expansion\fP\&. -.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 -Property expansion is disabled by default for these APIs. This can be changed -with the \fBexpand\-properties\fP prefix. See \fI\%Input Command Prefixes\fP\&. -.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 -The name of the command is provided with a \fBname\fP string field. 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. See the -\fBsubprocess\fP command for an example. -.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. -.sp -Property expansion is disabled by default for these APIs. This can be changed -with the \fBexpand\-properties\fP prefix. See \fI\%Input Command Prefixes\fP\&. -.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. -.TP -.B mark\-permanent -If set, mark the current position, and do not change the mark position -before the next \fBrevert\-seek\fP command that has \fBmark\fP or -\fBmark\-permanent\fP set (or playback of the current file ends). Until -this happens, \fBrevert\-seek\fP will always seek to the marked point. This -flag cannot be combined with \fBmark\fP\&. -.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\&. -.sp -Whether or not key\-repeat is enabled by default depends on the property. -Currently properties with continuous values are repeatable by default (like -\fBvolume\fP), while discrete values are not (like \fBosd\-level\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 \fBplaylist\-play\-index <integer|current|none>\fP -Start (or restart) playback of the given playlist index. In addition to the -0\-based playlist entry index, it supports the following values: -.INDENT 7.0 -.TP -.B <current> -The current playlist entry (as in \fBplaylist\-current\-pos\fP) will be -played again (unload and reload). If none is set, playback is stopped. -(In corner cases, \fBplaylist\-current\-pos\fP can point to a playlist entry -even if playback is currently inactive, -.TP -.B <none> -Playback is stopped. If idle mode (\fB\-\-idle\fP) is enabled, the player -will enter idle mode, otherwise it will exit. -.UNINDENT -.sp -This comm and is similar to \fBloadfile\fP in that it only manipulates the -state of what to play next, without waiting until the current file is -unloaded, and the next one is loaded. -.sp -Setting \fBplaylist\-pos\fP or similar properties can have a similar effect to -this command. However, it\(aqs more explicit, and guarantees that playback is -restarted if for example the new playlist entry is the same as the previous -one. -.TP -.B \fBloadfile <url> [<flags> [<options>]]\fP -Load the given file or URL and play it. Technically, this is just a playlist -manipulation command (which either replaces the playlist or appends an entry -to it). Actual file loading happens independently. For example, a -\fBloadfile\fP command that replaces the current file with a new one returns -before the current file is stopped, and the new file even begins loading. -.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\&. -When using the client API, this can be a \fBMPV_FORMAT_NODE_MAP\fP (or a Lua -table), however the values themselves must be strings currently. These -options are set during playback, and restored to the previous value at end -of playback (see \fI\%Per\-File Options\fP). -.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. -.TP -.B <append\-play> -Append the new playlist, and if nothing is currently playing, start -playback. (Always starts with the new playlist, even if the internal -playlist was not empty before running this command.) -.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 \fBplaylist\-unshuffle\fP -Attempt to revert the previous \fBplaylist\-shuffle\fP command. This works -only once (multiple successive \fBplaylist\-unshuffle\fP commands do nothing). -May not work correctly if new recursive playlists have been opened since -a \fBplaylist\-shuffle\fP command. -.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 executable is -searched in the directories in 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: true). 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. -.TP -.B \fBdetach\fP (\fBMPV_FORMAT_FLAG\fP) -Whether to run the process in detached mode (optional, default: no). In -this mode, the process is run in a new process session, and the command -does not wait for the process to terminate. If neither -\fBcapture_stdout\fP nor \fBcapture_stderr\fP have been set to true, -the command returns immediately after the new process has been started, -otherwise the command will read as long as the pipes are open. -.TP -.B \fBenv\fP (\fBMPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]\fP) -Set a list of environment variables for the new process (default: empty). -If an empty list is passed, the environment of the mpv process is used -instead. (Unlike the underlying OS mechanisms, the mpv command cannot -start a process with empty environment. Fortunately, that is completely -useless.) The format of the list is as in the \fBexecle()\fP syscall. Each -string item defines an environment variable as in \fBNANME=VALUE\fP\&. -.sp -On Lua, you may use \fButils.get_env_list()\fP to retrieve the current -environment if you e.g. simply want to add a new variable. -.TP -.B \fBstdin_data\fP (\fBMPV_FORMAT_STRING\fP) -Feed the given string to the new process\(aq stdin. Since this is a string, -you cannot pass arbitrary binary data. If the process terminates or -closes the pipe before all data is written, the remaining data is -silently discarded. Probably does not work on win32. -.TP -.B \fBpassthrough_stdin\fP (\fBMPV_FORMAT_FLAG\fP) -If enabled, wire the new process\(aq stdin to mpv\(aqs stdin (default: no). -Before mpv 0.33.0, this argument did not exist, but the behavior was as -if this was set to true. -.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 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 true. -.TP -.B \fBkilled_by_us\fP (\fBMPV_FORMAT_FLAG\fP) -Whether the process has been killed by mpv, for example as a result of -\fBplayback_only\fP being set to true, 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 -.INDENT 7.0 -.INDENT 3.5 -.IP "Example" -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -local r = mp.command_native({ - name = "subprocess", - playback_only = false, - capture_stdout = true, - args = {"cat", "/proc/cpuinfo"}, -}) -if r.status == 0 then - print("result: " .. r.stdout) -end -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This is a fairly useless Lua example, which demonstrates how to run -a process in a blocking manner, and retrieving its stdout output. -.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> <flags>\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. -.sp -Secondary argument: -.INDENT 7.0 -.TP -.B primary (default) -Steps through the primary subtitles. -.TP -.B secondary -Steps through the secondary subtitles. -.UNINDENT -.TP -.B \fBsub\-seek <skip> <flags>\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 -Secondary argument: -.INDENT 7.0 -.TP -.B primary (default) -Seeks through the primary subtitles. -.TP -.B secondary -Seeks through the secondary subtitles. -.UNINDENT -.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 \fBdelete\-watch\-later\-config [<filename>]\fP -Delete any existing resume config file that was written by -\fBquit\-watch\-later\fP or \fBwrite\-watch\-later\-config\fP\&. If a filename is -specified, then the deleted config is for that file; otherwise, it is the -same one as would be written by \fBquit\-watch\-later\fP or -\fBwrite\-watch\-later\-config\fP in the current circumstance. -.TP -.B \fBstop [<flags>]\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. -.sp -The first argument is optional, and supports the following flags: -.INDENT 7.0 -.TP -.B keep\-playlist -Do not clear the playlist. -.UNINDENT -.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> [<albumart>]]]]\fP -Load the given video file. See \fBsub\-add\fP command for common options. -.INDENT 7.0 -.TP -.B \fBalbumart\fP (\fBMPV_FORMAT_FLAG\fP) -If enabled, mpv will load the given video as album art. -.UNINDENT -.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, -\fB\-\-audio\-file\-auto\fP and \fB\-\-cover\-art\-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 semantics are exactly the same as with option parsing (see -\fI\%VIDEO FILTERS\fP). As such the text below is a redundant and incomplete -summary. -.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 it is, remove the filter. If it isn\(aqt, 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 <remove> -Like \fBtoggle\fP, but always remove the given filter from the chain. -.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. Deprecated, use \fBremove\fP\&. -.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 vflip\fP turn the 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 -This command is deprecated, except for mpv\-internal uses. -.sp -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 -This command is deprecated, except for mpv\-internal uses. -.sp -Disable the named input section. Undoes \fBenable\-section\fP\&. -.TP -.B \fBdefine\-section <name> <contents> [<flags>]\fP -This command is deprecated, except for mpv\-internal uses. -.sp -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 \fBosd\-overlay\fP -Add/update/remove an OSD overlay. -.sp -(Although this sounds similar to \fBoverlay\-add\fP, \fBosd\-overlay\fP is for -text overlays, while \fBoverlay\-add\fP is for bitmaps. Maybe \fBoverlay\-add\fP -will be merged into \fBosd\-overlay\fP to remove this oddity.) -.sp -You can use this to add text overlays in ASS format. ASS has advanced -positioning and rendering tags, which can be used to render almost any kind -of vector graphics. -.sp -This command accepts the following parameters: -.INDENT 7.0 -.TP -.B \fBid\fP -Arbitrary integer that identifies the overlay. Multiple overlays can be -added by calling this command with different \fBid\fP parameters. Calling -this command with the same \fBid\fP replaces the previously set overlay. -.sp -There is a separate namespace for each libmpv client (i.e. IPC -connection, script), so IDs can be made up and assigned by the API user -without conflicting with other API users. -.sp -If the libmpv client is destroyed, all overlays associated with it are -also deleted. In particular, connecting via \fB\-\-input\-ipc\-server\fP, -adding an overlay, and disconnecting will remove the overlay immediately -again. -.TP -.B \fBformat\fP -String that gives the type of the overlay. Accepts the following values -(HTML rendering of this is broken, view the generated manpage instead, -or the raw RST source): -.INDENT 7.0 -.TP -.B \fBass\-events\fP -The \fBdata\fP parameter is a string. The string is split on the -newline character. Every line is turned into the \fBText\fP part of -a \fBDialogue\fP ASS event. Timing is unused (but behavior of timing -dependent ASS tags may change in future mpv versions). -.sp -Note that it\(aqs better to put multiple lines into \fBdata\fP, instead -of adding multiple OSD overlays. -.sp -This provides 2 ASS \fBStyles\fP\&. \fBOSD\fP contains the text style as -defined by the current \fB\-\-osd\-...\fP options. \fBDefault\fP is -similar, and contains style that \fBOSD\fP would have if all options -were set to the default. -.sp -In addition, the \fBres_x\fP and \fBres_y\fP options specify the value -of the ASS \fBPlayResX\fP and \fBPlayResY\fP header fields. If \fBres_y\fP -is set to 0, \fBPlayResY\fP is initialized to an arbitrary default -value (but note that the default for this command is 720, not 0). -If \fBres_x\fP is set to 0, \fBPlayResX\fP is set based on \fBres_y\fP -such that a virtual ASS pixel has a square pixel aspect ratio. -.TP -.B \fBnone\fP -Special value that causes the overlay to be removed. Most parameters -other than \fBid\fP and \fBformat\fP are mostly ignored. -.UNINDENT -.TP -.B \fBdata\fP -String defining the overlay contents according to the \fBformat\fP -parameter. -.TP -.B \fBres_x\fP, \fBres_y\fP -Used if \fBformat\fP is set to \fBass\-events\fP (see description there). -Optional, defaults to 0/720. -.TP -.B \fBz\fP -The Z order of the overlay. Optional, defaults to 0. -.sp -Note that Z order between different overlays of different formats is -static, and cannot be changed (currently, this means that bitmap -overlays added by \fBoverlay\-add\fP are always on top of the ASS overlays -added by \fBosd\-overlay\fP). In addition, the builtin OSD components are -always below any of the custom OSD. (This includes subtitles of any kind -as well as text rendered by \fBshow\-text\fP\&.) -.sp -It\(aqs possible that future mpv versions will randomly change how Z order -between different OSD formats and builtin OSD is handled. -.TP -.B \fBhidden\fP -If set to true, do not display this (default: false). -.TP -.B \fBcompute_bounds\fP -If set to true, attempt to determine bounds and write them to the -command\(aqs result value as \fBx0\fP, \fBx1\fP, \fBy0\fP, \fBy1\fP rectangle -(default: false). If the rectangle is empty, not known, or somehow -degenerate, it is not set. \fBx1\fP/\fBy1\fP is the coordinate of the -bottom exclusive corner of the rectangle. -.sp -The result value may depend on the VO window size, and is based on the -last known window size at the time of the call. This means the results -may be different from what is actually rendered. -.sp -For \fBass\-events\fP, the result rectangle is recomputed to \fBPlayRes\fP -coordinates (\fBres_x\fP/\fBres_y\fP). If window size is not known, a -fallback is chosen. -.sp -You should be aware that this mechanism is very inefficient, as it -renders the full result, and then uses the bounding box of the rendered -bitmap list (even if \fBhidden\fP is set). It will flush various caches. -Its results also depend on the used libass version. -.sp -This feature is experimental, and may change in some way again. -.UNINDENT -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Always use named arguments (\fBmpv_command_node()\fP). Lua scripts should -use the \fBmp.create_osd_overlay()\fP helper instead of invoking this -command directly. -.UNINDENT -.UNINDENT -.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\&. Note that -client names only consist of alphanumeric characters and \fB_\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\&. Note that script -names only consist of alphanumeric characters and \fB_\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). -.IP 5. 3 -The text the key would produce, or empty string if not applicable. -.UNINDENT -.sp -The 5th argument is only set if no modifiers are present (using the shift -key with a letter is normally not emitted as having a modifier, and results -in upper case text instead, but some backends may mess up). -.sp -The key state consists of 2 characters: -.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 -.sp -Future versions can add more arguments and more key state characters to -support more input peculiarities. -.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> [<mode>]\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 -The mode argument: -.INDENT 7.0 -.TP -.B \fBdefault\fP -Apply the profile. Default if the argument is omitted. -.TP -.B \fBrestore\fP -Restore options set by a previous \fBapply\-profile\fP command for this -profile. Only works if the profile has \fBprofile\-restore\fP set to a -relevant mode. Prints a warning if nothing could be done. See -\fI\%Runtime profiles\fP for details. -.UNINDENT -.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. -.sp -On success, returns a \fBmpv_node\fP with a \fBclient_id\fP field set to the -return value of the \fBmpv_client_id()\fP API call of the newly created script -handle. -.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 List of events -.sp -This is a partial list of events. This section describes what -\fBmpv_event_to_node()\fP returns, and which is what scripting APIs and the JSON -IPC sees. Note that the C API has separate C\-level declarations with -\fBmpv_event\fP, which may be slightly different. -.sp -Note that events are asynchronous: the player core continues running while -events are delivered to scripts and other clients. In some cases, you can hooks -to enforce synchronous execution. -.sp -All events can have the following fields: -.INDENT 0.0 -.TP -.B \fBevent\fP -Name as the event (as returned by \fBmpv_event_name()\fP). -.TP -.B \fBid\fP -The \fBreply_userdata\fP field (opaque user value). If \fBreply_userdata\fP is 0, -the field is not added. -.TP -.B \fBerror\fP -Set to an error string (as returned by \fBmpv_error_string()\fP). This field -is missing if no error happened, or the event type does not report error. -Most events leave this unset. -.UNINDENT -.sp -This list uses the event name field value, and the C API symbol in brackets: -.INDENT 0.0 -.TP -.B \fBstart\-file\fP (\fBMPV_EVENT_START_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). -.sp -This has the following fields: -.INDENT 7.0 -.TP -.B \fBplaylist_entry_id\fP -Playlist entry ID of the file being loaded now. -.UNINDENT -.TP -.B \fBend\-file\fP (\fBMPV_EVENT_END_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 following fields: -.INDENT 7.0 -.TP -.B \fBreason\fP -Has 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 \fBplaylist_entry_id\fP -Playlist entry ID of the file that was being played or attempted to be -played. This has the same value as the \fBplaylist_entry_id\fP field in the -corresponding \fBstart\-file\fP event. -.TP -.B \fBfile_error\fP -Set to mpv error string describing the approximate reason why playback -failed. Unset if no error known. (In Lua scripting, this value was set -on the \fBerror\fP field directly. This is deprecated since mpv 0.33.0. -In the future, this \fBerror\fP field will be unset for this specific -event.) -.TP -.B \fBplaylist_insert_id\fP -If loading ended, because the playlist entry to be played was for example -a playlist, and the current playlist entry is replaced with a number of -other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT -(other event types may use this for similar but different purposes in the -future). In this case, playlist_insert_id will be set to the playlist -entry ID of the first inserted entry, and playlist_insert_num_entries to -the total number of inserted playlist entries. Note this in this specific -case, the ID of the last inserted entry is playlist_insert_id+num\-1. -Beware that depending on circumstances, you may observe the new playlist -entries before seeing the event (e.g. reading the "playlist" property or -getting a property change notification before receiving the event). -If this is 0 in the C API, this field isn\(aqt added. -.TP -.B \fBplaylist_insert_num_entries\fP -See playlist_insert_id. Only present if playlist_insert_id is present. -.UNINDENT -.TP -.B \fBfile\-loaded\fP (\fBMPV_EVENT_FILE_LOADED\fP) -Happens after a file was loaded and begins playback. -.TP -.B \fBseek\fP (\fBMPV_EVENT_SEEK\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 (\fBMPV_EVENT_PLAYBACK_RESTART\fP) -Start of playback after seek or after file was loaded. -.TP -.B \fBshutdown\fP (\fBMPV_EVENT_SHUTDOWN\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 (\fBMPV_EVENT_LOG_MESSAGE\fP) -Receives messages enabled with \fBmpv_request_log_messages()\fP (Lua: -\fBmp.enable_messages\fP). -.sp -This 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 \fBhook\fP -The event has the following fields: -.INDENT 7.0 -.TP -.B \fBhook_id\fP -ID to pass to \fBmpv_hook_continue()\fP\&. The Lua scripting wrapper -provides a better API around this with \fBmp.add_hook()\fP\&. -.UNINDENT -.TP -.B \fBget\-property\-reply\fP (\fBMPV_EVENT_GET_PROPERTY_REPLY\fP) -See C API. -.TP -.B \fBset\-property\-reply\fP (\fBMPV_EVENT_SET_PROPERTY_REPLY\fP) -See C API. -.TP -.B \fBcommand\-reply\fP (\fBMPV_EVENT_COMMAND_REPLY\fP) -This is one of the commands for which the \fB\(gaerror\fP field is meaningful. -.sp -JSON IPC and Lua and possibly other backends treat this specially and may -not pass the actual event to the user. See C API. -.sp -The event has the following fields: -.INDENT 7.0 -.TP -.B \fBresult\fP -The result (on success) of any \fBmpv_node\fP type, if any. -.UNINDENT -.TP -.B \fBclient\-message\fP (\fBMPV_EVENT_CLIENT_MESSAGE\fP) -Lua and possibly other backends treat this specially and may not pass the -actual event to the user. -.sp -The event has the following fields: -.INDENT 7.0 -.TP -.B \fBargs\fP -Array of strings with the message data. -.UNINDENT -.TP -.B \fBvideo\-reconfig\fP (\fBMPV_EVENT_VIDEO_RECONFIG\fP) -Happens on video output or filter reconfig. -.TP -.B \fBaudio\-reconfig\fP (\fBMPV_EVENT_AUDIO_RECONFIG\fP) -Happens on audio output or filter reconfig. -.TP -.B \fBproperty\-change\fP (\fBMPV_EVENT_PROPERTY_CHANGE\fP) -Happens when a property that is being observed changes value. -.sp -The event has the following fields: -.INDENT 7.0 -.TP -.B \fBname\fP -The name of the property. -.TP -.B \fBdata\fP -The new value of the property. -.UNINDENT -.UNINDENT -.sp -The following events also happen, but are deprecated: \fBtracks\-changed\fP, -\fBtrack\-switched\fP, \fBpause\fP, \fBunpause\fP, \fBmetadata\-update\fP, \fBidle\fP, -\fBtick\fP, \fBchapter\-change\fP\&. Use \fBmpv_observe_property()\fP -(Lua: \fBmp.observe_property()\fP) instead. -.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 -Before a hook is actually invoked on an API clients, it will attempt to return -new values for all observed properties that were changed before the hook. This -may make it easier for an application to set defined "barriers" between property -change notifications by registering hooks. (That means these hooks will have an -effect, even if you do nothing and make them continue immediately.) -.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. -.sp -Ordered after \fBstart\-file\fP and before \fBplayback\-restart\fP\&. -.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. If it fails again, this hook is _not_ called again, and -loading definitely fails. -.sp -Ordered after \fBon_load\fP, and before \fBplayback\-restart\fP and \fBend\-file\fP\&. -.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. -.sp -Ordered after \fBon_load_fail\fP etc. and before \fBplayback\-restart\fP\&. -.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. -.sp -Ordered before \fBend\-file\fP\&. Will also happen in the error case (then after -\fBon_load_fail\fP). -.TP -.B \fBon_before_start_file\fP -Run before a \fBstart\-file\fP event is sent. (If any client changes the -current playlist entry, or sends a quit command to the player, the -corresponding event will not actually happen after the hook returns.) -Useful to drain property changes before a new file is loaded. -.TP -.B \fBon_after_end_file\fP -Run after an \fBend\-file\fP event. Useful to drain property changes after a -file has finished. -.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. For a list of commands: -the first command determines the repeatability of the whole list (up to and -including version 0.33 \- a list was always repeatable). -.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 below, see -\fI\%OPTIONS\fP instead. Only properties which do not exist as option with the -same name, or which have very different behavior from the options are -documented below. -.sp -Properties marked as (RW) are writeable, while those that aren\(aqt are -read\-only. -.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 -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 \fBpid\fP -Process\-id of mpv. -.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 from -\fBpath\fP only 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 -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. -.sp -Before mpv 0.31.0, this showed the actual edition selected at runtime, if -you didn\(aqt set the option or property manually. With mpv 0.31.0 and later, -this strictly returns the user\-set option or property value, and the -\fBcurrent\-edition\fP property was added to return the runtime selected -edition (this matters with \fB\-\-edition=auto\fP, the default). -.TP -.B \fBcurrent\-edition\fP -Currently selected edition. This property is unavailable if no file is -loaded, or the file has no editions. (Matroska files make a difference -between having no editions and a single edition, which will be reflected by -the property, although in practice it does not matter.) -.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 (RW) -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 -Whether this is the default edition. -.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 -Returns \fByes\fP/true 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 -Whether the playback core is paused. This can differ from \fBpause\fP in -special situations, such as when the player pauses itself due to low -network cache. -.sp -This also returns \fByes\fP/true if playback is restarting or if nothing is -playing at all. In other words, it\(aqs only \fBno\fP/false if there\(aqs actually -video playing. (Behavior since mpv 0.7.0.) -.TP -.B \fBcache\-speed\fP -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). -.sp -This is the same as \fBdemuxer\-cache\-state/raw\-input\-rate\fP\&. -.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 -Whether the demuxer is idle, which means that the demuxer cache is filled -to the requested amount, and is currently not reading more data. -.TP -.B \fBdemuxer\-cache\-state\fP -Each entry in \fBseekable\-ranges\fP represents a region in the demuxer cache -that can be seeked to, with a \fBstart\fP and \fBend\fP fields containing the -respective timestamps. 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 true, 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 wasn\(aqt enabled with -\fB\-\-cache\-on\-disk=yes\fP\&. -.sp -\fBcache\-end\fP is \fBdemuxer\-cache\-time\fP\&. Missing if unavailable. -.sp -\fBreader\-pts\fP is the approximate timestamp of the start of the buffered -range. Missing if unavailable. -.sp -\fBcache\-duration\fP is \fBdemuxer\-cache\-duration\fP\&. Missing if unavailable. -.sp -\fBraw\-input\-rate\fP is the estimated input rate of the network layer (or any -other byte\-oriented input layer) in bytes per second. May be inaccurate or -missing. -.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 - "cache\-end" MPV_FORMAT_DOUBLE - "reader\-pts" MPV_FORMAT_DOUBLE - "cache\-duration" MPV_FORMAT_DOUBLE - "raw\-input\-rate" 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 -Whether the reader thread has hit the end of the file. -.TP -.B \fBunderrun\fP -Whether the reader thread could not satisfy a decoder\(aqs request for a -new packet. -.TP -.B \fBidle\fP -Whether 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 -Whether 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 -The start time reported by the demuxer in fractional seconds. -.TP -.B \fBpaused\-for\-cache\fP -Whether playback is paused because of waiting for the cache. -.TP -.B \fBcache\-buffering\-state\fP -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 -Whether the end of playback was reached. 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 -Whether the player is currently seeking, or otherwise trying to restart -playback. (It\(aqs possible that it returns \fByes\fP/true while a file is -loaded. This is because the same underlying code is used for seeking and -resyncing.) -.TP -.B \fBmixer\-active\fP -Whether the audio mixer is active. -.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 -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 -See \fBcolormatrix\fP\&. -.TP -.B \fBcolormatrix\-primaries\fP -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 -The current hardware decoding in use. If decoding is active, return one of -the values used by the \fBhwdec\fP option/property. \fBno\fP/false 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/hw\-pixelformat\fP -The underlying pixel format as string. This is relevant for some cases -of hardware decoding and unavailable otherwise. -.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/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.) -.TP -.B \fBvideo\-params/alpha\fP -Alpha type. If the format has no alpha channel, this will be unavailable -(but in future releases, it could change to \fBno\fP). If alpha is -present, this is set to \fBstraight\fP or \fBpremul\fP\&. -.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 - "hw\-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 - "average\-bpp" MPV_FORMAT_INT64 - "alpha" 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 -This has a number of sub\-properties: -.INDENT 7.0 -.TP -.B \fBvideo\-frame\-info/picture\-type\fP -The type of the picture. It can be "I" (intra), "P" (predicted), "B" -(bi\-dir predicted) or unavailable. -.TP -.B \fBvideo\-frame\-info/interlaced\fP -Whether the content of the frame is interlaced. -.TP -.B \fBvideo\-frame\-info/tff\fP -If the content is interlaced, whether the top field is displayed first. -.TP -.B \fBvideo\-frame\-info/repeat\fP -Whether the frame must be delayed when decoding. -.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. -.sp -Note that setting a value identical to its previous value will not resize -the window. That\(aqs because this property mirrors the \fBwindow\-scale\fP -option, and setting an option to its previous value is ignored. If this -value is set while the window is in a fullscreen, the multiplier is not -applied until the window is taken out of that state. Writing this property -to a maximized window can unmaximize the window depending on the OS and -window manager. If the window does not unmaximize, the multiplier will be -applied if the user unmaximizes the window later. -.sp -See \fBcurrent\-window\-scale\fP for the value derived from the actual window -size. -.sp -Since mpv 0.31.0, this always returns the previously set value (or the -default value), instead of the value implied by the actual window size. -Before mpv 0.31.0, this returned what \fBcurrent\-window\-scale\fP returns now, -after the window was created. -.TP -.B \fBcurrent\-window\-scale\fP (RW) -The \fBwindow\-scale\fP value calculated from the current window size. This -has the same value as \fBwindow\-scale\fP if the window size was not changed -since setting the option, and the window size was not restricted in other -ways. If the window is fullscreened, this will return the scale value -calculated from the last non\-fullscreen size of the window. The property -is unavailable if no video is active. -.sp -When setting this property in the fullscreen or maximized state, the behavior -is the same as window\-scale. In all ther cases, setting the value of this -property will always resize the window. This does not affect the value of -\fBwindow\-scale\fP\&. -.TP -.B \fBfocused\fP -Whether the window has focus. Might not be supported by all VOs. -.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 -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. -.sp -Writing to this property is deprecated. It has the same effect as writing to -\fBoverride\-display\-fps\fP\&. Since mpv 0.31.0, this property is unavailable -if no display FPS was reported (e.g. if no video is active), while in older -versions, it returned the \fB\-\-display\-fps\fP option value. -.TP -.B \fBestimated\-display\-fps\fP -The actual rate at which display refreshes seem to occur, measured by -system time. Only available if display\-sync mode (as selected by -\fB\-\-video\-sync\fP) is active. -.TP -.B \fBvsync\-jitter\fP -Estimated deviation factor of the vsync duration. -.TP -.B \fBdisplay\-width\fP, \fBdisplay\-height\fP -The current display\(aqs horizontal and vertical resolution in pixels. Whether -or not these values update as the mpv window changes displays depends on -the windowing backend. It may not be available on all platforms. -.TP -.B \fBdisplay\-hidpi\-scale\fP -The HiDPI scale factor as reported by the windowing backend. If no VO is -active, or if the VO does not report a value, this property is unavailable. -It may be saner to report an absolute DPI, however, this is the way HiDPI -support is implemented on most OS APIs. See also \fB\-\-hidpi\-window\-scale\fP\&. -.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/window size (not -including decorations drawn by the OS window manager). -.sp -Alias to \fBosd\-dimensions/w\fP and \fBosd\-dimensions/h\fP\&. -.TP -.B \fBosd\-par\fP -Last known OSD display pixel aspect (can be 0). -.sp -Alias to \fBosd\-dimensions/osd\-par\fP\&. -.TP -.B \fBosd\-dimensions\fP -Last known OSD dimensions. -.sp -Has the following sub\-properties (which can be read as \fBMPV_FORMAT_NODE\fP -or Lua table with \fBmp.get_property_native\fP): -.INDENT 7.0 -.TP -.B \fBosd\-dimensions/w\fP -Size of the VO window in OSD render units (usually pixels, but may be -scaled pixels with VOs like \fBxv\fP). -.TP -.B \fBosd\-dimensions/h\fP -Size of the VO window in OSD render units, -.TP -.B \fBosd\-dimensions/par\fP -Pixel aspect ratio of the OSD (usually 1). -.TP -.B \fBosd\-dimensions/aspect\fP -Display aspect ratio of the VO window. (Computing from the properties -above.) -.TP -.B \fBosd\-dimensions/mt\fP, \fBosd\-dimensions/mb\fP, \fBosd\-dimensions/ml\fP, \fBosd\-dimensions/mr\fP -OSD to video margins (top, bottom, left, right). This describes the -area into which the video is rendered. -.UNINDENT -.sp -Any of these properties may be unavailable or set to dummy values if the -VO window is not created or visible. -.TP -.B \fBmouse\-pos\fP -Read\-only \- last known mouse position, normalizd to OSD dimensions. -.sp -Has the following sub\-properties (which can be read as \fBMPV_FORMAT_NODE\fP -or Lua table with \fBmp.get_property_native\fP): -.INDENT 7.0 -.TP -.B \fBmouse\-pos/x\fP, \fBmouse\-pos/y\fP -Last known coordinates of the mouse pointer. -.TP -.B \fBmouse\-pos/hover\fP -Boolean \- whether the mouse pointer hovers the video window. The -coordinates should be ignored when this value is false, because the -video backends update them only when the pointer hovers the window. -.UNINDENT -.TP -.B \fBsub\-text\fP -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\-text\-ass\fP -Like \fBsub\-text\fP, but return the text in ASS format. Text subtitles in -other formats are converted. For native ASS subtitles, events that do -not contain any text (but vector drawings etc.) are not filtered out. If -multiple events match with the current playback time, they are concatenated -with line breaks. Contains only the "Text" part of the events. -.sp -This property is not enough to render ASS subtitles correctly, because ASS -header and per\-event metadata are not returned. You likely need to do -further filtering on the returned string to make it useful. -.sp -This property is experimental and might be removed in the future. -.TP -.B \fBsecondary\-sub\-text\fP -Same as \fBsub\-text\fP, but for the secondary subtitles. -.TP -.B \fBsub\-start\fP -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 \fBsecondary\-sub\-start\fP -Same as \fBsub\-start\fP, but for the secondary subtitles. -.TP -.B \fBsub\-end\fP -The current subtitle end 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 \fBsecondary\-sub\-end\fP -Same as \fBsub\-end\fP, but for the secondary subtitles. -.TP -.B \fBplaylist\-pos\fP (RW) -Current position on playlist. The first entry is on position 0. Writing to -this property may start playback at the new position. -.sp -In some cases, this is not necessarily the currently playing file. See -explanation of \fBcurrent\fP and \fBplaying\fP flags in \fBplaylist\fP\&. -.sp -If there the playlist is empty, or if it\(aqs non\-empty, but no entry is -"current", this property returns \-1. Likewise, writing \-1 will put the -player into idle mode (or exit playback if idle mode is not enabled). If an -out of range index is written to the property, this behaves as if writing \-1. -(Before mpv 0.33.0, instead of returning \-1, this property was unavailable -if no playlist entry was current.) -.sp -Writing the current value back to the property is subject to change. -Currently, it will restart playback of the playlist entry. But in the -future, writing the current value will be ignored. Use the -\fBplaylist\-play\-index\fP command to get guaranteed behavior. -.TP -.B \fBplaylist\-pos\-1\fP (RW) -Same as \fBplaylist\-pos\fP, but 1\-based. -.TP -.B \fBplaylist\-current\-pos\fP (RW) -Index of the "current" item on playlist. This usually, but not necessarily, -the currently playing item (see \fBplaylist\-playing\-pos\fP). Depending on the -exact internal state of the player, it may refer to the playlist item to -play next, or the playlist item used to determine what to play next. -.sp -For reading, this is exactly the same as \fBplaylist\-pos\fP\&. -.sp -For writing, this \fIonly\fP sets the position of the "current" item, without -stopping playback of the current file (or starting playback, if this is done -in idle mode). Use \-1 to remove the current flag. -.sp -This property is only vaguely useful. If set during playback, it will -typically cause the playlist entry \fIafter\fP it to be played next. Another -possibly odd observable state is that if \fBplaylist\-next\fP is run during -playback, this property is set to the playlist entry to play next (unlike -the previous case). There is an internal flag that decides whether the -current playlist entry or the next one should be played, and this flag is -currently inaccessible for API users. (Whether this behavior will kept is -possibly subject to change.) -.TP -.B \fBplaylist\-playing\-pos\fP -Index of the "playing" item on playlist. A playlist item is "playing" if -it\(aqs being loaded, actually playing, or being unloaded. This property is set -during the \fBMPV_EVENT_START_FILE\fP (\fBstart\-file\fP) and the -\fBMPV_EVENT_START_END\fP (\fBend\-file\fP) events. Outside of that, it returns -\-1. If the playlist entry was somehow removed during playback, but playback -hasn\(aqt stopped yet, or is in progress of being stopped, it also returns \-1. -(This can happen at least during state transitions.) -.sp -In the "playing" state, this is usually the same as \fBplaylist\-pos\fP, except -during state changes, or if \fBplaylist\-current\-pos\fP was written explicitly. -.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/playing\fP -\fByes\fP/true if the \fBplaylist\-playing\-pos\fP property points to this -entry, \fBno\fP/false or unavailable otherwise. -.TP -.B \fBplaylist/N/current\fP -\fByes\fP/true if the \fBplaylist\-current\-pos\fP property points to this -entry, \fBno\fP/false or unavailable otherwise. -.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. -.TP -.B \fBplaylist/N/id\fP -Unique ID for this entry. This is an automatically assigned integer ID -that is unique for the entire life time of the current mpv core -instance. Other commands, events, etc. use this as \fBplaylist_entry_id\fP -fields. -.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) - "id" MPV_FORMAT_INT64 -.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. (It is -missing if the format has no native ID, if the track is a pseudo\-track -that does not exist in this way in the actual file, or if the format -is handled by libavformat, and the format was not whitelisted as having -track IDs.) -.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/image\fP -\fByes\fP/true if this is a video track that consists of a single -picture, \fBno\fP/false or unavailable otherwise. The heuristic used to -determine if a stream is an image doesn\(aqt attempt to detect images in -codecs normally used for videos. Otherwise, it is reliable. -.TP -.B \fBtrack\-list/N/albumart\fP -\fByes\fP/true if this is an image embedded in an audio file or external -cover art, \fBno\fP/false or unavailable otherwise. -.TP -.B \fBtrack\-list/N/default\fP -\fByes\fP/true if the track has the default flag set in the file, -\fBno\fP/false or unavailable otherwise. -.TP -.B \fBtrack\-list/N/forced\fP -\fByes\fP/true if the track has the forced flag set in the file, -\fBno\fP/false or unavailable 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/true if the track is an external file, \fBno\fP/false or -unavailable 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/true if the track is currently decoded, \fBno\fP/false or -unavailable otherwise. -.TP -.B \fBtrack\-list/N/main\-selection\fP -It indicates the selection order of tracks for the same type. -If a track is not selected, or is selected by the \fB\-\-lavfi\-complex\fP, -it is not available. For subtitle tracks, \fB0\fP represents the \fBsid\fP, -and \fB1\fP represents the \fBsecondary\-sid\fP\&. -.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 - "image" MPV_FORMAT_FLAG - "albumart" MPV_FORMAT_FLAG - "default" MPV_FORMAT_FLAG - "forced" MPV_FORMAT_FLAG - "selected" MPV_FORMAT_FLAG - "main\-selection" MPV_FORMAT_INT64 - "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 \fBcurrent\-tracks/...\fP -This gives access to currently selected tracks. It redirects to the correct -entry in \fBtrack\-list\fP\&. -.sp -The following sub\-entries are defined: \fBvideo\fP, \fBaudio\fP, \fBsub\fP, -\fBsub2\fP -.sp -For example, \fBcurrent\-tracks/audio/lang\fP returns the current audio track\(aqs -language field (the same value as \fBtrack\-list/N/lang\fP). -.sp -If tracks of the requested type are selected via \fB\-\-lavfi\-complex\fP, the -first one is returned. -.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 -Whether it\(aqs generally possible to seek in the current file. -.TP -.B \fBpartially\-seekable\fP -Whether 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 \fByes\fP/true, so will \fBseekable\fP\&. -.TP -.B \fBplayback\-abort\fP -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\-msg3=\(aqThis is ${osd\-ass\-cc/0}{\e\eb1}bold text\(aq\fP -.IP \(bu 2 -\fBshow\-text "This is ${osd\-ass\-cc/0}{\e\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. See -\fI\%Flat command syntax\fP for details. -.sp -A list of tags can be found here: \fI\%http://docs.aegisub.org/latest/ASS_Tags/\fP -.TP -.B \fBvo\-configured\fP -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 -usually always returns \fByes\fP/true. -.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 \fBperf\-info\fP -Further performance data. Querying this property triggers internal -collection of some data, and may slow down the player. Each query will reset -some internal state. Property change notification doesn\(aqt and won\(aqt work. -All of this may change in the future, so don\(aqt use this. The builtin -\fBstats\fP script is supposed to be the only user; since it\(aqs bundled and -built with the source code, it can use knowledge of mpv internal to render -the information properly. See \fBstats\fP script description for some details. -.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 -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 \fBshared\-script\-properties\fP (RW) -This is a key/value map of arbitrary strings shared between scripts for -general use. The player itself does not use any data in it (although some -builtin scripts may). The property is not preserved across player restarts. -.sp -This is very primitive, inefficient, and annoying to use. It\(aqs a makeshift -solution which could go away any time (for example, when a better solution -becomes available). This is also why this property has an annoying name. You -should avoid using it, unless you absolutely have to. -.sp -Lua scripting has helpers starting with \fButils.shared_script_property_\fP\&. -They are undocumented because you should not use this property. If you still -think you must, you should use the helpers instead of the property directly. -.sp -You are supposed to use the \fBchange\-list\fP command to modify the contents. -Reading, modifying, and writing the property manually could data loss if two -scripts update different keys at the same time due to lack of -synchronization. The Lua helpers take care of this. -.sp -(There is no way to ensure synchronization if two scripts try to update the -same key at the same time.) -.TP -.B \fBworking\-directory\fP -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 \fBinput\-key\-list\fP -List of \fI\%Key names\fP, same as output by \fB\-\-input\-keylist\fP\&. -.TP -.B \fBmpv\-version\fP -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 -The configuration arguments which were passed to the build system -(typically the way \fB\&./waf configure ...\fP was invoked). -.TP -.B \fBffmpeg\-version\fP -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 \fBlibass\-version\fP -The value of \fBass_library_version()\fP\&. This is an integer, encoded in a -somewhat weird form (apparently "hex BCD"), indicating the release version -of the libass library linked to mpv. -.TP -.B \fBoptions/<name>\fP (RW) -The 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 (RW) -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 -The name of the option. -.TP -.B \fBoption\-info/<name>/type\fP -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 -Whether the option was set from the mpv command line. 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 -Whether 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 -The list of top\-level properties. -.TP -.B \fBprofile\-list\fP -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. -.TP -.B \fBcommand\-list\fP -The list of input commands. This returns an array of maps, where each map -node represents a command. This map currently only has a single entry: -\fBname\fP for the name of the command. (This property is supposed to be a -replacement for \fB\-\-input\-cmdlist\fP\&. The option dumps some more -information, but it\(aqs a valid feature request to extend this property if -needed.) -.TP -.B \fBinput\-bindings\fP -The list of current input key bindings. This returns an array of maps, -where each map node represents a binding for a single key/command. This map -has the following entries: -.INDENT 7.0 -.TP -.B \fBkey\fP -The key name. This is normalized and may look slightly different from -how it was specified in the source (e.g. in input.conf). -.TP -.B \fBcmd\fP -The command mapped to the key. (Currently, this is exactly the same -string as specified in the source, other than stripping whitespace and -comments. It\(aqs possible that it will be normalized in the future.) -.TP -.B \fBis_weak\fP -If set to true, any existing and active user bindings will take priority. -.TP -.B \fBowner\fP -If this entry exists, the name of the script (or similar) which added -this binding. -.TP -.B \fBsection\fP -Name of the section this binding is part of. This is a rarely used -mechanism. This entry may be removed or change meaning in the future. -.TP -.B \fBpriority\fP -A number. Bindings with a higher value are preferred over bindings -with a lower value. If the value is negative, this binding is inactive -and will not be triggered by input. Note that mpv does not use this -value internally, and matching of bindings may work slightly differently -in some cases. In addition, this value is dynamic and can change around -at runtime. -.TP -.B \fBcomment\fP -If available, the comment following the command on the same line. (For -example, the input.conf entry \fBf cycle bla # toggle bla\fP would -result in an entry with \fBcomment = "toggle bla", cmd = "cycle bla"\fP\&.) -.UNINDENT -.sp -This property is read\-only, and change notification is not supported. -Currently, there is no mechanism to change key bindings at runtime, other -than scripts adding or removing their own bindings. -.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, these return the actually active tracks. For -example, if you set \fBaid=5\fP, and the currently played file contains no -audio track with ID 5, the \fBaid\fP property will return \fBno\fP\&. -.sp -Before mpv 0.31.0, you could set existing tracks at runtime only. -.TP -.B \fBdisplay\-fps\fP -This inconsistent behavior is deprecated. Post\-deprecation, the reported -value and the option value are cleanly separated (\fBoverride\-display\-fps\fP -for the option value). -.TP -.B \fBvf\fP, \fBaf\fP -If you set the properties during playback, and the filter chain fails to -reinitialize, the option will be set, but the runtime filter chain does not -change. On the other hand, the next video to be played will fail, because -the initial filter chain cannot be created. -.sp -This behavior changed in mpv 0.31.0. Before this, the new value was rejected -\fIiff\fP a video (for \fBvf\fP) or an audio (for \fBaf\fP) track was active. If -playback was not active, the behavior was the same as the current one. -.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 \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 -Whether property expansion is enabled by default depends on which API is used -(see \fI\%Flat command syntax\fP, \fI\%Commands specified as arrays\fP and \fI\%Named -arguments\fP), but it can always be enabled with the \fBexpand\-properties\fP -prefix or disabled with the \fBraw\fP prefix, as described in \fI\%Input Command -Prefixes\fP\&. -.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, custom title, or target chapter -name while hovering the seekbar. -.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. If set to \fByes\fP, -default seeking mode is used (usually keyframes, but player defaults and -heuristics can change it to exact). If set to \fBno\fP, 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.) Additionally, \fBvisibility\fP must be set to \fBalways\fP\&. -Otherwise, this option does nothing. -.sp -Currently, this is supported for the \fBbottombar\fP and \fBtopbar\fP layout -only. The other layouts do not change if this option is set. Separately, -if window controls are present (see below), they will be affected -regardless of which osc layout is in use. -.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. -.sp -This does not work correctly with video outputs like \fB\-\-vo=xv\fP, which -render OSD into the unscaled video. -.TP -.B \fBwindowcontrols\fP -Default: auto (Show window controls if there is no window border) -.sp -Whether to show window management controls over the video, and if so, -which side of the window to place them. This may be desirable when the -window has no decorations, either because they have been explicitly -disabled (\fBborder=no\fP) or because the current platform doesn\(aqt support -them (eg: gnome\-shell with wayland). -.sp -The set of window controls is fixed, offering \fBminimize\fP, \fBmaximize\fP, -and \fBquit\fP\&. Not all platforms implement \fBminimize\fP and \fBmaximize\fP, -but \fBquit\fP will always work. -.TP -.B \fBwindowcontrols_alignment\fP -Default: right -.sp -If window controls are shown, indicates which side should they be aligned -to. -.sp -Supports \fBleft\fP and \fBright\fP which will place the controls on those -respective sides. -.TP -.B \fBgreenandgrumpy\fP -Default: no -.sp -Set to \fByes\fP to reduce festivity (i.e. disable santa hat in December.) -.TP -.B \fBlivemarkers\fP -Default: yes -.sp -Update chapter markers positions on duration changes, e.g. live streams. -The updates are unoptimized \- consider disabling it on very low\-end systems. -.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 (scroll) -T} -_ -T{ -3 -T} T{ -Input cache stats -T} -_ -T{ -4 -T} T{ -Active key bindings (scroll) -T} -_ -T{ -0 -T} T{ -Internal stuff (scroll) -T} -_ -.TE -.sp -On pages which support scroll, these key bindings are also active: -.TS -center; -|l|l|. -_ -T{ -UP -T} T{ -Scroll one line up -T} -_ -T{ -DOWN -T} T{ -Scroll one line down -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_page_1\fP -Default: 1 -.TP -.B \fBkey_page_2\fP -Default: 2 -.TP -.B \fBkey_page_3\fP -Default: 3 -.TP -.B \fBkey_page_4\fP -Default: 4 -.TP -.B \fBkey_page_0\fP -Default: 0 -.sp -Key bindings for page switching while stats are displayed. -.TP -.B \fBkey_scroll_up\fP -Default: UP -.TP -.B \fBkey_scroll_down\fP -Default: DOWN -.TP -.B \fBscroll_lines\fP -Default: 1 -.sp -Scroll key bindings and number of lines to scroll on pages which support it. -.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 -Additional keys can be configured in \fBinput.conf\fP to display the stats: -.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 -And to display a certain page directly: -.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 -.SS Active key bindings page -.sp -Lists the active key bindings and the commands they\(aqre bound to, excluding the -interactive keys of the stats script itself. See also \fB\-\-input\-test\fP for more -detailed view of each binding. -.sp -The keys are grouped automatically using a simple analysis of the command -string, and one should not expect documentation\-level grouping accuracy, -however, it should still be reasonably useful. -.sp -Using \fB\-\-idle \-\-script\-opts=stats\-bindlist=yes\fP will print the list to the -terminal and quit immediately. By default long lines are shortened to 79 chars, -and terminal escape sequences are enabled. A different length limit can be -set by changing \fByes\fP to a number (at least 40), and escape sequences can be -disabled by adding \fB\-\fP before the value, e.g. \fB\&...=\-yes\fP or \fB\&...=\-120\fP\&. -.sp -Like with \fB\-\-input\-test\fP, the list includes bindings from \fBinput.conf\fP and -from user scripts. Use \fB\-\-no\-config\fP to list only built\-in bindings. -.SS Internal stuff page -.sp -Most entries shown on this page have rather vague meaning. Likely none of this -is useful for you. Don\(aqt attempt to use it. Forget its existence. -.sp -Selecting this for the first time will start collecting some internal -performance data. That means performance will be slightly lower than normal for -the rest of the time the player is running (even if the stats page is closed). -Note that the stats page itself uses a lot of CPU and even GPU resources, and -may have a heavy impact on performance. -.sp -The displayed information is accumulated over the redraw delay (shown as -\fBpoll\-time\fP field). -.sp -This adds entries for each Lua script. If there are too many scripts running, -parts of the list will simply be out of the screen, but it can be scrolled. -.sp -If the underlying platform does not support pthread per thread times, the -displayed times will be 0 or something random (I suspect that at time of this -writing, only Linux provides the correct via pthread APIs for per thread times). -.sp -Most entries are added lazily and only during data collection, which is why -entries may pop up randomly after some time. It\(aqs also why the memory usage -entries for scripts that have been inactive since the start of data collection -are missing. -.sp -Memory usage is approximate and does not reflect internal fragmentation. -.sp -JS scripts memory reporting is disabled by default because collecting the data -at the JS side has an overhead. It can be enabled by exporting the env var -\fBMPV_LEAK_REPORT=1\fP before starting mpv, and will increase JS memory usage. -.sp -If entries have \fB/time\fP and \fB/cpu\fP variants, the former gives the real time -(monotonic clock), while the latter the thread CPU time (only if the -corresponding pthread API works and is supported). -.SH CONSOLE -.sp -The console is a REPL for mpv input commands. It is displayed on the video -window. It also shows log messages. It can be disabled entirely using the -\fB\-\-load\-osd\-console=no\fP option. -.SS Keybindings -.INDENT 0.0 -.TP -.B \(ga -Show the console. -.TP -.B ESC -Hide the console. -.TP -.B ENTER, Ctrl+J and Ctrl+M -Run the typed command. -.TP -.B Shift+ENTER -Type a literal newline character. -.TP -.B LEFT and Ctrl+B -Move the cursor to the previous character. -.TP -.B RIGHT and Ctrl+F -Move the cursor to the next character. -.TP -.B Ctrl+LEFT and Alt+B -Move the cursor to the beginning of the current word, or if between words, -to the beginning of the previous word. -.TP -.B Ctrl+RIGHT and Alt+F -Move the cursor to the end of the current word, or if between words, to the -end of the next word. -.TP -.B HOME and Ctrl+A -Move the cursor to the start of the current line. -.TP -.B END and Ctrl+E -Move the cursor to the end of the current line. -.TP -.B BACKSPACE and Ctrl+H -Delete the previous character. -.TP -.B Ctrl+D -Hide the console if the current line is empty, otherwise delete the next -character. -.TP -.B Ctrl+BACKSPACE and Ctrl+W -Delete text from the cursor to the beginning of the current word, or if -between words, to the beginning of the previous word. -.TP -.B Ctrl+DEL and Alt+D -Delete text from the cursor to the end of the current word, or if between -words, to the end of the next word. -.TP -.B Ctrl+U -Delete text from the cursor to the beginning of the current line. -.TP -.B Ctrl+K -Delete text from the cursor to the end of the current line. -.TP -.B Ctrl+C -Clear the current line. -.TP -.B UP and Ctrl+P -Move back in the command history. -.TP -.B DOWN and Ctrl+N -Move forward in the command history. -.TP -.B PGUP -Go to the first command in the history. -.TP -.B PGDN -Stop navigating the command history. -.TP -.B INSERT -Toggle insert mode. -.TP -.B Ctrl+V -Paste text (uses the clipboard on X11 and Wayland). -.TP -.B Shift+INSERT -Paste text (uses the primary selection on X11 and Wayland). -.TP -.B TAB and Ctrl+I -Complete the command or property name at the cursor. -.TP -.B Ctrl+L -Clear all log messages from the console. -.UNINDENT -.SS Commands -.INDENT 0.0 -.TP -.B \fBscript\-message\-to console type <text> [<cursor_pos>]\fP -Show the console and pre\-fill it with the provided text, optionally -specifying the initial cursor position as a positive integer starting from -1. -.INDENT 7.0 -.INDENT 3.5 -.IP "Example for input.conf" -.sp -\fB% script\-message\-to console type "seek absolute\-percent" 6\fP -.UNINDENT -.UNINDENT -.UNINDENT -.SS Known issues -.INDENT 0.0 -.IP \(bu 2 -Pasting text is slow on Windows -.IP \(bu 2 -Non\-ASCII keyboard input has restrictions -.IP \(bu 2 -The cursor keys move between Unicode code\-points, not grapheme clusters -.UNINDENT -.SS Configuration -.sp -This script can be customized through a config file \fBscript\-opts/console.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\&. -.sp -Key bindings can be changed in a standard way, see for example stats.lua -documentation. -.SS Configurable Options -.INDENT 0.0 -.TP -.B \fBscale\fP -Default: 1 -.sp -All drawing is scaled by this value, including the text borders and the -cursor. -.sp -If the VO backend in use has HiDPI scale reporting implemented, the option -value is scaled with the reported HiDPI scale. -.TP -.B \fBfont\fP -Default: unset (picks a hardcoded font depending on detected platform) -.sp -Set the font used for the REPL and the console. This probably doesn\(aqt -have to be a monospaced font. -.TP -.B \fBfont_size\fP -Default: 16 -.sp -Set the font size used for the REPL and the console. This will be -multiplied by "scale." -.UNINDENT -.SH LUA SCRIPTING -.sp -mpv can load Lua scripts. (See \fI\%Script location\fP\&.) -.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 Script location -.sp -Scripts can be passed to the \fB\-\-script\fP option, and are automatically loaded -from the \fBscripts\fP subdirectory of the mpv configuration directory (usually -\fB~/.config/mpv/scripts/\fP). -.sp -A script can be a single file. The file extension is used to select the -scripting backend to use for it. For Lua, it is \fB\&.lua\fP\&. If the extension is -not recognized, an error is printed. (If an error happens, the extension is -either mistyped, or the backend was not compiled into your mpv binary.) -.sp -mpv internally loads the script\(aqs name by stripping the \fB\&.lua\fP extension and -replacing all nonalphanumeric characters with \fB_\fP\&. E.g., \fBmy\-tools.lua\fP -becomes \fBmy_tools\fP\&. If there are several scripts with the same name, it is -made unique by appending a number. This is the name returned by -\fBmp.get_script_name()\fP\&. -.sp -Entries with \fB\&.disable\fP extension are always ignored. -.sp -If a script is a directory (either if a directory is passed to \fB\-\-script\fP, -or any sub\-directories in the script directory, such as for example -\fB~/.config/mpv/scripts/something/\fP), then the directory represents a single -script. The player will try to load a file named \fBmain.x\fP, where \fBx\fP is -replaced with the file extension. For example, if \fBmain.lua\fP exists, it is -loaded with the Lua scripting backend. -.sp -You must not put any other files or directories that start with \fBmain.\fP into -the script\(aqs top level directory. If the script directory contains for example -both \fBmain.lua\fP and \fBmain.js\fP, only one of them will be loaded (and which -one depends on mpv internals that may change any time). Likewise, if there is -for example \fBmain.foo\fP, your script will break as soon as mpv adds a backend -that uses the \fB\&.foo\fP file extension. -.sp -mpv also appends the top level directory of the script to the start of Lua\(aqs -package path so you can import scripts from there too. Be aware that this will -shadow Lua libraries that use the same package path. (Single file scripts do not -include mpv specific directory the Lua package path. This was silently changed -in mpv 0.32.0.) -.sp -Using a script directory is the recommended way to package a script that -consists of multiple source files, or requires other files (you can use -\fBmp.get_script_directory()\fP to get the location and e.g. load data files). -.sp -Making a script a git repository, basically a repository which contains a -\fBmain.lua\(ga\fP file in the root directory, makes scripts easily updateable -(without the dangers of auto\-updates). Another suggestion is to use git -submodules to share common files or libraries. -.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 three arguments: -\fBfn(success, result, error)\fP: -.INDENT 7.0 -.INDENT 3.5 -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.TP -.B \fBsuccess\fP -Always a Boolean and is true if the command was successful, -otherwise false. -.UNINDENT -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B \fBresult\fP -The result value (can be nil) in case of success, nil otherwise (as -returned by \fBmp.command_native()\fP). -.TP -.B \fBerror\fP -The error string in case of an error, nil otherwise. -.UNINDENT -.UNINDENT -.UNINDENT -.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. (Omitting works as follows: either pass \fBnil\fP for \fBname\fP, -or pass the \fBfn\fP argument in place of the name. The latter is not -recommended and is handled for compatibility only.) -.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 the following entries (and -may contain undocumented ones): -.INDENT 7.0 -.INDENT 3.5 -.INDENT 0.0 -.TP -.B \fBevent\fP -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). -.TP -.B \fBis_mouse\fP -Boolean Whether the event was caused by a mouse button. -.TP -.B \fBkey_name\fP -The name of they key that triggered this, or \fBnil\fP if -invoked artificially. If the key name is unknown, it\(aqs an -empty string. -.TP -.B \fBkey_text\fP -Text if triggered by a text key, otherwise \fBnil\fP\&. See -description of \fBscript\-binding\fP command for details (this -field is equivalent to the 5th argument). -.UNINDENT -.UNINDENT -.UNINDENT -.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 -If a property is unavailable, or on error, the value argument to \fBfn\fP is -\fBnil\fP\&. (The \fBobserve_property()\fP call always succeeds, even if a -property does not exist.) -.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\%https://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. Any nonalphanumeric characters are replaced with \fB_\fP\&. -.INDENT 7.0 -.INDENT 3.5 -.IP "Example" -.sp -The script \fB/path/to/foo\-script.lua\fP becomes \fBfoo_script\fP\&. -.UNINDENT -.UNINDENT -.TP -.B \fBmp.get_script_directory()\fP -Return the directory if this is a script packaged as directory (see -\fI\%Script location\fP for a description). Return nothing if this is a single -file script. -.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. -.TP -.B \fBmp.create_osd_overlay(format)\fP -Create an OSD overlay. This is a very thin wrapper around the \fBosd\-overlay\fP -command. The function returns a table, which mostly contains fields that -will be passed to \fBosd\-overlay\fP\&. The \fBformat\fP parameter is used to -initialize the \fBformat\fP field. The \fBdata\fP field contains the text to -be used as overlay. For details, see the \fBosd\-overlay\fP command. -.sp -In addition, it provides the following methods: -.INDENT 7.0 -.TP -.B \fBupdate()\fP -Commit the OSD overlay to the screen, or in other words, run the -\fBosd\-overlay\fP command with the current fields of the overlay table. -Returns the result of the \fBosd\-overlay\fP command itself. -.TP -.B \fBremove()\fP -Remove the overlay from the screen. A \fBupdate()\fP call will add it -again. -.UNINDENT -.sp -Example: -.INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -ov = mp.create_osd_overlay("ass\-events") -ov.data = "{\e\ean5}{\e\eb1}hello world!" -ov:update() -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -The advantage of using this wrapper (as opposed to running \fBosd\-overlay\fP -directly) is that the \fBid\fP field is allocated automatically. -.TP -.B \fBmp.get_osd_size()\fP -Returns a tuple of \fBosd_width, osd_height, osd_par\fP\&. The first two give -the size of the OSD in pixels (for video outputs like \fB\-\-vo=xv\fP, this may -be "scaled" pixels). The third is the display pixel aspect ratio. -.sp -May return invalid/nonsense values if OSD is not initialized yet. -.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 [, on_update]])\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 if the parameter is \fBnil\fP or missing. -.sp -The \fBon_update\fP parameter enables run\-time updates of all matching option -values via the \fBscript\-opts\fP option/property. If any of the matching -options changes, the values in the \fBtable\fP (which was originally passed to -the function) are changed, and \fBon_update(list)\fP is called. \fBlist\fP is -a table where each updated option has a \fBlist[option_name] = true\fP entry. -There is no initial \fBon_update()\fP call. This never re\-reads the config file. -\fBscript\-opts\fP is always applied on the original config file, ignoring -previous \fBscript\-opts\fP values (for example, if an option is removed from -\fBscript\-opts\fP at runtime, the option will have the value in the config -file). \fBtable\fP entries are only written for option values whose values -effectively change (this is important if the script changes \fBtable\fP -entries independently). -.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 -.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 (e.g. 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 \fBp2\fP is an absolute path, \fBp2\fP 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.get_env_list()\fP -Returns the C environment as a list of strings. (Do not confuse this with -the Lua "environment", which is an unrelated concept.) -.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 -.sp -For the existing event types, see \fI\%List of events\fP\&. -.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. -.sp -\fBfn(hook)\fP is the function that will be called during execution of the -hook. The parameter passed to it (\fBhook\fP) is a Lua object that can control -further aspects about the currently invoked hook. It provides the following -methods: -.INDENT 7.0 -.INDENT 3.5 -.INDENT 0.0 -.TP -.B \fBdefer()\fP -Returning from the hook function should not automatically continue -the hook. Instead, the API user wants to call \fBhook:cont()\fP on its -own at a later point in time (before or after the function has -returned). -.TP -.B \fBcont()\fP -Continue the hook. Doesn\(aqt need to be called unless \fBdefer()\fP was -called. -.UNINDENT -.UNINDENT -.UNINDENT -.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\%https://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.get_script_directory()\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.create_osd_overlay(format)\fP -.sp -\fBmp.get_osd_size()\fP (returned object has properties: width, height, aspect) -.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) Note: like lua \- this does NOT expand -meta\-paths like \fB~~/foo\fP (other JS file functions do expand meta paths). -.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.get_env_list()\fP -.sp -\fBmp.utils.getpid()\fP (LE) -.sp -\fBmp.add_hook(type, priority, fn(hook))\fP -.sp -\fBmp.options.read_options(obj [, identifier [, on_update]])\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, \fBappend_file\fP and \fBrequire\fP already use -this internally. -.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\&. -.TP -.B \fBmp.utils.append_file(fname, str)\fP -Same as \fBmp.utils.write_file\fP if the file \fBfname\fP does not exist. If it -does exist then append instead of overwrite. -.UNINDENT -.sp -Note: \fBread_file\fP, \fBwrite_file\fP and \fBappend_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\&. -.TP -.B \fBmp.module_paths\fP -Global modules search paths array for the \fBrequire\fP function (see below). -.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. Specifically, a module is a script which adds -properties (functions, etc) to its pre\-existing \fBexports\fP object, which -another script can access with \fBrequire(module\-id)\fP\&. This runs the module and -returns its \fBexports\fP object. Further calls to \fBrequire\fP for the same module -will return its cached \fBexports\fP object without running the module again. -.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 which starts with \fB\&./\fP or \fB\&../\fP is relative to the script or module -which \fBrequire\fP it. 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 considered a global module id and searched according -to \fBmp.module_paths\fP in normal array order, e.g. \fBrequire("x")\fP tries to -load \fBx.js\fP at one of the array paths, and id \fBfoo/x\fP tries to load \fBx.js\fP -inside dir \fBfoo\fP at one of the paths. -.sp -The \fBmp.module_paths\fP array is empty by default except for scripts which are -loaded as a directory where it contains one item \- \fB<directory>/modules/\fP . -The array may be updated from a script (or using custom init \- see below) which -will affect future calls to \fBrequire\fP for global module id\(aqs which are not -already loaded/cached. -.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 Custom initialization -.sp -After mpv initializes the JavaScript environment for a script but before it -loads the script \- it tries to run the file \fBinit.js\fP at the root of the mpv -configuration directory. Code at this file can update the environment further -for all scripts. E.g. if it contains \fBmp.module_paths.push("/foo")\fP then -\fBrequire\fP at all scripts will search global module id\(aqs also at \fB/foo\fP -(do NOT do \fBmp.module_paths = ["/foo"];\fP because this will remove existing -paths \- like \fB<script\-dir>/modules\fP for scripts which load from a directory). -.sp -The custom\-init file is ignored if mpv is invoked with \fB\-\-no\-config\fP\&. -.sp -Before mpv 0.34, the file name was \fB\&.init.js\fP (with dot) at the same dir. -.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.) -.sp -You can open the pipe in PuTTY as "serial" device. This is not very -comfortable, but gives a way to test interactively without having to write code. -.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 interpret 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 -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 Data flow -.sp -Currently, the mpv\-side IPC implementation does not service the socket while a -command is executed and the reply is written. It is for example not possible -that other events, that happened during the execution of the command, are -written to the socket before the reply is written. -.sp -This might change in the future. The only guarantee is that replies to IPC -messages are sent in sequence. -.sp -Also, since socket I/O is inherently asynchronous, it is possible that you read -unrelated event messages from the socket, before you read the reply to the -previous command you sent. In this case, these events were queued by the mpv -side before it read and started processing your command message. -.sp -If the mpv\-side IPC implementation switches away from blocking writes and -blocking command execution, it may attempt to send events at any time. -.sp -You can also use asynchronous commands, which can return in any order, and -which do not block IPC protocol interaction at all while the command is -executed in the background. -.SS Asynchronous commands -.sp -Command can be run asynchronously. This behaves exactly as with normal command -execution, except that execution is not blocking. Other commands can be sent -while it\(aqs executing, and command completion can be arbitrarily reordered. -.sp -The \fBasync\fP field controls this. If present, it must be a boolean. If missing, -\fBfalse\fP is assumed. -.sp -For example, this initiates an asynchronous command: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -{ "command": ["screenshot"], "request_id": 123, "async": true } -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -And this is the completion: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -{"request_id":123,"error":"success","data":null} -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -By design, you will not get a confirmation that the command was started. If a -command is long running, sending the message will lead to any reply until much -later when the command finishes. -.sp -Some commands execute synchronously, but these will behave like asynchronous -commands that finished execution immediately. -.sp -Cancellation of asynchronous commands is available in the libmpv API, but has -not yet been implemented in the IPC protocol. -.SS Commands with named arguments -.sp -If the \fBcommand\fP field is a JSON object, named arguments are expected. This -is described in the C API \fBmpv_command_node()\fP documentation (the -\fBMPV_FORMAT_NODE_MAP\fP case). In some cases, this may make commands more -readable, while some obscure commands basically require using named arguments. -.sp -Currently, only "proper" commands (as listed by \fI\%List of Input Commands\fP) -support named arguments. -.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 -.SS Alternative ways of starting clients -.sp -You can create an anonymous IPC connection without having to set -\fB\-\-input\-ipc\-server\fP\&. This is achieved through a mpv pseudo scripting backend -that starts processes. -.sp -You can put \fB\&.run\fP file extension in the mpv scripts directory in its config -directory (see the \fI\%FILES\fP section for details), or load them through other -means (see \fI\%Script location\fP). These scripts are simply executed with the OS -native mechanism (as if you ran them in the shell). They must have a proper -shebang and have the executable bit set. -.sp -When executed, a socket (the IPC connection) is passed to them through file -descriptor inheritance. The file descriptor is indicated as the special command -line argument \fB\-\-mpv\-ipc\-fd=N\fP, where \fBN\fP is the numeric file descriptor. -.sp -The rest is the same as with a normal \fB\-\-input\-ipc\-server\fP IPC connection. mpv -does not attempt to observe or other interact with the started script process. -.sp -This does not work in Windows yet. -.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 file \fI\%https://github.com/mpv\-player/mpv/blob/master/DOCS/interface\-changes.rst\fP -documents changes to the command and user interface, such as options and -properties. (It usually documents breaking changes only, additions and -enhancements are often not listed.) -.IP \(bu 2 -C API changes are listed in -\fI\%https://github.com/mpv\-player/mpv/blob/master/DOCS/client\-api\-changes.rst\fP -.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\%https://mpv.io/manual/master/#options\fP -.IP \(bu 2 -\fI\%https://mpv.io/manual/master/#list\-of\-input\-commands\fP -.IP \(bu 2 -\fI\%https://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 -They are available on Linux/BSD platforms only and enabled by default if the -compiler supports linking with the \fB\-rdynamic\fP flag. -.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 \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. If set to another -value, disable leak reporting. If unset, use the default, which normally is -\fB0\fP\&. If mpv was built with \fB\-\-enable\-ta\-leak\-report\fP, the default is -\fB1\fP\&. If leak reporting was disabled at compile time (\fBNDEBUG\fP in -custom \fBCFLAGS\fP), this environment variable is ignored. -.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\fP -The standard configuration directory. This can be overridden by environment -variables, in ascending order: -.INDENT 7.0 -.TP -.B 1 -If \fB$XDG_CONFIG_HOME\fP is set, then the derived configuration directory -will be \fB$XDG_CONFIG_HOME/mpv\fP\&. -.TP -.B 2 -If \fB$MPV_HOME\fP is set, then the derived configuration directory will be -\fB$MPV_HOME\fP\&. -.UNINDENT -.sp -If this directory, nor the original configuration directory (see below) do -not exist, mpv tries to create this directory automatically. -.TP -.B \fB~/.mpv/\fP -The original (pre 0.5.0) configuration directory. It will continue to be -read if present. -.sp -If both this directory and the standard configuration directory are -present, configuration will be read from both with the standard -configuration directory content taking precedence. However, you should -fully migrate to the standard directory and a warning will be shown in -this situation. -.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. -.sp -The \fB\-\-load\-scripts=no\fP option disables loading these files. -.sp -See \fI\%Script location\fP for details. -.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 -.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. -.