2022-09-04 12:36:01 +01:00
|
|
|
[![PyPI version](https://badge.fury.io/py/obsws-python.svg)](https://badge.fury.io/py/obsws-python)
|
2022-07-30 16:37:07 +01:00
|
|
|
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://github.com/aatikturk/obsstudio_sdk/blob/main/LICENSE)
|
|
|
|
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
|
|
|
|
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
|
|
|
|
|
2022-07-26 22:18:32 +01:00
|
|
|
# A Python SDK for OBS Studio WebSocket v5.0
|
2022-06-05 12:40:55 +01:00
|
|
|
|
2022-07-26 22:18:32 +01:00
|
|
|
Not all endpoints in the official documentation are implemented.
|
2022-06-05 12:40:55 +01:00
|
|
|
|
2022-07-26 03:31:32 +01:00
|
|
|
## Requirements
|
|
|
|
|
|
|
|
- [OBS Studio](https://obsproject.com/)
|
|
|
|
- [OBS Websocket v5 Plugin](https://github.com/obsproject/obs-websocket/releases/tag/5.0.0)
|
2022-11-17 11:32:03 +00:00
|
|
|
- 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.
|
2022-12-05 16:49:17 +00:00
|
|
|
- Python 3.9 or greater
|
2022-07-26 03:31:32 +01:00
|
|
|
|
2022-06-05 12:40:55 +01:00
|
|
|
### How to install using pip
|
|
|
|
|
|
|
|
```
|
2022-09-04 12:10:34 +01:00
|
|
|
pip install obsws-python
|
2022-06-05 12:40:55 +01:00
|
|
|
```
|
|
|
|
|
|
|
|
### How to Use
|
|
|
|
|
2022-11-17 11:32:03 +00:00
|
|
|
By default the clients connect with parameters:
|
|
|
|
|
|
|
|
- `host`: "localhost"
|
|
|
|
- `port`: 4455
|
2022-12-05 18:18:10 +00:00
|
|
|
- `password`: ""
|
2023-06-13 23:09:44 +01:00
|
|
|
|
2022-11-17 11:32:03 +00:00
|
|
|
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:
|
2022-07-25 23:51:30 +01:00
|
|
|
|
|
|
|
```toml
|
|
|
|
[connection]
|
|
|
|
host = "localhost"
|
|
|
|
port = 4455
|
|
|
|
password = "mystrongpass"
|
2023-05-29 11:48:41 +01:00
|
|
|
timeout = 3
|
2022-07-25 23:51:30 +01:00
|
|
|
```
|
|
|
|
|
2023-03-09 01:36:21 +00:00
|
|
|
It should be placed in your user home directory.
|
2022-07-25 23:51:30 +01:00
|
|
|
|
2022-07-26 23:08:07 +01:00
|
|
|
#### Otherwise:
|
|
|
|
|
2022-07-30 16:37:07 +01:00
|
|
|
Example `__main__.py`:
|
2022-06-05 12:40:55 +01:00
|
|
|
|
2022-07-26 22:05:09 +01:00
|
|
|
```python
|
2022-09-04 12:10:34 +01:00
|
|
|
import obsws_python as obs
|
2022-06-05 12:40:55 +01:00
|
|
|
|
2022-07-26 22:05:09 +01:00
|
|
|
# pass conn info if not in config.toml
|
2023-05-29 11:48:41 +01:00
|
|
|
cl = obs.ReqClient(host='localhost', port=4455, password='mystrongpass', timeout=3)
|
2022-06-05 12:40:55 +01:00
|
|
|
|
2022-07-26 22:05:09 +01:00
|
|
|
# Toggle the mute state of your Mic input
|
2022-07-26 22:06:06 +01:00
|
|
|
cl.toggle_input_mute('Mic/Aux')
|
2022-07-25 23:51:30 +01:00
|
|
|
```
|
2022-07-26 22:18:32 +01:00
|
|
|
|
2022-07-30 16:37:07 +01:00
|
|
|
### Requests
|
|
|
|
|
|
|
|
Method names for requests match the API calls but snake cased.
|
|
|
|
|
|
|
|
example:
|
|
|
|
|
|
|
|
```python
|
2022-08-31 20:13:23 +01:00
|
|
|
# load conn info from config.toml
|
|
|
|
cl = obs.ReqClient()
|
2022-07-30 16:37:07 +01:00
|
|
|
|
|
|
|
# GetVersion
|
|
|
|
resp = cl.get_version()
|
|
|
|
|
|
|
|
# SetCurrentProgramScene
|
2022-08-31 20:13:23 +01:00
|
|
|
cl.set_current_program_scene("BRB")
|
2022-07-30 16:37:07 +01:00
|
|
|
```
|
|
|
|
|
|
|
|
For a full list of requests refer to [Requests](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests)
|
|
|
|
|
|
|
|
### Events
|
|
|
|
|
2022-11-17 11:32:03 +00:00
|
|
|
When registering a callback function use the name of the expected API event in snake case form, prepended with "on\_".
|
2022-07-30 16:37:07 +01:00
|
|
|
|
|
|
|
example:
|
|
|
|
|
|
|
|
```python
|
2022-08-31 20:13:23 +01:00
|
|
|
# load conn info from config.toml
|
|
|
|
cl = obs.EventClient()
|
2022-07-30 16:37:07 +01:00
|
|
|
|
2022-11-17 11:32:03 +00:00
|
|
|
def on_scene_created(data):
|
2022-07-30 16:37:07 +01:00
|
|
|
...
|
|
|
|
|
|
|
|
# SceneCreated
|
2022-11-17 11:32:03 +00:00
|
|
|
cl.callback.register(on_scene_created)
|
2022-07-30 16:37:07 +01:00
|
|
|
|
2022-11-17 11:32:03 +00:00
|
|
|
def on_input_mute_state_changed(data):
|
2022-07-30 16:37:07 +01:00
|
|
|
...
|
|
|
|
|
|
|
|
# InputMuteStateChanged
|
2022-11-17 11:32:03 +00:00
|
|
|
cl.callback.register(on_input_mute_state_changed)
|
2022-07-30 16:37:07 +01:00
|
|
|
|
|
|
|
# returns a list of currently registered events
|
|
|
|
print(cl.callback.get())
|
2022-07-30 16:47:12 +01:00
|
|
|
|
|
|
|
# You may also deregister a callback
|
2022-11-17 11:32:03 +00:00
|
|
|
cl.callback.deregister(on_input_mute_state_changed)
|
2022-07-30 16:37:07 +01:00
|
|
|
```
|
|
|
|
|
2022-07-30 16:47:12 +01:00
|
|
|
`register(fns)` and `deregister(fns)` accept both single functions and lists of functions.
|
2022-07-30 16:37:07 +01:00
|
|
|
|
|
|
|
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())
|
|
|
|
|
2022-11-17 11:32:03 +00:00
|
|
|
def on_scene_created(data):
|
2022-07-30 16:37:07 +01:00
|
|
|
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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requeststatus)
|
|
|
|
|
2022-11-17 11:32:03 +00:00
|
|
|
### 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)
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
2022-07-30 16:37:07 +01:00
|
|
|
### Tests
|
|
|
|
|
|
|
|
First install development dependencies:
|
|
|
|
|
|
|
|
`pip install -e .['dev']`
|
|
|
|
|
|
|
|
To run all tests:
|
|
|
|
|
|
|
|
```
|
|
|
|
pytest -v
|
|
|
|
```
|
|
|
|
|
2022-07-26 22:18:32 +01:00
|
|
|
### Official Documentation
|
|
|
|
|
2022-07-30 16:37:07 +01:00
|
|
|
For the full documentation:
|
|
|
|
|
2022-07-26 22:18:32 +01:00
|
|
|
- [OBS Websocket SDK](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#obs-websocket-501-protocol)
|