播放音乐和音效

功能描述

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

播放音乐文件

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

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

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

播放音效文件

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

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

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

接口描述

@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];

上次更新：2022-05-06