Monogram API


Table of Contents


The format of the config.json file for an app.
A typical config.json file looks like this:
"name": "Lightroom",
"id": "com.adobe.lightroom",
"bundle": ["com.adobe.lightroom7", "com.adobe.lightroomclassic"],
"exe": ["lightroom.exe"],
"connection": [
"name": "sender",
"type": "websocket"
Here's what each property means (square brackets [] mean the property is optional).


Plain-text name for this app (e.g., "Photoshop")


Globally unique identifier for this app. Must have <tld>.<companyname>.<product> format (e.g, "com.adobe.photoshop")


Path to icon for this app. Can be a relative path (must be in the same folder as config.json) or base64-encoded PNG data.
If not specified, the default value is "icon.png"


List of socket configuration options for this config.
The first connection in this list is considered the "default" connection. This means its name does not have to be specified when defining inputs. See ConnectionConfigType


List of one or more possible unique Windows executable names for this app (e.g., ["lightroom5.exe", "lightroom6.exe"]). If "Automatically switch profiles based on active app" is enabled, Monogram Service will automatically switch to profiles that declare compatibility with the Windows exe name when the app is in focus.


List of one or more possible unique macOS bundle identifiers for this app (e.g., ["com.adobe.lightroom5", "com.adobe.lightroom6"]). Not necessarily the same as id. If "Automatically switch profiles based on active app" is enabled, Monogram Service will automatically switch to profiles that declare compatibility with the bundle name when the app is in focus.


Enable additional modes for customizing a physical input. Possible values are "midi" and "joystick".
If not specified, the UI will hide customization options for setting a physical input as a MIDI Mode or Joystick Mode. (OS and Keyboard modes are always shown)
This is a cosmetic setting only. It does not prevent MIDI or Joystick actions from being assigned or executed.
To limit end-user to specified joystick or MIDI configurations, define those actions using presets.json and leave [additionalActions] empty.


Optional. Enforce OS platform compatibility for this config bundle. The config bundle will only be loaded if the OS matches with platform.
Value can be '' (meaning load on all OSes), 'darwin', or 'win32'. Default value is ''.


Experimental - Behaviour may change without notice
Defines the modes available for this application for mode switching.


Where a user can go to get help if they encounter an issue with the integration.



Configuration options to facilitate socket communication with the target app
Available options


A string that identifies a connection for an application. For applications requiring multiple connections, each connection shall have a unique name.


What method to use for app communication. See ConnectionType


How to format the messages before sending them through the communication channel. The default is 'json'. See ProtocolType


Specify a port number (for tcp and websocket protocols only)


When set to true, Monogram Service will queue and aggregate all messages sent to the Client until (a) it receives a message from the Client or (b) a timeout condition is reached.
To begin receiving messages from Monogram Service, the Client shall first send any message (irrespective of payload) to Monogram. For example, socket.send({status: ok}). This signals to Monogram Service that the Client is ready to receive.
A timeout condition is reached when Monogram Service has not received any messages from the Client for a period of 300ms. When the timeout condition is reached, Monogram Service will (a) clear the queue and aggregation and (b) permit the next message to be sent. In other words, should the Client be unresponsive, the maximum frequency of messages Monogram Service will send is one message every 300ms.
Useful when significant amounts of synchronous processing must occur each time the Client receives a message.



Possible ways of connecting to an application. Options are websocket or udp
Type: $ElementType<ConnectionConfigType, "type">


The socket communication protocol to use with Socket connections. Options are "json" or "simple"
Type: ("json" | "simple" | string)


One of the categories that an app belongs to.
Type: ("photo" | "video" | "audio" | "design" | "3d")