IAudioEffectManager

This class provides audio management methods.

getEffectsVolume

Retrieves the volume of the audio effects.

public double getEffectsVolume();

Details

The volume is an integer ranging from 0 to 100. The default value is 100, which means the original volume.

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

Returns

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

getVolumeOfEffect

Gets the volume of a specified audio effect file.

public abstract int getVolumeOfEffect(int soundId);

Parameters

soundId
The ID of the audio effect file.

Returns

  • ≥ 0: Returns the volume of the specified audio effect, if the method call is successful. The value ranges between 0 and 100. 100 represents the original volume.
  • < 0: Failure.

pauseAllEffects

Pauses all audio effects.

public abstract int pauseAllEffects();

Returns

  • 0: Success.
  • < 0: Failure.

pauseEffect

Pauses 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);

Details

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. To achieve the optimal user experience, Agora recommends that do not playing more than three audio 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 file 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);

Details

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. To achieve the optimal user experience, Agora recommends that do not playing more than three audio files at the same time. After the playback of an audio effect file completes, the SDK triggers the onAudioEffectFinished callback.

This method supports playing URI files starting with content://.

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 file 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);

Details

To ensure smooth communication, It is recommended that you limit the size of the audio effect file. You can call 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 URL addresses, absolute paths, or file paths that start 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 effect files.

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);

Details

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

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 ID of the audio effect. 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 ID of the audio effect. Each audio effect has a unique ID.

Returns

  • 0: Success.
  • < 0: Failure.

unloadEffect

Releases a specified preloaded audio effect from the memory.

public abstract int unloadEffect(int soundId);

Parameters

soundId
The ID of the audio effect. Each audio effect has a unique ID.

Returns

  • 0: Success.
  • < 0: Failure.