Merge branch 'rc/4.0.+' into dev/flutter2

android/src/main/kotlin/io/agora/agora_rtc_engine/AgoraRtcEnginePlugin.kt

@@ -51,15 +51,25 @@ class AgoraRtcEnginePlugin : FlutterPlugin, MethodCallHandler, EventChannel.Stre
     }
   }
 
-  private fun initPlugin(context: Context, binaryMessenger: BinaryMessenger, platformViewRegistry: PlatformViewRegistry) {
+  private fun initPlugin(
+    context: Context,
+    binaryMessenger: BinaryMessenger,
+    platformViewRegistry: PlatformViewRegistry
+  ) {
     applicationContext = context.applicationContext
     methodChannel = MethodChannel(binaryMessenger, "agora_rtc_engine")
     methodChannel.setMethodCallHandler(this)
     eventChannel = EventChannel(binaryMessenger, "agora_rtc_engine/events")
     eventChannel.setStreamHandler(this)
 
-    platformViewRegistry.registerViewFactory("AgoraSurfaceView", AgoraSurfaceViewFactory(binaryMessenger, this, rtcChannelPlugin))
-    platformViewRegistry.registerViewFactory("AgoraTextureView", AgoraTextureViewFactory(binaryMessenger, this, rtcChannelPlugin))
+    platformViewRegistry.registerViewFactory(
+      "AgoraSurfaceView",
+      AgoraSurfaceViewFactory(binaryMessenger, this, rtcChannelPlugin)
+    )
+    platformViewRegistry.registerViewFactory(
+      "AgoraTextureView",
+      AgoraTextureViewFactory(binaryMessenger, this, rtcChannelPlugin)
+    )
   }
 
   override fun onAttachedToEngine(@NonNull binding: FlutterPlugin.FlutterPluginBinding) {

android/src/main/kotlin/io/agora/agora_rtc_engine/AgoraSurfaceViewFactory.kt

@@ -18,7 +18,14 @@ class AgoraSurfaceViewFactory(
   private val rtcChannelPlugin: AgoraRtcChannelPlugin
 ) : PlatformViewFactory(StandardMessageCodec.INSTANCE) {
   override fun create(context: Context, viewId: Int, args: Any?): PlatformView {
-    return AgoraSurfaceView(context.applicationContext, messenger, viewId, args as? Map<*, *>, rtcEnginePlugin, rtcChannelPlugin)
+    return AgoraSurfaceView(
+      context.applicationContext,
+      messenger,
+      viewId,
+      args as? Map<*, *>,
+      rtcEnginePlugin,
+      rtcChannelPlugin
+    )
   }
 }
 
@@ -56,17 +63,18 @@ class AgoraSurfaceView(
     this.javaClass.declaredMethods.find { it.name == call.method }?.let { function ->
       function.let { method ->
         val parameters = mutableListOf<Any?>()
-        function.parameters.forEach { parameter ->
-          val map = call.arguments<Map<*, *>>()
-          if (map.containsKey(parameter.name)) {
-            parameters.add(map[parameter.name])
+        call.arguments<Map<*, *>>()?.let { args ->
+          args.values.forEach {
+            parameters.add(it)
           }
         }
         try {
           method.invoke(this, *parameters.toTypedArray())
+          result.success(null)
           return@onMethodCall
         } catch (e: Exception) {
           e.printStackTrace()
+          result.error(e.toString(), null, null)
         }
       }
     }

android/src/main/kotlin/io/agora/agora_rtc_engine/AgoraTextureViewFactory.kt

@@ -168,7 +168,14 @@ class AgoraTextureViewFactory(
   }
 
   override fun create(context: Context, viewId: Int, args: Any?): PlatformView {
-    return AgoraTextureView(context.applicationContext, messenger, viewId, args as? Map<*, *>, rtcEnginePlugin, rtcChannelPlugin)
+    return AgoraTextureView(
+      context.applicationContext,
+      messenger,
+      viewId,
+      args as? Map<*, *>,
+      rtcEnginePlugin,
+      rtcChannelPlugin
+    )
   }
 }
 
@@ -204,17 +211,18 @@ class AgoraTextureView(
     this.javaClass.declaredMethods.find { it.name == call.method }?.let { function ->
       function.let { method ->
         val parameters = mutableListOf<Any?>()
-        function.parameters.forEach { parameter ->
-          val map = call.arguments<Map<*, *>>()
-          if (map.containsKey(parameter.name)) {
-            parameters.add(map[parameter.name])
+        call.arguments<Map<*, *>>()?.let { args ->
+          args.values.forEach {
+            parameters.add(it)
           }
         }
         try {
           method.invoke(this, *parameters.toTypedArray())
+          result.success(null)
           return@onMethodCall
         } catch (e: Exception) {
           e.printStackTrace()
+          result.error(e.toString(), null, null)
         }
       }
     }

lib/src/classes.dart

@@ -1302,15 +1302,20 @@ class RtcEngineConfig {
   Map<String, dynamic> toJson() => _$RtcEngineConfigToJson(this);
 }
 
-/// TODO(doc)
+/// The metronome configuration, which is set in [RtcEngine.startRhythmPlayer] or [RtcEngine.configRhythmPlayer].
 @JsonSerializable(explicitToJson: true)
 class RhythmPlayerConfig {
+  /// The number of beats per measure. The range is 1 to 9. The default value is 4, which means that each measure contains one downbeat and three upbeats.
   @JsonKey(includeIfNull: false)
   int? beatsPerMeasure;
 
+  /// Tempo (beats per minute). The range is 60 to 360. The default value is 60, which means that the metronome plays 60 beats in one minute.
   @JsonKey(includeIfNull: false)
   int? beatsPerMinute;
 
+  /// Whether to publish the sound of the metronome to remote users:
+  /// - `true`: (Default) Publish. Both the local user and remote users can hear the metronome.
+  /// - `false`: Do not publish. Only the local user can hear the metronome.
   @JsonKey(includeIfNull: false)
   bool? publish;
 
@@ -1325,17 +1330,29 @@ class RhythmPlayerConfig {
   Map<String, dynamic> toJson() => _$RhythmPlayerConfigToJson(this);
 }
 
-/// TODO(doc)
+/// Recording configuration, which is set in [RtcEngine.setAudioRecording].
 @JsonSerializable(explicitToJson: true)
 class AudioRecordingConfiguration {
+  /// The absolute path (including the filename extensions) of the recording file. For example: `/sdcard/emulated/0/audio.mp4` on Android and `/var/mobile/Containers/Data/audio.mp4` on iOS. Ensure that the path you specify exists and is writable.
   String filePath;
 
+  /// Audio recording quality. For details, see [AudioRecordingQuality]. This parameter applies to AAC files only.
   @JsonKey(includeIfNull: false)
   AudioRecordingQuality? recordingQuality;
 
+  /// Recording content. For details, see [AudioRecordingPosition].
   @JsonKey(includeIfNull: false)
   AudioRecordingPosition? recordingPosition;
 
+  /// Recording sample rate (Hz). The following values are supported:
+  /// - 16000
+  /// - (Default) 32000
+  /// - 44100
+  /// - 48000
+  ///
+  /// **Note**
+  /// - If this parameter is set to 44100 or 48000, for better recording effects, Agora recommends recording WAV files or AAC files whose `recordingQuality`
+  /// is `Medium` or `High`.
   @JsonKey(includeIfNull: false)
   AudioSampleRateType? recordingSampleRate;
 

lib/src/enums.dart

@@ -131,45 +131,45 @@ enum AudioLocalState {
   Failed,
 }
 
-/// The error code of the audio mixing file.
+/// The reason for the change of the music file playback state, reported in the [RtcEngineEventHandler.audioMixingStateChanged].
 enum AudioMixingReason {
-  /// The SDK cannot open the audio mixing file.
+  /// The SDK cannot open the music file. Possible causes include the local music file does not exist, the SDK does not support the file format, or the SDK cannot access the music file URL.
   @JsonValue(701)
   CanNotOpen,
 
-  /// The SDK opens the audio mixing file too frequently.
+  /// The SDK opens the music file too frequently. If you need to call [RtcEngine.startAudioMixing] multiple times, ensure that the call interval is longer than 500 ms.
   @JsonValue(702)
   TooFrequentCall,
 
-  /// The opening of the audio mixing file is interrupted.
+  /// The music file playback is interrupted.
   @JsonValue(703)
   InterruptedEOF,
 
-  /// TODO(doc)
+  /// Successfully calls `startAudioMixing` to play a music file.
   @JsonValue(720)
   StartedByUser,
 
-  /// TODO(doc)
+  /// The music file completes a loop playback.
   @JsonValue(721)
   OneLoopCompleted,
 
-  /// TODO(doc)
+  /// The music file starts a new loop playback.
   @JsonValue(722)
   StartNewLoop,
 
-  /// TODO(doc)
+  /// The music file completes all loop playback.
   @JsonValue(723)
   AllLoopsCompleted,
 
-  /// TODO(doc)
+  /// Successfully calls `stopAudioMixing` to stop playing the music file.
   @JsonValue(724)
   StoppedByUser,
 
-  /// TODO(doc)
+  /// Successfully calls `pauseAudioMixing` to pause playing the music file.
   @JsonValue(725)
   PausedByUser,
 
-  /// TODO(doc)
+  /// Successfully calls `resumeAudioMixing` to resume playing the music file.
   @JsonValue(726)
   ResumedByUser,
 
@@ -180,23 +180,32 @@ enum AudioMixingReason {
 
 /// The state of the audio mixing file.
 enum AudioMixingStateCode {
-  /// The audio mixing file is playing.
+  /// The music file is playing. This state comes with one of the following associated reasons:
+  /// - `StartedByuser(720)`
+  /// - `LoopCompleted(721)`
+  /// - `NewLoop(722)`
+  /// - `ResumedByUser(726)`
   @JsonValue(710)
   Playing,
 
-  /// The audio mixing file pauses playing.
+  /// The music file pauses playing. This state comes with `PausedByUser(725)`
   @JsonValue(711)
   Paused,
 
-  /// TODO(doc)
+  /// Ignore this state.
   @JsonValue(712)
   Restart,
 
-  /// The audio mixing file stops playing.
+  /// The music file stops playing. This state comes with one of the following associated reasons:
+  /// - `AllLoopsCompleted(723)`
+  /// - `StoppedByUser(724)`
   @JsonValue(713)
   Stopped,
 
-  /// An exception occurs when playing the audio mixing file.
+  /// An exception occurs during the playback of the music file. This state comes with one of the following associated reasons:
+  /// - `CanNotOpen(701)`
+  /// - `TooFrequentCall(702)`
+  /// - `InterruptedEOF(703)`
   @JsonValue(714)
   Failed,
 }
@@ -261,32 +270,32 @@ enum AudioProfile {
   MusicHighQualityStereo,
 }
 
-/// Audio recording quality.
+/// Audio recording quality, which is set in [RtcEngine.startAudioRecording].
 enum AudioRecordingQuality {
-  /// Low quality. The sample rate is 32 KHz, and the file size is around 1.2 MB after 10 minutes of recording.
+  /// Low quality. For example, the size of an AAC file with a sample rate of 32,000 Hz and a 10-minute recording is approximately 1.2 MB.
   @JsonValue(0)
   Low,
 
-  /// Medium quality. The sample rate is 32 KHz, and the file size is around 2 MB after 10 minutes of recording.
+  /// (Default) Medium quality. For example, the size of an AAC file with a sample rate of 32,000 Hz and a 10-minute recording is approximately 2 MB.
   @JsonValue(1)
   Medium,
 
-  /// High quality. The sample rate is 32 KHz, and the file size is around 3.75 MB after 10 minutes of recording.
+  /// High quality. For example, the size of an AAC file with a sample rate of 32,000 Hz and a 10-minute recording is approximately 3.75 MB.
   @JsonValue(2)
   High,
 }
 
-/// TODO(doc)
+/// Recording content, which is set in [RtcEngine.startAduioRecording].
 enum AudioRecordingPosition {
-  /// Low quality. The sample rate is 32 KHz, and the file size is around 1.2 MB after 10 minutes of recording.
+  /// 0: (Default) Records the mixed audio of the local user and all remote users.
   @JsonValue(0)
   PositionMixedRecordingAndPlayback,
 
-  /// Medium quality. The sample rate is 32 KHz, and the file size is around 2 MB after 10 minutes of recording.
+  /// 1: Records the audio of the local user only.
   @JsonValue(1)
   PositionRecording,
 
-  /// High quality. The sample rate is 32 KHz, and the file size is around 3.75 MB after 10 minutes of recording.
+  /// 2: Records the audio of all remote users only.
   @JsonValue(2)
   PositionMixedPlayback,
 }
@@ -872,15 +881,21 @@ enum ConnectionStateType {
 
 /// The video encoding degradation preference under limited bandwidth.
 enum DegradationPreference {
-  /// (Default) Degrades the frame rate to guarantee the video quality.
+  /// (Default) Prefers to reduce the video frame rate while maintaining video quality during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where video quality is prioritized.
+  ///
+  /// **Note**
+  /// - In the `COMMUNICATION` channel profile, the resolution of the video sent may change, so remote users need to handle this issue. See [RtcEngineEventHandler.videoSizeChanged].
   @JsonValue(0)
   MaintainQuality,
 
-  /// Degrades the video quality to guarantee the frame rate.
+  /// Prefers to reduce the video quality while maintaining the video frame rate during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where smoothness is prioritized and video quality is allowed to be reduced.
   @JsonValue(1)
   MaintainFramerate,
 
-  /// Reserved for future use.
+  /// Reduces the video frame rate and video quality simultaneously during video encoding under limited bandwidth. `Balenced` has a lower reduction than `MaintainQuality` and `MaintainFramerate`, and this preference is suitable for scenarios where both smoothness and video quality are a priority.
+  ///
+  /// **Note**
+  /// - the resolution of the video sent may change, so remote users need to handle this issue. See [RtcEngineEventHandler.videoSizeChanged].
   @JsonValue(2)
   MaintainBalanced
 }
@@ -1137,7 +1152,7 @@ enum ErrorCode {
   @JsonValue(157)
   ModuleNotFound,
 
-  /// TODO(doc)
+  /// The client is already recording audio. To start a new recording, call [RtcEngine.stopAudioRecording] to stop the current recording first, and then call [RtcEngine.startAudioRecording].
   @JsonValue(160)
   AlreadyInRecording,
 
@@ -1371,7 +1386,7 @@ enum LocalVideoStreamError {
   @JsonValue(7)
   CaptureMultipleForegroundApps,
 
-  /// TODO(doc)
+  /// The SDK cannot find the local video capture device.
   @JsonValue(8)
   DeviceNotFound,
 }

lib/src/events.dart

@@ -584,16 +584,14 @@ class RtcEngineEventHandler {
   @deprecated
   EmptyCallback? audioMixingFinished;
 
-  /// Occurs when the state of the local user's audio mixing file changes.
+  /// Occurs when the playback state of the local user's music file changes.
   ///
   /// When you call the [RtcEngine.startAudioMixing] method and the state of audio mixing file changes, the Agora SDK triggers this callback.
-  /// - When the audio mixing file plays, pauses playing, or stops playing, this callback returns 710, 711, or 713 in state, and 0 in the `errorCode` parameter.
-  /// - When exceptions occur during playback, this callback returns 714 in state and an error in the `errorCode` parameter.
-  /// - 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 [WarningCode.AudioMixingOpenError] = 701.
+  /// When the playback state of the local user's music file changes, the SDK triggers this callback and reports the current playback state and the reason for the change.
   ///
   /// The `AudioMixingStateCallback` typedef includes the following parameters:
-  /// - [AudioMixingStateCode] `state`: The state code.
-  /// - [AudioMixingReason] `reason`: The reason.
+  /// - [AudioMixingStateCode] `state`: The current music file playback state.
+  /// - [AudioMixingReason] `reason`: The reason for the change of the music file playback state.
   AudioMixingStateCallback? audioMixingStateChanged;
 
   /// Occurs when the audio effect file playback finishes.