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