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:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--install-completion |
boolean | Install completion for the current shell. | None |
--show-completion |
boolean | Show completion for the current shell, to copy it or customize the installation. | None |
--help |
boolean | Show this message and exit. | False |
owl mcap cat¶
Print messages from an .mcap file in a readable format.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--pretty / --no-pretty |
boolean | Pretty print JSON output | True |
--topics |
text | Topics to include (space-separated or multiple --topics flags) | None |
--exclude |
text | Topics to exclude (space-separated or multiple --exclude flags) | None |
--start-time |
integer | Start time in seconds | None |
--end-time |
integer | End time in seconds | None |
--n |
integer | Number of messages to print | None |
--help |
boolean | Show this message and exit. | False |
owl mcap convert¶
Convert an .mcap file into an .srt subtitle file. After the conversion, you may play .mkv file and verify the sanity of data.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--topics |
text | Comma-separated list of topics to include in the subtitle file | ['mouse/raw', 'mouse', 'keyboard'] |
--help |
boolean | Show this message and exit. | False |
owl mcap convert-overlay¶
Convert an .mcap file into a video with overlays showing mouse clicks and keyboard presses.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--topics |
text | Comma-separated list of topics to include in the overlay | ['mouse/raw', 'keyboard'] |
--fps |
float | Output video frame rate (default: use original MCAP frame rate) | None |
--max-duration-seconds |
float | Maximum duration in seconds to generate (default: entire video) | None |
--original-width |
integer | Original recording width resolution for mouse movement scaling | 2560 |
--original-height |
integer | Original recording height resolution for mouse movement scaling | 1440 |
--help |
boolean | Show this message and exit. | False |
owl mcap info¶
Display information about the .mcap file(s). Shows detailed info for single file, summary for multiple files.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--force-upgrade |
boolean | Force upgrade mcap CLI to latest version | False |
--help |
boolean | Show this message and exit. | False |
owl mcap migrate¶
MCAP migration commands with rollback and cleanup support.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
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 # Clean backup files in specific directory owl mcap migrate cleanup file.mcap # Clean backup for specific MCAP file
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--dry-run |
boolean | Show what would be deleted without actually deleting | False |
--yes, -y |
boolean | Skip confirmation prompt | False |
--verbose, -v |
boolean | Show detailed cleanup information | False |
--help |
boolean | Show this message and exit. | False |
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:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--yes, -y |
boolean | Skip confirmation prompt | False |
--verbose, -v |
boolean | Show detailed rollback information | False |
--help |
boolean | Show this message and exit. | False |
owl mcap migrate run¶
Migrate MCAP files to the highest reachable version with automatic version detection.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--target, -t |
text | Target version (default: highest reachable) | None |
--dry-run |
boolean | Show what would be migrated without making changes | False |
--verbose, -v |
boolean | Show detailed migration information | False |
--keep-backups / --no-backups |
boolean | Keep backup files after migration | True |
--yes, -y |
boolean | Skip confirmation prompt | False |
--help |
boolean | Show this message and exit. | False |
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:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--uri |
text | URI to use for all screen topic events | _required |
--dry-run |
boolean | Show what would be changed without making modifications | False |
--verbose, -v |
boolean | Show detailed processing information | False |
--yes, -y |
boolean | Skip confirmation prompt | False |
--keep-backups / --no-backups |
boolean | Keep backup files after processing | True |
--help |
boolean | Show this message and exit. | False |
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:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--keep-window |
text | Window name to keep events for | None |
--auto-detect-window |
boolean | Auto-detect the most frequent window to keep | False |
--exact / --substring |
boolean | Use exact window name matching (default: substring) | False |
--dry-run |
boolean | Show what would be changed without making modifications | False |
--verbose, -v |
boolean | Show detailed sanitization information | False |
--yes, -y |
boolean | Skip confirmation prompt | False |
--keep-backups / --no-backups |
boolean | Keep backup files after sanitization | True |
--max-removal-ratio |
float range (between 0.0 and 1.0) |
Maximum ratio of messages that can be removed (0.0-1.0). Safety feature to prevent accidental over-sanitization. | 0.2 |
--help |
boolean | Show this message and exit. | False |
Related Documentation¶
- OWAMcap Format Guide - Format specification
- Exploring Data - Analysis workflows
- CLI Tools - Complete CLI overview