api

package module
v2.0.14 Latest Latest
Warning

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

 Go to latest Published: Mar 13, 2026 License: BSD-3-Clause Imports: 30 Imported by: 2

README

StreamDeck API for Unix

This is a Go library for the streamdeckd daemon, not a standalone application. It provides interfaces for connecting to the daemon, accessing configuration objects, and creating custom handlers or GUI config editors for Elgato StreamDeck devices on Unix systems.

The library exposes an API for creating custom plugins to handle Stream Deck inputs (buttons, knobs, touch), managing icons and images, and also for communicating with the streamdeckd daemon via DBus.

Installation

go get github.com/unix-streamdeck/api

Usage

Connecting to the Stream Deck daemon
import (
    "fmt"
    "github.com/unix-streamdeck/api"
)

// Connect to the Stream Deck daemon
conn, err := api.Connect()
if err != nil {
    // Handle error
}
defer conn.Close()

// Get information about connected Stream Deck devices
devices, err := conn.GetInfo()
if err != nil {
    // Handle error
}

// Listen for page changes
err = conn.RegisterPageListener(func(serial string, page int32) {
    fmt.Printf("Device %s changed to page %d\n", serial, page)
})
Working with images
import (
    "github.com/unix-streamdeck/api"
    "image"
    _ "image/png"
    "os"
)

// Load an image
file, _ := os.Open("icon.png")
img, _, _ := image.Decode(file)

// Resize image to fit a Stream Deck key, ideally pass the `IconSize` field from `StreamDeckInfoV1` rather than magic num,ber
resizedImg := api.ResizeImage(img, 72) // 72x72 pixels

// Resize image with specific width and height (e.g., for LCD display) (`LcdWidth` and `LcdHeight` in `StreamDeckInfoV1`)
resizedLcdImg := api.ResizeImageWH(img, 800, 100)

// Add text to an image
imgWithText, _ := api.DrawText(resizedImg, "Hello", 0, "CENTER")
Implementing handlers
// Implement a key handler
type MyKeyHandler struct{}

func (h *MyKeyHandler) Key(key api.KeyConfigV3, info api.StreamDeckInfoV1) {
    // Handle key press
}

// Implement an icon handler
type MyIconHandler struct {
    running bool
}

func (h *MyIconHandler) Start(key api.KeyConfigV3, info api.StreamDeckInfoV1, callback func(image image.Image)) {
    h.running = true
    // Generate and update icon
    // Call callback with new images when needed
}

func (h *MyIconHandler) IsRunning() bool {
    return h.running
}

func (h *MyIconHandler) SetRunning(running bool) {
    h.running = running
}

func (h *MyIconHandler) Stop() {
    h.running = false
    // Clean up resources and stop calling callback
}

// Implement an LCD handler (for Stream Deck Plus)
type MyLcdHandler struct {
    running bool
}

func (h *MyLcdHandler) Start(knob api.KnobConfigV3, info api.StreamDeckInfoV1, callback func(image image.Image)) {
    h.running = true
    // Generate and update LCD image
}

func (h *MyLcdHandler) IsRunning() bool {
    return h.running
}

func (h *MyLcdHandler) SetRunning(running bool) {
    h.running = running
}

func (h *MyLcdHandler) Stop() {
    h.running = false
}

// Implement a knob or touch handler (for Stream Deck Plus)
type MyKnobHandler struct{}

func (h *MyKnobHandler) Input(knob api.KnobConfigV3, info api.StreamDeckInfoV1, event api.InputEvent) {
    switch event.EventType {
    case api.KNOB_CW:
        // Handle clockwise rotation
    case api.KNOB_CCW:
        // Handle counter-clockwise rotation
    case api.KNOB_PRESS:
        // Handle knob press
    }
}

API Documentation

The API provides several interfaces for handling Stream Deck interactions:

  • Handler: Base interface for all handlers
  • IconHandler: For handling dynamic icons/images
  • KeyHandler: For handling key press events
  • LcdHandler: For handling LCD displays (Stream Deck Plus)
  • KnobOrTouchHandler: For handling knob rotations and touch events (Stream Deck Plus)

Key components:

  • Connection: Manages DBus communication with the Stream Deck daemon
  • Image utilities: Functions for drawing text and resizing images
  • Configuration management: Functions for getting and setting device configurations
Configuration Objects

The library exposes configuration objects that can be used to interact with the streamdeckd daemon:

// Get the current configuration
config, err := conn.GetConfig()
if err != nil {
    // Handle error
}

// Modify configuration
// ...

// Set the updated configuration
err = conn.SetConfig(config)
if err != nil {
    // Handle error
}


// Commit configuration changes to disk
err = conn.CommitConfig()

// Or Reload configuration from disk if the changes weren't correct
err = conn.ReloadConfig()

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Documentation

Index

Constants

View Source 
const BorderClearance = 10

Variables

This section is empty.

Functions

func DrawProgressBar added in v2.0.11 

func DrawProgressBar(img image.Image, label string, x, y, h, w, progress float64) (image.Image, error)

func DrawProgressBarWithAccent added in v2.0.11 

func DrawProgressBarWithAccent(img image.Image, label string, x, y, h, w, progress float64, hex string) (image.Image, error)

func DrawText 

func DrawText(img image.Image, text string, options DrawTextOptions) (image.Image, error)

func FindXDoToolKeybindString added in v2.0.4 

func FindXDoToolKeybindString(code int) string

func HexColor added in v2.0.11 

func HexColor(hex string) color.RGBA

func LayerImages added in v2.0.12 

func LayerImages(background, foreground image.Image) (image.Image, error)

func ParseXDoToolKeybindString added in v2.0.4 

func ParseXDoToolKeybindString(keybind string) ([]int, error)

func ResizeImage 

func ResizeImage(img image.Image, keySize int) image.Image

func ResizeImageWH 

func ResizeImageWH(img image.Image, width int, height int) image.Image

func SubImage added in v2.0.14 

func SubImage(img image.Image, x0, y0, x1, y1 int) image.Image

Types

type Config 

type Config struct {
	Modules []string `json:"modules,omitempty"`
	Decks   []Deck   `json:"decks"`
}

type ConfigV3 

type ConfigV3 struct {
	Modules           []string            `json:"modules,omitempty"`
	Decks             []DeckV3            `json:"decks"`
	ObsConnectionInfo ObsConnectionInfoV2 `json:"obs_connection_info,omitempty"`
}

type Connection 

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

func Connect 

func Connect() (*Connection, error)

func (*Connection) Close 

func (c *Connection) Close()

func (*Connection) CommitConfig 

func (c *Connection) CommitConfig() error

func (*Connection) GetConfig 

func (c *Connection) GetConfig() (*ConfigV3, error)

func (*Connection) GetHandlerExample 

func (c *Connection) GetHandlerExample(serial string, keyConfig KeyConfigV3) (image.Image, error)

func (*Connection) GetInfo 

func (c *Connection) GetInfo() ([]*StreamDeckInfoV1, error)

func (*Connection) GetKnobHandlerExample added in v2.0.1 

func (c *Connection) GetKnobHandlerExample(serial string, knobConfig KnobConfigV3) (image.Image, error)

func (*Connection) GetModules 

func (c *Connection) GetModules() ([]*Module, error)

func (*Connection) GetObsFields 

func (c *Connection) GetObsFields() ([]*Field, error)

func (*Connection) PressButton 

func (c *Connection) PressButton(serial string, keyIndex int) error

func (*Connection) RegisterPageListener 

func (c *Connection) RegisterPageListener(cback func(string, int32)) error

func (*Connection) ReloadConfig 

func (c *Connection) ReloadConfig() error

func (*Connection) SetConfig 

func (c *Connection) SetConfig(config *ConfigV3) error

func (*Connection) SetPage 

func (c *Connection) SetPage(serial string, page int) error

type Deck 

type Deck struct {
	Serial string `json:"serial"`
	Pages  []Page `json:"pages"`
}

type DeckV3 

type DeckV3 struct {
	Serial                   string      `json:"serial"`
	Pages                    []PageV3    `json:"pages"`
	TouchPanelBackground     string      `json:"touch_panel_background"`
	TouchPanelBackgroundBuff image.Image `json:"-"`
	KeyGridBackground        string      `json:"key_grid_background"`
	KeyGridBackgroundBuff    image.Image `json:"-"`
}

func (*DeckV3) GetKeyGridBackground added in v2.0.14 

func (d *DeckV3) GetKeyGridBackground() string

func (*DeckV3) GetKeyGridBackgroundBuff added in v2.0.14 

func (d *DeckV3) GetKeyGridBackgroundBuff() image.Image

func (*DeckV3) GetTouchPanelBackground added in v2.0.13 

func (d *DeckV3) GetTouchPanelBackground() string

func (*DeckV3) GetTouchPanelBackgroundBuff added in v2.0.13 

func (d *DeckV3) GetTouchPanelBackgroundBuff() image.Image

func (*DeckV3) SetKeyGridBackgroundBuff added in v2.0.14 

func (d *DeckV3) SetKeyGridBackgroundBuff(img image.Image)

func (*DeckV3) SetTouchPanelBackgroundBuff added in v2.0.13 

func (d *DeckV3) SetTouchPanelBackgroundBuff(img image.Image)

type DepracatedConfig 

type DepracatedConfig struct {
	Modules []string `json:"modules,omitempty"`
	Pages   []Page   `json:"pages"`
}

type DrawTextOptions added in v2.0.10 

type DrawTextOptions struct {
	FontSize          int64
	VerticalAlignment VerticalAlignment
	FontFace          string
	Colour            string
}

type Field 

type Field struct {
	Title     string    `json:"title,omitempty"`
	Name      string    `json:"name,omitempty"`
	Type      FieldType `json:"type,omitempty"`
	FileTypes []string  `json:"file_types,omitempty"`
	ListItems []string  `json:"list_items,omitempty"`
}

type FieldType added in v2.0.10 

type FieldType string
const (
	File          FieldType = "File"
	Text          FieldType = "Text"
	Number        FieldType = "Number"
	TextAlignment FieldType = "TextAlignment"
	FontFace      FieldType = "FontFace"
	Select        FieldType = "Select"
	Colour        FieldType = "Colour"
)

type Handler 

type Handler interface {
}

type IConn 

type IConn interface {
	Close() error
	AddMatchSignal(options ...dbus.MatchOption) error
	Signal(ch chan<- *dbus.Signal)
	Object(dest string, path dbus.ObjectPath) dbus.BusObject
}

type IContext added in v2.0.10 

type IContext interface {
	SetRGB(r, g, b float64)
	SetHexColor(color string)
	SetFontFace(font font.Face)
	WordWrap(text string, width float64) []string
	DrawStringWrapped(s string, x, y, ax, ay, width, lineSpacing float64, align gg.Align)
	Image() image.Image
	MeasureMultilineString(text string, lineSpacing float64) (float64, float64)
	Width() int
	Height() int
}

type IconHandler 

type IconHandler interface {
	Handler
	Start(key KeyConfigV3, info StreamDeckInfoV1, callback func(image image.Image))
	IsRunning() bool
	SetRunning(running bool)
	Stop()
}

type InputEvent 

type InputEvent struct {
	EventType     InputEventType
	RotateNotches uint8
}

type InputEventType 

type InputEventType uint8
const (
	KNOB_CCW InputEventType = iota
	KNOB_CW
	KNOB_PRESS
	SCREEN_SHORT_TAP
	SCREEN_LONG_TAP
)

type Key 

type Key struct {
	Icon              string            `json:"icon,omitempty"`
	SwitchPage        int               `json:"switch_page,omitempty"`
	Text              string            `json:"text,omitempty"`
	TextSize          int               `json:"text_size,omitempty"`
	TextAlignment     string            `json:"text_alignment,omitempty"`
	Keybind           string            `json:"keybind,omitempty"`
	Command           string            `json:"command,omitempty"`
	Brightness        int               `json:"brightness,omitempty"`
	Url               string            `json:"url,omitempty"`
	IconHandler       string            `json:"icon_handler,omitempty"`
	KeyHandler        string            `json:"key_handler,omitempty"`
	IconHandlerFields map[string]string `json:"icon_handler_fields,omitempty"`
	KeyHandlerFields  map[string]string `json:"key_handler_fields,omitempty"`
	Buff              image.Image       `json:"-"`
	IconHandlerStruct IconHandler       `json:"-"`
	KeyHandlerStruct  KeyHandler        `json:"-"`
}

type KeyConfigV3 

type KeyConfigV3 struct {
	Icon                string            `json:"icon,omitempty"`
	SwitchPage          int               `json:"switch_page,omitempty"`
	Text                string            `json:"text,omitempty"`
	TextSize            int               `json:"text_size,omitempty"`
	TextAlignment       string            `json:"text_alignment,omitempty"`
	FontFace            string            `json:"font_face,omitempty"`
	TextColour          string            `json:"text_colour,omitempty"`
	Keybind             string            `json:"keybind,omitempty"`
	Command             string            `json:"command,omitempty"`
	Brightness          int               `json:"brightness,omitempty"`
	Url                 string            `json:"url,omitempty"`
	KeyHold             int               `json:"key_hold,omitempty"`
	ObsCommand          string            `json:"obs_command,omitempty"`
	ObsCommandParams    map[string]string `json:"obs_command_params,omitempty"`
	IconHandler         string            `json:"icon_handler,omitempty"`
	KeyHandler          string            `json:"key_handler,omitempty"`
	IconHandlerFields   map[string]any    `json:"icon_handler_fields,omitempty"`
	KeyHandlerFields    map[string]any    `json:"key_handler_fields,omitempty"`
	SharedHandlerFields map[string]any    `json:"shared_handler_fields,omitempty"`
	Buff                image.Image       `json:"-"`
	IconHandlerStruct   IconHandler       `json:"-"`
	KeyHandlerStruct    KeyHandler        `json:"-"`
	SharedState         map[string]any    `json:"-"`
}

type KeyGridBackgrounder added in v2.0.14 

type KeyGridBackgrounder interface {
	GetKeyGridBackground() string
	GetKeyGridBackgroundBuff() image.Image
	SetKeyGridBackgroundBuff(img image.Image)
}

type KeyHandler 

type KeyHandler interface {
	Handler
	Key(key KeyConfigV3, info StreamDeckInfoV1)
}

type KeyV3 

type KeyV3 struct {
	Application             map[string]*KeyConfigV3 `json:"application,omitempty"`
	ActiveBuff              image.Image             `json:"-"`
	ActiveIconHandlerStruct *IconHandler            `json:"-"`
	ActiveKeyHandlerStruct  *KeyHandler             `json:"-"`
	ActiveApplication       string                  `json:"-"`
}

type KnobActionV3 

type KnobActionV3 struct {
	SwitchPage       int               `json:"switch_page,omitempty"`
	Keybind          string            `json:"keybind,omitempty"`
	Command          string            `json:"command,omitempty"`
	Brightness       int               `json:"brightness,omitempty"`
	Url              string            `json:"url,omitempty"`
	ObsCommand       string            `json:"obs_command,omitempty"`
	ObsCommandParams map[string]string `json:"obs_command_params,omitempty"`
}

type KnobConfigV3 

type KnobConfigV3 struct {
	Icon                     string             `json:"icon,omitempty"`
	Text                     string             `json:"text,omitempty"`
	TextSize                 int                `json:"text_size,omitempty"`
	TextAlignment            string             `json:"text_alignment,omitempty"`
	FontFace                 string             `json:"font_face,omitempty"`
	TextColour               string             `json:"text_colour,omitempty"`
	LcdHandler               string             `json:"lcd_handler,omitempty"`
	KnobOrTouchHandler       string             `json:"knob_or_touch_handler,omitempty"`
	Buff                     image.Image        `json:"-"`
	LcdHandlerStruct         LcdHandler         `json:"-"`
	KnobOrTouchHandlerStruct KnobOrTouchHandler `json:"-"`
	LcdHandlerFields         map[string]any     `json:"lcd_handler_fields,omitempty"`
	KnobOrTouchHandlerFields map[string]any     `json:"knob_or_touch_handler_fields,omitempty"`
	SharedHandlerFields      map[string]any     `json:"shared_handler_fields,omitempty"`
	KnobPressAction          KnobActionV3       `json:"knob_press_action,omitempty"`
	KnobTurnUpAction         KnobActionV3       `json:"knob_turn_up_action,omitempty"`
	KnobTurnDownAction       KnobActionV3       `json:"knob_turn_down_action,omitempty"`
	SharedState              map[string]any     `json:"-"`
	TouchPanelBackground     string             `json:"touch_panel_background"`
	TouchPanelBackgroundBuff image.Image        `json:"-"`
}

func (*KnobConfigV3) GetTouchPanelBackground added in v2.0.13 

func (kc *KnobConfigV3) GetTouchPanelBackground() string

func (*KnobConfigV3) GetTouchPanelBackgroundBuff added in v2.0.13 

func (kc *KnobConfigV3) GetTouchPanelBackgroundBuff() image.Image

func (*KnobConfigV3) SetTouchPanelBackgroundBuff added in v2.0.13 

func (kc *KnobConfigV3) SetTouchPanelBackgroundBuff(img image.Image)

type KnobOrTouchHandler 

type KnobOrTouchHandler interface {
	Handler
	Input(key KnobConfigV3, info StreamDeckInfoV1, event InputEvent)
}

type KnobV3 

type KnobV3 struct {
	Application              map[string]*KnobConfigV3 `json:"application,omitempty"`
	ActiveBuff               image.Image              `json:"-"`
	ActiveApplication        string                   `json:"-"`
	TouchPanelBackground     string                   `json:"touch_panel_background"`
	TouchPanelBackgroundBuff image.Image              `json:"-"`
}

func (*KnobV3) GetTouchPanelBackground added in v2.0.13 

func (k *KnobV3) GetTouchPanelBackground() string

func (*KnobV3) GetTouchPanelBackgroundBuff added in v2.0.13 

func (k *KnobV3) GetTouchPanelBackgroundBuff() image.Image

func (*KnobV3) SetTouchPanelBackgroundBuff added in v2.0.13 

func (k *KnobV3) SetTouchPanelBackgroundBuff(img image.Image)

type LcdBackgrounder added in v2.0.14 

type LcdBackgrounder interface {
	GetTouchPanelBackground() string
	GetTouchPanelBackgroundBuff() image.Image
	SetTouchPanelBackgroundBuff(img image.Image)
}

type LcdHandler 

type LcdHandler interface {
	Handler
	Start(key KnobConfigV3, info StreamDeckInfoV1, callback func(image image.Image))
	IsRunning() bool
	SetRunning(running bool)
	Stop()
}

type Module 

type Module struct {
	Name              string                    `json:"name,omitempty"`
	NewIcon           func() IconHandler        `json:"-"`
	NewKey            func() KeyHandler         `json:"-"`
	NewLcd            func() LcdHandler         `json:"-"`
	NewKnobOrTouch    func() KnobOrTouchHandler `json:"-"`
	IconFields        []Field                   `json:"icon_fields,omitempty"`
	KeyFields         []Field                   `json:"key_fields,omitempty"`
	LcdFields         []Field                   `json:"lcd_fields,omitempty"`
	KnobOrTouchFields []Field                   `json:"knob_or_touch_fields,omitempty"`
	LinkedFields      []Field                   `json:"linked_fields,omitempty"`
	IsIcon            bool                      `json:"is_icon,omitempty"`
	IsKey             bool                      `json:"is_key,omitempty"`
	IsLcd             bool                      `json:"is_lcd,omitempty"`
	IsKnob            bool                      `json:"is_knob,omitempty"`
	IsLinkedHandlers  bool                      `json:"is_linked_handlers,omitempty"`
	Linked            bool                      `json:"linked,omitempty"`
}

type ObsConnectionInfoV2 

type ObsConnectionInfoV2 struct {
	Host string `json:"host,omitempty"`
	Port int    `json:"port,omitempty"`
}

type Page 

type Page []Key

type PageV3 

type PageV3 struct {
	Keys                     []KeyV3     `json:"keys"`
	Knobs                    []KnobV3    `json:"knobs"`
	TouchPanelBackground     string      `json:"touch_panel_background"`
	TouchPanelBackgroundBuff image.Image `json:"-"`
	KeyGridBackground        string      `json:"key_grid_background"`
	KeyGridBackgroundBuff    image.Image `json:"-"`
}

func (*PageV3) GetKeyGridBackground added in v2.0.14 

func (p *PageV3) GetKeyGridBackground() string

func (*PageV3) GetKeyGridBackgroundBuff added in v2.0.14 

func (p *PageV3) GetKeyGridBackgroundBuff() image.Image

func (*PageV3) GetTouchPanelBackground added in v2.0.13 

func (p *PageV3) GetTouchPanelBackground() string

func (*PageV3) GetTouchPanelBackgroundBuff added in v2.0.13 

func (p *PageV3) GetTouchPanelBackgroundBuff() image.Image

func (*PageV3) SetKeyGridBackgroundBuff added in v2.0.14 

func (p *PageV3) SetKeyGridBackgroundBuff(img image.Image)

func (*PageV3) SetTouchPanelBackgroundBuff added in v2.0.13 

func (p *PageV3) SetTouchPanelBackgroundBuff(img image.Image)

type StreamDeckInfo 

type StreamDeckInfo struct {
	Cols     int    `json:"cols,omitempty"`
	Rows     int    `json:"rows,omitempty"`
	IconSize int    `json:"icon_size,omitempty"`
	Page     int    `json:"page"`
	Serial   string `json:"serial,omitempty"`
}

type StreamDeckInfoV1 

type StreamDeckInfoV1 struct {
	Cols             int       `json:"cols,omitempty"`
	Rows             int       `json:"rows,omitempty"`
	IconSize         int       `json:"icon_size,omitempty"`
	Page             int       `json:"page"`
	Serial           string    `json:"serial,omitempty"`
	Name             string    `json:"name,omitempty"`
	Connected        bool      `json:"connected"`
	LastConnected    time.Time `json:"last_connected,omitempty"`
	LastDisconnected time.Time `json:"last_disconnected,omitempty"`
	LcdWidth         int       `json:"lcd_width,omitempty"`
	LcdHeight        int       `json:"lcd_height,omitempty"`
	LcdCols          int       `json:"lcd_cols,omitempty"`
	KnobCols         int       `json:"knob_cols,omitempty"`
}

type VerticalAlignment added in v2.0.10 

type VerticalAlignment string

TODO replace use of gg with native font.Drawer 

const (
	Top    VerticalAlignment = "TOP"
	Center VerticalAlignment = "CENTER"
	Bottom VerticalAlignment = "BOTTOM"
)

Source Files

View all Source files

Directories

Path Synopsis
mocks
mock_api
Package mock_api is a generated GoMock package.
 Package mock_api is a generated GoMock package.
mock_dbus
Package mock_dbus is a generated GoMock package.
 Package mock_dbus is a generated GoMock package.

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.