音效与伴音

更新时间: 2024/09/18 16:26:13

在音视频通话或直播场景中,默认情况下只有房间成员本人说话的人声。出于烘托气氛、营造多样化语音环境的需求,NERTC SDK 支持通过混音功能播放多个掌声、口哨等短时音效,或者为人声添加背景音乐、伴奏音乐或其他场景效果,并将合成后的声音播放给房间内其他成员。

功能概述

混音,指 SDK 从 App 获取一路音频数据,将 App 提供的音频数据与 SDK 采集的音频数据整合为一路音频数据,通常用于音乐直播、在线KTV、连麦PK、游戏直播等场景。

NERTC SDK 提供混音相关方法,实现播放短时音效和背景音乐的功能。

  • 播放短时音效:

    指通话或直播中播放短时音频文件,一般用于渲染房间气氛,例如游戏音效、掌声、口哨、欢呼声、笑声的短时音效。支持多个音效叠加播放。

  • 播放背景音乐:

    伴音功能支持在房间中播放本地或者在线音乐文件,作为通话或直播时的背景声音,同时让房间内的其他人听到此音乐。NERTC 播放伴音方法可以用来播放比较长的背景音,例如伴奏音乐、环境白噪声、背景音乐等等。

    NERTC 支持在麦克风关闭的状态下,发送伴音。在娱乐社交、在线教育等场景中,即使用户不想要开启麦克风进行语音聊天,也能在房间内播放背景音乐。

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

  • 混音:支持将音乐文件的音频流跟麦克风采集的音频流(主流)进行叠加并编码发送给对方,同时伴音功能支持通过辅流通道传输音乐文件的音频流。

  • 循环:可以设置是否循环播放混音文件,以及循环次数。

  • 音量控制:可以各自控制本地播放以及编码发送的混音音量。

  • 音调控制:可以按半音音阶调整本地播放的音乐文件的音调。例如在 K 歌场景中,为了使歌曲更适合主播的声线音域,主播可以调整伴音的音调,升高或降低伴奏的音阶。

  • 定位:混音任务支持从背景音乐文件的任意位置开始播放。

  • 叠加:可以同时播放多个短时音效文件。

注意事项

  • 伴音相关方法的返回值不等于 0,表示方法调用失败。
  • 加入房间前或加入房间后,均可启动音效和伴音。
  • 本地混音文件支持 MP3、M4A、AAC、3GP、WMA、WAV 格式,支持本地文件和在线 URL。
  • 可通过 onAudioMixingStateChanged 回调接收音乐文件播放状态改变的相关信息,如果播放出错,可通过对应错误码排查故障。

示例项目源码

网易云信提供音效与伴音的示例项目源码 SetBackgroundMusic,您可以参考该源码实现音效与伴音。

配置音效

配置步骤

  1. 调用 playEffectWitdId 方法播放指定 effectId 的音效文件。调用此方法时,您需要设置 option 参数指定播放的音效文件。相关参数的含义如下表。
参数 参数说明
path 指定音效文件的路径,例如 D:\\audio_files\\test.mp3。支持本地绝对路径或 URL 地址。
effectId 指定音效文件的 ID。
loopCount 指定音效文件循环播放的次数。该参数为正整数,可取最大值为 10000,默认值为 1,即默认仅播放一次。若该值小于等于 0,则默认为无限循环播放。
sendEnabled 是否将音效发送至远端。该参数的默认值为 YES,即远端用户可以听到该音效。
sendVolume 音效文件的发送音量。该参数的取值范围为 0 ~ 200,默认值为 100,表示使用文件的原始音量。
playbackEnabled 是否本地播放该音效。默认为 YES,即本地用户可以听到该音效。
playbackVolume 音效文件的播放音量。该参数的取值范围为 0 ~ 200,默认值为 100,表示使用文件的原始音量。
  • 您可以多次调用此方法以同时播放多个音效文件,实现音效的叠加。
  • 在调用此方法成功播放指定音效文件后,若您反复停止再重新播放该 effectId 对应的音效文件,首次播放时设置的 option 无效,会恢复为默认值。
  1. 音效播放任务管理。开始播放音效后,您还可以通过其他方法实现音效播放任务管理等更多功能,例如:
  • 进度管理:调用 pauseAllEffects 方法暂停播放所有音效、调用 resumeAllEffects 方法恢复播放所有音效、调用 setEffectPositionWithId 方法设置音效文件的播放位置等,此外也可以通过注册 onAudioEffectTimestampUpdateWithId 回调以监听音效文件的实时播放进度。
  • 音量管理:调用 setEffectSendVolumeWithId 方法设置音效文件的发送音量、调用 setEffectPlaybackVolumeWithId 方法设置音效文件的播放音量。
  • 音调管理:调用 setEffectPitchWithId 方法并通过 pitch 参数设置音效文件的音调。
    • 仅开始播放音效文件后可调用此方法;播放结束后,音调将恢复为默认值。
    • 音调 pitch 参数的取值范围为 [-12,12],默认值为 0,每相邻两个值的音调高度相差半音;取值的绝对值越大,音调升高或降低得越多。
    • 若 SDK 返回 30003,表示参数设置错误;若 SDK 返回 30005,表示引擎尚未初始化或未找到当前音效文件。
  • 获取混音相关信息:例如通过调用 getEffectDurationWithId 方法获取音效文件时长、调用 getEffectCurrentPositionWithId 方法获取音效文件当前播放进度、调用 getEffectPitchWithId 方法获取音效文件的音调等。
  1. 在离开房间前,调用 stopAllEffects 方法结束播放所有音效。

示例代码

// 调用 playEffectWitdId 播放指定的音效文件
NERtcCreateAudioEffectOption *option = [[NERtcCreateAudioEffectOption alloc] init];
option.path = @"path";
option.loopCount = 1;
option.sendEnabled = YES;
option.playbackEnabled = YES;
option.sendVolume = 100;
option.playbackVolume = 100;
[[NERtcEngine sharedEngine] playEffectWitdId:taskID effectOption:option];

// 调用 stopEffectWitdId 结束播放指定音效
[[NERtcEngine sharedEngine] stopEffectWitdId:taskID];

// 调用 pauseEffectWitdId 暂停播放指定音效
[[NERtcEngine sharedEngine] pauseEffectWitdId:taskID];

// 调用 resumeEffectWitdId 恢复播放指定音效
[[NERtcEngine sharedEngine] resumeEffectWitdId:taskID];

// 调用 pauseAllEffects 暂停播放所有音效
[[NERtcEngine sharedEngine] pauseAllEffects];

// 调用 resumeAllEffects 恢复播放所有音效
[[NERtcEngine sharedEngine] resumeAllEffects];

// 调用 setEffectSendVolumeWithId 设置音效文件发送音量
[[NERtcEngine sharedEngine] setEffectSendVolumeWithId:taskID volume:50];

// 调用 getEffectSendVolumeWithId 获取指定音效文件发送音量
uint32_t volume = 0;
[[NERtcEngine sharedEngine] getEffectSendVolumeWithId:taskID volume:&volume];

// 调用 setEffectPlaybackVolumeWithId 设置指定音效文件的播放音量
[[NERtcEngine sharedEngine] setEffectPlaybackVolumeWithId:taskID volume:50];

// 调用 getEffectPlaybackVolumeWithId 获取指定音效文件的播放音量
uint32_t volume = 0;
[[NERtcEngine sharedEngine] getEffectPlaybackVolumeWithId:taskID volume:&volume];

// 调用 setEffectPitchWithId 设置指定音效文件的音调
[[NERtcEngine sharedEngine] setEffectPitchWithId:taskID pitch:6];

// 调用 getEffectPitchWithId 获取指定音效文件的音调
int32_t pitch = 0;
[[NERtcEngine sharedEngine] getEffectPitchWithId:taskID pitch:&pitch];

// 调用 getEffectDurationWithId 获取指定音效文件时长
uint64_t duration = 0;
[[NERtcEngine sharedEngine] getEffectDurationWithId:taskID duration:&duration];

// 调用 getEffectCurrentPositionWithId 获取指定音效文件的播放进度
uint64_t position = 0;
[[NERtcEngine sharedEngine] getEffectCurrentPositionWithId:taskID position:&position];

// 调用 setEffectPositionWithId 设置指定音效文件的播放进度
[[NERtcEngine sharedEngine] setEffectPositionWithId:taskID position:0];

// 调用 stopAllEffects 结束播放所有音效
[[NERtcEngine sharedEngine] stopAllEffects];

API 参考

方法 功能描述
playEffectWitdId 播放指定音效文件
stopEffectWitdId 停止播放指定音效文件
pauseEffectWitdId 暂停播放指定音效文件
resumeEffectWitdId 恢复播放指定音效文件
pauseAllEffects 暂停播放所有音效文件
resumeAllEffects 恢复播放所有音效文件
setEffectSendVolumeWithId 设置音效文件发送音量
getEffectSendVolumeWithId 获取音效文件的发送音量
setEffectPlaybackVolumeWithId 设置音效文件的播放音量
getEffectPlaybackVolumeWithId 获取音效文件的播放音量
setEffectPitchWithId 设置音效文件的音调
getEffectPitchWithId 获取音效文件的音调
setEffectPositionWithId 设置音效文件的播放位置
getEffectDurationWithId 获取音效文件时长
getEffectCurrentPositionWithId 获取音效文件当前播放进度
stopAllEffects 暂停播放所有音效文件

配置伴音

配置步骤

  1. 初始化伴音配置类,通过 NERtcCreateAudioMixingOption 设置伴音任务相关参数,例如伴音文件路径、是否本地播放、是否通过辅流通道传输等等。

    若您选择通过辅流通道传输伴音音频流,请先调用 enableLocalSubStreamAudio 方法开启音频辅流。

  2. 调用 startAudioMixingWithOption 创建伴音任务。
  3. 伴音任务管理。开始伴音后,还可以通过其他方法实现伴音任务管理等更多功能,例如:
    • 进度管理: 通过 pauseAudioMixingresumeAudioMixing 暂停或恢复伴音、通过 setAudioMixingPosition 设置伴音文件的播放进度。
    • 音量管理:通过 setAudioMixingPlaybackVolumesetAudioMixingSendVolume 等方法设置伴音的播放音量、发送音量。
    • 音调管理:调用 setAudioMixingPitch 方法并通过 pitch 参数设置伴音文件的音调。
      • 仅开始伴音后可调用此方法;伴音结束后,音调将恢复为默认值。
      • 音调 pitch 参数的取值范围为 [-12,12],默认值为 0,每相邻两个值的音调高度相差半音;取值的绝对值越大,音调升高或降低得越多。
      • 若 SDK 返回 30003,表示参数设置错误;若 SDK 返回 30005,表示引擎尚未初始化或未找到当前伴音文件。
    • 获取伴音相关信息:例如通过 getAudioMixingCurrentPosition 等接口获取伴音文件的播放进度、调用 getAudioMixingPitch 方法获取伴音文件的音调等。
  4. 在离开房间前调用 stopAudioMixing 结束伴音。

示例代码

objcNSString *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;             //循环次数
option.startTimeStamp = 0;        //音乐文件开始播放的时间,UTC 时间戳
option.sendWithAudioType = NERtcAudioStreamType.kNERtcAudioStreamMain; //伴音跟随音频主流还是辅流,默认跟随主流
int ret = 
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];

// 获取和设置本地播放伴音的音调,范围为 -12 ~ 12
//int pitch;
[self.engine getAudioMixingPitch:&pitch];
[self.engine setAudioMixingPitch:pitch];

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

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

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

API 参考

方法 功能描述
startAudioMixingWithOption 开始伴音
enableLocalSubStreamAudio 开启音频辅流
stopAudioMixing 结束伴音
pauseAudioMixing 暂停伴音
resumeAudioMixing 恢复伴音
setAudioMixingPlaybackVolume 设置伴音文件的播放音量
setAudioMixingSendVolume 设置伴音文件的发送音量
setAudioMixingPitch 设置伴音文件的音调
getAudioMixingPlaybackVolume 获取伴音文件的播放音量
getAudioMixingSendVolume 获取伴音文件的发送音量
getAudioMixingPitch 获取伴音文件的音调
getAudioMixingDuration 获取伴音文件的总长度
setAudioMixingPosition 设置伴音文件的播放进度
getAudioMixingCurrentPosition 获取伴音文件的当前播放进度

事件 事件描述
onAudioMixingStateChanged 本地用户的伴音文件播放状态改变回调
onAudioMixingTimestampUpdate 伴音文件播放进度回调

常见问题

此文档是否对你有帮助?
有帮助
去反馈
  • 功能概述
  • 注意事项
  • 示例项目源码
  • 配置音效
  • 配置步骤
  • 示例代码
  • API 参考
  • 配置伴音
  • 配置步骤
  • 示例代码
  • API 参考
  • 常见问题