音效与混音文件
更新时间: 2024/08/05 15:02:55
在音视频通话或直播场景中,默认情况下只有房间成员本人说话的人声。出于烘托气氛、营造多样化语音环境的需求,NERTC SDK 支持通过混音功能播放多个掌声、口哨等短时音效,或者为人声添加背景音乐、伴奏音乐或其他场景效果,并将合成后的声音播放给房间内其他成员。
功能概述
混音,指 SDK 从 App 获取一路音频数据,将 App 提供的音频数据与 SDK 采集的音频数据整合为一路音频数据,通常用于音乐直播、在线KTV、连麦PK、游戏直播等场景。
NERTC SDK 提供混音相关方法,实现播放短时音效和背景音乐的功能。
-
播放短时音效:
指通话或直播中播放短时音频文件,一般用于渲染房间气氛,例如游戏音效、掌声、口哨、欢呼声、笑声的短时音效。支持多个音效叠加播放。
-
播放背景音乐:
伴音功能支持在房间中播放本地或者在线音乐文件,作为通话或直播时的背景声音,同时让房间内的其他人听到此音乐。NERTC 播放伴音方法可以用来播放比较长的背景音,例如伴奏音乐、环境白噪声、背景音乐等等。
NERTC 支持在麦克风关闭的状态下,发送伴音。在娱乐社交、在线教育等场景中,即使用户不想要开启麦克风进行语音聊天,也能在房间内播放背景音乐。
NERTC SDK 混音功能支持如下设置:
-
混音:支持将音乐文件的音频流跟麦克风采集的音频流(主流)进行叠加并编码发送给对方,同时伴音功能支持通过辅流通道传输音乐文件的音频流。
-
循环:可以设置是否循环播放混音文件,以及循环次数。
-
音量控制:可以各自控制本地播放以及编码发送的混音音量。
-
音调控制:可以按半音音阶调整本地播放的音乐文件的音调。例如在 K 歌场景中,为了使歌曲更适合主播的声线音域,主播可以调整伴音的音调,升高或降低伴奏的音阶。
-
定位:混音任务支持从背景音乐文件的任意位置开始播放。
-
叠加:可以同时播放多个短时音效文件。
注意事项
- 伴音相关方法的返回值不等于 0,表示方法调用失败。
- 在加入房间前或加入房间后都可以开启伴音和音效。
- 本地混音文件支持 MP3、M4A、AAC、3GP、WMA、WAV 格式,支持本地文件和在线 URL。
- 可通过
onAudioMixingStateChanged
回调接收音乐文件播放状态改变的相关信息,如果播放出错,可通过对应错误码排查故障。
配置音效
配置步骤
- 在调用
playEffect
方法播放指定effect_id
的音效文件。调用此方法时,您需要设置option
参数指定播放的音效文件。相关参数的含义如下表。
参数 | 参数说明 |
---|---|
path | 指定音效文件的路径,例如 D:\\audio_files\\test.mp3 。支持本地绝对路径或 URL 地址。 |
effect_id | 指定音效文件的 ID。 |
loop_count | 指定音效文件循环播放的次数。该参数为正整数,可取最大值为 10000,默认值为 1,即默认仅播放一次。若该值小于等于 0,则默认为无限循环播放。 |
send_enabled | 是否将音效发送至远端。该参数的默认值为 YES,即远端用户可以听到该音效。 |
send_volume | 音效文件的发送音量。该参数的取值范围为 0 ~ 200,默认值为 100,表示使用文件的原始音量。 |
playback_enabled | 是否本地播放该音效。默认为 YES,即本地用户可以听到该音效。 |
playback_volume | 音效文件的播放音量。该参数的取值范围为 0 ~ 200,默认值为 100,表示使用文件的原始音量。 |
- 您可以多次调用此方法以同时播放多个音效文件,实现音效的叠加。
- 在调用此方法成功播放指定音效文件后,若您反复停止再重新播放该
effect_id
对应的音效文件,首次播放时设置的option
无效,会恢复为默认值。
-
音效播放任务管理。开始播放音效后,您还可以通过其他方法实现音效播放任务管理等更多功能,例如:
-
进度管理:调用
pauseAllEffects
方法暂停播放所有音效、调用resumeAllEffects
方法恢复播放所有音效、调用setEffectPosition
方法设置音效文件的播放位置等,此外也可以通过注册onAudioEffectTimestampUpdate
回调以监听音效文件的实时播放进度 -
音量管理:调用
setEffectSendVolume
方法设置音效文件发送音量、调用setEffectPlaybackVolume
方法设置音效文件播放音量。 -
音调管理:调用
setEffectPitch
方法并通过pitch
参数设置音效文件的音调。- 仅开始播放音效文件后可调用此方法;播放结束后,音调将恢复为默认值。
- 音调
pitch
参数的取值范围为 [-12,12],默认值为 0,每相邻两个值的音调高度相差半音;取值的绝对值越大,音调升高或降低得越多。 - 若 SDK 返回 30003,表示参数设置错误;若 SDK 返回 30005,表示引擎尚未初始化或未找到当前音效文件。
-
获取音效相关信息:调用
getEffectDuration
方法获取音效文件时长、调用getEffectCurrentPosition
方法获取音效文件当前播放进度、调用getEffectPitch
方法获取音效文件的音调等。
-
-
在离开房间前,调用
stopAllEffects
方法结束播放所有音效。
示例代码
// 调用 playEffect 播放指定的音效文件
NERtcCreateAudioEffectOption option;
option.path = "path";
option.loop_count = 1;
option.send_enabled = true;
option.playback_enabled = true;
option.send_volume = 100;
option.playback_volume = 100;
rtc_engine_->playEffect(effect_id, option);
// 调用 stopEffect 结束播放音效文件
rtc_engine_->stopEffect(effect_id);
// 调用 pauseEffect 暂停播放音效文件
rtc_engine_->pauseEffect(effect_id);
// 调用 resumeEffect 恢复播放音效文件
rtc_engine_->resumeEffect(effect_id);
// 调用 pauseAllEffects 暂停所有音效播放
rtc_engine_->pauseAllEffects();
// 调用 resumeAllEffects 恢复所有音效播放
rtc_engine_->resumeAllEffects();
// 调用 setEffectPosition 设置指定音效文件的播放进度
uint32_t effect_id = 7788;
uint64_t timestamp_ms = 0;
rtc_engine_->setEffectPosition(effect_id, timestamp_ms);
// 调用 setEffectSendVolume 设置音效文件发送音量
uint32_t volume = 50;
rtc_engine_->setEffectSendVolume(effect_id, volume);
// 调用 getEffectSendVolume 获取音效文件发送音量
uint32_t volume = 0;
rtc_engine_->getEffectSendVolume(effect_id, &volume);
// 调用 setEffectPlaybackVolume 设置音效文件播放音量
uint32_t volume = 50;
rtc_engine_->setEffectPlaybackVolume(effect_id, volume);
// 调用 getEffectPlaybackVolume 设置音效文件播放音量
uint32_t volume = 0;
rtc_engine_->getEffectPlaybackVolume(effect_id, &volume);
// 调用 setEffectPitch 设置音效文件音调
int32_t pitch = 6;
rtc_engine_->setEffectPlaybackVolume(effect_id, pith);
// 调用 getEffectPitch 获取音效文件音调
int32_t pitch = 0;
rtc_engine_->getEffectPitch(effect_id, &pitch);
// 调用 getEffectDuration 获取指定音效文件时长
uint64_t effect_id = 7788;
uint64_t duration_ms = 0;
rtc_engine_->getEffectDuration(effect_id, &duration_ms);
// 调用 getEffectCurrentPosition 获取指定音效文件的播放进度
uint64_t effect_id = 7788;
uint64_t timestamp_ms = 0;
rtc_engine_->getEffectCurrentPosition(effect_id, ×tamp_ms);
// 调用 stopAllEffects 结束音效播放
rtc_engine_->stopAllEffects();
API 参考
方法 | 功能描述 |
---|---|
playEffect |
播放指定音效文件 |
stopEffect |
停止播放指定音效文件 |
pauseEffect |
暂停播放指定音效文件 |
resumeEffect |
恢复播放指定音效文件 |
stopAllEffects |
停止播放所有音效文件 |
pauseAllEffects |
暂停播放所有音效文件 |
resumeAllEffects |
恢复播放所有音效文件 |
setEffcetSendVolume |
设置音效文件的发送音量 |
setEffcetPlaybackVolume |
设置音效文件的播放音量 |
setEffectPitch |
设置音效文件音调 |
getEffectSendVolume |
获取音效文件的发送音量 |
getEffcetPlaybackVolume |
获取音效文件的播放音量 |
getEffectPitch |
获取音效文件音调 |
setEffectPosition |
设置音效文件的播放位置 |
getEffectDuration |
获取音效文件时长 |
getEffectCurrentPosition |
获取音效文件当前播放进度 |
事件 | 事件描述 |
---|---|
onAudioEffectFinished |
本地音效文件播放已结束回调 |
onAudioEffectTimestampUpdate |
本地音效文件播放进度信息回调 |
配置伴音
配置步骤
-
初始化伴音配置类,通过
NERtcCreateAudioMixingOption
设置伴音任务相关参数,例如伴音文件路径、是否本地播放、是否通过辅流通道传输等等。若您选择通过辅流通道传输伴音音频流,请先调用
enableLocalSubStreamAudio
方法开启音频辅流。 -
调用
startAudioMixing
开始伴音。 -
伴音任务管理。开始伴音后,还可以通过其他方法实现伴音任务管理等更多功能,例如:
-
进度管理: 通过
pauseAudioMixing
和resumeAudioMixing
暂停或恢复伴音、通过setAudioMixingPosition
设置伴音文件的播放进度。 -
音量管理:通过
setAudioMixingPlaybackVolume
和setAudioMixingSendVolume
等方法设置伴音的播放音量、伴音的发送音量。 -
音调管理:调用
setAudioMixingPitch
方法并通过pitch
参数设置伴音文件的音调。- 仅开始伴音后可调用此方法;伴音结束后,音调将恢复为默认值。
- 音调
pitch
参数的取值范围为 [-12,12],默认值为 0,每相邻两个值的音调高度相差半音;取值的绝对值越大,音调升高或降低得越多。 - 若 SDK 返回 30003,表示参数设置错误;若 SDK 返回 30005,表示引擎尚未初始化或未找到当前伴音文件。
-
获取伴音相关信息:调用
getAudioMixingCurrentPosition
方法获取伴音文件的播放进度、调用getAudioMixingPitch
方法获取伴音文件的音调等。
-
-
在离开房间前调用
stopAudioMixing
结束伴音。
示例代码
c++// 首先设置伴音参数
NERtcCreateAudioMixingOption option;
option.path = "D:\\audio_files\\test.mp3"; //伴音文件的全路径
option.playback_enabled = true; //是否本地播放
option.playback_volume = 100; //本地播放音量
option.send_enabled = true; //是否编码发送
option.send_volume = 100; //发送音量
option.loop_count = 1; //循环次数
option.start_timestamp = 0; //音乐文件开始播放的时间,UTC 时间戳
option.send_with_audio_type = nertc::kNERtcAudioStreamTypeMain; //伴音跟随音频主流还是辅流,默认跟随主流
int res = kNERtcErrFatal;
if (nrtc_engine_)
{
res = nrtc_engine_->startAudioMixing(&option);
}
if (kNERtcNoError == res)
{
//创建伴音任务成功
}
else
{
//创建伴音任务失败
}
// 暂停、恢复伴音任务
nrtc_engine_->pauseAudioMixing();
nrtc_engine_->resumeAudioMixing();
// 获取和设置本地播放伴音的音量,范围为 0 ~ 100
int volume = 0;
nrtc_engine_->getAudioMixingPlaybackVolume(&volume);
nrtc_engine_->setAudioMixingPlaybackVolume(volume);
// 获取和设置编码发送伴音的音量,范围为 0 ~ 100
volume = 0;
nrtc_engine_->getAudioMixingSendVolume(&volume);
nrtc_engine_->setAudioMixingSendVolume(volume);
// 获取和设置发送伴音的音调,范围为 -12 ~ 12
pitch = 0;
nrtc_engine_->getAudioMixingPitch(&pitch);
nrtc_engine_->setAudioMixingPitch(pitch);
// 获取伴音文件总时长
uint64_t duration = 0;
nrtc_engine_->getAudioMixingDuration(&duration);
// 获取当前伴音文件播放位置
uint64_t position = 0;
nrtc_engine_->getAudioMixingCurrentPosition(&position);
// 设置伴音文件播放位置
nrtc_engine_->seekAudioMixingPosition(position);
// 结束伴音任务
nrtc_engine_->stopAudioMixing();
API参考
方法 | 功能描述 |
---|---|
startAudioMixing |
开始播放伴音 |
enableLocalSubStreamAudio |
开启音频辅流 |
stopAudioMixing |
停止播放伴音 |
pauseAudioMixing |
暂停播放伴音 |
resumeAudioMixing |
恢复播放伴音 |
setAudioMixingPlaybackVolume |
设置伴音播放音量 |
setAudioMixingSendVolume |
设置伴音的发送音量 |
setAudioMixingPitch |
设置伴音的音调 |
getAudioMixingPlaybackVolume |
获取伴音的播放音量 |
getAudioMixingSendVolume |
获取伴音的发送音量 |
getAudioMixingPitch |
获取伴音的音调 |
getAudioMixingDuration |
获取伴音的总长度 |
setAudioMixingPosition |
设置伴音的播放进度 |
getAudioMixingCurrentPosition |
获取伴音当前播放进度 |
事件 | 事件描述 |
---|---|
onAudioMixingStateChanged |
伴音播放状态改变回调 |
onAudioMixingTimestampUpdate |
伴音播放进度回调 |