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