[doc] daily update 2024-12-2

lib/src/agora_base.dart

@@ -692,7 +692,7 @@ enum QualityType {
   @JsonValue(7)
   qualityUnsupported,
 
-  /// 8: Detecting the network quality.
+  /// 8: The last-mile network probe test is in progress.
   @JsonValue(8)
   qualityDetecting,
 }
@@ -930,7 +930,7 @@ extension OrientationModeExt on OrientationMode {
 /// Video degradation preferences when the bandwidth is a constraint.
 @JsonEnum(alwaysCreate: true)
 enum DegradationPreference {
-  /// 0: (Default) Prefers to reduce the video frame rate while maintaining video resolution during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where video quality is prioritized.
+  /// 0: Prefers to reduce the video frame rate while maintaining video resolution during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where video quality is prioritized. Deprecated: This enumerator is deprecated. Use other enumerations instead.
   @JsonValue(0)
   maintainQuality,
 
@@ -1623,7 +1623,7 @@ enum CompressionPreference {
   @JsonValue(0)
   preferLowLatency,
 
-  /// 1: (Default) High quality preference. The SDK compresses video frames while maintaining video quality. This preference is suitable for scenarios where video quality is prioritized.
+  /// 1: High quality preference. The SDK compresses video frames while maintaining video quality. This preference is suitable for scenarios where video quality is prioritized.
   @JsonValue(1)
   preferQuality,
 }
@@ -2933,7 +2933,7 @@ enum LocalVideoStreamReason {
   @JsonValue(8)
   localVideoStreamReasonDeviceNotFound,
 
-  /// 9: (macOS only) The video capture device currently in use is disconnected (such as being unplugged).
+  /// 9: (macOS and Windows only) The video capture device currently in use is disconnected (such as being unplugged).
   @JsonValue(9)
   localVideoStreamReasonDeviceDisconnected,
 
@@ -2974,7 +2974,7 @@ enum LocalVideoStreamReason {
   @JsonValue(20)
   localVideoStreamReasonScreenCaptureWindowNotSupported,
 
-  /// 21: (Windows only) The screen has not captured any data available for window sharing.
+  /// 21: (Windows and Android only) The currently captured window has no data.
   @JsonValue(21)
   localVideoStreamReasonScreenCaptureFailure,
 
@@ -4934,18 +4934,18 @@ extension VideoDenoiserModeExt on VideoDenoiserMode {
   }
 }
 
-/// The video noise reduction level.
+/// Video noise reduction level.
 @JsonEnum(alwaysCreate: true)
 enum VideoDenoiserLevel {
   /// 0: (Default) Promotes video quality during video noise reduction. balances performance consumption and video noise reduction quality. The performance consumption is moderate, the video noise reduction speed is moderate, and the overall video quality is optimal.
   @JsonValue(0)
   videoDenoiserLevelHighQuality,
 
-  /// 1: Promotes reducing performance consumption during video noise reduction. prioritizes reducing performance consumption over video noise reduction quality. The performance consumption is lower, and the video noise reduction speed is faster. To avoid a noticeable shadowing effect (shadows trailing behind moving objects) in the processed video, Agora recommends that you use this settinging when the camera is fixed.
+  /// 1: Promotes reducing performance consumption during video noise reduction. It prioritizes reducing performance consumption over video noise reduction quality. The performance consumption is lower, and the video noise reduction speed is faster. To avoid a noticeable shadowing effect (shadows trailing behind moving objects) in the processed video, Agora recommends that you use this setting when the camera is fixed.
   @JsonValue(1)
   videoDenoiserLevelFast,
 
-  /// 2: Enhanced video noise reduction. prioritizes video noise reduction quality over reducing performance consumption. The performance consumption is higher, the video noise reduction speed is slower, and the video noise reduction quality is better. If videoDenoiserLevelHighQuality is not enough for your video noise reduction needs, you can use this enumerator.
+  /// @nodoc
   @JsonValue(2)
   videoDenoiserLevelStrength,
 }
@@ -5988,7 +5988,7 @@ class ChannelMediaRelayConfiguration {
 
   /// The information of the target channel ChannelMediaInfo. It contains the following members: channelName : The name of the target channel. token : The token for joining the target channel. It is generated with the channelName and uid you set in destInfos.
   ///  If you have not enabled the App Certificate, set this parameter as the default value NULL, which means the SDK applies the App ID.
-  ///  If you have enabled the App Certificate, you must use the token generated with the channelName and uid. If the token of any target channel expires, the whole media relay stops; hence Agora recommends that you specify the same expiration time for the tokens of all the target channels. uid : The unique user ID to identify the relay stream in the target channel. The value ranges from 0 to (2 32 -1). To avoid user ID conflicts, this user ID must be different from any other user ID in the target channel. The default value is 0, which means the SDK generates a random user ID.
+  ///  If you have enabled the App Certificate, you must use the token generated with the channelName and uid. If the token of any target channel expires, the whole media relay stops; hence Agora recommends that you specify the same expiration time for the tokens of all the target channels. uid : The unique user ID to identify the relay stream in the target channel. The value ranges from 0 to (2 32 -1). To avoid user ID conflicts, this user ID must be different from any other user ID in the target channel. The default value is 0, which means the SDK generates a random UID.
   @JsonKey(name: 'destInfos')
   final List<ChannelMediaInfo>? destInfos;
 

lib/src/agora_media_base.dart

@@ -632,11 +632,11 @@ extension VideoPixelFormatExt on VideoPixelFormat {
 /// Video display modes.
 @JsonEnum(alwaysCreate: true)
 enum RenderModeType {
-  /// 1: Hidden mode. Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). One dimension of the video may have clipped contents.
+  /// 1: Hidden mode. The priority is to fill the window. Any excess video that does not match the window size will be cropped.
   @JsonValue(1)
   renderModeHidden,
 
-  /// 2: Fit mode. Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to disparity in the aspect ratio are filled with black.
+  /// 2: Fit mode. The priority is to ensure that all video content is displayed. Any areas of the window that are not filled due to the mismatch between video size and window size will be filled with black.
   @JsonValue(2)
   renderModeFit,
 
@@ -970,15 +970,17 @@ class VideoFrame {
   @JsonKey(name: 'matrix')
   final List<double>? matrix;
 
-  /// The alpha channel data output by using portrait segmentation algorithm. This data matches the size of the video frame, with each pixel value ranging from [0,255], where 0 represents the background and 255 represents the foreground (portrait). By setting this parameter, you can render the video background into various effects, such as transparent, solid color, image, video, etc. In custom video rendering scenarios, ensure that both the video frame and alphaBuffer are of the Full Range type; other types may cause abnormal alpha data rendering.
+  /// The alpha channel data output by using portrait segmentation algorithm. This data matches the size of the video frame, with each pixel value ranging from [0,255], where 0 represents the background and 255 represents the foreground (portrait). By setting this parameter, you can render the video background into various effects, such as transparent, solid color, image, video, etc.
+  ///  In custom video rendering scenarios, ensure that both the video frame and alphaBuffer are of the Full Range type; other types may cause abnormal alpha data rendering.
+  ///  Make sure that alphaBuffer is exactly the same size as the video frame (width × height), otherwise it may cause the app to crash.
   @JsonKey(name: 'alphaBuffer', ignore: true)
   final Uint8List? alphaBuffer;
 
   /// @nodoc
   @JsonKey(name: 'pixelBuffer', ignore: true)
   final Uint8List? pixelBuffer;
 
-  /// The meta information in the video frame. To use this parameter, please contact.
+  /// The meta information in the video frame. To use this parameter, contact.
   @VideoFrameMetaInfoConverter()
   @JsonKey(name: 'metaInfo')
   final VideoFrameMetaInfo? metaInfo;
@@ -1393,7 +1395,7 @@ class AudioSpectrumObserver {
   ///
   /// After successfully calling registerAudioSpectrumObserver to implement the onRemoteAudioSpectrum callback in the AudioSpectrumObserver and calling enableAudioSpectrumMonitor to enable audio spectrum monitoring, the SDK will trigger the callback as the time interval you set to report the received remote audio data spectrum.
   ///
-  /// * [spectrums] The audio spectrum information of the remote user, see UserAudioSpectrumInfo. The number of arrays is the number of remote users monitored by the SDK. If the array is null, it means that no audio spectrum of remote users is detected.
+  /// * [spectrums] The audio spectrum information of the remote user. See UserAudioSpectrumInfo. The number of arrays is the number of remote users monitored by the SDK. If the array is null, it means that no audio spectrum of remote users is detected.
   /// * [spectrumNumber] The number of remote users.
   final void Function(
           List<UserAudioSpectrumInfo> spectrums, int spectrumNumber)?

lib/src/agora_media_engine.dart

@@ -48,13 +48,7 @@ abstract class MediaEngine {
 
   /// Registers a raw video frame observer object.
   ///
-  /// If you want to obtain the original video data of some remote users (referred to as group A) and the encoded video data of other remote users (referred to as group B), you can refer to the following steps:
-  ///  Call registerVideoFrameObserver to register the raw video frame observer before joining the channel.
-  ///  Call registerVideoEncodedFrameObserver to register the encoded video frame observer before joining the channel.
-  ///  After joining the channel, get the user IDs of group B users through onUserJoined, and then call setRemoteVideoSubscriptionOptions to set the encodedFrameOnly of this group of users to true.
-  ///  Call muteAllRemoteVideoStreams (false) to start receiving the video streams of all remote users. Then:
-  ///  The raw video data of group A users can be obtained through the callback in VideoFrameObserver, and the SDK renders the data by default.
-  ///  The encoded video data of group B users can be obtained through the callback in VideoEncodedFrameObserver. If you want to observe raw video frames (such as YUV or RGBA format), Agora recommends that you implement one VideoFrameObserver class with this method. When calling this method to register a video observer, you can register callbacks in the VideoFrameObserver class as needed. After you successfully register the video frame observer, the SDK triggers the registered callbacks each time a video frame is received.
+  /// If you want to observe raw video frames (such as YUV or RGBA format), Agora recommends that you implement one VideoFrameObserver class with this method. When calling this method to register a video observer, you can register callbacks in the VideoFrameObserver class as needed. After you successfully register the video frame observer, the SDK triggers the registered callbacks each time a video frame is received.
   ///
   /// * [observer] The observer instance. See VideoFrameObserver.
   ///
@@ -65,14 +59,7 @@ abstract class MediaEngine {
 
   /// Registers a receiver object for the encoded video image.
   ///
-  /// If you only want to observe encoded video frames (such as h.264 format) without decoding and rendering the video, Agora recommends that you implement one VideoEncodedFrameObserver class through this method. If you want to obtain the original video data of some remote users (referred to as group A) and the encoded video data of other remote users (referred to as group B), you can refer to the following steps:
-  ///  Call registerVideoFrameObserver to register the raw video frame observer before joining the channel.
-  ///  Call registerVideoEncodedFrameObserver to register the encoded video frame observer before joining the channel.
-  ///  After joining the channel, get the user IDs of group B users through onUserJoined, and then call setRemoteVideoSubscriptionOptions to set the encodedFrameOnly of this group of users to true.
-  ///  Call muteAllRemoteVideoStreams (false) to start receiving the video streams of all remote users. Then:
-  ///  The raw video data of group A users can be obtained through the callback in VideoFrameObserver, and the SDK renders the data by default.
-  ///  The encoded video data of group B users can be obtained through the callback in VideoEncodedFrameObserver.
-  ///  Call this method before joining a channel.
+  /// If you only want to observe encoded video frames (such as H.264 format) without decoding and rendering the video, Agora recommends that you implement one VideoEncodedFrameObserver class through this method. Call this method before joining a channel.
   ///
   /// * [observer] The video frame observer object. See VideoEncodedFrameObserver.
   ///

lib/src/agora_media_player.dart

@@ -105,8 +105,7 @@ abstract class MediaPlayer {
   /// * [index] The index of the media stream. This parameter must be less than the return value of getStreamCount.
   ///
   /// Returns
-  /// If the call succeeds, returns the detailed information of the media stream. See PlayerStreamInfo.
-  ///  If the call fails, returns NULL.
+  /// If the call succeeds, returns the detailed information of the media stream. See PlayerStreamInfo. NULL, if the method call fails.
   Future<PlayerStreamInfo> getStreamInfo(int index);
 
   /// Sets the loop playback.
@@ -125,8 +124,8 @@ abstract class MediaPlayer {
   ///
   /// Call this method after calling open.
   ///
-  /// * [speed] The playback speed. Agora recommends that you limit this value to a range between 50 and 400, which is defined as follows:
-  ///  50: Half the original speed.
+  /// * [speed] The playback speed. Agora recommends that you set this to a value between 30 and 400, defined as follows:
+  ///  30: 0.3 times the original speed.
   ///  100: The original speed.
   ///  400: 4 times the original speed.
   ///
@@ -351,23 +350,25 @@ abstract class MediaPlayer {
   ///
   /// You can call this method to switch the media resource to be played according to the current network status. For example:
   ///  When the network is poor, the media resource to be played is switched to a media resource address with a lower bitrate.
-  ///  When the network is good, the media resource to be played is switched to a media resource address with a higher bitrate. After calling this method, if you receive the playerEventSwitchComplete event in the onPlayerEvent callback, the switch is successful; If you receive the playerEventSwitchError event in the onPlayerEvent callback, the switch fails.
+  ///  When the network is good, the media resource to be played is switched to a media resource address with a higher bitrate. After calling this method, if you receive the onPlayerEvent callback report the playerEventSwitchComplete event, the switching is successful. If the switching fails, the SDK will automatically retry 3 times. If it still fails, you will receive the onPlayerEvent callback reporting the playerEventSwitchError event indicating an error occurred during media resource switching.
   ///  Ensure that you call this method after open.
   ///  To ensure normal playback, pay attention to the following when calling this method:
   ///  Do not call this method when playback is paused.
   ///  Do not call the seek method during switching.
   ///  Before switching the media resource, make sure that the playback position does not exceed the total duration of the media resource to be switched.
   ///
   /// * [src] The URL of the media resource.
-  /// * [syncPts] Whether to synchronize the playback position (ms) before and after the switch: true : Synchronize the playback position before and after the switch. false : (Default) Do not synchronize the playback position before and after the switch. Make sure to set this parameter as false if you need to play live streams, or the switch fails. If you need to play on-demand streams, you can set the value of this parameter according to your scenarios.
+  /// * [syncPts] Whether to synchronize the playback position (ms) before and after the switch: true : Synchronize the playback position before and after the switch. false : (Default) Do not synchronize the playback position before and after the switch.
   ///
   /// 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.
   Future<void> switchSrc({required String src, bool syncPts = true});
 
   /// Preloads a media resource.
   ///
-  /// You can call this method to preload a media resource into the playlist. If you need to preload multiple media resources, you can call this method multiple times. If the preload is successful and you want to play the media resource, call playPreloadedSrc; if you want to clear the playlist, call stop. Agora does not support preloading duplicate media resources to the playlist. However, you can preload the media resources that are being played to the playlist again.
+  /// You can call this method to preload a media resource into the playlist. If you need to preload multiple media resources, you can call this method multiple times. If the preload is successful and you want to play the media resource, call playPreloadedSrc; if you want to clear the playlist, call stop.
+  ///  Before calling this method, ensure that you have called open or openWithMediaSource to open the media resource successfully.
+  ///  Agora does not support preloading duplicate media resources to the playlist. However, you can preload the media resources that are being played to the playlist again.
   ///
   /// * [src] The URL of the media resource.
   /// * [startPos] The starting position (ms) for playing after the media resource is preloaded to the playlist. When preloading a live stream, set this parameter to 0.

lib/src/agora_media_player_source.dart

@@ -40,7 +40,7 @@ class MediaPlayerSourceObserver {
   ///
   /// After calling the seek method, the SDK triggers the callback to report the results of the seek operation.
   ///
-  /// * [eventCode] The player events. See MediaPlayerEvent.
+  /// * [eventCode] The player event. See MediaPlayerEvent.
   /// * [elapsedTime] The time (ms) when the event occurs.
   /// * [message] Information about the event.
   final void Function(
@@ -58,8 +58,8 @@ class MediaPlayerSourceObserver {
   /// Reports the playback duration that the buffered data can support.
   ///
   /// When playing online media resources, the SDK triggers this callback every two seconds to report the playback duration that the currently buffered data can support.
-  ///  When the playback duration supported by the buffered data is less than the threshold (0 by default), the SDK returns playerEventBufferLow.
-  ///  When the playback duration supported by the buffered data is greater than the threshold (0 by default), the SDK returns playerEventBufferRecover.
+  ///  When the playback duration supported by the buffered data is less than the threshold (0 by default), the SDK returns playerEventBufferLow (6).
+  ///  When the playback duration supported by the buffered data is greater than the threshold (0 by default), the SDK returns playerEventBufferRecover (7).
   ///
   /// * [playCachedBuffer] The playback duration (ms) that the buffered data can support.
   final void Function(int playCachedBuffer)? onPlayBufferUpdated;