录制视频

录制视频#

本指南介绍如何在运行过程中，从可视化器或场景传感器录制 mp4 视频片段。

Shadow Hand 立方体转向任务的录像，录制 Rerun 可视化器的串流视图，包含四个串流环境和四种真值数据

每个 VideoRecorderCfg 条目独立运行：不同数据源按照各自的录制周期写入不同文件，同时运行的录制器数量没有限制。

快速开始#

在 env_cfg.video_recorders 中添加 VideoRecorderCfg ：

from isaaclab.envs.utils.video_recorder_cfg import VideoRecorderCfg

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

source 也接受 ImageViewCfg：使用 VideoRecorderCfg(source=view)，可与窗口共享图像选择和帧。传感器与透视视图示例见在可视化器中显示相机流视图。

也可在命令行传入 --video [SOURCE]，无需修改环境配置即可录制。--video 添加一个录制器；若要同时录制多个来源，在 env_cfg.video_recorders 中为每个来源列出一个 VideoRecorderCfg。此列表优先于 --video 的来源设置，但 --video_length 和 --video_interval 仍应用于所有录制器：

uv（推荐）

uv run isaaclab train --rl_library rsl_rl --task Isaac-Cartpole --video

--video 从指定来源录制，--viz 仍决定哪些可视化器打开窗口。所有命令行形式见 --video 来源，VideoRecorderCfg 选项见下方来源和片段控制。从不同于交互视图的角度录制，见从独立相机视角录制。

示例#

这三个示例均使用 Shadow Hand 立方体重定向任务 Isaac-Reorient-Cube-Shadow-Camera-Direct ，该任务内置平铺相机传感器。示例 1 和 2 分别演示一种录制来源，示例 3 则组合全部四种来源。

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 --viz kit

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 --viz kit,newton_gl

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.
``--viz`` selects the visualizers to record from; the configs below only set their camera and panels.
"""

from __future__ import annotations

import argparse
import contextlib
import os
import sys

import gymnasium as gym
import torch

from isaaclab.visualizers import WindowCfg

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 resolve_task_config, 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

# 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."""
    env_cfg, _ = resolve_task_config(_TASK_SHADOW, "", overrides=(*sys.argv[1:], "env.scene.tiled_camera=rgb"))
    env_cfg.scene.tiled_camera.height = 256
    env_cfg.scene.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.visualizer_cfgs = [KitVisualizerCfg(eye=_SHADOW_EYE, lookat=_SHADOW_LOOKAT)]

    out = _output_dir(1)
    env_cfg.video_recorders = [
        VideoRecorderCfg(
            source="viz: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)

    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='viz:newton_gl'`` 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)
    kit_cfg = KitVisualizerCfg(
        eye=_SHADOW_EYE,
        lookat=_SHADOW_LOOKAT,
        streaming_view=True,
        streaming_envs=min(num_envs, 16),
        # No streaming_sensor_prim_path: selects the existing
        # tiled_camera sensor automatically, so the streaming panel shows the same
        # RTX-rendered views as source="sensor:tiled_camera".
    )
    newton_cfg = NewtonGLVisualizerCfg(
        eye=_SHADOW_EYE,
        lookat=_SHADOW_LOOKAT,
        window=WindowCfg(size=(1280, 720)),
        focal_length=25.0,
    )
    env_cfg.sim.visualizer_cfgs = [kit_cfg, newton_cfg]

    out = _output_dir(3)
    env_cfg.video_recorders = [
        VideoRecorderCfg(
            source="viz:kit",
            output_dir=out,
            output_filename_prefix="kit_viewport",
            video_length=_VIDEO_LENGTH,
            fps=30,
            step_offset=_KIT_STEP_OFFSET,
        ),
        VideoRecorderCfg(
            source="viz: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="viz:newton_gl",
            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()

示例 1：Kit 视口#

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

录制 Kit 交互视口（RTX 渲染器）
显示 4 个并行环境
将一个视频片段写入 videos/recording_tutorial/example_1/kit_viewport_0000.mp4

Kit 可视化器

示例 2：场景传感器，无界面运行#

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

场景传感器

不打开可视化器窗口；直接从 tiled_camera 传感器读取帧
将一个视频片段写入 videos/recording_tutorial/example_2/sensor_0000.mp4
source="sensor:tiled_camera" 中的 tiled_camera 是该相机在 env.scene.sensors 中注册时使用的键
传感器的 data_types 必须包含待录制通道；默认通道为 rgb，也支持 depth、segmentation 和 normals，见数据源

示例 3：同时录制所有来源#

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

将四个独立的视频片段写入 videos/recording_tutorial/example_3/ ：

kit_viewport_0000.mp4 ：Kit 交互视口（RTX 渲染器）
tiled_kit_viewport_0000.mp4 ：Kit 平铺相机网格（各环境的视图）
newton_viewport_0000.mp4 ：Newton GL 查看器帧缓冲
sensor_0000.mp4 ：场景平铺相机传感器（离线渲染）

Newton GL 可视化器

Kit 可视化器平铺串流

常用配置#

以下命令行和配置示例不属于教程脚本，可按实际需要使用。

在强化学习训练中录制#

训练时不打开窗口，按固定间隔录制短片段：

uv run isaaclab train --rl_library rsl_rl --task Isaac-Cartpole --video \
    --video_length 200 --video_interval 2000

未设置 --viz 时，--video 从无窗口 Newton GL 可视化器录制。以下命令每 2,000 步录制一段 200 步的视频。除非录制器设置了 output_dir，train 和 play 入口将视频写入本次运行日志目录下的 videos/；自行构建录制器的脚本写入 output_dir，默认是 videos。添加 --viz kit，可在窗口中观察运行并录制相同视图。

从场景传感器录制深度或分割结果#

在传感器数据源后追加通道名称，即可录制 RGB 以外的数据。每个录制器写入独立文件，因此一次运行可以同时录制同一相机的多个通道：

env_cfg.video_recorders = [
    VideoRecorderCfg(source="sensor:tiled_camera:rgb", output_filename_prefix="rgb"),
    VideoRecorderCfg(source="sensor:tiled_camera:depth", output_filename_prefix="depth"),
]

深度使用 turbo 色图，映射范围为 depth_colormap_min 到 depth_colormap_max。segmentation 和 normals 同样可以为每个录制器设置独立文件名前缀。

使用 Viser 或 Rerun 查看视频流时录制#

Viser 和 Rerun 向浏览器或查看器发送视频流，但不提供帧捕获，无法直接录制。可以同时运行一个支持帧捕获的无界面可视化器：

uv run isaaclab train --rl_library rsl_rl --task Isaac-Cartpole --viz viser --video viz:newton_gl

也可以设置 source="sensor:<name>"，直接从场景相机录制，无需可视化器。

从独立相机视角录制#

录制角度应在可视化器上配置，不在录制器上配置。如需在交互式 Kit 查看器之外，从不同角度的无窗口 Newton 可视化器录制，请使用 --viz kit 并配置两个可视化器；录制器会以无窗口方式添加 Newton 可视化器：

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)),
]
env_cfg.video_recorders = [
    VideoRecorderCfg(source="viz:newton_gl", output_dir="videos/"),
]

也可以在场景中使用 CameraCfg 传感器，并通过 source="sensor:<name>" 录制。这样可以完全控制录制视角，无需第二个交互式可视化器。

数据源#

source 字符串用于选择采集对象：

来源字符串	采集对象
`"viz"` （默认值）	`--viz` 选中的第一个支持捕获的可视化器，否则使用无窗口 Newton GL 可视化器
`"viz:kit"`	Kit 可视化器视口
`"viz:kit:streaming_view"`	Kit 相机流面板，需要设置 `streaming_view=True`
`"viz:newton_gl"`	Newton GL 可视化器视口
`"viz:newton_rtx"`	Newton OVRTX 路径追踪视口
`"viz:newton_gl:streaming_view"`	Newton GL 相机流面板，需要设置 `streaming_view=True`
`"sensor:<name>"`	`env.scene.sensors[name]` 的 RGB 数据（默认）
`"sensor:<name>:rgb"`	RGB 通道
`"sensor:<name>:depth"`	深度，采用 turbo 色图，范围为 `depth_colormap_min` … `depth_colormap_max`
`"sensor:<name>:segmentation"`	分割，使用颜色区分
`"sensor:<name>:normals"`	表面法线，使用颜色表示

相机角度、分辨率及其他可视化设置应在对应的可视化器配置中设置，不在录制器中设置。--viz 未选中的 viz:<type> 可视化器仅为录制而无窗口运行，使用 sim.visualizer_cfgs 中对应配置的设置。

visualizer 可作为 viz 前缀的完整形式，例如 "visualizer:kit" 等同于 "viz:kit"。已弃用的 newton 类型（"viz:newton"）仍可使用，但会发出警告；请改用 newton_gl。这里也接受不带前缀的可视化器类型，例如 VideoRecorderCfg(source="newton_gl") 等同于 VideoRecorderCfg(source="viz:newton_gl")。

备注

可通过 "viz:newton_rtx" 录制 Newton RTX 查看器的帧缓冲区，但不支持录制其流式视图。

片段控制#

字段	默认值	含义
`video_length`	`200`	每个片段的环境步数
`video_interval`	`0`	`0` = 从第 1 步开始录制一个片段； `N > 0` = 每 N 步开始录制一个新片段
`fps`	`None`	输出帧率；设为 `None` 时，从 `env.metadata["render_fps"]` 或 `1 / step_dt` 确定
`output_dir`	`"videos"`	输出文件目录（按需创建）
`output_filename_prefix`	`"clip"`	文件名前缀；输出文件名为 `<prefix>_NNNN.mp4`
`keep_last_n_clips`	`None`	删除较早的片段；设为 `None` 时保留全部片段

运行开始时录制一个片段：

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

每隔 1,000 个环境步录制一个片段：

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

磁盘上仅保留最新片段：

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

限制#

source="viz:newton_gl:streaming_view" 和 source="viz:kit:streaming_view" 要求在对应可视化器配置中设置 streaming_view=True；否则构造录制器时会抛出 RuntimeError。
使用 source="sensor:<name>" 时，场景配置中必须存在该名称的传感器，其 data_types 必须包含待录制通道，默认通道为 "rgb"。

可视化器	`--video`	说明
`kit`	✓	启动 Isaac Sim，并在启动时为录制启用相机渲染。
`newton_gl`	✓	无窗口时使用 pyglet 的 EGL 后端；这是 `--video` 在未选择支持捕获的 `--viz` 时的默认来源。
`newton_rtx`	✓	启动 OVRTX 运行时；捕获帧时，将路径追踪帧缓冲区从 GPU 回读到 CPU。
`rerun`	✗	远程流式工具，无本地帧捕获 API。`viz:rerun` 会报错；`--video --viz rerun` 则从无窗口 `newton_gl` 录制。
`viser`	✗	浏览器流式工具，无本地帧捕获 API。`viz:viser` 会报错；`--video --viz viser` 则从无窗口 `newton_gl` 录制。

使用 Rerun 或 Viser 查看视频流时的录制方法，见使用 Viser 或 Rerun 查看视频流时录制。

另请参阅#

可视化：配置交互式可视化器并录制其画面
在可视化器中显示相机流视图：配置平铺相机面板
在训练期间采集传感器帧：将逐帧传感器输出保存为图像