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