Python SDK 接入指南

Python SDK 与 Go SDK 使用相同的职责划分：

• tirtcxauth：Token 签发、验证和 HTTP Bearer 认证。
• tirtcx：WHIP 接入、连接生命周期及媒体和命令收发。
• whipecho：可嵌入的 Echo Session 与 HTTP 适配。

环境要求

• Python 3.9 或更高版本。
• 从 TiRTC SDK 下载页 获取的、与部署平台匹配的 TiRTC SDK。
• 安装 cryptography，用于 Ed25519 Token。

安装

从 tangeai/whip-sdk 获取源码后执行：

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

解压 TiRTC SDK，找到 Linux 的 libTiRTC.so 或 macOS 的 libTiRTC.dylib。使用绝对路径设置 TIRTC_PYTHON_LIBRARY：

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

动态库及其运行时依赖必须来自同一 TiRTC SDK 发布包。Linux 部署还应按该发布包的说明配置动态库搜索路径。执行以下命令验证 Python 可以加载原生库：

python3 -c 'import tirtcx; tirtcx.init(); tirtcx.uninit(); print("TiRTC 原生库加载成功")'

出现 TiRTC native library not found 时，检查 TIRTC_PYTHON_LIBRARY 是否为动态库文件的绝对路径，以及运行用户是否具有读取权限。Token 签发和验证不依赖原生库；调用 tirtcx.init()、创建 WhipAcceptor 或使用连接 API 时才加载原生库。

初始化

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 可选

处理 POST

先使用完整 Raw Query 验证 Bearer Token，再将 SDP Offer 交给 Acceptor：

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,
    ),
)

# 返回 HTTP 201、Content-Type: application/sdp 和以下 Body。
answer_sdp = session.answer_sdp

业务应用生成至少 128 位密码学随机 Session ID，将 Session 保存到注册表，并通过 Location 返回资源地址。后台调用 session.wait_conn(timeout=30) 获得已建立连接的 Conn，随后处理媒体、命令和连接事件。

处理 DELETE

DELETE <Location> 不携带 Token。应用从注册表删除 Session，并调用：

session.close()

删除未知但格式有效的 Session ID 时也返回 204 No Content。

Echo

from whipecho import HTTPAdapter

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

普通业务请求返回 None，Echo 请求返回可写入 Web 框架的 status、headers 和 body。DELETE 路由从 Location 提取 Session ID，并调用 echo.serve_delete(session_id)。

echo.stats() 返回活跃会话、接入和建连失败、发送失败及事件丢弃等统计。需要实时 接入监控时，实现 whipecho.Observer 并传给 HTTPAdapter。Observer 回调可能来自 多个会话线程，必须快速返回且保证线程安全。

退出

停止 HTTP 入口后依次关闭 Echo Adapter 和业务 Session，再停止 TiRTC：

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

完整实现见 python/examples/quick_start.py。