# 音效文件播放管理
如不集成hwffmpeg.framework，接口则只有startAudioFile/stopAudioFile/pauseAudioFile/resumeAudioFile生效，回调则只有onStartAudioFile/onStopAudioFile/onPauseAudioFile/onResumeAudioFile生效，且startAudioFile播放格式只支持mp3。
 #### startAudioFile
```
- (int)startAudioFile:(HWRtcStartAudioFileParam * _Nonnull)startAudioFileParam;
- (int)startAudioFile:(NSString *)filePath publish:(int)publish cycle:(int)cycle replace:(int)replace;
- (int)startAudioFile:(NSString *)filePath  publish:(int)publish cycle:(int)cycle replace:(int)replace startPos:(unsigned int)startPos;
```
【**功能说明**】
接口一：设置播放的音频文件，需要入会调用才生效。
接口二：启动音频混音。
接口三：开始播放音频文件。当前只支持本地播放。若角色为"publisher"，不支持调用。
【**请求参数**】
- startAudioFileParam ：音频文件参数，具体请参见[HWRtcStartAudioFileParam](https://support.huaweicloud.com/csdk-rtc/rtc_05_0082.html#rtc_05_0082__section1569320211217)。
- filePath：音频文件路径。
- publish：是否将音频发送到远端 ，1表示音频发送到远端，0表示音频仅本地播放。
- cycle：音频播放次数，0表示无限循环。
- replace：是否用音频文件替换麦克风采集的声音，1表示只使用音频文件发送到远端，0表示将本地麦克风采集和音频文件混音后发送到远端。
- startPos：音频文件开始播放位置，单位ms。
【**返回参数** 】
- 0：方法调用成功。
- \> 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
- 需要加入房间后再调用此接口。
- 将会触发[onAudioMixStateChangedNotify](https://support.huaweicloud.com/csdk-rtc/rtc_05_0065.html#rtc_05_0065__section42915377368)回调。
 
 #### stopAudioFile
```
- (int)stopAudioFile;
```
【**功能说明**】
停止播放音频文件。房间内调用。
【**请求参数**】
无
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
- 需要加入房间后再调用此接口。
- 将会触发[onAudioMixStateChangedNotify](https://support.huaweicloud.com/csdk-rtc/rtc_05_0065.html#rtc_05_0065__section42915377368)回调。
 
 #### pauseAudioFile
```
- (int)pauseAudioFile;
```
【**功能说明**】
暂停播放音频文件。房间内调用。
【**请求参数**】
无
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
- 需要加入房间后再调用此接口。
- 将会触发[onAudioMixStateChangedNotify](https://support.huaweicloud.com/csdk-rtc/rtc_05_0065.html#rtc_05_0065__section42915377368)回调。
 
 #### resumeAudioFile
```
- (int)resumeAudioFile;
```
【**功能说明**】
恢复播放音频文件。房间内调用。
【**请求参数**】
无
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
- 需要加入房间后再调用此接口。
- 将会触发[onAudioMixStateChangedNotify](https://support.huaweicloud.com/csdk-rtc/rtc_05_0065.html#rtc_05_0065__section42915377368)回调。
 
 #### adjustAudioFileVolume
```
- (int)adjustAudioFileVolume:(unsigned int)volume;
```
【**功能说明**】
调整本地和远端音频播放的音量。
【**请求参数**】
volume：音量大小，默认音量为100，范围为0-100。
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
 #### adjustAudioFilePlayoutVolume
```
- (int)adjustAudioFilePlayoutVolume:(unsigned int)volume;
```
【**功能说明**】
调整本地音频播放的音量。
【**请求参数**】
volume：音量大小，默认音量为100，范围为0-100。
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
 #### getAudioFileVolume
```
- (int)getAudioFileVolume;
```
【**功能说明**】
获取音频播放的音量。
【**请求参数**】
无
【**返回参数** 】
- \>=0：音量大小。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
 #### getAudioFilePlayoutVolume
```
- (int)getAudioFilePlayoutVolume;
```
【**功能说明**】
获取本地播放音频音量。
【**请求参数**】
无
【**返回参数**】
音频音量。
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### getAudioFileDuration
```
- (int)getAudioFileDuration;
```
【**功能说明**】
获取音频文件的时长。
【**请求参数**】
无
【**返回参数** 】
- \>0：音频时长，单位ms。
- \<= 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### getAudioFileCurrentPosition
```
- (int)getAudioFileCurrentPosition;
```
【**功能说明**】
获取音频文件当前播放位置。
【**请求参数**】
无
【**返回参数** 】
- \>=0：播放位置，单位ms。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### setAudioFilePosition
```
- (int)setAudioFilePosition:(unsigned long long)position;
```
【**功能说明**】
设置音频播放位置。
【**请求参数**】
position：播放位置，单位ms。
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### getAudioClipsVolume
```
- (int)getAudioClipsVolume;
```
【**功能说明**】
获取音效总音量。
【**请求参数**】
无
【**返回参数** 】
- \>=0：音量。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### getVolumeOfAudioClip
```
- (int)getVolumeOfAudioClip:(int)soundId;
```
【**功能说明**】
获取指定音效音量。
【**请求参数**】
soundId：音效ID。
【**返回参数** 】
- \>=0：音量。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### setAudioClipsVolume
```
- (int)setAudioClipsVolume:(double)volume;
```
【**功能说明**】
设置音效总音量。
【**请求参数**】
volume：音量，默认音量为100，范围为0-100。
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### setVolumeOfAudioClip
```
- (int)setVolumeOfAudioClip:(int)soundId volume:(double)volume;
```
【**功能说明**】
设置指定音效音量。
【**请求参数**】
- soundId：音效ID。
- volume：音量，默认音量为100，范围为0-100。
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### playAudioClip
```
- (int)playAudioClip:(int)soundId 
                    filePath:(NSString *)filePath
                    loop:(int)loop 
                    pitch:(double)pitch 
                    pan:(double)pan
                    gain:(double)gain
                    publish:(int)publish
                    startPos:(int)startPos;
```
【**功能说明**】
播放音效文件并启动混音，需要在有joiner加入房间后调用。
【**请求参数**】
- soundId：音效ID，取值\>= 0。
- filePath：音效文件路径，支持本地文件和网络文件。
- loop：音效文件播放次数，0为循环播放。
- pitch：音调大小，（**当前不支持** ）**。**
- pan：空间位置，（**当前不支持** ）**。**
- gain：音量大小，取值范围0-100。
- publish：1表示将音效文件混音后发送到远端，0表示本地播放，不发送到远端。
- startPos：起始播放位置，单位ms。
【**返回参数**】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
soundId需要开发者自己生成并维护，保证不同的soundId对应不同的音效播放实例。同时音效播放完毕或者停止播放后，soundId需主动回收，待下一次播放音效时，建议复用被回收的soundId。
 #### stopAudioClip
```
-  (int)stopAudioClip:(int)soundId;
```
【**功能说明**】
停止播放指定音效。
【**请求参数**】
soundId：音效ID。
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### stopAllAudioClips
```
-  (int)stopAllAudioClips;
```
【**功能说明**】
停止播放所有音效。
【**请求参数**】
无
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### pauseAudioClip
```
-  (int)pauseAudioClip:(int)soundId;
```
【**功能说明**】
暂停播放指定音效。
【**请求参数**】
soundId 音效ID
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### pauseAllAudioClips
```
- (int)pauseAllAudioClips;
```
【**功能说明**】
暂停播放所有音效。
【**请求参数**】
无
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### resumeAudioClip
```
-  (int)resumeAudioClip:(int)soundId;
```
【**功能说明**】
恢复播放指定音效。
【**请求参数**】
soundId 音效ID
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### resumeAllAudioClips
```
-  (int)resumeAllAudioClips;
```
【**功能说明**】
恢复播放所有音效。
【**请求参数**】
无
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### getAudioClipCurrentPosition
```
-  (int)getAudioClipCurrentPosition:(int)soundId;
```
【**功能说明**】
获取指定音效当前播放位置。
【**请求参数**】
soundId：音效ID。
【**返回参数** 】
- \>=0：方法调用成功，返回位置，单位为ms。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### setAudioClipPosition
```
- (int)setAudioClipPosition:(int)soundId pos:(int)pos;
```
【**功能说明**】
设置指定音效播放位置。
【**请求参数**】
- soundId：音效ID。
- pos：位置，单位为ms。
【**返回参数** 】
- 0：方法调用成功。
- \< 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。
 #### getAudioClipDuration
```
- (int)getAudioClipDuration:(NSString *)filePath;
```
【**功能说明**】
获取音效文件时长。
【**请求参数**】
filePath：音效文件路径。
【**返回参数** 】
- \>0：方法调用成功，单位为ms。
- \<= 0：方法调用失败。具体请参见[HWRtcErrorCode](https://support.huaweicloud.com/csdk-rtc/rtc_05_0080.html)。
 
![](https://support.huaweicloud.com/csdk-rtc/public_sys-resources/caution_3.0-zh-cn.png)
需要加入房间后再调用此接口。