StreamDeck

README

streamdeck

streamdeck is a library for interfacing with the Elgato/Corsair Stream Deck

This library is written in the programing language Go.

Note

This project is a golang API for the Elgato/Corsair Stream Deck. This library unleashes the power of the StreamDeck. It allows you to completely customize the content of the device, without the need of the OEM's software.

License

streamdeck is published under the permissive MIT license.

Dependencies

There are a few go libraries which are needed at compile time. streamdeck does not have any runtime dependencies.

CGO

Compiling this library requires unfortunately a C compiler since the underlying HID library requires cgo for enumerating the HID devices.

Supported Operating Systems

The library should work on Linux, MacOS and Windows (>=7).

streamdeck works well on SoC boards like the Raspberry / Orange / Banana Pis.

Linux Device rules

On Linux you might have to create an udev rule, to access the streamdeck.

sudo vim /etc/udev/rules.d/99-streamdeck.rules

SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0060", MODE="0664", GROUP="plugdev"

After saving the udev rule, unplug and plug the streamdeck again into the USB port. For the rule above, your user must be a member of the plugdev group.

Make sure that your streamdeck is correctly recognized by executing:

$ go run examples/enumerate/enumerate.go
Found 1 Elgato Stream Deck(s):
	SerialNumber:        AL12H1A07123

Documentation

The auto generated documentation can be found at godoc.org

Examples

Please checkout the dedicated repository streamdeck-examples for examples.

My personal library of streamdeck elements / buttons can be found in the streamdeck-buttons repository.

Credits

This project would not have been possible without the work of Alex Van Camp. In particular his notes of the StreamDeck's protocol were very helpful. Alex has provided a reference implementation in Javascript / Node.js.

Documentation

Index

• Constants
• type BtnEvent
• type BtnState
  • func (i BtnState) String() string
• type Page
• type ReadErrorCb
• type StreamDeck
  • func NewStreamDeck(serial ...string) (*StreamDeck, error)
  • func (sd *StreamDeck) ClearAllBtns()
  • func (sd *StreamDeck) ClearBtn(btnIndex int) error
  • func (sd *StreamDeck) Close() error
  • func (sd *StreamDeck) FillColor(btnIndex, r, g, b int) error
  • func (sd *StreamDeck) FillImage(btnIndex int, img image.Image) error
  • func (sd *StreamDeck) FillImageFromFile(keyIndex int, path string) error
  • func (sd *StreamDeck) FillPanel(img image.Image) error
  • func (sd *StreamDeck) FillPanelFromFile(path string) error
  • func (sd *StreamDeck) SetBtnEventCb(ev BtnEvent)
  • func (sd *StreamDeck) WriteText(btnIndex int, textBtn TextButton) error
• type TextButton
• type TextLine

Constants

const ButtonSize = 72

ButtonSize is the size of a button (in pixel).

const NumButtonColumns = 5

NumButtonColumns is the number of columns on the Stream Deck.

const NumButtonRows = 3

NumButtonRows is the number of button rows on the Stream Deck.

const NumButtons = 15

NumButtons is the total amount of Buttons located on the Stream Deck.

const PanelHeight = NumButtonRows*ButtonSize + Spacer*(NumButtonRows-1)

PanelHeight is the total screen height of the stream deck (including spacers).

const PanelWidth = NumButtonColumns*ButtonSize + Spacer*(NumButtonColumns-1)

PanelWidth is the total screen width of the Stream Deck (including spacers).

const ProductID = 109

ProductID is the USB ProductID assigned to Elgato's Stream Deck (0x0060)

const Spacer = 19

Spacer is the spacing distance (in pixel) of two buttons on the Stream Deck.

const VendorID = 4057

VendorID is the USB VendorID assigned to Elgato (0x0fd9)

Types

type BtnEvent

type BtnEvent func(btnIndex int, newBtnState BtnState)

BtnEvent is a callback which gets executed when the state of a button changes, so whenever it gets pressed or released.

type BtnState

type BtnState int

BtnState is a type representing the button state.

const (
	// BtnPressed button pressed
	BtnPressed BtnState = iota
	// BtnReleased button released
	BtnReleased
)

func (BtnState) String

func (i BtnState) String() string

type Page

type Page interface {
	Set(btnIndex int, state BtnState) Page
	Parent() Page
	Draw()
	SetActive(bool)
}

Page contains the configuration of one particular page of buttons. Pages can be nested to an arbitrary depth.

type ReadErrorCb

type ReadErrorCb func(err error)

ReadErrorCb is a callback which gets executed in case reading from the Stream Deck fails (e.g. the cable get's disconnected).

type StreamDeck

type StreamDeck struct {
	sync.Mutex
	// contains filtered or unexported fields
}

StreamDeck is the object representing the Elgato Stream Deck.

func NewStreamDeck

func NewStreamDeck(serial ...string) (*StreamDeck, error)

NewStreamDeck is the constructor of the StreamDeck object. If several StreamDecks are connected to this PC, the Streamdeck can be selected by supplying the optional serial number of the Device. In the examples folder there is a small program which enumerates all available Stream Decks. If no serial number is supplied, the first StreamDeck found will be selected.

func (*StreamDeck) ClearAllBtns

func (sd *StreamDeck) ClearAllBtns()

ClearAllBtns fills all keys with the color black

func (*StreamDeck) ClearBtn

func (sd *StreamDeck) ClearBtn(btnIndex int) error

ClearBtn fills a particular key with the color black

func (*StreamDeck) Close

func (sd *StreamDeck) Close() error

Close the connection to the Elgato Stream Deck

func (*StreamDeck) FillColor

func (sd *StreamDeck) FillColor(btnIndex, r, g, b int) error

FillColor fills the given button with a solid color.

func (*StreamDeck) FillImage

func (sd *StreamDeck) FillImage(btnIndex int, img image.Image) error

FillImage fills the given key with an image. For best performance, provide the image in the size of 72x72 pixels. Otherwise it will be automatically resized.

func (*StreamDeck) FillImageFromFile

func (sd *StreamDeck) FillImageFromFile(keyIndex int, path string) error

FillImageFromFile fills the given key with an image from a file.

func (*StreamDeck) FillPanel

func (sd *StreamDeck) FillPanel(img image.Image) error

FillPanel fills the whole panel witn an image. The image is scaled to fit and then center-cropped (if necessary). The native picture size is 360px x 216px.

func (*StreamDeck) FillPanelFromFile

func (sd *StreamDeck) FillPanelFromFile(path string) error

FillPanelFromFile fills the entire panel with an image from a file.

func (*StreamDeck) SetBtnEventCb

func (sd *StreamDeck) SetBtnEventCb(ev BtnEvent)

SetBtnEventCb sets the BtnEvent callback which get's executed whenever a Button event (pressed/released) occures.

func (*StreamDeck) WriteText

func (sd *StreamDeck) WriteText(btnIndex int, textBtn TextButton) error

WriteText can write several lines of Text to a button. It is up to the user to ensure that the lines fit properly on the button.

type TextButton

type TextButton struct {
	Lines   []TextLine
	BgColor color.Color
}

TextButton holds the lines to be written to a button and the desired Background color.

type TextLine

type TextLine struct {
	Text      string
	PosX      int
	PosY      int
	Font      *truetype.Font
	FontSize  float64
	FontColor color.Color
}

TextLine holds the content of one text line.