PyAgoraRTC 0.2.0__py3-none-any.whl

pyagorartc/session/transport.py

@@ -0,0 +1,130 @@
+"""The ``GatewayTransport`` seam: what the session needs from a WebSocket, and nothing more.
+
+The ``websockets`` adapter lives beside it; the unit tier replaces it with a scripted fake.
+"""
+
+from __future__ import annotations
+
+from contextlib import suppress
+import logging
+import ssl
+from typing import TYPE_CHECKING, Protocol
+from urllib.parse import urlsplit
+
+from websockets.asyncio.client import connect as ws_connect
+from websockets.exceptions import WebSocketException
+from websockets.protocol import State
+
+from pyagorartc.exceptions import GatewayConnectError
+
+if TYPE_CHECKING:
+    from websockets.asyncio.client import ClientConnection
+
+
+class GatewayConnection(Protocol):
+    """One open gateway socket: text frames in and out, and a close."""
+
+    async def send(self, text: str) -> None:
+        """Send one text frame; raises ``GatewayConnectError`` if the socket is gone."""
+        ...
+
+    async def recv(self) -> str:
+        """Return the next text frame; raises ``GatewayConnectError`` when the socket closes."""
+        ...
+
+    async def close(self) -> None:
+        """Close the socket; idempotent."""
+        ...
+
+    @property
+    def is_open(self) -> bool:
+        """Whether frames can still be sent."""
+        ...
+
+
+class GatewayTransport(Protocol):
+    """Opens gateway sockets. ``url`` is the full ``wss://`` URL for one edge."""
+
+    async def connect(self, url: str, *, timeout_s: float, verify_ssl: bool) -> GatewayConnection:
+        """Open one connection.
+
+        Raises:
+            GatewayConnectError: The socket could not be opened in time.
+
+        """
+        ...
+
+
+def _ssl_context(*, verify: bool) -> ssl.SSLContext:
+    context = ssl.create_default_context()
+    if not verify:
+        context.check_hostname = False
+        context.verify_mode = ssl.CERT_NONE
+    return context
+
+
+# Built at import: loading the CA bundle is blocking I/O that must not run on the event loop.
+_VERIFIED_CONTEXT = _ssl_context(verify=True)
+_UNVERIFIED_CONTEXT = _ssl_context(verify=False)
+_SOCKET_ERRORS = (WebSocketException, OSError)
+# websockets logs every frame at DEBUG, and a renew_token frame is short enough to carry its whole token (§6).
+_WIRE_LOGGER = logging.getLogger("pyagorartc.session.wire")
+_WIRE_LOGGER.setLevel(logging.INFO)
+
+
+class WebsocketsConnection:
+    """``GatewayConnection`` over a ``websockets`` client connection."""
+
+    def __init__(self, connection: ClientConnection) -> None:
+        self._connection = connection
+
+    async def send(self, text: str) -> None:
+        """Send one text frame; raises ``GatewayConnectError`` if the socket is gone."""
+        try:
+            await self._connection.send(text)
+        except _SOCKET_ERRORS as exc:
+            raise GatewayConnectError("gateway socket closed") from exc
+
+    async def recv(self) -> str:
+        """Return the next frame as text; raises ``GatewayConnectError`` when the socket closes."""
+        try:
+            data = await self._connection.recv()
+        except _SOCKET_ERRORS as exc:
+            raise GatewayConnectError("gateway socket closed") from exc
+        return data.decode("utf-8", errors="replace") if isinstance(data, bytes) else data
+
+    async def close(self) -> None:
+        """Close the socket; idempotent."""
+        with suppress(*_SOCKET_ERRORS):
+            await self._connection.close()
+
+    @property
+    def is_open(self) -> bool:
+        """Whether frames can still be sent."""
+        return self._connection.state is State.OPEN
+
+
+def ssl_for(url: str, *, verify_ssl: bool) -> ssl.SSLContext | None:
+    """The TLS context for ``url``: none for ``ws://`` (the loopback fake gateway), verified unless told not (D10)."""
+    if urlsplit(url).scheme == "ws":
+        return None
+    return _VERIFIED_CONTEXT if verify_ssl else _UNVERIFIED_CONTEXT
+
+
+class WebsocketsTransport:
+    """``GatewayTransport`` backed by ``websockets``; TLS is verified unless ``verify_ssl`` is False (D10)."""
+
+    async def connect(self, url: str, *, timeout_s: float, verify_ssl: bool) -> GatewayConnection:
+        """Open one gateway socket.
+
+        Raises:
+            GatewayConnectError: The socket could not be opened within ``timeout_s``.
+
+        """
+        try:
+            connection = await ws_connect(
+                url, ssl=ssl_for(url, verify_ssl=verify_ssl), open_timeout=timeout_s, logger=_WIRE_LOGGER
+            )
+        except (TimeoutError, *_SOCKET_ERRORS) as exc:
+            raise GatewayConnectError(f"could not open the gateway socket at {url}") from exc
+        return WebsocketsConnection(connection)

pyagorartc-0.2.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: PyAgoraRTC
+Version: 0.2.0
+Summary: Async Python client for Agora RTC signalling: edge discovery, SDP/ORTC negotiation and the WebSocket gateway session
+Project-URL: Homepage, https://github.com/mikey0000/PyAgoraRTC
+Project-URL: Documentation, https://github.com/mikey0000/PyAgoraRTC/tree/main/docs
+Author: Michael Arthur
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: agora,asyncio,camera,ortc,rtc,sdp,webrtc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: sdp-transform>=1.1.0
+Requires-Dist: websockets>=13.1
+Description-Content-Type: text/markdown
+
+# 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`](docs/open_questions.md).
+
+## Install
+
+```
+pip install pyagorartc
+```
+
+Python 3.13+. Dependencies: `aiohttp`, `websockets>=13.1`, `sdp-transform`.
+
+## Usage
+
+```python
+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
+
+| Concern | Library provides | Host provides |
+|---|---|---|
+| Token refresh | `token_provider`, 30 s debounce (D8) | the vendor call that mints a token |
+| Device keep-alive | `keepalive`, `keepalive_interval_s`, `deadline` (D15) | the call to the device |
+| Stream recovery | peer-recovery timing, `on_peer_left(uid)` (D14) | re-requesting the stream |
+| Which camera | `SessionOptions.target_uid` | slot → uid |
+| Consumer quirks | `declare_remote_video_ssrc`, `disable_audio`, `instant_video`, subscribe retry | choosing them |
+| `set_client_role` after join | `send_set_client_role`, default off (D6) | knowing the device tolerates it |
+| RTM control | `RtmRestClient.send_peer_message` (D18) | the commands and their cadence |
+| Viewer transport | answer SDP, ICE servers, candidate helpers | views, auth, relays |
+
+The full table is in [`docs/architecture.md`](docs/architecture.md) §4.
+
+## Errors
+
+All exceptions derive from `PyAgoraRTCError`. None carries a token, ticket,
+credential or key.
+
+| Exception | Meaning |
+|---|---|
+| `APError` | Edge discovery failed on every access-point host. |
+| `APRejectedError` | The access point answered, but rejected every service (`.codes`). |
+| `SdpError` | The offer could not be converted, or no answer could be built. |
+| `GatewayConnectError` | No gateway edge accepted the WebSocket, or it closed (or stalled) before the join result. |
+| `JoinRejectedError` | The gateway refused the join (`.code`). |
+| `JoinTimeoutError` | No join result in time. |
+| `SessionClosedError` | The session has already ended. |
+| `RtmError` | An RTM peer message was not accepted (`.status`, `.code`). |
+
+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`](CONSTITUTION.md): the rules.
+- [`docs/architecture.md`](docs/architecture.md): layers, lifecycle, single homes.
+- [`docs/decisions.md`](docs/decisions.md): why (D1–D27).
+- [`docs/open_questions.md`](docs/open_questions.md): what is not settled (Q1–Q19).
+- [`docs/protocol.md`](docs/protocol.md): what the wire looks like.
+- [`docs/migration.md`](docs/migration.md): moving the Mammotion and PetKit integrations onto this library.
+- [`docs/testing.md`](docs/testing.md): how it is tested.
+
+## Licence
+
+GPL-3.0-or-later. See [`LICENSE`](LICENSE).

pyagorartc-0.2.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+pyagorartc/__init__.py,sha256=EnG8LuIf9JI0Ap4wDYLXOC1PAPhIFAh7x2RrXuTf310,1503
+pyagorartc/const.py,sha256=38JtRe3d21pajaI1MLEczhrpIV709xZpRmc7yPBxLws,2261
+pyagorartc/exceptions.py,sha256=Pls-eiFipMrfn-5S6tme2H-DinmTrj-LRFL2yTv_YVY,2026
+pyagorartc/models.py,sha256=mXCfmRi-qYDBAuxYmhPf7Gkp7g3YH9YHJH9KYD6Rj7g,7292
+pyagorartc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyagorartc/ap/__init__.py,sha256=yhp_jlDe-HAb_PlLP04QGnEKWcvlaxdQkTuEJmPcKnY,481
+pyagorartc/ap/client.py,sha256=i0A5i8khpER0o5uCqd3_cdelgVTYvzcFd5BsQGacMsY,8829
+pyagorartc/ap/password.py,sha256=i1-Cj_UAsDcFpFiqS8MI2qR4SYjDqahDEJVTA432_go,502
+pyagorartc/ap/response.py,sha256=AEvDpMdNJ1EaR1X61p4Couxamwu5fKwpJhm5s3Z29HI,12953
+pyagorartc/rtm/__init__.py,sha256=juxW-MBIOyNs0mVTrOHZdvPtsHHuhwWVjyLWBoxUp-A,169
+pyagorartc/rtm/client.py,sha256=ds0PpSW9IY_wcsnGRdDnB8QW4MKSd1pqIvu1keAbJLc,6958
+pyagorartc/sdp/__init__.py,sha256=eSRns-Rp2d3uUQ3Bw_-ioWTgLPoQdnL1S6yU14rOd3Q,738
+pyagorartc/sdp/answer.py,sha256=Q9xlHQcsMr3LUmEHqohbChobQR2IMGqefPfC21kXZiE,14788
+pyagorartc/sdp/candidates.py,sha256=dHeVT-56IAglTPBPQXExm992n5_YfnXwj77_v-3AY8Y,4188
+pyagorartc/sdp/offer.py,sha256=748xUSkdixoMhPRLZ9Hj_m69a4WOHk3OVDjEg5uWrRI,10521
+pyagorartc/session/__init__.py,sha256=8Ao68NG2OdMFqv__Np_D06i3z0fMZSb6cJcruCdjE_k,2031
+pyagorartc/session/messages.py,sha256=cfmH-CwnN66pclxxA5TVt7Oq2bC5iuoFuWe2r3qLtno,20884
+pyagorartc/session/recovery.py,sha256=EZLLhQZ4X3eteynqYcSOeYohH1MXCijXS2UPAo5_bOM,6667
+pyagorartc/session/session.py,sha256=0Gs7dWfscIcErmcEMy5LaFy1v6yCGfg5VbR9jkIA2Uk,31667
+pyagorartc/session/transport.py,sha256=1thvlEJDJSAOWbNu_sBlPa4pcP96BFHNxzUgrcEF9VM,4568
+pyagorartc-0.2.0.dist-info/METADATA,sha256=cS8VvzcQvvkNgS-tD0UJ0cuDqS8rdOu5Uu1NLQRfLAM,6523
+pyagorartc-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pyagorartc-0.2.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+pyagorartc-0.2.0.dist-info/RECORD,,

pyagorartc-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any