Replay a recording into a graph
Replaying a recording reproduces a run without the robot or sensors, so you can debug and compare changes on identical inputs. This guide plays an MCAP recording into a live graph at its recorded timing. To view a recording in Foxglove instead, see Record data and view it in Foxglove.
✨ Agent prompt: Replay a recording into a graph
Before you start
- You have a recording made with the MCAP logger, and a C++ Holoscan graph with an operator input for each topic you want to replay.
- To replay encoded video (
foxglove.CompressedVideo), a build with the NVIDIA Video Codec SDK and a GPU with a hardware video decoder. - The
isaac::common::mcap_replayerlibrary available to your build. Inside the Isaac OS repository, Build and run covers this. From your own project, see Integrate in your project.
The steps below are taken from the runnable MCAP replay reference.
Replay a recording into your own graph
Create the replayer
Name every topic to replay together with the type its recorded messages decode to. The replayer needs no graph, so build it first:
Wire each topic to a consumer
Give your graph a reference to the replayer:
In compose(), declare a default clock, which compile() requires, then call attach<T>()
once per topic with the operator input that should receive it. A topic you named but never
attached is not read:
Compile, run, then start the replayer
Start the replayer after run_async(), not before, unlike the logger and the ROS 2 bridge:
Wait for the end, then stop
finished() becomes true once the replayer has published everything, or the run gave up or
failed. It does not mean your consumers have processed those messages, so if their results
matter, wait for them before requesting the graph to stop. Stop the replayer, which logs the
summary, then the graph:
A replayer can be started once. To replay the file again, build a new McapReplayer.
Check the replay
The run takes about as long as the recording did, because replay follows the recorded
timeline. On stop() the replayer logs a per-topic summary. A healthy run reports every topic
delivered, nothing refused and nothing unreadable.
The counts are messages the replayer published, not messages your consumer processed. A consumer too slow to keep up loses its oldest unread messages without any message being refused.
📄 Example output
Change the speed or repeat the recording
Pass ReplayOptions before the topics. playback_speed is recorded seconds per wall-clock
second, so 2.0 replays in half the time. loop starts the recording over at its end, and
the run then continues until you stop it:
Replay a camera image topic
Image topics are recorded in the logger’s tensor envelope. Name them with a contract that bounds the frame size. A frame larger than the bound is refused when it is published:
Replayed frames arrive in host memory.
Replay an encoded video topic
Declare an encoded video topic like a raw image topic, naming the video topic rather than its
<topic>/metadata channel. Each frame is decoded on the GPU and published as a host tensor.
video_decoder_cuda_device in ReplayOptions picks the GPU that decodes (default 0):
Size the contract for the encoding the video was recorded from: an RGBA8 frame is larger than
an RGB8 one.
- Video is lossy, so replayed colors match the recording only to within compression loss.
- An
RGBA8recording replays with alpha 255, because H.264 and H.265 carry no alpha.
Replay while also recording
A graph has one flat namespace for imported and exported topics. If the same graph also records
a topic with the logger, or runs two replays, set operator_name in ReplayOptions so the
replayer’s endpoints get a distinct prefix.
Try it with the reference apps
Record five seconds of data. The app prints the path of the file it wrote:
Replay that file. Paths are inside the container, so a file under mcap_logger_output/ is at
/workspace/isaac_os/mcap_logger_output/:
The reference app replays seven topics and exposes --playback-speed=<number> and --loop.
A looping run ends on Ctrl+C and prints its summary.
If the replay is not what you expect
⚠️ The constructor throws
A topic name is not in the recording, or the type does not match what was recorded. This is checked before the graph is built. Check the topic names and types in the file.
For encoded video it also throws if the <topic>/metadata channel is missing, the build has no
NVIDIA Video Codec SDK, the GPU at video_decoder_cuda_device cannot decode the topic’s codec
(H.264 or H.265), or the topic’s first video message is missing or damaged. The message says
which.
⚠️ The run reports it never began
A consumer did not subscribe within 5 seconds, or reading made no progress for 5 seconds. The summary names the topic. Nothing was sent.
⚠️ Fewer video frames replay than were recorded
A video frame and its metadata message are joined on their log time. A message whose partner is missing is left out, and a warning at the end of the pass says how many. A frame that fails to decode, has an odd size, or decodes to a size other than its metadata’s is dropped and counted.
⚠️ Messages are refused or lost
A refusal means a message could not be published, usually because the consumer’s graph stopped.
The replayer does not slow down for a slow consumer: it drops the consumer’s oldest unread
messages to keep the recording’s timing. Make the consumer faster or lower playback_speed.
⚠️ The summary lists a few late messages at the start
The first messages on a topic can go out slower than the rest while replay warms up. The summary
gives a topic with late messages a line like 2 went out more than 10 ms after they were due (messages #1, #4), with their message numbers on that topic. The numbers count the messages
delivered on that topic, so they match the recording’s own order only while none were skipped; the
topic’s unreadable and refused counts show when some were. If the numbers are only the first few
and the topic’s average lateness and spacing stay low, the contents and the rest of the timing
are unaffected and no action is needed. If many messages are late, or the numbers are spread
through the run, the replay is falling behind during steady state: lower playback_speed, make
the consumer faster, or use a less busy machine. A looping replay also logs the late messages of
each pass as the recording starts over, since its summary only comes when the run ends. A topic
with a single message per pass has no restart to report at, so its late messages are listed for the
whole run.
Related
-
Library README: every option, how pacing works and how to read the summary statistics.
-
MCAP replay reference: the runnable app and its flags.