1# IAudioCapture 2 3 4## 概述 5 6音频接口的包路径。 7 8AudioCapture音频录音接口。 9 10提供音频录音支持的驱动能力，包括音频控制、音频属性、音频场景、音频音量、录制音频帧数据等。 11 12**起始版本：** 4.0 13 14**相关模块：**[HdiAudio](_hdi_audio_v11.md) 15 16 17## 汇总 18 19 20### Public 成员函数 21 22| 名称 | 描述 | 23| -------- | -------- | 24| [CaptureFrame](#captureframe) ([out] byte[] frame, [out] unsigned long replyBytes) | 从音频驱动中录制一帧输入数据（录音，音频上行数据）。 | 25| [GetCapturePosition](#getcaptureposition) ([out] unsigned long frames, [out] struct [AudioTimeStamp](_audio_time_stamp_v10.md) time) | Obtains the last number of input audio frames. | 26| [CheckSceneCapability](#checkscenecapability) ([in] struct [AudioSceneDescriptor](_audio_scene_descriptor_v10.md) scene, [out] boolean supported) | 判断某个音频场景能力是否支持。 | 27| [SelectScene](#selectscene) ([in] struct [AudioSceneDescriptor](_audio_scene_descriptor_v10.md) scene) | 选择音频场景。 | 28| [SetMute](#setmute) ([in] boolean mute) | 设置音频的静音状态。 | 29| [GetMute](#getmute) ([out] boolean mute) | 获取音频的静音状态。 | 30| [SetVolume](#setvolume) ([in] float volume) | 设置一个音频流的音量。 | 31| [GetVolume](#getvolume) ([out] float volume) | 获取一个音频流的音量。 | 32| [GetGainThreshold](#getgainthreshold) ([out] float min, [out] float max) | 获取音频流增益的阈值。 | 33| [GetGain](#getgain) ([out] float gain) | 获取音频流的增益。 | 34| [SetGain](#setgain) ([in] float gain) | 设置音频流的增益。 | 35| [GetFrameSize](#getframesize) ([out] unsigned long size) | 获取一帧音频数据的长度（字节数）大小。 | 36| [GetFrameCount](#getframecount) ([out] unsigned long count) | 获取音频buffer中的音频帧数。 | 37| [SetSampleAttributes](#setsampleattributes) ([in] struct [AudioSampleAttributes](_audio_sample_attributes_v10.md) attrs) | 设置音频采样的属性参数。 | 38| [GetSampleAttributes](#getsampleattributes) ([out] struct [AudioSampleAttributes](_audio_sample_attributes_v10.md) attrs) | 获取音频采样的属性参数。 | 39| [GetCurrentChannelId](#getcurrentchannelid) ([out] unsigned int channelId) | 获取音频的数据通道ID。 | 40| [SetExtraParams](#setextraparams) ([in] String keyValueList) | 设置音频拓展参数。 | 41| [GetExtraParams](#getextraparams) ([out] String keyValueList) | 获取音频拓展参数。 | 42| [ReqMmapBuffer](#reqmmapbuffer) ([in] int reqSize, [out] struct AudioMmapBufferDescriptor desc) | 请求mmap缓冲区。 | 43| [GetMmapPosition](#getmmapposition) ([out] unsigned long frames, [out] struct [AudioTimeStamp](_audio_time_stamp_v10.md) time) | 获取当前mmap的读/写位置。 | 44| [AddAudioEffect](#addaudioeffect) ([in] unsigned long effectid) | 添加音频效果。 | 45| [RemoveAudioEffect](#removeaudioeffect) ([in] unsigned long effectid) | 移除音频效果。 | 46| [GetFrameBufferSize](#getframebuffersize) ([out] unsigned long bufferSize) | 获取缓冲区大小。 | 47| [Start](#start) () | 启动一个音频播放或录音处理。 | 48| [Stop](#stop) () | 停止一个音频播放或录音处理。 | 49| [Pause](#pause) () | 暂停一个音频播放或录音处理。 | 50| [Resume](#resume) () | 恢复一个音频播放或录音处理。 | 51| [Flush](#flush) () | 刷新音频缓冲区buffer中的数据。 | 52| [TurnStandbyMode](#turnstandbymode) () | 设置或去设置设备的待机模式。 | 53| [AudioDevDump](#audiodevdump) ([in] int range, [in] int fd) | 保存音频设备信息。 | 54| [IsSupportsPauseAndResume](#issupportspauseandresume) ([out] boolean supportPause, [out] boolean supportResume) | 判断声卡是否支持音频录制的暂停和恢复功能。 | 55 56 57## 成员函数说明 58 59 60### AddAudioEffect() 61 62``` 63IAudioCapture::AddAudioEffect ([in] unsigned long effectid) 64``` 65 66**描述** 67 68添加音频效果。 69 70**起始版本：** 4.0 71 72**参数:** 73 74| 名称 | 描述 | 75| -------- | -------- | 76| effectid | 添加的音频效果实例标识符。 | 77 78**返回：** 79 80成功返回值0，失败返回负值。 81 82 83### AudioDevDump() 84 85``` 86IAudioCapture::AudioDevDump ([in] int range, [in] int fd ) 87``` 88 89**描述** 90 91保存音频设备信息。 92 93**起始版本：** 4.0 94 95**参数:** 96 97| 名称 | 描述 | 98| -------- | -------- | 99| range | 需要保存的信息范围（3 ~ 5），分为简要信息（3）、一般信息（4）、全量信息（5）。 | 100| fd | 保存到指定的目标文件。 | 101 102**返回：** 103 104成功返回值0，失败返回负值。 105 106 107### CaptureFrame() 108 109``` 110IAudioCapture::CaptureFrame ([out] byte[] frame, [out] unsigned long replyBytes ) 111``` 112 113**描述** 114 115从音频驱动中录制一帧输入数据（录音，音频上行数据）。 116 117**起始版本：** 4.0 118 119**参数:** 120 121| 名称 | 描述 | 122| -------- | -------- | 123| capture | 调用当前函数的IAudioCapture指针对象 | 124| frame | 待存放输入数据的音频frame。 | 125| requestBytes | 待存放输入数据的音频frame大小（字节数）。 | 126| replyBytes | 指向要读取的音频数据的实际长度（以字节为单位）的指针。 | 127 128**返回：** 129 130成功返回值0，失败返回负值。 131 132 133### CheckSceneCapability() 134 135``` 136IAudioCapture::CheckSceneCapability ([in] struct AudioSceneDescriptor scene, [out] boolean supported ) 137``` 138 139**描述** 140 141判断某个音频场景能力是否支持。 142 143**起始版本：** 4.0 144 145**参数:** 146 147| 名称 | 描述 | 148| -------- | -------- | 149| scene | 待判断的音频场景描述符，详请参考[AudioSceneDescriptor](_audio_scene_descriptor_v10.md)。 | 150| supported | 是否支持的状态保存到supported中，true表示支持，false表示不支持。 | 151 152**返回：** 153 154成功返回值0，失败返回负值。 155 156**参见：** 157 158[SelectScene](#selectscene) 159 160 161### Flush() 162 163``` 164IAudioCapture::Flush () 165``` 166 167**描述** 168 169刷新音频缓冲区buffer中的数据。 170 171**起始版本：** 4.0 172 173**返回：** 174 175成功返回值0，失败返回负值。 176 177 178### GetCapturePosition() 179 180``` 181IAudioCapture::GetCapturePosition ([out] unsigned long frames, [out] struct AudioTimeStamp time ) 182``` 183 184**描述** 185 186Obtains the last number of input audio frames. 187 188**起始版本：** 4.0 189 190**参数:** 191 192| 名称 | 描述 | 193| -------- | -------- | 194| capture | 调用当前函数的IAudioCapture指针对象 | 195| frames | 获取的音频帧数保存到frames中。 | 196| time | 获取的关联时间戳保存到time中，详请参考[AudioTimeStamp](_audio_time_stamp_v10.md)。 | 197 198**返回：** 199 200成功返回值0，失败返回负值。 201 202**参见：** 203 204[CaptureFrame](#captureframe) 205 206 207### GetCurrentChannelId() 208 209``` 210IAudioCapture::GetCurrentChannelId ([out] unsigned int channelId) 211``` 212 213**描述** 214 215获取音频的数据通道ID。 216 217**起始版本：** 4.0 218 219**参数:** 220 221| 名称 | 描述 | 222| -------- | -------- | 223| channelId | 获取的通道ID保存到channelId中。 | 224 225**返回：** 226 227成功返回值0，失败返回负值。 228 229 230### GetExtraParams() 231 232``` 233IAudioCapture::GetExtraParams ([out] String keyValueList) 234``` 235 236**描述** 237 238获取音频拓展参数。 239 240**起始版本：** 4.0 241 242**参数:** 243 244| 名称 | 描述 | 245| -------- | -------- | 246| keyValueList | 拓展参数键值对字符串列表，格式为key=value，多个键值对通过分号分割。 | 247 248**返回：** 249 250成功返回值0，失败返回负值。 251 252 253### GetFrameBufferSize() 254 255``` 256IAudioCapture::GetFrameBufferSize ([out] unsigned long bufferSize) 257``` 258 259**描述** 260 261获取缓冲区大小。 262 263**起始版本：** 4.0 264 265**参数:** 266 267| 名称 | 描述 | 268| -------- | -------- | 269| bufferSize | 获取的缓冲区大小保存在bufferSize中，单位为字节。 | 270 271**返回：** 272 273成功返回值0，失败返回负值。 274 275 276### GetFrameCount() 277 278``` 279IAudioCapture::GetFrameCount ([out] unsigned long count) 280``` 281 282**描述** 283 284获取音频buffer中的音频帧数。 285 286**起始版本：** 4.0 287 288**参数:** 289 290| 名称 | 描述 | 291| -------- | -------- | 292| count | 一个音频buffer中包含的音频帧数，获取后保存到count中。 | 293 294**返回：** 295 296成功返回值0，失败返回负值。 297 298 299### GetFrameSize() 300 301``` 302IAudioCapture::GetFrameSize ([out] unsigned long size) 303``` 304 305**描述** 306 307获取一帧音频数据的长度（字节数）大小。 308 309**起始版本：** 4.0 310 311**参数:** 312 313| 名称 | 描述 | 314| -------- | -------- | 315| size | 获取的音频帧大小（字节数）保存到size中。 | 316 317**返回：** 318 319成功返回值0，失败返回负值。 320 321 322### GetGain() 323 324``` 325IAudioCapture::GetGain ([out] float gain) 326``` 327 328**描述** 329 330获取音频流的增益。 331 332**起始版本：** 4.0 333 334**参数:** 335 336| 名称 | 描述 | 337| -------- | -------- | 338| gain | 保存当前获取到的增益到gain中。 | 339 340**返回：** 341 342成功返回值0，失败返回负值。 343 344**参见：** 345 346[GetGainThreshold](#getgainthreshold) 347 348[SetGain](#setgain) 349 350 351### GetGainThreshold() 352 353``` 354IAudioCapture::GetGainThreshold ([out] float min, [out] float max ) 355``` 356 357**描述** 358 359获取音频流增益的阈值。 360 361在具体的功能实现中，可以根据芯片平台的实际情况来进行处理： 362 363- 可以使用实际的增益值，例如增益的范围为-50db ~ 6db。 364 365- 也可以将增益范围设定为0.0~1.0，如果增益的范围为-50db ~ 6db， 则增益的映射关系为0.0表示静音（-50db），1.0表示最大增益（6db）。 366 367**起始版本：** 4.0 368 369**参数:** 370 371| 名称 | 描述 | 372| -------- | -------- | 373| min | 获取的音频增益的阈值下限保存到min中。 | 374| max | 获取的音频增益的阈值上限保存到max中。 | 375 376**返回：** 377 378成功返回值0，失败返回负值。 379 380**参见：** 381 382[GetGain](#getgain) 383 384[SetGain](#setgain) 385 386 387### GetMmapPosition() 388 389``` 390IAudioCapture::GetMmapPosition ([out] unsigned long frames, [out] struct AudioTimeStamp time ) 391``` 392 393**描述** 394 395获取当前mmap的读/写位置。 396 397**起始版本：** 4.0 398 399**参数:** 400 401| 名称 | 描述 | 402| -------- | -------- | 403| frames | 获取的音频帧计数保存到frames中。 | 404| time | 获取的关联时间戳保存到time中，详请参考[AudioTimeStamp](_audio_time_stamp_v10.md)。 | 405 406**返回：** 407 408成功返回值0，失败返回负值。 409 410 411### GetMute() 412 413``` 414IAudioCapture::GetMute ([out] boolean mute) 415``` 416 417**描述** 418 419获取音频的静音状态。 420 421**起始版本：** 4.0 422 423**参数:** 424 425| 名称 | 描述 | 426| -------- | -------- | 427| mute | 获取的静音状态保存到mute中，true表示静音操作、false表示取消静音操作。 | 428 429**返回：** 430 431成功返回值0，失败返回负值。 432 433**参见：** 434 435[SetMute](#setmute) 436 437 438### GetSampleAttributes() 439 440``` 441IAudioCapture::GetSampleAttributes ([out] struct AudioSampleAttributes attrs) 442``` 443 444**描述** 445 446获取音频采样的属性参数。 447 448**起始版本：** 4.0 449 450**参数:** 451 452| 名称 | 描述 | 453| -------- | -------- | 454| attrs | 获取的音频采样属性（例如采样频率、采样精度、通道）保存到attrs中，详请参考[AudioSampleAttributes](_audio_sample_attributes_v10.md)。 | 455 456**返回：** 457 458成功返回值0，失败返回负值。 459 460**参见：** 461 462[SetSampleAttributes](#setsampleattributes) 463 464 465### GetVolume() 466 467``` 468IAudioCapture::GetVolume ([out] float volume) 469``` 470 471**描述** 472 473获取一个音频流的音量。 474 475**起始版本：** 4.0 476 477**参数:** 478 479| 名称 | 描述 | 480| -------- | -------- | 481| volume | 获取的音量保存到volume中，范围0.0~1.0。 | 482 483**返回：** 484 485成功返回值0，失败返回负值。 486 487**参见：** 488 489[SetVolume](#setvolume) 490 491 492### IsSupportsPauseAndResume() 493 494``` 495IAudioCapture::IsSupportsPauseAndResume ([out] boolean supportPause, [out] boolean supportResume ) 496``` 497 498**描述** 499 500判断声卡是否支持音频录制的暂停和恢复功能。 501 502**起始版本：** 4.0 503 504**参数:** 505 506| 名称 | 描述 | 507| -------- | -------- | 508| supportPause | 是否支持暂停功能的状态保存到supportPause中，true表示支持，false表示不支持。 | 509| supportResume | 是否支持恢复功能的状态保存到supportResume中，true表示支持，false表示不支持。 | 510 511**返回：** 512 513成功返回值0，失败返回负值。 514 515 516### Pause() 517 518``` 519IAudioCapture::Pause () 520``` 521 522**描述** 523 524暂停一个音频播放或录音处理。 525 526**起始版本：** 4.0 527 528**返回：** 529 530成功返回值0，失败返回负值。 531 532**参见：** 533 534[Resume](#resume) 535 536 537### RemoveAudioEffect() 538 539``` 540IAudioCapture::RemoveAudioEffect ([in] unsigned long effectid) 541``` 542 543**描述** 544 545移除音频效果。 546 547**起始版本：** 4.0 548 549**参数:** 550 551| 名称 | 描述 | 552| -------- | -------- | 553| effectid | 移除的音频效果实例标识符。 | 554 555**返回：** 556 557成功返回值0，失败返回负值。 558 559 560### ReqMmapBuffer() 561 562``` 563IAudioCapture::ReqMmapBuffer ([in] int reqSize, [out] struct AudioMmapBufferDescriptor desc ) 564``` 565 566**描述** 567 568请求mmap缓冲区。 569 570**起始版本：** 4.0 571 572**参数:** 573 574| 名称 | 描述 | 575| -------- | -------- | 576| reqSize | 请求缓冲区的大小，单位：字节。 | 577| desc | 缓冲区描述符，详请参考[AudioMmapBufferDescripter](_audio_mmap_buffer_descripter_v10.md)。 | 578 579**返回：** 580 581成功返回值0，失败返回负值。 582 583 584### Resume() 585 586``` 587IAudioCapture::Resume () 588``` 589 590**描述** 591 592恢复一个音频播放或录音处理。 593 594**起始版本：** 4.0 595 596**返回：** 597 598成功返回值0，失败返回负值。 599 600**参见：** 601 602[Pause](#pause) 603 604 605### SelectScene() 606 607``` 608IAudioCapture::SelectScene ([in] struct AudioSceneDescriptor scene) 609``` 610 611**描述** 612 613选择音频场景。 614 615- 选择一个非常具体的音频场景（应用场景和输出设备的组合），例如同样是使用手机中的喇叭作为输出设备。 616 - 在媒体播放场景中，scene为media_speaker。 617 - 在语音通话免提场景中，scene为voice_speaker。 618 619- 只是选择一个音频场景，例如使用场景为媒体播放（media）、电影播放（movie）、游戏播放（game）。 620 621- 只是选择一个音频输出设备，例如输出设备为听筒（receiver）、喇叭（speaker）、有线耳机（headset）。 622 623**起始版本：** 4.0 624 625**参数:** 626 627| 名称 | 描述 | 628| -------- | -------- | 629| scene | 待设置的音频场景描述符，详请参考[AudioSceneDescriptor](_audio_scene_descriptor_v10.md)。 | 630 631**返回：** 632 633成功返回值0，失败返回负值。 634 635**参见：** 636 637[CheckSceneCapability](#checkscenecapability) 638 639 640### SetExtraParams() 641 642``` 643IAudioCapture::SetExtraParams ([in] String keyValueList) 644``` 645 646**描述** 647 648设置音频拓展参数。 649 650**起始版本：** 4.0 651 652**参数:** 653 654| 名称 | 描述 | 655| -------- | -------- | 656| keyValueList | 拓展参数键值对字符串列表，格式为key=value，多个键值对通过分号分割。 | 657 658**返回：** 659 660成功返回值0，失败返回负值。 661 662 663### SetGain() 664 665``` 666IAudioCapture::SetGain ([in] float gain) 667``` 668 669**描述** 670 671设置音频流的增益。 672 673**起始版本：** 4.0 674 675**参数:** 676 677| 名称 | 描述 | 678| -------- | -------- | 679| gain | 待设置的增益，最小为0.0，最大为1.0。 | 680 681**返回：** 682 683成功返回值0，失败返回负值。 684 685**参见：** 686 687[GetGainThreshold](#getgainthreshold) 688 689[GetGain](#getgain) 690 691 692### SetMute() 693 694``` 695IAudioCapture::SetMute ([in] boolean mute) 696``` 697 698**描述** 699 700设置音频的静音状态。 701 702**起始版本：** 4.0 703 704**参数:** 705 706| 名称 | 描述 | 707| -------- | -------- | 708| mute | 待设置的静音状态，true表示静音操作、false表示取消静音操作。 | 709 710**返回：** 711 712成功返回值0，失败返回负值。 713 714**参见：** 715 716[GetMute](#getmute) 717 718 719### SetSampleAttributes() 720 721``` 722IAudioCapture::SetSampleAttributes ([in] struct AudioSampleAttributes attrs) 723``` 724 725**描述** 726 727设置音频采样的属性参数。 728 729**起始版本：** 4.0 730 731**参数:** 732 733| 名称 | 描述 | 734| -------- | -------- | 735| attrs | 待设置的音频采样属性，例如采样频率、采样精度、通道，详请参考[AudioSampleAttributes](_audio_sample_attributes_v10.md)。 | 736 737**返回：** 738 739成功返回值0，失败返回负值。 740 741**参见：** 742 743[GetSampleAttributes](#getsampleattributes) 744 745 746### SetVolume() 747 748``` 749IAudioCapture::SetVolume ([in] float volume) 750``` 751 752**描述** 753 754设置一个音频流的音量。 755 756音量的取值范围是0.0~1.0，如果音频服务中的音量等级范围是0 ~ 15， 则音量的映射关系为0.0（或0）表示静音，1.0（或15）表示最大音量等级。 757 758**起始版本：** 4.0 759 760**参数:** 761 762| 名称 | 描述 | 763| -------- | -------- | 764| volume | 待设置的音量，范围0.0~1.0。 | 765 766**返回：** 767 768成功返回值0，失败返回负值。 769 770 771### Start() 772 773``` 774IAudioCapture::Start () 775``` 776 777**描述** 778 779启动一个音频播放或录音处理。 780 781**起始版本：** 4.0 782 783**返回：** 784 785成功返回值0，失败返回负值。 786 787**参见：** 788 789[Stop](#stop) 790 791 792### Stop() 793 794``` 795IAudioCapture::Stop () 796``` 797 798**描述** 799 800停止一个音频播放或录音处理。 801 802**起始版本：** 4.0 803 804**返回：** 805 806成功返回值0，失败返回负值。 807 808**参见：** 809 810[Start](#start) 811 812 813### TurnStandbyMode() 814 815``` 816IAudioCapture::TurnStandbyMode () 817``` 818 819**描述** 820 821设置或去设置设备的待机模式。 822 823**起始版本：** 4.0 824 825**返回：** 826 827设置设备待机模式成功返回值0，再次执行后去设置待机模式成功返回正值，失败返回负值。 828