游戏语音

功能简介

概念解释

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

功能描述

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

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

适用场景

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

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

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

示例源码下载

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

相关源码请查看 “Assets/ZegoExpressExample/Examples/AdvancedAudioProcessing/RangeAudio.cs” 文件。

前提条件

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

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

注意事项

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

• 由于范围语音功能模块是基于 ZegoExpressEngine 的推拉流接口功能来实现的，使用时无需关注推拉流的概念。在范围语音场景下，推音频流的概念转变为“开启麦克风”，拉音频流的概念转变为“开启扬声器”。建议您不要在接入范围语音功能的同时再使用 StartPublishingStream、StartPlayingStream 接口做推拉流操作，避免效果冲突。
• 范围语音功能模块中推拉流的相关回调（OnPublisherStateUpdate 、OnPlayerStateUpdate、OnPublisherQualityUpdate 和 OnPlayerQualityUpdate）不再生效。

使用步骤

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

1 创建引擎

调用 CreateEngine 接口，将申请到到 AppID 传入参数 appID，创建引擎单例对象。引擎当前只支持同时创建一个实例，超出后将返回 null。

ZegoEngineProfile profile = new ZegoEngineProfile();
// AppID 由 ZEGO 分配给各 App
profile.appID = appID;
profile.scenario = ZegoScenario::ZEGO_SCENARIO_GENERAL;
// 创建引擎实例
ZegoExpressEngine engine = ZegoExpressEngine.createEngine(profile);
if (engine == null) {
    //创建引擎失败
    return;
}

ZegoEngineProfile profile = new ZegoEngineProfile();
// AppID 由 ZEGO 分配给各 App
profile.appID = appID;
profile.scenario = ZegoScenario::ZEGO_SCENARIO_GENERAL;
// 创建引擎实例
ZegoExpressEngine engine = ZegoExpressEngine.createEngine(profile);
if (engine == null) {
    //创建引擎失败
    return;
}

2 创建范围语音模块

调用的 CreateRangeAudio 方法创建范围语音实例。

ZegoRangeAudio rangeAudio = engine.CreateRangeAudio();
if (rangeAudio == null) {
    // 创建范围语音实例模块失败
}

ZegoRangeAudio rangeAudio = engine.CreateRangeAudio();
if (rangeAudio == null) {
    // 创建范围语音实例模块失败
}

3 监听范围语音事件回调

可以根据需要设置麦克风事件回调委托，用于监听麦克风的开启状态 OnRangeAudioMicrophoneStateUpdate 通知。

// 播放器播放某音效的状态变更回调
void OnRangeAudioMicrophoneStateUpdate(ZegoRangeAudio rangeAudio, ZegoRangeAudioMicrophoneState state, int errorCode){
    if(TurningOn == state)
    {
        //麦克风打开中
    }
    else if(Off == state)
    {
        //麦克风关闭
    }
    else if(On == state)
    {
        //麦克风已成功打开
    }
}

rangeAudio.onRangeAudioMicrophoneStateUpdate = OnRangeAudioMicrophoneStateUpdate;

// 播放器播放某音效的状态变更回调
void OnRangeAudioMicrophoneStateUpdate(ZegoRangeAudio rangeAudio, ZegoRangeAudioMicrophoneState state, int errorCode){
    if(TurningOn == state)
    {
        //麦克风打开中
    }
    else if(Off == state)
    {
        //麦克风关闭
    }
    else if(On == state)
    {
        //麦克风已成功打开
    }
}

rangeAudio.onRangeAudioMicrophoneStateUpdate = OnRangeAudioMicrophoneStateUpdate;

4 登录房间

传入用户 ID 参数 userID 和 userName 创建 ZegoUser 用户对象后，调用 LoginRoom 接口，传入房间 ID 参数 roomID 和用户参数 user，登录房间。

ZegoUser user = new ZegoUser();
user.userID = "test";
user.userName = "testName";

ZegoRoomConfig roomConfig = new ZegoRoomConfig();
engine.LoginRoom("123",user,roomConfig);

ZegoUser user = new ZegoUser();
user.userID = "test";
user.userName = "testName";

ZegoRoomConfig roomConfig = new ZegoRoomConfig();
engine.LoginRoom("123",user,roomConfig);

5 设置收听者的当前位置

开发者可以通过调用 UpdateSelfPosition 接口，设置听者自身的所在位置和方位，或者在自身方位发生变化时更新自己在世界坐标系中的位置和朝向。

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

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

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

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

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

登录房间成功后，可以通过调用 UpdateAudioSource 接口，添加或更新发声者的位置信息。

• userID：为房间内其他发声用户的 ID。
• position：发声者在世界坐标系中的坐标，参数是长度为 3 的 float 数组，三个值依次表示前、右、上的坐标值。

// 用户在世界坐标系中的坐标，顺序是前、右、上。
float position[] = new float[3]{100.0, 100.0, 100.0};
// 添加/更新用户位置
rangeAudio.UpdateAudioSource("abc",position);

// 用户在世界坐标系中的坐标，顺序是前、右、上。
float position[] = new float[3]{100.0, 100.0, 100.0};
// 添加/更新用户位置
rangeAudio.UpdateAudioSource("abc",position);

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

// 设置音频接收距离的最大范围，超过该范围的音源声音会听不见
rangeAudio.SetAudioReceiveRange(1000);

// 设置音频接收距离的最大范围，超过该范围的音源声音会听不见
rangeAudio.SetAudioReceiveRange(1000);

// 设置 3D 音效的衰减范围区间 [min, max]
ZegoReceiveRangeParam param = new ZegoReceiveRangeParam();
param.min = reciveRangeMin;
param.max = reciveRangeMax;
rangeAudio.SetAudioReceiveRange(param);

// 设置 3D 音效的衰减范围区间 [min, max]
ZegoReceiveRangeParam param = new ZegoReceiveRangeParam();
param.min = reciveRangeMin;
param.max = reciveRangeMax;
rangeAudio.SetAudioReceiveRange(param);

8（可选）实现 3D 音效

rangeAudio.EnableSpatializer(true);

rangeAudio.EnableSpatializer(true);

9 开启麦克风、扬声器

登录房间成功后：

• 调用 EnableMicrophone 接口设置是否开启麦克风，当 enable 取值为 true 时表示开启，此时 SDK 将会自动使用主通道推音频流，为 false 时表示关闭。（可随时开启或关闭）

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

• 调用 EnableSpeaker 接口设置是否开启扬声器，enable 取值为 true 时表示开启，此时将会自动拉取房间内的音频流，为 false 时表示关闭。（可随时开启或关闭）

// 开启麦克风
rangeAudio.EnableMicrophone(true);
// 开启扬声器
rangeAudio.EnableSpeaker(true);

// 开启麦克风
rangeAudio.EnableMicrophone(true);
// 开启扬声器
rangeAudio.EnableSpeaker(true);

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

rangeAudio.SetTeamID("123");

rangeAudio.SetTeamID("123");

rangeAudio.SetRangeAudioMode(ZegoRangeAudioMode.World);

rangeAudio.SetRangeAudioMode(ZegoRangeAudioMode.World);

11 销毁范围语音模块

当不再使用范围语音模块时可调用 DestroyRangeAudio 接口销毁，释放范围语音模块占用的资源。

engine.DestroyRangeAudio(rangeAudio);

engine.DestroyRangeAudio(rangeAudio);

12 退出房间

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

// 退出房间
engine.LogoutRoom("roomID");

// 退出房间
engine.LogoutRoom("roomID");

常见问题

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

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

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

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

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

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

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

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