mirror of
https://github.com/onyx-and-iris/obsws-python.git
synced 2024-11-22 04:40:53 +00:00
186 lines
4.8 KiB
Markdown
186 lines
4.8 KiB
Markdown
[](https://badge.fury.io/py/obsws-python)
|
|
[](https://github.com/aatikturk/obsstudio_sdk/blob/main/LICENSE)
|
|
[](https://github.com/psf/black)
|
|
[](https://pycqa.github.io/isort/)
|
|
|
|
# A Python SDK for OBS Studio WebSocket v5.0
|
|
|
|
Not all endpoints in the official documentation are implemented.
|
|
|
|
## Requirements
|
|
|
|
- [OBS Studio](https://obsproject.com/)
|
|
- [OBS Websocket v5 Plugin](https://github.com/obsproject/obs-websocket/releases/tag/5.0.0)
|
|
- 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
|
|
|
|
### How to install using pip
|
|
|
|
```
|
|
pip install obsws-python
|
|
```
|
|
|
|
### How to Use
|
|
|
|
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.
|
|
|
|
#### `config file`
|
|
|
|
A valid `config.toml` might look like this:
|
|
|
|
```toml
|
|
[connection]
|
|
host = "localhost"
|
|
port = 4455
|
|
password = "mystrongpass"
|
|
```
|
|
|
|
It should be placed in your user home directory.
|
|
|
|
#### Otherwise:
|
|
|
|
Example `__main__.py`:
|
|
|
|
```python
|
|
import obsws_python as obs
|
|
|
|
# pass conn info if not in config.toml
|
|
cl = obs.ReqClient(host='localhost', port=4455, password='mystrongpass', timeout=3)
|
|
|
|
# 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. 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:
|
|
|
|
```python
|
|
# load conn info from config.toml
|
|
cl = obs.ReqClient()
|
|
|
|
# GetVersion, returns a response object
|
|
resp = cl.get_version()
|
|
# Access it's field as an attribute
|
|
print(f"OBS Version: {resp.obs_version}")
|
|
|
|
|
|
# SetCurrentProgramScene
|
|
cl.set_current_program_scene("BRB")
|
|
```
|
|
|
|
#### `send(param, data=None, raw=False)`
|
|
|
|
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:
|
|
|
|
```python
|
|
resp = cl_req.send("GetVersion", raw=True)
|
|
|
|
print(f"response data: {resp}")
|
|
```
|
|
|
|
For a full list of requests refer to [Requests](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests)
|
|
|
|
### Events
|
|
|
|
When registering a callback function use the name of the expected API event in snake case form, prepended with "on\_".
|
|
|
|
example:
|
|
|
|
```python
|
|
# load conn info from config.toml
|
|
cl = obs.EventClient()
|
|
|
|
def on_scene_created(data):
|
|
...
|
|
|
|
# SceneCreated
|
|
cl.callback.register(on_scene_created)
|
|
|
|
def on_input_mute_state_changed(data):
|
|
...
|
|
|
|
# InputMuteStateChanged
|
|
cl.callback.register(on_input_mute_state_changed)
|
|
|
|
# returns a list of currently registered events
|
|
print(cl.callback.get())
|
|
|
|
# You may also deregister a callback
|
|
cl.callback.deregister(on_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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#events)
|
|
|
|
### Attributes
|
|
|
|
For both request responses and event data you may inspect the available attributes using `attrs()`.
|
|
|
|
example:
|
|
|
|
```python
|
|
resp = cl.get_version()
|
|
print(resp.attrs())
|
|
|
|
def on_scene_created(data):
|
|
print(data.attrs())
|
|
```
|
|
|
|
### Errors
|
|
|
|
- `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 to [Codes](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requeststatus)
|
|
|
|
### Logging
|
|
|
|
If you want to see the raw messages simply set log level to DEBUG
|
|
|
|
example:
|
|
|
|
```python
|
|
import obsws_python as obs
|
|
import logging
|
|
|
|
|
|
logging.basicConfig(level=logging.DEBUG)
|
|
...
|
|
```
|
|
|
|
### Tests
|
|
|
|
First install development dependencies:
|
|
|
|
`pip install -e .['dev']`
|
|
|
|
To run all tests:
|
|
|
|
```
|
|
pytest -v
|
|
```
|
|
|
|
### Official Documentation
|
|
|
|
For the full documentation:
|
|
|
|
- [OBS Websocket SDK](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#obs-websocket-501-protocol)
|