Introduction

What’s this?

obs-ws-rc is a Python 3.5+ library that allows you to establish client connections to the obs-websocket plugin for OBS Studio.

It’s based on asyncio-approach which it inherited from the underlying WebSocket library - websockets

Performing requests

Firstly, obs-websocket‘s protocol provides you with the ability to send requests and retrieve responses to and from OBS Studio.

Let’s see how it’s done with obs-ws-rc:

"""Example shows how to send requests and get responses."""

import asyncio

from obswsrc import OBSWS
from obswsrc.requests import ResponseStatus, StartStreamingRequest
from obswsrc.types import Stream, StreamSettings


async def main():

    async with OBSWS('localhost', 4444, "password") as obsws:

        # We can send an empty StartStreaming request (in that case the plugin
        # will use OBS configuration), but let's provide some settings as well
        stream_settings = StreamSettings(
            server="rtmp://example.org/my_application",
            key="secret_stream_key",
            use_auth=False
        )
        stream = Stream(
            settings=stream_settings,
            type="rtmp_custom",
        )

        # Now let's actually perform a request
        response = await obsws.require(StartStreamingRequest(stream=stream))

        # Check if everything is OK
        if response.status == ResponseStatus.OK:
            print("Streaming has started")
        else:
            print("Couldn't start the stream! Reason:", response.error)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())
loop.close()

Listening to events

Secondly, the plugin sends events from time to time. This library lets you listen to these events and handle them:

"""Example shows how to listen to events."""

import asyncio
import logging
import sys

from obswsrc import OBSWS
from obswsrc.logs import logger


# We will output logging to sys.stdout, as many events might raise errors
# on creation (that's because protocol.json is not perfect) - such errors
# are logged by obs-ws-rc automatically, we just need to see them
logger.setLevel(logging.ERROR)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


async def main():

    async with OBSWS('localhost', 4444, "password") as obsws:

        print("Connection established.")

        # We will receive events here by awaiting for them (you can await for
        # an event of a specific type by providing `type_name` argument to
        # the obsws.event() method)
        event = await obsws.event()

        # Awaited event might be None if connection is closed
        while event is not None:
            print("Awaited for '{}' event!".format(event.type_name))
            event = await obsws.event()

        print("Connection terminated.")

loop = asyncio.get_event_loop()
loop.run_until_complete(main())
loop.close()

Protocol description

The protocol requrests, responses and events are declared in the PROTOCOL.md by the authors of the obs-websocket plugin.

However, there are minor mistakes in that file. And the field naming of the original protocol is inconsistent. For example, there’re fields like authRequired, at the same time there’re plenty of fields that use a hyphen as a word separator (like kbits-per-sec).

This library internally maps such fields to more pythonic names (auth_required and kbits_per_sec as such) - that allows for convenient passing fields as keyword arguments.

The version of the protocol used by this library can be found in ./obswsrc/protocol.json.

Indices and tables