1# 音频组件<a name="ZH-CN_TOPIC_0000001146901937"></a> 2 3- [简介](#section119mcpsimp) 4 - [基本概念](#section122mcpsimp) 5 6- [目录](#section179mcpsimp) 7- [使用说明](#section112738505318) 8 - [音频播放](#section1147510562812) 9 - [音频录制](#section295162052813) 10 - [音频管理](#section645572311287) 11 - [音量控制](#section645572311287_001) 12 - [设备控制](#section645572311287_002) 13 - [音频场景](#section645572311287_003) 14 - [音频流管理](#section645572311287_004) 15 - [JavaScript 用法](#section645572311287_005) 16 - [铃声管理](#section645572311287_006) 17 - [蓝牙SCO呼叫](#section645572311287_007) 18- [支持设备](#section645572311287_008) 19- [相关仓](#section340mcpsimp) 20 21## 简介<a name="section119mcpsimp"></a> 22 23音频组件用于实现音频相关的功能，包括音频播放，录制，音量管理和设备管理。 24 25**图 1** 音频组件架构图<a name="fig483116248288"></a> 26 27 28 29 30### 基本概念<a name="section122mcpsimp"></a> 31 32- **采样** 33 34采样是指将连续时域上的模拟信号按照一定的时间间隔采样，获取到离散时域上离散信号的过程。 35 36- **采样率** 37 38采样率为每秒从连续信号中提取并组成离散信号的采样次数，单位用赫兹（Hz）来表示。通常人耳能听到频率范围大约在20Hz～20kHz之间的声音。常用的音频采样频率有：8kHz、11.025kHz、22.05kHz、16kHz、37.8kHz、44.1kHz、48kHz、96kHz、192kHz等。 39 40- **声道** 41 42声道是指声音在录制或播放时在不同空间位置采集或回放的相互独立的音频信号，所以声道数也就是声音录制时的音源数量或回放时相应的扬声器数量。 43 44- **音频帧** 45 46音频数据是流式的，本身没有明确的一帧帧的概念，在实际的应用中，为了音频算法处理/传输的方便，一般约定俗成取2.5ms\~60ms为单位的数据量为一帧音频。这个时间被称之为“采样时间”，其长度没有特别的标准，它是根据编解码器和具体应用的需求来决定的。 47 48- **PCM** 49 50PCM（Pulse Code Modulation），即脉冲编码调制，是一种将模拟信号数字化的方法，是将时间连续、取值连续的模拟信号转换成时间离散、抽样值离散的数字信号的过程。 51 52## 目录<a name="section179mcpsimp"></a> 53 54仓目录结构如下： 55 56``` 57/foundation/multimedia/audio_standard # 音频组件业务代码 58├── frameworks # 框架代码 59│ ├── native # 内部接口实现 60│ └── js # 外部接口实现 61│ └── napi # napi 外部接口实现 62├── interfaces # 接口代码 63│ ├── inner_api # 内部接口 64│ └── kits # 外部接口 65├── sa_profile # 服务配置文件 66├── services # 服务代码 67├── LICENSE # 证书文件 68└── ohos.build # 编译文件 69``` 70 71## 使用说明<a name="section112738505318"></a> 72 73### 音频播放<a name="section1147510562812"></a> 74 75可以使用此仓库内提供的接口将音频数据转换为音频模拟信号，使用输出设备播放音频信号，以及管理音频播放任务。以下步骤描述了如何使用 **AudioRenderer** 开发音频播放功能： 76 771. 使用 **Create** 接口和所需流类型来获取 **AudioRenderer** 实例。 78 79 ``` 80 AudioStreamType streamType = STREAM_MUSIC; // 流类型示例 81 std::unique_ptr<AudioRenderer> audioRenderer = AudioRenderer::Create(streamType); 82 ``` 83 842. （可选）静态接口 **GetSupportedFormats**(), **GetSupportedChannels**(), **GetSupportedEncodingTypes**(), **GetSupportedSamplingRates**() 可用于获取支持的参数。 853. 准备设备，调用实例的 **SetParams** 。 86 87 ``` 88 AudioRendererParams rendererParams; 89 rendererParams.sampleFormat = SAMPLE_S16LE; 90 rendererParams.sampleRate = SAMPLE_RATE_44100; 91 rendererParams.channelCount = STEREO; 92 rendererParams.encodingType = ENCODING_PCM; 93 94 audioRenderer->SetParams(rendererParams); 95 ``` 96 974. （可选）使用 audioRenderer->**GetParams**(rendererParams) 来验证 SetParams。 985. AudioRenderer 实例调用 audioRenderer->**Start**() 函数来启动播放任务。 996. 使用 **GetBufferSize** 接口获取要写入的缓冲区长度。 100 101 ``` 102 audioRenderer->GetBufferSize(bufferLen); 103 ``` 104 1057. 从源（例如音频文件）读取要播放的音频数据并将其传输到字节流中。重复调用Write函数写入渲染数据。 106 107 ``` 108 bytesToWrite = fread(buffer, 1, bufferLen, wavFile); 109 while ((bytesWritten < bytesToWrite) && ((bytesToWrite - bytesWritten) > minBytes)) { 110 bytesWritten += audioRenderer->Write(buffer + bytesWritten, bytesToWrite - bytesWritten); 111 if (bytesWritten < 0) 112 break; 113 } 114 ``` 115 1168. 调用audioRenderer->**Drain**()来清空播放流。 1179. 调用audioRenderer->**Stop**()来停止输出。 11810. 播放任务完成后，调用AudioRenderer实例的audioRenderer->**Release**()函数来释放资源。 119 120以上提供了基本音频播放使用场景。 121 122 12311. 使用 audioRenderer->**SetVolume(float)** 和 audioRenderer->**GetVolume()** 来设置和获取当前音频流音量, 可选范围为 0.0 到 1.0。 124 125提供上述基本音频播放使用范例。更多接口说明请参考[**audio_renderer.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiorenderer/include/audio_renderer.h) 和 [**audio_info.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiocommon/include/audio_info.h)。 126 127### 音频录制<a name="section295162052813"></a> 128 129可以使用此仓库内提供的接口，让应用程序可以完成使用输入设备进行声音录制，将语音转换为音频数据，并管理录制的任务。以下步骤描述了如何使用 **AudioCapturer** 开发音频录制功能： 130 1311. 使用Create接口和所需流类型来获取 **AudioCapturer** 实例。 132 133 ``` 134 AudioStreamType streamType = STREAM_MUSIC; 135 std::unique_ptr<AudioCapturer> audioCapturer = AudioCapturer::Create(streamType); 136 ``` 137 1382. （可选）静态接口 **GetSupportedFormats**(), **GetSupportedChannels**(), **GetSupportedEncodingTypes**(), **GetSupportedSamplingRates**() 可用于获取支持的参数。 1393. 准备设备，调用实例的 **SetParams** 。 140 141 ``` 142 AudioCapturerParams capturerParams; 143 capturerParams.sampleFormat = SAMPLE_S16LE; 144 capturerParams.sampleRate = SAMPLE_RATE_44100; 145 capturerParams.channelCount = STEREO; 146 capturerParams.encodingType = ENCODING_PCM; 147 148 audioCapturer->SetParams(capturerParams); 149 ``` 150 1514. （可选）使用 audioCapturer->**GetParams**(capturerParams) 来验证 SetParams()。 1525. AudioCapturer 实例调用 AudioCapturer->**Start**() 函数来启动录音任务。 1536. 使用 **GetBufferSize** 接口获取要写入的缓冲区长度。 154 155 ``` 156 audioCapturer->GetBufferSize(bufferLen); 157 ``` 158 1597. 读取录制的音频数据并将其转换为字节流。重复调用read函数读取数据直到主动停止。 160 161 ``` 162 // set isBlocking = true/false for blocking/non-blocking read 163 bytesRead = audioCapturer->Read(*buffer, bufferLen, isBlocking); 164 while (numBuffersToCapture) { 165 bytesRead = audioCapturer->Read(*buffer, bufferLen, isBlockingRead); 166 if (bytesRead < 0) { 167 break; 168 } else if (bytesRead > 0) { 169 fwrite(buffer, size, bytesRead, recFile); // example shows writes the recorded data into a file 170 numBuffersToCapture--; 171 } 172 } 173 ``` 174 1758. （可选）audioCapturer->**Flush**() 来清空录音流缓冲区。 1769. AudioCapturer 实例调用 audioCapturer->**Stop**() 函数停止录音。 17710. 录音任务完成后，调用 AudioCapturer 实例的 audioCapturer->**Release**() 函数释放资源。 178 179提供上述基本音频录制使用范例。更多API请参考[**audio_capturer.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiocapturer/include/audio_capturer.h)和[**audio_info.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiocommon/include/audio_info.h)。 180 181### 音频管理<a name="section645572311287"></a> 182可以使用 [**audio_system_manager.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiomanager/include/audio_system_manager.h) 内的接口来控制音量和设备。 1831. 使用 **GetInstance** 接口获取 **AudioSystemManager** 实例. 184 ``` 185 AudioSystemManager *audioSystemMgr = AudioSystemManager::GetInstance(); 186 ``` 187#### 音量控制<a name="section645572311287_001"></a> 1882. 使用 **GetMaxVolume** 和 **GetMinVolume** 接口去查询音频流支持的最大和最小音量等级，在此范围内设置音量。 189 ``` 190 AudioVolumeType streamType = AudioVolumeType::STREAM_MUSIC; 191 int32_t maxVol = audioSystemMgr->GetMaxVolume(streamType); 192 int32_t minVol = audioSystemMgr->GetMinVolume(streamType); 193 ``` 1943. 使用 **SetVolume** 和 **GetVolume** 接口来设置和获取指定音频流的音量等级。 195 ``` 196 int32_t result = audioSystemMgr->SetVolume(streamType, 10); 197 int32_t vol = audioSystemMgr->GetVolume(streamType); 198 ``` 1994. 使用 **SetMute** 和 **IsStreamMute** 接口来设置和获取指定音频流的静音状态。 200 ``` 201 int32_t result = audioSystemMgr->SetMute(streamType, true); 202 bool isMute = audioSystemMgr->IsStreamMute(streamType); 2035. 使用 **SetRingerMode** 和 **GetRingerMode** 接口来设置和获取铃声模式。参考在 [**audio_info.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiocommon/include/audio_info.h) 定义的 **AudioRingerMode** 枚举来获取支持的铃声模式。 204 ``` 205 int32_t result = audioSystemMgr->SetRingerMode(RINGER_MODE_SILENT); 206 AudioRingerMode ringMode = audioSystemMgr->GetRingerMode(); 207 ``` 2086. 使用 **SetMicrophoneMute** 和 **IsMicrophoneMute** 接口来设置和获取麦克风的静音状态。 209 ``` 210 int32_t result = audioSystemMgr->SetMicrophoneMute(true); 211 bool isMicMute = audioSystemMgr->IsMicrophoneMute(); 212 ``` 213#### 设备控制<a name="section645572311287_002"></a> 2147. 使用 **GetDevices**, **deviceType_** 和 **deviceRole_** 接口来获取音频输入输出设备信息。 参考 [**audio_info.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiocommon/include/audio_info.h) 内定义的DeviceFlag, DeviceType 和 DeviceRole 枚举。 215 ``` 216 DeviceFlag deviceFlag = OUTPUT_DEVICES_FLAG; 217 vector<sptr<AudioDeviceDescriptor>> audioDeviceDescriptors 218 = audioSystemMgr->GetDevices(deviceFlag); 219 sptr<AudioDeviceDescriptor> audioDeviceDescriptor = audioDeviceDescriptors[0]; 220 cout << audioDeviceDescriptor->deviceType_; 221 cout << audioDeviceDescriptor->deviceRole_; 222 ``` 2238. 使用 **SetDeviceActive** 和 **IsDeviceActive** 接口去激活/去激活音频设备和获取音频设备激活状态。 224 ``` 225 ActiveDeviceType deviceType = SPEAKER; 226 int32_t result = audioSystemMgr->SetDeviceActive(deviceType, true); 227 bool isDevActive = audioSystemMgr->IsDeviceActive(deviceType); 228 ``` 2299. 提供其他用途的接口如 **IsStreamActive**, **SetAudioParameter** and **GetAudioParameter**, 详细请参考 [**audio_system_manager.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiomanager/include/audio_system_manager.h) 23010. 应用程序可以使用 **AudioManagerNapi::On**注册系统音量的更改。 在此，如果应用程序监听到系统音量更改的事件,就会用以下参数通知应用程序: 231volumeType : 更改的系统音量的类型 232volume : 当前的音量等级 233updateUi : 是否需要显示变化详细信息。（如果音量被增大/减小，将updateUi标志设置为true，在其他情况下，updateUi设置为false）。 234 ``` 235 const audioManager = audio.getAudioManager(); 236 237 export default { 238 onCreate() { 239 audioManager.on('volumeChange', (volumeChange) ==> { 240 console.info('volumeType = '+volumeChange.volumeType); 241 console.info('volume = '+volumeChange.volume); 242 console.info('updateUi = '+volumeChange.updateUi); 243 } 244 } 245 } 246 ``` 247 248#### 音频场景<a name="section645572311287_003"></a> 24911. 使用 **SetAudioScene** 和 **getAudioScene** 接口去更改和检查音频策略。 250 ``` 251 int32_t result = audioSystemMgr->SetAudioScene(AUDIO_SCENE_PHONE_CALL); 252 AudioScene audioScene = audioSystemMgr->GetAudioScene(); 253 ``` 254有关支持的音频场景，请参阅 **AudioScene** 中的枚举[**audio_info.h**](https://gitee.com/openharmony/multimedia_audio_framework/blob/master/interfaces/inner_api/native/audiocommon/include/audio_info.h)。 255#### 音频流管理<a name="section645572311287_004"></a> 256可以使用[**audio_stream_manager.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiomanager/include/audio_stream_manager.h)提供的接口用于流管理功能。 2571. 使用 **GetInstance** 接口获得 **AudioSystemManager** 实例。 258 ``` 259 AudioStreamManager *audioStreamMgr = AudioStreamManager::GetInstance(); 260 ``` 261 2622. 使用 **RegisterAudioRendererEventListener** 为渲染器状态更改注册侦听器。渲染器状态更改回调，该回调将在渲染器流状态更改时调用， 通过重写 **AudioRendererStateChangeCallback** 类中的函数 **OnRendererStateChange** 。 263 ``` 264 const int32_t clientUID; 265 266 class RendererStateChangeCallback : public AudioRendererStateChangeCallback { 267 public: 268 RendererStateChangeCallback = default; 269 ~RendererStateChangeCallback = default; 270 void OnRendererStateChange( 271 const std::vector<std::unique_ptr<AudioRendererChangeInfo>> &audioRendererChangeInfos) override 272 { 273 cout<<"OnRendererStateChange entered"<<endl; 274 } 275 }; 276 277 std::shared_ptr<AudioRendererStateChangeCallback> callback = std::make_shared<RendererStateChangeCallback>(); 278 int32_t state = audioStreamMgr->RegisterAudioRendererEventListener(clientUID, callback); 279 int32_t result = audioStreamMgr->UnregisterAudioRendererEventListener(clientUID); 280 ``` 281 2823. 使用 **RegisterAudioCapturerEventListener** 为捕获器状态更改注册侦听器。 捕获器状态更改回调，该回调将在捕获器流状态更改时调用， 通过重写 **AudioCapturerStateChangeCallback** 类中的函数 **OnCapturerStateChange** 。 283 ``` 284 const int32_t clientUID; 285 286 class CapturerStateChangeCallback : public AudioCapturerStateChangeCallback { 287 public: 288 CapturerStateChangeCallback = default; 289 ~CapturerStateChangeCallback = default; 290 void OnCapturerStateChange( 291 const std::vector<std::unique_ptr<AudioCapturerChangeInfo>> &audioCapturerChangeInfos) override 292 { 293 cout<<"OnCapturerStateChange entered"<<endl; 294 } 295 }; 296 297 std::shared_ptr<AudioCapturerStateChangeCallback> callback = std::make_shared<CapturerStateChangeCallback>(); 298 int32_t state = audioStreamMgr->RegisterAudioCapturerEventListener(clientUID, callback); 299 int32_t result = audioStreamMgr->UnregisterAudioCapturerEventListener(clientUID); 300 ``` 3014. 使用 **GetCurrentRendererChangeInfos** 获取所有当前正在运行的流渲染器信息，包括clientuid、sessionid、renderinfo、renderstate和输出设备详细信息。 302 ``` 303 std::vector<std::unique_ptr<AudioRendererChangeInfo>> audioRendererChangeInfos; 304 int32_t currentRendererChangeInfo = audioStreamMgr->GetCurrentRendererChangeInfos(audioRendererChangeInfos); 305 ``` 306 3075. 使用 **GetCurrentCapturerChangeInfos** 获取所有当前正在运行的流捕获器信息，包括clientuid、sessionid、capturerInfo、capturerState和输入设备详细信息。 308 ``` 309 std::vector<std::unique_ptr<AudioCapturerChangeInfo>> audioCapturerChangeInfos; 310 int32_t currentCapturerChangeInfo = audioStreamMgr->GetCurrentCapturerChangeInfos(audioCapturerChangeInfos); 311 ``` 312 有关结构，请参阅[**audio_info.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/interfaces/inner_api/native/audiocommon/include/audio_info.h) **audioRendererChangeInfos** 和 **audioCapturerChangeInfos**. 313 3146. 使用 **IsAudioRendererLowLatencySupported** 检查低延迟功能是否支持。 315 ``` 316 const AudioStreamInfo &audioStreamInfo; 317 bool isLatencySupport = audioStreamMgr->IsAudioRendererLowLatencySupported(audioStreamInfo); 318 ``` 319#### JavaScript 用法:<a name="section645572311287_005"></a> 320JavaScript应用可以使用系统提供的音频管理接口，来控制音量和设备。\ 321请参考 [**js-apis-audio.md**](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-audio.md#audiomanager) 来获取音量和设备管理相关JavaScript接口的用法。 322 323### 铃声管理<a name="section645572311287_006"></a> 324可以使用提供的接口[**iringtone_sound_manager.h**](https://gitee.com/openharmony/multimedia_audio_framework/blob/master/interfaces/inner_api/native/audioringtone/include/iringtone_sound_manager.h) 和 [**iringtone_player.h**](https://gitee.com/openharmony/multimedia_audio_framework/blob/master/interfaces/inner_api/native/audioringtone/include/iringtone_player.h)实现铃声播放功能。 3251. 使用 **CreateRingtoneManager** 接口创建 **IRingtoneSoundManager** 实例。 326 ``` 327 std::shared_ptr<IRingtoneSoundManager> ringtoneManagerClient = RingtoneFactory::CreateRingtoneManager(); 328 ``` 3292. 使用 **SetSystemRingtoneUri** 接口设置系统铃声Uri 330 ``` 331 std::string uri = "/data/media/test.wav"; 332 RingtoneType ringtoneType = RINGTONE_TYPE_DEFAULT; 333 ringtoneManagerClient->SetSystemRingtoneUri(context, uri, ringtoneType); 334 ``` 3353. 使用 **GetRingtonePlayer** 接口获取 **IRingtonePlayer** 实例。 336 ``` 337 std::unique_ptr<IRingtonePlayer> ringtonePlayer = ringtoneManagerClient->GetRingtonePlayer(context, ringtoneType); 338 ``` 3394. 使用 **Configure** 接口配置铃声播放器。 340 ``` 341 float volume = 1; 342 bool loop = true; 343 ringtonePlayer.Configure(volume, loop); 344 ``` 3455. 使用 **Start**, **Stop**, 和 **Release** 接口在铃声播放器实例上控制播放状态。 346 ``` 347 ringtonePlayer.Start(); 348 ringtonePlayer.Stop(); 349 ringtonePlayer.Release(); 350 ``` 3516. 使用 **GetTitle** 接口获取当前系统铃声的标题。 3527. 使用 **GetRingtoneState** 接口获取铃声播放状态 - **RingtoneState** 3538. 使用 **GetAudioRendererInfo** 获取 **AudioRendererInfo** 检查内容类型和流使用情况。 354### 蓝牙SCO呼叫<a name="section645572311287_007"></a> 355可以使用提供的接口 [**audio_bluetooth_manager.h**](https://gitee.com/openharmony/multimedia_audio_standard/blob/master/services/include/audio_bluetooth/client/audio_bluetooth_manager.h) 实现同步连接导向链路（SCO）的蓝牙呼叫。 356 3571. 为监听SCO状态更改，您可以使用 **OnScoStateChanged**. 358``` 359const BluetoothRemoteDevice &device; 360int state; 361void OnScoStateChanged(const BluetoothRemoteDevice &device, int state); 362``` 363 3642. (可选) 静态接口 **RegisterBluetoothScoAgListener**(), **UnregisterBluetoothScoAgListener**(), 可用于注册蓝牙SCO的侦听器。 365## 支持设备<a name="section645572311287_008"></a> 366以下是音频子系统支持的设备类型列表。 367 3681. **USB Type-C Headset**\ 369 数字耳机，包括自己的DAC（数模转换器）和作为耳机一部分的放大器。 3702. **WIRED Headset**\ 371 模拟耳机内部不包含任何DAC。它可以有3.5mm插孔或不带DAC的C型插孔。 3723. **Bluetooth Headset**\ 373 蓝牙A2DP（高级音频分配模式）耳机，用于无线传输音频。 3744. **Internal Speaker and MIC**\ 375 支持内置扬声器和麦克风，并将分别用作播放和录制的默认设备。 376 377## 相关仓<a name="section340mcpsimp"></a> 378 379[multimedia\_audio\_framework](https://gitee.com/openharmony/multimedia_audio_framework) 380
