流式视频编码指南

1. 概览

流式视频编码消除了视频 dataset 录制过程中传统的 PNG 往返（round-trip）流程。不再需要：

  1. 捕获帧 -> 将 PNG 写入磁盘 ->（episode 结束时）读取 PNG -> 编码为 MP4 -> 删除 PNG

帧可以在捕获期间实时编码：

  1. 捕获帧 -> 入队到编码器线程 -> 直接编码为 MP4

这使得 save_episode() 几乎即时完成（episode 结束时视频已编码完毕），并消除了以前在 episode 之间出现的阻塞等待，尤其是在长时间 episode 中使用多个相机时。

2. 调优参数

参数CLI 标志类型默认值描述
streaming_encoding--dataset.streaming_encodingboolTrue在捕获期间启用实时编码
vcodec--dataset.rgb_encoder.vcodecstr"libsvtav1"视频编解码器。"auto" 会检测最佳的硬件编码器
encoder_threads--dataset.encoder_threadsint \| NoneNone（自动）每个编码器实例的线程数。设为 None 将由编解码器自行决定
encoder_queue_maxsize--dataset.encoder_queue_maxsizeint30每台相机的最大缓冲帧数（30fps 下约 1 秒）。会消耗内存

3. 性能注意事项

流式编码意味着 CPU 在捕获循环期间（而非之后）编码视频。这产生了一个必须由以下各方共享的 CPU 预算：

  • 控制循环（读取相机、控制机器人、写入非视频数据）
  • 编码器线程（每台相机一个池）
  • 重放可视化（如已启用）
  • 操作系统和其他进程

分辨率与相机数量的影响

配置吞吐量（像素/秒）CPU 编码负载说明
2camsx 640x480x3 @30fps55M低在大多数系统上均可运行
2camsx 1280x720x3 @30fps165M中等在现代化系统上运行舒适
2camsx 1920x1080x3 @30fps373M高需要强劲的高端 CPU

encoder_threads 调优

此参数控制每个编码器实例在内部使用的线程数：

  • 更高的值（例如 4-5）：编码更快，但每台相机消耗更多 CPU 核心。适合拥有多核心的高端系统。
  • 更低的值（例如 1-2）：每台相机消耗的 CPU 更少，为核心处理捕获和可视化留出余量。适合低分辨率图像和性能较强的 CPU。
  • None（默认）：由编解码器自行决定。可在编解码器日志中查看相关信息。

背压与丢帧

每台相机都有一个有界队列（encoder_queue_maxsize，默认 30 帧）。当编码器跟不上时：

  1. 队列被填满（消耗内存）
  2. 新帧会被丢弃（而非阻塞）——捕获循环继续不受干扰地运行
  3. 记录一条警告："Encoder queue full for {camera}, dropped N frame(s)"
  4. 在 episode 结束时，报告每台相机总共丢弃的帧数

编码器跟不上的症状

  • 系统感觉卡顿并冻结：所有 CPU 都处于 100%
  • 日志中出现丢帧警告，或录制 dataset 的帧数/FPS 低于预期
  • 机器人运动卡顿：如果 CPU 严重过载，即使捕获循环也可能受到影响
  • 重放累积滞后：可视化落后于实时

4. 硬件加速编码

何时使用

在以下情况使用硬件编码：

  • CPU 是瓶颈（丢帧、机器人卡顿、重放滞后）
  • 你拥有兼容的硬件（GPU 或专用编码器）
  • 你在以高吞吐量录制（高分辨率或使用多台相机）

选择编解码器

编解码器CPU 使用文件大小质量说明
libsvtav1（默认）高最小最佳默认。压缩率最好但最耗费 CPU
h264中等大约大 30-50%良好软件 H.264。CPU 占用更低
硬件编码器极低最大良好卸载到专用硬件。最适合 CPU 受限的系统

可用的硬件编码器

编码器平台硬件CLI 值
h264_videotoolboxmacOSApple Silicon / Intel--dataset.rgb_encoder.vcodec=h264_videotoolbox
hevc_videotoolboxmacOSApple Silicon / Intel--dataset.rgb_encoder.vcodec=hevc_videotoolbox
h264_nvencLinux/WindowsNVIDIA GPU--dataset.rgb_encoder.vcodec=h264_nvenc
hevc_nvencLinux/WindowsNVIDIA GPU--dataset.rgb_encoder.vcodec=hevc_nvenc
h264_vaapiLinuxIntel/AMD GPU--dataset.rgb_encoder.vcodec=h264_vaapi
h264_qsvLinux/WindowsIntel Quick Sync--dataset.rgb_encoder.vcodec=h264_qsv
auto任意探测系统中可用的硬件编码器。如果找不到硬件编码器，则回退到 libsvtav1--dataset.rgb_encoder.vcodec=auto

要使用硬件加速编码器，你可能需要升级 GPU 驱动程序。

libsvtav1 是默认选择，因为它能提供最佳的训练性能；其他 vcodec 可以降低 CPU 占用并更快，但它们通常会产生更大的文件，并可能影响训练时间。

5. 故障排查

症状可能的原因修复方法
系统冻结、机器人运动卡顿或重放可视化滞后CPU 资源不足（100% 负载使用率）关闭其他应用、降低编码吞吐量、调低 encoder_threads、改用 h264、使用 display_data=False。如果 CPU 持续处于 100%，则可能对你的配置来说不够用，请考虑 --dataset.streaming_encoding=false 或硬件编码（--dataset.rgb_encoder.vcodec=auto）
dataset 出现 “Encoder queue full” 警告或丢帧编码器跟不上（队列溢出）如果 CPU 未达到 100%：增大 encoder_threads、增大 encoder_queue_maxsize 或使用硬件编码（--dataset.rgb_encoder.vcodec=auto）。
内存占用过高队列填充速度快于编码速度encoder_threads 过低或 CPU 不足。减小 encoder_queue_maxsize 或使用硬件编码
视频文件过大使用了硬件编码器或 H.264这是预期的权衡。如果 CPU 允许，请改用 libsvtav1
save_episode() 仍然很慢streaming_encoding 为 False设置 --dataset.streaming_encoding=true
编码器线程崩溃编解码器不可用或设置无效检查 vcodec 是否已安装，尝试 --dataset.rgb_encoder.vcodec=auto
录制的 dataset 缺少帧CPU/GPU 资源不足或偶发负载尖峰如果约 5% 的帧缺失，你的系统可能已过载——请遵循上面的建议。如果缺失的帧较少（约 2%），则可能是偶发的瞬时负载尖峰（通常在启动时）所致，可以视为正常现象。

6. 推荐配置

这些估算偏保守；我们建议在你的环境中测试——从较低负载开始，并逐渐增加。

高端系统：现代 12+ 核心（24+ 线程）

约 250-500M 像素/秒的吞吐量在 CPU 上应该可以轻松实现。如果可用的话，尝试硬件编码以获得更好的结果。

# 3camsx 1280x720x3 @30fps: Defaults work well. Optionally increase encoder parallelism.
# 2camsx 1920x1080x3 @30fps: Defaults work well. Optionally increase encoder parallelism.
lerobot-record --dataset.encoder_threads=5 ...

# 3camsx 1920x1080x3 @30fps: Might require some tuning.

中端系统：现代 8+ 核心（16+ 线程）或 Apple Silicon

约 80-300M 像素/秒的吞吐量在 CPU 上应该可以做到。

# 3camsx 640x480x3 @30fps: Defaults work well. Optionally decrease encoder parallelism.
# 2camsx 1280x720x3 @30fps: Defaults work well. Optionally decrease encoder parallelism.
lerobot-record --dataset.encoder_threads=2 ...

# 2camsx 1920x1080x3 @30fps: Might require some tuning.

低资源系统：现代 4+ 核心（8+ 线程）或 Raspberry Pi 5

在资源非常受限的系统上，流式编码可能会与捕获循环过度争抢资源。禁用它将回退到基于 PNG 的方式，即在 episode 之间进行编码（阻塞，但不会干扰捕获）。另外，也可以以较低的吞吐量录制，以同时降低捕获和编码的负载。还可以考虑将编解码器改为 h264 并使用批量编码。

# 2camsx 640x480x3 @30fps: Requires some tuning.

# Use H.264, disable streaming, consider batching encoding
lerobot-record --dataset.rgb_encoder.vcodec=h264 --dataset.streaming_encoding=false ...

7. 结语

性能最终取决于你的具体配置——每秒帧数、分辨率、CPU 核心数与负载、可用内存、episode 时长，以及你选择的编码器。请始终用你的目标工作负载进行测试，注意 CPU 与系统能力，并合理地调整 encoder_threads、encoder_queue_maxsize 和 vcodec。话虽如此，一个常见且实用的配置（适用于许多应用）是三台相机以 640×480x3 @30fps 运行；在现代系统上，这通常可以配合默认的流式视频编码设置顺畅运行。请始终通过比较视频时长与 CLI episode 时长，并确认行数等于 FPS × CLI 时长，来验证录制的 dataset 是否健康。

在 GitHub 上更新