1 功能简介

我们在直播中,为了增强真实感,烘托场景氛围需要播放的简短效果音。例如:掌声、笑声、礼物音效、提示音等。在游戏中,有时也需要播放子弹声、碰撞打击声等。

ZegoExpress SDK 提供音效文件播放器,通过 ZegoAudioEffectPlayer 统一管理音效,支持音效播放(可以多音效重叠播放)、播放控制(如暂停播放、音量调节、设置播放进度)、预加载音效等功能。

2 支持格式

音效文件播放器支持播放 MP3、M4A、AAC、WAV 格式的本地音频文件。

3 示例源码下载

请参考 下载示例源码 获取源码。

相关源码请查看 “/ZegoExpressExample/AdvancedAudioProcessing/src/main/java/im/zego/advancedaudioprocessing/audioeffectplayer” 目录下的文件。

4 前提条件

在实现音效文件播放器功能之前,请确保:

5 使用步骤

5.1 创建音效播放器

调用 ZegoExpressEngine 的 createAudioEffectPlayer 方法创建音效播放器实例。

引擎当前只支持同时创建一个实例,超出后将返回 null

ZegoAudioEffectPlayer audioEffectPlayer = ZegoExpressEngine.getEngine().createAudioEffectPlayer();

5.2 播放控制

5.2.1 (可选)为音效播放器设置事件回调

可以根据需要调用音效播放器的 setEventHandler 方法为播放器设置事件回调,用于监听“音效播放状态改变”等通知。

audioEffectPlayer.setEventHandler(new IZegoAudioEffectPlayerEventHandler() {
    @Override
    public void onAudioEffectPlayStateUpdate(ZegoAudioEffectPlayer audioEffectPlayer, int audioEffectID, ZegoAudioEffectPlayState state, int errorCode) {
                        Log.d("[ZEGO]", "onAudioEffectPlayStateUpdate errorCode:" + errorCode + "  audioEffectID:" + audioEffectID + "  state:" + state);
    }
});

5.2.2 开始播放

调用 start 方法播放音效,目前仅支持同时播放 12 个,且只能为本地文件,不支持播放网络资源。 “audioEffectID” 需要保持全局唯一。

  • 如果已通过 loadResource 方法预先加载了音效,则只需要传入预加载时的 “audioEffectID”,“path”(音效资源的路径)字段传空即可。
  • 若需要重复播放可以通过 ZegoAudioEffectPlayConfig 中 “playCount” 配置重复次数。如果设置为 “0”,则表示无限重复播放,直到用户手动调用 stop 停止。
int audioEffectID = 1;
ZegoAudioEffectPlayConfig config = new ZegoAudioEffectPlayConfig();
config.playCount = 10;
config.isPublishOut = true;
audioEffectPlayer.start(audioEffectID,"/storage/emulated/0/Android/data/im.zego.express.example.video/files/3-s.mp3",config);

5.2.3 暂停/恢复/停止播放

  1. 调用 pause 方法可以暂停播放 “audioEffectID” 指定的音效,调用 pauseAll 方法则暂停所有正在播放的音效。
  2. 音效暂停播放后,调用 resume 方法可以恢复播放 “audioEffectID” 指定的音效,调用 resumeAll 方法则恢复所有已暂停音效。
  3. 调用 stop 方法可以停止播放 “audioEffectID” 指定的音效,调用 stopAll 方法则停止播放所有音效。
audioEffectPlayer.pause(audioEffectID);
audioEffectPlayer.resume(audioEffectID);
audioEffectPlayer.stop(audioEffectID);
audioEffectPlayer.pauseAll();
audioEffectPlayer.resumeAll();
audioEffectPlayer.stopAll();

5.2.4 调节音量

  1. 调用 setVolume 方法可以设置 “audioEffectID” 指定的音效音量,取值范围为 [0, 200],默认值为 “100”。
  2. 调用 setVolumeAll 方法则同时设置所有音效音量,取值范围为 [0, 200],默认值为 “100”。
int volume =70;
audioEffectPlayer.setVolume(audioEffectID, volume);

// 设置所有音效的音量
audioEffectPlayer.setVolumeAll(volume);

5.2.5 播放进度控制

  1. 调用 getTotalDuration 方法获取单个音效的总时长。
  2. 调用 getCurrentProgress 方法获取音效当前播放进度。
  3. 调用 seekTo 方法可以根据需要设置播放进度。
// 获取音效的总时长
long totalDuration = audioEffectPlayer.getTotalDuration(audioEffectID);
// 获取音效当前播放进度
long progress = audioEffectPlayer.getCurrentProgress(audioEffectID);
// 设置播放进度
audioEffectPlayer.seekTo(audioEffectID, 1, new IZegoAudioEffectPlayerSeekToCallback() {
    @Override
    public void onSeekToCallback(int errorCode) {
        Log.d("[ZEGO]", "onSeekToCallback errorCode:" + errorCode);
    }
});

5.3 (可选)预加载资源

在频繁播放相同音效场景中,SDK 为了优化重复读文件并解码的性能,提供了预加载音效文件到内存中的功能。

调用 loadResource 方法加载音效资源,可通过 “callback” 参数来监听加载的结果,显示加载成功后方可播放。最多支持同时预加载 15 个本地音效文件(不支持网络资源),并且单个音效文件时长不能超过 30 s,否则加载会报错。

当加载的音效使用完成后,可以调用 unloadResource 接口卸载,以释放相关资源。否则 SDK 将在 ZegoAudioEffectPlayer 实例释放时会自动卸载已加载的音效。

预加载为非必须操作,为了提高性能或者需要反复播放某个特定的音效时推荐使用。

// 加载音效资源
audioEffectPlayer.loadResource(audioEffectID, "/storage/emulated/0/Android/data/im.zego.express.example.video/files/3-s.mp3", new IZegoAudioEffectPlayerLoadResourceCallback() {
    @Override
    public void onLoadResourceCallback(int i) {
        Log.d("[ZEGO]", "onLoadResourceCallback errorCode:" + i );                    

    }
});

// 卸载音效资源
audioEffectPlayer.unloadResource(audioEffectID);

5.4 销毁媒体播放器

使用完音效播放器后,需要及时调用 destroyAudioEffectPlayer 方法销毁,释放该播放器占用的资源。

engine.destroyAudioEffectPlayer(audioEffectPlayer);

6 API 参考列表

方法 描述
createAudioEffectPlayer 创建音效播放器实例
setEventHandler 设置音效播放器回调
start 播放音效
pause 暂停播放单个音效
pauseAll 暂停播放所有音效
resume 恢复播放单个音效
resumeAll 恢复播放所有音效
stop 停止播放单个音效
stopAll 停止播放所有音效
setVolume 调节音效音量
setVolumeAll 调节所有音效音量
getTotalDuration 控制播放进度
getCurrentProgress 获取当前播放进度
seekTo 设置指定的播放进度
loadResource 预加载资源
unloadResource 卸载资源
destroyAudioEffectPlayer 销毁音效播放器实例

7 音效播放器与媒体播放器有什么区别?

  • 媒体播放器主要用于播放视频及较长的音乐,支持播放网络资源。同一时间最多支持创建 4 个播放器实例,一个实例只能播放一个音视频。
  • 音效播放器主要用于播放时间较短的音效,不支持播放网络资源。同一时间只支持创建一个音效播放器实例,音效播放器支持多路音效并发播放,一个实例最多同时播放 12 个音效。

获取Demo

获取本文的Demo、开发文档、技术支持。

获取SDK的商务活动、热门产品。

注册即构ZEGO开发者帐号,快速开始。