mcap

Breaking changes

• mcap filter is now lossless by default: metadata and attachments are kept unless you pass the new --exclude-metadata / --exclude-attachments flags. The old --include-metadata / --include-attachments flags are now hidden deprecated no-ops that warn on stderr. (#1756)
• mcap filter --start / --end now apply to messages only; attachments are no longer dropped when their log_time falls outside the window (use --exclude-attachments to drop them). (#1756)
• mcap filter, mcap compress, and mcap decompress no longer silently re-sort indexed inputs: an out-of-order indexed file was previously re-sorted to log time, but the default is now --order preserve (keep stored message order). Pass --order log_time to restore the previous behavior. (#1762)
• Rewrite commands (filter, compress, decompress, sort) now write records in a standardized physical layout (metadata after the header → messages → attachments before Data End), so byte-level output can differ from 0.2.0 even when logical content is unchanged. (#1756, #1757)

New features

• Shared --order <preserve|log_time|topic> flag on filter, compress, decompress, and sort. preserve keeps stored order, log_time sorts by ascending log time (log-time alias), and topic groups each channel's messages together (channels by topic name then channel ID), placing each channel in its own chunk(s) when chunking is enabled for contiguous single-topic reads. Note that topic always buffers the selected messages in memory, and log_time buffers them when the input has no summary. (#1762, #1754, #1757)
• mcap filter gains --exclude-metadata and --exclude-attachments to opt out of the new lossless default. (#1756)
• mcap filter gains --no-chunks (write records outside of chunks). (#1763)
• mcap filter, compress, and decompress gain --no-crc (disable all output CRC fields), matching convert/merge/sort. (#1763)
• mcap sort gains an overridable --order flag (defaults to log_time), and its input and output are now optional — it reads from stdin and writes to stdout when omitted. (#1757)
• Expanded and corrected --help text across commands (remote URL inputs and --allow-remote-scan, log-time semantics for time filters, corrected cat --json encoding names, attachment retrieval, and in-place add corruption warnings), and hid the deprecated --start-nsecs / --end-nsecs flags from help (they remain accepted). (#1774)

Bug fixes

• mcap cat --json now emits protobuf fields set to their proto3 default value (e.g. 0, "", false, enum zero-variants) instead of omitting them from the output. (#1765)
• Rewrite commands no longer silently drop messages when an indexed input's Statistics record disagrees with its chunk message indexes (or a message index can't be parsed); the engine falls back to a linear scan. (#1771)
• mcap compress --compression invalid values are now rejected at parse time (exit code 2, [possible values: zstd, lz4, none]) instead of failing at runtime. (#1767)

Deprecations

These flags were renamed for consistency across the rewrite commands; the old names still work as hidden aliases that print a stderr warning, so existing invocations keep functioning.

• mcap filter --output-compression renamed to --compression, matching sort and the other rewrite commands (which already used --compression); --compression wins if both are set. (#1761)
• mcap sort --output-file renamed to --output (-o is unchanged), matching the other rewrite commands — previously only sort and merge used --output-file. filter, compress, and decompress also accept the deprecated --output-file as a hidden alias for uniformity. (#1757)
• mcap merge --output-file renamed to --output (-o is unchanged), for the same cross-command consistency. (#1771)

Performance

• Bounded memory for piped stdin: rewrite commands now spool non-seekable stdin to a temporary file and memory-map it instead of buffering the whole MCAP in memory. (#1759)
• Standardizing record placement adds an up-front metadata scan on the linear (summaryless or fallback) path, a modest throughput regression (~12–22% in benchmarks); well-formed indexed inputs are unaffected. (#1756)

New features

• mcap list attachments, mcap list metadata, mcap get attachment, and mcap get metadata can read local MCAP files that omit summary/index records by scanning when needed. (#1723)
• mcap merge now guarantees log-time ordered output, using command-line file order and per-file input order as stable tie-breakers for equal timestamps. (#1730)

Bug fixes

• mcap doctor now reports invalid Statistics channel counts that lack prior summary Channel records. (#1722)
• mcap info now reports numeric counts for files without a Statistics record instead of unknown when the data can be derived. (#1725)
• mcap doctor now treats spec-legal out-of-order top-level message times as warnings by default, while --strict-message-order still errors. (#1724)
• Output-writing commands now reject local output paths that resolve to the input file before truncating or writing. (#1729)
• Tarball/source-archive builds now stamp the short commit SHA into mcap --version instead of reporting unknown. (#1727)
• mcap doctor -v no longer emits the low-value Examining ... progress line on clean diagnostics. (#1731)
• Human-readable byte output now consistently uses decimal SI units (kB, MB, GB), and throughput labels use /s. (#1733)

Performance

• Added Criterion command benchmarks for merge, filter, sort, compress, and decompress; this is benchmark coverage rather than a runtime performance change. (#1732)

The mcap CLI has been rewritten in Rust. It is a drop-in replacement for the
previous release (v0.0.x) with the same commands, a smaller binary, new remote
and read capabilities, and a number of other changes described below.

New features

• Expanded remote reads: added HTTP(S) and Azure Blob Storage, alongside the
  existing Amazon S3 and Google Cloud Storage support. Indexed reads (info,
  list, single-record get) use the file index to fetch only the bytes they
  need, with no full download.
• Self-contained ROS 2 .db3 conversion. mcap convert reads the message
  definitions embedded in ROS 2 bags (Iron and later) — no sourced workspace or
  --ament-prefix-path required.
• Reads and sorts files without an index. mcap cat now reads local files
  that have no index by scanning them in file order, and mcap sort now sorts
  unindexed files, instead of refusing them.
• Reads from pipes. cat, filter, compress, and decompress accept piped
  (non-seekable) stdin, so producer | mcap filter -o out.mcap works.
• Reads files with missing or incomplete summaries. info, list, and cat
  fall back to scanning the data section when the summary is absent or incomplete
  (printing a summary section not available; full scan may be slow warning to
  stderr), and resolve schemas/channels that are defined only inside chunks — the
  previous CLI silently reported such files as empty.
• Smaller binary: roughly half the size. The Linux amd64 binary is 14.3 MB,
  down from 28.3 MB.

Bug fixes

• mcap doctor no longer crashes when examining files with malformed summary
  records (a truncated or corrupt ChunkIndex, AttachmentIndex, Schema, Channel,
  Message, Metadata, MetadataIndex, or Header record previously caused a
  segmentation fault).
• mcap recover always produces a valid, readable output file. Recovery
  previously could write internally inconsistent chunk indexes for some inputs.
• mcap filter topic-regex filtering behaves correctly.
  Previously, when --include-topic-regex matched no channels (or
  --exclude-topic-regex matched every channel), the resulting empty topic set
  was treated as "no filter" and every message was silently passed through. Both
  cases now produce an empty result, as expected.
• No more crashes or silent data loss on malformed files. On chunk-indexed
  files whose summary does not fully list their channels and schemas (disallowed
  by the MCAP spec), the previous CLI could segfault and leave a corrupt partial
  output (sort), or silently write a file containing none of the input's
  messages (compress). The new CLI fails with a clear, actionable error
  pointing to mcap recover.
• Attachments are no longer silently dropped by compress, decompress, and
  filter. The previous CLI omitted attachments that weren't listed in an
  attachment index; they are now preserved and indexed in the output.
• mcap du totals now add up to the file size. Each record's reported size
  includes its on-disk framing (the 1-byte opcode + 8-byte length prefix), and
  attachment records are now included in the table; previously both were omitted,
  so the totals undercounted the file. Percentages are computed in double
  precision, removing rounding artifacts in the last digits (e.g. 66.666667).

Removed

• mcap version subcommand — use mcap --version, which now reports both the
  CLI and library versions (replacing mcap version --library).
• --config global flag (no $HOME/.mcap.yaml config file) — the flag was
  never actually used; no command ever read a value from the config file.
• --pprof-profile global flag.
• convert --ament-prefix-path — ROS 2 .db3 conversion now uses embedded
  message definitions.
• compress --unchunked — compressed output is always chunked by definition.
• recover --always-decode-chunk — chunks are now always decoded.

Other changes

• mcap recover signals data loss through its exit code: 0 = full recovery,
  3 = recovered but lossy/truncated, 1 = nothing recovered. Previously it exited
  0 as long as recovery started, even when data was lost. It now defaults to
  --compression preserve (was zstd) and always decodes and re-encodes every
  chunk to guarantee valid output.
• mcap convert selects the input type by file extension (.bag for ROS 1,
  .db3 for ROS 2) instead of inspecting file contents, so inputs must use a
  recognized extension. To convert pre-Iron .db3 bags that have no embedded
  message definitions, use ros2 bag convert first.
• Writing over the input file is refused by sort and convert. Using the
  same path for input and output previously truncated the input and lost data.
• Invalid --compression values are now rejected everywhere instead of being
  silently accepted.
• mcap add metadata rejects duplicate --key names instead of silently
  keeping the last value, and now allows = inside values (e.g. -k key=a=b).
• mcap completion <shell> now also supports elvish (in addition to bash,
  zsh, fish, and powershell), and rejects an unknown shell name with a usage
  error instead of printing help.
• mcap doctor reports every structural problem it finds and writes all
  diagnostics to stderr (previously it stopped at the first error and wrote some
  warnings to stdout).
• Usage/argument errors exit with code 2 (the conventional code) and errors
  are prefixed with Error: on stderr.
• CRC/chunk flags renamed: --include-crc → --no-crc and --chunked →
  --no-chunks on convert, merge, and sort (effective defaults unchanged).
• New global flags: --color {auto,always,never}, -v/--verbose
  (repeatable), and --allow-remote-scan.
• Remote whole-file scans require --allow-remote-scan. Indexed reads
  (info, list, single-record get) need no flag, but commands that read or
  download the whole file (filter, merge, convert, recover, or any
  linear-scan fallback) require it. With multiple remote inputs, each is
  downloaded independently, so peak temporary disk usage can approach the combined
  input size.
• Rewritten files record the CLI as the writing library
  (Header.library = mcap-cli/<version> mcap-rust/<version>) for compress,
  decompress, filter, sort, recover, merge, and convert, and no longer
  carry forward the source file's library value. mcap add leaves the original
  header untouched.
• mcap info now sorts compression lines, renders wall-clock start/end times
  in UTC, and shows absolute RFC3339 timestamps only for recordings dated
  2000-01-01 or later (older/relative timestamps render as decimal seconds).