WebRTC 对讲接口说明文档

文档版本	V1.1
修订日期	2026-08-24
对应头文件	components/media/framework/api/include/api_webrtc.h
类型定义	components/media/framework/component_adapter/webrtc/include/ss_webrtc.h
适用模块	WebRTC 点对点音视频对讲（WebRTC）

---

1 概述

本模块对外提供 hi_fw_webrtc_* 系列接口，封装 WebRTC 点对点音视频对讲能力：通过 light_msg 与 webrtc_impl 通信，最终调用底层 ss_webrtc_*（封装 libdatachannel P2P 会话 + JitterBuffer + OpenH264 软解）。接口简洁清晰：init / deinit / start / stop + 信令（offer / sdp / candidate）+ 帧发送。

注意：本模块仅支持直连模式（Direct），不提供跨进程（IPC）客户端实现。媒体通道由调用方通过媒体框架（hi_fw_media_*）建立并拥有，WebRTC 模块仅做纯网络传输：以 attach 模式（attach_external_media = TD_TRUE）经 hi_fw_media_venc_reg_cb / hi_fw_media_aenc_reg_cb / hi_fw_media_adec_send_stream 复用框架预建的 VENC chn2 / AENC chn1 / ADEC chn0 通道，数据经框架回调收发。

提供两套信令处理方式：

• 手动信令（hi_fw_webrtc_init）：本地 SDP / ICE 经 on_signaling 回调交给应用，由应用转发到信令服务器；
• 内建信令（hi_fw_webrtc_init_with_signaling）：在手动版之上内建 WebSocket 信令客户端，自动连接信令服务器、加入房间、转发 SDP / ICE，断线自动重连。

模型层次：

WebRTC 对讲（Direct）
  ├─ light_msg 通道 → webrtc_impl → ss_webrtc_*
  ├─ WebRTC P2P 会话（libdatachannel）
  │    ├─ 视频通道（H.264 RTP 收发 + OpenH264 软解渲染）
  │    └─ 音频通道（裸 OPUS / RFC 7587 RTP 收发）
  ├─ 信令（手动 / 内建 WebSocket）
  └─ 媒体通道（attach 模式复用框架预建通道：VENC chn2 / AENC chn1 / ADEC chn0）

---

2 接口总览

编号	接口	模块	功能概述
1	hi_fw_webrtc_direct_init	模式管理	初始化 direct API（创建 light_msg 通道并注册 webrtc_impl）
2	hi_fw_webrtc_direct_deinit	模式管理	反初始化 direct API
3	hi_fw_webrtc_init	会话管理	初始化 WebRTC 对讲（手动信令）
4	hi_fw_webrtc_deinit	会话管理	反初始化，释放资源
5	hi_fw_webrtc_start	会话管理	启动对讲（发起方自动创建 Offer）
6	hi_fw_webrtc_stop	会话管理	停止对讲
7	hi_fw_webrtc_create_offer	信令	创建 SDP Offer
8	hi_fw_webrtc_set_remote_sdp	信令	设置远端 SDP
9	hi_fw_webrtc_add_candidate	信令	添加远端 ICE Candidate
10	hi_fw_webrtc_send_video	数据	发送视频帧（H.264 Annex-B）
11	hi_fw_webrtc_send_audio	数据	发送音频帧（裸 OPUS，RFC 7587）
12	hi_fw_webrtc_request_keyframe	数据	请求对端关键帧
13	hi_fw_webrtc_is_connected	状态	查询连接状态
14	hi_fw_webrtc_set_log	配置	配置日志轮转
15	hi_fw_webrtc_init_with_signaling	内建信令	初始化 WebRTC 对讲（内建信令处理）
16	hi_fw_webrtc_deinit_with_signaling	内建信令	反初始化（内建信令版本）

---

3 API 参考

3.1 hi_fw_webrtc_direct_init

【描述】

初始化 direct API：创建 webrtc_impl 并初始化 light_msg 消息通道。仅在直连模式下使用（本模块不提供 IPC 实现）。幂等：已初始化时直接返回成功。

【语法】

td_s32 hi_fw_webrtc_direct_init(td_void);

【参数】

无。

【返回值】

返回值	描述
0	初始化成功。
非0	初始化失败，返回 light_msg 通道错误码（见 5.2）。

【注意】

• 需在 hi_fw_webrtc_init() / hi_fw_webrtc_init_with_signaling() 之前调用；
• 与 hi_fw_webrtc_direct_deinit() 成对调用；
• 重复调用返回成功（幂等）。

【举例】

td_s32 ret = hi_fw_webrtc_direct_init();
if (ret != 0) {
    /* 处理失败 */
}

3.2 hi_fw_webrtc_direct_deinit

【描述】

反初始化 direct API：销毁 light_msg 通道并释放 webrtc_impl，同时兜底调用底层 ss_webrtc_deinit()（幂等）。

【语法】

td_void hi_fw_webrtc_direct_deinit(td_void);

【参数】

无。

【返回值】

无。

【注意】

• 与 hi_fw_webrtc_direct_init() 成对调用；
• 调用前应先 hi_fw_webrtc_deinit()，未初始化状态调用无副作用。

【举例】

hi_fw_webrtc_direct_deinit();

3.3 hi_fw_webrtc_init

【描述】

初始化 WebRTC 对讲会话（手动信令模式）。创建底层会话上下文并保存配置与回调（PeerConnection 等核心对象在 start 阶段才创建），并注册帧数据 / 状态 / 信令回调。本地生成的 SDP / ICE 经 on_signaling 回调交应用转发。

【语法】

td_s32 hi_fw_webrtc_init(const ot_webrtc_init_param *param, const ot_webrtc_callback *cb);

【参数】

参数名称	输入/输出	类型	描述
param	输入	const ot_webrtc_init_param *	信令 / STUN / TURN / 角色等配置，不能为 NULL。
cb	输入	const ot_webrtc_callback *	回调（帧数据 / 状态 / 信令），可为 NULL。

【返回值】

返回值	描述
0	初始化成功。
非0	初始化失败。API 层参数错误返回 -1（TD_FAILURE）；其余为 ss_webrtc_init 返回值透传或 light_msg 通道错误码。

【注意】

• param 为 NULL 返回 -1；
• 需先调用 hi_fw_webrtc_direct_init()；
• 媒体通道由调用方拥有，本接口不创建媒体通路，attach 模式下经 hi_fw_media_* 接口复用框架预建通道；
• 手动信令模式下，on_signaling 回调收到的本地 SDP / ICE 需应用自行转发到信令服务器；如需自动处理信令，使用 hi_fw_webrtc_init_with_signaling()。

【举例】

ot_webrtc_init_param param = {0};
ot_webrtc_callback cb = {0};

strcpy(param.stun_host, "stun.l.google.com");
param.stun_port = 19302;
param.is_initiator = TD_TRUE;
param.attach_external_media = TD_TRUE;

cb.on_video_frame = my_video_frame_cb;
cb.on_audio_frame = my_audio_frame_cb;
cb.on_state = my_state_cb;
cb.on_signaling = my_signaling_cb;

td_s32 ret = hi_fw_webrtc_init(&param, &cb);
if (ret != 0) {
    /* 处理失败 */
}

3.4 hi_fw_webrtc_deinit

【描述】

反初始化 WebRTC 对讲会话，释放底层资源。

【语法】

td_s32 hi_fw_webrtc_deinit(td_void);

【参数】

无。

【返回值】

返回值	描述
0	反初始化成功。
非0	反初始化失败，为 ss_webrtc_deinit 返回值透传或 light_msg 通道错误码。

【注意】

• 与 hi_fw_webrtc_init() 成对调用；
• 建议先 hi_fw_webrtc_stop() 再调用本接口。

【举例】

hi_fw_webrtc_deinit();

3.5 hi_fw_webrtc_start

【描述】

启动对讲：attach 模式下注册框架 VENC chn2 / AENC chn1 取流回调并启动通道，创建 JitterBuffer / OpenH264 解码器 / PeerConnection 与解码线程；若本端为发起方（is_initiator），内部延时约 500 ms 等待 ICE 收敛后自动创建 Offer（同步消息超时给足 15 秒）。

【语法】

td_s32 hi_fw_webrtc_start(td_void);

【参数】

无。

【返回值】

返回值	描述
0	启动成功。
非0	启动失败，为 ss_webrtc_start 返回值透传或 light_msg 通道错误码。

【注意】

• 需在 hi_fw_webrtc_init() 成功之后调用；
• 发起方启动内部含约 500 ms 的 ICE 收敛等待，调用会阻塞相应时长（同步等待上限 15 秒）。

【举例】

td_s32 ret = hi_fw_webrtc_start();
if (ret != 0) {
    /* 处理失败 */
}

3.6 hi_fw_webrtc_stop

【描述】

停止对讲：停止媒体通道并注销数据回调。

【语法】

td_s32 hi_fw_webrtc_stop(td_void);

【参数】

无。

【返回值】

返回值	描述
0	停止成功。
非0	停止失败，为 ss_webrtc_stop 返回值透传或 light_msg 通道错误码。

【注意】

• 与 hi_fw_webrtc_start() 成对调用。

【举例】

hi_fw_webrtc_stop();

3.7 hi_fw_webrtc_create_offer

【描述】

创建 SDP Offer。创建结果经 on_signaling 回调以 type="offer" 上报本地 SDP，由应用转发给对端。

【语法】

td_s32 hi_fw_webrtc_create_offer(td_void);

【参数】

无。

【返回值】

返回值	描述
0	创建成功。
非0	创建失败，为 ss_webrtc_create_offer 返回值透传或 light_msg 通道错误码。

【注意】

• 通常由发起方在 hi_fw_webrtc_start() 后调用（start 内部已自动创建 Offer 时无需重复调用）；
• 应答方收到对端 Offer 后使用 hi_fw_webrtc_set_remote_sdp() 设置远端 SDP。

【举例】

td_s32 ret = hi_fw_webrtc_create_offer();
if (ret != 0) {
    /* 处理失败 */
}

3.8 hi_fw_webrtc_set_remote_sdp

【描述】

设置远端 SDP：应答方设置对端 Offer，发起方设置对端 Answer。

【语法】

td_s32 hi_fw_webrtc_set_remote_sdp(const td_char *sdp, td_s32 type);

【参数】

参数名称	输入/输出	类型	描述
sdp	输入	const td_char *	远端 SDP 文本，不能为 NULL；长度超过通道载荷上限时报错返回（SDP 超长会导致对端解析失败）。
type	输入	td_s32	SDP 类型：0 = offer（OT_WEBRTC_SDP_OFFER），1 = answer（OT_WEBRTC_SDP_ANSWER），其他取值报错返回 -1。

【返回值】

返回值	描述
0	设置成功。
非0	设置失败。sdp 为 NULL、SDP 超长或 type 非法时返回 -1；其余为 ss_webrtc_set_remote_sdp 返回值透传或 light_msg 通道错误码。

【注意】

• sdp 为 NULL、SDP 过长（截断）或 type 非 0 / 1 时 API 层直接返回 -1 并打印错误日志。

【举例】

td_s32 ret = hi_fw_webrtc_set_remote_sdp(remote_sdp, OT_WEBRTC_SDP_OFFER);
if (ret != 0) {
    /* 处理失败 */
}

3.9 hi_fw_webrtc_add_candidate

【描述】

添加远端 ICE Candidate，用于对端 NAT 穿透。

【语法】

td_s32 hi_fw_webrtc_add_candidate(const td_char *candidate);

【参数】

参数名称	输入/输出	类型	描述
candidate	输入	const td_char *	ICE candidate 字符串（SDP 格式），不能为 NULL。

【返回值】

返回值	描述
0	添加成功。
非0	添加失败。candidate 为 NULL 或超长时返回 -1；其余为 ss_webrtc_add_candidate 返回值透传或 light_msg 通道错误码。

【注意】

• 手动信令模式下，应用收到对端 candidate 后调用本接口逐个添加。

【举例】

td_s32 ret = hi_fw_webrtc_add_candidate(candidate_str);
if (ret != 0) {
    /* 处理失败 */
}

3.10 hi_fw_webrtc_send_video

【描述】

发送视频帧（H.264 Annex-B 裸流），内部封装 RTP + 帧协议。小帧（≤ 1024 字节）经 light_msg 消息通道发送；大帧绕过消息通道直接调用底层 ss_webrtc_send_video（受消息载荷上限约束）。

【语法】

td_s32 hi_fw_webrtc_send_video(const td_u8 *data, td_u32 len, td_u32 rtp_ts, td_bool is_key);

【参数】

参数名称	输入/输出	类型	描述
data	输入	const td_u8 *	视频帧数据指针（H.264 Annex-B），不能为 NULL。
len	输入	td_u32	帧长度（字节），不能为 0；直接发送路径上限 16 MB（WEBRTC_MAX_SEND_VIDEO_BYTES）。
rtp_ts	输入	td_u32	RTP 时间戳（90 kHz 时钟）。
is_key	输入	td_bool	是否为关键帧（I 帧）。

【返回值】

返回值	描述
0	发送成功。
非0	发送失败。data 为 NULL / len 为 0 / 长度越界返回 -1；其余为 ss_webrtc_send_video 返回值透传或 light_msg 通道错误码。

【注意】

• 本接口仅供上行发送；下行接收的视频帧经 on_video_frame 回调交付；
• 消息通道路径同步超时 100 ms，避免阻塞编码线程；
• 调用前需确认会话已连接（可参考 hi_fw_webrtc_is_connected），未连接时发送会失败。

【举例】

td_s32 ret = hi_fw_webrtc_send_video(nalu, nalu_len, rtp_ts, is_key);
if (ret != 0) {
    /* 处理失败 */
}

3.11 hi_fw_webrtc_send_audio

【描述】

发送音频帧（裸 OPUS，RFC 7587），内部封装 RTP（48 kHz 时钟）。小帧（≤ 1024 字节）经消息通道发送；大帧直接调用底层 ss_webrtc_send_audio。

【语法】

td_s32 hi_fw_webrtc_send_audio(const td_u8 *data, td_u32 len, td_u32 rtp_ts);

【参数】

参数名称	输入/输出	类型	描述
data	输入	const td_u8 *	音频帧数据指针（裸 OPUS，RFC 7587），不能为 NULL。
len	输入	td_u32	帧长度（字节），不能为 0；直接发送路径上限 4096 字节（WEBRTC_MAX_SEND_AUDIO_BYTES）。
rtp_ts	输入	td_u32	RTP 时间戳（48 kHz 时钟，OPUS 20 ms 帧步长 960）。

【返回值】

返回值	描述
0	发送成功。
非0	发送失败。data 为 NULL / len 为 0 / 长度越界返回 -1；其余为 ss_webrtc_send_audio 返回值透传或 light_msg 通道错误码。

【注意】

• 下行接收的音频帧经 on_audio_frame 回调交付；
• 消息通道路径同步超时 100 ms。

【举例】

td_s32 ret = hi_fw_webrtc_send_audio(opus_frame, frame_len, rtp_ts);
if (ret != 0) {
    /* 处理失败 */
}

3.12 hi_fw_webrtc_request_keyframe

【描述】

请求对端发送关键帧（当前实现经 DataChannel 发送 request_keyframe 文本消息，非标准 RTCP PLI），用于丢包恢复或首帧请求。

【语法】

td_s32 hi_fw_webrtc_request_keyframe(td_void);

【参数】

无。

【返回值】

返回值	描述
0	请求发送成功。
非0	请求失败，为 ss_webrtc_request_keyframe 返回值透传或 light_msg 通道错误码。

【注意】

• 通常在对端视频花屏、解码失败时调用；
• 已知限制：DataChannel 仅在对端创建时可用，设备↔设备场景（双方均不主动创建 DataChannel）该请求实际不生效，只能等待对端编码器下一个 IDR 帧（默认 GOP 10，约 1 秒）。

【举例】

hi_fw_webrtc_request_keyframe();

3.13 hi_fw_webrtc_is_connected

【描述】

查询当前 WebRTC 连接状态。

【语法】

td_bool hi_fw_webrtc_is_connected(td_void);

【参数】

无。

【返回值】

返回值	描述
TD_TRUE	已连接。
TD_FALSE	未连接，或查询失败（如通道未初始化 / 同步消息失败）。

【注意】

• 查询失败（消息发送返回非 0）时同样返回 TD_FALSE，无法区分"未连接"与"查询失败"。

【举例】

if (hi_fw_webrtc_is_connected()) {
    /* 已连接，可发送帧 */
}

3.14 hi_fw_webrtc_set_log

【描述】

配置 WebRTC 底层日志轮转。

【语法】

td_s32 hi_fw_webrtc_set_log(const td_char *path, td_u32 max_size,
                            td_u32 max_files, td_s32 min_level);

【参数】

参数名称	输入/输出	类型	描述
path	输入	const td_char *	日志文件路径。NULL / 空串时仅输出到 stdout。
max_size	输入	td_u32	单文件大小上限（字节），达到后轮转；0 = 不轮转。
max_files	输入	td_u32	轮转备份数（xxx.log.1 ~ .N）；0 = 写满即截断。
min_level	输入	td_s32	最低级别：0 = DEBUG、1 = INFO、2 = WARN、3 = ERROR。

【返回值】

返回值	描述
0	配置成功。
非0	配置失败。path 超长时返回 -1；其余为 ss_webrtc_set_log_file 返回值透传或 light_msg 通道错误码。

【注意】

• 建议在初始化阶段尽早调用，以便完整记录后续日志。

【举例】

td_s32 ret = hi_fw_webrtc_set_log("/tmp/webrtc.log", 1 << 20, 3, 1);
if (ret != 0) {
    /* 处理失败 */
}

3.15 hi_fw_webrtc_init_with_signaling

【描述】

初始化 WebRTC 对讲（内建信令处理）。在 hi_fw_webrtc_init() 之上内建 WebSocket 信令客户端：

• 自动连接信令服务器并加入房间（以 ws_url / room 为准）；
• 组件 on_signaling 回调（本地 SDP / ICE）自动转发到信令服务器，WS 未连接时先入队（上限 256 条）、连接后补发；
• 收到的 offer / answer / candidate 自动送入 set_remote_sdp / add_candidate；
• WS 断线自动重连（3 s / 10 s / 30 s 退避封顶）：只重建 WS + 重新入房，不重启 RTC 会话，对端重新 offer 即可恢复对讲。

on_video_frame / on_video_render / on_audio_frame / on_state 原样回调应用（userdata 语义不变）；on_signaling 由本接口内部接管，不再回调应用。

【语法】

td_s32 hi_fw_webrtc_init_with_signaling(const ot_webrtc_init_param *param,
                                        const ot_webrtc_callback *cb,
                                        const td_char *ws_url, const td_char *room);

【参数】

参数名称	输入/输出	类型	描述
param	输入	const ot_webrtc_init_param *	信令 / STUN / TURN / 角色等配置（signaling_url / room 仅供日志），不能为 NULL。
cb	输入	const ot_webrtc_callback *	回调（帧数据 / 状态）；on_signaling 会被内部覆盖，不能为 NULL。
ws_url	输入	const td_char *	信令服务器地址（ws://host:port），必填，不能为 NULL / 空串。
room	输入	const td_char *	房间名，必填，不能为 NULL / 空串。

【返回值】

返回值	描述
0	初始化成功。
非0	初始化失败。param / cb / ws_url / room 缺失、或已有会话进行中返回 -1；其余为底层初始化或信令启动错误码。

【注意】

• 一次仅支持一个对讲会话，重复初始化（未反初始化）返回 -1；
• 内部会自动调用 hi_fw_webrtc_direct_init()，应用无需再单独调用；
• 与 hi_fw_webrtc_deinit_with_signaling() 成对使用。

【举例】

ot_webrtc_init_param param = {0};
ot_webrtc_callback cb = {0};

param.is_initiator = TD_TRUE;
param.attach_external_media = TD_TRUE;

cb.on_video_frame = my_video_frame_cb;
cb.on_state = my_state_cb;

td_s32 ret = hi_fw_webrtc_init_with_signaling(&param, &cb,
    "ws://192.168.1.100:8080", "room001");
if (ret != 0) {
    /* 处理失败 */
}

3.16 hi_fw_webrtc_deinit_with_signaling

【描述】

反初始化（内建信令版本）：断开信令连接、停止重连线程，并依次执行 hi_fw_webrtc_stop / hi_fw_webrtc_deinit / hi_fw_webrtc_direct_deinit。

【语法】

td_s32 hi_fw_webrtc_deinit_with_signaling(td_void);

【参数】

无。

【返回值】

返回值	描述
0	反初始化成功。
非0	反初始化失败。

【注意】

• 未初始化时返回成功（幂等）；
• 与 hi_fw_webrtc_init_with_signaling() 成对使用。

【举例】

hi_fw_webrtc_deinit_with_signaling();

---

4 数据类型

4.1 ot_webrtc_init_param（初始化参数）

【说明】

WebRTC 对讲初始化参数：信令 / STUN / TURN / 角色 / 媒体通道复用等配置。完整定义于 ss_webrtc.h，在 api_webrtc.h 中仅作前向声明。

【定义】

typedef struct ot_webrtc_init_param {
    td_char signaling_url[OT_WEBRTC_MAX_URL_LEN]; /* WebSocket 信令服务器地址（仅调用方参考） */
    td_char room[OT_WEBRTC_MAX_NAME_LEN];         /* 房间名 */
    td_char turn_user[OT_WEBRTC_MAX_NAME_LEN];    /* TURN 用户名 */
    td_char turn_pass[OT_WEBRTC_MAX_NAME_LEN];    /* TURN 密码 */
    td_char stun_host[OT_WEBRTC_MAX_URL_LEN];     /* STUN 服务器地址 */
    td_u16  stun_port;                            /* STUN 端口 */
    td_char turn_host[OT_WEBRTC_MAX_URL_LEN];     /* TURN 服务器地址 */
    td_u16  turn_port;                            /* TURN 端口 */
    td_bool is_initiator;                         /* 是否发起方 */
    td_bool attach_external_media;                /* 是否复用外部已建 MPP 通道 */
    td_bool dump_video;                           /* 是否保存接收 YUV（true 时 dump_dir 生效） */
    td_char dump_dir[OT_WEBRTC_MAX_URL_LEN];      /* dump 目录（默认 /tmp） */
    td_char bind_addr[OT_WEBRTC_MAX_URL_LEN];     /* ICE 绑定地址/IP（空 = 0.0.0.0 绑所有网卡） */
} ot_webrtc_init_param;

【成员】

成员名称	描述
signaling_url	信令服务器地址；手动信令模式仅供调用方参考（库内不建立 WebSocket），内建信令模式仅用于日志。
room	房间名；内建信令模式的实际入房以 hi_fw_webrtc_init_with_signaling 的 room 参数为准。
turn_user / turn_pass	TURN 服务器用户名 / 密码。
stun_host / stun_port	STUN 服务器地址 / 端口。
turn_host / turn_port	TURN 服务器地址 / 端口。
is_initiator	是否发起方：发起方 start 时自动创建 Offer，应答方等待对端 Offer。
attach_external_media	是否复用框架预建的 MPP 通道（attach 模式）。1 = attach，经 hi_fw_media_venc_reg_cb / hi_fw_media_aenc_reg_cb / hi_fw_media_adec_send_stream 复用 VENC chn2 + AENC chn1 + ADEC chn0，媒体收发均在框架回调线程内完成。
dump_video	是否保存接收解码的 YUV（为 true 时 dump_dir 生效；音频 dump 当前为空实现，不落盘）。
dump_dir	dump 目录，默认 /tmp。
bind_addr	ICE 绑定地址 / IP：空串 = 0.0.0.0 绑定所有网卡（默认，双网共存 / 单网自动兼容）；填指定网卡 IP（如 4G 网卡地址）则 host 候选仅上报该 IP，媒体只走该网卡。

【注意事项】

• turn_pass 为明文口令。安全约定：底层 ss_webrtc_init 消费后应擦除持有的副本；调用方在 hi_fw_webrtc_init() 返回后也应清零本结构体副本，避免口令明文长期滞留栈 / 堆（core dump / 内存转储泄露风险）。

【相关数据类型及接口】

• 接口：hi_fw_webrtc_init、hi_fw_webrtc_init_with_signaling

4.2 ot_webrtc_callback（回调集合）

【说明】

WebRTC 对讲事件回调集合：帧数据接收、解码渲染、状态变化、信令上报。

【定义】

typedef struct ot_webrtc_callback {
    void (*on_video_frame)(struct ot_webrtc_context *ctx, const td_u8 *data, td_u32 len,
                           td_u32 rtp_ts, td_bool is_key);
    void (*on_video_render)(struct ot_webrtc_context *ctx, const ot_webrtc_yuv_frame *frame);
    void (*on_audio_frame)(struct ot_webrtc_context *ctx, const td_u8 *data, td_u32 len,
                           td_u32 rtp_ts);
    void (*on_state)(struct ot_webrtc_context *ctx, ot_webrtc_state state);
    void (*on_signaling)(struct ot_webrtc_context *ctx, const td_char *type, const td_char *sdp);
    struct ot_webrtc_context *userdata;   /* 回调上下文，随每次回调原样回传 */
} ot_webrtc_callback;

【成员】

成员名称	描述
on_video_frame	接收视频数据（RTP 重组后的裸 NAL 单元，不含 Annex-B 起始码；按 NAL 粒度回调，一帧含 SPS/PPS/IDR 多个 NAL 时会多次回调）。
on_video_render	接收解码 YUV 帧（视频下行解码后回调；运行在解码线程，deinit 前 join，每解码一帧调用一次；frame 仅回调期间有效）。
on_audio_frame	接收音频帧（裸 OPUS，RFC 7587，一个 RTP 包一帧）。
on_state	连接状态变化（见 ot_webrtc_state）。
on_signaling	本地信令消息（SDP / ICE candidate），由调用方转发到信令服务器；内建信令模式下被内部接管，不再回调应用。
userdata	回调上下文，随每次回调原样回传。

【注意事项】

• 各回调指针可为空（不关心的事件不注册）；
• on_video_render 的 frame 指向解码器内部缓冲，仅回调期间有效，需保留须自行拷贝；
• 回调在对应工作线程（解码 / 网络）上下文中执行，回调内应避免长时间阻塞。

【相关数据类型及接口】

• 类型：ot_webrtc_yuv_frame、ot_webrtc_state
• 接口：hi_fw_webrtc_init、hi_fw_webrtc_init_with_signaling

4.3 ot_webrtc_yuv_frame（解码 YUV 帧）

【说明】

下行视频解码后的 YUV420 平面帧描述。

【定义】

typedef struct {
    td_u32 width;       /* 帧宽 */
    td_u32 height;      /* 帧高 */
    td_u32 stride_y;    /* Y 平面行跨度（stride_y × height 字节） */
    td_u32 stride_uv;   /* U/V 平面行跨度（stride_uv × height/2 字节） */
    const td_u8 *y;     /* Y 平面 */
    const td_u8 *u;     /* U 平面 */
    const td_u8 *v;     /* V 平面 */
    td_u32 frame_num;   /* 解码帧序号 */
} ot_webrtc_yuv_frame;

【成员】

成员名称	描述
width / height	帧宽高。
stride_y / stride_uv	Y / U / V 平面行跨度。
y / u / v	各平面数据指针，指向解码器内部缓冲。
frame_num	解码帧序号。

【注意事项】

• 仅 on_video_render 回调期间有效，需保留数据须自行拷贝。

【相关数据类型及接口】

• 回调：ot_webrtc_callback.on_video_render

4.4 ot_webrtc_state（连接状态枚举）

【说明】

WebRTC 连接状态。

【定义】

typedef enum {
    OT_WEBRTC_STATE_DISCONNECTED = 0,
    OT_WEBRTC_STATE_CONNECTING,
    OT_WEBRTC_STATE_CONNECTED,
    OT_WEBRTC_STATE_DISCONNECTING,
    OT_WEBRTC_STATE_BUTT
} ot_webrtc_state;

【成员】

成员名称	值	描述
OT_WEBRTC_STATE_DISCONNECTED	0	未连接。
OT_WEBRTC_STATE_CONNECTING	1	连接建立中。
OT_WEBRTC_STATE_CONNECTED	2	已连接。
OT_WEBRTC_STATE_DISCONNECTING	3	连接断开中。
OT_WEBRTC_STATE_BUTT	4	枚举结束标志（非法状态）。

【注意事项】

• 状态变化经 ot_webrtc_callback.on_state 回调上报。

【相关数据类型及接口】

• 回调：ot_webrtc_callback.on_state
• 接口：hi_fw_webrtc_is_connected

4.5 ot_webrtc_sdp_type（SDP 类型枚举）

【说明】

远端 SDP 类型，以整型语义传递（避免 api 头反向依赖底层枚举定义）。

【定义】

typedef enum {
    OT_WEBRTC_SDP_OFFER = 0,
    OT_WEBRTC_SDP_ANSWER,
    OT_WEBRTC_SDP_BUTT
} ot_webrtc_sdp_type;

【成员】

成员名称	值	描述
OT_WEBRTC_SDP_OFFER	0	Offer 类型。
OT_WEBRTC_SDP_ANSWER	1	Answer 类型。
OT_WEBRTC_SDP_BUTT	2	枚举结束标志（非法取值）。

【注意事项】

• hi_fw_webrtc_set_remote_sdp 的 type 参数仅接受 0 / 1，其他取值返回 -1。

【相关数据类型及接口】

• 接口：hi_fw_webrtc_set_remote_sdp

4.6 关键常量

常量	取值	说明
OT_WEBRTC_MAX_URL_LEN	256	信令 / STUN / TURN 地址字段长度上限。
OT_WEBRTC_MAX_NAME_LEN	64	房间名 / TURN 用户名 / 密码字段长度上限。
MSG_MAX_CONTENT_LEN	10 KB	light_msg 消息载荷上限（视频 / 音频大帧直接发送路径依据）。
WEBRTC_MAX_SEND_VIDEO_BYTES	16 MB	视频帧直接发送路径单帧长度上界。
WEBRTC_MAX_SEND_AUDIO_BYTES	4096 B	音频帧直接发送路径单帧长度上界。

---

5 错误码

本模块接口统一返回 0（TD_SUCCESS）表示成功，非 0 表示失败。失败时的返回值来源有三类：

5.1 API 层参数校验错误（TD_FAILURE）

API 层对入参做前置校验，不合法直接返回 -1（TD_FAILURE），不进入消息通道：

错误码	触发场景
-1（TD_FAILURE）	param / sdp / candidate / data / path 等指针为 NULL；帧长度越界；set_remote_sdp 的 type 非 0 / 1；SDP / candidate / 日志路径超长；init_with_signaling 参数缺失或重复初始化。

5.2 通信通道错误（LIGHT_MSG_E*）

直连模式下，消息经 light_msg 同步转发，通道自身错误码可能作为返回值透传，定义于 components/media/framework/api/direct/light_msg/light_msg.h：

错误码	值	描述
LIGHT_MSG_EFAIL	0x80000000	通用失败。
LIGHT_MSG_EINVALARG	0x80000003	参数非法（如消息载荷长度不匹配）。
LIGHT_MSG_EOUTOFMEM	0x80000004	内存分配失败。
LIGHT_MSG_EMSG_SYNC_MSG_TIMEOUT	0x80002005	同步消息超时。

5.3 底层错误码（ss_webrtc_*）

webrtc_impl 消息处理函数把 ss_webrtc_* 的返回值原样带回调用侧，底层错误码（如初始化失败、会话状态非法等）可能直接透传。本模块未定义自有错误码体系，底层错误码的具体数值由 ss_webrtc.cpp 内部定义；如需精确定位需结合服务端日志（HI_LOGE，模块名为 webrtc）。

说明：由于 TD_FAILURE（-1）与部分底层失败返回值数值相同，调用方应只依赖"0 = 成功、非 0 = 失败"的语义，不要依赖具体错误码数值。

---

6 使用注意事项

1. 句柄范围：本模块不涉及句柄入参。媒体通道（VENC / AENC / ADEC）由调用方通过媒体框架（hi_fw_media_*）建立并拥有，WebRTC 模块以 attach 模式经 hi_fw_media_venc_reg_cb / aenc_reg_cb / adec_send_stream 复用固定通道（VENC chn2 / AENC chn1 / ADEC chn0），不包含任何启动媒体通路 / MPP 直连逻辑。

2. 时序依赖：遵循以下启停顺序（停止为逆序）：

   direct_init                    // 模式初始化（内建信令版由 init_with_signaling 自动完成）
     → init(param, cb)            // 初始化会话（内建信令版为 init_with_signaling）
       → set_log(...)             // 日志配置（可选，尽早调用）
       → start()                  // 启动对讲（发起方自动创建 Offer）
       → [循环] send_video / send_audio / request_keyframe
       → [信令] create_offer / set_remote_sdp / add_candidate
   

   停止（逆序）：

stop()
  → deinit()
  → direct_deinit()

- 手动信令模式下，信令交互顺序：发起方 `create_offer`（发起方 `start` 内部已自动创建，通常无需再调）→ `on_signaling` 收到本地 offer → 转发对端 → 对端 `set_remote_sdp(sdp, 0)` 设置 offer（内部自动生成 answer 并经对端 `on_signaling` 回发，**无需也不应**调用 `create_offer`）→ 发起方 `set_remote_sdp(sdp, 1)` 设置 answer → 双方 `add_candidate` 交换 ICE。

1. 资源配对：

   • hi_fw_webrtc_direct_init() / hi_fw_webrtc_direct_deinit() 成对调用；
   • hi_fw_webrtc_init() / hi_fw_webrtc_deinit()、hi_fw_webrtc_start() / hi_fw_webrtc_stop() 成对调用；
   • hi_fw_webrtc_init_with_signaling() / hi_fw_webrtc_deinit_with_signaling() 成对使用（内部自动管理 direct_init / init / start 的资源，一次性释放）。

2. 数据发送约束：

   • 视频帧为 H.264 Annex-B 裸流、音频帧为裸 OPUS（RFC 7587）；编码格式由本模块固定（H.264 / OPUS），不随对端变化；
   • 视频帧 ≤ 1024 字节走消息通道、更大帧直接调底层；音频帧 ≤ 1024 字节走消息通道、更大帧直接调底层（视频上限 16 MB、音频上限 4096 字节）；
   • 发送前建议确认会话已连接（hi_fw_webrtc_is_connected），未连接时发送失败。

3. 模式差异：本模块仅支持直连模式（Direct），不提供跨进程（IPC）实现。init_with_signaling 为直连模式内建信令的简化封装，与手动信令 init 二选一，不可混用。

4. 回调线程：on_video_render 在解码线程、其余回调在网络 / 信令工作线程上下文中执行，回调内应避免长时间阻塞或调用可能导致死锁的接口。

5. 安全约定：ot_webrtc_init_param.turn_pass 为明文口令，调用方在 hi_fw_webrtc_init() 返回后应清零本结构体副本，避免口令明文滞留内存。

---

7 附注 / 关联文档

• 直连实现：components/media/framework/api/direct/webrtc/api_webrtc.c、webrtc_impl.c
• 内建信令实现：components/media/framework/api/direct/webrtc/webrtc_signaling.cpp、signaling_client.cpp / signaling_client.h
• 消息定义：components/media/framework/api/direct/webrtc/webrtc_msg_def.h
• 组件适配层：components/media/framework/component_adapter/webrtc/（ss_webrtc.h / ss_webrtc.cpp）
• 消息通道：components/media/framework/api/direct/light_msg/light_msg.h / light_msg.c
• 关联接口：媒体框架 hi_fw_media_*（VENC / AENC 通道，见 api_media.md）