Audio Effect Player

Feature Overview

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 sounds, 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 manages audio effects uniformly, supporting audio effect playback (multiple audio effects can be played simultaneously), 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

Download Sample Source Code

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

• A project has been created in the ZEGOCLOUD Console, and a valid AppID and AppSign have been obtained. For details, please refer to Console - Project Information.
• ZEGO Express SDK has been integrated into the project, and basic audio/video stream publishing and playing functionality has been implemented. For details, please refer to Quick Start - Integration and Quick Start - Implementation.

Implementation Steps

1 Create audio effect player

Call the createAudioEffectPlayer method of IZegoExpressEngine to create an audio effect player instance.

IZegoAudioEffectPlayer* audioEffectPlayer = engine->createAudioEffectPlayer();
if (audioEffectPlayer == nullptr) {
    printf("Failed to create audio effect player");
}

IZegoAudioEffectPlayer* audioEffectPlayer = engine->createAudioEffectPlayer();
if (audioEffectPlayer == nullptr) {
    printf("Failed to create audio effect player");
}

2 (Optional) Preload resources

// Load sound effect resource
audioEffectPlayer->loadResource(audioEffectID, "D:/soundEffectSample.mp3", [](int errorCode){
    printf("loadResource result=%s", errorCode==0? "succeed", "failed");
});

// Unload sound effect resource
audioEffectPlayer->unloadResource(audioEffectID);

// Load sound effect resource
audioEffectPlayer->loadResource(audioEffectID, "D:/soundEffectSample.mp3", [](int errorCode){
    printf("loadResource result=%s", errorCode==0? "succeed", "failed");
});

// Unload sound effect resource
audioEffectPlayer->unloadResource(audioEffectID);

3 Playback control

（Optional）Set event callbacks for audio effect player

class MyAudioEffectPlayerEventHandler: public IZegoAudioEffectPlayerEventHandler{
public:
    // Callback for state change when playing a sound effect
    void onAudioEffectPlayStateUpdate(IZegoAudioEffectPlayer* audioEffectPlayer, unsigned int audioEffectID, ZegoAudioEffectPlayState state, int errorCode) override{
        printf("effect %d : currentState=%d, errorCode=%d", audioEffectID, state, errorCode);
    }
}

auto eventHandler = std::make_shared<MyAudioEffectPlayerEventHandler>();
audioEffectPlayer->setEventHandler(eventHandler);

class MyAudioEffectPlayerEventHandler: public IZegoAudioEffectPlayerEventHandler{
public:
    // Callback for state change when playing a sound effect
    void onAudioEffectPlayStateUpdate(IZegoAudioEffectPlayer* audioEffectPlayer, unsigned int audioEffectID, ZegoAudioEffectPlayState state, int errorCode) override{
        printf("effect %d : currentState=%d, errorCode=%d", audioEffectID, state, errorCode);
    }
}

auto eventHandler = std::make_shared<MyAudioEffectPlayerEventHandler>();
audioEffectPlayer->setEventHandler(eventHandler);

Start playing

Call the start method to play sound effects. Currently, only supports playing up to 12 simultaneously, and can only be local files. Network resources are not supported. audioEffectID needs to remain globally unique.

• If the sound effect has been preloaded through the loadResource method, you only need to pass in the audioEffectID from preloading, and the path (path to the sound 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 repeated playback until the user manually calls stop to stop.

ZegoAudioEffectPlayConfig config;
config.repeatCount = 1;
config.isPublishOut = false;
audioEffectPlayer->start(audioEffectID, "D:/soundEffectSample.mp3", &config);

ZegoAudioEffectPlayConfig config;
config.repeatCount = 1;
config.isPublishOut = false;
audioEffectPlayer->start(audioEffectID, "D:/soundEffectSample.mp3", &config);

Pause, resume, stop playback

1. Call the pause method to pause playing the sound effect specified by audioEffectID, or call the pauseAll method to pause all currently playing sound effects.
2. After pausing sound effect playback, call the resume method to resume playing the sound effect specified by audioEffectID, or call the resumeAll method to resume all paused sound effects.
3. Call the stop method to stop playing the sound effect specified by audioEffectID, or call the stopAll method to stop playing all sound effects.

// Pause playback
audioEffectPlayer->pause(audioEffectID);
// Resume playback
audioEffectPlayer->resume(audioEffectID);
// Stop playback
audioEffectPlayer->stop(audioEffectID);

// Pause playback of all sound effects
audioEffectPlayer->pauseAll();
// Resume playback of all sound effects
audioEffectPlayer->resumeAll();
// Stop playback of all sound effects
audioEffectPlayer->stopAll();

// Pause playback
audioEffectPlayer->pause(audioEffectID);
// Resume playback
audioEffectPlayer->resume(audioEffectID);
// Stop playback
audioEffectPlayer->stop(audioEffectID);

// Pause playback of all sound effects
audioEffectPlayer->pauseAll();
// Resume playback of all sound effects
audioEffectPlayer->resumeAll();
// Stop playback of all sound effects
audioEffectPlayer->stopAll();

Adjust volume

1. Call the setVolume method to set the volume of the sound effect specified by audioEffectID. The value range is [0-200], and the default value is 100.
2. Call the setVolumeAll method to set the volume of all sound effects at the same time. The value range is [0-200], and the default value is 100.

// Set volume
audioEffectPlayer->setVolume(audioEffectID, volume);

// Set volume of all sound effects
audioEffectPlayer->setVolumeAll(volume);

// Set volume
audioEffectPlayer->setVolume(audioEffectID, volume);

// Set volume of all sound effects
audioEffectPlayer->setVolumeAll(volume);

Playback progress control

1. Call the getTotalDuration method to get the total duration of a single sound effect.
2. Call the getCurrentProgress method to get the current playback progress of the sound effect.
3. Call the seekTo method to set the playback progress as needed.

// Get total duration of sound effect
auto totalDuration = audioEffectPlayer->getTotalDuration(audioEffectID);
// Get current playback progress of sound effect
auto currentProgress = audioEffectPlayer->getCurrentProgress(audioEffectID);
// Set playback progress
audioEffectPlayer->seekTo(audioEffectID, total / 2, [](int errorCode){
    printf("seekTo result=%s", errorCode==0? "succeed", "failed");
});

// Get total duration of sound effect
auto totalDuration = audioEffectPlayer->getTotalDuration(audioEffectID);
// Get current playback progress of sound effect
auto currentProgress = audioEffectPlayer->getCurrentProgress(audioEffectID);
// Set playback progress
audioEffectPlayer->seekTo(audioEffectID, total / 2, [](int errorCode){
    printf("seekTo result=%s", errorCode==0? "succeed", "failed");
});

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);

engine->destroyAudioEffectPlayer(audioEffectPlayer);

FAQ

1. What is the difference between an audio effect player and a media player?