0
# obsws-python
1

2
A Python SDK for OBS Studio WebSocket v5.0 that enables programmatic control of OBS Studio through WebSocket connections. The library provides both request clients for sending commands and event clients for handling real-time OBS events, with support for configuration files, robust error handling, and convenient snake_case method names.
3

4
## Package Information
5

6
- **Package Name**: obsws-python
7
- **Language**: Python
8
- **Version**: 1.8.0
9
- **Installation**: `pip install obsws-python`
10
- **Python Requirements**: >=3.9
11
- **Dependencies**: websocket-client, tomli (Python <3.11)
12

13
## Core Imports
14

15
```python
16
import obsws_python as obs
17
```
18

19
Common usage patterns:
20

21
```python
22
from obsws_python import ReqClient, EventClient, Subs
23
```
24

25
## Basic Usage
26

27
### Request Client (Sending Commands)
28

29
```python
30
import obsws_python as obs
31

32
# Initialize client (loads from config.toml if present)
33
client = obs.ReqClient(host='localhost', port=4455, password='mypassword', timeout=3)
34

35
# Toggle mute on an input
36
client.toggle_input_mute('Mic/Aux')
37

38
# Get OBS version information
39
version_info = client.get_version()
40
print(f"OBS Version: {version_info.obs_version}")
41

42
# Switch scenes
43
client.set_current_program_scene('Scene 2')
44

45
# Close connection
46
client.disconnect()
47

48
# Or use context manager
49
with obs.ReqClient() as client:
50
    client.toggle_input_mute('Mic/Aux')
51
```
52

53
### Event Client (Handling Events)
54

55
```python
56
import obsws_python as obs
57

58
# Initialize event client with subscription filter
59
client = obs.EventClient(subs=obs.Subs.LOW_VOLUME)
60

61
# Define event handlers (use snake_case with "on_" prefix)
62
def on_scene_created(data):
63
    print(f"New scene created: {data.scene_name}")
64

65
def on_input_mute_state_changed(data):
66
    print(f"Input {data.input_name} mute changed to {data.input_muted}")
67

68
# Register callbacks
69
client.callback.register([on_scene_created, on_input_mute_state_changed])
70

71
# Keep listening (client runs in background thread)
72
input("Press Enter to stop listening...")
73

74
client.disconnect()
75
```
76

77
### Configuration File
78

79
Create `config.toml` in current directory, home directory, or `~/.config/obsws-python/`:
80

81
```toml
82
[connection]
83
host = "localhost"
84
port = 4455
85
password = "mystrongpass"
86
```
87

88
## Architecture
89

90
The library is built around three core components:
91

92
- **ReqClient**: Synchronous request-response client for sending commands to OBS
93
- **EventClient**: Asynchronous event listener that runs callbacks in response to OBS events  
94
- **Subs**: Event subscription flags to control which event types to receive
95

96
The underlying **ObsClient** handles WebSocket connections, authentication, and protocol communication. All public API methods use snake_case naming and return dataclass objects with snake_case attributes for easy access to response data.
97

98
## Error Handling
99

100
```python
101
from obsws_python.error import OBSSDKError, OBSSDKTimeoutError, OBSSDKRequestError
102

103
try:
104
    client = obs.ReqClient(password='wrongpassword')
105
except OBSSDKError as e:
106
    print(f"Connection failed: {e}")
107

108
try:
109
    client.get_version()
110
except OBSSDKRequestError as e:
111
    print(f"Request failed: {e.req_name} returned code {e.code}")
112
except OBSSDKTimeoutError as e:
113
    print(f"Request timed out: {e}")
114
```
115

116
## Capabilities
117

118
### Request Client Operations
119

120
Primary interface for sending commands to OBS Studio, supporting all major OBS WebSocket v5.0 operations including scene management, input control, audio settings, streaming, recording, configuration management, transitions, filters, and advanced features.
121

122
```python { .api }
123
class ReqClient:
124
    def __init__(self, host='localhost', port=4455, password='', timeout=None): ...
125
    def disconnect(self): ...
126
    def send(self, param, data=None, raw=False): ...
127
    
128
    # System operations
129
    def get_version(self): ...
130
    def get_stats(self): ...
131
    
132
    # Scene management
133
    def get_scene_list(self): ...
134
    def set_current_program_scene(self, name): ...
135
    def create_scene(self, name): ...
136
    
137
    # Configuration management
138
    def get_scene_collection_list(self): ...
139
    def set_current_scene_collection(self, name): ...
140
    def get_profile_list(self): ...
141
    def set_current_profile(self, name): ...
142
    
143
    # Scene transitions
144
    def get_transition_kind_list(self): ...
145
    def set_current_scene_transition(self, name): ...
146
    def trigger_studio_mode_transition(self): ...
147
    
148
    # Input operations
149
    def toggle_input_mute(self, name): ...
150
    def set_input_volume(self, name, vol_mul=None, vol_db=None): ...
151
    def get_input_settings(self, name): ...
152
    
153
    # Output management
154
    def get_output_list(self): ...
155
    def start_output(self, name): ...
156
    def stop_output(self, name): ...
157
    
158
    # Source operations
159
    def get_source_screenshot(self, name, img_format, width=None, height=None, quality=None): ...
160
    def get_source_active(self, name): ...
161
    
162
    # Media input controls
163
    def get_media_input_status(self, name): ...
164
    def trigger_media_input_action(self, name, action): ...
165
    
166
    # Advanced features
167
    def get_hot_key_list(self): ...
168
    def trigger_hot_key_by_name(self, hotkey_name, context_name=None): ...
169
```
170

171
[Request Client](./request-client.md)
172

173
### Event Handling System
174

175
Event-driven interface for responding to real-time OBS Studio state changes, with callback registration system and subscription filtering to control event volume.
176

177
```python { .api }
178
class EventClient:
179
    def __init__(self, host='localhost', port=4455, password='', subs=Subs.LOW_VOLUME, timeout=None): ...
180
    def disconnect(self): ...
181
    
182
class Callback:
183
    def register(self, fns): ...
184
    def deregister(self, fns): ...
185
    def get(self): ...
186
    def clear(self): ...
187
```
188

189
[Event Client](./event-client.md)
190

191
### Event Subscriptions
192

193
Flag-based system for controlling which OBS events to receive, allowing optimization of network traffic and callback processing load.
194

195
```python { .api }
196
class Subs(IntFlag):
197
    GENERAL = 1 << 0
198
    CONFIG = 1 << 1
199
    SCENES = 1 << 2
200
    INPUTS = 1 << 3
201
    # ... additional flags
202
    
203
    LOW_VOLUME = GENERAL | CONFIG | SCENES | INPUTS | TRANSITIONS | FILTERS | OUTPUTS | SCENEITEMS | MEDIAINPUTS | VENDORS | UI
204
    HIGH_VOLUME = INPUTVOLUMEMETERS | INPUTACTIVESTATECHANGED | INPUTSHOWSTATECHANGED | SCENEITEMTRANSFORMCHANGED
205
    ALL = LOW_VOLUME | HIGH_VOLUME
206
```
207

208
[Event Subscriptions](./event-subscriptions.md)
209

210
### Error Types
211

212
Comprehensive error handling with specific exception types for different failure scenarios including connection errors, timeouts, and request failures.
213

214
```python { .api }
215
class OBSSDKError(Exception): ...
216
class OBSSDKTimeoutError(OBSSDKError): ...
217
class OBSSDKRequestError(OBSSDKError):
218
    req_name: str
219
    code: int
220
```
221

222
[Error Handling](./error-handling.md)
223

224
## Types
225

226
### Connection Parameters
227

228
```python { .api }
229
class ConnectionConfig:
230
    host: str = 'localhost'
231
    port: int = 4455
232
    password: str = ''
233
    timeout: Optional[float] = None
234
    subs: int = Subs.LOW_VOLUME  # EventClient only
235
```
236

237
### Response Data Access
238

239
All request responses and event data are returned as dataclass objects with snake_case attributes:
240

241
```python
242
# Response objects have .attrs() method to inspect available attributes
243
response = client.get_version()
244
print(response.attrs())  # Lists all available attributes
245
print(response.obs_version)  # Access specific attribute
246

247
# Event data also provides .attrs() method
248
def on_scene_created(data):
249
    print(data.attrs())  # Lists all available attributes
250
    print(data.scene_name)  # Access specific attribute
251
```