游戏语音

1 功能简介

1.1 概念解释

• 范围：收听者接收音频的范围。
• 方位：指收听者在游戏世界坐标中的位置和朝向，详情可参考 5.5 设置收听者的当前位置。
• 收听者：房间内接收音频的用户
• 发声者：房间内发送音频的用户。

1.2 功能描述

ZEGO Express SDK 从 2.11.0 版本起，新增游戏语音模块，主要包括：范围语音、3D 音效、小队语音。

功能	说明
范围语音	房间内的收听者对音频的接收距离有范围限制，若发声者与自己的距离超过该范围，则无法听到声音。为保证语音清晰，附近超过 20 人发声时，只能听到离自己最近的 20 个发声者的声音。 假如设置音频接收距离的最大范围为 R，若发声者离收听者的距离为 r，则： 当 r < R 时，表示发声者在正常范围内，收听者可以听到声音。 当 r ≥ R 时，表示发声者超出了最大范围，收听者无法听到声音。 上图仅以范围语音模式为“全世界”时为例，更多不同模式组合关系下的声音可达情况请参考 5.10.2 设置通用语音模式。
3D 音效	声音有 3D 空间感，且按距离衰减。
通用语音模式	玩家可以选择加入小队，并支持在房间内自由切换“全世界”、“仅小队”、“隐秘小队”语音模式。 全世界：玩家能与世界范围内其他玩家互相通话，同时能够与队友相互通话。 仅小队：玩家仅与队友互相通话。 隐秘小队：玩家可与队友互相通话，能且仅能听到世界范围内其他玩家的语音。 队友之间的通话不受“范围”和 “3D 音效” 的影响，详情请查看 5.10.2 设置通用语音模式。 如果您希望自定义语音收发能力，请参考 5.10.3 设置自定义语音模式。

1.3 适用场景

游戏语音功能适用于吃鸡类游戏、元宇宙类场景。

在吃鸡类游戏中，小队语音提供编队功能，在游戏开始前和开始后都可以更换小队，开发者无需关注流分组以及推拉流的实现，直接实现小队语音功能。

在吃鸡游戏和元宇宙场景中，提供 3D 音效能力，在收听发声者音效时，有方向感距离感，让场景感受更真实。

2 下载示例源码

请参考 下载示例源码 获取源码。

相关源码请查看 “src/Examples/Others/RangeAudio” 目录下的文件。

3 前提条件

在实现范围语音之前，请确保：

• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 Server 地址，详情请参考 控制台 - 项目信息。
• 已在项目中集成 ZEGO Express SDK，并实现了基本的音视频推拉流功能，详情请参考 快速开始 - 集成 和 快速开始 - 实现流程。

并确保开发环境满足以下要求：

• 准备一台可以连接到互联网的 Windows 或 macOS 计算机。
• 推荐使用 56 或以上版本的 Chrome 浏览器，不同浏览器的兼容性说明请参考 7 浏览器兼容性。

4 注意事项

如果您已经使用 ZEGO Express SDK 的实时音视频功能，需要注意以下事项：

• 由于范围语音功能模块是基于 ZegoExpressEngine 的推拉流接口功能来实现的，使用时无需关注推拉流的概念。在范围语音场景下，推音频流的概念转变为“开启麦克风”，拉音频流的概念转变为“开启扬声器”。建议您不要在接入范围语音功能的同时再使用 startPublishingStream、startPlayingStream 接口做推拉流操作，避免效果冲突。
• 范围语音功能模块中推拉流的相关回调（publisherStateUpdate 和 playerStateUpdate）不再生效。
• 范围语音功能模块中调用 ZegoExpressEngine 的 on 接口注册了 roomStreamUpdate 和 streamExtraInfoUpdate 事件回调后，您接入范围语音功能时请勿调用 ZegoExpressEngine 的 off 接口把所有事件回调注销了。

5 使用步骤

上图仅展示了实现游戏语音功能的核心步骤与接口，开发者可以根据业务需要，参考下文文档的详细介绍，实现其他相关接口。

5.1 导入 SDK

1. 执行 npm i zego-express-engine-webrtc 命令安装依赖。

2. 在 “index.js” 文件中引入 SDK。

import { ZegoExpressEngine } from 'zego-express-engine-webrtc'

5.2 创建引擎

1. 创建引擎

创建 ZegoExpressEngine 引擎实例，将申请到的 AppID 传入参数 appID，将接入服务器地址传入参数 server。

初始化 ZegoExpressEngine 实例 zg 和范围语音功能实例 rangeAudio。

const zg = new ZegoExpressEngine(appID, server);
const rangeAudio = zg.createRangeAudioInstance();

2. 监听范围语音事件回调

如果需要注册回调，开发者可根据实际需要，实现 ZegoRangeAudioEvent 中的某些方法，通过范围语音实例 rangeAudio 可调用 on 接口设置回调。

rangeAudio.on("microphoneStateUpdate", (state, errorCode, extendedData) => {
  if (state === 0) {
    // 关闭麦克风声音
  } else if(state === 1) {
    // 开启麦克风中
  } else if(state === 2) {
    // 打开麦克风发送声音
  }
})

5.3 兼容不允许自动播放声音的浏览器

通过 isAudioContextRunning 接口判断浏览器是否支持自动播放声音，如果 isSupport 为 false，可以引导用户点击界面的 DOM 元素来触发点击事件，并在点击事件中调用 resumeAudioContext 接口来启动自动播放。

<button onclick="enableAutoPlay()">Click me</button>

const isSupport = rangeAudio.isAudioContextRunning();

async function enableAutoPlay() {
    // result 标识是否启用成功
    const result = await rangeAudio.resumeAudioContext();
}

5.4 登录房间

1. 获取登录 Token

登录房间需要用于验证身份的 Token，获取方式请参考 用户权限控制。如需快速调试，可使用控制台生成临时 Token。

2. 登录房间

通过 ZegoExpressEngine 实例 zg 调用 loginRoom 接口，传入房间 ID 参数 roomID、token 和用户参数 user，根据实际情况传入参数 config，登录房间。

// 登录房间，成功则返回 true
const result = await zg.loginRoom(roomID, token, {userID, userName});

5.5 设置收听者的当前位置

调用 updateSelfPosition 接口可以添加自身方位，或者在自身方位发生变化时更新自己在世界坐标系中的位置和朝向。

const position = [0,0,0];
const axisForward = [1,0,0];
const axisRight = [0,1,0];
const axisUp = [0,0,1];

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

5.6 添加或更新发声者位置信息

登录房间成功后调用 updateAudioSource 接口来更新发声者位置。

const userID = "other";
const position = [1,0,0];
rangeAudio.updateAudioSource(userID, position);

5.7 （可选）设置音频接收距离

rangeAudio.setAudioReceiveRange(100);

5.8 （可选）实现 3D 音效

// enable 为 true 表示开启，为 false 表示关闭。默认是关闭。
rangeAudio.enableSpatializer(true); 

5.9 开启麦克风、扬声器

登录房间成功后：

• 调用 enableMicrophone 接口设置是否开启麦克风，当 enable 取值为 true 时表示开启，取值为 false 时表示关闭。（可随时开启或关闭）

  开发者可以通过监听 microphoneStateUpdate 事件回调，获取麦克风更新后的状态。

• 调用 enableSpeaker 接口设置是否开启扬声器，enable 取值为 true 时表示开始拉取和播放音频流，为 “false” 时表示停止拉取和播放音频流。（可随时开启或关闭）

rangeAudio.on("microphoneStateUpdate", (state, errorCode, extendedData) => {
  if (state === 0) {
    // 关闭麦克风声音
  } else if(state === 1) {
    // 开启麦克风中
  } else if(state === 2) {
    // 已打开麦克风发送声音
  }
})
// 开启麦克风，enable 为 true 表示开启，为 false 表示关闭。
rangeAudio.enableMicrophone(enable);

// 开启扬声器，enable 为 true 表示开启，为 false 表示关闭。
rangeAudio.enableSpeaker(enable);

5.10 （可选）加入小队、设置语音模式

// 参数 teamID 传入字符串表示加入对应 teamID 的小队。
rangeAudio.setTeamID("teamID");
// 参数 teamID 不传或者传 undefined 表示退出小队。
rangeAudio.setTeamID();

// 参数 mode 可传 0 或 1。
// 0 为世界模式，可与登录房间内的所有人交流。
// 1 为仅小队模式，只与小队内的队员交流。
rangeAudio.setRangeAudioMode(1);

zg.setRangeAudioCustomMode(0, 0);

5.11 退出房间

调用 logoutRoom 接口退出房间，退出后将自动关闭麦克风和扬声器（即无法发送自己的音频，也无法收听别人的声音），并清空发声者信息列表。

zg.logoutRoom(roomID)

6 常见问题

1. 收听范围内的流最多支持同时拉多少路？

范围语音最多支持同时拉 20 路流。

为保证语音清晰，附近超过 20 人发声时，只能听到离自己最近的 20 个发声者的声音。如果超过 20 人且距离一样，则按照调用 updateAudioSource 接口时，每个 userID 首次传入的先后顺序而定。

2. 范围语音的“范围”指的是收听范围还是发声范围？

范围语音的“范围”指的是收听范围。

3. 小队语音中的成员连麦有 3D 音效吗？

小队中的语音是普通连麦的效果，暂无 3D 音效。

4. 若本身就在调用推流接口，此时需要使用范围语音会存在冲突吗？

范围语音当前使用主路发送音频，如果客户已经使用主路，则会存在冲突。

7 浏览器兼容性

• 范围语音的浏览器兼容性请参考 ZEGO Express Web SDK 支持哪些浏览器 。
• 3D 音效的浏览器兼容性如下：

  浏览器	兼容性
  Chrome	14 及以上
  Edge	79 及以上
  Firefox	53 及以上
  Opera	15 及以上
  IE	不支持
  Safari	14.1 及以上
  WebView Android	55 及以上
  Firefox for Android	53 及以上
  Opera Android	42 及以上
  Safari on iOS	14.5 及以上
  Samsung Internet	6.0 及以上