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 Multipurpose Internet Mail Extension (MIME) 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 \*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. To continue encoding or decoding, you must call **Configure** to configure the codec again. |
42| 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 \*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) | Pushes the input buffer filled with data to an audio codec. |
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. To use this function, you must know the exact name of the codec.
114
115**System capability**: SystemCapability.Multimedia.Media.AudioCodec
116
117**Since**: 11
118
119**Parameters**
120
121| Name| Description|
122| -------- | -------- |
123| name | Pointer to an audio codec name.|
124
125**Returns**
126
127Returns the pointer to an **OH_AVCodec** instance.
128
129
130### OH_AudioCodec_Destroy()
131
132```
133OH_AVErrCode OH_AudioCodec_Destroy (OH_AVCodec *codec)
134```
135
136**Description**
137
138Clears the internal resources of an audio codec and destroys the codec instance.
139
140**System capability**: SystemCapability.Multimedia.Media.AudioCodec
141
142**Since**: 11
143
144**Parameters**
145
146| Name| Description|
147| -------- | -------- |
148| codec | Pointer to an **OH_AVCodec** instance. |
149
150**Returns**
151
152Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
153
154
155### OH_AudioCodec_Flush()
156
157```
158OH_AVErrCode OH_AudioCodec_Flush (OH_AVCodec *codec)
159```
160
161**Description**
162
163Clears the input and output data in the internal buffer of an audio codec.
164
165This 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.
166
167**System capability**: SystemCapability.Multimedia.Media.AudioCodec
168
169**Since**: 11
170
171**Parameters**
172
173| Name| Description|
174| -------- | -------- |
175| codec | Pointer to an **OH_AVCodec** instance.|
176
177**Returns**
178
179Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
180
181
182### OH_AudioCodec_FreeOutputBuffer()
183
184```
185OH_AVErrCode OH_AudioCodec_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index)
186```
187
188**Description**
189
190Frees an output buffer of an audio codec.
191
192**System capability**: SystemCapability.Multimedia.Media.AudioCodec
193
194**Since**: 11
195
196**Parameters**
197
198| Name| Description|
199| -------- | -------- |
200| codec | Pointer to an **OH_AVCodec** instance.|
201| index | Index of an output buffer.|
202
203**Returns**
204
205Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
206
207
208### OH_AudioCodec_GetOutputDescription()
209
210```
211OH_AVFormat* OH_AudioCodec_GetOutputDescription (OH_AVCodec *codec)
212```
213
214**Description**
215
216Obtains the description information about the output data of an audio codec.
217
218
219The caller must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to manually release the **OH_AVFormat** instance in the return value.
220
221**System capability**: SystemCapability.Multimedia.Media.AudioCodec
222
223**Since**: 11
224
225**Parameters**
226
227| Name| Description|
228| -------- | -------- |
229| codec | Pointer to an **OH_AVCodec** instance.|
230
231**Returns**
232
233Returns 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.
234
235
236### OH_AudioCodec_IsValid()
237
238```
239OH_AVErrCode OH_AudioCodec_IsValid (OH_AVCodec *codec, bool *isValid)
240```
241
242**Description**
243
244Checks 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.
245
246**System capability**: SystemCapability.Multimedia.Media.AudioCodec
247
248**Since**: 11
249
250**Parameters**
251
252| Name| Description|
253| -------- | -------- |
254| codec | Pointer to an **OH_AVCodec** instance.|
255| 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.|
256
257**Returns**
258
259Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
260
261
262### OH_AudioCodec_Prepare()
263
264```
265OH_AVErrCode OH_AudioCodec_Prepare (OH_AVCodec *codec)
266```
267
268**Description**
269
270Prepares internal resources for an audio codec. This function must be called after **Configure**.
271
272**System capability**: SystemCapability.Multimedia.Media.AudioCodec
273
274**Since**: 11
275
276**Parameters**
277
278| Name| Description|
279| -------- | -------- |
280| codec | Pointer to an **OH_AVCodec** instance.|
281
282**Returns**
283
284Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
285
286
287### OH_AudioCodec_PushInputBuffer()
288
289```
290OH_AVErrCode OH_AudioCodec_PushInputBuffer (OH_AVCodec *codec, uint32_t index)
291```
292
293**Description**
294
295Pushes the input buffer filled with data to an audio codec.
296
297The [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.
298
299In addition, some codecs require the input of codec-specific data to initialize the encoding or decoding process.
300
301**System capability**: SystemCapability.Multimedia.Media.AudioCodec
302
303**Since**: 11
304
305**Parameters**
306
307| Name| Description|
308| -------- | -------- |
309| codec | Pointer to an **OH_AVCodec** instance.|
310| index | Index of an input buffer.|
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_AudioCodec_RegisterCallback()
318
319```
320OH_AVErrCode OH_AudioCodec_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData)
321```
322
323**Description**
324
325Sets an asynchronous callback so that your application can respond to events generated by an audio codec. This function must be called prior to **Prepare**.
326
327**System capability**: SystemCapability.Multimedia.Media.AudioCodec
328
329**Since**: 11
330
331**Parameters**
332
333| Name| Description|
334| -------- | -------- |
335| codec | Pointer to an **OH_AVCodec** instance.|
336| callback | Callback function to set. For details, see [OH_AVCodecCallback](_o_h___a_v_codec_callback.md).|
337| userData | User-specific data.|
338
339**Returns**
340
341Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
342
343
344### OH_AudioCodec_Reset()
345
346```
347OH_AVErrCode OH_AudioCodec_Reset (OH_AVCodec *codec)
348```
349
350**Description**
351
352Resets an audio codec. To continue encoding or decoding, you must call **Configure** to configure the codec again.
353
354**System capability**: SystemCapability.Multimedia.Media.AudioCodec
355
356**Since**: 11
357
358**Parameters**
359
360| Name| Description|
361| -------- | -------- |
362| codec | Pointer to an **OH_AVCodec** instance. |
363
364**Returns**
365
366Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
367
368
369### OH_AudioCodec_SetDecryptionConfig()
370
371```
372OH_AVErrCode OH_AudioCodec_SetDecryptionConfig (OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureAudio)
373```
374
375**Description**
376
377Sets the decryption information.
378
379**System capability**: SystemCapability.Multimedia.Media.AudioCodec
380
381**Since**: 12
382
383**Parameters**
384
385| Name| Description|
386| -------- | -------- |
387| codec | Pointer to an **OH_AVCodec** instance. |
388| mediaKeySession | Pointer to the media key session with the decryption feature. |
389| 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. |
390
391**Returns**
392
393Returns a result code defined in [OH_AVErrCode](_core.md#oh_averrcode).
394
395**AV_ERR_OK** is returned if the operation is successful.
396
397**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.
398
399**AV_ERR_INVALID_STATE** if the decoder service is unavailable.
400
401
402### OH_AudioCodec_SetParameter()
403
404```
405OH_AVErrCode OH_AudioCodec_SetParameter (OH_AVCodec *codec, const OH_AVFormat *format)
406```
407
408**Description**
409
410Sets dynamic parameters for an audio codec.
411
412This function can be called only after the codec is started. Incorrect parameter settings may cause encoding or decoding failure.
413
414**System capability**: SystemCapability.Multimedia.Media.AudioCodec
415
416**Since**: 11
417
418**Parameters**
419
420| Name| Description|
421| -------- | -------- |
422| codec | Pointer to an **OH_AVCodec** instance.|
423| format | Handle to an **OH_AVFormat** instance.|
424
425**Returns**
426
427Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
428
429
430### OH_AudioCodec_Start()
431
432```
433OH_AVErrCode OH_AudioCodec_Start (OH_AVCodec *codec)
434```
435
436**Description**
437
438Starts an audio codec after it is prepared successfully. After being started, the codec starts to report the **OH_AVCodecOnNeedInputBuffer** event.
439
440**System capability**: SystemCapability.Multimedia.Media.AudioCodec
441
442**Since**: 11
443
444**Parameters**
445
446| Name| Description|
447| -------- | -------- |
448| codec | Pointer to an **OH_AVCodec** instance.|
449
450**Returns**
451
452Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
453
454
455### OH_AudioCodec_Stop()
456
457```
458OH_AVErrCode OH_AudioCodec_Stop (OH_AVCodec *codec)
459```
460
461**Description**
462
463Stops an audio codec.
464
465After 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.
466
467**System capability**: SystemCapability.Multimedia.Media.AudioCodec
468
469**Since**: 11
470
471**Parameters**
472
473| Name| Description|
474| -------- | -------- |
475| codec | Pointer to an **OH_AVCodec** instance.|
476
477**Returns**
478
479Returns **AV_ERR_OK** if the operation is successful; returns an error code defined in [OH_AVErrCode](_core.md#oh_averrcode) otherwise.
480