文档中心
超低延迟直播
其他能力
音效文件播放器

音效文件播放器

更新时间：2025-06-23 16:09

功能简介

应用场景

音效，主要指为了增强真实感或者烘托场景氛围播放的简短效果音。例如：在直播期间，经常会有一些播放音效的场景，如掌声、礼物音效、提示音等。在游戏中，有时也需要播放子弹声、碰撞打击声等。

ZEGO Express SDK 提供音效文件播放器（ZegoAudioEffectPlayer），统一管理音效，支持音效播放（可以多音效重叠播放）、播放控制（如暂停播放、音量调节、设置播放进度）、预加载音效等功能。

本功能不支持在 WebGL 环境中运行使用。

支持格式

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

示例源码下载

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

相关源码请查看 “/ZegoExpressExample/Examples/AdvancedAudioProcessing” 目录下的文件。

前提条件

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

已在 ZEGO 控制台创建项目，并申请有效的 AppID 和 AppSign，详情请参考控制台 - 项目信息。
已在项目中集成 ZEGO Express SDK，并实现了基本的音视频推拉流功能，详情请参考快速开始 - 集成和快速开始 - 实现流程。

使用步骤

1 创建音效播放器

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

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

ZegoAudioEffectPlayer audioEffectPlayer = engine.CreateAudioEffectPlayer();

2 （可选）预加载资源

预加载资源

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

调用 LoadResource 方法加载音效资源，可通过 “callback” 参数来监听加载的结果，显示加载成功后方可播放。

最多支持同时预加载 12 个本地音效文件（不支持网络资源），并且单个音效文件时长不能超过 30s，否则加载会报错。

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

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

// 加载音效资源
audioEffectPlayer.LoadResource(audioEffectID, "path", (int errorCode)=>{

});

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

3 播放控制

3.1 （可选）为音效播放器设置事件回调

音效播放器事件回调设置

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

public void OnAudioEffectPlayStateUpdate(ZegoAudioEffectPlayer audioEffectPlayer, uint audioEffectID, ZegoAudioEffectPlayState state, int errorCode) {

}

3.2 开始播放

调用 Start 方法播放音效，目前仅支持同时播放 12 个，且只能为本地文件，不支持播放网络资源。

如果已通过 LoadResource 方法预先加载了音效，则只需要传入预加载时的 “audioEffectID”，“path”（音效资源的路径）字段传空即可。

audioEffectID 需要保持全局唯一。
若需要重复播放可以通过 ZegoAudioEffectPlayConfig 中 “playCount” 配置重复次数。如果设置为 “0”，则表示无限重复播放，直到用户手动调用 Stop 停止。

uint audioEffectID = 1;
ZegoAudioEffectPlayConfig playConfig = new ZegoAudioEffectPlayConfig();
config.playCount = 10;
config.isPublishOut = true;
audioEffectPlayer.Start(audioEffectID,"path",playConfig);

3.3 暂停/恢复/停止播放

暂停播放：调用 Pause 方法可以暂停播放 “audioEffectID” 指定的音效，调用 PauseAll 方法则暂停所有正在播放的音效。
恢复播放：音效暂停播放后，调用 Resume 方法可以恢复播放 “audioEffectID” 指定的音效，调用 ResumeAll 方法则恢复所有已暂停音效。
停止播放：调用 Stop 方法可以停止播放 “audioEffectID” 指定的音效，调用 StopAll 方法则停止播放所有音效。

audioEffectPlayer.Pause(audioEffectID);
audioEffectPlayer.Resume(audioEffectID);
audioEffectPlayer.Stop(audioEffectID);
audioEffectPlayer.PauseAll();
audioEffectPlayer.ResumeAll();
audioEffectPlayer.StopAll();

3.4 调节音量

调用 SetVolume 方法可以设置 “audioEffectID” 指定的音效音量，取值范围为 [0, 200]，默认值为 “100”。
调用 SetVolumeAll 方法则同时设置所有音效音量，取值范围为 [0, 200]，默认值为 “100”。

int volume =70;
audioEffectPlayer.SetVolume(audioEffectID, volume);

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

3.5 播放进度控制

调用 GetTotalDuration 方法获取单个音效的总时长。
调用 GetCurrentProgress 方法获取音效当前播放进度。
调用 SeekTo 方法可以根据需要设置播放进度。

// 获取音效的总时长
ulong totalDuration = audioEffectPlayer.GetTotalDuration(audioEffectID);
// 获取音效当前播放进度
ulong progress = audioEffectPlayer.GetCurrentProgress(audioEffectID);
// 设置播放进度
audioEffectPlayer.SeekTo(audioEffectID, 1, (int errorCode)=>{

});

4 销毁媒体播放器

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

engine.DestroyAudioEffectPlayer(audioEffectPlayer);

常见问题

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

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