English · 简体中文

RVE：Reverse Video Engineering

一个本地 MCP Server，把「已成片」逆向还原为可导入 NLE 的编辑时间线。

看到一条喜欢的成片。想知道它怎么剪的，并拿回一份能继续编辑的工程。

调研分析报告 · 贡献指南 · 交付验收

快速开始 · 工作原理 · 能还原什么 · Showcases · 案例库 · 模拟真人导入 · FAQ · 文档

git clone https://github.com/joker1point/rve.git && cd rve && python -m pip install -e ".[dev]"

成片 → 探测/切镜 → EditSpec → 导出（FCP7 / EDL / OTIO）→ NLE

flowchart LR
    A["成片<br/>final render"] --> B["探测 ffprobe<br/>probe_video"]
    B --> C["硬切检测 PySceneDetect<br/>detect_shots"]
    C --> D["EditSpec<br/>秒锚定 · 唯一权威结构"]
    D --> E["导出器<br/>FCP7 XML / EDL / OTIO"]
    E --> F["NLE<br/>Premiere · Resolve"]

    subgraph ADAPTER["薄适配器（不 vendor 上游源码）"]
        B
        C
    end

为什么存在

现有工具覆盖不到「成片 → 可继续编辑的时间线」这一格：

• 只能还原硬切：多数镜头切分工具止步于"切点列表"，不产出能被剪辑软件吃下的工程；

• 绑死单一 NLE：能导出时间线的少数方案往往只对接某一家剪辑软件，导出层不可替换；

• 封闭：反推提示词/分镜的 SaaS 是闭源服务，无法自托管、也无法被 Agent 直接调用。

RVE 的定位是 C 型（工程还原）：把成熟的上游工具（FFprobe、PySceneDetect、OpenTimelineIO）以薄适配器封装成统一流水线，产出秒锚定的唯一权威结构 EditSpec，再从它导出可导入的时间线。

想研究一条成片的节奏与结构？让 Agent 用 RVE 拆开它。它不需要源工程，就能给出镜头边界、节奏统计与存疑项，输出证据，并把结论导出成可编辑的时间线。

RVE 通过 MCP 把上述能力交给任意支持 MCP 的 AI Agent，同时提供同名 CLI 供你在终端直接调用。分析全程本地完成，结论附带证据与限制说明。

Related MCP server: vidx

快速开始

前置条件：本机需装 ffmpeg（含 ffprobe） 并加入 PATH。用 rve doctor 确认环境（缺依赖时只报告、不报错，doctor 永远退出 0）。

安装

RVE 尚未发布到 PyPI。当前可行的安装方式只有两种：

# 方式一：从 git 安装源码（含开发依赖）
git clone https://github.com/joker1point/rve.git && cd rve
python -m pip install -e ".[dev]"

# 方式二：安装本地构建的 wheel
python -m build --wheel          # 需 pip install build
python -m pip install dist/rve-0.1.0-py3-none-any.whl

安装后即得到 rve 命令（pyproject.toml 的 [project.scripts]，入口 rve = rve.cli:main）。

自检本机环境：

rve doctor

doctor 会逐项探测外部命令（ffprobe/ffmpeg）与 Python 依赖（scenedetect/opentimelineio/mcp），并打印缺失项的可执行安装建议。

接入你的 Agent（MCP Server）

RVE 以 stdio 传输启动 MCP server，对外暴露 8 个工具（probe_video、detect_shots、analyze_audio、describe_shots、build_edit_spec、get_edit_spec、export_timeline、render_report）与 1 个资源模板 editspec://{spec_id}。

CLI 没有 mcp 子命令。MCP server 的独立入口是 python -m rve.mcp.server。

在 Claude Desktop / Cursor 等的 MCP 配置中加入：

{
  "mcpServers": {
    "rve": {
      "command": "python",
      "args": ["-m", "rve.mcp.server"],
      "env": {
        "RVE_WORKSPACES": "C:/Users/<you>/.rve/workspaces"
      }
    }
  }
}

• command/args：以 stdio 启动 MCP server（等价于 rve.mcp.server:run_stdio）。

• env.RVE_WORKSPACES：spec 落盘根目录；缺省 ~/.rve/workspaces。CLI 与 MCP 共用同一工作区，Agent 产出的 spec 可被 rve export/rve report 直接复用。

用终端

CLI 只有 5 个子命令：doctor / analyze / export / report / specs。

# 1) 一条龙：探测 -> 硬切检测 -> 组装 EditSpec -> 导出 FCP7 XML
#    产物落在 out/<spec_id>.fcp7xml.xml，同时 spec 已存入工作区
rve analyze path/to/final_cut.mp4 --out out/

# 2) 列出工作区中已保存的 spec
rve specs

# 3) 把某个 spec 导出为 NLE 时间线
rve export <spec_id> --format fcp7xml
#    --format 取值：{fcp7xml, edl, otio}

# 4) 渲染人类可读的分镜复核报告（HTML）
rve report <spec_id>   # 固定写到 cwd/reports/<spec_id>_report.html，无 --out

analyze 的 --engine 可选 auto（默认，双引擎交叉验证）/content/adaptive；未实现的引擎取值会以退出码 2 明确报错，不会静默成功。

退出码约定（供脚本与 Agent 判断）：

doctor 是"体检报告"而非"断言"，永远退出 0，不因缺依赖而失败。

更新

RVE 没有自更新机制（没有 update 子命令，也没有 npm/npx 薄壳）。更新方式与安装一致：对源码安装执行 git pull 后重装，对 wheel 安装重新构建并安装新 wheel。

工作原理

你的 Agent 通过 MCP 调用 RVE，RVE 在本地探测素材、切分镜头、组装 EditSpec 并导出时间线；结论附带证据与限制。CLI 命令走的是同一套流水线。

RVE 照 REA 的分层组织，三层各司其职：

不 vendor 任何上游源码：RVE 不包含、也不复制 FFmpeg、PySceneDetect、OpenTimelineIO 的任何源码。上游工具一律以薄适配器封装：

• ffprobe 通过子进程调用用户机器上已安装的 ffprobe（src/rve/providers/ffprobe.py）；

• 切镜通过 import scenedetect 调用已安装的 PySceneDetect（src/rve/providers/shots_pyscenedetect.py）；

• OTIO 导出延迟导入 opentimelineio，因此未装 OTIO 也不会拖垮其余功能。

能还原什么（能力矩阵）

RVE 需要 Python 3.11/3.12/3.13，外加 ffmpeg（含 ffprobe）。能做什么取决于目标：

说明：analyze_audio 与 describe_shots 两个工具未落地，工具名存在不代表能力可用；未实现的能力一律显式报错，绝不 quietly succeed。注意区分导出侧与分析侧：FCP7 导出已输出带真实 <file> 的逐镜音频轨（见 Showcases），而"逐镜音频分析/画面描述"工具本身仍未实现。

Showcases

以下指标均由本机实跑产出，命令可复现。

Tears of Steel 片段：真实素材全链路还原

素材为 Tears of Steel 的真实片段（ffmpeg -ss 100 -t 60 -c copy 截取，1920×800 @ 24fps，61.808s）。运行 rve analyze 得到：

• 10 个镜头，Σ镜头时长 == 源时长 == 61.808s（连续、无缺口、无重叠）；

• 每分钟约 9.707 个切点（节奏曲线 slow_build），最短镜头 1.474s，无 < 0.5s 碎镜；

• 转场判定：9 条内部边界 → 7 硬切 / 2 溶解 / 0 淡出（每条都带峰值差、窗口基线、信噪比等证据）；

• uncertain == 1：唯一存疑项是 shots[9].cut_type——那条溶解只有 4 帧铺展、置信度 0.42，显式登记而非静默猜一个标签。

落盘证据：该 spec 的工作区目录含 spec.json 与 receipts/——receipts/build_edit_spec.json（本次组装的回执与产物清单）与 receipts/transitions.json（9 条内部边界的逐条证据：峰值差 / 窗口基线 / 信噪比 / 亮度极值）。二者均为离线可复核文件，不依赖 MCP 的瞬时返回。

导出的 FCP7 XML 经 scripts/independent_verify.py（不 import rve.* 的第二实现） 回读 → PASS：<xmeml> version=4、时间轴为纯平移（偏移 ≈ 0 帧、跨 10 镜一致）、末个 clipitem end=1483 且 sequence duration=1483 与期望一致、<timebase>=24 <ntsc>=FALSE、2 个 transitionitem 全部严格跨骑剪切点、音频轨 10 个 clipitem、<timecode> 存在（详细输出见独立验证）。

OTIO 读回：视频轨 clip 数 10 == EditSpec 镜头数，媒体引用齐全（missing_ref == 0、no_url == 0，target_url 回指源 tos_seg.webm），镜头区间之和 61.808s == 源时长。OTIO 的音频轨目前仍为空轨（0 个元素），不随 FCP7 一起补齐。

复现命令：

export RVE_WORKSPACES="$TEMP/rve_vC"
rve analyze /path/to/tos_seg.webm --out "$TEMP/rve_vC/out"
rve export <spec_id> --format fcp7xml --out "$TEMP/rve_vC/out/<spec_id>.fcp7xml"
rve export <spec_id> --format edl
rve export <spec_id> --format otio

交付闸门：14/14 PASS

python scripts/acceptance.py 是交付验收入口，逐阶段打印 PASS/FAIL，末行输出 RESULT: PASS|FAIL，全过才 exit 0。十四个阶段：S0 预检 / S1 宿主单测 / S2 构建 wheel + 全新 venv 安装 + rve --help/doctor / S2b 全新 venv 内单测 / S3 密闭端到端 analyze / S4 FCP7 XML 契约断言 / S5 EDL+OTIO+往返 / S6 MCP 面 / S7 开源卫生 / S8 包名闸门 / S9 独立校验（不 import rve 的第二实现回读 FCP7 XML） / S10 案例库（全新 venv 内 rve showcase list + 跑通程序合成案例） / S11 模拟真人导入（真值素材 + 独立解析器回读比对） / S12 可选切镜引擎 hypit（装了必须跑通，没装明确报告）。

最近一次本机实跑：

通过 14 / 失败 0 / 跳过 0
RESULT: PASS

其中 S1 宿主单测与 S2b 全新 venv 内单测均为 passed=164 skipped=0 failed=0 errors=0（宿主与全新环境依赖齐备，OTIO 用例全部执行；宿主若未装 opentimelineio，那几条 OTIO 用例按约定 skip 而非报错），S9 独立校验器退出码 0、裁决 PASS，S10 在全新 venv 内 rve showcase list 命中全部 4 个案例 id 并跑通程序合成案例，S11 模拟真人导入 9/9 通过（时间线总长 216 帧 = 7.200s、3 处硬切全部命中、2 处转场落在设计窗口内、6 个片段素材全部在线），S12 在全新 venv 内跑通 --engine hypit（未装 hypit 的机器上该阶段明确报告"可选依赖缺席"并 PASS）。

S9 为什么必须单列：S4 的 FCP7 契约断言由写 XML 的同一份代码执行，属自证——导出器与断言共享同一个错误假设时，闸门照绿。S9 换用一个不 import rve.* 的第二实现（scripts/independent_verify.py），从第一性原理重建时间轴再比对，专挡这类系统性盲区。详见独立验证。

案例库（Showcase Library）

案例库把「跑出来是什么样」固化成可复现、可校验的配方。每个案例是一份 case.json（随包分发），写清素材从哪来、怎么准备、期望指标是什么；rve showcase run <id> 会真的跑一遍主链路，把实测值与期望值逐项比对——对不上就是失败，不静默放过。

rve showcase list                                          # 列出全部案例
rve showcase run synth_hard_cut                            # 跑一个程序合成案例（零版权，CI 可跑）
rve showcase run tos_segment --material /path/to/tos.mp4    # 外部素材需自行准备

期望值全部来自本机实跑（ffmpeg 4.3.1 + scenedetect 0.7.2），不是估计值；tos_segment 一行取自上面 Showcases 段记录的同一条截取命令的实跑结果。

两条刻意的设计：

• 合成素材的配方就是可直接执行的 ffmpeg 命令行（{{out}} 为输出占位符），因此三个合成案例不依赖任何第三方素材文件，CI 随时可跑；

• 外部素材绝不自动联网下载：缺素材时命令会打印「怎么准备」（来源、许可、截取命令、放置位置）并以退出码 2 结束，不静默跳过。

案例通过 MCP 同样可调：list_showcases 列出全部，run_showcase 跑单个并返回逐项校验结果。

独立验证（回应"自证式验证"）

交付闸门里有一半结论只由 RVE 自己产出，说服力有限。为此 RVE 加了两条独立于自身实现的证据链：

1. 第二实现回读。 scripts/independent_verify.py 只依赖 Python 标准库、绝不 import rve.*（该约束由 tests/test_independent_verify.py 用源码正则钉死），按公开 xmeml 约定从第一性原理重建"源帧 → 序列帧"映射，再与 spec.json 逐镜比对时间轴连续性、帧率、sequence duration、转场跨骑与音频轨。闸门 S9 即跑它——最终 RESULT 由两份不共享假设的实现共同决定。

2. 真实 NLE 产物对标。 取 9 份真实 NLE 导出的 xmeml（Premiere 5 份 / FCP7·Hiero 1 份 / 第三方金标 3 份），检验读取器能否吃下真实形态，并逐条列出「真实产物 vs RVE 产物」的结构差异。样本与结论见 scripts/independent_verify_findings.md（样本只存本机临时目录，不入库——版权风险）。

本次实跑结果：

诚实边界。 对标同时暴露 3 项未定论差异，且它们对真实导入行为的影响未经真人实测，故本轮不凭猜修改，只登记在案：

1. <clipitem><duration> 口径——真实产物自身就不统一（有的写素材总时长、有的写本段长度），RVE 写"本段长度"，与其中一派一致，不能据此判定不合规；

2. <timecode> 缺 <source> 子元素——真实产物普遍有，但多数 NLE 容忍，是否必需未实测；

3. 音频 clipitem 缺 <link> 与视频互链——真实产物普遍有，是否必需未实测。

模拟真人导入（无 NLE 环境下的代理验收）

本项目唯一无法在仓库内闭环的验收项，是「真人在 Premiere / Resolve 里导入 FCP7 XML，打开时间线面板，核对镜头数 / 总时长 / 转场数」——本机没有任何 NLE，CI 也是 headless。

RVE 的做法是换基准，而不是降低断言：用 ffmpeg 造一段真值在设计期就完全已知的合成素材，再让一个不 import rve.* 的独立解析器站在 NLE 的位置只吃 XML 重建时间线，逐项与素材的设计真值比对。

python scripts/make_nle_ground_truth.py --out /tmp/fixture      # 造素材 + 真值
rve analyze /tmp/fixture/nle_fixture.mp4 --out /tmp/out        # 产出 FCP7 XML
python scripts/simulate_nle_import.py /tmp/out/*.fcp7xml.xml \
    --expect /tmp/fixture/ground_truth.json --html /tmp/panel.html

素材设计（30fps，帧数精确可算）：纯红 2.0s → SMPTE 彩条 1.5s → 纯绿 1.2s → 纯蓝 1.0s → 纯黄 1.0s（0.5s 溶解）→ 纯黑 1.0s（0.5s 淡出），总长 7.2s / 216 帧。

真值用内容事件表述，而不是「镜头起点」：3 处硬切点 + 2 段转场时间窗。因为渐变区算前一镜、算后一镜、还是单独成一镜，本身是约定而非事实——把它当断言会一碰就碎；而「硬切点必须出现在 X」「转场必须落在 X 这段时间窗里」是素材侧不容争辩的事实。

模拟器逐项核对的，正是人工在时间线面板上会看的那几件事：

本机实跑：9/9 全部通过——总长 216 帧 = 7.200s、3 处硬切全部命中、2 处转场均落在设计窗口内、6 个片段素材全部在线、音轨 6 对 6。--html 会产出一份可单独打开的时间线面板（视频轨 + 音轨 + 转场标记 + 核对表），用来替代「真人打开面板看一眼」那一步。

⚠️ 这条证据链验证什么、不验证什么 它验证：FCP7 XML 的时间线语义能被一个独立实现正确重建，且与素材的设计真值一致。 它不验证：Premiere / Resolve 会不会接受这个 XML、会不会自动裁剪转场两侧的片段、effectid 取值会不会被正确识别。 真 NLE 导入仍需人工在装有 Premiere/Resolve 的机器上执行一次——步骤见 FAQ。

EditSpec 契约（唯一权威结构）

EditSpec 是整条流水线的中心产物，契约由 src/rve/schema/editspec.py 强制：

• 纯时间锚定：所有时间字段都是秒（in_sec/out_sec/duration_sec…），不存时间码。秒↔时间码的唯一换算发生在 src/rve/exporters/ 内，形成单一事实来源。

• extra="forbid"：所有结构模型继承自 Strict，未知字段一律拒绝 —— 防止 schema 静默漂移（这也是并发协作时的接口防漂移锁）。

• 镜头铺满不变量：shots 必须连续、无重叠、铺满整条时间轴，否则校验失败、拒绝产出。这条不变量正是"导出到 NLE 后出现空洞或重叠"的根因拦截点。

• 存疑显式化：拿不准的结论进 uncertain[]，不用默认值蒙混。

导出格式

CLI --format 只接受上面三个取值（cli.py 的 _EXPORT_FORMATS）；同样这三个也通过 MCP export_timeline 触达。未实现的取值显式报错而非产出半成品——这是 RVE 的硬规矩：绝不 quietly succeed。

诚实的局限（Phase 0）

RVE 只对能验证的事负责。下表把「不可承诺项」说清：

FAQ

任何支持本地 MCP server 的 Agent。RVE 以 stdio 启动，入口是 python -m rve.mcp.server；把它登记进你 Agent 的 MCP 配置即可（见接入你的 Agent）。

本机需要 Python 3.11/3.12/3.13 加 ffmpeg（含 ffprobe） 并加入 PATH。scenedetect、mcp 与 opentimelineio 都是运行期依赖（pyproject.toml 的 dependencies），随安装一并带入。先跑 rve doctor 确认。

不能。RVE 尚未发布到 PyPI，请勿相信任何 pip install rve 的指引。当前只能从 git 装源码，或安装本地构建的 wheel。

不会。RVE 全程在本地分析，只有你的 Agent 收到工具结果；你的模型服务商另有自己的数据政策。

FCP7 XML 是主要出口，结构上满足 xmeml 契约（交付闸门 S4 全部通过），但真人用 Premiere / Resolve 真导入实测尚未完成——这是当前唯一未闭环的验收项：RVE 能在本地产出结构正确的 XML，并由不 import rve.* 的第二实现独立回读，但「剪辑软件是否真的接受它」只能由真人打开软件确认。EDL 不承载变速、滤镜与字幕（转场以 D+帧数表达），仅作最小链路验证；OTIO 作为中间层。

自己动手验证（3 步，约 2 分钟）：

# 1) 生成 FCP7 XML（<spec_id>.fcp7xml.xml 落在 out/）
rve analyze path/to/final_cut.mp4 --out out/

2. 在 Premiere（文件 → 导入）或 Resolve（文件 → 导入 → 时间线）打开 out/<spec_id>.fcp7xml.xml；

3. 核对时间线的镜头数、总时长、转场数量是否与 rve specs 中该 spec 的 shots / transition 一致。

导入失败或与 spec 不符时，请开 issue 并附上该 XML——这正是本项目最需要、也最缺的那份证据。

仓库内已有一个代理验收：闸门 S11 会造一段真值在设计期就完全已知的合成素材，再让一个不 import rve.* 的独立解析器站在 NLE 的位置只吃 XML 重建时间线，逐项与素材真值比对（本机实跑 9/9 通过）。它验证的是「XML 的时间线语义能被独立实现正确重建」，不能替代真人导入——软件是否接受这个 XML，仍然只能靠上面那 3 步。详见模拟真人导入。

因为产出不能被导入的半成品，比明确报错更糟。RVE 的规矩是"失败必须可见"：未实现的能力以退出码 2 报错，绝不 quietly succeed。

analyze_audio、describe_shots 等工具名已注册，但实现属 Phase 2，调用即 NotImplementedError。工具名存在不代表能力可用——以诚实的局限表为准。

文档

先看仓库里的：

• 调研分析报告：为什么收敛为 C 型，以及差异化定位。

• 贡献指南：开发环境、跑测试、提 PR 的顺序与硬性约定。

• 交付验收：十四阶段交付闸门，末行 RESULT: PASS|FAIL。

• 独立校验器 与 真实 NLE 产物对标发现：不 import rve 的第二实现，以及 9 份真实样本的结构差异清单。

• CI：ubuntu-latest，Python 3.11/3.12/3.13 矩阵。

• EditSpec 契约 与 导出格式：结构不变量与各格式状态。

Star history

RVE 还年轻。如果它对你有用，欢迎点个 Star。

Disclaimer（免责声明）

RVE 用于对你拥有或已获授权的视频做合法研究、学习与剪辑工程还原。请勿用它处理无权分析的内容。

RVE 不包含、也不授权任何上游工具（FFmpeg、PySceneDetect、OpenTimelineIO 等）的许可；使用这些工具须遵守各自的许可条款。

贡献

欢迎参与 RVE！开 issue 报 bug 或提建议，或发 pull request 改进代码与文档。

动手前请先读 CONTRIBUTING.md，并遵守硬性约定：不 vendor 上游源码、EditSpec 契约不可松、失败不吞。

许可证

MIT。

RVE 自有代码以 MIT 授权。第三方材料保留其各自的许可与版权声明。