playEffect abstract method

Future<void> playEffect({
  1. required int soundId,
  2. required String filePath,
  3. required int loopCount,
  4. required double pitch,
  5. required double pan,
  6. required int gain,
  7. bool publish = false,
  8. int startPos = 0,
})

Plays the specified local or online audio effect file.

You can call this method multiple times with different soundID and filePath to play multiple audio effect files simultaneously. For optimal user experience, it is recommended to play no more than 3 audio effect files at the same time. If you need to play an online audio effect file, Agora recommends caching the file to the local device first, then calling preloadEffect to preload the cached file into memory, and finally calling this method to play the effect. Otherwise, playback failure or no sound may occur due to timeout or failure in loading the online file.

  • soundId ID of the audio effect. Each audio effect has a unique ID. If you have loaded the audio effect into memory using preloadEffect, make sure this parameter matches the soundId set in preloadEffect.
  • filePath Path of the file to be played. Supports URL of online files or absolute path of local files. Must include file name and extension. Supported formats include MP3, AAC, M4A, MP4, WAV, 3GP, etc. If you have loaded the audio effect into memory using preloadEffect, make sure this parameter matches the filePath set in preloadEffect.
  • loopCount Number of times the audio effect is looped. ≥ 0: Number of loops. For example, 1 means loop once, i.e., played twice in total. -1: Loops indefinitely.
  • pitch Pitch of the audio effect. Value range is 0.5,2.0. Default is 1.0, which represents the original pitch. The smaller the value, the lower the pitch.
  • pan Spatial position of the audio effect. Value range is -1.0,1.0, for example: -1.0: Audio effect appears on the left 0.0: Audio effect appears in the center 1.0: Audio effect appears on the right
  • gain Volume of the audio effect. Value range is 0.0,100.0. Default is 100.0, which represents the original volume. The smaller the value, the lower the volume.
  • publish Whether to publish the audio effect to remote users: true : Publishes the audio effect to remote users. Both local and remote users can hear it. false : Does not publish the audio effect to remote users. Only local users can hear it.
  • startPos Playback position of the audio effect file in milliseconds.

Returns When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions. < 0: The method call fails. See Error Codes for details and resolution suggestions.

Implementation

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