空间音效
Initialize
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int Initialize(FLocalSpatialAudioConfig& config);
详情
- 你需要在 QueryInterface
(AGORA_IID_LOCAL_SPATIAL_AUDIO)
后调用该方法。 - 在调用 ILocalSpatialAudioEngine 类的其他方法前,你需要先调用该方法初始化 ILocalSpatialAudioEngine。
- SDK 只支持每个 App 创建一个 ILocalSpatialAudioEngine 实例。
参数
- config
- ILocalSpatialAudioEngine 的配置。详见 FLocalSpatialAudioConfig。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
MuteRemoteAudioStream
取消或恢复订阅指定远端用户的音频流。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int MuteRemoteAudioStream(int64 uid, bool mute);
详情
- 该方法需要在 JoinChannel 后调用。
- 在使用空间音效时,如需设置是否订阅指定用户的音频流,建议调用该方法替代 IRtcEngine 的 MuteRemoteAudioStream 方法。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- mute
- 是否取消订阅指定远端用户的音频流。
true
: 取消订阅指定用户的音频流。false
:(默认)订阅指定用户的音频流,SDK 根据本地用户和远端用户的距离决定是否订阅。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
MuteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int MuteAllRemoteAudioStreams(bool mute);
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在 JoinChannel 后调用。
- 在使用空间音效时,如需设置是否订阅所有远端用户的音频流,建议调用该方法替代 IRtcEngine 的 MuteAllRemoteAudioStreams 方法。
- 在调用该方法后,你需要调用 UpdateSelfPosition 和 UpdateRemotePosition 更新本地用户和远端用户的空间位置,否则该方法中的设置不会生效。
参数
- mute
- 是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
: 订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
MuteLocalAudioStream
取消或恢复发布本地音频流。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int MuteLocalAudioStream(bool mute);
详情
- 该方法不影响音频采集状态,因为没有禁用音频采集设备。
- 该方法需要在 JoinChannel 后调用。
- 在使用空间音效时,如需设置是否发布本地音频流,建议调用该方法替代 IRtcEngine 的 MuteLocalAudioStream 方法。
- 成功调用该方法后,远端会触发 FOnUserMuteAudio 回调和 FOnRemoteAudioStateChanged 回调。
参数
- mute
- 是否取消发布本地音频流。
true
: 取消发布本地音频流。false
: 发布本地音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
UpdateRemotePosition
更新远端用户的空间位置信息。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int UpdateRemotePosition(int64 uid, FRemoteVoicePositionInfo& posInfo);
详情
成功调用该方法后,SDK 会根据本地和远端用户的相对位置计算空间音效参数。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- posInfo
- 远端用户的空间位置信息。详见 FRemoteVoicePositionInfo。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
UpdateSelfPosition
更新本地用户的空间位置。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int UpdateSelfPosition(FVector position, FVector axisForward, FVector axisRight, FVector axisUp);
详情
- 在 ILocalSpatialAudioEngine 类下,该方法需要和 UpdateRemotePosition 搭配使用。SDK 会根据该方法和 UpdateRemotePosition 设置的参数计算本地和远端用户之间的相对位置,从而计算用户的空间音效参数。
参数
- position
- 在世界坐标系中的坐标。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisForward
- 在世界坐标系前轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisRight
- 在世界坐标系右轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisUp
- 在世界坐标系上轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
ClearRemotePositions
Release
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
void Release();
详情
该方法释放 IBaseSpatialAudioEngine 下的所有资源。当用户不需要使用空间音效时,你可以调用该方法将资源释放出来用于其他操作。
RemoveRemotePosition
SetAudioRecvRange
SetDistanceUnit
设置游戏引擎单位距离的长度(米)。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int SetDistanceUnit(float unit);
详情
游戏引擎里的距离单位是游戏引擎自定义的,而声网空间音效算法的距离单位为米。默认情况下,SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法,将游戏引擎里的单位距离换算为指定的米数。
参数
- unit
- 每单位游戏引擎距离转换后的米数。该参数取值需大于 0.00,默认值为 1.00。例如,将 unit 设为 2.00,表示每单位的游戏引擎距离等于 2 米。
该值越大,当远端用户远离本地用户时,本地用户听到的声音衰减速度越快。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetHeadphoneEQParameters
设置耳机均衡器的低频和高频参数。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int SetHeadphoneEQParameters(int lowGain, int highGain);
详情
在空间音效场景下,如果在调用 SetHeadphoneEQPreset 方法使用预设的耳机均衡效果后仍未达到预期,你可以通过调用该方法进一步调节耳机均衡效果。
参数
- lowGain
- 耳机均衡器的低频参数。取值范围为 [-10,10],取值越大,声音越低沉。
- highGain
- 耳机均衡器的高频参数。取值范围为 [-10,10],取值越大,声音越尖锐。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败
- -1:一般性的错误(未明确归类)。
SetHeadphoneEQPreset
设置预设的耳机均衡效果。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int SetHeadphoneEQPreset(FENUMWRAP_HEADPHONE_EQUALIZER_PRESET preset);
详情
该方法主要应用于空间音效场景下,你可以选择预设的耳机均衡器收听音频,以达到预期的音频体验。
参数
- preset
- 预设的耳机均衡效果。详见 EENUMCUSTOM_HEADPHONE_EQUALIZER_PRESET。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败
- -1:一般性的错误(未明确归类)。
SetMaxAudioRecvCount
SetPlayerAttenuation
设置媒体播放器的声音衰减属性。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int SetPlayerAttenuation(int playerId, bool forceSet, FString attenuation = "0.0");
参数
- playerId
- 媒体播放器 ID。可通过 GetMediaPlayerId 获取。
- attenuation
- 媒体播放器的声音衰减系数,取值范围为[0,1]。其中:
- 0:广播模式,即音量和音色均不随距离衰减,无论距离远近,本地用户听到的音量和音色都无变化。
- (0,0.5):弱衰减模式,即音量和音色在传播过程中仅发生微弱衰减,跟真实环境相比,声音可以传播得更远。
- 0.5:(默认)模拟音量在真实环境下的衰减,效果等同于不设置 attenuation 参数。
- (0.5,1]:强衰减模式,即音量和音色在传播过程中发生迅速衰减。
- forceSet
- 是否强制设定媒体播放器的声音衰减效果:
true
:强制使用 attenuation 设置媒体播放器的声音衰减效果,此时 FSpatialAudioZone 中的 audioAttenuation 中设置的隔声区域衰减系数对媒体播放器不生效。false
:不强制使用 attenuation 设置媒体播放器的声音衰减效果,分为以下两种情况。- 如果音源和听声者分属于隔声区域内部和外部,则声音衰减效果由 FSpatialAudioZone 中的 audioAttenuation 决定。
- 如果音源和听声者在同一个隔声区域内或同在隔声区域外,则声音衰减效果由该方法中的 attenuation 决定。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetRemoteAudioAttenuation
设置指定用户的声音衰减效果。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int SetRemoteAudioAttenuation(int64 uid, bool forceSet, FString attenuation = "0.0");
详情
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- attenuation
- 针对该用户的声音衰减系数,取值范围为[0,1]。其中:
- 0:广播模式,即音量和音色均不随距离衰减,无论距离远近,本地用户听到的音量和音色都无变化。
- (0,0.5):弱衰减模式,即音量和音色在传播过程中仅发生微弱衰减,跟真实环境相比,声音可以传播得更远。
- 0.5:(默认)模拟音量在真实环境下的衰减,效果等同于不设置 attenuation 参数。
- (0.5,1]:强衰减模式,即音量和音色在传播过程中发生迅速衰减。
- forceSet
- 是否强制设定该用户的声音衰减效果:
true
:强制使用 attenuation 设置该用户的声音衰减效果,此时 FSpatialAudioZone 中的 audioAttenuation 中设置的隔声区域衰减系数对该用户不生效。false
:不强制使用 attenuation 设置用户的声音衰减效果,分为以下两种情况。- 如果音源和听声者分属于隔声区域内部和外部,则声音衰减效果由 FSpatialAudioZone 中的 audioAttenuation 决定。
- 如果音源和听声者在同一个隔声区域内或同在隔声区域外,则声音衰减效果由该方法中的 attenuation 决定。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetRemoteUserSpatialAudioParams
设置远端用户的空间音效参数。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int SetRemoteUserSpatialAudioParams(int64 uid, const FSpatialAudioParams& params);
详情
该方法需要在 EnableSpatialAudio 后调用。成功设置远端用户的空间音效参数后,本地用户听远端用户会有空间感。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- params
- 空间音效参数。详见 FSpatialAudioParams。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
SetZones
设置隔声区域。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int SetZones(TArray<FSpatialAudioZone> zones);
详情
在虚拟互动场景下,你可以通过该方法设置隔声区域和声音衰减系数。当音源(可以为用户或媒体播放器)跟听声者分属于隔声区域内部和外部时,会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。
- 当音源跟听声者分属于隔声区域内部和外部时,声音的衰减效果由 FSpatialAudioZone 中的声音衰减系数决定。
- 如果用户或媒体播放器同在一个隔声区域内,则不受 FSpatialAudioZone 的影响,声音的衰减效果由 SetPlayerAttenuation 或 SetRemoteAudioAttenuation 中的 attenuation 参数决定。如果不调用 SetPlayerAttenuation 或 SetRemoteAudioAttenuation,则 SDK 默认声音的衰减系数为 0.5,即模拟声音在真实环境下的衰减。
- 如果音源跟接收者分别属于两个隔声区域,则接收者无法听到音源。
参数
- zones
- 隔声区域的设置。详见 FSpatialAudioZone。警告在 Windows 平台上,需确保 zones 数组中的成员个数与 zoneCount 的值相等,否则会导致崩溃。
- zoneCount
- 隔声区域的数量。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
UpdatePlayerPositionInfo
更新媒体播放器的空间位置。
UFUNCTION(BlueprintCallable, Category = "Agora|ILocalSpatialAudioEngine")
int UpdatePlayerPositionInfo(int playerId, const FRemoteVoicePositionInfo& positionInfo);
详情
成功更新后,本地用户可以听到媒体播放器空间位置的变化。
参数
- playerId
- 媒体播放器 ID。可通过 GetMediaPlayerId 获取。
- positionInfo
- 媒体播放器的空间位置信息。详见 FRemoteVoicePositionInfo。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
EnableSpatialAudio
开启或关闭空间音效。
UFUNCTION(BlueprintCallable, Category = "Agora|RtcEngineProxy")
int EnableSpatialAudio(bool enabled);
详情
开启空间音效后,你可以调用 SetRemoteUserSpatialAudioParams 设置远端用户的空间音效参数。
- 该方法在加入频道前后均可调用。
- 该方法依赖于空间音效动态库
libagora_spatial_audio_extension.dll
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启空间音效:
true
: 开启空间音效。false
: 关闭空间音效。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。