Architecture
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.
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.
Dial Events
In addition to key events, Stream Deck + can receive dial and touch display events like touchTap
, dialDown
, dialUp
, and dialRotate
.
Cross Platform
Stream Deck supports cross-platform plugins for Windows and macOS. In addition to the SDK supporting Javascript, C++, and Objective-C, 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.
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 manifest.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.
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 adidReceiveSettings
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 usessetGlobalSettings
, the Property Inspector will automatically receive adidReceiveGlobalSettings
callback with the new global settings. Similarly when the Property Inspector uses this API, the plugin will automatically receive adidReceiveGlobalSettings
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.