实时音视频
  • iOS
  • Android : Java
  • macOS
  • Windows
  • HarmonyOS
  • Linux
  • Web
  • 小程序
  • Flutter
  • Electron
  • Unreal Engine
  • Unity3D
  • uni-app
  • React Native
  • Cocos Creator
  • 产品简介
  • 下载
  • 体验 App
  • 快速开始
    • 跑通示例源码
    • 集成 SDK
    • 实现视频通话
    • 实时音视频 SDK 与实时语音 SDK 差异
    • 场景化音视频配置
  • 通信能力
  • 房间能力
  • 音频能力
  • 视频能力
  • 直播能力
  • 其他能力
  • 最佳实践
  • 客户端 API
  • 服务端 API
  • 常见错误码
  • 常见问题
  • 文档中心
  • 实时音视频
  • 其他能力
  • 音效文件播放器

音效文件播放器

更新时间:2024-01-02 18:48

功能简介

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

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

支持格式

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

示例源码下载

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

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

前提条件

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

使用步骤

1 创建音效播放器

调用 ZegoExpressEnginecreateAudioEffectPlayer 方法创建音效播放器实例。

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

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

2 (可选)预加载资源

预加载资源

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

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

当加载的音效使用完成后,可以调用 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);

3 播放控制

3.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);
    }
});

3.2 开始播放

调用 start 方法播放音效,目前仅支持同时播放 15 个,且只能为本地文件,不支持播放网络资源。 “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);

3.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();

3.4 调节音量

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

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

3.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);
    }
});

4 销毁音效文件播放器

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

engine.destroyAudioEffectPlayer(audioEffectPlayer);

常见问题

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

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