空间音效

initialize

初始化 ILocalSpatialAudioEngine。

C++

virtual int initialize(const LocalSpatialAudioConfig& config) = 0;

注：

• 你需要在 queryInterface(AGORA_IID_LOCAL_SPATIAL_AUDIO) 后调用该方法。

• 在调用 ILocalSpatialAudioEngine 类的其他方法前，你需要先调用该方法初始化 ILocalSpatialAudioEngine。

• SDK 只支持每个 app 创建一个 ILocalSpatialAudioEngine 实例。

参数

参数名	描述
config	ILocalSpatialAudioEngine 的配置。详见 LocalSpatialAudioConfig。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• ILocalSpatialAudioEngine

muteAllRemoteAudioStreams

取消或恢复订阅所有远端用户的音频流。

C++

virtual int muteAllRemoteAudioStreams(bool mute) = 0;

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流，包括在调用该方法后加入频道的用户的音频流。

注：

• 该方法需要在 joinChannel [2/2] 后调用。

• 在使用空间音效时，如需设置是否订阅所有远端用户的音频流，建议调用该方法替代 IRtcEngine 的 muteAllRemoteAudioStreams 方法。

• 在调用该方法后，你需要调用 updateSelfPosition 和 updateRemotePosition 更新本地用户和远端用户的空间位置，否则该方法中的设置不会生效。

参数

参数名	描述
mute	是否取消订阅所有远端用户的音频流： true: 取消订阅所有远端用户的音频流。 false: 订阅所有远端用户的音频流。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

muteLocalAudioStream

取消或恢复发布本地音频流。

C++

virtual int muteLocalAudioStream(bool mute) = 0;

注：

• 该方法不影响音频采集状态，因为没有禁用音频采集设备。

• 该方法需要在 joinChannel [2/2] 后调用。

• 在使用空间音效时，如需设置是否发布本地音频流，建议调用该方法替代 IRtcEngine 的 muteLocalAudioStream 方法。

• 成功调用该方法后，远端会触发 onUserMuteAudio 回调和 onRemoteAudioStateChanged 回调。

参数

参数名	描述
mute	是否取消发布本地音频流。 true: 取消发布本地音频流。 false: 发布本地音频流。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

muteRemoteAudioStream

取消或恢复订阅指定远端用户的音频流。

C++

virtual int muteRemoteAudioStream(uid_t uid, bool mute) = 0;

自从

v4.0.1

注：

• 该方法需要在 joinChannel [2/2] 后调用。

• 在使用空间音效时，如需设置是否订阅指定用户的音频流，建议调用该方法替代 IRtcEngine 的 muteRemoteAudioStream 方法。

参数

参数名	描述
uid	用户 ID。需与用户加入频道时填写的用户 ID 一致。
mute	是否取消订阅指定远端用户的音频流。 true: 取消订阅指定用户的音频流。 false:（默认）订阅指定用户的音频流，SDK 根据本地用户和远端用户的距离决定是否订阅。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

updateRemotePosition

更新远端用户的空间位置信息。

C++

virtual int updateRemotePosition(uid_t uid, const RemoteVoicePositionInfo &posInfo) = 0;

成功调用该方法后，SDK 会根据本地和远端用户的相对位置计算空间音效参数。

注： 该方法需要在 joinChannel [2/2] 后调用。

参数

参数名	描述
uid	用户 ID。需与用户加入频道时填写的用户 ID 一致。
posInfo	远端用户的空间位置信息。详见 RemoteVoicePositionInfo。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• ILocalSpatialAudioEngine

updateSelfPosition

更新本地用户的空间位置。

C++

virtual int updateSelfPosition(float position[3], float axisForward[3], float axisRight[3], float axisUp[3]) = 0;

• 在 ILocalSpatialAudioEngine 类下，该方法需要和 updateRemotePosition 搭配使用。SDK 会根据该方法和 updateRemotePosition 设置的参数计算本地和远端用户之间的相对位置，从而计算用户的空间音效参数。

参数

参数名	描述
position	在世界坐标系中的坐标。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。
axisForward	在世界坐标系前轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。
axisRight	在世界坐标系右轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。
axisUp	在世界坐标系上轴的单位向量。该参数是长度为 3 的数组，三个值依次表示前、右、上的坐标值。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

release

销毁 IBaseSpatialAudioEngine。

C++

virtual void release() = 0;

该方法释放 IBaseSpatialAudioEngine 下的所有资源。当用户不需要使用空间音效时，你可以调用该方法将资源释放出来用于其他操作。

调用该方法后，你将无法再使用 IBaseSpatialAudioEngine 下的任何 API。

注： 该方法需要在 IRtcEngine 的 release 方法前调用。

所属接口类

• IBaseSpatialAudioEngine

clearRemotePositions

删除所有远端用户的空间位置信息。

C++

virtual int clearRemotePositions() = 0;

成功调用该方法后，本地用户将听不到所有远端用户。

离开频道后，为避免计算资源的浪费，你也可以调用该方法删除所有远端用户的空间位置信息。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• ILocalSpatialAudioEngine

removeRemotePosition

删除指定远端用户的空间位置信息。

C++

virtual int removeRemotePosition(uid_t uid) = 0;

成功调用该方法后，本地用户将听不到指定的远端用户。

离开频道后，为避免计算资源的浪费，你也可以调用该方法删除指定远端用户的空间位置信息。

参数

参数名	描述
uid	用户 ID。需与用户加入频道时填写的用户 ID 一致。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• ILocalSpatialAudioEngine

setAudioRecvRange

设置本地用户的音频接收范围。

C++

virtual int setAudioRecvRange(float range) = 0;

设置成功后，用户只能听见设置范围内或属于同一队伍的远端用户。你可以随时调用该方法更新音频的接收范围。

参数

参数名	描述
range	可接收音频的最大范围，单位为游戏引擎中的距离单位。该参数取值需大于 0，默认值为 20。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setDistanceUnit

设置游戏引擎单位距离的长度（米）。

C++

virtual int setDistanceUnit(float unit) = 0;

游戏引擎里的距离单位是游戏引擎自定义的，而声网空间音效算法的距离单位为米。默认情况下，SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法，将游戏引擎里的单位距离换算为指定的米数。

参数

参数名	描述
unit	每单位游戏引擎距离转换后的米数。该参数取值需大于 0.00，默认值为 1.00。例如，将 unit 设为 2.00，表示每单位的游戏引擎距离等于 2 米。 该值越大，当远端用户远离本地用户时，本地用户听到的声音衰减速度越快。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setMaxAudioRecvCount

设置音频接收范围内最多可接收的音频流数。

C++

virtual int setMaxAudioRecvCount(int maxCount) = 0;

如果在音频接收范围内可接收的音频流数超过设置的值，则本地用户会接收音源距离较近的 maxCount 路音频。

参数

参数名	描述
maxCount	音频接收范围内最多可接收的音频流数。该参数取值需 ≤ 16，默认值为 10。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setPlayerAttenuation

设置媒体播放器的声音衰减属性。

C++

virtual int setPlayerAttenuation(int playerId, double attenuation, bool forceSet) = 0;

自从

v4.0.1

参数

参数名	描述
playerId	媒体播放器 ID。可通过 getMediaPlayerId 获取。
attenuation	媒体播放器的声音衰减系数，取值范围为[0,1]。其中： 0：广播模式，即音量和音色均不随距离衰减，无论距离远近，本地用户听到的音量和音色都无变化。 (0,0.5)：弱衰减模式，即音量和音色在传播过程中仅发生微弱衰减，跟真实环境相比，声音可以传播得更远。 0.5：（默认）模拟音量在真实环境下的衰减，效果等同于不设置 attenuation 参数。 (0.5,1]：强衰减模式，即音量和音色在传播过程中发生迅速衰减。
forceSet	是否强制设定媒体播放器的声音衰减效果： true：强制使用 attenuation 设置媒体播放器的声音衰减效果，此时 SpatialAudioZone 中的 audioAttenuation 中设置的隔声区域衰减系数对媒体播放器不生效。 false：不强制使用 attenuation 设置媒体播放器的声音衰减效果，分为以下两种情况。 如果音源和听声者分属于隔声区域内部和外部，则声音衰减效果由 SpatialAudioZone 中的 audioAttenuation 决定。 如果音源和听声者在同一个隔声区域内或同在隔声区域外，则声音衰减效果由该方法中的 attenuation 决定。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setRemoteAudioAttenuation

设置指定用户的声音衰减效果。

C++

virtual int setRemoteAudioAttenuation(uid_t uid, double attenuation, bool forceSet) = 0;

自从

v4.0.1

参数

参数名	描述
uid	用户 ID。需与用户加入频道时填写的用户 ID 一致。
attenuation	针对该用户的声音衰减系数，取值范围为[0,1]。其中： 0：广播模式，即音量和音色均不随距离衰减，无论距离远近，本地用户听到的音量和音色都无变化。 (0,0.5)：弱衰减模式，即音量和音色在传播过程中仅发生微弱衰减，跟真实环境相比，声音可以传播得更远。 0.5：（默认）模拟音量在真实环境下的衰减，效果等同于不设置 attenuation 参数。 (0.5,1]：强衰减模式，即音量和音色在传播过程中发生迅速衰减。
forceSet	是否强制设定该用户的声音衰减效果： true：强制使用 attenuation 设置该用户的声音衰减效果，此时 SpatialAudioZone 中的 audioAttenuation 中设置的隔声区域衰减系数对该用户不生效。 false：不强制使用 attenuation 设置用户的声音衰减效果，分为以下两种情况。 如果音源和听声者分属于隔声区域内部和外部，则声音衰减效果由 SpatialAudioZone 中的 audioAttenuation 决定。 如果音源和听声者在同一个隔声区域内或同在隔声区域外，则声音衰减效果由该方法中的 attenuation 决定。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

setRemoteUserSpatialAudioParams

设置远端用户的空间音效参数。

C++

virtual int setRemoteUserSpatialAudioParams(uid_t uid, const agora::SpatialAudioParams& params) = 0;

该方法需要在 enableSpatialAudio 后调用。成功设置远端用户的空间音效参数后，本地用户听远端用户会有空间感。

参数

参数名	描述
uid	用户 ID。需与用户加入频道时填写的用户 ID 一致。
params	空间音效参数。详见 SpatialAudioParams。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

setZones

设置隔声区域。

C++

virtual int setZones(const SpatialAudioZone *zones, unsigned int zoneCount) = 0;

自从

v4.0.1

在虚拟互动场景下，你可以通过该方法设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。

• 当音源跟听声者分属于隔声区域内部和外部时，声音的衰减效果由 SpatialAudioZone 中的声音衰减系数决定。

• 如果用户或媒体播放器同在一个隔声区域内，则不受 SpatialAudioZone 的影响，声音的衰减效果由 setPlayerAttenuation 或 setRemoteAudioAttenuation 中的 attenuation 参数决定。如果不调用 setPlayerAttenuation 或 setRemoteAudioAttenuation，则 SDK 默认声音的衰减系数为 0.5，即模拟声音在真实环境下的衰减。

• 如果音源跟接收者分别属于两个隔声区域，则接收者无法听到音源。

注： 如果多次调用该方法，以最后一次设置的隔声区域为准。

参数

参数名	描述
zones	隔声区域的设置。详见 SpatialAudioZone。 警告： 在 Windows 平台上，需确保 zones 数组中的成员个数与 zoneCount 的值相等，否则会导致崩溃。
zoneCount	隔声区域的数量。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

updatePlayerPositionInfo

更新媒体播放器的空间位置。

C++

virtual int updatePlayerPositionInfo(int playerId, const RemoteVoicePositionInfo& positionInfo) = 0;

成功更新后，本地用户可以听到媒体播放器空间位置的变化。

参数

参数名	描述
playerId	媒体播放器 ID。可通过 getMediaPlayerId 获取。
positionInfo	媒体播放器的空间位置信息。详见 RemoteVoicePositionInfo。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IBaseSpatialAudioEngine

enableSpatialAudio

开启或关闭空间音效。

C++

virtual int enableSpatialAudio(bool enabled) = 0;

开启空间音效后，你可以调用 setRemoteUserSpatialAudioParams 设置远端用户的空间音效参数。

注：

• 该方法在加入频道前后均可调用。

• 该方法依赖于空间音效动态库 libagora_spatial_audio_extension.dll，如果删除该动态库会导致无法正常开启该功能。

参数

参数名	描述
enabled	是否开启空间音效： true: 开启空间音效。 false: 关闭空间音效。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine