# Rerun inside Gradio

Use this only when the application needs an embedded Rerun viewer. A standalone
viewer or saved recording is simpler for ordinary debugging.

## Tested application shape

- Robium's 2026-07-15 VLA trial used `gradio_rerun` with a Rerun
  `RecordingStream` and `binary_stream`, yielding chunks from `stream.read()`
  into a streaming viewer component.
- The Gradio application was mounted into FastAPI. This kept simulation or
  policy execution separate from the web route while the component consumed
  recording bytes.
- JPEG-compressing browser-bound image logs materially reduced bandwidth in
  that application.

## Dependency boundary

- `lerobot[viz]==0.6.0` required a Rerun SDK below 0.34, while
  `gradio_rerun==0.34.1` required exactly 0.34.1. The resolver could not satisfy
  both.
- That application dropped LeRobot's `viz` extra and pinned the SDK required by
  the Gradio component. Re-resolve against current package metadata; do not
  preserve these old pins as universal defaults.
- Keep the Rerun SDK and embedded component on compatible versions. Verify a
  minimal streaming render before integrating the robot workload.

## Preserve the primary view

If a valid recording and successful chunk transport still produce a black
embedded canvas, stop treating the embed as the only live camera surface. Keep
Rerun for the saved/offline timeline and render the critical live frame through
the host UI directly. Robium's VLA trial passed this split after both path-based
and streamed-byte Gradio integrations stayed black despite valid RRF2 data.

# Rerun operating modes

Use the current SDK documentation and installed API as the source of truth.
The shapes below explain the decision; they do not freeze signatures.

## Local viewer

- `rr.init(..., spawn=True)` is appropriate when the producer has a local
  desktop and the run is exploratory.
- `spawn()` is the wrong default on a headless server. A display failure says
  nothing about the validity of the recording.

## Separate or remote viewer

- A producer can connect to an already-running viewer, or host a gRPC recording
  that a viewer connects to later.
- A browser-facing viewer is useful when installing a native viewer is not
  practical. Treat its bind address, exposed port, authentication, and retained
  history as service concerns.
- Rerun's served recording may buffer history for late clients. Set an
  intentional memory limit for long-running or high-bandwidth streams.
- LeRobot's distant dataset-viewer mode follows this same producer/server and
  remote-client shape; prefer its wrapper for LeRobot episodes.

## File output

- Save `.rrd` for CI, offline inspection, comparisons, and handoff.
- Record the application/schema version and the input revision beside the file
  when the recording is a test or experiment artifact.
- Prefer file output over opening a viewer in unattended jobs.

## Timelines and paths

- Use a sequence timeline for ordered episode steps and a timestamp/duration
  timeline when real timing matters. Do not infer alignment from logging order
  across concurrent producers.
- Static entities follow latest-at semantics and need not be logged at every
  step.
- Group paths by stable concepts such as `robot/camera`, `robot/state`,
  `policy/action`, and `world`; adapt this to the application's real hierarchy
  rather than copying the names literally.

## Version-sensitive failures

- If an archetype or time API is missing, inspect the installed SDK and its
  migration notes. Robium's 0.34.1 application used plural `rr.Scalars` and
  `rr.set_time(..., sequence=...)`; these are evidence for that pin, not a
  promise about another version.
- The Python SDK bundled the viewer in that application; C++ and Rust paths
  required a separately installed CLI. Verify the current packaging before
  depending on it.

---
name: rerun
description: Visualize robot and machine-learning data with Rerun.
---

# Rerun

Choose the **data sink first**. Where and when the viewer must run determines
how the application should log.

## Choose the viewing shape

- Use a spawned viewer for short local exploration with a real desktop.
- Stream to a separate viewer or serve one when the producer is remote or
  headless.
- Save an `.rrd` when the run must be inspectable later, reproducible in CI, or
  shared without keeping the producer alive.
- Embed a viewer only when it is part of the actual application experience;
  otherwise keep visualization out of the service boundary.

## Make the recording understandable

- Organize entity paths around the robot, sensors, policy, and world so related
  data shares a useful hierarchy.
- Use an explicit sequence or time timeline for episodes and rollouts. Log
  static geometry once and changing state at the corresponding step.
- Align transforms, images, actions, predictions, and outcomes on the same time
  basis before interpreting what the viewer shows.
- Check the current [Rerun documentation](https://rerun.io/docs) and
  [examples](https://rerun.io/examples) before choosing archetypes or calling
  APIs. Names and signatures change between releases.

## Go deeper only when needed

- For local, remote, file, and browser modes plus their common failures, read
  [OPERATING-MODES.md](OPERATING-MODES.md).
- For the Robium-tested Gradio streaming pattern and dependency conflict, read
  [GRADIO.md](GRADIO.md).
- Let LeRobot's dataset visualizer produce the recording when inspecting a
  LeRobot episode; use LeRobot guidance for its current command.
- When the boundary is live ROS topics, use RViz2 or Foxglove. Use the
  visualization skill only when the tool itself has not been chosen.

## Done

- The chosen sink works in the target environment, related data is aligned and
  navigable, and a saved or replayable artifact exists when the observation
  matters beyond the live session.