LeRobot 文件
串流視訊編碼指南
並獲得增強的文件體驗
開始使用
串流視訊編碼指南
1. 概覽
串流視訊編碼消除了視訊資料集錄製過程中傳統的 PNG 往返操作。與其執行
- 擷取影格 -> 將 PNG 寫入磁碟 -> (片段結束時) 讀取 PNG -> 編碼為 MP4 -> 刪除 PNG
不如在擷取期間即時編碼影格：
- 擷取影格 -> 加入編碼器執行緒佇列 -> 直接編碼為 MP4
這使得 save_episode() 幾乎能瞬間完成（片段結束時視訊已編碼完成），並消除了以往在片段之間發生的阻塞等待，對於長片段且有多個攝影機的情況尤其有效。
2. 調整參數
| 參數 | CLI 旗標 | 類型 | 預設 | 說明 |
|---|---|---|---|---|
streaming_encoding | --dataset.streaming_encoding | bool | True | 啟用擷取期間的即時編碼 |
vcodec | --dataset.vcodec | str | "libsvtav1" | 視訊編解碼器。"auto" 可偵測最佳硬體編碼器 |
encoder_threads | --dataset.encoder_threads | int | None | None (自動) | 每個編碼器實例的執行緒數。None 表示由編解碼器自行決定 |
encoder_queue_maxsize | --dataset.encoder_queue_maxsize | int | 60 | 每個攝影機的最大緩衝影格數（30fps 時約 2 秒）。會消耗記憶體 (RAM) |
3. 效能考量
串流編碼代表 CPU 正在擷取迴圈期間進行視訊編碼，而非之後。這會產生 CPU 預算限制，必須在以下處理程序間共享：
- 控制迴圈（讀取攝影機、控制機器人、寫入非視訊資料）
- 編碼器執行緒（每個攝影機一個執行緒池）
- Rerun 視覺化（若已啟用）
- 作業系統與其他處理程序
解析度與攝影機數量的影響
| 設定 | 輸送量 (px/sec) | CPU 編碼負載 | 備註： |
|---|---|---|---|
| 2 攝影機 x 640x480x3 @30fps | 55M | 低 | 適用於大多數系統 |
| 2 攝影機 x 1280x720x3 @30fps | 165M | 適中 | 在現代系統上運作流暢 |
| 2 攝影機 x 1920x1080x3 @30fps | 373M | 高 | 需要高效能 CPU |
encoder_threads 調整
此參數控制每個編碼器實例內部使用的執行緒數量
- 較高值（例如 4-5）：編碼速度更快，但每個攝影機消耗更多 CPU 核心。適用於擁有許多核心的高階系統。
- 較低值（例如 1-2）：每個攝影機消耗較少 CPU，為擷取與視覺化釋放核心。適用於低解析度影像與效能適中的 CPU。
None（預設值）：由編解碼器自行決定。詳細資訊請參見編解碼器日誌。
背壓與影格丟棄
每個攝影機都有一個有限的佇列（encoder_queue_maxsize，預設為 60 個影格）。當編碼器速度跟不上時：
- 佇列填滿（消耗記憶體）
- 新的影格會被丟棄（不會阻塞）— 擷取迴圈繼續不中斷
- 系統會記錄警告：
"Encoder queue full for {camera}, dropped N frame(s)" - 在片段結束時，會回報每個攝影機丟棄的影格總數
編碼器落後的徵兆
- 系統感到遲滯且凍結：所有 CPU 核心達到 100%
- 影格丟棄警告：日誌中出現警告，或者錄製的資料集中影格數/FPS 低於預期
- 機器人動作不連貫：如果 CPU 嚴重超載，甚至連擷取迴圈也可能受到影響
- 累積的 Rerun 延遲：視覺化進度落後於即時狀態
4. 硬體加速編碼
何時使用
在以下情況使用硬體加速 (HW) 編碼：
- CPU 成為瓶頸（出現丟棄影格、機器人動作不連貫、Rerun 延遲）
- 您擁有相容的硬體（GPU 或專用編碼器）
- 您正在以高輸送量錄製（高解析度或多攝影機）
選擇編解碼器
| 編解碼器 | CPU 使用率 | 檔案大小 | 品質 (Quality) | 備註： |
|---|---|---|---|---|
libsvtav1 (預設) | 高 | 最小 | 祝好 | 預設值。壓縮效果最好，但最消耗 CPU |
h264 | 中等 | 約大 30-50% | 良好 | 軟體編碼 H.264。CPU 消耗較低 |
| 硬體編碼器 | 極低 | 最大 | 良好 | 卸載至專用硬體。最適合 CPU 受限的系統 |
可用硬體編碼器
| 編碼器 | 平台 | 硬體 | CLI 值 |
|---|---|---|---|
h264_videotoolbox | macOS | Apple Silicon / Intel | --dataset.vcodec=h264_videotoolbox |
hevc_videotoolbox | macOS | Apple Silicon / Intel | --dataset.vcodec=hevc_videotoolbox |
h264_nvenc | Linux/Windows | NVIDIA GPU | --dataset.vcodec=h264_nvenc |
hevc_nvenc | Linux/Windows | NVIDIA GPU | --dataset.vcodec=hevc_nvenc |
h264_vaapi | Linux | Intel/AMD GPU | --dataset.vcodec=h264_vaapi |
h264_qsv | Linux/Windows | Intel Quick Sync | --dataset.vcodec=h264_qsv |
auto | Any | 自動探測系統中的可用硬體編碼器。若未找到，會退回至 libsvtav1 | --dataset.vcodec=auto |
為了使用硬體加速編碼器，您可能需要更新 GPU 驅動程式。
libsvtav1為預設值，因為它能提供最佳訓練效能；其他 vcodec 可降低 CPU 使用率並提升編碼速度，但通常會產生較大的檔案，並可能影響訓練時間。
5. 疑難排解
| 徵兆 | 可能原因 | 修正方法 |
|---|---|---|
| 系統凍結或機器人動作不連貫或 Rerun 視覺化延遲 | CPU 負載過高 (100% 使用率) | 關閉其他應用程式，降低編碼輸送量，調低 encoder_threads，使用 h264，使用 display_data=False。若 CPU 仍維持 100%，則代表硬體規格不足，請考慮 --dataset.streaming_encoding=false 或使用硬體編碼 (--dataset.vcodec=auto) |
| 「Encoder queue full」警告或資料集影格丟棄 | 編碼器跟不上 (佇列溢位) | 若 CPU 未達 100%：提高 encoder_threads，增加 encoder_queue_maxsize 或使用硬體編碼 (--dataset.vcodec=auto)。 |
| 高記憶體使用率 | 佇列累積速度快於編碼速度 | encoder_threads 太低或 CPU 效能不足。請減少 encoder_queue_maxsize 或使用硬體編碼 |
| 大型視訊檔案 | 使用硬體編碼器或 H.264 | 這是預期的取捨。若 CPU 允許，請切換至 libsvtav1 |
save_episode() 仍然緩慢 | streaming_encoding 為 False | 設定 --dataset.streaming_encoding=true |
| 編碼器執行緒當機 | 編解碼器不可用或設定無效 | 檢查是否已安裝 vcodec，嘗試 --dataset.vcodec=auto |
| 錄製的資料集遺失影格 | CPU/GPU 資源匱乏或突發性的負載峰值 | 若遺失約 5% 的影格，您的系統可能負載過重 — 請遵循上述建議。若遺失影格較少（約 2%），則通常是由於偶發性的暫時性負載（通常在啟動時）所致，屬於正常預期範圍。 |
6. 建議設定
這些估算值較為保守；我們建議在您的設置上進行測試——從低負載開始並逐步增加。
高階系統：現代 12+ 核心 (24+ 執行緒)
約 250-500M px/sec 的輸送量應能流暢運作。若想獲得更好的結果，請嘗試使用硬體編碼（如果可用）。
# 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
CPU 應能處理約 80-300M px/sec 的輸送量。
# 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 的做法，即在片段之間進行編碼（會阻塞，但不會干擾擷取）。或者，降低錄製輸送量以減輕擷取與編碼負載。也可考慮將編解碼器改為 h264 並使用批次編碼。
# 2camsx 640x480x3 @30fps: Requires some tuning.
# Use H.264, disable streaming, consider batching encoding
lerobot-record --dataset.vcodec=h264 --dataset.streaming_encoding=false ...7. 結語
效能最終取決於您的確切設定——影格速率 (FPS)、解析度、CPU 核心與負載、可用記憶體、片段長度以及您選擇的編碼器。請務必針對您的目標工作負載進行測試，留意您的 CPU 與系統能力，並合理調整 encoder_threads、encoder_queue_maxsize 與 vcodec。話雖如此，常見的實用配置（針對許多應用）是三個 640x480x3 @30fps 的攝影機；這在現代系統上通常能透過預設的串流視訊編碼設定順利運作。請務必透過比較視訊持續時間與 CLI 片段持續時間，並確認總影格數等於 FPS × CLI 持續時間，來驗證您錄製的資料集是否完整健康。