1 功能简介

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

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

2 支持格式

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

3 示例源码下载

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

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

4 前提条件

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

5 使用步骤

5.1 创建音效播放器

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

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

@property (nonatomic, strong) ZegoAudioEffectPlayer *audioEffectPlayer;
self.audioEffectPlayer = [[ZegoExpressEngine sharedEngine] createAudioEffectPlayer];
if (!self.audioEffectPlayer) {
    NSLog(@"创建音效播放器失败");
}

5.2 播放控制

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

音效播放器事件回调设置

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

5.2.2 开始播放

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

  • 如果已通过 loadResource 方法预先加载了音效,则只需要传入预加载时的 “audioEffectID”,“path”(音效资源的路径)字段传空即可。
  • 若需要重复播放可以通过 ZegoAudioEffectPlayConfig 中 “playCount” 配置重复次数。如果设置为 “0”,则表示无限重复播放,直到用户手动调用 stop 停止。
// 此处示例获取已存放于 App Bundle 内的 test.wav 资源
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"wav"];

ZegoAudioEffectPlayConfig *config = [[ZegoAudioEffectPlayConfig alloc] init];
config.playCount = 1; // 播放一次
config.isPublishOut = YES; // 播放混入推流中

// 使用 0 作为此次的 audioEffectID
[self.audioEffectPlayer start:0 path:filePath config:config];

5.2.3 暂停/恢复/停止播放

  1. 调用 pause 指定的音效,调用 pauseAll 方法则暂停所有正在播放的音效。
  2. 音效暂停播放后,调用 resume 方法可以恢复播放 “audioEffectID” 指定的音效,调用 resumeAll 方法则恢复所有已暂停音效。
  3. 调用 stop 指定的音效,调用 stopAll 方法则停止播放所有音效。
// 暂停 0 号 audioEffectID 资源的播放
[self.audioEffectPlayer pause:0];

// 恢复 0 号 audioEffectID 资源的播放
[self.audioEffectPlayer resume:0];

// 停止 0 号 audioEffectID 资源的播放
[self.audioEffectPlayer stop:0];

// 暂停所有资源的播放
[self.audioEffectPlayer pauseAll];

// 恢复所有资源的播放
[self.audioEffectPlayer resumeAll];

// 停止所有资源的播放
[self.audioEffectPlayer stopAll];

5.2.4 调节音量

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

// 设置所有资源的音量为 100
[self.audioEffectPlayer setVolumeAll:100];

5.2.5 播放进度控制

  1. 调用 getTotalDuration 方法获取单个音效的总时长。
  2. 调用 getCurrentProgress 方法获取音效当前播放进度。
  3. 调用 seekTo 方法可以根据需要设置播放进度。
// 获取 0 号 audioEffectID 的总时长
unsigned long long totalDuration = [self.audioEffectPlayer getTotalDuration:0];

// 获取 0 号 audioEffectID 的当前播放进度
unsigned long long currentProgress = [self.audioEffectPlayer getCurrentProgress:0];

// 设置 0 号 audioEffectID 的播放进度为总进度的一半
[self.audioEffectPlayer seekTo:(unsigned long long)(totalDuration / 2) audioEffectID:0 callback:^(int errorCode) {
    NSLog(@"seekTo result: %d", errorCode);
}];

5.3 (可选)预加载资源

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

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

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

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

// 此处示例获取已存放于 App Bundle 内的 test.wav 资源
NSString *filePath = [[NSBundle mainBundle] pathForResource:@"test" ofType:@"wav"];

[self.audioEffectPlayer loadResource:filePath audioEffectID:0 callback:^(int errorCode) {
    NSLog(@"loadResource result, errorCode: %d", errorCode);
}];

5.4 销毁媒体播放器

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

[[ZegoExpressEngine sharedEngine] destroyAudioEffectPlayer:self.audioEffectPlayer];

6 API 参考列表

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

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

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

获取更多支持

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

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

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