Websocket API Documentation

Real-time access to transcriptions and frame data from top livestreams

Conduit provides real-time access to transcriptions and frame data from the top livestreams on the internet. You can specify which streams to consume by sending "subscribe" events to the server. Once connected to a stream, our websocket will begin emits events containing transcriptions and base64 encoded images.

Generate your API Key

Before using Conduit, you need to generate an API key. You can do that by navigating to your user settings and clicking the "Create API Key" button.

Connecting to Conduit

Conduit uses Socket.io to handle connections and manage events. To connect to Conduit, create a new Socket.IO client and connect to https://data.tryconduit.io. Make sure to pass the API key generated above in the auth field.

import socketio
sio = socketio.Client()
sio.connect("https://data.tryconduit.io", auth={"Authorization": "sb_...xxxx"}, wait_timeout=10)

Subscribing to a Livestream

To subscribe to a livestream and begin receiving both transcriptions and images, you should emit a subscribe event with the all content type.

subscription_data = {
    "stream_url": "https://www.twitch.tv/esfandtv",
    "content_type": ["all"]
}
sio.emit("subscribe", subscription_data)

Handling Incoming Data

When data is available from the websocket, a livestream_data_event event will be fired. This event will contain the stream url the data is coming from, the transcription, and a base64 encoded image from the live video feed from when the speaker stopped talking. This event may contain more than one transcription when subscribed to many streams.

[
    {
        "stream_url": "https://www.twitch.tv/esfandtv",
        "transcription": "Thanks for watching!",
        "frame": "iVBORw0KGgoAAAANSUhEUgAAA1YAAAHgCAIAAAApMmt..."
    }
]

To receive this data from the websocket, you should set up an event handler to handle the livestream_data_event event.

@sio.on("livestream_data_event")
def livestream_data_event(data):
    for transcription in data:
        stream = transcription["stream_url"]
        message = transcription["transcription"]
        print(f"Stream: {stream} said:{message}")

Handling Errors

When there is an error with your request or one of the streams you're subscribed to, you will receive a error_event event. This event will contain an code and message describing the failure.

[
    {
        "code": "auth_failed",
        "message": "Failed to authenticate client."
    }
]

To handle these events, set up another socketIO event handler.

@sio.on("error_event")
def on_error_received(data):
    for error in data:
        code = error["error_code"]
        error = error["error_message"]
        print(f"Error code: {code} Error Message: {error}.")

Handling Subscribe / Unsubscribe Events

When a client subscribes or unsubscribes to a stream, a subscribe_event / unsubscribe_event will be fired containing a list of the client's currently subscribed streams. Below is an example of what that event may look like.

[
    {
        "stream_url": "https://www.twitch.tv/dumbdog", 
        "content_type": ["all"]
    }
]

You can subscribe to these events in a similar manner as the rest.

@sio.on("subscribe_event")
def on_subscribe_received(subscriptions):
    print(subscriptions)
 
@sio.on("unsubscribe_event")
def on_unsubscribe_received(subscriptions):
    print(subscriptions)
Error responses