mb-rrvideo

mb-rrvideo 是用于将 rrweb 录制的数据转为视频格式的工具。基于rrvideo改进。最大区别在于支持多个任务同时输入以及输出为mp4格式（通过node的ffmpeg来处理。好处是不需要在外部处理ffmpeg。因为有些服务器上安装升级ffmpeg非常麻烦。

功能特性

• 支持将 rrweb 录制的 JSON 数据转换为视频文件
• 支持自定义输出视频的路径和文件名
• 支持通过配置文件对回放进行详细配置
• 支持多种输出格式，如 mp4 和 webm
• 提供录制和转换过程的进度显示
• 支持批量处理多个 rrweb 录制文件
• 自动处理文件名冲突
• 提供详细的耗时统计，包括单个文件处理耗时、webm 合成耗时、视频转换耗时以及总任务耗时
• 命令行界面友好，易于集成和使用
• 提供视频合并（merge）能力，支持本地与远程视频混合输入
• 下载与转码过程提供更细粒度的进度与速度/ETA 信息

安装与升级

首次安装

1. 确保您已安装 Node.JS (推荐最新稳定版)
2. 打开终端或命令行工具，执行以下命令全局安装 mb-rrvideo CLI：

npm install -g mb-rrvideo

本地升级

如果您已经安装了 mb-rrvideo，可以通过以下步骤进行升级：

1. 打开终端或命令行工具
2. 执行以下命令来更新 mb-rrvideo 到最新版本：

npm update -g mb-rrvideo

或者，您可以先卸载旧版本再安装新版本：

npm uninstall -g mb-rrvideo
npm install -g mb-rrvideo

验证安装

安装完成后，您可以通过以下命令验证是否安装成功：

rrvideos --help

本地开发快速安装

如果你是从源码仓库在本地直接运行或开发，可以在项目根目录按以下步骤进行快速安装：

• 在项目根目录执行：
  • npm ci
  • 如需只安装 Chromium（更快，避免 WebKit 提示）：npx playwright install chromium
• 提示说明：
  • 若出现 Corepack 询问是否下载 Yarn 的提示，输入 y 继续。
  • WebKit 冻结的警告仅影响 macOS 13 的 WebKit，不影响 Chromium 的使用。

使用方法

mb-rrvideo 主要通过命令行界面 (CLI) 进行操作。以下是一些常用的命令和参数：

基本用法

将单个 rrweb 录制数据文件（通常是 .json 或 .data 格式）转换为视频：

rrvideos --input <录制文件路径>

例如：

rrvideos --input ./record/events.json

默认情况下，这会在当前执行命令的目录下生成一个基于输入文件名的视频文件（例如：输入 events.json 会生成 events.mp4）。

指定输出路径和文件名

您可以使用 --output 参数指定输出视频的路径和文件名：

rrvideos --input <录制文件路径> --output <输出视频路径/文件名>

例如：

rrvideos --input ./record/events.json --output ./videos/my-recording.mp4

指定输出格式

您可以使用 --format 参数指定输出视频的格式，支持 mp4 (默认) 和 webm：

rrvideos --input <录制文件路径> --format webm

例如，输出 webm 格式：

rrvideos --input ./record/events.json --output ./videos/my-recording.webm --format webm

批量处理文件

mb-rrvideo 支持同时处理多个输入文件。您可以多次使用 --input 参数，并对应多次使用 --output 参数来指定每个输入文件对应的输出文件名。

rrvideos --input <文件1> --input <文件2> --output <输出1> --output <输出2>

例如：

rrvideos --input ./record/session1.json --input ./record/session2.json --output ./output/session1.mp4 --output ./output/session2.mp4

如果不提供 --output 参数，程序会基于各输入文件的基本文件名生成输出文件名：例如 events1.json → events1.mp4、events2.json → events2.mp4。

若多个输入文件的基本文件名相同（例如不同目录下都叫 events.json），则自动在后续文件的输出名后追加 -1、-2 等后缀以避免冲突：

rrvideos --input ./a/events.json --input ./b/events.json
# 生成: ./a/events.mp4 与 ./b/events-1.mp4

当同时传入多个 --input 且仅提供一个字符串形式的 --output 时，程序会在该输出名的基础上按输入文件名追加后缀，形如：<output_base>-<input_basename>.<format>，以避免覆盖。

使用配置文件

对于更复杂的播放器配置（例如调整播放器尺寸、播放速度等），您可以通过一个 JSON 配置文件来实现。

rrvideos --input <录制文件路径> --config <配置文件路径>

配置文件的格式可以参考 rrvideo.config.example.json 文件。该文件通常包含 rrweb-player 的配置选项。

一个简单的配置文件示例 (my-config.json)：

{
  "width": 1920,
  "height": 1080,
  "speed": 2
}

然后使用命令：

rrvideos --input ./events.json --config ./my-config.json

其他参数

• --headless <true|false>: 是否以无头模式运行浏览器进行录制 (默认为 true)
• --resolutionRatio <0-1>: 分辨率比例，影响视频质量 (默认为 0.8)
• --speed <number>: 回放速度倍数，用于加速录制过程以提高处理效率 (默认为 1)。正常来说不建议改这个参数，因为加速后的视频还原回来也很奇怪

视频合并（merge）

除 rrweb 录制转换外，CLI 还支持合并多个视频文件，输入源可混合本地路径与远程 URL，并在处理前自动下载远程文件。支持 mp4 与 webm 输出，以及自动选择合并策略。

基本用法

rrvideos merge --videos <视频1,视频2,...> --output <输出文件>

• --videos 支持：
  • 多次传入：--videos a.mp4 --videos b.webm
  • 逗号分隔：--videos "a.mp4,b.webm,https://example.com/v.mp4"
  • 读取列表文件：--videos-file list.txt（按行列出，支持以 # 开头的注释）
• 输出文件通过 --output 指定，必须存在且为目标文件路径。

常用参数（合并）

• --format <mp4|webm>：输出格式，默认 mp4
• --method <auto|demuxer|reencode>：合并策略
  • auto：自动选择；配合 --auto-mode <resolution|strict>
  • demuxer：无重编码拼接（等参数视频）
  • reencode：重编码拼接（统一编码与参数）
• --auto-mode <resolution|strict>：自动模式依据
  • resolution（默认）：分辨率一致则优先 demuxer
  • strict：需宽高、编解码、帧率完全一致才走 demuxer
• 编码控制：--codec、--crf、--preset、--fps、--resolution、--audio <copy|reencode>
• 下载控制：--download-dir、--concurrency、--retries、--timeout、--headers key:value
• 行为控制：--overwrite、--no-cleanup、--verbose、--quiet

进度与日志（合并）

• 下载进度：实时显示已下载大小、总大小、百分比、平均速度与 ETA（每 ~500ms 更新一次）
• FFmpeg 进度：改为基于 timemark 与总时长估算，保证百分比在 0–100% 间合理变化；无法估算时回退到 FFmpeg 自带百分比
• 合并顺序：严格保留输入顺序（包括并发远程下载后的本地落盘顺序）
• concat 列表：在启动 FFmpeg 前打印 concat 文件路径与其内容，便于核对（--quiet 时不打印）

示例

1. 合并两个远程视频并重编码为 MP4：

rrvideos merge \
  --videos "https://www.w3schools.com/html/mov_bbb.mp4,https://www.w3schools.com/html/mov_bbb.mp4" \
  --output ./tmp/merge_test.mp4 \
  --method reencode --format mp4 --verbose

2. 远程 + 本地混合输入，自动选择策略：

rrvideos merge \
  --videos "./local/a.mp4,https://example.com/b.webm" \
  --output ./tmp/mixed_auto.mp4 \
  --method auto --auto-mode resolution

3. 静默模式与自定义下载并发/重试：

rrvideos merge \
  --videos-file ./videos.list \
  --output ./tmp/list_out.webm \
  --format webm --quiet \
  --concurrency 4 --retries 3 --timeout 300000

4. 携带请求头下载远程视频：

rrvideos merge \
  --videos "https://example.com/a.mp4" \
  --output ./tmp/a_out.mp4 \
  --headers "Authorization:Bearer xxx" --headers "User-Agent:mb-rrvideo"

下载与转码进度

为提升大型文件与长时间转码的可观测性，新增以下进度与日志能力：

• 远程下载：
  • 显示已下载与总大小、百分比、平均速度（字节单位自适配）与 ETA
  • 对 Content-Length 不可用的情况自动回退为“已下载大小 + 速度”展示
  • 日志频率控制：默认 ~500ms 更新一次；--quiet 仅关键提示；--verbose 包含更详细上下文
• FFmpeg 合并与转换：
  • 进度使用 timemark 与已探测的输入总时长估算，更准确避免“百分比异常上涨”
  • 当无法探测或媒体损坏时，回退到 FFmpeg 自带 progress.percent
  • 在 convertVideo、runDemuxerConcat、runReencodeConcat 内部均统一为上述策略

注意事项（合并）

• demuxer 仅适用于参数完全一致或符合自动模式判断的情况，否则请使用 reencode
• 某些远程源可能缺失 Content-Length 或出现重定向；日志会提示并自动跟随
• 如果输入媒体损坏或元数据异常，进度估算可能轻微偏差；最终完成时间以 FFmpeg 实际完成为准

命令行参数概览

| 参数 | 描述 | 示例值 | | ------------------- | -------------------------------------------------------------------- | -------------------------------------------- | | --input | 指定一个或多个输入的 rrweb 事件文件路径 (必需) | ./data/events.json | | --output | 指定一个或多个输出视频文件的路径/文件名 | ./video/output.mp4 | | --format | 指定输出视频的格式 (可选, 默认为 mp4) | webm, mp4 | | --config | 指定 rrweb播放器配置文件的路径 (可选) | ./rrvideo.config.json | | --headless | 是否以无头模式运行浏览器 (可选, 默认为 true) | false | | --resolutionRatio | 视频分辨率缩放比例，0到1之间 (可选, 默认为 0.8) | 1 |

日志输出与耗时统计

mb-rrvideo 在处理过程中会输出详细的日志信息，包括：

• 任务开始和结束时间
• 单个文件处理的开始和结束
• WebM 视频合成的耗时
• 视频格式转换（例如 WebM 到 MP4）的耗时
• 单个任务的总耗时
• 所有任务完成或失败后的总耗时

进度条会显示当前录制回放和视频转换的进度。

在使用 merge 时，额外的下载与转码日志会按前述“下载与转码进度”部分进行显示。

示例

1. 将单个文件转换为默认名称的 MP4：

rrvideos --input ./path/to/your/events.json

2. 将单个文件转换为指定名称和格式的 WebM：

rrvideos --input events.json --output my_video.webm --format webm

3. 批量转换多个文件，自动生成输出文件名：

rrvideos --input file1.json --input file2.data

4. 批量转换多个文件，并指定各自的输出文件名：

rrvideos --input r1.json --input r2.json --output video1.mp4 --output video2.mp4

5. 使用配置文件进行转换：

rrvideos --input recording.json --config player-settings.json

事件重排（rearrangeEvents）

为避免视频中出现超长空白区间，程序会在处理开始阶段对 rrweb 事件进行“重排”以优化时间轴：

• 分组规则：将相邻事件按照时间间隔进行分组，默认阈值为 1 分钟（60 * 1000ms）。超过阈值则开启新分组。
• 组内间隔：保留组内事件的原始间隔，确保同一段回放的节奏不变。
• 组间间隔：使用上一组的平均间隔作为组间过渡时间，压缩过长停顿，提升整体观感。
• 属性清理：移除事件中的 delay 属性（原始数据并未使用该属性）。

效果与日志：

• 程序会输出“原始视频长度”和“重排后视频长度”，帮助评估重排对总时长的影响。
• 在存在长时间空白的录制数据中，重排通常可显著缩短视频时长并消除冗长黑屏段。

注意事项：

• 事件重排为默认开启，目前未提供关闭开关；若对时间戳绝对准确性有严格要求，请在数据采集层面保证录制过程中不出现超长间隔。
• 重排不会更改事件顺序，仅调整时间戳，组内节奏保持不变。

注意事项

• FFmpeg 依赖已通过 @ffmpeg-installer/ffmpeg 自动处理，无需手动安装
• 处理非常大的 rrweb 事件文件可能需要较长时间和较多系统资源
• 输出目录需要有写入权限
• 建议在处理大量文件时确保有足够的磁盘空间

技术依赖

• Node.js (推荐最新稳定版)
• Playwright (用于浏览器自动化)
• FFmpeg (已通过 @ffmpeg-installer/ffmpeg 自动处理，无需手动安装)
• rrweb-player (用于回放录制的事件)

视频合并（merge）

mb-rrvideo 支持独立的“视频合并”功能，使用 ffmpeg 将多个本地或远程视频合并为一个输出文件。该功能与 rrweb 转视频功能完全独立，通过子命令 merge 调用。

基本用法

• 合并多个本地视频：

rrvideos merge --videos ./a.mp4 --videos ./b.mp4 --output ./out/merged.mp4

• 支持混合远程 URL 与本地路径：远程文件会先下载到本地再合并。

rrvideos merge --videos https://example.com/a.mp4 --videos ./b.webm --output ./out/merged.mp4

• 从列表文件读取（每行一个路径或 URL）：

rrvideos merge --videos-file ./merge-list.txt --output ./out/merged.mp4

逗号分隔输入（便捷方式）

为简化多文件输入，--videos 支持逗号分隔的列表字符串（建议整体用引号包裹）：

rrvideos merge --videos './a.mp4,./b.webm,https://example.com/c.mp4' --output ./out/merged.mp4

注意：若某条目自身包含逗号，请改用重复传参 --videos 或使用 --videos-file，避免误拆分。

合并参数

• --videos 或 -v：输入视频，支持重复传入多个或逗号分隔字符串；支持本地路径与 http/https URL。
• --videos-file：包含视频列表的文本文件，每行一个路径或 URL。
• --output 或 -o：合并输出文件路径（必填）。
• --format 或 -f：输出格式，mp4（默认）或 webm。
• --method：合并策略，auto（默认）、demuxer、reencode。
  • auto：自动检测（默认按“分辨率一致”走 demuxer，否则转码）。
  • demuxer：要求输入的编码、分辨率、帧率一致，走“流复制”（更快）。
  • reencode：强制转码统一到指定格式参数（更稳）。
• --auto-mode：resolution（默认，仅检测分辨率一致即可流复制）或 strict（编码、音频、分辨率、帧率全部一致才流复制）。
• --codec：视频编码器（默认 libx264 for mp4，libvpx-vp9 for webm）。
• --crf：质量因子（默认 23，范围常用 18–28，数值越低质量越高）。
• --preset：编码速度/质量平衡（默认 fast，范围 ultrafast–veryslow）。
• --fps：统一帧率（如 30），可选。
• --resolution：统一分辨率（如 1920x1080），可选。
• --audio：音频处理策略，默认 copy（能复制则复制，否则可能转码）。
• --download-dir：远程视频临时下载目录，默认 __rrvideos__temp__/merge_downloads。
• --concurrency：下载并发数，默认 4。
• --retries：下载重试次数，默认 3。
• --timeout：单文件下载超时（毫秒），默认 300000。
• --headers：远程下载自定义请求头，形如 key:value，可重复。
• --overwrite：允许覆盖已存在的输出文件。
• --no-cleanup：保留下载的临时文件，默认自动清理。
• --verbose/--quiet：控制日志详细程度。

示例

• 自动策略合并为 mp4：

rrvideos merge -v ./a.mp4 -v ./b.webm -o ./out/merged.mp4 -f mp4

• 严格“流复制”方式（要求参数一致）：

rrvideos merge -v ./part1.mp4 -v ./part2.mp4 -o ./out/merged.mp4 --method demuxer

• 强制转码统一分辨率与帧率：

rrvideos merge -v ./a.mp4 -v ./b.mp4 -o ./out/merged.mp4 --method reencode --resolution 1920x1080 --fps 30

• 逗号列表（条目不含逗号时）：

rrvideos merge --videos 'https://cdn/site/a.mp4,./b.mp4' --output ./out/merged.mp4

日志输出

合并过程会输出：下载进度（远程）、输入分析、合并阶段 FFmpeg 进度，以及成功/失败与总耗时统计。

版本信息

当前版本：1.0.1

许可证

MIT License