Audio Effect Player
Feature Overview
Audio effects mainly refer to short sound effects played to enhance realism or set the atmosphere of a scene. For example: during live streaming, there are often scenes for playing sound effects, such as applause, gift sound effects, prompt sounds, etc. In games, sometimes it is also necessary to play bullet sounds, collision impact sounds, etc.
The Audio Effect Player (ZegoAudioEffectPlayer) provided by ZEGO Express SDK uniformly manages audio effects, supports audio effect playing (multiple audio effects can be played at the same time), playback control (such as pausing playback, volume adjustment, setting playback progress), audio effect preloading, and other functions.
Supported Formats
The audio effect file player supports the following formats:
Audio Codec Formats:
- AAC, MP2, MP3, FLAC, WMA V1, WMA V2, PCM, AC3, EAC3
Container Formats:
- WAV, FLAC, MP3, MP4, MOV, MPEG-TS, FLV, Matroska (MKV), ASF
Example Source Code Download
Please refer to Download Example Source Code to get the source code.
For related source code, please check the files in the "/ZegoExpressExample/AdvancedAudioProcessing/src/main/java/im/zego/advancedaudioprocessing/audioeffectplayer" directory.
Prerequisites
Before implementing the audio effect player function, please ensure:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.
- You have integrated ZEGO Express SDK in your project and implemented basic audio and video publish and play stream functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
Usage Steps
1 Create audio effect player
Call the createAudioEffectPlayer method of ZegoExpressEngine to create an audio effect player instance.
The engine currently only supports creating one instance at the same time. Beyond that, null will be returned.
ZegoAudioEffectPlayer audioEffectPlayer = ZegoExpressEngine.getEngine().createAudioEffectPlayer();2 (Optional) Preload resources
In scenarios where the same audio effect is played frequently, in order to optimize the performance of repeatedly reading and decoding files, the SDK provides the function of preloading audio effect files into memory.
Call the loadResource method to load audio effect resources. You can listen to the loading result through the "callback" parameter and play it after the loading is successful. It supports preloading up to 15 local audio effect files at the same time (network resources are not supported), and the duration of a single audio effect file cannot exceed 30s, otherwise the loading will report an error.
When the loaded audio effect is used up, you can call the unloadResource interface to unload it to release related resources. Otherwise, the SDK will automatically unload the loaded audio effects when the ZegoAudioEffectPlayer instance is released.
Preloading is not a required operation. It is recommended to use it to improve performance or when you need to repeatedly play a specific audio effect.
// Load audio 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 );
}
});
// Unload audio effect resources
audioEffectPlayer.unloadResource(audioEffectID);3 Playback control
(Optional) Set event callback for audio effect player
You can call the setEventHandler method of the audio effect player as needed to set event callbacks for the player to listen to 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);
}
});Start playing
Call the start method to play audio effects. Currently, it only supports playing up to 12 audio effects at the same time, and can only be local files, not network resources. "audioEffectID" needs to be globally unique.
- If you have preloaded the audio effect through the loadResource method, you only need to pass in the "audioEffectID" during preloading, and pass in an empty string for the "path" (path of audio effect resources) field.
- If you need to repeat playback, you can configure the number of repetitions through "playCount" in ZegoAudioEffectPlayConfig. If set to "0", it means infinite loop playback 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);Pause/Resume/Stop playback
- Call the pause method to pause the audio effect specified by "audioEffectID", and call the pauseAll method to pause all playing audio effects.
- After the audio effect is paused, call the resume method to resume the audio effect specified by "audioEffectID", and call the resumeAll method to resume all paused audio effects.
- Call the stop method to stop the audio effect specified by "audioEffectID", and call the stopAll method to stop all audio effects.
audioEffectPlayer.pause(audioEffectID);
audioEffectPlayer.resume(audioEffectID);
audioEffectPlayer.stop(audioEffectID);
audioEffectPlayer.pauseAll();
audioEffectPlayer.resumeAll();
audioEffectPlayer.stopAll();Adjust volume
- Call the setVolume method to set the volume of the audio effect specified by "audioEffectID". The value range is [0, 200], and the default value is "100".
- Call the 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 audio effects
audioEffectPlayer.setVolumeAll(volume);Playback progress control
- Call the getTotalDuration method to get the total duration of a single audio effect.
- Call the getCurrentProgress method to get the current playback progress of the audio effect.
- Call the seekTo method to set the playback progress as needed.
// Get the total duration of the audio effect
long totalDuration = audioEffectPlayer.getTotalDuration(audioEffectID);
// Get the current playback progress of the audio 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 Destroy audio effect player
After using the audio effect player, you need to call the destroyAudioEffectPlayer method in time to destroy it and release the resources occupied by the player.
engine.destroyAudioEffectPlayer(audioEffectPlayer);FAQ
- What is the difference between audio effect player and media player?
| Player Type | Difference |
|---|---|
Media Player | Mainly used for playing videos and longer music, supports playing network resources. At the same time, it supports creating up to 4 player instances, and one instance can only play one audio or video. |
| Audio Effect Player | Mainly used for playing short sound effects, does not support playing network resources. At the same time, it only supports creating one audio effect player instance. The audio effect player supports concurrent playback of multiple audio effects, and one instance can play up to 12 audio effects at the same time. |