1# AudioDecoder 2 3 4## Overview 5 6The AudioDecoder module provides the functions for audio decoding. 7 8**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 9 10**Since**: 9 11 12**Deprecated from**: 11 13 14**Development suggestions**: All APIs of the current module have been deprecated. You can use [AudioCodec](_audio_codec.md) instead. For details about the API mappings before and after the deprecation, see the API reference. 15 16 17## Summary 18 19 20### Files 21 22| Name| Description| 23| -------- | -------- | 24| [native_avcodec_audiodecoder.h](native__avcodec__audiodecoder_8h.md) | Declares the native APIs used for audio decoding.| 25 26 27### Functions 28 29| Name| Description| 30| -------- | -------- | 31| OH_AVCodec \* [OH_AudioDecoder_CreateByMime](#oh_audiodecoder_createbymime) (const char \*mime) | Creates an audio decoder instance based on a Multipurpose Internet Mail Extension (MIME) type.| 32| OH_AVCodec \* [OH_AudioDecoder_CreateByName](#oh_audiodecoder_createbyname) (const char \*name) | Creates an audio decoder instance based on a decoder name.| 33| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Destroy](#oh_audiodecoder_destroy) (OH_AVCodec \*codec) | Clears the internal resources of an audio decoder and destroys the decoder instance.| 34| [OH_AVErrCode](_core.md#oh_averrcode) [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.| 35| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Configure](#oh_audiodecoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | Configures an audio decoder. Typically, you need to configure the audio description information that can be extracted from the container.| 36| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Prepare](#oh_audiodecoder_prepare) (OH_AVCodec \*codec) | Prepares internal resources for an audio decoder.| 37| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Start](#oh_audiodecoder_start) (OH_AVCodec \*codec) | Starts an audio decoder after it is prepared successfully.| 38| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Stop](#oh_audiodecoder_stop) (OH_AVCodec \*codec) | Stops an audio decoder.| 39| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Flush](#oh_audiodecoder_flush) (OH_AVCodec \*codec) | Clears the input and output data in the internal buffer of an audio decoder.| 40| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Reset](#oh_audiodecoder_reset) (OH_AVCodec \*codec) | Resets an audio decoder. To continue decoding, you must call **Configure** to configure the decoder again.| 41| OH_AVFormat \* [OH_AudioDecoder_GetOutputDescription](#oh_audiodecoder_getoutputdescription) (OH_AVCodec \*codec) | Obtains the description information about the output data of an audio decoder.| 42| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_SetParameter](#oh_audiodecoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | Sets dynamic parameters for an audio decoder.| 43| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_PushInputData](#oh_audiodecoder_pushinputdata) (OH_AVCodec \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | Notifies the audio decoder that the input data has been written to the buffer identified by **index**.| 44| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_FreeOutputData](#oh_audiodecoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | Frees an output buffer of an audio decoder.| 45| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_IsValid](#oh_audiodecoder_isvalid) (OH_AVCodec \*codec, bool \*isValid) | Checks whether an audio decoder instance is valid. This function is used to check the decoder validity when the background recovers from a fault or an application is switched from the background.| 46 47 48## Function Description 49 50 51### OH_AudioDecoder_Configure() 52 53``` 54OH_AVErrCode OH_AudioDecoder_Configure (OH_AVCodec *codec, OH_AVFormat *format) 55``` 56 57**Description** 58 59Configures an audio decoder. Typically, you need to configure the audio description information that can be extracted from the container. 60 61This function must be called prior to **Prepare**. 62 63**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 64 65**Since**: 9 66 67**Deprecated from**: 11 68 69**Substitute**: [OH_AudioCodec_Configure](_audio_codec.md#oh_audiocodec_configure) 70 71**Parameters** 72 73| Name| Description| 74| -------- | -------- | 75| codec | Pointer to an OH_AVCodec instance.| 76| format | Pointer to the OH_AVFormat instance, which provides the description information about the audio track to be decoded.| 77 78**Returns** 79 80**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 81 82 83### OH_AudioDecoder_CreateByMime() 84 85``` 86OH_AVCodec* OH_AudioDecoder_CreateByMime (const char *mime) 87``` 88 89**Description** 90 91Creates an audio decoder instance based on a MIME type. This function is recommended in most cases. 92 93**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 94 95**Since**: 9 96 97**Deprecated from**: 11 98 99**Substitute**: [OH_AudioCodec_CreateByMime](_audio_codec.md#oh_audiocodec_createbymime) 100 101**Parameters** 102 103| Name| Description| 104| -------- | -------- | 105| mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](_codec_base.md#variables).| 106 107**Returns** 108 109Pointer to an OH_AVCodec instance. 110 111 112### OH_AudioDecoder_CreateByName() 113 114``` 115OH_AVCodec* OH_AudioDecoder_CreateByName (const char *name) 116``` 117 118**Description** 119 120Creates an audio decoder instance based on a decoder name. To use this function, you must know the exact name of the decoder. 121 122**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 123 124**Since**: 9 125 126**Deprecated from**: 11 127 128**Substitute**: [OH_AudioCodec_CreateByName](_audio_codec.md#oh_audiocodec_createbyname) 129 130**Parameters** 131 132| Name| Description| 133| -------- | -------- | 134| name | Pointer to an audio decoder name.| 135 136**Returns** 137 138Pointer to an OH_AVCodec instance. 139 140 141### OH_AudioDecoder_Destroy() 142 143``` 144OH_AVErrCode OH_AudioDecoder_Destroy (OH_AVCodec *codec) 145``` 146 147**Description** 148 149Clears the internal resources of an audio decoder and destroys the decoder instance. 150 151**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 152 153**Since**: 9 154 155**Deprecated from**: 11 156 157**Substitute**: [OH_AudioCodec_Destroy](_audio_codec.md#oh_audiocodec_destroy) 158 159**Parameters** 160 161| Name| Description| 162| -------- | -------- | 163| codec | Pointer to an OH_AVCodec instance.| 164 165**Returns** 166 167**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 168 169 170### OH_AudioDecoder_Flush() 171 172``` 173OH_AVErrCode OH_AudioDecoder_Flush (OH_AVCodec *codec) 174``` 175 176**Description** 177 178Clears the input and output data in the internal buffer of an audio decoder. 179 180This function invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this function, ensure that the buffers with the specified indexes are no longer required. 181 182**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 183 184**Since**: 9 185 186**Deprecated from**: 11 187 188**Substitute**: [OH_AudioCodec_Flush](_audio_codec.md#oh_audiocodec_flush) 189 190**Parameters** 191 192| Name| Description| 193| -------- | -------- | 194| codec | Pointer to an OH_AVCodec instance.| 195 196**Returns** 197 198**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 199 200 201### OH_AudioDecoder_FreeOutputData() 202 203``` 204OH_AVErrCode OH_AudioDecoder_FreeOutputData (OH_AVCodec *codec, uint32_t index) 205``` 206 207**Description** 208 209Frees an output buffer of an audio decoder. 210 211**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 212 213**Since**: 9 214 215**Deprecated from**: 11 216 217**Substitute**: [OH_AudioCodec_FreeOutputBuffer](_audio_codec.md#oh_audiocodec_freeoutputbuffer) 218 219**Parameters** 220 221| Name| Description| 222| -------- | -------- | 223| codec | Pointer to an OH_AVCodec instance.| 224| index | Index of the output buffer.| 225 226**Returns** 227 228**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 229 230 231### OH_AudioDecoder_GetOutputDescription() 232 233``` 234OH_AVFormat* OH_AudioDecoder_GetOutputDescription (OH_AVCodec *codec) 235``` 236 237**Description** 238 239Obtains the description information about the output data of an audio decoder. 240 241The caller must manually release the OH_AVFormat instance in the return value. 242 243**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 244 245**Since**: 9 246 247**Deprecated from**: 11 248 249**Substitute**: [OH_AudioCodec_GetOutputDescription](_audio_codec.md#oh_audiocodec_getoutputdescription) 250 251**Parameters** 252 253| Name| Description| 254| -------- | -------- | 255| codec | Pointer to an OH_AVCodec instance.| 256 257**Returns** 258 259Handle to an OH_AVFormat instance. The lifecycle of this instance is refreshed when **GetOutputDescription** is called again and destroyed when the OH_AVCodec instance is destroyed. 260 261 262### OH_AudioDecoder_IsValid() 263 264``` 265OH_AVErrCode OH_AudioDecoder_IsValid (OH_AVCodec *codec, bool *isValid) 266``` 267 268**Description** 269 270Checks whether an audio decoder instance is valid. This function is used to check the decoder validity when the background recovers from a fault or an application is switched from the background. 271 272**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 273 274**Since**: 10 275 276**Deprecated from**: 11 277 278**Substitute**: [OH_AudioCodec_IsValid](_audio_codec.md#oh_audiocodec_isvalid) 279 280**Parameters** 281 282| Name| Description| 283| -------- | -------- | 284| codec | Pointer to an OH_AVCodec instance.| 285| isValid | Pointer to an instance of the Boolean type. The value **true** means that the decoder instance is valid and **false** means the opposite.| 286 287**Returns** 288 289**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 290 291 292### OH_AudioDecoder_Prepare() 293 294``` 295OH_AVErrCode OH_AudioDecoder_Prepare (OH_AVCodec *codec) 296``` 297 298**Description** 299 300Prepares internal resources for an audio decoder. This function must be called after **Configure**. 301 302**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 303 304**Since**: 9 305 306**Deprecated from**: 11 307 308**Substitute**: [OH_AudioCodec_Prepare](_audio_codec.md#oh_audiocodec_prepare) 309 310**Parameters** 311 312| Name| Description| 313| -------- | -------- | 314| codec | Pointer to an OH_AVCodec instance.| 315 316**Returns** 317 318**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 319 320 321### OH_AudioDecoder_PushInputData() 322 323``` 324OH_AVErrCode OH_AudioDecoder_PushInputData (OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr) 325``` 326 327**Description** 328 329Notifies the audio decoder that the input data has been written to the buffer identified by **index**. 330 331The [OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) callback reports the available input buffer and the index. 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. 332 333In addition, some decoders require the input of specific data to initialize the decoding process. 334 335**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 336 337**Since**: 9 338 339**Deprecated from**: 11 340 341**Substitute**: [OH_AudioCodec_PushInputBuffer](_audio_codec.md#oh_audiocodec_pushinputbuffer) 342 343**Parameters** 344 345| Name| Description| 346| -------- | -------- | 347| codec | Pointer to an OH_AVCodec instance.| 348| index | Index of the input buffer.| 349| attr | Description information about the data in the buffer.| 350 351**Returns** 352 353**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 354 355 356### OH_AudioDecoder_Reset() 357 358``` 359OH_AVErrCode OH_AudioDecoder_Reset (OH_AVCodec *codec) 360``` 361 362**Description** 363 364Resets an audio decoder. To continue decoding, you must call **Configure** to configure the decoder again. 365 366**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 367 368**Since**: 9 369 370**Deprecated from**: 11 371 372**Substitute**: [OH_AudioCodec_Reset](_audio_codec.md#oh_audiocodec_reset) 373 374**Parameters** 375 376| Name| Description| 377| -------- | -------- | 378| codec | Pointer to an OH_AVCodec instance.| 379 380**Returns** 381 382**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 383 384 385### OH_AudioDecoder_SetCallback() 386 387``` 388OH_AVErrCode OH_AudioDecoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData) 389``` 390 391**Description** 392 393Sets an asynchronous callback so that your application can respond to events generated by an audio decoder. This function must be called prior to **Prepare**. 394 395**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 396 397**Since**: 9 398 399**Deprecated from**: 11 400 401**Substitute**: [OH_AudioCodec_RegisterCallback](_audio_codec.md#oh_audiocodec_registercallback) 402 403**Parameters** 404 405| Name| Description| 406| -------- | -------- | 407| codec | Pointer to an OH_AVCodec instance.| 408| callback | Callback function to set. For details, see [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md).| 409| userData | User-specific data.| 410 411**Returns** 412 413**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 414 415 416### OH_AudioDecoder_SetParameter() 417 418``` 419OH_AVErrCode OH_AudioDecoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format) 420``` 421 422**Description** 423 424Sets dynamic parameters for an audio decoder. 425 426This function can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. 427 428**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 429 430**Since**: 9 431 432**Deprecated from**: 11 433 434**Substitute**: [OH_AudioCodec_SetParameter](_audio_codec.md#oh_audiocodec_setparameter) 435 436**Parameters** 437 438| Name| Description| 439| -------- | -------- | 440| codec | Pointer to an OH_AVCodec instance.| 441| format | Handle to an OH_AVFormat instance.| 442 443**Returns** 444 445**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 446 447 448### OH_AudioDecoder_Start() 449 450``` 451OH_AVErrCode OH_AudioDecoder_Start (OH_AVCodec *codec) 452``` 453 454**Description** 455 456Starts an audio decoder after it is prepared successfully. After being started, the decoder starts to report the **OH_AVCodecOnNeedInputData** event. 457 458**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 459 460**Since**: 9 461 462**Deprecated from**: 11 463 464**Substitute**: [OH_AudioCodec_Start](_audio_codec.md#oh_audiocodec_start) 465 466**Parameters** 467 468| Name| Description| 469| -------- | -------- | 470| codec | Pointer to an OH_AVCodec instance.| 471 472**Returns** 473 474**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 475 476 477### OH_AudioDecoder_Stop() 478 479``` 480OH_AVErrCode OH_AudioDecoder_Stop (OH_AVCodec *codec) 481``` 482 483**Description** 484 485Stops an audio decoder. 486 487After the decoder is stopped, you can call **Start** to start it again. If you have passed specific data in the previous **Start** for the decoder, you must pass it again. 488 489**System capability**: SystemCapability.Multimedia.Media.AudioDecoder 490 491**Since**: 9 492 493**Deprecated from**: 11 494 495**Substitute**: [OH_AudioCodec_Stop](_audio_codec.md#oh_audiocodec_stop) 496 497**Parameters** 498 499| Name| Description| 500| -------- | -------- | 501| codec | Pointer to an OH_AVCodec instance.| 502 503**Returns** 504 505**AV_ERR_OK** if the operation is successful; an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise. 506