Monogram API

OS Inputs (Optional)

The Monogram API is designed to provide the best experience when controlling target applications over WebSockets. However, sometimes using WebSockets is not possible. Or, maybe your application already has hooks for certain keyboard shortcuts or MIDI and you would like to leverage those first.
In this guide, we will talk about how to create a Monogram Config Bundle that only uses OS-level inputs such as keyboard shortcuts and MIDI.
Keyboard Shortcut App Example
In the picture above, all of those actions were implemented using Keyboard Shortcuts only. OS-Level Inputs give you the ability to experiment with Monogram in a friendly and low-effort way.

Creating with OS-level inputs

OS-level inputs can only be defined by presets.json, and are only inherited by Module Type rather than Input Type. This means that you need to define a preset for every module type that uses the keyboard shortcut.


In the myphotoeditor example, we defined an input named "Auto Tone" in inputs.json. This input would be available to be assigned to a dial as "Press" as well as a button as "Press", because Monogram automatically generates presets for modules with a compatible input modality.
Suppose now we must to use keyboard shortcut to accomplish the "Auto Tone" by pressing "Control+T". The "Control+T" keyboard shortcut must be defined under both button and dial keys in presets.json.
The presets.json would look something like this:
"button": [
"name": "auto-tone-button", // Define a unique name will help us highlight the correct preset when the user opens the module settings
"label": "Auto Tone",
"info": "Makes your photo beautiful",
"press": {
"key": "t",
"localCharacter": "t", // See Section "Limitations" about alternate keyboard layouts
"modifiers": [
"meta", // See section below on "Cross-Platform Control/Command keys" to learn more about the 'meta' key
"virtual": false
"dial": [
"name": "auto-tone-dial",
"label": "Auto Tone",
"info": "Makes your photo beautiful",
"press": {
"key": "t",
"localCharacter": "t",
"modifiers": [
"virtual": false
If you do not envision the user activating "Auto Tone" as a Dial Press, you can omit its definition for dial. Users will have to manually customize the Dial Press to "Control+T" in Creator to gain this functionality.

Defining a keyboard shortcut

The easiest way to create a valid configuration is to use Monogram Creator to capture the desired keyboard shortcut, then view the generated preset JSON object in Manual Entry view.
You can do this for MIDI, Mouse Scroll, and Joystick HID as well
To enable Manual Entry view, go to Preferences -> Advanced -> Enable debugging of module settings via Manual Entry view
Manual Entry View
  • meta: Monogram provides a modifier key called meta that is translated into command on macOS and control on Windows.
    • meta is never auto-generated in Manual Entry
    • In the example screenshot above, you would need to manually change the command in modifiers to meta so that it outputs "Command+T" on macOS and "Control+T" on Windows.
  • virtual: The virtual attribute defines whether the keyboard shortcut is executed by software or hardware. It may be necessary to enable virtual for certain keyboard layouts. See section "Limitations" below for more.
For more discussions on what goes in the JSON object for a Keyboard Shortcut, see section on KeystrokeConfigType in presets.json API Reference.

Example Config Bundle

We have put together an example Config Bundle that implements a simple keyboard shortcuts based solution for Microsoft Teams, a popular video conferencing app.
Key Highlights:
  • In config.json:
    • The program's bundle name and executable name is defined to enable auto profile switching on both macOS and Windows. Learn more about ConfigType.
    • The autoLoad property specifies a quick start profile called "MSTeams_Default.monogram". This further reduces friction for the users, as it will load the "MSTeams_Default.monogram" profile by default when the user first clicks on the app from "New Profile" tab.
  • In inputs.json: Nothing is defined -- it is just an empty array
    • There are no WebSockets or UDP based inputs available for us to use in Microsoft Teams.
  • In presets.json:
    • Some of the items were marked as Mac-exclusive or Windows-exclusive (e.g. temp-mute-mac and temp-mute-win). By using the exclusive property, you can handle OS-specific keyboard shortcuts with ease.
    • The meta modifier is used

MIDI and Joystick HID Actions

By default, MIDI and Joystick HID customization options are NOT shown in the UI for an app loaded by Config Bundle. This is done to reduce end-user confusion.
To enable those customization options in the UI for your application, add "midi" and/or "joystick" in the [additionalActions] property in ConfigType. Learn more.


Keyboard Layout

In customers with non-QWERTY keyboard layouts, the behaviour of keyboard shortcuts can be confusing. The properties key and localCharacter are used to mitigate issues with simulating keyboard shortcuts in alternative keyboard layouts.
  • If virtual is true, the software will trigger the character that was initially entered (it should be consistent even if the user changes their keyboard layout afterward).
    • The localCharacter property is used to emulate the character press
  • If virtual is false, the hardware will "press" the same key that was pressed during the assignment. It is expected to potentially enter different characters when the user changes their keyboard layout.
    • The key property stores the ASCII character corresponding to the scancode.
    • The hardware will send the scancode of key property as translated by USB-HID Standard (i.e. U.S. QWERTY Keyboard)
Example: Pressing the "A" key on an AZERTY keyboard will result in key being "q" and localCharacter being "a".
  • If virtual is true, the character "a" is emulated by software.
  • If virtual is false, the key with a scancode of 0x14 ("KEY_Q") is emulated by hardware.
There are additional cases where virtual cannot be customised. See section on KeystrokeConfigType in presets.json API Reference for more details.