音效处理
介绍跟音效处理相关的方法和回调。
clearRemotePositions
删除所有远端用户的空间位置信息。
public abstract int clearRemotePositions();
详情
成功调用该方法后,本地用户将听不到所有远端用户。
离开频道后,为避免计算资源的浪费,你也可以调用该方法删除所有远端用户的空间位置信息。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
create
public static synchronized ILocalSpatialAudioEngine create() { if (mInstance == null) { mInstance = new LocalSpatialAudioImpl(); } return mInstance; }
详情
该方法需要在 initialize 前调用。
返回值
enableSoundPositionIndication
开启/关闭远端用户的语音立体声。
public abstract int enableSoundPositionIndication(boolean enabled);
详情
如果想调用 setRemoteVoicePosition 实现听声辨位的功能,请确保在加入频道前调用该方法开启远端用户的语音立体声。
参数
- enabled
- 是否开启远端用户语音立体声:
true
: 开启语音立体声。false
: 关闭语音立体声。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableSpatialAudio
开启或关闭空间音效。
public abstract int enableSpatialAudio(boolean enabled);
详情
开启空间音效后,你可以调用 setRemoteUserSpatialAudioParams 设置远端用户的空间音效参数。
- 该方法在加入频道前后均可调用。
- 该方法依赖于空间音效动态库
libagora_spatial_audio_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启空间音效:
true
: 开启空间音效。false
: 关闭空间音效。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getAudioEffectManager
获取 IAudioEffectManager 类,以管理音效文件。
public abstract IAudioEffectManager getAudioEffectManager();
返回值
IAudioEffectManager
getEffectCurrentPosition
获取指定音效文件的播放进度。
public int getEffectCurrentPosition(int soundId);
详情
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 方法调用成功,返回指定音效文件的播放进度(毫秒)。
- < 0:方法调用失败。
getEffectDuration
获取指定音效文件总时长。
public abstract int getEffectDuration(String filePath);
详情
参数
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
/assets/
开头的路径。通过绝对路径访问本地文件可能会遇到权限问题,建议使用 URI 地址访问本地文件。例如content://com.android.providers.media.documents/document/audio%3A14441
。
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
返回值
- 方法调用成功,返回指定音效文件时长(毫秒)。
- < 0:方法调用失败。
initialize
public abstract int initialize(LocalSpatialAudioConfig config);
详情
- 你需要在 create 后调用该方法。
- 在调用 ILocalSpatialAudioEngine 类的其他方法前,你需要先调用该方法初始化 ILocalSpatialAudioEngine。
- SDK 只支持每个 app 创建一个 ILocalSpatialAudioEngine 实例。
参数
- config
- ILocalSpatialAudioEngine 的配置。详见 LocalSpatialAudioConfig。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
destroy
public static synchronized void destroy() { if (mInstance == null) return; mInstance.release(); mInstance = null; }
详情
该方法释放 ILocalSpatialAudioEngine 下的所有资源。当用户不需要使用空间音效时,你可以调用该方法将资源释放出来用于其他操作。
removeRemotePosition
删除指定远端用户的空间位置信息。
public abstract int removeRemotePosition(int uid);
详情
成功调用该方法后,本地用户将听不到指定的远端用户。
离开频道后,为避免计算资源的浪费,你也可以调用该方法删除指定远端用户的空间位置信息。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioEffectParameters
设置 SDK 预设人声音效的参数。
public abstract int setAudioEffectParameters(int preset, int param1, int param2);
详情
- 3D 人声音效:设置 3D 人声音效的环绕周期。
- 电音音效:设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效,建议你将基础调式和主音音高配置选项与应用的 UI 元素绑定。
设置后,频道内所有用户都能听到该效果。
- 该方法在加入频道前后都能调用。
- 为获取更好的人声效果,建议你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,不建议调用该方法处理含音乐的音频数据。
- 调用 setAudioEffectParameters 后,不建议调用以下方法,否则 setAudioEffectParameters 设置的效果会被覆盖:
参数
- preset
- SDK 预设的音效,支持以下设置:
- ROOM_ACOUSTICS_3D_VOICE,3D 人声音效。
- 你需要在使用该枚举前将 setAudioProfile [1/2] 的 profile 参数设置 为 MUSIC_STANDARD_STEREO(3) 或 MUSIC_HIGH_QUALITY_STEREO(5),否则该枚举设置无效。
- 启用 3D 人声后,用户需要使用支持双声道的音频播放设备才能听到预期效果。
- PITCH_CORRECTION,电音音效。为获取更好的人声效果,建议你在使用该枚举前将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5)。
- ROOM_ACOUSTICS_3D_VOICE,3D 人声音效。
- param1
-
- 如果 preset 设为 ROOM_ACOUSTICS_3D_VOICE ,则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60],单位为秒。默认值为 10,表示人声会 10 秒环绕 360 度。
- 如果 preset 设为 PITCH_CORRECTION,则 param1 表示电音音效的基础调式:
1
: (默认)自然大调。2
: 自然小调。3
: 和风小调。
- param2
-
- 如果 preset 设为 ROOM_ACOUSTICS_3D_VOICE,你需要将 param2 设置为
0
。 - 如果 preset 设为 PITCH_CORRECTION,则 param2 表示电音音效的主音音高:
1
: A2
: A#3
: B4
: (Default) C5
: C#6
: D7
: D#8
: E9
: F10
: F#11
: G12
: G#
- 如果 preset 设为 ROOM_ACOUSTICS_3D_VOICE,你需要将 param2 设置为
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioEffectPreset
设置 SDK 预设的人声音效。
public abstract int setAudioEffectPreset(int preset);
详情
调用该方法可以为本地发流用户设置 SDK 预设的人声音效,且不会改变原声的性别特征。设置音效后,频道内所有用户都能听到该效果。
为获取更好的人声效果,建议你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,不建议调用该方法处理含音乐的音频数据。
- 如果调用 setAudioEffectPreset 并设置除 ROOM_ACOUSTICS_3D_VOICE 或 PITCH_CORRECTION 外的枚举,请勿再调用 setAudioEffectParameters,否则 setAudioEffectPreset 设置的效果会被覆盖。
- 调用 setAudioEffectPreset 后,不建议调用以下方法,否则 setAudioEffectPreset 设置的效果会被覆盖:
- 该方法依赖于美声动态库
libagora_audio_beauty_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- preset
- 预设的音效选项。
- AUDIO_EFFECT_OFF: 原声,即关闭人声音效。
- ROOM_ACOUSTICS_KTV: KTV。
- ROOM_ACOUSTICS_VOCAL_CONCERT: 演唱会。
- ROOM_ACOUSTICS_STUDIO: 录音棚。
- ROOM_ACOUSTICS_PHONOGRAPH: 留声机。
- ROOM_ACOUSTICS_VIRTUAL_STEREO: 虚拟立体声,即 SDK 将单声道的音频渲染出双声道的音效。使用该预设音效前,你需要将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY 或 MUSIC_HIGH_QUALITY_STEREO,否则该预设音效的设置无效。
- ROOM_ACOUSTICS_SPACIAL: 空旷。
- ROOM_ACOUSTICS_ETHEREAL: 空灵。
- ROOM_ACOUSTICS_3D_VOICE: 3D 人声,即 SDK 将音频渲染出在用户周围环绕的效果。环绕周期默认为 10 秒。设置该音效后,你还可以调用 setAudioEffectParameters 修改环绕周期。
- 使用该预设音效前,你需要将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_STANDARD_STEREO 或 MUSIC_HIGH_QUALITY_STEREO,否则该预设音效的设置无效。
- 启用 3D 人声后,用户需要使用支持双声道的音频播放设备才能听到预期效果。
- VOICE_CHANGER_EFFECT_UNCLE: 大叔。建议用于处理男声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_OLDMAN: 老年男性。建议用于处理男声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_BOY: 男孩。建议用于处理男声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_SISTER: 少女。建议用于处理女声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_GIRL: 女孩。建议用于处理女声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_PIGKING: 猪八戒。
- VOICE_CHANGER_EFFECT_HULK: 绿巨人。
- STYLE_TRANSFORMATION_RNB: R&B。使用该预设音效前,你需要将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY 或 MUSIC_HIGH_QUALITY_STEREO,否则该预设音效的设置无效。
- STYLE_TRANSFORMATION_POPULAR: 流行。使用该预设音效前,你需要将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY 或 MUSIC_HIGH_QUALITY_STEREO,否则该预设音效的设置无效。
- PITCH_CORRECTION: 电音,即 SDK 以主音音高为 C 的自然大调为基础修正音频的实际音高。设置该音效后,你还可以调用 setAudioEffectParameters 调整修音的基础调式和主音音高。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEffectPosition
设置指定音效文件的播放位置。
public abstract int setEffectPosition(int soundId, int pos);
详情
成功设置后,本地音效文件会在指定位置开始播放。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- pos
- 音效文件的播放位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setHeadphoneEQParameters
设置耳机均衡器的低频和高频参数。
public abstract int setHeadphoneEQParameters(int lowGain, int highGain);
详情
- 自从
- v4.1.0
在空间音效场景下,如果在调用 setHeadphoneEQPreset 方法使用预设的耳机均衡效果后仍未达到预期,你可以通过调用该方法进一步调节耳机均衡效果。
参数
- lowGain
- 耳机均衡器的低频参数。取值范围为 [-10,10],取值越大,声音越低沉。
- highGain
- 耳机均衡器的高频参数。取值范围为 [-10,10],取值越大,声音越尖锐。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -1:一般性的错误(未明确归类)。
setHeadphoneEQPreset
设置预设的耳机均衡效果。
public abstract int setHeadphoneEQPreset(int preset);
详情
- 自从
- v4.0.1
该方法主要应用于空间音效场景下,你可以选择预设的耳机均衡器收听音频,以达到预期的音频体验。
参数
- preset
- 预设的耳机均衡效果。详见 HEADPHONE_EQUALIZER_PRESET。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -1:一般性的错误(未明确归类)。
setLocalVoiceEqualization
设置本地语音音效均衡。
public abstract int setLocalVoiceEqualization( Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain);
详情
参数
- bandFrequency
- 频谱子带索引。取值范围是 [0,9],分别代表音效的 10 个频带。对应的中心频率为 [31,62,125,250,500,1k,2k,4k,8k,16k] Hz。详见 AUDIO_EQUALIZATION_BAND_FREQUENCY 。
- bandGain
- 每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15],默认值为 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoiceFormant
设置共振峰比率以改变语音的音色。
public abstract int setLocalVoiceFormant(double formantRatio);
详情
- 自从
- v4.2.0
共振峰比率是影响声音音色的一个参数,共振峰比率取值越小声音会更低沉,取值越大声音会更尖锐。
参数
- formantRatio
- 共振峰比率,取值范围为 [-1.0,1.0]。默认值为 0.0,即不改变原声的音色。
注: 声网推荐的取值范围为 [-0.4,0.6] ,超出此范围外音效听感可能不佳。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoicePitch
设置本地语音音调。
public abstract int setLocalVoicePitch(double pitch);
详情
参数
- pitch
- 语音频率。可以 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVoiceReverb
设置本地音效混响。
public abstract int setLocalVoiceReverb(Constants.AUDIO_REVERB_TYPE reverbKey, int value);
详情
SDK 提供一个使用更为简便的方法 setAudioEffectPreset,直接实现流行、R&B、KTV 等预置的混响效果。
参数
- reverbKey
- 混响音效 Key。该方法共有 5 个混响音效 Key,详见 AUDIO_REVERB_TYPE。
- value
- 各混响音效 Key 所对应的值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRemoteUserSpatialAudioParams
设置远端用户的空间音效参数。
public abstract int setRemoteUserSpatialAudioParams(int uid, SpatialAudioParams params);
详情
该方法需要在 enableSpatialAudio 后调用。成功设置远端用户的空间音效参数后,本地用户听远端用户会有空间感。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- params
- 空间音效参数。详见 SpatialAudioParams。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRemoteVoicePosition
设置远端用户声音的 2D 位置,即水平面位置。
public abstract int setRemoteVoicePosition(int uid, double pan, double gain);
详情
设置远端用户声音的 2D 位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
- 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
- 为获得最佳听觉体验,建议使用该方法时使用有线耳机。
- 该方法需要在加入频道后调用。
参数
- uid
- 远端用户的 ID
- pan
- 设置远端用户声音的 2D 位置,取值范围为 [-1.0,1.0]:
- (默认)0.0: 声音出现在正前方。
- -1.0: 声音出现在左边。
- 1.0: 声音出现在右边。
- gain
- 设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceBeautifierParameters
设置预设美声效果的参数。
public abstract int setVoiceBeautifierParameters(int preset, int param1, int param2);
详情
调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后,频道内所有用户都能听到该效果。
为获取更好的人声效果,建议你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3),并将 profile 设为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,不建议调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierParameters,不建议调用以下方法,否则 setVoiceBeautifierParameters 设置的效果会被覆盖:
参数
- preset
- 预设的音效:
SINGING_BEAUTIFIER
: 歌唱美声。
- param1
- 歌声的性别特征:
1
: 男声。2
: 女声。
- param2
- 歌声的混响效果:
1
: 歌声在小房间的混响效果。2
: 歌声在大房间的混响效果。3
: 歌声在大厅的混响效果。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceBeautifierPreset
设置预设的美声效果。
public abstract int setVoiceBeautifierPreset(int preset);
详情
调用该方法可以为本地发流用户设置预设的人声美化效果。设置美声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的美声效果。各美声效果的适用场景可参考设置人声效果。
为获取更好的人声效果,建议你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3),并将 profile 设为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,不建议调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierPreset,不建议调用以下方法,否则 setVoiceBeautifierPreset 设置的效果会被覆盖:
- 该方法依赖于美声动态库
libagora_audio_beauty_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- preset
-
预设的美声效果选项:
- VOICE_BEAUTIFIER_OFF: 原声,即关闭美声效果。
- CHAT_BEAUTIFIER_MAGNETIC: 磁性(男)。
- CHAT_BEAUTIFIER_FRESH: 清新(女)。
- CHAT_BEAUTIFIER_VITALITY: 活力(女)。
- SINGING_BEAUTIFIER: 歌唱美声。
- 如果调用 setVoiceBeautifierPreset(SINGING_BEAUTIFIER),你可以美化男声并添加歌声在小房间的混响效果。请勿用于设置女声,否则音频会失真。
- 如果调用 setVoiceBeautifierParameters(SINGING_BEAUTIFIER, param1, param2),你可以美化男声或女声并添加混响效果。
- TIMBRE_TRANSFORMATION_VIGOROUS: 浑厚。
- TIMBRE_TRANSFORMATION_DEEP: 低沉。
- TIMBRE_TRANSFORMATION_MELLOW: 圆润。
- TIMBRE_TRANSFORMATION_FALSETTO: 假音。
- TIMBRE_TRANSFORMATION_FULL: 饱满。
- TIMBRE_TRANSFORMATION_CLEAR: 清澈。
- TIMBRE_TRANSFORMATION_RESOUNDING: 高亢。
- TIMBRE_TRANSFORMATION_RINGING: 嘹亮。
- ULTRA_HIGH_QUALITY_VOICE: 超高音质,即让音频更清晰、细节更丰富。
- 为达到更好的效果,建议在调用该方法前将 setAudioProfile [2/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5),且 scenario 参数设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 如果用户的音频采集设备可以高度还原音频细节,建议你不要开启超高音质,否则 SDK 会过度还原音频细节,达不到预期效果。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceConversionPreset
设置预设的变声效果。
public abstract int setVoiceConversionPreset(int preset);
详情
调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的变声效果。各变声效果的适用场景可参考《设置人声效果》。
为获取更好的人声效果,建议你在调用该方法前将 setAudioProfile [1/2] 的 profile 设为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5),并将 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,不建议调用该方法处理含音乐的音频数据。
- 调用 setVoiceConversionPreset 后,不建议调用以下方法,否则 setVoiceConversionPreset 设置的效果会被覆盖:
- 该方法依赖于美声动态库
libagora_audio_beauty_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- preset
-
预设的变声效果选项:
- VOICE_CONVERSION_OFF: 原声,即关闭变声效果。
- VOICE_CHANGER_NEUTRAL: 中性。为避免音频失真,请确保仅对女声设置该效果。
- VOICE_CHANGER_SWEET: 甜美。为避免音频失真,请确保仅对女声设置该效果。
- VOICE_CHANGER_SOLID: 稳重。为避免音频失真,请确保仅对男声设置该效果。
- VOICE_CHANGER_BASS: 低沉。为避免音频失真,请确保仅对男声设置该效果。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
getEffectsVolume
获取音效文件的播放音量。
public double getEffectsVolume();
详情
音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 音效文件的音量。
- < 0: 方法调用失败
getVolumeOfEffect
获取指定音效文件的播放音量。
public abstract int getVolumeOfEffect(int soundId);
参数
- soundId
- 音效文件的 ID。
返回值
- ≥ 0: 方法调用成功,返回播放音量。音量范围为 [0,100]。100 为原始音量。
- < 0: 方法调用失败。
pauseAllEffects
暂停所有音效文件播放。
public abstract int pauseAllEffects();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pauseEffect
暂停音效文件播放。
public abstract int pauseEffect(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
playEffect [1/2]
播放指定的本地或在线音效文件。
public abstract int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish);
详情
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。通过绝对路径访问本地文件可能会遇到权限问题,建议使用 URL 地址访问本地文件。例如
content://com.android.providers.media.documents/document/audio%203A14441
。 - loopCount
-
音效循环播放的次数。
- ≥ 0: 循环播放次数。例如,1 表示循环播放 1 次,即总计播放 2 次。
- -1: 无限循环播放。
- pitch
- 音效的音调,取值范围为 [0.5,2.0]。默认值为 1.0,表示原始音调。取值越小,则音调越低。
- pan
-
音效的空间位置。取值范围为 [-1.0,1.0],例如:
- -1.0:音效出现在左边
- 0.0:音效出现在正前方
- 1.0:音效出现在右边
- gain
- 音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0,表示原始音量。取值越小,则音量越低。
- publish
-
是否将音效发布至远端:
true
: 将音效发布至远端。本地用户和远端用户都能听到音效。false
: 不将音效发布至远端。只有本地用户能听到音效。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
playEffect [2/2]
播放指定的本地或在线音效文件。
public int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish, int startPos);
详情
你可以多次调用该方法,传入不同的 soundID 和 filePath,同时播放多个音效文件。为获得最佳用户体验,建议同时播放的音效文件不超过 3 个。音效文件播放结束后,SDK 会触发 onAudioEffectFinished 回调。
该方法支持播放以 content://
开头的 URI 文件。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
content://com.android.providers.media.documents/document/audio%203A14441
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。 - loopCount
-
音效循环播放的次数。
- ≥ 0: 循环播放次数。例如,1 表示循环播放 1 次,即总计播放 2 次。
- -1: 无限循环播放。
- pitch
- 音效的音调,取值范围为 [0.5,2.0]。默认值为 1.0,表示原始音调。取值越小,则音调越低。
- pan
-
音效的空间位置。取值范围为 [-1.0,1.0],例如:
- -1.0:音效出现在左边
- 0.0:音效出现在正前方
- 1.0:音效出现在右边
- gain
- 音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0,表示原始音量。取值越小,则音量越低。
- publish
-
是否将音效发布至远端:
true
: 将音效发布至远端。本地用户和远端用户都能听到音效。false
: 不将音效发布至远端。只有本地用户能听到音效。
- startPos
-
音效文件的播放位置,单位为毫秒。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
preloadEffect
将音效文件加载至内存。
public int preloadEffect(int soundId, String filePath);
详情
为保证通信畅通,请注意控制预加载音效文件的大小,并在 joinChannel [2/2] 前就使用该方法完成音效预加载。
- 该方法不支持在线音频文件。
- 该方法支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
/assets/
开头的路径。通过绝对路径访问本地文件可能会遇到权限问题,建议使用 URI 地址访问本地文件。例如content://com.android.providers.media.documents/document/audio%3A14441
。
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
resumeAllEffects
恢复播放所有音效文件。
public abstract int resumeAllEffects();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
resumeEffect
恢复播放指定音效文件。
public abstract int resumeEffect(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEffectsVolume
设置音效文件的播放音量。
public abstract int setEffectsVolume(double volume);
详情
参数
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVolumeOfEffect
实时调整音效文件的播放音量。
public abstract int setVolumeOfEffect(int soundId, double volume);
参数
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAllEffects
停止播放所有音效文件。
public abstract int stopAllEffects();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopEffect
停止播放指定音效文件。
public abstract int stopEffect(int soundId);
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
unloadEffect
从内存释放某个预加载的音效文件。
public abstract int unloadEffect(int soundId);
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
public abstract int muteAllRemoteAudioStreams(boolean mute);
详情
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在 joinChannel [2/2] 后调用。
- 在使用空间音效时,如需设置是否订阅所有远端用户的音频流,建议调用该方法替代 RtcEngine 的 muteAllRemoteAudioStreams 方法。
- 在调用该方法后,你需要调用 updateSelfPosition 和 updateRemotePosition 更新本地用户和远端用户的空间位置,否则该方法中的设置不会生效。
参数
- mute
-
是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
: 订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteLocalAudioStream
取消或恢复发布本地音频流。
public abstract int muteLocalAudioStream(boolean mute);
详情
- 该方法不影响音频采集状态,因为没有禁用音频采集设备。
- 该方法需要在 joinChannel [2/2] 后调用。
- 在使用空间音效时,如需设置是否发布本地音频流,建议调用该方法替代 RtcEngine 的 muteLocalAudioStream 方法。
- 成功调用该方法后,远端会触发 onUserMuteAudio 回调和 onRemoteAudioStateChanged 回调。
参数
- mute
-
是否取消发布本地音频流。
true
: 取消发布本地音频流。false
: 发布本地音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioRecvRange
设置本地用户的音频接收范围。
public abstract int setAudioRecvRange(float range);
详情
设置成功后,用户只能听见设置范围内或属于同一队伍的远端用户。你可以随时调用该方法更新音频的接收范围。
参数
- range
- 可接收音频的最大范围,单位为游戏引擎中的距离单位。该参数取值需大于 0,默认值为 20。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDistanceUnit
设置游戏引擎单位距离的长度(米)。
public abstract int setDistanceUnit(float unit);
详情
游戏引擎里的距离单位是游戏引擎自定义的,而声网空间音效算法的距离单位为米。默认情况下,SDK 会将每单位的游戏引擎距离换算为一米。你可以调用该方法,将游戏引擎里的单位距离换算为指定的米数。
参数
- unit
- 每单位游戏引擎距离转换后的米数。该参数取值需大于 0.00,默认值为 1.00。例如,将 unit 设为 2.00,表示每单位的游戏引擎距离等于 2 米。
该值越大,当远端用户远离本地用户时,本地用户听到的声音衰减速度越快。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setMaxAudioRecvCount
设置音频接收范围内最多可接收的音频流数。
public abstract int setMaxAudioRecvCount(int maxCount);
详情
如果在音频接收范围内可接收的音频流数超过设置的值,则本地用户会接收音源距离较近的 maxCount 路音频。
参数
- maxCount
- 音频接收范围内最多可接收的音频流数。该参数取值需 ≤ 16,默认值为 10。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setPlayerAttenuation
设置媒体播放器的声音衰减属性。
public abstract int setPlayerAttenuation(int playerId, double attenuation, boolean forceSet);
详情
- 自从
- 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: 方法调用失败。
setRemoteAudioAttenuation
设置指定用户的声音衰减效果。
public abstract int setRemoteAudioAttenuation(int uid, double attenuation, boolean forceSet);
详情
- 自从
- 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: 方法调用失败。
setZones
设置隔声区域。
public abstract int setZones(SpatialAudioZone[] zones);
详情
- 自从
- v4.0.1
在虚拟互动场景下,你可以通过该方法设置隔声区域和声音衰减系数。当音源(可以为用户或媒体播放器)跟听声者分属于隔声区域内部和外部时,会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。
- 当音源跟听声者分属于隔声区域内部和外部时,声音的衰减效果由 SpatialAudioZone 中的声音衰减系数决定。
- 如果用户或媒体播放器同在一个隔声区域内,则不受 SpatialAudioZone 的影响,声音的衰减效果由 setPlayerAttenuation 或 setRemoteAudioAttenuation 中的 attenuation 参数决定。如果不调用 setPlayerAttenuation 或 setRemoteAudioAttenuation,则 SDK 默认声音的衰减系数为 0.5,即模拟声音在真实环境下的衰减。
- 如果音源跟接收者分别属于两个隔声区域,则接收者无法听到音源。
参数
- zones
- 隔声区域的设置。详见 SpatialAudioZone。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updatePlayerPositionInfo
更新媒体播放器的空间位置。
public abstract int updatePlayerPositionInfo(int playerId, RemoteVoicePositionInfo positionInfo);
详情
成功更新后,本地用户可以听到媒体播放器空间位置的变化。
参数
- playerId
- 媒体播放器 ID。可通过 getMediaPlayerId 获取。
- positionInfo
- 媒体播放器的空间位置信息。详见 RemoteVoicePositionInfo。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateSelfPosition
更新本地用户的空间位置。
public abstract int updateSelfPosition( float[] position, float[] axisForward, float[] axisRight, float[] axisUp);
详情
- 在 ILocalSpatialAudioEngine 类下,该方法需要和 updateRemotePosition 搭配使用。SDK 会根据该方法和 updateRemotePosition 设置的参数计算本地和远端用户之间的相对位置,从而计算用户的空间音效参数。
参数
- position
- 在世界坐标系中的坐标。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisForward
- 在世界坐标系前轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisRight
- 在世界坐标系右轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
- axisUp
- 在世界坐标系上轴的单位向量。该参数是长度为 3 的数组,三个值依次表示前、右、上的坐标值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateRemotePosition
更新远端用户的空间位置信息。
public abstract int updateRemotePosition(int uid, RemoteVoicePositionInfo posInfo);
详情
成功调用该方法后,SDK 会根据本地和远端用户的相对位置计算空间音效参数。
参数
- uid
- 用户 ID。需与用户加入频道时填写的用户 ID 一致。
- posInfo
- 远端用户的空间位置信息。详见 RemoteVoicePositionInfo。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
onAudioEffectFinished
本地音效文件播放已结束回调。
public void onAudioEffectFinished(int soundId) {}
当播放音效结束后,会触发该回调。
参数
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。