streamdeck

package module
v0.0.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 26, 2022 License: MIT Imports: 18 Imported by: 0

README

Go Streamdeck

A Go interface to an Elgato Streamdeck (currently works with the 32-button XL only because that's what I have).

GoDoc

Designed for and tested with Ubuntu, Go 1.13+ and a Streamdeck XL. Images are the wrong size for other streamdecks; bug reports and patches are welcome!

Installation

Either include the library in your project or install it with the following command:

go get github.com/SKAARHOJ/go-streamdeck

On Linux, you might also need to add some udev rules. Put this into /etc/udev/rules.d/99-streamdeck.rules:

SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0060", MODE:="666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0063", MODE:="666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006c", MODE:="666"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006d", MODE:="666"

Usage

There are 2 ways to use this: the low-level "comms-oriented" interface (using streamdeck.Open) which wraps the USB HID protocol, or the higher-level "button-oriented" interface (using streamdeck.New) which represents buttons and actions.

If you want to implement your own actions, I suggest that you either instantiate a CustomAction or alternatively implement the ButtonActionHandler interface (basing your code on the CustomAction).

Example high-level usage

High level usage gives some helpers to set up buttons. This example has a few things to look at:

  • A button in position 2 that says "Hi world" and prints to the console when pressed

  • A button in position 7 displaying the number 7 - changes to number 8 when pressed.

  • A yellow button in position 26

  • A purple button in position 27, it changes colour and prints to the console when pressed.

import (
	"image/color"
	"time"

	streamdeck "github.com/SKAARHOJ/go-streamdeck"
	"github.com/SKAARHOJ/go-streamdeck/actionhandlers"
	"github.com/SKAARHOJ/go-streamdeck/buttons"
	_ "github.com/SKAARHOJ/go-streamdeck/devices"
)

func main() {
	sd, err := streamdeck.New()
	if err != nil {
		panic(err)
	}

	// A simple yellow button in position 26
	cButton := buttons.NewColourButton(color.RGBA{255, 255, 0, 255})
	sd.AddButton(26, cButton)

	// A button with text on it in position 2, which echoes to the console when presesd
	myButton := buttons.NewTextButton("Hi world")
	myButton.SetActionHandler(&actionhandlers.TextPrintAction{Label: "You pressed me"})
	sd.AddButton(2, myButton)

	// A button with text on it which changes when pressed
	myNextButton := buttons.NewTextButton("7")
	myNextButton.SetActionHandler(&actionhandlers.TextLabelChangeAction{NewLabel: "8"})
	sd.AddButton(7, myNextButton)

	// A button which performs multiple actions when pressed
	multiActionButton := buttons.NewColourButton(color.RGBA{255, 0, 255, 255})
	thisActionHandler := &actionhandlers.ChainedAction{}
	thisActionHandler.AddAction(&actionhandlers.TextPrintAction{Label: "Purple press"})
	thisActionHandler.AddAction(&actionhandlers.ColourChangeAction{NewColour: color.RGBA{255, 0, 0, 255}})
	multiActionButton.SetActionHandler(thisActionHandler)
	sd.AddButton(27, multiActionButton)

	time.Sleep(20 * time.Second)
}

The program runs for 20 seconds and then exits.

Example low-level usage

The low-level usage gives more control over the operations of the streamdeck and buttons.

This example shows an image on any pressed button, updating each time another button is pressed.

import streamdeck "github.com/SKAARHOJ/go-streamdeck"

func main() {
	sd, err := streamdeck.Open()
	if err != nil {
		panic(err)
	}
	sd.ClearButtons()

	sd.SetBrightness(50)

	sd.ButtonPress(func(btnIndex int, sd *streamdeck.Device, err error) {
		if err != nil {
			panic(err)
		}
		sd.ClearButtons()
		sd.WriteImageToButton("play.jpg", btnIndex)
	})

	time.Sleep(20 * time.Second)

}

The program runs for 20 seconds and then exits.

Showcase

Projects using this library (pull request to add yours!)

Contributions

This is a very new project but all feedback, comments, questions and patches are more than welcome. Please get in touch by opening an issue, it would be good to hear who is using the project and how things are going.

For more, see CONTRIBUTING.md.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Max 

func Max(x, y int) int

func Min 

func Min(x, y int) int

Golang Min/Max

func RegisterDevicetype 

func RegisterDevicetype(
	name string,
	imageSize image.Point,
	usbProductID uint16,
	resetPacket []byte,
	numberOfButtons uint,
	buttonRows uint,
	buttonCols uint,
	brightnessPacket []byte,
	buttonReadOffset uint,
	imageFormat string,
	imagePayloadPerPage uint,
	buttonMap map[uint]int,
	imageHeaderFunc func(bytesRemaining uint, btnIndex uint, pageNumber uint) []byte,
	imageAreaHeaderFunc func(bytesRemaining uint, x, y, width, height uint, pageNumber uint) []byte,
)

RegisterDevicetype allows the declaration of a new type of device, intended for use by subpackage "devices" 

func Search() []*deviceSearchResult

Search for streamdeck devices

Types

type Button 

type Button interface {
	ButtonDisplay
}

Button is the interface to satisfy for being a button; currently this is a direct proxy for the `ButtonDisplay` interface as there isn't a requirement to handle being pressed

type ButtonActionHandler 

type ButtonActionHandler interface {
	Pressed(Button)
}

ButtonActionHandler is the interface to satisfy for handling a button being pressed, generally via an `actionhandler`

type ButtonDecorator 

type ButtonDecorator interface {
	Apply(image.Image, int) image.Image
}

ButtonDecorator represents a way to modify the button image, for example to add a highlight or an "on/off" hint

type ButtonDisplay 

type ButtonDisplay interface {
	GetImageForButton(int) image.Image
	GetButtonIndex() int
	SetButtonIndex(int)
	RegisterUpdateHandler(func(Button))
	Pressed()
}

ButtonDisplay is the interface to satisfy for displaying on a button

type Device 

type Device struct {
	// contains filtered or unexported fields
}

Device is a struct which represents an actual Streamdeck device, and holds its reference to the USB HID device

func Open 

func Open() (*Device, error)

Open a Streamdeck device, the most common entry point

func OpenBySerial 

func OpenBySerial(serial string) (*Device, error)

Open a Streamdeck device, the most common entry point

func OpenWithoutReset 

func OpenWithoutReset() (*Device, error)

OpenWithoutReset will open a Streamdeck device, without resetting it

func (*Device) ButtonPress 

func (d *Device) ButtonPress(f func(int, *Device, error, bool))

ButtonPress registers a callback to be called whenever a button is pressed (or connection is lost!)

func (*Device) ClearButtons 

func (d *Device) ClearButtons()

ClearButtons writes a black square to all buttons

func (*Device) Close 

func (d *Device) Close()

Close the device

func (*Device) EncoderPress 

func (d *Device) EncoderPress(f func(int, *Device, bool))

EncoderPress registers a callback to be called whenever an encoder is pressed

func (*Device) EncoderRotate 

func (d *Device) EncoderRotate(f func(int, *Device, int))

EncoderRotate registers a callback to be called whenever an encoder is rotated

func (*Device) GetImageSize 

func (d *Device) GetImageSize() image.Point

GetImageSize returns the size of images on this Streamdeck

func (*Device) GetName 

func (d *Device) GetName() string

GetName returns the name of the type of Streamdeck

func (*Device) GetNumberOfButtons 

func (d *Device) GetNumberOfButtons() uint

func (*Device) GetSerial 

func (d *Device) GetSerial() string

GetSerial returns the device serial

func (*Device) GetUSBProductId 

func (d *Device) GetUSBProductId() int

func (*Device) HasImageCapability 

func (d *Device) HasImageCapability() bool

func (*Device) ResetComms 

func (d *Device) ResetComms()

ResetComms will reset the comms protocol to the StreamDeck; useful if things have gotten de-synced, but it will also reboot the StreamDeck

func (*Device) SetBrightness 

func (d *Device) SetBrightness(pct int)

SetBrightness sets the button brightness pct is an integer between 0-100

func (*Device) TouchPush 

func (d *Device) TouchPush(f func(*Device, uint16, uint16, bool))

TouchPush registers a callback to be called whenever the touch area is pushed (tap or hold)

func (*Device) TouchSwipe 

func (d *Device) TouchSwipe(f func(*Device, uint16, uint16, uint16, uint16))

TouchSwipe registers a callback to be called whenever the touch area is swiped

func (*Device) WriteColorToButton 

func (d *Device) WriteColorToButton(btnIndex int, colour color.Color) error

WriteColorToButton writes a specified color to the given button

func (*Device) WriteImageToButton 

func (d *Device) WriteImageToButton(btnIndex int, filename string) error

WriteImageToButton writes a specified image file to the given button

func (*Device) WriteRawImageToAreaUnscaled 

func (d *Device) WriteRawImageToAreaUnscaled(x, y int, rawImg image.Image) error

y doesn't work, keep it zero!

func (*Device) WriteRawImageToButton 

func (d *Device) WriteRawImageToButton(btnIndex int, rawImg image.Image) error

WriteRawImageToButton takes an `image.Image` and writes it to the given button, after resizing and rotating the image to fit the button (for some reason the StreamDeck screens are all upside down)

func (*Device) WriteTextToButton 

func (d *Device) WriteTextToButton(btnIndex int, text string, textColour color.Color, backgroundColour color.Color)

WriteTextToButton is a low-level way to write text directly onto a button on the StreamDeck

type StreamDeck 

type StreamDeck struct {
	// contains filtered or unexported fields
}

StreamDeck is the main struct to represent a StreamDeck device, and internally contains the reference to a `Device`

func New 

func New() (*StreamDeck, error)

New will return a new instance of a `StreamDeck`, and is the main entry point for the higher-level interface. It will return an error if there is no StreamDeck plugged in.

func (*StreamDeck) AddButton 

func (sd *StreamDeck) AddButton(btnIndex int, b Button)

AddButton adds a `Button` object to the StreamDeck at the specified index

func (*StreamDeck) ButtonUpdateHandler 

func (sd *StreamDeck) ButtonUpdateHandler(b Button)

ButtonUpdateHandler allows a user of this library to signal when something external has changed, such that this button should be update

func (*StreamDeck) GetButtonIndex 

func (sd *StreamDeck) GetButtonIndex(btnIndex int) Button

GetButtonByIndex returns a button for the given index

func (*StreamDeck) GetName 

func (sd *StreamDeck) GetName() string

GetName returns the name of the type of Streamdeck

func (*StreamDeck) SetBrightness 

func (sd *StreamDeck) SetBrightness(brightness int)

func (*StreamDeck) SetDecorator 

func (sd *StreamDeck) SetDecorator(btnIndex int, d ButtonDecorator)

SetDecorator imposes a ButtonDecorator onto a given button

func (*StreamDeck) UnsetDecorator 

func (sd *StreamDeck) UnsetDecorator(btnIndex int)

UnsetDecorator removes a ButtonDecorator from a given button

Source Files

View all Source files

Directories

Path Synopsis
examples
brightness
client
client2
client3
screenshot-command
test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.