Media Playback

Audio Mixing

adjustAudioMixingPlayoutVolume

Adjusts the local playback volume of the audio mixing.

public abstract int adjustAudioMixingPlayoutVolume(int volume);

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Timing

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume

The local playback volume of the audio mixing. The value range is [0, 100]. (Default is 100)

0: Mute.
100: Original volume.

Return Values

0: Success.
< 0: Failure.

adjustAudioMixingPublishVolume

Adjusts the audio mixing volume for publishing.

public abstract int adjustAudioMixingPublishVolume(int volume);

This method adjusts the audio mixing volume sent to other users.

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

volume: The audio mixing volume for publishing. The value range is [0, 100], with a default of 100, which means the original volume.

Return Values

0: Success.
< 0: Failure.

adjustAudioMixingVolume

Adjusts the volume during audio mixing.

public abstract int adjustAudioMixingVolume(int volume);

This method adjusts the audio mixing volume on both the local and remote clients.

Note: adjustAudioMixingVolume does not affect the volume of sound effects set by the playEffect method.

Timing

Call this method after calling startAudioMixing.

Parameters

volume: The audio mixing volume. The value range is [0, 100]. (Default is 100, which means the original volume.)

Return Values

0: Success.
< 0: Failure.

getAudioMixingCurrentPosition

Gets the current playback position of the audio mixing (milliseconds).

public abstract int getAudioMixingCurrentPosition();

Note:

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.
If you need to call getAudioMixingCurrentPosition multiple times, ensure the interval between calls is greater than 500 milliseconds.

Return Values

On success, returns the current playback position of the audio mixing (milliseconds). 0 means the music file has not started playing.
< 0: Failure.

getAudioMixingDuration

Gets the duration of the audio mixing file (milliseconds).

public abstract int getAudioMixingDuration();

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

On success, returns the duration of the audio mixing (milliseconds).
< 0: Failure.

getAudioMixingPlayoutVolume

Gets the local playback volume of the audio mixing.

public abstract int getAudioMixingPlayoutVolume();

You can call this method to get the local playback volume of the audio mixing file, which helps troubleshoot volume-related issues.

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

On success, returns the audio mixing volume in the range [0, 100].
On failure, returns an error code less than 0.

getAudioMixingPublishVolume

Gets the audio mixing volume for publishing.

public abstract int getAudioMixingPublishVolume();

This method helps troubleshoot audio volume-related issues.

Note: You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

≥ 0: Success. Returns the audio mixing volume in the range [0, 100].
< 0: Failure.

getAudioTrackCount

Gets the audio track index of the current music file.

public abstract int getAudioTrackCount();

Note: You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Return Values

On success, returns the audio track index.
< 0: Failure.

pauseAudioMixing

Pauses the playback and audio mixing of the music file.

public abstract int pauseAudioMixing();

After calling startAudioMixing to play a music file, you can call this method to pause the playback. To stop playback, call stopAudioMixing.

Timing

Call this method after joining a channel.

Return Values

0: Success.
< 0: Failure.

resumeAudioMixing

Resumes the playback and audio mixing of the music file.

public abstract int resumeAudioMixing();

After calling pauseAudioMixing, you can call resumeAudioMixing to resume playback.

Timing

Call this method after joining a channel.

Return Values

0: Success.
< 0: Failure.

selectAudioTrack

Selects the audio track to use during playback.

public abstract int selectAudioTrack(int audioIndex);

After getting the audio track index of the file, you can call this method to specify any track for playback. For example, if different tracks of a multi-track file store songs in different languages, you can use this method to select the playback language.

Note:

For supported audio file formats, see [What audio file formats are supported by Agora RTC SDK](https://doc.shengwang.cn/faq/general-product-inquiry/audio-format).
You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

audioIndex: The index of the audio track you want to specify. This value must be greater than 0 and less than the value returned by getAudioTrackCount.

Return Values

0: Success.
< 0: Failure.

selectMultiAudioTrack

Selects the audio tracks to play locally and to publish to the channel.

int selectMultiAudioTrack(int playoutTrackIndex, int publishTrackIndex);

Before calling this method, you need to open the media file using openWithMediaSource and set enableMultiAudioTrack to true in MediaPlayerSource.

Scenario

This method is suitable for scenarios such as KTV: the host can choose to play the original vocal track locally while publishing the accompaniment track to the channel.

Parameters

playoutTrackIndex: The index of the audio track for local playback. You can obtain this index via getStreamInfo.
publishTrackIndex: The index of the audio track to publish to the channel. You can obtain this index via getStreamInfo.

Return Values

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

setAudioMixingDualMonoMode

Sets the channel mode of the current audio file.

public abstract int setAudioMixingDualMonoMode(Constants.AudioMixingDualMonoMode mode);

You can set the channel mode of the audio file to original, left, right, or mixed mode as needed. For example, in a KTV scenario, the left channel stores accompaniment and the right channel stores the original vocals. You can set it based on your needs:

To hear only the accompaniment, set the channel mode to left.
To hear both accompaniment and vocals, set the channel mode to mixed.

Note: This method only applies to stereo audio files.

Scenario

In KTV scenarios, the left channel of a music file stores the accompaniment, and the right channel stores the original vocals. You can set it according to your needs:

If you only want to hear the accompaniment, call this method and set the channel mode to left channel.
If you want to hear both the accompaniment and the original vocals, call this method and set the channel mode to mixed mode.

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

mode: Channel mode. See AudioMixingDualMonoMode.

Return Values

0: Success.
< 0: Failure.

setAudioMixingPitch

Sets the pitch of the local music file.

public abstract int setAudioMixingPitch(int pitch);

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Timing

You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback.

Parameters

pitch: Sets the pitch of the local music file in semitones (default is 0). The value range is [-12, 12], where each increment or decrement represents one semitone. The greater the absolute value, the more noticeable the pitch change.

Return Values

0: Success.
< 0: Failure.

setAudioMixingPlaybackSpeed

Sets the playback speed of the current audio file.

public abstract int setAudioMixingPlaybackSpeed(int speed);

Make sure to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged callback with the state AUDIO_MIXING_STATE_PLAYING.

Parameters

speed

Playback speed. Recommended values are between 50 and 400, defined as:

50: Half the original speed.
100: Original speed.
400: Four times the original speed.

Return Values

0: Success.
< 0: Failure.

setAudioMixingPosition

Sets the playback position of the audio mixing.

public abstract int setAudioMixingPosition(int pos);

Timing

Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged callback.

Parameters

pos: The playback position in milliseconds.

Return Values

0: Success.
< 0: Failure.

startAudioMixing [1/2]

Starts playing a music file.

public abstract int startAudioMixing(String filePath, boolean loopback, int cycle);

Deprecated: This method is deprecated. Use startAudioMixing [2/2] instead.

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

Note:

If you use this method to play short sound effect files, playback may fail. It is recommended to use playEffect for such files.
If you need to call this method multiple times, ensure that the interval between each call is greater than 500 ms.
On Android, note the following:
- The Android device must be version v4.2 or later, and the API version must be v16 or later.
- If you need to play online music files, it is not recommended to use redirected URLs. Some Android devices may not be able to open redirected URLs.
- If you call this method on an emulator, ensure that the music file is located in the /sdcard/ directory and is in MP3 format.

Timing

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

Related Callbacks

After successfully calling this method, the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback is triggered. When the audio mixing file finishes playing, the SDK triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_STOPPED) callback on the local client.

Parameters

filePath

Note: If you have preloaded the sound effect into memory using preloadEffect, make sure the value of this parameter is the same as the filePath parameter in preloadEffect.

The file path. Supports the following types:

URI addresses that start with content://
Paths that start with /assets/
URLs
Absolute path of local files, including the file name and extension

Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP.

loopback

Whether to play the music file only on the local client:

true: Local playback only. Only the local user can hear the music.
false: Publish to remote. Remote users can also hear the music.

cycle

The number of times the music file is played:

> 0: Play the specified number of times. For example, 1 means play once.
-1: Play in an infinite loop.

Return Values

0: Success.
< 0: Failure.
- -1: A general error occurs (no specific reason).
- -2: Invalid parameter.
- -3: SDK not ready:
  - The audio module is not enabled.
  - The process is not completed.
  - RtcEngine initialization failed. Please reinitialize RtcEngine.

startAudioMixing [2/2]

Starts playing a music file.

public abstract int startAudioMixing(String filePath, boolean loopback, int cycle, int startPos);

This method supports playing URI files starting with content://. If the local music file does not exist, the SDK does not support the file format, or the music file URL is inaccessible, the SDK returns AUDIO_MIXING_REASON_CAN_NOT_OPEN.

Note:

If you call this method to play a short sound effect file, it may fail. Agora recommends using the playEffect method to play such files.
If you need to call this method multiple times, ensure that the interval between calls is greater than 500 ms.
On Android, note the following:
- The device must run Android v4.2 or later and API level v16 or higher.
- When playing online music files, Agora does not recommend using redirected URLs, as some Android devices may not support them.
- If calling this method on an emulator, ensure that the music file is located in the /sdcard/ directory and is in MP3 format.

Timing

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

Related Callbacks

Successfully calling this method triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) callback. When the audio mixing file finishes playing, the SDK triggers the onAudioMixingStateChanged (AUDIO_MIXING_STATE_STOPPED) callback locally.

Parameters

filePath

The file path. The path must include the file name and extension. Supports URL, absolute path, or paths starting with /assets/. Accessing local files using absolute paths may cause permission issues. Agora recommends using URI, for example: content://com.android.providers.media.documents/document/audio%3A14441.

loopback

Whether to play the music file only locally:

true: Play locally only. Only the local user hears the music.
false: Publish the music to remote users as well.

cycle

Number of times to play the music file:

> 0: Play the specified number of times. For example, 1 means play once.
-1: Loop indefinitely.

startPos

The starting position (in milliseconds) for playing the music file.

Return Values

0: Success.
< 0: Failure.
- -1: General error (unspecified reason).
- -2: Invalid parameter.
- -3: SDK not ready:
  - Audio module not enabled.
  - Incomplete setup.
  - RtcEngine initialization failed. Please reinitialize RtcEngine.

stopAudioMixing

Stops playing the music file.

public abstract int stopAudioMixing();

After calling startAudioMixing to play a music file, you can call this method to stop playback. If you only want to pause playback, call pauseAudioMixing instead.

Timing

Call this method after joining a channel.

Return Values

0: Success.
< 0: Failure.

onAudioMixingFinished

Callback for when local music file playback ends.

public void onAudioMixingFinished()

Deprecated: This method is deprecated. Use onAudioMixingStateChanged instead.

After calling startAudioMixing to play a local music file, this callback is triggered when playback ends. If startAudioMixing fails, it returns the error code WARN_AUDIO_MIXING_OPEN_ERROR.

Trigger Timing

This callback is triggered when the local music file playback ends.

onAudioMixingPositionChanged

Callback for music file playback progress.

public void onAudioMixingPositionChanged(long position)

After calling the startAudioMixing method to play a music file, the SDK triggers this callback every two seconds to report the playback progress of the music file.

Trigger Timing

This callback is triggered every two seconds after calling startAudioMixing to play the music file.

Parameters

position: Playback progress in milliseconds.

onAudioMixingStateChanged

Callback for changes in music file playback state.

public void onAudioMixingStateChanged(int state, int reason)

This callback reports the current playback state and error code of the music file.

Trigger Timing

This callback is triggered when the playback state of the music file changes.

Parameters

state

The playback state of the music file:

AUDIO_MIXING_STATE_PLAYING (710): The music file is playing.
AUDIO_MIXING_STATE_PAUSED (711): The music file is paused.
AUDIO_MIXING_STATE_STOPPED (713): The music file is stopped.
AUDIO_MIXING_STATE_FAILED (714): An error occurred while playing the music file. The SDK returns the specific reason via the reason parameter.

reason

Error code:

AUDIO_MIXING_REASON_OK (0): No error.
AUDIO_MIXING_REASON_CAN_NOT_OPEN (701): The SDK cannot open the music file.
AUDIO_MIXING_REASON_TOO_FREQUENT_CALL (702): The SDK is opening the music file too frequently.
AUDIO_MIXING_REASON_INTERRUPTED_EOF (703): The music file playback is interrupted.
AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED (721): One loop of the music file playback is completed.
AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED (723): All loops of the music file playback are completed.
AUDIO_MIXING_REASON_STOPPED_BY_USER (724): The music file playback is stopped by calling stopAudioMixing.

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.

pauseAllEffects

Pauses all sound effects.

public abstract int pauseAllEffects();

Return Values

0: Success.
< 0: Failure.

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.

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.