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:
- Before joining a channel, call the
getAudioEffectManager
method to get theIAudioEffectManager
class. - Call the
preloadEffect
method to preload the local audio effect file. - After joining a channel, call the
playEffect
method to play the audio effect file. After completing playing an audio effect file, the SDK triggers theonAudioEffectFinished
callback.
IAudioEffectManager
class.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.
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.
preloadEffect
before joining a channel.preloadEffect
, the audio effect file occupies memory until you call unloadEffect
or the user leaves the channel.
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.
playEffect
after joining a channel.
After successfully playing audio effect files, you can stop playing either a specified file or all audio effect files.
Pausing and resumption
When you play audio effect files, you can pause or resume playing either a specified file or all audio effect files.
playEffect
.
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.
getEffectDuration
after joining a channel, and call other methods in this group after playEffect
.
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.
playEffect
.
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.
/sdcard/
folder.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.
startAudioMixing
again when the SDK is playing a music file, the SDK automatically stops playing the previous music file and starts playing the next music file.
After successfully playing the music file, you can call stopAudioMixing
to stop the playback.
Pausing and resumption
When you play the music file, you can pause or resume playing the music file.
startAudioMixing
.
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.
startAudioMixing
and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY)
callback.
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.
startAudioMixing
and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY)
callback.
Playback speed
After successfully playing a music file, you can call setAudioMixingPlaybackSpeed
to set the playback speed of the current music file.
startAudioMixing
and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY)
callback.
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.
startAudioMixing
and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY)
callback.
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.
startAudioMixing
and receiving the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY)
callback.
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: