• 音视频
• VR
• 视频

VR-reversal 是一个基于 MPV 播放器的开源方案：它通过一个 Lua 脚本（360plugin.lua）配合 MPV 自带的v360视频滤镜，把左右格式（side-by-side）的 3D 视频当作 2D 视频来播放，让你在普通屏幕上用鼠标或键盘自由环视、缩放画面，还能把观看过程中的头部运动轨迹记录成 ffmpeg 可执行的命令日志，在退出播放器后一键把"你想看的画面"渲染成 2D 视频片段。读完本文，你将掌握该插件的安装方式、全部按键控制、配置文件定制方法，以及头部运动日志与convert_3dViewHistory.bat批量导出 2D 视频的完整原理。

一、项目组成与工作原理

仓库 VR-reversal 的核心文件只有三个，职责非常清晰：

工作原理一句话概括：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 主开关与画质

分辨率参数在源码中称为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 视角控制（键盘 + 鼠标）

各角度参数在源码中均有 ±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 左右眼与立体输出

3.4 标准 MPV 控制

插件没有覆盖 MPV 的常规播放控制，以下快捷键原样保留：

• 方向键：快进 / 快退；
• SPACE：暂停 / 继续；
• f：全屏切换；
• 9/0或//*：音量增减；
• m：静音；
• q：退出播放器。

四、进阶投影与立体模式控制

这些按键用于处理非默认格式或老旧片源。插件作者在 README 中说明：约 90% 的现代 VR 资源使用默认的 180° hequirect 投影即可正确播放，所以下面的键位多数时候用不到。

输入投影列表定义在源码的 inputProjections 表，默认索引为 0 即hequirect；输出投影定义在 outputProjections 表，默认flat。

4.1 按p切换的 6 种 2D 输出模式

按下p会依次经过以下模式（实现见 switchoutputsbs）：

最后三种模式通过追加 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 中可配置的全部项（附源码默认值，便于对照）：

说明：配置文件中没有出现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），表示该姿态变化跨越的播放时间区间；
• 每条指令是 ffmpegv360滤镜的[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"

参数含义：

七、源码实现要点：滤镜链与运行机制

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
• 视频