Real-time Audio
  • Platform
  • Framework / Engine
  • iOS
  • Android
  • macOS
  • Windows
  • Linux
  • Web
  • WeChat Mini Program

Audio Effect Player

Update Time:2021-05-07 20:28

1 Introduction

1.1 Application Scenarios

Audio effects mainly refer to short audio effects played to enhance the sense of reality or to enhance the atmosphere of the scene. For example: during the live broadcast, there are often scenes where audio effects are played, such as applause, gift audio effects, prompt audios, etc. In the game, sometimes it is necessary to play bullets, collision audios, etc.

ZegoExpress SDK provides a audio effect player, unified management of audio effects through ZegoEffectAudioPlayer, supports audio effect playback (multiple audio effects can be overlapped), playback control (such as pause playback, volume adjustment, set playback progress), preload audio effects and other functions.

1.2 Support Formats

The audio effect player supports playing MP3, MP4, WAV format files. If there is no audio data in the MP4 file, an error will be reported during playback.

2 Download the Sample Codes

Please refer to Sample Codes to get the sample codes.

For the relevant source code, please check the files in the "/ZegoExpressExample/AudioEffectPlayer" directory.

3 Prerequisites

Before implementing the "Audio Effect Player" functions, please make sure:

  • ZEGO Express SDK has been integrated in the project to realize basic real-time audio and video functions. For details, please refer to Quick Starts.
  • A project has been created in ZEGO Admin Console and a valid AppID and AppSign have been applied. For details, please refer to Console - Project Management.

4 Implementation Steps

4.1 Create a Audio Effect Player

Call the createAudioEffectPlayer method of ZegoExpressEngine to create an audio effect player instance.

The engine currently only supports the creation of one instance at the same time, and it will return null after exceeding.

ZegoAudioEffectPlayer audioEffectPlayer = ZegoExpressEngine.getEngine().createAudioEffectPlayer();

4.2 Play Control

4.2.1 (Optional) Set Event Callback for Audio Effect Player

Set Event Callback for Audio Effect Player

You can call the setEventHandler method of the audio effect player to set event callbacks for the player as needed, Used to monitor notifications such as "audio effect playback status change".

audioEffectPlayer.setEventHandler(new IZegoAudioEffectPlayerEventHandler() {
    @Override
    public void onAudioEffectPlayStateUpdate(ZegoAudioEffectPlayer audioEffectPlayer, int audioEffectID, ZegoAudioEffectPlayState state, int errorCode) {
                        Log.d("[ZEGO]", "onAudioEffectPlayStateUpdate errorCode:" + errorCode + "  audioEffectID:" + audioEffectID + "  state:" + state);
    }
});

4.2.2 Start Playing

Call start method to play audio effects, currently only supports 12 at the same time, and only It is a local file and does not support playing network resources. "AudioEffectID" needs to be globally unique.

  • If you have pre-loaded audio effects through the loadResource method, you only need Pass in the "audioEffectID" when preloading, and pass the "path" (path of the audio effect resource) field blank.

  • If you need to repeat by ZegoAudioEffectPlayConfig in "playCount" configure the number of repetitions. If it is set to "0", it means that the playback is repeated indefinitely, until the user manually calls stop to stop.

int audioEffectID = 1;
ZegoAudioEffectPlayConfig config = new ZegoAudioEffectPlayConfig();
config.playCount = 10;
config.isPublishOut = true;
audioEffectPlayer.start(audioEffectID,"/storage/emulated/0/Android/data/im.zego.express.example.video/files/3-s.mp3",config);   

4.2.3 Pause/Resume/Stop Playing

  1. Call pause method to pause the audio effect specified by "audioEffectID", call pauseAll method pauses all audio effects that are playing.

  2. After the audio effect is paused, call the resume method to resume the audio effect specified by "audioEffectID", call resumeAll method will resume all paused audio effects.

  3. Call stop method to stop playing the audio effect specified by "audioEffectID", call stopAll method will stop all audio effects.

audioEffectPlayer.pause(audioEffectID);
audioEffectPlayer.resume(audioEffectID);
audioEffectPlayer.stop(audioEffectID);
audioEffectPlayer.pauseAll();
audioEffectPlayer.resumeAll();
audioEffectPlayer.stopAll();

4.2.4 Adjust Volume

  1. Call setVolume method to set the audio effect volume specified by "audioEffectID", The value range is [0, 200] and the default value is "100".

  2. Call setVolumeAll method to set the volume of all audio effects at the same time, the value range is [0, 200] and the default value is "100".

int volume =70;
audioEffectPlayer.setVolume(audioEffectID, volume);

// Set the volume of all sound effects
audioEffectPlayer.setVolumeAll(volume);

4.2.5 Play Progress Control

  1. Call getTotalDuration method to get the total duration of a single audio effect.

  2. Call getCurrentProgress method to get the current playback progress of the audio effect.

  3. Call seekTo method to set the playback progress as needed.

// Get the total duration of the sound effect
long totalDuration = audioEffectPlayer.getTotalDuration(audioEffectID);
// Get the current playback progress of the sound effect
long progress = audioEffectPlayer.getCurrentProgress(audioEffectID);
// Set playback progress
audioEffectPlayer.seekTo(audioEffectID, 1, new IZegoAudioEffectPlayerSeekToCallback() {
    @Override
    public void onSeekToCallback(int errorCode) {
        Log.d("[ZEGO]", "onSeekToCallback errorCode:" + errorCode);
    }
});

4.3 (Optional) Preload Resources

Preload Resources

In scenarios where the same audio effect is frequently played, the SDK provides the function of preloading the audio effect file into the memory in order to optimize the performance of repeatedly reading and decoding the file.

Call loadResource method to load the audio effect resource, you can use "callback" Parameter to monitor the result of loading, display after successful loading, it can be played. It supports up to 15 local audio effect files to be preloaded at the same time (network resources are not supported), and the duration of a single audio effect file cannot exceed 30 seconds, otherwise an error will be reported when loading.

When the loaded audio effects are used, you can call the unloadResource interface to unload to release the related resources. Otherwise SDK will be ZegoAudioEffectPlayer automatically uninstalls audio loaded instance is released.

Preloading is an unnecessary operation. It is recommended to improve performance or to play a specific audio effect repeatedly.

// Load sound effect resources
audioEffectPlayer.loadResource(audioEffectID, "/storage/emulated/0/Android/data/im.zego.express.example.video/files/3-s.mp3", new IZegoAudioEffectPlayerLoadResourceCallback() {
    @Override
    public void onLoadResourceCallback(int i) {
        Log.d("[ZEGO]", "onLoadResourceCallback errorCode:" + i );

    }
});

// Uninstall sound effect resources
audioEffectPlayer.unloadResource(audioEffectID);

4.4 Destroy the Media Player

After using the audio effect player, you need to call the engine’s destroyAudioEffectPlayer method to destroy and release in time Resources occupied by this player.

engine.destroyAudioEffectPlayer(audioEffectPlayer);

5 API Reference

Method Description
createAudioEffectPlayer Create audio effect player instance.
setEventHandler Set audio effect player callback.
start Play audio.
pause Pause a single audio effect.
pauseAll Pause all audio effects.
resume Resume playing a single audio effect.
resumeAll Resume all audio effects.
stop Stop playing a single audio effect.
stopAll Stop all audio effects.
setVolume Adjust the audio effect volume.
setVolumeAll Adjust the volume of all audio effects.
getTotalDuration Control playback progress.
getCurrentProgress Get current playback progress.
seekTo Set the specified playback progress.
loadResource Preload resources.
unloadResource Unload resource.
destroyAudioEffectPlayer Destroy audio effect player instance.

6 FAQ

  1. What is the difference between a audio effect player and a media player?

    • The media player is mainly used to play videos and longer music, and supports the playback of network resources. At most 4 player instances can be created at the same time, and one instance can only play one audio and video resource.
    • The audio effect player is mainly used for audio resources with a short playing time, and does not support playing network resources. Only one audio effect player instance can be created at a time. The audio effect player supports concurrent playback of multiple audio resources. One instance can play up to 12 audio resources at the same time.