音效文件播放
- Flutter
更新时间不可用
getEffectCurrentPosition
获取指定音效文件的播放进度。
Future<int> getEffectCurrentPosition(int soundId);注： 该方法需要在 playEffect 后调用。
参数
返回值
- 方法调用成功，返回指定音效文件的播放进度（毫秒）。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getEffectDuration
获取指定音效文件总时长。
Future<int> getEffectDuration(String filePath);注： 该方法需要在加入频道后调用。
参数
返回值
- 方法调用成功，返回指定音效文件时长（毫秒）。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getEffectsVolume
获取音效文件的播放音量。
Future<int> getEffectsVolume();音量范围为 0~100。100 （默认值）为原始文件音量。
注： 该方法需要在 playEffect 后调用。
返回值
- 音效文件的音量。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getVolumeOfEffect
获取指定音效文件的播放音量。
Future<int> getVolumeOfEffect(int soundId);参数
返回值
- ≥ 0: 方法调用成功，返回播放音量。音量范围为 [0,100]。100 为原始音量。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
pauseAllEffects
暂停所有音效文件播放。
Future<void> pauseAllEffects();返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
pauseEffect
暂停音效文件播放。
Future<void> pauseEffect(int soundId);参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
playAllEffects
播放所有音效文件。
Future<void> playAllEffects(
{required int loopCount,
required double pitch,
required double pan,
required int gain,
bool publish = false});多次调用 preloadEffect 预加载多个音效文件后，你可以调用本方法播放所有预加载的音效文件。
参数
| 参数名 | 描述 |
|---|---|
loopCount | |
pitch | |
pan | |
gain | |
publish |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 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 | |
filePath | 播放文件的地址，支持在线文件的 URL 地址、播放文件的绝对路径，需精确到文件名及后缀。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP 等。 注： 如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 |
loopCount | |
pitch | |
pan | |
gain | |
publish | |
startPos |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
所属接口类
playEffectEx
在频道中播放指定音效。
Future<void> playEffectEx(
{required RtcConnection connection,
required int soundId,
required String filePath,
required int loopCount,
required double pitch,
required double pan,
required int gain,
bool publish = false,
int startPos = 0});自从
自 v6.6.2 版本新增。
你可以调用该方法在频道内向所有用户播放指定音效。每次调用该方法只能播放一个音效。若需同时播放多个音效，请使用不同的 soundId 和 filePath 多次调用该方法。你还可以设置是否在频道中发布该音效。
注：
- 声网建议不要同时播放超过三个音效。
- 该方法中的音效 ID 和文件路径必须与 preloadEffectEx 方法中的保持一致。
- 如果在调用 playEffectEx 之前调用了 preloadEffectEx，playEffectEx 执行后不会关闭文件资源。下次调用 playEffectEx 时会直接从头开始播放。
- 如果在调用 playEffectEx 之前未调用 preloadEffectEx，playEffectEx 执行后会销毁资源。下次调用 playEffectEx 时会尝试重新打开文件并从头播放。
适用场景
该方法适用于多频道场景。
参数
| 参数名 | 描述 |
|---|---|
connection | RtcConnection 对象，详见 RtcConnection。 |
soundId | |
filePath | |
loopCount | |
pitch | |
pan | |
gain | |
publish | |
startPos |
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
所属接口类
preloadEffect
将音效文件加载至内存。
Future<void> preloadEffect(
{required int soundId, required String filePath, int startPos = 0});为保证通信畅通，请注意控制预加载音效文件的大小。 该方法支持的预加载音频文件的格式见 RTC SDK 支持播放哪些格式的音频文件。
调用时机
声网建议在加入频道前调用该方法。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
preloadEffectEx
将指定音效预加载到频道中。
Future<void> preloadEffectEx(
{required RtcConnection connection,
required int soundId,
required String filePath,
int startPos = 0});自从
自 v6.6.2 版本新增。
每次调用该方法时，只能将一个音效文件预加载到内存中。如果需要预加载多个音效文件，请多次调用该方法。预加载完成后，可以调用 playEffect 播放预加载的音效，或调用 playAllEffects 播放所有预加载的音效。
注：
- 为确保使用体验流畅，音效文件的大小不应超过限制。
- 声网建议在加入频道前调用该方法。
- 如果在调用 playEffectEx 前已调用 preloadEffectEx，则 playEffectEx 执行后不会关闭文件资源。下次调用 playEffectEx 时会直接从头开始播放。
- 如果在调用 playEffectEx 前未调用 preloadEffectEx，则 playEffectEx 执行后会销毁资源。下次调用 playEffectEx 时会尝试重新打开文件并从头开始播放。
适用场景
该方法适用于多频道场景。
参数
| 参数名 | 描述 |
|---|---|
connection | 连接信息。详见 RtcConnection。 |
soundId | |
filePath | |
startPos |
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
所属接口类
resumeAllEffects
恢复播放所有音效文件。
Future<void> resumeAllEffects();当你调用 pauseAllEffects 暂停播放所有音效文件后，如需恢复播放，可以调用该方法。
调用时机
该方法需要在 pauseAllEffects 后调用。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
resumeEffect
恢复播放指定音效文件。
Future<void> resumeEffect(int soundId);参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setEffectPosition
设置指定音效文件的播放位置。
Future<void> setEffectPosition({required int soundId, required int pos});成功设置后，本地音效文件会在指定位置开始播放。
注： 该方法需要在 playEffect 后调用。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setEffectsVolume
设置音效文件的播放音量。
Future<void> setEffectsVolume(int volume);调用时机
该方法需要在 playEffect 后调用。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setVolumeOfEffect
设置指定音效文件的播放音量。
Future<void> setVolumeOfEffect({required int soundId, required int volume});调用时机
该方法需要在 playEffect 后调用。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
stopAllEffects
停止播放所有音效文件。
Future<void> stopAllEffects();当你不需要再播放音效文件时，可以调用该方法停止播放。如果你仅需暂停播放，请调用 pauseAllEffects。
调用时机
该方法需要在 playEffect 之后调用。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
stopEffect
停止播放指定音效文件。
Future<void> stopEffect(int soundId);当你不需要再播放某一音效文件时，可以调用该方法停止播放。如果你仅需暂停播放，请调用 pauseEffect。
调用时机
该方法需要在 playEffect 之后调用。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
unloadAllEffects
从内存释放所有预加载音效文件。
Future<void> unloadAllEffects();返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
unloadEffect
从内存释放某个预加载的音效文件。
Future<void> unloadEffect(int soundId);调用 preloadEffect 将音效文件加载至内存后，如需释放该音效文件，请调用该方法。
调用时机
该方法在加入频道前后均可调用。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
onAudioEffectFinished
本地音效文件播放已结束回调。
final void Function(int soundId)? onAudioEffectFinished;当播放音效结束后，会触发该回调。