4. MCAP Convert

mcap-convert is a standalone command-line tool that converts an MCAP recording into the SQLite .db format used by DDS Record & Replay.

Unlike DDS Replayer, this tool does not publish data back into a DDS domain. Instead, it reads an existing MCAP file and generates a SQLite output file for workflows that require SQL output.

4.1. Using MCAP Convert

After installing the standalone conversion tool, source the installation environment and run:

source install/setup.bash
mcap-convert -i /path/to/recording.mcap

If --sql-output is not provided, the tool writes the output next to the input file using the same base name and the .db extension.

To write the converted output to a specific location, pass --sql-output:

source install/setup.bash
mcap-convert -i /path/to/recording.mcap --sql-output /path/to/recording.db

If the value given to --sql-output has no extension, .db is appended automatically.

To tune the conversion batch size, use --sql-batch-size:

source install/setup.bash
mcap-convert -i /path/to/recording.mcap --sql-batch-size 8192

The batch size controls how many messages are processed before they are written to the SQLite output. The default value is 4096. Larger values can improve throughput at the cost of higher memory usage, while smaller values reduce memory usage and force more frequent flushes. The value must be between 1 and 160000001.

4.2. Optional Configuration File

The converter accepts an optional YAML configuration file through --config-path.

This file is a DDS Replayer configuration file, and it is validated against the DDS Replayer schema: a DDS Recorder configuration file is rejected. See Replay configuration for the available settings.

Only a subset of those settings affects the conversion, since no data is published to a DDS network:

• begin-time and end-time restrict the range of messages that are converted.

• partitions restricts the conversion to the messages published on the listed partitions.

• logging configures the traces of the conversion itself.

The remaining settings, such as rate or start-replay-time, are accepted by the schema but have no effect on the conversion.

If type information is not available for a topic in the input MCAP file, the converter still stores the CDR payload in the SQLite output, but deserialized type data cannot be generated for that topic.

4.3. MCAP Convert Command-Line Parameters

The mcap-convert application supports the following input arguments:

Command	Description	Option	Possible Values	Default Value
Help	It shows the usage information of the application.	-h --help
Version	It shows the current version of DDS Record & Replay and the hash of the last commit of the compiled code.	-v --version
Input File	Input MCAP file path.	-i --input-file	Readable file path	Required
Configuration File	Optional YAML configuration file path.	-c --config-path	Readable file path
SQL Output	Output SQLite file path. If the path has no extension, .db is appended automatically.	--sql-output	File path	Input file path with .db extension
SQL Batch Size	Number of messages processed before flushing a batch into the SQLite output.	--sql-batch-size	Integer greater than 0	4096
Debug	Enables the converter logs so the execution can be followed by internal debugging information. Sets Log Verbosity to info and Log Filter to DDSREPLAYER.	-d --debug
Log Verbosity	Set the verbosity level so only log messages with equal or higher importance level are shown.	--log-verbosity	info warning error	warning
Log Filter	Set a regex string as filter.	--log-filter	String	"DDSREPLAYER"