0_FAQ
常见问题解答
ver.20240918
如无特别说明，以下的每个问答都是基于Windows单平台的情况。
懒人包即 mpv-lazy ，相当于新手包，但由于mpv的复杂特性它其实并没法让你做到懒，只能增加初始易用度，略微减少学习成本。使用前务必完整阅读《新快速说明》
如果你想打好mpv的使用基础，那我依然推荐阅读《win10/11 mpv播放器通用教程》。
这个项目的名字叫 MPV_lazy ，两者并不相同，只是当初起名没想那么多很随意的产物。mpv-lazy 只内置了少数 MPV_lazy 的组件。
在mpv多次迭代之后，默认设置的性能消耗有了显著提升（特别是对于低端机器）。我的懒人包的预设设置也不是省油的灯。
如果你没有特殊的需求，仅需在 mpv.conf 中添加以下参数回归旧版本的“高性能模式”（如果已有内容，请将其放置在一般参数的最后行，profile之前，以确保实际生效）
hwdec = auto
profile = fast如果你的硬盘很慢，可以考虑将本地视频缓存进内存，可以有效改进跳转（特别是帧步退）时的表现。编辑 mpv.conf
cache = yes
demuxer-max-bytes = 2048MiB
demuxer-max-back-bytes = 1048MiB # 也可以给个较高的前缓存量防止mpv过于积极的回收已播完的内容（如果你很需要往回跳的话）原生不支持。和其它CLI程序一样，几乎没有支持限制单窗口运行的。
需要在主设置文件中启用 --use-filedir-conf=yes （懒人包已默认启用）。
这可以处理一些特例文件需要的特殊参数的情况（常规情况下你并不需要），只在播放指定文件时应用，播放其它文件时恢复。
启用前置参数后，建立和目标文件名一致的conf，将其放置在 源文件旁 或 mpv.conf 所在目录下。
例如你需要仅对 test.mp4 使用参数
hue=-1，那就创建一个叫 test.mp4.conf 的文件（并填入目标参数后保存），放在上述的路径（二选一）。
类似于 “特定单个文件的设置” 。同样需要 --use-filedir-conf=yes （懒人包已默认启用）。
后续操作的区别是，建立一个额外的 mpv.conf 放在目标路径下。
例如你需要仅对
D:\Videos（不含子文件夹）中的所有视频使用参数hue=-1，那就在该路径创建一个叫 mpv.conf 的文件（并填入目标参数后保存）。
Note
“特定单个文件的设置” 的优先级要更高。
即先应用全局设置（主设置目录的mpv.conf），其次是全局设置内引用的设置文件 --include ，然后应用特定目录的设置，最后再应用特定文件的设置。
原版mpv使用内置脚本osc提供的名为bottombar的默认布局。
Important
此界面的元素和对应的操作按钮功能都可能随版本更新而不断变化，以官方说明为准 https://mpv.io/manual/master/#the-interface
mpv-lazy 当前使用uosc作为第三方的界面，详见 #186
通常不存在此问题，除非使用了参数 --hidpi-window-scale=no （mpv.conf）禁用了mpv的DPI缩放，使用它的原因是属性 window-scale 的缩放系数会受dpi的影响而变化，导致用户无法（在stats页面）正确快速判断窗口缩放系数。
不幸的是部分OSC类脚本通常依赖此属性进行缩放适配。因此你可以重新启用此选项以获得最佳缩放率。
当前懒人包使用uosc脚本作为界面，其自带的脚本选项 ui-scale 额外独立进行缩放控制（编辑 script-opts.conf ）。
mpv在有些平台支持 IME （多语言布局）
示例：假如在 input.conf 中你注册了这样的按键方案 ——
. show-text "test"
如果你此时正在使用中文输入法的中文模式，你可能会发现按下 . 无法触发其对应功能，那么有两种处理方式：
(1)切换到输入法的英文布局或英文模式；
(2)在 input.conf 中增加中文模式的对应“键位”，即
。 show-text "test"
可以简单的类比成directshow架构播放器里的“视频渲染器”选项。
--vo=gpu是当下几乎完美的选择，gpu-next的定位是继任者但尚未完善。
gpu-next 新增了很多功能（例如杜比视界的基本播放），一些gpu原有的功能表现也不完全一致，参见 #39
以下内容除非特别注明，都默认是在描述--vo=gpu下的特性。
-
--hwdec=no如果你有一个高端的CPU，可以无脑软解；
如果你的处理器一般但片源基本正常（例如没有经常播放极端的4k60这类“高清病毒”的需求），软解也是正常的选择。 -
--hwdec=yes/--hwdec=auto优先尝试纯硬解（原生硬解 native hwdec）。
纯硬解对大多数人来说都是高效省电的选项，但不支持大量的滤镜和部分mpv选项（例如--video-rotate在该条件下仅支持90度的整数倍）
hwdec=yes/hwdec=auto会按照内部列表依次尝试，这也有概率回退到xxx-copy的解码模式。 -
--hwdec=auto-copy弥补了纯硬解的不足，是相对的功耗均衡选项。
*-copy的解码方式意味着需要较强的内存显存带宽性能，尤其是当你尝试4k60fps这种非典型片源时。
Tip
通常不必指定到具体的解码api。不是所有的硬解码api都能正确渲染（例如 hwdec=dxva2 存在错误的RGB颜色转换）。
RTX显卡用户可以使用 hwdec=nvdec 或 hwdec=nvdec-copy 来实现硬解部分YUV444像素格式；
Caution
另一个超前选择（可能存在问题）是 hwdec=vulkan / hwdec=vulkan-copy ，它对标准化的编码h26x有极致的优化，另见官方说明（Intel与AMD显卡用户需要设置对应的环境变量） mpv#11739
hwdec=d3d12va-copy 未通过官方支持，但也可用。
Note
不同的图形api所能支持的解码模式是不同的，进一步参考下文的 “图形API的选择” 。
可以使用profile来灵活设置自动切换，来满足不同格式匹配不同解码模式的需求，示例（如果使用mpv-lazy，则最好在 profiles.conf 中补充）
[native_hwdec_auto]
profile-desc = 超过2k宽度的片源自动dx纯硬解
profile-cond = width>=2000
profile-restore = copy
hwdec = d3d11va推荐直接使用 --gpu-context 而不是 --gpu-api 来指定，因为同个 gpu-api 下可以存在多个 gpu-context
Windows系统下默认的 gpu-context=d3d11 通常是最高效的选项（但尚未支持 --hwdec=nvdec --hwdec=vulkan ，只能以 nvdec-copy vulkan-copy 的方式使用）
AMD显卡用户推荐尝试 gpu-context=winvk ，
Important
Vulkan下存在一些明显差异： --dither-depth=auto 并不能有效检测实际位深，只能手动指定； --ontop 会导致全屏时强制进入独占模式）
老旧平台或设备（此处特指系统或硬件没有d3d11的支持）可以首选尝试 gpu-context=win
如果遇到播放一个文件便在对应路径生成类似 mpv.20231104-115713-153.log 的日志文件。这并非 mpv 自身的日志。根据之前的反馈，大概率来自其它软件的智障隐式层（比如 Wegame 可检查
vulkaninfo ）。
解决方案： 系统环境变量添加 VK_LOADER_LAYERS_DISABLE=VK_LAYER_TENCENT_wegame_cross_overlay
如果画面加速播放（Display FPS尝试推到极限），音频正常——
在显卡驱动面板中给mpv单独设置垂直同步开启（如无特殊需求，不应修改全局垂直同步）
快速垂直同步不是传统垂直同步
G-Sync/Free-Sync 最好也一同单独（“监视器技术”项选择“固定刷新”）禁用（与 --video-sync=display-resample 的机制冲突）
如果仍存在问题，尝试进一步设置“首选刷新率”项为“最高可用”
如果发生在使用VS补帧时跳转时间轴——
使用--hr-seek-framedrop=no
如果使用--audio-exclusive=yes，可能存在切换音轨时触发此现象。
这会随着播放时长的增长而越发明显（手动跳转一次可以再次对齐，但治标不治本）。
常见的一种原因是：视频本身是 VFR（可变帧率），这很可能不兼容修改帧率类的滤镜。如果针对此类视频有补帧需求，当前只有svpflow和rife的倍帧模式能避免问题。
另一种常见原因，虽然视频是恒定帧率但滤镜插入修改了帧速率的某滤镜导致了帧率可变。当前只能建议不要使用该滤镜。
使用--d3d11-adapter设定对应显卡（如果使用--gpu-context=winvk则应使用--vulkan-device）
或者进 Windows设置-图形设置-图形性能首选项，建立mpv专项指定对应显卡。
编辑具体的vpy脚本，对于示例脚本，我通常在靠前的部分提供用户修改的选项。
如果是k7sfunc，则自行阅读文档中对应模块的参数
设定--input-ipc-server=mpvpipe。
如果它报错插件冲突，尝试移除mpv-lazy内的vapoursynth64文件夹
如果你想使用原版mpv（建议直接使用它自带的mpv即原版）
打开统计数据的第二页shift+i→2
部分着色器存在触发条件，未满足条件则不触发。
也可以从控制台`查看是否存在报错
单独配置 mpv 不使用此功能，参见上文的 “音画不同步” 部分。
可能是由 --video-sync=display-resample 引发。
通常原因是超高刷新率（大于144Hz）导致的帧间隔太低而渲染器不足以在此时间内渲染完成一帧，尝试降低高级设置项。如果仍然无法满足要求，则使用默认的 --video-sync=audio
可能是由文件的时间码错误而引发。 在 input.conf 中添加快捷键设置：
<key> cycle correct-pts可以在运行时临时启用它，对于其它正常文件应关闭此功能。
可能是解码或渲染性能不足导致，降低设置、滤镜、着色器...如果回归最低配置依然存在，大概率是硬件真的太弱。（无解）
常见于使用--gpu-context=d3d11时，此时应尝试--d3d11-flip=no
可能是hdr相关的参数激进导致，尝试调节下列选项（仅仅作为示例，并不是万金油的值）
hdr-peak-decay-rate = 100
hdr-scene-threshold-low = 5.5
hdr-scene-threshold-high = 10--vo=gpu 不支持dovi的正常渲染，改用 --vo=gpu-next 。
但是 gpu-next 存在大量功能差异，参见 #39
Important
此处仅表示转换为一般SDR播放。如需模拟HDR直出，参见下文的 “杜比视界模拟HDR直出”。
当前只推荐在 gpu-next 下使用，至少在 mpv.conf 中使用以下的参数
vo=gpu-next
target-colorspace-hint=yesTip
（可选）并追加如下配置预设（如果使用mpv-lazy，则最好在 profiles.conf 中补充）
[HDR-direct]
profile-cond=p["video-params/sig-peak"]>1 and p["video-params/gamma"]=="pq"
profile-restore=copy
target-trc=pq
target-peak=1000 # 目标峰值亮度应以你的显示器实际为准在不同图形API下的操作略不同，继续参见下文：
在 mpv.conf 中使用以下的参数
gpu-context=winvk理论上，它会自动在播放hdr片源时激活显示器hdr信号，在播放sdr时自动关闭。（可能存在sdr偏色的问题）
在 mpv.conf 中使用以下的参数
gpu-context=d3d11此时，需要你在播放hdr片源时手动开启win10的hdr功能（默认快捷键 Win+Alt+B），播放sdr片源时再手动关闭，比vulkan下麻烦但是大概率不存在偏色问题。
全屏独占参数
--d3d11-exclusive-fs=yes可能有效（假设原本无法触发hdr输出），也可能破坏渲染（假设原本已成功触发hdr输出）。
即如果一切正常就别加这参数添加不稳定因素，如果原本不正常就尝试该参数期待奇迹。
直通（透传 passthrough）是指交给显示设备处理映射，尽可能减少与避免mpv的相关处理。
目前已知如果源的当前帧亮度高于设定的 --target-peak ，mpv会介入处理。
Note
因此，如果你使用了上述的 （可选） 步骤，应移除掉 [HDR-direct] 这个profile中的 --target-peak 参数
此方法仅凭回忆记录，未验证。
在 --vo=gpu 和 --gpu-context=d3d11 的条件下，先启用系统HDR（默认快捷键 Win+Alt+B），然后打开mpv，加载hdr视频。
明显缺点：暂停时画面过曝，可能受显卡驱动影响而无法工作。无法在sdr和hdr片源间自如切换。
请先完整阅读 “观看HDR时不做SDR转换”（非旧版） 部分。
这只能在 gpu-next 下使用，在 mpv.conf 中使用以下的参数：
仅演示vulkan版，如果使用d3d11，仍需手动开关，此操作参考前文的 “d3d11的HDR直出”
vo=gpu-next
gpu-context=winvk
target-colorspace-hint=yes
##以下参数建议放进profile中处理
target-trc=pq
target-prim=bt.2020
target-peak=1000 # 由于内部限制，如不设置会自动为 203 （这极大压制了输出亮度），演示片类可能需要上调至 10000 来模拟透传Note
这里指的是mpv的原生功能
与Windows11的autoHDR 或 Nvidia的RTX HDR不兼容
请先完整阅读 “观看HDR时不做SDR转换” 部分。
这只能在 gpu-next 下使用，在 mpv.conf 中使用以下的参数：
（仅演示vulkan版，如果使用d3d11，仍需手动开关，此操作参考前文的 “d3d11的HDR直出”）
vo=gpu-next
gpu-context=winvk
target-colorspace-hint=yes
inverse-tone-mapping=yes
##以下四项，如果有sdr hdr不同片源的混合直出需求，建议放进profile中处理
target-trc=pq
target-prim=bt.2020
##以下两项酌情使用（影响效果）
#target-peak=1000
#tone-mapping=hable通常发生在ASS/SSA字幕上。
如果正确配置 sub-auto=fuzzy 且文件名合规的情况下，即使手动拖放字幕到窗口也无法加载，可能是字幕文件本身不合规。
- 一种可能是文本编码非 UTF-8
- header不正确，并非以
[Script Info]（区分大小写） 为开头
通常发生在ASS/SSA字幕上。
一种可能情况是字幕是针对16比9的原始帧设计制作的，而压制作品处理过程中裁切了帧内黑边导致的错位。
常用的解决方法是滤镜填充恢复原始帧比例，这里建议用 input.conf 快捷键方案临时启用
<key> vf toggle pad=aspect=16/9:x=-1:y=-1
通常仅发生在ASS/SSA字幕上。
原因可能是字幕制作不规范。
在 mpv.conf 中使用以下的一项参数
sub-ass-use-video-data = none
## 或者
sub-ass-use-video-data = aspect-ratioWarning
这会使部分字幕的边框阴影加粗，如果很在意这个缺陷，建议转 input.conf 制作运行时切换的方案。
此示例及产生的副作用参见 #310
Note
旧版本mpv使用该参数替代
sub-ass-vsfilter-blur-compat=no
另一种情况发生在源视频为非常规比例，而字幕制作时并不匹配。
... 
建议用 input.conf 快捷键方案临时禁用
<key> cycle-values sub-ass-use-video-data none allNote
旧版本mpv使用该方法替代
<key> cycle sub-ass-vsfilter-aspect-compat
通常仅发生在ASS/SSA字幕上。
如果--interpolation=no（禁用帧混成）无改善，则进一步使用--video-sync=audio，代价是judder的回归。
也可以使用--blend-subtitles=video，但此后就无法使字幕输出在黑边（即--sub-ass-force-margins=yes无效）
可以在input.conf（mpv-lazy则对应input_uosc.conf）中新增快捷键以供在运行时启用
<key> cycle-values sub-ass-override "yes" "strip"
mpv渲染ASS次字幕时默认剥离所有效果以类似SRT的方式渲染，在 mpv.conf 中更改此参数可使其的渲染行为贴合主字幕。
secondary-sub-ass-override=yesmpv默认将次字幕置于顶部输出，更改此参数可恢复预设位置。
secondary-sub-pos=100例如仓库内的 input_plus.lua 可以快速实现按键切换。
参考如下步骤操作即可 ——
mpv主程序所在路径打开终端，输入运行；
./mpv --audio-device=help
获取设备ID或全名后，在 mpv.conf 即可指定启动时使用的设备；
# 法一：使用ID
audio-device="wasapi/{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"
# 法二：使用名称（更推荐这种方式，因为ID可能由于驱动更新或其它因素发生变化）
audio-device="wasapi/SPDIF 接口 (SC203 Speaker)"或 input.conf 中在指定的多个设备间切换
<key> cycle-values audio-device "wasapi/{bddcc18d-3c9b-4884-abd2-ea5e8e94beb1}" "wasapi/{03ef5a21-304e-4ba8-85d6-808a16295234}"
当前仅处理立体声道有较为可行的方案，参见脚本 https://gist.github.com/hooke007/8bfe362a45ba20467de057b71fcc084c
具体表现为播放5.1声轨的片源声音很小。可以手动指定混成至立体声，mpv.conf中使用如下参数（mpv-lazy已默认启用）——
audio-channels=stereoImportant
此处不使用 --ad-lavc-downmix=yes （解码器下混），因为在解码端执行下混之后，mpv识别到的声道不再大于2，所以不会触发mpv的下混功能。
--ad-lavc-downmix 简单粗暴效果较差且不适用于所有音源，为确保更好的效果和始终执行所需的下混功能，因此这里采用mpv的下混。
通常发生在 “多声道音频的下混” 处理后，由于算法的缺陷可能使得人声的响度依旧偏低。
法一：
使用脚本 https://gist.github.com/hooke007/1ead3a9b9196d5de69e8d37add889efb
法二：
（存在问题，暂不要使用；但是如果你不使用 “多声道音频的下混” ，则可以正常生效）
最简单的处理方式为使用配置预设按条件使用如下的音频滤镜：（如果使用mpv-lazy，则最好在 profiles.conf 中补充）
[louder_speaking]
profile-cond=p["audio-params/channel-count"]>2
af-pre=@vocal:loudnorm
[louder_speaking-alt]
profile-cond=p["audio-params/channel-count"]<=2
af-remove=@vocalP.S. 其它音频增益类滤镜： loudnorm 不是唯一的选择，其它可用参考 https://github.com/mpv-player/mpv/issues/10767
如果文件本身无错误。可能是压制者使用了旧版的x264编码器。
使用 --vd-lavc-assume-old-x264=yes 可以解决这个问题，但是不建议常驻这个设置。
法一：推荐使用仓库中的 input_plus.lua 脚本，绑定快捷键来运行时切换解决。
<key> cycle vd-lavc-assume-old-x264 ; script-binding input_plus/trackV_refresh
法二：参考前文的 “特定单个文件的设置” 小节
mpv原版不提供这个功能。mpv-lazy使用脚本 save_global_props.lua 来指定退出前保存的属性，可编辑对应的脚本设置文件 save_global_props.conf 来指定你想要保存的属性。
--save-position-on-quit=yes并非你想象的保存播放器的状态，它只针对具体的每个文件分别存储属性，并在二次播放对应文件时应用；
--watch-later-options 保存的属性不应与 save_global_props 重合
一般视频看不出来？正常，首先人眼对亮度平面的敏感度远高于色度平面；其次，因为你没有特殊的母源作为参考。
chroma-444.png 当基准， chroma-420.jpg 是经过预处理的色度半采样成品，分别打开多个mpv空窗口，分别拖入进行对比。
按以下流程操作：
- 在 mpv.conf 中设置
image-display-duration=inf防止1秒读图后自动关闭 - 在 input.conf 中添加以下这行代码，就可以在运行时使用快捷键快速切换色度升频的算法，即时观看差异。
不嫌烦的话，也可以在运行时调出控制台console，输入例如
<key> cycle-values cscale "bilinear" "spline36" "sinc" "lanczos" "jinc" "bicubic" "catmull_rom"set cscale ewa_lanczos的命令手动切换某个算法
（当然也别忘了和高质量的色度升频着色器 KrigBilateral 作对比）
我的简单测试结果 —— 从左上到右下分别是：无损源，bilinear，catmull_rom，KrigBilateral
在这个案例下KrigBilateral几乎完美的还原了损失的色彩，但在实际影片中的绝大多数场景下，除了nearest外几乎很难感知差异。所以建议在资源有限的情况下不要浪费性能在--cscale上
Tip
这是极端特例，图中字母笔画只有1像素宽度，这是形成如此巨大反差的最大因素；
其次常规的视频已经是色度压缩后的产物，没有真“原始”画面作为参照。
在一般的视频画面帧中，几乎不存在上述案例中这种完美的情况，所以这并不具备符合现实场景的画质比较价值。
- 整体
graph LR
0[video<br>视频源] --> 1[lavfi-complex<br>复合滤镜] --> 2[vf<br>视频滤镜链] --> 3[shader<br>着色器系统]
对于上面三个大类来说，调用顺序是固定的，不因你的参数应用顺序发生改变。例如你在运行时先启用着色器，后开启滤镜，mpv始终先应用滤镜而后应用着色器。
因此在庞观上可用的优化手段仅有减少启用的功能分类，减少每个分类下使用的子项目数量。
- 细分
对vf来讲，其子项目的调用顺序由用户指定。
例如
--vf=vflip,scale=-2:720,vapoursynth="test.vpy"即先垂直翻转，再缩放，最后应用vs滤镜。
调用顺序的改变也影响效果的改变，在不影响结果的前提下，可以合并同类滤镜减少性能损耗。
例如
--vf=vapoursynth="test1.vpy",vapoursynth="test2.vpy"即如果你需要调用两次vs滤镜的不同脚本，建议手动合并两脚本实现只调用一次该滤镜--vf=vapoursynth="test3.vpy"。
这也是 k7sfunc 产生的初衷，详情参见对于文档 《vpy的设计与优化思路》
对shader来讲，这是个十分复杂的子流程（参见 《着色器处理阶段》）
内置着色器（例如最常见的 --scale ）它的应用顺序是始终固定的。
但用户着色器（参见 《第三方用户着色器》）的情况要复杂的多，单个着色器甚至可能会绑定到多个不同阶段。
以相对简单的着色器为例一，adaptive_sharpen（位于OUTPUT HOOK） adaptive_sharpen_luma（位于源HOOK LUMA）不因你的调用顺序改变应用顺序，
即使--glsl-shaders=adaptive_sharpen.glsl;adaptive_sharpen_luma.glsl也始终先运行 adaptive_sharpen_luma 而后 adaptive_sharpen
例二，对于作用于同一阶段的用户着色器，以你的调用顺序为准。
例如--glsl-shaders=Anime4K_Restore_CNN_L.glsl;Anime4K_Denoise_Bilateral_Mean.glsl即先应用 Anime4K_Restore_CNN_L 而后 Anime4K_Denoise_Bilateral_Mean