Python API

本页列出开发 WHIP Service 常用的公开 Python API。完整定义以 whip-sdk/python/src 中的源码为准。

API 列表

包	API	说明
tirtcxauth	Ed25519TokenIssuer	创建 Token 签发器
tirtcxauth	Ed25519TokenVerifier	创建 Token 验证器
tirtcxauth	verify_bearer	验证 HTTP Bearer Token
tirtcx	init / start	初始化并启动 TiRTC
tirtcx	WhipAcceptor	创建无鉴权策略的 WHIP Acceptor
tirtcx	WhipAcceptor.whip_accept	接受 SDP Offer，创建 WHIP Session
tirtcx	WhipSession	管理待连接或已连接会话
tirtcx	Conn	已建立连接的 TiRTC 连接对象。处理收发媒体、命令和连接事件。
whipecho	HTTPAdapter	创建可嵌入 Echo HTTP 适配器
whipecho	Observer	接收 Echo 会话、媒体、失败和丢弃事件

Ed25519TokenIssuer.issue

token = issuer.issue(
    service,
    access_key,
    device_id,
    raw_query,
    ttl_seconds,
)

Token 不含 Nonce，在有效期内可重复用于建连。raw_query 会规范化后参与 Scope 计算，必须与设备使用的完整 Query 一致。

verify_bearer

result = verify_bearer(authorization, service, raw_query, verifier)

情况	status
验证成功	200，claims 非空
缺少 Bearer Token	401
Token 无效	403
Service 或 Verifier 未配置	500

WhipSession

API	说明
answer_sdp	SDP Answer 字节串
wait_conn(timeout)	等待并返回同一个 Conn
close()	幂等关闭待连接或已连接会话

Conn

事件通过 queue.Queue 暴露。Buffer 为 0 时不创建对应 Queue，启用后的最小容量为 4。

属性	内容
events.audio / events.video / events.message	媒体帧
events.command	Command
events.errors	连接错误
events.disconnected	断开通知
done	连接结束时置位的 threading.Event
error	连接结束原因；正常断开时为 None

发送方法包括 send_audio、send_video、send_message、send_command、 request_key_frame 及音视频订阅方法。

HTTPAdapter

API	说明
try_handle_post(raw_query, content_type, body)	处理 Echo POST；普通请求返回 None
serve_delete(session_id)	删除 Echo Session
stats()	返回统计快照
shutdown()	拒绝新会话并关闭现有会话

stats() 返回的 Stats 包含活跃会话数、接入和建连失败、收发媒体、发送失败、 事件丢弃及按关闭原因分类的累计值。Observer 回调可能来自多个会话线程，实现必须 快速返回且保证线程安全。