VR-reversal 实战指南:用 MPV 插件把 3D 视频转 2D 观看、环视缩放并导出 2D 视频

原创2026-10-15 15:21:581,693 阅读
文章标签:音视频视频处理VR3D渲染插件系统桌面应用

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 示例输出:3D 视频以 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 都自动加载该插件,需要做两件事:

  1. 把 360plugin.lua 放到 MPV 的 scripts 目录(MPV 会自动加载该目录下所有脚本);
  2. 把 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 压缩包),然后:

  1. 双击运行 vr-reversal.bat;
  2. 直接把视频文件拖到 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():移除按键、移除滤镜、恢复全部属性,插件完全卸载。

八、常见注意事项

  1. 默认投影假设:默认以 180° hequirect 输入、flat 输出工作,适配绝大多数现代 VR 片源;老片或特殊格式请用 1/2/b/r 调整。
  2. 分辨率与性能:实时环视本质是 CPU 上的 v360 重投影,且插件会临时关闭硬件解码,建议先用 y 逐步提升清晰度,以画质与流畅度的平衡为准。
  3. 导出需要 ffmpeg:仅观看无需安装;要渲染 2D 视频,请确保 ffmpeg 在 PATH 中可用,再运行生成的 convert_3dViewHistory.bat。
  4. 日志与批处理文件位置:*_3dViewHistory_*.txt 与 convert_3dViewHistory.bat 都生成在运行 MPV 时的当前工作目录,注意与源视频区分存放。
  5. 键位定制:优先修改 script-opts/360plugin.conf,改动即时作用于下次启动;不要直接修改 360plugin.lua 中的默认值表,以免升级时被覆盖。

以上就是 VR-reversal 从安装、播放控制、配置定制到运动日志导出 2D 视频的完整用法。把 360plugin.lua、script-opts/360plugin.conf 与 vr-reversal.bat 放进 MPV 对应目录,即可开始把手中的 3D 片源"转为"真正能随心环视的 2D 观影体验。

登录后查看全文
VR-reversal