[mpv] 通过 JSON IPC 控制 mpv 播放器

1. mpv 的 JSON IPC 是什么

mpv 支持通过JSON IPC被外部程序控制。启用方式是启动 mpv 时指定--input-ipc-server：在 Linux / macOS / 其他 Unix 系统上，它会创建一个Unix domain socket；在 Windows 上则是named pipe。外部程序连接这个 IPC 端点后，就可以给 mpv 发送命令，也可以接收 mpv 推送的事件。

1.1 在 Linux 上

通过以下方式启动

mpv xxx.mp3 --input-ipc-server=/tmp/mpvsocket

使用 socat 来控制它

>echo'{ "command": ["get_property", "playback-time"] }'|socat - /tmp/mpvsocket

1.2 在 Windows 上

通过以下方式启动

mpv xxx.mp3 --input-ipc-server=\\.\pipe\mpvsocket

通过命令提示符发送命令

echo{"command":["get_property","playback-time"]}>\\.\pipe\mpvsocket

2. JSON IPC 的基本消息格式

客户端可以通过发送以下格式的 JSON 消息来对 mpv 执行命令：

{"command":["command_name","param1","param2",...]}

其中command_name是要执行的命令名称，后跟参数列表。参数必须采用原生 JSON 值格式（整数、字符串、布尔值等）。每条消息必须以\n结尾。 此外，\n不得出现在消息中的任何位置。

然后 mpv 将发送一个回复，指示命令是否正确运行，以及一个包含命令特定返回数据的附加字段（也可以为空）。

{"error":"success","data":null}

mpv 还会向客户端发送以下格式的 JSON 消息：

{"event":"event_name"}

其中event_name是事件名称。

由于事件可能随时发生，有时可能难以确定哪个响应与哪个命令对应。可以在命令中添加request_id字段（必须是整数），这样响应中会有同样的request_id。

例如，以下请求：

{"command":["get_property","time-pos"],"request_id":1}

会生成以下响应：

{"error":"success","data":1.468135,"request_id":1}

如果不指定request_id，命令回复会将其设置为 0。

3. 事件机制

JSON IPC 不只是“发命令-收回复”，它还支持事件推送。这意味着 mpv 可以在状态变化时主动给客户端发消息，而不是每次都要客户端轮询。

最典型的是属性订阅。比如订阅pause属性：

{"command":["observe_property",1,"pause"],"request_id":2}

其中：

• 1是观察 ID，由客户端自己指定
• "pause"是要监听的属性名

当pause发生变化时，mpv 会推送类似这样的事件：

{"event":"property-change","id":1,"name":"pause","data":true}

字段含义：

• event：事件类型，这里是property-change
• id：对应前面observe_property时给的观察 ID
• name：变化的属性名
• data：属性的新值。

如果不再需要监听，可以发送：

{"command":["unobserve_property",1],"request_id":3}

4. 使用 JSON IPC 控制 mpv 的典型流程

典型流程如下：

1. 启动 mpv，并开启 IPC：

   mpv xxx.mp3 --input-ipc-server=/tmp/mpvsock

2. 外部程序连接/tmp/mpvsock

3. 发送一条 JSON 命令，例如查询time-pos

4. 读取 mpv 返回的一行 JSON

5. 如有需要，发送observe_property订阅事件

6. 持续读取 socket，既处理命令响应，也处理异步事件。

在属性层面，官方文档说明playback-time是time-pos的别名；因此查询播放时间时，time-pos和playback-time都可用。

5. 常用命令例子

5.1 查询当前播放位置

{"command":["get_property","time-pos"],"request_id":1}

5.2 查询是否暂停

{"command":["get_property","pause"],"request_id":2}

5.3 切换暂停 / 播放

{"command":["cycle","pause"],"request_id":3}

5.4 设置暂停

{"command":["set_property","pause",true],"request_id":4}

5.5 恢复播放

{"command":["set_property","pause",false],"request_id":5}

5.6 相对快进 10 秒

{"command":["seek",10,"relative"],"request_id":6}

5.7 跳到第 60 秒

{"command":["seek",60,"absolute"],"request_id":7}

5.8 获取音量

{"command":["get_property","volume"],"request_id":8}

5.9 设置音量为50

{"command":["set_property","volume",50],"request_id":9}

5.10 订阅 pause 属性变化

{"command":["observe_property",1,"pause"],"request_id":10}

5.11 取消订阅

{"command":["unobserve_property",1],"request_id":11}

5.12 退出

{"command":["quit"],"request_id":12}

这些命令都基于 mpv 的命令/属性模型，经由 JSON IPC 以结构化 JSON 的方式发送。