goobs

README

goobs

Interact with OBS Studio from Go!

installation

To use this library in your project, add it as a module after you've initialized your own:

❯ go mod init github.com/beautifulperson/my-cool-obs-thing
❯ go get github.com/onthegit/goobs

usage

The following example connects to the server and prints out some versions.

Check out the docs for more info, or just jump right into the other examples!

package main

import (
	"fmt"

	"github.com/onthegit/goobs"
)

func main() {
	client, err := goobs.New("localhost:4455", goobs.WithPassword("goodpassword"))
	if err != nil {
		panic(err)
	}
	defer client.Disconnect()

	version, err := client.General.GetVersion()
	if err != nil {
		panic(err)
	}

	fmt.Printf("OBS Studio version: %s\n", version.ObsVersion)
	fmt.Printf("Server protocol version: %s\n", version.ObsWebSocketVersion)
	fmt.Printf("Client protocol version: %s\n", goobs.ProtocolVersion)
	fmt.Printf("Client library version: %s\n", goobs.LibraryVersion)
}

The corresponding output:

❯ go run _examples/basic/main.go
OBS Studio version: 30.1.0
Server protocol version: 5.4.2
Client protocol version: 5.4.2
Client library version: 1.2.2

Documentation

Index

• Variables
• type Categories
• type Client
  • func New(host string, opts ...Option) (*Client, error)
  • func (c *Client) Disconnect() error
  • func (c *Client) Listen(f func(any))
• type Option
  • func WithDialer(x *websocket.Dialer) Option
  • func WithEventSubscriptions(x int) Option
  • func WithLogger(x api.Logger) Option
  • func WithPassword(x string) Option
  • func WithRequestHeader(x http.Header) Option
  • func WithResponseTimeout(x time.Duration) Option

Variables

var LibraryVersion = func() string {
	bi, ok := debug.ReadBuildInfo()
	if !ok {
		return "unknown"
	}

	for _, dep := range bi.Deps {
		if dep.Path == lib {
			return strings.TrimPrefix(dep.Version, "v")
		}
	}

	return "unknown"
}()

var ProtocolVersion = "5.4.2"

Types

type Categories

type Categories struct {
	Config      *config.Client
	Filters     *filters.Client
	General     *general.Client
	Inputs      *inputs.Client
	MediaInputs *mediainputs.Client
	Outputs     *outputs.Client
	Record      *record.Client
	SceneItems  *sceneitems.Client
	Scenes      *scenes.Client
	Sources     *sources.Client
	Stream      *stream.Client
	Transitions *transitions.Client
	Ui          *ui.Client
}

type Client

type Client struct {
	// See [Client.Listen] for more information.
	IncomingEvents chan any

	Categories
	// contains filtered or unexported fields
}

Client represents a client to an OBS websockets server.

func New

func New(host string, opts ...Option) (*Client, error)

New creates and configures a client to interact with the OBS websockets server. It also opens up a connection, so be sure to check the error.

func (*Client) Disconnect

func (c *Client) Disconnect() error

Disconnect sends a message to the OBS websocket server to close the client's open connection. You should defer a disconnection after creating your client to ensure the program doesn't leave any lingering connections open and potentially leak memory, e.g.:

client, err := goobs.New("localhost:4455", goobs.WithPassword("secret"))
if err != nil {
	panic(err)
}
defer client.Disconnect()

func (*Client) Listen

func (c *Client) Listen(f func(any))

Listen hooks into the incoming events from the server. You'll have to make type assertions to ensure you're getting the right events, e.g.:

client.Listen(func(event any) {
	switch val := event.(type) {
	case *events.InputVolumeChanged:
		// event i was looking for
	default:
		// other events
	}
})

If looking for high volume events, make sure you've initialized the client with the appropriate subscriptions with WithEventSubscriptions.

type Option

type Option func(*Client)

Option represents a functional option of a Client.

func WithDialer

func WithDialer(x *websocket.Dialer) Option

WithDialer sets the underlying gorilla/websocket.Dialer should one want to customize things like the handshake timeout or TLS configuration. If this is not set, it'll use the provided gorilla/websocket.DefaultDialer.

func WithEventSubscriptions

func WithEventSubscriptions(x int) Option

WithEventSubscriptions specifies the events we'd like to subscribe to via Client.Listen. The value is a bitmask of any of the subscription values specified in subscriptions. By default, all event categories are subscribed, except for events marked as high volume. High volume events must be explicitly subscribed to.

func WithLogger

func WithLogger(x api.Logger) Option

WithLogger sets the logger this library will use. See the logger.Logger interface. Should be compatible with most third-party loggers.

func WithPassword

func WithPassword(x string) Option

WithPassword sets the password of a client.

func WithRequestHeader

func WithRequestHeader(x http.Header) Option

WithRequestHeader sets custom headers our client can send when trying to connect to the WebSockets server, allowing us specify the origin, subprotocols, or the user agent.

func WithResponseTimeout

func WithResponseTimeout(x time.Duration) Option

WithResponseTimeout sets the time we're willing to wait to receive a response from the server for any request, before responding with an error. It's in milliseconds. The default timeout is 10 seconds.