Play Audio Effect or Music File

Introduction

During real-time audio and video interaction, for better atmosphere or entertainment, users often need to play audio effects or background music and make all users in the channel hear them. For example, users might add fighting sounds when playing an action game or include an accompaniment when singing. Agora provides two independent groups of methods so that you can play audio effect files and a music file separately.

Sample project

Agora provides an open-source demo project on GitHub that implements playing audio effect files and a music file. You can view the source code on Github or download the project to try it out.

Audio effect files

In this context, the audio effects are ambient sounds with a short duration, such as applause, cheers, fighting sounds, and gunshots. Usually, you can play multiple audio effects at the same time.

Agora provides a group of methods to play and manage audio effect files. Supported functions include the following:

• Play local or online audio effect files.
• Set the spatial position, number of loops, playback position, volume, and other playback options of an audio effect.
• Flexibly control the playing, pausing, resumption, and stopping of audio effect files, individually or globally.

To play audio effect files, see the following steps:

1. Before joining a channel, call the getAudioEffectManager method to get the IAudioEffectManager class.
2. Call the preloadEffect method to preload the local audio effect file.
3. After joining a channel, call the playEffect method to play the audio effect file. After completing playing an audio effect file, the SDK triggers the onAudioEffectFinished callback.

Getting the audio manager class

The Agora SDK provides the IAudioEffectManager class to manage audio effect files. Before playing an audio effect file, you need to get the IAudioEffectManager class.

// Imports the IAudioEffectManager class.
import io.agora.rtc.IAudioEffectManager;

// Calls getAudioEffectManager to get the IAudioEffectManager class.
private IAudioEffectManager audioEffectManager;
audioEffectManager = engine.getAudioEffectManager();

Specifying an audio effect file

Before playing an audio effect file, you need to set filePath and soundId to specify the audio effect file. The representing of two parameters is as follows:

• filePath: The audio effect file path, including the local and online file path. The SDK searches for audio effect files in this path.
• soundId: The audio effect ID, which you define. This ID must be unique. The SDK identifies an audio effect file based on its audio effect ID. Common solutions for defining audio effect IDs include incrementing the ID and using hashCode for the audio effect file name.

Preloading

The SDK supports preloading audio effect files. To improve performance, you can add the audio effect files into the memory in advance. Preloading is not required. Agora recommends that you choose whether to preload audio effect files according to your needs.

• If you need to play a specified audio effect repeatedly, Agora recommends preloading the audio effect file.
• If an audio effect file size is large, Agora recommends not preloading the audio effect file.

To preload multiple audio effect files, you need to call preloadEffect multiple times.

// Sets the audio effect ID.
int id = 0;
// Preloads the specified local audio effect file into the memory.
audioEffectManager.preloadEffect(id++, "your file path");

// Unloads the preloaded audio effect file. 
audioEffectManager.unloadEffect(id);

Playing and stopping

Call playEffect to play the audio effect file. You can call playEffect multiple times to play multiple audio effect files at the same time according to your requirements. When playing an audio effect file, you can set the playback options, such as number of loops, pitch, volume, and playback position.

// Starts to play the audio effect file.
audioEffectManager.playEffect(
  0,  // Sets the audio effect ID.
  "your file path",  // Sets the path of the audio effect file.
  -1,  // Sets the number of times the audio effect loops. -1 represents an infinite loop.  
  1,  // Sets the pitch of the audio effect. The value range is 0.5 to 2.0, where 1.0 is the original pitch.  
  0.0,  // Sets the spatial position of the audio effect. The value range is -1.0 to 1.0.  -1.0 represents the audio effect occurs on the left; 0 represents the audio effect occurs in the front; 1.0 represents the audio effect occurs on the right. 
  100,  // Sets the volume of the audio effect. The value range is 0 to 100. 100 represents the original volume.  
  true,  // Sets whether to publish the audio effect to the remote users. true represents that both the local user and remote users can hear the audio effect; false represents that only the local user can hear the audio effect.  
  0  // Sets the playback position (ms) of the audio effect file. 0 represents that the playback starts at the 0 ms mark of the audio effect file.
);

// Occurs when the local audio effect playback finishes.  
@Override
public void onAudioEffectFinished(int soundId) {
    super.onAudioEffectFinished(soundId);
}

After successfully playing audio effect files, you can stop playing either a specified file or all audio effect files.

// Stops playing a specified audio effect file. 
audioEffectManager.stopEffect(id);

// Stops playing all audio effect files. 
audioEffectManager.stopAllEffects();

Pausing and resumption

When you play audio effect files, you can pause or resume playing either a specified file or all audio effect files.

// Pauses playing a specified audio effect file.  
audioEffectManager.pauseEffect(id);

// Pauses playing all audio effect files. 
audioEffectManager.pauseAllEffects();

// Resumes playing a specified audio effect file.  
audioEffectManager.resumeEffect(id);

// Resumes playing all audio effect files. 
audioEffectManager.resumeAllEffects();

Playback position

If you need to adjust the playback position after playing the audio effect file, you can call this group of methods. For example, you can call this group of methods to adjust the playback position during looped playback of the audio effect file without stopping the playback.

// Gets the total duration of a specified local audio effect file.  
audioEffectManager.getEffectDuration("your file path");

// Sets the playback position (ms) of a specified local audio effect file. 500 represents that the playback starts at the 500 ms mark of the audio effect file.  
audioEffectManager.setEffectPosition(id, 500);

// Gets the current playback position of a specified local audio effect file.  
audioEffectManager.getEffectCurrentPosition(id);

Volume

After the audio effect file starts to play, you can call this group of methods to adjust the playback volume. For example, you can call this group of methods to adjust the playback volume during looped playback of the audio effect file without stopping the playback.

 // Sets the playback volume of all audio effect files. The value range is 0 to 100. 100 represents the original volume.  
audioEffectManager.setEffectsVolume(50.0);

// Sets the playback volume of a specified audio effect file. The value range is 0 to 100. 100 represents the original volume.  
audioEffectManager.setVolumeOfEffect(id, 50.0);

// Gets the playback volume of all audio effect files. The volume range is 0 to 100.  100 represents the original volume.  
audioEffectManager.getEffectsVolume();

API reference

• preloadEffect
• unloadEffect
• playEffect
• stopEffect
• stopAllEffects
• pauseEffect
• pauseAllEffects
• resumeEffect
• resumeAllEffects
• getEffectDuration
• setEffectPosition
• getEffectCurrentPosition
• setEffectsVolume
• setVolumeOfEffect
• getEffectsVolume
• onAudioEffectFinished

Audio mixing

Audio mixing means mixing a music file with the audio captured by a microphone. Users who use the audio mixing function often play a relatively long music file and only play one music file at a time. For example, users can play accompaniment when singing or play background music when chatting.

Agora provides a group of methods to play and manage the music file. Supported functions include the following:

• Play the local or online music file.
• Set the number of playbacks , playback position, volume, pitch, and other playback options of a music file.
• Flexibly control the playing, pausing, resumption, and stopping of the music file.
• Report the current playback state of the music file and the reason for the change.

After successfully calling startAudioMixing, the SDK triggers the onAudioMixingStateChanged callback when the playback state of the music file changes.

Playing and stopping

Call startAudioMixing to play a music file. When playing a music file, you can set the playback options, such as number of loops and playback position.

// Starts to play the music file.
engine.startAudioMixing(
  "your file path",  // Specifies the absolute path of the local or online music file that you want to play.  
  false,  // Sets whether to only play a music file on the local client. true represents that only the local user can hear the music; false represents that both the local user and remote users can hear the music.
  false,  // Sets whether to replace the audio captured by the microphone with a music file. true represents that the user can only hear music; false represents that the user can hear both the music and the audio captured by the microphone. 
  -1,  // Sets the number of times to play the music file. 1 represents play the file once.
  0  // Sets the playback position (ms) of the music file. 0 represents that the playback starts at the 0 ms mark of the music file.
);

// Occurs when the state of the local user's music file changes.  
@Override
public void onAudioMixingStateChanged(int state, int reason) {
    super.onAudioMixingStateChanged(state, reason);
}

After successfully playing the music file, you can call stopAudioMixing to stop the playback.

// Stops playing the music file. 
engine.stopAudioMixing();

Pausing and resumption

When you play the music file, you can pause or resume playing the music file.

// Pauses playing the music file.  
engine.pauseAudioMixing();

// Resumes playing the music file.  
engine.resumeAudioMixing();

Playback position

When the music file is playing, you can call this group of methods to adjust the playback position of the music file without stopping the playback.

// Gets the total duration of the current music file.  
engine.getAudioMixingDuration();

// Sets the playback position (ms) of the current music file. 500 represents that the playback starts at the 500 ms mark of the music file.  
engine.setAudioMixingPosition(500);

// Gets the current playback position of the music file.  
engine.getAudioMixingCurrentPosition();

Volume and pitch

After successfully playing the music file, you can call this group of methods to adjust the playback volume and pitch of the music file without stopping the playback.

// Adjusts the playback volume of the current music file for both local and remote playback. The value range is 0 to 100. 100 represents the original volume.  
engine.adjustAudioMixingVolume(50); 

// Adjusts the playback volume of the current music file for the remote playback. The value range is 0 to 100. 100 represents the original volume.  
engine.adjustAudioMixingPublishVolume(50); 

// Adjusts the playback volume of the current music file for the local playback. The value range is 0 to 100. 100 represents the original volume.  
engine.adjustAudioMixingPlayoutVolume(50); 

// Gets the playback volume of the current music file for the local playback. The volume range is 0 to 100. 100 represents the original volume.  
engine.getAudioMixingPlayoutVolume(); 

// Gets the playback volume of the current music file for the remote playback. The volume range is 0 to 100. 100 represents the original volume.  
engine.getAudioMixingPublishVolume(); 

// Sets the pitch of the current music file. The value range is -12 to 12. 0 represents the original pitch; 1 represents raising the original pitch by a semitone. 
engine.setAudioMixingPitch(5);

Playback speed

After successfully playing a music file, you can call setAudioMixingPlaybackSpeed to set the playback speed of the current music file.

// Agora recommends that you limit this value to between 50 and 400.
// 50 represents half the original speed, 100 represents the original speed, and 400 represents 4 times the original speed.
engine.setAudioMixingPlaybackSpeed(50);

Playback track

After successfully playing a music file, you can call this group of methods to set the playback track of the current music file.

// Gets the number of audio tracks of the current music file.
engine.getAudioTrackCount();
// Specifies the playback track of the current music file.
// The range of index is [0, getAudioTrackCount()).
engine.selectAudioTrack(2);

Playback channel mode

After successfully playing a music file, you can call setAudioMixingDualMonoMode to set the following channel mode of the current music file:

• AUDIO_MIXING_DUAL_MONO_AUTO: Original mode.
• AUDIO_MIXING_DUAL_MONO_L: Left channel mode. This mode replaces the audio of the right channel with the audio of the left channel, which means the user can only hear the audio of the left channel.
• AUDIO_MIXING_DUAL_MONO_R: Right channel mode. This mode replaces the audio of the left channel with the audio of the right channel, which means the user can only hear the audio of the right channel.
• AUDIO_MIXING_DUAL_MONO_MIX: Mixed channel mode. This mode mixes the audio of the left channel and the right channel, which means the user can hear the audio of the left channel and the right channel at the same time.

engine.setAudioMixingDualMonoMode(AUDIO_MIXING_DUAL_MONO_AUTO);

API reference

• startAudioMixing
• stopAudioMixng
• pauseAudioMixing
• resumeAudioMixing
• getAudioMixingDuration
• setAudioMixingPosition
• getAudioMixingCurrentPosition
• adjustAudioMixingVolume
• adjustAudioMixingPublishVolume
• adjustAudioMixingPlayoutVolume
• getAudioMixingPlayoutVolume
• getAudioMixingPublishVolume
• setAudioMixingPitch
• setAudioMixingPlaybackSpeed
• getAudioTrackCount
• selectAudioTrack
• setAudioMixingDualMonoMode
• onAudioMixingStateChanged

Reference

When playing a music file, you can also refer to the following articles:

• Why can't I play the background music using startAudioMixing on Android 10?
• What formats of audio files does the Agora RTC SDK support?