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