Recording Video

Isaac Lab can record video from a Kit or Newton GL visualizer, or directly from a scene camera sensor, by adding VideoRecorderCfg entries to the environment config. Each recorder captures from a configurable source and writes mp4 clips to disk independently. Streaming visualizers (Rerun, Viser) and the Newton RTX backend do not support frame capture; see Visualizer compatibility below.

from isaaclab.envs.utils.video_recorder_cfg import VideoRecorderCfg

env_cfg.video_recorders = [
    VideoRecorderCfg(source="visualizer:kit", output_dir="videos/")
]

This guide is accompanied by the run_video_recording.py tutorial script in IsaacLab/scripts/tutorials/07_visualizers. Pass --example 1, --example 2, or --example 3 to select which recording configuration to run.

Code for run_video_recording.py

# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
# All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause

"""Tutorial: recording video from visualizers and scene sensors.

This script demonstrates three progressively richer recording configurations,
all using the Shadow Hand cube-reorientation task
(``Isaac-Reorient-Cube-Shadow-Camera-Direct``).

Example 1 — Kit viewport (simplest)
    One clip from the Kit interactive viewport, showing 4 parallel environments.

    .. code-block:: bash

        uv run python scripts/tutorials/07_visualizers/run_video_recording.py \
            --example 1 --num_envs 4

Example 2 — scene sensor only, headless
    One clip captured directly from the scene's tiled-camera sensor.
    No visualizer window opens; the sensor renders offline.

    .. code-block:: bash

        uv run python scripts/tutorials/07_visualizers/run_video_recording.py \
            --example 2 --num_envs 16

Example 3 — Kit viewport + Kit tiled grid + Newton viewport + scene sensor
    Four independent clip streams recorded simultaneously.

    .. code-block:: bash

        uv run python scripts/tutorials/07_visualizers/run_video_recording.py \
            --example 3 --num_envs 4

Clips are written to ``videos/recording_tutorial/example_<N>/`` in the working directory.
Examples 1 and 2 each demonstrate one recording source; Example 3 combines all of them.
"""

from __future__ import annotations

import argparse
import contextlib
import os
import sys

import gymnasium as gym
import torch

import isaaclab_tasks  # noqa: F401

with contextlib.suppress(ImportError):
    import isaaclab_tasks_experimental  # noqa: F401

from isaaclab.app import add_launcher_args, launch_simulation
from isaaclab.envs.utils.video_recorder_cfg import VideoRecorderCfg

from isaaclab_tasks.utils import setup_preset_cli

# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------

_VIDEO_LENGTH = 100  # env steps per clip
_NUM_STEPS = 115  # slightly more than _VIDEO_LENGTH so the clip flushes cleanly

_TASK_SHADOW = "Isaac-Reorient-Cube-Shadow-Camera-Direct"

# Kit viewport camera: positioned to show a 2×2 grid of Shadow Hand environments.
# env_spacing=1.0 with 4 envs → envs centered at ±0.5 in x and y.
# Cube spawns at ~(0, -0.39, 0.6) per env; wrist cylinder is the landmark at the top.
_SHADOW_EYE = (0.0, -2.2, 1.8)
_SHADOW_LOOKAT = (0.0, -0.1, 0.4)
_SHADOW_ENV_SPACING = 1.0

# Tiled camera eye offset from each robot root for generated per-env cameras.
_SHADOW_TILED_EYE = (0.0, 0.35, 0.8)

# Skip the first few steps so the RTX renderer has warmed up before recording starts.
_KIT_STEP_OFFSET = 5


def _output_dir(example: int) -> str:
    return os.path.join("videos", "recording_tutorial", f"example_{example}")


def _shadow_env_cfg(num_envs: int, env_spacing: float = _SHADOW_ENV_SPACING):
    """Build a base Shadow Hand camera env cfg shared by all examples."""
    from isaaclab_tasks.core.reorient.config.shadow_hand.shadow_hand_direct_camera_env_cfg import ShadowHandCameraEnvCfg

    env_cfg = ShadowHandCameraEnvCfg()
    env_cfg.tiled_camera = env_cfg.tiled_camera.rgb
    env_cfg.tiled_camera.renderer_cfg = env_cfg.tiled_camera.renderer_cfg.default
    env_cfg.tiled_camera.height = 256
    env_cfg.tiled_camera.width = 256
    env_cfg.scene.num_envs = num_envs
    env_cfg.scene.env_spacing = env_spacing
    return env_cfg


# ---------------------------------------------------------------------------
# Per-example environment config builders
# ---------------------------------------------------------------------------


def _build_env_cfg_example_1(num_envs: int):
    """Shadow Hand + Kit viewport: one clip from the interactive viewport."""
    from isaaclab_visualizers.kit import KitVisualizerCfg

    env_cfg = _shadow_env_cfg(num_envs)
    env_cfg.sim.physics = env_cfg.sim.physics.default

    env_cfg.sim.visualizer_cfgs = [KitVisualizerCfg(eye=_SHADOW_EYE, lookat=_SHADOW_LOOKAT)]

    out = _output_dir(1)
    env_cfg.video_recorders = [
        VideoRecorderCfg(
            source="visualizer:kit",
            output_dir=out,
            output_filename_prefix="kit_viewport",
            video_length=_VIDEO_LENGTH,
            fps=30,
            step_offset=_KIT_STEP_OFFSET,
        ),
    ]
    return env_cfg, _TASK_SHADOW


def _build_env_cfg_example_2(num_envs: int):
    """Shadow Hand + headless: scene tiled-camera sensor clip only."""
    env_cfg = _shadow_env_cfg(num_envs, env_spacing=2.0)
    env_cfg.sim.physics = env_cfg.sim.physics.default
    env_cfg.sim.visualizer_cfgs = []  # no interactive visualizer

    out = _output_dir(2)
    env_cfg.video_recorders = [
        VideoRecorderCfg(
            source="sensor:tiled_camera",
            output_dir=out,
            output_filename_prefix="sensor",
            video_length=_VIDEO_LENGTH,
            fps=30,
        ),
    ]
    return env_cfg, _TASK_SHADOW


def _build_env_cfg_example_3(num_envs: int):
    """Shadow Hand + Kit viewport + Kit tiled grid + Newton viewport + sensor: four simultaneous streams.

    Note: ``source='visualizer:newton'`` captures the full Newton GL window. When
    ``streaming_view=True`` is set on :class:`~isaaclab_visualizers.newton.NewtonGLVisualizerCfg`,
    the GL window displays the per-environment camera panel, so this effectively records
    a Newton streaming view without a separate ``render_tiled_rgb_array()`` call.
    """
    from isaaclab_visualizers.kit import KitVisualizerCfg
    from isaaclab_visualizers.newton import NewtonGLVisualizerCfg

    env_cfg = _shadow_env_cfg(num_envs)
    env_cfg.sim.physics = env_cfg.sim.physics.default

    kit_cfg = KitVisualizerCfg(
        eye=_SHADOW_EYE,
        lookat=_SHADOW_LOOKAT,
        streaming_view=True,
        streaming_envs=min(num_envs, 16),
        # Reuse the existing scene camera sensor so the streaming panel shows
        # the same RTX-rendered views as source="sensor:tiled_camera".
        streaming_sensor_prim_path="/World/envs/env_.*/Camera",
    )
    newton_cfg = NewtonGLVisualizerCfg(
        eye=_SHADOW_EYE,
        lookat=_SHADOW_LOOKAT,
        window_width=1280,
        window_height=720,
        focal_length=25.0,
    )
    env_cfg.sim.visualizer_cfgs = [kit_cfg, newton_cfg]

    out = _output_dir(3)
    env_cfg.video_recorders = [
        VideoRecorderCfg(
            source="visualizer:kit",
            output_dir=out,
            output_filename_prefix="kit_viewport",
            video_length=_VIDEO_LENGTH,
            fps=30,
            step_offset=_KIT_STEP_OFFSET,
        ),
        VideoRecorderCfg(
            source="visualizer:kit:streaming_view",
            output_dir=out,
            output_filename_prefix="tiled_kit_viewport",
            video_length=_VIDEO_LENGTH,
            fps=30,
            step_offset=_KIT_STEP_OFFSET,
        ),
        VideoRecorderCfg(
            source="visualizer:newton",
            output_dir=out,
            output_filename_prefix="newton_viewport",
            video_length=_VIDEO_LENGTH,
            fps=30,
        ),
        VideoRecorderCfg(
            source="sensor:tiled_camera",
            output_dir=out,
            output_filename_prefix="sensor",
            video_length=_VIDEO_LENGTH,
            fps=30,
        ),
    ]
    return env_cfg, _TASK_SHADOW


_BUILDERS = {
    1: _build_env_cfg_example_1,
    2: _build_env_cfg_example_2,
    3: _build_env_cfg_example_3,
}

# ---------------------------------------------------------------------------
# Argument parsing
# ---------------------------------------------------------------------------
parser = argparse.ArgumentParser(description="Video recording tutorial for Isaac Lab environments.")
parser.add_argument(
    "--example", type=int, default=1, choices=[1, 2, 3], help="Which recording example to run (1, 2, or 3)."
)
parser.add_argument("--num_envs", type=int, default=None, help="Number of environments to simulate.")
add_launcher_args(parser)
args_cli, hydra_args = setup_preset_cli(parser)
sys.argv = [sys.argv[0]] + hydra_args


def main():
    """Run the selected video recording example."""
    defaults = {1: 4, 2: 16, 3: 4}
    num_envs = args_cli.num_envs if args_cli.num_envs is not None else defaults[args_cli.example]
    env_cfg, task = _BUILDERS[args_cli.example](num_envs)
    env_cfg.sim.device = args_cli.device if args_cli.device is not None else env_cfg.sim.device

    # Examples 1 and 3 record from the Kit viewport via omni.replicator, which requires
    # camera rendering support.  Force it here for visualizer-only recording.
    if args_cli.example in (1, 3):
        args_cli.enable_cameras = True

    with launch_simulation(env_cfg, args_cli):
        env = gym.make(task, cfg=env_cfg)

        out = _output_dir(args_cli.example)
        print(f"[INFO]: Running Example {args_cli.example} — clips → {out}/")
        print(f"[INFO]: Gym observation space: {env.observation_space}")
        print(f"[INFO]: Gym action space: {env.action_space}")

        print("[INFO]: Setup complete.")
        env.reset()
        for _ in range(_NUM_STEPS):
            with torch.inference_mode():
                actions = 2 * torch.rand(env.action_space.shape, device=env.unwrapped.device) - 1
                env.step(actions)

        env.close()
        print(f"[INFO]: Done. Clips written to {out}/")


if __name__ == "__main__":
    main()

Kit visualizer	Newton GL visualizer
Kit visualizer tiled streaming	Scene sensor

Tutorial examples

All three examples use the Shadow Hand cube-reorientation task (Isaac-Reorient-Cube-Shadow-Camera-Direct), which ships with a built-in tiled camera sensor. Example 1 and Example 2 each demonstrate one recording source; Example 3 combines all of them simultaneously.

Example 1: Kit viewport

uv run python scripts/tutorials/07_visualizers/run_video_recording.py \
    --example 1 --num_envs 4

Records the Kit interactive viewport (RTX renderer) showing 4 parallel environments. One clip is written to videos/recording_tutorial/example_1/kit_viewport_0000.mp4.

Example 2: Scene sensor, headless

uv run python scripts/tutorials/07_visualizers/run_video_recording.py \
    --example 2 --num_envs 16

No visualizer window opens. Frames are read directly from the tiled_camera sensor, writing one clip to videos/recording_tutorial/example_2/sensor_0000.mp4.

source="sensor:tiled_camera" refers to the key under which the camera is registered in env.scene.sensors. The sensor must have "rgb" in its data_types; only the rgb channel is currently supported for sensor sources.

Example 3: All sources simultaneously

uv run python scripts/tutorials/07_visualizers/run_video_recording.py \
    --example 3 --num_envs 4

Four independent clips are written to videos/recording_tutorial/example_3/:

• kit_viewport_0000.mp4 — Kit interactive viewport (RTX renderer).

• tiled_kit_viewport_0000.mp4 — Kit tiled-camera grid (per-environment views).

• newton_viewport_0000.mp4 — Newton GL viewer framebuffer.

• sensor_0000.mp4 — scene tiled-camera sensor (offline render).

Each VideoRecorderCfg entry is fully independent — different sources write different files at their own cadence. There is no limit on the number of simultaneous recorders.

Source types

The source string selects what to capture:

Source string	Captures from
"visualizer"	First active recording-capable visualizer (auto)
"visualizer:kit"	Kit visualizer viewport
"visualizer:kit:streaming_view"	Kit streaming camera panel (requires streaming_view=True)
"visualizer:newton"	Newton GL visualizer viewport
"visualizer:newton:streaming_view"	Newton GL streaming camera panel (requires streaming_view=True)
"sensor:<name>"	env.scene.sensors[name], RGB (default)
"sensor:<name>:rgb"	RGB channel
"sensor:<name>:depth"	Depth, turbo colormap (range: depth_colormap_min … depth_colormap_max)
"sensor:<name>:segmentation"	Segmentation, colorized
"sensor:<name>:normals"	Surface normals, colorized

The camera angle, resolution, and other visualizer settings are configured on the corresponding KitVisualizerCfg or NewtonGLVisualizerCfg, not on the recorder.

Clip control

Field	Default	Meaning
video_length	200	Env steps per clip
video_interval	0	0 = one clip starting at step 1; N > 0 = new clip every N steps
fps	None	Output frame rate; None resolves from env.metadata["render_fps"] or 1 / step_dt
output_dir	"videos"	Directory for output files (created on demand)
output_filename_prefix	"clip"	File stem; output is <prefix>_NNNN.mp4
keep_last_n_clips	None	Delete older clips; None keeps all

One clip at the start of a run:

VideoRecorderCfg(source="visualizer:kit", video_length=500, video_interval=0)

Recurring clips every 1 000 env steps:

VideoRecorderCfg(source="visualizer:kit", video_length=200, video_interval=1000)

Keep only the most recent clip on disk:

VideoRecorderCfg(source="visualizer:kit", video_length=200, video_interval=1000,
                 keep_last_n_clips=1)

Recording from an independent camera angle

Configure the recording angle on the visualizer rather than on the recorder. To open a headless Newton visualizer at a different angle alongside an interactive Kit viewer:

from isaaclab_visualizers.kit import KitVisualizerCfg
from isaaclab_visualizers.newton import NewtonGLVisualizerCfg

env_cfg.sim.visualizer_cfgs = [
    KitVisualizerCfg(eye=(4.0, 4.0, 2.0)),
    NewtonGLVisualizerCfg(eye=(12.0, 0.0, 6.0), headless=True),
]
env_cfg.video_recorders = [
    VideoRecorderCfg(source="visualizer:newton", output_dir="videos/"),
]

Alternatively, use a CameraCfg sensor in the scene and record with source="sensor:<name>", which gives full control over the recording viewpoint without requiring a second interactive visualizer.

Requirements

• moviepy 1.x and ffmpeg must be installed (both are already in Isaac Lab’s dependencies).

• For source="visualizer:kit" or "visualizer:kit:streaming_view": the Kit app is launched automatically by AppLauncher. In headless mode (--headless), you must also pass --enable_cameras (or set ENABLE_CAMERAS=1) to activate the Replicator offscreen render pipeline; without it, captured frames are black. The --video flag sets --enable_cameras automatically when no explicit recorder source is configured.

• For source="visualizer:newton" or "visualizer:newton_gl" / "visualizer:newton:streaming_view": an active NewtonGLVisualizerCfg must be in env_cfg.sim.visualizer_cfgs. Newton GL uses pyglet’s EGL backend and works headlessly without --enable_cameras.

• For source="sensor:<name>": the named field must exist on the scene config and have "rgb" in its data_types.

Visualizer compatibility

Only kit and newton_gl support frame capture for video recording. Both can run headless (headless=True on the cfg) so they add no UI window or interactive overhead when video is the only goal.

Visualizer	--video	Notes
kit	✓	Kit/Omniverse viewport; supports headless mode
newton_gl	✓	Newton OpenGL viewport; supports headless mode
newton_rtx	✗	Framebuffer readback (ViewerRTX.get_frame()) not yet available from the Newton SDK
rerun	✗	Remote streaming tool; no local frame-capture API
viser	✗	Browser streaming tool; no local frame-capture API

Passing --video alongside --viz rerun, --viz viser, or --viz newton_rtx raises an error when no other recording-capable visualizer is configured.

To run a streaming or RTX visualizer and record video simultaneously, add a headless capture backend alongside it in sim.visualizer_cfgs:

from isaaclab_visualizers.kit import KitVisualizerCfg
from isaaclab_visualizers.rerun import RerunVisualizerCfg

env_cfg.sim.visualizer_cfgs = [
    RerunVisualizerCfg(...),                 # streaming — for monitoring
    KitVisualizerCfg(headless=True),         # headless — provides frames for --video
]

Alternatively, record directly from a scene camera sensor without any visualizer:

VideoRecorderCfg(source="sensor:<name>")    # add to env_cfg.video_recorders

Limitations

• source="visualizer:kit" and source="visualizer:kit:streaming_view" require cubric to propagate Newton Fabric scene transforms to the RTX renderer. Without cubric, a warning is logged and a black-frame warning is emitted at clip write time. Use source="visualizer:newton" for guaranteed capture with Newton physics.

• source="visualizer:newton:streaming_view" and source="visualizer:kit:streaming_view" require streaming_view=True on the corresponding visualizer cfg. A RuntimeError is raised at the first capture attempt if it is not set.

See also

• Visualization — configuring interactive visualizers

• Using the Visualizer Streaming Camera View — tiled camera panel setup

• Capturing sensor frames during training — saving per-frame sensor outputs as images