Python SDK integration

The Python SDK follows the same responsibility boundaries as the Go SDK:

• tirtcxauth: token issuing, verification, and HTTP bearer authentication
• tirtcx: WHIP acceptance, connection lifecycle, media, and commands
• whipecho: embeddable Echo sessions and HTTP adaptation

Requirements

• Python 3.9 or later
• A TiRTC SDK for the deployment platform from the TiRTC SDK download page
• cryptography for Ed25519 tokens

Installation

Get the source from tangeai/whip-sdk:

git clone https://github.com/tangeai/whip-sdk.git
cd whip-sdk/python
python3 -m pip install .

Extract the TiRTC SDK and locate libTiRTC.so on Linux or libTiRTC.dylib on macOS. Set TIRTC_PYTHON_LIBRARY to its absolute path:

export TIRTC_PYTHON_LIBRARY='/absolute/path/to/libTiRTC.so'

The library and its runtime dependencies must come from the same TiRTC SDK release. On Linux, also configure the dynamic-library search path as described by that release. Verify loading before starting the service:

python3 -c 'import tirtcx; tirtcx.init(); tirtcx.uninit(); print("TiRTC native library loaded")'

If this reports TiRTC native library not found, verify that TIRTC_PYTHON_LIBRARY is the absolute path to the dynamic-library file and that the service user can read it. Token APIs do not load the native library; tirtcx.init(), WhipAcceptor, and connection APIs do.

Initialize

import tirtcx
from tirtcxauth import Ed25519TokenVerifier, verify_bearer

verifier = Ed25519TokenVerifier({"your-access-key": public_key})
tirtcx.init()
tirtcx.start()
acceptor = tirtcx.WhipAcceptor("203.0.113.10")  # candidate is optional

Handle POST

Verify the bearer token against the complete raw query before accepting the SDP Offer:

auth = verify_bearer(authorization, "your-service", raw_query, verifier)
if not auth.authenticated:
    return auth.status

session = acceptor.whip_accept(
    offer_sdp,
    tirtcx.ConnEventOptions(
        audio_buffer=16,
        video_buffer=16,
        command_buffer=16,
        error_buffer=4,
        disconnected_buffer=4,
    ),
)
answer_sdp = session.answer_sdp

Return 201, Content-Type: application/sdp, and the answer. Generate a session ID with at least 128 bits of cryptographic randomness, store the session, and return its resource URL in Location. In the background, call session.wait_conn(timeout=30) to obtain the established Conn and process media, commands, and connection events.

Handle DELETE

DELETE <Location> carries no token. Remove the session from the registry and call session.close(). Return 204 No Content for an unknown but valid session ID as well.

Echo

from whipecho import HTTPAdapter

echo = HTTPAdapter(acceptor, "/whip/echo/resource")
response = echo.try_handle_post(raw_query, content_type, offer_sdp)

Ordinary business requests return None. Echo requests return status, headers, and body for the web framework. Extract the session ID from Location for DELETE and call echo.serve_delete(session_id).

echo.stats() reports active sessions, accept and connection failures, send failures, and dropped events. For real-time monitoring, implement whipecho.Observer and pass it to HTTPAdapter. Observer callbacks may run on multiple session threads; they must return quickly and be thread-safe.

Shutdown

Stop HTTP ingress, shut down the Echo adapter and business sessions, then call:

echo.shutdown()
tirtcx.stop()
tirtcx.uninit()

See python/examples/quick_start.py for a complete implementation.