goobs

README

goobs

It's a Go client for Palakis/obs-websocket, allowing us to interact with OBS Studio via Go.

installation

To add this client library to your module, simply go get it like any other Go module after you've initialized your own:

❯ go mod init blah
❯ go get github.com/andreykaipov/goobs

usage

Usage is best demonstrated through example! Here's examples/sources/main.go, showcasing both the eventing and requests API. For brevity, error checks in a few places are omitted:

package main

import ...

func main() {
	client, err := goobs.New(
		os.Getenv("WSL_HOST")+":4444",
		goobs.WithPassword("hello"),                   // optional
		goobs.WithDebug(os.Getenv("OBS_DEBUG") != ""), // optional
	)
	if err != nil {
		panic(err)
	}

	go func() {
		for event := range client.IncomingEvents {
			switch e := event.(type) {
			case *events.SourceVolumeChanged:
				fmt.Printf("Volume changed for %-25q: %f\n", e.SourceName, e.Volume)
			default:
				log.Printf("Unhandled event: %#v", e.GetUpdateType())
			}
		}
	}()

	fmt.Println("Setting random volumes for each source...")

	rand.Seed(time.Now().UnixNano())
	list, _ := client.Sources.GetSourcesList()

	for _, v := range list.Sources {
		if _, err := client.Sources.SetVolume(&sources.SetVolumeParams{
			Source: v.Name,
			Volume: rand.Float64(),
		}); err != nil {
			panic(err)
		}
	}

	if len(list.Sources) == 0 {
		fmt.Println("No sources!")
		os.Exit(0)
	}

	fmt.Println("Test toggling the mute status of the first source...")

	name := list.Sources[0].Name
	resp, _ := client.Sources.GetVolume(&sources.GetVolumeParams{Source: name})
	fmt.Printf("%s is muted? %t\n", name, resp.Muted)

	_, _ = client.Sources.ToggleMute(&sources.ToggleMuteParams{Source: name})
	resp, _ = client.Sources.GetVolume(&sources.GetVolumeParams{Source: name})
	fmt.Printf("%s is muted? %t\n", name, resp.Muted)
}

And the corresponding output:

❯ go run examples/sources/main.go
Setting random volumes for each source...
Volume changed for "Chat"                   : 0.272767
Volume changed for "Window Capture"         : 0.791386
Volume changed for "Audio Output Capture"   : 0.777533
Volume changed for "Video Capture Device"   : 0.084827
Volume changed for "Mic/Aux"                : 0.104773
Volume changed for "Desktop Audio"          : 0.997565
Test toggling the mute status of the first source...
Chat is muted? false
2021/06/14 02:22:18 Unhandled event: "SourceMuteStateChanged"
Chat is muted? true

We can also run this example with OBS_DEBUG set to a non-empty string. If we do, our client will log all of the raw sent requests and received responses.

For further examples, it might help browsing through e2e/e2e_test.go, or through muesli/obs-cli which consumes this library.

development

The client library code is generated from the mess inside ./internal/comments by reading the generated obs-websocket protocol documentation.

Iteration typically involves changing the generative code, running make generate, and a make test.

Documentation

Index

• type Client
  • func New(host string, opts ...Option) (*Client, error)
• type Option
  • func WithDebug(x bool) Option
  • func WithDialer(x *websocket.Dialer) Option
  • func WithLogger(x requests.Logger) Option
  • func WithPassword(x string) Option
  • func WithRequestHeader(x http.Header) Option
  • func WithResponseTimeout(x time.Duration) Option

Types

type Client

type Client struct {
	*requests.Client
	// 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.

type Option

type Option func(*Client)

Option represents a functional option of a Client.

func WithDebug

func WithDebug(x bool) Option

WithDebug enables debug logging via a default logger.

func WithDialer

func WithDialer(x *websocket.Dialer) Option

WithDialer sets the underlying Gorilla WebSocket Dialer (see https://pkg.go.dev/github.com/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 DefaultDialer (see https://pkg.go.dev/github.com/gorilla/websocket#pkg-variables).

func WithLogger

func WithLogger(x requests.Logger) Option

WithLogger sets the logger to use for debug logging. Providing a logger implicitly turns debug logging on, unless debug logging is explicitly disabled.

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.