elgato-stream-deck

❗ Please note that stream-deck-ts is NOT a standalone application. It is not something you download and run on its own. It is not an alternative to the official Stream Deck program provided by Elgato. Instead, stream-deck-ts is a code library which provides an API to the Stream Deck. Developers can use this API to make their own applications which interface with the Stream Deck.

To further clarify: this is not an installable program. There is no user interface, and you cannot do anything with this library on its own. Out of the box, this library does nothing. It's purpose is to provide tools for programmers to build programs from the ground up which interact with a Stream Deck.

This is a tool for developers to use. It is not a program for end users. It cannot and will not replace the official Stream Deck program. That is not its goal. However, it does enable someone to more easily write a program which does do that.

Supported devices

Any additional devices would be appriciated. If you are able to control another device than those listed - please send a PR.

Elgato

• Elgato Stream Deck.
• Elgato Stream Deck Mini.

Install

$ npm install --save stream-deck-ts

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

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 stream-deck-ts'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 node-hid:

    sudo apt-get install build-essential git
    sudo apt-get install gcc-4.8 g++-4.8 && export CXX=g++-4.8
    sudo apt-get install sudo apt install libusb-1.0-0 libusb-1.0-0-dev

  • Install a recent version of Node.js.:

    curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
    sudo apt-get install -y nodejs 

  • Try installing stream-deck-ts
  • If you still have issues, ensure everything is updated and try again:

    sudo apt-get update && sudo apt-get upgrade

Table of Contents

• Example
• Features
• Planned Features
• Contributing
• API
  • selectDevice([vendor[, product]])
  • selectAllDevices([vendor[, product]])
  • Class: StreamDeck
    • Event: 'down'
    • Event: 'up'
    • Event: 'error'
    • streamDeck.buttonColumns
    • streamDeck.buttonLength
    • streamDeck.buttonRows
    • streamDeck.iconSize
    • streamDeck.pressedKeys
    • streamDeck.buttonIndexFromPosition(x, y)
    • streamDeck.checkValidKeyIndex(keyIndex)
    • streamDeck.clearAllKeys()
    • streamDeck.clearKey(keyIndex)
    • streamDeck.fillColor(keyIndex, rgb)
    • streamDeck.fillColor(keyIndex, r, g, b)
    • streamDeck.fillImage(keyIndex, buffer)
    • streamDeck.fillImageFromFile(keyIndex, filePath)
    • streamDeck.fillPanel(imagePathOrBuffer[, rawOptions])
    • streamDeck.forEachKey(callback)
    • streamDeck.sendFeatureReport(buffer)
    • streamDeck.setBrightness(percentage)
    • streamDeck.write(buffer)

Example

import { resolve } from "path";
import { selectDevice } from "stream-deck-ts";

(async function asyncMain() {
	// Automatically discovers connected Stream Decks, and attaches to the first one.
	// Returns `null` if there are no connected stream decks.
	// You also have the option of providing the numeric vendor identifier and product identifier.
	// For example: `const myStreamDeck = await selectDevice(VENDOR_ELGATO, PRODUCT_ELGATO_STREAMDECK_MINI);`
	const myStreamDeck = await selectDevice();
	if (!myStreamDeck) {
		throw new Error("No StreamDeck found.");
	}

	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!
	myStreamDeck.on('error', (error) => {
		console.error(error);
	});

	// Fill button 3 with an image of the GitHub logo.
	// This is asynchronous and returns a promise.
	myStreamDeck.fillImageFromFile(3, resolve(__dirname, 'github_logo.png')).then(() => {
		console.log('Successfully wrote a GitHub logo to key 3.');
	});

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

Features

• Multiplatform support: Windows 7-10, MacOS, Linux, and even Raspberry Pi!
• 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

Planned Features

• Hotplugging
• Key combinations
• Support "pages" feature from the official Elgato Stream Deck software
• Text labels
• Changing the standby image

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! The Contributor Guide has all the information you need for everything from reporting bugs to contributing entire new features. Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear.

All participants and maintainers in this project are expected to follow Code of Conduct, and just generally be kind to each other.

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

API

selectDevice ([vendor[, product]])

• vendor <number> An optional vendor identity number to limit which device will be selected.
• product <number> An optional product identity number to limit which device will be selected.
• Returns: <StreamDeck | null>

Select the first supported device. If no supported device is found null is returned.

selectAllDevices ([vendor[, product]])

• vendor <number> An optional vendor identity number to limit which devices will be selected.
• product <number> An optional product identity number to limit which devices will be selected.
• Returns: <Array<StreamDeck>>

Select the first supported device. If no supported device is found null is returned.

Class: StreamDeck

Instances of the StreamDeck class have an active connection to a device.

Event: 'down'

• keyIndex <number> The index of the key that got pressed.

The down event is triggered when a button on the Stream Deck has been pressed down.

Event: 'up'

• keyIndex <number> The index of the key that got released.

The up event is triggered when a button on the Stream Deck has been released which previously had been pressed down.

Event: 'error'

• error <Error> The index of the key that got released.

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.

streamDeck .buttonColumns

• <number>

Returns the number of button columns available to this StreamDeck.

streamDeck. buttonLength

• <number>

Returns the number of buttons available to this StreamDeck.

streamDeck .buttonRows

• <number>

Returns the number of button rows available to this StreamDeck.

streamDeck .hasPressedKeys

• <boolean>

A boolean showing if there currently are any pressed keys.

streamDeck .iconSize

• <number>

Returns the size in pixels used for icons.

streamDeck .pressedKeys

• <Array<number>>

A sorted list of all buttons currently pressed.

streamDeck .buttonIndexFromPosition (x, y)

• x <number> Cloumn number counted from from the left.
• y <number> Row number counted from from the top.
• Returns: <number> The keyIndex at the given position or undefined if out of bounds.

Get the keyIndex at a specific column and row.

streamDeck .checkValidKeyIndex (keyIndex)

• keyIndex <number> Cloumn number counted from from the left.
• y <number> Row number counted from from the top.
• Returns: <number> The keyIndex at the given position or undefined if out of bounds.

Validate a keyIndex. If the number is not valid the function will throw a TypeError, otherwise the same value will be returned.

streamDeck .clearAllKeys ()

• Returns: <StreamDeck>

Synchronously clears all keys on the device.

Example: clear all keys

// Clear all keys.
streamDeck.clearAllKeys();

streamDeck .clearKey (keyIndex)

• keyIndex <number> Key to affect.
• Returns: <StreamDeck>

Synchronously clears the given keyIndex's screen.

Example: clear button 2

// Clear button 2.
streamDeck.clearKey(2);

streamDeck .fillColor (keyIndex, rgb)

• keyIndex <number> Key to affect.
• rgb <number> Fill color.

Synchronously sets the given keyIndex's screen to a solid RGB color.

Example: set button 4 to solid red

// Turn key 4 solid red.
streamDeck.fillColor(4, 0xFF0000);

streamDeck .fillColor (keyIndex, r, g, b)

• keyIndex <number> Key to affect.
• r <number> Red component between 0 - 255.
• g <number> Green component between 0 - 255.
• b <number> Blue component between 0 - 255.

Synchronously sets the given keyIndex's screen to a solid RGB color.

Example: set button 5 to solid blue

// Turn key 5 solid red.
streamDeck.fillColor(5, 0, 0, 0xFF);

streamDeck .fillImage (keyIndex, buffer)

• keyIndex <number> Key to affect.
• buffer <Buffer> Image bytes.
• Returns: <Promise<StreamDeck>>

Synchronously writes a buffer of streamDeck.iconSize * streamDeck.iconSize RGB image data to the given keyIndex's screen. The buffer must be exactly the expected length of bytes. Any other length will result in an error being thrown.

Example: fill button 2 with an image of the GitHub logo

// Fill button 2 with an image of the GitHub logo.
import * as sharp from "sharp"; // See http://sharp.dimens.io/en/stable/ for full docs on this great library!
import { resolve } from "path";

const filepath = resolve(__dirname, 'github_logo.png');
const buffer = await sharp(filepath)
	.flatten() // Eliminate alpha channel, if any.
	.resize(streamDeck.iconSize, streamDeck.iconSize) // Scale up/down to the right size, cropping if necessary.
	.raw() // Give us uncompressed RGB.
	.toBuffer();

streamDeck.fillImage(2, buffer);

streamDeck .fillImageFromFile (keyIndex, filePath)

• keyIndex <number> Key to affect.
• filePath <string> File system path to an image file.
• Returns: <Promise<StreamDeck>>

Asynchronously reads an image from filePath and sets the given keyIndex's screen to that image. Automatically scales the image to the expected height and width and strips out the alpha channel. If necessary, the image will be center-cropped to fit into a square.

Example: fill the button 3 with an image of the GitHub logo

// Fill the button 3 with an image of the GitHub logo.
await streamDeck.fillImageFromFile(3, path.resolve(__dirname, 'github_logo.png'));
console.log('Successfully wrote a GitHub logo to key 3.');

streamDeck .fillPanel (imagePathOrBuffer[, rawOptions])

• imagePathOrBuffer <string | Uint8Array | Buffer> Image data or path to a file.
• rawOptions <object> Optional options object used if the image buffer contained raw pixel data.
  • rawOptions.channels <number> Number of channels per pixel. RGBA = 4.
  • rawOptions.height <number> Height in pixels.
  • rawOptions.width <number> Width in pixels.
• Returns: <Promise<StreamDeck>>

Asynchronously applies an image to the entire panel, spreading it over all keys. The image is scaled down and center-cropped to fit. This method does not currently account for the gaps between keys, and behaves as if each key was directly connected to its neighbors. If you wish to account for the gaps between keys, you'll need to do so via other means, and bake that into the image you provide to fillPanel.

This method accepts either a path to an image on the disk, or a buffer. The image path or buffer is passed directly to sharp. Therefore, this method accepts all images and buffers which sharp can accept.

Example: fill the entire panel with a photo of a sunny field

// Fill the entire panel with a photo of a sunny field.
import { resolve } from "path";

const filepath = resolve(__dirname, 'examples/fixtures/sunny_field.png');
await streamDeck.fillPanel(filepath);
console.log('Successfully filled the panel with an image.');

streamDeck .forEachKey (callback)

• callback <Function> The function to call for each button in the stream deck.
• Returns: <StreamDeck>

Execute a function for each button available to the StreamDeck.

streamDeck .sendFeatureReport (buffer)

• buffer <Buffer | Uint8Array> The buffer send to the Stream Deck.
• Returns: <StreamDeck>

Sends a HID feature report to the Stream Deck.

streamDeck .setBrightness (percentage)

• percentage <number> Percentage of brightness.
• Returns: <StreamDeck>

Synchronously set the brightness of the Stream Deck. This affects all keys at once. The brightness of individual keys cannot be controlled.

Example: set the Stream Deck to maximum brightness

// Set the Stream Deck to maximum brightness
streamDeck.setBrightness(100);

streamDeck .write (buffer)

• buffer <Buffer | Uint8Array> Data to write.
• Returns: <StreamDeck>

Synchronously writes an arbitrary Buffer instance to the Stream Deck. Throws if an error is encountered during the write operation.

Example: write a number of zeros to the stream deck

// Writes 16 bytes of zero to the Stream Deck.
streamDeck.write(Buffer.alloc(16));