作為上篇，本篇主講 mpv 播放器官方使用手冊(cè)中，關(guān)于輸入命令接口其中的?Ch.20 ~ Ch.20.12 章節(jié)內(nèi)容，剩下屬性相關(guān)的章節(jié)將會(huì)納入下篇講解。提前聲明，不會(huì)把輸入命令接口的全部?jī)?nèi)容都照搬過(guò)來(lái)，例如部分與客戶端 API 編程相關(guān)的章節(jié)僅一筆帶過(guò)。

寫這篇專欄的目的是讓大家了解基礎(chǔ)的語(yǔ)法規(guī)則，或是能看懂別人寫的配置，行動(dòng)前盡量做到知其然也要知其所以然。但還是那句話，部分配置項(xiàng)值得去研究和嘗試，絕大多數(shù)保持默認(rèn)就好。個(gè)人渣翻，內(nèi)容上有疏漏或謬誤的地方下方評(píng)論區(qū)反饋。

以下節(jié)選自?v0.35.1 官方使用手冊(cè)中的 COMMAND INTERFACE 章節(jié)，不保證內(nèi)容的時(shí)效性，僅供參考，實(shí)際還是以官方發(fā)布的最新文檔為準(zhǔn)，善用 Ctrl + F 快速定位你想要的內(nèi)容：

Ch.20 命令接口

mpv播放器內(nèi)核可以通過(guò)命令和屬性來(lái)進(jìn)行操控。許多跟播放器交互的方法都或多或少地用到了：鍵位綁定（input.conf），OSD（顯示帶有屬性的信息），JSON IPC，客戶端API（libmpv），以及經(jīng)典的從屬模式。

Ch.20.1 input.conf

input.conf 配置文件由一系列的鍵位綁定命令構(gòu)成，例如：

每行會(huì)將一個(gè)鍵位映射作（綁定）一條輸入命令。每個(gè)鍵位使用它們自身的文本值表示（若與 Shift 組合則表示大寫），或是特殊的鍵位名。例如，a 映射為不帶大寫轉(zhuǎn)換的 a 鍵位，A 則表示帶大寫轉(zhuǎn)換的 a 鍵位。

input.conf 文件位于 mpv 配置目錄中（一般是在 ~/.config/mpv/input.conf ，取決于不同的平臺(tái)）。這里定義了默認(rèn)的鍵位綁定配置：

一些特殊的鍵位可以通過(guò)以下方式獲?。?/p>

通常來(lái)講，鍵位可以跟 Shift，Ctrl 以及 Alt 組合起來(lái)使用：

mpv支持以輸入測(cè)試模式啟動(dòng)，該模式下會(huì)在 OSD 中顯示鍵位及其綁定的命令，被排除在外的命令除外：

（只有關(guān)閉窗口才會(huì)退出 mpv，按下通常的鍵位只會(huì)顯示綁定信息，即使是映射為退出命令的鍵位。）

另見(jiàn) Key names 小節(jié)。

Ch.20.2 input.conf 語(yǔ)法

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

默認(rèn)需要注意的是，鍵盤右側(cè) Alt 鍵位可被用于創(chuàng)建特殊的字符，因此避免將它注冊(cè)為修飾符。使用 --no-input-right-alt-gr 選項(xiàng)更改這條行為。

將換行始終視作一條新的綁定配置的開(kāi)始，以 # 打頭視為注釋（在帶引號(hào)的字符串參數(shù)之外）。要將命令綁定到 # 鍵位，可以使用 SHARP 指代。

<key> 既能表示是由鍵位產(chǎn)生的文本字符（ASCII 或 Unicode 字符），也可以是符號(hào)名（由 --input-keylist 打印的內(nèi)容）。

<section>（用 { } 括起來(lái)的部分）表示的是用于該命令的輸入段。

<command> 就表示命令本身，它是由命令名稱和多個(gè)（或者沒(méi)有）參數(shù)構(gòu)成，全部由空格分隔開(kāi)，字符串參數(shù)應(yīng)該用引號(hào)包裹，代表性地就是 " 。參考 Flat command syntax 小節(jié)。

你可以綁定多條命令到一個(gè)鍵位上，例如：

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

（按下 a 鍵位將按序執(zhí)行command1，command2）

同樣也可以將一條命令綁定到一系列的鍵位上：

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

（這在常規(guī)的命令語(yǔ)法中并不常見(jiàn)，當(dāng)依次按下 a，b，c 鍵位后執(zhí)行 command）

如果 a 或者 a-b 鍵位已經(jīng)被綁定，只會(huì)執(zhí)行首個(gè)被匹配到的命令，并且多鍵位組合的命令將永遠(yuǎn)不會(huì)被調(diào)用（你可以親自試試單獨(dú)或同時(shí)設(shè)置上面兩個(gè)示例中的綁定項(xiàng)，觀察按下鍵位之后的行為就能輕松理解這句話的意思），可以將中間的鍵位重映射為 ignore 以避免這些問(wèn)題。當(dāng)前非修飾符鍵位的最大組合數(shù)量是4。

Ch.20.3 鍵位名稱

所有的鼠標(biāo)和鍵盤輸入都將轉(zhuǎn)換為 mpv 指定的鍵位名稱。鍵名既可以是表示物理按鍵的特殊符號(hào)標(biāo)識(shí)符，或是由 UTF-8 編碼，用 Unicode 碼點(diǎn)表示的文本鍵名。這些通常是鍵盤輸入生成的內(nèi)容。例如 a 表示 A 鍵位，因此，mpv 使用的是由當(dāng)前操作系統(tǒng)鍵盤布局轉(zhuǎn)換得到的輸入內(nèi)容，而非物理掃描得到的按鍵碼。

當(dāng)前有一個(gè)硬編碼假設(shè)，就是每個(gè)文本鍵位都可以表示為單個(gè) Unicode 碼點(diǎn)（按照 NFKC 形式）。

所有的鍵名都可以跟 Shift，Ctrl，Alt，Meta 修飾符進(jìn)行組合，它們必須作為實(shí)際鍵名的前綴項(xiàng)，每個(gè)修飾符后面跟著一個(gè) + 號(hào)（比方說(shuō) ctrl+q）。

Shift 修飾符需要額外留意些，例如 Shift+2 在 input.conf 文件中通常應(yīng)該被指定為鍵名 @，并且類似的組合 Alt+Shift+2 通常寫作 Alt+@，諸如此類。特殊的鍵名，像 Shift+LEFT 則會(huì)按預(yù)期工作。如有疑問(wèn)，請(qǐng)使用 --input-test 選項(xiàng)以檢查 mpv 是如何對(duì)待一項(xiàng)鍵位或組合的。

符號(hào)鍵名和修飾符名是大小寫敏感的，Unicode 鍵名同樣也是大小寫敏感，因?yàn)檩斎虢壎ㄍǔＷ裱?Shift 鍵位。

另一種類型的鍵名是十六進(jìn)制形式的鍵名，用作那些既不是 unicode 也不是 mpv 特殊定義名稱的特殊鍵位的回退。一旦 mpv 為它們添加了專有名稱就會(huì)終止，但如果沒(méi)有發(fā)生這類情況，則可以允許你使用這個(gè)鍵位。

所有符號(hào)名都可以通過(guò) --input-keylist 列出。--input-test 是一種將所有輸入都打印到 OSD 上面的特殊模式。

對(duì)部分符號(hào)名的注解如下：

KP*

表示數(shù)字小鍵盤名（keypad），行為視后端而異（是否實(shí)現(xiàn)了這項(xiàng)功能，以及如何對(duì)待數(shù)字鎖定鍵 NumLock），但通常來(lái)說(shuō)，mpv 會(huì)嘗試將數(shù)字鍵盤上的鍵位映射到單獨(dú)的名稱之上，即使它們最終生成的文本與普通鍵位無(wú)異。

MOUSE_BTN*, MBTN*

表示多種鼠標(biāo)按鈕

（行為）取決于后端，鼠標(biāo)滾輪也可以表示成按鈕。此外，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 名稱已被棄用，不推薦繼續(xù)使用，建議使用新的符號(hào)命名。

WHEEL_*

表示鼠標(biāo)滾輪（一般來(lái)說(shuō)）。

AXIS_*

是作為 WHEEL_* 的已被棄用的別名。

*_DBL

表示鼠標(biāo)按鈕雙擊操作

MOUSE_MOVE, MOUSE_ENTER, MOUSE_LEAVE

由鼠標(biāo)移動(dòng)事件發(fā)出，進(jìn)入/離開(kāi)行為發(fā)生在當(dāng)鼠標(biāo)進(jìn)入或離開(kāi) mpv 播放窗口的時(shí)候（或者是當(dāng)前鼠標(biāo)區(qū)域，用到了已被棄用的鼠標(biāo)區(qū)域輸入部分的機(jī)制）。

CLOSE_WIN

表示當(dāng)使用操作系統(tǒng)的窗口管理器關(guān)閉 mpv 窗口時(shí)，產(chǎn)生的偽鍵位（你應(yīng)該盡可能地避免這種情況，因?yàn)楹芸赡軙?huì)在未來(lái)修改或移除這種行為）。

GAMEPAD_*

表示由 SDL 游戲手柄后端產(chǎn)生的按鍵

UNMAPPED

表示與任何未映射的鍵位相匹配的偽鍵位（你應(yīng)該盡可能地避免這種情況，因?yàn)楹芸赡軙?huì)在未來(lái)修改或移除這種行為）。

ANY_UNICODE

表示和生成文本的任何鍵位相匹配的偽鍵位（你應(yīng)該盡可能地避免這種情況，因?yàn)楹芸赡軙?huì)在未來(lái)修改或移除這種行為）。

Ch.20.4 扁平化命令語(yǔ)法（Flat command syntax）

這一小節(jié)主講 input.conf 當(dāng)中用到的語(yǔ)法，并且作為“input.conf syntax”在手冊(cè)的其他多處地方被引用到。

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

command_name 是一段用命令自身名稱表示且不加引號(hào)的字符串，見(jiàn) List of Input Commands 小節(jié)。

參數(shù)之間用空格隔開(kāi)，即使命令只期望傳入一個(gè)參數(shù)。帶有空格或其他特殊字符的參數(shù)必須用引號(hào)括起來(lái)，否則命令將無(wú)法被正確解析。

雙引號(hào)被解釋為按 JSON/C 風(fēng)格進(jìn)行轉(zhuǎn)義，類似 \t 或 " 或是 \，JSON 轉(zhuǎn)義依據(jù) RFC 8259 規(guī)范，在去除 surrogate pair 編碼之后進(jìn)行轉(zhuǎn)義（Surrogate Pair 是UTF-16中用于擴(kuò)展字符而使用的編碼方式，是一種采用兩個(gè)UTF-16編碼（四個(gè)字節(jié)）來(lái)表示一個(gè)字符。），這是唯一允許在換行處將 - 值當(dāng)作 \n 的形式。

單引號(hào)則是獲取字面意義上的內(nèi)容，且不能在值中包含額外的單引號(hào)字符。

反引號(hào)（ ` ）同樣是獲取字面意義上的內(nèi)容，但要比單引號(hào)更加地靈活，以 ` 打頭后面跟上任意的 ASCII 字符，并且以相反的順序，在與相同配對(duì)符號(hào)首次出現(xiàn)的位置結(jié)束（有多少開(kāi)頭就需要多少配對(duì)的結(jié)尾），例如? `-foo-` 或者 ``bar``。在這些分別是 -` 和 `` 的示例中是不允許在其中使用最終配對(duì)順序的，在第二項(xiàng)示例中最后一個(gè)字符值同樣也不能是反引號(hào)。

在同一參數(shù)中混用引號(hào)，類似 'foo'"bar" 是不受支持的。

需要注意的是參數(shù)傳入以及屬性的展開(kāi)發(fā)生在不同的階段。首先，參數(shù)按如上所述被確定下來(lái)，并在此后適當(dāng)?shù)臅r(shí)機(jī)展開(kāi)屬性，無(wú)論參數(shù)是否被引號(hào)修飾。不過(guò)，以上展開(kāi)行為依舊可以被 raw 或 $> 前綴項(xiàng)阻止。參考 Input Command Prefixes 和 Property Expansion 兩小節(jié)內(nèi)容。

以下兩小節(jié)與 libmpv 客戶端 API 約定相關(guān)暫且略過(guò)，有相關(guān)需求請(qǐng)自行查閱原文，根本難不倒你（

Ch.20.5 Commands specified as arrays

Ch.20.6 Named arguments

Ch.20.7 輸入命令列表

對(duì)于帶有參數(shù)的命令，其參數(shù)名被放在 < / > 里面，真實(shí)命令中不要畫蛇添足?？蛇x參數(shù)被放在 [ / ] 當(dāng)中，如果不傳入這些參數(shù)，則設(shè)為默認(rèn)值。

在 input.conf 當(dāng)中，記得用引號(hào)將字符串參數(shù)括起來(lái)（參考 Flat command syntax）

ignore

用它來(lái)“堵住”那些不該被綁定的鍵位，并且不執(zhí)行任何操作。對(duì)于禁用默認(rèn)的鍵位綁定來(lái)說(shuō)非常管用，而無(wú)需使用 --no-input-default-bindings 來(lái)禁用所有的（默認(rèn)）綁定。

seek <target> [<flags>]

變更播放位置，默認(rèn)是按相對(duì)秒數(shù)進(jìn)行跳轉(zhuǎn)。

第二個(gè)參數(shù)是由控制跳轉(zhuǎn)模式的標(biāo)志構(gòu)成。

relative （默認(rèn)）

相對(duì)于當(dāng)前位置進(jìn)行跳轉(zhuǎn)（負(fù)值則向后跳轉(zhuǎn)）。

曲目：開(kāi)始 <--- （向后跳轉(zhuǎn)） 當(dāng)前位置 （向前跳轉(zhuǎn)） ---> 結(jié)束

absolute

按照給定的（絕對(duì)）時(shí)間進(jìn)行跳轉(zhuǎn)（負(fù)值則從文件結(jié)尾開(kāi)始反向跳轉(zhuǎn)）。

absolute-percent

按照給定時(shí)長(zhǎng)百分比的位置進(jìn)行跳轉(zhuǎn)。

relative-percent

相對(duì)于當(dāng)前位置按時(shí)長(zhǎng)百分比進(jìn)行跳轉(zhuǎn)。

keyframes

始終在關(guān)鍵幀邊界處重新開(kāi)始播放（速度快）。

exact

始終進(jìn)行精準(zhǔn)跳轉(zhuǎn)（速度慢）。

可以把多個(gè)標(biāo)志組合起來(lái)使用，例如：absolute+keyframes

默認(rèn)情況下，keyframes 用于 relative，relative-percent 以及 absolute-percent 跳轉(zhuǎn)，exact 用于 absolute 跳轉(zhuǎn)。

在 mpv 0.9 版本之前，keyframes 和 exact 只能作為第三個(gè)參數(shù)傳入（原先使用的是空格而非+）。雖然仍可作為第三個(gè)參數(shù)傳入，但是有被棄用的打算。

revert-seek [<flags>]

撤銷 seek 以及其他一些跳轉(zhuǎn)命令（但并非全部）。一旦調(diào)用此命令將跳轉(zhuǎn)至先前的播放位置。第二次調(diào)用撤銷 revert-seek 命令本身。僅在同一個(gè)文件內(nèi)有效。

首個(gè)參數(shù)可選，并且可以改變以下行為：

mark

標(biāo)記當(dāng)前時(shí)間位置，待下一次正常執(zhí)行 revert-seek 命令將會(huì)回退到該時(shí)間點(diǎn)，自那之后無(wú)論發(fā)生了多少次跳轉(zhuǎn)。

mark-permanent

如果設(shè)置了該標(biāo)志，則會(huì)標(biāo)記當(dāng)前位置，并且在下次執(zhí)行 revert-seek 命令之前，又設(shè)置了 mark 或 mark-permanent （或是播放到當(dāng)前文件結(jié)尾）也不會(huì)有所變動(dòng)。直到再次出現(xiàn) revert-seek 將始終跳轉(zhuǎn)到標(biāo)記點(diǎn)。此標(biāo)志無(wú)法與mark 共用。

不帶參數(shù)的使用則按默認(rèn)行為來(lái)執(zhí)行。

frame-step

播放下一幀畫面后暫停，僅播放音頻時(shí)無(wú)效果。

frame-back-step

播放上一幀畫面后暫停，請(qǐng)注意這個(gè)過(guò)程可能會(huì)非常慢（嘗試精準(zhǔn)跳轉(zhuǎn)，相對(duì)來(lái)說(shuō)不是很快），而且有時(shí)候無(wú)法按預(yù)期執(zhí)行。效果如何則取決于能否正確地執(zhí)行精準(zhǔn)跳轉(zhuǎn)（例如，參考 --hr-seek-demuxer-offset 選項(xiàng)說(shuō)明）。視頻濾鏡或者其他修改畫面幀時(shí)序（例如去隔行掃描）的視頻后處理（video post-processing）一般都能正常工作，但在極端情況下可能會(huì)使得反步追蹤行為靜默異常。使用 --hr-seek-framedrop=no 應(yīng)該會(huì)有點(diǎn)幫助，盡管這會(huì)讓精準(zhǔn)跳轉(zhuǎn)變得更慢。

僅播放音頻時(shí)無(wú)效果。

set <name> <value>

將給定的屬性或選項(xiàng)設(shè)成給定的數(shù)值。

add <name> [<value>]

將給定的數(shù)值添加到屬性或選項(xiàng)上。遇到上溢或下溢時(shí)，則固定為最大限度，如果略去 <value>，則假定為1。

cycle <name> [<value>]

循環(huán)給定的屬性或選項(xiàng)，第二個(gè)參數(shù)可以是 up 或者 down 用來(lái)設(shè)定循環(huán)趨勢(shì)。上溢則將屬性設(shè)回最小值，下溢則設(shè)為最大值。如果省去 up 或 down，則假定為 up。

默認(rèn)情況下是否允許長(zhǎng)按鍵入（key-repeat）取決于屬性。當(dāng)前，具有連續(xù)值的屬性（如音量之類的），默認(rèn)是可以長(zhǎng)按的，而離散值則不行（像 OSD 級(jí)別的屬性）

注：這里所說(shuō)的 key-repeat 是指短時(shí)間內(nèi)反復(fù)觸發(fā)按鍵輸入，即用戶長(zhǎng)按調(diào)節(jié)鍵位，相應(yīng)的屬性能否正常響應(yīng)這類輸入。音量、亮度、飽和度等諸如此類的屬性，數(shù)值具有連續(xù)性是支持長(zhǎng)按調(diào)節(jié)。而某些屬性雖然也是通過(guò)數(shù)值進(jìn)行調(diào)節(jié)，但是各數(shù)值之間無(wú)邏輯關(guān)聯(lián)，不具備連續(xù)性則不支持長(zhǎng)按調(diào)節(jié)。

multiply <name> <value>

與 add 類似，但是用（給定的）數(shù)值乘上屬性或選項(xiàng)。

screenshot <flags>

截屏

有以下多個(gè)標(biāo)志可用（一部分可以跟 + 組合起來(lái)使用）：

<subtitles> （默認(rèn)）

按照視頻畫面的原始分辨率，并且?guī)献帜槐４鏋閳D片。在某些情況下，部分視頻輸出還可能會(huì)包含 OSD 界面。

<video>

類似 subtitles，但通常不會(huì)帶上 OSD 或字幕，具體行為取決于選用的視頻輸出。

<window>

保存 mpv 整個(gè)窗口的內(nèi)容，通常是經(jīng)過(guò)縮放，帶有 OSD 和字幕。具體行為取決于選用的視頻輸出，并且如果輸出不支持，該標(biāo)志會(huì)表現(xiàn)得近似 video。

<each-frame>

每幀都截圖，再次發(fā)出這條命令后停止截屏。請(qǐng)注意當(dāng)你在使用這個(gè)模式的時(shí)候應(yīng)該禁用丟幀（frame-dropping）處理，或者在丟幀得情況下你可能會(huì)接收到重復(fù)得畫面。該標(biāo)志可以結(jié)合其他標(biāo)志一起使用，例如 video+each-frame。

較早的 mpv 版本需要傳入single 和 each-frame 作為第二個(gè)參數(shù)（并且無(wú)標(biāo)志），這個(gè)語(yǔ)法仍然可以被識(shí)別，但未來(lái)很可能會(huì)被棄用或是移除。

如果你是用 ; 將該命令與另外一條命令結(jié)合起來(lái)使用，那么你可以使用 async 標(biāo)志來(lái)讓編碼/寫入圖片文件異步進(jìn)行。對(duì)于一般的單獨(dú)命令來(lái)說(shuō)，始終是異步進(jìn)行的，并且（async）標(biāo)志無(wú)效果（該行為自 mpv 0.29.0 之后有所變更）。

screenshot-to-file <filename> <flags>

將截圖保存至指定的文件中，文件的格式將由擴(kuò)展名猜測(cè)得到（并且忽略 --screenshot-format，這個(gè)行為在擴(kuò)展名缺失或未知時(shí)是不確定的）。第二項(xiàng)參數(shù)與 screenshot 的首個(gè)參數(shù)類似，支持 subtitles, video, window。

如果文件已存在則會(huì)覆蓋寫入。

如同所有輸入命令參數(shù)，文件名同樣受到屬性擴(kuò)展的約束，正如 Property Expansion 小節(jié)所述的那樣。

playlist-next <flags>

轉(zhuǎn)到播放列表中的下一首。

首個(gè)參數(shù)傳入：

weak（默認(rèn)）

如果當(dāng)前播放的是列表中的最后一項(xiàng)，則不做任何操作。

force

如果播放列表中無(wú)更多文件項(xiàng)則終止播放。

playlist-prev <flags>

轉(zhuǎn)到播放列表中的上一首。

首個(gè)參數(shù)傳入：

weak（默認(rèn)）

如果當(dāng)前播放的是列表中的第一項(xiàng)，則不做任何操作。

force

如果正在播放的是首個(gè)文件項(xiàng)則終止播放。

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

按照給定的播放列表索引開(kāi)始（或重新）播放。除了從0開(kāi)始的播放列表?xiàng)l目索引之外，還支持以下參數(shù)值：

<current>

再次播放當(dāng)前播放列表的曲目（同 playlist-current-pos 所示），若是設(shè)為 none，則停止播放（在極端情況下，playlist-current-pos 可以指向播放列表?xiàng)l目，即使當(dāng)前播放的項(xiàng)目處于非活動(dòng)狀態(tài)）。

<none>

停止播放，若啟用了空閑模式（--idle），則播放器會(huì)進(jìn)入空閑狀態(tài)，否則退出。

這條命令類似 loadfile，因?yàn)樗粫?huì)操作接下來(lái)要播放內(nèi)容的狀態(tài)，而不會(huì)等到當(dāng)前文件被卸載之后才去加載下一項(xiàng)。

設(shè)置 playlist-pos 或類似屬性可以達(dá)到與這條命令近似的效果。然而，這項(xiàng)會(huì)更高效，并且保證會(huì)在例如新的播放列表項(xiàng)目與前一個(gè)播放列表相同時(shí)重新開(kāi)始播放。

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

加載并播放給定的文件或 URL，技術(shù)上來(lái)說(shuō)，這僅僅是一條播放列表操作命令（替換或向播放列表中添加新的項(xiàng)目），實(shí)際文件會(huì)被獨(dú)立地加載。例如，一條用于將當(dāng)前文件替換成新文件的 loadfile 命令會(huì)在當(dāng)前文件停止播放之前就返回，并且甚至新文件還在被加載中。

第二項(xiàng)參數(shù)傳入：

<replace> （默認(rèn)）

停止播放當(dāng)前文件，并且立刻播放新的文件。

<append>

追加文件至播放列表。

<append-play>

追加文件，并且當(dāng)前未播放任何內(nèi)容，則開(kāi)始播放（始終從添加的文件開(kāi)始播放，即使在執(zhí)行這條命令之前的播放列表并不為空）。

playlist-clear

除當(dāng)前正在播放的文件以外，清除播放列表。

playlist-remove <index>

移除播放列表中給定索引的曲目，索引值從0開(kāi)始計(jì)數(shù)。特殊值 current 移除當(dāng)前曲目，請(qǐng)注意移除當(dāng)前曲目的同時(shí)也會(huì)停止播放，并從下一項(xiàng)曲目開(kāi)始播放。

playlist-move <index1> <index2>

移動(dòng)播放列表中位于 index1 的曲目至 index2 曲目的位置（矛盾的是，如果 index1 小于 index2，那么被移動(dòng)的播放列表曲目在移動(dòng)之后的索引值不會(huì)是 index2，因?yàn)?index2 指向的是目標(biāo)曲目，而不是移動(dòng)之后曲目的索引）。

注：在這條命令中，曲目自身的索引值并不會(huì)隨著曲目在列表中排布順序的改變而改變，因此慎用這條命令，濫用會(huì)使你當(dāng)前播放列表中曲目的索引順序會(huì)變得混亂，某些依賴文件索引值的播放器腳本可能會(huì)出錯(cuò)。

playlist-shuffle

混洗播放列表，這條命令與在啟動(dòng)時(shí)用 --shuffle 選項(xiàng)所完成的行為相似。

playlist-unshuffle

嘗試還原先前的 playlist-shuffle 命令，僅會(huì)生效一次（多次連續(xù)的使用 playlist-shuffle 命令不會(huì)有任何效果）。如果在使用了 playlist-shuffle 命令之后，開(kāi)啟了新一輪循環(huán)列表則可能無(wú)法正確起到作用。

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

執(zhí)行給定的命令，不像 MPlayer/mplayer2 以及 mpv 早期版本（0.2.x 和更早的版本），這條命令不會(huì)調(diào)起 shell，而是直接執(zhí)行命令，每項(xiàng)參數(shù)被獨(dú)立地傳入，如同 Property Expansion 小節(jié)中所述的那樣展開(kāi)。

該命令有眾多參數(shù)，且不能夠和命名參數(shù)（類似 mpv 環(huán)境下的關(guān)鍵字，有特殊含義的參數(shù)名）一塊兒使用。

程序按照 detach 的方式運(yùn)行，mpv 不會(huì)等待命令執(zhí)行完成，而是在生成命令之后立即繼續(xù)播放。

若要獲得舊版行為，請(qǐng)使用 /bin/sh 和 -c 作為前兩個(gè)參數(shù)。

subprocess（粗略介紹，同樣是與腳本 API 相關(guān)，對(duì)普通用戶的用處不大）

與 run 命令類似，但是會(huì)給予調(diào)用者對(duì)進(jìn)程執(zhí)行更多的控制權(quán)，并且不會(huì)主動(dòng)分離進(jìn)程。

通過(guò)異步地執(zhí)行這條命令來(lái)避免阻塞，直到進(jìn)程結(jié)束。

該命令有以下命名參數(shù)，不保證它們的先后順序，因此你應(yīng)該始終用命名參數(shù)去調(diào)用，參考 Named arguments 小節(jié)。

點(diǎn)到為止……

quit [<code>]

退出播放器，如果給定了參數(shù)，則用它作為退出碼。

quit-watch-later [<code>]

退出播放器，并且保存當(dāng)前播放位置。稍后播放同一文件時(shí)會(huì)跳轉(zhuǎn)到先前位置處開(kāi)始。可選參數(shù)的作用和 quit 命令相同，見(jiàn) RESUMING PLAYBACK 小節(jié)。

sub-add <url> [<flags> [<title> [<lang>]]]

加載給定的字幕文件或字幕流。默認(rèn)情況下，加載后將作為當(dāng)前字幕。

flags 參數(shù)可以是下列的其中一項(xiàng)值：

<select>

立刻選中字幕（默認(rèn)）。

<auto>

不選為字幕（或者在某些特殊場(chǎng)景下，讓默認(rèn)的流選擇機(jī)制來(lái)決定）。

<cached>

選中字幕，如果具有相同文件名的字幕已被添加進(jìn)來(lái)，那么就選擇之前那個(gè)，而不是重復(fù)加載（在這種情況下，標(biāo)題/語(yǔ)言會(huì)被忽略掉，并且如果自加載之后上述內(nèi)容發(fā)生了改變，那么這些變動(dòng)是不會(huì)被響應(yīng)）。

title 參數(shù)被用來(lái)設(shè)置 UI 中字幕軌的標(biāo)題。

lang 參數(shù)被用來(lái)設(shè)置字幕軌的語(yǔ)言，并且還可以影響將 flags 設(shè)為 auto 的字幕流的選擇。

sub-remove [<id>]

移除給定的字幕軌，如果缺少 id 參數(shù)，則移除當(dāng)前的字幕軌（僅對(duì)外掛字幕起作用）。

sub-reload [<id>]

重新加載給定的字幕軌，如果缺少 id 參數(shù)，則重載當(dāng)前的字幕軌（進(jìn)隊(duì)外掛字幕起作用）。

該命令是通過(guò)卸載并重新添加字幕軌的方式運(yùn)作。

sub-step <skip> <flags>

更改字幕計(jì)時(shí)以便在下一個(gè) <skip> 字幕事件后能夠顯示字幕。<skip> 可以是負(fù)值以便逐步向后回退。

第二項(xiàng)參數(shù)傳入：

primary（默認(rèn)）

逐步瀏覽主字幕。

secondary

逐步瀏覽次級(jí)字幕。

sub-seek <skip> <flags>

跳轉(zhuǎn)至下一個(gè)（skip 設(shè)為 1）或上一個(gè)（skip 設(shè)為 -1）字幕。除了跳轉(zhuǎn)視頻和音頻而不是調(diào)整字幕延遲之外，這條命令與 sub-step 類似。

第二個(gè)參數(shù)傳入：

primary（默認(rèn)）

依次跳轉(zhuǎn)切換主字幕。

secondary

依次跳轉(zhuǎn)切換次級(jí)字幕。

對(duì)于內(nèi)嵌字幕（類似 Matroska 格式），僅適用于已顯示的字幕事件，或是預(yù)取范圍較短的字幕事件。

print-text <text>

打印文本至標(biāo)準(zhǔn)輸出，字符串參數(shù)中可以包含屬性（參考 Property Expansion 小節(jié)），注意要把參數(shù)用引號(hào)括起來(lái)。

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

顯示文本至 OSD，字符串參數(shù)中可以包含屬性，可以用來(lái)顯示顯示播放時(shí)長(zhǎng)，文件名等等。

<duration>

用來(lái)顯示以 ms 計(jì)算的時(shí)長(zhǎng)消息。默認(rèn)情況下與 --osd-duration 使用的是相同值。

<level>

用來(lái)顯示文本的最小 OSD 等級(jí)（參考 --osd-level）。

僅可用于客戶端 API 的命令，略過(guò)：

expand-text <string>

expand-path "<string>"

show-progress

在 OSD 上面顯示進(jìn)度條，文件已播放時(shí)長(zhǎng)與總時(shí)長(zhǎng)。

write-watch-later-config

效果和 quit-watch-later 命令類似，但是將恢復(fù)信息寫入配置文件后不會(huì)退出，繼續(xù)正常播放。

delete-watch-later-config [<filename>]

刪除任何由 quit-watch-later 或 write-watch-later-config 命令寫入的現(xiàn)存恢復(fù)配置文件。如果指定了文件名，則刪除對(duì)應(yīng)的配置文件；否則刪除當(dāng)前環(huán)境可能由 quit-watch-later 或 write-watch-later-config 寫入的相同文件。

stop [<flags>]

停止播放并清空播放列表。默認(rèn)設(shè)置下，基本與 quit 類似。對(duì)于客戶端 API 的作用是：可以在不關(guān)閉播放器的情況下停止播放。

首個(gè)參數(shù)可選，且支持以下標(biāo)志：

keep-playlist

保留播放列表。

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

發(fā)送一個(gè)帶有給定坐標(biāo)? (<x>, <y>) 的鼠標(biāo)事件。

第二個(gè)參數(shù)傳入：

<button>

點(diǎn)擊鼠標(biāo)按鈕的號(hào)碼，應(yīng)為 0~19 其中的一個(gè)，如果省去 <button>，僅會(huì)更新坐標(biāo)位置。

第三個(gè)參數(shù)傳入：

<single>（默認(rèn)）

鼠標(biāo)事件表示為常規(guī)的單擊。

<double>

鼠標(biāo)事件表示為雙擊。

keypress <name>

向 mpv 輸入句柄發(fā)送一條按鍵事件，觸發(fā)為該鍵位配置的任何行為。

name 使用的是 input.conf 當(dāng)中為鍵位和修飾符約定的命名方案。對(duì)于客戶端 API 的作用是：可以發(fā)送按鍵事件至 libmpv 內(nèi)部處理。

keydown <name>

類似 keypress，但是設(shè)置 KEYDOWN 標(biāo)志，以便如果按鍵被綁定到一個(gè)可反復(fù)觸發(fā)的命令時(shí)，則會(huì)按照 mpv 的按鍵重復(fù)次數(shù)反復(fù)執(zhí)行，直到調(diào)用 keyup 命令為止。

keyup [<name>]

設(shè)置 KEYUP 標(biāo)志的同時(shí)，終止任何已被觸發(fā)的反復(fù)鍵入行為。name 為可選參數(shù)，如果未給定 name 或?yàn)榭沾?，KEYUP 標(biāo)志將會(huì)被設(shè)置到所有的鍵位上。否則，KEYUP 標(biāo)志僅會(huì)設(shè)置在由 name 指定的鍵位上。

keybind <name> <command>

將按鍵綁定到一條輸入命令上，command 必須是一條包含所有期望被傳入的參數(shù)和標(biāo)志的完整命令。name 和 command 全部使用的是 input.conf 命名方案，主要是對(duì)客戶端 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>]]]]

加載給定的視頻文件，命令選項(xiàng)請(qǐng)參考 sub-add 命令。

albumart (MPV_FORMAT_FLAG)

若啟用，mpv 將會(huì)加載給定的視頻作為專輯藝術(shù)封面。

video-remove [<id>]

移除指定的視頻軌，參考 sub-remove 命令。

video-reload [<id>]

重新加載指定的視頻軌，參考 sub-reload 命令。

rescan-external-files [<mode>]

根據(jù)當(dāng)前的 --sub-auto，--audio-file-auto 以及 --cover-art-auto 的設(shè)定重新掃描外部文件。當(dāng)文件被加載后，這條命令可以被用來(lái)自動(dòng)加載外部文件。

mode 參數(shù)可以是以下中的一個(gè)：

<reselect>（默認(rèn)）

選擇默認(rèn)的音頻和字幕流，這通常會(huì)選擇具有最高優(yōu)先級(jí)偏好的外部文件（這部分的實(shí)現(xiàn)目前不算太好，并且可能會(huì)根據(jù)需要進(jìn)行改進(jìn)）。

<keep-selection>

不要改變當(dāng)前軌道的選擇。

Ch.20.8（后續(xù)）可能會(huì)改動(dòng)的輸入命令

af <operation> <value>

變更音頻濾鏡鏈，參考 vf 命令。

vf <operation> <value>

變更視頻濾鏡鏈。

語(yǔ)義同選項(xiàng)解析的內(nèi)容一致（參考 VIDEO FILTERS），因此，以下文字多為冗余且不完整的摘要說(shuō)明。

第一項(xiàng)參數(shù)決定要做什么：

<set>

用新的濾鏡鏈覆蓋先前項(xiàng)。

<add>

附加新的濾鏡鏈到先前項(xiàng)中去。

<toggle>

檢查給定的濾鏡是否已存在于視頻鏈中。如果是，則會(huì)刪除相應(yīng)的濾鏡，反之則會(huì)添加濾鏡（如果有多個(gè)濾鏡被傳到命令中，上述行為會(huì)逐一作用于每個(gè)濾鏡）。

一種特殊的變形是將其與標(biāo)簽相結(jié)合，并且使用不帶濾鏡名和參數(shù)的 @name 作為濾鏡項(xiàng)。這將會(huì)切換啟用/禁用標(biāo)志。

<remove>

類似 toggle，但始終會(huì)從視頻鏈中刪除指定的濾鏡。

<del>

從視頻鏈中刪除指定的濾鏡，與其他情況不同，第二項(xiàng)參數(shù)是以逗號(hào)為分隔的濾鏡名或整數(shù)索引。0 表示第一個(gè)濾鏡，負(fù)數(shù)索引表示從最后一個(gè)濾鏡開(kāi)始計(jì)算，即 -1 表示最后一個(gè)濾鏡。該參數(shù)已被棄用，請(qǐng)使用 remove。

<clr>

刪除所有的濾鏡，請(qǐng)注意，與其他子命令一樣無(wú)法操控被自動(dòng)插入的濾鏡。

以上參數(shù)始終都需要傳給 vf 命令，例如，假設(shè)要用到 clr 則使用 vf clr ""。

你可以通過(guò)在標(biāo)簽之前加上 @name:（其中 name 是用戶選擇的任意標(biāo)識(shí)符）。在所有的濾鏡鏈修改命令中，標(biāo)簽被可用在按名稱引用的濾鏡上。對(duì)于 add 參數(shù)，使用一個(gè)當(dāng)前在用的標(biāo)簽將替換現(xiàn)有的濾鏡。

在變更了濾鏡鏈之后，vf 命令會(huì)在 OSD 上展示請(qǐng)求濾鏡列表，效果大致相當(dāng)于 show-text ${vf}，請(qǐng)注意，自動(dòng)插入、用于格式轉(zhuǎn)換的濾鏡不會(huì)顯示在列表中，僅會(huì)顯示用戶請(qǐng)求的內(nèi)容。

通常，該命令會(huì)檢查視頻鏈?zhǔn)欠癖怀晒Φ刂匦聞?chuàng)建，并在失敗時(shí)撤銷操作。如果在配置視頻之前執(zhí)行命令（如果在打開(kāi)文件后和在解碼視頻幀之前立即執(zhí)行命令，則可能會(huì)發(fā)生這種情況），則無(wú)法進(jìn)行檢查，隨后可能會(huì)發(fā)生創(chuàng)建視頻鏈?zhǔn)〉那闆r。

如何在軟件運(yùn)行期間切換到被禁用的濾鏡的示例：

• 添加類似 vf-add=@deband:!gradfun 到 mpv.conf 當(dāng)中，其中 @deband: 為標(biāo)簽，是任意的、用戶為該濾鏡條目指定的名稱。位于濾鏡名之前的 ! 表示默認(rèn)禁用該濾鏡。在此之后的所有內(nèi)容都是一般的過(guò)濾器名稱，并且有可能是濾鏡參數(shù)，就像一般的 --vf 語(yǔ)法那樣。

• 向 input.conf 中添加 a vf toggle @deband，當(dāng) a 鍵位被按下時(shí)，這會(huì)切換那些帶有 deband 標(biāo)簽濾鏡的“禁用”標(biāo)志。

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

遍歷參數(shù)值列表，每次調(diào)用命令都會(huì)把給定的屬性（property）設(shè)為列表中的下一參數(shù)值。該命令使用屬性/選項(xiàng)的當(dāng)前值，用它來(lái)確定列表的當(dāng)前位置。一旦找到目標(biāo)值后將設(shè)置列表中的下一個(gè)參數(shù)值（如果有必要，則會(huì)繞回到第一項(xiàng)進(jìn)行設(shè)置）。

該命令具有可變數(shù)量的參數(shù)項(xiàng)，且不能與已命名參數(shù)一同使用。

特殊參數(shù) !reverse 可用于逆向循環(huán)參數(shù)值列表，優(yōu)點(diǎn)是當(dāng)添加了第二個(gè)用于反向循環(huán)的鍵位綁定時(shí)，無(wú)需自行反轉(zhuǎn)參數(shù)值列表。

enable-section <name> [<flags>]

該命令已被棄用，軟件內(nèi)部使用除外，啟用命名輸入段（Input Section）中的所有鍵位綁定。（略）

disable-section <name>

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

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

棄用，理由同上，創(chuàng)建一個(gè)命名輸入段，或替換一個(gè)已存在的命名輸入域中的內(nèi)容。（略）

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

添加一個(gè)來(lái)自原始數(shù)據(jù)的 OSD 覆蓋層（overlay），這對(duì)于操控 mpv 并且想要在視頻窗口頂部顯示內(nèi)容的腳本和應(yīng)用程序可能會(huì)很有用。

覆蓋層通常會(huì)按照屏幕分辨率顯示，但在一些視頻輸出（VO）中，分辨率會(huì)降低為視頻分辨率。你可以讀取 osd-width 和 osd-height 屬性（以獲取相關(guān)數(shù)值）。至少對(duì)于 --vo-xv 和寬銀幕視頻源（例如 DVD），同樣也應(yīng)該讀取 osd-par ，并且覆蓋層應(yīng)該支持視頻寬高比補(bǔ)償。

該命令擁有以下的命名參數(shù)，順序不作保證，所以你始終應(yīng)該以命名參數(shù)的方式來(lái)調(diào)用它們，參考 Named arguments 小節(jié)。

id 是一個(gè)介于 0 到 63 之間用來(lái)區(qū)分覆蓋層元素的整數(shù)，可被用來(lái)添加多個(gè)覆蓋部分，用該命令搭配一個(gè)已有 ID 來(lái)更新一個(gè)覆蓋部分，或著用 overlay-remove 來(lái)移除一個(gè)部分。使用先前未被使用過(guò)的 ID 將會(huì)添加一個(gè)新的覆蓋層，而重復(fù)使用一個(gè) ID 則會(huì)更新這個(gè)區(qū)域。

x 和 y 指定了 OSD 應(yīng)該被顯示的位置。

file 指定了從中讀取原始圖像數(shù)據(jù)的文件，它可以是一個(gè)帶 @ 前綴的 UNIX 文件描述符（例如 @4），又或者是文件名。在命令返回之前，文件將會(huì)用 mmap() 的方式被映射到內(nèi)存中，進(jìn)行復(fù)制操作，并在命令返回前unmap（在 0.18.1 版本進(jìn)行了調(diào)整）。

也可以通過(guò)傳入一個(gè)前綴是 & 字符的整數(shù)作為內(nèi)存地址，傳入這樣一個(gè)原始內(nèi)存地址用作位圖內(nèi)存，錯(cuò)誤的地址會(huì)導(dǎo)致播放器崩潰。這種模式也許適合搭配 libmpv 使用。offset 參數(shù)僅用于增加內(nèi)存地址（從 0.8.0 版本開(kāi)始生效，之前的版本則忽略）。

offset 是與源文件中首個(gè)像素點(diǎn)的字節(jié)偏移值（當(dāng)前的實(shí)現(xiàn)方式始終是從位置 0 開(kāi)始到圖像末尾mmap整個(gè)文件，所以應(yīng)該避免使用較大的偏移值，在 0.8.0 版本之前，偏移值實(shí)際上會(huì)直接傳給 mmap，但之后的調(diào)整使之更易于使用。）

fmt 是標(biāo)識(shí)圖像格式的字符串。當(dāng)前，僅定義了 bgra，這種格式規(guī)定了每個(gè)像素有 4 字節(jié)，各分量有 8 位，最低有效 8 位是藍(lán)色分量，最高有效8位是透明分量（在小端模式下，分量順序是 B-G-R-A，B 作為首字節(jié)）。這會(huì)使用預(yù)乘 alpha：每個(gè)顏色分量都已經(jīng)與 alpha 分量相乘。這意味著每個(gè)分量的數(shù)值都會(huì)小于或等于 alpha 分量。（違背這個(gè)規(guī)則將會(huì)導(dǎo)致不同的視頻輸出會(huì)得到不同的結(jié)果：因混用錯(cuò)誤的 alpha 值從而導(dǎo)致數(shù)值溢出被認(rèn)定是不該發(fā)生的情況，在這種情況下，軟件的實(shí)現(xiàn)無(wú)法確保得到的行為是可預(yù)測(cè)的，即未定義行為。）

w，h 和 stride 指定了覆蓋層的大小，w 是覆蓋層的可視寬度，而 stride 指定了內(nèi)存中以字節(jié)為單位的寬度值。在一個(gè)使用了 bgra 格式的簡(jiǎn)單示例中，stride==4*w，大多數(shù)情況下，可被訪問(wèn)的內(nèi)存總量為 stride * h。（從技術(shù)上來(lái)說(shuō)，最小應(yīng)該是 stride * (h - 1) + w * 4，但為了簡(jiǎn)單起見(jiàn)，播放器會(huì)訪問(wèn)全部的 stride * h 字節(jié)。）

注意：

在 0.18.0 版本之前，在更新覆蓋層時(shí)，你必須通過(guò)替換成不同的內(nèi)存緩沖區(qū)來(lái)手動(dòng)執(zhí)行“雙緩沖”。從 0.18.1 版本開(kāi)始，內(nèi)存僅僅是用于復(fù)制，并且在命令返回后不會(huì)引用命令參數(shù)所指向的任何內(nèi)存，如果你想要在 0.18.1 版本之前使用這個(gè)命令，請(qǐng)閱讀舊版本文檔以了解如何正確處理這類問(wèn)題。

overlay-remove <id>

移除由 overlay-add 命令添加且具有相同 ID 的覆蓋層。如果不存在該 ID 對(duì)應(yīng)的覆蓋層，則不執(zhí)行任何操作。

osd-overlay

添加/更新/移除一個(gè) OSD 覆蓋層。

（雖然聽(tīng)上去跟 overlay-add 比較像，但 osd-overlay 是面向文本覆蓋層，而 overlay-add 是面向位圖，或許將來(lái) overlay-add 會(huì)合并為 osd-overlay 以消除這種怪相。）

你可以使用這條命令添加 ASS 格式的文本區(qū)域。ASS 擁有高級(jí)的定位和渲染標(biāo)簽，可用于渲染幾乎是任何類型的矢量圖形。

該命令可接受以下參數(shù)：

id

指定覆蓋層的任意整數(shù)，通過(guò)帶上不同 id 參數(shù)來(lái)調(diào)用這條命令可以添加多個(gè)覆蓋層。帶相同 id 參數(shù)調(diào)用命名則會(huì)替換先前設(shè)定的覆蓋層。

每個(gè) libmpv 客戶端（即 IPC 連接、腳本）都有一個(gè)單獨(dú)的命名空間，因此 API 用戶可以（自行）創(chuàng)建和分配 ID 而不會(huì)與其他 API 用戶起沖突。

如果 libmpv 客戶端被銷毀，則與其關(guān)聯(lián)的所有覆蓋層也會(huì)被刪除。特別是通過(guò) --input-ipc-server 建立的連接，添加覆蓋層并再次斷開(kāi)連接將會(huì)立刻刪除覆蓋層。

format

指定覆蓋層類型的字符串，接受以下參數(shù)值：

注：這一段落的網(wǎng)頁(yè)渲染有問(wèn)題，導(dǎo)致以下4組參數(shù)的部分描述內(nèi)容對(duì)不上號(hào)，請(qǐng)酌情參考。

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

ass-events

提供2個(gè) ASS 樣式，OSD 包含有當(dāng)前 --osd-... 選項(xiàng)定義的文本樣式，默認(rèn)值比較類似，并且包含將所有選項(xiàng)都設(shè)為默認(rèn)值時(shí) OSD 所具有的樣式。

none

可導(dǎo)致覆蓋層被移除的特殊值。除 id 和 format 之外的大多數(shù)參數(shù)都會(huì)被忽略。

data

字符串參數(shù)，根據(jù) format 參數(shù)定義覆蓋層內(nèi)容，字符串使用換行符進(jìn)行分隔。每一行都會(huì)轉(zhuǎn)換為 Dialogue ASS 事件的 Text 部分。某些依賴 ASS 標(biāo)簽的行為可能會(huì)在未來(lái)的 mpv 版本中有所變動(dòng)。

注意，推薦將多行內(nèi)容放到 data 參數(shù)中，而不是添加到多個(gè) OSD 覆蓋層中。

res_x, res_y

如果 format 參數(shù)被設(shè)為 ass-events 則可以使用，可選，默認(rèn)為 0/720。此外，res_x 和 res_y 選項(xiàng)還指定了 ASS PlayResX 和 PlayResY 標(biāo)題字段的值，如果 res_y 被設(shè)為 0，那么 PlayResY 會(huì)被初始化成一個(gè)任意默認(rèn)值（但請(qǐng)注意該命令的 res_y 默認(rèn)是720，而不是0）。如果 res_x 被設(shè)為 0，PlayResX 基于 res_y 進(jìn)行設(shè)置以便虛擬 ASS 像素能夠具有方形像素的長(zhǎng)寬比。

z

覆蓋層 Z 軸順序，可選，默認(rèn)為 0

需注意處在不同格式的覆蓋層之間的 Z 軸順序是靜態(tài)的，并且無(wú)法被修改（當(dāng)前，這意味著由 overlay-add 添加的位圖覆蓋層始終會(huì)置于由 overlay-add 添加的 ASS 覆蓋層之上）。此外，內(nèi)置的 OSD 組件始終會(huì)處于任何自定義 OSD 之下。（涵蓋了任意類型的字幕以及由 show-text 渲染得到的文本。）

未來(lái)的 mpv 版本可能會(huì)隨機(jī)改動(dòng)不同 OSD 格式和內(nèi)置 OSD 之間 Z 軸順序的處理方式。

hidden

如果設(shè)為 true，則不顯示指定內(nèi)容（默認(rèn)：false）

compute_bounds

如果設(shè)為 true，將嘗試邊界并將其寫入到命令的結(jié)果值當(dāng)中，構(gòu)成 x0、x1、y0、y1 矩形（默認(rèn)：false）。如果矩形為空、未知或以某種方式退回，則不會(huì)進(jìn)行設(shè)置。x1/y1 為矩形底部頂點(diǎn)坐標(biāo)。

結(jié)果值可能取決于視頻輸出窗口大小，并且基于調(diào)用時(shí)最后一個(gè)已知的窗口大小。這意味著結(jié)果可能與實(shí)際渲染的結(jié)果不一致。

對(duì)于 ass-events，結(jié)果中的矩形會(huì)重新計(jì)算為 PlayRes 坐標(biāo)（res_x/res_y），如果窗口大小未知?jiǎng)t會(huì)選擇回退。

你應(yīng)該留意到這種機(jī)制是非常低效的，因?yàn)樗阡秩就暾慕Y(jié)果，隨后使用渲染位圖列表的邊界框（即使設(shè)置了隱藏），會(huì)刷新各類緩存。同時(shí)，最終結(jié)果還取決于所使用的 libass 版本。

該功能為實(shí)驗(yàn)性質(zhì)，并且可能還會(huì)進(jìn)行改動(dòng)。

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

向所有的客戶端發(fā)送一條消息，并向其中傳入后續(xù)的參數(shù)列表。消息的具體含義是什么？帶多少參數(shù)？以及參數(shù)的含義是什么完全取決于接收方和發(fā)送方（彼此之間的約定）。所有的客戶端都會(huì)接收到消息，因此請(qǐng)小心處置命名沖突的問(wèn)題（或者使用 script-message-to）。

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

與 script-message 一樣，但只會(huì)發(fā)送給 <target> 命名的客戶端。每個(gè)客戶端（例如腳本）都擁有一個(gè)唯一命名。舉個(gè)例子，Lua 腳本可以通過(guò) mp.get_script_name() 獲取到它們的名稱。請(qǐng)注意客戶端名稱僅允許包含英文字母、數(shù)字以及 _ 字符。

該命令擁有可變數(shù)量的參數(shù)，并且無(wú)法使用已命名的參數(shù)。

script-binding <name>

調(diào)用腳本提供的鍵位綁定，可用于重映射由外部 Lua 腳本提供的鍵位綁定關(guān)聯(lián)。

參數(shù)為綁定關(guān)聯(lián)的名稱。

可選用腳本名稱作為前綴，并使用 / 作為分隔符，例如 script-binding scriptname/bindingname ，請(qǐng)注意腳本名稱僅允許由英文字母、數(shù)字以及 _ 字符構(gòu)成。

為了完整起見(jiàn)，以下是該命令內(nèi)部的工作流程，細(xì)節(jié)內(nèi)容可能會(huì)隨時(shí)進(jìn)行改動(dòng)。在所有匹配到的按鍵事件中，會(huì)調(diào)用? script-message-to 或者 script-message（取決于是否包含腳本名稱），參數(shù)如下：

1. key-binding 字符串

2. 綁定名稱（如上所述）

3. 字符串形式的按鍵狀態(tài)（見(jiàn)下文）

4. 鍵位名稱（自 0.15.0 版本以后）

5. 按鍵生成的文本內(nèi)容，若不適用則為空字符串。

第5項(xiàng)參數(shù)僅在沒(méi)有修飾符的情況下設(shè)置（使用 shift 鍵位搭配上一個(gè)字母通常不會(huì)當(dāng)作包含了修飾符的形式，而是會(huì)產(chǎn)生大寫文本的結(jié)果，但某些后端可能會(huì)處理不當(dāng)）。

按鍵狀態(tài)包含以下2類特性：

1. 是 d（按下），u（已釋放/抬起），r（長(zhǎng)按，持續(xù)激發(fā)，需綁定支持），p （無(wú)法追蹤方向的按壓）其中的一種狀態(tài)。

2. 無(wú)論事件是源自鼠標(biāo)、m（鼠標(biāo)按鈕）還是 -（其他鍵位）。

未來(lái)的版本可能會(huì)添加更多參數(shù)和鍵位狀態(tài)的特性，以支持更多的輸入特性。

ab-loop

循環(huán)播放 A-B 點(diǎn)循環(huán)的狀態(tài)，首次調(diào)用會(huì)設(shè)置 A 點(diǎn)（等同 ab-loop-a 屬性），第二次是設(shè)置 B 點(diǎn)，第三次則清除兩點(diǎn)循環(huán)。

drop-buffers

丟棄音頻/視頻/解復(fù)用器緩沖，隨后重新讀取。對(duì)于不同步且不可搜索的媒體流可能會(huì)起到作用，未來(lái)可能會(huì)修改或移除這條命令。

screenshot-raw [<flags>]

返回內(nèi)存中的截屏內(nèi)容，僅可通過(guò)客戶端 API 使用。該命令返回的 MPV_FORMAT_NODE_MAP 包含 w，h，stride 字段且均設(shè)置為顯式內(nèi)容，format 字段默認(rèn)被設(shè)置為 bgr0 格式，按照 B8G8R8X8（B 表示 LSB）的形式組織。用 X 填充的內(nèi)容表示未定，data 字段是一類帶有實(shí)際圖像數(shù)據(jù)的 MPV_FORMAT_BYTE_ARRAY 類型。圖像也會(huì)緊隨 mpv_node 的結(jié)果被釋放后盡快地被釋放。與客戶端 API 語(yǔ)義一樣，不允許向其中寫入圖像數(shù)據(jù)。

stride 表示從 (x0, y0) 像素點(diǎn)到 (x0, y0 + 1) 像素點(diǎn)之間的字節(jié)數(shù)，如果圖像有被裁剪或填充的話，那么這個(gè)數(shù)值可能會(huì)大于 w * 4，該數(shù)值也可以為負(fù)值。你可以使用 byte_index = y * stride + x * 4 的方式存取一個(gè)像素點(diǎn)（假定是 bgr0 格式）。

flags 參數(shù)有點(diǎn)類似 screenshot 的第一項(xiàng)參數(shù)，并且支持 subtitles，video，window 等內(nèi)容。

vf-command <label> <command> <argument>

向?yàn)V鏡發(fā)送一條帶有給定 <label> 的命令，使用 all 則會(huì)一次性向所有的濾鏡發(fā)送命令，命令和參數(shù)字符串必須是濾鏡所指定的內(nèi)容。當(dāng)前，這條命令僅適用于 lavfi 濾鏡，請(qǐng)參閱 libavfilter 文檔以獲取濾鏡支持的命令。

請(qǐng)注意 <label> 是 mpv 的濾鏡標(biāo)簽，而不是 libavfilter 相關(guān)的濾鏡名稱。

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

與 vf-command 類似，不過(guò)是用于音頻濾鏡的。

apply-profile <name> [<mode>]

應(yīng)用一項(xiàng)已命名的配置描述的內(nèi)容，這類似于在配置文件中使用 profile=name，不一樣的地方是你可以將其映射成一個(gè)快捷鍵，在軟件運(yùn)行期間改變它的狀態(tài)。

mode 參數(shù)可以是：

default

應(yīng)用配置，省略參數(shù)時(shí)默認(rèn)采用。

restore

恢復(fù)由先前的 apply-profile 命令為這個(gè)配置描述所設(shè)置的選項(xiàng)。當(dāng)且僅當(dāng)配置描述通過(guò) profile-restore 設(shè)為相關(guān)模式時(shí)有效。如果無(wú)法執(zhí)行任何操作則會(huì)輸出警告信息，細(xì)節(jié)請(qǐng)參考 Runtime profiles 章節(jié)。

load-script <filename>

加載腳本，類似于 --script 選項(xiàng)。多次調(diào)用該命令是否會(huì)等待腳本完成初始化或不作變動(dòng)，以及將來(lái)的操作行為是未定義的。

成功的話，返回一個(gè)帶有 client_id 字段的 mpv_node，其中 client_id 設(shè)置為新創(chuàng)建腳本句柄 mpv_client_id() API 調(diào)用的返回值。

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

該命令會(huì)修改 List Options 章節(jié)中描述的列表選項(xiàng)，<name> 參數(shù)是普通的選項(xiàng)名稱，而 <operation> 是用于選項(xiàng)的后綴或行為。

部分操作不需要傳值，但在命令中仍需要給定 value 參數(shù)，在這些情況下，value 必須為空字符串。

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

將當(dāng)前的緩存內(nèi)容轉(zhuǎn)儲(chǔ)到給定的文件中，如果存在 <filename> 文件則會(huì)被覆蓋。<start> 和 <end> 給定了需要轉(zhuǎn)儲(chǔ)的時(shí)間范圍。如果在給定的時(shí)間范圍內(nèi)沒(méi)有緩存數(shù)據(jù)，則可能不會(huì)轉(zhuǎn)儲(chǔ)任何內(nèi)容（創(chuàng)建空文件）。

轉(zhuǎn)儲(chǔ)較大的緩存內(nèi)容會(huì)讓播放器卡住，由于無(wú)法避免這個(gè)問(wèn)題，因此這個(gè)功能主要用在創(chuàng)建小范圍的內(nèi)容摘錄。

有關(guān)適用于該命令的各種附加說(shuō)明請(qǐng)參考 --stream-record，因?yàn)閮烧叨际褂昧讼嗤牡讓哟a來(lái)寫入輸出文件。

如果 <filename> 是空字符串，則不會(huì)執(zhí)行 dump-cache 命令。

如果未提供 <end>，則會(huì)啟用持續(xù)轉(zhuǎn)儲(chǔ)。隨后在轉(zhuǎn)儲(chǔ)完已有的緩存內(nèi)容后，任何從網(wǎng)絡(luò)中讀取的內(nèi)容也會(huì)被添加到緩存中，這個(gè)行為類似于 --stream-record（盡管不會(huì)與之發(fā)生沖突，且兩者可以同時(shí)使用）。

如果 <end> 時(shí)間位于緩存之后，則不會(huì)等待并寫入新接收到的數(shù)據(jù)到緩存中。

生成的文件末尾可能會(huì)存在略有損壞或不完整的情況（無(wú)法保證文件末尾能夠正確對(duì)齊）。

請(qǐng)注意該命令僅在轉(zhuǎn)儲(chǔ)結(jié)束后才算完成，工作方式類似 screenshot 命令，只不過(guò)會(huì)阻塞更多時(shí)長(zhǎng)。如果使用了連續(xù)轉(zhuǎn)儲(chǔ)，則在停止播放、發(fā)生錯(cuò)誤、運(yùn)行另一個(gè)轉(zhuǎn)存命令，或調(diào)用類似 mp.abort_async_command API 顯式終止該命令之前，該命令是不會(huì)結(jié)束的。詳情見(jiàn) Synchronous vs. Asynchronous 章節(jié)。

注意

這條命令主要是為網(wǎng)絡(luò)數(shù)據(jù)流量身打造的。對(duì)于本地文件可能有更好的方法來(lái)創(chuàng)建摘錄內(nèi)容等。有許多對(duì)用戶更加友好的 Lua 腳本通過(guò)生成單獨(dú)的 ffmpeg 實(shí)例，來(lái)重新編碼文件中的某些部分。對(duì)于網(wǎng)絡(luò)數(shù)據(jù)流實(shí)現(xiàn)起來(lái)有一定的困難，因?yàn)樾枰匦孪螺d數(shù)據(jù)流的緣故。即使使用了 --stream-record 將數(shù)據(jù)流寫入到本地文件系統(tǒng)中，也可能存在某些問(wèn)題，因?yàn)橛脕?lái)記錄的文件仍然可以被（外部程序）寫入。

該命令仍處在實(shí)驗(yàn)性質(zhì)，并且所有有關(guān)它的細(xì)節(jié)內(nèi)容未來(lái)可能會(huì)進(jìn)行調(diào)整。

ab-loop-dump-cache <filename>

本質(zhì)上是調(diào)用把當(dāng)前 AB 循環(huán)點(diǎn)作為參數(shù)的 dump-cache 命令，像 dump-cache 那樣，該命令會(huì)覆寫以 <filename> 為命名的文件。同樣地，如果 B 點(diǎn)被設(shè)為 no 則會(huì)在現(xiàn)有緩存被轉(zhuǎn)儲(chǔ)后，繼續(xù)轉(zhuǎn)存后續(xù)的內(nèi)容。

將來(lái)視情況可能會(huì)刪除該命令。

ab-loop-align-cache

在 ab-loop-dump-cache 命令將要（或許要）轉(zhuǎn)存的緩存范圍內(nèi)，重新判定 A/B 循環(huán)的起止點(diǎn)?；旧蠒?huì)跟關(guān)鍵幀的時(shí)間點(diǎn)對(duì)齊。推測(cè)結(jié)果可能會(huì)存在偏離，尤其是在緩存末尾（原因是重新封裝導(dǎo)致的粒度問(wèn)題）。如果在此期間緩存出現(xiàn)縮小的情況，則該命令設(shè)置的起止點(diǎn)也不再是有效參數(shù)。

相比 ab-loop-dump-cache 命令，將來(lái)這條命令更有可能被刪除。

無(wú)正式文檔說(shuō)明的命令：ao-reload（實(shí)驗(yàn)性質(zhì)/僅內(nèi)部使用）

略過(guò) Ch.20.8.1 事件列表（List of events）、Ch.20.8.2 鉤子事件（Hooks）等有關(guān)客戶端 API 的章節(jié)

Ch.20.9 輸入命令前綴

這些前綴位于按鍵名和實(shí)際命令之間?？梢灾付ǘ鄠€(gè)前綴，彼此之間用空格隔開(kāi)。

osd-auto

使用該命令的默認(rèn)行為，這也是 input.conf 其中命令的默認(rèn)設(shè)置。但有一些 libmpv/scripting/IPC API 并不會(huì)將其作為默認(rèn)值，而是使用 no-osd 。

no-osd

不對(duì)該命令使用任何有關(guān) OSD 的行為。

osd-bar

如果可以的話，使用該命令會(huì)顯示一個(gè)條狀控件。跳轉(zhuǎn)命令將會(huì)顯示該進(jìn)度條，而屬性變更命令則可能會(huì)顯示新設(shè)置的屬性值。

osd-msg

如果可能的話，使用該命令會(huì)顯示一條 OSD 消息。跳轉(zhuǎn)命令會(huì)顯示當(dāng)前的播放時(shí)長(zhǎng)，而屬性變更命令則會(huì)以文本的形式顯示新設(shè)置的屬性值。

osd-msg-bar

組合使用 osd-bar 和 osd-msg

raw

不展開(kāi)字符串參數(shù)中的屬性（例如 "${property-name}"），這是部分 libmpv/scripting/IPC API 的默認(rèn)行為。

expand-properties

按照屬性擴(kuò)展中描述的那樣展開(kāi)全部的字符串參數(shù)，這是 input.conf 其中命令的默認(rèn)行為。

repeatable

對(duì)于某些命令，長(zhǎng)按鍵位并不會(huì)重復(fù)執(zhí)行該命令。這個(gè)前綴在任何情況下都會(huì)強(qiáng)制開(kāi)啟按鍵重復(fù)，對(duì)于一個(gè)命令列表來(lái)說(shuō)：首個(gè)命令決定了整個(gè)列表的可重復(fù)與否（直到且包括 0.33 版本在內(nèi)，命令列表始終具有可重復(fù)的特性）。

async

允許異步執(zhí)行（如果可行的話）。注意只有少數(shù)命令能夠支持這項(xiàng)特性，默認(rèn)情況下，某些命令本身已具備異步執(zhí)行的能力（或者更確切的說(shuō)，效果可能會(huì)在命令執(zhí)行結(jié)束后顯現(xiàn)出來(lái)）。該標(biāo)志的含義將來(lái)可能會(huì)做出更改。僅當(dāng)你不完全依賴這個(gè)命令的返回也能實(shí)現(xiàn)你想要的效果時(shí)才去使用。

sync

允許同步執(zhí)行（如果可以的話）。通常所有的命令默認(rèn)都是同步的，但也有些命令默認(rèn)是異步，以便兼容舊版本的行為。

所有的 osd 前綴仍會(huì)被全局的 --osd-level 設(shè)置所覆蓋。

略過(guò) Ch.20.10 同步vs異步（Synchronous vs. Asynchronous）、Ch.20.11 異步命令細(xì)節(jié)（Asynchronous command details）章節(jié)

Ch.20.12 輸入節(jié)段

作用是對(duì)一組綁定配置進(jìn)行分組，并且單獨(dú)啟用或禁用它們，在 input.conf 文件里面，每個(gè)按鍵綁定都會(huì)被分配到一個(gè)輸入節(jié)段，而不是實(shí)際由具體文字所表示的節(jié)段。

另見(jiàn)： enable-section 和? disable-section 命令。

預(yù)定義的綁定配置有：

default

沒(méi)有指定輸入節(jié)段的綁定配置將隱式分配到這個(gè)節(jié)段中，且在軟件正常播放期間默認(rèn)處于啟用狀態(tài)。

encode

在編碼模式下激活的節(jié)段，以獨(dú)占的方式開(kāi)啟，因此會(huì)忽略默認(rèn)節(jié)段中的綁定配置。

參考資料：

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

• https://mpv.io（mpv項(xiàng)目官網(wǎng)）