api

package module
v2.0.0 Latest Latest
Warning

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

 Go to latest Published: Jun 23, 2025 License: BSD-3-Clause Imports: 15 Imported by: 0

README

Stream Deck 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 Stream Deck devices on Unix systems.

The library enables handling Stream Deck inputs (buttons, knobs, touch), managing icons and images, and communicating with the Stream Deck daemon via DBus.

Features

  • Connect to Stream Deck devices through the streamdeckd daemon
  • Handle button presses, knob rotations, and touch inputs
  • Create and manipulate images for Stream Deck displays
  • Manage device configurations and pages
  • Draw text on Stream Deck buttons with customizable fonts and alignments
  • Resize images to fit Stream Deck displays
  • OBS integration support

Installation

go get github.com/unix-streamdeck/api

Usage

Connecting to the Stream Deck daemon
import "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
}
Working with images
import (
    "github.com/unix-streamdeck/api"
    "image"
    _ "image/png" // Import for PNG support
    "os"
)

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

// Resize image to fit a Stream Deck key
resizedImg := api.ResizeImage(img, 72) // 72x72 pixels

// 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
}

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
  • KnobOrTouchHandler: For handling knob rotations and touch events

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
}

// Reload configuration from disk
err = conn.ReloadConfig()

// Commit configuration changes to disk
err = conn.CommitConfig()
Custom GUI Config Editors

The library provides the Module and Field types that can be used to create custom GUI configuration editors:

// Get available modules
modules, err := conn.GetModules()
if err != nil {
    // Handle error
}

// Get OBS-specific fields
obsFields, err := conn.GetObsFields()
if err != nil {
    // Handle error
}

Help Wanted!

If you want to help with the development of streamdeckd and its related repos, either by submitting code, finding/fixing bugs, or just replying to issues, please join this discord server: https://discord.gg/nyhuVEJWMQ

License

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

Documentation

Overview

Package mocks is a generated GoMock package.

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 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) 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"`
	Buff              image.Image       `json:"-"`
	IconHandlerStruct IconHandler       `json:"-"`
	KeyHandlerStruct  KeyHandler        `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"`
	KnobPressAction          KnobActionV3       `json:"knob_press_action,omitempty"`
	KnobTurnUpAction         KnobActionV3       `json:"knob_turn_up_action,omitempty"`
	KnobTurnDownAction       KnobActionV3       `json:"knob_turn_down_action,omitempty"`
}

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 MockBusObject 

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

MockBusObject is a mock of BusObject interface.

func NewMockBusObject 

func NewMockBusObject(ctrl *gomock.Controller) *MockBusObject

NewMockBusObject creates a new mock instance.

func (*MockBusObject) AddMatchSignal 

func (m *MockBusObject) AddMatchSignal(arg0, arg1 string, arg2 ...dbus.MatchOption) *dbus.Call

AddMatchSignal mocks base method.

func (*MockBusObject) Call 

func (m *MockBusObject) Call(arg0 string, arg1 dbus.Flags, arg2 ...interface{}) *dbus.Call

Call mocks base method.

func (*MockBusObject) CallWithContext 

func (m *MockBusObject) CallWithContext(arg0 context.Context, arg1 string, arg2 dbus.Flags, arg3 ...interface{}) *dbus.Call

CallWithContext mocks base method.

func (*MockBusObject) Destination 

func (m *MockBusObject) Destination() string

Destination mocks base method.

func (*MockBusObject) EXPECT 

func (m *MockBusObject) EXPECT() *MockBusObjectMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockBusObject) GetProperty 

func (m *MockBusObject) GetProperty(arg0 string) (dbus.Variant, error)

GetProperty mocks base method.

func (*MockBusObject) Go 

func (m *MockBusObject) Go(arg0 string, arg1 dbus.Flags, arg2 chan *dbus.Call, arg3 ...interface{}) *dbus.Call

Go mocks base method.

func (*MockBusObject) GoWithContext 

func (m *MockBusObject) GoWithContext(arg0 context.Context, arg1 string, arg2 dbus.Flags, arg3 chan *dbus.Call, arg4 ...interface{}) *dbus.Call

GoWithContext mocks base method.

func (*MockBusObject) Path 

func (m *MockBusObject) Path() dbus.ObjectPath

Path mocks base method.

func (*MockBusObject) RemoveMatchSignal 

func (m *MockBusObject) RemoveMatchSignal(arg0, arg1 string, arg2 ...dbus.MatchOption) *dbus.Call

RemoveMatchSignal mocks base method.

func (*MockBusObject) SetProperty 

func (m *MockBusObject) SetProperty(arg0 string, arg1 interface{}) error

SetProperty mocks base method.

func (*MockBusObject) StoreProperty 

func (m *MockBusObject) StoreProperty(arg0 string, arg1 interface{}) error

StoreProperty mocks base method.

type MockBusObjectMockRecorder 

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

MockBusObjectMockRecorder is the mock recorder for MockBusObject.

func (*MockBusObjectMockRecorder) AddMatchSignal 

func (mr *MockBusObjectMockRecorder) AddMatchSignal(arg0, arg1 interface{}, arg2 ...interface{}) *gomock.Call

AddMatchSignal indicates an expected call of AddMatchSignal.

func (*MockBusObjectMockRecorder) Call 

func (mr *MockBusObjectMockRecorder) Call(arg0, arg1 interface{}, arg2 ...interface{}) *gomock.Call

Call indicates an expected call of Call.

func (*MockBusObjectMockRecorder) CallWithContext 

func (mr *MockBusObjectMockRecorder) CallWithContext(arg0, arg1, arg2 interface{}, arg3 ...interface{}) *gomock.Call

CallWithContext indicates an expected call of CallWithContext.

func (*MockBusObjectMockRecorder) Destination 

func (mr *MockBusObjectMockRecorder) Destination() *gomock.Call

Destination indicates an expected call of Destination.

func (*MockBusObjectMockRecorder) GetProperty 

func (mr *MockBusObjectMockRecorder) GetProperty(arg0 interface{}) *gomock.Call

GetProperty indicates an expected call of GetProperty.

func (*MockBusObjectMockRecorder) Go 

func (mr *MockBusObjectMockRecorder) Go(arg0, arg1, arg2 interface{}, arg3 ...interface{}) *gomock.Call

Go indicates an expected call of Go.

func (*MockBusObjectMockRecorder) GoWithContext 

func (mr *MockBusObjectMockRecorder) GoWithContext(arg0, arg1, arg2, arg3 interface{}, arg4 ...interface{}) *gomock.Call

GoWithContext indicates an expected call of GoWithContext.

func (*MockBusObjectMockRecorder) Path 

func (mr *MockBusObjectMockRecorder) Path() *gomock.Call

Path indicates an expected call of Path.

func (*MockBusObjectMockRecorder) RemoveMatchSignal 

func (mr *MockBusObjectMockRecorder) RemoveMatchSignal(arg0, arg1 interface{}, arg2 ...interface{}) *gomock.Call

RemoveMatchSignal indicates an expected call of RemoveMatchSignal.

func (*MockBusObjectMockRecorder) SetProperty 

func (mr *MockBusObjectMockRecorder) SetProperty(arg0, arg1 interface{}) *gomock.Call

SetProperty indicates an expected call of SetProperty.

func (*MockBusObjectMockRecorder) StoreProperty 

func (mr *MockBusObjectMockRecorder) StoreProperty(arg0, arg1 interface{}) *gomock.Call

StoreProperty indicates an expected call of StoreProperty.

type Module 

type Module struct {
	Name       string  `json:"name,omitempty"`
	IconFields []Field `json:"icon_fields,omitempty"`
	KeyFields  []Field `json:"key_fields,omitempty"`
	IsIcon     bool    `json:"is_icon,omitempty"`
	IsKey      bool    `json:"is_key,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

Directories

Path Synopsis

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.