[Ch.20~20.12] [上篇] MPV Player 官方文档中有关输入命令接口的说明 v0.35.1

作为上篇，本篇主讲 mpv 播放器官方使用手册中，关于输入命令接口其中的 Ch.20 ~ Ch.20.12 章节内容，剩下属性相关的章节将会纳入下篇讲解。提前声明，不会把输入命令接口的全部内容都照搬过来，例如部分与客户端 API 编程相关的章节仅一笔带过。

写这篇专栏的目的是让大家了解基础的语法规则，或是能看懂别人写的配置，行动前尽量做到知其然也要知其所以然。但还是那句话，部分配置项值得去研究和尝试，绝大多数保持默认就好。个人渣翻，内容上有疏漏或谬误的地方下方评论区反馈。

以下节选自 v0.35.1 官方使用手册中的 COMMAND INTERFACE 章节，不保证内容的时效性，仅供参考，实际还是以官方发布的最新文档为准，善用 Ctrl + F 快速定位你想要的内容：

Ch.20 命令接口

mpv播放器内核可以通过命令和属性来进行操控。许多跟播放器交互的方法都或多或少地用到了：键位绑定（input.conf），OSD（显示带有属性的信息），JSON IPC，客户端API（libmpv），以及经典的从属模式。

Ch.20.1 input.conf

input.conf 配置文件由一系列的键位绑定命令构成，例如：

每行会将一个键位映射作（绑定）一条输入命令。每个键位使用它们自身的文本值表示（若与 Shift 组合则表示大写），或是特殊的键位名。例如，a 映射为不带大写转换的 a 键位，A 则表示带大写转换的 a 键位。

input.conf 文件位于 mpv 配置目录中（一般是在 ~/.config/mpv/input.conf ，取决于不同的平台）。这里定义了默认的键位绑定配置：

一些特殊的键位可以通过以下方式获取：

通常来讲，键位可以跟 Shift，Ctrl 以及 Alt 组合起来使用：

mpv支持以输入测试模式启动，该模式下会在 OSD 中显示键位及其绑定的命令，被排除在外的命令除外：

（只有关闭窗口才会退出 mpv，按下通常的键位只会显示绑定信息，即使是映射为退出命令的键位。）

另见 Key names 小节。

Ch.20.2 input.conf 语法

[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*

默认需要注意的是，键盘右侧 Alt 键位可被用于创建特殊的字符，因此避免将它注册为修饰符。使用 --no-input-right-alt-gr 选项更改这条行为。

将换行始终视作一条新的绑定配置的开始，以 # 打头视为注释（在带引号的字符串参数之外）。要将命令绑定到 # 键位，可以使用 SHARP 指代。

<key> 既能表示是由键位产生的文本字符（ASCII 或 Unicode 字符），也可以是符号名（由 --input-keylist 打印的内容）。

<section>（用 { } 括起来的部分）表示的是用于该命令的输入段。

<command> 就表示命令本身，它是由命令名称和多个（或者没有）参数构成，全部由空格分隔开，字符串参数应该用引号包裹，代表性地就是 " 。参考 Flat command syntax 小节。

你可以绑定多条命令到一个键位上，例如：

a show-text "command 1" ; show-text "command 2"

（按下 a 键位将按序执行command1，command2）

同样也可以将一条命令绑定到一系列的键位上：

a-b-c show-text "command run after a, b, c have been pressed"

（这在常规的命令语法中并不常见，当依次按下 a，b，c 键位后执行 command）

如果 a 或者 a-b 键位已经被绑定，只会执行首个被匹配到的命令，并且多键位组合的命令将永远不会被调用（你可以亲自试试单独或同时设置上面两个示例中的绑定项，观察按下键位之后的行为就能轻松理解这句话的意思），可以将中间的键位重映射为 ignore 以避免这些问题。当前非修饰符键位的最大组合数量是4。

Ch.20.3 键位名称

所有的鼠标和键盘输入都将转换为 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*

表示数字小键盘名（keypad），行为视后端而异（是否实现了这项功能，以及如何对待数字锁定键 NumLock），但通常来说，mpv 会尝试将数字键盘上的键位映射到单独的名称之上，即使它们最终生成的文本与普通键位无异。

MOUSE_BTN*, MBTN*

表示多种鼠标按钮

（行为）取决于后端，鼠标滚轮也可以表示成按钮。此外，MOUSE_BTN3 至 MOUSE_BTN6 是作为 WHEEL_UP，WHEEL_DOWN，WHEEL_LEFT，WHEEL_RIGHT 的已被弃用的别名。

MBTN* 是  MOUSE_BTN* 的别称。

其中：

MOUSE_BTN3 -> WHEEL_UP

MOUSE_BTN4 -> WHEEL_DOWN

MOUSE_BTN5 -> WHEEL_LEFT

MOUSE_BTN6 -> WHEEL_RIGHT

旧的 MOUSE_BTN3~6 名称已被弃用，不推荐继续使用，建议使用新的符号命名。

WHEEL_*

表示鼠标滚轮（一般来说）。

AXIS_*

是作为 WHEEL_* 的已被弃用的别名。

*_DBL

表示鼠标按钮双击操作

MOUSE_MOVE, MOUSE_ENTER, MOUSE_LEAVE

由鼠标移动事件发出，进入/离开行为发生在当鼠标进入或离开 mpv 播放窗口的时候（或者是当前鼠标区域，用到了已被弃用的鼠标区域输入部分的机制）。

CLOSE_WIN

表示当使用操作系统的窗口管理器关闭 mpv 窗口时，产生的伪键位（你应该尽可能地避免这种情况，因为很可能会在未来修改或移除这种行为）。

GAMEPAD_*

表示由 SDL 游戏手柄后端产生的按键

UNMAPPED

表示与任何未映射的键位相匹配的伪键位（你应该尽可能地避免这种情况，因为很可能会在未来修改或移除这种行为）。

ANY_UNICODE

表示和生成文本的任何键位相匹配的伪键位（你应该尽可能地避免这种情况，因为很可能会在未来修改或移除这种行为）。

Ch.20.4 扁平化命令语法（Flat command syntax）

这一小节主讲 input.conf 当中用到的语法，并且作为“input.conf syntax”在手册的其他多处地方被引用到。

<command> ::= [<prefixes>] <command_name> (<argument>)* <argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)

command_name 是一段用命令自身名称表示且不加引号的字符串，见 List of Input Commands 小节。

参数之间用空格隔开，即使命令只期望传入一个参数。带有空格或其他特殊字符的参数必须用引号括起来，否则命令将无法被正确解析。

双引号被解释为按 JSON/C 风格进行转义，类似 \t 或 " 或是 \，JSON 转义依据 RFC 8259 规范，在去除 surrogate pair 编码之后进行转义（Surrogate Pair 是UTF-16中用于扩展字符而使用的编码方式，是一种采用两个UTF-16编码（四个字节）来表示一个字符。），这是唯一允许在换行处将 - 值当作 \n 的形式。

单引号则是获取字面意义上的内容，且不能在值中包含额外的单引号字符。

反引号（ ` ）同样是获取字面意义上的内容，但要比单引号更加地灵活，以 ` 打头后面跟上任意的 ASCII 字符，并且以相反的顺序，在与相同配对符号首次出现的位置结束（有多少开头就需要多少配对的结尾），例如  `-foo-` 或者 ``bar``。在这些分别是 -` 和 `` 的示例中是不允许在其中使用最终配对顺序的，在第二项示例中最后一个字符值同样也不能是反引号。

在同一参数中混用引号，类似 'foo'"bar" 是不受支持的。

需要注意的是参数传入以及属性的展开发生在不同的阶段。首先，参数按如上所述被确定下来，并在此后适当的时机展开属性，无论参数是否被引号修饰。不过，以上展开行为依旧可以被 raw 或 $> 前缀项阻止。参考 Input Command Prefixes 和 Property Expansion 两小节内容。

以下两小节与 libmpv 客户端 API 约定相关暂且略过，有相关需求请自行查阅原文，根本难不倒你（

Ch.20.5 Commands specified as arrays

Ch.20.6 Named arguments

Ch.20.7 输入命令列表

对于带有参数的命令，其参数名被放在 < / > 里面，真实命令中不要画蛇添足。可选参数被放在 [ / ] 当中，如果不传入这些参数，则设为默认值。

在 input.conf 当中，记得用引号将字符串参数括起来（参考 Flat command syntax）

ignore

用它来“堵住”那些不该被绑定的键位，并且不执行任何操作。对于禁用默认的键位绑定来说非常管用，而无需使用 --no-input-default-bindings 来禁用所有的（默认）绑定。

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 只能作为第三个参数传入（原先使用的是空格而非+）。虽然仍可作为第三个参数传入，但是有被弃用的打算。

revert-seek [<flags>]

撤销 seek 以及其他一些跳转命令（但并非全部）。一旦调用此命令将跳转至先前的播放位置。第二次调用撤销 revert-seek 命令本身。仅在同一个文件内有效。

首个参数可选，并且可以改变以下行为：

mark

标记当前时间位置，待下一次正常执行 revert-seek 命令将会回退到该时间点，自那之后无论发生了多少次跳转。

mark-permanent

如果设置了该标志，则会标记当前位置，并且在下次执行 revert-seek 命令之前，又设置了 mark 或 mark-permanent （或是播放到当前文件结尾）也不会有所变动。直到再次出现 revert-seek 将始终跳转到标记点。此标志无法与mark 共用。

不带参数的使用则按默认行为来执行。

frame-step

播放下一帧画面后暂停，仅播放音频时无效果。

frame-back-step

播放上一帧画面后暂停，请注意这个过程可能会非常慢（尝试精准跳转，相对来说不是很快），而且有时候无法按预期执行。效果如何则取决于能否正确地执行精准跳转（例如，参考 --hr-seek-demuxer-offset 选项说明）。视频滤镜或者其他修改画面帧时序（例如去隔行扫描）的视频后处理（video post-processing）一般都能正常工作，但在极端情况下可能会使得反步追踪行为静默异常。使用 --hr-seek-framedrop=no 应该会有点帮助，尽管这会让精准跳转变得更慢。

仅播放音频时无效果。

set <name> <value>

将给定的属性或选项设成给定的数值。

add <name> [<value>]

将给定的数值添加到属性或选项上。遇到上溢或下溢时，则固定为最大限度，如果略去 <value>，则假定为1。

cycle <name> [<value>]

循环给定的属性或选项，第二个参数可以是 up 或者 down 用来设定循环趋势。上溢则将属性设回最小值，下溢则设为最大值。如果省去 up 或 down，则假定为 up。

默认情况下是否允许长按键入（key-repeat）取决于属性。当前，具有连续值的属性（如音量之类的），默认是可以长按的，而离散值则不行（像 OSD 级别的属性）

注：这里所说的 key-repeat 是指短时间内反复触发按键输入，即用户长按调节键位，相应的属性能否正常响应这类输入。音量、亮度、饱和度等诸如此类的属性，数值具有连续性是支持长按调节。而某些属性虽然也是通过数值进行调节，但是各数值之间无逻辑关联，不具备连续性则不支持长按调节。

multiply <name> <value>

与 add 类似，但是用（给定的）数值乘上属性或选项。

screenshot <flags>

截屏

有以下多个标志可用（一部分可以跟 + 组合起来使用）：

<subtitles> （默认）

按照视频画面的原始分辨率，并且带上字幕保存为图片。在某些情况下，部分视频输出还可能会包含 OSD 界面。

<video>

类似 subtitles，但通常不会带上 OSD 或字幕，具体行为取决于选用的视频输出。

<window>

保存 mpv 整个窗口的内容，通常是经过缩放，带有 OSD 和字幕。具体行为取决于选用的视频输出，并且如果输出不支持，该标志会表现得近似 video。

<each-frame>

每帧都截图，再次发出这条命令后停止截屏。请注意当你在使用这个模式的时候应该禁用丢帧（frame-dropping）处理，或者在丢帧得情况下你可能会接收到重复得画面。该标志可以结合其他标志一起使用，例如 video+each-frame。

较早的 mpv 版本需要传入single 和 each-frame 作为第二个参数（并且无标志），这个语法仍然可以被识别，但未来很可能会被弃用或是移除。

如果你是用 ; 将该命令与另外一条命令结合起来使用，那么你可以使用 async 标志来让编码/写入图片文件异步进行。对于一般的单独命令来说，始终是异步进行的，并且（async）标志无效果（该行为自 mpv 0.29.0 之后有所变更）。

screenshot-to-file <filename> <flags>

将截图保存至指定的文件中，文件的格式将由扩展名猜测得到（并且忽略 --screenshot-format，这个行为在扩展名缺失或未知时是不确定的）。第二项参数与 screenshot 的首个参数类似，支持 subtitles, video, window。

如果文件已存在则会覆盖写入。

如同所有输入命令参数，文件名同样受到属性扩展的约束，正如 Property Expansion 小节所述的那样。

playlist-next <flags>

转到播放列表中的下一首。

首个参数传入：

weak（默认）

如果当前播放的是列表中的最后一项，则不做任何操作。

force

如果播放列表中无更多文件项则终止播放。

playlist-prev <flags>

转到播放列表中的上一首。

首个参数传入：

weak（默认）

如果当前播放的是列表中的第一项，则不做任何操作。

force

如果正在播放的是首个文件项则终止播放。

playlist-play-index <integer|current|none>

按照给定的播放列表索引开始（或重新）播放。除了从0开始的播放列表条目索引之外，还支持以下参数值：

<current>

再次播放当前播放列表的曲目（同 playlist-current-pos 所示），若是设为 none，则停止播放（在极端情况下，playlist-current-pos 可以指向播放列表条目，即使当前播放的项目处于非活动状态）。

<none>

停止播放，若启用了空闲模式（--idle），则播放器会进入空闲状态，否则退出。

这条命令类似 loadfile，因为它只会操作接下来要播放内容的状态，而不会等到当前文件被卸载之后才去加载下一项。

设置 playlist-pos 或类似属性可以达到与这条命令近似的效果。然而，这项会更高效，并且保证会在例如新的播放列表项目与前一个播放列表相同时重新开始播放。

loadfile <url> [<flags> [<options>]]

加载并播放给定的文件或 URL，技术上来说，这仅仅是一条播放列表操作命令（替换或向播放列表中添加新的项目），实际文件会被独立地加载。例如，一条用于将当前文件替换成新文件的 loadfile 命令会在当前文件停止播放之前就返回，并且甚至新文件还在被加载中。

第二项参数传入：

<replace> （默认）

停止播放当前文件，并且立刻播放新的文件。

<append>

追加文件至播放列表。

<append-play>

追加文件，并且当前未播放任何内容，则开始播放（始终从添加的文件开始播放，即使在执行这条命令之前的播放列表并不为空）。

playlist-clear

除当前正在播放的文件以外，清除播放列表。

playlist-remove <index>

移除播放列表中给定索引的曲目，索引值从0开始计数。特殊值 current 移除当前曲目，请注意移除当前曲目的同时也会停止播放，并从下一项曲目开始播放。

playlist-move <index1> <index2>

移动播放列表中位于 index1 的曲目至 index2 曲目的位置（矛盾的是，如果 index1 小于 index2，那么被移动的播放列表曲目在移动之后的索引值不会是 index2，因为 index2 指向的是目标曲目，而不是移动之后曲目的索引）。

注：在这条命令中，曲目自身的索引值并不会随着曲目在列表中排布顺序的改变而改变，因此慎用这条命令，滥用会使你当前播放列表中曲目的索引顺序会变得混乱，某些依赖文件索引值的播放器脚本可能会出错。

playlist-shuffle

混洗播放列表，这条命令与在启动时用 --shuffle 选项所完成的行为相似。

playlist-unshuffle

尝试还原先前的 playlist-shuffle 命令，仅会生效一次（多次连续的使用 playlist-shuffle 命令不会有任何效果）。如果在使用了 playlist-shuffle 命令之后，开启了新一轮循环列表则可能无法正确起到作用。

run <command> [<arg1> [<arg2> [...]]]

执行给定的命令，不像 MPlayer/mplayer2 以及 mpv 早期版本（0.2.x 和更早的版本），这条命令不会调起 shell，而是直接执行命令，每项参数被独立地传入，如同 Property Expansion 小节中所述的那样展开。

该命令有众多参数，且不能够和命名参数（类似 mpv 环境下的关键字，有特殊含义的参数名）一块儿使用。

程序按照 detach 的方式运行，mpv 不会等待命令执行完成，而是在生成命令之后立即继续播放。

若要获得旧版行为，请使用 /bin/sh 和 -c 作为前两个参数。

subprocess（粗略介绍，同样是与脚本 API 相关，对普通用户的用处不大）

与 run 命令类似，但是会给予调用者对进程执行更多的控制权，并且不会主动分离进程。

通过异步地执行这条命令来避免阻塞，直到进程结束。

该命令有以下命名参数，不保证它们的先后顺序，因此你应该始终用命名参数去调用，参考 Named arguments 小节。

点到为止……

quit [<code>]

退出播放器，如果给定了参数，则用它作为退出码。

quit-watch-later [<code>]

退出播放器，并且保存当前播放位置。稍后播放同一文件时会跳转到先前位置处开始。可选参数的作用和 quit 命令相同，见 RESUMING PLAYBACK 小节。

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 设为 1）或上一个（skip 设为 -1）字幕。除了跳转视频和音频而不是调整字幕延迟之外，这条命令与 sub-step 类似。

第二个参数传入：

primary（默认）

依次跳转切换主字幕。

secondary

依次跳转切换次级字幕。

对于内嵌字幕（类似 Matroska 格式），仅适用于已显示的字幕事件，或是预取范围较短的字幕事件。

print-text <text>

打印文本至标准输出，字符串参数中可以包含属性（参考 Property Expansion 小节），注意要把参数用引号括起来。

show-text <text> [<duration>|-1 [<level>]]

显示文本至 OSD，字符串参数中可以包含属性，可以用来显示显示播放时长，文件名等等。

<duration>

用来显示以 ms 计算的时长消息。默认情况下与 --osd-duration 使用的是相同值。

<level>

用来显示文本的最小 OSD 等级（参考 --osd-level）。

仅可用于客户端 API 的命令，略过：

expand-text <string>

expand-path "<string>"

show-progress

在 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 类似。对于客户端 API 的作用是：可以在不关闭播放器的情况下停止播放。

首个参数可选，且支持以下标志：

keep-playlist

保留播放列表。

mouse <x> <y> [<button> [<mode>]]

发送一个带有给定坐标  (<x>, <y>) 的鼠标事件。

第二个参数传入：

<button>

点击鼠标按钮的号码，应为 0~19 其中的一个，如果省去 <button>，仅会更新坐标位置。

第三个参数传入：

<single>（默认）

鼠标事件表示为常规的单击。

<double>

鼠标事件表示为双击。

keypress <name>

向 mpv 输入句柄发送一条按键事件，触发为该键位配置的任何行为。

name 使用的是 input.conf 当中为键位和修饰符约定的命名方案。对于客户端 API 的作用是：可以发送按键事件至 libmpv 内部处理。

keydown <name>

类似 keypress，但是设置 KEYDOWN 标志，以便如果按键被绑定到一个可反复触发的命令时，则会按照 mpv 的按键重复次数反复执行，直到调用 keyup 命令为止。

keyup [<name>]

设置 KEYUP 标志的同时，终止任何已被触发的反复键入行为。name 为可选参数，如果未给定 name 或为空串，KEYUP 标志将会被设置到所有的键位上。否则，KEYUP 标志仅会设置在由 name 指定的键位上。

keybind <name> <command>

将按键绑定到一条输入命令上，command 必须是一条包含所有期望被传入的参数和标志的完整命令。name 和 command 全部使用的是 input.conf 命名方案，主要是对客户端 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>

不要改变当前轨道的选择。

Ch.20.8（后续）可能会改动的输入命令

af <operation> <value>

变更音频滤镜链，参考 vf 命令。

vf <operation> <value>

变更视频滤镜链。

语义同选项解析的内容一致（参考 VIDEO FILTERS），因此，以下文字多为冗余且不完整的摘要说明。

第一项参数决定要做什么：

<set>

用新的滤镜链覆盖先前项。

<add>

附加新的滤镜链到先前项中去。

<toggle>

检查给定的滤镜是否已存在于视频链中。如果是，则会删除相应的滤镜，反之则会添加滤镜（如果有多个滤镜被传到命令中，上述行为会逐一作用于每个滤镜）。

一种特殊的变形是将其与标签相结合，并且使用不带滤镜名和参数的 @name 作为滤镜项。这将会切换启用/禁用标志。

<remove>

类似 toggle，但始终会从视频链中删除指定的滤镜。

<del>

从视频链中删除指定的滤镜，与其他情况不同，第二项参数是以逗号为分隔的滤镜名或整数索引。0 表示第一个滤镜，负数索引表示从最后一个滤镜开始计算，即 -1 表示最后一个滤镜。该参数已被弃用，请使用 remove。

<clr>

删除所有的滤镜，请注意，与其他子命令一样无法操控被自动插入的滤镜。

以上参数始终都需要传给 vf 命令，例如，假设要用到 clr 则使用 vf clr ""。

你可以通过在标签之前加上 @name:（其中 name 是用户选择的任意标识符）。在所有的滤镜链修改命令中，标签被可用在按名称引用的滤镜上。对于 add 参数，使用一个当前在用的标签将替换现有的滤镜。

在变更了滤镜链之后，vf 命令会在 OSD 上展示请求滤镜列表，效果大致相当于 show-text ${vf}，请注意，自动插入、用于格式转换的滤镜不会显示在列表中，仅会显示用户请求的内容。

通常，该命令会检查视频链是否被成功地重新创建，并在失败时撤销操作。如果在配置视频之前执行命令（如果在打开文件后和在解码视频帧之前立即执行命令，则可能会发生这种情况），则无法进行检查，随后可能会发生创建视频链失败的情况。

如何在软件运行期间切换到被禁用的滤镜的示例：

• 添加类似 vf-add=@deband:!gradfun 到 mpv.conf 当中，其中 @deband: 为标签，是任意的、用户为该滤镜条目指定的名称。位于滤镜名之前的 ! 表示默认禁用该滤镜。在此之后的所有内容都是一般的过滤器名称，并且有可能是滤镜参数，就像一般的 --vf 语法那样。

• 向 input.conf 中添加 a vf toggle @deband，当 a 键位被按下时，这会切换那些带有 deband 标签滤镜的“禁用”标志。

cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]

遍历参数值列表，每次调用命令都会把给定的属性（property）设为列表中的下一参数值。该命令使用属性/选项的当前值，用它来确定列表的当前位置。一旦找到目标值后将设置列表中的下一个参数值（如果有必要，则会绕回到第一项进行设置）。

该命令具有可变数量的参数项，且不能与已命名参数一同使用。

特殊参数 !reverse 可用于逆向循环参数值列表，优点是当添加了第二个用于反向循环的键位绑定时，无需自行反转参数值列表。

enable-section <name> [<flags>]

该命令已被弃用，软件内部使用除外，启用命名输入段（Input Section）中的所有键位绑定。（略）

disable-section <name>

弃用，理由同上，配合 enable-section 使用。（略）

define-section <name> <contents> [<flags>]

弃用，理由同上，创建一个命名输入段，或替换一个已存在的命名输入域中的内容。（略）

overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>

添加一个来自原始数据的 OSD 覆盖层（overlay），这对于操控 mpv 并且想要在视频窗口顶部显示内容的脚本和应用程序可能会很有用。

覆盖层通常会按照屏幕分辨率显示，但在一些视频输出（VO）中，分辨率会降低为视频分辨率。你可以读取 osd-width 和 osd-height 属性（以获取相关数值）。至少对于 --vo-xv 和宽银幕视频源（例如 DVD），同样也应该读取 osd-par ，并且覆盖层应该支持视频宽高比补偿。

该命令拥有以下的命名参数，顺序不作保证，所以你始终应该以命名参数的方式来调用它们，参考 Named arguments 小节。

id 是一个介于 0 到 63 之间用来区分覆盖层元素的整数，可被用来添加多个覆盖部分，用该命令搭配一个已有 ID 来更新一个覆盖部分，或着用 overlay-remove 来移除一个部分。使用先前未被使用过的 ID 将会添加一个新的覆盖层，而重复使用一个 ID 则会更新这个区域。

x 和 y 指定了 OSD 应该被显示的位置。

file 指定了从中读取原始图像数据的文件，它可以是一个带 @ 前缀的 UNIX 文件描述符（例如 @4），又或者是文件名。在命令返回之前，文件将会用 mmap() 的方式被映射到内存中，进行复制操作，并在命令返回前unmap（在 0.18.1 版本进行了调整）。

也可以通过传入一个前缀是 & 字符的整数作为内存地址，传入这样一个原始内存地址用作位图内存，错误的地址会导致播放器崩溃。这种模式也许适合搭配 libmpv 使用。offset 参数仅用于增加内存地址（从 0.8.0 版本开始生效，之前的版本则忽略）。

offset 是与源文件中首个像素点的字节偏移值（当前的实现方式始终是从位置 0 开始到图像末尾mmap整个文件，所以应该避免使用较大的偏移值，在 0.8.0 版本之前，偏移值实际上会直接传给 mmap，但之后的调整使之更易于使用。）

fmt 是标识图像格式的字符串。当前，仅定义了 bgra，这种格式规定了每个像素有 4 字节，各分量有 8 位，最低有效 8 位是蓝色分量，最高有效8位是透明分量（在小端模式下，分量顺序是 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 字节。）

注意：

在 0.18.0 版本之前，在更新覆盖层时，你必须通过替换成不同的内存缓冲区来手动执行“双缓冲”。从 0.18.1 版本开始，内存仅仅是用于复制，并且在命令返回后不会引用命令参数所指向的任何内存，如果你想要在 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 连接、脚本）都有一个单独的命名空间，因此 API 用户可以（自行）创建和分配 ID 而不会与其他 API 用户起冲突。

如果 libmpv 客户端被销毁，则与其关联的所有覆盖层也会被删除。特别是通过 --input-ipc-server 建立的连接，添加覆盖层并再次断开连接将会立刻删除覆盖层。

format

指定覆盖层类型的字符串，接受以下参数值：

注：这一段落的网页渲染有问题，导致以下4组参数的部分描述内容对不上号，请酌情参考。

(HTML rendering of this is broken, view the generated manpage instead, or the raw RST source)

ass-events

提供2个 ASS 样式，OSD 包含有当前 --osd-... 选项定义的文本样式，默认值比较类似，并且包含将所有选项都设为默认值时 OSD 所具有的样式。

none

可导致覆盖层被移除的特殊值。除 id 和 format 之外的大多数参数都会被忽略。

data

字符串参数，根据 format 参数定义覆盖层内容，字符串使用换行符进行分隔。每一行都会转换为 Dialogue ASS 事件的 Text 部分。某些依赖 ASS 标签的行为可能会在未来的 mpv 版本中有所变动。

注意，推荐将多行内容放到 data 参数中，而不是添加到多个 OSD 覆盖层中。

res_x, res_y

如果 format 参数被设为 ass-events 则可以使用，可选，默认为 0/720。此外，res_x 和 res_y 选项还指定了 ASS PlayResX 和 PlayResY 标题字段的值，如果 res_y 被设为 0，那么 PlayResY 会被初始化成一个任意默认值（但请注意该命令的 res_y 默认是720，而不是0）。如果 res_x 被设为 0，PlayResX 基于 res_y 进行设置以便虚拟 ASS 像素能够具有方形像素的长宽比。

z

覆盖层 Z 轴顺序，可选，默认为 0

需注意处在不同格式的覆盖层之间的 Z 轴顺序是静态的，并且无法被修改（当前，这意味着由 overlay-add 添加的位图覆盖层始终会置于由 overlay-add 添加的 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），如果窗口大小未知则会选择回退。

你应该留意到这种机制是非常低效的，因为它在渲染完整的结果，随后使用渲染位图列表的边界框（即使设置了隐藏），会刷新各类缓存。同时，最终结果还取决于所使用的 libass 版本。

该功能为实验性质，并且可能还会进行改动。

script-message [<arg1> [<arg2> [...]]]

向所有的客户端发送一条消息，并向其中传入后续的参数列表。消息的具体含义是什么？带多少参数？以及参数的含义是什么完全取决于接收方和发送方（彼此之间的约定）。所有的客户端都会接收到消息，因此请小心处置命名冲突的问题（或者使用 script-message-to）。

script-message-to <target> [<arg1> [<arg2> [...]]]

与 script-message 一样，但只会发送给 <target> 命名的客户端。每个客户端（例如脚本）都拥有一个唯一命名。举个例子，Lua 脚本可以通过 mp.get_script_name() 获取到它们的名称。请注意客户端名称仅允许包含英文字母、数字以及 _ 字符。

该命令拥有可变数量的参数，并且无法使用已命名的参数。

script-binding <name>

调用脚本提供的键位绑定，可用于重映射由外部 Lua 脚本提供的键位绑定关联。

参数为绑定关联的名称。

可选用脚本名称作为前缀，并使用 / 作为分隔符，例如 script-binding scriptname/bindingname ，请注意脚本名称仅允许由英文字母、数字以及 _ 字符构成。

为了完整起见，以下是该命令内部的工作流程，细节内容可能会随时进行改动。在所有匹配到的按键事件中，会调用  script-message-to 或者 script-message（取决于是否包含脚本名称），参数如下：

1. key-binding 字符串

2. 绑定名称（如上所述）

3. 字符串形式的按键状态（见下文）

4. 键位名称（自 0.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>]

返回内存中的截屏内容，仅可通过客户端 API 使用。该命令返回的 MPV_FORMAT_NODE_MAP 包含 w，h，stride 字段且均设置为显式内容，format 字段默认被设置为 bgr0 格式，按照 B8G8R8X8（B 表示 LSB）的形式组织。用 X 填充的内容表示未定，data 字段是一类带有实际图像数据的 MPV_FORMAT_BYTE_ARRAY 类型。图像也会紧随 mpv_node 的结果被释放后尽快地被释放。与客户端 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>

向滤镜发送一条带有给定 <label> 的命令，使用 all 则会一次性向所有的滤镜发送命令，命令和参数字符串必须是滤镜所指定的内容。当前，这条命令仅适用于 lavfi 滤镜，请参阅 libavfilter 文档以获取滤镜支持的命令。

请注意 <label> 是 mpv 的滤镜标签，而不是 libavfilter 相关的滤镜名称。

af-command <label> <command> <argument>

与 vf-command 类似，不过是用于音频滤镜的。

apply-profile <name> [<mode>]

应用一项已命名的配置描述的内容，这类似于在配置文件中使用 profile=name，不一样的地方是你可以将其映射成一个快捷键，在软件运行期间改变它的状态。

mode 参数可以是：

default

应用配置，省略参数时默认采用。

restore

恢复由先前的 apply-profile 命令为这个配置描述所设置的选项。当且仅当配置描述通过 profile-restore 设为相关模式时有效。如果无法执行任何操作则会输出警告信息，细节请参考 Runtime profiles 章节。

load-script <filename>

加载脚本，类似于 --script 选项。多次调用该命令是否会等待脚本完成初始化或不作变动，以及将来的操作行为是未定义的。

成功的话，返回一个带有 client_id 字段的 mpv_node，其中 client_id 设置为新创建脚本句柄 mpv_client_id() API 调用的返回值。

change-list <name> <operation> <value>

该命令会修改 List Options 章节中描述的列表选项，<name> 参数是普通的选项名称，而 <operation> 是用于选项的后缀或行为。

部分操作不需要传值，但在命令中仍需要给定 value 参数，在这些情况下，value 必须为空字符串。

dump-cache <start> <end> <filename>

将当前的缓存内容转储到给定的文件中，如果存在 <filename> 文件则会被覆盖。<start> 和 <end> 给定了需要转储的时间范围。如果在给定的时间范围内没有缓存数据，则可能不会转储任何内容（创建空文件）。

转储较大的缓存内容会让播放器卡住，由于无法避免这个问题，因此这个功能主要用在创建小范围的内容摘录。

有关适用于该命令的各种附加说明请参考 --stream-record，因为两者都使用了相同的底层代码来写入输出文件。

如果 <filename> 是空字符串，则不会执行 dump-cache 命令。

如果未提供 <end>，则会启用持续转储。随后在转储完已有的缓存内容后，任何从网络中读取的内容也会被添加到缓存中，这个行为类似于 --stream-record（尽管不会与之发生冲突，且两者可以同时使用）。

如果 <end> 时间位于缓存之后，则不会等待并写入新接收到的数据到缓存中。

生成的文件末尾可能会存在略有损坏或不完整的情况（无法保证文件末尾能够正确对齐）。

请注意该命令仅在转储结束后才算完成，工作方式类似 screenshot 命令，只不过会阻塞更多时长。如果使用了连续转储，则在停止播放、发生错误、运行另一个转存命令，或调用类似 mp.abort_async_command API 显式终止该命令之前，该命令是不会结束的。详情见 Synchronous vs. Asynchronous 章节。

注意

这条命令主要是为网络数据流量身打造的。对于本地文件可能有更好的方法来创建摘录内容等。有许多对用户更加友好的 Lua 脚本通过生成单独的 ffmpeg 实例，来重新编码文件中的某些部分。对于网络数据流实现起来有一定的困难，因为需要重新下载数据流的缘故。即使使用了 --stream-record 将数据流写入到本地文件系统中，也可能存在某些问题，因为用来记录的文件仍然可以被（外部程序）写入。

该命令仍处在实验性质，并且所有有关它的细节内容未来可能会进行调整。

ab-loop-dump-cache <filename>

本质上是调用把当前 AB 循环点作为参数的 dump-cache 命令，像 dump-cache 那样，该命令会覆写以 <filename> 为命名的文件。同样地，如果 B 点被设为 no 则会在现有缓存被转储后，继续转存后续的内容。

将来视情况可能会删除该命令。

ab-loop-align-cache

在 ab-loop-dump-cache 命令将要（或许要）转存的缓存范围内，重新判定 A/B 循环的起止点。基本上会跟关键帧的时间点对齐。推测结果可能会存在偏离，尤其是在缓存末尾（原因是重新封装导致的粒度问题）。如果在此期间缓存出现缩小的情况，则该命令设置的起止点也不再是有效参数。

相比 ab-loop-dump-cache 命令，将来这条命令更有可能被删除。

无正式文档说明的命令：ao-reload（实验性质/仅内部使用）

略过 Ch.20.8.1 事件列表（List of events）、Ch.20.8.2 钩子事件（Hooks）等有关客户端 API 的章节

Ch.20.9 输入命令前缀

这些前缀位于按键名和实际命令之间。可以指定多个前缀，彼此之间用空格隔开。

osd-auto

使用该命令的默认行为，这也是 input.conf 其中命令的默认设置。但有一些 libmpv/scripting/IPC API 并不会将其作为默认值，而是使用 no-osd 。

no-osd

不对该命令使用任何有关 OSD 的行为。

osd-bar

如果可以的话，使用该命令会显示一个条状控件。跳转命令将会显示该进度条，而属性变更命令则可能会显示新设置的属性值。

osd-msg

如果可能的话，使用该命令会显示一条 OSD 消息。跳转命令会显示当前的播放时长，而属性变更命令则会以文本的形式显示新设置的属性值。

osd-msg-bar

组合使用 osd-bar 和 osd-msg

raw

不展开字符串参数中的属性（例如 "${property-name}"），这是部分 libmpv/scripting/IPC API 的默认行为。

expand-properties

按照属性扩展中描述的那样展开全部的字符串参数，这是 input.conf 其中命令的默认行为。

repeatable

对于某些命令，长按键位并不会重复执行该命令。这个前缀在任何情况下都会强制开启按键重复，对于一个命令列表来说：首个命令决定了整个列表的可重复与否（直到且包括 0.33 版本在内，命令列表始终具有可重复的特性）。

async

允许异步执行（如果可行的话）。注意只有少数命令能够支持这项特性，默认情况下，某些命令本身已具备异步执行的能力（或者更确切的说，效果可能会在命令执行结束后显现出来）。该标志的含义将来可能会做出更改。仅当你不完全依赖这个命令的返回也能实现你想要的效果时才去使用。

sync

允许同步执行（如果可以的话）。通常所有的命令默认都是同步的，但也有些命令默认是异步，以便兼容旧版本的行为。

所有的 osd 前缀仍会被全局的 --osd-level 设置所覆盖。

略过 Ch.20.10 同步vs异步（Synchronous vs. Asynchronous）、Ch.20.11 异步命令细节（Asynchronous command details）章节

Ch.20.12 输入节段

作用是对一组绑定配置进行分组，并且单独启用或禁用它们，在 input.conf 文件里面，每个按键绑定都会被分配到一个输入节段，而不是实际由具体文字所表示的节段。

另见： enable-section 和  disable-section 命令。

预定义的绑定配置有：

default

没有指定输入节段的绑定配置将隐式分配到这个节段中，且在软件正常播放期间默认处于启用状态。

encode

在编码模式下激活的节段，以独占的方式开启，因此会忽略默认节段中的绑定配置。

参考资料：

• https://mpv.io/manual（MPV Player Reference）

• https://mpv.io（mpv项目官网）