1# AudioEncoder 2 3## 概述 4 5AudioEncoder模块提供用于音频编码的函数。该模块在部分设备上可能不支持，可以通过[CanIUse](../syscap.md)接口确认。 6 7\@syscap SystemCapability.Multimedia.Media.AudioEncoder 8 9**起始版本：** 10 119 12 13## 汇总 14 15### 文件 16 17| 名称 | 描述 | 18| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | 19| [native_avcodec_audioencoder.h](native__avcodec__audioencoder_8h.md) | 声明用于音频编码的Native API。<br>**引用文件**：<multimedia/player_framework/native_avcodec_audioencoder.h><br>**库**：libnative_media_aenc.so | 20 21### 函数 22 23| 名称 | 描述 | 24| --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | 25| \*[OHOS::Media::OH_AudioEncoder_CreateByMime](#oh_audioencoder_createbymime) (const char \*mime) | 根据MIME类型创建音频编码器实例，大多数场景下建议使用此方式。 | 26| \*[OHOS::Media::OH_AudioEncoder_CreateByName](#oh_audioencoder_createbyname) (const char \*name) | 通过音频编码器名称创建音频编码器实例，使用此接口的前提是知道编码器的确切名称。 | 27| [OHOS::Media::OH_AudioEncoder_Destroy](#oh_audioencoder_destroy) (OH_AVCodec \*codec) | 清理编码器内部资源，销毁编码器实例。 | 28| [OHOS::Media::OH_AudioEncoder_SetCallback](#oh_audioencoder_setcallback) (OH_AVCodec \*codec, OH_AVCodecAsyncCallback callback, void \*userData) | 设置异步回调函数，使您的应用程序可以响应音频编码器生成的事件。 | 29| [OHOS::Media::OH_AudioEncoder_Configure](#oh_audioencoder_configure) (OH_AVCodec \*codec, OH_AVFormat \*format) | 要配置音频编码器，通常需要配置编码后的音轨的描述信息。 | 30| [OHOS::Media::OH_AudioEncoder_Prepare](#oh_audioencoder_prepare) (OH_AVCodec \*codec) | 准备编码器的内部资源，在调用此接口之前必须调用Configure接口。 | 31| [OHOS::Media::OH_AudioEncoder_Start](#oh_audioencoder_start) (OH_AVCodec \*codec) | Prepare成功后调用此接口启动编码器。 | 32| [OHOS::Media::OH_AudioEncoder_Stop](#oh_audioencoder_stop) (OH_AVCodec \*codec) | 停止编码器。 | 33| [OHOS::Media::OH_AudioEncoder_Flush](#oh_audioencoder_flush) (OH_AVCodec \*codec) | 清除编码器中缓存的输入和输出数据。 | 34| [OHOS::Media::OH_AudioEncoder_Reset](#oh_audioencoder_reset) (OH_AVCodec \*codec) | 重置编码器。 | 35| \*[OHOS::Media::OH_AudioEncoder_GetOutputDescription](#oh_audioencoder_getoutputdescription) (OH_AVCodec \*codec) | 获取编码器输出数据的描述信息，详细信息请参见[OH_AVFormat](native__avformat_8h.md)。 | 36| [OHOS::Media::OH_AudioEncoder_SetParameter](#oh_audioencoder_setparameter) (OH_AVCodec \*codec, OH_AVFormat \*format) | 配置编码器的动态参数。 | 37| [OHOS::Media::OH_AudioEncoder_PushInputData](#oh_audioencoder_pushinputdata) (OH_AVCodec \*codec, uint32_t index, OH_AVCodecBufferAttr attr) | 将填充有数据的输入缓冲区提交给音频编码器。 | 38| [OHOS::Media::OH_AudioEncoder_FreeOutputData](#oh_audioencoder_freeoutputdata) (OH_AVCodec \*codec, uint32_t index) | 将处理后的输出缓冲区返回给编码器。 | 39| [OHOS::Media::OH_AudioEncoder_IsValid](#oh_audioencoder_isvalid) (OH_AVCodec \*codec, bool \*isValid) | 检查当前编码器实例是否有效。 | 40 41## 函数说明 42 43### OH_AudioEncoder_Configure() 44 45``` 46OH_AVErrCode OHOS::Media::OH_AudioEncoder_Configure (OH_AVCodec * codec, OH_AVFormat * format ) 47``` 48 49**描述：** 50 51要配置音频编码器，通常需要配置编码后的音轨的描述信息。 52 53在调用Prepare之前，必须调用此接口。 54 55\@syscap SystemCapability.Multimedia.Media.AudioEncoder 56 57**参数：** 58 59| 名称 | 描述 | 60| ------ | --------------------------------------------------- | 61| codec | 指向OH_AVCodec实例的指针。 | 62| format | 指向OH_AVFormat的指针，给出要编码的音频轨道的描述。 | 63 64**返回：** 65 66如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 67 68**起始版本：** 69 709 71 72### OH_AudioEncoder_CreateByMime() 73 74``` 75OH_AVCodec* OHOS::Media::OH_AudioEncoder_CreateByMime (const char * mime) 76``` 77 78**描述：** 79 80根据MIME类型创建音频编码器实例，大多数场景下建议使用此方式。 81 82\@syscap SystemCapability.Multimedia.Media.AudioEncoder 83 84**参数：** 85 86| 名称 | 描述 | 87| ---- | ------------------------------------------------------- | 88| mime | MIME类型描述字符串，请参阅[AVCODEC_MIMETYPE](_codec_base.md#变量)。 | 89 90**返回：** 91 92返回指向OH_AVCodec实例的指针。 93 94**起始版本：** 95 969 97 98### OH_AudioEncoder_CreateByName() 99 100``` 101OH_AVCodec* OHOS::Media::OH_AudioEncoder_CreateByName (const char * name) 102``` 103 104**描述：** 105 106通过音频编码器名称创建音频编码器实例，使用此接口的前提是知道编码器的确切名称。 107 108\@syscap SystemCapability.Multimedia.Media.AudioEncoder 109 110**参数：** 111 112| 名称 | 描述 | 113| ---- | ---------------- | 114| name | 音频编码器名称。 | 115 116**返回：** 117 118返回指向OH_AVCodec实例的指针。 119 120**起始版本：** 121 1229 123 124### OH_AudioEncoder_Destroy() 125 126``` 127OH_AVErrCode OHOS::Media::OH_AudioEncoder_Destroy (OH_AVCodec * codec) 128``` 129 130**描述：** 131 132清理编码器内部资源，销毁编码器实例。 133 134\@syscap SystemCapability.Multimedia.Media.AudioEncoder 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 1489 149 150### OH_AudioEncoder_Flush() 151 152``` 153OH_AVErrCode OHOS::Media::OH_AudioEncoder_Flush (OH_AVCodec * codec) 154``` 155 156**描述：** 157 158清除编码器中缓存的输入和输出数据。 159 160调用此接口后，以前通过异步回调上报的所有缓冲区 索引都将失效，请确保不要访问这些索引对应的缓冲区。 161 162\@syscap SystemCapability.Multimedia.Media.AudioEncoder 163 164**参数：** 165 166| 名称 | 描述 | 167| ----- | -------------------------- | 168| codec | 指向OH_AVCodec实例的指针。 | 169 170**返回：** 171 172如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 173 174**起始版本：** 175 1769 177 178### OH_AudioEncoder_FreeOutputData() 179 180``` 181OH_AVErrCode OHOS::Media::OH_AudioEncoder_FreeOutputData (OH_AVCodec * codec, uint32_t index ) 182``` 183 184**描述：** 185 186将处理后的输出缓冲区返回给编码器。 187 188\@syscap SystemCapability.Multimedia.Media.AudioEncoder 189 190**参数：** 191 192| 名称 | 描述 | 193| ----- | ------------------------------ | 194| codec | 指向OH_AVCodec实例的指针。 | 195| index | 输出缓冲区Buffer对应的索引值。 | 196 197**返回：** 198 199如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 200 201**起始版本：** 202 2039 204 205### OH_AudioEncoder_GetOutputDescription() 206 207``` 208OH_AVFormat* OHOS::Media::OH_AudioEncoder_GetOutputDescription (OH_AVCodec * codec) 209``` 210 211**描述：** 212 213获取编码器输出数据的描述信息，详细信息请参见[OH_AVFormat](native__avformat_8h.md)。 214 215需要注意的是，返回值所指向的OH_AVFormat实例的生命周期需要调用者手动释放。 216 217\@syscap SystemCapability.Multimedia.Media.AudioEncoder 218 219**参数：** 220 221| 名称 | 描述 | 222| ----- | -------------------------- | 223| codec | 指向OH_AVCodec实例的指针。 | 224 225**返回：** 226 227返回OH_AVFormat句柄指针，生命周期将使用下一个GetOutputDescription 刷新，或使用OH_AVCodec销毁。 228 229**起始版本：** 230 2319 232 233### OH_AudioEncoder_IsValid() 234 235``` 236OH_AVErrCode OHOS::Media::OH_AudioEncoder_IsValid (OH_AVCodec * codec, bool * isValid ) 237``` 238 239**描述：** 240 241检查当前编码器实例是否有效。 242 243\@syscap SystemCapability.Multimedia.Media.AudioEncoder 244 245**参数：** 246 247| 名称 | 描述 | 248| ------- | ----------------------------------------------------------------- | 249| codec | 指向OH_AVCodec实例的指针。 | 250| isValid | 指向布尔实例的指针，true：编码器实例有效，false：编码器实例无效。 | 251 252**返回：** 253 254如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 255 256**起始版本：** 257 25810 259 260### OH_AudioEncoder_Prepare() 261 262``` 263OH_AVErrCode OHOS::Media::OH_AudioEncoder_Prepare (OH_AVCodec * codec) 264``` 265 266**描述：** 267 268准备编码器的内部资源，在调用此接口之前必须调用Configure接口。 269 270\@syscap SystemCapability.Multimedia.Media.AudioEncoder 271 272**参数：** 273 274| 名称 | 描述 | 275| ----- | -------------------------- | 276| codec | 指向OH_AVCodec实例的指针。 | 277 278**返回：** 279 280如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 281 282**起始版本：** 283 2849 285 286### OH_AudioEncoder_PushInputData() 287 288``` 289OH_AVErrCode OHOS::Media::OH_AudioEncoder_PushInputData (OH_AVCodec * codec, uint32_t index, OH_AVCodecBufferAttr attr ) 290``` 291 292**描述：** 293 294将填充有数据的输入缓冲区提交给音频编码器。 295 296**OH_AVCodecOnNeedInputData**回调 将报告可用的输入缓冲区和相应的索引值。一旦具有指定索引的缓冲区提交到音频编码器，则无法再次访问此缓冲区， 直到再次收到**OH_AVCodecOnNeedInputData**回调，收到相同索引时此缓冲区才可使用。 此外，对于某些编码器，需要在开始时向编码器输入特定配置参数，以初始化编码器的编码过程。 297 298\@syscap SystemCapability.Multimedia.Media.AudioEncoder 299 300**参数：** 301 302| 名称 | 描述 | 303| ----- | ------------------------------ | 304| codec | 指向OH_AVCodec实例的指针。 | 305| index | 输入缓冲区Buffer对应的索引值。 | 306| attr | 描述缓冲区中包含的数据的信息。 | 307 308**返回：** 309 310如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 311 312**起始版本：** 313 3149 315 316### OH_AudioEncoder_Reset() 317 318``` 319OH_AVErrCode OHOS::Media::OH_AudioEncoder_Reset (OH_AVCodec * codec) 320``` 321 322**描述：** 323 324重置编码器。如果要继续编码，需要再次调用Configure接口配置编码器实例。 325 326\@syscap SystemCapability.Multimedia.Media.AudioEncoder 327 328**参数：** 329 330| 名称 | 描述 | 331| ----- | -------------------------- | 332| codec | 指向OH_AVCodec实例的指针。 | 333 334**返回：** 335 336如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 337 338### OH_AudioEncoder_SetCallback() 339 340``` 341OH_AVErrCode OHOS::Media::OH_AudioEncoder_SetCallback (OH_AVCodec * codec, OH_AVCodecAsyncCallback callback, void * userData ) 342``` 343 344**描述：** 345 346设置异步回调函数，使您的应用程序可以响应音频编码器生成的事件。 347 348在调用Prepare之前，必须调用此接口。 349 350\@syscap SystemCapability.Multimedia.Media.AudioEncoder 351 352**参数：** 353 354| 名称 | 描述 | 355| -------- | ------------------------------------------------------------- | 356| codec | 指向OH_AVCodec实例的指针。 | 357| callback | 所有回调函数的集合，请参见**OH_AVCodecAsyncCallback**。 | 358| userData | 用户特定数据。 | 359 360**返回：** 361 362如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 363 364**起始版本：** 365 3669 367 368### OH_AudioEncoder_SetParameter() 369 370``` 371OH_AVErrCode OHOS::Media::OH_AudioEncoder_SetParameter (OH_AVCodec * codec, OH_AVFormat * format ) 372``` 373 374**描述：** 375 376配置编码器的动态参数。 377 378注意，该接口必须在编码器启动后才能调用。另外，参数配置错误可能会导致编码失败。 379 380\@syscap SystemCapability.Multimedia.Media.AudioEncoder 381 382**参数：** 383 384| 名称 | 描述 | 385| ------ | -------------------------- | 386| codec | 指向OH_AVCodec实例的指针。 | 387| format | OH_AVFormat句柄指针。 | 388 389**返回：** 390 391如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 392 393**起始版本：** 394 3959 396 397### OH_AudioEncoder_Start() 398 399``` 400OH_AVErrCode OHOS::Media::OH_AudioEncoder_Start (OH_AVCodec * codec) 401``` 402 403**描述：** 404 405Prepare成功后调用此接口启动编码器。 406 407启动后，编码器将开始上报OH_AVCodecOnNeedInputData事件。 408 409\@syscap SystemCapability.Multimedia.Media.AudioEncoder 410 411**参数：** 412 413| 名称 | 描述 | 414| ----- | -------------------------- | 415| codec | 指向OH_AVCodec实例的指针。 | 416 417**返回：** 418 419如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 420 421**起始版本：** 422 4239 424 425### OH_AudioEncoder_Stop() 426 427``` 428OH_AVErrCode OHOS::Media::OH_AudioEncoder_Stop (OH_AVCodec * codec) 429``` 430 431**描述：** 432 433停止编码器。停止后，您可以通过Start重新进入已启动状态。 434 435\@syscap SystemCapability.Multimedia.Media.AudioEncoder 436 437**参数：** 438 439| 名称 | 描述 | 440| ----- | -------------------------- | 441| codec | 指向OH_AVCodec实例的指针。 | 442 443**返回：** 444 445如果执行成功，则返回AV_ERR_OK，否则返回特定错误代码，请参阅[OH_AVErrCode](_core.md#oh_averrcode)。 446 447**起始版本：** 448 4499 450