1# VideoDecoder 2 3 4## 概述 5 6VideoDecoder模块提供用于视频解码的接口。 7 8对应的开发指南及样例可参考[视频解码](../../media/avcodec/video-decoding.md)。 9 10**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 11 12**起始版本：** 9 13 14接口在每个版本的支持情况以及在解码过程中可以调用的情况，如下图所示： 15 16 17 18 19 20## 汇总 21 22 23### 文件 24 25| 名称 | 描述 | 26| -------- | -------- | 27| [native_avcodec_videodecoder.h](native__avcodec__videodecoder_8h.md) | 声明用于视频解码的接口。 | 28 29 30### 函数 31 32| 名称 | 描述 | 33| -------- | -------- | 34| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoDecoder_CreateByMime](#oh_videodecoder_createbymime) (const char \*mime) | 根据[MIME](_codec_base.md#媒体编解码格式)类型创建视频解码器实例。 | 35| [OH_AVCodec](_codec_base.md#oh_avcodec) \* [OH_VideoDecoder_CreateByName](#oh_videodecoder_createbyname) (const char \*name) | 根据视频解码器名称创建视频解码器实例。 | 36| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Destroy](#oh_videodecoder_destroy) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 清理解码器内部资源，销毁解码器实例。 | 37| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetCallback](#oh_videodecoder_setcallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | 设置异步回调函数，让应用可以响应视频解码器生成的事件。（API11废弃） | 38| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVCodecCallback](_o_h___a_v_codec_callback.md) callback, void \*userData) | 注册异步回调函数，让应用可以响应视频解码器生成的事件。 | 39| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetSurface](#oh_videodecoder_setsurface) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OHNativeWindow](_codec_base.md#ohnativewindow) \*window) | 设置输出surface以提供视频解码输出。 | 40| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Configure](#oh_videodecoder_configure) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVFormat](_core.md#oh_avformat) \*format) | 配置视频解码器，通常需要配置解码视频轨迹的描述信息，这些信息可以从[OH_AVSource](_a_v_source.md)中提取。 | 41| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Prepare](#oh_videodecoder_prepare) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 准备解码器的内部资源。 | 42| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Start](#oh_videodecoder_start) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 调用OH_VideoDecoder_Prepare接口成功后调用此接口启动解码器。 | 43| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Stop](#oh_videodecoder_stop) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 停止解码器，释放输入输出buffer。 | 44| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Flush](#oh_videodecoder_flush) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 清除解码器中缓存的输入和输出数据及参数集如H.264格式的PPS/SPS。 | 45| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_Reset](#oh_videodecoder_reset) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 重置解码器，解码器回到初始化状态。 | 46| [OH_AVFormat](_core.md#oh_avformat) \* [OH_VideoDecoder_GetOutputDescription](#oh_videodecoder_getoutputdescription) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec) | 获取解码器输出数据的OH_AVFormat信息。 | 47| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetParameter](#oh_videodecoder_setparameter) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, [OH_AVFormat](_core.md#oh_avformat) \*format) | 设置解码器的动态参数。 | 48| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_PushInputData](#oh_videodecoder_pushinputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | 将填充数据的输入缓冲区提交给视频解码器。（API11废弃） | 49| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputData](#oh_videodecoder_renderoutputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将处理后的输出buffer返回给解码器，并通知解码器完成在输出surface上渲染buffer中包含的解码数据。（API11废弃） | 50| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_FreeOutputData](#oh_videodecoder_freeoutputdata) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将处理后的输出缓冲区返回到解码器。（API11废弃） | 51| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 通知视频解码器已对index对应的缓冲区完成输入数据的填充。 | 52| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将index对应的输出缓冲返回给解码器，缓冲中携带解码输出数据，并通知解码器完成在输出surface上渲染，输出缓冲包含解码数据。 | 53| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_RenderOutputBufferAtTime](#oh_videodecoder_renderoutputbufferattime) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index, int64_t renderTimestampNs) | 将index对应的输出缓冲返回给解码器，缓冲中携带解码输出数据，并通知解码器在开发者指定的时间内完成在输出surface上渲染，输出缓冲包含解码数据。 | 54| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 将处理后的输出缓冲区返回到解码器。 | 55| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_IsValid](#oh_videodecoder_isvalid) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, bool \*isValid) | 检查当前解码实例是否有效。 | 56| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_SetDecryptionConfig](#oh_videodecoder_setdecryptionconfig) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, MediaKeySession \*mediaKeySession, bool secureVideoPath) | 设置解密配置。 | 57| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_QueryInputBuffer](#oh_videodecoder_queryinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | 查询下一个可用输入缓冲区的索引。 | 58| [OH_AVBuffer](_core.md#oh_avbuffer) [OH_VideoDecoder_GetInputBuffer](#oh_videodecoder_getinputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 获取可用输入缓冲区的实例。 | 59| [OH_AVErrCode](_core.md#oh_averrcode) [OH_VideoDecoder_QueryOutputBuffer](#oh_videodecoder_queryoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t *index, int64_t timeoutUs) | 查询下一个可用输出缓冲区的索引。 | 60| [OH_AVBuffer](_core.md#oh_avbuffer) [OH_VideoDecoder_GetOutputBuffer](#oh_videodecoder_getoutputbuffer) ([OH_AVCodec](_codec_base.md#oh_avcodec) \*codec, uint32_t index) | 获取可用输出缓冲区的实例。 | 61 62 63## 函数说明 64 65 66### OH_VideoDecoder_Configure() 67 68``` 69OH_AVErrCode OH_VideoDecoder_Configure (OH_AVCodec *codec, OH_AVFormat *format ) 70``` 71**描述** 72配置视频解码器，通常需要配置解码视频的描述信息，这些信息可以从[OH_AVSource](_a_v_source.md)中提取。在调用OH_VideoDecoder_Prepare接口之前，必须调用此接口。 73 74以下参数的配置范围可通过[能力查询](../../media/avcodec/obtain-supported-codecs.md)获取，OH_MD_KEY_ROTATION配置的参数都支持。 75 76设置OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY接口时如果当前平台不支持，不报错，走正常解码流程。 77 78参数校验规则： 79 80| Key | 配置正常范围的值 | 配置超出范围的值 | 不配置该参数 | 81| -----------------------------------------------------------------------------| -------- | -------- | ------ | 82| OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 83| OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL | 84| OH_MD_KEY_PIXEL_FORMAT 请参阅[OH_AVPixelFormat](_core.md#oh_avpixelformat-1) | AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK | 85| OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | 86| OH_MD_KEY_ROTATION 请参阅[OH_MD_KEY_ROTATION](_codec_base.md#oh_md_key_rotation)| AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK | 87 88> **说明：** 89> 90> 建议按照该实例需要支持的最大分辨率来配置，否则可能会出现高于该分辨率的码流解码会触发异常。该设置直接影响应用的内存使用情况。 91 92 93**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 94 95**起始版本：** 9 96 97**参数:** 98 99| 名称 | 描述 | 100| -------- | -------- | 101| codec | 指向视频解码实例的指针。 | 102| format | 指向OH_AVFormat的指针，用于给出要解码的视频轨道的描述。 | 103 104**返回：** 105 106返回接口结果： 107 108AV_ERR_OK：执行成功。 109 110AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 111 112AV_ERR_INVALID_VAL： 113 114 1. 输入的codec指针为非解码器实例，或者为空指针； 115 2. 输入format参数不支持。 116 117AV_ERR_UNKNOWN：未知错误。 118 119AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 120 121AV_ERR_INVALID_STATE：本接口必须在OH_VideoDecoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 122 123AV_ERR_VIDEO_UNSUPPORTED_COLOR_SPACE_CONVERSION：不支持色彩空间转换功能。 124 125AV_ERR_UNSUPPORT：未支持的功能。 126 127 128### OH_VideoDecoder_CreateByMime() 129 130``` 131OH_AVCodec* OH_VideoDecoder_CreateByMime (const char *mime) 132``` 133**描述** 134根据MIME类型创建视频解码器实例，大多数情况下建议使用。 135 136**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 137 138**起始版本：** 9 139 140**参数:** 141 142| 名称 | 描述 | 143| -------- | -------- | 144| mime | MIME类型描述字符串，请参阅[AVCODEC_MIMETYPE](_codec_base.md#变量)。 | 145 146**返回：** 147 148返回一个指向视频解码实例的指针。当传入的解码器类型不支持或者内存资源耗尽时，返回NULL。 149 150 151### OH_VideoDecoder_CreateByName() 152 153``` 154OH_AVCodec* OH_VideoDecoder_CreateByName (const char *name) 155``` 156**描述** 157根据视频解码器名称创建视频解码器实例。使用此接口的前提是知道解码器的确切名称，解码器的名称可以通过能力查询获取。 158 159详情请参见：[获取支持的编解码能力](../../media/avcodec/obtain-supported-codecs.md#创建指定名称的编解码器)。 160 161**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 162 163**起始版本：** 9 164 165**参数:** 166 167| 名称 | 描述 | 168| -------- | -------- | 169| name | 视频解码器名称。 | 170 171**返回：** 172 173返回指向视频解码实例的指针。当输入的解码器名称不支持或者内存资源耗尽时，返回NULL。 174 175 176### OH_VideoDecoder_Destroy() 177 178``` 179OH_AVErrCode OH_VideoDecoder_Destroy (OH_AVCodec *codec) 180``` 181**描述** 182清理解码器内部资源，销毁解码器实例。不能重复销毁。 183 184**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 185 186**起始版本：** 9 187 188**参数:** 189 190| 名称 | 描述 | 191| -------- | -------- | 192| codec | 指向视频解码实例的指针。 | 193 194**返回：** 195 196返回接口结果： 197 198AV_ERR_OK：执行成功。 199 200AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 201 202AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 203 204AV_ERR_UNKNOWN：未知错误。 205 206AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 207 208 209### OH_VideoDecoder_Flush() 210 211``` 212OH_AVErrCode OH_VideoDecoder_Flush (OH_AVCodec *codec) 213``` 214**描述** 215清除解码器中缓存的输入和输出数据及参数集如H.264格式的PPS/SPS。调用此接口后，以前通过异步回调上报的所有缓冲区index都将失效，请确保不要访问这些index对应的缓冲区。 216 217**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 218 219**起始版本：** 9 220 221**参数:** 222 223| 名称 | 描述 | 224| -------- | -------- | 225| codec | 指向视频解码实例的指针。 | 226 227**返回：** 228 229返回接口结果： 230 231AV_ERR_OK：执行成功。 232 233AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 234 235AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 236 237AV_ERR_UNKNOWN：未知错误。 238 239AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 240 241AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 242 243 244### OH_VideoDecoder_FreeOutputBuffer() 245 246``` 247OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index ) 248``` 249**描述** 250将处理后的输出缓冲区返回到解码器。用户使用完需要及时调用此接口释放输出缓存区，否则会阻塞解码流程。 251 252详情请参见：[视频解码](../../media/avcodec/video-decoding.md) “Surface模式的步骤-12或Buffer模式步骤-10”。 253 254**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 255 256**起始版本：** 11 257 258**参数:** 259 260| 名称 | 描述 | 261| -------- | -------- | 262| codec | 指向视频解码实例的指针。 | 263| index | 输出buffer对应的索引值。由[OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer)给出。 | 264 265**返回：** 266 267返回接口结果： 268 269AV_ERR_OK：执行成功。 270 271AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 272 273AV_ERR_INVALID_VAL： 274 275 1. 输入的codec指针为非解码器实例，或者为空指针； 276 2. index非法或者连续给同一个index，该错误不影响后续解码流程。 277 278AV_ERR_UNKNOWN：未知错误。 279 280AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 281 282AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 283 284 285### OH_VideoDecoder_GetOutputDescription() 286 287``` 288OH_AVFormat* OH_VideoDecoder_GetOutputDescription (OH_AVCodec *codec) 289``` 290**描述** 291获取解码器输出数据的OH_AVFormat信息，请参阅[OH_AVFormat](_core.md#oh_avformat)。 292 293需要注意的是，指向的OH_AVFormat实例在生命周期结束时需要开发者通过调用接口[OH_AVFormat_Destroy](_core.md#oh_avformat_destroy)释放。 294 295**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 296 297**起始版本：** 9 298 299**参数:** 300 301| 名称 | 描述 | 302| -------- | -------- | 303| codec | 指向视频解码实例的指针。 | 304 305**返回：** 306 307返回指向OH_AVFormat实例的指针。当输入的codec指针非解码器实例，或者为空指针，则返回NULL。 308 309 310### OH_VideoDecoder_IsValid() 311 312``` 313OH_AVErrCode OH_VideoDecoder_IsValid (OH_AVCodec *codec, bool *isValid ) 314``` 315**描述** 316在解码器实例存在的情况下，检查当前解码器服务是否有效。 317 318**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 319 320**起始版本：** 10 321 322**参数:** 323 324| 名称 | 描述 | 325| -------- | -------- | 326| codec | 指向视频解码实例的指针。 | 327| isValid | 输出参数，指向布尔类型的指针。只有当接口返回AV_ERR_OK时，该值表示解码器服务的有效性（true为有效，false为无效）。建议开发者将isValid初始化为false。 | 328 329**返回：** 330 331返回接口结果： 332 333AV_ERR_OK：执行成功。 334 335AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 336 337 338### OH_VideoDecoder_Prepare() 339 340``` 341OH_AVErrCode OH_VideoDecoder_Prepare (OH_AVCodec *codec) 342``` 343**描述** 344准备解码器的内部资源，在调用该接口之前，必须调用OH_VideoDecoder_Configure接口。 345 346**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 347 348**起始版本：** 9 349 350**参数:** 351 352| 名称 | 描述 | 353| -------- | -------- | 354| codec | 指向视频解码实例的指针。 | 355 356**返回：** 357 358返回接口结果： 359 360AV_ERR_OK：执行成功。 361 362AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 363 364AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 365 366AV_ERR_UNKNOWN：未知错误。 367 368AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 369 370AV_ERR_OPERATE_NOT_PERMIT： 371 372 1. 内部执行错误； 373 2. 配置了色彩空间转换功能，但解码器处于Buffer模式。 374 375 376### OH_VideoDecoder_PushInputBuffer() 377 378``` 379OH_AVErrCode OH_VideoDecoder_PushInputBuffer (OH_AVCodec *codec, uint32_t index ) 380``` 381**描述** 382通知视频解码器已对index对应的缓冲区完成输入数据的填充。 383 384输入回调将报告可用的输入缓冲区和相应的index值，请参阅[OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer)。 一旦具有指定index的缓冲区提交到视频解码器，则无法再次访问缓冲区，直到再次收到输入回调，报告具有相同index的缓冲区可用。 385 386此外，对于某些解码器，需要在开始时向解码器输入编解码特定数据，以初始化解码器的解码过程，如H.264格式的PPS/SPS数据。 387开发者可以使用该接口把解码需要的参数集如H.264格式的PPS/SPS传递给解码器，该参数集可以单独送入解码器也可以和要解码的数据一起传入。 388 389**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 390 391**起始版本：** 11 392 393**参数:** 394 395| 名称 | 描述 | 396| -------- | -------- | 397| codec | 指向视频解码实例的指针。 | 398| index | 输入buffer对应的索引值。由[OH_AVCodecOnNeedInputBuffer](_codec_base.md#oh_avcodeconneedinputbuffer)给出。| 399 400**返回：** 401 402返回接口结果： 403 404AV_ERR_OK：执行成功。 405 406AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 407 408AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 409 410AV_ERR_UNKNOWN：未知错误。 411 412AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 413 414AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 415 416 417### OH_VideoDecoder_RegisterCallback() 418 419``` 420OH_AVErrCode OH_VideoDecoder_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData ) 421``` 422**描述** 423注册异步回调函数，让应用可以响应视频解码器生成的事件。在调用OH_VideoDecoder_Prepare接口之前，必须调用此接口。 424 425**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 426 427**起始版本：** 11 428 429**参数:** 430 431| 名称 | 描述 | 432| -------- | -------- | 433| codec | 指向视频解码器实例的指针。 | 434| callback | 所有回调函数的集合，请参见[OH_AVCodecCallback](_o_h___a_v_codec_callback.md)。 | 435| userData | 开发者执行回调所依赖的数据。 | 436 437**返回：** 438 439返回接口结果： 440 441AV_ERR_OK：执行成功。 442 443AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 444 445AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 446 447AV_ERR_UNKNOWN：未知错误。 448 449AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 450 451AV_ERR_INVALID_STATE：本接口必须在OH_VideoDecoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 452 453 454### OH_VideoDecoder_RenderOutputBuffer() 455 456``` 457OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer (OH_AVCodec *codec, uint32_t index ) 458``` 459**描述** 460将index对应的输出缓冲返回给解码器，缓冲中携带解码输出数据，并通知解码器完成在输出surface上渲染，输出缓冲包含解码数据。 461 462如果之前没有配置输出surface，则调用此接口仅将指定index对应的输出缓冲区返回给解码器。 463 464**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 465 466**起始版本：** 11 467 468**参数:** 469 470| 名称 | 描述 | 471| -------- | -------- | 472| codec | 指向视频解码实例的指针。 | 473| index | 输出buffer对应的索引值。由[OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer)给出。 | 474 475**返回：** 476 477返回接口结果： 478 479AV_ERR_OK：执行成功。 480 481AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 482 483AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 484 485AV_ERR_UNKNOWN：未知错误。 486 487AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 488 489AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 490 491 492### OH_VideoDecoder_RenderOutputBufferAtTime() 493 494``` 495OH_AVErrCode OH_VideoDecoder_RenderOutputBufferAtTime(OH_AVCodec *codec, uint32_t index, int64_t renderTimestampNs); 496``` 497**描述** 498将index对应的输出缓冲返回给解码器，缓冲中携带解码输出数据，并通知解码器在开发者指定的时间内完成在输出surface上渲染，输出缓冲包含解码数据。 499如果之前没有配置输出surface，则调用此接口仅将指定index对应的输出缓冲区返回给解码器。 500 501开发者可以使用时间戳在特定时间（在VSYNC或者缓冲区时间戳之后）渲染缓冲区。若要在指定的时间戳显示，时间戳需要合理接近系统时间，有几点需要注意： 5021. 缓冲区是按照顺序处理的，因此可能会阻塞后续缓冲区在surface上的显示，如果想要对用户的一些行为做出反应，例如停止或者快进快退视频，这一点很重要。 5032. 如果多个缓冲区被发送到surface要在同一个VSYNC上渲染，那么最后一个将会被显示，其他的将被丢弃。 5043. 如果时间戳与当前的系统时间不是“合理接近”，surface将会忽略时间戳，并在可行的最早时间里显示buffer。在此模式下不会丢弃帧。 5054. 如果需要由系统根据显示刷新率来丢帧，则必须调用此接口，否则应用需自行实现丢帧逻辑。 506 507**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 508 509**起始版本：** 12 510 511**参数:** 512 513| 名称 | 描述 | 514| -------- | -------- | 515| codec | 指向视频解码实例的指针。 | 516| index | 输出buffer对应的索引值。 由[OH_AVCodecOnNewOutputBuffer](_codec_base.md#oh_avcodeconnewoutputbuffer)给出。 | 517| renderTimestampNs | 输出buffer被发送到surface的时间戳，取值范围大于0，应由std::chrono::steady_clock标准库时钟生成，且单位为纳秒。 | 518 519**返回：** 520 521返回接口结果： 522 523AV_ERR_OK：执行成功。 524 525AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 526 527AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 528 529AV_ERR_UNKNOWN：未知错误。 530 531AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 532 533AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 534 535 536### OH_VideoDecoder_Reset() 537 538``` 539OH_AVErrCode OH_VideoDecoder_Reset (OH_AVCodec *codec) 540``` 541**描述** 542重置解码器，解码器回到初始化状态。如果要继续解码，需要再次调用OH_VideoDecoder_Configure接口配置解码器实例。 543 544**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 545 546**起始版本：** 9 547 548**参数:** 549 550| 名称 | 描述 | 551| -------- | -------- | 552| codec | 指向视频解码实例的指针。 | 553 554**返回：** 555 556返回接口结果： 557 558AV_ERR_OK：执行成功。 559 560AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 561 562AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 563 564AV_ERR_UNKNOWN：未知错误。 565 566AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 567 568 569### OH_VideoDecoder_SetDecryptionConfig() 570 571``` 572OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig (OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureVideoPath) 573``` 574**描述** 575设置解密配置。在调用OH_VideoDecoder_Prepare接口之前，可选择调用此接口。 576 577**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 578 579**起始版本：** 11 580 581**参数:** 582 583| 名称 | 描述 | 584| -------- | -------- | 585| codec | 指向视频解码实例的指针。 | 586| mediaKeySession | 指向带有解密功能的DRM会话实例的指针，请参阅[MediaKeySession](../../reference/apis-drm-kit/capi-native-mediakeysession-h.md)。 | 587| secureVideoPath | 安全视频通路。指定安全视频通路为true，非安全视频通路为false。在[Surface模式](../../media/avcodec/video-decoding.md#surface模式)下，既支持安全视频通路，也支持非安全视频通路。在[Buffer模式](../../media/avcodec/video-decoding.md#buffer模式)下，仅支持非安全视频通路。 | 588 589**返回：** 590 591返回接口结果： 592 593AV_ERR_OK：操作成功。 594 595AV_ERR_OPERATE_NOT_PERMIT： 596 597 1. 内部执行错误； 598 2. 解码服务进程异常； 599 3. 媒体密钥会话服务处于错误状态。 600 601AV_ERR_INVALID_VAL： 602 603 1. 输入的codec指针为非解码器实例或为空指针； 604 2. mediaKeySession为NULL或无效。 605 606AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 607 608 609### OH_VideoDecoder_SetParameter() 610 611``` 612OH_AVErrCode OH_VideoDecoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format ) 613``` 614**描述** 615设置解码器的动态参数。 616 617注意，该接口只能在解码器启动后调用。同时，参数配置错误可能会导致解码失败。 618 619**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 620 621**起始版本：** 9 622 623**参数:** 624 625| 名称 | 描述 | 626| -------- | -------- | 627| codec | 指向视频解码实例的指针。 | 628| format | 指向OH_AVFormat实例的指针。 | 629 630**返回：** 631 632返回接口结果： 633 634AV_ERR_OK：执行成功。 635 636AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 637 638AV_ERR_INVALID_VAL： 639 640 1. 输入的codec指针为非解码器实例，或者为空指针； 641 2. 输入format参数不支持。 642 643AV_ERR_UNKNOWN：未知错误。 644 645AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 646 647AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 648 649 650### OH_VideoDecoder_SetSurface() 651 652``` 653OH_AVErrCode OH_VideoDecoder_SetSurface (OH_AVCodec * codec, OHNativeWindow * window ) 654``` 655**描述** 656 657设置输出surface以提供视频解码输出。 658 659在初始化阶段，必须在调用OH_VideoDecoder_Prepare接口之前调用此接口。在Executing状态可以直接调用该接口。 660 661**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 662 663**起始版本：** 9 664 665**参数:** 666 667| 名称 | 描述 | 668| -------- | -------- | 669| codec | 指向视频解码实例的指针。 | 670| window | 指向OHNativeWindow实例的指针，请参阅[OHNativeWindow](_codec_base.md#ohnativewindow)。 | 671 672**返回：** 673 674返回接口结果： 675 676AV_ERR_OK：执行成功。 677 678AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 679 680AV_ERR_OPERATE_NOT_PERMIT：本接口仅支持在Surface模式下调用, 如果在Buffer模式调用, 则返回此错误码。 681 682AV_ERR_INVALID_VAL： 683 684 1. 输入的codec指针为非解码器实例，或者为空指针； 685 2. window为空指针。 686 687AV_ERR_UNKNOWN：未知错误。 688 689AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 690 691 692### OH_VideoDecoder_Start() 693 694``` 695OH_AVErrCode OH_VideoDecoder_Start (OH_AVCodec *codec) 696``` 697**描述** 698调用OH_VideoDecoder_Prepare接口成功后调用此接口启动解码器。成功启动后，解码器将开始报告注册的回调事件。 699 700**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 701 702**起始版本：** 9 703 704**参数:** 705 706| 名称 | 描述 | 707| -------- | -------- | 708| codec | 指向视频解码实例的指针。 | 709 710**返回：** 711 712返回接口结果： 713 714AV_ERR_OK：执行成功。 715 716AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 717 718AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 719 720AV_ERR_UNKNOWN：未知错误。 721 722AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 723 724AV_ERR_OPERATE_NOT_PERMIT： 725 726 1. 内部执行错误； 727 2. 视频色彩空间转换功能已配置，但是没有调用OH_VideoDecoder_Prepare接口。 728 729 730### OH_VideoDecoder_Stop() 731 732``` 733OH_AVErrCode OH_VideoDecoder_Stop (OH_AVCodec *codec) 734``` 735**描述** 736 737停止解码器，释放输入输出buffer。停止后，可以通过调用OH_VideoDecoder_Start接口重新进入Running状态。 738 739需要注意的是，如果编解码器特定数据以前已输入到解码器，则需要再次输入。 740 741**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 742 743**起始版本：** 9 744 745**参数:** 746 747| 名称 | 描述 | 748| -------- | -------- | 749| codec | 指向视频解码实例的指针。 | 750 751**返回：** 752 753返回接口结果： 754 755AV_ERR_OK：执行成功。 756 757AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 758 759AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 760 761AV_ERR_UNKNOWN：未知错误。 762 763AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 764 765AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 766 767 768### OH_VideoDecoder_QueryInputBuffer() 769 770``` 771OH_AVErrCode OH_VideoDecoder_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 772``` 773**描述** 774 775查询下一个可用输入缓冲区的索引。 776 777调用此接口后需要接着调用[OH_VideoDecoder_GetInputBuffer](#oh_videodecoder_getinputbuffer)接口获取缓冲区实例，并通过[OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer)接口传递给解码器。 778 779需要注意的是，上述操作仅在同步模式下支持。 780 781**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 782 783**起始版本：** 20 784 785**参数:** 786 787| 名称 | 描述 | 788| -------- | -------- | 789| codec | 指向视频解码实例的指针。 | 790| index | 输入buffer对应的索引值。| 791| timeoutUs | 超时时长，单位为微秒。负值：无限等待；0：立即退出；正值：等待指定时长后退出。 | 792 793**返回：** 794 795返回接口结果： 796 797AV_ERR_OK：执行成功。 798 799AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 800 801AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 802 803AV_ERR_UNKNOWN：未知错误。 804 805AV_ERR_SERVICE_DIED：编解码服务已终止。 806 807AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 808 809AV_ERR_OPERATE_NOT_PERMIT：禁止异步模式下使用。 810 811AV_ERR_TRY_AGAIN_LATER：查询失败，建议等待短暂间隔后重试。 812 813 814### OH_VideoDecoder_GetInputBuffer() 815 816``` 817OH_AVBuffer *OH_VideoDecoder_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index); 818``` 819**描述** 820 821获取可用输入缓冲区的实例。 822 823需要注意的是，此接口仅适用于同步模式。 824 825**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 826 827**起始版本：** 20 828 829**参数:** 830 831| 名称 | 描述 | 832| -------- | -------- | 833| codec | 指向视频解码实例的指针。 | 834| index | 输入buffer对应的索引值，可通过[OH_VideoDecoder_QueryInputBuffer](#oh_videodecoder_queryinputbuffer)接口获取。| 835 836**返回：** 837 838如果执行成功，则返回一个指向OH_AVBuffer实例的指针，否则返回NULL。 839 840 841### OH_VideoDecoder_QueryOutputBuffer() 842 843``` 844OH_AVErrCode OH_VideoDecoder_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 845``` 846**描述** 847 848查询下一个可用输出缓冲区的索引。 849 850通过[OH_VideoDecoder_GetOutputBuffer](#oh_videodecoder_getoutputbuffer)接口获取的缓冲区实例可以通过执行以下操作来显示或释放解码帧： 8511. 通过[OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer)接口将处理后的输出缓冲区返回到解码器。 8522. 通过[OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer)在输出surface上渲染。 8533. 通过[OH_VideoDecoder_RenderOutputBufferAtTime](#oh_videodecoder_renderoutputbufferattime)在指定时间内完成输出surface上渲染。 854 855需要注意的是，上述操作仅在同步模式下支持。 856 857**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 858 859**起始版本：** 20 860 861**参数:** 862 863| 名称 | 描述 | 864| -------- | -------- | 865| codec | 指向视频解码实例的指针。 | 866| index | 输出buffer对应的索引值。| 867| timeoutUs | 超时时长，单位为微秒。负值：无限等待；0：立即退出；正值：等待指定时长后退出。 | 868 869**返回：** 870 871返回接口结果： 872 873AV_ERR_OK：执行成功。 874 875AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 876 877AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 878 879AV_ERR_UNKNOWN：未知错误。 880 881AV_ERR_SERVICE_DIED：编解码服务已终止。 882 883AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 884 885AV_ERR_OPERATE_NOT_PERMIT：禁止异步模式下使用。 886 887AV_ERR_STREAM_CHANGED：流格式已变更，可以通过调用OH_VideoDecoder_GetOutputDescription接口获取新的流信息。 888 889AV_ERR_TRY_AGAIN_LATER：查询失败，建议等待短暂间隔后重试。 890 891 892### OH_VideoDecoder_GetOutputBuffer() 893 894``` 895OH_AVBuffer *OH_VideoDecoder_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index); 896``` 897**描述** 898 899获取可用输出缓冲区的实例。 900 901需要注意的是，此接口仅适用于同步模式。 902 903**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 904 905**起始版本：** 20 906 907**参数:** 908 909| 名称 | 描述 | 910| -------- | -------- | 911| codec | 指向视频解码实例的指针。 | 912| index | 输出buffer对应的索引值，可通过[OH_VideoDecoder_QueryOutputBuffer](#oh_videodecoder_queryoutputbuffer)接口获取。| 913 914**返回：** 915 916如果执行成功，则返回一个指向OH_AVBuffer实例的指针，否则返回NULL。 917 918 919## 废弃函数说明 920 921 922### OH_VideoDecoder_SetCallback() 923 924``` 925OH_AVErrCode OH_VideoDecoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData ) 926``` 927**描述** 928设置异步回调函数，让应用可以响应视频解码器生成的事件。在调用OH_VideoDecoder_Prepare接口之前，必须调用此接口。 929 930**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 931 932**起始版本：** 9 933 934**废弃版本：** 11 935 936**替代接口：**[OH_VideoDecoder_RegisterCallback](#oh_videodecoder_registercallback) 937 938**参数:** 939 940| 名称 | 描述 | 941| -------- | -------- | 942| codec | 指向视频解码实例的指针。 | 943| callback | 所有回调函数的集合，请参阅[OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md)。 | 944| userData | 开发者执行回调所依赖的数据。 | 945 946**返回：** 947 948返回接口结果： 949 950AV_ERR_OK：执行成功。 951 952AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 953 954AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 955 956AV_ERR_UNKNOWN：未知错误。 957 958AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 959 960AV_ERR_INVALID_STATE：本接口必须在OH_VideoDecoder_Prepare接口前调用，如果在其他状态时调用，则返回此错误码。 961 962 963### OH_VideoDecoder_RenderOutputData() 964 965``` 966OH_AVErrCode OH_VideoDecoder_RenderOutputData (OH_AVCodec *codec, uint32_t index ) 967``` 968**描述** 969将处理后的输出buffer返回给解码器，并通知解码器完成在输出surface上渲染buffer中包含的解码数据。 970 971如果之前没有配置输出surface，则调用此接口仅将指定index对应的输出缓冲区返回给解码器。 972 973**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 974 975**起始版本：** 9 976 977**废弃版本：** 11 978 979**替代接口：**[OH_VideoDecoder_RenderOutputBuffer](#oh_videodecoder_renderoutputbuffer) 980 981**参数:** 982 983| 名称 | 描述 | 984| -------- | -------- | 985| codec | 指向视频解码实例的指针。 | 986| index | 输出buffer对应的索引值。由[OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata)给出。 | 987 988**返回：** 989 990返回接口结果： 991 992AV_ERR_OK：执行成功。 993 994AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 995 996AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 997 998AV_ERR_UNKNOWN：未知错误。 999 1000AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 1001 1002AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 1003 1004 1005### OH_VideoDecoder_PushInputData() 1006 1007``` 1008OH_AVErrCode OH_VideoDecoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr ) 1009``` 1010**描述** 1011将填充数据的输入缓冲区提交给视频解码器。 1012 1013输入回调将报告可用的输入缓冲区和相应的index值，请参阅[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)。 一旦具有指定index的缓冲区提交到视频解码器，则无法再次访问缓冲区，直到再次收到输入回调，报告具有相同index的缓冲区可用。 1014 1015此外，对于某些解码器，需要在开始时向解码器输入编解码特定数据，以初始化解码器的解码过程，如H.264格式的PPS/SPS数据。 1016 1017**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 1018 1019**起始版本：** 9 1020 1021**废弃版本：** 11 1022 1023**替代接口：**[OH_VideoDecoder_PushInputBuffer](#oh_videodecoder_pushinputbuffer) 1024 1025**参数:** 1026 1027| 名称 | 描述 | 1028| -------- | -------- | 1029| codec | 指向视频解码实例的指针。 | 1030| index | 输入buffer对应的索引值。由[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)给出。 | 1031| attr | 描述缓冲区中包含的数据的信息。 | 1032 1033**返回：** 1034 1035返回接口结果： 1036 1037AV_ERR_OK：执行成功。 1038 1039AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 1040 1041AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 1042 1043AV_ERR_UNKNOWN：未知错误。 1044 1045AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 1046 1047AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 1048 1049 1050### OH_VideoDecoder_FreeOutputData() 1051 1052``` 1053OH_AVErrCode OH_VideoDecoder_FreeOutputData (OH_AVCodec *codec, uint32_t index ) 1054``` 1055**描述** 1056将处理后的输出缓冲区返回到解码器。 1057 1058**系统能力：** SystemCapability.Multimedia.Media.VideoDecoder 1059 1060**起始版本：** 9 1061 1062**废弃版本：** 11 1063 1064**替代接口：**[OH_VideoDecoder_FreeOutputBuffer](#oh_videodecoder_freeoutputbuffer) 1065 1066**参数:** 1067 1068| 名称 | 描述 | 1069| -------- | -------- | 1070| codec | 指向视频解码实例的指针。 | 1071| index | 输出buffer对应的索引值。由[OH_AVCodecOnNewOutputData](_codec_base.md#oh_avcodeconnewoutputdata)给出。 | 1072 1073**返回：** 1074 1075返回接口结果： 1076 1077AV_ERR_OK：执行成功。 1078 1079AV_ERR_NO_MEMORY：输入的解码器实例已经销毁。 1080 1081AV_ERR_INVALID_VAL：输入的codec指针为非解码器实例，或者为空指针。 1082 1083AV_ERR_UNKNOWN：未知错误。 1084 1085AV_ERR_OPERATE_NOT_PERMIT：内部执行错误。 1086 1087AV_ERR_INVALID_STATE：解码器状态不支持调用本接口时调用。 1088
