[crux-commits] ports/contrib (3.6): mpv: bump for API change on libplacebo

commit a4bc654323d38c109bb2d6a7a2419b7c3f3b84e6 Author: Danny Rawlins <contact@romster.me> Date: Sat Feb 27 23:37:40 2021 +1100 mpv: bump for API change on libplacebo diff --git a/mpv/.signature b/mpv/.signature index 0034e87df..5a0d80d9c 100644 --- a/mpv/.signature +++ b/mpv/.signature @@ -1,7 +1,8 @@ untrusted comment: verify with /etc/ports/contrib.pub -RWSagIOpLGJF36+DwOVFFyzIUAM2vhbRi1mdKblppXQsBLJ3Z5s9P/ZYAvheeAsZtrdYl6b4cj/gKnXevVaMJzDobvYAxqZD1Aw= -SHA256 (Pkgfile) = 671e1b02f65a6bf29fe3c5581fd926b6d78d48105be386920a2a91ce1ad9fa67 +RWSagIOpLGJF33GFhJgn2H+b+Vb0cfu61A4dbVtr6ydLe/GedAocCle1AkVzAbmuljBSojAw03InawRl6k6Si0FOotPag4ODNwk= +SHA256 (Pkgfile) = 6ff3c1b7fd4ccdb98d04f2022cd43b5834e80f11fc5cbbc6b1fd1485aea10e48 SHA256 (.footprint) = f14555b474f5c94353678e03ba77450f3c745c12b1786ae3740039d17fa35bcd SHA256 (mpv-v0.33.0.tar.gz) = f1b9baf5dc2eeaf376597c28a6281facf6ed98ff3d567e3955c95bf2459520b4 SHA256 (waf-2.0.9) = 2a8e0816f023995e557f79ea8940d322bec18f286917c8f9a6fa2dc3875dfa48 -SHA256 (mpv.1) = e2c8c722447909b9ab08725a0dc479330caaab51f5058912bebbef9688ef241d +SHA256 (mpv-libplacebo-3.104.0-api-change.patch) = a9f656a163e17a33050ea3ffe51203b948168437c87038239fc3a2424927b35a +SHA256 (mpv.1) = e672df1405028f8a01eed50a2216cc901355ac8704c87453a0a3074721314c18 diff --git a/mpv/Pkgfile b/mpv/Pkgfile index 5a77d091a..e7ed3fe1d 100644 --- a/mpv/Pkgfile +++ b/mpv/Pkgfile @@ -6,14 +6,17 @@ name=mpv version=0.33.0 -release=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-libplacebo-3.104.0-api-change.patch mpv.1) build() { cd $name-$version + patch -p1 -i $SRC/mpv-libplacebo-3.104.0-api-change.patch + install -m0755 $SRC/waf-2.0.9 waf [[ -e '/usr/lib/pkgconfig/libcdio_cdda.pc' ]] && PKGMK_MPV+=' --enable-cdda' diff --git a/mpv/mpv-libplacebo-3.104.0-api-change.patch b/mpv/mpv-libplacebo-3.104.0-api-change.patch new file mode 100644 index 000000000..5aaaf7b49 --- /dev/null +++ b/mpv/mpv-libplacebo-3.104.0-api-change.patch @@ -0,0 +1,84 @@ +From 7c4465cefb27d4e0d07535d368febdf77b579566 Mon Sep 17 00:00:00 2001 +From: Niklas Haas <git@haasn.xyz> +Date: Thu, 3 Dec 2020 08:25:23 +0100 +Subject: [PATCH] vo_gpu: placebo: update for upstream API changes + +The concept of sample/address modes was moved from `pl_tex` to +`pl_desc_binding`. + +The `pl_tex_blit()` function also underwent an API change. +--- + video/out/placebo/ra_pl.c | 31 +++++++++++++++++++++++++++++-- + 1 file changed, 29 insertions(+), 2 deletions(-) + +diff --git a/video/out/placebo/ra_pl.c b/video/out/placebo/ra_pl.c +index f8df590511..8244acff26 100644 +--- a/video/out/placebo/ra_pl.c ++++ b/video/out/placebo/ra_pl.c +@@ -144,8 +144,14 @@ bool mppl_wrap_tex(struct ra *ra, const struct pl_tex *pltex, + .blit_dst = pltex->params.blit_dst, + .host_mutable = pltex->params.host_writable, + .downloadable = pltex->params.host_readable, ++#if PL_API_VER >= 103 ++ // These don't exist upstream, so just pick something reasonable ++ .src_linear = pltex->params.format->caps & PL_FMT_CAP_LINEAR, ++ .src_repeat = false, ++#else + .src_linear = pltex->params.sample_mode == PL_TEX_SAMPLE_LINEAR, + .src_repeat = pltex->params.address_mode == PL_TEX_ADDRESS_REPEAT, ++#endif + }, + .priv = (void *) pltex, + }; +@@ -195,10 +201,12 @@ static struct ra_tex *tex_create_pl(struct ra *ra, + .blit_dst = params->blit_dst || params->render_dst, + .host_writable = params->host_mutable, + .host_readable = params->downloadable, ++#if PL_API_VER < 103 + .sample_mode = params->src_linear ? PL_TEX_SAMPLE_LINEAR + : PL_TEX_SAMPLE_NEAREST, + .address_mode = params->src_repeat ? PL_TEX_ADDRESS_REPEAT + : PL_TEX_ADDRESS_CLAMP, ++#endif + .initial_data = params->initial_data, + }); + +@@ -399,7 +407,18 @@ static void blit_pl(struct ra *ra, struct ra_tex *dst, struct ra_tex *src, + pldst.y1 = MPMIN(MPMAX(dst_rc->y1, 0), dst->params.h); + } + ++#if PL_API_VER >= 103 ++ pl_tex_blit(get_gpu(ra), &(struct pl_tex_blit_params) { ++ .src = src->priv, ++ .dst = dst->priv, ++ .src_rc = plsrc, ++ .dst_rc = pldst, ++ .sample_mode = src->params.src_linear ? PL_TEX_SAMPLE_LINEAR ++ : PL_TEX_SAMPLE_NEAREST, ++ }); ++#else + pl_tex_blit(get_gpu(ra), dst->priv, src->priv, pldst, plsrc); ++#endif + } + + static const enum pl_var_type var_type[RA_VARTYPE_COUNT] = { +@@ -627,9 +646,17 @@ static void renderpass_run_pl(struct ra *ra, + struct pl_desc_binding bind; + switch (inp->type) { + case RA_VARTYPE_TEX: +- case RA_VARTYPE_IMG_W: +- bind.object = (* (struct ra_tex **) val->data)->priv; ++ case RA_VARTYPE_IMG_W: { ++ struct ra_tex *tex = *((struct ra_tex **) val->data); ++ bind.object = tex->priv; ++#if PL_API_VER >= 103 ++ bind.sample_mode = tex->params.src_linear ? PL_TEX_SAMPLE_LINEAR ++ : PL_TEX_SAMPLE_NEAREST; ++ bind.address_mode = tex->params.src_repeat ? PL_TEX_ADDRESS_REPEAT ++ : PL_TEX_ADDRESS_CLAMP; ++#endif + break; ++ } + case RA_VARTYPE_BUF_RO: + case RA_VARTYPE_BUF_RW: + bind.object = (* (struct ra_buf **) val->data)->priv; diff --git a/mpv/mpv.1 b/mpv/mpv.1 index d41da81fe..bed207d59 100644 --- a/mpv/mpv.1 +++ b/mpv/mpv.1 @@ -175,6 +175,9 @@ Toggle infinite looping. .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 @@ -238,6 +241,12 @@ used, broken on the terminal). 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 +Cycles 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 @@ -287,10 +296,19 @@ in the mpv git repository. .SS Mouse Control .INDENT 0.0 .TP -.B button 3 and button 4 -Seek backward/forward 1 minute. +.B Left double click +Toggle fullscreen on/off. .TP -.B button 5 and button 6 +.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 @@ -314,7 +332,7 @@ 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 +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 @@ -324,9 +342,15 @@ because \fB\-\-fs\fP is a flag option that requires no parameter. If an option changes and its parameter becomes optional, then a command line using the alternative syntax will break. .sp -Currently, the parser makes no difference whether an option starts with \fB\-\-\fP -or a single \fB\-\fP\&. This might also change in the future, and \fB\-\-option value\fP -might always interpret \fBvalue\fP as filename in order to reduce ambiguities. +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 @@ -437,7 +461,7 @@ additionally wrapped in the fixed\-length syntax, e.g. \fB%n%string_of_length_n\ Some mpv options interpret paths starting with \fB~\fP\&. Currently, the prefix \fB~~/\fP expands to the mpv configuration directory (usually \fB~/.config/mpv/\fP). \fB~/\fP expands to the user\(aqs home directory. (The trailing \fB/\fP is always -required.) There are the following paths as well: +required.) The following paths are currently recognized: .TS center; |l|l|. @@ -449,6 +473,18 @@ Meaning T} _ T{ +\fB~~/\fP +T} T{ +mpv config dir (for example \fB~/.config/mpv/\fP) +T} +_ +T{ +\fB~/\fP +T} T{ +user home directory root (similar to shell, \fB$HOME\fP) +T} +_ +T{ \fB~~home/\fP T} T{ same as \fB~~/\fP @@ -472,6 +508,19 @@ T} T{ the path to the desktop (win32, OSX) 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 @@ -572,11 +621,19 @@ file\-local options. The option \fB\-\-a\fP is never reset here. .SS List Options .sp Some options which store lists of option values can have action suffixes. For -example, you can set a \fB,\fP\-separated list of filters with \fB\-\-vf\fP, but the -option also allows you to append filters with \fB\-\-vf\-append\fP\&. +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 -Options for filenames do not use \fB,\fP as separator, but \fB:\fP (Unix) or \fB;\fP -(Windows). +They support the following operations: .TS center; |l|l|. @@ -588,89 +645,196 @@ Meaning T} _ T{ -\-add +\-set T} T{ -Append 1 or more items (may become alias for \-append) +Set a list of items (using the list separator, interprets escapes) T} _ T{ \-append T} T{ -Append single item (avoids need for escaping) +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 +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 an existing item by integer index +Delete 1 or more items by integer index (deprecated) T} _ T{ -\-pre +\-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{ -Prepend 1 or more items +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 items +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 an item, or remove if if it already exists +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 -Although some operations allow specifying multiple \fB,\fP\-separated items, using -this is strongly discouraged and deprecated, except for \fB\-set\fP\&. +Without suffix, the operation used is normally \fB\-set\fP\&. .sp -Without suffix, the action taken is normally \fB\-set\fP\&. +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 -Some options only support a subset of the above. -.sp Options of this type can be changed at runtime using the \fBchange\-list\fP -command, which takes the suffix as separate operation parameter. -.SS Playing DVDs -.sp -DVDs can be played with the \fBdvd://[title]\fP syntax. The optional -title specifier is a number which selects between separate video -streams on the DVD. If no title is given (\fBdvd://\fP) then the longest -title is selected automatically by the library. This is usually what -you want. mpv does not support DVD menus. -.sp -DVDs which have been copied on to a hard drive or other mounted -filesystem (by e.g. the \fBdvdbackup\fP tool) are accommodated by -specifying the path to the local copy: \fB\-\-dvd\-device=PATH\fP\&. -Alternatively, running \fBmpv PATH\fP should auto\-detect a DVD directory -tree and play the longest title. -.sp -\fBNOTE:\fP -.INDENT 0.0 -.INDENT 3.5 -DVD subtitles -.sp -DVDs use image\-based subtitles. Image subtitles are implemented as -a bitmap video stream which can be superimposed over the main -movie. mpv\(aqs subtitle styling and positioning options and keyboard -shortcuts generally do not work with image\-based subtitles. -Exceptions include options like \fB\-\-stretch\-dvd\-subs\fP and -\fB\-\-stretch\-image\-subs\-to\-screen\fP\&. -.UNINDENT -.UNINDENT +command, which takes the suffix (without the \fB\-\fP) as separate operation +parameter. .SH CONFIGURATION FILES .SS Location and Syntax .sp @@ -696,7 +860,7 @@ setting them to \fIno\fP\&. Even suboptions can be specified in this way. # Use GPU\-accelerated video output by default. vo=gpu # Use quotes for text that can contain spaces: -status\-msg="Time: ${time\-pos}" +term\-status\-msg="Time: ${time\-pos}" .ft P .fi .UNINDENT @@ -813,24 +977,265 @@ profile=big\-cache .UNINDENT .UNINDENT .UNINDENT -.SS Auto profiles +.SS Runtime profiles .sp -Some profiles are loaded automatically. The following example demonstrates this: +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 -.IP "Auto profile loading" +.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. 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 -[protocol.dvd] -profile\-desc="profile for dvd:// streams" -alang=en +[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 -[extension.flv] -profile\-desc="profile for .flv files" -vf=flip +[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 @@ -843,7 +1248,57 @@ The profile name follows the schema \fBtype.name\fP, where type can be and \fBextension\fP for the extension of the path of the currently played file (\fInot\fP the file format). .sp -This feature is very limited, and there are no other auto profiles. +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 @@ -879,7 +1334,7 @@ listed. .IP \(bu 2 The current time position in \fBHH:MM:SS\fP format (\fBplayback\-time\fP property) .IP \(bu 2 -The total file duration (absent if unknown) (\fBlength\fP property) +The total file duration (absent if unknown) (\fBduration\fP property) .IP \(bu 2 Playback speed, e.g. \(ga\(ga x2.0\(ga\(ga. Only visible if the speed is not normal. This is the user\-requested speed, and not the actual speed (usually they should @@ -912,11 +1367,11 @@ certainty. Dropped frames, e.g. \fBDropped: 4\fP\&. Shows up only if the count is not 0. Can grow if the video framerate is higher than that of the display, or if video rendering is too slow. May also be incremented on "hiccups" and when the video -frame couldn\(aqt be displayed on time. (\fBvo\-drop\-frame\-count\fP property.) +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. -(\fBdrop\-frame\-count\fP property.) +(\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, @@ -986,10 +1441,10 @@ can also prefix it with \fBlavf://\fP or \fBffmpeg://\fP\&. \fBytdl://...\fP .INDENT 0.0 .INDENT 3.5 -By default, the youtube\-dl hook script (enabled by default for mpv CLI) -only looks at http URLs. Prefixing an URL with \fBytdl://\fP forces it to -be always processed by the script. This can also be used to invoke special -youtube\-dl functionality like playing a video by ID or invoking search. +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. @@ -1006,7 +1461,7 @@ Play data from stdin. \fBsmb://PATH\fP .INDENT 0.0 .INDENT 3.5 -Play a path from Samba share. +Play a path from Samba share. (Requires FFmpeg support.) .UNINDENT .UNINDENT .sp @@ -1021,42 +1476,19 @@ playlist); \fBmpls/<number>\fP (selects <number>.mpls playlist); \fB<number>\fP (select playlist with the same index). mpv will list the available playlists on loading. .sp -\fBbluray://\fP is an alias. -.UNINDENT -.UNINDENT -.sp -\fBdvd://[title|[starttitle]\-endtitle][/device]\fP \fB\-\-dvd\-device=PATH\fP -.INDENT 0.0 -.INDENT 3.5 -Play a DVD. DVD menus are not supported. If no title is given, the longest -title is auto\-selected. -.sp -\fBdvdnav://\fP is an old alias for \fBdvd://\fP and does exactly the same -thing. -.UNINDENT -.UNINDENT -.sp -\fBdvdread://...:\fP -.INDENT 0.0 -.INDENT 3.5 -Play a DVD using the old libdvdread code. This is what MPlayer and -older mpv versions used for \fBdvd://\fP\&. Use is discouraged. It\(aqs -provided only for compatibility and for transition, and to work -around outstanding dvdnav bugs (see "DVD library choices" above). -.UNINDENT -.UNINDENT -.sp -\fBtv://[channel][/input_id]\fP \fB\-\-tv\-...\fP -.INDENT 0.0 -.INDENT 3.5 -Analogue TV via V4L. Also useful for webcams. (Linux only.) +\fBbluray://\fP is an alias. .UNINDENT .UNINDENT .sp -\fBpvr://\fP \fB\-\-pvr\-...\fP +\fBdvd://[title][/device]\fP \fB\-\-dvd\-device=PATH\fP .INDENT 0.0 .INDENT 3.5 -PVR. (Linux only.) +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 @@ -1095,10 +1527,27 @@ string after the \fB//\fP directly to libavformat. 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 -For example, \fBmpv av://lavfi:mandelbrot\fP makes use of the libavfilter -wrapper included in libavdevice, and will use the \fBmandelbrot\fP source -filter to generate input data. +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 @@ -1154,6 +1603,45 @@ 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 @@ -1198,11 +1686,10 @@ if you manually use \fB\-\-player\-operation\-mode=pseudo\-gui\fP on the command .UNINDENT .sp This mode applies options from the builtin profile \fBbuiltin\-pseudo\-gui\fP, but -only if these haven\(aqt been set in the user\(aqs config file or on the command line. -Also, for compatibility with the old pseudo\-gui behavior, the options in the -\fBpseudo\-gui\fP profile are applied unconditionally. In addition, the profile -makes sure to enable the pseudo\-GUI mode, so that \fB\-\-profile=pseudo\-gui\fP -works like in older mpv releases. The profiles are currently defined as follows: +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 @@ -1213,6 +1700,20 @@ 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 @@ -1229,6 +1730,47 @@ 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 OSX. +.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 @@ -1238,6 +1780,8 @@ 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" @@ -1257,6 +1801,8 @@ 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" @@ -1273,6 +1819,8 @@ subtitles. .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. @@ -1283,6 +1831,56 @@ terminal when starting playback of a file. .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 playbac, 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 @@ -1322,6 +1920,11 @@ 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 @@ -1429,28 +2032,44 @@ as long as \fBplaylist.m3u\fP does not link to further playlists. 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 +Play files according to a playlist file. Supports some common formats. If no format is detected, it will be treated as list of files, separated by -newline characters. Note that XML playlist formats are not supported.) +newline characters. You may need this option to load plaintext files as +a playlist. Note that XML playlist formats are not supported. .sp -You can play playlists directly and without this option, however, this -option disables any security mechanisms that might be in place. You may -also need this option to load plaintext files as playlist. +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 mpv uses playlist files via \fB\-\-playlist\fP is not safe against -maliciously constructed files. Such files may trigger harmful actions. -This has been the case for all mpv and MPlayer versions, but -unfortunately this fact was not well documented earlier, and some people -have even misguidedly recommended use of \fB\-\-playlist\fP with untrusted -sources. Do NOT use \fB\-\-playlist\fP with random internet sources or files -you do not trust! +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 -Playlist can contain entries using other protocols, such as local files, -or (most severely), special protocols like \fBavdevice://\fP, which are -inherently unsafe. +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 @@ -1470,7 +2089,7 @@ threshold, a backward chapter seek will go to the beginning of the current chapter instead. A negative value means always go back to the previous chapter. .TP -.B \fB\-\-hr\-seek=<no|absolute|yes>\fP +.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 @@ -1487,6 +2106,11 @@ 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 @@ -1546,9 +2170,6 @@ In addition, if a playlist is loaded while this is set, the added playlist entries are not marked as originating from network or potentially unsafe location. (Instead, the behavior is as if the playlist entries were provided directly to mpv command line or \fBloadfile\fP command.) -.sp -Note that \fB\-\-playlist\fP always loads all entries, so you use that instead -if you really have the need for this functionality. .TP .B \fB\-\-access\-references=<yes|no>\fP Follow any references in the file being opened (default: yes). Disabling @@ -1611,6 +2232,14 @@ the file, and an unset \fBb\fP the end of the file. 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 @@ -1788,14 +2417,16 @@ increase \fB\-\-hwdec\-extra\-frames\fP instead (until you get playback without logged errors). .IP \(bu 2 The demuxer cache is essential for backward demuxing. Make sure to set -\fB\-\-demuxer\-seekable\-cache\fP (or just use \fB\-\-cache\fP). The cache size -might matter. If it\(aqs too small, a queue overflow will be logged, and -backward playback cannot continue, or it performs too many low level -seeks. If it\(aqs too large, implementation tradeoffs may cause general -performance issues. Use \fB\-\-demuxer\-max\-bytes\fP to potentially increase -the amount of packets the demuxer layer can queue for reverse demuxing -(basically it\(aqs the \fB\-\-video\-reversal\-buffer\fP equivalent for the -demuxer layer). +\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 @@ -1931,6 +2562,9 @@ 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 @@ -1985,11 +2619,15 @@ configuration subdirectory (usually \fB~/.config/mpv/scripts/\fP). .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 @@ -2000,6 +2638,13 @@ 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. @@ -2022,6 +2667,8 @@ 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" @@ -2057,7 +2704,8 @@ 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. +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 @@ -2078,18 +2726,23 @@ version of youtube\-dl to be installed on the system. (Enabled by default.) .sp If the script can\(aqt do anything with an URL, it will do nothing. .sp -The \fBtry_ytdl_first\fP script option accepts a boolean \(aqyes\(aq or \(aqno\(aq, and if -\(aqyes\(aq will try parsing the URL with youtube\-dl first, instead of the default -where it\(aqs only after mpv failed to open it. This mostly depends on whether -most of your URLs need youtube\-dl parsing. -.sp -The \fBexclude\fP script option accepts a \fB|\fP\-separated list of URL patterns -which mpv should not use with youtube\-dl. The patterns are matched after -the \fBhttp(s)://\fP part of the URL. +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. +should use \fB%\fP before any of the characters \fB^$()%|,.[]*+\-?\fP to +match that character. .INDENT 7.0 .INDENT 3.5 .IP "Examples" @@ -2106,18 +2759,98 @@ will exclude any URL that ends with \fB\&.mkv\fP or \fB\&.mp4\fP\&. .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 path to youtube\-dl executable or a compatible fork\(aqs. +The default "youtube\-dl" looks for the executable in PATH. In a Windows +environment 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 -The \fBuse_manifests\fP script option makes mpv use the master manifest URL for -formats like HLS and DASH, if available, allowing for video/audio selection -in runtime. It\(aqs disabled ("no") by default for performance reasons. +I have no idea. +.UNINDENT +.UNINDENT .TP -.B \fB\-\-ytdl\-format=<best|worst|mp4|webm|...>\fP +.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: youtube\-dl\(aqs default, currently \fBbestvideo+bestaudio/best\fP) +(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 @@ -2131,6 +2864,8 @@ 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" @@ -2152,11 +2887,22 @@ 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. +files. See \fI\%PSEUDO GUI MODE\fP for details. .UNINDENT .SS Video .INDENT 0.0 @@ -2198,28 +2944,44 @@ The argument selects the drop methods, and can be one of the following: .INDENT 7.0 .TP .B <no> -Disable any framedropping. +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. It tries to query -the display FPS (X11 only, not correct on multi\-monitor systems), or -assumes infinite display FPS if that fails. Drops are indicated in -the terminal status line as \fBDropped:\fP field. If the decoder is too slow, -in theory all frames would have to be dropped (because all frames are -too late) \- to avoid this, frame dropping stops if the effective -framerate is below 10 FPS. +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. Not recommended. +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. +Enable both modes. Not recommended. Better than just \fBdecoder\fP mode. .UNINDENT .sp \fBNOTE:\fP @@ -2239,8 +3001,8 @@ anymore. This does: .INDENT 7.0 .IP \(bu 2 -Use the demuxer reported FPS for frame dropping. This avoids that the -player needs to decode 1 frame in advance, lowering total latency in +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. @@ -2252,7 +3014,7 @@ frame, so if this is not done, there is some likeliness that the VO has to drop some frames if rendering the first frame takes longer than needed. .UNINDENT .TP -.B \fB\-\-display\-fps=<fps>\fP +.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 @@ -2262,11 +3024,69 @@ monitor. 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 @@ -2274,17 +3094,19 @@ hardware decoding is not possible, mpv will fall back on software decoding. always use software decoding (default) .TP .B auto -enable best hw decoder (see below) +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 \fB\-\-gpu\-context=x11\fP, -or \fB\-\-vo=vdpau\fP (Linux only) +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) @@ -2297,7 +3119,7 @@ copies video back into system RAM (Linux with some GPUs only) .TP .B videotoolbox requires \fB\-\-vo=gpu\fP (OS X 10.8 and up), -or \fB\-\-vo=opengl\-cb\fP (iOS 9.0 and up) +or \fB\-\-vo=libmpv\fP (iOS 9.0 and up) .TP .B videotoolbox\-copy copies video back into system RAM (OS X 10.8 or iOS 9.0 and up) @@ -2329,16 +3151,16 @@ requires \fB\-\-vo=gpu\fP (Raspberry Pi only \- default if available) .B mmal\-copy copies video back to system RAM (Raspberry Pi only) .TP -.B cuda +.B nvdec requires \fB\-\-vo=gpu\fP (Any platform CUDA is available) .TP -.B cuda\-copy +.B nvdec\-copy copies video back to system RAM (Any platform CUDA is available) .TP -.B nvdec +.B cuda requires \fB\-\-vo=gpu\fP (Any platform CUDA is available) .TP -.B nvdec\-copy +.B cuda\-copy copies video back to system RAM (Any platform CUDA is available) .TP .B crystalhd @@ -2355,55 +3177,56 @@ never be enabled. Also note that if the first found method doesn\(aqt actually work, it will always fall back to software decoding, instead of trying the next method (might matter on some Linux systems). .sp -\fBauto\-copy\fP selects only modes that copy the video data back to system -memory after decoding. This selects modes like \fBvaapi\-copy\fP (and so on). -If none of these work, hardware decoding is disabled. This mode is always -guaranteed to incur no additional loss compared to software decoding, and -will allow CPU processing with video filters. -.sp -The \fBvaapi\fP mode, if used with \fB\-\-vo=gpu\fP, requires Mesa 11 and most -likely works with Intel GPUs only. It also requires the opengl EGL backend. -.sp -The \fBcuda\fP and \fBcuda\-copy\fP modes provides deinterlacing in the decoder -which is useful as there is no other deinterlacing mechanism in the gpu -output path. To use this deinterlacing you must pass the option: -\fBvd\-lavc\-o=deint=[weave|bob|adaptive]\fP\&. -Pass \fBweave\fP (or leave the option unset) to not attempt any -deinterlacing. \fBcuda\fP should always be preferred unless the \fBgpu\fP -vo is not being used or filters are required. -.sp -\fBnvdec\fP is a newer implementation of CUVID/CUDA decoding, which uses the -FFmpeg decoders for file parsing. Experimental, is known not to correctly -check whether decoding is supported by the hardware at all. Deinterlacing -is not supported. Since this uses FFmpeg\(aqs codec parsers, it is expected -that this generally causes fewer issues than \fBcuda\fP\&. +\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 -Most video filters will not work with hardware decoding as they are -primarily implemented on the CPU. Some exceptions are \fBvdpaupp\fP, -\fBvdpaurb\fP and \fBvavpp\fP\&. See \fI\%VIDEO FILTERS\fP for more details. +\fBauto\-copy\-safe\fP selects the union of methods selected with \fBauto\-safe\fP +and \fBauto\-copy\fP\&. .sp -The \fB\&...\-copy\fP modes (e.g. \fBdxva2\-copy\fP) allow you to use hardware -decoding with any VO, backend or filter. Because these copy the decoded -video back to system RAM, they\(aqre likely less efficient than the direct -modes (like e.g. \fBdxva2\fP), and probably not more efficient than software -decoding except for some codecs (e.g. HEVC). +\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 -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -When using this switch, hardware decoding is still only done for some -codecs. See \fB\-\-hwdec\-codecs\fP to enable hardware decoding for more -codecs. -.UNINDENT -.UNINDENT +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 \fBnvdec\fP and \fBcuda\fP methods work with Vulkan. +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" @@ -2422,10 +3245,10 @@ chroma scalers instead of the one specified by \fB\-\-cscale\fP\&. In other cases, hardware decoding can also reduce the bit depth of the decoded image, which can introduce banding or precision loss for 10\-bit files. .sp -\fBvdpau\fP is usually safe, except for 10 bit video. If deinterlacing -enabled (or the \fBvdpaupp\fP video filter is active in general), it -forces RGB conversion. The latter currently does not treat certain -colorspaces like BT.2020 correctly. +\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 @@ -2441,10 +3264,11 @@ completely ordinary video sources. \fBrpi\fP always uses the hardware overlay renderer, even with \fB\-\-vo=gpu\fP\&. .sp -\fBcuda\fP should be safe, but it has been reported to corrupt the -timestamps causing glitched, flashing frames on some files. It can also -sometimes cause massive framedrops for unknown reasons. Caution is -advised. +\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 @@ -2472,13 +3296,13 @@ the first thing you should try is disabling it. This option is for troubleshooting hwdec interop issues. Since it\(aqs a debugging option, its semantics may change at any time. .sp -This is useful for the \fBgpu\fP and \fBopengl\-cb\fP VOs for selecting which +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 \fBopengl\-cb\fP, which has +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\&. @@ -2524,17 +3348,18 @@ 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. +\fBnvdec\fP hwdecs with the OpenGL GPU backend, and with the \fBcuda\-copy\fP +or \fBnvdec\-copy\fP hwdecs in all cases. .sp -By default, the device that is being used to provide \fBgpu\fP output will -also be used for decoding (and in the vast majority of cases, only one -GPU will be present). +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 -Note that when using the \fBcuda\-copy\fP or \fBnvdec\-copy\fP hwdec, a -different option must be passed: \fB\-\-vd\-lavc\-o=gpu=<0..>\fP\&. +For the \fBcopy\fP hwdecs, the default device will be the first device +enumerated by the CUDA libraries \- however that is done. .sp -Note that this option is not available with the Vulkan GPU backend. With -Vulkan, decoding must always happen on the display device. +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 @@ -2644,6 +3469,15 @@ 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. @@ -2763,7 +3597,7 @@ Allow hardware decoding for a given list of codecs only. The special value You can get the list of allowed codecs with \fBmpv \-\-vd=help\fP\&. Remove the prefix, e.g. instead of \fBlavc:h264\fP use \fBh264\fP\&. .sp -By default, this is set to \fBh264,vc1,hevc,vp9\fP\&. Note that +By default, this is set to \fBh264,vc1,hevc,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 @@ -2791,6 +3625,11 @@ detected or reported profiles are somehow incorrect. 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 @@ -2829,6 +3668,8 @@ welcome. A full list of AVOptions can be found in the FFmpeg manual. Some options which used to be direct options can be set with this mechanism, like \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" @@ -3108,7 +3949,7 @@ The standard mandates that DRC is enabled by default, but mpv (and some other players) ignore this for the sake of better audio quality. .TP .B \fB\-\-ad\-lavc\-downmix=<yes|no>\fP -Whether to request audio channel downmixing from the decoder (default: yes). +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. @@ -3123,6 +3964,8 @@ machine and use that, up to the maximum of 16 (default: 1). 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. @@ -3234,7 +4077,7 @@ This option has no influence on files with normal video tracks. .B \fB\-\-audio\-files=<files>\fP Play audio from an external file while viewing a video. .sp -This is a list option. See \fI\%List Options\fP for details. +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 @@ -3333,6 +4176,8 @@ directories. .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 @@ -3364,6 +4209,14 @@ 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 @@ -3410,7 +4263,7 @@ two subtitles at once: use \fB\-\-sid\fP to select the first subtitle index, and \fB\-\-secondary\-sid\fP to select the second index. (The index is printed on the terminal output after the \fB\-\-sid=\fP in the list of streams.) .sp -\fB\-\-sub\-files\fP is a list option (see \fI\%List Options\fP for details), and +\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 @@ -3489,15 +4342,23 @@ Default: no. Use fonts embedded in Matroska container files and ASS scripts (default: yes). These fonts can be used for SSA/ASS subtitle rendering. .TP -.B \fB\-\-sub\-pos=<0\-100>\fP +.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. -.sp -\fBNOTE:\fP +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. Use with care, or use \fB\-\-sub\-margin\-y\fP instead. +rendering in addition to the problem above. +.sp +Using \fB\-\-sub\-margin\-y\fP can achieve this in a better way. .UNINDENT .UNINDENT .TP @@ -3516,6 +4377,8 @@ loaded assuming a framerate of 23.976 at 25 FPS. .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" @@ -3765,7 +4628,8 @@ default. Don\(aqt automatically load external subtitle files. .TP .B exact -Load the media filename with subtitle file extension (default). +Load the media filename with subtitle file extension and possibly +language suffixes (default). .TP .B fuzzy Load all subs containing media filename. @@ -3812,15 +4676,26 @@ 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\fP +.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\&. +\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 @@ -3889,7 +4764,7 @@ the \fBsub\fP configuration subdirectory (usually \fB~/.config/mpv/sub/\fP) .UNINDENT .UNINDENT .sp -This is a list option. See \fI\%List Options\fP for details. +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 @@ -4088,6 +4963,53 @@ 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, currently, always 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\-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 @@ -4155,8 +5077,8 @@ Fullscreen playback. .B \fB\-\-fs\-screen=<all|current|0\-32>\fP In multi\-monitor configurations (i.e. a single desktop that spans across multiple displays), this option tells mpv which screen to go fullscreen to. -If \fBdefault\fP is provided mpv will fallback on using the behavior -depending on what the user provided with the \fBscreen\fP option. +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)" @@ -4284,7 +5206,7 @@ On Windows, if combined with fullscreen mode, this causes mpv to be treated as exclusive fullscreen window that bypasses the Desktop Window Manager. .TP -.B \fB\-\-ontop\-level=<window|system|level>\fP +.B \fB\-\-ontop\-level=<window|system|desktop|level>\fP (OS X only) Sets the level of an ontop window (default: window). .INDENT 7.0 @@ -4295,10 +5217,18 @@ On top of all other windows. .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. @@ -4313,7 +5243,7 @@ applied to window/video with size exceeding size of the screen. (X11 only) Show the video window on all virtual desktops. .TP -.B \fB\-\-geometry=<[W[xH]][+\-x+\-y]>\fP, \fB\-\-geometry=<x:y>\fP +.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 @@ -4322,7 +5252,9 @@ 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". +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. @@ -4372,9 +5304,10 @@ Forces the window width and height to half the screen width and height. Will show black borders to compensate for the video aspect ratio (with most VOs and without \fB\-\-no\-keepaspect\fP). .TP -.B \fB50%+10+10\fP +.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. +pixels below/left of the top left corner of the screen, on the +second workspace. .UNINDENT .UNINDENT .UNINDENT @@ -4470,6 +5403,23 @@ they override this option). 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 @@ -4528,10 +5478,10 @@ See also \fB\-\-monitorpixelaspect\fP and \fB\-\-video\-aspect\-override\fP\&. .UNINDENT .TP .B \fB\-\-hidpi\-window\-scale\fP, \fB\-\-no\-hidpi\-window\-scale\fP -(OS X and X11 only) +(OS X, 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 none\-HiDPI resolutions. This is the default OS X +as having the same size as on non\-HiDPI resolutions. This is the default OS X behavior. .TP .B \fB\-\-native\-fs\fP, \fB\-\-no\-native\-fs\fP @@ -4549,7 +5499,8 @@ 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"). +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 @@ -4786,6 +5737,8 @@ 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" @@ -4821,6 +5774,18 @@ 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 @@ -4872,6 +5837,12 @@ See \fB\-\-demuxer\-mkv\-subtitle\-preroll\fP\&. .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 @@ -4955,7 +5926,8 @@ accept suffixes such as \fBKiB\fP and \fBMiB\fP\&. .TP .B \fB\-\-demuxer\-max\-back\-bytes=<bytesize>\fP This controls how much past data the demuxer is allowed to preserve. This -is useful only if the \fB\-\-demuxer\-seekable\-cache\fP option is enabled. +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 @@ -4963,7 +5935,8 @@ 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). +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 @@ -4975,23 +5948,45 @@ 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 -This controls whether seeking can use the demuxer cache (default: auto). If -enabled, short seek offsets will not trigger a low level demuxer seek +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 -Keep in mind that some events can flush the cache or force a low level -seek anyway, such as switching tracks, or attempting to seek before the -start or after the end of the file. -.sp The special value \fBauto\fP means \fByes\fP in the same situation as \fB\-\-cache\-secs\fP is used (i.e. when the stream appears to be a network stream or the stream cache is enabled). .TP +.B \fB\-\-demuxer\-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, @@ -5020,8 +6015,13 @@ should buffer ahead in seconds (default: 1). As long as no packet has a timestamp difference higher than the readahead amount relative to the last packet returned to the decoder, the demuxer keeps reading. .sp -Note that the \fB\-\-cache\-secs\fP option will override this value if a cache -is enabled, and the value is larger. +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.) @@ -5060,6 +6060,18 @@ 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 @@ -5107,23 +6119,6 @@ with a dummy video, and the normal ways to quit the player will not work (key bindings that normally quit will be shown on OSD only, just like any other binding). See \fI\%INPUT.CONF\fP\&. .TP -.B \fB\-\-input\-file=<filename>\fP -Read commands from the given file. Mostly useful with a FIFO. Since -mpv 0.7.0 also understands JSON commands (see \fI\%JSON IPC\fP), but you can\(aqt -get replies or events. Use \fB\-\-input\-ipc\-server\fP for something -bi\-directional. On MS Windows, JSON commands are not available. -.sp -This can also specify a direct file descriptor with \fBfd://N\fP (UNIX only). -In this case, JSON replies will be written if the FD is writable. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -When the given file is a FIFO mpv opens both ends, so you can do several -\fIecho "seek 10" > mp_pipe\fP and the pipe will stay valid. -.UNINDENT -.UNINDENT -.TP .B \fB\-\-input\-terminal\fP, \fB\-\-no\-input\-terminal\fP \fB\-\-no\-input\-terminal\fP prevents the player from reading key events from standard input. Useful when reading data from standard input. This is @@ -5146,12 +6141,48 @@ Windows. .sp See \fI\%JSON IPC\fP for details. .TP -.B \fB\-\-input\-appleremote=<yes|no>\fP -(OS X only) -Enable/disable Apple Remote support. Enabled by default (except for libmpv). +.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. Enabled by default (except for libmpv). +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 @@ -5288,7 +6319,7 @@ A value of 50 means the bar is half the screen wide. Height of the OSD bar, in percentage of the screen height (default: 3.125). .TP .B \fB\-\-osd\-back\-color=<color>\fP -See \fB\-\-osd\-color\fP\&. Color used for OSD text background. +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). @@ -5300,7 +6331,7 @@ Format text on bold. Format text on italic. .TP .B \fB\-\-osd\-border\-color=<color>\fP -See \fB\-\-osd\-color\fP\&. Color used for the OSD font border. +See \fB\-\-sub\-color\fP\&. Color used for the OSD font border. .sp \fBNOTE:\fP .INDENT 7.0 @@ -5598,6 +6629,21 @@ Set the WebP quality level. Higher means better quality. The default is 75. 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 @@ -5629,11 +6675,27 @@ Software scaler chroma horizontal shifting. See \fB\-\-sws\-scaler\fP\&. .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). In this case, zimg \fImay\fP be used, if the internal -zimg wrapper supports the input and output formats. It will silently -fall back to libswscale if one of these conditions does not apply. +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. @@ -5642,10 +6704,53 @@ If the internal component using the swscale wrapper hooks up logging correctly, a verbose priority log message will indicate whether zimg is being used. .sp -Currently, barely anything uses this. +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 \fB\-\-zimg\-\-scaler=<point|bilinear|bicubic|spline16|lanczos>\fP -Zimg luma scaler to use (default: bilinear). +.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: @@ -5698,6 +6803,8 @@ For testing/debugging only. Can be removed or changed any time. .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 @@ -5851,11 +6958,23 @@ See \fI\%Property Expansion\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. +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 @@ -5864,9 +6983,8 @@ Prepend timing information to each console message. Decide whether to use network cache settings (default: auto). .sp If enabled, use up to \fB\-\-cache\-secs\fP for the cache size (but still limited -to \fB\-\-demuxer\-max\-bytes\fP). \fB\-\-demuxer\-seekable\-cache=auto\fP behaves as if -it was set to \fByes\fP\&. If disabled, \fB\-\-cache\-pause\fP and related are -implicitly disabled. +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 @@ -5880,6 +6998,12 @@ instead. Turn off input stream caching. See \fB\-\-cache\fP\&. .TP .B \fB\-\-cache\-secs=<seconds>\fP +Deprecated. Once this option is removed, there will be no way to limit the +cache size by time (only by size with \fB\-\-demuxer\-max\-bytes\fP). This option +is considered useless, since there is no good reason to limit the cache by +time, and the default value of this option is already something very high. +The interaction with the other cache options is also confusing. +.sp 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 @@ -5969,6 +7093,86 @@ 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 @@ -5985,6 +7189,8 @@ 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" @@ -6046,9 +7252,10 @@ A file containing the private key for the certificate. Specify a referrer path or URL for HTTP requests. .TP .B \fB\-\-network\-timeout=<seconds>\fP -Specify the network timeout in seconds. This affects at least HTTP. The -special value 0 (default) uses the FFmpeg/Libav defaults. If a protocol -is used which does not support timeouts, this option is silently ignored. +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 @@ -6058,12 +7265,14 @@ regarding its internal timeout option. Not only does the RTSP timeout option accept different units (seconds instead of microseconds, causing mpv to pass it huge values), it will also overflow FFmpeg internal calculations. The worst is that merely setting the option will put RTSP -into listening mode, which breaks any client uses. Do not use this -option with RTSP URLs. +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|tcp|http>\fP +.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. @@ -6198,7 +7407,7 @@ for further remarks. .SS GPU renderer options .sp The following video options are currently all specific to \fB\-\-vo=gpu\fP and -\fB\-\-vo=opengl\-cb\fP only, which are the only VOs that implement them. +\fB\-\-vo=libmpv\fP only, which are the only VOs that implement them. .INDENT 0.0 .TP .B \fB\-\-scale=<filter>\fP @@ -6399,6 +7608,8 @@ downscaling. Increases quality, but reduces performance while downscaling. 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 @@ -6553,7 +7764,7 @@ and drivers, this only works reliably when in fullscreen mode. It may also require driver\-specific hacks if using multiple monitors, to ensure mpv syncs to the right one. Compositing window managers can also lead to bad results, as can missing or incorrect display FPS information (see -\fB\-\-display\-fps\fP). +\fB\-\-override\-display\-fps\fP). .TP .B \fB\-\-vulkan\-swap\-mode=<mode>\fP Controls the presentation mode of the vulkan swapchain. This is similar @@ -6597,8 +7808,19 @@ waiting for pipeline bubbles and memory operations. Not beneficial on all GPUs. It\(aqs worth noting that if async compute is enabled, and the device supports more compute queues than graphics queues (bound by the restrictions set by \fB\-\-vulkan\-queue\-count\fP), mpv will internally try and prefer the -use of compute shaders over fragment shaders wherever possible. Not enabled -by default, since it seems to cause issues with some drivers. +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\-\-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 @@ -6652,6 +7874,22 @@ 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 @@ -6664,14 +7902,9 @@ drivers support it.) .sp Currently only relevant for \fB\-\-gpu\-api=d3d11\fP\&. .TP -.B \fB\-\-wayland\-frame\-wait\-offset=<\-100..3000>\fP -Control the amount of offset (in microseconds) to add to wayland\(aqs frame wait -(default 1000). The wayland context assumes that if frame callback or presentation -feedback isn\(aqt received within a certain amount of time then the video is being -rendered offscreen. The time it waits is equal to how long it takes your monitor -to display a frame (i.e. 1/refresh rate) plus the offset. In general, staying -close to your monitor\(aqs refresh rate is preferred, but with a small offset in -case a frame takes a little long to display. +.B \fB\-\-wayland\-app\-id=<string>\fP +Set the client app id for Wayland\-based video output methods. By default, "mpv" +is used. .TP .B \fB\-\-wayland\-disable\-vsync=<yes|no>\fP Disable vsync for the wayland contexts (default: no). Useful for benchmarking @@ -6679,6 +7912,15 @@ 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: 64) 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\&. @@ -6701,11 +7943,15 @@ It may be removed in the future. .UNINDENT .UNINDENT .TP -.B \fB\-\-glsl\-shaders=<file\-list>\fP +.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. Each use of the option will -add another file to the internal list of shaders (see \fI\%List Options\fP). +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" @@ -7097,7 +8343,7 @@ renderer is selected (similar to \fB\-\-gpu\-dumb\-mode\fP). .sp Windows with ANGLE only. .TP -.B \fB\-\-cocoa\-force\-dedicated\-gpu=<yes|no>\fP +.B \fB\-\-macos\-force\-dedicated\-gpu=<yes|no>\fP Deactivates the automatic graphics switching and forces the dedicated GPU. (default: no) .sp @@ -7256,6 +8502,12 @@ defaults. Anything higher than 1000ms though seems too long and shouldn\(aqt be set anyway. OS X 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\-\-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 @@ -7276,7 +8528,7 @@ autoprobe order). auto\-select (default) .TP .B cocoa -Cocoa/OS X (deprecated, use \-\-vo=opengl\-cb instead) +Cocoa/OS X (deprecated, use \-\-vo=libmpv instead) .TP .B win Win32/WGL @@ -7317,12 +8569,6 @@ X11/EGL .TP .B android Android/EGL. Requires \fB\-\-wid\fP be set to an \fBandroid.view.Surface\fP\&. -.TP -.B vdpauglx -Use vdpau presentation with GLX as backing. Experimental use only. -Using this will have no advantage (other than additional bugs or -performance problems), and is for doing experiments only. Will not -be used automatically. .UNINDENT .TP .B \fB\-\-gpu\-api=<type>\fP @@ -7530,12 +8776,12 @@ level, a tone mapping filter will be inserted. For HLG, it has the additional effect of parametrizing the inverse OOTF, in order to get colorimetrically consistent results with the mastering display. For SDR, or when using an ICC (profile (\fB\-\-icc\-profile\fP), setting this to a value -above 100 essentially causes the display to be treated as if it were an HDR +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 100. For HDR curves, it -uses 100 * the transfer function\(aqs nominal peak. +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 @@ -7590,6 +8836,10 @@ 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 @@ -7705,6 +8955,13 @@ 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 @@ -7810,7 +9067,8 @@ not be supported on all platforms. If alpha framebuffers are unavailable, it silently falls back on a normal framebuffer. Note that if you set the \fB\-\-fbo\-format\fP option to a non\-default value, a format with alpha must be specified, or this won\(aqt work. -This does not work on X11 with EGL and Mesa (freedesktop bug 67676). +Whether this really works depends on the windowing system and desktop +environment. .TP .B no Ignore alpha component. @@ -7822,8 +9080,8 @@ any advantages over normal textures. Note that hardware decoding overrides this flag. Could be removed any time. .TP .B \fB\-\-background=<color>\fP -Color used to draw parts of the mpv window not covered by video. See -\fB\-\-osd\-color\fP option how colors are defined. +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 @@ -7877,6 +9135,8 @@ 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) @@ -7987,7 +9247,8 @@ Drop or repeat audio data to compensate desyncing video. See \fB\-\-video\-sync\-adrop\-size\fP\&. This mode will cause severe audio artifacts if the real monitor refresh rate is too different from the reported or -forced rate. +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. @@ -7997,6 +9258,17 @@ 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 +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 @@ -8024,13 +9296,6 @@ the A/V desync cannot be compensated, too high values could lead to chaotic frame dropping due to the audio "overshooting" and skipping multiple video frames before the sync logic can react. .TP -.B \fB\-\-video\-sync\-adrop\-size=<value>\fP -For the \fB\-\-video\-sync=display\-adrop\fP mode. This mode duplicates/drops -audio data to keep audio in sync with video. To avoid audio artifacts on -jitter (which would add/remove samples all the time), this is done in -relatively large, fixed units, controlled by this option. The unit is -seconds. -.TP .B \fB\-\-mf\-fps=<value>\fP Framerate used when decoding from multiple PNG or JPEG files with \fBmf://\fP (default: 1). @@ -8050,6 +9315,8 @@ 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.) @@ -8086,11 +9353,43 @@ does not cause default stream selection over the "proper" file. This makes it slightly less intrusive. (In mpv 0.28.0 and before, this was not quite strictly enforced.) .sp -This is a list option. See \fI\%List Options\fP for details. +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 files. +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|fuzzy>\fP +Whether to load _external_ cover art automatically (default: fuzzy). Similar +to \fB\-\-sub\-auto\fP and \fB\-\-audio\-file\-auto\fP\&. However, it\(aqs currently limited +to picking up a whitelist of "album art" filenames (such as \fBcover.jpg\fP), +so currently only the \fBfuzzy\fP choice is available. In addition, if a video +already has tracks (which are not marked as cover art), external cover art +will not be loaded. +.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). @@ -8209,6 +9508,35 @@ A libavfilter source\-only filter (Conways\(aq Life Game). .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 @@ -8228,8 +9556,7 @@ in the list. .INDENT 3.5 See \fB\-\-ao=help\fP for a list of compiled\-in audio output drivers. The driver \fB\-\-ao=alsa\fP is preferred. \fB\-\-ao=pulse\fP is preferred on systems -where PulseAudio is used. On BSD systems, \fB\-\-ao=oss\fP or \fB\-\-ao=sndio\fP -may work (the latter being experimental). +where PulseAudio is used. .UNINDENT .UNINDENT .sp @@ -8256,21 +9583,6 @@ and multichannel audio at the same time will work as expected. .UNINDENT .UNINDENT .TP -.B \fBoss\fP -OSS audio output driver -.sp -The following global options are supported by this audio output: -.INDENT 7.0 -.TP -.B \fB\-\-oss\-mixer\-device\fP -Sets the audio mixer device (default: \fB/dev/mixer\fP). -.TP -.B \fB\-\-oss\-mixer\-channel\fP -Sets the audio mixer channel (default: \fBpcm\fP). Other valid values -include \fBvol, pcm, line\fP\&. For a complete list of options look for -\fBSOUND_DEVICE_NAMES\fP in \fB/usr/include/linux/soundcard.h\fP\&. -.UNINDENT -.TP .B \fBjack\fP JACK (Jack Audio Connection Kit) audio output driver. .sp @@ -8340,7 +9652,7 @@ Native Mac OS X audio output driver using direct device access and exclusive mode (bypasses the sound server). .TP .B \fBopenal\fP -OpenAL audio output driver +OpenAL audio output driver. This is broken and does not work. .INDENT 7.0 .TP .B \fB\-\-openal\-num\-buffers=<2\-128>\fP @@ -8412,10 +9724,6 @@ Sets the audio buffer length in seconds. Is used only as a hint by the sound system. Playing a file with \fB\-v\fP will show the requested and obtained exact buffer size. A value of 0 selects the sound system default. -.TP -.B \fB\-\-sdl\-bufcnt=<count>\fP -Sets the number of extra audio buffers in mpv. Usually needs not be -changed. .UNINDENT .TP .B \fBnull\fP @@ -8480,32 +9788,6 @@ Append to the file, instead of overwriting it. Always use this with the it will write a WAVE header every time the file is opened. .UNINDENT .TP -.B \fBrsound\fP -Audio output to an RSound daemon. Use \fB\-\-audio\-device=rsound/<hostname>\fP -to set the host name (with \fB<hostname>\fP replaced, without the \fB< >\fP). -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Completely useless, unless you intend to run RSound. Not to be -confused with RoarAudio, which is something completely -different. -.UNINDENT -.UNINDENT -.TP -.B \fBsndio\fP -Audio output to the OpenBSD sndio sound system -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Experimental. There are known bugs and issues. -.UNINDENT -.UNINDENT -.sp -(Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel -layouts.) -.TP .B \fBwasapi\fP Audio output to the Windows Audio Session API. .UNINDENT @@ -8605,6 +9887,9 @@ the display refresh rate. 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 @@ -8641,36 +9926,6 @@ negative values a blurring algorithm (default: 0). Apply a noise reduction algorithm to the video (default: 0; no noise reduction). .TP -.B \fB\-\-vo\-vdpau\-deint=<\-4\-4>\fP -(Deprecated. See note about \fBvdpaupp\fP\&.) -.sp -Select deinterlacing mode (default: 0). In older versions (as well as -MPlayer/mplayer2) you could use this option to enable deinterlacing. -This doesn\(aqt work anymore, and deinterlacing is enabled with either -the \fBd\fP key (by default mapped to the command \fBcycle deinterlace\fP), -or the \fB\-\-deinterlace\fP option. Also, to select the default deint mode, -you should use something like \fB\-\-vf\-defaults=vdpaupp:deint\-mode=temporal\fP -instead of this sub\-option. -.INDENT 7.0 -.TP -.B 0 -Pick the \fBvdpaupp\fP video filter default, which corresponds to 3. -.TP -.B 1 -Show only first field. -.TP -.B 2 -Bob deinterlacing. -.TP -.B 3 -Motion\-adaptive temporal deinterlacing. May lead to A/V desync -with slow video hardware and/or high resolution. -.TP -.B 4 -Motion\-adaptive temporal deinterlacing with edge\-guided spatial -interpolation. Needs fast video hardware. -.UNINDENT -.TP .B \fB\-\-vo\-vdpau\-chroma\-deint\fP (Deprecated. See note about \fBvdpaupp\fP\&.) .sp @@ -8770,39 +10025,9 @@ proper OpenGL drivers, and where ANGLE does not perform well. .UNINDENT .UNINDENT .sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -Before to 0.21.0, \fBdirect3d_shaders\fP and \fBdirect3d\fP were -different, with \fBdirect3d\fP not using shader by default. Now -both use shaders by default, and \fBdirect3d_shaders\fP is a -deprecated alias. Use the \fB\-\-vo\-direct3d\-prefer\-stretchrect\fP -or the \fB\-\-vo\-direct3d\-disable\-shaders\fP options to get the old -behavior of \fBdirect3d\fP\&. -.UNINDENT -.UNINDENT -.sp The following global options are supported by this video output: .INDENT 7.0 .TP -.B \fB\-\-vo\-direct3d\-prefer\-stretchrect\fP -Use \fBIDirect3DDevice9::StretchRect\fP over other methods if possible. -.TP -.B \fB\-\-vo\-direct3d\-disable\-stretchrect\fP -Never render the video using \fBIDirect3DDevice9::StretchRect\fP\&. -.TP -.B \fB\-\-vo\-direct3d\-disable\-textures\fP -Never render the video using D3D texture rendering. Rendering with -textures + shader will still be allowed. Add \fBdisable\-shaders\fP to -completely disable video rendering with textures. -.TP -.B \fB\-\-vo\-direct3d\-disable\-shaders\fP -Never use shaders when rendering video. -.TP -.B \fB\-\-vo\-direct3d\-only\-8bit\fP -Never render YUV video with more than 8 bits per component. -Using this flag will force software conversion to 8\-bit. -.TP .B \fB\-\-vo\-direct3d\-disable\-texture\-align\fP Normally texture sizes are always aligned to 16. With this option enabled, the video texture will always have exactly the same size as @@ -8874,7 +10099,7 @@ color space conversion and chroma upsampling is generally in the hand of the hardware decoder APIs. .sp \fBgpu\fP makes use of FBOs by default. Sometimes you can achieve better -quality or performance by changing the \fB\-\-gpu\-fbo\-format\fP option to +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 OS X setups being very slow with \fBrgb16\fP but fast @@ -8990,8 +10215,16 @@ This driver is a joke. .TP .B \fBtct\fP Color Unicode art video output driver that works on a text console. -Depends on support of true color by modern terminals to display the images -at full color range. On Windows it requires an ansi terminal such as mintty. +By default depends on support of true color by modern terminals to display +the images at full color range, but 256\-colors outout 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 @@ -9015,6 +10248,116 @@ These default to 80x25 if the terminal size cannot be determined. 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. +.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 +Choose diffuse type automatically +.TP +.B none +Don\(aqt diffuse +.TP +.B atkinson +Diffuse with Bill Atkinson\(aqs method. (Default) +.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) +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. +This option has no effect if fixed palette is used. +.TP +.B \fB\-\-vo\-sixel\-threshold=<threshold>\fP (default: \-1) +When using a dynamic 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), however, it seems that in \fBmlterm\fP it +causes image corruption. The default (\-1) will change the palette +on every frame and will have better quality, and no corruption in +\fBmlterm\fP\&. +.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. @@ -9113,6 +10456,9 @@ 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 @@ -9230,6 +10576,9 @@ To use hardware decoding with \fB\-\-vo=gpu\fP instead, use 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 @@ -9450,6 +10799,30 @@ Changing playback speed would change pitch, leaving audio tempo at .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 @@ -9517,6 +10890,13 @@ 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 @@ -9624,6 +11004,9 @@ 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.) @@ -9632,12 +11015,24 @@ filters is currently still possible, but deprecated.) 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 -Deletes the filter. The filter can even given the way it was added (filter -name and its full argument list), by label (prefixed with \fB@\fP), or as -index number. Index numbers start at 0, negative numbers address the end of -the list (\-1 is the last). (Passing multiple filters is currently still -possible, but deprecated.) +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. @@ -9949,6 +11344,10 @@ same values as the \fBstereo\-in\fP option. 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 @@ -9958,6 +11357,18 @@ aspect ratio is an implementation detail, and might change later. 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 @@ -10451,6 +11862,55 @@ Print computed fingerprints the the terminal (default: no). This is mostly for testing and such. Scripts should use \fBvf\-metadata\fP to read information from this filter instead. .UNINDENT +.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 @@ -10469,12 +11929,12 @@ list of supported formats. Specifies the output format options for libavformat. See \fB\-\-ofopts=help\fP for a full list of supported options. .sp -Options are managed in lists. There are a few commands to manage the -options list. +This is a key/value list option. See \fI\%List Options\fP for details. .INDENT 7.0 .TP -.B \fB\-\-ofopts\-add=<options1[,options2,...]>\fP -Appends the options given as arguments to the options list. +.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. @@ -10502,12 +11962,12 @@ selects 128 kbps MP3 encoding. .UNINDENT .UNINDENT .sp -Options are managed in lists. There are a few commands to manage the -options list. +This is a key/value list option. See \fI\%List Options\fP for details. .INDENT 7.0 .TP -.B \fB\-\-oacopts\-add=<options1[,options2,...]>\fP -Appends the options given as arguments to the options list. +.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. @@ -10542,12 +12002,12 @@ selects VBR quality factor 23 for H.264 encoding. .UNINDENT .UNINDENT .sp -Options are managed in lists. There are a few commands to manage the -options list. +This is a key/value list option. See \fI\%List Options\fP for details. .INDENT 7.0 .TP -.B \fB\-\-ovcopts\-add=<options1[,options2,...]>\fP -Appends the options given as arguments to the options list. +.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. @@ -10572,6 +12032,8 @@ 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" @@ -10586,6 +12048,8 @@ adds a title and a comment to the output file. .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" @@ -10672,6 +12136,8 @@ mpv \-\-input\-test \-\-force\-window \-\-idle .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 @@ -10711,13 +12177,90 @@ If \fBa\fP or \fBa\-b\fP or \fBb\fP are already bound, this will run the first c 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 +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> ::= (<string> | " <quoted_string> ")\fP +.fi .sp -\fB<command> ::= [<prefixes>] <command_name> (<argument>)*\fP -\fB<argument> ::= (<string> | " <quoted_string> " )\fP .sp \fBcommand_name\fP is an unquoted string with the command name itself. See \fI\%List of Input Commands\fP for a list. @@ -10762,11 +12305,10 @@ This applies to certain APIs, such as \fBmp.command_native()\fP (with tables tha have string keys) in Lua scripting, or \fBmpv_command_node()\fP (with MPV_FORMAT_NODE_MAP) in the C libmpv client API. .sp -Like with array commands, quoting and escaping is inherently not needed in the -normal case. -.sp -The name of each command is defined in each command description in the -\fI\%List of Input Commands\fP\&. \fB\-\-input\-cmdlist\fP also lists them. +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. @@ -10836,6 +12378,13 @@ The first argument is optional, and can change the behavior: 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. @@ -10948,8 +12497,37 @@ If the first file on the playlist is currently played, do nothing. 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. +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 @@ -10968,8 +12546,10 @@ before running this command.) .sp The third argument is a list of options and values which should be set while the file is playing. It is of the form \fBopt1=value1,opt2=value2,..\fP\&. -Not all options can be changed this way. Some options require a restart -of the player. +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). @@ -11004,6 +12584,12 @@ will have after moving.) 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 @@ -11054,7 +12640,7 @@ and \fBexecvp\fP behavior. .TP .B \fBplayback_only\fP (\fBMPV_FORMAT_FLAG\fP) Boolean indicating whether the process should be killed when playback -terminates (optional, default: yes). If enabled, stopping playback +terminates (optional, default: true). If enabled, stopping playback will automatically kill the process, and you can\(aqt start it outside of playback. .TP @@ -11069,6 +12655,36 @@ 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): @@ -11077,7 +12693,7 @@ The command returns the following result (as \fBMPV_FORMAT_NODE_MAP\fP): .B \fBstatus\fP (\fBMPV_FORMAT_INT64\fP) The raw exit status of the process. It will be negative on error. The meaning of negative values is undefined, other than meaning error (and -does not necessarily correspond to OS low level exit status values). +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 @@ -11096,13 +12712,12 @@ the process was terminated in an unusual way. The string \fBinit\fP if the process could not be started. .sp On Windows, \fBkilled\fP is only returned when the process has been -killed by mpv as a result of \fBplayback_only\fP being set to \fByes\fP\&. +killed by mpv as a result of \fBplayback_only\fP being set to true. .TP .B \fBkilled_by_us\fP (\fBMPV_FORMAT_FLAG\fP) -Set to \fByes\fP if the process has been killed by mpv, for example as a -result of \fBplayback_only\fP being set to \fByes\fP, aborting the command -(e.g. by \fBmp.abort_async_command()\fP), or if the player is about to -exit. +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 @@ -11124,6 +12739,32 @@ 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. @@ -11239,10 +12880,24 @@ on the OSD. Write the resume config file that the \fBquit\-watch\-later\fP command writes, but continue playback normally. .TP -.B \fBstop\fP +.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). @@ -11332,6 +12987,10 @@ Change audio filter chain. See \fBvf\fP command. .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 @@ -11342,8 +13001,8 @@ Overwrite the previous filter chain with the new one. Append the new filter chain to the previous one. .TP .B <toggle> -Check if the given filter (with the exact parameters) is already -in the video chain. If yes, remove the filter. If no, add the filter. +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 @@ -11351,12 +13010,15 @@ 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. +filter. Deprecated, use \fBremove\fP\&. .TP .B <clr> Remove all filters. Note that like the other sub\-commands, this does @@ -11426,6 +13088,8 @@ 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 @@ -11452,9 +13116,13 @@ 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 @@ -11559,6 +13227,122 @@ to see how to handle this correctly. 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 @@ -11598,9 +13382,15 @@ The name of the binding (as established above). 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 key state consists of 2 letters: +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 @@ -11610,6 +13400,9 @@ binding), \fBp\fP (key was pressed; happens if up/down can\(aqt be tracked). 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 @@ -11652,18 +13445,32 @@ name. .B \fBaf\-command <label> <command> <argument>\fP Same as \fBvf\-command\fP, but for audio filters. .TP -.B \fBapply\-profile <name>\fP +.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 -There is no such thing as "unapplying" a profile \- applying a profile -merely sets all option values listed within the profile. +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 @@ -11712,51 +13519,264 @@ write newly received data to it. 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\&. +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 -\fBNOTE:\fP +The event has the following fields: .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 +.TP +.B \fBresult\fP +The result (on success) of any \fBmpv_node\fP type, if any. .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. +.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 author reserves the right to remove this command if enough motivation -is found to move this functionality to a trivial Lua script. +The event has the following fields: +.INDENT 7.0 .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. +.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 -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. +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 -Undocumented commands: \fBao\-reload\fP (experimental/internal). +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 @@ -11769,6 +13789,12 @@ the player freeze randomly. Basically, nobody should use this API. 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 @@ -11780,13 +13806,18 @@ 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. +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 @@ -11798,58 +13829,25 @@ without having to "probe" the available streams at first. 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. -.UNINDENT -.SS Legacy hook API .sp -\fBWARNING:\fP -.INDENT 0.0 -.INDENT 3.5 -The legacy API is deprecated and will be removed soon. -.UNINDENT -.UNINDENT -.sp -There are two special commands involved. Also, the client must listen for -client messages (\fBMPV_EVENT_CLIENT_MESSAGE\fP in the C API). -.INDENT 0.0 +Ordered before \fBend\-file\fP\&. Will also happen in the error case (then after +\fBon_load_fail\fP). .TP -.B \fBhook\-add <hook\-name> <id> <priority>\fP -Subscribe to the hook identified by the first argument (basically, the -name of event). The \fBid\fP argument is an arbitrary integer chosen by the -user. \fBpriority\fP is used to sort all hook handlers globally across all -clients. Each client can register multiple hook handlers (even for the -same hook\-name). Once the hook is registered, it cannot be unregistered. -.sp -When a specific event happens, all registered handlers are run serially. -This uses a protocol every client has to follow explicitly. When a hook -handler is run, a client message (\fBMPV_EVENT_CLIENT_MESSAGE\fP) is sent to -the client which registered the hook. This message has the following -arguments: -.INDENT 7.0 -.IP 1. 3 -the string \fBhook_run\fP -.IP 2. 3 -the \fBid\fP argument the hook was registered with as string (this can be -used to correctly handle multiple hooks registered by the same client, -as long as the \fBid\fP argument is unique in the client) -.IP 3. 3 -something undefined, used by the hook mechanism to track hook execution -.UNINDENT -.sp -Upon receiving this message, the client can handle the event. While doing -this, the player core will still react to requests, but playback will -typically be stopped. -.sp -When the client is done, it must continue the core\(aqs hook execution by -running the \fBhook\-ack\fP command. +.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 \fBhook\-ack <string>\fP -Run the next hook in the global chain of hooks. The argument is the 3rd -argument of the client message that starts hook execution for the -current client. +.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 @@ -12001,9 +13999,13 @@ an option at runtime. .INDENT 0.0 .INDENT 3.5 Most options can be set as runtime via properties as well. Just remove the -leading \fB\-\-\fP from the option name. These are not documented. Only -properties which do not exist as option with the same name, or which have -very different behavior from the options are documented below. +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 @@ -12016,7 +14018,7 @@ OSD formatting will display it in the form of \fB+1.23456%\fP, with the number being \fB(raw \- 1) * 100\fP for the given raw property value. .TP .B \fBdisplay\-sync\-active\fP -Return whether \fB\-\-video\-sync=display\fP is actually active. +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 @@ -12067,9 +14069,9 @@ determine it yourself, for example by using the \fBworking\-directory\fP property. .TP .B \fBstream\-open\-filename\fP -The full path to the currently played media. This is different only from -\fBpath\fP in special cases. In particular, if \fB\-\-ytdl=yes\fP is used, and -the URL is detected by \fByoutube\-dl\fP, then the script will set this +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 @@ -12168,7 +14170,7 @@ time of the file (could affect e.g. transport streams). See Remaining length of the file in seconds. Note that the file duration is not always exactly known, so this is an estimate. .TP -.B \fBaudio\-pts\fP (R) +.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 @@ -12189,6 +14191,18 @@ Current chapter number. The number of the first chapter is 0. .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. @@ -12208,12 +14222,12 @@ index. 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 +.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 -\fByes\fP if this is the default edition, \fBno\fP otherwise. +Whether this is the default edition. .TP .B \fBedition\-list/N/title\fP Edition title as stored in the file. Not always available. @@ -12315,24 +14329,26 @@ added by \fB\-\-vf=lavfi=cropdetect\fP\&. Equivalent to \fBvf\-metadata/<filter\-label>\fP, but for audio filters. .TP .B \fBidle\-active\fP -Return \fByes\fP if no file is loaded, but the player is staying around +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 -Return \fByes\fP if the playback core is paused, otherwise \fBno\fP\&. This can -be different \fBpause\fP in special situations, such as when the player -pauses itself due to low network cache. +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 if playback is restarting or if nothing is -playing at all. In other words, it\(aqs only \fBno\fP if there\(aqs actually +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 (R) +.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 @@ -12345,14 +14361,13 @@ Approximate time of video buffered in the demuxer, in seconds. Same as data in demuxer. .TP .B \fBdemuxer\-cache\-idle\fP -Returns \fByes\fP if the demuxer is idle, which means the demuxer cache is -filled to the requested amount, and is currently not reading more data. +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 -Various undocumented or half\-documented things. -.sp Each entry in \fBseekable\-ranges\fP represents a region in the demuxer cache -that can be seeked to. If there are multiple demuxers active, this only +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. @@ -12367,8 +14382,8 @@ can actually be used for cached seeking. points to the beginning of the stream (BOF). This implies you cannot seek before this position at all. \fBeof\-cached\fP indicates whether the seek range with the highest timestamp points to the end of the stream (EOF). If both -\fBbof\-cached\fP and \fBeof\-cached\fP are set to \fByes\fP, and there\(aqs only 1 -cache range, the entire stream is cached. +\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 @@ -12377,7 +14392,19 @@ demuxer position (it ignores seek ranges after it). .sp \fBfile\-cache\-bytes\fP is the number of bytes stored in the file cache. This includes all overhead, and possibly unused data (like pruned data). This -member is missing if the file cache is not active. +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 @@ -12396,6 +14423,10 @@ MPV_FORMAT_NODE_MAP "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 @@ -12405,14 +14436,14 @@ Other fields (might be changed or removed in the future): .INDENT 7.0 .TP .B \fBeof\fP -True if the reader thread has hit the end of the file. +Whether the reader thread has hit the end of the file. .TP .B \fBunderrun\fP -True if the reader thread could not satisfy a decoder\(aqs request for a +Whether the reader thread could not satisfy a decoder\(aqs request for a new packet. .TP .B \fBidle\fP -True if the thread is currently not reading. +Whether the thread is currently not reading. .TP .B \fBtotal\-bytes\fP Sum of packet bytes (plus some overhead estimation) of the entire packet @@ -12420,38 +14451,37 @@ queue, including cached seekable ranges. .UNINDENT .TP .B \fBdemuxer\-via\-network\fP -Returns \fByes\fP if the stream demuxed via the main demuxer is most likely -played via network. What constitutes "network" is not always clear, might -be used for other types of untrusted streams, could be wrong in certain -cases, and its definition might be changing. Also, external files (like -separate audio files or streams) do not influence the value of this -property (currently). +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 (R) -Returns the start time reported by the demuxer in fractional seconds. +.B \fBdemuxer\-start\-time\fP +The start time reported by the demuxer in fractional seconds. .TP .B \fBpaused\-for\-cache\fP -Returns \fByes\fP when playback is paused because of waiting for the cache. +Whether playback is paused because of waiting for the cache. .TP .B \fBcache\-buffering\-state\fP -Return the percentage (0\-100) of the cache fill status until the player -will unpause (related to \fBpaused\-for\-cache\fP). +The percentage (0\-100) of the cache fill status until the player will +unpause (related to \fBpaused\-for\-cache\fP). .TP .B \fBeof\-reached\fP -Returns \fByes\fP if end of playback was reached, \fBno\fP otherwise. Note -that this is usually interesting only if \fB\-\-keep\-open\fP is enabled, -since otherwise the player will immediately play the next file (or exit -or enter idle mode), and in these cases the \fBeof\-reached\fP property will -logically be cleared immediately after it\(aqs set. +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 -Returns \fByes\fP if the player is currently seeking, or otherwise trying -to restart playback. (It\(aqs possible that it returns \fByes\fP while a file -is loaded. This is because the same underlying code is used for seeking and +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 -Return \fByes\fP if the audio mixer is active, \fBno\fP otherwise. +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. @@ -12522,14 +14552,14 @@ MPV_FORMAT_NODE_MAP Same as \fBaudio\-params\fP, but the format of the data written to the audio API. .TP -.B \fBcolormatrix\fP (R) +.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 (R) +.B \fBcolormatrix\-input\-range\fP See \fBcolormatrix\fP\&. .TP -.B \fBcolormatrix\-primaries\fP (R) +.B \fBcolormatrix\-primaries\fP See \fBcolormatrix\fP\&. .TP .B \fBhwdec\fP (RW) @@ -12545,8 +14575,8 @@ hardware decoder. Since mpv 0.18.0, \fBhwdec\-current\fP is available for this purpose. .TP .B \fBhwdec\-current\fP -Return the current hardware decoding in use. If decoding is active, return -one of the values used by the \fBhwdec\fP option/property. \fBno\fP indicates +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 @@ -12584,16 +14614,15 @@ etc. applied). This has a number of sub\-properties: 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/plane\-depth\fP -Bit depth for each color component as integer. This is only exposed -for planar or single\-component formats, and is unavailable for other -formats. -.TP .B \fBvideo\-params/w\fP, \fBvideo\-params/h\fP Video size as integers, with no aspect correction applied. .TP @@ -12633,6 +14662,11 @@ Intended display rotation in degrees (clockwise). .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, @@ -12645,6 +14679,7 @@ the following contents: .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 @@ -12660,6 +14695,8 @@ MPV_FORMAT_NODE_MAP "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 @@ -12691,19 +14728,21 @@ are used on OSD, the information might be off by a few frames due to OSD redrawing and frame display being somewhat disconnected, and you might have to pause and force a redraw. .sp -Sub\-properties: +This has a number of sub\-properties: .INDENT 7.0 -.INDENT 3.5 -.sp -.nf -.ft C -video\-frame\-info/picture\-type -video\-frame\-info/interlaced -video\-frame\-info/tff -video\-frame\-info/repeat -.ft P -.fi -.UNINDENT +.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 @@ -12726,9 +14765,24 @@ 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 +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 \fBwindow\-minimized\fP -Return whether the video window is minimized or not. +.B \fBcurrent\-window\-scale\fP +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. The property is unavailable if no video is active. +.TP +.B \fBfocused\fP +Whether the window has focus. Currently works only on X11, Wayland and +macOS. .TP .B \fBdisplay\-names\fP Names of the displays that the mpv window covers. On X11, these @@ -12739,21 +14793,32 @@ window (as determined by the MonitorFromWindow API.) On macOS these are the Display Product Names as used in the System Information and only one display name is returned since a window can only be on one screen. .TP -.B \fBdisplay\-fps\fP (RW) +.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 -Only available if display\-sync mode (as selected by \fB\-\-video\-sync\fP) is -active. Returns the actual rate at which display refreshes seem to occur, -measured by system time. +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\-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. @@ -12765,35 +14830,145 @@ The read and write components of this option can be split up into Last known OSD width (can be 0). This is needed if you want to use the \fBoverlay\-add\fP command. It gives you the actual OSD size, which can be different from the window size in some cases. +.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 -Return the current subtitle text regardless of sub visibility. -Formatting is stripped. If the subtitle is not text\-based -(i.e. DVD/BD subtitles), an empty string is returned. +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 \fBsub\-start\fP -Return the current subtitle start time (in seconds). If there\(aqs multiple -current subtitles, returns the first start time. If no current subtitle is -present null is returned instead. +The current subtitle start time (in seconds). If there\(aqs multiple current +subtitles, returns the first start time. If no current subtitle is present +null is returned instead. .TP .B \fBsub\-end\fP -Return the current subtitle start time (in seconds). If there\(aqs multiple -current subtitles, return the last end time. If no current subtitle is -present, or if it\(aqs present but has unknown or incorrect duration, null -is returned instead. +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 \fBplaylist\-pos\fP (RW) -Current position on playlist. The first entry is on position 0. Writing -to the property will restart playback at the written entry. +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 @@ -12811,17 +14986,24 @@ Number of playlist entries (same as \fBplaylist\-count\fP). .B \fBplaylist/N/filename\fP Filename of the Nth entry. .TP -.B \fBplaylist/N/current\fP, \fBplaylist/N/playing\fP -\fByes\fP if this entry is currently playing (or being loaded). -Unavailable or \fBno\fP otherwise. When changing files, \fBcurrent\fP and -\fBplaying\fP can be different, because the currently playing file hasn\(aqt -been unloaded yet; in this case, \fBcurrent\fP refers to the new -selection. (Since mpv 0.7.0.) +.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, @@ -12838,6 +15020,7 @@ MPV_FORMAT_NODE_ARRAY "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 @@ -12862,7 +15045,11 @@ within tracks of the same type (sub/audio/video), but otherwise not. 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. +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. @@ -12871,32 +15058,39 @@ Track title as it is stored in the file. Not always available. Track language as identified by the file. Not always available. .TP .B \fBtrack\-list/N/albumart\fP -\fByes\fP if this is a video track that consists of a single picture, -\fBno\fP or unavailable otherwise. This is used for video tracks that are -really attached pictures in audio files. +\fByes\fP/true if this is a video track that consists of a single +picture, \fBno\fP/false or unavailable otherwise. This is used for video +tracks that are really attached pictures in audio files. .TP .B \fBtrack\-list/N/default\fP -\fByes\fP if the track has the default flag set in the file, \fBno\fP -otherwise. +\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 if the track has the forced flag set in the file, \fBno\fP -otherwise. +\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 if the track is an external file, \fBno\fP otherwise. This is -set for separate subtitle files. +\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 if the track is currently decoded, \fBno\fP otherwise. +\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 @@ -12967,6 +15161,7 @@ MPV_FORMAT_NODE_ARRAY "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 @@ -12991,6 +15186,26 @@ MPV_FORMAT_NODE_ARRAY .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 +A sub\-entry is accessible only if a track of that type is actually selected. +Tracks selected via \fB\-\-lavfi\-complex\fP never appear under this property. +\fBcurrent\-tracks\fP and \fBcurrent\-tracks/\fP are currently not accessible, and +will not return anything. +.sp +Scripts etc. should not use this. They should use \fBtrack\-list\fP, loop over +all tracks, and inspect the \fBselected\fP field to test whether a track is +selected (or compare the \fBid\fP field to the \fBvideo\fP / \fBaudio\fP etc. +options). +.TP .B \fBchapter\-list\fP List of chapters, current entry marked. Currently, the raw property value is useless. @@ -13053,20 +15268,20 @@ MPV_FORMAT_NODE_ARRAY It\(aqs also possible to write the property using this format. .TP .B \fBseekable\fP -Return whether it\(aqs generally possible to seek in the current file. +Whether it\(aqs generally possible to seek in the current file. .TP .B \fBpartially\-seekable\fP -Return \fByes\fP if the current file is considered seekable, but only because -the cache is active. This means small relative seeks may be fine, but larger -seeks may fail anyway. Whether a seek will succeed or not is generally not -known in advance. +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 true, \fBseekable\fP will also return true. +If this property returns \fByes\fP/true, so will \fBseekable\fP\&. .TP .B \fBplayback\-abort\fP -Return whether playback is stopped or is to be stopped. (Useful in obscure -situations like during \fBon_load\fP hook processing, when the user can -stop playback, but the script has to explicitly end processing.) +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 @@ -13104,9 +15319,9 @@ processed for C escape sequences before passing it to the OSD code. A list of tags can be found here: \fI\%http://docs.aegisub.org/latest/ASS_Tags/\fP .TP .B \fBvo\-configured\fP -Return whether the VO is configured right now. Usually this corresponds to -whether the video window is visible. If the \fB\-\-force\-window\fP option is -used, this is usually always returns \fByes\fP\&. +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 @@ -13174,6 +15389,15 @@ MPV_FORMAT_NODE_MAP 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 @@ -13207,9 +15431,9 @@ achieved with e.g. \fB${=video\-bitrate}\fP\&. These properties shouldn\(aqt be used anymore. .TP .B \fBaudio\-device\-list\fP -Return the list of discovered audio devices. This is mostly for use with -the client API, and reflects what \fB\-\-audio\-device=help\fP with the command -line player returns. +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 @@ -13260,9 +15484,31 @@ Current video output driver (name as used with \fB\-\-vo\fP). .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 -Return the working directory of the mpv process. Can be useful for JSON IPC -users, because the command line player usually works with relative paths. +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 @@ -13315,32 +15561,40 @@ The encoder names (\fBdriver\fP entries) can be passed to \fB\-\-ovc\fP and 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 -Return the mpv version/copyright string. Depending on how the binary was -built, it might contain either a release version, or just a git hash. +The mpv version/copyright string. Depending on how the binary was built, it +might contain either a release version, or just a git hash. .TP .B \fBmpv\-configuration\fP -Return the configuration arguments which were passed to the build system +The configuration arguments which were passed to the build system (typically the way \fB\&./waf configure ...\fP was invoked). .TP .B \fBffmpeg\-version\fP -Return the contents of the \fBav_version_info()\fP API call. This is a string -which identifies the build in some way, either through a release version -number, or a git hash. This applies to Libav as well (the property is -still named the same.) This property is unavailable if mpv is linked against -older FFmpeg and Libav versions. +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) -Read\-only access to value of option \fB\-\-<name>\fP\&. Most options can be -changed at runtime by writing to this property. Note that many options -require reloading the file for changes to take effect. If there is an -equivalent property, prefer setting the property instead. +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 +.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 @@ -13359,19 +15613,19 @@ sub\-properties \- they may change radically in the feature. .INDENT 7.0 .TP .B \fBoption\-info/<name>/name\fP -Returns the name of the option. +The name of the option. .TP .B \fBoption\-info/<name>/type\fP -Return the name of the option type, like \fBString\fP or \fBInteger\fP\&. -For many complex types, this isn\(aqt very accurate. +The name of the option type, like \fBString\fP or \fBInteger\fP\&. For many +complex types, this isn\(aqt very accurate. .TP .B \fBoption\-info/<name>/set\-from\-commandline\fP -Return \fByes\fP if the option was set from the mpv command line, -\fBno\fP otherwise. What this is set to if the option is e.g. changed -at runtime is left undefined (meaning it could change in the future). +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 -Return \fByes\fP if the option was set per\-file. This is the case with +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. @@ -13393,15 +15647,67 @@ available. .UNINDENT .TP .B \fBproperty\-list\fP -Return the list of top\-level properties. +The list of top\-level properties. .TP .B \fBprofile\-list\fP -Return the list of profiles and their contents. This is highly -implementation\-specific, and may change any time. Currently, it returns -an array of options for each profile. Each option has a name and a value, -with the value currently always being a string. Note that the options array -is not a map, as order matters and duplicate entries are possible. Recursive +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 @@ -13410,55 +15716,32 @@ caveats with some properties (due to historical reasons): .INDENT 0.0 .TP .B \fBvid\fP, \fBaid\fP, \fBsid\fP -While playback is active, you can set existing tracks only. (The option -allows setting any track ID, and which tracks to enable is chosen at -loading time.) +While playback is active, these result 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 -Option changes at runtime are affected by this as well. +Before mpv 0.31.0, you could set existing tracks at runtime only. .TP .B \fBdisplay\-fps\fP -If a VO is created, this will return either the actual display FPS, or -an invalid value, instead of the option value. +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 new value will be rejected. Setting the option or -setting the property outside of playback will always succeed/fail in the -same way. Also, there are no \fBvf\-add\fP etc. properties, but you can use -the \fBvf\fP/\fBaf\fP group of commands to achieve the same. +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 -Option changes at runtime are affected by this as well. -.TP -.B \fBedition\fP -While a file is loaded, the property will always return the effective -edition, and setting the \fBauto\fP value will show somewhat strange behavior -(the property eventually switching to whatever is the default edition). +This behavior changed in mpv 0.31.0. Before this, the new value was rejected +\fIiff\fP video (for \fBvf\fP) or audio (for \fBaf\fP) was active. If playback was +not active, the behavior was the same as the current behavior. .TP .B \fBplaylist\fP The property is read\-only and returns the current internal playlist. The option is for loading playlist during command line parsing. For client API uses, you should use the \fBloadlist\fP command instead. .TP -.B \fBwindow\-scale\fP -Might verify the set value when setting while a window is created. -.TP -.B \fBaudio\-file\fP, \fBsub\-file\fP, \fBexternal\-file\fP -These options/properties are actually lists of filenames. To make the -command\-line interface easier, each \fB\-\-audio\-file=...\fP option appends -the full string to the internal list. However, when used as properties, -every time you set the property as a string the internal list will be -replaced with a single entry containing the string you set. \fB,\fP or other -separators are never used. You have to use \fBMPV_FORMAT_NODE_ARRAY\fP (or -corresponding API, e.g. \fBmp.set_property_native()\fP with a table in Lua) -to set multiple entries. -.sp -Strictly speaking, option access via API (e.g. \fBmpv_set_option_string()\fP) -has the same problem, and it\(aqs only a difference between CLI/API. -.TP -.B \fBplaylist\-pos\fP, \fBchapter\fP -These properties behave different from the deprecated options with the same -names. -.TP .B \fBprofile\fP, \fBinclude\fP These are write\-only, and will perform actions as they are written to, exactly as if they were used on the mpv CLI commandline. Their only use is @@ -13938,11 +16221,12 @@ or \fBknob\fP\&. This is relative to the full height of the seekbar. .B \fBseekbarkeyframes\fP Default: yes .sp -Controls the mode used to seek when dragging the seekbar. By default, -keyframes are used. If set to false, exact seeking on mouse drags -will be used instead. Keyframes are preferred, but exact seeks may be -useful in cases where keyframes cannot be found. Note that using exact -seeks can potentially make mouse dragging much slower. +Controls the mode used to seek when dragging the seekbar (default: true). If +set to true, default seeking mode is used (usually keyframes, but player +defaults and heuristics can change it to exact). If set to false, exact +seeking on mouse drags will be used instead. Keyframes are preferred, but +exact seeks may be useful in cases where keyframes cannot be found. Note +that using exact seeks can potentially make mouse dragging much slower. .TP .B \fBseekrangestyle\fP Default: inverted @@ -14087,10 +16371,13 @@ 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.) +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 layout only. The other -layouts do not change if this option is set. +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 @@ -14099,6 +16386,36 @@ filled with the background color (black by default). 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.) .UNINDENT .SS Script Commands .sp @@ -14179,7 +16496,38 @@ _ T{ 2 T} T{ -Show frame timings +Show frame timings (scroll) +T} +_ +T{ +3 +T} T{ +Input cache stats +T} +_ +T{ +4 +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 @@ -14209,9 +16557,26 @@ 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 .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 @@ -14311,35 +16676,180 @@ for example: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C -e script\-binding stats/display\-stats -E script\-binding stats/display\-stats\-toggle -.ft P -.fi +.nf +.ft C +e script\-binding stats/display\-stats +E script\-binding stats/display\-stats\-toggle +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Using \fBinput.conf\fP, it is also possible to directly display a certain page: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +i script\-binding stats/display\-page\-1 +e script\-binding stats/display\-page\-2 +.ft P +.fi +.UNINDENT +.UNINDENT +.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 +Run the typed command. +.TP +.B Shift+ENTER +Type a literal newline character. +.TP +.B Ctrl+LEFT and Ctrl+RIGHT +Move cursor to previous/next word. +.TP +.B UP and DOWN +Navigate command history. +.TP +.B PGUP +Go to the first command in the history. +.TP +.B PGDN +Stop navigating command history. +.TP +.B INSERT +Toggle insert mode. +.TP +.B Shift+INSERT +Paste text (uses the primary selection on X11). +.TP +.B TAB +Complete the command or property name at the cursor. +.TP +.B Ctrl+C +Clear current line. +.TP +.B Ctrl+K +Delete text from the cursor to the end of the line. +.TP +.B Ctrl+L +Clear all log messages from the console. +.TP +.B Ctrl+U +Delete text from the cursor to the beginning of the line. +.TP +.B Ctrl+V +Paste text (uses the clipboard on X11). +.TP +.B Ctrl+W +Delete text from the cursor to the beginning of the current word. +.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 -Using \fBinput.conf\fP, it is also possible to directly display a certain page: +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 -.INDENT 3.5 +.TP +.B \fBscale\fP +Default: 1 .sp -.nf -.ft C -i script\-binding stats/display\-page\-1 -e script\-binding stats/display\-page\-2 -.ft P -.fi -.UNINDENT +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. Scripts passed to the \fB\-\-script\fP option, or found in -the \fBscripts\fP subdirectory of the mpv configuration directory (usually -\fB~/.config/mpv/scripts/\fP) will be loaded on program start. mpv also appends the -\fBscripts\fP subdirectory to the end of Lua\(aqs path so you can import scripts from -there too. Since it\(aqs added to the end, don\(aqt name scripts you want to import -the same as Lua libraries because they will be overshadowed by them. +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 @@ -14365,6 +16875,47 @@ mp.observe_property("pause", "bool", on_pause_change) .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 +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 @@ -14466,12 +17017,31 @@ nil if it\(aqs missing. .TP .B \fBmp.command_native_async(table [,fn])\fP Like \fBmp.command_native()\fP, but the command is ran asynchronously (as far -as possible), and upon completion, fn is called. fn has two arguments: -\fBfn(success, result, error)\fP\&. \fBsuccess\fP is always a Boolean and is true -if the command was successful, otherwise false. The second parameter is -the result value (can be nil) in case of success, nil otherwise (as returned -by \fBmp.command_native()\fP). The third parameter is the error string in case -of an error, nil otherwise. +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\&. @@ -14579,7 +17149,9 @@ 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. +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: @@ -14593,11 +17165,31 @@ If set to \fBtrue\fP, enables key repeat for this specific binding. .B \fBcomplex\fP If set to \fBtrue\fP, then \fBfn\fP is called on both key up and down events (as well as key repeat, if enabled), with the first -argument being a table. This table has an \fBevent\fP entry, which -is set to one of the strings \fBdown\fP, \fBrepeat\fP, \fBup\fP or -\fBpress\fP (the latter if key up/down can\(aqt be tracked). It further -has an \fBis_mouse\fP entry, which tells whether the event was caused -by a mouse button. +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 @@ -14705,6 +17297,10 @@ 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. @@ -14816,6 +17412,11 @@ The script \fB/path/to/fooscript.lua\fP becomes \fBfooscript\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). @@ -14891,6 +17492,50 @@ Used by \fBmp.add_key_binding\fP, so be careful about name collisions. .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 ouputs 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 @@ -14922,14 +17567,27 @@ the read_options function. The function will overwrite the default values with values found in the config\-file and the command\-line (in that order). .INDENT 0.0 .TP -.B \fBoptions.read_options(table [, identifier])\fP +.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\&. +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: @@ -15078,7 +17736,7 @@ value is the trailing part of the path, the directory entry. .TP .B \fButils.join_path(p1, p2)\fP Return the concatenation of the 2 paths. Tries to be clever. For example, -if \fB\(gap2\fP is an absolute path, p2 is returned without change. +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 @@ -15136,6 +17794,10 @@ This is a legacy wrapper around calling the \fBrun\fP command with 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 @@ -15185,119 +17847,8 @@ mp.register_event("file\-loaded", my_fn) .fi .UNINDENT .UNINDENT -.SS List of events -.INDENT 0.0 -.TP -.B \fBstart\-file\fP -Happens right before a new file is loaded. When you receive this, the -player is loading the file (or possibly already done with it). -.TP -.B \fBend\-file\fP -Happens after a file was unloaded. Typically, the player will load the -next file right away, or quit if this was the last file. -.sp -The event has the \fBreason\fP field, which takes one of these values: -.INDENT 7.0 -.TP -.B \fBeof\fP -The file has ended. This can (but doesn\(aqt have to) include -incomplete files or broken network connections under -circumstances. -.TP -.B \fBstop\fP -Playback was ended by a command. -.TP -.B \fBquit\fP -Playback was ended by sending the quit command. -.TP -.B \fBerror\fP -An error happened. In this case, an \fBerror\fP field is present with -the error string. -.TP -.B \fBredirect\fP -Happens with playlists and similar. Details see -\fBMPV_END_FILE_REASON_REDIRECT\fP in the C API. -.TP -.B \fBunknown\fP -Unknown. Normally doesn\(aqt happen, unless the Lua API is out of sync -with the C API. (Likewise, it could happen that your script gets -reason strings that did not exist yet at the time your script was -written.) -.UNINDENT -.TP -.B \fBfile\-loaded\fP -Happens after a file was loaded and begins playback. -.TP -.B \fBseek\fP -Happens on seeking. (This might include cases when the player seeks -internally, even without user interaction. This includes e.g. segment -changes when playing ordered chapters Matroska files.) -.TP -.B \fBplayback\-restart\fP -Start of playback after seek or after file was loaded. -.TP -.B \fBidle\fP -Idle mode is entered. This happens when playback ended, and the player was -started with \fB\-\-idle\fP or \fB\-\-force\-window\fP\&. This mode is implicitly ended -when the \fBstart\-file\fP or \fBshutdown\fP events happen. -.TP -.B \fBtick\fP -Called after a video frame was displayed. This is a hack, and you should -avoid using it. Use timers instead and maybe watch pausing/unpausing events -to avoid wasting CPU when the player is paused. -.TP -.B \fBshutdown\fP -Sent when the player quits, and the script should terminate. Normally -handled automatically. See \fI\%Details on the script initialization and lifecycle\fP\&. -.TP -.B \fBlog\-message\fP -Receives messages enabled with \fBmp.enable_messages\fP\&. The message data -is contained in the table passed as first parameter to the event handler. -The table contains, in addition to the default event fields, the following -fields: -.INDENT 7.0 -.TP -.B \fBprefix\fP -The module prefix, identifies the sender of the message. This is what -the terminal player puts in front of the message text when using the -\fB\-\-v\fP option, and is also what is used for \fB\-\-msg\-level\fP\&. -.TP -.B \fBlevel\fP -The log level as string. See \fBmsg.log\fP for possible log level names. -Note that later versions of mpv might add new levels or remove -(undocumented) existing ones. -.TP -.B \fBtext\fP -The log message. The text will end with a newline character. Sometimes -it can contain multiple lines. -.UNINDENT -.sp -Keep in mind that these messages are meant to be hints for humans. You -should not parse them, and prefix/level/text of messages might change -any time. -.TP -.B \fBget\-property\-reply\fP -Undocumented (not useful for Lua scripts). -.TP -.B \fBset\-property\-reply\fP -Undocumented (not useful for Lua scripts). -.TP -.B \fBcommand\-reply\fP -Undocumented (not useful for Lua scripts). -.TP -.B \fBclient\-message\fP -Undocumented (used internally). -.TP -.B \fBvideo\-reconfig\fP -Happens on video output or filter reconfig. -.TP -.B \fBaudio\-reconfig\fP -Happens on audio output or filter reconfig. -.UNINDENT .sp -The following events also happen, but are deprecated: \fBtracks\-changed\fP, -\fBtrack\-switched\fP, \fBpause\fP, \fBunpause\fP, \fBmetadata\-update\fP, -\fBchapter\-change\fP\&. Use \fBmp.observe_property()\fP instead. +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 @@ -15310,8 +17861,28 @@ hook). These hooks allow the player to call script functions and wait for their result (normally, the Lua scripting interface is asynchronous from the point of view of the player core). \fBpriority\fP is an arbitrary integer that allows ordering among hooks of the same kind. Using the value 50 is -recommended as neutral default value. \fBfn\fP is the function that will be -called during execution of the hook. +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 @@ -15450,6 +18021,8 @@ success, \fBfn\fP is called always a\-sync, \fBerror\fP is empty string on succe .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 @@ -15464,6 +18037,10 @@ success, \fBfn\fP is called always a\-sync, \fBerror\fP is empty string on succe .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 @@ -15494,11 +18071,14 @@ success, \fBfn\fP is called always a\-sync, \fBerror\fP is empty string on succe .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)\fP +\fBmp.add_hook(type, priority, fn(hook))\fP .sp -\fBmp.options.read_options(obj [, identifier])\fP (types: string/boolean/number) +\fBmp.options.read_options(obj [, identifier [, on_update]])\fP (types: +string/boolean/number) .SS Additional utilities .INDENT 0.0 .TP @@ -15551,6 +18131,9 @@ Note: please remove added key bindings before calling \fBexit()\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 @@ -15587,9 +18170,11 @@ to use \fBsetTimeout(fn)\fP as a one\-time idle observer. .SS CommonJS modules and \fBrequire(id)\fP .sp CommonJS Modules are a standard system where scripts can export common functions -for use by other scripts. A module is a script which adds properties (functions, -etc) to its invisible \fBexports\fP object, which another script can access by -loading it with \fBrequire(module\-id)\fP \- which returns that \fBexports\fP object. +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 @@ -15599,19 +18184,33 @@ do work. In general, this is for mpv modules and not a node.js replacement. A \fB\&.js\fP file extension is always added to \fBid\fP, e.g. \fBrequire("./foo")\fP will load the file \fB\&./foo.js\fP and return its \fBexports\fP object. .sp -An id is relative (to the script which \fBrequire\fP\(aqd it) if it starts with -\fB\&./\fP or \fB\&../\fP\&. Otherwise, it\(aqs considered a "top\-level id" (CommonJS term). +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 -Top level id is evaluated as absolute filesystem path if possible (e.g. \fB/x/y\fP -or \fB~/x\fP). Otherwise, it\(aqs searched at \fBscripts/modules.js/\fP in mpv config -dirs \- in normal config search order. E.g. \fBrequire("x")\fP is searched as file -\fBx.js\fP at those dirs, and id \fBfoo/x\fP is searched as file \fBfoo/x.js\fP\&. +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 \fB\&.init.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\&. .SS The event loop .sp The event loop poll/dispatch mpv events as long as the queue is not empty, then @@ -15769,6 +18368,9 @@ echo show\-text ${playback\-time} >\e\e.\epipe\empvsocket 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, @@ -15860,9 +18462,6 @@ Would generate this response: .sp If you don\(aqt specify a \fBrequest_id\fP, command replies will set it to 0. .sp -Commands may run asynchronously in the future, instead of blocking the socket -until a reply is sent. -.sp All commands, replies, and events are separated from each other with a line break character (\fB\en\fP). .sp @@ -15873,6 +18472,78 @@ 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 @@ -16080,6 +18751,26 @@ Is equivalent to: .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: @@ -16092,10 +18783,13 @@ including new features and bug fixes: .IP \(bu 2 The git log, which is the "real" changelog .IP \(bu 2 -The files \fBclient\-api\-changes.rst\fP and \fBinterface\-changes.rst\fP in the -\fBDOCS\fP sub directoryon the git repository, which document API and user -interface changes (the latter usually documents breaking changes only, rather -than additions). +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 @@ -16195,10 +18889,6 @@ Used to determine mpv config directory. If \fBXDG_CONFIG_HOME\fP is not set, \fB$HOME/.mpv\fP is always added to the list of config search paths with a lower priority. .TP -.B \fBXDG_CONFIG_DIRS\fP -If set, XDG\-style system configuration directories are used. Otherwise, -the UNIX convention (\fBPREFIX/etc/mpv/\fP) is used. -.TP .B \fBMPV_HOME\fP Directory where mpv looks for user settings. Overrides \fBHOME\fP, and mpv will try to load the config file as \fB$MPV_HOME/mpv.conf\fP\&. @@ -16209,7 +18899,11 @@ 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 \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 @@ -16343,6 +19037,33 @@ mpv system\-wide settings (depends on \fB\-\-prefix\fP passed to configure \- mp 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 @@ -16368,9 +19089,11 @@ fonts, which is more memory\-efficient. .TP .B \fB~/.config/mpv/scripts/\fP All files in this directory are loaded as if they were passed to the -\fB\-\-script\fP option. They are loaded in alphabetical order, and sub\-directories -and files with no \fB\&.lua\fP extension are ignored. The \fB\-\-load\-scripts=no\fP -option disables loading these files. +\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 @@ -16392,12 +19115,6 @@ for details. Other files in this directory are specific to the corresponding scripts as well, and the mpv core doesn\(aqt touch them. .UNINDENT -.sp -Note that the environment variables \fB$XDG_CONFIG_HOME\fP and \fB$MPV_HOME\fP can -override the standard directory \fB~/.config/mpv/\fP\&. -.sp -Also, the old config location at \fB~/.mpv/\fP is still read, and if the XDG -variant does not exist, will still be preferred. .SH FILES ON WINDOWS .sp On win32 (if compiled with MinGW, but not Cygwin), the default config file