Capturing Demo Videos

Record demo videos for documentation and presentations. PyBulletFleet provides three recording approaches.

Capture Pipeline Overview

Method	Mode	Output	Requirements
Python API (start_recording)	Headless or GUI	MP4 / GIF	PyBullet only
RECORD env var	run_simulation() auto-capture	MP4 / GIF	PyBullet only
capture_demo.py	Batch headless	MP4 / GIF	PyBullet only
capture_screen_demo.py	GUI screen recording	MP4	X11 + ffmpeg + xdotool

Python API

Call start_recording() on the simulation core to record from within your script:

from pybullet_fleet import MultiRobotSimulationCore

sim = MultiRobotSimulationCore.from_yaml("config/config.yaml")
# ... spawn agents ...

# Record 4 seconds as MP4 (auto-saved when run_simulation ends)
sim.start_recording("output.mp4", duration=4.0, fps=30)
sim.run_simulation(duration=5.0)

Key parameters:

Parameter	Default	Description
output	"recording.gif"	File path (.gif or .mp4)
duration	None	Recording length in seconds (None = manual stop)
fps	15	Capture & playback frame rate
width / height	800 / 600	Frame resolution
camera_mode	"auto"	"auto" | "gui" | "orbit" | "manual"
time_base	"sim"	"sim" (1× playback) or "real" (wall-clock speed)

For advanced usage (manual start/stop, orbit camera, custom camera params), see the SimulationRecorder API reference.

Environment Variable

When the RECORD environment variable is set, recording starts automatically at the beginning of run_simulation() and the file is saved when the simulation ends. No script changes are required.

# Basic usage
RECORD=output.mp4 python examples/scale/100robots_grid_demo.py

# With custom settings
RECORD=demo.gif RECORD_DURATION=6.0 RECORD_FPS=10 \
  python examples/basics/action_system_demo.py

Variable	Default	Description
RECORD	—	Output path (triggers recording)
RECORD_DURATION	4.0	Duration in seconds
RECORD_FPS	15	Frame rate
RECORD_WIDTH / RECORD_HEIGHT	800 / 600	Frame resolution
RECORD_TIME_BASE	"sim"	"sim" or "real"

Batch Capture Scripts

For batch recording of multiple demos, two scripts read the shared scripts/demos.yaml configuration.

Headless Capture — capture_demo.py

Uses SimulationRecorder to render frames internally (no window needed). Works in CI and headless environments.

# Record all demos as MP4
python scripts/capture_demo.py

# Single demo, custom format
python scripts/capture_demo.py --demo 100robots_grid_mixed --format gif

GUI Screen Capture — capture_screen_demo.py

Records the actual PyBullet GUI window including the DataMonitor overlay. Requires a running X11 display.

# Record all demos
python scripts/capture_screen_demo.py

# Single demo with custom delay
python scripts/capture_screen_demo.py --demo 100robots_grid_mixed --delay 3

# Dry run (show commands without executing)
python scripts/capture_screen_demo.py --dry-run

# List available demos
python scripts/capture_screen_demo.py --list

Parameter resolution (3-layer merge)

Screen capture parameters are resolved in order (later wins):

1. format_defaults from demos.yaml (e.g. mp4: {fps: 30, duration: 6.0})

2. CLI arguments (--fps, --duration)

3. Per-demo overrides in the YAML

Per-demo delay

Demos that load many robots need extra time to stabilize before recording. Set delay per-demo in demos.yaml:

demos:
  pick_drop_arm_100robots:
    script: examples/scale/pick_drop_arm_100robots_demo.py
    delay: 5          # Wait 5s after window appears before recording

  action_system:
    script: examples/basics/action_system_demo.py
    # No delay — starts recording immediately

The CLI --delay flag serves as a global fallback for demos without a per-demo delay setting.

demos.yaml Format

format_defaults:
  gif:
    fps: 10
    width: 640
    height: 480
    duration: 4.0
    time_base: sim
  mp4:
    fps: 30
    width: 1280
    height: 960
    duration: 6.0
    time_base: sim

demos:
  demo_name:
    script: examples/path/to/demo.py      # Required
    args: ["--mode=mixed"]                 # Optional CLI args for the demo
    delay: 3                               # Optional stabilize delay (seconds)
    mp4:                                   # Optional per-format overrides
      fps: 60
      duration: 10.0

Field	Type	Default	Description
script	str	required	Path to demo Python script
args	list	[]	CLI arguments passed to the demo
delay	int	CLI --delay or None	Stabilize delay before recording
mp4 / gif	dict	{}	Per-format parameter overrides

Output

Recordings are saved to docs/media/ by default:

docs/media/
  100robots_grid_mixed.mp4
  100robots_cube_patrol.mp4
  pick_drop_arm_100robots.mp4
  ...

For shell-level usage of screen_capture.sh, see scripts/README.md.