playEffect method

Future<void> playEffect (
  1. int soundId,
  2. String filePath,
  3. int loopCount,
  4. double pitch,
  5. double pan,
  6. double gain,
  7. bool publish,
  8. [int startPos]
)

播放指定音效文件。 该方法播放指定的本地或在线音效文件。你可以在该方法中设置音效文件的播放次数、音调、音效的空间位置和增益，以及远端用户是否能听到该音效。

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

调用该方法播放音效结束后，SDK 会触发 RtcEngineEventHandler.audioEffectFinished 回调。

Parameter soundId 音效的 ID。每个音效均有唯一的 ID。如果你已通过 RtcEngine.preloadEffect 将音效加载至内存， 确保这里的 soundID 与 RtcEngine.preloadEffect 设置的 soundId 相同。

Parameter filePath 音效文件的文件路径，需精确到文件名及后缀。

  • （Android）：支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，Agora 推荐使用 URI 地址访问本地文件。例如："content://com.android.providers.media.documents/document/audio%3A14441"。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。 如果你已通过 RtcEngine.preloadEffect 将音效加载至内存，请确保该参数与 RtcEngine.preloadEffect 中设置的 filePath 相同。
  • （iOS）：音效文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。 支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。 详见 Best Practices for iOS Audio。 如果你已通过 RtcEngine.preloadEffect 将音效加载至内存，请确保该参数与 RtcEngine.preloadEffect 中设置的 filePath 相同。

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

Parameter pitch 音效的音调。取值范围为 0.5,2.0。默认值为 1.0，代表原始音调。取值越小，则音调越低。

Parameter pan 音效的空间位置。取值范围为 -1.0,1.0：

  • -1.0：音效出现在左边。
  • 0：音效出现在正前边。
  • 1.0：音效出现在右边。

Parameter gain 音效的音量。取值范围为 0.0,100.0。100.0 为默认值，代表原始音量。取值越小，则音量越低。

Parameter publish 是否将音效发布到远端：

  • true：音效文件在本地播放的同时，会发布到 Agora 云上，因此远端用户也能听到该音效。
  • false：音效文件不会发布到 Agora 云上，因此只能在本地听到该音效。

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

Implementation

@override
Future<void> playEffect(int soundId, String filePath, int loopCount,
    double pitch, double pan, double gain, bool publish,
    [int startPos]) {
  return _invokeMethod('playEffect', {
    'soundId': soundId,
    'filePath': filePath,
    'loopCount': loopCount,
    'pitch': pitch,
    'pan': pan,
    'gain': gain,
    'publish': publish,
    'startPos': startPos
  });
}