• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# AudioDecoder
2
3
4## 概述
5
6AudioDecoder模块提供用于音频解码功能的函数。该模块在部分设备上可能不支持，可以通过[CanIUse](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/syscap.md)接口确认。
7
8@syscap SystemCapability.Multimedia.Media.AudioDecoder
9
10**起始版本：**
119
12
13## 汇总
14
15
16### 文件
17
18  | 名称 | 描述 |
19| -------- | -------- |
20| [native_avcodec_audiodecoder.h](native__avcodec__audiodecoder_8h.md) | 声明用于音频解码的Native API。<br>引用文件：<multimedia/player_framework/native_avcodec_audiodecoder.h>  |
21
22
23### 函数
24
25  | 名称 | 描述 |
26| -------- | -------- |
27| [OH_AudioDecoder_CreateByMime](#oh_audiodecoder_createbymime) (const char \*mime) | 通过mime类型创建一个音频解码器实例，大多数情况下推荐使用该接口。  |
28| [OH_AudioDecoder_CreateByName](#oh_audiodecoder_createbyname) (const char \*name) | 通过音频解码器名称创建一个音频解码器实例，使用这个接口的前提是必须清楚解码器准确的名称。  |
29| [OH_AudioDecoder_Destroy](#oh_audiodecoder_destroy) (OH_AVCodec \*codec) | 清空解码器内部资源，并销毁解码器实例  |
30| [OH_AudioDecoder_SetCallback](#oh_audiodecoder_setcallback) (OH_AVCodec \*codec, [OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) callback, void \*userData) | 设置异步回调函数，使得你的应用能够响应音频解码器产生的事件，该接口被调用必须是在Prepare被调用前。  |
31| [OH_AudioDecoder_Configure](#oh_audiodecoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | 配置音频解码器，典型地，需要配置被解码音频轨道的描述信息，这些信息能够从容器中提取出来， 该接口被调用必须是在Prepare被调用前。  |
32| [OH_AudioDecoder_Prepare](#oh_audiodecoder_prepare) (OH_AVCodec \*codec) | 准备解码器内部资源，调用该接口前必须先调用Configure接口。  |
33| [OH_AudioDecoder_Start](#oh_audiodecoder_start) (OH_AVCodec \*codec) | 启动解码器，该接口必须在已经Prepare成功后调用。 在启动成功后，解码器将开始报告[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)事件。  |
34| [OH_AudioDecoder_Stop](#oh_audiodecoder_stop) (OH_AVCodec \*codec) | 停止解码器。在停止后可通过Start重新进入Started状态，但需要注意的是，若先前给解码器输入过 Codec-Specific-Data，则需要重新输入。  |
35| [OH_AudioDecoder_Flush](#oh_audiodecoder_flush) (OH_AVCodec \*codec) | 清空解码器内部缓存的输入输出数据。在该接口被调用后，所有先前通过异步回调报告的Buffer的索引都将 失效，确保不要再访问这些索引对应的Buffers。  |
36| [OH_AudioDecoder_Reset](#oh_audiodecoder_reset) (OH_AVCodec \*codec) | 重置解码器。如需继续解码工作，需要重新调用Configure接口以配置该解码器实例。  |
37| [OH_AudioDecoder_GetOutputDescription](#oh_audiodecoder_getoutputdescription) (OH_AVCodec \*codec) | 获取该解码器输出数据的描述信息，需要注意的是，返回值所指向的OH_AVFormat实例需调用者手动释放。  |
38| [OH_AudioDecoder_SetParameter](#oh_audiodecoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | 向解码器设置动态参数，注意：该接口仅能在解码器被启动后调用，同时错误的参数设置，可能会导致解码失败。  |
39| [OH_AudioDecoder_PushInputData](#oh_audiodecoder_pushinputdata) (OH_AVCodec \*codec, uint32_t index, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) attr) | 将填充好数据的输入Buffer提交给音频解码器。[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)回调会报告可用的输入 Buffer及对应的索引值。一旦指定索引的Buffer被提交给解码器，直到再一次收到[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) 回调报告相同索引的Buffer可用前，该Buffer都不可以再次被访问。另外，对于部分解码器，要求在最开始给解码器输入 Codec-Specific-Data，用以初始化解码器的解码过程。  |
40| [OH_AudioDecoder_FreeOutputData](#oh_audiodecoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | 将处理结束的输出Buffer交还给解码器。  |
41
42
43## 函数说明
44
45
46### OH_AudioDecoder_Configure()
47
48
49```
50OH_AVErrCode OH_AudioDecoder_Configure (OH_AVCodec * codec, OH_AVFormat * format )
51```
52**描述:**
53配置音频解码器，典型地，需要配置被解码音频轨道的描述信息，这些信息能够从容器中提取出来， 该接口被调用必须是在Prepare被调用前。
54
55@syscap SystemCapability.Multimedia.Media.AudioDecoder
56
57**参数:**
58
59  | 名称 | 描述 |
60| -------- | -------- |
61| codec | 指向OH_AVCodec实例的指针  |
62| format | 指向OH_AVFormat的指针，用以给出待解码音频轨道的描述信息  |
63
64**返回:**
65
66执行成功返回AV_ERR_OK
67
68执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
69
70
71### OH_AudioDecoder_CreateByMime()
72
73
74```
75OH_AVCodec* OH_AudioDecoder_CreateByMime (const char * mime)
76```
77**描述:**
78通过mime类型创建一个音频解码器实例，大多数情况下推荐使用该接口。
79
80@syscap SystemCapability.Multimedia.Media.AudioDecoder
81
82**参数:**
83
84  | 名称 | 描述 |
85| -------- | -------- |
86| mime | mime类型描述字符串，参考[OH_AVCODEC_MIMETYPE_AUDIO_AAC](_codec_base.md#oh_avcodec_mimetype_audio_aac) |
87
88**返回:**
89
90返回一个指向OH_AVCodec实例的指针
91
92
93### OH_AudioDecoder_CreateByName()
94
95
96```
97OH_AVCodec* OH_AudioDecoder_CreateByName (const char * name)
98```
99**描述:**
100通过音频解码器名称创建一个音频解码器实例，使用这个接口的前提是必须清楚解码器准确的名称。
101
102@syscap SystemCapability.Multimedia.Media.AudioDecoder
103
104**参数:**
105
106  | 名称 | 描述 |
107| -------- | -------- |
108| name | 音频解码器名称  |
109
110**返回:**
111
112返回一个指向OH_AVCodec实例的指针
113
114
115### OH_AudioDecoder_Destroy()
116
117
118```
119OH_AVErrCode OH_AudioDecoder_Destroy (OH_AVCodec * codec)
120```
121**描述:**
122清空解码器内部资源，并销毁解码器实例
123
124@syscap SystemCapability.Multimedia.Media.AudioDecoder
125
126**参数:**
127
128  | 名称 | 描述 |
129| -------- | -------- |
130| codec | 指向OH_AVCodec实例的指针  |
131
132**返回:**
133
134执行成功返回AV_ERR_OK
135
136执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
137
138
139### OH_AudioDecoder_Flush()
140
141
142```
143OH_AVErrCode OH_AudioDecoder_Flush (OH_AVCodec * codec)
144```
145**描述:**
146清空解码器内部缓存的输入输出数据。在该接口被调用后，所有先前通过异步回调报告的Buffer的索引都将 失效，确保不要再访问这些索引对应的Buffers。
147
148@syscap SystemCapability.Multimedia.Media.AudioDecoder
149
150**参数:**
151
152  | 名称 | 描述 |
153| -------- | -------- |
154| codec | 指向OH_AVCodec实例的指针  |
155
156**返回:**
157
158执行成功返回AV_ERR_OK
159
160执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
161
162
163### OH_AudioDecoder_FreeOutputData()
164
165
166```
167OH_AVErrCode OH_AudioDecoder_FreeOutputData (OH_AVCodec * codec, uint32_t index )
168```
169**描述:**
170将处理结束的输出Buffer交还给解码器。
171
172@syscap SystemCapability.Multimedia.Media.AudioDecoder
173
174**参数:**
175
176  | 名称 | 描述 |
177| -------- | -------- |
178| codec | 指向OH_AVCodec实例的指针  |
179| index | 输出Buffer对应的索引值  |
180
181**返回:**
182
183执行成功返回AV_ERR_OK
184
185执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
186
187
188### OH_AudioDecoder_GetOutputDescription()
189
190
191```
192OH_AVFormat* OH_AudioDecoder_GetOutputDescription (OH_AVCodec * codec)
193```
194**描述:**
195获取该解码器输出数据的描述信息，需要注意的是，返回值所指向的OH_AVFormat实例需调用者手动释放。
196
197@syscap SystemCapability.Multimedia.Media.AudioDecoder
198
199**参数:**
200
201  | 名称 | 描述 |
202| -------- | -------- |
203| codec | 指向OH_AVCodec实例的指针  |
204
205**返回:**
206
207返回OH_AVFormat句柄指针，需调用者手动释放;
208
209
210### OH_AudioDecoder_Prepare()
211
212
213```
214OH_AVErrCode OH_AudioDecoder_Prepare (OH_AVCodec * codec)
215```
216**描述:**
217准备解码器内部资源，调用该接口前必须先调用Configure接口。
218
219@syscap SystemCapability.Multimedia.Media.AudioDecoder
220
221**参数:**
222
223  | 名称 | 描述 |
224| -------- | -------- |
225| codec | 指向OH_AVCodec实例的指针  |
226
227**返回:**
228
229执行成功返回AV_ERR_OK
230
231执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
232
233
234### OH_AudioDecoder_PushInputData()
235
236
237```
238OH_AVErrCode OH_AudioDecoder_PushInputData (OH_AVCodec * codec, uint32_t index, OH_AVCodecBufferAttr attr )
239```
240**描述:**
241将填充好数据的输入Buffer提交给音频解码器。[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)回调会报告可用的输入 Buffer及对应的索引值。一旦指定索引的Buffer被提交给解码器，直到再一次收到[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata) 回调报告相同索引的Buffer可用前，该Buffer都不可以再次被访问。另外，对于部分解码器，要求在最开始给解码器输入 Codec-Specific-Data，用以初始化解码器的解码过程。
242
243@syscap SystemCapability.Multimedia.Media.AudioDecoder
244
245**参数:**
246
247  | 名称 | 描述 |
248| -------- | -------- |
249| codec | 指向OH_AVCodec实例的指针  |
250| index | 输入Buffer对应的索引值  |
251| attr | 描述该Buffer内所包含数据的信息  |
252
253**返回:**
254
255执行成功返回AV_ERR_OK
256
257执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
258
259
260### OH_AudioDecoder_Reset()
261
262
263```
264OH_AVErrCode OH_AudioDecoder_Reset (OH_AVCodec * codec)
265```
266**描述:**
267重置解码器。如需继续解码工作，需要重新调用Configure接口以配置该解码器实例。
268
269@syscap SystemCapability.Multimedia.Media.AudioDecoder
270
271**参数:**
272
273  | 名称 | 描述 |
274| -------- | -------- |
275| codec | 指向OH_AVCodec实例的指针  |
276
277**返回:**
278
279执行成功返回AV_ERR_OK
280
281执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
282
283
284### OH_AudioDecoder_SetCallback()
285
286
287```
288OH_AVErrCode OH_AudioDecoder_SetCallback (OH_AVCodec * codec, OH_AVCodecAsyncCallback callback, void * userData )
289```
290**描述:**
291设置异步回调函数，使得你的应用能够响应音频解码器产生的事件，该接口被调用必须是在Prepare被调用前。
292
293@syscap SystemCapability.Multimedia.Media.AudioDecoder
294
295**参数:**
296
297  | 名称 | 描述 |
298| -------- | -------- |
299| codec | 指向OH_AVCodec实例的指针  |
300| callback | 一个包含所有回调函数的集合体，参考[OH_AVCodecAsyncCallback](_o_h___a_v_codec_async_callback.md) |
301| userData | 用户特定数据  |
302
303**返回:**
304
305执行成功返回AV_ERR_OK
306
307执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
308
309
310### OH_AudioDecoder_SetParameter()
311
312
313```
314OH_AVErrCode OH_AudioDecoder_SetParameter (OH_AVCodec * codec, OH_AVFormat * format )
315```
316**描述:**
317向解码器设置动态参数，注意：该接口仅能在解码器被启动后调用，同时错误的参数设置，可能会导致解码失败。
318
319@syscap SystemCapability.Multimedia.Media.AudioDecoder
320
321**参数:**
322
323  | 名称 | 描述 |
324| -------- | -------- |
325| codec | 指向OH_AVCodec实例的指针  |
326| format | OH_AVFormat句柄指针  |
327
328**返回:**
329
330执行成功返回AV_ERR_OK
331
332执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
333
334
335### OH_AudioDecoder_Start()
336
337
338```
339OH_AVErrCode OH_AudioDecoder_Start (OH_AVCodec * codec)
340```
341**描述:**
342启动解码器，该接口必须在已经Prepare成功后调用。 在启动成功后，解码器将开始报告[OH_AVCodecOnNeedInputData](_codec_base.md#oh_avcodeconneedinputdata)事件。
343
344@syscap SystemCapability.Multimedia.Media.AudioDecoder
345
346**参数:**
347
348  | 名称 | 描述 |
349| -------- | -------- |
350| codec | 指向OH_AVCodec实例的指针  |
351
352**返回:**
353
354执行成功返回AV_ERR_OK
355
356执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
357
358
359### OH_AudioDecoder_Stop()
360
361
362```
363OH_AVErrCode OH_AudioDecoder_Stop (OH_AVCodec * codec)
364```
365**描述:**
366停止解码器。在停止后可通过Start重新进入Started状态，但需要注意的是，若先前给解码器输入过 Codec-Specific-Data，则需要重新输入。
367
368@syscap SystemCapability.Multimedia.Media.AudioDecoder
369
370**参数:**
371
372  | 名称 | 描述 |
373| -------- | -------- |
374| codec | 指向OH_AVCodec实例的指针  |
375
376**返回:**
377
378执行成功返回AV_ERR_OK
379
380执行失败返回具体错误码，参考[OH_AVErrCode](_core.md#oh_averrcode)
381