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