Audio Effect Player
Feature Introduction
Audio effects mainly refer to short effect sounds played to enhance realism or set the atmosphere of a scene. For example: during live streaming, there are often scenarios for playing sound effects, such as applause, gift sound effects, prompt tones, etc. In games, it is sometimes necessary to play sounds such as gunshots, collision impacts, etc.
The audio effect player (ZegoAudioEffectPlayer) provided by ZEGO Express SDK uniformly manages audio effects, supporting audio effect playback (multiple audio effects can be played simultaneously), playback control (such as pause playback, volume adjustment, set 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
Sample Source Code Download
Please refer to Download Sample Source Code to get the source code.
For related source code, please check the files in the "/ZegoExpressExample/Examples/AdvancedAudioProcessing/AudioEffectPlayer" directory.
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 AppSign. For details, please refer to Console - Project Information.
- You have integrated ZEGO Express SDK in the project and implemented basic audio and video publishing and playing functions. For details, please refer to Quick Start - Integration and Quick Start - Implementation Flow.
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, it will return nil.
@property (nonatomic, strong) ZegoAudioEffectPlayer *audioEffectPlayer;self.audioEffectPlayer = [[ZegoExpressEngine sharedEngine] createAudioEffectPlayer];
if (!self.audioEffectPlayer) {
NSLog(@"Failed to create audio effect player");
}2 (Optional) Preload resources
In scenarios where the same audio effect is played frequently, 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. The audio effect can be played only 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 no longer needed, you can call the unloadResource interface to unload it to release related resources. Otherwise, the SDK will automatically unload loaded audio effects when the ZegoAudioEffectPlayer instance is released.
Preloading is not a required operation. It is recommended when you need to improve performance or need to repeatedly play a specific audio effect.
// This example gets the test.wav resource already stored in the App Bundle
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"wav"];
[self.audioEffectPlayer loadResource:filePath audioEffectID:0 callback:^(int errorCode) {
NSLog(@"loadResource result, errorCode: %d", errorCode);
}];3 Playback control
(Optional) Set event callback for audio effect player
As needed, you can call the setEventHandler method of the audio effect player to set event callbacks for the player, used to listen to notifications such as "audio effect playback status change".
[self.audioEffectPlayer setEventHandler:self];- (void)audioEffectPlayer:(ZegoAudioEffectPlayer *)audioEffectPlayer audioEffectID:(unsigned int)audioEffectID playStateUpdate:(ZegoAudioEffectPlayState)state errorCode:(int)errorCode {
NSLog(@"Play state update. ID:%d, state:%lu, err:%d", audioEffectID, (unsigned long)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 can only be local files, does not support playing network resources. The "audioEffectID" needs to be globally unique.
- 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 passed as 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.
// This example gets the test.wav resource already stored in the App Bundle
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"wav"];
ZegoAudioEffectPlayConfig *config = [[ZegoAudioEffectPlayConfig alloc] init];
// Play once
config.playCount = 1;
// Mix into stream publishing
config.isPublishOut = YES;
// Use 0 as the audioEffectID for this time
[self.audioEffectPlayer start:0 path:filePath 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 audio effects that are playing.
- After the audio effect is paused, call the resume method to resume 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 playing all audio effects.
// Pause playback of audioEffectID No. 0
[self.audioEffectPlayer pause:0];
// Resume playback of audioEffectID No. 0
[self.audioEffectPlayer resume:0];
// Stop playback of audioEffectID No. 0
[self.audioEffectPlayer stop:0];
// Pause playback of all resources
[self.audioEffectPlayer pauseAll];
// Resume playback of all resources
[self.audioEffectPlayer resumeAll];
// Stop playback of all resources
[self.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".
// Set the volume of audioEffectID No. 0 to 100
[self.audioEffectPlayer setVolume:100 audioEffectID:0];
// Set the volume of all resources to 100
[self.audioEffectPlayer setVolumeAll:100];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 audioEffectID No. 0
unsigned long long totalDuration = [self.audioEffectPlayer getTotalDuration:0];
// Get the current playback progress of audioEffectID No. 0
unsigned long long currentProgress = [self.audioEffectPlayer getCurrentProgress:0];
// Set the playback progress of audioEffectID No. 0 to half of the total progress
[self.audioEffectPlayer seekTo:(unsigned long long)(totalDuration / 2) audioEffectID:0 callback:^(int errorCode) {
NSLog(@"seekTo result: %d", 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.
[[ZegoExpressEngine sharedEngine] destroyAudioEffectPlayer:self.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 shorter audio 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 multiple audio effects playing concurrently, and one instance can play up to 12 audio effects at the same time. |