企业官网建设流程全解析

mpv 内置 Console 控制台完全指南：命令输入、补全、历史记录与外观配置

【免费下载链接】mpv🎥 Command line media player项目地址: https://gitcode.com/GitHub_Trending/mp/mpv

mpv 播放器内置了一个可在视频画面与终端间自由切换的控制台（Console）脚本，它把按键敲进的自由文本、命令自动补全、历史记录乃至多条目选择列表统一收纳在mp.inputAPI 之下，供commands.lua、select.lua等其它内置脚本复用。本文以官方手册 DOCS/man/console.rst 为主线，并结合实现源码 player/lua/console.lua 与配套的 SELECT 选择列表手册，完整讲解控制台的两种工作模式、全部按键定义、可配置选项及其底层行为，让你既能在日常操作中快速上手，也能在自定义 mpv 脚本时正确调用它。

1. Console 是什么：mpv 的文本输入中枢

从功能定位上看，Console 是 mpv 的一个内置 Lua 脚本，其职责是“把用户的文本输入交给其它脚本处理”，中间通过的桥梁就是mp.inputAPI。它有以下三个关键特征：

• 两处可显示的界面：既可以绘制在视频窗口的 OSD 上，也可以在无视频界面（如纯终端运行）时直接渲染到终端。实现中通过terminal_output()判断当前是否处于终端输出模式（依据current-vo与video-osd属性，见 console.lua）。
• 两种输入模式：处理自由格式文本（自由输入 + 命令补全），或让用户从预定义列表中选择条目。
• 可整体关闭：使用--load-console=no可完全禁用该脚本。该选项的默认值为yes，见 DOCS/man/options.rst。

在 mpv 自带的脚本体系中，Console 是“最底层的基础设施”：

• player/lua/commands.lua 是 Console 最常见的调用者，负责解析命令、维护命令历史并提供补全数据（它require "mp.input"并用input.get()弹出输入界面）。用户默认在 mpv 中按下`（反引号，即commands/openscript-binding）即可调出命令输入行，该键位定义见 etc/input.conf。
• player/lua/select.lua 是mp.input.selectAPI 的内置客户端，负责把轨道切换、章节跳转、播放列表项选择等操作格式化成一个可选条目列表并在 Console 中展示。其按键是 Console 基础按键的“扩展集”，详见后文。
• 各级g开头的选择类快捷键、右键上下文菜单（context_menu.lua）最终都在 Console 中以列表形式交互。

也就是说：你敲入命令时看到的是 Console，你按g切换字幕轨道弹出的列表，底层同样是 Console。

2. 快速上手：调出与关闭输入行

mpv 安装后默认只把`键绑定到commands/open（打开命令输入行）。在input.conf中把注释符号#去掉即可启用：

` script-binding commands/open

其它内置脚本也可以把console.lua注册的enablescript-binding 或直接发送script-message-to commands open来打开输入界面。此外，在 Console 打开期间，ESC 或 Ctrl+[会隐藏控制台，输入框内直接按Ctrl+D且当前行内容为空时也会关闭。

Console 会向上汇报自己的开关状态：

• 打开时设置属性user-data/mpv/console/open为true，关闭时恢复false（见 console.lua 与 console.lua）；
• 关闭（取消）时会向调用脚本发送closed回调事件，附带关闭时的行内容与光标位置，方便调用方在用户放弃输入后做善后处理。

3. 自由文本模式：完整的按键速查表

Console 的键位风格是“GUI 文本框常用键位 + readline 键位”的混合体（源码中的绑定表见 [console.lua](https://link.gitcode.com/i/35a5f71d2ad79c03bfae87b798287d63#L1691-L1767））。下表覆盖了自由文本模式（自由输入）下的全部按键行为，并标注了在代码中对应的处理逻辑：

3.1 提交与退出

源码细节：submit()在提交自由文本时会先把命令行追加进历史（history_add），若keep_open未开启则关闭控制台（见 console.lua）。

3.2 光标移动

在列表选择（含历史搜索）模式下，Ctrl+b/Ctrl+f会退化为“上/下翻一页”语义（page_up_or_prev_char/page_down_or_next_char），LEFT/RIGHT同理被pgup/pgdn接管。

3.3 删除与清行

3.4 历史记录导航

一个贴心细节：如果在浏览历史前你正在编辑一行尚未执行的文本，Console 会先把这行临时存入历史末尾，避免误按上下键导致内容丢失（见go_history中 console.lua）。

3.5 剪贴板、日志与显示

剪贴板在不同平台走不同实现：X11/Wayland 通过clipboard/text、clipboard/text-primary属性读取，Wayland 下必要时还会回退到外部wl-paste（见 console.lua）。而Ctrl+y的复制、粘贴在 mpv 新版中依赖update-clipboard命令与 player/clipboard 子系统。

4. 从列表中选择：mp.input.select模式

当脚本通过mp.input.selectAPI 提供一个条目列表时，Console 会切换为“选择模式”——在屏幕中央渲染一个带背景、滚动条、可点击的菜单，并将上述自由文本按键扩展为选择导航按键（详见 SELECT 选择列表手册）。

4.1 基础扩展按键

4.2 列表内的模糊筛选

在列表模式下，直接输入可打印字符会触发模糊搜索（fuzzy search）。搜索行为还有三条补充规则：

• 查询以'开头时切换为精确匹配；
• 精确匹配模式下可用空格分隔多个关键词，只有同时命中全部关键词的条目才会保留；
• 精确搜索是否区分大小写由配置项case_sensitive决定。

实现层面，模糊搜索基于内置的 player/lua/fzy.lua（mp.fzy）打分排序，精确模式则做子串定位并对命中字符着色（match_color）。一个值得注意的工程细节：当候选集非常大时（如数百上千条播放列表），过滤过程被放进协程分片执行——每片最长 0.005 秒、每次处理 1000 条后让出事件循环，保证打字不卡顿（见 console.lua）。此外在渲染 OSD 前，每个条目会被截断到安全长度并剔除换行，避免超长文本让 libass 卡死（console.lua）。

4.3 select.lua 提供的开箱即用选择

select.lua内置脚本为上述列表模式提供了一批现成的 script-binding，默认绑定在g开头的键位序列上，可用input.conf自由改绑：

在input.conf中，所有select/*绑定均可传可选参数keep-open，使菜单在选中一次后保持打开以便连续操作。手册给出的两个典型示例：

# 改绑：Ctrl+p 打开播放列表选择 Ctrl+p script-binding select/select-playlist # 保留打开：g-t 选择轨道后菜单不关闭 g-t script-binding select/select-track keep-open

历史与续看条目还常配合autocreate-playlist一起使用，示例：

g-h script-binding select/select-watch-history; no-osd set autocreate-playlist filter g-w script-binding select/select-watch-later; no-osd set autocreate-playlist filter

上述select.conf本身的配置（如历史条目日期格式history_date_format、是否隐藏同路径重复历史hide_history_duplicates、上下文菜单文件路径menu_conf_path等）均在 DOCS/man/select.rst 中有完整说明。

5. 命令历史与日志的底层行为

Console 内部把“输入会话”按id隔离：每个调用者（及其 prompt）拥有独立的history、log_buffers与待保存历史。命令历史会在每次提交时通过history_add()去重追加（相同条目只保留最新一次，取决于history_dedup配置，console.lua），并在 mpvshutdown事件中把新命令追加写入调用者指定的历史文件（console.lua）。

日志侧同样按会话缓冲，单会话上限为10000 行（MAX_LOG_LINES），超出时丢弃最早的行；Ctrl+l可手动清空。日志与输入行通过独立的ass-eventsOSD overlay 渲染（有可选列表时其 z 序提升到 2000 以覆盖 OSC），并每隔 0.05 秒合并一次渲染请求避免频繁重绘（console.lua）。

与 OSC 的协作：Console 会监听user-data/osc/margins，自动避开顶部/底部 OSC 占据的屏幕区域；宽高比也随osd-dimensions与display-hidpi-scale属性实时调整，因此窗口缩放时输入行不会错位（console.lua）。

6. 自动补全：网格对齐与模糊匹配

自由输入模式下，调用方（如commands.lua）会持续把“当前输入前缀”对应的候选列表发回 Console，并以等宽字体排版成网格展示在输入行上方：

• 网格列宽按font_hw_ratio（字高/字宽比）折算，候选较多时还会分页；
• 命中字符按match_color高亮，聚焦（已选中）的候选用focused_color/focused_back_color反色显示；
• 若窗口未聚焦，输入光标会自动淡出。

补全列表也做了模糊匹配：发送方给出一批候选后，Console 用fzy.filter_range按当前词打分排序（console.lua）；用户按Tab/Shift+Tab循环选择。若调用方声明autoselect_completion，则按Enter时会自动选取第一个候选。

一个小坑（源码注释也标明 TODO）：libass 渲染底边对齐文本时会两次扣除--osd-margin-x，所以osd-margin-x较大时，OSD 上每行能容纳的字符数估算会偏保守。

7. 配置文件与全部可配置选项

Console 的配置载体有两种：

1. mpv 用户目录下的script-opts/console.conf；
2. 命令行--script-opts=console-<key>=<value>选项。

两种方式的语法均遵循mp.options（见 DOCS/man/lua.rst 与 player/lua/options.lua）。注意mp.input的调用方可以在打开输入框时按选项逐项覆盖这些设置，而配置文件里声明过的默认值定义在源码顶部 console.lua。

下面是手册中全部可配置选项的整理（默认值已与源码逐项核对）：

一个典型的script-opts/console.conf示例：

# 示例：更大的输入字体 + 深色半透明菜单 + 显眼的命中色 font_size=28 background_alpha=120 focused_color=#FFFFFF focused_back_color=#E22 match_color=#FFCC00 history_dedup=yes

命令行等效写法：

mpv --script-opts=console-font_size=28 --script-opts=console-match_color=FFCC00 video.mkv

若要整体放弃该脚本，可传--load-console=no；若只是想放弃“命令输入”这一层（但保留 select/context-menu 等列表能力），则可单独关闭 commands 脚本--load-commands=no（两者默认为yes，见 DOCS/man/options.rst）。

8. 已知问题与注意事项

手册明确标注了以下两点已知限制，使用时应心中有数：

• 非 ASCII 键盘输入存在限制：虽然代码通过next_utf8/prev_utf8正确处理了 UTF-8 光标移动，并对剪贴板粘贴等做了平台适配，但非英文输入法（IME）的实时键盘流在部分平台/窗口系统下仍有兼容性瑕疵；
• 方向键按 Unicode 码点移动，而非按“字形簇”（grapheme cluster）移动：诸如组合字符（基字符 + 变音符号）、emoji ZWJ 序列会被当作多个码点逐个移动，光标步进粒度与“用户感知的字符”不完全一致。

此外可以推断的工程性限制还包括：终端模式下 Console 依赖osd_message与终端回显协作渲染光标反转效果，对终端宽度检测（term-size）有依赖；对历史上限文件格式为“每行一条命令”的纯文本。

9. 小结：Console 在 mpv 脚本生态中的位置

总结一句话：Console 是 mpv 面向用户的“输入层”实现，而commands.lua（命令）、select.lua（选择）、context_menu.lua（右键菜单）都是站在它之上的业务层。如果你想为自己写的 Lua/JavaScript 脚本提供交互输入，最佳做法不是复制这段按键处理逻辑，而是直接调用mp.inputAPI，让 Console 统一负责文本编辑、补全网格、模糊筛选、历史去重与 OSD/终端双端渲染。以上全部行为与选项的权威出处，可对照 DOCS/man/console.rst、DOCS/man/select.rst 与源码 player/lua/console.lua 三处交叉阅读。

【免费下载链接】mpv🎥 Command line media player项目地址: https://gitcode.com/GitHub_Trending/mp/mpv