Events Received

Once a plugin is loaded by the Stream Deck application and the user sets some keys to use the plugin, the plugin will receive some events. A plugin can receive several types of events:

Event	Description
keyDown	When the user presses a key, the plugin will receive the `keyDown` event.
keyUp	When the user releases a key, the plugin will receive the `keyUp` event.
willAppear	When an instance of an action appears, the plugin will receive a `willAppear` event.
willDisappear	When an instance of an action disappears, the plugin will receive a `willDisappear` event.
titleParametersDidChange	When the user changes the title or title parameters, the plugin will receive a `titleParametersDidChange` event.
deviceDidConnect	When a device is plugged to the computer, the plugin will receive a `deviceDidConnect` event.
deviceDidDisconnect	When a device is unplugged from the computer, the plugin will receive a `deviceDidDisconnect` event.
applicationDidLaunch	When a monitored application is launched, the plugin will be notified and will receive the `applicationDidLaunch` event.
applicationDidTerminate	When a monitored application is terminated, the plugin will be notified and will receive the `applicationDidTerminate` event.

keyDown

When the user presses a key, the plugin will receive the keyDown event as a json structure like:

var json = {
    "action": "com.elgato.example.action1",
    "event": "keyDown",
    "context": opaqueValue,
    "device": opaqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "state": 0,
        "userDesiredState": 1,
        "isInMultiAction": false
    }
};

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
event	keyDown
context	An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the `setTitle` API.
device	An opaque value identifying the device. Note that this opaque value will change each time you relaunch the Stream Deck application.
payload	A json object

The payload object contains the following members:

Payload	Description
settings	This json object contains data that you can set and are stored persistently.
coordinates	The coordinates of the action triggered.
state	This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
userDesiredState	This is a parameter that is only set when the action is triggered with a specific value from a Multi Action. For example if the user sets the Game Capture Record action to be disabled in a Multi Action, you would see the value 1. Only the value 0 and 1 are valid.
isInMultiAction	Boolean indicating if the action is inside a Multi Action.

keyUp

When the user releases a key, the plugin will receive the keyUp event as a json structure like:

var json = {
    "action": "com.elgato.example.action1",
    "event": "keyUp",
    "context": opaqueValue,
    "device": opaqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "state": 0,
        "userDesiredState": 1,
        "isInMultiAction": false
    }
};

Members	Description
action	The action unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered.
event	keyUp
context	An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the `setTitle` API.
device	An opaque value identifying the device. Note that this opaque value will change each time you relaunch the Stream Deck application.
payload	A json object

The payload object contains the following members:

Payload	Description
settings	This json object contains data that you can set and is stored persistently.
coordinates	The coordinates of the action triggered.
state	This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
userDesiredState	This is a parameter that is only set when the action is triggered with a specific value from a Multi Action. For example if the user sets the Game Capture Record action to be disabled in a Multi Action, you would see the value 1. Only the value 0 and 1 are valid.
isInMultiAction	Boolean indicating if the action is inside a Multi Action.

willAppear

When an instance of an action appears, the plugin will receive a willAppear event. You will see such an event when:

the Stream Deck application is started
the user switches between profiles
the user sets a key to use your action

The json structure looks like:

var json = {
    "action": "com.elgato.example.action1",
    "event": "willAppear",
    "context": opaqueValue,
    "device": opaqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "state": 0,
        "isInMultiAction": false
    }
};

Members	Description
action	The action unique identifier. If you plugin supports multiple actions, you should use this value to know which action was triggered.
event	willAppear
context	An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the `setTitle` API.
device	An opaque value identifying the device. Note that this opaque value will change each time you relaunch the Stream Deck application.
payload	A json object

The payload object contains the following members:

Payload	Description
settings	This json object contains data that you can set and are stored persistently.
coordinates	The coordinates of the action triggered.
state	This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
isInMultiAction	Boolean indicating if the action is inside a Multi Action.

willDisappear

When an instance of an action disappears, the plugin will receive a willDisappear event. You will see such an event when:

the user switches between profiles
the user deletes an action

The json structure looks like:

var json = {
    "action": "com.elgato.example.action1",
    "event": "willDisappear",
    "context": opaqueValue,
    "device": opaqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "state": 0,
        "isInMultiAction": false
    }
};

Members	Description
action	The action unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered.
event	willAppear
context	An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the `setTitle` API.
device	An opaque value identifying the device. Note that this opaque value will change each time you relaunch the Stream Deck application.
payload	A json object

The payload object contains the following members:

Payload	Description
settings	This json object contains data that you can set and is stored persistently.
coordinates	The coordinates of the action triggered.
state	This is a parameter that is only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
isInMultiAction	Boolean indicating if the action is inside a Multi Action.

titleParametersDidChange

When the user changes the title or title parameters of the instance of an action, the plugin will receive a titleParametersDidChange event. The json structure looks like:

var json = {
  "action": "com.elgato.example.action1", 
  "event": "titleParametersDidChange", 
  "context": "opaqueValue", 
  "device": "opaqueValue", 
  "payload": {
    "coordinates": {
      "column": 3, 
      "row": 1
    }, 
    "settings": {<json data>}, 
    "state": 0, 
    "title": "", 
    "titleParameters": {
      "fontFamily": "", 
      "fontSize": 12, 
      "fontStyle": "", 
      "fontUnderline": false, 
      "showTitle": true, 
      "titleAlignment": "bottom", 
      "titleColor": "#ffffff"
    }
  }
}

Members	Description
action	The action unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered.
event	titleParametersDidChange
context	An opaque value identifying the instance's action. You will need to pass this opaque value to several APIs like the `setTitle` API.
device	An opaque value identifying the device. Note that this opaque value will change each time you relaunch the Stream Deck application.
payload	A json object

The payload object contains the following members:

Payload	Description
settings	This json object contains data that you can set and is stored persistently.
coordinates	The coordinates of the action triggered.
state	This value indicates for which state of the action the title or title parameters have been changed.
title	The new title.
titleParameters	A json object describing the new title parameters.

The titleParameters object contains the following members:

TitleParameters	Description
fontFamily	The font family for the title.
fontSize	The font size for the title.
fontStyle	The font style for the title.
fontUnderline	Boolean indicating an underline under the title.
showTitle	Boolean indicating if the title is visible.
titleAlignment	Vertical alignment of the title. Possible values are "top", "bottom" and "middle".
titleColor	Title color.

deviceDidConnect

When a device is plugged to the computer, the plugin will receive a deviceDidConnect event. The json structure looks like:

var json = {
    "event": "deviceDidConnect",
    "device": opaqueValue,
     "deviceInfo": {
        "type": 0,
         "size": {
            "columns": 5,
            "rows": 3
        }
    },
};

Members	Description
event	deviceDidConnect
device	An opaque value identifying the device. Note that this opaque value will change each time you relaunch the Stream Deck application.
deviceInfo	A json object containing information about the device.

The deviceInfo object contains the following members:

device	Description
type	Type of device. Possible values are `kESDSDKDeviceType_StreamDeck` (0) and `kESDSDKDeviceType_StreamDeckMini` (1).
size	The number of columns and rows of keys that the device owns.

deviceDidDisconnect

When a device is unplugged from the computer, the plugin will receive a deviceDidDisconnect event. The json structure looks like:

var json = {
    "event": "deviceDidDisconnect"
    "device": opaqueValue,
};

Members	Description
event	deviceDidDisconnect
device	An opaque value identifying the device. Note that this opaque value will change each time you relaunch the Stream Deck application.

applicationDidLaunch

A plugin can request in its manifest.json to be notified when some applications are launched or terminated. In order to do so, the manifest.json should contain an ApplicationsToMonitor object specifying the list of application identifiers to monitor. On macOS the application bundle identifier is used while the exe filename is used on Windows. For example the Apple Mail sample plugin uses the following:

"ApplicationsToMonitor": {
    "mac": [
        "com.apple.mail"
    ]
]

When a monitored application is launched, the plugin will be notified and will receive the applicationDidLaunch event. The json structure looks like:

var json = {
    "event": "applicationDidLaunch",
    "payload" : {
        "application": "com.apple.mail"
    }
};

Members	Description
event	applicationDidLaunch
payload	A json object

The payload object contains the following members:

Payload	Description
application	The identifier of the application that has been launched.

applicationDidTerminate

A plugin can request in its manifest.json to be notified when some applications are launched or terminated. In order to do so, the manifest.json should contain an ApplicationsToMonitor object specifying the list of application identifiers to monitor. On macOS the application bundle identifier is used while the exe filename is used on Windows. For example the Apple Mail sample plugin uses the following:

"ApplicationsToMonitor": {
    "mac": [
        "com.apple.mail"
    ]
]

When a monitored application is terminated, the plugin will be notified and will receive the applicationDidTerminate event. The json structure looks like:

var json = {
    "event": "applicationDidTerminate",
    "payload" : {
        "application": "com.apple.mail"
    }
};

Members	Description
event	applicationDidTerminate
payload	A json object

The payload object contains the following members:

Payload	Description
application	The identifier of the application that has been launched.