音效文件播放

getEffectCurrentPosition

获取指定音效文件的播放进度。

C++

virtual int getEffectCurrentPosition(int soundId) = 0;

注意： 该方法需要在 playEffect 后调用。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。

返回值

• 方法调用成功，返回指定音效文件的播放进度（毫秒）。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

getEffectDuration

获取指定音效文件总时长。

C++

virtual int getEffectDuration(const char* filePath) = 0;

注意： 该方法需要在加入频道后调用。

参数

参数名	描述
filePath	文件路径： Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，建议使用 URI 地址访问本地文件。例如 content://com.android.providers.media.documents/document/audio%3A14441。 Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 C:\music\audio.mp4。

返回值

• 方法调用成功，返回指定音效文件时长（毫秒）。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

getEffectsVolume

获取音效文件的播放音量。

C++

virtual int getEffectsVolume() = 0;

音量范围为 0~100。100 （默认值）为原始文件音量。

注意： 该方法需要在 playEffect 后调用。

返回值

• 音效文件的音量。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

getVolumeOfEffect

获取指定音效文件的播放音量。

C++

virtual int getVolumeOfEffect(int soundId) = 0;

参数

参数名	描述
soundId	音效文件的 ID。

返回值

• ≥ 0: 方法调用成功，返回播放音量。音量范围为 [0,100]。100 为原始音量。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

pauseAllEffects

暂停所有音效文件播放。

C++

virtual int pauseAllEffects() = 0;

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

pauseEffect

暂停音效文件播放。

C++

virtual int pauseEffect(int soundId) = 0;

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

playAllEffects

播放所有音效文件。

C++

virtual int playAllEffects(int loopCount, double pitch, double pan, int gain, bool publish = false) = 0;

多次调用 preloadEffect 预加载多个音效文件后，你可以调用本方法播放所有预加载的音效文件。

参数

参数名	描述
loopCount	音效文件循环播放的次数： -1: 无限循环播放音效文件，直至调用 stopEffect 或 stopAllEffects 后停止。 0: 播放音效文件一次。 1: 播放音效文件两次。
pitch	音效的音调。取值范围为 [0.5,2.0]。默认值为 1.0，代表原始音调。取值越小，则音调越低。
pan	音效的空间位置。取值范围为 [-1.0,1.0]: -1.0: 音效出现在左边。 0: 音效出现在正前边。 1.0: 音效出现在右边。
gain	音效的音量。取值范围为 [0,100]。100 为默认值，代表原始音量。取值越小，则音量越低。
publish	是否将音效发布到远端： true: 将音效发布到远端。本地和远端用户都能听到该音效。 false: （默认）不将音效发布到远端。只能本地用户能听到该音效。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

playEffect

播放指定的本地或在线音效文件。

C++

virtual int playEffect(int soundId,
    const char* filePath,
    int loopCount,
    double pitch,
    double pan,
    int gain,
    bool publish,
    int startPos) = 0;

注意： 如果你需要通过该方法来播放在线音效文件，建议你先将在线音效文件缓存到本地设备，调用 preloadEffect 将缓存的音效文件预加载到内存中，然后再调用此方法播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。 你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。音效文件播放结束后，SDK 会触发 onAudioEffectFinished 回调。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。 注意： 如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 soundId 相同。
filePath	播放文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 C:\music\audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。 注意： 如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 filePath 相同。
loopCount	音效循环播放的次数。 ≥ 0: 循环播放次数。例如，1 表示循环播放 1 次，即总计播放 2 次。 -1: 无限循环播放。
pitch	音效的音调，取值范围为 [0.5,2.0]。默认值为 1.0，表示原始音调。取值越小，则音调越低。
pan	音效的空间位置。取值范围为 [-1.0,1.0]，例如： -1.0：音效出现在左边 0.0：音效出现在正前方 1.0：音效出现在右边
gain	音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0，表示原始音量。取值越小，则音量越低。
publish	是否将音效发布至远端： true: 将音效发布至远端。本地用户和远端用户都能听到音效。 false: 不将音效发布至远端。只有本地用户能听到音效。
startPos	音效文件的播放位置，单位为毫秒。

返回值

• 0：方法调用成功。

• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

preloadEffect

将音效文件加载至内存。

C++

virtual int preloadEffect(int soundId, const char* filePath) = 0;

为保证通信畅通，请注意控制预加载音效文件的大小，并在 joinChannel [2/2] 前就使用该方法完成音效预加载。

注意：

• 该方法不支持在线音频文件。

• 该方法支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。
filePath	文件路径： Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，建议使用 URI 地址访问本地文件。例如 content://com.android.providers.media.documents/document/audio%3A14441。 Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 C:\music\audio.mp4。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

resumeAllEffects

恢复播放所有音效文件。

C++

virtual int resumeAllEffects() = 0;

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

resumeEffect

恢复播放指定音效文件。

C++

virtual int resumeEffect(int soundId) = 0;

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

setEffectPosition

设置指定音效文件的播放位置。

C++

virtual int setEffectPosition(int soundId, int pos) = 0;

成功设置后，本地音效文件会在指定位置开始播放。

注意： 该方法需要在 playEffect 后调用。

参数

参数名	描述
soundId	音效的 ID。每个音效的 ID 具有唯一性。
pos	音效文件的播放位置，单位为毫秒。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

setEffectsVolume

设置音效文件的播放音量。

C++

virtual int setEffectsVolume(int volume) = 0;

注意： 该方法需要在 playEffect 后调用。

参数

参数名	描述
volume	播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

setVolumeOfEffect

实时调整音效文件的播放音量。

C++

virtual int setVolumeOfEffect(int soundId, int volume) = 0;

参数

参数名	描述
soundId	指定音效的 ID。每个音效均有唯一的 ID。
volume	播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

stopAllEffects

停止播放所有音效文件。

C++

virtual int stopAllEffects() = 0;

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

stopEffect

停止播放指定音效文件。

C++

virtual int stopEffect(int soundId) = 0;

参数

参数名	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

unloadAllEffects

从内存释放所有预加载音效文件。

C++

virtual int unloadAllEffects() = 0;

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

unloadEffect

从内存释放某个预加载的音效文件。

C++

virtual int unloadEffect(int soundId) = 0;

参数

参数名	描述
soundId	指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

onAudioEffectFinished

本地音效文件播放已结束回调。

C++

virtual void onAudioEffectFinished(int soundId) {
    }

当播放音效结束后，会触发该回调。

参数

参数名	描述
soundId	指定音效的 ID。每个音效均有唯一的 ID。

所属接口类

• IRtcEngineEventHandler