Audio Effect Player
Feature Overview
This document does not apply to the Web platform.
Audio effects refer to short sound effects played to enhance realism or set the atmosphere. For example: During live streaming, there are often scenarios for playing sound effects, such as applause, gift sound effects, notification sounds, etc. In games, sometimes bullet sounds, collision sounds, etc. also need to be played.
ZEGO Express SDK provides an audio effect player (ZegoAudioEffectPlayer) to uniformly manage audio effects, supporting audio effect playback (multiple audio effects can be played simultaneously), playback control (such as pause, volume adjustment, setting playback progress), and preloading audio effects.
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
Download Sample Source Code
Please refer to Download Sample Source Code to get the source code.
For related source code, please check files in the "lib/topics/AudioAdvanced/audio_effect_player" directory.
Prerequisites
Before implementing the audio effect player feature, ensure:
- You have integrated ZEGO Express SDK in your project and implemented basic real-time audio and video features. For details, please refer to Quick Start - Integrating SDK and Quick Start - Implementing Video Call.
- 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.
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 a time. Exceeding this limit will return null.
var audioEffectPlayer = await ZegoExpressEngine.instance.createAudioEffectPlayer();2 (Optional) Preload Resources
In scenarios where the same audio effect is played frequently, to optimize the performance of repeated file reading and decoding, the SDK provides the feature to preload 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 only after loading is successful. It supports preloading up to 12 local audio effect files at the same time (network resources are not supported), and the duration of a single audio effect file cannot exceed 30 seconds, otherwise loading will fail.
When the loaded audio effect is no longer needed, you can call the unloadResource method to unload it and release related resources. Otherwise, the SDK will automatically unload loaded audio effects when the ZegoAudioEffectPlayer instance is released.
Preloading is optional. It is recommended to improve performance or when a specific audio effect needs to be played repeatedly.
// Load audio effect resource
audioEffectPlayer?.loadResource(audioEffectID, "/storage/emulated/0/Android/data/im.zego.express.example.video/files/3-s.mp3").then((ZegoAudioEffectPlayerLoadResourceResult result) {
});
// Unload audio effect resource
audioEffectPlayer?.unloadResource(audioEffectID);3 Playback Control
(Optional) Set Event Callback for Audio Effect Player
You can implement the ZegoExpressEngine.onAudioEffectPlayStateUpdate callback to listen for notifications of "audio effect playback state changes".
ZegoExpressEngine.onAudioEffectPlayStateUpdate = (ZegoAudioEffectPlayer audioEffectPlayer, int audioEffectID, ZegoAudioEffectPlayState state, int errorCode) {
};Start Playback
Call the start method to play audio effects. Currently, it supports playing up to 12 audio effects simultaneously, and only local files are supported. Network resources are not supported. The "audioEffectID" must be globally unique.
- If the audio effect has been preloaded through the loadResource method, you only need to pass the "audioEffectID" from preloading, and the "path" (path to the audio effect resource) field can be left empty.
- If you need to repeat playback, you can configure the number of repetitions through "playCount" in ZegoAudioEffectPlayConfig. If set to "0", it means infinite repeat playback until the user manually calls stop to stop.
int audioEffectID = 1;
int playCount = 10;
bool isPublishOut = true;
var config = ZegoAudioEffectPlayConfig(playCount, isPublishOut);
audioEffectPlayer?.start(audioEffectID, path: "/storage/emulated/0/Android/data/im.zego.express.example.video/files/3-s.mp3", config: config);Pause/Resume/Stop Playback
- Call the pause method to pause the audio effect specified by "audioEffectID". Call the pauseAll method to pause all currently playing audio effects.
- After pausing audio effect playback, call the resume method to resume playback of the audio effect specified by "audioEffectID". Call the resumeAll method to resume all paused audio effects.
- Call the stop method to stop the audio effect specified by "audioEffectID". 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 simultaneously. The value range is [0, 200], and the default value is "100".
int volume =70;
audioEffectPlayer?.setVolume(audioEffectID, volume);
// Set volume for 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 total duration of audio effect
var totalDuration = await audioEffectPlayer?.getTotalDuration(audioEffectID);
// Get current playback progress of audio effect
var progress = await audioEffectPlayer?.getCurrentProgress(audioEffectID);
// Set playback progress
audioEffectPlayer?.seekTo(audioEffectID, 1).then((ZegoAudioEffectPlayerSeekToResult result) {
});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 most 4 player instances can be created at the same time, and one instance can only play one audio or video. |
| Audio Effect Player | Mainly used for playing shorter audio effects, does not support playing network resources. Only one audio effect player instance can be created at the same time. The audio effect player supports concurrent playback of multiple audio effects, and one instance can play up to 12 audio effects simultaneously. |