Skip to content

MCAP Commands (owl mcap)

Tools for working with MCAP files - the core data format for multimodal desktop recordings.

Command Reference

owl mcap

MCAP file management commands.

Usage:

owl mcap [OPTIONS] COMMAND [ARGS]...
owl mcap cat

Print messages from an .mcap file in a readable format.

Usage:

owl mcap cat [OPTIONS] {mcap_path}
owl mcap info

Display information about the .mcap file(s). Shows detailed info for single file, summary for multiple files.

Usage:

owl mcap info [OPTIONS] {mcap_paths}...
owl mcap migrate

MCAP migration commands with rollback and cleanup support.

Usage:

owl mcap migrate [OPTIONS] COMMAND [ARGS]...
owl mcap migrate cleanup

Clean up MCAP backup files.

This command finds backup files (.mcap.backup) using the specified patterns and removes them after confirmation. Use --dry-run to preview what would be deleted.

Examples: owl mcap migrate cleanup # Clean all backup files in current directory tree owl mcap migrate cleanup ".mcap.backup" # Clean backup files in current directory only owl mcap migrate cleanup "/path/to/backups//.mcap.backup" # Clean all backup files recursively under a specific directory owl mcap migrate cleanup file.mcap # Clean backup for specific MCAP file

Usage:

owl mcap migrate cleanup [OPTIONS] [patterns]...
owl mcap migrate rollback

Rollback MCAP files from their backup files.

This command finds backup files (.mcap.backup) corresponding to the specified MCAP files and restores the original files from the backups. The backup files are removed after successful rollback.

Usage:

owl mcap migrate rollback [OPTIONS] {files}...
owl mcap migrate run

Migrate MCAP files to the highest reachable version with automatic version detection.

Usage:

owl mcap migrate run [OPTIONS] {files}...
owl mcap rename-uri

Rename URIs in mediaref fields of screen topic events in MCAP files.

This command processes MCAP files to set all URIs in the mediaref fields of screen topic events to the specified new URI. This is useful for updating file paths or URLs when media files have been moved or renamed.

Examples: owl mcap rename-uri recording.mcap --uri "new_video.mkv" owl mcap rename-uri *.mcap --uri "/new/path/video.mp4" owl mcap rename-uri data.mcap --uri "http://new.com/video" --dry-run

Usage:

owl mcap rename-uri [OPTIONS] {files}...
owl mcap sanitize

Sanitize MCAP files by keeping only events when a specific window is active.

This command filters MCAP files to retain only the events that occurred when the specified window was active, effectively removing data from other applications for privacy or focus purposes.

Safety feature: By default, the operation will be blocked if more than 20% of messages would be removed, preventing accidental over-sanitization. Use --max-removal-ratio to adjust this threshold.

Examples: owl mcap sanitize recording.mcap --keep-window "Notepad" owl mcap sanitize *.mcap --keep-window "Work App" --exact owl mcap sanitize data.mcap --keep-window "Browser" --dry-run owl mcap sanitize data.mcap --keep-window "App" --max-removal-ratio 0.95 owl mcap sanitize recording.mcap --auto-detect-window

Usage:

owl mcap sanitize [OPTIONS] {files}...
owl mcap subtitle

Generate subtitle file from MCAP recording for playback verification.

Usage:

owl mcap subtitle [OPTIONS] {input_file}
owl mcap trim

Trim mcap recording and referenced MKV files to a specific time range.

Usage:

owl mcap trim [OPTIONS] {input_mcap} {output_mcap}