Fix OVD Recorder hanging silently on non-PhysX backends (#7507)

## Description

The OVD Recorder (`AnimationRecorder`) only works with the PhysX
backend, but most tasks now default to Newton. As a result,
`--anim_recording_enabled` silently did nothing: recording never
started, `--anim_recording_stop_time` was never reached, and the process
ran until manually killed with nothing saved.

This PR:
- Raises a clear error at simulation startup when
`--anim_recording_enabled` is set on a physics backend that doesn't
support the OVD Recorder (via a new
`PhysicsManager.supports_anim_recording` flag, set `True` only on
`PhysxManager`), naming the active backend and pointing the user to
`physics=isaacsim_physx`.
- Adds an `overrides` parameter to `parse_env_cfg()` so standalone
(non-Hydra) scripts can apply `physics=`/`renderer=`/`presets=`
overrides, and updates the `run_cartpole_rl_env.py` tutorial to forward
unrecognized CLI args this way.
- Updates `docs/source/how-to/record_animation.rst` to note the PhysX
requirement and fix the example command so it actually works as
documented.

## Type of change

- Bug fix (non-breaking change which fixes an issue)

## Testing

- Reran the exact documented repro command on the default (Newton)
backend: now fails fast with a clear `ValueError` instead of hanging.
- Reran with `physics=isaacsim_physx`: recording stops at
`--anim_recording_stop_time`, saves `baked_animation_recording.usda`,
process exits cleanly (exit code 0).
- `uv run isaaclab -f` passes for all touched files.
- Targeted tests (`test_physics_manager_lifecycle.py`, `test_hydra.py`):
94 passed.
- Docs build (`make -C docs current-docs`, warnings-as-errors):
succeeded with no warnings.

## Checklist

- [x] I have read and understood the contribution guidelines
- [x] I have run the `pre-commit` checks with `uv run isaaclab -f`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added a changelog fragment under
`source/<pkg>/changelog.d/` for every touched package
- [x] I have added my name to `CONTRIBUTORS.md` (already present)

## Release backport

- [x] <!-- backport-active-release --> Backport this pull request to the
active release branch after it merges into `develop`

(cherry picked from commit 69de9b2)

Author: matthewtrepte

docs/source/how-to/record_animation.rst

@@ -97,6 +97,16 @@ This method is more scalable and better suited for large-scale training scenario
 
 It’s not UI-controlled—the whole process is enabled through CLI flags and runs automatically.
 
+.. note::
+
+   The OVD Recorder uses OmniPVD, which only records **PhysX** simulations. If the active physics backend is not
+   PhysX (for example, Newton, which is the default for many tasks), Isaac Lab raises an error at startup naming
+   the active backend instead of recording. Select the PhysX backend by adding ``physics=isaacsim_physx`` to the
+   command line, as shown below.
+
+   The PhysX backend requires Isaac Sim. If it isn't installed yet, add ``--extra isaacsim`` to the ``uv run``
+   command; see :ref:`installation-optional-extras` for details.
+
 
 Workflow Summary
 ~~~~~~~~~~~~~~~~
@@ -120,14 +130,14 @@ To record an animation:
 
       .. code-block:: bash
 
-         uv run python scripts/tutorials/03_envs/run_cartpole_rl_env.py --anim_recording_enabled --anim_recording_start_time 1 --anim_recording_stop_time 3
+         uv run python scripts/tutorials/03_envs/run_cartpole_rl_env.py --anim_recording_enabled --anim_recording_start_time 1 --anim_recording_stop_time 3 physics=isaacsim_physx
 
    .. tab-item:: :icon:`fa-brands fa-windows` Windows
       :sync: windows
 
       .. code-block:: batch
 
-         uv run python scripts\tutorials\03_envs\run_cartpole_rl_env.py --anim_recording_enabled --anim_recording_start_time 1 --anim_recording_stop_time 3
+         uv run python scripts\tutorials\03_envs\run_cartpole_rl_env.py --anim_recording_enabled --anim_recording_start_time 1 --anim_recording_stop_time 3 physics=isaacsim_physx
 
 .. note::
 

scripts/benchmarks/benchmark_cameras.py

@@ -236,7 +236,8 @@
 
 
 AppLauncher.add_app_launcher_args(parser)
-args_cli = parser.parse_args()
+# forward unrecognized args as Hydra-style task config overrides
+args_cli, hydra_overrides = parser.parse_known_args()
 args_cli.enable_cameras = True
 
 if args_cli.autotune:
@@ -527,7 +528,7 @@ def inject_cameras_into_task(
     num_cameras_per_env: int = 1,
 ) -> gym.Env:
     """Loads the task, sticks cameras into the config, and creates the environment."""
-    cfg = parse_env_cfg(task, device=args_cli.device, use_fabric=args_cli.use_fabric)
+    cfg = parse_env_cfg(task, device=args_cli.device, use_fabric=args_cli.use_fabric, overrides=hydra_overrides)
     scene_cfg = cfg.scene
 
     num_envs = int(num_cams / num_cameras_per_env)

scripts/environments/export_IODescriptors.py

@@ -19,8 +19,8 @@
 parser.add_argument("--output_dir", type=str, default=None, help="Path to the output directory.")
 # append AppLauncher cli args
 AppLauncher.add_app_launcher_args(parser)
-# parse the arguments
-args_cli = parser.parse_args()
+# parse the arguments, forwarding unrecognized ones as Hydra-style task config overrides
+args_cli, hydra_overrides = parser.parse_known_args()
 args_cli.headless = True
 
 # launch omniverse app
@@ -44,7 +44,9 @@
 def main():
     """Random actions agent with Isaac Lab environment."""
     # create environment configuration
-    env_cfg = parse_env_cfg(args_cli.task, device=args_cli.device, num_envs=1, use_fabric=True)
+    env_cfg = parse_env_cfg(
+        args_cli.task, device=args_cli.device, num_envs=1, use_fabric=True, overrides=hydra_overrides
+    )
     # create environment
     env = gym.make(args_cli.task, cfg=env_cfg)
 

scripts/environments/state_machine/lift_cube_sm.py

@@ -29,8 +29,8 @@
 parser.add_argument("--num_envs", type=int, default=None, help="Number of environments to simulate.")
 # append AppLauncher cli args
 AppLauncher.add_app_launcher_args(parser)
-# parse the arguments
-args_cli = parser.parse_args()
+# parse the arguments, forwarding unrecognized ones as Hydra-style task config overrides
+args_cli, hydra_overrides = parser.parse_known_args()
 
 # launch omniverse app
 app_launcher = AppLauncher(args_cli)
@@ -257,6 +257,7 @@ def main():
         device=args_cli.device,
         num_envs=args_cli.num_envs,
         use_fabric=not args_cli.disable_fabric,
+        overrides=hydra_overrides,
     )
     # create environment
     env = gym.make("IsaacContrib-Lift-Cube-Franka-IK-Abs", cfg=env_cfg)

scripts/environments/state_machine/open_cabinet_sm.py

@@ -29,8 +29,8 @@
 parser.add_argument("--num_envs", type=int, default=None, help="Number of environments to simulate.")
 # append AppLauncher cli args
 AppLauncher.add_app_launcher_args(parser)
-# parse the arguments
-args_cli = parser.parse_args()
+# parse the arguments, forwarding unrecognized ones as Hydra-style task config overrides
+args_cli, hydra_overrides = parser.parse_known_args()
 
 # launch omniverse app
 app_launcher = AppLauncher(args_cli)
@@ -276,6 +276,7 @@ def main():
         device=args_cli.device,
         num_envs=args_cli.num_envs,
         use_fabric=not args_cli.disable_fabric,
+        overrides=hydra_overrides,
     )
     # create environment
     env = gym.make("IsaacContrib-Open-Drawer-Franka-IK-Abs", cfg=env_cfg)

scripts/environments/teleoperation/teleop_replay_agent.py

@@ -372,7 +372,8 @@
     ),
 )
 AppLauncher.add_app_launcher_args(parser)
-args_cli = parser.parse_args()
+# forward unrecognized args as Hydra-style task config overrides
+args_cli, hydra_overrides = parser.parse_known_args()
 
 app_launcher_args = vars(args_cli)
 # Enable external camera rendering by default so the replay mimics the production teleop env (perf
@@ -392,6 +393,7 @@
 import statistics
 import sys
 import time
+from collections.abc import Sequence
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -1044,7 +1046,11 @@ def _ensure_replicator_loaded() -> None:
 
 
 def _prepare_env_cfg(
-    task: str, num_envs: int, device: str, apply_rtx_settings: bool = False
+    task: str,
+    num_envs: int,
+    device: str,
+    apply_rtx_settings: bool = False,
+    overrides: Sequence[str] = (),
 ) -> tuple[ManagerBasedRLEnvCfg, object | None]:
     """Build and tweak an env config suitable for non-interactive replay.
 
@@ -1083,12 +1089,13 @@ def _prepare_env_cfg(
             RTX/DLSS global settings applied; a headless replay that renders
             nothing neither needs them nor has the extensions loaded to apply
             them. See :func:`_rtx_rendering_requested`.
+        overrides: Hydra-style ``key=value`` overrides forwarded to :func:`parse_env_cfg`.
 
     Returns:
         Tuple ``(env_cfg, success_term)``. ``success_term`` is ``None`` when
         the env doesn't define a ``success`` termination term.
     """
-    env_cfg = parse_env_cfg(task, device=device, num_envs=num_envs)
+    env_cfg = parse_env_cfg(task, device=device, num_envs=num_envs, overrides=overrides)
     env_cfg.env_name = task.split(":")[-1]
     if not isinstance(env_cfg, ManagerBasedRLEnvCfg):
         raise ValueError(
@@ -1628,6 +1635,7 @@ def main() -> int:
             args_cli.num_envs,
             args_cli.device,
             apply_rtx_settings=_rtx_rendering_requested(args_cli),
+            overrides=hydra_overrides,
         )
 
         if not hasattr(env_cfg, "isaac_teleop") or env_cfg.isaac_teleop is None:

scripts/imitation_learning/isaaclab_mimic/annotate_demos.py

@@ -52,8 +52,12 @@
     external_callback_function = string_to_callable(args_cli.external_callback, separator=".")
     remaining_args_env_registration = external_callback_function()
 
-# Error on unrecognized arguments.
-unrecognized_args = list_intersection(remaining_args, remaining_args_env_registration)
+# Extras of the form "key=value" are Hydra-style task config overrides forwarded to
+# parse_env_cfg(); everything else must be consumed by the external callback or is an error.
+hydra_overrides = [arg for arg in remaining_args if "=" in arg]
+unrecognized_args = list_intersection(
+    [arg for arg in remaining_args if arg not in hydra_overrides], remaining_args_env_registration
+)
 if unrecognized_args:
     parser.error(f"unrecognized arguments: {' '.join(unrecognized_args)}")
 
@@ -195,7 +199,7 @@ def main():
     if env_name is None:
         raise ValueError("Task/env name was not specified nor found in the dataset.")
 
-    env_cfg = parse_env_cfg(env_name, device=args_cli.device, num_envs=1)
+    env_cfg = parse_env_cfg(env_name, device=args_cli.device, num_envs=1, overrides=hydra_overrides)
 
     env_cfg.env_name = env_name
 

scripts/imitation_learning/isaaclab_mimic/consolidated_demo.py

@@ -62,8 +62,8 @@
 )
 # append AppLauncher cli args
 AppLauncher.add_app_launcher_args(parser)
-# parse the arguments
-args_cli = parser.parse_args()
+# parse the arguments, forwarding unrecognized ones as Hydra-style task config overrides
+args_cli, hydra_overrides = parser.parse_known_args()
 
 # launch the simulator
 app_launcher = AppLauncher(args_cli)
@@ -371,7 +371,7 @@ def main():
         raise ValueError("Task/env name was not specified nor found in the dataset.")
 
     # parse configuration
-    env_cfg = parse_env_cfg(env_name, device=args_cli.device, num_envs=num_envs)
+    env_cfg = parse_env_cfg(env_name, device=args_cli.device, num_envs=num_envs, overrides=hydra_overrides)
     env_cfg.env_name = env_name
 
     # extract success checking function to invoke manually

scripts/imitation_learning/locomanipulation_sdg/generate_data.py

@@ -123,7 +123,8 @@
 )
 
 AppLauncher.add_app_launcher_args(parser)
-args_cli = parser.parse_args()
+# forward unrecognized args as Hydra-style task config overrides
+args_cli, hydra_overrides = parser.parse_known_args()
 
 app_launcher = AppLauncher(args_cli)
 simulation_app = app_launcher.app
@@ -993,7 +994,7 @@ def replay(
         if env_name is None:
             raise ValueError("Task/env name was not specified nor found in the dataset.")
 
-        env_cfg = parse_env_cfg(env_name, device=args_cli.device, num_envs=1)
+        env_cfg = parse_env_cfg(env_name, device=args_cli.device, num_envs=1, overrides=hydra_overrides)
         env_cfg.sim.device = "cpu"
         env_cfg.recorders.dataset_export_dir_path = os.path.dirname(args_cli.output_file)
         env_cfg.recorders.dataset_filename = os.path.basename(args_cli.output_file)

scripts/imitation_learning/locomanipulation_sdg/gr00t/rollout_policy.py

@@ -31,7 +31,8 @@
     "Converts env observations/actions to match. Default is 'xyzw'.",
 )
 AppLauncher.add_app_launcher_args(parser)
-args_cli = parser.parse_args()
+# forward unrecognized args as Hydra-style task config overrides
+args_cli, hydra_overrides = parser.parse_known_args()
 
 app_launcher = AppLauncher(args_cli)
 simulation_app = app_launcher.app
@@ -374,7 +375,7 @@ def eval_policy(
 
         policy = Policy(model_path=args_cli.model_path, embodiment_tag=args_cli.embodiment_tag)
 
-        env_cfg = parse_env_cfg(env_name, device=args_cli.device, num_envs=1)
+        env_cfg = parse_env_cfg(env_name, device=args_cli.device, num_envs=1, overrides=hydra_overrides)
         env_cfg.sim.device = args_cli.device
         # Drop the SDG output-data recorder term: it pulls env._locomanipulation_sdg_output_data,
         # which is only populated by the data-generation state machine, not during policy rollout.