在通话或直播过程中,除了用户自己说话的声音,有时候需要播放自定义的声音或者音乐文件并且让频道内的其他人也听到,比如需要给游戏添加音效,或者需要播放背景音乐等,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]);
preloadEffect
playEffect
pauseEffect
pauseAllEffects
resumeEffect
resumeAllEffects
stopEffect
stopAllEffects
unloadEffect
混音是指播放本地或者在线音乐文件,同时让频道内的其他人听到此音乐。混音方法主要用来播放比较长的背景音,比如直播的时候播放的音乐,同时只可以有一个文件播放。如果在混音播放第一个文件的过程中播放第二个文件,会自动停止第一个文件的播放。
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();
startAudioMixing
stopAudioMixng
adjustAudioMixingVolume
adjustAudioMixingPublishVolume
adjustAudioMixingPlayoutVolume
setLocalVoicePitch
setAudioMixingPitch
pauseAudioMixing
resumeAudioMixing
getAudioMixingDuration
getAudioMixingCurrentPosition
setAudioMixingPosition
onAudioMixingStateChanged