Property Inspector (UI)

The property inspector (UI) connects to Stream Deck using a WebSocket, allowing it to directly receive a subset of events, and send commands. The WebSocket connection also allows the property inspector to communicate with the application-layer (i.e. the plugin).

Registration

A connection with Stream Deck is established within the property inspector by defining a function on the window, named connectElgatoStreamDeckSocket. Once the DOM has loaded, Stream Deck will invoke this function and provide registration information, including the port to connect on.

Below is an example of implementing the connectElgatoStreamDeckSocket function to establish a connection with Stream Deck:

Connecting to Stream Deck in the property inspector

window.connectElgatoStreamDeckSocket = (port, uuid, event, info, actionInfo) => {
    const infoObj = JSON.parse(info); // Information about Stream Deck and the plugin.
    const actionInfo = JSON.parse(actionInfo); // Information about the action the UI is for.

    // Establish a connection with Stream Deck
	const connection = new WebSocket(`ws://127.0.0.1:${port}`);
	connection.onopen = () => {
		connection.send(JSON.stringify({ event, uuid }));
	};
};

connectElgatoStreamDeckSocket

Connects to the Stream Deck, enabling the UI to interact with the plugin, and access the Stream Deck API.

window.connectElgatoStreamDeckSocket = (port: string, uuid: string, event: string, info: string, actionInfo: string) => void | Promise<void>

Parameters

Name	Description
port	Port to be used when connecting to Stream Deck.
uuid	Identifies the UI; this must be provided when establishing the connection with Stream Deck.
event	Name of the event that identifies the registration procedure; this must be provided when establishing the connection with Stream Deck.
info	Information about the Stream Deck application and operating system.
actionInfo	Information about the action the UI is associated with.

RegistrationInfo

Information about the Stream Deck application, the plugin, the user's operating system, user's Stream Deck devices, etc.

type RegistrationInfo = {
    application: {
        font: string;
        language: "de" | "en" | "es" | "fr" | "ja" | "ko" | "zh_CN" | "zh_TW";
        platform: "mac" | "windows";
        platformVersion: string;
        version: string;
    };
    colors: {
        buttonMouseOverBackgroundColor: string;
        buttonPressedBackgroundColor: string;
        buttonPressedBorderColor: string;
        buttonPressedTextColor: string;
        highlightColor: string;
    };
    devicePixelRatio: number;
    devices: {
        id: string;
        name: string;
        size: {
            columns: number;
            rows: number;
        };
        type: DeviceType;
    }[];
    plugin: {
        uuid: string;
        version: string;
    };
};

application: objectRequired

Stream Deck application specific information.

font: stringRequired

Font being used by the Stream Deck application.

language: "de" | "en" | "es" | "fr" | "ja" | "ko" | "zh_CN" | "zh_TW"Required

Users preferred language; this is used by the Stream Deck application for localization.

platform: "mac" | "windows"Required

Operating system.

platformVersion: stringRequired

Operating system version, e.g. "10" for Windows 10.

version: stringRequired

Stream Deck application version.

colors: objectRequired

Collection of preferred colors used by the Stream Deck.

buttonMouseOverBackgroundColor: stringRequired

Color that denotes the background of a button that is being moused over.

buttonPressedBackgroundColor: stringRequired

Color that denotes the background of a pressed button.

buttonPressedBorderColor: stringRequired

Color that denotes the border of a press button.

buttonPressedTextColor: stringRequired

Color that denotes the text of a pressed button.

highlightColor: stringRequired

Color of highlighted text.

devicePixelRatio: numberRequired

Pixel ratio, used to identify if the Stream Deck application is running on a high DPI screen.

devices: object[]Required

Devices associated with the Stream Deck application; this may include devices that are not currently connected. Use "deviceDidConnect" event to determine which devices are active.

plugin: objectRequired

Information about the plugin.

uuid: stringRequired

Unique identifier of the plugin, as defined by the plugin.

version: stringRequired

Version of the plugin.

Events

DidReceiveGlobalSettings

Occurs when the plugin receives the global settings from the Stream Deck.

type DidReceiveGlobalSettings = {
    event: "didReceiveGlobalSettings";
    payload: {
        settings: JsonObject;
    };
};

event: "didReceiveGlobalSettings"Required

Name of the event used to identify what occurred.

payload: objectRequired

Additional information about the event that occurred.

settings: JsonObjectRequired

Global settings associated with this plugin.

DidReceivePluginMessage

Occurs when a message was received from the plugin.

type DidReceivePluginMessage = {
    action: string;
    context: string;
    event: "sendToPropertyInspector";
    payload: JsonValue;
};

action: stringRequired

Unique identifier of the action as defined within the plugin's manifest (Actions[].UUID) e.g. "com.elgato.wavelink.mute".

context: stringRequired

Identifies the instance of an action that caused the event, i.e. the specific key or dial. This identifier can be used to provide feedback to the Stream Deck, persist and request settings associated with the action instance, etc.

event: "sendToPropertyInspector"Required

Name of the event used to identify what occurred.

payload: JsonValueRequired

Contextualized information for this event.

DidReceiveSettings

Occurs when the settings associated with an action instance are requested, or when the the settings were updated by the property inspector.

type DidReceiveSettings = {
    action: string;
    context: string;
    device: string;
    event: "didReceiveSettings";
    payload:
        | {
              controller: "Keypad";
              isInMultiAction: true;
              settings: JsonObject;
              state?: number;
          }
        | {
              controller: "Encoder" | "Keypad";
              coordinates: {
                  column: number;
                  row: number;
              };
              isInMultiAction: false;
              settings: JsonObject;
              state?: number;
          };
};

action: stringRequired

Unique identifier of the action as defined within the plugin's manifest (Actions[].UUID) e.g. "com.elgato.wavelink.mute".

context: stringRequired

Identifies the instance of an action that caused the event, i.e. the specific key or dial. This identifier can be used to provide feedback to the Stream Deck, persist and request settings associated with the action instance, etc.

device: stringRequired

Unique identifier of the Stream Deck device that this event is associated with.

event: "didReceiveSettings"Required

Name of the event used to identify what occurred.

payload: MultiActionPayload | SingleActionPayloadRequired

Contextualized information for this event.

One of:

MultiActionPayload

controller: "Keypad"Required

Defines the controller type the action is applicable to. Keypad refers to a standard action on a Stream Deck device, e.g. 1 of the 15 buttons on the Stream Deck MK.2, or a pedal on the Stream Deck Pedal, etc., whereas an Encoder refers to a dial / touchscreen on the Stream Deck +.

NB: Requires Stream Deck 6.5 for WillAppear and WillDisappear events.

isInMultiAction: trueRequired

Determines whether the action is part of a multi-action.

NB. Requires Stream Deck 6.7 when accessed from the property inspector.

settings: JsonObjectRequired

Settings associated with the action instance.

state: numberRequired

Current state of the action; only applicable to actions that have multiple states defined within the manifest.json file.

SingleActionPayload

controller: ControllerRequired

Defines the controller type the action is applicable to. Keypad refers to a standard action on a Stream Deck device, e.g. 1 of the 15 buttons on the Stream Deck MK.2, or a pedal on the Stream Deck Pedal, etc., whereas an Encoder refers to a dial / touchscreen on the Stream Deck +.

coordinates: CoordinatesRequired

Coordinates that identify the location of an action.

column: numberRequired

Column the action instance is located in, indexed from 0.

row: numberRequired

Row the action instance is located on, indexed from 0. NB When the device is DeviceType.StreamDeckPlus the row can be 0 for keys (Keypad), and will always be 0 for dials (Encoder); to differentiate between actions types, cross-check the value of controller found on WillAppear.payload.

isInMultiAction: falseRequired

Determines whether the action is part of a multi-action.

NB. Requires Stream Deck 6.7 when accessed from the property inspector.

settings: JsonObjectRequired

Settings associated with the action instance.

state: numberRequired

Current state of the action; only applicable to actions that have multiple states defined within the manifest.json file.

Commands

GetGlobalSettings

Gets the global settings associated with the plugin. Causes DidReceiveGlobalSettings to be emitted.

type GetGlobalSettings = {
    context: string;
    event: "getGlobalSettings";
};

context: stringRequired

Defines the context of the command, e.g. which action instance the command is intended for.

event: "getGlobalSettings"Required

Name of the command, used to identify the request.

GetSettings

Gets the settings associated with an instance of an action. Causes DidReceiveSettings to be emitted.

type UIGetSettings = {
    action: string;
    context: string;
    context: string;
    event: "getSettings";
};

action: stringRequired

Unique identifier of the action as defined within the plugin's manifest (Actions[].UUID) e.g. "com.elgato.wavelink.mute".

context: stringRequired

Identifies the instance of an action that caused the event, i.e. the specific key or dial. This identifier can be used to provide feedback to the Stream Deck, persist and request settings associated with the action instance, etc.

context: stringRequired

Defines the context of the command, e.g. which action instance the command is intended for.

event: "getSettings"Required

Name of the command, used to identify the request.

OpenUrl

Opens the URL in the user's default browser.

type OpenUrl = {
    event: "openUrl";
    payload: {
        url: string;
    };
};

event: "openUrl"Required

Name of the command, used to identify the request.

payload: objectRequired

Additional information supplied as part of the command.

url: stringRequired

URL to open.

SendToPlugin

Sends a message to the plugin.

type SendToPlugin = {
    action: string;
    context: string;
    event: "sendToPlugin";
    payload: JsonValue;
};

action: stringRequired

Unique identifier of the action as defined within the plugin's manifest (Actions[].UUID) e.g. "com.elgato.wavelink.mute".

context: stringRequired

Identifies the instance of an action that caused the event, i.e. the specific key or dial. This identifier can be used to provide feedback to the Stream Deck, persist and request settings associated with the action instance, etc.

event: "sendToPlugin"Required

Name of the command, used to identify the request.

payload: JsonValueRequired

Additional information supplied as part of the command.

SetGlobalSettings

Sets the global settings associated with the plugin.

type SetGlobalSettings = {
    context: string;
    event: "setGlobalSettings";
    payload: JsonObject;
};

context: stringRequired

Defines the context of the command, e.g. which action instance the command is intended for.

event: "setGlobalSettings"Required

Name of the command, used to identify the request.

payload: JsonObjectRequired

Additional information supplied as part of the command.

SetSettings

Sets the settings associated with an instance of an action.

type UISetSettings = {
    action: string;
    context: string;
    context: string;
    event: "setSettings";
    payload: JsonObject;
};

action: stringRequired

Unique identifier of the action as defined within the plugin's manifest (Actions[].UUID) e.g. "com.elgato.wavelink.mute".

context: stringRequired

Identifies the instance of an action that caused the event, i.e. the specific key or dial. This identifier can be used to provide feedback to the Stream Deck, persist and request settings associated with the action instance, etc.

context: stringRequired

Defines the context of the command, e.g. which action instance the command is intended for.

event: "setSettings"Required

Name of the command, used to identify the request.

payload: JsonObjectRequired

Additional information supplied as part of the command.