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