音效文件播放

getEffectCurrentPosition

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

Java

public int getEffectCurrentPosition(int soundId);

详情

注意

该方法需要在 playEffect [2/2] 后调用。

参数

soundId

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

返回值

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

所属接口类

• RtcEngine

getEffectDuration

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

Java

public abstract int getEffectDuration(String filePath);

详情

注意

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

参数

filePath

文件路径：

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

返回值

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

所属接口类

• RtcEngine

getEffectsVolume

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

Java

public double getEffectsVolume();

详情

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

注意

该方法需要在 playEffect [2/2] 后调用。

返回值

• 音效文件的音量。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IAudioEffectManager

getVolumeOfEffect

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

Java

public abstract int getVolumeOfEffect(int soundId);

参数

soundId

音效文件的 ID。

返回值

• ≥ 0: 方法调用成功，返回播放音量。音量范围为 [0,100]。100 为原始音量。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

pauseAllEffects

暂停所有音效文件播放。

Java

public abstract int pauseAllEffects();

返回值

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

所属接口类

• IAudioEffectManager

pauseEffect

暂停音效文件播放。

Java

public abstract int pauseEffect(int soundId);

参数

soundId

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

返回值

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

所属接口类

• IAudioEffectManager

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 支持播放哪些格式的音频文件。如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告 AUDIO_MIXING_REASON_CAN_NOT_OPEN。

你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。

调用时机

该方法在加入频道前后均可调用。

调用限制

如果你需要播放在线音效文件，声网建议先将在线音效文件缓存到本地设备，调用 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 次，即总计播放 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: 不将音效发布至远端。只有本地用户能听到音效。

返回值

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

所属接口类

• IAudioEffectManager

playEffect [2/2]

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

Java

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

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

你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。

调用时机

该方法在加入频道前后均可调用。

调用限制

如果你需要播放在线音效文件，声网建议先将在线音效文件缓存到本地设备，调用 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 次，即总计播放 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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IAudioEffectManager

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（原始音量）。值越小，音量越低。

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 版本新增。

该方法允许你设置是否在频道中发布音效。要同时播放多个音效文件，请使用不同的 soundId 和 filePath 多次调用该方法。调用 preloadEffect 预加载音效后，可以调用该方法将指定音效播放给频道内的所有用户。每次调用该方法只能播放一个音效。如需同时播放多个音效，请多次调用该方法。

注意

• 声网建议同时播放的音效不超过三个。
• 此方法中的音效 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

将音效文件加载至内存。

Java

public int preloadEffect(int soundId, String filePath);

为保证通信畅通，请注意控制预加载音效文件的大小。

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

调用时机

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

调用限制

无。

参数

soundId

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

filePath

文件路径：

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

返回值

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

所属接口类

• IAudioEffectManager

preloadEffectEx [1/2]

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

Java

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

自从

自 v4.6.0 版本新增。

每次调用该方法时，仅将一个指定的音效文件预加载到内存中。若需预加载多个音效文件，请多次调用该方法。预加载完成后，你可以调用 playEffect [2/2] 播放指定音效，或调用 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 [2/2] 播放已预加载的音效，或调用 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: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IAudioEffectManager

resumeEffect

恢复播放指定音效文件。

Java

public abstract int resumeEffect(int soundId);

参数

soundId

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

返回值

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

所属接口类

• IAudioEffectManager

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 [2/2] 后调用。

调用限制

无。

参数

volume

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

返回值

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

所属接口类

• IAudioEffectManager

setVolumeOfEffect

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

Java

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

调用时机

该方法需要在 playEffect [2/2] 后调用。

调用限制

无。

参数

soundId

指定音效的 ID。每个音效均有唯一的 ID。

volume

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

返回值

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

所属接口类

• IAudioEffectManager

stopAllEffects

停止播放所有音效文件。

Java

public abstract int stopAllEffects();

当你不需要再播放音效文件时，可以调用该方法停止播放。如果你仅需暂停播放，请调用 pauseAllEffects。

调用时机

该方法需要在 playEffect [1/2] 或 playEffect [2/2] 之后调用。

调用限制

无。

返回值

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

所属接口类

• IAudioEffectManager

stopEffect

停止播放指定音效文件。

Java

public abstract int stopEffect(int soundId);

当你不需要再播放某一音效文件时，可以调用该方法停止播放。如果你仅需暂停播放，请调用 pauseEffect。

调用时机

该方法需要在 playEffect [1/2] 或 playEffect [2/2] 之后调用。

调用限制

无。

参数

soundId

指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

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

所属接口类

• IAudioEffectManager

unloadEffect

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

Java

public abstract int unloadEffect(int soundId);

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

调用时机

该方法在加入频道前后均可调用。

调用限制

无。

参数

soundId

指定音效文件的 ID。每个音效文件均有唯一的 ID。

返回值

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

所属接口类

• IAudioEffectManager

onAudioEffectFinished

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

Java

public void onAudioEffectFinished(int soundId) {}

详情

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

参数

soundId

指定音效的 ID。每个音效均有唯一的 ID。

所属接口类

• IRtcEngineEventHandler