URL Scheme API

MouseViz supports a focused URL scheme API for core recording and navigation commands in the v1.0.x launch. Additional automation commands are planned after the first public direct-download release is stable.

The general format is:

mouseviz://command-name?param1=value1&param2=value2

Quick Start

You can trigger URL schemes from Terminal, automation tools, or scripts:

Terminal:

open "mouseviz://start-recording"

AppleScript:

open location "mouseviz://start-recording"

Raycast / Alfred / Keyboard Maestro: Use the "Open URL" action with any mouseviz:// command.

Recording Control

Commands to start and stop mouse tracking sessions. Pause and resume automation are planned for a post-launch update.

Start Recording

mouseviz://start-recording

Begin a new mouse tracking session. If tracking is not already active, this starts a countdown and begins recording mouse movements, clicks, and scrolls. Ignored if already recording.

Available since v1.0

Stop Recording

mouseviz://stop-recording

Stop the current tracking session. If auto-save is enabled, the session data is saved automatically. Ignored if not recording.

Available since v1.0

Pause Recording

mouseviz://pause

Pause the current recording without ending it. Events stop being captured until resumed. Ignored if not recording or already paused.

Planned after v1.0.x

Resume Recording

mouseviz://resume

Resume a paused recording session. Ignored if not paused.

Planned after v1.0.x

Markers

Add timestamped markers during a recording to flag important moments. Marker automation is planned for a post-launch update.

Add Marker

mouseviz://add-marker?name=Task%201

Add a named task marker at the current timestamp in the active recording. Defaults to "Marker" if no name is provided. Ignored if not recording.

Examples:

# Add a named marker
open "mouseviz://add-marker?name=Checkout%20Flow"

# Add a default marker
open "mouseviz://add-marker"

Planned after v1.0.x

Overlay & Visualization

Commands for controlling the visualization overlay. These commands are planned after the v1.0.x launch.

Show Overlay

mouseviz://show-overlay

Show the visualization overlay (heatmap, trails, clicks, etc.).

Planned after v1.0.x

Hide Overlay

mouseviz://hide-overlay

Hide the visualization overlay.

Planned after v1.0.x

Set Visualization Mode

mouseviz://set-mode?mode=3

Set the active visualization mode using a bitmask value. See the mode values in Settings > Visualization.

Planned after v1.0.x

Clear Overlay

mouseviz://clear

Clear all visualization data (heatmap, trails, click pulses) from the overlay.

Planned after v1.0.x

Export

Export Heatmap

mouseviz://export-heatmap

Open the export dialog for the current heatmap visualization. Exports to the configured default directory.

Planned after v1.0.x

Query Commands

Query commands will return JSON data by copying it to your system clipboard. These commands are planned after the v1.0.x launch.

Get Status

mouseviz://status

Copies JSON with the current recording status to the clipboard:

{
  "isTracking": true,
  "isPaused": false,
  "duration": 125.4,
  "totalMoves": 4200,
  "totalClicks": 38,
  "totalScrolls": 12,
  "markerCount": 3,
  "eventCount": 4250,
  "activeModes": 1,
  "participant": "Alice",
  "project": "Checkout Redesign"
}

Automation example:

open "mouseviz://status" && sleep 0.5 && pbpaste | jq .isTracking

Planned after v1.0.x

List Session History

mouseviz://list-history?limit=5

Copies a JSON array of recent sessions to the clipboard.

Planned after v1.0.x

Get Version

mouseviz://version

Copies the app version and build number as JSON to the clipboard.

Planned after v1.0.x

Health Check

mouseviz://health-check

Copies a diagnostic health report as JSON to the clipboard. Useful for troubleshooting.

Planned after v1.0.x

Navigation

Commands that open specific windows or panels in MouseViz.

Open Settings

mouseviz://settings

Open the MouseViz settings window.

Available since v1.0

Open Study Scripts

mouseviz://study-scripts

Open the Study Scripts panel to view, create, and manage your study scripts.

Available since v1.0

Import Study Script

mouseviz://import-study?file=/path/to/script.json

Import a study script from a JSON file on disk. The file must conform to the MouseViz study script schema. After import, the Study Scripts panel opens automatically.

Examples:

# Import from Desktop
open "mouseviz://import-study?file=/Users/me/Desktop/usability-test.json"

# Import from Downloads
open "mouseviz://import-study?file=/Users/me/Downloads/study.json"

The file path must be URL-encoded if it contains spaces or special characters.

Available since v1.0

Open File

mouseviz://open-file?path=/path/to/image.png&type=image

Open a file in the appropriate MouseViz editor. This command is planned for the Share Extension handoff after the v1.0.x launch.

Planned after v1.0.x