API Reference
Apple Shortcuts
Control MouseViz from the macOS Shortcuts app and Siri with 9 built-in actions.
MouseViz integrates with the macOS Shortcuts app via App Intents, giving you 9 actions you can use in any Shortcut workflow or trigger via Siri.
Setup
No setup required. Once MouseViz is installed, all actions appear automatically in the Shortcuts app under the MouseViz section.
To find them:
- Open Shortcuts.app
- Create a new Shortcut or edit an existing one
- Search for "MouseViz" in the action library
Available Actions
Recording
| Action | Description | Returns |
|---|---|---|
| Start MouseViz Recording | Begins a new recording session with countdown. Opens the app if not running. | Status message |
| Stop MouseViz Recording | Stops the current recording and returns the saved session path. | Session file path |
| Pause MouseViz Recording | Pauses the active recording without ending it. | Status message |
| Resume MouseViz Recording | Resumes a paused recording. | Status message |
Markers
| Action | Description | Parameters | Returns |
|---|---|---|---|
| Add MouseViz Marker | Adds a named task marker to the active recording. | Marker Name (required) | Confirmation message |
Status & History
| Action | Description | Parameters | Returns |
|---|---|---|---|
| Get MouseViz Status | Returns the current recording status including duration, clicks, moves, and markers. | None | Recording Status entity |
| List MouseViz Sessions | Returns a list of recent recording sessions from history. | Limit (default: 10) | Array of Session entities |
Overlay
| Action | Description | Returns |
|---|---|---|
| Toggle MouseViz Overlay | Toggles the visualization overlay on or off. | New visibility state |
Export
| Action | Description | Parameters | Returns |
|---|---|---|---|
| Export MouseViz Heatmap | Exports the current heatmap visualization to a file. | Output Directory (optional) | File path |
Siri Phrases
Each action has associated Siri phrases. Some examples:
- "Start recording in MouseViz"
- "Stop MouseViz recording"
- "Pause recording in MouseViz"
- "Resume MouseViz"
- "Add marker in MouseViz"
- "Get MouseViz status"
- "List MouseViz sessions"
- "Toggle MouseViz overlay"
- "Export heatmap from MouseViz"
Shortcut Examples
Auto-Record with Markers
Create a Shortcut that starts a recording, waits for a set time, adds markers at intervals, and stops:
- Start MouseViz Recording
- Wait 30 seconds
- Add MouseViz Marker — name: "Task 1 Complete"
- Wait 30 seconds
- Add MouseViz Marker — name: "Task 2 Complete"
- Stop MouseViz Recording
Quick Status Check
Create a single-action Shortcut bound to a keyboard shortcut:
- Get MouseViz Status
- Show Result — displays tracking state, duration, and click count
Scheduled Export
Combine with Shortcuts automation to export heatmaps at regular intervals:
- Export MouseViz Heatmap — directory: ~/Desktop/Heatmaps
- Show Notification — "Heatmap exported"
Available since v1.2