音效文件播放

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 地址、绝对路径，或以 /assets/ 开头的文件路径。使用绝对路径访问本地文件可能会遇到权限问题，建议使用 URI 地址。例如：content://com.android.providers.media.documents/document/audio%3A14441。
• Windows：音效文件的绝对路径或 URL 地址（包括文件名后缀）。例如：C:\music\audio.mp4。
• iOS 或 macOS：音效文件的绝对路径或 URL 地址（包括文件名后缀）。例如：/var/mobile/Containers/Data/audio.mp4。

返回值

• 方法调用成功，返回指定音效文件的总时长（毫秒）。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

getEffectsVolume

获取当前音效的音量。

C++

virtual int getEffectsVolume() = 0;

音量为 0 到 100 之间的整数，默认值为 100，表示原始音量。

信息

请在调用 playEffect 后调用此方法。

返回值

• 0：方法调用成功，返回音效的音量。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

getVolumeOfEffect

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

C++

virtual int getVolumeOfEffect(int soundId) = 0;

参数

soundId

音效文件的 ID。

返回值

• 方法调用成功，返回指定音效的音量，取值范围为 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 = false, int startPos = 0) = 0;

要同时播放多个音效文件，请使用不同的 soundId 和 filePath 多次调用该方法。为获得最佳用户体验，声网建议不要同时播放超过三个音效文件。

信息

如果需要播放在线音效文件，声网建议先将其缓存到本地设备，调用 preloadEffect 将其预加载到内存中，再调用该方法播放音效。否则，可能因加载超时或失败导致播放失败或无声。 如果在调用 playEffect 前调用了 preloadEffect，则在 playEffect 执行后文件资源不会被关闭。下次调用 playEffect 时将直接从头开始播放。 如果在调用 playEffect 前未调用 preloadEffect，则在 playEffect 执行后资源将被销毁。下次调用 playEffect 时将尝试重新打开文件并从头播放。

调用时机

你可以在加入频道前或后调用该方法。

相关回调

成功调用该方法后，SDK 会触发 onAudioEffectFinished 回调报告音效播放完成。

参数

soundId

音效 ID。每个音效文件的 ID 是唯一的。如果已调用 preloadEffect 将音效预加载到内存中，请确保该参数的值与 preloadEffect 中的 soundId 相同。

filePath

文件路径。支持 URL 和本地文件的绝对路径，路径需精确到文件名及扩展名。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。详见声网 RTC SDK 支持哪些音频文件格式。如果已调用 preloadEffect 将音效预加载到内存中，请确保该参数的值与 preloadEffect 中的 filePath 相同。

loopCount

音效的循环播放次数：

• ≥ 0：播放的次数。例如，1 表示循环播放一次，即总共播放两次。
• -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

playEffectEx

在频道中播放指定音效。

C++

virtual int playEffectEx(const RtcConnection& connection, int soundId, const char* filePath, int loopCount, double pitch, double pan, int gain, bool publish = false, int startPos = 0) = 0;

自从

自 v4.6.0 版本新增。

你可以调用该方法在频道内向所有用户播放指定音效。每次调用该方法只能播放一个音效。若需同时播放多个音效，请使用不同的 soundId 和 filePath 多次调用该方法。你还可以设置是否在频道中发布该音效。

信息

• 声网建议不要同时播放超过三个音效。
• 该方法中的音效 ID 和文件路径必须与 preloadEffect 方法中的保持一致。

适用场景

该方法适用于多频道场景。

参数

connection

RtcConnection 对象，详见 RtcConnection。

soundId

音效 ID。

filePath

本地文件的绝对路径或在线文件的 URL。支持的音频格式包括 mp3、mp4、m4a、aac、3gp、mkv 和 wav。

loopCount

音效的循环播放次数：

• -1：无限循环，直到调用 stopEffect 或 stopAllEffects。
• 0：播放一次。
• 1：播放两次。

pitch

音效的音调。取值范围为 0.5 到 2.0，默认值为 1.0（原始音调）。数值越小，音调越低。

pan

音效的空间位置。取值范围为 -1.0 到 1.0：

• -1.0：音效从用户左侧传来。
• 0.0：音效从用户正前方传来。
• 1.0：音效从用户右侧传来。

gain

音效的音量。取值范围为 0 到 100，默认值为 100（原始音量）。数值越小，音量越低。

publish

是否在频道中发布该音效：

• true：在频道中发布该音效。
• false：（默认）不在频道中发布该音效。

startPos

音效文件的播放起始位置，单位为毫秒。

返回值

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

所属接口类

• IRtcEngineEx

preloadEffect

将指定的音效文件预加载到内存中。

C++

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

确保所有预加载文件的总大小不超过限制。

信息

• 如果在调用 playEffect 之前调用 preloadEffect，playEffect 执行后不会关闭文件资源。下次调用 playEffect 时会直接从头开始播放。
• 如果在调用 playEffect 之前未调用 preloadEffect，playEffect 执行后会销毁资源。下次调用 playEffect 时会尝试重新打开文件并从头开始播放。

调用时机

建议在加入频道前调用该方法。

参数

soundId

音效 ID。每个音效文件的 ID 必须唯一。

filePath

文件路径：

• Android：文件路径需精确到文件名和后缀名。支持 URL 地址、绝对路径或以 /assets/ 开头的路径。使用绝对路径访问本地文件可能会遇到权限问题，建议使用 URI 地址，例如：content://com.android.providers.media.documents/document/audio%3A14441。
• Windows：音效文件的绝对路径或 URL 地址（包括文件名后缀），例如：C:\music\audio.mp4。
• iOS 或 macOS：音效文件的绝对路径或 URL 地址（包括文件名后缀），例如：/var/mobile/Containers/Data/audio.mp4。

startPos

音效文件的播放起始位置，单位为毫秒。

返回值

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

所属接口类

• IRtcEngine

preloadEffectEx

预加载指定音效文件到频道。

C++

virtual int preloadEffectEx(const RtcConnection& connection, int soundId, const char* filePath, int startPos = 0) = 0;

自从

自 v4.6.0 版本新增。

每次调用该方法只能将一个音效文件预加载到内存中。如果你需要预加载多个音效文件，请多次调用该方法。预加载完成后，你可以调用 playEffect 播放指定音效，或调用 playAllEffects 播放所有已预加载的音效。

信息

• 为确保使用体验流畅，音效文件的大小不应超过限制。
• 声网建议你在加入频道前调用该方法。

适用场景

该方法适用于多频道场景。

参数

connection

连接信息。详见 RtcConnection。

soundId

音效 ID。

filePath

本地文件的绝对路径或在线文件的 URL。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

startPos

音效文件的播放起始位置（单位为毫秒）。

返回值

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

所属接口类

• IRtcEngineEx

resumeAllEffects

恢复播放所有音效文件。

C++

virtual int resumeAllEffects() = 0;

调用 pauseAllEffects 暂停播放后，可以调用该方法恢复播放。

调用时机

请在调用 pauseAllEffects 之后调用此方法。

返回值

• 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;

调用时机

在调用 playEffect 之后调用该方法。

参数

soundId

音效文件的唯一 ID。

volume

播放音量，取值范围为 [0, 100]。（默认）为 100，表示原始音量。

返回值

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

所属接口类

• IRtcEngine

stopAllEffects

停止播放所有音效。

C++

virtual int stopAllEffects() = 0;

调用该方法可以停止所有音效的播放。如果只需暂停播放，请调用 pauseAllEffects。

调用时机

请在调用 playEffect 之后调用此方法。

返回值

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

所属接口类

• IRtcEngine

stopEffect

停止播放指定音效。

C++

virtual int stopEffect(int soundId) = 0;

调用该方法可停止播放指定的音效。如果只需暂停播放，请调用 pauseEffect 方法。

调用时机

请在调用 playEffect 方法之后调用此方法。

参数

soundId

音效的 ID，每个音效具有唯一的 ID。

返回值

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

所属接口类

• IRtcEngine

unloadAllEffects

释放内存中的所有预加载音效。

C++

virtual int unloadAllEffects() = 0;

返回值

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

所属接口类

• IRtcEngine

unloadEffect

释放指定的预加载音效文件。

C++

virtual int unloadEffect(int soundId) = 0;

调用 preloadEffect 将音效文件加载到内存后，如需释放该音效文件，可调用该方法。

调用时机

你可以在加入频道前或加入频道后调用此方法。

参数

soundId

音效的 ID。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。

所属接口类

• IRtcEngine

onAudioEffectFinished

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

C++

virtual void onAudioEffectFinished(int soundId) {}

当本地音效文件播放结束时，会触发该回调。你可以通过该回调获知指定音效是否已播放完成。

参数

soundId

音效 ID，每个音效文件的唯一标识。

所属接口类

• IRtcEngineEventHandler