diff --git a/lib/src/agora_base.dart b/lib/src/agora_base.dart index c1b913aad..4285145b9 100644 --- a/lib/src/agora_base.dart +++ b/lib/src/agora_base.dart @@ -1973,7 +1973,7 @@ class WatermarkOptions { this.watermarkRatio, this.mode}); - /// Is the watermark visible in the local preview view? true : (Default) The watermark is visible in the local preview view. false : The watermark is not visible in the local preview view. + /// Whether the watermark is visible in the local preview view: true : (Default) The watermark is visible in the local preview view. false : The watermark is not visible in the local preview view. @JsonKey(name: 'visibleInPreview') final bool? visibleInPreview; @@ -3578,7 +3578,7 @@ enum RtmpStreamPublishReason { @JsonValue(15) rtmpStreamPublishReasonInvalidAppid, - /// 16: Your project does not have permission to use streaming services. Refer to Media Push to enable the Media Push permission. + /// 16: Your project does not have permission to use streaming services. @JsonValue(16) rtmpStreamPublishReasonInvalidPrivilege, @@ -5721,7 +5721,7 @@ enum ChannelMediaRelayError { @JsonValue(1) relayErrorServerErrorResponse, - /// 2: No server response. You can call leaveChannel to leave the channel. This error can also occur if your project has not enabled co-host token authentication. You can to enable the service for cohosting across channels before starting a channel media relay. + /// 2: No server response. This error may be caused by poor network connections. If this error occurs when initiating a channel media relay, you can try again later; if this error occurs during channel media relay, you can call leaveChannel to leave the channel. This error can also occur if the channel media relay service is not enabled in the project. You can contact to enable the service. @JsonValue(2) relayErrorServerNoResponse, diff --git a/lib/src/agora_media_engine.dart b/lib/src/agora_media_engine.dart index 48ad9b6c6..ca05859c8 100644 --- a/lib/src/agora_media_engine.dart +++ b/lib/src/agora_media_engine.dart @@ -96,13 +96,12 @@ abstract class MediaEngine { /// Pulls the remote audio data. /// - /// Before calling this method, you need to call setExternalAudioSink to notify the app to enable and set the external rendering. After a successful call of this method, the app pulls the decoded and mixed audio data for playback. - /// This method only supports pulling data from custom audio source. If you need to pull the data captured by the SDK, do not call this method. + /// Before calling this method, call setExternalAudioSink (enabled : true) to notify the app to enable and set the external audio rendering. After a successful call of this method, the app pulls the decoded and mixed audio data for playback. /// Call this method after joining a channel. - /// Once you enable the external audio sink, the app will not retrieve any audio data from the onPlaybackAudioFrame callback. - /// The difference between this method and the onPlaybackAudioFrame callback is as follows: + /// Both this method and onPlaybackAudioFrame callback can be used to get audio data after remote mixing. Note that after calling setExternalAudioSink to enable external audio rendering, the app no longer receives data from the onPlaybackAudioFrame callback. Therefore, you should choose between this method and the onPlaybackAudioFrame callback based on your actual business requirements. The specific distinctions between them are as follows: + /// After calling this method, the app automatically pulls the audio data from the SDK. By setting the audio data parameters, the SDK adjusts the frame buffer to help the app handle latency, effectively avoiding audio playback jitter. /// The SDK sends the audio data to the app through the onPlaybackAudioFrame callback. Any delay in processing the audio frames may result in audio jitter. - /// After a successful method call, the app automatically pulls the audio data from the SDK. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback. + /// This method is only used for retrieving audio data after remote mixing. If you need to get audio data from different audio processing stages such as capture and playback, you can register the corresponding callbacks by calling registerAudioFrameObserver. /// /// * [frame] Pointers to AudioFrame. /// diff --git a/lib/src/agora_media_player.dart b/lib/src/agora_media_player.dart index 05e4a3673..4324f2e29 100644 --- a/lib/src/agora_media_player.dart +++ b/lib/src/agora_media_player.dart @@ -145,7 +145,16 @@ abstract class MediaPlayer { /// 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. Future selectAudioTrack(int index); - /// @nodoc + /// Selects the audio tracks that you want to play on your local device and publish to the channel respectively. + /// + /// You can call this method to determine the audio track to be played on your local device and published to the channel. Before calling this method, you need to open the media file with the openWithMediaSource method and set enableMultiAudioTrack in MediaSource as true. + /// + /// * [playoutTrackIndex] The index of audio tracks for local playback. You can obtain the index through getStreamInfo. + /// * [publishTrackIndex] The index of audio tracks to be published in the channel. You can obtain the index through getStreamInfo. + /// + /// 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 selectMultiAudioTrack( {required int playoutTrackIndex, required int publishTrackIndex}); diff --git a/lib/src/agora_rtc_engine.dart b/lib/src/agora_rtc_engine.dart index 8e87b2432..f356b0456 100644 --- a/lib/src/agora_rtc_engine.dart +++ b/lib/src/agora_rtc_engine.dart @@ -1448,7 +1448,7 @@ class ChannelMediaOptions { final bool? publishRhythmPlayerTrack; /// Whether to enable interactive mode: true : Enable interactive mode. Once this mode is enabled and the user role is set as audience, the user can receive remote video streams with low latency. false :Do not enable interactive mode. If this mode is disabled, the user receives the remote video streams in default settings. - /// This parameter only applies to scenarios involving cohosting across channels. The cohosts need to call the joinChannelEx method to join the other host's channel as an audience member, and set isInteractiveAudience to true. + /// This parameter only applies to co-streaming scenarios. The cohosts need to call the joinChannelEx method to join the other host's channel as an audience member, and set isInteractiveAudience to true. /// This parameter takes effect only when the user role is clientRoleAudience. @JsonKey(name: 'isInteractiveAudience') final bool? isInteractiveAudience; @@ -2548,7 +2548,7 @@ class RtcEngineEventHandler { /// Occurs when the extension is enabled. /// - /// After a successful call of enableExtension (true), the extension triggers this callback. + /// The extension triggers this callback after it is successfully enabled. /// /// * [provider] The name of the extension provider. /// * [extName] The name of the extension. @@ -2556,7 +2556,7 @@ class RtcEngineEventHandler { /// Occurs when the extension is disabled. /// - /// After a successful call of enableExtension (false), this callback is triggered. + /// The extension triggers this callback after it is successfully destroyed. /// /// * [extName] The name of the extension. /// * [provider] The name of the extension provider. @@ -2564,7 +2564,7 @@ class RtcEngineEventHandler { /// Occurs when the extension runs incorrectly. /// - /// When calling enableExtension (true) fails or the extension runs in error, the extension triggers this callback and reports the error code and reason. + /// In case of extension enabling failure or runtime errors, the extension triggers this callback and reports the error code along with the reasons. /// /// * [provider] The name of the extension provider. /// * [extension] The name of the extension. @@ -3404,9 +3404,7 @@ abstract class RtcEngine { /// /// * [enabled] Whether to enable the image enhancement function: true : Enable the image enhancement function. false : (Default) Disable the image enhancement function. /// * [options] The image enhancement options. See BeautyOptions. - /// * [type] Type of media source. See MediaSourceType. In this method, this parameter supports only the following two settings: - /// The default value is unknownMediaSource. - /// If you want to use the second camera to capture video, set this parameter to secondaryCameraSource. + /// * [type] Source type of the extension. See MediaSourceType. /// /// 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. @@ -3425,7 +3423,7 @@ abstract class RtcEngine { /// When you use an external video source to implement custom video capture, or send an external video source to the SDK, Agora recommends using setExtensionProperty. /// This method relies on the image enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. /// - /// * [enabled] Whether to enable low-light enhancement function: true : Enable low-light enhancement function. false : (Default) Disable low-light enhancement function. + /// * [enabled] Whether to enable low-light enhancement: true : Enable low-light enhancement. false : (Default) Disable low-light enhancement. /// * [options] The low-light enhancement options. See LowlightEnhanceOptions. /// * [type] The type of the video source. See MediaSourceType. /// @@ -3700,7 +3698,7 @@ abstract class RtcEngine { /// Sets the default video stream type to subscribe to. /// - /// The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sender side, which means the sender does not actively send low-quality video stream. The receiver can initiate a low-quality video stream request by calling this method, and the sender will automatically start sending low-quality video stream upon receiving the request. By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. The SDK will dynamically adjust the size of the corresponding video stream based on the size of the video window to save bandwidth and computing resources. The default aspect ratio of the low-quality video stream is the same as that of the high-quality video stream. According to the current aspect ratio of the high-quality video stream, the system will automatically allocate the resolution, frame rate, and bitrate of the low-quality video stream. Under limited network conditions, if the publisher does not disable the dual-stream mode using enableDualStreamMode (false), the receiver can choose to receive either the high-quality video stream, or the low-quality video stream. The high-quality video stream has a higher resolution and bitrate, while the low-quality video stream has a lower resolution and bitrate. + /// The SDK will dynamically adjust the size of the corresponding video stream based on the size of the video window to save bandwidth and computing resources. The default aspect ratio of the low-quality video stream is the same as that of the high-quality video stream. According to the current aspect ratio of the high-quality video stream, the system will automatically allocate the resolution, frame rate, and bitrate of the low-quality video stream. The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sending end, which means the sender does not actively send low-quality video stream. The receiver with the role of the host can initiate a low-quality video stream request by calling this method, and upon receiving the request, the sending end automatically starts sending the low-quality video stream. /// Call this method before joining a channel. The SDK does not support changing the default subscribed video stream type after joining a channel. /// If you call both this method and setRemoteVideoStreamType, the setting of setRemoteVideoStreamType takes effect. /// @@ -3724,7 +3722,11 @@ abstract class RtcEngine { /// Sets the video stream type to subscribe to. /// - /// Under limited network conditions, if the publisher does not disable the dual-stream mode using enableDualStreamMode (false), the receiver can choose to receive either the high-quality video stream, or the low-quality video stream. The high-quality video stream has a higher resolution and bitrate, while the low-quality video stream has a lower resolution and bitrate. By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. The SDK will dynamically adjust the size of the corresponding video stream based on the size of the video window to save bandwidth and computing resources. The default aspect ratio of the low-quality video stream is the same as that of the high-quality video stream. According to the current aspect ratio of the high-quality video stream, the system will automatically allocate the resolution, frame rate, and bitrate of the low-quality video stream. The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sender side, which means the sender does not actively send low-quality video stream. The receiver can initiate a low-quality video stream request by calling this method, and the sender will automatically start sending low-quality video stream upon receiving the request. You can call this method either before or after joining a channel. If you call both setRemoteVideoStreamType and setRemoteDefaultVideoStreamType, the setting of setRemoteVideoStreamType takes effect. + /// The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sending end, which means the sender does not actively send low-quality video stream. The receiver with the role of the host can initiate a low-quality video stream request by calling this method, and upon receiving the request, the sending end automatically starts sending the low-quality video stream. The SDK will dynamically adjust the size of the corresponding video stream based on the size of the video window to save bandwidth and computing resources. The default aspect ratio of the low-quality video stream is the same as that of the high-quality video stream. According to the current aspect ratio of the high-quality video stream, the system will automatically allocate the resolution, frame rate, and bitrate of the low-quality video stream. + /// You can call this method either before or after joining a channel. + /// If the publisher has already called setDualStreamMode and set mode to disableSimulcastStream (never send low-quality video stream), calling this method will not take effect, you should call setDualStreamMode again on the sending end and adjust the settings. + /// Calling this method on the receiving end of the audience role will not take effect. + /// If you call both setRemoteVideoStreamType and setRemoteDefaultVideoStreamType, the settings in setRemoteVideoStreamType take effect. /// /// * [uid] The user ID. /// * [streamType] The video stream type, see VideoStreamType. @@ -4592,7 +4594,7 @@ abstract class RtcEngine { /// Sets dual-stream mode configuration on the sender side. /// - /// The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sender side, which means the sender does not actively send low-quality video stream. The receiver can initiate a low-quality video stream request by calling setRemoteVideoStreamType, and the sender then automatically starts sending low-quality video stream upon receiving the request. + /// The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sender side, which means the sender does not actively send low-quality video stream. The receiving end with the role of the host can initiate a low-quality video stream request by calling setRemoteVideoStreamType, and upon receiving the request, the sending end automatically starts sending low-quality stream. /// If you want to modify this behavior, you can call this method and set mode to disableSimulcastStream (never send low-quality video streams) or enableSimulcastStream (always send low-quality video streams). /// If you want to restore the default behavior after making changes, you can call this method again with mode set to autoSimulcastStream. The difference and connection between this method and enableDualStreamMode is as follows: /// When calling this method and setting mode to disableSimulcastStream, it has the same effect as calling enableDualStreamMode and setting enabled to false. @@ -4821,9 +4823,7 @@ abstract class RtcEngine { /// * [provider] The name of the extension provider. /// * [extension] The name of the extension. /// * [enable] Whether to enable the extension: true : Enable the extension. false : Disable the extension. - /// * [type] Type of media source. See MediaSourceType. In this method, this parameter supports only the following two settings: - /// The default value is unknownMediaSource. - /// If you want to use the second camera to capture video, set this parameter to secondaryCameraSource. + /// * [type] Source type of the extension. See MediaSourceType. /// /// 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. @@ -4841,9 +4841,7 @@ abstract class RtcEngine { /// * [extension] The name of the extension. /// * [key] The key of the extension. /// * [value] The value of the extension key. - /// * [type] Type of media source. See MediaSourceType. In this method, this parameter supports only the following two settings: - /// The default value is unknownMediaSource. - /// If you want to use the second camera to capture video, set this parameter to secondaryCameraSource. + /// * [type] Source type of the extension. See MediaSourceType. /// /// 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. @@ -4960,13 +4958,13 @@ abstract class RtcEngine { /// Registers an extension. /// - /// After the extension is loaded, you can call this method to register the extension. This method applies to Windows only. + /// After the extension is loaded, you can call this method to register the extension. + /// Before calling this method, you need to call loadExtensionProvider to load the extension first. + /// For extensions external to the SDK (such as Extensions Marketplace extensions and SDK extensions), you need to call this method before calling setExtensionProperty. /// /// * [provider] The name of the extension provider. /// * [extension] The name of the extension. - /// * [type] Type of media source. See MediaSourceType. In this method, this parameter supports only the following two settings: - /// The default value is unknownMediaSource. - /// If you want to use the second camera to capture video, set this parameter to secondaryCameraSource. + /// * [type] Source type of the extension. See MediaSourceType. /// /// 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. @@ -5393,7 +5391,7 @@ abstract class RtcEngine { /// Starts screen capture. /// - /// There are two ways to start screen sharing, you can choose one according to your needs: + /// There are two options for enabling screen sharing. You can choose the one that best suits your specific scenario: /// Call this method before joining a channel, then call joinChannel to join channel and set publishScreenCaptureVideo to true to start screen sharing. /// Call this method after joining a channel, then call updateChannelMediaOptions and set publishScreenCaptureVideo to true to start screen sharing. /// This method applies to Android and iOS only. @@ -5402,7 +5400,7 @@ abstract class RtcEngine { /// If you are using the custom audio source instead of the SDK to capture audio, Agora recommends you add the keep-alive processing logic to your application to avoid screen sharing stopping when the application goes to the background. /// This feature requires high-performance device, and Agora recommends that you use it on iPhone X and later models. /// This method relies on the iOS screen sharing dynamic library AgoraReplayKitExtension.xcframework. If the dynamic library is deleted, screen sharing cannot be enabled normally. - /// On the Android platform, make sure the user has granted the app screen capture permission. + /// On the Android platform, if the user has not granted the app screen capture permission, the SDK reports the onPermissionError (2) callback. /// On Android 9 and later, to avoid the application being killed by the system after going to the background, Agora recommends you add the foreground service android.permission.FOREGROUND_SERVICE to the /app/Manifests/AndroidManifest.xml file. /// Due to performance limitations, screen sharing is not supported on Android TV. /// Due to system limitations, if you are using Huawei phones, do not adjust the video encoding resolution of the screen sharing stream during the screen sharing, or you could experience crashes. diff --git a/lib/src/agora_rtc_engine_ex.dart b/lib/src/agora_rtc_engine_ex.dart index 739f8d2ef..7fb1f8587 100644 --- a/lib/src/agora_rtc_engine_ex.dart +++ b/lib/src/agora_rtc_engine_ex.dart @@ -135,7 +135,9 @@ abstract class RtcEngineEx implements RtcEngine { /// Sets the video stream type to subscribe to. /// - /// The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sender side, which means the sender does not actively send low-quality video stream. The receiver can initiate a low-quality video stream request by calling this method, and the sender will automatically start sending low-quality video stream upon receiving the request. By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. The SDK will dynamically adjust the size of the corresponding video stream based on the size of the video window to save bandwidth and computing resources. The default aspect ratio of the low-quality video stream is the same as that of the high-quality video stream. According to the current aspect ratio of the high-quality video stream, the system will automatically allocate the resolution, frame rate, and bitrate of the low-quality video stream. Under limited network conditions, if the publisher does not disable the dual-stream mode using enableDualStreamModeEx (false), the receiver can choose to receive either the high-quality video stream, or the low-quality video stream. The high-quality video stream has a higher resolution and bitrate, while the low-quality video stream has a lower resolution and bitrate. + /// The SDK will dynamically adjust the size of the corresponding video stream based on the size of the video window to save bandwidth and computing resources. The default aspect ratio of the low-quality video stream is the same as that of the high-quality video stream. According to the current aspect ratio of the high-quality video stream, the system will automatically allocate the resolution, frame rate, and bitrate of the low-quality video stream. The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sending end, which means the sender does not actively send low-quality video stream. The receiver with the role of the host can initiate a low-quality video stream request by calling this method, and upon receiving the request, the sending end automatically starts sending the low-quality video stream. + /// If the publisher has already called setDualStreamModeEx and set mode to disableSimulcastStream (never send low-quality video stream), calling this method will not take effect, you should call setDualStreamModeEx again on the sending end and adjust the settings. + /// Calling this method on the receiving end of the audience role will not take effect. /// /// * [uid] The user ID. /// * [streamType] The video stream type, see VideoStreamType. @@ -620,7 +622,7 @@ abstract class RtcEngineEx implements RtcEngine { /// /// After you enable dual-stream mode, you can call setRemoteVideoStreamType to choose to receive either the high-quality video stream or the low-quality video stream on the subscriber side. You can call this method to enable or disable the dual-stream mode on the publisher side. Dual streams are a pairing of a high-quality video stream and a low-quality video stream: /// High-quality video stream: High bitrate, high resolution. - /// Low-quality video stream: Low bitrate, low resolution. This method is applicable to all types of streams from the sender, including but not limited to video streams collected from cameras, screen sharing streams, and custom-collected video streams. + /// Low-quality video stream: Low bitrate, low resolution. Deprecated: This method is deprecated as of v4.2.0. Use setDualStreamModeEx instead. This method is applicable to all types of streams from the sender, including but not limited to video streams collected from cameras, screen sharing streams, and custom-collected video streams. /// /// * [enabled] Whether to enable dual-stream mode: true : Enable dual-stream mode. false : (Default) Disable dual-stream mode. /// * [streamConfig] The configuration of the low-quality video stream. See SimulcastStreamConfig. When setting mode to disableSimulcastStream, setting streamConfig will not take effect. @@ -635,7 +637,7 @@ abstract class RtcEngineEx implements RtcEngine { /// Sets the dual-stream mode on the sender side. /// - /// The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sender side, which means the sender does not actively send low-quality video stream. The receiver can initiate a low-quality video stream request by calling setRemoteVideoStreamTypeEx, and the sender will automatically start sending low-quality video stream upon receiving the request. + /// The SDK defaults to enabling low-quality video stream adaptive mode (autoSimulcastStream) on the sending end, which means the sender does not actively send low-quality video stream. The receiver with the role of the host can initiate a low-quality video stream request by calling setRemoteVideoStreamTypeEx, and upon receiving the request, the sending end automatically starts sending the low-quality video stream. /// If you want to modify this behavior, you can call this method and set mode to disableSimulcastStream (never send low-quality video streams) or enableSimulcastStream (always send low-quality video streams). /// If you want to restore the default behavior after making changes, you can call this method again with mode set to autoSimulcastStream. The difference and connection between this method and enableDualStreamModeEx is as follows: /// When calling this method and setting mode to disableSimulcastStream, it has the same effect as enableDualStreamModeEx (false).