直播服务接口说明文档

文档版本	V1.0
修订日期	2026-08-20
对应头文件	components/media/framework/api/include/api_liveserver.h
类型定义	components/media/framework/api/include/api_liveserver.h、components/media/framework/component_adapter/liveserver/include/ss_liveserver.h
适用模块	直播服务（LiveServer / LIVESVR）

---

1 概述

直播服务对外提供 hi_fw_livesvr_* 系列接口，将媒体框架已初始化的音视频编码通道（VENC / AENC）封装为 RTSP 直播流，对外提供基于标准 RTSP 协议的拉流服务（默认监听 554 端口，播放地址形如 rtsp://<ip>:554/livestream/<stream_name>）。框架屏蔽了底层 RTSP 服务（ss_rtsp_server）、事件总线（eventhub）与消息通道细节，并支持两种运行模式：

• 直连模式（Direct）：应用与直播服务同进程，通过 hi_fw_livesvr_direct_init() 启动。
• 跨进程模式（IPC / Client）：应用与直播服务分进程，通过 hi_fw_livesvr_client_init() 建立客户端。

客户端接入 / 断开、服务端异常等事件通过 hi_fw_livesvr_set_event_callback() 注册的回调上报，无需应用轮询。

模型层次：

直播服务（LiveServer）
  ├─ RTSP 服务（监听 554 端口，最大连接数 1~2）
  └─ 直播流（Stream）
       ├─ 视频轨（VENC 编码通道）
       └─ 音频轨（AENC 编码通道）

---

2 接口总览

编号	接口	模块	功能概述
1	hi_fw_livesvr_direct_init	模式管理	初始化直连模式直播服务
2	hi_fw_livesvr_direct_deinit	模式管理	去初始化直连模式直播服务
3	hi_fw_livesvr_client_init	模式管理	初始化跨进程模式直播客户端
4	hi_fw_livesvr_client_deinit	模式管理	去初始化跨进程模式直播客户端
5	hi_fw_livesvr_init	直播服务	初始化 RTSP 直播服务
6	hi_fw_livesvr_deinit	直播服务	去初始化 RTSP 直播服务
7	hi_fw_livesvr_add_stream	直播流	添加一路直播流
8	hi_fw_livesvr_remove_stream	直播流	移除一路直播流
9	hi_fw_livesvr_remove_all_stream	直播流	移除所有直播流
10	hi_fw_livesvr_register_event	事件	注册直播事件到事件总线
11	hi_fw_livesvr_unregister_event	事件	从事件总线注销直播事件
12	hi_fw_livesvr_set_event_callback	事件	设置事件上报回调

---

3 API 参考

3.1 hi_fw_livesvr_direct_init

【描述】

初始化直连模式直播服务，创建直播服务实现（liveserver_impl）与 light_msg 消息通道。仅在直连模式下调用。

【语法】

td_s32 hi_fw_livesvr_direct_init(td_void);

【参数】

无。

【返回值】

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

【注意】

• 仅在直连模式下调用；跨进程模式应调用 hi_fw_livesvr_client_init()。
• 需在 hi_fw_livesvr_init() 之前调用。
• 与 hi_fw_livesvr_direct_deinit() 成对调用，不具幂等性，重复调用需先执行 direct_deinit。

【举例】

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

3.2 hi_fw_livesvr_direct_deinit

【描述】

去初始化直连模式直播服务，销毁消息通道与直播服务实现。

【语法】

td_void hi_fw_livesvr_direct_deinit(td_void);

【参数】

无。

【返回值】

无。

【注意】

• 与 hi_fw_livesvr_direct_init() 成对调用；
• 调用前应先 hi_fw_livesvr_deinit()，否则直播服务资源由该函数一并清理。

【举例】

hi_fw_livesvr_direct_deinit();

3.3 hi_fw_livesvr_client_init

【描述】

初始化跨进程模式直播客户端，建立应用进程到直播服务进程的 channel 通道，并注册事件接收回调。仅在跨进程模式下调用。

【语法】

td_s32 hi_fw_livesvr_client_init(const td_char *endpoint);

【参数】

参数名称	输入/输出	类型	描述
endpoint	输入	const td_char *	端点地址（服务端 channel 端点标识）。为 NULL 或空串时使用默认端点 /tmp/ipc_livesvr_test.sock。

【返回值】

返回值	描述
0	初始化成功。
-1	初始化失败（TD_FAILURE）。

【注意】

• 仅在跨进程（IPC）模式下调用；直连模式应调用 hi_fw_livesvr_direct_init()。
• 重复调用（已初始化状态）返回成功，不重复创建通道。
• endpoint 需与服务进程端 liveserver 服务监听端点保持一致。

【举例】

td_s32 ret = hi_fw_livesvr_client_init("/tmp/ipc_livesvr_test.sock");
if (ret != 0) {
    /* 处理失败 */
}

3.4 hi_fw_livesvr_client_deinit

【描述】

去初始化跨进程模式直播客户端，注销事件回调 handler 并销毁 channel 通道。

【语法】

td_s32 hi_fw_livesvr_client_deinit(td_void);

【参数】

无。

【返回值】

返回值	描述
0	去初始化成功。
-1	去初始化失败（TD_FAILURE）。

【注意】

• 与 hi_fw_livesvr_client_init() 成对调用；
• 未初始化状态下调用返回成功（幂等）。

【举例】

hi_fw_livesvr_client_deinit();

3.5 hi_fw_livesvr_init

【描述】

初始化 RTSP 直播服务：创建并启动 RTSP 服务（默认监听 554 端口），绑定底层媒体操作回调（VENC / AENC 的查询与启停）。仅在已完成模式初始化（direct_init / client_init）后可调用。

【语法】

td_s32 hi_fw_livesvr_init(td_s32 max_conn_num);

【参数】

参数名称	输入/输出	类型	描述
max_conn_num	输入	td_s32	最大并发连接数，取值范围 [1, 2]。

【返回值】

返回值	描述
0	初始化成功。
非0	初始化失败。直连模式下具体错误码见 5.1；跨进程模式下统一为 -1（TD_FAILURE）。

【注意】

• max_conn_num 超出 [1, 2] 范围返回 OT_LIVESVR_EINVAL（直连模式）；
• 重复初始化（已初始化状态）返回 OT_LIVESVR_EINITIALIZED（直连模式）；
• 需先调用 hi_fw_livesvr_direct_init() 或 hi_fw_livesvr_client_init()；
• 直播拉流地址：rtsp://<设备IP>:554/livestream/<stream_name>。

【举例】

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

3.6 hi_fw_livesvr_deinit

【描述】

去初始化 RTSP 直播服务：停止 RTSP 服务、移除所有已添加的直播流。

【语法】

td_s32 hi_fw_livesvr_deinit(td_void);

【参数】

无。

【返回值】

返回值	描述
0	去初始化成功。
非0	去初始化失败。直连模式下具体错误码见 5.1；跨进程模式下统一为 -1。

【注意】

• 未初始化状态下调用返回 OT_LIVESVR_ENOINIT（直连模式）；
• 与 hi_fw_livesvr_init() 成对调用。

【举例】

hi_fw_livesvr_deinit();

3.7 hi_fw_livesvr_add_stream

【描述】

添加一路直播流，将指定的视频编码通道（VENC）和 / 或音频编码通道（AENC）绑定到该流。添加成功后客户端可通过 rtsp://<设备IP>:554/livestream/<stream_name> 拉取。

【语法】

td_s32 hi_fw_livesvr_add_stream(td_handle venc_hdl, td_handle aenc_hdl, const td_char *stream_name);

【参数】

参数名称	输入/输出	类型	描述
venc_hdl	输入	td_handle	视频编码通道句柄。不携带视频轨时传 OT_INVALID_HANDLE。
aenc_hdl	输入	td_handle	音频编码通道句柄。不携带音频轨时传 OT_INVALID_HANDLE。
stream_name	输入	const td_char *	流名称，非空、不能为 NULL。跨进程模式下最长 63 个字符（超出截断）；用于生成 RTSP 播放路径 livestream/<stream_name>。

【返回值】

返回值	描述
0	添加成功。
非0	添加失败。直连模式下具体错误码见 5.1；跨进程模式下统一为 -1。

【注意】

• venc_hdl 与 aenc_hdl 至少有一个有效（非 OT_INVALID_HANDLE），否则返回 OT_LIVESVR_EINVAL；
• stream_name 为 NULL 或空串返回 OT_LIVESVR_EINVAL；
• 流名称不能重复，重名返回 OT_LIVESVR_EEXIST；
• 最大支持 4 路直播流，超出返回 OT_LIVESVR_EMAXSOURCE；
• 未初始化直播服务时返回 OT_LIVESVR_ENOINIT；
• 各通道的编码启动 / 停止由 RTSP 会话发起与释放时自动触发（内部绑定 ss_media_start_venc / ss_media_stop_venc 等回调），应用无需手动启停。

【举例】

td_s32 ret = hi_fw_livesvr_add_stream(venc_hdl, aenc_hdl, "main");
if (ret != 0) {
    /* 处理失败 */
}

3.8 hi_fw_livesvr_remove_stream

【描述】

按名称移除一路直播流，并停止该流绑定的编码通道。

【语法】

td_s32 hi_fw_livesvr_remove_stream(const td_char *stream_name);

【参数】

参数名称	输入/输出	类型	描述
stream_name	输入	const td_char *	待移除的流名称，需与 hi_fw_livesvr_add_stream 传入的名称一致。

【返回值】

返回值	描述
0	移除成功。
非0	移除失败。直连模式下具体错误码见 5.1；跨进程模式下统一为 -1。

【注意】

• 未找到对应名称的流返回 OT_LIVESVR_ELOST；
• stream_name 为 NULL 或空串返回 OT_LIVESVR_EINVAL。

【举例】

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

3.9 hi_fw_livesvr_remove_all_stream

【描述】

移除所有已添加的直播流，并停止各流绑定的编码通道。

【语法】

td_s32 hi_fw_livesvr_remove_all_stream(td_void);

【参数】

无。

【返回值】

返回值	描述
0	移除成功。
非0	移除失败。直连模式下具体错误码见 5.1；跨进程模式下统一为 -1。

【注意】

• 未初始化直播服务时返回 OT_LIVESVR_ENOINIT；
• hi_fw_livesvr_deinit() 内部会先调用本接口，故无需单独调用。

【举例】

hi_fw_livesvr_remove_all_stream();

3.10 hi_fw_livesvr_register_event

【描述】

将直播事件（客户端连接、断开、服务端错误）注册到事件总线。注册后，对应事件发生时才会发布到事件总线并最终上报给应用回调。需与 hi_fw_livesvr_set_event_callback() 配合使用。

【语法】

td_s32 hi_fw_livesvr_register_event(td_void);

【参数】

无。

【返回值】

返回值	描述
0	注册成功。
非0	注册失败。直连模式下具体错误码见 5.1；跨进程模式下统一为 -1。

【注意】

• 建议在 hi_fw_livesvr_init() 之后、hi_fw_livesvr_set_event_callback() 之前调用；
• 与 hi_fw_livesvr_unregister_event() 成对调用。

【举例】

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

3.11 hi_fw_livesvr_unregister_event

【描述】

将直播事件从事件总线注销，停止事件发布。

【语法】

td_s32 hi_fw_livesvr_unregister_event(td_void);

【参数】

无。

【返回值】

返回值	描述
0	注销成功。
非0	注销失败。直连模式下具体错误码见 5.1；跨进程模式下统一为 -1。

【注意】

• 与 hi_fw_livesvr_register_event() 成对调用。

【举例】

hi_fw_livesvr_unregister_event();

3.12 hi_fw_livesvr_set_event_callback

【描述】

设置直播事件上报回调。设置后，客户端连接 / 断开、服务端错误等事件通过回调上报；传入 NULL 可清除回调。

【语法】

td_s32 hi_fw_livesvr_set_event_callback(hi_fw_livesvr_event_cb cb, td_void *arg);

【参数】

参数名称	输入/输出	类型	描述
cb	输入	hi_fw_livesvr_event_cb	事件回调函数指针。为 NULL 时清除已注册回调。
arg	输入	td_void *	用户上下文，回调时原样透传。可为 NULL。

【返回值】

返回值	描述
0	设置成功。
非0	设置失败（直连模式为事件订阅错误码，跨进程模式统一为 -1）。

【注意】

• cb 为 NULL 时清除回调并返回成功（直连模式下同时销毁内部事件订阅）；
• 跨进程模式下，本接口会同步通知服务端启动 / 停止事件推送；
• 回调在事件发布线程上下文中执行，回调内应避免长时间阻塞。

【举例】

static td_void my_livesvr_event_cb(td_u32 event_id, td_s32 result,
    const td_char *payload, td_void *arg)
{
    (void)arg;
    if (event_id == OT_EVENT_LIVESRV_CLIENT_CONNECT) {
        printf("client connect, ip=%s\n", payload);
    } else if (event_id == OT_EVENT_LIVESRV_SERVER_ERROR) {
        printf("server error, id=%d, msg=%s\n", result, payload);
    }
}

td_s32 ret = hi_fw_livesvr_set_event_callback(my_livesvr_event_cb, NULL);
if (ret != 0) {
    /* 处理失败 */
}

---

4 数据类型

4.1 OT_LIVESVR_Event（直播事件枚举）

【说明】

定义直播服务上报给应用回调的事件类型。

【定义】

typedef enum {
    OT_EVENT_LIVESRV_CLIENT_CONNECT = 0x1234,
    OT_EVENT_LIVESRV_CLIENT_DISCONNECT,
    OT_EVENT_LIVESRV_SERVER_ERROR,
    OT_EVENT_LIVESRV_BUTT,
} OT_LIVESVR_Event;

【成员】

成员名称	值	描述
OT_EVENT_LIVESRV_CLIENT_CONNECT	0x1234	RTSP 客户端连接成功。
OT_EVENT_LIVESRV_CLIENT_DISCONNECT	0x1235	RTSP 客户端断开。
OT_EVENT_LIVESRV_SERVER_ERROR	0x1236	直播服务内部错误。
OT_EVENT_LIVESRV_BUTT	0x1237	枚举结束标志（非法事件，仅作范围校验用）。

【注意事项】

• 事件枚举定义于 api_liveserver.h 与 ss_liveserver.h（两处定义一致）；
• 回调的 payload 参数：连接 / 断开事件携带客户端 IP 字符串，服务器错误事件携带错误消息字符串；result 参数仅服务器错误事件有效（携带错误 ID）。

【相关数据类型及接口】

• 回调类型：hi_fw_livesvr_event_cb
• 接口：hi_fw_livesvr_set_event_callback、hi_fw_livesvr_register_event、hi_fw_livesvr_unregister_event

4.2 hi_fw_livesvr_event_cb（事件回调类型）

【说明】

直播事件上报回调函数类型。

【定义】

typedef td_void (*hi_fw_livesvr_event_cb)(td_u32 event_id, td_s32 result,
    const td_char *payload, td_void *arg);

【成员】

参数名称	描述
event_id	事件 ID，取值见 OT_LIVESVR_Event。
result	附加结果码，仅服务器错误事件有效（携带错误 ID）。
payload	事件负载：连接 / 断开事件为客户端 IP 字符串；服务器错误事件为错误消息字符串。
arg	注册回调时传入的用户上下文。

【注意事项】

• 回调由事件发布线程触发，执行期间不应阻塞或调用可能引发死锁的接口。

【相关数据类型及接口】

• 枚举：OT_LIVESVR_Event
• 接口：hi_fw_livesvr_set_event_callback

---

5 错误码

本模块接口统一返回 0（TD_SUCCESS）表示成功，非 0 表示失败。失败时的返回值可能来自以下三类错误。

5.1 框架层错误（OT_LIVESVR_E*）

直播服务在 component_adapter 层（ss_liveserver.c）使用一组自有错误码，定义于 components/media/framework/component_adapter/liveserver/include/ss_liveserver.h：

#define OT_LIVESVR_EINVAL       (-1)
#define OT_LIVESVR_ENOINIT      (-2)
#define OT_LIVESVR_EINITIALIZED (-3)
#define OT_LIVESVR_EEXIST       (-4)
#define OT_LIVESVR_ELOST        (-5)
#define OT_LIVESVR_EMAXSOURCE   (-6)

错误码	值	描述
OT_LIVESVR_EINVAL	-1	输入参数非法（max_conn_num 越界、空指针、流名称为空、音视频句柄均无效等）。
OT_LIVESVR_ENOINIT	-2	直播服务未初始化即调用。
OT_LIVESVR_EINITIALIZED	-3	重复初始化。
OT_LIVESVR_EEXIST	-4	流名称已存在。
OT_LIVESVR_ELOST	-5	未找到指定名称的流。
OT_LIVESVR_EMAXSOURCE	-6	直播流数量超过上限（4 路）。

透传说明：与 OT_MEDIA_E* 类似，OT_LIVESVR_E* 为框架内部错误码，是否到达 hi_fw_livesvr_xxx 接口取决于运行模式：

• 直连模式（Direct）：liveserver_impl 消息处理函数把 ss_livesvr_* 的返回值通过 light_msg 的 ret_val 原样带回调用侧，OT_LIVESVR_E* 会透传出来；
• 跨进程模式（IPC / Client）：客户端 api_livesvr_client_finish_call() 把远端返回的任何非 0 值统一映射为 TD_FAILURE（-1），OT_LIVESVR_E* 不会透传到客户端接口，调用方只能看到成功（0）或失败（-1）；
• 注意 OT_LIVESVR_EINVAL 与 TD_FAILURE 数值相同（均为 -1），即便在直连模式下透传，也无法从返回值数值上区分二者。

5.2 底层错误码

直连模式下，ss_livesvr_* 内部调用底层 RTSP 服务（ss_rtsp_server）、媒体操作回调（ss_media_*）与事件总线（eventhub）时，相关返回值可能作为错误码直接透传（如 RTSP 创建 / 添加流失败返回 TD_FAILURE、事件总线注册失败返回 eventhub 错误码）。如需精确定位需结合服务端日志（HI_LOGE，模块名为 LiveSvr）。

5.3 通信 / 通道错误

• 直连模式（Direct）：light_msg 自身错误码可能作为返回值出现（如消息超时 LIGHT_MSG_EMSG_SYNC_MSG_TIMEOUT = 0x80002005、参数非法 LIGHT_MSG_EINVALARG = 0x80000003 等），数值远大于 -6，可据此与框架层错误区分。
• 跨进程模式（IPC / Client）：channel_client 通信失败统一返回 TD_FAILURE（-1）。

说明：跨进程模式下所有失败统一收敛为 TD_FAILURE（-1），无法从返回值区分具体错误类型，如需定位具体原因需结合服务端日志（HI_LOGE）。

---

6 使用注意事项

1. 句柄范围：venc_hdl、aenc_hdl 由媒体框架初始化流程创建，应用只使用、不自行构造；无效 / 不需要的轨传 OT_INVALID_HANDLE。内部通过媒体操作回调（ss_media_get_venc_attr、ss_media_start_venc 等）获取编码属性并按需启停。

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

   direct_init / client_init        // 模式初始化
     → livesvr_init(max_conn_num)   // 启动 RTSP 服务（端口 554）
       → register_event             // 注册事件（可选，需事件上报时）
       → set_event_callback         // 设置事件回调（可选）
       → add_stream(...)            // 添加直播流（可多路，最多 4 路）
   

   停止（逆序）：

remove_stream / remove_all_stream
  → unregister_event
  → livesvr_deinit
  → direct_deinit / client_deinit

1. 资源配对：

   • hi_fw_livesvr_direct_init() / hi_fw_livesvr_direct_deinit() 成对调用（直连模式）；
   • hi_fw_livesvr_client_init() / hi_fw_livesvr_client_deinit() 成对调用（跨进程模式）；
   • hi_fw_livesvr_init() / hi_fw_livesvr_deinit()、hi_fw_livesvr_register_event() / hi_fw_livesvr_unregister_event() 成对调用。

2. 流名称约束：stream_name 非空、长度不超过 63 个字符；命名区分大小写，全局唯一（重名返回 OT_LIVESVR_EEXIST）。直播播放地址为 rtsp://<设备IP>:554/livestream/<stream_name>。

3. 容量与连接约束：

   • 最大并发连接数 max_conn_num 范围 [1, 2]；
   • 最大直播流数 4 路（LIVE_SERVER_RTSP_MAX_STREAM_CNT）；
   • RTSP 会话超时时间配置为 6 秒（LIVE_SERVER_RTSP_TIMEOUT_SEC）。

4. 模式差异：

   • 直连模式（Direct）：调用 hi_fw_livesvr_direct_init()，同进程消息转发，事件回调直接由事件总线同步派发；
   • 跨进程模式（IPC）：调用 hi_fw_livesvr_client_init(endpoint)，经 channel 通道转发，服务端通过异步消息推送事件，客户端 handler 分发到回调，行为与直连模式保持一致；所有错误统一收敛为 TD_FAILURE。

5. 回调线程：事件回调在事件发布线程上下文中执行，回调内应避免长时间阻塞或调用可能导致死锁的接口。

---

7 附注 / 关联文档

• 直连实现：components/media/framework/api/direct/liveserver/api_liveserver.c、liveserver_impl.c
• 跨进程客户端：components/media/framework/api/client/liveserver/api_liveserver.c
• 跨进程桥接：components/media/framework/api/ipc_bridge/liveserver/
• 组件适配层：components/media/framework/component_adapter/liveserver/
• 底层 RTSP 服务：components/media/framework/component_adapter/liveserver/src/ss_rtsp_server.c（ss_liveserver.c 依赖）
• 事件总线：components/media/framework/api/direct/liveserver/eventhub.h 对应实现
• 关联接口：媒体框架 hi_fw_media_*（VENC / AENC 初始化，见 api_media.md）