# 空间音频 (/zh-CN/realtime-media/rtc/build/audio/spatial-audio) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" /> 空间音频能够将真实世界的声音体验带到虚拟数字世界，为用户提供更具吸引力的在线体验。通过声网提供的空间音频技术，你可以在虚拟互动场景下模拟声音在现实环境中的传播特点： **超拟真空间塑造效果** 利用范围音频、声音模糊、空气衰减模拟等技术，完美模拟现实听觉感受。 - 当声源和其他角色之间的距离、方位或朝向发生变化时，不同的角色听到的声音大小和方向均不相同。 - 当声源和其他角色之间的距离超过设置的范围后，后者无法听到声源发出的声音。 - 通过设置隔声区域、空气衰减、声音模糊等音效，完美模拟现实的听觉感受。 **3D 高保真** - 根据面部朝向、音源朝向、3D 空间内音源的相对位置进行音效处理渲染。 - 支持 48 kHz 全频带采样和 3D 高保真音效处理及渲染。 **多平台适配** 支持 iOS、Android、macOS、Windows、Web、Unity、Flutter、React Native、Electron、Unreal 等平台。 **超低延时、低功耗、低成本** 空间音频算法采用先进的前端处理模式，并通过云服务同步空间坐标，端云协同处理模式能够有效降低整体延时和功耗。相比传统的左右声道立体声，声网提供的空间音频技术在声音的立体感和空间感上都有明显的提升，两者区别如下所示： | 对比项 | 传统立体声 | 声网空间音频 | | -------- | -------------------------------------------- | --------------------------------------------------- | | 立体感 | 左右两个维度 | 以世界坐标系的 x、y、z 坐标轴表示右、上、前三个维度 | | 空间感 | 通过调节左右声道的音量，体现具有空间感的声音 | 使用空间音频算法，通过设置距离、方位、朝向等参数，塑造声音的空间感 | | 用户体验 | 平面 | 立体、自然、真实 | ## 适用场景 [#适用场景] #### 社交语聊 [#社交语聊] 在语聊房 App 界面中，以九宫格的形式展示所有用户头像，并对每个用户赋予一个坐标和朝向。在互动过程中，你可以感受到周围的用户发出的声音大小和方位跟其所在的位置有关。如果你在屏幕中拖动自己的头像，随着你跟某个用户之间的距离逐渐变远，你会听到该用户的声音也越来越小，超出一定范围后会彻底听不到，符合现实环境中声音的传播特点。 #### 游戏 & 元宇宙 [#游戏--元宇宙] 在游戏和元宇宙这类 3D 场景中，你可以使用空间音频技术实现更多功能，如下表所示： | 功能 | 描述 | | --- | --- | | 声音模糊 | 对指定远端用户或媒体播放器开启声音模糊处理。例如：在咖啡厅场景中，如果需要制造两个虚拟角色 “说悄悄话” 的效果，可以对他们开启声音模糊处理模式，其他角色会听到被处理过的、模糊的声音。 | | 范围音频 | [spatial-audio-android-html-0-2-1 details](#table-slot-spatial-audio-android-html-0-2-1) | | 超拟真空间塑造 | [spatial-audio-android-html-0-3-1 details](#table-slot-spatial-audio-android-html-0-3-1) | | 隔声区域 | 定义一个隔声区域并对隔声区域内的音源设置声音衰减系数，使区域外的接收方听区域内的音源时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。例如：在 KTV 场景中，当虚拟角色在 KTV 包厢外时，只能听到来自包厢内的较小的声音；在打开包厢门的时候，会在一瞬间体验到包厢里唱歌的声音迎面扑来。 | **spatial-audio-android-html-0-2-1 details** 根据当前场景的大小设置一个音频接收范围，在该范围以内，声音传播得越远，接收方听到的声音越小。你可以通过设置声音衰减系数，在不同的场景下获得更加拟真的衰减效果： - 在丛林场景中，将衰减系数设置为 0.9，声音在传播时迅速衰减。 - 在平原场景中，将衰减系数设置为 0.1，声音可以传播得很远。 **spatial-audio-android-html-0-3-1 details** 为全方位模拟真实场景的空间感，对每个虚拟角色赋予 4 组坐标，分别表示以下维度： - 虚拟角色空间坐标（x,y,z）：虚拟角色在 3D 空间里的坐标。 - 虚拟角色面部朝向坐标（x,y,z）：虚拟角色在场景中的面部朝向坐标。 - 虚拟角色头顶朝向坐标（x,y,z）：虚拟角色的头顶指向的坐标，可结合面部朝向坐标确定虚拟角色的动作和姿态。例如：虚拟角色平躺的时候，面部朝向天空，头顶朝向前方。 - 右手朝向（x,y,z）：直角坐标系是使用左手坐标系还是右手坐标系。在一个场景中只能使用一种坐标系。 #### 在线会议 [#在线会议] 在线会议场景下，你可以将所有上麦用户分布到主持人的周围，并赋予每个用户坐标。用户听到的每个声音都有方向感和空间感，模拟真实环境下的会议室体验，相比传统在线会议，能够带给用户全新的与会体验、降低用户疲惫感。 ## 技术原理 [#技术原理] 实现用户空间音频和媒体播放器空间音频时的原理有所不同： - 用户空间音频：自行部署服务器，用于发送本地空间位置以及接收远端用户的空间位置，然后由 SDK 计算用户间的相对位置，从而计算出相应的空间音频参数。 - 媒体播放器空间音频：通过 SDK 计算本地用户和媒体播放器的相对位置，然后计算出相应的空间音频参数。 ## 前提条件 [#前提条件] 在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 实现空间音频 [#实现空间音频] 本节介绍如何使用 SDK 实现空间音频，API 调用时序如下图所示。 ### 初始化空间音频引擎 [#初始化空间音频引擎] 调用 `ILocalSpatialAudioEngine` 类中的 `create` 和 `initialize` 初始化 `ILocalSpatialAudioEngine` 对象，开启空间音频。 ```java localSpatial = ILocalSpatialAudioEngine.create(); LocalSpatialAudioConfig localSpatialAudioConfig = new LocalSpatialAudioConfig(); localSpatialAudioConfig.mRtcEngine = engine; localSpatial.initialize(localSpatialAudioConfig); ``` ### 设置音频属性和场景 [#设置音频属性和场景] :::warning[注意] 在 Android 平台实现空间音频时，你需要在初始化空间音频引擎后设置音频属性和音频场景，以获得预期的音质效果。 ::: 1. 调用 `setAudioProfile`，将 `profile` 设置为你预期的音频编码属性。 2. 调用 `setAudioScenario`，将 `scenario` 设置为 `AUDIO_SCENARIO_GAME_STREAMING`，以获得预期的音质效果。 ```java engine.setAudioProfile(io.agora.rtc2.Constants.AUDIO_PROFILE_MUSIC_STANDARD); engine.setAudioScenario(io.agora.rtc2.Constants.AUDIO_SCENARIO_GAME_STREAMING); ``` ### 设置音频接收范围 [#设置音频接收范围] - 调用 `setMaxAudioRecvCount` 设置音频接收范围内最多可接收的音频流数，建议 `maxCount` 取值 ≤ 16。 - 调用 `setAudioRecvRange` 设置可接收音频的最大范围，单位为米，建议 `range` 取值＞ 0。 ```java localSpatial.setMaxAudioRecvCount(2); localSpatial.setAudioRecvRange(AXIS_MAX_DISTANCE); ``` ### 更新空间位置 [#更新空间位置] - 在用户空间音频场景下，调用 `updateSelfPosition` 和 `updateRemotePosition` 方法，分别更新本地用户和远端用户的位置。 - 在媒体播放器空间音频场景下，调用 `updateSelfPosition` 和 `updatePlayerPositionInfo` 方法，分别更新本地用户和媒体播放器的位置。推荐的调用时机如下所示： - 当频道内有新用户加入。 - 当本地、远端用户或媒体播放器的相对位置发生改变。 - 根据实际需求调用。 ```java // 更新本地用户位置 float[] pos = getVoicePosition(localIv); float[] forward = new float[]{1.0F, 0.0F, 0.0F}; float[] right = new float[]{0.0F, 1.0F, 0.0F}; float[] up = new float[]{0.0F, 0.0F, 1.0F}; localSpatial.updateSelfPosition(pos, forward, right, up); // 更新远端用户位置 if (remoteLeftTv.getTag() == null) { remoteLeftTv.setTag(uid); remoteLeftTv.setVisibility(View.VISIBLE); remoteLeftTv.setText(uid + ""); RemoteVoicePositionInfo info = getVoicePositionInfo(remoteLeftTv); Log.d(TAG, "left remote user >> pos=" + Arrays.toString(info.position)); localSpatial.updateRemotePosition(uid, info); remoteLeftTv.setOnClickListener(v -> showRemoteUserSettingDialog(uid)); } else if (remoteRightTv.getTag() == null) { remoteRightTv.setTag(uid); remoteRightTv.setVisibility(View.VISIBLE); remoteRightTv.setText(uid + ""); localSpatial.updateRemotePosition(uid, getVoicePositionInfo(remoteRightTv)); remoteRightTv.setOnClickListener(v -> showRemoteUserSettingDialog(uid)); } ``` ### 设置空间音频参数 [#设置空间音频参数] 调用 `setRemoteUserSpatialAudioParams` 或 `setSpatialAudioParams`，针对远端用户或媒体播放器设置空间音频参数。如果要实现特定音效，可参考如下参数设置： - 空气衰减效果：将 `enable_air_absorb` 设置为 `true`；并将 `speaker_attenuation` 设置为预期的声音衰减系数。 - 声音模糊效果：将 `enable_blur` 设置为 `true`。 ```java // 开启空气衰减效果 spatialAudioParams.enable_air_absorb = true; // 开启声音模糊效果 spatialAudioParams.enable_blur = true; // 以设置媒体播放器空间音频参数为例 engine.setRemoteUserSpatialAudioParams(uid, spatialAudioParams); ``` ### （可选）设置隔声区域 [#可选设置隔声区域] 1. 调用 `setZones` 设置一个隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟接收方分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。 1. （可选）调用 `setRemoteAudioAttenuation` 或 `setPlayerAttenuation` 分别针对用户和媒体播放器设置声音衰减属性，并指定是否使用该设置强制覆盖 `setZones` 中的声音衰减系数。 ```java SpatialAudioZone mediaPlayerLeftZone = new SpatialAudioZone(); // 隔声区域的 ID mediaPlayerLeftZone.zoneSetId = 1; // 隔声区域和外部互通时的声音衰减系数 mediaPlayerLeftZone.audioAttenuation = 1f; float[] voicePosition = getVoicePosition(zoneTv); float[] viewRelativeSizeInAxis = getViewRelativeSizeInAxis(zoneTv); // 隔声区域的空间中心点 mediaPlayerLeftZone.position = new float[]{voicePosition[0], voicePosition[1], 0}; // 以 position 为起点，向前的单位向量 mediaPlayerLeftZone.forward = new float[]{1.f, 0, 0}; // 以 position 为起点，向右的单位向量 mediaPlayerLeftZone.right = new float[]{0, 1.f, 0}; // 以 position 为起点，向上的单位向量 mediaPlayerLeftZone.up = new float[]{0, 0, 1.f}; // 隔声区域的前向长度 mediaPlayerLeftZone.forwardLength = viewRelativeSizeInAxis[1]; // 隔声区域的右向长度 mediaPlayerLeftZone.rightLength = viewRelativeSizeInAxis[0]; // 隔声区域的上向长度 mediaPlayerLeftZone.upLength = AXIS_MAX_DISTANCE; localSpatial.setZones(new SpatialAudioZone[]{mediaPlayerLeftZone}); localSpatial.setRemoteAudioAttenuation(uid, 0.5f, false); localSpatial.setPlayerAttenuation(mediaPlayer.getMediaPlayerId(), 0.5f, false); ``` ### （可选）设置耳机均衡效果 [#可选设置耳机均衡效果] 1. 调用 `setHeadphoneEQPreset` 方法，选择预设的耳机均衡器收听音频，以达到预期的音频体验。 1. （可选）如果执行上一步后仍未达到预期，你可以调用 `setHeadphoneEQParameters` 自行调节耳机均衡效果，执行该方法后，`setHeadphoneEQPreset` 方法设置的预设值会被覆盖。 ```java engine.setHeadphoneEQPreset(io.agora.rtc2.Constants.HEADPHONE_EQUALIZER_OVEREAR); engine.setHeadphoneEQParameters(10, 10); ``` ### 关闭空间音频 [#关闭空间音频] 在互动过程中，你可选择暂停或关闭空间音频。 #### 暂停指定远端用户在本地的空间音频 [#暂停指定远端用户在本地的空间音频] 1. 如果不想继续体验远端用户在本地的空间音频、或远端用户已退出频道，调用 `removeRemotePosition` 删除该用户的空间位置信息，以节省计算资源。 :::warning[注意] 当远端用户离开频道时，必须调用 `removeRemotePosition` 删除该用户的空间位置信息，否则可能导致本地听不到来自其他远端用户的空间音频。 ::: 1. （可选）如果之后想恢复该用户在本地的空间音频，可调用 `updateRemotePosition` 方法重新设置远端用户的位置信息。 ```java // 暂停指定远端用户在本地的空间音频 localSpatial.removeRemotePosition(uid) // 恢复指定远端用户在本地的空间音频 localSpatial.updateRemotePosition(uid, getVoicePositionInfo(remoteLeftTv)); ``` #### 暂停所有远端用户在本地的空间音频 [#暂停所有远端用户在本地的空间音频] 1. 如果你不想再继续体验本地的空间音频，可以调用 `clearRemotePositions` 删除所有远端用户的空间位置信息。 :::warning[注意] 调用该方法会导致本地听不到所有远端用户的音频，声网建议你谨慎调用该方法。 ::: 1. （可选）如果之后还需要听到远端用户的音频，你需要重新调用 `ILocalSpatialAudioEngine` 中的 `muteAllRemoteAudioStreams(false)` 恢复订阅远端用户的音频流。 ```java // 删除所有远端用户的空间位置信息 localSpatial.clearRemotePositions(); // 恢复订阅远端用户的音频流 localSpatial.muteAllRemoteAudioStreams(false); ``` #### 暂停本地用户在远端的空间音频 [#暂停本地用户在远端的空间音频] 1. 调用 `ILocalSpatialAudioEngine` 中的 `muteLocalAudioStream(true)`，取消发布本地音频流。 1. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `false`，即可恢复空间音频。 ```java // 取消发布本地音频流 localSpatial.muteLocalAudioStream(true); // 恢复发布本地音频流 localSpatial.muteLocalAudioStream(false); ``` #### 关闭空间音频 [#关闭空间音频-1] 1. 在频道内调用 `RtcEngine` 中的 `enableSpatialAudio` 并将参数设置为 `false`，此时所有跟空间音频相关的设置都会被重置。 1. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `true`，然后重新调用相关 API 设置空间音频效果。 1. （可选）调用 `ILocalSpatialAudioEngine` 中的 `destroy` 销毁 `ILocalSpatialAudioEngine` 对象。 ```java // 关闭空间音频 engine.enableSpatialAudio(false); // 销毁 ILocalSpatialAudioEngine 对象 localSpatial.destroy(); ``` ## 参考信息 [#参考信息] ### 示例项目 [#示例项目] 声网提供了开源的空间音频示例项目供你参考，你可以前往下载或查看其中的源代码。 SpatialSound} href="https://gitee.com/agoraio-community/API-Examples/blob/main/Android/APIExample-Audio/app/src/main/java/io/agora/api/example/examples/advanced/SpatialSound.java" /> SpatialSound} href="https://github.com/Shengwang-Community/API-Examples/blob/main/Android/APIExample-Audio/app/src/main/java/io/agora/api/example/examples/advanced/SpatialSound.java" /> ### API 参考 [#api-参考] - [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) - [`initialize`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#initialize) - [`setMaxAudioRecvCount`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setmaxaudiorecvcount) - [`setAudioRecvRange`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setaudiorecvrange) - [`updateSelfPosition`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#updateselfposition) - [`updateRemotePosition`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#updateremoteposition) - [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#updateplayerpositioninfo) - [`setRemoteUserSpatialAudioParams`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setremoteuserspatialaudioparams) - [`setSpatialAudioParams`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setspatialaudioparams) - [`setZones`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setzones) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setremoteaudioattenuation) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setplayerattenuation) - [`clearRemotePositions`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#clearremotepositions) - [`muteLocalAudioStream`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#mutelocalaudiostream) - [`muteAllRemoteAudioStreams`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#muteallremoteaudiostreams) - [`enableSpatialAudio`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#enablespatialaudio) - [`destroy`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#destroy) - [`RtcEngine`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#setheadphoneeqparameters) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" /> 空间音频能够将真实世界的声音体验带到虚拟数字世界，为用户提供更具吸引力的在线体验。通过声网提供的空间音频技术，你可以在虚拟互动场景下模拟声音在现实环境中的传播特点： **超拟真空间塑造效果** 利用范围音频、声音模糊、空气衰减模拟等技术，完美模拟现实听觉感受。 - 当声源和其他角色之间的距离、方位或朝向发生变化时，不同的角色听到的声音大小和方向均不相同。 - 当声源和其他角色之间的距离超过设置的范围后，后者无法听到声源发出的声音。 - 通过设置隔声区域、空气衰减、声音模糊等音效，完美模拟现实的听觉感受。 **3D 高保真** - 根据面部朝向、音源朝向、3D 空间内音源的相对位置进行音效处理渲染。 - 支持 48 kHz 全频带采样和 3D 高保真音效处理及渲染。 **多平台适配** 支持 iOS、Android、macOS、Windows、Web、Unity、Flutter、React Native、Electron、Unreal 等平台。 **超低延时、低功耗、低成本** 空间音频算法采用先进的前端处理模式，并通过云服务同步空间坐标，端云协同处理模式能够有效降低整体延时和功耗。相比传统的左右声道立体声，声网提供的空间音频技术在声音的立体感和空间感上都有明显的提升，两者区别如下所示： | 对比项 | 传统立体声 | 声网空间音频 | | -------- | -------------------------------------------- | --------------------------------------------------- | | 立体感 | 左右两个维度 | 以世界坐标系的 x、y、z 坐标轴表示右、上、前三个维度 | | 空间感 | 通过调节左右声道的音量，体现具有空间感的声音 | 使用空间音频算法，通过设置距离、方位、朝向等参数，塑造声音的空间感 | | 用户体验 | 平面 | 立体、自然、真实 | ## 适用场景 [#适用场景-1] #### 社交语聊 [#社交语聊-1] 在语聊房 App 界面中，以九宫格的形式展示所有用户头像，并对每个用户赋予一个坐标和朝向。在互动过程中，你可以感受到周围的用户发出的声音大小和方位跟其所在的位置有关。如果你在屏幕中拖动自己的头像，随着你跟某个用户之间的距离逐渐变远，你会听到该用户的声音也越来越小，超出一定范围后会彻底听不到，符合现实环境中声音的传播特点。 #### 游戏 & 元宇宙 [#游戏--元宇宙-1] 在游戏和元宇宙这类 3D 场景中，你可以使用空间音频技术实现更多功能，如下表所示： | 功能 | 描述 | | --- | --- | | 声音模糊 | 对指定远端用户或媒体播放器开启声音模糊处理。例如：在咖啡厅场景中，如果需要制造两个虚拟角色 “说悄悄话” 的效果，可以对他们开启声音模糊处理模式，其他角色会听到被处理过的、模糊的声音。 | | 范围音频 | [spatial-audio-macos-ios-html-0-2-1 details](#table-slot-spatial-audio-macos-ios-html-0-2-1) | | 超拟真空间塑造 | [spatial-audio-macos-ios-html-0-3-1 details](#table-slot-spatial-audio-macos-ios-html-0-3-1) | | 隔声区域 | 定义一个隔声区域并对隔声区域内的音源设置声音衰减系数，使区域外的接收方听区域内的音源时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。例如：在 KTV 场景中，当虚拟角色在 KTV 包厢外时，只能听到来自包厢内的较小的声音；在打开包厢门的时候，会在一瞬间体验到包厢里唱歌的声音迎面扑来。 | **spatial-audio-macos-ios-html-0-2-1 details** 根据当前场景的大小设置一个音频接收范围，在该范围以内，声音传播得越远，接收方听到的声音越小。你可以通过设置声音衰减系数，在不同的场景下获得更加拟真的衰减效果： - 在丛林场景中，将衰减系数设置为 0.9，声音在传播时迅速衰减。 - 在平原场景中，将衰减系数设置为 0.1，声音可以传播得很远。 **spatial-audio-macos-ios-html-0-3-1 details** 为全方位模拟真实场景的空间感，对每个虚拟角色赋予 4 组坐标，分别表示以下维度： - 虚拟角色空间坐标（x,y,z）：虚拟角色在 3D 空间里的坐标。 - 虚拟角色面部朝向坐标（x,y,z）：虚拟角色在场景中的面部朝向坐标。 - 虚拟角色头顶朝向坐标（x,y,z）：虚拟角色的头顶指向的坐标，可结合面部朝向坐标确定虚拟角色的动作和姿态。例如：虚拟角色平躺的时候，面部朝向天空，头顶朝向前方。 - 右手朝向（x,y,z）：直角坐标系是使用左手坐标系还是右手坐标系。在一个场景中只能使用一种坐标系。 #### 在线会议 [#在线会议-1] 在线会议场景下，你可以将所有上麦用户分布到主持人的周围，并赋予每个用户坐标。用户听到的每个声音都有方向感和空间感，模拟真实环境下的会议室体验，相比传统在线会议，能够带给用户全新的与会体验、降低用户疲惫感。 ## 技术原理 [#技术原理-1] 实现用户空间音频和媒体播放器空间音频时的原理有所不同： - 用户空间音频：自行部署服务器，用于发送本地空间位置以及接收远端用户的空间位置，然后由 SDK 计算用户间的相对位置，从而计算出相应的空间音频参数。 - 媒体播放器空间音频：通过 SDK 计算本地用户和媒体播放器的相对位置，然后计算出相应的空间音频参数。 ## 前提条件 [#前提条件-1] 在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 实现空间音频 [#实现空间音频-1] 本节介绍如何使用 SDK 实现空间音频，API 调用时序如下图所示。 ### 初始化空间音频引擎 [#初始化空间音频引擎-1] 调用 `AgoraLocalSpatialAudioKit` 类中 `sharedLocalSpatialAudioWithConfig` 初始化 `AgoraLocalSpatialAudioKit` 对象，开启空间音频。 ```swift agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: KeyCenter.AppId, delegate: self) let localSpatialConfig = AgoraLocalSpatialAudioConfig() localSpatialConfig.rtcEngine = agoraKit localSpatial = AgoraLocalSpatialAudioKit.sharedLocalSpatialAudio(with: localSpatialConfig) ``` ### 设置音频属性和场景 [#设置音频属性和场景-1] 1. 调用 `setAudioProfile`，将 `profile` 设置为你预期的音频编码属性。 2. 调用 `setAudioScenario`，将 `scenario` 设置为 `AgoraAudioScenarioGameStreaming`，以获得预期的音质效果。 ```swift agoraKit.setAudioProfile(.musicStandard) agoraKit.setAudioScenario(.gameStreaming) ``` ### 设置音频接收范围 [#设置音频接收范围-1] - 调用 `setMaxAudioRecvCount` 设置音频接收范围内最多可接收的音频流数，建议 `maxCount` 取值 ≤ 16。 - 调用 `setAudioRecvRange` 设置可接收音频的最大范围，单位为米，建议 `range` 取值＞ 0。 ```swift localSpatial.setMaxAudioRecvCount(2) localSpatial.setAudioRecvRange(Float(SCREENSIZE.height)) ``` ### 更新空间位置 [#更新空间位置-1] - 在用户空间音频场景下，调用 `updateSelfPosition` 和 `updateRemotePosition` 方法，分别更新本地用户和远端用户的位置。 - 在媒体播放器空间音频场景下，调用 `updateSelfPosition` 和 `updatePlayerPositionInfo` 方法，分别更新本地用户和媒体播放器的位置。推荐的调用时机如下所示： - 当频道内有新用户加入。 - 当本地、远端用户或媒体播放器的相对位置发生改变。 - 根据实际需求调用。 ```swift // 更新本地用户位置 let pos = getViewCenterPostion(view: selfPostionView) localSpatial.updateSelfPosition(pos, axisForward: forward, axisRight: right, axisUp: up) // 更新远端用户位置 if remoteUserButton1.tag <= 0 { remoteUserButton1.setTitle("\(uid)", for: .normal) remoteUserButton1.tag = Int(uid) remoteUserButton1.isHidden = false localSpatial.updateRemotePosition(uid, positionInfo: getPlayerPostion(view: remoteUserButton1)) } else if remoteUserButton2.tag <= 0 { remoteUserButton2.setTitle("\(uid)", for: .normal) remoteUserButton2.tag = Int(uid) remoteUserButton2.isHidden = false localSpatial.updateRemotePosition(uid, positionInfo: getPlayerPostion(view: remoteUserButton2)) } ``` ### 设置空间音频参数 [#设置空间音频参数-1] 调用 `setRemoteUserSpatialAudioParams` 或 `setSpatialAudioParams`，针对远端用户或媒体播放器设置空间音频参数。如果要实现特定音效，可参考如下参数设置： - 空气衰减效果：将 `enable_air_absorb` 设置为 `true`；并将 `speaker_attenuation` 设置为预期的声音衰减系数。 - 声音模糊效果：将 `enable_blur` 设置为 `true`。 ```swift // 开启空气衰减效果 let params = AgoraSpatialAudioParams() params.enable_air_absorb = true // 开启声音模糊效果 params.enable_blur = true // 以设置媒体播放器空间音频参数为例 mediaPlayer.setSpatialAudioParams(params) ``` ### （可选）设置隔声区域 [#可选设置隔声区域-1] 1. 调用 `setZones` 设置一个隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟接收方分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。 2. （可选）调用 `setRemoteAudioAttenuation` 或 `setPlayerAttenuation` 分别针对用户和媒体播放器设置声音衰减属性，并指定是否使用该设置强制覆盖 `setZones` 中的声音衰减系数。 ```swift let audioZone = AgoraSpatialAudioZone() // 隔声区域的 ID audioZone.zoneSetId = 1 // 隔声区域和外部互通时的声音衰减系数 audioZone.audioAttenuation = 1 // 以 position 为起点，向前的单位向量 audioZone.forward = forward // 以 position 为起点，向右的单位向量 audioZone.right = right // 以 position 为起点，向上的单位向量 audioZone.up = up // 隔声区域的空间中心点 audioZone.position = getViewCenterPostion(view: voiceContainerView1) // 隔声区域的前向长度 audioZone.forwardLength = Float(voiceContainerView1.frame.width) // 隔声区域的右向长度 audioZone.rightLength = Float(voiceContainerView1.frame.height) // 隔声区域的上向长度 audioZone.upLength = Float(maxDistance) localSpatial.setZones([audioZone]) localSpatial.setRemoteAudioAttenuation(uid, attenuation: 0.5, forceSet: false) localSpatial.setPlayerAttenuation(0.5, playerId: UInt(mediaPlayer.getMediaPlayerId()), forceSet: false) ``` ### （可选）设置耳机均衡效果 [#可选设置耳机均衡效果-1] 1. 调用 `setHeadphoneEQPreset` 方法，选择预设的耳机均衡器收听音频，以达到预期的音频体验。 2. （可选）如果执行上一步后仍未达到预期，你可以调用 `setHeadphoneEQParameters` 自行调节耳机均衡效果，执行该方法后，`setHeadphoneEQPreset` 方法设置的预设值会被覆盖。 ```swift agoraKit.setHeadphoneEQPreset(.overEar) agoraKit.setHeadphoneEQParameters(10, gain: 10) ``` ### 关闭空间音频 [#关闭空间音频-2] 在互动过程中，你可选择暂停或关闭空间音频。 ##### 暂停指定远端用户在本地的空间音频 [#暂停指定远端用户在本地的空间音频-1] 1. 如果不想继续体验远端用户在本地的空间音频、或远端用户已退出频道，调用 `removeRemotePosition` 删除该用户的空间位置信息，以节省计算资源。 :::warning[注意] 当远端用户离开频道时，必须调用 `removeRemotePosition` 删除该用户的空间位置信息，否则可能导致本地听不到来自其他远端用户的空间音频。 ::: 2. （可选）如果之后想恢复该用户在本地的空间音频，可调用 `updateRemotePosition` 方法重新设置远端用户的位置信息。 ```swift // 暂停指定远端用户在本地的空间音频 localSpatial.removeRemotePosition(uid) // 恢复指定远端用户在本地的空间音频 localSpatial.updateRemotePosition(uid, positionInfo: getPlayerPostion(view: remoteLeftTv)) ``` #### 暂停所有远端用户在本地的空间音频 [#暂停所有远端用户在本地的空间音频-1] 1. 如果你不想再继续体验本地的空间音频，可以调用 `clearRemotePositions` 删除所有远端用户的空间位置信息。 :::warning[注意] 调用该方法会导致本地听不到所有远端用户的音频，声网建议你谨慎调用该方法。 ::: 2. （可选）如果之后还需要听到远端用户的音频，你需要重新调用 `AgoraLocalSpatialAudioKit` 中的 `muteAllRemoteAudioStreams(false)` 恢复订阅远端用户的音频流。 ```swift // 删除所有远端用户的空间位置信息 localSpatial.clearRemotePositions() // 恢复订阅远端用户的音频流 localSpatial.muteAllRemoteAudioStreams(false) ``` #### 暂停本地用户在远端的空间音频 [#暂停本地用户在远端的空间音频-1] 1. 调用 `AgoraLocalSpatialAudioKit` 中的 `muteLocalAudioStream(true)`，取消发布本地音频流。 2. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `false`，即可恢复空间音频。 ```swift // 取消发布本地音频流 localSpatial.muteLocalAudioStream(true) // 恢复发布本地音频流 localSpatial.muteLocalAudioStream(false) ``` #### 关闭空间音频 [#关闭空间音频-3] 1. 在频道内调用 `AgoraRtcEngineKit` 中的 `enableSpatialAudio` 并将参数设置为 `false`，此时所有跟空间音频相关的设置都会被重置。 2. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `true`，然后重新调用相关 API 设置空间音频效果。 3. （可选）调用 `AgoraLocalSpatialAudioKit` 中的 `destroy` 销毁 `AgoraLocalSpatialAudioKit` 对象。 ```swift // 关闭空间音频 agoraKit.enableSpatialAudio(false) // 销毁 AgoraLocalSpatialAudioKit 对象 AgoraLocalSpatialAudioKit.destroy() ``` ## 参考信息 [#参考信息-1] ### 示例项目 [#示例项目-1] 声网提供了开源的空间音频示例项目供你参考，你可以前往下载或查看其中的源代码。 SpatialAudio} href="https://gitee.com/agoraio-community/API-Examples/blob/main/iOS/APIExample/APIExample/Examples/Advanced/SpatialAudio/SpatialAudio.swift" /> SpatialAudio} href="https://github.com/Shengwang-Community/API-Examples/blob/main/iOS/APIExample/APIExample/Examples/Advanced/SpatialAudio/SpatialAudio.swift" /> ### API 参考 [#api-参考-1] - [`AgoraLocalSpatialAudioKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_ilocalspatialaudioengine) - [`sharedLocalSpatialAudioWithConfig`](/zh-CN/api-reference/rtc/ios/initialize#api_irtcengine_initialize) - [`setMaxAudioRecvCount`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#setmaxaudiorecvcount) - [`setAudioRecvRange`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#setaudiorecvrange) - [`updateSelfPosition`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) - [`updateRemotePosition`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) - [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateplayerpositioninfo) - [`setRemoteUserSpatialAudioParams`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_irtcengine_setremoteuserspatialaudioparams) - [`setSpatialAudioParams`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#setspatialaudioparams) - [`setZones`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#setzones) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`clearRemotePositions`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#clearremotepositions) - [`muteLocalAudioStream`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#mutelocalaudiostream) - [`muteAllRemoteAudioStreams`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#muteallremoteaudiostreams) - [`enableSpatialAudio`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#enablespatialaudio) - [`destroy`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#destroy) - [`AgoraRtcEngineKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="macos" /> 空间音频能够将真实世界的声音体验带到虚拟数字世界，为用户提供更具吸引力的在线体验。通过声网提供的空间音频技术，你可以在虚拟互动场景下模拟声音在现实环境中的传播特点： **超拟真空间塑造效果** 利用范围音频、声音模糊、空气衰减模拟等技术，完美模拟现实听觉感受。 - 当声源和其他角色之间的距离、方位或朝向发生变化时，不同的角色听到的声音大小和方向均不相同。 - 当声源和其他角色之间的距离超过设置的范围后，后者无法听到声源发出的声音。 - 通过设置隔声区域、空气衰减、声音模糊等音效，完美模拟现实的听觉感受。 **3D 高保真** - 根据面部朝向、音源朝向、3D 空间内音源的相对位置进行音效处理渲染。 - 支持 48 kHz 全频带采样和 3D 高保真音效处理及渲染。 **多平台适配** 支持 iOS、Android、macOS、Windows、Web、Unity、Flutter、React Native、Electron、Unreal 等平台。 **超低延时、低功耗、低成本** 空间音频算法采用先进的前端处理模式，并通过云服务同步空间坐标，端云协同处理模式能够有效降低整体延时和功耗。相比传统的左右声道立体声，声网提供的空间音频技术在声音的立体感和空间感上都有明显的提升，两者区别如下所示： | 对比项 | 传统立体声 | 声网空间音频 | | -------- | -------------------------------------------- | --------------------------------------------------- | | 立体感 | 左右两个维度 | 以世界坐标系的 x、y、z 坐标轴表示右、上、前三个维度 | | 空间感 | 通过调节左右声道的音量，体现具有空间感的声音 | 使用空间音频算法，通过设置距离、方位、朝向等参数，塑造声音的空间感 | | 用户体验 | 平面 | 立体、自然、真实 | ## 适用场景 [#适用场景-2] #### 社交语聊 [#社交语聊-2] 在语聊房 App 界面中，以九宫格的形式展示所有用户头像，并对每个用户赋予一个坐标和朝向。在互动过程中，你可以感受到周围的用户发出的声音大小和方位跟其所在的位置有关。如果你在屏幕中拖动自己的头像，随着你跟某个用户之间的距离逐渐变远，你会听到该用户的声音也越来越小，超出一定范围后会彻底听不到，符合现实环境中声音的传播特点。 #### 游戏 & 元宇宙 [#游戏--元宇宙-2] 在游戏和元宇宙这类 3D 场景中，你可以使用空间音频技术实现更多功能，如下表所示： | 功能 | 描述 | | --- | --- | | 声音模糊 | 对指定远端用户或媒体播放器开启声音模糊处理。例如：在咖啡厅场景中，如果需要制造两个虚拟角色 “说悄悄话” 的效果，可以对他们开启声音模糊处理模式，其他角色会听到被处理过的、模糊的声音。 | | 范围音频 | [spatial-audio-macos-ios-html-0-2-1 details](#table-slot-spatial-audio-macos-ios-html-0-2-1-1) | | 超拟真空间塑造 | [spatial-audio-macos-ios-html-0-3-1 details](#table-slot-spatial-audio-macos-ios-html-0-3-1-1) | | 隔声区域 | 定义一个隔声区域并对隔声区域内的音源设置声音衰减系数，使区域外的接收方听区域内的音源时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。例如：在 KTV 场景中，当虚拟角色在 KTV 包厢外时，只能听到来自包厢内的较小的声音；在打开包厢门的时候，会在一瞬间体验到包厢里唱歌的声音迎面扑来。 | **spatial-audio-macos-ios-html-0-2-1 details** 根据当前场景的大小设置一个音频接收范围，在该范围以内，声音传播得越远，接收方听到的声音越小。你可以通过设置声音衰减系数，在不同的场景下获得更加拟真的衰减效果： - 在丛林场景中，将衰减系数设置为 0.9，声音在传播时迅速衰减。 - 在平原场景中，将衰减系数设置为 0.1，声音可以传播得很远。 **spatial-audio-macos-ios-html-0-3-1 details** 为全方位模拟真实场景的空间感，对每个虚拟角色赋予 4 组坐标，分别表示以下维度： - 虚拟角色空间坐标（x,y,z）：虚拟角色在 3D 空间里的坐标。 - 虚拟角色面部朝向坐标（x,y,z）：虚拟角色在场景中的面部朝向坐标。 - 虚拟角色头顶朝向坐标（x,y,z）：虚拟角色的头顶指向的坐标，可结合面部朝向坐标确定虚拟角色的动作和姿态。例如：虚拟角色平躺的时候，面部朝向天空，头顶朝向前方。 - 右手朝向（x,y,z）：直角坐标系是使用左手坐标系还是右手坐标系。在一个场景中只能使用一种坐标系。 #### 在线会议 [#在线会议-2] 在线会议场景下，你可以将所有上麦用户分布到主持人的周围，并赋予每个用户坐标。用户听到的每个声音都有方向感和空间感，模拟真实环境下的会议室体验，相比传统在线会议，能够带给用户全新的与会体验、降低用户疲惫感。 ## 技术原理 [#技术原理-2] 实现用户空间音频和媒体播放器空间音频时的原理有所不同： - 用户空间音频：自行部署服务器，用于发送本地空间位置以及接收远端用户的空间位置，然后由 SDK 计算用户间的相对位置，从而计算出相应的空间音频参数。 - 媒体播放器空间音频：通过 SDK 计算本地用户和媒体播放器的相对位置，然后计算出相应的空间音频参数。 ## 前提条件 [#前提条件-2] 在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 实现空间音频 [#实现空间音频-2] 本节介绍如何使用 SDK 实现空间音频，API 调用时序如下图所示。 ### 初始化空间音频引擎 [#初始化空间音频引擎-2] 调用 `AgoraLocalSpatialAudioKit` 类中 `sharedLocalSpatialAudioWithConfig` 初始化 `AgoraLocalSpatialAudioKit` 对象，开启空间音频。 ```swift agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: KeyCenter.AppId, delegate: self) let localSpatialConfig = AgoraLocalSpatialAudioConfig() localSpatialConfig.rtcEngine = agoraKit localSpatial = AgoraLocalSpatialAudioKit.sharedLocalSpatialAudio(with: localSpatialConfig) ``` ### 设置音频属性和场景 [#设置音频属性和场景-2] 1. 调用 `setAudioProfile`，将 `profile` 设置为你预期的音频编码属性。 2. 调用 `setAudioScenario`，将 `scenario` 设置为 `AgoraAudioScenarioGameStreaming`，以获得预期的音质效果。 ```swift agoraKit.setAudioProfile(.musicStandard) agoraKit.setAudioScenario(.gameStreaming) ``` ### 设置音频接收范围 [#设置音频接收范围-2] - 调用 `setMaxAudioRecvCount` 设置音频接收范围内最多可接收的音频流数，建议 `maxCount` 取值 ≤ 16。 - 调用 `setAudioRecvRange` 设置可接收音频的最大范围，单位为米，建议 `range` 取值＞ 0。 ```swift localSpatial.setMaxAudioRecvCount(2) localSpatial.setAudioRecvRange(Float(SCREENSIZE.height)) ``` ### 更新空间位置 [#更新空间位置-2] - 在用户空间音频场景下，调用 `updateSelfPosition` 和 `updateRemotePosition` 方法，分别更新本地用户和远端用户的位置。 - 在媒体播放器空间音频场景下，调用 `updateSelfPosition` 和 `updatePlayerPositionInfo` 方法，分别更新本地用户和媒体播放器的位置。推荐的调用时机如下所示： - 当频道内有新用户加入。 - 当本地、远端用户或媒体播放器的相对位置发生改变。 - 根据实际需求调用。 ```swift // 更新本地用户位置 let pos = getViewCenterPostion(view: selfPostionView) localSpatial.updateSelfPosition(pos, axisForward: forward, axisRight: right, axisUp: up) // 更新远端用户位置 if remoteUserButton1.tag <= 0 { remoteUserButton1.setTitle("\(uid)", for: .normal) remoteUserButton1.tag = Int(uid) remoteUserButton1.isHidden = false localSpatial.updateRemotePosition(uid, positionInfo: getPlayerPostion(view: remoteUserButton1)) } else if remoteUserButton2.tag <= 0 { remoteUserButton2.setTitle("\(uid)", for: .normal) remoteUserButton2.tag = Int(uid) remoteUserButton2.isHidden = false localSpatial.updateRemotePosition(uid, positionInfo: getPlayerPostion(view: remoteUserButton2)) } ``` ### 设置空间音频参数 [#设置空间音频参数-2] 调用 `setRemoteUserSpatialAudioParams` 或 `setSpatialAudioParams`，针对远端用户或媒体播放器设置空间音频参数。如果要实现特定音效，可参考如下参数设置： - 空气衰减效果：将 `enable_air_absorb` 设置为 `true`；并将 `speaker_attenuation` 设置为预期的声音衰减系数。 - 声音模糊效果：将 `enable_blur` 设置为 `true`。 ```swift // 开启空气衰减效果 let params = AgoraSpatialAudioParams() params.enable_air_absorb = true // 开启声音模糊效果 params.enable_blur = true // 以设置媒体播放器空间音频参数为例 mediaPlayer.setSpatialAudioParams(params) ``` ### （可选）设置隔声区域 [#可选设置隔声区域-2] 1. 调用 `setZones` 设置一个隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟接收方分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。 2. （可选）调用 `setRemoteAudioAttenuation` 或 `setPlayerAttenuation` 分别针对用户和媒体播放器设置声音衰减属性，并指定是否使用该设置强制覆盖 `setZones` 中的声音衰减系数。 ```swift let audioZone = AgoraSpatialAudioZone() // 隔声区域的 ID audioZone.zoneSetId = 1 // 隔声区域和外部互通时的声音衰减系数 audioZone.audioAttenuation = 1 // 以 position 为起点，向前的单位向量 audioZone.forward = forward // 以 position 为起点，向右的单位向量 audioZone.right = right // 以 position 为起点，向上的单位向量 audioZone.up = up // 隔声区域的空间中心点 audioZone.position = getViewCenterPostion(view: voiceContainerView1) // 隔声区域的前向长度 audioZone.forwardLength = Float(voiceContainerView1.frame.width) // 隔声区域的右向长度 audioZone.rightLength = Float(voiceContainerView1.frame.height) // 隔声区域的上向长度 audioZone.upLength = Float(maxDistance) localSpatial.setZones([audioZone]) localSpatial.setRemoteAudioAttenuation(uid, attenuation: 0.5, forceSet: false) localSpatial.setPlayerAttenuation(0.5, playerId: UInt(mediaPlayer.getMediaPlayerId()), forceSet: false) ``` ### （可选）设置耳机均衡效果 [#可选设置耳机均衡效果-2] 1. 调用 `setHeadphoneEQPreset` 方法，选择预设的耳机均衡器收听音频，以达到预期的音频体验。 2. （可选）如果执行上一步后仍未达到预期，你可以调用 `setHeadphoneEQParameters` 自行调节耳机均衡效果，执行该方法后，`setHeadphoneEQPreset` 方法设置的预设值会被覆盖。 ```swift agoraKit.setHeadphoneEQPreset(.overEar) agoraKit.setHeadphoneEQParameters(10, gain: 10) ``` ### 关闭空间音频 [#关闭空间音频-4] 在互动过程中，你可选择暂停或关闭空间音频。 ##### 暂停指定远端用户在本地的空间音频 [#暂停指定远端用户在本地的空间音频-2] 1. 如果不想继续体验远端用户在本地的空间音频、或远端用户已退出频道，调用 `removeRemotePosition` 删除该用户的空间位置信息，以节省计算资源。 :::warning[注意] 当远端用户离开频道时，必须调用 `removeRemotePosition` 删除该用户的空间位置信息，否则可能导致本地听不到来自其他远端用户的空间音频。 ::: 2. （可选）如果之后想恢复该用户在本地的空间音频，可调用 `updateRemotePosition` 方法重新设置远端用户的位置信息。 ```swift // 暂停指定远端用户在本地的空间音频 localSpatial.removeRemotePosition(uid) // 恢复指定远端用户在本地的空间音频 localSpatial.updateRemotePosition(uid, positionInfo: getPlayerPostion(view: remoteLeftTv)) ``` #### 暂停所有远端用户在本地的空间音频 [#暂停所有远端用户在本地的空间音频-2] 1. 如果你不想再继续体验本地的空间音频，可以调用 `clearRemotePositions` 删除所有远端用户的空间位置信息。 :::warning[注意] 调用该方法会导致本地听不到所有远端用户的音频，声网建议你谨慎调用该方法。 ::: 2. （可选）如果之后还需要听到远端用户的音频，你需要重新调用 `AgoraLocalSpatialAudioKit` 中的 `muteAllRemoteAudioStreams(false)` 恢复订阅远端用户的音频流。 ```swift // 删除所有远端用户的空间位置信息 localSpatial.clearRemotePositions() // 恢复订阅远端用户的音频流 localSpatial.muteAllRemoteAudioStreams(false) ``` #### 暂停本地用户在远端的空间音频 [#暂停本地用户在远端的空间音频-2] 1. 调用 `AgoraLocalSpatialAudioKit` 中的 `muteLocalAudioStream(true)`，取消发布本地音频流。 2. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `false`，即可恢复空间音频。 ```swift // 取消发布本地音频流 localSpatial.muteLocalAudioStream(true) // 恢复发布本地音频流 localSpatial.muteLocalAudioStream(false) ``` #### 关闭空间音频 [#关闭空间音频-5] 1. 在频道内调用 `AgoraRtcEngineKit` 中的 `enableSpatialAudio` 并将参数设置为 `false`，此时所有跟空间音频相关的设置都会被重置。 2. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `true`，然后重新调用相关 API 设置空间音频效果。 3. （可选）调用 `AgoraLocalSpatialAudioKit` 中的 `destroy` 销毁 `AgoraLocalSpatialAudioKit` 对象。 ```swift // 关闭空间音频 agoraKit.enableSpatialAudio(false) // 销毁 AgoraLocalSpatialAudioKit 对象 AgoraLocalSpatialAudioKit.destroy() ``` ## 参考信息 [#参考信息-2] ### 示例项目 [#示例项目-2] 声网提供了开源的空间音频示例项目供你参考，你可以前往下载或查看其中的源代码。 SpatialAudio} href="https://gitee.com/agoraio-community/API-Examples/blob/main/macOS/APIExample/Examples/Advanced/SpatialAudio/SpatialAudio.swift" /> SpatialAudio} href="https://github.com/Shengwang-Community/API-Examples/blob/main/macOS/APIExample/Examples/Advanced/SpatialAudio/SpatialAudio.swift" /> ### API 参考 [#api-参考-2] - [`AgoraLocalSpatialAudioKit`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_ilocalspatialaudioengine) - [`sharedLocalSpatialAudioWithConfig`](/zh-CN/api-reference/rtc/macos/initialize#api_irtcengine_initialize) - [`setMaxAudioRecvCount`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#setmaxaudiorecvcount) - [`setAudioRecvRange`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#setaudiorecvrange) - [`updateSelfPosition`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) - [`updateRemotePosition`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) - [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateplayerpositioninfo) - [`setRemoteUserSpatialAudioParams`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_irtcengine_setremoteuserspatialaudioparams) - [`setSpatialAudioParams`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#setspatialaudioparams) - [`setZones`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#setzones) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`clearRemotePositions`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#clearremotepositions) - [`muteLocalAudioStream`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#mutelocalaudiostream) - [`muteAllRemoteAudioStreams`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#muteallremoteaudiostreams) - [`enableSpatialAudio`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#enablespatialaudio) - [`destroy`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#destroy) - [`AgoraRtcEngineKit`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="windows" /> 空间音频能够将真实世界的声音体验带到虚拟数字世界，为用户提供更具吸引力的在线体验。通过声网提供的空间音频技术，你可以在虚拟互动场景下模拟声音在现实环境中的传播特点： **超拟真空间塑造效果** 利用范围音频、声音模糊、空气衰减模拟等技术，完美模拟现实听觉感受。 - 当声源和其他角色之间的距离、方位或朝向发生变化时，不同的角色听到的声音大小和方向均不相同。 - 当声源和其他角色之间的距离超过设置的范围后，后者无法听到声源发出的声音。 - 通过设置隔声区域、空气衰减、声音模糊等音效，完美模拟现实的听觉感受。 **3D 高保真** - 根据面部朝向、音源朝向、3D 空间内音源的相对位置进行音效处理渲染。 - 支持 48 kHz 全频带采样和 3D 高保真音效处理及渲染。 **多平台适配** 支持 iOS、Android、macOS、Windows、Web、Unity、Flutter、React Native、Electron、Unreal 等平台。 **超低延时、低功耗、低成本** 空间音频算法采用先进的前端处理模式，并通过云服务同步空间坐标，端云协同处理模式能够有效降低整体延时和功耗。相比传统的左右声道立体声，声网提供的空间音频技术在声音的立体感和空间感上都有明显的提升，两者区别如下所示： | 对比项 | 传统立体声 | 声网空间音频 | | -------- | -------------------------------------------- | --------------------------------------------------- | | 立体感 | 左右两个维度 | 以世界坐标系的 x、y、z 坐标轴表示右、上、前三个维度 | | 空间感 | 通过调节左右声道的音量，体现具有空间感的声音 | 使用空间音频算法，通过设置距离、方位、朝向等参数，塑造声音的空间感 | | 用户体验 | 平面 | 立体、自然、真实 | ## 适用场景 [#适用场景-3] #### 社交语聊 [#社交语聊-3] 在语聊房 App 界面中，以九宫格的形式展示所有用户头像，并对每个用户赋予一个坐标和朝向。在互动过程中，你可以感受到周围的用户发出的声音大小和方位跟其所在的位置有关。如果你在屏幕中拖动自己的头像，随着你跟某个用户之间的距离逐渐变远，你会听到该用户的声音也越来越小，超出一定范围后会彻底听不到，符合现实环境中声音的传播特点。 #### 游戏 & 元宇宙 [#游戏--元宇宙-3] 在游戏和元宇宙这类 3D 场景中，你可以使用空间音频技术实现更多功能，如下表所示： | 功能 | 描述 | | --- | --- | | 声音模糊 | 对指定远端用户或媒体播放器开启声音模糊处理。例如：在咖啡厅场景中，如果需要制造两个虚拟角色 “说悄悄话” 的效果，可以对他们开启声音模糊处理模式，其他角色会听到被处理过的、模糊的声音。 | | 范围音频 | [spatial-audio-windows-html-0-2-1 details](#table-slot-spatial-audio-windows-html-0-2-1) | | 超拟真空间塑造 | [spatial-audio-windows-html-0-3-1 details](#table-slot-spatial-audio-windows-html-0-3-1) | | 隔声区域 | 定义一个隔声区域并对隔声区域内的音源设置声音衰减系数，使区域外的接收方听区域内的音源时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。例如：在 KTV 场景中，当虚拟角色在 KTV 包厢外时，只能听到来自包厢内的较小的声音；在打开包厢门的时候，会在一瞬间体验到包厢里唱歌的声音迎面扑来。 | **spatial-audio-windows-html-0-2-1 details** 根据当前场景的大小设置一个音频接收范围，在该范围以内，声音传播得越远，接收方听到的声音越小。你可以通过设置声音衰减系数，在不同的场景下获得更加拟真的衰减效果： - 在丛林场景中，将衰减系数设置为 0.9，声音在传播时迅速衰减。 - 在平原场景中，将衰减系数设置为 0.1，声音可以传播得很远。 **spatial-audio-windows-html-0-3-1 details** 为全方位模拟真实场景的空间感，对每个虚拟角色赋予 4 组坐标，分别表示以下维度： - 虚拟角色空间坐标（x,y,z）：虚拟角色在 3D 空间里的坐标。 - 虚拟角色面部朝向坐标（x,y,z）：虚拟角色在场景中的面部朝向坐标。 - 虚拟角色头顶朝向坐标（x,y,z）：虚拟角色的头顶指向的坐标，可结合面部朝向坐标确定虚拟角色的动作和姿态。例如：虚拟角色平躺的时候，面部朝向天空，头顶朝向前方。 - 右手朝向（x,y,z）：直角坐标系是使用左手坐标系还是右手坐标系。在一个场景中只能使用一种坐标系。 #### 在线会议 [#在线会议-3] 在线会议场景下，你可以将所有上麦用户分布到主持人的周围，并赋予每个用户坐标。用户听到的每个声音都有方向感和空间感，模拟真实环境下的会议室体验，相比传统在线会议，能够带给用户全新的与会体验、降低用户疲惫感。 ## 技术原理 [#技术原理-3] 实现用户空间音频和媒体播放器空间音频时的原理有所不同： - 用户空间音频：自行部署服务器，用于发送本地空间位置以及接收远端用户的空间位置，然后由 SDK 计算用户间的相对位置，从而计算出相应的空间音频参数。 - 媒体播放器空间音频：通过 SDK 计算本地用户和媒体播放器的相对位置，然后计算出相应的空间音频参数。 ## 前提条件 [#前提条件-3] 在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 实现空间音频 [#实现空间音频-3] 本节介绍如何使用 SDK 实现空间音频，API 调用时序如下图所示。 ### 初始化空间音频引擎 [#初始化空间音频引擎-3] 调用 `ILocalSpatialAudioEngine` 类中的 `initialize` 初始化 `ILocalSpatialAudioEngine` 对象，开启空间音频。 ```cpp m_localSpatial = nullptr; m_rtcEngine->queryInterface(AGORA_IID_LOCAL_SPATIAL_AUDIO, (void**)&m_localSpatial); LocalSpatialAudioConfig config; config.rtcEngine = m_rtcEngine; m_localSpatial->initialize(config); ``` ### 设置音频属性和场景 [#设置音频属性和场景-3] 1. 调用 `setAudioProfile`，将 `profile` 设置为你预期的音频编码属性。 2. 调用 `setAudioScenario`，将 `scenario` 设置为 `AUDIO_SCENARIO_GAME_STREAMING`，以获得预期的音质效果。 ```cpp m_rtcEngine->setAudioProfile(AUDIO_PROFILE_MUSIC_STANDARD); m_rtcEngine->setAudioScenario(AUDIO_SCENARIO_GAME_STREAMING); ``` ### 设置音频接收范围 [#设置音频接收范围-3] - 调用 `setMaxAudioRecvCount` 设置音频接收范围内最多可接收的音频流数，建议 `maxCount` 取值 ≤ 16。 - 调用 `setAudioRecvRange` 设置可接收音频的最大范围，单位为米，建议 `range` 取值＞ 0。 ```cpp m_localSpatial->setMaxAudioRecvCount(2); m_localSpatial->setAudioRecvRange(AXIS_MAX_DISTANCE); ``` ### 更新空间位置 [#更新空间位置-3] - 在用户空间音频场景下，调用 `updateSelfPosition` 和 `updateRemotePosition` 方法，分别更新本地用户和远端用户的位置。 - 在媒体播放器空间音频场景下，调用 `updateSelfPosition` 和 `updatePlayerPositionInfo` 方法，分别更新本地用户和媒体播放器的位置。推荐的调用时机如下所示： - 当频道内有新用户加入。 - 当本地、远端用户或媒体播放器的相对位置发生改变。 - 根据实际需求调用。 ```cpp // 更新本地用户位置 float pos[3] = { 0 }; CaculateObjectPosition(m_staLocalMove, pos); float forward[3] = { 1.0f, 0, 0 }; float right[3] = { 0, 1.0f, 0 }; float up[3] = { 0, 0, 1.0f }; m_localSpatial->updateSelfPosition(pos, forward, right, up); // 更新远端用户位置 if (remoteLeftUid == 0) { remoteLeftUid = wParam; m_staRemoteLeft.ShowWindow(TRUE); RemoteVoicePositionInfo posInfo; memset(&posInfo, 0, sizeof(RemoteVoicePositionInfo)); CaculateObjectPosition(m_staRemoteLeft, posInfo.position); m_localSpatial->updateRemotePosition(remoteLeftUid, posInfo); } else if (remoteRightUid == 0) { remoteRightUid = wParam; m_staRemoteRight.ShowWindow(TRUE); RemoteVoicePositionInfo posInfo; memset(&posInfo, 0, sizeof(RemoteVoicePositionInfo)); CaculateObjectPosition(m_staRemoteRight, posInfo.position); m_localSpatial->updateRemotePosition(remoteRightUid, posInfo); } ``` ### 设置空间音频参数 [#设置空间音频参数-3] 调用 `setRemoteUserSpatialAudioParams` 或 `setSpatialAudioParams`，针对远端用户或媒体播放器设置空间音频参数。如果要实现特定音效，可参考如下参数设置： - 空气衰减效果：将 `enable_air_absorb` 设置为 `true`；并将 `speaker_attenuation` 设置为预期的声音衰减系数。 - 声音模糊效果：将 `enable_blur` 设置为 `true`。 ```cpp // 设置空气衰减效果 spatialAudioParams.enable_air_absorb = true; // 设置声音模糊效果 spatialAudioParams.enable_blur = true; // 以设置媒体播放器空间音频参数为例 m_mediaPlayerLeft->setSpatialAudioParams(spatialAudioParams); ``` ### （可选）设置隔声区域 [#可选设置隔声区域-3] 1. 调用 `setZones` 设置一个隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟接收方分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。 2. （可选）调用 `setRemoteAudioAttenuation` 或 `setPlayerAttenuation` 分别针对用户和媒体播放器设置声音衰减属性，并指定是否使用该设置强制覆盖 `setZones` 中的声音衰减系数。 ```cpp SpatialAudioZone mediaPlayerLeftZone; memset(&mediaPlayerLeftZone, 0, sizeof(SpatialAudioZone)); // 隔声区域和外部互通时的声音衰减系数 mediaPlayerLeftZone.audioAttenuation = 1.0f; // 隔声区域的空间中心点 CaculateObjectPosition(m_staZone, mediaPlayerLeftZone.position); // 以 position 为起点，向前的单位向量 mediaPlayerLeftZone.forward[0] = 1.0f; // 以 position 为起点，向右的单位向量 mediaPlayerLeftZone.right[1] = 1.0f; // 以 position 为起点，向上的单位向量 mediaPlayerLeftZone.up[2] = 1.0f; RECT zoneSize; CaculateZoneRect(m_staZone, &zoneSize); // 隔声区域的前向长度 mediaPlayerLeftZone.forwardLength = zoneSize.bottom - zoneSize.top * 1.0f; // 隔声区域的右向长度 mediaPlayerLeftZone.rightLength = zoneSize.right - zoneSize.left * 1.0f; // 隔声区域的上向长度 mediaPlayerLeftZone.upLength = AXIS_MAX_DISTANCE; m_localSpatial->setZones(&mediaPlayerLeftZone, 1); m_localSpatial->setRemoteAudioAttenuation(uid, 0.5f, false); m_localSpatial->setPlayerAttenuation(mediaPlayer.getMediaPlayerId(), 0.5f, false); ``` ### （可选）设置耳机均衡效果 [#可选设置耳机均衡效果-3] 1. 调用 `setHeadphoneEQPreset` 方法，选择预设的耳机均衡器收听音频，以达到预期的音频体验。 2. （可选）如果执行上一步后仍未达到预期，你可以调用 `setHeadphoneEQParameters` 自行调节耳机均衡效果，执行该方法后，`setHeadphoneEQPreset` 方法设置的预设值会被覆盖。 ```cpp m_rtcEngine->setHeadphoneEQPreset(HEADPHONE_EQUALIZER_OVEREAR); m_rtcEngine->setHeadphoneEQParameters(10, 10); ``` ### 关闭空间音频 [#关闭空间音频-6] 在互动过程中，你可选择暂停或关闭空间音频。 #### 暂停指定远端用户在本地的空间音频 [#暂停指定远端用户在本地的空间音频-3] 1. 如果不想继续体验远端用户在本地的空间音频、或远端用户已退出频道，调用 `removeRemotePosition` 删除该用户的空间位置信息，以节省计算资源。 :::warning[注意] 当远端用户离开频道时，必须调用 `removeRemotePosition` 删除该用户的空间位置信息，否则可能导致本地听不到来自其他远端用户的空间音频。 ::: 2. （可选）如果之后想恢复该用户在本地的空间音频，可调用 `updateRemotePosition` 方法重新设置远端用户的位置信息。 ```cpp // 暂停指定远端用户在本地的空间音频 m_localSpatial->removeRemotePosition(uid) // 恢复指定远端用户在本地的空间音频 m_localSpatial->updateRemotePosition(uid, getVoicePositionInfo(remoteLeftTv)); ``` #### 暂停所有远端用户在本地的空间音频 [#暂停所有远端用户在本地的空间音频-3] 1. 如果你不想再继续体验本地的空间音频，可以调用 `clearRemotePositions` 删除所有远端用户的空间位置信息。 :::warning[注意] 调用该方法会导致本地听不到所有远端用户的音频，声网建议你谨慎调用该方法。 ::: 2. （可选）如果之后还需要听到远端用户的音频，你需要重新调用 `ILocalSpatialAudioEngine` 中的 `muteAllRemoteAudioStreams(false)` 恢复订阅远端用户的音频流。 ```cpp // 删除所有远端用户的空间位置信息 m_localSpatial->clearRemotePositions(); // 恢复订阅远端用户的音频流 m_localSpatial->muteAllRemoteAudioStreams(false); ``` #### 暂停本地用户在远端的空间音频 [#暂停本地用户在远端的空间音频-3] 1. 调用 `ILocalSpatialAudioEngine` 中的 `muteLocalAudioStream(true)`，取消发布本地音频流。 2. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `false`，即可恢复空间音频。 ```cpp // 取消发布本地音频流 m_localSpatial->muteLocalAudioStream(true); // 恢复发布本地音频流 m_localSpatial->muteLocalAudioStream(false); ``` #### 关闭空间音频 [#关闭空间音频-7] 1. 在频道内调用 `IRtcEngine` 中的 `enableSpatialAudio` 并将参数设置为 `false`，此时所有跟空间音频相关的设置都会被重置。 2. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `true`，然后重新调用相关 API 设置空间音频效果。 3. （可选）调用 `ILocalSpatialAudioEngine` 中的 `destroy` 销毁 `ILocalSpatialAudioEngine` 对象。 ```cpp // 关闭空间音频 m_rtcEngine->enableSpatialAudio(false); // 销毁 ILocalSpatialAudioEngine 对象 m_localSpatial->release(); ``` ## 参考信息 [#参考信息-3] ### 示例项目 [#示例项目-3] 声网提供了开源的空间音频示例项目供你参考，你可以前往下载或查看其中的源代码。 SpatialAudio} href="https://gitee.com/agoraio-community/API-Examples/blob/main/windows/APIExample/APIExample/Advanced/SpatialAudio" /> SpatialAudio} href="https://github.com/Shengwang-Community/API-Examples/tree/main/windows/APIExample/APIExample/Advanced/SpatialAudio" /> ### API 参考 [#api-参考-3] - [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ilocalspatialaudioengine) - [`initialize`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#initialize) - [`setMaxAudioRecvCount`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setmaxaudiorecvcount) - [`setAudioRecvRange`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setaudiorecvrange) - [`updateSelfPosition`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#updateselfposition) - [`updateRemotePosition`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#updateremoteposition) - [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#updateplayerpositioninfo) - [`setRemoteUserSpatialAudioParams`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setremoteuserspatialaudioparams) - [`setSpatialAudioParams`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setspatialaudioparams) - [`setZones`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setzones) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setremoteaudioattenuation) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setplayerattenuation) - [`clearRemotePositions`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#clearremotepositions) - [`muteLocalAudioStream`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#mutelocalaudiostream) - [`muteAllRemoteAudioStreams`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#muteallremoteaudiostreams) - [`enableSpatialAudio`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#enablespatialaudio) - [`destroy`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#destroy) - [`IRtcEngine`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setheadphoneeqparameters) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="electron" /> 空间音频能够将真实世界的声音体验带到虚拟数字世界，为用户提供更具吸引力的在线体验。通过声网提供的空间音频技术，你可以在虚拟互动场景下模拟声音在现实环境中的传播特点： **超拟真空间塑造效果** 利用范围音频、声音模糊、空气衰减模拟等技术，完美模拟现实听觉感受。 - 当声源和其他角色之间的距离、方位或朝向发生变化时，不同的角色听到的声音大小和方向均不相同。 - 当声源和其他角色之间的距离超过设置的范围后，后者无法听到声源发出的声音。 - 通过设置隔声区域、空气衰减、声音模糊等音效，完美模拟现实的听觉感受。 **3D 高保真** - 根据面部朝向、音源朝向、3D 空间内音源的相对位置进行音效处理渲染。 - 支持 48 kHz 全频带采样和 3D 高保真音效处理及渲染。 **多平台适配** 支持 iOS、Android、macOS、Windows、Web、Unity、Flutter、React Native、Electron、Unreal 等平台。 **超低延时、低功耗、低成本** 空间音频算法采用先进的前端处理模式，并通过云服务同步空间坐标，端云协同处理模式能够有效降低整体延时和功耗。相比传统的左右声道立体声，声网提供的空间音频技术在声音的立体感和空间感上都有明显的提升，两者区别如下所示： | 对比项 | 传统立体声 | 声网空间音频 | | -------- | -------------------------------------------- | --------------------------------------------------- | | 立体感 | 左右两个维度 | 以世界坐标系的 x、y、z 坐标轴表示右、上、前三个维度 | | 空间感 | 通过调节左右声道的音量，体现具有空间感的声音 | 使用空间音频算法，通过设置距离、方位、朝向等参数，塑造声音的空间感 | | 用户体验 | 平面 | 立体、自然、真实 | ## 适用场景 [#适用场景-4] #### 社交语聊 [#社交语聊-4] 在语聊房 App 界面中，以九宫格的形式展示所有用户头像，并对每个用户赋予一个坐标和朝向。在互动过程中，你可以感受到周围的用户发出的声音大小和方位跟其所在的位置有关。如果你在屏幕中拖动自己的头像，随着你跟某个用户之间的距离逐渐变远，你会听到该用户的声音也越来越小，超出一定范围后会彻底听不到，符合现实环境中声音的传播特点。 #### 游戏 & 元宇宙 [#游戏--元宇宙-4] 在游戏和元宇宙这类 3D 场景中，你可以使用空间音频技术实现更多功能，如下表所示： | 功能 | 描述 | | --- | --- | | 声音模糊 | 对指定远端用户或媒体播放器开启声音模糊处理。例如：在咖啡厅场景中，如果需要制造两个虚拟角色 “说悄悄话” 的效果，可以对他们开启声音模糊处理模式，其他角色会听到被处理过的、模糊的声音。 | | 范围音频 | [spatial-audio-rn-electron-html-0-2-1 details](#table-slot-spatial-audio-rn-electron-html-0-2-1) | | 超拟真空间塑造 | [spatial-audio-rn-electron-html-0-3-1 details](#table-slot-spatial-audio-rn-electron-html-0-3-1) | | 隔声区域 | 定义一个隔声区域并对隔声区域内的音源设置声音衰减系数，使区域外的接收方听区域内的音源时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。例如：在 KTV 场景中，当虚拟角色在 KTV 包厢外时，只能听到来自包厢内的较小的声音；在打开包厢门的时候，会在一瞬间体验到包厢里唱歌的声音迎面扑来。 | **spatial-audio-rn-electron-html-0-2-1 details** 根据当前场景的大小设置一个音频接收范围，在该范围以内，声音传播得越远，接收方听到的声音越小。你可以通过设置声音衰减系数，在不同的场景下获得更加拟真的衰减效果： - 在丛林场景中，将衰减系数设置为 0.9，声音在传播时迅速衰减。 - 在平原场景中，将衰减系数设置为 0.1，声音可以传播得很远。 **spatial-audio-rn-electron-html-0-3-1 details** 为全方位模拟真实场景的空间感，对每个虚拟角色赋予 4 组坐标，分别表示以下维度： - 虚拟角色空间坐标（x,y,z）：虚拟角色在 3D 空间里的坐标。 - 虚拟角色面部朝向坐标（x,y,z）：虚拟角色在场景中的面部朝向坐标。 - 虚拟角色头顶朝向坐标（x,y,z）：虚拟角色的头顶指向的坐标，可结合面部朝向坐标确定虚拟角色的动作和姿态。例如：虚拟角色平躺的时候，面部朝向天空，头顶朝向前方。 - 右手朝向（x,y,z）：直角坐标系是使用左手坐标系还是右手坐标系。在一个场景中只能使用一种坐标系。 #### 在线会议 [#在线会议-4] 在线会议场景下，你可以将所有上麦用户分布到主持人的周围，并赋予每个用户坐标。用户听到的每个声音都有方向感和空间感，模拟真实环境下的会议室体验，相比传统在线会议，能够带给用户全新的与会体验、降低用户疲惫感。 ## 技术原理 [#技术原理-4] 实现用户空间音频和媒体播放器空间音频时的原理有所不同： - 用户空间音频：自行部署服务器，用于发送本地空间位置以及接收远端用户的空间位置，然后由 SDK 计算用户间的相对位置，从而计算出相应的空间音频参数。 - 媒体播放器空间音频：通过 SDK 计算本地用户和媒体播放器的相对位置，然后计算出相应的空间音频参数。 ## 前提条件 [#前提条件-4] 在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 实现空间音频 [#实现空间音频-4] 本节介绍如何使用 SDK 实现空间音频，API 调用时序如下图所示。 ### 初始化空间音频引擎 [#初始化空间音频引擎-4] 调用 `getLocalSpatialAudioEngine` 和 `initialize` 初始化 `ILocalSpatialAudioEngine` 对象，开启空间音频。 ```typescript rtcEngine = createAgoraRtcEngine(); localSpatial = rtcEngine.getLocalSpatialAudioEngine() localSpatial.initialize(); ``` ### 设置音频属性和场景 [#设置音频属性和场景-4] 1. 调用 `setAudioProfile`，将 `profile` 设置为你预期的音频编码属性。 2. 调用 `setAudioScenario`，将 `scenario` 设置为 `AudioScenarioGameStreaming`，以获得预期的音质效果。 ```typescript rtcEngine.setAudioProfile(AudioProfileType.AudioProfileSpeechStandard); rtcEngine.setAudioScenario(AudioScenarioType.AudioScenarioGameStreaming); ``` ### 设置音频接收范围 [#设置音频接收范围-4] - 调用 `setMaxAudioRecvCount` 设置音频接收范围内最多可接收的音频流数，建议 `maxCount` 取值 ≤ 16。 - 调用 `setAudioRecvRange` 设置可接收音频的最大范围，单位为米，建议 `range` 取值＞ 0。 ```typescript localSpatial.setMaxAudioRecvCount(2); localSpatial.setAudioRecvRange(50); ``` ### 更新空间位置 [#更新空间位置-4] - 在用户空间音频场景下，调用 `updateSelfPosition` 和 `updateRemotePosition` 方法，分别更新本地用户和远端用户的位置。 - 在媒体播放器空间音频场景下，调用 `updateSelfPosition` 和 `updatePlayerPositionInfo` 方法，分别更新本地用户和媒体播放器的位置。推荐的调用时机如下所示： - 当频道内有新用户加入。 - 当本地、远端用户或媒体播放器的相对位置发生改变。 - 根据实际需求调用。 ```typescript // 更新本地用户位置 localSpatial.updateSelfPosition( [0, 0, 0], // position [1, 0, 0], // axisForward [0, 1, 0], // axisRight [0, 0, 1] // axisUp ); // 更新远端用户位置 localSpatial.updateRemotePosition( uid, // 远端用户 ID { position: [0, 0, 0], axisForward: [1, 0, 0], } ); // 更新媒体播放器位置 localSpatial.updatePlayerPositionInfo( mediaPlayer.getMediaPlayerId(), // 媒体播放器 ID { position: [0, 0, 0], axisForward: [1, 0, 0], } ); ``` ### 设置空间音频参数 [#设置空间音频参数-4] 调用 `setRemoteUserSpatialAudioParams` 或 `setSpatialAudioParams`，针对远端用户或媒体播放器设置空间音频参数。如果要实现特定音效，可参考如下参数设置： - 空气衰减效果：将 `enable_air_absorb` 设置为 `true`；并将 `speaker_attenuation` 设置为预期的声音衰减系数。 - 声音模糊效果：将 `enable_blur` 设置为 `true`。 ```typescript rtcEngine.setRemoteUserSpatialAudioParams( uid, { enable_air_absorb: true, speaker_attenuation: 0.5, enable_blur: true, } ); ``` ### （可选）设置隔声区域 [#可选设置隔声区域-4] 1. 调用 `setZones` 设置一个隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟接收方分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。 1. （可选）调用 `setRemoteAudioAttenuation` 或 `setPlayerAttenuation` 分别针对用户和媒体播放器设置声音衰减属性，并指定是否使用该设置强制覆盖 `setZones` 中的声音衰减系数。 ```typescript localSpatial.setZones( [ { zoneSetId: 1, // 隔声区域的 ID position: [0, 0, 0], // 隔声区域的空间中心点 forward: [1, 0, 0], // 以 position 为起点，向前的单位向量 right: [0, 1, 0], // 以 position 为起点，向右的单位向量 up: [0, 0, 1], // 以 position 为起点，向上的单位向量 forwardLength: 10, // 隔声区域的前向长度 rightLength: 10, // 隔声区域的右向长度 upLength: 10, // 隔声区域的上向长度 audioAttenuation: 0.5, // 隔声区域和外部互通时的声音衰减系数 } ], 1 ); localSpatial.setRemoteAudioAttenuation( mediaPlayer.getMediaPlayerId(), // 媒体播放器 ID 0.5, false ); localSpatial.setPlayerAttenuation( mediaPlayer.getMediaPlayerId(), // 媒体播放器 ID 0.5, false ); ``` ### （可选）设置耳机均衡效果 [#可选设置耳机均衡效果-4] 1. 调用 `setHeadphoneEQPreset` 方法，选择预设的耳机均衡器收听音频，以达到预期的音频体验。 1. （可选）如果执行上一步后仍未达到预期，你可以调用 `setHeadphoneEQParameters` 自行调节耳机均衡效果，执行该方法后，`setHeadphoneEQPreset` 方法设置的预设值会被覆盖。 ```typescript rtcEngine.setHeadphoneEQPreset(HeadphoneEqualizerPreset.HeadphoneEqualizerOverear); rtcEngine.setHeadphoneEQParameters(10, 10); ``` ### 关闭空间音频 [#关闭空间音频-8] 在互动过程中，你可选择暂停或关闭空间音频。 #### 暂停指定远端用户在本地的空间音频 [#暂停指定远端用户在本地的空间音频-4] 1. 如果不想继续体验远端用户在本地的空间音频、或远端用户已退出频道，调用 `removeRemotePosition` 删除该用户的空间位置信息，以节省计算资源。 :::warning[注意] 当远端用户离开频道时，必须调用 `removeRemotePosition` 删除该用户的空间位置信息，否则可能导致本地听不到来自其他远端用户的空间音频。 ::: 1. （可选）如果之后想恢复该用户在本地的空间音频，可调用 `updateRemotePosition` 方法重新设置远端用户的位置信息。 ```typescript // 暂停指定远端用户在本地的空间音频 localSpatial.removeRemotePosition(uid) // 恢复指定远端用户在本地的空间音频 localSpatial.updateRemotePosition( uid, // 远端用户 ID { position: [0, 0, 0], axisForward: [1, 0, 0], } ); ``` #### 暂停所有远端用户在本地的空间音频 [#暂停所有远端用户在本地的空间音频-4] 1. 如果你不想再继续体验本地的空间音频，可以调用 `clearRemotePositions` 删除所有远端用户的空间位置信息。 :::warning[注意] 调用该方法会导致本地听不到所有远端用户的音频，声网建议你谨慎调用该方法。 ::: 1. （可选）如果之后还需要听到远端用户的音频，你需要重新调用 `ILocalSpatialAudioEngine` 中的 `muteAllRemoteAudioStreams(false)` 恢复订阅远端用户的音频流。 ```typescript // 删除所有远端用户的空间位置信息 localSpatial.clearRemotePositions(); // 恢复订阅远端用户的音频流 localSpatial.muteAllRemoteAudioStreams(false); ``` #### 暂停本地用户在远端的空间音频 [#暂停本地用户在远端的空间音频-4] 1. 调用 `ILocalSpatialAudioEngine` 中的 `muteLocalAudioStream(true)`，取消发布本地音频流。 1. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `false`，即可恢复空间音频。 ```typescript // 取消发布本地音频流 localSpatial.muteLocalAudioStream(true); // 恢复发布本地音频流 localSpatial.muteLocalAudioStream(false); ``` #### 关闭空间音频 [#关闭空间音频-9] 1. 在频道内调用 `RtcEngine` 中的 `enableSpatialAudio` 并将参数设置为 `false`，此时所有跟空间音频相关的设置都会被重置。 2. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `true`，然后重新调用相关 API 设置空间音频效果。 3. 调用 `ILocalSpatialAudioEngine` 中的 `release` 销毁 `ILocalSpatialAudioEngine` 对象。 ```typescript // 关闭空间音频 rtcEngine.enableSpatialAudio(false); // 销毁 ILocalSpatialAudioEngine 对象 localSpatial.release(); ``` ## 参考信息 [#参考信息-4] ### 示例项目 [#示例项目-4] 声网提供了开源的空间音频示例项目供你参考，你可以前往下载或查看其中的源代码。 :::info[信息] 示例项目中的 `SpatialAudio.tsx` 和 `LocalSpatialAudioEngine.tsx` 需配合使用才能实现空间音频。 ::: SpatialAudio} href="https://gitee.com/agoraio-community/Electron-SDK/blob/main/example/src/renderer/examples/advanced/SpatialAudio/SpatialAudio.tsx" /> SpatialAudio} href="https://github.com/AgoraIO-Extensions/Electron-SDK/blob/main/example/src/renderer/examples/advanced/SpatialAudio/SpatialAudio.tsx" /> LocalSpatialAudioEngine} href="https://gitee.com/agoraio-community/Electron-SDK/blob/main/example/src/renderer/examples/advanced/LocalSpatialAudioEngine/LocalSpatialAudioEngine.tsx" /> LocalSpatialAudioEngine} href="https://github.com/AgoraIO-Extensions/Electron-SDK/blob/main/example/src/renderer/examples/advanced/LocalSpatialAudioEngine/LocalSpatialAudioEngine.tsx" /> ### API 参考 [#api-参考-4] - [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_ilocalspatialaudioengine) - [`initialize`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#initialize) - [`setMaxAudioRecvCount`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setmaxaudiorecvcount) - [`setAudioRecvRange`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setaudiorecvrange) - [`updateSelfPosition`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#updateselfposition) - [`updateRemotePosition`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#updateremoteposition) - [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#updateplayerpositioninfo) - [`setRemoteUserSpatialAudioParams`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setremoteuserspatialaudioparams) - [`setSpatialAudioParams`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setspatialaudioparams) - [`setZones`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setzones) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setremoteaudioattenuation) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setplayerattenuation) - [`clearRemotePositions`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#clearremotepositions) - [`muteLocalAudioStream`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#mutelocalaudiostream) - [`muteAllRemoteAudioStreams`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#muteallremoteaudiostreams) - [`enableSpatialAudio`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#enablespatialaudio) - [`destroy`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#destroy) - [`RtcEngine`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#setheadphoneeqparameters) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="unity" /> 空间音频能够将真实世界的声音体验带到虚拟数字世界，为用户提供更具吸引力的在线体验。通过声网提供的空间音频技术，你可以在虚拟互动场景下模拟声音在现实环境中的传播特点： **超拟真空间塑造效果** 利用范围音频、声音模糊、空气衰减模拟等技术，完美模拟现实听觉感受。 - 当声源和其他角色之间的距离、方位或朝向发生变化时，不同的角色听到的声音大小和方向均不相同。 - 当声源和其他角色之间的距离超过设置的范围后，后者无法听到声源发出的声音。 - 通过设置隔声区域、空气衰减、声音模糊等音效，完美模拟现实的听觉感受。 **3D 高保真** - 根据面部朝向、音源朝向、3D 空间内音源的相对位置进行音效处理渲染。 - 支持 48 kHz 全频带采样和 3D 高保真音效处理及渲染。 **多平台适配** 支持 iOS、Android、macOS、Windows、Web、Unity、Flutter、React Native、Electron、Unreal 等平台。 **超低延时、低功耗、低成本** 空间音频算法采用先进的前端处理模式，并通过云服务同步空间坐标，端云协同处理模式能够有效降低整体延时和功耗。相比传统的左右声道立体声，声网提供的空间音频技术在声音的立体感和空间感上都有明显的提升，两者区别如下所示： | 对比项 | 传统立体声 | 声网空间音频 | | -------- | -------------------------------------------- | --------------------------------------------------- | | 立体感 | 左右两个维度 | 以世界坐标系的 x、y、z 坐标轴表示右、上、前三个维度 | | 空间感 | 通过调节左右声道的音量，体现具有空间感的声音 | 使用空间音频算法，通过设置距离、方位、朝向等参数，塑造声音的空间感 | | 用户体验 | 平面 | 立体、自然、真实 | ## 适用场景 [#适用场景-5] #### 社交语聊 [#社交语聊-5] 在语聊房 App 界面中，以九宫格的形式展示所有用户头像，并对每个用户赋予一个坐标和朝向。在互动过程中，你可以感受到周围的用户发出的声音大小和方位跟其所在的位置有关。如果你在屏幕中拖动自己的头像，随着你跟某个用户之间的距离逐渐变远，你会听到该用户的声音也越来越小，超出一定范围后会彻底听不到，符合现实环境中声音的传播特点。 #### 游戏 & 元宇宙 [#游戏--元宇宙-5] 在游戏和元宇宙这类 3D 场景中，你可以使用空间音频技术实现更多功能，如下表所示： | 功能 | 描述 | | --- | --- | | 声音模糊 | 对指定远端用户或媒体播放器开启声音模糊处理。例如：在咖啡厅场景中，如果需要制造两个虚拟角色 “说悄悄话” 的效果，可以对他们开启声音模糊处理模式，其他角色会听到被处理过的、模糊的声音。 | | 范围音频 | [spatial-audio-unity-html-0-2-1 details](#table-slot-spatial-audio-unity-html-0-2-1) | | 超拟真空间塑造 | [spatial-audio-unity-html-0-3-1 details](#table-slot-spatial-audio-unity-html-0-3-1) | | 隔声区域 | 定义一个隔声区域并对隔声区域内的音源设置声音衰减系数，使区域外的接收方听区域内的音源时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。例如：在 KTV 场景中，当虚拟角色在 KTV 包厢外时，只能听到来自包厢内的较小的声音；在打开包厢门的时候，会在一瞬间体验到包厢里唱歌的声音迎面扑来。 | **spatial-audio-unity-html-0-2-1 details** 根据当前场景的大小设置一个音频接收范围，在该范围以内，声音传播得越远，接收方听到的声音越小。你可以通过设置声音衰减系数，在不同的场景下获得更加拟真的衰减效果： - 在丛林场景中，将衰减系数设置为 0.9，声音在传播时迅速衰减。 - 在平原场景中，将衰减系数设置为 0.1，声音可以传播得很远。 **spatial-audio-unity-html-0-3-1 details** 为全方位模拟真实场景的空间感，对每个虚拟角色赋予 4 组坐标，分别表示以下维度： - 虚拟角色空间坐标（x,y,z）：虚拟角色在 3D 空间里的坐标。 - 虚拟角色面部朝向坐标（x,y,z）：虚拟角色在场景中的面部朝向坐标。 - 虚拟角色头顶朝向坐标（x,y,z）：虚拟角色的头顶指向的坐标，可结合面部朝向坐标确定虚拟角色的动作和姿态。例如：虚拟角色平躺的时候，面部朝向天空，头顶朝向前方。 - 右手朝向（x,y,z）：直角坐标系是使用左手坐标系还是右手坐标系。在一个场景中只能使用一种坐标系。 #### 在线会议 [#在线会议-5] 在线会议场景下，你可以将所有上麦用户分布到主持人的周围，并赋予每个用户坐标。用户听到的每个声音都有方向感和空间感，模拟真实环境下的会议室体验，相比传统在线会议，能够带给用户全新的与会体验、降低用户疲惫感。 ## 技术原理 [#技术原理-5] 实现用户空间音频和媒体播放器空间音频时的原理有所不同： - 用户空间音频：自行部署服务器，用于发送本地空间位置以及接收远端用户的空间位置，然后由 SDK 计算用户间的相对位置，从而计算出相应的空间音频参数。 - 媒体播放器空间音频：通过 SDK 计算本地用户和媒体播放器的相对位置，然后计算出相应的空间音频参数。 ## 前提条件 [#前提条件-5] 在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 实现空间音频 [#实现空间音频-5] 本节介绍如何使用 SDK 实现空间音频，API 调用时序如下图所示。 ### 初始化空间音频引擎 [#初始化空间音频引擎-5] 调用 `IRtcEngine` 类中的 `GetLocalSpatialAudioEngine` 获取 `ILocalSpatialAudioEngine` 对象，调用 `ILocalSpatialAudioEngine` 类下的 `Initialize` 初始化对象，开启空间音频。 ```csharp SpatialAudioEngine = RtcEngine.GetLocalSpatialAudioEngine(); var ret = SpatialAudioEngine.Initialize(); Debug.Log("_spatialAudioEngine: Initialize " + ret); ``` ### 设置音频属性和场景 [#设置音频属性和场景-5] - 调用 `SetAudioProfile` 设置音频编码属性。 - 调用 `SetAudioScenario` 设置音频应用场景。声网推荐你将 `scenario` 设置为 `AUDIO_SCENARIO_GAME_STREAMING`。 ```csharp RtcEngine.SetAudioProfile(AUDIO_PROFILE_TYPE.AUDIO_PROFILE_DEFAULT); RtcEngine.SetAudioScenario(AUDIO_SCENARIO_TYPE.AUDIO_SCENARIO_GAME_STREAMING); ``` ### 设置音频接收范围 [#设置音频接收范围-5] - 调用 `SetAudioRecvRange` 设置可接收音频的最大范围，单位为米，建议 `range` 取值＞ 0。 - 调用 `SetMaxAudioRecvCount` 设置音频接收范围内最多可接收的音频流数，建议 `maxCount` 取值 ≤ 16。 ```csharp SpatialAudioEngine.SetAudioRecvRange(30); SpatialAudioEngine.SetMaxAudioRecvCount(10); ``` ### 更新空间位置 [#更新空间位置-5] - 在用户空间音频场景下，调用 `UpdateSelfPosition` 和 `UpdateRemotePosition` 方法，分别更新本地用户和远端用户的位置。 - 在媒体播放器空间音频场景下，调用 `UpdateSelfPosition` 和 `UpdatePlayerPositionInfo` 方法，分别更新本地用户和媒体播放器的位置。推荐的调用时机如下所示： - 当频道内有新用户加入。 - 当本地、远端用户或媒体播放器的相对位置发生改变。 - 根据实际需求调用。 ```csharp // 更新本地用户位置 // 隔声区域的空间中心点 float[] localUserPosition = new float[] { 0.0f, 0.0f, 0.0f }; // 以 position 为起点，向前的单位向量，对应 Unity Vector3 的 z 轴 float[] forward = new float[] { 1.0f, 0.0f, 0.0f }; // 以 position 为起点，向右的单位向量，对应 Unity Vector3 的 x 轴 float[] right = new float[] { 0.0f, 1.0f, 0.0f }; // 以 position 为起点，向上的单位向量，对应 Unity Vector3 的 y 轴 float[] up = new float[] { 0.0f, 0.0f, 1.0f }; var ret = SpatialAudioEngine.UpdateSelfPosition(localUserPosition, forward, right, up); Debug.Log("UpdateSelfPosition return: " + ret); // 更新远端用户位置 float[] positionRemote = { 0.0f, 1.0f, 0.0f }; float[] forwardRemote = { 0, 0, 0 }; RemoteVoicePositionInfo remoteVoicePositionInfo = new RemoteVoicePositionInfo(positionRemote, forwardRemote); var ret = SpatialAudioEngine.UpdateRemotePosition(UidUseInMPK, remoteVoicePositionInfo); Debug.Log("_spatialAudio.UpdateRemotePosition returns: " + ret); ``` ### 设置空间音频参数 [#设置空间音频参数-5] 调用 `SetRemoteUserSpatialAudioParams` 或 `SetSpatialAudioParams` 为远端用户或媒体播放器设置空间音频参数。如果要实现特定音效，可参考如下参数设置： - 空气衰减效果：即模拟声音在空气中传播的音色衰减效果。在一定的传输距离下，高频声音衰减速度快、低频声音衰减速度慢。你可以通过 `enable_air_absorb` 控制是否开启空气衰减效果。开启后需确认 `speaker_attenuation` 的值不为 `0`，否则该设置不生效。 - 声音模糊效果：将 `enable_blur` 设置为 `true`。 ```csharp SpatialAudioParams audioParams = new SpatialAudioParams(); // 开启空气衰减效果 audioParams.enable_air_absorb.SetValue(true); // 开启声音模糊效果 audioParams.enable_blur.SetValue(true); // 以设置远端用户空间音频参数为例 RtcEngine.SetRemoteUserSpatialAudioParams(uid, audioParams); ``` ### （可选）设置隔声区域 [#可选设置隔声区域-5] 1. 调用 `SetZones` 设置一个隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟接收方分属于隔声区域内部和外部时，会体验到类似真实环境中，声音在遇到建筑隔断时的衰减效果。 2. 调用 `SetRemoteAudioAttenuation` 或 `SetPlayerAttenuation` 分别针对用户和媒体播放器设置声音衰减属性，并指定是否使用该设置强制覆盖 `SetZones` 中的声音衰减系数。 ```csharp SpatialAudioZone mediaPlayerLeftZone = new SpatialAudioZone(); mediaPlayerLeftZone.zoneSetId = 1; mediaPlayerLeftZone.audioAttenuation = 1.0f; float[] voicePosition = { 0.0f, 0.0f, 0.0f }; float[] viewRelativeSizeInAxis = { 1.0f, 1.0f, 1.0f }; // 在世界坐标系中的坐标 mediaPlayerLeftZone.position = new float[] { voicePosition[0], voicePosition[1], 0 }; // 以 position 为起点，向前的单位向量，对应 Unity Vector3 的 z 轴 mediaPlayerLeftZone.forward = new float[] { 1.0f, 0, 0 }; // 以 position 为起点，向右的单位向量，对应 Unity Vector3 的 x 轴 mediaPlayerLeftZone.right = new float[] { 0, 1.0f, 0 }; // 以 position 为起点，向上的单位向量，对应 Unity Vector3 的 y 轴 mediaPlayerLeftZone.up = new float[] { 0, 0, 1.0f }; // 隔声区域的前向长度 mediaPlayerLeftZone.forwardLength = viewRelativeSizeInAxis[1]; // 隔声区域的右向长度 mediaPlayerLeftZone.rightLength = viewRelativeSizeInAxis[0]; // 隔声区域的上向长度 mediaPlayerLeftZone.upLength = viewRelativeSizeInAxis[2]; SpatialAudioEngine.SetZones(new SpatialAudioZone[] { mediaPlayerLeftZone },1); // 针对用户设置声音衰减属性 SpatialAudioEngine.SetRemoteAudioAttenuation(uid, 0.5f, false); // 针对媒体播放器设置声音衰减属性 SpatialAudioEngine.SetPlayerAttenuation(MediaPlayer.GetId(), 0.5f, false); ``` ### （可选）设置耳机均衡效果 [#可选设置耳机均衡效果-5] 1. 调用 `SetHeadphoneEQPreset` 方法，选择预设的耳机均衡器收听音频，以达到预期的音频体验。 2. 如果执行上一步后仍未达到预期，你可以调用 `SetHeadphoneEQParameters` 自行调节耳机均衡效果，执行该方法后，`SetHeadphoneEQPreset` 方法设置的预设值会被覆盖。 ```csharp RtcEngine.SetHeadphoneEQPreset(HEADPHONE_EQUALIZER_PRESET.HEADPHONE_EQUALIZER_OVEREAR); RtcEngine.SetHeadphoneEQParameters(10, 10); ``` ### 暂停或关闭空间音频 [#暂停或关闭空间音频] 在互动过程中，你可选择暂停或关闭空间音频。 #### （可选）暂停指定远端用户在本地的空间音频 [#可选暂停指定远端用户在本地的空间音频] 1. 如果不想继续体验远端用户在本地的空间音频、或远端用户已退出频道，调用 `RemoveRemotePosition` 删除该用户的空间位置信息，以节省计算资源。 :::warning[注意] 当远端用户离开频道时，必须调用 `RemoveRemotePosition` 删除该用户的空间位置信息，否则可能导致本地听不到来自其他远端用户的空间音频。 ::: 2. 如果之后想恢复该用户在本地的空间音频，可调用 `UpdateRemotePosition` 方法重新设置远端用户的位置信息。 ```csharp // 暂停指定远端用户在本地的空间音频 SpatialAudioEngine.RemoveRemotePosition(uid); // 恢复指定远端用户在本地的空间音频系统下的坐标和朝向 float[] position = new float[] { 1.0f, 1.0f, 1.0f }; // 以 position 为起点，向右的单位向量，对应 Unity Vector3 的 x 轴 float[] forward = new float[] { 1.0f, 1.0f, 1.0f }; RemoteVoicePositionInfo positionInfo = new RemoteVoicePositionInfo(position, forward); SpatialAudioEngine.UpdateRemotePosition(uid, positionInfo); ``` #### （可选）暂停所有远端用户在本地的空间音频 [#可选暂停所有远端用户在本地的空间音频] 1. 如果你不想再继续体验本地的空间音频，可以调用 `ClearRemotePositions` 删除所有远端用户的空间位置信息。 :::warning[注意] 调用该方法会导致本地听不到所有远端用户的音频，声网建议你谨慎调用该方法。 ::: 2. 如果之后还需要听到远端用户的音频，你需要重新调用 `ILocalSpatialAudioEngine` 中的 `MuteAllRemoteAudioStreams` 并将 `mute` 设为 `false` 恢复订阅远端用户的音频流。 ```csharp // 删除所有远端用户的空间位置信息 SpatialAudioEngine.ClearRemotePositions(); // 恢复订阅远端用户的音频流 SpatialAudioEngine.MuteAllRemoteAudioStreams(false); ``` #### （可选）暂停本地用户在远端的空间音频 [#可选暂停本地用户在远端的空间音频] 1. 调用 `ILocalSpatialAudioEngine` 中的 `MuteLocalAudioStream` 并将 `mute` 设为 `true` 以取消发布本地音频流。 2. 如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `false`，即可恢复空间音频。 ```csharp // 取消发布本地音频流 SpatialAudioEngine.MuteLocalAudioStream(true); // 恢复发布本地音频流 SpatialAudioEngine.MuteLocalAudioStream(false); ``` #### 关闭空间音频 [#关闭空间音频-10] 1. 在频道内调用 `IRtcEngine` 中的 `EnableSpatialAudio` 并将 `enabled` 参数设置为 `false`，此时所有跟空间音频相关的设置都会被重置。 2. 如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `true`，然后重新调用相关 API 设置空间音频效果。 3. 如果你不需要再使用空间音频功能，调用 `ILocalSpatialAudioEngine` 中的 `Dispose` 销毁 `ILocalSpatialAudioEngine` 对象。 ```csharp // 关闭空间音频 RtcEngine.EnableSpatialAudio(false); // 销毁 ILocalSpatialAudioEngine 对象 SpatialAudioEngine.Dispose(); ``` ## 相关文档 [#相关文档] ### 示例项目 [#示例项目-5] 声网提供了开源的实时音视频互动示例项目供你参考，你可以前往下载或查看其中的源代码。 SpatialAudioWithMediaPlayer} href="https://gitee.com/agoraio-community/Agora-Unity-Quickstart/blob/main/API-Example-Unity/Assets/API-Example/Examples/Advanced/SpatialAudioWithMediaPlayer/SpatialAudioWithMediaPlayer.cs" /> SpatialAudioWithMediaPlayer} href="https://github.com/AgoraIO-Extensions/Agora-Unity-Quickstart/blob/main/API-Example-Unity/Assets/API-Example/Examples/Advanced/SpatialAudioWithMediaPlayer/SpatialAudioWithMediaPlayer.cs" /> ### API 参考 [#api-参考-5] - [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) - [`Initialize`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#initialize) - [`SetMaxAudioRecvCount`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setmaxaudiorecvcount) - [`SetAudioRecvRange`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setaudiorecvrange) - [`UpdateSelfPosition`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#updateselfposition) - [`UpdateRemotePosition`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#updateremoteposition) - [`UpdatePlayerPositionInfo`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#updateplayerpositioninfo) - [`SetRemoteUserSpatialAudioParams`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setremoteuserspatialaudioparams) - [`SetZones`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setzones) - [`SetRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setremoteaudioattenuation) - [`SetPlayerAttenuation`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setplayerattenuation) - [`ClearRemotePositions`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#clearremotepositions) - [`MuteLocalAudioStream`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#mutelocalaudiostream) - [`MuteAllRemoteAudioStreams`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#muteallremoteaudiostreams) - [`EnableSpatialAudio`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#enablespatialaudio) - [`Dispose`](/zh-CN/api-reference/rtc/unity/initialize#api_irtcengine_release) - [`IMediaPlayer`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imediaplayer) - [`SetSpatialAudioParams`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setspatialaudioparams) - [`IRtcEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) - [`GetLocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_getlocalspatialaudioengine) - [`SetHeadphoneEQPreset`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setheadphoneeqpreset) - [`SetHeadphoneEQParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#setheadphoneeqparameters) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="react-native" /> 空间音频能够将真实世界的声音体验带到虚拟数字世界，为用户提供更具吸引力的在线体验。通过声网提供的空间音频技术，你可以在虚拟互动场景下模拟声音在现实环境中的传播特点： **超拟真空间塑造效果** 利用范围音频、声音模糊、空气衰减模拟等技术，完美模拟现实听觉感受。 - 当声源和其他角色之间的距离、方位或朝向发生变化时，不同的角色听到的声音大小和方向均不相同。 - 当声源和其他角色之间的距离超过设置的范围后，后者无法听到声源发出的声音。 - 通过设置隔声区域、空气衰减、声音模糊等音效，完美模拟现实的听觉感受。 **3D 高保真** - 根据面部朝向、音源朝向、3D 空间内音源的相对位置进行音效处理渲染。 - 支持 48 kHz 全频带采样和 3D 高保真音效处理及渲染。 **多平台适配** 支持 iOS、Android、macOS、Windows、Web、Unity、Flutter、React Native、Electron、Unreal 等平台。 **超低延时、低功耗、低成本** 空间音频算法采用先进的前端处理模式，并通过云服务同步空间坐标，端云协同处理模式能够有效降低整体延时和功耗。相比传统的左右声道立体声，声网提供的空间音频技术在声音的立体感和空间感上都有明显的提升，两者区别如下所示： | 对比项 | 传统立体声 | 声网空间音频 | | -------- | -------------------------------------------- | --------------------------------------------------- | | 立体感 | 左右两个维度 | 以世界坐标系的 x、y、z 坐标轴表示右、上、前三个维度 | | 空间感 | 通过调节左右声道的音量，体现具有空间感的声音 | 使用空间音频算法，通过设置距离、方位、朝向等参数，塑造声音的空间感 | | 用户体验 | 平面 | 立体、自然、真实 | ## 适用场景 [#适用场景-6] #### 社交语聊 [#社交语聊-6] 在语聊房 App 界面中，以九宫格的形式展示所有用户头像，并对每个用户赋予一个坐标和朝向。在互动过程中，你可以感受到周围的用户发出的声音大小和方位跟其所在的位置有关。如果你在屏幕中拖动自己的头像，随着你跟某个用户之间的距离逐渐变远，你会听到该用户的声音也越来越小，超出一定范围后会彻底听不到，符合现实环境中声音的传播特点。 #### 游戏 & 元宇宙 [#游戏--元宇宙-6] 在游戏和元宇宙这类 3D 场景中，你可以使用空间音频技术实现更多功能，如下表所示： | 功能 | 描述 | | --- | --- | | 声音模糊 | 对指定远端用户或媒体播放器开启声音模糊处理。例如：在咖啡厅场景中，如果需要制造两个虚拟角色 “说悄悄话” 的效果，可以对他们开启声音模糊处理模式，其他角色会听到被处理过的、模糊的声音。 | | 范围音频 | [spatial-audio-rn-electron-html-0-2-1 details](#table-slot-spatial-audio-rn-electron-html-0-2-1-1) | | 超拟真空间塑造 | [spatial-audio-rn-electron-html-0-3-1 details](#table-slot-spatial-audio-rn-electron-html-0-3-1-1) | | 隔声区域 | 定义一个隔声区域并对隔声区域内的音源设置声音衰减系数，使区域外的接收方听区域内的音源时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。例如：在 KTV 场景中，当虚拟角色在 KTV 包厢外时，只能听到来自包厢内的较小的声音；在打开包厢门的时候，会在一瞬间体验到包厢里唱歌的声音迎面扑来。 | **spatial-audio-rn-electron-html-0-2-1 details** 根据当前场景的大小设置一个音频接收范围，在该范围以内，声音传播得越远，接收方听到的声音越小。你可以通过设置声音衰减系数，在不同的场景下获得更加拟真的衰减效果： - 在丛林场景中，将衰减系数设置为 0.9，声音在传播时迅速衰减。 - 在平原场景中，将衰减系数设置为 0.1，声音可以传播得很远。 **spatial-audio-rn-electron-html-0-3-1 details** 为全方位模拟真实场景的空间感，对每个虚拟角色赋予 4 组坐标，分别表示以下维度： - 虚拟角色空间坐标（x,y,z）：虚拟角色在 3D 空间里的坐标。 - 虚拟角色面部朝向坐标（x,y,z）：虚拟角色在场景中的面部朝向坐标。 - 虚拟角色头顶朝向坐标（x,y,z）：虚拟角色的头顶指向的坐标，可结合面部朝向坐标确定虚拟角色的动作和姿态。例如：虚拟角色平躺的时候，面部朝向天空，头顶朝向前方。 - 右手朝向（x,y,z）：直角坐标系是使用左手坐标系还是右手坐标系。在一个场景中只能使用一种坐标系。 #### 在线会议 [#在线会议-6] 在线会议场景下，你可以将所有上麦用户分布到主持人的周围，并赋予每个用户坐标。用户听到的每个声音都有方向感和空间感，模拟真实环境下的会议室体验，相比传统在线会议，能够带给用户全新的与会体验、降低用户疲惫感。 ## 技术原理 [#技术原理-6] 实现用户空间音频和媒体播放器空间音频时的原理有所不同： - 用户空间音频：自行部署服务器，用于发送本地空间位置以及接收远端用户的空间位置，然后由 SDK 计算用户间的相对位置，从而计算出相应的空间音频参数。 - 媒体播放器空间音频：通过 SDK 计算本地用户和媒体播放器的相对位置，然后计算出相应的空间音频参数。 ## 前提条件 [#前提条件-6] 在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 实现空间音频 [#实现空间音频-6] 本节介绍如何使用 SDK 实现空间音频，API 调用时序如下图所示。 ### 初始化空间音频引擎 [#初始化空间音频引擎-6] 调用 `getLocalSpatialAudioEngine` 和 `initialize` 初始化 `ILocalSpatialAudioEngine` 对象，开启空间音频。 ```typescript rtcEngine = createAgoraRtcEngine(); localSpatial = rtcEngine.getLocalSpatialAudioEngine() localSpatial.initialize(); ``` ### 设置音频属性和场景 [#设置音频属性和场景-6] 1. 调用 `setAudioProfile`，将 `profile` 设置为你预期的音频编码属性。 2. 调用 `setAudioScenario`，将 `scenario` 设置为 `AudioScenarioGameStreaming`，以获得预期的音质效果。 ```typescript rtcEngine.setAudioProfile(AudioProfileType.AudioProfileSpeechStandard); rtcEngine.setAudioScenario(AudioScenarioType.AudioScenarioGameStreaming); ``` ### 设置音频接收范围 [#设置音频接收范围-6] - 调用 `setMaxAudioRecvCount` 设置音频接收范围内最多可接收的音频流数，建议 `maxCount` 取值 ≤ 16。 - 调用 `setAudioRecvRange` 设置可接收音频的最大范围，单位为米，建议 `range` 取值＞ 0。 ```typescript localSpatial.setMaxAudioRecvCount(2); localSpatial.setAudioRecvRange(50); ``` ### 更新空间位置 [#更新空间位置-6] - 在用户空间音频场景下，调用 `updateSelfPosition` 和 `updateRemotePosition` 方法，分别更新本地用户和远端用户的位置。 - 在媒体播放器空间音频场景下，调用 `updateSelfPosition` 和 `updatePlayerPositionInfo` 方法，分别更新本地用户和媒体播放器的位置。推荐的调用时机如下所示： - 当频道内有新用户加入。 - 当本地、远端用户或媒体播放器的相对位置发生改变。 - 根据实际需求调用。 ```typescript // 更新本地用户位置 localSpatial.updateSelfPosition( [0, 0, 0], // position [1, 0, 0], // axisForward [0, 1, 0], // axisRight [0, 0, 1] // axisUp ); // 更新远端用户位置 localSpatial.updateRemotePosition( uid, // 远端用户 ID { position: [0, 0, 0], axisForward: [1, 0, 0], } ); // 更新媒体播放器位置 localSpatial.updatePlayerPositionInfo( mediaPlayer.getMediaPlayerId(), // 媒体播放器 ID { position: [0, 0, 0], axisForward: [1, 0, 0], } ); ``` ### 设置空间音频参数 [#设置空间音频参数-6] 调用 `setRemoteUserSpatialAudioParams` 或 `setSpatialAudioParams`，针对远端用户或媒体播放器设置空间音频参数。如果要实现特定音效，可参考如下参数设置： - 空气衰减效果：将 `enable_air_absorb` 设置为 `true`；并将 `speaker_attenuation` 设置为预期的声音衰减系数。 - 声音模糊效果：将 `enable_blur` 设置为 `true`。 ```typescript rtcEngine.setRemoteUserSpatialAudioParams( uid, { enable_air_absorb: true, speaker_attenuation: 0.5, enable_blur: true, } ); ``` ### （可选）设置隔声区域 [#可选设置隔声区域-6] 1. 调用 `setZones` 设置一个隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟接收方分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。 1. （可选）调用 `setRemoteAudioAttenuation` 或 `setPlayerAttenuation` 分别针对用户和媒体播放器设置声音衰减属性，并指定是否使用该设置强制覆盖 `setZones` 中的声音衰减系数。 ```typescript localSpatial.setZones( [ { zoneSetId: 1, // 隔声区域的 ID position: [0, 0, 0], // 隔声区域的空间中心点 forward: [1, 0, 0], // 以 position 为起点，向前的单位向量 right: [0, 1, 0], // 以 position 为起点，向右的单位向量 up: [0, 0, 1], // 以 position 为起点，向上的单位向量 forwardLength: 10, // 隔声区域的前向长度 rightLength: 10, // 隔声区域的右向长度 upLength: 10, // 隔声区域的上向长度 audioAttenuation: 0.5, // 隔声区域和外部互通时的声音衰减系数 } ], 1 ); localSpatial.setRemoteAudioAttenuation( mediaPlayer.getMediaPlayerId(), // 媒体播放器 ID 0.5, false ); localSpatial.setPlayerAttenuation( mediaPlayer.getMediaPlayerId(), // 媒体播放器 ID 0.5, false ); ``` ### （可选）设置耳机均衡效果 [#可选设置耳机均衡效果-6] 1. 调用 `setHeadphoneEQPreset` 方法，选择预设的耳机均衡器收听音频，以达到预期的音频体验。 1. （可选）如果执行上一步后仍未达到预期，你可以调用 `setHeadphoneEQParameters` 自行调节耳机均衡效果，执行该方法后，`setHeadphoneEQPreset` 方法设置的预设值会被覆盖。 ```typescript rtcEngine.setHeadphoneEQPreset(HeadphoneEqualizerPreset.HeadphoneEqualizerOverear); rtcEngine.setHeadphoneEQParameters(10, 10); ``` ### 关闭空间音频 [#关闭空间音频-11] 在互动过程中，你可选择暂停或关闭空间音频。 #### 暂停指定远端用户在本地的空间音频 [#暂停指定远端用户在本地的空间音频-5] 1. 如果不想继续体验远端用户在本地的空间音频、或远端用户已退出频道，调用 `removeRemotePosition` 删除该用户的空间位置信息，以节省计算资源。 :::warning[注意] 当远端用户离开频道时，必须调用 `removeRemotePosition` 删除该用户的空间位置信息，否则可能导致本地听不到来自其他远端用户的空间音频。 ::: 1. （可选）如果之后想恢复该用户在本地的空间音频，可调用 `updateRemotePosition` 方法重新设置远端用户的位置信息。 ```typescript // 暂停指定远端用户在本地的空间音频 localSpatial.removeRemotePosition(uid) // 恢复指定远端用户在本地的空间音频 localSpatial.updateRemotePosition( uid, // 远端用户 ID { position: [0, 0, 0], axisForward: [1, 0, 0], } ); ``` #### 暂停所有远端用户在本地的空间音频 [#暂停所有远端用户在本地的空间音频-5] 1. 如果你不想再继续体验本地的空间音频，可以调用 `clearRemotePositions` 删除所有远端用户的空间位置信息。 :::warning[注意] 调用该方法会导致本地听不到所有远端用户的音频，声网建议你谨慎调用该方法。 ::: 1. （可选）如果之后还需要听到远端用户的音频，你需要重新调用 `ILocalSpatialAudioEngine` 中的 `muteAllRemoteAudioStreams(false)` 恢复订阅远端用户的音频流。 ```typescript // 删除所有远端用户的空间位置信息 localSpatial.clearRemotePositions(); // 恢复订阅远端用户的音频流 localSpatial.muteAllRemoteAudioStreams(false); ``` #### 暂停本地用户在远端的空间音频 [#暂停本地用户在远端的空间音频-5] 1. 调用 `ILocalSpatialAudioEngine` 中的 `muteLocalAudioStream(true)`，取消发布本地音频流。 1. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `false`，即可恢复空间音频。 ```typescript // 取消发布本地音频流 localSpatial.muteLocalAudioStream(true); // 恢复发布本地音频流 localSpatial.muteLocalAudioStream(false); ``` #### 关闭空间音频 [#关闭空间音频-12] 1. 在频道内调用 `RtcEngine` 中的 `enableSpatialAudio` 并将参数设置为 `false`，此时所有跟空间音频相关的设置都会被重置。 2. （可选）如果之后想再次开启空间音频，可再次调用该方法并将参数设置为 `true`，然后重新调用相关 API 设置空间音频效果。 3. 调用 `ILocalSpatialAudioEngine` 中的 `release` 销毁 `ILocalSpatialAudioEngine` 对象。 ```typescript // 关闭空间音频 rtcEngine.enableSpatialAudio(false); // 销毁 ILocalSpatialAudioEngine 对象 localSpatial.release(); ``` ## 参考信息 [#参考信息-5] ### 示例项目 [#示例项目-6] 声网提供了开源的空间音频示例项目供你参考，你可以前往下载或查看其中的源代码。 :::info[信息] 示例项目中的 `SpatialAudio.tsx` 和 `LocalSpatialAudioEngine.tsx` 需配合使用才能实现空间音频。 ::: SpatialAudio} href="https://gitee.com/agoraio-community/react-native-agora/tree/main/example/src/examples/advanced/SpatialAudio/SpatialAudio.tsx" /> SpatialAudio} href="https://github.com/AgoraIO-Extensions/react-native-agora/blob/main/examples/legacy/src/examples/advanced/SpatialAudio/SpatialAudio.tsx" /> LocalSpatialAudioEngine} href="https://gitee.com/agoraio-community/react-native-agora/tree/main/example/src/examples/advanced/LocalSpatialAudioEngine/LocalSpatialAudioEngine.tsx" /> LocalSpatialAudioEngine} href="https://github.com/AgoraIO-Extensions/react-native-agora/blob/main/examples/legacy/src/examples/advanced/LocalSpatialAudioEngine/LocalSpatialAudioEngine.tsx" /> ### API 参考 [#api-参考-6] - [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_ilocalspatialaudioengine) - [`initialize`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#initialize) - [`setMaxAudioRecvCount`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setmaxaudiorecvcount) - [`setAudioRecvRange`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setaudiorecvrange) - [`updateSelfPosition`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#updateselfposition) - [`updateRemotePosition`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#updateremoteposition) - [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#updateplayerpositioninfo) - [`setRemoteUserSpatialAudioParams`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setremoteuserspatialaudioparams) - [`setSpatialAudioParams`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setspatialaudioparams) - [`setZones`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setzones) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setremoteaudioattenuation) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setplayerattenuation) - [`clearRemotePositions`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#clearremotepositions) - [`muteLocalAudioStream`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#mutelocalaudiostream) - [`muteAllRemoteAudioStreams`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#muteallremoteaudiostreams) - [`enableSpatialAudio`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#enablespatialaudio) - [`destroy`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#destroy) - [`RtcEngine`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#setheadphoneeqparameters) <_PlatformProcessedMarker close="true" />