mpv 命令行参数速查：从窗口控制到滤镜链的 9 大场景配置手册
【免费下载链接】mpv🎥 Command line media player项目地址: https://gitcode.com/GitHub_Trending/mp/mpv
mpv 选项动辄上百个，想把字幕字体、延迟、位置一次调到位，靠翻 man 页显然不现实。这份手册按你实际要干的活把 mpv 命令行参数切成 9 类，每条命令都能直接复制运行，配一张速查表，改完保存即生效。
快速上手：6 条最常用的命令
mpv --fs --ontop video.mp4 # 全屏播放并窗口置顶 mpv --geometry=100:100:800x600 video.mp4 # 在指定坐标以 800x600 打开窗口 mpv --hwdec=auto --volume=80 video.mp4 # 自动硬解并把音量设为 80 mpv --start=330 --end=900 --speed=1.25 video.mp4 # 从 5:30 播到 15:00，1.25 倍速 mpv --sub-font="Noto Sans" --sub-font-size=32 --sub-delay=0.5 video.mkv # 字幕字体、字号、延迟一次调好 mpv --loop=inf --shuffle music/ # 整目录随机循环播放参数体系一览：先认对类型再填值
| 类型 | 含义 | 典型参数举例 |
|---|---|---|
| bool | 是/否开关 | --fs、--ontop、--pause |
| int | 整数 | --volume=80、--vd-lavc-threads=4 |
| float | 浮点数 | --speed=1.25、--sub-scale=1.0 |
| string | 字符串 | --sub-font=Noto Sans、--audio-device |
| choice | 枚举值 | --video-sync=display-resample、--framedrop |
| geometry | 几何尺寸 | --geometry=100:100:800x600、--autofit=90%x90% |
| color | 颜色 | --sub-outline-color=0x000000 |
| time | 时间点/时长 | --start=330、--end=900 |
配置优先级从低到高依次为：内置默认值 < 系统配置 < 用户配置 < 命令行。
一句话：你在终端里敲的--参数，永远压过配置文件里写死的同名设置。
4.1 🎬 窗口与画面控制
本节覆盖：全屏、置顶、几何定位、自动适配窗口大小。
| 选项 | 类型 | 默认值 | 一句话说明 |
|---|---|---|---|
--fs | bool | no | 启动即全屏 |
--ontop | bool | no | 窗口置顶于所有窗口之上 |
--geometry | geometry | - | 指定窗口位置与尺寸 |
--autofit | geometry | - | 窗口自适应到给定尺寸 |
--autofit-larger | geometry | - | 仅限制窗口最大尺寸 |
--panscan | float | 0 | 裁剪黑边并放大画面 |
--window-scale | float | 1 | 按倍数缩放窗口 |
--keep-open | bool | no | 播放结束后不退出 |
mpv --fs video.mp4 # 直接进全屏 mpv --geometry=50%:50% video.mp4 # 窗口居中打开 mpv --autofit-larger=90%x90% video.mp4 # 窗口不超过屏幕 90% mpv --panscan=0.2 video.mp4 # 裁掉上下黑边再放大⚠️
--geometry的坐标与尺寸之间用冒号:分隔、尺寸内宽高校正用x小写，写错会直接报几何参数错误。--autofit与--autofit-larger语义相反：前者是"撑满到"，后者是"封顶到"。
4.2 ⚙️ 音画质量调优
本节覆盖：硬解、解码线程、去块、反交错与插帧。
| 选项 | 类型 | 默认值 | 一句话说明 |
|---|---|---|---|
--hwdec | choice | auto | 指定硬件解码后端 |
--hwdec-extra-frames | int | auto | 提高硬解缓冲区帧数防掉帧 |
--video-sync | choice | audio | 视频与显示刷新同步模式 |
--deinterlace | choice | no | 启用反交错 |
--deinterlace-field-parity | choice | auto | 反交错场序 |
--interpolation | bool | no | 帧间插值（需 GPU 解码上下文） |
--scale | choice | - | 缩放算法 |
--dscale | choice | - | 桌面缩放算法 |
mpv --hwdec=vaapi --vo=gpu video.mp4 # Linux 走 VA-API 硬解 mpv --hwdec=d3d11va --vo=gpu video.mp4 # Windows 走 D3D11VA 硬解 mpv --video-sync=display-resample video.mp4 # 锁定显示刷新率重采样 mpv --deinterlace --interpolation video.mkv # 老片源反交错 + 插帧⚠️ 硬解后端与渲染上下文是绑定关系：
--hwdec=vaapi需要--vo=gpu或--vo=dmabuf-wayland，--hwdec=vulkan则必须--vo=gpu-next。选错组合时 mpv 会静默回退软解，终端里会打一条 "hwdec failed" 提示，别以为硬解没生效。
4.3 字幕全链路
本节覆盖：轨道选择、字体字号、位置、延迟、编码与边框样式。
| 选项 | 类型 | 默认值 | 一句话说明 |
|---|---|---|---|
--sid | choice | auto | 指定字幕轨道 ID |
--sub-auto | choice | fuzzy | 自动外挂字幕匹配方式 |
--sub-font | string | - | 字幕字体名 |
--sub-font-size | float | 5.0 | 字号（相对比例） |
--sub-pos | float | 100 | 字幕垂直位置，越小越靠上 |
--sub-delay | float | 0 | 字幕延迟（秒） |
--sub-codepage | string | auto | 非 UTF-8 字幕的编码 |
--sub-border-size | float | 2 | 描边/边框粗细 |
mpv --sid=2 video.mkv # 指定第 2 条字幕轨 mpv --sub-font="Noto Sans" --sub-font-size=32 video.mkv # 字体与字号 mpv --sub-delay=0.5 --sub-pos=85 video.mkv # 延迟 0.5s、位置略降 mpv --sub-codepage=cp1252 video.mkv # 修复 Windows 外挂字幕乱码 mpv --sub-auto=fuzzy --slang=en,zh video.mkv # 自动外挂 + 中英文字幕⚠️
--sub-codepage前加+强制重编码（如+cp1252），否则 mpv 只在检测到非法 UTF-8 时才转换；--sub-pos取值 0-150，超过 100 会把字幕推到屏幕顶部以外。
4.4 播放流管理
本节覆盖：循环、倍速、起点终点、A-B 区间与播放列表。
| 选项 | 类型 | 默认值 | 一句话说明 |
|---|---|---|---|
--loop | choice | 1 | 当前文件循环次数，inf无限 |
--loop-file | choice | 1 | 同--loop的旧别名 |
--loop-playlist | choice | no | 整个播放列表循环 |
--speed | float | 1 | 播放倍速 |
--start | time | 0 | 从指定时间点开始 |
--end | time | - | 到指定时间点停止 |
--shuffle | bool | no | 随机化播放顺序 |
--playlist-start | int | 1 | 从列表第 N 项开始 |
mpv --loop=inf music/ # 整目录无限循环 mpv --start=330 --end=900 video.mp4 # 只播 5:30~15:00 片段 mpv --speed=2 --audio-pitch-correction video.mp4 # 2 倍速但保持音调 mpv --ab-loop-a=00:10:00 --ab-loop-b=00:15:00 video.mkv # A-B 反复磨 mpv --shuffle --playlist=music.m3u # 列表随机播放⚠️
--ab-loop-a/b的时间格式支持HH:MM:SS.mmm，两个值必须成对出现，只写 A 不写 B 等于白设。--speed配合--audio-pitch-correction（默认开启）会自动挂上 scaletempo 滤波器，倍速不变调。
4.5 网络与流媒体
本节覆盖：缓存、磁盘缓存、超时、UA 伪装与 HTTP 头。
| 选项 | 类型 | 默认值 | 一句话说明 |
|---|---|---|---|
--cache | choice | auto | 是否启用 RAM 缓存 |
--demuxer-max-bytes | int | 256M | 缓存字节上限 |
--cache-on-disk | bool | no | 缓存写磁盘而非内存 |
--cache-dir | string | - | 磁盘缓存目录 |
--network-timeout | float | 10 | 网络请求超时秒数 |
--user-agent | string | - | 伪装 UA 头 |
--http-header-fields | string | - | 追加自定义 HTTP 头 |
mpv --cache=yes --demuxer-max-bytes=500M http://example.com/stream.m3u8 # 大缓存防抖 mpv --cache-on-disk --cache-dir=~/.cache/mpv http://example.com/live.m3u8 # 磁盘缓存 mpv --user-agent="Mozilla/5.0" http://example.com/stream.m3u8 # 伪装浏览器 UA mpv --http-header-fields="Referer: http://example.com" http://example.com/stream.m3u8 # 带 Referer 防盗链 mpv --network-timeout=30 http://example.com/stream.m3u8 # 放宽超时⚠️
--cache-on-disk对慢速网络有效，但会把缓存数据落盘，机械硬盘上反而增加延迟；--http-header-fields的值里带空格或冒号时要整体加引号，否则会被当成多个参数。
4.6 输入映射与快捷键
本节覆盖：input.conf 语法、默认键位与自定义绑定。
input.conf每行一条绑定，格式[Shift+][Ctrl+][Alt+]<key> <command> [; <command2>]，文件在~/.config/mpv/input.conf，改完保存即生效。
| 默认键 | 命令 | 默认键 | 命令 |
|---|---|---|---|
SPACE | cycle pause | RIGHT/LEFT | seek ±5 |
UP/DOWN | seek ±60 | 9/0 | add volume ∓2 |
f | cycle fullscreen | m | cycle mute |
j | cycle sub | z/Z | add sub-delay ∓0.1 |
s | screenshot | q | quit |
# ~/.config/mpv/input.conf 自定义片段 Ctrl+UP add volume 5 # 自定义音量步进 Alt+RIGHT seek 30 # 快进 30s F1 show-text "File: ${filename}" # 屏幕显示当前文件名 # 用 ignore 解除默认绑定 ctrl+w ignorempv --input-test --force-window --idle # 进测试模式看按键映射 mpv --input-keylist # 打印所有特殊键名⚠️ 多键序列绑定（如
a-b-c）会被单键b的默认绑定截胡；想让b单独失效又不想丢序列，把b绑到ignore而不是删行。
4.7 配置文件与 Profile 用法
本节覆盖：多级配置路径、conf 语法与 [profile] 配置档。
读取顺序（后覆盖前）：/etc/mpv/mpv.conf→~/.config/mpv/mpv.conf→ 命令行。语法上把命令行--去掉即可，#起注释行。
# ~/.config/mpv/mpv.conf fs=yes volume=80 hwdec=auto video-sync=display-resample [high-quality] profile-desc="高质量渲染" vo=gpu scale=ewa_lanczossharp cscale=ewa_lanczossharp interpolation=yes video-sync=display-resample [low-power] profile-desc="低功耗" vo=gpu hwdec=no scale=bilinearmpv --profile=high-quality video.mp4 # 激活指定 profile mpv --profile=help # 列出内置 profile⚠️ profile 块要写在文件末尾，否则前面的全局设置会被 profile 锁死；
--no-config会跳过全部配置文件，排障时先加它。
4.8 脚本、滤镜与扩展
本节覆盖：Lua 脚本、vf/af 滤镜链、lavfi-complex 与截图模板。
| 选项 | 类型 | 默认值 | 一句话说明 |
|---|---|---|---|
--script | string | - | 加载一个 Lua 脚本 |
--script-opts | string | - | 给脚本传键值对 |
--vf | string | - | 视频滤镜链 |
--af | string | - | 音频滤镜链 |
--lavfi-complex | string | - | FFmpeg 复杂滤镜图 |
--screenshot-template | string | - | 截图文件名模板 |
--screenshot-format | choice | png | 截图输出格式 |
mpv --script=TOOLS/lua/autocrop.lua video.mp4 # 自动裁剪黑边 mpv --vf=scale=1280:720,vflip video.mp4 # 缩放 + 垂直翻转 mpv --af=lavfi=[loudnorm] video.mp4 # 响度归一 mpv --lavfi-complex="[0:v]scale=1280:720[v];[v]vflip[out]" video.mp4 # 复杂滤镜图 mpv --screenshot-template="shot-%n" --screenshot-format=png video.mp4 # 模板化截图⚠️
--vf里多个滤镜用英文逗号分隔，滤镜参数用冒号:；--lavfi-complex的图节点标签必须闭合，漏掉[out]会导致视频流找不到输出。
4.9 🐛 性能与调试
本节覆盖：解码线程、丢帧策略、渲染后端与日志输出。
| 选项 | 类型 | 默认值 | 一句话说明 |
|---|---|---|---|
--vd-lavc-threads | int | auto | 视频解码线程数 |
--framedrop | choice | no | 丢帧模式，decoder/danger |
--vo | choice | auto | 视频输出后端 |
--gpu-api | choice | - | gpu-next 的图形 API（vulkan/gl） |
--gpu-context | choice | auto | 图形上下文（x11/angle/d3d11） |
--msg-level | string | - | 模块日志级别 |
--log-file | string | - | 日志落盘路径 |
mpv --vd-lavc-threads=4 --framedrop=decoder video.mp4 # 限 4 线程 + 解码层丢帧 mpv --vo=gpu-next --gpu-api=vulkan video.mp4 # Vulkan 渲染管线 mpv --msg-level=all=v video.mp4 # 全模块 verbose 日志 mpv --log-file=mpv.log --msg-level=ffmpeg=trace video.mp4 # 详细日志落盘 mpv --vo=null --ao=null --no-video video.mp4 # 无头测试只跑解码⚠️
--msg-level只能调高不能调低（调高上限由终端控制），要安静日志用--msg-level=all=no；--vo=null --ao=null组合下没有画面也没有声音，专门用来跑--end限定的片段做吞吐测试。
故障排查速查表
| 现象 | 排查命令 | 说明 |
|---|---|---|
| 无画面 | mpv --vo=null --ao=null --no-video video.mp4 | 先确认解码链路通，再看终端vo报错 |
| 音画不同步 | mpv --audio-delay=0.2 video.mp4 | 音频超前加正值，落后加负值 |
| 字幕乱码 | mpv --sub-codepage=cp1252 video.mkv | 按源文件实际编码选，加+强制转换 |
| 硬解回退软解 | mpv --hwdec=auto,unsafe-hwdec --hwdec-codecs=all video.mp4 | 看终端hwdec行是否报 unsupported |
| 网络卡顿 | mpv --demuxer-max-bytes=500M --network-timeout=30 URL | 先放大缓存再放宽超时，顺序别反 |
| 配置不生效 | mpv --no-config video.mp4与mpv video.mp4对比 | 前者无配置、后者读全部，差异即来源 |
mpv 全部选项可跑mpv --list-options自检，man 页见 DOCS/man/options.rst，键位文档见 DOCS/man/input.rst。
【免费下载链接】mpv🎥 Command line media player项目地址: https://gitcode.com/GitHub_Trending/mp/mpv
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
