mpv —— 媒体播放器

Copyright:

GPLv3

概要

mpv [options] [file|URL|PLAYLIST|-]

mpv [options] files

描述

mpv 是一个基于MPlayer和mplayer2的媒体播放器。它支持多种视频文件格式、音视频编解码器和字幕类型。特殊的输入URL类型可用于读取硬盘文件以外的各种输入源。根据不同的平台，支持多种不同的音视频输出方式。

可以在本手册的末尾找到快速入门的使用示例。

交互控制

mpv有一个完全可设置的、命令驱动的控制层，允许你使用键盘、鼠标或远程控制mpv（不支持LIRC —— 将遥控器设置为输入设备代替）。

参见 --input- 选项获取自定义的方法。

下方的列表不一定完整。参见 etc/input.conf 获取默认绑定的列表。用户的 input.conf 文件和Lua脚本可以定义额外的按键绑定。

参见 --input-test 获取按键的交互绑定详情，以及内置脚本 统计数据 以获取按键绑定列表（包括输出到终端的内容）。

键盘控制

左 和 右

向前/向后跳转5秒。Shift+箭头 进行1秒的精确跳转（参见 --hr-seek ）

上 和 下

向后/向前跳转1分。Shift+箭头 进行5秒的精确跳转（参见 --hr-seek ）

Ctrl+左/右

跳转到上一个/下一个字幕。受限且可能并非总是有效；参见 sub-seek 命令

Ctrl+Shift+左/右

调节字幕延迟，以便现在显示下一个或上一个字幕。这对同步字幕音频特别有用

[ 和 ]

减少/增加当前播放速度的10%

{ 和 }

减半/加倍当前的播放速度

退格键

重置播放速度到正常

Shift+退格

撤销上一次的跳转。这只在播放列表条目没有变动的情况下起效。第二次点击它将回到原来的位置。详见 revert-seek 命令

Shift+Ctrl+退格

标记当前位置。它将被 Shift+BACKSPACE 作为还原的位置（一旦跳转回来，标记将被重置）。可以用它来在文件中跳转，然后返回到离开时的准确位置

< 和 >

在播放列表中后退/前进

回车键

在播放列表中前进

p 或 空格键

暂停（再次按下取消暂停）

.

步进。按一次将暂停，每连续按一次将播放一帧，然后再进入暂停模式

,

步退。按一次将暂停，每连续按一次将反向播放一帧，然后再进入暂停模式

q

停止播放并退出

Q

类似 q ，但存储当前的播放位置。尽可能之后播放同样的文件将恢复在旧的播放位置。参见 恢复播放

/ 和 *

减少/增加音量

9 和 0

减少/增加音量

m

静音

_

循环可用的视频轨

#

循环可用的音轨

E

循环可用的版本 edition

f

切换全屏（另参见 --fs ）

ESC

退出全屏模式

T

切换置顶（另参见 --ontop ）

w 和 W

减少/增加平移和扫描范围。目前 e 键与 W 键的作用相同但不赞成使用

o （或 P ）

在OSD上显示进度条、已过时间和总持续时间

O

切换OSD状态，一般时间显示 和 “播放时间/总持续时间”显示

v

切换字幕的可见性

j 和 J

循环可用的字幕

z 和 Z

调整字幕延迟 +/-0.1秒。目前 x 键与 Z 键的作用相同但不赞成使用

l

设定/清除A-B循环点。详见 ab-loop 命令

L

切换无限循环

Ctrl++ 和 Ctrl+-

调整音频延迟（A/V同步）+/-0.1秒

Shift+g 和 Shift+f

调整字幕字体大小，幅度为+/-10%

u

在应用仅 --sub-ass-* 相关项的覆盖（默认值）到SSA/ASS字幕和几乎完全覆盖它们的普通字幕样式之间切换。详见 --sub-ass-override

V

切换字幕的VSFilter长宽比兼容模式。详见 --sub-ass-vsfilter-aspect-compat

r 和 R

上/下移动字幕。 t 键的作用与 R 目前相同，但不鼓励使用。

s

截一次屏

S

截一次屏，无字幕（是否有效取决于视频输出驱动的支持）

Ctrl+s

截一次屏，按照窗口显示的内容（有字幕、OSD和缩放后的视频）

PGUP 和 PGDWN

跳转到上一章/下一章的开头。在大多数情况下，“上一章”实际是指当前章节的开头；参见 --chapter-seek-threshold

Shift+PGUP 和 Shift+PGDWN

向后或向前跳转10分钟（曾经被映射到不需要Shift的PGUP/PGDWN）

b

激活/注销去色带

d

循环去隔行扫描器

A

循环长宽比覆盖

Ctrl+h

切换硬件视频解码开/关

Alt+上/下/左/右

移动视频的矩形（平移）

Alt++/-

可改变视频缩放

Alt+退格

重置平移/缩放的设定

F8

显示播放列表和其中文件的当前位置

F9

显示音频和字幕流的列表

i 和 I

显示/切换一个显示关于当前播放文件的统计数据的覆盖层，比如编解码器、帧率、丢帧数等。详见 统计数据

DEL

在 永不/自动（鼠标移动）/始终 之间循环OSC的可见性

`

显示控制台（ESC会再次关闭它，参见 控制台 ）

（以下按键只有在使用支持对应的调整的视频输出时才有效。）

1 和 2

调整对比度

3 和 4

调整亮度

5 和 6

调整伽玛

7 和 8

调整饱和度

Alt+0 （macOS用 Command+0 ）

调整视频窗口到原来的一半

Alt+1 （macOS用 Command+1 ）

调整视频窗口到原来的大小

Alt+2 （macOS用 Command+2 ）

调整视频窗口到原来的两倍

Command+f （macOS独占）

切换全屏（另见 --fs ）

（以下按键绑定可在控制台中打开一个选择器，通过键入所需项目的部分内容和/或通过按键绑定导航，从项目列表中进行选择： Down 和 Ctrl+n 向下滚动， Up 和 Ctrl+p 向上滚动， PGDWN 和 Ctrl+f 向下滚动一页， PGUP 和 Ctrl+b 向上滚动一页。）

g-p

选择一个播放列表条目

g-s

选择一个字幕轨

g-S

选择一个次字幕轨

g-a

选择一个音轨

g-v

选择一个视频轨

g-t

选择一个任何类型的轨道

g-c

选择一个章节

g-l

选择一个要搜索的字幕行。目前，这要求在 PATH 中有 ffmpeg，或在 Windows 下与 mpv 位于同一文件夹中

g-d

选择一个音频设备

g-b

选择一个已定义的按键输入绑定

g-r

显示所有属性的值

（如果键盘上有多媒体键，那么以下按键是有效的。）

PAUSE

暂停

STOP

停止播放并退出

PREVIOUS 和 NEXT

向后/向前跳转1分钟

ZOOMIN 和 ZOOMOUT

改变视频变焦

如果没有看到一些更老的按键绑定，查看mpv git仓库中的 etc/restore-old-bindings.conf

鼠标控制

左键双击

切换全屏的开/关

右键

切换暂停的开/关

前进/后退键

跳至播放列表中的下/上一个条目

滚轮向上/下

减少/增加音量

滚轮向左/右

向前/向后跳转10秒

Ctrl+滚轮向上/下

改变视频缩放

上下文菜单

警告

此功能是实验性的。它可能无法适用于所有VO。将来可能会实现基于 libass 的回退版。

上下文菜单是用户交互时（鼠标右键等）在视频窗口上弹出的菜单。

要使用这一功能，需要在 menu-data 属性中填充菜单定义的数据，并添加键绑定以执行 context-menu 命令，这可以通过用户脚本完成。

使用方法

以 - 开头的命令行参数被解释为选项，其它都是文件名或URLs。除了 flag 标志选项（或包括 yes 的可选择性的选项），所有选项都需要一个参数，其形式为 --option=value

一个例外是孤立的 - （没有其它任何东西），这意味着媒体数据将从stdin读取。另外， -- （没有其它任何东西）将使播放器把所有后面的参数解释为文件名，即使它们以 - 开头。（要播放一个名为 - 的文件，你需要使用 ./- 。）

每个 flag 选项都有一个 no-flag 对应的选项，例如， --fs 选项的对立是 --no-fs 。 --fs=yes 与 --fs 相同， --fs=no 与 --no-fs 相同。

如果一个选项被标记为 （XXX独占） ，它只能与 XXX 选项结合使用，或者在 XXX 已被编译进mpv的情况下使用。

遗留的选项语法

--option=value 的语法没有被严格执行，被替代的遗留语法 -option value 和 -option=value 也可以工作。这主要是为了和MPlayer的兼容性。应该避免使用这些。它们的语义可能在未来的任何时候产生变动。

例如，被替代的语法将看待选项后面的参数是一个文件名。 mpv -fs no 将尝试播放一个名为 no 的文件，因为 --fs 是一个无需参数的标志选项。如果一个选项改变了，并它的参数成为可选的项目，那么使用替代语法的命令行就会中断。

在mpv0.31.0之前，一个选项是以 -- 还是单个 - 开头没有区别。较新的mpv版本严格要求你在 = 之后传递选项的值。例如，以前 mpv --log-file f.txt 会向 f.txt 写入日志，但现在这个命令行失效了，因为 --log-file 期待一个选项的值，而 f.txt 只是被认为是一个待播放的普通文件（如 mpv f.txt ）。

未来的计划是， -option value 将不再有效，带有单个 - 的选项与 -- 选项的行为相同。

转义空格和其它特殊字符

请记住，shell会对传递给mpv的参数进行部分分析和处理。例如，可能需要引用或转义选项和文件名：

mpv "filename with spaces.mkv" --title="window title"

如果涉及到子选项解析器，情况会变得更复杂。子选项解析器将一些选项放入单个字符串中，并一次将它们传递给一个组件，而不是在命令行的层级上使用多个选项。

子选项解析器可以用 " 和 [...] 来引用字符串。此外，还有一种特殊形式的带 %n% 的引用，如下所述。

例如，假设假想的的 foo 滤镜能接受多个选项：

mpv test.mkv --vf=foo:option1=value1:option2:option3=value3,bar

这将把 option1 和 option3 传递给 foo 滤镜， option2 作为标志（隐含 option2=yes ），并在其后添加一个 bar 滤镜。如果一个选项包含空格或如 , 或 : 这样的字符，需要引用它们：

mpv '--vf=foo:option1="option value with spaces",bar'

Shell实际上可能从传递到命令行的字符串中剥离一些引号，所以这个例子对字符串进行了两次引用，确保mpv接收到引号 " 。

[...] 形式的引用包括了在 [ 和 ] 之间的一切东西。它对那些不解析参数中间的这些字符的shells很有用（比如bash）。这些引号是对称的（从mpv0.9.0开始）： [ 和 ] 嵌套，引号终止于字符串中没有匹配 [ 的最后一个 ] 。（例如， [a[b]c] 的结果是 a[b]c 。）

固定长度的引用语法是给外部脚本和程序使用的。

它以 % 开头，格式如下:

%n%string_of_length_n

示例

mpv '--vf=foo:option1=%11%quoted text' test.avi

或者在一个脚本中：

mpv --vf=foo:option1=%`expr length "$NAME"`%"$NAME" test.avi

注意：在适用于JSON-IPC的地方， %n% 是在解码JSON数据后的UTF-8字节的长度。

传递给client API的子选项也要进行转义处理。使用 mpv_set_option_string() 就像在命令行中传递 --name=data 一样（但是没有shell对字符串的处理）。一些选项支持以更结构化的方式传递数值，而不是标志字符串，可以避免子选项解析的混乱。例如， --vf 支持 MPV_FORMAT_NODE ，它允许你以表和数组的嵌套数据结构传递子选项。

路径

在向mpv传递任意的路径和文件名时必须注意一些问题。例如，以 - 开头的路径将被解释为选项。同样，如果一个路径包含序列 :// ，前面的字符串可能被解释为协议的前缀，尽管 :// 可以是合法的UNIX路径的一部分。为了避免任意路径的问题，你应该确保传递给mpv的绝对路径以 / 开始，而相对路径以 ./ 开始。

不赞成使用伪协议 file:// ，因为它涉及到奇怪的URL非转义规则。

名称 - 本身被解释为stdin，并将导致mpv禁用控制台控制。（这使它适合播放pipe到stdin的数据。）

特殊参数 -- 可以用来阻止mpv将后面的参数解释为选项。

当使用client API时，你应该严格避免使用 mpv_command_string 来调用 loadfile 命令，而应该选择例如 mpv_command 来避免文件名转义的需要。

对于传递给子选项的路径，由于需要转义特殊字符，情况会更复杂。为了解决这个问题，可以用固定长度的语法来包装路径，例如 %n%string_of_length_n （见上文）。

一些mpv选项解释以 ~ 开头的路径。目前，前缀 ~~home/ 扩展到mpv设置目录（通常是 ~/.config/mpv/ ）。 ~/ 扩展到用户的主目录。（尾部的 / 总是需要的。）当前可以识别以下路径：

名称	意义
~~/	如果子路径存在于mpv的任何设置目录中，则返回现有文件/目录的路径。否则这相当于 ~~home/ 。注意，如果使用了 –no-config ， ~~/foobar 将解析为 foobar ，这可能是意想不到的情况
~/	用户的主目录根（类似于shell， $HOME ）
~~home/	mpv的设置目录（例如 ~/.config/mpv/ ）
~~global/	全局的设置路径，如果存在（win32不可用）
~~osxbundle/	macOS bundle的资源路径（macOS独占）
~~desktop/	桌面的路径（win32 macOS）
~~exe_dir/	win32独占：包含exe的目录路径（用于设置文件； $MPV_HOME 会覆盖它）
~~cache/	应用程序的缓存路径 ( ~/.cache/mpv/ )。在某些平台，这将和 ~~home/ 一致
~~state/	应用程序状态数据的路径 ( ~/.local/state/mpv/ ) 。在某些平台，这将和 ~~home/ 一致
~~old_home/	请勿使用

单文件选项

当播放多个文件时，在命令行中给出的任何选项通常会影响所有文件。例如:

mpv --a file1.mkv --b file2.mkv --c

文件	激活的选项
file1.mkv	--a --b --c
file2.mkv	--a --b --c

（这与MPlayer和mplayer2不同。）

另外，如果任何选项在运行时被更改（通过输入命令），它们在播放新文件时不会被重置。

有时，按每个文件变更选项是很有用的。这可以通过添加特殊的单文件标记 --{ 和 --} 来实现。（注意，在某些shells上必须转义这些标记。）示例:

mpv --a file1.mkv --b --\{ --c file2.mkv --d file3.mkv --e --\} file4.mkv --f

文件	激活的选项
file1.mkv	--a --b --f
file2.mkv	--a --b --f --c --d --e
file3.mkv	--a --b --f --c --d --e
file4.mkv	--a --b --f

此外，任何在运行时改变的单文件选项都会在当前文件停止播放时被重置。如果在播放 file2.mkv 时改变了 --c 选项，那么在推进到 file3.mkv 时就会被重置。这只影响到单文件选项。选项 --a 在这里永远不会被重置。

列表选项

一些能存储选项值列表的选项可以有动作后缀。例如， --display-tags 选项接收一个用 , 分隔标签的列表，但该选项也允许用 --display-tags-append 附加一个单一的标签，标签名称可以例如包含一个字面意义的 , 而不需要进行转义。

字符串列表和路径列表选项

字符串列表用 , 分隔。字符串不被选项系统本身所解析或解释。然而，大多数路径或文件列表选项使用 : （Unix）或 ; （Windows）作为分隔符，而不是 ,

它们支持以下操作：

后缀	含义
-set	设置一个项目列表（使用列表分隔符，用反斜杠转义）
-append	追加单个项目（不解释转义）
-add	追加1个或多个项目（与 -set 的语法相同）
-pre	前置1个或多个项目（与 -set 的语法相同）
-clr	清除选项（移除所有项目）
-remove	如果存在，则删除指定的项目（不解释转义）
-toggle	追加一个项目，如果它已存在列表中，则移除（无转义）

-append 是一种追加单个项目的简单方式，不需要转义参数（在shell层级可能仍需要转义）。

按键/值列表选项

一个按键/值列表是一个按键/值字符串的对应列表。在编程语言中，这种类型的数据结构通常被称为map或字典。顺序通常并不重要，尽管在某些情况下顺序可能很重要。

它们支持以下操作：

后缀	含义
-set	设置一个项目列表（使用 , 作为分隔符）
-append	追加单个项目（需要转义按键，不用转义值）
-add	追加1个或多个项目（与 -set 的语法相同）
-remove	如果存在，通过按键删除指定的项目（不解释转义）

按键在列表中是唯一的。如果设置了一个已经存在的按键，在追加新的值之前，现有的按键会被移除。

如果想要在不解释转义或 , 的情况下传递一个值，推荐使用 -append 变体。当使用libmpv时，最好使用 MPV_FORMAT_NODE_MAP ；当使用脚本后端或JSON IPC时，使用合适的结构化数据类型。

在mpv0.33之前， : 也被 -set 识别为分隔符。

对象设置列表选项

这对一些选项是一个非常复杂的选项类型，例如 --af 和 --vf 选项。它们通常需要复杂的转义。详见 视频滤镜 。

它们支持以下操作：

后缀	含义
-set	设置一个对象列表（使用 , 作为分隔符）
-append	追加单个对象
-add	追加1个或多个对象（与 -set 的语法相同）
-pre	前置1个或多个对象（与 -set 的语法相同）
-clr	清除选项（移除所有对象）
-remove	如果存在，则删除指定的对象
-toggle	追加一个对象，如果它已存在列表中，则移除
-help	伪操作，在终端输出一个帮助文本

通用

没有后缀的操作通常就是 -set

尽管有些操作允许指定多个项目，但除了 -set 之外，强烈不赞成使用这种已过时的操作。有可能像 -add 和 -pre 这样的操作会像 -append 一样工作，只接受一个未转义的项目（所以分隔符 , 不会被解析，而是作为值的一部分被传递）。

一些选项（如 --sub-file, --audio-file, --glsl-shader ）是带有 -append 动作的适当选项的别名。例如， --sub-file 是 --sub-files-append 的别名。

这种类型的选项可以在运行时使用 change-list 命令进行修改，该命令将后缀（不含 - ）作为单独的操作参数。

设置文件

定位和语法

可以把所有的选项放在设置文件中，每次mpv运行的时候都会读取。系统级的设置文件 “mpv.conf” 在你的设置目录中（例如 /etc/mpv 或 /usr/local/etc/mpv ），用户级的是 ~/.config/mpv/mpv.conf 。相关细节和具体平台的情况（特别是Windows的路径），参见 文件 部分。

用户级的选项覆盖系统级的选项，命令行给出的选项会覆盖前两种选项。设置文件的语法是 option=value 。在 # 之后的所有内容都被认为是注释。没有值就能工作的选项可以通过设置为 yes 来启用，禁用则是 no ，如果该值被省略，则暗示 yes 。甚至子选项也可以用这种方式指定。

设置文件示例

# 不允许新窗口超出屏幕
autofit-larger=100%x100%
# 如果可用就启用硬件解码，这个示例暗示了 "=yes"
hwdec
# 空格不需要被转义
osd-playing-msg=File: ${filename}

转义特殊字符

这与命令行选项的处理方式相同。配置项可以使用双引号（ " , ' ）引用，也可以使用之前提到的固定长度语法（ %n% ）引用。这就好像将引用字符串的确切内容作为命令行选项传递一样。在这个级别上，不解释C风格的转义字符，尽管某些选项会手动执行这个操作（这是一种混乱，可能会在某个时候改变）。这里不涉及shell，因此只需要引用选项值以转义值的任意位置的 # ，或 " 或 ' 或 % ，以及前导符与尾随的空格。

将命令行选项放入设置文件中

几乎所有的命令行选项都可以放到设置文件中。此处有个小指南：

选项	设置文件条目
--flag	flag
-opt val	opt=val
--opt=val	opt=val
-opt "has spaces"	opt=has spaces

特定文件的设置文件

也可以编写针对指定文件的设置文件。如果想要给一个名为 “video.avi” 的文件写一个设置文件，那么创建一个名为 “video.avi.conf” 的文件，并在其中加入特定的选项，然后把它放在 ~/.config/mpv/ 。你也可以把该设置文件和待播放的文件放在同一目录下。这两种方式都需要设置 --use-filedir-conf 选项（在命令行或全局设置文件中）。如果在同一目录下发现了特定文件的设置文件，就不会从 ~/.config/mpv 中加载特定文件的设置文件。此外， --use-filedir-conf 选项可以启用特定目录的设置文件。对于这一点，mpv首先尝试从播放的文件的同一目录加载mpv.conf，然后再尝试加载任何特定文件的设置文件。

配置预设

为了便于处理不同的设置，可以在设置文件中定义配置预设。一套配置预设以方括号中的名称作为开头，例如： [my-profile] 。所有后面的选项将属于该配置预设的部分。它的描述（由 --profile=help 显示）可以用选项 profile-desc 来定义。要结束这个配置预设，可以开始另一个，或者使用名为 default 的配置预设来继续使用常规选项。

可以使用 --profile=help 列出所有配置预设，使用 --show-profile=<name> （用配置预设的名称替换 <name> ）显示配置预设的内容。可以使用 --profile=<name> 选项在启动时应用配置预设，或者在运行时使用 apply-profile <name> 命令。

带有配置预设的mpv设置文件的示例

# 一般的顶层选项
fullscreen=yes

# 一个可以用 --profile=big-cache 启用的配置预设
[big-cache]
cache=yes
demuxer-max-bytes=512MiB
demuxer-readahead-secs=20

[network]
profile-desc="profile for content over network"
force-window=immediate
# 你也可以包含其它 profile
profile=big-cache

[reduce-judder]
video-sync=display-resample
interpolation=yes

# 再次使用这个 profile 来扩展它
[network]
demuxer-max-back-bytes=512MiB
# 引入一个内置的 profile
profile=fast

运行时的配置预设

配置预设可以在运行时用 apply-profile 命令来设置。由于这个操作是“破坏性的”（配置预设中的每一个条目都被简单地设置为一个选项，覆盖了之前的值），无法再次启用和禁用对应的配置预设。

作为部分补救措施，有一种方法可以使配置预设在用配置预设的值覆盖之前保存旧的选项值，然后在之后使用 apply-profile <profile-name> restore 来恢复旧值。

这可以通过选项 profile-restore 来启用，它需要以下的其中一个选项：

default

无操作，不还原任何操作（默认）

copy

当应用一个配置预设时，在从配置预设中设置它们之前，将所有该配置预设对应的选项的旧值复制到一个备份中。当需要还原时，这些对应的选项被重置为被备份的旧值。

每个配置预设都有自己的备份值列表。如果备份已经存在（例如，如果 apply-profile name 被连续调用了一次以上），现有的备份就不会被改变。还原操作将删除该备份。

重要的是要了解，还原并不是“撤销”对应选项的设置，而只是简单的复制旧的选项值。例如考虑 vf-add ，向 vf 追加一个条目。这个机制将简单地复制整个 vf 列表，并且在还原时 _不_ 执行 vf-add 的逆操作（即 vf-remove ）。

注意，如果一个配置预设包含递归的配置预设（通过 profile 选项），这些递归的配置预设中的选项会被视为该配置预设的一部分。在创建或使用备份时，被引入的配置预设的备份列表不会被使用。还原一个配置预设不会还原被引入的配置预设，只还原被引入的配置预设的选项（就像它们是该主配置预设的一部分）。

copy-equal

类似于 copy ，但只有当选项的值与配置预设的有效设置的值相同时才会还原。这尝试处理用户在交互式改变选项后，不希望其被重置的情况。

示例

[something]
profile-restore=copy-equal
vf-add=rotate=PI/2  # 旋转90度

然后运行这些命令将导致如注释所描述的行为：

set vf vflip
apply-profile something
vf add hflip
apply-profile something
# vf == vflip,rotate=PI/2,hflip,rotate=PI/2
apply-profile something restore
# vf == vflip

附带条件的自动配置预设

设置了 profile-cond 选项的配置预设在符合相关条件的情况下会自动应用（除非自动配置预设被禁用）。该选项需要一个字符串，它被解析为Lua表达式。如果表达式被评估为true，则应用配置预设，如果表达式出错或评估为false，则不应用配置预设。这个Lua代码的执行没有被沙盒化。

条件表达式中的任何变量都可以引入属性。如果一个标识符还没有被Lua或mpv定义，它将被解释为属性。例如， pause 将返回当前的暂停状态。你不能用 - 来引入属性，因为那表示减法，但是如果变量名包含任何 _ 字符，它们就会变成 - 。例如， playback_time 将返回属性 playback-time

一个鲁棒性更好的访问属性的方法是使用 p.property_name 或 get("property-name", default_value) 。如果引入一个同名的新标识符，自动变量到属性的magic就会失效（例如，如果添加一个名为 pause() 的函数， pause 将返回一个函数值，而不是 pause 属性的值）。

注意，如果一个属性不可用，它将返回 nil ，如果在表达式中使用，可能会引起错误。这些错误会被记录在verbose模式中，并且表达式会被认为是false。

每当一个配置预设的附带条件所引入的属性发生变化时，条件会被重新评估。如果条件的返回值从false或error变成了true，就会应用该配置预设。

一旦条件从true变为false，这个机制就会尝试“不应用”配置预设。如果想要使用这个，需要为该配置预设设置 profile-restore 。另一种可能性是创建另一个具有相反条件的配置预设来撤销其它配置预设。

可以使用递归的配置预设。但是不赞成在一个有条件的配置预设中引入其它的附带条件的配置预设，因为这可能导致棘手和反直觉的行为。

示例

只是让高清视频看起来滑稽：

[something]
profile-desc=HD video sucks
profile-cond=width >= 1280
hue=-50

让路径中含有 “youtube” 或 “youtu.be” 的视频变的更加明亮 ：

[youtube]
profile-cond=path:find('youtu%.?be')
gamma=20

如果你想在条件再次变为false时还原配置预设，你可以设置 profile-restore ：

[something]
profile-desc=Mess up video when entering fullscreen
profile-cond=fullscreen
profile-restore=copy
vf-add=rotate=PI/2  # 旋转90度

这是在进入全屏时将 rotate 滤镜追加到视频滤镜链中。当离开全屏时， vf 选项被设置为进入全屏前的值。请注意，这也会删除用户在全屏模式下添加的任何其它滤镜。避免这种情况比较棘手，例如可以通过添加第二个具有相反条件和操作的配置预设来解决：

[something]
profile-cond=fullscreen
vf-add=@rot:rotate=PI/2

[something-inv]
profile-cond=not fullscreen
vf-remove=@rot

警告

每当涉及到的属性发生变化时，条件就会被再次评估。例如，如果你的条件使用 p.playback_time ，条件大约在视频的每一帧中都要重新评估。这可能很慢。

该功能由一个内部的Lua脚本管理。条件在这个脚本中作为Lua代码执行。它的环境至少包含以下内容：

(function environment table)

每个Lua函数都有一个环境表。这用于标识符的访问。它没有命名的Lua符号；它是隐含的。

环境对mpv属性进行 “magic” 访问。如果一个标识符还没有在 _G 中定义，它将检索同名的mpv属性。在读取属性之前，名称中任何出现的 _ 都会被替换成 - 。返回的值是由 mp.get_property_native(name) 检索的。在内部，使用了一个属性值的缓存，通过观察属性来更新，所以不能观察的属性将永远停留在初始值。

如果你想访问名称中实际包含 _ 的属性，请使用 get() （它不执行transliteration）。

在内部，环境表有一个 __index 元方法设置，它执行访问逻辑。

p

一个类似于环境表的 “magic” 表。与后者不同，它不喜欢访问定义在 _G 中的变量 - 它总是访问属性。

get(name [, def])

读取一个属性并返回其值。如果属性值为 nil （例如，如果属性不存在），将返回 def

这在表面上与 mp.get_property_native(name) 类似。一个重要的区别是，它访问了属性缓存，并启用了变化检测逻辑（这对自动配置预设的动态运行时的行为至关重要）。另外，它不会返回一个错误值作为第二个返回值。

上面提到的 “magic” 表使用这个函数作为后端。它不执行 _ 的transliteration

此外，与空白mpv Lua脚本中的环境相同。例如， math 被定义了，可以访问Lua的标准math库。

警告

这个功能可能会被无限期地改变。你可能被迫在mpv更新时调整你的配置预设

遗留的自动配置预设

有些配置预设是使用遗留的机制自动加载的。下面的例子证明了这一点：

加载自动配置预设

[extension.mkv]
profile-desc="profile for .mkv files"
vf=vflip

配置预设的名称遵循 type.name 的模式，其中type可以是 protocol 表示正在使用的输入/输出协议（见 --list-protocols ）， extension 表示当前播放文件的路径扩展名（ 不是 文件的格式）。

这个功能非常有限，被认为是软性过时的。使用附带条件的配置预设。

从其它程序或脚本中使用mpv

从其它程序或脚本中使用mpv，有三种选择：

1. 把它当作UNIX的进程调用。如果你这样做的话， 不要解析终端的输出 。终端输出适用于人，并可能随时发生变化。另外，终端的行为本身也可能随时改变。兼容性无法得到保证。

   如果你传递了 --terminal=no ，你的代码也应该起效。不要尝试通过向mpv的stdin发送终端控制代码来模拟用户输入。如果你需要交互式控制，推荐使用 --input-ipc-server 。这可以让你通过unix域套接字（或Windows的命名管道）访问 JSON IPC

   根据你的想做的事情，传递 --no-config 或 --config-dir 可能是一个好方案，以避免与用于CLI播放的常规mpv用户设置发生冲突。

   使用 --input-ipc-server 也适用于像远程控制等的目的（然而，IPC协议自身并不 “安全”，它也不打算变得安全）。

2. 使用libmpv。当mpv被用作一个完全不同的应用程序的播放后端时，一般推荐使用这种方法。提供的C语言API与CLI机制以及脚本API非常接近。

   注意，即使libmpv具有不同的默认值，它也可以被设置成完全像CLI播放器一样去工作（除了命令行解析是不可用的）。

   参见 EMBEDDING INTO OTHER PROGRAMS (LIBMPV)

3. 作为一个用户脚本（ LUA SCRIPTING, JAVASCRIPT, `C PLUGINS`_ ）。当目标是 “增强” CLI播放器时，推荐使用这种方式。脚本可以访问mpv的整个 client API。

   这是为播放器创建第三方扩展的标准方式。

所有这些都可以访问 client API，它是由播放器内核提供的各种机制的总和，正如这里所记录的： 选项, 输入命令列表, 属性, 事件列表 （另参见 C API）, Hooks.

截屏

当前播放的文件的截图可以使用 ‘screenshot’ 输入模式命令来拍摄，它默认与 s 键绑定。命名为 mpv-shotNNNN.jpg 的文件将被保存在工作目录中，使用第一个可用的数字编号 —— 没有文件会被覆盖。在伪GUI模式下，屏幕截图将被保存在其它地方。参见 伪GUI模式

一张屏幕截图通常会包含在视频滤镜链末端的未缩放的视频内容和字幕。默认情况下， S 拍摄的屏幕截图不带字幕，而 s 包含字幕。

与MPlayer不同，视频滤镜 screenshot 是不需要的。在mpv中从来不需要该滤镜，并且已被移除。

终端状态行

在播放过程中，mpv在终端显示播放状态。它看起来像这样：

AV: 00:03:12 / 00:24:25 (13%) A-V: -0.000

状态行可以被 --term-status-msg 选项覆盖。

以下是可以在状态行显示的东西的列表。还列出了可用于手动获取相同信息的输入属性。

• AV: 或 V: （仅视频） 或 A: （仅音频）

• 当前的时间位置，按 HH:MM:SS 的格式（ playback-time 属性）

• 总的文件持续时间（如果未知，则不存在）（ duration 属性）

• 播放速度，例如： x2.0 。只有在速度不正常时才可见。这是用户请求的速度，而不是实际速度（通常它们应该是一样的，除非播放太慢）（ speed 属性）

• 播放百分比，例如： (13%) 。文件已经播放了多少。通常由播放位置和持续时间计算而来，但如果这些方法不可用，可以退回到其它方法（比如字节位置）（ percent-pos 属性）

• 音频/视频同步为 A-V:  0.000 。这是音频和视频的时间差。通常它应该是0或接近0。如果它在增长，表明可能有播放问题（ avsync 属性）

• 总的A/V同步变化，例如： ct: -0.417 。通常是不可见的。如果有音频“丢失”，或者没有足够的帧可以丢弃，就会显示。通常这表明有问题（ total-avsync-change 属性）

• 编码状态在 {...} ，只在编码模式下显示

• 显示同步状态。如果显示同步是激活的（ display-sync-active 属性），会显示 DS: 2.500/13 ，其中第一个数字是每个视频帧的平均垂直同步数（例如，在60Hz屏幕上播放24Hz视频时为2.5），如果比率没有取整，或者有错误的帧（ vsync-ratio ），可能会出现抖动，第二个数字是花费较长时间估计的垂直同步数（ vo-delayed-frame-count 属性）。后者是启发式的，因为一般而言不可能肯定地确定

• 丢帧数，例如： Dropped: 4 。只有当计数不为0时才会显示。如果视频帧率高于显示器的帧率，或者视频渲染太慢，就会增加。也可能在 “hiccups” 和视频帧不能及时显示时增加。（ frame-drop-count 属性。）如果解码器丢帧，解码器丢帧的数量也会附加到显示上，例如： Dropped: 4/34 。只有当解码器丢帧的功能被启用时，即``–framedrop`` 选项，才会发生这种情况（ decoder-frame-drop-count 属性）

• 缓存状态，例如： Cache:  2s/134KB 。如果流媒体缓存被启用，则可见。第一个值显示在解复用器中缓冲的视频量（秒），第二个值显示缓冲量的估计大小，以千字节为单位（ demuxer-cache-duration 和 demuxer-cache-state 属性）

低延迟播放

mpv为常规的视频播放进行优化，意味着它实际上试图缓冲尽可能多有意义的数据。这将增加延迟。只有通过特意禁用增加延迟的功能，才有可能减少延迟。

内置的 low-latency 配置预设尝试应用一些可以减少延迟的选项。可以使用 --profile=low-latency 来应用它们。可以用 --show-profile=low-latency 来列出其内容（有些选项很模糊，可能每个mpv版本都有变化）。

请注意，有些选项会降低播放质量。

大多数延迟实际上是由不便利的计时行为引起的。可以用 --untimed 来禁用它，但它很可能会中断，除非流中没有音频，并且输入以恒定的速率向播放器提供数据。

另一个常见的问题是MJPEG流。这些流没有正确的帧率信号。使用 --untimed 或 --correct-pts=no --container-fps-override=60 可能有所帮助。

对于直播流，由于暂停数据流、稍低的播放速率，或因“缓冲”而暂停，数据可能会累积。如果解复用器缓存被启用，这些可以被手动跳过。实验性的 drop-buffers 命令可以用来丢弃任何已缓冲的数据，尽管它非常具有破坏性。

在某些情况下，手动调整TCP缓冲区的大小等可以帮助减少延迟。

可以尝试的其它选项：

• --opengl-glfinish=yes 可以减少图形驱动中的缓冲区

• --opengl-swapinterval=0 同上

• --vo=xv 同上

• 无音频的情况下 --framedrop=no --speed=1.01 可能对直播信号源有帮助（结果可能是混合的）

恢复播放

mpv能够存储当前播放的文件的播放位置，并在下次播放该文件时从那里恢复。这是通过命令 quit-watch-later （默认与 Shift+Q 绑定）和 write-watch-later-config ，以及选项 --save-position-on-quit 实现的。

始终用绑定到 quit-watch-later 的按键退出和使用 --save-position-on-quit 的区别是，即使mpv是用绑定键以外的方法关闭的，后者都会保存播放位置，例如点击窗口标题栏上的关闭按钮。但是，如果 mpv 突然终止来不及保存，那么播放位置就不会被记住。例如，在未关闭 mpv 的情况下关闭系统。

mpv也保存除播放位置以外的其它选项，当它们在播放开始后已被修改，例如音量和已选的音轨/字幕轨，并在下次播放文件时恢复它们的值。可以用 --watch-later-options 选项进行设置哪些选项会被保存。

当播放多个播放列表的条目时，mpv会检查其中一个是否有相关的恢复设置文件，如果找到了，就从该文件重新开始播放。例如，如果你在一个节目的第5集上使用 quit-watch-later ，然后播放所有的剧集，mpv会自动从第5集开始恢复播放。

设置这一功能的更多选项被列在 稍后观看 中。

协议

http://..., https://, …

支持许多网络协议，但必须始终指定协议前缀。mpv不会尝试猜测一个文件名是否实际上是一个网络地址。一个协议前缀始终是必要的。

注意，并非所有的前缀都在这里有记录。未记录的前缀要么是已记录的协议的别名，要么只是重定向到FFmpeg中的实现和记录的协议。

data: 受支持，但需要采用 data:// 的格式。这样做是为了避免与文件名产生歧义。你也可以用 lavf:// 或 ffmpeg:// 作为前缀。

ytdl://...

默认情况下，youtube-dl hook脚本只看http(s)的URLs。用 ytdl:// 作为URL的前缀，可以让脚本始终处理该URL。这也可以用来调用youtube-dl的特殊功能，如按ID播放视频或调用搜索功能。

请记住，你不能用它来传递youtube-dl的命令行选项，你必须使用 --ytdl-raw-options 来代替。

-

从stdin播放数据。

smb://PATH

播放来自Samba共享的路径（需要FFmpeg支持）。

bd://[title][/device] --bluray-device=PATH

播放蓝光光盘。从libbluray1.0.1开始，你可以通过将ISO文件传递给 --bluray-device 来读取。

title 可以是 longest 或 first （选择默认的播放列表）； mpls/<number> （选择 <number>.mpls 播放列表）； <number> （选择具有相同索引的播放列表）。mpv在加载时将列出可用的播放列表。

bluray:// 是一个别名。

dvd://[title][/device] --dvd-device=PATH

播放一个DVD。不支持DVD菜单。如果没有给出标题，将自动选择最长的标题。如果没有 --dvd-device ，它可能会尝试打开一个实际的光驱，如果有的话，并为操作系统实现。

dvdnav:// 是 dvd:// 的旧别名，其作用完全相同。

dvb://[cardnumber@]channel --dvbin-...

通过DVB的数字电视（Linux独占）。

mf://[@listfile|filemask|glob|printf-format] --mf-...

将一系列图像当作视频播放。

如果 URL 路径以 @ 开头，它将被解释为包含一系列图像路径的文件路径，这些图像路径由换行符分隔。如果 URL 路径包含 , ，则会被解析为由 , 分隔的图像路径列表。如果 URL 路径不包含 % ，且在 POSIX 平台上，则被解析为 glob，如果未指定 * ，则自动添加。否则，将解析 printf 序列 %[.][NUM]d （其中 NUM 为一位、两位或三位小数）和 %% 。例如， mf://image-%d.jpg 可以播放 image-1.jpg` 、 image-2.jpg 和 image-10.jpg 等文件，前提是文件之间没有大的间隔。

cdda://[device] --cdrom-device=PATH --cdda-...

播放CD。

lavf://...

访问任何FFmpeg的libavformat协议。基本上，这把 // 后面的字符串直接传递给了libavformat。

av://type:options

这是为使用libavdevice输入而准备的。 type 是libavdevice解复用器的名称， options 是传递给demuxer的（伪）文件名。

示例

mpv av://v4l2:/dev/video0 --profile=low-latency --untimed

这将以几乎最低的延迟播放来自第一个v4l输入的视频。这是一个很好的替代被删除的 tv:// 输入的方法。使用 --untimed 是一个hack，可以立即输出捕获的帧，而不是遵循输入的帧速率（将来可能有更好的方法来处理这个问题）。

avdevice:// 是一个别名。

file://PATH

一个作为URL的本地路径。在一些特殊的使用情况下可能会有用。注意， PATH 本身应该以第三个 / 开头，来使路径成为绝对路径。

appending://PATH

播放一个本地文件，但假设它被附加到了。例如，这对目前正在下载到硬盘的文件很有用。这将阻止播放，只有在超时约2秒后没有新数据被追加时才停止播放。

使用这个方法还是不太好，因为没有办法检测一个文件是否真的被追加了，或者是否还在写入。如果你想播放一些程序的输出，可以考虑使用一个pipe（ something | mpv - ）。如果真的必须是硬盘上的文件，用tail来让它永远等待，例如： tail -f -c +0 file.mkv | mpv -

fd://123

从给定的文件描述符（例如123）读取数据。这类似于通过 - 将数据pipe到stdin，但可以使用任意的文件描述符。当stream layer“打开” 文件描述符时，mpv可能会修改一些文件描述符的属性。

fdclose://123

类似 fd:// ，但文件描述符在使用后会被关闭。当使用这个时，你需要确保同一个fd URL只被使用一次。

edl://[edl specification as in edl-mpv.rst]

将多个文件的部分内容拼接在一起并播放。

slice://start[-end]@URL

读取一个流的片段。

start 和 end 代表一个字节范围，接受后缀，如 KiB 和 MiB 。 end 是可选的。

如果 end 以 + 开头，则被视为从 start 开始的偏移。

只适用于可跳转的流。

示例:

mpv slice://1g-2g@cap.ts

在跳转1GiB后开始从cap.ts读取，然后读取达到2GiB或文件结束。

mpv slice://1g-+2g@cap.ts

在跳转1GiB后开始从cap.ts读取，然后读取达到3GiB或文件结束。

mpv slice://100m@appending://cap.ts

在跳转100MB后开始从cap.ts读取，然后读取直到文件结束。

null://

模拟一个空文件。如果打开写入，它将丢弃所有数据。如果使用这个协议， null 解复用器将特意传递autoprobing（然而对于空文件不会自动调用）。

memory://data

使用 data 部分作为源数据。

hex://data

类似 memory://，但字符串被解释为hexdump。

伪GUI模式

mpv没有官方的GUI，除了OSC（ 屏显式控制器 ），它不是一个完整的GUI，也不打算成为GUI。然而，为了弥补缺乏预期的GUI行为，在某些情况下mpv会在启动时改变一些设置，使其行为略微更像GUI模式。

目前这只发生在以下情况中：

• 如果在Linux上使用 mpv.desktop 文件启动（例如，从菜单或桌面环境提供的文件关联启动）

• 如果在Windows上从explorer.exe启动（技术上讲，如果它是在Windows上启动的，并且所有的stdout/stderr/stdin句柄都未设置）

• 在macOS上从bundle中启动

• 如果你手动在命令行中使用 --player-operation-mode=pseudo-gui

该模式应用内置的配置预设 builtin-pseudo-gui 中的选项，但仅当这些选项没有在用户的设置文件或命令行中设置，这是与使用 --profile=builtin-pseudo-gui 的主要区别。

目前该配置预设的定义如下：

[builtin-pseudo-gui]
terminal=no
force-window=yes
idle=once
screenshot-directory=~~desktop/

pseudo-gui profile的存在是为了兼容。 pseudo-gui profile中的选项是无条件应用的。此外，该profile确保启用伪GUI模式，因此 --profile=pseudo-gui 可以像在旧版mpv中一样工作。

[pseudo-gui]
player-operation-mode=pseudo-gui

警告

目前，你可以在设置文件中以正常的方式扩展 pseudo-gui profile。这已经过时d。在未来的mpv版本中，该行为可能会变更，不要应用你的额外设置，和/或使用一个不同的配置预设名称。

选项

轨道选择

--alang=<languagecode[,languagecode,...]>

以 IETF 语言标记的形式，指定要使用的音频语言优先级列表。等效 ISO 639-1 双字母代码和 ISO 639-2 三字母代码。将使用列表中与文件中音轨语言匹配的第一个标签。匹配子标记较多的音轨将优先于匹配子标记较少的音轨。另见 --aid

这是一个字符串列表选项。详见 列表选项

示例

• mpv dvd://1 --alang=hu,en 在DVD上选择匈牙利语的轨道，如不可获取该语言，则回到英语

• mpv --alang=jpn example.mkv 播放带有日语音频的Matroska文件

--slang=<languagecode[,languagecode,...]>

近似 --alang，但用于字幕轨。

这是一个字符串列表选项。详见 列表选项

示例

• mpv dvd://1 --slang=hu,en 选择DVD上选择匈牙利文字幕轨，如不可获取该语言，则回退到英文

• mpv --slang=jpn example.mkv 播放带有日文字幕的Matroska文件

• mpv --slang=pt-BR example.mkv 播放带有巴西葡萄牙语字幕（如果可用）的Matroska文件，否则播放任何葡萄牙语字幕

--vlang=<...>

相当于 --alang 和 --slang ，用于视频轨道。

这是一个字符串列表选项。详见 列表选项

--aid=<ID|auto|no>

选择音轨。 auto 选择默认轨， no 禁用音频。另参见 --alang 。mpv通常在开始播放文件时在终端输出可用的音轨。

--audio 是 --aid 的别名。

--aid=no 或 --audio=no 禁用音频播放（后一种变体在client API中不起作用）。

备注

轨道选择的选项（ --aid 但也包括 --sid 和其它选项）有时可能会出现奇怪的行为。并且，这种行为往往随着每个mpv版本的发布而改变。

轨道选择的属性将返回播放之外的选项值（符合预期），但在播放过程中，受影响的轨道选择会被返回。例如，在 --aid=auto 的情况下， aid 属性会在播放初始化后突然返回 2 （假设文件至少有2个音轨，而且第二个是默认轨）。

在mpv0.32.0（和一些之前的版本）中，如果传递的轨道值不存在对应的实际轨道（例如 --aid=2 但只有1个音轨）， aid 属性会返回 no 。然而，如果在播放过程中增加了另一个音轨，再尝试将 aid 属性设置为 2 ，什么也不会发生，因为 aid 选项的值仍然是 2 ，而写入相同的值是没有效果的。

在mpv0.33.0中，这个行为被改变。现在如果轨道选择的选项尝试选择一个不存在的轨道，它在播放初始化时会被重置为 auto 。如果轨道实际存在，但未能初始化，也会这样做。其后果是，与mpv0.33.0之前的版本不同，用户的轨道选择的参数在某些情况下被影响了。

另外，从mpv0.33.0开始，尝试通过数字来选择一个轨道将严格特执行选择这个轨道。在此变化前，尝试选择一个不存在的轨道，会在播放初始化时回退到选择默认轨道。新的行为更具一致性。

在运行时设置一个轨道选择的属性，然后播放一个新文件，如果新文件的轨道列表的fingerprint不同，可能会重置轨道选择为默认值。

注意上述所有的微妙组合：例如， mpv --aid=2 file_with_2_audio_tracks.mkv file_with_1_audio_track.mkv 会先播放第一个文件的正确轨道，而后第二个文件不播放音频。如果你再返回第一个文件，它的第一个音轨将被播放，而第二个文件则播放音频。如果再执行同样的操作，但不是使用 --aid=2 ，而是在文件播放时运行 set aid 2 ，那么换到第二个文件将播放它的音轨。这是因为运行时的轨道选择会启用启发式fingerprint。

最有可能的是这不会结束。

--sid=<ID|auto|no>

显示由 <ID> 指定的字幕流。 auto 选择默认的字幕， no 禁用字幕。

--sub 是 --sid 的别名。

--sid=no 或 --sub=no 禁用字幕解码（后一种变体在client API中不起作用）。

--vid=<ID|auto|no>

选择视频频道。 auto 选择默认的轨道， no 禁用视频。

--video 是 --vid 的别名。

--vid=no 或 --video=no 禁用视频播放（后一种变体在client API中不起作用）。

如果视频被禁用，mpv将尝试下载音频，只有当媒体是用youtube-dl串流时，因为这样可以节省带宽。这是通过在ytdl_hook.lua脚本中将ytdl_format设置为 “bestaudio/best” 来实现的。

--edition=<ID|auto>

（Matroska文件独占）指定要使用的edition（章节集），其中0是第一个。如果设置为 auto （默认），mpv将选择被注明为默认的第一个edition，如果没有注明的默认，则选择定义中的第一个edition。

--track-auto-selection=<yes|no>

启用默认轨道的自动选择（默认： yes）。启用它将使播放器根据 --aid, --alang 和其它项目来选择流。如果禁用，则不选择任何轨道。此外，如果没有选择轨道，播放器将不会退出，而是等待（这种等待模式类似暂停，但实际没有设置pause选项）。

这对 --lavfi-complex 很有用：你可以在该模式下开始播放，然后在运行时通过设置graph滤镜来设置选择轨道。注意，如果 --lavfi-complex 在播放开始前被设置，被引入的轨道始终会被选中。

--subs-with-matching-audio=<yes|forced|no>

自动选择字幕轨时，即使所选音频流与你首选的字幕语言相匹配，也会选择该字幕音轨（默认： yes）。如果该选项设置为 no ，则无论 --slang 或 subs-fallback 如何设置，mpv 都不会自动选择与音频语言匹配的字幕轨。如果设置为 forced ，则只会选择强制字幕。

--subs-match-os-language=<yes|no>

在自动选择字幕轨道时，如果音频流的语言与操作系统的语言匹配（在合适的条件下，默认轨道或适当的强制轨道），则选择匹配操作系统语言的轨道。请注意，如果设置了 --slang，将完全忽略此选项（默认： yes）。

--subs-fallback=<yes|default|no>

当自动选择字幕轨道时，如果没有轨道符合你的优先语言，则选择一个完整的轨道，即使它不符合你的优先字幕语言（默认： default）。将此设置为 default 表示只有标记为 default 的流才会被选中。

--subs-fallback-forced=<yes|no|always>

在自动选择字幕轨道时，默认值为 yes ，如果字幕语言与音频语言匹配并且匹配您的首选语言列表，将首选使用强制字幕轨道。特殊值 always 将只选择强制字幕轨道，永远不会选择非强制轨道。相反， no 将永远不选择强制字幕轨道。

播放控制

--start=<relative time>

跳转到给定的时间位置。

时间的一般格式是 [+|-][[hh:]mm:]ss[.ms] 。如果时间的前缀是 - ，则该时间被认为是相对于文件末尾的位置（解复用其/文件的标记）。 + 通常会被忽略（但是请见下文）。

以下是可识别的可替代的时间规格：

pp% 跳转到百分比位置 pp (0-100)

#c 跳转到章节编号 c (章节从1开始)

none 重置任何之前设置的选项（对libmpv有用）

如果给出 --rebase-start-time=no ，那么在时间前加上 + ，使时间是相对于文件的起始时间。没有前缀的时间戳被认为是绝对时间，例如，应该跳转到文件中包含该时间戳的帧。作为一个错误，但也却是一个隐藏功能，在 + 或 - 前放1个或多个空格，总是会将该时间解释为绝对时间，这可以用来跳转到负的时间戳（最多用于调试）。

示例

--start=+56, --start=00:56

跳转到开始时间+56秒

--start=-56, --start=-00:56

跳转到结束时间-56秒

--start=01:10:00

跳转到1小时10分

--start=50%

跳转到文件的中间部分

--start=30 --end=40

跳转到30秒，播放10秒，然后退出

--start=-3:20 --length=10

跳转到文件结束前的3分20秒，播放10秒，然后退出

--start='#2' --end='#4'

播放第2章和第3章，然后退出

--end=<relative time>

在给定的时间停止。如果时间是相对于 --start 的，则使用 --length 。有效的选项值和示例，参见 --start

--length=<relative time>

在相对于开始时间的一个给定时间后停止。有效的选项值和示例，参见 --start

如果同时提供了 --end 和 --length ，播放将在到达两个结束点中的其中一个时停止。

隐性注意点：如果设置了 --rebase-start-time=no ，并且指定的时间不是“绝对”时间，正如 --start 选项描述中定义的那样，则不能生效。

--rebase-start-time=<yes|no>

是否将文件的开始时间移动到 00:00:00 （默认： yes）。这对于以随机时间戳开始的文件来说不那么突兀，比如传输流。另一方面，如果有时间戳重置，产生的行为可能相当奇怪。出于这个原因，如果你真的对真实的时间戳感兴趣，可以用 no 来禁用这种行为。

--speed=<0.01-100>

按参数给定的系数减慢或加快播放速度。

如果使用了 --audio-pitch-correction （默认： yes），以高于正常速度播放会自动插入 scaletempo2 音频滤镜。

--pause

以暂停状态启动播放器。

--shuffle

以随机顺序播放文件。

--playlist-start=<auto|index>

设置从内部播放列表的哪个文件开始播放。索引是一个整数，0表示第一个文件。值 auto 表示选择要播放的条目是留给播放恢复机制的（默认）。如果一个具有给定索引的条目不存在，行为是未指定的，在未来的mpv版本中可能会改变。如果播放列表包含更多的播放列表，也是同样的情况（不要期待任何合理的行为）。不过，把播放列表文件传递给mpv应该可以使这个选项起作用。例如， mpv playlist.m3u --playlist-start=123 将按预期工作，只要 playlist.m3u 不链接到其它的播放列表。

值 no 是 auto 的过时的别名。

--playlist=<filename>

根据一个播放列表文件播放文件。支持一些常见的格式。如果没有检测到格式，它将被视为一系列文件，用换行符分隔。可能需要这个选项来加载纯文本文件作为播放列表。注意，不支持XML播放列表格式。

这个选项强制 --demuxer=playlist 来解析播放列表文件。一些播放列表格式，特别是CUE和光盘格式，需要使用不同的解复用器，使用该选项将无法工作。不使用这个选项仍然可以直接播放它们。

你可以不带这个选项而直接播放播放列表。在mpv0.31.0版本之前，这个选项禁用了任何可能存在的安全机制，但从0.31.0开始，它使用与直接播放播放列表文件相同的安全机制。如果信任播放列表文件，可以用 --load-unsafe-playlists 禁用任何安全检查。因为播放列表可以加载其它播放列表的条目，考虑只对播放列表本身而不是其条目，应用这个选项，使用这样类似的方法：

mpv --{ --playlist=filename --load-unsafe-playlists --}

警告

旧版本的mpv通过 --playlist 播放播放列表文件的方式对恶意构建的文件而言是不安全的。这样的文件可能引发有害行为。在0.31.0之前的所有mpv和所有MPlayer版本都是如此，但不幸的是，这个事实在早期没有被很好的记录，有些人甚至误导性的推荐使用 --playlist 和不值得信任的文件来源。如果不确定你的mpv版本至少是0.31.0，请不要用 --playlist 链接随机的互联网来源或不信任的文件。

特别是，播放列表可以包含使用除本地文件以外的协议的条目，例如像 avdevice:// 这样的特殊协议（它本质上就不安全）。

--chapter-merge-threshold=<number>

合并几乎连续的有序章节部分的阈值，以毫秒为单位（默认： 100）。一些带有有序章节的Matroska文件有不准确的章节结束时间戳，导致一个章节的结束和下一个章节的开始之间有一个小间隙，但它们应该是匹配的。如果一个播放部分的结束与下一个部分的开始之间的距离小于给定的阈值，那么就在章节的变更期间继续正常播放视频，而不是做一个跳转。

--chapter-seek-threshold=<seconds>

以秒为单位，从章节开始到上一章的距离，在该长度内，后退一章将进入前一章（默认： 5.0）。超过这个阈值，向前跳转章节将前往当前章节的开头。一个负的值意味着始终返回到前一章。

--hr-seek=<no|absolute|yes|default>

选择何时使用不限于关键帧的精确跳转。这种跳转需要解码视频从上一个关键帧到目标位置，因此可能需要一些时间，取决于解码性能。对于某些视频格式，精确跳转被禁用。这个选项选择了用于跳转的默认选择；在定义按键绑定和输入命令时，可以明确地覆盖该默认值。

no:

从不使用精确跳转

absolute:

如果在文件中寻找一个绝对位置，如章节跳转，使用精确跳转，但对相对位置，例如方向键的默认行为，则不使用

default:

类似 absolute ，但在仅有音频的情况下启用。具体的行为视具体情况而定，可能会随着新版本的发布而改变（默认）

yes:

尽可能使用精确跳转

always:

与 yes 相同（为了兼容性）

--hr-seek-demuxer-offset=<seconds>

这个选项的存在是为了解决由于某些文件格式的解复用器的错误或限制而导致的精确跳转失败（正如 --hr-seek 里的描述）。有些解复用器不能在给定的目标位置之前寻找关键帧，而只能跳转一个靠后的位置。这个选项的值将从被给定的解复用器的时间戳中减去。因此，如果把这个选项设置为1.5，并尝试做精确跳转到60秒，解复用器会被告知要跳转到时间58.5，这有希望能减少它错误的跳转到比60秒晚的某个时间的机会。设置这个选项的坏处是，精确跳转的速度会更慢，因为目标的靠前位置和真正的目标之间的视频可能被解复用器不必要的解码。

--hr-seek-framedrop=<yes|no>

允许视频解码器在跳转过程中丢帧，如果这些帧在跳转的目标之前。如果启用这个功能，精确跳转会加快，但如果使用修改时间戳或添加新帧的视频滤镜，会导致精确跳转略过目标帧。例如，当启用去隔行扫描时，这可能会破坏帧的backstepping。

默认： yes

--index=<mode>

控制如何在文件中跳转。请注意，如果文件中缺少索引，默认情况下将在运行中建立，所以不需要改变。但它可能对一些损坏的文件有帮助。

default:

如果文件存在索引就使用它，如果缺失就建立索引

recreate:

不读取或使用该文件的索引

备注

这个选项只有在底层媒体支持跳转的情况下才有效（例如不使用stdin、pipe等）。

--load-unsafe-playlists

从播放列表中加载被认为不安全的URL（默认： no）。这包括特殊协议和任何不指向普通文件的东西。另一方面，本地文件和HTTP链接始终被认为是安全的。

此外，如果当设置该选项后时加载了一个播放列表，添加的播放列表条目不会被标记为来自网络或潜在的不安全位置（相反，其行为就像是，播放列表条目好像被直接提供给mpv命令行或 loadfile 命令）。

--access-references=<yes|no>

遵循被打开的文件中的任何引入（默认： yes）。如果文件被自动扫描（如缩略图生成），禁用这个功能是有帮助的。例如，如果缩略图扫描器遇到一个包含网络URL的播放列表文件，而扫描器不应该打开这些文件，启用这个选项就可以阻止这个动作。该选项还可以禁用有序章节，mov参考文件，加载压缩档，以及一些其它的功能。

在旧版的FFmpeg中，这在某些情况下将无法工作。一些FFmpeg解复用器可能不遵循这个选项。

这个选项并不防止加载成对的字幕文件等。使用 --autoload-files=no 来阻止这种情况。

如果你打开的是非文件（例如，使用 dvd://directory 会加载指定目录下的一大堆文件），该选项并不总是有效。如果文件名不是以 / 开头，就用 ./ 作为前缀，可以避免这种情况。

--loop-playlist=<N|inf|force|no>, --loop-playlist

循环播放 N 次。值为 1 时播放一次（默认）， 2 播放两次，等等。 inf 表示永远。 no 与 1 相同，禁止循环播放。如果在命令行指定了多个文件，整个播放列表将被循环播放。 --loop-playlist 与 --loop-playlist=inf 相同。

force 模式与 inf 相似，但不会跳过已被标记为失败的播放列表条目。这表示播放器可能会浪费CPU时间，尝试循环播放一个不存在的文件。但在非常糟糕的网络条件下，它可能对播放网络广播有用。

--loop-file=<N|inf|no>, --loop=<N|inf|no>

循环一个文件N次。 inf 表示永远， no 表示正常播放。为了兼容性， --loop-file 和 --loop-file=yes 也被接受，并且与 --loop-file=inf 相同。

与 --loop-playlist 的不同是，它不循环播放列表，而只是文件本身。如果播放列表只包含一个文件，这两个选项的区别是，这个选项在循环中执行跳转，而不是重新加载文件。

备注

--loop-file 计算的是使播放器跳转到文件开头的次数，而不是完全播完的次数。这表示 --loop-file=1 最终会播放该文件两次。 --loop-playlist 则不同，它计算完全播完的次数。

--loop 是这个选项的别名。

--ab-loop-a=<time>, --ab-loop-b=<time>

设置循环点。如果播放中通过了 b 的时间戳，它将跳转到 a 的时间戳。跳转超过 b 点时不再循环（这是有意设计的）。

如果 a 在 b 之后，行为正如按正确顺序给出的点一样，播放器将在通过 a 后跳转到 b 。这与旧版的行为不同，旧版的行为是禁止循环的（并且是一个错误，在文件的末端循环跳转回到 a ）。

如果任一选项被设置为 no （或未设置），循环被禁用。这与旧版的行为不同，以前未设置的 a 表示文件的开头，而未设置的 b 表示文件的结尾。

循环点可以在运行时通过相应的属性来调整。另参见 ab-loop 命令。

--ab-loop-count=<N|inf>

只运行A-B循环N次，然后忽略A-B循环点（默认： inf）。每完成一次循环迭代，该选项将递减1（除非它被设置为 inf 或0）。 inf 表示循环会永远进行下去。如果这个选项被设置为0，A-B循环将被忽略，甚至 ab-loop 命令也不会再次启用循环（如果两个循环点都已被设置，但 ab-loop-count 为0，该命令将在OSD信息中显示 (disabled) ）。

--ordered-chapters=<yes|no>

默认： yes。禁用对Matroska有序章节的支持。mpv不会加载或搜索其它文件的视频片段，也会忽略为主文件指定的任何章节顺序。

--ordered-chapters-files=<playlist-file>

启用对 Matroska 有序章节的支持。mpv 将加载和搜索其他文件中的视频片段，也会查看主文件中指定的任何章节顺序（默认： yes）。

对于加载不在本地文件系统上的有序章节文件，或如果被引入的文件在不同的目录中，这很有用。

注意：播放列表可以是一个简单的文本文件，内含用换行符分隔的文件名。

--chapters-file=<filename>

从这个文件加载章节，而不使用主文件中的章节元数据。

这可以接受一个媒体文件（如mkv）或甚至一个如ffmetadata的伪格式，并使用其章节来替换当前文件的章节。这不能直接与OGM或XML章节一起工作。

--sstep=<sec>

在每一帧后跳过<sec>秒。

备注

如果没有 --hr-seek ，跳过的时间将扣在关键帧上。

--stop-playback-on-init-failure=<yes|no>

如果音频或视频初始化失败，停止播放（默认： no）。如果使用 no ，在其中一个失败时，将继续以纯视频或纯音频模式播放。这不影响纯音频或纯视频文件的播放。

--play-direction=<forward|+|backward|->

控制播放方向（默认： forward）。设置 backward 将尝试以反向播放文件，伴随着播放时间递减。如果在播放开始时设置，播放将从文件的末端开始。如果在播放过程中改变它，将发出一个hr-seek来改变方向。

+ 和 - 是 forward 和 backward 的别名。

这个选项的其它描述与 backward 模式有关。

备注

向前播放是非常脆弱的。它不一定能工作，比正向播放慢得多，而且会破坏某些其它功能。它的工作效果如何主要取决于正在播放的文件。一般来说，只有在众星捧月的情况下，它才能显示出良好的效果（或结果良好）。

mpv，以及大多数媒体格式，被设计成只用于向后播放。向前播放被固定在mpv顶层，并尝试做出中等程度的努力来使向前播放工作。根据你的使用情况决定，其它工具可能工作得更好。

向前播放并不完全是一个一流的功能。在实现上做了一些取舍，这些取舍对向前播放不利，但反过来又不会对正常播放造成不利影响。为了降低复杂性，各种可能的优化都没有实现。通常情况下，一个媒体播放器是高度管线化的（未来的数据是在独立的线程中准备的，所以当下一阶段需要它时，它是实时可用的），但向前播放基本上会在各种随机的点上使管线停滞。

例如，对于只有i帧编码的向前播放是微不足道的，围绕它们建立的工具可能会有效地利用它们（考虑视频编辑器或相片查看器）。在这种情况下mpv不是有效率的，因为它使用其通用的向后播放的算法，在这上面没有特别优化。

如果你只是想快速倒退视频并只显示“关键帧”，那么就使用向前播放，按住左箭头键（在默认设置的CLI上会发送许多小的相对跳转的命令）。

该实现主要由3部分组成：

• 向前解复用。这依赖于解复用器的缓存，所以解复用器的缓存应该（或必须，没有测试）被启用，它的大小会影响性能。如果缓存过小或过大，可能会导致二次运行时的行为。

• 向前解码。使用的解码器库（libavcodec）不支持这个。它是通过提前输入几比特的数据，将结果放入队列，反向返回队列数据给视频输出驱动，然后在较早的位置重新开始来模拟的。这可能需要缓存超大量的解码数据，也会完全破坏管线。

• 向前输出。这相对简单，因为解码器按需要的顺序返回帧。然而，这可能会引起各种问题，因为滤镜会观察到音频和视频向前移动。

已知问题：

• 它很脆弱。如果有任何东西不工作，可能会出现随机的无用的行为。在简单的情况下，播放器将只是播放无意义的东西和伪影。在其它情况下，它可能会卡住或加热CPU（不过，内存使用量远远超过用户设置的限制将是一个错误）。

• 性能和资源的使用情况并不理想。这在一定程度上是普通媒体格式向前播放所固有的，这在一定程度上是由于实现的抉择和权衡。

• 这极其依赖于良好的解复用器行为。尽管向前解复用不需要特殊的解复用器支持，但需要解复用器可靠地执行跳转，能满足一些关于packet元数据的特殊需求，并具有确定性的行为。

• 准确地从结尾开始播放可能会也可能不会工作，这取决于跳转行为和文件持续时间检测。

• 一些容器格式、音频和视频编码由于其行为而不被支持。没有列表，而且播放器通常不检测它们。某些直播流（包括电视捕获）可能会表现出特别的问题，以及一些有损的音频编码。已知h264 intra-refresh由于libavcodec的问题而无法工作。WAV和其他一些raw音频格式往往有问题 —— 有一些处理它们的hacks，可能有效也可能无效。

• 不支持字幕的向前解复用。字幕显示仍然适用于一些外部文本字幕格式（这些是完全读取入内存的，只需要向前显示）。缓存在字幕渲染器中的文本字幕也有机会被正确显示。

• 一些处理播放损坏的或难以处理的文件的功能将不能完全工作（如时间戳修正）。

• 如果通过向前播放执行解复用器的低级跳转（例如，跳转实际的解复用器，而不仅仅是在解复用器的缓存内），创建的跳转范围可能无法连接，因为没有达到足够的重叠度。

• 尝试硬件视频解码可能会耗尽所有的GPU内存，然后崩溃一两样东西。或者会失败，因为 --hwdec-extra-frames 会肯定的被设置的太低。

• 流记录被破坏了。如果只在缓存区域内倒退播放， --stream-record 可能会继续工作。

• 相对跳转可能表现得很奇怪。小规模的向前跳转（短的时间段，即 seek -1 ）可能不会真正的正确跳转，音频将保持静音一段时间。建议使用hr-seek，它应该不会有这些问题。

• 有些事情就是很奇怪。例如，虽然跳转命令以预期的方式操纵播放时间（只要它们能正常工作），但framestep命令是换位的。backstepping将开销巨大的性能代价来向后移动1帧。

调试：

• 移除所有已设置的 --vf / --af 滤镜。禁用硬件解码。禁用像SPDIF直通这样的功能。

• 增加 --video-reversal-buffer 可能有助于逆转队列的溢出，这可能发生在高比特率视频或大GOP的视频。硬件解码大多会忽略这一点，你需要增加 --hwdec-extra-frames ，而不是（直到得到没有错误记录的播放）。

• 解复用器缓存对向前解码至关重要。确保设置 --cache=yes 。缓存的大小可能很重要。如果它太小，队列溢出将被记录，向前播放不能继续，或者它执行了太多的低级跳转。如果太大，实现的权衡可能会导致一般的性能问题。使用 --demuxer-max-bytes 可能会增加解复用层可以排队进行反向解复用的packets的数量（基本上是相当于解复用层的 --video-reversal-buffer ）。

• 设置 --vd-queue-enable=yes 可以使播放更加流畅（一旦成功）。

• --demuxer-backward-playback-step 也是影响可进行多少次跳转的因素，以及向前解复用是否会因队列溢出而中断。如果它设置得太高，即使缓存足够大，backstep操作也需要一直搜索更多的packets。

• 设置 --demuxer-cache-wait 可能有助于将整个文件缓存到解复用器缓存中。设置 --demuxer-max-bytes 到一个大的尺寸，以确保它能读取整个缓存； --demuxer-max-back-bytes 也应该设置到一个大的尺寸，以防止尝试裁剪缓存的行为。

• 如果在即使音频输出驱动不劣质的情况下，可以听到音频瑕疵，增加 --audio-backward-overlap 可能有帮助。

--video-reversal-buffer=<bytesize>, --audio-reversal-buffer=<bytesize>

用于向前解码。向前解码是按step向前进行解码，然后反转解码器的输出。这些选项控制了可以缓冲的最大字节数的近似值。它的主要用途是避免无限制的资源使用；在正常的向前播放过程中，它不应该达到极限，如果它达到了，它就会丢帧并报告。

如果在倒放过程中得到反转队列溢出的错误，请使用这个选项。增加尺寸，直到警告消失。通常，视频缓冲区会首先溢出，尤其是高分辨率的视频。

如果使用视频硬解码，这就没有效果。视频帧的大小将不包括引入的GPU和驱动内存。一些硬件解码器也可能受到 --hwdec-extra-frames 的限制。

队列大小需要多大，完全取决于媒体的编码方式。音频通常需要一个非常小的缓冲区，而视频可能需要过大的缓冲区。

（技术上讲，这允许最后一帧超过限制。另外，这还没有考虑到其它缓冲帧，例如解码器内部或视频输出。）

这完全不影响解复用器缓存的行为。

默认值和取值范围，参见 --list-options 。 <bytesize> 选项接受后缀，如 KiB 和 MiB 。

--video-backward-overlap=<auto|number>, --audio-backward-overlap=<auto|number>

用于向前解码的重叠关键帧范围的数量（默认： auto）（“关键帧”应理解为mpv/ffmpeg的特定含义）。向前解码是通过小step向前解码来进行的。一些编码不能从任何packet重新开始解码（即使它被标记为跳转点），这在向前解码中变得很明显（理论上这也是跳转的问题，但 --hr-seek-demuxer-offset 可以解决跳转的问题）。特别是，基于MDCT的音频编码受到影响。

解决办法是每次给解码器送入一个前一个的packet，然后discard输出。这个选项控制要送多少个packet。 auto 的选择目前对视频来说硬编码为0，对有损音频使用1，对无损音频使用0。对于一些特定的有损音频编码，这被设置为2。

--video-backward-overlap 有可能处理intra-refresh视频，这取决于具体条件。可能还需要使用 --vd-lavc-show-all 选项。

--video-backward-batch=<number>, --audio-backward-batch=<number>

向前解码时一次解码的关键帧范围的数量（默认：视频为1，音频为10）。是另一个没有意义的调整参数，没有人应该使用。这应该只影响性能。理论上，为音频设置一个高于1的数字将减少开销，因为减少了频繁的backstep操作，以及减少了因解码重叠帧而产生的冗余解码工作（参见 --audio-backward-overlap ）。另一方面，它需要一个更大的反转缓冲区，并可能由于破坏管线而使播放不顺畅（例如，通过解码很多，然后有一段时间什么都不做）。

设置 --video-backward-batch 可能没有意义。但在理论上，它可以通过减少backstep操作来帮助intra-only编码。

--demuxer-backward-playback-step=<seconds>

在回放过程中，解复用器应该跳转回的获得新数据包的秒数（默认：60）。这对调整向前播放是很有用的，详见 --play-direction

设置为一个非常低的值或0，可能会使播放器认为跳转被损坏，或可能使它执行多次跳转。

将其设置为较高值可能会导致二次运行时的行为。

程序行为

--help, --h

显示选项的简短摘要。

也可以传递给该选项一个字符串，它将列出所有名称中包含该字符串的顶级选项，例如， --h=scale 代表所有包含 scale 的选项。特殊字符串 * 列出所有顶级选项。

-v

增加详细级别，在命令行上每多一个 -v 就增加一个级别。

--version, -V

输出版本号的字符串并退出。

--no-config

不加载默认设置或任何用户文件。这会阻止加载用户级别和系统级别的 mpv.conf 和 input.conf 文件。其它用户文件也会被阻止，比如恢复播放文件和缓存文件。此选项仅在作为命令行标志使用时才生效。

备注

由命令行选项明确请求的文件，如 --include 或 --use-filedir-conf ，仍将被加载。

另参见： --config-dir

--list-options

输出所有可用的选项。

--list-properties

输出一系列可用的属性列表。

--list-protocols

输出一系列受支持的协议列表。

--log-file=<path>

打开给定的路径进行写入，并输出日志信息到其中。已存在的文件将被替换。日志级别至少是 -v -v ，但可以通过 --msg-level 提高（该选项不能降低到强制的最低日志级别以下）。

一个特殊情况是macOS bundle，它将默认在 ~/Library/Logs/mpv.log 创建一个日志文件。

--config-dir=<path>

强制使用一个不同的设置目录。如果设置了这个，给定的目录将被用来加载设置文件，而所有其它的设置目录都会被忽略。这表示全局的mpv设置目录以及每个用户的目录都被忽略，通过环境变量（ MPV_HOME ）覆盖的内容也被忽略。

请注意，缓存路径和状态路径（~~/cache，~~/state）不被视为“设置”，它们保留自己的自动检测逻辑。

注意， --no-config 选项优先于该选项。

--dump-stats=<filename>

将某些统计数据写入给定的文件。该文件在打开时被截断。该文件将包含原始样本，每个样本都有一个时间戳。为了使这个文件变成可读的，可以使用脚本 TOOLS/stats-conv.py （目前它以图表形式显示）。

这个选项只在调试时有用。

--idle=<no|yes|once>

让mpv在没有文件可以播放时空闲等待而不是退出。主要在输入模式下有用，mpv可以通过输入命令来控制。（默认： no )

once 将只在启动时空闲，一旦第一个播放列表播放完毕，就让播放器关闭。

--include=<configuration-file>

指定设置文件，在默认设置文件之后进行解析。

--load-scripts=<yes|no>

如果设置为 “no”，则不自动加载设置子目录 scripts （通常是 ~/.config/mpv/scripts/ ）中的脚本。（默认： yes ）

--script=<filename>, --scripts=file1.lua:file2.lua:...

加载一个Lua脚本。第二个选项允许你加载多个脚本，用路径分隔符（Unix下为 : ，Windows下为 ; ）将它们分开。

--scripts 是一个路径列表选项。详见 列表选项

--script-opts=key1=value1,key2=value2,...

为脚本设置选项。脚本可以通过按键来查询一个选项。如果一个选项被使用，以及该选项值具有什么样的语义，完全取决于所加载的脚本。没有被任何脚本声明的值会被忽略。

这是一个按键/值列表选项。详见 列表选项

--merge-files

假装所有传递给mpv的文件都被串联成一个单一的大文件。这使用内部的时间轴/EDL支持。

--profile=<profile1,profile2,...>

使用给定的配置预设， --profile=help 显示已定义的配置预设的列表。

--reset-on-next-file=<all|option1,option2,...>

通常情况下，mpv在播放播放列表上的下一个文件时，会尝试保留所有的设置，即使用户在播放时改变了这些设置（这种行为与MPlayer相反，MPlayer在开始播放下一个文件时尝试重置所有设置）。

默认：不重置任何东西。

这可以通过这个选项来改变。它接受一个选项列表，mpv将在播放开始时把这些选项的值重置为初始值。初始值要么是默认值，要么是由设置文件或命令行设置的。

特殊名称 all 会重置尽可能多的选项。

这是一个字符串列表选项。详见 列表选项

示例

• --reset-on-next-file=pause 在切换到下一个文件时重置暂停模式

• --reset-on-next-file=fullscreen,speed 重置全屏和播放速度设置，如果它们在播放过程中被改变

• --reset-on-next-file=all 尝试重置所有在播放过程中被改变的设置

--show-profile=<profile>

显示一个配置预设的描述和内容。如果没有提供参数，则列出所有的配置预设。

--use-filedir-conf

在将要播放的文件的同一目录下查找针对该文件的设置文件。参见 特定文件的设置文件

警告

如果从不受信任的媒体中播放可能会有风险。

--ytdl=<yes|no>

启用youtube-dl hook脚本。它将查看输入的URL，并播放位于该网站上的视频。这适用于许多流媒体网站，而不仅仅是该脚本所命名的网站。这需要在系统上安装一个较新版本的youtube-dl。（默认： yes）

如果该脚本不能处理某个URL，它将不执行任何操作。

它接受一组选项，可以通过 --script-opts 选项（使用 ytdl_hook- 作为前缀）传递给它：

try_ytdl_first=<yes|no>

如果 “yes”，将首先尝试用youtube-dl解析URL，而不是默认的在mpv加载失败后才解析。这主要取决于你的大部分URL是否需要youtube-dl解析。

exclude=<URL1|URL2|...

一个用 | 分隔的不使用youtube-dl的URL模式列表。这些模式在URL的 http(s):// 部分之后被匹配。

^ 匹配URL的开头， $ 匹配其结尾，你应该在任何 ^$()%|,.[]*+-? 字符之前使用 % 来匹配该字符。

示例

• --script-opts=ytdl_hook-exclude='^youtube%.com' 将排除任何以 http://youtube.com 或 https://youtube.com 开头的URL。

• --script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$' 将排除任何以 .mkv 或 .mp4 结尾的URL。

在这里可以看到更多的lua模式：https://www.lua.org/manual/5.1/manual.html#5.4.1

all_formats=<yes|no>

如果 “yes”，将尝试添加所有由youtube-dl报告的格式（默认： no）。每种格式都作为一个单独的轨道被添加。此外，它们被延迟加载，且实际上只有在选择轨道时才会打开（这应该能使加载时间和没有这个设置选项时一样短）。

它增加了平均比特率的元数据，如果可获得的话，这表示可以使用 --hls-bitrate 来决定选择哪条轨道（HLS过去是唯一一种以类似方式公开替代质量流的格式，因此这是选项的名称）。

代表youtube-dl默认选择的格式的音轨将被设置为dedfault标志。这表示mpv通常仍应选择用 --ytdl-format 默认选择的格式。

尽管这种机制使得在运行时切换流成为可能，但由于各种技术原因，它并不适合该目的（它很慢，这无法真正解决）。一般而言，这个选项无用，只是为了显示它的可能性而添加的。

在做质量/带宽选择时，有两种情况必须考虑：

1. 完全独立的音频和视频流（类似DASH）。这些流中的每一个都只包含音频或视频，所以可以不受限制地混合和组合音频/视频带宽。这在直觉上与按音轨选择质量的概念最匹配（ all_formats 的存在缘由）。

2. 独立的混合音频和视频流的集合。每个版本的媒体都包含音频和视频流，而且它们是交错的。为了不浪费带宽，应该只选择这些版本中的一个（例如，如果选择了一个音频流，那么对应的视频将被下载，即使选择了不同流的视频）。

   mpv仍然将它们表示为单独的轨道，但会将每个轨道的标题设置为 muxed-N ，其中 N 被替换为原流的youtube-dl格式的ID。

有些网站会混合使用1.和2.，但我们假定他们这样做是出于兼容性的考虑，但根本没有理由使用它们。

force_all_formats=<yes|no>

如果设置为 “yes”，并且 all_formats 也设置为 “yes”，这将尝试将所有youtube-dl报告的格式表示为轨道，即使mpv通常会使用它报告的direct URL（默认： yes）。

如果youtube-dl在一个master HLS播放列表上工作，这通常会有区别。

如果设置为 “no”，这种特定的流会被当作好像 all_formats 设置为 “no”，并使用youtube-dl（通过 -ytdl-format ）进行流的选择。

thumbnails=<all|best|none>

将缩略图添加为视频轨（默认： none）

缩略图作为轨道添加时会被下载，因此当缩略图较多时， “all” 会明显影响打开视频所需的时间。

use_manifests=<yes|no>

使mpv使用如HLS和DASH等格式的master manifest URL，如果可获得的话，允许在运行时选择视频/音频（默认： no）。由于性能原因，默认禁用（”no”）。

ytdl_path=youtube-dl

设置youtube-dl的可执行文件或兼容的fork文件的路径。路径应该用分隔符，Unix是 “:” 而Windows是 “;” 。mpv在PATH和mpv的设置目录中依次寻找设置的路径。默认的是 “yt-dlp”，”yt-dlp_x86” 和 “youtube-dl”。在Windows上，后缀并非必要，但只接受 “.exe” 。

为什么选项名称混合了 _ 和 - ？

我不知道。

--ytdl-format=<ytdl|best|worst|mp4|webm|...>

直接传递给youtube-dl的视频格式/质量。可能的值是针对网站和视频的，对于一个给定的URL，可用的格式可以通过命令 youtube-dl --list-formats URL 找到。关于可用的别名，参见youtube-dl的文档。（默认： bestvideo+bestaudio/best )

ytdl 的值根本没有向youtube-dl传递 –format` 选项，因此没有覆盖其默认值。注意，有时youtube-dl返回的格式是mpv无法使用的，在这种情况下，mpv的默认值可能会更好工作。

--ytdl-raw-options=<key>=<value>[,<key>=<value>[,...]]

传递任意的选项给youtube-dl。参数应该以按键-值成对的形式传递。没有参数的选项必须包括 = 。

没有安全检查，所以有可能破坏某些事情（例如，将无效的参数传递给youtube-dl）。

可以传递一个代理URL，让youtube-dl在解析网站时使用它。这对于有地理限制的URL很有用。在youtube-dl解析后，一些URL也需要代理来播放，所以这可以把代理信息传递给mpv。请注意，SOCKS代理不被支持，https的URL也会绕过代理。这是FFmpeg的一个限制。

这是一个按键/值列表选项。详见 列表选项

示例

• --ytdl-raw-options=username=user,password=pass

• --ytdl-raw-options=force-ipv6=

• --ytdl-raw-options=proxy=[http://127.0.0.1:3128]

• --ytdl-raw-options-append=proxy=http://127.0.0.1:3128

--js-memory-report=<yes|no>

启用在数据统计叠加层中为JavaScript脚本报告内存使用情况。默认禁用，因为它会增加开销并增加内存使用量。此选项仅在启动mpv之前启用时才会生效。

--load-stats-overlay=<yes|no>

启用内置脚本，在一个按键绑定上显示有用的播放信息（默认： yes）。默认情况下，使用 i 键（ I 键使覆盖层永久化）。

--load-osd-console=<yes|no>

启用内置脚本，在一个按键绑定上显示控制台，可让你输入命令（默认： yes）。在默认情况下， ` 键用于显示控制台， ESC 键用于再次隐藏它。

--load-auto-profiles=<yes|no|auto>

启用内置脚本，进行自动配置预设（默认： auto ）。详见 附带条件的自动配置预设 。 auto 将加载脚本，但如果不存在附带条件的自动配置预设，则立即卸载它。

--load-select=<yes|no>

启用内置脚本，让你从项目列表中进行选择（默认： yes）。默认情况下，它的按键绑定以 g 键开始。

--player-operation-mode=<cplayer|pseudo-gui>

用于启用“伪GUI模式”，这表示一些选项的默认值被改变。这个选项通常不应该直接使用，而应该由mpv内部使用，或者由mpv提供的脚本、设置文件或.desktop文件。详见 伪GUI模式

稍后观看

--save-position-on-quit

在退出时总是保存当前的播放位置。当以后再次播放该文件时，播放器会在开始时跳转到之前的播放位置。如果以任何其他方式停止一个文件的播放而不是退出，这种情况不会发生。例如，前往播放列表中的下一个文件不会保存位置，而是在下次播放该文件时从头开始播放。

这种行为默认是禁用的，但当用Shift+Q退出播放器时，总是可用的。

--watch-later-dir=<path>

存储“稍后观看”临时文件的目录。

--watch-later-directory 是 --watch-later-dir 的别名。

如果不设置该选项，临时文件将被存储在本地的状态目录（通常是 ~/.local/state/mpv/ ）下的一个名为 “watch_later “的子文件夹中。

--resume-playback=<yes|no>

在设置子目录 watch_later （通常是 ~/.config/mpv/watch_later/ ）恢复播放位置。参见 quit-watch-later 输入命令。（默认： yes）

--resume-playback-check-mtime=<yes|no>

如果文件的修改时间与保存时间相同，只恢复设置子目录 watch_later （通常是 ~/.config/mpv/watch_later/ ）中的播放位置。这可以阻止同名但内容不同的文件向后跳过。（默认： no ）

--watch-later-options=option1,option2,...

如果选项在mpv启动后被改变，它们将被保存在 “watch_later” 里的文件中。这些值将在下次播放文件时被恢复。注意，播放位置是通过 start 项保存的。

当移除选项时，已有的稍后观看的数据不会被修改，仍然会被完全应用，但是新的稍后观看的数据将不包含这些选项。

有关默认恢复的属性列表，参见 --help=watch-later-options 。

这是一个字符串列表选项。详见 列表选项

示例

• --watch-later-options-remove=sid 字幕轨的选择不会被保存到稍后观看的文件中

• --watch-later-options-remove=volume --watch-later-options-remove=mute 音量和静音状态不会被保存到稍后观看的文件中

• --watch-later-options=start 没有项目将被保存到稍后观看的文件中，除了（最后的）播放位置

--write-filename-in-watch-later-config

在稍后观看的设置文件前加上它们所指的文件名。这只是作为注释简单的写入在文件的顶部。

警告

这个选项可能会暴露隐私敏感信息，因此默认禁用。

--ignore-path-in-watch-later-config

在使用稍后观看功能时忽略路径（即只使用文件名）。（默认： no）

视频

--vo=<driver>

指定要使用的视频输出后端。详见 视频输出驱动 以了解可用驱动程序的描述。

--vd=<...>

根据视频解码器的族和名称，指定要使用的视频解码器的优先列表。详见 --ad 。这两个选项使用相同的语法和语义；唯一的区别是它们对不同的解码列表进行操作。

备注

参见 --vd=help 了解可用解码器的完整列表。

--vf=<filter1[=parameter1:parameter2:...],filter2,...>

指定一个视频滤镜的列表，应用于视频流。详见 视频滤镜 了解可用滤镜的描述。选项变体 --vf-add , --vf-pre 和 --vf-clr 的存在是为了修改先前指定的列表，但在典型使用中应该不需要这些。

--untimed

在输出视频帧时不休眠。当与 --audio=no 一起使用时，对基准测试有用。

--framedrop=<mode>

在速度慢的系统上，或者在有帧数上限的视频输出上播放高帧率的视频时，跳过显示一些帧来维持A/V同步。

该参数选择丢帧的方式，可以是下列之一：

<no>

禁用任何丢帧。不推荐，仅用于测试。

<vo>

在视频输出中丢弃落后的帧（默认）。这仍然对所有帧进行解码和过滤，但不在视频输出中渲染它们。丢弃的帧在终端状态行中显示在 Dropped: 字段。

在音频同步的模式下，这将丢弃在显示时已经过期的帧。如果解码器太慢，理论上所有的帧都会被丢弃（因为所有的帧都太晚） —— 为了避免这种情况，如果有效帧率低于10FPS，则停止丢帧。

在显示同步模式下（参见 --video-sync ），这只影响A/V丢帧或帧重复的方式。如果该模式被禁用，A/V不同步理论上不会再影响视频调度（很像 display-resample-desync 模式）。然而，即使禁用，帧仍然会根据视频和显示频率之间的比例被跳过（即丢帧）。

这是推荐的模式，也是默认的模式。

<decoder>

旧的、基于解码器的丢帧模式（这与mpv0.5.x及之前版本中的 --framedrop=yes 相同）。这告诉解码器跳过帧（除非需要它们来解码未来的帧）。可能对慢速系统有帮助，但可能产生无法观看的不稳定输出，甚至完全冻结显示。

这使用了一种可能没有意义的启发式方法，而且一般来说不能获得良好的结果，因为解码器的丢帧不能以一种可预测的方式控制。不推荐。

即使你想使用这个，也最好选择 decoder+vo 以获得更好的结果。

--vd-lavc-framedrop 选项控制要丢掉哪些帧。

<decoder+vo>

启用两种模式。不推荐。但比只有 decoder 的模式好。

备注

--vo=vdpau 有自己的代码用于 vo 丢帧的模式。与其它的视频输出驱动可能有轻微的不同。

--video-latency-hacks=<yes|no>

启用一些倾向于减少1或2帧视频延迟的东西（默认： no）。请注意，一旦播放器的计时代码不再需要做这些事情，这个选项可能会被移除而不另行通知。已知使用该选项会破坏其它选项（例如 –interpolation ），因此不建议启用。

它的操作：

• 使用解复用器报告的FPS进行丢帧。这避免了播放器需要提前解码1帧，有效地降低了总延迟。这也表示，如果解复用器报告的FPS是错误的，或者视频滤镜链改变了FPS（例如去隔行扫描），那么它就可能丢弃太多或不够的帧数。

• 禁用等待第一个视频帧。通常情况下，播放器会等待第一个视频帧被完全渲染后再开始正常播放。一些视频输出驱动会在渲染第一帧时懒散地初始化一些东西，所以如果不这样做，如果渲染第一帧的时间太长超过需求，视频输出就不得不丢弃一些帧。

--display-fps-override=<fps>

设置与 --video-sync=display-* 模式一起使用的显示FPS。默认情况下，使用一个检测值。请记住，设置一个不正确的值（即使是轻微的错误）可能会破坏视频播放。在多显示器系统中，有可能检测到的值来自错误的显示器。

只有在你有理由相信自动检测的数值是错误的情况下才设置这个选项。

--hwdec=<api1,api2,...|no|auto|auto-safe|auto-copy>

如果可能的话，指定应该使用的视频硬件解码API。硬解码是否实际完成取决于视频编码。如果硬件解码不可能，mpv将回退到软件解码。

硬件解码在默认情况下是不启用的，目的是保持开箱即用的设置尽可能的可靠。然而，当使用现代硬件时，硬解码应该能正常工作，提供更低的CPU使用率，并可能减少功耗。在老旧系统上，由于CPU资源不足，可能有必要使用硬解码；即使在现代系统上，足够复杂的内容（例如4K60 AV1）也可能需要它。

备注

使用 Ctrl+h 快捷键来在运行时切换硬解码。它在 auto-safe 和 no 之间切换这个选项。

如果你决定默认使用硬件解码，一般的建议是用命令行选项尝试解码，并向自己证明它对你关注的内容有理想的效果。在此之后，你可以把它添加到你的设置文件中。

在测试时，你应该先使用 hwdec=auto-safe ，因为它将限制自己从开发团队积极支持的hwdec中选择。如果这并没有产生有效的硬解码，你可以尝试 hwdec=auto 让它尝试加载所有可能的hwdec，但是如果 auto-safe 无法工作，你可能需要知道哪种hwdec与你的硬件匹配，并阅读下方的条目。

如果 auto-safe 或 auto 产生了期待的结果，我们建议只需坚持使用它，如果确实有必要，只在你的设置文件中设定一个特定的hwdec。

如果你使用Ubuntu软件包，请记住他们的 /etc/mpv/mpv.conf 包含 hwdec=vaapi ，这不是很理想，因为它对你的系统来说可能不是正确的选择，而且它可能最终使用一个低效的wrapper来掩饰。我们建议删除这一行或完全删除该文件。

备注

即使启用，硬解码仍然只对某些编码开放白名单。在更多的情况下启用硬解码，参见 --hwdec-codecs

选择哪种方式？

• 如果只想在运行时启用硬件解码，不要设置参数，或者在 mpv.conf 中加入 hwdec=no （与某些在默认情况下强制启用的发行版相关，比如Ubuntu）。使用默认绑定 Ctrl+h 在运行时启用它。

• 如果不确定，但希望硬件解码在默认情况下被启用，可以在 mpv.conf 中加入 hwdec=auto-safe ，并认识到可能会导致问题。

• 如果想测试可用的硬件解码方式，传递 --hwdec=auto --hwdec-codecs=all ，查看终端的输出。

• 如果你是一个开发者，或者想进行详细的测试，可能需要其它任何可能的选项值。

该选项接受一个以逗号分隔的 api 类型的列表，以及某些特殊值：

no:

始终使用软件解码（默认）

auto-safe:

启用任何白名单中的hw解码器（见下文）

auto:

强制启用任何已找到的hw解码器（见下文）

yes:

与 auto-safe 完全相同

auto-copy:

启用最佳的带copy-back的hw解码器（见下文）

备注

特殊值可以与api名称混合。例如： vaapi,auto 将尝试使用 vaapi ，如果失败，再运行一般的 auto 逻辑。

受到积极支持的hwdec：

d3d11va:

需要 --vo=gpu 与 --gpu-context=d3d11 或 --gpu-context=angle （Windows 8以上独占）

d3d11va-copy:

将视频复制回到系统RAM（Windows 8以上独占）

videotoolbox:

需要 --vo=gpu （macOS 10.8及以上）或 --vo=libmpv （iOS 9.0及以上）

videotoolbox-copy:

将视频复制回到系统RAM（macOS 10.8或iOS 9.0及以上版本）

vaapi:

需要 --vo=gpu 或 --vo=vaapi 或 --vo=dmabuf-wayland （Linux独占）

vaapi-copy:

将视频复制回到系统RAM（Linux或Windows，且仅某些GPU可用）

nvdec:

需要 --vo=gpu （任何可用CUDA的平台）

nvdec-copy:

将视频复制回到系统RAM（任何可用CUDA的平台）

drm:

需要 --vo=gpu （Linux独占）

drm-copy:

将视频复制回到系统RAM（Linux独占）

vulkan:

需要 --vo=gpu-next （任何带有Vulkan视频解码的平台）

vulkan-copy:

将视频复制回到系统RAM（任何带有Vulkan视频解码的平台）

其它的hwdec（只有当你了解不得不做时才使用）：

dxva2:

需要 --vo=gpu 与 --gpu-context=d3d11 或 --gpu-context=angle 或 --gpu-context=dxinterop （Windows独占）

dxva2-copy:

将视频复制回到系统RAM（Windows独占）

vdpau:

需要 --vo=gpu 和 --gpu-context=x11 ，或 --vo=vdpau （Linux独占）

vdpau-copy:

将视频复制回到系统RAM（Linux独占，且仅某些GPU可用）

mediacodec:

需要 --vo=gpu 与 --gpu-context=android ，或 --vo=mediacodec_embed （Android独占）

mediacodec-copy:

将视频复制回到系统RAM（Android独占）

cuda:

需要 --vo=gpu （任何可用CUDA的平台）

cuda-copy:

将视频复制回到系统RAM（任何可用CUDA的平台）

crystalhd:

将视频复制回到系统RAM（任何受硬件支持的平台）

rkmpp:

需要 --vo=gpu （部分RockChip设备独占）

auto 尝试使用第一个可用的方式来自动启用硬解码。这仍然取决于所使用的是什么视频输出驱动。例如，如果没有使用 --vo=gpu 或 --vo=vdpau ，vdpau解码将永不会被启用。还要注意的是，如果第一个找到的方式在实际情况中无法工作，它将总是回退到软解，而不是尝试下一个方式（在一些Linux系统上可能很重要）。

auto-safe 与 auto 类似，但只允许白名单中的被认为是“安全”的方式。这应该是在设置文件中默认启用硬解的一种合理方式（尽管你不应该这样做；最好在运行时用 Ctrl+h 启用）。不像 auto ，它不会尝试启用未知或已知的损坏的方式。此外，在其它已知会导致问题的情况下，这可能会禁用硬解，但目前这个机制是相当原始的（作为一个仍然会引发问题的例子：Windows上HEVC和Intel芯片的某些组合往往会导致mpv崩溃，很可能是由于驱动的错误）。

auto-copy-safe 选择了联合 auto-safe 和 auto-copy 的方式。

auto-copy 只选择在解码后将视频数据复制回到系统内存的模式。这就选择了像 vaapi-copy （等等）这样的模式。如果这些都无效，硬解就会被禁用。这种模式通常保证，与软解相比不会产生额外的质量损失（假定视频流是现代的编码且无错误），并将允许由CPU处理的视频滤镜。这种模式适用于所有视频滤镜和视频输出驱动。

因为这些模式把解码后的视频复制回到系统RAM，它们的效率往往不如直接模式，如果你的CPU资源不足，可能对软解没有太大帮助。

备注

大多数non-copy的方式只在OpenGL GPU后端工作。目前，只有 vaapi 、 nvdec 和 cuda 方式能在Vulkan上工作。

vaapi 模式，如果与 --vo=gpu 一起使用，需要Mesa 11，并且很可能只适用于Intel和AMD的GPU。它还需要opengl EGL后端。

nvdec 和 nvdec-copy 是最新的方式，建议在Nvidia GPU上进行硬解。

cuda 和 cuda-copy 是在Nvidia GPU上进行硬解的老旧实现，使用Nvidia的比特流解析器，而不是FFmpeg的。这可能导致功能上的缺失，比如HDR内容的错误播放， nvdec / nvdec-copy 应始终是首选，除非特别需要Nvidia的去隔行扫描算法。要使用这种反交错，必须传递选项： vd-lavc-o=deint=[weave|bob|adaptive] 。传递 weave （或不设置该选项）来不尝试任何反交错。

硬件解码的质量降级

理论上，硬解不会降低视频质量（至少对于h264和HEVC编码是这样）。然而，由于视频输出API的限制，以及实际硬件解码器的错误，可能会有一些损失，甚至是非常不正确的结果。这在很大程度上已经不再是现代硬件的问题，但仍有很多硬件不在此范围内，所以要注意。下面讨论了已知的问题，但不能认为这个清单是详尽的，因为即使是在某一代硬件上运行良好的hwdec，在其它型号上也可能有问题。

在某些情况下，RGB转换是强制的，这表示RGB转换是由硬件解码API执行的，而不是由 --vo=gpu 使用的着色器。这意味着某些色彩空间可能无法正确显示，而且某些过滤（比如去色带）不能以理想的方式应用。这通常也会迫使用低质量的色度缩放器，而不是由 --cscale 指定的。在其它情况下，硬解也会降低解码后图像的位深，对于10-bit的文件来说，会引入色带或精度损失。

vdpau 始终在硬件中进行RGB转换，它不能正确支持较新的色彩空间，如BT.2020。然而， vdpau 不支持10比特或HDR编码，所以这些限制不太可能是相关的。

dxva2 是不安全的。它似乎总是使用BT.601进行强制RGB转换，但实际行为取决于GPU驱动程序。一些驱动程序似乎会转换为有限范围的RGB，这给人一种褪色的感觉。除了特定驱动程序的行为外，全局系统设置可能也会影响到这一点。即使是完全普通的视频源，这也可能会给出不正确的结果。

mediacodec 是不安全的。 它强制进行RGB转换（非 -copy ），它对非标准色彩空间的处理效果如何还不清楚。在极少数支持10位的情况下，输出的位深度将被降低到8。

cuda 通常是安全的，但取决于文件/流的混合方式，据报告它会破坏时间戳，导致帧闪烁。它有时也会因不明原因而引起大量的丢帧。建议谨慎使用， nvdec 应该始终是优选。

crystalhd 不安全。它总是转换为4:2:2 YUV，这可能是有损的，取决于转换过程中如何进行色度抽样。出于某种原因，它还会丢弃每一帧的左上角像素。

如果你遇到任何奇怪的解码问题，帧故障或变色，并且你启用了 --hwdec ，你应该首先尝试禁用它。

--gpu-hwdec-interop=<auto|all|no|name>

这个选项是用来排除硬解interop问题的。由于它是一个调试选项，它的语义可能在任何时候改变。

这对 gpu 和 libmpv 视频输出驱动很有用，可以准确选择使用哪个硬解interop context。它也可以用来有效的阻止某些后端的加载。

如果设置为 auto （默认），其行为取决于视频输出驱动：对于 gpu ，它不做任何事情，interop context在有需求时被加载（当解码器探测到 --hwdec 支持时）。对于没有按需加载的 libmpv ，这相当于 all 。

空字符串等同于 auto 。

如果设置为 all ，它尝试在GL context创建时加载所有的interop contexts。

除此以外，可以设置特定的后端，且可以用 help 查询它们的列表（仅mpv CLI可用）。

在运行时对此的更改会被忽略（每当渲染器被创建时都会使用当前的选项值）。

--hwdec-extra-frames=<N>

硬件解码应该预分配的GPU帧数（默认：参见 --list-options 的输出）。如果这个数值太低，在解码过程中帧分配可能会失败，视频帧可能会被丢弃或破坏。设置太高则只是浪费显存，没有任何好处。

这个值只用于需要预先分配surfaces的硬解API（已知的例子包括 d3d11va 和 vaapi ）。对于其它API，帧是按需分配的。细节取决于硬件解码器的libavcodec实现。

所需的surfaces数取决于动态运行时的状况。默认值是一个固定值，被认为对大多数用途来说是足够的。但在某些情况下，它可能是不够的。

--hwdec-image-format=<name>

通过 --hwdec 设置硬解使用的内部像素格式（默认： no ）。特殊值 no 选择一个特定于实现的标准格式。大多数解码器实现只支持一种格式，如果不支持某格式，将初始化失败。

有些实现可能支持多种格式。特别的是，已知videotoolbox需要 uyvy422 以便在一些旧的硬件上获得良好的性能。d3d11va可能始终使用 yuv420p ，这使用不透明的格式，可能没有优势。

--cuda-decode-device=<auto|0..>

在使用OpenGL GPU后端的 cuda 或 nvdec 硬解时选择用于解码的GPU设备，在使用 cuda-copy 或 nvdec-copy 硬解时的所有情况也是如此。

对于OpenGL GPU后端，用于解码的默认设备是被用来提供 gpu 输出的设备（在绝大多数情况下，只有一个GPU会呈现）。

对于 copy 硬解，默认设备将是CUDA库所枚举的第一个设备 —— 无论如何都是如此。

对于Vulkan GPU后端，解码必须始终发生在显示设备上，这个选项没有影响。

--vaapi-device=<device file|adapter name>

为 vaapi-copy 选择DRM设备。这应该是一个DRM设备文件的路径。（默认： /dev/dri/renderD128 ）

在 Windows 系统中，它会将适配器名称作为输入。如果未设置，将选择默认适配器。如果输入 “help” ，则会列出替代适配器。

--panscan=<0.0-1.0>

启用平移和扫描功能（例如，裁剪16:9视频的两侧，使其适合4:3的显示器而没有黑边）。范围控制图像被裁剪的程度。可能不适用于所有的视频输出驱动。

如果使用了选项 --video-unscaled ，这个选项就没有作用。

--video-aspect-override=<ratio|no>

覆盖视频长宽比，以防播放的文件中长宽比信息不正确或缺失。

这些值有特殊含义：

0:

禁用长宽比处理，假设视频是方形像素

no:

与 0 相同

-1:

使用视频流或容器的长宽（默认）

但请注意，对这些特殊值的处理在未来可能会改变。

示例

• --video-aspect-override=4:3 或 --video-aspect-override=1.3333

• --video-aspect-override=16:9 或 --video-aspect-override=1.7777

• --no-video-aspect-override 或 --video-aspect-override=no

--video-aspect-method=<bitstream|container>

这设置了默认的视频长宽决定方法（如果长宽 _没有_ 被用户用 --video-aspect-override 或其它方式覆盖）。

container:

严格倾向于容器的长宽比。这显然是VLC的默认行为，至少在Matroska中是如此。请注意，如果容器没有设置长宽比，其行为与比特流相同

bitstream:

严格倾向于比特流长宽比，除非没有设置比特流长宽比。这显然是XBMC/kodi的默认行为，至少对Matroska是这样

目前mpv的默认值是 container

通常情况下，你不应该设置这个。如果遇到的视频在mpv里有错误的长宽比，但在其它播放器里似乎是正确的，请尝试各种选择。

--video-unscaled=<no|yes|downscale-big>

禁用视频的缩放功能。如果窗口比视频大，就会添加黑条。否则，视频将被裁切，除非该选项被设置为 downscale-big ，在这种情况下，视频将匹配窗口。视频仍然可以受到其他 --video-... 选项的影响。该选项禁用了 --panscan 的效果。

请注意，即使视频没有被缩放，缩放器的算法仍然可能被使用。例如，这可能影响色度转换。如果视频源使用非正方形像素（例如变形宽屏DVD），视频也将在一个通道上被缩放。

如果使用 --keepaspect=no ，该选项将被禁用。

--video-pan-x=<value>, --video-pan-y=<value>

将显示的视频矩形在X或Y方向移动给定的值。单位是缩放后的视频尺寸的分数（全尺寸，即使视频的部分内容由于panscan或其它选项不可见）。

例如，使用 --video-pan-x=-0.1 在一个1920x1080屏幕上全屏显示视频会将视频向左移动192像素，而使用 --video-pan-y=-0.1 会将视频向上移动108像素。

如果使用 --keepaspect=no ，该选项将被禁用。

--video-rotate=<0-359|no>

顺时针旋转视频，单位是度。如果给了 no ，视频就永远不会旋转，即使文件有旋转元数据（旋转值被添加到旋转元数据中，这意味着 0 值将根据旋转元数据旋转视频）。

当使用没有copy-back的硬件解码时，只有90°的步幅可以工作，而软解和将视频复制回到系统内存的硬解方式支持0和359之间的所有值。

--video-crop=<[W[xH]][+x+y]>, --video-crop=<x:y>

裁切视频，从x、y偏移处开始，裁剪w、h像素。裁切将由VO应用于源视频矩形（在变形拉伸之前）。裁剪矩形如果不在视频矩形内，则会被忽略。与等效的 ‘lavfi-crop’ 不同，这适用于硬件解码。如果省略偏移，将裁切中心区域。将裁剪设置为空的 --video-crop=0x0+0+0 将覆盖容器的裁剪并禁用裁剪。将裁剪设置为 --video-crop="" 将禁用手动裁切，并在指定时恢复容器的裁切。

--video-zoom=<value>

按给定值调整视频显示缩放（变焦）。该参数是给定的对数2。例如， --video-zoom=0 是不缩放， --video-zoom=1 是两倍尺寸， --video-zoom=-2 是四分之一，以此类推。

如果使用 --keepaspect=no ，该选项将被禁用。

--video-scale-x=<value>, --video-scale-y=<value>

将视频显示尺寸与给定值相乘（默认： 1.0）。如果使用非默认值，这将与窗口尺寸不同，所以视频将被切断，或加入黑条。

这个值与从 --video-zoom 得出的值和正常的视频宽高比相乘。如果使用 --keepaspect=no ，该选项将被禁用。

--video-align-x=<-1-1>, --video-align-y=<-1-1>

在黑色边框内移动视频矩形，如果视频和屏幕的长宽比不同，通常会添加黑色边来填充视频到屏幕。 --video-align-y=-1 会将视频移到屏幕顶部（只在底部留有边框），数值为 0 会将其居中（默认），数值为 1 会将视频放在屏幕底部。

如果视频和屏幕的长宽比完全匹配，这些选项没有任何作用。

如果使用 --keepaspect=no ，该选项将被禁用。

--video-margin-ratio-left=<val>, --video-margin-ratio-right=<val>, --video-margin-ratio-top=<val>, --video-margin-ratio-bottom=<val>

在每条边上设置额外的视频边距（默认： 0）。每个值是窗口大小的比率，使用的范围是0.0-1.0。例如，在窗口大小为1000像素时，设置选项 --video-margin-ratio-right=0.2 ，将在窗口的右边增加200像素的边框。

视频会被这些边距“框住”。窗口的大小不改变。特别是它不会放大窗口，而且边距会引起视频默认被缩小。这在将来可能会也可能不会改变。

边距是在视频旋转90°后应用的，但在任何其它视频转换之前。

如果使用 --keepaspect=no ，该选项将被禁用。

字幕仍然可以使用这些边距，取决于 --sub-use-margins 及类似的选项。

这些选项是为OSC创建的。一些奇怪的决定是为了OSC而作出的，例如使边距值成为一个比率（而不是像素）。这些选项有可能被那些更普遍有用的选项所取代。这些选项的行为也可能改变，以更好的适应OSC的要求。

--correct-pts=<yes|no>

--correct-pts=no 将mpv切换到使用固定帧率值（使用 --container-fps-override 选项，或使用文件信息）来确定视频计时的模式。有时，在这种模式下，具有非常破碎的时间戳的文件可以得到一定程度的播放。请注意，在这种模式下，视频滤镜、字幕渲染、跳转（包括精确跳转和帧步退）和音频同步可能完全被破坏。

--container-fps-override=<float>

覆盖视频帧速率。如果原始值是错误的或缺失的，则很有用。

备注

只在 --correct-pts=no 模式下工作。

--deinterlace=<yes|no|auto>

启用或禁用隔行扫描（默认： no）。隔行扫描的视频会出现丑陋的梳状伪影，在快速移动时可见。启用这个功能通常会插入bwdif视频滤镜，以便对视频进行去隔行扫描，或者如果支持的话，让视频输出应用去隔行扫描。

使用 auto 时，如果 ffmpeg 检测到视频帧是隔行扫描的，mpv 将插入去隔行扫描滤镜。请注意，在某些情况下可能会出现误报，例如文件被编码为隔行扫描，但视频实际上并非如此。因此， auto 不是默认值。

请注意，使用此滤镜 会 与任何手动插入的去隔行扫描滤镜发生冲突，如果视频实际上不是隔行扫描的，这将使视频看起来更糟糕。

--deinterlace-field-parity=<tff|bff|auto>

指定去隔行扫描时的场序（默认： auto） 隔行扫描视频的每一帧被分为两个场，然后分别传输。顶场代表偶数行，底场代表奇数行。去隔行扫描时，去隔行扫描器需要知道场的正确时间顺序，否则视频会出现抖动。

auto 会自动检测视频的场序， tff 会强制顶场优先，而 bff 会强制底场优先。

--frames=<number>

只播放/转换视频的前 <number> 帧，然后退出。

--frames=0 表示加载文件，但在初始化播放前立即退出（可能对那些只想确定一些文件属性的脚本很有用）。

对于纯音频的播放，任何大于0的值都会在初始化后立即退出播放。值0的行为和视频一样。

--video-output-levels=<outputlevels>

用于YUV到RGB转换的RGB动态范围。通常情况下，输出设备比如PC显示器使用全范围的动态范围。然而，一些电视和视频监视器希望使用studio RGB范围。向期望studio级别输入的设备提供全范围输出，会导致黑点和白点的破坏，反之则会导致黑色和白色的发灰。

并非所有的视频输出驱动都支持这个选项。有些会无声的忽略它。

可用的颜色范围是：

auto:

自动选择（等于全范围）（默认）

limited:

有限范围（每个分量16-235），studio 级别

full:

全范围（每个分量0-255），PC级别

备注

建议使用你图形驱动的动态范围的选项，如果可用的话。

--hwdec-codecs=<codec1,codec2,...|all>

只允许对一个给定的编码列表进行硬件解码。特殊值 all 总是允许所有的编码。

可以用 mpv --vd=help 获得允许的编码列表。移除前缀，例如，用 h264 代替 lavc:h264

默认情况下，这被设置为 h264,vc1,hevc,vp8,vp9,av1,prores 。请注意，像 h264_vdpau 这样的硬件加速的特殊编码已经没有意义了，事实上已经从FFmpeg中移除了这种形式。

通常只有在损坏的GPU上才需要这样做，在这种情况下，一个编码被报告为支持，但解码导致的问题比它解决的问题更多。

备注

在某些损坏的驱动程序（如 Linux 上的NVIDIA）上，探测 GPU 不支持的编解码器会不必要地降低视频播放初始化的速度。为缓解这一问题，可明确指定一个列表，其中只包含设置支持的编码。

示例

mpv --hwdec=vdpau --hwdec-codecs=h264,mpeg2video

只对h264和mpeg2启用vdpau解码。

--vd-lavc-check-hw-profile=<yes|no>

检查硬件解码器的profile（默认： yes）。如果设置了 no ，就会无条件地选择硬件解码器的最高profile，即使视频的profile高于此，也会强制解码。其结果很可能是解码错误，但如果检测到的或报告的profile在某种程度上不正确，也可能有帮助。

--vd-lavc-software-fallback=<yes|no|N>

如果硬件加速解码器失败，退回到软件解码（默认：3）。如果这是一个数字，那么如果连续N个帧解码失败，就会触发回退。1相当于 yes

设置为更高的数字可能会破坏播放开始时的回退：如果回退发生，文件的部分内容将被跳过，这大约是无法解码的packets的数量。低于一个未指定计数的值不会有这个问题，因为mpv保留了这些packets。

--vd-lavc-film-grain=<auto|cpu|gpu>

启用GPU上的胶片颗粒应用。如果视频解码是在CPU上完成的，在GPU上做胶片颗粒应用可以加速解码。该选项也有助于硬件解码，因为它可以减少帧拷贝的数量。

默认情况下，它被设置为 auto ，所以如果VO支持胶片颗粒应用，那么它将被视为 gpu 。如果VO不支持这个，那么不论设置的值是什么，它将被视为 cpu 。当前，只有 gpu-next 支持胶片颗粒应用。

--vd-lavc-dr=<auto|yes|no>

启用直接渲染（默认： auto）。如果设置为 yes ，视频将被直接解码到GPU video memory（或暂存缓冲区）。这可以加快视频上传速度，对高分辨率或慢速硬件可能有帮助。这只适用于以下的视频输出驱动：

• gpu : 需要至少OpenGL 4.4或Vulkan

• libmpv : libmpv渲染API有可选的支持

auto 项将尝试猜测DR是否能在你的特定硬件上提高性能。当前，如果使用OpenGL，它会对AMD或NVIDIA启用，如果使用Vulkan，则无条件地启用。

使用任何类型的写入到图像数据（或输出新分配的帧）的视频滤镜都会默默的禁用DR代码路径。

--vd-lavc-bitexact

在所有解码步骤中只使用bit-exact的算法（用于测试编码）。

--vd-lavc-fast （MPEG-1/2和H.264独占）

启用不符合格式规范并可能导致问题的优化，比如简化的dequantization，简化的 motion compensation，假设使用默认的quantization matrix，假设为YUV 4:2:0，跳过一些检查来检测损坏的比特流。

--vd-lavc-o=<key>=<value>[,<key>=<value>[,...]]

向libavcodec解码器传递AVOptions。注意，欢迎打一个补丁，使 o= 不需要通过AVOption系统传递所有未知的选项。AVOptions的完整列表可以在FFmpeg手册中找到。

一些曾经是直接选项的选项可以通过这个机制来设置，比如 bug, gray, idct, ec, vismv, skip_top （原 st ）, skip_bottom （原 sb ）, debug

这是一个按键/值列表选项。详见 列表选项

示例

--vd-lavc-o=debug=pict

--vd-lavc-show-all=<yes|no>

显示即使是破损/毁坏的帧（默认： no）。如果这个选项被设置为no，libavcodec将不会输出在初始关键帧被解码之前的被解码的帧，或者被识别为损坏的帧。

--vd-lavc-skiploopfilter=<skipvalue> （H.264和HEVC独占）

在解码期间跳过loop滤镜（又名deblocking）。由于过滤后的帧应该被用作解码附属帧的参考，这对质量的影响比不对MPEG-2视频进行deblocking更糟糕。但至少对于高比特率的HDTV来说，这提供了一个很大的加速，而几乎没有明显的质量损失。H.264或HEVC以外的编解码器可能部分支持这个选项 (通常只有 all 和 none )。

<skipvalue> 可以是以下的一种：

none:

从不跳过

default:

跳过无用的处理步骤（例如AVI中的0尺寸的packets）

nonref:

跳过没有参考的帧（例如不用于解码其他帧，错误不能“累积”）

bidir:

跳过B帧

nonkey:

跳过所有帧，除了关键帧

all:

跳过所有帧

--vd-lavc-skipidct=<skipvalue> （MPEG-1/2/4独占）

跳过IDCT步骤。这在几乎所有情况下都会使质量下降很多。（可用的skip值参见skiploopfilter）

--vd-lavc-skipframe=<skipvalue>

完全跳过帧的解码。加速很大，但动作生硬，有时会出现不良伪影。（可用的skip值参见skiploopfilter）

--vd-lavc-framedrop=<skipvalue>

设置与 --framedrop 一起使用的成帧掠夺模式。（可用的skip值参见skiploopfilter）

--vd-lavc-threads=<N>

解码时使用的线程数。实际是否支持线程取决于编码（默认： 0）。0表示自动检测机器上的核心数并使用该数，最多为16。你可以手动设置16个以上的线程。

--vd-lavc-assume-old-x264=<yes|no>

假定视频是由一个旧的、有问题的x264版本压制的（默认： no）。通常情况下，这是由libavcodec自动检测的。但是如果比特流不包含x264版本信息（或者以某种方式被跳过），并且该流实际上是由旧的x264（build 150或更早的）版本压制的，并且如果该流使用 4:4:4 色度，那么libavcodec将默认显示损坏的视频。这个选项将libavcodec的 x264_build 选项设置为 150 ，这表示如果流不包含版本信息，或者根本不是由x264压制的，它就会假定它是由旧版本压制的。如果你想让你损坏的文件正常工作，启用这个选项是非常安全的，但是理论上这可能会破坏不是由x264压制的流，或者如果由较新的x264版本压制的流不包含版本信息。

--vd-apply-cropping

某些视频编解码器支持裁切，意味着只有解码帧的子矩形用于显示。此选项控制libavcodec如何处理裁剪。在解码过程中进行裁切对齐和硬件解码方面存在一些限制。如果启用了此选项，解码器将应用裁切，否则由VO处理。默认启用。

--swapchain-depth=<N>

允许最多N个in-flight的帧。这实质上控制了帧的延迟。增加交换链深度可以改善管线并防止错过垂直同步，但会增加可见的延迟。这个选项只规定了一个上限，该实现可以使用比内部请求更低的延迟。设置为1表示视频输出驱动将等待每一帧变为可见，再开始渲染下一帧。（默认： 3）

音频

--audio-pitch-correction=<yes|no>

如果启用这个功能（默认），以不同于正常的速度播放时会自动插入 scaletempo2 音频滤镜。您可以插入除了 scaletempo2 之外的滤镜，并使用 附带条件的自动配置预设 来修改它们的参数：

[af_insert]
profile-cond=speed ~= 1
profile-restore=copy
af-add=scaletempo2=search-interval=50 # Insert filter and params here.

以这种方式设置的滤镜会替换掉默认的 scaletempo2 ，而不是与其叠加。如果插入了多个能够进行音调修正的音频滤镜，那么滤镜链中只使用最后一个。有关每个可用滤镜的具体信息，详见音频滤镜部分。

--audio-device=<name>

使用给定的音频设备。这由音频输出的名称组成，例如 alsa ，后面接 / ，然后接音频输出的具体设备名称。这个选项的默认值是 auto ，它以默认设备的优先顺序尝试每个音频输出。

你可以用``–audio-device=help`` 列出音频设备。这将输出带引号的设备名称，后面接描述。设备名称是你必须传递给 --audio-device 选项的东西。音频设备的列表可以通过API使用 audio-device-list 属性来检索。

虽然该选项通常采取上述方法所显示的字符串之一，但你也可以通过手动构建它来强制大多数音频输出驱动的设备。例如 name/foobar 强制音频输出驱动的 name 使用设备 foobar 。然而， --ao 选项将严格强制一个特定的音频输出。为了避免混淆，不要同时使用 --ao 和 --audio-device

ALSA的示例

MPlayer和mplayer2要求你将ALSA设备名称中的任何 ‘,’ 替换为 ‘.’ ，任何 ‘:’ 替换为 ‘=’ 。例如，要使用名为 dmix:default 的设备，你必须这样做：

-ao alsa:device=dmix=default

在mpv中，你可以改用：

--audio-device=alsa/dmix:default

--audio-exclusive=<yes|no>

启用独占输出模式。在这种模式下，系统通常被锁定，只有mpv能够输出音频。

这只对某些音频输出有效，比如 wasapi coreaudio 和 pipewire 。其它音频输出会默默的忽略这个选项。它们要么没有独占模式的概念，要么就是缺少mpv方面的实现。

--audio-fallback-to-null=<yes|no>

如果没有音频设备被打开，它的行为就像给出了 --ao=null 一样。这和 --audio-device 结合起来很有用：如果选择的设备不存在，client API用户（或Lua脚本）可以让播放正常进行，并检查 current-ao 和 audio-device-list 属性，来做出关于如何继续的高级决策。

--ao=<driver>

指定要使用的音频输出驱动。详见 音频输出驱动 以了解可用驱动的描述。

--af=<filter1[=parameter1:parameter2:...],filter2,...>

指定一个应用于音频流的音频滤镜列表。详见 音频滤镜 以了解可用滤镜的描述。选项变体 --af-add , --af-pre 和 --af-clr 的存在可用于修改先前指定的列表，但在典型使用中不需要这些。

--audio-spdif=<codecs>

应该使用的压缩音频直通的编解码器的列表。这对传统的S/PDIF和HDMI都有效。

可能的编码有 ac3, dts, dts-hd, eac3, truehd 。可以用 , 分隔多个编码来指定。 dts 指的是低码率的DTS core，而 dts-hd 指的是DTS MA（接收器和操作系统支持的不同）。如果同时指定 dts 和 dts-hd ，它的作用等同于只指定 dts-hd

在早期的mpv版本中，你可以使用 --ad 来强制使用spdif wrapper。现在这不再有效。

警告

没有什么理由要使用这个。HDMI支持未压缩的多声道PCM，mpv支持通过FFmpeg的新DCA解码器（基于libdcadec）进行无损的DTS-HD解码。

--ad=<decoder1,decoder2,...[-]>

根据解码器的名称指定一个要使用的音频解码器的优先列表。当确定使用哪个解码器时，会选择首个与音频格式匹配的解码器。如果该解码器不可用，则使用下一个解码器。最后，它尝试所有其它没有被选项明确选择或拒绝的解码器。

列表末尾的 - 抑制了回退到不在 --ad 列表中的其它可用解码器。 + 在一个条目前面，强制使用解码器。这两种方法通常都不应该使用，因为它们破坏了正常的解码器自动选择。这两种方法都已被废弃。

示例

--ad=mp3float

优先使用FFmpeg的 mp3float 解码器，而不是所有其它的MP3解码器。

--ad=help

列出所有可用的解码器。

警告

不可能使用该选项时启用压缩音频的直通（通过SPDIF/HDMI的AC3和DTS）。请使用 --audio-spdif 代替。

--volume=<value>

设置启动时的音量。0表示无声，100表示没有音量缩小或放大。为了兼容性，可以传递负值，但会被当作0处理。

从mpv0.18.1开始，它始终控制内部混音器（又名“软件音量”）。

--volume-max=<100.0-1000.0>

以百分比为单位设置最大音量级别（默认： 130）。130 的值可以将音量调节到正常响度水平的两倍左右。

--volume-gain=<db>

以 dB 为单位设置音量增益。该值应用优先于其他音量和增益设置。

--volume-gain-max=<0.0-150.0> , --volume-gain-min=<-150.0-0.0>

以 dB 为单位设置音量增益范围（默认： min -96 dB，max 12 dB）。

--replaygain=<no|track|album>

根据存储在文件元数据中的回放增益值来调整音量增益。使用 --replaygain=no （默认），不进行调整。用 --replaygain=track ，应用于轨道增益。用 --replaygain=album ，如果有专辑，就应用于专辑增益，否则就回退到轨道增益。

--replaygain-preamp=<db>

预放大增益，单位为dB，应用于选定的回放增益（默认： 0）。

--replaygain-clip=<yes|no>

允许音量增益削波（默认： no）。如果不启用该选项，mpv 会自动降低增益以防止削波。

--replaygain-fallback=<db>

如果文件没有回放增益标签，以dB为单位应用增益。如果回放增益逻辑在某种程度上未激活，这个选项总是被应用。如果这个选项被应用，其它回放增益选项就不会被应用。

--audio-delay=<sec>

音频延迟，以秒为单位（正或负的浮点值）。正值是延迟音频，负值是延迟视频。

--mute=<yes|no|auto>

设置启动时的音频静音状态（默认： no）。

auto 是一个过时的可能值，相当于 no

另参见： --volume

--audio-demuxer=<[+]name>

当使用 --audio-file 时，使用这种音频解复用器类型。在名称前使用 + 来强制它；这将跳过一些检查。通过 --audio-demuxer=help 输出解复用器的名称。

--ad-lavc-ac3drc=<level>

选择AC-3音频流的动态范围压缩级别。 <level> 是一个从0到1的浮点值，0表示不压缩（这是默认的），1表示完全压缩（使响亮的片段更安静，反之亦然）。也可以接受高达6的值，但纯粹是实验性的。这个选项只有在AC-3流包含所需的范围压缩信息时才会显示效果。

标准规定DRC在默认情况下被启用，但mpv（和其它一些播放器）为了更好的音频质量而忽略这一点。

--ad-lavc-downmix=<yes|no>

是否要求解码器对音频声道进行下混处理（默认： no）。一些解码器，如AC-3、AAC和DTS，可以在解码时重混音频。请求的输出声道数是用 --audio-channels 选项设置的。对于在立体声系统上播放环绕声音频很有用。

--ad-lavc-threads=<0-16>

解码时使用的线程数量。线程是否真正支持取决于编码。截至撰写本文时，它只支持一些无损编码。0表示自动检测机器的核心数，并使用该数，最大为16（默认： 1）。

--ad-lavc-o=<key>=<value>[,<key>=<value>[,...]]

将AVOptions传递给libavcodec解码器。注意，欢迎打一个补丁，使o=不需要，并通过AVOption系统传递所有未知的选项。AVOptions的完整列表可以在FFmpeg手册中找到。

这是一个按键/值列表选项。详见 列表选项

--ad-spdif-dtshd=<yes|no> , --dtshd=<yes|no>

如果DTS是直通的，则使用DTS-HD。

警告

该选项和通过 --ad 启用直通的做法已过时，改用 --audio-spdif=dts-hd

--audio-channels=<auto-safe|auto|layouts>

控制哪些音频声道被输出（例如，环绕声或立体声）。有以下几种可选：

• --audio-channels=auto-safe

  使用系统的首选声道布局。如果没有（比如连接硬件设备而不是系统混音器时），就强制使用立体声。有些音频输出可能简单的接受任何布局，并自行进行降频处理。

  这是默认的。

• --audio-channels=auto

  向音频设备发送它所接受的任何内容，倾向于音频的原始声道布局。可能引起HDMI的问题（参见下方的警告）。

• --audio-channels=layout1,layout2,...

  应该允许的用 , 分隔的声道布局列表。技术上来说，这只是把滤镜链的输出调整到列表中最匹配的布局，并把结果传递给音频API。音频API有可能会选择一个不同的声道布局。

  对于直接的硬件输出，特别是通过HDMI（参见下方的HDMI警告），建议使用这种模式。

• --audio-channels=<stereo|mono>

  强制下混到立体声或单声道。这是前一项的特例。（参见下面几段的含义。）

如果给出了一个布局列表，每一项目可以是一个明确的声道布局名称（如 5.1 ），或一个声道数。声道数指的是默认的布局，例如2声道指的是立体声，6指的是5.1。

参见 ---audio-channels=help 输出，了解定义好的默认布局。这也列出了扬声器的名称，可以用来表达任意的声道布局（例如 fl-fr-lfe 是2.1）。

如果声道布局列表中只有1项，解码器将被要求产生相应的输出。这有时会触发解码器下混，这可能与正常的mpv下混不同（只有一些解码器支持重混音频，如AC-3、AAC或DTS。你可以使用 --ad-lavc-downmix=no 来使解码器始终输出其原生布局）。一个后果是， --audio-channels=stereo 会触发解码器下混，而 auto 或 auto-safe 永远不会，即使他们最终选择立体声。发生这种情况是因为，是否使用解码器下混的决定发生在音频设备被打开之前。

如果媒体文件（即解码器）的声道布局和音频输出驱动的不匹配，mpv将尝试插入一个转换滤镜。你可能需要改变系统混音器的声道布局，来达到你想要的输出，因为mpv无法控制它。在一些音频输出驱动上的另一个解决方法是使用 --audio-exclusive=yes 来完全规避系统混音器。

警告

当通过HDMI使用音频时，使用 auto 会导致问题。操作系统通常会报告所有可以通过HDMI的声道布局，即使接收器不支持它们。如果接收器得到一个不支持的声道布局，就会发生一些随机的事情，比如丢弃额外的声道，或添加噪音。

建议你设置一个你想要的布局的明确白名单。例如，大多数通过HDMI连接的A/V接收机，如果确实可以7.1，就可以通过这方式实现： --audio-channels=7.1,5.1,stereo

--audio-display=<no|embedded-first|external-first>

决定在播放音频文件时是否显示封面图片，以及优先级。它将显示找到的第一张图片，其它图片可作为视频轨道。

no:

在播放音频文件时完全禁用视频显示

embedded-first:

显示嵌入式图像和外部封面图片，优先显示内嵌图像（默认）

external-first:

显示嵌入式图像和外部封面图片，优先显示外部文件

这个选项对一般的有视频轨道的文件没有影响。

--audio-files=<files>

在观看视频时播放外部文件的音频。

这是一个路径列表选项。详见 列表选项

--audio-file=<file>

CLI/设置文件只是 --audio-files-append 的别名。每次使用这个选项将添加一个新的音轨。细节类似于 --sub-file 的工作方式。

--audio-format=<format>

选择用于从音频滤镜层输出到声卡的采样格式。 <format> 的可用值在下方的 format 音频滤镜的描述中列出。

--audio-samplerate=<Hz>

选择要使用的输出采样率（当然声卡在这方面有限制）。如果选择的采样频率与当前媒体的不同，内部的swresample音频滤镜将被插入音频滤镜层来补偿差异。

--gapless-audio=<no|yes|weak>

尝试播放连续的音频文件，在文件切换的地方没有静默或中断。默认： weak

no:

禁用无间隔音频

yes:

音频设备使用为第一个播放的文件选择的参数打开，然后为无间隔播放保持开放。这表示，如果第一个文件的采样率很低，那么后面的文件可能会被重采样到相同的低采样率，导致声音质量下降。如果你播放不同参数的文件，考虑使用比如 --audio-samplerate 和 --audio-format 的选项来明确选择共享的输出格式。

weak:

通常情况下，音频设备会保持开放（使用它首次初始化的格式）。如果解码器输出的音频格式改变了，音频设备会被关闭并重新打开。这表示通常情况下，使用相同设置编码的文件将获得无间隔音频，但在其它情况下可能不会无间隔。音频设备保持开放的确切条件是一个实现细节，可以在不同版本之间更改。目前，即使采样格式改变，设备也会被保留，但采样格式是可转换的。如果在还有音频的情况下，视频还在进行，尝试使用无间隔也是明确放弃的。

备注

这个功能是以一种简单的方式实现的，在从一个文件转到另一个文件时，依靠音频输出设备的缓冲来继续播放。如果新文件的播放开始得很慢，例如因为它是从远程网络位置播放的，或者因为你指定的缓冲设置需要时间进行初始缓冲填充，那么在新文件的播放开始之前，缓冲的音频可能会用完。

--initial-audio-sync=<yes|no>

当开始一个视频文件或在事件发生后，比如跳转，mpv默认会修改音频流，使其与视频从相同的时间戳开始，在开始时插入静音或切掉第一个样本。禁用这个选项会使播放器表现得像旧版mpv一样：视频和音频都立即开始，即使它们的开始时间戳不同，然后如果有必要，视频时间会逐渐调整，来达到正确的同步。

--audio-file-auto=<no|exact|fuzzy|all>

加载与视频文件名匹配的额外音频文件。参数指定了外部音频文件的匹配模式。

no:

不自动加载外部音频文件（默认）

exact:

加载带有音频文件扩展名的媒体文件名

fuzzy:

加载所有包含媒体文件名的音频文件

all:

加载当前目录和 --audio-file-paths 目录中的所有音频文件

--audio-file-auto-exts=ext1,ext2,...

在使用 audio-file-auto 时尝试匹配的音频文件扩展名。

这是一个字符串列表选项。详见 列表选项

--audio-file-paths=<path1:path2:...>

相当于 --sub-file-paths 选项，但用于自动加载的音频文件。

这是一个路径列表选项。详见 列表选项

--audio-client-name=<name>

播放器报告给音频API的应用程序名称。如果你想强制使用不同的音频profile（例如使用PulseAudio），或者在使用libmpv时设置你自己的应用程序名称，就很有用。

--audio-buffer=<seconds>

设置音频输出的最小缓冲区。如果音频设备可行的话，它实际上可能会创建一个更大的缓冲区。如果设备创建了一个较小的缓冲区，额外的音频将被缓存在一个额外的软件缓冲区中。

把缓冲区变大可能会使软件音量和其它滤镜的反应变慢，在播放速度变化时引入额外的问题，并在音频格式变化时屏蔽播放器。较小的缓冲区可能会导致音频丢失。

这个选项应该只用于测试。如果一个非默认值有明显的帮助，应该联系mpv的开发者。

默认： 0.2（即200ms）

--audio-stream-silence=<yes|no>

烧钱的消费级音频硬件（比如A/V接收机）经常忽略通过HDMI发送的初始音频。这可能发生在每次通过HDMI停止和恢复音频的时候。为了弥补这一点，你可以启用这个选项，在跳转时不停止和重启音频，用静默来填补空隙。同样，当暂停播放时，音频也不会停止，暂停时播放的是静音。注意，如果没有选择音轨，音频设备仍然会被立即关闭。

不是所有的音频输出驱动都支持这个。

警告

这修改了某些微妙的播放器行为，如A/V同步和负载处理。强烈建议不要启用这个选项。

--audio-wait-open=<secs>

这对与`–audio-stream-silence=yes`` 一起的使用有意义。如果给出了这个选项，播放器将在打开音频设备后等待给定的秒数，然后再发送实际的音频数据给它。如果你的昂贵的硬件会丢弃前1或2秒的音频数据，那就很有用。如果没有设置 --audio-stream-silence=yes ，这个选项很可能只是浪费时间。

字幕

备注

更改样式和位置不会对所有的字幕都起作用。基于图像的字幕（DVD, Bluray/PGS, DVB）由于基础性的原因不能改变。ASS格式的字幕通常不会被故意改变，但可以用 --sub-ass-override 来控制覆盖它们。

--sub-demuxer=<[+]name>

为 ---sub-file 强制使用的字幕解复用器类型。通过 --sub-demuxer=help 输出解复用器的名称。

--sub-lavc-o=<key>=<value>[,<key>=<value>[,...]]

将 AVOptions 传递给 libavcodec 解码器。请注意，欢迎提供补丁，使 o= 不再需要，并通过 AVOption 系统传递所有未知选项。AVOptions 的完整列表可在 FFmpeg 手册中找到。

这是一个按键/值列表选项。详见 列表选项

--sub-delay=<sec>

延迟主字幕 <sec> 秒。可以是负数。

--secondary-sub-delay=<sec>

延迟次字幕 <sec> 秒。可以是负数。

--sub-files=<file-list>, --sub-file=<filename>

添加一个字幕文件到外部字幕列表中。

如果你只使用一次 --sub-file ，该字幕文件就会默认显示。

如果 --sub-file 被多次使用，可以在运行时通过循环字幕轨道来切换到要使用的字幕。可以同时显示两个字幕：使用 --sid 选择第一个字幕索引， --secondary-sid 选择第二个索引（索引输出在终端输出的流列表里的 --sid= 之后）。

--sub-files 是一个路径列表选项（详见 列表选项 ），可以接受多个文件名，用 : (Unix) 或 ; (Windows)分隔，而 --sub-file 只接受一个文件名，但可以多次使用来添加多个文件。技术上， --sub-file 是 --sub-files-append 的CLI/设置文件的别名。

--secondary-sid=<ID|auto|no>

选择一个次级字幕流。这与 --sid 相似。如果选择了次字幕，它默认将作为顶部字幕（即在屏幕的顶部）与普通字幕一起呈现，并提供一种同时呈现双字幕的方法。

这个功能有一些相关的注意事项。例如，位图字幕将总是在其通常的位置呈现，所以选择位图字幕作为次字幕将导致字幕重叠。如果视频被禁用，次字幕永远不会在终端上显示。

备注

次字幕的样式和对任何格式化标签的解析都是禁用的。在内部，与 --sub-ass=no 相同的机制被用来剥离样式。

备注

如果主字幕流包含格式化标签，将部分字幕显示在屏幕的顶部，它将与副字幕重叠。为了防止这种情况，你可以使用 --sub-ass=no 来禁用主字幕流中的样式。

--sub-scale=<0-100>

文本字幕的字体大小系数（默认： 1）。

备注

这也影响ASS字幕，并可能导致不正确的字幕渲染。小心使用，或用 --sub-font-size 代替。

--sub-scale-by-window=<yes|no>

是否随窗口大小缩放字幕（默认： yes）。如果禁用这个功能，改变窗口尺寸不会更改字幕字体大小。

和 --sub-scale 一样，这可能会破坏ASS字幕。

--sub-scale-with-window=<yes|no>

使字幕的字体大小与窗口关联，而不是与视频关联。如果你总是想要相同的字体大小，这很有用，即使视频没有完全覆盖窗口，例如，因为屏幕和窗口的长宽不匹配（而且播放器会添加黑条）。

默认： yes

这个选项被错误的命名。与听起来令人困惑的类似选项 --sub-scale-by-window 的区别是， --sub-scale-with-window 仍然是根据窗口的近似大小进行缩放，而另一个选项则是禁用这种缩放。

只影响纯文本字幕（或者ASS，前提是如果 --sub-ass-override 设置得足够高）。

--sub-ass-scale-with-window=<yes|no>

类似 --sub-scale-with-window ，但只影响ASS格式的字幕。和 --sub-scale 一样，这可能会破坏ASS字幕。

默认： no

--embeddedfonts=<yes|no>

使用内嵌在Matroska容器文件和ASS脚本中的字体（默认： yes）。这些字体可以用于SSA/ASS字幕的渲染。

--sub-pos=<0-150>

指定字幕在屏幕上的位置。该值是字幕的垂直位置，单位是屏幕高度的%。100是原始位置，通常不是屏幕的绝对底部，而是在底部和字幕之间有一些留空。高于100的数值会使字幕进一步向下移动。

警告

如果该选项的值高于100，文本字幕（相对于图像字幕）可能会被切断。这是一个libass的限制。

这也影响ASS字幕，除了上述问题外，还可能导致不正确的字幕渲染。

使用 --sub-margin-y 可以用更好的方式来达成这个目的。

--secondary-sub-pos=<0-150>

指定次字幕在屏幕上的位置。这类似 --sub-pos 但仅用于次字幕。

--sub-speed=<0.1-10.0>

将字幕event的时间戳与给定值相乘。可以修复基于帧的字幕格式的播放速度。只影响文本字幕。

示例

--sub-speed=25/23.976 播放以帧为基础的字幕，假定帧率为23.976，速度为25FPS。

--sub-ass-style-overrides=<[Style.]Param=Value[,...]>

覆盖一些样式或脚本信息参数。

这是一个字符串列表选项。详见 列表选项

示例

• --sub-ass-style-overrides=FontName=Arial,Default.Bold=1

• --sub-ass-style-overrides=PlayResY=768

备注

使用这个选项可能会导致不正确的字幕渲染。

--sub-ass-hinting=<none|light|normal|native>

设置字体hinting类型。 <type> 可以是：

none:

无hinting（默认）

light:

FreeType autohinter，light模式

normal:

FreeType autohinter，normal模式

native:

字体的原生hinter

警告

启用hinting可能会导致错误位置的文本（在它应该与视频背景相匹配的情况下），或者降低一些不好的ASS脚本的动画的平滑度。不推荐使用这个选项，除非真的需要。

--sub-ass-line-spacing=<value>

设置SSA/ASS渲染器的行距值。

--sub-ass-shaper=<simple|complex>

设置libass使用的文本布局引擎。

simple:

只使用Fribidi，速度快，不能正确渲染某些语言

complex:

使用HarfBuzz，速度较慢，支持更多语言

complex 是默认的。如果libass没有针对HarfBuzz进行编译，libass会默默地恢复到 simple

--sub-ass-styles=<filename>

加载在指定文件中找到的所有SSA/ASS样式，并使用它们来渲染文本字幕。文件的语法与SSA/ASS的 [V4 Styles] / [V4+ Styles] 部分完全一样。

备注

使用这个选项可能导致不正确的字幕渲染。

--sub-ass-override=<yes|no|force|scale|strip>

控制是否应该应用用户风格覆盖。请注意，所有这些覆盖都尝试在某种程度上智能的识别出一个字幕是否被认为是一个“符号”。

no:

按照字幕脚本的指定渲染字幕，没有覆盖

yes:

应用所有的 --sub-ass-* 样式覆盖选项。改变这些选项的默认值可能导致不正确的字幕渲染（默认）

force:

类似 yes ，但也强制使用所有 --sub-* 选项。可以轻易破坏渲染

scale:

类似 yes ，但也应用 --sub-scale

strip:

彻底剥离字幕的所有ASS标签和样式。这相当于以前的 --no-ass / --no-sub-ass 选项

这也控制了一些位图字幕的覆盖，以及SRT等格式的HTML标签，尽管该选项的名称不同。

--secondary-sub-ass-override=<yes|no|force|scale|strip>

控制是否应该应用用户风格覆盖次字幕。这与 --sub-ass-override 类似。

默认： strip.

--sub-ass-force-margins

如果字幕是ASS格式，在有黑边的情况下，启用将顶部字幕和字幕放进黑边。

默认： no

--sub-use-margins

如果字幕是纯文本格式（或ASS格式，前提是如果 --sub-ass-override 设置得足够高），在有黑边的情况下，启用将顶部字幕和字幕放进黑边。

默认： yes

--sub-ass-vsfilter-aspect-compat=<yes|no>

在播放变形视频时拉伸SSA/ASS字幕，与传统VSFilter行为兼容。当视频以方形像素存储时，这个开关没有影响。

历史上最常用于SSA/ASS字幕格式的渲染器VSFilter具有可疑的行为，如果视频以变形格式存储，需要缩放显示时，会导致字幕也被拉伸。这种行为通常是不可取的，较新的VSFilter版本可能会有不同的行为。然而，许多现有的脚本通过在相反的方向上进行修改来补偿拉伸。因此，如果这类脚本被“正确”地显示出来，它们就不会如预期那样出现。这个开关启用模拟旧的VSFilter行为（不可取但许多现有的脚本都如此期望）。

默认情况下是启用的。

--sub-ass-vsfilter-blur-compat=<yes|no>

根据视频分辨率而不是脚本分辨率来缩放 \blur 标签的大小（默认启用）。这是VSFilter的错误，根据一些人的说法，为了兼容性的名义不再能被修复。

请注意，这是用实际的视频分辨率来计算偏移比例系数，而不是视频滤镜链或视频输出所使用的。

--sub-vsfilter-bidi-compat=<yes|no>

将隐式 bidi 检测设为 ltr 而非 auto 以匹配 ASS 的默认设置。这也会禁用 libass 的不兼容扩展。目前，这包括根据 Unicode 6.3 中引入的修订版 Unicode 双向算法进行的括号对匹配，还影响 BiDi 运行的分割和处理方式，以及 unicode 文本的软换行。

这只影响纯文本（非ASS）字幕。默认： no

--sub-ass-vsfilter-color-compat=<basic|full|force-601|no>

像(xy-)vsfilter那样损坏颜色（默认： basic）。历史上，VSFilter没有颜色空间的概念。只要使用标清视频（BT.601）的色彩空间就没有问题。但是，当一切都转向高清（BT.709）时，VSFilter仍然将RGB颜色转换为BT.601，将它们渲染到视频帧中，并将帧处理到使用BT.709来转换为RGB的视频输出。结果是字幕的颜色被损坏了。后来，在ASS格式的基础上增加了一些不好的hack，来控制颜色的损坏处理方式。

basic:

只处理BT.601->BT.709的损坏，如果字幕似乎表明这是需要的（默认）

full:

处理完整的 YCbCr Matrix header和所有libass和mpv支持的视频色彩空间。这可能会导致在极端情况下出现严重的故障，而且对于兼容性来说不是严格需要的（希望如此），这就是它不是默认的原因

force-601:

强制BT.601->BT.709的损坏，无视字幕header或视频色彩空间

no:

完全禁用颜色损坏。所有颜色都是RGB。

选择除 no 以外的任何东西都会使字幕颜色依赖于视频色彩空间，例如，理论上不可能将字幕脚本与另一个视频文件重复使用。 --sub-ass-override 选项不影响该选项的解释。

--stretch-dvd-subs=<yes|no>

在播放变形视频时拉伸DVD字幕，以便在不良的DVD上获得更好的字体效果。当视频以方形像素存储时，这个开关没有效果 —— 虽然对DVD输入来说不可能是这种情况。

许多工作室在制作DVD时倾向于使用为方形像素设计的位图字体，导致字体在DVD播放器上看起来被拉伸了。这个选项可以解决这个问题，然而代价是可能会使一些字幕错误对齐（例如公示语翻译）。

默认情况下是禁用的。

--stretch-image-subs-to-screen=<yes|no>

拉伸DVD和其它图像字幕到屏幕，忽略视频的边距。这和 --sub-use-margins 对文本字幕的效果类似，只是文本本身会被拉伸，而不仅仅是重新定位（至少在一般情况下这是不可避免的，因为理论上一个图像位图可以由单个覆盖整个屏幕的位图组成，而播放器将无法得知文本部分的确切定位）。

这个选项不能正确显示字幕。小心使用。

默认情况下是禁用的。

--image-subs-video-resolution=<yes|no>

用视频分辨率覆盖图像字幕的分辨率（默认： no）。通常情况下，字幕画布是匹配视频画布的（例如信箱式）。设置这个选项可以使用视频尺寸作为字幕画布尺寸。可以用来测试损坏的字幕，这经常发生在视频被转码时，同时试图保留旧的字幕。

--sub-ass=<yes|no>

原生渲染ASS字幕（默认： yes）。

备注

这已经被 --sub-ass-override=strip 淘汰过时。你可能还需要 --embeddedfonts=no 来获得同样的行为。另外，使用 --sub-ass-override=style 应该给出更好的效果，而不会对字幕造成太大破坏。

如果指定了 --sub-ass=no ，所有的标签和样式声明都会被剥离并在显示时被忽略。字幕渲染器使用 --sub- 选项所指定的字体样式来替代。

备注

使用 --sub-ass=no 可能会导致ASS/SSA字幕的渲染不正确或完全损坏。有时强行覆盖ASS字幕的样式是有用的，但一般情况下应该避免。

--sub-auto=<no|exact|fuzzy|all>

加载与视频文件名匹配的额外字幕文件。参数指定了外部字幕文件的匹配模式。默认情况下， exact 被启用。

no:

不自动加载外部字幕文件

exact:

加载带有字幕文件扩展名和可能的语言后缀的媒体文件名（默认）

fuzzy:

加载包含媒体文件名的所有字幕

all:

加载当前和 --sub-file-paths 目录中的所有字幕文件

--sub-auto-exts=ext1,ext2,...

在使用 --sub-auto 时尝试匹配的字幕文件扩展名。请注意，修改此列表也会影响在拖放文件时mpv识别为字幕的文件类型。

这是个字符串列表选项。详见 列表选项

--sub-codepage=<codepage>

你可以用这个选项来指定字幕代码页，uchardet将被用来猜测字符集（如果mpv没有用uchardet编译，那么 utf-8 是有效的默认值）。

这个选项的默认值是 auto ，它启用自动检测。

依次采取以下步骤来确定最终的编码页：

• 如果特定的代码页有 + ，则使用它

• 如果数据看起来像UTF-8，就假定它是UTF-8

• 如果 --sub-codepage 被设置为一个特定的代码页，则使用它

• 运行uchardet，如果成功，则使用它

• 否则，使用 UTF-8-BROKEN

示例

• --sub-codepage=latin2 如果输入不是UTF-8，则使用Latin 2

• --sub-codeepage=+cp1250 始终强制重编码为cp1250

伪代码页 UTF-8-BROKEN 是内部使用的。如果它被设置，字幕被解释为UTF-8，”Latin 1” 作为非有效UTF-8序列的后备字节。 iconv从不参与这种模式。

备注

这只适用于文本字幕文件。其它类型的字幕（特别是mkv文件中的字幕）始终被假定为UTF-8。

--sub-stretch-durations=<yes|no>

拉伸字幕持续时间，使其在下一个字幕开始时结束。这将有助于解决字幕持续时间为零的错误问题。

备注

这仅应用于文本字幕。

--sub-fix-timing=<yes|no>

调整字幕计时是为了移除字幕之间的微小间隔或重叠（如果差距小于210毫秒，间隔或重叠会被移除）。

--sub-forced-events-only=<yes|no>

启用此选项将仅显示字幕流中的强制事件。只有一些位图字幕格式（如DVD或PGS）能够在流中包含强制和非强制事件的混合。在文本字幕上启用此选项将导致不显示任何字幕（默认： no ）。

--sub-fps=<rate>

指定字幕文件的帧速率（默认：视频帧速率）。只影响文本字幕。

备注

<rate> > 视频帧率，则加快基于帧的字幕文件的字幕速度，减慢基于时间的字幕文件的速度。

另参见： --sub-speed

--sub-gauss=<0.0-3.0>

对图像字幕应用高斯模糊（默认： 0）。这有助于使像素化的DVD/Vobsubs观感更佳。除了0以外的值还可以切换到软件字幕的缩放。可能会很慢。

备注

从不应用于文本字幕。

--sub-gray

将图像字幕转换成灰度。有助于使黄色的DVD/Vobsubs观感更佳。

备注

从不应用于文本字幕。

--sub-file-paths=<path-list>

指定额外的目录来搜索匹配视频的字幕。多个目录可以用”:”（在Windows下为”;”）隔开。路径可以是相对的或绝对的。相对路径被解释为相对于视频文件的目录。如果文件是一个URL，只有绝对路径和 sub 设置子目录会被扫描。

示例

假定 /path/to/video/video.avi 被播放并且 --sub-file-paths=sub:subtitles 被指定，mpv在这些目录中搜索字幕文件：

• /path/to/video/

• /path/to/video/sub/

• /path/to/video/subtitles/

• sub 设置子目录（通常是 ~/.config/mpv/sub/ ）

这是一个路径列表选项。详见 列表选项

--sub-visibility=<yes|no>

可用于禁用字幕显示，但仍可选中和解码它。

--secondary-sub-visibility=<yes|no>

可用于禁用次字幕显示，但仍可选中和解码它。

--sub-clear-on-seek

（费解的，很少有用。）可以用来播放有重复ReadOrder字段的损坏的mkv文件。ReadOrder是Matroska式ASS字幕packets的第一个字段。它应该是唯一的，libass使用它来快速消除重复的内容。这个选项禁用了交叉跳转的字幕缓存，因此在跳转之后，libass不能消除与先前的packets具有相同ReadOrder的字幕packets。请注意，如果实际播放的不是上述损坏的 mkv 文件，启用该选项可能会导致字幕渲染错误。

--teletext-page=<1-999>

选择要解码的 teletext 页码。

这适用于 dvb_teletext 字幕流，如果FFmpeg在编译时支持它。

值 1-999 适用于单个页面。特殊值 0 （默认）匹配所有字幕页。特殊值 -1 匹配所有页面。

请注意，页面 100 是实际电传文本的默认起始页。它也是该选项先前前的默认值。

有关详情，参阅 FFmpeg 文档中的 libzvbi-teletext 部分。

默认： 0

--sub-past-video-end

在视频的最后一帧之后，如果这个选项被启用，字幕将继续根据音频的时间戳来更新。否则，最后一帧视频的字幕将停留在屏幕上。

默认：禁用

--sub-font=<name>

为本身没有指定特定字体的字幕指定使用的字体。默认是 sans-serif

示例

• --sub-font='Bitstream Vera Sans'

• --sub-font='Comic Sans MS'

备注

在渲染ASS字幕时， --sub-font 选项（以及许多其它与样式相关的 --sub- 选项）会被忽略，除非指定 --sub-ass=no 。

这被用于支持fontconfig模式。从libass0.13.0开始，它不再工作。

--sub-font-size=<size>

指定字幕字体的大小。单位是窗口高度为720时按比例计算的像素大小。实际的像素大小随着窗口高度的变化而缩放：如果窗口高度大于或小于720，文字的实际大小也会随之增加或减少。

默认： 55

--sub-back-color=<color>

参见 --sub-color 。用于字幕文本背景的颜色。你可以使用 --sub-shadow-offset 来改变它相对于文本的大小。

--sub-blur=<0..20.0>

应用于字体边框的高斯模糊系数。0表示不应用模糊（默认）。

--sub-bold=<yes|no>

格式化文本为粗体。

--sub-italic=<yes|no>

格式化文本为斜体。

--sub-border-color=<color>

参见 --sub-color 。用于字幕字体边框的颜色。

--sub-border-size=<size>

字幕字体边框的大小，以缩放的像素为单位（详见 --sub-font-size ）。值为0时禁用边框。

默认： 3

--sub-color=<color>

指定无样式的文本字幕的颜色。

颜色是以 r/g/b 的形式指定的，其中每个颜色分量被指定为0.0到1.0范围内的数字。也可以通过使用 r/g/b/a 来指定透明度，其中alpha值0表示完全透明，1.0表示不透明。如果没有给出alpha分量，颜色就是100%不透明的。

传递单个数字给选项，就可以把字幕设置为灰色，而``gray/a``的形式可以让你额外指定alpha。

示例

• --sub-color=1.0/0.0/0.0 设置字幕为不透明的红色

• --sub-color=1.0/0.0/0.0/0.75 设置字幕为不透明的红色带75%透明

• --sub-color=0.5/0.75 设置字幕为50%灰色带75%透明

另外，颜色可以被指定为RGB十六进制三元组，其形式为 #RRGGBB ，其中每个2位数组表示0（ 00 ）到255（ FF ）范围内的一个颜色值。例如， #FF0000 是红色。这与web颜色类似。Alpha是用 #AARRGGBB 来表示的。

示例

• --sub-color='#FF0000' 设置字幕为不透明的红色

• --sub-color='#C0808080' 设置字幕为50%灰色带75%透明

--sub-margin-x=<size>

字幕的左右屏幕边距，以缩放后的像素为单位（详见 --sub-font-size ）。

这个选项指定了字幕到左边的距离，以及长字幕文本到右边界被打断的距离。

默认： 25

--sub-margin-y=<size>

字幕的顶部和底部的屏幕边距，以缩放后的像素为单位（详见 --sub-font-size ）。

这个选项指定了无样式的文本字幕的垂直边距。如果你只想提高垂直字幕的位置，使用 --sub-pos

默认： 22

--sub-align-x=<left|center|right>

控制文本字幕应该对齐屏幕的哪个角落（默认： center ）

除了在 --sub-ass=no 模式下，从不应用于ASS字幕。同样，这也不适用于图像字幕。

--sub-align-y=<top|center|bottom>

垂直位置（默认： bottom ）。详见 --sub-align-x

--sub-justify=<auto|left|center|right>

控制多行字幕的对齐方式，而不考虑其对齐位置（默认： auto ，按照 --sub-align-x 的定义进行对齐）。推荐使用左对齐，使子句更易便于人眼阅读。

--sub-ass-justify=<yes|no>

如果 --sub-ass-override 没有设置为 no ，则在ASS字幕上应用 --sub-justify 所定义的对齐方式。默认： no

--sub-shadow-color=<color>

参见 --sub-color 。用于字幕文本阴影的颜色。

备注

当指定 --sub-back-color 时（或者更确切地说：当该选项没有被设置为完全透明时）被忽略。

--sub-shadow-offset=<size>

字幕文本阴影的偏移，以缩放后的像素为单位（详见 --sub-font-size ）。值为0时禁用阴影。

默认： 0

--sub-spacing=<size>

水平字幕字体的间距，以缩放后的像素为单位（详见 --sub-font-size ）。这个值会加到正常的字符间距上。允许负值。

默认： 0

--sub-filter-sdh=<yes|no>

应用滤镜去除为耳聋人或听力障碍者（SDH）添加的字幕。这是为英语准备的，但也可能部分适用于其它语言。其目的是，它可以被始终启用，所以可能不会移除所有添加的部分。

它将删除speaker标签（如 MAN:）和任何包含在 --sub-filter-sdh-enclosures 选项指定的符号（如 arentheses 或 括号 ）内的文本。请注意，括号（全宽括号和正常变体）是一种特殊情况，只会删除大写文本。要进行更多过滤，可以使用 --sub-filter-sdh-harder 选项。

默认： no

--sub-filter-sdh-harder=<yes|no>

做更难的SDH过滤（如果由 --sub-filter-sdh 启用）。也将移除speaker labels和圆括号内使用小写和大写字母的文本。

默认： no

--sub-filter-sdh-enclosures=<string>

指定一个字符串， --sub-filter-sdh 将使用该字符串删除可能的文本。由该字符串指定的字符括起来的文本将被删除。请注意，已知成对的括号字符（如 ( 或 [ ））将在内部映射到与其匹配的右侧字符，因此您只需指定左侧字符。

默认： ([（

--sub-filter-regex-...=...

设置一个正则表达式列表来匹配文本字幕，并移除任何匹配的行（默认：空）。这是一个字符串列表选项。详见 列表选项 。通常，你应该使用 --sub-filter-regex-append=<regex> ，每一个选项的使用都会附加一个新的正则表达式，而不需要对抗转义问题。

列表的项目是按顺序匹配的。如果一个正则表达式匹配，这个过程就会停止，该字幕行会被丢弃。默认情况下，匹配的文本是ASS event的 Text 字段（如果字幕格式不同，它总是被转换）。这可能包括格式化的tags。匹配是不分大小写的，但如何做到这一点取决于libc，而且很可能只在ASCII中工作。它对位图/图像字幕不起作用。在劣质操作系统上不可用（需要POSIX regex的支持）。

示例

--sub-filter-regex-append=opensubtitles\.org 过滤一些广告。

从技术上讲，使用列表进行匹配是多余的，因为你可以只使用单个组合的正则表达式。但它有助于诊断，便于使用，以及临时禁用或启用单个的滤镜。

警告

这是实验性的。语义很可能会改变，如果你使用这个，你应该准备好以后更新这个选项。想法包括用一个非常原始和小的sed子集来代替regexes，或者用一些方法来控制大小写敏感度。

--sub-filter-jsre-...=...

与 --sub-filter-regex 相同，但使用JavaScript正则表达式。共享/受所有 --sub-filter-regex-* 控制选项影响（见下文），也是试验性的。只需要JavaScript支持。

--sub-filter-regex-plain=<yes|no>

是否首先将ASS “Text” 字段转换为纯文本（默认： no）。这将剥离ASS tags并应用ASS directives，比如 \N 到换行。如果结果是多行的，那么重构表达式锚点 ^ 和 $ 会匹配每一行，但任何匹配都会丢弃所有行。

--sub-filter-regex-warn=<yes|no>

用warning日志级别记录被丢弃的行，而不是verbose（默认： no）。对测试有帮助.

--sub-filter-regex-enable=<yes|no>

是否启用regex过滤（默认： yes）。注意，如果在 --sub-filter-regex 列表中没有添加任何regexes，将此选项设置为 yes 没有任何作用。它是为了方便临时禁用或启用过滤功能。

--sub-create-cc-track=<yes|no>

对于每个视频流，创建一个closed captions轨道（默认： no）。唯一的目的是使轨道在播放开始时可以选择，而不是懒散地创建它。这只适用于 ATSC A53 Part 4 Closed Captions （显示由mpv使用 eia_608 编码的字幕轨道）。CC轨道被标记为 “default” ，并根据正常的字幕轨道选择规则来选择。然后你也可以使用 --sid 来明确选择正确的轨道。

如果视频流不包含closed captions，或者没有视频被解码，CC轨道将保持空白且不显示任何文本。

--sub-font-provider=<auto|none|fontconfig>

使用哪种libass的font provider后端（默认： auto）。 auto 将尝试使用原生font provider：Linux上的fontconfig，macOS上的CoreText，Windows上的DirectWrite。 fontconfig 会强制使用fontconfig，如果libass在构建时支持的话（如果不支持，它的行为与 none 相似）。

none font provider有效地禁用了系统字体。它仍然会试图使用内嵌的字体（除非设置了 --embeddedfonts=no ；这与所有其它font provider的行为相同），和 subfont.ttf （如果提供），和 fonts 子目录中的字体（如果提供）。（回退比其它font provider更严格，如果一个字体名称不匹配，它可能宁愿不渲染任何使用缺失字体的文本。）

--sub-fonts-dir=<path>

这个目录中的字体文件将被mpv/libass用来渲染字幕。如果你不想在系统中安装字体的话，该目录很有用。注意，此目录中的文件在被mpv使用之前会被加载到内存中。如果你有很多字体，考虑使用 fonts.conf（参见 文件 部分）来涵盖额外的mpv用户设置。

If this option is not specified, ~~/fonts will be used by default.

窗口

--title=<string>

设置窗口的标题。这用于视频窗口，如果可能，也设置音频流标题。

属性被扩展。（参见 属性扩展 ）

警告

有可能导致显著的CPU占用，这取决于使用的属性。变更窗口的标题通常是一个缓慢的操作，如果标题每一帧都在变化，播放可能会被损坏。

--screen=<default|0-32>

在多显示器配置中（例如单个桌面跨越多个显示器），这个选项告知mpv在哪个屏幕上显示视频。

注意（X11）

该选项并非适用于所有的窗口管理器。在这种情况下，你可以尝试使用 --geometry 来明确定位窗口。窗口管理器也可能提供原生功能来控制应用程序窗口应使用的屏幕。

注意（Wayland）

由于不允许放置窗口，因此该选项在 wayland 上不起作用。不过，设置该选项确实会影响 mpv 在寻找输出时的初始猜测，这对 --geometry 或 --autofit 等依赖于显示器分辨率的选项可能有用。

另参见 --fs-screen

–screen-name=<string>``。

在多显示器配置中，这个选项告知mpv根据来自视频后端的屏幕名称在哪个屏幕上显示视频。 --screen 选项中的注意事项同样适用于此。如果 --screen 是明确设置的，这个选项将被忽略，没有任何作用。

--fullscreen, --fs

全屏播放。

--fs-screen=<all|current|0-32>

在多显示器配置中（例如单个桌面跨越多个显示器），这个选项告知mpv要全屏到哪个屏幕。如果使用 current ，mpv将回退到用户提供的 screen 选项。

注意（X11）

这个选项只有在理解EWMH _NET_WM_FULLSCREEN_MONITORS 提示的窗口管理器中才能正常工作。

注意（macOS）

all 在macOS上不起作用，行为会像 current 一样。

另参见 --screen

--fs-screen-name=<string>

在多显示器配置中，这个选项告知mpv根据视频后端的屏幕名称进入全屏。 --fs-screen 选项中的注意事项同样适用于此。如果 --fs-screen 是明确设置的，这个选项将被忽略，没有任何作用。

--keep-open=<yes|no|always>

当播放或跳转超过文件的末尾，并且没有下一个文件要播放时（并且不使用 --loop ），不终止。取代的是，暂停播放器。当尝试在文件结束后跳转时，播放器将试图跳转到最后一帧。

通常情况下，这就像在文件末尾时 set pause yes 一样，除非设置了 --keep-open-pause=no 选项。

可以给出以下参数：

no:

如果当前文件结束，转到下一个文件或终止（默认）

yes:

如果当前文件是最后一个播放列表条目，不终止。相当于 --keep-open 不带参数

always:

类似 yes ，但也应用于最后一个播放列表条目之前的文件。这表示播放将永远不会自动推进到下一个文件

备注

当使用 --frames 时，这个选项不被遵循。如果绑定使用 force ，明确地跳到下一个文件，也会终止播放。

另外，如果发生错误或异常情况，播放器还是会退出。

从mpv0.6.0开始，如果播放列表中有下一个文件，或者播放列表是循环的，这就不会暂停。近似地，这将在播放器正常退出时暂停，但在实际中，有一些极端的情况不是这样的（例如， mpv --keep-open file.mkv /dev/null 将正常播放file.mkv，然后无法打开 /dev/null ，然后退出）。（在mpv0.8.0中， always 被引入，它恢复了旧的行为。）

--keep-open-pause=<yes|no>

如果设置为 no ，当 --keep-open 激活时，不会暂停，而只是在文件结束时停止，当你向前跳转时继续向后播放，直到结束时再次停止。默认： yes

--image-display-duration=<seconds|inf>

如果当前文件是图像，播放图像的时间为给定的秒数（默认： 1）。 inf 表示该文件永远保持打开（直到用户手动停止播放）。

与 --keep-open 不同，播放器不是暂停的，只是继续播放直到时间结束。（在“播放”期间，它不应该使用任何资源。）

这影响到图像文件，它被定义为只有1个视频帧且无音频。播放器可能会将某些非图像识别为图像，例如，如果 --length 被用来减少长度到1帧，或者如果你跳转到最后一帧。

这个选项不影响用于 mf:// 或 --merge-files 的帧速率。为此，请使用 --mf-fps 代替。

查看图像时，命令行输出不会跟踪播放时间，编码时也不会复制图像帧。要强制播放器进入 dumb mode 并实际计算秒数，或在编码时复制图像，需要使用 --demuxer=lavf --demuxer-lavf-o=loop=1 ，并使用 --length 或 --frames 在特定时间后停止播放。

--force-window=<yes|no|immediate>

即使没有视频也要创建一个视频输出窗口。这对假装mpv是一个GUI应用程序时很有用。目前，该窗口的大小总是960x540，并受 --geometry 、 --autofit 和类似选项的制约。

警告

窗口只在初始化后创建（以确保在视频尺寸与 --force-window 默认窗口尺寸不同的情况下，默认的窗口放置仍然有效）。如果初始化工作不完美，这可能是一个问题，比如在网络连接不好的情况下打开URL，或者打开损坏的视频文件。 immediate 模式可用于在程序启动时创建窗口，但这可能导致其它问题。

--taskbar-progress=<yes|no>

（Windows独占）启用/禁用任务栏中的播放进度渲染（Windows 7及以上）。

默认启用。

--snap-window

（Windows独占）将播放器窗口固定在屏幕边缘。

--drag-and-drop=<no|auto|replace|append|insert-next>

控制拖放在支持该功能的平台上的默认行为。 auto 将服从底层操作系统/平台给mpv的指示。通常情况下，在拖放过程中按住shift会将项目追加到播放列表中，否则新文件将完全取代旧文件。 replace 和 append 和 insert-next 总是分别强制替换和追加和插入至下一个到播放列表中。 no 禁用所有拖拽和拖放行为。

--ontop

使播放器窗口停留在其他窗口的顶部。

在Windows上，如果与全屏模式相结合，这将导致mpv被视为绕过DWM的独占全屏窗口。

--ontop-level=<window|system|desktop|level>

（macOS独占）设置一个置顶窗口的等级（默认： window）。

window:

在所有其它窗口之上

system:

在系统元素，比如任务栏、菜单栏和Dock之上

desktop:

在窗口和桌面图标后的Dekstop之上

level:

一个整数的级别

--focus-on=<never|open|all>

（macOS独占）聚焦视频窗口，使其成为特定事件的最前端窗口 (默认： open)

never:

在打开或加载新文件事件中从不聚焦窗口

open:

在创建时聚焦窗口，例如在初始化 vo 时

all:

在打开和新文件加载事件中聚焦窗口

--window-corners=<default|donotround|round|roundsmall>

（Windows独占）设置窗口圆角的偏好。

default:

由系统决定是否要圆角窗口角落

donotround:

永不使用圆角

round:

如果合适的话，圆角窗口角落

roundsmall:

如果合适的话，带有小半径圆角窗口角落

--border=<yes|no>

播放视频时带有窗口边框和装饰。由于这是默认开启的，使用 --no-border 来禁用标准的窗口装饰。

--title-bar=<yes|no>

（Windows和X11独占）使用窗口标题栏播放视频。由于默认情况下是启用的，因此使用 --title-bar=no 隐藏标题栏。 --border=no 选项优先。

--on-all-workspaces

（X11和macOS独占）在所有虚拟桌面上显示视频窗口。

--geometry=<[W[xH]][+-x+-y][/WS]> , --geometry=<x:y>

调整初始窗口的位置或大小。 W 和 H 以像素为单位设置窗口大小。 x 和 y 设置窗口位置，从屏幕的左上角到正在显示的图像的左上角，以像素计算。如果在参数后给了一个百分比符号（ % ），就会把这个值变成该方向上屏幕尺寸的百分比。位置的指定类似于标准的X11 --geometry 选项格式，例如，+10-50表示“从左边框开始放置10个像素，从下边框开始放置50个像素”，”-20+-10”表示“从右边框开始放置20个像素，从上边框开始放置10个像素”。末尾的 / 后接一个整数，表示窗口应该出现在哪个工作区（虚拟桌面）（X11独占）。

如果使用 --wid 选项指定一个外部窗口，这个选项将被忽略。

对于完全支持 --screen 的视频输出驱动，坐标是相对于 --screen 给出的屏幕的。

备注

一般而言只受GUI视频输出驱动的支持。编码时会被忽略。

注意（macOS）

在macOS上，屏幕坐标系的原点位于左下角。例如， 0:0 将把窗口放在屏幕的左下方。

注意（X11）

这个选项并不能在所有的窗口管理器中正常工作。

注意（Wayland）

Wayland 不允许客户端自行定位，因此该选项只会影响窗口大小。

示例

50:40

将窗口放在x=50, y=40的位置。

50%:50%

将窗口放置在屏幕的中央。

100%:100%

将窗口放置在屏幕的右下角。

50%

将窗口宽度设置为屏幕宽度的一半。窗口高度的设置是为了使窗口具有视频的长宽比。

50%x50%

强制窗口的宽度和高度为屏幕宽度和高度的一半。将显示黑边来补偿视频的长宽比（适用于大多数VO且带有 --keepaspect=yes ）。

50%+10+10/2

将窗口设置为屏幕宽度的一半，并将其定位在屏幕左上角下/左10个像素，在第二个工作区。

另参见 --autofit 和 --autofit-larger ，用于在不改变长宽比的情况下让窗口匹配一个给定的尺寸。

--autofit=<[W[xH]]>

将初始窗口尺寸设置为由 WxH 指定的最大尺寸，不改变窗口的长宽比。尺寸以像素为单位计算，如果数字后有百分比符号（ % ），则以屏幕大小的百分数为单位。

该选项永远不改变窗口的长宽比。如果长宽比不匹配，窗口的尺寸就会缩小，直到匹配到指定的尺寸。

窗口的位置不纳入考虑，也不被这个选项修改（窗口管理器仍然可能根据尺寸的不同来放置窗口）。使用 --geometry 来改变窗口的位置。它的效果会在这个选项之后应用。

详见 --geometry 以了解如何处理多显示器的设置。

如果你只想限制窗口的最大尺寸，而不是总是强制一个窗口尺寸，请使用 --autofit-larger 代替。

如果你想把窗口的宽度和高度都强制到一个特定的尺寸，请使用 --geometry

备注

一般而言只受GUI视频输出驱动的支持。编码时会被忽略。

示例

70%

使窗口宽度为屏幕尺寸的70%，保持宽高比。

1000

设置窗口宽度为1000像素，保持长宽比。

70%x60%

使窗口尽可能大，不超过屏幕宽度的70%，或不超过屏幕高度的60%。

--autofit-larger=<[W[xH]]>

这个选项的行为与 --autofit 完全一样，但它设置窗口的最大尺寸。

示例

90%x80%

如果视频超过屏幕宽度的90%或屏幕高度的80%，使窗口变小，直到其宽度为屏幕的90%，或高度为屏幕的80%。

--autofit-smaller=<[W[xH]]>

这个选项的行为与 --autofit 完全一样，只是它设置了窗口的最小尺寸（就像 --autofit-larger 设置的最大尺寸一样）。

示例

500x500

使窗口至少有500像素宽和500像素高（根据视频的长宽比，宽度或高度将大于500，以保持长宽比相同）。

--window-scale=<factor>

将视频窗口的大小调整为视频大小的倍数（或分数）。该选项在 --autofit 和其它选项应用之前应用（所以它们覆盖此选项）。根据操作系统和窗口管理器的不同，在窗口最大化时更改此选项可能会取消窗口最大化。如果窗口没有取消最大化，用户稍后取消窗口最大化时将应用乘数。

例如， --window-scale=0.5 将显示窗口为视频尺寸的一半。

--window-minimized=<yes|no>

视频窗口是否被最小化。如果当前视频输出驱动支持的话，设置这个将最小化或取消最小化视频窗口。注意，有些视频输出驱动可能支持最小化而不支持取消最小化（例如：Wayland）。

这个选项和 --window-maximized 是在程序启动时还是在运行时工作，以及它们是否（在运行时）被更新以反映实际的窗口状态，很大程度上取决于视频输出驱动和窗口系统。有些视频输出驱动根本没有实现它们或其中的一部分，而其它视频输出驱动可能受到窗口系统的限制（尤其是Wayland）。

--window-maximized=<yes|no>

视频窗口是否被最大化。如果当前视频输出驱动支持的话，设置这个将最大化或取消最大化视频窗口。更多详见 --window-minimized

--cursor-autohide=<number|no|always>

使鼠标指针在指定的毫秒数后自动隐藏（默认： 1000 ）。 no 将禁用光标自动隐藏功能。 always 表示光标将保持隐藏。

--cursor-autohide-fs-only

如果给出这个选项，光标在窗口模式下总是可见的。在全屏模式下，光标会根据 --cursor-autohide 显示或隐藏。

--force-rgba-osd-rendering

改变一些视频输出渲染OSD和文本字幕的方式。这并不改变字幕的外观，只对性能有影响。对于支持原生ASS渲染的视频输出（如 gpu, vdpau, direct3d ），这可能会稍快或稍慢，取决于GPU驱动和硬件。对于其它视频输出，这只会使渲染变慢。

--force-render

不论窗口的可见性，强制mpv始终渲染帧。目前只影响X11和Wayland视频输出驱动，因为只有它们具有这种优化（即其它的输出都是不考虑可见性进行渲染）。

--force-window-position

每当视频参数、视频流或文件有变化时，强制将mpv的视频输出窗口移到默认位置。这曾经是默认行为。目前只影响到X11和SDL视频输出驱动。

--auto-window-resize=<yes|no>

默认情况下，如果视频的大小发生变化，mpv会自动调整自己的大小（例如，在播放列表中向前跳转）。把这个选项设置为 no 就可以阻止该行为，因此窗口的大小不会自动改变。这个选项对 --autofit 和 --geometry 选项没有任何影响。

--keepaspect=<yes|no>

--keepaspect=no 会始终将视频拉伸到窗口大小，并禁用窗口管理器的提示的窗口强制长宽比。（在全屏模式下被忽略）

--keepaspect-window=<yes|no>

--keepaspect-window=yes （默认）会将窗口尺寸锁定为视频长宽。 --keepaspect-window=no 禁用这一行为，如果窗口的长宽和视频的长宽不匹配，则会增加黑条。这是否真的有效，取决于视频输出的后端。（在全屏模式下被忽略）

--monitoraspect=<ratio>

设置你的显示器或电视屏幕的长宽比。如果数值为0，则禁用之前的设置（例如在设置文件中）。如果启用，将覆盖 --monitorpixelaspect 的设置。

另参见 --monitorpixelaspect 和 --video-aspect-override

示例

• --monitoraspect=4:3 或 --monitoraspect=1.3333

• --monitoraspect=16:9 或 --monitoraspect=1.7777

--hidpi-window-scale=<yes|no>

根据支持的比例系数来缩放窗口大小（默认： no）。例如，如果操作系统的 DPI 缩放比例设置为 200%，则 mpv 的窗口大小将乘以 2。

--native-fs=<yes|no>

（macOS独占）使用操作系统的原生全屏机制（默认： yes）。

--show-in-taskbar=<yes|no>

（Windows和X11独占）在任务栏中显示 mpv（默认： yes）。如果设置为 “否”，在支持的窗口管理器中，mpv 将不再出现在任务栏和任务列表中，并可能被排除在 Alt+Tab 窗口切换之外。

--monitorpixelaspect=<ratio>

设置你的显示器或电视屏幕的单个像素的长宽比（默认： 1）。值1表示方形像素（对（几乎？）所有LCD都是正确的）。另参见 --monitoraspect 和 --video-aspect-override

--stop-screensaver=<yes|no|always>

在启动时关闭屏幕保护程序（或屏幕blanker和类似机制），在退出时再次打开（默认： yes）。当使用 yes 时，屏幕保护程序将在播放不激活时被重新启用。 always 将始终禁用屏幕保护程序。注意只能在有视频输出的情况下才能停止屏保（例如，有一个打开的mpv窗口）。并非所有视频输出、平台或桌面环境都支持此功能。

在 mpv 0.33.0 之前，X11 后端在未暂停时以 10 秒间隔运行 xdg-screensaver reset 以支持某些环境中的屏保抑制。这一功能在 0.33.0 中被移除，但可以通过用户脚本调用 xdg-screensaver 命令行程序。

--wid=<ID>

这告知mpv附加到一个现有的窗口。如果选择了支持该选项的视频输出驱动，它将使用该窗口进行视频输出。mpv将根据该窗口的大小缩放视频，如果视频的长宽比不同，将添加黑条来补偿。

在X11上，该ID被解释为X11上的一个 Window 。与MPlayer/mplayer2不同，mpv始终创建自己的窗口，并将wid窗口设置为父窗口。该窗口将始终重新调整大小来完全覆盖父窗口。值 0 被特别解释，mpv将直接在根窗口上绘制。

在win32上，ID被解释为 HWND 。将其作为值转换传递给 uint32_t （所有的Windows句柄都是32位的）。 mpv将创建自己的窗口，并将窗口设置为父窗口，就像X11一样。

在macOS/Cocoa上，ID被解释为 NSView* 。将其作为值转换传递给 intptr_t ，mpv将创建自己的子视图。因为macOS不支持外来进程的窗口内嵌，这只适用于libmpv，从命令行使用时会崩溃。

在Android上，ID会被解释为 android.view.Surface 。将其作为值转换传递给 intptr_t 。与 --vo=mediacodec_embed 和 --hwdec=mediacodec 一起使用，以便使用MediaCodec直接渲染，或者与 --vo=gpu --gpu-context=android 一起使用（带或者不带 --hwdec=mediacodec ）。

--window-dragging=<yes|no>

当鼠标点击在窗口上并移动指针时，移动窗口。（默认： yes）

--x11-name=<string>

为基于X11的视频输出方法设置窗口进程名称。

--x11-netwm=<yes|no|auto>

（X11独占）控制NetWM协议功能的使用。

这可能对损坏的窗口管理器有帮助，也可能没有。这提供了一些现已被移除的 --fstype 选项实现的功能。实际上，开发人员并不知道这个选项被需要到什么程度，所以欢迎反馈。

具体来说， yes 将强制使用NetWM的全屏支持，即使WM没有宣传过。这对那些故意破坏的WM很有用，比如XMonad（据说XMonad没有宣传全屏支持，是因为Flash使用它）。显然，那些想使用全屏的应用程序应该忽略NetWM的支持提示，或者提供一个变通方案。XMonad故意破坏X协议，真是太可耻了（好像X还不够坏似的）。

默认情况下，NetWM支持是自动检测的（ auto ）。

这个选项在将来可能会被移除。

--x11-bypass-compositor=<yes|no|fs-only|never>

如果设置为 yes ，则要求合成器取消对mpv窗口的重定向（默认： fs-only ）。这使用了 _NET_WM_BYPASS_COMPOSITOR 的提示。

fs-only 要求窗口管理器只在全屏模式下禁用合成器。

no 将 _NET_WM_BYPASS_COMPOSITOR 设置为0，这是EWMH规范所声明的默认值，也就是说，不做任何改变。

never 要求窗口管理器永不禁用合成器。

--x11-present=<no|auto|yes>

是否使用来自X11演示扩展的演示统计（默认： auto ）。

mpv向X11询问目前的事件，然后它可以使用这些事件进行更精确的帧呈现。这只有在使用 --video-sync=display-... 时才有效果。

auto 选项列举了自动检测的XRandr提供者。如果找到amd、radeon、intel或nouveau（标准的x86 Mesa驱动），并且没有找到nvidia，就会启用演示反馈。其它驱动不被认为可以工作，所以它们不会被自动启用。

yes 或 no 仍然可以被传递，以启用/禁用这一机制，以防你的硬件/驱动程序/等等的组合出现好/坏的行为。

--x11-wid-title=<yes|no>

当mpv嵌入X11时是否设置窗口标题（默认： no ）。

光盘设备

--cdda-device=<path>

指定用于CDDA播放的CD设备（默认： /dev/cdrom ）。

--dvd-device=<path>

指定DVD设备或ISO文件名（默认： /dev/dvd ）。你也可以指定一个包含之前直接从DVD复制文件出来的目录（例如，使用 vobcopy ）。

示例

mpv dvd:// --dvd-device=/path/to/dvd/

--bluray-device=<path>

（Blu-ray独占）指定蓝光光盘的位置。必须是一个具有蓝光结构的目录。

示例

mpv bd:// --bluray-device=/path/to/bd/

--cdda-...

这些选项可以用来调节mpv的CD音频读取功能。

--cdda-speed=<value>

设置CD的旋转速度。

--cdda-paranoia=<0-2>

设置偏移水平。0以外的值似乎会破坏第一个以外的任何轨道的播放。

0:

禁用检查（默认）

1:

只检查重叠部分

2:

完整的数据修正和验证

--cdda-sector-size=<value>

设置atomic读取大小。

--cdda-overlap=<value>

在验证过程中强制最小重叠搜索到 <value> 扇区。

--cdda-toc-offset=<value>

在寻址轨道时，在报告的数值上增加 <value> 扇区。可能是负值。

--cdda-skip=<yes|no>

（永不）接受不完美的数据重建。

--cdda-cdtext=<yes|no>

输出CD文本。这在默认情况下是禁用的，因为它会因未知原因损坏CD-ROM驱动器的性能。

--dvd-speed=<speed>

尝试限制DVD的速度（默认： 0 ，不改变）。DVD的基础速度是1385 kB/s，所以一个8x的驱动器的读取速度可以达到11080 kB/s。较慢的速度使硬盘更安静。针对观看DVD，2700 kB/s应该足够安静和快速。mpv在关闭时将速度重置为驱动器的默认值。取值超过100则表示速度的单位是kB/s。取值低于100的则表示1385 kB/s的倍数，例如 --dvd-speed=8 选择了11080 kB/s。

备注

你需要有对DVD设备的写入权限才能变更速度。

--dvd-angle=<ID>

一些DVD包含可以从多个角度观看的场景。该选项告知mpv要使用哪个角度（默认： 1）。

均衡器

--brightness=<-100-100>

调整视频信号的明度（默认： 0）。不是所有的视频输出驱动都支持。

--contrast=<-100-100>

调整视频信号的对比度（默认： 0）。不是所有的视频输出驱动都支持。

--saturation=<-100-100>

调整视频信号的饱和度（默认： 0）。用这个选项可以得到灰度输出。不是所有的视频输出驱动都支持。

--gamma=<-100-100>

调整视频信号的伽玛（默认： 0）。不是所有的视频输出驱动都支持。

--hue=<-100-100>

调整视频信号的色相（默认： 0）。用这个选项可以得到图像的彩色底片。不是所有的视频输出驱动都支持。

解复用器

--demuxer=<[+]name>

强制使用的解复用器类型。在名称前使用’+’来强制它；这将跳过一些检查。可给的解复用器名称和 --demuxer=help 输出的一样。

--demuxer-lavf-analyzeduration=<value>

分析流属性的最大长度，以秒为单位。

--demuxer-lavf-probe-info=<yes|no|auto|nostreams>

是否探测流的信息（默认： auto）。技术上讲，这控制了是否调用libavformat的 avformat_find_stream_info() 函数。通常情况下，调用它比较安全，但它也可能使启动变慢。

auto 的选择（默认）尝试对一些已知安全的白名单中的格式跳过该功能，而对所有其它格式调用。

nostreams 的选择只在文件打开后，似乎不包含流的情况下才调用（在需要调用该函数来检测流的情况下很有帮助，比如FLV文件）。

--demuxer-lavf-probescore=<1-100>

请求libavformat的最低探测分数。较低的值需要加载更少的数据（使流启动的更快），但使文件格式检测不那么可靠。可以用来强制自动检测 libavformat 的解复用器，即使 libavformat 认为检测结果不够可靠。（默认： 26）

--demuxer-lavf-allow-mimetype=<yes|no>

允许从HTTP MIME类型衍生出的格式（默认： yes）。如果从HTTP播放文件时神秘的失败，即使同样的文件在本地磁盘上能正常播放，则将此设置为 no 。

它的默认值是为了以减少打开HTTP流时的延迟。

--demuxer-lavf-format=<name>

强制使用一个指定的libavformat解复用器。

--demuxer-lavf-hacks=<yes|no>

默认情况下，其中一些格式与其它格式不同，将通过明确的检查来处理。其中大多数是对libavformat解复用器的怪异或不完美行为的补偿。传递 no 将禁用这些格式。仅用于调试和测试。

--demuxer-lavf-o=<key>=<value>[,<key>=<value>[,...]]

将AVOptions传递给libavformat解复用器。

注意，欢迎打补丁，使 o= 不需要，并通过AVOption系统传递所有未知的选项。AVOptions的完整列表可以在FFmpeg手册中找到。注意，一些选项可能与mpv的选项冲突。

这是一个按键/值列表选项。详见 列表选项

示例

--demuxer-lavf-o=fflags=+ignidx

--demuxer-lavf-probesize=<value>

在检测阶段探测的最大数据量。在MPEG-TS的情况下，这个值确定了要扫描的最大TS packets 的数量。

--demuxer-lavf-buffersize=<value>

为libavformat分配的流读取缓冲区的大小，以字节为单位（默认： 32768）。减少该尺寸可以降低延迟。注意，libavformat可能会在内部重新分配缓冲区，或者不完全使用所有的缓冲区。

--demuxer-lavf-linearize-timestamps=<yes|no|auto>

试图对解复用后的流中的时间戳重置进行线性化处理（默认： auto）。这只对单一音频流进行了测试。不知道它对视频是否正常工作（但可能不会）。请注意，无论哪种方式的实现都有点不正确，并且会引入大约1个编码帧大小的不连续性。

auto 模式对OGG音频流启用这个功能。这涵盖了OGG网络广播流的常见和恼人的情况。其中一些会在每次新歌开始时将时间戳重置为0。这破坏了mpv的可寻址缓存，它无法处理时间戳的重置。请注意，FFmpeg/libavformat的跳转API也不能处理这个问题；如果这个选项对这个问题的破坏更大，而如果它被禁用，你至少可以在流中的第一首歌内跳转。好吧，如果在mpv的缓存之外跳转，你也不会获得任何有用的东西。

--demuxer-lavf-propagate-opts=<yes|no>

传播FFmpeg级别的选项到递归打开的连接（默认： yes）。这是有必要的，因为FFmpeg会自动将这些设置应用到嵌套的AVIO上下文。另一方面，在某些情况下这可能会破坏 —— 这是FFmpeg的API，你不可能赢。

这尤其影响到 --timeout 选项和任何与 --demuxer-lavf-o 一起传递的东西。

如果这个选项在未来的某个时候被认为是不必要的，它将被删除而不另行通知。

--demuxer-mkv-subtitle-preroll=<yes|index|no>

当在某处跳转时，更努力的显示内嵌的软字幕。正常情况下，由于一些容器文件格式的设计，可能会发生在跳转目标处的字幕不显示的情况。只有在跳转之前或正好在字幕首次出现的位置时，字幕才会出现。更糟的是，字幕的出现时间往往比相关的视频帧提前很久，因此，跳转视频帧通常不会在该位置解复用字幕。

启用这个选项使解复用器在跳转目标的前方一点开始读取数据，从而使字幕正确出现。请注意，这将使跳转变慢，而且不能保证始终有效。它只在字幕足够接近跳转目标时才起作用。

只对内部的Matroska解复用器起作用。始终则对绝对跳转和精确跳转启用，这个选项只改变相对或不精确的跳转行为。

你可以使用 --demuxer-mkv-subtitle-preroll-secs 选项来指定解复用器最多应该预读多少数据，以便找到可能重叠的字幕packets。将此设置为0将有效地禁用这种预滚动机制。设置一个非常大的值会使跳转变得非常慢，而且一个非常大的值会在每次跳转时从开始到跳转目标完全重读整个文件 —— 在文件的最后，跳转会变得更慢。细节很混乱，这个值实际上是四舍五入到与前一个视频关键帧的簇。

一些文件，特别是用较新的mkvmerge版本混流的文件，有内嵌的信息，可以用来确定哪些字幕packets与跳转目标重叠。在这些情况下，mpv会将读取的数据量降到最低（尽管它仍然会读取 所有 包含第一个想要的字幕packets的集群和跳转目标之间的数据）。如果指定了 index 的选择（这是默认值），那么只有在这个信息实际可用的情况下才会进行预滚动。如果使用这种方法，跳过的最大数据量可以由 --demuxer-mkv-subtitle-preroll-secs-index 来控制（它仍然使用没有 -index 的选项的值，如果该值更高的话）。

零参见 --hr-seek-demuxer-offset 选项。 这个选项可以达到类似的效果，但是只有在精确跳转激活的情况下。它适用于任何解复用器，但会使跳转速度大幅降低，因为它必须解码音频和视频数据，而不只是跳过它们。

--demuxer-mkv-subtitle-preroll-secs=<value>

参见 --demuxer-mkv-subtitle-preroll

--demuxer-mkv-subtitle-preroll-secs-index=<value>

参见 --demuxer-mkv-subtitle-preroll

--demuxer-mkv-probe-start-time=<yes|no>

检查Matroska文件的开始时间（默认： yes）。这简单的读取第一个簇的时间戳，并假定它是开始时间。技术上来说，这也读取第一个时间戳，它可能会增加一帧的延迟（这可能与直播流有关）。

--demuxer-mkv-probe-video-duration=<yes|no|full>`

当打开文件时，跳转到文件的结尾，并检查最后一个视频packet的时间戳，并将其报告为文件的持续时间。这仅仅是为了与Haali兼容。在这种模式下，打开文件的速度可能会变慢（特别是在通过http播放时），或者对损坏的文件的处理会更糟糕。所以不要使用该选项。

yes 模式只是使用索引，并从文件的末端读取少量的块。 full 模式实际上是遍历整个文件，即使没有索引也能做出可靠的估计（比如分部的文件）。

--demuxer-rawaudio-channels=<value>

如果使用 --demuxer=rawaudio ，声道的数量（或声道布局）（默认： stereo）。

--demuxer-rawaudio-format=<value>

--demuxer=rawaudio 的采样格式（默认： s16le）。使用 --demuxer-rawaudio-format=help 来获得所有格式的列表。

--demuxer-rawaudio-rate=<value>

--demuxer=rawaudio 的采样率（默认： 44kHz）。

--demuxer-rawvideo-fps=<value>

--demuxer=rawvideo 的每秒帧数（默认： 25.0）。

--demuxer-rawvideo-w=<value>, --demuxer-rawvideo-h=<value>

--demuxer=rawvideo 的图像尺寸，以像素为单位。

示例

播放一个 raw YUV 样本：

mpv sample-720x576.yuv –demuxer=rawvideo –demuxer-rawvideo-w=720 –demuxer-rawvideo-h=576

--demuxer-rawvideo-format=<value>

--demuxer=rawvideo 的色彩空间（fourcc）的十六进制或字符串（默认： YV12 ）。

--demuxer-rawvideo-mp-format=<value>

--demuxer=rawvideo 的内部视频格式的色彩空间。使用 --demuxer-rawvideo-mp-format=help 获得可能的格式的列表。

--demuxer-rawvideo-codec=<value>

设置视频编码，而不是在使用 --demuxer=rawvideo 时选择的 rawvideo 编码。它使用与 --vd 中的编解码器名称相同的值（但它不接受解码器的名称）。

--demuxer-rawvideo-size=<value>

当使用 --demuxer=rawvideo 时帧的大小，以字节为单位。

--demuxer-max-bytes=<bytesize>

这控制了解复用器允许提前缓冲的量。一般来说，解复用器会根据需要尽量提前读取，或者根据 --demuxer-readahead-secs 的请求来进行。该选项可以用来限制最大的预读数。这限制了在文件损坏或播放不同步的情况下过多的预读取。一旦达到其中一个限制，解复用器将停止读取额外的packets（由于技术原因，这些限制仍然可以被略微超出）。

如果你得到一个packet队列溢出的警告，并且你认为用一个更大的packet队列可以正常播放，那么就把这些限制设得更高。

默认值和取值范围参见 --list-options 。 <bytesize> 选项接受后缀，比如 KiB 和 MiB

--demuxer-max-back-bytes=<bytesize>

这控制了解复用器允许保留多少过去的数据。这只有在启用缓存时才有用。

与前向缓存不同，没有控制实际缓存的秒数 —— 它将简单地使用该选项允许的内存。把这个选项设置为0将严格禁止任何后缓存，但这将导致前向寻址范围从当前播放位置之后开始的情况（因为它删除了作为寻址点的过去的packets）。

如果到达文件的末端，剩余的未使用的前向缓冲区空间将被“捐献”给后向缓冲区（除非后向缓冲区的大小被设置为0，或者 --demuxer-donate-buffer 被设置为 no ）。这仍然限制了缓存的总使用量为前向和后向缓存的总和，并有效地更好地利用了允许的总内存预算。（相反的情况不会发生：空闲的后向缓冲区永远不会被“捐献”给前向缓冲区。)

请记住，播放器中的其他缓冲区（如解码器）会导致解复用器将“未来”帧缓存在后缓冲区中，这可能会扭曲关于后缓冲区包含多少数据的印象。

参见 --list-options ，了解默认值和取值范围。

--demuxer-donate-buffer=<yes|no>

是否让后缓冲区使用前缓冲区的一部分（默认： yes）。如果设置为 yes ，则启用 --demuxer-max-back-bytes 选项描述中的“捐献”行为。这意味着后缓冲区可以使用的内存达到前和后缓冲区选项的总和，减去前缓冲区的活动大小。如果设置为 no ，选项会严格限制前和后缓冲区的大小。

注意，如果到达文件的末尾，缓冲的数据保持不变，即使你在缓冲区内回头跳转。这是因为只有在读取新的数据时才会减少后缓冲区。

--demuxer-seekable-cache=<yes|no|auto>

调试选项，控制跳转是否可以使用解复用器缓存（默认： auto）。通常你不需要设置这个选项；如果 --cache 被设置为 yes （或者如果 --cache=auto ，则暗示为 yes ），默认的 auto 会做正确的事情并启用缓存跳转。

如果启用，短的寻道偏移将不会触发低级别的解复用器寻道（这意味着，例如可以避免缓慢的网络往返或FFmpeg寻道错误）。如果跳转不能在缓存范围内发生，将触发一个低级别的寻址。在缓冲区外跳转将开始一个新的缓冲范围，但如果解复用器表现出某些不被支持的行为，可能丢弃旧的缓冲范围。

特殊值 auto 表示在与 --cache-secs 相同的情况下 yes （即当流出现在网络或流缓存被启用时）。

--demuxer-thread=<yes|no>

在一个单独的线程中运行解复用器，并让它预取一定数量的packets（默认： yes）。启用这个功能可以使播放更顺畅，启用预取等功能，并防止网络卡住使播放器冻结。另一方面，它可能会增加开销，或者后台预取会占用CPU资源。

不建议禁用这个选项。只在调试时使用它。

--demuxer-termination-timeout=<seconds>

播放器应该等待多少秒来关闭解复用器（默认： 0.1）。在强行关闭流层之前，播放器将最多等待这么长的时间。强制关闭通常意味着网络I/O没有机会优雅地关闭它的连接（当然操作系统仍然可以正确地关闭TCP连接），可能会导致恼人的信息被记录下来，在某些情况下，会使远程服务器混乱。

这个超时通常只在加载已经正常完成的情况下应用。如果加载被用户中止，或者在某些极端的情况下，比如在播放过程中移除来自网络的外部音轨，强制关闭始终会被使用。

--demuxer-readahead-secs=<seconds>

如果 --demuxer-thread 被启用，这控制了解复用器应该提前多少秒缓冲（默认： 1）。只要没有packet的时间戳差异高于相对于返回给解码器的最后一个packet的预读量，解复用器就会保持读取。

注意，启用缓存（如 --cache=yes ，或者如果输入被认为是网络流，并使用 --cache=auto ），这个选项几乎会被忽略（ --cache-secs 将覆盖这个选项。技术上讲，使用两个选项的最大值）。

这个选项的主要目的是限制本地播放的预读，因为一个大的预读值在这种情况下没有太大作用。

（这个值往往是模糊的，因为许多文件格式不存储线性时间戳。）

--demuxer-hysteresis-secs=<seconds>

一旦达到解复用器的限制（ --demuxer-max-bytes , --demuxer-readahead-secs 或 --cache-secs ），该值可以用来指定在解复用器再次提前缓冲前的滞后时间。这指定了从当前播放位置开始，在解复用器继续提前缓冲之前，需要在缓存中剩余的最大秒数。

例如，如果指定的值为 10 秒，则解复用器会提前缓冲到解复用器的上限，直到缓存中只剩下10秒的内容时才会再次开始提前缓冲。

这可以显著节省功耗，并通过使解复用器一次只缓冲几块内容而不是不停地缓冲以保持缓冲区的填充来减少负载。

如果你想省电并减少负载，把它设置成一个比 --cache-secs 或 --demuxer-readahead-secs 低得多的数值。如果对于一个给定的数据流，需要很长的时间来缓冲任何东西（比如从一个非常慢的磁盘上读取），那么应该提高滞后值进行补偿。

默认值是0秒，这将禁用缓存滞后。一个10秒的值可能对大多数情况都有效。

--prefetch-playlist=<yes|no>

在当前项目的播放结束时预取下一个播放列表项目（默认： no）。

这不会将下一个URL的视频数据预填充到缓存中。预取的视频数据只受当前的播放列表条目支持，并取决于解复用器缓存设置（默认启用）。这只用在当前的URL被完全读取后，打开下一个播放列表的URL。

这对由 youtube-dl 封装器解析的URL 没 效果，也不会起作用。

如果使用特定文件的选项，或者在预取开始和下一个文件播放之间的时间窗口内改变选项，这可能会产生微妙错误的结果。

这可能偶尔会做出错误的预取判定。例如，它不能预测你是否在播放列表中回退，并假定你不会编辑播放列表。

它是高度实验性的。

--force-seekable=<yes|no>

如果播放器认为媒体文件是不可跳转的（例如，从管道中播放，或者是http流的服务器不支持范围的请求），跳转将被禁用。这个选项可以强行启用它。对于缓存中的跳转，有很大的成功机会。

--demuxer-cache-wait=<yes|no>

在开始播放之前读取数据，直到到达文件的末端，或者解复用器缓存达到最大容量。只有当这一切完成后，播放才开始。这故意发生在用 --start 触发的初始搜索之前。这不会改变初始缓存后的任何运行时行为。如果文件不能被完全缓存，该选项无用。

--rar-list-all-volumes=<yes|no>

当打开多卷rar文件时，打开所有卷以创建一个包含文件的完整列表（默认： no）。如果禁用，只有标题位于第一卷内的存档条目被列出（因此在用mpv打开.rar文件时播放）。这样做可以加快打开速度，而且典型的白痴用例，即播放包含单个媒体文件的未压缩的多卷rar文件，也变得更快。

打开的速度仍然很慢，因为出于未知的、愚蠢的和不必要的原因，libarchive在播放主文件时还是会打开所有卷，尽管mpv还没有迭代出任何存档条目。

--directory-mode=<auto|lazy|recursive|ignore>

在打开目录时，可以选择以延迟方式、递归方式或根本不打开子目录。默认为 auto ，如果使用 --shuffle ，则表现得像 recursive ，否则表现得像 lazy 。

输入

--native-keyrepeat=<yes|no>

使用系统设置的按键重复的延迟和速率，而不是 --input-ar-delay 和 ``–input-ar-rate``（默认： no）这是否应用取决于视频输出的后端和它如何处理键盘输入。不应用于终端输入。

--native-touch=<yes|no>

（Windows独占）对于为不支持触控的客户端（如 Windows）发送模拟鼠标输入的平台，使用系统本地触摸事件，而不是接收模拟鼠标事件（默认： no）。这对这些平台的多点触控支持是必需的。

请注意，该选项对其他平台没有影响：要么 mpv 不支持原生触控，要么该平台不提供接收模拟鼠标输入的选项（因此原生触控终处于启用状态，例如 Wayland）。

--input-ar-delay

在开始前自动重复一个按键的延迟，以毫秒为单位（默认： 200）设为0以禁用。

--input-ar-rate

在自动重复中每秒产生的按键按压的数量（默认： 40）。

--input-conf=<filename>

指定输入设置文件，而不是mpv设置目录中的默认位置（通常是 ~/.config/mpv/input.conf ）。

--input-default-bindings=<yes|no>

使用默认等级的（“弱”）按键键绑定（默认： yes）。这些是设置文件比如 input.conf 可以覆盖的绑定。目前它影响到内置的按键绑定，以及脚本使用 mp.add_key_binding 绑定的按键（但不包括 mp.add_forced_key_binding ，因为这会覆盖 input.conf ）。

--input-builtin-bindings=<yes|no>

在启动时加载内置的按键绑定（默认： yes）。这个选项只在(lib)mpv初始化时应用，如果使用的话，以后就不可能再启用它们。可能对libmpv clients有用。

--input-cmdlist

输出所有可以绑定到按键的命令。

--input-commands=<cmd1,cmd2,...>

定义供 mpv 运行的命令列表。语法格式与 input.conf 相同，但开头没有按键绑定参数。如果在启动时设置此选项，命令将在音频和视频播放开始后运行（在无文件的idle模式下，将立即运行）。在运行时更改值时，命令也将尽快运行。

这是一个按键/值列表选项。详见 `List Options`_

示例

--input-commands="playlist-play-index 1,set ao-volume 40"

将播放列表索引设置为 1，将ao-volume设置为 40

--input-doubleclick-time=<milliseconds>

将连续两次按键识别为一次双击的时间，以毫秒为单位（默认： 300）。

--input-keylist

输出所有可以与命令绑定的按键。

--input-key-fifo-size=<2-65000>

指定缓冲按键events的FIFO的大小（默认： 7）。如果它太小，一些events可能会丢失。设置为一个非常大的值的主要缺点是，如果你按住一个按键触发了一些特别慢的命令，那么播放器在处理所有排队的命令时可能无法响应。

--input-test

输入测试模式。mpv不会在按键时执行命令，而是在OSD上显示按键和绑定的命令。必须和一个虚拟视频一起使用，一般的退出播放器的方法将不起作用（通常退出的按键绑定将只显示在OSD上，就像其它的绑定一样）。参见 INPUT.CONF

--input-terminal=<yes|no>

--input-terminal=no 阻止播放器从标准输入读取按键events。在从标准输入读取数据时很有用。当在命令行中发现 - 时，这将自动启用。有些情况下，你必须手动设置，例如，如果你打开 /dev/stdin （或你系统中的等价物），在播放列表中使用stdin或打算以后通过loadfile或loadlist输入命令从stdin读取数据。

--input-ipc-server=<filename>

启用IPC支持并在给定的路径上创建监听套接字。

在Linux和Unix上，给定的路径是一个常规的文件系统路径。在Windows上，使用命名的pipes，所以路径指的是pipe namespace（ \\.\pipe\<name> ）。如果缺少 \\.\pipe\ 前缀，mpv会在创建pipe前自动添加，所以 --input-ipc-server=/tmp/mpv-socket 和 --input-ipc-server=\\.\pipe\tmp\mpv-socket 对于Windows上的IPC是等效的。

详见 JSON IPC

--input-ipc-client=fd://<N>

连接单个IPC client到给定的FD。这与 --input-ipc-server 有点相似，只是没有创建套接字，而传递的FD被当作从 accept() 收到的套接字连接。在实践中，你可以传递一个由 socketpair() 创建的FD，或者一个pipe。在这两种情况下，你必须确保FD实际上是由mpv继承的（不要设置POSIX的 CLOEXEC 标志）。

当连接被关闭时，播放器就会退出。

这有点类似于被移除的 --input-file 选项，只是它只支持整数FDs，而不能打开实际的路径。

示例

--input-ipc-client=fd://123

备注

在Windows上不适用，将来也不适用。

警告

在运行时写入 input-ipc-server 选项将为 input-ipc-client 选项启动另一个IPC client句柄实例，因为初始化是捆绑的，这个东西很愚蠢。这是一个错误。在运行时写入到 input-ipc-client 将为新的值启动另一个IPCclient句柄，而不停止旧的句柄，即使FD值是相同的（但字符串是不同的，例如，由于whitespace）。这不是一个错误。

--input-gamepad=<yes|no>

启用/禁用SDL2游戏手柄支持。默认禁用。

--input-cursor=<yes|no>

允许mpv接收由视频输出驱动报告的指针events。必需要使用OSC，或在选中DVD菜单中的按钮。支持与否取决于使用的视频输出驱动。

--input-cursor-passthrough=<yes|no>

告诉后端窗口系统允许指针事件穿过mpv窗口。这使得mpv下面的窗口能够接收指针事件，就好像mpv窗口从未存在过一样。

--input-media-keys=<yes|no>

在mpv可以选择接收媒体按键或让系统处理媒体按键的系统中 —— 这个选项控制mpv是否应该接收媒体按键。

默认： yes（除了libmpv）。macOS和Windows独占，因为在其它地方mpv没有选择 —— 系统决定是否将媒体按键发送给mpv。例如，在X11或Wayland上，没有实现系统级的媒体按键。当mpv窗口被聚焦时，媒体按键是否起作用是由实现定义的。

--input-preprocess-wheel=<yes|no>

预处理 WHEEL_* 事件，以便在水平或垂直方向滚动时，即使两个方向同时滚动，也不会产生另一个方向的事件（默认： yes）。

这种预处理有利于防止在使用默认键绑定的触摸板上滚动改变音量时意外寻址。由于使用了死区机制，禁用预处理可以进行对角滚动（如平移），并有可能减少输入延迟。

请注意，禁用预处理不会影响操作系统/驱动程序在将这些事件发送到 mpv 之前所做的任何过滤（如果有的话）。

--input-right-alt-gr=<yes|no>

（macOS和Windows独占）将右Alt键作为Alt Gr来产生特殊字符。如果禁用，将右键Alt算作Alt修饰键。默认启用。

--input-vo-keyboard=<yes|no>

对于不能参与正确的键盘输入调度的视频输出驱动，禁用所有键盘输入。可能不会影响所有的视频输出。一般而言只对内嵌有用。

在X11上，一个启用了输入功能的子窗口会抓取所有的键盘输入，只要它是 1.一个焦点窗口的子窗口，并且 2.鼠标在子窗口内。 它可以从嵌入mpv窗口的应用程序中窃取所有的键盘输入，另一方面，如果鼠标在mpv窗口之外，即使mpv有焦点，mpv窗口也不会收到任何输入。现代的toolkits可以绕过这个奇怪的X11行为，但是天真的内嵌外部的窗口会破坏它。

唯一合理处理这个问题的方法是使用XEmbed协议，它是为了解决这些问题而设计的。GTK提供 GtkSocket ，它支持XEmbed。Qt似乎没有提供任何在较新版本中的工作的东西。

如果embedder支持XEmbed，输入应该在默认设置下工作，并且禁用这个选项。注意 input-default-bindings 在libmpv中也是默认禁用的 —— 如果你想要mpv的默认按键绑定，应该启用它。

--input-touch-emulate-mouse=<yes|no>

当启用多点触控支持时（平台要求或 --native-touch 启用），会模拟触控事件中的鼠标移动和按键操作（默认： yes）。这对于读取不支持 --native-touch=no 的平台（如 Wayland）鼠标位置的鼠标键绑定和脚本的兼容性非常有用。

OSD

--osc=<yes|no>

是否加载屏显式控制器（默认： yes）。

--osd-bar=<yes|no>

启用OSD条的显示（默认： yes）。

你可以在input.conf中使用 osd- 前缀在每条命令的基础上进行设置，参见 输入命令前缀 。如果你想完全禁用OSD，使用 --osd-level=0

--osd-on-seek=<no,bar,msg,msg-bar>

设置在跳转过程中OSD上显示的内容。默认： bar

你可以在input.conf中使用 osd- 前缀在每条命令的基础上进行设置，参见 输入命令前缀

--osd-duration=<time>

设置OSD信息的持续时间，以ms为单位（默认： 1000）。

--osd-font=<name>

指定OSD使用的字体。默认： sans-serif

示例

• --osd-font='Bitstream Vera Sans'

• --osd-font='Comic Sans MS'

--osd-font-size=<size>

指定OSD的字体大小。详见 --sub-font-size

默认： 55

--osd-msg1=<string>

在OSD等级1（默认可见）的OSD上显示这个字符串作为信息。该信息默认是可见的，只要没有其它信息挡住它，并且OSD等级无改变（参见 --osd-level ）。扩展属性；参见 属性扩展

--osd-msg2=<string>

类似于 --osd-msg1 ，但用于OSD等级2。如果这是一个空字符串（默认），那么将显示播放时间。

--osd-msg3=<string>

类似于 --osd-msg1 ，但用于OSD等级3。如果这是一个空字符串（默认），那么就会显示播放时间、持续时间和一些更多的信息。

当使用 show-progress 命令时（默认映射到 P ），以及在input.conf中使用 --osd-on-seek 或 osd- 前缀（参见 输入命令前缀 ）进行跳转时，这将覆盖 --osd-level=3 的状态文本。

--osd-status-msg 是一个遗留的等效选项（但有一个微小差异）。

--osd-status-msg=<string>

在播放过程中显示一个自定义的字符串而不是标准的状态文本。当使用 show-progress 命令时（默认映射到 P ），以及在input.conf中使用 --osd-on-seek 或 osd- 前缀（参见 输入命令前缀 ）进行跳转时，这将覆盖 --osd-level=3 的状态文本。扩展属性。参见 属性扩展

这个选项已经被 --osd-msg3 取代。唯一的区别是该选项隐含了 ${osd-sym-cc} 。如果 --osd-msg3 不是空的，这个选项将被忽略。

--osd-playing-msg=<string>

当播放开始时在OSD上显示一条信息。字符串被扩展为属性，例如： --osd-playing-msg='file: ${filename}' 将显示信息 file: ，后方接的是一个空格和当前播放的文件名。

参见 属性扩展

--osd-playing-msg-duration=<time>

设置 osd-playing-msg 的持续时间，以毫秒为单位。如果不设置， osd-playing-msg 将在以 osd-duration 设置的时间内停留在屏幕上。

--osd-bar-align-x=<-1-1>

OSD条的位置。-1是最左边，0是中间，1是最右边。允许使用小数值（如0.5）。

--osd-bar-align-y=<-1-1>

OSD条的位置。-1是顶部，0是中间，1是底部。允许使用小数值（如0.5）。

--osd-bar-w=<1-100>

OSD条的宽度，以屏幕宽度的百分比为单位（默认： 75）。50的值表示条的宽度是屏幕的一半。

--osd-bar-h=<0.1-50>

OSD条的高度，以屏幕高度的百分比为单位（默认： 3.125）。

--osd-bar-border-size=<size>

OSD条边框的大小，按比例缩放像素 （详见 --sub-font-size ）

默认： 0.5

–osd-back-color=<color>``。

参见 --sub-color 。用于OSD文本背景的颜色。

--osd-blur=<0..20.0>

应用于OSD条边框的高斯模糊系数。0表示不应用模糊（默认）。

--osd-bold=<yes|no>

格式化文本为粗体。

--osd-italic=<yes|no>

格式化文本为斜体。

--osd-border-color=<color>

参见 --sub-color 。用于OSD字体边框的颜色。

--osd-border-size=<size>

OSD字体边框的大小，以像素为单位（详见 --sub-font-size ）。值为0时禁用边框。

默认： 3

--osd-color=<color>

指定用于OSD的颜色。详见 --sub-color

--osd-fractions

显示带小数点的秒数的OSD时间（精度为毫秒）。有助于查看视频帧的精确时间戳。

--osd-level=<0-3>

指定OSD应该以何种模式启动。

0:

OSD被完全禁用（仅剩字幕）

1:

启用（仅在用户交互时显示）

2:

启用 + 默认可见当前时间

3:

启用 + --osd-status-msg （默认为当前时间和状态）

--osd-margin-x=<size>

OSD的左右屏幕边距，以缩放后的像素为单位（详见 --sub-font-size ）。

这个选项指定了OSD与左边的距离，以及从右边框到长OSD文本的断开距离。

默认： 25

--osd-margin-y=<size>

OSD的顶部和底部屏幕边距，以缩放后的像素为单位（详见 --sub-font-size ）。

这个选项指定了OSD的垂直边距。

默认： 22

--osd-align-x=<left|center|right>

控制OSD应该对齐屏幕的哪个角（默认： left ）。

--osd-align-y=<top|center|bottom>

垂直位置（默认： top ）。详见 --osd-align-x

--osd-scale=<factor>

OSD字体大小的乘数，与 --osd-font-size 的值相乘。

--osd-scale-by-window=<yes|no>

是否随窗口尺寸缩放OSD（默认： yes）。如果这个选项被禁用， --osd-font-size 和其它使用缩放后像素的OSD选项总是以实际像素为准。其影响是，改变窗口尺寸不会改变OSD字体大小。

--osd-shadow-color=<color>

参见 --sub-color 。用于OSD阴影的颜色。

备注

当指定 --osd-back-color 时被忽略（或者更确切地说：当该选项没有设置为完全透明时）。

--osd-shadow-offset=<size>

OSD阴影的位移，以缩放后的像素为单位（详见 --sub-font-size ）。值为0时禁用阴影。

默认： 0

--osd-spacing=<size>

水平OSD/字幕字体的间距，以缩放后的像素为单位（详见 --sub-font-size ）。这个值会加到正常的字母间距上。允许负值。

默认： 0

--video-osd=<yes|no>

在视频窗口上启用OSD渲染（默认： yes）。这可用于终端OSD是优先的情况。如果你只是想禁用所有的OSD渲染，使用 --osd-level=0

它不影响字幕或由脚本创建的覆盖层（特别的是，OSC需要用 --osc=no 来禁用）。

这个选项在某种程度上是实验性的，将来可能会被另一种机制所取代。

--osd-font-provider=<...>

参见 --sub-font-provider 了解可接受的值。注意，不同于字幕，OSD从不使用来自媒体文件的内嵌字体。

--osd-fonts-dir=<path>

参见 --sub-fonts-dir 了解详情。默认为 ~~/fonts

屏幕截图

--screenshot-format=<type>

设置用于保存屏幕截图的图像文件类型。

可用的选择：

png:

PNG

jpg:

JPEG（默认）

jpeg:

JPEG（JPG的别名）

webp:

WebP

jxl:

JPEG XL

--screenshot-tag-colorspace=<yes|no>

用适当的色彩空间标记屏幕截图。默认 yes

请注意，并非所有格式都支持此功能。当不支持或禁用此选项时，截图将在写入前转换为 sRGB。

--screenshot-high-bit-depth=<yes|no>

如果可能的话，用与源视频相似的位深写入截图（默认： yes）。这对PNG来说特别有意思，因为这有时会触发写入16位的PNG，使得文件体积很大。如果使用16比特，这也会在结果文件中内含一个未使用的alpha通道。

--screenshot-template=<template>

指定用于保存屏幕截图的文件名模板。该模板指定了不含扩展名的文件名，并可以包含格式说明符，在截屏时将被替换。默认情况下，模板是 mpv-shot%n ，这会导致产生类似例如 mpv-shot0012.png 的文件名。

模板可以用相对或绝对路径开始，来指定应保存截图的目录位置。

如果最终的截图文件名指向一个已经存在的文件，该文件将不会被覆盖写入。或者如果模板包含 %n ，那么就使用不同的、新生成的文件名保存，否则截图将不被保存。

允许的格式说明符：

%[#][0X]n

一个序列数字，用零填充，长度为X（默认： 04）。例如，传递格式 %04n 将产生的第12张截图是 0012 。每次截图或文件已经存在的情况下，数字会递增。长度 X 必须在0-9的范围内。带了可选的#符号，mpv将使用最低的可用数字。例如，如果你截了三张图 —— 0001, 0002, 0003 —— 并删除了前两张，接下来的两张截图就不会是0004和0005，而是0001和0002。

%f

当前播放视频的文件名。

%F

与 %f 相同，但剥离文件扩展名，包括点。

%x

当前播放视频的目录路径。如果视频不在文件系统上（但例如 http:// ），这将扩展为一个空字符串。

%X{fallback}

与 %x 相同，但如果视频文件不在文件系统上，返回 {...} 内的回退字符串。

%p

当前播放时间，格式与OSD中使用的相同。其结果是一个 “HH:MM:SS” 形式的字符串。例如，如果视频处于5分34秒的时间位置， %p 将被替换为 “00:05:34” 。

%P

类似于 %p ，但扩展为以毫秒为单位的播放时间。它的格式是 “HH:MM:SS.mm”，其中 “mmm” 是播放时间的毫秒部分。

备注

这是一个获得独特的每帧时间戳的简单方法（帧数序号会更直观，但不容易被实现，因为容器格式通常使用时间戳来识别帧）。

%wX

使用格式化的字符串 X 指定当前播放时间。 %p 就像 %wH:%wM:%wS ， %P 就像 %wH:%wM:%wS.%wT

有效的格式说明符：

%wH

时（用0到2位数填充）

%wh

时（无填充）

%wM

分（00-59）

%wm

总时间（包括小时，与 %wM 不同）

%wS

秒（00-59）

%ws

总秒数 (包括小时和分钟)

%wf

类似 %ws ，但作为浮点数

%wT

毫秒（000-999）

%tX

使用格式化的 X 指定当前的本地日期/时间。这个格式说明符在内部使用UNIX的 strftime() 函数，并插入传递 “%X” 到 strftime 的结果。例如， %tm 将插入当前月份的数字。你不得不使用多个 %tX 说明符来建立一个完整的日期/时间字符串。

%{prop[:fallback text]}

插入输入属性 ‘prop’ 的值。例如： %{filename} 与 %f 相同。如果该属性不存在或不可用，将插入一个错误文本，除非指定一个回退文本。

%%

替换为 % 字符本身。

--screenshot-dir=<path>

存储屏幕截图在此目录中。该路径与 --screenshot-template 生成的文件名结合。如果模板文件名已经是绝对的，该目录将被忽略。

--screenshot-directory 是 --screenshot-dir 的别名。

如果该目录不存在，它将在首张截图时被创建。如果它不是一个目录，在尝试写入截图时将产生一个错误。

这个选项在默认情况下没有设置，因此将写入截图到mpv启动的目录中。在伪GUI模式下（参见 伪GUI模式 ），这被设置为桌面。

--screenshot-jpeg-quality=<0-100>

设置JPEG的质量等级。越高表示质量越好。默认： 90

--screenshot-jpeg-source-chroma=<yes|no>

写入与视频相同的色度抽样到JPEG文件（默认： yes）。如果禁用，将使用libjpeg的默认值。

--screenshot-png-compression=<0-9>

设置PNG压缩等级。越高表示更好的压缩率。这将影响写入截图文件的体积和所用时间。太高的压缩率可能会占用足够的CPU时间而打断播放。默认： 7

--screenshot-png-filter=<0-5>

设置在PNG压缩前应用的滤镜。0是无，1是 “sub” ，2是 “up” ，3是 “average” ，4是 “Paeth” ，5是 “mixed” 。这影响到可以达成的压缩等级。对于大多数图像， “mixed” 实现了最佳的压缩率，因此它是默认的。

--screenshot-webp-lossless=<yes|no>

写入无损的WebP文件。如果设置了这个选项， --screenshot-webp-quality 将被忽略。默认： no

--screenshot-webp-quality=<0-100>

设置WebP质量等级。越高表示质量越好。默认： 75

--screenshot-webp-compression=<0-6>

设置WebP的压缩等级。越高表示更好的压缩率，但需要更多的CPU时间。注意，在使用有损的WebP文件时，这也会影响截图质量。默认： 4

--screenshot-jxl-distance=<0-15>

设置JPEG XL的Butteraugli距离。更低意味着更好的质量。无损是 0.0 ，而 1.0 大约相当于摄影内容的JPEG质量90。对于“视觉无损”的屏幕截图，使用 0.1 。默认： 1.0

--screenshot-jxl-effort=<1-9>

设置JPEG XL的压缩力度。更高的力度（通常）意味着更好的压缩度，但需要更多的CPU时间。默认： 4

--screenshot-avif-encoder=<encoder>

指定 libavcodec 在编码 avif 截图时使用的 AV1 编码器。

默认： libaom-av1

--screenshot-avif-pixfmt=<format>

为 libavcodec 编码器指定像素格式。默认为空，这样 mpv 就可以选择一个接近源格式的格式。

--screenshot-avif-opts=key1=value1,key2=value2,...

为所选编码器指定 libavcodec 选项。更多信息请查阅 FFmpeg 文档。

默认： usage=allintra,crf=0,cpu-used=8

注意：默认值只保证适用于 libaom-av1 编码器。上述选项可能对其它编码器无效或不是最佳选择。

这是一个按键/值列表选项。详见 `List Options`_

示例

“--screenshot-avif-opts=crf=23,aq-mode=complexity”

将 crf 设置为 23，将量化（aq-mode）设置为基于复杂度。

--screenshot-sw=<yes|no>

是否对屏幕截图使用软件渲染（默认： no）。

如果设置为no（目前vo_gpu和vo_gpu_next独占），屏幕截图将由当前的视频输出驱动渲染。这样做的好处是，这将（可能）始终像在视频窗口中显示的那样，因为渲染时使用的是相同的代码。但是由于渲染器需要重新初始化，这可能会很慢，而且可能打断播放。

如果设置为yes，则使用软件缩放器将视频转换为RGB（或目标截图要求的任何内容）。在这种情况下，转换将在一个单独的线程中运行，可能不会打断播放。软件渲染器可能缺乏一些职能，比如HDR渲染。如果使用``window``模式，图像也将在软件中进行缩放，这可能无法准确反映实际可见的结果。

软件缩放器

--sws-scaler=<name>

指定与 --vf=scale 一起使用的软件缩放器算法。这也影响到缺乏硬件加速的视频输出驱动，例如 x11 。另参见 --vf=scale

要获取可用的缩放器列表，请运行 --sws-scaler=help

默认： bicubic

--sws-lgb=<0-100>

软件缩放器的高斯模糊滤波（亮度）。参见 --sws-scaler

--sws-cgb=<0-100>

软件缩放器的高斯模糊滤波（色度）。参见 --sws-scaler

--sws-ls=<-100-100>

软件缩放器的锐化滤波（亮度）。参见 --sws-scaler

--sws-cs=<-100-100>

软件缩放器的锐化滤波（色度）。参见 --sws-scaler

--sws-chs=<h>

软件缩放器的色度水平偏移。参见 --sws-scaler

--sws-cvs=<v>

软件缩放器的色度垂直偏移。参见 --sws-scaler

--sws-bitexact=<yes|no>

未知的功能（默认： no）。请参考libswscale的源代码。就libswscale API而言，其主要目的是为所有平台上的相同输入产生完全相同的输出（输出在任何地方都有相同的“位深”，因此是 “bitexact”）。通常禁用该优化。

--sws-fast=<yes|no>

允许优化以助于提高性能，但会降低质量（默认： no）。

像 drm 和 x11 这样的视频输出驱动将从使用 --sws-fast 中获益良多。你可能需要设置其它选项，如 --sws-scaler 。内建的 sws-fast 配置预设应用了该选项和其它一些选项，以获得性能提升而降低质量。另参见 --sws-allow-zimg

--sws-allow-zimg=<yes|no>

允许使用zimg（如果使用内部swscale包装器的组件明确允许这样做）（默认： yes）。在这种情况下，如果内部的zimg包装器支持输入和输出的格式，就 可能 使用zimg。如果这些条件中的任一不适用，它将默默的或无声的回退到libswscale。

如果使用了zimg，其它的 --sws- 选项将被忽略，而使用 --zimg- 类的选项来取代。

如果使用swscale包装器的内部组件正确的挂上了日志，一个冗长的优先级日志信息将显示是否使用了zimg。

大多数需要软件转换的东西都可以利用该项。

备注

请注意，zimg 可能 比libswscale慢。通常，它在x86平台上更快，但在ARM上更慢（由于缺乏ARM特定的优化）。mpv的zimg包装器对某些格式使用了未经优化的重新打包，这不能责怪zimg。

--zimg-scaler=<point|bilinear|bicubic|spline16|spline36|lanczos>

使用的Zimg亮度缩放器（默认： lanczos）。

--zimg-scaler-param-a=<default|float>, --zimg-scaler-param-b=<default|float>

设置缩放器参数。默认情况下，这些参数被设置为特殊的字符串 default ，它映射到一个特定的缩放器默认值。如果某缩放器是不可调节的，则忽略。

lanczos

--zimg-scaler-param-a 是tap的数量。

bicubic

a和b是双立方的b和c参数。

--zimg-scaler-chroma=...

与 --zimg-scaler 相同，用于色度插值（默认： bilinear）。

--zimg-scaler-chroma-param-a, --zimg-scaler-chroma-param-b

与 --zimg-scaler-param-a / --zimg-scaler-param-b 相同，用于色度。

--zimg-dither=<no|ordered|random|error-diffusion>

色深抖动（默认： random）。

--zimg-threads=<auto|integer>

设置用于缩放的最大线程数（默认： auto）。 auto 使用当前机器的逻辑内核数量。注意，缩放器可能会根据情况使用更少的线程（甚至只有1个线程）。传递值1可禁用线程，并始终在单个操作中缩放图像。更高的线程数浪费资源，但通常会使它更快。

注意，一些zimg的git版本有bug，如果使用了线程，会破坏输出。

--zimg-fast=<yes|no>

允许优化以助于提高性能，但会降低质量（默认： yes）。目前，这可能简化伽马的转换操作。

音频重采样器

它控制mpv所做的任何重采样的默认选项（但除去内建的libavfilter，系统音频API重采样，或任何其它的地方）。

--audio-resample-filter-size=<length>

相对于低采样率的滤波长度。（默认： 16）

--audio-resample-phase-shift=<count>

多相条目数的对数。（…, 10->1024, 11->2048, 12->4096, …） （默认： 10->1024）

--audio-resample-cutoff=<cutoff>

截止频率（0.0-1.0），默认设置取决于滤波长度。

--audio-resample-linear=<yes|no>

如果设置，那么滤波将在多相条目之间进行线性插值。（默认： no）

--audio-normalize-downmix=<yes|no>

如果环绕声被下混为立体声，启用/禁用标准化（默认： no）。如果该功能被禁用，下混可能导致削波。如果它被启用，输出可能会太安静。这取决于源音频。

如果下混由于某种原因发生在mpv之外，或在解码器内（解码器下混），或在音频输出中（系统混音器），这无影响。

--audio-resample-max-output-size=<length>

限制一次过滤的音频帧的最大尺寸，以毫秒为单位（默认： 40）。为了使重采样速度变化反应更快，输出的大小是受限的。特别是当解码器或滤镜输出非常大的帧尺寸时（如一些无损编解码器或一些DRC滤镜），这是必要的。该选项不会以任何方式影响重采样算法。

仅用于测试/调试。可能在任何时候被移除或更改。

--audio-swresample-o=<string>

在SwrContext或AVAudioResampleContext上设置AVOptions。这些应该记录在FFmpeg中。

这是一个按键/值列表选项。详见 列表选项

终端

--quiet

使控制台的输出不过于冗长；特别是防止显示状态行（即 AV: 3.4 (00:00:03.37) / 5320.6 … ）。在低速的或不能正确处理回车（即 \r ）的损坏终端上特别有用。

另参见： --really-quiet 和 --msg-level

--really-quiet

显示比 --quiet 更少的输出和状态信息。

--terminal=<yes|no>

--terminal=no 禁用任何终端和 stdin/stdout/stderr 的使用。这将完全静默任何的信息输出。

与 --really-quiet 不同，这也禁用输入和终端的初始化。

--msg-color=<yes|no>

启用终端的彩色控制台输出（默认： yes）。

--msg-level=<module1=level1,module2=level2,...>

直接控制每个模块的冗长程度。模块 all 可以变更所有模块的冗长程度。从这个选项中变更冗长程度是按照从左到右的顺序进行的，且每项都可以覆盖前项。

用 --msg-level=all=trace 来运行mpv，可以看到mpv输出的所有信息。你可以使用输出中输出的模块名称（每行的前缀为 [...] ）来限制只输出感兴趣的模块。

这也会影响 --log-file ，并在某些情况下也会影响到libmpv API的日志记录。

备注

有些信息在命令行被解析之前就已被输出，因此不受 --msg-level 的影响。要控制这些信息，你必须使用 MPV_VERBOSE 环境变量；详见 环境变量

可用的级别：

no:

完全静默

fatal:

仅限致命信息

error:

错误信息

warn:

警告信息

info:

信息类的消息

status:

状态信息（默认）

v:

冗长信息

debug:

调试信息

trace:

非常嘈杂的调试信息

示例

mpv --msg-level=ao/sndio=no

完全静默 ao_sndio 的输出，它使用日志前缀 [ao/sndio]

mpv --msg-level=all=warn,ao/alsa=error

只显示警告或更糟的信息，且让 ao_alsa 的输出只显示错误。

--term-osd=<auto|no|force>

当没有视频输出时，控制是否在控制台显示OSD信息（默认： auto）。

auto:

如果没有视频输出，使用终端OSD

no:

禁用终端OSD

force:

即使视频输出激活，也使用终端OSD

如果设置了 --video-osd=no ，模式 auto 也会启用终端OSD。

--term-osd-bar=<yes|no>

启用在终端的状态行下输出一个进度条。（默认禁用）

--term-osd-bar-chars=<string>

自定义 --term-osd-bar 功能。该字符串预计由5个字符组成（开始，左侧空格，位置指示器，右侧空格，结束）。你可以使用Unicode字符，但要注意双倍宽度的字符将不会被正确处理。

默认： [-+-]

--term-playing-msg=<string>

开始播放后输出一个字符串。该字符串可被扩展为属性，例如： --term-playing-msg='file: ${filename}' 将输出字符串 file: 后接空格和当前播放的文件名。

参见 属性

--term-status-msg=<string>

在播放过程中输出一个自定义的字符串，而不是标准的状态行。可扩展属性。参见 属性扩展

--term-title=<string>

设置终端的标题。目前，这只是将设置窗口标题的转义序列与提供的（属性扩展）字符串简单连接起来。如果扩展的字符串包含结束转义序列的字节，或者终端不理解该序列，这将会造成混乱。后者可能包括令人遗憾的win32.

可扩展属性。参见 属性扩展

--msg-module

在每个控制台信息前加上模块名称。

--msg-time

在每个控制台信息前加上时间信息。时间的单位是播放器进程开始后的秒数（理论，但实际略晚），使用单一的取决于操作系统的时间源。在正常的UNIX系统中，这叫 CLOCK_MONOTONIC

缓存

--cache=<yes|no|auto>

决定是否使用网络缓存设置（默认： auto）。

如果启用，使用最大的 --cache-secs 作为缓存大小（但仍然受限于 --demuxer-max-bytes ），并使缓存数据可跳转（如果可能）。如果禁用， --cache-pause 和相关的都被隐式禁用。

auto 的选择是根据流是否被认为涉及网络链接或其它慢速媒体来启用（这是一个不完美的启发式方法）。

在mpv0.30.0之前，这个选项曾经接受一个数字，指定缓存的大小，单位是kilobytes。使用例如 --cache --demuxer-max-bytes=123k 来代替。

--cache-secs=<seconds>

如果缓存被激活，要预读取多少秒的音频/视频。如果且仅当缓存被启用且数值较大时，这将覆盖``–demuxer-readahead-secs`` 选项。默认值被设置的非常高，所以实际达到的预读取通常会受到 --demuxer-max-bytes 选项的限制。设置这个选项通常只对限制预读取有用。

--cache-on-disk=<yes|no>

将packet数据写入到一个临时文件，而不是将它们保存在内存中。这只有和 --cache 一起使用才有意义。如果一般的缓存被禁用，这个选项将被忽略。

缓存文件只是附加的。即使播放器出现裁剪数据，它所释放的文件空间也不会被重新使用。缓存文件在播放结束时被删除。

注意，packet元数据仍然保留在内存中。 --demuxer-max-bytes 和相关选项 只 适用于元数据。这种元数据的大小不尽相同，但每小时50MB的媒体是典型的。缓存统计将报告这个元数据的大小，而不是缓存文件的大小。如果元数据触顶了大小限制，元数据就会被裁剪（但不会切掉缓存文件）。

当媒体被关闭时，缓存文件被删除。缓存文件在媒体关闭后一般是没有价值的，而且很难从中检索到任何媒体数据（设计上不支持）。

如果该选项在运行时被启用，缓存文件会被创建，但旧的数据会保留在内存缓存中。如果该选项在运行时被禁用，旧的数据将保留在硬盘缓存中，并且缓存文件在媒体关闭之前不会被关闭。如果该选项被禁用并再次启用，将继续使用首先打开的缓存文件。

--demuxer-cache-dir=<path>

创建临时文件的目录。如果未设置，缓存将被存储在系统的缓存目录下（通常是 ~/.cache/mpv ）。

目前，这只用于 --cache-on-disk

--cache-pause=<yes|no>

当缓存中的数据用完后，播放器是否应该自动暂停，并中止解码/播放（默认： yes）。如果启用，它会暂停，一旦有更多的数据可用，又名“缓冲”，就解除暂停。

--cache-pause-wait=<seconds>

如果输入了“缓冲”，packet缓存在再次开始播放之前应该有多少秒的缓冲时间（默认： 1）。这可以用来控制如果 --cache-pause 被启用，解复用器拖欠时，播放器重新缓存的时间。如果给定的时间高于 --cache-secs 或 --demuxer-readahead-secs 设置的最大时间，或者由于其它原因（如文件结束或达到设置的最大缓存大小）预读取结束，播放将提前恢复。

--cache-pause-initial=<yes|no>

在开始播放前进入“缓冲”模式（默认： no）。这可以用来确保播放顺利开始，以换取等待一些时间来预读取网络数据（由 --cache-pause-wait 控制）。例如，一些常见的行为是，播放开始后，但随着播放的进行尝试解码更多的数据时，网络缓存立即不足。

另一个可能发生的情况是，网络预读取对CPU的要求很高（由于在后台进行解复用），以至于播放一开始就掉帧。在这种情况下，启用这个选项，并将 --cache-secs 和 --cache-pause-wait 设置为大致相同的值，会有帮助。

这个选项也会在跳转后重新开始播放时触发。

--demuxer-cache-unlink-files=<immediate|whendone|no>

是否或何时解除缓存文件的连接（默认： immediate）。这影响到缓存文件，这些文件本身是临时性的，在播放器终止后留在硬盘上没有意义。这是一个调试选项。

immediate

在缓存文件被创建后解除其连接。缓存文件将不再可见，即使它们还在使用。这可以确保当播放器终止时，它们被保证从硬盘中删除，即使它崩溃。

whendone

关闭后删除缓存文件。

no

不删除缓存文件。它们会消耗硬盘空间且没有用途。

目前，这只用于 --cache-on-disk

--stream-buffer-size=<bytesize>

低级流字节缓冲区的大小（默认： 128KB）。它被用作解复用器和低级I/O（例如套接字）之间的缓冲区。一般来说，它可以非常小，主要用途类似于C标准库中的内部缓冲区FILE。

缓冲区的一半始终用于保证回跳转，这对不可跳转的输入很重要。

有一些已知的情况，这有助于性能而设置一个大的缓冲区：

1. mp4文件。libavformat可能会在两个方向上触发许多小的跳转，取决于文件是如何被复用的。

2. 某些网络文件系统，它们没有缓存，小的读取可能是低效的。

在其它情况下，将其设置为一个大的值会降低性能。

通常情况下，读取链接是在缓冲区大小的一半，但可能会发生链接是在较小和较大的交替进行的情况（这是由于内部环形缓冲区的wrap-around）。

默认值和取值范围参见 --list-options 。 <bytesize> 选项接受后缀，比如 KiB 和 MiB

--vd-queue-enable=<yes|no>, --ad-queue-enable

启用在一个单独的线程上运行视频/音频解码器（默认： no）。如果启用，解码器将在一个单独的线程上运行，并在解码器和更高等级的播放逻辑之间放置一个帧队列。帧队列的大小由下面的其它选项定义。

这可能是毫无意义的。libavcodec已经有了多线程解码（默认启用），这使得它基本上没有必要。在一些高带宽视频缓慢解码的极端条件下，它可能会有帮助（在这些情况下，libavcodec会屏蔽播放逻辑，而使用解码线程将在不影响播放逻辑的情况下均匀分配解码时间）。在其它情况下，它只是会使跳转速度变慢，并使用明显更多的内存。

队列大小受其它 --vd-queue-... 选项的限制。最终的队列大小是具有最低限制的选项所指示的最小值。每个解码器/轨道都有自己的队列，可以使用完全配置的队列大小。

大多数队列选项可以在运行时改变。 --vd-queue-enable 本身（和音频等效选项）只有在解码完全重新初始化时才会更新。然而，设置 --vd-queue-max-samples=1 应该几乎导致与 --vd-queue-enable=no 相同的行为，该值可用于有效地在运行时启用/禁用队列。

这不应该被用于硬件解码。有可能为音频启用这个功能，但这更没有意义。

--vd-queue-max-bytes=<bytesize>, --ad-queue-max-bytes

队列的最大近似允许大小。如果超出，解码将被停止。最大尺寸可以超过大约1帧。

默认值和数值范围参见 --list-options 。 <bytesize> 选项接受后缀，比如 KiB 和 MiB

--vd-queue-max-samples=<int>, --ad-queue-max-samples

队列的最大帧数（视频）或采样数（音频）。音频的大小可能会超过1帧左右。

默认值和取值范围参见 --list-options

--vd-queue-max-secs=<seconds>, --ad-queue-max-secs

队列中媒体的最大秒数。特殊值0表示不设置限制。队列大小可能会超过2帧左右。时间戳重置可能导致队列大小的随机使用。

默认值和取值范围参见 --list-options

网络

--user-agent=<string>

使用 <string> 作为HTTP流的用户代理。

--cookies=<yes|no>

在进行HTTP请求时支持cookies。默认： no

--cookies-file=<filename>

从 <filename> 读取HTTP cookies。假设该文件是 Netscape 格式。

--http-header-fields=<field1,field2>

设置当访问HTTP流时自定义HTTP字段。

这是一个字符串列表选项。详见 列表选项

示例

mpv --http-header-fields='Field1: value1','Field2: value2' \
http://localhost:1234

将生成HTTP请求:

GET / HTTP/1.0
Host: localhost:1234
User-Agent: MPlayer
Icy-MetaData: 1
Field1: value1
Field2: value2
Connection: close

--http-proxy=<proxy>

HTTP/HTTPS的URL代理。如果设置了它，环境变量 http_proxy 就会被忽略。环境变量 no_proxy 仍被遵循。如果该选项不是以 http:// 开头，则会被静默忽略。代理不用于https URL。设置该选项并不能试图让ytdl脚本使用代理。

--tls-ca-file=<filename>

用于TLS的证书授权数据库文件。（在较早的FFmpeg版本中静默失败。）

--tls-verify

当使用TLS时，验证对方的证书（例如，用 https://... ）。（在较早的FFmpeg版本中静默失败。）

--tls-cert-file

一个包含证书的用于与对方握手的文件。

--tls-key-file

一个包含证书的私钥的文件。

--referrer=<string>

为HTTP请求指定一个引用者路径或URL。

--network-timeout=<seconds>

指定网络超时，以秒为单位（默认： 60）。这至少会影响HTTP。特殊值 0 将使用FFmpeg的默认值。如果使用的协议不支持超时，该选项会被静默忽略。

警告

这破坏了RTSP协议，因为FFmpeg的API在其内部超时选项上不一致。RTSP超时选项不仅接受不同的单位（秒而不是微秒，导致mpv传递给它巨大的数值），而且还会溢出FFmpeg的内部计算结果。最糟糕的是，仅仅设置该选项就会使RTSP进入监听模式，这就破坏了任何客户端的使用。在写这篇文档的时候，此修正还未生效。由于该原因，此选项在RTSP URL上被忽略（或应该被忽略）。你仍可以直接用 --demuxer-lavf-o 设置超时选项。

--rtsp-transport=<lavf|udp|udp_multicast|tcp|http>

选择RTSP传输方式（默认： tcp）。在播放 rtsp://... 网址时，这将选择底层网络传输。值 lavf 将决定权留给libavformat。

--hls-bitrate=<no|min|max|<rate>>

如果播放HLS流，该选项控制默认选择哪些流。该选项允许以下参数：

no:

不做任何特别的事情。通常，这将简单的选择它能找到的首个音频/视频流。

min:

挑选比特率最低的流。

max:

相同的挑选但比特率最高的流。（默认）

此外，如果选项是一个数字，那么将选择最高比特率等于或小于该选项值的流。

所用的比特率是由服务器发送的，并不能保证它是真正有意义的。

数字视频广播

--dvbin-prog=<string>

这定义了要调节的频道。通常，你可以通过使用流URL来指定，比如 "dvb://ZDF HD" ，但你可以通过在运行时写入此属性来调节到不同的频道。另参见 dvbin-channel-switch-offset 来获得更有用的频道切换功能。

--dvbin-card=<0-15>

指定使用卡号 0-15（默认： 0）。

--dvbin-file=<filename>

指示mpv从 <filename> 中读取频道列表。默认是在mpv设置目录下（通常是 ~/.config/mpv ），文件名是 channels.conf.{sat,ter,cbl,atsc,isdbt} （根据你的卡类型）或 channels.conf 作为最后手段。请注意，推荐使用特定的文件名和卡类型，因为传统的频道格式没有完全标准化，因此否则可能无法自动检测传输系统。对于DVB-S/2卡，推荐使用VDR 1.7.x格式的频道表，因为它可以调节到DVB-S2频道，启用字幕并对PMT进行解码（这在很大程度上改善了解复用）。仍然支持经典的mplayer格式的频道表（没有这些改进），对于其它的卡类型，只实现了有限的VDR格式频道表支持（欢迎打补丁）。对于有动态PID切换的频道或不完整的 channels.conf ，推荐使用 -dvbin-full-transponder 或神奇的 8192 PID。

--dvbin-timeout=<1-30>

试图调节到一个频率时，在放弃前等待的最大秒数（默认： 30）。

--dvbin-full-transponder=<yes|no>

不对程序的PID进行过滤，只对频率进行调节，并将全转发器传给解复用器。在这种情况下，播放器前端从全转发器中选择流，所以最初显示的频道可能与所选频道不匹配。通过循环 program 属性，可以在频道之间进行切换。这对于在一个转发器上录制多个节目，或解决 channels.conf 中的问题很有用。我们也建议对那些即时切换PID的频道使用这个功能，例如区域新闻。

默认： no

--dvbin-channel-switch-offset=<integer>

这个值不是通过设置文件来设定的，但是可用于频道切换。 input.conf 中可以通过 cycle 该值来执行 up 和 down 的通道切换。该数字有效的给出了频道列表中初始调节到的频道的偏移量。

一个示例， input.conf 可以包含：H cycle dvbin-channel-switch-offset up, K cycle dvbin-channel-switch-offset down

GPU渲染选项

以下视频选项目前都是针对 --vo=gpu, --vo=libmpv 和 --vo=gpu-next 的，它们是唯一实现这些选项的视频输出驱动。

--scale=<filter>

放大视频时使用的filter函数。

bilinear

双线性硬件纹理过滤（最快，质量很低）。这是使用 fast 配置时的默认设置。

lanczos

Lanczos缩放。提供了质量和性能之间的良好平衡。这是 --scale 的默认设置。可以使用 --scale-radius 来控制采样点的数量，但最好不要更改它。

（该filter是 sinc-windowed sinc 的别名）

ewa_lanczos

椭圆加权平均的Lanczos缩放。也被称为Jinc。相对较慢，但质量非常好。半径可以用 scale-radius 来控制。增加半径会使filter更锐利但会增加更多的振铃。

（该filter是 jinc-windowed jinc 的别名）

ewa_lanczossharp

ewa_lanczos的一个略锐利的版本，这是使用 high-quality 配置时的默认设置。

ewa_lanczos4sharpest

非常锐利的缩放器，但比 ewa_lanczossharp 稍慢。容易出现边缘振铃效应，因此建议将其与一个抗振铃着色器结合使用。在 --vo=gpu-next 中，设置此filter将启用内置的抗振铃，因此无需额外操作。

mitchell

Mitchell-Netravali。 B 和 C 参数可以用 --scale-param1 和 --scale-param2 来设置。

hermite

Hermite样条。类似于 bicubic ，但将 B 设置为 0.0 。这个滤镜具有半径1.0的特殊特性，因此与其它filter相比非常快，但容易出现阻塞效应。这是 --dscale 的默认设置。

catmull_rom

Catmull-Rom。类似于 mitchell ，其中 B 和 C 参数分别为 0.0 和 0.5 。这个filter比 mitchell 更锐利，但更容易产生振铃。

oversample

最邻近的一个版本，（天真地）对像素进行过采样，因此，重叠在边缘的像素会被线性内插值，而不是取整。这以换取增加一些模糊度为代价，基本上消除了由最邻近插值引起的小缺陷和抖动伪影。该filter擅可用来帧混成，也常被称为 “smoothmotion”（参见 --tscale ）。

linear

一个 --tscale filter。

还有一些更多的filter，但大多数没那么有用。传递值 help 以获得完整的列表，例如:

mpv --scale=help

--cscale=<filter>

和 --scale 一样，但用于插值色度信息。如果图像没有进行抽样，这个选项将完全被忽略。如果这个选项没有被设置，将应用由 --scale 暗示的filter。

--dscale=<filter>

和 --scale 一样，但在缩小时应用这些filter。

--tscale=<filter>

用于插值时间轴（帧）的filter。只有当 --interpolation 被启用时才会使用。 --tscale 的唯一有效选择是可分离的卷积filter（使用 --tscale=help 来获得一个列表）。默认： oversample

常见的 --tscale 选择包括 oversample, linear, catmull_rom, mitchell, gaussian, 或 bicubic 。这些都是按照平滑度/模糊度递增的顺序排列的， bicubic 是最平滑/最模糊的，而 oversample 是最清晰/最不平滑的。

--scale-param1=<value>, --scale-param2=<value>, --cscale-param1=<value>, --cscale-param2=<value>, --dscale-param1=<value>, --dscale-param2=<value>, --tscale-param1=<value>, --tscale-param2=<value>

设置filter参数。默认情况下，这些参数被设置为特殊的字符串 default ，它映射到一个特定缩放器的默认值。如果filter是不可调的，则忽略。目前，这影响到下列filter参数：

bicubic

样条参数（ B 和 C ）。默认： B=1 C=0

gaussian

缩放参数（ t ）。增加这个参数会使结果更模糊。默认： 1

oversample

使用插值之前与边缘的最小距离。设置为0将始终插值边缘，而设置为0.5将永远不插值，因此表现为使用常规的最邻近算法。默认： 0.0

--scale-blur=<value>, --cscale-blur=<value>, --dscale-blur=<value>, --tscale-blur=<value>

Kernel缩放系数（也被称为模糊系数）。减少它可以使结果更锐利，增加它可以使结果更模糊（默认： 0）。如果设置为0，将使用kernel的首选模糊系数。注意，设置的太低（例如0.5）会导致不好的结果。通常推荐使用0.8到1.2之间的值。

--scale-clamp=<0.0-1.0>, --cscale-clamp, --dscale-clamp, --tscale-clamp

指定要乘以负系数的权重偏差。指定 --scale-clamp=1 的效果是完全去除负的权重，从而有效地将数值范围限制在[0-1]。可以指定0.0和1.0之间的值，只对负权重进行适度减弱。这对 --tscale 特别有用，它可以减少时域的过多的振铃伪影（通常表现为短促的闪光或黑边，主要围绕在移动的边缘），以可能增加更多模糊为代价。 --tscale-clamp 的默认值是1.0，其它的默认值是0.0。

--scale-taper=<value>, --scale-wtaper=<value>, --dscale-taper=<value>, --dscale-wtaper=<value>, --cscale-taper=<value>, --cscale-wtaper=<value>, --tscale-taper=<value>, --tscale-wtaper=<value>

Kernel/window taper系数。增加它可以使filter函数变平。值的范围是0到1。值为0（默认）表示没有平坦化，值为1使filter完全平坦（相当于一个box函数）。介于两者之间的值意味着某些部分将是平坦的，实际的filter函数将被挤压到两者之间的空间中。

--scale-radius=<value>, --cscale-radius=<value>, --dscale-radius=<value>, --tscale-radius=<value>

为可调的filter设置半径，必须是0.5到16.0之间的浮点数。如果未指定则默认为filter的首选半径。并非对每个缩放器和视频输出驱动的组合都有效。

注意，根据filter的实现细节和视频缩放比例，实际使用的半径可能是不同的（很可能被增加一点）。

--scale-antiring=<value>, --cscale-antiring=<value>, --dscale-antiring=<value>, --tscale-antiring=<value>

设置抗振铃强度。这尝试消除振铃，但在此过程中可能会引入其它伪影。必须是0.0和1.0之间的浮点数。默认值0.0完全禁用抗振铃。

注意，这不影响特殊的 bilinear 和 bicubic_fast filter，也不影响任何polar (EWA) 缩放器。

--scale-window=<window>, --cscale-window=<window>, --dscale-window=<window>, --tscale-window=<window>

（仅限高级用户）为kernel选择一个自定义的window函数。如果未设置则默认为filter的首选window。使用 --scale-window=help 来获得一个支持的window函数的列表。

--scale-wparam=<window>, --cscale-wparam=<window>, --cscale-wparam=<window>, --tscale-wparam=<window>

（仅限高级用户）设置由 --scale-window 等给出的window函数的参数。默认情况下，这些参数被设置为特殊的字符串 default ，它映射到一个特定window的默认值。如果window不可调则忽略。目前，这影响到以下window参数：

kaiser

window参数（alpha）。默认： 6.33

blackman

window参数（alpha）。默认： 0.16

gaussian

缩放参数（t）。增加它使window变宽。默认： 1

--scaler-resizes-only

如果视频图像没有调整大小，则禁用缩放器。在这种情况下， bilinear 会被用来代替 --scale 设置的任何东西。如果不进行缩放，双线性将完美再现源图像。默认启用。注意，这个选项从不影响 --cscale

--correct-downscaling

当使用基于卷积的filter时，在缩小时扩展filter的尺寸。增加了质量，但降低了缩小时的性能。默认启用

这对变形视频来说会有轻微的次优化表现（但仍然比没有好），因为它将扩展尺寸以仅匹配轴之间比例系数的较低值。

注意：当在 --vo=gpu 中使用双线性缩小时，该选项被忽略。

--linear-downscaling

在缩小时线性缩放亮度。它应该只能用于至少有16位精度的 --fbo-format 。该选项对HDR内容无影响。默认启用

--linear-upscaling

在放大时线性缩放亮度。和 --linear-downscaling 一样，它应该只能用于至少有16位精度的 --fbo-format 。除了测试/特殊目的外，通常不推荐这样做。建议用户启用 --sigmoid-upscaling 或保持两个选项都禁用（即以伽玛缩放亮度）。

--sigmoid-upscaling

当放大时，使用正弦波颜色变换以避免强调振铃伪影。默认启用。这与 --linear-upscaling 不兼容并取代了它（注意sigmoidization也需要线性化，所以在两种情况下 LINEAR 渲染步骤都会启动）。

--sigmoid-center

用于 --sigmoid-upscaling 的正弦曲线的中心，必须是0.0到1.0之间的浮点数。如果未指定则默认： 0.75

--sigmoid-slope

用于 --sigmoid-upscaling 的正弦曲线的斜率，必须是1.0到20.0之间的浮点数。如果未指定则默认： 6.5

--interpolation

减少由视频帧数和显示器刷新率不匹配引起的卡顿（也被称为抖动）。

警告

这需要将 --video-sync 选项设置为 display- 模式之一，否则它将被默默禁用。这在mpv0.14.0之前是不需要的。

这实质上是试图通过沿时间轴卷积视频来插补缺失的帧。使用的filter可以用 --tscale 设置来控制。

--interpolation-threshold=<0..1,-1>

低于这个阈值的帧率插值将被禁用（默认： 0.01 ）。计算方法是 abs(disphz/vfps - 1) < threshold ，其中 vfps 是速度调整后的视频FPS， disphz 是显示器刷新率（速度调整后的视频FPS大致等于正常的视频FPS，但是应用了减速和加速。如果你使用 --video-sync=display-resample 来使视频与显示FPS同步运行，或者改变 speed 属性，这很重要）。

默认的目的是，在使用 --video-sync=display-* 的重计时不能充分调整视频速度以实现流畅播放的情况下启用插值。例如，如果一个视频是60.00FPS，而你的显示器刷新率是59.94Hz，插值将永远不会被激活，因为不匹配是在刷新率的1%以内。默认值还处理了mpv不能确定容器FPS的情况，比如在某些直播流中，可能会动态地切换插值的开启和关闭。在这种情况下，默认情况是不使用插值，而是允许 --video-sync=display-* 来重新计时视频以匹配显示器的刷新率。详见 --video-sync-max-video-change 了解关于mpv如何重新计时视频。

还要注意的是，如果你使用 --video-sync=display-vdrop ，速率的微小偏差会禁用插值，每隔一分钟就会引入一个不连续。

将此设置为 -1 来禁用这个逻辑。

--interpolation-preserve

即使渲染器参数发生变化，也保留前几帧的插值结果 —— 与剪切和视频放置有关的选项除外，这些选项总是会使缓存失效。启用该选项可以使渲染器设置的动态更新稍微平滑，但代价是对这种变化的响应延迟会稍高。默认为开启（只影响 --vo=gpu-next ，注意 --vo=gpu 始终使插值的帧失效）。

--opengl-pbo

启用PBOs的使用。在某些驱动上，这可能会更快，特别是当源视频尺寸很大时（例如所谓的“4K”视频）。在其他它驱动上，它可能会更慢或引起延迟问题。

--dither-depth=<N|no|auto>

设置抖动的目标深度为N，默认： auto

no

禁用mpv所做的任何抖动

auto

自动选择。 --vo=gpu ：检测位深或回退8bpc。 --vo=gpu-next` ：检测位深或回退8bpc（对于SDR）

8

抖动到8比特输出

请注意，除非使用 gpu-api=d3d11 ，否则无法检测在线位深。建议将该值明确设置为显示器的位深，因为某些液晶面板自身执行的抖动质量可能较低。

--dither-size-fruit=<2-8>

设置抖动矩阵的大小（默认： 6）。矩阵的实际大小是 (2^N) x (2^N) ，选项值为 N ，所以值为6时，大小为64x64。矩阵在启动时生成，一个大的矩阵可能需要相当长的时间来计算（秒）。

只能在 --dither=fruit 模式下使用。

--dither=<fruit|ordered|error-diffusion|no>

选择抖动算法（默认： fruit）（通常情况下， --dither-depth 选项控制是否启用抖动。）

error-diffusion 选项需要计算着色器的支持。它也需要大量的共享内存来运行，其大小取决于kernel（见下方的 --error-diffusion 选项）和视频窗口的高度。如果没有足够的共享内存来运行着色器，它将回退到 fruit 抖动。

--temporal-dither

启用时域抖动（只有在一般情况下启用抖动时才会激活）。通过改变平铺的抖动矩阵的方向，每个帧上的8种不同抖动模式之间会发生变化。不幸的是，这可能会导致LCD显示器上的闪烁，因为这些显示器有很高的反应时间。

--temporal-dither-period=<1-128>

确定在使用 --temporal-dither 时抖动模式的更新频率。1（默认）将在每一视频帧上更新，2在每隔一帧更新，以此类推。

--error-diffusion=<kernel>

当设置了 --dither=error-diffusion 时，使用的误差扩散的kernel。

simple

只向相邻的两个像素传播误差。最快但质量低

sierra-lite

速度快且质量合理。这是默认值

floyd-steinberg

最值得注意的误差扩散kernel

atkinson

看起来与其它kernel不同，因为在抖动过程中只有部分误差会被传播。这个kernel的典型用途是保存抖动的屏幕截图（在窗口模式下）。这个kernel产生的文件稍小，但抖动质量仍然合理。

还有其它的kernel（使用 --error-diffusion=help 列出），但它们中的大多数都要慢得多，而且需要更大的共享内存。在这些kernel中， burkes 在性能和质量之间取得了良好的平衡，可能是你首先想尝试的kernel。

--gpu-debug

启用GPU调试。这意味着什么取决于API类型。对于OpenGL，它调用 glGetError() ，并请求一个调试环境。对于Vulkan，它启用验证层。

--opengl-swapinterval=<n>

两次缓冲区互换之间的显示帧间隔。1相当于启用垂直同步，0相当于禁用垂直同步。如果没有指定则默认为1。

注意，这取决于正确的OpenGL 垂直同步支持。在某些平台和驱动上，只有在全屏模式下才能可靠地工作。如果使用多个显示器，它可能还需要特定驱动程序的hack，以确保mpv同步到正确的显示器。合成窗口管理器也会导致不好的结果，比如显示FPS信息可能丢失或不正确（参见 --display-fps-override ）。

--vulkan-device=<device name>

用于渲染和呈现的Vulkan设备的名称或UUID。使用 --vulkan-device=help 来查看可用设备的列表和它们的名称与UUID。如果未指定，将使用第一个枚举的硬件Vulkan设备。

--vulkan-swap-mode=<mode>

控制vulkan交换链的呈现模式。这与 --opengl-swapinterval 选项相似。

auto

使用vulkan上下文的首选交换链模式（默认）

fifo

非撕裂，垂直同步被阻塞。类似于“垂直同步打开”

fifo-relaxed

撕裂，垂直同步被阻塞。迟来的帧会撕裂而不是卡顿

mailbox

非撕裂，无垂直同步阻塞。类似于“三重缓冲”

immediate

撕裂，无垂直同步阻塞。类似于“垂直同步关闭”

--vulkan-queue-count=<1..8>

控制用于渲染的VkQueues的数量（受你的设备支持的数量限制）。理论上，使用更多的队列可以在帧之间实现一些并行性（当使用一个高于1的 --swapchain-depth 时），但在队列之间没有真正的并行性的硬件上，它也会使这变得缓慢。（默认： 1）

--vulkan-async-transfer

在支持的vulkan设备上启用异步传输队列的使用。使用它们可以使纹理上传和混合等传输操作与实际渲染同时进行，从而提高整体吞吐量和功耗。默认启用，而且应该是相对安全的。

--vulkan-async-compute

在支持的vulkan设备上启用异步计算队列的使用。从理论上讲，使用它可以实现计算着色器与图形着色器的乱序调度，从而使硬件在等待管线bubbles和内存操作时能够做更有效的工作。不是在所有的GPU上都有优势。值得注意的是，如果启用了异步计算，并且设备支持的计算队列多于图形队列（受 --vulkan-queue-count 的限制），mpv将在内部尝试并尽可能优先使用计算着色器而不是片段着色器。默认启用，尽管Nvidia用户可能想禁用它。

--vulkan-display-display=<n>

当使用 displayvk GPU上下文时，选定的Vulkan设备上的显示器的索引将呈现在上面。使用 --vulkan-display-display=help 来查看可用的显示器列表。如果没有指定，将使用第一个枚举的显示器。

--vulkan-display-mode=<n>

当使用 displayvk GPU上下文时，所选Vulkan显示器的显示模式的索引。使用 --vulkan-display-mode=help 来查看可用模式的列表。如果没有指定，将使用第一个枚举的模式。

--vulkan-display-plane=<n>

当使用 displayvk GPU上下文时，选定的Vulkan设备上的平面的索引，以呈现在上面。使用 --vulkan-display-plane=help 来查看可用平面的列表。如果没有指定，将使用第一个枚举的平面。

--d3d11-exclusive-fs=<yes|no>

当全屏视频被请求时，将D3D11交换链的全屏状态切换为“全屏”。在其它应用程序中也被称为“独占全屏”或“D3D全屏”。让mpv完全控制在交换链的屏幕上进行渲染。默认情况下是关闭的。

--d3d11-warp=<yes|no|auto>

使用WARP（Windows高级光栅化平台）与D3D11 GPU后端（默认： auto）。这是一个高性能的软件渲染器。默认情况下，只有当系统没有支持D3D11的硬件适配器时才会使用它。即使扩展的GPU功能将与WARP一起工作，但它们可能非常慢。

--d3d11-feature-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1>

在使用D3D11 GPU后端时，选择一个特定的功能等级。默认情况下，会使用最高的可用功能等级。这个选项可以用来选择一个较低的功能等级，这主要是对调试有用。大多数扩展的GPU特性在9_x功能等级下将无法工作。

--d3d11-flip=<yes|no>

启用翻转模型呈现，通过与DWM共享表面来避免不必要地复制后缓存（默认： yes）。这可能会引起老旧驱动的性能问题。如果不支持翻转模型呈现（例如，在没有平台更新的Windows 7上），mpv将自动回退到旧的bitblt呈现模型。

--d3d11-sync-interval=<0..4>

安排呈现每一帧的VBlank间隔数（默认：1）。设置为1将启用垂直同步，设置为0将禁用它。

--d3d11-adapter=<adapter name|help>

选择一个特定的D3D11适配器来进行D3D11渲染。如果没有设置，将选择默认的适配器。当给出“help”时，会列出其它的适配器。

根据字符串的开头来检查是否匹配，不区分大小写。因此，如果适配器的描述以厂商名称开始，就可以使用它作为选择参数。

利用D3D11渲染抽象的辅助功能来接收设备的硬件解码器，比如D3D11VA或DXVA2的DXGI模式，将受此选择的影响。

--d3d11-output-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f>

选择一种用于D3D11渲染的特定的D3D11输出格式。”auto” 是默认的，它将根据设置的桌面位深度选择rgba8或rgb10_a2。rgba16f和bgra8不在自动检测逻辑中，可用于手动测试。

备注

桌面位深度的查询只来自于Windows 10的API。因此在旧系统上，它只能自动利用rgba8输出格式。

备注

对于 –vo=gpu-next` ，这是一个尽力而为的提示，libplacebo 有最终决定权使用哪种格式。

--d3d11-output-csp=<auto|srgb|linear|pq|bt.2020>

选择一个用于D3D11渲染的特定的D3D11输出色彩空间。 auto 是默认值，它将选择交换链所在的桌面的色彩空间。

除了 srgb 和 pq 以外的值在测试中存在问题，所以它们主要用于手动测试。

备注

交换链色彩空间的设置只能从Windows 10的API中获得。因此，在旧系统上它将无法工作。

--d3d11va-zero-copy=<yes|no>

默认情况下，当使用 --gpu-api=d3d11 带硬件解码时 ，视频图像将从解码器表面复制（GPU到GPU）到一个着色器资源。设置这个选项可以避免复制，直接从解码器图像中采样。这可能会提高性能并降低功耗，但是由于填充的原因，可能会导致图像在底部和右侧边缘的采样不正确，并且可能会引发驱动错误，因为Direct3D 11在技术上不允许从解码器表面采样（尽管大多数驱动支持它）。

目前只与 --gpu-api=d3d11 有关。

--wayland-app-id=<string>

为基于Wayland的视频输出方法设置client app ID（默认： mpv ）。

--wayland-configure-bounds=<auto|yes|no>

控制mpv是否选择进入由合成器发送的configure bounds事件（默认： auto）。这将限制mpv窗口的初始大小，使其达到合成器所期望的最大尺寸。在大多数情况下，这只是为了防止mpv窗口在第一次渲染时大于显示器的尺寸。默认值为 auto ，此时如果任何 autofit 或 geometry 类的选项也被设置，configure-bounds 将被静默忽略。

--wayland-content-type=<auto|none|photo|video|game>

如果合成器支持，mpv将使用内容类型协议发送一个提示，告诉合成器正在显示什么类型的内容。 auto （默认）将自动切换，告诉合成器内容是照片、视频或可能不是，这取决于内部启发式的方法。

--wayland-disable-vsync=<yes|no>

为基于Wayland的视频输出禁用mpv的内部垂直同步（默认： no）。当与 --video-sync=display-desync --audio=no 和 --untimed=yes 结合使用时，这对wayland视频输出的基准测试非常有用。

--wayland-edge-pixels-pointer=<value>

定义边缘边框的大小（默认： 16），以便使用鼠标在wayland上下文中启动client调整大小的events。仅当合成器中没有服务器端装饰时，此选项才能激活。

--wayland-edge-pixels-touch=<value>

定义边缘边框的大小（默认： 32），以便使用鼠标在wayland上下文中启动client调整大小的events。

--spirv-compiler=<compiler>

控制哪个编译器用于将GLSL翻译成SPIR-V。这（目前）只与 --gpu-api=vulkan 和 --gpu-api=d3d11 有关。目前可能的选择只有：

auto

使用第一个可用的编译器（默认）

shaderc

使用libshaderc，它是一个围绕glslang的API wrapper。如果可用，这通常是最优先的

备注

这个选项已过时，因为只有一个合理的值。它可能在将来被移除。

--glsl-shader=<file>, --glsl-shaders=<file-list>

自定义GLSL hooks。这些是一种灵活的来添加自定义片段着色器的方式，可以在渲染管线中几乎任意的点注入，并访问所有先前的中间纹理。

每次使用 --glsl-shader 选项都会在内部着色器列表中添加另一个文件，而 --glsl-shaders 则是一个文件列表，并用它覆盖内部列表。后者是一个路径列表选项（详见 列表选项 ）。

警告

语法还不稳定且可能随时会改变。

用户着色器的一般语法是这样的:

//!METADATA ARGS...
//!METADATA ARGS...

vec4 hook() {
   ...
   return something;
}

//!METADATA ARGS...
//!METADATA ARGS...

...

每一段元数据，连同它后面的非元数据行，都定义了单一的块。目前有两种类型的块，HOOKs和TEXTUREs。

一个 TEXTURE 块可以设置以下选项：

TEXTURE <name> (required)

这个纹理的名称。然后Hooks可以用BIND绑定这个名字下的纹理。这必须是纹理块的第一个选项。

SIZE <width> [<height>] [<depth>] (required)

纹理的尺寸。高度和深度是可选的。纹理的类型（1D、2D或3D）取决于指定的组件数量。

FORMAT <name> (required)

示例的纹理格式。初始化 gpu 视频输出驱动时，支持的纹理格式将在调试日志记录中列出（查找 Texture formats: ）。通常，这遵循OpenGL命名规则。例如， rgb16 提供了3个具有标准化16位组件的通道。一个奇怪之处是浮点格式：例如， rgba16f 具有16位内部精度，但纹理数据以32位浮点形式提供，驱动程序在纹理上传时转换数据。

虽然格式名称遵循通用的命名规则，但并不是所有的硬件、驱动、GL版本等都能使用这些格式。

FILTER <LINEAR|NEAREST>

从该纹理采样时使用的最小/放大率filter。

BORDER <CLAMP|REPEAT|MIRROR>

从该纹理采样时使用的边框wrapping模式。

元数据之后接一串十六进制的字节，定义了原始纹理数据，对应 FORMAT 指定的格式，在单行上，没有多余的空白。

一个 HOOK 块可以设置以下选项：

HOOK <name> (required)

要挂钩的纹理。在一个元数据块中可以出现多次，最多是一个预定的限制。请看下面的可钩住的纹理列表。

DESC <title>

用户友好型的传递描述。这是在属性 vo-passes 的传递列表中代表该着色器时使用的名称。

BIND <name>

加载一个纹理（可以来自mpv，也可以来自 TEXTURE 块），并使其可用于该通道。当从mpv中绑定纹理时，这也将设置宏，以方便正确访问它。列表见下文。默认情况下，没有纹理被绑定。特殊名称HOOKED可以用来指代触发这个传递的纹理。

SAVE <name>

给出纹理的名称，以便将这次传递的结果保存到其中。默认情况下，它被设置为特殊名称HOOKED，具有覆盖挂钩纹理的效果。

WIDTH <szexpr>, HEIGHT <szexpr>

指定本次处理结果的纹理尺寸。 szexpr 指的是RPN（反向波尔符号）中的表达式，使用运算符+ - * / > < !，浮点字数，以及对现有纹理（如MAIN.width或CHROMA.height）、OUTPUT或NATIVE_CROPPED（经过pan-and-scan, video-align-x/y, video-pan-x/y等裁剪的输入纹理的尺寸，可能还有预缩放）的引用。默认情况下，这些被分别设置为HOOKED.w和HOOKED.h。

WHEN <szexpr>

指定一个需要为真（非零）的条件，以使着色器阶段被评估。如果它失败了，它将被默默地省略（注意，像这样的着色器阶段，如果依赖于一个可选的钩子点，仍然会导致钩子点被保存，这有一些小的开销）。

OFFSET <ox oy | ALIGN>

表示这个通道所引入的像素偏移（offset）。这些像素偏移将被累积，并在下一个缩放通道（ cscale 或 scale ）中被修正。默认值是0 0，对应于无偏移。请注意，在不覆盖挂钩纹理时，偏移量会被忽略。

一个特殊的值 ALIGN 将试图通过将其与参照物对齐来修复HOOKED的现有偏移。它要求HOOKED是可调整大小的（见下文）。它与片段着色器透明地工作。对于计算着色器，需要使用预定义的 texmap 宏来处理坐标映射。

COMPONENTS <n>

指定这个通道的输出有多少个相关的组件，并且应该存储在纹理中，最多4个（rgba）。默认情况下，这个值等于HOOKED中的组件数。

COMPUTE <bw> <bh> [<tw> <th>]

指定此着色器应被视为计算着色器，其块大小为bw和bh。计算着色器将被派发多少个必要的块，以完全铺满输出。在每个块中，将有tw*th线程，形成一个工作组。换句话说：tw和th指定了工作组的大小，它可以与块的大小不同。因此，举例来说，一个在500x500纹理上运行的bw, bh = 32，tw, th = 8的计算着色器将调度16x16块（向上取整），每个块有8x8个线程。

mpv中的计算着色器的处理方式与片段着色器有些不同。你不需要定义产生输出样本的 vec4 hook ，而是直接定义 void hook ，使用 imageStore 写到一个固定的只写的图像单元 out_image （这是由mpv绑定的）。为了帮助在没有顶点的情况下翻译纹理坐标，mpv提供了一个特殊的函数 NAME_map(id) 来从输出图像的texel空间映射到所有绑定纹理的纹理坐标。特别是， NAME_pos 等同于 NAME_map(gl_GlobalInvocationID) ，尽管只有在(tw,th)==(bw,bh)的情况下使用这个函数才真正有意义。

每个绑定的mpv纹理（通过 BIND ）将为该着色器通道提供以下定义，其中NAME是绑定纹理的名称：

vec4 NAME_tex(vec2 pos)

用来访问某个点的纹理的采样函数（在纹理坐标空间，范围[0,1]）。这将处理任何必要的归一化转换。

vec4 NAME_texOff(vec2 offset)

以像素为单位在某一偏移处对纹理进行采样。工作原理与NAME_tex类似，但还负责必要的旋转，例如在vec2(-1,0)处取样，总是向左倾斜一个像素。

vec2 NAME_pos

该纹理的局部纹理坐标，范围[0,1]。

vec2 NAME_size

纹理的（旋转）尺寸，单位为像素。

mat2 NAME_rot

与该纹理相关的旋转矩阵（将像素空间旋转到纹理坐标）。

vec2 NAME_pt

单个像素的（未旋转的）尺寸，范围[0,1]。

float NAME_mul

需要乘以纹理内容的系数，以便将其归一化为[0,1]的范围。

sampler NAME_raw

原始绑定纹理本身。除非绝对必要，否则应避免使用这个。

通常情况下，用户应该使用NAME_tex或NAME_texOff来读取纹理。然而，对于某些着色器来说，从NAME_RAW中进行自定义采样，性能会更好，在这种情况下，需要注意遵循NAME_mul和NAME_rot。

除了这些参数外，以下uniforms也是全局可用的：

float random

范围为[0-1]的随机数，每帧不同。

int frame

一个简单的渲染帧数，每一帧增加一个，永不重置（不考虑寻求）。

vec2 input_size

输入图像的像素大小（可能经过裁剪和预缩放）。

vec2 target_size

缩放后（可能是裁剪后）的图像的可见部分的像素大小。

vec2 tex_offset

由用户着色器或panscan、video-align-x/y、video-pan-x/y等选项引入的纹理偏移。

在内部，vo_gpu可以生成以下任意数量的纹理。每当一个纹理被vo_gpu渲染并保存时，所有钩住它的通道都会按照用户添加的顺序运行。这是一个合法钩点的列表：

RGB, LUMA, CHROMA, ALPHA, XYZ (resizable)

源平面（原始）。其中哪个工作取决于源的图像格式。

CHROMA_SCALED, ALPHA_SCALED (fixed)

源平面（放大）。这些只在抽样的内容上启动。

NATIVE (resizable)

合并后的图像，在源色彩空间中，转换为RGB之前。

MAINPRESUB (resizable)

转换为RGB后的图像，但在应用 --blend-subtitles=video 之前。

MAIN (resizable)

主图像，在转换为RGB后，但在放大前。

LINEAR (fixed)

线性亮度图像，在缩放之前。这只在 --linear-upscaling, --linear-downscaling or --sigmoid-upscaling 生效的情况下发生。

SIGMOID (fixed)

在缩放之前，对亮度进行Sigmoid处理。这只在 --sigmoid-upscaling 生效的情况下发生。

PREKERNEL (fixed)

缩放器kernel运行前的图像。

POSTKERNEL (fixed)

缩放器kernel运行后的图像。

SCALED (fixed)

在进行色彩管理之前，最终放大的图像。

OUTPUT (fixed)

最终的输出图像，在色彩管理之后但在抖动和绘制到屏幕之前。

只有标有 resizable 的贴图可以通过该通道进行转换。当覆盖一个标有 fixed 的纹理时，WIDTH、HEIGHT和OFFSET必须保持其默认值。

--glsl-shader=<file>

CLI/设置文件只是 --glsl-shaders-append 的别名。

--glsl-shader-opts=param1=value1,param2=value2,...

指定用于可调节着色器参数的选项。你可以通过在着色器名称前加上 / ，例如 shader/param=value ，来针对特定命名的着色器。如果没有前缀，参数会影响所有着色器。着色器名称是着色器文件名的基础部分，不带扩展名（ --vo=gpu-next 独占）。

--deband

启用去色带算法。这大大减少了可见的色带、色块和其它量化伪影的数量，代价是使一些最细微的细节变得非常模糊。在实际中，它几乎总是一种改进 —— 禁用它的唯一原因是为了性能。

--deband-iterations=<0..16>

每个采样要执行去色带步骤的数量。每一步都会减少一点带状物，但需要时间来计算。注意，每一步的强度下降得很快，所以较高数字（>4）实际上是无用的（默认： 1）。

--deband-threshold=<0..4096>

去色带滤镜的截止阀值。较高的数字会大大增加去色带强度，但会逐渐减少图像细节（默认： 48）。

--deband-range=<1..64>

去色带的初始半径。半径在每次迭代中线性增加。半径越大则坡度越大，但半径越小平滑效果越好（默认： 16）。

如果你增加了 --deband-iterations ，你可能应该减少此项来进行补偿。

--deband-grain=<0..4096>

给图像添加一些额外的噪点。这大大有助于掩盖剩余的量化伪影。更高的数字会增加更多的噪点（默认： 32）。

--corner-rounding=<0..1>

如果将值设置为大于 0.0 ，则输出将呈现带有圆角的效果，就好像应用了一个alpha透明度遮罩一样。该值表示要圆角的边长的相对比例 - 值为 1.0 时尽可能圆角化（ --vo=gpu 独占）。

--sharpen=<value>

如果设置为0以外的值，则启用一个unsharp masking滤镜。正值将锐化图像（但增加更多的振铃和锯齿）。负值会使图像变得模糊。如果你的GPU足够强大，可以考虑使用 ewa_lanczossharp 缩放filter或 --scale-blur 选项取代（ --vo=gpu 独占）。

--opengl-glfinish

在交换缓冲区之前调用 glFinish() （默认： no）。速度较慢，但在进行framedropping时可能会改善结果。可能完全损坏性能。细节完全取决于OpenGL驱动。

--opengl-waitvsync

在每次缓冲区交换后调用 glXWaitVideoSyncSGI （默认： no）。这可能会也可能不会对视频计时的准确性和丢帧有帮助。这有可能使视频输出变慢，或者根本没有影响。

（X11/GLX独占）

--opengl-dwmflush=<no|windowed|yes|auto>

（Windows独占）在Windows下交换缓冲区后调用 DwmFlush （默认： auto）。它还设置了 SwapInterval(0) 以忽略OpenGL的时间。可用的值是：no（禁用），windowed（仅在窗口模式下），yes（也在全屏下）。

值 auto 将尝试确定合成器是否处于激活状态，只有当它似乎处于活动状态时才调用 DwmFlush

这可能有助于获得更一致的帧间隔，特别是对于高帧率的clips —— 这也可能减少丢帧。通常，一个 windowed 的值就足够了，因为全屏可能会绕过DWM。

--angle-d3d11-feature-level=<11_0|10_1|10_0|9_3>

在D3D11中使用ANGLE后端时，选择一个特定的功能等级。默认情况下，会使用最高的可用功能等级。这个选项可以用来选择一个较低的功能等级，这主要对调试有用。请注意，OpenGL ES 3.0只支持10_1或更高的功能等级。大多数扩展的OpenGL功能在较低的功能等级下无法工作（类似于 --gpu-dumb-mode ）。

（Windows ANGLE独占）

--angle-d3d11-warp=<yes|no|auto>

在D3D11中使用ANGLE后端时，使用WARP（Windows高级光栅化平台）（默认： auto）。这是一个高性能的软件渲染器。默认情况下，当Direct3D硬件不支持Direct3D 11功能级别9_3时，会使用它。虽然扩展的OpenGL功能将与WARP一起工作，但它们可能非常慢。

（Windows ANGLE独占）

--angle-egl-windowing=<yes|no|auto>

使用ANGLE的内置EGL窗口函数来创建交换链（默认： auto）。如果设置为 no ，并且正在使用D3D11渲染器，ANGLE内置的交换链将不被使用，而是创建一个为视频渲染而优化的自定义交换链。如果设置为 auto ，自定义交换链将用于D3D11，而内置交换链将用于D3D9。这个选项主要是为了调试，以防自定义交换链的性能不佳或不工作。

如果设置为 yes ，选项 --angle-flip 将没有作用。

（Windows ANGLE独占）

--angle-flip=<yes|no>

启用翻转模型呈现，这可以避免通过与DWM共享表面而不必要地复制后缓存（默认： yes）。这可能会导致老旧驱动的性能问题。如果不支持翻转模型呈现（例如，在没有平台更新的Windows 7上），mpv将自动回退到旧的bitblt呈现模型。

如果设置为 no ，选项 --angle-swapchain-length 将没有影响。

（Windows ANGLE独占）

--angle-renderer=<d3d9|d3d11|auto>

在使用ANGLE后端时强制使用特定的渲染器（默认： auto）。在自动模式下，对于支持Direct3D 11功能级别9_3或更高的系统，它会选择D3D11，否则会选择D3D9。这个选项主要是为了调试的目的。通常情况下，没有理由强制使用特定的渲染器，尽管 --angle-renderer=d3d9 在旧硬件上可能会有稍好的性能。请注意，D3D9渲染器只支持OpenGL ES 2.0，所以如果选择了这个渲染器，大多数扩展的OpenGL功能将无法工作（类似于 --gpu-dumb-mode ）。

（Windows ANGLE独占）

--macos-force-dedicated-gpu=<yes|no>

停用自动图形切换并强制使用独立GPU（默认： no）。

（macOS独占）

--cocoa-cb-sw-renderer=<yes|no|auto>

在使用cocoa-cb时使用苹果软件渲染器（默认： auto）。如果设置为 no ，软件渲染器永远不会被使用，而是在无法创建通常的像素格式时失败， yes 将永远只使用软件渲染器，而 auto 只在无法创建通常的像素格式时回退到软件渲染器。

（macOS且cocoa-cb独占）

--cocoa-cb-10bit-context=<yes|no>

为上下文的创建创建一个10bit的像素格式（默认： yes）。要求使用16位的半浮点帧缓冲器，而不是8位的整数帧缓冲器。

（macOS且cocoa-cb独占）

--cocoa-cb-output-csp=<csp>

这将设置图层的色彩空间，以激活 macOS 色彩转换。根据所使用的色彩空间，系统的 EDR (HDR) 支持将被激活。要获得正确的结果，需要将其设置为 VO 目标的色彩原色/转移特性。建议将此开关与 --target-trc 和 --target-prim 一起使用。

<csp> 可以是以下值之一：

auto:

Sets the color space to the icc profile of the screen (default).

display-p3:

DCI P3 primaries, a D65 white point and the sRGB transfer function.

display-p3-hlg:

DCI P3 primaries, a D65 white point and the Hybrid Log-Gamma (HLG) transfer function.

display-p3-pq:

DCI P3 primaries, a D65 white point and the Perceptual Quantizer (PQ) transfer function.

display-p3-linear:

DCI P3 primaries, a D65 white point and linear transfer function.

dci-p3:

DCI P3 color space.

bt.2020:

ITU BT.2020 color space.

bt.2020-linear:

ITU BT.2020 color space and linear transfer function.

bt.2100-hlg:

ITU BT.2100 and the Hybrid Log-Gamma (HLG) transfer function.

bt.2100-pq:

ITU BT.2100 and the Perceptual Quantizer (PQ) transfer function.

bt.709:

ITU BT.709 color space.

srgb:

sRGB colorimetry and non-linear transfer function.

srgb-linear:

Same as sRGB but linear transfer function.

rgb-linear:

RGB and linear transfer function.

adobe:

Adobe RGB (1998) color space.

（macOS且cocoa-cb独占）

--macos-title-bar-appearance=<appearance>

设置标题栏的外观（默认： auto）。并非所有的外观和 --macos-title-bar-material 材质的组合都是有意义的或者是唯一的。当前macOS版本不支持的外观会回退到默认值。

<appearance> 可以是下列之一：

auto:

检测系统设置并适当地设置标题栏的外观。在macOS 10.14上，它也能检测到运行时的变化

aqua:

标准的macOS浅色外观

darkAqua:

标准的macOS暗色外观(macOS 10.14+)

vibrantLight:

充满活力的浅色外观

vibrantDark:

充满活力的深色外观

aquaHighContrast:

浅色无障碍外观(macOS 10.14+)

darkAquaHighContrast:

深色无障碍外观(macOS 10.14+)

vibrantLightHighContrast:

活力的浅色易读性外观(macOS 10.14+)

vibrantDarkHighContrast:

活力的深色易读性外观(macOS 10.14+)

--macos-title-bar-material=<material>

设置标题栏的材质（默认： titlebar）。所有过时的材质不应该在macOS 10.14+上使用，因为它们的功能没有保证。不是所有的材质和 --macos-title-bar-appearance 的组合都有意义，也不是唯一的。你当前的macOS版本不支持的材质会回退到默认值。（macOS且cocoa-cb独占）

<material> 可以是以下的一种：

titlebar:

标准的macOS标题栏材质

selection:

标准的macOS选择材质

menu:

标准的macOS菜单材质(macOS 10.11以上)

popover:

标准的macOS弹出窗口材质(macOS 10.11+)

sidebar:

标准的macOS侧边栏材质(macOS 10.11+)

headerView:

标准的macOS标题视图材质(macOS 10.14+)

sheet:

标准的macOS页面材质(macOS 10.14+)

windowBackground:

标准的macOS窗口背景材质(macOS 10.14+)

hudWindow:

标准的macOS hudWindow材质(macOS 10.14+)

fullScreen:

标准的macOS全屏材质(macOS 10.14+)

toolTip:

标准的macOS工具提示材质(macOS 10.14+)

contentBackground:

标准的macOS内容背景材质(macOS 10.14+)

underWindowBackground:

标准的macOS窗口下的背景材质(macOS 10.14+)

underPageBackground:

标准的macOS页面下的背景材质(在macOS 10.14+中已过时)

dark:

标准的macOS深色材质(在macOS 10.14+中已过时)

light:

标准的macOS浅色材质(macOS 10.14+)

mediumLight:

标准的macOS中浅材质(macOS 10.11+, 在macOS 10.14+中已过时)

ultraDark:

标准的macOS超深材质(macOS 10.11+, 在macOS 10.14+中已过时)

--macos-title-bar-color=<color>

设置标题栏的颜色（默认：完全透明）。受 --macos-title-bar-appearance 和 --macos-title-bar-material 的影响。颜色语法参见 --sub-color

--macos-fs-animation-duration=<default|0-1000>

设置全屏调整大小动画的持续时间，单位是ms（默认： default）。默认值略小于系统的动画持续时间（500ms），以防止当一个异步动画的结束与系统全屏动画的结束同时发生时出现一些问题。设置任何高于500ms的时间都只会在系统宽屏动画结束后过早地取消调整大小的动画。上限仍然设置为1000ms，因为苹果或用户有可能改变系统的默认值。不过任何高于1000ms的东西都显得太长了，无论如何都不应该被设置。（macOS且cocoa-cb独占）

--macos-app-activation-policy=<regular|accessory|prohibited>

改变应用程序的激活策略。accessory使得Dock中的mpv图标可以被隐藏（默认： regular）。

（macOS独占）

--macos-geometry-calculation=<visible|whole>

这将改变用于计算窗口的屏幕位置和大小的矩形（默认： visible）。 visible 考量菜单栏和Dock，窗口只在可见的屏幕框架矩形内定位/大小， whole 考量整个屏幕框架矩形，忽略了菜单栏和Dock。之前的其他限制仍然适用，比如窗口不能放在菜单栏的上面等等。

（macOS独占）

--macos-render-timer=<timer>

设置帧渲染与显示垂直刷新率同步的模式（默认： callback）。（macOS Vulkan(macvk)独占）

<timer> 可以是以下之一：

callback:

同步到CVDisplayLink回调

precise:

同步到CVDisplayLink回调提供的下一个垂直显示刷新的时间信息

system:

无手动同步，依赖于层机制和下一个可绘制的情况

feedback:

与precise相同，但使用presentation反馈核心机制

--android-surface-size=<WxH>

设置Android gpu上下文使用的渲染表面的尺寸。如果尺寸在运行期间发生变化（例如，如果设备被旋转），需要由嵌入的应用程序通过surfaceChanged回调进行设置。

（Android 和 --gpu-context=android 独占）

--gpu-sw

即使检测到软件渲染器也继续。

--gpu-context=<context1,context2,...[,]>

指定要使用的 GPU 上下文的优先级列表。值 auto （默认）选择默认自动探测顺序的GPU上下文。你也可以通过 help 来获得后端编译的完整列表（按自动探测顺序排序）。

auto

自动选择（默认）

win

Win32/WGL

winvk

VK_KHR_win32_surface

angle

Direct3D11通过OpenGL ES转译层ANGLE。这几乎支持 win 后端所做的一切（如果ANGLE的构建足够新）

dxinterop（实验性的）

Win32，使用WGL进行渲染，使用Direct3D 9Ex进行呈现。在Nvidia和AMD上工作。较新的Intel芯片和最新的驱动也适用

d3d11

Win32，使用原生Direct3D 11渲染

x11

X11/GLX（已过时/遗留，现在优选EGL）

x11vk

VK_KHR_xlib_surface

wayland

Wayland/EGL

waylandvk

VK_KHR_wayland_surface

drm

DRM/EGL

displayvk

VK_KHR_display。这个后端大致相当于Vukan的DRM/EGL，允许通过Vulkan直接渲染而无需显示管理器

x11egl

X11/EGL

android

Android/EGL。需要 --wid 被设置为 android.view.Surface

macvk

macOS上使用一个转译层（实验性的），通过Metal surface支持的Vulkan

--gpu-api=<type>

控制哪种类型的图形API将被接受：

auto

使用任何可用的API（默认）

opengl

只允许OpenGL（需要OpenGL 2.1+或GLES 2.0+）

vulkan

只允许Vulkan（需要一个有效的/工作的 --spirv-compiler ）

d3d11

只允许 --gpu-context=d3d11

--opengl-es=<mode>

控制哪种类型的OpenGL上下文将被接受

auto

允许所有类型的OpenGL（默认）

yes

只允许GLES

no

只允许桌面/核心GL

--fbo-format=<fmt>

选择用于FBOs的纹理的内部格式。该格式可以影响视频输出的性能和质量。 fmt 可以是：rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f, rgba12, rgba16, rgba16f, rgba16hf, rgba32f之一。

默认： auto ，首先尝试使用16位浮点（rgba16f, rgba16hf），如果没有这些浮点，则回退到rgba16。最后，如果先前的所有格式都不可用，则尝试使用rgb10_a2或rgba8。

--gamma-factor=<0.1..2.0>

设置一个额外的原始伽玛系数（默认：1.0）。如果用其他方式调整伽玛（比如用 --gamma 选项或按键绑定和 gamma 属性），该值将与其它伽玛值相乘。

此选项已过时，将来可能会被移除。

--gamma-auto

根据环境照明条件自动修正伽马值（为明亮的房间添加一个伽马增强）。

此选项已过时，将来可能会被移除。

注意：只在macOS上实现。

--image-lut=<file>

指定一个自定义的LUT文件（Adobe .cube格式），在图像解码过程中应用到颜色上。LUT的确切解释取决于 --image-lut-type 的值。（ --vo=gpu-next 独占）

--image-lut-type=<value>

控制送入和送出指定为 --image-lut 的LUT的颜色值的解释。有效值是：

auto

从标记的元数据中自动选择LUT的解释，否则就回退到 native （默认）

native

在解码为RGB之前，在其原始色彩空间中应用于原始图像内容。例如，对于HDR10图像，这将是在0.0 - 1.0的范围内输入PQ编码的YCbCr值

normalized

应用于标准化的RGB图像内容，从其原始色彩编码解码后，但在线性化之前

conversion

完全取代了颜色解码。这种类型的LUT应该摄入图像的原生色彩空间，并输出标准化的非线性RGB

--target-colorspace-hint

如果可能的话，自动设置显示器的输出色彩空间，来传递流的输入值（例如，用于HDR直通）。需要一个支持的驱动程序和 --vo=gpu-next

--target-prim=<value>

指定显示器的色彩原色。当不使用ICC色彩管理时，视频色彩将被适应到这个色彩空间。有效值是：

auto

禁用任何适应，除了非典型的色彩空间。具体而言，宽/非典型色域会自动适应BT.709，而标准色域（即BT.601和BT.709）的内容不会被触及（默认）

bt.470m

ITU-R BT.470M

bt.601-525

ITU-R BT.601（525线标清系统，如NTSC），SMPTE 170M/240M

bt.601-625

ITU-R BT.601（625线标清系统，如PAL/SECAM），ITU-R BT.470 B/G

bt.709

ITU-R BT.709（高清），IEC 61966-2-4（sRGB），SMPTE RP177 Annex B

bt.2020

ITU-R BT.2020 (UHD)

apple

苹果RGB

adobe

Adobe RGB (1998)

prophoto

ProPhoto RGB (ROMM)

cie1931

CIE 1931 RGB (不要与CIE XYZ混淆)

dci-p3

DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2

v-gamut

松下 V-Gamut (VARICAM) primaries

s-gamut

索尼 S-Gamut (S-Log) primaries

--target-trc=<value>

指定显示器的转换特性（伽玛）。当不使用ICC色彩管理时，视频色彩将被调整到此曲线。有效值是：

auto

禁用任何适应，除了非典型的转换。具体来说，HDR或线性光源材料会自动转换为伽玛2.2，而SDR内容则不被触及（默认）

bt.1886

ITU-R BT.1886曲线（假定对比度为无限）

srgb

IEC 61966-2-4（sRGB）

linear

线性亮度输出

gamma1.8

纯功率曲线（伽玛1.8），也被用于苹果RGB

gamma2.0

纯功率曲线（伽玛2.0）

gamma2.2

纯功率曲线（伽玛2.2）

gamma2.4

纯功率曲线（伽玛2.4）

gamma2.6

纯功率曲线（伽玛2.6）

gamma2.8

纯功率曲线（伽玛2.8），也被用于BT.470-BG

prophoto

ProPhoto RGB (ROMM)

pq

ITU-R BT.2100 PQ（感知量化器）曲线，又名SMPTE ST2084

hlg

ITU-R BT.2100 HLG（混合对数伽马）曲线，又名ARIB STD-B67

v-log

松下V-Log（VARICAM）曲线

s-log1

索尼S-Log1曲线

s-log2

索尼S-Log2曲线

备注

当使用HDR输出格式时，mpv将按照指定的曲线进行编码，但它不会设置任何HDMI标志或其它信号，这些信号可能是目标设备正确显示HDR信号所需的。用户在使用这些信号格式进行显示之前，应该独立保证这一点。

--target-peak=<auto|nits>

指定输出显示器的测量峰值亮度，单位是cd/m^2（又名尼特）。这个亮度的解释取决于设置的 --target-trc 。在所有情况下，它对将被发送到显示器的信号值施加了一个限制。如果信号源超过了这个亮度水平，将插入一个色调映射滤镜。对于HLG来说，它还有一个额外的作用，就是对逆向OOTF进行参数化，以便获得与母版显示器一致的色度结果。对于SDR，或者当使用ICC profile（ --icc-profile ）时，将其设置为高于203的值，基本上会使显示器被视为变相的HDR显示器。（参见下方的注意）

在 auto 模式下（默认），所选择的峰值是基于使用中的TRC的一个适当的值。对于SDR曲线，它使用203。对于HDR曲线，它使用203 * 转换函数的额定峰值。

备注

当使用SDR转换函数时，通常不需要这样做，而且设置它可能会导致非常意外的结果。 它 有用的一个场景是如果你想用传统的转换函数和校准设备来校准HDR显示器。在这种情况下，你可以将你的HDR显示器设置为高亮度，如800cd/m^2，然后将其校准到一个标准曲线，如gamma2.8。将这个值设置为800，然后指示mpv将其作为一个具有给定峰值的HDR显示器。在不可能向显示器输入PQ或HLG的环境中，这可能是一个很好的选择，并且使mpv有可能使用HDR显示，而不管操作系统是否支持HDMI HDR元数据。

在这样的设置中，我们强烈推荐将 --tone-mapping 设置为 mobius 或甚至 clip

--target-contrast=<auto|10-1000000|inf>

指定输出显示的测量对比度。--target-contrast 与 --target-peak 值一起用于计算显示器的黑点。在HDR色调映射期间用于黑点补偿。默认值为 auto，它假设典型的SDR显示器具有1000:1的对比度，或者在使用HDR --target-trc 时假定具有无限对比度。 inf 对比度指定具有完美黑色级别的显示器，实际上是OLED显示器。（ --vo=gpu-next 独占）

--target-gamut=<value>

限制显示的色域。您可以使用此选项输出例如 DCIP3-in-BT.2020 等色彩。将 --target-prim 设为包含色彩空间的基色（数值将被编码到基色中），将 --target-gamut 设为要限制色彩的色域。取值与 --target-prim 相同。（ --vo=gpu-next 独占）

--target-lut=<file>

指定一个自定义的LUT文件（Adobe .cube格式），在屏幕上显示之前应用于颜色。这个LUT是在编码到目标色彩空间后，以标准化的RGB值输入的，所以在应用 ---target-trc 之后。（ --vo=gpu-next 独占）

--tone-mapping=<value>

指定用于将图像色调映射到目标显示上的算法。这与HDR->SDR转换和降低色域有关（例如，在标准色域显示器上播放BT.2020内容）。有效值是：

auto

根据内部启发式方法选择最佳曲线（默认）

clip

硬性裁切任何超出范围的数值。当你关心范围内值的完美色彩准确性时，使用这个方法，代价是完全扭曲范围外的值。一般不推荐使用

mobius

Reinhard对具有线性截面的Möbius变换的推广。平滑地映射范围外的值，同时尽可能地保留范围内材料的对比度和颜色。当你关心颜色的准确性而不是细节的保留时，使用它。这介于 clip 和 reinhard 之间，取决于 --tone-mapping-param

reinhard

Reinhard色调映射算法。非常简单的连续曲线。保留了图像的整体亮度，但使用了非线性对比度，这导致了细节的扁平化和色彩精度的下降

hable

类似于 reinhard ，但更好地保留了暗部和亮部的细节（略带sigmoidal），代价是所有东西都略微变暗/变不饱和。由John Hable开发，用于视频游戏中。当你关心细节的保存而不是颜色/亮度的准确性时，就使用它个。这大致相当于 --tone-mapping=reinhard --tone-mapping-param=0.24 。如果可能的话，你还应该启用 --hdr-compute-peak 以获得最佳效果

bt.2390

ITU-R报告BT.2390中指定的感知色调映射曲线（EETF）

gamma

拟合色调曲线之间的对数转换

linear

将整个参考色域线性地拉伸（线性倍数）到显示

spline

感知线性单轴多项式（ --vo=gpu-next 独占）

bt.2446a

在ITU-R报告BT.2446中指定的HDR<->SDR映射，方法A。这推荐用于精心制作的内容（ --vo=gpu-next 独占）

st2094-40

SMPTE ST2094-40 附件B中规定的动态HDR10+色调映射方法。在没有元数据的情况下，回退到与输入/输出平均亮度特性相匹配的固定spline（ --vo=gpu-next 独占）

st2094-10

SMPTE ST2094-10 附件B.2中规定的动态色调映射方法。在概念上比ST2094-40简单，但通常产生的结果更差（ --vo=gpu-next 独占）

--tone-mapping-param=<value>

设置色调映射参数。默认情况下，它被设置为特殊的字符串 default ，它映射到一个特定算法的默认值。如果色调映射算法不可调则忽略。这影响到下列色调映射算法：

clip

指定一个额外的线性系数，在裁剪前乘以信号。默认： 1.0

mobius

指定从线性到莫比乌斯变换的过渡点。低于这个点的每一个值都被保证为1:1的映射。这个值越高，结果就越精确，但代价是失去明亮的细节。默认： 0.3，由于初始斜率很陡，它仍然相当准确地保留了范围内的颜色

reinhard

指定显示峰值处的局部对比度系数。默认： 0.5，这表示in-gamut值的亮度将是裁切时的一半左右

bt.2390

指定knee点的偏移量。默认： 1.0，高于原始ITU-R规范的值0.5（ --vo=gpu-next 独占）

gamma

指定函数的指数。默认： 1.8

linear

指定拉伸时使用的缩放系数。默认： 1.0

spline

指定knee点（在PQ空间中）。默认： 0.30

st2094-10

指定knee点的对比度（斜率）。默认： 1.0

--inverse-tone-mapping

如果设置，允许反转色调映射（将SDR扩展到HDR）。不是所有的色调映射曲线都支持。请谨慎使用。（ --vo=gpu-next 独占）

--tone-mapping-max-boost=<1.0..10.0>

允许色调映射算法通过过曝提高图像平均亮度的上限。默认： 1.0，不允许额外提高亮度。2.0的值允许过曝2倍，以此类推。提高这个设置可以帮助揭示黑暗场景中隐藏的细节，但提高得太高会使黑暗场景显得不自然地明亮。（ --vo=gpu 独占）

--tone-mapping-visualize

显示色调映射LUT（PQ-PQ）的活动图。仅用于调试目的。X轴显示PQ输入值，Y轴显示PQ输出值。色调映射曲线显示为绿色/黄色。黄色意味着亮度从源头上被提高了，深蓝色区域显示亮度被降低的地方。额外的彩色区域和线条表示各种显示器限制，以及参考对角线（中性色调映射）和源场景平均亮度信息（如果有的话）。（ --vo=gpu-next 独占）

--gamut-mapping-mode

在完成任何色调映射后，指定用于降低目标显示的图像色域的算法。

auto

自动选择最佳模式（默认）

clip

硬性裁切到色域（每个通道）。非常低质量，但极低性能损耗

perceptual

使用软拐点函数来进行平衡感知的色域映射，以消除裁切区域，并使用色调变换函数来保持饱和度（ --vo=gpu-next 独占）

relative

执行相对比色法，同时保持亮度和色度之间的指数关系（ --vo=gpu-next 独占）

saturation

执行简单的RGB->RGB饱和度映射。输入的R/G/B通道被直接映射到输出的R/G/B通道。不会出现裁切，但会扭曲所有的色调且/或导致褪色的观感（ --vo=gpu-next 独占）

absolute

执行绝对色度剪裁。与 relative 类似，但不适应白点（ --vo=gpu-next 独占）

desaturate

执行恒定亮度比色法，使颜色向白色褪色，直到它们在色域范围内

darken

均匀地使输入略微变暗，以防止高光部分被削掉，然后将色度钳制在输入色域边界，略微偏向于保留色度而不是亮度（ --vo=gpu-next 独占）

warn

不进行色域映射，而只是高亮色域外的像素

linear

线性/均匀地使图像去饱和，以使整个图像进入目标色域（ --vo=gpu-next 独占）

--hdr-compute-peak=<auto|yes|no>

计算每一帧HDR峰值和帧平均亮度，而不是依赖标记的元数据。这些值是局部区域以及几帧的平均值，以防止数值抖动太大。这个选项基本上为你提供了动态的、每个场景的色调映射。需要计算着色器，这是一个相当新的OpenGL特性，而且在某些驱动上可能会表现得很糟糕，所以启用时要自己承担风险。如果支持计算着色器和SSBO，特殊值 auto （默认）将自动启用HDR峰值计算。

--allow-delayed-peak-detect

当使用 --hdr-compute-peak 时，如果对性能有利，允许将检测到的峰值延迟一帧。特别是，当不需要高级渲染时，需要这样做以避免不必要的FBO介入。如果已经有一个indirect传递，例如启用高级缩放时，则没有影响。默认为no。（ --vo=gpu-next 独占，注意 --vo=gpu 始终延迟峰值。）

--hdr-peak-percentile=<0.0..100.0>

考虑输入图像亮度直方图的百分位数作为场景的真实峰值。如果将其设置为100（默认值），则测量最亮的像素。否则，频率分布的顶部逐渐被删减。将其设置得太低将导致非常亮的细节被裁剪，但可以改善具有非常亮的孤立高光的场景的动态亮度范围。除100以外的值会带来轻微的性能损耗。（ --vo=gpu-next 独占）

--hdr-peak-decay-rate=<1.0..1000.0>

用于HDR峰值检测算法的衰减率（默认： 20.0）。这只与 --hdr-compute-peak 启用时有关。更高的值使峰值衰减得更慢，导致更稳定的数值，但代价是更多类似”eye adaptation”的效果（尽管这在一定程度上被 --hdr-scene-threshold 缓解）。0.0的值（可能的最低值）可以禁止所有的平均化，这意味着每一帧的值都直接作为测量值使用，但是对于”noisy”源不推荐这样做，因为它可能导致过度的闪烁。（在信号理论方面，这控制了IIR低通滤波器的时间常数”tau”。）

--hdr-scene-threshold-low=<0.0..100.0>, --hdr-scene-threshold-high=<0.0..100.0>

亮度差异被认为是场景变化的最低和最高阈值（单位：dB）（默认：1.0低，3.0高）。这只有在启用 --hdr-compute-peak 时才相关。通常情况下，画面亮度的小波动会被峰值平均机制补偿，但对于亮度的大跳动，会导致画面过亮或过暗长达几秒钟，这取决于 --hdr-peak-decay-rate 的值。为了解决这个问题，当运行中的平均值和当前帧之间的亮度超过低阈值时，mpv将使averaging filter更加积极，直到高阈值的极限（此时filter会变得即时）。

--hdr-contrast-recovery=<0.0..2.0>, --hdr-contrast-smoothness=<1.0..100.0>

启用HDR对比度恢复算法，旨在在色调映射后增强HDR视频的对比度。强度（默认值：0.0）表示对比度恢复的程度，0.0表示完全禁用，1.0表示100%强度。允许大于1.0的值，但可能会导致过多的锐化效果。平滑度（默认值：3.5）表示用于获取对比度信息的HDR源的低通滤波程度 - 2.0的值相当于2倍降采样。低DPI显示器的用户（<= 100）可能希望降低这个值，而高DPI显示器（“retina”）的用户可能希望增加它。（ --vo=gpu-next 独占）

--use-embedded-icc-profile

加载媒体文件（如PNG图像）中的内嵌ICC profile（默认： yes）。请注意，这个选项只有在同时使用显示ICC profile（ --icc-profile 或 --icc-profile-auto ）时才有效，而且还需要LittleCMS 2支持。

--icc-profile=<file>

加载一个ICC profile，并使用它来转换视频RGB到屏幕输出。需要LittleCMS 2的编译支持。它覆盖了 --target-prim, --target-trc 和 --icc-profile-auto 选项。

--icc-profile-auto

自动选择当前由操作系统的显示设置指定的ICC显示profile。

注意：在Windows上，默认profile必须是一个ICC profile。不支持WCS profiles。

使用libmpv和渲染API的应用程序需要通过 MPV_RENDER_PARAM_ICC_PROFILE 提供ICC profile。

--icc-cache

是否存储和加载从ICC profile中创建的3D LUTs缓存（默认： yes ）。这可以用来加快加载速度，因为LittleCMS 2创建一个3D LUT可能需要一段时间。请注意，这些文件包含了未压缩的LUTs。它们的大小取决于 --icc-3dlut-size ，而且可能非常大。

对于 --vo=gpu-next , 如果超过缓存限制（1.5GiB），在过去 24 小时内未被访问的文件可能会被清除。

对于 --vo=gpu ，这不是自动清理的，所以旧的、未使用的缓存文件可能会无限期地存在。

--icc-cache-dir

储存icc缓存的目录。如果未设置，缓存将被存储在系统的缓存目录下（通常是 ~/.cache/mpv ）。

--icc-intent=<value>

指定用于颜色转换的ICC意图（当使用 --icc-profile 时）。

0

感知的

1

相对色度（默认）

2

饱和度

3

绝对色度

--icc-3dlut-size=<auto|RxGxB>

从ICC profile生成的3D LUT在每个维度的大小。默认值为 auto ，意味着根据配置文件的特征自动选择大小。大小的范围从2到512。

注意： 除测试外， 强烈 不建议将此选项设置为 auto 以外的任何值。

--icc-force-contrast=<no|0-1000000|inf>

用一个特定的值覆盖目标设备的检测对比度。如果可能的话，这是从profile中自动检测出来的，但对于某些profile来说，它可能会丢失，导致对比度被认为是无限的。因此，视频可能看起来比预期的更暗。如果是这种情况，设置这个选项可能有帮助。这只影响BT.1886内容。默认的 no 表示使用profile的值。特殊值 inf 会使BT.1886曲线被当作纯功率的伽玛2.4函数处理。

--icc-use-luma

使用ICC配置文件内的亮度值。（ --vo=gpu-next 独占）

--lut=<file>

指定一个自定义的LUT（Adobe .cube格式），作为颜色转换的一部分应用到颜色上。具体解释取决于 --lut-type 的值。（ --vo=gpu-next 独占）

--lut-type=<value>

控制送入和送出指定为 --lut 的LUT的颜色值的解释。有效值是：

auto

从标记的元数据中自动选择LUT的解释，否则就退回到 native （默认）

native

在转换到输出色彩空间之前，应用于原始RGB色彩空间的原始图像内容（非线性亮度）

normalized

在转换到输出色彩空间之前，应用于线性亮度下的标准化RGB图像内容

conversion

完全取代了从图像色彩空间到输出色彩空间的转换。如果有这样的LUT，它具有最高的优先权，并优先于任何ICC profile，以及与色调映射和输出比色有关的选项（ --target-prim, --target-trc 等）。

--blend-subtitles=<yes|video|no>

在插值和/或色彩管理之前，将字幕直接混合到放大后的视频帧上（默认： no）。启用这个功能会使字幕受到 --icc-profile, --target-prim, --target-trc, --interpolation, --gamma-factor 和 --glsl-shaders 的影响。当使用 --interpolation 时，它还能提高字幕的性能。

启用这个功能的缺点是它将字幕限制在视频的可见部分，所以（例如）你不能让字幕存在于视频下面的黑边上。

如果选择 video ，行为类似于 yes ，但字幕是以视频的原始分辨率绘制的，并随着视频的缩放而缩放。

警告

这改变了处理字幕颜色的方式。通常情况下，字幕的颜色被假定为sRGB，并按此进行色彩管理。启用这个选项后，它们将被视为在视频的色彩空间中。如果你想让softsubbed ASS signs与视频颜色相匹配，这样做很好，但可能会导致SRT字幕或类似的东西看起来有点不对劲。

--background=<none|color|tiles>

如果帧有 Alpha 分量，则决定将其与哪种背景（如果有的话）混合。如果没有 alpha 分量，则不做任何处理。

color

将边框与背景颜色（ --background-color ，通常为黑色）混合。

tiles

将边框与 16x16 灰/白色方格背景混合（默认）。

none

不混合帧，保持 Alpha 不变。

在 mpv 0.38.0 之前，该选项接受指定背景颜色的颜色值。现在由 --background-color 选项完成。请使用该选项。

--background=<color>

用来绘制mpv窗口中没有被视频覆盖的部分的颜色。参见 --sub-color 选项关于如何定义颜色。

--border-background=<none|color|tiles>

类似 --background 但只应用于窗口的黑边/边框区域。 vo=gpu-next 独占。默认： color

--opengl-rectangle-textures

强制使用矩形纹理（默认： no）。通常情况下，这不应该比普通纹理有任何优势。请注意，硬件解码会覆盖这个标志。可能在任何时候被移除。

--gpu-tex-pad-x, --gpu-tex-pad-y

将视频源的纹理放大的像素量。仅用于调试（通常纹理的大小是准确的，但由于硬件解码的interop，我们可能需要用额外的填充interop ，这可以用这些选项来测试）。可能在任何时候被移除。

--opengl-early-flush=<yes|no|auto>

在渲染完一帧后，在试图显示之前调用 glFlush() （默认： auto）。在某些情况下可以解决卡顿问题，在其它情况下可能会导致卡顿。 auto 模式只有在渲染器在渲染后要等待一段时间时才会调用 glFlush() ，而不是立即翻转GL前后缓冲区（也就是说，在显示同步模式下不会调用）。

在macOS上，这个功能始终被停用，因为它只会导致性能问题和其它倒退。

--gpu-dumb-mode=<yes|no|auto>

这种模式是非常受限制的，并将禁用大多数扩展功能。这包括高质量的缩放器和自定义着色器！

它适用于不支持FBOs的硬件（包括GLES，它对FBOs的支持不足），或者从坏的或旧的硬件中获得更高的性能。

如果有需要的话，这个模式会自动强制执行，这个选项在调试时非常有用。如果没有使用需要FBO的功能，默认的 auto 会自动启用它。

这个选项在未来可能会被默默移除。

--gpu-shader-cache

是否存储和加载已编译的GLSL着色器（默认： yes ）。通常情况下，着色器的编译速度非常快，所以一般不需要这样做。这对任何涉及 GLSL 到 SPIR-V 转换的情况都很重要：即 D3D11、ANGLE 或 Vulkan，以及其他一些专有驱动程序。启用它可以提高这些平台的启动性能。

对于 –vo=gpu-next ，如果超过缓存限制（128MiB），在过去 24 小时内未被访问的文件可能会被清除。

对于 --vo=gpu ，这不是自动清理的，所以旧的、未使用的缓存文件可能会无限期的存在。

--gpu-shader-cache-dir

存储gpu着色器缓存的目录。如果未设置，缓存将被存储在系统的缓存目录（通常是 ~/.cache/mpv ）。

--libplacebo-opts=<key>=<value>[,<key>=<value>[,...]]

将额外的原始选项传递给libplacebo渲染后端（用于``–vo=gpu-next``）。可能会覆盖使用常规选项系统设置的任何其他选项的效果。仅用于调试目的。需要libplacebo v6.309或更高版本。详见：

https://libplacebo.org/options/

杂项

--display-tags=tag1,tags2,...

设置应在终端上显示的标签列表。列表中但播放文件中不存在的标签将不会显示。如果一个值以 * 结尾，所有的标签都按前缀匹配（尽管没有通用的globbing）。仅仅传递 * 本质上是过滤。

默认包括一个通用的标签列表，用 --list-options 调用mpv来查看它。

这是一个字符串列表选项。详见 列表选项

--mc=<seconds/frame>

每一帧的最大A-V同步修正（以秒为单位）

--autosync=<factor>

根据音频延迟测量结果逐渐调整A/V同步。指定 --autosync=0 ，默认情况下，将导致帧计时完全基于音频延迟测量。指定 --autosync=1 将做同样的事情，但会巧妙地改变A/V修正算法。如果在 --audio=no 的情况下视频帧数不均匀，通常可以通过将其设置为大于1的整数来解决。该值越高，计时就越接近 --audio=no 。尝试 --autosync=30 以平滑那些没有实现完美音频延迟测量的声音驱动的问题。有了这个值，如果发生大的A/V同步偏移，它们只需要1或2秒就可以解决。这种对突然的A/V偏移的反应时间的延迟应该是打开这个选项的唯一副作用，对所有的声音驱动都是如此。

--video-timing-offset=<seconds>

控制在视频显示目标时间之前多久应该渲染该帧（默认： 0.050）。如果一个视频帧应该在某个时间显示，视频输出驱动将提前开始渲染该帧，然后将执行一个阻塞等待，直到显示时间，然后才“交换”该帧进行显示。渲染不能在前一帧显示之前开始，所以该值隐含受到视频帧率的限制。在正常的视频帧率下，默认值将确保渲染始终在前一帧显示完后立即开始。另一方面，设置一个太高的值会减少低FPS值的响应速度。

这个选项对于使用渲染API的client API用户来说很有意思，因为你可以阻止它限制你的FPS（参见 mpv_render_context_render() 文档）。

这只应用于音频计时模式（例如 --video-sync=audio ）。在其它模式下（ --video-sync=display-... ），视频计时依赖于垂直同步阻塞，不使用此选项。

--video-sync=<audio|...>

播放器如何使音频和视频同步。

如果你使用这个选项，你通常想把它设置为 display-resample 以启用一种计时模式，例如在24Hz的屏幕上播放24fps的视频时尽量不跳帧或重复。

以 display- 开头的模式尝试完全同步输出视频帧到显示上，使用检测到的显示器垂直刷新率作为提示，显示帧的平均速度。这些模式会稍微改变视频速度以匹配显示。参见 --video-sync-... 选项进行微调。这种模式的稳健性因做了一些理想化的假设而进一步降低，这些假设在现实中可能并不总是适用。行为可能取决于视频输出驱动和系统的视频和音频驱动。媒体文件必须使用恒定的帧速率。片段式的VFR可能对某些容器格式也有效（但如mkv无效）。

在某些情况下，播放器会在一段时间内自动恢复到 audio 模式或永久地恢复。这可能发生在帧率很低的视频上，或者帧率无法被检测到。

同样在显示同步模式下，视频播放的打断（比如切换全屏模式，或者简单地调整窗口大小）会跳过本应显示的视频帧，而 audio 模式会在渲染器恢复后显示它们（通常会导致短暂的A/V不同步和视频的“追赶”）。

在mpv0.30.0之前，在严重的A/V不同步时会回退到 audio 模式。这已被改变，因为它不会零星地停止。现在， display-desync 做了它所承诺的事情，并可能以任意的数量与音频不同步，直到它通过跳转被手动修复。

这些模式也需要一个垂直同步阻塞的呈现模式。对于OpenGL来说，这被翻译成 --opengl-swapinterval=1 。对于Vulkan，它被翻译成 --vulkan-swap-mode=fifo （或 fifo-relaxed ）。

名称中带有 desync 的模式并不试图保持音频/视频的同步。它们会缓慢（或快速）地取消同步，直到例如下一次跳转发生。这些模式是用来测试的，而非用于认真使用。

audio:

将视频帧计时到音频。这是最稳健的模式，因为播放器不需要对显示器的行为进行任何假设。缺点是它可能会导致偶尔的丢帧或重复。如果音频被禁用，这将使用系统时钟。这是默认模式。

display-resample:

对音频重新采样以匹配视频。这种模式也将尝试调整音频速度来补偿其它漂移（这表示它将每隔一段时间以不同的速度播放音频，以减少A/V差异）。

display-resample-vdrop:

重新采样音频以匹配视频。丢弃视频帧以补偿漂移。

display-resample-desync:

与之前的模式一样，但没有A/V补偿。

display-tempo:

类似于 display-resample ，但是将音频速度变化应用到音频滤镜而不是重采样，以避免音调的变化。注意，一些音频滤镜在速度接近1时表现不佳。建议使用一个附带条件的自动配置预设，当速度过于接近1时，自动切换到 display-resample ，以适应你的滤镜设定。使用 (speed * video_speed_correction) 来获得该条件下的实际播放速度。详见 附带条件的自动配置预设

display-vdrop:

丢弃或重复视频帧，以补偿不同步的视频（虽然它应该有与 audio 相同的效果，但实现却非常不同）。

display-adrop:

丢弃或重复音频数据以补偿不同步的视频。如果真实的显示器刷新率与报告的或强制的刷新率相差太大，这种模式将引起严重的音频瑕疵。从mpv0.33.0开始，这个模式作用于整全部音频帧，而不是单个采样。

display-desync:

同步视频到显示，并让音频自行播放。

desync:

同步视频到系统时钟，并让音频自行播放。

--video-sync-max-factor=<value>

尝试将视频的FPS与显示的FPS相匹配的最大倍数（默认： 5）。

例如，如果设置为1，只要速度变化不超过 --video-sync-max-video-change 设置的值，视频的FPS就会被强制为显示FPS的整数倍。

关于该选项如何影响插值，请参见 --interpolation-threshold

--video-sync-max-video-change=<value>

应用于 --video-sync=display-... 的视频的最大速度差，以百分比为单位（默认： 1）。如果显示器和视频刷新方式在给定范围内不匹配，显示同步模式将被禁用。它还会尝试倍数：在60赫兹的屏幕上播放30帧的视频，每隔一帧就会重复一次。在60赫兹的屏幕上播放24帧的视频将以2-3-2-3-…的模式播放视频。

默认设置不够宽松，无法将23.976帧的视频加速到25帧。我们认为音调变化过于极端，默认情况下不允许这种行为。将这个选项设置为 5 的值来启用它。

注意， --video-sync=display-tempo 可避免这种音调的变化。

另注意，在 --video-sync=display-resample 或 --video-sync=display-tempo 模式下，如果需要A/V同步，音频速度将额外被改变一点。参见 --video-sync-max-audio-change

--video-sync-max-audio-change=<value>

在 --video-sync=display-... 的情况下，应用于音频的最大 附加 速度差，以百分比为单位（默认： 0.125）。通常情况下，播放器会以视频的速度播放音频。但如果音频和视频的位置差异太大，例如，由于漂移或其它计时错误，它将试图通过这个额外的系数来加快或减慢音频的速度。如果A/V不同步不能得到补偿，那么太低的值可能会导致视频丢帧或重复，太高的值可能会导致混乱的丢帧，原因是音频“过冲”和在同步逻辑能反应之前跳过多个视频帧。

--mf-fps=<value>

当用 mf:// 从多个PNG或JPEG文件解码时使用的帧速率（默认： 1）。

--mf-type=<value>

mf:// 的输入文件类型（可用：jpeg, png, tga, sgi）。默认情况下，这是从文件扩展名猜测出来的。

--stream-dump=<destination-filename>

读取文件的字节流并将其写入给定的目标文件，而不是播放。目标文件被覆盖。对测试网络相关的行为可能很有用。

--stream-lavf-o=opt1=value1,opt2=value2,...

在用libavformat打开的流上设置AVOptions。未知或拼写错误的选项会被默默地忽略。（它们会在终端输出的verbose模式下被提及，即 --v 。一般而言，我们因为其它的选项，比如用户代理并不是所有的协议都可以使用的，不能输出错误 ，而输出未知选项的错误最终会显得过于嘈杂。）

这是一个按键/值列表选项。详见 列表选项

--backdrop-type=<auto|none|mica|acrylic|mica-alt>

（Windows独占）控制背景/边框样式。

auto:

默认的Windows行为

none:

背景将是黑色或白色，取决于系统的主题设置

mica:

启用Mica样式，这是Windows 11的默认样式

acrylic:

启用Acrylic样式（磨砂玻璃外观）

mica-alt:

与Mica相同，只是反向

--window-affinity=<default|excludefromcmcapture|monitor>

（Windows独占）控制 mpv 的窗口关联行为。

default:

默认的Windows行为

excludefromcapture:

mpv的窗口将完全排除在外部应用程序或屏幕录制软件的捕获范围之外

monitor:

使mpv窗口变为黑屏

--vo-mmcss-profile=<name>

（Windows独占）为视频渲染器线程设置MMCSS profile（默认： Playback ）。

--priority=<prio>

（Windows独占）根据Windows下的预定义优先级，设置mpv进程的优先级。

<prio> 的可能值： idle|belownormal|normal|abovenormal|high|realtime

警告

使用realtime优先级会导致系统锁死。

--force-media-title=<string>

强制将 media-title 属性的内容变成这个值。对于想要设置标题的脚本很有用，而不需要覆盖用户在 --title 中的设置。

--external-files=<file-list>

加载一个文件并添加其所有的轨道。这对一起播放不同的文件很有用（例如来自一个文件的音频与来自另一个文件的视频），或用于高级的 --lavfi-complex （就像同时播放两个视频文件）。

与 --sub-files 和 --audio-files 不同，它包括所有轨道，不会导致默认流选择在“正确的”文件上。这使得它稍微不那么具有侵入性。（在mpv0.28.0及以前，这一点并没有严格执行。）

这是一个路径列表选项。详见 列表选项

--external-file=<file>

CLI/设置文件中的 --external-files-append 的专用别名。每次使用该选项将添加一个新的外部文件。

--cover-art-files=<file-list>

在播放音频时使用一个外部文件作为封面图。这使得它出现在轨道列表上，并受制于自动轨道选择。像 --audio-display 这样的选项控制是否应该选择这样的轨道。

（与用 --external-files 加载文件的区别是，视频轨将被标记为图片，这影响了自动选择的方式。如果传递的文件是视频，只有第一帧会被解码和显示。如果源文件是视频，在播放过程中启用封面图轨道可能会显示一个随机帧。通常情况下，你不应该把视频传递给这个选项，因此本段描述了由实现细节巧合导致的行为。）

这是一个路径列表选项。详见 列表选项

--cover-art-file=<file>

CLI/设置文件中的 --cover-art-files-append 的专用别名。每次使用该选项将添加一个新的外部文件。

--cover-art-auto=<no|exact|fuzzy|all>

是否自动加载 _外部的_ 封面图。类似于 --sub-auto 和 --audio-file-auto 。如果一个视频已经有轨道（没有标记为封面），外部封面将不会被加载。

no:

不自动加载封面图

exact:

加载带有图像文件扩展名的媒体文件（默认）

fuzzy:

加载所有包含媒体文件名的封面图

all:

加载当前目录下的所有图像

详见 --cover-art-files 了解封面图的组成。

参见 --audio-display 关于如何控制封面图的显示（这可用来禁用属于文件一部分的封面图）。

--cover-art-auto-exts=ext1,ext2,...

在使用``cover-art-auto``时尝试匹配的封面艺术文件扩展名。

这是一个字符串列表选项。详见 `List Options`_

--cover-art-whitelist=<no|yes>

是否将文件加载为封面艺术，文件名包括 “AlbumArt”、”Album”、”cover”、”front”、”AlbumArtSmall”、”Folder”、”.folder”、”thumb” 和一个扩展名，扩展名在 --cover-art-auto-exts 中指定。如果 cover-art-auto 为 no ，则此选项无效。

默认： yes

--autoload-files=<yes|no>

自动加载/选择外部文件（默认： yes）。

如果设置为 no ，则不自动加载由 --sub-auto , --audio-file-auto 和 --cover-art-auto 指定的外部文件。如果外部文件被强制添加（如 --sub-files ），它们将不会被自动选择。

这不影响播放列表的扩展、重定向或其它参考文件的加载，比如有序章节。

--stream-record=<file>

将从解复用器接收/读取的数据写入给定的输出文件。输出文件将总是被覆盖而不询问。输出格式由输出文件的扩展名决定。

在录制过程中切换数据流或跳转可能会导致录制被停止和/或文件被破坏。请小心使用。

在解复用器缓存之外跳转会导致输出文件的“跳跃”，但在解复用器缓存内跳转应该不会影响录制。一个例外是，当你向前跳转到足够远的距离，超过了前向缓冲区的大小，在这种情况下，缓冲区停止主动读取。如果是实时流，这将导致数据丢失。

如果这是在运行时设置的，则旧文件被关闭，而新文件被打开。注意，这将只在缓存末尾写入附加的数据，已经缓存的数据不能被写入。你可以尝试使用 dump-cache 命令作为替代。

外部文件（ --audio-file 等）会被忽略，它只对“主”文件起作用。对使用有序章节的文件或EDL文件使用这个命令，一般而言也不能正确工作。

因为它使用FFmpeg的libavformat来写入输出文件，所以会有一些小问题。例如，典型的情况是，只有当输出格式与输入格式相同时，它才能工作。即使使用 ffmpeg 工具也是这种情况。其中一个原因是 ffmpeg 和它的库包含了某些针对这些问题的hacks和变通方法，外部用户无法使用。

--lavfi-complex=<string>

设置一个“复合的”libavfilter滤镜，这表示单个graph滤镜可以接受来自多个音视频源轨道的输入。该graph可以产生单一的音频或视频输出（或两者）。

目前，该graph滤镜的标签被用来选择参与的输入轨道和音频/视频输出。以下规则适用：

• 一个形式为 aidN 的标签选择音频轨道N作为输入（例如 aid1 ）

• 一个形式为 vidN 的标签选择视频轨道N作为输入

• 一个名为 ao 的标签将被连接到音频输出

• 一个名为 vo 的标签将被连接到视频输出

每个标签只能使用一次。如果你想把例如一个音频流用于多个滤镜，你需要使用 asplit 滤镜。多个视频或音频输出是不可能的，但你可以使用滤镜将它们合并成一个。

在运行时不可能改变连接到滤镜的轨道，除非你明确改变 lavfi-complex 属性并设置新的轨道分配。当graph被改变时，轨道的选择也会根据使用的标签而改变。

其它的轨道，只要它们没有连接到滤镜，且相应的输出也没有连接到滤镜，仍然可以用正常的方法自由改变。

请注意，正常的滤镜链（ --af , --vf ）是应用在复合graphs（如 ao 标签）和实际输出之间。

示例

• --lavfi-complex='[aid1] [aid2] amix [ao]' 同时播放轨道1和2。

• --lavfi-complex='[vid1] [vid2] vstack [vo]' 堆叠视频轨1和2并同时播放它们。注意，两个轨道需要有相同的宽度，否则滤镜初始化会失败（你可以在 vstack 滤镜之前添加 scale 滤镜来修正尺寸）。为了从其它文件加载视频轨道，你可以使用 --external-file=other.mkv

• --lavfi-complex='[vid1] [vid2] [vid3] hstack=inputs=3 [vo]' 使用输入选项可堆叠 2 个以上音轨。

• --lavfi-complex='[aid1] asplit [t1] [ao] ; [t1] showvolume [t2] ; [vid1] [t2] overlay [vo]' 播放音轨1，并将每个扬声器的测量音量覆盖在视频轨1上。

关于可用的滤镜，详见FFmpeg libavfilter文档。

--metadata-codepage=<codepage>

各种输入元数据的代码页（默认： auto ）。这会影响文件标签、章节标题等的解释方式。在大多数情况下，这只会转换为UTF-8，因为非UTF-8的代码页很少使用。

参见 --sub-codepage 选项，关于如何指定代码页以及关于自动检测和代码页转换的进一步细节。（底层代码相同）

转换不应用于在运行时更新的元数据。

音频输出驱动

音频输出驱动是连接不同音频输出设施的接口。其语法是

--ao=<driver1,driver2,...[,]>

指定一个要使用的音频输出驱动的优先级列表。

如果这个列表末尾有 , ，mpv将回退到不在列表中的驱动程序。

备注

参见 --ao=help 获取已编译的音频输出驱动的列表，按自动探测顺序排列。

可用的音频输出驱动有：

alsa

ALSA音频输出驱动

该AO支持以下全局选项：

--alsa-resample=yes

启用ALSA重采样插件。（默认禁用，因为一些驱动程序在某些情况下报告了不正确的音频延迟）。

--alsa-mixer-device=<device>

设置与 ao-volume 一起使用的混音器设备（默认： default ）。

--alsa-mixer-name=<name>

设置混音器元素的名称（默认： Master ）。例如，这是 PCM 或 Master

--alsa-mixer-index=<number>

设置混音器通道的索引（默认： 0）。考虑到 “amixer scontrols” 的输出，那么索引就是元素名称后面的数字。

--alsa-non-interleaved

允许输出非交错格式（如果音频解码器使用这种格式）。目前默认禁用，因为一些流行的ALSA插件在使用非交错格式时完全失效。

--alsa-ignore-chmap

不读取或设置ALSA设备的声道图 —— 只请求所需的声道数，然后将音频原封不动的传递给它。此选项很可能不应被使用。它在调试中可能很有用，或者对于有特殊设计的ALSA配置的静态设置（在这种情况下，你应该始终用 --audio-channels 强制使用相同的布局，否则它只对使用ALSA设备暗含布局的文件有效）。

--alsa-buffer-time=<microseconds>

设置请求的缓冲时间，以微秒为单位。数值 0 可以跳过ALSA API的任何请求。该选项和 --alsa-periods 选项使用ALSA的 near 函数来设置请求的参数。如果这样做的结果是一个空的配置集，那么就跳过设置这些参数。

这两个选项都控制缓冲区的大小。过小的缓冲区会导致较高的CPU使用率和音频丢失，而过大的缓冲区则会导致音量变化和其它滤镜的延迟。

--alsa-periods=<number>

从ALSA API请求的周期数。详见 --alsa-buffer-time 以了解更多。

警告

要获得多声道/环绕声音频，使用 --audio-channels=auto 。 这个选项的默认值是 auto-safe，它将明确地拒绝多声道输出，因为无法检测某个声道布局是否被实际支持。

你也可以尝试 使用上混插件 。这使 default 设备启用多声道音频，并在共享访问的情况下自动上混，因此同时播放立体声和多声道音频将按预期工作。

oss

OSS音频输出驱动

jack

JACK（Jack Audio Connection Kit）音频输出驱动

支持以下全局选项：

--jack-port=<name>

连接到指定名称的端口（默认： physical ports）

--jack-name=<client>

传递给JACK的客户端名称（默认： mpv ）。如果你想让某些连接自动建立，这很有用。

--jack-autostart=<yes|no>

必要时自动启动jack（默认： no）。注意这往往是不可靠的，并且会使stdout中充斥着服务器信息。

--jack-connect=<yes|no>

自动建立与输出端口的连接（默认： yes）。当启用时，输出声道的最大数量将被限制到可用输出端口的数量。

--jack-std-channel-layout=<waveext|any>

选择标准的声道布局（默认： waveext）。JACK本身没有声道布局的概念（例如指定一个声道应该映射到对应的扬声器） —— 它只是接收应用程序输出的任何东西，并将其重新连接到用户定义的任何地方。这意味着用户和应用程序负责处理声道的布局。 waveext 使用 WAVE_FORMAT_EXTENSIBLE 顺序，尽管它是由微软定义的，但它是许多系统的标准。值 any 使JACK接受来自音频滤镜链的任何东西，无视声道布局，也无需重新排序。这种模式可能不是很有用，除了用于调试或固定的设置。

coreaudio （macOS独占）

使用AudioUnits和CoreAudio声音服务的原生macOS音频输出驱动。

当播放有损格式时，自动重定向到 coreaudio_exclusive

支持以下全局选项：

--coreaudio-change-physical-format=<yes|no>

更改物理格式为与请求的音频格式相似（默认： no）。这样有利于多声道音频输出将实际起效。缺点是它会改变系统全局的音频设置。这相当于在 Audio MIDI Setup 工具中的 Audio Devices 对话框中改变 Format 设置。注意这不会影响所选的扬声器设置。

--coreaudio-spdif-hack=<yes|no>

尝试将AC3/DTS数据作为PCM透传。这对不支持AC3的驱动很有用。它将 AC3 数据转换为浮点，并假定驱动程序将做逆向转换，这意味着传统的A/V接收机将把它作为压缩的IEC框架的AC3流来接收，而忽略它被标记为PCM 。这禁用了正常的AC3直通功能（即使设备报告支持它）。使用时要特别小心。

coreaudio_exclusive （macOS独占）

原生macOS音频输出驱动，使用直接设备访问和独占模式（绕过声音服务）

avfoundation (macOS only)

使用 AVFoundation 中 AVSampleBufferAudioRenderer 的原生 macOS 音频输出驱动程序，支持 空间音频.

警告

Turning on spatial audio may hang the playback if mpv is not started out of the bundle, though playback with spatial audio off always works.

openal

OpenAL音频输出驱动

--openal-num-buffers=<2-128>

指定音频缓冲区的使用数量。值越低CPU的使用率越低。默认： 4

--openal-num-samples=<256-32768>

指定用于每个缓冲区的完整采样的数量。更高的值利于降低CPU占用率。默认： 8192

--openal-direct-channels=<yes|no>

启用OpenAL Soft的直接声道扩展，以避免ambisonics或HRTF的音染。默认： yes

pulse

PulseAudio音频输出驱动

支持以下全局选项：

--pulse-host=<host>

指定要使用的主机。空的 <host> 字符串使用本地连接， “localhost” 则使用网络传输（很可能不是你期望的）

--pulse-buffer=<1-2000|native>

以毫秒为单位设置音频缓冲区的大小。较高的值可以缓冲更多的数据，并且有较低的缓冲区不足的概率。较小的值使音频流反应更快，例如对播放速度变化的响应。 “native” 让声音服务自行设定缓冲

--pulse-latency-hacks=<yes|no>

启用hack来解决PulseAudio的时间错误（默认： yes）。如果启用，mpv将自己进行详细的延迟计算。如果禁用，它将使用PulseAudio自动更新的时间信息。禁用这个功能可能对网络音频或一些插件有帮助，而启用它可能对一些未知的情况有帮助（由于 PulseAudio 16.0 的已知错误，目前已启用）

--pulse-allow-suspended=<yes|no>

即使sink挂起也允许mpv使用PulseAudio（默认： no）。如果PulseAudio以桥接到jack的方式运行，而mpv的sink-input被设置为jack使用的输入，则会很有用。

pipewire

PipeWire音频输出驱动

该音频输出支持以下全局选项：

--pipewire-buffer=<1-2000|native>

设置音频缓冲区，以毫秒为单位。越高的值缓存更多的数据，且具有较低的缓冲区不足概率。值越小，音频流的反应越快，例如对播放速度变化的反应。 “native” 让声音服务自行设定缓冲

--pipewire-remote=<remote>

指定通过本地UNIX套接字连接的PipeWire远程守护进程名称。一个空的 <remote> 字符串使用默认的名为``pipewire-0`` 的远程。

--pipewire-volume-mode=<channel|global>

指定 ao-volume 属性是否应该应用于声道音量或全局音量。默认为全局音量。

sdl

SDL 2.0+音频输出驱动。应该在任何受SDL 2.0支持的平台上工作，但可能需要为你的系统正确的设置 SDL_AUDIODRIVER 环境变量。

备注

该驱动是为了与极其陌生的环境兼容，例如其他驱动程序都无法使用的系统。

支持以下全局选项：

--sdl-buflen=<length>

以秒为单位设置音频缓冲区的长度。只作为声音系统的提示使用。用 -v 播放文件将显示请求的和获得的确切缓冲区大小。如果数值为0，则选择声音系统的默认值。

null

无音频输出，但保持视频播放速度。你可以使用 --ao=null --ao-null-untimed 做基准测试。

支持以下全局选项：

--ao-null-untimed

不模拟一个完美音频设备的计时。这意味着音频解码将尽快的进行，而不是按照系统时钟计时。

--ao-null-buffer

以秒为单位模拟的缓冲区长度

--ao-null-outburst

以采样为单位模拟的块状大小

--ao-null-speed

以倍率为单位模拟的音频播放速度。通常，真实的音频设备不会和系统时钟的速度完全一样。它会有一点偏差，这个选项有助于模拟这种情况。

--ao-null-latency

模拟的设备延时。这是对EOF的补充。

--ao-null-broken-eof

模拟损坏的音频驱动，它总是将固定的设备延迟添加到报告的音频播放位置。

--ao-null-broken-delay

模拟损坏的不能正确报告延迟的音频驱动

--ao-null-channel-layouts

如果不是空值，这是一个声音输出驱动允许的以 , 分隔的声道布局列表。这可以用来测试声道布局的选择。

--ao-null-format

强制声音输出驱动接受的音频输出格式。如果没有设置则接受任何格式。

pcm

原始PCM/WAVE文件编码的音频输出

支持以下全局选项：

--ao-pcm-waveheader=<yes|no>

包括或不包括WAVE header（默认： yes）。如果不包括，将生成raw PCM

--ao-pcm-file=<filename>

把声音写入到 <filename> 而不是默认的 audiodump.wav 。如果指定了 no-waveheader ，则默认为 audiodump.pcm

--ao-pcm-append=<yes|no>

追加到文件中，而不是覆盖写入它。一定要和 no-waveheader 选项一起使用 —— 和 waveheader 一起使用会损坏，因为每次打开文件时都会写入一个WAVE header

sndio

音频输出到OpenBSD sndio声音系统

（注意：仅支持单声道，立体声，4.0/5.1和7.1声道布局）

wasapi

音频输出到Windows音频会话API

该AO支持以下全局选项：

--wasapi-exclusive-buffer=<default|min|1-2000000>

设置独占模式下的缓冲区持续时间（即使用 --audio-exclusive=yes 时）。 default 和 min 分别使用 WASAPI 报告的默认和最小设备周期。你也可以直接以微秒为单位指定缓冲持续时间，在这种情况下，短于最小设备周期的持续时间将四舍五入为最小周期。

默认的缓冲持续时间在大多数情况下都能提供稳定的播放，但据报告，在某些设备上，默认设置下的流重置会出现故障。在这种情况下，指定更短的持续时间可能会有帮助。

视频输出驱动

视频输出驱动是连接不同视频输出设备的接口。其语法是：

--vo=<driver1,driver2,...[,]>

指定一个要使用的视频输出驱动的优先级列表。

如果这个列表末尾有 , ，mpv将回退到不在列表中的驱动程序。

备注

参见 --vo=help 获取已编译的视频输出驱动的列表。

--vo=gpu 是默认的推荐的输出驱动。其他所有的驱动都是为了兼容性或特定场景。如果默认值无效，它将回退到其他驱动（优先顺序和 --vo=help 列出的相同）。

可用的视频输出驱动有：

gpu

通用的可定制的、GPU加速的视频输出驱动。它支持扩展缩放方式、抖动、色彩管理、自定义着色器、HDR等。

参见 GPU渲染选项 ，了解该视频输出的特定选项。

默认情况下，mpv使用平衡质量和性能的设置。此外，还有两个预定义的配置文件可用： fast 用于最大性能， high-quality 用于优越的渲染质量。您可以使用 --profile=<name> 选项应用特定的配置文件，并使用 --show-profile=<name> 来查看其内容。

这个视频输出虚拟了几个可能的图形API和窗口环境，可以用 --gpu-api 和 --gpu-context 选项来影响它们。

OpenGL-interop的硬件解码在一定程度上受支持。请注意在这种模式下，一些边缘情况可能无法被良好处理，并且色彩空间转换和色度还原通常由硬解码API负责。

gpu 默认使用FBOs。有时你可以通过改变选项 --fbo-format 为 rgb16f, rgb32f 或 rgb 来达到更好的质量或性能。已知的问题包括Mesa/Intel不接受 rgb16 ，Mesa有时不支持浮点纹理，以及一些macOS的设置在使用 rgb16 时非常慢，但使用``rgb32f``时非常快。如果你存在运行问题，也可以尝试启用 --gpu-dumb-mode=yes 选项。

gpu-next

基于 libplacebo 的实验性视频渲染器。它几乎支持与 --vo=gpu 相同的功能集。列表参见 GPU渲染选项

通常应该更快，质量更高，但有些功能可能仍然缺失或运行异常。期待（并报告！）错误。有关已知差异和错误的列表，参见此处：

https://github.com/mpv-player/mpv/wiki/GPU-Next-vs-GPU

xv （X11独占）

使用XVideo扩展来启用硬件加速显示。这是在X上兼容性最好的视频输出驱动，但可能质量低下，而且在OSD和字幕显示方面存在问题。

备注

这个驱动程序是为了与旧系统兼容。

支持以下全局选项：

--xv-adaptor=<number>

选择一个指定的XVideo适配器（检查xvinfo结果）

--xv-port=<number>

选择一个指定的XVideo端口

--xv-ck=<cur|use|set>

选择获取color key的源（默认： cur）

cur

默认取当前在Xv中设置的color key

use

使用但不设置mpv的color key（使用 --colorkey 选项来变更）

set

与use相同，但也设置提供的color key

--xv-ck-method=<none|man|bg|auto>

设置color key的绘制方法（默认： man）

none

禁用color-keying

man

手动绘制color key（在部分情况下减少闪烁）

bg

将color key设置为窗口背景

auto

由Xv绘制color key

--xv-colorkey=<number>

变更color key为你选择的RGB值。 0x000000 是纯黑， 0xffffff 是纯白

--xv-buffers=<number>

用于内部环形缓冲区的图片缓存的数量（默认： 2）。增大该数会使用更多的内存，但如果视频帧率接近或高于显示器刷新率，可能有助于解决X服务器响应不够快的问题。

x11 （X11独占）

无硬件加速的共享内存视频输出驱动，只要有X11就能工作。

从mpv 0.30.0开始，你可能需要使用 --profile=sw-fast 去实现正常的性能。

备注

这只是一个后备方案，通常不应该使用。

vdpau （X11独占）

https://mpv.io/manual/master/#video-output-drivers-vdpau

direct3d （Windows独占）

使用Direct3D接口的视频输出驱动

备注

这个驱动是为了兼容那些没有提供合适的OpenGL驱动的系统，以及ANGLE表现不好的平台。

支持以下全局选项：

--vo-direct3d-disable-texture-align

通常情况下，纹理尺寸总是对齐到16。启用这个选项后，视频纹理将总是与视频本身的尺寸完全相同。

调试选项。这些可能是不正确的，可能会在将来被移除，可能会崩溃，可能会导致低速运行，等等。如果你为了性能或正常运行真的需要这些，请联系开发者。

--vo-direct3d-force-power-of-2

总是强制纹理为2的幂，即使设备报告支持非2的幂的纹理尺寸

--vo-direct3d-texture-memory=<mode>

只影响启用着色器/纹理的操作，以及(E)OSD。可用的值：

default （默认）

使用 D3DPOOL_DEFAULT 和一个 D3DPOOL_SYSTEMMEM 纹理进行锁定。如果驱动支持 D3DDEVCAPS_TEXTURESYSTEMMEMORY ，则直接使用 D3DPOOL_SYSTEMMEM

default-pool

使用 D3DPOOL_DEFAULT （类似 default ，但绝不使用shadow-texture）

default-pool-shadow

使用 D3DPOOL_DEFAULT 和一个 D3DPOOL_SYSTEMMEM 纹理进行锁定（类似 default ，但总是强制使用shadow-texture）

managed

使用 D3DPOOL_MANAGED

scratch

使用 D3DPOOL_SCRATCH 和一个 D3DPOOL_SYSTEMMEM 纹理进行锁定

--vo-direct3d-swap-discard

使用 D3DSWAPEFFECT_DISCARD 可能更快。也可能更慢，因为它必须(?)清除每一帧。

--vo-direct3d-exact-backbuffer

始终将后缓存的大小调整到窗口大小。

sdl

SDL 2.0+ 渲染视频输出驱动，取决于是否有硬件加速的系统。应该在SDL 2.0支持的所有平台上工作。关于详细调整，请参考你的副本文件 SDL_hints.h

备注

此驱动是为了与无法提供正常的图形驱动程序的系统兼容。

支持以下全局选项：

--sdl-sw

即使检测到软件渲染器也继续

--sdl-switch-mode

指示SDL在全屏时切换显示器的视频模式

dmabuf-wayland

实验性的Wayland输出驱动，旨在与 drm stateless 或 VA API 硬件解码一起使用。该驱动被设计为避免任何GPU到CPU的拷贝，并使用固定功能的硬件（如果可用的话）而不是GPU着色器来执行缩放和色彩空间转换。这就为其它任务释放了GPU资源。强烈建议使用适当的 --hwdec 选项（如 auto-safe ）来配合使用此VO。虽然在某些情况下可以不使用 --hwdec ，因为mpv的内部转换滤镜，但不建议这样做，因为这是一个不必要的额外步骤。正确的输出取决于您的GPU、驱动程序和合成器的支持。已知Weston和基于wlroots的合成器（如Sway）以及英特尔GPU通常可以正常工作。

vaapi

Intel VA API视频输出驱动，支持硬件解码。请注意除了兼容性之外，绝对没有理由使用这个。这是低质量的，而且在OSD方面有问题。我们强烈建议你使用 --vo=gpu --hwdec=vaapi 代替它。

支持以下全局选项：

--vo-vaapi-scaling=<algorithm>

default

驱动程序的默认值（默认）

fast

速度快但质量低

hq

未指定的依赖驱动程序的高质量缩放，但速度慢

nla

non-linear anamorphic scaling

--vo-vaapi-scaled-osd=<yes|no>

如果启用，那么OSD将按视频分辨率渲染，并按显示分辨率进行缩放。默认情况下，这个功能是禁用的，如果驱动程序支持，OSD将以显示分辨率渲染。

null

无视频输出。对于基准测试很有用。

通常情况下，用 --video=no 来禁用视频更好。

支持以下全局选项：

--vo-null-fps=<value>

模拟显示FPS。这人为地限制了视频输出每秒接受的帧数。

caca

Color ASCII art video output driver that works on a text console.

This driver reserves some keys for runtime configuration. These keys are hardcoded and cannot be bound:

d and D

Toggle dithering algorithm.

a and A

Toggle antialiasing method.

h and H

Toggle charset method.

c and C

Toggle color method.

备注

This driver is a joke.

tct

彩色Unicode艺术视频输出驱动，在文本控制台中工作。默认情况下，取决于现代终端对真彩色的支持，以完整色范围显示图像，但也支持256色输出（见下文）。在Windows上，它需要一个ansi终端例如mintty。

从mpv 0.30.0开始，你可能需要使用 --profile=sw-fast 来获得合格的性能。

注意：TCT图像输出与mpv的其他终端输出不同步，这可能导致图像破碎。选项 --terminal=no 或 --really-quiet 有助于解决这个问题。

--vo-tct-algo=<algo>

选择如何将像素写入到终端

half-blocks

使用unicode LOWER HALF BLOCK字符来实现更高的垂直分辨率（默认）

plain

使用空格。导致垂直分辨率下降两重，但理论上在更多地方起作用

--vo-tct-buffering=<pixel|line|frame>

Specifies the size of data batches buffered before being sent to the terminal.

TCT image output is not synchronized with other terminal output from mpv, which can lead to broken images. Sending data to the terminal in small batches may improve parallelism between terminal processing and mpv processing but incurs a static overhead of generating tens of thousands of small writes. Also, depending on the terminal used, sending frames in one chunk might help with tearing of the output, especially if not used with --really-quiet and other logs interrupt the data stream.

pixel

Send data to terminal for each pixel.

line

Send data to terminal for each line. (Default)

frame

Send data to terminal for each frame.

--vo-tct-width=<width> --vo-tct-height=<height>

假设终端有指定的字符宽度和/或高度。如果不能检测终端尺寸，这些默认为80x25

--vo-tct-256=<yes|no> （默认： no）

使用256色 —— 用于不支持真彩色的终端

kitty

使用kitty图形协议的终端图形输出。曾用kitty和Konsole测试。

你可能需要使用 --profile=sw-fast 来取得良好的性能。

Kitty的尺寸和对齐选项：

--vo-kitty-cols=<columns> --vo-kitty-rows=<rows> （默认： 0）

以字符单元指定终端尺寸，否则 (0) 从终端读取，或回退到 80x25

--vo-kitty-width=<width> --vo-kitty-height=<height> （默认： 0）

指定可用的像素大小，否则 (0) 从终端读取，或回退到 320x240

--vo-kitty-left=<col> --vo-kitty-top=<row> （默认： 0）

指定图像开始在字符单元中的位置（1是第一列或第一行）。如果是0（默认值），则尝试根据其它值和图像的长宽比及缩放来自动决定

--vo-kitty-config-clear=<yes|no> （默认： yes）

每当输出被重新配置时，是否清理终端（例如，当视频尺寸发生改变）

--vo-kitty-alt-screen=<yes|no> （默认： yes）

是否使用备用的屏幕缓冲区并在退出时将终端返回到之前的状态。当设置为 no 时，退出后最后的kitty图像会保留在屏幕上，且光标会跟随它

--vo-kitty-use-shm=<yes|no> （默认： no）

使用共享内存对象来传输图像数据到终端。这比以转义代码形式发送数据要快得多，但不被许多终端支持。它也只在本地机器上工作，而无法通过例如SSH的连接

这个选项在Windows上未实现。

sixel

使用sixels的终端图形输出。用 mlterm 和 xterm 测试。

注意：Sixel图像输出与mpv的其他终端输出不同步，这可能导致图像破碎。选项 --really-quiet 有助于解决这个问题，建议使用。在某些平台上，使用 --vo-sixel-buffered 选项可能有效。

你可能需要使用 --profile=sw-fast 来获得合格的性能。

注意：在撰写本文时， xterm 默认不启用sixel —— 以 xterm -ti 340 启动是启用它的一个方法。另外， xterm 默认不显示大于1000x1000像素的图像。

为了正确地渲染和对齐sixel图像，mpv需要知道终端的尺寸，包括单元格和像素。默认情况下，它试图使用终端报告的值，然而，由于终端之间的差异，这是一个容易出错的过程，不能确定地自动进行 —— 一些终端报告的尺寸是以像素为单位的，包括边距 —— 例如 xterm ，而其他终端报告的是实际可用的像素数 - 如 mlterm 。此外，它们在最大化或全屏时的表现可能不同，mpv不能用标准方法检测这种状态。

Sixel的大小和对齐选项：

--vo-sixel-cols=<columns> --vo-sixel-rows=<rows> （默认： 0）

以字符单元指定终端尺寸，否则(0)从终端读取，或退回到80x25。注意，mpv不使用最后一行的sixel，因为这似乎会导致滚动。

--vo-sixel-width=<width> --vo-sixel-height=<height> （默认： 0）

指定可用的像素大小，否则(0)从终端读取，或退回到320x240。除了排除最后一行外，高度也被进一步四舍五入为6的倍数（sixel单位高度），以避免溢出低于指定的尺寸。

--vo-sixel-left=<col> --vo-sixel-top=<row> （默认： 0）

指定图像开始在字符单元中的位置（1是第一列或第一行）。如果是0（默认），则尝试根据其他值和图像的长宽比和缩放来自动确定它。

--vo-sixel-pad-x=<pad_x> --vo-sixel-pad-y=<pad_y> （默认： -1）

只在mpv从终端读取尺寸（像素）时使用。指定终端报告的尺寸所包含的填充像素数（单边）。如果-1（默认），那么像素数将被四舍五入为单元格数的倍数（每个轴），以考虑报告中的边距 —— 这只有在每个轴的总体填充量小于单元格数时才能正确工作。

--vo-sixel-config-clear=<yes|no> （默认： yes）

每当输出被重新配置时，是否清理终端（例如，当视频尺寸发生改变）

--vo-sixel-alt-screen=<yes|no> （默认： yes）

是否使用备用的屏幕缓冲区并在退出时将终端返回到之前的状态。当设置为 no 时，退出后最后一个sixel图像会保留在屏幕上，且光标会跟随它

--vo-sixel-exit-clear 是该选项的一个过时的别名，将来可能被移除。

--vo-sixel-buffered=<yes|no> （默认： no）

在写入到终端之前，缓冲完整的输出序列。在POSIX平台上，这可以帮助防止中断（包括来自其它应用程序的中断），从而防止图像被破坏，但对于某些终端来说，可能要牺牲性能，而且受限于实现细节

Sixel图像质量的选项：

--vo-sixel-dither=<algo>

选择libsixel应该应用的抖动算法。根据libsixel的文档，可以是以下列表中的一个。

auto （默认）

让libsixel选择抖动方法

none

不扩散

atkinson

用Bill Atkinson的方法进行扩散

fs

用Floyd-Steinberg的方法扩散

jajuni

用Jarvis, Judice & Ninke的方法进行扩散

stucki

用Stucki的方法进行扩散

burkes

用Burkes的方法进行扩散

arithmetic

位置稳定的算术抖动

xor

基于位置稳定的算术xor抖动

--vo-sixel-fixedpalette=<yes|no> （默认： yes）

使用libsixel的内置静态调色板，使用XTERM256配置预设进行抖动。固定调色板使用256色进行抖动。请注意，使用 no （在撰写本文时）会减慢 xterm 的速度。

--vo-sixel-reqcolors=<colors> （默认： 256）

对固定调色板没有影响。设置libsixel使用动态调色板所需的颜色数。这个值也取决于终端仿真器。Xterm支持256种颜色。可以把这个值设得低一些，以提高性能。

--vo-sixel-threshold=<threshold> （默认： -1）

对固定调色板没有影响。定义改变调色板的阈值 —— 以颜色数量的百分比表示，例如，当颜色数量改变20%时，20将改变调色板。这是一个减少调色板变化次数的简单措施，因为在某些终端（ xterm ）中它可能很慢。默认的(-1)将在每一帧上选择一个调色板，并且会有更好的质量。

image

将每一帧输出到当前目录下的一个图像文件。每个文件名是用前导零填充的帧号。

支持以下全局选项：

--vo-image-format=<format>

选择图像文件格式

jpg

JPEG文件，扩展名为.jpg（默认）

jpeg

JPEG文件，扩展名为.jpeg

png

PNG文件

webp

WebP文件

--vo-image-png-compression=<0-9>

PNG压缩系数（速度与文件大小的权衡）（默认： 7）

--vo-image-png-filter=<0-5>

在PNG压缩前应用的过滤器（0 = none; 1 = sub; 2 = up; 3 = average; 4 = Paeth; 5 = mixed）（默认： 5）

--vo-image-jpeg-quality=<0-100>

JPEG质量系数（默认： 90）

--vo-image-jpeg-optimize=<0-100>

JPEG优化系数（默认： 100）

--vo-image-webp-lossless=<yes|no>

启用写入无损质量的WebP文件（默认： no）

--vo-image-webp-quality=<0-100>

WebP质量（默认： 75）

--vo-image-webp-compression=<0-6>

WebP压缩系数（默认： 4）

--vo-image-outdir=<dirname>

指定保存图像文件的目录（默认： ./ ）

libmpv

用于libmpv的直接嵌入。作为一个特例，在macOS上，它被当作mpv(cocoa-cb)中的一个普通视频输出使用。否则在其他情况下是无用的（参见 <mpv/render.h> ）。

这也支持许多 gpu 视频输出的选项，取决于后端。

drm (Direct Rendering Manager)

https://mpv.io/manual/master/#video-output-drivers-drm

mediacodec_embed （安卓）

将 IMGFMT_MEDIACODEC 帧直接渲染到 android.view.Surface 。需要 --hwdec=mediacodec 的硬件解码，以及 --vo=mediacodec_embed 和 --wid=(intptr_t)(*android.view.Surface)

由于这个视频输出使用原生解码和渲染程序，mpv的许多功能（字幕渲染、OSD/OSC、视频滤镜等）在这个驱动中是不可用的。

要使用硬解码应使用 --vo=gpu ，并一起使用 --hwdec=mediacodec 或 --hwdec=mediacodec-copy 和 --gpu-context=android

wlshm （Wayland独占）

没有硬件加速的共享内存视频输出驱动，只要有Wayland就能工作。

从mpv 0.30.0开始，你可能需要使用 --profile=sw-fast 来获得合格的性能。

备注

这只是一个后备方案，通常不应使用。

音频滤镜

音频滤镜允许你修改音频流和它的属性。其语法是：

--af=...

设置一连串的音频滤镜。完整的语法参见 --vf （ 视频滤镜 ）

备注

要获得可用的音频滤镜的完整列表，参见 --af=help

另外，请记住，大多数实际的滤镜是通过 lavfi wrapper获得的，它使你可以使用libavfilter的大多数滤镜。这包括所有从MPlayer移植到libavfilter的滤镜。

--vf 的描述阐述了如何使用libavfilter以及如何解决已过时的mpv滤镜。

参见 --vf 的选项组，了解 --af-add , --af-pre , --af-clr 以及其它可能的工作方式。

可用的滤镜有：

lavcac3enc[=options]

使用libavcodec在运行时将多声道音频编码为AC-3。支持16-bit native-endian输入格式，最多6个声道。当输出原始AC-3流时，输出是big-endian，当输出到S/PDIF时是native-endian。如果输入的采样率不是48kHz、44.1kHz或32kHz，它将被重采样为48kHz。

tospdif=<yes|no>

如果 no ，则输出raw AC-3流，如果 yes （默认），则输出到S/PDIF进行透传。

bitrate=<rate>

用于AC-3流的比特率。设置为384以获得384kbps。

默认是640。一些接收机可能无法处理。

有效值： 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, 448, 512, 576, 640.

特殊值 auto 根据输入的声道数选择一个默认的比特率。

1ch:

96

2ch:

192

3ch:

224

4ch:

384

5ch:

448

6ch:

448

minch=<n>

如果输入声道数少于 <minch> ，滤镜将自行分离（默认： 3）

encoder=<name>

选择要使用的libavcodec编码器。目前，这应该是一个AC-3编码器，使用其它编码器会失败的很惨

format=format:srate:channels:out-srate:out-channels

它本身不做任何格式转换。相反，如果需要的话，它可以使滤镜系统在这个滤镜之前或之后插入必要的转换滤镜。它主要用于控制进入其它滤镜的音频格式。要指定音频输出的格式，参见 --audio-format --audio-samplerate --audio-channels 。这个滤镜能够强制指定一个特定的格式，而 --audio-* 可以由音频输出驱动根据输出的兼容性进行覆盖。

所有的参数都是可选的。前三个参数限制了滤镜接受的输入内容。因此它们会导致转换滤镜在这个滤镜之前被插入。 out- 参数告知在这个滤镜之后的滤镜或音频输出如何解析数据，而不进行实际的转换。设置这些参数可能会损坏什么，除非你真的知道你因为某些原因需要这样做，比如测试或处理损坏的媒体文件。

<format>

强制转换为这种格式。使用 --af=format=format=help 来获得有效格式的列表

<srate>

强制转换到一个特定的采样率。采样率是一个整数，例如48000

<channels>

强制混合到一个特定的声道布局。参见 --audio-channels 选项的可能值

<out-srate>

<out-channels>

注意 ：这个滤镜曾经被命名为 force 。旧的 format 滤镜曾经自行转换，不像这个滤镜让滤镜系统处理转换。

scaletempo[=option1:option2:...]

在不改变音调的情况下缩放音频节奏，可选与播放速度同步。

它的工作原理是以正常速度播放 ‘stride’ 毫秒的音频，然后消耗 ‘stride*scale’ 毫秒的输入音频。它通过将 ‘overlap’% 的步长与前一个步长之后的音频混合在一起。它可选对下一个 ‘search’ 毫秒的音频进行简短的数据分析，以确定最佳重叠位置。

scale=<amount>

名义上的缩放节奏的数量。除了速度之外，还对这个量进行缩放（默认： 1.0）

stride=<amount>

输出每个步幅的长度，单位是毫秒。太高的值会在高音阶量时产生明显的跳动，在低音阶量时产生回声。非常低的值会反转音调。增加会改善性能（默认：60）

overlap=<factor>

重叠步长的系数。减少会改善性能（默认： 20）

search=<amount>

搜索最佳重叠位置的长度，以毫秒为单位。减少会明显改善性能。在慢速系统上，你可能想把它设置得很低（默认： 14）

speed=<tempo|pitch|both|none>

设置对速度变化的响应。

tempo

缩放速度与播放速度同步（默认）

pitch

反转滤镜的效果。缩放音调而不改变速度。在你的 input.conf 中加入这个，以按音乐的半音阶来调节:

[ multiply speed 0.9438743126816935
] multiply speed 1.059463094352953

警告

失去与视频的同步

both

同时缩放速度和改变音调

none

忽略速度的变化

示例

mpv --af=scaletempo --speed=1.2 media.ogg

将以1.2倍于正常的速度播放媒体，音频为正常音调。改变播放速度将改变音频节奏来匹配。

mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 media.ogg

将以1.2倍于正常的速度播放媒体，音频为正常音调，但改变播放速度对音频节奏没有影响。

mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg

会对质量和性能参数进行调整。

mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg

将以1.2倍于正常的速度播放媒体，音频为正常音调。改变播放速度将改变音调，使音频节奏保持在1.2倍。

scaletempo2[=option1:option2:...]

缩放音频节奏而不改变音调。这个算法是从chromium移植过来的，使用了波形相似度叠加（WSOLA）方法。与 scaletempo 和 rubberband R2 引擎或 engine=faster 相比，它似乎能获得更高的音频质量。如果使用了 audio-pitch-correction 选项（默认开启），则在改变播放速度时会自动插入该滤镜。

默认情况下， search-interval 和 window-size 参数的值与chromium相同。

min-speed=<speed>

如果播放速度低于 <speed> ，则将音频静音（默认： 0.25）

max-speed=<speed>

如果播放速度高于 <speed> 并且 <speed> != 0 ，则将音频静音（默认： 8.0）

search-interval=<amount>

搜索最佳重叠位置的长度，以毫秒为单位（默认： 40）

window-size=<amount>

overlap-and-add window的长度，以毫秒为单位（默认： 12）

rubberband

用librubberband进行高质量的音调修正。它可以代替 scaletempo 和 scaletempo2 ，当以不同于正常的速度播放时，它将用于调整音频音调。它也可以用来调整音频音调而不改变播放速度。

<pitch-scale=<amount>

设置音调比例系数。频率要乘以这个值。

engine=<faster|finer>

选择要使用的核心 Rubberband 引擎。有两种可供选择：

Faster:

这是 Rubberband R2 引擎。它的 CPU 占用率明显低于 Finer(R3) 引擎。

Finer:

这是 Rubberband R3 引擎。该引擎仅适用于 librubberband 3 或更高版本。其输出质量明显更高，但 CPU 占用率也更高（如果可用的话它是默认值）

这个滤镜有许多额外的子选项。你可以用 mpv --af=rubberband=help 列出它们。这也会显示每个选项的默认值。这里没有记录这些选项，因为它们只是被传递给librubberband。参阅librubberband的文档以了解每个选项的作用： https://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html 请注意，某些选项只适用于 R2(faster) 和 R3(finer) 引擎中的一个。（mpv rubberband滤镜的子选项名称和值与librubberband的映射遵循一个简单的模式： "Option" + Name + Value ）

这个滤镜支持下列 af-command 命令：

set-pitch

动态设置 <pitch-scale> 参数。这可以用来在运行时改变播放的音调。注意，速度是用标准的 speed 属性控制的，而不是 af-command 。

multiply-pitch <factor>

动态的乘以当前的 <pitch-scale> 的值。 例如：0.5可以下降一个八度，1.5可以上升一个五度。如果你想上升或下降半音阶，用1.059463094352953和0.9438743126816935。

lavfi=graph

使用FFmpeg的libavfilter过滤音频。

<graph>

Libavfilter graph。详见 lavfi 视频滤镜 —— graph的语法是一样的

警告

不要忘记引用libavfilter graphs，如lavfi视频滤镜部分所述

o=<string>

AVOptions

fix-pts=<yes|no>

根据采样数确定PTS（默认： no）。如果这个选项被启用，播放器将不依赖于libavfilter准确的传递PTS。相反，它将采样数作为PTS传给libavfilter，并根据它和输入的PTS计算mpv使用的PTS。这有助于处理那些输出重新计算的PTS而不是原始PTS的滤镜（包括要求PTS从0开始的滤镜）。mpv通常希望滤镜不要接触PTS（或者只在改变帧边界的范围内），所以这不是默认的，但在使用损坏的滤镜时需要这样处理。在实际情况中，这些损坏的滤镜会随着时间的推移导致缓慢的A/V不同步（对于某些文件），或者如果你从文件中间跳转或开始播放，会完全中断播放。

drop

这个滤镜丢弃或重复音频帧来适应播放速度。它总是在完整的音频帧上操作，因为它是为了处理SPDIF（压缩音频透传）。如果使用 --video-sync=display-adrop 选项，它会自动使用。不要使用这个滤镜（或给定的选项）；它们的质量极低。

视频滤镜

视频滤镜允许你修改视频流和它的属性。本节描述的所有信息也适用于音频滤镜（一般使用前缀 --af 而不是 --vf ）。

确切的语法是：

--vf=<filter1[=parameter1:parameter2:...],filter2,...>

设置一个视频滤镜链。这包括滤镜的名称，以及 = 后面的参数选项列表。参数由 : 分隔（不是 , ，因为那会开始一个新的滤镜条目）。

在滤镜名称之前，可以用 @name: 指定一个标签，其中name是一个用户给定的任意的名称，用来标识该滤镜。只有当你想在运行时切换滤镜的时候才需要这样做。

滤镜名称前的 ! 表示该滤镜默认是禁用的。它将在滤镜创建时被跳过。这对运行时的滤镜切换也很有用。

参见 vf 命令（和 toggle 子命令）的进一步解释和示例。

一般的滤镜条目语法是：

["@"<label-name>":"] ["!"] <filter-name> [ "=" <filter-parameter-list> ]

或者对于特殊的 “toggle” 语法（参见 vf 命令）：

"@"<label-name>

和 filter-parameter-list ：

<filter-parameter> | <filter-parameter> "," <filter-parameter-list>

和 filter-parameter ：

( <param-name> "=" <param-value> ) | <param-value>

param-value 可以进一步用 [ / ] 来引用，如果该值包含 , 或 = 等字符。这一点特别适用于 lavfi 滤镜，它使用与mpv（MPlayer历史上的）非常相似的语法来指定滤镜及其参数。

备注

--vf 只能以单个轨道作为输入，即使过滤器支持动态输入。无法使用需要多个输入的滤镜。对于这种情况，请使用 --lavfi-complex 。这也适用于 --af 。

滤镜可以在运行时被操控。你可以使用上面描述的 @ 标签，结合 vf 命令（参见 命令接口 ）来获得更多的控制。初始禁用的滤镜与 ! 在这方面也很有用。

备注

要获得可用的视频滤镜的完整列表，参见 --vf=help 和 https://ffmpeg.org/ffmpeg-filters.html

另外，请记住，大多数实际的滤镜是通过 lavfi wrapper获得的，它可以让你使用libavfilter的大多数滤镜。这包括所有从MPlayer移植到libavfilter的滤镜。

大多数内置滤镜在某些方面已经过时了，除非它们只在mpv中可用（比如处理mpv特性的滤镜，或者只在mpv中实现的）。

如果一个滤镜不是内置的， lavfi-bridge 将被自动尝试。这个bridge不支持支援输出，也不在实际使用滤镜之前验证参数。尽管mpv的语法与libavfilter的相当相似，但它并不一样（这表示不是所有vf_lavfi的 graph 选项接受的东西都会被 --vf 接受）。

你也可以在滤镜的名字前缀加上 lavfi- 来强制使用wrapper。如果滤镜的名字与mpv内置的过时的滤镜相冲突时，这很有帮助。例如， --vf=lavfi-scale=args 会使用libavfilter的 scale 滤镜，而不是mpv的过时的内置滤镜。

视频滤镜是在列表中管理的。有许多命令可以管理滤镜列表：

--vf-append=filter

将给定参数的滤镜追加到滤镜列表的后方。

--vf-add=filter

将给定参数的滤镜追加到滤镜列表的后方（目前仍然可以传递多个滤镜，但已过时）。

--vf-pre=filter

将给定参数的滤镜添加到滤镜列表的前方（目前仍然可以传递多个滤镜，但已过时）。

--vf-remove=filter

从列表中删除滤镜。滤镜可以按照添加的方式（滤镜名称和它的完整参数列表），或者通过标签（以 @ 为前缀）给出。滤镜的匹配工作如下：如果任何一个被比较的滤镜有一个标签集，则只比较标签。如果没有一个滤镜有标签，则比较滤镜的名称、参数和参数顺序（目前仍然可以传递多个滤镜，但已过时）。

-vf-toggle=filter

如果给定的滤镜还没有出现，则将其追加到列表的后方；如果已经出现，则将其从列表中移除。滤镜的匹配工作如 --vf-remove 中所描述。

--vf-clr

完全清空滤镜列表。

对于支持它的滤镜，你可以通过它们的名字访问参数。

--vf=<filter>=help

输出某个特定滤镜的参数名称和参数值范围。

可用的mpv独占滤镜有：

format=fmt=<value>:colormatrix=<value>:...

应用视频参数覆盖，可选择转换。默认情况下，这将覆盖视频的参数而不进行转换（除了 fmt 参数），但对于支持转换的参数，可以用 convert=yes 来进行适当的转换。

<fmt>

图像格式名称，例如rgb15、bgr24、420p，等等。（默认：不改变。）

这个滤镜总是执行转换到给定的格式。

备注

为获取可用的格式列表，使用 --vf=format=fmt=help

备注

在某些情况下支持硬件格式之间的转换。例如： 从 cuda 到 vulkan ，或 vaapi 到 vulkan.

<convert=yes|no>

强制颜色参数的转换（默认： no）。

如果禁用（默认），可能进行的唯一转换是格式转换，如果 <fmt> 被设置。所有其它参数（如 <colormatrix> ）都是强制的，而没有转换。这种模式通常在文件被错误地标记时很有用。

如果启用了这个功能，如果有任何参数不匹配，就会使用libswscale或zimg。如果mpv的zimg wrapper支持输入/输出图像格式，并且使用了 --sws-allow-zimg=yes ，就会使用zimg。这两种库可能不支持所有种类的转换。这通常会导致无声的错误转换。zimg在许多情况下有更好的机会正确执行转换。

在这两种情况下，颜色参数都是在图像格式转换的输出阶段设置的（如果 fmt 被设置）。不同的是，在 convert=no 时，颜色参数不会传递给转换器。

如果输入和输出的视频参数相同，转换总是会被跳过。

在硬件格式之间转换时，该参数没有影响，唯一进行转换的是格式转换。

示例

mpv test.mkv --vf=format:colormatrix=ycgco

结果是不正确的颜色（如果test.mkv被正确标记）。

mpv test.mkv --vf=format:colormatrix=ycgco:convert=yes --sws-allow-zimg

结果是真正转换为 ycgco ，假设渲染器支持它（ --vo=gpu 通常支持）。你可以添加 --vo=xv 来强制要求一个绝对不支持它的视频输出驱动，它应该显示不正确的颜色作为确认。

使用 --sws-allow-zimg=no （或者在构建时禁用zimg）将使用libswscale，它在写入时不能执行这种转换。

<colormatrix>

控制播放视频时YUV到RGB色彩空间的转换。有各种标准。通常情况下，标清视频应使用BT.601，高清视频应使用BT.709（这已默认处理）。使用不正确的色彩空间会导致颜色的饱和度略低或过高，并出现偏移。

这些选项并不总是受支持。不同的视频输出提供不同支持程度的程度。 gpu 和 vdpau 视频输出驱动通常提供完全支持。如果系统视频驱动支持的话， xv 输出可以设置色彩空间，但不支持输入和输出电平。 scale 视频滤镜可以设置色彩空间和输入电平，但只有在输出格式为RGB的情况下（如果视频输出驱动程序支持RGB输出，你可以用 -vf scale,format=rgba 强制实现它）。

如果这个选项被设置为 auto （这是默认的），视频的色彩空间标志将被使用。如果该标志没有设置，色彩空间将被自动选择。这是通过一个简单的启发式方法来完成的，它尝试区分标清和高清视频。如果视频大于1279x576像素，将使用BT.709（高清）；否则将选择BT.601（标清）。

可用的色彩空间有：

auto:

自动选择（默认）

bt.601:

ITU-R Rec. BT.601 (SD)

bt.709:

ITU-R Rec. BT.709 (HD)

bt.2020-ncl:

ITU-R Rec. BT.2020 （非恒定亮度）

bt.2020-cl:

ITU-R Rec. BT.2020 （恒定亮度）

bt.2100-pq:

ITU-R Rec. BT.2100 ICtCp PQ 变体

bt.2100-hlg:

ITU-R Rec. BT.2100 ICtCp HLG 变体

dolbyvision:

Dolby Vision 杜比视界

smpte-240m:

SMPTE-240M

<colorlevels>

用于YUV到RGB转换的YUV动态范围。这个选项只有在播放不遵循标准动态范围或被错误标记的损坏文件时才需要。如果视频没有指定它的动态范围，则假定它是有限范围。

与应用 <colormatrix> 的限制相同。

可用的动态范围有：

auto:

自动选择（通常是有限范围）（默认）

limited:

有限范围（亮度为16-235，色度为16-240）

full:

全范围（亮度和色度都为0-255）

<primaries>

源文件被编码的RGB原色。通常这应该设置在文件头中，但是当播放损坏或错误标记的文件时，可以用它来覆盖这个设置。

这个选项只影响执行色彩管理的视频输出驱动，例如， gpu 设置了 target-prim 或 icc-profile 子选项。

如果这个选项被设置为 auto （这是默认的），视频的色彩原色标志将被使用。如果该标志没有设置，将自动选择颜色空间，使用以下启发式方法。如果 <colormatrix> 被设置或确定为BT.2020或BT.709，就会使用相应的原色。否则，如果视频高度正好是576（PAL），则使用BT.601-625。如果正好是480或486（NTSC），则使用BT.601-525。如果视频分辨率是其他的，则使用BT.709。

可用的色彩原色有：

auto:

自动选择（默认）

bt.601-525:

ITU-R BT.601 (SD) 525-line systems (NTSC, SMPTE-C)

bt.601-625:

ITU-R BT.601 (SD) 625-line systems (PAL, SECAM)

bt.709:

ITU-R BT.709 (HD)（等同sRGB原色）

bt.2020:

ITU-R BT.2020 (UHD)

apple:

Apple RGB

adobe:

Adobe RGB (1998)

prophoto:

ProPhoto RGB (ROMM)

cie1931:

CIE 1931 RGB

dci-p3:

DCI-P3 (Digital Cinema)

v-gamut:

Panasonic V-Gamut primaries

<gamma>

源文件被编码的伽马函数。通常情况下，这应该设置在文件头中，但当播放损坏或错误标记的文件时，可以用它来覆盖设置。

这个选项只影响执行色彩管理的视频输出驱动程序。

如果这个选项被设置为 auto （这是默认值），那么对于YCbCr内容，伽玛将被设置为BT.1886，对于RGB内容，将被设置为sRGB，对于XYZ内容，将被设置为Linear。

可用的伽玛函数有：

auto:

自动选择（默认）

bt.1886:

ITU-R BT.1886 (EOTF corresponding to BT.601/BT.709/BT.2020)

srgb:

IEC 61966-2-4 (sRGB)

linear:

Linear light

gamma1.8:

Pure power curve (gamma 1.8)

gamma2.0:

Pure power curve (gamma 2.0)

gamma2.2:

Pure power curve (gamma 2.2)

gamma2.4:

Pure power curve (gamma 2.4)

gamma2.6:

Pure power curve (gamma 2.6)

gamma2.8:

Pure power curve (gamma 2.8)

prophoto:

ProPhoto RGB (ROMM) curve

pq:

ITU-R BT.2100 PQ (Perceptual quantizer) curve

hlg:

ITU-R BT.2100 HLG (Hybrid Log-gamma) curve

v-log:

Panasonic V-Log transfer curve

s-log1:

Sony S-Log1 transfer curve

s-log2:

Sony S-Log2 transfer curve

<sig-peak>

视频文件的参考峰值照度，相对于信号的参考白电平。这对HDR来说很重要，但也可以用色调映射SDR内容来模拟不同的曝光。通常从最大内容亮度或母版元数据等标签中推断出来。

默认的0.0将默认为源的标称峰值亮度。

<light>

场景的亮度类型。这主要是根据伽马函数正确推断出来的，但在查看raw camera footage（例如V-Log）时，覆盖这一点可能很有用，因为它通常是基于场景参考的，而不是基于显示参考的。

可用的亮度类型有：

auto:

自动选择（默认）

display:

Display-referred light（大多数内容）

hlg:

Scene-referred using the HLG OOTF (e.g. HLG content)

709-1886:

Scene-referred using the BT709+BT1886 interaction

gamma1.2:

Scene-referred using a pure power OOTF (gamma=1.2)

<dolbyvision=yes|no>

是否包含杜比视界元数据（默认： yes）。如果禁用，将从帧中剥离任何杜比视界元数据。

<hdr10plus=yes|no>

是否包含HDR10+元数据（默认： yes）。如果禁用，将从帧中剥离任何HDR10+元数据。

<film-grain=yes|no>

是否包括胶片颗粒元数据（默认： yes）。如果禁用，任何胶片颗粒元数据都将从帧中剥离。

<stereo-in>

设置视频被假定为编码的立体模式。使用 --vf=format:stereo-in=help 来列出所有可用模式。检查 stereo3d 的滤镜文档，看看这些名称的含义。

<stereo-out>

设置视频显示的立体模式。取值与 stereo-in 选项相同。

<rotate>

设置视频的旋转度，假定是以度数进行编码。特殊值 -1 使用输入的格式。

<w>, <h>

如果不是0，执行转换到给定的尺寸。如果没有设置 convert=yes ，则忽略。

<dw>, <dh>

设置显示尺寸。请注意，设置显示尺寸，使视频在两个方向上都被缩放，而不仅仅是改变宽高比，这是一个实现细节，以后可能会改变。

<dar>

设置视频帧的显示长宽比。这是一个浮点数，但也可以传递诸如 [16:9] 之类的值（用 [...] 来引用，以防止选项解析器解释 : 字符）。

<force-scaler=auto|zimg|sws>

如果适用的话，强制一个特定的缩放器后端。这是一个调试选项，随时可能消失。

<alpha=auto|straight|premul>

设置视频使用的透明种类。如果图像格式没有透明通道，则未定义效果（可能被忽略或导致错误，取决于mpv内部如何发展）。设置这个可能会或不会导致下游的图像处理以不同的方式处理透明度，这取决于支持的情况。使用了 convert 或zimg，这将转换透明。libswscale和其他FFmpeg组件会完全忽略这一点。

lavfi=graph[:sws-flags[:o=opts]]

使用FFmpeg的libavfilter过滤视频。

<graph>

libavfilter graph的字符串。该滤镜必须有一个视频输入pad和一个视频输出pad

语法和可用的滤镜参见 https://ffmpeg.org/ffmpeg-filters.html

警告

如果你想用这个选项使用完整的滤镜语法，你必须引用滤镜graph，以防止mpv的语法和滤镜graph的语法发生冲突。为了防止引用和转义的混乱，如果你知道你想从输入文件中使用哪个视频轨道，可以考虑使用 --lavfi-complex （反正几乎所有的视频文件都只有一个视频轨道）。

示例

--vf=lavfi=[gradfun=20:30,vflip]

gradfun 滤镜带无意义的参数，接着是 vflip 滤镜（这展示了libavfilter如何接受一个graph，而不仅仅是一个滤镜）。滤镜graph的字符串是用 [ 和 ] 引用的。这不需要在某些shell（如bash）中使用额外的引用或转义，而其他shell（如zsh）则需要在选项字符串周围加上额外的 " 来引用。

'--vf=lavfi="gradfun=20:30,vflip"'

和前面一样，但使用的是所有shell都安全的引用。外侧的 ' 引用确保shell不会删除mpv所需的 " 引用。

'--vf=lavfi=graph="gradfun=radius=30:strength=20,vflip"'

和之前一样，但对所有东西都使用命名的参数。

<sws-flags>

如果libavfilter插入了像素格式转换的滤镜，这个选项给出了应该传递给libswscale的标志。这个选项是数值型的，并采用 SWS_ 标志的位数组合。

参见 https://git.videolan.org/?p=ffmpeg.git;a=blob;f=libswscale/swscale.h

<o>

设置AVFilterGraph选项。这些应该在FFmpeg中有所记录。

示例

'--vf=lavfi=yadif:o="threads=2,thread_type=slice"'

强制一个特定的线程设置。

sub=[=bottom-margin:top-margin]

将字幕渲染移到滤镜链中的一个任意点，或在视频滤镜中强制进行字幕渲染，而不是使用视频输出OSD支持。

<bottom-margin>

在帧的底部添加一个黑带。SSA/ASS渲染器可以在那里放置字幕（使用 --sub-use-margins ）。

<top-margin>

顶部的黑带用于放置顶部字幕（使用 --sub-use-margins ）。

示例

--vf=sub,eq

将字幕的渲染移到eq滤镜之前。这将使字幕颜色和视频都受到视频均衡器设置的影响。

vapoursynth=file:buffered-frames:concurrent-frames

加载一个VapourSynth滤镜脚本。这是为流处理准备的：mpv实际上提供了一个源滤镜，而不是使用原生的VapourSynth视频源。mpv源将只在一个小的帧窗口内响应帧请求（这个窗口的大小由 buffered-frames 参数控制），超出的请求将返回错误。因此，你不能使用VapourSynth的全部功能，但你可以使用某些滤镜。

警告

不要使用这个滤镜，除非你有VapourSynth的专业知识，并且知道如何修复mpv VapourSynth wrapper代码中的错误。

如果你只是想播放VapourSynth生成的视频（例如使用原生的VapourSynth视频源），最好使用 vspipe 和一个pipe或FIFO来把视频送入mpv。如果滤镜脚本需要随机的帧访问（参见 buffered-frames 参数），同样适用。

file

脚本源的文件名。目前，这总是一个Python脚本（VapourSynth惯例下的 .vpy ）。

变量 video_in 被设置为mpv的视频源，希望脚本能从它那里读取视频（否则，mpv将不解码视频，视频packet队列将溢出，最终导致只有音频播放，或者更糟）。

脚本创建的graph滤镜也应该使用 _DurationNum 和 _DurationDen 帧属性来透传时间戳。

关于mpv定义的脚本变量的完整列表，参见选项列表的末尾。

示例：

import vapoursynth as vs
from vapoursynth import core
core.std.AddBorders(video_in, 10, 10, 20, 20).set_output()

警告

该脚本将在每次跳转时被重新加载。这样做是为了在不连续的情况下正确重置滤镜。

buffered-frames

在滤镜之前应该缓冲的最大解码视频帧数（默认： 4）。这指定了脚本在向后方向上可以请求的最大帧数。

例如，如果 buffered-frames=5 ，脚本刚刚请求了第15帧，它仍然可以请求第10帧，但第9帧已经不可用。如果它请求第30帧，mpv将再解码15帧，而只保留第25-30帧。

这个缓冲区存在的唯一原因是为了满足VapourSynth滤镜的随机访问请求。

VapourSynth API有一个 getFrameAsync 函数，它需要一个绝对的帧数。源滤镜必须对所有的请求作出回应。例如，一个源滤镜可以请求第2432帧，然后是第3帧。源滤镜通常通过预先索引整个文件来实现这一点。

另一方面，mpv是面向流的，不允许滤镜进行跳转（而且允许这样做是无意义的，因为这样会有损性能）。滤镜在播放过程中按顺序获得帧，不能不按顺序请求它们。

为了弥补这种不匹配，mpv允许滤镜在一个特定的窗口内访问帧。 buffered-frames 控制这个窗口的大小。大多数VapourSynth滤镜恰好与此配合，因为mpv请求的帧是依次增加的，而大多数滤镜只需要请求“临近”的帧。

如果滤镜请求的帧序号比缓冲的最高帧还高，新的帧将被解码，直到达到请求的帧序数。超过数量的帧将以先进先出的方式被刷掉（这个缓冲区里的最大数量只有 buffered-frames ）。

如果滤镜请求的帧序号比缓冲区内最低帧还低，那么这个请求就不能被满足，并且会向滤镜返回一个错误。这种错误不应该发生在一个“正确的”VapourSynth环境中。具体会发生什么，取决于所涉及的滤镜。

增加这个缓冲区不会改善性能。相反，它会浪费内存，并减慢跳转速度（当需要一次性解码足够多的帧来填充缓冲区时）。它只是为了防止上一段所述的错误。

一个滤镜需要多少帧取决于滤镜的实现细节，mpv无法知道。一个缩放滤镜可能只需要1帧，一个插值滤镜可能需要少量帧，而 Reverse 滤镜将需要无限帧。

如果你想在VapourSynth的能力范围内可靠地运行，请使用 vspipe

缓冲帧的实际数量也取决于 concurrent-frames 选项的值。目前，两个选项的值相乘，得到最终的缓冲区大小。

concurrent-frames

应该并行请求的帧的数量。并行的程度取决于滤镜和mpv解码视频以提供给滤镜的速度。这个值可能应该与你机器上的核心数量成正比。大多数时候，使其高于核心数实际上会使其变慢。

技术上来说，mpv将循环调用VapourSynth的 getFrameAsync 函数，直到有 concurrent-frames 帧还没有被滤镜返回。这也是假设mpv滤镜链的其他部分能够快速读取 vapoursynth 滤镜的输出（例如，如果你暂停播放器，过滤将很快停止，因为过滤后的帧在队列中等待）。

实际的并行性取决于许多其他因素。

默认情况下，这使用特殊值 auto ，它将选项设置为检测到的逻辑CPU核心的数量。

以下 .vpy 脚本的变量是由mpv定义的：

video_in

作为vapoursynth clip的mpv视频源。注意，这有一个不正确的（非常高的）长度设置，这使许多滤镜感到困惑。这是必要的，因为真正的帧数是未知的。你可以在clip上使用 Trim 滤镜来减少长度。

video_in_dw, video_in_dh

视频的显示尺寸。如果视频不使用方形像素（如DVD），可以与视频尺寸不同。

container_fps

由文件头报告的FPS值。这个值可能是错误的或完全损坏的（例如0或NaN）。即使这个值是正确的，如果另一个滤镜改变了真实的FPS（通过丢帧或插入帧），这个变量的值将没有用。注意 --container-fps-override 命令行选项会覆盖这个值。

对一些坚持要有FPS的滤镜很有用。

display_fps

当前显示器的刷新率。注意，这个值可以是0。

display_res

当前显示器的分辨率。这是一个整数数组，第一个条目对应宽度，第二个条目对应高度。这些值可以为0。请注意，这不会响应显示器更改，而且可能在所有平台上都无法正常工作。

vavpp

VA-API视频后处理。要求系统支持VA-API，即Linux/BSD独占。只与 --vo=vaapi 和 --vo=gpu 一起工作。目前是去交错。如果要求去交错（使用 d 键，默认映射到 cycle deinterlace 命令，或 --deinterlace 选项），这个滤镜会自动插入。

deint=<method>

选择反交错的算法。

no

不执行去隔行扫描

auto

选择最佳质量的去隔行算法（默认）。这按照文档中的选项顺序进行， motion-compensated 被认为是最佳质量

first-field

只显示第一个场

bob

bob去隔行扫描

weave, motion-adaptive, motion-compensated

高级去隔行扫描算法。这些是否真的有效，取决于GPU硬件、GPU驱动、驱动错误和mpv错误

<interlaced-only>

no:

对所有帧进行隔行扫描（默认）

yes:

只对标记为交错的帧进行反交错处理

reversal-bug=<yes|no>

no:

使用旧版Mesa驱动所解析的API。虽然这种解释更明显、更直观，但显然是错误的，而且不被英特尔驱动开发者所认同

yes:

使用英特尔对表面前向和后向参考的解释（默认）。这就是英特尔驱动和新的Mesa驱动所期望的。只对高级去隔行扫描算法重要

vdpaupp

VDPAU视频后处理。只对 --vo=vdpau 和 --vo=gpu 起作用。如果要求去隔行扫描（使用 d 键，默认映射到 cycle deinterlace 命令，或 --deinterlace 选项），这个滤镜会自动插入。当启用去交错时，如果使用了 vdpau 视频输出，或如果使用了 gpu ，并且至少激活了一次硬件解码（例如加载了vdpau），它总是比软件去交错滤镜更具优先级。

sharpen=<-1-1>

对于正值，对视频应用锐化算法，对于负值应用模糊算法（默认： 0）

denoise=<0-1>

对视频应用降噪算法（默认： 0；不降噪）

deint=<yes|no>

是否启用去隔行扫描（默认： no）。如果启用，它将使用 deint-mode 选择的模式

deint-mode=<first-field|bob|temporal|temporal-spatial>

选择去隔行扫描模式（默认： temporal）

注意，目前有一种机制允许 vdpau 视频输出改变自动插入的 vdpaupp 滤镜的 deint-mode 。为了避免混淆，建议不要使用与过滤有关的 --vo=vdpau 子选项。

first-field

只显示第一个场

bob

Bob去隔行扫描

temporal

基于运动适应性的时域反交错。可能导致慢速视频硬件和/或高分辨率下的A/V不同步

temporal-spatial

基于运动自适应的时域反交错，边缘引导的空间插值。需要快速的视频硬件

chroma-deint

使时域反交错器同时运行在亮度和色度上（默认）。使用no-chroma-deint来只使用亮度并加速高级去隔行。对慢速的视频内存很有用

pullup

尝试应用反转交错，需要基于运动自适应的时域反交错

interlaced-only=<yes|no>

如果 yes ，只对标记为隔行的帧进行去交错处理（默认： no）

hqscaling=<0-9>

0

使用默认的VDPAU缩放比例（默认）

1-9

应用高质量的VDPAU缩放（需要适格的硬件）

d3d11vpp

Direct3D 11视频后处理。目前需要D3D11硬件解码才能使用。

deint=<yes|no>

是否启用去隔行扫描（默认： no）

interlaced-only=<yes|no>

如果 yes ，只对标记为隔行的帧进行去隔行（默认： no）

mode=<blend|bob|adaptive|mocomp|ivctc|none>

尝试选择一个具有给定处理能力的视频处理器。如果一个视频处理器支持多种能力，不清楚实际选择的是哪种算法。 none 始终回退。在大多数（但不是所有）硬件上，这个选项可能什么都不做，因为视频处理器通常支持所有模式或不支持任何模式。

fingerprint=...

计算视频帧fingerprints并作为元数据提供。事实上，它目前几乎不配被称为 fingerprint ，因为它不计算“正确的”fingerprints，只计算微小的降级图像（但可用于计算图像哈希值或进行相似性匹配）。

这个滤镜的主要目的是为了支持 skip-logo.lua 脚本。如果这个脚本被抛弃，或者mpv获得了加载用户定义的滤镜的方法（除了VapourSynth），这个滤镜将被移除。由于这个滤镜的“特殊”性质，它将被移除而没有任何警告。

从滤镜中读取的预期方式是使用 vf-metadata （另参见 clear-on-query 滤镜参数）。该属性将返回一个按键/值成对的列表，如下所示：

fp0.pts = 1.2345
fp0.hex = 1234abcdef...bcde
fp1.pts = 1.4567
fp1.hex = abcdef1234...6789
...
fpN.pts = ...
fpN.hex = ...
type = gray-hex-16x16

每个 fp<N> 条目是针对一个帧。 pts 条目指定了帧的时间戳（在滤镜链中；在简单的情况下，这与显示的时间戳相同）。 hex 字段是十六进制编码的fingerprint，其大小和含义取决于 type 滤镜选项。 type 字段的值与滤镜创建时的选项相同。

这将返回自上次查询该属性以来被过滤的帧。如果 clear-on-query=no 被设置，查询不会重置帧的列表。在这两种情况下，最多返回10个帧。如果有更多的帧，最旧的帧会被丢弃。帧是按过滤顺序返回的。

（因为 vf-metadata 机制的内部结构很糟糕，所以不会返回每帧细节的结构化列表。返回的格式可能会在将来改变）

这个滤镜为了速度和利益而使用zimg。然而，在一些情况下，它将回退到libswscale：较小的像素格式，不对齐的数据指针或stride，或者如果zimg由于未知的原因不能初始化。在这些情况下，滤镜将使用更多的CPU。另外，它还会输出不同的fingerprints，因为libswscale不能执行我们通常要求zimg提供的全范围扩展。因此，滤镜可能会更慢，并且在随机的情况下可能不能正确工作。

type=...

要计算的fingerprint。可用的类型有：

gray-hex-8x8:

grayscale, 8 bit, 8x8 size

gray-hex-16x16:

grayscale, 8 bit, 16x16 size（默认）

这两种类型都是简单地移除所有的颜色，降级图像的缩放，将所有的像素值串联成一个字节数组，并将该数组转换为十六进制字符串。

clear-on-query=yes|no

如果该滤镜的 vf-metadata 属性被查询到，则清除帧fingerprints列表（默认： yes）。这需要用户的一些注意。某些类型的访问可能会多次查询该滤镜，从而导致帧丢失。

print=yes|no

输出计算的fingerprints到终端（默认： no）。这主要是为了测试之类的。脚本应该使用 vf-metadata 来读取这个滤镜的信息。

gpu=...

使用通常与 --vo=gpu 一起使用的Vulkan或OpenGL渲染器，将视频转换为RGB。对于OpenGL来说，这需要EGL实现的支持默认显示器上的离屏渲染（Mesa就是这种情况）。

子选项：

api=<type>

更改值 type 来选择渲染 API。 您还可以通过传递 help 获取已编译后端的完整列表。

egl

EGL （如果可用即默认）

vulkan

Vulkan

w=<pixels>, h=<pixels>

输出的尺寸，单位是像素（默认： 0）。如果不是正数，这将使用第一个过滤后的输入帧的大小

警告

这是高度实验性的。性能糟糕，而且它首先不会在任何地方工作。有些功能不被支持。

警告

这不做OSD渲染。如果你看到OSD，那么它已经被视频输出驱动的后端渲染了（如果可能的话，字幕是由 gpu 滤镜渲染的）。

警告

如果你在编码模式下使用这个，请记住，编码模式将在软件中使用设置的软件缩放器将RGB滤镜的输出转换为yuv420p。使用 zimg 可能会改善这一点，但无论如何，这可能会违背你使用这个滤镜的目的。

警告

不要和 --vo=gpu 一起使用。它将应用两次过滤，因为大多数 --vo=gpu 选项是无条件应用于 gpu 滤镜的。mpv中没有机制来阻止这种情况。

编码/压制

你可以使用这个工具将文件从一种格式/编码转换到另一种。

--o=<filename>

启用编码模式并指定输出文件名。

--of=<format>

指定输出格式（通过 -o 指定的文件扩展名覆盖自动检测）。参见 --of=help 以获取受支持格式的完整列表。

--ofopts=<options>

指定libavformat的输出格式选项。参见 --ofopts=help 以获取受支持的选项的完整列表。

这是一个按键/值列表 选项。详见 列表选项

--ofopts-add=<option>

将作为参数给定的选项追加到选项列表中（目前仍可传递多个选项，但已过时）

--ofopts=""

完全清空选项列表

--oac=<codec>

指定输出的音频编码。参见 --oac=help 以获取受支持的编码的完整列表。

--oacopts=<options>

指定libavcodec的输出音频编码选项。参见 --oacopts=help 以获取受支持的选项的完整列表。

示例

“--oac=libmp3lame --oacopts=b=128000”

选择128kbps的MP3进行编码

这是一个按键/值列表选项。详见 列表选项

--oacopts-add=<option>

将作为参数给定的选项追加到选项列表中（目前仍可传递多个选项，但已过时）

--oacopts=""

完全清空选项列表

--ovc=<codec>

指定输出的视频编码。参见 --ovc=help 以获取受支持的编码的完整列表。

--ovcopts=<options>

指定libavcodec的输出视频编码选项。参见 –ovcopts=help 以获取受支持的选项的完整列表。

示例

"--ovc=mpeg4 --ovcopts=qscale=5"

为MPEG-4编码选择恒定的量化器缩放5

"--ovc=libx264 --ovcopts=crf=23"

为H.264编码选择VBR质量系数23

这是一个按键/值列表选项。详见 列表选项

--ovcopts-add=<option>

将作为参数给定的选项追加到选项列表中（目前仍可传递多个选项，但已过时）

--ovcopts=""

完全清空选项列表

--orawts

将输入pts复制到输出视频中（不受某些输出容器格式的支持，例如AVI）。在这种模式下，不连续点不被固定，所有的点都是被原样传递过去。在这种模式下，千万不要向前跳转或使用多个输入文件！

--ocopy-metadata=<yes|no>

在进行编码时，从输入文件复制元数据到输出文件（默认： yes）。

--oset-metadata=<metadata-tag[,metadata-tag,...]>

指定要包括在输出文件中的元数据。支持的值在不同的输出格式中有所不同。例如，Matroska（MKV）和FLAC允许几乎任意的符号说明，而MP4和MP3的支持则比较有限。

这是一个按键/值列表选项。详见 列表选项

示例

“--oset-metadata=title="Output title",comment="Another tag"”

在输出文件中增加一个标题和一个注释

--oremove-metadata=<metadata-tag[,metadata-tag,...]>

指定从输入文件复制时要从输出文件中排除的元数据。

这是一个字符串列表选项。详见 列表选项

示例

“--oremove-metadata=comment,genre”

排除将注释和流派标签复制到输出文件。

命令接口

mpv的核心可以用命令和属性来控制。许多与播放器交互的方式都使用它们：按键绑定（ input.conf ），OSD（用属性显示信息），JSON IPC，客户端API（ libmpv ），以及经典的slave mode 。

input.conf

input.conf文件由一系列按键绑定的列表组成，例如:

s screenshot      # 用s键截屏
LEFT seek 15      # 将向左键映射为向前搜寻15秒

每一行映射一个按键到一个输入命令。按键被指定为其按键名（如果与 Shift 结合，则为大写），或者为特殊键指定一个名称。例如， a 映射到 a 键，不需要shift，而 A 映射到 a 键，需要shift 。

该文件位于mpv设置目录下（通常在 ~/.config/mpv/input.conf ，取决于平台）。默认的绑定在这里定义:

https://github.com/mpv-player/mpv/blob/master/etc/input.conf

特殊按键的列表可以通过以下方式获得

mpv --input-keylist

一般来说，按键可以与 Shift Ctrl Alt 组合:

ctrl+q quit

mpv 可以在输入测试模式下启动，在OSD上显示按键的绑定和它们所绑定的命令，而不会执行命令:

mpv --input-test --force-window --idle

（只有关闭窗口才能使 mpv 退出，按下普通的键只是显示绑定的命令，即使被映射为quit）

另参见 按键名称

input.conf语法

[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*

注意，默认情况下，右Alt键可以被创建为特殊字符，因此两个Alt不会注册为单个修饰键。选项 --input-right-alt-gr 可以改变这一行为。

换行总是开始一个新的绑定。 # 开始一个注释（在被引用的字符串参数之外）。为了将命令与 # 键绑定，可以使用 SHARP

<key> 是该按键的字面字符（ASCII或Unicode字符），或者是一个符号名称（正如由 --input-keylist 输出的内容）。

<section> （用 { 和 } 括起来）是这个命令的输入部分。

<command> 是命令本身。它由命令名称和多个（或无）参数组成，所有参数都用空格隔开。字符串参数应被引用，一般用 " 。参见 Flat命令语法

你可以绑定多个命令到一个按键上。例如：

a show-text “command 1” ; show-text “command 2”

也可以将一个命令与多个按键绑定：

a-b-c show-text “command run after a, b, c have been pressed”

（这在一般的命令语法中没有展示）

如果 a 或 a-b 或 b 已经被绑定，这将运行第一个匹配的命令，而多键命令将不会被调用。为了避免这个问题，可以将中间键重映射到 ignore 。多个键联合的最大数量（非修饰键）目前是4。

按键名称

所有的鼠标和键盘的输入都要转换为mpv指定的按键名称。键名要么是代表物理键的特殊符号标识，要么是文本键名，它是UTF-8编码的unicode码点。这些都是键盘输入通常会产生的，例如， a 代表A键。因此，mpv使用由当前操作系统键盘布局转译的输入，而不是物理扫描代码。

目前有一个硬编码的假设，即每个文本键都可以表示为一个单一的unicode码点（NFKC形式）。

所有的键名都可以与修饰键 Shift Ctrl Alt Meta 结合。它们必须以实际的键名为前缀，每个修饰键后面都有一个 + （例如 ctrl+q ）。

需要注意一下 Shift 修饰键。例如， Shift+2 通常应该在 input.conf 中指定为键名 @ ，同样， Alt+Shift+2 的组合通常为 Alt+@ ，等等。特殊的键名，如 Shift+LEFT ，也能如期工作。如果有疑问 —— 使用 --input-test 来检查mpv是如何处理某个按键/组合的。

符号键名和修饰键名不区分大小写。Unicode键名是区分大小写的，因为输入绑定通常遵循shift键。

另一种类型的键名是十六进制键名，作为特殊键的后备键，既不是unicode，也没有特殊的mpv定义的名称。一旦mpv为它们添加了合适的名字，它们就会失效，但如果不这样做，你就可以使用一个键。

所有的符号键名都由 --input-keylist 列出。 --input-test 是一个特殊的模式，在OSD上输出出所有的输入。

对一些符号键名的注释：

KP*

小键盘名。行为因后端而异（是否实现，以及如何处理numlock），但通常情况下，mpv尝试将小键盘上的按键映射到独立的名称，即使它们能输出与一般按键相同的文本。

MOUSE_BTN* MBTN*

各种鼠标按钮

取决于后端，鼠标滚轮也可被表示为一个按钮。此外， MOUSE_BTN3 MOUSE_BTN4 MOUSE_BTN5 MOUSE_BTN6 分别是 WHEEL_UP WHEEL_DOWN WHEEL_LEFT WHEEL_RIGHT 的过时的别名。

MBTN* 是 MOUSE_BTN* 的别名

WHEEL_*

鼠标滚轮（通常）

AXIS_*

WHEEL_* 的别名，已过时

*_DBL

鼠标按键 双击

MOUSE_MOVE MOUSE_ENTER MOUSE_LEAVE

由鼠标移动事件触发。当光标进入或离开mpv窗口（或当前光标区域，使用已过时的鼠标区域输入部分机制）时ENTER/LEAVE发生。

CLOSE_WIN

当使用操作系统窗口管理器关闭mpv窗口时发出的虚拟键（例如，通过点击窗口标题栏的关闭按钮）

GAMEPAD_*

由SDL游戏手柄后端触发的键

UNMAPPED

匹配任何未映射的键的虚拟键（如果可能的话，你应该避免这样做，因为它可能会变更行为或在将来被移除）

ANY_UNICODE

匹配任何产生文本的键的虚拟键（如果可能的话，你应该避免这样做，因为它可能会变更行为或在将来被移除）

Flat命令语法

这是在input.conf中使用的语法，并在其它的一些地方被“input.conf语法”提及。

<command>  ::= [<prefixes>] <command_name> (<argument>)*

<argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)

command_name 是一个不引用的包含命令名称本身的字符串。参见列表 输入命令列表

参数之间用空格隔开，即使命令只有一个参数。带有空格或其他特殊字符的参数必须引用，否则命令不能被正确解析。

双引号引用解释JSON/C-style的转义，如 \t 或 \" 或 \\ 。JSON根据RFC 8259进行转义，减去surrogate pair转义。这是唯一一种允许在值上加换行的形式 —— 如 \n

单引号引用解释字面内容，并且不能在值中包含单引号的字符。

自定义引用也是解释字面内容，但比单引号引用更灵活。它们以 ` （反引号）开始，后面是任何ASCII字符，并以同一对的第一次出现为结束，顺序相反，例如： `-foo-` 或 ``bar`` 。最后一对序列不允许出现在值中 —— 例子分别是 -` 和 `` 。在第二个例子中，值的最后一个字符也不能是反引号。

不支持对同一个参数的进行混合引用，如 'foo'"bar" 。

请注意，参数解析和属性扩展发生在不同阶段。首先，参数如上所述被确定，然后，如果适用的话，属性被扩展 —— 无视参数的引用。然而，仍然可以用 raw 前缀或 $> 防止被扩展。参见 输入命令前缀 和 属性扩展

指定为数组的命令

这适用于部分API，例如Lua脚本中的 mp.commandv() 或 mp.command_native() （带有数组参数），或者C语言libmpv客户端API中的 mpv_command() 或 mpv_command_node() （带有 MPV_FORMAT_NODE_ARRAY ）。

命令以及所有的参数都以一个数组的形式传递。类似于 Flat命令语法 ，你可以先把前缀作为字符串传递（每个都是单独的数组项），然后把命令名称作为字符串，然后把每个参数作为字符串或原生值。

由于这些API将参数作为单独的字符串或原生值来传递，所以它们不需要引用，并且支持转义。技术上讲，有一个input.conf解析器，它首先将命令字符串分割成数个参数，然后为每个参数调用解析器。input.conf解析器通常处理引号和转义。上面提到的数组命令API直接将字符串传递给参数解析器，或者可以通过传递非字符串值的职能回避它们。

对于这些API，属性扩展默认是禁用的。这可以用 expand-properties 前缀来改变。参见 输入命令前缀

有时命令的参数是字符串，而这些参数实际上是由其它组件解析的（例如，用 vf add 的滤镜字符串） —— 在这些情况下，你不得不在input.conf中进行双击，但在数组API中则不必。

对于复杂的命令，可以考虑使用 命名参数 来代替，这样应该会更具兼容性。不过有些命令不支持命名参数，而是采用数组参数。

命名参数

这适用于部分API，例如Lua脚本中的 mp.command_native() （有字符串键的表），或者C语言libmpv客户端API中的 mpv_command_node() （带有 MPV_FORMAT_NODE_MAP ）。

命令的名称是由 name 字符串字段提供的。每个命令的名称在 输入命令列表 中的每个命令描述内都有定义。 --input-cmdlist 也可以列出它们。参见 subprocess 命令为例。

有些命令不支持命名参数（例如 run 命令）。你需要使用以数组形式传递参数的API。

命名参数在 “flat” 的input.conf语法中不被支持，这意味着你根本无法在input.conf中使用它们作为按键的绑定。

对于这些API，属性扩展默认是禁用的。这可以通过 expand-properties 前缀来改变。参见 输入命令前缀

输入命令列表

带参数的命令中，参数名称用符号 < / > 括起来。不要在实际命令中加入这些符号。可选参数用 [ / ] 符号括起来。如果你不传递它们，它们将被设置为默认值。

记住在input.conf中引用字符串参数（参见 Flat命令语法 ）

ignore

用它来“屏蔽”应该被取消绑定的按键，不触发任何命令。对禁用部分默认绑定很有用，而不必用 --input-default-bindings=no 禁用所有绑定。

seek <target> [<flags>]

变更播放位置。默认情况下，以相对的秒数来跳转。

第二个参数是跳转模式：

relative （默认）

相对当前位置跳转（负值向前跳转）

absolute

跳转到一个指定的时间（负值从文件的末尾开始）

absolute-percent

跳转到一个指定的百分比位置

relative-percent

跳转到相对当前位置的百分比位置

keyframes

始终在关键帧处重新开始播放（快）

exact

始终做精确跳转（慢）

多个标志可以合并，例如： absolute+keyframes

默认情况下， keyframes 用于 relative, relative-percent 和 absolute-percent 跳转，而 exact 用于 absolute 跳转。

在mpv 0.9之前， keyframes 和 exact 标志必须作为第3个参数传递（基本上是用空格代替 +）。第3个参数仍然被解析，但被认为是过时的语法。

revert-seek [<flags>]

撤销 seek 命令，以及其他的跳转命令（但不一定是所有的）。调用这个命令一次会回到跳转前的播放位置。第二次调用它将撤销 revert-seek 命令本身。这只在同一个文件中有效。

第一个参数是可选的，它可以改变行为：

mark

标记当前的时间位置。下一次正常的 revert-seek 命令将返回到这个时间点，不管上次之后发生了多少次搜索。

mark-permanent

如果设置，标记当前时间位置，在下一个设置了 mark 或 mark-permanent 的 revert-seek 命令之前（或当前文件的播放结束），不改变标记位置。在这之前, revert-seek 将一直跳转到被标记的时间点. 这个标志不能与 mark 结合使用。

在没有任何参数的情况下使用默认行为。

frame-step

播放一帧，然后暂停。对纯音频播放无效。

frame-back-step

后退一帧，然后暂停。注意，这可能非常慢（它尝试精确，而不是快速），有时不能达到预期效果。这样做的效果如何，取决于精确跳转是否正常工作（例如，参见 --hr-seek-demuxer-offset 选项）。视频滤镜或其它修改帧计时的视频后处理（例如去隔行扫描）通常应该有效，但在边缘情况下可能会使反向步进暗中发生错误。使用 --hr-seek-framedrop=no 应该会有帮助，尽管它可能会使精确跳转更慢。

这对纯音频播放无效。

set <name> <value>

将指定的属性或选项设置为指定的值。

del <name>

删除指定的属性。大多数属性不能被删除。

add <name> [<value>]

向属性或选项添加指定的值。在上溢或下溢时，将属性钳制为最大值。如果省略了 <value> ，则假定为 1 。

cycle <name> [<value>]

循环指定的属性或选项。第二个参数可以是 up 或 down 来设置循环方向。上溢时，将属性设回最小值，下溢时，将其设为最大值。如果省略了 up 或 down ，则假定为 up 。

默认情况下是否启用按键可重复，取决于属性。目前具有连续性的值的属性默认是可重复的（如 volume ），而离散值则不是（如 osd-level ）。

multiply <name> <value>

类似 add ，但将属性或选项与数值相乘。

screenshot <flags>

拍摄屏幕截图。

有多个标志可供选择（有些可与 + 组合）：

<subtitles> （默认）

以原始分辨率保存视频图像，带有字幕。在某些情况下，一些视频输出可能仍然包括OSD。

<video>

类似 subtitles ，但通常没有OSD或字幕。具体行为取决于所选的视频输出。

<window>

保存mpv窗口的内容。通常视频是缩放过的，有OSD和字幕。具体行为取决于所选的视频输出。

<each-frame>

每一帧截一次屏。再次发出这个命令可以停止截图。注意，使用这种模式时，你应该禁用frame-dropping功能 —— 否则在丢帧的情况下，你可能会收到重复的图像。这个标志可以和其他标志结合使用，例如 video+each-frame

旧版本mpv需要把 single 和 each-frame 作为第二个参数传递（且无标志）。这种语法仍然可以被解析，但已经过时，将来可能会被移除。

如果你使用 ; 把这个命令和另一个命令结合起来，你可以使用 async 标志来使编码/写入图像文件成为异步的。对于普通的独立命令，它总是异步的，这个标志没有影响。（该行为在mpv0.29.0中被更改）

成功后，将返回一个带有 filename 字段，设为保存的屏幕截图位置的 mpv_node 。

screenshot-to-file <filename> <flags>

截图并保存到一个指定的文件。文件的格式将由扩展名来猜测（并且 --screenshot-format 被忽略 —— 当扩展名丢失或未知时，行为是随机的）。

第二个参数和 screenshot 的第一个参数一样，支持 subtitles video window

如果文件已存在，它将被覆盖写入。

像所有的输入命令参数一样，文件名符合属性扩展，如 属性扩展 中所述。

playlist-next <flags>

转到播放列表的下一个条目。

第一个参数：

weak （默认）

如果播放列表的最后一个文件是当前播放的文件，则无操作

force

如果播放列表没有更多的文件，就终止播放

playlist-prev <flags>

转到播放列表的上一个条目。

第一个参数：

weak （默认）

如果播放列表的第一个文件是当前播放的文件，则无操作

force

如果第一个文件正在播放，就终止播放

playlist-next-playlist

以不同的 playlist-path 转到播放列表上的下一个条目。

playlist-prev-playlist

以不同的 playlist-path 转到播放列表上的上一个条目。

playlist-play-index <integer|current|none>

开始（或重新开始）播放指定的播放列表索引。除了基于0的播放列表条目索引外，它还支持以下值：

<current>

当前的播放列表条目（如 playlist-current-pos ）将被再次播放（卸载和重新加载）。如果没有设置，播放就会停止。(在边缘情况下， playlist-current-pos 可以指向一个播放列表条目，即使当前的播放状态未激活。

<none>

播放被停止。如果空闲模式（ --idle ）被启用，播放器将进入空闲模式，否则将退出。

该命令和 loadfile 类似，它只操作下一个将播放文件的状态，而不等待当前文件被退出，或下一个文件被加载。

设置 playlist-pos 或类似的属性可以产生与此命令近似的效果。然而它更明确，例如，新的播放列表条目与旧的相同，它将保证重启播放。

loadfile <url> [<flags> [<index> [<options>]]]

加载指定的文件或URL并播放它。从技术上讲，这只是一个播放列表的操作命令（它要么替换播放列表，要么添加一个条目）。实际的文件加载是独立发生的。例如，一个用新文件替换当前文件的 loadfile 命令会在当前文件停止之前返回，而后才开始加载新文件。

第二个参数：

<replace> （默认）

停止播放当前文件，并立即播放新文件

<append>

将文件追加到播放列表中

<append-play>

添加文件，如果当前没有文件播放，则开始播放（始终从添加的文件开始播放，即使在运行这个命令之前的播放列表不是空的）

<insert-next>

将文件直接插入播放列表的当前条目之后。

<insert-next-play>

将文件插入下一个，如果当前没有播放，则开始播放。(总是从添加的文件开始播放，即使运行此命令前播放列表不是空的也是如此）。

<insert-at>

在第三个参数给定的索引处将文件插入播放列表。

<insert-at-play>

在第三个参数给定的索引处插入文件，如果当前没有播放，则开始播放。(总是从添加的文件开始播放，即使播放列表在运行此命令前不是空的）。

第三个参数是插入索引，仅用于 insert-at 和 insert-at-play 操作。与这些操作一起使用时，新项目将被插入播放列表中的索引位置，如果索引小于 0 或大于播放列表的大小，则会被追加到末尾。所有其他操作都将忽略此参数。

第四个参数是一个选项和值的列表，应该在文件播放时设置。它的形式是 opt1=value1,opt2=value2,.. 。当使用client API时，这可以是一个 MPV_FORMAT_NODE_MAP （或一个Lua表），但当前的值本身必须是字符串。这些选项在播放过程中设置，并在播放结束时恢复到之前的值（参见 单文件选项 ）。

loadlist <url> [<flags> [<index>]]

加载指定的列表文件或URL（类似 --playlist ）。

第二个参数：

<replace> （默认）

停止播放，用新的列表替换播放器内部的播放列表

<append>

在当前的内部播放列表的末尾追加新的播放列表

<append-play>

追加新的播放列表，如果当前没有文件播放，则开始播放（始终从新的列表开始播放，即使在运行这个命令之前的内部播放列表不是空的）

<insert-next>

将新播放列表直接插入当前内部播放列表的当前条目之后。

<insert-next-play>

插入新的播放列表，如果当前没有播放列表，则开始播放。(总是从新的播放列表开始播放，即使运行此命令前内部播放列表不是空的也是如此）。

<insert-at>

在第三个参数给定的索引处插入新的播放列表。

<insert-at-play>

在第三个参数给定的索引处插入新的播放列表，如果当前没有播放列表，则开始播放。(总是从新的播放列表开始播放，即使运行此命令前内部播放列表不是空的）。

第三个参数是插入索引，仅用于 insert-at 和 insert-at-play 操作。与这些操作一起使用时，新的播放列表将插入到内部播放列表中的索引位置，如果索引小于 0 或大于内部播放列表的大小，则附加到末尾。所有其他操作都将忽略此参数。

playlist-clear

清除播放列表，除了当前播放的文件。

playlist-remove <index>

移除指定索引的播放列表条目。索引值从0开始计算。 特殊值 current 移除当前的条目。注意，移除当前条目也会停止播放并开始播放下一个条目。

playlist-move <index1> <index2>

移动索引1的播放列表条目，使其取代索引2的条目（矛盾的是，如果index1低于index2，移动后的播放列表条目将没有index2的索引值，因为index2指的是目标条目，而不是该条目移动后的索引）。

playlist-shuffle

随机洗牌播放列表。这与使用 --shuffle 选项时启动的情况类似。

playlist-unshuffle

尝试恢复之前的 playlist-shuffle 命令。这只起一次作用（对多个连续的 playlist-unshuffle 命令无效）。如果在 playlist-shuffle 命令之后，有新的递归播放列表被打开，可能无法正常起效。

run <command> [<arg1> [<arg2> [...]]]

运行指定的命令。与MPlayer/mplayer2和mpv的早期版本（0.2.x和更早的版本）不同，这不会调用shell。相反，命令被直接运行，每个参数单独传递。每个参数都如 属性扩展 中那样被扩展。

此命令具有可变数量的参数，也不能与命名参数一起使用。

程序以分离的方式运行，mpv不会等待命令完成，但会在生成命令后立即继续播放。

要获得旧版的行为，使用 /bin/sh 和 -c 作为前两个参数。

示例

run "/bin/sh" "-c" "echo ${title} > /tmp/playing"

这不是一个特别好的例子，因为它没有处理转义，而一个特别准备的文件可能允许攻击者执行任意的shell命令。建议编写一个小的shell脚本，然后用 run 来调用。

subprocess

类似 run ，但给予调用者更多关于进程执行的控制权，并且不分离进程。

你可以通过异步运行这个命令来避免阻塞，直到进程终止（例如Lua脚本中的 mp.command_native_async() ）。

这个命令有以下命名参数。它们的顺序是不保证的，所以你应该始终用命名参数来调用它们，参见 命名参数

args (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])

字符串的数组，命令是第一个参数，后接的是后续的命令行参数。这就像 run 命令的参数列表。

第一个数组条目是可执行文件的绝对路径，或者是没有路径成分的文件名，在这种情况下，可执行文件会在环境变量 PATH 的目录中搜索。在Unix上，这相当于 posix_spawnp 和 execvp 的行为。

playback_only (MPV_FORMAT_FLAG)

布尔值，表示当播放结束时，进程是否应该被终止（可选，默认： yes）。如果启用，停止播放将自动结束该进程，且你不能在播放之外启动它。

capture_size (MPV_FORMAT_INT64)

整数，设置可以捕获的最大stdout加stderr字节数（可选，默认： 64MB）。如果字节数超过该数，捕获将被停止。此限制是针对每个被捕获的流。

capture_stdout (MPV_FORMAT_FLAG)

捕获进程输出到stdout的所有数据，并在进程结束后返回（可选，默认： no）。

capture_stderr (MPV_FORMAT_FLAG)

与 capture_stdout 相同，但针对stderr 。

detach (MPV_FORMAT_FLAG)

是否以分离模式运行进程（可选，默认： no）。在这种模式下，进程会在一个新的进程会话中运行，命令不会等待进程终止。如果 capture_stdout 和 capture_stderr 都没有设置为 yes ，命令在新进程启动后立即返回，否则，只要管道开启，命令就会读取。

env (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])

为新进程设置一个环境变量的列表（默认为空）。如果传递了一个空列表，则使用mpv进程的环境来代替（不同于底层操作系统的机制，mpv命令不能以空环境启动一个进程。幸运的是那完全无用）。列表的格式和 execle() 系统调用中的一样。每个字符串项都定义了一个环境变量，比如 NAME=VALUE

在Lua上，你可以使用 utils.get_env_list() 来检索当前环境，比如假设你想添加一个新的变量。

stdin_data (MPV_FORMAT_STRING)

向新进程的stdin输入给定的字符串。由于这是一个字符串，你不能传递任意的二进制数据。如果进程在所有数据写入前终止或关闭管道，剩余的数据将被默默地丢弃。可能在win32上不起效。

passthrough_stdin (MPV_FORMAT_FLAG)

如果启用，将新进程的stdin连接到mpv的stdin（默认： no）。在mpv 0.33.0之前，这个参数不存在，但其行为类似于被设置为 yes 。

该命令返回以下结果（作为 MPV_FORMAT_NODE_MAP ）。

status (MPV_FORMAT_INT64)

通常情况下，如果进程正常结束，这就是进程的退出代码（0或正数），如果出现其它错误（启动失败、被mpv中止等），则为负数。负值的意义未被定义，除了表示错误（不对应操作系统的低级别退出状态值）。

在Windows上，即使进程优雅地退出，也可能会返回一个负值，因为win32的 UINT 退出代码在被设置为结果集中的 int64_t 字段之前被分配给了一个``int`` 变量。这个问题以后可能会被修复。

stdout (MPV_FORMAT_BYTE_ARRAY)

被捕获的stdout流，受限于 capture_size

stderr (MPV_FORMAT_BYTE_ARRAY)

与 stdout 相同，但用于stderr 。

error_string (MPV_FORMAT_STRING)

如果进程正常退出，则为空字符串。如果进程以不寻常的方式终止，则为字符串 killed . 如果进程不能被启动，则为字符串 init 。

在Windows系统中，只有当进程被mpv杀死时， killed 才会被返回，因为 playback_only 被设置为true

killed_by_us (MPV_FORMAT_FLAG)

进程是否被mpv杀死，例如由于 playback_only 被设置为true，中止命令（比如通过 mp.abort_async_command() ），或者播放器即将退出。

注意，只要参数正确，命令本身将总是返回success。进程是否可以被生成，或者是否以某种方式被杀死或返回错误状态，必须从结果值中查询。

这个命令可以通过API异步中止。另参见 异步命令详情 。只有 run 命令可以以真正分离的方式启动进程。

备注

如果子进程不是以分离模式启动的，即使 playback_only 为false，它也会在播放器退出时被终止。

警告

如果你想在播放器处于空闲状态时运行命令，或者你不想让播放结束时终结命令，不要忘记设置 playback_only 的字段为false

示例

local r = mp.command_native({
    name = "subprocess",
    playback_only = false,
    capture_stdout = true,
    args = {"cat", "/proc/cpuinfo"},
})
if r.status == 0 then
    print("result: " .. r.stdout)
end

这是一个相当无用的Lua例子，它演示了如何以阻塞的方式运行一个进程，并检索其stdout输出。

quit [<code>]

退出播放器。如果给出了一个参数，它将作为进程的退出代码。

quit-watch-later [<code>]

退出播放器，并存储当前的播放位置。以后播放该文件时，将跳转到先前的位置。（可选的）参数与 quit 命令完全一样。参见 恢复播放

sub-add <url> [<flags> [<title> [<lang>]]]

加载指定的字幕文件或流。默认情况下，加载后它被选为当前字幕。

flags 参数是以下值之一：

<select>

立即选择字幕（默认）

<auto>

不选择字幕（或者在某些特殊情况下，让默认的流选择机制决定）

<cached>

选择字幕。如果已经添加了一个相同文件名的字幕，则选择该字幕，而不是加载一个重复的条目（在这种情况下，标题/语言被忽略，如果在加载后发生了变化，这些变化将不会被反映出来）

title 参数设置UI中的曲轨道标题。

lang 参数设置轨道语言，如果 flags 设置为 auto ，也会影响流的选择。

sub-remove [<id>]

移除指定的字幕轨。如果缺少 id 参数，则移除当前轨道。（只对外部字幕文件有效）

sub-reload [<id>]

重新加载指定的字幕轨。如果缺少 id 参数，则重新加载当前轨道。（只对外部字幕文件有效）

这通过卸载和重新添加字幕轨道来工作。

sub-step <skip> <flags>

改变字幕时间，使下一个 <skip> 字幕事件之后的字幕事件被显示。 <skip> 可以是负数以便后退。

第二个参数：

primary （默认）

在主字幕中步进

secondary

在次字幕中步进

sub-seek <skip> <flags>

跳转视频和音频位置，以便显示 <skip> 字幕事件之后的字幕事件。例如， sub-seek 1 跳到下一个字幕， sub-seek -1 跳到上一个字幕， sub-seek 0 则跳到当前字幕的开头。

这类似于 sub-step ，只是它跳转视频和音频，而不是调整字幕延迟。

第二个参数：

primary （默认）

通过主字幕步进

secondary

通过次字幕步进

对于嵌入式字幕（如Matroska），这只适用于已经显示过的字幕事件，或在一个短的预取范围内。有关如何控制可用预取范围的详细信息，详见 缓存 部分。

print-text <text>

输出文本到stdout。字符串可以包含属性（参见 属性扩展 ）。注意把参数放在引号里。

show-text <text> [<duration>|-1 [<level>]]

在OSD上显示文本。字符串可以包含属性，如 属性扩展 中所述。这可以用来显示播放时间、文件名，等等。 no-osd 对该命令无效。

<duration>

显示信息的时间，单位是ms。默认情况下，它使用与 --osd-duration 相同的值

<level>

显示文本的最小OSD层级（参见 --osd-level ）

expand-text <text>

对参数进行属性扩展，并返回扩展后的字符串。这只能通过client API或脚本中的 mp.command_native 来使用。（见 属性扩展 ）

expand-path "<text>"

将一个路径的double-tilde占位符扩展为一个特定平台的路径。与 expand-text 一样，这只能通过client API或脚本中的 mp.command_native 来使用。

示例

mp.osd_message(mp.command_native({"expand-path", "~~home/"}))

这一行Lua将在OSD上显示用户的mpv设置目录的位置。

normalize-path <filename>

通过将路径 filename 转换为绝对路径、删除连续的斜线、删除 . 部分、解析 .. 组件以及在 Windows 上将斜线转换为反斜线，返回路径 filename 的规范表示。除非平台是 Unix-like，且路径组件之一是 ..，否则不会解析符号链接。如果 filename 是一个 URL，则会原封不动地返回。只能通过client API 或使用 mp.command_native 的脚本使用。

示例

mp.osd_message(mp.command_native({"normalize-path", "/foo//./bar"}))

这行Lua在OSD上输出 “/foo/bar”

escape-ass <text>

修改 text 以便解析 ASS 标记的命令和函数，如 osd-overlay 和 mp.create_osd_overlay 会逐字显示并返回。只能通过client API 或使用 mp.command_native 的脚本使用。

示例

mp.osd_message(mp.command_native({"escape-ass", "foo {bar}"}))

这行Lua在OSD上输出 “foo \{bar}”

show-progress

在OSD上显示进度条、已用时间和文件的总时间。 no-osd 对该命令无效

write-watch-later-config

写入 quit-watch-later 命令所写的恢复设置文件，但继续正常播放。

delete-watch-later-config [<filename>]

删除任何由 quit-watch-later 或 write-watch-later-config 写入的现有恢复设置文件。如果指定了文件名，那么删除的是该文件的设置；否则，就是在当前情况下由 quit-watch-later 或 write-watch-later-config 写入的设置。

stop [<flags>]

停止播放并清除播放列表。在默认设置下，这基本上类似 quit 。对client API很有用：可以在不终止播放器的情况下停止播放。

第一个参数是可选的，并支持以下标志：

keep-playlist

不清除播放列表。

mouse <x> <y> [<button> [<mode>]]

向指定的坐标（ <x>, <y> ）发送一个鼠标事件。

第二个参数：

<button>

被点击的鼠标按钮的按钮编号。这应该是0-19中的一个。如果 <button> 被省略，只有位置会被更新

第三个参数：

<single> （默认）

鼠标事件代表常规的单击

<double>

鼠标事件代表双击

keypress <name> [<scale>]

通过mpv的输入处理程序发送一个key event，触发为该按键设置的任何行为。 name 使用 input.conf 的命名方案来命名按键和修饰键。 scale 用于缩放由绑定命令引起的数值变化（与精确滚动机制相同）。对client API 非常有用：key events可以发送到 libmpv，由 libmpv 在内部处理。

keydown <name>

类似于 keypress ，但设置了 KEYDOWN 标志，因此，如果按键被绑定到一个可重复的命令，它将随着mpv的按键重复计时重复运行，直到 keyup 命令被再次调用。

keyup [<name>]

设置 KEYUP 标志，停止任何已经触发的重复行为。 name 是可选的。如果 name 没有指定或为空字符串， KEYUP 将被设置在所有按键上。否则， KEYUP 将只设置在 name 指定的键上。

keybind <name> <command>

将一个键与一个输入命令绑定。 command 必须是一个完整的命令，包含所有需要的参数和标志。 name 和 command 都使用 input.conf 的命名方式。这主要对client API有用。

audio-add <url> [<flags> [<title> [<lang>]]]

加载指定的音频文件。参见 sub-add 命令。

audio-remove [<id>]

移除指定的音轨。参见 sub-remove 命令。

audio-reload [<id>]

重新加载指定的音轨。参见 sub-reload 命令。

video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]

加载指定的视频文件。常见选项参见 sub-add 命令。

albumart (MPV_FORMAT_FLAG)

如果启用，mpv将加载指定视频作为专辑封面。

video-remove [<id>]

移除指定的视频轨道。参见 sub-remove 命令。

video-reload [<id>]

重新加载指定的视频轨道。参见 sub-reload 命令。

rescan-external-files [<mode>]

根据当前的 --sub-auto, --audio-file-auto 和 --cover-art-auto 设置重新扫描外部文件。这可以用来自动加载外部文件，在文件被加载 之后 。

mode 参数是以下之一：

<reselect> （默认）

选择默认的音频和字幕流，这通常会选择具有最高优先级的外部文件（这个实现并不完美，可以根据要求进行改进）

<keep-selection>

不改变当前的音轨选择

context-menu

在视频窗口上显示上下文菜单。详见 上下文菜单 部分。

可能变更的输入命令

af <operation> <value>

变更音频滤镜链。参见 vf 命令。

vf <operation> <value>

变更视频滤镜链。

其语义与选项解析完全相同（参见 视频滤镜 ）。因此，下面的文字是一个多余的、不完整的总结。

第一个参数决定发生什么：

<set>

用新的滤镜链覆盖之前的滤镜链

<add>

将新的滤镜链追加到之前的滤镜链后方

<toggle>

检查指定的滤镜（有准确的参数）是否已经存在视频滤镜链中。如果存在，移除该滤镜。如果不存在，则追加该滤镜（如果多个滤镜被传递到命令中，逐个滤镜执行）

一个特殊的变量是把它和标签结合起来，用 @name 不带滤镜名称和参数作为滤镜条目。这样就可以切换启用/禁用标志。

<remove>

类似 toggle ，但始终移除滤镜链上的指定滤镜

<clr>

移除所有滤镜。注意，和其他子命令一样，这并不能控制自动插入的滤镜

参数总是需要的。例如，如果 clr ，使用 vf clr ""

你可以通过在滤镜前加上 @name: （其中 name 是用户选择的任意标识符）为滤镜指定标签。标签可以用来在所有的滤镜链修改命令中用名字来指代滤镜。对于 add 来说，使用一个已经使用过的标签将取代现有的滤镜。

vf 命令在修改滤镜链后在OSD上显示所请求的滤镜列表。这大致相当于 show-text ${vf} 。注意，用于格式转换的自动插入的滤镜不显示在列表中，只显示用户请求的内容。

通常情况下，命令会检查视频链是否重新创建成功，失败时将撤销操作。如果命令在视频设置之前运行（如果命令在打开文件后，在视频帧被解码之前立即运行，就可能发生），这个检查就不能运行。那么就可能发生创建视频链失败的情况。

input.conf的示例

• a vf set vflip a 键把视频上下颠倒

• b vf set "" b 键移除所有视频滤镜

• c vf toggle gradfun c 键切换去色带

如何在运行时切换禁用的滤镜的示例

• 在 mpv.conf 中加入类似 vf-add=@deband:!gradfun 的内容。 @deband: 是标签，是用户为这个滤镜条目任意起的名字。滤镜名称前的 ! 默认情况下禁用该过滤器。之后的内容是正常的滤镜名称和可能的滤镜参数，就像正常的 --vf 语法一样。

• 在 input.conf 中添加 a vf toggle @deband 。当按下 a 键时，这将切换标签为 deband 的过滤器的 “disable” 标志。

cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]

循环一系列值的列表。每次调用该命令将把指定的属性设置为列表中的下一个值。该命令将使用属性/选项的当前值，并利用它来确定当前在值列表中的位置。一旦找到它，将设置为列表中的下一个值（如果需要的话，将回到第一个项目）。

这个命令的参数数量不定，不能与命名参数一起使用。

特殊参数 !reverse 可以用来反向循环值列表。唯一的好处是，在添加第二个按键绑定的时候，你不需要自己反转值列表进行循环。

enable-section <name> [<flags>]

除mpv内部使用外，此命令已过时。

启用命名的输入部分的所有按键绑定。

启用的输入部分形成一个堆栈。在堆栈顶部的部分的绑定比下部的部分优先。这条命令将该部分放在堆栈的顶部。如果该部分已经在堆栈上，它将被事先隐式地移除（一个部分不能在堆栈中出现多次）。

参数 flags 可以是下列标志的组合（用 + 分隔）：

<exclusive>

在新启用的部分之前启用的所有部分都被禁用。一旦它们上面的所有独占部分被移除，它们将被重新启用。换句话说，新的部分会影射所有之前的部分。

<allow-hide-cursor>

此功能不能通过公开API使用。

<allow-vo-dragging>

同上。

disable-section <name>

除mpv内部使用外，此命令已过时。

禁用命名的输入部分。撤销 enable-section 。

define-section <name> <contents> [<flags>]

除mpv内部使用外，此命令已过时。

创建一个命名的输入部分，或者替换一个已经存在的输入部分的内容。 contents 参数使用与 input.conf 文件相同的语法（除了不允许在其中使用section的语法），包括需要用换行符来分隔绑定的内容。

如果 contents 参数是一个空字符串，则该部分被移除。

名为 default 的部分是正常的输入部分。

一般来说，输入部分必须用 enable-section 命令启用，否则会被忽略。

最后一个参数有如下含义：

<default> （如果省略了该参数也可）

只有当用户还没有把这个键绑定到一个命令时，才使用这个部分定义的按键绑定。

<force>

始终绑定一个按键（如果有歧义，则使用最近被激活的输入部分）。

这个命令可以用来给脚本或客户端API用户分配任意的键。如果输入部分定义了 script-binding 的命令，也可以获得单独的按键up/down事件，以及相对详细的按键状态信息。特殊的键名 unmapped 可以用来匹配任何未映射的按键。

overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride> <dw> <dh>

添加一个来自原始数据的OSD叠加层。这对控制mpv的脚本和应用程序可能很有用，它们想在视频窗口上面显示内容。

叠加层通常是以屏幕分辨率显示的，但对于某些视频输出驱动来说，分辨率会降低到视频的分辨率。你可以阅读 osd-width 和 osd-height 属性。至少对于 --vo-xv 和变形视频（如DVD）， osd-par 也应该被读取，并且覆盖层应该遵循是宽高比补偿的。

这有以下命名参数。它们的顺序是不被保证的，所以你应该始终用命名参数来调用它们，参见 命名参数

id 是一个介于0到63之间的整数，用于识别叠加元素。这个ID可以用来添加多个覆盖部分，通过使用这个命令更新一个已经存在的ID的部分，或者用 overlay-remove 来移除一个部分。使用一个先前未使用的ID将添加一个新的覆盖层，而重复使用一个ID将更新它。

x 和 y 指定OSD应该显示的位置。

file 指定从原始图像数据读取的文件。它可以是以 @ 为前缀的数字UNIX文件描述符（例如： @4 ），也可以是文件名。文件将被 mmap() 映射到内存中，被复制，并在命令返回前解除映射（在mpv 0.18.1中已改变）。

也可以通过传递内存地址作为整数前缀的 & 字符来传递原始内存地址作为位图内存使用。在这里传递错误的东西会使播放器崩溃。这种模式在与libmpv一起使用时可能很有用。 offset 参数被简单地添加到内存地址中（从mpv 0.8.0开始，之前被忽略）。

offset 是源文件中第一个像素的字节偏移（目前的实现总是将整个文件从位置0到图像的末端进行mmap，所以应该避免大的偏移量。在mpv 0.8.0之前，偏移量实际上是直接传递给 mmap 的，但为了使用更方便，它被改变了）。

fmt 是一个标识图像格式的字符串。目前，只有 bgra 被定义。这种格式每个像素有4个字节，每个部分有8位。最不重要的8位是蓝色，最重要的8位是alpha（在little endian中，组成是B-G-R-A，B是第一个字节）。这使用了预乘alpha：每个颜色分量都已经与alpha分量相乘。这意味着每个分量的数值都等于或小于alpha分量（违反这个规则会导致不同视频输出驱动的不同结果：由于混合损坏的alpha值而导致的数值溢出被认为是不应该发生的事情，因此，在这种情况下，该实现并不能确保你得到可预测的行为）。

w , h` 和 stride 指定覆盖层的尺寸。 w 是覆盖层的可见宽度，而 stride 给出的是内存中的字节宽度。在简单的情况下，使用 bgra 格式， stride==4*w 。一般来说，访问的内存总量是 stride * h （从技术上讲，最小的尺寸是 stride * (h - 1) + w * 4 ，但是为了简单起见，播放器将访问所有 stride * h 的字节）。

dw 和 dh （可选）指定叠加层的显示尺寸。叠加层的可见部分（ w 和 h ）在显示时会根据 dw 和 dh 按比例缩放。 如果没有参数，则使用 w 和 h 的值。

备注

在mpv 0.18.1之前，当更新一个覆盖层时，你必须手动进行“双重缓冲”，用一个不同的内存缓冲区来替换它。从mpv 0.18.1开始，内存被简单地复制，并且在提交返回后不引用任何由命令参数指示的内存。如果你想在mpv 0.18.1之前使用这个命令，请阅读旧的文档，看看如何正确处理这个问题。

overlay-remove <id>

移除用 overlay-add 添加的相同ID的覆盖层。如果没有这个ID的覆盖层，则不做任何处理。

osd-overlay

添加/更新/移除一个OSD覆盖层。

（尽管这听起来与 overlay-add 相似， osd-overlay 是用于文本覆盖，而 overlay-add 是用于位图。也许 overlay-add 将被合并到 osd-overlay 中，以消除这种奇怪的现象。）

你可以用它来添加ASS格式的文本覆盖层。ASS有高级的定位和渲染标签，可以用来渲染几乎所有种类的矢量图形。

这个命令接受以下参数：

id

识别覆盖层的任意整数。用不同的 id 参数调用此命令，可以添加多个覆盖层。用相同的 id 调用这个命令，会替换之前设置的覆盖层。

每个libmpv客户端（即IPC连接、脚本）都有一个单独的命名空间，所以ID可以由API用户编排和分配，而不会与其他API用户冲突。

如果libmpv客户端被销毁，所有与之相关的覆盖层也会被移除。特别是，通过 --input-ipc-server 连接，添加一个覆盖层，然后断开连接，将再次立即移除该覆盖层。

format

给出覆盖层类型的字符串。接受以下值（HTML渲染已损坏，请查看生成的手册，或原始RST源）：

ass-events

参数 data 是一个字符串。该字符串在换行符上被分隔。每一行都被转化为 Dialogue ASS事件的 Text 部分。计时是不使用的（但依赖计时的ASS标签的行为可能会在未来的mpv版本中改变）。

注意，最好把多行放入 data ，而不是添加多个OSD覆盖。

这提供了2个ASS的 Styles 。 OSD 包含由当前 --OSD-... 选项定义的文本样式。 Default 也是类似的，包含 OSD 在所有选项都设置为默认情况下的风格。

此外， res_x 和 res_y 选项指定 ASS PlayResX 和 PlayResY 头部域的值。如果 res_y 被设置为0， PlayResY 将被初始化为一个任意的默认值（但注意这个命令的默认值是720，不是0）。如果 res_x 被设置为0， PlayResX 将根据 res_y 来设置，这样虚拟的ASS像素就有一个方形的像素宽高比。

none

特殊值，导致覆盖层被移除。除了 id 和 format 以外的大多数参数都被忽略。

data

根据 format 参数，定义覆盖内容的字符串。

res_x , res_y

如果 format 被设置为 ass-events （参见那部分的描述），则使用。这是可选的，默认为0/720。

z

叠加的Z顺序。这是可选的，默认为0。

注意，不同格式的覆盖层之间的Z顺序是静态的，不能改变（目前，这意味着由 overlay-add 添加的位图覆盖层总是在由 osd-overlay 添加的ASS覆盖层之上）。此外，内置的OSD组件总是在任何自定义OSD的下方（这包括任何形式的字幕以及由 show-text 渲染的文本）。

未来的mpv版本可能会随机改变不同OSD格式和内置OSD之间的Z顺序的处理方式。

hidden

如果设置为 true，就不显示它（默认： false）。

compute_bounds

如果设置为 true，尝试确定边界并将其作为 x0, x1, y0, y1 的矩形写入命令的结果值（默认： false）。如果矩形是空的，未知的，或者某种程度上是退化的，则不设置。 x1/y1 是矩形的底端独占角的坐标。

结果值可能取决于视频输出驱动窗口的大小，并且是基于调用时最后已知的窗口大小。这意味着结果可能与实际渲染的内容不同。

对于 ass-events ，结果矩形被重新计算为 PlayRes 坐标（ res_x / res_y ）。如果窗口尺寸未知，就会选择一个回退值。

你应该意识到这个机制是非常低效的，因为它渲染了全部的结果，然后使用渲染的位图列表的边界框（即使 hidden 被设置）。它将刷新各种缓存。它的结果也取决于所使用的libass版本。

该功能是实验性的，可能会以某种方式再次改变。

备注

始终使用命名参数（ mpv_command_node() ）。Lua脚本应该使用 mp.create_osd_overlay() 帮助器，而不是直接调用这个命令。

script-message [<arg1> [<arg2> [...]]]

向所有clients发送一条消息，并把以下参数列表传递给它。这个消息是什么意思，它需要多少个参数，以及这些参数是什么意思，完全由接收方和发送方决定。每个client都会收到这个消息，所以要注意命名的冲突（或者使用 script-message-to ）。

这个命令的参数数量不定，不能与命名参数一起使用。

script-message-to <target> [<arg1> [<arg2> [...]]]

与 script-message 相同，但只发送给名为 <target> 的client。每个client（脚本等）都有一个唯一的名字。例如，Lua脚本可以通过 mp.get_script_name() 获得其名称。注意，clients名只能由字母数字字符和 _ 组成。

这个命令的参数数量不定，不能与命名参数一起使用。

script-binding <name>

调用一个脚本提供的按键绑定。这可以用来重新映射由外部Lua脚本提供的按键绑定。

参数是绑定的名称。

它可以选择以脚本的名称为前缀，使用 / 作为分隔符，例如 script-binding scriptname/bindingname 。注意，脚本名称只能由字母数字字符和 _ 组成。

为了完整起见，这里是这个命令的内部工作方式。细节可能随时改变。在任何匹配的按键事件中， script-message-to 或 script-message 被调用（取决于是否包含脚本名称），参数如下：

1. 字符串 key-binding

2. 绑定的名称（如上所述）

3. 作为字符串的按键状态（见下文）

4. 按键名称（从mpv0.15.0开始）

5. 该键将产生的文本，如果不适用，则为空字符串

第5个参数只有在没有修饰键的情况下才会被设置（将shift键与字母一起使用通常不会发出带有修饰键的消息，而是会生成大写文本，但某些后端可能会出错）。

按键状态由2个字符组成：

1. d``（键被按下）， ``u （被释放）， r （键仍然在下，并且被重复；只有当此绑定的键重复被启用时）， p （键被按下；如果上/下不能被追踪，则发生）

2. 事件是否来自鼠标， m （鼠标按钮）或 - （其它）

未来的版本可能增加更多的参数和更多的按键状态字符，以支持更多的输入特性。

ab-loop

在A-B循环状态中循环。第一次命令将设置 A 点（ ab-loop-a 属性）；第二次是 B 点，第三次将清除两个点。

drop-buffers

删除音频/视频/解复用器的缓存，并从新开始刷新。这可能有助于处理无法同步的流。这个命令在将来可能会被修改或移除。

screenshot-raw [<flags>]

在内存中返回一个屏幕截图。这只能通过client API使用。这个命令返回的MPV_FORMAT_NODE_MAP的 w, h, stride 字段被设置为明显的内容。 format 字段默认设置为 bgr0 。这个格式被组织为 B8G8R8X8 （其中 B 是LSB）。填充物 X 的内容是未定义的。 data 字段是MPV_FORMAT_BYTE_ARRAY类型，包含实际图像数据。当结果mpv_node被释放时，图像也被释放。像通常的client API语义一样，你不允许写入图像数据。

stride 是指从 (x0, y0) 的像素到 (x0, y0 + 1) 的像素的字节数。如果图像被裁剪，或者有边距，这个数字可以大于 w * 4 。这个数字也可以是负数。你可以用 byte_index = y * stride + x * 4 访问一个像素（假设是 bgr0 格式）。

flags 参数与 screenshot 的第一个参数一样，支持 subtitles, video, window

vf-command <label> <command> <argument> [<target>]

向滤镜发送命令。请注意，目前这只适用于 lavfi 滤镜。有关每个滤镜支持的命令列表，请参阅 libavfilter 文档。

<label> 是 mpv 滤镜的标签，使用 all 一次发送到所有滤镜。

<command> 和 <argument> 是滤镜指定的字符串。

<target> 是滤镜或滤镜实例名称，默认为 all 。请注意，对于支持目标的过滤器（如复杂的 lavfi 过滤器链），目标是一个额外的指定符。

af-command <label> <command> <argument> [<target>]

与 vf-command 相同，但用于音频滤镜。

apply-profile <name> [<mode>]

应用一个已命名的配置预设的内容。这就像在设置文件中使用 profile=name ，你除了可以把它映射到一个按键绑定，也可在运行时更改它。

模式参数：

default

应用该配置文件。如果省略该参数，则为默认。

restore

恢复执行 apply-profile 命令应用该配置预设之前的选项。只有当配置预设的 profile-restore 设置为相关的模式时才有效。如果没有操作执行，则输出一个警告。详情参见 运行时的配置预设

load-config-file <filename>

加载配置文件，类似于 --include 选项。如果文件已经包含，则在重新解析前不会重置其先前的选项。

load-input-conf <filename>

加载输入配置文件，类似于 --input-conf 选项。如果该文件已被包含，则在重新解析前不会重置其先前的绑定。

load-script <filename>

加载一个脚本，类似于 --script 选项。这是否等待脚本完成初始化已被改变了多次，未来的行为未被定义。

成功后，返回一个 mpv_node ，其 client_id 字段设置为新创建的脚本句柄的 mpv_client_id() API调用的返回值。

change-list <name> <operation> <value>

该命令改变一系列的选项列表，如 列表选项 中所述。 <name> 参数是普通的选项名称，而 <operation> 是选项的后缀或操作。

有些操作不取值，但命令仍然需要值参数。在这些情况下，值必须是一个空字符串。

示例

change-list glsl-shaders append file.glsl

将一个文件添加到 glsl-shaders 列表中。在命令行中相当于 --glsl-shaders-append=file.glsl 或者 --glsl-shader=file.glsl

dump-cache <start> <end> <filename>

将当前的缓存转储到指定的文件名。如果名为 <filename> 的文件已经存在，它将被覆盖。 <start> 和 <end> 给出要转储的时间范围。如果在给定的时间范围内没有数据被缓存，则可能没有数据被转储（创建一个没有数据包的文件）。

转储较大部分的缓存将冻结播放器。我们没有努力去解决这个问题，因为这个功能主要是为了创建小的摘录。

请参见 --stream-record 的各种注意事项，这些注意事项大多也适用于这个命令，因为两者都使用相同的底层代码来编写输出文件。

如果 <filename> 是一个空字符串，正在进行的 dump-cache 将被停止。

如果 <end> 是 no ，则启用连续转储。然后，在转储现有的缓存部分后，从网络上读取的任何内容也会被追加到缓存中。这与 --stream-record 相似（尽管它与该选项不冲突，而且它们可以同时激活）。

如果 <end> 时间在缓存之后，该命令将 _不_ 等待并将新收到的数据写入缓存。

结果文件的结尾处可能会有轻微的损坏或不完整（没有做出足够的努力来保证末端的正确对齐）。

注意，这个命令只有在转储结束后才会结束。这意味着它的工作原理与 screenshot 命令类似，只是它可以阻挡更长的时间。如果使用连续转储，该命令将不会结束，直到停止播放、发生错误、运行另一个 dump-cache 命令，或者调用 mp.abort_async_command 这样的API来明确停止该命令。请看 同步与异步

备注

这主要是为网络流创建的。对于本地文件，可能有更好的方法来创建摘录之类的。有很多更友好的Lua脚本，通过催生一个单独的 ffmpeg 实例来重新编码文件的一部分。对于网络流，这不是那么容易做到的，因为流必须再次被下载。即使使用 --stream-record 将流记录到本地文件系统，也可能会有问题，因为记录的文件仍然被写入。

这个命令是实验性的，关于它的所有细节在将来可能会改变。

ab-loop-dump-cache <filename>

本质上是调用``dump-cache``，以当前AB循环点为参数。与 dump-cache 一样，这将覆盖名为 <filename> 的文件。同样地，如果B点被设置为 no ，它将在现有的缓存被转储后进入连续转储。

如果发现有足够的动力将这个功能转移到一个微不足道的Lua脚本中，作者保留删除这个命令的权利。

ab-loop-align-cache

在 ab-loop-dump-cache 命令将（可能）转储的缓存内，重新调整A/B循环点的起点和终点。基本上，它将关键帧上的时间对齐。猜测可能会有偏差，特别是在结尾处（由于重新转换带来的精度问题）。如果缓存在此期间缩小了，该命令设置的点也不会是有效参数。

这个命令的未来比 ab-loop-dump-cache 更不确定，如果作者认为它没有用，可能会消失而不被替换。

begin-vo-dragging

如果当前 VO 支持，则开始拖动窗口。该命令只能在按下鼠标键时调用，否则将被忽略。该命令的具体效果取决于 VO 对窗口拖动的实现。例如，在 Windows 中，只有鼠标左键可以开始拖动窗口，而 X11 和 Wayland 则允许使用其他鼠标键。

未记录的命令： ao-reload （实验性的/内部的）。

事件列表

这是一个部分的事件列表。本节描述了 mpv_event_to_node() 返回的内容，也就是脚本API和JSON IPC看到的内容。注意，C语言API有单独的C语言级别的声明与 mpv_event ，可能略有不同。

请注意，事件是异步的：当事件被传递给脚本和其他它户端时，播放器核心继续运行。在某些情况下，你可以用hooks来强制执行同步执行。

所有的事件都可以有以下字段：

event

事件的名称（如由 mpv_event_name() 返回）。

id

reply_userdata 字段（不透明的用户值）。如果 reply_userdata 是0，该字段不被添加。

error

设置为一个错误字符串（如由 mpv_error_string() 返回）。如果没有发生错误，或者事件类型不报告错误，这个字段就会丢失。大多数事件不设置这个字段。

这个列表使用事件名称字段的值，以及括号中的C API符号：

start-file ( MPV_EVENT_START_FILE )

发生在一个新文件被加载之前。当你收到它时，播放器正在加载文件（或者可能已经完成）。

它有以下字段：

playlist_entry_id

现在正在加载的文件的播放列表条目ID。

end-file ( MPV_EVENT_END_FILE )

发生在一个文件被卸载后。通常情况下，播放器将立即加载下一个文件，如果这是最后一个文件，则退出。

该事件有以下字段：

reason

有这些值之一：

eof

该文件已经结束。这可以（但不一定）包括不完整的文件或网络连接中断的情况。

stop

播放被一个命令结束。

quit

播放是通过发送退出命令结束的。

error

发生了一个错误。在这种情况下，有一个 error 字段和错误字符串。

redirect

发生在播放列表和类似的情况。详情见C API中的 MPV_END_FILE_REASON_REDIRECT

unknown

未知。通常不会发生，除非Lua的API与C的API不同步（同样，也可能发生你的脚本得到的原因字符串在你写入脚本的时候还不存在）。

playlist_entry_id

正在播放或试图播放的文件的播放列表条目ID。这个值与相应的 start-file 事件中的 playlist_entry_id 字段相同。

file_error

设置为mpv错误字符串，描述播放失败的大致原因。如果不知道错误，就不设置（在Lua脚本中，这个值是直接设置在 error 字段上。从mpv 0.33.0开始，这已经被废弃了。在未来，这个 error 字段对于这个特定事件将被取消设置）。

playlist_insert_id

如果加载结束，因为要播放的播放列表条目是例如一个播放列表，而当前的播放列表条目被一些其它条目所取代。这种情况至少在 MPV_END_FILE_REASON_REDIRECT 中可能发生（其它事件类型将来可能出于类似但不同的目的使用这个）。在这种情况下， playlist_insert_id 将被设置为第一个插入条目的播放列表条目ID，而 playlist_insert_num_entries 则是插入的播放列表条目的总数。注意，在这种特定情况下，最后插入的条目的ID是 playlist_insert_id+num-1 。请注意，根据情况，你可能会在看到事件之前观察到新的播放列表条目（例如，在收到事件之前读取 “playlist” 属性或获得属性变化通知）。如果在C API中为0，这个字段就不会被添加。

playlist_insert_num_entries

参见 playlist_insert_id 。只有当 playlist_insert_id 存在时才会出现。

file-loaded ( MPV_EVENT_FILE_LOADED )

发生在一个文件被加载并开始播放之后。

seek ( MPV_EVENT_SEEK )

发生在跳转时（这可能包括播放器内部跳转的情况，即使没有用户交互。这包括例如播放有序章节的Matroska文件时的片段变化）。

playback-restart ( MPV_EVENT_PLAYBACK_RESTART )

在跳转后或文件被加载后的开始播放。

shutdown ( MPV_EVENT_SHUTDOWN )

当播放器退出时发送，脚本应该终止。通常是自动处理。参见 `Details on the script initialization and lifecycle`_

log-message (MPV_EVENT_LOG_MESSAGE)

接收用 mpv_request_log_messages() 启用的信息（Lua: mp.enable_messages ）。

除了默认的事件字段外，它还包含以下字段：

prefix

模块前缀，识别消息的发件人。当使用 --v 选项时，这是终端播放器放在消息文本前面的东西，也是用于 --msg-level 的东西。

level

日志级别为字符串。参见 msg.log 了解可能的日志级别名称。请注意，mpv的后续版本可能会增加新的级别或移除（未记录的）现有级别。

text

日志信息。该文本将以换行符结束。有时它可能包含多行。

请记住，这些信息是为了提供人性化的提示。你不应该解析它们，而且信息的前缀/级别/文本可能随时改变。

hook

该事件有以下字段：

hook_id

要传递给 mpv_hook_continue() 的ID。Lua脚本包装器通过 mp.add_hook() 提供了一个更好的API。

get-property-reply ( MPV_EVENT_GET_PROPERTY_REPLY )

参见C API.

set-property-reply ( MPV_EVENT_SET_PROPERTY_REPLY )

参见C API.

command-reply ( MPV_EVENT_COMMAND_REPLY )

这是 error 字段有意义的命令之一。

JSON IPC和Lua以及可能的其它后端会特别处理这个问题，可能不会将实际的事件传递给用户。参见C API。

该事件有以下字段：

result

任何 mpv_node 类型的结果（成功时），如果有的话。

client-message ( MPV_EVENT_CLIENT_MESSAGE )

Lua和可能的其它后端对其进行特殊处理，可能不会将实际事件传递给用户。

该事件有以下字段：

args

包含信息数据的字符串数组。

video-reconfig ( MPV_EVENT_VIDEO_RECONFIG )

发生在视频输出或过滤器的重新配置上。

audio-reconfig ( MPV_EVENT_AUDIO_RECONFIG )

发生在音频输出或过滤器的重新配置上。

property-change ( MPV_EVENT_PROPERTY_CHANGE )

当被观察的属性改变值时发生。

该事件有以下字段：

name

属性的名称。

data

该属性的新值。

以下事件也会发生，但已过时。 idle , tick 使用 mpv_observe_property() (Lua: mp.observe_property() ) 来替代。

Hooks

Hooks是播放器核心和脚本或类似的东西之间的同步事件。这适用于客户端API（包括Lua脚本接口）。通常情况下，事件应该是异步的，而hook API提供了一种笨拙而不明显的方式来处理需要更严格协调的事件。没有做出任何API稳定性的保证。不完全遵循协议会使播放器随机冻结。基本上，没有人应该使用这个API。

C API在头文件里有描述。Lua API在Lua部分有描述。

在对API客户端实际调用hook之前，它将尝试为所有在hook之前被改变的观察到的属性返回新的值。这可能使应用程序更容易通过注册hook在属性变化通知之间设置定义的“障碍”（这意味着这些hooks会有效果，即使您什么也不做并使它们立即继续）。

目前定义了以下hooks：

on_load

当一个文件要被打开时，在实际做任何事情之前被调用。例如，你可以读写 stream-open-filename 属性来重定向一个URL到其它地方（考虑支持很少给用户一个直接的媒体URL的流媒体网站），或者你可以通过设置 file-local-options/<option name> 属性来设置每个文件选项。播放器将等待，直到所有hooks都运行。

排序在 start-file 之后和 playback-restart 之前。

on_load_fail

在文件被打开后调用但失败时。这可以用来在本地解复用器无法识别文件的情况下提供一个回退，而不是像 on_load 那样总是在本地解复用器之前运行。只有当 stream-open-filename 被改变时，才会重试解复用。如果它再次失败，这个hook就不会再被调用，并且加载肯定会失败。

排序在 on_load 之后， playback-restart 和 end-file 之前。

on_preloaded

在文件被打开后，在轨道被选择和解码器被创建前被调用。如果API用户想根据可用的音轨集手动选择音轨，这有一定的用处。这对于通过API以特定方式初始化 --lavfi-complex 也很有用，而不必一开始就“探测”可用的流。

注意，这还没有应用默认的轨道选择。究竟哪些操作可以做，哪些不可以做，哪些信息可以用，哪些还不能用，都有待于改变。

排序在 on_load_fail 等之后， playback-restart 之前。

on_unload

在关闭文件之前运行，在实际取消一切初始化之前。在这种状态下不可能恢复播放。

排序在 end-file 之前。在错误的情况下也会发生（那就在 on_load_fail 之后）。

on_before_start_file

在发送 start-file 事件之前运行（如果任何客户端改变了当前的播放列表条目，或者向播放器发送了退出命令，相应的事件在hook返回后将不会实际发生）。在加载新的文件之前，对排出属性的变化很有用。

on_after_end_file

在 end-file 事件后运行。有助于在文件结束后排出属性变化。

输入命令前缀

这些前缀放在按键名和实际命令之间。可以指定多个前缀。它们之间用空格隔开。

osd-auto

使用该命令的默认行为。这是 input.conf 中命令的默认值。一些libmpv/scripting/IPC APIs不使用它作为默认，而是使用 no-osd

no-osd

不要为该命令使用任何OSD。

osd-bar

如果可能的话，为该命令显示一个条状图。跳转命令会显示进度条，改变属性的命令可能会显示新设定的值。

osd-msg

如果可能的话，为该命令显示一个OSD信息。跳转命令会显示当前的播放时间，改变属性的命令会以文本形式显示新设定的值。

osd-msg-bar

结合osd-bar和osd-msg。

raw

不在字符串参数中展开属性（如 "${property-name}" ）。这是一些libmpv/scripting/IPC APIs的默认设置。

expand-properties

所有的字符串参数都按照 属性扩展 中的描述进行扩展。这是 input.conf 中命令的默认设置。

repeatable

对于某些命令来说，一直按着一个按键不会重复运行命令。这个前缀在任何情况下都强制启用按键重复。对于一个命令列表：第一个命令决定了整个列表的可重复性（到0.33版本为止 —— 一个列表总是可重复的）。

async

允许异步执行（如果可能）。注意，只有少数命令会支持这一点（通常这一点有明确的记录）。有些命令默认是异步的（或者说，它们的效果可能会在命令完成后表现出来）。这个标志的语义在未来可能会改变。只有当你不依赖这个命令的效果在它返回时完全实现时才设置它。参见 同步与异步

sync

允许同步执行（如果可能）。通常情况下，所有的命令默认都是同步的，但有些命令默认是异步的，以便与旧版的行为兼容。

所有的osd前缀仍然被全局的 --osd-level 设置所覆盖。

同步与异步

async 和 sync 的前缀只关系到命令发出方如何等待命令的完成。通常情况下，它不会影响命令本身的表现方式。有以下几种情况：

• 正常的input.conf命令总是以异步方式运行。慢速运行的命令排队或并行运行。

• “多个” input.conf命令（1个按键绑定，用 ; 串联）将被依次执行，但那些异步的命令除外（要么以 async 为前缀，要么某些命令默认为异步）。这些异步命令会以分离的方式运行，可能与列表中其余的同步命令并行。

• 普通的Lua和libmpv命令（例如 mpv_command() ）是以阻塞方式运行的，除非使用了 async 前缀，或者该命令默认为异步的。这意味着在同步的情况下，调用者会阻塞，即使核心继续播放。异步模式是以分离的方式运行命令。

• 异步libmpv命令API（例如 mpv_command_async() ）永远不会阻塞调用者，并且总是用消息通知他们完成。 sync 和 async 的前缀没有区别。

• Lua还提供了运行异步命令的API，其行为类似于C语言的对应命令。

• 在所有情况下，异步模式仍然可以以同步的方式运行命令，甚至在分离模式下。例如，当一个命令没有异步实现的时候，就会发生这种情况。在这种情况下，异步libmpv API仍然不会阻塞调用者。

在mpv 0.29.0之前， async 前缀只被截图命令使用，并使它们以分离的方式运行文件保存代码。现在这是默认的， async 只在上面提到的方面改变行为。

目前，以下命令在同步与异步下有不同的等待特性：sub-add, audio-add, sub-reload, audio-reload, rescan-external-files, screenshot, screenshot-to-file, dump-cache, ab-loop-dump-cache

异步命令详情

在API层面上，每个异步命令都与启动它的上下文绑定。例如，由 mpv_command_async 启动的异步命令被绑定到传递给函数的 mpv_handle 。只有这个 mpv_handle 能收到完成通知（ MPV_EVENT_COMMAND_REPLY ），而且只有这个句柄能直接中止仍在运行的命令。如果 mpv_handle 被销毁，由它启动的任何仍在运行的异步命令都会被终止。

脚本API和JSON IPC给每个脚本/连接提供了自己的隐式 mpv_handle

如果播放器被关闭，核心可能会自行中止所有悬而未决的异步命令（就像代表API用户对每个悬而未决的命令强制调用 mpv_abort_async_command() 。这发生在发送 MPV_EVENT_SHUTDOWN 的同时，而且没有办法阻止它。

输入区

输入区将一套绑定分组，并一次性启用或禁用它们。在 input.conf 中，每个按键的绑定都被分配到一个输入区，而不是实际有明确的文本区。

另参见： enable-section 和 disable-section 命令。

预定义的绑定：

default

没有输入区的绑定被隐含地分配给这个区。它在正常播放时默认是启用的。

encode

在编码模式下激活的区。它被独立启用，所以在 default 区的绑定被忽略。

属性

属性被用于在运行时设置mpv选项，或者查询任意信息。它们可以用 set/add/cycle 命令操作，用 show-text 检索，或者其它任何使用属性扩展的方法。(参见 属性扩展 ）。

属性名称用RW注释的，表示该属性通常是可写的。

如果一个选项被引用，该属性通常会采取/返回与该选项完全相同的值。在这些情况下，属性只是一种在运行时改变选项的方法。

属性列表

备注

大多数选项也可以通过属性在运行时设置。只需从选项名称中移除前面的 -- 。下面没有记录这些内容，参见 选项 。只有那些不存在同名的选项的属性，或者与选项有非常不同的行为的属性才会在下面记录。

标记为(RW)的属性是可写的，而那些没有标记的是只读的。

audio-speed-correction video-speed-correction

与播放器尝试播放文件的 speed 相乘的系数。通常情况下，它正好是1。（显示同步模式将使其有用）

OSD格式将以 +1.23456% 的形式显示，数字是 (raw - 1) * 100 ，用于给定的原始属性值。

display-sync-active

--video-sync=display 是否实际激活。

filename

当前播放的文件，路径已剥离。如果这是一个URL，也尝试取消百分比编码。（结果不一定正确，但看起来更适合显示。使用 path 属性来获取未修改的文件名）

这有一个子属性：

filename/no-ext

类似 filename 属性，但如果文本中包含 . ，则剥离最后一个 . 后的所有文本。通常这将移除文件扩展名。

file-size

源文件/流的长度，以字节为单位。（这与 ${stream-end} 相同。对于分段/多段的文件，这将返回主文件或清单文件的大小，无视它的格式）

estimated-frame-count

当前文件中的总帧数。

备注

这只是一个估计值。（它是由两个不可靠的数量计算出来的：帧数和流长度）

estimated-frame-number

当前数据流中的当前帧数。

备注

这只是一个估计值。（它是由两个不可靠的数量计算出来的：帧数和可能是取整的时间戳）

pid

mpv的进程ID。

path

当前播放文件的完整路径。通常这和你在mpv命令行或 loadfile 命令中传递的字符串完全一样，即使它是一个相对路径。如果你期望一个绝对路径，你将不得不自行检测，例如通过使用 working-directory 属性。

stream-open-filename

当前播放的媒体的完整路径。这只在特殊情况下与 path 不同。特别是，如果使用了 --ytdl=yes ，并且URL是由 youtube-dl 检测的，那么脚本将把这个属性设置为实际的媒体URL。这个属性应该只在 on_load 或 on_load_fail hook期间设置，否则它将没有效果（或者可能在未来做一些实现定义的事情）。如果当前媒体播放结束，该属性将被重置。

media-title

如果当前播放的文件有一个 title 标签，则使用该标签。

否则，返回 filename 属性。

file-format

文件格式的符号名称。在某些情况下，这是一个用逗号分隔的格式名称列表，例如mp4是 mov,mp4,m4a,3gp,3g2,mj2 （对于任何格式，这个列表在将来可能会增加）

current-demuxer

当前解复用器的名称。（这个没有用处）

（由 demuxer 重命名而来）

stream-path

流层面的文件名（完整路径）。（这可能没有用处，几乎不会与 path 不同）

stream-pos

源流中的原始字节位置。从技术上讲，它返回传递给解码器的最新数据包的位置。

stream-end

源流中的原始结束位置，以字节为单位。

duration

当前文件的持续时间，以秒为单位。如果持续时间未知，该属性不可用。注意，文件的持续时间并不总是准确的，所以这是一个估计值。

它取代了 length 属性，该属性在mpv0.9发布后已过时。（语义是一样的）

它有一个子属性：

duration/full

即 duration 附带毫秒数

avsync

最近的A/V同步差异。如果音频或视频被禁用，则不可用。

total-avsync-change

已完成的总A-V同步校正。如果音频或视频被禁用，则不可用。

decoder-frame-drop-count

解码器的丢帧数，由于视频进度远落后于音频（当使用 --framedrop=decoder 时）。有时，在其它情况下，例如视频封装损坏，或解码器不遵循通常的规则，这可能会增加丢帧数。如果视频被禁用，则不可用。

frame-drop-count

视频输出驱动的丢帧数（当使用 --framedrop=vo 时）。

mistimed-frame-count

为了保持A/V同步，在显示同步模式下没有正确计时的视频帧数。这不包括外部情况，例如视频渲染太慢或图形驱动程序以某种方式跳过垂直同步。它也不包括取整的错误（特别是在源时间戳不正常的情况下可能发生）。例如，使用 display-desync 模式时，不应该把这个值从0改变。

vsync-ratio

对于一个帧平均显示多少个垂直同步。这只在display-sync被激活时可用。对于60Hz屏幕上的30FPS视频，这将是2。这是实际预定的动态平均数，所以60Hz时的24FPS不会永远精确地保持在2.5，而是根据最后显示的帧抖动。

vo-delayed-frame-count

在显示同步模式下，由于外部条件造成的延迟帧数的估计值。注意一般来说，mpv不得不猜测这种情况的发生，而且猜测的结果可能不准确。

percent-pos (RW)

当前文件中的位置（0-100）。使用它而不是从其它属性中计算的好处是，如果文件的持续时间未知，它可以正确地退回从字节位置到估计的播放位置。

time-pos (RW)

当前文件中的位置，以秒为单位。

它有一个子属性：

time-pos/full

即 time-pos 附带毫秒数

time-start

已过时。在mpv0.14之前，它用于返回文件的开始时间（可能影响例如传输流）。参见 --rebase-start-time 选项。

time-remaining

文件的剩余长度，以秒为单位。注意，文件的持续时间并不总是准确已知的，所以这是一个估计值。

它有一个子属性：

time-remaining/full

即 time-remaining 附带毫秒数

audio-pts

当前文件中的音频播放位置（秒）。与time-pos不同，它的更新频率高于每帧一次。对于纯音频文件，它几乎等同于时间位置，而对于纯视频文件，这个属性不可用。

它有一个子属性：

audio-pts/full

即 audio-pts 附带毫秒数

playtime-remaining

time-remaining 与当前的 speed 相乘。

它有一个子属性：

playtime-remaining/full

即 playtime-remaining 附带毫秒数

playback-time (RW)

在当前文件中的位置，以秒为单位。与 time-pos 不同，时间被钳制在文件的范围内。（不准确的文件持续时间等可能使它超出范围。在尝试跳转到文件范围以外时很有用，因为跳转的目标时间被认为是跳转过程中的当前位置）。

它有一个子属性：

playback-time/full

即 playback-time 附带毫秒数

chapter (RW)

当前的章节编号。第一章的编号是0。

edition (RW)

当前的MKV edition编号。将此属性设置为一个不同的值将重新开始播放。第一个edition的号码是0。

在mpv0.31.0之前，如果你没有手动设置选项或属性，这显示的是在运行时选择的实际版本。在mpv0.31.0及以后的版本中，这严格地返回用户设置的选项或属性值，并且增加了 current-edition 属性来返回运行时选择的版本（默认情况下这与 --edition=auto 有关）。

current-edition

当前选择的edition。如果没有加载文件，或者文件没有版本，该属性就不可用。（Matroska文件在没有editions和单一edition之间有区别，这将反映在该属性中，尽管在实际中并不重要）

chapters

章节的数量。

editions

MKV editions的数量。

edition-list

editions的列表，当前条目被标记。目前，原始属性值是无用的。

这有一系列子属性。用基于0来取代 N 的edition索引

edition-list/count

edition的数量。如果没有edition，它可以是0或1（如果有一个无用的伪版本，就是1）

edition-list/N/id (RW)

edition ID为整数。用它来设置 edition 属性。目前，这与edition索引相同

edition-list/N/default

这是否是默认的edition

edition-list/N/title

存储在文件中的edition标题。不总是可获取的

当用client API使用 MPV_FORMAT_NODE 查询该属性时，或用Lua mp.get_property_native ，这将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each edition)
        "id"                MPV_FORMAT_INT64
        "title"             MPV_FORMAT_STRING
        "default"           MPV_FORMAT_FLAG

metadata

元数据键/值对。

如果用Lua的 mp.get_property_native 访问该属性，这将返回一个元数据键与元数据值映射的表。如果是通过client API访问，则返回一个 MPV_FORMAT_NODE_MAP ，其中标签键映射到标签值。

对于OSD，它返回一个格式化的列表。尝试以原始字符串的形式检索这个属性是无效的。

这有一系列子属性：

metadata/by-key/<key>

元数据条目 <key> 的值

metadata/list/count

元数据条目的数量

metadata/list/N/key

第N个元数据条目的键名（第一个条目是 0 ）

metadata/list/N/value

第N个元数据条目的值

metadata/<key>

旧版本的 metadata/by-key/<key> 。不鼓励使用，因为元数据的关键字符串可能与其他子属性冲突

这个属性的布局可能会有变化。欢迎提出建议，这个属性到底应该如何工作。

当使用client API使用 MPV_FORMAT_NODE 查询该属性时，或使用Lua mp.get_property_native ，这将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_MAP
    (key and string value for each metadata entry)

filtered-metadata

类似 metadata ，但只包括 --display-tags 选项中列出的字段。这也是输出到终端的标签集。

chapter-metadata

当前章节的元数据。作用类似于 metadata 属性。它也允许同样的访问方法（使用子属性）。

每一章的元数据是非常罕见的。通常情况下，只有章节名称（ title ）被设置。

为了访问其它信息，如章节的开始，参见 chapter-list 属性。

vf-metadata/<filter-label>

由视频滤镜添加的元数据。通过滤镜标签获取，如果没有使用 @filter-label: 语法明确指定，将是 <filter-name>NN

工作原理类似于 metadata 属性。它允许同样的访问方法（使用子属性）。

这种元数据的一个例子是由 --vf=lavfi=cropdetect 添加的剪裁参数。

af-metadata/<filter-label>

相当于 vf-metadata/<filter-label> ，但用于音频滤镜。

deinterlace-active

如果 mpv 的去隔行扫描滤波器处于活动状态，则返回 yes/true 。请注意，它不会检测任何通过 --vf 手动插入的隔行扫描滤波器。

idle-active

如果没有文件被加载，但由于 --idle 选项，播放器在附近驻留，返回 yes /true。

（由 idle 改名而来）

core-idle

播放核心是否暂停。在特殊情况下，这可能与 pause 不同，例如当播放器由于网络缓存不足而自行暂停。

如果播放正在重启或根本没有播放，这也会返回 yes /true。换句话说，只有在真正有视频播放的情况下，才会返回 no /false。（从mpv0.7.0开始的行为）

cache-speed

缓存和下层（如网络）之间的当前I/O读取速度。这给出了1秒内的字节数（使用client API的 MPV_FORMAT_INT64 类型）

这与 demuxer-cache-state/raw-input-rate 相同

demuxer-cache-duration

视频在解复用器中缓存的大致持续时间，以秒为单位。这个猜测非常不可靠，通常无法获取这个属性，即使数据已缓存。

demuxer-cache-time

视频在解复用器中缓存的大致时间，以秒为单位。与 demuxer-cache-duration 相同，但返回解复用器中缓冲数据的最后时间戳。

demuxer-cache-idle

解复用器是否处于空闲状态，这意味着解复用器的缓存已经填充到要求的数量，目前没有读取更多数据。

demuxer-cache-state

seekable-ranges 中的每个条目代表了解复用器缓存中可以被搜索到的区域，其中的 start 和 end 字段包含各自的时间戳。如果有多个解复用器在运行，这只返回关于“主”解复用器的信息，但将来可能会改变为返回所有解复用器的统一信息。这些范围的顺序是任意的。通常情况下，范围在被合并之前会有一些重叠。在边缘情况下，范围可能多处重叠。

跳转范围的末端通常比 demuxer-cache-time 属性返回的值小，因为该属性返回的是猜测的缓冲量，而跳转范围代表的是实际可用于缓冲跳转的缓冲数据。

bof-cached 表示具有最低时间戳的跳转范围是否指向流的开始（BOF）。这意味着你完全不能在这个位置之前跳转。 eof-cached 表示具有最高时间戳的跳转范围是否指向流的末端（EOF）。如果 bof-cached 和 eof-cached 都为true，并且只有一个缓存范围，则整个数据流都被缓存。

fw-bytes 是在当前解码位置开始的范围内缓冲的数据包的字节数。这是一个粗略的估计（可能没有正确考虑到各种开销），并在解复用器的位置停止（它忽略了之后的跳转范围）。

file-cache-bytes 是存储在文件缓存中的字节数。这包括所有的开销，以及可能的未使用的数据（如修剪的数据）。如果文件缓存没有和 --cache-on-disk=yes 一起启用，就缺失这个数据。

cache-end 是 demuxer-cache-time 。如果不可用则缺失。

reader-pts 是缓冲范围开始的大致时间戳。如果不可用则缺失。

cache-duration``是`demuxer-cache-duration 。如果不可用则缺失。

raw-input-rate 是网络层（或任何其他层级向字节的输入层）的估计输入率，单位是字节每秒。可能不准确或丢失。

ts-per-stream 是一个数组，包含视频、音频和字幕等每种流类型的条目。对于每种数据流类型，该数据流类型的解串器缓存详情可作为 cache-duration 、reader-pts 和 cache-end 提供。

当用client API用 MPV_FORMAT_NODE 查询该属性时，或用Lua mp.get_property_native ，这将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_MAP
    "seekable-ranges"   MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP
            "start"             MPV_FORMAT_DOUBLE
            "end"               MPV_FORMAT_DOUBLE
    "bof-cached"        MPV_FORMAT_FLAG
    "eof-cached"        MPV_FORMAT_FLAG
    "fw-bytes"          MPV_FORMAT_INT64
    "file-cache-bytes"  MPV_FORMAT_INT64
    "cache-end"         MPV_FORMAT_DOUBLE
    "reader-pts"        MPV_FORMAT_DOUBLE
    "cache-duration"    MPV_FORMAT_DOUBLE
    "raw-input-rate"    MPV_FORMAT_INT64
    "ts-per-stream"     MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP
              "type"            MPV_FORMAT_STRING
              "cache-duration"  MPV_FORMAT_DOUBLE
              "reader-pts"      MPV_FORMAT_DOUBLE
              "cache-end"       MPV_FORMAT_DOUBLE

其他字段（将来可能被改变或删除）：

eof

读取器线程是否达到了文件的末端

underrun

读者器线程是否不能满足解码器对新数据包的请求

idle

线程是否目前没有在被读取

total-bytes

整个数据包队列的数据包字节数之和（加上一些开销的估计），包括缓存的可跳转范围

demuxer-via-network

通过主解复用器解复用的流是否最可能通过网络播放。构成“网络”的部分并不总是清楚的，可能用于其他类型的不可信任的流，在某些情况下可能是错误的，而且它的定义可能正在改变。另外，外部文件（如独立的音频文件或流）并不影响这个属性的值（目前）。

demuxer-start-time

解复用器报告的开始时间，以带小数的秒为单位。

paused-for-cache

播放是否因等待缓存而暂停。

cache-buffering-state

缓存填充状态的百分比（0-100），直到播放器取消暂停（与 paused-for-cache 有关）。

eof-reached

是否到达播放进度的结束。注意通常只有当 --keep-open 被启用时，这才有意义，因为否则播放器会立即播放下一个文件（或退出或进入空闲模式），在这些情况下， eof-reach 属性被设置后，在逻辑上将立即被清除。

seeking

播放器目前是否正在跳转，或以其他方式尝试重新开始播放（有可能在文件加载时返回 yes /true。这是因为相同的底层代码被用于跳转和重新同步）。

mixer-active

音频混音器是否激活。

这个选项相对来说是无用的。在mpv0.18.1之前，它可以用来推断 volume 属性的行为。

ao-volume (RW)

系统音量。这个属性只有在mpv音频输出当前处于激活状态时才可用，并且只有在底层实现支持音量控制时才可用。这个选项的作用取决于API。例如，在ALSA上，这通常会改变整个系统的音频，而在PulseAudio上，这控制每个应用的音量。

ao-mute (RW)

与 ao-volume 相似，但控制静音状态。即使 ao-volume 起效，也可能未实现。

audio-params

由音频解码器输出的音频格式。这有一系列子属性：

audio-params/format

采样格式的字符串。这与mpv其它地方使用的名称相同

audio-params/samplerate

采样率

audio-params/channels

声道布局的字符串。这与 --audio-channels 接受的内容相似

audio-params/hr-channels

类似 channels ，但不是发送至音频设备的可能的隐秘的实际布局，而是返回一个希望更容易被人阅读的形式（通常只有 audio-out-params/hr-channels 有意义）

audio-params/channel-count

音频声道的数量。这与上面描述的 channels 字段是重复的

当用client API的 MPV_FORMAT_NODE 查询该属性，或用Lua mp.get_property_native ，这将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_MAP
    "format"            MPV_FORMAT_STRING
    "samplerate"        MPV_FORMAT_INT64
    "channels"          MPV_FORMAT_STRING
    "channel-count"     MPV_FORMAT_INT64
    "hr-channels"       MPV_FORMAT_STRING

audio-out-params

和 audio-params 相同，但却是写入到音频API的数据格式。

colormatrix

重定向到 video-params/colormatrix 。这个参数（以及类似的参数）可以被 format 视频滤镜覆盖。

colormatrix-input-range

参见 colormatrix 。

·colormatrix-primaries`

参见 colormatrix 。

hwdec (RW)

反映 --hwdec 选项。

如果可能的话，对它的写入可以改变当前使用的硬件解码器（在内部，播放器可能会重新初始化解码器，并将执行一次跳转以正确刷新视频）。你可以关注其他的hwdec属性来观察这是否成功。

与mpv0.9.x及之前的版本不同的是，这并不返回当前激活的硬件解码器。从mpv0.18.0开始， hwdec-current 可用于此目的。

hwdec-current

当前正在使用的硬件解码。如果解码是激活的，返回 hwdec 选项/属性所使用的值之一。 no /false表示软件解码。如果没有加载解码器，该属性不可用。

hwdec-interop

这将返回当前加载的硬件解码/输出interop驱动程序。这只有在视频输出程序被打开后才知道（也可能是后来）。对于某些视频输出（如 gpu ），这可能永远不会提前知道，而只在解码器成功尝试创建硬件解码器时才知道（使用 --gpu-hwdec-interop 可以加急加载）。如果有多个驱动程序被加载，它们将以 , 分隔。

如果没有视频输出被激活或没有已知的interop驱动，这个属性就不可用。

这不一定使用与 hwdec 相同的值。同一硬件解码器可以有多个interop驱动，这取决于平台和视频输出。

width, height

视频尺寸。这使用解码后的视频尺寸，或者如果还没有解码的视频帧，则使用（可能不正确的）容器显示的尺寸。

video-params

视频参数，由解码器输出（和覆写的例如应用的长宽比等）。这有一系列子属性：

video-params/pixelformat

像素格式的字符串。这与mpv的其它地方使用的名称相同

video-params/hw-pixelformat

基本像素格式的字符串。这与某些硬件解码的情况有关，否则无法使用

video-params/average-bpp

每像素的平均比特数，为整数。子采样的平面格式使用不同的分辨率，这就是这个值有时会很奇怪或令人困惑的原因。在某些格式中可能不可用

video-params/w, video-params/h

视频尺寸为整数，没有应用长宽比校正

video-params/dw, video-params/dh

视频尺寸为整数，按正确的长宽比进行缩放

video-params/crop-x, video-params/crop-y

源视频帧的裁切偏移量

video-params/crop-w, video-params/crop-h

视频裁切后的尺寸

video-params/aspect

显示长宽比为浮点数

video-params/aspect-name

以字符串形式显示宽高比名称。该名称与特定宽高比的电影胶片格式名相对应。

video-params/par

像素长宽比

video-params/sar

存储长宽比

video-params/sar-name

字符串形式的存储宽高比名称

video-params/colormatrix

使用中的色彩矩阵的字符串（精确值可能会变化）

video-params/colorlevels

动态范围的字符串（精确值可能会变化）

video-params/primaries

使用中的色彩原色的字符串（精确值可能会变化）

video-params/gamma

使用中的伽马函数的字符串（精确值可能会变化）

video-params/sig-peak

视频文件标记的信号峰值，以浮点数表示（已过时）

video-params/light

使用中的亮度类型的字符串（精确值可能会变化）

video-params/chroma-location

色度采样的字符串（精确值可能会变化）

video-params/rotate

预设的显示旋转度数（顺时针）

video-params/stereo-in

源文件的立体3D模式（参见 format 视频滤镜的 stereo-in 选项）

video-params/alpha

透明度类型。如果格式没有透明通道，这将是不可用的（但在未来的版本中，它可能变为 no ）。如果有，这将被设置为 straight 或 premul

video-params/min-luma

HDR10 元数据报告的最低亮度（单位：cd/m²）

video-params/max-luma

HDR10 元数据报告的最高亮度（单位：cd/m²）

video-params/max-cll

HDR10 元数据报告的最大内容亮度（单位：cd/m²）

video-params/max-fall

HDR10 元数据报告的最大帧平均亮度（单位：cd/m²）

video-params/scene-max-r

由 HDR10+ 元数据报告的场景 R 分量的最大 RGB 值（单位：cd/m²）

video-params/scene-max-g

由 HDR10+ 元数据报告的场景 G 分量的最大 RGB 值（单位：cd/m²）

video-params/scene-max-b

由 HDR10+ 元数据报告的场景 B 分量的最大 RGB 值（单位：cd/m²）

video-params/max-pq-y

帧的最大 PQ 亮度，由峰值检测报告（单位 PQ，0-1）

video-params/avg-pq-y

帧的平均 PQ 亮度，由峰值检测报告（单位 PQ，0-1）

当使用client API的 MPV_FORMAT_NODE 查询该属性时，或者用Lua mp.get_property_native ，将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_MAP
    "pixelformat"       MPV_FORMAT_STRING
    "hw-pixelformat"    MPV_FORMAT_STRING
    "w"                 MPV_FORMAT_INT64
    "h"                 MPV_FORMAT_INT64
    "dw"                MPV_FORMAT_INT64
    "dh"                MPV_FORMAT_INT64
    "aspect"            MPV_FORMAT_DOUBLE
    "par"               MPV_FORMAT_DOUBLE
    "colormatrix"       MPV_FORMAT_STRING
    "colorlevels"       MPV_FORMAT_STRING
    "primaries"         MPV_FORMAT_STRING
    "gamma"             MPV_FORMAT_STRING
    "sig-peak"          MPV_FORMAT_DOUBLE
    "light"             MPV_FORMAT_STRING
    "chroma-location"   MPV_FORMAT_STRING
    "rotate"            MPV_FORMAT_INT64
    "stereo-in"         MPV_FORMAT_STRING
    "average-bpp"       MPV_FORMAT_INT64
    "alpha"             MPV_FORMAT_STRING
    "min-luma"          MPV_FORMAT_DOUBLE
    "max-luma"          MPV_FORMAT_DOUBLE
    "max-cll"           MPV_FORMAT_DOUBLE
    "max-fall"          MPV_FORMAT_DOUBLE
    "scene-max-r"       MPV_FORMAT_DOUBLE
    "scene-max-g"       MPV_FORMAT_DOUBLE
    "scene-max-b"       MPV_FORMAT_DOUBLE
    "max-pq-y"          MPV_FORMAT_DOUBLE
    "avg-pq-y"          MPV_FORMAT_DOUBLE

dwidth, dheight

视频显示尺寸。这是应用了滤镜和长宽比缩放之后的视频尺寸。实际的视频窗口大小仍可能与此不同，例如，如果用户手动调整视频窗口的大小。

这些值与 video-out-params/dw 和 video-out-params/dh 相同。

video-dec-params

非常类似 video-params ，但不应用覆写。

video-out-params

与 video-params 相同，但在视频滤镜被应用后。如果没有使用视频滤镜，这将包含与 video-params 相同的值。请注意，这仍然不一定是视频窗口所使用的，因为用户可以改变窗口的大小，所有真正的视频输出驱动都独立于滤镜链而自行缩放。

拥有与 video-params 相同的子属性。

video-target-params

类似 video-params ，但与 VO 输出的目标属性有关。

拥有与 video-params 相同的子属性。

video-frame-info

当前帧的大致信息。请注意，如果在OSD上使用这些信息，由于OSD重绘和帧显示有些脱节，信息可能会有几帧的偏差，你可能不得不暂停并强制重绘。

这有一系列子属性：

video-frame-info/picture-type

图片的类型。它可以是 “I”（关键）、”P”（前向参考）、”B”（双向参考）或不可用

video-frame-info/interlaced

帧的内容是否交错

video-frame-info/tff

如果内容是隔行扫描，是否先显示顶场

video-frame-info/repeat

解码时是否必须延迟帧数

container-fps

容器FPS。这很容易包含假的值。对于使用现代容器格式或视频编解码器的视频，这往往是不正确的。

（由 fps 重命名）

estimated-vf-fps

视频滤镜链输出的估计/测量的FPS（如果没有使用滤镜，这对应解码器输出）。这使用过去10帧的平均时间来计算FPS。如果涉及到丢帧，它将是不准确的（比如当明确的启用了framedrop，或在精确跳转之后）。具有不精确时间戳的文件（如Matroska）可能导致不稳定的结果。

current-window-scale (RW)

根据当前窗口大小计算的 window-scale 值。如果窗口大小在设置选项后没有改变，并且窗口大小没有受到其他方面的限制，那么这个值与 window-scale 相同。如果窗口是全屏的，这将返回从窗口的最后一次非全屏尺寸计算出来的比例值。如果没有视频被激活，该属性不可用。

也可以写入该属性。这与写入 window-scale 的行为相同。请注意，写入 current-window-scale 不会影响 window-scale 的值。

focused

窗口是否处于焦点。可能并非所有视频输出驱动都支持。

display-names

mpv窗口所包含的显示器的名称。在X11上，这些是xrandr名称（LVDS1, HDMI1, DP1, VGA1, 等等）。在Windows上，这些是GDI名称（\.DISPLAY1，\.DISPLAY2，等等），列表中的第一个显示器将是Windows认为与该窗口相关的（由MonitorFromWindow API决定）。在 macOS 上，这些是系统信息中使用的显示产品名称，括号中是序列号，由于一个窗口只能在一个屏幕上显示，因此只返回一个显示名称。在 Wayland 上，如果使用的协议版本 >= 4（LVDS-1、HDMI-A-1、X11-1 等），这些是 wl_output 名称；如果使用的协议版本 <4，这些是 geometry 事件报告的 wl_output 模型。

display-fps

当前显示器的刷新率。目前，这是视频涵盖的任何显示器的最低FPS，由底层系统API检索（例如X11的xrandr）。它不是测量的FPS。它不一定在所有平台上都可用。注意，任何列出的事实都可能在没有警告的情况下随时改变。

estimated-display-fps

显示器刷新的实际速度，由系统时间测量。只有在display-sync模式（由 --video-sync 选择）激活时才可用。

vsync-jitter

垂直同步持续时间的估计偏差系数。

display-width, display-height

当前显示器的水平和垂直分辨率，以像素为单位。这些值是否在mpv窗口改变显示时更新，取决于窗口化后端。它并非在所有平台上都可用。

display-hidpi-scale

由窗口后端报告的HiDPI比例系数。如果没有视频输出程序被激活，或者视频输出没有报告一个值，这个属性是不可用的。报告一个绝对的DPI可能更合理，然而，这是大多数操作系统API实现HiDPI支持的方式。另参见 --hidpi-window-scale

osd-width, osd-height

最近的已知的OSD宽度（可以是0）。如果你想使用 overlay-add 命令，就需要这个。它给你实际的OSD/窗口尺寸（不包括操作系统窗口管理器绘制的装饰）。

是 osd-dimensions/w 和 osd-dimensions/h 的别名

osd-par

最近的已知的OSD显示像素长宽比（可以是0）。

是 osd-dimensions/osd-par 的别名

osd-dimensions

最近的已知的OSD尺寸。

有以下子属性（可以作为 MPV_FORMAT_NODE 或Lua表用 mp.get_property_native 读取）：

osd-dimensions/w

OSD渲染单元中的视频输出驱动窗口的尺寸（通常是像素，但也可以用视频输出例如 xv 的缩放像素）

osd-dimensions/h

OSD渲染单元中的视频输出驱动窗口的尺寸

osd-dimensions/par

OSD的像素长宽比（通常为1）

osd-dimensions/aspect

视频输出驱动窗口的显示长宽比（用上面的属性计算）

osd-dimensions/mt, osd-dimensions/mb, osd-dimensions/ml, osd-dimensions/mr

OSD到视频的（上、下、左、右）空白距离。这描述了视频被渲染的区域

如果视频输出窗口没有被创建或不可见，这些属性中的任何一个都可能不可用或被设为伪值。

term-size

当前终端尺寸。

它有两个子属性。

term-size/w

终端宽度，以单元格为单位

term-size/h

终端高度，以单元格为单位

此属性不可观测。响应尺寸变化需要轮询。

window-id

只读的 - mpv的窗口ID。可能并不总是可用的，例如，由于窗口尚未被打开或不被视频输出驱动支持。

mouse-pos

只读 —— 最近的已知的鼠标位置，根据OSD尺寸常规化。

有以下子属性（可以用 MPV_FORMAT_NODE 或 mp.get_property_native 读取Lua表）：

mouse-pos/x, mouse-pos/y

鼠标指针的最后已知坐标

mouse-pos/hover

布尔值 —— 鼠标指针是否悬停在视频窗口上。当此值为false时，坐标应被忽略，因为视频后端只有在指针悬停窗口时才会更新坐标

touch-pos

只读 - 最后已知的触摸点位置，按 OSD 尺寸标准化。

它有多个子属性。将 N 替换为基于 0 的触摸点索引。每当有新的手指触摸屏幕时，就会有一个新的触摸点被添加到触摸点列表中，其中可用的未使用的 N 最小。

touch-pos/count

活动触摸点的数量。

touch-pos/N/x , touch-pos/N/y

第 N 个触摸点的位置。

touch-pos/N/id

触摸点的唯一标识符。当单个触摸点的索引发生变化时，该标识符可用于识别单个触摸点。

在client API 中使用 MPV_FORMAT_NODE 或 Lua mp.get_property_native 查询属性时，将返回一个 mpv_node 并包含以下内容：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each touch point)
        "x"        MPV_FORMAT_INT64
        "y"        MPV_FORMAT_INT64
        "id"       MPV_FORMAT_INT64

sub-ass-extradata

当前 ASS 字幕轨道的额外数据。不进行格式化。额外数据将以字符串形式按原样返回。此属性不适用于非 ASS 类的字幕轨。

sub-text

当前的字幕文本，不管字幕是否可见。格式被剥离。如果字幕不是基于文本的（例如DVD/BD字幕），将返回一个空字符串。

它有不同格式的子属性：

sub-text/ass

类似 sub-text ，但返回ASS格式的文本。其他格式的文本字幕会被转换。对于原生ASS字幕，不包含任何文本（但是矢量图等）的事件不会被过滤掉。如果多个事件与当前播放时间相匹配，它们会用换行符连接起来。只包含事件的“文本”部分。

这个属性不足以正确渲染ASS字幕，因为ASS header和每个事件的元数据没有被返回。使用 /ass-full 作为取代方案。

sub-text/ass-full

类似于 sub-text-ass ，但返回包含所有字段的完整事件，格式为 .ass 文本文件中的行。与 sub-ass-extradata 一起使用可获得样式信息。

sub-text-ass （已过时）

已过时的 sub-text/ass 的别名。

secondary-sub-text

与 sub-text 相同（子属性也如此），但用于次字幕。

sub-start

当前字幕的开始时间（以秒为单位）。如果有多个当前字幕，返回第一个的开始时间。如果没有当前的字幕被呈现，将返回null。

它有一个子属性：

sub-start/full

sub-start 以毫秒为单位

secondary-sub-start

与 sub-start 相同，但用于次字幕。

sub-end

当前字幕的结束时间（以秒为单位）。如果有多个当前字幕，返回最后的结束时间。如果没有当前的字幕被呈现，或者有呈现但持续时间未知或不正确，则返回null。

它有一个子属性：

sub-end/full

sub-end 以毫秒为单位

secondary-sub-end

与 sub-end 相同，但用于次字幕。

playlist-pos (RW)

当前在播放列表中的位置。第一个条目是在0的位置。写入这个属性将在新位置开始播放。

在某些情况下，这不必是当前播放的文件。参见 playlist 中的 current 和 playing 标志的解释。

如果播放列表是空的，或者如果它不是空的，但没有条目是 “current” 的，这个属性就会返回-1。同样，写入-1将使播放器进入空闲模式（如果没有启用空闲模式则退出播放）。（在mpv0.33.0之前，如果没有播放列表条目是“当前的”，这个属性就不可用）

将当前值写回属性不会有任何影响。如果需要，可使用 playlist-play-index 重启当前条目的播放。

playlist-pos-1 (RW)

与 playlist-pos 相同，但基于1。

playlist-current-pos (RW)

播放列表中的 “current” 项目的索引。这通常是，但不必是当前正在播放的项目（参见 playlist-playing-pos ）。根据播放器的确切内部状态，它可能指的是下一个要播放的播放列表项目，或者用于决定下一个播放内容的播放列表项目。

对于读取，这与 playlist-pos 完全相同。

对于写入，这 只 设置 “current” 项目的位置，而不停止当前文件的播放（或者开始播放，如果这是在空闲模式下进行的）。使用-1来移除当前标志。

这个属性只是隐约有用。如果在播放过程中设置，它通常会导致播放列表中 后 的条目被接下来播放。另一个可能很奇怪的观察状态是，如果在播放过程中运行 playlist-next ，这个属性会被设置为下一个要播放的播放列表条目（与前面的情况不同）。有一个内部标志来决定是播放当前的播放列表条目还是下一个，这个标志目前对API用户来说是不可访问的（这种行为是否会被保留，可能会有变化）

playlist-playing-pos

播放列表中 “正在播放” 的项目的索引。如果一个播放列表项目正在加载、实际播放或正在卸载，它就是 “playing” 。这个属性在 MPV_EVENT_START_FILE ( start-file ) 和 MPV_EVENT_START_END ( end-file ) 事件中被设置。除此以外，它返回-1。如果播放列表条目在播放过程中被移除，但播放还没有停止，或正在停止，它也会返回-1（这至少在状态转换时可能发生）。

在“正在播放”状态下，这通常与 playlist-pos 相同，除了在状态转换时，或者如果 playlist-current-pos 被明确写入。

playlist-count

总共的播放列表条目的数量。

playlist-path

mpv展开条目之前，当前条目的原始播放列表路径。如果文件最初没有以某种方式与播放列表相关联，则不可用。

playlist

播放列表，当前标记的条目。目前，原始属性值是无用的。

这有一系列子属性。用基于0代替 N 的播放列表条目索引

playlist/count

播放列表条目的数量（与 playlist-count 相同）

playlist/N/filename

第N个条目的文件名

playlist/N/playing

如果 playlist-playing-pos 属性指向此条目，则为 yes /true，否则为 no /false或不可用

playlist/N/current

如果 playlist-current-pos 属性指向此条目，则为 yes /true，否则为 no /false或不可用

playlist/N/title

第N个条目的名称。如果播放列表文件包含这样的字段，并且是受mpv解析器支持的播放列表格式，或者如果播放列表条目之前已被打开，并且已经获得了一个与文件名不同的媒体标题，则可用

playlist/N/id

这个条目的唯一ID。这是一个自动分配的整数ID，在当前mpv核心实例的整个生命周期中是唯一的。其他命令、事件等使用它作为 playlist_entry_id 字段

playlist/N/playlist-path

mpv展开此条目之前的播放列表的原始路径。如果文件最初没有以某种方式与播放列表相关联，则不可用

当client API使用 MPV_FORMAT_NODE 查询该属性时，或者用Lua mp.get_property_native ，这将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each playlist entry)
        "filename"  MPV_FORMAT_STRING
        "current"   MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
        "playing"   MPV_FORMAT_FLAG (same)
        "title"     MPV_FORMAT_STRING (optional)
        "id"        MPV_FORMAT_INT64

track-list

音频/视频/字幕的轨道列表，当前条目被标记。目前，原始属性值是无用的。

这有一系列子属性。用基于0代替 N 的轨道索引。

track-list/count

轨道的总数

track-list/N/id

用于 --sid/--aid/--vid 的ID。这在同一类型的轨道中是唯一的（字幕/音频/视频），但在其他方面不是

track-list/N/type

描述媒体类型的字符串。 audio, video, sub 之一

track-list/N/src-id

源文件中使用的轨道ID。不总是可用的（如果格式没有原生ID，如果轨道是一个伪轨道，在实际文件中不存在这种方式，或者如果格式由libavformat处理，而格式没有被列入有轨道ID的白名单，它就会丢失）

track-list/N/title

储存在文件中的轨道标题。并非总是可用

track-list/N/lang

文件中标识的轨道语言。并非总是可用

track-list/N/image

如果这是一个由单一图片组成的视频轨道，则为 yes /true，否则为 no /false或不可用。用来确定一个流是否是图像的启发式方法并不尝试检测通常用于视频的编解码器中的图像。否则，它是可靠的

track-list/N/albumart

如果这是一个嵌入音频文件或外部的封面图像，则为 yes /true，否则为 no /false或不可用

track-list/N/default

如果该轨道在文件中设置了默认标志，则为 yes /true，否则为 no /false或不可用

track-list/N/forced

如果文件中设置了force标志，则为 yes /true，否则为 no /false或不可用

track-list/N/codec

该轨道使用的编解码器名称，例如 h264 。在某些罕见情况下不可用

track-list/N/codec-desc

此音轨使用的编解码器描述性名称

track-list/N/codec-profile

此音轨使用的编解码器配置文件。仅在音轨已被解码的情况下可用

track-list/N/external

如果该轨道是一个外部文件，则为 yes /true，否则为 no /false或不可用。这是为独立的字幕文件设置的

track-list/N/external-filename

如果轨道来自外部文件的文件名，否则不可用

track-list/N/selected

如果该轨道目前已被解码，则为 yes /true，否则为 no /false或不可用

track-list/N/main-selection

它表示同一类型的轨道的选择顺序。如果一个轨道没有被选中，或被 --lavfi-complex 选中，它就不可用。对于字幕轨道， 0 代表 sid ， 1 代表 secondary-sid

track-list/N/ff-index

通常由FFmpeg工具使用的流索引。注意，如果使用libavformat（ --demuxer=lavf ）以外的解复用器，可能会出现错误。对于mkv文件，即使使用默认（内置）的解复用器，索引通常也会匹配，但并不能保证

track-list/N/decoder

如果正在解码此轨道，则为简短的解码器名称

track-list/N/decoder-desc

如果这个轨道正在被解码，则是人性化的可读的解码器名称

track-list/N/demux-w, track-list/N/demux-h

容器显示的视频尺寸提示（不总是准确）

track-list/N/demux-crop-x, track-list/N/demux-crop-y

源视频帧的裁切偏移量

track-list/N/demux-crop-w, track-list/N/demux-crop-h

裁切后的视频尺寸

track-list/N/demux-channel-count

容器显示的音频声道数量（并不总是准确 —— 特别是音轨可能被解码为不同数量）

track-list/N/demux-channels

容器显示的声道布局（不总是准确）

track-list/N/demux-samplerate

容器显示的音频采样率（不总是准确）

track-list/N/demux-fps

容器显示的视频FPS（不总是准确）

track-list/N/demux-bitrate

音频平均比特率，以每秒比特为单位（不总是准确）

track-list/N/demux-rotation

视频顺时针旋转元数据，以度为单位

track-list/N/demux-par

像素长宽比

track-list/N/format-name

ffmpeg 格式的简短名称。如果音轨是音频，这将是采样格式的名称。如果音轨是视频，这将是像素格式的名称。

track-list/N/audio-channels （已过时）

过时的 track-list/N/demux-channel-count 的别名

track-list/N/replaygain-track-peak, track-list/N/replaygain-track-gain

每条轨道的回放增益值。只适用于源文件中存储有相应信息的音轨

track-list/N/replaygain-album-peak, track-list/N/replaygain-album-gain

每张专辑的回放增益值。如果文件有每个音轨但没有每个专辑的信息，每个专辑的值将从目前的每个音轨的值中复制。在这种情况下，未来的mpv版本有可能使这些属性反而不可用。

track-list/N/dolby-vision-profile, track-list/N/dolby-vision-level

Dolby Vision 配置文件和级别。如果容器不提供此信息，则可能不可用。

当用client API的 MPV_FORMAT_NODE 查询该属性时，或用Lua mp.get_property_native ，这将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each track)
        "id"                    MPV_FORMAT_INT64
        "type"                  MPV_FORMAT_STRING
        "src-id"                MPV_FORMAT_INT64
        "title"                 MPV_FORMAT_STRING
        "lang"                  MPV_FORMAT_STRING
        "image"                 MPV_FORMAT_FLAG
        "albumart"              MPV_FORMAT_FLAG
        "default"               MPV_FORMAT_FLAG
        "forced"                MPV_FORMAT_FLAG
        "selected"              MPV_FORMAT_FLAG
        "main-selection"        MPV_FORMAT_INT64
        "external"              MPV_FORMAT_FLAG
        "external-filename"     MPV_FORMAT_STRING
        "codec"                 MPV_FORMAT_STRING
        "codec-desc"            MPV_FORMAT_STRING
        "codec-profile"         MPV_FORMAT_STRING
        "ff-index"              MPV_FORMAT_INT64
        "decoder-desc"          MPV_FORMAT_STRING
        "demux-w"               MPV_FORMAT_INT64
        "demux-h"               MPV_FORMAT_INT64
        "demux-crop-x"          MPV_FORMAT_INT64
        "demux-crop-y"          MPV_FORMAT_INT64
        "demux-crop-w"          MPV_FORMAT_INT64
        "demux-crop-h"          MPV_FORMAT_INT64
        "demux-channel-count"   MPV_FORMAT_INT64
        "demux-channels"        MPV_FORMAT_STRING
        "demux-samplerate"      MPV_FORMAT_INT64
        "demux-fps"             MPV_FORMAT_DOUBLE
        "demux-bitrate"         MPV_FORMAT_INT64
        "demux-rotation"        MPV_FORMAT_INT64
        "demux-par"             MPV_FORMAT_DOUBLE
        "audio-channels"        MPV_FORMAT_INT64
        "replaygain-track-peak" MPV_FORMAT_DOUBLE
        "replaygain-track-gain" MPV_FORMAT_DOUBLE
        "replaygain-album-peak" MPV_FORMAT_DOUBLE
        "replaygain-album-gain" MPV_FORMAT_DOUBLE
        "dolby-vision-profile"  MPV_FORMAT_INT64
        "dolby-vision-level"    MPV_FORMAT_INT64

current-tracks/...

这可以访问当前选择的轨道。它重定向到 track-list 中的正确条目。

定义了以下子条目： video, audio, sub, sub2

例如， current-tracks/audio/lang 返回当前音轨的语言字段（与 track-list/N/lang 的值相同）。

如果通过 --lavfi-complex 选择了所要求的类型的轨道，将返回第一个。

chapter-list (RW)

章节列表，当前条目被标记。目前，原始属性值是无用的。

这有一系列子属性。用基于0代替 N 的章节索引。

chapter-list/count

章节的数量

chapter-list/N/title

存储在文件中的章节标题。并非总是可用

chapter-list/N/time

章节的开始时间，单位是浮点数的秒

当用client API的 MPV_FORMAT_NODE 查询该属性，或用Lua mp.get_property_native ，将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each chapter)
        "title" MPV_FORMAT_STRING
        "time"  MPV_FORMAT_DOUBLE

af, vf (RW)

参见 --vf / --af 和 vf / af 命令。

当用client API的 MPV_FORMAT_NODE 查询该属性，或用Lua mp.get_property_native ，将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each filter entry)
        "name"      MPV_FORMAT_STRING
        "label"     MPV_FORMAT_STRING [optional]
        "enabled"   MPV_FORMAT_FLAG [optional]
        "params"    MPV_FORMAT_NODE_MAP [optional]
            "key"   MPV_FORMAT_STRING
            "value" MPV_FORMAT_STRING

也可以用这种格式来写入属性。

seekable

通常是否可以在当前文件中跳转。

partially-seekable

当前文件是否被认为是跳转的，但只因为缓存是激活的。这意味着小的相对跳转可能是可行的，但较大的跳转可能会失败。跳转是否会成功，通常是不能预先知道的。

如果这个属性返回 yes /true，那么 seekable 也会返回。

playback-abort

播放是否已经停止或将要停止（在不明显的情况下很有用，比如在 on_load hook处理过程中，用户可以停止播放，但脚本必须明确结束处理）。

cursor-autohide (RW)

参见 --cursor-autohide 。将此设置为一个新的值将总是更新光标，并重置内部的计时器。

osd-sym-cc

将当前的OSD符号作为不透明的OSD控制代码（cc）插入。这只对 show-text 命令或设置OSD信息的选项有意义。控制代码是具体实施的，对其他事情没有用处。

osd-ass-cc

${osd-ass-cc/0} 在OSD中禁止转义ASS序列的文本， ${osd-ass-cc/1} 再次启用。默认情况下，ASS序列被转义以避免意外的格式化，该属性可以禁用这一行为。注意，这些属性会返回一个不透明的OSD控制代码，这只对 show-text 命令或设置OSD信息的选项有意义。

示例

• --osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'

• show-text "This is ${osd-ass-cc/0}{\\b1}bold text"

任何由libass理解的ASS覆写标签都可以使用。

注意，你需要转义 \ 字符，因为字符串在传递给OSD代码之前会被处理为C转义序列。详见 Flat命令语法

标签的列表可以在这里找到： https://aegisub.org/docs/latest/ass_tags/

vo-configured

当前视频输出驱动是否被配置了。通常这与视频窗口是否可见相对应。如果使用了 --force-window 选项，通常总是返回``yes`` /true。

vo-passes

包含对视频输出的活动渲染传递及其执行时间的内省。并非所有的视频输出驱动都能实现。

这被进一步细分为两种帧类型， vo-passes/fresh 用于刷新的帧（必须已被上传、缩放等）， vo-passes/redraw 用于重新绘制的帧（只需要已被重绘）。任何指定的子类型的传递次数可以从一帧到另一帧发生变化，因此不应依赖以上。

每个帧类型都有一系列进一步的子属性。用帧类型代替 TYPE ， N 代替基于0的传递索引， M 代替基于0的采样索引。

vo-passes/TYPE/count

传递的数量

vo-passes/TYPE/N/desc

传递的人性化描述

vo-passes/TYPE/N/last

最近的测量的执行时间，以纳秒为单位

vo-passes/TYPE/N/avg

该传递的平均执行时间，以纳秒为单位。确切的时间范围是可变的，但一般应该是几秒钟

vo-passes/TYPE/N/peak

该平均范围内的峰值执行时间（最高值），以纳秒为单位

vo-passes/TYPE/N/count

该通道的采样

vo-passes/TYPE/N/samples/M

该通道的特定采样的原始执行时间，以纳秒为单位

当用client API的 MPV_FORMAT_NODE 查询该属性时，或用Lua mp.get_property_native ，将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_MAP
"TYPE" MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP
        "desc"    MPV_FORMAT_STRING
        "last"    MPV_FORMAT_INT64
        "avg"     MPV_FORMAT_INT64
        "peak"    MPV_FORMAT_INT64
        "count"   MPV_FORMAT_INT64
        "samples" MPV_FORMAT_NODE_ARRAY
             MP_FORMAT_INT64

注意，不支持通过subkeys直接访问这个结构，唯一的访问方式是通过前面提到的 MPV_FORMAT_NODE

perf-info

进一步的性能数据。查询这个属性会触发一些数据的内部收集，可能会拖慢播放器。每次查询都会重置一些内部状态。属性变化通知没有也不会起作用。所有这些都可能在未来改变，所以不要使用这个。内置的 stats 脚本应该是唯一的用户；因为它是和源代码捆绑在一起的，它可以使用mpv内部的知识来正确渲染信息。一些细节参见 stats 脚本描述。

video-bitrate, audio-bitrate, sub-bitrate

在数据包层面上计算的比特率值。它的工作原理是将两个关键帧之间的所有数据包的比特大小除以它们的演示时间戳距离（这使用时间戳存储在文件中，所以例如播放速度不会影响返回值）。特别是，视频比特率将只在每个关键帧更新，并显示 “past” 的比特率。为了使该属性对用户界面更友好，对这些属性的更新会以某种方式进行节制。

单位是比特/秒。OSD格式将这些值变成千比特（或兆比特，如果合适的话），这可以通过使用原始属性值来防止，例如，用 ${=video-bitrate}

请注意，这些属性的准确性受到一些因素的影响。如果底层的解复用器在解复用时重写了数据包（对某些文件格式做了重写），比特率可能略有偏差。如果时间戳不好或抖动（如在Matroska中），即使是恒定的比特率流也可能显示波动的比特率。

这些值到底是如何计算的，将来可能会改变。

在mpv的早期版本中，这些属性使用一个完全不同的方法返回一个静态（但不好）的猜测。

packet-video-bitrate, packet-audio-bitrate, packet-sub-bitrate

video-bitrate, audio-bitrate, sub-bitrate 的旧版的过时的属性。它们的表现完全相同，但返回的是以千比特为单位的值。另外，它们没有任何OSD格式，尽管同样可以用例如 ${=video-bitrate} 来实现。

这些属性不应该再被使用。

audio-device-list

已发现的音频设备的列表。这主要用于client API，并反映了命令行播放器 --audio-device=help 返回的内容。

当用client API的 MPV_FORMAT_NODE 查询属性时，或用Lua mp.get_property_native ，将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each device entry)
        "name"          MPV_FORMAT_STRING
        "description"   MPV_FORMAT_STRING

name 是要传递给 --audio-device 选项的东西（通常是一个相当神秘的音频API特定ID），而 description 是人性化的可读的自由格式文本。如果没有描述，或者描述本来就是一个空字符串，那么描述将被设置为设备名称（减去mpv特有的 <driver>/ 前缀）。

名称设置为 auto 的特殊条目选择默认的音频输出驱动和默认设备。

该属性可以通过client API和Lua脚本中的属性观察机制进行查看（从技术上讲，在第一次读取这个属性时就会启用变化通知）。

audio-device (RW)

设置音频设备。这直接读取/写入 --audio-device 选项，但在写入访问时，音频输出将被安排重新加载。

在没有音频输出的情况下写入这个属性，不会自动启用音频（在先前写入访问 audio-device 后，由于重新初始化失败而禁用音频的情况下也是如此）。

这个属性也不会告诉你哪个音频设备在被实际使用中。

这些细节的处理方式在未来可能会改变。

current-vo

当前的视频输出驱动（与 --vo 一起使用的名称）。

current-gpu-context

VO的当前 GPU 上下文（与 --gpu-context 一起使用的名称）。对 --vo=gpu 和 ``–vo=gpu-next` 有效。

current-ao

当前的音频输出驱动（与 --ao 一起使用的名称）。

user-data (RW)

这是一个在客户端之间共享的任意节点的递归按键/值图表，以供一般使用（即脚本、IPC客户端、主机应用程序等）。播放器自身不使用其中的任何数据（尽管一些内置脚本可能使用）。该属性在播放器重新启动后不会被保留。

子路径可以被直接访问；例如， user-data/my-script/state/a 可被读取、写入或观测。

top-level 对象本身不能被直接写入；而是写入到子路径。

将此属性或其子属性转换为字符串，这将得到一个JSON的呈现。如果转换一个 leaf-level 对象（即不是图表或数组）并且不使用 raw 模式，将给出底层内容（例如，字符串将被直接输出，而没有引号或JSON转义）。

menu-data (RW)

此属性存储原始菜单定义。详情请参阅 上下文菜单 部分。

type

菜单项类型。可以是 separator , submenu 或空。

title

菜单项标题。如果类型不是 separator 则必须填写。

cmd

点击菜单项时要执行的命令。

shortcut

菜单项右侧显示的菜单项快捷键。 快捷键不一定要有功能，它只是一个视觉提示。

state

菜单项的状态。可以是 checked , disabled, hidden 或空。

submenu

子菜单项，类型为 submenu 时必须填写。

使用client API MPV_FORMAT_NODE 或 Lua mp.get_property_native 查询属性时，将返回一个 mpv_node，内容如下：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (menu item)
        "type"           MPV_FORMAT_STRING
        "title"          MPV_FORMAT_STRING
        "cmd"            MPV_FORMAT_STRING
        "shortcut"       MPV_FORMAT_STRING
        "state"          MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]
        "submenu"        MPV_FORMAT_NODE_ARRAY[menu item]

如果 mpv 视频输出当前处于活动状态，则使用client API MPV_FORMAT_NODE 或 Lua mp.set_property_native 写入此属性将触发菜单的立即更新。您可以通过观察 current-vo 属性来检查情况。

working-directory

mpv进程的工作目录。对JSON IPC用户可能有用，因为命令行播放器通常使用相对路径。

protocol-list

可能被播放器识别的协议前缀列表。它们被返回，没有尾部的 :// 后缀（但仍然总是需要）。在某些情况下，协议实际上是不被支持的（如果ffmpeg在编译时不支持TLS，可以考虑 https ）。

decoder-list

支持的解码器的列表。这列出了可以传递给 --vd 和 --ad 的解码器。

codec

典型的编解码器名称，用于识别解码器可以处理的格式

driver

解码器本身的名称。通常，这与 codec 相同。有时它可能不同。它用于区分同一编解码器的多个解码器

description

解码器和编解码器的人性化的可读描述

当用client API的 MPV_FORMAT_NODE 查询该属性，或用Lua mp.get_property_native ，将返回一个mpv_node，内容如下：

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each decoder entry)
        "codec"         MPV_FORMAT_STRING
        "driver"        MPV_FORMAT_STRING
        "description"   MPV_FORMAT_STRING

encoder-list

libavcodec编码器的列表。这与 decoder-list 的格式相同。编码器名称（ driver 条目）可以传递给 --ovc 和 --oac （没有 --vd 和 --ad 要求的 lavc: 前缀）。

demuxer-lavf-list

可用的libavformat解复用器名称的列表。这可以用来检查对特定格式的支持或与 --demuxer-lavf-format 一起使用。

input-key-list

按键名称 列表，与 --input-keylist 的输出相同。

mpv-version

mpv版本/版权字符串。根据二进制文件的构建方式，它可能包含一个发布版本号，或者只是一个git哈希值。

mpv-configuration

传递给构建系统的配置参数。如果用于编译mpv的meson版本低于1.1.0，那么就会显示一条由多个任意选项组成的硬编码字符串。

ffmpeg-version

av_version_info() API调用的内容。这是一个以某种方式标识构建的字符串，可以是发布版本号，也可以是git哈希值。如果mpv与较早的FFmpeg版本链接，这个属性就不可用。

libass-version

ass_library_version() 的值。这是一个整数，以有点奇怪的形式编码（显然是 “hex BCD”），表示链接到mpv的libass库的发布版本。

platform

返回一个描述mpv的目标构建平台的字符串。该值取决于底层构建系统检测到的内容。一些最常见的值是： windows , darwin （macos或ios）, linux , android 和 freebsd 。请注意，这不是一个完整的列表。

options/<name> (RW)

选项 --<name> 的值。大多数选项可以在运行时通过写到这个属性来改变。请注意，许多选项需要重新加载文件以使更改生效。如果有同等的属性，最好设置该属性。

应该没有任何理由访问 options/<name> 而不是 <name> ，除非这些属性有不同的行为或冲突的语义。

file-local-options/<name> (RW)

类似于 options/<name> ，但是当通过该属性设置一个选项时，一旦当前文件停止播放，该选项将被重置为旧值。当没有文件正在播放（或正在加载）时，尝试写入一个选项会导致错误。

（注意，如果一个选项被标记为file-local，即使是 options/ 也会访问本地值，而 old 值将在播放结束时被恢复，在播放结束前不能被读取或写入）

option-info/<name>

每个选项的额外信息。

这有一系列子属性。用顶层选项的名称替换 <name> 。不保证这些子属性的稳定性 —— 它们可能在功能中发生根本性变化。

option-info/<name>/name

选项的名称

option-info/<name>/type

选项类型的名称，如 String 或 Integer 。对于许多复杂的类型，这并不是很准确

option-info/<name>/set-from-commandline

该选项是否从mpv命令行设置。如果选项在运行时被改变，这个选项将被设置为undefined（意味着它可能在将来改变）

option-info/<name>/set-locally

该选项是否按单文件设置。自动加载的设置文件、文件-目录的设置和其他情况都是如此。这意味着当播放结束时，选项的值将被恢复到播放开始前的值

option-info/<name>/expects-file

选项是否将文件路径作为参数

option-info/<name>/default-value

该选项的默认值。可能并非总是可用

option-info/<name>/min, option-info/<name>/max

选项允许的最小和最大整数值。只有在选项是数字的情况下才可用，并且最小/最大值已在内部设置。也有可能只设置了其中一个

option-info/<name>/choices

如果该选项是一个可选择的选项，可能可选。整数的选择可能包括也可能不包括（它们可以由 min 和 max 暗示）。请注意，那些表现得像选项的选项，但内部不是实际的选项，可能没有这个信息

property-list

顶层属性的列表

profile-list

配置预设和其内容的列表。这是高度特定于此的实现，并可能随时改变。目前，它为每个配置预设返回一个选项数组。每个选项有一个名称和一个值，目前值总是一个字符串。请注意，选项数组不是一个表，因为顺序很重要，有可能出现重复的条目。递归的配置预设不被展开，并显示为特殊的 profile 选项。

如果 profile restore 字段包含默认值（可能是因为它没有设置，或者显式设置为 default ），则当前缺少该字段，但将来可能会包含值 default 。

command-list

输入命令的列表。这将返回一个数组表，其中每个表节点代表一个命令。这个表目前只有一个条目。 name 代表命令的名称（这个属性应该是对 --input-cmdlist 的替代。该选项转储了一些更多的信息，但如果需要的话，扩展这个属性是一个有效的功能请求）。

input-bindings

当前输入按键键绑定的列表。这将返回一个数组，其中每个表节点代表一个单一的按键键/命令的绑定。这个表有以下条目：

key

按键的名称。这是标准化的，可能与源文件中的指定方式略有不同（例如，在input.conf中）

cmd

映射到按键上的命令（目前，这与源文件中指定的字符串完全相同，只是删除了空格和注释。将来有可能被规范化）

is_weak

如果设置为 yes，任何现有的和激活的用户绑定将被优先考虑

owner

如果此条目存在，则是添加此绑定的脚本（或类似）的名称

section

该绑定属于某个部分的名称。这是一个很少使用的机制。这个条目可能会被删除或在将来改变含义

priority

一个数字。数值高的绑定比数值低的绑定优先。如果该值为负数，这个绑定是未激活的，不会被输入触发。注意，mpv内部不使用这个值，在某些情况下，绑定的匹配工作可能略有不同。此外，这个值是动态的，可以在运行时改变。

comment

如果存在的话，在同一行的命令后面的注释（例如，input.conf条目 f cycle bla # toggle bla 会产生一个条目 comment = "toggle bla", cmd = "cycle bla" ）

这个属性是只读的，不支持更改提醒。目前，除了脚本添加或删除自己的绑定外，没有任何机制可以在运行时改变按键绑定。

选项和属性之间的不一致处

你可以把（几乎）所有的选项作为属性来访问，尽管有些属性有一些注意事项（由于历史原因）。

vid, aid, sid

当播放处于激活状态时，这些属性返回实际激活的轨道。例如，如果你设置了 aid=5 ，而当前播放的文件不包含ID为5的音轨， aid 属性将返回 no

在mpv0.31.0之前，你只能在运行时设置存在的音轨。

display-fps

这种不一致的行为已过时。弃用后，报告值和选项值被干净地分离开（选项值为 overrid-display-fps ）。

vf, af

如果你在播放过程中设置了这些属性，而滤镜链未能成功重新初始化，选项将被设置，但运行时的滤镜链不会改变。另一方面，下一个要播放的视频会失败，因为初始的滤镜链不能被创建。

这种行为在mpv0.31.0中有所改变。在此之前， 如果 一个视频（对于 vf ）或一个音频（对于 af ）轨道是激活的，新的值被拒绝。如果播放没有激活，行为与当前相同。

playlist

该属性是只读的，返回当前的内部播放列表。该选项是为了在命令行解析时加载播放列表。对于client API的用户，你应该使用 loadlist 命令代替。

profile, include

这些都是只写入的，并将执行被写入的动作，就像在mpv CLI命令行上使用一样。它们唯一的用途是在 mpv_initialize() 之前使用libmpv，而这可能只在转码模式下有用。普通的libmpv用户应该使用其它机制，比如 apply-profile 命令，以及 mpv_load_config_file API函数。避免使用这些属性。

属性扩展

所有输入命令的字符串参数以及某些选项（如 --term-playing-msg ）都要符合属性扩展。需要注意的是，属性扩展在一些地方不起作用，例如，数字参数是预期的（例如， add 命令不做属性扩展。 set 命令是一个例外，而非一般规则）。

input.conf示例

i show-text "Filename: ${filename}"

当按下 i 键时显示当前文件的文件名。

属性扩展是否默认启用取决于使用的哪种API（参见 Flat命令语法 指定为数组的命令 命名参数 ），但它总是可以用 expand-properties 前缀启用，或用 raw 前缀禁用，如 输入命令前缀 所述。

支持以下扩展：

${NAME}

展开到属性 NAME 的值。如果检索该属性失败，则扩展为错误字符串。（使用 ${NAME:} 带尾巴的 : 来扩展到一个空字符串）。如果 NAME 前缀为 = ，则展开为该属性的原始值（见下文）

${NAME:STR}

展开到属性 NAME 的值，如果不能检索到该属性，则展开到 STR 。 STR 是递归展开的

${?NAME:STR}

如果有 NAME 属性，则扩展到 STR （递归）

${!NAME:STR}

如果不能检索到 NAME 属性，则扩展为 STR （递归）

${?NAME==VALUE:STR}

如果属性 NAME 扩展为等于 VALUE 的字符串，则扩展为 STR （递归）。你可以在 NAME 前加上 = ，以便比较一个属性的原始值（见下文）。如果该属性不可用，或者在检索时发生其他错误，该值永远不会被视为相等。注意， VALUE 不能包含任何 : 或 } 字符。另外，如果有需要，将来可能会增加用 " 或 % 转义的功能

${!NAME==VALUE:STR}

与 ? 变体相同，但是如果值不相等， STR 将被展开（使用与 ? 相同的语义）

$$

展开为 $

$}

展开为 } （要在递归扩展中产生这个字符）

$>

禁用属性扩展和对字符串其余部分的 $ 的特殊处理

在允许属性扩展的地方，通常也接受C-style转义。例如：

• \n 成为一个换行符

• \\ 扩展为 \

原始和格式化的属性

通常情况下，属性被格式化为人性化的可读文本，旨在显示在OSD或终端上。通过在属性名称前加上 = ，可以从一个属性中获取未格式化的（原始）值。这些原始值可以被其他程序解析，并遵循与属性相关的选项相同的惯例。此外，还有一个 > 前缀，用于格式化人类可读的文本，浮点数值采用固定精度。这对于输出需要恒定宽度的数值非常有用。

示例

• ${time-pos} 扩展为 00:14:23 （如果播放位置在14分23秒）

• ${=time-pos}``扩展为 ``863.4 （同样的时间，加上400毫秒 —— 在格式化的情况下通常不显示毫秒）

• ${avsync} 扩展为 +0.003

• ${>avsync} 扩展为 +0.0030

• ${=avsync} 扩展为 0.003028

有时，原始属性值和格式化的属性值所携带的信息量的差异可能相当大。在某些情况下，原始值有更多的信息，比如比秒更精确的 time-pos 。有时情况正好相反，例如 aid 在格式化的情况下显示音轨标题和语言，但如果是原始值，则只显示音轨号码。

屏显式控制器

屏显式控制器（简称：OSC）是一个与mpv集成的最小GUI，提供基本的鼠标操控功能。它的目的是使新用户的交互更容易，并且能够精确和直接的进行进度查询。

如果mpv在编译时支持Lua，那么OSC是默认启用的。它可以通过选项 --osc=no 完全禁用。

使用OSC

默认情况下，只要光标在播放器窗口内移动，OSC就会显示；如果光标在OSC外超过0.5秒没有移动，或者光标离开窗口，OSC就会隐藏。

界面

+-----------+-------------+-------------------------------+-----------+
| 上一文件  |  下一文件   |  标题                         |  缓存指示 |
+----+------+------+------+--------------+------+----+----+------+----+
| 播 | 上一 | 下一 | 已过 |   进度条     | 剩余 | 音 | 字 | 音量 | 全 |
| 放 | 章节 | 章节 | 时间 |              | 时间 | 轨 | 幕 |      | 屏 |
+----+------+------+------+--------------+------+----+----+------+----+

上一文件

左键单机	播放列表中的上一个文件
右键单机	显示播放列表
shift左键单机	显示播放列表

下一文件

左键单机	播放列表中的下一个文件
右键单机	显示播放列表
shift左键单机	显示播放列表

标题

悬停在进度条时，显示当前的媒体标题、文件名、自定义标题或目标章节名称

左键单机	显示播放列表中的位置、长度和完整标题
右键单机	显示文件名

缓存指示

显示当前的缓冲状态

播放

左键单机

切换 播放/暂停

上一章节

左键单机	跳转章节开头/上一章节
右键单机	显示章节列表
shift左键单机	显示章节列表

下一章节

左键单机	跳转下一章节
右键单机	显示章节列表
shift左键单机	显示章节列表

已过时间

显示当前播放位置的时间戳

左键单机	切换 显示带毫秒的时间码

进度条

显示当前的播放位置和章节的位置

左键单机	跳转位置
鼠标滚轮	前进/后退

剩余时间

显示剩余播放时间的时间戳

左键单机	切换 总时间/剩余时间

音轨 字幕

显示所选轨道的可用数量

左键单机	循环 音频/字幕轨 前进
右键单机	循环 音频/字幕轨 后退
shift左键单机	显示可用的音频/字幕轨列表
鼠标滚轮	循环 音频/字幕轨 前进/后退

音量

左键单机	切换 静音
滚轮滚动	音量增大/减小

全屏

左键单机

切换 全屏

按键绑定

如果没有其他命令已经绑定在这些键上，这些键的绑定默认是激活的。在发生冲突的情况下，需要将该功能绑定到不同的按键上。参见 脚本命令 部分。

del	循环 OSC可见性 始终隐藏/自动显示/始终显示

设置

可以通过 mpv 用户目录下的设置文件 script-opts/osc.conf 和命令行选项 --script-opts 来定制该脚本。设置语法记录在 `mp.options functions`_ 部分。

命令行语法

为了避免与其他脚本发生冲突，所有选项都需要以 osc- 为前缀。

示例:

--script-opts=osc-optionA=value1,osc-optionB=value2

设置选项

layout

默认： bottombar

OSC的布局。目前可用的有：box, slimbox, bottombar 和 topbar。0.21.0之前的默认值是 box

seekbarstyle

默认： bar

设置播放位置标记的样式和进度条的整体形状： bar, diamond 或 knob

seekbarhandlesize

默认： 0.6

如果 seekbarstyle 被设置为 diamond 或 knob ，播放位置标记的大小比例。这是相对于进度条的全部高度而言的。

seekbarkeyframes

默认： yes

控制拖动进度条时使用的搜索模式。如果设置为 yes ，则使用默认的搜索模式（通常是关键帧，但播放器的默认和启发式方法可以将其改为精确）。如果设置为 no ，将使用鼠标拖动的精确搜索方式。关键帧是首选，但在找不到关键帧的情况下，精确搜索可能是有用的。请注意，使用精确搜索有可能使鼠标拖动的速度更慢。

seekrangestyle

默认： inverted

在进度条上显示可搜索的范围。 bar 显示它们在进度条的全部高度上， line 是一条粗线， inverted 是一条细线，在播放位置标记上反色。 none 将隐藏。此外， slider 将在进度条内显示永久的线条，里面标有缓存范围。请注意，这些会根据seekbarstyle选项的不同而有所差异。另外， slider 在 seekbarstyle 设置为 bar 时无效。

seekrangeseparate

默认： yes

控制如果 seekbarstyle 设置为 bar ，是否在进度条的顶部显示线型可寻范围，或者单独显示。

seekrangealpha

默认： 200

可搜寻范围的透明度，0（不透明）到255（完全透明）

scrollcontrols

默认： yes

默认情况下，如果鼠标悬停在 OSC 元素上，使用鼠标滚轮上下滚动会触发某些操作（例如seek）。设置为 no 可禁用任何特殊的鼠标滚轮行为。

deadzonesize

默认： 0.5

死区的大小。死区是一个区域，使鼠标像离开窗口一样。在那里移动不会使OSC显示出来，如果鼠标进入该区域，它将立即隐藏。死区从与OSC相对的窗口边界开始，其大小控制它在窗口中的跨度。值在0.0和1.0之间，其中0意味着OSC将总是随着鼠标在窗口中的移动而弹出，1意味着OSC只在鼠标悬停时显示。0.21.0之前的默认值是0。

minmousemove

默认： 0

鼠标在刻度之间移动的最小像素量，使OSC显示出来。0.21.0之前的默认值是3。

showwindowed

默认： yes

在窗口状态下启用OSC

showfullscreen

默认： yes

全屏时启用OSC

idlescreen

默认： yes

空闲状态下显示mpv的logo和文字

scalewindowed

默认： 1.0

窗口化时OSC的比例系数

scalefullscreen

默认： 1.0

全屏时OSC的比例系数

vidscale

默认： yes

随视频的比例缩放OSC。 no 试图在窗口大小允许的范围内保持OSC大小不变。

valign

默认： 0.8

垂直对齐，-1（顶部）到1（底部）

halign

默认： 0.0

水平对齐，-1（左侧）到1（右侧）

barmargin

默认： 0

底部（bottomombar）或顶部（topbar）的边距，单位是像素

boxalpha

默认： 80

背景的透明度，0（不透明）到255（完全透明）

hidetimeout

默认： 500

在没有鼠标移动的情况下，OSC隐藏的时间，以ms为单位，不能是负数

fadeduration

默认： 200

淡出的持续时间，以ms为单位，0=不淡出

title

默认： ${media-title}

支持属性扩展的字符串，将被显示为OSC标题。ASS标签被转义，换行被转换为空格。

tooltipborder

默认： 1

使用bottombar或topbar布局时，搜寻时间码的大小

timetotal

默认： no

显示总时间而不是剩余时间

remaining_playtime

默认： yes

时间剩余显示是否考虑播放速度。 yes - 考虑当前速度下还剩多少播放时间。 no - 考虑视频时长下还剩多少时间。

timems

默认： no

显示带毫秒的时间码

tcspace

默认： 100 （允许的范围： 50-200 ）

调整 bottombar 和 topbar 布局中为时间码（当前时间和剩余时间）保留的空间。时间码的宽度取决于字体，对于某些字体，时间码附近的间距变得太小。使用高于100的值来增加间距，或低于100的值来减少间距。

visibility

默认： auto （鼠标移动时自动隐藏/显示）

也支持 never 和 always

boxmaxchars

默认： 80

mpv不能测量屏幕上的文本宽度，所以需要用字符数来限制。默认值是保守的，允许使用等宽字体而不溢出。然而，对于许多常见的字体，可以使用一个更大的数字。请自行斟酌。

boxvideo

默认： no

是否在视频上覆盖osc（ no ），或在osc未覆盖的区域内框住视频（ yes ）。如果设置了这个选项，osc可能会覆盖 --video-margin-ratio-* 选项，即使用户已经设置了它们（如果所有选项都被设置为默认值，则不会覆盖它们）。此外， visibility 必须被设置为 always 。否则，这个选项没有任何效果。

目前，只支持 bottombar 和 topbar 的布局。如果设置了这个选项，其他的布局就不会改变。另外，如果存在窗口控件（见下文），无论使用哪种OSC布局，它们都会受到影响。

边框是静态的，即使OSC被设置为只在鼠标交互时出现，边框也会出现。如果OSC是不可见的，边框就会简单地用背景色（默认为黑色）填充。

目前这仍然会使OSC与字幕重叠（如果 --sub-use-margins 选项被设置为 yes ，默认）。这可能会在以后修复。

这在个别视频输出驱动中不能正常工作，如 --vo=xv ，它将OSD渲染进未缩放的视频中。

windowcontrols

默认： auto （如果没有窗口边框就显示窗口控件）

是否在视频上显示窗口管理控件，如果明确，则放在窗口的一边。当窗口没有装饰时，这可能是可取的，因为它们被明确地禁用（ border=no ）或者因为当前平台不支持它们（例如：gnome-shell与wayland）。

窗口控件是固定的，提供 minimize, maximize 和 quit 。不是所有的平台都实现了 minimize 和 maximize ，但 quit 总是有效的。

windowcontrols_alignment

默认： right

如果窗口控件被显示出来，显示它们应该向一边对齐。

left 和 right 支持将把控件放在左侧和右侧。

windowcontrols_title

默认： ${media-title}

支持属性扩展的字符串，将显示为窗口控件的标题。ASS 标签会被转义，换行符和尾部斜杠会被剥离。

greenandgrumpy

默认： no

设置为 yes 以减少节日气氛（例如，在12月禁用圣诞帽）

livemarkers

默认： yes

在持续时间变化时更新章节标记的位置，例如，直播流。状态更新尚未优化 —— 考虑在非常低端的系统上禁用它。

chapters_osd , playlist_osd

默认： yes

当左键单机OSC的下一个/上一个按钮时，是否分别在OSD上显示章节/播放列表。

playlist_media_title

默认： yes

是否以媒体标题显示为播放列表的条目。如果设置为 no ，则使用文件名。请注意，文件的媒体标题只有在加载后才可用。

chapter_fmt

默认： Chapter: %s

当悬停在进度条上时，显示章节名称的模板。使用 no 来禁止悬停时的章节显示。否则，它是一个lua string.format 模板， %s 被替换成实际的名字。

unicodeminus

默认： no

在显示剩余播放时间时，使用Unicode减号而不是ASCII连字符。

background_color

默认： #000000

Sets the background color of the OSC.

timecode_color

默认： #FFFFFF

Sets the color of the timecode and seekbar, of the OSC.

title_color

默认： #FFFFFF

Sets the color of the video title. Formatted as #RRGGBB.

time_pos_color

默认： #FFFFFF

Sets the color of the timecode at hover position in the seekbar.

time_pos_outline_color

默认： #FFFFFF

Sets the color of the timecode’s outline at hover position in the seekbar. Also affects the timecode in the slimbox layout.

buttons_color

默认： #FFFFFF

Sets the colors of the big buttons.

top_buttons_color

默认： #FFFFFF

Sets the colors of the top buttons.

small_buttonsL_color

默认： #FFFFFF

Sets the colors of the small buttons on the left in the box layout.

small_buttonsR_color

默认： #FFFFFF

Sets the colors of the small buttons on the right in the box layout.

held_element_color

默认： #999999

Sets the colors of the elements that are being pressed or held down.

脚本命令

OSC脚本会监听某些脚本命令。这些命令可以绑定在 input.conf 中，或者由其他脚本发送。

osc-message

使用OSC在屏幕上显示一条信息。第一个参数是信息，第二个参数是持续时间（秒）。

osc-visibility

控制可见性模式 never / auto （在鼠标移动时）/ always 和 cycle 在各种模式之间循环。

示例

你可以把这个放到 input.conf 中，用 a 键隐藏OSC，用 b 键设置自动模式（默认）:

a script-message osc-visibility never
b script-message osc-visibility auto

osc-idlescreen

控制空闲状态时mpv的logo可见性。有效的参数是 yes no ，也可用 cycle 来切换。

osc-playlist osc-chapterlist osc-tracklist

使用OSC显示各自类型的列表的有限视图。第一个参数是持续时间，单位是秒。

统计数据

该内置脚本显示当前播放文件的信息和统计数据。如果mpv在编译时支持Lua，它就会默认启用。可以通过 --load-stats-overlay=no 选项完全禁用它。

使用

下面的按键绑定默认是激活的，除非有其他功能已经被绑定：

i	只在一个固定的时间段内显示统计数据
I	切换 显示/隐藏统计数据（再次切换前始终显示）

当统计数据在屏幕上可见时，以下的按键绑定是激活的，无视之前已有的绑定。它们允许你在 不同页面 的统计数据之间切换：

1	显示通用信息
2	显示帧计时（可滚动）
3	输入缓存统计
4	激活的按键绑定（可滚动）
0	内部活动（可滚动）

在支持滚动的页面上，这些按键的绑定也是激活的：

UP	向上滚动一行
DOWN	向下滚动一行

第 4 页还绑定了 / 以通过键入绑定或命令的一部分来搜索输入绑定。

设置

该脚本可以通过放置在mpv用户目录下的设置文件 script-opts/stats.conf 和 --script-opts 命令行选项来定制。设置语法在 `mp.options functions`_ 中已描述。

设置选项

key_page_1

默认： 1

key_page_2

默认： 2

key_page_3

默认： 3

key_page_4

默认： 4

key_page_0

默认： 0

在显示统计数据时进行页面切换的按键绑定

key_scroll_up

默认： UP

key_scroll_down

默认： DOWN

key_scroll_search

默认： /

scroll_lines

默认： 1

滚动操作的按键绑定和在支持它的页面上单次滚动的行数

duration

默认： 4

统计数据的持续显示时间，以秒为单位（固定时间段显示时）

redraw_delay

默认： 1

统计数据的刷新间隔时间，以秒为单位（始终显示时）

persistent_overlay

默认： no

当 no 时，其它脚本输出到屏幕的文本的可以覆盖已显示的统计数据。当 yes 时，显示的统计数据会在对应的时间段内持续显示。当多个脚本决定同时输出文本时，这可能导致文本重叠。

term_width_limit

默认： -1

设置终端宽度。值为 0 表示宽度无限大， -1 表示自动。

term_height_limit

默认： -1

设置终端高度。值为 0 表示宽度无限大， -1 表示自动。

plot_perfdata

默认： yes

显示性能数据的图表（第2页）

plot_vsync_ratio

默认： yes

plot_vsync_jitter

默认： yes

显示vsync和jitter值的图表（第1页）。只有在始终显示时才显示。

plot_tonemapping_lut

默认： no

自动启用色调映射LUT可视化。仅在切换时启用。

flush_graph_data

默认： yes

在始终显示时清除用于绘制图形的数据缓存

font

默认： 与 --osd-font 一致

字体名称。应支持尽可能多的字重来获得最佳的视觉体验。

font_mono

默认： monospace

用于对齐文本所必需的等宽字体名称。目前，monospaced digits已足够。

font_size

默认： 8

用于渲染文本的字体大小

font_color

默认： 与 --osd-color 一致

文本颜色

border_size

默认： 0.8

围绕字体绘制的边框大小

border_color

默认： 与 --osd-border-color 一致

文本边框的颜色

shadow_x_offset

默认： 0

阴影与文字之间的水平距离。

shadow_y_offset

默认： 0

阴影与文字之间的垂直距离。

shadow_color

默认： 与 --osd-shadow-color 一致

文本阴影3的颜色

alpha

默认： 11

指定 font_color 时文本的透明度，指定 border_color 时文本边框的透明度，指定 shadow_color 时文本阴影的透明度。

plot_bg_border_color

默认： 0000FF

用于绘制图形的边框颜色

plot_bg_border_width

默认： 0.5

用于绘制图形的边框宽度

plot_bg_color

默认： 262626

用于绘制图形的背景颜色

plot_color

默认： FFFFFF

用于绘制图形的颜色

vidscale

默认： yes

根据视频缩放文本和图表。 no 试图保持大小不变。

注意：颜色为十六进制值，并使用ASS标签的顺序。BBGGRR（蓝绿红）。

不同的按键绑定

可以在 input.conf 中设置额外的按键来显示统计数据:

e script-binding stats/display-stats
E script-binding stats/display-stats-toggle

以及直接显示某个页面:

i script-binding stats/display-page-1
e script-binding stats/display-page-2

激活的按键绑定的页面

列出激活的按键绑定和它们所绑定的命令，不包括统计数据脚本本身的交互键。也参见 --input-test 以获得每个绑定的更详细信息。

这些按键是通过对命令字符串的简单分析而自动分组的，不应该期望文件级别的分组精度，然而，它仍然应该是相当有用的。

使用 --idle --script-opts=stats-bindlist=yes 会将列表输出到终端并立即退出。默认情况下，长行会被缩短到79个字符，并且终端转义序列被启用。通过将 yes 改为数字（至少40）可以设置不同的长度限制，通过在数值前添加 - 可以禁用转义序列，例如 ...=-yes 或 ...=-120

和 --input-test 一样，列表中包括来自 input.conf 和用户脚本的绑定。使用 --no-config 只列出内建的绑定。

内部活动的页面

该页显示的大多数条目都有相当模糊的含义。可能这些东西对你无用。不要试图使用它。忘记它的存在。

首次选择这个页面将开始收集一些内部性能数据。这意味着在播放器运行的其余时间里，性能会比正常情况下略低（即使统计数据页面被关闭）。注意，统计数据页面本身会使用大量的CPU甚至GPU资源，可能会对性能产生严重影响。

显示的信息在redraw delay时积累（显示为 poll-time 字段）

它为每个Lua脚本增加了条目。如果有太多的脚本在运行，列表中的部分内容会简单地排列超出屏幕，但可以滚动浏览。

如果底层平台不支持pthread per thread times，显示的时间将是0或随机的（我怀疑在写本文时，只有Linux通过pthread APIs提供了正确的per thread times）。

大多数条目都是懒散的添加的，而且只在数据收集期间增加，这就是为什么一些条目可能会在一段时间后随机出现。这也是为什么自数据收集开始后，一直不活动的脚本的内存使用条目会消失。

Memory usage是近似情况，并不反映internal fragmentation 。

JS脚本内存报告默认情况下是禁用的，因为在JS端收集数据会增加开销并增加内存使用。可以通过在启动mpv之前设置 --js-memory-report 选项来启用它。

如果条目有 /time 和 /cpu 变量，前者给出真实时间（monotonic clock），而后者给出thread CPU time（只有当相应的pthread API工作并被支持时）。

控制台

控制台是mpv中可输入命令的交互式解释器。它显示在视频窗口上。它也显示日志信息。它可以通过 --load-osd-console=no 选项完全禁用。

按键绑定

`

显示控制台

ESC, Ctrl+[

隐藏控制台

ENTER, Ctrl+J, Ctrl+M

运行输入的命令

Shift+ENTER

换行输入

LEFT, Ctrl+b

移动光标至前一个字符

RIGHT, Ctrl+f

移动光标至后一个字符

Ctrl+LEFT, Alt+b

移动光标至当前单词的开头，如果在单词之间，则移到前一个单词的开头

Ctrl+RIGHT, Alt+f

移动光标至当前单词的末尾，如果在单词之间，则移到后一个单词的结尾

HOME, Ctrl+a

移动光标至当前行的开头

END, Ctrl+e

移动光标至当前行的结尾

BACKSPACE, Ctrl+h

删除前一个字符

Ctrl+d

如果当前行是空的，隐藏控制台，否则删除后一个字符

Ctrl+BACKSPACE, Ctrl+w

删除从光标到当前单词的开头的文本，如果在单词之间，则删除到前一个单词的开头

Ctrl+DEL, Alt+d

删除从光标到当前单词的结尾的文本，如果在单词之间，则删除到下一个单词的结尾

Ctrl+u

删除从光标到当前行开头的文本

Ctrl+k

删除从光标到当前行结尾的文本

Ctrl+c

删除当前行

UP, Ctrl+p

向前浏览历史命令

DOWN, Ctrl+n

向后浏览历史命令

PGUP

转到历史命令的第一个命令

PGDN

停止浏览历史命令

INSERT

切换 插入/覆盖模式

Ctrl+v

粘贴文本（在X11和Wayland上使用剪贴板）

Shift+INSERT

粘贴文本（在X11和Wayland上使用primary selection）

TAB, Ctrl+i

补全光标处的命令或属性名称。第一次按下时会插入补全内容的最长公共前缀，随后按下时会在它们之间循环。

Shift+TAB

向后循环浏览补全信息

Ctrl+l

清除控制台中的所有日志信息

命令

script-message-to console type <text> [<cursor_pos>]

显示控制台并预填充所提供的文本，可选择指定初始光标位置为从1开始的正整数。

input.conf示例

% script-message-to console type "seek  absolute-percent" 6; keypress ESC” 6``

（打开控制台）输入一个百分比位置，跳转并关闭控制台。

Ctrl+o script-message-to console type "loadfile ''; keypress ESC" 11

输入要播放的文件或 URL。Tab 补全文件系统中的路径。

已知问题

• Windows系统粘贴文本的速度慢

• 非ASCII键盘输入有限制

• 光标键在Unicode code-points之间移动，而不是在grapheme cluster之间移动

设置

这个脚本可以通过放置在mpv用户目录下的设置文件 script-opts/console.conf 和 --script-opts 命令行选项来定制。设置语法在 `mp.options functions`_ 中描述。

按键的绑定可以用标准的方式来改变，例如参见 stats.lua 文档。

设置选项

scale

默认： 1

所有的绘制都按该值缩放，包括文本边框和光标。

如果使用的视频输出驱动后端有HiDPI比例报告的比例，则选项值将采用HiDPI比例。

font

默认： 未设置（根据检测到的平台选择一个硬编码的字体）

设置用于交互式解释器和控制台的字体。必需是等宽字体才能正确对齐代码补全辅助。

font_size

默认： 16

设置用于交互式解释器和控制台的字体大小。这将和scale相乘。

border_size

默认： 1

设置用于交互式解释器和控制台的字体边框大小。

case_sensitive

默认： （windows为 yes ，其它平台为 no ）

Tab 补全是否区分大小写，仅适用于 ASCII 字符。

history_dedup

默认： yes

删除历史记录中的重复条目，只保留最新的一项。

font_hw_ratio

默认： auto

字体高度与字体宽度的比例。调节代码补全辅助的表格宽度。对于一般的等宽字体，1.8-2.5 范围内的值是合理的。

LUA SCRIPTING

https://mpv.io/manual/master/#lua-scripting

JAVASCRIPT

https://mpv.io/manual/master/#javascript

JSON IPC

https://mpv.io/manual/master/#json-ipc

CHANGELOG

https://mpv.io/manual/master/#changelog

EMBEDDING INTO OTHER PROGRAMS (LIBMPV)

https://mpv.io/manual/master/#embedding-into-other-programs-libmpv

环境变量

有许多环境变量可以用来控制mpv的行为。

HOME, XDG_CONFIG_HOME

用来决定mpv的设置目录。如果 XDG_CONFIG_HOME 没有被设置， $HOME/.config/mpv 就会被使用。

$HOME/.mpv 始终被添加到优先级较低的设置搜索路径列表中。

MPV_HOME

mpv寻找用户设置的目录。覆盖 HOME ，mpv将尝试加载的设置文件为 $MPV_HOME/mpv.conf

MPV_VERBOSE （另参见 -v 和 --msg-level ）

设置所有消息模块的初始详细程度（默认： 0）。这是一个整数，产生的详细程度与传递到命令行的 --v 选项的数量相对应。

MPV_LEAK_REPORT

如果设为 1 ，启用内部talloc泄漏报告。如果设为其它值，禁用泄漏报告。如果未设置，使用默认值，通常是 0 。如果mpv是用 --enable-ta-leak-report 构建的，则默认是 1 。如果泄漏报告在编译时被禁用（在 CFLAGS 自定义中的 NDEBUG ），这个环境变量将被忽略。

LADSPA_PATH

指定LADSPA插件的搜索路径。如果它未设置，必须使用完全合规的路径名称。

DISPLAY

要使用的标准X11的显示名称。

FFmpeg:

该库访问各种环境变量。然而，它们没有被集中记录，并且记录它们也不属于我们的工作。因此，这个列表是不完整的。

值得注意的环境变量：

http_proxy

用于代理 http:// 和 https:// 网址的URL

no_proxy

不应该使用代理的域名模式列表。列表条目由 , 分隔。模式可以用 * 包括

libdvdcss:

DVDCSS_CACHE

指定一个目录，用于存储标题键值。这将加快对缓存中的DVD的解析速度。如果 DVDCSS_CACHE 目录不存在，则将被创建，并创建一个以DVD的标题或生产日期来命名的子目录。如果 DVDCSS_CACHE 未设置或为空，libdvdcss将使用默认值，在Unix下为 ${HOME}/.dvdcss/ ，在Windows下为Roaming应用数据目录（ %APPDATA% ）。特殊值 “off” 是禁用缓存。

DVDCSS_METHOD

设置libdvdcss用于读取加密光盘的认证和解密方法。可以是 title, key 或 disc 之一。

key

是默认方法。libdvdcss将使用一组计算好的播放器密钥来尝试获取光盘密钥。如果驱动器不识别任何播放器的密钥，这可能会失败。

disc

是密钥失败时的一个后备方法。libdvdcss不使用播放器密钥，而是使用暴力算法破解光盘密钥。这个过程是CPU密集型的，并且需要64MB的内存来存储临时数据。

title

是当所有其他方法都失败时的回退。它不依赖与DVD驱动器的密钥交换，而是使用密码攻击来猜测标题密钥。在极少数情况下，这可能会失败，因为光盘上没有足够的加密数据来进行统计攻击，但另一方面，这是解密存储在硬盘上的DVD，或RPC2驱动器上存在错误区域的DVD的唯一方法。

DVDCSS_RAW_DEVICE

指定要使用的原始设备。确切的用法将取决于你的操作系统，例如，Linux设置原始设备的工具是raw(8)。请注意，在大多数操作系统中，使用一个原始设备需要高度对齐的缓冲区。Linux要求2048字节对齐（这是一个DVD扇区的大小）。

DVDCSS_VERBOSE

设置libdvdcss的详细程度。

0:

完全不输出任何信息

1:

输出错误信息到stderr

2:

输出错误信息和调试信息到stderr

DVDREAD_NOKEYS

在启动时跳过检索所有密钥。目前禁用。

HOME

待修正: 记录它。

退出代码

通常 mpv 在成功完成播放后返回0作为退出代码。如果发生错误，可能返回以下的退出代码：

1:

初始化mpv时出错。如果未知的选项被传递给mpv，也会返回这个代码

2:

传递给mpv的文件不能被播放。这有点模糊：目前，如果初始化基本成功，文件的播放就被认为是成功的，即使初始化后立即播放失败

3:

一些文件可以播放，而一些文件无法播放（使用上面的成功定义）

4:

由于信号、视频输出驱动窗口中的Ctrl+c（默认），或来自编码模式下的默认退出的按键绑定而退出

注意，手动退出播放器将总是导致退出代码为0，覆盖正常返回的退出代码。另外， quit 输入命令可以接受一个退出代码：在这种情况下，该退出代码会被返回。

文件

请注意，本节假定使用 Linux/BSD。在其它平台上，路径可能有所不同。有关Windows的具体内容，参见 WINDOWS的文件 部分。

/usr/local/etc/mpv/mpv.conf

mpv的系统级的设置（取决于传递给设置的 --prefix —— mpv在默认设置中使用 /usr/local/etc/mpv/ 作为设置目录，而大多数Linux发行版将其设置为 /etc/mpv/ ）。

~/.cache/mpv

标准缓存目录。在mpv中的某些选项可能会导致它将缓存文件写入硬盘。这可以被环境变量覆盖，按升序排列：

1:

如果设置了 $XDG_CACHE_HOME ，则派生的缓存目录将为 $XDG_CACHE_HOME/mpv

2:

如果设置了 $MPV_HOME ，则派生的缓存目录将为 $MPV_HOME

如果目录不存在，mpv将尝试自动创建它。

~/.config/mpv

标准的设置目录。这可以被环境变量覆盖，按升序排列：

1:

如果 $XDG_CONFIG_HOME 被设置，那么衍生的设置目录将是 $XDG_CONFIG_HOME/mpv

2:

如果 $MPV_HOME``被设置，那么衍生的设置目录将是 ``$MPV_HOME

如果这个目录和原始设置目录（见下文）都不存在，mpv将尝试自动创建这个目录。

~/.mpv/

原始的（0.5.0之前）设置目录。如果存在，它将继续被读取。如果存在此目录而标准设置目录不存在，则缓存文件和稍后观看设置文件也将写入此目录。

如果该目录和标准的设置目录都存在，设置将从两者中读取，标准的设置目录的内容优先。然而，应该完全迁移到标准目录，在这种情况下，将显示一个警告。

~/.config/mpv/mpv.conf

mpv的用户设置（参见 设置文件 部分）

~/.config/mpv/input.conf

按键绑定 (参见 INPUT.CONF 部分)

~/.config/mpv/fonts.conf

为mpv定制的Fontconfig的fonts.conf。应该在这个文件中包含系统级的fonts.conf，否则mpv将不知道在系统中已经存在的字体。

只有在libass由fontconfig构建时才可用。

~/.config/mpv/subfont.ttf

后备的字幕字体

~/.config/mpv/fonts/

选项 --sub-fonts-dir （参见 字幕 ） 和 --osd-fonts-dir （参见 OSD ）的默认路径。

~/.config/mpv/scripts/

该目录中的所有文件被加载，就像它们被传递给 --script 选项一样。它们是按字母顺序加载的。

选项 --load-scripts=no 禁用加载这些文件。

详见 `Script location`_

~/.local/state/mpv/watch_later/

内含临时的设置文件，用于还原使用稍后观看功能的文件播放。例如参见 Q 按键绑定，或 quit-watch-later 输入命令。

这可以被环境变量覆盖，按升序排列：

1:

如果设置了 $XDG_STATE_HOME ，则派生的稍后观看目录将为 $XDG_STATE_HOME/mpv/watch_later

2:

如果设置了 $MPV_HOME ，则派生的稍后观看目录将为 $MPV_HOME/watch_later

每个文件都是一个小的设置文件，如果相应的媒体文件被加载，它就会被加载。它包含播放位置和一些（不一定是全部）在播放过程中被改变的设置。文件名是由媒体文件的完整路径散列出来的。一般来说，不可能从这个哈希值中提取媒体文件名。然而，你可以设置 --write-filename-in-watch-later-config 选项，播放器将把媒体文件名添加到还原设置文件的内容中。

~/.config/mpv/script-opts/osc.conf

这是由OSC脚本加载的。详见 屏显式控制器

这个目录中的其它文件也是特定于相应的脚本的，mpv核心不会接触它们。

WINDOWS的文件

在win32上（如果用MinGW编译，而不是Cygwin），默认的设置文件的位置是不同的。它们通常位于 %APPDATA%/mpv/ 下。例如，mpv.conf的路径是 %APPDATA%/mpv/mpv.conf ，它映射到一个系统级的和用户级的特定路径，例如

C:\users\USERNAME\AppData\Roaming\mpv\mpv.conf

你可以通过在cmd.exe中运行 echo %APPDATA%\mpv\mpv.conf 来找到确切路径。

其它设置文件（如 input.conf ）也在同一目录下。参见上方的 文件 部分。

缓存目录位于 %LOCALAPPDATA%/mpv/cache 。

稍后观看目录位于 %LOCALAPPDATA%/mpv/watch_later 。

环境变量 $MPV_HOME 会完全覆盖这些，就像在UNIX上一样。

如果mpv.exe旁边有一个名为 portable_config 的目录存在，所有的设置将只从这个目录加载。稍后观看的设置和缓存文件也会被写入到这个目录（这只存在于Windows，与 $MPV_HOME 是重合的。然而，由于Windows对脚本非常不友好，一个包装器脚本仅仅设置 $MPV_HOME ，就像你在其它系统上做的那样，是不可行的。 portable_config 为绕过这一限制提供了便利）。

与 mpv.exe 在同一目录下的设置文件的加载优先级较低。一些设置文件只被加载一次，这意味着例如两个 input.conf 文件位于两个设置目录中，只有优先级较高的目录中的文件才会被加载。

第三个具有最低优先级的设置目录是与 mpv.exe 在同一目录下的名为 mpv 的目录。这曾经是具有最高优先级的目录，但现在不赞成使用，将来可能会被移除。

注意，mpv偏好混用路径分隔符 / 和 \ 以达到简便的目的。kernel32.dll接受这种方式，但cmd.exe不接受。

MACOS的文件

在 macOS 上，稍后观看目录位于 ~/.config/mpv/watch_later/ ，缓存目录设置为 ~/Library/Caches/io.mpv/ 。这些目录不能被环境变量覆盖。其它的内容与 文件 一样。