功能描述

在实时音视频互动过程中，为烘托气氛、增添趣味性，用户通常需要播放音效或音乐文件并且让频道内所有用户都听到。例如，在游戏中添加打斗声，在唱歌时添加伴奏。Agora 提供两组独立的方法，你可以分别实现播放音效和音乐文件。

示例项目

Agora 在 GitHub 上提供已实现播放音效或音乐文件功能的开源示例项目。你可以下载体验并参考源代码。

音效文件

本文提到的音效是指持续时间短的氛围音，例如掌声、欢呼声、打斗声、枪击声等，通常多个音效可以叠加使用。

Agora 提供一组方法播放和管理音效文件，主要包括如下功能：

• 播放本地或在线音效文件
• 设置音效的空间位置、循环次数、播放位置、音量等播放选项
• 灵活控制指定或全部音效文件的播放、暂停、恢复与停止

参考如下步骤实现播放音效文件：

1. 在加入频道前调用 getAudioEffectManager 方法获取音效管理类 IAudioEffectManager。
2. 调用 preloadEffect 方法预加载本地音效文件。
3. 加入频道后调用 playEffect 方法播放音效文件。当音效文件播放完成时，SDK 会触发 onAudioEffectFinished 回调。

获取音效管理类

Agora SDK 提供 IAudioEffectManager 类播放和管理音效。在播放音效文件前，你需要获取 IAudioEffectManager 类。

// 导入 IAudioEffectManager 类。
import io.agora.rtc.IAudioEffectManager;

// 调用 getAudioEffectManager 方法获取音效管理类。
private IAudioEffectManager audioEffectManager;
audioEffectManager = engine.getAudioEffectManager();

指定音效文件

在播放音效文件前，你需要设置 filePath 和 soundId指定音效文件。两个参数的含义如下：

• filePath: 音效文件路径，支持本地或在线文件路径。SDK 会在该路径中查找音效文件。
• soundId: 音效 ID，由你自行定义，具有唯一性。SDK 会根据音效 ID 来识别音效文件。常见的音效 ID 定义方法有自增 ID、使用音效文件名的 hashCode 等。

预加载

SDK 支持预加载功能，你可以将音效文件提前加载到内存，以提高性能。预加载不是一个必须的步骤，Agora 建议你按需选择。

• 如果需要反复播放某个特定的音效，则建议预加载音效文件。
• 如果音效文件较大，则不建议预加载音效文件。

如需加载多个音效文件，你需要多次调用 preloadEffect。

// 设置音效 ID。
int id = 0;
// 将指定的本地音效文件预加载至内存。 
audioEffectManager.preloadEffect(id++, "your file path");

// 释放预加载的音效文件。 
audioEffectManager.unloadEffect(id);

播放和停止

调用 playEffect 播放音效文件。根据需求，你可以多次调用 playEffect 同时播放多个音效文件。在播放音效文件时，你可以设置循环次数、音调、音量、播放位置等。

// 开始播放音效文件。
audioEffectManager.playEffect(
  0,  // 设置音效 ID。
  "your file path",  // 设置音效文件路径。
  -1,  // 设置音效循环播放的次数。-1 表示无限循环。 
  1,  // 设置的音效的音调。取值范围为 [0.5, 2.0]。1.0 表示原始音调。
  0.0,  // 设置的音效空间位置。取值范围为 [-1.0,1.0]。-1.0 表示音效出现在左边；0 表示音效出现在正前方；1 表示音效出现在右边。
  100,  // 设置音量。取值范围为 [0,100]，100 表示原始音量。 
  true,  // 设置是否将音效发布至远端。true 表示本地用户和远端用户都能听到音效；false 表示只有本地用户能听到音效。 
  0  // 设置音效文件的播放位置。0 表示从音效文件的第 0 ms 开始播放。
);

// 本地音效文件播放已结束回调。 
@Override
public void onAudioEffectFinished(int soundId) {
    super.onAudioEffectFinished(soundId);
}

成功播放后，你可以停止播放指定或全部的音效文件。

// 停止播放指定的音效文件。
audioEffectManager.stopEffect(id);

// 停止播放所有音效文件。
audioEffectManager.stopAllEffects();

暂停与恢复

在音效文件播放时，你可以暂停或恢复播放指定或全部音效文件。

// 暂停播放指定的音效文件。
audioEffectManager.pauseEffect(id);

// 暂停播放所有的音效文件。
audioEffectManager.pauseAllEffects();

// 恢复播放指定的音效文件。 
audioEffectManager.resumeEffect(id);

// 恢复播放所有的音效文件。
audioEffectManager.resumeAllEffects();

播放位置

如需在播放音效文件后调整播放位置，你可以调用本组方法。例如，在循环播放音效文件期间，你可以调用本组方法调整播放位置，无需停止播放。

// 获取指定本地音效文件的总时长。 
audioEffectManager.getEffectDuration("your file path");

// 设置指定音效文件的播放位置。500 表示从音效文件的第 500 ms 开始播放。 
audioEffectManager.setEffectPosition(id, 500);

// 获取指定音效文件的当前播放位置。
audioEffectManager.getEffectCurrentPosition(id);

音量

在音效文件开始播放后，你可以调用本组方法调节播放音量。例如，在循环播放音效文件期间，你可以调用本组方法调节播放音量，无需停止播放。

// 设置所有音效文件的播放音量。取值范围为 [0,100]，100 表示原始音量。 
audioEffectManager.setEffectsVolume(50.0);

// 设置指定音效文件的播放音量。取值范围为 [0,100]，100 表示原始音量。 
audioEffectManager.setVolumeOfEffect(id, 50.0);

// 获取音效文件的播放音量。音量范围为 [0,100]，100 表示原始音量。 
audioEffectManager.getEffectsVolume();

API 参考

• preloadEffect
• unloadEffect
• playEffect
• stopEffect
• stopAllEffects
• pauseEffect
• pauseAllEffects
• resumeEffect
• resumeAllEffects
• getEffectDuration
• setEffectPosition
• getEffectCurrentPosition
• setEffectsVolume
• setVolumeOfEffect
• getEffectsVolume
• onAudioEffectFinished

音乐混音

音乐混音是指将音乐文件与麦克风采集的音频混合。使用混音功能的用户通常会播放比较长的音乐文件，并且同一时间只播放一个音乐文件。例如，在唱歌时播放伴奏，在聊天时播放背景音乐。

Agora 提供一组方法播放和管理音乐文件，主要包括如下功能：

• 播放本地或在线音乐文件
• 设置音乐文件的播放次数、播放位置、音量、音调等播放选项
• 灵活控制音乐文件的播放、暂停、恢复与停止
• 报告当前的音乐文件播放状态和播放状态改变的原因

成功调用 startAudioMixing 后，当音乐文件播放状态发生改变时，SDK 会触发 onAudioMixingStateChanged 回调。

播放和停止

调用 startAudioMixing 播放音乐文件。在播放音乐文件时，可以设置循环次数、播放位置等。

// 开始播放音乐文件。
engine.startAudioMixing(
  "your file path",  // 指定需要混音的本地或在线音乐文件的绝对路径。
  false,  // 设置是否只在本地播放音乐文件。true 表示只有本地用户能听到音乐；false 表示本地用户和远端用户都能听到音乐。
  false,  // 设置是否用音乐文件替换麦克风采集的音频。true 表示用户只能听到音乐；false 表示用户可以听到音乐和麦克风采集的音频。
  -1,  // 设置音乐文件的播放次数。-1 表示循环播放。 
  0  // 设置音乐文件的播放位置。0 表示从音乐文件的第 0 ms 开始播放。 
);

// 本地用户的音乐文件播放状态已改变回调。 
@Override
public void onAudioMixingStateChanged(int state, int reason) {
    super.onAudioMixingStateChanged(state, reason);
}

成功播放音乐文件后，你可以调用 stopAudioMixing 停止播放。

//停止播放音乐文件。
engine.stopAudioMixing();

暂停与恢复

在音乐文件播放时，你可以暂停或恢复播放音乐文件。

// 暂停播放音乐文件。 
engine.pauseAudioMixing();

// 恢复播放音乐文件。 
engine.resumeAudioMixing();

播放位置

在音乐文件播放时，你可以调用本组方法调整音乐文件的播放位置，无需停止播放。

// 获取当前音乐文件的总时长。 
engine.getAudioMixingDuration();

// 设置当前音乐文件的播放位置。500 表示从音乐文件的第 500 ms 开始播放。 
engine.setAudioMixingPosition(500); 

// 获取音乐文件的当前播放位置。 
engine.getAudioMixingCurrentPosition();

音量与音调

成功播放音乐文件后，你可以调用本组方法调整音乐文件的播放音量与音调，无需停止播放。

// 调节当前音乐文件在本地和远端的播放音量。取值范围为 [0,100]，100 表示原始音量。 
engine.adjustAudioMixingVolume(50);

// 调节当前音乐文件在远端的播放音量。取值范围为 [0,100]，100 表示原始音量。 
engine.adjustAudioMixingPublishVolume(50); 

// 调节当前音乐文件在本地的播放音量。取值范围为 [0,100]，100 表示原始音量。 
engine.adjustAudioMixingPlayoutVolume(50); 

// 获取当前音乐文件在本地的播放音量。音量范围为 [0,100]，100 表示原始音量。 
engine.getAudioMixingPlayoutVolume(); 

// 获取当前音乐文件在远端的播放音量。音量范围为 [0,100]，100 表示原始音量。 
engine.getAudioMixingPublishVolume(); 

// 调节当前音乐文件的音调。取值范围为 [-12,12]，0 表示原始音调，1 表示升高一个半音。
engine.setAudioMixingPitch(5);

API 参考

• startAudioMixing
• stopAudioMixng
• pauseAudioMixing
• resumeAudioMixing
• getAudioMixingDuration
• setAudioMixingPosition
• getAudioMixingCurrentPosition
• adjustAudioMixingVolume
• adjustAudioMixingPublishVolume
• adjustAudioMixingPlayoutVolume
• getAudioMixingPlayoutVolume
• getAudioMixingPublishVolume
• setAudioMixingPitch
• onAudioMixingStateChanged

相关链接

当播放音乐文件时，你还可以参考如下文档：

• 为什么 Android 10 无法使用 startAudioMixing 播放背景音乐？