A Python SDK for OBS Studio WebSocket v5.0

This is a wrapper around OBS Websocket. Not all endpoints in the official documentation are implemented.

Requirements

• OBS Studio
• OBS Websocket v5 Plugin
  • With the release of OBS Studio version 28, Websocket plugin is included by default. But it should be manually installed for earlier versions of OBS.
• Python 3.10 or greater

How to install using pip

pip install obsws-python

How to Use

Load connection info from toml config. A valid config.toml might look like this:

[connection]
host = "localhost"
port = 4455
password = "mystrongpass"

It should be placed next to your __main__.py file.

Otherwise:

Import and start using, keyword arguments are as follows:

• host: obs websocket server
• port: port to access server
• password: obs websocket server password

Example __main__.py:

import obsws_python as obs

# pass conn info if not in config.toml
cl = obs.ReqClient(host='localhost', port=4455, password='mystrongpass')

# Toggle the mute state of your Mic input
cl.toggle_input_mute('Mic/Aux')

Requests

Method names for requests match the API calls but snake cased.

example:

# load conn info from config.toml
cl = obs.ReqClient()

# GetVersion
resp = cl.get_version()

# SetCurrentProgramScene
cl.set_current_program_scene("BRB")

For a full list of requests refer to Requests

Events

When registering a function callback use the name of the expected API event in snake case form.

example:

# load conn info from config.toml
cl = obs.EventClient()

def scene_created(data):
    ...

# SceneCreated
cl.callback.register(scene_created)

def input_mute_state_changed(data):
    ...

# InputMuteStateChanged
cl.callback.register(input_mute_state_changed)

# returns a list of currently registered events
print(cl.callback.get())

# You may also deregister a callback
cl.callback.deregister(input_mute_state_changed)

register(fns) and deregister(fns) accept both single functions and lists of functions.

For a full list of events refer to Events

Attributes

For both request responses and event data you may inspect the available attributes using attrs().

example:

resp = cl.get_version()
print(resp.attrs())

def scene_created(data):
    print(data.attrs())

Errors

If a request fails an OBSSDKError will be raised with a status code.

For a full list of status codes refer to Codes

Tests

First install development dependencies:

pip install -e .['dev']

To run all tests:

pytest -v

Official Documentation

For the full documentation:

• OBS Websocket SDK