startAudioMixing method Null safety

Future<void> startAudioMixing(
  1. String filePath,
  2. bool loopback,
  3. bool replace,
  4. int cycle,
  5. [int? startPos]
)

Starts playing and mixing the music file.

This method mixes the specified local or online audio file with the audio captured by the microphone, or replaces the audio captured by the microphone with the specified local or remote audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops.

After successfully playing the music file, the SDK triggers RtcEngineEventHandler.audioMixingStateChanged (AudioMixingStateCode.Playing). After finishing playing the music file, the SDK triggers the RtcEngineEventHandler.audioMixingStateChanged (AudioMixingStateCode.Stopped).

Note

  • This method supports both Android and iOS. To use this method in Android, ensure that the Android device is v4.2 or later, and the API version is v16 or later.
  • Call this method when you are in the channel, otherwise it may cause issues.
  • If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the AudioMixingReason.TooFrequentCall error occurs.
  • If you want to play an online music file, Agora does not recommend using the redirected URL address. Some Android devices may fail to open a redirected URL address.
  • If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns AudioMixingReason.CanNotOpen.
  • If you call this method on an emulator, only the MP3 file format is supported.

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 loopback Whether to only play the music file on the local client:

  • true: Only play music files on the local client so that only the local user can hear the music.
  • false: Publish music files to remote clients so that both the local user and remote users can hear the music.

Parameter replace Whether to replace the audio captured by the microphone with a music file:

  • true: Replace. Users can only hear music.
  • false: Do not replace. Users can hear both music and audio captured by the microphone.

Parameter cycle The number of times the music file plays.

  • ≤ 0: The number of playback times. For example, 0 means that the SDK does not play the music file, while 1 means that the SDK plays the music file once.
  • -1: Play the music in an indefinite loop.

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

Implementation

@override
Future<void> startAudioMixing(
    String filePath, bool loopback, bool replace, int cycle,
    [int? startPos]) {
  return _invokeMethod('startAudioMixing', {
    'filePath': filePath,
    'loopback': loopback,
    'replace': replace,
    'cycle': cycle,
    'startPos': startPos,
  });
}