Keep asset video by default for rerun visualization (#135)

Author: shuheng-liu

docs/source/tutorials/visualization.rst

@@ -9,8 +9,40 @@ The following example shows how to visualize the first episode (index 0) of the
 
    opentau-dataset-viz --repo-id lerobot/droid_100 --episode-index 0
 
+When the dataset is already available in a local directory, ``--repo-id`` is optional and you can point directly to it with ``--root``:
+
+.. code-block:: bash
+
+   opentau-dataset-viz --root ~/.cache/huggingface/lerobot/lerobot/droid_100 --episode-index 0
+
 This command will open a `rerun <https://rerun.io>`_ window displaying the selected episode, allowing you to explore the episode interactively.
 
+Camera Logging Mode
+-------------------
+
+For datasets that include camera streams stored as MP4 files, ``opentau-dataset-viz`` supports different camera logging modes:
+
+- ``frames``: logs decoded frames with ``rr.Image``.
+- ``asset_video``: logs source MP4 files with ``rr.AssetVideo`` and synchronizes playback using ``rr.VideoFrameReference``.
+- ``auto`` (default): same behavior as ``asset_video`` with graceful fallback to ``frames`` when MP4 assets or required Rerun APIs are unavailable.
+
+If your episodes contain one or more videos and the generated ``.rrd`` files are large, prefer ``asset_video`` (or ``auto``) to take advantage of video compression.
+
+.. code-block:: bash
+
+   # Prefer MP4 assets (smaller .rrd when videos are available)
+   opentau-dataset-viz --repo-id lerobot/droid_100 --episode-index 0 --camera-log-mode asset_video
+
+   # Always log decoded frames (existing behavior)
+   opentau-dataset-viz --repo-id lerobot/droid_100 --episode-index 0 --camera-log-mode frames
+
+To compare storage size, save both outputs and compare the resulting files:
+
+.. code-block:: bash
+
+   opentau-dataset-viz --repo-id lerobot/droid_100 --episode-index 0 --save 1 --output-dir ./rrd_frames --camera-log-mode frames
+   opentau-dataset-viz --repo-id lerobot/droid_100 --episode-index 0 --save 1 --output-dir ./rrd_asset --camera-log-mode asset_video
+
 OpenTau also supports visualizing a dataset with URDF models. To do this, you need to first install ``opentau`` with optional URDF support:
 
 .. code-block:: bash

src/opentau/datasets/lerobot_dataset.py

@@ -1694,11 +1694,21 @@ def save_episode(self, episode_data: dict | None = None) -> None:
             self.tolerance_s,
         )
 
-        video_files = list(self.root.rglob("*.mp4"))
-        assert len(video_files) == self.num_episodes * len(self.meta.video_keys)
-
-        parquet_files = list(self.root.rglob("*.parquet"))
-        assert len(parquet_files) == self.num_episodes
+        expected_episodes = self.meta.total_episodes
+        missing_videos: list[str] = []
+        for ep_idx in range(expected_episodes):
+            for vid_key in self.meta.video_keys:
+                video_path = self.root / self.meta.get_video_file_path(ep_idx, vid_key)
+                if not video_path.is_file():
+                    missing_videos.append(str(video_path))
+        assert not missing_videos, "Missing expected encoded videos:\n" + "\n".join(missing_videos)
+
+        missing_parquet: list[str] = []
+        for ep_idx in range(expected_episodes):
+            parquet_path = self.root / self.meta.get_data_file_path(ep_idx)
+            if not parquet_path.is_file():
+                missing_parquet.append(str(parquet_path))
+        assert not missing_parquet, "Missing expected parquet episode files:\n" + "\n".join(missing_parquet)
 
         # delete images
         img_dir = self.root / "images"