Actions

Fresh

Source

Elgato Stream Deck SDK - Actions

Overview

Actions are the core interactive elements in Stream Deck plugins. They represent keys, dials, pedals, and G-Keys that users can add to their Stream Deck canvas.

Controller Types

Type	Description	Devices
Key	Standard buttons	Stream Deck, Pedal, G-Keys
Dial	Rotary encoder + touch strip	Stream Deck +

Action UUIDs

Actions use reverse-DNS formatted UUIDs prefixed by the plugin UUID:

Plugin UUID:  com.elgato.hello-world
Action UUID:  com.elgato.hello-world.counter

Never Change UUIDs

Once published, never change a UUID. This removes the action from all user configurations.

SOP: Create and Register an Action

Step 1: Define Metadata in Manifest

Add the action to your manifest.json under the Actions array:

{
  "Actions": [
    {
      "UUID": "com.elgato.hello-world.log",
      "Name": "Log Key Press",
      "Icon": "imgs/actions/log",
      "Tooltip": "Logs when a key is pressed",
      "Controllers": ["Keypad"]
    }
  ]
}

Step 2: Implement the Action

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

@action({ UUID: "com.elgato.hello-world.log" })
export class LogKeyPressAction extends SingletonAction {
  override onKeyDown(ev: KeyDownEvent): void | Promise<void> {
    streamDeck.logger.info("Key pressed!");
  }
}

Step 3: Register Before Connect

import streamDeck from "@elgato/streamdeck";
import { LogKeyPressAction } from "./actions/log-key-press";

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

Event Lifecycle

Core Events

Event	Trigger
onWillAppear	Action appears on canvas
onWillDisappear	Action removed from canvas
onKeyDown	User presses key
onKeyUp	User releases key
onDidReceiveSettings	Settings requested or updated
onPropertyInspectorDidAppear	Property Inspector opens
onPropertyInspectorDidDisappear	Property Inspector closes
onSendToPlugin	Message from Property Inspector
onTitleParametersDidChange	Title settings updated
onDidReceiveResources	Resources updated (SD 7.1+)

Accessing Visible Actions

Outside event handlers, iterate over all visible actions:

streamDeck.actions.forEach((action) => {
  action.setTitle("Hello world");
});

Within an action class, access instances of that specific type:

this.actions.forEach((action) => {
  action.setTitle("Updated");
});

Common Commands

Command	Description
getSettings<U>()	Retrieve action settings
setSettings<U>(settings)	Persist settings
getResources()	Get embedded files (SD 7.1+)
setResources(resources)	Set embedded files (SD 7.1+)
isDial()	Check if instance is a dial
isKey()	Check if instance is a key
showAlert()	Display warning indicator

Hiding Actions

To hide an action from the actions list (useful for deprecation or pre-configured profiles):

{
  "UUID": "com.example.hidden-action",
  "VisibleInActionsList": false
}