IAudioEffectManager

This class provides audio management methods.

getEffectsVolume

Retrieves the volume of the audio effects.

public double getEffectsVolume();

The volume range is [0,100]. The default value is 100, the original volume.

Attention: Call this method after the playEffect [2/2] method.

Returns

  • Volume of the audio effects, if this method call succeeds.
  • < 0: Failure.

getVolumeOfEffect

Gets the volume of a specified audio effect.

public abstract int getVolumeOfEffect(int soundId);

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.

pauseAllEffects

Pauses playing all audio effect files.

public abstract int pauseAllEffects();

Returns

  • 0: Success.
  • < 0: Failure.

pauseEffect

Pauses playing a specified audio effect file.

public abstract int pauseEffect(int soundId);

Parameters

soundId
The audio effect ID. The ID of each audio effect file is unique.

Returns

  • 0: Success.
  • < 0: Failure.

playEffect [1/2]

Plays the specified local or online audio effect file.

 public abstract int playEffect(int soundId, String filePath, int loopCount, double pitch,
      double pan, double gain, boolean publish);
Attention: If you use this method to play an online audio effect file, Agora recommends that you cache the online audio effect file to your local device, call preloadEffect to preload the cached audio effect file into memory, and then call this method to play the audio effect. Otherwise, you might encounter playback failures or no sound during playback due to loading timeouts or failures.
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.
Note: Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See Supported Audio Formats.

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. 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%203A14441.

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.

Returns

  • 0: Success.
  • < 0: Failure.

playEffect [2/2]

Plays the specified local or online audio effect file.

public int playEffect(int soundId, String filePath, int loopCount, double pitch,
                        double pan, double gain, boolean publish, int startPos);
Attention: If you use this method to play an online audio effect file, Agora recommends that you cache the online audio effect file to your local device, call preloadEffect to preload the cached audio effect file into memory, and then call this method to play the audio effect. Otherwise, you might encounter playback failures or no sound during playback due to loading timeouts or failures.

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, content://com.android.providers.media.documents/document/audio%203A14441. 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.

public int preloadEffect(int soundId, String filePath);

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].

Attention:

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.

Returns

  • 0: Success.
  • < 0: Failure.

resumeAllEffects

Resumes playing all audio effects.

public abstract int resumeAllEffects();

Returns

  • 0: Success.
  • < 0: Failure.

resumeEffect

Resumes playing a specified audio effect.

public abstract int resumeEffect(int soundId);

Parameters

soundId
The audio effect ID. The ID of each audio effect file is unique.

Returns

  • 0: Success.
  • < 0: Failure.

setEffectsVolume

Sets the volume of the audio effects.

public abstract int setEffectsVolume(double volume);
Attention: Call this method after the playEffect [2/2] method.

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.

setVolumeOfEffect

Sets the volume of a specified audio effect.

public abstract int setVolumeOfEffect(int soundId, double volume);

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.

stopAllEffects

Stops playing all audio effects.

public abstract int stopAllEffects();

Returns

  • 0: Success.
  • < 0: Failure.

stopEffect

Stops playing a specified audio effect.

public abstract int stopEffect(int soundId);

Parameters

soundId
The audio effect ID. The ID of each audio effect file is unique.

Returns

  • 0: Success.
  • < 0: Failure.

unloadEffect

Releases a specified preloaded audio effect from the memory.

public abstract int unloadEffect(int soundId);

Parameters

soundId
The audio effect ID. The ID of each audio effect file is unique.

Returns

  • 0: Success.
  • < 0: Failure.