音效与混音文件

功能描述

在音视频通话过程中,部分场景中除了用户自己说话的声音,有时候希望让远端用户听到特殊的音频文件,比如氛围音效文件、伴奏音乐文件。NERTC SDK 提供以下方法可以满足播放音效和音乐文件的需求。

播放音效文件

音效是指较短的音频,多用来渲染房间气氛,比如鼓掌、喝彩等氛围音效,支持多个音效叠加播放。

NERTC SDK 混音功能支持如下设置:

  1. 混音:混音指的是音效文件的音频流跟麦克风采集的音频流进行混音(叠加)并编码发送给对方;
  2. 循环:可以设置是否循环播放混音文件,以及循环次数。
  3. 音量控制:可以各自控制本地播放以及编码发送的混音音量

播放混音文件

混音是指播放本地或者在线音乐文件,同时让频道内的其他人听到此音乐。NERtc播放混音方法可以用来播放比较长的背景音,比如直播的时候播放的音乐。

NERTC SDK 混音功能支持如下设置:

  1. 混音:混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音(叠加)并编码发送给对方;
  2. 循环:可以设置是否循环播放混音文件,以及循环次数。
  3. 定位:混音任务支持从文件的任意位置开始播放
  4. 音量控制:可以各自控制本地播放以及编码发送的混音音量

Android

实现方法

参考如下步骤,在你的项目中实现播放混音文件:

  1. 在加入频道成功后调用 startAudioMixing 开始混音。
  2. 根据 pauseAudioMixing、resumeAudioMixing 等操作 进行 暂停、恢复、控制音量、定位 等功能。
  3. 在离开频道前调用 stopAudioMixing 结束混音。

示例代码

// 首先设置混音参数
NERtcCreateAudioMixingOption option = new NERtcCreateAudioMixingOption();
option.path = "/sdcard/test.mp3"; //混音文件路径
option.playbackEnabled = true;    //是否本地播放
option.playbackVolume = 100;      //本地播放音量
option.sendEnabled = true;        //是否编码发送
option.sendVolume = 100;          //发送音量
option.loopCount = 1;             //循环次数
int ret = NERtcEx.getInstance().startAudioMixing(option);; //开始混音任务
if(ret == NERtcConstants.ErrorCode.OK) {
    //创建混音任务成功
}else {
    //创建混音任务失败
}

// 暂停、恢复混音任务
NERtcEx.getInstance().pauseAudioMixing();
NERtcEx.getInstance().resumeAudioMixing();

// 获取和设置本地播放混音的音量,范围为 0 ~ 100
int volume = NERtcEx.getInstance().getAudioMixingPlaybackVolume();
NERtcEx.getInstance().setAudioMixingPlaybackVolume(volume);

// 获取和设置编码发送混音的音量,范围为 0 ~ 100
int volume = NERtcEx.getInstance().getAudioMixingSendVolume();
NERtcEx.getInstance().setAudioMixingSendVolume(volume);

// 获取混音文件总时长
long time = NERtcEx.getInstance().getAudioMixingDuration();

// 获取当前混音文件播放位置
long position = NERtcEx.getInstance().getAudioMixingCurrentPosition();

// 设置混音文件播放位置
NERtcEx.getInstance().seekAudioMixingPosition(position);

// 结束混音任务
NERtcEx.getInstance().stopAudioMixing();

API参考

方法 功能描述
startAudioMixing 开始混音
stopAudioMixing 结束混音
pauseAudioMixing 暂停混音
resumeAudioMixing 恢复混音
setAudioMixingPlaybackVolume 设置混音播放音量
setAudioMixingSendVolume 设置伴奏的发送音量
getAudioMixingPlaybackVolume 获取混音的播放音量
getAudioMixingSendVolume 获取混音的发送音量
getAudioMixingDuration 获取混音的总长度
setAudioMixingPosition 设置混音的播放进度
getAudioMixingCurrentPosition 获取混音当前播放进度
事件 事件描述
onAudioMixingStateChanged 伴音状态回调
onAudioMixingTimestampUpdate 伴奏播放进度回调

开发注意事项

iOS

实现方法

参考如下步骤,在你的项目中实现播放混音文件:

  1. 初始化混音配置类,自定义各项设置;
  2. 加入频道成功后调用 - (int)startAudioMixingTaskWithOption:(NERtcCreateAudioMixingOption *)option 创建混音任务;
  3. 对伴音任务可以进行 暂停、恢复、控制音量、定位 等功能;
  4. 调用 - (int)stopAudioMixing 结束混音任务;

示例代码

NSString *path = [[NSBundle mainBundle] pathForResource:@"1" ofType:@"m4a"];
NERtcCreateAudioMixingOption option = [[NERtcCreateAudioMixingOption alloc] init];
option.path = path;               //混音文件路径
option.playbackEnabled = YES;    //是否本地播放(默认为YES)
option.playbackVolume = 100;      //本地播放音量
option.sendEnabled = YES;        //是否编码发送(默认为YES)
option.sendVolume = 100;          //发送音量
option.loopCount = 1;             //循环次数
int ret = 
[self.engine startAudioMixingWithOption:option]; //开始混音任务
if (ret == kNERtcNoError) {
    //创建混音任务成功
} else {
    //创建混音任务失败
}

// 暂停、恢复混音任务
[self.engine pauseAudioMixing];
[self.engine resumeAudioMixing];

// 获取和设置本地播放混音的音量,范围为 0 ~ 100
int volume = 0;
[self.engine getAudioMixingPlaybackVolume:&volume];
[self.engine setAudioMixingPlaybackVolume:volume];

// 获取和设置编码发送混音的音量,范围为 0 ~ 100
//int volume;
[self.engine getAudioMixingSendVolume:&volume];
[self.engine setAudioMixingSendVolume:volume];

// 获取混音文件总时长
uint64_t duration;
[self.engine getAudioMixingDuration:&duration];
// 获取当前混音文件播放位置
uint64_t position;
[self.engine getAudioMixingCurrentPosition:&position];

// 设置混音文件播放位置
[self.engine setAudioMixingPosition:position];

// 结束混音任务
[self.engine stopAudioMixing];

API参考

方法 功能描述
startAudioMixingWithOption 开始播放音乐文件
stopAudioMixing 停止播放音乐文件
pauseAudioMixing 暂停播放音乐文件
resumeAudioMixing 恢复播放音乐文件
setAudioMixingPlaybackVolume 设置音乐文件播放音量
setAudioMixingSendVolume 设置音乐文件的发送音量
getAudioMixingPlaybackVolume 获取音乐文件的播放音量
getAudioMixingSendVolume 获取音乐文件的发送音量
getAudioMixingDuration 获取音乐文件的总长度
setAudioMixingPosition 设置音乐文件的播放进度
getAudioMixingCurrentPosition 获取音乐文件当前播放进度
事件 事件描述
onAudioMixingStateChanged 本地用户的音乐文件播放状态改变回调
onAudioMixingTimestampUpdate 音乐文件播放进度回调

开发注意事项

  1. 音量设置取值范围: 0~100;
  2. 本地混音文件支持格式: .m4a, .mp3, .wav, .acc;

Windows/macOS

实现方法

参考如下步骤,在你的项目中实现播放混音文件:

  1. 在加入频道成功后调用 startAudioMixing 开始混音。
  2. 根据 pauseAudioMixingresumeAudioMixing 等操作 进行 暂停、恢复、控制音量、定位 等功能。
  3. 在离开频道前调用 stopAudioMixing 结束混音。

示例代码

// 首先设置混音参数
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;             //循环次数
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);

// 获取混音文件总时长
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 开始播放伴奏
stopAudioMixing 停止播放伴奏
pauseAudioMixing 暂停播放伴奏
resumeAudioMixing 恢复播放伴奏
setAudioMixingPlaybackVolume 设置伴奏播放音量
setAudioMixingSendVolume 设置伴奏的发送音量
getAudioMixingPlaybackVolume 获取伴奏的播放音量
getAudioMixingSendVolume 获取伴奏的发送音量
getAudioMixingDuration 获取伴奏的总长度
setAudioMixingPosition 设置伴奏的播放进度
getAudioMixingCurrentPosition 获取伴奏当前播放进度
事件 事件描述
onAudioMixingStateChanged 伴奏播放状态改变回调
onAudioMixingTimestampUpdate 伴奏播放进度回调

开发注意事项

Web

实现方法

参考如下步骤,在你的项目中实现播放云端混音文件:

  1. 在加入频道成功后调用 startAudioMixing 开始混音。
  2. 根据 pauseAudioMixingresumeAudioMixing 等操作 进行 暂停、恢复、控制音量、seek 等功能。
  3. 在离开频道前调用 stopAudioMixing 结束混音。

示例代码

开始文件混音任务
const audioMixingEndHandler = function(event){
  console.warn('伴音结束: ', event)
}

const options = {
  audioFilePath: '"someaudio.mp3"', 
  loopback: false,
  replace: false,
  cycle: 0,
  playStartTime: 0,
  volume: 200,
  auidoMixingEnd: audioMixingEndHandler
}
localStream.startAudioMixing(options).then(res=>{
  console.log('伴音成功')
}).catch(err=>{
  console.error('伴音失败: ', err)
})
参数名 类型 说明
audioFilePath String 必须,云端音频文件路径
loopback Boolean 可选,是否循环播放,缺省为false,即播放一次就结束(这里如果是false,则cycle参数不生效)
replace Boolean 可选,是否替换麦克风采集的音频数据,缺省为false
cycle number 可选,表示循环播放的次数,需要loopback参数置为true(如果想无限循环,cycle设置为0,loopback设置为true),缺省为0,如果loopback为true,表示无限循环,如果loopback为false,该参数不生效
playStartTime number 可选,设置音频文件开始播放的位置,单位为 s。缺省设为 0,即从头开始播放
volume number 可选,设置音频文件的音量,范围(0-255)
auidoMixingEnd Function 可选,伴音文件播放完成时的通知反馈

err(格式是Object)伴音错误码,属性如下:

err属性名 类型 说明
name string 错误名称
code number 错误码
desc string 错误描述

startAudioMixing接口可能出现的错误码:

name code desc
'AudioMixingUnsupport' 63102 '该浏览器不支持伴音功能'
'AudioFileDownloadError' 63101 '伴音文件加载失败'
'AudioStreamFetchError' 63002 '获取麦克风音频流失败'
'AudioDisabled' 63007 '音频功能已被禁用'
暂停本地语音伴音
localStream.pauseAudioMixing().then(res=>{
  console.log('暂停伴音成功')
}).catch(err=>{
  console.error('暂停伴音失败: ', err)
})

err(格式是Object)伴音错误码,属性如下:

err属性名 类型 说明
name string 错误名称
code number 错误码
desc string 错误描述

pauseAudioMixing接口可能出现的错误码

name code desc
'AudioMixingUnsupport' 63102 '该浏览器不支持伴音功能'
'pausedMusicalAccompaniment' 63104 '已经暂停伴音'
'UnstartMusicalAccompaniment' 63105 '当前没有伴音'
恢复本地语音伴音
localStream.resumeAudioMixing().then(res=>{
  console.log('恢复伴音成功')
}).catch(err=>{
  console.error('恢复伴音失败: ', err)
})

err(格式是Object)伴音错误码,属性如下:

err属性名 类型 说明
name string 错误名称
code number 错误码
desc string 错误描述

resumeAudioMixing接口可能出现的错误码

name code desc
'AudioMixingUnsupport' 63102 '该浏览器不支持伴音功能'
'UnpauseMusicalAccompaniment' 63103 '已经暂停伴音'
'UnstartMusicalAccompaniment' 63105 '当前没有伴音'
停止伴音
localStream.stopAudioMixing().then(res=>{
  console.log('停止伴音成功')
}).catch(err=>{
  console.error('停止伴音失败: ', err)
})

err(格式是Object)伴音错误码,属性如下:

err属性名 类型 说明
name string 错误名称
code number 错误码
desc string 错误描述

stopAudioMixing接口可能出现的错误码

name code desc
'AudioMixingUnsupport' 63102 '该浏览器不支持伴音功能'
'UnstartMusicalAccompaniment' 63105 '当前没有伴音'
设置伴音的音量
const volume = 100
localStream.adjustAudioMixingVolume(volume).then(res=>{
  console.log('设置伴音的音量成功')
}).catch(err=>{
  console.error('设置伴音的音量失败: ', err)
})
参数名 类型 说明
volume Number 必须,设置的音量,取值0-255

err(格式是Object)伴音错误码,属性如下:

err属性名 类型 说明
name string 错误名称
code number 错误码
desc string 错误描述

stopAudioMixing接口可能出现的错误码

name code desc
'AudioMixingUnsupport' 63102 '该浏览器不支持伴音功能'
'UnstartMusicalAccompaniment' 63105 '当前没有伴音'
'ParamError' 11405 '参数错误'
获取伴音文件的总时长

const audioFileTotalTime = localStream.getAudioMixingDuration()
audioFileTotalTime属性 类型 说明
totalTime Number 音乐文件总时长,单位是s
设置伴音播放的位置
const playStartTime = 10
localStream.setAudioMixingPosition(playStartTime).then(res=>{
  console.log('设置伴音播放的位置成功')
}).catch(err=>{
  console.error('设置伴音播放的位置失败: ', err)
})
参数名 类型 说明
playStartTime Number 必须,设置的开始播放时间,取值0-音乐文件的总时长

err(格式是Object)伴音错误码,属性如下:

err属性名 类型 说明
name string 错误名称
code number 错误码
desc string 错误描述

stopAudioMixing接口可能出现的错误码

name code desc
'AudioMixingUnsupport' 63102 '该浏览器不支持伴音功能'
'UnstartMusicalAccompaniment' 63105 '当前没有伴音'
'ParamError' 11405 '参数错误'
获取伴音文件的播放进度

const audioFilePlayedTime = netcall.getAudioMixingCurrentPosition()
audioFilePlayedTime属性 类型 说明
playedTime Number 音乐文件已经播放了多久,单位是s

API参考

方法 功能描述
startAudioMixing 开始播放音乐文件和本地麦克风声音的混合
pauseAudioMixing 暂停播放音乐文件
resumeAudioMixing 恢复播放音乐文件
stopAudioMixing 停止播放音乐文件
adjustAudioMixingVolume 调节音乐文件播放音量
getAudioMixingDuration 获取音乐文件的总长度
setAudioMixingPosition 获取音乐文件当前播放进度