音效文件播放

getEffectCurrentPosition

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

Java

public abstract int getEffectCurrentPosition(int soundId);

信息

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

参数

soundId

音效 ID。每个音效文件的 ID 是唯一的。

返回值

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

所属接口类

• RtcEngine

getEffectDuration

获取音效文件的时长。

Java

public abstract int getEffectDuration(String filePath);

信息

请在加入频道后调用该方法。

参数

filePath

音效文件的路径：

• Android：路径需精确到文件名和后缀名。支持 URL 地址、绝对路径，或以 /assets/ 开头的文件路径。使用绝对路径访问本地文件可能会遇到权限问题，建议使用 URI 地址，例如：

content://com.android.providers.media.documents/document/audio%3A14441。

返回值

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

所属接口类

• RtcEngine

getEffectsVolume

获取音效的音量。

Java

public abstract double getEffectsVolume();

音量为整数，范围为 0 到 100。默认值为 100，表示原始音量。

信息

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

返回值

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

所属接口类

• RtcEngine

getVolumeOfEffect

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

Java

public abstract int getVolumeOfEffect(int soundId);

参数

soundId

音效文件的 ID。

返回值

• 方法调用成功，返回指定音效的音量，取值范围为 0 到 100，100 表示原始音量。
• 方法调用失败，返回值小于 0。

所属接口类

• RtcEngine

pauseAllEffects

暂停所有音效。

Java

public abstract int pauseAllEffects();

返回值

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

所属接口类

• RtcEngine

pauseEffect

暂停指定音效文件的播放。

Java

public abstract int pauseEffect(int soundId);

参数

soundId

音效 ID。每个音效文件的 ID 是唯一的。

返回值

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

所属接口类

• RtcEngine

playAllEffects

播放所有音效。

Java

public abstract int playAllEffects(int loopCount, double pitch, double pan, double gain, boolean publish);

多次调用 preloadEffect 将多个音效预加载到内存后，可以调用该方法为频道内所有用户播放所有预加载的音效。

参数

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：（默认）不发布音效，只有本地用户能听到。

返回值

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

所属接口类

• RtcEngine

playEffect [1/2]

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

Java

public abstract int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish);

该方法支持播放以 content:// 开头的 URI 文件。关于支持的音频文件格式，详见声网 RTC SDK 支持哪些格式的音频文件。若本地音乐文件不存在、SDK 不支持该文件格式，或无法访问音乐文件的 URL，SDK 会报告 AUDIO_MIXING_REASON_CAN_NOT_OPEN。

信息

如果需要播放在线音效文件，建议先将其缓存到本地设备，调用 preloadEffect 将文件预加载到内存中，再调用该方法播放音效。否则可能因加载超时或失败导致播放失败或无声。

调用时机

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

相关回调

音效文件播放完成后，SDK 会触发 onAudioEffectFinished 回调。

参数

soundId

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

filePath

音效文件路径。支持以下格式：

• 以 content:// 开头的 URI 地址。
• 以 /assets/ 开头的路径。
• URL。
• 本地文件的绝对路径（需精确到文件名和扩展名）。

支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。

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：不将音效发布给远端用户，只有本地用户能听到音效。

返回值

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

所属接口类

• RtcEngine

playEffect [2/2]

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

Java

public abstract int playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish, int startPos);

该方法支持播放以 content:// 开头的 URI 文件。支持的音频文件格式详见声网 RTC SDK 支持哪些格式的音频文件。如果本地音频文件不存在、SDK 不支持该文件格式，或无法访问音频文件的 URL，SDK 会返回错误码 AUDIO_MIXING_REASON_CAN_NOT_OPEN。

信息

如果需要播放在线音效文件，声网建议先将其缓存到本地设备，调用 preloadEffect 将文件预加载到内存中，再调用该方法播放音效。否则，可能因加载超时或失败导致播放失败或无声。

调用时机

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

相关回调

音效文件播放完成后，SDK 会触发 onAudioEffectFinished 回调。

参数

soundId

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

信息

如果你已通过调用 preloadEffect 将音效预加载到内存中，请确保该参数的值与 preloadEffect 中的 soundId 相同。

filePath

音效文件路径。支持以 content:// 开头的 URI 地址、以 /assets/ 开头的路径、URL 以及本地文件的绝对路径。路径需精确到文件名及扩展名。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。

信息

如果你已通过调用 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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

playEffectEx [1/2]

在频道中播放指定音效。

Java

public abstract int playEffectEx(RtcConnection connection, int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish, int startPos);

自从

自 v4.6.0 版本新增。

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

信息

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

适用场景

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

参数

connection

连接信息。详见 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.0 到 100.0，默认值为 100.0（原始音量）。值越小，音量越低。

publish

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

• true：在频道中发布音效。
• false：不在频道中发布音效。

startPos

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

返回值

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

所属接口类

• RtcEngineEx

playEffectEx [2/2]

在频道中播放指定音效。

Java

public abstract int playEffectEx(RtcConnection connection, int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish);

自从

自 v4.6.0 版本新增。

调用 preloadEffect 预加载音效后，你可以调用 playEffectEx 将指定音效播放给频道内所有用户。每次调用该方法只能播放一个音效，若需同时播放多个音效，请使用不同的 soundId 和 filePath 多次调用该方法。

信息

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

适用场景

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

参数

connection

连接信息。详见 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.0 到 100.0，默认值为 100（原始音量）。数值越小，音量越低。

publish

是否在频道中发布音效：

• true：在频道中发布音效。
• false：不在频道中发布音效。

返回值

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

所属接口类

• RtcEngineEx

preloadEffect [1/2]

预加载指定的音效文件。

Java

public abstract int preloadEffect(int soundId, String filePath, int startPos);

你可以多次调用该方法，将多个音效文件预加载到内存中。预加载完成后，可以调用 playEffect 播放预加载的音效，或调用 playAllEffects 播放所有已预加载的音效。

信息

• 为确保通信流畅，请限制音效文件的大小。
• 声网建议你在加入频道前调用该方法。
• 如果在调用 playEffect 前调用了 preloadEffect，则在 playEffect 执行后文件资源不会被关闭。下次调用 playEffect 时将从头开始播放。
• 如果未在调用 playEffect 前调用 preloadEffect，则在 playEffect 执行后资源将被销毁。下次调用 playEffect 时将尝试重新打开文件并从头播放。

参数

soundId

音效的 ID。

filePath

本地音效文件的绝对路径或在线音效文件的 URL。

startPos

在线音效文件的起始播放位置。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 和 wav。

返回值

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

所属接口类

• RtcEngine

preloadEffect [2/2]

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

Java

public abstract int preloadEffect(int soundId, String filePath);

确保所有预加载文件的总大小不超过限制。支持的音频文件格式，详见声网 RTC SDK 支持哪些音频文件格式。

调用时机

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

参数

soundId

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

filePath

文件路径：

• Android：文件路径需精确到文件名和后缀名。声网支持 URL 地址、绝对路径，或以 /assets/ 开头的文件路径。如果使用绝对路径访问本地文件，可能会遇到权限问题，因此建议使用 URI 地址。例如：

content://com.android.providers.media.documents/document/audio%3A14441。

返回值

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

所属接口类

• RtcEngine

preloadEffectEx [1/2]

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

Java

public abstract int preloadEffectEx(RtcConnection connection, int soundId, String filePath, int startPos);

自从

自 v4.6.0 版本新增。

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

信息

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

适用场景

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

参数

connection

连接信息。详见 RtcConnection。

soundId

音效 ID。

filePath

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

startPos

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

返回值

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

所属接口类

• RtcEngineEx

preloadEffectEx [2/2]

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

Java

public abstract int preloadEffectEx(RtcConnection connection, int soundId, String filePath);

自从

自 v4.6.0 版本新增。

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

信息

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

适用场景

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

参数

connection

连接信息。详见 RtcConnection。

soundId

音效 ID。

filePath

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

返回值

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

所属接口类

• RtcEngineEx

resumeAllEffects

恢复播放所有音效文件。

Java

public abstract int resumeAllEffects();

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

调用时机

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

返回值

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

所属接口类

• RtcEngine

resumeEffect

恢复播放指定音效。

Java

public abstract int resumeEffect(int soundId);

参数

soundId

音效 ID。每个音效文件的 ID 是唯一的。

返回值

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

所属接口类

• RtcEngine

setEffectPosition

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

Java

public abstract int setEffectPosition(int soundId, int pos);

信息

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

参数

soundId

音效 ID。每个音效文件的 ID 是唯一的。

pos

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

返回值

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

所属接口类

• RtcEngine

setEffectsVolume

设置音效的播放音量。

Java

public abstract int setEffectsVolume(double volume);

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

调用时机

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

参数

volume

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

返回值

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

所属接口类

• RtcEngine

setVolumeOfEffect

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

Java

public abstract int setVolumeOfEffect(int soundId, double volume);

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

调用时机

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

参数

soundId

音效的 ID。每个音效文件具有唯一的 ID。

volume

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

返回值

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

所属接口类

• RtcEngine

stopAllEffects

停止播放所有音效。

Java

public abstract int stopAllEffects();

如果你只需要暂停播放，请调用 pauseAllEffects 方法。

调用时机

在调用 playEffect 方法之后调用。

返回值

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

所属接口类

• RtcEngine

stopEffect

停止播放指定音效。

Java

public abstract int stopEffect(int soundId);

如果只需要暂停播放，请调用 pauseEffect 方法。

调用时机

在调用 playEffect 之后调用。

参数

soundId

音效的 ID。每个音效都有唯一的 ID。

返回值

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

所属接口类

• RtcEngine

unloadEffect

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

Java

public abstract int unloadEffect(int soundId);

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

调用时机

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

参数

soundId

音效的 ID。每个音效都有唯一的 ID。

返回值

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

所属接口类

• RtcEngine

onAudioEffectFinished

本地音效文件播放完成时的回调。

Java

public void onAudioEffectFinished(int soundId) {}

触发时机

该回调在本地音效文件播放完成时被触发。

参数

soundId

音效文件的唯一 ID。

所属接口类

• IRtcEngineEventHandler