ros2bagplayer

R2026b

Replay ROS 2 bag data to ROS 2 network

Since R2026b

Description

Use the ros2bagplayer object to publish messages from a ROS 2 bag file to the ROS 2 network. Use this object to replay recorded ROS 2 data for simulation, debugging, and algorithm testing of subscriber nodes with realistic timing without needing the original hardware. You can create multiple player objects on the same or different bag files. By default, the ros2bagplayer object starts publishing all topics in the bag. You can also configure include and exclude filtering using topic names and regular expressions when starting playback. You can pause and resume playback as many times as needed, seek to a desired time point by using seekPlayer, and change the playback rate by using setRate. After stopping playback, you can start playback again on the same object. To change ros2bagplayer properties, create a new player object.

Creation

Syntax

bagPlayer = ros2bagplayer(bagPath)

bagPlayer = ros2bagplayer(bagPath,Name=Value)

Description

bagPlayer = ros2bagplayer(bagPath) creates a ROS 2 bag player object that replays messages from the specified ROS 2 bag file to the ROS 2 network. Use the bagPath input argument to set the Path property.

bagPlayer = ros2bagplayer(bagPath,Name=Value) sets player properties using name-value arguments.

Input Arguments

bagPath — Path to ROS 2 bag file

string scalar | character vector

Path to the ROS 2 bag file, specified as a string scalar or character vector. The path must point to an existing ROS 2 bag file.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

PlayerNodeName — Name of player node

string scalar | character vector

Name of the player node, specified as a string scalar or character vector. The player node takes the name of the created ros2bagplayer object by default.

Data Types: char | string

DomainID — Domain ID of ROS 2 network

0 (default) | numeric scalar

Domain ID of the connected ROS 2 network, specified as a numeric scalar.

Data Types: numeric

Rate — Initial playback rate

1.0 (default) | positive numeric scalar

Initial playback rate, specified as a positive numeric scalar. A value of 1.0 replays at the original recorded speed. Values greater than 1.0 speed up replay, and values less than 1.0 slow it down.

Data Types: double

Loop — Enable looped playback

false (default) | true or 1 | false or 0

Enable looped playback, specified as true (1) or false (0). When enabled, the bag restarts automatically after reaching the end and continues indefinitely until stopped.

Data Types: logical

StartOffset — Start playback offset into the bag

0 (default) | nonnegative numeric scalar

Start playback offset into the bag, specified as a nonnegative numeric scalar in seconds. The player skips the first N seconds of the bag before starting playback.

Data Types: double

PlaybackDuration — Maximum playback duration

Inf (default) | positive numeric scalar

Maximum playback duration, specified as a positive numeric scalar in seconds. The player stops playback after this many seconds of played time from the start offset. The default value Inf plays the entire bag.

Data Types: double

PlaybackUntil — Stop playback at a specific timestamp

Inf (default) | positive numeric scalar

Stop playback at a specific timestamp, specified as a positive numeric scalar in seconds. The player stops when the bag timestamp reaches the specified value. The default value Inf plays the entire bag.

Data Types: double

WaitForAllAcked — Option to wait for subscriber acknowledgment

0 (default) | nonnegative numeric scalar

Option to wait for subscriber acknowledgment, specified as a nonnegative numeric scalar. When enabled, the player waits for all published messages to be acknowledged by subscribers before publishing the next message. This option requires the publisher QoS reliability policy to be set to "reliable".

Data Types: logical

ClockPublishFrequency — Frequency for publishing to /clock topic

0 (default) | nonnegative numeric scalar

Frequency for publishing to the /clock topic, specified as a nonnegative numeric scalar in hertz. When set to a value greater than 0, the player publishes simulated time on the /clock topic at the specified frequency, enabling ROS 2 nodes using use_sim_time to follow bag timestamps. A value of 0 disables clock publishing.

Data Types: double

EnableLoanMessage — Use loaned messages for publishing efficiency

true (default) | true or 1 | false or 0

Use loaned messages for publishing efficiency, specified as true (1) or false (0). Loaned messages use zero-copy publishing to reduce memory allocation overhead during playback. Disable this option if compatibility issues occur with the middleware.

Data Types: logical

ReadAheadQueueSize — Buffer size for read-ahead message queue

1000 (default) | positive integer

Buffer size for the read-ahead message queue, specified as a positive integer. The player preloads this number of messages into memory for smooth, deterministic playback. Increase this value for smoother playback at the cost of more memory usage.

Data Types: uint64

Output Arguments

bagPlayer — ROS 2 bag player

ros2bagplayer object

ROS 2 bag player, returned as a ros2bagplayer object.

Properties

Node Data

Path — Input path to ROS 2 bag file

string scalar | character vector

This property becomes read-only after creation of the object.

Input path to the ROS 2 bag file, specified as a string scalar or character vector.

Data Types: char | string

PlayerNodeName — Name of player node

string scalar | character vector

This property becomes read-only after creation of the object.

Name of the player node, specified as a string scalar or character vector. The player node takes the name of the created ros2bagplayer object by default.

Data Types: char | string

DomainID — Domain ID of ROS 2 network

0 (default) | numeric scalar

This property becomes read-only after creation of the object.

Domain ID of the connected ROS 2 network, specified as a numeric scalar.

Data Types: numeric

PlayerStatus — Current status of player

Read-only: "Idle" (default) | "Playing" | "Paused"

This property is read-only.

Current status of the player, represented as "Idle", "Playing", or "Paused".

Data Types: char | string

Filters — Include and exclude filter settings

Read-only: 1×1 struct

This property is read-only.

Include and exclude filter settings, returned as a structure with two fields:

• IncludeFilters — Structure containing IncludeTopics and IncludeRegex fields.

• ExcludeFilters — Structure containing ExcludeTopics and ExcludeRegex fields.

You can apply or modify filter settings only through the startPlaying function.

Data Types: struct

StorageSettings — Bag file storage settings

Read-only: 1×1 struct

This property is read-only.

Bag file storage settings, returned as a structure containing the StorageFormat field. The storage format is automatically detected from the bag file.

Data Types: struct

PlayerSettings — Player configuration settings

Read-only: 1×1 struct

This property is read-only.

Player configuration settings, returned as a structure with the following fields:

• ReadAheadQueueSize — Number of messages preloaded into memory (default: 1000).

• Rate — Playback-rate multiplier (default: 1).

• Loop — Whether looped playback is enabled (default: false).

• ClockPublishFrequency — Frequency for publishing to the /clock topic in hertz (default: 0).

• StartOffset — Seconds to skip at the beginning of the bag (default: 0).

• PlaybackDuration — Maximum playback duration in seconds (default: Inf).

• PlaybackUntil — Stop at an absolute timestamp in seconds (default: Inf).

• PlaybackUntilNSec — Stop at an absolute timestamp in nanoseconds (default: Inf).

• WaitForAllAcked — Whether to wait for subscriber acknowledgment (default: false).

• EnableLoanMessage — Whether loaned message publishing is disabled (default: false).

These settings are configured through name-value arguments in the constructor.

Data Types: struct

To understand filter precedence, include filters first narrow the set of topics to play or replay, and exclude filters then further remove topics from that narrowed set.

Include Filters

IncludeTopics — Name of topics to include

string scalar | character vector | cell array

Name of topics to include during playback, specified as a string scalar, character vector, or a cell array.

You can apply or modify these settings only through the startPlaying function.

IncludeRegex — Name of topics to include that match regular expressions

string scalar | character vector

Name of topics to include during playback that match regular expressions, specified as a string scalar or character vector.

You can apply or modify these settings only through the startPlaying function.

Exclude Filters

ExcludeTopics — Name of topics to exclude

string scalar | character vector | cell array

Name of topics to exclude from playback, specified as a string scalar, character vector, or a cell array.

You can apply or modify these settings only through the startPlaying function.

ExcludeRegex — Name of topics to exclude that match regular expressions

string scalar | character vector

Name of topics to exclude from playback that match regular expressions, specified as a string scalar or character vector.

You can apply or modify these settings only through the startPlaying function.

Object Functions

startPlaying	Start playing ROS 2 bag data to ROS 2 network
stopPlaying	Stop playing ROS 2 bag data to ROS 2 network
pausePlaying	Pause playing ROS 2 bag data without losing playback state
resumePlaying	Resume playing ROS 2 bag data after pausing
seekPlayer	Seek to target time in ROS 2 bag during replay
setRate	Change replay rate of ROS 2 bag player

Examples

Navigate ROS 2 Bag Playback with Seek and Resume

This example shows how to create a ros2bagplayer object for a ROS 2 bag file, start playback, pause at a moment of interest, seek to a specific target timestamp, resume playback from that point, and stop when the investigation is complete. Use this workflow to navigate to a relevant event in a large bag without replaying the entire file from the beginning.

Create a ROS 2 bag player to play recorded ROS 2 network data from a bag file.

bagPlayer = ros2bagplayer(fullfile(pwd,"ros2bag_3D_data"));

Verify the player status before starting playback.

disp(bagPlayer.PlayerStatus)

Idle

Start playing all topics from the bag file to the ROS 2 network. The player publishes bag messages in chronological order.

startPlaying(bagPlayer);
disp("Playback started.")

Playback started.

disp(bagPlayer.PlayerStatus)

Playing

You can run ros2 topic echo topicName with topicName specified as any of topic from the bag to verify that the player is publishing messages. Here is a sample code:

ros2 topic echo /scan

Allow playback to run briefly, then pause the player to inspect a moment of interest. Pausing preserves the playback position so you can investigate downstream system behavior.

pause(3)
pausePlaying(bagPlayer);
disp("Playback paused.")
disp(bagPlayer.PlayerStatus)

Seek to a target timestamp in the bag to skip directly to the event of interest. The player repositions to the specified time point (in seconds) or the nearest valid time point in the bag.

targetTime = 120.5;
seekPlayer(bagPlayer,targetTime);
disp("Seeked to " + targetTime + " seconds in the bag.")

Resume playback from the new position. The player continues publishing messages from the seeked time point.

resumePlaying(bagPlayer);
disp("Playback resumed from seeked position.")
disp(bagPlayer.PlayerStatus)

Allow playback to continue for the duration of interest, then stop the player to end the investigation. Stopping returns the player to an idle state.

pause(5)
stopPlaying(bagPlayer);
disp("Playback stopped.")
disp(bagPlayer.PlayerStatus)

Play Filtered Topics and Adjust Playback Rate

Create a ros2bagplayer object, start playing a selected subset of topics using include and exclude filters, change the playback speed during the run, and stop playback when the scenario is complete. This workflow is useful for playing filtered topics to the ROS 2 network and adjusting the playback rate to speed up or slow down testing.

Create a ROS 2 bag player to play recorded 3D visualization data from a bag file.

bagPlayer = ros2bagplayer(fullfile(pwd,"ros2bag_3D_data"));

Start playback with topic filters. Use ExcludeTopics to skip the second marker topic and play only the scan and first marker topic. Exclude filters let you remove irrelevant topics from playback without listing every topic you want to keep. Note that ExcludeTopics can only be used when IncludeTopics is left at its default (all topics).

startPlaying(bagPlayer, ...
    ExcludeTopics={'/visualization_marker_2'});
disp("Playback started with filtered topics.")

Playback started with filtered topics.

disp(bagPlayer.PlayerStatus)

Playing

Allow playback to run at the default rate (1x) for an initial observation period.

pause(2)

Speed up the playback rate to 3x to fast-forward through a less interesting portion of the data. A rate value greater than 1.0 speeds up playback, while a value less than 1.0 slows it down. The new rate takes effect immediately.

setRate(bagPlayer,3.0);
disp("Playback rate set to 3x.")

Playback rate set to 3x.

After fast-forwarding, slow down the playback rate to 0.5x for detailed inspection of a critical scenario segment.

pause(2)
setRate(bagPlayer,0.5);
disp("Playback rate set to 0.5x for detailed inspection.")

Playback rate set to 0.5x for detailed inspection.

Return the playback rate to the original recorded speed (1x).

pause(2)
setRate(bagPlayer,1.0);
disp("Playback rate restored to 1x.")

Playback rate restored to 1x.

Stop playback when the test scenario is complete. The player resets to an idle state, and you can call startPlaying again to restart from the beginning with the same or different filters.

pause(2)
stopPlaying(bagPlayer);

The player is currently idle. You must start playing before attempting to stop.

disp("Playback stopped.")

Playback stopped.

disp(bagPlayer.PlayerStatus)

Idle

Version History

Introduced in R2026b