Ti RTC 开发文档

中文

English

中文

English

C API 参考 ​

这页是 C SDK 的 API 详细使用说明，收录公开类型、回调、函数、宏、参数、返回值和生命周期规则。

调用顺序 ​

阶段接口说明
配置TiRtcSetOption()在 TiRtcStart() 前设置。TIRTC_OPT_MAX_SEND_BUFFER 必须在 TiRtcInit() 前设置才生效。
初始化TiRtcInit()初始化进程级 SDK 运行时。
启动TiRtcStart()启动 SDK。返回 0 只表示启动请求已提交，真正启动完成以 TIRTC_EVENT_SYS_STARTED 为准。
使用TiRtcConnect() / 回调 / 发送接口连接建立后收发媒体、流内消息和命令。
停止TiRtcStop()停止 SDK。完成后通过 TIRTC_EVENT_SYS_STOPPED 通知。
释放TiRtcUninit()释放 SDK 运行时资源。

典型顺序：

c
TiRtcSetOption(TIRTC_OPT_MAX_SEND_BUFFER, &max_send_buffer, sizeof(max_send_buffer));
TiRtcInit();
TiRtcSetOption(TIRTC_OPT_DEVICE_SECRET_KEY, device_secret_key, strlen(device_secret_key));
TiRtcStart(device_id, &callbacks);

/* 建连、收发媒体和命令 */

TiRtcStop();
TiRtcUninit();

错误码 ​

错误码详情也可见错误码说明。

常量值含义
TIRTC_E_NOT_INITIALIZED-40001未初始化，需先调用 TiRtcInit()
TIRTC_E_INVALID_HANDLE-40002连接无效
TIRTC_E_INVALID_PARAMETER-40003参数无效
TIRTC_E_INVALID_LICENSE-40004设备身份参数无效
TIRTC_E_TIMEOUTED-40005操作超时
TIRTC_E_BUSY-40006网络忙或发送缓冲区满
TIRTC_E_CONN_TIMEOUTCLOSE-40007连接因心跳超时关闭
TIRTC_E_CONN_REMOTECLOSE-40008连接被远端主动关闭
TIRTC_E_CONN_OTHER_ERROR-40009其他连接错误
TIRTC_E_LACK_OF_RESOURCE-40010资源不足，包含内存不足
TIRTC_E_CACHE_EXPIRED-40011连接参数缓存过期，需重新传入有效 token
TIRTC_E_SERVER_ERROR-40012服务器端错误
TIRTC_E_INTERNAL_ERROR-40013SDK 内部错误
TIRTC_E_NO_SECRET_KEY-40014未设置 device_secret_key
TIRTC_E_UNEXPECTED_RESPONSE-40015服务器响应格式非预期

基础类型 ​

tirtc_conn_t ​

c
typedef struct _tirtc_conn *tirtc_conn_t;

表示一条点对点连接。

  • 其他端连接到本端时，通过 TIRTCCALLBACKS.on_conn_accepted 传出。
  • 主动连接通过 TIRTCCONNECTCALLBACK 传出。
  • on_disconnected 回调返回后，这个连接对象由 SDK 自动释放。
  • TiRtcDisconnect() 返回后，就应把该连接对象视为不可再用；如果你的业务需要等 SDK 内部释放完成，再等 on_disconnected 回调。

TIRTCNETCONN ​

c
typedef enum {
    TIRTC_NETCONN_WIFI = 0,
    TIRTC_NETCONN_4G
} TIRTCNETCONN;
取值说明
TIRTC_NETCONN_WIFIWi-Fi，默认值
TIRTC_NETCONN_4G运营商数据网络；使用时需要设置 TIRTC_OPT_ICCID

TIRTCOPTION ​

TiRtcSetOption() 使用的配置项。如无特别说明，配置项应在 TiRtcStart() 前设置。

配置项data 类型调用时机与说明
TIRTC_OPT_SERVICE_ENDPOINTconst char *服务入口地址。不设置时使用默认入口。
TIRTC_OPT_DEVICE_SECRET_KEYconst char *设置 device_secret_key。需要允许其他端连接到本端时，先设置该选项，再用 device_id 启动。不要把 device_secret_key 写进日志、截图或客户端代码。
TIRTC_OPT_MAX_CONNECTIONSint *最大连接数，主要用于资源受限的系统。
TIRTC_OPT_NETWORK_TYPEint *联网方式，值见 TIRTCNETCONN。默认 TIRTC_NETCONN_WIFI。
TIRTC_OPT_ICCIDconst char *4G SIM 卡 ICCID。TIRTC_OPT_NETWORK_TYPE 为 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 开启，默认 1。

开启 TIRTC_OPT_CONNECT_CACHE 后，TiRtcConnect() 成功时会按 remote_id 缓存服务器返回的连接参数。缓存有效期由服务器返回；有效期内再次连接同一 remote_id 时，token 可传 NULL。缓存未命中或过期时，TiRtcConnect() 返回 TIRTC_E_CACHE_EXPIRED。

TIRTCMEDIA ​

TIRTCFRAMEINFO.media 使用的媒体类型。

c
typedef enum TIRTCMEDIA {
    TIRTC_MEDIA_MESSAGE = 0,
    TIRTC_AUDIO_MIN = 1,
    TIRTC_AUDIO_PCM = TIRTC_AUDIO_MIN,
    TIRTC_AUDIO_ALAW = 2,
    TIRTC_AUDIO_AAC = 3,
    TIRTC_AUDIO_OPUS = 4,
    TIRTC_AUDIO_MAX = 64,
    TIRTC_VIDEO_MIN = 65,
    TIRTC_VIDEO_JPEG = TIRTC_VIDEO_MIN,
    TIRTC_VIDEO_H264 = 66,
    TIRTC_VIDEO_H265 = 67,
    TIRTC_VIDEO_MAX = 127
} 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 视频帧

相关宏：

c
#define TIRTC_IS_AUDIO(mt) ((mt) >= TIRTC_AUDIO_MIN && (mt) <= TIRTC_AUDIO_MAX)
#define TIRTC_IS_VIDEO(mt) ((mt) >= TIRTC_VIDEO_MIN && (mt) <= TIRTC_VIDEO_MAX)

TIRTCAUDIOSAMPLE ​

音频采样规格，填入音频帧的 TIRTCFRAMEINFO.flags。

取值说明
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，同一连接内音频和视频不能共用同一个 stream_id。
media媒体类型，取值见 TIRTCMEDIA。
flags视频帧最低位表示关键帧；音频帧填 TIRTCAUDIOSAMPLE。
reserved预留字段，当前填 0。
ts时间戳，单位毫秒。
length数据长度，单位字节，不含帧头自身。

视频关键帧相关宏：

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

同一连接内，音频和视频不能复用同一个 stream_id。发送视频时，每路视频流的第一帧必须是关键帧；发送音频时，flags 填 TIRTCAUDIOSAMPLE 取值。

TIRTCSYSEVENT ​

TIRTCCALLBACKS.on_event 使用的系统事件。

取值说明
TIRTC_EVENT_SYS_STARTEDSDK 成功启动
TIRTC_EVENT_SYS_STOPPEDSDK 已停止
TIRTC_EVENT_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;

C SDK 通过这个结构体向应用通知连接事件、媒体帧、命令和内部事件。

  • 所有回调都在 SDK 自己的线程执行。回调里只做轻量处理；如果要写文件、解码、编码、访问网络或等待锁，先把数据复制到业务线程。
  • TIRTCCALLBACKS 结构体和其中的函数指针生命周期必须覆盖整个 SDK 运行期，不能指向临时栈变量。
  • 回调里的 data 指针只在当前回调内有效；需要跨线程使用时，先自行复制。
回调触发时机使用约束
on_eventSDK 内部事件。event 取值见 TIRTCSYSEVENT。data 可为 NULL，长度由 len 给出。
on_conn_accepted其他端已经连接到本端。hconn 可立即用于发送媒体或命令。
on_conn_error连接出现错误。出现后该连接上的收发不再有效；应在回调外调用 TiRtcDisconnect() 释放资源。
on_disconnectedTiRtcDisconnect() 内部操作完成。回调返回后连接对象由 SDK 自动释放。只有业务需要等待 SDK 释放完成时才实现它。
on_audio收到对端音频帧。data 回调返回后失效。
on_video收到对端视频帧。data 回调返回后失效。
on_message收到对端流内消息。对应 media == TIRTC_MEDIA_MESSAGE。
on_command收到对端命令通道数据。cmdw 是原始命令字，格式见命令通道章节。
on_request_key_frame对端请求在指定流上立即发送关键帧。下一帧应输出关键帧。
on_subscribe_video对端请求开始发送指定视频流。返回 0 表示接受，非 0 表示拒绝。
on_unsubscribe_video对端请求停止发送指定视频流。停止对应视频流发送。
on_subscribe_audio对端请求开始发送指定音频流。返回 0 表示接受，非 0 表示拒绝。
on_unsubscribe_audio对端请求停止发送指定音频流。停止对应音频流发送。

不要在 on_conn_error 中直接调用 TiRtcDisconnect()。把连接对象放入业务线程或事件循环，再在回调外断开。

TIRTCCONNECTCALLBACK ​

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

TiRtcConnect() 和 WHIP 连接接口的异步结果回调。

参数说明
error0 表示连接成功；非 0 为错误码。
hconn连接成功时为有效连接对象；失败时为 NULL。
user_data调用连接接口时传入的用户上下文指针。

TIRTCLOGCALLBACK ​

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

日志输出回调。log 不是以 \0 结尾的字符串，读取时以 length 为准。

TIRTCWHIPSERVERONSDPREADYCB ​

c
typedef void (*TIRTCWHIPSERVERONSDPREADYCB)(const char *sdp, int len, void *user);

WHIP 服务端 answer SDP 就绪回调。

参数说明
sdpanswer SDP 字符串。
lenSDP 长度，单位字节。
userTiRtcWhipAccept() 传入的用户数据指针。

禁止在此回调中阻塞。

生命周期 ​

TiRtcGetVersion ​

c
const char *TiRtcGetVersion(void);

返回 SDK 版本字符串。

返回值说明
const char *静态存储的版本字符串，无需释放。

TiRtcGetErrorStr ​

c
const char *TiRtcGetErrorStr(int error);

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

参数说明
errorTiRTC 错误码，或 0。
返回值说明
const char *静态字符串。0 返回 OK，未知错误码返回未知码说明。

TiRtcInit ​

c
int TiRtcInit(void);

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

返回值说明
0成功
负数错误码

TIRTC_OPT_MAX_SEND_BUFFER 必须在 TiRtcInit() 前设置才生效。

TiRtcUninit ​

c
void TiRtcUninit(void);

释放 SDK 运行时资源。通常在 TiRtcStop() 完成后调用。

TiRtcSetOption ​

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

设置全局配置项。

参数说明
opt配置项，取值见 TIRTCOPTION。
data配置数据指针，类型与具体配置项有关。
lendata 指向的数据长度，单位字节。
返回值说明
0成功
TIRTC_E_INVALID_PARAMETERopt 或 data 非法
其他负数错误码

TiRtcStart ​

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

启动 SDK。

参数说明
identity启动身份参数，或 NULL。
cbs回调结构体指针，生命周期要求见 TIRTCCALLBACKS。

启动身份参数支持两种推荐用法：

传值作用
NULL只允许本端主动连接其他端，不允许其他端连接到本端。
"<device_id>"允许其他端连接到本端。调用前先通过 TiRtcSetOption(TIRTC_OPT_DEVICE_SECRET_KEY, ...) 设置 device_secret_key。
返回值说明
0启动请求已提交；实际启动结果通过 cbs->on_event(TIRTC_EVENT_SYS_STARTED, ...) 通知。
负数错误码

TiRtcStop ​

c
int TiRtcStop(void);

停止 SDK。

返回值说明
0停止请求已提交或处理成功。完成后通过 TIRTC_EVENT_SYS_STOPPED 通知。
负数错误码

连接管理 ​

TiRtcConnect ​

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

主动发起 P2P 连接。

参数说明
remote_id目标标识。具体取值应和服务端签发 token 时绑定的目标一致；连接某台设备时通常等于目标 device_id。
token你的业务服务端签发的连接授权凭证。首次连接应传有效 token。
cb连接结果回调，不能为 NULL。
user_data原样传给 cb 的用户上下文指针。
返回值说明
0连接请求已提交，最终结果通过 cb 通知。
TIRTC_E_CACHE_EXPIRED缓存已过期，需重新获取并传入有效 token。
其他负数错误码

token 是一次性的，不要重复使用。开启连接参数缓存后，SDK 会缓存成功连接时服务器返回的连接参数；缓存有效期内再次连接同一 remote_id 时，token 可传 NULL。

TiRtcDisconnect ​

c
int TiRtcDisconnect(tirtc_conn_t hconn);

主动断开连接。

参数说明
hconn连接对象。
返回值说明
0成功提交断开操作。
TIRTC_E_INVALID_HANDLE连接对象无效。
其他负数错误码

这是异步操作，不会阻塞到 SDK 内部彻底释放完成。调用返回后即认为 hconn 不再有效，不应再对它执行任何操作。若需与 SDK 内部释放同步，可在 on_disconnected() 回调中处理。

TiRtcGetSendBufferUsed ​

c
size_t TiRtcGetSendBufferUsed(tirtc_conn_t hconn);

返回连接当前发送缓冲区已使用字节数。可与 TIRTC_OPT_MAX_SEND_BUFFER 设置的上限对比，用于判断是否需要丢帧或限流。

参数说明
hconn连接对象。
返回值说明
size_t已使用字节数；hconn 无效时返回 0。

TiRtcConnSetUserData ​

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

把用户数据指针关联到连接。

参数说明
hconn连接对象。
user_data用户数据指针，可通过 TiRtcConnGetUserData() 取回。
返回值说明
0成功
TIRTC_E_INVALID_HANDLE连接对象无效

TiRtcConnGetUserData ​

c
void *TiRtcConnGetUserData(tirtc_conn_t hconn);

取回由 TiRtcConnSetUserData() 关联的用户数据指针。

参数说明
hconn连接对象。
返回值说明
void *用户数据指针；hconn 无效时返回 NULL。

媒体发送 ​

TiRtcSendMessageStream ​

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

通用的音频、视频和流内消息发送接口。线程安全，支持多线程并发调用。

参数说明
hconn连接对象。
pFi帧信息指针，不能为 NULL。
frame待发送的数据指针。
返回值说明
> 0发送字节数。
TIRTC_E_INVALID_HANDLE连接对象无效。
TIRTC_E_INVALID_PARAMETERpFi 为 NULL 或 media 类型非法。
TIRTC_E_BUSY发送缓冲区已满，视频帧被丢弃。
其他负数错误码。

发送策略：

  • pFi->media == TIRTC_MEDIA_MESSAGE 时发送流内消息。
  • pFi->media 为音频或视频类型时，按 TIRTCFRAMEINFO 描述发送媒体帧。
  • 发送操作只根据 pFi->media 选择传输策略，不检查数据内容。
  • 视频流首帧必须是关键帧。如果首帧不是关键帧，这路视频会等到关键帧到来后再开始发送。
  • 发送缓冲区满时，SDK 会丢弃后续非关键视频帧，直到下一个关键帧到来。
  • 音频帧会直接加入发送队列，不会按视频关键帧规则丢帧。
  • 流内消息可以放在任意 stream_id 上，除 length 外的帧头语义由你的业务协议自行解释。

TiRtcSendVideoStream ​

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

视频发送封装。内部调用 TiRtcSendMessageStream()。

参数说明
hconn连接对象。
pFi帧信息指针，pFi->media 必须是视频类型。
frame视频数据指针。
返回值说明
> 0发送字节数。
TIRTC_E_INVALID_PARAMETERpFi->media 不是视频类型。
其他同 TiRtcSendMessageStream()。

TiRtcSendAudioStream ​

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

音频发送封装。内部调用 TiRtcSendMessageStream()。

参数说明
hconn连接对象。
pFi帧信息指针，pFi->media 必须是音频类型，pFi->flags 填音频采样规格。
frame音频数据指针。
返回值说明
> 0发送字节数。
TIRTC_E_INVALID_PARAMETERpFi->media 不是音频类型。
其他同 TiRtcSendMessageStream()。

命令通道 ​

命令通道用于传输自定义控制数据，和媒体流相互独立。对端通过 TIRTCCALLBACKS.on_command 收到数据。

TiRtcSendCommand ​

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

在命令通道上发送数据。

参数说明
hconn连接对象。
cmdw原始命令字。开发者应用应使用大于等于 0x10000 的值。
data命令参数数据指针，可为 NULL。
length命令参数长度，单位字节。
返回值说明
> 0发送字节数。
< 0错误码。

命令字格式 ​

当你只需要单向控制消息时，可以直接用大于等于 0x10000 的 cmdw。当你需要双向请求、重复请求或乱序应答时，使用 SDK 提供的命令字格式。

位域字段说明
bit 0RESPONSE_BIT为 1 表示这是对己方先前请求的应答；为 0 表示请求。
bit 1~15cmd命令标识。开发者应用使用从 0x4000 开始的值。
bit 16~31sn命令序号，用于匹配请求和应答。

命令字取值范围：

cmdw 范围cmd 范围使用者
0 ~ 0x1fff0 ~ 0xfffSDK 内部使用
0x2000 ~ 0xffff0x1000 ~ 0x3fff预留范围，不用于开发者应用
>= 0x100000x4000 ~ 0x7fff开发者应用

atomic_get_cmd_sn ​

c
uint32_t atomic_get_cmd_sn(void);

原子地返回下一个命令序号并自增。返回值低 16 位为有效序号。

需要乱序应答时，使用顺序是：

  1. 调用 atomic_get_cmd_sn() 获取序号。
  2. 将带有该序号的应答处理器挂入等待队列。
  3. 发送命令。

必须先挂等待队列再发送命令，否则应答可能在处理器挂入前就已到达。

命令字辅助宏 ​

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 IS_RESERVED_CMDW(cmdw) (cmdw < 0x2000)
#define RESPONSE_BIT 0x0001
#define TiRtcSendReq(hconn, cmd, data, length) TiRtcSendCommand(hconn, (cmd)&~RESPONSE_BIT, data, length)
#define TiRtcSendReqWithSn(hconn, sn, cmd, data, length) \
    TiRtcSendCommand(hconn, MAKE_CMDW(cmd, sn), data, length)
#define TiRtcSendResp(hconn, cmdw, data, length) TiRtcSendCommand(hconn, (cmdw)|RESPONSE_BIT, data, length)
宏说明
GET_CMD(cmdw)从命令字提取命令标识。
GET_SN(cmdw)从命令字提取命令序号。
MAKE_CMDW(cmd, sn)用命令标识和序号生成命令字。
IS_RESERVED_CMDW(cmdw)判断命令字是否落在 SDK 内部使用范围。
RESPONSE_BIT应答标志位。
TiRtcSendReq(...)发送请求，清除应答位。
TiRtcSendReqWithSn(...)发送请求，并自动把 sn 填入高 16 位。
TiRtcSendResp(...)发送应答，置位应答位。cmdw 直接使用收到的请求命令字。

TiRtcRequestKeyFrame ​

c
int TiRtcRequestKeyFrame(tirtc_conn_t hconn, uint8_t stream_id);

请求对端在指定视频流上立即发送关键帧。对端会收到 on_request_key_frame 回调。

TiRtcSubscribeVideo ​

c
int TiRtcSubscribeVideo(tirtc_conn_t hconn, uint8_t stream_id);

请求对端开始发送指定视频流。对端会收到 on_subscribe_video 回调。

TiRtcUnsubscribeVideo ​

c
int TiRtcUnsubscribeVideo(tirtc_conn_t hconn, uint8_t stream_id);

请求对端停止发送指定视频流。对端会收到 on_unsubscribe_video 回调。

TiRtcSubscribeAudio ​

c
int TiRtcSubscribeAudio(tirtc_conn_t hconn, uint8_t stream_id);

请求对端开始发送指定音频流。对端会收到 on_subscribe_audio 回调。

TiRtcUnsubscribeAudio ​

c
int TiRtcUnsubscribeAudio(tirtc_conn_t hconn, uint8_t stream_id);

请求对端停止发送指定音频流。对端会收到 on_unsubscribe_audio 回调。

上述订阅和关键帧接口返回 0 表示成功，否则返回错误码。

日志 ​

TiRtcLogConfig ​

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

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

参数说明
bOutputToConsole非 0 时同时输出到 stdout。
path日志文件路径。传 NULL 不输出到文件。
size日志文件最大字节数，超出后滚动覆盖。

TiRtcLogSetLevel ​

c
void TiRtcLogSetLevel(int level);

设置日志详细程度。值越大越详细。level > 10 时，同时将底层 WebRTC 库的日志级别设为 level - 10。

TiRtcLogSetCallback ​

c
void TiRtcLogSetCallback(TIRTCLOGCALLBACK cb);

设置日志输出回调。

  • 设置后，SDK 将所有日志内容通过回调传给应用，不再自行输出到文件或控制台。
  • 通常用于无文件系统的小系统。
  • cb 传 NULL 可清除回调，恢复默认输出行为。

WHIP ​

TiRtcWhipAccept ​

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

WHIP 服务端接口：接收 WHIP offer SDP，并异步生成 answer SDP。

参数说明
offeroffer SDP 数据，通常来自 HTTP 请求 body。
offer_lenoffer SDP 长度，单位字节。
whip_sdp_cbanswer SDP 就绪回调。应在该回调中向发起 WHIP 请求的一端返回 HTTP 201，body 为 answer SDP。
cb数据通道全部就绪或出错时触发的连接结果回调。
user原样传给 whip_sdp_cb 和 cb 的用户数据指针。
返回值说明
0请求已提交。
负数错误码。

TiRtcWhipConnect ​

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

WHIP 发起接口：通过平台服务向目标发起连接。

参数说明
service_desc服务描述字符串，不是 remote_id 或 device_id。
token你的业务服务端签发的连接授权凭证。
cb连接结果回调。
user_data原样传给 cb 的用户上下文指针。
返回值说明
0连接请求已提交。HTTP 请求和 ICE 协商在后台执行，最终结果通过 cb 通知。
负数错误码。

常见误用 ​

误用结果处理方式
TIRTCCALLBACKS 写在栈上，函数返回后还继续使用 SDK回调指针失效使用静态存储、全局对象或生命周期覆盖 SDK 运行期的对象。
在回调里写文件、等待锁、sleep 或做长时间计算阻塞 SDK 自己的线程在回调里快速复制数据，再交给业务线程处理。
在 on_conn_error 里直接调用 TiRtcDisconnect()可能阻塞 SDK 自己的线程设置标志或投递任务，在回调外断开连接。
把 TiRtcStart() 返回 0 当成 SDK 已启动启动状态判断错误等待 TIRTC_EVENT_SYS_STARTED。
TIRTC_OPT_MAX_SEND_BUFFER 在 TiRtcInit() 之后才设置该选项不会生效在 TiRtcInit() 前设置。
设置 TIRTC_NETCONN_4G 但没有设置 TIRTC_OPT_ICCID启动参数不完整同时提供 ICCID。
同一连接内让音频和视频共用同一个 stream_id流冲突为每一路音频或视频分配独立 stream_id。
视频首帧不是关键帧该路视频要等到下一个关键帧才会发出第一帧设置 TIRTC_FRAME_FLAG_KEY_FRAME。
音频帧 flags 未填写采样规格对端无法按预期解释音频参数按 TIRTCAUDIOSAMPLE 填写。
TiRtcConnect() 返回 TIRTC_E_CACHE_EXPIRED 后继续用 token == NULL 重试无法重新建连重新获取有效 token 后再连接。
TiRtcSendMessageStream() 返回 TIRTC_E_BUSY 后继续堆积发送发送缓冲区持续拥塞丢弃非关键视频帧，按发送缓冲区状态限流。
收到 on_conn_error 后继续发流或发命令调用不再有效断开并清理该连接。
给 TiRtcSendCommand() 传入小于 0x10000 的开发者命令字可能落入保留范围，导致行为不符合公开约束开发者应用统一使用大于等于 0x10000 的命令字。

相关文档 ​

Ti RTC 开发文档

Copyright © 2025