### Install and Configure Node.js

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

Commands to install and verify the required Node.js version using nvm.

```bash
nvm install 24
```

```bash
nvm use 24
```

```bash
node -v
```

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

### Get Global Settings using sdpi-components

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

Retrieve global settings for the plugin using the `sdpi-components` library. This example demonstrates how to access settings asynchronously via a Promise.

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

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

### Install Prettier Configuration

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

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

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

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

### Install ESLint and Prettier Configurations

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

Install the Elgato ESLint and Prettier configurations as development dependencies using npm.

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

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

### Plugin Build Scripts

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

Example configuration for build and watch scripts in package.json.

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

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

### Install ESLint Configuration

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 Stream Deck CLI

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

Global installation commands for the Stream Deck CLI using various package managers.

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

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

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

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

### Getting Global Settings

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

An example using `sdpi-components` to retrieve global settings from Stream Deck within the property inspector.

```APIDOC
## Get Global Settings in the Property Inspector

### Description
This snippet shows how to use the `sdpi-components` library to fetch the global settings configured for the plugin from Stream Deck.

### Method
JavaScript (Client-side)

### Endpoint
N/A (Internal SDK method)

### Parameters
None

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

### Response
#### Success Response (Promise resolves with settings)
- **settings** (object) - An object containing the global settings for the plugin.

### Response Example
```json
{
  "someSetting": "value",
  "anotherSetting": 123
}
```
```

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

### Example Manifest JSON File

Source: https://docs.elgato.com/streamdeck/sdk/references/manifest

An example of a manifest JSON file referencing the schema URL and including basic plugin information.

```json
{
	"$schema": "https://schemas.elgato.com/streamdeck/plugins/manifest.json",
	"Author": "Elgato",
	"Name": "Test Plugin"
	// ...
}
```

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

### Stream Deck Plugin URL Examples

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

Examples of deep-link and proxy-based URLs for a sample plugin identifier.

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

```text
https://oauth2-redirect.elgato.com/streamdeck/plugins/message/com.elgato.hello-world/auth
```

```text
https%3A%2F%2Foauth2-redirect.elgato.com%2Fstreamdeck%2Fplugins%2Fmessage%2Fcom.elgato.hello-world%2Fauth
```

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

### Passive Deep-Link Example

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

Demonstrates a passive deep-link, which does not bring the Stream Deck window to the foreground. Use the `streamdeck=hidden` query parameter. Recommended for setup operations.

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

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

### Example Manifest with Localized Strings

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

Demonstrates how to define manifest strings, including those for actions and their states, in a JSON format.

```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"
                }
            }
        }
    ]
}
```

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

### Configure Property Inspector HTML

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

Examples for including the SDPI components script and initializing the streamDeckClient to set settings.

```html
<!doctype html>
<html>

<head lang="en">
    <meta charset="utf-8" />

    <script src="sdpi-components.js"></script>
</head>

<body>

    <script>
        const { streamDeckClient } = SDPIComponents;

        streamDeckClient.setSettings({
            name: "John Doe",
            showName: true,
            favColor: "green",
        });
    </script>
</body>

</html>
```

```html
<!doctype html>
<html>

<head lang="en">
    <meta charset="utf-8" />

    <script src="https://sdpi-components.dev/releases/v4/sdpi-components.js"></script>
</head>

<body>

    <script>
        const { streamDeckClient } = SDPIComponents;

        streamDeckClient.setSettings({
            name: "John Doe",
            showName: true,
            favColor: "green",
        });
    </script>
</body>

</html>
```

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

### 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 this action instance.

### Method
GET (or equivalent function call)

### Endpoint
N/A (Function Call)

### Response
#### Success Response (200)
- **value** (JsonObject) - The settings for this action instance.

### Response Example
```json
{
  "setting1": "value1",
  "setting2": 123
}
```
```

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

### Install Stream Deck SDK

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

Update the SDK dependency to the latest version via npm.

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

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

### Active Deep-Link Example

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

An example of an active deep-link that brings the Stream Deck window to the foreground. Recommended for OAuth flows.

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

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

### Define resource map structure

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

Examples of the required map structure for resource file paths before and after import.

```json
{
    fileOne: "C:\\audio\\track.mp3",
    fileTwo: "C:\\config.json"
}
```

```json
{
    fileOne: "C:\\...\\7ae61d68-6882-41dd-8e90-3c54114fa2cf\\track.mp3",
    fileTwo: "C:\\...\\7ae61d68-6882-41dd-8e90-3c54114fa2cf\\config.json"
}
```

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

### Example Deep-Link URL Breakdown

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

Illustrates how a sample deep-link URL is parsed into its path, query, and fragment components.

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

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

### Use Typed Global Settings

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

Enhance intellisense and type safety when getting global settings by providing a type definition. This example tracks the count of deep-link messages received.

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

// Define a type that represents the settings.
type Settings = {
	count: number;
};

streamDeck.system.onDidReceiveDeepLink(async (ev) => {
	// When getting the settings, supply the type.
	let { count = 0 } = await streamDeck.settings.getGlobalSettings<Settings>();

	count++;
	await streamDeck.settings.setGlobalSettings({ count });
});

streamDeck.connect();
```

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

### Handle Application Launch Event

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

Subscribe to the 'onApplicationDidLaunch' event to receive notifications when a registered application starts. Log the application identifier upon launch.

```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"
});
```

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

### Pack Plugin Directory

Source: https://docs.elgato.com/streamdeck/sdk/introduction/distribution

Use the 'pack' command from the Stream Deck CLI to package your plugin's .sdPlugin directory into a distributable .streamDeckPlugin installer file. This command validates and bundles your plugin's contents.

```bash
# Pack the *.sdPlugin directory
streamdeck pack com.elgato.hello-world.sdPlugin
```

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

### Define Layout JSON

Source: https://docs.elgato.com/streamdeck/sdk/references/touch-strip-layout

Example structure for a custom layout JSON file using the $schema property.

```json
{
	"$schema": "https://schemas.elgato.com/streamdeck/plugins/layout.json",
	"id": "CustomLayout",
	"items": [
		// ...
	]
}
```

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

### Run Plugin in Watch Mode

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

Starts the development watch process to automatically rebuild and reload the plugin.

```bash
npm run watch
```

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

### Command: 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
## Command: getGlobalSettings

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

### Parameters
- **context** (string) - Required - Defines the context of the command.
- **event** ("getGlobalSettings") - Required - Name of the command.
- **id** (string) - Optional - Identifier that can be used to identify the response to this request.

### Request Example
{
    "context": "plugin_context",
    "event": "getGlobalSettings",
    "id": "request_id"
}
```

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

### Example Deep-Link Message Submission

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

Shows the URL to submit to a plugin with UUID `com.elgato.hello-world` to trigger the deep-link handler.

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

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

### Command: GetGlobalSettings

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

Gets the global settings associated with the plugin. This command causes the `didReceiveGlobalSettings` event to be emitted.

```APIDOC
## Command: GetGlobalSettings

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

### Method
Send to Stream Deck

### Event
getGlobalSettings

### Fields
- **context** (string) - Required - The plugin's identifier, as provided by Stream Deck.
- **event** (string) - Required - Name of the command ('getGlobalSettings').
```

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

### Start Watching for File Changes (pnpm)

Source: https://docs.elgato.com/streamdeck/sdk/introduction/your-first-changes

Run this command in your terminal to enable hot-reloading for your Stream Deck plugin when using pnpm.

```bash
pnpm watch
```

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

### Configure Prettier with .prettierrc.js

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

Override default Prettier configurations by creating a .prettierrc.js file. This example demonstrates how to prefer spaces over tabs and set the tab width to 2.

```javascript
module.exports = {
	...require("@elgato/prettier-config"),
	tabWidth: 2,
	useTabs: false,
};
```

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

### Start Watching for File Changes (yarn)

Source: https://docs.elgato.com/streamdeck/sdk/introduction/your-first-changes

Run this command in your terminal to enable hot-reloading for your Stream Deck plugin when using yarn.

```bash
yarn watch
```

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

### Create New Plugin

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

Initializes the plugin creation wizard.

```bash
streamdeck create
```

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

### Configure ESLint with Elgato Recommended Settings

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 from Elgato.

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

export default config.recommended;
```

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

### Build Plugin Commands

Source: https://docs.elgato.com/streamdeck/sdk/introduction/your-first-changes

Commands to build the plugin using different package managers.

```bash
npm run build
```

```bash
yarn build
```

```bash
pnpm build
```

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

### Get action settings

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

Retrieves the settings associated with the current action instance.

```typescript
function getSettings<U extends JsonObject>(): Promise<U>
```

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

### getResources

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

Gets the resources (files) associated with this action. These resources are embedded into the action when it is exported.

```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
GET (or equivalent function call)

### Endpoint
N/A (Function Call)

### Response
#### Success Response (200)
- **resources** (Resources) - A map of file paths representing the action's resources.

### Response Example
```json
{
  "resource1.png": "/path/to/resource1.png",
  "resource2.json": "/path/to/resource2.json"
}
```
```

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

### Command: 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.

```APIDOC
## Command: 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.

### Method
Send to Stream Deck

### Event
getResources

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

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

### Action Key Image Manipulation

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

Demonstrates how to set the image for an action key, with options to specify the target (hardware, software, or both) and the state.

```APIDOC
## POST /actions/{actionUUID}/image

### Description
Sets the image to be displayed for this action instance. This can only be done by the plugin when the user has not specified a custom image.

### Method
POST

### Endpoint
`/actions/{actionUUID}/image`

### Parameters
#### Path Parameters
- **actionUUID** (string) - Required - The UUID of the action to update.

#### Request Body
- **image** (string) - Optional - The image to display. Can be a local file path, a base64 encoded string, or an SVG string. If undefined, the manifest image is used.
- **options** (object) - Optional - Additional options for rendering the image.
  - **target** (string) - Optional - Specifies where the image should be rendered (e.g., `Target.HardwareAndSoftware`).
  - **state** (number) - Optional - The state of the key to apply the image to (0 or 1).

### Request Example
```json
{
  "image": "imgs/actions/counter/key.png",
  "options": {
    "target": "hardware_and_software",
    "state": 1
  }
}
```

### Response
#### Success Response (200)
- **None** - The operation is asynchronous and does not return data upon success.

#### Response Example
(No response body on success)
```

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

### Get action resources

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

Retrieves files embedded with the action. Available from Stream Deck 7.1.

```typescript
function getResources(): Promise<Resources>
```

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

### Action Key Commands

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

Provides information on available commands for action keys, including methods for managing resources, settings, images, and states.

```APIDOC
## Commands Available to Key Actions

### getResources

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

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

### getSettings

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

#### Method Signature
`getSettings<U extends JsonObject>(): Promise<U>`

### setImage

#### Description
Sets the image to be displayed for this action instance. The image can only be set by the plugin when the user has not specified a custom image.

#### Method Signature
`setImage(image?: string, options?: ImageOptions): Promise<void>`

#### Parameters
- **image** (string) - Optional - The image to display. Can be a local file path, a base64 encoded string, or an SVG string. If undefined, the manifest image is used.
- **options** (ImageOptions) - Optional - Additional options that define where and how the image should be rendered.

### setResources

#### Description
Sets the resources (files) associated with this action. Available from Stream Deck 7.1.

#### Method Signature
`setResources(resources: Resources): Promise<void>`

#### Parameters
- **resources** (Resources) - Required - The resources as a map of file paths.

### setSettings

#### Description
Sets the settings associated with this action instance. Use in conjunction with `Action.getSettings`.

#### Method Signature
`setSettings<U extends JsonObject>(value: U): Promise<void>`

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

### setState

#### Description
Sets the current state of this action instance. Only applies to actions with multiple states defined in the manifest.

#### Method Signature
`setState(state: number): Promise<void>`

#### Parameters
- **state** (number) - Required - State to set; this can be either 0 or 1.
```

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

### GetSettings

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

Retrieves the settings associated with a specific action instance.

```APIDOC
## GET getSettings

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

### Request Body
- **action** (string) - Required - Identifies the action type, as specified by the UUID within the manifest.
- **context** (string) - Required - The action instance identifier.
- **event** (string) - Required - Name of the command ("getSettings").

### Request Example
{
	"action": "com.example.action",
	"context": "instance-id",
	"event": "getSettings"
}
```

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

### ShowOk

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

Temporarily shows an OK success indicator on the action instance.

```APIDOC
## ShowOk

### Description
Temporarily shows an "OK" (success) indicator on the action instance.

### Request Body
- **context** (string) - Required - Defines the context of the command.
- **event** (string) - Required - Must be "showOk".
```

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

### View Plugin File Structure

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

Displays the standard directory layout of a scaffolded Stream Deck plugin.

```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
```

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

### Get macOS Application Identifier

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

Use this terminal command to find the CFBundleIdentifier for macOS applications, which is required for monitoring.

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

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

### Logged Output from Deep-Link Message

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

The expected log output when the example deep-link message is received and processed by the event handler.

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

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

### showOk

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

Displays a success indicator on the action instance.

```APIDOC
## showOk

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

### Response
- **Promise<void>** - Returns a promise that resolves when the success indicator is displayed.
```

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

### Get Global Settings in Plugin

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

Retrieve global settings within a Stream Deck plugin. Ensure `streamDeck.connect()` is called to establish the connection.

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

streamDeck.system.onDidReceiveDeepLink(async (ev) => {
	// Get the settings.
	const settings = await streamDeck.settings.getGlobalSettings();
});

streamDeck.connect();
```

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

### Handle System Wake Event

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

Listen for the `onSystemDidWakeUp` event to restore connections or state after the system wakes up. This event is only available within the plugin context, not the property inspector.

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

streamDeck.system.onSystemDidWakeUp((ev) => {
	// Handle system wake.
});

streamDeck.connect();
```

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

### Layout Validation CLI Output

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

Example output from the `streamdeck validate` command indicating that a layout item's rectangle is outside the canvas boundaries.

```text
8:13  error    items[0].rect[0] must not be outside of the canvas
8:13  error    └ Width and height, relative to the x and y, must be within the 200x100 px canvas
```

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

### Handle Settings in Plugin

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

Implementation of the onDidReceiveSettings event to handle updates from the property inspector.

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

// Define the action's settings type.
type Settings = {
	count: number;
};

@action({ UUID: "com.elgato.hello-world.counter" })
class Counter extends SingletonAction<Settings> {
	/**
	 * Occurs when the application-layer receives the settings from the UI.
	 */

	override onDidReceiveSettings(ev: DidReceiveSettingsEvent<Settings>): void {
		// Handle the settings changing in the property inspector (UI).
	}
}

streamDeck.actions.registerAction(new Counter());
streamDeck.connect();
```

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

### GET /streamdeck/plugins/message/{PLUGIN_UUID}

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

This endpoint acts as a redirect proxy to forward OAuth2 authorization callbacks to a specific Stream Deck plugin using its unique UUID.

```APIDOC
## GET /streamdeck/plugins/message/{PLUGIN_UUID}

### Description
Forwards OAuth2 authorization callback parameters to a Stream Deck plugin via deep-linking. No data is stored on Elgato servers.

### Method
GET

### Endpoint
https://oauth2-redirect.elgato.com/streamdeck/plugins/message/{PLUGIN_UUID}

### Parameters
#### Path Parameters
- **PLUGIN_UUID** (string) - Required - The unique identifier of the plugin.

#### Query Parameters
- **code** (string) - Optional - Authorization code to exchange for an access token.
- **state** (string) - Optional - Value supplied as part of requesting authorization.
- **scope** (string) - Optional - Specifies the level of access granted.
- **error** (string) - Optional - Error returned by the authorization provider when unsuccessful.
```

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

### Open URL in Browser

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

Use this utility to open a specified URL in the user's default browser. Custom URL schemes are not supported.

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

streamDeck.actions.onKeyDown(() => {
	streamDeck.system.openUrl("https://elgato.com");
});

streamDeck.connect();
```

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

### Invalid Custom Layout Example

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

This JSON demonstrates a custom layout where an item's rectangle exceeds the 200x100 px canvas bounds, which will cause rendering issues.

```json
{
    "$schema": "https://schemas.elgato.com/streamdeck/plugins/layout.json",
    "id": "hello-world",
    "items": [
        {
            "key": "title",
            "type": "text",

            "rect": [100, 0, 136, 50], // x (100) + width (136) exceeds 200
            "font": { "size": 32, "weight": 600 },
            "alignment": "left"
        }
    ]
}
```

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

### Run Prettier Lint Fix Script

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

Use this NPM script to automatically format your project files according to Prettier's rules. Ensure Prettier is installed and configured in your package.json.

```json
{
	"scripts": {
		"lint:fix": "prettier . --write"
	}
}
```

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

### Stream Deck Plugin File Structure

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

Illustrates the directory structure for a Stream Deck plugin, including localization files.

```tree
. 
├── *.sdPlugin/ 
│   ├── bin/ 
│   ├── imgs/ 
│   ├── logs/ 
│   ├── ui/ 
│   │   └── increment-counter.html 
│   ├── de.json 
│   ├── en.json 
│   ├── es.json 
│   ├── fr.json 
│   ├── ja.json 
│   ├── ko.json 
│   ├── manifest.json 
│   ├── zh_CN.json 
│   └── zh_TW.json 
├── src/ 
│   ├── actions/ 
│   │   └── increment-counter.ts 
│   └── plugin.ts 
├── package.json 
├── rollup.config.mjs 
└── tsconfig.json
```

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

### Stream Deck Application Launch Event

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

This TypeScript type defines the structure for the 'applicationDidLaunch' event. It is sent by Stream Deck when a monitored application starts, providing the name of the launched application.

```typescript
type ApplicationDidLaunch = {
    event: "applicationDidLaunch";
    payload: {
        application: string;
    };
};
```

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

### Operating System Compatibility

Source: https://docs.elgato.com/streamdeck/sdk/references/manifest

Specifies the operating system and minimum version required for the plugin.

```APIDOC
## Operating System Compatibility

Operating system that the plugin supports, and the minimum required version needed to run the plugin.

### Properties

*   **MinimumVersion** (string, Required) - Minimum version required of the operating system to run the plugin.
*   **Platform** (string, Required) - Operating system supported by the plugin. Allowed values: `"mac"`, `"windows"`.
```

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

### Import Miscellaneous Utilities

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

Updates the source package for common utilities from @elgato/streamdeck to @elgato/utils.

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

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

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

### Increment Counter Action with Reset Logic

Source: https://docs.elgato.com/streamdeck/sdk/introduction/your-first-changes

This TypeScript code implements an action that increments a counter. It resets the count to 0 when it reaches 256, and starts from 1 if the count is 0. Ensure the action is decorated with @action and extends SingletonAction.

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

@action({ UUID: "com.elgato.hello-world.increment" })
export class IncrementCounter extends SingletonAction<CounterSettings> {
	/**
	 * Occurs when the action will appear.
	 */
	override onWillAppear(ev: WillAppearEvent<CounterSettings>): void | Promise<void> {
		return ev.action.setTitle(`${ev.payload.settings.count ?? 0}`);
	}

	/**
	 * Occurs when the action's key is pressed down.
	 */
	override async onKeyDown(ev: KeyDownEvent<CounterSettings>): Promise<void> {
		// Determine the current count from the settings.
		let count = ev.payload.settings.count ?? 0;
		if (count === 0) {
			count = 1;
		} else if (count < 256) {
			count = count * 2;
		} else {
			count = 0;
		}

		// Update the current count in the action's settings, and change the title.
		await ev.action.setSettings({ count });
		await ev.action.setTitle(`${count}`);
	}
}

type CounterSettings = {
	count: number;
};

```

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

### ApplicationDidLaunch Event

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

Describes the event received by the plugin when a monitored application is launched.

```APIDOC
## Event: ApplicationDidLaunch

### Description
Occurs when a monitored application is launched. Monitored applications are defined in the manifest.json file.

### Response
- **event** (string) - Required - The event name: "applicationDidLaunch".
- **payload** (object) - Required - Contains the application details.
  - **application** (string) - Required - The name of the application that triggered the event.

### Response Example
{
    "event": "applicationDidLaunch",
    "payload": {
        "application": "com.example.app"
    }
}
```

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

### Global Settings Management

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

Methods for managing plugin-wide settings.

```APIDOC
## Global Settings API

### Description
Manage settings that apply to the entire plugin. Global settings are recommended for security-sensitive data like API keys.

### Methods
- **Writing**: `streamDeck.settings.setGlobalSettings(settings)`
- **Reading**: `streamDeck.settings.getGlobalSettings()`
- **Changed**: `streamDeck.settings.onDidReceiveGlobalSettings(handler)`
```

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

### Enable Developer Mode

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

Command to enable the remote debugger for the property inspector.

```bash
streamdeck dev
```

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

### Define GetGlobalSettings command structure

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

Represents the command structure for requesting global plugin settings, which triggers a DidReceiveGlobalSettings event.

```typescript
type GetGlobalSettings = {
    context: string;
    event: "getGlobalSettings";
    id?: string;
};
```

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

### Layout $B1 Configuration

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

JSON definition for the $B1 layout, including a title, icon, value, and a bar indicator.

```json
{
    "$schema": "https://schemas.elgato.com/streamdeck/plugins/layout.json",
    "id": "$B1",
    "items": [
        {
            "key": "title",
            "type": "text",
            "rect": [16, 10, 136, 24],
            "font": { "size": 16, "weight": 600 },
            "alignment": "left"
        },
        {
            "key": "icon",
            "type": "pixmap",
            "rect": [16, 40, 48, 48]
        },
        {
            "key": "value",
            "type": "text",
            "rect": [76, 40, 108, 32],
            "font": { "size": 24, "weight": 600 },
            "alignment": "right"
        },
        {
            "key": "indicator",
            "type": "bar",
            "rect": [76, 74, 108, 12],
            "value": 0,
            "subtype": 4,
            "border_w": 0
        }
    ]
}
```

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

### Register Applications in Manifest

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

Specify applications to monitor in the plugin's manifest JSON file under the 'ApplicationsToMonitor' property. This configuration is OS-specific.

```json
{
    "$schema": "https://schemas.elgato.com/streamdeck/plugins/manifest.json",
    "UUID": "com.elgato.hello-world",
    "Name": "Hello World",
    "Version": "0.1.0.0",
    "Author": "Elgato",
    "Actions": [
        {
            "Name": "Counter",
            "UUID": "com.elgato.hello-world.increment",
            "Icon": "static/imgs/actions/counter/icon",
            "Tooltip": "Displays a count, which increments by one on press.",
            "Controllers": ["Keypad"],
            "States": [
                {
                    "Image": "static/imgs/actions/counter/key",
                    "TitleAlignment": "middle"
                }
            ]
        }
    ],
    "Category": "Hello World",
    "CategoryIcon": "static/imgs/plugin/category-icon",
    "CodePath": "bin/plugin.js",
    "Description": ".",
    "Icon": "static/imgs/plugin/marketplace",
    "SDKVersion": 2,
    "Software": {
        "MinimumVersion": "6.6"
    },
    "OS": [
        {
            "Platform": "mac",
            "MinimumVersion": "10.15"
        },
        {
            "Platform": "windows",
            "MinimumVersion": "10"
        }
    ],
    "Nodejs": {
        "Version": "20",
        "Debug": "enabled"
    },
    "ApplicationsToMonitor": {
        "mac": ["com.elgato.WaveLink"],
        "windows": ["Elgato Wave Link.exe"]
    },
    "Profiles": [
        {
            "Name": "My Cool Profile",
            "DeviceType": 0,
            "Readonly": false,
            "DontAutoSwitchWhenInstalled": false,
            "AutoInstall": true
        }
    ]
}
```

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

### GetSettings API

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

Retrieves the settings associated with an instance of an action. This action causes `DidReceiveSettings` to be emitted.

```APIDOC
## POST /GetSettings

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

### Method
POST

### Endpoint
/GetSettings

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

### Request Example
{
  "context": "some-context-string",
  "event": "getSettings",
  "id": "unique-id-456"
}

### Response
#### Success Response (200)
- **event** (string) - The event type, which will be "didGetSettings".
- **id** (string) - The identifier for the request.
- **payload** (object) - Contains the settings associated with the action instance.
  - **settings** (object) - An object containing the settings.

#### Response Example
{
  "event": "didGetSettings",
  "id": "unique-id-456",
  "payload": {
    "settings": {
      "color": "red",
      "title": "My Action"
    }
  }
}
```

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

### Layout $X1 Configuration

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

JSON definition for the $X1 layout, which includes a text title and an icon.

```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]
        }
    ]
}
```

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

### Action Key Event Handling

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

Details the event handlers available for action keys, specifically `onKeyDown` and `onKeyUp`, which are triggered by user interaction.

```APIDOC
## Event Handlers for Action Keys

### onKeyDown

#### Description
Occurs when the user presses an action key down.

#### Method Signature
`onKeyDown?(ev: KeyDownEvent): void | Promise<void>`

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

### onKeyUp

#### Description
Occurs when the user releases a pressed action key.

#### Method Signature
`onKeyUp?(ev: KeyUpEvent): void | Promise<void>`

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

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

### Trigger Descriptions in Manifest

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

Shows how to define trigger descriptions in the manifest JSON file for encoder actions.

```APIDOC
## Trigger Descriptions
Trigger descriptions can help the user to understand what the encoder does in a particular dial action. This can be set in the manifest file using the `Actions[].Encoder.TriggerDescriptions` property.

### Manifest JSON file, with an action referencing a trigger description
```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"
                }
            }
        }
    ]
    // ...
}
```
```

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

### Action Class: Handling Multiple Events

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

This action class demonstrates handling both 'key down' and 'will appear' events. It provides context for the action, device, and controller type.

```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!`);
	}
}
```

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

### Validate Settings with Zod

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

Shows how to use Zod to validate settings, providing default values and ensuring type safety at runtime. This approach reduces the risk of runtime errors.

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

// Define the Zod schema.
const Settings = z.object({
	name: z.string().default("Elgato"),
});

// Infer the settings type.
type Settings = z.infer<typeof Settings>;

/**
 * An example action that demonstrates parsing settings with Zod.
 */
export class MyAction extends SingletonAction<Settings> {
	/**
	 * Occurs when the user presses the key action.
	 */
	override async onKeyDown(ev: KeyDownEvent<Settings>): Promise<void> {
		/*
		 * Settings can safely be undefined here, Zod
		 * will fallback `name` to "Elgato".
		 */
		const { name } = Settings.parse(ev.payload.settings);
		name.toLowerCase(); // "elgato"
	}
}
```