1# VideoEncoder 2 3 4## 概述 5 6VideoEncoder模块提供用于视频编码的函数。 7 8**系统能力：** SystemCapability.Multimedia.VideoEncoder 9 10**起始版本：** 9 11 12 13## 汇总 14 15 16### 文件 17 18| 名称 | 描述 | 19| -------- | -------- | 20| [native_avcodec_videoencoder.h](native__avcodec__videoencoder_8h.md) | 声明用于视频编码的Native API。 | 21 22 23### 类型定义 24 25| 名称 | 描述 | 26| -------- | -------- | 27| typedef enum [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode-1) [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) | 视频编码器的比特率模式。 | 28 29 30### 枚举 31 32| 名称 | 描述 | 33| -------- | -------- | 34| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) { CBR = 0, VBR = 1, CQ = 2 } | 视频编码器的比特率模式。 | 35 36 37### 函数 38 39| 名称 | 描述 | 40| -------- | -------- | 41| OH_AVCodec \* [OH_VideoEncoder_CreateByMime](#oh_videoencoder_createbymime) (const char \*mime) | 从MIME类型创建视频编码器实例。 | 42| OH_AVCodec \* [OH_VideoEncoder_CreateByName](#oh_videoencoder_createbyname) (const char \*name) | 通过视频编码器名称创建视频编码器实例。 | 43| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Destroy](#oh_videoencoder_destroy) (OH_AVCodec \*codec) | 清理编码器内部资源，销毁编码器实例。 | 44| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_SetCallback](#oh_videoencoder_setcallback) (OH_AVCodec \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | 设置异步回调函数，让应用可以响应视频编码器生成的事件。 | 45| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_RegisterCallback](#oh_videoencoder_registercallback) (OH_AVCodec \*codec, [OH_AVCodecCallback](_o_h___a_v_codec_callback.md) callback, void \*userData) | 注册异步回调函数，让应用可以响应视频编码器生成的事件。 | 46| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Configure](#oh_videoencoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | 配置视频编码器，通常需要配置要编码的视频轨的描述信息。 | 47| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Prepare](#oh_videoencoder_prepare) (OH_AVCodec \*codec) | 准备编码器的内部资源。 | 48| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Start](#oh_videoencoder_start) (OH_AVCodec \*codec) | 启动编码器，准备成功后必须调用此接口。 | 49| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Stop](#oh_videoencoder_stop) (OH_AVCodec \*codec) | 停止编码器。 | 50| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Flush](#oh_videoencoder_flush) (OH_AVCodec \*codec) | 清除编码器中缓存的输入和输出数据。 | 51| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_Reset](#oh_videoencoder_reset) (OH_AVCodec \*codec) | 重置编码器。 | 52| OH_AVFormat \* [OH_VideoEncoder_GetOutputDescription](#oh_videoencoder_getoutputdescription) (OH_AVCodec \*codec) | 获取编码器输出数据的描述信息。 | 53| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_SetParameter](#oh_videoencoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | 为编码器设置动态参数。 | 54| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_GetSurface](#oh_videoencoder_getsurface) (OH_AVCodec \*codec, OHNativeWindow \*\*window) | 从视频编码器获取输入Surface。 | 55| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_FreeOutputData](#oh_videoencoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | 将处理后的输出缓冲区返回给编码器。 | 56| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_NotifyEndOfStream](#oh_videoencoder_notifyendofstream) (OH_AVCodec \*codec) | 通知视频编码器输入流已结束。 | 57| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputData](#oh_videoencoder_pushinputdata) (OH_AVCodec \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | 将填入数据的输入缓冲区提交给视频编码器。 | 58| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) (OH_AVCodec \*codec, uint32_t index) | 将填入数据的输入缓冲区提交给视频编码器。 | 59| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer) (OH_AVCodec \*codec, uint32_t index) | 将处理后的输出缓冲区返回给编码器。 | 60| OH_AVFormat \* [OH_VideoEncoder_GetInputDescription](#oh_videoencoder_getinputdescription) (OH_AVCodec \*codec) | 获取视频编码器接收的描述信息。 | 61| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoEncoder_IsValid](#oh_videoencoder_isvalid) (OH_AVCodec \*codec, bool \*isValid) | 检查当前编码实例是否有效。 | 62 63 64## 类型定义说明 65 66 67### OH_VideoEncodeBitrateMode 68 69``` 70typedef enum OH_VideoEncodeBitrateMode OH_VideoEncodeBitrateMode 71``` 72 73**描述** 74 75视频编码器的比特率模式。 76 77**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 78 79**起始版本：** 9 80 81 82## 枚举类型说明 83 84 85### OH_VideoEncodeBitrateMode 86 87``` 88enum OH_VideoEncodeBitrateMode 89``` 90 91**描述** 92 93视频编码器的比特率模式。 94 95**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 96 97**起始版本：** 9 98 99| 枚举值 | 描述 | 100| -------- | -------- | 101| CBR | 恒定比特率模式。 | 102| VBR | 可变比特率模式。 | 103| CQ | 恒定质量模式。 | 104 105 106## 函数说明 107 108 109### OH_VideoEncoder_Configure() 110 111``` 112OH_AVErrCode OH_VideoEncoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 113``` 114 115**描述** 116 117配置视频编码器，通常需要配置要编码的视频轨的描述信息。必须在调用Prepare之前，调用此接口。 118 119**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 120 121**起始版本：** 9 122 123**参数:** 124 125| 名称 | 描述 | 126| -------- | -------- | 127| codec | 指向视频编码实例的指针。 | 128| format | 指向OH_AVFormat的指针，用于给出要编码的视频轨的描述。 | 129 130**返回：** 131 132如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 133 134 135### OH_VideoEncoder_CreateByMime() 136 137``` 138OH_AVCodec* OH_VideoEncoder_CreateByMime (const char *mime) 139``` 140 141**描述** 142 143从MIME类型创建视频编码器实例，大多数情况下建议使用。 144 145**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 146 147**起始版本：** 9 148 149**参数:** 150 151| 名称 | 描述 | 152| -------- | -------- | 153| mime | MIME类型描述字符串，请参阅[AVCODEC_MIMETYPE](_codec_base.md#变量)。 | 154 155**返回：** 156 157成功则返回一个指向视频编码实例的指针，失败则返回nullptr。 158 159 160### OH_VideoEncoder_CreateByName() 161 162``` 163OH_AVCodec* OH_VideoEncoder_CreateByName (const char *name) 164``` 165 166**描述** 167 168通过视频编码器名称创建视频编码器实例。使用此接口的前提是知道编码器的确切名称。 169 170**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 171 172**起始版本：** 9 173 174**参数:** 175 176| 名称 | 描述 | 177| -------- | -------- | 178| name | 视频编码器名称。 | 179 180**返回：** 181 182成功则返回一个指向视频编码实例的指针，失败则返回nullptr。 183 184 185### OH_VideoEncoder_Destroy() 186 187``` 188OH_AVErrCode OH_VideoEncoder_Destroy (OH_AVCodec *codec) 189``` 190 191**描述** 192 193清理编码器内部资源，销毁编码器实例。 194 195**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 196 197**起始版本：** 9 198 199**参数:** 200 201| 名称 | 描述 | 202| -------- | -------- | 203| codec | 指向视频编码实例的指针。 | 204 205**返回：** 206 207如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 208 209 210### OH_VideoEncoder_Flush() 211 212``` 213OH_AVErrCode OH_VideoEncoder_Flush (OH_AVCodec *codec) 214``` 215 216**描述** 217 218清除编码器中缓存的输入和输出数据。 219 220调用此接口后，以前通过异步回调上报的所有缓冲区索引都将失效，请确保不要访问这些索引对应的缓冲区。 221 222**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 223 224**起始版本：** 9 225 226**参数:** 227 228| 名称 | 描述 | 229| -------- | -------- | 230| codec | 指向视频编码实例的指针。 | 231 232**返回：** 233 234如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 235 236 237### OH_VideoEncoder_FreeOutputBuffer() 238 239``` 240OH_AVErrCode OH_VideoEncoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 241``` 242 243**描述** 244 245将处理后的输出缓冲区返回给编码器。 246 247**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 248 249**起始版本：** 11 250 251**参数:** 252 253| 名称 | 描述 | 254| -------- | -------- | 255| codec | 指向视频编码实例的指针。 | 256| index | 输出缓冲区对应的索引值。 | 257 258**返回：** 259 260如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 261 262 263### OH_VideoEncoder_FreeOutputData() 264 265``` 266OH_AVErrCode OH_VideoEncoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 267``` 268 269**描述** 270 271将处理后的输出缓冲区返回给编码器。 272 273**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 274 275**起始版本：** 9 276 277**废弃版本：** 11 278 279**替代接口：**[OH_VideoEncoder_FreeOutputBuffer](#oh_videoencoder_freeoutputbuffer) 280 281**参数:** 282 283| 名称 | 描述 | 284| -------- | -------- | 285| codec | 指向视频编码实例的指针。 | 286| index | 输出缓冲区对应的索引值。 | 287 288**返回：** 289 290如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 291 292 293### OH_VideoEncoder_GetInputDescription() 294 295``` 296OH_AVFormat* OH_VideoEncoder_GetInputDescription (OH_AVCodec *codec) 297``` 298 299**描述** 300 301获取视频编码器接收的描述信息，调用[OH_VideoEncoder_Configure](#oh_videoencoder_configure)后调用此接口。 应该注意的是，返回指针所指向的OH_AVFormat实例的生命周期需要由调用者手动释放，请参阅[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)。 302 303**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 304 305**起始版本：** 10 306 307**参数:** 308 309| 名称 | 描述 | 310| -------- | -------- | 311| codec | 指向视频编码实例的指针。 | 312 313**返回：** 314 315返回指向OH_AVFormat实例的指针。 316 317 318### OH_VideoEncoder_GetOutputDescription() 319 320``` 321OH_AVFormat* OH_VideoEncoder_GetOutputDescription (OH_AVCodec *codec) 322``` 323 324**描述** 325 326获取编码器输出数据的描述信息。 327 328需要注意的是，返回值指向的OH_AVFormat实例的生命周期需要调用者手动释放。 329 330**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 331 332**起始版本：** 9 333 334**参数:** 335 336| 名称 | 描述 | 337| -------- | -------- | 338| codec | 指向视频编码实例的指针。 | 339 340**返回：** 341 342返回指向OH_AVFormat实例的指针。 343 344 345### OH_VideoEncoder_GetSurface() 346 347``` 348OH_AVErrCode OH_VideoEncoder_GetSurface (OH_AVCodec *codec, OHNativeWindow ** window ) 349``` 350 351**描述** 352 353从视频编码器获取输入Surface，必须在调用Prepare之前调用此接口。 354 355**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 356 357**起始版本：** 9 358 359**参数:** 360 361| 名称 | 描述 | 362| -------- | -------- | 363| codec | 指向视频编码实例的指针。 | 364| window | 指向OHNativeWindow实例的指针。 应用负责管理window的生命周期，结束时调用OH_NativeWindow_DestroyNativeWindow释放。 | 365 366**返回：** 367 368如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 369 370 371### OH_VideoEncoder_IsValid() 372 373``` 374OH_AVErrCode OH_VideoEncoder_IsValid (OH_AVCodec *codec, bool *isValid ) 375``` 376 377**描述** 378 379检查当前编码实例是否有效。 380 381**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 382 383**起始版本：** 10 384 385**参数:** 386 387| 名称 | 描述 | 388| -------- | -------- | 389| codec | 指向视频编码实例的指针。 | 390| isValid | 输出参数。指向布尔实例的指针，如果编码器实例有效，则为true，如果编码器实例无效，则为false。 | 391 392**返回：** 393 394如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 395 396 397### OH_VideoEncoder_NotifyEndOfStream() 398 399``` 400OH_AVErrCode OH_VideoEncoder_NotifyEndOfStream (OH_AVCodec *codec) 401``` 402 403**描述** 404 405通知视频编码器输入流已结束。建议使用此接口进行通知。编码器surface模式下，输入流的结束通知。 406 407**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 408 409**起始版本：** 9 410 411**参数:** 412 413| 名称 | 描述 | 414| -------- | -------- | 415| codec | 指向视频编码实例的指针。 | 416 417**返回：** 418 419如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 420 421 422### OH_VideoEncoder_Prepare() 423 424``` 425OH_AVErrCode OH_VideoEncoder_Prepare (OH_AVCodec *codec) 426``` 427 428**描述** 429 430若要准备编码器的内部资源，必须先调用Configure接口，再调用此接口。 431 432**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 433 434**起始版本：** 9 435 436**参数:** 437 438| 名称 | 描述 | 439| -------- | -------- | 440| codec | 指向视频编码实例的指针。 | 441 442**返回：** 443 444如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 445 446 447### OH_VideoEncoder_PushInputBuffer() 448 449``` 450OH_AVErrCode OH_VideoEncoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 451``` 452 453**描述** 454 455将填入数据的输入缓冲区提交给视频编码器。 456 457**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 458 459**起始版本：** 11 460 461**参数:** 462 463| 名称 | 描述 | 464| -------- | -------- | 465| codec | 指向视频编码实例的指针。 | 466| index | 输入缓冲区对应的索引值。 | 467 468**返回：** 469 470如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 471 472 473### OH_VideoEncoder_PushInputData() 474 475``` 476OH_AVErrCode OH_VideoEncoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 477``` 478 479**描述** 480 481将填入数据的输入缓冲区提交给视频编码器。 482 483**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 484 485**起始版本：** 10 486 487**废弃版本：** 11 488 489**替代接口：**[OH_VideoEncoder_PushInputBuffer](#oh_videoencoder_pushinputbuffer) 490 491**参数:** 492 493| 名称 | 描述 | 494| -------- | -------- | 495| codec | 指向视频编码实例的指针。 | 496| index | 输入缓冲区对应的索引值。 | 497| attr | 缓冲区中包含数据的描述信息。 | 498 499**返回：** 500 501如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 502 503 504### OH_VideoEncoder_RegisterCallback() 505 506``` 507OH_AVErrCode OH_VideoEncoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 508``` 509 510**描述** 511 512注册异步回调函数，让应用可以响应视频编码器生成的事件。在调用Prepare之前，必须调用此接口。 513 514**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 515 516**起始版本：** 11 517 518**参数:** 519 520| 名称 | 描述 | 521| -------- | -------- | 522| codec | 指向视频编码实例的指针。 | 523| callback | 所有回调函数的集合，请参阅[OH_AVCodecCallback](_o_h___a_v_codec_callback.md)。 | 524| userData | 用户特定数据。 | 525 526**返回：** 527 528如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 529 530 531### OH_VideoEncoder_Reset() 532 533``` 534OH_AVErrCode OH_VideoEncoder_Reset (OH_AVCodec *codec) 535``` 536 537**描述** 538 539重置编码器。如果要继续编码，需要再次调用Configure接口配置编码器实例。 540 541**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 542 543**起始版本：** 9 544 545**参数:** 546 547| 名称 | 描述 | 548| -------- | -------- | 549| codec | 指向视频编码实例的指针。 | 550 551**返回：** 552 553如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 554 555 556### OH_VideoEncoder_SetCallback() 557 558``` 559OH_AVErrCode OH_VideoEncoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 560``` 561 562**描述** 563 564设置异步回调函数，让应用可以响应视频编码器生成的事件。在调用Prepare之前，必须调用此接口。 565 566**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 567 568**起始版本：** 9 569 570**废弃版本：** 11 571 572**替代接口：**[OH_VideoEncoder_RegisterCallback](#oh_videoencoder_registercallback) 573 574**参数:** 575 576| 名称 | 描述 | 577| -------- | -------- | 578| codec | 指向视频编码实例的指针。 | 579| callback | 所有回调函数的集合，请参阅[OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md)。 | 580| userData | 用户特定数据。 | 581 582**返回：** 583 584如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 585 586 587### OH_VideoEncoder_SetParameter() 588 589``` 590OH_AVErrCode OH_VideoEncoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 591``` 592 593**描述** 594 595为编码器设置动态参数。 注意，此接口只有在编码器启动后才能调用。 同时，不正确的参数设置可能会导致编码失败。 596 597**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 598 599**起始版本：** 9 600 601**参数:** 602 603| 名称 | 描述 | 604| -------- | -------- | 605| codec | 指向视频编码实例的指针。 | 606| format | 指向OH_AVFormat实例的指针。 | 607 608**返回：** 609 610如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 611 612 613### OH_VideoEncoder_Start() 614 615``` 616OH_AVErrCode OH_VideoEncoder_Start (OH_AVCodec *codec) 617``` 618 619**描述** 620 621启动编码器，准备成功后必须调用此接口。成功启动后，编码器将开始报告注册的回调事件。 622 623**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 624 625**起始版本：** 9 626 627**参数:** 628 629| 名称 | 描述 | 630| -------- | -------- | 631| codec | 指向视频编码实例的指针。 | 632 633**返回：** 634 635如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 636 637 638### OH_VideoEncoder_Stop() 639 640``` 641OH_AVErrCode OH_VideoEncoder_Stop (OH_AVCodec *codec) 642``` 643 644**描述** 645 646停止编码器。停止之后，你可以通过Start接口进入Started状态。 647 648**系统能力：** SystemCapability.Multimedia.Media.VideoEncoder 649 650**起始版本：** 9 651 652**参数:** 653 654| 名称 | 描述 | 655| -------- | -------- | 656| codec | 指向视频编码实例的指针。 | 657 658**返回：** 659 660如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 661