需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

音效文件播放

  • Android

更新时间不可用

getEffectCurrentPosition

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

Java
public abstract int getEffectCurrentPosition(int soundId);

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

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

getEffectDuration

获取音效文件的时长。

Java
public abstract int getEffectDuration(String filePath);

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

参数

参数名描述
filePath

音效文件的路径：

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

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

getEffectsVolume

获取音效的音量。

Java
public abstract double getEffectsVolume();

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

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

返回值

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

所属接口类

getVolumeOfEffect

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

Java
public abstract int getVolumeOfEffect(int soundId);

参数

参数名描述
soundId

音效文件的 ID。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

pauseAllEffects

暂停所有音效。

Java
public abstract int pauseAllEffects();

返回值

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

所属接口类

pauseEffect

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

Java
public abstract int pauseEffect(int soundId);

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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

所属接口类

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

注：

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

调用时机

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

相关回调

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

参数

参数名描述
soundId

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

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

filePath

注： 如果你已通过调用 preloadEffect 将音效预加载到内存中，请确保该参数的值与 preloadEffect 中的 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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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 文件。关于支持的音频文件格式，参见 What formats of audio files does the Agora RTC SDK support。如果本地音频文件不存在、SDK 不支持该文件格式，或无法访问音频文件的 URL，SDK 会报告 AUDIO_MIXING_REASON_CAN_NOT_OPEN。

注：

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

调用时机

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

相关回调

音效文件播放完成后，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：方法调用失败。

所属接口类

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 和文件路径必须与 preloadEffectEx 方法中的一致。
  • 如果在调用 playEffectEx 之前调用了 preloadEffectEx，则在 playEffectEx 执行后文件资源不会被关闭。下次调用 playEffectEx 时将从头开始播放。
  • 如果在调用 playEffectEx 之前未调用 preloadEffectEx，则在 playEffectEx 执行后资源将被销毁。下次调用 playEffectEx 时将尝试重新打开文件并从头开始播放。

适用场景

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

参数

参数名描述
connection

连接信息，详见 RtcConnection。

soundId

音效 ID。

filePath

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

loopCount

音效的循环播放次数：

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

所属接口类

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

调用 preloadEffectEx 预加载音效后，可以使用该方法将指定音效播放给频道中的所有用户。你可以多次调用该方法，并传入不同的 soundId 和 filePath，以同时播放多个音效文件。每次调用该方法只能播放一个音效。

注：

  • 声网建议不要同时播放超过三个音效。
  • 本方法中的音效 ID 和文件路径必须与 preloadEffectEx 方法中保持一致。
  • 如果在调用 playEffectEx 之前调用了 preloadEffectEx，则在 playEffectEx 执行后文件资源不会被关闭。下次调用 playEffectEx 时将从头开始播放。
  • 如果在调用 playEffectEx 之前未调用 preloadEffectEx，则在 playEffectEx 执行后资源将被销毁。下次调用 playEffectEx 时将尝试重新打开文件并从头播放。

适用场景

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

参数

参数名描述
connection

连接信息，详见 RtcConnection。

soundId

音效 ID。

filePath

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

loopCount

音效的循环播放次数：

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

所属接口类

preloadEffect [1/2]

预加载指定的音效文件。

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

该方法每次调用时仅将一个指定的音效文件预加载到内存中。若需预加载多个音效文件，请多次调用该方法。

注：

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

参数

参数名描述
soundId

音效的 ID。

filePath

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

startPos

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

preloadEffect [2/2]

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

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

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

注：

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

调用时机

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

参数

参数名描述
soundId

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

filePath

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

  • URL 地址。
  • 绝对路径。
  • 以 /assets/ 开头的文件路径。

路径需精确到文件名和后缀名。如果使用绝对路径访问本地文件，可能会遇到权限问题，建议使用 URI 地址，例如：content://com.android.providers.media.documents/document/audio%3A14441。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

preloadEffectEx [1/2]

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

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

自从

自 v4.6.0 版本新增。

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

注：

  • 为确保使用体验流畅，音效文件的大小不应超过限制。
  • 声网建议在加入频道前调用该方法。
  • 如果在调用 playEffectEx 前已调用 preloadEffectEx，则 playEffectEx 执行后不会关闭文件资源。下次调用 playEffectEx 时将从头开始播放。
  • 如果在调用 playEffectEx 前未调用 preloadEffectEx，则 playEffectEx 执行后会销毁文件资源。下次调用 playEffectEx 时将尝试重新打开文件并从头开始播放。

适用场景

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

参数

参数名描述
connection

连接信息，详见 RtcConnection。

soundId

音效 ID。

filePath

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

startPos

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

preloadEffectEx [2/2]

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

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

自从

自 v4.6.0 版本新增。

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

注：

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

适用场景

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

参数

参数名描述
connection

连接信息。详见 RtcConnection。

soundId

音效 ID。

filePath

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

resumeAllEffects

恢复播放所有音效文件。

Java
public abstract int resumeAllEffects();

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

调用时机

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

返回值

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

所属接口类

resumeEffect

恢复播放指定音效。

Java
public abstract int resumeEffect(int soundId);

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setEffectPosition

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

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

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

参数

参数名描述
soundId

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

pos

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setEffectsVolume

设置音效的播放音量。

Java
public abstract int setEffectsVolume(double volume);

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

调用时机

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

参数

参数名描述
volume

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setVolumeOfEffect

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

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

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

调用时机

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

参数

参数名描述
soundId

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

volume

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

stopAllEffects

停止播放所有音效。

Java
public abstract int stopAllEffects();

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

调用时机

在调用 playEffect 方法之后调用。

返回值

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

所属接口类

stopEffect

停止播放指定音效。

Java
public abstract int stopEffect(int soundId);

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

调用时机

在调用 playEffect 之后调用。

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

unloadEffect

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

Java
public abstract int unloadEffect(int soundId);

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

调用时机

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

参数

参数名描述
soundId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

onAudioEffectFinished

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

Java
public void onAudioEffectFinished(int soundId) {}

触发时机

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

参数

参数名描述
soundId

音效文件的唯一 ID。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利