DOCSEARCHbyAlgolia
Submit Docs

goobs Go Library

repository·main·Indexed 41 days ago

https://github.com/andreykaipov/goobs

A Go library for interacting with OBS Studio via the OBS WebSocket protocol. It supports the v5 protocol (v1.x and above) and provides a structured API for making requests, listening to real-time events, and managing OBS scenes and inputs. The library includes a Docker image for running OBS headlessly in CI environments.

Tokens
9.9K
Snippets
32
Records
38
Agent score
48%

What's inside goobs

  2. Getting started with goobs

    main

    To use goobs, you must have a recent version of OBS running with the WebSocket Server enabled.

    Requirements:

    • OBS with WebSocket Server (v5 protocol).
    • If you are using an older version of OBS where the server is a plugin, it likely uses protocol v4. goobs v1.x and above support the v5 protocol. The last version to support v4 was v0.8.1.

    Verification: Check the Tools menu in OBS for WebSocket Server Settings. If this menu item is missing, you should upgrade OBS.

  3. Enable VNC access in the OBS Docker container

    main

    To observe how a client interacts with OBS or to manually set up test conditions, you can enable VNC access by setting the vnc=1 environment variable. You can also optionally set a password using the vnc_password environment variable.

    # Enable VNC
❯ docker run --rm -it -e vnc=1 -p 5900:5900 ghcr.io/andreykaipov/goobs

# Enable VNC with a password
❯ docker run --rm -it -e vnc=1 -e vnc_password=delicious -p 5900:5900 ghcr.io/andreykaipov/goobs

  4. Verify bundled OBS configs

    main

    To quickly verify that your updated configurations were bundled correctly, rebuild the image and run it. Since copying configs is one of the last layers, the rebuild is fast.

    ❯ docker run --rm -it --name obs -p 4455:1234 -e vnc=1 -p 5900:5900 "$(docker build -q docker)"

  5. Make requests to OBS

    main

    Requests are organized by category (e.g., client.SceneItems, client.Inputs). To perform an action, call the corresponding method on the category object.

    goobs supports two patterns for defining request parameters:

    1. Builder Pattern: Using New<RequestName>Params().With<Field>(value).
    2. Struct Initialization: Creating the params struct directly (e.g., &sceneitems.SetSceneItemEnabledParams{...}).

    To discover which InputKind or other parameters to use, it is recommended to first call a Get... method (like GetInputList) or listen to events to see the data structure returned by OBS.

    // Example: Using the builder pattern for GetSceneItemList
params := sceneitems.NewGetSceneItemListParams().WithSceneName(sceneName)
sceneList, err := client.SceneItems.GetSceneItemList(params)

// Example: Using direct struct initialization for SetSceneItemEnabled
params := &sceneitems.SetSceneItemEnabledParams{
    SceneName:        &scene,
    SceneItemId:      &sourceID,
    SceneItemEnabled: &visible,
}
_, err := client.SceneItems.SetSceneItemEnabled(params)

  7. Connect to the OBS WebSocket server

    main

    Use goobs.New to create a new client. You must provide the server address (e.g., localhost:4455).

    If your development environment is running in WSL and OBS is running on the Windows host, you must point to the Windows host IP instead of localhost.

    You can use functional options like goobs.WithPassword(string) to configure the client connection.

    client, err := goobs.New("localhost:4455", goobs.WithPassword("bigmoney420!!"))

  8. Run OBS headlessly with Docker

    main

    You can run OBS and OBS-WebSocket headlessly using a Docker image. This is primarily useful for testing obs-websocket client libraries in CI environments.

    By default, the obs-websocket server is bound to localhost:1234 within the container. If you enable VNC, the VNC server is bound to localhost:5900 within the container.

    ❯ docker run --rm -it -p 4455:1234 ghcr.io/andreykaipov/goobs

  9. Update bundled OBS configs

    main

    You can customize the bundled scene and profile configurations by:

    1. Running the container with VNC enabled.
    2. Connecting via a VNC client (e.g., noVNC, VNC Viewer).
    3. Modifying the configurations directly within OBS.
    4. Syncing the modified configs to your local machine using ./sync.sh.
    5. Rebuilding the image to include the new configs.

  10. Install goobs via Go modules

    main

    To use goobs in your Go project, initialize your module and then use go get to fetch the library.

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

  11. Configure goobs via environment variables

    main

    You can configure the behavior of the goobs client using the following environment variables:

    VariableValuesDescription
    GOOBS_LOGtrace, debug, info, errorSets the logging level for the client.
    GOOBS_PROFILEmemprofile=<file>, help, etc.Enables profiling. Set to help to see available options.

    Example: Memory Profiling

    GOOBS_PROFILE=memprofile=mem.out OBS_PORT=4455 go test -v -run=profile client_test.go

  12. Connect to OBS Studio and retrieve version information

    main

    You can connect to an OBS WebSocket server using goobs.New. This function accepts a connection string (e.g., localhost:4455) and functional options like goobs.WithPassword. Once connected, you can access various OBS features through the client instance. In this example, we use client.General.GetVersion() to retrieve version details for OBS Studio, the server protocol, the client protocol, and the library itself.

    package main

import (
	"fmt"

	"github.com/andreykaipov/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)
}