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