ApsaraVideo Live：音頻常用操作和配置

1.1.音頻編碼模式（AliRtcAudioProfile）

1.2.音頻情境模式（AliRtcAudioScenario）

1.3.範例程式碼

以下將為您提供一些常見情境的音頻編碼模式及應用情境的模式設定樣本。

需要藍芽採集

// 需要設定為AliRtcSceneDefaultMode情境
mAliRtcEngine.setAudioProfile(AliRtcEngineHighQualityMode, AliRtcSceneDefaultMode);

// 需要設定為AliRtcSceneDefaultMode情境
engine.setAudioProfile(AliRtcAudioProfile.engineHighQualityMode, audio_scene: AliRtcAudioScenario.sceneDefaultMode)

this.rtcEngine.setAudioProfile(AliRtcAudioProfile.AliRtcHighQualityMode, AliRtcAudioScenario.AliRtcSceneDefaultMode);

[self.engine setAudioProfile:AliRtcEngineHighQualityMode audio_scene:AliRtcSceneDefaultMode];

mAliRtcEngine->SetAudioProfile(AliEngineHighQualityMode, AliEngineSceneDefaultMode);

需要與 Web 端互連

// 需要設定為採樣率48k的編碼模式,例如AliRtcEngineHighQualityMode
mAliRtcEngine.setAudioProfile(AliRtcEngineHighQualityMode, AliRtcSceneMusicMode);

// 需要設定為採樣率48k的編碼模式，例如AliRtcEngineHighQualityMode
engine.setAudioProfile(AliRtcAudioProfile.engineHighQualityMode, audio_scene: AliRtcAudioScenario.sceneMusicMode)

this.rtcEngine.setAudioProfile(AliRtcAudioProfile.AliRtcHighQualityMode, AliRtcAudioScenario.AliRtcSceneMusicMode);

[self.engine setAudioProfile:AliRtcEngineHighQualityMode audio_scene:AliRtcSceneMusicMode];

mAliRtcEngine->SetAudioProfile(AliEngineHighQualityMode, AliEngineSceneMusicMode);

需要雙聲道

// 設定為帶Stereo的模式，例如AliRtcEngineStereoHighQualityMode
mAliRtcEngine.setAudioProfile(AliRtcEngineStereoHighQualityMode, AliRtcSceneMusicMode);

// 設定為帶Stereo的模式，例如AliRtcEngineStereoHighQualityMode
engine.setAudioProfile(AliRtcAudioProfile.engineStereoHighQualityMode, audio_scene: AliRtcAudioScenario.sceneMusicMode)

this.rtcEngine.setAudioProfile(AliRtcAudioProfile.AliRtcStereoHighQualityMode, AliRtcAudioScenario.AliRtcSceneMusicMode);

[self.engine setAudioProfile:AliRtcEngineStereoHighQualityMode audio_scene:AliRtcSceneMusicMode];

mAliRtcEngine->SetAudioProfile(AliEngineStereoHighQualityMode, AliEngineSceneMusicMode);

2.1.靜音麥克風

ARTC 提供muteLocalMic介面用於靜音麥克風和外部輸入音頻，該介面可以在加入頻道前後調用設定是否靜音。

支援設定的模式AliRtcMuteLocalAudioMode如下：

範例程式碼如下：

// 靜音全部
mAliRtcEngine.muteLocalMic(true, AliRtcEngine.AliRtcMuteLocalAudioMode.AliRtcMuteAllAudioMode);
// 取消靜音全部
mAliRtcEngine.muteLocalMic(false, AliRtcEngine.AliRtcMuteLocalAudioMode.AliRtcMuteAllAudioMode);
// 僅靜音麥克風
mAliRtcEngine.muteLocalMic(true, AliRtcEngine.AliRtcMuteLocalAudioMode.AliRtcMuteOnlyMicAudioMode);

// 靜音全部
self.rtcEngine?.muteLocalMic(true, mode: .allAudioMode)
// 取消靜音全部
self.rtcEngine?.muteLocalMic(false, mode: .allAudioMode)
// 僅靜音麥克風
self.rtcEngine?.muteLocalMic(true, mode: .onlyMicAudioMode)

// 靜音全部
this.rtcEngine.muteLocalMic(true, AliRtcMuteLocalAudioMode.AliRtcMuteLocalAudioModeMuteAll);
// 取消靜音全部
this.rtcEngine.muteLocalMic(false, AliRtcMuteLocalAudioMode.AliRtcMuteLocalAudioModeMuteAll);
// 僅靜音麥克風
this.rtcEngine.muteLocalMic(true, AliRtcMuteLocalAudioMode.AliRtcMuteLocalAudioModeMuteOnlyMic);

// 靜音全部
[self.engine muteLocalMic:TRUE mode:AliRtcMuteAllAudioMode];
// 取消靜音全部
[self.engine muteLocalMic:FALSE mode:AliRtcMuteAllAudioMode];
// 僅靜音麥克風
[self.engine muteLocalMic:TRUE mode:AliRtcMuteOnlyMicAudioMode];

// 靜音全部
mAliRtcEngine->MuteLocalMic(true, AliEngineMuteLocalAudioModeMuteAll);
// 取消靜音全部
mAliRtcEngine->MuteLocalMic(false, AliEngineMuteLocalAudioModeMuteAll);
// 僅靜音麥克風
mAliRtcEngine->MuteLocalMic(true, AliEngineMuteLocalAudioModeMuteOnlyMic);

2.2.關閉/恢複麥克風採集

SDK 加入頻道預設開啟麥克風採集，如果需要關閉麥克風採集，可以調用stopAudioCapture停止麥克風採集，此介面會釋放麥克風資源停止採集音頻。如果需要恢複麥克風採集，請調用startAudioCapture介面。

// 停止麥克風採集
mAliRtcEngine.stopAudioCapture();
// 恢複麥克風採集
mAliRtcEngine.startAudioCapture();

// 停止麥克風採集
self.rtcEngine?.stopAudioCapture()
// 恢複麥克風採集
self.rtcEngine?.startAudioCapture()

// 停止麥克風採集
this.rtcEngine.stopAudioCapture();
// 恢複麥克風採集
this.rtcEngine.startAudioCapture();

// 停止麥克風採集
[self.engine stopAudioCapture];
// 恢複麥克風採集
[self.engine startAudioCapture];

// 停止麥克風採集
mAliRtcEngine->StopAudioCapture();
// 恢複麥克風採集
mAliRtcEngine->StartAudioCapture();

3.1.靜音遠端使用者

ARTC 提供muteRemoteAudioPlaying介面停止/恢複遠端指定使用者音頻播放，介面定義如下：

public abstract int muteRemoteAudioPlaying(String uid, boolean mute);

• 這裡的靜音不影響音頻拉流和解碼，可以在入會前後設定。

• 這裡的靜音僅影響遠端使用者音頻在本端的播放，不影響遠端使用者採集。

3.2.設定指定遠端使用者播放音量

ARTC 提供setPlayoutVolume介面控制本端播放音量。

/**
 * @brief 設定播放音量
 * @param volume 播放音量，取值範圍[0,400]
 * - 0：靜音
 * - <100：減小音量
 * - >100：放大音量
 * @return
 * - 0: 成功
 * - 非0: 失敗
 */
public abstract int setPlayoutVolume(int volume);

ARTC 提供setRemoteAudioVolume介面用於控制指定的遠端使用者音頻播放音量，當傳入 volume 參數為 0 時等同於muteRemoteAudioPlaying介面。

/**
 * @brief 調節本地播放的指定遠端使用者音量
 * @param uid 使用者ID，從App server分配的唯一標示符
 * @param volume 播放音量，取值範圍[0,100] 0：靜音；100：原始音量
 * @return
 * - 0: 成功
 * - 非0: 失敗
 */
public abstract int setRemoteAudioVolume(String uid, int volume);

4.1.開啟耳返

可以在加入頻道前後調用enableEarBack介面開啟耳返功能。如果需要關閉耳返功能，請再次調用enableEarBack並將參數置為 false。

rtcEngine.enableEarBack(true);

engine.enableEarBack(true)

this.rtcEngine.enableEarBack(true);

[self.engine enableEarBack:YES];

mAliRtcEngine->EnableEarBack(TRUE);

4.2.設定耳返音量

調用setEarBackVolume介面調整耳返的音量，參數volume表示音量大小，範圍為 [0~100]，其中 0 表示靜音，100 表示正常音量，預設值為 100。

rtcEngine.setEarBackVolume(60);

rtcEngine?.setEarBackVolume(volume)

this.rtcEngine.setEarBackVolume(value);

[self.engine setEarBackVolume:60];

mAliRtcEngine->SetEarBackVolume(volume);

5.1. 開啟回調功能

調用enableAudioVolumeIndication 開啟功能並設定回調頻率、平滑係數等，參數如下：

• interval：回調頻率間隔，單位為 ms。建議設定為 300～500ms，最小不能低於 10ms，如果設定為負值表示關閉此功能。

• smooth：平滑係數，數值越大表示平滑程度越高，反之平滑程度低即時性好，建議設定為 3，取值範圍為 [0-9]。

• reportVad：說話人檢測開關，0 表示關閉，1 表示開啟。

mAliRtcEngine.enableAudioVolumeIndication(500, 3,1);

// 使用者音量回調和說話人檢測
engine.enableAudioVolumeIndication(500, smooth: 3, reportVad: 1)

// 使用者音量回調和說話人檢測
this.rtcEngine.enableAudioVolumeIndication(1000, 3, 1);

// 使用者音量回調和說話人檢測
[self.engine enableAudioVolumeIndication:500 smooth:3 reportVad:1];

// 使用者音量回調和說話人檢測
mAliRtcEngine->EnableAudioVolumeIndication(500, 3, 1);

5.2. 實現並註冊相關回調

調用registerAudioVolumeObserver介面註冊相關回調，之後系統會根據設定的間隔回調：

• onAudioVolume 回調負責提供周期性的音頻音量資訊，用於即時掌握各使用者的發言強度。系統會定時上報當前檢測到的所有使用者（包括本地和遠端）的音量層級，開發人員可用於實現聲波動畫、音量指示條或靜音檢測等 UI 反饋。其中，當 mUserId 為 "0" 時，表示該條目為本地採集音量；mUserId 為“1”時表示所有遠端使用者的混音音量，其他值表示指定使用者的音量資訊。 totalVolume 表示所有遠端使用者混音後的總體音量。

• onActiveSpeaker 是語音激勵（Voice Activity Detection, VAD）觸發的主講人回調。當系統檢測到某個使用者成為當前最活躍的發言人（說話音量和期間超過閾值）時，會通過此回調通知應用程式層。開發人員可利用該事件實現“自動聚焦發言人”的互動體驗，例如會議情境講說話人視頻視窗置為大屏等。

private final AliRtcEngine.AliRtcAudioVolumeObserver mAliRtcAudioVolumeObserver = new AliRtcEngine.AliRtcAudioVolumeObserver() {
    // 使用者音量回調
    @Override
    public void onAudioVolume(List<AliRtcEngine.AliRtcAudioVolume> speakers, int totalVolume){
        handler.post(() -> {
            if(!speakers.isEmpty()) {
                for(AliRtcEngine.AliRtcAudioVolume volume : speakers) {
                    if("0".equals(volume.mUserId)) {
                        // 本地目前使用者音量

                    } else if ("1".equals(volume.mUserId)) {
                        // 遠端使用者整體音量

                    } else {
                        // 遠端使用者音量

                    }
                }
            }
        });
    }

    // 說話人檢測回調
    @Override
    public void onActiveSpeaker(String uid){
        // 說話人
        handler.post(() -> {
            String mag = "onActiveSpeaker uid:" + uid;
            ToastHelper.showToast(AudioBasicUsageActivity.this, mag, Toast.LENGTH_SHORT);
        });
    }
};
// 註冊回調
mAliRtcEngine.registerAudioVolumeObserver(mAliRtcAudioVolumeObserver);

func onAudioVolumeCallback(_ array: [AliRtcUserVolumeInfo]?, totalVolume: Int32) {
    // 使用者音量回調
    "onAudioVolumeCallback, totalVolume: \(totalVolume)".printLog()
}

func onActiveSpeaker(_ uid: String) {
    // 說話人回調
    "onActiveSpeaker, uid: \(uid)".printLog()
}

this.rtcEngineEventListener.onAudioVolumeCallback(
  (volumeInfo : AliRtcUserVolumeInfo[], volumeInfoCount : number, totalVolume : number) => {
    console.info(`音量回調: volumeInfo=${volumeInfo}, volumeInfoCount=${volumeInfoCount}, totalVolume=${totalVolume}`);
  }
)

this.rtcEngineEventListener.onActiveSpeaker((uid: string) => {
  console.info(`當前活動使用者: uid=${uid}`);
});

- (void)onAudioVolumeCallback:(NSArray <AliRtcUserVolumeInfo *> *)array totalVolume:(int)totalVolume {
    for(AliRtcUserVolumeInfo *info in array) {
        NSString *uid = info.uid;
        NSInteger volume = info.volume;
        dispatch_async(dispatch_get_main_queue(), ^{
            NSArray * volumeArray = [ _audioVolumeLabel.stringValue componentsSeparatedByString:@"\n"];

            if ([uid isEqualToString:@"1"]) { //遠端音量
                //遠端音量整體值
            }else if ([uid isEqualToString:@"0"] ){ //本地音量
                //本地音量顯示
            } else {

                // 遠端使用者整體音量
            }
        });
    }
}

- (void)onActiveSpeaker:(NSString *)uid {
    if ([uid isEqualToString:@"0"]) {
        [self log:[@"說話人：自己" UTF8String]];
    } else {
        NSDictionary *dic = [self.engine getUserInfo:uid];
        NSString *name = dic[@"displayName"];
        MyLog(@"說話人：%@",name);
    }
}

void CTutorialDlg::OnAudioVolumeCallback(const AliEngineUserVolumeInfo* volumeInfo, int volumeInfoCount, int totalVolume)
{
	CArray<AliEngineUserVolumeInfo*>* pArray = new CArray<AliEngineUserVolumeInfo*>;
	for (int i = 0; i < volumeInfoCount; i++)
	{
		AliEngineUserVolumeInfo* p = new AliEngineUserVolumeInfo;
		p->uid = volumeInfo[i].uid;
		p->volume = volumeInfo[i].volume;
		p->speechState = volumeInfo[i].speechState;
		p->sumVolume = volumeInfo[i].sumVolume;
		pArray->Add(p);
	}
    /* 通知UI重新整理 */
	PostMessage(MM_VOLUME_CALLBACK, (WPARAM)totalVolume, (LPARAM)pArray);
}

void CTutorialDlg::OnActiveSpeaker(const char *uid)
{
	m_strCurSpeaker = CString(uid);
    /* 通知UI重新整理  */
	PostMessage(MM_ACTIVE_SPEAKER, NULL, NULL);
}

6.1.預設音頻路由

預設音頻路由用於在入會前設定預設的音頻路由裝置，在耳機和擴音器之間選擇。如果沒有設定該功能，將預設使用擴音器。

/**
* @brief 設定預設音訊輸出是否從擴音器出聲，預設從擴音器出聲
* @param defaultToSpeakerphone
* - true: 擴音器模式(預設擴音器)
* - false: 耳機模式
* @return
* - 0: 成功
* - <0: 失敗
*/
public int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeakerphone);

6.2.當前音頻路由

當前音頻路由用於在會議當中設定當前播放的音訊裝置，在耳機和擴音器之間選擇。如果沒有設定該功能， 將使用預設音頻路由所設定的裝置進行播放。

在沒有外置裝置的情況下，使用者可以調用enableSpeakerphone設定當前是否使用擴音器，設定為否則使用耳機。如果需要檢查當前的音訊裝置為擴音器或耳機，可以調用isSpeakerOn介面。

/**
 * @brief 設定音訊輸出為耳機還是擴音器
 * @param enable   true:擴音器模式（預設擴音器）；false:耳機模式
 * @return
 * - 0: 成功
 * - <0: 失敗
 */
public int enableSpeakerphone(boolean enable);
/**
* @brief 擷取當前音訊輸出為耳機還是擴音器
* @return 
* - true: 擴音器模式；
* - false: 耳機模式
*/
public boolean isSpeakerOn();

6.3.音頻路由裝置變化回調

如果想擷取音頻播放裝置切換時的回調需要註冊並監聽以下回調。

public abstract class AliRtcEngineEventListener {
    /**
     * @brief 警告通知
     * @details 如果engine出現warning，通過這個回調通知app
     * @param warn 警告類型
     * @param message 警告訊息
     */
    public void onOccurWarning(int warn, String message);
}

warn傳回值和裝置類型對應關係如下表：