Architecture

How Stream Deck communicates with plugins.

The Stream Deck software loads all the custom plugins when the application starts. Websocket APIs allow bidirectional communication between the plugins and the Stream Deck application using JSON.

Stream Deck Architecture

Plugin Registration

Each plugin communicates with the Stream Deck application using a dedicated WebSocket on a port specified by the Stream Deck application. The plugin must follow the Registration Procedure for this communication to work.

Key Events

There is a single instance of the plugin running in the Stream Deck application, even if multiple keys contain the same action provided by the plugin. Once registered, the plugin will be able to send and receive events like the keyDown and keyUp events.

Cross Platform

Stream Deck supports cross-platform plugins for Windows and macOS. In addition to the SDK supporting Javascript, there are many third-party plugin libraries in other programming languages.

Plugin

A plugin is composed of 4 elements:

• Manifest: describes the plugin (name, author, icon, etc.) and defines the actions

• Code: the code executed on startup, when pressing a key etc.

• Property Inspector: the user interface displayed when selecting a key in the canvas

• Assets: images, localization, etc.

Plugin Architecture

The manifest file has a CodePath member indicating the path to the plugin's code. An HTML file (in case you use Javascript) or a compiled command-line tool (C++, Objective-C, ...) to be run in a separate process.

Plugin Unique Identifier

Each plugin has a unique identifier used to identify the plugin in the Stream Deck store. The unique identifier must be a uniform type identifier (UTI) that contains only lowercase alphanumeric characters (a-z, 0-9), hyphen (-), and period (.). The string must be in reverse-DNS format. For example, if your domain is elgato.com and you create a plugin named Hello, you could assign the string com.elgato.hello as your plugin's Unique Identifier.

Plugin Instance

Each plugin has a single instance. All keys added to the canvas send events to that single plugin instance using a different context.

Actions

A plugin can describe multiple actions in its manifest. For example, the Game Capture plugin has six actions: Scene, Record, Screenshot, Flashback Recording, Stream, Live Commentary, all listed in the manijest.json (see Manifest).

Coordinates

Events can provide the coordinates of the key on the canvas. With those coordinates, groups of keys can have additional functionality.

Coordinates

Context

Each instance of the action has a context the Stream Deck application uses to locate the action. The plugin code should not rely on this value.

Property Inspector

The plugin and the Property Inspector are running independently from each other. Both should register to the Stream Deck application using the Registration Procedure and can communicate with the Stream Deck application using a dedicated WebSocket. There are several APIs available to exchange data between the plugin and the Property Inspector:

• When the Property Inspector is displayed, the current settings of the selected action are passed directly to the Property Inspector in the inActionInfo parameter. The Property Inspector can use this information to display the current settings in its UI.

• You can use the setSettings API to persistently save settings for the action's instance. The plugin will also automatically receive a didReceiveSettings callback with the new settings.

• You can use the setGlobalSettings API to save some data globally for the plugin (third-party access key, user settings, etc.). When the plugin uses setGlobalSettings, the Property Inspector will automatically receive a didReceiveGlobalSettings callback with the new global settings. Similarly when the Property Inspector uses this API, the plugin will automatically receive a didReceiveGlobalSettings callback.

• If you need to pass internal data from the plugin to the Property Inspector, you can use the sendToPropertyInspector API.

• Similarly, if you need to pass internal data from the Property Inspector to the plugin, you can use the sendToPlugin API.