playEffect method

@override Future<void> playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, double gain, bool publish, [ int? startPos, ])

Plays a specified local or online audio effect file.

With this method, you can set the loop count, pitch, pan, and gain of the audio effect file and whether the remote user can hear the audio effect.

To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time.

After completing playing an audio effect file, the SDK triggers the RtcEngineEventHandler.audioEffectFinished callback.

Note

• Call this method joining a channel.

Parameter soundId Audio effect ID. The ID of each audio effect file is unique. If you preloaded the audio effect into the memory through the RtcEngine.preloadEffect method, ensure that this parameter is set to the same value as in RtcEngine.preloadEffect.

Parameter filePath The file path, including the filename extensions.

• Android: To access an online file, Agora supports using a URL address; to access a local file, Agora supports using a URI address, an absolute path, or a path that starts with /assets/. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav. For details, see Supported Media Formats. Note: You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: "content://com.android.providers.media.documents/document/audio%3A14441".
• iOS: To access an online file, Agora supports using a URL address; to access a local file, Agora supports using an absolute path. For example: /var/mobile/Containers/Data/audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. For details, see Best Practices for iOS Audio.

Parameter loopCount The number of times the audio effect loops:

• ≥ 0: The number of loops. For example, 1 means loop one time, which means play the audio effect two times in total.
• -1: Play the audio effect in an indefinite loop.

Parameter pitch The pitch of the audio effect. The range is 0.5,2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch.

Parameter pan The spatial position of the audio effect. The range is -1.0,1.0. For example:

• -1.0: The audio effect occurs on the left.
• 0.0: The audio effect occurs in the front.
• 1.0: The audio effect occurs on the right.

Parameter gain The volume of the audio effect. The range is 0.0,100.0. The default value is 100.0, which means the original volume. The smaller the value, the less the gain.

Parameter publish Whether to publish the audio effect to the remote users:

• true: Publish. Both the local user and remote users can hear the audio effect.
• false: Do not publish. Only the local user can hear the audio effect.

Parameter startPos The playback position (ms) of the audio effect file.

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,
  });
}