elgato-stream-deck

elgato-stream-deck

elgato-stream-deck is a Node.js library for interfacing with the Elgato Stream Deck.

Install

$ npm install --save elgato-stream-deck

If that fails (or if you are on a Raspberry Pi), you will need to install a compiler toolchain to enable npm to build some of node-elgato-stream-deck's dependencies from source.

• Windows
  • Install windows-build-tools:

  npm install --global windows-build-tools
  

• MacOS
  • Install Xcode, then:

  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. We've had success with v7:

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

  • Try installing node-elgato-stream-deck
  • 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
  • write
  • fillColor
  • fillImageFromFile
  • fillImage
  • clearKey
  • setBrightness
• Events
  • down
  • up
  • error
• Protocol Notes

Example

JavaScript

const path = require('path');
const streamDeck = require('elgato-stream-deck');

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

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

streamDeck.on('error', error => {
    console.error(error);
});

// Fill the second button from the left in the first row with an image of the GitHub logo.
// This is asynchronous and returns a promise.
streamDeck.fillImageFromFile(3, path.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.
streamDeck.fillColor(4, 255, 0, 0);
console.log('Successfully wrote a red square to key 4.');

TypeScript

import streamDeck = require('elgato-stream-deck');

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

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

streamDeck.on('error', error => {
    console.error(error);
});

Features

• Miltiplatform support: Windows 7-10, MacOS, Linux, and even Raspberry Pi!
• Key down and key up events
• Fill keys with images or solid RGB colors
• Typescript support
• Set the Stream Deck brightness

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

> streamDeck.write(buffer) -> undefined

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

Example

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

> streamDeck.fillColor(keyIndex, r, g, b) -> undefined

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

Example

// Turn key 4 (the top left key) solid red.
streamDeck.fillColor(4, 255, 0, 0);

> streamDeck.fillImageFromFile(keyIndex, filePath) -> Promise

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

Example

// Fill the second button from the left in the first row with an image of the GitHub logo.
streamDeck.fillImageFromFile(3, path.resolve(__dirname, 'github_logo.png'))
	.then(() => {
		console.log('Successfully wrote a GitHub logo to key 3.');
	})
	.catch(err => {
		console.error(err);
	});

> streamDeck.fillImage(keyIndex, buffer) -> undefined

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

Example

// Fill the third button from the left in the first row with an image of the GitHub logo.
const sharp = require('sharp'); // See http://sharp.dimens.io/en/stable/ for full docs on this great library!
sharp(path.resolve(__dirname, 'github_logo.png'))
	.flatten() // Eliminate alpha channel, if any.
	.resize(streamDeck.ICON_SIZE) // Scale down to the right size, cropping if necessary.
	.raw() // Give us uncompressed RGB
	.toBuffer()
	.then(buffer => {
		return streamDeck.fillImage(2, buffer);
	})
	.catch(err => {
		console.error(err);
	});

> streamDeck.clearKey(keyIndex) -> undefined

Synchronously clears the given keyIndex's screen.

Example

// Clear the third button from the left in the first row.
streamDeck.clearKey(2);

> streamDeck.setBrightness(percentage) -> undefined

Synchronously set the brightness of the Stream Deck.

Example

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

Events

> down

Fired whenever a key is pressed. keyIndex is the 0-14 numerical index of that key.

Example

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

> up

Fired whenever a key is released. keyIndex is the 0-14 numerical index of that key.

Example

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

> error

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.

Example

streamDeck.on('error', error => {
    console.error(error);
});

Protocol Notes

Raw protocol notes can be found in NOTES.md. These detail the protocol and method for interacting with the Stream Deck which this module implements.