VR-reversal 实战指南:用 MPV 插件把 3D 视频转 2D 观看、环视缩放并导出 2D 视频
VR-reversal 实战指南:用 MPV 插件把 3D 视频转 2D 观看、环视缩放并导出 2D 视频
VR-reversal 是一个基于 MPV 播放器的开源方案:它通过一个 Lua 脚本(360plugin.lua)配合 MPV 自带的 v360 视频滤镜,把左右格式(side-by-side)的 3D 视频当作 2D 视频来播放,让你在普通屏幕上用鼠标或键盘自由环视、缩放画面,还能把观看过程中的头部运动轨迹记录成 ffmpeg 可执行的命令日志,在退出播放器后一键把"你想看的画面"渲染成 2D 视频片段。读完本文,你将掌握该插件的安装方式、全部按键控制、配置文件定制方法,以及头部运动日志与 convert_3dViewHistory.bat 批量导出 2D 视频的完整原理。
一、项目组成与工作原理
仓库 VR-reversal 的核心文件只有三个,职责非常清晰:
| 文件 | 作用 |
|---|---|
| 360plugin.lua | 核心 Lua 插件:读取配置、注册按键、动态增删 v360 滤镜、记录头部运动日志 |
| script-opts/360plugin.conf | 默认配置文件:定义自动启用开关与全部按键绑定 |
| vr-reversal.bat | Windows 便捷启动脚本:免命令行、支持拖放视频 |
工作原理一句话概括:MPV 加载脚本 → 脚本向视频链追加一条带 @vrrev 标签的 v360 滤镜 → 播放器实时用该滤镜把输入的立体(SBS/TB)画面重投影为平面 2D 画面 → 脚本通过按键/鼠标不断更新滤镜参数(yaw/pitch/roll/d_fov 等)实现环视与缩放。从源码看,滤镜参数更新走的是 updateFilters 函数:首次用 vf add 加入,之后用 vf set 就地更新,避免反复重建滤镜链。
-- 360plugin.lua 中构造的滤镜参数(节选自 updateFilters)
@vrrev:v360=<输入投影>:<输出投影>:reset_rot=1:in_stereo=<sbs/tb>:out_stereo=<2d/sbs>:id_fov=180:d_fov=110:yaw=0:pitch=0:roll=0:w=<res>*192.0:h=<res>*108.0:h_flip=0:interp=<缩放算法>,setsar=sar=<sar>
二、安装与三种启动方式
2.1 前提准备
- MPV 播放器(必需):前往官方 mpv.io 下载对应平台的最新版本。VR-reversal 不提供独立播放器,只提供插件。
- ffmpeg(可选):仅当你想把观看过程导出为 2D 视频时才需要;仅观看无需安装。
2.2 方式一:命令行临时加载(最直接)
将 360plugin.lua 下载到本地,然后用命令行启动:
mpv --script=360plugin.lua --script-opts=360plugin-enabled=yes videoFile.mp4
参数拆解:
--script=360plugin.lua:让 MPV 加载该 Lua 脚本;--script-opts=360plugin-enabled=yes:相当于把配置项enabled置为yes,脚本启动后立即生效,无需再按键开启;videoFile.mp4:要播放的 3D 左右格式视频文件。
这种方式的优点是不改动 MPV 全局配置,按需启用,适合临时体验。
2.3 方式二:自动启用(放进 MPV 配置目录)
如果你希望每次打开 MPV 都自动加载该插件,需要做两件事:
- 把 360plugin.lua 放到 MPV 的
scripts目录(MPV 会自动加载该目录下所有脚本); - 把 script-opts/360plugin.conf 放到 MPV 的
script-opts目录(与 MPV 主配置目录同级)。
然后把配置文件中的 enabled=no 改为 enabled=yes,之后每次 MPV 会话都会自动启用。其原理是脚本在启动时通过 mp.options.read_options(opts) 读取与脚本同名的配置文件(script-opts/360plugin.conf),见 360plugin.lua 第 7-41 行;若 enabled 为 true,脚本加载末尾会直接调用 initFunction() 完成初始化(第 728-730 行)。
2.4 方式三(Windows):vr-reversal.bat + 拖放视频
Windows 用户不想记命令行的话,可以把 mpv.exe、vr-reversal.bat 和 360plugin.lua 放在同一目录(仓库 Releases 中提供后两者的 Zip 压缩包),然后:
- 双击运行
vr-reversal.bat; - 直接把视频文件拖到 MPV 窗口上开始播放。
批处理内容 本质上就是封装了命令行参数:
@ECHO OFF
pushd %~dp0
ECHO "%~1"
IF "%~1"=="" GOTO BLANK
mpv.exe --script=360plugin.lua --script-opts=360plugin-enabled=yes "%~1"
GOTO DONE
:BLANK
mpv.exe --script=360plugin.lua --script-opts=360plugin-enabled=yes
:DONE
popd
即:带文件参数时直接播放该文件,不带参数时只打开启用了插件的 MPV 空窗口,等待拖放。
三、上手操作:完整按键控制
播放过程中随时按 ? 可在屏幕上显示默认按键与鼠标控制的速查清单(帮助内容由 build_help_string 根据当前实际绑定动态生成,改过键位后显示的是新键位)。
3.1 主开关与画质
| 按键 | 功能 | 说明 |
|---|---|---|
v |
开/关 3D→2D 转换主功能 | 首次按下启用插件(初始化滤镜与绑定),再次按下卸载 |
y / h |
提高 / 降低画面分辨率 | 视频默认以低分辨率预览,需要细节时按 y |
e |
循环切换视频缩放算法 | 见下方说明 |
分辨率参数在源码中称为 res,初始为 1.0,范围被限制在 1 到 20 之间(increment_res),实际输出尺寸为 宽 = res × 192、高 = res × 108,即 res=1 时约 192×108(低质量快速预览),res=10 时即 1920×1080,res=20 时达 3840×2160。每次调整 OSD 会提示当前输出宽度。
关于 e 键需要说明:README 描述为"在最近邻与双三次之间切换",但从源码看实际是 5 种算法的循环(switchScaler):nearest → cubic → lagrange9 → lanczos → linear,再回到 nearest,OSD 会提示当前算法名,默认初始为 linear。
3.2 视角控制(键盘 + 鼠标)
| 输入 | 功能 | 源码绑定名 |
|---|---|---|
i / k |
向上 / 向下看(pitch) | pitch_up / pitch_down |
l / j |
向右 / 向左看(yaw) | yaw_up / yaw_down |
u / o |
向左 / 向右歪头(roll) | roll_left / roll_right |
= / - |
放大 / 缩小(d_fov) | zoom_in / zoom_out |
| 鼠标滚轮上 / 下 | 放大 / 缩小 | wzoom_in / wzoom_out |
TAB |
视角回中(yaw/pitch/roll 归零) | reset_view |
| 鼠标左键点击 | 进入/退出"鼠标环视"模式 | grab_mouse |
| 鼠标移动 | 在环视模式下控制视角 | mouse_pan |
各角度参数在源码中均有 ±180° 的硬限制(increment_yaw 等)。缩放的实际含义是改变显示视野角 d_fov,初始为 110°,取值范围 30°~150°,数值越小画面越"放大"(increment_zoom)。
鼠标环视的映射逻辑见 mouse_pan:根据鼠标在 OSD 坐标系中的位置,把横向偏移映射为 yaw、纵向偏移映射为 pitch(((mouseX/osd_w)-0.5)*180),开启平滑时采用指数滑动平均 yaw=(目标值+yaw*5)/6 来柔化转动。
3.3 左右眼与立体输出
| 按键 | 功能 | 说明 |
|---|---|---|
t |
切换左眼 / 右眼 | 通过翻转 h_flip 实现,OSD 提示当前眼睛(switchEye) |
g |
开 / 关鼠标平滑 | 默认开启,关闭后鼠标转动更"跟手"(toggleSmoothMouse) |
n |
开始 / 停止记录头部运动 | 详见"头部运动记录"章节 |
? |
显示按键与鼠标控制速查 | OSD 显示 10 秒 |
3.4 标准 MPV 控制
插件没有覆盖 MPV 的常规播放控制,以下快捷键原样保留:
方向键:快进 / 快退;SPACE:暂停 / 继续;f:全屏切换;9/0或//*:音量增减;m:静音;q:退出播放器。
四、进阶投影与立体模式控制
这些按键用于处理非默认格式或老旧片源。插件作者在 README 中说明:约 90% 的现代 VR 资源使用默认的 180° hequirect 投影即可正确播放,所以下面的键位多数时候用不到。
| 按键 | 功能 | 循环内容(来自源码) |
|---|---|---|
r |
切换输入立体格式 | sbs(左右)↔ tb(上下) |
b |
循环输入 FOV 边界 | 180° → 360° → 90° → 180° |
1 |
循环输入投影 | hequirect → equirect → fisheye → pannini → cylindrical → sg |
2 |
循环输出投影 | flat → sg |
p |
循环 2D 输出模式 | 见下方展开 |
输入投影列表定义在源码的 inputProjections 表,默认索引为 0 即 hequirect;输出投影定义在 outputProjections 表,默认 flat。
4.1 按 p 切换的 6 种 2D 输出模式
按下 p 会依次经过以下模式(实现见 switchoutputsbs):
| 模式 | 含义 | 附加滤镜 / 采样比 |
|---|---|---|
2d |
平面 2D 输出(默认) | 无,sar=1.0 |
sbs |
重新投影后的左右全宽输出 | 无,sar=1.0 |
sbs-hw |
左右半宽输出 | sar=0.5 |
sbs2l:arcg |
红-青(灰阶/单色)anaglyph 红蓝眼镜输出 | ,stereo3d=sbs2l:arcg |
sbs2l:arbg |
红-蓝(灰阶/单色)anaglyph 输出 | ,stereo3d=sbs2l:arbg |
sbs2l:arcd |
红-青 Dubois 算法 anaglyph 输出 | ,stereo3d=sbs2l:arcd |
最后三种模式通过追加 MPV 的 stereo3d 滤镜把立体信号编码为红蓝/红青眼镜可看的画面,适合没有 3D 显示器的用户直接用普通显示器配 anaglyph 眼镜体验立体感。
五、配置文件定制:script-opts/360plugin.conf
5.1 配置机制
脚本启动时通过 mp.options.read_options(opts) 读取 script-opts 目录下与脚本同名的 .conf 文件(即 script-opts/360plugin.conf),文件中每一项都会覆盖 Lua 代码中的默认值,因此改键位、改启动行为都不需要编辑脚本本身,也支持通过命令行 --script-opts=xxx=yyy 临时覆盖。
5.2 完整参数表
下表汇总了 script-opts/360plugin.conf 中可配置的全部项(附源码默认值,便于对照):
| 配置项 | 配置值 / 默认值 | 功能说明 |
|---|---|---|
enabled |
no |
设为 yes 后启动即自动启用插件 |
toggle_vr360 |
v |
主功能开/关 |
cycle_input |
1 |
循环输入投影 |
cycle_output |
2 |
循环输出投影 |
roll_left / roll_right |
u / o |
歪头(roll)左右 |
write_log |
w |
立即写入一条当前头部位置日志(需处于记录会话中) |
pitch_up / pitch_down |
i / k |
上下看 |
yaw_up / yaw_down |
l / j |
左右看 |
easy_crop |
c |
立即刷新一次滤镜(相当于重新套用当前参数) |
res_up / res_down |
y / h |
提高 / 降低分辨率 |
zoom_in / zoom_out |
= / - |
放大 / 缩小 |
wzoom_out / wzoom_in |
WHEEL_DOWN / WHEEL_UP |
滚轮缩小 / 放大 |
reset_view |
TAB |
视角回中(注意:配置文件为 TAB,Lua 内置默认值是 0,实际生效以配置文件为准) |
switch_stereo |
r |
切换输入立体格式 sbs/tb |
switch_eye |
t |
切换左眼 / 右眼 |
switch_scaler |
e |
循环缩放算法 |
toggle_smooth |
g |
鼠标平滑开关 |
switch_bounds |
b |
循环输入 FOV 边界 180/360/90 |
new_log_session |
n |
开始 / 停止记录头部运动 |
grab_mouse |
mouse_btn0 |
鼠标左键进入环视模式 |
mouse_pan |
mouse_move |
鼠标移动控制视角 |
show_help |
? |
显示控制速查 |
osc |
no |
启用插件时关闭 MPV 默认播放器控制条 |
fullscreen |
yes |
启用插件时强制全屏 |
osd-font-size |
30 |
OSD 提示字体大小 |
说明:配置文件中没有出现 switch_output_sbs(p 键对应项),此时由 Lua 内置默认值补全,无需自行添加。
5.3 关于 input.conf 覆盖的注意事项
README 提到也可以在 MPV 的 input.conf 中按常规方式覆盖按键。需要提醒的是:从源码看,插件使用 mp.add_forced_key_binding 注册按键(initFunction 第 642-644 行),强制绑定在 MPV 中优先级高于普通 input.conf 绑定,因此想要可靠地自定义键位,最推荐的方式还是直接编辑 script-opts/360plugin.conf;在 input.conf 中覆盖可能不生效,视具体 MPV 版本而定。
六、头部运动记录与 2D 视频批量导出
这是 VR-reversal 最有特色的功能:你可以一边观看一边"指挥"镜头运动,脚本把这些运动轨迹保存为 ffmpeg 可直接执行的命令日志,退出后自动生成批处理脚本,一键渲染出 2D 视频片段。
6.1 记录会话(按 n)
- 按一次
n:开始记录,OSD 提示Started Motion Record xxx_3dViewHistory_0.txt; - 再按一次
n:停止本次记录并封存日志文件; - 多次按
n会生成多个编号递增的日志段({文件名}_3dViewHistory_0.txt、_1.txt……),编号逻辑见 openNewLogFile; - 记录期间每 0.1 秒 OSD 会刷新一次已录制时长(printRecordingStatus)。
6.2 日志文件格式
日志每行代表一次头部姿态变化,格式为:
起始时间-结束时间 , [expr] v360 pitch 'lerp(起,止,(T-起始)/时长)', [expr] v360 yaw 'lerp(起,止,(T-起始)/时长)', [expr] v360 roll 'lerp(...)', [expr] v360 d_fov 'lerp(...)';
生成逻辑见 writeHeadPositionChange:
- 时间戳精确到毫秒(
%.3f-%.3f),表示该姿态变化跨越的播放时间区间; - 每条指令是 ffmpeg
v360滤镜的[expr]命令,lerp(起,止,(T-起始)/时长)表示在起止时间之间对角度做线性插值,使渲染出的镜头运动平滑连续; - 只有 pitch / yaw / roll / d_fov 中发生变化的项才会写入;
- 如果相邻两次采样间隔超过 5 秒(例如中途 seek 跳转),脚本会强制补写一条记录,保证时间轴上没有断档(第 174 行);
- 日志以
#开头写入若干注释行,包含录制起止时间、总时长,以及一条可直接复制的建议 ffmpeg 转换命令。
6.3 退出后自动生成 convert_3dViewHistory.bat
退出播放器(或文件播放结束)时,脚本触发 onExit:把所有记录会话对应的完整 ffmpeg 命令收集起来,用 & 连接(顺序执行),写入当前目录下的 convert_3dViewHistory.bat。安装 ffmpeg 后双击/运行这个批处理文件,即可自动完成全部 2D 片段渲染。
6.4 建议的 ffmpeg 转换命令逐段解析
脚本在每条日志末尾注释中写入的完整命令形如(第 539-542 行):
ffmpeg -y -ss 0.000 -i "videoFile.mp4" -to 12.340 -copyts \
-filter_complex "v360=hequirect:flat:in_stereo=sbs:out_stereo=2d:reset_rot=1:id_fov=180:d_fov=110.000:yaw=0.000:pitch=0.000:roll=0.000:w=1920.0:h=108.0:interp=cubic:h_flip=0,setsar=sar=1.000,sendcmd=filename=videoFile_3dViewHistory_0.txt" \
-avoid_negative_ts make_zero -preset slower -crf 17 "videoFile_2d_000.mp4"
参数含义:
| 参数 | 作用 |
|---|---|
-ss <起始> -i <原视频> -to <结束> |
截取录制区间对应的源视频片段 |
-copyts |
保留原始时间戳,保证与日志中的时间轴一致 |
-filter_complex "v360=..." |
复用观看时的 v360 重投影参数,输出固定为 1920×1080、interp=cubic |
sendcmd=filename=xxx_3dViewHistory_0.txt |
关键机制:ffmpeg 按时间读取该日志文件中的 [expr] v360 ... 命令,逐帧驱动镜头运动,让渲染结果与你的观看轨迹完全一致 |
-avoid_negative_ts make_zero |
规避截取后的负时间戳问题 |
-preset slower -crf 17 |
高质量慢速编码(CRF 越低质量越高) |
videoFile_2d_000.mp4 |
输出文件命名:{原文件名}_2d_{会话编号}.mp4 |
七、源码实现要点:滤镜链与运行机制
7.1 命名滤镜 @vrrev
脚本用 MPV 的命名滤镜机制(vf add / vf set / vf remove,标签 @vrrev)管理滤镜生命周期:首次启用时 add,后续参数变化时 set,关闭插件时 remove。这保证了重复调整视角时不必反复重建滤镜链,性能开销小。
7.2 属性保存与恢复
脚本启用时会保存并接管一系列 MPV 属性(save_props):hwdec、fullscreen、osc、osd-font-size、cursor-autohide,退出插件时全部还原(restore_props)。
特别值得注意的是 硬件解码处理:源码注释明确说明,启用插件期间会强制把 hwdec 设为 no,原因是硬件解码与 v360 滤镜存在格式转换错误(报错信息形如 Impossible to convert between the formats supported by the filter 'mpv_src_default_in' and the filter 'auto_scaler_0')。因此高分辨率 3D 视频的实时环视对 CPU 性能有一定要求,这也是插件默认从低分辨率 res=1 预览开始的原因之一。
7.3 生命周期与事件
- 加载脚本时只注册
toggle_vr360(v)这一个强制绑定作为"总开关"(register_toggle_key); - 首次按
v或配置enabled=yes时才执行initFunction():保存属性、注册全部按键、设置osc/fullscreen/osd-font-size、注册end-file与shutdown事件、启动 0.1 秒记录计时器; - 播放结束或退出时执行
onExit():封存日志、合并 ffmpeg 命令、写出convert_3dViewHistory.bat; - 再次按
v执行teardownFunction():移除按键、移除滤镜、恢复全部属性,插件完全卸载。
八、常见注意事项
- 默认投影假设:默认以 180°
hequirect输入、flat输出工作,适配绝大多数现代 VR 片源;老片或特殊格式请用1/2/b/r调整。 - 分辨率与性能:实时环视本质是 CPU 上的 v360 重投影,且插件会临时关闭硬件解码,建议先用
y逐步提升清晰度,以画质与流畅度的平衡为准。 - 导出需要 ffmpeg:仅观看无需安装;要渲染 2D 视频,请确保 ffmpeg 在 PATH 中可用,再运行生成的
convert_3dViewHistory.bat。 - 日志与批处理文件位置:
*_3dViewHistory_*.txt与convert_3dViewHistory.bat都生成在运行 MPV 时的当前工作目录,注意与源视频区分存放。 - 键位定制:优先修改 script-opts/360plugin.conf,改动即时作用于下次启动;不要直接修改 360plugin.lua 中的默认值表,以免升级时被覆盖。
以上就是 VR-reversal 从安装、播放控制、配置定制到运动日志导出 2D 视频的完整用法。把 360plugin.lua、script-opts/360plugin.conf 与 vr-reversal.bat 放进 MPV 对应目录,即可开始把手中的 3D 片源"转为"真正能随心环视的 2D 观影体验。
