1# native_avcodec_audiocodec.h 2 3## Overview 4 5The file declares the native APIs used for audio encoding and decoding. 6 7**File to include**: <multimedia/player_framework/native_avcodec_audiocodec.h> 8 9**Library**: libnative_media_acodec.so 10 11**System capability**: SystemCapability.Multimedia.Media.AudioCodec 12 13**Since**: 11 14 15**Related module**: [AudioCodec](capi-audiocodec.md) 16 17**Sample**: [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) 18 19## Summary 20 21### Structs 22 23| Name| typedef Keyword| Description| 24| -- | -- | -- | 25| [MediaKeySession](capi-audiocodec-mediakeysession.md) | MediaKeySession | Describes the fields for MediaKeySession.| 26 27### Functions 28 29| Name| Description| 30| -- | -- | 31| [OH_AVCodec *OH_AudioCodec_CreateByMime(const char *mime, bool isEncoder)](#oh_audiocodec_createbymime) | Creates an audio codec instance based on a MIME type. This function is recommended in most cases.| 32| [OH_AVCodec *OH_AudioCodec_CreateByName(const char *name)](#oh_audiocodec_createbyname) | Creates an audio codec instance based on a codec name. To use this function, you must know the exact name of the codec.| 33| [OH_AVErrCode OH_AudioCodec_Destroy(OH_AVCodec *codec)](#oh_audiocodec_destroy) | Clears the internal resources of an audio codec and destroys the codec instance. | 34| [OH_AVErrCode OH_AudioCodec_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData)](#oh_audiocodec_registercallback) | 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**.| 35| [OH_AVErrCode OH_AudioCodec_Configure(OH_AVCodec *codec, const OH_AVFormat *format)](#oh_audiocodec_configure) | Configures the audio description. The audio codec is usually configured based on the audio description. This function must be called prior to **Prepare**.| 36| [OH_AVErrCode OH_AudioCodec_Prepare(OH_AVCodec *codec)](#oh_audiocodec_prepare) | Prepares internal resources for an audio codec. This function must be called after **Configure**.| 37| [OH_AVErrCode OH_AudioCodec_Start(OH_AVCodec *codec)](#oh_audiocodec_start) | Starts an audio codec after it is prepared successfully. After being started, the codec starts to report the **OH_AVCodecOnNeedInputBuffer** event.| 38| [OH_AVErrCode OH_AudioCodec_Stop(OH_AVCodec *codec)](#oh_audiocodec_stop) | Stops an audio codec. After 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.| 39| [OH_AVErrCode OH_AudioCodec_Flush(OH_AVCodec *codec)](#oh_audiocodec_flush) | Clears the input and output data in the internal buffer of an audio codec. This 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.| 40| [OH_AVErrCode OH_AudioCodec_Reset(OH_AVCodec *codec)](#oh_audiocodec_reset) | Resets an audio codec. To continue encoding or decoding, you must call **Configure** to configure the codec again. | 41| [OH_AVFormat *OH_AudioCodec_GetOutputDescription(OH_AVCodec *codec)](#oh_audiocodec_getoutputdescription) | Obtains the OH_AVFormat information about the output data of an audio codec.<br>You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to manually release the OH_AVFormat instance in the return value. | 42| [OH_AVErrCode OH_AudioCodec_SetParameter(OH_AVCodec *codec, const OH_AVFormat *format)](#oh_audiocodec_setparameter) | Sets dynamic parameters for an audio codec.<br>This function can be called only after the codec is started. Incorrect parameter settings may cause encoding or decoding failure. | 43| [OH_AVErrCode OH_AudioCodec_PushInputBuffer(OH_AVCodec *codec, uint32_t index)](#oh_audiocodec_pushinputbuffer) | Pushes the input buffer filled with data to an audio codec.<br>The [OH_AVCodecOnNeedInputBuffer](capi-native-avcodec-base-h.md#oh_avcodeconneedinputbuffer) callback reports the available input buffer and the index.<br>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](capi-native-avcodec-base-h.md#oh_avcodeconneedinputbuffer) callback.<br>In addition, some codecs require the input of codec-specific data to initialize the encoding or decoding process. | 44| [OH_AVErrCode OH_AudioCodec_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index)](#oh_audiocodec_freeoutputbuffer) | Frees an output buffer of an audio codec. | 45| [OH_AVErrCode OH_AudioCodec_IsValid(OH_AVCodec *codec, bool *isValid)](#oh_audiocodec_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. | 46| [OH_AVErrCode OH_AudioCodec_SetDecryptionConfig(OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureAudio)](#oh_audiocodec_setdecryptionconfig) | Sets the decryption information.| 47| [OH_AVErrCode OH_AudioCodec_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)](#oh_audiocodec_queryinputbuffer) | Obtains the index of an available input buffer for an audio codec within the specified timeout period.<br>After obtaining the index, call [OH_AudioCodec_GetInputBuffer](#oh_audiocodec_getinputbuffer) to obtain the buffer corresponding to the index.<br>After the buffer is filled, call [OH_AudioCodec_PushInputBuffer](#oh_audiocodec_pushinputbuffer) with the same index to push the buffer to the codec.<br>Note: This function can be used only in synchronous mode of the audio codec. | 48| [OH_AVBuffer *OH_AudioCodec_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index)](#oh_audiocodec_getinputbuffer) | Obtains the input buffer identified by **index** for an audio codec. Note: This function can be used only in synchronous mode of the audio codec.| 49| [OH_AVErrCode OH_AudioCodec_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)](#oh_audiocodec_queryoutputbuffer) | Obtains the index of an available output buffer for an audio codec within the specified timeout period. After obtaining the index, call [OH_AudioCodec_GetOutputBuffer](#oh_audiocodec_getoutputbuffer) to obtain the buffer corresponding to the index.<br>After the use, call [OH_AudioCodec_FreeOutputBuffer](#oh_audiocodec_freeoutputbuffer) to release the buffer. Once released, the buffer cannot be reused. Prolonged failure to release buffers will block the codec process. Note: This function can be used only in synchronous mode of the audio codec. | 50| [OH_AVBuffer *OH_AudioCodec_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index)](#oh_audiocodec_getoutputbuffer) | Obtains the output buffer identified by **index** for an audio codec. Note: This function can be used only in synchronous mode of the audio codec.| 51 52## Function Description 53 54### OH_AudioCodec_CreateByMime() 55 56``` 57OH_AVCodec *OH_AudioCodec_CreateByMime(const char *mime, bool isEncoder) 58``` 59 60**Description** 61 62Creates an audio codec instance based on a MIME type. This function is recommended in most cases. 63 64**System capability**: SystemCapability.Multimedia.Media.AudioCodec 65 66**Since**: 11 67 68 69**Parameters** 70 71| Name| Description| 72| -- | -- | 73| const char *mime | Pointer to a string that describes the MIME type. For details, see [AVCODEC_MIMETYPE](capi-native-avcodec-base-h.md#variables).| 74| bool isEncoder | The value **true** means to create an encoder, and **false** means to create a decoder.| 75 76**Returns** 77 78| Type| Description| 79| -- | -- | 80| [OH_AVCodec](capi-codecbase-oh-avcodec.md) * | Pointer to an OH_AVCodec instance.| 81 82### OH_AudioCodec_CreateByName() 83 84``` 85OH_AVCodec *OH_AudioCodec_CreateByName(const char *name) 86``` 87 88**Description** 89 90Creates an audio codec instance based on a codec name. To use this function, you must know the exact name of the codec, which can be obtained by calling [OH_AVCapability_GetName](capi-native-avcapability-h.md#oh_avcapability_getname). 91 92**System capability**: SystemCapability.Multimedia.Media.AudioCodec 93 94**Since**: 11 95 96 97**Parameters** 98 99| Name| Description| 100| -- | -- | 101| const char *name | Pointer to an audio codec name.| 102 103**Returns** 104 105| Type| Description| 106| -- | -- | 107| [OH_AVCodec](capi-codecbase-oh-avcodec.md) * | Pointer to an OH_AVCodec instance.| 108 109### OH_AudioCodec_Destroy() 110 111``` 112OH_AVErrCode OH_AudioCodec_Destroy(OH_AVCodec *codec) 113``` 114 115**Description** 116 117Clears the internal resources of an audio codec and destroys the codec instance. Do not repeatedly destroy the instance. Otherwise, the program may crash. 118 119**System capability**: SystemCapability.Multimedia.Media.AudioCodec 120 121**Since**: 11 122 123 124**Parameters** 125 126| Name| Description| 127| -- | -- | 128| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 129 130**Returns** 131 132| Type| Description| 133| -- | -- | 134| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The OH_AVCodec instance is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.<br>**AV_ERR_NO_MEMORY**: Internal resources have been released.<br>**AV_ERR_UNKNOWN**: An internal error occurs. You are advised to check logs.| 135 136### OH_AudioCodec_RegisterCallback() 137 138``` 139OH_AVErrCode OH_AudioCodec_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData) 140``` 141 142**Description** 143 144Sets an asynchronous callback so that your application can respond to events generated by an audio codec. This function must be called prior to **Prepare**. 145 146**System capability**: SystemCapability.Multimedia.Media.AudioCodec 147 148**Since**: 11 149 150 151**Parameters** 152 153| Name| Description| 154| -- | -- | 155| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 156| [OH_AVCodecCallback](_o_h___a_v_codec_callback.md) callback | Callback function to set. For details, see [OH_AVCodecCallback](capi-codecbase-oh-avcodeccallback.md).| 157| void *userData | User-specific data.| 158 159**Returns** 160 161| Type| Description| 162| -- | -- | 163| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: An input parameter is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.| 164 165### OH_AudioCodec_Configure() 166 167``` 168OH_AVErrCode OH_AudioCodec_Configure(OH_AVCodec *codec, const OH_AVFormat *format) 169``` 170 171**Description** 172 173Configures the audio description. The audio codec is usually configured based on the audio description. This function must be called prior to **Prepare**. 174 175**System capability**: SystemCapability.Multimedia.Media.AudioCodec 176 177**Since**: 11 178 179 180**Parameters** 181 182| Name| Description| 183| -- | -- | 184| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 185| [const OH_AVFormat](_core.md#oh_avformat) *format | Pointer to an OH_AVFormat instance, which provides the description information about the audio track to be encoded or decoded.| 186 187**Returns** 188 189| Type| Description| 190| -- | -- | 191| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: An input parameter is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. This may be because of incorrect state or unsupported operation.<br>**AV_ERR_UNKNOWN**: An internal error occurs. You are advised to check logs.| 192 193### OH_AudioCodec_Prepare() 194 195``` 196OH_AVErrCode OH_AudioCodec_Prepare(OH_AVCodec *codec) 197``` 198 199**Description** 200 201Prepares internal resources for an audio codec. This function must be called after **Configure**. 202 203**System capability**: SystemCapability.Multimedia.Media.AudioCodec 204 205**Since**: 11 206 207 208**Parameters** 209 210| Name| Description| 211| -- | -- | 212| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 213 214**Returns** 215 216| Type| Description| 217| -- | -- | 218| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The OH_AVCodec instance is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. This may be because of incorrect state or unsupported operation.<br>**AV_ERR_UNKNOWN**: An internal error occurs. You are advised to check logs.| 219 220### OH_AudioCodec_Start() 221 222``` 223OH_AVErrCode OH_AudioCodec_Start(OH_AVCodec *codec) 224``` 225 226**Description** 227 228Starts an audio codec after it is prepared successfully. After being started, the codec starts to report the **OH_AVCodecOnNeedInputBuffer** event. 229 230**System capability**: SystemCapability.Multimedia.Media.AudioCodec 231 232**Since**: 11 233 234 235**Parameters** 236 237| Name| Description| 238| -- | -- | 239| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 240 241**Returns** 242 243| Type| Description| 244| -- | -- | 245| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The OH_AVCodec instance is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. This may be because of incorrect state or unsupported operation.<br>**AV_ERR_UNKNOWN**: An internal error occurs. You are advised to check logs.| 246 247### OH_AudioCodec_Stop() 248 249``` 250OH_AVErrCode OH_AudioCodec_Stop(OH_AVCodec *codec) 251``` 252 253**Description** 254 255Stops an audio codec. After 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. 256 257**System capability**: SystemCapability.Multimedia.Media.AudioCodec 258 259**Since**: 11 260 261 262**Parameters** 263 264| Name| Description| 265| -- | -- | 266| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 267 268**Returns** 269 270| Type| Description| 271| -- | -- | 272| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The OH_AVCodec instance is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. This may be because of incorrect state or unsupported operation.<br>**AV_ERR_UNKNOWN**: An internal error occurs. You are advised to check logs.| 273 274### OH_AudioCodec_Flush() 275 276``` 277OH_AVErrCode OH_AudioCodec_Flush(OH_AVCodec *codec) 278``` 279 280**Description** 281 282Clears the input and output data in the internal buffer of an audio codec. This 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. 283 284**System capability**: SystemCapability.Multimedia.Media.AudioCodec 285 286**Since**: 11 287 288 289**Parameters** 290 291| Name| Description| 292| -- | -- | 293| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 294 295**Returns** 296 297| Type| Description| 298| -- | -- | 299| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The OH_AVCodec instance is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. This may be because of incorrect state or unsupported operation.<br>**AV_ERR_UNKNOWN**: An internal error occurs. You are advised to check logs.| 300 301### OH_AudioCodec_Reset() 302 303``` 304OH_AVErrCode OH_AudioCodec_Reset(OH_AVCodec *codec) 305``` 306 307**Description** 308 309Resets an audio codec. The configured parameters and input and output data are cleared. 310 311To continue encoding or decoding, you must call **Configure** to configure the codec again. 312 313**System capability**: SystemCapability.Multimedia.Media.AudioCodec 314 315**Since**: 11 316 317 318**Parameters** 319 320| Name| Description| 321| -- | -- | 322| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 323 324**Returns** 325 326| Type| Description| 327| -- | -- | 328| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The OH_AVCodec instance is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.| 329 330### OH_AudioCodec_GetOutputDescription() 331 332``` 333OH_AVFormat *OH_AudioCodec_GetOutputDescription(OH_AVCodec *codec) 334``` 335 336**Description** 337 338Obtains the OH_AVFormat information about the output data of an audio codec. 339 340You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to manually release the OH_AVFormat instance in the return value. 341 342**System capability**: SystemCapability.Multimedia.Media.AudioCodec 343 344**Since**: 11 345 346 347**Parameters** 348 349| Name| Description| 350| -- | -- | 351| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 352 353**Returns** 354 355| Type| Description| 356| -- | -- | 357| [OH_AVFormat](_core.md#oh_avformat) * | 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.| 358 359### OH_AudioCodec_SetParameter() 360 361``` 362OH_AVErrCode OH_AudioCodec_SetParameter(OH_AVCodec *codec, const OH_AVFormat *format) 363``` 364 365**Description** 366 367Sets dynamic parameters for an audio codec. 368 369This function can be called only after the codec is started. Incorrect parameter settings may cause encoding or decoding failure. 370 371**System capability**: SystemCapability.Multimedia.Media.AudioCodec 372 373**Since**: 11 374 375 376**Parameters** 377 378| Name| Description| 379| -- | -- | 380| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 381| [const OH_AVFormat](_core.md#oh_avformat) *format | Handle to an OH_AVFormat instance.| 382 383**Returns** 384 385| Type| Description| 386| -- | -- | 387| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: An input parameter is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. This may be because of incorrect state or unsupported operation.<br>**AV_ERR_UNKNOWN**: An internal error occurs. You are advised to check logs.| 388 389### OH_AudioCodec_PushInputBuffer() 390 391``` 392OH_AVErrCode OH_AudioCodec_PushInputBuffer(OH_AVCodec *codec, uint32_t index) 393``` 394 395**Description** 396 397Notifies the audio codec that the input data has been written to the buffer identified by **index**. 398 399The [OH_AVCodecOnNeedInputBuffer](capi-native-avcodec-base-h.md#oh_avcodeconneedinputbuffer) callback reports the available input buffer and the index. 400 401After being pushed to the codec, a buffer is not accessible until the buffer with the same index is reported again through the [OH_AVCodecOnNeedInputBuffer](capi-native-avcodec-base-h.md#oh_avcodeconneedinputbuffer) callback. 402 403In addition, some codecs require the input of codec-specific data to initialize the encoding or decoding process. 404 405Note: If the return value is **AV_ERR_UNKNOWN**, the call does not take effect, and the input buffer is still in the unprocessed state. You need to handle the error according to the specific error code and then call **OH_AudioCodec_PushInputBuffer**. 406 407**System capability**: SystemCapability.Multimedia.Media.AudioCodec 408 409**Since**: 11 410 411 412**Parameters** 413 414| Name| Description| 415| -- | -- | 416| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 417| uint32_t index | Index of the [OH_AVCodecOnNeedInputBuffer](capi-native-avcodec-base-h.md#oh_avcodeconneedinputbuffer).| 418 419**Returns** 420 421| Type| Description| 422| -- | -- | 423| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The input index is used or invalid. Use the index returned by the [OH_AVCodecOnNeedInputBuffer](capi-native-avcodec-base-h.md#oh_avcodeconneedinputbuffer) callback.<br>**AV_ERR_INVALID_STATE**: The codec state is incorrect. Before calling **OH_AudioCodec_PushInputBuffer**, ensure that [OH_AudioCodec_Configure](#oh_audiocodec_configure), [OH_AudioCodec_Prepare](#oh_audiocodec_prepare), and [OH_AudioCodec_Start](#oh_audiocodec_start) are successfully called in sequence.<br>**AV_ERR_UNKNOWN**: The input buffer size is invalid. Ensure that the buffer size and flags are correctly set.| 424 425### OH_AudioCodec_FreeOutputBuffer() 426 427``` 428OH_AVErrCode OH_AudioCodec_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index) 429``` 430 431**Description** 432 433Frees an output buffer of an audio codec. You need to call this function to release the output buffer in a timely manner. Otherwise, the encoding or decoding process is blocked. 434 435**System capability**: SystemCapability.Multimedia.Media.AudioCodec 436 437**Since**: 11 438 439 440**Parameters** 441 442| Name| Description| 443| -- | -- | 444| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 445| uint32_t index | Index of the [OH_AVCodecOnNewOutputBuffer](capi-native-avcodec-base-h.md#oh_avcodeconnewoutputbuffer).| 446 447**Returns** 448 449| Type| Description| 450| -- | -- | 451| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: An input parameter is nullptr or invalid. The buffer index is obtained from [OH_AVCodecOnNewOutputBuffer](capi-native-avcodec-base-h.md#oh_avcodeconnewoutputbuffer).<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation is not allowed. This may be because of incorrect state or unsupported operation.<br>**AV_ERR_UNKNOWN**: An internal error occurs. You are advised to check logs.| 452 453### OH_AudioCodec_IsValid() 454 455``` 456OH_AVErrCode OH_AudioCodec_IsValid(OH_AVCodec *codec, bool *isValid) 457``` 458 459**Description** 460 461Checks whether an audio codec instance is valid. 462 463This function is used to detect the codec status when a background fault is rectified or an application is switched from the background. 464 465**System capability**: SystemCapability.Multimedia.Media.AudioCodec 466 467**Since**: 11 468 469 470**Parameters** 471 472| Name| Description| 473| -- | -- | 474| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 475| bool *isValid | Pointer to an instance of the Boolean type. The value **true** means that the codec instance is valid, and **false** means the opposite.| 476 477**Returns** 478 479| Type| Description| 480| -- | -- | 481| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: An input parameter is nullptr or invalid.| 482 483### OH_AudioCodec_SetDecryptionConfig() 484 485``` 486OH_AVErrCode OH_AudioCodec_SetDecryptionConfig(OH_AVCodec *codec, MediaKeySession *mediaKeySession,bool secureAudio) 487``` 488 489**Description** 490 491Sets the decryption information. 492 493**System capability**: SystemCapability.Multimedia.Media.AudioCodec 494 495**Since**: 12 496 497 498**Parameters** 499 500| Name| Description| 501| -- | -- | 502| [OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 503| [MediaKeySession](capi-audiocodec-mediakeysession.md) *mediaKeySession | Pointer to the media key session with the decryption feature.| 504| bool secureAudio | Whether a secure decoder is used. **true** if used, **false** otherwise.<br>Currently, the secure decoder is not supported for audio decryption. | 505 506**Returns** 507 508| Type| Description| 509| -- | -- | 510| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The OH_AVCodec instance is nullptr or invalid, or the mediaKeySystemInfo instance is nullptr or invalid.<br>**AV_ERR_INVALID_STATE**: The decoding service is unavailable.| 511 512### OH_AudioCodec_QueryInputBuffer() 513 514``` 515OH_AVErrCode OH_AudioCodec_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs) 516``` 517 518**Description** 519 520Obtains the index of an available input buffer for an audio codec within the specified timeout period. 521 522After obtaining the index, call [OH_AudioCodec_GetInputBuffer](#oh_audiocodec_getinputbuffer) to obtain the buffer corresponding to the index. 523 524After the buffer is filled, call [OH_AudioCodec_PushInputBuffer](#oh_audiocodec_pushinputbuffer) with the same index to push the buffer to the codec. 525 526Note: This function can be used only in synchronous mode of the audio codec. 527 528**System capability**: SystemCapability.Multimedia.Media.AudioCodec 529 530**Since**: 20 531 532 533**Parameters** 534 535| Name| Description| 536| -- | -- | 537| [struct OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 538| uint32_t *index | Pointer to the index of the input buffer obtained.| 539| int64_t timeoutUs | Timeout period, in microseconds. A negative value means to wait infinitely.| 540 541**Returns** 542 543| Type| Description| 544| -- | -- | 545| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The operation fails due to incorrect input parameters.<br>**AV_ERR_INVALID_STATE**: The operation fails due to an invalid state, for example, the codec not being started.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation fails because the call is not allowed in asynchronous mode.<br>**AV_ERR_TRY_AGAIN_LATER**: The operation fails because no available buffer is obtained within the timeout period.| 546 547### OH_AudioCodec_GetInputBuffer() 548 549``` 550OH_AVBuffer *OH_AudioCodec_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index) 551``` 552 553**Description** 554 555Obtains the input buffer identified by **index** for an audio codec. Note: This function can be used only in synchronous mode of the audio codec. 556 557**System capability**: SystemCapability.Multimedia.Media.AudioCodec 558 559**Since**: 20 560 561 562**Parameters** 563 564| Name| Description| 565| -- | -- | 566| [struct OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 567| uint32_t index | Index of the input buffer. It is obtained by calling [OH_AudioCodec_QueryInputBuffer](#oh_audiocodec_queryinputbuffer).| 568 569**Returns** 570 571| Type| Description| 572| -- | -- | 573| OH_AVBuffer * | Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned.| 574 575### OH_AudioCodec_QueryOutputBuffer() 576 577``` 578OH_AVErrCode OH_AudioCodec_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs) 579``` 580 581**Description** 582 583Obtains the index of an available output buffer for an audio codec within the specified timeout period. 584 585After obtaining the index, call [OH_AudioCodec_GetOutputBuffer](#oh_audiocodec_getoutputbuffer) to obtain the buffer corresponding to the index. 586 587After the use, call [OH_AudioCodec_FreeOutputBuffer](#oh_audiocodec_freeoutputbuffer) to release the buffer. Once released, the buffer cannot be reused. Prolonged failure to release buffers will block the codec process. Note: This function can be used only in synchronous mode of the audio codec. 588 589**System capability**: SystemCapability.Multimedia.Media.AudioCodec 590 591**Since**: 20 592 593 594**Parameters** 595 596| Name| Description| 597| -- | -- | 598| [struct OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 599| uint32_t *index | Pointer to the index of the output buffer obtained.| 600| int64_t timeoutUs | Timeout period, in microseconds. A negative value means to wait infinitely.| 601 602**Returns** 603 604| Type| Description| 605| -- | -- | 606| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The operation fails due to incorrect input parameters.<br>**AV_ERR_INVALID_STATE**: The operation fails due to an invalid state, for example, the codec not being started.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The operation fails because the call is not allowed in asynchronous mode.<br>**AV_ERR_STREAM_CHANGED**: The format of the decoded output stream changes. You can call [OH_AudioCodec_GetOutputDescription](#oh_audiocodec_getoutputdescription) to obtain the new stream information.<br>**AV_ERR_TRY_AGAIN_LATER**: The operation fails because no available buffer is obtained within the timeout period.| 607 608### OH_AudioCodec_GetOutputBuffer() 609 610``` 611OH_AVBuffer *OH_AudioCodec_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index) 612``` 613 614**Description** 615 616Obtains the output buffer identified by **index** for an audio codec. 617 618Note: This function can be used only in synchronous mode of the audio codec. 619 620**System capability**: SystemCapability.Multimedia.Media.AudioCodec 621 622**Since**: 20 623 624 625**Parameters** 626 627| Name| Description| 628| -- | -- | 629| [struct OH_AVCodec](capi-codecbase-oh-avcodec.md) *codec | Pointer to an OH_AVCodec instance.| 630| uint32_t index | Index of the output buffer. It is obtained by calling [OH_AudioCodec_QueryOutputBuffer](#oh_audiocodec_queryoutputbuffer).| 631 632**Returns** 633 634| Type| Description| 635| -- | -- | 636| OH_AVBuffer * | Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned.| 637