Stream Deck SDK

Appearance

Settings ​

Fresh

Source

Elgato Stream Deck SDK - Settings

Overview ​

The SDK provides two settings types:

  • Action settings - Per-instance configuration attached to individual actions
  • Global settings - Plugin-wide settings shared across all actions

Action Settings ​

Writing Settings ​

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

@action({ UUID: "com.elgato.hello-world.counter" })
class Counter extends SingletonAction {
  override async onKeyDown(ev: KeyDownEvent): Promise<void> {
    await ev.action.setSettings({ count: 1 });
  }
}

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

Reading Settings with Type Safety ​

typescript
type Settings = {
  count: number;
};

@action({ UUID: "com.elgato.hello-world.counter" })
class Counter extends SingletonAction<Settings> {
  override async onKeyDown(ev: KeyDownEvent<Settings>): Promise<void> {
    let { count = 0 } = ev.payload.settings;
    count++;
    await ev.action.setSettings({ count });
  }
}

Listening for Changes ​

typescript
@action({ UUID: "com.elgato.hello-world.counter" })
class Counter extends SingletonAction<Settings> {
  override onDidReceiveSettings(ev: DidReceiveSettingsEvent<Settings>): void {
    // Triggered when Property Inspector updates settings
  }
}

Global Settings ​

Security

API keys, OAuth tokens, and other sensitive data must use global settings. Never store secrets in action settings.

Writing Global Settings ​

typescript
streamDeck.system.onDidReceiveDeepLink((ev) => {
  streamDeck.settings.setGlobalSettings({
    messageReceived: true,
  });
});

streamDeck.connect();

Reading Global Settings ​

typescript
type GlobalSettings = {
  count: number;
};

streamDeck.system.onDidReceiveDeepLink(async (ev) => {
  let { count = 0 } = await streamDeck.settings.getGlobalSettings<GlobalSettings>();
  count++;
  await streamDeck.settings.setGlobalSettings({ count });
});

Global Settings Change Event ​

typescript
streamDeck.settings.onDidReceiveGlobalSettings((ev) => {
  // Handle global settings changes
});

API Quick Reference ​

OperationAction SettingsGlobal Settings
Writeev.action.setSettings()streamDeck.settings.setGlobalSettings()
Readev.payload.settings or ev.action.getSettings()streamDeck.settings.getGlobalSettings()
Change EventSingletonAction.onDidReceiveSettings()streamDeck.settings.onDidReceiveGlobalSettings()

Experimental: Message Identifiers ​

Distinguish between settings changes and get-requests:

typescript
streamDeck.settings.useExperimentalMessageIdentifiers = true;
streamDeck.connect();

With this enabled, onDidReceiveSettings only fires on actual changes, not on get requests.

Runtime Validation with Zod ​

TypeScript types don't guarantee runtime values. Use validation:

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

const Settings = z.object({
  name: z.string().default("Elgato"),
});

type Settings = z.infer<typeof Settings>;

export class MyAction extends SingletonAction<Settings> {
  override async onKeyDown(ev: KeyDownEvent<Settings>): Promise<void> {
    const { name } = Settings.parse(ev.payload.settings);
    name.toLowerCase(); // Guaranteed to be a string
  }
}

Supported Data Types ​

Settings persist as JSON objects supporting: booleans, numbers, strings, null, arrays, and objects.