1# AudioDecoder 2 3 4## Overview 5 6Provides the functions for audio decoding. This module may not be supported on some devices. You can call [CanIUse](../syscap.md) to check whether this module is supported on your device. 7 8@syscap SystemCapability.Multimedia.Media.AudioDecoder 9 10**Since** 119 12 13## Summary 14 15 16### Files 17 18 | Name| Description| 19| -------- | -------- | 20| [native_avcodec_audiodecoder.h](native__avcodec__audiodecoder_8h.md) | Declares the native APIs used for audio decoding.<br>File to include: <multimedia/player_framework/native_avcodec_audiodecoder.h> | 21 22 23### Functions 24 25 | Name| Description| 26| -------- | -------- | 27| [OH_AudioDecoder_CreateByMime](#oh_audiodecoder_createbymime) (const char \*mime) | Creates an audio decoder instance based on a Multipurpose Internet Mail Extension (MIME) type. This API is recommended in most cases. | 28| [OH_AudioDecoder_CreateByName](#oh_audiodecoder_createbyname) (const char \*name) | Creates an audio decoder instance based on an audio decoder name. To use this API, you must know the exact name of the audio decoder. | 29| [OH_AudioDecoder_Destroy](#oh_audiodecoder_destroy) (OH_AVCodec \*codec) | Clears the internal resources of an audio decoder and destroys the audio decoder instance. | 30| [OH_AudioDecoder_SetCallback](#oh_audiodecoder_setcallback) (OH_AVCodec \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | Sets an asynchronous callback so that your application can respond to events generated by an audio decoder. This API must be called prior to **Prepare**. | 31| [OH_AudioDecoder_Configure](#oh_audiodecoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | Configures an audio decoder. Typically, you need to configure the attributes, which can be extracted from the container, of the audio track that can be decoded. This API must be called prior to **Prepare**. | 32| [OH_AudioDecoder_Prepare](#oh_audiodecoder_prepare) (OH_AVCodec \*codec) | Prepares internal resources for an audio decoder. This API must be called after **Configure**. | 33| [OH_AudioDecoder_Start](#oh_audiodecoder_start) (OH_AVCodec \*codec) | Starts an audio decoder. This API can be called only after the decoder is prepared successfully. After being started, the decoder starts to report the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) event. | 34| [OH_AudioDecoder_Stop](#oh_audiodecoder_stop) (OH_AVCodec \*codec) | Stops an audio decoder. After the decoder is stopped, you can call **Start** to start it again. If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. | 35| [OH_AudioDecoder_Flush](#oh_audiodecoder_flush) (OH_AVCodec \*codec) | Clears the input and output data in the internal buffer of an audio decoder. This API invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this API, ensure that the buffers corresponding to the indexes are no longer required. | 36| [OH_AudioDecoder_Reset](#oh_audiodecoder_reset) (OH_AVCodec \*codec) | Resets an audio decoder. To continue decoding, you must call **Configure** and **Start** to configure and start the decoder again. | 37| [OH_AudioDecoder_GetOutputDescription](#oh_audiodecoder_getoutputdescription) (OH_AVCodec \*codec) | Obtains the attributes of the output data of an audio decoder. The caller must manually release the **OH_AVFormat** instance in the return value. | 38| [OH_AudioDecoder_SetParameter](#oh_audiodecoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | Sets dynamic parameters for an audio decoder. This API can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. | 39| [OH_AudioDecoder_PushInputData](#oh_audiodecoder_pushinputdata) (OH_AVCodec \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | Pushes the input buffer filled with data to an audio decoder. The [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback reports available input buffers and their indexes. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback. In addition, some decoders require the input of codec-specific data to initialize the decoding process. | 40| [OH_AudioDecoder_FreeOutputData](#oh_audiodecoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of an audio decoder. | 41 42 43## Function Description 44 45 46### OH_AudioDecoder_Configure() 47 48 49``` 50OH_AVErrCode OH_AudioDecoder_Configure (OH_AVCodec * codec, OH_AVFormat * format ) 51``` 52**Description**<br> 53Configures an audio decoder. Typically, you need to configure the attributes, which can be extracted from the container, of the audio track that can be decoded. This API must be called prior to **Prepare**. 54 55@syscap SystemCapability.Multimedia.Media.AudioDecoder 56 57**Parameters** 58 59 | Name| Description| 60| -------- | -------- | 61| codec | Indicates the pointer to an **OH_AVCodec** instance. | 62| format | Indicates the handle to an **OH_AVFormat** instance, which provides the attributes of the audio track to be decoded. | 63 64**Returns** 65 66Returns **AV_ERR_OK** if the operation is successful. 67 68Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 69 70 71### OH_AudioDecoder_CreateByMime() 72 73 74``` 75OH_AVCodec* OH_AudioDecoder_CreateByMime (const char * mime) 76``` 77**Description**<br> 78Creates an audio decoder instance based on a MIME type. This API is recommended in most cases. 79 80@syscap SystemCapability.Multimedia.Media.AudioDecoder 81 82**Parameters** 83 84 | Name| Description| 85| -------- | -------- | 86| mime | Indicates the pointer to a MIME type. For details, see [OH_AVCODEC_MIMETYPE_AUDIO_AAC](_codec_base.md#oh_avcodec_mimetype_audio_aac).| 87 88**Returns** 89 90Returns the pointer to an **OH_AVCodec** instance. 91 92 93### OH_AudioDecoder_CreateByName() 94 95 96``` 97OH_AVCodec* OH_AudioDecoder_CreateByName (const char * name) 98``` 99**Description**<br> 100Creates an audio decoder instance based on an audio decoder name. To use this API, you must know the exact name of the audio decoder. 101 102@syscap SystemCapability.Multimedia.Media.AudioDecoder 103 104**Parameters** 105 106 | Name| Description| 107| -------- | -------- | 108| name | Indicates the pointer to an audio decoder name. | 109 110**Returns** 111 112Returns the pointer to an **OH_AVCodec** instance. 113 114 115### OH_AudioDecoder_Destroy() 116 117 118``` 119OH_AVErrCode OH_AudioDecoder_Destroy (OH_AVCodec * codec) 120``` 121**Description**<br> 122Clears the internal resources of an audio decoder and destroys the audio decoder instance. 123 124@syscap SystemCapability.Multimedia.Media.AudioDecoder 125 126**Parameters** 127 128 | Name| Description| 129| -------- | -------- | 130| codec | Indicates the pointer to an **OH_AVCodec** instance. | 131 132**Returns** 133 134Returns **AV_ERR_OK** if the operation is successful. 135 136Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 137 138 139### OH_AudioDecoder_Flush() 140 141 142``` 143OH_AVErrCode OH_AudioDecoder_Flush (OH_AVCodec * codec) 144``` 145**Description**<br> 146Clears the input and output data in the internal buffer of an audio decoder. This API invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this API, ensure that the buffers corresponding to the indexes are no longer required. 147 148@syscap SystemCapability.Multimedia.Media.AudioDecoder 149 150**Parameters** 151 152 | Name| Description| 153| -------- | -------- | 154| codec | Indicates the pointer to an **OH_AVCodec** instance. | 155 156**Returns** 157 158Returns **AV_ERR_OK** if the operation is successful. 159 160Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 161 162 163### OH_AudioDecoder_FreeOutputData() 164 165 166``` 167OH_AVErrCode OH_AudioDecoder_FreeOutputData (OH_AVCodec * codec, uint32_t index ) 168``` 169**Description**<br> 170Frees an output buffer of an audio decoder. 171 172@syscap SystemCapability.Multimedia.Media.AudioDecoder 173 174**Parameters** 175 176 | Name| Description| 177| -------- | -------- | 178| codec | Indicates the pointer to an **OH_AVCodec** instance. | 179| index | Indicates the index of an output buffer. | 180 181**Returns** 182 183Returns **AV_ERR_OK** if the operation is successful. 184 185Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 186 187 188### OH_AudioDecoder_GetOutputDescription() 189 190 191``` 192OH_AVFormat* OH_AudioDecoder_GetOutputDescription (OH_AVCodec * codec) 193``` 194**Description**<br> 195Obtains the attributes of the output data of an audio decoder. The caller must manually release the **OH_AVFormat** instance in the return value. 196 197@syscap SystemCapability.Multimedia.Media.AudioDecoder 198 199**Parameters** 200 201 | Name| Description| 202| -------- | -------- | 203| codec | Indicates the pointer to an **OH_AVCodec** instance. | 204 205**Returns** 206 207Returns the handle to an **OH_AVFormat** instance, which must be manually released. 208 209 210### OH_AudioDecoder_Prepare() 211 212 213``` 214OH_AVErrCode OH_AudioDecoder_Prepare (OH_AVCodec * codec) 215``` 216**Description**<br> 217Prepares internal resources for an audio decoder. This API must be called after **Configure**. 218 219@syscap SystemCapability.Multimedia.Media.AudioDecoder 220 221**Parameters** 222 223 | Name| Description| 224| -------- | -------- | 225| codec | Indicates the pointer to an **OH_AVCodec** instance. | 226 227**Returns** 228 229Returns **AV_ERR_OK** if the operation is successful. 230 231Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 232 233 234### OH_AudioDecoder_PushInputData() 235 236 237``` 238OH_AVErrCode OH_AudioDecoder_PushInputData (OH_AVCodec * codec, uint32_t index, OH_AVCodecBufferAttr attr ) 239``` 240**Description**<br> 241Pushes the input buffer filled with data to an audio decoder. The [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback reports available input buffers and their indexes. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback. In addition, some decoders require the input of codec-specific data to initialize the decoding process. 242 243@syscap SystemCapability.Multimedia.Media.AudioDecoder 244 245**Parameters** 246 247 | Name| Description| 248| -------- | -------- | 249| codec | Indicates the pointer to an **OH_AVCodec** instance. | 250| index | Indicates the index of an input buffer. | 251| attr | Indicates the attributes of the data contained in the buffer. | 252 253**Returns** 254 255Returns **AV_ERR_OK** if the operation is successful. 256 257Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 258 259 260### OH_AudioDecoder_Reset() 261 262 263``` 264OH_AVErrCode OH_AudioDecoder_Reset (OH_AVCodec * codec) 265``` 266**Description**<br> 267Resets an audio decoder. To continue decoding, you must call **Configure** and **Start** to configure and start the decoder again. 268 269@syscap SystemCapability.Multimedia.Media.AudioDecoder 270 271**Parameters** 272 273 | Name| Description| 274| -------- | -------- | 275| codec | Indicates the pointer to an **OH_AVCodec** instance. | 276 277**Returns** 278 279Returns **AV_ERR_OK** if the operation is successful. 280 281Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 282 283 284### OH_AudioDecoder_SetCallback() 285 286 287``` 288OH_AVErrCode OH_AudioDecoder_SetCallback (OH_AVCodec * codec, OH_AVCodecAsyncCallback callback, void * userData ) 289``` 290**Description**<br> 291Sets an asynchronous callback so that your application can respond to events generated by an audio decoder. This API must be called prior to **Prepare**. 292 293@syscap SystemCapability.Multimedia.Media.AudioDecoder 294 295**Parameters** 296 297 | Name| Description| 298| -------- | -------- | 299| codec | Indicates the pointer to an **OH_AVCodec** instance. | 300| callback | Indicates a collection of all callback functions. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md).| 301| userData | Indicates the pointer to user-specific data. | 302 303**Returns** 304 305Returns **AV_ERR_OK** if the operation is successful. 306 307Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 308 309 310### OH_AudioDecoder_SetParameter() 311 312 313``` 314OH_AVErrCode OH_AudioDecoder_SetParameter (OH_AVCodec * codec, OH_AVFormat * format ) 315``` 316**Description**<br> 317Sets dynamic parameters for an audio decoder. This API can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. 318 319@syscap SystemCapability.Multimedia.Media.AudioDecoder 320 321**Parameters** 322 323 | Name| Description| 324| -------- | -------- | 325| codec | Indicates the pointer to an **OH_AVCodec** instance. | 326| format | Indicates the handle to an **OH_AVFormat** instance. | 327 328**Returns** 329 330Returns **AV_ERR_OK** if the operation is successful. 331 332Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 333 334 335### OH_AudioDecoder_Start() 336 337 338``` 339OH_AVErrCode OH_AudioDecoder_Start (OH_AVCodec * codec) 340``` 341**Description**<br> 342Starts an audio decoder. This API can be called only after the decoder is prepared successfully. After being started, the decoder starts to report the [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) event. 343 344@syscap SystemCapability.Multimedia.Media.AudioDecoder 345 346**Parameters** 347 348 | Name| Description| 349| -------- | -------- | 350| codec | Indicates the pointer to an **OH_AVCodec** instance. | 351 352**Returns** 353 354Returns **AV_ERR_OK** if the operation is successful. 355 356Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 357 358 359### OH_AudioDecoder_Stop() 360 361 362``` 363OH_AVErrCode OH_AudioDecoder_Stop (OH_AVCodec * codec) 364``` 365**Description**<br> 366Stops an audio decoder. After the decoder is stopped, you can call **Start** to start it again. If you have passed codec-specific data in the previous **Start** for the decoder, you must pass it again. 367 368@syscap SystemCapability.Multimedia.Media.AudioDecoder 369 370**Parameters** 371 372 | Name| Description| 373| -------- | -------- | 374| codec | Indicates the pointer to an **OH_AVCodec** instance. | 375 376**Returns** 377 378Returns **AV_ERR_OK** if the operation is successful. 379 380Returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) if the operation fails. 381