Audio Effect Files

getEffectCurrentPosition

Gets the current playback position of the specified audio effect file.

public abstract int getEffectCurrentPosition(int soundId);

Note: Call this method after calling the playEffect method.

Parameters

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

Return Values

On success, returns the playback position (ms) of the specified audio effect file.
< 0: Failure.

getEffectDuration

Gets the duration of an audio effect file.

public abstract int getEffectDuration(String filePath);

Note: Call this method after joining a channel.

Parameters

filePath

The path of the audio effect file:

Android: The path must include the file name and extension. Supports URL, absolute path, or file path starting with /assets/. Accessing local files with an absolute path may cause permission issues. It is recommended to use a URI, such as:

content://com.android.providers.media.documents/document/audio%3A14441.

Return Values

On success, returns the total duration (ms) of the specified audio effect file.
< 0: Failure.

getEffectsVolume

Gets the volume of the audio effects.

public abstract double getEffectsVolume();

The volume is an integer in the range [0, 100]. The default is 100, representing the original volume.

Note: Call this method after calling playEffect.

Return Values

On success, returns the volume of the audio effects.
< 0: Failure.

getVolumeOfEffect

Gets the volume of the specified sound effect file.

public abstract int getVolumeOfEffect(int soundId);

Parameters

soundId: The ID of the sound effect file.

Return Values

If the method call succeeds, returns the volume of the specified sound effect. The range is [0, 100], where 100 is the original volume.
If the method call fails, returns a value less than 0.

pauseEffect

Pauses playback of the specified sound effect file.

public abstract int pauseEffect(int soundId);

Parameters

soundId: Sound effect ID. Each sound effect file has a unique ID.

Return Values

0: Success.
< 0: Failure.

playAllEffects

Plays all sound effects.

public abstract int playAllEffects(int loopCount, double pitch, double pan, double gain, boolean publish);

After preloading multiple sound effects into memory using preloadEffect, you can call this method to play all preloaded sound effects for all users in the channel.

Parameters

loopCount

The number of times the sound effect loops:

-1: Loops indefinitely until stopEffect or stopAllEffects is called.
0: Plays the sound effect once.
1: Plays the sound effect twice.

pitch

The pitch of the sound effect. The range is [0.5, 2.0], with a default value of 1.0 (original pitch). Lower values indicate lower pitch.

pan

The spatial position of the sound effect. The range is [-1.0, 1.0]:

-1.0: Plays from the left.
0.0: Plays from the center.
1.0: Plays from the right.

gain

The volume of the sound effect. The range is [0, 100], with a default value of 100 (original volume). Lower values indicate lower volume.

publish

Whether to publish the sound effect to remote users:

true: Publishes the sound effect to remote users. Both local and remote users can hear it.
false: (Default) Does not publish the sound effect. Only the local user can hear it.

Return Values

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 that start with content://. See What formats of audio files does the Agora RTC SDK support for supported formats. If the local audio file does not exist, the SDK does not support the file format, or the audio file URL is inaccessible, the SDK returns AUDIO_MIXING_REASON_CAN_NOT_OPEN. To play multiple audio effect files simultaneously, call this method multiple times with different soundId and filePath. For the best user experience, Agora recommends not playing more than three audio files simultaneously.

Note:

To play online audio effect files, Agora recommends caching the file on the local device and calling preloadEffect to preload it into memory before calling this method to play it. Otherwise, playback may fail or be silent due to timeout or loading failure.
If you call preloadEffectEx before playEffectEx, the file resource will not be closed after playEffectEx is executed. The next time you call playEffectEx, it will start playing from the beginning.
If you call playEffectEx directly without calling preloadEffectEx, the resource will be destroyed after playEffectEx is executed. The next time you call it, it will try to reopen the file and play from the beginning.

Timing

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

Related Callbacks

After the audio effect file finishes playing, the SDK triggers the onAudioEffectFinished callback.

Parameters

soundId

Audio effect ID. Each audio effect file must have a unique ID.

Note: If you have preloaded the audio effect into memory using preloadEffect, make sure this parameter matches the soundId used in preloadEffect.

filePath

File path. Supports URI starting with content://, path starting with /assets/, URL, and absolute path of local files. The absolute path must include the file name and extension. Supported formats include MP3, AAC, M4A, MP4, WAV, and 3GP.

Note: If you have preloaded the audio effect into memory using preloadEffect, make sure this parameter matches the filePath used in preloadEffect.

loopCount

Number of times the audio effect loops:

≥ 0: Number of times to play. For example, 1 means loop once, i.e., play twice in total.
-1: Loop the audio file indefinitely.

pitch

Pitch of the audio effect. Range: 0.5 to 2.0. Default is 1.0, which represents the original pitch. The smaller the value, the lower the pitch.

pan

Spatial position of the audio effect. Range: -1.0 to 1.0:

-1.0: Played from the user's left.
0.0: Played from the front.
1.0: Played from the user's right.

gain

Volume of the audio effect. Range: 0.0 to 100.0. Default is 100.0, which represents the original volume. The smaller the value, the lower the volume.

publish

Whether to publish the audio effect to remote users:

true: Publish the audio effect. Both local and remote users can hear it.
false: Do not publish the audio effect. Only the local user can hear it.

Return Values

0: The method call succeeds. < 0: The method call fails.

playEffect [2/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, int startPos);

This method supports playing URI files that start with content://. For supported audio file formats, see What formats of audio files does the Agora RTC SDK support. If the local audio file does not exist, the SDK does not support the file format, or the audio file URL is inaccessible, the SDK reports AUDIO_MIXING_REASON_CAN_NOT_OPEN.

Note:

If you need to play an online audio effect file, it is recommended to first cache it to the local device, call preloadEffect to preload the file into memory, and then call this method to play it. Otherwise, playback may fail or be silent due to timeout or loading failure.
If preloadEffect is called before playEffect, the file resource will not be closed after playEffect is executed. The next call to playEffect will start playback from the beginning.
If playEffect is called without first calling preloadEffect, the resource will be destroyed after playback ends. The next call to playEffect will attempt to reopen the file and play from the beginning.

Timing

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

Related Callbacks

After the audio effect file finishes playing, the SDK triggers the onAudioEffectFinished callback.

Parameters

soundId

Audio effect ID. Each audio effect file has a unique ID.

Note: If you have preloaded the audio effect into memory by calling preloadEffect, ensure that this parameter matches the soundId used in preloadEffect.

filePath

File path. Supports URIs starting with content://, paths starting with /assets/, URLs, and absolute paths of local files. The path must include the file name and extension. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP.

Note: If you have preloaded the audio effect into memory by calling preloadEffect, ensure that this parameter matches the filePath used in preloadEffect.

loopCount

Number of times the audio effect is looped:

≥ 0: Number of loops. For example, 1 means loop once, i.e., play twice in total.
-1: Loop the audio file indefinitely.

pitch

Pitch of the audio effect. Value range is 0.5 to 2.0. Default is 1.0, which means original pitch. The smaller the value, the lower the pitch.

pan

Spatial position of the audio effect. Value range is -1.0 to 1.0:

-1.0: Audio plays from the user's left.
0.0: Audio plays from the front.
1.0: Audio plays from the user's right.

gain

Volume of the audio effect. Value range is 0.0 to 100.0. Default is 100.0, which means original volume. The smaller the value, the lower the volume.

publish

Whether to publish the audio effect to remote users:

true: Publish the audio effect to remote users. Both local and remote users can hear it.
false: Do not publish the audio effect to remote users. Only the local user can hear it.

startPos

Start position of the audio effect file in milliseconds.

Return Values

0: Success. < 0: Failure.

playEffectEx [1/2]

Plays the specified audio effect in the channel.

public abstract int playEffectEx(RtcConnection connection, int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish, int startPos);

Since: Available since v4.6.0.

You can call this method to play the specified audio effect to all users in the channel. Each call to this method can only play one audio effect. To play multiple audio effects simultaneously, call this method multiple times and set different soundId and filePath for each audio effect.

Note:

Agora recommends not playing more than three audio effects simultaneously.
The sound effect ID and file path in this method must be consistent with those in the preloadEffectEx method.
If preloadEffectEx is called before playEffectEx, the file resource will not be closed after playEffectEx is executed. The next call to playEffectEx will start playback from the beginning.
If preloadEffectEx is not called before playEffectEx, the resource will be destroyed after playEffectEx is executed. The next call to playEffectEx will attempt to reopen the file and play from the beginning.

Scenario

This method applies to multi-channel scenarios.

Parameters

connection

Connection information. See RtcConnection.

soundId

Audio effect ID.

filePath

The absolute path of a local file or the URL of an online file. Supported audio formats include mp3, mp4, m4a, aac, 3gp, mkv, and wav.

loopCount

Number of times the audio effect loops:

-1: Loops indefinitely until stopEffect or stopAllEffects is called.
0: Plays once.
1: Plays twice.

pitch

Pitch of the audio effect. The range is from 0.5 to 2.0. The default value is 1.0 (original pitch). The smaller the value, the lower the pitch.

pan

Spatial position of the audio effect. The range is from -1.0 to 1.0:

-1.0: The audio effect plays from the user's left.
0.0: The audio effect plays from the user's front.
1.0: The audio effect plays from the user's right.

gain

Volume of the audio effect. The range is from 0.0 to 100.0. The default value is 100 (original volume). The smaller the value, the lower the volume.

publish

Whether to publish the audio effect in the channel:

true: Publishes the audio effect in the channel.
false: Does not publish the audio effect in the channel.

startPos

The start position (in milliseconds) for playback of the audio effect file.

Return Values

0: Success.
< 0: Failure.

playEffectEx [2/2]

Plays the specified audio effect in the channel.

public abstract int playEffectEx(RtcConnection connection, int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish);

Since: Available since v4.6.0.

After calling preloadEffectEx to preload the audio effect, you can use this method to play the specified audio effect to all users in the channel. You can call this method multiple times with different soundId and filePath to play multiple audio effects simultaneously. Each call to this method can only play one audio effect.

Note:

Agora recommends not playing more than three audio effects simultaneously.
The sound effect ID and file path in this method must be consistent with those in the preloadEffectEx method.
If preloadEffectEx is called before playEffectEx, the file resource will not be closed after playEffectEx is executed. The next call to playEffectEx will start playback from the beginning.
If preloadEffectEx is not called before playEffectEx, the resource will be destroyed after playEffectEx is executed. The next call to playEffectEx will attempt to reopen the file and play from the beginning.

Scenario

This method applies to multi-channel scenarios.

Parameters

connection

Connection information. See RtcConnection.

soundId

Audio effect ID.

filePath

The absolute path of a local file or the URL of an online file. Supported audio formats include: mp3, mp4, m4a, aac, 3gp, mkv, and wav.

loopCount

Number of times the audio effect loops:

-1: Loops indefinitely until stopEffect or stopAllEffects is called.
0: Plays once.
1: Plays twice.

pitch

Pitch of the audio effect. The range is from 0.5 to 2.0. The default value is 1.0 (original pitch). The smaller the value, the lower the pitch.

pan

Spatial position of the audio effect. The range is from -1.0 to 1.0:

-1.0: The audio effect plays from the user's left.
0.0: The audio effect plays from the user's front.
1.0: The audio effect plays from the user's right.

gain

Volume of the audio effect. The range is from 0.0 to 100.0. The default value is 100 (original volume). The smaller the value, the lower the volume.

publish

Whether to publish the audio effect in the channel:

true: Publishes the audio effect in the channel.
false: Does not publish the audio effect in the channel.

Return Values

0: Success.
< 0: Failure.

preloadEffect [1/2]

Preloads the specified audio effect file.

public abstract int preloadEffect(int soundId, String filePath, int startPos);

This method preloads only one specified audio effect file into memory per call. To preload multiple audio effect files, call this method multiple times. After preloading, you can call playEffect to play the preloaded effect or call playAllEffects to play all preloaded effects.

Note:

To ensure smooth communication, limit the size of audio effect files.
Agora recommends calling this method before joining a channel.
If you call preloadEffect before playEffect, the file resource will not be closed after playEffect is executed. The next time you call playEffect, it will start playing from the beginning.
If you do not call preloadEffect before playEffect, the resource will be destroyed after playEffect is executed. The next time you call playEffect, it will try to reopen the file and play from the beginning.

Parameters

soundId: ID of the audio effect.
filePath: Absolute path of a local audio effect file or URL of an online audio effect file.
startPos: Start playback position of the online audio effect file. Supported formats include: mp3, mp4, m4a, aac, 3gp, mkv, and wav.

Return Values

0: The method call succeeds.
< 0: The method call fails.

preloadEffect [2/2]

Preloads the specified audio effect file into memory.

public abstract int preloadEffect(int soundId, String filePath);

Make sure the total size of all preloaded files does not exceed the limit. See What formats of audio files does the Agora RTC SDK support.

Note:

If you call preloadEffect before playEffect, the file resource will not be closed after playEffect is executed. The next time you call playEffect, it will start playing from the beginning.
If you do not call preloadEffect before playEffect, the resource will be destroyed after playEffect is executed. The next time you call playEffect, it will try to reopen the file and play from the beginning.

Timing

Agora recommends calling this method before joining a channel.

Parameters

soundId

Audio effect ID. Each audio effect file must have a unique ID.

filePath

File path. Supports the following formats:

URL.
Absolute path.
File path starting with /assets/.

The path must include the file name and extension. If you access a local file using an absolute path, you may encounter permission issues. It is recommended to use a URI, for example:content://com.android.providers.media.documents/document/audio%3A14441.

Return Values

0: The method call succeeds.
< 0: The method call fails.

preloadEffectEx [1/2]

Preloads the specified audio effect into the channel.

public abstract int preloadEffectEx(RtcConnection connection, int soundId, String filePath, int startPos);

Since: Added since v4.6.0.

Each call to this method can preload only one audio effect file into memory. To preload multiple audio effect files, call this method multiple times. After preloading, you can call playEffect to play the preloaded audio effect, or call playAllEffects to play all preloaded audio effects.

Note:

To ensure a smooth experience, the size of the audio effect file should not exceed the limit.
Agora recommends calling this method before joining a channel.
If preloadEffectEx is called before playEffectEx, then after playEffectEx is executed, the file resource will not be closed. The next call to playEffectEx will start playback from the beginning.
If preloadEffectEx is not called before playEffectEx, then after playEffectEx is executed, the file resource will be destroyed. The next call to playEffectEx will attempt to reopen the file and play from the beginning.

Scenario

This method applies to multi-channel scenarios.

Parameters

connection: Connection information. See RtcConnection.
soundId: Audio effect ID.
filePath: Absolute path of a local file or URL of an online file. Supported audio formats include: mp3, mp4, m4a, aac, 3gp, mkv, and wav.
startPos: Start position of the audio effect file in milliseconds.

Return Values

0: Success.
< 0: Failure.

preloadEffectEx [2/2]

Preloads the specified audio effect into the channel.

public abstract int preloadEffectEx(RtcConnection connection, int soundId, String filePath);

Since: Added since v4.6.0.

Each call to this method can preload only one audio effect file into memory. To preload multiple audio effect files, call this method multiple times. After preloading, you can call playEffect to play the preloaded audio effect, or call playAllEffects to play all preloaded audio effects.

Note:

To ensure a smooth experience, the size of the audio effect file should not exceed the limit.
Agora recommends calling this method before joining a channel.
If preloadEffectEx is called before playEffectEx, then after playEffectEx is executed, the file resource will not be closed. The next call to playEffectEx will start playback from the beginning.
If preloadEffectEx is not called before playEffectEx, then after playEffectEx is executed, the resource will be destroyed. The next call to playEffectEx will attempt to reopen the file and play from the beginning.

Scenario

This method is applicable to multi-channel scenarios.

Parameters

connection: Connection information. See RtcConnection.
soundId: Audio effect ID.
filePath: Absolute path of a local file or URL of an online file. Supported audio formats include: mp3, mp4, m4a, aac, 3gp, mkv, and wav.

Return Values

0: Success.
< 0: Failure.

resumeAllEffects

Resumes playback of all audio effect files.

public abstract int resumeAllEffects();

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

Timing

Call this method after pauseAllEffects.

Return Values

0: Success.
< 0: Failure.

resumeEffect

Resumes playback of the specified audio effect.

public abstract int resumeEffect(int soundId);

Parameters

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

Return Values

0: Success.
< 0: Failure.

setEffectPosition

Sets the playback position of the audio effect file.

public abstract int setEffectPosition(int soundId, int pos);

Note: Call this method after calling the playEffect method.

Parameters

soundId: The ID of the audio effect. Each audio effect file has a unique ID.
pos: The playback position of the audio effect file, in milliseconds.

Return Values

0: Success.
< 0: Failure.

setEffectsVolume

Sets the playback volume of audio effects.

public abstract int setEffectsVolume(double volume);

You must call this method after calling playEffect.

Timing

You must call this method after calling playEffect.

Parameters

volume: Playback volume. The range is [0, 100]. (Default: 100, representing original volume.)

Return Values

0: Success.
< 0: Failure.

setVolumeOfEffect

Sets the playback volume of the specified sound effect file.

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

Call this method after calling playEffect.

Timing

Call this method after calling playEffect.

Parameters

soundId: The ID of the sound effect. Each sound effect file has a unique ID.
volume: Playback volume. The range is [0, 100]. (Default is 100)

Return Values

0: Success.
< 0: Failure.

stopAllEffects

Stops playback of all audio effects.

public abstract int stopAllEffects();

If you only need to pause playback, call the pauseAllEffects method.

Timing

Call after the playEffect method.

Return Values

0: Success.
< 0: Failure.

stopEffect

Stops playback of the specified audio effect.

public abstract int stopEffect(int soundId);

If you only need to pause playback, call the pauseEffect method.

Timing

Call after playEffect.

Parameters

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

Return Values

0: Success.
< 0: Failure.

unloadEffect

Releases the specified preloaded audio effect file.

public abstract int unloadEffect(int soundId);

After calling preloadEffect to load the audio effect file into memory, you can call unloadEffect to release it.

Timing

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

Parameters

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

Return Values

0: Success.
< 0: Failure.

onAudioEffectFinished

Callback when local audio effect file finishes playing.

public void onAudioEffectFinished(int soundId) {}

Trigger Timing

This callback is triggered when the local audio effect file finishes playing.

Parameters

soundId: The unique ID of the audio effect file.