播放音效或音乐文件

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

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

技术原理

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

• 音效 API：播放持续时间短的氛围音，例如掌声、欢呼声、打斗声、枪击声等，通常可以同时播放多个音效文件。
• 音乐 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，在你的项目中播放音效和音乐混音文件。

实现播放音效

音效 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 表示原始音调

   展开全部 48 行

播放音乐

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

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

   XML

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

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

   Java

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

   展开全部 28 行

相关文档

本节提供了在实现播放音效或音乐功能时可能需要的相关文档。

示例项目

声网在 GitHub 上提供了一个开源的 PlayAudioFiles 示例项目。你可以前往下载或查看其中的源代码。

API 参考

• playEffect
• onAudioEffectFinished
• startAudioMixing
• onAudioMixingStateChanged

相关文档

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

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

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