[doc] daily update 2024-1-17

lib/src/agora_log.dart

@@ -106,7 +106,7 @@ class LogConfig {
   @JsonKey(name: 'filePath')
   final String? filePath;
 
-  /// The size (KB) of an agorasdk.log file. The value range is [128, 20480]. The default value is 1,024 KB. If you set fileSizeInKByte smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you set fileSizeInKByte greater than 20,480 KB, the SDK automatically adjusts it to 20,480 KB.
+  /// The size (KB) of an agorasdk.log file. The value range is [128,20480]. The default value is 2,048 KB. If you set fileSizeInKByte smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you set fileSizeInKByte greater than 20,480 KB, the SDK automatically adjusts it to 20,480 KB.
   @JsonKey(name: 'fileSizeInKB')
   final int? fileSizeInKB;
 

lib/src/agora_media_base.dart

@@ -126,7 +126,7 @@ enum AudioRoute {
   @JsonValue(4)
   routeLoudspeaker,
 
-  /// 5: The audio route is a bluetooth headset.
+  /// 5: The audio route is a Bluetooth device using the HFP protocol.
   @JsonValue(5)
   routeHeadsetbluetooth,
 
@@ -247,7 +247,7 @@ enum MediaSourceType {
   @JsonValue(2)
   primaryCameraSource,
 
-  /// 3: The secondary camera.
+  /// 3: A secondary camera.
   @JsonValue(3)
   secondaryCameraSource,
 
@@ -259,7 +259,7 @@ enum MediaSourceType {
   @JsonValue(5)
   secondaryScreenSource,
 
-  /// @nodoc
+  /// 6. Custom video source.
   @JsonValue(6)
   customVideoSource,
 
@@ -967,15 +967,17 @@ extension MediaPlayerSourceTypeExt on MediaPlayerSourceType {
 /// The frame position of the video observer.
 @JsonEnum(alwaysCreate: true)
 enum VideoModulePosition {
-  /// 1: The post-capturer position, which corresponds to the video data in the onCaptureVideoFrame callback.
+  /// 1: The location of the locally collected video data after preprocessing corresponds to the onCaptureVideoFrame callback. The observed video here has the effect of video pre-processing, which can be verified by enabling image enhancement, virtual background, or watermark.
   @JsonValue(1 << 0)
   positionPostCapturer,
 
   /// 2: The pre-renderer position, which corresponds to the video data in the onRenderVideoFrame callback.
   @JsonValue(1 << 1)
   positionPreRenderer,
 
-  /// 4: The pre-encoder position, which corresponds to the video data in the onPreEncodeVideoFrame callback.
+  /// 4: The pre-encoder position, which corresponds to the video data in the onPreEncodeVideoFrame callback. The observed video here has the effects of video pre-processing and encoding pre-processing.
+  ///  To verify the pre-processing effects of the video, you can enable image enhancement, virtual background, or watermark.
+  ///  To verify the pre-encoding processing effect, you can set a lower frame rate (for example, 5 fps).
   @JsonValue(1 << 2)
   positionPreEncoder,
 }
@@ -1519,7 +1521,7 @@ extension MediaRecorderStreamTypeExt on MediaRecorderStreamType {
 /// The current recording state.
 @JsonEnum(alwaysCreate: true)
 enum RecorderState {
-  /// -1: An error occurs during the recording. See RecorderErrorCode for the reason.
+  /// -1: An error occurs during the recording. See RecorderReasonCode for the reason.
   @JsonValue(-1)
   recorderStateError,
 
@@ -1545,26 +1547,26 @@ extension RecorderStateExt on RecorderState {
   }
 }
 
-/// The reason for the state change.
+/// @nodoc
 @JsonEnum(alwaysCreate: true)
 enum RecorderErrorCode {
-  /// 0: No error.
+  /// @nodoc
   @JsonValue(0)
   recorderErrorNone,
 
-  /// 1: The SDK fails to write the recorded data to a file.
+  /// @nodoc
   @JsonValue(1)
   recorderErrorWriteFailed,
 
-  /// 2: The SDK does not detect any audio and video streams, or audio and video streams are interrupted for more than five seconds during recording.
+  /// @nodoc
   @JsonValue(2)
   recorderErrorNoStream,
 
-  /// 3: The recording duration exceeds the upper limit.
+  /// @nodoc
   @JsonValue(3)
   recorderErrorOverMaxDuration,
 
-  /// 4: The recording configuration changes.
+  /// @nodoc
   @JsonValue(4)
   recorderErrorConfigChanged,
 }

lib/src/agora_media_engine.dart

@@ -150,10 +150,10 @@ abstract class MediaEngine {
 
   /// Creates a custom audio track.
   ///
-  /// To publish a custom audio source to multiple channels, see the following steps:
+  /// Ensure that you call this method before joining a channel. To publish a custom audio source, see the following steps:
   ///  Call this method to create a custom audio track and get the audio track ID.
-  ///  In ChannelMediaOptions of each channel, set publishCustomAduioTrackId to the audio track ID that you want to publish, and set publishCustomAudioTrack to true.
-  ///  If you call pushAudioFrame, and specify trackId as the audio track ID set in step 2, you can publish the corresponding custom audio source in multiple channels.
+  ///  Call joinChannel to join the channel. In ChannelMediaOptions, set publishCustomAduioTrackId to the audio track ID that you want to publish, and set publishCustomAudioTrack to true.
+  ///  Call pushAudioFrame and specify trackId as the audio track ID set in step 2. You can then publish the corresponding custom audio source in the channel.
   ///
   /// * [trackType] The type of the custom audio track. See AudioTrackType. If audioTrackDirect is specified for this parameter, you must set publishMicrophoneTrack to false in ChannelMediaOptions when calling joinChannel to join the channel; otherwise, joining the channel fails and returns the error code -2.
   /// * [config] The configuration of the custom audio track. See AudioTrackConfig.
@@ -170,7 +170,6 @@ abstract class MediaEngine {
   ///
   /// Returns
   /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly.
-  ///  < 0: Failure.
   Future<void> destroyCustomAudioTrack(int trackId);
 
   /// Sets the external audio sink.
@@ -185,17 +184,21 @@ abstract class MediaEngine {
   ///
   /// Returns
   /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly.
-  ///  < 0: Failure.
   Future<void> setExternalAudioSink(
       {required bool enabled, required int sampleRate, required int channels});
 
   /// @nodoc
   Future<void> enableCustomAudioLocalPlayback(
       {required int trackId, required bool enabled});
 
-  /// Pushes the external raw video frame to the SDK.
+  /// Pushes the external raw video frame to the SDK through video tracks.
   ///
-  /// If you call createCustomVideoTrack method to get the video track ID, set the customVideoTrackId parameter to the video track ID you want to publish in the ChannelMediaOptions of each channel, and set the publishCustomVideoTrack parameter to true, you can call this method to push the unencoded external video frame to the SDK.
+  /// To publish a custom video source, see the following steps:
+  ///  Call createCustomVideoTrack to create a video track and get the video track ID.
+  ///  Call joinChannel to join the channel. In ChannelMediaOptions, set customVideoTrackId to the video track ID that you want to publish, and set publishCustomVideoTrack to true.
+  ///  Call this method and specify videoTrackId as the video track ID set in step 2. You can then publish the corresponding custom video source in the channel. After calling this method, even if you stop pushing external video frames to the SDK, the custom video stream will still be counted as the video duration usage and incur charges. Agora recommends that you take appropriate measures based on the actual situation to avoid such video billing.
+  ///  If you no longer need to capture external video data, you can call destroyCustomVideoTrack to destroy the custom video track.
+  ///  If you only want to use the external video data for local preview and not publish it in the channel, you can call muteLocalVideoStream to cancel sending video stream or call updateChannelMediaOptions to set publishCustomVideoTrack to false.
   ///
   /// * [frame] The external raw video frame to be pushed. See ExternalVideoFrame.
   /// * [videoTrackId] The video track ID returned by calling the createCustomVideoTrack method. The default value is 0.
@@ -221,7 +224,6 @@ abstract class MediaEngine {
   ///
   /// Returns
   /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly.
-  ///  < 0: Failure.
   void unregisterAudioFrameObserver(AudioFrameObserver observer);
 
   /// Unregisters the video frame observer.