Ti RTC 开发文档

中文

English

中文

English

设备端 C API 参考 ​

设备端错误码见错误码。

对象总览 ​

对象作用
tirtc_conn_t表示一条设备连接
TIRTCCALLBACKS定义设备端回调入口
TIRTCFRAMEINFO描述音频帧、视频帧和流内消息
TIRTCOPTION定义全局配置项
TIRTCCONNECTCALLBACK接收异步连接结果
TIRTCLOGCALLBACK接管 SDK 日志输出

通用约束 ​

  • TIRTCCALLBACKS 及其中回调函数的生命周期必须覆盖整个 SDK 运行期。
  • 所有回调都在 SDK 内部线程执行。回调里只做轻量工作，不做阻塞或耗时操作。
  • 回调里的 data 指针只在当前回调内有效；需要跨线程使用时，先自行拷贝。
  • 不要在回调里直接调用 TiRtcDisconnect()；尤其收到 on_conn_error 后，要切到回调外线程或事件循环再断开。
  • TiRtcDisconnect() 是异步操作。调用返回后就把 hconn 当成无效；只有当你必须等 SDK 内部彻底释放时，才实现 on_disconnected 作为同步点。
  • stream_id 取值范围是 0 到 15。同一连接内音频和视频不能复用同一个 stream_id。
  • 每路视频流的第一帧必须是关键帧。
  • 音频帧的 flags 填 TIRTCAUDIOSAMPLE；视频帧的 flags 按位使用 TIRTC_FRAME_FLAG_KEY_FRAME。
  • 收到 on_conn_error 后，这条连接上的收发已不再有效；仍需在回调外调用 TiRtcDisconnect() 完成释放。

生命周期 ​

层级相关接口说明
进程级TiRtcInit() / TiRtcUninit()初始化和释放 SDK 运行时
会话级TiRtcStart() / TiRtcStop()启动和停止设备端服务
连接级on_conn_accepted / TiRtcConnect() / TiRtcDisconnect()建立、使用和释放单条连接

常见顺序：TiRtcSetOption(TIRTC_OPT_MAX_SEND_BUFFER) -> TiRtcInit() -> 其他 TiRtcSetOption() -> TiRtcStart() -> 连接建立与收发 -> TiRtcStop() -> TiRtcUninit()。

TiRtcGetVersion ​

c
const char *TiRtcGetVersion(void);

返回 SDK 版本字符串。

TiRtcGetErrorStr ​

c
const char *TiRtcGetErrorStr(int error);

把错误码转换为可读字符串。

TiRtcInit ​

c
int TiRtcInit(void);

初始化 SDK。必须在 TiRtcStart() 前调用。

TiRtcUninit ​

c
void TiRtcUninit(void);

释放 SDK 运行时资源。

TiRtcSetOption ​

c
int TiRtcSetOption(TIRTCOPTION opt, const void *data, uint32_t len);

设置全局配置项。

配置项data 类型说明
TIRTC_OPT_SERVICE_ENDPOINTconst char *服务入口地址；不设置时使用默认入口
TIRTC_OPT_SECRET_KEYconst char *单独设置 device_secret_key；可替代在 license 字符串中明文传入
TIRTC_OPT_MAX_CONNECTIONSint *最大连接数；默认 5
TIRTC_OPT_NETWORK_TYPEint *联网方式；取值见 TIRTCNETCONN，默认 TIRTC_NETCONN_WIFI
TIRTC_OPT_ICCIDconst char *TIRTC_NETCONN_4G 下必填
TIRTC_OPT_WAKEUPint *是否支持休眠唤醒；0 或 1，默认 0
TIRTC_OPT_RESTRICTED_NETWORKint *是否受限网络；0 或 1，默认 0
TIRTC_OPT_MAX_SEND_BUFFERuint32_t *发送缓冲区上限；必须在 TiRtcInit() 前设置。默认普通版 512 KB，CONFIG_SMALL_MEMORY 下 100 KB
TIRTC_OPT_CONNECT_CACHEint *是否启用连接参数缓存；0 关闭、1 开启，默认开启

TiRtcStart ​

c
int TiRtcStart(const char *license, const TIRTCCALLBACKS *cbs);

启动 C SDK 会话。

  • license == NULL 时，只启动客户端能力，不接收入站连接。
  • 传 "<device_id>" 时，先通过 TIRTC_OPT_SECRET_KEY 设置 device_secret_key。
  • 也兼容 "<device_id>,<device_secret_key>" 形式。
  • 返回 0 只表示参数校验通过；真正启动完成以 on_event(TiEVENT_SYS_STARTED, ...) 为准。

TiRtcStop ​

c
int TiRtcStop(void);

停止 SDK。完成后由 on_event(TiEVENT_SYS_STOPPED, ...) 通知。

核心类型 ​

tirtc_conn_t ​

c
typedef struct _tirtc_conn *tirtc_conn_t;

表示一条点对点连接。设备端在 on_conn_accepted 中拿到它；on_disconnected 返回后，这个句柄由 SDK 自动释放。

TIRTCNETCONN ​

取值说明
TIRTC_NETCONN_WIFIWi-Fi
TIRTC_NETCONN_4G运营商数据网络

TIRTCMEDIA ​

取值说明
TIRTC_MEDIA_MESSAGE流内消息
TIRTC_AUDIO_PCMPCM 音频
TIRTC_AUDIO_ALAWG.711 A-law
TIRTC_AUDIO_AACAAC 音频
TIRTC_AUDIO_OPUSOpus 音频
TIRTC_VIDEO_JPEGJPEG 图像
TIRTC_VIDEO_H264H.264 视频
TIRTC_VIDEO_H265H.265 视频

TIRTCAUDIOSAMPLE ​

取值说明
TIRTC_AUDIOSAMPLE_8K16B1C8 kHz、16 bit、单声道
TIRTC_AUDIOSAMPLE_16K16B1C16 kHz、16 bit、单声道
TIRTC_AUDIOSAMPLE_8K16B2C8 kHz、16 bit、双声道
TIRTC_AUDIOSAMPLE_16K16B2C16 kHz、16 bit、双声道

TIRTCFRAMEINFO ​

c
typedef struct TIRTCFRAMEINFO {
    uint8_t  stream_id;
    uint8_t  media;
    uint8_t  flags;
    uint8_t  reserved;
    uint32_t ts;
    uint32_t length;
} TIRTCFRAMEINFO;
字段说明
stream_id流 ID；取值 0 到 15。同一连接内音频和视频不能共用
media媒体类型；取值见 TIRTCMEDIA
flags视频帧按位使用 TIRTC_FRAME_FLAG_KEY_FRAME；音频帧填 TIRTCAUDIOSAMPLE
reserved预留字段；当前填 0
ts主机序时间戳，单位毫秒
lengthpayload 字节长度

视频关键帧相关宏：

c
#define TIRTC_FRAME_FLAG_KEY_FRAME 0x01
#define TIRTC_IS_KEY_FRAME(flags) ((flags) & TIRTC_FRAME_FLAG_KEY_FRAME)

TIRTCSYSEVENT ​

取值说明
TiEVENT_SYS_STARTEDSDK 已启动
TiEVENT_SYS_STOPPEDSDK 已停止
TiEVENT_ACCESS_HIJACKINGHTTP 请求被重定向

回调 ​

TIRTCCALLBACKS ​

c
typedef struct TIRTCCALLBACKS {
    void (*on_event)(int event, const void *data, int len);
    void (*on_conn_accepted)(tirtc_conn_t hconn);
    void (*on_conn_error)(tirtc_conn_t hconn, int error);
    void (*on_disconnected)(tirtc_conn_t hconn);
    void (*on_audio)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_video)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_message)(tirtc_conn_t hconn, const TIRTCFRAMEINFO *pFi, void *data);
    void (*on_command)(tirtc_conn_t hconn, uint32_t cmdw, const void *data, uint32_t len);
    void (*on_request_key_frame)(tirtc_conn_t hconn, uint8_t stream_id);
    int (*on_subscribe_video)(tirtc_conn_t hconn, uint8_t stream_id);
    void (*on_unsubscribe_video)(tirtc_conn_t hconn, uint8_t stream_id);
    int (*on_subscribe_audio)(tirtc_conn_t hconn, uint8_t stream_id);
    void (*on_unsubscribe_audio)(tirtc_conn_t hconn, uint8_t stream_id);
} TIRTCCALLBACKS;
回调触发时机
on_eventSDK 内部事件
on_conn_accepted收到新的入站连接
on_conn_error连接出现错误
on_disconnectedTiRtcDisconnect() 完成，连接句柄即将释放
on_audio收到对端音频帧
on_video收到对端视频帧
on_message收到对端流内消息
on_command收到对端命令通道数据
on_request_key_frame对端请求立即发送关键帧
on_subscribe_video对端请求开始接收某路视频
on_unsubscribe_video对端请求停止接收某路视频
on_subscribe_audio对端请求开始接收某路音频
on_unsubscribe_audio对端请求停止接收某路音频

TIRTCCONNECTCALLBACK ​

c
typedef void (*TIRTCCONNECTCALLBACK)(int error, tirtc_conn_t hconn, void *user_data);

连接结果回调。设备端在主动建连或 WHIP 场景会用到它。

TIRTCLOGCALLBACK ​

c
typedef void (*TIRTCLOGCALLBACK)(const char *log, uint32_t length);

日志输出回调。设置后，SDK 不再向控制台或文件输出日志。

连接管理 ​

TiRtcConnect ​

c
int TiRtcConnect(const char *remote_id,
                 const char *token,
                 TIRTCCONNECTCALLBACK cb,
                 void *user_data);

主动连接到指定 remote_id。

  • cb 不能为空；返回 0 只表示连接请求已提交，真正结果以后续 cb 为准。
  • 首次连接应传入有效 token。这个 token 是一次性的，不要重复使用。
  • 同一个 remote_id 在缓存有效期内可传 NULL 复用连接参数。
  • 缓存失效时返回 TIRTC_E_CACHE_EXPIRED，需要重新传入有效 token。

TiRtcDisconnect ​

c
int TiRtcDisconnect(tirtc_conn_t hconn);

主动断开连接。

  • 这是异步操作，不会阻塞到 SDK 内部彻底释放完成。
  • 调用返回后，不应再继续使用这个 hconn。
  • 如果你必须等待 SDK 内部释放完成，再把 on_disconnected 当成同步点。

TiRtcGetSendBufferUsed ​

c
size_t TiRtcGetSendBufferUsed(tirtc_conn_t hconn);

返回当前连接已占用的发送缓冲区字节数。

TiRtcConnSetUserData ​

c
int TiRtcConnSetUserData(tirtc_conn_t hconn, void *user_data);

给连接绑定业务上下文。

TiRtcConnGetUserData ​

c
void *TiRtcConnGetUserData(tirtc_conn_t hconn);

取回绑定在连接上的业务上下文。

媒体发送 ​

TiRtcSendMessageStream ​

c
int TiRtcSendMessageStream(tirtc_conn_t hconn,
                           const TIRTCFRAMEINFO *pFi,
                           const void *frame);

通用发送入口，线程安全，支持多线程并发调用。

  • media == TIRTC_MEDIA_MESSAGE 时发送流内消息。
  • media 为音频或视频时，按 TIRTCFRAMEINFO 描述发送媒体帧。
  • 返回值大于 0 表示实际发送字节数；负值为错误码。
  • 返回 TIRTC_E_BUSY 时，表示发送缓冲区已满；Nano 会对视频流丢弃非关键帧直到下一个关键帧。
  • 视频流首帧不是关键帧时，这条视频流会一直等到关键帧到来后再开始发。
  • 流内消息可以放在任意 stream_id 上，TIRTCFRAMEINFO 里除 length 之外的语义由你的业务自己约定。

TiRtcSendVideoStream ​

c
int TiRtcSendVideoStream(tirtc_conn_t hconn,
                         const TIRTCFRAMEINFO *pFi,
                         const void *frame);

视频发送封装。pFi->media 必须是视频类型。

TiRtcSendAudioStream ​

c
int TiRtcSendAudioStream(tirtc_conn_t hconn,
                         const TIRTCFRAMEINFO *pFi,
                         const void *frame);

音频发送封装。pFi->media 必须是音频类型。

命令与订阅控制 ​

TiRtcSendCommand ​

c
int TiRtcSendCommand(tirtc_conn_t hconn,
                     uint32_t cmdw,
                     const void *data,
                     uint32_t length);

在命令通道上发送数据。cmdw 必须大于等于 0x2000。

atomic_get_cmd_sn ​

c
uint32_t atomic_get_cmd_sn(void);

返回下一个命令序号。需要乱序应答时，先取序号，再挂等待项，再发送命令。

命令字辅助宏 ​

c
#define GET_CMD(cmdw) (((cmdw) >> 1) & 0x7fff)
#define GET_SN(cmdw) ((cmdw) >> 16)
#define MAKE_CMDW(cmd, sn) (((uint32_t)(sn)) << 16 | (((cmd) << 1) & 0xffff))
#define TiRtcSendReq(hconn, cmd, data, length) ...
#define TiRtcSendReqWithSn(hconn, sn, cmd, data, length) ...
#define TiRtcSendResp(hconn, cmdw, data, length) ...

用于组装命令字、发送请求和发送应答。

需要 sn、请求/响应配对或乱序应答时，再进入对应的高级文档设计业务协议。

TiRtcRequestKeyFrame ​

c
int TiRtcRequestKeyFrame(tirtc_conn_t hconn, uint8_t stream_id);

请求对端在指定视频流上立即发送关键帧。

TiRtcSubscribeVideo ​

c
int TiRtcSubscribeVideo(tirtc_conn_t hconn, uint8_t stream_id);

请求对端开始发送指定视频流。

TiRtcUnsubscribeVideo ​

c
int TiRtcUnsubscribeVideo(tirtc_conn_t hconn, uint8_t stream_id);

请求对端停止发送指定视频流。

TiRtcSubscribeAudio ​

c
int TiRtcSubscribeAudio(tirtc_conn_t hconn, uint8_t stream_id);

请求对端开始发送指定音频流。

TiRtcUnsubscribeAudio ​

c
int TiRtcUnsubscribeAudio(tirtc_conn_t hconn, uint8_t stream_id);

请求对端停止发送指定音频流。

日志 ​

TiRtcLogConfig ​

c
void TiRtcLogConfig(int bOutputToConsole, const char *path, uint32_t size);

配置 SDK 内置文件日志。仅 Linux 平台有效。

TiRtcLogSetLevel ​

c
void TiRtcLogSetLevel(int level);

设置日志详细程度。

TiRtcLogSetCallback ​

c
void TiRtcLogSetCallback(TIRTCLOGCALLBACK cb);

把日志输出改为回调方式。

WHIP ​

TiRtcWhipAccept ​

c
int TiRtcWhipAccept(const char *offer,
                    int offer_len,
                    TIRTCWHIPSERVERONSDPREADYCB whip_sdp_cb,
                    TIRTCCONNECTCALLBACK cb,
                    void *user);

设备端接收 WHIP offer，并异步产出 answer SDP。

TiRtcWhipConnect ​

c
int TiRtcWhipConnect(const char *service_desc,
                     const char *token,
                     TIRTCCONNECTCALLBACK cb,
                     void *user_data);

通过平台信令发起 WHIP 连接。

常见误用 ​

误用结果
TIRTCCALLBACKS 写在栈上后立即返回回调指针失效
在回调里做阻塞 I/O 或长时间计算拖住 SDK 内部线程
在 on_conn_error 回调里直接调用 TiRtcDisconnect()可能卡住 SDK 内部线程；应改到回调外处理
把 TiRtcStart() 返回 0 当成已经启动完成启动信号判断错误；应以 TiEVENT_SYS_STARTED 为准
TIRTC_OPT_MAX_SEND_BUFFER 在 TiRtcInit() 之后才设置该选项不会生效
TIRTC_OPT_NETWORK_TYPE 设成 TIRTC_NETCONN_4G 却没填 TIRTC_OPT_ICCID启动参数不完整
同一连接内让音频和视频复用同一个 stream_id流冲突
视频首帧不是关键帧这路视频要等到下一个关键帧才会发出
音频帧 flags 不填采样规格对端无法按预期解释音频参数
TiRtcConnect() 命中 TIRTC_E_CACHE_EXPIRED 后仍继续用旧缓存重试无法重新建连
TiRtcSendMessageStream() 返回 TIRTC_E_BUSY 后仍持续堆发送发送缓冲区持续拥塞
收到 on_conn_error 后继续发流或发命令调用不再有效

相关文档 ​

Ti RTC 开发文档

Copyright © 2025