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 | window,keyboard,mouse,keyboard/state |
--help |
boolean | Show this message and exit. | False |
owl mcap info¶
Display information about the .mcap file.
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 record¶
Record screen, keyboard, mouse, and window events to an .mcap and .mkv file.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--record-audio / --no-record-audio |
boolean | Whether to record audio | True |
--record-video / --no-record-video |
boolean | Whether to record video | True |
--record-timestamp / --no-record-timestamp |
boolean | Whether to record timestamp | True |
--show-cursor / --no-show-cursor |
boolean | Whether to show the cursor in the capture | True |
--fps |
float | The frame rate of the video. Default is 60 fps. | 60.0 |
--window-name |
text | The name of the window to capture, substring of window name is supported | None |
--monitor-idx |
integer | The index of the monitor to capture | None |
--width |
integer | The width of the video. If None, the width will be determined by the source. | None |
--height |
integer | The height of the video. If None, the height will be determined by the source. | None |
--additional-args |
text | Additional arguments to pass to the pipeline. For detail, see https://gstreamer.freedesktop.org/documentation/d3d11/d3d11screencapturesrc.html | None |
--start-after |
float | Delay recording start by this many seconds. Shows countdown during delay. | None |
--stop-after |
float | Automatically stop recording after this many seconds from start. | None |
--health-check-interval |
float | Interval in seconds for checking resource health. Set to 0 to disable. | 5.0 |
--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
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--keep-window |
text | Window name to keep events for | _required |
--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