空间音频
clearRemotePositions
enableSpatialAudio
启用或关闭空间音效。
C++
virtual int enableSpatialAudio(bool enabled) = 0;
启用空间音效后，你可以调用 setRemoteUserSpatialAudioParams 设置远端用户的空间音效参数。
信息
- 你可以在加入频道前或加入频道后调用此方法。
- 此方法依赖空间音效动态库 libagora_spatial_audio_extension.dll。如果该动态库被删除，该功能将无法正常启用。
参数
- enabled
- 是否启用空间音效：
- true：启用空间音效。
- false：关闭空间音效。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
initialize
C++
virtual int initialize(const LocalSpatialAudioConfig& config) = 0;
在调用 ILocalSpatialAudioEngine 的其他方法前，你必须先调用 queryInterface 获取接口实例，并通过该方法初始化 ILocalSpatialAudioEngine。每个 App 仅支持创建一个 ILocalSpatialAudioEngine 实例。
参数
- config
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
muteAllRemoteAudioStreams
停止或恢复订阅所有远端用户的音频流。
C++
virtual int muteAllRemoteAudioStreams(bool mute) = 0;
调用该方法后，本地用户将停止或恢复订阅所有远端用户的音频流，包括后续加入频道的用户。
信息
- 请在调用
joinChannel方法后调用本方法。 - 使用空间音效时，如需设置是否停止订阅所有远端用户的音频流，声网推荐使用本方法，而非 IRtcEngine 下的同名方法。
- 调用本方法后，需要调用 updateSelfPosition 和 updateRemotePosition 更新本地用户和远端用户的空间位置，否则本方法的设置不会生效。
参数
- mute
- 是否停止订阅所有远端用户的音频流：
- true：停止订阅所有远端用户的音频流。
- false：订阅所有远端用户的音频流。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
muteLocalAudioStream
停止或恢复发布本地音频流。
C++
virtual int muteLocalAudioStream(bool mute) = 0;
信息
该方法不会影响任何正在进行的音频录制，因为它不会禁用音频采集设备。 请在调用
joinChannel 方法之后调用该方法。 使用空间音效时，如果需要设置是否停止发布本地音频流，建议调用该方法，而不是 IRtcEngine 下的同名方法。相关回调
成功调用该方法后，远端会触发 onUserMuteAudio 和 onRemoteAudioStateChanged 回调。
参数
- mute
- 是否停止发布本地音频流：
- true：停止发布本地音频流。
- false：发布本地音频流。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
muteRemoteAudioStream
停止或恢复订阅指定远端用户的音频流。
C++
virtual int muteRemoteAudioStream(uid_t uid, bool mute) = 0;
信息
- 请在调用
joinChannel方法后调用此方法。 - 使用空间音效时，如需设置是否停止订阅指定用户的音频流，声网建议调用此方法，而非 muteRemoteAudioStream 方法。
参数
- uid
- 用户 ID。该值必须与用户加入频道时传入的用户 ID 相同。
- mute
- 是否订阅指定远端用户的音频流：
- true：停止订阅该用户的音频流。
- false：（默认）订阅该用户的音频流。SDK 会根据本地用户与远端用户之间的距离决定是否订阅。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
release
释放 ILocalSpatialAudioEngine 的所有资源。
C++
virtual void release() = 0;
调用该方法可释放 ILocalSpatialAudioEngine 下的所有资源。调用该方法后，将无法再使用 ILocalSpatialAudioEngine 下的任何 API。
信息
请在调用 release 方法之前调用该方法。
removeRemotePosition
移除指定远端用户的空间位置信息。
C++
virtual int removeRemotePosition(uid_t uid) = 0;
调用该方法后，本地用户将无法再听到指定远端用户的声音。离开频道后，为避免浪费计算资源，建议调用该方法移除该远端用户的空间位置信息，否则该信息将持续保留。当远端用户数量超过通过 setMaxAudioRecvCount 设置的最大可接收音频流数量时，系统会根据相对距离自动取消订阅距离最远用户的音频流。
参数
- uid
uid。该值必须与用户加入频道时传入的用户 ID 相同。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setAudioRecvRange
setDistanceUnit
设置游戏引擎中每个单位距离对应的米数。
C++
virtual int setDistanceUnit(float unit) = 0;
在声网的空间音效算法中，距离以米为单位进行测量，而游戏引擎中的距离单位是自定义的。SDK 默认将游戏引擎中的每个单位距离转换为 1 米。你可以调用 setDistanceUnit 方法，将游戏引擎中的单位距离转换为指定的米数。
参数
- unit
- 游戏引擎中每个单位距离对应的米数。该参数的值必须大于 0.00，默认值为 1.00。例如，将
unit设置为 2.00 表示游戏引擎中每个单位距离等于 2 米。值越大，当远端用户远离本地用户时，本地用户听到的声音衰减得越快。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setHeadphoneEQParameters
设置耳机均衡器的低频和高频参数。
C++
virtual int setHeadphoneEQParameters(int lowGain, int highGain) = 0;
在空间音效场景中，如果调用 setHeadphoneEQPreset 后未达到预期的耳机均衡效果，可以通过调用该方法进一步调整。
参数
- lowGain
- 耳机均衡器的低频参数，取值范围为 [-10, 10]。值越大，声音越浑厚。
- highGain
- 耳机均衡器的高频参数，取值范围为 [-10, 10]。值越大，声音越清晰。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -1：发生通用错误（无具体原因）。
setHeadphoneEQPreset
设置预设的耳机均衡效果。
C++
virtual int setHeadphoneEQPreset(HEADPHONE_EQUALIZER_PRESET preset) = 0;
该方法主要用于空间音效场景。你可以选择预设的耳机均衡器来聆听音频，以获得预期的音频体验。
信息
如果你使用的耳机本身已经具有良好的均衡效果，调用该方法可能不会带来显著提升，甚至可能降低体验。
参数
- preset
- 预设的耳机均衡效果，详见 HEADPHONE_EQUALIZER_PRESET。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -1：发生通用错误（无具体原因）。
setMaxAudioRecvCount
setPlayerAttenuation
设置媒体播放器的声音衰减属性。
C++
virtual int setPlayerAttenuation(int playerId, double attenuation, bool forceSet) = 0;
参数
- playerId
- 媒体播放器的 ID。你可以通过调用 getMediaPlayerId 获取设备 ID。
- attenuation
- 远端用户或媒体播放器的声音衰减系数，取值范围为 [0, 1]。具体取值说明如下：
- 0：广播模式，音量和音色不会随距离衰减，本地用户听到的音量和音色不会随距离变化。
- (0, 0.5)：弱衰减模式，音量和音色在传播过程中仅有轻微衰减，声音传播距离比真实环境更远。
- 0.5：（默认）模拟真实环境中的音量衰减效果，等效于未设置
speaker_attenuation参数。 - (0.5, 1]：强衰减模式，音量和音色在传播过程中快速衰减。
- forceSet
- 是否强制设置媒体播放器的声音衰减效果：
- true：强制使用
attenuation设置媒体播放器的衰减效果，此时 SpatialAudioZone 中通过audioAttenuation设置的隔音区衰减系数对媒体播放器无效。 - false：不强制使用
attenuation设置媒体播放器的声音衰减效果，具体如下：- 如果声源和收听者分别位于隔音区内外，声音衰减效果由 SpatialAudioZone 中的
audioAttenuation决定。 - 如果声源和收听者位于同一隔音区内或同一隔音区外，声音衰减效果由本方法中的
attenuation决定。
- 如果声源和收听者分别位于隔音区内外，声音衰减效果由 SpatialAudioZone 中的
- true：强制使用
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setRemoteAudioAttenuation
设置指定用户的声音衰减效果。
C++
virtual int setRemoteAudioAttenuation(uid_t uid, double attenuation, bool forceSet) = 0;
参数
- uid
- 用户 ID。该参数必须与用户加入频道时传入的用户 ID 相同。
- attenuation
- 用户的声音衰减系数，取值范围为 [0,1]。各取值含义如下：
- 0：广播模式，音量和音色不会随距离衰减，本地用户听到的音量和音色不会因距离变化而变化。
- (0, 0.5)：弱衰减模式，音量和音色在传播过程中仅有轻微衰减，声音传播距离比真实环境更远。
- 0.5：（默认）模拟真实环境中的音量衰减效果，等效于未设置
speaker_attenuation参数。 - (0.5, 1]：强衰减模式，音量和音色在传播过程中迅速衰减。
- forceSet
- 是否强制设置用户的声音衰减效果：
- true：强制使用
attenuation设置用户的声音衰减效果，此时 SpatialAudioZone 中audioAttenuation设置的隔音区衰减系数对该用户无效。 - false：不强制使用
attenuation设置用户的声音衰减效果，具体如下：- 若声源和接收者分别位于隔音区内外，衰减效果由 SpatialAudioZone 中的
audioAttenuation决定； - 若声源和接收者位于同一隔音区或同在隔音区外，衰减效果由本方法中的
attenuation决定。
- 若声源和接收者分别位于隔音区内外，衰减效果由 SpatialAudioZone 中的
- true：强制使用
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setRemoteUserSpatialAudioParams
设置远端用户的空间音效参数。
C++
virtual int setRemoteUserSpatialAudioParams(uid_t uid, const agora::SpatialAudioParams& params) = 0;
调用 enableSpatialAudio 后调用该方法。设置成功后，你可以听到具有空间感的远端用户的声音。
参数
- uid
- 远端用户 ID。该参数必须与你调用加入频道方法时传入的用户 ID 相同。
- params
- 空间音效参数。详见 SpatialAudioParams。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setSpatialAudioParams
启用或关闭媒体播放器的空间音效。
C++
virtual int setSpatialAudioParams(const SpatialAudioParams& params) = 0;
调用该方法成功设置媒体播放器的空间音效参数后，SDK 会为媒体播放器启用空间音效，本地用户可以听到具有空间感的媒体资源。若需关闭空间音效，请将 params 设置为 NULL。
参数
- params
- 媒体播放器的空间音效参数。详见 SpatialAudioParams。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setZones
设置隔音区域。
C++
virtual int setZones(const SpatialAudioZone *zones, unsigned int zoneCount) = 0;
在虚拟互动场景中，你可以使用该方法设置隔音区域及其声音衰减系数。当声源（用户或媒体播放器）和接收者分别位于隔音区域的内外时，可以模拟现实中声音被建筑物阻隔时的衰减效果：
- 当声源和接收者分别位于隔音区域的内外时，声音的衰减效果由 SpatialAudioZone 中的衰减系数决定。
- 当用户或媒体播放器处于同一个隔音区域内时，不受 SpatialAudioZone 的影响，声音衰减效果由 setPlayerAttenuation 或 setRemoteAudioAttenuation 中的
attenuation参数决定。若未调用上述方法，SDK 默认使用 0.5 的声音衰减系数。 - 当声源和接收者分别位于两个不同的隔音区域中，接收者将无法听到声源。
信息
如果多次调用该方法，以最后一次设置的隔音区域为准。
参数
- zones
- 隔音区域设置。设置为 NULL 表示清除所有隔音区域。详见 SpatialAudioZone。信息在 Windows 平台上，必须确保
zones数组中的成员数量等于zoneCount的值，否则可能导致崩溃。 - zoneCount
- 隔音区域的数量。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
updatePlayerPositionInfo
更新媒体播放器的空间位置。
C++
virtual int updatePlayerPositionInfo(int playerId, const RemoteVoicePositionInfo& positionInfo) = 0;
调用该方法后，本地用户可以听到媒体播放器空间位置的变化。
调用时机
该方法可以在加入频道前或加入频道后调用。
参数
- playerId
- 媒体播放器的 ID。你可以通过调用 getMediaPlayerId 获取该 ID。
- positionInfo
- 媒体播放器的空间位置信息，详见 RemoteVoicePositionInfo。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
updateRemotePosition
更新指定远端用户的空间位置。
C++
virtual int updateRemotePosition(uid_t uid, const RemoteVoicePositionInfo &posInfo) = 0;
调用时机
请在调用 joinChannel 方法后调用该方法。
参数
- uid
- 用户 ID。该值必须与用户加入频道时传入的用户 ID 相同。
- posInfo
- 远端用户的空间位置。详见 RemoteVoicePositionInfo。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
updateSelfPosition
更新本地用户的空间位置。
C++
virtual int updateSelfPosition(const float position[3], const float axisForward[3], const float axisRight[3], const float axisUp[3]) = 0;
该方法属于 ILocalSpatialAudioEngine 类，需要与 updateRemotePosition 搭配使用。SDK 会根据该方法和 updateRemotePosition 中的参数设置，计算本地用户与远端用户之间的相对位置，并据此生成空间音效参数。
参数
- position
- 世界坐标系中的位置坐标。该参数为长度为 3 的数组，三个值依次表示前、右、上的坐标。
- axisForward
- 坐标系中 x 轴的单位向量。该参数为长度为 3 的数组，三个值依次表示前、右、上的坐标。
- axisRight
- 坐标系中 y 轴的单位向量。该参数为长度为 3 的数组，三个值依次表示前、右、上的坐标。
- axisUp
- 坐标系中 z 轴的单位向量。该参数为长度为 3 的数组，三个值依次表示前、右、上的坐标。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。