Introduction

In a call or live interactive streaming, you may need to play custom audio or music files to all the users in the channel. For example, adding sound effects in a game, or playing background music. We provide two groups of methods for playing audio effect files and audio mixing.

Before proceeding, ensure that you implement a basic call or live interactive streaming in your project. See Start a Voice Call and Start live interactive streaming for details.

Play audio effect files

The play audio effect methods can be used to play ambient sound, such as clapping and gunshots. You can play multiple audio effects at the same time, and preload audio effect files for efficiency.

The Agora Unity SDK provides the AudioEffectManagerImpl class to manage audio effects, including a series of methods. The audio effect file is specified by the file path, but the AudioEffectManagerImpl class uses the sound ID to identify the audio effect file. The SDK does not follow any rule to define the sound ID. Each audio effect file must have a unique sound ID, and you can do that by incrementing the ID and using hashCode for the audio effect files.

Implementation

Follow these steps to play audio effects:

  1. Call the GetAudioEffectManager method to get the AudioEffectManagerImpl class.
  2. Call the PreloadEffect method to preload the audio effect files.
  3. After joining a channel, call the PlayEffect method to play the audio effects. We do not recommend playing more than three audio effects at the same time.
Call the audio effect methods in the AudioEffectManagerImpl class.

The following figure shows the API call sequence. After playing the audio effects, you can pause the playback, set the volume, and remove the audio effects. See the sample code for details.

Sample code

// Initializes the AudioEffectManagerImpl class.
AudioEffectManagerImpl audioEffectManager = (AudioEffectManagerImpl)mRtcEngine.GetAudioEffectManager();
// Preloads audio effects, you can call this method multiple times to preload multiple audio effects.
int ret = audioEffectManager.PreloadEffect(nSoundID, filePath);
// Plays a specified audio effect.
int ret = audioEffectManager.PlayEffect(nSoundID, filePath, nLoopCount, dPitch, dPan, nGain, true);
// Pauses a specified audio effect.
int ret = audioEffectManager.PauseEffect(nSoundID);
// Pauses all audio effects.
int ret = audioEffectManager.PauseAllEffects();
// Resumes playing a specified audio effect.
int ret = audioEffectManager.ResumeEffect(nSoundID);
// Resumes playing all audio effects.
int ret = audioEffectManager.ResumeAllEffects();
// Stops playing a specified audio effect.
int ret = audioEffectManager.StopEffect(nSoundID);
// Stops playing all audio effects.
int ret = audioEffectManager.StopAllEffects();
// Releases a specified audio effect from the memory.
int ret = audioEffectManager.UnloadEffect(nSoundID);

API reference

Considerations

Preloading audio effects is not mandatory. However, we recommend preloading audio effects to improve efficiency or to play an audio effect multiple times. We do not recommend preloading audio effects with large file sizes.

Audio mixing

Audio mixing is playing a local or online music file while speaking, so that other users in the channel can hear the music. The audio mixing methods can be used to play background music, for example playing music in live interactive streaming. Only one music file can be played at one time. If you start playing a second music file during audio mixing, the first music file stops playing.
Agora audio mixing supports the following options:

  • Mix or replace the audio:
    • Mix the music file with the audio captured by the microphone and send it to other users
    • Replace the audio captured by the microphone with the music file.
  • Loop: Sets whether to loop the audio mixing file and the number of times to play the file.
  • State change notification: Reports when the state of the audio mixing file changes, for example when the audio mixing file pauses playback or resumes playback.

Implementation

string filePath = "http://www.hochmuth.com/mp3/Haydn_Cello_Concerto_D-1.mp3";
// Starts playing and mixing the music file.
int ret = mRtcEngine.StartAudioMixing(filePath, false, true, 1);
// Adjusts the volume of the music file as 50% of the original volume.
int ret = mRtcEngine.AdjustAudioMixingVolume(50);
// Gets the audio mixing volume for local playback.
int ret = mRtcEngine.GetAudioMixingPlayoutVolume();
// Gets the audio mixing volume for publishing.
int ret = mRtcEngine.GetAudioMixingPublishVolume();
// Gets the duration (ms) of the music file.
int ret = mRtcEngine.GetAudioMixingDuration();
// Gets the playback position (ms) of the music file.
int ret = mRtcEngine.GetAudioMixingCurrentPosition();
// Sets the playback position of the music file at 3000 ms.
int ret = mRtcEngine.SetAudioMixingPosition(3000);
// Stops playing and mixing the music file.
int ret = mRtcEngine.StopAudioMixing();

API reference

Considerations

Ensure that you call the methods when you are in the channel.