Audio Effect Processing
Introduces methods and callbacks related to audio effect processing.
clearRemotePositions
Removes the spatial positions of all remote users.
virtual int clearRemotePositions() = 0;
After successfully calling this method, the local user no longer hears any remote users.
After leaving the channel, to avoid wasting resources, you can also call this method to delete the spatial positions of all remote users.
Returns
- 0: Success.
- < 0: Failure.
enableSoundPositionIndication
Enables/Disables stereo panning for remote users.
virtual int enableSoundPositionIndication(bool enabled) = 0;
Ensure that you call this method before joining a channel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition.
Parameters
- enabled
- Whether to enable stereo panning for remote users:
true
: Enable stereo panning.false
: Disable stereo panning.
Returns
- 0: Success.
- < 0: Failure.
enableSpatialAudio
Enables or disables the spatial audio effect.
virtual int enableSpatialAudio(bool enabled) = 0;
After enabling the spatial audio effect, you can call setRemoteUserSpatialAudioParams to set the spatial audio effect parameters of the remote user.
- You can call this method either before or after joining a channel.
- This method relies on the spatial audio dynamic library
libagora_spatial_audio_extension.dll
. If the dynamic library is deleted, the function cannot be enabled normally.
Parameters
- enabled
- Whether to enable the spatial audio effect:
true
: Enable the spatial audio effect.false
: Disable the spatial audio effect.
Returns
- 0: Success.
- < 0: Failure.
getEffectCurrentPosition
Retrieves the playback position of the audio effect file.
virtual int getEffectCurrentPosition(int soundId) = 0;
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.
Returns
- The playback position (ms) of the specified audio effect file, if the method call succeeds.
- < 0: Failure.
getEffectDuration
Retrieves the duration of the audio effect file.
virtual int getEffectDuration(const char* filePath) = 0;
Parameters
- filePath
- File path:
- Android: The file path, which needs to be accurate to the file name and suffix. Agora supports using a URI address, an absolute path, or a path that starts with
/assets/
. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example:content://com.android.providers.media.documents/document/audio%3A14441
. - Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example:
C:\music\audio.mp4
.
- Android: The file path, which needs to be accurate to the file name and suffix. Agora supports using a URI address, an absolute path, or a path that starts with
Returns
- The total duration (ms) of the specified audio effect file, if the method call succeeds.
- < 0: Failure.
getEffectsVolume
Retrieves the volume of the audio effects.
virtual int getEffectsVolume() = 0;
The volume range is [0,100]. The default value is 100, the original volume.
Returns
- Volume of the audio effects, if this method call succeeds.
- < 0: Failure.
getVolumeOfEffect
Gets the volume of a specified audio effect.
virtual int getVolumeOfEffect(int soundId) = 0;
Parameters
- soundId
- The ID of the audio effect.
Returns
- The volume of the specified audio effect, if the method call succeeds. The value range is [0,100]. 100 represents the original volume.
- < 0: Failure.
initialize
Initializes ILocalSpatialAudioEngine.
virtual int initialize(const LocalSpatialAudioConfig& config) = 0;
- Call this method after calling
queryInterface(AGORA_IID_LOCAL_SPATIAL_AUDIO)
. - Before calling other methods of the ILocalSpatialAudioEngine class, you need to call this method to initialize ILocalSpatialAudioEngine.
- The SDK supports creating only one ILocalSpatialAudioEngine instance for an app.
Parameters
- config
- The configuration of ILocalSpatialAudioEngine. See LocalSpatialAudioConfig for details.
Returns
- 0: Success.
- < 0: Failure.
muteAllRemoteAudioStreams
Stops or resumes subscribing to the audio streams of all remote users.
virtual int muteAllRemoteAudioStreams(bool mute) = 0;
After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.
- Call this method after joinChannel [2/2].
- When using the spatial audio effect, if you need to set whether to stop subscribing to the audio streams of all remote users, Agora recommends calling this method instead of the muteAllRemoteAudioStreams method under IRtcEngine.
- After calling this method, you need to call updateSelfPosition and updateRemotePosition to update the spatial location of the local user and the remote user; otherwise, the settings in this method do not take effect.
Parameters
- mute
-
Whether to stop subscribing to the audio streams of all remote users:
true
: Stops subscribing to the audio streams of all remote users.false
: Subscribe to the audio streams of all remote users.
Returns
- 0: Success.
- < 0: Failure.
muteLocalAudioStream
Stops or resumes publishing the local audio stream.
virtual int muteLocalAudioStream(bool mute) = 0;
- This method does not affect any ongoing audio recording, because it does not disable the audio capture device.
- Call this method after joinChannel [2/2].
- When using the spatial audio effect, if you need to set whether to publish the local audio stream, Agora recommends calling this method instead of the muteLocalAudioStream method under IRtcEngine.
Parameters
- mute
- Whether to stop publishing the local audio stream.
true
: Stop publishing the local audio stream.false
: Publish the local audio stream.
Returns
- 0: Success.
- < 0: Failure.
muteRemoteAudioStream
Stops or resumes subscribing to the audio stream of a specified user.
virtual int muteRemoteAudioStream(uid_t uid, bool mute) = 0;
- Since
- v4.0.1
- Call this method after joinChannel [2/2].
- When using the spatial audio effect, if you need to set whether to stop subscribing to the audio stream of a specified user, Agora recommends calling this method instead of the muteRemoteAudioStream method under IRtcEngine.
Parameters
- uid
- The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
- mute
-
Whether to subscribe to the specified remote user's audio stream.
true
: Stop subscribing to the audio stream of the specified user.false
: (Default) Subscribe to the audio stream of the specified user. The SDK decides whether to subscribe according to the distance between the local user and the remote user.
Returns
- 0: Success.
- < 0: Failure.
pauseAllEffects
Pauses playing all audio effect files.
virtual int pauseAllEffects() = 0;
Returns
- 0: Success.
- < 0: Failure.
pauseEffect
Pauses playing a specified audio effect file.
virtual int pauseEffect(int soundId) = 0;
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.
Returns
- 0: Success.
- < 0: Failure.
playAllEffects
Plays all audio effects.
virtual int playAllEffects(int loopCount, double pitch, double pan, int gain, bool publish = false) = 0;
After calling preloadEffect multiple times to preload multiple audio effects into the memory, you can call this method to play all the specified audio effects for all users in the channel.
Parameters
- loopCount
- The number of times the audio effect loops:
- -1: Play the audio effect in an indefinite loop until you call stopEffect or stopAllEffects.
- 0: Play the audio effect once.
- 1: Play the audio effect twice.
- pitch
-
The pitch of the audio effect. The value ranges between 0.5 and 2.0. The default value is 1.0 (original pitch). The lower the value, the lower the pitch.
- pan
- The spatial position of the audio effect. The value ranges between -1.0 and 1.0:
- -1.0: The audio effect shows on the left.
- 0: The audio effect shows ahead.
- 1.0: The audio effect shows on the right.
- gain
-
The volume of the audio effect. The value range is [0, 100]. The default value is 100 (original volume). The smaller the value, the lower the volume.
- publish
- Whether to publish the audio effect to the remote users:
true
: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.false
: Do not publish the audio effect to the remote users. Only the local user can hear the audio effect.
Returns
- 0: Success.
- < 0: Failure.
playEffect
Plays the specified local or online audio effect file.
virtual int playEffect(int soundId,
const char* filePath,
int loopCount,
double pitch,
double pan,
int gain,
bool publish,
int startPos) = 0;
To play multiple audio effect files at the same time, call this method multiple times with different soundId and filePath. For a better user experience, Agora recommends playing no more than three audio effect files at the same time. After the playback of an audio effect file completes, the SDK triggers the onAudioEffectFinished callback.
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that the value of this parameter is the same as that of soundId in preloadEffect.
- filePath
-
The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example,
C:\music\audio.mp4
. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.Attention: If you have preloaded an audio effect into memory by calling preloadEffect, ensure that the value of this parameter is the same as that of filePath in preloadEffect. - loopCount
-
The number of times the audio effect loops.
- ≥ 0: The number of playback times. For example, 1 means looping one time, which means playing the audio effect two times in total.
- -1: Play the audio effect in an infinite loop.
- pitch
- The pitch of the audio effect. The value range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch.
- pan
-
The spatial position of the audio effect. The value ranges between -1.0 and 1.0:
- -1.0: The audio effect is heard on the left of the user.
- 0.0: The audio effect is heard in front of the user.
- 1.0: The audio effect is heard on the right of the user.
- gain
- The volume of the audio effect. The value range is 0.0 to 100.0. The default value is 100.0, which means the original volume. The smaller the value, the lower the volume.
- publish
-
Whether to publish the audio effect to the remote users:
true
: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.false
: Do not publish the audio effect to the remote users. Only the local user can hear the audio effect.
- startPos
-
The playback position (ms) of the audio effect file.
Returns
- 0: Success.
- < 0: Failure.
preloadEffect
Preloads a specified audio effect file into the memory.
virtual int preloadEffect(int soundId, const char* filePath) = 0;
To ensure smooth communication, limit the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling joinChannel [2/2].
- This method does not support online audio effect files.
- For the audio file formats supported by this method, see What formats of audio files the Agora RTC SDK support.
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.
- filePath
- File path:
- Android: The file path, which needs to be accurate to the file name and suffix. Agora supports using a URI address, an absolute path, or a path that starts with
/assets/
. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example:content://com.android.providers.media.documents/document/audio%3A14441
. - Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example:
C:\music\audio.mp4
.
- Android: The file path, which needs to be accurate to the file name and suffix. Agora supports using a URI address, an absolute path, or a path that starts with
Returns
- 0: Success.
- < 0: Failure.
release
Destroys IBaseSpatialAudioEngine.
virtual void release() = 0;
This method releases all resources under IBaseSpatialAudioEngine. When the user does not need to use the spatial audio effect, you can call this method to release resources for other operations.
removeRemotePosition
Removes the spatial position of the specified remote user.
virtual int removeRemotePosition(uid_t uid) = 0;
After successfully calling this method, the local user no longer hears the specified remote user.
After leaving the channel, to avoid wasting resources, you can also call this method to delete the spatial position of the specified remote user.
Parameters
- uid
- The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
Returns
- 0: Success.
- < 0: Failure.
resumeAllEffects
Resumes playing all audio effects.
virtual int resumeAllEffects() = 0;
Returns
- 0: Success.
- < 0: Failure.
resumeEffect
Resumes playing a specified audio effect.
virtual int resumeEffect(int soundId) = 0;
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.
Returns
- 0: Success.
- < 0: Failure.
setAudioEffectParameters
Sets parameters for SDK preset audio effects.
virtual int setAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2) = 0;
- 3D voice effect: Sets the cycle period of the 3D voice effect.
- Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively.
After setting the audio parameters, all users in the channel can hear the effect.
- You can call this method either before or after joining a channel.
- To get better audio effect quality, Agora recommends calling and setting scenario in setAudioProfile [1/2] as AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.
- Do not set the profile parameter in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6), or the method does not take effect.
- This method works best with the human voice. Agora does not recommend using this method for audio containing music.
- After calling setAudioEffectParameters, Agora recommends not calling the following methods, or the settings in setAudioEffectParameters are overridden:
Parameters
- preset
- The options for SDK preset audio effects:
- ROOM_ACOUSTICS_3D_VOICE, 3D voice effect:
- You need to set the profile parameter in setAudioProfile [1/2] to AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator; otherwise, the enumerator setting does not take effect.
- If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.
- PITCH_CORRECTION; pitch correction effect: To achieve better audio effect quality, Agora recommends setting the profile parameter in setAudioProfile [1/2] to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before setting this enumerator.
- ROOM_ACOUSTICS_3D_VOICE, 3D voice effect:
- param1
-
- If you set preset to ROOM_ACOUSTICS_3D_VOICE, param1 indicates the cycle period of the 3D voice effect. The value range is [1,60], in seconds. The default value is 10, indicating that the voice moves around you every 10 seconds.
- If you set preset to PITCH_CORRECTION, param1 indicates the basic mode of the pitch correction effect:
1
: (Default) Natural major scale.2
: Natural minor scale.3
: Japanese pentatonic scale.
- param2
-
- If you set preset to ROOM_ACOUSTICS_3D_VOICE, you need to set param2 to
0
. - If you set preset to PITCH_CORRECTION, param2 indicates the tonic pitch of the pitch correction effect:
1
: A2
: A#3
: B4
: (Default) C5
: C#6
: D7
: D#8
: E9
: F10
: F#11
: G12
: G#
- If you set preset to ROOM_ACOUSTICS_3D_VOICE, you need to set param2 to
Returns
- 0: Success.
- < 0: Failure.
setAudioEffectPreset
Sets an SDK preset audio effect.
virtual int setAudioEffectPreset(AUDIO_EFFECT_PRESET preset) = 0;
Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect.
To get better audio effect quality, Agora recommends calling setAudioProfile [1/2] and setting the scenario parameter as AUDIO_SCENARIO_GAME_STREAMING (3) before calling this method.
- You can call this method either before or after joining a channel.
- Do not set the profile parameter in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6), or the method does not take effect.
- This method works best with the human voice. Agora does not recommend using this method for audio containing music.
- If you call setAudioEffectPreset and set enumerators except for ROOM_ACOUSTICS_3D_VOICE or PITCH_CORRECTION, do not call setAudioEffectParameters; otherwise, setAudioEffectPreset is overridden.
- After calling setAudioEffectPreset, Agora recommends not calling the following methods, or the settings in setAudioEffectPreset are overridden:
- This method relies on the voice beautifier dynamic library
libagora_audio_beauty_extension.dll
. If the dynamic library is deleted, the function cannot be enabled normally.
Parameters
- preset
- The options for SDK preset audio effects. See AUDIO_EFFECT_PRESET.
Returns
- 0: Success.
- < 0: Failure.
setAudioRecvRange
Sets the audio reception range of the local user.
virtual int setAudioRecvRange(float range) = 0;
After the setting is successful, the local user can only hear the remote users within the setting range or belonging to the same team. You can call this method at any time to update the audio reception range.
Parameters
- range
- The maximum audio reception range. The unit is meters. The value must be greater than 0.
Returns
- 0: Success.
- < 0: Failure.
setDistanceUnit
Sets the length (in meters) of the game engine distance per unit.
virtual int setDistanceUnit(float unit) = 0;
In a game engine, the unit of distance is customized, while in the Agora spatial audio algorithm, distance is measured in meters. By default, the SDK converts the game engine distance per unit to one meter. You can call this method to convert the game engine distance per unit to a specified number of meters.
Parameters
- unit
- The number of meters that the game engine distance per unit is equal to. This parameter must be greater than 0.00. For example, setting unit as 2.00 means the game engine distance per unit equals 2 meters.
The larger the value is, the faster the sound heard by the local user attenuates when the remote user moves far away from the local user.
Returns
- 0: Success.
- < 0: Failure.
setEffectPosition
Sets the playback position of an audio effect file.
virtual int setEffectPosition(int soundId, int pos) = 0;
After a successful setting, the local audio effect file starts playing at the specified position.
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.
- pos
- The playback position (ms) of the audio effect file.
Returns
- 0: Success.
- < 0: Failure.
setEffectsVolume
Sets the volume of the audio effects.
virtual int setEffectsVolume(int volume) = 0;
Parameters
- volume
- The playback volume. The value range is [0, 100]. The default value is 100, which represents the original volume.
Returns
- 0: Success.
- < 0: Failure.
setHeadphoneEQParameters
Sets the low- and high-frequency parameters of the headphone equalizer.
virtual int setHeadphoneEQParameters(int lowGain, int highGain) = 0;
- Since
- v4.1.0
In a spatial audio effect scenario, if the preset headphone equalization effect is not achieved after calling the setHeadphoneEQPreset method, you can further adjust the headphone equalization effect by calling this method.
Parameters
- lowGain
- The low-frequency parameters of the headphone equalizer. The value range is [-10,10]. The larger the value, the deeper the sound.
- highGain
- The high-frequency parameters of the headphone equalizer. The value range is [-10,10]. The larger the value, the sharper the sound.
Returns
- 0: Success.
- < 0: Failure.
- -1: A general error occurs (no specified reason).
setHeadphoneEQPreset
Sets the preset headphone equalization effect.
virtual int setHeadphoneEQPreset(HEADPHONE_EQUALIZER_PRESET preset) = 0;
- Since
- v4.0.1
This method is mainly used in spatial audio effect scenarios. You can select the preset headphone equalizer to listen to the audio to achieve the expected audio experience.
Parameters
- preset
- The preset headphone equalization effect. See HEADPHONE_EQUALIZER_PRESET.
Returns
- 0: Success.
- < 0: Failure.
- -1: A general error occurs (no specified reason).
setLocalVoiceEqualization
Sets the local voice equalization effect.
virtual int setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain) = 0;
Parameters
- bandFrequency
- The band frequency. The value ranges between 0 and 9; representing the respective 10-band center frequencies of the voice effects, including 31, 62, 125, 250, 500, 1k, 2k, 4k, 8k, and 16k Hz. For more details, see AUDIO_EQUALIZATION_BAND_FREQUENCY.
- bandGain
- The gain of each band in dB. The value ranges between -15 and 15. The default value is 0.
Returns
- 0: Success.
- < 0: Failure.
setLocalVoicePitch
Changes the voice pitch of the local speaker.
virtual int setLocalVoicePitch(double pitch) = 0;
Parameters
- pitch
- The local voice pitch. The value range is [0.5,2.0]. The lower the value, the lower the pitch. The default value is 1 (no change to the pitch).
Returns
- 0: Success.
- < 0: Failure.
setLocalVoiceReverb
Sets the local voice reverberation.
virtual int setLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value) = 0;
The SDK also provides the setAudioEffectPreset method, which allows you to directly implement preset reverb effects for such as pop, R&B, and KTV.
Parameters
- reverbKey
- The reverberation key. Agora provides five reverberation keys; see AUDIO_REVERB_TYPE for details.
- value
- The value of the reverberation key.
Returns
- 0: Success.
- < 0: Failure.
setMaxAudioRecvCount
Sets the maximum number of streams that a user can receive in a specified audio reception range.
virtual int setMaxAudioRecvCount(int maxCount) = 0;
If the number of receivable streams exceeds the set value, the local user receives the maxCount streams that are closest to the local user. If there are users who belong to the same team as the local user in the room, the local user receives the audio of the teammates first. For example, when maxCount is set to 3, if there are five remote users in the room, two of whom belong to the same team as the local user, and three of whom belong to different teams but are within the audio reception range of the local user, the local user can hear the two teammates and the one user from a different team closest to the local user.
Parameters
- maxCount
- The maximum number of streams that a user can receive within a specified audio reception range.
Returns
- 0: Success.
- < 0: Failure.
setPlayerAttenuation
Sets the sound attenuation properties of the media player.
virtual int setPlayerAttenuation(int playerId, double attenuation, bool forceSet) = 0;
- Since
- v4.0.1
Parameters
- playerId
- The ID of the media player. You can get the media player ID by calling getMediaPlayerId.
- attenuation
- The sound attenuation coefficient of the remote user or media player. The value range is [0,1]. The values are as follows:
- 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance.
- (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment.
- 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the speaker_attenuation parameter.
- (0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process.
- forceSet
- Whether to force the sound attenuation effect of the media player:
true
: Force attenuation to set the attenuation of the user. At this time, the attenuation coefficient of the sound insulation area set in the audioAttenuation in the SpatialAudioZone does not take effect for the user.false
: Do not force attenuation e to set the user's sound attenuationffect, as shown in the following two cases.- If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the audioAttenuation in SpatialAudioZone.
- If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by attenuation in this method.
Returns
- 0: Success.
- < 0: Failure.
setRemoteAudioAttenuation
Sets the sound attenuation effect for the specified user.
virtual int setRemoteAudioAttenuation(uid_t uid, double attenuation, bool forceSet) = 0;
- Since
- v4.0.1
Parameters
- uid
- The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
- attenuation
- For the user's sound attenuation coefficient, the value range is [0,1]. The values are as follows:
- 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance.
- (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment.
- 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the speaker_attenuation parameter.
- (0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process.
- forceSet
- Whether to force the user's sound attenuation effect:
true
: Force attenuation to set the sound attenuation of the user. At this time, the attenuation coefficient of the sound insulation area set in the audioAttenuation in the SpatialAudioZone does not take effect for the user.false
: Do not force attenuation to set the user's sound attenuation effect, as shown in the following two cases.- If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the audioAttenuation in SpatialAudioZone.
- If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by attenuation in this method.
Returns
- 0: Success.
- < 0: Failure.
setRemoteUserSpatialAudioParams
Sets the spatial audio effect parameters of the remote user.
virtual int setRemoteUserSpatialAudioParams(uid_t uid, const agora::SpatialAudioParams& params) = 0;
Call this method after enableSpatialAudio. After successfully setting the spatial audio effect parameters of the remote user, the local user can hear the remote user with a sense of space.
Parameters
- uid
- The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
- params
- The spatial audio parameters. See SpatialAudioParams for details.
Returns
- 0: Success.
- < 0: Failure.
setRemoteVoicePosition
Sets the 2D position (the position on the horizontal plane) of the remote user's voice.
virtual int setRemoteVoicePosition(uid_t uid, double pan, double gain) = 0;
This method sets the 2D position and volume of a remote user, so that the local user can easily hear and identify the remote user's position.
When the local user calls this method to set the voice position of a remote user, the voice difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a sense of space. This method applies to massive multiplayer online games, such as Battle Royale games.
- For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel.
- For the best voice positioning, Agora recommends using a wired headset.
- Call this method after joining a channel.
Parameters
- uid
- The user ID of the remote user.
- pan
- The voice position of the remote user. The value ranges from -1.0 to 1.0:
- 0.0: (Default) The remote voice comes from the front.
- -1.0: The remote voice comes from the left.
- 1.0: The remote voice comes from the right.
- gain
- The volume of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original volume of the remote user). The smaller the value, the lower the volume.
Returns
- 0: Success.
- < 0: Failure.
setVoiceBeautifierParameters
Sets parameters for the preset voice beautifier effects.
virtual int setVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2) = 0;
Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. After setting the audio parameters, all users in the channel can hear the effect.
For better voice effects, Agora recommends that you call setAudioProfile [1/2] and set scenario to AUDIO_SCENARIO_GAME_STREAMING(3) and profile to AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.
- You can call this method either before or after joining a channel.
- Do not set the profile parameter in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6), or the method does not take effect.
- This method works best with the human voice. Agora does not recommend using this method for audio containing music.
- After calling setVoiceBeautifierParameters, Agora recommends not calling the following methods, because they can override settings in setVoiceBeautifierParameters:
Parameters
- preset
- The option for the preset audio effect:
SINGING_BEAUTIFIER
: The singing beautifier effect.
- param1
- The gender characteristics options for the singing voice:
1
: A male-sounding voice.2
: A female-sounding voice.
- param2
- The reverberation effect options for the singing voice:
1
: The reverberation effect sounds like singing in a small room.2
: The reverberation effect sounds like singing in a large room.3
: The reverberation effect sounds like singing in a hall.
Returns
- 0: Success.
- < 0: Failure.
setVoiceBeautifierPreset
Sets a preset voice beautifier effect.
virtual int setVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset) = 0;
Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting a voice beautifier effect, all users in the channel can hear the effect. You can set different voice beautifier effects for different scenarios.
For better voice effects, Agora recommends that you call setAudioProfile [1/2] and set scenario to AUDIO_SCENARIO_GAME_STREAMING (3) and profile to AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) before calling this method.
- You can call this method either before or after joining a channel.
- Do not set the profile parameter in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6), or the method does not take effect.
- This method works best with the human voice. Agora does not recommend using this method for audio containing music.
- After calling setVoiceBeautifierPreset, Agora recommends not calling the following methods, because they can override settings in setVoiceBeautifierPreset:
- This method relies on the voice beautifier dynamic library
libagora_audio_beauty_extension.dll
. If the dynamic library is deleted, the function cannot be enabled normally.
Parameters
- preset
-
The preset voice beautifier effect options: VOICE_BEAUTIFIER_PRESET.
Returns
- 0: Success.
- < 0: Failure.
setVoiceConversionPreset
Sets a preset voice beautifier effect.
virtual int setVoiceConversionPreset(VOICE_CONVERSION_PRESET preset) = 0;
Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting an audio effect, all users in the channel can hear the effect. You can set different voice beautifier effects for different scenarios. For the applicable scenarios of each voice beautifier effect, refer to Set the Voice Effect.
To achieve better audio effect quality, Agora recommends that you call setAudioProfile [1/2] and set the profile to AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5) and scenario to AUDIO_SCENARIO_GAME_STREAMING(3) before calling this method.
- You can call this method either before or after joining a channel.
- Do not set the profile parameter in setAudioProfile [1/2] to AUDIO_PROFILE_SPEECH_STANDARD(1) or AUDIO_PROFILE_IOT(6), or the method does not take effect.
- This method works best with the human voice. Agora does not recommend using this method for audio containing music.
- After calling setVoiceConversionPreset, Agora recommends not calling the following methods, or the settings in setVoiceConversionPreset are overridden:
- This method relies on the voice beautifier dynamic library
libagora_audio_beauty_extension.dll
. If the dynamic library is deleted, the function cannot be enabled normally.
Parameters
- preset
-
The options for the preset voice beautifier effects: VOICE_CONVERSION_PRESET.
Returns
- 0: Success.
- < 0: Failure.
setVolumeOfEffect
Sets the volume of a specified audio effect.
virtual int setVolumeOfEffect(int soundId, int volume) = 0;
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.
- volume
- The playback volume. The value range is [0, 100]. The default value is 100, which represents the original volume.
Returns
- 0: Success.
- < 0: Failure.
setZones
Sets the sound insulation area.
virtual int setZones(const SpatialAudioZone *zones, unsigned int zoneCount) = 0;
- Since
- v4.0.1
In virtual interactive scenarios, you can use this method to set the sound insulation area and sound attenuation coefficient. When the sound source (which can be the user or the media player) and the listener belong to the inside and outside of the sound insulation area, they can experience the attenuation effect of sound similar to the real environment when it encounters a building partition.
- When the sound source and the listener belong to the inside and outside of the sound insulation area, the sound attenuation effect is determined by the sound attenuation coefficient in SpatialAudioZone.
- If the user or media player is in the same sound insulation area, it is not affected by SpatialAudioZone, and the sound attenuation effect is determined by the attenuation parameter in setPlayerAttenuation or setRemoteAudioAttenuation. If you do not call setPlayerAttenuation or setRemoteAudioAttenuation, the default sound attenuation coefficient of the SDK is 0.5, which simulates the attenuation of the sound in the real environment.
- If the sound source and the receiver belong to two sound insulation areas, the receiver cannot hear the sound source.
Parameters
- zones
- Sound insulation area settings. See SpatialAudioZone.
- zoneCount
- The number of sound insulation areas.
Returns
- 0: Success.
- < 0: Failure.
stopAllEffects
Stops playing all audio effects.
virtual int stopAllEffects() = 0;
Returns
- 0: Success.
- < 0: Failure.
stopEffect
Stops playing a specified audio effect.
virtual int stopEffect(int soundId) = 0;
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.
Returns
- 0: Success.
- < 0: Failure.
unloadAllEffects
Releases a specified preloaded audio effect from the memory.
virtual int unloadAllEffects() = 0;
Returns
- 0: Success.
- < 0: Failure.
unloadEffect
Releases a specified preloaded audio effect from the memory.
virtual int unloadEffect(int soundId) = 0;
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.
Returns
- 0: Success.
- < 0: Failure.
updatePlayerPositionInfo
Updates the spatial position of the media player.
virtual int updatePlayerPositionInfo(int playerId, const RemoteVoicePositionInfo& positionInfo) = 0;
After a successful update, the local user can hear the change in the spatial position of the media player.
Parameters
- playerId
- The ID of the media player. You can get the media player ID by calling getMediaPlayerId.
- positionInfo
- The spatial position of the media player. See RemoteVoicePositionInfo.
Returns
- 0: Success.
- < 0: Failure.
updateRemotePosition
Updates the spatial position of the specified remote user.
virtual int updateRemotePosition(uid_t uid, const RemoteVoicePositionInfo &posInfo) = 0;
After successfully calling this method, the SDK calculates the spatial audio parameters based on the relative position of the local and remote user.
Parameters
- uid
- The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
- posInfo
- The spatial position of the remote user. See RemoteVoicePositionInfo.
Returns
- 0: Success.
- < 0: Failure.
updateSelfPosition
Updates the spatial position of the local user.
virtual int updateSelfPosition(float position[3], float axisForward[3], float axisRight[3], float axisUp[3]) = 0;
- Under the ILocalSpatialAudioEngine class, this method needs to be used with updateRemotePosition. The SDK calculates the relative position between the local and remote users according to this method and the parameter settings in updateRemotePosition, and then calculates the user's spatial audio effect parameters.
Parameters
- position
- The coordinates in the world coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
- axisForward
- The unit vector of the x axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
- axisRight
- The unit vector of the y axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
- axisUp
- The unit vector of the z axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
Returns
- 0: Success.
- < 0: Failure.
onAudioEffectFinished
Occurs when the playback of the local music file finishes.
virtual void onAudioEffectFinished(int soundId) { }
This callback occurs when the local audio effect file finishes playing.
Parameters
- soundId
- The audio effect ID. The ID of each audio effect file is unique.