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