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