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.

4.2. Optional Configuration File

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

This file uses the same structure as the DDS Replayer configuration file. See Replay configuration for the available settings.

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
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"