OBS WebSocket RemoteControl¶
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
.