Go API

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

API 列表

包	API	说明
tirtcxauth	NewEd25519TokenIssuer	创建 Token 签发器
tirtcxauth	NewEd25519TokenVerifier	创建 Token 验证器
tirtcxauth	BearerInterceptor	创建 HTTP Bearer 认证拦截器
tirtcxauth	ClaimsFromContext	读取请求中已验证的 Claims
tirtcx	NewWhipAcceptor	创建无鉴权策略的 WHIP Acceptor
tirtcx	WhipAcceptor.WhipAccept	接受 SDP Offer，创建 WHIP Session
tirtcx	WhipSession	管理待连接或已连接会话
tirtcx	Conn	已建立连接的 TiRTC 连接对象。处理收发媒体、命令和连接事件。
whipecho	NewHTTPAdapter	创建可嵌入 Echo HTTP 适配器

Token 与 HTTP 认证

BearerInterceptor

func BearerInterceptor(
    service string,
    verifier TokenVerifier,
    observers ...AuthObserver,
) HTTPInterceptor

拦截器从 Authorization: Bearer <token> 读取 Token，并使用请求的完整原始 Query 验证签名和 Scope。

• 缺少 Token：返回 401 Unauthorized。
• Token 无效：返回 403 Forbidden。
• 配置无效：返回 500 Internal Server Error。
• 验证成功：把 TokenClaims 副本放入请求 Context，再调用下一个 Handler。

业务 Handler 可读取已验证身份：

claims, ok := tirtcxauth.ClaimsFromContext(r.Context())

TokenClaims 字段：

字段	含义
Subject	获得委托的设备 ID
Scope	绑定服务名和规范化 Query 的访问范围
Issuer	签发 Token 的 Access Key ID
IssuedAt / ExpiresAt	Unix 秒表示的签发时间和失效时间

Token 中不包含 Nonce，验证器也不执行防重放检查。单次连接请求保护由 TiRTC SDK 与平台自动完成。

该拦截器用于创建会话的 POST，不应用于 DELETE <Location>。

Token 签发

issuer, err := tirtcxauth.NewEd25519TokenIssuer(privateKeys)
token, err := issuer.Issue(
    service,
    accessKey,
    deviceID,
    rawQuery,
    ttl,
)

rawQuery 是 peer_id 的查询串。SDK 会按规范进行 Query 规范化。

WHIP 接入

NewWhipAcceptor

func NewWhipAcceptor(candidate string) *WhipAcceptor

创建不包含认证策略的 Acceptor。candidate 为空时使用 SDK 默认地址；仅在需要公布不同的公网地址时设置。

WhipAcceptor.WhipAccept

func (a *WhipAcceptor) WhipAccept(
    ctx context.Context,
    offer []byte,
    eventOptions ConnEventOptions,
) (*WhipSession, error)

ctx 只控制同步等待 SDP Answer 的阶段。HTTP Handler 返回 Answer 后取消请求 Context，不会取消后续连接建立。

认证必须在调用本方法前完成。应用负责会话 ID、Location、注册表和 DELETE 策略。

会话生命周期

WhipSession.AnswerSDP

func (s *WhipSession) AnswerSDP() []byte

返回 SDP Answer 的副本，用于 HTTP 201 Created 响应。

WhipSession.WaitConn

func (s *WhipSession) WaitConn(ctx context.Context) (*Conn, error)

可并发、重复调用；所有等待者取得同一个最终结果。每个等待者拥有独立 Context，单个等待超时或取消不会关闭会话。

WhipSession.Close

func (s *WhipSession) Close() error

关闭待连接或已连接会话。该方法可重复调用。

连接 API

方法	说明
Events()	返回已启用的事件通道
Done()	连接正常断开或出错后关闭
Err()	在 Done() 关闭后返回终止错误；正常断开返回 nil
EventStats()	返回事件丢弃累计值
SendAudio / SendVideo / SendMessage	发送媒体或消息帧
SendCommand	发送命令
RequestKeyFrame	请求关键帧
SubscribeAudio / SubscribeVideo	订阅媒体流
UnsubscribeAudio / UnsubscribeVideo	取消订阅媒体流
Close()	断开连接

FrameInfo 与媒体类型

type FrameInfo struct {
    StreamID uint8
    Media    MediaType
    Flags    uint8
    Ts       uint32
    Length   uint32
}

字段	说明
StreamID	取值 0～15；同一连接内全局唯一，音频和视频不能复用同一 ID
Media	帧编码，取值见下表
Flags	音频为采样规格：0=8 kHz/16 bit/单声道，1=16 kHz/16 bit/单声道，2=8 kHz/16 bit/双声道，3=16 kHz/16 bit/双声道；视频 bit 0 表示关键帧
Ts	毫秒精度的 32 位时间戳；同一媒体流内应单调递增，允许自然回绕
Length	接收帧的 Payload 字节数；发送时由 SDK 根据 data 长度填写，调用方无需设置

常量	内容
MediaMessage	媒体流内消息
AudioPCM / AudioALaw / AudioAAC / AudioOpus / AudioAMR	对应编码的音频帧
VideoJPEG / VideoH264 / VideoH265	对应编码的视频帧

SendAudio、SendVideo 和 SendMessage 在返回前复制 Payload，调用返回后可复用输入切片。收到的事件帧也由 Go 侧持有，消费方可以在回调返回后读取。具体编码参数必须与设备端约定一致。

ConnEventOptions

字段	事件
AudioBuffer / VideoBuffer / MessageBuffer / CommandBuffer	对应数据事件
ErrorBuffer / DisconnectedBuffer	连接错误与断开事件
RequestKeyFrameBuffer	关键帧请求
UnsubscribeVideoBuffer / UnsubscribeAudioBuffer	取消订阅事件
SubscribeVideoHandler / SubscribeAudioHandler	对端订阅请求的同步决策

缓冲区小于等于 0 表示不启用对应事件；正数小于 MinEventBufferSize 时按最小值创建。订阅 Handler 返回 0 表示接受，非 0 表示拒绝。Handler 运行在原生回调中，必须快速返回；未配置或发生 Panic 时按 0 处理。

Echo HTTP API

NewHTTPAdapter

func NewHTTPAdapter(
    acceptor Acceptor,
    locationPrefix string,
    opts HTTPOptions,
) (*HTTPAdapter, error)

locationPrefix 必须是无尾部 / 的规范绝对路径。HTTPOptions 可配置 SDP 大小、建连超时、Logger 和 Observer。

方法	说明
Wrap(business)	在普通业务 Handler 前增加 Echo 选择
PostHandler()	返回专用 Echo POST Handler
TryHandlePOST(w, r)	框架无关的 Echo 选择入口
DeleteHandler()	返回标准库路由使用的 DELETE Handler
ServeDelete(w, r, id)	使用外部路由提取的会话 ID 删除资源
Stats()	返回线程安全的统计快照
Shutdown(ctx)	停止接入、关闭会话并等待退出