1# 典型场景的视频编码配置
2
3描述AVCodec在不同应用场景下的推荐配置参数，供调用者根据实际应用场景进行视频编码应用的开发。
4
5视频编码包括低时延、直播、离线转码等主要场景。
6
7
8## 通用开发步骤
9
10**在CMake脚本中链接动态库**
11
12```cmake
13target_link_libraries(sample PUBLIC libnative_media_codecbase.so)
14target_link_libraries(sample PUBLIC libnative_media_core.so)
15target_link_libraries(sample PUBLIC libnative_media_venc.so)
16```
17
18> **说明：**
19>
20> 上述'sample'字样仅为示例，此处由调用者根据实际工程目录自定义。
21>
22
23**添加头文件**
24
25```c++
26#include <multimedia/player_framework/native_avcodec_videoencoder.h>
27#include <multimedia/player_framework/native_avcapability.h>
28#include <multimedia/player_framework/native_avcodec_base.h>
29#include <multimedia/player_framework/native_avformat.h>
30#include <fstream>
31```
32
33## 低时延场景
34
35低时延场景涵盖了视频会议、云游戏、互动直播以及生产远程操作等，这些均是对端到端时延有较高要求的交互式应用。下图展示了典型的低时延场景。
36
37a. 视频会议（单向）:
38
39   ![Video conference](figures/video-conference.png)
40
41b. 云游戏场景:
42
43   ![Cloud gaming](figures/cloud-gaming.png)
44
45c. 生产操作场景:
46
47   ![Production operation](figures/production-operation.png)
48
49
50**开发指导**
51
52基础编码流程请参考[视频编码](video-encoding.md)，下面仅针对编码器配置阶段做具体说明。
53
541. 校验特性。
55
56   在创建编码器实例前，可校验当前视频编码器是否支持低时延特性。若支持，则可以使能编码低时延特性。
57
58    ```c++
59    // 1.1 获取对应视频编码器能力句柄，此处以H.265为例
60    OH_AVCapability *cap = OH_AVCodec_GetCapability(OH_AVCODEC_MIMETYPE_VIDEO_HEVC, true);
61    // 1.2 通过特性能力查询接口校验是否支持低时延特性
62    bool isSupported = OH_AVCapability_IsFeatureSupported(cap, VIDEO_LOW_LATENCY);
63    ```
64
652. 配置编码器参数。
66
67    在配置编码器参数阶段，配置适合低时延场景的编码参数。
68
69    ```c++
70    // 2.1 创建配置AVFormat
71    OH_AVFormat *format = OH_AVFormat_Create();
72
73    // 2.2 填充使能参数键值对（以1080p@15fps SDR输入源为例）
74    OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, 1920); // 视频宽
75    OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, 1080); // 视频高
76    OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, AV_PIXEL_FORMAT_NV12); // YUV排布格式
77    OH_AVFormat_SetIntValue(format, OH_MD_KEY_RANGE_FLAG, 0); // 0:limited range/TV 1:full range/PC
78    OH_AVFormat_SetIntValue(format, OH_MD_KEY_COLOR_PRIMARIES, OH_ColorPrimary::COLOR_PRIMARY_BT709); // 视频源色域
79    OH_AVFormat_SetIntValue(format, OH_MD_KEY_TRANSFER_CHARACTERISTICS, OH_TransferCharacteristic::TRANSFER_CHARACTERISTIC_BT709); // OETF/EOTF曲线
80    OH_AVFormat_SetIntValue(format, OH_MD_KEY_MATRIX_COEFFICIENTS, OH_MatrixCoefficient:: MATRIX_COEFFICIENT_BT709); // 视频YUV和RGB转换矩阵
81    OH_AVFormat_SetIntValue(format, OH_MD_KEY_PROFILE, OH_HEVCProfile::HEVC_PROFILE_MAIN); // 编码profile
82    OH_AVFormat_SetDoubleValue(format, OH_MD_KEY_FRAME_RATE, 15.0); // 视频帧率
83    OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY, 1); // 低时延场景必选, 使能低时延特性：YUV进一帧，出一帧码流数据
84    OH_AVFormat_SetIntValue(format, OH_MD_KEY_I_FRAME_INTERVAL, -1);
85    OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_ENCODE_BITRATE_MODE, OH_VideoEncodeBitrateMode::CBR); // 码控模式配置为CBR
86    OH_AVFormat_SetLongValue(format, OH_MD_KEY_BITRATE, 1500000); // 设置码率为1.5Mbps
87
88    // 2.3 参数配置
89    int32_t ret = OH_VideoEncoder_Configure(videoEnc, format);
90    if (ret != AV_ERR_OK) {
91        // 异常处理
92    }
93    // 2.4 配置完成后销毁AVFormat
94    OH_AVFormat_Destroy(format);
95    ```
96
97    > **注意：**
98    > 低时延场景需要配置B帧个数为0。
99    >
100
1013. 配置解码器参数。
102
103    视频编码器使能低时延特性后，对应地，解码器也需要配置适合低时延场景的解码参数。
104
105    在 CMake 脚本中链接动态库。
106    ``` cmake
107    target_link_libraries(sample PUBLIC libnative_media_vdec.so)
108    ```
109
110    添加头文件。
111    ```c++
112    #include <multimedia/player_framework/native_avcodec_videodecoder.h>
113    ```
114
115    ```c++
116    // 3.1 创建配置AVFormat
117    OH_AVFormat *format = OH_AVFormat_Create();
118
119    // 3.2 写入format
120    OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, 1920); // 视频宽，必须配置
121    OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, 1080); // 视频高，必须配置
122    OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, AV_PIXEL_FORMAT_NV12); // YUV排布格式
123    // 必选，配置低时延解码
124    OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY, 1); // 低时延场景必选，使能低时延特性：YUV进一帧，出一帧码流数据
125
126    // 3.3 配置解码器
127    int32_t ret = OH_VideoDecoder_Configure(videoDec, format);
128    if (ret != AV_ERR_OK) {
129        // 异常处理
130    }
131    // 3.4 配置完成后销毁AVFormat
132    OH_AVFormat_Destroy(format);
133    ```
134    如果需要适配网络波动，推荐结合采用[时域可分层视频编码](video-encoding-temporal-scalability.md)配置。
135
136## 直播场景
137
138直播场景包括泛娱乐直播、游戏直播、赛事直播等，这些均是对视频端到端时延要求不高的应用场景。
139
140   ![Live streaming](figures/live-streaming.png)
141
142
143**开发指导**
144
145基础编码流程请参考[视频编码](video-encoding.md)，下面仅针对编码器配置阶段做具体说明。
146
1471. （可选）校验特性。
148
149   在创建编码器实例前，可校验当前视频编码器是否支持低时延特性。若支持，则可以使能编码低时延特性。
150
151    ```c++
152    // 1.1 获取对应视频编码器能力句柄，此处以H.265为例
153    OH_AVCapability *cap = OH_AVCodec_GetCapability(OH_AVCODEC_MIMETYPE_VIDEO_HEVC, true);
154    // 1.2 通过特性能力查询接口校验是否支持低时延特性
155    bool isSupported = OH_AVCapability_IsFeatureSupported(cap, VIDEO_LOW_LATENCY);
156    ```
157
1582. 配置编码器参数。
159
160    在配置编码器参数阶段，配置适合直播场景的编码参数。
161
162    ```c++
163    // 2.1 创建配置用临时AVFormat
164    OH_AVFormat *format = OH_AVFormat_Create();
165    // 2.2 填充使能参数键值对（以1080p@15fps SDR输入源为例）
166    OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, 1920); // 视频宽
167    OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, 1080); // 视频高
168    OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, AV_PIXEL_FORMAT_NV12); // YUV排布格式
169    OH_AVFormat_SetIntValue(format, OH_MD_KEY_RANGE_FLAG, 0); // 0:limited range/TV 1:full range/PC
170    OH_AVFormat_SetIntValue(format, OH_MD_KEY_COLOR_PRIMARIES, OH_ColorPrimary::COLOR_PRIMARY_BT709); // 视频源色域
171    OH_AVFormat_SetIntValue(format, OH_MD_KEY_TRANSFER_CHARACTERISTICS, OH_TransferCharacteristic::TRANSFER_CHARACTERISTIC_BT709); // OETF/EOTF曲线
172    OH_AVFormat_SetIntValue(format, OH_MD_KEY_MATRIX_COEFFICIENTS, OH_MatrixCoefficient:: MATRIX_COEFFICIENT_BT709); // 视频YUV和RGB转换矩阵
173    OH_AVFormat_SetIntValue(format, OH_MD_KEY_PROFILE, OH_HEVCProfile::HEVC_PROFILE_MAIN); // 编码profile
174    OH_AVFormat_SetDoubleValue(format, OH_MD_KEY_FRAME_RATE, 22); // 视频帧率
175    OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY, 1); // 直播场景如果时延要求高，可选设置，使能低时延特性：YUV进一帧，出一帧码流数据
176    OH_AVFormat_SetIntValue(format, OH_MD_KEY_I_FRAME_INTERVAL, 2000); // 关键帧间隔2s
177    OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_ENCODE_BITRATE_MODE, OH_VideoEncodeBitrateMode::VBR); // 码控模式配置为VBR
178    OH_AVFormat_SetLongValue(format, OH_MD_KEY_BITRATE, 2500000); // 设置码率为2.5Mbps// 2.3 参数配置
179    int32_t ret = OH_VideoEncoder_Configure(videoEnc, format);
180    if (ret != AV_ERR_OK) {
181        // 异常处理
182    }
183    // 2.4 配置完成后销毁临时AVFormat
184    OH_AVFormat_Destroy(format);
185    ```
186
187
188## 离线转码场景
189
190离线转码场景包括电视剧、电影、网络短剧、直播回放、编辑导出等多种应用场景，为了适配支持不同显示规格（如480p、1080p、4K等）终端、不同码流格式（如H.264、H.265等）的终端，以及不同带宽条件下的多种情况，在内容制作端对源进行离线转码，生成多种尺寸、多种码率、多种编码格式的视频码流文件，供用户分享或者观看。
191
192   ![Video On-Demand](figures/vod.png)
193
194
195**开发指导**
196
197基础编码流程请参考[视频编码](video-encoding.md)，下面仅针对编码器配置阶段做具体说明。
198
199配置编码器参数。
200
201在配置编码器参数阶段，配置适合离线转码场景的编码参数。
202
203```c++
204// 1. 创建配置AVFormat
205OH_AVFormat *format = OH_AVFormat_Create();
206// 2. 填充使能参数键值对（以1080p@15fps SDR输入源为例）
207OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, 1920); // 视频宽
208OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, 1080); // 视频高
209OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, AV_PIXEL_FORMAT_NV12); // YUV排布格式
210OH_AVFormat_SetIntValue(format, OH_MD_KEY_RANGE_FLAG, 0); // 0:limited range/TV 1:full range/PC
211OH_AVFormat_SetIntValue(format, OH_MD_KEY_COLOR_PRIMARIES, OH_ColorPrimary::COLOR_PRIMARY_BT709); // 视频源色域
212OH_AVFormat_SetIntValue(format, OH_MD_KEY_TRANSFER_CHARACTERISTICS, OH_TransferCharacteristic::TRANSFER_CHARACTERISTIC_BT709); // OETF/EOTF曲线
213OH_AVFormat_SetIntValue(format, OH_MD_KEY_MATRIX_COEFFICIENTS, OH_MatrixCoefficient:: MATRIX_COEFFICIENT_BT709); // 视频YUV和RGB转换矩阵
214OH_AVFormat_SetIntValue(format, OH_MD_KEY_PROFILE, OH_HEVCProfile::HEVC_PROFILE_MAIN); // 编码profile
215OH_AVFormat_SetDoubleValue(format, OH_MD_KEY_FRAME_RATE, 25); // 视频帧率
216OH_AVFormat_SetIntValue(format, OH_MD_KEY_I_FRAME_INTERVAL, 5000); // 关键帧间隔5s
217OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_ENCODE_BITRATE_MODE, OH_VideoEncodeBitrateMode::VBR); // 码控模式配置为VBR
218OH_AVFormat_SetLongValue(format, OH_MD_KEY_BITRATE, 3000000); // 设置码率为3Mbps
219// 3. 参数配置
220int32_t ret = OH_VideoEncoder_Configure(videoEnc, format);
221if (ret != AV_ERR_OK) {
222    // 异常处理
223}
224// 4. 配置完成后销毁AVFormat
225OH_AVFormat_Destroy(format);
226```