or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-handling.mdevent-client.mdevent-subscriptions.mdindex.mdrequest-client.md
tile.json

tessl/pypi-obsws-python

A Python SDK for OBS Studio WebSocket v5.0

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/obsws-python@1.8.x

To install, run

npx @tessl/cli install tessl/pypi-obsws-python@1.8.0

index.mddocs/

obsws-python

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.

Package Information

  • Package Name: obsws-python
  • Language: Python
  • Version: 1.8.0
  • Installation: pip install obsws-python
  • Python Requirements: >=3.9
  • Dependencies: websocket-client, tomli (Python <3.11)

Core Imports

import obsws_python as obs

Common usage patterns:

from obsws_python import ReqClient, EventClient, Subs

Basic Usage

Request Client (Sending Commands)

import obsws_python as obs

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

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

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

# Switch scenes
client.set_current_program_scene('Scene 2')

# Close connection
client.disconnect()

# Or use context manager
with obs.ReqClient() as client:
    client.toggle_input_mute('Mic/Aux')

Event Client (Handling Events)

import obsws_python as obs

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

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

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

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

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

client.disconnect()

Configuration File

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

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

Architecture

The library is built around three core components:

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

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.

Error Handling

from obsws_python.error import OBSSDKError, OBSSDKTimeoutError, OBSSDKRequestError

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

try:
    client.get_version()
except OBSSDKRequestError as e:
    print(f"Request failed: {e.req_name} returned code {e.code}")
except OBSSDKTimeoutError as e:
    print(f"Request timed out: {e}")

Capabilities

Request Client Operations

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.

class ReqClient:
    def __init__(self, host='localhost', port=4455, password='', timeout=None): ...
    def disconnect(self): ...
    def send(self, param, data=None, raw=False): ...
    
    # System operations
    def get_version(self): ...
    def get_stats(self): ...
    
    # Scene management
    def get_scene_list(self): ...
    def set_current_program_scene(self, name): ...
    def create_scene(self, name): ...
    
    # Configuration management
    def get_scene_collection_list(self): ...
    def set_current_scene_collection(self, name): ...
    def get_profile_list(self): ...
    def set_current_profile(self, name): ...
    
    # Scene transitions
    def get_transition_kind_list(self): ...
    def set_current_scene_transition(self, name): ...
    def trigger_studio_mode_transition(self): ...
    
    # Input operations
    def toggle_input_mute(self, name): ...
    def set_input_volume(self, name, vol_mul=None, vol_db=None): ...
    def get_input_settings(self, name): ...
    
    # Output management
    def get_output_list(self): ...
    def start_output(self, name): ...
    def stop_output(self, name): ...
    
    # Source operations
    def get_source_screenshot(self, name, img_format, width=None, height=None, quality=None): ...
    def get_source_active(self, name): ...
    
    # Media input controls
    def get_media_input_status(self, name): ...
    def trigger_media_input_action(self, name, action): ...
    
    # Advanced features
    def get_hot_key_list(self): ...
    def trigger_hot_key_by_name(self, hotkey_name, context_name=None): ...

Request Client

Event Handling System

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

class EventClient:
    def __init__(self, host='localhost', port=4455, password='', subs=Subs.LOW_VOLUME, timeout=None): ...
    def disconnect(self): ...
    
class Callback:
    def register(self, fns): ...
    def deregister(self, fns): ...
    def get(self): ...
    def clear(self): ...

Event Client

Event Subscriptions

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

class Subs(IntFlag):
    GENERAL = 1 << 0
    CONFIG = 1 << 1
    SCENES = 1 << 2
    INPUTS = 1 << 3
    # ... additional flags
    
    LOW_VOLUME = GENERAL | CONFIG | SCENES | INPUTS | TRANSITIONS | FILTERS | OUTPUTS | SCENEITEMS | MEDIAINPUTS | VENDORS | UI
    HIGH_VOLUME = INPUTVOLUMEMETERS | INPUTACTIVESTATECHANGED | INPUTSHOWSTATECHANGED | SCENEITEMTRANSFORMCHANGED
    ALL = LOW_VOLUME | HIGH_VOLUME

Event Subscriptions

Error Types

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

class OBSSDKError(Exception): ...
class OBSSDKTimeoutError(OBSSDKError): ...
class OBSSDKRequestError(OBSSDKError):
    req_name: str
    code: int

Error Handling

Types

Connection Parameters

class ConnectionConfig:
    host: str = 'localhost'
    port: int = 4455
    password: str = ''
    timeout: Optional[float] = None
    subs: int = Subs.LOW_VOLUME  # EventClient only

Response Data Access

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

# Response objects have .attrs() method to inspect available attributes
response = client.get_version()
print(response.attrs())  # Lists all available attributes
print(response.obs_version)  # Access specific attribute

# Event data also provides .attrs() method
def on_scene_created(data):
    print(data.attrs())  # Lists all available attributes
    print(data.scene_name)  # Access specific attribute