Registration Procedure

How Plugins Connect to Stream Dock

Plugin Registration

Plugins must follow the registration procedure outlined below. You can reuse the code implemented in various examples. We provide this process in JavaScript, but you can use any programming language that supports WebSocket to implement it. When the Stream Dock application starts, it creates an instance of each plugin.

For JavaScript plugins, use multiple parameters to call connectElgatoStreamDeckSocket(). To ensure compatibility with Elgato, we use the same function names as theirs so that your plugin can be compatible with Elgato software.
For plugins packaged as .exe files, use multiple parameters to launch the .exe executable file.

These parameters include port and unique identifiers used to communicate with the Stream Dock application.

JavaScript Plugin Registration

For JavaScript plugins, you need to declare the following JavaScript functions:

// To ensure compatibility with Elgato,
// we use the same function names as theirs, 
// so your developed plugin can be compatible with Elgato software.
function connectElgatoStreamDeckSocket(
    inPort, 
    inPluginUUID, 
    inRegisterEvent, 
    inInfo
)

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

Create a WebSocket using the provided port parameter:

const server = new WebSocket('ws://127.0.0.1:' + inPort);

When the WebSocket opens, the plugin needs to register JSON data:

server.onopen = () => server.send(
    JSON.stringify({ event: inRegisterEvent, uuid: inPluginUUID });
);

After completing the above two steps, the plugin should receive events through the following function:

server.onmessage = (e) => (
    console.log(e.data);
);

Plugin Registration for Compiled Executables

For plugins packaged as .exe, you will start the .exe executable with the following parameters:

Parameter	Description
-port	The string `"-port"`
port	The port used for connecting to the WebSocket
-pluginUUID	The string `"-pluginUUID"`
pluginUUID	A unique identifier string used to register the plugin after opening the WebSocket
-registerEvent	The string `"-registerEvent"`
event	The event type applied to register the plugin after opening the WebSocket
-info	The string `"-info"`
info	A JSON string containing Stream Dock and device information

PropertyInspector Registration

For the Property Inspector, you need to declare the following JavaScript functions:

// To ensure compatibility with Elgato,
// we use the same function names as theirs, 
// so your developed plugin can be compatible with Elgato software.
function connectElgatoStreamDeckSocket(
    inPort,
    inPropertyInspectorUUID, 
    inRegisterEvent, 
    inInfo, 
    inActionInfo
)

Parameter	Description
inPort	The port used for connecting to the WebSocket
inPropertyInspectorUUID	The unique identifier string used to register the Property Inspector after opening the WebSocket
inRegisterEvent	The event type applied to register the Property Inspector after opening the WebSocket
inInfo	A JSON object containing information about the application
inActionInfo	A JSON object containing information about the action

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

Create a WebSocket using the provided port parameter:

const server = new WebSocket('ws://127.0.0.1:' + inPort);

When the WebSocket opens, the Property Inspector needs to register JSON data

server.onopen = () => server.send(
    JSON.stringify({ event: inRegisterEvent, uuid: inPropertyInspectorUUID });
);

After performing the above two steps, the Property Inspector should receive events via the following function:

server.onmessage = (e) => (
    console.log(e.data);
);

info

The JSON objects used in the registration process are as follows:

{
    "application":{
        "font":"HarmonyOS Sans",
        "language":"zh_CN",
        "platform":"windows",
        "platformVersion":"10.0.19045",
        "version":"4.9"
    },
    "colors":{
        "buttonMouseOverBackgroundColor":"#464646FF",
        "buttonPressedBackgroundColor":"#303030FF",
        "buttonPressedBorderColor":"#646464FF",
        "buttonPressedTextColor":"#969696FF",
        "highlightColor":"#0078FFFF"
    },
    "devicePixelRatio":1,
    "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
        }
    ],
    "plugin":{
        "uuid":"com.mirabox.demo",
        "version":"1.8"
    }
}

Parameter	Description
application	A JSON object containing information about the application
colors	A JSON object containing color information
devices	A JSON array containing information about devices
plugin	A JSON object containing information about the plugin
devicePixelRatio	The pixel ratio indicating whether the Stream Dock application is running on a HiDPI screen

Application Object

The application object contains the following members:

application	Description
language	The language of the application
platform	The platform on which the application is running
platformVersion	The version of the platform
version	The version of the application

Plugin Object

The plugin object contains the following members:

plugin	Description
uuid	The unique identifier of the plugin
version	The version of the plugin

Devices Array

The devices array contains the following members:

devices	Description
id	The unique identifier of the device
name	The name of the device
size	The size of the device
type	The type of the device

inActionInfo

The inActionInfo parameter is a JSON string that contains the following information:

{
  "action": "com.mirabox.demo.action1", 
  "context": uniqueValue, 
  "device": uniqueValue, 
  "payload": {
    "settings": {<JSON data>},
    "controller": "Keypad" | "Encoder"
    "coordinates": {
      "column": 2, 
      "row": 1
    }
  }
}

Parameter	Description
action	The unique identifier of the action defined in the plugin
context	A value used to identify the instance of the action
device	A value used to identify the device
payload	A JSON object

Payload Object

The payload object contains the following members:

payload	Description
settings	A JSON object containing persistently stored data
controller	An array of controllers. Valid values include `Keypad`, `Information`, `SecondaryScreen`, `Knob`. `Keypad` is for regular keys, `Information` is for display only without touch or key events, `SecondaryScreen` is for small screen display, and `Knob` is for the rotary knob. Default is ["`Keypad`"].
coordinates	The coordinates of the triggered action