URL Scheme API

Automate MouseViz by triggering actions via URL schemes from Raycast, Alfred, Keyboard Maestro, or custom scripts.

Overview

MouseViz supports a URL scheme API that lets you trigger any action programmatically. URL schemes are special links that, when opened, tell MouseViz to perform a specific action — like starting a recording session or importing a study script.

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"

Recording & Control

Commands to start and stop mouse tracking sessions and access app settings.

Start Recording

Availablev1.0+

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

URL Scheme

mouseviz://start-recording

Examples

Start a session

mouseviz://start-recording

Stop Recording

Availablev1.0+

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

URL Scheme

mouseviz://stop-recording

Examples

Stop the current session

mouseviz://stop-recording

Open Settings

Availablev1.0+

Open the MouseViz settings window.

URL Scheme

mouseviz://settings

Examples

Open settings

mouseviz://settings

Study Scripts

Commands for managing UX study scripts — structured task sequences used to guide participants through research sessions.

Open Study Scripts

Availablev1.0+

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

URL Scheme

mouseviz://study-scripts

Examples

Open the panel

mouseviz://study-scripts

Import Study Script

Availablev1.0+

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.

URL Scheme

mouseviz://import-study

Parameters

Name	Type	Required	Description
file	string	Yes	Absolute file path to the study script JSON file.e.g. /Users/me/Desktop/usability-test.json

Examples

Import a script from Desktop

mouseviz://import-study?file=/Users/me/Desktop/usability-test.json

Import from Downloads

mouseviz://import-study?file=/Users/me/Downloads/study.json

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

Visualization Modes

Toggle individual visualization layers on and off. These commands control what is rendered on the overlay.

Toggle Heatmap

Coming Soon

Toggle the visibility of the mouse movement heatmap overlay.

URL Scheme

mouseviz://toggle-heatmap

Toggle Spotlight

Coming Soon

Toggle Spotlight mode, which dims the screen and highlights the area around the cursor.

URL Scheme

mouseviz://toggle-spotlight

Toggle Trail

Coming Soon

Toggle the mouse movement trail visualization.

URL Scheme

mouseviz://toggle-trail

Toggle Clicks

Coming Soon

Toggle the visual click pulse animations on the overlay.

URL Scheme

mouseviz://toggle-clicks

Overlay & Export

Commands for managing the overlay state and exporting visualization data.

Toggle Tracking

Coming Soon

Toggle mouse tracking on or off. Unlike start/stop recording, this is a single command that switches between states.

URL Scheme

mouseviz://toggle-tracking

Clear Overlay

Coming Soon

Clear the current heatmap, trail, and all other visual data from the overlay.

URL Scheme

mouseviz://clear-overlay

Export Heatmap

Coming Soon

Open the export dialog for the current heatmap visualization.

URL Scheme

mouseviz://export-heatmap