Video encoding parameters

ビデオストレージが有効な場合、LeRobotはタイムステップごとの画像ファイルを保存する代わりに、各カメラストリームをMP4ファイルとして保存します。ビデオエンコードは時間軸に沿って圧縮を行うため、PNGの山を扱う場合と比べて、通常はデータセットのサイズとI/Oを削減できます。また、MP4はすべてのプレイヤーやローダーが理解する形式であるため、互換性を保ちます。

MP4へのフレームエンコードは、エンコーダーの選択、ピクセルフォーマット、GOP/キーフレーム、品質と速度のバランス、および任意の追加エンコーダーフラグを含む、完全なFFmpegパイプラインです。これらの設定の多くは、PyAVを介して渡されるネストされたRGBEncoderConfig（lerobot.configs.video.RGBEncoderConfig）であるrgb_encoderを通じて、ユーザーが調整できます。

これらのパラメータは、--dataset.rgb_encoder.<field>（例：lerobot-recordまたはlerobot-rollout）を介してCLIから設定できます。このブロックは、その実行のすべてのカメラ映像ストリームに適用されます。

rgb_encoder が効果を発揮するには、ビデオの保存を有効にする必要があります — Python API では use_videos=True、CLI では --dataset.video=true（録画時のデフォルト値）を指定します。ビデオが無効の場合、入力は画像のままとなり、rgb_encoder は無視されます。

いつフレームが書き込まれるのか、エンコードされるのか（ストリーミングかエピソード後か）の詳細、キュー、およびその他のトップレベルの--dataset.*スイッチについては、Streaming Video Encodingを参照してください。エンコードパラメータの比較と実験については、video-benchmark Spaceを参照してください。

例

lerobot-record \
    --robot.type=so100_follower \
    --robot.port=/dev/tty.usbmodem58760431541 \
    --robot.cameras="{laptop: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
    --robot.id=black \
    --teleop.type=so100_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \
    --teleop.id=blue \
    --dataset.repo_id=<my_username>/<my_dataset_name> \
    --dataset.num_episodes=2 \
    --dataset.single_task="Grab the cube" \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2 \
    --dataset.rgb_encoder.vcodec=h264 \
    --dataset.rgb_encoder.preset=fast \
    --dataset.rgb_encoder.extra_options='{"tune": "film", "profile:v": "high", "bf": 2}' \
    --display_data=true

チューニングパラメータ

デフォルト値は、一般的なロボティクスデータセットにおいて圧縮率、視覚品質、デコード/シーク速度のバランスを取るよう調整されています。これらの値を変更すると、録画（CPU負荷、フレームドロップ）と学習（デコードスループット、画像品質）の両方に影響を与える可能性があります。

これらのパラメータを上書きするのは、明確な理由がある場合のみとし、新しい設定に依存する前に、パイプラインへの影響を測定してください。

以下のすべてのフラグは、CLI では --dataset.rgb_encoder. というプレフィックスが付与されます。

深度ストリーム

深度マップ（Intel RealSense、Reachy 2）は、RGB ストリームと並んで、独自のビデオストリームとして保存されます。生深度（uint16 のミリメートルまたは float32 のメートル）は 8 ビットコーデックでは保持できないため、LeRobot は各マップを 12 ビットコード（[0, 4095]）に量子化します。これはデフォルトで対数的に行われ、深度センサーの 1/depth エラープロファイルに合わせるためです。その後、高ビット深度のピクセルフォーマット（gray12le）にパッキングし、12 ビットコーデックでエンコードします。

並列のdepth_encoderブロック（DepthEncoderConfig）を通じて深度パイプラインを設定します。これはRGBEncoderConfigのすべてのフィールド（vcodec、pix_fmt、crf、…）を共有し、--dataset.depth_encoder.<field>で設定する4つの量子化パラメータを追加します。

lerobot-record \
    ... \
    --dataset.depth_encoder.vcodec=hevc \
    --dataset.depth_encoder.depth_min=0.05 \
    --dataset.depth_encoder.depth_max=5.0 \
    --dataset.depth_encoder.use_log=true

depth_min、depth_max、および shift は、入力深度の単位に関わらず、常にメートルとして解釈されます。入力は自動検出されます。整数配列（例: RealSense から直接取得した uint16 のミリメートル値）はミリメートルとして、浮動小数点配列はメートルとして扱われます。 depth_min / depth_max は、センサーの実際の動作範囲を囲むように設定してください。この範囲外の量子は飽和するため、境界部分の詳細が潰れてしまう可能性があります。

Depth機能はmeta/info.json内で"is_depth_map": trueとしてフラグ付けされ、その量子化設定（video.depth_min、video.depth_max、video.shift、video.use_log）が永続化されます。これにより、読み込み時にdepthを物理単位に逆量子化することが可能になります。

読み込み時の出力ユニット

depth_encoderは記録時の関心事です。読み込み（例：トレーニング中）時に深度マップがデクアンタイズされる単位は、読み込み時のフラグ--dataset.depth_output_unitによって別途設定されます：

lerobot-train \
    --dataset.repo_id=<my_username>/<my_dataset_name> \
    --dataset.depth_output_unit=m \
    --policy.type=act

これは純粋にデコード時の表示上の選択であり、変更しないため、保存された動画やそのメタデータは変わりません。そのため、同じデータセットを再エンコードせずにmmまたはmとして読み取ることができます。深度カメラを備えていないデータセットには影響しません。

データセットメタデータへの永続化

ビデオストリームの最初のエピソードがエンコードされると、エンコーダーの設定は、ファイル自体から取得された値とともに、各ビデオ機能の下でデータセットのメタデータに永続化されます（meta/info.json）。ビデオ機能observation.images.<camera>の場合、info.json内のレイアウトは以下の通りです。

{
  "features": {
    "observation.images.laptop": {
      "dtype": "video",
      "shape": [480, 640, 3],
      "info": {
        "video.height": 480,
        "video.width": 640,
        "video.codec": "h264",
        "video.pix_fmt": "yuv420p",
        "video.fps": 30,
        "video.channels": 3,
        "is_depth_map": false,
        "video.g": 2,
        "video.crf": 30,
        "video.preset": "fast",
        "video.fast_decode": 0,
        "video.video_backend": "pyav",
        "video.extra_options": { "tune": "film", "profile:v": "high", "bf": 2 }
      }
    }
  }
}

infoブロックには、2つのソースが寄与します:

このブロックは、最初のエピソードから一度だけ設定されます。データセット内のすべてのエピソードが同じrgb_encoderでエンコードされていることを前提としています。録画中にエンコーダーの設定を変更することはサポートされていません。info.jsonには、最初のエピソードで使用されたパラメータのみが反映されます。

データセットのマージ

merge_datasetsでデータセットをアグリゲーションする際、動画ファイルはそのまま連結されます（再エンコードは行われません）。また、info.json内のエンコーダーフィールドはキーごとにマージされます。