@elgato/streamdeck NPM

Stream Deck SDK

Welcome to the official SDK for creating Stream Deck plugins. Designed to make building with Stream Deck easy, the SDK provides everything you need to connect and communicate with Stream Deck, and lets you focus on the fun stuff.

📥 Prerequisites

The Stream Deck SDK uses Node.js; we recommend installing Node with a Node version manager such as nvm (macOS) or nvm-windows (Windows). With one of these version managers installed, the specific version of Node can be set via:

nvm install 20.1.0
nvm use 20.1.0

📦 Example

npm i @elgato/streamdeck

import streamDeck from "@elgato/streamdeck";

// Show an "OK" icon when an action is pressed.
streamDeck.client.onKeyDown(({ action }) => {
    action.showOk();
});

!IMPORTANT Stream Deck plugins require scaffolding, and it is highly recommended to use the streamdeck create CLI command.

📖 Usage

🔗 Client

The streamDeck.client acts as the bridge between your plugin, and the Stream Deck. The client provides event listeners for receiving events from Stream Deck e.g. when an action appears, and functions for sending commands to the Stream Deck e.g. updating settings.

import streamDeck from "@elgato/streamdeck";

// Event examples.
streamDeck.client.onWillAppear(({ action }) => { ... });     // Occurs when an action appears.
streamDeck.client.onWillDisappear(({ action }) => { ... });  // Occurs when an action disappears.

// Command examples.
streamDeck.client.setGlobalSettings(settings); // Updates the global settings.
streamDeck.client.switchToProfile(profile, device); // Switch to a pre-defined profile.

🗺️ Actions

The streamDeck.actions object provides methods for routing events of a specific action type, as identified by their UUID defined within the manifest; routing is particularly useful when your plugin provides multiple actions.

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

@action({ UUID: "com.elgato.test.toggle-on-off" })
class ToggleOnOff extends SingletonAction {
    onKeyDown() {
        // Occurs when key down happens for an action of type "com.elgato.test.toggle-on-off"
    }
}

@action({ UUID: "com.elgato.test.change-brightness" })
class ChangeBrightness extends SingletonAction {
    onKeyDown() {
        // Occurs when key down happens for an action of type "com.elgato.test.change-brightness"
    }
}

streamDeck.actions.registerAction(new ToggleOnOff());
streamDeck.actions.registerAction(new ChangeBrightness());

🎛️ Devices

The streamDeck.devices collection contains information about the user's Stream Deck devices.

import streamDeck from "@elgato/streamdeck";

streamDeck.devices.forEach((device) => {
    // Device information.
});

📄 Logging

The streamDeck.logger object provides local file-based logging, allowing you to diagnose, track, and debug your plugin. Logs files operate a file-rotation policy and are re-indexed when the plugin starts or they exceed 50MiB, with the 10 most recent log files being retained.

!NOTE Logs can be found within the plugin's folder, under /logs.

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

const logger = streamDeck.logger.createScope("Custom Logger");

logger.error("Error message");
logger.warn("Warning message");
logger.info("Information message");
logger.debug("Debug message"); // ❌ Default level is INFO
logger.trace("Trace message"); // ❌ Default level is INFO

logger.setLevel(LogLevel.TRACE);

logger.debug("Debug message"); // ✅
logger.trace("Trace message"); // ✅

!WARNING
When the log-level is set to TRACE all communication between the Stream Deck and the plugin will be logged to the file system, this includes all settings. Please ensure sensitive information is not transmitted whilst TRACE is active.