Skip to content

Registration Procedure

Plugin Registration

The Stream Deck application loads each plugin at launch or when the plugin is installed. The plugin must follow the registration procedure as described in this page. The procedure is fairly simple and you can re-use the code already implemented in the various Samples. We provide an implementation of this procedure in Javascript, C++ and Objective-C.

When the Stream Deck application is launched, it spawns one instance of each plugin. The plugin process is started and

  • for Javascript plugins, its connectElgatoStreamDeckSocket() is called with several parameters.
  • for compiled plugins written for example in C++ or Objective-C, its main() function is called with several parameters.

These parameters contain among others the port to use for the communication and the plugin unique identifier. The plugin should open the websocket communication and registers itself with the Stream Deck application. After this procedure, the plugin and the Stream Deck application are communicating though the websocket.


Javascript plugin Registration

For a Javascript plugin, you need to declare the following Javascript function:

function connectElgatoStreamDeckSocket(inPort, inPluginUUID, inRegisterEvent, inInfo)

This function is called when the plugin is loaded and should:

  • create the WebSocket with the port passed in parameter:
websocket = new WebSocket("ws://localhost:" + inPort);
  • When the WebSocket is open, the plugin needs to be registered with a special json data:
websocket.onopen = function()
{
    // WebSocket is connected, register the plugin
    var json = {
        "event": inRegisterEvent,
        "uuid": inPluginUUID
    };

    websocket.send(JSON.stringify(json));
};
  • After performing these 2 steps, the plugin should receive the events though the function:
websocket.onmessage = function (evt)

The inInfo parameter is described in the section Info parameter.


Compiled plugin Registration

If your plugin is a compiled plugin (C++, Objective-C, ...), the command line tool will be executed with the following parameters:

Parameters Description
-port The string "-port"
port The port that should be used to create the WebSocket
-pluginUUID The string "-pluginUUID"
UUID A unique identifier string that should be used to register the plugin once the WebSocket is opened
-registerEvent The string "-registerEvent"
event The event type that should be used to register the plugin once the WebSocket is opened
-info The string "-info"
info A stringified json containing the Stream Deck application information and devices information.

The info json is described in the section Info parameter.


Property Inspector Registration

For the Property Inspector, you need to declare the following Javascript function:

function connectElgatoStreamDeckSocket(inPort, inPropertyInspectorUUID, inRegisterEvent, inInfo, inActionInfo)
Members Description
inPort The port that should be used to create the WebSocket
inPropertyInspectorUUID A unique identifier string to register Property Inspector with Stream Deck software
inRegisterEvent The event type that should be used to register the plugin once the WebSocket is opened. For Property Inspector this is
"registerPropertyInspector"
inInfo A json object containing information about the application. (see below Info parameter)
inActionInfo A json object containing information about the action. (see below inActionInfo parameter.

This function is called when the Property Inspector is displayed and should:

  • create the WebSocket with the port passed in parameter:
websocket = new WebSocket("ws://localhost:" + inPort);
  • When the WebSocket is open, the Property Inspector needs to be registered with a special json data:
websocket.onopen = function()
{
    // WebSocket is connected, register the Property Inspector
    var json = {
        "event": inRegisterEvent,
        "uuid": inPropertyInspectorUUID
    };

    websocket.send(JSON.stringify(json));
};
  • After performing these 2 steps, the Property Inspector should receive the events though the function:
websocket.onmessage = function (evt)

The inInfo parameter is described in the section Info parameter.


Info parameter

The info parameter used in the registration process is a json object like:

{
  "application": {
    "language": "en", 
    "platform": "mac", 
    "version": "4.1.0"
  }, 
  "plugin": {
    "version": "1.1"
  },
  "devicePixelRatio": 2, 
  "devices": [
    {
      "id": "55F16B35884A859CCE4FFA1FC8D3DE5B", 
      "name": "Device Name", 
      "size": {
        "columns": 5, 
        "rows": 3
      }, 
      "type": 0
    },
    {
      "id": "B8F04425B95855CF417199BCB97CD2BB", 
      "name": "Another Device", 
      "size": {
        "columns": 3, 
        "rows": 2
      }, 
      "type": 1
    }
  ]
}
Members Description
application A json object containing information about the application.
plugin A json object containing information about the plugin.
devices A json array containing information about the devices.
devicePixelRatio Pixel ratio value to indicate if the Stream Deck application is running on a HiDPI screen.

The application object contains the following members:

application Description
language In which language the Stream Deck application is running. Possible values are en, fr, de, es, ja, zh_CN.
platform On which platform the Stream Deck application is running. Possible values are kESDSDKApplicationInfoPlatformMac ("mac") and kESDSDKApplicationInfoPlatformWindows ("windows").
version The Stream Deck application version.

The plugin object contains the following members:

plugin Description
version The plugin version as written in the manifest.json.

The devices array contains the following members:

devices Description
id An opaque value identifying the device.
type Type of device. Possible values are kESDSDKDeviceType_StreamDeck (0), kESDSDKDeviceType_StreamDeckMini (1), kESDSDKDeviceType_StreamDeckXL (2) and kESDSDKDeviceType_StreamDeckMobile (3). This parameter parameter won't be present if you never plugged a device to the computer.
size The number of columns and rows of keys that the device owns.
name The name of the device set by the user.

inActionInfo parameter

The inActionInfo parameter is a stringified JSON-object (aka JSON-string). It contains the following information:

{
  "action": "com.elgato.analogclock.action", 
  "context": opaqueValue, 
  "device": opaqueValue, 
  "payload": {
    "settings": {<json data>},
    "coordinates": {
      "column": 2, 
      "row": 1
    }
  }
}

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.
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.
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.