跳转至
项目
版本
全文检索

ot_autorate 码率自适应

1 模块概述

ot_autorate 是 network 组件中的码率自适应模块，通过协同模组的预估速率，动态调整编码码率以及编码参数，达成流畅点播的目标。

  • 目标平台：Hi3516CV610 + Hi2131（4G Cat1）
  • 编码格式：H.265 AVBR / H.265 CBR
  • 产物形式：静态库 libautorate.a
  • Kconfig 选项：COMP_NETWORK_OT_AUTORATE
  • 依赖：海思 SDK（ss_mpi_venc.h、ss_mpi_sys.h）、securec、pthread

2 接口总览

编号 接口 模块 功能概述
1 ot_autorate_init 初始化 初始化码率自适应模块。
2 ot_autorate_deinit 初始化 去初始化码率自适应模块。
3 ot_autorate_set_attr 属性管理 设置码率自适应属性。
4 ot_autorate_get_attr 属性管理 获取码率自适应属性。
5 ot_autorate_add_venc_chn 通道管理 向码率自适应增加一个编码通道。
6 ot_autorate_remove_venc_chn 通道管理 从码率自适应移除一个编码通道。
7 ot_autorate_query_venc_chn 通道管理 查询码率自适应中的编码通道。
8 ot_autorate_notify_on_stream 码流通知 获取到码流时通知到码率自适应模块。
9 ot_autorate_set_log_file 调试日志 开启或关闭码率自适应调试日志保存。

3 API 接口参考

码率自适应模块提供以下API：

  • ot_autorate_init：初始化码率自适应模块。
  • ot_autorate_deinit：去初始化码率自适应模块。
  • ot_autorate_set_attr：设置码率自适应属性。
  • ot_autorate_get_attr：获取码率自适应属性。
  • ot_autorate_add_venc_chn：向码率自适应增加一个编码通道。
  • ot_autorate_remove_venc_chn：从码率自适应移除一个编码通道。
  • ot_autorate_query_venc_chn：查询码率自适应中的编码通道。
  • ot_autorate_notify_on_stream：获取到码流时通知到码率自适应模块。
  • ot_autorate_set_log_file：开启或关闭码率自适应调试日志保存。

3.1 ot_autorate_init

【描述】

初始化码率自适应模块。

【语法】

td_s32 ot_autorate_init(const ot_autorate_attr *attr, const ot_autorate_call_back *callback);

【参数】

参数名 描述 输入/输出
attr 码率自适应属性，参考 ot_autorate_attr 。 输入
callback 码率自适应回调函数，参考 ot_autorate_call_back 。 输入

【返回值】

返回值 描述
0 成功。
非 0 失败，其值为错误码。

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 系统启动或去初始化后调用，重复初始化返回成功。

【举例】

无

【相关主题】

无

3.2 ot_autorate_deinit

【描述】

去初始化码率自适应模块。

【语法】

td_s32 ot_autorate_deinit(td_void);

【参数】

无

【返回值】

返回值 描述
0 成功。
非 0 失败，其值为错误码。

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 初始化后调用，重复去初始化返回成功。
  • 确保所有编码通道都已移除再去初始化码率自适应，否则去初始化失败。

【举例】

无

【相关主题】

无

3.3 ot_autorate_set_attr

【描述】

设置码率自适应属性。

【语法】

td_s32 ot_autorate_set_attr(const ot_autorate_attr *attr);

【参数】

参数名 描述 输入/输出
attr 码率自适应属性，参考 ot_autorate_attr 。 输入

【返回值】

返回值 描述
0 成功。
非 0 失败，其值为错误码。

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 初始化后调用，否则设置不成功。
  • 支持运行过程中，动态设置码率自适应属性。

【举例】

无

【相关主题】

无

3.4 ot_autorate_get_attr

【描述】

获取码率自适应属性。

【语法】

td_s32 ot_autorate_get_attr(ot_autorate_attr *attr);

【参数】

参数名 描述 输入/输出
attr 码率自适应属性，参考 ot_autorate_attr 。 输出

【返回值】

返回值 描述
0 成功。
非 0 失败，其值为错误码。

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 初始化后调用，否则获取属性失败。
  • 支持运行过程中，动态获取码率自适应属性。

【举例】

无

【相关主题】

无

3.5 ot_autorate_add_venc_chn

【描述】

向码率自适应增加一个编码通道。

【语法】

td_s32 ot_autorate_add_venc_chn(td_s32 venc_hdl);

【参数】

参数名 描述 输入/输出
venc_hdl 编码通道号。取值范围：[0, OT_VENC_MAX_CHN_NUM]。 输入

【返回值】

返回值 描述
0 成功。
非 0 失败，其值为错误码。

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 调用此接口向码率自适应增加一个编码通道，建议在点播该编码通道时调用。
  • 多个用户点播同一个编码通道时，需要重复调用此接口增加系统的编码通道。
  • 最多支持向码率自适应增加4个不同的编码通道。

【举例】

无

【相关主题】

无

3.6 ot_autorate_remove_venc_chn

【描述】

从码率自适应移除一个编码通道。

【语法】

td_s32 ot_autorate_remove_venc_chn(td_s32 venc_hdl);

【参数】

参数名 描述 输入/输出
venc_hdl 编码通道号。取值范围：[0, OT_VENC_MAX_CHN_NUM]。 输入

【返回值】

返回值 描述
0 成功。
非 0 失败，其值为错误码。

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 调用此接口从码率自适应移除一个编码通道，建议在退出点播该编码通道时调用。
  • 多个用户点播同一个编码通道时，要与ot_autorate_add_venc_chn 接口对称调用。
  • 所有编码通道都移除后，码率自适应自动停止工作。
  • 修改编码通道的分辨率时，通道销毁前调用此接口，通道创建后调用ot_autorate_add_venc_chn 接口。

【举例】

无

【相关主题】

无

3.7 ot_autorate_query_venc_chn

【描述】

查询码率自适应中的编码通道。

【语法】

td_s32 ot_autorate_query_venc_chn(ot_autorate_venc_chn *venc_chn);

【参数】

参数名 描述 输入/输出
venc_chn 编码通道属性，参考 ot_autorate_venc_chn 。 输出

【返回值】

返回值 描述
0 成功。
非 0 失败，其值为错误码。

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 去初始化前需要移除所有编码通道或者需要停止码率自适应工作时，可调用此接口查询配置到码率自适应中的编码通道，并做移除操作。
  • 点播流程异常导致实际点播的编码通道状态与码率自适应不同步时，可先调用此接口查询，再调用ot_autorate_add_venc_chn或ot_autorate_remove_venc_chn 接口进行同步。

【举例】

无

【相关主题】

无

3.8 ot_autorate_notify_on_stream

【描述】

获取到码流时通知到码率自适应模块。

【语法】

td_void ot_autorate_notify_on_stream(ot_venc_chn chn, const ot_autorate_stream *stream);

【参数】

参数名 描述 输入/输出
chn 编码通道号。取值范围：[0, OT_VENC_MAX_CHN_NUM]。 输入
stream 码流结构体，参考 ot_autorate_stream 。 输入

【返回值】

无

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 未在码率自适应中的编码通道调用此接口，不产生作用。
  • 建议在获取码流时调用此接口。

【举例】

无

【相关主题】

无

3.9 ot_autorate_set_log_file

【描述】

设置调试日志的开关和路径。

【语法】

td_s32 ot_autorate_set_log_file(td_bool enable, const td_char *file_path);

【参数】

参数名 描述 输入/输出
enable 调试日志的开关。取值范围：[0,1]。 输入
file_path 调试日志的保存路径。 输入

【返回值】

返回值 描述
0 成功。
非 0 失败，其值为错误码。

【需求】

  • 头文件：ot_autorate.h
  • 库文件：libautorate.a

【注意】

  • 初始化后可调用此接口设置调试日志的开关和路径，默认关闭。
  • enable 为1时，file_path 要传入有效的目录路径。

【举例】

无

【相关主题】

无

4 数据类型

码率自适应模块相关数据类型定义如下：

  • ot_autorate_attr：定义码率自适应模块属性结构体。
  • ot_autorate_event：定义码率自适应上报的事件类型。
  • ot_autorate_event_para：定义码率自适应上报的事件参数。
  • ot_autorate_call_back：定义码率自适应回调函数。
  • ot_autorate_venc_chn：定义码率自适应的编码通道配置。
  • ot_autorate_table：定义码率自适应用户自定义调整表。
  • ot_autorate_stream：定义码率自适应码流信息。

4.1 ot_autorate_attr

【说明】

定义码率自适应模块属性结构体。

【定义】

typedef struct  {
    td_u32 run_period;
    td_u32 default_video_rate;
    td_u32 max_video_rate;
    td_u32 min_video_rate;
    td_u32 step_rate;
    td_u32 adjust_dir;
} ot_autorate_attr;

【成员】

成员名 描述
run_period 码率自适应运行周期，值越小调整越快。取值范围：[300,2000]，单位：ms。建议取值：500
default_video_rate 非运动场景下期望达到的码率上限。取值范围：[20,5000]，单位：kbps。建议取值：
max_video_rate 最大视频编码码率。取值范围：[20,5000]，单位：kbps。建议取值：
min_video_rate 最小视频编码码率。取值范围：[20,max_video_rate]，单位：kbps。建议取值：
step_rate 单次调整的视频码率。取值范围：[10,1000]，单位：kbps。建议取值：64 或 100
adjust_dir 码率自适应调整的方向，值越小越偏向流畅优先，值越大越偏向画质优先。取值范围：[0,8]。建议取值：4

【注意事项】

无

【相关数据类型及接口】

  • ot_autorate_init
  • ot_autorate_set_attr
  • ot_autorate_get_attr

4.2 ot_autorate_event

【说明】

定义码率自适应上报的事件类型。

【定义】

typedef enum  {
    OT_EVENT_UP,
    OT_EVENT_DOWN,
    OT_EVENT_HQ_NET,
    OT_EVENT_BQ_NET,
    OT_EVENT_HQ_VIDEO,
} ot_autorate_event;

【成员】

成员名 描述
OT_EVENT_UP 网络质量好转，参考建议目标码率调整。
OT_EVENT_DOWN 网络质量变差，参考建议目标码率调整。
OT_EVENT_HQ_NET 网络质量优，已调到最大码率，空口仍无压力。
OT_EVENT_BQ_NET 网络质量差，已调到最小码率，空口仍有压力，如有需要可降帧、降分辨率等。
OT_EVENT_HQ_VIDEO 瞬时码率超过空口速率。

【注意事项】

  • 对于OT_EVENT_UP和OT_EVENT_DOWN事件，结合ot_autorate_event_para中的目标码率进行调整。
  • 如果在OT_EVENT_BQ_NET事件中做了降帧，可以在OT_EVENT_UP事件中回调码率的同时回调帧率。

【相关数据类型及接口】

无

4.3 ot_autorate_event_para

【说明】

定义码率自适应上报的事件参数结构体。

【定义】

typedef struct  {
    td_u32 target_rate;
    td_u32 venc_count;
    td_s32 venc_hdl[OT_AUTORATE_VENC_MAX_CHN_NUM];
} ot_autorate_event_para;

【成员】

成员名 描述
target_rate 码率自适应输出的目标码率。
venc_count 添加到码率自适应中的编码通道数量。
venc_hdl 添加到码率自适应中的编码通道号数组。

【注意事项】

  • 结合ot_autorate_event的类型使用该接口参数。
  • 目标码率是各通道的目标码率之和，用户可以自行分配到各编码通道。
  • venc_count和venc_hdl是已经配置到码率自适应的编码通道数和编码通道号，用户可以在回调函数中使用该参数进行码率配置。

【相关数据类型及接口】

无

4.4 ot_autorate_call_back

【说明】

定义码率自适应回调函数。

【定义】

typedef struct  {
    td_s32 (*ot_autorate_get_modem_info)(char *buf, td_u32 buf_len);
    td_s32 (*ot_autorate_get_modem_curr_rate)(char *buf, td_u32 buf_len);
    td_void (*ot_autorate_event_report)(ot_autorate_event ot_event, ot_autorate_event_para *para);
    td_void (*ot_autorate_get_user_table)(td_u32 curr_rate, td_u32 buff_used, ot_autorate_table *table);
} ot_autorate_call_back;

【成员】

成员名 描述
ot_autorate_get_modem_info 获取4G模组空口预估速率的回调函数。
ot_autorate_get_modem_curr_rate 获取4G模组空口实时速率的回调函数。
ot_autorate_event_report 码率自适应事件上报的回调函数。
ot_autorate_get_user_table 获取用户自定义码率调整表的回调函数。

【注意事项】

  • ot_autorate_get_modem_info回调函数，需要用户实现：向Hi2131发送AT+NULTHP?命令，并将AT返回的响应接收到回调函数的参数buf中。
  • ot_autorate_get_modem_curr_rate回调函数，需要用户实现：向Hi2131发送AT+NUESTATS=THP命令，并将AT返回的响应接收到回调函数的参数buf中。
  • ot_autorate_event_report回调函数中，用户需要配置做响应的调节，参考ot_autorate_event 和ot_autorate_event_para。
  • ot_autorate_get_user_table回调函数中，用户根据当前码率和缓冲区使用率，设置自定义的调整步长和判定级别，参考ot_autorate_table。

【相关数据类型及接口】

无

4.5 ot_autorate_venc_chn

【说明】

定义码率自适应上的编码通道配置。

【定义】

typedef struct {
    td_u32 count;
    td_s32 venc_hdl[OT_AUTORATE_VENC_MAX_CHN_NUM];
    td_u32 ref_count[OT_AUTORATE_VENC_MAX_CHN_NUM];
} ot_autorate_venc_chn;

【成员】

成员名 描述
count 码率自适应中生效的编码通道数量。
venc_hdl 码率自适应中生效的编码通道号数组。
ref_count 编码通道加入到码率自适应中的计数值。

【注意事项】

  • 同一个编码通道被多次加入到码率自适应中，ref_count表示其加入次数。

【相关数据类型及接口】

  • ot_autorate_query_venc_chn

4.6 ot_autorate_table

【说明】

定义码率自适应用户自定义调整表。

【定义】

typedef struct {
    td_s32 step_rate;
    td_u32 judge_level;
} ot_autorate_table;

【成员】

成员名 描述
step_rate 用户自定义的单次调整码率步长。
judge_level 用户自定义的判定级别。

【注意事项】

无

【相关数据类型及接口】

  • ot_autorate_call_back

4.7 ot_autorate_stream

【说明】

定义码率自适应码流信息。

【定义】

typedef struct {
    td_u32 stream_size;
    ot_venc_ref_type ref_type;
} ot_autorate_stream;

【成员】

成员名 描述
stream_size 码流大小。
ref_type 帧类型（I帧/P帧/B帧），参考 ot_venc_ref_type。

【注意事项】

无

【相关数据类型及接口】

  • ot_autorate_notify_on_stream

5 错误码

错误代码 宏定义 描述
OT_DEFINE_ERR(0x41, OT_ERR_LEVEL_ERROR, OT_ERR_NULL_PTR) OT_ERR_AUTORATE_NULL_PTR 输入参数空指针错误。
OT_DEFINE_ERR(0x41, OT_ERR_LEVEL_ERROR, OT_ERR_NOT_SUPPORT) OT_ERR_AUTORATE_NOT_SUPPORT 不支持的功能。
OT_DEFINE_ERR(0x41, OT_ERR_LEVEL_ERROR, 0x40) OT_ERR_AUTORATE_NOT_INIT 码率自适应未初始化。
OT_DEFINE_ERR(0x41, OT_ERR_LEVEL_ERROR, 0x41) OT_ERR_AUTORATE_CHN_FULL 编码通道已满（最多4个）。
OT_DEFINE_ERR(0x41, OT_ERR_LEVEL_ERROR, 0x42) OT_ERR_AUTORATE_INVALARG 输入参数非法。
OT_DEFINE_ERR(0x41, OT_ERR_LEVEL_ERROR, 0x43) OT_ERR_AUTORATE_NO_RESOURCES 无可用资源（如线程创建失败）。
OT_DEFINE_ERR(0x41, OT_ERR_LEVEL_ERROR, 0x44) OT_ERR_AUTORATE_CHN_NEED_REMOV 去初始化前需先移除所有编码通道。
OT_DEFINE_ERR(0x41, OT_ERR_LEVEL_ERROR, 0x45) OT_ERR_AUTORATE_PATH_NOT_EXIST 调试日志路径不存在。

6 使用注意事项

  1. 句柄范围：venc_hdl 取值范围为 [0, OT_VENC_MAX_CHN_NUM)，最多支持向码率自适应增加4个不同的编码通道。

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

    启动：

    ot_autorate_init(&attr, &callback)       // 初始化，传入属性和回调
  → ot_autorate_add_venc_chn(venc_hdl)   // 添加编码通道
  → [循环] ot_autorate_notify_on_stream  // 获取码流时通知

    停止（逆序）：

ot_autorate_remove_venc_chn(venc_hdl)    // 移除所有编码通道
  → ot_autorate_deinit()                 // 去初始化

  1. 资源配对：ot_autorate_add_venc_chn 与 ot_autorate_remove_venc_chn 必须对称调用。内部采用引用计数机制，多个用户点播同一通道时需重复调用 add，退出时需对应次数调用 remove。去初始化前必须移除所有编码通道，否则返回 OT_ERR_AUTORATE_CHN_NEED_REMOV。

  2. 属性语义：ot_autorate_attr 为动态属性，支持运行过程中通过 ot_autorate_set_attr 动态修改。初始化时必须传入有效的初始属性。

  3. 编码格式：仅支持 H.265 AVBR 和 H.265 CBR 两种编码格式，其他格式返回 OT_ERR_AUTORATE_NOT_SUPPORT。

7 附注 / 关联文档

  • 头文件：ot_autorate.h
  • Kconfig 选项：COMP_NETWORK_OT_AUTORATE
  • 依赖：海思 SDK（ss_mpi_venc.h、ss_mpi_sys.h）、securec、pthread
  • DFX 诊断：通过 /proc/autorate 查看码率自适应运行状态