Repository files navigation

Not all endpoints in the official documentation are implemented.

• 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.9 or greater

pip install obsws-python

By default the clients connect with parameters:

• host: "localhost"
• port: 4455
• password: ""
• timeout: None

You may override these parameters by storing them in a toml config file or passing them as keyword arguments.

Order of precedence: keyword arguments then config file then default values.

A validconfig.toml might look like this:

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

It should be placed in your user home directory.

Example__main__.py:

importobsws_pythonasobs# pass conn info if not in config.tomlcl=obs.ReqClient(host='localhost',port=4455,password='mystrongpass',timeout=3)# Toggle the mute state of your Mic inputcl.toggle_input_mute('Mic/Aux')

Method names for requests match the API calls but snake cased. If a successful call is made with the Request client and the response is expected to contain fields then a response object will be returned. You may then access the response fields as class attributes. They will be snake cased.

example:

# load conn info from config.tomlcl=obs.ReqClient()# GetVersion, returns a response objectresp=cl.get_version()# Access it's field as an attributeprint(f"OBS Version:{resp.obs_version}")# SetCurrentProgramScenecl.set_current_program_scene("BRB")

If you prefer to work with the JSON data directly the {ReqClient}.send() method accepts an argument,raw. If set to True the raw response data will be returned, instead of a response object.

example:

resp=cl_req.send("GetVersion",raw=True)print(f"response data:{resp}")

For a full list of requests refer toRequests

When registering a callback function use the name of the expected API event in snake case form, prepended with "on_".

example:

# load conn info from config.tomlcl=obs.EventClient()defon_scene_created(data):    ...# SceneCreatedcl.callback.register(on_scene_created)defon_input_mute_state_changed(data):    ...# InputMuteStateChangedcl.callback.register(on_input_mute_state_changed)# returns a list of currently registered eventsprint(cl.callback.get())# You may also deregister a callbackcl.callback.deregister(on_input_mute_state_changed)

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

For a full list of events refer toEvents

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

example:

resp=cl.get_version()print(resp.attrs())defon_scene_created(data):print(data.attrs())

• OBSSDKError: Base error class.
• OBSSDKTimeoutError: Raised if a timeout occurs during sending/receiving a request or receiving an event
• OBSSDKRequestError: Raised when a request returns an error code.
  • The following attributes are available:
    • req_name: name of the request.
    • code: request status code.
  • For a full list of status codes refer toCodes

If you want to see the raw messages simply set log level to DEBUG

example:

importobsws_pythonasobsimportlogginglogging.basicConfig(level=logging.DEBUG)...

Installhatch and then:

hatch test

For the full documentation:

• OBS Websocket SDK