A typescript sdk to create plugins for the elgato streamdeck.
The goal of this sdk is to make all the events (sent and received to / from the streamdeck) and their paylods typesafe.
Features:
- simple event interface
- working typehints and autocompletion for events and their payloads
If you want to start writing your plugin right away you might want to look at the streamdeck-ts-template package.
It will help you with:
- setting up this sdk
- configuring your plugins metadata
- bundling your code into the format the streamdeck needs
- creating a package for redistribution
See UPGRADE.md for details about the upgrade process for new major versions.
- numberdisplay - the example numberdisplay plugin that comes with the streamdeck ported to use this sdk.
- datetime - shows the date and the time.
yarn add @rweich/streamdeck-ts
or
npm install @rweich/streamdeck-ts
import { Streamdeck } from '@rweich/streamdeck-ts';
// Create plugin instance
const plugin = new Streamdeck().plugin();
// Add event listeners
plugin.on('keyDown', ({ row, column }) => {
console.log(`key pressed on row ${row} and column ${column}`);
});
// Sending events:
// For some events you'll need to set a context (the "button-id").
// It's sent along most events received from the streamdeck.
plugin.on('willAppear', ({ context }) => {
plugin.setTitle('new Title', context);
});
let keypresses = 0;
plugin.on('keyDown', ({ context }) => {
plugin.setTitle(`key pressed ${++keypresses} times`, context);
});
// same for the property inspector
const pi = new Streamdeck().propertyinspector();
pi.on('didReceiveSettings', ({ settings }) => console.log('got settings', settings));
- About
- Quickstart
- Upgrading guide
- Example Implementations
- Installation
- Usage Example
- Table of Contents
- Exposing the plugin / pi instances to the streamdeck
- Incoming events
- applicationDidLaunch
- applicationDidTerminate
- deviceDidConnect
- deviceDidDisconnect
- didReceiveGlobalSettings
- didReceiveSettings
- keyDown
- keyUp
- propertyInspectorDidAppear
- propertyInspectorDidDisappear
- sendToPlugin
- sendToPropertyInspector
- systemDidWakeUp
- titleParametersDidChange
- websocketOpen
- willAppear
- willDisappear
- Outgoing events
- License
The Streamdeck needs a globally accessible connectElgatoStreamDeckSocket
method to register the plugin and propertyinspector.
Both, the plugin and pi instances can be exposed to the streamdeck by binding their createStreamdeckConnector
method to the connectElgatoStreamDeckSocket
. E.g.:
window.connectElgatoStreamDeckSocket = plugin.createStreamdeckConnector();
âšī¸ See the streamdeck-ts-template for a real example how to do that.
The Plugin / Propertyinspector can listen to the following events sent by the streamdeck.
For detailled information see the official docs for events received from the streamdeck.
Triggered when an application - specified in the manifest.json
- was launched.
Event-Payload:
event: { application: string; }
Example:
plugin.on('applicationDidLaunch', ({ application }) => console.log(`${application} was launched!`));
- is sent to: [x] Plugin [ ] PI
Triggered when an application - specified in the manifest.json
- was terminated.
Event-Payload:
event: { application: string; }
Example:
plugin.on('applicationDidTerminate', ({ application }) => console.log(`${application} was terminated!`));
- is sent to: [x] Plugin [ ] PI
Triggered when a streamdeck device gets plugged to the computer.
Event-Payload:
event: {
device: string;
name: string;
type: DeviceType; // enum { StreamDeck, StreamDeckMini, StreamDeckXL, StreamDeckMobile, CorsairGKeys }
columns: number;
rows: number;
}
Example:
plugin.on('deviceDidConnect', ({ name }) => console.log(`device ${name} was plugged in`));
- is sent to: [x] Plugin [ ] PI
Triggered when a streamdeck device gets unplugged from the computer.
Event-Payload:
event: {
device: string;
}
Example:
plugin.on('deviceDidDisconnect', ({ device }) => console.log(`device with id ${device} was unplugged`));
- is sent to: [x] Plugin [ ] PI
Triggered after a GetGlobalSettingsEvent was sent to the streamdeck.
Event-Payload:
event: { settings: unknown }
Example:
plugin.on('didReceiveGlobalSettings', ({ settings }) => console.log('got settings', settings));
- is sent to: [x] Plugin [x] PI
Triggered after a GetSettingsEvent was sent to the streamdeck.
Event-Payload:
event: {
settings: unknown;
row: numbe | undefinedr;
column: number | undefined;
isInMultiAction: boolean;
state: number | undefined;
action: string;
context: string;
device: string;
}
Example:
plugin.on('didReceiveSettings', ({ row, column, settings }) =>
console.log(`got settings for button ${row} / ${column}`, settings),
);
- is sent to: [x] Plugin [x] PI
Triggered when the button gets pressed.
Event-Payload:
event: {
row: number | undefined;
column: number | undefined;
isInMultiAction: boolean;
state: number | undefined;
userDesiredState: number | undefined;
action: string;
context: string;
device: string;
settings: unknown;
}
Example:
plugin.on('keyDown', ({ row, column }) => console.log(`key down on ${row} / ${column}`));
- is sent to: [x] Plugin [ ] PI
Triggered when the button gets released.
Event-Payload:
event: {
row: number | undefined;
column: number | undefined;
isInMultiAction: boolean;
state: number | undefined;
userDesiredState: number | undefined;
action: string;
context: string;
device: string;
settings: unknown;
}
Example:
plugin.on('keyUp', ({ row, column }) => console.log(`key up on ${row} / ${column}`));
- is sent to: [x] Plugin [ ] PI
Triggered when the property inspector appears.
Event-Payload:
event: {
action: string;
context: string;
device: string;
}
Example:
plugin.on('propertyInspectorDidAppear', () => console.log(`the propertyinspector appeared!`));
- is sent to: [x] Plugin [ ] PI
Triggered when the property inspector appears.
Event-Payload:
event: {
action: string;
context: string;
device: string;
}
Example:
plugin.on('propertyInspectorDidDisappear', () => console.log(`the propertyinspector disappeared!`));
- is sent to: [x] Plugin [ ] PI
Triggered when the propertyinspector sends a SendToPluginEvent.
Event-Payload:
event: {
action: string;
context: string;
payload: Record<string, unknown>;
}
Example:
plugin.on('sendToPlugin', ({ payload }) => console.log(`the pi sent some data:`, payload));
- is sent to: [x] Plugin [ ] PI
Triggered when the plugin sends a SendToPropertyInspectorEvent.
Event-Payload:
event: {
action: string;
context: string;
payload: Record<string, unknown>;
}
Example:
pi.on('sendToPropertyInspector', ({ payload }) => console.log(`the plugin sent some data:`, payload));
- is sent to: [ ] Plugin [x] PI
Triggered when the computer is wake up.
Event-Payload:
no payload
Example:
plugin.on('systemDidWakeUp', () => console.log(`system did wake up!`));
- is sent to: [x] Plugin [ ] PI
Triggered when the user changes the title or title parameters.
Event-Payload:
event: {
action: string;
context: string;
device: string;
row: number;
column: number;
settings: unknown;
state: number;
title: string;
fontFamily: string
fontSize: number
fontStyle: string
fontUnderline: boolean
showTitle: boolean
titleAlignment: string
titleColor: string
}
Example:
plugin.on('titleParametersDidChange', ({ fontSize }) => console.log(`new title/params with size ${fontSize}!`));
- is sent to: [x] Plugin [ ] PI
Triggered when the websocket to the streamdeck was successfully opened.
Event-Payload:
event: {
uuid: string;
info: string;
}
Example:
plugin.on('websocketOpen', ({ uuid }) => console.log(`websocket opened for uuid/context: ${uuid}`));
- is sent to: [x] Plugin [x] PI
Triggered when the plugin / button gets displayed on the streamdeck.
Event-Payload:
event: {
settings: unknown;
row: number | undefined;
column: number | undefined;
isInMultiAction: boolean;
state: number | undefined;
action: string;
context: string;
device: string;
}
Example:
plugin.on('willAppear', ({ row, column }) => console.log(`the button appeared on ${row} / ${column}`));
- is sent to: [x] Plugin [ ] PI
Triggered when the plugin / button is no longer displayed on the streamdeck.
Event-Payload:
event: {
settings: unknown;
row: number | undefined;
column: number | undefined;
isInMultiAction: boolean;
state: number | undefined;
action: string;
context: string;
device: string;
}
Example:
plugin.on('willDisappear', ({ row, column }) => console.log(`the button disappeared from ${row} / ${column}`));
- is sent to: [x] Plugin [ ] PI
The plugin and propertyinspector can send the following events to the streamdeck:
For detailled information see the official docs for events sent to the streamdeck.
Requests the settings globally stored for all buttons using this plugin / pi.
Triggers the didReceiveGlobalSettings event.
getGlobalSettings(context: string): void
Example:
plugin.getGlobalSettings('context');
- can be sent from: [x] Plugin [x] PI
Requests the settings stored for the button instance.
Triggers the didReceiveSettings event.
getSettings(context: string): void
Example:
plugin.getSettings('context');
- can be sent from: [x] Plugin [x] PI
Makes the streamdeck write the log message to a debug log file.
logMessage(message: string): void
Example:
plugin.logMessage('the message');
- can be sent from: [x] Plugin [x] PI
Makes the streamdeck open the url in a browser.
openUrl(url: string): void
Example:
plugin.openUrl('the url');
- can be sent from: [x] Plugin [x] PI
Sends data to the plugin. Triggers the sendToPlugin event.
sendToPlugin(context: string, payload: Record<string, unknown>, action: string): void
Example:
pi.sendToPlugin('context', { some: 'data' }, 'action');
- can be sent from: [ ] Plugin [x] PI
Sends data to the propertyinspector. Triggers the sendToPropertyInspector event.
sendToPropertyInspector(context: string, payload: Record<string, unknown>): void
Example:
plugin.sendToPropertyInspector('context', { some: 'data' });
- can be sent from: [x] Plugin [ ] PI
Changes the image of the button.
setImage(image: string, context: string, options: { target?: 'hardware' | 'software' | 'both'; state?: number }): void
Example:
plugin.setImage('imagedataAsBase64', 'context');
- can be sent from: [x] Plugin [ ] PI
Persists the data globally (not just for the current button).
Triggers the didReceiveGlobalSettings event for the plugin (if sent by pi) and for the pi (if sent by plugin).
setGlobalSettings(context: string, settings: unknown): void
Example:
plugin.setGlobalSettings('context', { your: 'new-global-settings' });
- can be sent from: [x] Plugin [x] PI
Persists the settings for the current button.
Triggers the didReceiveSettings event for the plugin (if sent by pi) and for the pi (if sent by plugin).
setSettings(context: string, eventPayload: unknown): void
Example:
plugin.setSettings('context', { your: 'new-settings' });
- can be sent from: [x] Plugin [x] PI
Changes the state of the button if it supports multiple states.
setState(state: number, context: string): void
Example:
plugin.setState(1, 'context');
- can be sent from: [x] Plugin [ ] PI
Changes the title of the button.
setTitle(title: string, context: string, options: { target?: 'hardware' | 'software' | 'both'; state?: number }): void
Example:
plugin.setTitle('the new title', 'context');
- can be sent from: [x] Plugin [ ] PI
Will show an alert icon on the button.
showAlert(context: string): void
Example:
plugin.showAlert('context');
- can be sent from: [x] Plugin [ ] PI
Will show an ok checkmark on the button.
showOk(context: string): void
Example:
plugin.showOk('context');
- can be sent from: [x] Plugin [ ] PI
Makes the streamdeck switch to the preconfigured readonly profile.
switchToProfile(profilename: string, context: string, device: string): void
Example:
plugin.switchToProfile('profilename', 'context', 'device');
- can be sent from: [x] Plugin [ ] PI