播放音乐音效

功能描述

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

播放音乐文件

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

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

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

播放音效文件

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

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

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

接口描述

public class ChannelEngine {
    /*
     * 开始播放音乐文件。
     * 成功调用该方法后，后续的播放状态变化通过onSoundStateChanged回调获取。
     * @param filePath 指定需要播放的声音文件的绝对路径。
     * @param cycle 循环播放次数。正整数表示具体的循环播放的次数，-1表示无限循环播放。
     * @param publish 
      - true: 本地用户和远端用户都能听到播放的声音
      - false: 只有本地用户可以听到播放的声音
      * @return
         - 0 : 成功.
         - < 0: 失败.
     */
    public int startSoundMixing(String filePath, int cycle, boolean publish);
    /*
     * 停止播放音乐文件。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int stopSoundMixing();
    /*
     * 暂停播放音乐文件。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int pauseSoundMixing();
    /*
     * 恢复播放音乐文件。
     * @return
         - 0 : 成功.
        - < 0: 失败.
     */
    public int resumeSoundMixing();
    /*
     * 设置音乐文件的播放位置。
     * @param pos 音乐文件的播放位置，单位为毫秒。
     * @return
        - >= 0 : 音乐进度.
         - < 0: 失败.
    */
    public int setSoundMixingPosition();
    /*
     * 获取音乐文件的播放进度，单位为毫秒。
     * @return
         - 0 : 成功.
        - < 0: 失败.
     */
    public int getSoundMixingCurrentPosition();
    /*
     * 获取音乐文件总时长，单位为毫秒。
     * @return
        - >= 0: 声音文件时长。
        - < 0: 失败.
     */
    public int getSoundMixingDuration();
    /*
     * 调整播放的音乐文件的音调。
     * @param pitch 按半音音阶调整本地播放的音乐文件的音调，默认值为0，即不调整音调，取值范围为 [-12,12]。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int setSoundMixingPitch(int pitch);
    /*
     * 调节音乐文件播放音量。
     * @param vol 音乐文件音量范围为 0~100。100（默认值）为原始文件音量。
     * @return
        - 0 : 成功.
         - < 0: 失败.
     */
    public int adjustSoundMixingVolume(int vol);
    /*
     * 调节音乐文件本地播放音量。
     * @param vol 音乐文件音量范围为 0~100。100（默认值）为原始文件音量。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int adjustSoundMixingPlayoutVolume(int vol);
    /*
     * 调节音乐文件远端播放音量。
     * @param vol 音乐文件音量范围为 0~100。100（默认值）为原始文件音量。
     * @return
        - 0 : 成功.
        - < 0: 失败.
    */
    public int adjustSoundMixingPublishVolume(int vol);
    /*
     * 获取音乐文件的本地播放音量。
     * @return
        - >= 0: 音乐文件的本地播放音量，范围为 [0, 100]。
        - < 0: 失败.
     */
    public int getSoundMixingPlayoutVolume();
    /*
     * 获取音乐文件的远端播放音量。
     * @return
        - >= 0: 音乐文件的远端播放音量，范围为 [0, 100]。
        - < 0: 失败.
     */
    public int getSoundMixingPublishVolume();
    /*
     * 开始播放音效文件。
     * 可以多次调用该方法，同时播放多个音效文件，实现音效叠加。
     * 播放音效结束后，会触发onEffectFinished回调。
     * @param effectId 音效文件ID。
     * @param filePath 指定需要播放的音效文件的绝对路径。
     * @param cycle 循环播放次数。正整数表示具体的循环播放的次数，-1表示无限循环播放。
     * @param publish
        - true: 本地用户和远端用户都能听到播放的声音
        - false: 只有本地用户可以听到播放的声音
     * @return
        - 0  成功.
        - < 0: 失败.
    */ 
    public int playEffect(int effectId, String filePath, int cycle, boolean publish);
    /*
     * 停止播放音效文件。
     * @param effectId 音效文件ID。
     * @return
        - 0 : 成功.
        - < 0: 失败.
    */
    public int stopEffect(int effectId);
    /*
     * 停止播放所有音效文件。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int stopAllEffects();
    /*
     * 暂停播放音效文件。
     * @param effectId 音效文件ID。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int pauseEffect(int effectId);
    /*
     * 暂停播放所有音效文件。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int pauseAllEffects();
    /*
     * 恢复播放音效文件。
     * @param effectId 音效文件ID。
     * @return
        - 0 : 成功.
        - < 0: 失败.
    */
    public int resumeEffect(int effectId);
    /*
     * 恢复播放所有音效文件。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int resumeAllEffects();
    /*
     * 获取播放音效文件音量。
     * @return
        - >= 0: 音效文件的播放音量，范围为 [0, 100]
        - < 0: 失败.
     */
    public int getEffectsVolume();
    /*
     * 设置音效文件的播放音量。
     * @param vol 音效文件音量范围为 0~100。100（默认值）为原始文件音量。
     * @return
        - 0 : 成功.
        - < 0: 失败.
     */
    public int setEffectsVolume(int volume);
    /*
     * 设置指定音效文件的音量。
     * @param effectId 音效文件ID。
     * @param vol 音效文件音量范围为 0~100。100（默认值）为原始文件音量。
     * @return
        - 0 : 成功.
        - < 0: 失败.
    */
    public int setVolumeOfEffect(int effectId, int vol);
}

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

示例代码

//播放本地tonight1.mp3音乐, 循环混音播放1次，本地和远端用户都可以听到
engine.startSoundMixing("/assets/tonight1.mp3", 1, true);

//播放本地clap.mp3音效, 循环播放2次，只有本地用户都可以听到
engine.playEffect(111, "/assets/clap.mp3", 2, false);

上次更新：2021-09-17