LeRobot documentation
ストリーミング動画エンコーディングガイド
ストリーミング動画エンコーディングガイド
1. 概要
ストリーミング動画エンコーディングにより、動画データセットの録画時の従来のPNG往復が不要になります。従来の方法では:
- フレームをキャプチャ -> PNGをディスクに書き込み -> (エピソード終了時) PNGを読み込み -> MP4にエンコード -> PNGを削除
フレームはキャプチャ中にリアルタイムでエンコードできます:
- フレームのキャプチャ -> エンコーダースレッドへのキューイング -> MP4への直接エンコード
これにより、save_episode()はほぼ即時に実行されるようになります（エピソードが終了する時点で動画はすでにエンコード済みです）。また、以前はエピソード間で発生していたブロッキングの待機が解消され、特に長時間のエピソードで複数のカメラを使用する場合にその効果が顕著です。
2. パラメータの調整
| パラメータ | CLIフラグ | 型 | デフォルト | 説明 |
|---|---|---|---|---|
streaming_encoding | --dataset.streaming_encoding | bool | False | キャプチャ中にリアルタイムエンコーディングを有効にする |
vcodec | --dataset.rgb_encoder.vcodec | str | "libsvtav1" | ビデオコーデック。"auto"は最適なHWエンコーダーを検出します |
encoder_threads | --dataset.encoder_threads | int \| None | None（自動） | エンコーダーインスタンスあたりのスレッド数。Noneの場合、vcodedが決定します |
encoder_queue_maxsize | --dataset.encoder_queue_maxsize | int | 30 | カメラごとのバッファリングされる最大フレーム数(30fpsで約1秒分)。RAMを消費します |
3. 性能に関する考慮事項
ストリーミングエンコーディングとは、キャプチャループの最中にCPUが動画をエンコードすることを意味します。これにより、次の間で共有されなければならないCPU予算が生まれます。
- 制御ループ（カメラの読み取り、ロボットの制御、非動画データの書き込み）
- エンコーダースレッド（カメラごとに1つのプール）
- 可視化の再実行（有効な場合）
- OSおよびその他のプロセス
解像度とカメラ台数の影響
| セットアップ | スループット（px/sec） | CPUエンコーディングの読み込み | 注記 |
|---|---|---|---|
| 2camsx 640x480x3 @30fps | 55M | 低 | ほとんどのシステムで動作します |
| 2camsx 1280x720x3 @30fps | 165M | 中程度 | モダンなシステムで快適に動作 |
| 2camsx 1920x1080x3 @30fps | 373M | 高 | 高性能なハイエンドCPUが必要です |
encoder_threadsのチューニング
このパラメータは、各エンコーダーインスタンスが内部で使用するスレッド数を制御します:
- 高い値（例：4〜5）：エンコード速度が速くなりますが、カメラごとに多くのCPUコアを使用します。コア数が豊富なハイエンドシステムに適しています。
- 低い値（例：1〜2）：カメラごとのCPU使用量が少なくなり、キャプチャや可視化のコアを確保できます。低解像度の画像や高性能なCPUに適しています。
None(デフォルト): コーデックに決定を委ねます。利用可能な情報はコーデックのログにあります。
バックプレッシャーとフレームのドロップ
各カメラには有界キュー（encoder_queue_maxsize、デフォルトは30フレーム）があります。エンコーダーが処理に追いつかない場合:
- キューが埋まっていく（RAMを消費する）
- 新しいフレームは破棄されます（ブロックされません）— キャプチャループは中断されずに続行されます
- 警告が記録されます:
"Encoder queue full for {camera}, dropped N frame(s)" - エピソード終了時、カメラごとの合計ドロップフレーム数が報告されます
エンコーダーの遅延の兆候
- システムがカクカクしてフリーズする: すべての CPU が 100% になっています
- ログ内のドロップフレーム警告、または記録されたデータセットで期待値を下回るフレーム数/FPS
- ロボットの動きがぎこちない: CPU が深刻に過負荷状態にある場合、キャプチャループにも影響が出る可能性があります
- 蓄積された再実行ラグ: 可視化がリアルタイムに追いつかない
4. ハードウェアアクセラレーションによるエンコーディング
使用タイミング
次の場合は、HWエンコーディングを使用してください：
- CPUがボトルネック（フレームドロップ、ロボットの動作がカクカクする、rerunの遅延）
- 互換性のあるハードウェア（GPUまたは専用エンコーダー）をお持ちです
- 高スループット（高解像度または多数のカメラ）で記録しています
コーデックの選択
| コーデック | CPU使用率 | ファイルサイズ | 品質 | 注記 |
|---|---|---|---|---|
libsvtav1（デフォルト） | 高 | 最小 | ベスト | デフォルト。最も高い圧縮率ですが、CPU負荷も最大です |
h264 | 中程度 | 約30〜50%大きい | 良い | ソフトウェア H.264。CPU負荷の低減 |
| HWエンコーダー | 非常に低い | 最大 | 良い | 専用ハードウェアにオフロードします。CPUリソースが制約されているシステムに最適です |
利用可能なHWエンコーダー
| エンコーダー | プラットフォーム | ハードウェア | CLI 値 |
|---|---|---|---|
h264_videotoolbox | macOS | Apple Silicon / Intel | --dataset.rgb_encoder.vcodec=h264_videotoolbox |
hevc_videotoolbox | macOS | Apple Silicon / Intel | --dataset.rgb_encoder.vcodec=hevc_videotoolbox |
h264_nvenc | Linux/Windows | NVIDIA GPU | --dataset.rgb_encoder.vcodec=h264_nvenc |
hevc_nvenc | Linux/Windows | NVIDIA GPU | --dataset.rgb_encoder.vcodec=hevc_nvenc |
h264_vaapi | Linux | Intel/AMD GPU | --dataset.rgb_encoder.vcodec=h264_vaapi |
h264_qsv | Linux/Windows | Intel Quick Sync | --dataset.rgb_encoder.vcodec=h264_qsv |
auto | すべて | 利用可能なHWエンコーダをシステムにクエリします。HWエンコーダが見つからない場合はlibsvtav1にフォールバックします | --dataset.rgb_encoder.vcodec=auto |
HWアクセラレーション対応エンコーダーを使用するには、GPUドライバーのアップグレードが必要な場合があります。
libsvtav1がデフォルトであるのは、最も優れた学習パフォーマンスを提供するためです。他のvcodecsはCPU使用量を削減し、より高速になる場合がありますが、通常はファイルサイズが大きくなり、学習時間に影響を与える可能性があります。
5. トラブルシューティング
| 症状 | 考えられる原因 | 修正 |
|---|---|---|
| システムがフリーズする、ロボットの動作がぎこちなくなる、またはRerunのビジュアライゼーションが遅延する | CPUが逼迫（負荷使用率100%） | 他のアプリを閉じ、エンコードのスループットを下げ、encoder_threadsを減らし、h264を使用し、display_data=Falseを使用してください。CPUが引き続き100%のままの場合、お使いの環境では性能が不足している可能性があります。--dataset.streaming_encoding=falseまたはHWエンコード（--dataset.rgb_encoder.vcodec=auto）を検討してください。 |
| データセットにおける「Encoder queue full」の警告やフレームのドロップ | エンコーダーが追いついていない（キューのオーバーフロー） | CPUが100%に達していない場合: encoder_threadsを増やす、encoder_queue_maxsizeを増やす、またはHWエンコーディングを使用する(--dataset.rgb_encoder.vcodec=auto)。 |
| RAM使用量が高い | エンコードよりキューの充填が速い | encoder_threads が低すぎるか、CPU が不足しています。encoder_queue_maxsize を減らすか、HW エンコーディングを使用してください。 |
| 大規模な動画ファイル | HWエンコーダーまたはH.264の使用 | 想定されるトレードオフ。CPUが許可している場合はlibsvtav1に切り替えてください |
save_episode() がまだ遅い | streaming_encoding は False です | --dataset.streaming_encoding=true を設定します |
| エンコーダースレッドのクラッシュ | コーデックが利用できないか、設定が無効です | vcodecがインストールされていることを確認し、--dataset.rgb_encoder.vcodec=autoを試してください。 |
| 記録されたデータセットにフレームが欠落しています | CPU/GPUの逼迫または一時的な負荷の急増 | フレームの約5%が欠落している場合、システムが過負荷状態である可能性が高いです。上記の推奨事項に従ってください。欠落しているフレームが少ない場合（約2%）、それは一時的な負荷の急増（起動時によく見られます）によるものと考えられ、想定内の範囲とみなすことができます。 |
6. 推奨設定
これらの推定値は保守的なものです。ご自身の環境でテストすることをお勧めします。低い負荷から開始し、徐々に負荷を上げていきましょう。
ハイエンドシステム: 最新の12コア以上(24スレッド以上)
CPUでのスループットは、約250〜500M px/sec程度であれば快適に動作するはずです。さらに良い結果を得たい場合は、利用可能な場合はHWエンコーディングを試してください。
# 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.rgb_encoder.vcodec=h264 --dataset.streaming_encoding=false ...7. 結びの言葉
パフォーマンスは最終的に、正確なセットアップ — フレームレート、解像度、CPU コア数と負荷、利用可能なメモリ、エピソードの長さ、選択したエンコーダー — に依存します。必ずターゲットのワークロードでテストし、CPU とシステム的能力に注意を払い、encoder_threads、encoder_queue_maxsize、vcodec を適切に調整してください。とはいえ、一般的な実用的な設定（多くのアプリケーションにおいて）は、640×480x3 @30fps の 3 台のカメラです。これは、モダンなシステムではデフォルトのストリーミング動画エンコード設定で通常問題なく動作します。記録されたデータセットが健全であることを確認するために、必ず動画の再生時間を CLI のエピソード時間と比較し、行数が FPS × CLI 時間と等しいことを確認してください。