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

音效文件播放

  • C++

更新时间不可用

getEffectCurrentPosition

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

C++
virtual int getEffectCurrentPosition(int soundId) = 0;

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

参数

参数名描述
soundId

音效 ID。

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

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

返回值

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

所属接口类

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

所属接口类

getEffectsVolume

获取当前音效的音量。

C++
virtual int getEffectsVolume() = 0;

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

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

返回值

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

所属接口类

getVolumeOfEffect

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

C++
virtual int getVolumeOfEffect(int soundId) = 0;

参数

参数名描述
soundId

音效文件的 ID。

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

返回值

  • 方法调用成功，返回指定音效的音量，取值范围为 0 到 100，100 表示原始音量。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

pauseAllEffects

暂停所有音效。

C++
virtual int pauseAllEffects() = 0;

返回值

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

所属接口类

pauseEffect

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

C++
virtual int pauseEffect(int soundId) = 0;

参数

参数名描述
soundId

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

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

返回值

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

所属接口类

playAllEffects

播放所有音效文件。

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

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

参数

参数名描述
loopCount

音效文件的循环播放次数：

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

所属接口类

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;

调用 preloadEffect 后，可以调用该方法为频道内所有用户播放指定的音效。每次调用该方法只能播放一个音效。如需同时播放多个音效，需要多次调用该方法。

注：

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

调用时机

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

相关回调

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

参数

参数名描述
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 到 100，默认值为 100（原始音量）。值越小，音量越低。

publish

是否将音效发布到远端：

  • true：将音效发布到远端。
  • false：（默认）不将音效发布到远端。
startPos

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

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

返回值

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

所属接口类

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 多次调用该方法。你还可以设置是否在频道中发布该音效。

注：

适用场景

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

参数

参数名描述
connection

RtcConnection 对象，详见 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 到 100，默认值为 100（原始音量）。数值越小，音量越低。

publish

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

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

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

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

返回值

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

所属接口类

preloadEffect

预加载指定的音效文件。

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

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

注：

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

调用时机

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

参数

参数名描述
soundId

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

filePath

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

startPos

音效播放的起始位置，单位为毫秒。默认值为 0，表示从头开始播放。

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

返回值

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

所属接口类

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

所属接口类

resumeAllEffects

恢复播放所有音效文件。

C++
virtual int resumeAllEffects() = 0;

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

调用时机

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

返回值

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

所属接口类

resumeEffect

恢复播放指定音效的播放。

C++
virtual int resumeEffect(int soundId) = 0;

参数

参数名描述
soundId

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

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

返回值

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

所属接口类

setEffectPosition

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

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

设置成功后，音效文件将从指定位置开始播放。

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

参数

参数名描述
soundId

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

pos

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

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

返回值

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

所属接口类

setEffectsVolume

设置音效播放音量。

C++
virtual int setEffectsVolume(int volume) = 0;

调用时机

在调用 playEffect 方法之后调用。

参数

参数名描述
volume

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

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

返回值

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

所属接口类

setVolumeOfEffect

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

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

调用时机

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

参数

参数名描述
soundId

音效文件的唯一 ID。

volume

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

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

返回值

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

所属接口类

stopAllEffects

停止播放所有音效。

C++
virtual int stopAllEffects() = 0;

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

调用时机

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

返回值

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

所属接口类

stopEffect

停止播放指定音效。

C++
virtual int stopEffect(int soundId) = 0;

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

调用时机

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

参数

参数名描述
soundId

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

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

返回值

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

所属接口类

unloadAllEffects

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

C++
virtual int unloadAllEffects() = 0;

返回值

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

所属接口类

unloadEffect

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

C++
virtual int unloadEffect(int soundId) = 0;

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

调用时机

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

参数

参数名描述
soundId

音效的 ID。

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

返回值

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

所属接口类

onAudioEffectFinished

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

C++
virtual void onAudioEffectFinished(int soundId) {}

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

参数

参数名描述
soundId

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

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利