音視頻進階教程｜如何實作游戲中的實時語音

1 游戲實時語音功能簡介

1.1 游戲實時語音概念解釋

• 范圍：收聽者接收音頻的范圍，
• 方位：指收聽者在游戲世界坐標中的位置和朝向，詳情可參考 5.5 初始化設定 中的“步驟 1”，
• 收聽者：房間內接收音頻的用戶
• 發聲者：房間內發送音頻的用戶，

1.2 游戲實時語音功能描述

ZEGO Express SDK 從 2.11.0 版本起，新增游戲語音模塊，主要包括：范圍語音、3D 音效、小隊語音，適用于吃雞類游戲、元宇宙類場景，

在吃雞類游戲中，小隊語音提供編隊功能，在游戲開始前和開始后都可以更換小隊，開發者無需關注流分組以及推拉流的實作，直接實作小隊語音功能，

在吃雞游戲和元宇宙場景中，提供 3D 音效能力，在收聽發聲者音效時，有方向感距離感，讓場景感受更真實，

實作游戲中的范圍語音

房間內的收聽者對音頻的接收距離有范圍限制，若發聲者與自己的距離超過該范圍，則無法聽到聲音，為保證語音清晰，附近超過 20 人發聲時，只能聽到離自己最近的 20 個發聲者的聲音，

假如設定音頻接收距離的最大范圍為 R，若發聲者離收聽者的距離為 r，則：

a. 當 r < R 時，表示發聲者在正常范圍內，收聽者可以聽到聲音，

b. 當 r ≥ R 時，表示發聲者超出了最大范圍，收聽者無法聽到聲音，

下圖僅以范圍語音模式為“全世界”時為例，更多不同模式組合關系下的聲音可達情況請參考 5.9 （可選）設定小隊語音功能 中的“步驟 2”，

游戲實時音視頻的3D音效

聲音有 3D 空間感且按距離衰減，

游戲小隊模式語音

玩家可以選擇加入小隊，并支持在房間內自由切換“全世界”模式、“僅小隊”模式、“隱秘小隊”模式，

• 全世界：玩家可與隊友互相通話，同時能與范圍內同為全世界模式的玩家互相通話，
• 僅小隊：玩家只能與隊友互相通話，
• 隱秘小隊：玩家可與隊友互相通話，但只能單向接收范圍內全世界模式的玩家的語音，

2 游戲范圍語音功能-示例原始碼下載

請參考 下載示例原始碼 獲取原始碼，

相關原始碼請查看 “/ZegoExpressExample/Examples/AdvancedAudioProcessing/RangeAudio” 目錄下的檔案，

3 游戲范圍語音功能實作的前提條件

在實作范圍語音之前，請確保：

• 已在專案中集成 ZEGO Express SDK，實作基本的實時音視頻功能，詳情請參考 快速開始 - 集成 和 快速開始 - 實作視頻通話，
• 已在 ZEGO 控制臺 創建專案，并申請有效的 AppID 和 AppSign，詳情請參考 控制臺 - 專案管理 中的“專案資訊”，

4 范圍語音實作的注意事項

使用范圍語音功能時請務必關注如下注意事項，以免影響接入，

如果您已經使用 ZEGO Express SDK 的實時音視頻功能，需要注意以下事項：

• 由于范圍語音功能模塊是基于 ZegoExpressEngine 的推拉流介面功能來實作的，使用時無需關注推拉流的概念，在范圍語音場景下，推音頻流的概念轉變為“開啟麥克風”，拉音頻流的概念轉變為“開啟揚聲器”，建議您不要在接入范圍語音功能的同時再使用 startPublishingStream、startPlayingStream 介面做推拉流操作，避免效果沖突，

5 實時音視頻-范圍語音SDK的使用步驟

5.1 范圍語音SDK創建引擎

呼叫 createEngine 介面，將申請到到 AppID 和 AppSign 傳入引數 “appID” 和 “appSign”，創建引擎單例物件，引擎當前只支持同時創建一個實體，超出后將回傳 null，

/** 定義 SDK 引擎物件 */
ZegoExpressEngine engine;

ZegoEngineProfile profile = new ZegoEngineProfile();
/** 請通過官網注冊獲取，格式為 123456789L */
profile.appID = appID;
/** 64個字符，請通過官網注冊獲取，格式為"0123456789012345678901234567890123456789012345678901234567890123" */
profile.appSign = appSign;
/** 通用場景接入 */
profile.scenario = ZegoScenario.GENERAL;
/** 設定app的application 物件 */
profile.application = getApplication();
/** 創建引擎 */
engine = ZegoExpressEngine.createEngine(profile, null);

5.2 游戲語音創建范圍語音模塊

呼叫的 createRangeAudio 方法創建范圍語音實體，

ZegoRangeAudio rangAudio = engine.createRangeAudio();
if (rangAudio == null) {
    printf("創建范圍語音實體模塊失敗");
}

5.3 監聽范圍語音事件回呼

可以根據需要呼叫 setEventHandler 介面為麥克風設定事件回呼，用于監聽麥克風的開啟狀態 onRangeAudioMicrophoneStateUpdate 通知，

// set range audio event handler
rangeAudio.setEventHandler(new IZegoRangeAudioEventHandler() {
    @Override
    public void onRangeAudioMicrophoneStateUpdate(ZegoRangeAudio rangeAudio, ZegoRangeAudioMicrophoneState state, int errorCode) {
        super.onRangeAudioMicrophoneStateUpdate(rangeAudio, state, errorCode);
        AppLogger.getInstance().callApi("microphone state update. state: %s, errorCode: %d", state, errorCode);
    }
});

5.4 登錄房間

傳入用戶 ID 引數 userID 和 userName 創建 ZegoUser 用戶物件后，呼叫 loginRoom 介面，傳入房間 ID 引數 roomID 和用戶引數 user，登錄房間，

• 同一個 AppID 內，需保證 roomID 全域唯一，
• 同一個 AppID 內，需保證 userID 全域唯一，建議開發者將其設定成一個有意義的值，可將 userID 與自己業務賬號系統進行關聯，
• userID 與 userName 不能為空，否則會導致登錄房間失敗，

/** 創建用戶 */
ZegoUser user = new ZegoUser("user1");

/** 開始登錄房間 */
engine.loginRoom("room1", user);

當用戶已成功登錄房間后，如果應用例外退出，在重啟應用后，開發者需先呼叫 logoutRoom 介面退出房間，再呼叫 loginRoom 介面重新登錄房間，

5.5 初始化設定

1. 設定聽者自身所在位置和朝向

開發者可以通過呼叫 updateSelfPosition 介面，設定聽者自身的所在位置和方位，或者在自身方位發生變化時更新自己在世界坐標系中的位置和朝向，

• 在呼叫 enableSpeaker 打開揚聲器之前如果沒有呼叫該介面設定位置資訊，則無法接收除小隊以外其他人的聲音，
• 自身坐標系三個軸的坐標值可以通過第三方 3D 引擎的旋轉角度換算矩陣得到，

// 自身在世界坐標系中的坐標，順序是前、右、上，
float[] position = new float[]{100.0, 100.0, 100.0};
// 自身坐標系前朝向的單位向量，
float[] axisForward = new float[]{1.0,0.0,0.0};
// 自身坐標系右朝向的單位向量，
float[] axisRight = new float[]{0.0,1.0,0.0};
// 自身坐標系上朝向的單位向量，
float[] axisUp = new float[]{0.0,0.0,1.0};

rangAudio.updateSelfPosition(position, axisForward, axisRight, axisUp);

2. （可選）設定音頻接收距離的最大范圍

呼叫 setAudioReceiveRange 介面設定聽者接收音頻距離的最大范圍，即以自身為起點，3D 空間中以設定的距離為立體空間，設定該范圍后，在開啟 3D 音效的情況下，聲音將會隨距離的增加而衰減，直至超出所設定的范圍，則不再有聲音，小隊內的語音，不會受到該值的限制，也不會有 3D 音效，

如果不設定，則表示只能接收本小隊內的成員聲音，無法接收小隊外的所有聲音，

rangAudio.setAudioReceiveRange(1000);

3. （可選）設定是否開啟 3D 音效

呼叫 enableSpatializer 介面設定 3D 音效，enable 取值為 true 時表示開啟 3D 音效，此時房間內非小隊成員的音頻，會隨著發聲者離自身的距離和方向的變化而產生空間感的變化，為 false 時表示關閉 3D 音效，（可隨時開啟或關閉）

該功能只對小隊以外的人生效，

rangAudio.enableSpatializer(true);

5.6 添加或更新發聲者位置資訊

登錄房間成功后，需要通過呼叫 updateAudioSource 介面，添加或更新發聲者的位置資訊，

• 全世界模式下：需要更新房間內，收聽者和所有發聲者的位置，隱秘小隊模式下：需要更新房間內，所有在音頻接收范圍內，且為全世界模式的發聲者的位置，如果未設定發聲者位置，或者發聲者超出收聽者范圍，會出現聽不到聲音的情況，

• 這里發聲者指的是房間內其他人，收聽者指的是自己，

• userID：為房間內其他發聲用戶的 ID，

• position：發聲者在世界坐標系中的坐標，引數是長度為 3 的 float 陣列，三個值依次表示前、右、上的坐標值，

// 用戶在世界坐標系中的坐標，順序是前、右、上，
float[] position = new float[]{100.0, 100.0, 100.0};
// 添加/更新用戶位置
rangAudio.updateAudioSource("abc",position);

5.7 設定是否開啟麥克風

登錄房間成功后呼叫 enableMicrophone 介面設定是否開啟麥克風，當 enable 取值為 true 時表示開啟，此時 SDK 將會自動使用主通道推音頻流，為 false 時表示關閉，（可隨時開啟或關閉）

需要通過監聽 onRangeAudioMicrophoneStateUpdate 事件回呼來獲取麥克風更新后的狀態，

rangAudio.enableMicrophone(true);

5.8 設定是否開啟揚聲器

登錄房間成功后呼叫 enableSpeaker 介面設定是否開啟揚聲器，enable 取值為 true 時表示開啟，此時將會自動拉取房間內的音頻流，為 false 時表示關閉，（可隨時開啟或關閉）

當超過最大拉流數限制（目前為 20 路）時，會優先拉取小隊內成員音頻流（需設定小隊模式），再拉取世界內距離自身范圍最近的音頻流，

rangAudio.enableSpeaker(true);

5.9 （可選）設定小隊語音功能

1. 設定隊伍 ID

呼叫 setTeamID 介面可根據需要設定想要加入的小隊 ID（可隨時變更 ID），設定 ID 后即可直接加入，加入小隊后，與同一小隊內隊員之間的交流不受范圍語音和 3D 音效的限制，

rangAudio.setTeamID("123");

2. 設定語音模式

呼叫 setRangeAudioMode) 介面設定范圍語音模式（可隨時切換模式），mode 引數取值為 ZegoRangeAudioModeWorld 或 ZegoRangeAudioSecretTeam 時表示可以聽到所有處于世界模式的人的聲音，取值為 ZegoRangeAudioModeTeam 時表示只能聽到同一小隊內其他成員的聲音，

rangeAudio.setRangeAudioMode(ZegoRangeAudioMode.WORLD);

不同范圍語音模式下，發聲者聲音的可接收情況有所不同，

• 假設 A 用戶的模式為 “全世界”，則 B 用戶在不同范圍語音模式下的聲音可接收情況如下：

• 假設 A 用戶的模式為 “僅小隊”，則 B 用戶在不同范圍語音模式下的聲音可接收情況如下：

• 假設 A 用戶的模式為 “隱秘小隊”，則 B 用戶在不同范圍語音模式下的聲音可接收情況如下：

5.10 銷毀范圍語音模塊

當不再使用范圍語音模塊時可呼叫 destroyRangeAudio 介面銷毀，釋放范圍語音模塊占用的資源，

engine.destroyRangeAudio(rangAudio);

5.11 退出房間

呼叫 logoutRoom 介面退出房間，退出后將自動關閉麥克風和揚聲器（即無法發送自己的音頻，也無法收聽別人的聲音），并清空發聲者資訊串列，

// 退出房間
engine.logoutRoom("roomID");

5 獲取 范圍語音 更多幫助

獲取本文 實時音視頻-范圍語音 的開發檔案、技術支持，訪問即構檔案中心開發檔案頁，適合對語音音效要求較高的小游戲，元宇宙類場景，

標籤：Java

上一篇：列舉與介面常量、類常量有什么區別？

下一篇：PHP微信掃碼登錄