README

@elgato-stream-deck/node

@elgato-stream-deck/node is a shared library for interfacing with the various models of the Elgato Stream Deck.

Intended use

This library has nothing to do with the streamdeck software produced by Elgato. There is nothing here to install and run. This is a library to help developers make alternatives to that software

Install

$ npm install --save @elgato-stream-deck/node

$ npm install --save @julusian/jpeg-turbo@^1.0.1 (Optional)

It is recommended to install @julusian/jpeg-turbo to greatly improve performance for writing images to the StreamDeck XL or the Original-v2. Without doing so jpeg-js will be used instead, but image transfers will be noticably more cpu intensive and slower. jpeg-turbo has prebuilt binaries, but is not installed by default to ensure installation is easy for users who do not need the performance for the XL or the Original-v2.

Native dependencies

All of this library's native dependencies ship with prebuilt binaries, so having a full compiler toolchain should not be necessary to install @elgato-stream-deck/node.

However, in the event that installation does fail (or if you are on a platform that our dependencies don't provide prebuilt binaries for, such as a Raspberry Pi), you will need to install a compiler toolchain to enable npm to build some of @elgato-stream-deck/node's dependencies from source. Expand the details block below for full instructions on how to do so.

Compiling dependencies from source

Windows

Install windows-build-tools:

npm install --global windows-build-tools

MacOS
- Install the Xcode Command Line Tools:
```
xcode-select --install
```
Linux (including Raspberry Pi)
- Follow the instructions for Linux in the "Compiling from source" steps for
- Try installing @elgato-stream-deck/node
- If you still have issues, ensure everything is updated and try again:
```
sudo apt-get update && sudo apt-get upgrade
```

Linux

On linux, the udev subsystem blocks access to the StreamDeck without some special configuration. Save the following to /etc/udev/rules.d/50-elgato.rules and reload the rules with sudo udevadm control --reload-rules

SUBSYSTEM=="input", GROUP="input", MODE="0666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0060", MODE:="666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0063", MODE:="666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006c", MODE:="666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006d", MODE:="666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0080", MODE:="666", GROUP="plugdev"
KERNEL=="hidraw", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0060", MODE:="666", GROUP="plugdev"
KERNEL=="hidraw", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0063", MODE:="666", GROUP="plugdev"
KERNEL=="hidraw", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006c", MODE:="666", GROUP="plugdev"
KERNEL=="hidraw", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006d", MODE:="666", GROUP="plugdev"
KERNEL=="hidraw", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0080", MODE:="666", GROUP="plugdev"

Unplug and replug the device and it should be usable

Features

Multiplatform support: Windows 7-10, MacOS, Linux, and even Raspberry Pi!
Support for every StreamDeck model (Original, Mini & XL)
Key down and key up events
Fill keys with images or solid RGB colors
Fill the entire panel with a single image, spread across all keys
Set the Stream Deck brightness
TypeScript support

API

The root methods exposed by the library are as follows. For more information it is recommended to rely on the typescript typings for hints or to browse through the source to see what methods are available

/**
 * Scan for and list detected devices
 */
export function listStreamDecks(): StreamDeckDeviceInfo[]

/**
 * Get the info of a device if the given path is a streamdeck
 */
export function getStreamDeckInfo(path: string): StreamDeckDeviceInfo | undefined

/**
 * Open a streamdeck
 * @param devicePath The path of the device to open. If not set, the first will be used
 * @param userOptions Options to customise the device behvaiour
 */
export function openStreamDeck(devicePath?: string, userOptions?: OpenStreamDeckOptionsNode): StreamDeck

The StreamDeck type can be found here

Example

import { openStreamDeck } from '@elgato-stream-deck/node'

// Automatically discovers connected Stream Decks, and attaches to the first one.
// Throws if there are no connected stream decks.
// You also have the option of providing the devicePath yourself as the first argument to the constructor.
// For example: const myStreamDeck = new StreamDeck('\\\\?\\hid#vid_05f3&pid_0405&mi_00#7&56cf813&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}')
// On linux the equivalent would be: const myStreamDeck = new StreamDeck('0001:0021:00')
// Available devices can be found with listStreamDecks()
const myStreamDeck = await openStreamDeck() // Will throw an error if no Stream Decks are connected.

myStreamDeck.on('down', (keyIndex) => {
    console.log('key %d down', keyIndex)
})

myStreamDeck.on('up', (keyIndex) => {
    console.log('key %d up', keyIndex)
})

// Fired whenever an error is detected by the `node-hid` library.
// Always add a listener for this event! If you don't, errors will be silently dropped.
myStreamDeck.on('error', (error) => {
    console.error(error)
})

// Fill the first button form the left in the first row with a solid red color. This is asynchronous.
await myStreamDeck.fillKeyColor(4, 255, 0, 0)
console.log('Successfully wrote a red square to key 4.')

Some more complex demos can be found in the examples folder.

Contributing

The elgato-stream-deck team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear.

Please refer to the Changelog for project history details, too.

Usage no npm install needed!