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