From a4bc654323d38c109bb2d6a7a2419b7c3f3b84e6 Mon Sep 17 00:00:00 2001 From: Danny Rawlins Date: Sat, 27 Feb 2021 23:37:40 +1100 Subject: mpv: bump for API change on libplacebo --- mpv/.signature | 7 +- mpv/Pkgfile | 5 +- mpv/mpv-libplacebo-3.104.0-api-change.patch | 84 + mpv/mpv.1 | 4627 +++++++++++++++++++++------ 4 files changed, 3764 insertions(+), 959 deletions(-) create mode 100644 mpv/mpv-libplacebo-3.104.0-api-change.patch (limited to 'mpv') 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.gz 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 +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 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/\fP (selects .mpls playlist); \fB\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=\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=\fP Display the subtitle stream specified by \fB\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=\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=\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=\fP +.B \fB\-\-hr\-seek=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\fP +.B \fB\-\-ytdl\-format=\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==[,=[,...]]\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=\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=\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=\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 -Disable any framedropping. +Disable any frame dropping. Not recommended, for testing only. .TP .B 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 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 -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=\fP +.B \fB\-\-override\-display\-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=\fP +Deprecated alias for \fB\-\-override\-display\-fps\fP\&. +.TP .B \fB\-\-hwdec=\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\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=\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=\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=\fP, \fB\-\-video\-scale\-y=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\fP +Log dropped lines with warning log level, instead of verbose (default: no). +Helpful for testing. +.TP +.B \fB\-\-sub\-filter\-regex\-enable=\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=\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=\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=\fP +.B \fB\-\-ontop\-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=\fP +.B \fB\-\-geometry=<[W[xH]][+\-x+\-y][/WS]>\fP, \fB\-\-geometry=\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=\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=\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=\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=\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=\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=\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=\fP See \fB\-\-demuxer\-mkv\-subtitle\-preroll\fP\&. .TP +.B \fB\-\-demuxer\-mkv\-probe\-start\-time=\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=\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=\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=\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=\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=\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=\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=\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=\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=\fP -(OS X only) -Enable/disable Apple Remote support. Enabled by default (except for libmpv). +.B \fB\-\-input\-ipc\-client=fd://\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=\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=\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=\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=\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=\fP Software scaler chroma vertical shifting. See \fB\-\-sws\-scaler\fP\&. .TP +.B \fB\-\-sws\-bitexact=\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=\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=\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=\fP +Zimg luma scaler to use (default: lanczos). +.TP +.B \fB\-\-zimg\-scaler\-param\-a=\fP, \fB\-\-zimg\-scaler\-param\-b=\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=\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=\fP +Dithering (default: random). +.TP +.B \fB\-\-zimg\-threads=\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=\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=\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=\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=\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=\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\fP options +accept suffixes such as \fBKiB\fP and \fBMiB\fP\&. +.TP +.B \fB\-\-vd\-queue\-enable=, \-\-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=\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\fP options +accept suffixes such as \fBKiB\fP and \fBMiB\fP\&. +.TP +.B \fB\-\-vd\-queue\-max\-samples=\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=\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=\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=\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=\fP +.B \fB\-\-rtsp\-transport=\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=\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=\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=\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=\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=\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=\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=\fP +Set the client app id for Wayland\-based video output methods. By default, "mpv" +is used. .TP .B \fB\-\-wayland\-disable\-vsync=\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=\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=\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=\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=\fP +.B \fB\-\-glsl\-shader=\fP, \fB\-\-glsl\-shaders=\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=\fP +.B \fB\-\-macos\-force\-dedicated\-gpu=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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=\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/\fP -to set the host name (with \fB\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=\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=\fP, \fB\-\-vo\-sixel\-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=\fP, \fB\-\-vo\-sixel\-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=\fP, \fB\-\-vo\-sixel\-top=\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=\fP, \fB\-\-vo\-sixel\-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=\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=\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=\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=\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=\fP +Mute audio if the playback speed is below \fB\fP\&. (default: 0.25) +.TP +.B \fBmax\-speed=\fP +Mute audio if the playback speed is above \fB\fP +and \fB != 0\fP\&. (default: 4.0) +.TP +.B \fBsearch\-interval=\fP +Length in milliseconds to search for best overlap position. (default: 30) +.TP +.B \fBwindow\-size=\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\fP, \fB\fP +If not 0, perform conversion to the given size. Ignored if +\fBconvert=yes\fP is not set. +.TP .B \fB\fP, \fB\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\fP +Force a specific scaler backend, if applicable. This is a debug option +and could go away any time. +.TP +.B \fB\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=\fP, \fBh=\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=\fP -Appends the options given as arguments to the options list. +.B \fB\-\-ofopts\-add=