! 新版开发者中心已正式上线,旧文档将于6月30日下架,不再维护 立即体验
互动视频

音效播放器

下载pdf
更新时间:2020-05-07 18:49

1 功能简介

1.1 应用场景

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

所以 SDK 提供音效播放器 ZegoAudioPlayer 类统一管理音效,支持音效播放、播放控制、多音效重叠播放,并将声音混入推流中,并且为了提升性能,支持预加载音效功能。

1.2 支持格式

音效播放器支持 MP3、MP4、WAV 格式的文件。但如果 MP4 文件中没有音频数据,播放会报错。

1.3 音效播放器业务流程

音效播放器业务状态流转如下图所示:

2 下载示例源码

互动视频 Demo 源码下载地址:互动视频示例 Demo_iOS

码云下载地址(国内推荐)
阿里云下载地址(国内推荐)
github下载地址

示例 Demo 包含了基础专题和进阶专题,展示了如何使用 SDK API,开发者可参考其用法来实现自己的业务。示例 Demo 涵盖了 SDK 的大部分功能,开发者也可在示例 Demo 中查找 ZEGO SDK 更多的进阶功能,测试其功能和性能,以实现特定的需求。

音效播放器模块源码请查看 /src/LiveRoomPlayground-iOS/AudioPlayer 目录下的源文件。

3 使用步骤

播放音效与推流操作没有顺序限制,若想将音效声混入推流中,在推流前播放音效并设置将音效混入推流中,后续推流成功时,拉流端播放此条流也能听到音效声。

简单的调用流程如图:

3.1 初始化并设置代理

self.player = [[ZegoAudioPlayer alloc] init];
[self.player setDelegate:self];

3.2 播放控制

3.2.1 开始播放

接口定义如下:

/**
 * 播放音效
 * 
 * @param soundID 音效 ID
 * @param path 音效资源文件的本地路径
 * @param loopCount 循环次数
 * @param publish 是否放入推流中
 * 
 * @attention 如果是播放预加载的音效,指定音效 ID, 音效资源文件填 nil
 */
- (void)playEffect:(unsigned int)soundID source:(NSString *)path loop:(int)loopCount publish:(BOOL)publish;
  1. SDK 内部使用 soundID 进行音效的播放控制,SDK 不强制用户如何传入该参数,最好保证每个音效可以有唯一的 id,推荐的方式有静态自增 id 和传入音效文件路径的 hash 两种方式。
  2. 目前仅支持播放本地文件,不支持 iOS 媒体库中的音乐(ipod-library://)和网络资源。
  3. loopCount 指音效文件循环播放的次数,0表示播放一次,1表示播放2次,-1表示无限循环播放直到主动停止播放。
  4. publish 指是否将播放的音效混入推流,这样拉流方也可以听到你播放的音效,反之则不会听到。
  5. 开始播放将回调 onPlayEffect 事件,如果播放失败则 error 非 0;播放结束将回调 onPlayEnd 事件,如果播放失败不会回调该事件。

3.2.2 停止、暂停、恢复播放

接口定义如下:

/**
 * 停止播放音效
 * 
 * @param soundID 音效 ID
 */
- (void)stopEffect:(unsigned int)soundID;

/**
 * 暂停播放音效
 * 
 * @param soundID 音效 ID
 */
- (void)pauseEffect:(unsigned int)soundID;

/**
 * 恢复播放音效
 * 
 * @param soundID 音效 ID
 */
- (void)resumeEffect:(unsigned int)soundID;

/**
 * 暂停全部音效
 */
- (void)pauseAll;

/**
 * 恢复全部音效
 */
- (void)resumeAll;

/**
 * 停止全部音效
 */
- (void)stopAll;

3.2.3 调节播放音量

接口定义如下:

/**
 * 设置单个音效的音量
 * 
 * @param soundID 音效 ID
 * @param volume 音量,有效范围 0 到 100,默认 100
 */
- (void)setEffect:(unsigned int)soundID volume:(int)volume;

/**
 * 设置所有音效的音量
 *
 * @param volume 音量,有效范围 0 到 100,默认 100
 */
- (void)setVolumeAll:(int)volume;

3.2.4 播放进度控制

接口定义如下:

/**
 * 设置进度
 *
 * @param soundID 音效 ID
 * @param timestamp 进度,单位毫秒
 * @return 返回 -1 表示失败,返回 0 表示成功
 */
- (int)seekTo:(unsigned int)soundID timestamp:(long)timestamp;

/**
 * 获取音效的总时长
 *
 * @param soundID 音效 ID
 * @return 返回音效的总时长,单位毫秒,失败返回 0
 */
- (long)getDuration:(unsigned int)soundID;

/**
 * 获取音效的当前进度
 *
 * @param soundID 音效 ID
 * @return 返回音效的当前进度,单位毫秒,失败返回 -1
 */
- (long)getCurrentDuration:(unsigned int)soundID;

3.3 预加载

在频繁播放相同音效场景中,SDK 为了优化重复读文件并解码的性能,提供了预加载音效文件到内存中的功能。
预加载支持最多同时加载 15 个音效文件,并且音效文件时长不能超过 30s,否则加载会报错。

接口定义如下:

/**
 * 预加载音效
 *
 * @param soundID 音效 ID
 * @param path 音效资源文件的本地路径
 */
- (void)preloadEffect:(unsigned int)soundID source:(NSString*)path;

/**
 * 删除预加载音效
 * 
 * @param soundID 音效 ID
 */
- (void)unloadEffect:(unsigned int)soundID;
  1. 调用 preloadEffect 接口后,将回调 onPreloadEffect:error: 事件,如果播放失败则 error 非 0;预加载完成将回调 onPreloadComplete: 事件,如果预加载失败不会回调该事件。

  2. 预加载音效需要等待 onPreloadComplete 回调后方可播放,否则会导致播放出错。
    播放预加载音效时,只需要传入预加载时传入的 soundID 即可,path 字段传 nil 即可。

  3. 在加载的音效使用完毕之后,可以通过调用删除预加载音效接口释放相关资源;否则 SDK 将在 ZegoAudioPlayer 释放时释放加载的资源。

    提示: 预加载不是一个必须的步骤,一般来说为了提高性能或者需要反复播放某个特定的音效的时候,我们建议使用预加载。

4 API 参考列表

方法 描述
setDelegate: 设置回调
ZegoAudioPlayerDelegate 音效播放器回调代理
playEffect:source:loop:publish: 播放音效
stopEffect: 停止播放音效
pauseEffect: 暂停播放音效
resumeEffect: 恢复播放音效
setEffect:volume: 设置单个音效的音量
setVolumeAll: 设置所有音效的音量
pauseAll 暂停全部音效
resumeAll 恢复全部音效
stopAll 停止全部音效
preloadEffect:source: 预加载音效
unloadEffect: 删除预加载音效
seekTo:timestamp: 设置进度
getDuration: 获取音效的总时长
getCurrentDuration: 获取音效的当前进度

5 相关文档

可使用 ZEGO SDK 完成如下功能来实现直播以检验可在推流中混入音效的功能。

6 FAQ

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

答:媒体播放器主要用于播放视频及较长的音乐,可以播放网络资源,有实例数量限制;音效播放器主要用于播放时间较短的音效,支持多路并发播放,但是不支持播放网络资源。

Q2:音效播放器支持同时播放几个音效文件?

答:音效播放器支持同时播放12个音效,预加载支持加载15个。