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