播放音频文件

功能描述

在通话或直播过程中，有时候需要播放自定义的音频文件并让频道内的其他人也听到，比如需要给游戏增加音效，或者播放背景音乐等。

在使用音效管理器前，请确保已在项目中实现基本的实时音视频功能。

支持格式

支持 mp3，aac，m4a，3gp，wav 格式

播放音效文件

音效通常指持续很短的音频。播放音效文件方法主要用来播放短小的氛围音，比如鼓掌、游戏子弹撞击声音等，可以多个音效叠加播放。

音效由音频文件路径指定，但在 SDK 内部使用 sound id 来识别和处理音效。SDK 并不强制如何定义 sound id，保证每个音效有唯一的识别即可。一般的做法有自增 id，使用音效文件名的 hashCode 等。

使用步骤

在加入频道前调用 preloadEffect 方法预加载音效文件，可以多次调用该方法加载多个音效文件。
加入频道后调用 playEffect 方法播放音效文件，可以多次调用该方法同时播放多个音效。我们建议最多同时播放三个音效文件。

示例代码

// 预加载音效（推荐），需注意音效文件的大小，并在加入频道前完成加载
#ifdef UNICODE
  CHAR wdFilePath[MAX_PATH];
  ::WideCharToMultiByte(CP_UTF8, 0, filePath, -1, wdFilePath, MAX_PATH, NULL, NULL);
  int nRet = rtcEngine.preloadEffect(nSoundID, wdFilePath);
#else
  int nRet = rtcEngine.preloadEffect(nSoundID, filePath);
#endif

// 开始播放音效文件，如果设置了预加载，需要指定 nSoundID 
#ifdef UNICODE
  CHAR wdFilePath[MAX_PATH];
  ::WideCharToMultiByte(CP_UTF8, 0, filePath, -1, wdFilePath, MAX_PATH, NULL, NULL);
  int nRet = rtcEngine.playEffect(nSoundID, // 音效唯一标识
  wdFilePath, // 文件路径
  nLoopCount, // 重复播放次数
  dPitch, // 音效的音调
  dPan, // 音效的空间位置，0 表示正前方
  nGain, // 音效音量，取值 0 - 100， 100 代表原始音量
  TRUE // 是否令远端也能听到音效的声音
#else
  int nRet = rtcEngine.playEffect(nSoundID, filePath, nLoopCount, dPitch, dPan, nGain, TRUE);
#endif

// 暂停指定的音效播放
int nRet = rtcEngine.pauseEffect(nSoundID);

// 暂停所有音效播放
int nRet = rtcEngine.pauseAllEffects();

// 继续指定的已经暂停的音效播放
int nRet = rtcEngine.resumeEffect(nSoundID);

// 继续所有已经暂停的音效播放
int nRet = rtcEngine.resumeAllEffects();

// 停止指定的音效播放
int nRet = rtcEngine.stopEffect(nSoundID);

// 停止所有音效播放
int nRet = rtcEngine.stopAllEffects();

// 释放预加载的音效
int nRet = rtcEngine.unloadEffect(nSoundID);

API 参考

开发注意事项

预加载不是一个必须的步骤，一般来说为了提高性能或者需要反复播放某个特定的音效的时候，我们建议使用预加载。
如果音效文件比较大，不建议预加载。
以上方法都有返回值，返回值小于 0 表示方法调用失败。

音乐混音

混音是指播放本地或者在线音乐文件，同时让频道内的其他人听到此音乐。
混音方法主要用来播放比较长的背景音，比如直播的时候播放的音乐，同时只可以有一个文件播放。如果在混音播放第一个文件的过程中播放第二个文件，会自动停止第一个文件的播放。

混音功能支持如下设置：

混音或替换：混音指的是音乐文件的音频流跟麦克风采集的音频流进行混音（叠加）并编码发送给对方；替换指的是麦克风采集的音频被音乐文件的音频流替换掉，对方只能听见音乐播放。
循环：可以设置是否循环播放混音文件，以及循环次数。
调节音量：可以同时或分别调节音乐文件在本地和远端的播放音量。
调节音调：可以分别调节本地人声的音调和音乐文件的音调。

实现方法

LPCTSTR filePath = "http://www.hochmuth.com/mp3/Haydn_Cello_Concerto_D-1.mp3";
// 开始播放混音
#ifdef UNICODE
 CHAR wdFilePath[MAX_PATH];
 ::WideCharToMultiByte(CP_UTF8, 0, filePath, -1, wdFilePath, MAX_PATH, NULL, NULL);
int nRet = rtcEngine.startAudioMixing(wdFilePath, // 混音文件路径，支持网络文件，比如 http 协议的
 FALSE, // 只在本端播放
  TRUE, // 混音文件内容替换麦克风采集的声音
  1 // 混音文件重复播放次数
  );
#else
int nRet = rtcEngine.startAudioMixing(filePath, FALSE, TRUE, 1);
#endif

// 结束播放混音
int nRet = rtcEngine.stopAudioMixing();

API 参考

开发注意事项

在频道内调用混音方法，否则会有潜在问题。
以上方法都有返回值，返回值小于 0 表示方法调用失败。