Audio Effect Player
Feature Overview
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, prompt tones, etc. In games, sometimes it is necessary to play bullet sounds, collision impact sounds, etc.
The audio effect player (ZegoAudioEffectPlayer) provided by ZEGO Express SDK uniformly manages audio effects on media streams, supporting audio effect playback (multiple audio effects can be played simultaneously), playback control (such as pause 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
The address of online audio files needs to comply with the browser's same-origin policy.
Prerequisites
Before implementing the audio effect player feature, please ensure:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and Server address. For details, please refer to Console - Project Information.
- You have integrated ZEGO Express SDK in your project and implemented basic audio and video stream publishing and playing 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.
Each media stream object only supports creating one ZegoAudioEffectPlayer instance at the same time.
// localStream is the ZegoLocalStream instance object created through createZegoStream
const audioEffectPlayer = zg.createAudioEffectPlayer(
localStream
)2 (Optional) Preload Resources
In scenarios where the same audio effect is played frequently, the SDK provides a function to preload audio effect files into memory to optimize the waste of network and performance caused by repeatedly downloading and decoding files. Using preloaded audio effects can also load the audio effects in advance, avoiding playback delays caused by slow loading when playing audio effects through the start interface.
Call the loadAudioEffect interface of ZegoExpressEngine to load audio effect resources, and get the asynchronous loading result through Promise.
When the loaded audio effect is no longer needed, you can call the unloadAudioEffect interface to unload the audio effect resources to release related resources.
Preloading is not required. It is recommended to use it when you need to improve performance or need to repeatedly play a specific audio effect.
const audioEffectID = "2";
// Online audio file address
const path = "https//xxx.mp3";
// Load audio effect resources
zg.loadAudioEffect(audioEffectID, path).then(res=>{
// Audio effect loading completed
});
// After loading is completed, you can release audio effect resources
zg.unloadAudioEffect(audioEffectID);3 Playback Control
Start Playback
Call the start interface to play audio effects.
-
The "audioEffectID" needs to remain globally unique, and "options.path" is the online audio file address of MP3, M4A, AAC, WAV, or other audio formats supported by the browser.
-
If the audio effect has been preloaded through the loadAudioEffect method, you only need to pass in the "audioEffectID" during preloading, and the "options.path" (path of the audio effect resource) field can be passed as empty.
const audioEffectID = "1"
const options = {
// Audio effect file address
path: "https://xxx.mp3"
}
audioEffectPlayer.start(
audioEffect.id,
options,
() => {
// Audio effect playback start callback
},
() => {
// Audio effect playback end callback
}
)Pause/Resume/Stop Playback
- Call the pause interface to pause the audio effect specified by "audioEffectID". If "audioEffectID" is not passed, all currently playing audio effects will be paused.
// Pause specified audio effect
audioEffectPlayer.pause(audioEffectID);
// Pause all audio effects
audioEffectPlayer.pauseAll();- After the audio effect is paused, call the resume interface to resume playback of the audio effect specified by "audioEffectID". If "audioEffectID" is not passed, all paused audio effects will be resumed.
// Resume specified audio effect
audioEffectPlayer.resume(audioEffectID);
// Resume all audio effects
audioEffectPlayer.resume();- Call the stop interface to stop playing the audio effect specified by "audioEffectID". If "audioEffectID" is not passed, all audio effects will be stopped.
// Stop specified audio effect
audioEffectPlayer.stop(audioEffectID);
// Stop all audio effects
audioEffectPlayer.stop();Adjust Volume
Call the setVolume interface to set the volume of the audio effect specified by "audioEffectID". The volume value range is [0, 100], and the default value is 100.
const volume = 70;
audioEffectPlayer.setVolume(audioEffectID, volume);Playback Progress Control
- Call the getTotalDuration interface to get the total duration of a single audio effect, in milliseconds.
- Call the getCurrentProgress interface to get the current playback progress of the audio effect.
- Call the seekTo interface 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, example: jump to the middle position of the audio effect progress
audioEffectPlayer.seekTo(audioEffectID, totalDuration/2);