Skip to content

releases/mcap-cli/v0.1.0

Choose a tag to compare

@amacneil amacneil released this 11 Jun 17:26
· 66 commits to main since this release
8b8f303

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).