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