pyagorartc

Async Python client for Agora RTC signalling, for WebRTC consumers that are not the Agora SDK: a browser behind Home Assistant, go2rtc, pion.

A device publishes video to an Agora channel. pyagorartc finds the Agora edge, turns the consumer's SDP offer into Agora's ORTC, joins the channel over the gateway WebSocket, subscribes to the stream, and hands back an answer SDP. Media then flows directly between the consumer and the Agora edge. It also sends Agora RTM peer messages over REST, which some vendors use as a device control channel.

It knows channels, tokens, edges, SDP and gateway messages. It does not know any vendor. Mammotion mowers and PetKit cameras are the two known hosts; vendor behaviour plugs in through callbacks and options.

What it does not do

• No media. It never touches RTP. The consumer receives the stream.
• No decryption. Agora channel encryption (aes_*) is applied inside the SDK's media path. The fields are modelled but never sent (the SDK RSA-wraps the secret), and a plain WebRTC consumer cannot decode an encrypted stream anyway (D20, Q17).
• No relay. It does not run go2rtc, a TURN server, or an HTTP/WHEP endpoint. Those are host jobs.
• No vendor API. Credentials arrive already fetched.
• No recovery policy. It times peer recovery; the host decides what recovery means.

Status

Alpha (0.x). The API below is the target surface; pyagorartc.__all__ is the supported part of it (Constitution §10). Wire behaviour comes from recordings, the Agora Web SDK 4.24.3 and two shipped integrations; what is still a guess is listed in docs/open_questions.md.

Install

pip install pyagorartc

Python 3.13+. Dependencies: aiohttp, websockets>=13.1, sdp-transform.

Usage

import aiohttp
from pyagorartc import AgoraAPClient, AgoraSession, ChannelCredentials, CloseReason, PyAgoraRTCError, SessionOptions


async def on_closed(reason: CloseReason) -> None:
    print("session ended:", reason)


async def on_peer_left(uid: int) -> None:
    print("publisher", uid, "left; ask the device to publish again")


async def stream(viewer, creds: ChannelCredentials) -> None:
    async with aiohttp.ClientSession() as http:
        ap = await AgoraAPClient(http).choose_server(creds)
        viewer.set_ice_servers(ap.get_ice_servers())       # before the viewer makes its offer
        offer_sdp = await viewer.create_offer()

        session = AgoraSession(creds, ap, options=SessionOptions(target_uid=1),
                               on_closed=on_closed, on_peer_left=on_peer_left)
        try:
            answer_sdp = await session.join(offer_sdp, session_id="viewer-1")
            await viewer.set_answer(answer_sdp)
            await viewer.wait_until_done()
        except PyAgoraRTCError as err:
            print("join failed:", err)
        finally:
            await session.close()                          # cancel and await owned tasks, leave, close

viewer stands for whatever produces the offer. One session serves one offer; a new offer is a new AgoraSession. Candidates known before join() go in with session.add_ice_candidate(...).

Vendor policy

The full table is in docs/architecture.md §4.

Errors

All exceptions derive from PyAgoraRTCError. None carries a token, ticket, credential or key.

A failed join raises; it never returns a made-up answer (D9). A running session reports its end once, through on_closed(CloseReason) (D14).

Documentation

• CONSTITUTION.md: the rules.
• docs/architecture.md: layers, lifecycle, single homes.
• docs/decisions.md: why (D1–D27).
• docs/open_questions.md: what is not settled (Q1–Q19).
• docs/protocol.md: what the wire looks like.
• docs/migration.md: moving the Mammotion and PetKit integrations onto this library.
• docs/testing.md: how it is tested.

Licence

GPL-3.0-or-later. See LICENSE.