mpv-Emo · 深度定制的 mpv 播放器配置

全网弹幕 · 在线中文字幕 · 内容自适应 AI 增强 · 360° 全景 · 可视化均衡器 · 统一右键菜单

uosc Dracula 主题主界面 · 十余个分类的全平台统一右键菜单

---

✨ 特性一览

🎯 内容自适应画质	按动画/真人 × SD/HD/4K × 帧率自动挂载 Anime4K / ArtCNN / FSRCNNX / SSimSuperRes 超分组，掉帧自动降档，HDR 与直播源自动避让
💬 全网弹幕	uosc_danmaku：弹幕搜索/自动加载/自动关联剧集，B 站与爱腾优源，overlay 高刷渲染
🔍 在线中文字幕	ASSRT 射手网 + Wyzie(TMDb) 双源搜索，AI 本地生成字幕（whisper），自动对时
🎛️ 可视化均衡器	10 段 EQ 图形化拖拽，14 种预设，配置持久化；与比特流直通模式互锁
🌐 360° 全景视频	mpv360 全套：等距柱状/双鱼眼/EAC 投影，键鼠自由视角
🖱️ 统一右键菜单	dyn_menu + uosc 深度定制，十余个分类全部带中文菜单注解，档位勾选态可视化
🎨 超分与插帧武器库	Anime4K 全集 / AnimeJaNai / CuNNy / FSRCNNX / ArtCNN / ravu / RIFE 补帧，右键按需加载
📺 HDR 双引擎	gpu-next 原生直通与 hdr-toys 着色器链双模式，SDR 内屏自动 tone-map
🔄 自更新器	manager.lua 第三方脚本/着色器检查更新，本地定制永不覆盖
🖥️ 三平台自检	deploy.py 部署自检与运行时准备，四态依赖报告

📷 更多截图

可视化均衡器	超分与补帧

中文增强 stats	全功能右键菜单

🚀 快速开始

# 1. 安装 mpv 0.41+（Arch: sudo pacman -S mpv）
git clone https://github.com/emoeem/mpv.git ~/.config/mpv

# 2. 依赖自检（自动报告缺失项与补建运行时目录）
python3 ~/.config/mpv/deploy.py --check

# 3. 字体：UI 字体 MFGA 因授权未定不入库，按 UI-FONTS.md 自行放置到 fonts/MFGA/
# 4. 播放任意视频，右键打开菜单即可使用全部功能

🎬 演示视频：录制中，敬请期待 —— 录制脚本见 tools/record-demo.sh

📚 详细文档

这是我的个人 mpv 配置仓库，主要面向 Linux / Wayland 桌面，使用 gpu-next + Vulkan 输出，并围绕高质量视频、HDR/SDR 色彩处理、字幕、播放列表、 历史记录和 uosc 操作界面进行定制。

当前配置的核心原则：

• 以 mpv.conf、input.conf 和 script-opts/ 为主要配置入口。
• 禁用 mpv 默认键位，使用仓库内可审计的自定义键位。
• 使用定制版 uosc，不直接用上游文件覆盖本地改动。
• 使用 profile 组织画质、色彩、HDR、着色器和场景模式。
• 运行时数据、缓存和第三方更新器的 Git 镜像不提交到仓库。

文档以当前工作区中的实际文件为准。修改配置后，快捷键和参数说明应再次以 input.conf、mpv.conf 与 script-opts/ 为最终依据。

目录

• 快速开始
• 目录结构
• 配置特点
• 画质与色彩 profile
• uosc 界面
• 脚本功能
• 快捷键
• 第三方更新器
• 三平台部署
• 依赖与注意事项
• Yaozhi 可移植性审计
• 更新记录

快速开始

依赖

建议使用带有以下能力的完整 mpv 构建：

• gpu-next
• Vulkan / Wayland 视频输出
• PipeWire 音频输出
• VapourSynth
• ytdl_hook
• yt-dlp

部分脚本还需要系统工具或外部运行时，例如 VapourSynth、Whisper、Trakt 访问令牌、浏览器 cookies 和桌面剪贴板工具。未使用对应功能时，可以不安装 相关依赖。

安装

如果目标目录还没有 mpv 配置，可以执行：

git clone https://github.com/emoeem/mpv.git ~/.config/mpv

如果目录已经存在，请先备份当前配置，再根据需要合并文件。此仓库包含个人 字体、ICC 文件、脚本和着色器，不建议直接覆盖另一个完整配置目录。

启动与检查

mpv --force-window=yes

运行时可使用 M 检查 manager.json 中配置的第三方来源。检查配置语法时， 可以执行：

git diff --check
luac -p scripts/uosc/main.lua \
  scripts/uosc/elements/Menu.lua \
  scripts/uosc/elements/Controls.lua \
  scripts/uosc/elements/Timeline.lua

目录结构

~/.config/mpv/
├── mpv.conf                         # 主配置：输出、解码、音频、字幕、截图和 profile
├── input.conf                       # 自定义快捷键与 uosc 菜单
├── inputevent_key.conf              # 单击、双击、长按等增强键位
├── profiles.conf                    # 游戏、电影、动画、HDR 等场景 profile
├── menu.conf                        # select.lua 菜单数据，目前由动态菜单接管
├── platform.conf                    # 平台分流：按 platform 属性注入 gpu-context / ao / hwdec
├── deploy.py                        # 三平台部署自检与运行时准备（纯标准库，Python 3.9+）
├── scripts/                         # Lua / JavaScript 播放脚本
├── script-opts/                     # 各脚本的配置
├── script-modules/                  # 脚本共用模块
├── shaders/                         # GLSL 缩放、锐化、去色带和 AI 着色器
├── vs/                              # VapourSynth 补帧、超分、降噪和去交错脚本
├── fonts/                           # OSD、字幕和 uosc 字体
├── audit/                           # 配置审计脚本（键位/文档/主题色，见 audit/README.md）
├── icc/                             # ICC 色彩配置文件
├── script-assets/                   # 起播格式徽标等资源
├── manager.json                     # 第三方来源与更新策略
├── .manager/                        # 更新器缓存和备份，已加入 gitignore
├── cache/                           # watch-later、着色器和 ICC 缓存，已忽略
├── files/                           # 播放历史、截图等运行时数据，已忽略
└── archive/                         # 已停用的历史配置备份

主要文件

文件	作用
mpv.conf	定义默认输出、解码、音频、字幕、截图、网络和 profile
input.conf	定义键位，并通过 #menu: 注释生成 uosc 菜单
profiles.conf	定义可手动启用的场景模式
platform.conf	按 mpv 的 platform 属性为 Linux / Windows / macOS 注入 gpu-context、ao、hwdec，三平台共用一份配置
deploy.py	三平台部署自检：四态检测、补建运行时目录、按需复制字重（只用标准库）
script-opts/uosc.conf	定义 uosc 控件、颜色、字体、时间轴和动画
manager.json	定义哪些第三方目录只检查，哪些目录允许整体替换
scripts/manager.lua	异步检查、比较、备份和更新第三方脚本 / 着色器
script-opts/	控制各个脚本的行为，避免把脚本参数硬编码在 Lua 中

配置特点

视频输出与硬件解码

mpv.conf 的默认视频链路为：

vo=gpu-next
gpu-context=waylandvk
hwdec=auto-safe
hwdec-codecs=all

这套设置适合 Wayland + Vulkan 环境。auto-safe 优先保证硬解兼容性， hwdec-codecs=all 允许全功能构建尝试更多编码格式。高负载的 8K、高帧率 内容会通过条件 profile 降低后处理或切换到音频同步，减少掉帧风险。

播放状态与历史

• idle=yes：没有文件或播放结束后保持 mpv 窗口运行。
• ontop：默认窗口置顶。
• save-position-on-quit=yes：退出时保存播放位置。
• watch-later-dir=~~/cache/watch_later：将 watch-later 状态放入缓存目录。
• resume-playback-check-mtime=yes：文件修改时间改变时避免错误恢复同名文件。
• save-watch-history=yes：将播放记录写入 files/watch_history.jsonl。
• reset-on-next-file=...：切换文件时重置音轨、字幕、滤镜、速度、色彩和画面变换。
• hr-seek=yes：默认启用精确跳转。
• hr-seek-framedrop=no：精确跳转时不主动丢帧，便于保持音视频同步和配合补帧。

OSD、字体与 Dracula

播放器 UI（OSD、uosc、stats、菜单等）统一使用 MFGA YouHei，详见 UI-FONTS.md；文本字幕自 2026-10-04 起也统一使用 MFGA YouHei。 Linux/libass 不做 emoji 字体回退，emoji 会显示为空白/方块。 当前主题是 Dracula：

用途	颜色
Foreground（文字）	#F8F8F2
深层背景（视频贴近层，派生）	#191A21
深层背景次级（派生）	#21222C
Background（菜单底）	#282A36
Selection / Surface	#343746
Current Line / Window border	#44475A
Comment（次要文字）	#6272A4
Purple（主强调：进度条、选中）	#BD93F9
Pink	#FF79C6
Green	#50FA7B
Red	#FF5555
Orange	#FFB86C
Cyan	#8BE9FD
Yellow	#F1FA8C

视频贴近层的 #191A21 / #21222C / #343746 是派生的更深层级色， 用于保持「背景 → 菜单 → 选中」的深度层次；主强调色为 Dracula 紫。

对应设置分布在：

• mpv.conf：osd-color、osd-back-color、字幕颜色和轮廓。
• script-opts/uosc.conf：uosc 控件、菜单、时间轴、选中状态和提示颜色。
• scripts/manager.lua：更新器底部进度条的独立颜色。

OSD 文本默认对齐左上（osd-align-x=left / osd-align-y=top，边距 16），而顶栏是 48 高的胶囊栏——第一行正好压在文件标题胶囊上，跳转反馈、截图提示和脚本消息都会 糊在标题上。mpv.conf 因此设 osd-margin-y=84（≈ top_bar_size × scale + 原边距）， 把顶部让出顶栏高度；osd-scale-by-window 会让它随窗口同比缩放。

原生 OSC 通过 osc=no 禁用，由定制版 uosc 提供播放控制界面。

音频

• ao=pipewire：Linux 下使用 PipeWire。
• audio-format=float：使用浮点格式处理音频。
• audio-channels=auto-safe：默认按安全方式选择输出声道。
• replaygain=album：优先使用专辑 ReplayGain。
• gapless-audio=weak：音乐模式下尽量无缝切歌，同时保留格式变化时的兼容性。
• audio-file-auto=fuzzy：从 audio/ 等目录自动查找匹配音轨。
• alang=japanese,jpn,jap,ja,jp,english,eng,en：日语优先，其次英语。

字幕

• sub-codepage=gb18030：兼容常见中文文本字幕编码。
• sub-auto=fuzzy：自动加载匹配的外挂字幕。
• sub-file-paths=sub:subs:subtitles:字幕：搜索多个字幕目录。
• slang=chs,sc,zh-Hans,zh-CN,cht,tc,zh-Hant,zh-HK,zh-TW,chi,zho,zh： 优先加载中文字幕。
• 默认字幕字体为 MFGA YouHei，字号为 34。
• 支持字幕重载、轨道切换、字幕同步、字幕导出、Whisper 生成字幕和字幕兼容性 开关，见字幕快捷键。

截图

默认截图为 WebP：

screenshot-format=webp
screenshot-webp-quality=85
screenshot-webp-compression=6
screenshot-tag-colorspace=yes

截图模板为：

~~/files/screen/%{media-title}-%P-%n

因此截图会保存在 files/screen/，同时保留正确的色彩空间标记。profiles.conf 中的 截图 profile 可以临时切换到高质量 PNG。

网络播放与 yt-dlp

• ytdl=yes：启用 mpv 的 URL 解析增强。
• 默认优先选择 2160p 以下视频并排除 VP9.2。
• 通过 cookies-from-browser=Firefox 读取 Firefox cookies。
• 在线格式的清晰度选择由 uosc 自带的流质量菜单提供（CTRL+F，候选见 script-opts/uosc.conf 的 stream_quality_options），在线媒体解析由 online-media.lua 承接。
• profiles.conf 中的 网络流 会在 demuxer-via-network=yes 时自动启用： 预读目标为 30 秒，前向缓存上限为 256 MiB，回退缓存上限为 32 MiB。
• 直播 是需要手动应用的低缓存、低延迟场景配置，不会被普通网络视频自动触发。

输入策略

input-default-bindings=no 会关闭 mpv 默认键位和脚本默认键位注册方案， 主要行为统一由 input.conf 显式定义。这样可以减少不同脚本之间的快捷键冲突， 也便于通过 uosc 菜单找到对应操作。

画质与色彩 profile

当前默认启用

mpv.conf 当前启用以下 profile：

profile=Target
profile=Dither
profile=HQ
profile=HDR2SDR

Profile	作用
Target	使用目标色彩空间链路，不自动套用系统 ICC
Dither	使用 fruit 抖动，降低量化色带且开销适中
HQ	EWA Lanczos Sharp、Catmull-Rom、抗振铃和 sigmoid upscaling
HDR2SDR	HDR 到 SDR 的动态峰值检测和 tone mapping

Target 与 ICC / ICC+ 是不同的色彩管理路径，不建议同时启用。

主配置中的可选 profile

Profile	用途
ICC	使用系统自动发现的 ICC 配置
ICC+	使用仓库中的 ICC 文件或手动指定的显示器 ICC
Dither+	Floyd-Steinberg 误差扩散，质量更高、开销更大
Tscale	display-resample + oversample 时域插值
Tscale+	display-resample + sphinx 时域插值
DeBand-low	轻度去色带
DeBand-medium	中等去色带
DeBand-high	强去色带
SDR2HDR	SDR 反向映射到 HDR，仅适合 HDR 显示设备
SWscaler	软件缩放器备用方案
NNEDI3 / NNEDI3+	高质量神经网络插值，后者开销更大
ravu-zoom	较轻量的通用放大
FSRCNNX / FSRCNNX+	HD 放大 / SD 去伪影变体
Ani4K / AniSD	动画和 SD 动画的高负载 ArtCNN 方案
Anime4K	KrigBilateral + Anime4K 修复、抗锯齿和高光限制
SSIM	适合 4K 或希望控制开销的场景

profiles.conf 场景模式

除 网络流 与 直播 会按网络媒体属性自动触发外（点播走 VOD 大缓冲，无时长的 直播流走低延迟档，两者按 duration 互斥），其余场景 profile 需要在启动参数或配置中 使用 --profile=<名称>；也可以通过快捷键动态应用部分着色器 profile， 右键 菜单 > 场景配置组（#@profiles 动态生成）可一键应用。

Profile	说明
游戏	低延迟、高性能，关闭插帧和去色带
电影	高质量、插帧、去色带和 HDR 映射
动画	动画专用 Anime4K 修复与去模糊
低功耗	关闭硬解并降低缩放和解码负载，适合排查性能问题
网络流	网络点播自动触发，使用 30 秒预读、256 MiB 前向缓存和网络超时设置
HDR画质	手动 HDR 画质预设：目标峰值、色域映射和 PixelClipper
截图	PNG 高质量截图和高质量缩放
直播	无时长网络流自动触发：低缓存、低延迟和流重连

内容自适应画质引擎（content-adaptive）

scripts/content-adaptive.lua 在每次加载文件时按 内容类型 × 分辨率 × 帧率 自动 挂载超分着色器组，与上面的手动配置组互补：

HDR 源（pq/hlg）      → 不挂超分，交给 HDR 处理链
直播流（网络+无时长）  → 不挂超分，性能优先
动画 SD               → FSRCNNX_distort + Krig
动画 HD               → Ani4K ArtCNN + Krig（掉帧降档 → Anime4K 轻量 → 仅 Krig）
真人 SD               → FSRCNNX_x2_8 + Krig
真人 HD               → SSimSuperRes + Krig（掉帧降档 → 仅 Krig）
4K                    → 仅 Krig，不做放大
源帧率 >47fps         → 跳过 FSRCNNX 类重组

• 内容类型按文件名/路径关键词判定（压制组词库在 script-opts/content_adaptive.conf）， CTRL+ALT+c 可手动三态覆盖（动画/真人/自动）。
• 手动改动着色器（CTRL+0~9 / ALT+1~8）时本文件内自动让位，下个文件恢复； uosc「超分与补帧」菜单（Emo > 超分与补帧）可切换 关闭/自动/性能/画质 四档并持久化。
• 手动着色器跨文件不残留（reset-on-next-file 含 glsl-shaders），每个文件由引擎 重新决策；AI 补帧档位仅记录意图（vs-mlrt 运行时未装，播放保持原生）。

自动条件 profile

以下 profile 由 mpv 属性或媒体参数自动触发：

Profile	触发目的
hdr-2390	使用 BT.2390 时调整 tone mapping 参数
SDR-gamut	对非 BT.709 SDR 内容使用 clip 色域映射
SDR-target	对普通 SDR 内容关闭不必要的目标色彩提示
HDR	识别 PQ / HLG 内容并设置 HDR 目标参数
HDR-PASS	HDR 显示设备满足条件时启用直通路径
video-sync	速度修正较大时切换到 display-tempo
fps-fix	高帧率视频改用音频同步，降低异常耗能
8k-fix	8K 级别视频关闭高负载后处理并降低掉帧风险
pgs-fix	修复超宽画面中 PGS 字幕的比例错位
pause	暂停时取消置顶
maximized	最大化时禁止自动调整窗口大小
minimized	最小化时自动暂停
end	播放结束后退出全屏和最大化
media-title	网络协议和磁链使用媒体标题作为窗口标题

HDR 峰值百分位不再由 auto profile 管理。它由 scripts/hdr-peak-percentile-guard.lua 在运行时按 video-params/avg-pq-y 在 99.8 与 99.995 之间切换，避免 auto profile 直接读取高速变化的动态 元数据而与脚本争抢同一属性，详见 mpv.conf 中的相关注释。

HDR 处理链双模式（hdr-toys）

默认是 native：保持上面的「原生 HDR 直通 + libplacebo 兜底」不变。按 ALT+H 可切到 toys，由 hdr-toys 的 OUTPUT 着色器接管 tone mapping 与色域映射，输出 SDR。

两种模式是替代关系，不能同时生效。切换与守护由 scripts/hdr-pipeline.lua 负责：

• 进入 toys 时快照 tone-mapping、gamut-mapping-mode、target-*、icc-*、 inverse-tone-mapping 等属性并接管，退出时按快照还原。
• toys 运行期间观察这些属性，把其他写入方改回的值纠正过来：input.conf 的 HDR 热键、uosc 的 target-peak 菜单、[HDR画质] / [电影] / [动画] 手动 profile，以及用 glsl-shaders= 整体替换列表的着色器 profile。
• scripts/linux-video-policy.lua 检测到 user-data/hdr-pipeline/active 时跳过 色彩策略，避免每次切文件都与 toys 对打；RIFE 准入不受影响。

覆盖范围与片源有关：

片源	链路
BT.2020 + PQ	clip_both → pq_inv → astra → bottosson → bt1886
BT.2020 + HLG	clip_both → hlg_inv → astra → bottosson → bt1886
BT.2020 + BT.1886	bt1886_inv → bottosson → bt1886
非 BT.2020（含 709 SDR）	自动回退原生链，并提示一次

bottosson 按 BT.709 目标硬编码、假定工作空间是 BT.2020，所以非 BT.2020 内容 不能套用同一条链；直接用上游配置里全局的 tone-mapping=clip 会让这类片源落入 「内置映射被关闭、toys 链又不匹配」的裸 clip 状态，因此这里选择回退而不是硬套。

本地对 shaders/hdr-toys/tone-mapping/astra.glsl 有一处补丁：上游 baseline b43e457 把 GLSL 保留字 packed 用作变量名，在 libplacebo 7.360.1 / GLSL 460 下会报 unexpected PACKED_TOK 并导致整个 compute pass 失败。 补丁只把该变量改名为 packed_bits。manager.json 中该来源是 check 模式， 升级前需要确认上游是否已修，否则要重新应用这处改名。

uosc 界面

当前定制版 uosc 位于 scripts/uosc/，版本标识为 5.13.0。它不是可以随意 整体替换的上游副本，原因是本地对菜单、时间轴、顶栏、鼠标行为、动画和颜色 有定制。

主要外观设置

来自 script-opts/uosc.conf：

设置	当前值	作用
top_bar	always	允许渲染顶栏；实际显隐仍由 autohide + 鼠标接近度决定
autohide	yes	播放中鼠标静止后，顶栏/底栏/时间轴一起淡出
timeline_style	segments	分段式圆角块时间轴（对齐 Mpv∞）
timeline_size	18	时间轴元素高度（segments 样式下条高约 13px）
timeline_persistency	paused	暂停时保持整个控制区展开（dock 主值来自时间轴，顶栏跟随）
timeline_media_info	auto	硬解/分辨率/HDR/编码/FPS/码率胶囊：跟时间轴显隐，可设 always/never
timeline_heatmap	overlay	热图以叠加层显示
chapter_display	yes	在时间轴显示章节标记和名称
controls_size	40	控制按钮尺寸
controls_margin	20	控制栏外边距
controls_persistency	idle	空闲时保留控制栏
menu_font	MFGA YouHei	菜单字体
menu_item_height	46	菜单项目高度
scale	1.30	界面缩放
font_scale	1.00	文字缩放
border_radius	10	控件和菜单圆角
pause_indicator	static	暂停时显示中央常驻圆形指示器（对齐 Mpv∞）
opacity.controls	0.5	按钮圆角底衬可见，形成胶囊观感
opacity.title	0.62	顶栏标题/章节胶囊底衬（亮画面上也看得见）
progress	windowed	窗口模式显示细进度条
progress_playing_only	yes	只在实际播放时显示细进度条
dock_animation	yes	启用底部 Dock 动画
dock_animation_mode	smooth	平滑 Dock 动画

界面风格对齐 Mpv∞（Android 播放器）：底栏控件带可见圆角底衬（胶囊观感）、 暂停时中央常驻指示器、右侧速度胶囊、时间轴用 Dracula 紫作进度强调色 （time_current=BD93F9，同时作用于时钟文字）。空闲态底栏用前后 space 居中并补齐统计入口，与播放态观感一致。窗口过窄时 uosc 会按 narrow 角色 自动丢弃低优先级按钮，属于响应式行为而非配置缺失。

信息分工（本轮确立）：

位置	职责
顶栏	文件名（超长 UTF-8 安全截断）→「第 N 章 · 标题」→ 引擎胶囊（原生/Toys，可点切换）→ 窗口按钮
时间轴	左端当前播放位置、右端总时长，是唯一的完整进度信息源
底栏	只放操作，不再重复显示 当前 / 剩余
技术信息	默认随底栏淡出；timeline_media_info=never 可完全关闭，改用 stats 面板

顶栏不再单独承载播放时间；章节胶囊在标题空间不足时优先让位， 先丢章节、再整颗隐藏，保证文件名可读。

想恢复底栏的 当前 / 剩余，在 script-opts/uosc.conf 的 controls 串里 加回 <video,audio>time 即可（TimeDisplay.lua 仍在，未删能力）。

控制栏

控制栏按「左排功能开关 · 中央播放控制 · 右排工具」分组：

• 左排：字幕（CC）、音轨、弹幕菜单、片头片尾跳过与标记、去黑边。
• 中央：时间显示、上一集、播放 / 暂停、下一集（stop 已从底栏移除， 保留在菜单与 SHIFT+F11）。
• 右排：截图、睡眠定时器、统计信息、播放列表、速度胶囊、更多菜单。
• 空闲状态：打开文件、最近播放、播放列表、统计信息、更多菜单，整组居中。

统计信息按钮是一个带状态的开关：面板开着时按钮变成紫底深图标（uosc 的 active 态），tooltip 变「关闭统计信息（Shift+I）」；再点一次关闭并恢复常态。 它读的是 stats.lua 写出的 user-data/mpv-emo/stats-visible，所以用键盘 I、右键菜单或任何脚本开关面板时，按钮高亮都会同步，不会出现「按钮亮着 但面板已经关了」。

时间轴右键绑定为 uosc/chapters，不会修改视频或片头片尾标记。 画面区域右键菜单（conditional-rightclick）会在空间允许时贴近鼠标 位置打开（menu-blurred-at 锚点）。 uosc 快捷键面板由 CTRL+ALT+u 打开，界面开关由 CTRL+ALT+SHIFT+u 控制。

脚本功能

界面、播放列表与文件

脚本	功能
uosc/	主播放界面、菜单、时间轴、顶栏、缩放和自定义按钮
stats-indicator.lua	观察 user-data/mpv-emo/stats-visible，把 stats 面板开关状态映射到 uosc 按钮高亮与 tooltip
uosc_danmaku/	弹幕搜索、加载、延迟、保存、源管理和弹幕样式菜单
thumbfast.lua	时间轴缩略图预览，两阶段显示（先附近关键帧，再精确画面）
playlistmanager.lua	播放列表浏览、排序、移动、保存、随机和网络标题解析
file-browser/	OSD 文件浏览器、目录缓存、收藏和多选
open_dialog.lua	调用原生文件选择器
command_palette.lua	命令面板
dyn_menu.lua / cycle-commands.lua	动态菜单和循环命令

历史、书签与状态

脚本	功能
simplehistory.lua	播放历史、隐身历史、恢复进度和最近播放菜单
recentmenu.lua	对历史菜单进行 uosc / select / 命令面板适配
simplebookmark.lua	文件书签和进度书签
history-bookmark.lua	历史与书签辅助功能
live-adaptive-quality.lua	Linux 直播缓存自适应画质：缓存不足逐级降档、稳定后恢复、限制切换频率
linux-video-policy.lua	Linux HDR/SDR 自动色彩策略 + RIFE 安全准入检测（依赖存在时才允许）
auto-save-state.lua	自动保存状态
episode-preferences.lua	在同一连续剧内临时保持音轨、字幕位置和播放倍速
persist_properties.lua	跨文件持久化指定属性
memo.lua	本地备注记录
undoredo.lua	跳转和循环跳转撤销 / 重做
sleep-timer.lua	睡眠定时器：到点退出、退出并保存进度或暂停，支持底栏徽标与暂停感知

字幕、章节与片段

脚本	功能
sub-select.lua	字幕选择
sub-assrt.lua	字幕下载菜单
sub-wyzie.lua	Wyzie 在线字幕搜索：文件名 → TMDb 匹配 → 下载挂载，需自行申请免费 API key
autosubsync/	字幕同步菜单和同步处理
sub-fastwhisper.lua	使用本地 Whisper 生成字幕
sub_export.lua	导出当前内封字幕
uosc-subtitle-lines.lua	在 uosc 中查看字幕行内容
mute-on-specific-subtitle-words.js	根据指定字幕词语切换静音
chapter-list.lua	章节列表
chapter-make-read.lua	创建、编辑、删除和写出章节文件
chapterskip.lua	静音跳转、章节跳过和片头片尾标记
mpv_chapters.js	JavaScript 章节列表
skip-segments.lua	标记、编辑和自动跳过片头片尾；在线片段来自 TheIntroDB v4（introdb_url），季集编号与媒体服务器的显示序不一致时用 introdb_mapping（official/dvd/absolute…，留空即 TVDB 存储序）

画面、音频和截图

脚本	功能
dynamic-crop.lua	检测并切除黑边，只对视频流工作；起播尺寸未就绪时自动重试
content-adaptive.lua	内容自适应画质引擎：按动画/真人 × SD/HD/4K × 帧率自动挂超分组，掉帧自动降档，手动让位，配置见 script-opts/content_adaptive.conf
hdr-mode.lua	HDR 模式辅助
hdr-pipeline.lua	HDR 处理链双模式：原生直通 / hdr-toys，含属性守护与片源回退
drcbox.lua	音频动态范围处理
equalizer-gui.lua	可视化 10 段均衡器（e 键 / 音频 菜单），14 种预设、配置持久化到 script-opts/equalizer-gui.json；与比特流直通互斥
mpv360.lua	360° 全景视频（视频 > 360°VR 菜单），配合 shaders/mpv360.glsl 与 script-opts/mpv360.conf；键位仅 VR 激活期间生效
music-mode.lua	音乐播放模式
stats.lua	中文增强统计信息
system-monitor.lua	系统监控 OSD：CPU/GPU 温度、功耗、内存、电池（对齐 Mpv∞ 的 Stats Page 6）
screenshot-to-clipboard.lua	截图并复制到剪贴板
mpv-animated.lua	动图截取与导出
pip.lua	画中画辅助
startup-format-logos.lua	起播时显示编码、音频、字幕等格式徽标

在线服务和远程控制

脚本	功能
uosc 流质量菜单	CTRL+F 选择在线视频清晰度（OpenSubtitles 下载也内置于 uosc 字幕菜单）
simple-mpv-webui/	提供浏览器控制界面，端口由 script-opts/webui.conf 决定
trakt-scrobble/	Trakt 搜索和播放记录同步
sponsorblock 相关脚本	跳过已标记的赞助商片段
trackselect.lua	按语言或元数据辅助选择音轨

画质增强资源

shaders/ 按用途收录多类 GLSL 资源，包括：

• Anime4K、Ani4K、AniSD、ArtCNN、ACNet、CuNNy（含 dp4a/ 量化版，着色器 > CuNNy 菜单免键开关）。
• mpv360.glsl：360° 全景投影重映射（equirect / 双鱼眼 / EAC 等），由 scripts/mpv360.lua 进入 VR 模式时 append、退出时 remove，菜单在 视频 > 360°VR。
• FSRCNNX、NNEDI3、RAVU、SSIM、AiUpscale。
• KrigBilateral、JointBilateral、色度升频和自适应锐化。
• SMAA、DLAA、CMAA、去色带、降噪、翻转、旋转、缩放和色温滤镜。
• ambient/ambient_glow.glsl：环境光晕，亮部提取 + 两级高斯 + 加性合成。
• hdr-toys/：HDR 到 SDR 的 transfer / tone-mapping / gamut-mapping 着色器（上游 MIT）， 由 ALT+H 的 toys 模式按片源类型选用，详见上文的双模式说明。

ambient_glow.glsl 用 ALT+a 以 change-list glsl-shaders toggle 开关，不要写成 profile：着色器配置组（[动画]、[AnimeJaNai] 等）用 glsl-shaders= 整体替换列表， 会把 append 的着色器冲掉，而 change-list 是独立的运行时开关。参数 STR=0 时 所有 pass 被 //!WHEN 跳过，只剩 1 个色阶的取整差异。

vs/ 收录 VapourSynth 处理链，包括：

• MEMC_*：RIFE、SVP、MVT 和 DRBA 补帧。
• SR_*：ACNet、ArtCNN 超分。
• NR_*：BM3D、CCD 降噪。
• ETC_DEINT_EX：去交错。
• MIX_UAI_*：AI 画质增强。

快捷键

快捷键定义在 input.conf。下表只记录当前启用的绑定；以大写字母书写的键名 表示需要按住 Shift，例如 A 与 a 是两个不同绑定。uosc 菜单中的项目 也来自 input.conf 行尾的 #menu: 注释。

为避免被 niri 的全局绑定截获，mpv 不直接使用 F2、F7–F11 和 CTRL+LEFT / CTRL+RIGHT；对应功能使用下表中的带修饰键组合。

打开、历史、书签与剪贴板

按键	功能
o	打开 uosc 内置文件浏览器
CTRL+o	打开原生文件浏览器
TAB	打开 OSD 文件浏览器并刷新
`	打开播放历史
ALT+l	切换隐身历史模式
CTRL+L	加载最后播放文件
CTRL+l	加载最后播放文件及进度
N	打开书签菜单
CTRL+n	添加进度书签
CTRL+N	添加文件书签
ALT+C	打开剪贴菜单
CTRL+c	复制文件路径和进度
CTRL+F	打开 / 关闭 yt-dlp 视频格式菜单
ALT+F	打开 / 关闭 yt-dlp 音频格式菜单
CTRL+ALT+h	打开近期播放菜单

文件、窗口与播放状态

按键	功能
SHIFT+F11	停止当前播放
ALT+t	切换窗口置顶
ALT+b	切换窗口最大化
ENTER	切换全屏
i	临时显示统计信息
I	常驻显示统计信息
l	设置或清除 A-B 片段循环
L	切换单文件循环
n	随机播放列表
[ / ]	播放速度减 0.1 / 加 0.1
{ / }	播放速度减半 / 加倍
BS	播放速度重置为 1.0
ALT+o	在文件管理器中定位当前文件
DEL	删除当前文件，并要求确认
b	最小化窗口
q	退出 mpv
Q	退出并保存 watch-later 状态

导航、章节与跳转

按键	功能
O	切换 OSD 时间轴
F4	打开综合 OSD 菜单
F5	打开播放列表
F6	打开音频设备列表
CTRL+F7	打开章节列表
CTRL+F8	打开轨道列表
CTRL+F9	打开视频轨列表
CTRL+F10	打开音频轨列表
CTRL+F11	打开字幕轨列表
ALT+c	标记章节时间
ALT+e	编辑当前章节标题
ALT+r	删除当前章节
ALT+w	写出 CHAPTER 文件
ALT+g	写出 OGM 章节文件
< / >	播放列表上一个 / 下一个文件
PGDWN / PGUP	上一章节 / 下一章节
F3	跳到下一个静音位置
ALT+q	切换章节跳过模式
ALT+n	标记片头或片尾
, / .	上一帧 / 下一帧
LEFT / RIGHT	后退 30 秒 / 前进 30 秒
SHIFT+LEFT / SHIFT+RIGHT	精确后退 / 前进 1 秒
SHIFT+DOWN / SHIFT+UP	精确后退 80 秒 / 前进 80 秒
CTRL+z / CTRL+x	撤销 / 重做跳转
CTRL+ALT+z	撤销循环跳转

画面、窗口缩放与色彩

按键	功能
A	循环切换 16:9、4:3、2.35:1 和默认宽高比
ALT+SHIFT+LEFT / ALT+SHIFT+RIGHT	左旋转 / 右旋转视频
CTRL+- / CTRL+=	缩小 / 放大窗口
ALT+- / ALT+=	缩小 / 放大视频画面
ALT+LEFT / ALT+RIGHT	向左 / 向右移动画面
ALT+UP / ALT+DOWN	向上 / 向下移动画面
ALT+p	切换裁切填充
ALT+BS	重置画面缩放、裁切、旋转、平移和宽高比
CTRL+I	切换 ICC 自动校色
1 / 2	对比度减 1 / 加 1
3 / 4	明度减 1 / 加 1
5 / 6	伽马减 1 / 加 1
7 / 8	饱和度减 1 / 加 1
- / =	色相减 1 / 加 1
CTRL+BS	重置对比度、明度、伽马、饱和度和色相
D	切换 deband
ALT+z / ALT+x	增加 / 降低 deband 强度
h	循环切换 HDR tone mapping 曲线
ALT+h	切换 HDR 动态峰值检测
CTRL+h	切换 HDR 直通提示
CTRL+t	循环切换显示器传输特性
CTRL+T	切换映射目标峰值 100 / 203
CTRL+g	切换色域映射模式
ALT+H	切换 HDR 处理链：原生直通 / hdr-toys

视频、截图与动图

按键	功能
ALT+i	切换插帧 / 抖动补偿
C	切换 dynamic-crop 去黑边
d	切换去交错
s	有字幕、无 OSD 的源尺寸单帧截图
S	无字幕、无 OSD 的源尺寸单帧截图
CTRL+s	有字幕、有 OSD 的窗口尺寸单帧截图
ALT+s	有字幕、无 OSD 的逐帧截图
ALT+S	无字幕、无 OSD 的逐帧截图
CTRL+S	有字幕、有 OSD 的窗口尺寸逐帧截图
c	标记片段剪切起止位置
a	切换剪切音频信息
CTRL+C	清除剪切标记
w / W	设置动图开始 / 结束时间
CTRL+w	导出无字幕动图
CTRL+W	导出带字幕动图

音频与音量

按键	功能
UP / DOWN	音量加 5 / 减 5
9 / 0	音量减 1 / 加 1
y	切换音轨
m	切换静音
CTRL+, / CTRL+.	音频延迟减 0.1 / 加 0.1
;	重置音频延迟
CTRL+y	切换音频独占模式
CTRL+Y	切换精确跳转丢帧同步模式
ALT+y	循环切换 7.1、5.1、立体声和自动声道模式
CTRL+F2	循环切换动态范围 / 响度滤镜
ALT+`	清空音频滤镜

字幕

按键	功能
j	切换主字幕轨
k	切换次字幕轨
v / ALT+V	切换主字幕 / 次字幕可见性
u	切换 ASS 字幕渲染样式
F	循环切换默认字幕字体
CTRL+r	重载当前字幕
ALT+R	切换次字幕样式覆盖
ALT+T	切换字幕与视频帧混合
K	切换字幕时序修复
J	切换 ASS 字幕颜色转换兼容
V	切换使用视频信息渲染字幕
ALT+B	切换 bidi 双向检测兼容
ALT+X	切换 ASS 阴影边框缩放覆盖
H	切换 ASS 字幕输出到黑边
ALT+Z	切换文本字幕输出到黑边
P	切换 PGS 字幕铺满屏幕
p	切换 PGS 字幕灰度转换
Y	切换字幕选择脚本
CTRL+f	使用 ASSRT 搜索字幕
ALT+F	使用 Wyzie 搜索字幕（需 API key）
CTRL+m	打开字幕同步菜单
CTRL+M	打开字幕内容菜单
ALT+m	导出当前内封字幕
ALT+f	使用 Whisper 生成 AI 字幕
r / t	主字幕上移 / 下移
R / T	次字幕上移 / 下移
z / x	主字幕延迟减 0.1 / 加 0.1
Z / X	次字幕延迟减 0.1 / 加 0.1
ALT+j / ALT+k	主字幕缩小 / 放大
CTRL+j / CTRL+k	跳转上一条 / 下一条字幕
SHIFT+BS	重置字幕位置、字号和延迟

视频滤镜

按键	功能
CTRL+`	清空视频滤镜
ALT+v	切换弱去色块滤镜
!	切换限定色域格式滤镜
@	垂直翻转
SHARP	水平翻转
$	旋转 180 度
%	Gamma 2.2 修正
^	强制 59.94 fps
*	填充 16:9 黑边并居中
&	6500K 色温修正
CTRL+ALT+f	循环切换风格滤镜预设：鲜艳 / 电影 / 夜览暖色 / 冷峻 / 深黑 / 关闭

风格预设用 set vf 整体替换滤镜链（互斥的单活跃语义），应用预设会清掉 vf toggle 加的个别滤镜，效果等同 CTRL+` 清空；也可在 uosc 菜单 「视频滤镜 > 风格预设」里逐个直达。

着色器

按键	着色器
CTRL+0	清空所有 GLSL 着色器
CTRL+1	KrigBilateral
CTRL+2	SSimSuperRes
CTRL+3	SSimDownscaler
CTRL+4	adaptive-sharpen
CTRL+5	FSRCNNX
CTRL+6	FSRCNNX distort
CTRL+7	NNEDI3 nns32 win8x4
CTRL+8	RAVU zoom
CTRL+9	Anime4K 抗锯齿
ALT+a	环境光晕（shaders/ambient/ambient_glow.glsl）

profile、命令面板与工具

按键	功能
CTRL+P	循环切换 FSRCNNX、FSRCNNX+、NNEDI3、ravu-zoom 和 Anime4K
ALT+1	应用 FSRCNNX
ALT+2	应用 FSRCNNX+
ALT+3	应用 ravu-zoom
ALT+4	应用 Ani4K
ALT+5	应用 AniSD
ALT+6	应用 Anime4K
ALT+7	应用 NNEDI3
ALT+8	应用 NNEDI3+
CTRL+B	切换标题栏
CTRL+R	切换播放下一个文件时重置的状态集合
~	打开 mpv 控制台
Ctrl+p	打开 Command Palette
CTRL+ALT+u	打开 uosc 快捷键面板
CTRL+ALT+SHIFT+u	显示 / 隐藏 uosc 界面
CTRL+ALT+t	复制当前时间
CTRL+ALT+s	复制当前字幕内容
M	检查并更新第三方脚本和着色器
CTRL+ALT+SHIFT+s	截图到剪贴板
CTRL+ALT+b	切换 SponsorBlock
CTRL+ALT+g	显示 / 隐藏 JavaScript 章节列表
CTRL+ALT+m	打开睡眠定时器菜单
CTRL+ALT+y	开 / 关系统监控面板（温度、功耗、内存、电池）

Trakt、弹幕和 Web 功能

按键	功能
ALT+d	打开 Trakt 搜索菜单
ALT+D	切换 Trakt 播放记录同步
CTRL+d	显示 / 隐藏弹幕
CTRL+D	打开弹幕综合菜单
CTRL+ALT+d	弹幕延迟加 1 秒
CTRL+ALT+a	弹幕延迟减 1 秒
_	立即保存当前弹幕
ALT+_	检查弹幕脚本更新

鼠标、媒体键和退出

按键	功能
MENU	开关 uosc 菜单
POWER	退出 mpv
PLAY / PAUSE / PLAYPAUSE	播放 / 暂停
STOP	退出 mpv
FORWARD / REWIND	前进 30 秒 / 后退 30 秒
NEXT / PREV	播放列表下一个 / 上一个文件
SPACE	播放 / 暂停
MBTN_LEFT	播放 / 暂停
MBTN_Right	开关 uosc 菜单
MBTN_FORWARD / MBTN_BACK	播放列表下一个 / 上一个文件
Wheel_Up / Wheel_Down	音量加 10 / 减 10
ESC	退出全屏并取消窗口最大化

第三方更新器

按 M 会运行 scripts/manager.lua，来源由根目录的 manager.json 管理。 更新器使用异步 Git 子进程，不阻塞 mpv 的播放和其他 Lua 脚本，并在 uosc / OSD 底部显示来源、阶段和总体进度。

来源策略

来源	目标目录	模式	说明
uosc	scripts/uosc	check	基于本地定制版 5.13.0，只检查上游
uosc_danmaku	scripts/uosc_danmaku	check	本地有弹幕适配和行为定制
trakt_scrobble	scripts/trakt-scrobble	check	本地配置可能包含服务适配
simple_mpv_webui	scripts/simple-mpv-webui	check	本地端口和页面有定制
cunny_shaders	shaders/CuNNy	check	菜单条目按文件名引用，上游新增/改名需同步 input.conf
mpv360	scripts/mpv360.lua	check	配套 shaders/mpv360.glsl 不随上游更新替换
equalizer_gui	scripts/equalizer-gui.lua	check	单文件脚本，本地不改实现
anime4k	shaders/Anime4K/glsl	replace	允许整体替换上游 GLSL 目录
file_browser	scripts/file-browser	replace	允许整体替换上游文件浏览器

check 与 replace

• check：获取上游分支并比较提交和目录树，只报告是否有更新，绝不覆盖本地目录。
• replace：确认上游目录树确实变化后，才暂存、备份和整体替换。
• 无变化时不更新、不创建备份、不改动目标目录。
• 已管理目录出现本地修改时，replace 会保护性跳过，避免覆盖本地文件。
• 旧版嵌套 .git 会移动到 .manager/backups/<name>/，不会参与目标目录复制。
• 每个来源使用 .manager/<name>.git bare mirror，并在 .manager/state.json 保存状态。
• mpv 退出时会中止仍在运行的更新子进程。

manager.json 中的 baseline 用于记录定制版本基于哪个上游版本或提交。 例如 uosc 当前 baseline 为 5.13.0；发现上游版本变化时，需要人工比较和合并 本地改动，再决定是否更新 baseline。不要把 .manager/ 缓存目录提交到仓库。

2026-08-29 已将 Yaozhi 8.29 便携包的 uosc、弹幕与共享脚本改动合并进本地 定制版，合并范围、保留的本地定制与跳过项见 CHANGELOG.md。 注意：本地 uosc_danmaku 在上游 Tony15246/uosc_danmaku（baseline d8c1cd8） 之上有本地重构（如 modules/resolver_affinity.lua，上游没有）。check 模式 永不覆盖本地，它只回答"上游是否前进"；上游有新提交时是否值得合并，需要人工 做三方合并判断，并且不能对该目录使用 replace 模式（会抹掉本地重构）。

添加来源时，建议先使用 check：

{
  "name": "unique_name",
  "url": "https://github.com/owner/project.git",
  "branch": "main",
  "source": "upstream/subdirectory",
  "destination": "scripts/project",
  "mode": "check",
  "baseline": "v1.0.0"
}

只有明确允许整体替换、且没有本地定制的目录，才使用 "mode": "replace"。

三平台部署

仓库的主目标是 Linux / Wayland。platform.conf 用 mpv 的 platform 属性把 gpu-context、ao、hwdec 分流给 Windows 与 macOS，所以三平台共用同一份 配置；但运行时依赖（Python venv、VapourSynth 插件、剪贴板工具、字体）必须 按平台各自准备。

deploy.py 是仓库自带的自检与准备脚本：只用 Python 标准库，要求 Python 3.9+， 检测结果分 available / degraded / unavailable / unverified 四态，不会 因为可选组件缺失就报错退出。

只有 Linux/Wayland 这台机器是实测过的。下面 Windows 与 macOS 的步骤是按配置 与脚本代码推导的部署流程，尚未在真机上跑过，标注为「待实测」。

命令

命令	作用
python3 deploy.py	默认 = --check --prepare：先检测，再补建缺失的运行时目录
python3 deploy.py --check	只检测，不写任何文件
python3 deploy.py --prepare	只创建缺失目录（已存在的跳过，可重复执行）
python3 deploy.py --fonts-dir PATH	显式指定用户字体目录（Windows / macOS 必用）
python3 deploy.py --skip-fonts	跳过字重复制（四字重齐全时 --prepare 默认会复制，fonts/MFGA/ 已进 .gitignore）
python3 deploy.py --json	机器可读输出，stdout 只有 JSON

cd ~/.config/mpv            # Windows: %APPDATA%\mpv
python3 deploy.py --check
python3 deploy.py --json | python3 -m json.tool | head -40

退出码只有两个：

• 0：关键依赖齐备，或仅存在降级 / 未验证项；
• 2：关键依赖缺失（mpv 不可用，或解释器低于 3.9）。

检测报告的四态

状态	含义	例子
available	有命令输出或文件事实确认可用	pactl info 里出现 PulseAudio (on PipeWire 1.6.10)
degraded	部分可用，会掉到兜底路径	会话是 Wayland 但只装了 xclip；vsmlrt 缺失导致补帧不可用
unavailable	明确缺失	PATH 里没有 mpv；用户字体目录里四个字重一个都没有
unverified	本机无法验证，不做结论	Windows 的 wasapi、macOS 的 coreaudio、真实硬解是否跑通

「列表里有」不等于「跑得通」：mpv --hwdec=help 列出的是编译进 mpv 的后端， nvidia-smi 只证明驱动在，两者都不证明某张片子真的硬解成功。脚本因此把 hwdec（后端列表）和 hwdec_runtime（运行时）拆成两项，后者恒为 unverified， 直到你在有窗口的会话里实测。

Linux（已实测）

# 1. 依赖（Arch 系示例，其他发行版换包名）
sudo pacman -S mpv yt-dlp git deno python wl-clipboard xclip zenity

# 2. 自检
cd ~/.config/mpv
python3 deploy.py

# 3. 起播
mpv --force-window=yes

本机结果：mpv v0.41.0 / gpu-next + waylandvk / PipeWire 1.6.10 / wl-copy + wl-paste 齐备；vsmlrt 缺失 → RIFE 补帧为 degraded。

Windows（待实测）

# 1. mpv：把 mpv.exe 放进 PATH，或在配置目录旁放 portable_config
mpv --version
mpv --hwdec=help        # 期望看到 d3d11va / dxva2，本机无法代你确认

# 2. Python 3.9+ 与 git
py -3 --version
git --version

# 3. 自检（配置目录通常是 %APPDATA%\mpv）
cd $env:APPDATA\mpv
py -3 deploy.py --check --fonts-dir "$env:LOCALAPPDATA\Microsoft\Windows\Fonts\MFGA"

# 4. 在线媒体 venv 必须用 Windows 解释器重建
py -3 -m venv online-media\runtime
online-media\runtime\Scripts\python.exe -m pip install -r online-media\requirements.txt

注意三点：

1. venv 的解释器是 Scripts\python.exe，不是 Linux 的 bin/python3； 仓库里现存的 online-media/runtime-manifest.json 声明 windows-x86_64， 与当前 Linux venv 不一致时 deploy.py 会报 degraded。
2. scripts/manager.lua 的 replace 模式在 Windows 上只按「安全检查」对待： 它会暂存、备份再整体替换目录，遇到本地修改会保护性跳过。真正会动文件， 想稳妥就在 manager.json 里把该来源改成 check（只比较、不覆盖）。
3. 剪贴板走 PowerShell Get-Clipboard / Set-Clipboard （script-modules/extended-menu.lua、scripts/uosc/lib/utils.lua）， 未在 Windows 上实测。

macOS（待实测）

brew install mpv yt-dlp git deno python
cd ~/.config/mpv
python3 deploy.py --check --fonts-dir ~/Library/Fonts/MFGA

# venv 用 macOS 的 bin/python3 重建
python3 -m venv online-media/runtime
online-media/runtime/bin/python3 -m pip install -r online-media/requirements.txt

macOS 侧只有 cocoa + VideoToolbox：platform.conf 的 [platform-macos] 不设 gpu-context（交给 mpv 自选），hwdec=videotoolbox,auto-copy-safe。剪贴板分支 是 pbcopy / pbpaste（extended-menu.lua）与 osascript （scripts/screenshot-to-clipboard.lua），同样未实测。

必装与可选依赖

类别	组件	缺失后果
必装	mpv（含 gpu-next）	播放器不可用，deploy.py 返回 2
必装	Python 3.9+	无法运行 deploy.py 与 online-media/*.py resolver
强烈建议	git	M 更新器（manager.lua）无法检查上游
强烈建议	yt-dlp	ytdl_hook 失效，网络播放只能靠直链
建议	deno	scripts/online-media.lua 无法给 yt-dlp 传 --js-runtimes deno:…，YouTube 解析易失败（mpv 自带 JS 引擎跑 scripts/*.js，不依赖 deno）
建议	wl-clipboard（Wayland）/ xclip（X11）	复制标题、截图进剪贴板失效
可选	zenity	scripts/open_dialog.lua 的文件/目录选择对话框不可用（X11/Wayland 授权框同理）
可选	VapourSynth + vsmlrt + TensorRT	RIFE 补帧与 AI 超分不可用（degraded）
可选	fc-match（fontconfig）	无法验证 MFGA YouHei 是否被真正解析

已知降级与不保证的能力

• 硬解：hwdec=nvdec-copy,vaapi-copy,auto-copy-safe 是候选链，mpv 会跳过不存在的 后端；某些编码/驱动组合仍会回落到软解，--hwdec=no 是排查手段。
• 补帧 / AI 超分：依赖 VapourSynth 插件与显卡后端，vsmlrt、TensorRT、模型文件 缺一不可，且要按显卡选后端（ncnn / ort_cuda / trt）。
• 剪贴板：三平台实现完全不同，Windows / macOS 分支未实测。
• 渲染上下文：Linux 配置写死 gpu-context=waylandvk；X11 会话下需要改成 x11vk 或删掉该行（platform.conf 注释里已写明）。
• Windows 的 manager.lua replace：只做安全检查与备份替换，不代表上游目录可以 无条件覆盖本地改动。

字体授权与打包

MFGA YouHei 字体模块不在本仓库内：整块模块约 237 MB，其中四个必需字重 （200.ttf / 300.ttf / 400.ttf / 700.ttf）合计约 126 MiB。

• 默认不复制、不入库：python3 deploy.py --prepare 只报告字体状态， 不会把字体写进工作区。
• python3 deploy.py --prepare 在检测到四个字重齐全时会复制到 fonts/MFGA/（该目录已进 .gitignore，不会被提交）；只想看状态就加 --skip-fonts。它会先确认四个字重 齐全，再逐个复制并按「已存在则跳过」处理；缺字重时整体跳过并报出缺哪几个。
• 本机字体不等于可再分发字体：复制前先确认授权，提交前确认 fonts/MFGA/ 不会被 git add 进去（.gitignore 只排除了 cache/、files/、.manager/ 等运行时数据， 没有忽略 fonts/MFGA/）。
• 用户字体目录里缺字重时，fontconfig 会把 MFGA YouHei 静默回退到任意可用字体， mpv 不报错——这正是需要自检脚本的原因。

运行时目录

deploy.py --prepare 只创建配置里确实引用的目录，已存在则跳过：

目录	依据
cache/	mpv 运行时缓存根目录
files/	播放历史、书签、截图等运行时数据
cache/shaders_cache/	mpv.conf gpu-shader-cache-dir
cache/icc_cache/	mpv.conf icc-cache-dir
files/screen/	mpv.conf screenshot-template=~~/files/screen/…

这些目录都在 .gitignore 里，创建它们不会污染提交。

依赖与注意事项

• vo=gpu-next 和 gpu-context=waylandvk 适用于 Wayland；在 X11 或 Windows 环境中需要调整 GPU context。
• hwdec=auto-safe 不能保证所有显卡驱动和编码格式都能硬解。遇到画面异常时， 可用 --hwdec=no 临时排查。
• dynamic-crop.lua 只处理视频流。播放音乐封面或单张图片时看到 only works for videos 属于预期行为。
• VapourSynth、Anime4K、NNEDI3、Ani4K 和 Whisper 等高负载功能会明显增加 GPU / CPU 使用率，建议按片源和设备性能选择。
• ytdl-raw-options-append=cookies-from-browser=Firefox 需要 Firefox cookies 可访问，并且不应把浏览器 cookies 文件复制进仓库。
• WebUI 会监听由 script-opts/webui.conf 指定的地址和端口。若监听在局域网 地址，应确认防火墙和访问权限。
• cache/、files/ 和 .manager/ 是运行时目录，已在 .gitignore 中排除。
• 字体、ICC、着色器和脚本属于配置的一部分，克隆后不要只复制 mpv.conf。
• 修改 uosc 时应优先手动比较上游变化；不要对当前定制目录直接执行上游整体覆盖。

相关链接

• mpv 官方手册
• uosc
• uosc_danmaku
• thumbfast
• InputEvent
• Dracula 调色板
• mpv-sub-assrt
• Anime4K
• mpv360
• Equalizer-GUI
• akFace/mpv.config（均衡器 / VR / CuNNy 借鉴来源）

许可

本仓库整体以 LGPL-3.0 发布（见 COPYING.LESSER）。 scripts/ 与 shaders/ 内的第三方组件保留其原始许可证（uosc GPL-3.0、Anime4K MIT/LGPL、 mpv360 MIT 等），使用与分发时请一并遵守。MFGA UI 字体因授权未定不随仓库分发。