Monogram API
Search…
⌃K

presets.json

Table of Contents

PresetsType

The presets.json file has this format
This file is used for special cases like modules that can modify multiple inputs or send keyboard shortcuts.
Monogram implicitly defines several presets based on the given inputs.json. This means presets for simple slider and button actions do not need to be specified.
To override a Monogram-generated preset, specify a module preset with the same name property as the name of the input to override.
A typical presets.json looks like this
{
"button": [
{
"name": "Next Frame", // Define a unique name for this preset
// Since there is no `label` property, the `name` property will be used
// for user-facing displays. Therefore we use a more human-friendly name here.
"press": {
"input": "jog", // Matches with the name defined in `inputs.json`
"action": "increment" // Specific payload for that action
}
},
{
"name": "Previous Frame",
"press": ["jog", "decrement"] // Alternative short-form expression
},
{
"name": "copy-text" // Define a unique programmatic name for this preset
"label": "Copy", // The `label` property is a human-friendly name used for user-facing display purposes
// By using a separate `name` and `label` property, you can have the freedom
// to rename this preset in the future and the program will still understand that
// existing modules assigned to "copy-text" preset is in fact the same one
// Separating `name` from `label` is also required for multi-lingual support (Not yet Implemented)
"press": {
"key": "c",
"modifiers": ["meta"]
}
},
{
"name": "Paste",
"press": {
"key": "v",
"modifiers": ["meta"]
}
}
],
"dial": [
[
"temperature", // Takes the Monogram-generated preset named "temperature"
{
"info": "Turn to change temperature. Press to reset white balance"
"press": {
"macro": [
["temperature", "reset"],
["tint", "reset"]
]
}
} // And override the Monogram-generated preset with the above information
],
[
"tint",
{
"info": "Turn to change tint. Press to reset white balance"
"press": {
"macro": [
["temperature", "reset"],
["tint", "reset"]
]
}
}
],
{
"name": "Exposure/Contast",
"info": "Turn to change Exposure. Press and turn to change Contrast. Press to reset both",
"turn": "exposure",
"pressAndTurn": "contrast",
"press": {
"macro": [
["exposure", "reset"],
["contrast", "reset"]
]
}
},
{
"name": "Transport",
"info": "Turn to Shuttle. Press and turn to Jog. Press to Play/Pause",
"leftTurn": ["shuttle", "decrement"],
"rightTurn": ["shuttle", "increment"],
"press": "togglePlayback",
"pressAndLeftTurn": ["jog", "decrement"],
"pressAndRightTurn": ["jog", "increment"],
}
]
}
See ActionConfigType for more details about the expected format of module actions like press, turn and slide.

PresetType

Format for each presets specified in presets.json.

Create a new preset

The { name: string, exclusive?: 'mac' | 'win' } & SettingsType form specifies a completely new preset.

name

Mandatory. A unique identifier string for this preset. Must be unique within each app. Used to identify this preset when assigning them to physical inputs (i.e. Monogram modules).

[exclusive]

Optional. Limits the visibility of this preset by user's operating system. Can be either win or mac. Monogram Creator will only show this preset in the UI if it matches with the operating system listed. It does not prevent this preset from being assigned.

SettingsType

See section on SettingsType for details on label and info properties.

Extend from a built-in preset

The [ string, SettingsType ] form takes a built-in preset and modifies it with some extra overrides. Leave out the name string entry in the overrides to override an existing built-in preset with your desired Settings. Otherwise, a new preset is created.

User-friendly labels and help text

To help user understand the preset's functionality, the label property can be provided to help categorize and rationalize the name shown in the UI.
As well, the info string property can be used to provide a longer explaination on what this module preset does and how it could be used by the user.
See SettingsType for details on label and info properties.
Type: (any | [string, SettingsType])

SettingsType

Generic module settings object. Can be treated as a preset when it contains a name string property. See the [Module]SettingsType types below for how to declare settings for different module types.

Common SettingsType items

[label]

A user-friendly string for this input. Used as the display text in the UI. To improve organization, the period . character may be used to group items into categories.
For example, given Layer.New Layer, Layer.Delete Layer, and Zoom.Out, the UI will present the items as follows:
+ Layer
|-- New Layer
|-- Delete Layer
+ Zoom
|-- Zoom Out

[info]

Optional. More detailed information on what the preset is for, displayed in the UI during preset selection. Can be multi-line.

[temporary]

Experimental - Behaviour may change without notice
An optional boolean flag used to indicate that this Preset is temporary. Used for dynamically updated presets. The input will not be shown in the UI if this is true.

ButtonSettingsType

Format for Button module presets.

Properties

DialSettingsType

Format for Dial module presets.

turn properties

Action specifiers for what to do when the dial turns.
When assigning
  • turn
  • pressAndTurn
Then do not assign any of
  • leftTurn
  • rightTurn
  • pressAndLeftTurn
  • pressAndRightTurn

pose property

Used in limited applications where the dial behaves more like a slider (i.e., absolute pose). This is primarily used for MIDI CC (non-relative) and Joystick axis.
When specifying pose, do not specify any of the turn actions.

Note about USB-enabled actions

The above recommendations apply to software-based actions such as those specified in the app inputs; however, hardware-based actions such as keyboard shortcuts and MIDI assigned to press, turn, leftTurn, rightTurn and pose may interfere with the pressAndTurn assignments.
The hardware cannot differentiate "turn" from "press and turn", so if a hardware "turn" and a software "press and turn" action are specified, both shall be executed.
As a workaround, some assignments may be declared as "virtual", including keyboard shortcuts, mouse click, mouse cursor and mouse scroll. This has its own drawbacks. See KeystrokeConfigType for details.

sensitivity

sensitivity is an integer that ranges from 0 to 9, inclusive. Its default value is 9. Sensitivity is inversely proportional to the distance between dial "ticks". That is, the lower the number, the more the dial must turn to execute a single action.

Properties

SliderSettingsType

Format for Slider module presets.

Properties

OrbiterSettingsType

Format for Orbiter module presets.
  • turn properties

Action specifiers for what to do when the dial turns.
When assigning
  • turn
Then do not assign any of
  • leftTurn
  • rightTurn

tilt properties

Action specifiers for what to do when the disc is displaced in the x-axis or y-axis.

pose properties

Used in limited applications where the dial or Orbiter disc behaves more like a slider (i.e., absolute pose). This is primarily used for MIDI CC (non-relative) and Joystick axis.
When specifying pose, do not specify any of the turn actions.

turnSensitivity

turnSensitivity is an integer that ranges from 0 to 9, inclusive. Its default value is 9. The sensitivity is inversely proportional to the distance between dial "ticks". That is, the lower the number, the more the dial must turn to execute a single action.

tiltSensitivity

tiltSensitivity is an integer that ranges from 1 to 5, inclusive. Its default value is 3. The sensitivity is inversely proportional to the disc's displacement. That is, the lower the number, the more the disc must displace to execute a single action.
TIP: You can change this using the “Tilt Sensitivity” on the UI. If you make a mistake and "tiltSensitivity" is outside of the 1 to 5 range, then it will default to 3.

tiltMode

tiltMode is an integer that ranges from 0 to 2, inclusive. Its default value is 2. It represents the blending mode between the X and Y axis.
When tiltMode is 0, X and Y axes are totally isolated. The axis with the largest magnitude is used for the output. Use this when only one axis should be changing at a time.
When tiltMode is 1, X and Y axes are partially blended. Orbiter will snap the output to the nearest axis. Obvious off-axis movements are not affected. Use this to allow isolated and independent changing of two variables, yet still make simultaneous expressive control possible.
When tiltMode is 2, the X and Y axes are output as-is, without additional processing. Use this when you want equal weighting for both axes. This is the default.

Properties

ActionConfigType

Every module setting that emits an action has this general format.
When the config is
{
input: string,
action?: string,
app?: string
}
Monogram expects the input to refer to an input name in inputs.json. Monogram makes a best guess at what to do with this input based on what module setting is assigned. For example, assigning a dial's turn setting to "volume" makes the dial increment or decrement the volume input.
action is the type of action to perform on that input. This is only applicable to PulseActionType, where the action could be one of
  • "reset",
  • "increment", or
  • "decrement"
for inputs that have step and/or reset values.
action is ignored in other contexts.
app is the ID of the application for which to perform this action (see ConnectionConfigType). If not specified, it pulls the id value from the adjacent config.json.
When the config is
string
This is short for
{
input: string
}
with the app ID in the adjacent directory
When the config is
[
string, // (1)
string // (2)
]
This is short for
{
input: string, // (1)
action: string // (2)
}
with the app ID in the adjacent directory
Type: (string | [string, string] | {input: string, action: string?, app: string?} | MacroConfigType<ActionConfigType>)

MacroConfigType

The configuration type of an action that can execute multiple actions with one module actuation.
Example Macro in Lightroom using Pulse actions: Flag the photo, perform auto adjustments, increase rating and go to the next photo.
Given this inputs.json:
{
"flagPick",
"autoTone",
{
"name": "rating",
"step": 1,
"range": [0, 5]
"reset": 0
},
{
"name": "currentPhoto",
"step": 1
}
}
Define this button preset:
{
"button": [
{
"name": "Autochoose",
"press": {
"macro": [
"flagPick",
"autoTone",
["rating", "increment"],
{
"input": "currentPhoto",
"action": "increment",
"app": "com.adobe.lightroom"
}
]
}
}
]
}
The A type paramter must be one a ActionConfigType instance. This may include PulseConfigType, NudgeConfigType, or SetConfigType
The interval property specifies a time to wait (in milliseconds) between consecutive actions (defaults to 0).

Properties

UsbEnabledPulseConfigType

Complete pulse action config for module settings that support USB. See PulseConfigType and UsbPulseConfigType

PulseConfigType

Configuration for actions that don't require any parameters such as Play, Pause, Reset Value, etc.
Some valid examples
"play"
["exposure", "reset"]
{
"input": "contrast",
"action": "increment",
"app": "com.adobe.lightroom"
}
See InputType
Type: ((string | [string, PulseActionType] | {input: string, app: string?} | {input: string, app: string?, action: "reset", to: number?} | {input: string, app: string?, action: ("increment" | "decrement"), step: number?} | MacroConfigType<PulseConfigType>) | KeystrokeConfigType | {mac: KeystrokeConfigType, win: KeystrokeConfigType} | ClickConfigType)

PulseActionType

Possible pulse action types
Type: ("reset" | "increment" | "decrement")

KeystrokeConfigType

Configuration options for keystroke pulse actions.
The meta modifier is used for shortcuts that should use control on Windows and command on Mac.
Example:
{
"key": "delete",
"modifiers": ["control", "alt"]
}
When Monogram receives configuration for a supported module, it configures the Core to emit one of the following for the target actuation:
  1. 1.
    Hardware Keyboard Mode: Send classic HID hardware scan codes, identical to how a regular keyboard works
  2. 2.
    Software Keyboard Mode: Simulate a virtual key press with OS-automation APIs
Case 1 applies when the following is true
  • The selected module supports hardware settings. For example, the dial's press setting support hardware keystrokes, but pressAndLeftTurn and pressAndRightTurn do not.
  • The config is not part of a macro
  • The virtual property is not set to true
Case 2 applies in all other cases.
The key must always correspond to the position of the key position on a US Keyboard layout. For example, if the OS uses an AZERTY keyboard layout and the A key is required, use this config.
{ "key": "q" }
However, there are subtle technical differences between how Hardware v.s. Software keyboard modes:
In software mode, the above would type q. In other cases, such as for a Russian keyboard layout where the key at the q position is й, nothing happens in software mode.
With "virtual": true, Specify the input property as the desired key to be printed. If this property is set and does not match key, Monogram attempts to type input instead of key.

Properties

HardwareModifierType

Modifiers understood by hardware (physical and virtual). Each element of ModifierType is translated to one of these.
Note that command is the Windows key on Windows systems.
Type: ("control" | "shift" | "right_shift" | "alt" | "command")

MODIFIERS

Translation from a user-specified modifiers (e.g., 'windows', 'meta') to modifiers required by hardware and keyboard automation (e.g., 'command', 'control').

ModifierType

Any modifier allowed in the KeystrokeConfigType's modifiers array. Includes "control", "ctrl", "shift", "right_shift", "alt", "option", "windows", "win", "command", "meta".
Type: $Keys<any>

KEYCODES

Internal translation from virtual key to scancode. Not all keycodes are available on all platforms.

KeyType

String representing a keyboard key such as "a", "left" or "numpad_1".
Type: $Keys<any>

ROBOTJSCOMPATIBLE

all the robotjs compatible consumer code functions we support
Type: Array<string>

ClickConfigType

Configuration options for mouse click pulse actions.
Specify these to simulate mouse-clicks with the press of a Monogram button
Example left-click
{ "click": "left" }
Specify "virtual": true to enforce software click simulation (see KeystrokeConfigType for details).

Properties

  • click ("left" | "middle" | "right")
  • virtual boolean?

MouseButtonType

Possible mouse button values
Type: $ElementType<ClickConfigType, "click">

UsbEnabledNudgeConfigType

Complete nudge action config for module settings support USB. See NudgeConfigType and UsbNudgeConfigType

NudgeConfigType

Actions used to increment or decrement the values of inputs. Take a single parameter, which is the amount to increase by.
Some valid examples
{ "input": "volume" }
"volume"
{ "input": "position", "action": "z", "step": "0.02" }
The input string must be from named entry in inputs.json.
Specify an action property with values "x", "y" or "z" for adjusting single dimensions on a TwoAxisInputObjectType or ThreeAxisInputObjectType

ScrollConfigType

Used to simulate the scroll wheel with dial turns. Scrolling could go in either the horizontal or vertical direction. For virtual configs, specify a "step" number for how many points to scroll by.
Non-virtual, hardware-based scrolling works the same way as a mouse's scroll wheel (usually line-by-line) and is only available on the latest Core and firmware.
Specify "invert": true" to reverse scroll direction. Example:
{ "scroll": "horizontal", "invert": true }
For scrolling with a modifier (e.g. control+scroll for Zoom), modifiers may be used. virtual must be true for scrolling with a modifier. modifiersTimeoutMs specifies how long the modifier is kept held down after the scrolling is complete. If modifiersTimeoutMs is not supplied, a default value of 100ms is applied.
Example - Scrolling with shift held down:
{"scroll": "vertical", "step": 10, "modifiers": ["shift"], "modifiersTimeoutMs": 200, "virtual": false }
Virtual mouse scroll allow point-level scrolling. It works with any Core and is only available for macOS
Example - scroll down 10 points at a time on macOS:
{ "scroll: "vertical", "step": 10, "virtual": true }

Properties

CursorConfigType

Simulate mouse cursor movement. Specify "invert": true to reverse movement direction. Non-virtual, hardware-based mouse is only available on the latest Core and firmware. Example:
{ "cursor": "x", "invert": true }
Virtual mouse movement works with any Core and is only available on macOS. Example - move the mouse cursor down 5 points at a time.
{ "cursor": "y", "step" 5, "virtual": true }

Properties

UsbEnabledSetConfigType

Complete nudge action config for module settings support USB. See SetConfigType and UsbSetConfigType

SetConfigType

Actions used to set the value of inputs. These are for actions that take a single parameter which is the value to set.
Optionally include a range property to constrain the input's actual range
Some valid examples
{ "input": "volume", "range": [25, 75] }
["position", "y"]
"volume"
The input string must be from named entry in inputs.json.
Specify an action property with values "x", "y" or "z" for adjusting single dimensions on a TwoAxisInputObjectType or ThreeAxisInputObjectType
Type: (string | [string, AxisType] | {input: string, action: AxisType?, range: [number, number]?, app: string?} | MacroConfigType<SetConfigType>)

AxisType

Possible axes for 2D and 3D input configs on single-dimensional dials and sliders.
Type: ("x" | "y" | "z")

UsbPulseConfigType

Possible USB configuration schemes that may be assigned to button press and dial left/right turn.

UsbNudgeConfigType

Possible USB configuration schemes that may be assigned to dial turn.

UsbSetConfigType

Possible USB configuration schemes that may be assigend to dial/slider position.

MidiPulseConfigType

MIDI pulse configuration, applicable to button, dial press and other noted settings. For all cases, the default channel is 1 and the maximum channel is 16. channel must be an integer.
Valid examples:
{ "midi": "note", "note": 1 }
{ "midi": "cc", "cc": 4, "toggle": true, "onValue": 127, "offValue": 0, "channel": 2 }
{ "midi": "pc", "pc": 8, "channel": 4 }
pc and cc for buttons are only available with the latest Core and firmware.

MidiSetConfigType

MIDI set configuration, available to dial position, slider and other noted module settings. For all cases, the default channel is 1 and the maximum channel is 16. channel must be an integer.
Valid examples:
{ "midi": "cc", "cc": 4, "channel": 3 }
{ "midi": "pressure" }
Channel pressure is only available for the latest Core and firmware

MidiNudgeConfigType

MIDI nudge configuration, for dial turn and other noted module settings. Used for relative CC (Condor only). The default channel is 1 and the maximum channel is 16. channel must be an integer.

MidiNoteConfigType