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

This method supports playing URI files starting with content://. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support. If the local music file does not exist, the SDK does not support the file format, or the the SDK cannot access the music file URL, the SDK reports AUDIO_MIXING_REASON_CAN_NOT_OPEN.

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 you do not playing more than three audio files at the same time.

Call timing

You can call this method either before or after joining a channel.

Restrictions

If you need 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 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.

Related callbacks

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 file path. The SDK supports URI addresses starting with content://, paths starting with /assets/, URLs and absolute paths of local files. The absolute path needs to be accurate to the file name and extension. 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.

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

This method supports playing URI files starting with content://. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support. If the local music file does not exist, the SDK does not support the file format, or the the SDK cannot access the music file URL, the SDK reports AUDIO_MIXING_REASON_CAN_NOT_OPEN.

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 you do not playing more than three audio files at the same time.

Call timing

You can call this method either before or after joining a channel.

Restrictions

If you need 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 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.

Related callbacks

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 file path. The SDK supports URI addresses starting with content://, paths starting with /assets/, URLs and absolute paths of local files. The absolute path needs to be accurate to the file name and extension. 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);

Ensure the size of all preloaded files does not exceed the limit.

For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support.

Call timing

Agora recommends that you call this method before joining a channel.

Restrictions

None.

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

After you call pauseAllEffects to pause the playback, you can call this method to resume the playback.

Call timing

Call this method after pauseAllEffects.

Restrictions

None.

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

Call timing

Call this method after playEffect [2/2].

Restrictions

None.

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

Gets the volume of a specified audio effect file.

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

Call timing

Call this method after playEffect [2/2].

Restrictions

None.

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

When you no longer need to play the audio effect, you can call this method to stop the playback. If you only need to pause the playback, call pauseAllEffects.

Call timing

Call this method after the playEffect [1/2] or playEffect [2/2].

Restrictions

None.

Returns

  • 0: Success.
  • < 0: Failure.

stopEffect

Stops playing a specified audio effect.

public abstract int stopEffect(int soundId);

When you no longer need to play the audio effect, you can call this method to stop the playback. If you only need to pause the playback, call pauseEffect.

Call timing

Call this method after the playEffect [1/2] or playEffect [2/2].

Restrictions

None.

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

After loading the audio effect file into memory using preloadEffect, if you need to release the audio effect file, call this method.

Call timing

You can call this method either before or after joining a channel.

Restrictions

None.

Parameters

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

Returns

  • 0: Success.
  • < 0: Failure.