diff --git a/lib/src/agora_base.dart b/lib/src/agora_base.dart index 9b8e38370..a50a38514 100644 --- a/lib/src/agora_base.dart +++ b/lib/src/agora_base.dart @@ -1774,7 +1774,7 @@ class VideoEncoderConfiguration { @JsonKey(name: 'frameRate') final int? frameRate; - /// The encoding bitrate (Kbps) of the video. : (Recommended) Standard bitrate mode. In this mode, the bitrates of the live broadcasting profile is higher than that of the communication profile. : Adaptive bitrate mode In this mode, the bitrates of the live broadcasting profile equals that of the communication profile. If this mode is selected, the video frame rate of live broadcasting scenarios may be lower than the set value. + /// The encoding bitrate (Kbps) of the video. (0): (Recommended) Standard bitrate mode. In this mode, the bitrates of the live broadcasting profile is higher than that of the communication profile. (-1): Adaptive bitrate mode. In this mode, the bitrates of the live broadcasting profile equals that of the communication profile. If this mode is selected, the video frame rate of live broadcasting scenarios may be lower than the set value. @JsonKey(name: 'bitrate') final int? bitrate; @@ -2654,7 +2654,7 @@ enum LocalAudioStreamError { @JsonValue(2) localAudioStreamErrorDeviceNoPermission, - /// 3: (Android and iOS only) The local audio capture device is used. Remind your users to check whether another application occupies the microphone. Local audio capture automatically resumes after the microphone is idle for about five seconds. You can also try to rejoin the channel after the microphone is idle. + /// 3: (Android and iOS only) The local audio capture device is already in use. Remind your users to check whether another application occupies the microphone. Local audio capture automatically resumes after the microphone is idle for about five seconds. You can also try to rejoin the channel after the microphone is idle. @JsonValue(3) localAudioStreamErrorDeviceBusy, @@ -2760,11 +2760,11 @@ enum LocalVideoStreamError { @JsonValue(5) localVideoStreamErrorEncodeFailure, - /// 6: (For iOS only) The app is in the background. Remind the user that video capture cannot be performed normally when the app is in the background. + /// 6: (iOS only) The app is in the background. Remind the user that video capture cannot be performed normally when the app is in the background. @JsonValue(6) localVideoStreamErrorCaptureInbackground, - /// 7: (For iOS only) The current application window is running in Slide Over, Split View, or Picture in Picture mode, and another app is occupying the camera. Remind the user that the application cannot capture video properly when the app is running in Slide Over, Split View, or Picture in Picture mode and another app is occupying the camera. + /// 7: (iOS only) The current application window is running in Slide Over, Split View, or Picture in Picture mode, and another app is occupying the camera. Remind the user that the application cannot capture video properly when the app is running in Slide Over, Split View, or Picture in Picture mode and another app is occupying the camera. @JsonValue(7) localVideoStreamErrorCaptureMultipleForegroundApps, @@ -2772,11 +2772,11 @@ enum LocalVideoStreamError { @JsonValue(8) localVideoStreamErrorDeviceNotFound, - /// 9: (For macOS only) The video capture device currently in use is disconnected (such as being unplugged). + /// 9: (macOS only) The video capture device currently in use is disconnected (such as being unplugged). @JsonValue(9) localVideoStreamErrorDeviceDisconnected, - /// 10: (For macOS and Windows only) The SDK cannot find the video device in the video device list. Check whether the ID of the video device is valid. + /// 10: (macOS and Windows only) The SDK cannot find the video device in the video device list. Check whether the ID of the video device is valid. @JsonValue(10) localVideoStreamErrorDeviceInvalidId, @@ -2784,18 +2784,18 @@ enum LocalVideoStreamError { @JsonValue(101) localVideoStreamErrorDeviceSystemPressure, - /// 11: (For macOS only) The shared window is minimized when you call startScreenCaptureByWindowId to share a window. The SDK cannot share a minimized window. You can cancel the minimization of this window at the application layer, for example by maximizing this window. + /// 11: (macOS only) The shared window is minimized when you call startScreenCaptureByWindowId to share a window. The SDK cannot share a minimized window. You can cancel the minimization of this window at the application layer, for example by maximizing this window. @JsonValue(11) localVideoStreamErrorScreenCaptureWindowMinimized, - /// 12: (For macOS and Windows only) The error code indicates that a window shared by the window ID has been closed or a full-screen window shared by the window ID has exited full-screen mode. After exiting full-screen mode, remote users cannot see the shared window. To prevent remote users from seeing a black screen, Agora recommends that you immediately stop screen sharing. Common scenarios for reporting this error code: + /// 12: (macOS and Windows only) The error code indicates that a window shared by the window ID has been closed or a full-screen window shared by the window ID has exited full-screen mode. After exiting full-screen mode, remote users cannot see the shared window. To prevent remote users from seeing a black screen, Agora recommends that you immediately stop screen sharing. Common scenarios reporting this error code: /// When the local user closes the shared window, the SDK reports this error code. /// The local user shows some slides in full-screen mode first, and then shares the windows of the slides. After the user exits full-screen mode, the SDK reports this error code. /// The local user watches a web video or reads a web document in full-screen mode first, and then shares the window of the web video or document. After the user exits full-screen mode, the SDK reports this error code. @JsonValue(12) localVideoStreamErrorScreenCaptureWindowClosed, - /// 13: (For Windows only) The window being shared is overlapped by another window, so the overlapped area is blacked out by the SDK during window sharing. + /// 13: (Windows only) The window being shared is overlapped by another window, so the overlapped area is blacked out by the SDK during window sharing. @JsonValue(13) localVideoStreamErrorScreenCaptureWindowOccluded, @@ -2807,7 +2807,7 @@ enum LocalVideoStreamError { @JsonValue(21) localVideoStreamErrorScreenCaptureFailure, - /// @nodoc + /// 22: (Windows and macOS only) No permission for screen capture. @JsonValue(22) localVideoStreamErrorScreenCaptureNoPermission, } @@ -3767,7 +3767,7 @@ class LiveTranscoding { @JsonKey(name: 'height') final int? height; - /// Bitrate of the output video stream for Media Push in Kbps. The default value is 400 Kbps. + /// Bitrate of the output video stream for Media Push in Kbps. The default value is 400 Kbps. Set this member according to the table. If you set a bitrate beyond the proper range, the SDK automatically adapts it to a value within the range. @JsonKey(name: 'videoBitrate') final int? videoBitrate; @@ -4198,7 +4198,7 @@ enum ConnectionChangedReasonType { @JsonValue(13) connectionChangedClientIpAddressChanged, - /// 14: Timeout for the keep-alive of the connection between the SDK and the Agora edge server. The connection state changes to . + /// 14: Timeout for the keep-alive of the connection between the SDK and the Agora edge server. The SDK tries to reconnect to the server automatically. @JsonValue(14) connectionChangedKeepAliveTimeout, @@ -5256,7 +5256,7 @@ class ScreenCaptureParameters { @JsonKey(name: 'bitrate') final int? bitrate; - /// Whether to capture the mouse in screen sharing: true : (Default) Capture the mouse. false : Do not capture the mouse. + /// Whether to capture the mouse in screen sharing: true : (Default) Capture the mouse. false : Do not capture the mouse. Due to macOS system restrictions, setting this parameter to false is ineffective during screen sharing (it has no impact when sharing a window). @JsonKey(name: 'captureMouseCursor') final bool? captureMouseCursor; @@ -5397,7 +5397,7 @@ class AudioRecordingConfiguration { this.quality, this.recordingChannel}); - /// The absolute path (including the filename extensions) of the recording file. For example: C:\music\audio.mp4. Ensure that the directory for the log files exists and is writable. + /// The absolute path (including the filename extensions) of the recording file. For example: C:\music\audio.aac. Ensure that the directory for the log files exists and is writable. @JsonKey(name: 'filePath') final String? filePath; diff --git a/lib/src/agora_media_base.dart b/lib/src/agora_media_base.dart index caef1c54c..06151e8cb 100644 --- a/lib/src/agora_media_base.dart +++ b/lib/src/agora_media_base.dart @@ -341,11 +341,11 @@ enum ContentInspectType { @JsonValue(0) contentInspectInvalid, - /// 1: Video content moderation. SDK takes screenshots, inspects video content of the video stream in the channel, and uploads the screenshots and moderation results. + /// @nodoc @JsonValue(1) contentInspectModeration, - /// 2: Screenshot capture. SDK takes screenshots of the video stream in the channel and uploads them. + /// 2: Video screenshot and upload via Agora self-developed extension. SDK takes screenshots of the video stream in the channel and uploads them. @JsonValue(2) contentInspectSupervision, } @@ -558,7 +558,7 @@ enum VideoPixelFormat { @JsonValue(4) videoPixelRgba, - /// 8: The format is NV12. + /// @nodoc @JsonValue(8) videoPixelNv12, diff --git a/lib/src/agora_media_engine.dart b/lib/src/agora_media_engine.dart index cd31c463f..88e68d08c 100644 --- a/lib/src/agora_media_engine.dart +++ b/lib/src/agora_media_engine.dart @@ -58,7 +58,7 @@ abstract class MediaEngine { /// Ensure that you call this method before joining a channel. /// When handling the video data returned in the callbacks, pay attention to the changes in the width and height parameters, which may be adapted under the following circumstances: /// When network conditions deteriorate, the video resolution decreases incrementally. - /// If the user adjusts the video profile, the resolution of the video returned in the callbacks also changes. After registering the raw video observer, you can use the obtained raw video data in various video pre-processing scenarios, such as implementing virtual backgrounds and image enhacement scenarios by yourself, Agora provides some open source sample projects on GitHub for your reference. + /// If the user adjusts the video profile, the resolution of the video returned in the callbacks also changes. /// /// * [observer] The observer instance. See VideoFrameObserver. /// @@ -232,7 +232,7 @@ abstract class MediaEngine { /// 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. void unregisterVideoFrameObserver(VideoFrameObserver observer); - /// Unregisters a receiver object for the encoded video image. + /// Unregisters a receiver object for the encoded video frame. /// /// * [observer] The video observer, reporting the reception of each video frame. See VideoEncodedFrameObserver. /// diff --git a/lib/src/agora_media_player.dart b/lib/src/agora_media_player.dart index 92c5b05cb..88c63428f 100644 --- a/lib/src/agora_media_player.dart +++ b/lib/src/agora_media_player.dart @@ -101,7 +101,7 @@ abstract class MediaPlayer { /// Gets the number of the media streams in the media resource. /// - /// Call this method after calling open. + /// Call this method after you call open and receive the onPlayerSourceStateChanged callback reporting the state playerStateOpenCompleted. /// /// Returns /// The number of the media streams in the media resource if the method call succeeds. diff --git a/lib/src/agora_rtc_engine.dart b/lib/src/agora_rtc_engine.dart index af228bb36..12417e305 100644 --- a/lib/src/agora_rtc_engine.dart +++ b/lib/src/agora_rtc_engine.dart @@ -1254,7 +1254,7 @@ class ImageTrackOptions { /// @nodoc const ImageTrackOptions({this.imageUrl, this.fps, this.mirrorMode}); - /// The URL of the image that you want to use to replace the video feeds. The image must be in PNG format. This method supports adding an image from the local absolute or relative file path. On the Android platform, adding images from /assets/ is not supported. + /// The image URL. Supported formats of images include JPEG, JPG, PNG and GIF. This method supports adding an image from the local absolute or relative file path. On the Android platform, adding images from /assets/ is not supported. @JsonKey(name: 'imageUrl') final String? imageUrl; @@ -1276,7 +1276,7 @@ class ImageTrackOptions { /// The channel media options. /// -/// Agora supports publishing multiple audio streams and one video stream at the same time and in the same RtcConnection. For example, publishMicrophoneTrack, publishAudioTrack, publishCustomAudioTrack, and publishMediaPlayerAudioTrack can be set as true at the same time, but only one of publishCameraTrack, publishScreenCaptureVideo publishScreenTrack, publishCustomVideoTrack, or publishEncodedVideoTrack can be set as true. Agora recommends that you set member parameter values yourself according to your business scenario, otherwise the SDK will automatically assign values to member parameters. +/// Agora supports publishing multiple audio streams and one video stream at the same time and in the same RtcConnection. For example, publishMicrophoneTrack, publishCustomAudioTrack, and publishMediaPlayerAudioTrack can be set as true at the same time, but only one of publishCameraTrack, publishScreenCaptureVideo publishScreenTrack, publishCustomVideoTrack, or publishEncodedVideoTrack can be set as true. Agora recommends that you set member parameter values yourself according to your business scenario, otherwise the SDK will automatically assign values to member parameters. @JsonSerializable(explicitToJson: true, includeIfNull: false) class ChannelMediaOptions { /// @nodoc @@ -2115,7 +2115,7 @@ class RtcEngineEventHandler { /// /// When the token expires during a call, the SDK triggers this callback to remind the app to renew the token. When receiving this callback, you need to generate a new token on your token server and you can renew your token through one of the following ways: /// Call renewToken to pass in the new token. - /// Call to leave the current channel and then pass in the new token when you call joinChannel to join a channel. + /// Call leaveChannel to leave the current channel and then pass in the new token when you call joinChannel to join a channel. /// /// * [connection] The connection information. See RtcConnection. final void Function(RtcConnection connection)? onRequestToken; @@ -2244,7 +2244,7 @@ class RtcEngineEventHandler { /// Occurs when the user role switching fails in the interactive live streaming. /// - /// In the live broadcasting channel profile, when the local user calls to switch the user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role. + /// In the live broadcasting channel profile, when the local user calls setClientRole to switch the user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role. /// /// * [connection] The connection information. See RtcConnection. /// * [reason] The reason for a user role switch failure. See ClientRoleChangeFailedReason. @@ -3058,7 +3058,7 @@ abstract class RtcEngine { /// * [token] The token generated on your server for authentication. When the token for preloading channels expires, you can update the token based on the number of channels you preload. /// When preloading one channel, calling this method to pass in the new token. /// When preloading more than one channels: - /// If you use a wildcard token for all preloaded channels, call updatePreloadChannelToken to update the token. + /// If you use a wildcard token for all preloaded channels, call updatePreloadChannelToken to update the token. When generating a wildcard token, ensure the user ID is not set as 0. /// If you use different tokens to preload different channels, call this method to pass in your user ID, channel name and the new token. /// * [channelId] The channel name that you want to preload. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters (89 characters in total): /// All lowercase English letters: a to z. @@ -3087,7 +3087,7 @@ abstract class RtcEngine { /// * [token] The token generated on your server for authentication. When the token for preloading channels expires, you can update the token based on the number of channels you preload. /// When preloading one channel, calling this method to pass in the new token. /// When preloading more than one channels: - /// If you use a wildcard token for all preloaded channels, call updatePreloadChannelToken to update the token. + /// If you use a wildcard token for all preloaded channels, call updatePreloadChannelToken to update the token. When generating a wildcard token, ensure the user ID is not set as 0. /// If you use different tokens to preload different channels, call this method to pass in your user ID, channel name and the new token. /// * [channelId] The channel name that you want to preload. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters (89 characters in total): /// All lowercase English letters: a to z. @@ -3134,7 +3134,7 @@ abstract class RtcEngine { /// This method allows users to join only one channel at a time. /// Ensure that the app ID you use to generate the token is the same app ID that you pass in the initialize method; otherwise, you may fail to join the channel by token. /// - /// * [token] The token generated on your server for authentication. + /// * [token] The token generated on your server for authentication. If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. /// * [channelId] The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters: /// All lowercase English letters: a to z. /// All uppercase English letters: A to Z. @@ -3200,7 +3200,7 @@ abstract class RtcEngine { /// Sets the channel profile. /// - /// After initializing the SDK, the default channel profile is the live streaming profile. You can call this method to set the usage scenario of the channel. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the interactive live video streaming. + /// After initializing the SDK, the default channel profile is the live streaming profile. You can call this method to set the channel profile. The Agora SDK differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call and prioritizes video quality for interactive live video streaming. /// To ensure the quality of real-time communication, Agora recommends that all users in a channel use the same channel profile. /// This method must be called and set before joinChannel, and cannot be set again after joining the channel. /// @@ -3218,7 +3218,7 @@ abstract class RtcEngine { /// In the interactive live streaming profile, the SDK sets the user role as audience by default. You can call this method to set the user role as host. You can call this method either before or after joining a channel. If you call this method to set the user's role as the host before joining the channel and set the local video property through the setupLocalVideo method, the local video preview is automatically enabled when the user joins the channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following: /// Calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state. /// Triggers onClientRoleChanged on the local client. - /// Triggers onUserJoined or onUserOffline on the remote client. This method applies to the interactive live streaming profile (the profile parameter of setChannelProfile is channelProfileLiveBroadcasting) only. + /// Triggers onUserJoined or onUserOffline on the remote client. This method applies to the interactive live streaming profile (the profile parameter of setChannelProfile is set as channelProfileLiveBroadcasting) only. /// /// * [role] The user role in the interactive live streaming. See ClientRoleType. /// * [options] The detailed options of a user, including the user level. See ClientRoleOptions. @@ -3259,13 +3259,13 @@ abstract class RtcEngine { /// /// In scenarios where there are existing cameras to capture video, Agora recommends that you use the following steps to capture and publish video with multiple cameras: /// Call this method to enable multi-channel camera capture. - /// Call to start the local video preview. + /// Call startPreview to start the local video preview. /// Call startCameraCapture, and set sourceType to start video capture with the second camera. /// Call joinChannelEx, and set publishSecondaryCameraTrack to true to publish the video stream captured by the second camera in the channel. If you want to disable multi-channel camera capture, use the following steps: /// Call stopCameraCapture. - /// Call this method with enabled set to false. You can call this method before and after to enable multi-camera capture: - /// If it is enabled before, the local video preview shows the image captured by the two cameras at the same time. - /// If it is enabled after, the SDK stops the current camera capture first, and then enables the primary camera and the second camera. The local video preview appears black for a short time, and then automatically returns to normal. When using this function, ensure that the system version is 13.0 or later. The minimum iOS device types that support multi-camera capture are as follows: + /// Call this method with enabled set to false. You can call this method before and after startPreview to enable multi-camera capture: + /// If it is enabled before startPreview, the local video preview shows the image captured by the two cameras at the same time. + /// If it is enabled after startPreview, the SDK stops the current camera capture first, and then enables the primary camera and the second camera. The local video preview appears black for a short time, and then automatically returns to normal. When using this function, ensure that the system version is 13.0 or later. The minimum iOS device types that support multi-camera capture are as follows: /// iPhone XR /// iPhone XS /// iPhone XS Max @@ -3368,16 +3368,22 @@ abstract class RtcEngine { /// Sets the image enhancement options. /// /// Enables or disables image enhancement, and sets the options. - /// Call this method before calling enableVideo or. - /// This method relies on the video enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + /// Call this method before calling enableVideo or startPreview. + /// 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. + /// This feature has high requirements on device performance. When calling this method, the SDK automatically checks the capabilities of the current device. /// /// * [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] The type of the video source, see MediaSourceType. + /// * [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. /// /// 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. errNotSupported (4): The current device version is below Android 5.0, and this operation is not supported. + /// < 0: Failure. + /// -4: The current device does not support this feature. Possible reasons include: + /// The current device capabilities do not meet the requirements for image enhancement. Agora recommends you replace it with a high-performance device. + /// The current device version is lower than Android 5.0 and does not support this feature. Agora recommends you replace the device or upgrade the operating system. Future setBeautyEffectOptions( {required bool enabled, required BeautyOptions options, @@ -3391,7 +3397,7 @@ abstract class RtcEngine { /// Both this method and setExtensionProperty can turn on low-light enhancement: /// When you use the SDK to capture video, Agora recommends this method (this method only works for video captured by the SDK). /// 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 video enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + /// 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. /// * [options] The low-light enhancement options. See LowlightEnhanceOptions. @@ -3413,7 +3419,7 @@ abstract class RtcEngine { /// Both this method and setExtensionProperty can turn on video noise reduction function: /// When you use the SDK to capture video, Agora recommends this method (this method only works for video captured by the SDK). /// 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 video enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + /// 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 video noise reduction: true : Enable video noise reduction. false : (Default) Disable video noise reduction. /// * [options] The video noise reduction options. See VideoDenoiserOptions. @@ -3435,7 +3441,7 @@ abstract class RtcEngine { /// Both this method and setExtensionProperty can enable color enhancement: /// When you use the SDK to capture video, Agora recommends this method (this method only works for video captured by the SDK). /// 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 video enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + /// 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 color enhancement: true Enable color enhancement. false : (Default) Disable color enhancement. /// * [options] The color enhancement options. See ColorEnhanceOptions. @@ -3451,8 +3457,8 @@ abstract class RtcEngine { /// Enables/Disables the virtual background. /// - /// The virtual background feature enables the local user to replace their original background with a static image, dynamic video, blurred background, or portrait-background segmentation to achieve picture-in-picture effect. Once the virtual background feature is enabled, all users in the channel can see the custom background. Call this method before calling enableVideo or. - /// This feature requires high performance devices. Agora recommends that you implement it on devices equipped with the following chips: + /// The virtual background feature enables the local user to replace their original background with a static image, dynamic video, blurred background, or portrait-background segmentation to achieve picture-in-picture effect. Once the virtual background feature is enabled, all users in the channel can see the custom background. Call this method before calling enableVideo or startPreview. + /// This feature has high requirements on device performance. When calling this method, the SDK automatically checks the capabilities of the current device. Agora recommends you use virtual background on devices with the following processors: /// Snapdragon 700 series 750G and later /// Snapdragon 800 series 835 and later /// Dimensity 700 series 720 and later @@ -3479,9 +3485,7 @@ abstract class RtcEngine { /// 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. - /// -1: The custom background image does not exist. Check the value of source in VirtualBackgroundSource. - /// -2: The color format of the custom background image is invalid. Check the value of color in VirtualBackgroundSource. - /// -3: The device does not support virtual background. + /// -4: The device capabilities do not meet the requirements for the virtual background feature. Agora recommends you try it on devices with higher performance. Future enableVirtualBackground( {required bool enabled, required VirtualBackgroundSource backgroundSource, @@ -3588,7 +3592,7 @@ abstract class RtcEngine { /// Enables or disables the local audio capture. /// - /// The audio function is enabled by default when users joining a channel. This method disables or re-enables the local audio function to stop or restart local audio capturing. This method does not affect receiving or playing the remote audio streams, and enableLocalAudio (false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel. Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback, which reports localAudioStreamStateStopped (0) or localAudioStreamStateRecording (1). + /// The audio function is enabled by default when users joining a channel. This method disables or re-enables the local audio function to stop or restart local audio capturing. This method does not affect receiving the remote audio streams, and enableLocalAudio (false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel. Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback, which reports localAudioStreamStateStopped (0) or localAudioStreamStateRecording (1). /// The difference between this method and muteLocalAudioStream are as follow: enableLocalAudio : Disables or re-enables the local audio capturing and processing. If you disable or re-enable local audio capturing using the enableLocalAudio method, the local user might hear a pause in the remote audio playback. muteLocalAudioStream : Sends or stops sending the local audio streams. /// You can call this method either before or after joining a channel. Calling it before joining a channel only sets the device state, and it takes effect immediately after you join the channel. /// @@ -3727,7 +3731,7 @@ abstract class RtcEngine { /// Sets the default stream type of subscrption for remote video streams. /// - /// By default, the SDK enables the low-quality video stream auto mode on the sending end (it does not actively send the low-quality video stream). The host identity receiver can initiate a low-quality video stream application at the receiving end by calling this method (the call to this method by the audience receiver does not take effect). After receiving the application, the sending end automatically switches to the low-quality video stream mode. Under limited network conditions, if the publisher has not disabled 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, and 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. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream. + /// By default, the SDK enables the low-quality video stream auto mode on the sending end (it does not actively send the low-quality video stream). The host identity receiver can initiate a low-quality video stream application at the receiving end by calling this method (the call to this method by the audience receiver does not take effect). After receiving the application, the sending end automatically switches to the low-quality video stream mode. Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode (false), the receiver can choose to receive either the high-quality video stream or the low-video stream. The high-quality video stream has a higher resolution and bitrate, and 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. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of 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 SDK applies the settings in the setRemoteVideoStreamType method. /// @@ -4042,7 +4046,7 @@ abstract class RtcEngine { /// Sets the channel mode of the current audio file. /// /// In a stereo music file, the left and right channels can store different audio data. According to your needs, you can set the channel mode to original mode, left channel mode, right channel mode, or mixed channel mode. For example, in the KTV scenario, the left channel of the music file stores the musical accompaniment, and the right channel stores the singing voice. If you only need to listen to the accompaniment, call this method to set the channel mode of the music file to left channel mode; if you need to listen to the accompaniment and the singing voice at the same time, call this method to set the channel mode to mixed channel mode. - /// Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. + /// You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// This method only applies to stereo audio files. /// /// * [mode] The channel mode. See AudioMixingDualMonoMode. @@ -4639,7 +4643,7 @@ abstract class RtcEngine { /// /// The SDK enables the low-quality video stream auto mode on the sender side by default (it does not actively sending low-quality video streams). The host identity receiver can initiate a low-quality video stream application at the receiving end by calling setRemoteVideoStreamType. After receiving the application, the sending end automatically switches to the low-quality video stream mode. /// If you want to modify this behavior, you can call this method and modify the 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 is as follows: + /// 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 and setting enabled to false. /// When calling this method and setting mode to enableSimulcastStream, it has the same effect as calling and setting enabled to true. /// Both methods can be called before and after joining a channel. If both methods are used, the settings in the method called later takes precedence. @@ -4990,7 +4994,9 @@ abstract class RtcEngine { /// * [extension] The name of the extension. /// * [key] The key of the extension. /// * [value] The value of the extension key. - /// * [type] The type of the video source, see MediaSourceType. + /// * [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. /// /// 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. @@ -5469,7 +5475,7 @@ abstract class RtcEngine { /// 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. /// On the iOS platform, screen sharing is only available on iOS 12.0 and later. - /// The billing for the screen sharing stream is based on the dimensions in ScreenVideoParameters. When you do not pass in a value, Agora bills you at 1280 × 720; when you pass a value in, Agora bills you at that value. + /// The billing for the screen sharing stream is based on the dimensions in ScreenVideoParameters. When you do not pass in a value, Agora bills you at 1280 × 720; when you pass a value in, Agora bills you at that value. For billing details, see. /// 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. @@ -5606,8 +5612,7 @@ abstract class RtcEngine { /// Starts pushing media streams to a CDN without transcoding. /// - /// Ensure that you enable the Media Push service before using this function. See Enable Media Push. - /// Call this method after joining a channel. + /// Call this method after joining a channel. /// Only hosts in the LIVE_BROADCASTING profile can call this method. /// If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. Agora recommends that you use the server-side Media Push function. You can call this method to push an audio or video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times. After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming. /// @@ -5623,8 +5628,7 @@ abstract class RtcEngine { /// Starts Media Push and sets the transcoding configuration. /// - /// Agora recommends that you use the server-side Media Push function. You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times. After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming. - /// Ensure that you enable the Media Push service before using this function. See Enable Media Push. + /// Agora recommends that you use the server-side Media Push function. You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times. Under one Agora project, the maximum number of concurrent tasks to push media streams is 200 by default. If you need a higher quota, contact. After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming. /// Call this method after joining a channel. /// Only hosts in the LIVE_BROADCASTING profile can call this method. /// If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. @@ -5731,8 +5735,8 @@ abstract class RtcEngine { /// Sets the rotation angle of the captured video. /// - /// You must call this method after enableVideo. The setting result will take effect after the camera is successfully turned on, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). - /// This method applies to Windows only. + /// This method applies to Windows only. + /// You must call this method after enableVideo. The setting result will take effect after the camera is successfully turned on, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). /// When the video capture device does not have the gravity sensing function, you can call this method to manually adjust the rotation angle of the captured video. /// /// * [type] The video source type. See VideoSourceType. @@ -6005,7 +6009,7 @@ abstract class RtcEngine { /// The local client: onLocalUserRegistered, onJoinChannelSuccess and onConnectionStateChanged callbacks. /// The remote client: The onUserJoined callback, if the user is in the COMMUNICATION profile, and the onUserInfoUpdated callback if the user is a host in the LIVE_BROADCASTING profile. Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods. To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the ID of the user is set to the same parameter type. /// - /// * [token] The token generated on your server for authentication. + /// * [token] The token generated on your server for authentication. If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. /// * [channelId] The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters: /// All lowercase English letters: a to z. /// All uppercase English letters: A to Z. @@ -6042,7 +6046,7 @@ abstract class RtcEngine { /// The local client: onLocalUserRegistered, onJoinChannelSuccess and onConnectionStateChanged callbacks. /// The remote client: The onUserJoined callback, if the user is in the COMMUNICATION profile, and the onUserInfoUpdated callback if the user is a host in the LIVE_BROADCASTING profile. /// - /// * [token] The token generated on your server for authentication. + /// * [token] The token generated on your server for authentication. If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. /// * [channelId] The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters: /// All lowercase English letters: a to z. /// All uppercase English letters: A to Z. @@ -6286,11 +6290,10 @@ abstract class RtcEngine { /// Enables or disables video screenshot and upload. /// - /// When video screenshot and upload function is enabled, the SDK takes screenshots and upload videos sent by local users based on the type and frequency of the module you set in ContentInspectConfig. After video screenshot and upload, the Agora server sends the callback notification to your app server in HTTPS requests and sends all screenshots to the third-party cloud storage service. Before calling this method, ensure that the video screenshot upload service has been activated. Before calling this method, ensure that Video content moderation service has been activated. - /// This method relies on the video screenshot and upload dynamic library libagora_content_inspect_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + /// When video screenshot and upload function is enabled, the SDK takes screenshots and uploads videos sent by local users based on the type and frequency of the module you set in ContentInspectConfig. After video screenshot and upload, the Agora server sends the callback notification to your app server in HTTPS requests and sends all screenshots to the third-party cloud storage service. Before calling this method, ensure that you have contacted to activate the video screenshot upload service. /// /// * [enabled] Whether to enable video screenshot and upload : true : Enables video screenshot and upload. false : Disables video screenshot and upload. - /// * [config] Configuration of video screenshot and upload. See ContentInspectConfig. + /// * [config] Configuration of video screenshot and upload. See ContentInspectConfig. When the video moderation module is set to video moderation via Agora self-developed extension(contentInspectSupervision), the video screenshot and upload dynamic library libagora_content_inspect_extension.dll is required. Deleting this library disables the screenshot and upload feature. /// /// 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. @@ -6311,7 +6314,16 @@ abstract class RtcEngine { Future adjustCustomAudioPublishVolume( {required int trackId, required int volume}); - /// @nodoc + /// Adjusts the volume of the custom audio track played locally. + /// + /// Ensure you have called the createCustomAudioTrack method to create a custom audio track before calling this method. If you want to change the volume of the audio to be played locally, you need to call this method again. + /// + /// * [trackId] The audio track ID. Set this parameter to the custom audio track ID returned in createCustomAudioTrack. + /// * [volume] The volume of the audio source. The value can range from 0 to 100. 0 means mute; 100 means the original volume. + /// + /// 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 adjustCustomAudioPlayoutVolume( {required int trackId, required int volume}); diff --git a/lib/src/agora_rtc_engine_ex.dart b/lib/src/agora_rtc_engine_ex.dart index 71c13eafd..af7cbc155 100644 --- a/lib/src/agora_rtc_engine_ex.dart +++ b/lib/src/agora_rtc_engine_ex.dart @@ -34,7 +34,7 @@ abstract class RtcEngineEx implements RtcEngine { /// If you want to join the same channel from different devices, ensure that the user IDs are different for all devices. /// Ensure that the app ID you use to generate the token is the same as the app ID used when creating the RtcEngine instance. /// - /// * [token] The token generated on your server for authentication. + /// * [token] The token generated on your server for authentication. If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. /// * [connection] The connection information. See RtcConnection. /// * [options] The channel media options. See ChannelMediaOptions. /// @@ -57,7 +57,7 @@ abstract class RtcEngineEx implements RtcEngine { /// /// This method lets the user leave the channel, for example, by hanging up or exiting the call. After calling joinChannelEx to join the channel, this method must be called to end the call before starting the next call. This method can be called whether or not a call is currently in progress. This method releases all resources related to the session. This method call is asynchronous. When this method returns, it does not necessarily mean that the user has left the channel. After you leave the channel, the SDK triggers the onLeaveChannel callback. After actually leaving the channel, the local user triggers the onLeaveChannel callback; after the user in the communication scenario and the host in the live streaming scenario leave the channel, the remote user triggers the onUserOffline callback. /// If you call release immediately after calling this method, the SDK does not trigger the onLeaveChannel callback. - /// Calling leaveChannel will leave the channels when calling joinChannel and joinChannelEx at the same time. + /// If you want to leave the channels that you joined by calling joinChannel and joinChannelEx, call the leaveChannel method. /// /// * [connection] The connection information. See RtcConnection. /// * [options] The options for leaving the channel. See LeaveChannelOptions. This parameter only supports the stopMicrophoneRecording member in the LeaveChannelOptions settings; setting other members does not take effect. @@ -420,7 +420,7 @@ abstract class RtcEngineEx implements RtcEngine { /// Creates a data stream. /// - /// Creates a data stream. Each user can create up to five data streams in a single channel. Compared with createDataStreamEx, this method does not support data reliability. If a data packet is not received five seconds after it was sent, the SDK directly discards the data. + /// Creates a data stream. Each user can create up to five data streams in a single channel. /// /// * [config] The configurations for the data stream. See DataStreamConfig. /// * [connection] The connection information. See RtcConnection. @@ -521,8 +521,7 @@ abstract class RtcEngineEx implements RtcEngine { /// Starts pushing media streams to a CDN without transcoding. /// - /// Ensure that you enable the Media Push service before using this function. See Enable Media Push. - /// Call this method after joining a channel. + /// Call this method after joining a channel. /// Only hosts in the LIVE_BROADCASTING profile can call this method. /// If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. Agora recommends that you use the server-side Media Push function. You can call this method to push an audio or video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times. After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming. /// diff --git a/lib/src/audio_device_manager.dart b/lib/src/audio_device_manager.dart index 83e4de364..47319d9a8 100644 --- a/lib/src/audio_device_manager.dart +++ b/lib/src/audio_device_manager.dart @@ -138,10 +138,19 @@ abstract class AudioDeviceManager { /// The ID of the current loopback device. Future getLoopbackDevice(); - /// @nodoc + /// Mutes the audio playback device. + /// + /// * [mute] Whether to mute the audio playback device: true : Mute the audio playback device. false : Unmute the audio playback device. + /// + /// 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 setPlaybackDeviceMute(bool mute); - /// @nodoc + /// Retrieves whether the audio playback device is muted. + /// + /// Returns + /// true : The audio playback device is muted. false : The audio playback device is unmuted. Future getPlaybackDeviceMute(); /// @nodoc