簡(jiǎn)介

音頻組件用于實(shí)現(xiàn)音頻相關(guān)的功能，包括音頻播放，錄制，音量管理和設(shè)備管理。

圖 1 音頻組件架構(gòu)圖

基本概念

• 采樣

采樣是指將連續(xù)時(shí)域上的模擬信號(hào)按照一定的時(shí)間間隔采樣，獲取到離散時(shí)域上離散信號(hào)的過(guò)程。

• 采樣率

采樣率為每秒從連續(xù)信號(hào)中提取并組成離散信號(hào)的采樣次數(shù)，單位用赫茲（Hz）來(lái)表示。通常人耳能聽(tīng)到頻率范圍大約在20Hz～20kHz之間的聲音。常用的音頻采樣頻率有：8kHz、11.025kHz、22.05kHz、16kHz、37.8kHz、44.1kHz、48kHz、96kHz、192kHz等。

• 聲道

聲道是指聲音在錄制或播放時(shí)在不同空間位置采集或回放的相互獨(dú)立的音頻信號(hào)，所以聲道數(shù)也就是聲音錄制時(shí)的音源數(shù)量或回放時(shí)相應(yīng)的揚(yáng)聲器數(shù)量。

• 音頻幀

音頻數(shù)據(jù)是流式的，本身沒(méi)有明確的一幀幀的概念，在實(shí)際的應(yīng)用中，為了音頻算法處理/傳輸?shù)姆奖?，一般約定俗成取2.5ms~60ms為單位的數(shù)據(jù)量為一幀音頻。這個(gè)時(shí)間被稱(chēng)之為“采樣時(shí)間”，其長(zhǎng)度沒(méi)有特別的標(biāo)準(zhǔn)，它是根據(jù)編解碼器和具體應(yīng)用的需求來(lái)決定的。

• PCM

PCM（Pulse Code Modulation），即脈沖編碼調(diào)制，是一種將模擬信號(hào)數(shù)字化的方法，是將時(shí)間連續(xù)、取值連續(xù)的模擬信號(hào)轉(zhuǎn)換成時(shí)間離散、抽樣值離散的數(shù)字信號(hào)的過(guò)程。

目錄

倉(cāng)目錄結(jié)構(gòu)如下：

/foundation/multimedia/audio_standard  # 音頻組件業(yè)務(wù)代碼
├── frameworks                         # 框架代碼
│   ├── native                         # 內(nèi)部接口實(shí)現(xiàn)
│   └── js                             # 外部接口實(shí)現(xiàn)
│       └── napi                       # napi 外部接口實(shí)現(xiàn)
├── interfaces                         # 接口代碼
│   ├── inner_api                      # 內(nèi)部接口
│   └── kits                           # 外部接口
├── sa_profile                         # 服務(wù)配置文件
├── services                           # 服務(wù)代碼
├── LICENSE                            # 證書(shū)文件
└── bundle.json                        # 編譯文件

使用說(shuō)明

音頻播放

可以使用此倉(cāng)庫(kù)內(nèi)提供的接口將音頻數(shù)據(jù)轉(zhuǎn)換為音頻模擬信號(hào)，使用輸出設(shè)備播放音頻信號(hào)，以及管理音頻播放任務(wù)。以下步驟描述了如何使用 AudioRenderer 開(kāi)發(fā)音頻播放功能：

1. 使用 Create 接口和所需流類(lèi)型來(lái)獲取 AudioRenderer 實(shí)例。

   AudioStreamType streamType = STREAM_MUSIC; // 流類(lèi)型示例
   std::unique_ptr< AudioRenderer > audioRenderer = AudioRenderer::Create(streamType);
   

2. （可選）靜態(tài)接口 GetSupportedFormats (), GetSupportedChannels (), GetSupportedEncodingTypes (), GetSupportedSamplingRates () 可用于獲取支持的參數(shù)。
3. 準(zhǔn)備設(shè)備，調(diào)用實(shí)例的 SetParams 。

   AudioRendererParams rendererParams;
   rendererParams.sampleFormat = SAMPLE_S16LE;
   rendererParams.sampleRate = SAMPLE_RATE_44100;
   rendererParams.channelCount = STEREO;
   rendererParams.encodingType = ENCODING_PCM;
   
   audioRenderer- >SetParams(rendererParams);
   

4. （可選）使用 audioRenderer-> GetParams (rendererParams) 來(lái)驗(yàn)證 SetParams。
5. （可選）使用 SetAudioEffectMode 和 GetAudioEffectMode 接口來(lái)設(shè)置和獲取當(dāng)前音頻流的音效模式。

   AudioEffectMode effectMode = EFFECT_DEFAULT;
   int32_t result = audioRenderer- >SetAudioEffectMode(effectMode);
   AudioEffectMode mode = audioRenderer- >GetAudioEffectMode();
   

6. AudioRenderer 實(shí)例調(diào)用 audioRenderer-> Start () 函數(shù)來(lái)啟動(dòng)播放任務(wù)。
7. 使用 GetBufferSize 接口獲取要寫(xiě)入的緩沖區(qū)長(zhǎng)度。

   audioRenderer- >GetBufferSize(bufferLen);
   

8. 從源（例如音頻文件）讀取要播放的音頻數(shù)據(jù)并將其傳輸?shù)阶止?jié)流中。重復(fù)調(diào)用Write函數(shù)寫(xiě)入渲染數(shù)據(jù)。

   bytesToWrite = fread(buffer, 1, bufferLen, wavFile);
   while ((bytesWritten < bytesToWrite) && ((bytesToWrite - bytesWritten) > minBytes)) {
       bytesWritten += audioRenderer- >Write(buffer + bytesWritten, bytesToWrite - bytesWritten);
       if (bytesWritten < 0)
           break;
   }
   

9. 調(diào)用audioRenderer-> Drain ()來(lái)清空播放流。
10. 調(diào)用audioRenderer-> Stop ()來(lái)停止輸出。
11. 播放任務(wù)完成后，調(diào)用AudioRenderer實(shí)例的audioRenderer-> Release ()函數(shù)來(lái)釋放資源。

以上提供了基本音頻播放使用場(chǎng)景。

12. 使用 audioRenderer->SetVolume(float) 和 audioRenderer->GetVolume() 來(lái)設(shè)置和獲取當(dāng)前音頻流音量, 可選范圍為 0.0 到 1.0。

音頻錄制

可以使用此倉(cāng)庫(kù)內(nèi)提供的接口，讓?xiě)?yīng)用程序可以完成使用輸入設(shè)備進(jìn)行聲音錄制，將語(yǔ)音轉(zhuǎn)換為音頻數(shù)據(jù)，并管理錄制的任務(wù)。以下步驟描述了如何使用 AudioCapturer 開(kāi)發(fā)音頻錄制功能：

1. 使用Create接口和所需流類(lèi)型來(lái)獲取 AudioCapturer 實(shí)例。

   AudioStreamType streamType = STREAM_MUSIC;
   std::unique_ptr< AudioCapturer > audioCapturer = AudioCapturer::Create(streamType);
   

2. （可選）靜態(tài)接口 GetSupportedFormats (), GetSupportedChannels (), GetSupportedEncodingTypes (), GetSupportedSamplingRates () 可用于獲取支持的參數(shù)。
3. 準(zhǔn)備設(shè)備，調(diào)用實(shí)例的 SetParams 。

   AudioCapturerParams capturerParams;
   capturerParams.sampleFormat = SAMPLE_S16LE;
   capturerParams.sampleRate = SAMPLE_RATE_44100;
   capturerParams.channelCount = STEREO;
   capturerParams.encodingType = ENCODING_PCM;
   
   audioCapturer- >SetParams(capturerParams);
   

4. （可選）使用 audioCapturer-> GetParams (capturerParams) 來(lái)驗(yàn)證 SetParams()。
5. AudioCapturer 實(shí)例調(diào)用 AudioCapturer-> Start () 函數(shù)來(lái)啟動(dòng)錄音任務(wù)。
6. 使用 GetBufferSize 接口獲取要寫(xiě)入的緩沖區(qū)長(zhǎng)度。

   audioCapturer- >GetBufferSize(bufferLen);
   

7. 讀取錄制的音頻數(shù)據(jù)并將其轉(zhuǎn)換為字節(jié)流。重復(fù)調(diào)用read函數(shù)讀取數(shù)據(jù)直到主動(dòng)停止。

   // set isBlocking = true/false for blocking/non-blocking read
   bytesRead = audioCapturer- >Read(*buffer, bufferLen, isBlocking);
   while (numBuffersToCapture) {
       bytesRead = audioCapturer- >Read(*buffer, bufferLen, isBlockingRead);
       if (bytesRead <= 0) {
           break;
       } else if (bytesRead > 0) {
           fwrite(buffer, size, bytesRead, recFile); // example shows writes the recorded data into a file
           numBuffersToCapture--;
       }
   }
   

8. （可選）audioCapturer-> Flush () 來(lái)清空錄音流緩沖區(qū)。
9. AudioCapturer 實(shí)例調(diào)用 audioCapturer-> Stop () 函數(shù)停止錄音。
10. 錄音任務(wù)完成后，調(diào)用 AudioCapturer 實(shí)例的 audioCapturer-> Release () 函數(shù)釋放資源。

音頻管理

可以使用 [ audio_system_manager.h ]內(nèi)的接口來(lái)控制音量和設(shè)備。

1. 使用 GetInstance 接口獲取 AudioSystemManager 實(shí)例.

   AudioSystemManager *audioSystemMgr = AudioSystemManager::GetInstance();
   

音量控制

2. 使用 GetMaxVolume 和 GetMinVolume 接口去查詢(xún)音頻流支持的最大和最小音量等級(jí)，在此范圍內(nèi)設(shè)置音量。

   AudioVolumeType streamType = AudioVolumeType::STREAM_MUSIC;
   int32_t maxVol = audioSystemMgr- >GetMaxVolume(streamType);
   int32_t minVol = audioSystemMgr- >GetMinVolume(streamType);
   

3. 使用 SetVolume 和 GetVolume 接口來(lái)設(shè)置和獲取指定音頻流的音量等級(jí)。

   int32_t result = audioSystemMgr- >SetVolume(streamType, 10);
   int32_t vol = audioSystemMgr- >GetVolume(streamType);
   

4. 使用 SetMute 和 IsStreamMute 接口來(lái)設(shè)置和獲取指定音頻流的靜音狀態(tài)。

   int32_t result = audioSystemMgr- >SetMute(streamType, true);
   bool isMute = audioSystemMgr- >IsStreamMute(streamType);
   

5. 使用 SetRingerMode 和 GetRingerMode 接口來(lái)設(shè)置和獲取鈴聲模式。參考在 [ audio_info.h ]定義的 AudioRingerMode 枚舉來(lái)獲取支持的鈴聲模式。

   int32_t result = audioSystemMgr- >SetRingerMode(RINGER_MODE_SILENT);
   AudioRingerMode ringMode = audioSystemMgr- >GetRingerMode();
   

6. 使用 SetMicrophoneMute 和 IsMicrophoneMute 接口來(lái)設(shè)置和獲取麥克風(fēng)的靜音狀態(tài)。

   int32_t result = audioSystemMgr- >SetMicrophoneMute(true);
   bool isMicMute = audioSystemMgr- >IsMicrophoneMute();
   

設(shè)備控制

7. 使用 GetDevices , deviceType_ 和 deviceRole_ 接口來(lái)獲取音頻輸入輸出設(shè)備信息。 內(nèi)定義的DeviceFlag, DeviceType 和 DeviceRole 枚舉。

   DeviceFlag deviceFlag = OUTPUT_DEVICES_FLAG;
   vector< sptr< AudioDeviceDescriptor >> audioDeviceDescriptors
       = audioSystemMgr- >GetDevices(deviceFlag);
   sptr< AudioDeviceDescriptor > audioDeviceDescriptor = audioDeviceDescriptors[0];
   cout < < audioDeviceDescriptor- >deviceType_;
   cout < < audioDeviceDescriptor- >deviceRole_;
   

8. 使用 SetDeviceActive 和 IsDeviceActive 接口去激活/去激活音頻設(shè)備和獲取音頻設(shè)備激活狀態(tài)。

   ActiveDeviceType deviceType = SPEAKER;
   int32_t result = audioSystemMgr- >SetDeviceActive(deviceType, true);
   bool isDevActive = audioSystemMgr- >IsDeviceActive(deviceType);
   

9. 提供其他用途的接口如 IsStreamActive , SetAudioParameter and GetAudioParameter
10. 應(yīng)用程序可以使用 AudioManagerNapi::On注冊(cè)系統(tǒng)音量的更改。 在此，如果應(yīng)用程序監(jiān)聽(tīng)到系統(tǒng)音量更改的事件,就會(huì)用以下參數(shù)通知應(yīng)用程序: volumeType : 更改的系統(tǒng)音量的類(lèi)型 volume : 當(dāng)前的音量等級(jí) updateUi : 是否需要顯示變化詳細(xì)信息。（如果音量被增大/減小，將updateUi標(biāo)志設(shè)置為true，在其他情況下，updateUi設(shè)置為false）。

const audioManager = audio.getAudioManager();

export default {
  onCreate() {
    audioManager.on('volumeChange', (volumeChange) == > {
      console.info('volumeType = '+volumeChange.volumeType);
      console.info('volume = '+volumeChange.volume);
      console.info('updateUi = '+volumeChange.updateUi);
    }
  }
}

音頻場(chǎng)景

11. 使用 SetAudioScene 和 getAudioScene 接口去更改和檢查音頻策略。

    int32_t result = audioSystemMgr- >SetAudioScene(AUDIO_SCENE_PHONE_CALL);
    AudioScene audioScene = audioSystemMgr- >GetAudioScene();
    

有關(guān)支持的音頻場(chǎng)景，請(qǐng)參閱 AudioScene 中的枚舉[ audio_info.h ]

音頻流管理

可以使用[ audio_stream_manager.h ]提供的接口用于流管理功能。

1. 使用 GetInstance 接口獲得 AudioSystemManager 實(shí)例。

   AudioStreamManager *audioStreamMgr = AudioStreamManager::GetInstance();
   

2. 使用 RegisterAudioRendererEventListener 為渲染器狀態(tài)更改注冊(cè)偵聽(tīng)器。渲染器狀態(tài)更改回調(diào)，該回調(diào)將在渲染器流狀態(tài)更改時(shí)調(diào)用， 通過(guò)重寫(xiě) AudioRendererStateChangeCallback 類(lèi)中的函數(shù) OnRendererStateChange 。

   const int32_t clientPid;
   
   class RendererStateChangeCallback : public AudioRendererStateChangeCallback {
   public:
       RendererStateChangeCallback = default;
       ~RendererStateChangeCallback = default;
   void OnRendererStateChange(
       const std::vector< std::unique_ptr< AudioRendererChangeInfo >> &audioRendererChangeInfos) override
   {
       cout< "OnRendererStateChange entered"<
   

3. 使用 RegisterAudioCapturerEventListener 為捕獲器狀態(tài)更改注冊(cè)偵聽(tīng)器。 捕獲器狀態(tài)更改回調(diào)，該回調(diào)將在捕獲器流狀態(tài)更改時(shí)調(diào)用， 通過(guò)重寫(xiě) AudioCapturerStateChangeCallback 類(lèi)中的函數(shù) OnCapturerStateChange 。

   const int32_t clientPid;
   
   class CapturerStateChangeCallback : public AudioCapturerStateChangeCallback {
   public:
       CapturerStateChangeCallback = default;
       ~CapturerStateChangeCallback = default;
   void OnCapturerStateChange(
       const std::vector< std::unique_ptr< AudioCapturerChangeInfo >> &audioCapturerChangeInfos) override
   {
       cout< "OnCapturerStateChange entered"<
   

4. 使用 GetCurrentRendererChangeInfos 獲取所有當(dāng)前正在運(yùn)行的流渲染器信息，包括clientuid、sessionid、renderinfo、renderstate和輸出設(shè)備詳細(xì)信息。

   std::vector< std::unique_ptr< AudioRendererChangeInfo >> audioRendererChangeInfos;
   int32_t currentRendererChangeInfo = audioStreamMgr- >GetCurrentRendererChangeInfos(audioRendererChangeInfos);
   

5. 使用 GetCurrentCapturerChangeInfos 獲取所有當(dāng)前正在運(yùn)行的流捕獲器信息，包括clientuid、sessionid、capturerInfo、capturerState和輸入設(shè)備詳細(xì)信息。

   std::vector< std::unique_ptr< AudioCapturerChangeInfo >> audioCapturerChangeInfos;
   int32_t currentCapturerChangeInfo = audioStreamMgr- >GetCurrentCapturerChangeInfos(audioCapturerChangeInfos);
   

6. 使用 IsAudioRendererLowLatencySupported 檢查低延遲功能是否支持。

   const AudioStreamInfo &audioStreamInfo;
   bool isLatencySupport = audioStreamMgr- >IsAudioRendererLowLatencySupported(audioStreamInfo);
   

7. 使用 GetEffectInfoArray 接口查詢(xún)指定[ StreamUsage ]下可以支持的音效模式。

   AudioSceneEffectInfo audioSceneEffectInfo;
   int32_t status = audioStreamMgr- >GetEffectInfoArray(audioSceneEffectInfo,streamUsage);
   

JavaScript 用法:

JavaScript應(yīng)用可以使用系統(tǒng)提供的音頻管理接口，來(lái)控制音量和設(shè)備。
請(qǐng)參考 [ js-apis-audio.md ]來(lái)獲取音量和設(shè)備管理相關(guān)JavaScript接口的用法。

藍(lán)牙SCO呼叫

可以使用提供的接口 [ audio_bluetooth_manager.h ] 實(shí)現(xiàn)同步連接導(dǎo)向鏈路（SCO）的藍(lán)牙呼叫。

1. 為監(jiān)聽(tīng)SCO狀態(tài)更改，您可以使用 OnScoStateChanged .

const BluetoothRemoteDevice &device;
int state;
void OnScoStateChanged(const BluetoothRemoteDevice &device, int state);

2. (可選) 靜態(tài)接口 RegisterBluetoothScoAgListener (), UnregisterBluetoothScoAgListener (), 可用于注冊(cè)藍(lán)牙SCO的偵聽(tīng)器。

支持設(shè)備

以下是音頻子系統(tǒng)支持的設(shè)備類(lèi)型列表。

1. USB Type-C Headset
   數(shù)字耳機(jī)，包括自己的DAC（數(shù)模轉(zhuǎn)換器）和作為耳機(jī)一部分的放大器。

2. WIRED Headset
   模擬耳機(jī)內(nèi)部不包含任何DAC。它可以有3.5mm插孔或不帶DAC的C型插孔。

3. Bluetooth Headset
   藍(lán)牙A2DP（高級(jí)音頻分配模式）耳機(jī)，用于無(wú)線(xiàn)傳輸音頻。

4. Internal Speaker and MIC
   支持內(nèi)置揚(yáng)聲器和麥克風(fēng)，并將分別用作播放和錄制的默認(rèn)設(shè)備。

   審核編輯 黃宇