Action JSON

Lunchpad.run() in a script takes an action as a JSON object. This page is that object, for every action a script can run.

Lunchpad.run({ type: "playSound", file: "C:\\Sounds\\airhorn.wav", volume: 0.8 });

The type says which action it is; the rest are its fields.

• A field marked * is required. An action missing one is skipped, and the reason goes to the log.
• Every other field may be left out: the engine fills in its default.
• Placeholders work in text fields, exactly as they do in the editor: {{velocity}}, {{secret.key}}, and the rest. See Variables and placeholders.
• The example under each action is the smallest object that runs.

Note

This page is generated from the app itself, so it says what this version of Lunchpad actually accepts. The field names are the same ones a page file uses, so an exported page is a good place to copy a working object from.

What is not here

The flow markers — Condition, Otherwise, Flip flop, Push-to-talk and their ends — only mean something inside an action list. A script that queues one has it skipped and logged, so they are left out of this list. Run script itself is here and works, but a snippet cannot see what a script it queued did.

Media

Play sound playSound

Play an audio file on an output device (`None` = app default device).

{ "type": "playSound", "file": "…" }

Field	Value	What it is
file*	text
volume	number	1.0 = 100 %; legacy allowed up to 20.0
start	number	Trim start, 0.0..1.0 of the file
end	number	Trim end, 0.0..1.0 of the file
outputDevice	text or null
volumeFromVelocity	true or false	Scale the volume by the trigger velocity (velocity-sensitive pads)

Text to speech textToSpeech

{ "type": "textToSpeech", "text": "…" }

Field	Value	What it is
text*	text
voice	text or null
volume	number

System audio setSystemVolume

Volume or mute of the default output or input device. `volume` is the level (0-100 %) for `Set`, the step for `Adjust`, unused for the mutes.

{ "type": "setSystemVolume", "target": "output", "volume": 0 }

Field	Value	What it is
target*	SystemVolumeTarget
mode	SystemVolumeMode
volume*	number
volumeFrom	text or null	Variable or placeholder that overrides `volume` when it holds a number
device	text or null	A specific device by name; `None` = the system's default device

Switch audio device setAudioDevice

Make a device the system default output (speakers) or input (microphone).

{ "type": "setAudioDevice", "target": "output", "device": "…" }

Field	Value	What it is
target*	SystemVolumeTarget
device*	text	Device name as the system lists it (placeholders allowed)

Stop all sounds stopAllSounds

Stop every sound Lunchpad is playing.

{ "type": "stopAllSounds" }

General

Delay delay

{ "type": "delay", "ms": 0 }

Field	Value	What it is
ms*	number
msFrom	text or null	A variable (or `{{template}}`) holding the milliseconds; `ms` when it is missing or not a number.

Switch page switchPage

{ "type": "switchPage", "pageId": "…" }

Field	Value	What it is
pageId*	text

Run another button runButton

Run another button's actions as part of this chain. With `wait` the runner waits for the other button's macro to finish.

{ "type": "runButton", "target": { "x": 0, "y": 0 } }

Field	Value	What it is
target*	ButtonRef
trigger	ButtonTrigger

Set colour setColor

Change and persist the colour of a button: this one (no target) or any other button on any page.

{ "type": "setColor", "color": { "mode": "palette", "index": 0 } }

Field	Value	What it is
color*	PadColor
target	ButtonRef or null

Set fader setFader

Move a fader (by name) to a value, as if its pad had been pressed: LEDs, `fader.<name>` and, unless `run_actions` is off, its actions.

{ "type": "setFader", "fader": "…", "value": "…" }

Field	Value	What it is
fader*	text
value*	text	Number or placeholder, clamped to the fader's range
runActions	true or false

Flow

Condition ifStart

Branch: actions up to `IfElse` run when the condition holds, actions between `IfElse` and `IfEnd` when it does not.

{ "type": "ifStart", "variable": "…", "op": "equals", "elseId": "…", "endId": "…" }

Field	Value	What it is
variable*	text
op*	CompareOp
value	text
elseId*	text
endId*	text

Loop loopStart

Loop: the actions up to `LoopTimeout` repeat, with a pause between rounds. `Count` runs the body once per value from `from` to `to` in steps of `step` (`loop.value`); `Until` repeats until the check holds, checked before or after each round; `Forever` repeats until the macro is stopped. When `timeout_ms` has passed, the actions between `LoopTimeout` and `LoopEnd` run instead. Everything after the end runs either way.

{ "type": "loopStart", "timeoutId": "…", "endId": "…" }

Field	Value	What it is
mode	LoopMode
variable	text
op	CompareOp
value	text
check	LoopCheck	`Until` only: where the check runs.
from	text	`Count` only: first value, last value and step; placeholders allowed.
to	text
step	text
intervalMs	number	Pause between two rounds, in milliseconds (never below `LOOP_MIN_INTERVAL_MS`).
timeoutMs	number	Time limit counted from the first round; 0 = none.
timeoutId*	text
endId*	text

Flip flop: A flipFlopStart

Actions between Start and Middle run on "A" presses, between Middle and End on "B" presses; `is_a` alternates and is persisted.

{ "type": "flipFlopStart", "middleId": "…", "endId": "…" }

Field	Value	What it is
middleId*	text
endId*	text
isA	true or false

Push-to-talk on pushToTalkStart

{ "type": "pushToTalkStart", "endId": "…" }

Field	Value	What it is
endId*	text

System

Launch application launchApplication

{ "type": "launchApplication", "executable": "…" }

Field	Value	What it is
executable*	text
arguments	text
hidden	true or false
killOnStop	true or false
saveOutputTo	text or null	Store the program's standard output in this variable (needs `wait`)
saveScope	VarScope

HTTP request httpRequest

Any HTTP call. URL, headers, body and auth may contain `{{velocity}}`, `{{x}}`, `{{y}}` and `{{pageId}}`.

{ "type": "httpRequest", "method": "get", "url": "…" }

Field	Value	What it is
method*	HttpMethod
url*	text
headers	list of HttpHeader
contentType	text or null	Content-Type for the body (`None` sends none / lets the mode decide)
body	text	Text body, or `name=value` lines for a multipart form
bodyMode	HttpBodyMode
bodyFile	text or null	File whose bytes are sent as the body (`body_mode = File`)
files	list of HttpFilePart	File parts of a multipart form (`body_mode = Multipart`)
auth	HttpAuth
timeoutMs	number
ignoreTlsErrors	true or false
saveTo	text or null	Store the response body in this variable (`<name>.status` gets the status code, `<name>.file` the saved file, `<name>.cached` whether the file was reused)
saveScope	VarScope
response	HttpResponse	What becomes of the response: text only, or a file in the download folder made from the body, a base64 field or a URL in a field
responseField	text	JSON field (dot path, `data.0.url`) for the field modes; empty = the whole body
fileName	text	File name (placeholders allowed) in the download folder, or an absolute path; empty = a name derived from the request
reuse	true or false	Skip the request when a file (or stored text) for the same inputs exists

Run script runScript

Run a JavaScript snippet with access to the variables; its result can be stored in a variable.

{ "type": "runScript", "code": "…" }

Field	Value	What it is
code*	text
saveTo	text or null
saveScope	VarScope

Set variable setVariable

Set a variable to a value (placeholders allowed).

{ "type": "setVariable", "name": "…", "value": "…" }

Field	Value	What it is
name*	text
value*	text
scope	VarScope

Add to variable addToVariable

Add a number to a variable (counters); missing or non-numeric values count as 0.

{ "type": "addToVariable", "name": "…", "amount": "…" }

Field	Value	What it is
name*	text
amount*	text	Number or placeholder, negative to subtract
scope	VarScope

Debug window debug

Show a window with `text`, placeholders filled in. Each action has its own window; running it again updates the text.

{ "type": "debug" }

Field	Value	What it is
title	text
text	text
alwaysOnTop	true or false	Keep the window above the others

Keyboard & mouse

Hotkey sequence hotkey

{ "type": "hotkey", "keystrokes": [ { "type": "key", "event": "down", "key": "…", "modifiers": [ "…" ] } ] }

Field	Value	What it is
keystrokes*	list of Keystroke
restoreAllAtEnd	true or false

Mouse sequence mouse

Mouse steps run in order: move, click, press, release, scroll, drag, wait.

{ "type": "mouse" }

Field	Value	What it is
steps	list of MouseStep

Get mouse position mousePosition

Remember where the pointer is: `<name>` = "x,y", plus `.x` and `.y`.

{ "type": "mousePosition", "saveTo": "…" }

Field	Value	What it is
saveTo*	text
saveScope	VarScope

Window

Get window getWindow

Find another program's window, the one in front or by title, and remember it: `<name>` = its handle, plus `.title`, `.app`, `.x`, `.y`, `.width` and `.height`.

{ "type": "getWindow", "saveTo": "…" }

Field	Value	What it is
target	WindowTarget
title	text
matching	TitleMatch
app	text
saveTo*	text
saveScope	VarScope

Set window setWindow

Find another program's window and raise, minimize, maximize, restore, lower, close, move, size or center it.

{ "type": "setWindow" }

Field	Value	What it is
target	WindowTarget
title	text
matching	TitleMatch
app	text
op	WindowOp
x	text
y	text
width	text
height	text
screen	text	1-based screen number, blank for the window's own; `move`, `bounds` and `center` take it as their frame of reference, `screen` moves there.

Get screen getScreen

Remember a screen: `<name>` = JSON with number, x, y, width, height, scale, dpi, primary and count (of screens), each also as `<name>.<field>`.

{ "type": "getScreen", "saveTo": "…" }

Field	Value	What it is
pick	ScreenPick
number	text	The 1-based number, for `pick: number` (placeholders)
saveTo*	text
saveScope	VarScope

Stop

Stop this macro stopThisMacro

{ "type": "stopThisMacro" }

Restart this macro restartThisMacro

{ "type": "restartThisMacro" }

Stop all macros stopAllMacros

{ "type": "stopAllMacros" }

OBS Studio

OBS: switch scene obsSwitchScene

{ "type": "obsSwitchScene", "scene": "…" }

Field	Value	What it is
scene*	text
collection	text

OBS: show or hide source obsToggleSource

{ "type": "obsToggleSource", "scene": "…", "source": "…", "visible": true }

Field	Value	What it is
scene*	text
collection	text
source*	text
visible*	true or false
mode	VisibilityMode or null	Show / hide / toggle; `None` falls back to `visible`

OBS: set audio obsSetAudio

{ "type": "obsSetAudio", "scene": "…", "source": "…", "muted": true, "volumeDb": 0 }

Field	Value	What it is
scene*	text
collection	text
source*	text
muted*	true or false
muteMode	MuteMode or null	Mute / unmute / toggle / keep; `None` falls back to `muted`
volumeDb*	number	Volume in `volume_unit` (dB: -100..26, percent: 0..2000 like OBS's advanced audio properties)
volumeFrom	text or null	Variable or placeholder that overrides `volume_db` when it holds a number (faders write `value`)
volumeUnit	VolumeUnit
setVolume	true or false	Whether the volume is applied at all (a pure mute button leaves it alone)

OBS: toggle filter obsToggleFilter

{ "type": "obsToggleFilter", "source": "…", "filter": "…", "enabled": true }

Field	Value	What it is
source*	text
filter*	text
enabled*	true or false

OBS: stream, record, replay obsStream

{ "type": "obsStream", "target": "stream", "mode": "start" }

Field	Value	What it is
target*	ObsTarget
mode*	ObsMode

OBS: save replay obsSaveReplay

{ "type": "obsSaveReplay" }

OBS: studio mode obsStudioMode

Studio mode on/off, or push the preview scene to the program.

{ "type": "obsStudioMode", "mode": "enable" }

Field	Value	What it is
mode*	StudioMode

OBS: trigger hotkey obsTriggerHotkey

Fire an OBS hotkey over the websocket, without giving OBS the focus: by its name (`OBSBasic.StartStreaming`; `context` names the source for per-source ones such as `libobs.mute`) or by the key combination bound in OBS (`key` is an OBS key id such as `OBS_KEY_F5`).

{ "type": "obsTriggerHotkey" }

Field	Value	What it is
by	ObsHotkeyBy
name	text
context	text
key	text
shift	true or false
control	true or false
alt	true or false
command	true or false

Streamlabs

Streamlabs: switch scene slobsSwitchScene

Streamlabs Desktop: the same controls as OBS, by name.

{ "type": "slobsSwitchScene", "scene": "…" }

Field	Value	What it is
scene*	text
collection	text

Streamlabs: show or hide source slobsToggleSource

{ "type": "slobsToggleSource", "scene": "…", "source": "…", "visible": true }

Field	Value	What it is
scene*	text
collection	text
source*	text
visible*	true or false
mode	VisibilityMode or null

Streamlabs: set audio slobsSetAudio

{ "type": "slobsSetAudio", "scene": "…", "source": "…", "muted": true, "volumeDb": 0 }

Field	Value	What it is
scene*	text
collection	text
source*	text
muted*	true or false
muteMode	MuteMode or null
volumeDb*	number	Volume in `volume_unit`: dB mapped onto the mixer fader, or percent as the fader position
volumeFrom	text or null
volumeUnit	VolumeUnit
setVolume	true or false

Streamlabs: toggle filter slobsToggleFilter

{ "type": "slobsToggleFilter", "source": "…", "filter": "…", "enabled": true }

Field	Value	What it is
source*	text
filter*	text
enabled*	true or false

Streamlabs: stream, record, replay slobsStream

{ "type": "slobsStream", "target": "stream", "mode": "start" }

Field	Value	What it is
target*	ObsTarget
mode*	ObsMode

Streamlabs: save replay slobsSaveReplay

{ "type": "slobsSaveReplay" }

Streamlabs: studio mode slobsStudioMode

Studio mode on/off, or push the preview live.

{ "type": "slobsStudioMode", "mode": "enable" }

Field	Value	What it is
mode*	StudioMode

Home Assistant

Home Assistant: on / off homeAssistantTurn

Home Assistant: turn an entity on or off (or toggle it)

{ "type": "homeAssistantTurn", "entity": "…" }

Field	Value	What it is
entity*	text
mode	HaPower

Home Assistant: set a value homeAssistantSetValue

Home Assistant: set a numeric property, fixed or from a variable / fader

{ "type": "homeAssistantSetValue", "entity": "…", "value": 0 }

Field	Value	What it is
entity*	text
kind	HaValueKind
value*	number
valueFrom	text or null	Variable or placeholder that overrides `value` when it holds a number

Home Assistant: call a service homeAssistantCallService

Home Assistant: call any service; `data` is JSON and may contain placeholders

{ "type": "homeAssistantCallService", "domain": "…", "service": "…" }

Field	Value	What it is
domain*	text
service*	text
entity	text
data	text

The types they use

ButtonRef

Reference to a button; `page_id: None` means the page of the calling button.

Field	Value	What it is
pageId	text or null
x*	number
y*	number

ButtonTrigger

Which list of another button to run.

Value	What it means
"press"*	The `down` actions
"release"	The `up` actions
"tap"	`down` then `up`
"hold"	The long-press (`hold`) actions

CompareOp

Value	What it means
"equals"*
"notEquals"
"contains"
"startsWith"
"endsWith"
"greaterThan"
"lessThan"
"isEmpty"
"isNotEmpty"
"matches"	Regular expression match

HaPower

On / off / toggle through the `homeassistant` domain, which works for every entity kind.

Value	What it means
"on"*
"off"
"toggle"

HaValueKind

Numeric things an entity can be set to.

Value	What it means
"brightness"*	Light brightness, 0–100 %
"colorTemperature"	Light colour temperature in Kelvin
"position"	Cover position, 0 (closed) – 100 (open)
"fanSpeed"	Fan speed, 0–100 %
"volume"	Media player volume, 0–100 %
"number"	`number` / `input_number` value, in the entity's own unit
"temperature"	Climate target temperature

HttpAuth

An object whose type says which one it is:

type	With	What it means
"none"*	nothing else
"basic"	usernamepassword
"bearer"	token

HttpBodyMode

Value	What it means
"text"*	`body` text with `content_type`
"file"	The bytes of `body_file`
"multipart"	multipart/form-data: `body` lines as text fields, `files` as file parts

HttpFilePart

Field	Value	What it is
field*	text	Form field name, e.g. "file"
path*	text
filename	text or null	Filename sent to the server; defaults to the file's own name
contentType	text or null	Content type of the part; guessed from the extension when empty

HttpHeader

Field	Value	What it is
name*	text
value*	text

HttpMethod

Value	What it means
"get"
"post"
"put"
"patch"
"delete"
"head"

HttpResponse

What an HTTP action does with the response body.

Value	What it means
"text"*	Keep the text in the variable only
"file"	The body is the file
"base64Field"	A field holds base64 data (a data URL prefix is fine)
"urlField"	A field holds a URL to download

KeyEvent

Value	What it means
"down"
"up"
"tap"

Keystroke

An object whose type says which one it is:

type	With	What it means
"key"	eventkeymodifiers
"delay"	ms
"text"	textdelayMs

LoopCheck

Where an `Until` loop checks: before a round (the body may never run) or after it (the body runs at least once).

Value	What it means
"head"*
"tail"

LoopMode

What makes a loop go round.

Value	What it means
"count"	From a first to a last value, in steps: a counted loop.
"until"*	Until the check holds.
"forever"	Until the macro is stopped (or the time limit hits).

MouseButton

A mouse button as the actions name it.

Value	What it means
"left"*
"right"
"middle"

MouseStep

One step of a mouse sequence. Coordinates and amounts are strings so they take placeholders.

An object whose type says which one it is:

type	With	What it means
"move"	xyrelative	Put the pointer at `x`, `y`, or with `relative` move it by that much
"click"	buttonclicks	Click `clicks` times (1–5) where the pointer is
"press"	button	Hold a button down until a release step
"release"	button
"scroll"	amountaxis	Turn the wheel by `amount` notches: positive down (or right)
"drag"	xybutton	Press a button where the pointer is, move to `x`, `y`, let go
"delay"	ms	Wait `ms` milliseconds (at most 5000)

MuteMode

Value	What it means
"mute"
"unmute"
"toggle"
"keep"	Leave the mute state alone

ObsHotkeyBy

How an OBS hotkey is picked.

Value	What it means
"name"*	By the hotkey's name in OBS
"keys"	By the key combination bound in OBS

ObsMode

Value	What it means
"start"
"stop"
"toggle"

ObsTarget

Value	What it means
"stream"
"record"
"replay"

PadColor

What a pad's LED shows. Palette indices refer to Novation's 128 colours.

An object whose mode says which one it is:

mode	With	What it means
"palette"	index
"flashing"	indexalt
"pulsing"	index
"rgb"	rgb

ScreenPick

Which screen a get-screen action means.

Value	What it means
"primary"*	The main display
"number"	By its number
"foreground"	The one the foreground window is on
"pointer"	The one under the pointer

ScrollAxis

Value	What it means
"vertical"*
"horizontal"

StudioMode

Value	What it means
"enable"
"disable"
"toggle"
"transition"	Make the preview scene live (studio mode must be on)

SystemVolumeMode

Value	What it means
"set"*	Set the level
"adjust"	Change the level by the amount (negative = quieter)
"mute"
"unmute"
"toggleMute"

SystemVolumeTarget

Value	What it means
"output"	Speakers / headphones
"input"	Microphone

TitleMatch

How a title is compared.

Value	What it means
"contains"*
"startsWith"
"exact"
"regex"

VarScope

Where a variable lives: `Local` registers belong to one macro run (and the buttons it calls), `Global` variables are shared by every macro.

Value	What it means
"local"*
"global"

VisibilityMode

Value	What it means
"show"
"hide"
"toggle"

VolumeUnit

How a volume number is meant: decibels, or percent of the app's own scale.

Value	What it means
"db"*
"percent"

WindowOp

Value	What it means
"focus"*
"minimize"
"maximize"
"restore"
"sendToBack"
"close"
"move"	To `x`, `y`, on `screen` when given (a blank coordinate keeps the window's place)
"resize"	To `width` × `height`
"bounds"	Move and resize at once
"center"	On `screen`, or on the window's own screen
"screen"	To `screen`, keeping the window's place on it

WindowTarget

Which window a window action means.

Value	What it means
"foreground"	The window with the focus right now
"title"*	By title (and program)