Elgato Stream Deck SDK

https://docs.elgato.com/streamdeck/sdk/
Admin
The Elgato Stream Deck SDK provides tools and documentation for developers to create, build, and...
Tokens:55,195
Snippets:511
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install latest SDK and CLI

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v3

Install the latest versions of the SDK and CLI.

```bash
npm i @elgato/streamdeck@latest @elgato/cli@latest
```

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

### Install @elgato/prettier-config

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Install the @elgato/prettier-config package as a devDependency.

```bash
npm install @elgato/prettier-config --save-dev
```

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

### Install Elgato ESLint and Prettier Configurations

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Install the Elgato ESLint and Prettier configurations as dev dependencies.

```bash
npm install @elgato/eslint-config @elgato/prettier-config --save-dev
```

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

### Install and verify Node.js with nvm

Source: https://docs.elgato.com/streamdeck/sdk/introduction/getting-started

Install Node.js version 24 using nvm, switch to it, and verify the installed version. Run these commands in sequence in your terminal.

```bash
nvm install 24
```

```bash
nvm use 24
```

```bash
node -v
```

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

### Install @elgato/eslint-config

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Install the @elgato/eslint-config package as a dev dependency.

```bash
npm install @elgato/eslint-config --save-dev
```

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

### Install @elgato/streamdeck v2

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Install the latest version of the @elgato/streamdeck package.

```bash
npm i @elgato/streamdeck@latest
```

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

### Log file format example

Source: https://docs.elgato.com/streamdeck/sdk/guides/logging

Shows the format of log entries: <iso_date> <log_level> [[scope]: ]<message>. The example shows a log entry with an ISO date, INFO level, and message.

```text
<iso_date> <log_level> [[scope]: ]<message>
```

```text
2024-05-05T12:35:13.000Z INFO  Hello world
```

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

### Install Stream Deck CLI with npm, yarn, or pnpm

Source: https://docs.elgato.com/streamdeck/sdk/introduction/getting-started

Install the Stream Deck CLI globally using npm, yarn, or pnpm. Choose one package manager; they are alternatives.

```bash
npm install -g @elgato/cli
```

```bash
yarn global add @elgato/cli
```

```bash
pnpm add -g @elgato/cli
```

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

### Start development watch command

Source: https://docs.elgato.com/streamdeck/sdk/introduction/getting-started

Run this command to start watching for changes. Changes to manifest.json or src are automatically reflected in Stream Deck; press Ctrl+C to stop.

```bash
npm run watch

```

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

### Example deep-link URL to send

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Example deep-link URL sent to the plugin with identifier com.elgato.hello-world. The path is URL-encoded and a fragment is included.

```text
streamdeck://plugins/message/com.elgato.hello-world/Hello%20world#Testing
```

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

### Expected log output from deep-link example

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Expected log output from the example event handler when receiving the deep-link URL streamdeck://plugins/message/com.elgato.hello-world/Hello%20world#Testing.

```text
Path = /Hello%20world
Fragment = Testing
```

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

### Annotated deep-link URL example

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Annotated example of a deep-link URL showing the path, query, and fragment components. The URL uses the plugin identifier com.elgato.hello-world.

```text
                                                              href
                                                   ┌───────────┴───────────┐
streamdeck://plugins/message/com.elgato.hello-world/hello?name=Elgato#waving
                                                   └─┬──┘ └────┬────┘ └─┬──┘
                                                    path      query    fragment
```

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

### Miscellaneous Utilities Import: Before and After

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Before and after examples for importing miscellaneous utilities. These are now imported from `@elgato/utils` instead of `@elgato/streamdeck`.

```typescript
import {
	Enumerable,
	EventEmitter,
	type EventsOf,
} from "@elgato/streamdeck";
```

```typescript
import {
	Enumerable,
	EventEmitter,
	type EventsOf,
} from "@elgato/utils";
```

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

### Active deep-link example

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Example of an active deep-link that brings Stream Deck's window to the foreground. This is the default behavior and is recommended for OAuth flows.

```text
streamdeck://plugins/message/com.elgato.hello-world/hello
```

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

### fr.json with custom Localization strings

Source: https://docs.elgato.com/streamdeck/sdk/guides/i18n

Updated version of the fr.json example that includes a Localization object with custom strings. Note: the file is named fr.json but contains German text; the example is for demonstration.

```json
{
    "Name": "Lautstärkeregler",
    "Description": "Übernehmen Sie die Kontrolle über Ihre Audiolautstärke",
    "com.example.volume.adjust": {
        "Name": "Lautstärkeregelung",
        "Tooltip": "Kontrollieren Sie Ihre Lautstärke",
        "States": [
            {
                "Name": "Stummschaltung aufheben"
            },
            {
                "Name": "Stumm"
            }
        ],
        "Encoder": {
            "TriggerDescription": {
                "LongTouch": "Stumm",
                "Push": "Stummschaltung umschalten",
                "Rotate": "Anpassen",
                "Touch": "Stummschaltung umschalten"
            }
        }
    },

    "Localization": {
        "More info": "Weitere Informationen",
        "Save": "Speichern",
        "Reset": "Zurücksetzen"
    }
}
```

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

### getSettings

Source: https://docs.elgato.com/streamdeck/sdk/guides/dials

Gets the settings associated with this action instance.

```APIDOC
## getSettings

### Description
Gets the settings associated with this action instance.

### Method
function getSettings(): Promise<TSettings>

### Parameters
None

### Response
Returns a Promise that resolves to the settings of type `TSettings`.
```

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

### getSettings

Source: https://docs.elgato.com/streamdeck/sdk/guides/neo-infobar

Gets the settings associated with this action instance.

```APIDOC
## getSettings

### Description
Gets the settings associated this action instance.

### Method
function

### Signature
`function getSettings(): Promise<TSettings>`

### Parameters
None

### Returns
- **TSettings** - The settings associated with the action instance.
```

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

### getSettings

Source: https://docs.elgato.com/streamdeck/sdk/guides/actions

Gets the settings associated with this action instance.

```APIDOC
## getSettings

### Description
Gets the settings associated with this action instance.

### Method
function getSettings(): Promise<TSettings>

### Parameters
None.

### Returns
Promise<TSettings> - A promise that resolves to the settings associated with the action instance.
```

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

### Manifest with localizable strings (volume controller)

Source: https://docs.elgato.com/streamdeck/sdk/guides/i18n

Example manifest for a volume controller plugin showing the strings that can be localized, including action-specific strings indexed by UUID.

```json
{
    // Some properties omitted for brevity...
    "Name": "Volume Controller",
    "Description": "Take control of your audio volume",
    "Actions": [
        {
            "UUID": "com.example.volume.adjust",
            "Name": "Volume control",
            "Tooltip": "Control your volume",
            "States": [
                {
                    "Name": "Unmute"
                },
                {
                    "Name": "Mute"
                }
            ],
            "Encoder": {
                "TriggerDescription": {
                    "LongTouch": "Mute",
                    "Push": "Toggle mute",
                    "Rotate": "Adjust",
                    "Touch": "Stummschaltung umschalten"
                }
            }
        }
    ]
}
```

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

### JSON Types Import: Before and After

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Before and after examples for importing JSON types. The types are now imported from `@elgato/utils` instead of `@elgato/streamdeck`.

```typescript
import type {
	JsonObject,
	JsonPrimitive,
	JsonValue
} from "@elgato/streamdeck";
```

```typescript
import type {
	JsonObject,
	JsonPrimitive,
	JsonValue
} from "@elgato/utils";
```

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

### Passive deep-link example with streamdeck=hidden

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Example of a passive deep-link that does not bring Stream Deck's window to the foreground. Requires the query string parameter streamdeck=hidden and Stream Deck 7.0 or higher.

```text
streamdeck://plugins/message/com.elgato.hello-world/hello?streamdeck=hidden
                                                          └───────┬───────┘
                                                          Passive deep-link
```

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

### Neo Infobar action with layouts

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v3

Example of a Neo Infobar action using layouts. Checks the action type with isNeoInfobar() and sets feedback layout and content.

```typescript
import { action, SingletonAction, WillAppearEvent } from "@elgato/streamdeck";

@action({ UUID: "com.elgato.example.neo-infobar" })
export class ExampleNeoInfobarAction extends SingletonAction {
	/**
	 * Occurs when the action appears.
	 */
	override async onWillAppear(ev: WillAppearEvent): Promise<void> {
		if (ev.action.isNeoInfobar()) {
			// Set the layout.
			await ev.action.setFeedbackLayout("layout.json");
			await ev.action.setFeedback({
				img: "logo",
				text: "Hello world",
			});
		}
	}
}
```

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

### Log an INFO message

Source: https://docs.elgato.com/streamdeck/sdk/guides/logging

Creates an INFO log entry. This is the example from the previous chapter, shown here to illustrate the INFO log level.

```javascript
streamDeck.logger.info("Hello world");
```

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

### getSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/plugin

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

```APIDOC
## getSettings

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

### Command
`getSettings`

### Parameters
- **context** (string) - Required - 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.
- **id** (string) - Optional - Optional identifier that can be used to identify the response to this request.

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

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

### Send to Property Inspector: Before and After

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Before and after examples for sending payloads to the property inspector. The new API removes the `.current?` optional chaining.

```typescript
import streamDeck from "@elgato/streamdeck";

streamDeck.ui.current?.sendToPropertyInspector({
	message: "Hello world",
});
```

```typescript
import streamDeck from "@elgato/streamdeck";

streamDeck.ui.sendToPropertyInspector({
	message: "Hello world",
});
```

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

### Log file path example

Source: https://docs.elgato.com/streamdeck/sdk/guides/logging

Shows the location of a plugin's log file within the plugin's logs directory. The path includes the plugin UUID and an index, with 0 being the most recent.

```text
com.elgato.hello-world.sdPlugin/logs/com.elgato.hello-world.0.log
└─────────┬──────────┘               └─────────┬──────────┘ └──┐
     Plugin UUID                          Plugin UUID        Index
```

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

### GetSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/ui

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

```APIDOC
## GetSettings

### Description
Gets the settings associated with an instance of an action. Causes `didReceiveSettings` to be emitted.

### Command
`getSettings`

### Parameters
- **action** (string) - Required - Identifies the action type, as specified by the UUID within the manifest.
- **context** (string) - Required - The action instance identifier.
- **event** ("getSettings") - Required - Name of the command.
- **id** (string) - Optional - Optional identifier that can be used to identify the response to this request.

### Request Example
```json
{
  "action": "com.example.action",
  "context": "actionInstanceId",
  "event": "getSettings",
  "id": "optionalId"
}
```
```

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

### Property Inspector Action: Before and After

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Before and after examples for accessing the current property inspector action. The new API uses the `.action` property instead of `.current`.

```typescript
import streamDeck from "@elgato/streamdeck";

streamDeck.ui.current;
```

```typescript
import streamDeck from "@elgato/streamdeck";

streamDeck.ui.action;
```

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

### Switch profile on key down

Source: https://docs.elgato.com/streamdeck/sdk/guides/profiles

Example of switching to a bundled profile when a key is pressed. The plugin can only switch to profiles distributed with the plugin, not user-defined profiles. The switchToProfile method is called with the device ID and the profile name.

```typescript
import streamDeck, { action, KeyDownEvent, SingletonAction } from "@elgato/streamdeck";

@action({ UUID: "com.elgato.example.action" })
export class IncrementCounter extends SingletonAction {
	/**
	 * Occurs when the user presses the key action.
	 */
	override onKeyDown(ev: KeyDownEvent<CounterSettings>): void | Promise<void> {
		streamDeck.profiles.switchToProfile(ev.device.id, "My Cool Profile"); 
	}
}

type CounterSettings = {
	count: number;
};
```

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

### Logging Level: Before and After

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v2

Before and after examples for setting the logger level. The new API uses a string literal instead of the `LogLevel` enum.

```typescript
import streamDeck, { LogLevel } from "@elgato/streamdeck";

streamDeck.logger.setLevel(LogLevel.TRACE);
```

```typescript
import streamDeck from "@elgato/streamdeck";

streamDeck.logger.setLevel("trace");
```

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

### Get global settings with sdpi-components

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/ui

Uses the Stream Deck Client provided by sdpi-components to retrieve global settings. The `getGlobalSettings()` method returns a promise that resolves with the settings object.

```javascript
SDPIComponents
	.streamDeckClient
	.getGlobalSettings()
	.then((settings) => {
		console.log(settings);
	});
```

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

### getGlobalSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/plugin

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

```APIDOC
## getGlobalSettings

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

### Command
`getGlobalSettings`

### Parameters
- **context** (string) - Required - 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.
- **id** (string) - Optional - Optional identifier that can be used to identify the response to this request.

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

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

### Layout JSON file for a Neo Infobar action

Source: https://docs.elgato.com/streamdeck/sdk/guides/neo-infobar

Example layout JSON for a Neo Infobar, rendering a title with images on both sides. Layout items must have unique 'key', defined 'type' and 'rect', not overlap on the same 'zOrder', and stay within the 232x50 pixel bounds.

```json
{
    "$schema": "https://schemas.elgato.com/streamdeck/plugins/layout.json",
    "id": "neo",
    "controller": "Neo",
    "items": [
        {
            "type": "pixmap",
            "key": "leading",
            "rect": [10, 15, 20, 20]
        },
        {
            "key": "title",
            "type": "text",
            "rect": [40, 15, 152, 20],
            "font": {
                "size": 15
            }
        },
        {
            "key": "trailing",
            "type": "pixmap",
            "rect": [202, 15, 20, 20]
        }
    ]
}
```

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

### GetGlobalSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/ui

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

```APIDOC
## GetGlobalSettings

### Description
Gets the global settings associated with the plugin. Causes `didReceiveGlobalSettings` to be emitted.

### Command
`getGlobalSettings`

### Parameters
- **context** (string) - Required - The plugin's identifier, as provided by Stream Deck.
- **event** ("getGlobalSettings") - Required - Name of the command.
- **id** (string) - Optional - Optional identifier that can be used to identify the response to this request.

### Request Example
```json
{
  "context": "pluginIdentifier",
  "event": "getGlobalSettings",
  "id": "optionalId"
}
```
```

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

### LogKeyPressAction event handlers

Source: https://docs.elgato.com/streamdeck/sdk/guides/actions

Example of a SingletonAction subclass that handles onWillAppear and onKeyDown events. The event parameter provides access to the action instance, device, and payload controller. Settings can be accessed via ev.payload.settings.

```TypeScript
import streamDeck, { action, type KeyDownEvent, SingletonAction, type WillAppearEvent } from "@elgato/streamdeck";

/**
 * An action that logs a key press.
 */
@action({ UUID: "com.elgato.hello-world.log" })
export class LogKeyPressAction extends SingletonAction {
	/**
	 * Handles the action appearing on the canvas.
	 * @param ev Information about the event.
	 */
	override onWillAppear(ev: WillAppearEvent): void | Promise<void> {
		ev.action; // instance of the action the event is for.
		ev.action.device; // device information.
		ev.payload.controller; // type of the action, i.e. key, or dial & touchscreen.

		// etc.
	}

	/**
	 * Handles the user pressing a Stream Deck key (pedal, G-key, etc).
	 * @param ev Information about the event.
	 */
	override onKeyDown(ev: KeyDownEvent): void | Promise<void> {
		streamDeck.logger.info(`Key pressed!`);
	}
}
```

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

### Settings events lifecycle - Before

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v3

Before the settings events lifecycle change: onDidReceiveGlobalSettings fires both when settings change and when getting settings.

```typescript
streamDeck.settings.onDidReceiveGlobalSettings((ev) => {
	// Fired when the settings change in the property inspector
	// and when getting the settings.
});

const settings = await streamDeck.settings.getGlobalSettings();
```

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

### Manifest JSON with TriggerDescription

Source: https://docs.elgato.com/streamdeck/sdk/guides/dials

Defines trigger descriptions for an encoder action in the manifest file using the Actions[].Encoder.TriggerDescription property. The example shows descriptions for Push, Rotate, Touch, and LongTouch.

```json
{
    "Actions": [
        {
            "Icon": "action-icon",
            "Name": "Trigger Description Example",
            "Controllers": ["Encoder"],
            "Encoder": {
                "layout": "$A1",

                "TriggerDescription": {
                    "Push": "Play / Pause",
                    "Rotate": "Adjust Volume",
                    "Touch": "Play / Pause",
                    "LongTouch": "Skip Track"
                }
            }
        }
    ]
    // ...
}
```

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

### Log at all levels with @elgato/streamdeck

Source: https://docs.elgato.com/streamdeck/sdk/guides/logging

Logs messages at all five log levels: error, warn, info, debug, and trace. The streamDeck.connect() call is included to complete the plugin setup.

```javascript
import streamDeck from "@elgato/streamdeck";

streamDeck.logger.error("Failures or exceptions");
streamDeck.logger.warn("Recoverable errors");
streamDeck.logger.info("Hello world");
streamDeck.logger.debug("Debugging information");
streamDeck.logger.trace("Detailed messages");

streamDeck.connect();
```

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

### Action class updating its layout to a custom layout file

Source: https://docs.elgato.com/streamdeck/sdk/guides/dials

TypeScript example using setFeedbackLayout to change the layout of a dial action at runtime. Checks if the action is a dial before calling the function.

```typescript
import { action, SingletonAction, WillAppearEvent } from "@elgato/streamdeck";

@action({ UUID: "com.elgato.test.one" })
export class IncrementCounter extends SingletonAction {
	/**
	 * Occurs when the action will appear.
	 */
	override async onWillAppear(ev: WillAppearEvent): Promise<void> {
		if (ev.action.isDial()) {
			// Specify built-in layout name (e.g. "$B1"), or path to the custom layout file.
			await ev.action.setFeedbackLayout("custom-layout.json"); 
		}
	}
}
```

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

### Create eslint.config.js with Recommended Config

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Create an eslint.config.js file at the root of your project to use the recommended ESLint configuration.

```javascript
import { config } from "@elgato/eslint-config";

export default config.recommended;
```

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

### Get macOS app CFBundleIdentifier with osascript

Source: https://docs.elgato.com/streamdeck/sdk/guides/app-monitoring

Finds the CFBundleIdentifier of a macOS application using osascript in the terminal. Replace "Application Name" with the actual app name to get the identifier used in ApplicationsToMonitor.

```bash
osascript -e 'id of app "Application Name"'
```

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

### Plugin file structure

Source: https://docs.elgato.com/streamdeck/sdk/introduction/getting-started

Directory tree of the scaffolded plugin, showing the .sdPlugin compiled output, source files, and configuration files.

```text
.
├── *.sdPlugin/
│   ├── bin/
│   ├── imgs/
│   ├── logs/
│   ├── ui/
│   │   └── increment-counter.html
│   └── manifest.json
├── src/
│   ├── actions/
│   │   └── increment-counter.ts
│   └── plugin.ts
├── package.json
├── rollup.config.mjs
└── tsconfig.json

```

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

### getResources

Source: https://docs.elgato.com/streamdeck/sdk/guides/actions

Gets the resources (files) associated with this action. Available from Stream Deck 7.1.

```APIDOC
## getResources

### Description
Gets the resources (files) associated with this action; these resources are embedded into the action when it is exported, either individually, or as part of a profile. Available from Stream Deck 7.1.

### Method
function getResources(): Promise<Resources>

### Parameters
None.

### Returns
Promise<Resources> - A promise that resolves to the resources associated with the action.
```

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

### getResources

Source: https://docs.elgato.com/streamdeck/sdk/guides/neo-infobar

Gets the resources (files) associated with this action. Available from Stream Deck 7.1.

```APIDOC
## getResources

### Description
Gets the resources (files) associated with this action; these resources are embedded into the action when it is exported, either individually, or as part of a profile.

### Method
function

### Signature
`function getResources(): Promise<Resources>`

### Parameters
None

### Returns
- **Resources** - The resources associated with the action.

### Availability
Stream Deck 7.1+
```

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

### Configure package.json for Linting

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Add a lint script and configure Prettier in package.json.

```json
{
	"scripts": {
		"lint": "eslint --max-warnings 0"
	},
	"prettier": "@elgato/prettier-config"
}
```

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

### Settings events lifecycle - Now

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v3

Now: onDidReceiveGlobalSettings only fires when settings change in the property inspector, not when getting settings.

```typescript
streamDeck.settings.onDidReceiveGlobalSettings((ev) => {
	// Fired when the settings change in the property inspector.
});

const settings = await streamDeck.settings.getGlobalSettings();
```

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

### Run ESLint with --max-warnings 0

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Run ESLint from the terminal with the --max-warnings 0 flag to fail on any warnings.

```bash
eslint --max-warnings 0
```

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

### Listen for application launch with onApplicationDidLaunch

Source: https://docs.elgato.com/streamdeck/sdk/guides/app-monitoring

Subscribes to the onApplicationDidLaunch event to handle when a registered application launches. The callback receives an ApplicationDidLaunchEvent and logs the application name via streamDeck.logger.info.

```typescript
import streamDeck, { ApplicationDidLaunchEvent } from "@elgato/streamdeck";

streamDeck.system.onApplicationDidLaunch((ev: ApplicationDidLaunchEvent) => {
	// Handle a registered application launching
	streamDeck.logger.info(ev.application); // e.g. "Elgato Wave Link.exe"
});
```

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

### didReceiveSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/ui

Documentation for the didReceiveSettings event, which is triggered when settings are requested or updated.

```APIDOC
## didReceiveSettings

### Description
Occurs when the settings associated with an action instance are requested, or when the settings were updated by the plugin.

### Event
`didReceiveSettings`

### Payload

#### MultiActionPayload
- **controller** ("Keypad") - Required - Defines the controller type of the action. `Keypad` refers to a standard key action on a Stream Deck device.
- **isInMultiAction** (true) - Required - Determines whether the action is part of a multi-action. Requires Stream Deck 6.7.
- **settings** (JsonObject) - Required - Settings associated with the action instance.
- **state** (number) - Optional - Current state of the action; only applicable to actions that support multiple states.

#### SingleActionPayload
- **controller** (Controller) - Required - Defines the controller type of the action. `Keypad` refers to a standard key action on a Stream Deck device. `Encoder` refers to a dial / touchscreen on the Stream Deck +.
- **coordinates** (Coordinates) - Required - Coordinates that identify the location of the action.
  - **column** (number) - Required - Column the action instance is located on; indexed from 0.
  - **row** (number) - Required - Row the action instance is located on; indexed from 0.
- **isInMultiAction** (false) - Required - Determines whether the action is part of a multi-action. Requires Stream Deck 6.7 when accessed from the property inspector.
- **settings** (JsonObject) - Required - Settings associated with the action instance.
- **state** (number) - Optional - Current state of the action; only applicable to actions that support multiple states.

### Common Fields
- **action** (string) - Required - Identifies the action type, as specified by the UUID within the manifest.
- **context** (string) - Required - Identifier for the instance of the action the event is for.
- **device** (string) - Required - Identifier for the Stream Deck device the action is on.
- **event** ("didReceiveSettings") - Required - Name of the event.
- **payload** (ActionPayload) - Required - Additional information about the action.
```

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

### switchToProfile

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/plugin

Documentation for the switchToProfile command, which switches to a profile on a specified device.

```APIDOC
## switchToProfile

### Description
Switches to the profile, as distributed by the plugin, on the specified device. Plugins may only switch to profiles distributed with the plugin, as defined within the manifest, and cannot access user-defined profiles.

### Event
`switchToProfile`

### Parameters

#### context (string, required)
Defines the context of the command, e.g. which action instance the command is intended for.

#### device (string, required)
Unique identifier of the device where the profile should be set.

#### event ("switchToProfile", required)
Name of the command, used to identify the request.

#### payload (TPayload, required)
Additional information supplied as part of the command.

##### payload.page (number, optional)
Optional page to show when switching to the profile, indexed from 0. When `undefined`, the page that was previously visible (when switching away from the profile) will be made visible.

##### payload.profile (string, optional)
Name of the profile to switch to; the name must be identical to the one provided in the manifest. When not specified, Stream Deck will switch to the previous profile.

### Example
```typescript
type SwitchToProfile = {
    context: string;
    device: string;
    event: "switchToProfile";
    payload: {
        page?: number;
        profile?: string;
    };
};
```
```

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

### streamDeck.devices.onDeviceDidChange

Source: https://docs.elgato.com/streamdeck/sdk/guides/devices

Registers a callback that is invoked when a Stream Deck device changes, for example its name or size. The callback receives a DeviceDidChangeEvent containing the changed device.

```APIDOC
## [SDK] streamDeck.devices.onDeviceDidChange

### Description
Registers a callback that is invoked when a Stream Deck device changes, for example its name or size. The callback receives a `DeviceDidChangeEvent` containing the changed device.

### Method
Event subscription

### Endpoint
`streamDeck.devices.onDeviceDidChange(callback)`

### Parameters
- **callback** (function) - Required - Callback function that receives a `DeviceDidChangeEvent`.

### Request Example
```typescript
import streamDeck, { type DeviceDidChangeEvent } from "@elgato/streamdeck";

streamDeck.devices.onDeviceDidChange((ev: DeviceDidChangeEvent) => {
	const { id, isConnected, name, size, type } = ev.device;

	streamDeck.logger.info(name);
});
```

### Response
#### Success Response
- **ev** (DeviceDidChangeEvent) - Event object containing the changed device.
  - **device** (Device) - The changed device with properties `id`, `isConnected`, `name`, `size`, `type`.

#### Response Example
```typescript
// Example usage
streamDeck.devices.onDeviceDidChange((ev) => {
	const { id, isConnected, name, size, type } = ev.device;
	streamDeck.logger.info(name);
});
```
```

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

### showOk

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/plugin

Temporarily shows an "OK" (i.e. success), in the form of a check-mark in a green circle, on the action instance. Used to provide visual feedback when an action successfully executed.

```APIDOC
## showOk

### Description
Temporarily shows an "OK" (i.e. success), in the form of a check-mark in a green circle, on the action instance. Used to provide visual feedback when an action successfully executed.

### Event
`showOk`

### Parameters
- **context** (string) - Required - Defines the context of the command, e.g. which action instance the command is intended for.
- **event** ("showOk") - Required - Name of the command, used to identify the request.

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

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

### getResources

Source: https://docs.elgato.com/streamdeck/sdk/guides/dials

Gets the resources (files) associated with this action; these resources are embedded into the action when it is exported, either individually, or as part of a profile. Available from Stream Deck 7.1.

```APIDOC
## getResources

### Description
Gets the resources (files) associated with this action; these resources are embedded into the action when it is exported, either individually, or as part of a profile. Available from Stream Deck 7.1.

### Method
function getResources(): Promise<Resources>

### Parameters
None

### Response
Returns a Promise that resolves to a `Resources` object containing the resources associated with the action.
```

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

### Format files with Prettier CLI

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Run Prettier in write mode to format all files in the project.

```bash
prettier . --write
```

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

### getResources

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/plugin

Gets the resources (files) associated with the action; these resources are embedded into the action when it is exported, either individually, or as part of a profile. Available from Stream Deck 7.1.

```APIDOC
## getResources

### Description
Gets the resources (files) associated with the action; these resources are embedded into the action when it is exported, either individually, or as part of a profile. Available from Stream Deck 7.1.

### Command
`getResources`

### Parameters
- **context** (string) - Required - Defines the context of the command, e.g. which action instance the command is intended for.
- **event** ("getResources") - Required - Name of the command, used to identify the request.
- **id** (string) - Optional - Optional identifier that can be used to identify the response to this request.

### Request Example
```json
{
  "context": "string",
  "event": "getResources",
  "id": "string"
}
```
```

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

### GetResources

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/ui

Gets the resources (files) associated with the action; these resources are embedded into the action when it is exported, either individually, or as part of a profile. Available from Stream Deck 7.1.

```APIDOC
## GetResources

### Description
Gets the resources (files) associated with the action; these resources are embedded into the action when it is exported, either individually, or as part of a profile. Available from Stream Deck 7.1.

### Command
`getResources`

### Parameters
- **action** (string) - Required - Identifies the action type, as specified by the UUID within the manifest.
- **context** (string) - Required - Defines the context of the command, e.g. which action instance the command is intended for.
- **event** ("getResources") - Required - Name of the command, used to identify the request.
- **id** (string) - Optional - Optional identifier that can be used to identify the response to this request.

### Request Example
```json
{
  "action": "com.example.action",
  "context": "actionInstanceId",
  "event": "getResources",
  "id": "optionalId"
}
```
```

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

### onDidReceiveSettings

Source: https://docs.elgato.com/streamdeck/sdk/guides/dials

Event handler for settings updates in the property inspector.

```APIDOC
## onDidReceiveSettings

### Description
Occurs when the settings are updated within the property inspector. When `streamDeck.settings.useLegacySettingsBehavior` is set to `true`, this also fires after calling `getSettings()`.

### Method
Event handler method on `SingletonAction` class.

### Signature
`function onDidReceiveSettings?(ev: DidReceiveSettingsEvent): void | Promise<void>`

### Parameters
- **ev** (DidReceiveSettingsEvent) - Required - Information about the event, including the source action and contextual payload information.

```

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

### didReceiveSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/plugin

Documentation for the didReceiveSettings event, including its payload structure and field descriptions.

```APIDOC
## didReceiveSettings

### Description
Occurs when the settings associated with an action instance are requested, or when the settings are updated in the property inspector.

### Event
`didReceiveSettings`

### Payload

#### 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** (true) - Required - Determines whether the action is part of a multi-action. NB. Requires Stream Deck 6.7 when accessed from the property inspector.
- **resources** (Resources) - Required - Resources (files) associated with the action. Available from Stream Deck 7.1.
- **settings** (JsonObject) - Required - Settings associated with the action instance.
- **state** (number) - Optional - Current state of the action; only applicable to actions that have multiple states defined within the `manifest.json` file.

#### SingleActionPayload
- **controller** (Controller) - 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 +.
- **coordinates** (Coordinates) - Required - Coordinates that identify the location of an action.
  - **column** (number) - Required - Column the action instance is located in, indexed from 0.
  - **row** (number) - Required - Row the action instance is located on, indexed from 0. Note: When the device is Stream Deck +, the row can be 0 for keys (`Keypad`), and will _always_ be 0 for dials (`Encoder`); to differentiate between actions types, cross-check the `controller`.
- **isInMultiAction** (false) - Required - Determines whether the action is part of a multi-action. NB. Requires Stream Deck 6.7 when accessed from the property inspector.
- **resources** (Resources) - Required - Resources (files) associated with the action. Available from Stream Deck 7.1.
- **settings** (JsonObject) - Required - Settings associated with the action instance.
- **state** (number) - Optional - Current state of the action; only applicable to actions that have multiple states defined within the `manifest.json` file.

### Example
```typescript
type DidReceiveSettings = {
    action: string;
    context: string;
    device: string;
    event: "didReceiveSettings";
    id?: string;
    payload:
        | {
              controller: "Keypad";
              isInMultiAction: true;
              resources: {
                  [key: string]: string;
              };
              settings: JsonObject;
              state?: number;
          }
        | {
              controller: "Encoder" | "Keypad" | "Neo";
              coordinates: {
                  column: number;
                  row: number;
              };
              isInMultiAction: false;
              resources: {
                  [key: string]: string;
              };
              settings: JsonObject;
              state?: number;
          };
};
```
```

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

### Configure Prettier in package.json

Source: https://docs.elgato.com/streamdeck/sdk/style-guide/linting

Add this entry to your package.json to use the Elgato Prettier configuration.

```json
"prettier": "@elgato/prettier-config"
```

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

### Reading custom localizations with streamDeck.i18n.translate

Source: https://docs.elgato.com/streamdeck/sdk/guides/i18n

Shows how to read custom strings using the streamDeck.i18n.translate function. The function returns the key if no localization is found for the requested language, as shown by the Spanish example where es.json is not defined.

```javascript
import streamDeck from "@elgato/streamdeck";

streamDeck.i18n.translate("More info");
// Output: "More info"

streamDeck.i18n.translate("More info", "de");
// Output: "Weitere Informationen"

streamDeck.i18n.translate("More info", "es");
// Output: "More info", es.json is not defined
```

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

### Layout $X1 (Icon)

Source: https://docs.elgato.com/streamdeck/sdk/guides/dials

Pre-defined layout for the Stream Deck + touch strip. Displays a title text and an icon pixmap.

```json
{
    "$schema": "https://schemas.elgato.com/streamdeck/plugins/layout.json",
    "id": "$X1",
    "items": [
        {
            "key": "title",
            "type": "text",
            "rect": [16, 10, 136, 24],
            "font": { "size": 16, "weight": 600 },
            "alignment": "left"
        },
        {
            "key": "icon",
            "type": "pixmap",
            "rect": [76, 40, 48, 48]
        }
    ]
}
```

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

### npm scripts in package.json

Source: https://docs.elgato.com/streamdeck/sdk/introduction/getting-started

Pre-populated npm scripts for building and watching the plugin. The watch script uses the streamdeck restart command with a placeholder for your plugin UUID.

```json
{
	"scripts": {
		"build": "rollup -c",
		"watch": "rollup -c -w --watch.onEnd=\"streamdeck restart {{YOUR_PLUGIN_UUID}}\"",
	},
	// ...
}

```

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

### Define a Neo Infobar action in the manifest

Source: https://docs.elgato.com/streamdeck/sdk/guides/neo-infobar

Manifest definition for a Neo Infobar action. The 'Controllers' property must include 'Neo' for the action to appear on Stream Deck Neo. Requires Stream Deck 7.6 or later in the manifest's 'Software.MinimumVersion'.

```json
{
	"Actions": [
		{
			"Name": "Neo Infobar Example Action",
			"UUID": "com.elgato.example.neo-infobar",
			"Controllers": ["Neo"] 
		}
	]
}
```

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

### Action class updating trigger description with setTriggerDescription

Source: https://docs.elgato.com/streamdeck/sdk/guides/dials

Shows how to programmatically update trigger descriptions using the setTriggerDescription function in an action class. The example updates descriptions for push, rotate, touch, and longTouch events.

```typescript
import { action, DialUpEvent, SingletonAction } from "@elgato/streamdeck";

@action({ UUID: "com.elgato.trigger-description-example.increment" })
export class IncrementCounter extends SingletonAction<CounterSettings> {
	/**
	 * Occurs when the user releases a dial.
	 */
	override async onDialUp(ev: DialUpEvent<CounterSettings>): Promise<void> {

		await ev.action.setTriggerDescription({
			push: "Increment counter",
			rotate: "Adjust increment",
			touch: "Increment counter",
			longTouch: "Reset counter",
		});
	}
}

/**
 * Settings for {@link IncrementCounter}.
 */
type CounterSettings = {
	count?: number;
	incrementBy?: number;
};
```

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

### Action class with onKeyDown handler

Source: https://docs.elgato.com/streamdeck/sdk/guides/actions

Defines an action class that inherits from SingletonAction and overrides the onKeyDown method to handle key press events. The @action decorator specifies the action's UUID. This example logs a message when a key is pressed.

```typescript
import streamDeck, { action, type KeyDownEvent, SingletonAction } from "@elgato/streamdeck";

/**
 * An action that logs a Stream Deck key press.
 */
@action({ UUID: "com.elgato.hello-world.log" })
export class LogKeyPressAction extends SingletonAction {
	/**
	 * Handles the user pressing a Stream Deck key (pedal, G-key, etc).
	 * @param ev Information about the event.
	 */
	override onKeyDown(ev: KeyDownEvent): void | Promise<void> {
		streamDeck.logger.info(`Key pressed!`);
	}
}
```

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

### SetSettings

Source: https://docs.elgato.com/streamdeck/sdk/references/websocket/ui

Sets the settings associated with an action instance, and notifies the plugin by emitting `didReceiveSettings`.

```APIDOC
## SetSettings

### Description
Sets the settings associated with an action instance, and notifies the plugin by emitting `didReceiveSettings`.

### Command
`setSettings`

### Parameters
- **action** (string) - Required - Identifies the action type, as specified by the UUID within the manifest.
- **context** (string) - Required - The action instance identifier.
- **event** ("setSettings") - Required - Name of the command.
- **payload** (JsonObject) - Required - Action settings to save.

### Request Example
```json
{
  "action": "com.example.action",
  "context": "actionInstanceId",
  "event": "setSettings",
  "payload": {}
}
```
```

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

### Access visible actions of a specific type with this.actions

Source: https://docs.elgato.com/streamdeck/sdk/guides/actions

Shows how to access visible actions of a specific action type using the `this.actions` property inside a SingletonAction class. The example iterates over actions with the UUID "com.elgato.hello-world.increment" and sets their title.

```typescript
import { action, KeyDownEvent, SingletonAction } from "@elgato/streamdeck";

/**
 * Example of accessing the visible actions of a specific action type.
 */
@action({ UUID: "com.elgato.hello-world.increment" })
export class IncrementCounter extends SingletonAction {
	/**
	 * Occurs when the user presses the key.
	 */
	override onKeyDown(ev: KeyDownEvent) {
		// Iterate over visible actions with the UUID "com.elgato.hello-world.increment".

		this.actions.forEach((action) => {
			ev.action.setTitle("Hello world!");
		});
	}
}
```

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

### KeyAction with settings type (Now)

Source: https://docs.elgato.com/streamdeck/sdk/releases/upgrading/v3

In v3, when referencing Action, KeyAction, DialAction, or NeoInfobarAction, the associated settings type must always be specified.

```typescript
import type { KeyAction } from "@elgato/streamdeck";

type Settings = {
	count: number;
};

const action: KeyAction<Settings>; 
```

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

### Create a scoped logger

Source: https://docs.elgato.com/streamdeck/sdk/guides/logging

Creates a scoped logger named "Main" and logs an info message. The output shows the log entry with the scope name in the log file.

```typescript
import streamDeck from "@elgato/streamdeck";

const scopedLogger = streamDeck.logger.createScope("Main");
scopedLogger.info("Hello world");

streamDeck.connect();
```

```log
2024-05-05T12:35:13.000Z INFO  Main: Hello world
```

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

### Register deep-link event handler with onDidReceiveDeepLink

Source: https://docs.elgato.com/streamdeck/sdk/guides/deep-linking

Registers a callback for inbound deep-link messages using the onDidReceiveDeepLink event handler in the system namespace. The handler receives an event object with the deep-link URL; the plugin must call streamDeck.connect() to start receiving messages.

```javascript
import streamDeck from "@elgato/streamdeck";

streamDeck.system.onDidReceiveDeepLink((ev) => {
	// Handle the deep-link message
});

streamDeck.connect();
```

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

### setSettings

Source: https://docs.elgato.com/streamdeck/sdk/guides/neo-infobar

Sets the settings associated with this action instance.

```APIDOC
## setSettings

### Description
Sets the settings associated with this action instance.

### Method
function

### Signature
`function setSettings(value: TSettings): Promise<void>`

### Parameters
- **value** (TSettings) - Required - Settings to persist.
```

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

### setSettings

Source: https://docs.elgato.com/streamdeck/sdk/guides/dials

Sets the settings associated with this action instance.

```APIDOC
## setSettings

### Description
Sets the settings associated with this action instance.

### Method
function setSettings(value: TSettings): Promise<void>

### Parameters
- **value** (TSettings) - Required - Settings to persist.

### Response
Returns a Promise that resolves when the settings are set.
```
Tokens:
Raw