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