音效文件播放
getEffectCurrentPosition
getEffectDuration
获取指定音效文件总时长。
Future<int> getEffectDuration(String filePath);
详情
参数
- filePath
- 文件路径：
- Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以
/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。
- Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以
返回值
- 方法调用成功，返回指定音效文件时长（毫秒）。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
getEffectsVolume
获取音效文件的播放音量。
Future<int> getEffectsVolume();
详情
音量范围为 0~100。100 （默认值）为原始文件音量。
返回值
- 音效文件的音量。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
getVolumeOfEffect
pauseAllEffects
暂停所有音效文件播放。
Future<void> pauseAllEffects();
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类pauseEffect
暂停音效文件播放。
Future<void> pauseEffect(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类playAllEffects
播放所有音效文件。
Future<void> playAllEffects(
{required int loopCount,
required double pitch,
required double pan,
required int gain,
bool publish = false});
详情
多次调用 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: （默认）不将音效发布到远端。只能本地用户能听到该音效。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类playEffect
播放指定的本地或在线音效文件。
Future<void> playEffect(
{required int soundId,
required String filePath,
required int loopCount,
required double pitch,
required double pan,
required int gain,
bool publish = false,
int startPos = 0});
你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，建议同时播放的音效文件不超过 3 个。
调用时机
该方法在加入频道前后均可调用。
调用限制
如果你需要播放在线音效文件，声网建议先将在线音效文件缓存到本地设备，调用 preloadEffect 将缓存的音效文件预加载到内存中，然后再调用此方法播放音效。否则，可能出现因在线音效文件加载超时、加载失败而导致的播放失败和无声的问题。
相关回调
音效文件播放结束后，SDK 会触发 onAudioEffectFinished 回调。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。注意
- filePath
播放文件的地址，支持在线文件的 URL 地址、播放文件的绝对路径，需精确到文件名及后缀。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP 等。
注意- 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
音效文件的播放位置，单位为毫秒。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
preloadEffect
将音效文件加载至内存。
Future<void> preloadEffect(
{required int soundId, required String filePath, int startPos = 0});
为保证通信畅通，请注意控制预加载音效文件的大小。
该方法支持的预加载音频文件的格式见 RTC SDK 支持播放哪些格式的音频文件。
调用时机
声网建议在加入频道前调用该方法。
调用限制
无。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
- 文件路径：
- Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以
/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。
- Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以
- startPos
- 音效文件加载的起始位置，单位为毫秒。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类resumeAllEffects
恢复播放所有音效文件。
Future<void> resumeAllEffects();
当你调用 pauseAllEffects 暂停播放所有音效文件后，如需恢复播放，可以调用该方法。
调用时机
该方法需要在 pauseAllEffects 后调用。
调用限制
无。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类resumeEffect
恢复播放指定音效文件。
Future<void> resumeEffect(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类setEffectPosition
setEffectsVolume
设置音效文件的播放音量。
Future<void> setEffectsVolume(int volume);
详情
参数
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类setVolumeOfEffect
实时调整音效文件的播放音量。
Future<void> setVolumeOfEffect({required int soundId, required int volume});
参数
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类stopAllEffects
停止播放所有音效文件。
Future<void> stopAllEffects();
当你不需要再播放音效文件时，可以调用该方法停止播放。如果你仅需暂停播放，请调用 pauseAllEffects。
调用时机
该方法需要在 playEffect 之后调用。
调用限制
无。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类stopEffect
停止播放指定音效文件。
Future<void> stopEffect(int soundId);
当你不需要再播放某一音效文件时，可以调用该方法停止播放。如果你仅需暂停播放，请调用 pauseEffect。
调用时机
该方法需要在 playEffect 之后调用。
调用限制
无。
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类unloadAllEffects
从内存释放所有预加载音效文件。
Future<void> unloadAllEffects();
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类unloadEffect
从内存释放某个预加载的音效文件。
Future<void> unloadEffect(int soundId);
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类