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