簡介

音頻組件用于實現音頻相關的功能，包括音頻播放，錄制，音量管理和設備管理。

圖 1 音頻組件架構圖

基本概念

• 采樣

采樣是指將連續時域上的模擬信號按照一定的時間間隔采樣，獲取到離散時域上離散信號的過程。

• 采樣率

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

• 聲道

聲道是指聲音在錄制或播放時在不同空間位置采集或回放的相互獨立的音頻信號，所以聲道數也就是聲音錄制時的音源數量或回放時相應的揚聲器數量。

• 音頻幀

音頻數據是流式的，本身沒有明確的一幀幀的概念，在實際的應用中，為了音頻算法處理/傳輸的方便，一般約定俗成取2.5ms~60ms為單位的數據量為一幀音頻。這個時間被稱之為“采樣時間”，其長度沒有特別的標準，它是根據編解碼器和具體應用的需求來決定的。

• PCM

PCM（Pulse Code Modulation），即脈沖編碼調制，是一種將模擬信號數字化的方法，是將時間連續、取值連續的模擬信號轉換成時間離散、抽樣值離散的數字信號的過程。

目錄

倉目錄結構如下：

/foundation/multimedia/audio_standard  # 音頻組件業務代碼
├── frameworks                         # 框架代碼
│   ├── native                         # 內部接口實現
│   └── js                             # 外部接口實現
│       └── napi                       # napi 外部接口實現
├── interfaces                         # 接口代碼
│   ├── inner_api                      # 內部接口
│   └── kits                           # 外部接口
├── sa_profile                         # 服務配置文件
├── services                           # 服務代碼
├── LICENSE                            # 證書文件
└── bundle.json                        # 編譯文件

使用說明

音頻播放

可以使用此倉庫內提供的接口將音頻數據轉換為音頻模擬信號，使用輸出設備播放音頻信號，以及管理音頻播放任務。以下步驟描述了如何使用 AudioRenderer 開發音頻播放功能：

1. 使用 Create 接口和所需流類型來獲取 AudioRenderer 實例。

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

2. （可選）靜態接口 GetSupportedFormats (), GetSupportedChannels (), GetSupportedEncodingTypes (), GetSupportedSamplingRates () 可用于獲取支持的參數。
3. 準備設備，調用實例的 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) 來驗證 SetParams。
5. （可選）使用 SetAudioEffectMode 和 GetAudioEffectMode 接口來設置和獲取當前音頻流的音效模式。

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

6. AudioRenderer 實例調用 audioRenderer-> Start () 函數來啟動播放任務。
7. 使用 GetBufferSize 接口獲取要寫入的緩沖區長度。

   audioRenderer- >GetBufferSize(bufferLen);
   

8. 從源（例如音頻文件）讀取要播放的音頻數據并將其傳輸到字節流中。重復調用Write函數寫入渲染數據。

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

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

以上提供了基本音頻播放使用場景。

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

音頻錄制

可以使用此倉庫內提供的接口，讓應用程序可以完成使用輸入設備進行聲音錄制，將語音轉換為音頻數據，并管理錄制的任務。以下步驟描述了如何使用 AudioCapturer 開發音頻錄制功能：

1. 使用Create接口和所需流類型來獲取 AudioCapturer 實例。

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

2. （可選）靜態接口 GetSupportedFormats (), GetSupportedChannels (), GetSupportedEncodingTypes (), GetSupportedSamplingRates () 可用于獲取支持的參數。
3. 準備設備，調用實例的 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) 來驗證 SetParams()。
5. AudioCapturer 實例調用 AudioCapturer-> Start () 函數來啟動錄音任務。
6. 使用 GetBufferSize 接口獲取要寫入的緩沖區長度。

   audioCapturer- >GetBufferSize(bufferLen);
   

7. 讀取錄制的音頻數據并將其轉換為字節流。重復調用read函數讀取數據直到主動停止。

   // 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 () 來清空錄音流緩沖區。
9. AudioCapturer 實例調用 audioCapturer-> Stop () 函數停止錄音。
10. 錄音任務完成后，調用 AudioCapturer 實例的 audioCapturer-> Release () 函數釋放資源。

音頻管理

可以使用 [ audio_system_manager.h ]內的接口來控制音量和設備。

1. 使用 GetInstance 接口獲取 AudioSystemManager 實例.

   AudioSystemManager *audioSystemMgr = AudioSystemManager::GetInstance();
   

音量控制

2. 使用 GetMaxVolume 和 GetMinVolume 接口去查詢音頻流支持的最大和最小音量等級，在此范圍內設置音量。

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

3. 使用 SetVolume 和 GetVolume 接口來設置和獲取指定音頻流的音量等級。

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

4. 使用 SetMute 和 IsStreamMute 接口來設置和獲取指定音頻流的靜音狀態。

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

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

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

6. 使用 SetMicrophoneMute 和 IsMicrophoneMute 接口來設置和獲取麥克風的靜音狀態。

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

設備控制

7. 使用 GetDevices , deviceType_ 和 deviceRole_ 接口來獲取音頻輸入輸出設備信息。 內定義的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 接口去激活/去激活音頻設備和獲取音頻設備激活狀態。

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

9. 提供其他用途的接口如 IsStreamActive , SetAudioParameter and GetAudioParameter
10. 應用程序可以使用 AudioManagerNapi::On注冊系統音量的更改。 在此，如果應用程序監聽到系統音量更改的事件,就會用以下參數通知應用程序: volumeType : 更改的系統音量的類型 volume : 當前的音量等級 updateUi : 是否需要顯示變化詳細信息。（如果音量被增大/減小，將updateUi標志設置為true，在其他情況下，updateUi設置為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);
    }
  }
}

音頻場景

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

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

有關支持的音頻場景，請參閱 AudioScene 中的枚舉[ audio_info.h ]

音頻流管理

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

1. 使用 GetInstance 接口獲得 AudioSystemManager 實例。

   AudioStreamManager *audioStreamMgr = AudioStreamManager::GetInstance();
   

2. 使用 RegisterAudioRendererEventListener 為渲染器狀態更改注冊偵聽器。渲染器狀態更改回調，該回調將在渲染器流狀態更改時調用， 通過重寫 AudioRendererStateChangeCallback 類中的函數 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 為捕獲器狀態更改注冊偵聽器。 捕獲器狀態更改回調，該回調將在捕獲器流狀態更改時調用， 通過重寫 AudioCapturerStateChangeCallback 類中的函數 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 獲取所有當前正在運行的流渲染器信息，包括clientuid、sessionid、renderinfo、renderstate和輸出設備詳細信息。

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

5. 使用 GetCurrentCapturerChangeInfos 獲取所有當前正在運行的流捕獲器信息，包括clientuid、sessionid、capturerInfo、capturerState和輸入設備詳細信息。

   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 接口查詢指定[ StreamUsage ]下可以支持的音效模式。

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

JavaScript 用法:

JavaScript應用可以使用系統提供的音頻管理接口，來控制音量和設備。
請參考 [ js-apis-audio.md ]來獲取音量和設備管理相關JavaScript接口的用法。

藍牙SCO呼叫

可以使用提供的接口 [ audio_bluetooth_manager.h ] 實現同步連接導向鏈路（SCO）的藍牙呼叫。

1. 為監聽SCO狀態更改，您可以使用 OnScoStateChanged .

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

2. (可選) 靜態接口 RegisterBluetoothScoAgListener (), UnregisterBluetoothScoAgListener (), 可用于注冊藍牙SCO的偵聽器。

支持設備

以下是音頻子系統支持的設備類型列表。

1. USB Type-C Headset
   數字耳機，包括自己的DAC（數模轉換器）和作為耳機一部分的放大器。

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

3. Bluetooth Headset
   藍牙A2DP（高級音頻分配模式）耳機，用于無線傳輸音頻。

4. Internal Speaker and MIC
   支持內置揚聲器和麥克風，并將分別用作播放和錄制的默認設備。

   審核編輯 黃宇