开发者中心
互动直播
Agora.io 社区
中文
search-icon
播放音频文件
更新时间 2020/12/04 01:39:56

功能描述

在通话或直播过程中，除了用户自己说话的声音，有时候需要播放自定义的声音或者音乐文件并且让频道内的其他人也听到，比如需要给游戏添加音效，或者需要播放背景音乐等，Agora 提供以下两组方法可以满足播放音效和音乐文件的需求。

开始前请确保已在你的项目中实现基本的实时音视频功能。 详见开始音视频通话或开始互动直播。

示例项目

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

播放音效文件

音效通常指持续很短的音频。播放音效文件方法主要用来播放短小的氛围音，比如鼓掌、游戏子弹撞击声音等，可以多个音效叠加播放。
音效由音频文件路径指定，但在 SDK 内部使用 sound id 来识别和处理音效。SDK 并不强制如何定义 sound id，保证每个音效有唯一的识别即可。一般的做法有自增 id，使用音效文件名的 hashCode 等。

实现方法

// 设置根据指定的音效文件路径自动分配 soundId，并将音效文件路径和 soundId 关联。
m_mapEffect.insert(std::make_pair(filePath, m_soundId++));

// 将指定的音效文件预加载至内存。需注意音效文件的大小，并在加入频道前完成加载。
m_rtcEngine->preloadEffect(m_mapEffect[strEffect], filePath);

// 设置音效循环播放的次数，-1 代表无限循环。
int loops = -1;

// 设置的音效的音调，取值范围为 [0.5, 2.0]。
double pitch = 1.5;

// 设置音量，取值范围 [0,100]，100 代表原始音量。
int gain = 100;

// 设置的音效空间位置。1.0 表示音效出现在右边。
double pan = 1.0;

// 设置是否将音效传到远端。
BOOL publish = true;

// 播放指定的音效文件。
m_rtcEngine->playEffect(m_mapEffect[strEffect], filePath, loops, pitch, pan, gain, publish);

// 停止播放指定的音效文件。
m_rtcEngine->stopEffect(m_mapEffect[strEffect]);

// 暂停播放指定的音效文件。
m_rtcEngine->pauseEffect(m_mapEffect[strEffect]);

// 暂停播放所有音效文件。
m_rtcEngine->pauseAllEffects();

// 设置音效文件的播放音量，取值范围为 [0,100]。
m_rtcEngine->setEffectsVolume(50);

// 恢复播放所有音效文件。
m_rtcEngine->resumeAllEffects();

// 停止播放所有音效文件。
m_rtcEngine->stopAllEffects();

// 释放预加载的音效文件。
m_rtcEngine->unloadEffect(m_mapEffect[strEffect]);

API 参考

开发注意事项

  • 预加载不是一个必须的步骤，一般来说为了提高性能或者需要反复播放某个特定的音效的时候，我们建议使用预加载。但如果音效文件较大，不建议预加载。
  • 以上方法都有返回值，返回值小于 0 表示方法调用失败。

音乐混音

混音是指播放本地或者在线音乐文件，同时让频道内的其他人听到此音乐。混音方法主要用来播放比较长的背景音，比如直播的时候播放的音乐，同时只可以有一个文件播放。如果在混音播放第一个文件的过程中播放第二个文件，会自动停止第一个文件的播放。

Agora 混音功能支持如下设置：

  • 混音或替换： 混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音（叠加）并编码发送给对方；替换指的是麦克风采集的音频被音乐文件的音频流替换掉，对方只能听见音乐播放。
  • 循环：可以设置是否循环播放混音文件，以及循环次数。
  • 调节音量：可以同时或分别调节音乐文件在本地和远端的播放音量。
  • 调节音调：可以分别调节本地人声的音调和音乐文件的音调。

实现方法

// 指定需要混音的本地或在线音频文件的绝对路径。
std::string filePath = "http://www.hochmuth.com/mp3/Haydn_Cello_Concerto_D-1.mp3";

// 设置是否只有本地用户可以听到混音的音频。true 表示只有本地用户可以听到混音的音频；false 表示本地用户和远端用户都能听到混音的音频。
BOOL loopback = false;

// 设置是否将混音文件内容替换麦克风采集的声音。true 只推送指定的本地音频文件或者线上音频文件；false 表示本地音频文件与来自麦克风的音频流混音。
BOOL replace = true;

// 设置循环播放次数。
int cycle = 1;

// 开始播放混音。
int nRet = m_rtcEngine->startAudioMixing(filePath, loopback, replace, cycle);

// 调节本地用户听到的音乐文件音量，取值范围为 [0,100]。
m_rtcEngine->adjustAudioMixingPlayoutVolume(50);

// 调节远端用户听到的音乐文件音量，取值范围为 [0,100]。
m_rtcEngine->adjustAudioMixingPublishVolume(50);

//停止播放音乐文件。
m_rtcEngine->stopAudioMixing();

API 参考

开发注意事项

  • 在频道内调用混音方法，否则会有潜在问题。
  • 以上方法都有返回值，返回值小于 0 表示方法调用失败。
score