1# AudioDecoder
2
3
4## 概述
5
6AudioDecoder模块提供用于音频解码功能的函数。
7
8**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
9
10**起始版本：** 9
11
12**废弃版本：** 11
13
14**替代建议：** 当前模块下的接口均已废弃，开发者可使用[AudioCodec](_audio_codec.md)完成对应功能开发，单个接口的替代关系可查阅具体的接口说明。
15
16
17## 汇总
18
19
20### 文件
21
22| 名称 | 描述 |
23| -------- | -------- |
24| [native_avcodec_audiodecoder.h](native__avcodec__audiodecoder_8h.md) | 声明用于音频解码的Native API。 |
25
26
27### 函数
28
29| 名称 | 描述 |
30| -------- | -------- |
31| OH_AVCodec \* [OH_AudioDecoder_CreateByMime](#oh_audiodecoder_createbymime) (const char \*mime) | 根据MIME类型创建音频解码器实例。 |
32| OH_AVCodec \* [OH_AudioDecoder_CreateByName](#oh_audiodecoder_createbyname) (const char \*name) | 通过音频解码器名称创建音频解码器实例。 |
33| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Destroy](#oh_audiodecoder_destroy) (OH_AVCodec \*codec) | 清理解码器内部资源，销毁解码器实例。 |
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) | 设置异步回调函数，使应用可以响应音频解码器生成的事件。 |
35| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Configure](#oh_audiodecoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | 要配置音频解码器，通常需要配置从容器中提取的音频描述信息。 |
36| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Prepare](#oh_audiodecoder_prepare) (OH_AVCodec \*codec) | 准备解码器的内部资源。 |
37| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Start](#oh_audiodecoder_start) (OH_AVCodec \*codec) | 调用此接口启动解码器，在Prepare成功后执行。 |
38| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Stop](#oh_audiodecoder_stop) (OH_AVCodec \*codec) | 停止解码器。 |
39| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Flush](#oh_audiodecoder_flush) (OH_AVCodec \*codec) | 清除解码器中缓存的输入和输出数据。 |
40| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_Reset](#oh_audiodecoder_reset) (OH_AVCodec \*codec) | 重置解码器。如果要继续解码，需要再次调用Configure接口配置解码器实例。 |
41| OH_AVFormat \* [OH_AudioDecoder_GetOutputDescription](#oh_audiodecoder_getoutputdescription) (OH_AVCodec \*codec) | 获取解码器输出数据的描述信息。 |
42| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_SetParameter](#oh_audiodecoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | 配置解码器的动态参数。 |
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) | 将填充有数据的输入缓冲区提交给音频解码器。 |
44| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_FreeOutputData](#oh_audiodecoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | 将处理后的输出缓冲区返回给解码器。 |
45| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AudioDecoder_IsValid](#oh_audiodecoder_isvalid) (OH_AVCodec \*codec, bool \*isValid) | 检查当前解码器实例是否有效，可用于后台故障恢复或应用程序从后台恢复时检测解码器有效状态。 |
46
47
48## 函数说明
49
50
51### OH_AudioDecoder_Configure()
52
53```
54OH_AVErrCode OH_AudioDecoder_Configure (OH_AVCodec *codec, OH_AVFormat *format)
55```
56
57**描述**
58
59要配置音频解码器，通常需要配置从容器中提取的音频描述信息。
60
61在调用Prepare之前，必须调用此接口。
62
63**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
64
65**起始版本：** 9
66
67**废弃版本：** 11
68
69**替代接口：**[OH_AudioCodec_Configure](_audio_codec.md#oh_audiocodec_configure)
70
71**参数:**
72
73| 名称 | 描述 |
74| -------- | -------- |
75| codec | 指向OH_AVCodec实例的指针。 |
76| format | 指向OH_AVFormat的指针，给出要解码的音频轨道的描述。 |
77
78**返回：**
79
80如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
81
82
83### OH_AudioDecoder_CreateByMime()
84
85```
86OH_AVCodec* OH_AudioDecoder_CreateByMime (const char *mime)
87```
88
89**描述**
90
91根据MIME类型创建音频解码器实例，大多数场景下建议使用此方式。
92
93**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
94
95**起始版本：** 9
96
97**废弃版本：** 11
98
99**替代接口：**[OH_AudioCodec_CreateByMime](_audio_codec.md#oh_audiocodec_createbymime)
100
101**参数:**
102
103| 名称 | 描述 |
104| -------- | -------- |
105| mime | MIME类型描述字符串，请参阅[AVCODEC_MIMETYPE](_codec_base.md#变量)。 |
106
107**返回：**
108
109返回指向OH_AVCodec实例的指针。
110
111
112### OH_AudioDecoder_CreateByName()
113
114```
115OH_AVCodec* OH_AudioDecoder_CreateByName (const char *name)
116```
117
118**描述**
119
120通过音频解码器名称创建音频解码器实例，使用此接口的前提是知道解码器的确切名称。
121
122**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
123
124**起始版本：** 9
125
126**废弃版本：** 11
127
128**替代接口：**[OH_AudioCodec_CreateByName](_audio_codec.md#oh_audiocodec_createbyname)
129
130**参数:**
131
132| 名称 | 描述 |
133| -------- | -------- |
134| name | 音频解码器名称。 |
135
136**返回：**
137
138返回指向OH_AVCodec实例的指针。
139
140
141### OH_AudioDecoder_Destroy()
142
143```
144OH_AVErrCode OH_AudioDecoder_Destroy (OH_AVCodec *codec)
145```
146
147**描述**
148
149清理解码器内部资源，销毁解码器实例。
150
151**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
152
153**起始版本：** 9
154
155**废弃版本：** 11
156
157**替代接口：**[OH_AudioCodec_Destroy](_audio_codec.md#oh_audiocodec_destroy)
158
159**参数:**
160
161| 名称 | 描述 |
162| -------- | -------- |
163| codec | 指向OH_AVCodec实例的指针。 |
164
165**返回：**
166
167如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
168
169
170### OH_AudioDecoder_Flush()
171
172```
173OH_AVErrCode OH_AudioDecoder_Flush (OH_AVCodec *codec)
174```
175
176**描述**
177
178清除解码器中缓存的输入和输出数据。
179
180调用此接口后，以前通过异步回调上报的所有缓冲区索引都将失效，请确保不要访问这些索引对应的缓冲区。
181
182**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
183
184**起始版本：** 9
185
186**废弃版本：** 11
187
188**替代接口：**[OH_AudioCodec_Flush](_audio_codec.md#oh_audiocodec_flush)
189
190**参数:**
191
192| 名称 | 描述 |
193| -------- | -------- |
194| codec | 指向OH_AVCodec实例的指针。 |
195
196**返回：**
197
198如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
199
200
201### OH_AudioDecoder_FreeOutputData()
202
203```
204OH_AVErrCode OH_AudioDecoder_FreeOutputData (OH_AVCodec *codec, uint32_t index)
205```
206
207**描述**
208
209将处理后的输出缓冲区返回给解码器。
210
211**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
212
213**起始版本：** 9
214
215**废弃版本：** 11
216
217**替代接口：**[OH_AudioCodec_FreeOutputBuffer](_audio_codec.md#oh_audiocodec_freeoutputbuffer)
218
219**参数:**
220
221| 名称 | 描述 |
222| -------- | -------- |
223| codec | 指向OH_AVCodec实例的指针。 |
224| index | 输出缓冲区Buffer对应的索引值。 |
225
226**返回：**
227
228如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
229
230
231### OH_AudioDecoder_GetOutputDescription()
232
233```
234OH_AVFormat* OH_AudioDecoder_GetOutputDescription (OH_AVCodec *codec)
235```
236
237**描述**
238
239获取解码器输出数据的描述信息。
240
241需要注意的是，返回值所指向的OH_AVFormat实例的生命周期需要调用者手动释放。
242
243**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
244
245**起始版本：** 9
246
247**废弃版本：** 11
248
249**替代接口：**[OH_AudioCodec_GetOutputDescription](_audio_codec.md#oh_audiocodec_getoutputdescription)
250
251**参数:**
252
253| 名称 | 描述 |
254| -------- | -------- |
255| codec | 指向OH_AVCodec实例的指针。 |
256
257**返回：**
258
259返回OH_AVFormat句柄指针，生命周期将使用下一个GetOutputDescription 刷新，或使用OH_AVCodec销毁。
260
261
262### OH_AudioDecoder_IsValid()
263
264```
265OH_AVErrCode OH_AudioDecoder_IsValid (OH_AVCodec *codec, bool *isValid)
266```
267
268**描述**
269
270检查当前解码器实例是否有效，可用于后台故障恢复或应用程序从后台恢复时检测解码器有效状态。
271
272**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
273
274**起始版本：** 10
275
276**废弃版本：** 11
277
278**替代接口：**[OH_AudioCodec_IsValid](_audio_codec.md#oh_audiocodec_isvalid)
279
280**参数:**
281
282| 名称 | 描述 |
283| -------- | -------- |
284| codec | 指向OH_AVCodec实例的指针。 |
285| isValid | 指向布尔类型的指针，true：解码器实例有效，false：解码器实例无效。 |
286
287**返回：**
288
289如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
290
291
292### OH_AudioDecoder_Prepare()
293
294```
295OH_AVErrCode OH_AudioDecoder_Prepare (OH_AVCodec *codec)
296```
297
298**描述**
299
300准备解码器的内部资源，在调用此接口之前必须调用Configure接口。
301
302**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
303
304**起始版本：** 9
305
306**废弃版本：** 11
307
308**替代接口：**[OH_AudioCodec_Prepare](_audio_codec.md#oh_audiocodec_prepare)
309
310**参数:**
311
312| 名称 | 描述 |
313| -------- | -------- |
314| codec | 指向OH_AVCodec实例的指针。 |
315
316**返回：**
317
318如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
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**描述**
328
329将填充有数据的输入缓冲区提交给音频解码器。
330
331[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)回调将报告可用的输入缓冲区和相应的索引值。一旦具有指定索引的缓冲区提交到音频解码器，则无法再次访问此缓冲区， 直到再次收到[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)回调，收到相同索引时此缓冲区才可使用。
332
333此外，对于某些解码器，需要在开始时向解码器输入特定配置参数，以初始化解码器的解码过程。
334
335**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
336
337**起始版本：** 9
338
339**废弃版本：** 11
340
341**替代接口：**[OH_AudioCodec_PushInputBuffer](_audio_codec.md#oh_audiocodec_pushinputbuffer)
342
343**参数:**
344
345| 名称 | 描述 |
346| -------- | -------- |
347| codec | 指向OH_AVCodec实例的指针。 |
348| index | 输入缓冲区Buffer对应的索引值。 |
349| attr | 描述缓冲区中包含的数据的信息。 |
350
351**返回：**
352
353如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
354
355
356### OH_AudioDecoder_Reset()
357
358```
359OH_AVErrCode OH_AudioDecoder_Reset (OH_AVCodec *codec)
360```
361
362**描述**
363
364重置解码器。如果要继续解码，需要再次调用Configure接口配置解码器实例。
365
366**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
367
368**起始版本：** 9
369
370**废弃版本：** 11
371
372**替代接口：**[OH_AudioCodec_Reset](_audio_codec.md#oh_audiocodec_reset)
373
374**参数:**
375
376| 名称 | 描述 |
377| -------- | -------- |
378| codec | 指向OH_AVCodec实例的指针。 |
379
380**返回：**
381
382如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
383
384
385### OH_AudioDecoder_SetCallback()
386
387```
388OH_AVErrCode OH_AudioDecoder_SetCallback (OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData)
389```
390
391**描述**
392
393设置异步回调函数，使应用可以响应音频解码器生成的事件。在调用Prepare之前，必须调用此接口。
394
395**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
396
397**起始版本：** 9
398
399**废弃版本：** 11
400
401**替代接口：**[OH_AudioCodec_RegisterCallback](_audio_codec.md#oh_audiocodec_registercallback)
402
403**参数:**
404
405| 名称 | 描述 |
406| -------- | -------- |
407| codec | 指向OH_AVCodec实例的指针。 |
408| callback | 所有回调函数的集合，请参阅 [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md)。 |
409| userData | 用户特定数据。 |
410
411**返回：**
412
413如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
414
415
416### OH_AudioDecoder_SetParameter()
417
418```
419OH_AVErrCode OH_AudioDecoder_SetParameter (OH_AVCodec *codec, OH_AVFormat *format)
420```
421
422**描述**
423
424配置解码器的动态参数。
425
426注意：该接口必须在解码器启动后才能调用。另外，参数配置错误可能会导致解码失败。
427
428**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
429
430**起始版本：** 9
431
432**废弃版本：** 11
433
434**替代接口：**[OH_AudioCodec_SetParameter](_audio_codec.md#oh_audiocodec_setparameter)
435
436**参数:**
437
438| 名称 | 描述 |
439| -------- | -------- |
440| codec | 指向OH_AVCodec实例的指针。 |
441| format | OH_AVFormat句柄指针。 |
442
443**返回：**
444
445如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
446
447
448### OH_AudioDecoder_Start()
449
450```
451OH_AVErrCode OH_AudioDecoder_Start (OH_AVCodec *codec)
452```
453
454**描述**
455
456调用此接口启动解码器，在Prepare成功后执行。启动后，解码器将开始上报OH_AVCodecOnNeedInputData事件。
457
458**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
459
460**起始版本：** 9
461
462**废弃版本：** 11
463
464**替代接口：**[OH_AudioCodec_Start](_audio_codec.md#oh_audiocodec_start)
465
466**参数:**
467
468| 名称 | 描述 |
469| -------- | -------- |
470| codec | 指向OH_AVCodec实例的指针。 |
471
472**返回：**
473
474如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
475
476
477### OH_AudioDecoder_Stop()
478
479```
480OH_AVErrCode OH_AudioDecoder_Stop (OH_AVCodec *codec)
481```
482
483**描述**
484
485停止解码器。
486
487停止后，您可以通过Start重新进入已启动状态，但需要注意的是， 如果解码器之前已输入数据，则需要重新输入解码器数据。
488
489**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder
490
491**起始版本：** 9
492
493**废弃版本：** 11
494
495**替代接口：**[OH_AudioCodec_Stop](_audio_codec.md#oh_audiocodec_stop)
496
497**参数:**
498
499| 名称 | 描述 |
500| -------- | -------- |
501| codec | 指向OH_AVCodec实例的指针。 |
502
503**返回：**
504
505如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅 [OH_AVErrCode](_core.md#oh_averrcode)。
506