api

package module
v2.0.9 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2026 License: BSD-3-Clause Imports: 14 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

This section is empty.

Variables

This section is empty.

Functions

func CompareKeyConfigs 

func CompareKeyConfigs(c1 KeyConfigV3, c2 KeyConfigV3) bool

func CompareKeys 

func CompareKeys(k1 KeyV3, k2 KeyV3) bool

func DrawText 

func DrawText(currentImage image.Image, text string, fontSize int, fontAlignment string) (image.Image, error)

func FindXDoToolKeybindString added in v2.0.4 

func FindXDoToolKeybindString(code int) string

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

Types

type Config 

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

type ConfigV1 

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

type ConfigV2 

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

type ConfigV3 

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

type Conn 

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

func (*Conn) AddMatchSignal 

func (c *Conn) AddMatchSignal(options ...dbus.MatchOption) error

func (*Conn) Close 

func (c *Conn) Close() error

func (*Conn) Signal 

func (c *Conn) Signal(ch chan<- *dbus.Signal)

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 DeckV2 

type DeckV2 struct {
	Serial string   `json:"serial"`
	Pages  []PageV1 `json:"pages"`
}

type DeckV3 

type DeckV3 struct {
	Serial string   `json:"serial"`
	Pages  []PageV3 `json:"pages"`
}

type DepracatedConfig 

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

type Field 

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

type Handler 

type Handler interface {
}

type IConn 

type IConn interface {
	Close() error
	AddMatchSignal(options ...dbus.MatchOption) error
	Signal(ch chan<- *dbus.Signal)
}

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"`
	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 KeyHandler 

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

type KeyV1 

type KeyV1 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"`
	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"`
	Buff              image.Image       `json:"-"`
	IconHandlerStruct IconHandler       `json:"-"`
	KeyHandlerStruct  KeyHandler        `json:"-"`
}

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"`
	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:"-"`
}

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:"-"`
}

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 PageV1 

type PageV1 []KeyV1

type PageV3 

type PageV3 struct {
	Keys  []KeyV3  `json:"keys"`
	Knobs []KnobV3 `json:"knobs"`
}

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"`
}

Source Files

View all Source files

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.