播放音乐和音效 编辑文档

功能描述

在通话过程中,除了用户自己说话的声音,有时候希望让远端用户听到特殊的音频文件,比如需要添加音效,或者需要播放背景音乐等,QttAudio对播放音效和音乐文件的需求提供了支持。

播放音乐文件

QttAudio支持播放本地音乐文件,同时让频道内的其他人听到此音乐。比如通话的时候播放背景音乐,同时只可以有一个文件播放。

QttAudio播放音乐功能支持如下设置:

  1. 本地或者混音播放:本地播放指音乐只有本地用户可以听到,混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音(叠加)并编码发送给对方,本地和远端用户都可以听到音乐;
  2. 循环播放:可以设置是否循环播放音乐文件,以及循环次数;
  3. 指定位置播放:可以设置从音乐文件的指定位置开始播放;
  4. 调节音量:可以同时或分别调节音乐文件在本地和远端的播放音量;

播放音效文件

音效通常指持续很短的音频。播放音效文件方法主要用来播放短小的氛围音,比如鼓掌、喝彩等氛围音效,支持多个音效叠加播放。

QttAudio播放音效功能支持如下设置:

  1. 本地或者混音播放:本地播放指音效只有本地用户可以听到,混音指的是音效文件的音频流跟麦克风采集的音频流进行混音(叠加)并编码发送给对方,本地和远端用户都可以听到音效;
  2. 循环播放:可以设置是否循环播放音效文件,以及循环次数;
  3. 调节音量:可以同时或分别调节音效文件在本地和远端的播放音量;

接口描述

@interface QttChannelEngine : NSObject
/*
* 开始播放声音文件。
* 成功调用该方法后,后续的播放状态变化通过onSoundStateChanged获取。
* @param filePath 指定需要播放的声音文件的绝对路径。
* @param cycle 循环播放次数。正整数表示具体的循环播放的次数,-1表示无限循环播放。
* @param publish
- true: 本地用户和远端用户都能听到播放的声音
- false: 只有本地用户可以听到播放的声音
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)startSoundMixing:(NSString*)filePath cycle:(int)cycle publish:(bool)publish;

/*
* 停止播放声音文件。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)stopSoundMixing;

/*
* 暂停播放声音文件。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)pauseSoundMixing;

/*
* 恢复播放声音文件。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)resumeSoundMixing;

/*
* 设置声音文件的播放位置。
* @param pos 声音文件的播放位置,单位为毫秒。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)setSoundMixingPosition:(int)pos;

/*
* 获取声音文件的播放进度,单位为毫秒。
* @return
- >= 0: 音乐文件当前播放进度
- < 0: 失败.
*/
- (int)getSoundMixingCurrentPosition;

/*
* 获取声音文件总时长,单位为毫秒。
* @return
- >= 0: 声音文件时长。
- < 0: 失败.
*/
- (int)getSoundMixingDuration;

/*
* 调整播放的声音文件的音调。
* @param pitch 按半音音阶调整本地播放的音乐文件的音调,默认值为0,即不调整音调,取值范围为 [-12,12]。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)setSoundMixingPitch:(int)pitch;

/*
* 调节声音文件播放音量。
* @param vol 声音文件音量范围为 0~100。100(默认值)为原始文件音量。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)adjustSoundMixingVolume:(int)vol;

/*
* 调节声音文件本地播放音量。
* @param vol 声音文件音量范围为 0~100。100(默认值)为原始文件音量。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)adjustSoundMixingPlayoutVolume:(int)vol;

/*
* 调节声音文件远端播放音量。
* @param vol 声音文件音量范围为 0~100。100(默认值)为原始文件音量。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)adjustSoundMixingPublishVolume:(int)vol;

/*
* 获取声音文件的本地播放音量。
* @return
- >= 0: 声音文件的本地播放音量,范围为 [0, 100]。
- < 0: 失败.
*/
- (int)getSoundMixingPlayoutVolume;

/*
* 获取声音文件的远端播放音量。
* @return
- >= 0: 声音文件的远端播放音量,范围为 [0, 100]。
- < 0: 失败.
*/
- (int)getSoundMixingPublishVolume;

/*
* 开始播放音效文件。
* 可以多次调用该方法,同时播放多个音效文件,实现音效叠加。
* 播放音效结束后,会触发onEffectFinished。
* @param effectId 音效文件ID。
* @param filePath 指定需要播放的音效文件的绝对路径。
* @param cycle 循环播放次数。正整数表示具体的循环播放的次数,-1表示无限循环播放。
* @param publish
- true: 本地用户和远端用户都能听到播放的声音
- false: 只有本地用户可以听到播放的声音
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)playEffect:(int)effectId filePath:(NSString*)filePath cycle:(int)cycle publish:(bool)publish;

/*
* 停止播放音效文件。
* @param effectId 音效文件ID。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)stopEffect:(int)effectId;

/*
* 停止播放所有音效文件。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)stopAllEffects;
/*
* 暂停播放音效文件。
* @param effectId 音效文件ID。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)pauseEffect:(int)effectId;

/*
* 暂停播放所有音效文件。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)pauseAllEffects;

/*
* 恢复播放音效文件。
* @param effectId 音效文件ID。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)resumeEffect:(int)effectId;

/*
* 恢复播放所有音效文件。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)resumeAllEffects;

/*
* 获取播放音效文件音量。
* @return
- >= 0: 音效文件的播放音量,范围为 [0, 100]。
- < 0: 失败.
*/
- (int)getEffectsVolume;

/*
* 设置音效文件的播放音量。
* @param vol 音效文件音量范围为 0~100。100(默认值)为原始文件音量。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)setEffectsVolume:(int)volume;

/*
* 设置指定音效文件的音量。
* @param effectId 音效文件ID。
* @param vol 音效文件音量范围为 0~100。100(默认值)为原始文件音量。
* @return
- 0(ERR_SUCCESS): 成功.
- < 0: 失败.
*/
- (int)setVolumeOfEffect:(int)effectId vol:(int)vol;
@end

音乐播放过程的状态变化会触发onSoundStateChanged回调,音效播放完成后会触发onEffectFinished回调。

示例代码

//播放music.mp3音乐, 循环混音播放1次,本地和远端用户都可以听到
NSString *path = [[NSBundle mainBundle] pathForResource:@"music" ofType:@"mp3"];
[engine startSoundMixing:path cycle:1 publish:true];
//播放effect.mp3音效, 循环播放2次,只有本地用户都可以听到
NSString *path = [[NSBundle mainBundle] pathForResource:@"effect" ofType:@"mp3"];
[engine playEffect:path cycle:2 publish:false];
野狗新手?
立即注册,为你提供安全可靠的实时通信云服务。
没找到需要的文档?
你可以提交工单反馈 或 阅读常见问题