NEON_NOTES

mpv OSD 与逐帧配置 ​

这套配置用于在 macOS 的 mpv 播放窗口中常驻显示视频帧率、当前帧号、估算总帧数和播放时间，同时提供前后逐帧快捷键。

OSD 是什么？

OSD 是 On-Screen Display（屏幕信息显示），即叠加在视频画面上的状态文字。

1. 安装 mpv ​

如果还没有安装 Homebrew，请先完成 Homebrew 的安装。随后在终端运行：

bash
brew install mpv

Homebrew 的 mpv Formula 提供 macOS 预编译版本。安装完成后可检查版本：

bash
mpv --version

2. 创建配置目录 ​

mpv 的用户配置文件通常放在 ~/.config/mpv/：

bash
mkdir -p ~/.config/mpv

如果目录中已经存在配置，建议先备份：

bash
cp ~/.config/mpv/mpv.conf ~/.config/mpv/mpv.conf.bak 2>/dev/null || true
cp ~/.config/mpv/input.conf ~/.config/mpv/input.conf.bak 2>/dev/null || true

3. 配置常驻 OSD ​

编辑 ~/.config/mpv/mpv.conf，加入以下内容：

ini
# 使用 macOS 硬件解码
hwdec=auto-safe

# 常驻 OSD
osd-level=1
osd-font-size=28
osd-color="#FFFFFF"
osd-border-size=2
osd-fractions=yes

# 实测输出 FPS / 容器标称 FPS / 当前帧 / 总帧数 / 时间
osd-msg1="FPS: ${estimated-vf-fps}  Source: ${container-fps}\nFrame: ${estimated-frame-number} / ${estimated-frame-count}\nTime: ${time-pos} / ${duration}"

保存后重新打开 mpv，配置即可生效。

OSD 字段说明 ​

字段含义
estimated-vf-fps视频滤镜链输出的近期估算或实测 FPS；未使用滤镜时对应解码器输出
container-fps容器声明的标称帧率，该值可能不准确
estimated-frame-number根据 FPS 与时间戳计算的当前估算帧号
estimated-frame-count根据 FPS 与时长计算的估算总帧数
time-pos当前播放位置
duration视频总时长；某些媒体可能无法准确获得

帧号并非绝对值

mpv 官方说明，estimated-frame-number 和 estimated-frame-count 都是估算值。对于 VFR（可变帧率）视频、时间戳精度较低的视频或发生丢帧的场景，显示结果可能不稳定，不适合作为严格的视频帧编号依据。

4. 配置逐帧快捷键 ​

编辑 ~/.config/mpv/input.conf：

ini
# 方向键逐帧
RIGHT frame-step
LEFT  frame-back-step

# 备用快捷键
. frame-step
, frame-back-step

# 空格暂停或继续
SPACE cycle pause

# 显示或隐藏详细性能统计
i script-binding stats/display-stats-toggle

5. 使用方法 ​

  1. 在终端打开视频：

    bash
    mpv /path/to/video.mp4

  2. 按 Space 暂停播放。

  3. 按 → 或 . 前进一帧。

  4. 按 ← 或 , 后退一帧。

  5. 按 i 显示或隐藏解码、渲染、掉帧和同步等性能统计。

向前逐帧通常更直接。frame-back-step 会通过精确定位回到前一帧，因此长 GOP 视频可能较慢；精确定位能力、视频滤镜和 VFR 视频也可能影响结果。

6. 临时运行，不修改配置 ​

只想临时查看 OSD 时，可以直接通过命令行传入配置：

bash
mpv video.mp4 \
  --osd-level=1 \
  --osd-fractions \
  '--osd-msg1=FPS: ${estimated-vf-fps}  Source: ${container-fps}  Frame: ${estimated-frame-number}/${estimated-frame-count}  Time: ${time-pos}'

该命令只对本次播放生效，不会修改 mpv.conf。

7. 性能判断注意事项 ​

逐帧暂停适合检查画面和单帧解码延迟，但不能代表连续播放性能。测试正常播放时，可以按 i 重点观察：

  • Dropped Frames：播放过程中丢弃的帧。
  • Mistimed：未能按预期时刻显示的帧。
  • 解码与渲染耗时：用于判断性能瓶颈位于解码还是显示阶段。

参考资料 ​