Audio Effect Player
Function Overview
Application Scenarios
Audio effects mainly 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 it is necessary to play bullet sounds, collision impact sounds, etc.
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), preloading audio effects, and other functions.
This feature is not supported in WebGL environments.
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 Example Source Code
Please refer to Download Example Source Code to get the source code.
For related source code, please view files in the "/ZegoExpressExample/Examples/AdvancedAudioProcessing" directory.
Prerequisites
Before implementing the audio effect player function, please ensure:
- You have created a project in ZEGOCLOUD Console and applied for valid AppID and AppSign. For details, please refer to Console - Project Information.
- You have integrated ZEGO Express SDK in the project and implemented basic audio and video streaming functions. 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 a time. If exceeded, it will return null.
ZegoAudioEffectPlayer audioEffectPlayer = engine.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 function to preload audio effect files into memory.
Call the LoadResource method to load audio effect resources. You can monitor the loading result through the "callback" parameter, and display it only after loading is successful.
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 no longer needed, 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 mandatory. It is recommended when improving performance or needing to repeatedly play a specific audio effect.
// Load audio effect resources
audioEffectPlayer.LoadResource(audioEffectID, "path", (int errorCode)=>{
});
// Unload audio effect resources
audioEffectPlayer.UnloadResource(audioEffectID);3 Playback control
(Optional) Set event callbacks for audio effect player
You can set event callbacks for the player by listening to the OnAudioEffectPlayStateUpdate method of the audio effect player as needed to monitor notifications such as "audio effect playback state change".
public void OnAudioEffectPlayStateUpdate(ZegoAudioEffectPlayer audioEffectPlayer, uint audioEffectID, ZegoAudioEffectPlayState state, int errorCode) {
}Start playback
Call the Start method to play audio effects. Currently only supports playing 12 audio effects at the same time, and only local files are supported. Network resources are not supported.
- If the audio effect has been preloaded through the LoadResource method, you only need to pass in the "audioEffectID" during preloading, and the "path" (path of the audio effect resource) field can be left empty.
audioEffectID needs to remain globally unique.
- 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.
uint audioEffectID = 1;
ZegoAudioEffectPlayConfig playConfig = new ZegoAudioEffectPlayConfig();
config.playCount = 10;
config.isPublishOut = true;
audioEffectPlayer.Start(audioEffectID,"path",playConfig);Pause/Resume/Stop playback
- Pause playback: Call the Pause method to pause the audio effect specified by "audioEffectID". Call the PauseAll method to pause all currently playing audio effects.
- Resume playback: After the audio effect is paused, call the Resume method to resume playback of the audio effect specified by "audioEffectID". Call the ResumeAll method to resume all paused audio effects.
- Stop playback: Call the Stop method to stop the audio effect specified by "audioEffectID". Call the StopAll method to stop playing 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
ulong totalDuration = audioEffectPlayer.GetTotalDuration(audioEffectID);
// Get the current playback progress of the audio effect
ulong progress = audioEffectPlayer.GetCurrentProgress(audioEffectID);
// Set playback progress
audioEffectPlayer.SeekTo(audioEffectID, 1, (int errorCode)=>{
});4 Destroy media 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 an audio effect player and a media player?
| Player Type | Difference |
|---|---|
Media Player | Mainly used for playing videos and longer music, supports playing network resources. At the same time, supports creating up to 4 player instances, and one instance can only play one audio or video. |
| Audio Effect Player | Mainly used for playing shorter sound effects, does not support playing network resources. At the same time, only supports creating one audio effect player instance. The audio effect player supports multi-channel audio effect concurrent playback, and one instance can play up to 12 audio effects at the same time. |