播放音效或音乐文件

在游戏或 K 歌等实时音视频场景中，为烘托气氛、增添趣味性，用户通常需要播放音效或音乐文件。

本文介绍如何在你的项目中实现播放音效或音乐文件功能。

技术原理

声网提供了以下 API， 帮助你实现播放音效或音乐文件：

• 音效 API：播放持续时间短的氛围音，例如掌声、欢呼声、打斗声、枪击声等，通常可以同时播放多个音效文件。
• 音乐 API：播放比较长的音乐文件，例如，在唱歌时播放伴奏，在聊天时播放背景音乐。同一时间，只能播放一个音乐文件。

注意

如果使用 startAudioMixing 等音乐 API 播放时长较短的音效文件、或使用 playEffect 等音效 API 播放时长较长的音乐文件可能会播放失败。

这些方法主要包括如下功能：

功能	音效 API	音乐 API
播放或停止播放特定的音频文件	preloadEffect unloadEffect playEffect stopEffect stopAllEffects	startAudioMixing stopAudioMixing
暂停或恢复播放音频文件	pauseEffect pauseAllEffects resumeEffect resumeAllEffects	pauseAudioMixing resumeAudioMixing
获取和调整音频文件的播放位置和音量	setEffectPosition getEffectCurrentPosition getEffectsVolume setEffectsVolume setVolumeOfEffect	getAudioMixingCurrentPosition setAudioMixingPosition getAudioMixingPublishVolume adjustAudioMixingPublishVolume getAudioMixingPlayoutVolume adjustAudioMixingPlayoutVolume
报告音频文件的播放状态	onAudioEffectFinished	onAudioMixingStateChanged

前提条件

在进行操作之前，请确保你已满足以下条件：

• 项目已经实现了基本的实时音视频功能。
• 了解 Android 设备支持的媒体文件格式。
• 调用音乐混音 API，你的设备需要运行 Android 4.2 或以上版本。

实现播放音频文件

本节介绍如何调用音效 API 和音乐混音 API，在你的项目中播放音效和音乐混音文件。

播放音效

1. 添加 App 权限 对于 targetSdkVersion >= 20 的 Android 项目，在项目的 AndroidManifest.xml 文件中添加如下内容：

   XML

    <application>
       android:usesCleartextTraffic="true"
       android:requestLegacyExternalStorage="true"
    </application>

2. 实现播放音效的逻辑。在你的声网项目中，打开管理音效播放的文件并添加如下代码：

   Java

   // 导入 IAudioEffectManger 类
   import io.agora.rtc.IAudioEffectManager;
   
   // 调用 getAudioEffectManager 获取 IAudioEffectManager 类
   private IAudioEffectManager audioEffectManager;
   audioEffectManager = mRtcEngine.getAudioEffectManager();
   
   // 设置音效 ID，作为识别音效文件的唯一标识
   int id = 0;
   // 如果要反复播放音效，你可以将音效文件预加载至内存。如果音效文件体积较大，请勿预加载
   // 你只能预加载本地音效文件
   audioEffectManager.preloadEffect(id++, "Your file path");
   
   // 调用 playEffect 播放指定的音效文件
   // 多次调用 playEffect，设置多个音效 ID，同时播放多个音效文件
   audioEffectManager.playEffect(
       0,   // 设置音效 ID
       "Your file path",   // 设置音效文件路径
       -1,  // 设置音效循环播放的次数。-1 表示无限循环
       1,   // 设置音效的音调。1 表示原始音调
       0.0, // 设置音效的空间位置。0.0 表示音效出现在正前方
       100, // 设置音效音量。100 表示原始音量
       true,// 设置是否将音效发布至远端
       0    // 设置音效文件的播放位置。0 表示从音效文件的第 0 ms 开始播放
   );
   
   // 暂停或恢复播放指定音效文件
   audioEffectManager.pauseEffect(id);
   audioEffectManager.resumeEffect(id);
   
   // 设置指定的本地音效文件的播放位置
   audioEffectManager.setEffectPosition(id, 500);
   
   // 设置所有音效文件的播放音量
   audioEffectManager.setEffectsVolume(50.0);
   
   // 设置指定音效文件的播放音量
   audioEffectManager.setVolumeOfEffect(id, 50.0);
   
   // 释放预加载的音效文件
   audioEffectManager.unloadEffect(id);
   
   // 停止播放所有音效文件
   audioEffectManager.stopAllEffects;
   
   @Override
   // 当音效文件播放结束后触发该回调
   public void onAudioEffectFinished(int soundId) {
       super.onAudioEffectFinished(soundId);
   }

播放音乐

加入频道之前或之后，调用 startAudioMixing 方法播放音乐文件。成功调用该方法后，音乐文件状态发生变化时，SDK 触发 onAudioMixingStateChanged 回调。该回调也报告音乐文件状态变化的原因。

1. 添加 App 特权。针对 targetSdkVersion >= 20 的 Android 项目，在项目的 AndroidManifest.xml 文件中添加如下内容：

   XML

    <application>
       android:usesCleartextTraffic="true"
       android:requestLegacyExternalStorage="true"
    </application>

2. 实现音乐播放逻辑。加入频道之前或之后，调用 startAudioMixing 方法播放音乐文件。成功调用该方法后，音乐混音状态发生变化时，SDK 触发 onAudioMixingStateChanged 回调。该回调也报告音乐混音状态变化的原因。你还可以通过下列方法实现播放控制：

   • pauseAudioMixing：暂停播放。
   • resumeAudioMixing：恢复播放。
   • stopAudioMixing：停止播放。
   • setAudioMixingPosition：设置当前音乐文件的播放位置。
   • adjustAudioMixingPlayoutVolume：调节当前音乐文件在本地的播放音量。
   • adjustAudioMixingPublishVolume：调节当前音乐文件在远端的播放音量。
   Java

   // 开始播放音乐文件
   mRtcEngine.startAudioMixing(
       "Your file path",  // 指定本地或在线音乐文件的路径
       false,             // 设置是否只在本地播放音乐文件。false 表示本地用户和远端用户都能听到音乐
       -1,                // 设置音乐文件的播放次数。-1 表示无限循环
       0                  // 设置音乐文件起始的播放位置
   );
   
   @Override
   // 当音乐文件播放状态发生改变时触发该回调
   // 在收到 onAudioMixingStateChanged 回调后，声网建议调用其他音乐 API，如 pauseAudioMixing 或 getAudioMixingDuration
   public void onAudioMixingStateChanged(int state, int reason) {
       super.onAudioMixingStateChanged(state, reason);
   }
   
   // 暂停或恢复播放音乐文件
   rtcEngine.pauseAudioMixing();
   rtcEngine.resumeAudioMixing();
   // 获取当前音乐文件的总时长
   rtcEngine.getAudioMixingDuration();
   // 设置当前音乐文件的播放位置。500 表示从音乐文件的第 500 ms 开始播放
   rtcEngine.setAudioMixingPosition(500);
   // 调节当前音乐文件在远端的播放音量
   rtcEngine.adjustAudioMixingPublishVolume(50);
   // 调节当前音乐文件在本地的播放音量
   rtcEngine.adjustAudioMixingPlayoutVolume(50);

参考信息

示例项目

声网提供了开源的示例项目供你参考，你可以前往下载或查看其中的源代码。

PlayAudioFiles

API 参考

• preloadEffect
• playEffect
• onAudioEffectFinished
• startAudioMixing
• onAudioMixingStateChanged
• pauseAudioMixing
• resumeAudioMixing
• stopAudioMixing
• adjustAudioMixingPlayoutVolume
• adjustAudioMixingPublishVolume

相关文档

为什么通过系统音量无法调节背景音乐？

为什么 Android 9 无法使用 startAudioMixing 或 playEffect 播放音频文件？

为什么 Android 设备上挂断系统电话后音乐文件不会自动恢复播放？