空间音频
- C#
更新时间不可用
GetLocalSpatialAudioEngine
获取 ILocalSpatialAudioEngine 对象。
public abstract ILocalSpatialAudioEngine GetLocalSpatialAudioEngine();详情
注： 该方法需要在初始化 IRtcEngine 对象后调用。
返回值
一个 ILocalSpatialAudioEngine 对象。
Initialize
public abstract int Initialize();详情
注：
- 在调用 ILocalSpatialAudioEngine 类的其他方法前，你需要先调用该方法初始化 ILocalSpatialAudioEngine。
- SDK 只支持每个 App 创建一个 ILocalSpatialAudioEngine 实例。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
MuteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
public abstract int MuteAllRemoteAudioStreams(bool mute);详情
成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流，包括在调用该方法后加入频道的用户的音频流。
注：
- 该方法需要在 JoinChannel [1/2] 或 JoinChannel [2/2] 后调用。
- 在使用空间音频时，如需设置是否订阅所有远端用户的音频流，建议调用该方法替代 IRtcEngine 的 MuteAllRemoteAudioStreams 方法。
- 在调用该方法后，你需要调用 UpdateSelfPosition 和 UpdateRemotePosition 更新本地用户和远端用户的空间位置，否则该方法中的设置不会生效。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
MuteLocalAudioStream
取消或恢复发布本地音频流。
public abstract int MuteLocalAudioStream(bool mute);详情
注：
- 该方法不影响音频采集状态，因为没有禁用音频采集设备。
- 该方法需要在 JoinChannel [1/2] 或 JoinChannel [2/2] 后调用。
- 在使用空间音频时，如需设置是否发布本地音频流，建议调用该方法替代 IRtcEngine 的 MuteLocalAudioStream 方法。
- 成功调用该方法后，远端会触发 OnUserMuteAudio 回调和 OnRemoteAudioStateChanged 回调。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
MuteRemoteAudioStream
取消或恢复订阅指定远端用户的音频流。
public abstract int MuteRemoteAudioStream(uint uid, bool mute);详情
注：
- 该方法需要在 JoinChannel [1/2] 或 JoinChannel [2/2] 后调用。
- 在使用空间音频时，如需设置是否订阅指定用户的音频流，建议调用该方法替代 IRtcEngine 的 MuteRemoteAudioStream 方法。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
UpdateRemotePosition
更新远端用户的空间位置信息。
public abstract int UpdateRemotePosition(uint uid, RemoteVoicePositionInfo posInfo);详情
成功调用该方法后，SDK 会根据本地和远端用户的相对位置计算空间音频参数。
注： 该方法需要在 JoinChannel [1/2] 或 JoinChannel [2/2] 后调用。
参数
| 参数名 | 描述 |
|---|---|
uid | |
posInfo | 远端用户的空间位置信息。详见 RemoteVoicePositionInfo。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
UpdateSelfPosition
更新本地用户的空间位置。
public abstract int UpdateSelfPosition(float[] position, float[] axisForward, float[] axisRight, float[] axisUp);详情
- 在 ILocalSpatialAudioEngine 类下，该方法需要和 UpdateRemotePosition 搭配使用。SDK 会根据该方法和 UpdateRemotePosition 设置的参数计算本地和远端用户之间的相对位置，从而计算用户的空间音频参数。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
ClearRemotePositions
删除所有远端用户的空间位置信息。
public abstract int ClearRemotePositions();详情
成功调用该方法后，本地用户将听不到所有远端用户。
离开频道后，为避免计算资源的浪费，你也可以调用该方法删除所有远端用户的空间位置信息。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
RemoveRemotePosition
删除指定远端用户的空间位置信息。
public abstract int RemoveRemotePosition(uint uid);详情
成功调用该方法后，本地用户将听不到指定的远端用户。
离开频道后，为避免计算资源的浪费，你需要调用该方法删除指定远端用户的空间位置信息。否则，该用户的空间位置信息会一直被保存。当远端用户人数大于 SetMaxAudioRecvCount 中设定的可接收音频流数时，会按照相对距离依次自动取消订阅距离最远的用户的音频流。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
Dispose
public abstract void Dispose();详情
该方法释放 ILocalSpatialAudioEngine 下的所有资源。当用户不需要使用空间音频时，你可以调用该方法将资源释放出来用于其他操作。
调用该方法后，你将无法再使用 ILocalSpatialAudioEngine 下的任何 API。如需再次使用空间音频，你需要等 Dispose 执行结束后再调用 Initialize 创建一个新的 ILocalSpatialAudioEngine。
注： 该方法需要在 IRtcEngine 的 Dispose 方法前调用。
SetAudioRecvRange
设置本地用户的音频接收范围。
public abstract int SetAudioRecvRange(float range);详情
设置成功后，用户只能听见设置范围内或属于同一队伍的远端用户。你可以随时调用该方法更新音频的接收范围。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetDistanceUnit
设置游戏引擎单位距离的长度（米）。
public abstract int SetDistanceUnit(float unit);详情
游戏引擎里的距离单位是游戏引擎自定义的，而声网空间音频算法的距离单位为米。默认情况下，SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法，将游戏引擎里的单位距离换算为指定的米数。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetHeadphoneEQParameters
设置耳机均衡器的低频和高频参数。
public abstract int SetHeadphoneEQParameters(int lowGain, int highGain);详情
在空间音频场景下，如果在调用 SetHeadphoneEQPreset 方法使用预设的耳机均衡效果后仍未达到预期，你可以通过调用该方法进一步调节耳机均衡效果。
参数
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败
- -1：一般性的错误（未明确归类）。
所属接口类
SetHeadphoneEQPreset
设置预设的耳机均衡效果。
public abstract int SetHeadphoneEQPreset(HEADPHONE_EQUALIZER_PRESET preset);详情
该方法主要应用于空间音频场景下，你可以选择预设的耳机均衡器收听音频，以达到预期的音频体验。
注： 如果你使用的耳机已经具备良好的均衡效果，调用该方法时可能不会获得明显的体验提升效果，甚至可能导致体验下降。
参数
| 参数名 | 描述 |
|---|---|
preset | 预设的耳机均衡效果。详见 HEADPHONE_EQUALIZER_PRESET。 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败
- -1：一般性的错误（未明确归类）。
所属接口类
SetMaxAudioRecvCount
设置音频接收范围内最多可接收的音频流数。
public abstract int SetMaxAudioRecvCount(int maxCount);详情
如果在音频接收范围内可接收的音频流数超过设置的值，则本地用户会接收音源距离较近的 maxCount 路音频。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetPlayerAttenuation
设置媒体播放器的声音衰减属性。
public abstract int SetPlayerAttenuation(int playerId, double attenuation, bool forceSet);详情
参数
| 参数名 | 描述 |
|---|---|
playerId | |
attenuation | |
forceSet | 是否强制设定媒体播放器的声音衰减效果：
|
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetRemoteAudioAttenuation
设置指定用户的声音衰减效果。
public abstract int SetRemoteAudioAttenuation(uint uid, double attenuation, bool forceSet);详情
参数
| 参数名 | 描述 |
|---|---|
uid | |
attenuation | |
forceSet | 是否强制设定该用户的声音衰减效果：
|
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetRemoteUserSpatialAudioParams
设置远端用户的空间音频参数。
public abstract int SetRemoteUserSpatialAudioParams(uint uid, SpatialAudioParams param);详情
该方法需要在 EnableSpatialAudio 后调用。成功设置远端用户的空间音频参数后，本地用户听远端用户会有空间感。
参数
| 参数名 | 描述 |
|---|---|
uid | |
param | 空间音频参数。详见 SpatialAudioParams。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
SetSpatialAudioParams
开启或关闭媒体播放器的空间音频。
public abstract int SetSpatialAudioParams(SpatialAudioParams spatial_audio_params);详情
成功设置媒体播放器的空间音频参数后，SDK 会开启媒体播放器的空间音频，即本地用户听媒体资源会有空间感。
如果需关闭媒体播放器的空间音频，你需要将 params 参数设为空。
参数
| 参数名 | 描述 |
|---|---|
spatial_audio_params | 媒体播放器的空间音频参数。详见 SpatialAudioParams。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
SetZones
设置隔声区域。
public abstract int SetZones(SpatialAudioZone[] zones, uint zoneCount);详情
在虚拟互动场景下，你可以通过该方法设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于隔声区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。
- 当音源跟听声者分属于隔声区域内部和外部时，声音的衰减效果由 SpatialAudioZone 中的声音衰减系数决定。
- 如果用户或媒体播放器同在一个隔声区域内，则不受 SpatialAudioZone 的影响，声音的衰减效果由 SetPlayerAttenuation 或 SetRemoteAudioAttenuation 中的 attenuation 参数决定。如果不调用 SetPlayerAttenuation 或 SetRemoteAudioAttenuation，则 SDK 默认声音的衰减系数为 0.5，即模拟声音在真实环境下的衰减。
- 如果音源跟接收者分别属于两个隔声区域，则接收者无法听到音源。
注： 如果多次调用该方法，以最后一次设置的隔声区域为准。
参数
| 参数名 | 描述 |
|---|---|
zones | 隔声区域的设置。详见 SpatialAudioZone。当你将该参数设置为 注意： 在 Windows 平台上，需确保 zones 数组中的成员个数与 zoneCount 的值相等，否则会导致崩溃。 |
zoneCount |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
UpdatePlayerPositionInfo
更新媒体播放器的空间位置。
public abstract int UpdatePlayerPositionInfo(int playerId, RemoteVoicePositionInfo positionInfo);成功更新后，本地用户可以听到媒体播放器空间位置的变化。
调用时机
加入频道前后均可调用。
调用限制
无。
参数
| 参数名 | 描述 |
|---|---|
playerId | |
positionInfo | 媒体播放器的空间位置信息。详见 RemoteVoicePositionInfo。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
EnableSpatialAudio
开启或关闭空间音频。
public abstract int EnableSpatialAudio(bool enabled);详情
开启空间音频后，你可以调用 SetRemoteUserSpatialAudioParams 设置远端用户的空间音频参数。
注：
- 该方法在加入频道前后均可调用。
- 该方法依赖于空间音频动态库
libagora_spatial_audio_extension.dll，如果删除该动态库会导致无法正常开启该功能。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。