Space Plugin SDK

https://sdk.key123.vip/en/
Admin
Space Plugin SDK is a cross-platform development platform that enables developers to create...
Tokens:18,979
Snippets:85
Trust Score:5.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Clone Stream Dock Plugin Template using Git

Source: https://sdk.key123.vip/en/guide/get-started

Clone the official Stream Dock Plugin SDK repository from GitHub to start developing your plugin. This command initializes a local copy of the template repository.

```git
git clone git@github.com:MiraboxSpace/StreamDock-Plugin-SDK.git
```

--------------------------------

### Access Stream Dock Debugging URL

Source: https://sdk.key123.vip/en/guide/get-started

This URL is used for debugging Stream Dock plugins. It allows developers to access debugging interfaces and reload plugin components within a browser environment.

```http
http://localhost:23519/
```

--------------------------------

### Applications to Monitor Configuration Example

Source: https://sdk.key123.vip/en/guide/manifest

Configures the plugin to receive notifications when specified applications start or terminate. This is useful for creating context-aware actions.

```json
{
  "ApplicationsToMonitor": {
    "mac": [
      "com.apple.mail",
      "com.apple.safari"
    ],
    "windows": [
      "someApp.exe",
      "anotherApp.exe"
    ]
  }
}
```

--------------------------------

### OS Support Configuration Example

Source: https://sdk.key123.vip/en/guide/manifest

Defines the operating systems and minimum required versions for a plugin to function. This allows developers to specify compatibility for different platforms like macOS and Windows.

```json
{
  "OS": [
    {
      "Platform": "mac",
      "MinimumVersion" : "10.11"
    },
    {
      "Platform": "windows",
      "MinimumVersion" : "7"
    }
  ]
}
```

--------------------------------

### Example manifest.json Structure

Source: https://sdk.key123.vip/en/guide/manifest

This JSON structure defines the manifest for a Stream Deck plugin. It includes details about actions, plugin metadata, and compatibility with operating systems and software versions.

```json
{
  "Actions": [
    {
      "UUID": "com.mirabox.streamdock.demo.action1",
      "Icon": "images/icon.png",
      "state": 0,
      "States": [
        {
          "FontSize": "11",
          "FontStyle": "Bold",
          "TitleAlignment": "bottom",
          "Image": "images/index.jpg"
        }
      ],
      "Settings": {
      },
      "UserTitleEnabled": false,
      "SupportedInMultiActions": false,
      "Controllers": [
        "Keypad",
        "Information",
        "SecondaryScreen",
        "Knob",
        "btn"
      ],
      "Name": "Name",
      "Tooltip": "Tooltip",
      "PropertyInspectorPath": "index.html"
    }
  ],
  "Version": "2.0.0",
  "Name": "Demo",
  "Icon": "images/icon.png",
  "CategoryIcon": "images/icon.png",
  "Category": "",
  "Description": "This is a sample plugin",
  "CodePath": "index.html",
  "SDKVersion": 1,
  "Author": "MiraBox",
  "URL": "http://video.hotspotek.com.cn/",
  "OS": [
    {
      "Platform": "mac",
      "MinimumVersion": "10.11"
    },
    {
      "Platform": "windows",
      "MinimumVersion": "7"
    }
  ],
  "Software": {
    "MinimumVersion": "2.10.179.426"
  },
  "Nodejs":{
    "Version": "20"
  }
}
```

--------------------------------

### Displaying Button Feedback Messages

Source: https://sdk.key123.vip/en/guide/style-guide

Use these functions to inform users about the success or failure of their button actions within the Stream Dock plugin.

```javascript
showAlert();
showOk();
```

--------------------------------

### Stream Deck Software Version Requirement Example

Source: https://sdk.key123.vip/en/guide/manifest

Specifies the minimum version of the Stream Deck application required for the plugin. This ensures that the plugin utilizes features available in newer versions of the software.

```json
{
  "Software": {
    "MinimumVersion" : "2.10.179.426"
  }
}
```

--------------------------------

### Vue Property Inspector Setup

Source: https://sdk.key123.vip/en/guide/property-inspector

Sets up a Vue-based Property Inspector for Stream Dock plugins. It uses custom hooks for property and internationalization stores and watches for events from the Stream Dock.

```vue
<script setup lang="ts">
  import { usePropertyStore, useWatchEvent, TabView } from '@/hooks/property';
  import { useI18nStore } from '@/hooks/i18n';

  const i18n = useI18nStore();
  const property = usePropertyStore();
  useWatchEvent({
    didReceiveSettings(data) {},
    sendToPropertyInspector(data) {}
  });
</script>

<template>
</template>

<style lang="scss" scoped></style>

```

--------------------------------

### Property Inspector Registration

Source: https://sdk.key123.vip/en/guide/registration

Guide for registering Property Inspectors using JavaScript, including WebSocket connection and event handling.

```APIDOC
## Property Inspector Registration

Property Inspectors use the `connectElgatoStreamDeckSocket` function for registration.

### Function Signature

```javascript
function connectElgatoStreamDeckSocket(
    inPort,
    inPropertyInspectorUUID, 
    inRegisterEvent, 
    inInfo, 
    inActionInfo
)
```

### Parameter Descriptions

-   **inPort** (number) - The port used for connecting to the WebSocket.
-   **inPropertyInspectorUUID** (string) - The unique identifier string for the Property Inspector.
-   **inRegisterEvent** (string) - The event type for registering the Property Inspector.
-   **inInfo** (object) - An object containing information about the Stream Deck application.
-   **inActionInfo** (object) - An object containing information about the specific action.

### Registration Steps

1.  **Create WebSocket:** Establish a WebSocket connection to `ws://127.0.0.1:[inPort]`.
    ```javascript
    const server = new WebSocket('ws://127.0.0.1:' + inPort);
    ```
2.  **Send Registration Data:** Upon successful WebSocket connection, send registration JSON data.
    ```javascript
    server.onopen = () => server.send(
        JSON.stringify({ event: inRegisterEvent, uuid: inPropertyInspectorUUID });
    );
    ```
3.  **Receive Events:** Process incoming events through the `onmessage` handler.
    ```javascript
    server.onmessage = (e) => (
        console.log(e.data);
    );
    ```
```

--------------------------------

### WillAppear Event

Source: https://sdk.key123.vip/en/guide/events-received

The willAppear event is triggered when an action becomes visible on the Stream Deck, such as on application start, profile switching, or key assignment.

```APIDOC
## willAppear

### Description
This event is received by the plugin when an instance of an action appears on the Stream Dock. This can happen when hardware is first inserted or when entering a folder containing the action.

### Scenarios
* The Stream Dock application starts
* The user switches between profiles
* The user sets a key to use your action

### Event Data
```json
{
    "action": "com.mirabox.demo.action1",
    "event": "willAppear",
    "context": "uniqueValue",
    "device": "uniqueValue",
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3,
            "row": 1
        },
        "controller": "Keypad",
        "state": 0,
        "isInMultiAction": false
    }
}
```

### Payload Members
* **action** (string) - Unique identifier for the action.
* **event** (string) - The name of the event, which is 'willAppear'.
* **context** (string) - Value that identifies the instance action.
* **device** (string) - Value used to identify the device.
* **payload** (object) - A JSON object containing event details.
  * **settings** (object) - Persistent storage data for the action.
  * **coordinates** (object) - Coordinates of the triggered action (column, row).
  * **controller** (string) - Type of controller (e.g., 'Keypad', 'Information', 'SecondaryScreen', 'Knob').
  * **state** (number) - Current state of the action if defined in manifest.json (starts from 0).
  * **isInMultiAction** (boolean) - Indicates if the action is part of a Multi-Action.
```

--------------------------------

### Vue.js Internationalization Setup and Usage

Source: https://sdk.key123.vip/en/guide/i18n

Explains how to set up internationalization for Vue.js templates by defining a `useI18nStore` hook in `src/hooks/i18n.ts`. This hook retrieves the current language and returns a localization object. The example shows how to import and use this hook in a Vue component to display localized strings.

```typescript
export const useI18nStore = () => {
  const language = window.argv[3].application.language;
  const localString = {
    en: {
      test: 'test'
    },
    zh_CN: {
      test: '测试'
    }
  };
  return localString[language] || localString['en'];
};
```

```vue
<script setup lang="ts">
  import { usePropertyStore, useWatchEvent } from '@/hooks/property';
  import { useI18nStore } from '@/hooks/i18n';

  const i18n = useI18nStore();
  const property = usePropertyStore();
  useWatchEvent({
    didReceiveSettings(data) {},
    sendToPropertyInspector(data) {}
  });
</script>

<template>
  <div>{{ i18n.test }}</div>
</template>
```

--------------------------------

### Vue Property Inspector with Input Binding

Source: https://sdk.key123.vip/en/guide/property-inspector

An example of a Vue Property Inspector that uses two-way data binding to synchronize an input field with the plugin's settings. It includes internationalization and tab view components.

```vue
<script setup lang="ts">
  import { usePropertyStore, useWatchEvent, TabView } from '@/hooks/property';
  import { useI18nStore } from '@/hooks/i18n';

  const i18n = useI18nStore();
  const property = usePropertyStore();
  useWatchEvent({
    didReceiveSettings(data) {},
    sendToPropertyInspector(data) {}
  });
</script>

<template>
  <TabView :title="i18n.title">
    <input type="text" v-model="property.settings.text">
  </TabView>
</template>

<style lang="scss" scoped></style>

```

--------------------------------

### Compiled Executable Plugin Registration

Source: https://sdk.key123.vip/en/guide/registration

Information on how to launch compiled executable plugins with the necessary parameters for registration.

```APIDOC
## Plugin Registration for Compiled Executables

Compiled executable plugins are launched with specific command-line parameters.

### Launch Parameters

| Parameter      | Description                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `-port`        | The string `"-port"`, followed by the port number for the WebSocket connection.                          |
| `port`         | The port number used for connecting to the WebSocket.                                                       |
| `-pluginUUID` | The string `"-pluginUUID"`, followed by a unique identifier string used to register the plugin.          |
| `pluginUUID` | A unique identifier string for the plugin.                                                                  |
| `-registerEvent`| The string `"-registerEvent"`, followed by the event type applied to register the plugin.                 |
| `event`        | The event type for plugin registration.                                                                     |
| `-info`        | The string `"-info"`, followed by a JSON string containing Stream Deck and device information.            |
| `info`         | A JSON string containing Stream Deck and device information.                                                |

**Example Launch Command:**

```bash
YourPlugin.exe -port 1234 -pluginUUID "your-plugin-uuid" -registerEvent "registerPlugin" -info "{\"application\": \"StreamDeck\", \"version\": \"1.0\"}"
```
```

--------------------------------

### showOk

Source: https://sdk.key123.vip/en/guide/events-sent

Displays a temporary OK checkmark icon on an action.

```APIDOC
## POST /showOk

### Description
This event allows plugins to display a temporary 'OK' checkmark icon on a specific action instance, indicating a successful operation or state.

### Method
POST

### Endpoint
/showOk

### Parameters
#### Request Body
- **event** (string) - Required - Must be 'showOk'.
- **context** (string) - Required - A unique identifier for the action instance where the OK icon should be shown.

### Request Example
```json
{
    "event": "showOk",
    "context": "uniqueValue"
}
```

### Response
#### Success Response (200)
An empty response or a success confirmation.

#### Response Example
(No specific response body format is defined for success, typically an acknowledgment).

```

--------------------------------

### Receive Action Instance Settings

Source: https://sdk.key123.vip/en/guide/events-sent

Callback event received after a getSettings request, containing the persistent data for an action instance. Includes action details, context, device info, and the settings payload.

```json
{
  "action": "com.mirabox.demo.action1", 
  "event": "didReceiveSettings", 
  "context": uniqueValue, 
  "device": uniqueValue, 
  "payload": {
   "settings": {"<json data>"},
    "coordinates": {
      "column": 3, 
      "row": 1
    }, 
    "isInMultiAction": false
  }
}
```

--------------------------------

### Plugin Manifest Configuration

Source: https://sdk.key123.vip/en/guide/manifest

Defines the core properties and behaviors of a Stream Deck plugin, including actions, states, and system requirements.

```APIDOC
## Plugin Manifest Structure

This section details the properties that can be included in a Stream Deck plugin's manifest file.

### Actions
Defines the available actions for the plugin.

- **UUID** (Required, string): Unique identifier for the action (e.g., `com.mirabox.streamdock.demo.action1`).
- **Icon** (Required, string): Relative path to the action's icon (40x40px).
- **Name** (Required, string): User-visible name of the action.
- **state** (Optional, integer): Index of the initial state (default: 0).
- **States** (Required, array): Array defining the different states of the action.
  - **Image** (Required, string): Image for the state.
  - **Title** (Optional, string): Default title for the state.
  - **ShowTitle** (Optional, boolean): Whether to display the title (default: true).
  - **TitleColor** (Optional, string): Color of the title.
  - **TitleAlignment** (Optional, string): Vertical alignment of the title ('top', 'bottom', 'center').
  - **FontFamily** (Optional, string): Font family for the title.
  - **FontStyle** (Optional, string): Font style for the title ('Regular', 'Bold', 'Italic', 'Bold Italic').
  - **FontSize** (Optional, integer): Font size for the title.
  - **FontUnderline** (Optional, boolean): Underline for the title (default: false).
- **PropertyInspectorPath** (Optional, string): Relative path to the Property Inspector HTML file.
- **SupportedInMultiActions** (Optional, boolean): Whether the action supports multi-actions (default: true).
- **Tooltip** (Optional, string): Tooltip text displayed on hover.
- **Settings** (Optional, object): Initial settings for the action.
- **UserTitleEnabled** (Optional, boolean): Whether the user title field is enabled (default: true).
- **Controllers** (Optional, array): Supported controller types ('Keypad', 'Information', 'SecondaryScreen', 'Knob', default: ['Keypad']).
- **VisibleInActionsList** (Optional, boolean): Whether the action is visible in the action list (default: true).
- **OS** (Optional, array): Supported operating systems.
  - **Platform** (Required, string): OS name ('mac' or 'windows').
  - **MinimumVersion** (Required, string): Minimum OS version (e.g., '10.11', '7').

### Software Requirements
Specifies the minimum Stream Deck application version.

- **Software.MinimumVersion** (Required, string): Minimum Stream Dock application version (e.g., `2.10.179.426`).

### Application Monitoring
Monitors specific applications for start/termination events.

- **ApplicationsToMonitor** (object): Contains platform-specific application identifiers.
  - **mac** (array): List of macOS bundle identifiers (e.g., `com.apple.mail`).
  - **windows** (array): List of Windows executable names (e.g., `someApp.exe`).

### Node.js Integration
Enables the use of Node.js for plugins.

- **Nodejs**: Configuration for built-in Node.js support.
  - **Version** (integer): Specifies the Node.js version to use (e.g., `20`). Requires specific Stream Deck software versions.
    - Windows: Software version `3.10.188.226` or above, built-in Node.js version `20.8.1`.
    - macOS: Software version `3.10.191.0421` or above.

```

--------------------------------

### Display OK Checkmark with showOk Event

Source: https://sdk.key123.vip/en/guide/events-sent

Allows plugins to display a temporary OK checkmark icon on an action instance. This event requires the context of the action.

```JSON
{
    "event": "showOk",
    "context": uniqueValue
}
```

--------------------------------

### JavaScript Plugin Registration

Source: https://sdk.key123.vip/en/guide/registration

Details on how JavaScript plugins establish a WebSocket connection and register with the Stream Deck.

```APIDOC
## JavaScript Plugin Registration

Plugins must declare the `connectElgatoStreamDeckSocket` function to register.

### Function Signature

```javascript
function connectElgatoStreamDeckSocket(inPort, inPluginUUID, inRegisterEvent, inInfo)
```

### Registration Steps

1.  **Create WebSocket:** Establish a WebSocket connection to `ws://127.0.0.1:[inPort]`.
    ```javascript
    const server = new WebSocket('ws://127.0.0.1:' + inPort);
    ```
2.  **Send Registration Event:** Upon successful WebSocket connection, send a registration event.
    ```javascript
    server.onopen = () => server.send(
        JSON.stringify({ event: inRegisterEvent, uuid: inPluginUUID });
    );
    ```
3.  **Receive Events:** Process incoming events through the `onmessage` handler.
    ```javascript
    server.onmessage = (e) => (
        console.log(e.data);
    );
    ```
```

--------------------------------

### Global Settings Management Events

Source: https://sdk.key123.vip/en/guide/events-sent

APIs for managing globally persistent data, such as tokens or shared configurations.

```APIDOC
## POST /setGlobalSettings

### Description
Globally save plugin data. This can be used to save tokens or other data available across all actions.

### Method
POST

### Endpoint
(This is an event-driven system, not a REST API endpoint. The event is sent to the Stream Deck application.)

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event, `setGlobalSettings`.
- **context** (string) - Required - The context of the plugin or property inspector.
- **payload** (object) - Required - JSON data to be saved.
  - **payload.settings** (object) - Required - The global data to save.

### Request Example
```json
{
    "event": "setGlobalSettings",
    "context": "uniqueValue",
    "payload": {
        "settings": {}
    }
}
```

### Response
#### Success Response (200)
(No explicit response. A `didReceiveGlobalSettings` event is sent to the relevant party.)

## POST /getGlobalSettings

### Description
Request globally stored persistent data.

### Method
POST

### Endpoint
(This is an event-driven system, not a REST API endpoint. The event is sent to the Stream Deck application.)

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event, `getGlobalSettings`.
- **context** (string) - Required - The context of the plugin or property inspector.

### Request Example
```json
{
    "event": "getGlobalSettings",
    "context": "uniqueValue"
}
```

### Response
#### Success Response (200)
(No explicit response. A `didReceiveGlobalSettings` event is asynchronously received.)

#### Response Example (didReceiveGlobalSettings)
```json
{
  "event": "didReceiveGlobalSettings", 
  "payload": {
     "settings": {}
   }
}
```
```

--------------------------------

### Configure application monitoring in manifest.json

Source: https://sdk.key123.vip/en/guide/events-received

Plugins can specify applications to monitor in the `manifest.json` file. This configuration allows plugins to receive events when these applications are launched or terminated. The format differs between macOS (bundle identifier) and Windows (exe file name).

```json
"ApplicationsToMonitor": {
 "mac": [
  "com.apple.mail"
 ]
}
```

--------------------------------

### didReceiveGlobalSettings

Source: https://sdk.key123.vip/en/guide/events-received

This event is sent when global settings change. These settings apply across all actions and profiles.

```APIDOC
## didReceiveGlobalSettings

Event received after globalSettings change.

### Description

This event is sent to the plugin when the global settings for the application are changed. Global settings are persistent and apply to all actions and profiles.

### Method

This is an event pushed from the Stream Dock application, not a direct API call.

### Endpoint

N/A (Event-driven)

### Parameters

#### Request Body

- **event** (string) - Required - Must be `didReceiveGlobalSettings`.
- **payload** (object) - Required - Contains the global settings.
    - **settings** (object) - Required - This JSON object contains the persistent storage data for global settings.

### Request Example

```json
{
  "event": "didReceiveGlobalSettings", 
  "payload": {
   "settings": {"globalSetting1": "globalValue1"}
  }
}
```

### Response

This event does not expect a response from the plugin.

#### Success Response (200)

N/A

#### Response Example

N/A
```

--------------------------------

### Settings Management Events

Source: https://sdk.key123.vip/en/guide/events-sent

APIs for managing action-specific settings, including saving and retrieving persistent data.

```APIDOC
## POST /setSettings

### Description
Permanently save data for an action instance.

### Method
POST

### Endpoint
(This is an event-driven system, not a REST API endpoint. The event is sent to the Stream Deck application.)

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event, `setSettings`.
- **context** (string) - Required - The context of the action instance or property inspector.
- **payload** (object) - Required - JSON data to be saved.
  - **payload.settings** (object) - Required - The data to save.

### Request Example
```json
{
    "event": "setSettings",
    "context": "uniqueValue",
    "payload": {
        "settings": {}
    }
}
```

### Response
#### Success Response (200)
(No explicit response. A `didReceiveSettings` event is sent to the relevant party.)

## POST /getSettings

### Description
Request persistent data for an action instance.

### Method
POST

### Endpoint
(This is an event-driven system, not a REST API endpoint. The event is sent to the Stream Deck application.)

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event, `getSettings`.
- **context** (string) - Required - The context of the action instance or property inspector.

### Request Example
```json
{
    "event": "getSettings",
    "context": "uniqueValue"
}
```

### Response
#### Success Response (200)
(No explicit response. A `didReceiveSettings` event is asynchronously received.)

#### Response Example (didReceiveSettings)
```json
{
  "action": "com.mirabox.demo.action1", 
  "event": "didReceiveSettings", 
  "context": "uniqueValue", 
  "device": "uniqueValue", 
  "payload": {
   "settings": {},
    "coordinates": {
      "column": 3, 
      "row": 1 
    },
    "isInMultiAction": false
  }
}
```
```

--------------------------------

### Request Global Plugin Settings

Source: https://sdk.key123.vip/en/guide/events-sent

Request globally stored persistent data for a plugin. Asynchronously, a didReceiveGlobalSettings event will be received containing the requested data.

```json
{
    "event": "getGlobalSettings",
    "context": uniqueValue
}
```

--------------------------------

### keyUp Event

Source: https://sdk.key123.vip/en/guide/events-received

This event is sent when a user releases a key. Similar to keyDown, it includes action, context, device, and payload details.

```APIDOC
## POST /events/keyUp

### Description
This event is triggered when the user releases a key.

### Method
POST

### Endpoint
/events/keyUp

### Request Body
- **action** (string) - Required - Unique identifier for the action.
- **event** (string) - Required - Must be "keyUp".
- **context** (string) - Required - Value that identifies the instance action.
- **device** (string) - Required - Value used to identify the device.
- **payload** (object) - Required - A JSON object containing event-specific data.
  - **settings** (object) - Required - Persistent storage data.
  - **coordinates** (object) - Required - Coordinates of the triggered action.
    - **column** (integer) - Required - Column coordinate.
    - **row** (integer) - Required - Row coordinate.
  - **state** (integer) - Optional - The current state of the action if it supports multiple states.
  - **isInMultiAction** (boolean) - Optional - Indicates if the action is part of a Multi-Action.

### Request Example
```json
{
  "action": "com.mirabox.demo.action2",
  "event": "keyUp",
  "context": "uniqueValue",
  "device": "uniqueValue",
  "payload": {
    "settings": {}, 
    "coordinates": {
      "column": 0,
      "row": 0
    },
    "state": 0,
    "isInMultiAction": false
  }
}
```

### Response
#### Success Response (200)
No specific response structure defined, typically an acknowledgment of event receipt.
```

--------------------------------

### systemDidWakeUp Event

Source: https://sdk.key123.vip/en/guide/events-received

This event is triggered when the computer wakes up. The plugin may receive multiple such events, and device availability is not guaranteed.

```json
{
 "event": "systemDidWakeUp"
}
```

--------------------------------

### keyUp Event Structure

Source: https://sdk.key123.vip/en/guide/events-received

This JSON structure details the 'keyUp' event, triggered when a user releases a key. It contains action identifiers, context, device, and a payload with settings, coordinates, state, and multi-action status.

```json
{
  "action": "com.mirabox.demo.action2",
  "event": "keyUp",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
    "state": 0,
    "isInMultiAction": false
  }
}
```

--------------------------------

### didReceiveSettings

Source: https://sdk.key123.vip/en/guide/events-received

This event is triggered when the settings for a specific action instance change. It provides the updated settings, coordinates, and information about multi-action usage.

```APIDOC
## didReceiveSettings

Event received after settings change.

### Description

This event is sent to the plugin when the settings for an action instance are changed. This can happen when the user modifies settings via the property inspector or through other means.

### Method

This is an event pushed from the Stream Dock application, not a direct API call.

### Endpoint

N/A (Event-driven)

### Parameters

#### Request Body

- **action** (string) - Required - Unique identifier for the action.
- **event** (string) - Required - Must be `didReceiveSettings`.
- **context** (string) - Required - Value that identifies the instance action.
- **device** (string) - Required - Value used to identify the device.
- **payload** (object) - Required - Contains settings, coordinates, and multi-action status.
    - **settings** (object) - Required - Contains the persistent storage data for the action.
    - **coordinates** (object) - Required - Coordinates of the triggered action.
        - **column** (integer) - The column number of the action.
        - **row** (integer) - The row number of the action.
    - **isInMultiAction** (boolean) - Optional - Boolean indicating whether the action is within a Multi-Action.

### Request Example

```json
{
  "action": "com.mirabox.demo.action1", 
  "event": "didReceiveSettings", 
  "context": "uniqueValue", 
  "device": "uniqueValue", 
  "payload": {
   "settings": {"mySetting": "myValue"},
    "coordinates": {
      "column": 3,
      "row": 1
    },
    "isInMultiAction": false
  }
}
```

### Response

This event does not expect a response from the plugin.

#### Success Response (200)

N/A

#### Response Example

N/A
```

--------------------------------

### Set Action Image with setImage Event (Base64)

Source: https://sdk.key123.vip/en/guide/events-sent

Allows plugins to dynamically change the image of an action instance using base64 encoded images. Supports PNG, JPG, and GIF formats. The event includes context, payload with image, target, and state.

```JSON
{
    "event": "setImage",
    "context": uniqueValue,
    "payload": {
        "image": "data:image/png;base64,avFOdwp0Ksgoe...",
        "target": software, hardware or both,
        "state": 0-based integer
    }
}
```

--------------------------------

### Manifest JSON Structure for Internationalization

Source: https://sdk.key123.vip/en/guide/i18n

Defines the structure of the manifest.json file for internationalization, including fields for general strings and localized strings for actions and custom keys. This structure allows Stream Dock to load appropriate translations based on the user's language.

```json
{
  "Description": "Test", 
  "Name": "Test", 
  "Category": "Test", 
  "com.mirabox.demo.action1": {
    "Name": "Test", 
    "Tooltip": "Test"
  },
  "Localization": {
    "test": "Test"
  }
}
```

--------------------------------

### Action Information JSON String

Source: https://sdk.key123.vip/en/guide/registration

This JSON string provides details about an action triggered by a user. It includes the action identifier, context, associated device, and a payload containing settings, controller type, and coordinates.

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

--------------------------------

### applicationDidLaunch Event

Source: https://sdk.key123.vip/en/guide/events-received

This event notifies the plugin when a monitored application has been launched. The plugin can be configured in manifest.json to monitor specific applications.

```APIDOC
## applicationDidLaunch

### Description
When a monitored application is launched, the plugin will receive this event.

### Method
EVENT

### Endpoint
/websites/sdk_key123_vip_en

### Parameters
#### Event Payload
- **event** (string) - Required - Must be 'applicationDidLaunch'.
- **payload** (object) - Required - A JSON object containing details about the launched application.
  - **application** (string) - Required - The identifier of the launched application (e.g., bundle identifier on macOS, exe file name on Windows).

### Response Example
```json
{
  "event": "applicationDidLaunch",
  "payload": {
    "application": "com.apple.mail"
  }
}
```
```

--------------------------------

### Receive Global Plugin Settings

Source: https://sdk.key123.vip/en/guide/events-sent

Callback event received after a getGlobalSettings request, containing the globally stored persistent data for the plugin.

```json
{
  "event": "didReceiveGlobalSettings", 
  "payload": {
     "settings": {"<json data>"}
   }
}
```

--------------------------------

### didReceiveGlobalSettings Event Structure

Source: https://sdk.key123.vip/en/guide/events-received

This event is triggered when global settings are modified. It provides the updated global settings within its payload.

```json
{
  "event": "didReceiveGlobalSettings", 
  "payload": {
   "settings": {<json data>}
  }
}
```

--------------------------------

### Utility Events

Source: https://sdk.key123.vip/en/guide/events-sent

Events for performing utility functions like opening URLs and logging messages.

```APIDOC
## POST /openUrl

### Description
Open a URL in the default browser.

### Method
POST

### Endpoint
(This is an event-driven system, not a REST API endpoint. The event is sent to the Stream Deck application.)

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event, `openUrl`.
- **payload** (object) - Required - Contains the URL to open.
  - **payload.url** (string) - Required - The URL to open.

### Request Example
```json
{
    "event": "openUrl",
    "payload": {
        "url": "https://www.example.com"
    }
}
```

### Response
#### Success Response (200)
(No explicit response. The URL is opened in the default browser.)

## POST /logMessage

### Description
Write a debug message to the log file.

### Method
POST

### Endpoint
(This is an event-driven system, not a REST API endpoint. The event is sent to the Stream Deck application.)

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event, `logMessage`.
- **payload** (object) - Required - Contains the message to log.
  - **payload.message** (string) - Required - The debug message.

### Request Example
```json
{
    "event": "logMessage",
    "payload": {
        "message": "This is a debug message."
    }
}
```

### Response
#### Success Response (200)
(No explicit response. The message is written to the log file.)
```

--------------------------------

### setImage

Source: https://sdk.key123.vip/en/guide/events-sent

Dynamically updates the image of an action instance.

```APIDOC
## POST /setImage

### Description
Enables plugins to dynamically change the image displayed for an action instance. This is useful for visual feedback or changing the appearance of an action based on its state or context. Supports both base64 encoded images and SVG.

### Method
POST

### Endpoint
/setImage

### Parameters
#### Request Body
- **event** (string) - Required - Must be 'setImage'.
- **context** (string) - Required - A unique identifier for the action instance whose image needs to be changed.
- **payload** (object) - Required - Contains the new image and targeting information.
  - **image** (string) - Required - The image data. Can be a base64 encoded image string (e.g., `data:image/png;base64,...`) or an SVG string (e.g., `data:image/svg+xml;charset=utf8,<svg>...</svg>`).
  - **target** (integer) - Optional - Specifies where the image should be displayed. Defaults to 0 (both hardware and software).
    - 0: Hardware and Software
    - 1: Only Hardware
    - 2: Only Software
  - **state** (integer) - Optional - A 0-based integer representing the state of the action. If omitted, the image is applied to all states.

### Request Example (PNG)
```json
{
    "event": "setImage",
    "context": "uniqueValue",
    "payload": {
        "image": "data:image/png;base64,avFOdwp0Ksgoe...",
        "target": 0,
        "state": 0
    }
}
```

### Request Example (SVG)
```json
{
    "event": "setImage",
    "context": "context",
    "payload": {
        "image": "data:image/svg+xml;charset=utf8,<svg></svg>",
        "target": 0
    }
}
```

### Response
#### Success Response (200)
An empty response or a success confirmation.

#### Response Example
(No specific response body format is defined for success, typically an acknowledgment).

```

--------------------------------

### Stream Deck Plugin Registration Function

Source: https://sdk.key123.vip/en/guide/property-inspector

Defines the standard JavaScript function used to register a Property Inspector with the Stream Dock application. This ensures compatibility with Elgato's ecosystem.

```javascript
// 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
);

```

--------------------------------

### Request Action Instance Settings

Source: https://sdk.key123.vip/en/guide/events-sent

Request persistent data stored for an action instance. Upon calling, the plugin or Property Inspector will asynchronously receive a didReceiveSettings event with the data.

```json
{
    "event": "getSettings",
    "context": uniqueValue
}
```

--------------------------------

### dialDown

Source: https://sdk.key123.vip/en/guide/events-received

Fired when a user presses down on a Stream Deck dial. Includes action, context, device, and payload with settings and coordinates.

```APIDOC
## dialDown

When the user presses the knob, the plugin will receive the event.

### Description

This event is triggered when a user presses down on a dial (encoder) on the Stream Deck hardware. It provides information about the action, context, device, and the current settings and coordinates associated with the dial press.

### Method

This is an event pushed from the Stream Dock application, not a direct API call.

### Endpoint

N/A (Event-driven)

### Parameters

#### Request Body

- **action** (string) - Required - Unique identifier for the action. Use this to determine which action was triggered if your plugin supports multiple actions.
- **event** (string) - Required - Must be `dialDown`.
- **context** (string) - Required - Value that identifies the instance action.
- **device** (string) - Required - Value used to identify the device.
- **payload** (object) - Required - A JSON object containing event-specific data.
    - **controller** (string) - Required - Indicates the type of controller, expected to be `Encoder` for dial events.
    - **settings** (object) - Required - This JSON object contains the persistent storage data for the action.
    - **coordinates** (object) - Required - Coordinates of the triggered action.
        - **column** (integer) - The column number of the action.
        - **row** (integer) - The row number of the action.

### Request Example

```json
{
  "action": "com.mirabox.demo.action2",
  "event": "dialDown",
  "context": "uniqueValue",
  "device": "uniqueValue",
  "payload": {
    "controller": "Encoder",
    "settings": {"dialSetting": "initialValue"},
    "coordinates": {
      "column": 0,
      "row": 0
    }
  }
}
```

### Response

This event does not typically expect a direct response from the plugin, but the plugin can react to the event by updating its state or UI.
```

--------------------------------

### JavaScript Internationalization in Property Inspector

Source: https://sdk.key123.vip/en/guide/i18n

Demonstrates how to dynamically load and apply translations in a JavaScript-based Property Inspector. It uses XMLHttpRequest to fetch the language JSON file and updates text content and input placeholders accordingly. Requires the `$local` flag to be true and the `$lang` variable to be populated.

```javascript
if (!$local) return;
    $lang = await new Promise(resolve => {
        const req = new XMLHttpRequest();
        req.open('GET', `../../${JSON.parse(app).application.language}.json`);
        req.send();
        req.onreadystatechange = () => {
            if (req.readyState === 4) {
                resolve(JSON.parse(req.responseText).Localization);
            }
        };
    });

    const walker = document.createTreeWalker($dom.main, NodeFilter.SHOW_TEXT, (e) => {
        return e.data.trim() && NodeFilter.FILTER_ACCEPT;
    });
    while (walker.nextNode()) {
        console.log(walker.currentNode.data);
        walker.currentNode.data = $lang[walker.currentNode.data];
    }
    // placeholder
    const translate = item => {
        if (item.placeholder?.trim()) {
            console.log(item.placeholder);
            item.placeholder = $lang[item.placeholder];
        }
    };
    $('input', true).forEach(translate);
    $('textarea', true).forEach(translate);
```

--------------------------------

### didReceiveSettings Event Structure

Source: https://sdk.key123.vip/en/guide/events-received

This event is received when the settings for an action change. It includes information about the action, context, device, and the new settings payload. The payload contains persistent data and coordinates.

```json
{
  "action": "com.mirabox.demo.action1", 
  "event": "didReceiveSettings", 
  "context": "uniqueValue", 
  "device": "uniqueValue", 
  "payload": {
   "settings": {<json data>},
    "coordinates": {
      "column": 3, 
      "row": 1 
    },
    "isInMultiAction": false
  }
}
```

--------------------------------

### Set Action Title with setTitle Event

Source: https://sdk.key123.vip/en/guide/events-sent

Enables plugins to dynamically change the title of an action instance. This event accepts a title, a target (software, hardware, or both), and an optional state.

```JSON
{
    "event": "setTitle",
    "context": uniqueValue,
    "payload": {
        "title": "MyTitle",
        "target": software, hardware or both,
        "state": 0-based integer
    }
}
```

--------------------------------

### keyDown Event Structure

Source: https://sdk.key123.vip/en/guide/events-received

This JSON structure represents the 'keyDown' event, occurring when a user presses a key. It includes action and device information, context, and a payload with settings, coordinates, state, and multi-action status.

```json
{
  "action": "com.mirabox.demo.action2",
  "event": "keyDown",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
    "state": 0,
    "isInMultiAction": false
  }
}
```

--------------------------------

### Vue Data Persistence in Property Inspector

Source: https://sdk.key123.vip/en/guide/property-inspector

Demonstrates how to persist plugin settings using Vue's reactivity system. Changes to the settings ref are automatically sent to the Stream Dock using the 'setSettings' event.

```vue
const preventWatch = ref(false);
const settings = ref(window.argv[4].payload.settings);
watch(
    settings,
    () => {
      if (preventWatch.value) return;
      server.send(
        JSON.stringify({
          event: 'setSettings',
          context: window.argv[1],
          payload: settings.value
        })
      );
    },
    { deep: true }
);

```

--------------------------------

### showAlert

Source: https://sdk.key123.vip/en/guide/events-sent

Displays a temporary alert icon on an action.

```APIDOC
## POST /showAlert

### Description
This event allows plugins to display a temporary alert icon on a specific action instance, providing visual feedback to the user.

### Method
POST

### Endpoint
/showAlert

### Parameters
#### Request Body
- **event** (string) - Required - Must be 'showAlert'.
- **context** (string) - Required - A unique identifier for the action instance where the alert should be shown.

### Request Example
```json
{
    "event": "showAlert",
    "context": "uniqueValue"
}
```

### Response
#### Success Response (200)
An empty response or a success confirmation.

#### Response Example
(No specific response body format is defined for success, typically an acknowledgment).

```
Tokens:
Raw