diff --git a/android/build.gradle b/android/build.gradle index a7f04272b..8a17626fd 100644 --- a/android/build.gradle +++ b/android/build.gradle @@ -51,9 +51,9 @@ dependencies { if (isDev(project)) { implementation fileTree(dir: "libs", include: ["*.jar"]) } else { - api 'io.agora.rtc:iris-rtc:4.2.1-build.1' - api 'io.agora.rtc:full-sdk:4.2.1' - api 'io.agora.rtc:full-screen-sharing:4.2.1' + api 'io.agora.rtc:iris-rtc:4.2.2-build.1' + api 'io.agora.rtc:full-sdk:4.2.2' + api 'io.agora.rtc:full-screen-sharing:4.2.2' } } diff --git a/example/lib/examples/advanced/music_player/music_player.dart b/example/lib/examples/advanced/music_player/music_player.dart index 3bf025648..304c791a3 100644 --- a/example/lib/examples/advanced/music_player/music_player.dart +++ b/example/lib/examples/advanced/music_player/music_player.dart @@ -206,8 +206,7 @@ class _MusicPlayerExampleState extends State { if (!isPreloaded) { _preloadCompleted = Completer(); _getLyricCompleted = Completer(); - await _musicContentCenter.preload( - songCode: _selectedMusic.songCode!); + await _musicContentCenter.preload(_selectedMusic.songCode!); _getLyricRequestId = await _musicContentCenter.getLyric( songCode: _selectedMusic.songCode!); } else { @@ -310,18 +309,30 @@ class _MusicPlayerExampleState extends State { }); } }, - onPreLoadEvent: (int songCode, int percent, String lyricUrl, - PreloadStatusCode status, MusicContentCenterStatusCode errorCode) { + onPreLoadEvent: ( + String requestId, + int songCode, + int percent, + String lyricUrl, + PreloadStatusCode status, + MusicContentCenterStatusCode errorCode, + ) { logSink.log( - '[onPreLoadEvent], songCode: $songCode, percent: $percent status: $status, errorCode: $errorCode, lyricUrl: $lyricUrl'); + '[onPreLoadEvent], requestId: $requestId songCode: $songCode, percent: $percent status: $status, errorCode: $errorCode, lyricUrl: $lyricUrl'); if (_selectedMusic.songCode == songCode && status == PreloadStatusCode.kPreloadStatusCompleted) { _preloadCompleted?.complete(); _preloadCompleted = null; } }, - onLyricResult: (String requestId, String lyricUrl, - MusicContentCenterStatusCode errorCode) { + onLyricResult: ( + String requestId, + int songCode, + String lyricUrl, + MusicContentCenterStatusCode errorCode, + ) { + logSink.log( + '[onLyricResult], requestId: $requestId songCode: $songCode, lyricUrl: $lyricUrl errorCode: $errorCode'); if (_getLyricRequestId == requestId) { _getLyricCompleted?.complete(lyricUrl); _getLyricCompleted = null; diff --git a/ios/agora_rtc_engine.podspec b/ios/agora_rtc_engine.podspec index d27d09af4..96f48fff5 100644 --- a/ios/agora_rtc_engine.podspec +++ b/ios/agora_rtc_engine.podspec @@ -23,8 +23,8 @@ Pod::Spec.new do |s| puts '[plugin_dev] Found .plugin_dev file, use vendored_frameworks instead.' s.vendored_frameworks = 'libs/*.xcframework' else - s.dependency 'AgoraIrisRTC_iOS', '4.2.1-build.1' - s.dependency 'AgoraRtcEngine_iOS', '4.2.1' + s.dependency 'AgoraIrisRTC_iOS', '4.2.2-build.1' + s.dependency 'AgoraRtcEngine_iOS', '4.2.2' end s.platform = :ios, '9.0' diff --git a/lib/src/agora_base.dart b/lib/src/agora_base.dart index 48fe6e0f7..9b8e38370 100644 --- a/lib/src/agora_base.dart +++ b/lib/src/agora_base.dart @@ -196,15 +196,24 @@ enum ErrorCodeType { @JsonValue(2) errInvalidArgument, - /// 3: The SDK is not ready. Possible reasons include the following:The initialization of RtcEngine fails. Reinitialize the RtcEngine.No user has joined the channel when the method is called. Check the code logic.The user has not left the channel when the rate or complain method is called. Check the code logic.The audio module is disabled.The program is not complete. + /// 3: The SDK is not ready. Possible reasons include the following: + /// The initialization of RtcEngine fails. Reinitialize the RtcEngine. + /// No user has joined the channel when the method is called. Check the code logic. + /// The user has not left the channel when the rate or complain method is called. Check the code logic. + /// The audio module is disabled. + /// The program is not complete. @JsonValue(3) errNotReady, - /// 4: The RtcEngine does not support the request. Possible reasons include the following:The built-in encryption mode is incorrect, or the SDK fails to load the external encryption library. Check the encryption mode setting, or reload the external encryption library. + /// 4: The RtcEngine does not support the request. Possible reasons include the following: + /// The built-in encryption mode is incorrect, or the SDK fails to load the external encryption library. Check the encryption mode setting, or reload the external encryption library. @JsonValue(4) errNotSupported, - /// 5: The request is rejected. Possible reasons include the following:The RtcEngine initialization fails. Reinitialize the RtcEngine.The channel name is set as the empty string "" when joining the channel. Reset the channel name.When the joinChannelEx method is called to join multiple channels, the specified channel name is already in use. Reset the channel name. + /// 5: The request is rejected. Possible reasons include the following: + /// The RtcEngine initialization fails. Reinitialize the RtcEngine. + /// The channel name is set as the empty string "" when joining the channel. Reset the channel name. + /// When the joinChannelEx method is called to join multiple channels, the specified channel name is already in use. Reset the channel name. @JsonValue(5) errRefused, @@ -244,11 +253,15 @@ enum ErrorCodeType { @JsonValue(14) errNetDown, - /// 17: The request to join the channel is rejected. Possible reasons include the following:The user is already in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the connectionStateDisconnected(1) state.After calling startEchoTest for the call test, the user tries to join the channel without calling stopEchoTest to end the current test. To join a channel, the call test must be ended by calling stopEchoTest. + /// 17: The request to join the channel is rejected. Possible reasons include the following: + /// The user is already in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the connectionStateDisconnected (1) state. + /// After calling startEchoTest for the call test, the user tries to join the channel without calling stopEchoTest to end the current test. To join a channel, the call test must be ended by calling stopEchoTest. @JsonValue(17) errJoinChannelRejected, - /// 18: Fails to leave the channel. Possible reasons include the following:The user has left the channel before calling the leaveChannel method. Stop calling this method to clear this error.The user calls the leaveChannel method to leave the channel before joining the channel. In this case, no extra operation is needed. + /// 18: Fails to leave the channel. Possible reasons include the following: + /// The user has left the channel before calling the leaveChannel method. Stop calling this method to clear this error. + /// The user calls the leaveChannel method to leave the channel before joining the channel. In this case, no extra operation is needed. @JsonValue(18) errLeaveChannelRejected, @@ -280,11 +293,13 @@ enum ErrorCodeType { @JsonValue(103) errNoServerResources, - /// 109: The current token has expired. Apply for a new token on the server and call renewToken.Deprecated:This enumerator is deprecated. Use connectionChangedTokenExpired(9) in the onConnectionStateChanged callback instead. + /// 109: The current token has expired. Apply for a new token on the server and call renewToken. Deprecated: This enumerator is deprecated. Use connectionChangedTokenExpired (9) in the onConnectionStateChanged callback instead. @JsonValue(109) errTokenExpired, - /// 110: Invalid token. Typical reasons include the following:App Certificate is enabled in Agora Console, but the code still uses App ID for authentication. Once App Certificate is enabled for a project, you must use token-based authentication.The uid used to generate the token is not the same as the uid used to join the channel.Deprecated:This enumerator is deprecated. Use connectionChangedInvalidToken(8) in the onConnectionStateChanged callback instead. + /// 110: Invalid token. Typical reasons include the following: + /// App Certificate is enabled in Agora Console, but the code still uses App ID for authentication. Once App Certificate is enabled for a project, you must use token-based authentication. + /// The uid used to generate the token is not the same as the uid used to join the channel. Deprecated: This enumerator is deprecated. Use connectionChangedInvalidToken (8) in the onConnectionStateChanged callback instead. @JsonValue(110) errInvalidToken, @@ -543,7 +558,7 @@ enum UserOfflineReasonType { @JsonValue(0) userOfflineQuit, - /// 1: The SDK times out and the user drops offline because no data packet is received within a certain period of time.If the user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user dropped offline. + /// 1: The SDK times out and the user drops offline because no data packet is received within a certain period of time. If the user quits the call and the message is not passed to the SDK (due to an unreliable channel), the SDK assumes the user dropped offline. @JsonValue(1) userOfflineDropped, @@ -596,7 +611,7 @@ enum InterfaceIdType { @JsonValue(7) agoraIidRtcConnection, - /// This interface class is deprecated. + /// @nodoc @JsonValue(8) agoraIidSignalingEngine, @@ -780,7 +795,7 @@ enum FrameRate { @JsonValue(30) frameRateFps30, - /// 60: 60 fpsFor Windows and macOS only. + /// 60: 60 fps For Windows and macOS only. @JsonValue(60) frameRateFps60, } @@ -884,7 +899,9 @@ extension VideoFrameTypeExt on VideoFrameType { /// Video output orientation mode. @JsonEnum(alwaysCreate: true) enum OrientationMode { - /// 0: (Default) The output video always follows the orientation of the captured video. The receiver takes the rotational information passed on from the video encoder. This mode applies to scenarios where video orientation can be adjusted on the receiver.If the captured video is in landscape mode, the output video is in landscape mode.If the captured video is in portrait mode, the output video is in portrait mode. + /// 0: (Default) The output video always follows the orientation of the captured video. The receiver takes the rotational information passed on from the video encoder. This mode applies to scenarios where video orientation can be adjusted on the receiver. + /// If the captured video is in landscape mode, the output video is in landscape mode. + /// If the captured video is in portrait mode, the output video is in portrait mode. @JsonValue(0) orientationModeAdaptive, @@ -921,7 +938,7 @@ enum DegradationPreference { @JsonValue(1) maintainFramerate, - /// 2: Reduces the video frame rate and video resolution simultaneously during video encoding under limited bandwidth. The maintainBalanced has a lower reduction than maintainQuality and maintainFramerate, and this preference is suitable for scenarios where both smoothness and video quality are a priority.The resolution of the video sent may change, so remote users need to handle this issue. See onVideoSizeChanged. + /// 2: Reduces the video frame rate and video resolution simultaneously during video encoding under limited bandwidth. The maintainBalanced has a lower reduction than maintainQuality and maintainFramerate, and this preference is suitable for scenarios where both smoothness and video quality are a priority. The resolution of the video sent may change, so remote users need to handle this issue. See onVideoSizeChanged. @JsonValue(2) maintainBalanced, @@ -1010,6 +1027,43 @@ extension ScreenCaptureFramerateCapabilityExt } } +/// The level of the codec capability. +@JsonEnum(alwaysCreate: true) +enum VideoCodecCapabilityLevel { + /// -1: Unsupported video type. Currently, only H.264 and H.265 formats are supported. If the video is in another format, this value will be returned. + @JsonValue(-1) + codecCapabilityLevelUnspecified, + + /// 5: Supports encoding and decoding videos up to 1080p and 30 fps. + @JsonValue(5) + codecCapabilityLevelBasicSupport, + + /// 10: Supports encoding and decoding videos up to1080p and 30 fps. + @JsonValue(10) + codecCapabilityLevel1080p30fps, + + /// 20: Support encoding and decoding videos up to 1080p and 60 fps. + @JsonValue(20) + codecCapabilityLevel1080p60fps, + + /// 30: Support encoding and decoding videos up to 4K and 30 fps. + @JsonValue(30) + codecCapabilityLevel4k60fps, +} + +/// @nodoc +extension VideoCodecCapabilityLevelExt on VideoCodecCapabilityLevel { + /// @nodoc + static VideoCodecCapabilityLevel fromValue(int value) { + return $enumDecode(_$VideoCodecCapabilityLevelEnumMap, value); + } + + /// @nodoc + int value() { + return _$VideoCodecCapabilityLevelEnumMap[this]!; + } +} + /// Video codec types. @JsonEnum(alwaysCreate: true) enum VideoCodecType { @@ -1029,7 +1083,7 @@ enum VideoCodecType { @JsonValue(3) videoCodecH265, - /// 6: Generic.This type is used for transmitting raw video data, such as encrypted video frames. The SDK returns this type of video frames in callbacks, and you need to decode and render the frames yourself. + /// 6: Generic. This type is used for transmitting raw video data, such as encrypted video frames. The SDK returns this type of video frames in callbacks, and you need to decode and render the frames yourself. @JsonValue(6) videoCodecGeneric, @@ -1045,7 +1099,7 @@ enum VideoCodecType { @JsonValue(13) videoCodecVp9, - /// 20: Generic JPEG.This type consumes minimum computing resources and applies to IoT devices. + /// 20: Generic JPEG. This type consumes minimum computing resources and applies to IoT devices. @JsonValue(20) videoCodecGenericJpeg, } @@ -1420,7 +1474,7 @@ class VideoSubscriptionOptions { @JsonKey(name: 'type') final VideoStreamType? type; - /// Whether to subscribe to encoded video frames only:true: Subscribe to the encoded video data (structured data) only; the SDK does not decode or render raw video data.false: (Default) Subscribe to both raw video data and encoded video data. + /// Whether to subscribe to encoded video frames only: true : Subscribe to the encoded video data (structured data) only; the SDK does not decode or render raw video data. false : (Default) Subscribe to both raw video data and encoded video data. @JsonKey(name: 'encodedFrameOnly') final bool? encodedFrameOnly; @@ -1461,7 +1515,7 @@ class EncodedVideoFrameInfo { @JsonKey(name: 'height') final int? height; - /// The number of video frames per second.When this parameter is not 0, you can use it to calculate the Unix timestamp of externally encoded video frames. + /// The number of video frames per second. When this parameter is not 0, you can use it to calculate the Unix timestamp of externally encoded video frames. @JsonKey(name: 'framesPerSecond') final int? framesPerSecond; @@ -1580,7 +1634,9 @@ class AdvanceOptions { /// Video mirror mode. @JsonEnum(alwaysCreate: true) enum VideoMirrorModeType { - /// 0: The SDK determines the mirror mode.For the mirror mode of the local video view: If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default.For the remote user: The mirror mode is disabled by default. + /// 0: The SDK determines the mirror mode. + /// For the mirror mode of the local video view: If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default. + /// For the remote user: The mirror mode is disabled by default. @JsonValue(0) videoMirrorModeAuto, @@ -1643,11 +1699,33 @@ extension CodecCapMaskExt on CodecCapMask { } } +/// The level of the codec capability. +@JsonSerializable(explicitToJson: true, includeIfNull: false) +class CodecCapLevels { + /// @nodoc + const CodecCapLevels({this.hwDecodingLevel, this.swDecodingLevel}); + + /// Hardware decoding capability level, which represents the device's ability to perform hardware decoding on videos of different quality. See VideoCodecCapabilityLevel. + @JsonKey(name: 'hwDecodingLevel') + final VideoCodecCapabilityLevel? hwDecodingLevel; + + /// Software decoding capability level, which represents the device's ability to perform software decoding on videos of different quality. See VideoCodecCapabilityLevel. + @JsonKey(name: 'swDecodingLevel') + final VideoCodecCapabilityLevel? swDecodingLevel; + + /// @nodoc + factory CodecCapLevels.fromJson(Map json) => + _$CodecCapLevelsFromJson(json); + + /// @nodoc + Map toJson() => _$CodecCapLevelsToJson(this); +} + /// The codec capability of the device. @JsonSerializable(explicitToJson: true, includeIfNull: false) class CodecCapInfo { /// @nodoc - const CodecCapInfo({this.codecType, this.codecCapMask}); + const CodecCapInfo({this.codecType, this.codecCapMask, this.codecLevels}); /// The video codec types. See VideoCodecType. @JsonKey(name: 'codecType') @@ -1657,6 +1735,10 @@ class CodecCapInfo { @JsonKey(name: 'codecCapMask') final int? codecCapMask; + /// The level of the codec capability. See CodecCapLevels. + @JsonKey(name: 'codecLevels') + final CodecCapLevels? codecLevels; + /// @nodoc factory CodecCapInfo.fromJson(Map json) => _$CodecCapInfoFromJson(json); @@ -1696,7 +1778,7 @@ class VideoEncoderConfiguration { @JsonKey(name: 'bitrate') final int? bitrate; - /// The minimum encoding bitrate (Kbps) of the video.The SDK automatically adjusts the encoding bitrate to adapt to the network conditions. Using a value greater than the default value forces the video encoder to output high-quality images but may cause more packet loss and sacrifice the smoothness of the video transmission. Unless you have special requirements for image quality, Agora does not recommend changing this value.This parameter only applies to the interactive streaming profile. + /// The minimum encoding bitrate (Kbps) of the video. The SDK automatically adjusts the encoding bitrate to adapt to the network conditions. Using a value greater than the default value forces the video encoder to output high-quality images but may cause more packet loss and sacrifice the smoothness of the video transmission. Unless you have special requirements for image quality, Agora does not recommend changing this value. This parameter only applies to the interactive streaming profile. @JsonKey(name: 'minBitrate') final int? minBitrate; @@ -1708,7 +1790,7 @@ class VideoEncoderConfiguration { @JsonKey(name: 'degradationPreference') final DegradationPreference? degradationPreference; - /// Sets the mirror mode of the published local video stream. It only affects the video that the remote user sees. See VideoMirrorModeType.By default, the video is not mirrored. + /// Sets the mirror mode of the published local video stream. It only affects the video that the remote user sees. See VideoMirrorModeType. By default, the video is not mirrored. @JsonKey(name: 'mirrorMode') final VideoMirrorModeType? mirrorMode; @@ -1732,11 +1814,11 @@ class DataStreamConfig { /// @nodoc const DataStreamConfig({this.syncWithAudio, this.ordered}); - /// Whether to synchronize the data packet with the published audio packet.true: Synchronize the data packet with the audio packet.false: Do not synchronize the data packet with the audio packet.When you set the data packet to synchronize with the audio, then if the data packet delay is within the audio delay, the SDK triggers the onStreamMessage callback when the synchronized audio packet is played out. Do not set this parameter as true if you need the receiver to receive the data packet immediately. Agora recommends that you set this parameter to true only when you need to implement specific functions, for example, lyric synchronization. + /// Whether to synchronize the data packet with the published audio packet. true : Synchronize the data packet with the audio packet. false : Do not synchronize the data packet with the audio packet. When you set the data packet to synchronize with the audio, then if the data packet delay is within the audio delay, the SDK triggers the onStreamMessage callback when the synchronized audio packet is played out. Do not set this parameter as true if you need the receiver to receive the data packet immediately. Agora recommends that you set this parameter to true only when you need to implement specific functions, for example, lyric synchronization. @JsonKey(name: 'syncWithAudio') final bool? syncWithAudio; - /// Whether the SDK guarantees that the receiver receives the data in the sent order.true: Guarantee that the receiver receives the data in the sent order.false: Do not guarantee that the receiver receives the data in the sent order.Do not set this parameter as true if you need the receiver to receive the data packet immediately. + /// Whether the SDK guarantees that the receiver receives the data in the sent order. true : Guarantee that the receiver receives the data in the sent order. false : Do not guarantee that the receiver receives the data in the sent order. Do not set this parameter as true if you need the receiver to receive the data packet immediately. @JsonKey(name: 'ordered') final bool? ordered; @@ -1835,7 +1917,9 @@ class Rectangle { /// The position and size of the watermark on the screen. /// -/// The position and size of the watermark on the screen are determined by xRatio , yRatio , and widthRatio : ( xRatio , yRatio ) refers to the coordinates of the upper left corner of the watermark, which determines the distance from the upper left corner of the watermark to the upper left corner of the screen. The widthRatio determines the width of the watermark. +/// The position and size of the watermark on the screen are determined by xRatio, yRatio, and widthRatio : +/// (xRatio, yRatio) refers to the coordinates of the upper left corner of the watermark, which determines the distance from the upper left corner of the watermark to the upper left corner of the screen. +/// The widthRatio determines the width of the watermark. @JsonSerializable(explicitToJson: true, includeIfNull: false) class WatermarkRatio { /// @nodoc @@ -1999,27 +2083,30 @@ class RtcStats { @JsonKey(name: 'userCount') final int? userCount; - /// Application CPU usage (%).The value of cpuAppUsage is always reported as 0 in the onLeaveChannel callback.As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. + /// Application CPU usage (%). + /// The value of cpuAppUsage is always reported as 0 in the onLeaveChannel callback. + /// As of Android 8.1, you cannot get the CPU usage from this attribute due to system limitations. @JsonKey(name: 'cpuAppUsage') final double? cpuAppUsage; - /// The system CPU usage (%).For Windows, in the multi-kernel environment, this member represents the average CPU usage. The value = (100 - System Idle Progress in Task Manager)/100.The value of cpuTotalUsage is always reported as 0 in the onLeaveChannel callback. + /// The system CPU usage (%). For Windows, in the multi-kernel environment, this member represents the average CPU usage. The value = (100 - System Idle Progress in Task Manager)/100. + /// The value of cpuTotalUsage is always reported as 0 in the onLeaveChannel callback. @JsonKey(name: 'cpuTotalUsage') final double? cpuTotalUsage; - /// The round-trip time delay (ms) from the client to the local router.This property is disabled on devices running iOS 14 or later, and enabled on devices running versions earlier than iOS 14 by default. To enable this property on devices running iOS 14 or later, .On Android, to get gatewayRtt, ensure that you add the android.permission.ACCESS_WIFI_STATE permission after in the AndroidManifest.xml file in your project. + /// The round-trip time delay (ms) from the client to the local router. This property is disabled on devices running iOS 14 or later, and enabled on devices running versions earlier than iOS 14 by default. To enable this property on devices running iOS 14 or later,. On Android, to get gatewayRtt, ensure that you add the android.permission.ACCESS_WIFI_STATE permission after in the AndroidManifest.xml file in your project. @JsonKey(name: 'gatewayRtt') final int? gatewayRtt; - /// The memory ratio occupied by the app (%).This value is for reference only. Due to system limitations, you may not get this value. + /// The memory ratio occupied by the app (%). This value is for reference only. Due to system limitations, you may not get this value. @JsonKey(name: 'memoryAppUsageRatio') final double? memoryAppUsageRatio; - /// The memory occupied by the system (%).This value is for reference only. Due to system limitations, you may not get this value. + /// The memory occupied by the system (%). This value is for reference only. Due to system limitations, you may not get this value. @JsonKey(name: 'memoryTotalUsageRatio') final double? memoryTotalUsageRatio; - /// The memory size occupied by the app (KB).This value is for reference only. Due to system limitations, you may not get this value. + /// The memory size occupied by the app (KB). This value is for reference only. Due to system limitations, you may not get this value. @JsonKey(name: 'memoryAppUsageInKbytes') final int? memoryAppUsageInKbytes; @@ -2270,7 +2357,10 @@ extension AudioAinsModeExt on AudioAinsMode { /// The audio profile. @JsonEnum(alwaysCreate: true) enum AudioProfileType { - /// 0: The default audio profile.For the interactive streaming profile: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps.For the communication profile: Windows: A sample rate of 16 kHz, audio encoding, mono, and a bitrate of up to 16 Kbps.Android/macOS/iOS: + /// 0: The default audio profile. + /// For the interactive streaming profile: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps. + /// For the communication profile: + /// Windows: A sample rate of 16 kHz, audio encoding, mono, and a bitrate of up to 16 Kbps. Android/macOS/iOS: A sample rate of 32 kHz, audio encoding, mono, and a bitrate of up to 18 Kbps. @JsonValue(0) audioProfileDefault, @@ -2282,7 +2372,7 @@ enum AudioProfileType { @JsonValue(2) audioProfileMusicStandard, - /// 3: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 80 Kbps.To implement stereo audio, you also need to call setAdvancedAudioOptions and set audioProcessingChannels to audioProcessingStereo in AdvancedAudioOptions. + /// 3: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 80 Kbps. To implement stereo audio, you also need to call setAdvancedAudioOptions and set audioProcessingChannels to audioProcessingStereo in AdvancedAudioOptions. @JsonValue(3) audioProfileMusicStandardStereo, @@ -2290,7 +2380,7 @@ enum AudioProfileType { @JsonValue(4) audioProfileMusicHighQuality, - /// 5: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 128 Kbps.To implement stereo audio, you also need to call setAdvancedAudioOptions and set audioProcessingChannels to audioProcessingStereo in AdvancedAudioOptions. + /// 5: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 128 Kbps. To implement stereo audio, you also need to call setAdvancedAudioOptions and set audioProcessingChannels to audioProcessingStereo in AdvancedAudioOptions. @JsonValue(5) audioProfileMusicHighQualityStereo, @@ -2452,7 +2542,20 @@ enum VideoApplicationScenarioType { @JsonValue(0) applicationScenarioGeneral, - /// If set to applicationScenarioMeeting (1), the SDK automatically enables the following strategies:In meeting scenarios where low-quality video streams are required to have a high bitrate, the SDK automatically enables multiple technologies used to deal with network congestions, to enhance the performance of the low-quality streams and to ensure the smooth reception by subscribers.The SDK monitors the number of subscribers to the high-quality video stream in real time and dynamically adjusts its configuration based on the number of subscribers.If nobody subscribers to the high-quality stream, the SDK automatically reduces its bitrate and frame rate to save upstream bandwidth.If someone subscribes to the high-quality stream, the SDK resets the high-quality stream to the VideoEncoderConfiguration configuration used in the most recent calling of setVideoEncoderConfiguration. If no configuration has been set by the user previously, the following values are used:Resolution: (Windows and macOS) 1280 × 720; (Android and iOS) 960 × 540Frame rate: 15 fpsBitrate: (Windows and macOS) 1600 Kbps; (Android and iOS) 1000 KbpsThe SDK monitors the number of subscribers to the low-quality video stream in real time and dynamically enables or disables it based on the number of subscribers.If the user has called setDualStreamMode to set that never send low-quality video stream (disableSimulcastStream), the dynamic adjustment of the low-quality stream in meeting scenarios will not take effect.If nobody subscribes to the low-quality stream, the SDK automatically disables it to save upstream bandwidth.If someone subscribes to the low-quality stream, the SDK enables the low-quality stream and resets it to the SimulcastStreamConfig configuration used in the most recent calling of setDualStreamMode. If no configuration has been set by the user previously, the following values are used:Resolution: 480 × 272Frame rate: 15 fpsBitrate: 500 Kbps1: The meeting scenario. + /// If set to applicationScenarioMeeting (1), the SDK automatically enables the following strategies: + /// In meeting scenarios where low-quality video streams are required to have a high bitrate, the SDK automatically enables multiple technologies used to deal with network congestions, to enhance the performance of the low-quality streams and to ensure the smooth reception by subscribers. + /// The SDK monitors the number of subscribers to the high-quality video stream in real time and dynamically adjusts its configuration based on the number of subscribers. + /// If nobody subscribers to the high-quality stream, the SDK automatically reduces its bitrate and frame rate to save upstream bandwidth. + /// If someone subscribes to the high-quality stream, the SDK resets the high-quality stream to the VideoEncoderConfiguration configuration used in the most recent calling of setVideoEncoderConfiguration. If no configuration has been set by the user previously, the following values are used: + /// Resolution: (Windows and macOS) 1280 × 720; (Android and iOS) 960 × 540 + /// Frame rate: 15 fps + /// Bitrate: (Windows and macOS) 1600 Kbps; (Android and iOS) 1000 Kbps + /// The SDK monitors the number of subscribers to the low-quality video stream in real time and dynamically enables or disables it based on the number of subscribers. If the user has called setDualStreamMode to set that never send low-quality video stream (disableSimulcastStream), the dynamic adjustment of the low-quality stream in meeting scenarios will not take effect. + /// If nobody subscribes to the low-quality stream, the SDK automatically disables it to save upstream bandwidth. + /// If someone subscribes to the low-quality stream, the SDK enables the low-quality stream and resets it to the SimulcastStreamConfig configuration used in the most recent calling of setDualStreamMode. If no configuration has been set by the user previously, the following values are used: + /// Resolution: 480 × 272 + /// Frame rate: 15 fps + /// Bitrate: 500 Kbps 1: The meeting scenario. @JsonValue(1) applicationScenarioMeeting, } @@ -2547,7 +2650,7 @@ enum LocalAudioStreamError { @JsonValue(1) localAudioStreamErrorFailure, - /// 2: No permission to use the local audio capturing device. Remind your users to grant permission.Deprecated:This enumerator is deprecated. Please use recordAudio in the onPermissionError callback instead. + /// 2: No permission to use the local audio capturing device. Remind your users to grant permission. Deprecated: This enumerator is deprecated. Please use recordAudio in the onPermissionError callback instead. @JsonValue(2) localAudioStreamErrorDeviceNoPermission, @@ -2641,7 +2744,7 @@ enum LocalVideoStreamError { @JsonValue(1) localVideoStreamErrorFailure, - /// 2: No permission to use the local video capturing device. Remind the user to grant permissions and rejoin the channel.Deprecated:This enumerator is deprecated. Please use camera in the onPermissionError callback instead. + /// 2: No permission to use the local video capturing device. Remind the user to grant permissions and rejoin the channel. Deprecated: This enumerator is deprecated. Please use camera in the onPermissionError callback instead. @JsonValue(2) localVideoStreamErrorDeviceNoPermission, @@ -2669,7 +2772,7 @@ enum LocalVideoStreamError { @JsonValue(8) localVideoStreamErrorDeviceNotFound, - /// 9:(For macOS only) The video capture device currently in use is disconnected (such as being unplugged). + /// 9: (For macOS only) The video capture device currently in use is disconnected (such as being unplugged). @JsonValue(9) localVideoStreamErrorDeviceDisconnected, @@ -2685,7 +2788,10 @@ enum LocalVideoStreamError { @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: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. + /// 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: + /// 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, @@ -2897,7 +3003,7 @@ enum RemoteVideoStateReason { @JsonValue(12) remoteVideoStateReasonSdkInBackground, - /// @nodoc + /// 13: The local video decoder does not support decoding the remote video stream. @JsonValue(13) remoteVideoStateReasonCodecNotSupport, } @@ -3050,7 +3156,9 @@ class AudioVolumeInfo { /// @nodoc const AudioVolumeInfo({this.uid, this.volume, this.vad, this.voicePitch}); - /// The user ID.In the local user's callback, uid is 0.In the remote users' callback, uid is the user ID of a remote user whose instantaneous volume is the highest. + /// The user ID. + /// In the local user's callback, uid is 0. + /// In the remote users' callback, uid is the user ID of a remote user whose instantaneous volume is the highest. @JsonKey(name: 'uid') final int? uid; @@ -3058,11 +3166,15 @@ class AudioVolumeInfo { @JsonKey(name: 'volume') final int? volume; - /// Voice activity status of the local user.0: The local user is not speaking.1: The local user is speaking.The vad parameter does not report the voice activity status of remote users. In a remote user's callback, the value of vad is always 1.To use this parameter, you must set reportVad to true when calling enableAudioVolumeIndication. + /// Voice activity status of the local user. + /// 0: The local user is not speaking. + /// 1: The local user is speaking. + /// The vad parameter does not report the voice activity status of remote users. In a remote user's callback, the value of vad is always 1. + /// To use this parameter, you must set reportVad to true when calling enableAudioVolumeIndication. @JsonKey(name: 'vad') final int? vad; - /// The voice pitch of the local user. The value ranges between 0.0 and 4000.0.The voicePitch parameter does not report the voice pitch of remote users. In the remote users' callback, the value of voicePitch is always 0.0. + /// The voice pitch of the local user. The value ranges between 0.0 and 4000.0. The voicePitch parameter does not report the voice pitch of remote users. In the remote users' callback, the value of voicePitch is always 0.0. @JsonKey(name: 'voicePitch') final double? voicePitch; @@ -3082,7 +3194,7 @@ class DeviceInfo { /// @nodoc const DeviceInfo({this.isLowLatencyAudioSupported}); - /// Whether the audio device supports ultra-low-latency capture and playback:true: The device supports ultra-low-latency capture and playback.false: The device does not support ultra-low-latency capture and playback. + /// Whether the audio device supports ultra-low-latency capture and playback: true : The device supports ultra-low-latency capture and playback. false : The device does not support ultra-low-latency capture and playback. @JsonKey(name: 'isLowLatencyAudioSupported') final bool? isLowLatencyAudioSupported; @@ -3286,7 +3398,9 @@ enum RtmpStreamPublishState { @JsonValue(2) rtmpStreamPublishStateRunning, - /// 3: The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume RTMP or RTMPS streaming and returns this state.If the SDK successfully resumes the streaming, rtmpStreamPublishStateRunning(2) returns.If the streaming does not resume within 60 seconds or server errors occur, rtmpStreamPublishStateFailure(4) returns. If you feel that 60 seconds is too long, you can also actively try to reconnect. + /// 3: The RTMP or RTMPS streaming is recovering. When exceptions occur to the CDN, or the streaming is interrupted, the SDK tries to resume RTMP or RTMPS streaming and returns this state. + /// If the SDK successfully resumes the streaming, rtmpStreamPublishStateRunning (2) returns. + /// If the streaming does not resume within 60 seconds or server errors occur, rtmpStreamPublishStateFailure (4) returns. If you feel that 60 seconds is too long, you can also actively try to reconnect. @JsonValue(3) rtmpStreamPublishStateRecovering, @@ -3469,7 +3583,9 @@ class RtcImage { @JsonKey(name: 'zOrder') final int? zOrder; - /// The transparency of the watermark or background image. The range of the value is [0.0,1.0]:0.0: Completely transparent.1.0: (Default) Opaque. + /// The transparency of the watermark or background image. The range of the value is [0.0,1.0]: + /// 0.0: Completely transparent. + /// 1.0: (Default) Opaque. @JsonKey(name: 'alpha') final double? alpha; @@ -3483,7 +3599,7 @@ class RtcImage { /// The configuration for advanced features of the RTMP or RTMPS streaming with transcoding. /// -/// If you want to enable the advanced features of streaming with transcoding, contact . +/// If you want to enable the advanced features of streaming with transcoding, contact. @JsonSerializable(explicitToJson: true, includeIfNull: false) class LiveStreamAdvancedFeature { /// @nodoc @@ -3493,7 +3609,7 @@ class LiveStreamAdvancedFeature { @JsonKey(name: 'featureName') final String? featureName; - /// Whether to enable the advanced features of streaming with transcoding:true: Enable the advanced features.false: (Default) Do not enable the advanced features. + /// Whether to enable the advanced features of streaming with transcoding: true : Enable the advanced features. false : (Default) Do not enable the advanced features. @JsonKey(name: 'opened') final bool? opened; @@ -3508,11 +3624,15 @@ class LiveStreamAdvancedFeature { /// Connection states. @JsonEnum(alwaysCreate: true) enum ConnectionStateType { - /// 1: The SDK is disconnected from the Agora edge server. The state indicates the SDK is in one of the following phases:Theinitial state before calling the joinChannel method.The app calls the leaveChannel method. + /// 1: The SDK is disconnected from the Agora edge server. The state indicates the SDK is in one of the following phases: + /// Theinitial state before calling the joinChannel method. + /// The app calls the leaveChannel method. @JsonValue(1) connectionStateDisconnected, - /// 2: The SDK is connecting to the Agora edge server. This state indicates that the SDK is establishing a connection with the specified channel after the app calls joinChannel.If the SDK successfully joins the channel, it triggers the onConnectionStateChanged callback and the connection state switches to connectionStateConnected.After the connection is established, the SDK also initializes the media and triggers onJoinChannelSuccess when everything is ready. + /// 2: The SDK is connecting to the Agora edge server. This state indicates that the SDK is establishing a connection with the specified channel after the app calls joinChannel. + /// If the SDK successfully joins the channel, it triggers the onConnectionStateChanged callback and the connection state switches to connectionStateConnected. + /// After the connection is established, the SDK also initializes the media and triggers onJoinChannelSuccess when everything is ready. @JsonValue(2) connectionStateConnecting, @@ -3520,11 +3640,15 @@ enum ConnectionStateType { @JsonValue(3) connectionStateConnected, - /// 4: The SDK keeps reconnecting to the Agora edge server. The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues.If the SDK cannot rejoin the channel within 10 seconds, it triggers onConnectionLost, stays in the connectionStateReconnecting state, and keeps rejoining the channel.If the SDK fails to rejoin the channel 20 minutes after being disconnected from the Agora edge server, the SDK triggers the onConnectionStateChanged callback, switches to the connectionStateFailed state, and stops rejoining the channel. + /// 4: The SDK keeps reconnecting to the Agora edge server. The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues. + /// If the SDK cannot rejoin the channel within 10 seconds, it triggers onConnectionLost, stays in the connectionStateReconnecting state, and keeps rejoining the channel. + /// If the SDK fails to rejoin the channel 20 minutes after being disconnected from the Agora edge server, the SDK triggers the onConnectionStateChanged callback, switches to the connectionStateFailed state, and stops rejoining the channel. @JsonValue(4) connectionStateReconnecting, - /// 5: The SDK fails to connect to the Agora edge server or join the channel. This state indicates that the SDK stops trying to rejoin the channel. You must call leaveChannel to leave the channel.You can call joinChannel to rejoin the channel.If the SDK is banned from joining the channel by the Agora edge server through the RESTful API, the SDK triggers the onConnectionStateChanged callback. + /// 5: The SDK fails to connect to the Agora edge server or join the channel. This state indicates that the SDK stops trying to rejoin the channel. You must call leaveChannel to leave the channel. + /// You can call joinChannel to rejoin the channel. + /// If the SDK is banned from joining the channel by the Agora edge server through the RESTful API, the SDK triggers the onConnectionStateChanged callback. @JsonValue(5) connectionStateFailed, } @@ -3576,15 +3700,21 @@ class TranscodingUser { @JsonKey(name: 'height') final int? height; - /// The layer index number of the host's video. The value range is [0, 100].0: (Default) The host's video is the bottom layer.100: The host's video is the top layer.If the value is less than 0 or greater than 100, errInvalidArgument error is returned.Setting zOrder to 0 is supported. + /// The layer index number of the host's video. The value range is [0, 100]. + /// 0: (Default) The host's video is the bottom layer. + /// 100: The host's video is the top layer. + /// If the value is less than 0 or greater than 100, errInvalidArgument error is returned. + /// Setting zOrder to 0 is supported. @JsonKey(name: 'zOrder') final int? zOrder; - /// The transparency of the host's video. The value range is [0.0,1.0].0.0: Completely transparent.1.0: (Default) Opaque. + /// The transparency of the host's video. The value range is [0.0,1.0]. + /// 0.0: Completely transparent. + /// 1.0: (Default) Opaque. @JsonKey(name: 'alpha') final double? alpha; - /// The audio channel used by the host's audio in the output audio. The default value is 0, and the value range is [0, 5].0: (Recommended) The defaut setting, which supports dual channels at most and depends on the upstream of the host.1: The host's audio uses the FL audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.2: The host's audio uses the FC audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.3: The host's audio uses the FR audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.4: The host's audio uses the BL audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.5: The host's audio uses the BR audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first.0xFF or a value greater than 5: The host's audio is muted, and the Agora server removes the host's audio.If the value is not 0, a special player is required. + /// The audio channel used by the host's audio in the output audio. The default value is 0, and the value range is [0, 5]. 0 : (Recommended) The defaut setting, which supports dual channels at most and depends on the upstream of the host. 1 : The host's audio uses the FL audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first. 2 : The host's audio uses the FC audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first. 3 : The host's audio uses the FR audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first. 4 : The host's audio uses the BL audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first. 5 : The host's audio uses the BR audio channel. If the host's upstream uses multiple audio channels, the Agora server mixes them into mono first. 0xFF or a value greater than 5 : The host's audio is muted, and the Agora server removes the host's audio. If the value is not 0, a special player is required. @JsonKey(name: 'audioChannel') final int? audioChannel; @@ -3625,11 +3755,15 @@ class LiveTranscoding { this.advancedFeatures, this.advancedFeatureCount}); - /// The width of the video in pixels. The default value is 360.When pushing video streams to the CDN, the value range of width is [64,1920]. If the value is less than 64, Agora server automatically adjusts it to 64; if the value is greater than 1920, Agora server automatically adjusts it to 1920.When pushing audio streams to the CDN, set width and height as 0. + /// The width of the video in pixels. The default value is 360. + /// When pushing video streams to the CDN, the value range of width is [64,1920]. If the value is less than 64, Agora server automatically adjusts it to 64; if the value is greater than 1920, Agora server automatically adjusts it to 1920. + /// When pushing audio streams to the CDN, set width and height as 0. @JsonKey(name: 'width') final int? width; - /// The height of the video in pixels. The default value is 640.When pushing video streams to the CDN, the value range of height is [64,1080]. If the value is less than 64, Agora server automatically adjusts it to 64; if the value is greater than 1080, Agora server automatically adjusts it to 1080.When pushing audio streams to the CDN, set width and height as 0. + /// The height of the video in pixels. The default value is 640. + /// When pushing video streams to the CDN, the value range of height is [64,1080]. If the value is less than 64, Agora server automatically adjusts it to 64; if the value is greater than 1080, Agora server automatically adjusts it to 1080. + /// When pushing audio streams to the CDN, set width and height as 0. @JsonKey(name: 'height') final int? height; @@ -3637,11 +3771,11 @@ class LiveTranscoding { @JsonKey(name: 'videoBitrate') final int? videoBitrate; - /// Frame rate (fps) of the output video stream set for Media Push. The default value is 15. The value range is (0,30].The Agora server adjusts any value over 30 to 30. + /// Frame rate (fps) of the output video stream set for Media Push. The default value is 15. The value range is (0,30]. The Agora server adjusts any value over 30 to 30. @JsonKey(name: 'videoFramerate') final int? videoFramerate; - /// DeprecatedThis member is deprecated.Latency mode:true: Low latency with unassured quality.false: (Default) High latency with assured quality. + /// Deprecated This member is deprecated. Latency mode: true : Low latency with unassured quality. false : (Default) High latency with assured quality. @JsonKey(name: 'lowLatency') final bool? lowLatency; @@ -3649,7 +3783,7 @@ class LiveTranscoding { @JsonKey(name: 'videoGop') final int? videoGop; - /// Video codec profile type for Media Push. Set it as 66, 77, or 100 (default). See VideoCodecProfileType for details.If you set this parameter to any other value, Agora adjusts it to the default value. + /// Video codec profile type for Media Push. Set it as 66, 77, or 100 (default). See VideoCodecProfileType for details. If you set this parameter to any other value, Agora adjusts it to the default value. @JsonKey(name: 'videoCodecProfile') final VideoCodecProfileType? videoCodecProfile; @@ -3673,11 +3807,11 @@ class LiveTranscoding { @JsonKey(name: 'transcodingExtraInfo') final String? transcodingExtraInfo; - /// DeprecatedObsolete and not recommended for use.The metadata sent to the CDN client. + /// Deprecated Obsolete and not recommended for use. The metadata sent to the CDN client. @JsonKey(name: 'metadata') final String? metadata; - /// The watermark on the live video. The image format needs to be PNG. See RtcImage.You can add one watermark, or add multiple watermarks using an array. + /// The watermark on the live video. The image format needs to be PNG. See RtcImage. You can add one watermark, or add multiple watermarks using an array. @JsonKey(name: 'watermark') final List? watermark; @@ -3685,7 +3819,7 @@ class LiveTranscoding { @JsonKey(name: 'watermarkCount') final int? watermarkCount; - /// The number of background images on the live video. The image format needs to be PNG. See RtcImage.You can add a background image or use an array to add multiple background images. This parameter is used with backgroundImageCount. + /// The number of background images on the live video. The image format needs to be PNG. See RtcImage. You can add a background image or use an array to add multiple background images. This parameter is used with backgroundImageCount. @JsonKey(name: 'backgroundImage') final List? backgroundImage; @@ -3701,7 +3835,12 @@ class LiveTranscoding { @JsonKey(name: 'audioBitrate') final int? audioBitrate; - /// The number of audio channels for Media Push. Agora recommends choosing 1 (mono), or 2 (stereo) audio channels. Special players are required if you choose 3, 4, or 5.1: (Default) Mono2: Stereo.3: Three audio channels.4: Four audio channels.5: Five audio channels. + /// The number of audio channels for Media Push. Agora recommends choosing 1 (mono), or 2 (stereo) audio channels. Special players are required if you choose 3, 4, or 5. + /// 1: (Default) Mono + /// 2: Stereo. + /// 3: Three audio channels. + /// 4: Four audio channels. + /// 5: Five audio channels. @JsonKey(name: 'audioChannels') final int? audioChannels; @@ -3746,11 +3885,11 @@ class TranscodingVideoStream { @JsonKey(name: 'sourceType') final VideoSourceType? sourceType; - /// The user ID of the remote user.Use this parameter only when the source type is videoSourceRemote for local video mixing. + /// The user ID of the remote user. Use this parameter only when the source type is videoSourceRemote for local video mixing. @JsonKey(name: 'remoteUserUid') final int? remoteUserUid; - /// The URL of the image.Use this parameter only when the source type is the image for local video mixing. + /// The URL of the image. Use this parameter only when the source type is the image for local video mixing. @JsonKey(name: 'imageUrl') final String? imageUrl; @@ -3774,7 +3913,9 @@ class TranscodingVideoStream { @JsonKey(name: 'height') final int? height; - /// The number of the layer to which the video for the local video mixing belongs. The value range is [0, 100].0: (Default) The layer is at the bottom.100: The layer is at the top. + /// The number of the layer to which the video for the local video mixing belongs. The value range is [0, 100]. + /// 0: (Default) The layer is at the bottom. + /// 100: The layer is at the top. @JsonKey(name: 'zOrder') final int? zOrder; @@ -3782,7 +3923,7 @@ class TranscodingVideoStream { @JsonKey(name: 'alpha') final double? alpha; - /// Whether to mirror the video for the local video mixing.true: Mirror the video for the local video mixing.false: (Default) Do not mirror the video for the local video mixing.This parameter only takes effect on video source types that are cameras. + /// Whether to mirror the video for the local video mixing. true : Mirror the video for the local video mixing. false : (Default) Do not mirror the video for the local video mixing. This parameter only takes effect on video source types that are cameras. @JsonKey(name: 'mirror') final bool? mirror; @@ -3883,11 +4024,11 @@ class LastmileProbeConfig { this.expectedUplinkBitrate, this.expectedDownlinkBitrate}); - /// Sets whether to test the uplink network. Some users, for example, the audience members in a LIVE_BROADCASTING channel, do not need such a test.true: Test the uplink network.false: Do not test the uplink network. + /// Sets whether to test the uplink network. Some users, for example, the audience members in a LIVE_BROADCASTING channel, do not need such a test. true : Test the uplink network. false : Do not test the uplink network. @JsonKey(name: 'probeUplink') final bool? probeUplink; - /// Sets whether to test the downlink network:true: Test the downlink network.false: Do not test the downlink network. + /// Sets whether to test the downlink network: true : Test the downlink network. false : Do not test the downlink network. @JsonKey(name: 'probeDownlink') final bool? probeDownlink; @@ -4029,7 +4170,9 @@ enum ConnectionChangedReasonType { @JsonValue(7) connectionChangedInvalidChannelName, - /// 8: The connection failed because the token is not valid. Possible reasons are as follows:The App Certificate for the project is enabled in Agora Console, but you do not use a token when joining the channel. If you enable the App Certificate, you must use a token to join the channel.The uid specified when calling joinChannel to join the channel is inconsistent with the uid passed in when generating the token. + /// 8: The connection failed because the token is not valid. Possible reasons are as follows: + /// The App Certificate for the project is enabled in Agora Console, but you do not use a token when joining the channel. If you enable the App Certificate, you must use a token to join the channel. + /// The uid specified when calling joinChannel to join the channel is inconsistent with the uid passed in when generating the token. @JsonValue(8) connectionChangedInvalidToken, @@ -4037,7 +4180,9 @@ enum ConnectionChangedReasonType { @JsonValue(9) connectionChangedTokenExpired, - /// 10: The connection is rejected by server. Possible reasons are as follows:The user is already in the channel and still calls a method, for example, joinChannel, to join the channel. Stop calling this method to clear this error.The user tries to join a channel while a test call is in progress. The user needs to join the channel after the call test ends. + /// 10: The connection is rejected by server. Possible reasons are as follows: + /// The user is already in the channel and still calls a method, for example, joinChannel, to join the channel. Stop calling this method to clear this error. + /// The user tries to join a channel while a test call is in progress. The user needs to join the channel after the call test ends. @JsonValue(10) connectionChangedRejectedByServer, @@ -4102,7 +4247,7 @@ extension ConnectionChangedReasonTypeExt on ConnectionChangedReasonType { /// The reason for a user role switch failure. @JsonEnum(alwaysCreate: true) enum ClientRoleChangeFailedReason { - /// 1: The number of hosts in the channel is already at the upper limit.This enumerator is reported only when the support for 128 users is enabled. The maximum number of hosts is based on the actual number of hosts configured when you enable the 128-user feature. + /// 1: The number of hosts in the channel is already at the upper limit. This enumerator is reported only when the support for 128 users is enabled. The maximum number of hosts is based on the actual number of hosts configured when you enable the 128-user feature. @JsonValue(1) clientRoleChangeFailedTooManyBroadcasters, @@ -4302,6 +4447,7 @@ class VideoCanvas { const VideoCanvas( {this.view, this.uid, + this.backgroundColor, this.renderMode, this.mirrorMode, this.setupMode, @@ -4310,7 +4456,7 @@ class VideoCanvas { this.cropArea, this.enableAlphaMask}); - /// Video display window. + /// The video display window. @JsonKey(name: 'view') final int? view; @@ -4318,11 +4464,17 @@ class VideoCanvas { @JsonKey(name: 'uid') final int? uid; + /// The background color of the video canvas in RGBA format. The default value is 0x00000000, which represents completely transparent black. + @JsonKey(name: 'backgroundColor') + final int? backgroundColor; + /// The rendering mode of the video. See RenderModeType. @JsonKey(name: 'renderMode') final RenderModeType? renderMode; - /// The mirror mode of the view. See VideoMirrorModeType.For the mirror mode of the local video view: If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default.For the remote user: The mirror mode is disabled by default. + /// The mirror mode of the view. See VideoMirrorModeType. + /// For the mirror mode of the local video view: If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default. + /// For the remote user: The mirror mode is disabled by default. @JsonKey(name: 'mirrorMode') final VideoMirrorModeType? mirrorMode; @@ -4342,7 +4494,10 @@ class VideoCanvas { @JsonKey(name: 'cropArea') final Rectangle? cropArea; - /// (Optional) Whether the receiver enables alpha mask rendering:true: The receiver enables alpha mask rendering.false: (default) The receiver disables alpha mask rendering.Alpha mask rendering can create images with transparent effects and extract portraits from videos. When used in combination with other methods, you can implement effects such as picture-in-picture and watermarking.This property applies to macOS only.The receiver can render alpha channel information only when the sender enables alpha transmission.To enable alpha transmission, . + /// (Optional) Whether the receiver enables alpha mask rendering: true : The receiver enables alpha mask rendering. false : (default) The receiver disables alpha mask rendering. Alpha mask rendering can create images with transparent effects and extract portraits from videos. When used in combination with other methods, you can implement effects such as picture-in-picture and watermarking. + /// This property applies to macOS only. + /// The receiver can render alpha channel information only when the sender enables alpha transmission. + /// To enable alpha transmission,. @JsonKey(name: 'enableAlphaMask') final bool? enableAlphaMask; @@ -4580,7 +4735,9 @@ class ColorEnhanceOptions { @JsonKey(name: 'strengthLevel') final double? strengthLevel; - /// The level of skin tone protection. The value range is [0.0, 1.0]. 0.0 means no skin tone protection. The higher the value, the higher the level of skin tone protection. The default value is 1.0.When the level of color enhancement is higher, the portrait skin tone can be significantly distorted, so you need to set the level of skin tone protection.When the level of skin tone protection is higher, the color enhancement effect can be slightly reduced.Therefore, to get the best color enhancement effect, Agora recommends that you adjust strengthLevel and skinProtectLevel to get the most appropriate values. + /// The level of skin tone protection. The value range is [0.0, 1.0]. 0.0 means no skin tone protection. The higher the value, the higher the level of skin tone protection. The default value is 1.0. + /// When the level of color enhancement is higher, the portrait skin tone can be significantly distorted, so you need to set the level of skin tone protection. + /// When the level of skin tone protection is higher, the color enhancement effect can be slightly reduced. Therefore, to get the best color enhancement effect, Agora recommends that you adjust strengthLevel and skinProtectLevel to get the most appropriate values. @JsonKey(name: 'skinProtectLevel') final double? skinProtectLevel; @@ -4603,11 +4760,11 @@ class VirtualBackgroundSource { @JsonKey(name: 'background_source_type') final BackgroundSourceType? backgroundSourceType; - /// The type of the custom background image. The color of the custom background image. The format is a hexadecimal integer defined by RGB, without the # sign, such as 0xFFB6C1 for light pink. The default value is 0xFFFFFF, which signifies white. The value range is [0x000000, 0xffffff]. If the value is invalid, the SDK replaces the original background image with a white background image.This parameter takes effect only when the type of the custom background image is backgroundColor. + /// The type of the custom background image. The color of the custom background image. The format is a hexadecimal integer defined by RGB, without the # sign, such as 0xFFB6C1 for light pink. The default value is 0xFFFFFF, which signifies white. The value range is [0x000000, 0xffffff]. If the value is invalid, the SDK replaces the original background image with a white background image. This parameter takes effect only when the type of the custom background image is backgroundColor. @JsonKey(name: 'color') final int? color; - /// The local absolute path of the custom background image. PNG and JPG formats are supported. If the path is invalid, the SDK replaces the original background image with a white background image.This parameter takes effect only when the type of the custom background image is backgroundImg. + /// The local absolute path of the custom background image. PNG and JPG formats are supported. If the path is invalid, the SDK replaces the original background image with a white background image. This parameter takes effect only when the type of the custom background image is backgroundImg. @JsonKey(name: 'source') final String? source; @@ -4699,7 +4856,7 @@ class SegmentationProperty { @JsonKey(name: 'modelType') final SegModelType? modelType; - /// The range of accuracy for identifying green colors (different shades of green) in the view. The value range is [0,1], and the default value is 0.5. The larger the value, the wider the range of identifiable shades of green. When the value of this parameter is too large, the edge of the portrait and the green color in the portrait range are also detected. Agora recommends that you dynamically adjust the value of this parameter according to the actual effect.This parameter only takes effect when modelType is set to segModelGreen. + /// The range of accuracy for identifying green colors (different shades of green) in the view. The value range is [0,1], and the default value is 0.5. The larger the value, the wider the range of identifiable shades of green. When the value of this parameter is too large, the edge of the portrait and the green color in the portrait range are also detected. Agora recommends that you dynamically adjust the value of this parameter according to the actual effect. This parameter only takes effect when modelType is set to segModelGreen. @JsonKey(name: 'greenCapacity') final double? greenCapacity; @@ -4743,11 +4900,11 @@ enum AudioTrackType { @JsonValue(-1) audioTrackInvalid, - /// 0: Mixable audio tracks. You can publish multiple mixable audio tracks in one channel, and SDK will automatically mix these tracks into one. The latency of mixable audio tracks is higher than that of direct audio tracks. + /// 0: Mixable audio tracks. This type of audio track supports mixing with other audio streams (such as audio streams captured by microphone) and playing locally or publishing to channels after mixing. The latency of mixable audio tracks is higher than that of direct audio tracks. @JsonValue(0) audioTrackMixable, - /// 1: Direct audio tracks. When creating multiple audio tracks of this type, each direct audio track can only be published in one channel and cannot be mixed with others. The latency of direct audio tracks is lower than that of mixable audio tracks. + /// 1: Direct audio tracks. This type of audio track will replace the audio streams captured by the microphone and does not support mixing with other audio streams. The latency of direct audio tracks is lower than that of mixable audio tracks. If audioTrackDirect is specified for this parameter, you must set publishMicrophoneTrack to false in ChannelMediaOptions when calling joinChannel to join the channel; otherwise, joining the channel fails and returns the error code -2. @JsonValue(1) audioTrackDirect, } @@ -4771,7 +4928,7 @@ class AudioTrackConfig { /// @nodoc const AudioTrackConfig({this.enableLocalPlayback}); - /// Whether to enable the local audio-playback device:true: (Default) Enable the local audio-playback device.false: Do not enable the local audio-playback device. + /// Whether to enable the local audio-playback device: true : (Default) Enable the local audio-playback device. false : Do not enable the local audio-playback device. @JsonKey(name: 'enableLocalPlayback') final bool? enableLocalPlayback; @@ -4790,19 +4947,21 @@ enum VoiceBeautifierPreset { @JsonValue(0x00000000) voiceBeautifierOff, - /// A more magnetic voice.Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may experience vocal distortion. + /// A more magnetic voice. Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may experience vocal distortion. @JsonValue(0x01010100) chatBeautifierMagnetic, - /// A fresher voice.Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. + /// A fresher voice. Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. @JsonValue(0x01010200) chatBeautifierFresh, - /// A more vital voice.Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. + /// A more vital voice. Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. @JsonValue(0x01010300) chatBeautifierVitality, - /// Singing beautifier effect.If you call setVoiceBeautifierPreset(singingBeautifier), you can beautify a male-sounding voice and add a reverberation effect that sounds like singing in a small room. Agora recommends using this enumerator to process a male-sounding voice; otherwise, you might experience vocal distortion.If you call setVoiceBeautifierParameters(singingBeautifier, param1, param2), you can beautify a male or female-sounding voice and add a reverberation effect. + /// Singing beautifier effect. + /// If you call setVoiceBeautifierPreset (singingBeautifier), you can beautify a male-sounding voice and add a reverberation effect that sounds like singing in a small room. Agora recommends using this enumerator to process a male-sounding voice; otherwise, you might experience vocal distortion. + /// If you call setVoiceBeautifierParameters (singingBeautifier, param1, param2), you can beautify a male or female-sounding voice and add a reverberation effect. @JsonValue(0x01020100) singingBeautifier, @@ -4838,7 +4997,9 @@ enum VoiceBeautifierPreset { @JsonValue(0x01030800) timbreTransformationRinging, - /// A ultra-high quality voice, which makes the audio clearer and restores more details.To achieve better audio effect quality, Agora recommends that you set the profile of to audioProfileMusicHighQuality(4) or audioProfileMusicHighQualityStereo(5) and scenario to audioScenarioGameStreaming(3) before calling setVoiceBeautifierPreset.If you have an audio capturing device that can already restore audio details to a high degree, Agora recommends that you do not enable ultra-high quality; otherwise, the SDK may over-restore audio details, and you may not hear the anticipated voice effect. + /// A ultra-high quality voice, which makes the audio clearer and restores more details. + /// To achieve better audio effect quality, Agora recommends that you set the profile of to audioProfileMusicHighQuality (4) or audioProfileMusicHighQualityStereo (5) and scenario to audioScenarioGameStreaming (3) before calling setVoiceBeautifierPreset. + /// If you have an audio capturing device that can already restore audio details to a high degree, Agora recommends that you do not enable ultra-high quality; otherwise, the SDK may over-restore audio details, and you may not hear the anticipated voice effect. @JsonValue(0x01040100) ultraHighQualityVoice, } @@ -4893,31 +5054,31 @@ enum AudioEffectPreset { @JsonValue(0x02010700) roomAcousticsEthereal, - /// A 3D voice effect that makes the voice appear to be moving around the user. The default cycle period is 10 seconds. After setting this effect, you can call setAudioEffectParameters to modify the movement period.If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect. + /// A 3D voice effect that makes the voice appear to be moving around the user. The default cycle period is 10 seconds. After setting this effect, you can call setAudioEffectParameters to modify the movement period. If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect. @JsonValue(0x02010800) roomAcoustics3dVoice, - /// Virtual surround sound, that is, the SDK generates a simulated surround sound field on the basis of stereo channels, thereby creating a surround sound effect.If the virtual surround sound is enabled, users need to use stereo audio playback devices to hear the anticipated audio effect. + /// Virtual surround sound, that is, the SDK generates a simulated surround sound field on the basis of stereo channels, thereby creating a surround sound effect. If the virtual surround sound is enabled, users need to use stereo audio playback devices to hear the anticipated audio effect. @JsonValue(0x02010900) roomAcousticsVirtualSurroundSound, - /// A middle-aged man's voice.Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + /// A middle-aged man's voice. Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. @JsonValue(0x02020100) voiceChangerEffectUncle, - /// An older man's voice.Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + /// An older man's voice. Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. @JsonValue(0x02020200) voiceChangerEffectOldman, - /// A boy's voice.Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + /// A boy's voice. Agora recommends using this preset to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. @JsonValue(0x02020300) voiceChangerEffectBoy, - /// A young woman's voice.Agora recommends using this preset to process a female-sounding voice; otherwise, you may not hear the anticipated voice effect. + /// A young woman's voice. Agora recommends using this preset to process a female-sounding voice; otherwise, you may not hear the anticipated voice effect. @JsonValue(0x02020400) voiceChangerEffectSister, - /// A girl's voice.Agora recommends using this preset to process a female-sounding voice; otherwise, you may not hear the anticipated voice effect. + /// A girl's voice. Agora recommends using this preset to process a female-sounding voice; otherwise, you may not hear the anticipated voice effect. @JsonValue(0x02020500) voiceChangerEffectGirl, @@ -5081,7 +5242,9 @@ class ScreenCaptureParameters { this.highLightColor, this.enableHighLight}); - /// The video encoding resolution of the shared screen stream. See VideoDimensions. The default value is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges.If the screen dimensions are different from the value of this parameter, Agora applies the following strategies for encoding. Suppose dimensions is set to 1920 × 1080:If the value of the screen dimensions is lower than that of dimensions, for example, 1000 × 1000 pixels, the SDK uses the screen dimensions, that is, 1000 × 1000 pixels, for encoding.If the value of the screen dimensions is higher than that of dimensions, for example, 2000 × 1500, the SDK uses the maximum value under dimensions with the aspect ratio of the screen dimension (4:3) for encoding, that is, 1440 × 1080. + /// The video encoding resolution of the shared screen stream. See VideoDimensions. The default value is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. If the screen dimensions are different from the value of this parameter, Agora applies the following strategies for encoding. Suppose dimensions is set to 1920 × 1080: + /// If the value of the screen dimensions is lower than that of dimensions, for example, 1000 × 1000 pixels, the SDK uses the screen dimensions, that is, 1000 × 1000 pixels, for encoding. + /// If the value of the screen dimensions is higher than that of dimensions, for example, 2000 × 1500, the SDK uses the maximum value under dimensions with the aspect ratio of the screen dimension (4:3) for encoding, that is, 1440 × 1080. @JsonKey(name: 'dimensions') final VideoDimensions? dimensions; @@ -5093,11 +5256,11 @@ 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. @JsonKey(name: 'captureMouseCursor') final bool? captureMouseCursor; - /// Whether to bring the window to the front when calling the startScreenCaptureByWindowId method to share it:true: Bring the window to the front.false: (Default) Do not bring the window to the front. + /// Whether to bring the window to the front when calling the startScreenCaptureByWindowId method to share it: true : Bring the window to the front. false : (Default) Do not bring the window to the front. @JsonKey(name: 'windowFocus') final bool? windowFocus; @@ -5105,19 +5268,21 @@ class ScreenCaptureParameters { @JsonKey(name: 'excludeWindowList') final List? excludeWindowList; - /// The number of windows to be excluded.On the Windows platform, the maximum value of this parameter is 24; if this value is exceeded, excluding the window fails. + /// The number of windows to be excluded. On the Windows platform, the maximum value of this parameter is 24; if this value is exceeded, excluding the window fails. @JsonKey(name: 'excludeWindowCount') final int? excludeWindowCount; - /// (For macOS and Windows only) The width (px) of the border. The default value is 5, and the value range is (0, 50].This parameter only takes effect when highLighted is set to true. + /// (For macOS and Windows only) The width (px) of the border. The default value is 5, and the value range is (0, 50]. This parameter only takes effect when highLighted is set to true. @JsonKey(name: 'highLightWidth') final int? highLightWidth; - /// (For macOS and Windows only)On Windows platforms, the color of the border in ARGB format. The default value is 0xFF8CBF26.On macOS, COLOR_CLASS refers to NSColor. + /// (For macOS and Windows only) + /// On Windows platforms, the color of the border in ARGB format. The default value is 0xFF8CBF26. + /// On macOS, COLOR_CLASS refers to NSColor. @JsonKey(name: 'highLightColor') final int? highLightColor; - /// (For macOS and Windows only) Whether to place a border around the shared window or screen:true: Place a border.false: (Default) Do not place a border.When you share a part of a window or screen, the SDK places a border around the entire window or screen if you set this parameter to true. + /// (For macOS and Windows only) Whether to place a border around the shared window or screen: true : Place a border. false : (Default) Do not place a border. When you share a part of a window or screen, the SDK places a border around the entire window or screen if you set this parameter to true. @JsonKey(name: 'enableHighLight') final bool? enableHighLight; @@ -5232,15 +5397,19 @@ 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.mp4. Ensure that the directory for the log files exists and is writable. @JsonKey(name: 'filePath') final String? filePath; - /// Whether to encode the audio data:true: Encode audio data in AAC.false: (Default) Do not encode audio data, but save the recorded audio data directly. + /// Whether to encode the audio data: true : Encode audio data in AAC. false : (Default) Do not encode audio data, but save the recorded audio data directly. @JsonKey(name: 'encode') final bool? encode; - /// Recording sample rate (Hz).16000(Default) 320004410048000If you set this parameter to 44100 or 48000, Agora recommends recording WAV files, or AAC files with quality set as audioRecordingQualityMedium or audioRecordingQualityHigh for better recording quality. + /// Recording sample rate (Hz). + /// 16000 + /// (Default) 32000 + /// 44100 + /// 48000 If you set this parameter to 44100 or 48000, Agora recommends recording WAV files, or AAC files with quality set as audioRecordingQualityMedium or audioRecordingQualityHigh for better recording quality. @JsonKey(name: 'sampleRate') final int? sampleRate; @@ -5248,11 +5417,15 @@ class AudioRecordingConfiguration { @JsonKey(name: 'fileRecordingType') final AudioFileRecordingType? fileRecordingType; - /// Recording quality. See audiorecordingqualitytype.Note: This parameter applies to AAC files only. + /// Recording quality. See audiorecordingqualitytype. Note: This parameter applies to AAC files only. @JsonKey(name: 'quality') final AudioRecordingQualityType? quality; - /// The audio channel of recording: The parameter supports the following values:1: (Default) Mono.2: Stereo.The actual recorded audio channel is related to the audio channel that you capture.If the captured audio is mono and recordingChannel is 2, the recorded audio is the dual-channel data that is copied from mono data, not stereo.If the captured audio is dual channel and recordingChannel is 1, the recorded audio is the mono data that is mixed by dual-channel data.The integration scheme also affects the final recorded audio channel. If you need to record in stereo, contact . + /// The audio channel of recording: The parameter supports the following values: + /// 1: (Default) Mono. + /// 2: Stereo. The actual recorded audio channel is related to the audio channel that you capture. + /// If the captured audio is mono and recordingChannel is 2, the recorded audio is the dual-channel data that is copied from mono data, not stereo. + /// If the captured audio is dual channel and recordingChannel is 1, the recorded audio is the mono data that is mixed by dual-channel data. The integration scheme also affects the final recorded audio channel. If you need to record in stereo, contact. @JsonKey(name: 'recordingChannel') final int? recordingChannel; @@ -5298,7 +5471,7 @@ class AudioEncodedFrameObserver { /// Gets the encoded audio data of the local user. /// - /// After calling registerAudioEncodedFrameObserver and setting the encoded audio as audioEncodedFrameObserverPositionRecord , you can get the encoded audio data of the local user from this callback. + /// After calling registerAudioEncodedFrameObserver and setting the encoded audio as audioEncodedFrameObserverPositionRecord, you can get the encoded audio data of the local user from this callback. /// /// * [channels] The number of channels. /// 1: Mono. @@ -5311,7 +5484,7 @@ class AudioEncodedFrameObserver { /// Gets the encoded audio data of all remote users. /// - /// After calling registerAudioEncodedFrameObserver and setting the encoded audio as audioEncodedFrameObserverPositionPlayback , you can get encoded audio data of all remote users through this callback. + /// After calling registerAudioEncodedFrameObserver and setting the encoded audio as audioEncodedFrameObserverPositionPlayback, you can get encoded audio data of all remote users through this callback. /// /// * [samplesPerSec] Recording sample rate (Hz). /// * [channels] The number of channels. @@ -5326,7 +5499,7 @@ class AudioEncodedFrameObserver { /// Gets the mixed and encoded audio data of the local and all remote users. /// - /// After calling registerAudioEncodedFrameObserver and setting the audio profile as audioEncodedFrameObserverPositionMixed , you can get the mixed and encoded audio data of the local and all remote users through this callback. + /// After calling registerAudioEncodedFrameObserver and setting the audio profile as audioEncodedFrameObserverPositionMixed, you can get the mixed and encoded audio data of the local and all remote users through this callback. /// /// * [samplesPerSec] Recording sample rate (Hz). /// * [channels] The number of channels. @@ -5441,7 +5614,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. 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. @JsonValue(2) relayErrorServerNoResponse, @@ -5642,15 +5815,19 @@ class ChannelMediaRelayConfiguration { const ChannelMediaRelayConfiguration( {this.srcInfo, this.destInfos, this.destCount}); - /// The information of the source channel. See ChannelMediaInfo. It contains the following members:channelName: The name of the source channel. The default value is NULL, which means the SDK applies the name of the current channel.token: The token for joining the source channel. This token is generated with the channelName and uid you set in srcInfo.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, and the uid must be set as 0.uid: The unique user ID to identify the relay stream in the source channel. Agora recommends leaving the default value of 0 unchanged. + /// The information of the source channel. See ChannelMediaInfo. It contains the following members: channelName : The name of the source channel. The default value is NULL, which means the SDK applies the name of the current channel. token : The token for joining the source channel. This token is generated with the channelName and uid you set in srcInfo. + /// 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, and the uid must be set as 0. uid : The unique user ID to identify the relay stream in the source channel. Agora recommends leaving the default value of 0 unchanged. @JsonKey(name: 'srcInfo') final ChannelMediaInfo? srcInfo; - /// 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. + /// 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. @JsonKey(name: 'destInfos') final List? destInfos; - /// The number of target channels. The default value is 0, and the value range is from 0 to 4. Ensure that the value of this parameter corresponds to the number of ChannelMediaInfo structs you define in destInfo. + /// The number of target channels. The default value is 0, and the value range is from 0 to 6. Ensure that the value of this parameter corresponds to the number of ChannelMediaInfo structs you define in destInfo. @JsonKey(name: 'destCount') final int? destCount; @@ -5819,7 +5996,7 @@ class EncryptionConfig { @JsonKey(name: 'encryptionMode') final EncryptionMode? encryptionMode; - /// Encryption key in string type with unlimited length. Agora recommends using a 32-byte key.If you do not set an encryption key or set it as NULL, you cannot use the built-in encryption, and the SDK returns -2. + /// Encryption key in string type with unlimited length. Agora recommends using a 32-byte key. If you do not set an encryption key or set it as NULL, you cannot use the built-in encryption, and the SDK returns -2. @JsonKey(name: 'encryptionKey') final String? encryptionKey; @@ -5950,7 +6127,15 @@ enum StreamSubscribeState { @JsonValue(0) subStateIdle, - /// 1: Fails to subscribe to the remote stream. Possible reasons:The remote user:Calls muteLocalAudioStream(true) or muteLocalVideoStream(true) to stop sending local media stream.Calls disableAudio or disableVideo to disable the local audio or video module.Calls enableLocalAudio(false) or enableLocalVideo(false) to disable local audio or video capture.The role of the remote user is audience.The local user calls the following methods to stop receiving remote streams:Call muteRemoteAudioStream(true) or muteAllRemoteAudioStreams(true) to stop receiving the remote audio stream.Call muteRemoteVideoStream(true) or muteAllRemoteVideoStreams(true) to stop receiving the remote video stream. + /// 1: Fails to subscribe to the remote stream. Possible reasons: + /// The remote user: + /// Calls muteLocalAudioStream (true) or muteLocalVideoStream (true) to stop sending local media stream. + /// Calls disableAudio or disableVideo to disable the local audio or video module. + /// Calls enableLocalAudio (false) or enableLocalVideo (false) to disable local audio or video capture. + /// The role of the remote user is audience. + /// The local user calls the following methods to stop receiving remote streams: + /// Call muteRemoteAudioStream (true) or muteAllRemoteAudioStreams (true) to stop receiving the remote audio stream. + /// Call muteRemoteVideoStream (true) or muteAllRemoteVideoStreams (true) to stop receiving the remote video stream. @JsonValue(1) subStateNoSubscribed, @@ -5983,7 +6168,11 @@ enum StreamPublishState { @JsonValue(0) pubStateIdle, - /// 1: Fails to publish the local stream. Possible reasons:The local user calls muteLocalAudioStream(true) or muteLocalVideoStream(true) to stop sending local media streams.The local user calls disableAudio or disableVideo to disable the local audio or video module.The local user calls enableLocalAudio(false) or enableLocalVideo(false) to disable the local audio or video capture.The role of the local user is audience. + /// 1: Fails to publish the local stream. Possible reasons: + /// The local user calls muteLocalAudioStream (true) or muteLocalVideoStream (true) to stop sending local media streams. + /// The local user calls disableAudio or disableVideo to disable the local audio or video module. + /// The local user calls enableLocalAudio (false) or enableLocalVideo (false) to disable the local audio or video capture. + /// The role of the local user is audience. @JsonValue(1) pubStateNoPublished, @@ -6025,15 +6214,15 @@ class EchoTestConfiguration { @JsonKey(name: 'view') final int? view; - /// Whether to enable the audio device for the loop test:true: (Default) Enable the audio device. To test the audio device, set this parameter as true.false: Disable the audio device. + /// Whether to enable the audio device for the loop test: true : (Default) Enable the audio device. To test the audio device, set this parameter as true. false : Disable the audio device. @JsonKey(name: 'enableAudio') final bool? enableAudio; - /// Whether to enable the video device for the loop test:true: (Default) Enable the video device. To test the video device, set this parameter as true.false: Disable the video device. + /// Whether to enable the video device for the loop test: true : (Default) Enable the video device. To test the video device, set this parameter as true. false : Disable the video device. @JsonKey(name: 'enableVideo') final bool? enableVideo; - /// The token used to secure the audio and video call loop test. If you do not enable App Certificate in Agora Console, you do not need to pass a value in this parameter; if you have enabled App Certificate in Agora Console, you must pass a token in this parameter; the uid used when you generate the token must be 0xFFFFFFFF, and the channel name used must be the channel name that identifies each audio and video call loop tested. For server-side token generation, see . + /// The token used to secure the audio and video call loop test. If you do not enable App Certificate in Agora Console, you do not need to pass a value in this parameter; if you have enabled App Certificate in Agora Console, you must pass a token in this parameter; the uid used when you generate the token must be 0xFFFFFFFF, and the channel name used must be the channel name that identifies each audio and video call loop tested. For server-side token generation, see. @JsonKey(name: 'token') final String? token; @@ -6178,7 +6367,7 @@ class ScreenVideoParameters { /// The audio configuration for the shared screen stream. /// -/// Only available where captureAudio is true . +/// Only available where captureAudio is true. @JsonSerializable(explicitToJson: true, includeIfNull: false) class ScreenAudioParameters { /// @nodoc @@ -6215,19 +6404,21 @@ class ScreenCaptureParameters2 { this.captureVideo, this.videoParams}); - /// Determines whether to capture system audio during screen sharing:true: Capture system audio.false: (Default) Do not capture system audio.Due to system limitations, capturing system audio is only applicable to Android API level 29 and later (that is, Android 10 and later). + /// Determines whether to capture system audio during screen sharing: true : Capture system audio. false : (Default) Do not capture system audio. + /// Due to system limitations, capturing system audio is only applicable to Android API level 29 and later (that is, Android 10 and later). + /// To improve the success rate of capturing system audio during screen sharing, ensure that you have called the setAudioScenario method and set the audio scenario to audioScenarioGameStreaming. @JsonKey(name: 'captureAudio') final bool? captureAudio; - /// The audio configuration for the shared screen stream. See ScreenAudioParameters.This parameter only takes effect when captureAudio is true. + /// The audio configuration for the shared screen stream. See ScreenAudioParameters. This parameter only takes effect when captureAudio is true. @JsonKey(name: 'audioParams') final ScreenAudioParameters? audioParams; - /// Whether to capture the screen when screen sharing:true: (Default) Capture the screen.false: Do not capture the screen.Due to system limitations, the capture screen is only applicable to Android API level 21 and above, that is, Android 5 and above. + /// Whether to capture the screen when screen sharing: true : (Default) Capture the screen. false : Do not capture the screen. Due to system limitations, the capture screen is only applicable to Android API level 21 and above, that is, Android 5 and above. @JsonKey(name: 'captureVideo') final bool? captureVideo; - /// The video configuration for the shared screen stream. See ScreenVideoParameters.This parameter only takes effect when captureVideo is true. + /// The video configuration for the shared screen stream. See ScreenVideoParameters. This parameter only takes effect when captureVideo is true. @JsonKey(name: 'videoParams') final ScreenVideoParameters? videoParams; @@ -6239,7 +6430,7 @@ class ScreenCaptureParameters2 { Map toJson() => _$ScreenCaptureParameters2ToJson(this); } -/// The rendering state of the media frame.` +/// The rendering state of the media frame. @JsonEnum(alwaysCreate: true) enum MediaTraceEvent { /// 0: The video frame has been rendered. @@ -6289,19 +6480,31 @@ class VideoRenderingTracingInfo { @JsonKey(name: 'join2JoinSuccess') final int? join2JoinSuccess; - /// If the local user calls startMediaRenderingTracing before successfully joining the channel, this value is the time interval from the local user successfully joining the channel to the remote user joining the channel. The unit is milliseconds.If the local user calls startMediaRenderingTracing after successfully joining the channel, the value is the time interval from calling startMediaRenderingTracing to when the remote user joins the channel. The unit is milliseconds.If the local user calls startMediaRenderingTracing after the remote user joins the channel, the value is 0 and meaningless.In order to reduce the time of rendering the first frame for remote users, Agora recommends that the local user joins the channel when the remote user is in the channel to reduce this value. + /// If the local user calls startMediaRenderingTracing before successfully joining the channel, this value is the time interval from the local user successfully joining the channel to the remote user joining the channel. The unit is milliseconds. + /// If the local user calls startMediaRenderingTracing after successfully joining the channel, the value is the time interval from calling startMediaRenderingTracing to when the remote user joins the channel. The unit is milliseconds. + /// If the local user calls startMediaRenderingTracing after the remote user joins the channel, the value is 0 and meaningless. + /// In order to reduce the time of rendering the first frame for remote users, Agora recommends that the local user joins the channel when the remote user is in the channel to reduce this value. @JsonKey(name: 'joinSuccess2RemoteJoined') final int? joinSuccess2RemoteJoined; - /// If the local user calls startMediaRenderingTracing before the remote user joins the channel, this value is the time interval from when the remote user joins the channel to when the local user sets the remote view. The unit is milliseconds.If the local user calls startMediaRenderingTracing after the remote user joins the channel, this value is the time interval from calling startMediaRenderingTracing to setting the remote view. The unit is milliseconds.If the local user calls startMediaRenderingTracing after setting the remote view, the value is 0 and has no effect.In order to reduce the time of rendering the first frame for remote users, Agora recommends that the local user sets the remote view before the remote user joins the channel, or sets the remote view immediately after the remote user joins the channel to reduce this value. + /// If the local user calls startMediaRenderingTracing before the remote user joins the channel, this value is the time interval from when the remote user joins the channel to when the local user sets the remote view. The unit is milliseconds. + /// If the local user calls startMediaRenderingTracing after the remote user joins the channel, this value is the time interval from calling startMediaRenderingTracing to setting the remote view. The unit is milliseconds. + /// If the local user calls startMediaRenderingTracing after setting the remote view, the value is 0 and has no effect. + /// In order to reduce the time of rendering the first frame for remote users, Agora recommends that the local user sets the remote view before the remote user joins the channel, or sets the remote view immediately after the remote user joins the channel to reduce this value. @JsonKey(name: 'remoteJoined2SetView') final int? remoteJoined2SetView; - /// If the local user calls startMediaRenderingTracing before the remote user joins the channel, this value is the time interval from the remote user joining the channel to subscribing to the remote video stream. The unit is milliseconds.If the local user calls startMediaRenderingTracing after the remote user joins the channel, this value is the time interval from calling startMediaRenderingTracing to subscribing to the remote video stream. The unit is milliseconds.If the local user calls startMediaRenderingTracing after subscribing to the remote video stream, the value is 0 and has no effect.In order to reduce the time of rendering the first frame for remote users, Agora recommends that after the remote user joins the channel, the local user immediately subscribes to the remote video stream to reduce this value. + /// If the local user calls startMediaRenderingTracing before the remote user joins the channel, this value is the time interval from the remote user joining the channel to subscribing to the remote video stream. The unit is milliseconds. + /// If the local user calls startMediaRenderingTracing after the remote user joins the channel, this value is the time interval from calling startMediaRenderingTracing to subscribing to the remote video stream. The unit is milliseconds. + /// If the local user calls startMediaRenderingTracing after subscribing to the remote video stream, the value is 0 and has no effect. + /// In order to reduce the time of rendering the first frame for remote users, Agora recommends that after the remote user joins the channel, the local user immediately subscribes to the remote video stream to reduce this value. @JsonKey(name: 'remoteJoined2UnmuteVideo') final int? remoteJoined2UnmuteVideo; - /// If the local user calls startMediaRenderingTracing before the remote user joins the channel, this value is the time interval from when the remote user joins the channel to when the local user receives the remote video stream. The unit is milliseconds.If the local user calls startMediaRenderingTracing after the remote user joins the channel, this value is the time interval from calling startMediaRenderingTracing to receiving the remote video stream. The unit is milliseconds.If the local user calls startMediaRenderingTracing after receiving the remote video stream, the value is 0 and has no effect.In order to reduce the time of rendering the first frame for remote users, Agora recommends that the remote user publishes video streams immediately after joining the channel, and the local user immediately subscribes to remote video streams to reduce this value. + /// If the local user calls startMediaRenderingTracing before the remote user joins the channel, this value is the time interval from when the remote user joins the channel to when the local user receives the remote video stream. The unit is milliseconds. + /// If the local user calls startMediaRenderingTracing after the remote user joins the channel, this value is the time interval from calling startMediaRenderingTracing to receiving the remote video stream. The unit is milliseconds. + /// If the local user calls startMediaRenderingTracing after receiving the remote video stream, the value is 0 and has no effect. + /// In order to reduce the time of rendering the first frame for remote users, Agora recommends that the remote user publishes video streams immediately after joining the channel, and the local user immediately subscribes to remote video streams to reduce this value. @JsonKey(name: 'remoteJoined2PacketReceived') final int? remoteJoined2PacketReceived; @@ -6360,6 +6563,129 @@ class RecorderStreamInfo { Map toJson() => _$RecorderStreamInfoToJson(this); } +/// @nodoc +@JsonEnum(alwaysCreate: true) +enum LocalProxyMode { + /// @nodoc + @JsonValue(0) + connectivityFirst, + + /// @nodoc + @JsonValue(1) + localOnly, +} + +/// @nodoc +extension LocalProxyModeExt on LocalProxyMode { + /// @nodoc + static LocalProxyMode fromValue(int value) { + return $enumDecode(_$LocalProxyModeEnumMap, value); + } + + /// @nodoc + int value() { + return _$LocalProxyModeEnumMap[this]!; + } +} + +/// @nodoc +@JsonSerializable(explicitToJson: true, includeIfNull: false) +class LogUploadServerInfo { + /// @nodoc + const LogUploadServerInfo( + {this.serverDomain, this.serverPath, this.serverPort, this.serverHttps}); + + /// @nodoc + @JsonKey(name: 'serverDomain') + final String? serverDomain; + + /// @nodoc + @JsonKey(name: 'serverPath') + final String? serverPath; + + /// @nodoc + @JsonKey(name: 'serverPort') + final int? serverPort; + + /// @nodoc + @JsonKey(name: 'serverHttps') + final bool? serverHttps; + + /// @nodoc + factory LogUploadServerInfo.fromJson(Map json) => + _$LogUploadServerInfoFromJson(json); + + /// @nodoc + Map toJson() => _$LogUploadServerInfoToJson(this); +} + +/// @nodoc +@JsonSerializable(explicitToJson: true, includeIfNull: false) +class AdvancedConfigInfo { + /// @nodoc + const AdvancedConfigInfo({this.logUploadServer}); + + /// @nodoc + @JsonKey(name: 'logUploadServer') + final LogUploadServerInfo? logUploadServer; + + /// @nodoc + factory AdvancedConfigInfo.fromJson(Map json) => + _$AdvancedConfigInfoFromJson(json); + + /// @nodoc + Map toJson() => _$AdvancedConfigInfoToJson(this); +} + +/// @nodoc +@JsonSerializable(explicitToJson: true, includeIfNull: false) +class LocalAccessPointConfiguration { + /// @nodoc + const LocalAccessPointConfiguration( + {this.ipList, + this.ipListSize, + this.domainList, + this.domainListSize, + this.verifyDomainName, + this.mode, + this.advancedConfig}); + + /// @nodoc + @JsonKey(name: 'ipList') + final List? ipList; + + /// @nodoc + @JsonKey(name: 'ipListSize') + final int? ipListSize; + + /// @nodoc + @JsonKey(name: 'domainList') + final List? domainList; + + /// @nodoc + @JsonKey(name: 'domainListSize') + final int? domainListSize; + + /// @nodoc + @JsonKey(name: 'verifyDomainName') + final String? verifyDomainName; + + /// @nodoc + @JsonKey(name: 'mode') + final LocalProxyMode? mode; + + /// @nodoc + @JsonKey(name: 'advancedConfig') + final AdvancedConfigInfo? advancedConfig; + + /// @nodoc + factory LocalAccessPointConfiguration.fromJson(Map json) => + _$LocalAccessPointConfigurationFromJson(json); + + /// @nodoc + Map toJson() => _$LocalAccessPointConfigurationToJson(this); +} + /// The spatial audio parameters. @JsonSerializable(explicitToJson: true, includeIfNull: false) class SpatialAudioParams { diff --git a/lib/src/agora_base.g.dart b/lib/src/agora_base.g.dart index a3e2ef9b0..2dcad2bb4 100644 --- a/lib/src/agora_base.g.dart +++ b/lib/src/agora_base.g.dart @@ -283,10 +283,46 @@ const _$CompressionPreferenceEnumMap = { CompressionPreference.preferQuality: 1, }; +CodecCapLevels _$CodecCapLevelsFromJson(Map json) => + CodecCapLevels( + hwDecodingLevel: $enumDecodeNullable( + _$VideoCodecCapabilityLevelEnumMap, json['hwDecodingLevel']), + swDecodingLevel: $enumDecodeNullable( + _$VideoCodecCapabilityLevelEnumMap, json['swDecodingLevel']), + ); + +Map _$CodecCapLevelsToJson(CodecCapLevels instance) { + final val = {}; + + void writeNotNull(String key, dynamic value) { + if (value != null) { + val[key] = value; + } + } + + writeNotNull('hwDecodingLevel', + _$VideoCodecCapabilityLevelEnumMap[instance.hwDecodingLevel]); + writeNotNull('swDecodingLevel', + _$VideoCodecCapabilityLevelEnumMap[instance.swDecodingLevel]); + return val; +} + +const _$VideoCodecCapabilityLevelEnumMap = { + VideoCodecCapabilityLevel.codecCapabilityLevelUnspecified: -1, + VideoCodecCapabilityLevel.codecCapabilityLevelBasicSupport: 5, + VideoCodecCapabilityLevel.codecCapabilityLevel1080p30fps: 10, + VideoCodecCapabilityLevel.codecCapabilityLevel1080p60fps: 20, + VideoCodecCapabilityLevel.codecCapabilityLevel4k60fps: 30, +}; + CodecCapInfo _$CodecCapInfoFromJson(Map json) => CodecCapInfo( codecType: $enumDecodeNullable(_$VideoCodecTypeEnumMap, json['codecType']), codecCapMask: json['codecCapMask'] as int?, + codecLevels: json['codecLevels'] == null + ? null + : CodecCapLevels.fromJson( + json['codecLevels'] as Map), ); Map _$CodecCapInfoToJson(CodecCapInfo instance) { @@ -300,6 +336,7 @@ Map _$CodecCapInfoToJson(CodecCapInfo instance) { writeNotNull('codecType', _$VideoCodecTypeEnumMap[instance.codecType]); writeNotNull('codecCapMask', instance.codecCapMask); + writeNotNull('codecLevels', instance.codecLevels?.toJson()); return val; } @@ -1165,6 +1202,7 @@ Map _$WlAccStatsToJson(WlAccStats instance) { VideoCanvas _$VideoCanvasFromJson(Map json) => VideoCanvas( view: json['view'] as int?, uid: json['uid'] as int?, + backgroundColor: json['backgroundColor'] as int?, renderMode: $enumDecodeNullable(_$RenderModeTypeEnumMap, json['renderMode']), mirrorMode: @@ -1191,6 +1229,7 @@ Map _$VideoCanvasToJson(VideoCanvas instance) { writeNotNull('view', instance.view); writeNotNull('uid', instance.uid); + writeNotNull('backgroundColor', instance.backgroundColor); writeNotNull('renderMode', _$RenderModeTypeEnumMap[instance.renderMode]); writeNotNull('mirrorMode', _$VideoMirrorModeTypeEnumMap[instance.mirrorMode]); writeNotNull('setupMode', _$VideoViewSetupModeEnumMap[instance.setupMode]); @@ -1922,6 +1961,94 @@ Map _$RecorderStreamInfoToJson(RecorderStreamInfo instance) { return val; } +LogUploadServerInfo _$LogUploadServerInfoFromJson(Map json) => + LogUploadServerInfo( + serverDomain: json['serverDomain'] as String?, + serverPath: json['serverPath'] as String?, + serverPort: json['serverPort'] as int?, + serverHttps: json['serverHttps'] as bool?, + ); + +Map _$LogUploadServerInfoToJson(LogUploadServerInfo instance) { + final val = {}; + + void writeNotNull(String key, dynamic value) { + if (value != null) { + val[key] = value; + } + } + + writeNotNull('serverDomain', instance.serverDomain); + writeNotNull('serverPath', instance.serverPath); + writeNotNull('serverPort', instance.serverPort); + writeNotNull('serverHttps', instance.serverHttps); + return val; +} + +AdvancedConfigInfo _$AdvancedConfigInfoFromJson(Map json) => + AdvancedConfigInfo( + logUploadServer: json['logUploadServer'] == null + ? null + : LogUploadServerInfo.fromJson( + json['logUploadServer'] as Map), + ); + +Map _$AdvancedConfigInfoToJson(AdvancedConfigInfo instance) { + final val = {}; + + void writeNotNull(String key, dynamic value) { + if (value != null) { + val[key] = value; + } + } + + writeNotNull('logUploadServer', instance.logUploadServer?.toJson()); + return val; +} + +LocalAccessPointConfiguration _$LocalAccessPointConfigurationFromJson( + Map json) => + LocalAccessPointConfiguration( + ipList: + (json['ipList'] as List?)?.map((e) => e as String).toList(), + ipListSize: json['ipListSize'] as int?, + domainList: (json['domainList'] as List?) + ?.map((e) => e as String) + .toList(), + domainListSize: json['domainListSize'] as int?, + verifyDomainName: json['verifyDomainName'] as String?, + mode: $enumDecodeNullable(_$LocalProxyModeEnumMap, json['mode']), + advancedConfig: json['advancedConfig'] == null + ? null + : AdvancedConfigInfo.fromJson( + json['advancedConfig'] as Map), + ); + +Map _$LocalAccessPointConfigurationToJson( + LocalAccessPointConfiguration instance) { + final val = {}; + + void writeNotNull(String key, dynamic value) { + if (value != null) { + val[key] = value; + } + } + + writeNotNull('ipList', instance.ipList); + writeNotNull('ipListSize', instance.ipListSize); + writeNotNull('domainList', instance.domainList); + writeNotNull('domainListSize', instance.domainListSize); + writeNotNull('verifyDomainName', instance.verifyDomainName); + writeNotNull('mode', _$LocalProxyModeEnumMap[instance.mode]); + writeNotNull('advancedConfig', instance.advancedConfig?.toJson()); + return val; +} + +const _$LocalProxyModeEnumMap = { + LocalProxyMode.connectivityFirst: 0, + LocalProxyMode.localOnly: 1, +}; + SpatialAudioParams _$SpatialAudioParamsFromJson(Map json) => SpatialAudioParams( speakerAzimuth: (json['speaker_azimuth'] as num?)?.toDouble(), diff --git a/lib/src/agora_log.dart b/lib/src/agora_log.dart index a8e362ff4..c3259bf99 100644 --- a/lib/src/agora_log.dart +++ b/lib/src/agora_log.dart @@ -106,11 +106,11 @@ class LogConfig { @JsonKey(name: 'filePath') final String? filePath; - /// The size (KB) of an agorasdk.log file. The value range is [128,1024]. The default value is 1,024 KB. If you set fileSizeInKByte smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you set fileSizeInKByte greater than 1,024 KB, the SDK automatically adjusts it to 1,024 KB. + /// The size (KB) of an agorasdk.log file. The value range is [128,20480]. The default value is 2,048 KB. If you set fileSizeInKByte smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you set fileSizeInKByte greater than 20,480 KB, the SDK automatically adjusts it to 20,480 KB. @JsonKey(name: 'fileSizeInKB') final int? fileSizeInKB; - /// The output level of the SDK log file. See LogLevel.For example, if you set the log level to WARN, the SDK outputs the logs within levels FATAL, ERROR, and WARN. + /// The output level of the SDK log file. See LogLevel. For example, if you set the log level to WARN, the SDK outputs the logs within levels FATAL, ERROR, and WARN. @JsonKey(name: 'level') final LogLevel? level; diff --git a/lib/src/agora_media_base.dart b/lib/src/agora_media_base.dart index b8be964a4..caef1c54c 100644 --- a/lib/src/agora_media_base.dart +++ b/lib/src/agora_media_base.dart @@ -210,11 +210,11 @@ class AudioParameters { /// The use mode of the audio data. @JsonEnum(alwaysCreate: true) enum RawAudioFrameOpModeType { - /// 0: Read-only mode, + /// 0: Read-only mode, For example, when users acquire the data with the Agora SDK, then start the media push. @JsonValue(0) rawAudioFrameOpModeReadOnly, - /// 2: Read and write mode, + /// 2: Read and write mode, For example, when users have their own audio-effect processing module and perform some voice preprocessing, such as a voice change. @JsonValue(2) rawAudioFrameOpModeReadWrite, } @@ -363,7 +363,7 @@ extension ContentInspectTypeExt on ContentInspectType { } } -/// A structure used to configure the frequency of video screenshot and upload.ContentInspectModule +/// A ContentInspectModule structure used to configure the frequency of video screenshot and upload. @JsonSerializable(explicitToJson: true, includeIfNull: false) class ContentInspectModule { /// @nodoc @@ -391,11 +391,11 @@ class ContentInspectConfig { /// @nodoc const ContentInspectConfig({this.extraInfo, this.modules, this.moduleCount}); - /// Additional information on the video content (maximum length: 1024 Bytes).The SDK sends the screenshots and additional information on the video content to the Agora server. Once the video screenshot and upload process is completed, the Agora server sends the additional information and the callback notification to your server. + /// Additional information on the video content (maximum length: 1024 Bytes). The SDK sends the screenshots and additional information on the video content to the Agora server. Once the video screenshot and upload process is completed, the Agora server sends the additional information and the callback notification to your server. @JsonKey(name: 'extraInfo') final String? extraInfo; - /// Functional module. See ContentInspectModule.A maximum of 32 ContentInspectModule instances can be configured, and the value range of MAX_CONTENT_INSPECT_MODULE_COUNT is an integer in [1,32].A function module can only be configured with one instance at most. Currently only the video screenshot and upload function is supported. + /// Functional module. See ContentInspectModule. A maximum of 32 ContentInspectModule instances can be configured, and the value range of MAX_CONTENT_INSPECT_MODULE_COUNT is an integer in [1,32]. A function module can only be configured with one instance at most. Currently only the video screenshot and upload function is supported. @JsonKey(name: 'modules') final List? modules; @@ -611,7 +611,7 @@ enum RenderModeType { @JsonValue(2) renderModeFit, - /// Deprecated:3: This mode is deprecated. + /// Deprecated: 3: This mode is deprecated. @JsonValue(3) renderModeAdaptive, } @@ -1004,7 +1004,8 @@ class AudioFrameObserverBase { /// Gets the captured audio frame. /// - /// To ensure that the data format of captured audio frame is as expected, Agora recommends that you set the audio data format as follows: After calling setRecordingAudioFrameParameters to set the audio data format, call registerAudioFrameObserver to register the audio observer object, the SDK will calculate the sampling interval according to the parameters set in this method, and triggers the onRecordAudioFrame callback according to the sampling interval. Due to the limitations of Flutter, this callback does not support sending processed audio data back to the SDK. + /// To ensure that the data format of captured audio frame is as expected, Agora recommends that you set the audio data format as follows: After calling setRecordingAudioFrameParameters to set the audio data format, call registerAudioFrameObserver to register the audio observer object, the SDK will calculate the sampling interval according to the parameters set in this method, and triggers the onRecordAudioFrame callback according to the sampling interval. + /// Due to the limitations of Flutter, this callback does not support sending processed audio data back to the SDK. /// /// * [audioFrame] The raw audio data. See AudioFrame. /// * [channelId] The channel ID. @@ -1013,7 +1014,8 @@ class AudioFrameObserverBase { /// Gets the raw audio frame for playback. /// - /// To ensure that the data format of audio frame for playback is as expected, Agora recommends that you set the audio data format as follows: After calling setPlaybackAudioFrameParameters to set the audio data format and registerAudioFrameObserver to register the audio frame observer object, the SDK calculates the sampling interval according to the parameters set in the methods, and triggers the onPlaybackAudioFrame callback according to the sampling interval. Due to the limitations of Flutter, this callback does not support sending processed audio data back to the SDK. + /// To ensure that the data format of audio frame for playback is as expected, Agora recommends that you set the audio data format as follows: After calling setPlaybackAudioFrameParameters to set the audio data format and registerAudioFrameObserver to register the audio frame observer object, the SDK calculates the sampling interval according to the parameters set in the methods, and triggers the onPlaybackAudioFrame callback according to the sampling interval. + /// Due to the limitations of Flutter, this callback does not support sending processed audio data back to the SDK. /// /// * [audioFrame] The raw audio data. See AudioFrame. /// * [channelId] The channel ID. @@ -1022,7 +1024,8 @@ class AudioFrameObserverBase { /// Retrieves the mixed captured and playback audio frame. /// - /// To ensure that the data format of mixed captured and playback audio frame meets the expectations, Agora recommends that you set the data format as follows: After calling setMixedAudioFrameParameters to set the audio data format and registerAudioFrameObserver to register the audio frame observer object, the SDK calculates the sampling interval according to the parameters set in the methods, and triggers the onMixedAudioFrame callback according to the sampling interval. Due to the limitations of Flutter, this callback does not support sending processed audio data back to the SDK. + /// To ensure that the data format of mixed captured and playback audio frame meets the expectations, Agora recommends that you set the data format as follows: After calling setMixedAudioFrameParameters to set the audio data format and registerAudioFrameObserver to register the audio frame observer object, the SDK calculates the sampling interval according to the parameters set in the methods, and triggers the onMixedAudioFrame callback according to the sampling interval. + /// Due to the limitations of Flutter, this callback does not support sending processed audio data back to the SDK. /// /// * [audioFrame] The raw audio data. See AudioFrame. /// * [channelId] The channel ID. @@ -1031,7 +1034,8 @@ class AudioFrameObserverBase { /// Gets the in-ear monitoring audio frame. /// - /// In order to ensure that the obtained in-ear audio data meets the expectations, Agora recommends that you set the in-ear monitoring-ear audio data format as follows: After calling setEarMonitoringAudioFrameParameters to set the audio data format and registerAudioFrameObserver to register the audio frame observer object, the SDK calculates the sampling interval according to the parameters set in the methods, and triggers the onEarMonitoringAudioFrame callback according to the sampling interval. Due to the limitations of Flutter, this callback does not support sending processed audio data back to the SDK. + /// In order to ensure that the obtained in-ear audio data meets the expectations, Agora recommends that you set the in-ear monitoring-ear audio data format as follows: After calling setEarMonitoringAudioFrameParameters to set the audio data format and registerAudioFrameObserver to register the audio frame observer object, the SDK calculates the sampling interval according to the parameters set in the methods, and triggers the onEarMonitoringAudioFrame callback according to the sampling interval. + /// Due to the limitations of Flutter, this callback does not support sending processed audio data back to the SDK. /// /// * [audioFrame] The raw audio data. See AudioFrame. final void Function(AudioFrame audioFrame)? onEarMonitoringAudioFrame; @@ -1070,7 +1074,8 @@ class AudioFrame { this.samplesPerSec, this.buffer, this.renderTimeMs, - this.avsyncType}); + this.avsyncType, + this.presentationMs}); /// The type of the audio frame. See AudioFrameType. @JsonKey(name: 'type') @@ -1084,7 +1089,9 @@ class AudioFrame { @JsonKey(name: 'bytesPerSample') final BytesPerSample? bytesPerSample; - /// The number of audio channels (the data are interleaved if it is stereo).1: Mono.2: Stereo. + /// The number of audio channels (the data are interleaved if it is stereo). + /// 1: Mono. + /// 2: Stereo. @JsonKey(name: 'channels') final int? channels; @@ -1092,11 +1099,11 @@ class AudioFrame { @JsonKey(name: 'samplesPerSec') final int? samplesPerSec; - /// The data buffer of the audio frame. When the audio frame uses a stereo channel, the data buffer is interleaved.The size of the data buffer is as follows: buffer = samples × channels × bytesPerSample. + /// The data buffer of the audio frame. When the audio frame uses a stereo channel, the data buffer is interleaved. The size of the data buffer is as follows: buffer = samples × channels × bytesPerSample. @JsonKey(name: 'buffer', ignore: true) final Uint8List? buffer; - /// The timestamp (ms) of the external audio frame.You can use this timestamp to restore the order of the captured audio frame, and synchronize audio and video frames in video scenarios, including scenarios where external video sources are used. + /// The timestamp (ms) of the external audio frame. You can use this timestamp to restore the order of the captured audio frame, and synchronize audio and video frames in video scenarios, including scenarios where external video sources are used. @JsonKey(name: 'renderTimeMs') final int? renderTimeMs; @@ -1104,6 +1111,10 @@ class AudioFrame { @JsonKey(name: 'avsync_type') final int? avsyncType; + /// @nodoc + @JsonKey(name: 'presentationMs') + final int? presentationMs; + /// @nodoc factory AudioFrame.fromJson(Map json) => _$AudioFrameFromJson(json); @@ -1155,18 +1166,26 @@ extension AudioFramePositionExt on AudioFramePosition { /// Audio data format. /// -/// The SDK calculates the sampling interval through the samplesPerCall , sampleRate , and channel parameters in AudioParams , and triggers the onRecordAudioFrame , onPlaybackAudioFrame , onMixedAudioFrame , and onEarMonitoringAudioFrame callbacks according to the sampling interval. Sample interval (sec) = samplePerCall /( sampleRate × channel ) . Ensure that the sample interval ≥ 0.01 (s). +/// The SDK calculates the sampling interval through the samplesPerCall, sampleRate, and channel parameters in AudioParams, and triggers the onRecordAudioFrame, onPlaybackAudioFrame, onMixedAudioFrame, and onEarMonitoringAudioFrame callbacks according to the sampling interval. Sample interval (sec) = samplePerCall /(sampleRate × channel). +/// Ensure that the sample interval ≥ 0.01 (s). @JsonSerializable(explicitToJson: true, includeIfNull: false) class AudioParams { /// @nodoc const AudioParams( {this.sampleRate, this.channels, this.mode, this.samplesPerCall}); - /// The audio sample rate (Hz), which can be set as one of the following values:8000.(Default) 16000.32000.4410048000 + /// The audio sample rate (Hz), which can be set as one of the following values: + /// 8000. + /// (Default) 16000. + /// 32000. + /// 44100 + /// 48000 @JsonKey(name: 'sample_rate') final int? sampleRate; - /// The number of audio channels, which can be set as either of the following values:1: (Default) Mono.2: Stereo. + /// The number of audio channels, which can be set as either of the following values: + /// 1: (Default) Mono. + /// 2: Stereo. @JsonKey(name: 'channels') final int? channels; @@ -1300,7 +1319,7 @@ class VideoEncodedFrameObserver { /// Reports that the receiver has received the to-be-decoded video frame sent by the remote end. /// - /// If you call the setRemoteVideoSubscriptionOptions method and set encodedFrameOnly to true , the SDK triggers this callback locally to report the received encoded video frame information. + /// If you call the setRemoteVideoSubscriptionOptions method and set encodedFrameOnly to true, the SDK triggers this callback locally to report the received encoded video frame information. /// /// * [uid] The user ID of the remote user. /// * [imageBuffer] The encoded video image buffer. @@ -1308,7 +1327,7 @@ class VideoEncodedFrameObserver { /// * [videoEncodedFrameInfo] For the information of the encoded video frame, see EncodedVideoFrameInfo. /// /// Returns - /// Reserved for future use. + /// Without practical meaning. final void Function(int uid, Uint8List imageBuffer, int length, EncodedVideoFrameInfo videoEncodedFrameInfo)? onEncodedVideoFrameReceived; } @@ -1326,18 +1345,31 @@ class VideoFrameObserver { /// Occurs each time the SDK receives a video frame captured by local devices. /// - /// After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. In this callback, you can get the video data captured by local devices. You can then pre-process the data according to your scenarios. The video data that this callback gets has not been pre-processed, and is not watermarked, cropped, rotated or beautified. If the video data type you get is RGBA, the SDK does not support processing the data of the alpha channel. Due to the limitations of Flutter, this callback does not support sending processed video data back to the SDK. + /// After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. In this callback, you can get the video data captured by local devices. You can then pre-process the data according to your scenarios. + /// The video data that this callback gets has not been pre-processed, and is not watermarked, cropped, rotated or beautified. + /// If the video data type you get is RGBA, the SDK does not support processing the data of the alpha channel. + /// Due to the limitations of Flutter, this callback does not support sending processed video data back to the SDK. /// /// * [sourceType] Video source types, including cameras, screens, or media player. See VideoSourceType. - /// * [videoFrame] The video frame. See VideoFrame.The default value of the video frame data format obtained through this callback is as follows:Android: textureiOS: cvPixelBuffermacOS: YUV 420Windows: YUV 420 + /// * [videoFrame] The video frame. See VideoFrame. The default value of the video frame data format obtained through this callback is as follows: + /// Android: texture + /// iOS: cvPixelBuffer + /// macOS: YUV 420 + /// Windows: YUV 420 final void Function(VideoSourceType sourceType, VideoFrame videoFrame)? onCaptureVideoFrame; /// Occurs each time the SDK receives a video frame before encoding. /// - /// After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. In this callback, you can get the video data before encoding and then process the data according to your particular scenarios. Due to the limitations of Flutter, this callback does not support sending processed video data back to the SDK. The video data that this callback gets has been preprocessed, with its content cropped and rotated, and the image enhanced. + /// After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. In this callback, you can get the video data before encoding and then process the data according to your particular scenarios. + /// Due to the limitations of Flutter, this callback does not support sending processed video data back to the SDK. + /// The video data that this callback gets has been preprocessed, with its content cropped and rotated, and the image enhanced. /// - /// * [videoFrame] The video frame. See VideoFrame.The default value of the video frame data format obtained through this callback is as follows:Android: textureiOS: cvPixelBuffermacOS: YUV 420Windows: YUV 420 + /// * [videoFrame] The video frame. See VideoFrame. The default value of the video frame data format obtained through this callback is as follows: + /// Android: texture + /// iOS: cvPixelBuffer + /// macOS: YUV 420 + /// Windows: YUV 420 /// * [sourceType] The type of the video source. See VideoSourceType. final void Function(VideoSourceType sourceType, VideoFrame videoFrame)? onPreEncodeVideoFrame; @@ -1348,9 +1380,11 @@ class VideoFrameObserver { /// Occurs each time the SDK receives a video frame sent by the remote user. /// - /// After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. In this callback, you can get the video data sent from the remote end before rendering, and then process it according to the particular scenarios. If the video data type you get is RGBA, the SDK does not support processing the data of the alpha channel. Due to the limitations of Flutter, this callback does not support sending processed video data back to the SDK. + /// After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. In this callback, you can get the video data sent from the remote end before rendering, and then process it according to the particular scenarios. + /// If the video data type you get is RGBA, the SDK does not support processing the data of the alpha channel. + /// Due to the limitations of Flutter, this callback does not support sending processed video data back to the SDK. /// - /// * [videoFrame] The video frame. See VideoFrame.The default value of the video frame data format obtained through this callback is as follows: + /// * [videoFrame] The video frame. See VideoFrame. The default value of the video frame data format obtained through this callback is as follows: /// Android: texture /// iOS: cvPixelBuffer /// macOS: YUV 420 @@ -1367,11 +1401,11 @@ class VideoFrameObserver { /// The process mode of the video frame: @JsonEnum(alwaysCreate: true) enum VideoFrameProcessMode { - /// Read-only mode.In this mode, you do not modify the video frame. The video frame observer is a renderer. + /// Read-only mode. In this mode, you do not modify the video frame. The video frame observer is a renderer. @JsonValue(0) processModeReadOnly, - /// Read and write mode.In this mode, you modify the video frame. The video frame observer is a video filter. + /// Read and write mode. In this mode, you modify the video frame. The video frame observer is a video filter. @JsonValue(1) processModeReadWrite, } diff --git a/lib/src/agora_media_base.g.dart b/lib/src/agora_media_base.g.dart index 9fac5b89f..497e7cdd5 100644 --- a/lib/src/agora_media_base.g.dart +++ b/lib/src/agora_media_base.g.dart @@ -282,6 +282,7 @@ AudioFrame _$AudioFrameFromJson(Map json) => AudioFrame( samplesPerSec: json['samplesPerSec'] as int?, renderTimeMs: json['renderTimeMs'] as int?, avsyncType: json['avsync_type'] as int?, + presentationMs: json['presentationMs'] as int?, ); Map _$AudioFrameToJson(AudioFrame instance) { @@ -301,6 +302,7 @@ Map _$AudioFrameToJson(AudioFrame instance) { writeNotNull('samplesPerSec', instance.samplesPerSec); writeNotNull('renderTimeMs', instance.renderTimeMs); writeNotNull('avsync_type', instance.avsyncType); + writeNotNull('presentationMs', instance.presentationMs); return val; } diff --git a/lib/src/agora_media_engine.dart b/lib/src/agora_media_engine.dart index 5313f0009..cd31c463f 100644 --- a/lib/src/agora_media_engine.dart +++ b/lib/src/agora_media_engine.dart @@ -38,9 +38,9 @@ extension AudioMixingDualMonoModeExt on AudioMixingDualMonoMode { abstract class MediaEngine { /// Registers an audio frame observer object. /// - /// Call this method to register an audio frame observer object (register a callback). When you need the SDK to trigger onMixedAudioFrame , onRecordAudioFrame , onPlaybackAudioFrame or onEarMonitoringAudioFrame callback, you need to use this method to register the callbacks. Ensure that you call this method before joining a channel. + /// Call this method to register an audio frame observer object (register a callback). When you need the SDK to trigger onMixedAudioFrame, onRecordAudioFrame, onPlaybackAudioFrame or onEarMonitoringAudioFrame callback, you need to use this method to register the callbacks. Ensure that you call this method before joining a channel. /// - /// * [observer] The observer object instance. See AudioFrameObserver. Agora recommends calling this method after receiving onLeaveChannel to release the audio observer object. + /// * [observer] The observer instance. See AudioFrameObserver. Agora recommends calling this method after receiving onLeaveChannel to release the audio observer object. /// /// 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. @@ -48,17 +48,35 @@ 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. 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 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. + /// 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. /// - /// * [observer] The observer object instance. See VideoFrameObserver. + /// * [observer] The observer instance. See VideoFrameObserver. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void registerVideoFrameObserver(VideoFrameObserver observer); /// 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. 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. /// /// * [observer] The video frame observer object. See VideoEncodedFrameObserver. /// @@ -72,12 +90,19 @@ abstract class MediaEngine { /// * [trackId] The audio track ID. If you want to publish a custom external audio source, set this parameter to the ID of the corresponding custom audio track you want to publish. /// /// 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. + /// 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 pushAudioFrame({required AudioFrame frame, int trackId = 0}); /// 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 method call, 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. 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: 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. + /// Before calling this method, you need to call setExternalAudioSink to notify the app to enable and set the external rendering. After a successful method call, 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. + /// 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: + /// 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. /// /// * [frame] Pointers to AudioFrame. /// @@ -89,13 +114,14 @@ abstract class MediaEngine { /// /// Call this method before joining a channel. /// - /// * [enabled] Whether to use the external video source:true: Use the external video source. The SDK prepares to accept the external video frame.false: (Default) Do not use the external video source. - /// * [useTexture] Whether to use the external video frame in the Texture format.true: Use the external video frame in the Texture format.false: (Default) Do not use the external video frame in the Texture format. + /// * [enabled] Whether to use the external video source: true : Use the external video source. The SDK prepares to accept the external video frame. false : (Default) Do not use the external video source. + /// * [useTexture] Whether to use the external video frame in the Texture format. true : Use the external video frame in the Texture format. false : (Default) Do not use the external video frame in the Texture format. /// * [sourceType] Whether the external video frame is encoded. See ExternalVideoSourceType. - /// * [encodedVideoOption] Video encoding options. This parameter needs to be set if sourceType is encodedVideoFrame. To set this parameter, contact . + /// * [encodedVideoOption] Video encoding options. This parameter needs to be set if sourceType is encodedVideoFrame. To set this parameter, contact. /// /// 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. + /// 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 setExternalVideoSource( {required bool enabled, required bool useTexture, @@ -104,17 +130,17 @@ abstract class MediaEngine { /// Sets the external audio source parameters. /// - /// Call this method before joining a channel. + /// Deprecated: This method is deprecated, use createCustomAudioTrack instead. Call this method before joining a channel. /// - /// * [enabled] Whether to enable the external audio source:true: Enable the external audio source.false: (Default) Disable the external audio source. + /// * [enabled] Whether to enable the external audio source: true : Enable the external audio source. false : (Default) Disable the external audio source. /// * [sampleRate] The sample rate (Hz) of the external audio source which can be set as 8000, 16000, 32000, 44100, or 48000. /// * [channels] The number of channels of the external audio source, which can be set as 1 (Mono) or 2 (Stereo). - /// * [sourceNumber] The number of external audio sources. The value of this parameter should be larger than 0. The SDK creates a corresponding number of custom audio tracks based on this parameter value and names the audio tracks starting from 0. In ChannelMediaOptions, you can set publishCustomAudioSourceId to the audio track ID you want to publish. - /// * [localPlayback] Whether to play the external audio source:true: Play the external audio source.false: (Default) Do not play the external source. - /// * [publish] Whether to publish audio to the remote users:true: (Default) Publish audio to the remote users.false: Do not publish audio to the remote users. + /// * [localPlayback] Whether to play the external audio source: true : Play the external audio source. false : (Default) Do not play the external source. + /// * [publish] Whether to publish audio to the remote users: true : (Default) Publish audio to the remote users. false : Do not publish audio to the remote users. /// /// 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. + /// 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 setExternalAudioSource( {required bool enabled, required int sampleRate, @@ -122,15 +148,19 @@ abstract class MediaEngine { bool localPlayback = false, bool publish = true}); - /// Creates a customized audio track. + /// Creates a custom audio track. /// - /// When you need to publish multiple custom captured audios in the channel, you can refer to the following steps: Call this method to create a custom audio track and get the audio track ID. In ChannelMediaOptions of each channel, set publishCustomAduioTrackId to the audio track ID that you want to publish, and set publishCustomAudioTrack to true . If you call pushAudioFrame trackId as the audio track ID set in step 2, you can publish the corresponding custom audio source in multiple channels. + /// To publish a custom audio source to multiple channels, see the following steps: + /// Call this method to create a custom audio track and get the audio track ID. + /// In ChannelMediaOptions of each channel, set publishCustomAduioTrackId to the audio track ID that you want to publish, and set publishCustomAudioTrack to true. + /// If you call pushAudioFrame, and specify trackId as the audio track ID set in step 2, you can publish the corresponding custom audio source in multiple channels. /// - /// * [trackType] The type of the custom audio track. See AudioTrackType. + /// * [trackType] The type of the custom audio track. See AudioTrackType. If audioTrackDirect is specified for this parameter, you must set publishMicrophoneTrack to false in ChannelMediaOptions when calling joinChannel to join the channel; otherwise, joining the channel fails and returns the error code -2. /// * [config] The configuration of the custom audio track. See AudioTrackConfig. /// /// Returns - /// If the method call is successful, the audio track ID is returned as the unique identifier of the audio track. If the method call fails, a negative value is returned. + /// If the method call is successful, the audio track ID is returned as the unique identifier of the audio track. + /// If the method call fails, a negative value is returned. Future createCustomAudioTrack( {required AudioTrackType trackType, required AudioTrackConfig config}); @@ -139,19 +169,23 @@ abstract class MediaEngine { /// * [trackId] The custom audio track ID returned in createCustomAudioTrack. /// /// 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. + /// 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 destroyCustomAudioTrack(int trackId); /// Sets the external audio sink. /// /// This method applies to scenarios where you want to use external audio data for playback. After you set the external audio sink, you can call pullAudioFrame to pull remote audio frames. The app can process the remote audio and play it with the audio effects that you want. /// - /// * [enabled] Whether to enable or disable the external audio sink:true: Enables the external audio sink.false: (Default) Disables the external audio sink. + /// * [enabled] Whether to enable or disable the external audio sink: true : Enables the external audio sink. false : (Default) Disables the external audio sink. /// * [sampleRate] The sample rate (Hz) of the external audio sink, which can be set as 16000, 32000, 44100, or 48000. - /// * [channels] The number of audio channels of the external audio sink:1: Mono.2: Stereo. + /// * [channels] The number of audio channels of the external audio sink: + /// 1: Mono. + /// 2: Stereo. /// /// 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. + /// 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 setExternalAudioSink( {required bool enabled, required int sampleRate, required int channels}); @@ -161,7 +195,7 @@ abstract class MediaEngine { /// Pushes the external raw video frame to the SDK. /// - /// If you call createCustomVideoTrack method to get the video track ID, set the customVideoTrackId parameter to the video track ID you want to publish in the ChannelMediaOptions of each channel, and set the publishCustomVideoTrack parameter to true , you can call this method to push the unencoded external video frame to the SDK. + /// If you call createCustomVideoTrack method to get the video track ID, set the customVideoTrackId parameter to the video track ID you want to publish in the ChannelMediaOptions of each channel, and set the publishCustomVideoTrack parameter to true, you can call this method to push the unencoded external video frame to the SDK. /// /// * [frame] The external raw video frame to be pushed. See ExternalVideoFrame. /// * [videoTrackId] The video track ID returned by calling the createCustomVideoTrack method. The default value is 0. @@ -186,7 +220,8 @@ abstract class MediaEngine { /// * [observer] The audio frame observer, reporting the reception of each audio frame. See AudioFrameObserver. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void unregisterAudioFrameObserver(AudioFrameObserver observer); /// Unregisters the video frame observer. diff --git a/lib/src/agora_media_player.dart b/lib/src/agora_media_player.dart index 8a0e56ac4..92c5b05cb 100644 --- a/lib/src/agora_media_player.dart +++ b/lib/src/agora_media_player.dart @@ -5,7 +5,8 @@ abstract class MediaPlayer { /// Gets the ID of the media player. /// /// Returns - /// ≥ 0: Success. The ID of the media player. < 0: Failure. + /// ≥ 0: Success. The ID of the media player. + /// < 0: Failure. int getMediaPlayerId(); /// Opens the media resource. @@ -16,7 +17,8 @@ abstract class MediaPlayer { /// * [startPos] The starting position (ms) for playback. Default value is 0. /// /// 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. + /// 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 open({required String url, required int startPos}); /// Opens a media file and configures the playback scenarios. @@ -26,53 +28,62 @@ abstract class MediaPlayer { /// * [source] Media resources. See MediaSource. /// /// 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. + /// 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 openWithMediaSource(MediaSource source); /// Plays the media file. /// - /// After calling open or seek , you can call this method to play the media file. + /// After calling open or seek, you can call this method to play the media file. /// /// 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. + /// 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 play(); /// Pauses the playback. /// /// 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. + /// 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 pause(); /// Stops playing the media track. /// /// 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. + /// 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 stop(); /// Resumes playing the media file. /// /// 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. + /// 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 resume(); /// Seeks to a new playback position. /// - /// fter successfully calling this method, you will receive the onPlayerEvent callback, reporting the result of the seek operation to the new playback position. To play the media file from a specific position, do the following: Call this method to seek to the position you want to begin playback. Call the play method to play the media file. + /// After successfully calling this method, you will receive the onPlayerEvent callback, reporting the result of the seek operation to the new playback position. To play the media file from a specific position, do the following: + /// Call this method to seek to the position you want to begin playback. + /// Call the play method to play the media file. /// /// * [newPos] The new playback position (ms). /// /// 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. + /// 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 seek(int newPos); /// Sets the pitch of the current media resource. /// - /// Call this method after calling open . + /// Call this method after calling open. /// /// * [pitch] Sets the pitch of the local music file by the chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file. /// /// 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. + /// 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 setAudioPitch(int pitch); /// Gets the duration of the media resource. @@ -84,45 +95,53 @@ abstract class MediaPlayer { /// Gets current local playback progress. /// /// Returns - /// Returns the current playback progress (ms) if the call succeeds. < 0: Failure. See MediaPlayerError . + /// Returns the current playback progress (ms) if the call succeeds. + /// < 0: Failure. See MediaPlayerError. Future getPlayPosition(); /// Gets the number of the media streams in the media resource. /// - /// Call this method after calling open . + /// Call this method after calling open. /// /// Returns - /// The number of the media streams in the media resource if the method call succeeds. < 0: Failure. See MediaPlayerError . + /// The number of the media streams in the media resource if the method call succeeds. + /// < 0: Failure. See MediaPlayerError. Future getStreamCount(); /// Gets the detailed information of the media stream. /// - /// Call this method after calling getStreamCount . + /// Call this method after calling getStreamCount. /// /// * [index] The index of the media stream. /// /// 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. + /// If the call fails, returns NULL. Future getStreamInfo(int index); /// Sets the loop playback. /// - /// If you want to loop, call this method and set the number of the loops. When the loop finishes, the SDK triggers onPlayerSourceStateChanged and reports the playback state as playerStatePlaybackAllLoopsCompleted . + /// If you want to loop, call this method and set the number of the loops. When the loop finishes, the SDK triggers onPlayerSourceStateChanged and reports the playback state as playerStatePlaybackAllLoopsCompleted. /// /// * [loopCount] The number of times the audio effect loops: /// /// 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. + /// 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 setLoopCount(int loopCount); /// Sets the channel mode of the current audio file. /// - /// Call this method after calling open . + /// Call this method after calling open. /// - /// * [speed] The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:50: Half the original speed.100: The original speed.400: 4 times the original speed. + /// * [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. + /// 100: The original speed. + /// 400: 4 times the original speed. /// /// 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. + /// 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 setPlaybackSpeed(int speed); /// Selects the audio track used during playback. @@ -132,18 +151,11 @@ abstract class MediaPlayer { /// * [index] The index of the audio track. /// /// 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. + /// 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 selectAudioTrack(int index); - /// Sets the private options for the media player. - /// - /// The media player supports setting private options by key and value. Under normal circumstances, you do not need to know the private option settings, and just use the default option settings. Ensure that you call this method before open . If you need to push streams with SEI into the CDN, call setPlayerOptionInInt ("sei_data_with_uuid", 1) ; otherwise, the loss of SEI might occurs. - /// - /// * [key] The key of the option. - /// * [value] The value of the key. - /// - /// 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. + /// @nodoc Future setPlayerOptionInInt({required String key, required int value}); /// @nodoc @@ -162,15 +174,16 @@ abstract class MediaPlayer { /// Gets current playback state. /// /// Returns - /// The current playback state. See MediaPlayerState . + /// The current playback state. See MediaPlayerState. Future getState(); /// Sets whether to mute the media file. /// - /// * [muted] Whether to mute the media file:true: Mute the media file.false: (Default) Unmute the media file. + /// * [muted] Whether to mute the media file: true : Mute the media file. false : (Default) Unmute the media file. /// /// 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. + /// 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 mute(bool muted); /// Reports whether the media resource is muted. @@ -181,7 +194,9 @@ abstract class MediaPlayer { /// Adjusts the local playback volume. /// - /// * [volume] The local playback volume, which ranges from 0 to 100:0: Mute.100: (Default) The original volume. + /// * [volume] The local playback volume, which ranges from 0 to 100: + /// 0: Mute. + /// 100: (Default) 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. @@ -190,14 +205,19 @@ abstract class MediaPlayer { /// Gets the local playback volume. /// /// Returns - /// The local playback volume, which ranges from 0 to 100. 0: Mute. 100: (Default) The original volume. + /// The local playback volume, which ranges from 0 to 100. + /// 0: Mute. + /// 100: (Default) The original volume. Future getPlayoutVolume(); /// Adjusts the volume of the media file for publishing. /// /// After connected to the Agora server, you can call this method to adjust the volume of the media file heard by the remote user. /// - /// * [volume] The volume, which ranges from 0 to 400:0: Mute.100: (Default) The original volume.400: Four times the original volume (amplifying the audio signals by four times). + /// * [volume] The volume, which ranges from 0 to 400: + /// 0: Mute. + /// 100: (Default) The original volume. + /// 400: Four times the original volume (amplifying the audio signals by four times). /// /// 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. @@ -206,13 +226,15 @@ abstract class MediaPlayer { /// Gets the volume of the media file for publishing. /// /// Returns - /// ≥ 0: The remote playback volume. < 0: Failure. + /// ≥ 0: The remote playback volume. + /// < 0: Failure. Future getPublishSignalVolume(); /// Sets the view. /// /// 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. + /// 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 setView(int view); /// Sets the render mode of the media player. @@ -220,7 +242,8 @@ abstract class MediaPlayer { /// * [renderMode] Sets the render mode of the view. See RenderModeType. /// /// 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. + /// 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 setRenderMode(RenderModeType renderMode); /// Registers a media player observer. @@ -228,7 +251,8 @@ abstract class MediaPlayer { /// * [observer] The player observer, listening for events during the playback. See MediaPlayerSourceObserver. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void registerPlayerSourceObserver(MediaPlayerSourceObserver observer); /// Releases a media player observer. @@ -236,7 +260,8 @@ abstract class MediaPlayer { /// * [observer] The player observer, listening for events during the playback. See MediaPlayerSourceObserver. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void unregisterPlayerSourceObserver(MediaPlayerSourceObserver observer); /// Registers an audio frame observer object. @@ -256,7 +281,8 @@ abstract class MediaPlayer { /// * [observer] The audio observer. See AudioPcmFrameSink. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void unregisterAudioFrameObserver(AudioPcmFrameSink observer); /// Registers a video frame observer object. @@ -266,7 +292,8 @@ abstract class MediaPlayer { /// * [observer] The video observer, reporting the reception of each video frame. See MediaPlayerVideoFrameObserver. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void registerVideoFrameObserver(MediaPlayerVideoFrameObserver observer); /// Unregisters the video frame observer. @@ -274,7 +301,8 @@ abstract class MediaPlayer { /// * [observer] The video observer, reporting the reception of each video frame. See MediaPlayerVideoFrameObserver. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void unregisterVideoFrameObserver(MediaPlayerVideoFrameObserver observer); /// @nodoc @@ -287,12 +315,15 @@ abstract class MediaPlayer { /// 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 open . This method only applies to stereo audio files. + /// 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 open. + /// This method only applies to stereo audio files. /// /// * [mode] The channel mode. See AudioDualMonoMode. /// /// 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. + /// 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 setAudioDualMonoMode(AudioDualMonoMode mode); /// @nodoc @@ -328,24 +359,33 @@ abstract class MediaPlayer { /// Switches the media resource being played. /// - /// 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. 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. + /// 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. + /// 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. 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. /// /// 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. + /// 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 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. 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. /// /// 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. + /// 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 preloadSrc({required String src, required int startPos}); /// Plays preloaded media resources. @@ -355,7 +395,8 @@ abstract class MediaPlayer { /// * [src] The URL of the media resource in the playlist must be consistent with the src set by the preloadSrc method; otherwise, the media resource cannot be played. /// /// 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. + /// 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 playPreloadedSrc(String src); /// Unloads media resources that are preloaded. @@ -365,7 +406,8 @@ abstract class MediaPlayer { /// * [src] The URL of the media resource. /// /// 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. + /// 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 unloadSrc(String src); /// Enables or disables the spatial audio effect for the media player. @@ -375,7 +417,8 @@ abstract class MediaPlayer { /// * [params] The spatial audio effect parameters of the media player. See SpatialAudioParams. /// /// 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. + /// 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 setSpatialAudioParams(SpatialAudioParams params); /// @nodoc @@ -390,7 +433,8 @@ abstract class MediaPlayerCacheManager { /// The cached media file currently being played will not be deleted. /// /// 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. See MediaPlayerError . + /// 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. See MediaPlayerError. Future removeAllCaches(); /// Deletes a cached media file that is the least recently used. @@ -398,7 +442,8 @@ abstract class MediaPlayerCacheManager { /// You can call this method to delete a cached media file when the storage space for the cached files is about to reach its limit. After you call this method, the SDK deletes the cached media file that is least used. The cached media file currently being played will not be deleted. /// /// 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. See MediaPlayerError . + /// 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. See MediaPlayerError. Future removeOldCache(); /// Deletes a cached media file. @@ -408,7 +453,8 @@ abstract class MediaPlayerCacheManager { /// * [uri] The URI (Uniform Resource Identifier) of the media file to be deleted. /// /// 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. See MediaPlayerError . + /// 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. See MediaPlayerError. Future removeCacheByUri(String uri); /// Sets the storage path for the media files that you want to cache. @@ -418,7 +464,8 @@ abstract class MediaPlayerCacheManager { /// * [path] The absolute path of the media files to be cached. Ensure that the directory for the media files exists and is writable. /// /// 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. See MediaPlayerError . + /// 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. See MediaPlayerError. Future setCacheDir(String path); /// Sets the maximum number of media files that can be cached. @@ -426,7 +473,8 @@ abstract class MediaPlayerCacheManager { /// * [count] The maximum number of media files that can be cached. The default value is 1,000. /// /// 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. See MediaPlayerError . + /// 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. See MediaPlayerError. Future setMaxCacheFileCount(int count); /// Sets the maximum size of the aggregate storage space for cached media files. @@ -434,17 +482,19 @@ abstract class MediaPlayerCacheManager { /// * [cacheSize] The maximum size (bytes) of the aggregate storage space for cached media files. The default value is 1 GB. /// /// 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. See MediaPlayerError . + /// 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. See MediaPlayerError. Future setMaxCacheFileSize(int cacheSize); /// Sets whether to delete cached media files automatically. /// /// If you enable this function to remove cached media files automatically, when the cached media files exceed either the number or size limit you set, the SDK automatically deletes the least recently used cache file. /// - /// * [enable] Whether to enable the SDK to delete cached media files automatically:true: Delete cached media files automatically.false: (Default) Do not delete cached media files automatically. + /// * [enable] Whether to enable the SDK to delete cached media files automatically: true : Delete cached media files automatically. false : (Default) Do not delete cached media files automatically. /// /// 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. See MediaPlayerError . + /// 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. See MediaPlayerError. Future enableAutoRemoveCache(bool enable); /// Gets the storage path of the cached media files. @@ -454,7 +504,8 @@ abstract class MediaPlayerCacheManager { /// * [length] An input parameter; the maximum length of the cache file storage path string. /// /// Returns - /// The call succeeds, and the SDK returns the storage path of the cached media files. < 0: Failure. See MediaPlayerError . + /// The call succeeds, and the SDK returns the storage path of the cached media files. + /// < 0: Failure. See MediaPlayerError. Future getCacheDir(int length); /// Gets the maximum number of media files that can be cached. @@ -462,7 +513,8 @@ abstract class MediaPlayerCacheManager { /// By default, the maximum number of media files that can be cached is 1,000. /// /// Returns - /// > 0: The call succeeds and returns the maximum number of media files that can be cached. < 0: Failure. See MediaPlayerError . + /// > 0: The call succeeds and returns the maximum number of media files that can be cached. + /// < 0: Failure. See MediaPlayerError. Future getMaxCacheFileCount(); /// Gets the maximum size of the aggregate storage space for cached media files. @@ -470,13 +522,15 @@ abstract class MediaPlayerCacheManager { /// By default, the maximum size of the aggregate storage space for cached media files is 1 GB. You can call the setMaxCacheFileSize method to set the limit according to your scenarios. /// /// Returns - /// > 0: The call succeeds and returns the maximum size (in bytes) of the aggregate storage space for cached media files. < 0: Failure. See MediaPlayerError . + /// > 0: The call succeeds and returns the maximum size (in bytes) of the aggregate storage space for cached media files. + /// < 0: Failure. See MediaPlayerError. Future getMaxCacheFileSize(); /// Gets the number of media files that are cached. /// /// Returns - /// ≥ 0: The call succeeds and returns the number of media files that are cached. < 0: Failure. See MediaPlayerError . + /// ≥ 0: The call succeeds and returns the number of media files that are cached. + /// < 0: Failure. See MediaPlayerError. Future getCacheFileCount(); } diff --git a/lib/src/agora_media_player_source.dart b/lib/src/agora_media_player_source.dart index 010d613ed..c55853102 100644 --- a/lib/src/agora_media_player_source.dart +++ b/lib/src/agora_media_player_source.dart @@ -54,7 +54,9 @@ 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 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. /// /// * [playCachedBuffer] The playback duration (ms) that the buffered data can support. final void Function(int playCachedBuffer)? onPlayBufferUpdated; diff --git a/lib/src/agora_media_player_types.dart b/lib/src/agora_media_player_types.dart index 5ff7c578a..4bbf71a9e 100644 --- a/lib/src/agora_media_player_types.dart +++ b/lib/src/agora_media_player_types.dart @@ -487,7 +487,7 @@ class PlayerUpdatedInfo { @JsonKey(name: 'deviceId') final String? deviceId; - /// The statistics about the media file being cached.If you call the openWithMediaSource method and set enableCache as true, the statistics about the media file being cached is updated every second after the media file is played. See CacheStatistics. + /// The statistics about the media file being cached. If you call the openWithMediaSource method and set enableCache as true, the statistics about the media file being cached is updated every second after the media file is played. See CacheStatistics. @JsonKey(name: 'cacheStatistics') final CacheStatistics? cacheStatistics; @@ -524,19 +524,22 @@ class MediaSource { @JsonKey(name: 'startPos') final int? startPos; - /// Whether to enable autoplay once the media file is opened:true: (Default) Enables autoplay.false: Disables autoplay.If autoplay is disabled, you need to call the play method to play a media file after it is opened. + /// Whether to enable autoplay once the media file is opened: true : (Default) Enables autoplay. false : Disables autoplay. If autoplay is disabled, you need to call the play method to play a media file after it is opened. @JsonKey(name: 'autoPlay') final bool? autoPlay; - /// Whether to cache the media file when it is being played:true:Enables caching.false: (Default) Disables caching.Agora only supports caching on-demand audio and video streams that are not transmitted in HLS protocol.If you need to enable caching, pass in a value to uri; otherwise, caching is based on the url of the media file.If you enable this function, the Media Player caches part of the media file being played on your local device, and you can play the cached media file without internet connection. The statistics about the media file being cached are updated every second after the media file is played. See CacheStatistics. + /// Whether to cache the media file when it is being played: true :Enables caching. false : (Default) Disables caching. + /// Agora only supports caching on-demand audio and video streams that are not transmitted in HLS protocol. + /// If you need to enable caching, pass in a value to uri; otherwise, caching is based on the url of the media file. + /// If you enable this function, the Media Player caches part of the media file being played on your local device, and you can play the cached media file without internet connection. The statistics about the media file being cached are updated every second after the media file is played. See CacheStatistics. @JsonKey(name: 'enableCache') final bool? enableCache; - /// Whether the media resource to be opened is a live stream or on-demand video distributed through Media Broadcast service:true: The media resource to be played is a live or on-demand video distributed through Media Broadcast service.false: (Default) The media resource is not a live stream or on-demand video distributed through Media Broadcast service.If you need to open a live stream or on-demand video distributed through Broadcast Streaming service, pass in the URL of the media resource to url, and set isAgoraSource as true; otherwise, you don't need to set the isAgoraSource parameter. + /// Whether the media resource to be opened is a live stream or on-demand video distributed through Media Broadcast service: true : The media resource to be played is a live or on-demand video distributed through Media Broadcast service. false : (Default) The media resource is not a live stream or on-demand video distributed through Media Broadcast service. If you need to open a live stream or on-demand video distributed through Broadcast Streaming service, pass in the URL of the media resource to url, and set isAgoraSource as true; otherwise, you don't need to set the isAgoraSource parameter. @JsonKey(name: 'isAgoraSource') final bool? isAgoraSource; - /// Whether the media resource to be opened is a live stream:true: The media resource is a live stream.false: (Default) The media resource is not a live stream.If the media resource you want to open is a live stream, Agora recommends that you set this parameter as true so that the live stream can be loaded more quickly.If the media resource you open is not a live stream, but you set isLiveSource as true, the media resource is not to be loaded more quickly. + /// Whether the media resource to be opened is a live stream: true : The media resource is a live stream. false : (Default) The media resource is not a live stream. If the media resource you want to open is a live stream, Agora recommends that you set this parameter as true so that the live stream can be loaded more quickly. If the media resource you open is not a live stream, but you set isLiveSource as true, the media resource is not to be loaded more quickly. @JsonKey(name: 'isLiveSource') final bool? isLiveSource; diff --git a/lib/src/agora_music_content_center.dart b/lib/src/agora_music_content_center.dart index 0a30d4d71..90aa9b7f6 100644 --- a/lib/src/agora_music_content_center.dart +++ b/lib/src/agora_music_content_center.dart @@ -309,6 +309,7 @@ class MusicContentCenterEventHandler { this.onMusicChartsResult, this.onMusicCollectionResult, this.onLyricResult, + this.onSongSimpleInfoResult, this.onPreLoadEvent, }); @@ -321,11 +322,16 @@ class MusicContentCenterEventHandler { MusicContentCenterStatusCode errorCode)? onMusicCollectionResult; /// @nodoc - final void Function(String requestId, String lyricUrl, + final void Function(String requestId, int songCode, String lyricUrl, MusicContentCenterStatusCode errorCode)? onLyricResult; + /// @nodoc + final void Function(String requestId, int songCode, String simpleInfo, + MusicContentCenterStatusCode errorCode)? onSongSimpleInfoResult; + /// @nodoc final void Function( + String requestId, int songCode, int percent, String lyricUrl, @@ -409,7 +415,7 @@ abstract class MusicContentCenter { String? jsonOption}); /// @nodoc - Future preload({required int songCode, String? jsonOption}); + Future preload(int songCode); /// @nodoc Future removeCache(int songCode); @@ -422,4 +428,11 @@ abstract class MusicContentCenter { /// @nodoc Future getLyric({required int songCode, int lyricType = 0}); + + /// @nodoc + Future getSongSimpleInfo(int songCode); + + /// @nodoc + Future getInternalSongCode( + {required int songCode, required String jsonOption}); } diff --git a/lib/src/agora_rtc_engine.dart b/lib/src/agora_rtc_engine.dart index 4847df0e4..af228bb36 100644 --- a/lib/src/agora_rtc_engine.dart +++ b/lib/src/agora_rtc_engine.dart @@ -28,11 +28,11 @@ enum MediaDeviceType { @JsonValue(4) audioApplicationPlayoutDevice, - /// (For macOS only)5: Virtual audio playback device (virtual sound card). + /// (For macOS only) 5: Virtual audio playback device (virtual sound card). @JsonValue(5) audioVirtualPlayoutDevice, - /// (For macOS only)6: Virtual audio capturing device (virtual sound card). + /// (For macOS only) 6: Virtual audio capturing device (virtual sound card). @JsonValue(6) audioVirtualRecordingDevice, } @@ -61,11 +61,11 @@ enum AudioMixingStateType { @JsonValue(711) audioMixingStatePaused, - /// 713: The music file stops playing.The possible reasons include:audioMixingReasonAllLoopsCompleted(723)audioMixingReasonStoppedByUser(724) + /// 713: The music file stops playing. The possible reasons include: audioMixingReasonAllLoopsCompleted (723) audioMixingReasonStoppedByUser (724) @JsonValue(713) audioMixingStateStopped, - /// 714: An error occurs during the playback of the audio mixing file.The possible reasons include:audioMixingReasonCanNotOpen(701)audioMixingReasonTooFrequentCall(702)audioMixingReasonInterruptedEof(703) + /// 714: An error occurs during the playback of the audio mixing file. The possible reasons include: audioMixingReasonCanNotOpen (701) audioMixingReasonTooFrequentCall (702) audioMixingReasonInterruptedEof (703) @JsonValue(714) audioMixingStateFailed, } @@ -370,11 +370,11 @@ class LocalVideoStats { @JsonKey(name: 'uid') final int? uid; - /// The actual bitrate (Kbps) while sending the local video stream.This value does not include the bitrate for resending the video after packet loss. + /// The actual bitrate (Kbps) while sending the local video stream. This value does not include the bitrate for resending the video after packet loss. @JsonKey(name: 'sentBitrate') final int? sentBitrate; - /// The actual frame rate (fps) while sending the local video stream.This value does not include the frame rate for resending the video after packet loss. + /// The actual frame rate (fps) while sending the local video stream. This value does not include the frame rate for resending the video after packet loss. @JsonKey(name: 'sentFrameRate') final int? sentFrameRate; @@ -430,7 +430,7 @@ class LocalVideoStats { @JsonKey(name: 'qualityAdaptIndication') final QualityAdaptIndication? qualityAdaptIndication; - /// The bitrate (Kbps) while encoding the local video stream.This value does not include the bitrate for resending the video after packet loss. + /// The bitrate (Kbps) while encoding the local video stream. This value does not include the bitrate for resending the video after packet loss. @JsonKey(name: 'encodedBitrate') final int? encodedBitrate; @@ -454,7 +454,9 @@ class LocalVideoStats { @JsonKey(name: 'dualStreamEnabled') final bool? dualStreamEnabled; - /// The local video encoding acceleration type. 0: Software encoding is applied without acceleration.1: Hardware encoding is applied for acceleration. + /// The local video encoding acceleration type. + /// 0: Software encoding is applied without acceleration. + /// 1: Hardware encoding is applied for acceleration. @JsonKey(name: 'hwEncoderAccelerating') final int? hwEncoderAccelerating; @@ -502,7 +504,7 @@ class RemoteAudioStats { @JsonKey(name: 'networkTransportDelay') final int? networkTransportDelay; - /// The network delay (ms) from the audio receiver to the jitter buffer.When the receiving end is an audience member and audienceLatencyLevel of ClientRoleOptions is 1, this parameter does not take effect. + /// The network delay (ms) from the audio receiver to the jitter buffer. When the receiving end is an audience member and audienceLatencyLevel of ClientRoleOptions is 1, this parameter does not take effect. @JsonKey(name: 'jitterBufferDelay') final int? jitterBufferDelay; @@ -530,7 +532,7 @@ class RemoteAudioStats { @JsonKey(name: 'frozenRate') final int? frozenRate; - /// The quality of the remote audio stream in the reported interval. The quality is determined by the Agora real-time audio MOS (Mean Opinion Score) measurement method. The return value range is [0, 500]. Dividing the return value by 100 gets the MOS score, which ranges from 0 to 5. The higher the score, the better the audio quality.The subjective perception of audio quality corresponding to the Agora real-time audio MOS scores is as follows:MOS scorePerception of audio qualityGreater than 4Excellent. The audio sounds clear and smooth.From 3.5 to 4Good. The audio has some perceptible impairment but still sounds clear.From 3 to 3.5Fair. The audio freezes occasionally and requires attentive listening.From 2.5 to 3Poor. The audio sounds choppy and requires considerable effort to understand.From 2 to 2.5Bad. The audio has occasional noise. Consecutive audio dropouts occur, resulting in some information loss. The users can communicate only with difficulty.Less than 2Very bad. The audio has persistent noise. Consecutive audio dropouts are frequent, resulting in severe information loss. Communication is nearly impossible. + /// The quality of the remote audio stream in the reported interval. The quality is determined by the Agora real-time audio MOS (Mean Opinion Score) measurement method. The return value range is [0, 500]. Dividing the return value by 100 gets the MOS score, which ranges from 0 to 5. The higher the score, the better the audio quality. The subjective perception of audio quality corresponding to the Agora real-time audio MOS scores is as follows: MOS score Perception of audio quality Greater than 4 Excellent. The audio sounds clear and smooth. From 3.5 to 4 Good. The audio has some perceptible impairment but still sounds clear. From 3 to 3.5 Fair. The audio freezes occasionally and requires attentive listening. From 2.5 to 3 Poor. The audio sounds choppy and requires considerable effort to understand. From 2 to 2.5 Bad. The audio has occasional noise. Consecutive audio dropouts occur, resulting in some information loss. The users can communicate only with difficulty. Less than 2 Very bad. The audio has persistent noise. Consecutive audio dropouts are frequent, resulting in severe information loss. Communication is nearly impossible. @JsonKey(name: 'mosValue') final int? mosValue; @@ -542,7 +544,7 @@ class RemoteAudioStats { @JsonKey(name: 'plcCount') final int? plcCount; - /// The total active time (ms) between the start of the audio call and the callback of the remote user.The active time refers to the total duration of the remote user without the mute state. + /// The total active time (ms) between the start of the audio call and the callback of the remote user. The active time refers to the total duration of the remote user without the mute state. @JsonKey(name: 'totalActiveTime') final int? totalActiveTime; @@ -598,7 +600,7 @@ class RemoteVideoStats { @JsonKey(name: 'uid') final int? uid; - /// Deprecated:In scenarios where audio and video are synchronized, you can get the video delay data from networkTransportDelay and jitterBufferDelay in RemoteAudioStats.The video delay (ms). + /// Deprecated: In scenarios where audio and video are synchronized, you can get the video delay data from networkTransportDelay and jitterBufferDelay in RemoteAudioStats. The video delay (ms). @JsonKey(name: 'delay') final int? delay; @@ -646,11 +648,11 @@ class RemoteVideoStats { @JsonKey(name: 'frozenRate') final int? frozenRate; - /// The amount of time (ms) that the audio is ahead of the video.If this value is negative, the audio is lagging behind the video. + /// The amount of time (ms) that the audio is ahead of the video. If this value is negative, the audio is lagging behind the video. @JsonKey(name: 'avSyncTimeMs') final int? avSyncTimeMs; - /// The total active time (ms) of the video.As long as the remote user or host neither stops sending the video stream nor disables the video module after joining the channel, the video is available. + /// The total active time (ms) of the video. As long as the remote user or host neither stops sending the video stream nor disables the video module after joining the channel, the video is available. @JsonKey(name: 'totalActiveTime') final int? totalActiveTime; @@ -1000,11 +1002,11 @@ class CameraCapturerConfiguration { this.format, this.followEncodeDimensionRatio}); - /// This parameter applies to Android and iOS only.The camera direction. See CameraDirection. + /// This parameter applies to Android and iOS only. The camera direction. See CameraDirection. @JsonKey(name: 'cameraDirection') final CameraDirection? cameraDirection; - /// This method applies to Windows only.The ID of the camera. The maximum length is MaxDeviceIdLengthType. + /// This method applies to Windows only. The ID of the camera. The maximum length is MaxDeviceIdLengthType. @JsonKey(name: 'deviceId') final String? deviceId; @@ -1012,7 +1014,7 @@ class CameraCapturerConfiguration { @JsonKey(name: 'format') final VideoFormat? format; - /// Whether to follow the video aspect ratio set in setVideoEncoderConfiguration:true: (Default) Follow the set video aspect ratio. The SDK crops the captured video according to the set video aspect ratio and synchronously changes the local preview screen and the video frame in onCaptureVideoFrame and onPreEncodeVideoFrame.false: Do not follow the system default audio playback device. The SDK does not change the aspect ratio of the captured video frame. + /// Whether to follow the video aspect ratio set in setVideoEncoderConfiguration : true : (Default) Follow the set video aspect ratio. The SDK crops the captured video according to the set video aspect ratio and synchronously changes the local preview screen and the video frame in onCaptureVideoFrame and onPreEncodeVideoFrame. false : Do not follow the system default audio playback device. The SDK does not change the aspect ratio of the captured video frame. @JsonKey(name: 'followEncodeDimensionRatio') final bool? followEncodeDimensionRatio; @@ -1036,19 +1038,19 @@ class ScreenCaptureConfiguration { this.params, this.regionRect}); - /// Whether to capture the window on the screen:true: Capture the window.false: (Default) Capture the screen, not the window. + /// Whether to capture the window on the screen: true : Capture the window. false : (Default) Capture the screen, not the window. @JsonKey(name: 'isCaptureWindow') final bool? isCaptureWindow; - /// (macOS only) The display ID of the screen.This parameter takes effect only when you want to capture the screen on macOS. + /// (macOS only) The display ID of the screen. This parameter takes effect only when you want to capture the screen on macOS. @JsonKey(name: 'displayId') final int? displayId; - /// (Windows only) The relative position of the shared screen to the virtual screen.This parameter takes effect only when you want to capture the screen on Windows. + /// (Windows only) The relative position of the shared screen to the virtual screen. This parameter takes effect only when you want to capture the screen on Windows. @JsonKey(name: 'screenRect') final Rectangle? screenRect; - /// (For Windows and macOS only)Window ID.This parameter takes effect only when you want to capture the window. + /// (For Windows and macOS only) Window ID. This parameter takes effect only when you want to capture the window. @JsonKey(name: 'windowId') final int? windowId; @@ -1184,11 +1186,11 @@ class ScreenCaptureSourceInfo { @JsonKey(name: 'sourceName') final String? sourceName; - /// The image content of the thumbnail. See ThumbImageBuffer + /// The image content of the thumbnail. See ThumbImageBuffer. @JsonKey(name: 'thumbImage') final ThumbImageBuffer? thumbImage; - /// The image content of the icon. See ThumbImageBuffer + /// The image content of the icon. See ThumbImageBuffer. @JsonKey(name: 'iconImage') final ThumbImageBuffer? iconImage; @@ -1200,7 +1202,7 @@ class ScreenCaptureSourceInfo { @JsonKey(name: 'sourceTitle') final String? sourceTitle; - /// Determines whether the screen is the primary display:true: The screen is the primary display.false: The screen is not the primary display. + /// Determines whether the screen is the primary display: true : The screen is the primary display. false : The screen is not the primary display. @JsonKey(name: 'primaryMonitor') final bool? primaryMonitor; @@ -1212,7 +1214,7 @@ class ScreenCaptureSourceInfo { @JsonKey(name: 'position') final Rectangle? position; - /// (For Windows only) Whether the window is minimized:true: The window is minimized.false: The window is not minimized. + /// (For Windows only) Whether the window is minimized: true : The window is minimized. false : The window is not minimized. @JsonKey(name: 'minimizeWindow') final bool? minimizeWindow; @@ -1252,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 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. @JsonKey(name: 'imageUrl') final String? imageUrl; @@ -1274,18 +1276,22 @@ 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, 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. @JsonSerializable(explicitToJson: true, includeIfNull: false) class ChannelMediaOptions { /// @nodoc const ChannelMediaOptions( {this.publishCameraTrack, this.publishSecondaryCameraTrack, + this.publishThirdCameraTrack, + this.publishFourthCameraTrack, this.publishMicrophoneTrack, this.publishScreenCaptureVideo, this.publishScreenCaptureAudio, this.publishScreenTrack, this.publishSecondaryScreenTrack, + this.publishThirdScreenTrack, + this.publishFourthScreenTrack, this.publishCustomAudioTrack, this.publishCustomAudioTrackId, this.publishCustomVideoTrack, @@ -1310,71 +1316,87 @@ class ChannelMediaOptions { this.customVideoTrackId, this.isAudioFilterable}); - /// Whether to publish the video captured by the camera:true: Publish the video captured by the camera.false: Do not publish the video captured by the camera. + /// Whether to publish the video captured by the camera: true : Publish the video captured by the camera. false : Do not publish the video captured by the camera. @JsonKey(name: 'publishCameraTrack') final bool? publishCameraTrack; - /// Whether to publish the video captured by the second camera:true: Publish the video captured by the second camera.false: Do not publish the video captured by the second camera. + /// Whether to publish the video captured by the second camera: true : Publish the video captured by the second camera. false : Do not publish the video captured by the second camera. @JsonKey(name: 'publishSecondaryCameraTrack') final bool? publishSecondaryCameraTrack; - /// Whether to publish the audio captured by the microphone:true: Publish the audio captured by the microphone.false: Do not publish the audio captured by the microphone. + /// Whether to publish the video captured by the third camera: true : Publish the video captured by the third camera. false : Do not publish the video captured by the third camera. This method is for Windows and macOS only. + @JsonKey(name: 'publishThirdCameraTrack') + final bool? publishThirdCameraTrack; + + /// Whether to publish the video captured by the fourth camera: true : Publish the video captured by the fourth camera. false : Do not publish the video captured by the fourth camera. This method is for Windows and macOS only. + @JsonKey(name: 'publishFourthCameraTrack') + final bool? publishFourthCameraTrack; + + /// Whether to publish the audio captured by the microphone: true : Publish the audio captured by the microphone. false : Do not publish the audio captured by the microphone. @JsonKey(name: 'publishMicrophoneTrack') final bool? publishMicrophoneTrack; - /// Whether to publish the video captured from the screen:true: Publish the video captured from the screen.false: Do not publish the video captured from the screen.This parameter applies to Android and iOS only. + /// Whether to publish the video captured from the screen: true : Publish the video captured from the screen. false : Do not publish the video captured from the screen. This parameter applies to Android and iOS only. @JsonKey(name: 'publishScreenCaptureVideo') final bool? publishScreenCaptureVideo; - /// Whether to publish the audio captured from the screen:true: Publish the audio captured from the screen.false: Publish the audio captured from the screen.This parameter applies to Android and iOS only. + /// Whether to publish the audio captured from the screen: true : Publish the audio captured from the screen. false : Publish the audio captured from the screen. This parameter applies to Android and iOS only. @JsonKey(name: 'publishScreenCaptureAudio') final bool? publishScreenCaptureAudio; - /// Whether to publish the video captured from the screen:true: Publish the video captured from the screen.false: (Default) Do not publish the video captured from the screen. + /// Whether to publish the video captured from the screen: true : Publish the video captured from the screen. false : Do not publish the video captured from the screen. This method is for Windows and macOS only. @JsonKey(name: 'publishScreenTrack') final bool? publishScreenTrack; - /// Whether to publish the video captured from the second screen:true: Publish the video captured from the second screen.false: Do not publish the video captured from the second screen. + /// Whether to publish the video captured from the second screen: true : Publish the video captured from the second screen. false : Do not publish the video captured from the second screen. @JsonKey(name: 'publishSecondaryScreenTrack') final bool? publishSecondaryScreenTrack; - /// Whether to publish the audio captured from a custom source:true: Publish the audio captured from the custom source.false: Do not publish the captured audio from a custom source. + /// Whether to publish the video captured from the third screen: true : Publish the captured video from the third screen. false : Do not publish the video captured from the third screen. This method is for Windows and macOS only. + @JsonKey(name: 'publishThirdScreenTrack') + final bool? publishThirdScreenTrack; + + /// Whether to publish the video captured from the fourth screen: true : Publish the captured video from the fourth screen. false : Do not publish the video captured from the fourth screen. This method is for Windows and macOS only. + @JsonKey(name: 'publishFourthScreenTrack') + final bool? publishFourthScreenTrack; + + /// Whether to publish the audio captured from a custom source: true : Publish the audio captured from the custom source. false : Do not publish the captured audio from a custom source. @JsonKey(name: 'publishCustomAudioTrack') final bool? publishCustomAudioTrack; - /// The ID of the custom audio source to publish. The default value is 0.If you have set sourceNumber in setExternalAudioSource to a value greater than 1, the SDK creates the corresponding number of custom audio tracks and assigns an ID to each audio track, starting from 0. + /// The ID of the custom audio source to publish. The default value is 0. If you have set sourceNumber in setExternalAudioSource to a value greater than 1, the SDK creates the corresponding number of custom audio tracks and assigns an ID to each audio track, starting from 0. @JsonKey(name: 'publishCustomAudioTrackId') final int? publishCustomAudioTrackId; - /// Whether to publish the video captured from a custom source:true: Publish the video captured from the custom source.false: Do not publish the captured video from a custom source. + /// Whether to publish the video captured from a custom source: true : Publish the video captured from the custom source. false : Do not publish the captured video from a custom source. @JsonKey(name: 'publishCustomVideoTrack') final bool? publishCustomVideoTrack; - /// Whether to publish the encoded video:true: Publish the encoded video.false: Do not publish the encoded video. + /// Whether to publish the encoded video: true : Publish the encoded video. false : Do not publish the encoded video. @JsonKey(name: 'publishEncodedVideoTrack') final bool? publishEncodedVideoTrack; - /// Whether to publish the audio from the media player:true: Publish the audio from the media player.false: Do not publish the audio from the media player. + /// Whether to publish the audio from the media player: true : Publish the audio from the media player. false : Do not publish the audio from the media player. @JsonKey(name: 'publishMediaPlayerAudioTrack') final bool? publishMediaPlayerAudioTrack; - /// Whether to publish the video from the media player:true: Publish the video from the media player.false: Do not publish the video from the media player. + /// Whether to publish the video from the media player: true : Publish the video from the media player. false : Do not publish the video from the media player. @JsonKey(name: 'publishMediaPlayerVideoTrack') final bool? publishMediaPlayerVideoTrack; - /// Whether to publish the local transcoded video:true: Publish the local transcoded video.false: Do not publish the local transcoded video. + /// Whether to publish the local transcoded video: true : Publish the local transcoded video. false : Do not publish the local transcoded video. @JsonKey(name: 'publishTranscodedVideoTrack') final bool? publishTranscodedVideoTrack; - /// Whether to automatically subscribe to all remote audio streams when the user joins a channel:true: Subscribe to all remote audio streams.false: Do not automatically subscribe to any remote audio streams. + /// Whether to automatically subscribe to all remote audio streams when the user joins a channel: true : Subscribe to all remote audio streams. false : Do not automatically subscribe to any remote audio streams. @JsonKey(name: 'autoSubscribeAudio') final bool? autoSubscribeAudio; - /// Whether to automatically subscribe to all remote video streams when the user joins the channel:true: Subscribe to all remote video streams.false: Do not automatically subscribe to any remote video streams. + /// Whether to automatically subscribe to all remote video streams when the user joins the channel: true : Subscribe to all remote video streams. false : Do not automatically subscribe to any remote video streams. @JsonKey(name: 'autoSubscribeVideo') final bool? autoSubscribeVideo; - /// Whether to enable audio capturing or playback:true: Do not enable audio capturing or playback.false: Do not enable audio capturing or playback.If you need to publish the audio streams captured by your microphone, ensure this parameter is set as true. + /// Whether to enable audio capturing or playback: true : Enable audio capturing or playback. false : Do not enable audio capturing or playback. If you need to publish the audio streams captured by your microphone, ensure this parameter is set as true. @JsonKey(name: 'enableAudioRecordingOrPlayout') final bool? enableAudioRecordingOrPlayout; @@ -1406,7 +1428,9 @@ class ChannelMediaOptions { @JsonKey(name: 'mediaPlayerAudioDelayMs') final int? mediaPlayerAudioDelayMs; - /// (Optional) The token generated on your server for authentication. See This parameter takes effect only when calling updateChannelMediaOptions or updateChannelMediaOptionsEx.Ensure that the App ID, channel name, and user name used for creating the token are the same as those used by the initialize method for initializing the RTC engine, and those used by the joinChannel and joinChannelEx methods for joining the channel. + /// (Optional) The token generated on your server for authentication. + /// This parameter takes effect only when calling updateChannelMediaOptions or updateChannelMediaOptionsEx. + /// Ensure that the App ID, channel name, and user name used for creating the token are the same as those used by the initialize method for initializing the RTC engine, and those used by the joinChannel and joinChannelEx methods for joining the channel. @JsonKey(name: 'token') final String? token; @@ -1414,11 +1438,13 @@ class ChannelMediaOptions { @JsonKey(name: 'enableBuiltInMediaEncryption') final bool? enableBuiltInMediaEncryption; - /// Whether to publish the sound of a metronome to remote users:true: Publish processed audio frames. Both the local user and remote users can hear the metronome.false: Do not publish the sound of the metronome. Only the local user can hear the metronome. + /// Whether to publish the sound of a metronome to remote users: true : Publish processed audio frames. Both the local user and remote users can hear the metronome. false : Do not publish the sound of the metronome. Only the local user can hear the metronome. @JsonKey(name: 'publishRhythmPlayerTrack') 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 takes effect only when the user role is clientRoleAudience. + /// 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 takes effect only when the user role is clientRoleAudience. @JsonKey(name: 'isInteractiveAudience') final bool? isInteractiveAudience; @@ -1426,7 +1452,7 @@ class ChannelMediaOptions { @JsonKey(name: 'customVideoTrackId') final int? customVideoTrackId; - /// Whether the audio stream being published is filtered according to the volume algorithm:true: The audio stream is filtered. If the audio stream filter is not enabled, this setting does not takes effect.false: The audio stream is not filtered.If you need to enable this function, contact . + /// Whether the audio stream being published is filtered according to the volume algorithm: true : The audio stream is filtered. If the audio stream filter is not enabled, this setting does not takes effect. false : The audio stream is not filtered. If you need to enable this function, contact. @JsonKey(name: 'isAudioFilterable') final bool? isAudioFilterable; @@ -1438,31 +1464,6 @@ class ChannelMediaOptions { Map toJson() => _$ChannelMediaOptionsToJson(this); } -/// @nodoc -@JsonEnum(alwaysCreate: true) -enum LocalProxyMode { - /// @nodoc - @JsonValue(0) - connectivityFirst, - - /// @nodoc - @JsonValue(1) - localOnly, -} - -/// @nodoc -extension LocalProxyModeExt on LocalProxyMode { - /// @nodoc - static LocalProxyMode fromValue(int value) { - return $enumDecode(_$LocalProxyModeEnumMap, value); - } - - /// @nodoc - int value() { - return _$LocalProxyModeEnumMap[this]!; - } -} - /// The cloud proxy type. @JsonEnum(alwaysCreate: true) enum ProxyType { @@ -1508,104 +1509,6 @@ extension ProxyTypeExt on ProxyType { } } -/// @nodoc -@JsonSerializable(explicitToJson: true, includeIfNull: false) -class LogUploadServerInfo { - /// @nodoc - const LogUploadServerInfo( - {this.serverDomain, this.serverPath, this.serverPort, this.serverHttps}); - - /// @nodoc - @JsonKey(name: 'serverDomain') - final String? serverDomain; - - /// @nodoc - @JsonKey(name: 'serverPath') - final String? serverPath; - - /// @nodoc - @JsonKey(name: 'serverPort') - final int? serverPort; - - /// @nodoc - @JsonKey(name: 'serverHttps') - final bool? serverHttps; - - /// @nodoc - factory LogUploadServerInfo.fromJson(Map json) => - _$LogUploadServerInfoFromJson(json); - - /// @nodoc - Map toJson() => _$LogUploadServerInfoToJson(this); -} - -/// @nodoc -@JsonSerializable(explicitToJson: true, includeIfNull: false) -class AdvancedConfigInfo { - /// @nodoc - const AdvancedConfigInfo({this.logUploadServer}); - - /// @nodoc - @JsonKey(name: 'logUploadServer') - final LogUploadServerInfo? logUploadServer; - - /// @nodoc - factory AdvancedConfigInfo.fromJson(Map json) => - _$AdvancedConfigInfoFromJson(json); - - /// @nodoc - Map toJson() => _$AdvancedConfigInfoToJson(this); -} - -/// @nodoc -@JsonSerializable(explicitToJson: true, includeIfNull: false) -class LocalAccessPointConfiguration { - /// @nodoc - const LocalAccessPointConfiguration( - {this.ipList, - this.ipListSize, - this.domainList, - this.domainListSize, - this.verifyDomainName, - this.mode, - this.advancedConfig}); - - /// @nodoc - @JsonKey(name: 'ipList') - final List? ipList; - - /// @nodoc - @JsonKey(name: 'ipListSize') - final int? ipListSize; - - /// @nodoc - @JsonKey(name: 'domainList') - final List? domainList; - - /// @nodoc - @JsonKey(name: 'domainListSize') - final int? domainListSize; - - /// @nodoc - @JsonKey(name: 'verifyDomainName') - final String? verifyDomainName; - - /// @nodoc - @JsonKey(name: 'mode') - final LocalProxyMode? mode; - - /// @nodoc - @JsonKey(name: 'advancedConfig') - final AdvancedConfigInfo? advancedConfig; - - /// @nodoc - factory LocalAccessPointConfiguration.fromJson(Map json) => - _$LocalAccessPointConfigurationFromJson(json); - - /// @nodoc - Map toJson() => _$LocalAccessPointConfigurationToJson(this); -} - /// The options for leaving a channel. @JsonSerializable(explicitToJson: true, includeIfNull: false) class LeaveChannelOptions { @@ -1613,15 +1516,15 @@ class LeaveChannelOptions { const LeaveChannelOptions( {this.stopAudioMixing, this.stopAllEffect, this.stopMicrophoneRecording}); - /// Whether to stop playing and mixing the music file when a user leaves the channel. true: (Default) Stop playing and mixing the music file.false: Do not stop playing and mixing the music file. + /// Whether to stop playing and mixing the music file when a user leaves the channel. true : (Default) Stop playing and mixing the music file. false : Do not stop playing and mixing the music file. @JsonKey(name: 'stopAudioMixing') final bool? stopAudioMixing; - /// Whether to stop playing all audio effects when a user leaves the channel. true: (Default) Stop playing all audio effects.false: Do not stop playing any audio effect. + /// Whether to stop playing all audio effects when a user leaves the channel. true : (Default) Stop playing all audio effects. false : Do not stop playing any audio effect. @JsonKey(name: 'stopAllEffect') final bool? stopAllEffect; - /// Whether to stop microphone recording when a user leaves the channel. true: (Default) Stop microphone recording.false: Do not stop microphone recording. + /// Whether to stop microphone recording when a user leaves the channel. true : (Default) Stop microphone recording. false : Do not stop microphone recording. @JsonKey(name: 'stopMicrophoneRecording') final bool? stopMicrophoneRecording; @@ -1633,7 +1536,7 @@ class LeaveChannelOptions { Map toJson() => _$LeaveChannelOptionsToJson(this); } -/// RtcEngineEventHandlerThe SDK uses the interface to send event notifications to your app. Your app can get those notifications through methods that inherit this interface. +/// The SDK uses the RtcEngineEventHandler interface to send event notifications to your app. Your app can get those notifications through methods that inherit this interface. class RtcEngineEventHandler { /// @nodoc const RtcEngineEventHandler({ @@ -1782,25 +1685,28 @@ class RtcEngineEventHandler { /// Reports the last mile network probe result. /// - /// The SDK triggers this callback within 30 seconds after the app calls startLastmileProbeTest . + /// The SDK triggers this callback within 30 seconds after the app calls startLastmileProbeTest. /// /// * [result] The uplink and downlink last-mile network probe test result. See LastmileProbeResult. final void Function(LastmileProbeResult result)? onLastmileProbeResult; /// Reports the volume information of users. /// - /// By default, this callback is disabled. You can enable it by calling enableAudioVolumeIndication . Once this callback is enabled and users send streams in the channel, the SDK triggers the onAudioVolumeIndication callback according to the time interval set in enableAudioVolumeIndication . The SDK triggers two independent onAudioVolumeIndication callbacks simultaneously, which separately report the volume information of the local user who sends a stream and the remote users (up to three) whose instantaneous volume is the highest. Once this callback is enabled, if the local user calls the muteLocalAudioStream method to mute, the SDK continues to report the volume indication of the local user. If a remote user whose volume is one of the three highest in the channel stops publishing the audio stream for 20 seconds, the callback excludes this user's information; if all remote users stop publishing audio streams for 20 seconds, the SDK stops triggering the callback for remote users. + /// By default, this callback is disabled. You can enable it by calling enableAudioVolumeIndication. Once this callback is enabled and users send streams in the channel, the SDK triggers the onAudioVolumeIndication callback according to the time interval set in enableAudioVolumeIndication. The SDK triggers two independent onAudioVolumeIndication callbacks simultaneously, which separately report the volume information of the local user who sends a stream and the remote users (up to three) whose instantaneous volume is the highest. Once this callback is enabled, if the local user calls the muteLocalAudioStream method to mute, the SDK continues to report the volume indication of the local user. If a remote user whose volume is one of the three highest in the channel stops publishing the audio stream for 20 seconds, the callback excludes this user's information; if all remote users stop publishing audio streams for 20 seconds, the SDK stops triggering the callback for remote users. /// /// * [connection] The connection information. See RtcConnection. /// * [speakers] The volume information of the users. See AudioVolumeInfo. An empty speakers array in the callback indicates that no remote user is in the channel or is sending a stream. - /// * [speakerNumber] The total number of users.In the callback for the local user, if the local user is sending streams, the value of speakerNumber is 1.In the callback for remote users, the value range of speakerNumber is [0,3]. If the number of remote users who send streams is greater than or equal to three, the value of speakerNumber is 3. - /// * [totalVolume] The volume of the speaker. The value range is [0,255].In the callback for the local user, totalVolume is the volume of the local user who sends a stream.In the callback for remote users, totalVolume is the sum of the volume of all remote users (up to three) whose instantaneous volume is the highest. + /// * [speakerNumber] The total number of users. + /// In the callback for the local user, if the local user is sending streams, the value of speakerNumber is 1. + /// In the callback for remote users, the value range of speakerNumber is [0,3]. If the number of remote users who send streams is greater than or equal to three, the value of speakerNumber is 3. + /// * [totalVolume] The volume of the speaker. The value range is [0,255]. + /// In the callback for the local user, totalVolume is the volume of the local user who sends a stream. In the callback for remote users, totalVolume is the sum of the volume of all remote users (up to three) whose instantaneous volume is the highest. final void Function(RtcConnection connection, List speakers, int speakerNumber, int totalVolume)? onAudioVolumeIndication; /// Occurs when a user leaves a channel. /// - /// This callback notifies the app that the user leaves the channel by calling leaveChannel . From this callback, the app can get information such as the call duration and quality statistics. + /// This callback notifies the app that the user leaves the channel by calling leaveChannel. From this callback, the app can get information such as the call duration and quality statistics. /// /// * [connection] The connection information. See RtcConnection. /// * [stats] The statistics of the call. See RtcStats. @@ -1831,7 +1737,8 @@ class RtcEngineEventHandler { /// * [position] The playback progress (ms). /// /// 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. + /// 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. final void Function(int position)? onAudioMixingPositionChanged; /// Occurs when the playback of the local music file finishes. @@ -1858,7 +1765,7 @@ class RtcEngineEventHandler { /// Reports the last mile network quality of each user in the channel. /// - /// This callback reports the last mile network conditions of each user in the channel. Last mile refers to the connection between the local device and Agora's edge server. The SDK triggers this callback once every two seconds. If a channel includes multiple users, the SDK triggers this callback as many times. txQuality is rxQuality is + /// This callback reports the last mile network conditions of each user in the channel. Last mile refers to the connection between the local device and Agora's edge server. The SDK triggers this callback once every two seconds. If a channel includes multiple users, the SDK triggers this callback as many times. txQuality is when the user is not sending a stream; rxQuality is when the user is not receiving a stream. /// /// * [connection] The connection information. See RtcConnection. /// * [remoteUid] The user ID. The network quality of the user with this user ID is reported. If the uid is 0, the local network quality is reported. @@ -1884,7 +1791,7 @@ class RtcEngineEventHandler { /// /// This callback reports the last-mile network conditions of the local user before the user joins the channel. Last mile refers to the connection between the local device and Agora's edge server. Before the user joins the channel, this callback is triggered by the SDK once startLastmileProbeTest is called and reports the last-mile network conditions of the local user. /// - /// * [quality] The last-mile network quality. qualityUnknown(0): The quality is unknown.qualityExcellent(1): The quality is excellent.qualityGood(2): The network quality seems excellent, but the bitrate can be slightly lower than excellent.qualityPoor(3): Users can feel the communication is slightly impaired.qualityBad(4): Users cannot communicate smoothly.qualityVbad(5): The quality is so bad that users can barely communicate.qualityDown(6): The network is down, and users cannot communicate at all.See QualityType. + /// * [quality] The last-mile network quality. qualityUnknown (0): The quality is unknown. qualityExcellent (1): The quality is excellent. qualityGood (2): The network quality seems excellent, but the bitrate can be slightly lower than excellent. qualityPoor (3): Users can feel the communication is slightly impaired. qualityBad (4): Users cannot communicate smoothly. qualityVbad (5): The quality is so bad that users can barely communicate. qualityDown (6): The network is down, and users cannot communicate at all. See QualityType. final void Function(QualityType quality)? onLastmileQuality; /// Occurs when the first local video frame is displayed on the local video view. @@ -1901,16 +1808,25 @@ class RtcEngineEventHandler { /// Occurs when the first video frame is published. /// - /// The SDK triggers this callback under one of the following circumstances: The local client enables the video module and calls joinChannel successfully. The local client calls muteLocalVideoStream ( true ) and muteLocalVideoStream ( false ) in sequence. The local client calls disableVideo and enableVideo in sequence. + /// The SDK triggers this callback under one of the following circumstances: + /// The local client enables the video module and calls joinChannel successfully. + /// The local client calls muteLocalVideoStream (true) and muteLocalVideoStream (false) in sequence. + /// The local client calls disableVideo and enableVideo in sequence. /// /// * [connection] The connection information. See RtcConnection. /// * [elapsed] Time elapsed (ms) from the local user calling joinChannel until the SDK triggers this callback. - final void Function(RtcConnection connection, int elapsed)? + final void Function(VideoSourceType source, int elapsed)? onFirstLocalVideoFramePublished; /// Occurs when the first remote video frame is received and decoded. /// - /// The SDK triggers this callback under one of the following circumstances: The remote user joins the channel and sends the video stream. The remote user stops sending the video stream and re-sends it after 15 seconds. Reasons for such an interruption include: The remote user leaves the channel. The remote user drops offline. The remote user calls muteLocalVideoStream to stop sending the video stream. The remote user calls disableVideo to disable video. + /// The SDK triggers this callback under one of the following circumstances: + /// The remote user joins the channel and sends the video stream. + /// The remote user stops sending the video stream and re-sends it after 15 seconds. Reasons for such an interruption include: + /// The remote user leaves the channel. + /// The remote user drops offline. + /// The remote user calls muteLocalVideoStream to stop sending the video stream. + /// The remote user calls disableVideo to disable video. /// /// * [connection] The connection information. See RtcConnection. /// * [remoteUid] The user ID of the remote user sending the video stream. @@ -1933,7 +1849,11 @@ class RtcEngineEventHandler { /// Occurs when the local video stream state changes. /// - /// When the state of the local video stream changes (including the state of the video capture and encoding), the SDK triggers this callback to report the current state. This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur. The SDK triggers the onLocalVideoStateChanged callback with the state code of localVideoStreamStateFailed and error code of localVideoStreamErrorCaptureFailure in the following situations: The app switches to the background, and the system gets the camera resource. If your app runs in the background on a device running Android 9 or later, you cannot access the camera. If your app runs in the background on a device running Android 6 or later, the camera is occupied by a third-party app. Once the camera is released, the SDK triggers the onLocalVideoStateChanged ( localVideoStreamStateCapturing , localVideoStreamErrorOk ) callback. The camera starts normally, but does not output video frames for four consecutive seconds. When the camera outputs the captured video frames, if the video frames are the same for 15 consecutive frames, the SDK triggers the onLocalVideoStateChanged callback with the state code of localVideoStreamStateCapturing and error code of localVideoStreamErrorCaptureFailure . Note that the video frame duplication detection is only available for video frames with a resolution greater than 200 × 200, a frame rate greater than or equal to 10 fps, and a bitrate less than 20 Kbps. For some device models, the SDK does not trigger this callback when the state of the local video changes while the local video capturing device is in use, so you have to make your own timeout judgment. + /// When the state of the local video stream changes (including the state of the video capture and encoding), the SDK triggers this callback to report the current state. This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur. The SDK triggers the onLocalVideoStateChanged callback with the state code of localVideoStreamStateFailed and error code of localVideoStreamErrorCaptureFailure in the following situations: + /// The app switches to the background, and the system gets the camera resource. + /// If your app runs in the background on a device running Android 9 or later, you cannot access the camera. + /// If your app runs in the background on a device running Android 6 or later, the camera is occupied by a third-party app. Once the camera is released, the SDK triggers the onLocalVideoStateChanged (localVideoStreamStateCapturing, localVideoStreamErrorOk) callback. + /// The camera starts normally, but does not output video frames for four consecutive seconds. When the camera outputs the captured video frames, if the video frames are the same for 15 consecutive frames, the SDK triggers the onLocalVideoStateChanged callback with the state code of localVideoStreamStateCapturing and error code of localVideoStreamErrorCaptureFailure. Note that the video frame duplication detection is only available for video frames with a resolution greater than 200 × 200, a frame rate greater than or equal to 10 fps, and a bitrate less than 20 Kbps. For some device models, the SDK does not trigger this callback when the state of the local video changes while the local video capturing device is in use, so you have to make your own timeout judgment. /// /// * [source] The type of the video source. See VideoSourceType. /// * [state] The state of the local video, see LocalVideoStreamState. @@ -1967,9 +1887,13 @@ class RtcEngineEventHandler { final void Function(RtcConnection connection, int remoteUid, int width, int height, int elapsed)? onFirstRemoteVideoFrame; - /// Occurs when a remote user (in the communication profile)/ host (in the live streaming profile) leaves the channel. + /// Occurs when a remote user (in the communication profile)/ host (in the live streaming profile) joins the channel. /// - /// In a communication channel, this callback indicates that a remote user joins the channel. The SDK also triggers this callback to report the existing users in the channel when a user joins the channel. In a live-broadcast channel, this callback indicates that a host joins the channel. The SDK also triggers this callback to report the existing hosts in the channel when a host joins the channel. Agora recommends limiting the number of hosts to 17. The SDK triggers this callback under one of the following circumstances: A remote user/host joins the channel. A remote user switches the user role to the host after joining the channel. A remote user/host rejoins the channel after a network interruption. + /// In a communication channel, this callback indicates that a remote user joins the channel. The SDK also triggers this callback to report the existing users in the channel when a user joins the channel. + /// In a live-broadcast channel, this callback indicates that a host joins the channel. The SDK also triggers this callback to report the existing hosts in the channel when a host joins the channel. Agora recommends limiting the number of hosts to 17. The SDK triggers this callback under one of the following circumstances: + /// A remote user/host joins the channel. + /// A remote user switches the user role to the host after joining the channel. + /// A remote user/host rejoins the channel after a network interruption. /// /// * [connection] The connection information. See RtcConnection. /// * [remoteUid] The ID of the user or host who joins the channel. @@ -1979,7 +1903,9 @@ class RtcEngineEventHandler { /// Occurs when a remote user (in the communication profile)/ host (in the live streaming profile) leaves the channel. /// - /// There are two reasons for users to become offline: Leave the channel: When a user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel. Drop offline: When no data packet of the user or host is received for a certain period of time (20 seconds for the communication profile, and more for the live broadcast profile), the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections. It's recommended to use the Agora RTM SDK for reliable offline detection. + /// There are two reasons for users to become offline: + /// Leave the channel: When a user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel. + /// Drop offline: When no data packet of the user or host is received for a certain period of time (20 seconds for the communication profile, and more for the live broadcast profile), the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections. It's recommended to use the Agora RTM SDK for reliable offline detection. /// /// * [connection] The connection information. See RtcConnection. /// * [remoteUid] The ID of the user who leaves the channel or goes offline. @@ -1993,7 +1919,7 @@ class RtcEngineEventHandler { /// /// * [connection] The connection information. See RtcConnection. /// * [remoteUid] The user ID. - /// * [muted] Whether the remote user's audio stream is muted:true: User's audio stream is muted.false: User's audio stream is unmuted. + /// * [muted] Whether the remote user's audio stream is muted: true : User's audio stream is muted. false : User's audio stream is unmuted. final void Function(RtcConnection connection, int remoteUid, bool muted)? onUserMuteAudio; @@ -2003,7 +1929,7 @@ class RtcEngineEventHandler { /// /// * [connection] The connection information. See RtcConnection. /// * [remoteUid] The user ID of the remote user. - /// * [muted] Whether the remote user stops publishing the video stream:true: The remote user stops publishing the video stream.false: The remote user resumes publishing the video stream. + /// * [muted] Whether the remote user stops publishing the video stream: true : The remote user stops publishing the video stream. false : The remote user resumes publishing the video stream. final void Function(RtcConnection connection, int remoteUid, bool muted)? onUserMuteVideo; @@ -2013,7 +1939,7 @@ class RtcEngineEventHandler { /// /// * [connection] The connection information. See RtcConnection. /// * [remoteUid] The user ID of the remote user. - /// * [enabled] true: The video module is enabled.false: The video module is disabled. + /// * [enabled] true : The video module is enabled. false : The video module is disabled. final void Function(RtcConnection connection, int remoteUid, bool enabled)? onUserEnableVideo; @@ -2027,7 +1953,7 @@ class RtcEngineEventHandler { /// /// * [connection] The connection information. See RtcConnection. /// * [remoteUid] The user ID of the remote user. - /// * [enabled] Whether the specified remote user enables/disables the local video capturing function:true: The video module is enabled. Other users in the channel can see the video of this remote user.false: The video module is disabled. Other users in the channel can no longer receive the video stream from this remote user, while this remote user can still receive the video streams from other users. + /// * [enabled] Whether the specified remote user enables/disables the local video capturing function: true : The video module is enabled. Other users in the channel can see the video of this remote user. false : The video module is disabled. Other users in the channel can no longer receive the video stream from this remote user, while this remote user can still receive the video streams from other users. final void Function(RtcConnection connection, int remoteUid, bool enabled)? onUserEnableLocalVideo; @@ -2055,7 +1981,7 @@ class RtcEngineEventHandler { /// /// * [connection] The connection information. See RtcConnection. /// * [stats] The statistics of the local video stream. See LocalVideoStats. - final void Function(RtcConnection connection, LocalVideoStats stats)? + final void Function(VideoSourceType source, LocalVideoStats stats)? onLocalVideoStats; /// Reports the statistics of the video stream sent by each remote users. @@ -2074,7 +2000,7 @@ class RtcEngineEventHandler { /// Occurs when the camera focus area changes. /// - /// The SDK triggers this callback when the local user changes the camera focus position by calling setCameraFocusPositionInPreview . This callback is for Android and iOS only. + /// The SDK triggers this callback when the local user changes the camera focus position by calling setCameraFocusPositionInPreview. This callback is for Android and iOS only. /// /// * [x] The x-coordinate of the changed camera focus area. /// * [y] The y-coordinate of the changed camera focus area. @@ -2085,13 +2011,20 @@ class RtcEngineEventHandler { /// Occurs when the camera exposure area changes. /// - /// The SDK triggers this callback when the local user changes the camera exposure position by calling setCameraExposurePosition . This callback is for Android and iOS only. + /// The SDK triggers this callback when the local user changes the camera exposure position by calling setCameraExposurePosition. This callback is for Android and iOS only. final void Function(int x, int y, int width, int height)? onCameraExposureAreaChanged; /// Reports the face detection result of the local user. /// - /// Once you enable face detection by calling enableFaceDetection ( true ) , you can get the following information on the local user in real-time: The width and height of the local video. The position of the human face in the local view. The distance between the human face and the screen. This value is based on the fitting calculation of the local video size and the position of the human face. This callback is for Android and iOS only. When it is detected that the face in front of the camera disappears, the callback will be triggered immediately. When no human face is detected, the frequency of this callback to be rtriggered wil be decreased to reduce power consumption on the local device. The SDK stops triggering this callback when a human face is in close proximity to the screen. On Android, the value of distance reported in this callback may be slightly different from the actual distance . Therefore, Agora does not recommend using it for accurate calculation. + /// Once you enable face detection by calling enableFaceDetection (true), you can get the following information on the local user in real-time: + /// The width and height of the local video. + /// The position of the human face in the local view. + /// The distance between the human face and the screen. This value is based on the fitting calculation of the local video size and the position of the human face. + /// This callback is for Android and iOS only. + /// When it is detected that the face in front of the camera disappears, the callback will be triggered immediately. When no human face is detected, the frequency of this callback to be triggered wil be decreased to reduce power consumption on the local device. + /// The SDK stops triggering this callback when a human face is in close proximity to the screen. + /// On Android, the value of distance reported in this callback may be slightly different from the actual distance. Therefore, Agora does not recommend using it for accurate calculation. /// /// * [imageWidth] The width (px) of the video image captured by the local camera. /// * [imageHeight] The height (px) of the video image captured by the local camera. @@ -2138,7 +2071,9 @@ class RtcEngineEventHandler { /// Occurs when the connection between the SDK and the server is interrupted. /// - /// Deprecated: Use onConnectionStateChanged instead. The SDK triggers this callback when it loses connection with the server for more than four seconds after the connection is established. After triggering this callback, the SDK tries to reconnect to the server. You can use this callback to implement pop-up reminders. The differences between this callback and onConnectionLost are as follow: The SDK triggers the onConnectionInterrupted callback when it loses connection with the server for more than four seconds after it successfully joins the channel. The SDK triggers the onConnectionLost callback when it loses connection with the server for more than 10 seconds, whether or not it joins the channel. If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora's edge server, the SDK stops rejoining the channel. + /// Deprecated: Use onConnectionStateChanged instead. The SDK triggers this callback when it loses connection with the server for more than four seconds after the connection is established. After triggering this callback, the SDK tries to reconnect to the server. You can use this callback to implement pop-up reminders. The differences between this callback and onConnectionLost are as follow: + /// The SDK triggers the onConnectionInterrupted callback when it loses connection with the server for more than four seconds after it successfully joins the channel. + /// The SDK triggers the onConnectionLost callback when it loses connection with the server for more than 10 seconds, whether or not it joins the channel. If the SDK fails to rejoin the channel 20 minutes after being disconnected from Agora's edge server, the SDK stops rejoining the channel. /// /// * [connection] The connection information. See RtcConnection. final void Function(RtcConnection connection)? onConnectionInterrupted; @@ -2178,14 +2113,16 @@ class RtcEngineEventHandler { /// Occurs when the token expires. /// - /// 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. + /// 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. /// /// * [connection] The connection information. See RtcConnection. final void Function(RtcConnection connection)? onRequestToken; /// Occurs when the token expires in 30 seconds. /// - /// When the token is about to expire in 30 seconds, the SDK triggers this callback to remind the app to renew the token. Upon receiving this callback, you need to generate a new token on your server, and call renewToken to pass the new token to the SDK. + /// When the token is about to expire in 30 seconds, the SDK triggers this callback to remind the app to renew the token. Upon receiving this callback, you need to generate a new token on your server, and call renewToken to pass the new token to the SDK. In scenarios involving multiple channels, you need to call updateChannelMediaOptionsEx to pass the new token to the SDK. /// /// * [connection] The connection information. See RtcConnection. /// * [token] The token that expires in 30 seconds. @@ -2198,7 +2135,10 @@ class RtcEngineEventHandler { /// Occurs when the first audio frame is published. /// - /// The SDK triggers this callback under one of the following circumstances: The local client enables the audio module and calls joinChannel successfully. The local client calls muteLocalAudioStream ( true ) and muteLocalAudioStream ( false ) in sequence. The local client calls disableAudio and enableAudio in sequence. + /// The SDK triggers this callback under one of the following circumstances: + /// The local client enables the audio module and calls joinChannel successfully. + /// The local client calls muteLocalAudioStream (true) and muteLocalAudioStream (false) in sequence. + /// The local client calls disableAudio and enableAudio in sequence. /// /// * [connection] The connection information. See RtcConnection. /// * [elapsed] Time elapsed (ms) from the local user calling joinChannel until the SDK triggers this callback. @@ -2217,7 +2157,13 @@ class RtcEngineEventHandler { /// Occurs when the SDK decodes the first remote audio frame for playback. /// - /// Deprecated: Use onRemoteAudioStateChanged instead. The SDK triggers this callback under one of the following circumstances: The remote user joins the channel and sends the audio stream for the first time. The remote user's audio is offline and then goes online to re-send audio. It means the local user cannot receive audio in 15 seconds. Reasons for such an interruption include: The remote user leaves channel. The remote user drops offline. The remote user calls muteLocalAudioStream to stop sending the audio stream. The remote user calls disableAudio to disable audio. + /// Deprecated: Use onRemoteAudioStateChanged instead. The SDK triggers this callback under one of the following circumstances: + /// The remote user joins the channel and sends the audio stream for the first time. + /// The remote user's audio is offline and then goes online to re-send audio. It means the local user cannot receive audio in 15 seconds. Reasons for such an interruption include: + /// The remote user leaves channel. + /// The remote user drops offline. + /// The remote user calls muteLocalAudioStream to stop sending the audio stream. + /// The remote user calls disableAudio to disable audio. /// /// * [connection] The connection information. See RtcConnection. /// * [uid] The user ID of the remote user. @@ -2253,7 +2199,9 @@ class RtcEngineEventHandler { /// Occurs when the most active remote speaker is detected. /// - /// After a successful call of enableAudioVolumeIndication , the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user whose volume is detected as the loudest for the most times, is the most active user. When the number of users is no less than two and an active remote speaker exists, the SDK triggers this callback and reports the uid of the most active remote speaker. If the most active remote speaker is always the same user, the SDK triggers the onActiveSpeaker callback only once. If the most active remote speaker changes to another user, the SDK triggers this callback again and reports the uid of the new active remote speaker. + /// After a successful call of enableAudioVolumeIndication, the SDK continuously detects which remote user has the loudest volume. During the current period, the remote user whose volume is detected as the loudest for the most times, is the most active user. When the number of users is no less than two and an active remote speaker exists, the SDK triggers this callback and reports the uid of the most active remote speaker. + /// If the most active remote speaker is always the same user, the SDK triggers the onActiveSpeaker callback only once. + /// If the most active remote speaker changes to another user, the SDK triggers this callback again and reports the uid of the new active remote speaker. /// /// * [connection] The connection information. See RtcConnection. /// * [uid] The user ID of the most active speaker. @@ -2271,7 +2219,12 @@ class RtcEngineEventHandler { /// * [filePath] The local path of the snapshot. /// * [width] The width (px) of the snapshot. /// * [height] The height (px) of the snapshot. - /// * [errCode] The message that confirms success or gives the reason why the snapshot is not successfully taken:0: Success.< 0: Failure:-1: The SDK fails to write data to a file or encode a JPEG image.-2: The SDK does not find the video stream of the specified user within one second after the takeSnapshot method call succeeds. The possible reasons are: local capture stops, remote end stops publishing, or video data processing is blocked.-3: Calling the takeSnapshot method too frequently. + /// * [errCode] The message that confirms success or gives the reason why the snapshot is not successfully taken: + /// 0: Success. + /// < 0: Failure: + /// -1: The SDK fails to write data to a file or encode a JPEG image. + /// -2: The SDK does not find the video stream of the specified user within one second after the takeSnapshot method call succeeds. The possible reasons are: local capture stops, remote end stops publishing, or video data processing is blocked. + /// -3: Calling the takeSnapshot method too frequently. final void Function(RtcConnection connection, int uid, String filePath, int width, int height, int errCode)? onSnapshotTaken; @@ -2307,7 +2260,7 @@ class RtcEngineEventHandler { /// /// * [deviceType] The device type. See MediaDeviceType. /// * [volume] The volume value. The range is [0, 255]. - /// * [muted] Whether the audio device is muted:true: The audio device is muted.false: The audio device is not muted. + /// * [muted] Whether the audio device is muted: true : The audio device is muted. false : The audio device is not muted. final void Function(MediaDeviceType deviceType, int volume, bool muted)? onAudioDeviceVolumeChanged; @@ -2418,7 +2371,7 @@ class RtcEngineEventHandler { /// Reports the built-in encryption errors. /// - /// When encryption is enabled by calling enableEncryption , the SDK triggers this callback if an error occurs in encryption or decryption on the sender or the receiver side. + /// When encryption is enabled by calling enableEncryption, the SDK triggers this callback if an error occurs in encryption or decryption on the sender or the receiver side. /// /// * [connection] The connection information. See RtcConnection. /// * [errorType] Details about the error type. See EncryptionErrorType. @@ -2520,7 +2473,7 @@ class RtcEngineEventHandler { /// Occurs when the extension is enabled. /// - /// After a successful call of enableExtension ( true ) , the extension triggers this callback. + /// After a successful call of enableExtension (true), the extension triggers this callback. /// /// * [provider] The name of the extension provider. /// * [extName] The name of the extension. @@ -2528,7 +2481,7 @@ class RtcEngineEventHandler { /// Occurs when the extension is disabled. /// - /// After a successful call of enableExtension ( false ) , this callback is triggered. + /// After a successful call of enableExtension (false), this callback is triggered. /// /// * [extName] The name of the extension. /// * [provider] The name of the extension provider. @@ -2536,7 +2489,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. + /// When calling enableExtension (true) fails or the extension runs in error, the extension triggers this callback and reports the error code and reason. /// /// * [provider] The name of the extension provider. /// * [extension] The name of the extension. @@ -2553,7 +2506,7 @@ class RtcEngineEventHandler { /// Occurs when there's an error during the local video mixing. /// - /// When you fail to call startLocalVideoTranscoder or updateLocalTranscoderConfiguration , the SDK triggers this callback to report the reason. + /// When you fail to call startLocalVideoTranscoder or updateLocalTranscoderConfiguration, the SDK triggers this callback to report the reason. /// /// * [stream] The video streams that cannot be mixed during video mixing. See TranscodingVideoStream. /// * [error] The reason for local video mixing error. See VideoTranscoderError. @@ -2583,17 +2536,20 @@ abstract class VideoDeviceManager { /// This method is for Windows and macOS only. /// /// Returns - /// Success: A VideoDeviceInfo array including all video devices in the system. Failure: An empty array. + /// Success: A VideoDeviceInfo array including all video devices in the system. + /// Failure: An empty array. Future> enumerateVideoDevices(); /// Specifies the video capture device with the device ID. /// - /// Plugging or unplugging a device does not change its device ID. This method is for Windows and macOS only. + /// Plugging or unplugging a device does not change its device ID. + /// This method is for Windows and macOS only. /// - /// * [deviceIdUTF8] The device ID. You can get the device ID by calling enumerateVideoDevices.The maximum length is MaxDeviceIdLengthType. + /// * [deviceIdUTF8] The device ID. You can get the device ID by calling enumerateVideoDevices. The maximum length is MaxDeviceIdLengthType. /// /// 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. + /// 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 setDevice(String deviceIdUTF8); /// Retrieves the current video capture device. @@ -2611,7 +2567,8 @@ abstract class VideoDeviceManager { /// * [deviceIdUTF8] The ID of the video capture 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. + /// 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 numberOfCapabilities(String deviceIdUTF8); /// Gets the detailed video frame information of the video capture device in the specified video format. @@ -2622,7 +2579,7 @@ abstract class VideoDeviceManager { /// * [deviceCapabilityNumber] The index number of the video format. If the return value of numberOfCapabilities is i, the value range of this parameter is [0,i). /// /// Returns - /// The specific information of the specified video format, including width (px), height (px), and frame rate (fps). See VideoFormat . + /// The specific information of the specified video format, including width (px), height (px), and frame rate (fps). See VideoFormat. Future getCapability( {required String deviceIdUTF8, required int deviceCapabilityNumber}); @@ -2670,7 +2627,7 @@ class RtcEngineContext { @JsonKey(name: 'audioScenario') final AudioScenarioType? audioScenario; - /// The region for connection. This is an advanced feature and applies to scenarios that have regional restrictions. The area codes support bitwise operation. + /// The region for connection. This is an advanced feature and applies to scenarios that have regional restrictions. The area codes support bitwise operation. @JsonKey(name: 'areaCode') final int? areaCode; @@ -2683,7 +2640,8 @@ class RtcEngineContext { /// Rename agorasdk.3.log to agorasdk.4.log. /// Rename agorasdk.2.log to agorasdk.3.log. /// Rename agorasdk.1.log to agorasdk.2.log. - /// Create a new agorasdk.log file. The overwrite rules for the agoraapi.log file are the same as for agorasdk.log. Sets the log file size. See LogConfig.By default, the SDK generates five SDK log files and five API call log files with the following rules: + /// Create a new agorasdk.log file. + /// The overwrite rules for the agoraapi.log file are the same as for agorasdk.log. Sets the log file size. See LogConfig. By default, the SDK generates five SDK log files and five API call log files with the following rules: @JsonKey(name: 'logConfig') final LogConfig? logConfig; @@ -2695,11 +2653,11 @@ class RtcEngineContext { @JsonKey(name: 'useExternalEglContext') final bool? useExternalEglContext; - /// Whether to enable domain name restriction:true: Enables the domain name restriction. This value is suitable for scenarios where IoT devices use IoT cards for network access. The SDK will only connect to servers in the domain name or IP whitelist that has been reported to the operator.false: (Default) Disables the domain name restriction. This value is suitable for most common scenarios. + /// Whether to enable domain name restriction: true : Enables the domain name restriction. This value is suitable for scenarios where IoT devices use IoT cards for network access. The SDK will only connect to servers in the domain name or IP whitelist that has been reported to the operator. false : (Default) Disables the domain name restriction. This value is suitable for most common scenarios. @JsonKey(name: 'domainLimit') final bool? domainLimit; - /// Whether to automatically register the Agora extensions when initializing RtcEngine:true: (Default) Automatically register the Agora extensions when initializing RtcEngine.false: Do not register the Agora extensions when initializing RtcEngine. You need to call enableExtension to register the Agora extensions. + /// Whether to automatically register the Agora extensions when initializing RtcEngine : true : (Default) Automatically register the Agora extensions when initializing RtcEngine. false : Do not register the Agora extensions when initializing RtcEngine. You need to call enableExtension to register the Agora extensions. @JsonKey(name: 'autoRegisterAgoraExtensions') final bool? autoRegisterAgoraExtensions; @@ -2784,7 +2742,9 @@ class Metadata { /// @nodoc const Metadata({this.uid, this.size, this.buffer, this.timeStampMs}); - /// The user ID.For the recipient:the ID of the remote user who sent the Metadata.Ignore it for sender. + /// The user ID. + /// For the recipient:the ID of the remote user who sent the Metadata. + /// Ignore it for sender. @JsonKey(name: 'uid') final int? uid; @@ -2966,19 +2926,19 @@ class DirectCdnStreamingMediaOptions { this.publishMediaPlayerId, this.customVideoTrackId}); - /// Sets whether to publish the video captured by the camera:true: Publish the video captured by the camera.false: (Default) Do not publish the video captured by the camera. + /// Sets whether to publish the video captured by the camera: true : Publish the video captured by the camera. false : (Default) Do not publish the video captured by the camera. @JsonKey(name: 'publishCameraTrack') final bool? publishCameraTrack; - /// Sets whether to publish the audio captured by the microphone:true: Publish the audio captured by the microphone.false: (Default) Do not publish the audio captured by the microphone. + /// Sets whether to publish the audio captured by the microphone: true : Publish the audio captured by the microphone. false : (Default) Do not publish the audio captured by the microphone. @JsonKey(name: 'publishMicrophoneTrack') final bool? publishMicrophoneTrack; - /// Sets whether to publish the captured audio from a custom source:true: Publish the captured audio from a custom source.false: (Default) Do not publish the captured audio from the custom source. + /// Sets whether to publish the captured audio from a custom source: true : Publish the captured audio from a custom source. false : (Default) Do not publish the captured audio from the custom source. @JsonKey(name: 'publishCustomAudioTrack') final bool? publishCustomAudioTrack; - /// Sets whether to publish the captured video from a custom source:true: Publish the captured video from a custom source.false: (Default) Do not publish the captured video from the custom source. + /// Sets whether to publish the captured video from a custom source: true : Publish the captured video from a custom source. false : (Default) Do not publish the captured video from the custom source. @JsonKey(name: 'publishCustomVideoTrack') final bool? publishCustomVideoTrack; @@ -3039,19 +2999,29 @@ class ExtensionInfo { abstract class RtcEngine { /// Releases the RtcEngine instance. /// - /// This method releases all resources used by the Agora SDK. Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. After a successful method call, you can no longer use any method or callback in the SDK anymore. If you want to use the real-time communication functions again, you must call createAgoraRtcEngine and initialize to create a new RtcEngine instance. If you want to create a new RtcEngine instance after destroyingthe current one, ensure that you wait till the release method execution to complete. + /// This method releases all resources used by the Agora SDK. Use this method for apps in which users occasionally make voice or video calls. When users do not make calls, you can free up resources for other operations. After a successful method call, you can no longer use any method or callback in the SDK anymore. If you want to use the real-time communication functions again, you must call createAgoraRtcEngine and initialize to create a new RtcEngine instance. + /// This method can be called synchronously. You need to wait for the resource of RtcEngine to be released before performing other operations (for example, create a new RtcEngine object). Therefore, Agora recommends calling this method in the child thread to avoid blocking the main thread. + /// Besides, Agora does not recommend you calling release in any callback of the SDK. Otherwise, the SDK cannot release the resources until the callbacks return results, which may result in a deadlock. /// - /// * [sync] Whether the method is called synchronously:true: Synchronous call. Agora suggests calling this method in a sub-thread to avoid congestion in the main thread because the synchronous call and the app cannot move on to another task until the resources used by RtcEngine are released. Besides, you cannot call release in any method or callback of the SDK. Otherwise, the SDK cannot release the resources until the callbacks return results, which may result in a deadlock.false: Asynchronous call. Currently this method only supports synchronous calls, do not set this parameter to this value. + /// * [sync] Whether the method is called synchronously: true : Synchronous call. false : Asynchronous call. Currently this method only supports synchronous calls. Do not set this parameter to this value. Future release({bool sync = false}); /// Initializes RtcEngine. /// - /// All called methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread. Before calling other APIs, you must call createAgoraRtcEngine and initialize to create and initialize the RtcEngine object. The SDK supports creating only one RtcEngine instance for an app. + /// All called methods provided by the RtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread. + /// Before calling other APIs, you must call createAgoraRtcEngine and initialize to create and initialize the RtcEngine object. + /// The SDK supports creating only one RtcEngine instance for an app. /// /// * [context] Configurations for the RtcEngine instance. See RtcEngineContext. /// /// 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: A general error occurs (no specified reason). -2: The parameter is invalid. -7: The SDK is not initialized. -22: The resource request failed. The SDK fails to allocate resources because your app consumes too much system resource or the system resources are insufficient. -101: The App ID is invalid. + /// 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: A general error occurs (no specified reason). + /// -2: The parameter is invalid. + /// -7: The SDK is not initialized. + /// -22: The resource request failed. The SDK fails to allocate resources because your app consumes too much system resource or the system resources are insufficient. + /// -101: The App ID is invalid. Future initialize(RtcEngineContext context); /// Gets the SDK version. @@ -3073,20 +3043,117 @@ abstract class RtcEngine { /// * [size] The size of CodecCapInfo. /// /// Returns - /// One CodecCapInfo array indicating the video encoding capability of the device, if the method call succeeds. If the call timeouts, please modify the call logic and do not invoke the method in the main thread. + /// One CodecCapInfo array indicating the video encoding capability of the device, if the method call succeeds. + /// If the call timeouts, please modify the call logic and do not invoke the method in the main thread. Future> queryCodecCapability(int size); + /// Preloads a channel with token, channelId, and uid. + /// + /// When audience members need to switch between different channels frequently, calling the method can help shortening the time of joining a channel, thus reducing the time it takes for audience members to hear and see the host. As it may take a while for the SDK to preload a channel, Agora recommends that you call this method as soon as possible after obtaining the channel name and user ID to join a channel. + /// When calling this method, ensure you set the user role as audience and do not set the audio scenario as audioScenarioChorus, otherwise, this method does not take effect. + /// You also need to make sure that the channel name, user ID and token passed in for preloading are the same as the values passed in when joinning the channel, otherwise, this method does not take effect. + /// One RtcEngine instance supports preloading 20 channels at most. When exceeding this limit, the latest 20 preloaded channels take effect. + /// Failing to preload a channel does not mean that you can't join a channel, nor will it increase the time of joining a channel. If you join a preloaded channel, leave it and want to rejoin the same channel, you do not need to call this method unless the token for preloading the channel expires. + /// + /// * [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 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. + /// All uppercase English letters: A to Z. + /// All numeric characters: 0 to 9. + /// Space + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// * [uid] The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2 32 -1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so. + /// + /// 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. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + /// -102: The channel name is invalid. You need to pass in a valid channel name and join the channel again. + Future preloadChannel( + {required String token, required String channelId, required int uid}); + + /// Preloads a channel with token, channelId, and userAccount. + /// + /// When audience members need to switch between different channels frequently, calling the method can help shortening the time of joining a channel, thus reducing the time it takes for audience members to hear and see the host. As it may take a while for the SDK to preload a channel, Agora recommends that you call this method as soon as possible after obtaining the channel name and user ID to join a channel. If you join a preloaded channel, leave it and want to rejoin the same channel, you do not need to call this method unless the token for preloading the channel expires. + /// Failing to preload a channel does not mean that you can't join a channel, nor will it increase the time of joining a channel. + /// One RtcEngine instance supports preloading 20 channels at most. When exceeding this limit, the latest 20 preloaded channels take effect. + /// When calling this method, ensure you set the user role as audience and do not set the audio scenario as audioScenarioChorus, otherwise, this method does not take effect. + /// You also need to make sure that the User Account, channel ID and token passed in for preloading are the same as the values passed in when joining the channel, otherwise, this method does not take effect. + /// + /// * [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 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. + /// All uppercase English letters: A to Z. + /// All numeric characters: 0 to 9. + /// Space + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// * [userAccount] The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total): + /// The 26 lowercase English letters: a to z. + /// The 26 uppercase English letters: A to Z. + /// All numeric characters: 0 to 9. + /// Space + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// + /// 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. + /// -2: The parameter is invalid. For example, the User Account is empty. You need to pass in a valid parameter and join the channel again. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + /// -102: The channel name is invalid. You need to pass in a valid channel name and join the channel again. + Future preloadChannelWithUserAccount( + {required String token, + required String channelId, + required String userAccount}); + + /// Updates the wildcard token for preloading channels. + /// + /// You need to maintain the life cycle of the wildcard token by yourself. When the token expires, you need to generate a new wildcard token and then call this method to pass in the new token. + /// + /// * [token] The new token. + /// + /// 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. + /// -2: The parameter is invalid. For example, the token is invalid. You need to pass in a valid parameter and join the channel again. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + Future updatePreloadChannelToken(String token); + /// Joins a channel with media options. /// - /// This method enables users to join a channel. Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other. A successful call of this method triggers the following callbacks: The local client: The onJoinChannelSuccess and onConnectionStateChanged callbacks. The remote client: onUserJoined , if the user joining the channel is in the Communication profile or is a host in the Live-broadcasting profile. When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client. 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. + /// This method enables users to join a channel. Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other. A successful call of this method triggers the following callbacks: + /// The local client: The onJoinChannelSuccess and onConnectionStateChanged callbacks. + /// The remote client: onUserJoined, if the user joining the channel is in the Communication profile or is a host in the Live-broadcasting profile. When the connection between the client and Agora's server is interrupted due to poor network conditions, the SDK tries reconnecting to the server. When the local client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback on the local client. + /// 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. - /// * [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.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," - /// * [uid] The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 232-1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so. + /// * [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. + /// All numeric characters: 0 to 9. + /// Space + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// * [uid] The user ID. This parameter is used to identify the user in the channel for real-time audio and video interaction. You need to set and manage user IDs yourself, and ensure that each user ID in the same channel is unique. This parameter is a 32-bit unsigned integer. The value range is 1 to 2 32 -1. If the user ID is not assigned (or set to 0), the SDK assigns a random user ID and returns it in the onJoinChannelSuccess callback. Your application must record and maintain the returned user ID, because the SDK does not do so. /// * [options] The channel media options. See ChannelMediaOptions. /// /// 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. -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in ChannelMediaOptions is invalid. You need to pass in a valid parameter and join the channel again. -3: Failes to initialize the RtcEngine object. You need to reinitialize the RtcEngine object. -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. -8: The internal state of the RtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling startEchoTest to stop the test after calling stopEchoTest to start a call loop test. You need to call stopEchoTest before calling this method. -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the connectionStateDisconnected (1) state. -102: The channel name is invalid. You need to pass in a valid channelname in channelId to rejoin the channel. -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel. + /// 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. + /// -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in ChannelMediaOptions is invalid. You need to pass in a valid parameter and join the channel again. + /// -3: Failes to initialize the RtcEngine object. You need to reinitialize the RtcEngine object. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + /// -8: The internal state of the RtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling startEchoTest to stop the test after calling stopEchoTest to start a call loop test. You need to call stopEchoTest before calling this method. + /// -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the connectionStateDisconnected (1) state. + /// -102: The channel name is invalid. You need to pass in a valid channelname in channelId to rejoin the channel. + /// -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel. Future joinChannel( {required String token, required String channelId, @@ -3098,104 +3165,158 @@ abstract class RtcEngine { /// * [options] The channel media options. See ChannelMediaOptions. /// /// 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. -2: The value of a member in the ChannelMediaOptions structure is invalid. For example, the token or the user ID is invalid. You need to fill in a valid parameter. -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. -8: The internal state of the RtcEngine object is wrong. The possible reason is that the user is not in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. If you receive the connectionStateDisconnected (1) or connectionStateFailed (5) state, the user is not in the channel. You need to call joinChannel to join a channel before calling this method. + /// 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. + /// -2: The value of a member in the ChannelMediaOptions structure is invalid. For example, the token or the user ID is invalid. You need to fill in a valid parameter. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + /// -8: The internal state of the RtcEngine object is wrong. The possible reason is that the user is not in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. If you receive the connectionStateDisconnected (1) or connectionStateFailed (5) state, the user is not in the channel. You need to call joinChannel to join a channel before calling this method. Future updateChannelMediaOptions(ChannelMediaOptions options); /// Sets channel options and leaves the channel. /// - /// If you call release immediately after calling this method, the SDK does not trigger the onLeaveChannel callback. If you have called joinChannelEx to join multiple channels, calling this method will leave the channels when calling joinChannel and joinChannelEx at the same time. This method will release all resources related to the session, leave the channel, that is, hang up or exit the call. This method can be called whether or not a call is currently in progress. After joining the channel, you must call this method or to end the call, otherwise, the next call cannot be started. This method call is asynchronous. When this method returns, it does not necessarily mean that the user has left the channel. 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. + /// If you have called joinChannelEx to join multiple channels, calling this method will leave the channels when calling joinChannel and joinChannelEx at the same time. This method will release all resources related to the session, leave the channel, that is, hang up or exit the call. This method can be called whether or not a call is currently in progress. After joining the channel, you must call this method or to end the call, otherwise, the next call cannot be started. This method call is asynchronous. When this method returns, it does not necessarily mean that the user has left the channel. 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. /// /// * [options] The options for leaving the channel. See LeaveChannelOptions. /// /// 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. + /// 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 leaveChannel({LeaveChannelOptions? options}); /// Renews the token. /// - /// The SDK triggers the onTokenPrivilegeWillExpire callback. The onConnectionStateChanged callback reports connectionChangedTokenExpired (9). + /// The SDK triggers the onTokenPrivilegeWillExpire callback. + /// The onConnectionStateChanged callback reports connectionChangedTokenExpired (9). /// /// * [token] The new token. /// /// 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. -2: The parameter is invalid. For example, the token is invalid. You need to fill in a valid parameter. -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + /// 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. + /// -2: The parameter is invalid. For example, the token is invalid. You need to fill in a valid parameter. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. Future renewToken(String token); /// 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. 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. + /// 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. + /// 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. /// /// * [profile] The channel profile. See ChannelProfileType. /// /// 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. -2: The parameter is invalid. -7: The SDK is not initialized. + /// 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. + /// -2: The parameter is invalid. + /// -7: The SDK is not initialized. Future setChannelProfile(ChannelProfileType profile); /// Sets the user role and level in an interactive live streaming channel. /// - /// 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. + /// 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. /// /// * [role] The user role in the interactive live streaming. See ClientRoleType. /// * [options] The detailed options of a user, including the user level. See ClientRoleOptions. /// /// 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: A general error occurs (no specified reason). -2: The parameter is invalid. -5: The request is rejected. -7: The SDK is not initialized. + /// 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: A general error occurs (no specified reason). + /// -2: The parameter is invalid. + /// -5: The request is rejected. + /// -7: The SDK is not initialized. Future setClientRole( {required ClientRoleType role, ClientRoleOptions? options}); /// Starts an audio device loopback test. /// - /// To test whether the user's local sending and receiving streams are normal, you can call this method to perform an audio and video call loop test, which tests whether the audio and video devices and the user's upstream and downstream networks are working properly. After starting the test, the user needs to make a sound or face the camera. The audio or video is output after about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream networks are working properly; if the video playback is normal, the video device and the user's upstream and downstream networks are working properly. You can call this method either before or after joining a channel. After calling this method, call stopEchoTest to end the test; otherwise, the user cannot perform the next audio and video call loop test and cannot join the channel. In live streaming scenarios, this method only applies to hosts. + /// To test whether the user's local sending and receiving streams are normal, you can call this method to perform an audio and video call loop test, which tests whether the audio and video devices and the user's upstream and downstream networks are working properly. After starting the test, the user needs to make a sound or face the camera. The audio or video is output after about two seconds. If the audio playback is normal, the audio device and the user's upstream and downstream networks are working properly; if the video playback is normal, the video device and the user's upstream and downstream networks are working properly. + /// You can call this method either before or after joining a channel. When calling in a channel, make sure that no audio or video stream is being published. + /// After calling this method, call stopEchoTest to end the test; otherwise, the user cannot perform the next audio and video call loop test and cannot join the channel. + /// In live streaming scenarios, this method only applies to hosts. /// /// * [config] The configuration of the audio and video call loop test. See EchoTestConfiguration. /// /// Returns - /// 0: Success. < 0: Failure. + /// 0: Success. + /// < 0: Failure. Future startEchoTest(EchoTestConfiguration config); /// Stops the audio call test. /// /// 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. -5(ERR_REFUSED): Failed to stop the echo test. The echo test may not be running. + /// < 0: Failure. + /// -5(ERR_REFUSED): Failed to stop the echo test. The echo test may not be running. Future stopEchoTest(); /// Enables or disables multi-camera capture. /// - /// 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 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: iPhone XR iPhone XS iPhone XS Max iPad Pro 3rd generation and later - /// - /// * [enabled] Whether to enable multi-camera video capture mode:true: Enable multi-camera capture mode; the SDK uses multiple cameras to capture video.false: Disable multi-camera capture mode; the SDK uses a single camera to capture video. + /// 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 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: + /// iPhone XR + /// iPhone XS + /// iPhone XS Max + /// iPad Pro 3rd generation and later + /// + /// * [enabled] Whether to enable multi-camera video capture mode: true : Enable multi-camera capture mode; the SDK uses multiple cameras to capture video. false : Disable multi-camera capture mode; the SDK uses a single camera to capture video. /// * [config] Capture configuration for the second camera. See CameraCapturerConfiguration. /// /// 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. + /// 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 enableMultiCamera( {required bool enabled, required CameraCapturerConfiguration config}); /// Enables the video module. /// - /// Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode; if called during a call, the audio call switches to a video call. Call disableVideo to disable the video mode. A successful call of this method triggers the onRemoteVideoStateChanged callback on the remote client. This method enables the internal engine and is valid after leaving the channel. Calling this method will reset the entire engine, resulting in a slow response time. Instead of callling this method, you can independently control a specific video module based on your actual needs using the following methods: enableLocalVideo : Whether to enable the camera to create the local video stream. muteLocalVideoStream : Whether to publish the local video stream. muteRemoteVideoStream : Whether to subscribe to and play the remote video stream. muteAllRemoteVideoStreams : Whether to subscribe to and play all remote video streams. A successful call of this method resets enableLocalVideo , muteRemoteVideoStream , and muteAllRemoteVideoStreams . Proceed it with caution. + /// Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode; if called during a call, the audio call switches to a video call. Call disableVideo to disable the video mode. A successful call of this method triggers the onRemoteVideoStateChanged callback on the remote client. + /// This method enables the internal engine and is valid after leaving the channel. + /// Calling this method will reset the entire engine, resulting in a slow response time. Instead of callling this method, you can independently control a specific video module based on your actual needs using the following methods: enableLocalVideo : Whether to enable the camera to create the local video stream. muteLocalVideoStream : Whether to publish the local video stream. muteRemoteVideoStream : Whether to subscribe to and play the remote video stream. muteAllRemoteVideoStreams : Whether to subscribe to and play all remote video streams. + /// A successful call of this method resets enableLocalVideo, muteRemoteVideoStream, and muteAllRemoteVideoStreams. Proceed it with caution. /// /// 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. + /// 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 enableVideo(); /// Disables the video module. /// - /// This method can be called before joining a channel or during a call to disable the video module. If it is called before joining a channel, an audio call starts when you join the channel; if called during a call, a video call switches to an audio call. Call enableVideo to enable the video module. A successful call of this method triggers the onUserEnableVideo ( false ) callback on the remote client. This method affects the internal engine and can be called after leaving the channel. This method resets the internal engine and thus might takes some time to take effect. Agora recommends using the following APIs to control the video modules separately: enableLocalVideo : Whether to enable the camera to create the local video stream. muteLocalVideoStream : Whether to publish the local video stream. muteRemoteVideoStream : Whether to subscribe to and play the remote video stream. muteAllRemoteVideoStreams : Whether to subscribe to and play all remote video streams. + /// This method can be called before joining a channel or during a call to disable the video module. If it is called before joining a channel, an audio call starts when you join the channel; if called during a call, a video call switches to an audio call. Call enableVideo to enable the video module. A successful call of this method triggers the onUserEnableVideo (false) callback on the remote client. + /// This method affects the internal engine and can be called after leaving the channel. + /// This method resets the internal engine and thus might takes some time to take effect. Agora recommends using the following APIs to control the video modules separately: enableLocalVideo : Whether to enable the camera to create the local video stream. muteLocalVideoStream : Whether to publish the local video stream. muteRemoteVideoStream : Whether to subscribe to and play the remote video stream. muteAllRemoteVideoStreams : Whether to subscribe to and play all remote video streams. /// /// 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. + /// 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 disableVideo(); /// Enables the local video preview and specifies the video source for the preview. /// - /// You can call this method to enable local video preview. Before calling this method, ensure that you do the following: Call setupLocalVideo to set the local preview window. Call enableVideo to enable the video. The local preview enables the mirror mode by default. After the local video preview is enabled, if you call leaveChannel to exit the channel, the local preview remains until you call stopPreview to disable it. The video source type set in this method needs to be consistent with the video source type of VideoCanvas you set in setupLocalVideo . + /// You can call this method to enable local video preview. Call this method after the following: + /// Call setupLocalVideo to initialize the local preview. + /// Call enableVideo to enable the video module. + /// The local preview enables the mirror mode by default. + /// After the local video preview is enabled, if you call leaveChannel to exit the channel, the local preview remains until you call stopPreview to disable it. + /// The video source type set in this method needs to be consistent with the video source type of VideoCanvas you set in setupLocalVideo. /// /// * [sourceType] The type of the video source. See VideoSourceType. /// /// 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. + /// 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 startPreview( {VideoSourceType sourceType = VideoSourceType.videoSourceCameraPrimary}); @@ -3206,24 +3327,31 @@ abstract class RtcEngine { /// * [sourceType] The type of the video source. See VideoSourceType. /// /// 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. + /// 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 stopPreview( {VideoSourceType sourceType = VideoSourceType.videoSourceCameraPrimary}); /// Starts the last mile network probe test. /// - /// This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT). Once this method is enabled, the SDK returns the following callbacks: onLastmileQuality : The SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience. onLastmileProbeResult : The SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective. This method applies to the following scenarios: Before a user joins a channel, call this method to check the uplink network quality. In a live streaming channel, call this method to check the uplink network quality before an audience member switches to a host. Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted. A host should not call this method after joining a channel (when in a call). + /// This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT). Once this method is enabled, the SDK returns the following callbacks: onLastmileQuality : The SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience. onLastmileProbeResult : The SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective. This method applies to the following scenarios: + /// Before a user joins a channel, call this method to check the uplink network quality. + /// In a live streaming channel, call this method to check the uplink network quality before an audience member switches to a host. + /// Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted. + /// A host should not call this method after joining a channel (when in a call). /// /// * [config] The configurations of the last-mile network probe test. See LastmileProbeConfig. /// /// 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. + /// 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 startLastmileProbeTest(LastmileProbeConfig config); /// Stops the last mile network probe test. /// /// 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. + /// 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 stopLastmileProbeTest(); /// Sets the video encoder configuration. @@ -3233,19 +3361,23 @@ abstract class RtcEngine { /// * [config] Video profile. See VideoEncoderConfiguration. /// /// 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. + /// 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 setVideoEncoderConfiguration(VideoEncoderConfiguration config); /// 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. + /// 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. /// - /// * [enabled] Whether to enable the image enhancement function:true: Enable the image enhancement function.false: (Default) Disable the image enhancement function. + /// * [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. /// /// 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. + /// 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. Future setBeautyEffectOptions( {required bool enabled, required BeautyOptions options, @@ -3253,14 +3385,21 @@ abstract class RtcEngine { /// Sets low-light enhancement. /// - /// The low-light enhancement feature can adaptively adjust the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video. You can call this method to enable the color enhancement feature and set the options of the color enhancement effect. Call this method after calling enableVideo . Dark light enhancement has certain requirements for equipment performance. The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely. 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. + /// The low-light enhancement feature can adaptively adjust the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video. You can call this method to enable the color enhancement feature and set the options of the color enhancement effect. + /// Call this method after calling enableVideo. + /// Dark light enhancement has certain requirements for equipment performance. The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely. + /// 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. /// - /// * [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 function: true : Enable low-light enhancement function. false : (Default) Disable low-light enhancement function. /// * [options] The low-light enhancement options. See LowlightEnhanceOptions. /// * [type] The type of the video source. 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. < 0: Failure. + /// 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 setLowlightEnhanceOptions( {required bool enabled, required LowlightEnhanceOptions options, @@ -3268,14 +3407,21 @@ abstract class RtcEngine { /// Sets video noise reduction. /// - /// Underlit environments and low-end video capture devices can cause video images to contain significant noise, which affects video quality. In real-time interactive scenarios, video noise also consumes bitstream resources and reduces encoding efficiency during encoding. You can call this method to enable the video noise reduction feature and set the options of the video noise reduction effect. Call this method after calling enableVideo . Video noise reduction has certain requirements for equipment performance. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely. 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. + /// Underlit environments and low-end video capture devices can cause video images to contain significant noise, which affects video quality. In real-time interactive scenarios, video noise also consumes bitstream resources and reduces encoding efficiency during encoding. You can call this method to enable the video noise reduction feature and set the options of the video noise reduction effect. + /// Call this method after calling enableVideo. + /// Video noise reduction has certain requirements for equipment performance. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely. + /// 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. /// - /// * [enabled] Whether to enable video noise reduction:true: Enable video noise reduction.false: (Default) Disable video noise reduction. + /// * [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. /// * [type] The type of the video source. 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. < 0: Failure. + /// 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 setVideoDenoiserOptions( {required bool enabled, required VideoDenoiserOptions options, @@ -3283,14 +3429,21 @@ abstract class RtcEngine { /// Sets color enhancement. /// - /// The video images captured by the camera can have color distortion. The color enhancement feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid. You can call this method to enable the color enhancement feature and set the options of the color enhancement effect. Call this method after calling enableVideo . The color enhancement feature has certain performance requirements on devices. With color enhancement turned on, Agora recommends that you change the color enhancement level to one that consumes less performance or turn off color enhancement if your device is experiencing severe heat problems. 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. + /// The video images captured by the camera can have color distortion. The color enhancement feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid. You can call this method to enable the color enhancement feature and set the options of the color enhancement effect. + /// Call this method after calling enableVideo. + /// The color enhancement feature has certain performance requirements on devices. With color enhancement turned on, Agora recommends that you change the color enhancement level to one that consumes less performance or turn off color enhancement if your device is experiencing severe heat problems. + /// 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. /// - /// * [enabled] Whether to enable color enhancement:true Enable color enhancement.false: (Default) Disable color enhancement. + /// * [enabled] Whether to enable color enhancement: true Enable color enhancement. false : (Default) Disable color enhancement. /// * [options] The color enhancement options. See ColorEnhanceOptions. /// * [type] The type of the video source. 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. < 0: Failure. + /// 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 setColorEnhanceOptions( {required bool enabled, required ColorEnhanceOptions options, @@ -3298,15 +3451,37 @@ 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: Snapdragon 700 series 750G and later Snapdragon 800 series 835 and later Dimensity 700 series 720 and later Kirin 800 series 810 and later Kirin 900 series 980 and later Devices with an A9 chip and better, as follows: iPhone 6S and later iPad Air 3rd generation and later iPad 5th generation and later iPad Pro 1st generation and later iPad mini 5th generation and later Agora recommends that you use this feature in scenarios that meet the following conditions: A high-definition camera device is used, and the environment is uniformly lit. There are few objects in the captured video. Portraits are half-length and unobstructed. Ensure that the background is a solid color that is different from the color of the user's clothing. This method relies on the virtual background dynamic library libagora_segmentation_extension.dll . If the dynamic library is deleted, the function cannot be enabled normally. - /// - /// * [enabled] Whether to enable virtual background:true: Enable virtual background.false: Disable 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: + /// Snapdragon 700 series 750G and later + /// Snapdragon 800 series 835 and later + /// Dimensity 700 series 720 and later + /// Kirin 800 series 810 and later + /// Kirin 900 series 980 and later + /// Devices with an A9 chip and better, as follows: + /// iPhone 6S and later + /// iPad Air 3rd generation and later + /// iPad 5th generation and later + /// iPad Pro 1st generation and later + /// iPad mini 5th generation and later + /// Agora recommends that you use this feature in scenarios that meet the following conditions: + /// A high-definition camera device is used, and the environment is uniformly lit. + /// There are few objects in the captured video. Portraits are half-length and unobstructed. Ensure that the background is a solid color that is different from the color of the user's clothing. + /// This method relies on the virtual background dynamic library libagora_segmentation_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + /// + /// * [enabled] Whether to enable virtual background: true : Enable virtual background. false : Disable virtual background. /// * [backgroundSource] The custom background. See VirtualBackgroundSource. To adapt the resolution of the custom background image to that of the video captured by the SDK, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted. /// * [segproperty] Processing properties for background images. See SegmentationProperty. - /// * [type] The type of the video source. See MediaSourceType.In this method, this parameter supports only the following two settings:The default value is primaryCameraSource.If you want to use the second camera to capture video, set this parameter to secondaryCameraSource. + /// * [type] The type of the video source. See MediaSourceType. In this method, this parameter supports only the following two settings: + /// The default value is primaryCameraSource. + /// 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. -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. + /// 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. Future enableVirtualBackground( {required bool enabled, required VirtualBackgroundSource backgroundSource, @@ -3315,59 +3490,87 @@ abstract class RtcEngine { /// Initializes the video view of a remote user. /// - /// This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees. Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view. You need to specify the ID of the remote user in this method. If the remote user ID is unknown to the application, set it after the app receives the onUserJoined callback. To unbind the remote user from the view, set the view parameter to NULL. Once the remote user leaves the channel, the SDK unbinds the remote user. To update the rendering or mirror mode of the remote video view during a call, use the setRemoteRenderMode method. If you use the Agora recording function, the recording client joins the channel as a placeholder client, triggering the onUserJoined callback. Do not bind the placeholder client to the app view because the placeholder client does not send any video streams. If your app does not recognize the placeholder client, bind the remote user to the view when the SDK triggers the onFirstRemoteVideoDecoded callback. + /// This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees. Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view. You need to specify the ID of the remote user in this method. If the remote user ID is unknown to the application, set it after the app receives the onUserJoined callback. To unbind the remote user from the view, set the view parameter to NULL. Once the remote user leaves the channel, the SDK unbinds the remote user. + /// To update the rendering or mirror mode of the remote video view during a call, use the setRemoteRenderMode method. + /// If you use the Agora recording function, the recording client joins the channel as a placeholder client, triggering the onUserJoined callback. Do not bind the placeholder client to the app view because the placeholder client does not send any video streams. If your app does not recognize the placeholder client, bind the remote user to the view when the SDK triggers the onFirstRemoteVideoDecoded callback. /// /// * [canvas] The remote video view and settings. See VideoCanvas. /// /// 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. + /// 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 setupRemoteVideo(VideoCanvas canvas); /// Initializes the local video view. /// - /// This method initializes the video view of a local stream on the local device. It affects only the video view that the local user sees, not the published local video stream. Call this method to bind the local video stream to a video view and to set the rendering and mirror modes of the video view. After initialization, call this method to set the local video and then join the channel. The local video still binds to the view after you leave the channel. To unbind the local video from the view, set the view parameter as NULL . You can call this method either before or after joining a channel. To update the rendering or mirror mode of the local video view during a call, use the setLocalRenderMode method. + /// This method initializes the video view of a local stream on the local device. It affects only the video view that the local user sees, not the published local video stream. Call this method to bind the local video stream to a video view (view) and to set the rendering and mirror modes of the video view. After initialization, call this method to set the local video and then join the channel. The local video still binds to the view after you leave the channel. To unbind the local video from the view, set the view parameter as NULL. + /// You can call this method either before or after joining a channel. + /// To update the rendering or mirror mode of the local video view during a call, use the setLocalRenderMode method. /// /// * [canvas] The local video view and settings. See VideoCanvas. /// /// 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. + /// 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 setupLocalVideo(VideoCanvas canvas); /// Sets video application scenarios. /// /// After successfully calling this method, the SDK will automatically enable the best practice strategies and adjust key performance metrics based on the specified scenario, to optimize the video experience. Ensure that you call this method before joining a channel. /// - /// * [scenarioType] The type of video application scenario. See VideoApplicationScenarioType.If set to applicationScenarioMeeting (1), the SDK automatically enables the following strategies:In meeting scenarios where low-quality video streams are required to have a high bitrate, the SDK automatically enables multiple technologies used to deal with network congestions, to enhance the performance of the low-quality streams and to ensure the smooth reception by subscribers.The SDK monitors the number of subscribers to the high-quality video stream in real time and dynamically adjusts its configuration based on the number of subscribers.If nobody subscribers to the high-quality stream, the SDK automatically reduces its bitrate and frame rate to save upstream bandwidth.If someone subscribes to the high-quality stream, the SDK resets the high-quality stream to the VideoEncoderConfiguration configuration used in the most recent calling of setVideoEncoderConfiguration. If no configuration has been set by the user previously, the following values are used:Resolution: (Windows and macOS) 1280 × 720; (Android and iOS) 960 × 540Frame rate: 15 fpsBitrate: (Windows and macOS) 1600 Kbps; (Android and iOS) 1000 KbpsThe SDK monitors the number of subscribers to the low-quality video stream in real time and dynamically enables or disables it based on the number of subscribers.If the user has called setDualStreamMode to set that never send low-quality video stream (disableSimulcastStream), the dynamic adjustment of the low-quality stream in meeting scenarios will not take effect.If nobody subscribes to the low-quality stream, the SDK automatically disables it to save upstream bandwidth.If someone subscribes to the low-quality stream, the SDK enables the low-quality stream and resets it to the SimulcastStreamConfig configuration used in the most recent calling of setDualStreamMode. If no configuration has been set by the user previously, the following values are used:Resolution: 480 × 272Frame rate: 15 fpsBitrate: 500 Kbps + /// * [scenarioType] The type of video application scenario. See VideoApplicationScenarioType. If set to applicationScenarioMeeting (1), the SDK automatically enables the following strategies: + /// In meeting scenarios where low-quality video streams are required to have a high bitrate, the SDK automatically enables multiple technologies used to deal with network congestions, to enhance the performance of the low-quality streams and to ensure the smooth reception by subscribers. + /// The SDK monitors the number of subscribers to the high-quality video stream in real time and dynamically adjusts its configuration based on the number of subscribers. + /// If nobody subscribers to the high-quality stream, the SDK automatically reduces its bitrate and frame rate to save upstream bandwidth. + /// If someone subscribes to the high-quality stream, the SDK resets the high-quality stream to the VideoEncoderConfiguration configuration used in the most recent calling of setVideoEncoderConfiguration. If no configuration has been set by the user previously, the following values are used: + /// Resolution: (Windows and macOS) 1280 × 720; (Android and iOS) 960 × 540 + /// Frame rate: 15 fps + /// Bitrate: (Windows and macOS) 1600 Kbps; (Android and iOS) 1000 Kbps + /// The SDK monitors the number of subscribers to the low-quality video stream in real time and dynamically enables or disables it based on the number of subscribers. If the user has called setDualStreamMode to set that never send low-quality video stream (disableSimulcastStream), the dynamic adjustment of the low-quality stream in meeting scenarios will not take effect. + /// If nobody subscribes to the low-quality stream, the SDK automatically disables it to save upstream bandwidth. + /// If someone subscribes to the low-quality stream, the SDK enables the low-quality stream and resets it to the SimulcastStreamConfig configuration used in the most recent calling of setDualStreamMode. If no configuration has been set by the user previously, the following values are used: + /// Resolution: 480 × 272 + /// Frame rate: 15 fps + /// Bitrate: 500 Kbps /// /// 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. + /// 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 setVideoScenario(VideoApplicationScenarioType scenarioType); /// Enables the audio module. /// - /// The audio mode is enabled by default. This method enables the internal engine and can be called anytime after initialization. It is still valid after one leaves channel. Calling this method will reset the entire engine, resulting in a slow response time. Instead of callling this method, you can independently control a specific audio module based on your actual needs using the following methods: enableLocalAudio : Whether to enable the microphone to create the local audio stream. muteLocalAudioStream : Whether to publish the local audio stream. muteRemoteAudioStream : Whether to subscribe and play the remote audio stream. muteAllRemoteAudioStreams : Whether to subscribe to and play all remote audio streams. A successful call of this method resets enableLocalAudio , muteRemoteAudioStream , and muteAllRemoteAudioStreams . Proceed it with caution. + /// The audio mode is enabled by default. + /// This method enables the internal engine and can be called anytime after initialization. It is still valid after one leaves channel. + /// Calling this method will reset the entire engine, resulting in a slow response time. Instead of callling this method, you can independently control a specific audio module based on your actual needs using the following methods: enableLocalAudio : Whether to enable the microphone to create the local audio stream. muteLocalAudioStream : Whether to publish the local audio stream. muteRemoteAudioStream : Whether to subscribe and play the remote audio stream. muteAllRemoteAudioStreams : Whether to subscribe to and play all remote audio streams. + /// A successful call of this method resets enableLocalAudio, muteRemoteAudioStream, and muteAllRemoteAudioStreams. Proceed it with caution. /// /// 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. + /// 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 enableAudio(); /// Disables the audio module. /// - /// This method disables the internal engine and can be called anytime after initialization. It is still valid after one leaves channel. This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio modules separately: enableLocalAudio : Whether to enable the microphone to create the local audio stream. muteLocalAudioStream : Whether to publish the local audio stream. muteRemoteAudioStream : Whether to subscribe and play the remote audio stream. muteAllRemoteAudioStreams : Whether to subscribe to and play all remote audio streams. + /// This method disables the internal engine and can be called anytime after initialization. It is still valid after one leaves channel. + /// This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio modules separately: enableLocalAudio : Whether to enable the microphone to create the local audio stream. muteLocalAudioStream : Whether to publish the local audio stream. muteRemoteAudioStream : Whether to subscribe and play the remote audio stream. muteAllRemoteAudioStreams : Whether to subscribe to and play all remote audio streams. /// /// 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. + /// 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 disableAudio(); /// Sets the audio profile and audio scenario. /// - /// You can call this method either before or after joining a channel. In scenarios requiring high-quality audio, such as online music tutoring, Agora recommends you set profile as audioProfileMusicHighQuality (4) and scenario as audioScenarioGameStreaming (3) . + /// You can call this method either before or after joining a channel. + /// In scenarios requiring high-quality audio, such as online music tutoring, Agora recommends you set profile as audioProfileMusicHighQuality (4) and scenario as audioScenarioGameStreaming (3). /// /// * [profile] The audio profile, including the sampling rate, bitrate, encoding mode, and the number of channels. See AudioProfileType. /// * [scenario] The audio scenarios. See AudioScenarioType. Under different audio scenarios, the device uses different volume types. /// /// 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. + /// 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 setAudioProfile( {required AudioProfileType profile, AudioScenarioType scenario = AudioScenarioType.audioScenarioDefault}); @@ -3379,37 +3582,45 @@ abstract class RtcEngine { /// * [scenario] The audio scenarios. See AudioScenarioType. Under different audio scenarios, the device uses different volume types. /// /// 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. + /// 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 setAudioScenario(AudioScenarioType scenario); /// 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 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. + /// 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 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. /// - /// * [enabled] true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone).false: Disable the local audio function, that is, to stop local audio capturing. + /// * [enabled] true : (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone). false : Disable the local audio function, that is, to stop local audio capturing. /// /// 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. + /// 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 enableLocalAudio(bool enabled); /// Stops or resumes publishing the local audio stream. /// /// This method does not affect any ongoing audio recording, because it does not disable the audio capture device. A successful call of this method triggers the onUserMuteAudio and onRemoteAudioStateChanged callbacks on the remote client. /// - /// * [mute] Whether to stop publishing the local audio stream:true: Stops publishing the local audio stream.false: (Default) Resumes publishing the local audio stream. + /// * [mute] Whether to stop publishing the local audio stream: true : Stops publishing the local audio stream. false : (Default) Resumes publishing the local audio stream. /// /// 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. + /// 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 muteLocalAudioStream(bool mute); /// Stops or resumes subscribing to the audio streams of all remote users. /// - /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. Call this method after joining a channel. If you do not want to subscribe the audio streams of remote users before joining a channel, you can set autoSubscribeAudio as false when calling joinChannel . + /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. + /// Call this method after joining a channel. + /// If you do not want to subscribe the audio streams of remote users before joining a channel, you can set autoSubscribeAudio as false when calling joinChannel. /// - /// * [mute] Whether to stop subscribing to the audio streams of all remote users:true: Stops subscribing to the audio streams of all remote users.false: (Default) Subscribes to the audio streams of all remote users by default. + /// * [mute] Whether to stop subscribing to the audio streams of all remote users: true : Stops subscribing to the audio streams of all remote users. false : (Default) Subscribes to the audio streams of all remote users by default. /// /// 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. + /// 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 muteAllRemoteAudioStreams(bool mute); /// @nodoc @@ -3420,40 +3631,50 @@ abstract class RtcEngine { /// Call this method after joining a channel. /// /// * [uid] The user ID of the specified user. - /// * [mute] Whether to subscribe to the specified remote user's audio stream.true: Stop subscribing to the audio stream of the specified user.false: (Default) Subscribe to the audio stream of the specified user. + /// * [mute] Whether to subscribe to the specified remote user's audio stream. true : Stop subscribing to the audio stream of the specified user. false : (Default) Subscribe to the audio stream of the specified user. /// /// 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. + /// 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 muteRemoteAudioStream({required int uid, required bool mute}); /// Stops or resumes publishing the local video stream. /// - /// A successful call of this method triggers the onUserMuteVideo callback on the remote client. This method executes faster than the enableLocalVideo ( false ) method, which controls the sending of the local video stream. This method does not affect any ongoing video recording, because it does not disable the camera. + /// A successful call of this method triggers the onUserMuteVideo callback on the remote client. + /// This method executes faster than the enableLocalVideo (false) method, which controls the sending of the local video stream. + /// This method does not affect any ongoing video recording, because it does not disable the camera. /// - /// * [mute] Whether to stop publishing the local video stream.true: Stop publishing the local video stream.false: (Default) Publish the local video stream. + /// * [mute] Whether to stop publishing the local video stream. true : Stop publishing the local video stream. false : (Default) Publish the local video stream. /// /// 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. + /// 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 muteLocalVideoStream(bool mute); /// Enables/Disables the local video capture. /// - /// This method disables or re-enables the local video capture, and does not affect receiving the remote video stream. After calling enableVideo , the local video capture is enabled by default. You can call enableLocalVideo ( false ) to disable the local video capture. If you want to re-enable the local video capture, call enableLocalVideo ( true ). After the local video capturer is successfully disabled or re-enabled, the SDK triggers the onRemoteVideoStateChanged callback on the remote client. You can call this method either before or after joining a channel. This method enables the internal engine and is valid after leaving the channel. + /// This method disables or re-enables the local video capture, and does not affect receiving the remote video stream. After calling enableVideo, the local video capture is enabled by default. You can call enableLocalVideo (false) to disable the local video capture. If you want to re-enable the local video capture, call enableLocalVideo (true). After the local video capturer is successfully disabled or re-enabled, the SDK triggers the onRemoteVideoStateChanged callback on the remote client. + /// You can call this method either before or after joining a channel. + /// This method enables the internal engine and is valid after leaving the channel. /// - /// * [enabled] Whether to enable the local video capture.true: (Default) Enable the local video capture.false: Disable the local video capture. Once the local video is disabled, the remote users cannot receive the video stream of the local user, while the local user can still receive the video streams of remote users. When set to false, this method does not require a local camera. + /// * [enabled] Whether to enable the local video capture. true : (Default) Enable the local video capture. false : Disable the local video capture. Once the local video is disabled, the remote users cannot receive the video stream of the local user, while the local user can still receive the video streams of remote users. When set to false, this method does not require a local camera. /// /// 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. + /// 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 enableLocalVideo(bool enabled); /// Stops or resumes subscribing to the video streams of all remote users. /// - /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. Call this method after joining a channel. If you do not want to subscribe the video streams of remote users before joining a channel, you can call joinChannel and set autoSubscribeVideo as false . + /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. + /// Call this method after joining a channel. + /// If you do not want to subscribe the video streams of remote users before joining a channel, you can call joinChannel and set autoSubscribeVideo as false. /// - /// * [mute] Whether to stop subscribing to the video streams of all remote users.true: Stop subscribing to the video streams of all remote users.false: (Default) Subscribe to the audio streams of all remote users by default. + /// * [mute] Whether to stop subscribing to the video streams of all remote users. true : Stop subscribing to the video streams of all remote users. false : (Default) Subscribe to the audio streams of all remote users by default. /// /// 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. + /// 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 muteAllRemoteVideoStreams(bool mute); /// @nodoc @@ -3464,91 +3685,124 @@ abstract class RtcEngine { /// Call this method after joining a channel. /// /// * [uid] The user ID of the specified user. - /// * [mute] Whether to subscribe to the specified remote user's video stream.true: Stop subscribing to the video streams of the specified user.false: (Default) Subscribe to the video stream of the specified user. + /// * [mute] Whether to subscribe to the specified remote user's video stream. true : Stop subscribing to the video streams of the specified user. false : (Default) Subscribe to the video stream of the specified user. /// /// 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. + /// 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 muteRemoteVideoStream({required int uid, required bool mute}); /// Sets the stream type of the remote video. /// - /// 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. The SDK enables the low-quality video stream auto mode on the sender by default (not actively sending low-quality video streams). The host at the receiving end can call this method to initiate a low-quality video stream stream request on the receiving end, and the sender automatically switches to the low-quality video stream mode after 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. + /// 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. 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. /// /// * [uid] The user ID. /// * [streamType] The video stream type: VideoStreamType. /// /// 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. + /// 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 setRemoteVideoStreamType( {required int uid, required VideoStreamType streamType}); /// Options for subscribing to remote video streams. /// - /// When a remote user has enabled dual-stream mode, you can call this method to choose the option for subscribing to the video streams sent by the remote user. If you only register one VideoFrameObserver object, the SDK subscribes to the raw video data and encoded video data by default (the effect is equivalent to setting encodedFrameOnly to false ). If you only register one VideoEncodedFrameObserver object, the SDK only subscribes to the encoded video data by default (the effect is equivalent to setting encodedFrameOnly to true ). If you register one VideoFrameObserver object and one VideoEncodedFrameObserver object successively, the SDK subscribes to the encoded video data by default (the effect is equivalent to setting encodedFrameOnly to false ). If you call this method first with the options parameter set, and then register one VideoFrameObserver or VideoEncodedFrameObserver object, you need to call this method again and set the options parameter as described in the above two items to get the desired results. Agora recommends the following steps: Set autoSubscribeVideo to false when calling joinChannel to join a channel. Call this method after receiving the onUserJoined callback to set the subscription options for the specified remote user's video stream. Call the muteRemoteVideoStream method to resume subscribing to the video stream of the specified remote user. If you set encodedFrameOnly to true in the previous step, the SDK triggers the onEncodedVideoFrameReceived callback locally to report the received encoded video frame information. + /// When a remote user has enabled dual-stream mode, you can call this method to choose the option for subscribing to the video streams sent by the remote user. + /// If you only register one VideoFrameObserver object, the SDK subscribes to the raw video data and encoded video data by default (the effect is equivalent to setting encodedFrameOnly to false). + /// If you only register one VideoEncodedFrameObserver object, the SDK only subscribes to the encoded video data by default (the effect is equivalent to setting encodedFrameOnly to true). + /// If you register one VideoFrameObserver object and one VideoEncodedFrameObserver object successively, the SDK subscribes to the encoded video data by default (the effect is equivalent to setting encodedFrameOnly to false). + /// If you call this method first with the options parameter set, and then register one VideoFrameObserver or VideoEncodedFrameObserver object, you need to call this method again and set the options parameter as described in the above two items to get the desired results. Agora recommends the following steps: + /// Set autoSubscribeVideo to false when calling joinChannel to join a channel. + /// Call this method after receiving the onUserJoined callback to set the subscription options for the specified remote user's video stream. + /// Call the muteRemoteVideoStream method to resume subscribing to the video stream of the specified remote user. If you set encodedFrameOnly to true in the previous step, the SDK triggers the onEncodedVideoFrameReceived callback locally to report the received encoded video frame information. /// /// * [uid] The user ID of the remote user. /// * [options] The video subscription options. See VideoSubscriptionOptions. /// /// 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. + /// 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 setRemoteVideoSubscriptionOptions( {required int uid, required VideoSubscriptionOptions options}); /// Sets the default stream type of subscrption for remote video streams. /// - /// The SDK enables the low-quality video stream auto mode on the sender by default (not actively sending low-quality video streams). The host at the receiving end can call this method to initiate a low-quality video stream stream request on the receiving end, and the sender automatically switches to the low-quality video stream mode after receiving the request. 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. 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. + /// 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. + /// 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. /// /// * [streamType] The default video-stream type. See VideoStreamType. /// /// 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. + /// 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 setRemoteDefaultVideoStreamType(VideoStreamType streamType); /// Set the blocklist of subscriptions for audio streams. /// - /// You can call this method to specify the audio streams of a user that you do not want to subscribe to. You can call this method either before or after joining a channel. The blocklist is not affected by the setting in muteRemoteAudioStream , muteAllRemoteAudioStreams , and autoSubscribeAudio in ChannelMediaOptions . Once the blocklist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. + /// You can call this method to specify the audio streams of a user that you do not want to subscribe to. + /// You can call this method either before or after joining a channel. + /// The blocklist is not affected by the setting in muteRemoteAudioStream, muteAllRemoteAudioStreams, and autoSubscribeAudio in ChannelMediaOptions. + /// Once the blocklist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. + /// If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. /// - /// * [uidList] The user ID list of users that you do not want to subscribe to.If you want to specify the audio streams of a user that you do not want to subscribe to, add the user ID in this list. If you want to remove a user from the blocklist, you need to call the setSubscribeAudioBlocklist method to update the user ID list; this means you only add the uid of users that you do not want to subscribe to in the new user ID list. + /// * [uidList] The user ID list of users that you do not want to subscribe to. If you want to specify the audio streams of a user that you do not want to subscribe to, add the user ID in this list. If you want to remove a user from the blocklist, you need to call the setSubscribeAudioBlocklist method to update the user ID list; this means you only add the uid of users that you do not want to subscribe to in the new user ID list. /// * [uidNumber] The number of users in the user ID list. /// /// 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. + /// 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 setSubscribeAudioBlocklist( {required List uidList, required int uidNumber}); /// Sets the allowlist of subscriptions for audio streams. /// - /// You can call this method to specify the audio streams of a user that you want to subscribe to. If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. You can call this method either before or after joining a channel. The allowlist is not affected by the setting in muteRemoteAudioStream , muteAllRemoteAudioStreams and autoSubscribeAudio in ChannelMediaOptions . Once the allowlist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. + /// You can call this method to specify the audio streams of a user that you want to subscribe to. + /// If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. + /// You can call this method either before or after joining a channel. + /// The allowlist is not affected by the setting in muteRemoteAudioStream, muteAllRemoteAudioStreams and autoSubscribeAudio in ChannelMediaOptions. + /// Once the allowlist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. /// - /// * [uidList] The user ID list of users that you want to subscribe to.If you want to specify the audio streams of a user for subscription, add the user ID in this list. If you want to remove a user from the allowlist, you need to call the setSubscribeAudioAllowlist method to update the user ID list; this means you only add the uid of users that you want to subscribe to in the new user ID list. + /// * [uidList] The user ID list of users that you want to subscribe to. If you want to specify the audio streams of a user for subscription, add the user ID in this list. If you want to remove a user from the allowlist, you need to call the setSubscribeAudioAllowlist method to update the user ID list; this means you only add the uid of users that you want to subscribe to in the new user ID list. /// * [uidNumber] The number of users in the user ID list. /// /// 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. + /// 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 setSubscribeAudioAllowlist( {required List uidList, required int uidNumber}); /// Set the blocklist of subscriptions for video streams. /// - /// You can call this method to specify the video streams of a user that you do not want to subscribe to. If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. Once the blocklist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. You can call this method either before or after joining a channel. The blocklist is not affected by the setting in muteRemoteVideoStream , muteAllRemoteVideoStreams and autoSubscribeAudio in ChannelMediaOptions . + /// You can call this method to specify the video streams of a user that you do not want to subscribe to. + /// If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. + /// Once the blocklist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. + /// You can call this method either before or after joining a channel. + /// The blocklist is not affected by the setting in muteRemoteVideoStream, muteAllRemoteVideoStreams and autoSubscribeAudio in ChannelMediaOptions. /// - /// * [uidList] The user ID list of users that you do not want to subscribe to.If you want to specify the video streams of a user that you do not want to subscribe to, add the user ID of that user in this list. If you want to remove a user from the blocklist, you need to call the setSubscribeVideoBlocklist method to update the user ID list; this means you only add the uid of users that you do not want to subscribe to in the new user ID list. + /// * [uidList] The user ID list of users that you do not want to subscribe to. If you want to specify the video streams of a user that you do not want to subscribe to, add the user ID of that user in this list. If you want to remove a user from the blocklist, you need to call the setSubscribeVideoBlocklist method to update the user ID list; this means you only add the uid of users that you do not want to subscribe to in the new user ID list. /// * [uidNumber] The number of users in the user ID list. /// /// 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. + /// 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 setSubscribeVideoBlocklist( {required List uidList, required int uidNumber}); /// Set the allowlist of subscriptions for video streams. /// - /// You can call this method to specify the video streams of a user that you want to subscribe to. If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. Once the allowlist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. You can call this method either before or after joining a channel. The allowlist is not affected by the setting in muteRemoteVideoStream , muteAllRemoteVideoStreams and autoSubscribeAudio in ChannelMediaOptions . + /// You can call this method to specify the video streams of a user that you want to subscribe to. + /// If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. + /// Once the allowlist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. + /// You can call this method either before or after joining a channel. + /// The allowlist is not affected by the setting in muteRemoteVideoStream, muteAllRemoteVideoStreams and autoSubscribeAudio in ChannelMediaOptions. /// - /// * [uidList] The user ID list of users that you want to subscribe to.If you want to specify the video streams of a user for subscription, add the user ID of that user in this list. If you want to remove a user from the allowlist, you need to call the setSubscribeVideoAllowlist method to update the user ID list; this means you only add the uid of users that you want to subscribe to in the new user ID list. + /// * [uidList] The user ID list of users that you want to subscribe to. If you want to specify the video streams of a user for subscription, add the user ID of that user in this list. If you want to remove a user from the allowlist, you need to call the setSubscribeVideoAllowlist method to update the user ID list; this means you only add the uid of users that you want to subscribe to in the new user ID list. /// * [uidNumber] The number of users in the user ID list. /// /// 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. + /// 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 setSubscribeVideoAllowlist( {required List uidList, required int uidNumber}); @@ -3556,28 +3810,35 @@ abstract class RtcEngine { /// /// This method enables the SDK to regularly report the volume information to the app of the local user who sends a stream and remote users (three users at most) whose instantaneous volumes are the highest. Once you call this method and users send streams in the channel, the SDK triggers the onAudioVolumeIndication callback at the time interval set in this method. You can call this method either before or after joining a channel. /// - /// * [interval] Sets the time interval between two consecutive volume indications:≤ 0: Disables the volume indication.> 0: Time interval (ms) between two consecutive volume indications. The lowest value is 50. + /// * [interval] Sets the time interval between two consecutive volume indications: + /// ≤ 0: Disables the volume indication. + /// > 0: Time interval (ms) between two consecutive volume indications. The lowest value is 50. /// * [smooth] The smoothing factor that sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The recommended value is 3. The greater the value, the more sensitive the indicator. - /// * [reportVad] true: Enables the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback reports the voice activity status of the local user.false: (Default) Disables the voice activity detection of the local user. Once it is disabled, the vad parameter of the onAudioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user. + /// * [reportVad] true : Enables the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback reports the voice activity status of the local user. false : (Default) Disables the voice activity detection of the local user. Once it is disabled, the vad parameter of the onAudioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user. /// /// 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. + /// 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 enableAudioVolumeIndication( {required int interval, required int smooth, required bool reportVad}); /// Starts audio recording on the client and sets recording configurations. /// - /// The Agora SDK allows recording during a call. After successfully calling this method, you can record the audio of users in the channel and get an audio recording file. Supported formats of the recording file are as follows: WAV: High-fidelity files with typically larger file sizes. For example, if the sample rate is 32,000 Hz, the file size for 10-minute recording is approximately 73 MB. AAC: Low-fidelity files with typically smaller file sizes. For example, if the sample rate is 32,000 Hz and the recording quality is audioRecordingQualityMedium , the file size for 10-minute recording is approximately 2 MB. Once the user leaves the channel, the recording automatically stops. Call this method after joining a channel. + /// The Agora SDK allows recording during a call. After successfully calling this method, you can record the audio of users in the channel and get an audio recording file. Supported formats of the recording file are as follows: + /// WAV: High-fidelity files with typically larger file sizes. For example, if the sample rate is 32,000 Hz, the file size for 10-minute recording is approximately 73 MB. + /// AAC: Low-fidelity files with typically smaller file sizes. For example, if the sample rate is 32,000 Hz and the recording quality is audioRecordingQualityMedium, the file size for 10-minute recording is approximately 2 MB. Once the user leaves the channel, the recording automatically stops. Call this method after joining a channel. /// /// * [config] Recording configurations. See AudioRecordingConfiguration. /// /// 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. + /// 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 startAudioRecording(AudioRecordingConfiguration config); /// Registers an encoded audio observer. /// - /// Call this method after joining a channel. You can call this method or startAudioRecording to set the recording type and quality of audio files, but Agora does not recommend using this method and startAudioRecording at the same time. Only the method called later will take effect. + /// Call this method after joining a channel. + /// You can call this method or startAudioRecording to set the recording type and quality of audio files, but Agora does not recommend using this method and startAudioRecording at the same time. Only the method called later will take effect. /// /// * [config] Observer settings for the encoded audio. See AudioEncodedFrameObserverConfig. /// * [observer] The encoded audio observer. See AudioEncodedFrameObserver. @@ -3591,19 +3852,22 @@ abstract class RtcEngine { /// Stops the audio recording on the client. /// /// 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. + /// 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 stopAudioRecording(); /// Creates a media player instance. /// /// Returns - /// The MediaPlayer instance, if the method call succeeds. An empty pointer, if the method call fails. + /// The MediaPlayer instance, if the method call succeeds. + /// An empty pointer, if the method call fails. Future createMediaPlayer(); /// Destroys the media player instance. /// /// 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. + /// 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 destroyMediaPlayer(MediaPlayer mediaPlayer); /// @nodoc @@ -3614,15 +3878,30 @@ abstract class RtcEngine { /// Starts playing the music file. /// - /// This method mixes the specified local or online audio file with the audio from the microphone, or replaces the microphone's audio with the specified local or remote audio file. A successful method call triggers the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. When the audio mixing file playback finishes, the SDK triggers the onAudioMixingStateChanged ( audioMixingStateStopped ) callback on the local client. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support . You can call this method either before or after joining a channel. If you need to call startAudioMixing multiple times, ensure that the time interval between calling this method is more than 500 ms. If the local music file does not exist, the SDK does not support the file format, or the the SDK cannot access the music file URL, the SDK reports 701. - /// - /// * [filePath] File path:Android: The file path, which needs to be accurate to the file name and suffix. Agora supports URL addresses, absolute paths, or file paths that start with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%3A14441Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: C:\music\audio.mp4.iOS or macOS: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. - /// * [loopback] Whether to only play music files on the local client:true: Only play music files on the local client so that only the local user can hear the music.false: Publish music files to remote clients so that both the local user and remote users can hear the music. - /// * [cycle] The number of times the music file plays.≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file while 1 means that the SDK plays once.-1: Play the audio file in an infinite loop. + /// This method mixes the specified local or online audio file with the audio from the microphone, or replaces the microphone's audio with the specified local or remote audio file. A successful method call triggers the onAudioMixingStateChanged (audioMixingStatePlaying) callback. When the audio mixing file playback finishes, the SDK triggers the onAudioMixingStateChanged (audioMixingStateStopped) callback on the local client. + /// For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support. + /// You can call this method either before or after joining a channel. If you need to call startAudioMixing multiple times, ensure that the time interval between calling this method is more than 500 ms. + /// If the local music file does not exist, the SDK does not support the file format, or the the SDK cannot access the music file URL, the SDK reports 701. + /// + /// * [filePath] File path: + /// Android: The file path, which needs to be accurate to the file name and suffix. Agora supports URL addresses, absolute paths, or file paths that start with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example : content://com.android.providers.media.documents/document/audio%3A14441 + /// Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example : C:\music\audio.mp4. + /// iOS or macOS: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. + /// * [loopback] Whether to only play music files on the local client: true : Only play music files on the local client so that only the local user can hear the music. false : Publish music files to remote clients so that both the local user and remote users can hear the music. + /// * [cycle] The number of times the music file plays. + /// ≥ 0: The number of playback times. For example, 0 means that the SDK does not play the music file while 1 means that the SDK plays once. + /// -1: Play the audio file in an infinite loop. /// * [startPos] The playback position (ms) of the music file. /// /// 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: A general error occurs (no specified reason). -2: The parameter is invalid. -3: The SDK is not ready. The audio module is disabled. The program is not complete. The initialization of RtcEngine fails. Reinitialize the RtcEngine . + /// 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: A general error occurs (no specified reason). + /// -2: The parameter is invalid. + /// -3: The SDK is not ready. + /// The audio module is disabled. + /// The program is not complete. + /// The initialization of RtcEngine fails. Reinitialize the RtcEngine. Future startAudioMixing( {required String filePath, required bool loopback, @@ -3634,7 +3913,8 @@ abstract class RtcEngine { /// This method stops the audio mixing. Call this method when you are in a channel. /// /// 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. + /// 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 stopAudioMixing(); /// Pauses playing and mixing the music file. @@ -3642,7 +3922,8 @@ abstract class RtcEngine { /// Call this method after joining a channel. /// /// 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. + /// 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 pauseAudioMixing(); /// Resumes playing and mixing the music file. @@ -3650,165 +3931,198 @@ abstract class RtcEngine { /// This method resumes playing and mixing the music file. Call this method when you are in a channel. /// /// 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. + /// 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 resumeAudioMixing(); /// Selects the audio track used during playback. /// - /// After getting the track index of the audio file, you can call this method to specify any track to play. For example, if different tracks of a multi-track file store songs in different languages, you can call this method to set the playback language. For the supported formats of audio files, see . You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. + /// After getting the track index of the audio file, you can call this method to specify any track to play. For example, if different tracks of a multi-track file store songs in different languages, you can call this method to set the playback language. + /// For the supported formats of audio files, see. + /// You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// - /// * [index] The audio track you want to specify. The value range is [0, getAudioTrackCount()]. + /// * [index] The audio track you want to specify. The value range is [0, getAudioTrackCount ()]. /// /// 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. + /// 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 selectAudioTrack(int index); /// Gets the index of audio tracks of the current music file. /// - /// You need to 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. /// /// Returns - /// The SDK returns the index of the audio tracks if the method call succeeds. < 0: Failure. + /// The SDK returns the index of the audio tracks if the method call succeeds. + /// < 0: Failure. Future getAudioTrackCount(); /// Adjusts the volume during audio mixing. /// - /// This method adjusts the audio mixing volume on both the local client and remote clients. Call this method after startAudioMixing . + /// This method adjusts the audio mixing volume on both the local client and remote clients. + /// Call this method after startAudioMixing. /// /// * [volume] Audio mixing volume. The value ranges between 0 and 100. The default value is 100, which 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. + /// 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 adjustAudioMixingVolume(int volume); /// Adjusts the volume of audio mixing for publishing. /// - /// This method adjusts the volume of audio mixing for publishing (sending to other users). Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. + /// This method adjusts the volume of audio mixing for publishing (sending to other users). Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// /// * [volume] The volume of audio mixing for local playback. The value ranges between 0 and 100 (default). 100 represents 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. + /// 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 adjustAudioMixingPublishVolume(int volume); /// Retrieves the audio mixing volume for publishing. /// - /// This method helps troubleshoot audio volume‑related issues. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. + /// This method helps troubleshoot audio volume‑related issues. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// /// Returns - /// ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. < 0: Failure. + /// ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. + /// < 0: Failure. Future getAudioMixingPublishVolume(); /// Adjusts the volume of audio mixing for local playback. /// - /// Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. + /// Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// /// * [volume] The volume of audio mixing for local playback. The value ranges between 0 and 100 (default). 100 represents 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. + /// 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 adjustAudioMixingPlayoutVolume(int volume); /// Retrieves the audio mixing volume for local playback. /// - /// This method helps troubleshoot audio volume‑related issues. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. + /// This method helps troubleshoot audio volume‑related issues. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// /// Returns - /// ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. < 0: Failure. + /// ≥ 0: The audio mixing volume, if this method call succeeds. The value range is [0,100]. + /// < 0: Failure. Future getAudioMixingPlayoutVolume(); /// Retrieves the duration (ms) of the music file. /// - /// Retrieves the total duration (ms) of the audio. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. + /// Retrieves the total duration (ms) of the audio. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// /// Returns - /// ≥ 0: The audio mixing duration, if this method call succeeds. < 0: Failure. + /// ≥ 0: The audio mixing duration, if this method call succeeds. + /// < 0: Failure. Future getAudioMixingDuration(); /// Retrieves the playback position (ms) of the music file. /// - /// Retrieves the playback position (ms) of the audio. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. If you need to call getAudioMixingCurrentPosition multiple times, ensure that the time interval between calling this method is more than 500 ms. + /// Retrieves the playback position (ms) of the audio. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. + /// If you need to call getAudioMixingCurrentPosition multiple times, ensure that the time interval between calling this method is more than 500 ms. /// /// Returns - /// ≥ 0: The current playback position (ms) of the audio mixing, if this method call succeeds. 0 represents that the current music file does not start playing. < 0: Failure. + /// ≥ 0: The current playback position (ms) of the audio mixing, if this method call succeeds. 0 represents that the current music file does not start playing. + /// < 0: Failure. Future getAudioMixingCurrentPosition(); /// Sets the audio mixing position. /// - /// Call this method to set the playback position of the music file to a different starting position (the default plays from the beginning). You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. + /// Call this method to set the playback position of the music file to a different starting position (the default plays from the beginning). You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// /// * [pos] Integer. The playback position (ms). /// /// 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. + /// 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 setAudioMixingPosition(int pos); /// 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. This method only applies to stereo audio files. + /// 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. + /// This method only applies to stereo audio files. /// /// * [mode] The channel mode. See AudioMixingDualMonoMode. /// /// 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. + /// 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 setAudioMixingDualMonoMode(AudioMixingDualMonoMode mode); /// Sets the pitch of the local music file. /// - /// When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged ( audioMixingStatePlaying ) callback. + /// When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only. You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (audioMixingStatePlaying) callback. /// /// * [pitch] Sets the pitch of the local music file by the chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file. /// /// 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. + /// 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 setAudioMixingPitch(int pitch); /// Retrieves the volume of the audio effects. /// - /// The volume is an integer ranging from 0 to 100. The default value is 100, which means the original volume. Call this method after playEffect . + /// The volume is an integer ranging from 0 to 100. The default value is 100, which means the original volume. Call this method after playEffect. /// /// Returns - /// Volume of the audio effects, if this method call succeeds. < 0: Failure. + /// Volume of the audio effects, if this method call succeeds. + /// < 0: Failure. Future getEffectsVolume(); /// Sets the volume of the audio effects. /// - /// Call this method after playEffect . + /// Call this method after playEffect. /// /// * [volume] The playback volume. The value range is [0, 100]. The default value is 100, which represents 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. + /// 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 setEffectsVolume(int volume); /// Preloads a specified audio effect file into the memory. /// - /// To ensure smooth communication, It is recommended that you limit the size of the audio effect file. You can call this method to preload the audio effect before calling joinChannel . This method does not support online audio effect files. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support . + /// To ensure smooth communication, It is recommended that you limit the size of the audio effect file. You can call this method to preload the audio effect before calling joinChannel. + /// This method does not support online audio effect files. + /// For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support. /// /// * [soundId] The audio effect ID. The ID of each audio effect file is unique. - /// * [filePath] File path:Android: The file path, which needs to be accurate to the file name and suffix. Agora supports URL addresses, absolute paths, or file paths that start with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%3A14441Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: C:\music\audio.mp4.iOS or macOS: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. + /// * [filePath] File path: + /// Android: The file path, which needs to be accurate to the file name and suffix. Agora supports URL addresses, absolute paths, or file paths that start with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example : content://com.android.providers.media.documents/document/audio%3A14441 + /// Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example : C:\music\audio.mp4. + /// iOS or macOS: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. /// * [startPos] The playback position (ms) of the audio effect file. /// /// 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. + /// 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 preloadEffect( {required int soundId, required String filePath, int startPos = 0}); /// Plays the specified local or online audio effect file. /// - /// If you use this method to play an online audio effect file, Agora recommends that you cache the online audio effect file to your local device, call preloadEffect to preload the cached audio effect file into memory, and then call this method to play the audio effect. Otherwise, you might encounter playback failures or no sound during playback due to loading timeouts or failures. To play multiple audio effect files at the same time, call this method multiple times with different soundId and filePath . To achieve the optimal user experience, Agora recommends that do not playing more than three audio files at the same time. After the playback of an audio effect file completes, the SDK triggers the onAudioEffectFinished callback. + /// If you use this method to play an online audio effect file, Agora recommends that you cache the online audio effect file to your local device, call preloadEffect to preload the cached audio effect file into memory, and then call this method to play the audio effect. Otherwise, you might encounter playback failures or no sound during playback due to loading timeouts or failures. To play multiple audio effect files at the same time, call this method multiple times with different soundId and filePath. To achieve the optimal user experience, Agora recommends that do not playing more than three audio files at the same time. After the playback of an audio effect file completes, the SDK triggers the onAudioEffectFinished callback. /// - /// * [soundId] The audio effect ID. The ID of each audio effect file is unique.If you have preloaded an audio effect into memory by calling preloadEffect, ensure that the value of this parameter is the same as that of soundId in preloadEffect. - /// * [filePath] The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example, C:\music\audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats.If you have preloaded an audio effect into memory by calling preloadEffect, ensure that the value of this parameter is the same as that of filePath in preloadEffect. - /// * [loopCount] The number of times the audio effect loops.≥ 0: The number of playback times. For example, 1 means looping one time, which means playing the audio effect two times in total.-1: Play the audio file in an infinite loop. + /// * [soundId] The audio effect ID. The ID of each audio effect file is unique. If you have preloaded an audio effect into memory by calling preloadEffect, ensure that the value of this parameter is the same as that of soundId in preloadEffect. + /// * [filePath] The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example, C:\music\audio.mp4. Supported audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. See supported audio formats. If you have preloaded an audio effect into memory by calling preloadEffect, ensure that the value of this parameter is the same as that of filePath in preloadEffect. + /// * [loopCount] The number of times the audio effect loops. + /// ≥ 0: The number of playback times. For example, 1 means looping one time, which means playing the audio effect two times in total. + /// -1: Play the audio file in an infinite loop. /// * [pitch] The pitch of the audio effect. The value range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch. - /// * [pan] The spatial position of the audio effect. The value ranges between -1.0 and 1.0:-1.0: The audio effect is heard on the left of the user.0.0: The audio effect is heard in front of the user.1.0: The audio effect is heard on the right of the user. + /// * [pan] The spatial position of the audio effect. The value ranges between -1.0 and 1.0: + /// -1.0: The audio effect is heard on the left of the user. + /// 0.0: The audio effect is heard in front of the user. + /// 1.0: The audio effect is heard on the right of the user. /// * [gain] The volume of the audio effect. The value range is 0.0 to 100.0. The default value is 100.0, which means the original volume. The smaller the value, the lower the volume. - /// * [publish] Whether to publish the audio effect to the remote users:true: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.false: Do not publish the audio effect to the remote users. Only the local user can hear the audio effect. + /// * [publish] Whether to publish the audio effect to the remote users: true : Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect. false : Do not publish the audio effect to the remote users. Only the local user can hear the audio effect. /// * [startPos] The playback position (ms) of the audio effect file. /// /// 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. + /// 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 playEffect( {required int soundId, required String filePath, @@ -3823,14 +4137,21 @@ abstract class RtcEngine { /// /// After calling preloadEffect multiple times to preload multiple audio effects into the memory, you can call this method to play all the specified audio effects for all users in the channel. /// - /// * [loopCount] The number of times the audio effect loops:-1: Play the audio effect files in an indefinite loop until you call stopEffect or stopAllEffects.0: Play the audio effect once.1: Play the audio effect twice. + /// * [loopCount] The number of times the audio effect loops: + /// -1: Play the audio effect files in an indefinite loop until you call stopEffect or stopAllEffects. + /// 0: Play the audio effect once. + /// 1: Play the audio effect twice. /// * [pitch] The pitch of the audio effect. The value ranges between 0.5 and 2.0. The default value is 1.0 (original pitch). The lower the value, the lower the pitch. - /// * [pan] The spatial position of the audio effect. The value ranges between -1.0 and 1.0:-1.0: The audio effect shows on the left.0: The audio effect shows ahead.1.0: The audio effect shows on the right. + /// * [pan] The spatial position of the audio effect. The value ranges between -1.0 and 1.0: + /// -1.0: The audio effect shows on the left. + /// 0: The audio effect shows ahead. + /// 1.0: The audio effect shows on the right. /// * [gain] The volume of the audio effect. The value range is [0, 100]. The default value is 100 (original volume). The smaller the value, the lower the volume. - /// * [publish] Whether to publish the audio effect to the remote users:true: Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect.false: (Default) Do not publish the audio effect to the remote users. Only the local user can hear the audio effect. + /// * [publish] Whether to publish the audio effect to the remote users: true : Publish the audio effect to the remote users. Both the local user and remote users can hear the audio effect. false : (Default) Do not publish the audio effect to the remote users. Only the local user can hear the audio effect. /// /// 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. + /// 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 playAllEffects( {required int loopCount, required double pitch, @@ -3843,7 +4164,8 @@ abstract class RtcEngine { /// * [soundId] The ID of the audio effect file. /// /// Returns - /// ≥ 0: Returns the volume of the specified audio effect, if the method call is successful. The value ranges between 0 and 100. 100 represents the original volume. < 0: Failure. + /// ≥ 0: Returns the volume of the specified audio effect, if the method call is successful. The value ranges between 0 and 100. 100 represents the original volume. + /// < 0: Failure. Future getVolumeOfEffect(int soundId); /// Sets the volume of a specified audio effect. @@ -3852,7 +4174,8 @@ abstract class RtcEngine { /// * [volume] The playback volume. The value range is [0, 100]. The default value is 100, which represents 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. + /// 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 setVolumeOfEffect({required int soundId, required int volume}); /// Pauses a specified audio effect file. @@ -3860,13 +4183,15 @@ abstract class RtcEngine { /// * [soundId] The audio effect ID. The ID of each audio effect file is unique. /// /// 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. + /// 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 pauseEffect(int soundId); /// Pauses all audio effects. /// /// 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. + /// 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 pauseAllEffects(); /// Resumes playing a specified audio effect. @@ -3874,13 +4199,15 @@ abstract class RtcEngine { /// * [soundId] The audio effect ID. The ID of each audio effect file is unique. /// /// 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. + /// 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 resumeEffect(int soundId); /// Resumes playing all audio effect files. /// /// 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. + /// 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 resumeAllEffects(); /// Stops playing a specified audio effect. @@ -3888,13 +4215,15 @@ abstract class RtcEngine { /// * [soundId] The ID of the audio effect. Each audio effect has a unique ID. /// /// 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. + /// 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 stopEffect(int soundId); /// Stops playing all audio effects. /// /// 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. + /// 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 stopAllEffects(); /// Releases a specified preloaded audio effect from the memory. @@ -3902,34 +4231,41 @@ abstract class RtcEngine { /// * [soundId] The ID of the audio effect. Each audio effect has a unique ID. /// /// 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. + /// 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 unloadEffect(int soundId); /// Releases a specified preloaded audio effect from the memory. /// /// 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. + /// 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 unloadAllEffects(); /// Retrieves the duration of the audio effect file. /// /// Call this method after joining a channel. /// - /// * [filePath] File path:Android: The file path, which needs to be accurate to the file name and suffix. Agora supports URL addresses, absolute paths, or file paths that start with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example: content://com.android.providers.media.documents/document/audio%3A14441Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: C:\music\audio.mp4.iOS or macOS: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. + /// * [filePath] File path: + /// Android: The file path, which needs to be accurate to the file name and suffix. Agora supports URL addresses, absolute paths, or file paths that start with /assets/. You might encounter permission issues if you use an absolute path to access a local file, so Agora recommends using a URI address instead. For example : content://com.android.providers.media.documents/document/audio%3A14441 + /// Windows: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example : C:\music\audio.mp4. + /// iOS or macOS: The absolute path or URL address (including the suffixes of the filename) of the audio effect file. For example: /var/mobile/Containers/Data/audio.mp4. /// /// Returns - /// The total duration (ms) of the specified audio effect file, if the method call succeeds. < 0: Failure. + /// The total duration (ms) of the specified audio effect file, if the method call succeeds. + /// < 0: Failure. Future getEffectDuration(String filePath); /// Sets the playback position of an audio effect file. /// - /// After a successful setting, the local audio effect file starts playing at the specified position. Call this method after playEffect . + /// After a successful setting, the local audio effect file starts playing at the specified position. Call this method after playEffect. /// /// * [soundId] The audio effect ID. The ID of each audio effect file is unique. /// * [pos] The playback position (ms) of the audio effect file. /// /// 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. + /// 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 setEffectPosition({required int soundId, required int pos}); /// Retrieves the playback position of the audio effect file. @@ -3939,94 +4275,138 @@ abstract class RtcEngine { /// * [soundId] The audio effect ID. The ID of each audio effect file is unique. /// /// Returns - /// The playback position (ms) of the specified audio effect file, if the method call succeeds. < 0: Failure. + /// The playback position (ms) of the specified audio effect file, if the method call succeeds. + /// < 0: Failure. Future getEffectCurrentPosition(int soundId); /// Enables or disables stereo panning for remote users. /// - /// Ensure that you call this method before joining a channel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition . + /// Ensure that you call this method before joining a channel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition. /// - /// * [enabled] Whether to enable stereo panning for remote users:true: Enable stereo panning.false: Disable stereo panning. + /// * [enabled] Whether to enable stereo panning for remote users: true : Enable stereo panning. false : Disable stereo panning. /// /// 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. + /// 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 enableSoundPositionIndication(bool enabled); /// Sets the 2D position (the position on the horizontal plane) of the remote user's voice. /// - /// This method sets the 2D position and volume of a remote user, so that the local user can easily hear and identify the remote user's position. When the local user calls this method to set the voice position of a remote user, the voice difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a sense of space. This method applies to massive multiplayer online games, such as Battle Royale games. For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel. For the best voice positioning, Agora recommends using a wired headset. Call this method after joining a channel. + /// This method sets the 2D position and volume of a remote user, so that the local user can easily hear and identify the remote user's position. When the local user calls this method to set the voice position of a remote user, the voice difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a sense of space. This method applies to massive multiplayer online games, such as Battle Royale games. + /// For this method to work, enable stereo panning for remote users by calling the enableSoundPositionIndication method before joining a channel. + /// For the best voice positioning, Agora recommends using a wired headset. + /// Call this method after joining a channel. /// /// * [uid] The user ID of the remote user. - /// * [pan] The voice position of the remote user. The value ranges from -1.0 to 1.0:0.0: (Default) The remote voice comes from the front.-1.0: The remote voice comes from the left.1.0: The remote voice comes from the right. + /// * [pan] The voice position of the remote user. The value ranges from -1.0 to 1.0: + /// 0.0: (Default) The remote voice comes from the front. + /// -1.0: The remote voice comes from the left. + /// 1.0: The remote voice comes from the right. /// * [gain] The volume of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original volume of the remote user). The smaller the value, the lower the 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. + /// 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 setRemoteVoicePosition( {required int uid, required double pan, required double gain}); /// Enables or disables the spatial audio effect. /// - /// After enabling the spatial audio effect, you can call setRemoteUserSpatialAudioParams to set the spatial audio effect parameters of the remote user. You can call this method either before or after joining a channel. This method relies on the spatial audio dynamic library libagora_spatial_audio_extension.dll . If the dynamic library is deleted, the function cannot be enabled normally. + /// After enabling the spatial audio effect, you can call setRemoteUserSpatialAudioParams to set the spatial audio effect parameters of the remote user. + /// You can call this method either before or after joining a channel. + /// This method relies on the spatial audio dynamic library libagora_spatial_audio_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. /// - /// * [enabled] Whether to enable the spatial audio effect:true: Enable the spatial audio effect.false: Disable the spatial audio effect. + /// * [enabled] Whether to enable the spatial audio effect: true : Enable the spatial audio effect. false : Disable the spatial audio effect. /// /// 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. + /// 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 enableSpatialAudio(bool enabled); /// Sets the spatial audio effect parameters of the remote user. /// - /// Call this method after enableSpatialAudio . After successfully setting the spatial audio effect parameters of the remote user, the local user can hear the remote user with a sense of space. + /// Call this method after enableSpatialAudio. After successfully setting the spatial audio effect parameters of the remote user, the local user can hear the remote user with a sense of space. /// /// * [uid] The user ID. This parameter must be the same as the user ID passed in when the user joined the channel. /// * [params] The spatial audio parameters. See SpatialAudioParams. /// /// 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. + /// 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 setRemoteUserSpatialAudioParams( {required int uid, required SpatialAudioParams params}); /// Sets a preset voice beautifier effect. /// - /// Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting a voice beautifier effect, all users in the channel can hear the effect. You can set different voice beautifier effects for different scenarios. For better voice effects, Agora recommends that you call setAudioProfile and set scenario to audioScenarioGameStreaming (3) and profile to audioProfileMusicHighQuality (4) or audioProfileMusicHighQualityStereo (5) before calling this method. You can call this method either before or after joining a channel. Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) or audioProfileIot (6) , or the method does not take effect. This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. After calling setVoiceBeautifierPreset , Agora does not recommend calling the following methods, otherwise the effect set by setVoiceBeautifierPreset will be overwritten: setAudioEffectPreset setAudioEffectParameters setLocalVoicePitch setLocalVoiceEqualization setLocalVoiceReverb setVoiceBeautifierParameters setVoiceConversionPreset This method relies on the voice beautifier dynamic library libagora_audio_beauty_extension.dll . If the dynamic library is deleted, the function cannot be enabled normally. + /// Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting a voice beautifier effect, all users in the channel can hear the effect. You can set different voice beautifier effects for different scenarios. For better voice effects, Agora recommends that you call setAudioProfile and set scenario to audioScenarioGameStreaming (3) and profile to audioProfileMusicHighQuality (4) or audioProfileMusicHighQualityStereo (5) before calling this method. + /// You can call this method either before or after joining a channel. + /// Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) or audioProfileIot (6), or the method does not take effect. + /// This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. + /// After calling setVoiceBeautifierPreset, Agora does not recommend calling the following methods, otherwise the effect set by setVoiceBeautifierPreset will be overwritten: setAudioEffectPreset setAudioEffectParameters setLocalVoicePitch setLocalVoiceEqualization setLocalVoiceReverb setVoiceBeautifierParameters setVoiceConversionPreset + /// This method relies on the voice beautifier dynamic library libagora_audio_beauty_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. /// /// * [preset] The preset voice beautifier effect options: VoiceBeautifierPreset. /// /// 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. + /// 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 setVoiceBeautifierPreset(VoiceBeautifierPreset preset); /// Sets an SDK preset audio effect. /// - /// Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect. To get better audio effect quality, Agora recommends setting the scenario parameter of setAudioProfile as audioScenarioGameStreaming (3) before calling this method. You can call this method either before or after joining a channel. Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) audioProfileIot or (6), or the method does not take effect. This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. If you call setAudioEffectPreset and set enumerators except for roomAcoustics3dVoice or pitchCorrection , do not call setAudioEffectParameters ; otherwise, setAudioEffectPreset is overridden. After calling setAudioEffectPreset , Agora does not recommend you to call the following methods, otherwise the effect set by setAudioEffectPreset will be overwritten: setVoiceBeautifierPreset setLocalVoicePitch setLocalVoiceEqualization setLocalVoiceReverb setVoiceBeautifierParameters setVoiceConversionPreset This method relies on the voice beautifier dynamic library libagora_audio_beauty_extension.dll . If the dynamic library is deleted, the function cannot be enabled normally. + /// Call this method to set an SDK preset audio effect for the local user who sends an audio stream. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect. To get better audio effect quality, Agora recommends setting the scenario parameter of setAudioProfile as audioScenarioGameStreaming (3) before calling this method. + /// You can call this method either before or after joining a channel. + /// Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) audioProfileIot or (6), or the method does not take effect. + /// This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. + /// If you call setAudioEffectPreset and set enumerators except for roomAcoustics3dVoice or pitchCorrection, do not call setAudioEffectParameters; otherwise, setAudioEffectPreset is overridden. + /// After calling setAudioEffectPreset, Agora does not recommend you to call the following methods, otherwise the effect set by setAudioEffectPreset will be overwritten: setVoiceBeautifierPreset setLocalVoicePitch setLocalVoiceEqualization setLocalVoiceReverb setVoiceBeautifierParameters setVoiceConversionPreset + /// This method relies on the voice beautifier dynamic library libagora_audio_beauty_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. /// /// * [preset] The options for SDK preset audio effects. See AudioEffectPreset. /// /// 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. + /// 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 setAudioEffectPreset(AudioEffectPreset preset); /// Sets a preset voice beautifier effect. /// - /// Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting an audio effect, all users in the channel can hear the effect. You can set different voice beautifier effects for different scenarios. To achieve better audio effect quality, Agora recommends that you call setAudioProfile and set the profile to audioProfileMusicHighQuality (4) or audioProfileMusicHighQualityStereo (5) and scenario to audioScenarioGameStreaming (3) before calling this method. You can call this method either before or after joining a channel. Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) or audioProfileIot (6) , or the method does not take effect. This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. After calling setVoiceConversionPreset , Agora does not recommend you to call the following methods, otherwise the effect set by setVoiceConversionPreset will be overwritten: setAudioEffectPreset setAudioEffectParameters setVoiceBeautifierPreset setVoiceBeautifierParameters setLocalVoicePitch setLocalVoiceFormant setLocalVoiceEqualization setLocalVoiceReverb This method relies on the voice beautifier dynamic library libagora_audio_beauty_extension.dll . If the dynamic library is deleted, the function cannot be enabled normally. + /// Call this method to set a preset voice beautifier effect for the local user who sends an audio stream. After setting an audio effect, all users in the channel can hear the effect. You can set different voice beautifier effects for different scenarios. To achieve better audio effect quality, Agora recommends that you call setAudioProfile and set the profile to audioProfileMusicHighQuality (4) or audioProfileMusicHighQualityStereo (5) and scenario to audioScenarioGameStreaming (3) before calling this method. + /// You can call this method either before or after joining a channel. + /// Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) or audioProfileIot (6), or the method does not take effect. + /// This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. + /// After calling setVoiceConversionPreset, Agora does not recommend you to call the following methods, otherwise the effect set by setVoiceConversionPreset will be overwritten: setAudioEffectPreset setAudioEffectParameters setVoiceBeautifierPreset setVoiceBeautifierParameters setLocalVoicePitch setLocalVoiceFormant setLocalVoiceEqualization setLocalVoiceReverb + /// This method relies on the voice beautifier dynamic library libagora_audio_beauty_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. /// /// * [preset] The options for the preset voice beautifier effects: VoiceConversionPreset. /// /// 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. + /// 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 setVoiceConversionPreset(VoiceConversionPreset preset); /// Sets parameters for SDK preset audio effects. /// - /// Call this method to set the following parameters for the local user who sends an audio stream: 3D voice effect: Sets the cycle period of the 3D voice effect. Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively. After setting the audio parameters, all users in the channel can hear the effect. You can call this method either before or after joining a channel. To get better audio effect quality, Agora recommends setting the scenario parameter of setAudioProfile as audioScenarioGameStreaming (3) before calling this method. Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) audioProfileIot or (6), or the method does not take effect. This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. After calling setAudioEffectParameters , Agora does not recommend you to call the following methods, otherwise the effect set by setAudioEffectParameters will be overwritten: setAudioEffectPreset setVoiceBeautifierPreset setLocalVoicePitch setLocalVoiceEqualization setLocalVoiceReverb setVoiceBeautifierParameters setVoiceConversionPreset + /// Call this method to set the following parameters for the local user who sends an audio stream: + /// 3D voice effect: Sets the cycle period of the 3D voice effect. + /// Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively. After setting the audio parameters, all users in the channel can hear the effect. + /// You can call this method either before or after joining a channel. + /// To get better audio effect quality, Agora recommends setting the scenario parameter of setAudioProfile as audioScenarioGameStreaming (3) before calling this method. + /// Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) audioProfileIot or (6), or the method does not take effect. + /// This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. + /// After calling setAudioEffectParameters, Agora does not recommend you to call the following methods, otherwise the effect set by setAudioEffectParameters will be overwritten: setAudioEffectPreset setVoiceBeautifierPreset setLocalVoicePitch setLocalVoiceEqualization setLocalVoiceReverb setVoiceBeautifierParameters setVoiceConversionPreset /// - /// * [preset] The options for SDK preset audio effects:roomAcoustics3dVoice, 3D voice effect:Call setAudioProfile and set the profile parameter in to audioProfileMusicStandardStereo(3) or audioProfileMusicHighQualityStereo(5) before setting this enumerator; otherwise, the enumerator setting does not take effect.If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect.pitchCorrection, Pitch correction effect: To achieve better audio effect quality, Agora recommends setting the profile parameter in setAudioProfile to audioProfileMusicHighQuality(4) or audioProfileMusicHighQualityStereo(5) before setting this enumerator. - /// * [param1] If you set preset to roomAcoustics3dVoice, param1 sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is seconds. The default value is 10, indicating that the voice moves around you every 10 seconds.If you set preset to pitchCorrection, param1 indicates the basic mode of the pitch correction effect:1: (Default) Natural major scale.2: Natural minor scale.3: Japanese pentatonic scale. - /// * [param2] If you set preset to roomAcoustics3dVoice , you need to set param2 to 0.If you set preset to pitchCorrection, param2 indicates the tonic pitch of the pitch correction effect:1: A2: A#3: B4: (Default) C5: C#6: D7: D#8: E9: F10: F#11: G12: G# + /// * [preset] The options for SDK preset audio effects: roomAcoustics3dVoice, 3D voice effect: + /// Call setAudioProfile and set the profile parameter in to audioProfileMusicStandardStereo (3) or audioProfileMusicHighQualityStereo (5) before setting this enumerator; otherwise, the enumerator setting does not take effect. + /// If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect. pitchCorrection, Pitch correction effect: To achieve better audio effect quality, Agora recommends setting the profile parameter in setAudioProfile to audioProfileMusicHighQuality (4) or audioProfileMusicHighQualityStereo (5) before setting this enumerator. + /// * [param1] If you set preset to roomAcoustics3dVoice, param1 sets the cycle period of the 3D voice effect. The value range is [1,60] and the unit is seconds. The default value is 10, indicating that the voice moves around you every 10 seconds. + /// If you set preset to pitchCorrection, param1 indicates the basic mode of the pitch correction effect: 1 : (Default) Natural major scale. 2 : Natural minor scale. 3 : Japanese pentatonic scale. + /// * [param2] If you set preset to roomAcoustics3dVoice , you need to set param2 to 0. + /// If you set preset to pitchCorrection, param2 indicates the tonic pitch of the pitch correction effect: 1 : A 2 : A# 3 : B 4 : (Default) C 5 : C# 6 : D 7 : D# 8 : E 9 : F 10 : F# 11 : G 12 : G# /// /// 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. + /// 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 setAudioEffectParameters( {required AudioEffectPreset preset, required int param1, @@ -4034,14 +4414,19 @@ abstract class RtcEngine { /// Sets parameters for the preset voice beautifier effects. /// - /// Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. After setting the audio parameters, all users in the channel can hear the effect. For better voice effects, Agora recommends that you call setAudioProfile and set scenario to audioScenarioGameStreaming (3) and profile to audioProfileMusicHighQuality (4) or audioProfileMusicHighQualityStereo (5) before calling this method. You can call this method either before or after joining a channel. Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) or audioProfileIot (6) , or the method does not take effect. This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. After calling setVoiceBeautifierParameters , Agora does not recommend calling the following methods, otherwise the effect set by setVoiceBeautifierParameters will be overwritten: setAudioEffectPreset setAudioEffectParameters setVoiceBeautifierPreset setLocalVoicePitch setLocalVoiceEqualization setLocalVoiceReverb setVoiceConversionPreset + /// Call this method to set a gender characteristic and a reverberation effect for the singing beautifier effect. This method sets parameters for the local user who sends an audio stream. After setting the audio parameters, all users in the channel can hear the effect. For better voice effects, Agora recommends that you call setAudioProfile and set scenario to audioScenarioGameStreaming (3) and profile to audioProfileMusicHighQuality (4) or audioProfileMusicHighQualityStereo (5) before calling this method. + /// You can call this method either before or after joining a channel. + /// Do not set the profile parameter in setAudioProfile to audioProfileSpeechStandard (1) or audioProfileIot (6), or the method does not take effect. + /// This method has the best effect on human voice processing, and Agora does not recommend calling this method to process audio data containing music. + /// After calling setVoiceBeautifierParameters, Agora does not recommend calling the following methods, otherwise the effect set by setVoiceBeautifierParameters will be overwritten: setAudioEffectPreset setAudioEffectParameters setVoiceBeautifierPreset setLocalVoicePitch setLocalVoiceEqualization setLocalVoiceReverb setVoiceConversionPreset /// - /// * [preset] The option for the preset audio effect:SINGING_BEAUTIFIER: The singing beautifier effect. - /// * [param1] The gender characteristics options for the singing voice:1: A male-sounding voice.2: A female-sounding voice. - /// * [param2] The reverberation effect options for the singing voice:1: The reverberation effect sounds like singing in a small room.2: The reverberation effect sounds like singing in a large room.3: The reverberation effect sounds like singing in a hall. + /// * [preset] The option for the preset audio effect: SINGING_BEAUTIFIER : The singing beautifier effect. + /// * [param1] The gender characteristics options for the singing voice: 1 : A male-sounding voice. 2 : A female-sounding voice. + /// * [param2] The reverberation effect options for the singing voice: 1 : The reverberation effect sounds like singing in a small room. 2 : The reverberation effect sounds like singing in a large room. 3 : The reverberation effect sounds like singing in a hall. /// /// 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. + /// 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 setVoiceBeautifierParameters( {required VoiceBeautifierPreset preset, required int param1, @@ -4060,17 +4445,19 @@ abstract class RtcEngine { /// * [pitch] The local voice pitch. The value range is [0.5,2.0]. The lower the value, the lower the pitch. The default value is 1.0 (no change to the pitch). /// /// 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. + /// 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 setLocalVoicePitch(double pitch); /// Set the formant ratio to change the timbre of human voice. /// - /// Formant ratio affects the timbre of voice. The smaller the value, the deeper the sound will be, and the larger, the sharper. You can call this method to set the formant ratio of local audio to change the timbre of human voice. After you set the formant ratio, all users in the channel can hear the changed voice. If you want to change the timbre and pitch of voice at the same time, Agora recommends using this method together with setLocalVoicePitch . You can call this method either before or after joining a channel. + /// Formant ratio affects the timbre of voice. The smaller the value, the deeper the sound will be, and the larger, the sharper. You can call this method to set the formant ratio of local audio to change the timbre of human voice. After you set the formant ratio, all users in the channel can hear the changed voice. If you want to change the timbre and pitch of voice at the same time, Agora recommends using this method together with setLocalVoicePitch. You can call this method either before or after joining a channel. /// - /// * [formantRatio] The formant ratio. The value range is [-1.0, 1.0]. The default value is 0.0, which means do not change the timbre of the voice.Agora recommends setting this value within the range of [-0.4, 0.6]. Otherwise, the voice may be seriously distorted. + /// * [formantRatio] The formant ratio. The value range is [-1.0, 1.0]. The default value is 0.0, which means do not change the timbre of the voice. Agora recommends setting this value within the range of [-0.4, 0.6]. Otherwise, the voice may be seriously distorted. /// /// 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. + /// 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 setLocalVoiceFormant(double formantRatio); /// Sets the local voice equalization effect. @@ -4081,20 +4468,22 @@ abstract class RtcEngine { /// * [bandGain] The gain of each band in dB. The value ranges between -15 and 15. The default value is 0. /// /// 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. + /// 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 setLocalVoiceEqualization( {required AudioEqualizationBandFrequency bandFrequency, required int bandGain}); /// Sets the local voice reverberation. /// - /// The SDK provides an easier-to-use method, setAudioEffectPreset , to directly implement preset reverb effects for such as pop, R&B, and KTV. You can call this method either before or after joining a channel. + /// The SDK provides an easier-to-use method, setAudioEffectPreset, to directly implement preset reverb effects for such as pop, R&B, and KTV. You can call this method either before or after joining a channel. /// /// * [reverbKey] The reverberation key. Agora provides five reverberation keys, see AudioReverbType. /// * [value] The value of the reverberation key. /// /// 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. + /// 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 setLocalVoiceReverb( {required AudioReverbType reverbKey, required int value}); @@ -4105,7 +4494,9 @@ abstract class RtcEngine { /// * [preset] The preset headphone equalization effect. See HeadphoneEqualizerPreset. /// /// 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: A general error occurs (no specified reason). + /// 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: A general error occurs (no specified reason). Future setHeadphoneEQPreset(HeadphoneEqualizerPreset preset); /// Sets the low- and high-frequency parameters of the headphone equalizer. @@ -4116,7 +4507,9 @@ abstract class RtcEngine { /// * [highGain] The high-frequency parameters of the headphone equalizer. The value range is [-10,10]. The larger the value, the sharper the sound. /// /// 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: A general error occurs (no specified reason). + /// 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: A general error occurs (no specified reason). Future setHeadphoneEQParameters( {required int lowGain, required int highGain}); @@ -4127,17 +4520,19 @@ abstract class RtcEngine { /// * [filePath] The complete path of the log files. These log files are encoded in UTF-8. /// /// 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. + /// 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 setLogFile(String filePath); /// Sets the log output level of the SDK. /// - /// Deprecated: Use logConfig in initialize instead. This method sets the output log level of the SDK. You can use one or a combination of the log filter levels. The log level follows the sequence of logFilterOff , logFilterCritical , logFilterError , logFilterWarn , logFilterInfo , and logFilterDebug . Choose a level to see the logs preceding that level. If, for example, you set the log level to logFilterWarn , you see the logs within levels logFilterCritical , logFilterError and logFilterWarn . + /// Deprecated: Use logConfig in initialize instead. This method sets the output log level of the SDK. You can use one or a combination of the log filter levels. The log level follows the sequence of logFilterOff, logFilterCritical, logFilterError, logFilterWarn, logFilterInfo, and logFilterDebug. Choose a level to see the logs preceding that level. If, for example, you set the log level to logFilterWarn, you see the logs within levels logFilterCritical, logFilterError and logFilterWarn. /// /// * [filter] The output log level of the SDK. See LogFilterType. /// /// 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. + /// 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 setLogFilter(LogFilterType filter); /// Sets the output log level of the SDK. @@ -4147,31 +4542,47 @@ abstract class RtcEngine { /// * [level] The log level: LogLevel. /// /// 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. + /// 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 setLogLevel(LogLevel level); /// Sets the log file size. /// - /// Deprecated: Use the logConfig parameter in initialize instead. By default, the SDK generates five SDK log files and five API call log files with the following rules: The SDK log files are: agorasdk.log , agorasdk.1.log , agorasdk.2.log , agorasdk.3.log , and agorasdk.4.log . The API call log files are: agoraapi.log , agoraapi.1.log , agoraapi.2.log , agoraapi.3.log , and agoraapi.4.log . The default size for each SDK log file is 1,024 KB; the default size for each API call log file is 2,048 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in agorasdk.log or agoraapi.log . When agorasdk.log is full, the SDK processes the log files in the following order: Delete the agorasdk.4.log file (if any). Rename agorasdk.3.log to agorasdk.4.log . Rename agorasdk.2.log to agorasdk.3.log . Rename agorasdk.1.log to agorasdk.2.log . Create a new agorasdk.log file. The overwrite rules for the agoraapi.log file are the same as for agorasdk.log . This method is used to set the size of the agorasdk.log file only and does not effect the agoraapi.log file . + /// Deprecated: Use the logConfig parameter in initialize instead. By default, the SDK generates five SDK log files and five API call log files with the following rules: + /// The SDK log files are: agorasdk.log, agorasdk.1.log, agorasdk.2.log, agorasdk.3.log, and agorasdk.4.log. + /// The API call log files are: agoraapi.log, agoraapi.1.log, agoraapi.2.log, agoraapi.3.log, and agoraapi.4.log. + /// The default size for each SDK log file is 1,024 KB; the default size for each API call log file is 2,048 KB. These log files are encoded in UTF-8. + /// The SDK writes the latest logs in agorasdk.log or agoraapi.log. + /// When agorasdk.log is full, the SDK processes the log files in the following order: + /// Delete the agorasdk.4.log file (if any). + /// Rename agorasdk.3.log to agorasdk.4.log. + /// Rename agorasdk.2.log to agorasdk.3.log. + /// Rename agorasdk.1.log to agorasdk.2.log. + /// Create a new agorasdk.log file. + /// The overwrite rules for the agoraapi.log file are the same as for agorasdk.log. This method is used to set the size of the agorasdk.log file only and does not effect the agoraapi.log file. /// - /// * [fileSizeInKBytes] The size (KB) of an agorasdk.log file. The value range is [128,20480]. The default value is 1,024 KB. If you set fileSizeInKByte smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you set fileSizeInKByte greater than 20,480 KB, the SDK automatically adjusts it to 20,480 KB. + /// * [fileSizeInKBytes] The size (KB) of an agorasdk.log file. The value range is [128,20480]. The default value is 2,048 KB. If you set fileSizeInKByte smaller than 128 KB, the SDK automatically adjusts it to 128 KB; if you set fileSizeInKByte greater than 20,480 KB, the SDK automatically adjusts it to 20,480 KB. /// /// 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. + /// 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 setLogFileSize(int fileSizeInKBytes); /// @nodoc - Future uploadLogFile(String requestId); + Future uploadLogFile(); /// Updates the display mode of the local video view. /// - /// After initializing the local video view, you can call this method to update its rendering and mirror modes. It affects only the video view that the local user sees, not the published local video stream. Ensure that you have called the setupLocalVideo method to initialize the local video view before calling this method. During a call, you can call this method as many times as necessary to update the display mode of the local video view. + /// After initializing the local video view, you can call this method to update its rendering and mirror modes. It affects only the video view that the local user sees, not the published local video stream. + /// Ensure that you have called the setupLocalVideo method to initialize the local video view before calling this method. + /// During a call, you can call this method as many times as necessary to update the display mode of the local video view. /// /// * [renderMode] The local video display mode. See RenderModeType. - /// * [mirrorMode] The mirror mode of the local video view. See VideoMirrorModeType.If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default. + /// * [mirrorMode] The mirror mode of the local video view. See VideoMirrorModeType. If you use a front camera, the SDK enables the mirror mode by default; if you use a rear camera, the SDK disables the mirror mode by default. /// /// 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. + /// 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 setLocalRenderMode( {required RenderModeType renderMode, VideoMirrorModeType mirrorMode = @@ -4179,14 +4590,17 @@ abstract class RtcEngine { /// Updates the display mode of the video view of a remote user. /// - /// After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees. Call this method after initializing the remote view by calling the setupRemoteVideo method. During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user. + /// After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees. + /// Call this method after initializing the remote view by calling the setupRemoteVideo method. + /// During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user. /// /// * [uid] The user ID of the remote user. /// * [renderMode] The rendering mode of the remote user view. /// * [mirrorMode] The mirror mode of the remote user view. See VideoMirrorModeType. /// /// 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. + /// 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 setRemoteRenderMode( {required int uid, required RenderModeType renderMode, @@ -4199,30 +4613,43 @@ abstract class RtcEngine { /// * [mirrorMode] The local video mirror mode. See VideoMirrorModeType. /// /// 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. + /// 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 setLocalVideoMirrorMode(VideoMirrorModeType mirrorMode); /// Enables or disables the dual-stream mode on the sender and sets the low-quality video stream. /// - /// Deprecated: This method is deprecated as of v4.2.0. Use setDualStreamMode instead. 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. 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. 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. If you need to enable dual video streams in a multi-channel scenario, you can call the enableDualStreamModeEx method. You can call this method either before or after joining a channel. + /// Deprecated: This method is deprecated as of v4.2.0. Use setDualStreamMode instead. 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. 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. + /// 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. + /// If you need to enable dual video streams in a multi-channel scenario, you can call the enableDualStreamModeEx method. + /// You can call this method either before or after joining a channel. /// - /// * [enabled] Whether to enable dual-stream mode:true: Enable dual-stream mode.false: (Default) Disable dual-stream mode. + /// * [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. /// /// 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. + /// 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 enableDualStreamMode( {required bool enabled, SimulcastStreamConfig? streamConfig}); /// Sets dual-stream mode configuration on the sender, and sets the low-quality video stream. /// - /// The SDK enables the low-quality video stream auto mode on the sender by default, which is equivalent to calling this method and setting the mode to autoSimulcastStream . 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). + /// 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: + /// 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. /// /// * [mode] The mode in which the video stream is sent. See SimulcastStreamMode. - /// * [streamConfig] The configuration of the low-quality video stream. See SimulcastStreamConfig.When setting mode to disableSimulcastStream, setting streamConfig will not take effect. + /// * [streamConfig] The configuration of the low-quality video stream. See SimulcastStreamConfig. When setting mode to disableSimulcastStream, setting streamConfig will not take effect. /// /// 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. + /// 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 setDualStreamMode( {required SimulcastStreamMode mode, SimulcastStreamConfig? streamConfig}); @@ -4232,15 +4659,20 @@ abstract class RtcEngine { /// Sets the format of the captured raw audio data. /// - /// Sets the audio format for the onRecordAudioFrame callback. Ensure that you call this method before joining a channel. The SDK calculates the sampling interval based on the samplesPerCall , sampleRate and channel parameters set in this method. Sample interval (sec) = samplePerCall /( sampleRate × channel ) . Ensure that the sample interval ≥ 0.01 (s). + /// Sets the audio format for the onRecordAudioFrame callback. + /// Ensure that you call this method before joining a channel. + /// The SDK calculates the sampling interval based on the samplesPerCall, sampleRate and channel parameters set in this method. Sample interval (sec) = samplePerCall /(sampleRate × channel). Ensure that the sample interval ≥ 0.01 (s). /// /// * [sampleRate] The sample rate returned in the onRecordAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz. - /// * [channel] The number of channels returned in the onRecordAudioFrame callback:1: Mono.2: Stereo. + /// * [channel] The number of channels returned in the onRecordAudioFrame callback: + /// 1: Mono. + /// 2: Stereo. /// * [mode] The use mode of the audio frame. See RawAudioFrameOpModeType. /// * [samplesPerCall] The number of data samples returned in the onRecordAudioFrame callback, such as 1024 for the Media Push. /// /// 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. + /// 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 setRecordingAudioFrameParameters( {required int sampleRate, required int channel, @@ -4249,15 +4681,20 @@ abstract class RtcEngine { /// Sets the audio data format for playback. /// - /// Sets the data format for the onPlaybackAudioFrame callback. Ensure that you call this method before joining a channel. The SDK calculates the sampling interval based on the samplesPerCall , sampleRate and channel parameters set in this method. Sample interval (sec) = samplePerCall /( sampleRate × channel ) . Ensure that the sample interval ≥ 0.01 (s). The SDK triggers the callback according to the sampling interval. onPlaybackAudioFrame + /// Sets the data format for the onPlaybackAudioFrame callback. + /// Ensure that you call this method before joining a channel. + /// The SDK calculates the sampling interval based on the samplesPerCall, sampleRate and channel parameters set in this method. Sample interval (sec) = samplePerCall /(sampleRate × channel). Ensure that the sample interval ≥ 0.01 (s). The SDK triggers the onPlaybackAudioFrame callback according to the sampling interval. /// /// * [sampleRate] The sample rate returned in the onPlaybackAudioFrame callback, which can be set as 8000, 16000, 32000, 44100, or 48000 Hz. - /// * [channel] The number of channels returned in the onPlaybackAudioFrame callback:1: Mono.2: Stereo. + /// * [channel] The number of channels returned in the onPlaybackAudioFrame callback: + /// 1: Mono. + /// 2: Stereo. /// * [mode] The use mode of the audio frame. See RawAudioFrameOpModeType. /// * [samplesPerCall] The number of data samples returned in the onPlaybackAudioFrame callback, such as 1024 for the Media Push. /// /// 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. + /// 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 setPlaybackAudioFrameParameters( {required int sampleRate, required int channel, @@ -4271,7 +4708,8 @@ abstract class RtcEngine { /// * [samplesPerCall] Sets the number of samples. In Media Push scenarios, set it as 1024. /// /// 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. + /// 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 setMixedAudioFrameParameters( {required int sampleRate, required int channel, @@ -4279,15 +4717,20 @@ abstract class RtcEngine { /// Sets the format of the in-ear monitoring raw audio data. /// - /// This method is used to set the in-ear monitoring audio data format reported by the onEarMonitoringAudioFrame callback. Before calling this method, you need to call enableInEarMonitoring , and set includeAudioFilters to earMonitoringFilterBuiltInAudioFilters or earMonitoringFilterNoiseSuppression . The SDK calculates the sampling interval based on the samplesPerCall , sampleRate and channel parameters set in this method. Sample interval (sec) = samplePerCall /( sampleRate × channel ) . Ensure that the sample interval ≥ 0.01 (s). The SDK triggers the onEarMonitoringAudioFrame callback according to the sampling interval. + /// This method is used to set the in-ear monitoring audio data format reported by the onEarMonitoringAudioFrame callback. + /// Before calling this method, you need to call enableInEarMonitoring, and set includeAudioFilters to earMonitoringFilterBuiltInAudioFilters or earMonitoringFilterNoiseSuppression. + /// The SDK calculates the sampling interval based on the samplesPerCall, sampleRate and channel parameters set in this method. Sample interval (sec) = samplePerCall /(sampleRate × channel). Ensure that the sample interval ≥ 0.01 (s). The SDK triggers the onEarMonitoringAudioFrame callback according to the sampling interval. /// /// * [sampleRate] The sample rate of the audio data reported in the onEarMonitoringAudioFrame callback, which can be set as 8,000, 16,000, 32,000, 44,100, or 48,000 Hz. - /// * [channel] The number of audio channels reported in the onEarMonitoringAudioFrame callback.1: Mono.2: Stereo. + /// * [channel] The number of audio channels reported in the onEarMonitoringAudioFrame callback. + /// 1: Mono. + /// 2: Stereo. /// * [mode] The use mode of the audio frame. See RawAudioFrameOpModeType. /// * [samplesPerCall] The number of data samples reported in the onEarMonitoringAudioFrame callback, such as 1,024 for the Media Push. /// /// 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. + /// 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 setEarMonitoringAudioFrameParameters( {required int sampleRate, required int channel, @@ -4297,10 +4740,11 @@ abstract class RtcEngine { /// Sets the audio data format reported by onPlaybackAudioFrameBeforeMixing. /// /// * [sampleRate] The sample rate (Hz) of the audio data, which can be set as 8000, 16000, 32000, 44100, or 48000. - /// * [channel] The number of channels of the external audio source, which can be set as 1(Mono) or 2(Stereo). + /// * [channel] The number of channels of the external audio source, which can be set as 1 (Mono) or 2 (Stereo). /// /// 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. + /// 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 setPlaybackAudioFrameBeforeMixingParameters( {required int sampleRate, required int channel}); @@ -4311,15 +4755,18 @@ abstract class RtcEngine { /// * [intervalInMS] The interval (in milliseconds) at which the SDK triggers the onLocalAudioSpectrum and onRemoteAudioSpectrum callbacks. The default value is 100. Do not set this parameter to a value less than 10, otherwise calling this method would fail. /// /// 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. -2: Invalid parameters. + /// 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. + /// -2: Invalid parameters. Future enableAudioSpectrumMonitor({int intervalInMS = 100}); /// Disables audio spectrum monitoring. /// - /// After calling enableAudioSpectrumMonitor , if you want to disable audio spectrum monitoring, you can call this method. You can call this method either before or after joining a channel. + /// After calling enableAudioSpectrumMonitor, if you want to disable audio spectrum monitoring, you can call this method. You can call this method either before or after joining a channel. /// /// 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. + /// 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 disableAudioSpectrumMonitor(); /// Register an audio spectrum observer. @@ -4334,49 +4781,63 @@ abstract class RtcEngine { /// Unregisters the audio spectrum observer. /// - /// After calling registerAudioSpectrumObserver , if you want to disable audio spectrum monitoring, you can call this method. You can call this method either before or after joining a channel. + /// After calling registerAudioSpectrumObserver, if you want to disable audio spectrum monitoring, you can call this method. You can call this method either before or after joining a channel. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void unregisterAudioSpectrumObserver(AudioSpectrumObserver observer); /// Adjusts the capturing signal volume. /// /// You can call this method either before or after joining a channel. /// - /// * [volume] The volume of the user. The value range is [0,400].0: Mute.If you only need to mute the audio signal, Agora recommends that you use muteRecordingSignal instead.100: (Default) The original volume.400: Four times the original volume (amplifying the audio signals by four times). + /// * [volume] The volume of the user. The value range is [0,400]. + /// 0: Mute. If you only need to mute the audio signal, Agora recommends that you use muteRecordingSignal instead. + /// 100: (Default) The original volume. + /// 400: Four times the original volume (amplifying the audio signals by four times). /// /// 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. + /// 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 adjustRecordingSignalVolume(int volume); /// Whether to mute the recording signal. /// - /// * [mute] true: The media file is muted.false: (Default) Do not mute the recording signal.If you have already called adjustRecordingSignalVolume to adjust the volume, then when you call this method and set it to true, the SDK will record the current volume and mute it. To restore the previous volume, call this method again and set it to false. + /// * [mute] true : The media file is muted. false : (Default) Do not mute the recording signal. If you have already called adjustRecordingSignalVolume to adjust the volume, then when you call this method and set it to true, the SDK will record the current volume and mute it. To restore the previous volume, call this method again and set it to false. /// /// 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. + /// 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 muteRecordingSignal(bool mute); /// Adjusts the playback signal volume of all remote users. /// - /// This method adjusts the playback volume that is the mixed volume of all remote users. You can call this method either before or after joining a channel. + /// This method adjusts the playback volume that is the mixed volume of all remote users. + /// You can call this method either before or after joining a channel. /// - /// * [volume] The volume of the user. The value range is [0,400].0: Mute.If you only need to mute the audio signal, Agora recommends that you use muteRecordingSignal instead.100: (Default) The original volume.400: Four times the original volume (amplifying the audio signals by four times). + /// * [volume] The volume of the user. The value range is [0,400]. + /// 0: Mute. If you only need to mute the audio signal, Agora recommends that you use muteRecordingSignal instead. + /// 100: (Default) The original volume. + /// 400: Four times the original volume (amplifying the audio signals by four times). /// /// 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. + /// 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 adjustPlaybackSignalVolume(int volume); /// Adjusts the playback signal volume of a specified remote user. /// - /// You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. Call this method after joining a channel. The playback volume here refers to the mixed volume of a specified remote user. + /// You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. + /// Call this method after joining a channel. + /// The playback volume here refers to the mixed volume of a specified remote user. /// /// * [uid] The user ID of the remote user. /// * [volume] Audio mixing volume. The value ranges between 0 and 100. The default value is 100, which 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. + /// 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 adjustUserPlaybackSignalVolume( {required int uid, required int volume}); @@ -4394,13 +4855,18 @@ abstract class RtcEngine { /// Enables loopback audio capturing. /// - /// If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. This method applies to the macOS and Windows only. macOS does not support loopback audio capture of the default sound card. If you need to use this function, use a virtual sound card and pass its name to the deviceName parameter. Agora recommends using AgoraALD as the virtual sound card for audio capturing. You can call this method either before or after joining a channel. + /// If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. + /// This method applies to the macOS and Windows only. + /// macOS does not support loopback audio capture of the default sound card. If you need to use this function, use a virtual sound card and pass its name to the deviceName parameter. Agora recommends using AgoraALD as the virtual sound card for audio capturing. + /// You can call this method either before or after joining a channel. /// - /// * [enabled] Whether to enable loopback audio capturing.true: Enable loopback audio capturing.false: (Default) Disable loopback audio capturing. - /// * [deviceName] macOS: The device name of the virtual sound card. The default value is set to NULL, which means using AgoraALD for loopback audio capturing.Windows: The device name of the sound card. The default is set to NULL, which means the SDK uses the sound card of your device for loopback audio capturing. + /// * [enabled] Whether to enable loopback audio capturing. true : Enable loopback audio capturing. false : (Default) Disable loopback audio capturing. + /// * [deviceName] macOS: The device name of the virtual sound card. The default value is set to NULL, which means using AgoraALD for loopback audio capturing. + /// Windows: The device name of the sound card. The default is set to NULL, which means the SDK uses the sound card of your device for loopback audio capturing. /// /// 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. + /// 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 enableLoopbackRecording( {required bool enabled, String? deviceName}); @@ -4411,7 +4877,8 @@ abstract class RtcEngine { /// * [volume] Audio mixing volume. The value ranges between 0 and 100. The default value is 100, which 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. + /// 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 adjustLoopbackSignalVolume(int volume); /// @nodoc @@ -4419,25 +4886,32 @@ abstract class RtcEngine { /// Enables in-ear monitoring. /// - /// This method enables or disables in-ear monitoring. Users must use earphones (wired or Bluetooth) to hear the in-ear monitoring effect. You can call this method either before or after joining a channel. + /// This method enables or disables in-ear monitoring. + /// Users must use earphones (wired or Bluetooth) to hear the in-ear monitoring effect. + /// You can call this method either before or after joining a channel. /// - /// * [enabled] Enables or disables in-ear monitoring.true: Enables in-ear monitoring.false: (Default) Disables in-ear monitoring. + /// * [enabled] Enables or disables in-ear monitoring. true : Enables in-ear monitoring. false : (Default) Disables in-ear monitoring. /// * [includeAudioFilters] The audio filter of in-ear monitoring: See EarMonitoringFilterType. /// /// 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. - 8: Make sure the current audio routing is Bluetooth or headset. + /// 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. + /// - 8: Make sure the current audio routing is Bluetooth or headset. Future enableInEarMonitoring( {required bool enabled, required EarMonitoringFilterType includeAudioFilters}); /// Sets the volume of the in-ear monitor. /// - /// This method applies to Android and iOS only. Users must use wired earphones to hear their own voices. You can call this method either before or after joining a channel. + /// This method applies to Android and iOS only. + /// Users must use wired earphones to hear their own voices. + /// You can call this method either before or after joining a channel. /// /// * [volume] The volume of the in-ear monitor. The value ranges between 0 and 100. The default value is 100. /// /// 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. + /// 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 setInEarMonitoringVolume(int volume); /// Adds an extension to the SDK. @@ -4445,23 +4919,25 @@ abstract class RtcEngine { /// (For Windows and Android only) /// /// * [path] The extension library path and name. For example: /library/libagora_segmentation_extension.dll. - /// * [unloadAfterUse] Whether to uninstall the current extension when you no longer using it:true: Uninstall the extension when the RtcEngine is destroyed.false: (Rcommended) Do not uninstall the extension until the process terminates. + /// * [unloadAfterUse] Whether to uninstall the current extension when you no longer using it: true : Uninstall the extension when the RtcEngine is destroyed. false : (Rcommended) Do not uninstall the extension until the process terminates. /// /// 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. + /// 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 loadExtensionProvider( {required String path, bool unloadAfterUse = false}); /// Sets the properties of the extension provider. /// - /// You can call this method to set the attributes of the extension provider and initialize the relevant parameters according to the type of the provider. Call this method after enableExtension , and before enabling the audio ( enableAudio / enableLocalAudio ) or the video ( enableVideo / enableLocalVideo ). + /// You can call this method to set the attributes of the extension provider and initialize the relevant parameters according to the type of the provider. Call this method after enableExtension, and before enabling the audio (enableAudio / enableLocalAudio) or the video (enableVideo / enableLocalVideo). /// /// * [provider] The name of the extension provider. /// * [key] The key of the extension. /// * [value] The value of the extension key. /// /// 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. + /// 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 setExtensionProviderProperty( {required String provider, required String key, required String value}); @@ -4471,10 +4947,13 @@ abstract class RtcEngine { /// /// * [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] 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. + /// 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 registerExtension( {required String provider, required String extension, @@ -4482,15 +4961,21 @@ abstract class RtcEngine { /// Enables or disables extensions. /// - /// To call this method, call it immediately after initializing the RtcEngine object. If you want to enable multiple extensions, you need to call this method multiple times. The data processing order of different extensions in the SDK is determined by the order in which the extensions are enabled. That is, the extension that is enabled first will process the data first. + /// To call this method, call it immediately after initializing the RtcEngine object. + /// If you want to enable multiple extensions, you need to call this method multiple times. + /// The data processing order of different extensions in the SDK is determined by the order in which the extensions are enabled. That is, the extension that is enabled first will process the data first. /// /// * [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. + /// * [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. /// /// 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. -3: The extension library is not loaded. Agora recommends that you check the storage location or the name of the dynamic library. + /// 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. + /// -3: The extension library is not loaded. Agora recommends that you check the storage location or the name of the dynamic library. Future enableExtension( {required String provider, required String extension, @@ -4508,7 +4993,8 @@ abstract class RtcEngine { /// * [type] The type of the video source, 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. < 0: Failure. + /// 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 setExtensionProperty( {required String provider, required String extension, @@ -4525,7 +5011,8 @@ abstract class RtcEngine { /// * [type] Source type of the extension. See MediaSourceType. /// /// Returns - /// The extension information, if the method call succeeds. An empty string, if the method call fails. + /// The extension information, if the method call succeeds. + /// An empty string, if the method call fails. Future getExtensionProperty( {required String provider, required String extension, @@ -4535,21 +5022,27 @@ abstract class RtcEngine { /// Sets the camera capture configuration. /// - /// This method is for Android and iOS only. This method must be called after the camera is turned on, such as calling after startPreview and enableVideo . + /// This method is for Android and iOS only. + /// This method must be called after the camera is turned on, such as calling after startPreview and enableVideo. /// /// * [config] The camera capture configuration. See CameraCapturerConfiguration. /// /// 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. + /// 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 setCameraCapturerConfiguration( CameraCapturerConfiguration config); /// Creates a customized video track. /// - /// When you need to publish multiple custom captured videos in the channel, you can refer to the following steps: Call this method to create a video track and get the video track ID. In each channel's ChannelMediaOptions , set the customVideoTrackId parameter to the ID of the video track you want to publish, and set publishCustomVideoTrack to true . If you call pushVideoFrame , and specify customVideoTrackId as the videoTrackId set in step 2, you can publish the corresponding custom video source in multiple channels. + /// When you need to publish multiple custom captured videos in the channel, you can refer to the following steps: + /// Call this method to create a video track and get the video track ID. + /// In each channel's ChannelMediaOptions, set the customVideoTrackId parameter to the ID of the video track you want to publish, and set publishCustomVideoTrack to true. + /// If you call pushVideoFrame, and specify customVideoTrackId as the videoTrackId set in step 2, you can publish the corresponding custom video source in multiple channels. /// /// Returns - /// If the method call is successful, the video track ID is returned as the unique identifier of the video track. If the method call fails, a negative value is returned. + /// If the method call is successful, the video track ID is returned as the unique identifier of the video track. + /// If the method call fails, a negative value is returned. Future createCustomVideoTrack(); /// @nodoc @@ -4560,7 +5053,8 @@ abstract class RtcEngine { /// * [videoTrackId] The video track ID returned by calling the createCustomVideoTrack method. /// /// 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. + /// 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 destroyCustomVideoTrack(int videoTrackId); /// @nodoc @@ -4568,15 +5062,18 @@ abstract class RtcEngine { /// Switches between front and rear cameras. /// - /// This method needs to be called after the camera is started (for example, by calling startPreview or joinChannel ). This method is for Android and iOS only. + /// This method is for Android and iOS only. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). /// /// 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. + /// 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 switchCamera(); /// Checks whether the device supports camera zoom. /// - /// Call this method after enabling the local camera, for example, by calling joinChannel , enableVideo , or enableLocalVideo , depending on which method you use to turn on your local camera. This method is for Android and iOS only. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// This method is for Android and iOS only. /// /// Returns /// true : The device supports camera zoom. false : The device does not support camera zoom. @@ -4584,7 +5081,8 @@ abstract class RtcEngine { /// Checks whether the device camera supports face detection. /// - /// Call this method after enabling the local camera, for example, by calling joinChannel , enableVideo , or enableLocalVideo , depending on which method you use to turn on your local camera. This method is for Android and iOS only. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// This method is for Android and iOS only. /// /// Returns /// true : The device camera supports face detection. false : The device camera does not support face detection. @@ -4592,7 +5090,10 @@ abstract class RtcEngine { /// Checks whether the device supports camera flash. /// - /// Call this method after enabling the local camera, for example, by calling joinChannel , enableVideo , or enableLocalVideo , depending on which method you use to turn on your local camera. This method is for Android and iOS only. The app enables the front camera by default. If your front camera does not support enabling the flash, this method returns false . If you want to check whether the rear camera supports the flash function, call switchCamera before this method. On iPads with system version 15, even if isCameraTorchSupported returns true , you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// This method is for Android and iOS only. + /// The app enables the front camera by default. If your front camera does not support enabling the flash, this method returns false. If you want to check whether the rear camera supports the flash function, call switchCamera before this method. + /// On iPads with system version 15, even if isCameraTorchSupported returns true, you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues. /// /// Returns /// true : The device supports camera flash. false : The device does not support camera flash. @@ -4600,7 +5101,8 @@ abstract class RtcEngine { /// Check whether the device supports the manual focus function. /// - /// Call this method after enabling the local camera, for example, by calling joinChannel , enableVideo , or enableLocalVideo , depending on which method you use to turn on your local camera. This method is for Android and iOS only. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// This method is for Android and iOS only. /// /// Returns /// true : The device supports the manual focus function. false : The device does not support the manual focus function. @@ -4608,7 +5110,8 @@ abstract class RtcEngine { /// Checks whether the device supports the face auto-focus function. /// - /// This method is for Android and iOS only. Call this method after enabling the local camera, for example, by calling joinChannel , enableVideo , or enableLocalVideo , depending on which method you use to turn on your local camera. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// This method is for Android and iOS only. /// /// Returns /// true : The device supports the face auto-focus function. false : The device does not support the face auto-focus function. @@ -4616,27 +5119,34 @@ abstract class RtcEngine { /// Sets the camera zoom ratio. /// - /// This method is for Android and iOS only. This method must be called after the camera is turned on, such as calling after startPreview and enableVideo . + /// 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 is for Android and iOS only. /// /// * [factor] The camera zoom ratio. The value ranges between 1.0 and the maximum zoom supported by the device. You can get the maximum zoom ratio supported by the device by calling the getCameraMaxZoomFactor method. /// /// 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: if the method if failed. + /// 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: if the method if failed. Future setCameraZoomFactor(double factor); /// Enables or disables face detection for the local user. /// - /// You can call this method either before or after joining a channel. This method is for Android and iOS only. Once face detection is enabled, the SDK triggers the onFacePositionChanged callback to report the face information of the local user, which includes the following: The width and height of the local video. The position of the human face in the local view. The distance between the human face and the screen. This method needs to be called after the camera is started (for example, by calling enableVideo ). + /// You can call this method either before or after joining a channel. This method is for Android and iOS only. Once face detection is enabled, the SDK triggers the onFacePositionChanged callback to report the face information of the local user, which includes the following: + /// The width and height of the local video. + /// The position of the human face in the local view. + /// The distance between the human face and the screen. This method needs to be called after the camera is started (for example, by calling startPreview or enableVideo ). /// - /// * [enabled] Whether to enable face detection for the local user:true: Enable face detection.false: (Default) Disable face detection. + /// * [enabled] Whether to enable face detection for the local user: true : Enable face detection. false : (Default) Disable face detection. /// /// 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. + /// 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 enableFaceDetection(bool enabled); /// Gets the maximum zoom ratio supported by the camera. /// - /// This method is for Android and iOS only. Call this method after enabling the local camera, for example, by calling joinChannel , enableVideo , or enableLocalVideo , depending on which method you use to turn on your local camera. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// This method is for Android and iOS only. /// /// Returns /// The maximum zoom factor. @@ -4644,39 +5154,48 @@ abstract class RtcEngine { /// Sets the camera manual focus position. /// - /// This method must be called after the camera is turned on, such as calling after startPreview and enableVideo . After a successful method call, the SDK triggers the onCameraFocusAreaChanged callback. This method is for Android and iOS 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). + /// This method is for Android and iOS only. + /// After a successful method call, the SDK triggers the onCameraFocusAreaChanged callback. /// /// * [positionX] The horizontal coordinate of the touchpoint in the view. /// * [positionY] The vertical coordinate of the touchpoint in the view. /// /// 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. + /// 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 setCameraFocusPositionInPreview( {required double positionX, required double positionY}); /// Enables the camera flash. /// - /// This method is for Android and iOS only. This method must be called after the camera is turned on, such as calling after startPreview and enableVideo . + /// 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 is for Android and iOS only. /// - /// * [isOn] Whether to turn on the camera flash:true: Turn on the flash.false: (Default) Turn off the flash. + /// * [isOn] Whether to turn on the camera flash: true : Turn on the flash. false : (Default) Turn off the flash. /// /// 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. + /// 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 setCameraTorchOn(bool isOn); /// Enables the camera auto-face focus function. /// - /// By default, the SDK disables face autofocus on Android and enables face autofocus on iOS. To set face autofocus, call this method. This method is for Android and iOS only. This method must be called after the camera is turned on, such as calling after startPreview and enableVideo . + /// By default, the SDK disables face autofocus on Android and enables face autofocus on iOS. To set face autofocus, call this method. + /// 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 is for Android and iOS only. /// - /// * [enabled] Whether to enable face autofocus:true: Enable the camera auto-face focus function.false: Disable face autofocus. + /// * [enabled] Whether to enable face autofocus: true : Enable the camera auto-face focus function. false : Disable face autofocus. /// /// 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. + /// 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 setCameraAutoFocusFaceModeEnabled(bool enabled); /// Checks whether the device supports manual exposure. /// - /// Call this method after enabling the local camera, for example, by calling joinChannel , enableVideo , or enableLocalVideo , depending on which method you use to turn on your local camera. This method is for Android and iOS only. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// This method is for Android and iOS only. /// /// Returns /// true : The device supports manual exposure. false : The device does not support manual exposure. @@ -4684,19 +5203,49 @@ abstract class RtcEngine { /// Sets the camera exposure position. /// - /// This method must be called after the camera is turned on, such as calling after startPreview and enableVideo . After a successful method call, the SDK triggers the onCameraExposureAreaChanged callback. This method is for Android and iOS 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). + /// This method is for Android and iOS only. + /// After a successful method call, the SDK triggers the onCameraExposureAreaChanged callback. /// /// * [positionXinView] The horizontal coordinate of the touchpoint in the view. /// * [positionYinView] The vertical coordinate of the touchpoint in the view. /// /// 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. + /// 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 setCameraExposurePosition( {required double positionXinView, required double positionYinView}); + /// Queries whether the current camera supports adjusting exposure value. + /// + /// This method is for Android and iOS only. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// Before calling setCameraExposureFactor, Agora recoomends that you call this method to query whether the current camera supports adjusting the exposure value. + /// By calling this method, you adjust the exposure value of the currently active camera, that is, the camera specified when calling setCameraCapturerConfiguration. + /// + /// Returns + /// true : Success. false : Failure. + Future isCameraExposureSupported(); + + /// Sets the camera exposure value. + /// + /// Insufficient or excessive lighting in the shooting environment can affect the image quality of video capture. To achieve optimal video quality, you can use this method to adjust the camera's exposure value. + /// This method is for Android and iOS 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). + /// Before calling this method, Agora recommends calling isCameraExposureSupported to check whether the current camera supports adjusting the exposure value. + /// By calling this method, you adjust the exposure value of the currently active camera, that is, the camera specified when calling setCameraCapturerConfiguration. + /// + /// * [factor] The camera exposure value. The default value is 0, which means using the default exposure of the camera. The larger the value, the greater the exposure. When the video image is overexposed, you can reduce the exposure value; when the video image is underexposed and the dark details are lost, you can increase the exposure value. If the exposure value you specified is beyond the range supported by the device, the SDK will automatically adjust it to the actual supported range of the device. On Android, the value range is [-20.0, 20.0]. On iOS, the value range is [-8.0, 8.0]. + /// + /// 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 setCameraExposureFactor(double factor); + /// Checks whether the device supports auto exposure. /// - /// This method applies to iOS only. Call this method before calling joinChannel , enableVideo , or enableLocalVideo , depending on which method you use to turn on your local camera. + /// This method must be called after the camera is successfully enabled, that is, after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as localVideoStreamStateCapturing (1). + /// This method applies to iOS only. /// /// Returns /// true : The device supports auto exposure. false : The device does not support auto exposure. @@ -4704,49 +5253,78 @@ abstract class RtcEngine { /// Sets whether to enable auto exposure. /// - /// This method applies to iOS only. This method must be called after the camera is turned on, such as calling after startPreview and enableVideo . + /// 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 iOS only. /// - /// * [enabled] Whether to enable auto exposure:true: Enable auto exposure.false: Disable auto exposure. + /// * [enabled] Whether to enable auto exposure: true : Enable auto exposure. false : Disable auto exposure. /// /// 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. + /// 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 setCameraAutoExposureFaceModeEnabled(bool enabled); /// Sets the default audio playback route. /// - /// This method applies to Android and iOS only. Ensure that you call this method before joining a channel. If you need to change the audio route after joining a channel, call setEnableSpeakerphone . Most mobile phones have two audio routes: an earpiece at the top, and a speakerphone at the bottom. The earpiece plays at a lower volume, and the speakerphone at a higher volume. When setting the default audio route, you determine whether audio playback comes through the earpiece or speakerphone when no external audio device is connected. + /// This method applies to Android and iOS only. + /// Ensure that you call this method before joining a channel. If you need to change the audio route after joining a channel, call setEnableSpeakerphone. Most mobile phones have two audio routes: an earpiece at the top, and a speakerphone at the bottom. The earpiece plays at a lower volume, and the speakerphone at a higher volume. When setting the default audio route, you determine whether audio playback comes through the earpiece or speakerphone when no external audio device is connected. /// - /// * [defaultToSpeaker] Whether to set the speakerphone as the default audio route:true: Set the speakerphone as the default audio route.false: Set the earpiece as the default audio route. + /// * [defaultToSpeaker] Whether to set the speakerphone as the default audio route: true : Set the speakerphone as the default audio route. false : Set the earpiece as the default audio route. /// /// 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. + /// 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 setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker); /// Enables/Disables the audio route to the speakerphone. /// - /// If the default audio route of the SDK (see Set the Audio Route ) or the setting in setDefaultAudioRouteToSpeakerphone cannot meet your requirements, you can call setEnableSpeakerphone to switch the current audio route. After a successful method call, the SDK triggers the onAudioRoutingChanged callback. This method only sets the audio route in the current channel and does not influence the default audio route. If the user leaves the current channel and joins another channel, the default audio route is used. This method applies to Android and iOS only. Call this method after joining a channel. If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, the SDK plays audio through the last connected device. + /// If the default audio route of the SDK (see Set the Audio Route) or the setting in setDefaultAudioRouteToSpeakerphone cannot meet your requirements, you can call setEnableSpeakerphone to switch the current audio route. After a successful method call, the SDK triggers the onAudioRoutingChanged callback. This method only sets the audio route in the current channel and does not influence the default audio route. If the user leaves the current channel and joins another channel, the default audio route is used. + /// This method applies to Android and iOS only. + /// Call this method after joining a channel. + /// If the user uses an external audio playback device such as a Bluetooth or wired headset, this method does not take effect, and the SDK plays audio through the external device. When the user uses multiple external devices, the SDK plays audio through the last connected device. /// - /// * [speakerOn] Sets whether to enable the speakerphone or earpiece:true: Enable device state monitoring. The audio route is the speakerphone.false: Disable device state monitoring. The audio route is the earpiece. + /// * [speakerOn] Sets whether to enable the speakerphone or earpiece: true : Enable device state monitoring. The audio route is the speakerphone. false : Disable device state monitoring. The audio route is the earpiece. /// /// 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. + /// 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 setEnableSpeakerphone(bool speakerOn); /// Checks whether the speakerphone is enabled. /// - /// This method is for Android and iOS only. You can call this method either before or after joining a channel. + /// This method is for Android and iOS only. + /// You can call this method either before or after joining a channel. /// /// Returns /// true : The speakerphone is enabled, and the audio plays from the speakerphone. false : The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece. Future isSpeakerphoneEnabled(); + /// Selects the audio playback route in communication audio mode. + /// + /// This method is used to switch the audio route from Bluetooth headphones to earpiece, wired headphones or speakers in communication audio mode (). After the method is called successfully, the SDK will trigger the onAudioRoutingChanged callback to report the modified route. + /// This method is for Android only. + /// Using this method and the setEnableSpeakerphone method at the same time may cause conflicts. Agora recommends that you use the setRouteInCommunicationMode method alone. + /// + /// * [route] The audio playback route you want to use: + /// -1: The default audio route. + /// 0: Headphones with microphone. + /// 1: Handset. + /// 2: Headphones without microphone. + /// 3: Device's built-in speaker. + /// 4: (Not supported yet) External speakers. + /// 5: Bluetooth headphones. + /// 6: USB device. + /// + /// Returns + /// Without practical meaning. + Future setRouteInCommunicationMode(int route); + /// Gets a list of shareable screens and windows. /// /// You can call this method before sharing a screen or window to get a list of shareable screens and windows, which enables a user to use thumbnails in the list to easily choose a particular screen or window to share. This list also contains important information such as window ID and screen ID, with which you can call startScreenCaptureByWindowId or startScreenCaptureByDisplayId to start the sharing. This method applies to macOS and Windows only. /// /// * [thumbSize] The target size of the screen or window thumbnail (the width and height are in pixels). The SDK scales the original image to make the length of the longest side of the image the same as that of the target size without distorting the original image. For example, if the original image is 400 × 300 and thumbSize is 100 × 100, the actual size of the thumbnail is 100 × 75. If the target size is larger than the original size, the thumbnail is the original image and the SDK does not scale it. /// * [iconSize] The target size of the icon corresponding to the application program (the width and height are in pixels). The SDK scales the original image to make the length of the longest side of the image the same as that of the target size without distorting the original image. For example, if the original image is 400 × 300 and iconSize is 100 × 100, the actual size of the icon is 100 × 75. If the target size is larger than the original size, the icon is the original image and the SDK does not scale it. - /// * [includeScreen] Whether the SDK returns the screen information in addition to the window information:true: The SDK returns screen and window information.false: The SDK returns window information only. + /// * [includeScreen] Whether the SDK returns the screen information in addition to the window information: true : The SDK returns screen and window information. false : The SDK returns window information only. /// /// Returns /// The ScreenCaptureSourceInfo array. @@ -4757,25 +5335,33 @@ abstract class RtcEngine { /// Sets the operational permission of the SDK on the audio session. /// - /// The SDK and the app can both configure the audio session by default. If you need to only use the app to configure the audio session, this method restricts the operational permission of the SDK on the audio session. You can call this method either before or after joining a channel. Once you call this method to restrict the operational permission of the SDK on the audio session, the restriction takes effect when the SDK needs to change the audio session. This method is only available for iOS platforms. This method does not restrict the operational permission of the app on the audio session. + /// The SDK and the app can both configure the audio session by default. If you need to only use the app to configure the audio session, this method restricts the operational permission of the SDK on the audio session. You can call this method either before or after joining a channel. Once you call this method to restrict the operational permission of the SDK on the audio session, the restriction takes effect when the SDK needs to change the audio session. + /// This method is only available for iOS platforms. + /// This method does not restrict the operational permission of the app on the audio session. /// /// * [restriction] The operational permission of the SDK on the audio session. See AudioSessionOperationRestriction. This parameter is in bit mask format, and each bit corresponds to a permission. /// /// 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. + /// 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 setAudioSessionOperationRestriction( AudioSessionOperationRestriction restriction); /// Captures the screen by specifying the display ID. /// - /// This method shares a screen or part of the screen. There are two ways to start screen sharing, you can choose one according to your needs: Call this method before joining a channel, and then call joinChannel to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. This method is for Windows and macOS only. + /// This method shares a screen or part of the screen. There are two ways to start screen sharing, you can choose one according to your needs: + /// Call this method before joining a channel, and then call joinChannel to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. + /// Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. This method is for Windows and macOS only. /// - /// * [displayId] The display ID of the screen to be shared.For the Windows platform, if you need to simultaneously share two screens (main screen and secondary screen), you can set displayId to -1 when calling this method. + /// * [displayId] The display ID of the screen to be shared. For the Windows platform, if you need to simultaneously share two screens (main screen and secondary screen), you can set displayId to -1 when calling this method. /// * [regionRect] (Optional) Sets the relative location of the region to the screen. Pass in nil to share the entire screen. See Rectangle. /// * [captureParams] Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters. /// /// 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. -2: The parameter is invalid. -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. + /// 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. + /// -2: The parameter is invalid. + /// -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. Future startScreenCaptureByDisplayId( {required int displayId, required Rectangle regionRect, @@ -4783,14 +5369,19 @@ abstract class RtcEngine { /// Captures the whole or part of a screen by specifying the screen rect. /// - /// There are two ways to start screen sharing, you can choose one according to your needs: Call this method before joining a channel, and then call joinChannel to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. Deprecated: This method is deprecated. Use startScreenCaptureByDisplayId instead. Agora strongly recommends using startScreenCaptureByDisplayId if you need to start screen sharing on a device connected to another display. This method shares a screen or part of the screen. You need to specify the area of the screen to be shared. This method applies to Windows only. + /// There are two ways to start screen sharing, you can choose one according to your needs: + /// Call this method before joining a channel, and then call joinChannel to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. + /// Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. Deprecated: This method is deprecated. Use startScreenCaptureByDisplayId instead. Agora strongly recommends using startScreenCaptureByDisplayId if you need to start screen sharing on a device connected to another display. This method shares a screen or part of the screen. You need to specify the area of the screen to be shared. This method applies to Windows only. /// /// * [screenRect] Sets the relative location of the screen to the virtual screen. - /// * [regionRect] Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. + /// * [regionRect] Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen. /// * [captureParams] The screen sharing encoding parameters. The default video resolution is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters. /// /// 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. -2: The parameter is invalid. -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. + /// 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. + /// -2: The parameter is invalid. + /// -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. Future startScreenCaptureByScreenRect( {required Rectangle screenRect, required Rectangle regionRect, @@ -4798,22 +5389,33 @@ abstract class RtcEngine { /// Gets the audio device information. /// - /// After calling this method, you can get whether the audio device supports ultra-low-latency capture and playback. This method is for Android only. You can call this method either before or after joining a channel. + /// After calling this method, you can get whether the audio device supports ultra-low-latency capture and playback. + /// This method is for Android only. + /// You can call this method either before or after joining a channel. /// /// Returns - /// The DeviceInfo object that identifies the audio device information. Not null: Success. Null: Failure. + /// The DeviceInfo object that identifies the audio device information. + /// Not null: Success. + /// Null: Failure. Future getAudioDeviceInfo(); /// Captures the whole or part of a window by specifying the window ID. /// - /// There are two ways to start screen sharing, you can choose one according to your needs: Call this method before joining a channel, and then call joinChannel to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. This method captures a window or part of the window. You need to specify the ID of the window to be captured. This method applies to the macOS and Windows only. The window sharing feature of the Agora SDK relies on WGC (Windows Graphics Capture) or GDI (Graphics Device Interface) capture, and WGC cannot be set to disable mouse capture on systems earlier than Windows 10 2004. Therefore, captureMouseCursor(false) might not work when you start window sharing on a device with a system earlier than Windows 10 2004. See ScreenCaptureParameters . This method supports window sharing of UWP (Universal Windows Platform) applications. Agora tests the mainstream UWP applications by using the lastest SDK, see details as follows: + /// There are two ways to start screen sharing, you can choose one according to your needs: + /// Call this method before joining a channel, and then call joinChannel to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. + /// Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to true to start screen sharing. This method captures a window or part of the window. You need to specify the ID of the window to be captured. + /// This method applies to the macOS and Windows only. + /// The window sharing feature of the Agora SDK relies on WGC (Windows Graphics Capture) or GDI (Graphics Device Interface) capture, and WGC cannot be set to disable mouse capture on systems earlier than Windows 10 2004. Therefore, captureMouseCursor(false) might not work when you start window sharing on a device with a system earlier than Windows 10 2004. See ScreenCaptureParameters. This method supports window sharing of UWP (Universal Windows Platform) applications. Agora tests the mainstream UWP applications by using the lastest SDK, see details as follows: /// /// * [windowId] The ID of the window to be shared. /// * [regionRect] (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. See Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window. /// * [captureParams] Screen sharing configurations. The default video resolution is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters. /// /// 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. -2: The parameter is invalid. -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. + /// 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. + /// -2: The parameter is invalid. + /// -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. Future startScreenCaptureByWindowId( {required int windowId, required Rectangle regionRect, @@ -4821,12 +5423,15 @@ abstract class RtcEngine { /// Sets the content hint for screen sharing. /// - /// A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithms to different types of content. If you don't call this method, the default content hint is contentHintNone . You can call this method either before or after you start screen sharing. + /// A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithms to different types of content. If you don't call this method, the default content hint is contentHintNone. You can call this method either before or after you start screen sharing. /// /// * [contentHint] The content hint for screen sharing. See VideoContentHint. /// /// 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. -2: The parameter is invalid. -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. + /// 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. + /// -2: The parameter is invalid. + /// -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. Future setScreenCaptureContentHint(VideoContentHint contentHint); /// Updates the screen capturing region. @@ -4836,37 +5441,62 @@ abstract class RtcEngine { /// * [regionRect] The relative location of the screen-share area to the screen or window. If you do not set this parameter, the SDK shares the whole screen or window. See Rectangle. If the specified region overruns the screen or window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen or window. /// /// 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. + /// 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. /// -2: The parameter is invalid. /// -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. Future updateScreenCaptureRegion(Rectangle regionRect); /// Updates the screen capturing parameters. /// - /// This method is for Windows and macOS only. Call this method after starting screen sharing or window sharing. + /// This method is for Windows and macOS only. + /// Call this method after starting screen sharing or window sharing. /// - /// * [captureParams] The screen sharing encoding parameters. The default video resolution is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters + /// * [captureParams] The screen sharing encoding parameters. The default video resolution is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters. /// /// 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. -2: The parameter is invalid. -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. + /// 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. + /// -2: The parameter is invalid. + /// -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. Future updateScreenCaptureParameters( ScreenCaptureParameters captureParams); /// Starts screen capture. /// - /// There are two ways to start screen sharing, you can choose one according to your needs: 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. 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. 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 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. Due to system limitations, some Xiaomi devices do not support capturing system audio during screen sharing. To avoid system audio capture failure when screen sharing, Agora recommends that you set the audio application scenario to audioScenarioGameStreaming by using the setAudioScenario method before joining the channel. + /// There are two ways to start screen sharing, you can choose one according to your needs: + /// 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. + /// 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. + /// 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 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. + /// Due to system limitations, some Xiaomi devices do not support capturing system audio during screen sharing. + /// To avoid system audio capture failure when screen sharing, Agora recommends that you set the audio application scenario to audioScenarioGameStreaming by using the setAudioScenario method before joining the channel. /// /// * [captureParams] The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters2. /// /// 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. -2: The parameter is null. + /// 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. + /// -2: The parameter is null. Future startScreenCapture(ScreenCaptureParameters2 captureParams); /// Starts screen capture. /// - /// This method, as well as startScreenCapture , startScreenCaptureByDisplayId , and startScreenCaptureByWindowId , all have the capability to start screen capture, with the following differences: startScreenCapture only applies to Android and iOS, whereas this method only applies to Windows and iOS. startScreenCaptureByDisplayId and startScreenCaptureByWindowId only support capturing video from a single screen or window. By calling this method and specifying the sourceType parameter, you can capture multiple video streams used for local video mixing or multi-channel publishing. This method applies to the macOS and Windows only. If you call this method to start screen capture, Agora recommends that you call stopScreenCaptureBySourceType to stop the capture and avoid using stopScreenCapture . + /// This method, as well as startScreenCapture, startScreenCaptureByDisplayId, and startScreenCaptureByWindowId, all have the capability to start screen capture, with the following differences: startScreenCapture only applies to Android and iOS, whereas this method only applies to Windows and iOS. startScreenCaptureByDisplayId and startScreenCaptureByWindowId only support capturing video from a single screen or window. By calling this method and specifying the sourceType parameter, you can capture multiple video streams used for local video mixing or multi-channel publishing. + /// This method applies to the macOS and Windows only. + /// If you call this method to start screen capture, Agora recommends that you call stopScreenCaptureBySourceType to stop the capture and avoid using stopScreenCapture. /// - /// * [sourceType] The type of the video source. See VideoSourceType.Windows supports up to four screen capture video streams.macOS supports only one screen capture video stream. You can only set this parameter to videoSourceScreen(2). + /// * [sourceType] The type of the video source. See VideoSourceType. + /// Windows supports up to four screen capture video streams. + /// macOS supports only one screen capture video stream. You can only set this parameter to videoSourceScreen (2). /// * [config] The configuration of the captured screen. See ScreenCaptureConfiguration. /// /// Returns @@ -4877,12 +5507,17 @@ abstract class RtcEngine { /// Updates the screen capturing parameters. /// - /// If the system audio is not captured when screen sharing is enabled, and then you want to update the parameter configuration and publish the system audio, you can refer to the following steps: Call this method, and set captureAudio to true . Call updateChannelMediaOptions , and set publishScreenCaptureAudio to true to publish the audio captured by the screen. This method applies to Android and iOS only. On the iOS platform, screen sharing is only available on iOS 12.0 and later. + /// If the system audio is not captured when screen sharing is enabled, and then you want to update the parameter configuration and publish the system audio, you can refer to the following steps: + /// Call this method, and set captureAudio to true. + /// Call updateChannelMediaOptions, and set publishScreenCaptureAudio to true to publish the audio captured by the screen. + /// This method applies to Android and iOS only. + /// On the iOS platform, screen sharing is only available on iOS 12.0 and later. /// /// * [captureParams] The screen sharing encoding parameters. The default video resolution is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters2. /// /// 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. + /// 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. /// -2: The parameter is invalid. /// -8: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again. Future updateScreenCapture(ScreenCaptureParameters2 captureParams); @@ -4890,7 +5525,8 @@ abstract class RtcEngine { /// Queries the highest frame rate supported by the device during screen sharing. /// /// Returns - /// The highest frame rate supported by the device, if the method is called successfully. See ScreenCaptureFramerateCapability . < 0: Failure. + /// The highest frame rate supported by the device, if the method is called successfully. See ScreenCaptureFramerateCapability. + /// < 0: Failure. Future queryScreenCaptureCapability(); /// Sets the screen sharing scenario. @@ -4900,28 +5536,33 @@ abstract class RtcEngine { /// * [screenScenario] The screen sharing scenario. See ScreenScenarioType. /// /// 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. + /// 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 setScreenCaptureScenario(ScreenScenarioType screenScenario); /// Stops screen capture. /// /// 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. + /// 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 stopScreenCapture(); /// Stops screen capture. /// - /// After calling startScreenCaptureBySourceType to start capturing video from one or more screens, you can call this method and set the sourceType parameter to stop capturing from the specified screens. This method applies to the macOS and Windows only. If you call startScreenCapture , startScreenCaptureByWindowId , or startScreenCaptureByDisplayId to start screen capure, Agora recommends that you call stopScreenCapture instead to stop the capture. + /// After calling startScreenCaptureBySourceType to start capturing video from one or more screens, you can call this method and set the sourceType parameter to stop capturing from the specified screens. + /// This method applies to the macOS and Windows only. + /// If you call startScreenCapture, startScreenCaptureByWindowId, or startScreenCaptureByDisplayId to start screen capure, Agora recommends that you call stopScreenCapture instead to stop the capture. /// /// * [sourceType] The type of the video source. See VideoSourceType. /// /// 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. + /// 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 stopScreenCaptureBySourceType(VideoSourceType sourceType); /// Retrieves the call ID. /// - /// When a user joins a channel on a client, a callId is generated to identify the call from the client. Some methods, such as rate and complain , must be called after the call ends to submit feedback to the SDK. These methods require the callId parameter. Call this method after joining a channel. + /// When a user joins a channel on a client, a callId is generated to identify the call from the client. Some methods, such as rate and complain, must be called after the call ends to submit feedback to the SDK. These methods require the callId parameter. Call this method after joining a channel. /// /// Returns /// The current call ID. @@ -4936,7 +5577,10 @@ abstract class RtcEngine { /// * [description] A description of the call. The string length should be less than 800 bytes. /// /// 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. -2 ( ERR_INVALID_ARGUMENT ). -3 ( ERR_NOT_READY ). + /// 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. + /// -2 (ERR_INVALID_ARGUMENT). + /// -3 (ERR_NOT_READY). Future rate( {required String callId, required int rating, @@ -4950,17 +5594,28 @@ abstract class RtcEngine { /// * [description] A description of the call. The string length should be less than 800 bytes. /// /// 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. -2: The parameter is invalid. - 3: The SDK is not ready. Possible reasons include the following: The initialization of RtcEngine fails. Reinitialize the RtcEngine . No user has joined the channel when the method is called. Please check your code logic. The user has not left the channel when the rate or complain method is called. Please check your code logic. The audio module is disabled. The program is not complete. + /// 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. + /// -2: The parameter is invalid. + /// - 3: The SDK is not ready. Possible reasons include the following: + /// The initialization of RtcEngine fails. Reinitialize the RtcEngine. + /// No user has joined the channel when the method is called. Please check your code logic. + /// The user has not left the channel when the rate or complain method is called. Please check your code logic. + /// The audio module is disabled. The program is not complete. Future complain({required String callId, required String description}); /// 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. 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. + /// Ensure that you enable the Media Push service before using this function. See Enable Media Push. + /// 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. /// /// * [url] The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. /// /// 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. + /// 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. /// -2: The URL is null or the string length is 0. /// -7: The SDK is not initialized before calling this method. /// -19: The Media Push URL is already in use, use another URL instead. @@ -4968,60 +5623,81 @@ 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 . 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 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. + /// 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. /// /// * [url] The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. /// * [transcoding] The transcoding configuration for Media Push. See LiveTranscoding. /// /// 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. -2: The URL is null or the string length is 0. -7: The SDK is not initialized before calling this method. -19: The Media Push URL is already in use, use another URL instead. + /// 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. + /// -2: The URL is null or the string length is 0. + /// -7: The SDK is not initialized before calling this method. + /// -19: The Media Push URL is already in use, use another URL instead. Future startRtmpStreamWithTranscoding( {required String url, required LiveTranscoding transcoding}); /// Updates the transcoding configuration. /// - /// Agora recommends that you use the server-side Media Push function. After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the onTranscodingUpdated callback after the transcoding configuration is updated. + /// Agora recommends that you use the server-side Media Push function. After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the onTranscodingUpdated callback after the transcoding configuration is updated. /// /// * [transcoding] The transcoding configuration for Media Push. See LiveTranscoding. /// /// 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. + /// 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 updateRtmpTranscoding(LiveTranscoding transcoding); /// Stops pushing media streams to a CDN. /// - /// Agora recommends that you use the server-side Media Push function. You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing 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. + /// Agora recommends that you use the server-side Media Push function. You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing 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. /// /// * [url] The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. /// /// 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. + /// 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 stopRtmpStream(String url); /// Starts the local video mixing. /// - /// After calling this method, you can merge multiple video streams into one video stream locally. For example, you can merge the video streams captured by the camera, screen sharing, media player, remote video, video files, images, etc. into one video stream, and then publish the mixed video stream to the channel. Local video mixing requires more CPU resources. Therefore, Agora recommends enabling this function on devices with higher performance. If you need to mix locally captured video streams, the SDK supports the following capture combinations: On the Windows platform, it supports up to 4 video streams captured by cameras + 4 screen sharing streams. On the macOS platform, it supports up to 4 video streams captured by cameras + 1 screen sharing stream. On Android and iOS platforms, it supports video streams captured by up to 2 cameras (the device itself needs to support dual cameras or supports external cameras) + 1 screen sharing stream. If you need to mix the locally collected video streams, you need to call this method after startCameraCapture or startScreenCaptureBySourceType If you want to publish the mixed video stream to the channel, you need to set publishTranscodedVideoTrack in ChannelMediaOptions to true when calling joinChannel or updateChannelMediaOptions . + /// After calling this method, you can merge multiple video streams into one video stream locally. For example, you can merge the video streams captured by the camera, screen sharing, media player, remote video, video files, images, etc. into one video stream, and then publish the mixed video stream to the channel. + /// Local video mixing requires more CPU resources. Therefore, Agora recommends enabling this function on devices with higher performance. + /// If you need to mix locally captured video streams, the SDK supports the following capture combinations: + /// On the Windows platform, it supports up to 4 video streams captured by cameras + 4 screen sharing streams. + /// On the macOS platform, it supports up to 4 video streams captured by cameras + 1 screen sharing stream. + /// On Android and iOS platforms, it supports video streams captured by up to 2 cameras (the device itself needs to support dual cameras or supports external cameras) + 1 screen sharing stream. + /// If you need to mix the locally collected video streams, you need to call this method after startCameraCapture or startScreenCaptureBySourceType. + /// If you want to publish the mixed video stream to the channel, you need to set publishTranscodedVideoTrack in ChannelMediaOptions to true when calling joinChannel or updateChannelMediaOptions. /// - /// * [config] Configuration of the local video mixing, see LocalTranscoderConfiguration.The maximum resolution of each video stream participating in the local video mixing is 4096 × 2160. If this limit is exceeded, video mixing does not take effect.The maximum resolution of the mixed video stream is 4096 × 2160. + /// * [config] Configuration of the local video mixing, see LocalTranscoderConfiguration. + /// The maximum resolution of each video stream participating in the local video mixing is 4096 × 2160. If this limit is exceeded, video mixing does not take effect. + /// The maximum resolution of the mixed video stream is 4096 × 2160. /// /// 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. + /// 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 startLocalVideoTranscoder(LocalTranscoderConfiguration config); /// Updates the local video mixing configuration. /// - /// After calling startLocalVideoTranscoder , call this method if you want to update the local video mixing configuration. If you want to update the video source type used for local video mixing, such as adding a second camera or screen to capture video, you need to call this method after startCameraCapture or startScreenCaptureBySourceType + /// After calling startLocalVideoTranscoder, call this method if you want to update the local video mixing configuration. If you want to update the video source type used for local video mixing, such as adding a second camera or screen to capture video, you need to call this method after startCameraCapture or startScreenCaptureBySourceType. /// /// * [config] Configuration of the local video mixing, see LocalTranscoderConfiguration. /// /// 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. + /// 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 updateLocalTranscoderConfiguration( LocalTranscoderConfiguration config); /// Stops the local video mixing. /// - /// After calling startLocalVideoTranscoder , call this method if you want to stop the local video mixing. + /// After calling startLocalVideoTranscoder, call this method if you want to stop the local video mixing. /// /// 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. @@ -5029,10 +5705,12 @@ abstract class RtcEngine { /// Starts camera capture. /// - /// You can call this method to start capturing video from one or more cameras by specifying sourceType . On the iOS platform, if you want to disable multi-camera capture, you need to call enableMultiCamera and set enabled to true before calling this method. + /// You can call this method to start capturing video from one or more cameras by specifying sourceType. On the iOS platform, if you want to enable multi-camera capture, you need to call enableMultiCamera and set enabled to true before calling this method. /// - /// * [sourceType] The type of the video source. See VideoSourceType.On the mobile platforms, you can capture video from up to 2 cameras, provided the device has dual cameras or supports an external camera.On the desktop platforms, you can capture video from up to 4 cameras. - /// * [config] The configuration of the video capture. See CameraCapturerConfiguration.On the iOS platform, this parameter has no practical function. Use the config parameter in enableMultiCamera instead to set the video capture configuration. + /// * [sourceType] The type of the video source. See VideoSourceType. + /// On the mobile platforms, you can capture video from up to 2 cameras, provided the device has dual cameras or supports an external camera. + /// On the desktop platforms, you can capture video from up to 4 cameras. + /// * [config] The configuration of the video capture. See CameraCapturerConfiguration. On the iOS platform, this parameter has no practical function. Use the config parameter in enableMultiCamera instead to set the video capture configuration. /// /// 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. @@ -5042,23 +5720,27 @@ abstract class RtcEngine { /// Stops camera capture. /// - /// After calling startCameraCapture to start capturing video through one or more cameras, you can call this method and set the sourceType parameter to stop the capture from the specified cameras. On the iOS platform, if you want to disable multi-camera capture, you need to call enableMultiCamera after calling this method and set enabled to false . If you are using the local video mixing function, calling this method can cause the local video mixing to be interrupted. + /// After calling startCameraCapture to start capturing video through one or more cameras, you can call this method and set the sourceType parameter to stop the capture from the specified cameras. On the iOS platform, if you want to disable multi-camera capture, you need to call enableMultiCamera after calling this method and set enabled to false. If you are using the local video mixing function, calling this method can cause the local video mixing to be interrupted. /// /// * [sourceType] The type of the video source. See VideoSourceType. /// /// 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. + /// 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 stopCameraCapture(VideoSourceType sourceType); /// Sets the rotation angle of the captured video. /// - /// This method applies to Windows only. This method must be called after the camera is turned on, such as calling after startPreview and enableVideo . 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. + /// 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. + /// 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. /// * [orientation] The clockwise rotation angle. See VideoOrientation. /// /// 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. + /// 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 setCameraDeviceOrientation( {required VideoSourceType type, required VideoOrientation orientation}); @@ -5071,7 +5753,7 @@ abstract class RtcEngine { /// You can call this method either before or after joining a channel. /// /// Returns - /// The current connection state. See ConnectionStateType . + /// The current connection state. See ConnectionStateType. Future getConnectionState(); /// Adds event handlers @@ -5082,7 +5764,8 @@ abstract class RtcEngine { /// * [eventHandler] Callback events to be added. See RtcEngineEventHandler. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void registerEventHandler(RtcEngineEventHandler eventHandler); /// Removes the specified callback handler. @@ -5101,33 +5784,48 @@ abstract class RtcEngine { /// Sets the built-in encryption mode. /// - /// Deprecated: Use enableEncryption instead. The SDK supports built-in encryption schemes, AES-128-GCM is supported by default. Call this method to use other encryption modes. All users in the same channel must use the same encryption mode and secret . Refer to the information related to the AES encryption algorithm on the differences between the encryption modes. Before calling this method, please call setEncryptionSecret to enable the built-in encryption function. + /// Deprecated: Use enableEncryption instead. The SDK supports built-in encryption schemes, AES-128-GCM is supported by default. Call this method to use other encryption modes. All users in the same channel must use the same encryption mode and secret. Refer to the information related to the AES encryption algorithm on the differences between the encryption modes. Before calling this method, please call setEncryptionSecret to enable the built-in encryption function. /// - /// * [encryptionMode] The following encryption modes:"aes-128-xts": 128-bit AES encryption, XTS mode."aes-128-ecb": 128-bit AES encryption, ECB mode."aes-256-xts": 256-bit AES encryption, XTS mode."sm4-128-ecb": 128-bit SM4 encryption, ECB mode."aes-128-gcm": 128-bit AES encryption, GCM mode."aes-256-gcm": 256-bit AES encryption, GCM mode."": When this parameter is set as null, the encryption mode is set as "aes-128-gcm" by default. + /// * [encryptionMode] The following encryption modes: + /// " aes-128-xts ": 128-bit AES encryption, XTS mode. + /// " aes-128-ecb ": 128-bit AES encryption, ECB mode. + /// " aes-256-xts ": 256-bit AES encryption, XTS mode. + /// " sm4-128-ecb ": 128-bit SM4 encryption, ECB mode. + /// " aes-128-gcm ": 128-bit AES encryption, GCM mode. + /// " aes-256-gcm ": 256-bit AES encryption, GCM mode. + /// "": When this parameter is set as null, the encryption mode is set as " aes-128-gcm " by default. /// /// 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. + /// 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 setEncryptionMode(String encryptionMode); /// Enables built-in encryption with an encryption password before users join a channel. /// - /// Deprecated: Use enableEncryption instead. Before joining the channel, you need to call this method to set the secret parameter to enable the built-in encryption. All users in the same channel should use the same secret . The secret is automatically cleared once a user leaves the channel. If you do not specify the secret or secret is set as null, the built-in encryption is disabled. Do not use this method for Media Push. For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption. + /// Deprecated: Use enableEncryption instead. Before joining the channel, you need to call this method to set the secret parameter to enable the built-in encryption. All users in the same channel should use the same secret. The secret is automatically cleared once a user leaves the channel. If you do not specify the secret or secret is set as null, the built-in encryption is disabled. + /// Do not use this method for Media Push. + /// For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption. /// /// * [secret] The encryption password. /// /// 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. + /// 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 setEncryptionSecret(String secret); /// Enables or disables the built-in encryption. /// /// In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel. All users in the same channel must use the same encryption mode and encryption key. After the user leaves the channel, the SDK automatically disables the built-in encryption. To enable the built-in encryption, call this method before the user joins the channel again. If you enable the built-in encryption, you cannot use the Media Push function. /// - /// * [enabled] Whether to enable built-in encryption:true: Enable the built-in encryption.false: Disable the built-in encryption. + /// * [enabled] Whether to enable built-in encryption: true : Enable the built-in encryption. false : Disable the built-in encryption. /// * [config] Built-in encryption configurations. See EncryptionConfig. /// /// 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. -2: An invalid parameter is used. Set the parameter with a valid value. -4: The built-in encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library. -7: The SDK is not initialized. Initialize the RtcEngine instance before calling this method. + /// 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. + /// -2: An invalid parameter is used. Set the parameter with a valid value. + /// -4: The built-in encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library. + /// -7: The SDK is not initialized. Initialize the RtcEngine instance before calling this method. Future enableEncryption( {required bool enabled, required EncryptionConfig config}); @@ -5138,39 +5836,57 @@ abstract class RtcEngine { /// * [config] The configurations for the data stream. See DataStreamConfig. /// /// Returns - /// ID of the created data stream, if the method call succeeds. < 0: Failure. + /// ID of the created data stream, if the method call succeeds. + /// < 0: Failure. Future createDataStream(DataStreamConfig config); /// Sends data stream messages. /// - /// Sends data stream messages to all users in a channel. The SDK has the following restrictions on this method: Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 KB. Each client can send up to 6 KB of data per second. Each user can have up to five data streams simultaneously. A successful method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message. - /// A failed method call triggers the onStreamMessageError callback on the remote client. Ensure that you call createDataStream to create a data channel before calling this method. In live streaming scenarios, this method only applies to hosts. + /// Sends data stream messages to all users in a channel. The SDK has the following restrictions on this method: + /// Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 KB. + /// Each client can send up to 6 KB of data per second. + /// Each user can have up to five data streams simultaneously. A successful method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message. + /// A failed method call triggers the onStreamMessageError callback on the remote client. + /// Ensure that you call createDataStream to create a data channel before calling this method. + /// In live streaming scenarios, this method only applies to hosts. /// /// * [streamId] The data stream ID. You can get the data stream ID by calling createDataStream. /// * [data] The message to be sent. /// * [length] The length of the data. /// /// 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. + /// 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 sendStreamMessage( {required int streamId, required Uint8List data, required int length}); /// Adds a watermark image to the local video. /// - /// This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one. The watermark coordinates are dependent on the settings in the setVideoEncoderConfiguration method: If the orientation mode of the encoding video ( OrientationMode ) is fixed landscape mode or the adaptive landscape mode, the watermark uses the landscape orientation. If the orientation mode of the encoding video ( OrientationMode ) is fixed portrait mode or the adaptive portrait mode, the watermark uses the portrait orientation. When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfiguration method; otherwise, the watermark image will be cropped. Ensure that calling this method after enableVideo . If you only want to add a watermark to the media push, you can call this method or the method. This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray. If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings. If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member to set whether or not the watermark is visible in the preview. If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. + /// This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one. The watermark coordinates are dependent on the settings in the setVideoEncoderConfiguration method: + /// If the orientation mode of the encoding video (OrientationMode) is fixed landscape mode or the adaptive landscape mode, the watermark uses the landscape orientation. + /// If the orientation mode of the encoding video (OrientationMode) is fixed portrait mode or the adaptive portrait mode, the watermark uses the portrait orientation. + /// When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfiguration method; otherwise, the watermark image will be cropped. + /// Ensure that calling this method after enableVideo. + /// If you only want to add a watermark to the media push, you can call this method or the method. + /// This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray. + /// If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings. + /// If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member to set whether or not the watermark is visible in the preview. + /// If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. /// /// * [watermarkUrl] The local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path. /// * [options] The options of the watermark image to be added. See WatermarkOptions. /// /// 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. + /// 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 addVideoWatermark( {required String watermarkUrl, required WatermarkOptions options}); /// Removes the watermark image from the video stream. /// /// 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. + /// 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 clearVideoWatermarks(); /// @nodoc @@ -5183,10 +5899,11 @@ abstract class RtcEngine { /// /// Deprecated: The SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method. You can call this method to enable or disable interoperability with the Agora Web SDK. If a channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user. This method is only applicable in live streaming scenarios, and interoperability is enabled by default in communication scenarios. /// - /// * [enabled] Whether to enable interoperability:true: Enable interoperability.false: (Default) Disable interoperability. + /// * [enabled] Whether to enable interoperability: true : Enable interoperability. false : (Default) Disable interoperability. /// /// 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. + /// 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 enableWebSdkInteroperability(bool enabled); /// Reports customized messages. @@ -5202,13 +5919,14 @@ abstract class RtcEngine { /// Registers the metadata observer. /// /// You need to implement the MetadataObserver class and specify the metadata type in this method. This method enables you to add synchronized metadata in the video stream for more diversified - /// live interactive streaming, such as sending shopping links, digital coupons, and online quizzes. Call this method before joinChannel . + /// live interactive streaming, such as sending shopping links, digital coupons, and online quizzes. Call this method before joinChannel. /// /// * [observer] The metadata observer. See MetadataObserver. /// * [type] The metadata type. The SDK currently only supports videoMetadata. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void registerMediaMetadataObserver( {required MetadataObserver observer, required MetadataType type}); @@ -5218,7 +5936,8 @@ abstract class RtcEngine { /// * [type] The metadata type. The SDK currently only supports videoMetadata. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void unregisterMediaMetadataObserver( {required MetadataObserver observer, required MetadataType type}); @@ -5240,39 +5959,77 @@ abstract class RtcEngine { /// Sets whether to enable the AI ​​noise suppression function and set the noise suppression mode. /// - /// You can call this method to enable AI noise suppression function. Once enabled, the SDK automatically detects and reduces stationary and non-stationary noise from your audio on the premise of ensuring the quality of human voice. Stationary noise refers to noise signal with constant average statistical properties and negligibly small fluctuations of level within the period of observation. Common sources of stationary noises are: Television; Air conditioner; Machinery, etc. Non-stationary noise refers to noise signal with huge fluctuations of level within the period of observation. Common sources of non-stationary noises are: Thunder; Explosion; Cracking, etc. + /// You can call this method to enable AI noise suppression function. Once enabled, the SDK automatically detects and reduces stationary and non-stationary noise from your audio on the premise of ensuring the quality of human voice. Stationary noise refers to noise signal with constant average statistical properties and negligibly small fluctuations of level within the period of observation. Common sources of stationary noises are: + /// Television; + /// Air conditioner; + /// Machinery, etc. Non-stationary noise refers to noise signal with huge fluctuations of level within the period of observation; common sources of non-stationary noises are: + /// Thunder; + /// Explosion; + /// Cracking, etc. Agora does not recommend enabling this function on devices running Android 6.0 and below. /// - /// * [enabled] Whether to enable the AI noise suppression function:true: Enable the AI noise suppression.false: (Default) Disable the AI noise suppression. + /// * [enabled] Whether to enable the AI noise suppression function: true : Enable the AI noise suppression. false : (Default) Disable the AI noise suppression. /// * [mode] The AI noise suppression modes. See AudioAinsMode. /// /// 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. + /// 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 setAINSMode( {required bool enabled, required AudioAinsMode mode}); /// Registers a user account. /// - /// Once registered, the user account can be used to identify the local user when the user joins the channel. After the registration is successful, the user account can identify the identity of the local user, and the user can use it to join the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and account of the local user. This method is optional. To join a channel with a user account, you can choose either of the following ways: Call registerLocalUserAccount to create a user account, and then call joinChannelWithUserAccount to join the channel. Call the joinChannelWithUserAccount method to join the channel. The difference between the two ways is that the time elapsed between calling the registerLocalUserAccount method and joining the channel is shorter than directly calling joinChannelWithUserAccount . Ensure that you set the userAccount parameter; otherwise, this method does not take effect. Ensure that the userAccount is unique in the channel. 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. + /// Once registered, the user account can be used to identify the local user when the user joins the channel. After the registration is successful, the user account can identify the identity of the local user, and the user can use it to join the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and account of the local user. This method is optional. To join a channel with a user account, you can choose either of the following ways: + /// Call registerLocalUserAccount to create a user account, and then call joinChannelWithUserAccount to join the channel. + /// Call the joinChannelWithUserAccount method to join the channel. The difference between the two ways is that the time elapsed between calling the registerLocalUserAccount method and joining the channel is shorter than directly calling joinChannelWithUserAccount. + /// Ensure that you set the userAccount parameter; otherwise, this method does not take effect. + /// Ensure that the userAccount is unique in the channel. + /// 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. /// /// * [appId] The App ID of your project on Agora Console. - /// * [userAccount] The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are as follow(89 in total):The 26 lowercase English letters: a to z.The 26 uppercase English letters: A to Z.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// * [userAccount] The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are as follow(89 in total): + /// The 26 lowercase English letters: a to z. + /// The 26 uppercase English letters: A to Z. + /// All numeric characters: 0 to 9. + /// Space + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," /// /// 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. + /// 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 registerLocalUserAccount( {required String appId, required String userAccount}); /// Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. /// - /// This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks: 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. + /// This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks: + /// 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. - /// * [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.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," - /// * [userAccount] The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total):The 26 lowercase English letters: a to z.The 26 uppercase English letters: A to Z.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// * [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. + /// All numeric characters: 0 to 9. + /// Space + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// * [userAccount] The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total): + /// The 26 lowercase English letters: a to z. + /// The 26 uppercase English letters: A to Z. + /// All numeric characters: 0 to 9. + /// Space + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," /// * [options] The channel media options. See ChannelMediaOptions. /// /// 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. -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in ChannelMediaOptions is invalid. You need to pass in a valid parameter and join the channel again. -3: Failes to initialize the RtcEngine object. You need to reinitialize the RtcEngine object. -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. -8: The internal state of the RtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling startEchoTest to stop the test after calling stopEchoTest to start a call loop test. You need to call stopEchoTest before calling this method. -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the connectionStateDisconnected (1) state. -102: The channel name is invalid. You need to pass in a valid channelname in channelId to rejoin the channel. -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel. + /// 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. + /// -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in ChannelMediaOptions is invalid. You need to pass in a valid parameter and join the channel again. + /// -3: Failes to initialize the RtcEngine object. You need to reinitialize the RtcEngine object. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + /// -8: The internal state of the RtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling startEchoTest to stop the test after calling stopEchoTest to start a call loop test. You need to call stopEchoTest before calling this method. + /// -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the connectionStateDisconnected (1) state. + /// -102: The channel name is invalid. You need to pass in a valid channelname in channelId to rejoin the channel. + /// -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel. Future joinChannelWithUserAccount( {required String token, required String channelId, @@ -5281,20 +6038,28 @@ abstract class RtcEngine { /// Joins the channel with a user account, and configures whether to automatically subscribe to audio or video streams after joining the channel. /// - /// 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. 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. This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks: 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. + /// 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. 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. This method allows a user to join the channel with the user account. After the user successfully joins the channel, the SDK triggers the following callbacks: + /// 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. - /// * [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.All numeric characters: 0 to 9.Space"!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// * [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. + /// All numeric characters: 0 to 9. + /// Space + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," /// * [userAccount] The user account. This parameter is used to identify the user in the channel for real-time audio and video engagement. You need to set and manage user accounts yourself and ensure that each user account in the same channel is unique. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as NULL. Supported characters are (89 in total): /// The 26 lowercase English letters: a to z. /// The 26 uppercase English letters: A to Z. /// All numeric characters: 0 to 9. /// Space - /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "= ", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," + /// "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," /// * [options] The channel media options. See ChannelMediaOptions. /// /// 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. + /// 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 joinChannelWithUserAccountEx( {required String token, required String channelId, @@ -5308,7 +6073,8 @@ abstract class RtcEngine { /// * [userAccount] The user account. /// /// Returns - /// A pointer to the UserInfo instance, if the method call succeeds. If the call fails, returns NULL . + /// A pointer to the UserInfo instance, if the method call succeeds. + /// If the call fails, returns NULL. Future getUserInfoByUserAccount(String userAccount); /// Gets the user information by passing in the user ID. @@ -5318,39 +6084,64 @@ abstract class RtcEngine { /// * [uid] The user ID. /// /// Returns - /// A pointer to the UserInfo instance, if the method call succeeds. If the call fails, returns NULL . + /// A pointer to the UserInfo instance, if the method call succeeds. + /// If the call fails, returns NULL. Future getUserInfoByUid(int uid); /// Starts relaying media streams across channels or updates channels for media relay. /// - /// The first successful call to this method starts relaying media streams from the source channel to the destination channels. To relay the media stream to other channels, or exit one of the current media relays, you can call this method again to update the destination channels. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback, and this callback returns the state of the media stream relay. Common states are as follows: If the onChannelMediaRelayStateChanged callback returns relayStateRunning (2) and relayOk (0), it means that the SDK starts relaying media streams from the source channel to the destination channel. If the onChannelMediaRelayStateChanged callback returns relayStateFailure (3), an exception occurs during the media stream relay. Call this method after joining the channel. This method takes effect only when you are a host in a live streaming channel. The relaying media streams across channels function needs to be enabled by contacting . Agora does not support string user accounts in this API. + /// The first successful call to this method starts relaying media streams from the source channel to the destination channels. To relay the media stream to other channels, or exit one of the current media relays, you can call this method again to update the destination channels. This feature supports relaying media streams to a maximum of six destination channels. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback, and this callback returns the state of the media stream relay. Common states are as follows: + /// If the onChannelMediaRelayStateChanged callback returns relayStateRunning (2) and relayOk (0), it means that the SDK starts relaying media streams from the source channel to the destination channel. + /// If the onChannelMediaRelayStateChanged callback returns relayStateFailure (3), an exception occurs during the media stream relay. + /// Call this method after joining the channel. + /// This method takes effect only when you are a host in a live streaming channel. + /// The relaying media streams across channels function needs to be enabled by contacting. + /// Agora does not support string user accounts in this API. /// /// * [configuration] The configuration of the media stream relay. See ChannelMediaRelayConfiguration. /// /// 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: A general error occurs (no specified reason). -2: The parameter is invalid. -7: The method call was rejected. It may be because the SDK has not been initialized successfully, or the user role is not an host. -8: Internal state error. Probably because the user is not an audience member. + /// 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: A general error occurs (no specified reason). + /// -2: The parameter is invalid. + /// -7: The method call was rejected. It may be because the SDK has not been initialized successfully, or the user role is not a host. + /// -8: Internal state error. Probably because the user is not a broadcaster. Future startOrUpdateChannelMediaRelay( ChannelMediaRelayConfiguration configuration); /// Starts relaying media streams across channels. This method can be used to implement scenarios such as co-host across channels. /// - /// Deprecated: This method is deprecated. Use startOrUpdateChannelMediaRelay instead. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay. If the onChannelMediaRelayStateChanged callback returns relayStateRunning (2) and relayOk (0), and the onChannelMediaRelayEvent callback returns relayEventPacketSentToDestChannel (4), it means that the SDK starts relaying media streams between the source channel and the target channel. If the onChannelMediaRelayStateChanged callback returns relayStateFailure (3), an exception occurs during the media stream relay. Call this method after joining the channel. This method takes effect only when you are a host in a live streaming channel. After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay. The relaying media streams across channels function needs to be enabled by contacting . Agora does not support string user accounts in this API. + /// Deprecated: This method is deprecated. Use startOrUpdateChannelMediaRelay instead. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay. + /// If the onChannelMediaRelayStateChanged callback returns relayStateRunning (2) and relayOk (0), and the onChannelMediaRelayEvent callback returns relayEventPacketSentToDestChannel (4), it means that the SDK starts relaying media streams between the source channel and the target channel. + /// If the onChannelMediaRelayStateChanged callback returns relayStateFailure (3), an exception occurs during the media stream relay. + /// Call this method after joining the channel. + /// This method takes effect only when you are a host in a live streaming channel. + /// After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay. + /// The relaying media streams across channels function needs to be enabled by contacting. + /// Agora does not support string user accounts in this API. /// /// * [configuration] The configuration of the media stream relay. See ChannelMediaRelayConfiguration. /// /// 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: A general error occurs (no specified reason). -2: The parameter is invalid. -7: The method call was rejected. It may be because the SDK has not been initialized successfully, or the user role is not an host. -8: Internal state error. Probably because the user is not an audience member. + /// 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: A general error occurs (no specified reason). + /// -2: The parameter is invalid. + /// -7: The method call was rejected. It may be because the SDK has not been initialized successfully, or the user role is not a host. + /// -8: Internal state error. Probably because the user is not a broadcaster. Future startChannelMediaRelay( ChannelMediaRelayConfiguration configuration); /// Updates the channels for media stream relay. /// - /// Deprecated: This method is deprecated. Use startOrUpdateChannelMediaRelay instead. After the media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call this method. After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the relayEventPacketUpdateDestChannel (7) state code. Call the method after successfully calling the startChannelMediaRelay method and receiving onChannelMediaRelayStateChanged ( relayStateRunning , relayOk ) ; otherwise, the method call fails. + /// Deprecated: This method is deprecated. Use startOrUpdateChannelMediaRelay instead. After the media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call this method. After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the relayEventPacketUpdateDestChannel (7) state code. Call the method after successfully calling the startChannelMediaRelay method and receiving onChannelMediaRelayStateChanged (relayStateRunning, relayOk); otherwise, the method call fails. /// /// * [configuration] The configuration of the media stream relay. See ChannelMediaRelayConfiguration. /// /// 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. + /// 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 updateChannelMediaRelay( ChannelMediaRelayConfiguration configuration); @@ -5359,23 +6150,26 @@ abstract class RtcEngine { /// After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback reports relayStateIdle (0) and relayOk (0), the host successfully stops the relay. If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback with the relayErrorServerNoResponse (2) or relayErrorServerConnectionLost (8) status code. You can call the leaveChannel method to leave the channel, and the media stream relay automatically stops. /// /// 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. + /// 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 stopChannelMediaRelay(); /// Pauses the media stream relay to all target channels. /// - /// After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all target channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay . Call this method after startOrUpdateChannelMediaRelay . + /// After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all target channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay. Call this method after startOrUpdateChannelMediaRelay. /// /// 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. + /// 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 pauseAllChannelMediaRelay(); /// Resumes the media stream relay to all target channels. /// - /// After calling the pauseAllChannelMediaRelay method, you can call this method to resume relaying media streams to all destination channels. Call this method after pauseAllChannelMediaRelay . + /// After calling the pauseAllChannelMediaRelay method, you can call this method to resume relaying media streams to all destination channels. Call this method after pauseAllChannelMediaRelay. /// /// 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. + /// 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 resumeAllChannelMediaRelay(); /// Sets the audio profile of the audio streams directly pushed to the CDN by the host. @@ -5385,7 +6179,8 @@ abstract class RtcEngine { /// * [profile] The audio profile, including the sampling rate, bitrate, encoding mode, and the number of channels. See AudioProfileType. /// /// 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. + /// 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 setDirectCdnStreamingAudioConfiguration( AudioProfileType profile); @@ -5393,23 +6188,25 @@ abstract class RtcEngine { /// /// This method only affects video streams captured by cameras or screens, or from custom video capture sources. That is, when you set publishCameraTrack or publishCustomVideoTrack in DirectCdnStreamingMediaOptions as true to capture videos, you can call this method to set the video profiles. If your local camera does not support the video resolution you set,the SDK automatically adjusts the video resolution to a value that is closest to your settings for capture, encoding or streaming, with the same aspect ratio as the resolution you set. You can get the actual resolution of the video streams through the onDirectCdnStreamingStats callback. /// - /// * [config] Video profile. See VideoEncoderConfiguration.During CDN live streaming, Agora only supports setting OrientationMode as orientationModeFixedLandscape or orientationModeFixedPortrait. + /// * [config] Video profile. See VideoEncoderConfiguration. During CDN live streaming, Agora only supports setting OrientationMode as orientationModeFixedLandscape or orientationModeFixedPortrait. /// /// 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. + /// 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 setDirectCdnStreamingVideoConfiguration( VideoEncoderConfiguration config); /// Starts pushing media streams to the CDN directly. /// - /// Aogra does not support pushing media streams to one URL repeatedly. Media options Agora does not support setting the value of publishCameraTrack and publishCustomVideoTrack as true , or the value of publishMicrophoneTrack and publishCustomAudioTrack as true at the same time. When choosing media setting options ( DirectCdnStreamingMediaOptions ), you can refer to the following examples: If you want to push audio and video streams published by the host to the CDN, the media setting options should be set as follows: publishCustomAudioTrack is set as true and call the pushAudioFrame method publishCustomVideoTrack is set as true and call the pushVideoFrame method publishCameraTrack is set as false (the default value) publishMicrophoneTrack is set as false (the default value) As of v4.2.0, Agora SDK supports audio-only live streaming. You can set publishCustomAudioTrack or publishMicrophoneTrack in DirectCdnStreamingMediaOptions as true and call pushAudioFrame to push audio streams. Agora only supports pushing one audio and video streams or one audio streams to CDN. + /// Aogra does not support pushing media streams to one URL repeatedly. Media options Agora does not support setting the value of publishCameraTrack and publishCustomVideoTrack as true, or the value of publishMicrophoneTrack and publishCustomAudioTrack as true at the same time. When choosing media setting options (DirectCdnStreamingMediaOptions), you can refer to the following examples: If you want to push audio and video streams published by the host to the CDN, the media setting options should be set as follows: publishCustomAudioTrack is set as true and call the pushAudioFrame method publishCustomVideoTrack is set as true and call the pushVideoFrame method publishCameraTrack is set as false (the default value) publishMicrophoneTrack is set as false (the default value) As of v4.2.0, Agora SDK supports audio-only live streaming. You can set publishCustomAudioTrack or publishMicrophoneTrack in DirectCdnStreamingMediaOptions as true and call pushAudioFrame to push audio streams. Agora only supports pushing one audio and video streams or one audio streams to CDN. /// /// * [eventHandler] See onDirectCdnStreamingStateChanged and onDirectCdnStreamingStats. /// * [publishUrl] The CDN live streaming URL. /// * [options] The media setting options for the host. See DirectCdnStreamingMediaOptions. /// /// 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. + /// 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 startDirectCdnStreaming( {required DirectCdnStreamingEventHandler eventHandler, required String publishUrl, @@ -5418,7 +6215,8 @@ abstract class RtcEngine { /// Stops pushing media streams to the CDN directly. /// /// 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. + /// 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 stopDirectCdnStreaming(); /// @nodoc @@ -5427,14 +6225,19 @@ abstract class RtcEngine { /// Enables the virtual metronome. /// - /// In music education, physical education and other scenarios, teachers usually need to use a metronome so that students can practice with the correct beat. The meter is composed of a downbeat and upbeats. The first beat of each measure is called a downbeat, and the rest are called upbeats. In this method, you need to set the file path of the upbeat and downbeat, the number of beats per measure, the beat speed, and whether to send the sound of the metronome to remote users. After successfully calling this method, the SDK triggers the onRhythmPlayerStateChanged callback locally to report the status of the virtual metronome. This method is for Android and iOS only. After enabling the virtual metronome, the SDK plays the specified audio effect file from the beginning, and controls the playback duration of each file according to beatsPerMinute you set in AgoraRhythmPlayerConfig . For example, if you set beatsPerMinute as 60 , the SDK plays one beat every second. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration. By default, the sound of the virtual metronome is published in the channel. If you do not want the sound to be heard by the remote users, you can set publishRhythmPlayerTrack in ChannelMediaOptions as false . + /// In music education, physical education and other scenarios, teachers usually need to use a metronome so that students can practice with the correct beat. The meter is composed of a downbeat and upbeats. The first beat of each measure is called a downbeat, and the rest are called upbeats. In this method, you need to set the file path of the upbeat and downbeat, the number of beats per measure, the beat speed, and whether to send the sound of the metronome to remote users. After successfully calling this method, the SDK triggers the onRhythmPlayerStateChanged callback locally to report the status of the virtual metronome. + /// This method is for Android and iOS only. + /// After enabling the virtual metronome, the SDK plays the specified audio effect file from the beginning, and controls the playback duration of each file according to beatsPerMinute you set in AgoraRhythmPlayerConfig. For example, if you set beatsPerMinute as 60, the SDK plays one beat every second. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration. + /// By default, the sound of the virtual metronome is published in the channel. If you do not want the sound to be heard by the remote users, you can set publishRhythmPlayerTrack in ChannelMediaOptions as false. /// /// * [sound1] The absolute path or URL address (including the filename extensions) of the file for the downbeat. For example, C:\music\audio.mp4. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support. /// * [sound2] The absolute path or URL address (including the filename extensions) of the file for the upbeats. For example, C:\music\audio.mp4. For the audio file formats supported by this method, see What formats of audio files does the Agora RTC SDK support. /// * [config] The metronome configuration. See AgoraRhythmPlayerConfig. /// /// 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. -22: Cannot find audio effect files. Please set the correct paths for sound1 and sound2 . + /// 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. + /// -22: Cannot find audio effect files. Please set the correct paths for sound1 and sound2. Future startRhythmPlayer( {required String sound1, required String sound2, @@ -5442,54 +6245,69 @@ abstract class RtcEngine { /// Disables the virtual metronome. /// - /// After calling startRhythmPlayer , you can call this method to disable the virtual metronome. This method is for Android and iOS only. + /// After calling startRhythmPlayer, you can call this method to disable the virtual metronome. This method is for Android and iOS only. /// /// 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. + /// 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 stopRhythmPlayer(); /// Configures the virtual metronome. /// - /// This method is for Android and iOS only. After enabling the virtual metronome, the SDK plays the specified audio effect file from the beginning, and controls the playback duration of each file according to beatsPerMinute you set in AgoraRhythmPlayerConfig . For example, if you set beatsPerMinute as 60 , the SDK plays one beat every second. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration. By default, the sound of the virtual metronome is published in the channel. If you do not want the sound to be heard by the remote users, you can set publishRhythmPlayerTrack in ChannelMediaOptions as false . After calling startRhythmPlayer , you can call this method to reconfigure the virtual metronome. After successfully calling this method, the SDK triggers the onRhythmPlayerStateChanged callback locally to report the status of the virtual metronome. + /// This method is for Android and iOS only. + /// After enabling the virtual metronome, the SDK plays the specified audio effect file from the beginning, and controls the playback duration of each file according to beatsPerMinute you set in AgoraRhythmPlayerConfig. For example, if you set beatsPerMinute as 60, the SDK plays one beat every second. If the file duration exceeds the beat duration, the SDK only plays the audio within the beat duration. + /// By default, the sound of the virtual metronome is published in the channel. If you do not want the sound to be heard by the remote users, you can set publishRhythmPlayerTrack in ChannelMediaOptions as false. After calling startRhythmPlayer, you can call this method to reconfigure the virtual metronome. After successfully calling this method, the SDK triggers the onRhythmPlayerStateChanged callback locally to report the status of the virtual metronome. /// /// * [config] The metronome configuration. See AgoraRhythmPlayerConfig. /// /// 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. + /// 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 configRhythmPlayer(AgoraRhythmPlayerConfig config); /// Takes a snapshot of a video stream. /// - /// This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path. The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successfully taken, as well as the details for that snapshot. Call this method after joining a channel. This method takes a snapshot of the published video stream specified in ChannelMediaOptions . If the user's video has been preprocessed, for example, watermarked or beautified, the resulting snapshot includes the pre-processing effect. + /// This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path. The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successfully taken, as well as the details for that snapshot. + /// Call this method after joining a channel. + /// When used for local video snapshots, this method takes a snapshot for the video streams specified in ChannelMediaOptions. + /// If the user's video has been preprocessed, for example, watermarked or beautified, the resulting snapshot includes the pre-processing effect. /// /// * [uid] The user ID. Set uid as 0 if you want to take a snapshot of the local user's video. - /// * [filePath] The local path (including filename extensions) of the snapshot. For example:Windows: C:\Users\\AppData\Local\Agora\\example.jpgiOS: /App Sandbox/Library/Caches/example.jpgmacOS: ～/Library/Logs/example.jpgAndroid: /storage/emulated/0/Android/data//files/example.jpgEnsure that the path you specify exists and is writable. + /// * [filePath] The local path (including filename extensions) of the snapshot. For example: + /// Windows: C:\Users\\AppData\Local\Agora\\example.jpg + /// iOS: /App Sandbox/Library/Caches/example.jpg + /// macOS: ～/Library/Logs/example.jpg + /// Android: /storage/emulated/0/Android/data//files/example.jpg Ensure that the path you specify exists and is writable. /// /// 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. + /// 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 takeSnapshot({required int uid, required String filePath}); /// 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. 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 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. /// - /// * [enabled] Whether to enable video screenshot and uploadtrue: Enables video screenshot and upload. false: Disables video screenshot and upload. + /// * [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. /// /// 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. + /// 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 enableContentInspect( {required bool enabled, required ContentInspectConfig config}); - /// Adjusts the volume of the custom external audio source when it is published in the channel. + /// Adjusts the volume of the custom audio track played remotely. /// - /// Ensure you have called the createCustomAudioTrack method to create an external audio track before calling this method. If you want to change the volume of the audio to be published, you need to call this method again. + /// 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 published, 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. + /// 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 adjustCustomAudioPublishVolume( {required int trackId, required int volume}); @@ -5499,12 +6317,18 @@ abstract class RtcEngine { /// Sets up cloud proxy service. /// - /// When users' network access is restricted by a firewall, configure the firewall to allow specific IP addresses and ports provided by Agora; then, call this method to enable the cloud proxyType and set the cloud proxy type with the proxyType parameter. After successfully connecting to the cloud proxy, the SDK triggers the onConnectionStateChanged ( connectionStateConnecting , connectionChangedSettingProxyServer ) callback. To disable the cloud proxy that has been set, call the setCloudProxy ( noneProxy ) . To change the cloud proxy type that has been set, call the setCloudProxy ( noneProxy ) first, and then call the setCloudProxy to set the proxyType you want. Agora recommends that you call this method after joining a channel. When a user is behind a firewall and uses the Force UDP cloud proxy, the services for Media Push and cohosting across channels are not available. When you use the Force TCP cloud proxy, note that an error would occur when calling the startAudioMixing method to play online music files in the HTTP protocol. The services for Media Push and cohosting across channels use the cloud proxy with the TCP protocol. + /// When users' network access is restricted by a firewall, configure the firewall to allow specific IP addresses and ports provided by Agora; then, call this method to enable the cloud proxyType and set the cloud proxy type with the proxyType parameter. After successfully connecting to the cloud proxy, the SDK triggers the onConnectionStateChanged (connectionStateConnecting, connectionChangedSettingProxyServer) callback. To disable the cloud proxy that has been set, call the setCloudProxy (noneProxy). To change the cloud proxy type that has been set, call the setCloudProxy (noneProxy) first, and then call the setCloudProxy to set the proxyType you want. + /// Agora recommends that you call this method after joining a channel. + /// When a user is behind a firewall and uses the Force UDP cloud proxy, the services for Media Push and cohosting across channels are not available. + /// When you use the Force TCP cloud proxy, note that an error would occur when calling the startAudioMixing method to play online music files in the HTTP protocol. The services for Media Push and cohosting across channels use the cloud proxy with the TCP protocol. /// - /// * [proxyType] The type of the cloud proxy. See CloudProxyType.This parameter is mandatory. The SDK reports an error if you do not pass in a value. + /// * [proxyType] The type of the cloud proxy. See CloudProxyType. This parameter is mandatory. The SDK reports an error if you do not pass in a value. /// /// 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. -2: The parameter is invalid. -7: The SDK is not initialized. + /// 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. + /// -2: The parameter is invalid. + /// -7: The SDK is not initialized. Future setCloudProxy(CloudProxyType proxyType); /// @nodoc @@ -5512,12 +6336,13 @@ abstract class RtcEngine { /// Sets audio advanced options. /// - /// If you have advanced audio processing requirements, such as capturing and sending stereo audio, you can call this method to set advanced audio options. Call this method after calling joinChannel , enableAudio and enableLocalAudio . + /// If you have advanced audio processing requirements, such as capturing and sending stereo audio, you can call this method to set advanced audio options. Call this method after calling joinChannel, enableAudio and enableLocalAudio. /// /// * [options] The advanced options for audio. See AdvancedAudioOptions. /// /// 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. + /// 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 setAdvancedAudioOptions( {required AdvancedAudioOptions options, int sourceType = 0}); @@ -5528,20 +6353,22 @@ abstract class RtcEngine { /// /// Agora recommends that you call this method after joining a channel. When publishing video streams, you can call this method to replace the current video feeds with custom images. Once you enable this function, you can select images to replace the video feeds through the ImageTrackOptions parameter. If you disable this function, the remote users see the video feeds that you publish. /// - /// * [enable] Whether to replace the current video feeds with custom images:true: Replace the current video feeds with custom images.false: (Default) Do not replace the current video feeds with custom images. + /// * [enable] Whether to replace the current video feeds with custom images: true : Replace the current video feeds with custom images. false : (Default) Do not replace the current video feeds with custom images. /// * [options] Image configurations. See ImageTrackOptions. /// /// 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. + /// 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 enableVideoImageSource( {required bool enable, required ImageTrackOptions options}); /// Gets the current Monotonic Time of the SDK. /// - /// Monotonic Time refers to a monotonically increasing time series whose value increases over time. The unit is milliseconds. In custom video capture and custom audio capture scenarios, in order to ensure audio and video synchronization, Agora recommends that you call this method to obtain the current Monotonic Time of the SDK, and then pass this value into the timestamp parameter in the captured video frame ( VideoFrame ) and audio frame ( AudioFrame ). + /// Monotonic Time refers to a monotonically increasing time series whose value increases over time. The unit is milliseconds. In custom video capture and custom audio capture scenarios, in order to ensure audio and video synchronization, Agora recommends that you call this method to obtain the current Monotonic Time of the SDK, and then pass this value into the timestamp parameter in the captured video frame (VideoFrame) and audio frame (AudioFrame). /// /// Returns - /// ≥0: The method call is successful, and returns the current Monotonic Time of the SDK (in milliseconds). < 0: Failure. + /// ≥0: The method call is successful, and returns the current Monotonic Time of the SDK (in milliseconds). + /// < 0: Failure. Future getCurrentMonotonicTimeInMs(); /// @nodoc @@ -5552,7 +6379,16 @@ abstract class RtcEngine { /// You can use this method to get the type of network in use at any stage. You can call this method either before or after joining a channel. /// /// Returns - /// ≥ 0: The method call is successful, and the local network connection type is returned. 0: The SDK disconnects from the network. 1: The network type is LAN. 2: The network type is Wi-Fi (including hotspots). 3: The network type is mobile 2G. 4: The network type is mobile 3G. 5: The network type is mobile 4G. 6: The network type is mobile 5G. < 0: The method call failed with an error code. -1: The network type is unknown. + /// ≥ 0: The method call is successful, and the local network connection type is returned. + /// 0: The SDK disconnects from the network. + /// 1: The network type is LAN. + /// 2: The network type is Wi-Fi (including hotspots). + /// 3: The network type is mobile 2G. + /// 4: The network type is mobile 3G. + /// 5: The network type is mobile 4G. + /// 6: The network type is mobile 5G. + /// < 0: The method call failed with an error code. + /// -1: The network type is unknown. Future getNetworkType(); /// Provides technical preview functionalities or special customizations by configuring the SDK with JSON options. @@ -5560,23 +6396,32 @@ abstract class RtcEngine { /// * [parameters] Pointer to the set parameters in a JSON string. /// /// 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. + /// 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 setParameters(String parameters); /// Enables tracing the video frame rendering process. /// - /// The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is successfully called and reports information about the event through the onVideoRenderingTracingResult callback. By default, the SDK starts tracing the video rendering event automatically when the local user successfully joins the channel. You can call this method at an appropriate time according to the actual application scenario to customize the tracing process. After the local user leaves the current channel, the SDK automatically resets the time point to the next time when the user successfully joins the channel. + /// The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is successfully called and reports information about the event through the onVideoRenderingTracingResult callback. + /// By default, the SDK starts tracing the video rendering event automatically when the local user successfully joins the channel. You can call this method at an appropriate time according to the actual application scenario to customize the tracing process. + /// After the local user leaves the current channel, the SDK automatically resets the time point to the next time when the user successfully joins the channel. /// /// 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. -7: The method is called before RtcEngine is initialized. + /// 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. + /// -7: The method is called before RtcEngine is initialized. Future startMediaRenderingTracing(); /// Enables audio and video frame instant rendering. /// - /// After successfully calling this method, the SDK enables the instant frame rendering mode, which can speed up the first frame rendering speed after the user joins the channel. Once the instant rendering function is enabled, it can only be canceled by calling the release method to destroy the RtcEngine object. In this mode, the SDK uses Agora's custom encryption algorithm to shorten the time required to establish transmission links, and the security is reduced compared to the standard DTLS (Datagram Transport Layer Security). If the application scenario requires higher security standards, Agora recommends that you do not use this method. + /// After successfully calling this method, the SDK enables the instant frame rendering mode, which can speed up the first frame rendering speed after the user joins the channel. + /// Once the instant rendering function is enabled, it can only be canceled by calling the release method to destroy the RtcEngine object. + /// In this mode, the SDK uses Agora's custom encryption algorithm to shorten the time required to establish transmission links, and the security is reduced compared to the standard DTLS (Datagram Transport Layer Security). If the application scenario requires higher security standards, Agora recommends that you do not use this method. /// /// 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. -7: The method is called before RtcEngine is initialized. + /// 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. + /// -7: The method is called before RtcEngine is initialized. Future enableInstantMediaRendering(); /// Gets the current NTP (Network Time Protocol) time. @@ -5629,18 +6474,20 @@ abstract class RtcEngine { /// * [sourceType] The type of the video source. See VideoSourceType. /// /// 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. + /// 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 sendMetaData( {required Metadata metadata, required VideoSourceType sourceType}); /// Sets the maximum size of the media metadata. /// - /// After calling registerMediaMetadataObserver , you can call this method to set the maximum size of the media metadata. + /// After calling registerMediaMetadataObserver, you can call this method to set the maximum size of the media metadata. /// /// * [size] The maximum size of media metadata. /// /// 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. + /// 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 setMaxMetadataSize(int size); /// Unregisters the encoded audio frame observer. @@ -5648,7 +6495,8 @@ abstract class RtcEngine { /// * [observer] The encoded audio observer. See AudioEncodedFrameObserver. /// /// 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. + /// When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown; and you need to catch the exception and handle it accordingly. + /// < 0: Failure. void unregisterAudioEncodedFrameObserver(AudioEncodedFrameObserver observer); /// Gets the C++ handle of the Native SDK. @@ -5781,15 +6629,15 @@ enum VideoProfileType { @JsonValue(37) videoProfileLandscape360p8, - /// 38: 640 × 360, frame rate 15 fps, bitrate 800 Kbps.This profile applies only to the live streaming channel profile. + /// 38: 640 × 360, frame rate 15 fps, bitrate 800 Kbps. This profile applies only to the live streaming channel profile. @JsonValue(38) videoProfileLandscape360p9, - /// 39: 640 × 360, frame rate 24 fps, bitrate 800 Kbps.This profile applies only to the live streaming channel profile. + /// 39: 640 × 360, frame rate 24 fps, bitrate 800 Kbps. This profile applies only to the live streaming channel profile. @JsonValue(39) videoProfileLandscape360p10, - /// 100: 640 × 360, frame rate 24 fps, bitrate 1000 Kbps.This profile applies only to the live streaming channel profile. + /// 100: 640 × 360, frame rate 24 fps, bitrate 1000 Kbps. This profile applies only to the live streaming channel profile. @JsonValue(100) videoProfileLandscape360p11, @@ -5921,15 +6769,15 @@ enum VideoProfileType { @JsonValue(1037) videoProfilePortrait360p8, - /// 1038: 360 × 640, frame rate 15 fps, bitrate 800 Kbps.This profile applies only to the live streaming channel profile. + /// 1038: 360 × 640, frame rate 15 fps, bitrate 800 Kbps. This profile applies only to the live streaming channel profile. @JsonValue(1038) videoProfilePortrait360p9, - /// 1039: 360 × 640, frame rate 24 fps, bitrate 800 Kbps.This profile applies only to the live streaming channel profile. + /// 1039: 360 × 640, frame rate 24 fps, bitrate 800 Kbps. This profile applies only to the live streaming channel profile. @JsonValue(1039) videoProfilePortrait360p10, - /// 1100: 360 × 640, frame rate 24 fps, bitrate 1000 Kbps.This profile applies only to the live streaming channel profile. + /// 1100: 360 × 640, frame rate 24 fps, bitrate 1000 Kbps. This profile applies only to the live streaming channel profile. @JsonValue(1100) videoProfilePortrait360p11, diff --git a/lib/src/agora_rtc_engine.g.dart b/lib/src/agora_rtc_engine.g.dart index d276e05fe..38c06fe23 100644 --- a/lib/src/agora_rtc_engine.g.dart +++ b/lib/src/agora_rtc_engine.g.dart @@ -591,11 +591,15 @@ ChannelMediaOptions _$ChannelMediaOptionsFromJson(Map json) => ChannelMediaOptions( publishCameraTrack: json['publishCameraTrack'] as bool?, publishSecondaryCameraTrack: json['publishSecondaryCameraTrack'] as bool?, + publishThirdCameraTrack: json['publishThirdCameraTrack'] as bool?, + publishFourthCameraTrack: json['publishFourthCameraTrack'] as bool?, publishMicrophoneTrack: json['publishMicrophoneTrack'] as bool?, publishScreenCaptureVideo: json['publishScreenCaptureVideo'] as bool?, publishScreenCaptureAudio: json['publishScreenCaptureAudio'] as bool?, publishScreenTrack: json['publishScreenTrack'] as bool?, publishSecondaryScreenTrack: json['publishSecondaryScreenTrack'] as bool?, + publishThirdScreenTrack: json['publishThirdScreenTrack'] as bool?, + publishFourthScreenTrack: json['publishFourthScreenTrack'] as bool?, publishCustomAudioTrack: json['publishCustomAudioTrack'] as bool?, publishCustomAudioTrackId: json['publishCustomAudioTrackId'] as int?, publishCustomVideoTrack: json['publishCustomVideoTrack'] as bool?, @@ -641,12 +645,16 @@ Map _$ChannelMediaOptionsToJson(ChannelMediaOptions instance) { writeNotNull('publishCameraTrack', instance.publishCameraTrack); writeNotNull( 'publishSecondaryCameraTrack', instance.publishSecondaryCameraTrack); + writeNotNull('publishThirdCameraTrack', instance.publishThirdCameraTrack); + writeNotNull('publishFourthCameraTrack', instance.publishFourthCameraTrack); writeNotNull('publishMicrophoneTrack', instance.publishMicrophoneTrack); writeNotNull('publishScreenCaptureVideo', instance.publishScreenCaptureVideo); writeNotNull('publishScreenCaptureAudio', instance.publishScreenCaptureAudio); writeNotNull('publishScreenTrack', instance.publishScreenTrack); writeNotNull( 'publishSecondaryScreenTrack', instance.publishSecondaryScreenTrack); + writeNotNull('publishThirdScreenTrack', instance.publishThirdScreenTrack); + writeNotNull('publishFourthScreenTrack', instance.publishFourthScreenTrack); writeNotNull('publishCustomAudioTrack', instance.publishCustomAudioTrack); writeNotNull('publishCustomAudioTrackId', instance.publishCustomAudioTrackId); writeNotNull('publishCustomVideoTrack', instance.publishCustomVideoTrack); @@ -700,94 +708,6 @@ const _$ChannelProfileTypeEnumMap = { ChannelProfileType.channelProfileCommunication1v1: 4, }; -LogUploadServerInfo _$LogUploadServerInfoFromJson(Map json) => - LogUploadServerInfo( - serverDomain: json['serverDomain'] as String?, - serverPath: json['serverPath'] as String?, - serverPort: json['serverPort'] as int?, - serverHttps: json['serverHttps'] as bool?, - ); - -Map _$LogUploadServerInfoToJson(LogUploadServerInfo instance) { - final val = {}; - - void writeNotNull(String key, dynamic value) { - if (value != null) { - val[key] = value; - } - } - - writeNotNull('serverDomain', instance.serverDomain); - writeNotNull('serverPath', instance.serverPath); - writeNotNull('serverPort', instance.serverPort); - writeNotNull('serverHttps', instance.serverHttps); - return val; -} - -AdvancedConfigInfo _$AdvancedConfigInfoFromJson(Map json) => - AdvancedConfigInfo( - logUploadServer: json['logUploadServer'] == null - ? null - : LogUploadServerInfo.fromJson( - json['logUploadServer'] as Map), - ); - -Map _$AdvancedConfigInfoToJson(AdvancedConfigInfo instance) { - final val = {}; - - void writeNotNull(String key, dynamic value) { - if (value != null) { - val[key] = value; - } - } - - writeNotNull('logUploadServer', instance.logUploadServer?.toJson()); - return val; -} - -LocalAccessPointConfiguration _$LocalAccessPointConfigurationFromJson( - Map json) => - LocalAccessPointConfiguration( - ipList: - (json['ipList'] as List?)?.map((e) => e as String).toList(), - ipListSize: json['ipListSize'] as int?, - domainList: (json['domainList'] as List?) - ?.map((e) => e as String) - .toList(), - domainListSize: json['domainListSize'] as int?, - verifyDomainName: json['verifyDomainName'] as String?, - mode: $enumDecodeNullable(_$LocalProxyModeEnumMap, json['mode']), - advancedConfig: json['advancedConfig'] == null - ? null - : AdvancedConfigInfo.fromJson( - json['advancedConfig'] as Map), - ); - -Map _$LocalAccessPointConfigurationToJson( - LocalAccessPointConfiguration instance) { - final val = {}; - - void writeNotNull(String key, dynamic value) { - if (value != null) { - val[key] = value; - } - } - - writeNotNull('ipList', instance.ipList); - writeNotNull('ipListSize', instance.ipListSize); - writeNotNull('domainList', instance.domainList); - writeNotNull('domainListSize', instance.domainListSize); - writeNotNull('verifyDomainName', instance.verifyDomainName); - writeNotNull('mode', _$LocalProxyModeEnumMap[instance.mode]); - writeNotNull('advancedConfig', instance.advancedConfig?.toJson()); - return val; -} - -const _$LocalProxyModeEnumMap = { - LocalProxyMode.connectivityFirst: 0, - LocalProxyMode.localOnly: 1, -}; - LeaveChannelOptions _$LeaveChannelOptionsFromJson(Map json) => LeaveChannelOptions( stopAudioMixing: json['stopAudioMixing'] as bool?, diff --git a/lib/src/agora_rtc_engine_ex.dart b/lib/src/agora_rtc_engine_ex.dart index 034d94e62..71c13eafd 100644 --- a/lib/src/agora_rtc_engine_ex.dart +++ b/lib/src/agora_rtc_engine_ex.dart @@ -25,18 +25,29 @@ class RtcConnection { /// This interface class contains multi-channel methods. /// -/// Inherited from RtcEngine . +/// Inherited from RtcEngine. abstract class RtcEngineEx implements RtcEngine { /// Joins a channel with the connection ID. /// - /// You can call this method multiple times to join more than one channel. If you are already in a channel, you cannot rejoin it with the same user ID. 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. + /// You can call this method multiple times to join more than one channel. + /// If you are already in a channel, you cannot rejoin it with the same user ID. + /// 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. /// * [connection] The connection information. See RtcConnection. /// * [options] The channel media options. See ChannelMediaOptions. /// /// 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. -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in ChannelMediaOptions is invalid. You need to pass in a valid parameter and join the channel again. -3: Failes to initialize the RtcEngine object. You need to reinitialize the RtcEngine object. -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. -8: The internal state of the RtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling startEchoTest to stop the test after calling stopEchoTest to start a call loop test. You need to call stopEchoTest before calling this method. -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the connectionStateDisconnected (1) state. -102: The channel name is invalid. You need to pass in a valid channelname in channelId to rejoin the channel. -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel. + /// 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. + /// -2: The parameter is invalid. For example, the token is invalid, the uid parameter is not set to an integer, or the value of a member in ChannelMediaOptions is invalid. You need to pass in a valid parameter and join the channel again. + /// -3: Failes to initialize the RtcEngine object. You need to reinitialize the RtcEngine object. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + /// -8: The internal state of the RtcEngine object is wrong. The typical cause is that you call this method to join the channel without calling startEchoTest to stop the test after calling stopEchoTest to start a call loop test. You need to call stopEchoTest before calling this method. + /// -17: The request to join the channel is rejected. The typical cause is that the user is in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. Do not call this method to join the channel unless you receive the connectionStateDisconnected (1) state. + /// -102: The channel name is invalid. You need to pass in a valid channelname in channelId to rejoin the channel. + /// -121: The user ID is invalid. You need to pass in a valid user ID in uid to rejoin the channel. Future joinChannelEx( {required String token, required RtcConnection connection, @@ -44,13 +55,16 @@ abstract class RtcEngineEx implements RtcEngine { /// Sets channel options and leaves the channel. /// - /// 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. + /// 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. /// /// * [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. + /// * [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. /// /// 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. + /// 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 leaveChannelEx( {required RtcConnection connection, LeaveChannelOptions? options}); @@ -60,7 +74,11 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// 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. -2: The value of a member in the ChannelMediaOptions structure is invalid. For example, the token or the user ID is invalid. You need to fill in a valid parameter. -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. -8: The internal state of the RtcEngine object is wrong. The possible reason is that the user is not in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. If you receive the connectionStateDisconnected (1) or connectionStateFailed (5) state, the user is not in the channel. You need to call joinChannel to join a channel before calling this method. + /// 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. + /// -2: The value of a member in the ChannelMediaOptions structure is invalid. For example, the token or the user ID is invalid. You need to fill in a valid parameter. + /// -7: The RtcEngine object has not been initialized. You need to initialize the RtcEngine object before calling this method. + /// -8: The internal state of the RtcEngine object is wrong. The possible reason is that the user is not in the channel. Agora recommends that you use the onConnectionStateChanged callback to determine whether the user exists in the channel. If you receive the connectionStateDisconnected (1) or connectionStateFailed (5) state, the user is not in the channel. You need to call joinChannel to join a channel before calling this method. Future updateChannelMediaOptionsEx( {required ChannelMediaOptions options, required RtcConnection connection}); @@ -73,7 +91,8 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setVideoEncoderConfigurationEx( {required VideoEncoderConfiguration config, required RtcConnection connection}); @@ -86,18 +105,20 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setupRemoteVideoEx( {required VideoCanvas canvas, required RtcConnection connection}); /// Stops or resumes receiving the audio stream of a specified user. /// /// * [uid] The ID of the specified user. - /// * [mute] Whether to stop receiving the audio stream of the specified user:true: Stop receiving the audio stream of the specified user.false: (Default) Resume receiving the audio stream of the specified user. + /// * [mute] Whether to stop receiving the audio stream of the specified user: true : Stop receiving the audio stream of the specified user. false : (Default) Resume receiving the audio stream of the specified user. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 muteRemoteAudioStreamEx( {required int uid, required bool mute, @@ -108,11 +129,12 @@ abstract class RtcEngineEx implements RtcEngine { /// This method is used to stop or resume receiving the video stream of a specified user. You can call this method before or after joining a channel. If a user leaves a channel, the settings in this method become invalid. /// /// * [uid] The user ID of the remote user. - /// * [mute] Whether to stop receiving the video stream of the specified user:true: Stop receiving the video stream of the specified user.false: (Default) Resume receiving the video stream of the specified user. + /// * [mute] Whether to stop receiving the video stream of the specified user: true : Stop receiving the video stream of the specified user. false : (Default) Resume receiving the video stream of the specified user. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 muteRemoteVideoStreamEx( {required int uid, required bool mute, @@ -120,14 +142,15 @@ abstract class RtcEngineEx implements RtcEngine { /// Sets the stream type of the remote video. /// - /// Under limited network conditions, if the publisher has not disabled 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, 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. The SDK enables the low-quality video stream auto mode on the sender by default (not actively sending low-quality video streams). The host at the receiving end can call this method to initiate a low-quality video stream stream request on the receiving end, and the sender automatically switches to the low-quality video stream mode after receiving the request. + /// Under limited network conditions, if the publisher has not disabled 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, 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. The SDK enables the low-quality video stream auto mode on the sender by default (not actively sending low-quality video streams). The host at the receiving end can call this method to initiate a low-quality video stream stream request on the receiving end, and the sender automatically switches to the low-quality video stream mode after receiving the request. /// /// * [uid] The user ID. /// * [streamType] The video stream type: VideoStreamType. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setRemoteVideoStreamTypeEx( {required int uid, required VideoStreamType streamType, @@ -137,37 +160,41 @@ abstract class RtcEngineEx implements RtcEngine { /// /// This method does not affect any ongoing audio recording, because it does not disable the audio capture device. A successful call of this method triggers the onUserMuteAudio and onRemoteAudioStateChanged callbacks on the remote client. /// - /// * [mute] Whether to stop publishing the local audio stream:true: Stops publishing the local audio stream.false: (Default) Resumes publishing the local audio stream. + /// * [mute] Whether to stop publishing the local audio stream: true : Stops publishing the local audio stream. false : (Default) Resumes publishing the local audio stream. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 muteLocalAudioStreamEx( {required bool mute, required RtcConnection connection}); /// Stops or resumes publishing the local video stream. /// - /// A successful call of this method triggers the onUserMuteVideo callback on the remote client. This method does not affect any ongoing video recording, because it does not disable the camera. + /// A successful call of this method triggers the onUserMuteVideo callback on the remote client. + /// This method does not affect any ongoing video recording, because it does not disable the camera. /// - /// * [mute] Whether to stop publishing the local video stream. - /// true: Stop publishing the local video stream. - /// false: (Default) Publish the local video stream. + /// * [mute] Whether to stop publishing the local video stream. true : Stop publishing the local video stream. false : (Default) Publish the local video stream. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 muteLocalVideoStreamEx( {required bool mute, required RtcConnection connection}); /// Stops or resumes subscribing to the audio streams of all remote users. /// - /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including the ones join the channel subsequent to this call. Call this method after joining a channel. If you do not want to subscribe the audio streams of remote users before joining a channel, you can set autoSubscribeAudio as false when calling joinChannel . + /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including the ones join the channel subsequent to this call. + /// Call this method after joining a channel. + /// If you do not want to subscribe the audio streams of remote users before joining a channel, you can set autoSubscribeAudio as false when calling joinChannel. /// - /// * [mute] Whether to stop subscribing to the audio streams of all remote users:true: Stops subscribing to the audio streams of all remote users.false: (Default) Subscribes to the audio streams of all remote users by default. + /// * [mute] Whether to stop subscribing to the audio streams of all remote users: true : Stops subscribing to the audio streams of all remote users. false : (Default) Subscribes to the audio streams of all remote users by default. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 muteAllRemoteAudioStreamsEx( {required bool mute, required RtcConnection connection}); @@ -175,24 +202,30 @@ abstract class RtcEngineEx implements RtcEngine { /// /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. /// - /// * [mute] Whether to stop subscribing to the video streams of all remote users.true: Stop subscribing to the video streams of all remote users.false: (Default) Subscribe to the audio streams of all remote users by default. + /// * [mute] Whether to stop subscribing to the video streams of all remote users. true : Stop subscribing to the video streams of all remote users. false : (Default) Subscribe to the audio streams of all remote users by default. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 muteAllRemoteVideoStreamsEx( {required bool mute, required RtcConnection connection}); /// Set the blocklist of subscriptions for audio streams. /// - /// You can call this method to specify the audio streams of a user that you do not want to subscribe to. You can call this method either before or after joining a channel. The blocklist is not affected by the setting in muteRemoteAudioStream , muteAllRemoteAudioStreams , and autoSubscribeAudio in ChannelMediaOptions . Once the blocklist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. + /// You can call this method to specify the audio streams of a user that you do not want to subscribe to. + /// You can call this method either before or after joining a channel. + /// The blocklist is not affected by the setting in muteRemoteAudioStream, muteAllRemoteAudioStreams, and autoSubscribeAudio in ChannelMediaOptions. + /// Once the blocklist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. + /// If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. /// - /// * [uidList] The user ID list of users that you do not want to subscribe to.If you want to specify the audio streams of a user that you do not want to subscribe to, add the user ID in this list. If you want to remove a user from the blocklist, you need to call the setSubscribeAudioBlocklist method to update the user ID list; this means you only add the uid of users that you do not want to subscribe to in the new user ID list. + /// * [uidList] The user ID list of users that you do not want to subscribe to. If you want to specify the audio streams of a user that you do not want to subscribe to, add the user ID in this list. If you want to remove a user from the blocklist, you need to call the setSubscribeAudioBlocklist method to update the user ID list; this means you only add the uid of users that you do not want to subscribe to in the new user ID list. /// * [uidNumber] The number of users in the user ID list. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setSubscribeAudioBlocklistEx( {required List uidList, required int uidNumber, @@ -200,15 +233,19 @@ abstract class RtcEngineEx implements RtcEngine { /// Sets the allowlist of subscriptions for audio streams. /// - /// You can call this method to specify the audio streams of a user that you want to subscribe to. If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. You can call this method either before or after joining a channel. The allowlist is not affected by the setting in muteRemoteAudioStream , muteAllRemoteAudioStreams and autoSubscribeAudio in ChannelMediaOptions . Once the allowlist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. + /// You can call this method to specify the audio streams of a user that you want to subscribe to. + /// If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. + /// You can call this method either before or after joining a channel. + /// The allowlist is not affected by the setting in muteRemoteAudioStream, muteAllRemoteAudioStreams and autoSubscribeAudio in ChannelMediaOptions. + /// Once the allowlist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. /// - /// * [uidList] The user ID list of users that you want to subscribe to. - /// If you want to specify the audio streams of a user for subscription, add the user ID in this list. If you want to remove a user from the allowlist, you need to call the setSubscribeAudioAllowlist method to update the user ID list; this means you only add the uid of users that you want to subscribe to in the new user ID list. + /// * [uidList] The user ID list of users that you want to subscribe to. If you want to specify the audio streams of a user for subscription, add the user ID in this list. If you want to remove a user from the allowlist, you need to call the setSubscribeAudioAllowlist method to update the user ID list; this means you only add the uid of users that you want to subscribe to in the new user ID list. /// * [uidNumber] The number of users in the user ID list. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setSubscribeAudioAllowlistEx( {required List uidList, required int uidNumber, @@ -216,15 +253,19 @@ abstract class RtcEngineEx implements RtcEngine { /// Set the blocklist of subscriptions for video streams. /// - /// You can call this method to specify the video streams of a user that you do not want to subscribe to. If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. Once the blocklist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. You can call this method either before or after joining a channel. The blocklist is not affected by the setting in muteRemoteVideoStream , muteAllRemoteVideoStreams and autoSubscribeAudio in ChannelMediaOptions . + /// You can call this method to specify the video streams of a user that you do not want to subscribe to. + /// If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. + /// Once the blocklist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. + /// You can call this method either before or after joining a channel. + /// The blocklist is not affected by the setting in muteRemoteVideoStream, muteAllRemoteVideoStreams and autoSubscribeAudio in ChannelMediaOptions. /// - /// * [uidList] The user ID list of users that you do not want to subscribe to. - /// If you want to specify the video streams of a user that you do not want to subscribe to, add the user ID of that user in this list. If you want to remove a user from the blocklist, you need to call the setSubscribeVideoBlocklist method to update the user ID list; this means you only add the uid of users that you do not want to subscribe to in the new user ID list. + /// * [uidList] The user ID list of users that you do not want to subscribe to. If you want to specify the video streams of a user that you do not want to subscribe to, add the user ID of that user in this list. If you want to remove a user from the blocklist, you need to call the setSubscribeVideoBlocklist method to update the user ID list; this means you only add the uid of users that you do not want to subscribe to in the new user ID list. /// * [uidNumber] The number of users in the user ID list. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setSubscribeVideoBlocklistEx( {required List uidList, required int uidNumber, @@ -232,14 +273,19 @@ abstract class RtcEngineEx implements RtcEngine { /// Set the allowlist of subscriptions for video streams. /// - /// You can call this method to specify the video streams of a user that you want to subscribe to. If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. Once the allowlist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. You can call this method either before or after joining a channel. The allowlist is not affected by the setting in muteRemoteVideoStream , muteAllRemoteVideoStreams and autoSubscribeAudio in ChannelMediaOptions . + /// You can call this method to specify the video streams of a user that you want to subscribe to. + /// If a user is added in the allowlist and blocklist at the same time, only the blocklist takes effect. + /// Once the allowlist of subscriptions is set, it is effective even if you leave the current channel and rejoin the channel. + /// You can call this method either before or after joining a channel. + /// The allowlist is not affected by the setting in muteRemoteVideoStream, muteAllRemoteVideoStreams and autoSubscribeAudio in ChannelMediaOptions. /// - /// * [uidList] The user ID list of users that you want to subscribe to.If you want to specify the video streams of a user for subscription, add the user ID of that user in this list. If you want to remove a user from the allowlist, you need to call the setSubscribeVideoAllowlist method to update the user ID list; this means you only add the uid of users that you want to subscribe to in the new user ID list. + /// * [uidList] The user ID list of users that you want to subscribe to. If you want to specify the video streams of a user for subscription, add the user ID of that user in this list. If you want to remove a user from the allowlist, you need to call the setSubscribeVideoAllowlist method to update the user ID list; this means you only add the uid of users that you want to subscribe to in the new user ID list. /// * [uidNumber] The number of users in the user ID list. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setSubscribeVideoAllowlistEx( {required List uidList, required int uidNumber, @@ -254,7 +300,8 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setRemoteVideoSubscriptionOptionsEx( {required int uid, required VideoSubscriptionOptions options, @@ -262,15 +309,21 @@ abstract class RtcEngineEx implements RtcEngine { /// Sets the 2D position (the position on the horizontal plane) of the remote user's voice. /// - /// This method sets the voice position and volume of a remote user. When the local user calls this method to set the voice position of a remote user, the voice difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a sense of space. This method applies to massive multiplayer online games, such as Battle Royale games. For the best voice positioning, Agora recommends using a wired headset. Call this method after joining a channel. + /// This method sets the voice position and volume of a remote user. When the local user calls this method to set the voice position of a remote user, the voice difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a sense of space. This method applies to massive multiplayer online games, such as Battle Royale games. + /// For the best voice positioning, Agora recommends using a wired headset. + /// Call this method after joining a channel. /// /// * [uid] The user ID of the remote user. - /// * [pan] The voice position of the remote user. The value ranges from -1.0 to 1.0:-1.0: The remote voice comes from the left.0.0: (Default) The remote voice comes from the front.1.0: The remote voice comes from the right. + /// * [pan] The voice position of the remote user. The value ranges from -1.0 to 1.0: + /// -1.0: The remote voice comes from the left. + /// 0.0: (Default) The remote voice comes from the front. + /// 1.0: The remote voice comes from the right. /// * [gain] The volume of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original volume of the remote user). The smaller the value, the lower the volume. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setRemoteVoicePositionEx( {required int uid, required double pan, @@ -285,7 +338,9 @@ abstract class RtcEngineEx implements RtcEngine { /// Sets the video display mode of a specified remote user. /// - /// After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees. Call this method after initializing the remote view by calling the setupRemoteVideo method. During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user. + /// After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees. + /// Call this method after initializing the remote view by calling the setupRemoteVideo method. + /// During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user. /// /// * [uid] The user ID of the remote user. /// * [renderMode] The video display mode of the remote user. See RenderModeType. @@ -293,7 +348,8 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setRemoteRenderModeEx( {required int uid, required RenderModeType renderMode, @@ -302,15 +358,19 @@ abstract class RtcEngineEx implements RtcEngine { /// Enables loopback audio capturing. /// - /// If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. This method applies to the macOS and Windows only. macOS does not support loopback audio capture of the default sound card. If you need to use this function, use a virtual sound card and pass its name to the deviceName parameter. Agora recommends using AgoraALD as the virtual sound card for audio capturing. This method only supports using one sound card for audio capturing. + /// If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end. + /// This method applies to the macOS and Windows only. + /// macOS does not support loopback audio capture of the default sound card. If you need to use this function, use a virtual sound card and pass its name to the deviceName parameter. Agora recommends using AgoraALD as the virtual sound card for audio capturing. + /// This method only supports using one sound card for audio capturing. /// /// * [connection] The connection information. See RtcConnection. - /// * [enabled] Sets whether to enable loopback audio capture:true: Enable loopback audio capturing.false: (Default) Disable loopback audio capturing. + /// * [enabled] Sets whether to enable loopback audio capture: true : Enable loopback audio capturing. false : (Default) Disable loopback audio capturing. /// * [deviceName] macOS: The device name of the virtual sound card. The default value is set to NULL, which means using AgoraALD for loopback audio capturing. /// Windows: The device name of the sound card. The default is set to NULL, which means the SDK uses the sound card of your device for loopback audio capturing. /// /// 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. + /// 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 enableLoopbackRecordingEx( {required RtcConnection connection, required bool enabled, @@ -326,14 +386,17 @@ abstract class RtcEngineEx implements RtcEngine { /// Adjusts the playback signal volume of a specified remote user. /// - /// You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. Call this method after joining a channel. The playback volume here refers to the mixed volume of a specified remote user. + /// You can call this method to adjust the playback volume of a specified remote user. To adjust the playback volume of different remote users, call the method as many times, once for each remote user. + /// Call this method after joining a channel. + /// The playback volume here refers to the mixed volume of a specified remote user. /// /// * [uid] The user ID of the remote user. /// * [volume] Audio mixing volume. The value ranges between 0 and 100. The default value is 100, which means the original volume. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 adjustUserPlaybackSignalVolumeEx( {required int uid, required int volume, @@ -346,7 +409,7 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// Returns - /// The current connection state. See ConnectionStateType . + /// The current connection state. See ConnectionStateType. Future getConnectionStateEx(RtcConnection connection); /// @nodoc @@ -357,20 +420,26 @@ 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. 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. /// /// * [config] The configurations for the data stream. See DataStreamConfig. /// * [connection] The connection information. See RtcConnection. /// /// Returns - /// ID of the created data stream, if the method call succeeds. < 0: Failure. + /// ID of the created data stream, if the method call succeeds. + /// < 0: Failure. Future createDataStreamEx( {required DataStreamConfig config, required RtcConnection connection}); /// Sends data stream messages. /// - /// After calling createDataStreamEx , you can call this method to send data stream messages to all users in the channel. The SDK has the following restrictions on this method: Up to 60 packets can be sent per second in a channel with each packet having a maximum size of 1 KB. Each client can send up to 30 KB of data per second. Each user can have up to five data streams simultaneously. A successful method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message. - /// A failed method call triggers the onStreamMessageError callback on the remote client. Ensure that you call createDataStreamEx to create a data channel before calling this method. This method applies only to the COMMUNICATION profile or to the hosts in the LIVE_BROADCASTING profile. If an audience in the LIVE_BROADCASTING profile calls this method, the audience may be switched to a host. + /// After calling createDataStreamEx, you can call this method to send data stream messages to all users in the channel. The SDK has the following restrictions on this method: + /// Up to 60 packets can be sent per second in a channel with each packet having a maximum size of 1 KB. + /// Each client can send up to 30 KB of data per second. + /// Each user can have up to five data streams simultaneously. A successful method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message. + /// A failed method call triggers the onStreamMessageError callback on the remote client. + /// Ensure that you call createDataStreamEx to create a data channel before calling this method. + /// This method applies only to the COMMUNICATION profile or to the hosts in the LIVE_BROADCASTING profile. If an audience in the LIVE_BROADCASTING profile calls this method, the audience may be switched to a host. /// /// * [streamId] The data stream ID. You can get the data stream ID by calling createDataStreamEx. /// * [data] The message to be sent. @@ -378,7 +447,8 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 sendStreamMessageEx( {required int streamId, required Uint8List data, @@ -387,14 +457,23 @@ abstract class RtcEngineEx implements RtcEngine { /// Adds a watermark image to the local video. /// - /// This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one. The watermark coordinates are dependent on the settings in the setVideoEncoderConfigurationEx method: If the orientation mode of the encoding video ( OrientationMode ) is fixed landscape mode or the adaptive landscape mode, the watermark uses the landscape orientation. If the orientation mode of the encoding video ( OrientationMode ) is fixed portrait mode or the adaptive portrait mode, the watermark uses the portrait orientation. When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfigurationEx method; otherwise, the watermark image will be cropped. Ensure that you have called enableVideo before calling this method. This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray. If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings. If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member to set whether or not the watermark is visible in the preview. If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. + /// This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one. The watermark coordinates are dependent on the settings in the setVideoEncoderConfigurationEx method: + /// If the orientation mode of the encoding video (OrientationMode) is fixed landscape mode or the adaptive landscape mode, the watermark uses the landscape orientation. + /// If the orientation mode of the encoding video (OrientationMode) is fixed portrait mode or the adaptive portrait mode, the watermark uses the portrait orientation. + /// When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfigurationEx method; otherwise, the watermark image will be cropped. + /// Ensure that you have called enableVideo before calling this method. + /// This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray. + /// If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings. + /// If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member to set whether or not the watermark is visible in the preview. + /// If you have enabled the mirror mode for the local video, the watermark on the local video is also mirrored. To avoid mirroring the watermark, Agora recommends that you do not use the mirror and watermark functions for the local video at the same time. You can implement the watermark function in your application layer. /// /// * [watermarkUrl] The local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path. /// * [options] The options of the watermark image to be added. See WatermarkOptions. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 addVideoWatermarkEx( {required String watermarkUrl, required WatermarkOptions options, @@ -405,7 +484,8 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 clearVideoWatermarkEx(RtcConnection connection); /// Agora supports reporting and analyzing customized messages. @@ -423,13 +503,16 @@ abstract class RtcEngineEx implements RtcEngine { /// /// This method enables the SDK to regularly report the volume information to the app of the local user who sends a stream and remote users (three users at most) whose instantaneous volumes are the highest. Once you call this method and users send streams in the channel, the SDK triggers the onAudioVolumeIndication callback at the time interval set in this method. /// - /// * [interval] Sets the time interval between two consecutive volume indications:≤ 0: Disables the volume indication.> 0: Time interval (ms) between two consecutive volume indications. The lowest value is 50. + /// * [interval] Sets the time interval between two consecutive volume indications: + /// ≤ 0: Disables the volume indication. + /// > 0: Time interval (ms) between two consecutive volume indications. The lowest value is 50. /// * [smooth] The smoothing factor that sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The recommended value is 3. The greater the value, the more sensitive the indicator. - /// * [reportVad] true: Enables the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback reports the voice activity status of the local user.false: (Default) Disables the voice activity detection of the local user. Once it is disabled, the vad parameter of the onAudioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user. + /// * [reportVad] true : Enables the voice activity detection of the local user. Once it is enabled, the vad parameter of the onAudioVolumeIndication callback reports the voice activity status of the local user. false : (Default) Disables the voice activity detection of the local user. Once it is disabled, the vad parameter of the onAudioVolumeIndication callback does not report the voice activity status of the local user, except for the scenario where the engine automatically detects the voice activity of the local user. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 enableAudioVolumeIndicationEx( {required int interval, required int smooth, @@ -438,13 +521,17 @@ 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. 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. + /// Ensure that you enable the Media Push service before using this function. See Enable Media Push. + /// 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. /// /// * [url] The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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. /// -2: The URL is null or the string length is 0. /// -7: The SDK is not initialized before calling this method. /// -19: The Media Push URL is already in use, use another URL instead. @@ -453,14 +540,22 @@ abstract class RtcEngineEx implements 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. 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 stopRtmpStreamEx 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 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. + /// 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 stopRtmpStreamEx first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. /// /// * [url] The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. /// * [transcoding] The transcoding configuration for Media Push. See LiveTranscoding. /// * [connection] The connection information. See RtcConnection. /// /// 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. -2: The URL is null or the string length is 0. -7: The SDK is not initialized before calling this method. -19: The Media Push URL is already in use, use another URL instead. + /// 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. + /// -2: The URL is null or the string length is 0. + /// -7: The SDK is not initialized before calling this method. + /// -19: The Media Push URL is already in use, use another URL instead. Future startRtmpStreamWithTranscodingEx( {required String url, required LiveTranscoding transcoding, @@ -468,63 +563,89 @@ abstract class RtcEngineEx implements RtcEngine { /// Updates the transcoding configuration. /// - /// Agora recommends that you use the server-side Media Push function. After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the onTranscodingUpdated callback after the transcoding configuration is updated. + /// Agora recommends that you use the server-side Media Push function. After you start pushing media streams to CDN with transcoding, you can dynamically update the transcoding configuration according to the scenario. The SDK triggers the onTranscodingUpdated callback after the transcoding configuration is updated. /// /// * [transcoding] The transcoding configuration for Media Push. See LiveTranscoding. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 updateRtmpTranscodingEx( {required LiveTranscoding transcoding, required RtcConnection connection}); /// Stops pushing media streams to a CDN. /// - /// Agora recommends that you use the server-side Media Push function. You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing 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. + /// Agora recommends that you use the server-side Media Push function. You can call this method to stop the live stream on the specified CDN address. This method can stop pushing media streams to only one CDN address at a time, so if you need to stop pushing 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. /// /// * [url] The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported. /// /// 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. + /// 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 stopRtmpStreamEx( {required String url, required RtcConnection connection}); /// Starts relaying media streams across channels or updates channels for media relay. /// - /// The first successful call to this method starts relaying media streams from the source channel to the destination channels. To relay the media stream to other channels, or exit one of the current media relays, you can call this method again to update the destination channels. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback, and this callback returns the state of the media stream relay. Common states are as follows: If the onChannelMediaRelayStateChanged callback returns relayStateRunning (2) and relayOk (0), it means that the SDK starts relaying media streams from the source channel to the destination channel. If the onChannelMediaRelayStateChanged callback returns relayStateFailure (3), an exception occurs during the media stream relay. Call this method after joining the channel. This method takes effect only when you are a host in a live streaming channel. The relaying media streams across channels function needs to be enabled by contacting . Agora does not support string user accounts in this API. + /// The first successful call to this method starts relaying media streams from the source channel to the destination channels. To relay the media stream to other channels, or exit one of the current media relays, you can call this method again to update the destination channels. This feature supports relaying media streams to a maximum of six destination channels. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback, and this callback returns the state of the media stream relay. Common states are as follows: + /// If the onChannelMediaRelayStateChanged callback returns relayStateRunning (2) and relayOk (0), it means that the SDK starts relaying media streams from the source channel to the destination channel. + /// If the onChannelMediaRelayStateChanged callback returns relayStateFailure (3), an exception occurs during the media stream relay. + /// Call this method after joining the channel. + /// This method takes effect only when you are a host in a live streaming channel. + /// The relaying media streams across channels function needs to be enabled by contacting. + /// Agora does not support string user accounts in this API. /// /// * [configuration] The configuration of the media stream relay. See ChannelMediaRelayConfiguration. /// * [connection] The connection information. See RtcConnection. /// /// 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: A general error occurs (no specified reason). -2: The parameter is invalid. -7: The method call was rejected. It may be because the SDK has not been initialized successfully, or the user role is not an host. -8: Internal state error. Probably because the user is not an audience member. + /// 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: A general error occurs (no specified reason). + /// -2: The parameter is invalid. + /// -7: The method call was rejected. It may be because the SDK has not been initialized successfully, or the user role is not a host. + /// -8: Internal state error. Probably because the user is not a broadcaster. Future startOrUpdateChannelMediaRelayEx( {required ChannelMediaRelayConfiguration configuration, required RtcConnection connection}); /// Starts relaying media streams across channels. This method can be used to implement scenarios such as co-host across channels. /// - /// Deprecated: This method is deprecated. Use startOrUpdateChannelMediaRelayEx instead. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay. If the onChannelMediaRelayStateChanged callback returns relayStateRunning (2) and relayOk (0), and the onChannelMediaRelayEvent callback returns relayEventPacketSentToDestChannel (4), it means that the SDK starts relaying media streams between the source channel and the target channel. If the onChannelMediaRelayStateChanged callback returns relayStateFailure (3), an exception occurs during the media stream relay. Call this method after joining the channel. This method takes effect only when you are a host in a live streaming channel. After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelayEx method to quit the current relay. The relaying media streams across channels function needs to be enabled by contacting . Agora does not support string user accounts in this API. + /// Deprecated: This method is deprecated. Use startOrUpdateChannelMediaRelayEx instead. After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay. + /// If the onChannelMediaRelayStateChanged callback returns relayStateRunning (2) and relayOk (0), and the onChannelMediaRelayEvent callback returns relayEventPacketSentToDestChannel (4), it means that the SDK starts relaying media streams between the source channel and the target channel. + /// If the onChannelMediaRelayStateChanged callback returns relayStateFailure (3), an exception occurs during the media stream relay. + /// Call this method after joining the channel. + /// This method takes effect only when you are a host in a live streaming channel. + /// After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelayEx method to quit the current relay. + /// The relaying media streams across channels function needs to be enabled by contacting. + /// Agora does not support string user accounts in this API. /// /// * [configuration] The configuration of the media stream relay. See ChannelMediaRelayConfiguration. /// * [connection] The connection information. See RtcConnection. /// /// 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: A general error occurs (no specified reason). -2: The parameter is invalid. -7: The method call was rejected. It may be because the SDK has not been initialized successfully, or the user role is not an host. -8: Internal state error. Probably because the user is not an audience member. + /// 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: A general error occurs (no specified reason). + /// -2: The parameter is invalid. + /// -7: The method call was rejected. It may be because the SDK has not been initialized successfully, or the user role is not a host. + /// -8: Internal state error. Probably because the user is not a broadcaster. Future startChannelMediaRelayEx( {required ChannelMediaRelayConfiguration configuration, required RtcConnection connection}); /// Updates the channels for media stream relay. /// - /// Deprecated: This method is deprecated. Use startOrUpdateChannelMediaRelayEx instead. After the media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call this method. After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the relayEventPacketUpdateDestChannel (7) state code. Call the method after successfully calling the startChannelMediaRelayEx method and receiving onChannelMediaRelayStateChanged ( relayStateRunning , relayOk ) ; otherwise, the method call fails. + /// Deprecated: This method is deprecated. Use startOrUpdateChannelMediaRelayEx instead. After the media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call this method. After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the relayEventPacketUpdateDestChannel (7) state code. Call the method after successfully calling the startChannelMediaRelayEx method and receiving onChannelMediaRelayStateChanged (relayStateRunning, relayOk); otherwise, the method call fails. /// /// * [configuration] The configuration of the media stream relay. See ChannelMediaRelayConfiguration. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 updateChannelMediaRelayEx( {required ChannelMediaRelayConfiguration configuration, required RtcConnection connection}); @@ -536,27 +657,30 @@ abstract class RtcEngineEx implements RtcEngine { /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 stopChannelMediaRelayEx(RtcConnection connection); /// Pauses the media stream relay to all target channels. /// - /// After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all target channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay . Call this method after startOrUpdateChannelMediaRelayEx . + /// After the cross-channel media stream relay starts, you can call this method to pause relaying media streams to all target channels; after the pause, if you want to resume the relay, call resumeAllChannelMediaRelay. Call this method after startOrUpdateChannelMediaRelayEx. /// /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 pauseAllChannelMediaRelayEx(RtcConnection connection); /// Resumes the media stream relay to all target channels. /// - /// After calling the pauseAllChannelMediaRelayEx method, you can call this method to resume relaying media streams to all destination channels. Call this method after pauseAllChannelMediaRelayEx . + /// After calling the pauseAllChannelMediaRelayEx method, you can call this method to resume relaying media streams to all destination channels. Call this method after pauseAllChannelMediaRelayEx. /// /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 resumeAllChannelMediaRelayEx(RtcConnection connection); /// @nodoc @@ -569,16 +693,17 @@ abstract class RtcEngineEx implements RtcEngine { /// Enables or disables dual-stream mode on the sender side. /// - /// 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. + /// 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. /// - /// * [enabled] Whether to enable dual-stream mode: - /// true: Enable dual-stream mode. - /// false: (Default) Disable dual-stream mode. + /// * [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. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 enableDualStreamModeEx( {required bool enabled, required SimulcastStreamConfig streamConfig, @@ -586,14 +711,18 @@ abstract class RtcEngineEx implements RtcEngine { /// Sets the dual-stream mode on the sender side. /// - /// The SDK enables the low-quality video stream auto mode on the sender by default, which is equivalent to calling this method and setting the mode to autoSimulcastStream . 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). 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 ) . When calling this method and setting mode to enableSimulcastStream , it has the same effect as enableDualStreamModeEx ( 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. + /// The SDK enables the low-quality video stream auto mode on the sender by default, which is equivalent to calling this method and setting the mode to autoSimulcastStream. 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). 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). + /// When calling this method and setting mode to enableSimulcastStream, it has the same effect as enableDualStreamModeEx (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. /// /// * [mode] The mode in which the video stream is sent. See SimulcastStreamMode. /// * [streamConfig] The configuration of the low-quality video stream. See SimulcastStreamConfig. /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 setDualStreamModeEx( {required SimulcastStreamMode mode, required SimulcastStreamConfig streamConfig, @@ -608,7 +737,10 @@ abstract class RtcEngineEx implements RtcEngine { /// Takes a snapshot of a video stream. /// - /// The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successfully taken, as well as the details for that snapshot. This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path. Call this method after the joinChannelEx method. This method takes a snapshot of the published video stream specified in ChannelMediaOptions . If the user's video has been preprocessed, for example, watermarked or beautified, the resulting snapshot includes the pre-processing effect. + /// The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successfully taken, as well as the details for that snapshot. This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path. + /// Call this method after the joinChannelEx method. + /// When used for local video snapshots, this method takes a snapshot for the video streams specified in ChannelMediaOptions. + /// If the user's video has been preprocessed, for example, watermarked or beautified, the resulting snapshot includes the pre-processing effect. /// /// * [connection] The connection information. See RtcConnection. /// * [uid] The user ID. Set uid as 0 if you want to take a snapshot of the local user's video. @@ -616,11 +748,11 @@ abstract class RtcEngineEx implements RtcEngine { /// Windows: C:\Users\\AppData\Local\Agora\\example.jpg /// iOS: /App Sandbox/Library/Caches/example.jpg /// macOS: ～/Library/Logs/example.jpg - /// Android: /storage/emulated/0/Android/data//files/example.jpg - /// Ensure that the path you specify exists and is writable. + /// Android: /storage/emulated/0/Android/data//files/example.jpg Ensure that the path you specify exists and is writable. /// /// 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. + /// 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 takeSnapshotEx( {required RtcConnection connection, required int uid, @@ -628,11 +760,13 @@ abstract class RtcEngineEx implements RtcEngine { /// Enables tracing the video frame rendering process. /// - /// By default, the SDK starts tracing the video rendering event automatically when the local user successfully joins the channel. You can call this method at an appropriate time according to the actual application scenario to customize the tracing process. After the local user leaves the current channel, the SDK automatically resets the time point to the next time when the user successfully joins the channel. The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is successfully called and reports information about the event through the onVideoRenderingTracingResult callback. + /// By default, the SDK starts tracing the video rendering event automatically when the local user successfully joins the channel. You can call this method at an appropriate time according to the actual application scenario to customize the tracing process. + /// After the local user leaves the current channel, the SDK automatically resets the time point to the next time when the user successfully joins the channel. The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is successfully called and reports information about the event through the onVideoRenderingTracingResult callback. /// /// * [connection] The connection information. See RtcConnection. /// /// 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. + /// 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 startMediaRenderingTracingEx(RtcConnection connection); } diff --git a/lib/src/agora_spatial_audio.dart b/lib/src/agora_spatial_audio.dart index fd0728174..d680db82e 100644 --- a/lib/src/agora_spatial_audio.dart +++ b/lib/src/agora_spatial_audio.dart @@ -70,7 +70,11 @@ class SpatialAudioZone { @JsonKey(name: 'upLength') final double? upLength; - /// The sound attenuation coefficient when users within the sound insulation area communicate with external users. The value range is [0,1]. The values are as follows:0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance.(0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment.0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the audioAttenuation parameter.(0.5,1]: Strong attenuation mode (default value is 1), that is, the volume and timbre attenuate rapidly during propagation. + /// The sound attenuation coefficient when users within the sound insulation area communicate with external users. The value range is [0,1]. The values are as follows: + /// 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance. + /// (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment. + /// 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the audioAttenuation parameter. + /// (0.5,1]: Strong attenuation mode (default value is 1), that is, the volume and timbre attenuate rapidly during propagation. @JsonKey(name: 'audioAttenuation') final double? audioAttenuation; @@ -84,11 +88,11 @@ class SpatialAudioZone { /// This class contains some of the APIs in the LocalSpatialAudioEngine class. /// -/// The LocalSpatialAudioEngine class inherits from BaseSpatialAudioEngine . +/// The LocalSpatialAudioEngine class inherits from BaseSpatialAudioEngine. abstract class BaseSpatialAudioEngine { /// Destroys BaseSpatialAudioEngine. /// - /// This method releases all resources under BaseSpatialAudioEngine . When the user does not need to use the spatial audio effect, you can call this method to release resources for other operations. After calling this method, you can no longer use any of the APIs under BaseSpatialAudioEngine . Call this method before the release method under RtcEngine . + /// This method releases all resources under BaseSpatialAudioEngine. When the user does not need to use the spatial audio effect, you can call this method to release resources for other operations. After calling this method, you can no longer use any of the APIs under BaseSpatialAudioEngine. Call this method before the release method under RtcEngine. Future release(); /// Sets the maximum number of streams that a user can receive in a specified audio reception range. @@ -98,7 +102,8 @@ abstract class BaseSpatialAudioEngine { /// * [maxCount] The maximum number of streams that a user can receive within a specified audio reception range. The value of this parameter should be ≤ 16, and the default value is 10. /// /// 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. + /// 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 setMaxAudioRecvCount(int maxCount); /// Sets the audio reception range of the local user. @@ -108,22 +113,24 @@ abstract class BaseSpatialAudioEngine { /// * [range] The maximum audio reception range. The unit is meters. The value of this parameter must be greater than 0, and the default value is 20. /// /// 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. + /// 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 setAudioRecvRange(double range); /// Sets the length (in meters) of the game engine distance per unit. /// /// In a game engine, the unit of distance is customized, while in the Agora spatial audio algorithm, distance is measured in meters. By default, the SDK converts the game engine distance per unit to one meter. You can call this method to convert the game engine distance per unit to a specified number of meters. /// - /// * [unit] The number of meters that the game engine distance per unit is equal to. The value of this parameter must be greater than 0.00, and the default value is 1.00. For example, setting unit as 2.00 means the game engine distance per unit equals 2 meters.The larger the value is, the faster the sound heard by the local user attenuates when the remote user moves far away from the local user. + /// * [unit] The number of meters that the game engine distance per unit is equal to. The value of this parameter must be greater than 0.00, and the default value is 1.00. For example, setting unit as 2.00 means the game engine distance per unit equals 2 meters. The larger the value is, the faster the sound heard by the local user attenuates when the remote user moves far away from the local user. /// /// 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. + /// 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 setDistanceUnit(double unit); /// Updates the spatial position of the local user. /// - /// Under the LocalSpatialAudioEngine class, this method needs to be used with updateRemotePosition . The SDK calculates the relative position between the local and remote users according to this method and the parameter settings in updateRemotePosition , and then calculates the user's spatial audio effect parameters. + /// Under the LocalSpatialAudioEngine class, this method needs to be used with updateRemotePosition. The SDK calculates the relative position between the local and remote users according to this method and the parameter settings in updateRemotePosition, and then calculates the user's spatial audio effect parameters. /// /// * [position] The coordinates in the world coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn. /// * [axisForward] The unit vector of the x axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn. @@ -131,7 +138,8 @@ abstract class BaseSpatialAudioEngine { /// * [axisUp] The unit vector of the z axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn. /// /// 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. + /// 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 updateSelfPosition( {required List position, required List axisForward, @@ -154,7 +162,8 @@ abstract class BaseSpatialAudioEngine { /// * [positionInfo] The spatial position of the media player. See RemoteVoicePositionInfo. /// /// 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. + /// 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 updatePlayerPositionInfo( {required int playerId, required RemoteVoicePositionInfo positionInfo}); @@ -163,44 +172,63 @@ abstract class BaseSpatialAudioEngine { /// Stops or resumes publishing the local audio stream. /// - /// This method does not affect any ongoing audio recording, because it does not disable the audio capture device. Call this method after joinChannel . When using the spatial audio effect, if you need to set whether to stop subscribing to the audio stream of a specified user, Agora recommends calling this method instead of the muteLocalAudioStream method in RtcEngine . A successful call of this method triggers the onUserMuteAudio and onRemoteAudioStateChanged callbacks on the remote client. + /// This method does not affect any ongoing audio recording, because it does not disable the audio capture device. + /// Call this method after joinChannel. + /// When using the spatial audio effect, if you need to set whether to stop subscribing to the audio stream of a specified user, Agora recommends calling this method instead of the muteLocalAudioStream method in RtcEngine. + /// A successful call of this method triggers the onUserMuteAudio and onRemoteAudioStateChanged callbacks on the remote client. /// - /// * [mute] Whether to stop publishing the local audio stream:true: Stop publishing the local audio stream.false: Publish the local audio stream. + /// * [mute] Whether to stop publishing the local audio stream: true : Stop publishing the local audio stream. false : Publish the local audio stream. /// /// 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. + /// 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 muteLocalAudioStream(bool mute); /// Stops or resumes subscribing to the audio streams of all remote users. /// - /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. Call this method after joinChannel . When using the spatial audio effect, if you need to set whether to stop subscribing to the audio streams of all remote users, Agora recommends calling this method instead of the muteAllRemoteAudioStreams method in RtcEngine . After calling this method, you need to call updateSelfPosition and updateRemotePosition to update the spatial location of the local user and the remote user; otherwise, the settings in this method do not take effect. + /// After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. + /// Call this method after joinChannel. + /// When using the spatial audio effect, if you need to set whether to stop subscribing to the audio streams of all remote users, Agora recommends calling this method instead of the muteAllRemoteAudioStreams method in RtcEngine. + /// After calling this method, you need to call updateSelfPosition and updateRemotePosition to update the spatial location of the local user and the remote user; otherwise, the settings in this method do not take effect. /// - /// * [mute] Whether to stop subscribing to the audio streams of all remote users:true: Stop subscribing to the audio streams of all remote users.false: Subscribe to the audio streams of all remote users. + /// * [mute] Whether to stop subscribing to the audio streams of all remote users: true : Stop subscribing to the audio streams of all remote users. false : Subscribe to the audio streams of all remote users. /// /// 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. + /// 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 muteAllRemoteAudioStreams(bool mute); /// Sets the sound insulation area. /// - /// In virtual interactive scenarios, you can use this method to set the sound insulation area and sound attenuation coefficient. When the sound source (which can be the user or the media player) and the listener belong to the inside and outside of the sound insulation area, they can experience the attenuation effect of sound similar to the real environment when it encounters a building partition. When the sound source and the listener belong to the inside and outside of the sound insulation area, the sound attenuation effect is determined by the sound attenuation coefficient in SpatialAudioZone . If the user or media player is in the same sound insulation area, it is not affected by SpatialAudioZone , and the sound attenuation effect is determined by the attenuation parameter in setPlayerAttenuation or setRemoteAudioAttenuation . If you do not call setPlayerAttenuation or setRemoteAudioAttenuation , the default sound attenuation coefficient of the SDK is 0.5, which simulates the attenuation of the sound in the real environment. If the sound source and the receiver belong to two sound insulation areas, the receiver cannot hear the sound source. If this method is called multiple times, the last sound insulation area set takes effect. + /// In virtual interactive scenarios, you can use this method to set the sound insulation area and sound attenuation coefficient. When the sound source (which can be the user or the media player) and the listener belong to the inside and outside of the sound insulation area, they can experience the attenuation effect of sound similar to the real environment when it encounters a building partition. + /// When the sound source and the listener belong to the inside and outside of the sound insulation area, the sound attenuation effect is determined by the sound attenuation coefficient in SpatialAudioZone. + /// If the user or media player is in the same sound insulation area, it is not affected by SpatialAudioZone, and the sound attenuation effect is determined by the attenuation parameter in setPlayerAttenuation or setRemoteAudioAttenuation. If you do not call setPlayerAttenuation or setRemoteAudioAttenuation, the default sound attenuation coefficient of the SDK is 0.5, which simulates the attenuation of the sound in the real environment. + /// If the sound source and the receiver belong to two sound insulation areas, the receiver cannot hear the sound source. If this method is called multiple times, the last sound insulation area set takes effect. /// - /// * [zones] Sound insulation area settings. See SpatialAudioZone. + /// * [zones] Sound insulation area settings. See SpatialAudioZone. On the Windows platform, it is necessary to ensure that the number of members in the zones array is equal to the value of zoneCount; otherwise, it may cause a crash. /// * [zoneCount] The number of sound insulation areas. /// /// 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. + /// 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 setZones( {required List zones, required int zoneCount}); /// Sets the sound attenuation properties of the media player. /// /// * [playerId] The ID of the media player. - /// * [attenuation] The sound attenuation coefficient of the remote user or media player. The value range is [0,1]. The values are as follows:0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance.(0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment.0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the speaker_attenuation parameter.(0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process. - /// * [forceSet] Whether to force the sound attenuation effect of the media player:true: Force attenuation to set the attenuation of the media player. At this time, the attenuation coefficient of the sound insulation are set in the audioAttenuation in the SpatialAudioZone does not take effect for the media player.false: Do not force attenuation to set the sound attenuation effect of the media player, as shown in the following two cases.If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the audioAttenuation in SpatialAudioZone.If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by attenuation in this method. + /// * [attenuation] The sound attenuation coefficient of the remote user or media player. The value range is [0,1]. The values are as follows: + /// 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance. + /// (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment. + /// 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the speaker_attenuation parameter. + /// (0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process. + /// * [forceSet] Whether to force the sound attenuation effect of the media player: true : Force attenuation to set the attenuation of the media player. At this time, the attenuation coefficient of the sound insulation are set in the audioAttenuation in the SpatialAudioZone does not take effect for the media player. false : Do not force attenuation to set the sound attenuation effect of the media player, as shown in the following two cases. + /// If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the audioAttenuation in SpatialAudioZone. + /// If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by attenuation in this method. /// /// 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. + /// 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 setPlayerAttenuation( {required int playerId, required double attenuation, @@ -208,37 +236,42 @@ abstract class BaseSpatialAudioEngine { /// Stops or resumes subscribing to the audio stream of a specified user. /// - /// Call this method after joinChannel . When using the spatial audio effect, if you need to set whether to stop subscribing to the audio stream of a specified user, Agora recommends calling this method instead of the muteRemoteAudioStream method in RtcEngine . + /// Call this method after joinChannel. + /// When using the spatial audio effect, if you need to set whether to stop subscribing to the audio stream of a specified user, Agora recommends calling this method instead of the muteRemoteAudioStream method in RtcEngine. /// /// * [uid] The user ID. This parameter must be the same as the user ID passed in when the user joined the channel. - /// * [mute] Whether to subscribe to the specified remote user's audio stream.true: Stop subscribing to the audio stream of the specified user.false: (Default) Subscribe to the audio stream of the specified user. The SDK decides whether to subscribe according to the distance between the local user and the remote user. + /// * [mute] Whether to subscribe to the specified remote user's audio stream. true : Stop subscribing to the audio stream of the specified user. false : (Default) Subscribe to the audio stream of the specified user. The SDK decides whether to subscribe according to the distance between the local user and the remote user. /// /// 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. + /// 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 muteRemoteAudioStream({required int uid, required bool mute}); } /// This class calculates user positions through the SDK to implement the spatial audio effect. /// -/// This class inherits from BaseSpatialAudioEngine . Before calling other APIs in this class, you need to call the initialize method to initialize this class. +/// This class inherits from BaseSpatialAudioEngine. Before calling other APIs in this class, you need to call the initialize method to initialize this class. abstract class LocalSpatialAudioEngine implements BaseSpatialAudioEngine { /// Initializes LocalSpatialAudioEngine. /// - /// Before calling other methods of the LocalSpatialAudioEngine class, you need to call this method to initialize LocalSpatialAudioEngine . The SDK supports creating only one LocalSpatialAudioEngine instance for an app. + /// Before calling other methods of the LocalSpatialAudioEngine class, you need to call this method to initialize LocalSpatialAudioEngine. + /// The SDK supports creating only one LocalSpatialAudioEngine instance for an app. /// /// 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. + /// 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 initialize(); /// Updates the spatial position of the specified remote user. /// - /// After successfully calling this method, the SDK calculates the spatial audio parameters based on the relative position of the local and remote user. Call this method after joinChannel . + /// After successfully calling this method, the SDK calculates the spatial audio parameters based on the relative position of the local and remote user. Call this method after joinChannel. /// /// * [uid] The user ID. This parameter must be the same as the user ID passed in when the user joined the channel. /// * [posInfo] The spatial position of the remote user. See RemoteVoicePositionInfo. /// /// 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. + /// 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 updateRemotePosition( {required int uid, required RemoteVoicePositionInfo posInfo}); @@ -255,7 +288,8 @@ abstract class LocalSpatialAudioEngine implements BaseSpatialAudioEngine { /// * [uid] The user ID. This parameter must be the same as the user ID passed in when the user joined the channel. /// /// 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. + /// 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 removeRemotePosition(int uid); /// @nodoc @@ -267,7 +301,8 @@ abstract class LocalSpatialAudioEngine implements BaseSpatialAudioEngine { /// After successfully calling this method, the local user no longer hears any remote users. After leaving the channel, to avoid wasting resources, you can also call this method to delete the spatial positions of all remote users. /// /// 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. + /// 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 clearRemotePositions(); /// @nodoc @@ -281,13 +316,13 @@ abstract class LocalSpatialAudioEngine implements BaseSpatialAudioEngine { /// (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment. /// 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the speaker_attenuation parameter. /// (0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process. - /// * [forceSet] Whether to force the user's sound attenuation effect:true: Force attenuation to set the sound attenuation of the user. At this time, the attenuation coefficient of the sound insulation area set in the audioAttenuation of the SpatialAudioZone does not take effect for the user. + /// * [forceSet] Whether to force the user's sound attenuation effect: true : Force attenuation to set the sound attenuation of the user. At this time, the attenuation coefficient of the sound insulation area set in the audioAttenuation of the SpatialAudioZone does not take effect for the user. /// If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the audioAttenuation in SpatialAudioZone. - /// If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by attenuation in this method. - /// false: Do not force attenuation to set the user's sound attenuation effect, as shown in the following two cases. + /// If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by attenuation in this method. false : Do not force attenuation to set the user's sound attenuation effect, as shown in the following two cases. /// /// 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. + /// 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 setRemoteAudioAttenuation( {required int uid, required double attenuation, required bool forceSet}); } diff --git a/lib/src/audio_device_manager.dart b/lib/src/audio_device_manager.dart index f0ae17c7f..83e4de364 100644 --- a/lib/src/audio_device_manager.dart +++ b/lib/src/audio_device_manager.dart @@ -29,7 +29,8 @@ abstract class AudioDeviceManager { /// This method is for Windows and macOS only. /// /// Returns - /// Success: Returns an AudioDeviceInfo array, which includes all the audio playback devices. Failure: An empty array. + /// Success: Returns an AudioDeviceInfo array, which includes all the audio playback devices. + /// Failure: An empty array. Future> enumeratePlaybackDevices(); /// Enumerates the audio capture devices. @@ -37,7 +38,8 @@ abstract class AudioDeviceManager { /// This method is for Windows and macOS only. /// /// Returns - /// Success: An AudioDeviceInfo array, which includes all the audio capture devices. Failure: An empty array. + /// Success: An AudioDeviceInfo array, which includes all the audio capture devices. + /// Failure: An empty array. Future> enumerateRecordingDevices(); /// Sets the audio playback device. @@ -47,7 +49,8 @@ abstract class AudioDeviceManager { /// * [deviceId] The ID of the specified audio playback device. You can get the device ID by calling enumeratePlaybackDevices. Connecting or disconnecting the audio device does not change the value of deviceId. /// /// 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. + /// 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 setPlaybackDevice(String deviceId); /// Retrieves the audio playback device associated with the device ID. @@ -79,7 +82,8 @@ abstract class AudioDeviceManager { /// * [deviceId] The ID of the audio capture device. You can get the Device ID by calling enumerateRecordingDevices. Connecting or disconnecting the audio device does not change the value of deviceId. /// /// 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. + /// 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 setRecordingDevice(String deviceId); /// Gets the current audio recording device. @@ -105,7 +109,8 @@ abstract class AudioDeviceManager { /// * [volume] The volume of the audio recording device. The value range is [0,255]. 0 means no sound, 255 means maximum 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. + /// 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 setRecordingDeviceVolume(int volume); /// @nodoc @@ -113,12 +118,16 @@ abstract class AudioDeviceManager { /// Sets the loopback device. /// - /// The SDK uses the current playback device as the loopback device by default. If you want to specify another audio device as the loopback device, call this method, and set deviceId to the loopback device you want to specify. You can call this method to change the audio route currently being used, but this does not change the default audio route. For example, if the default audio route is microphone, you call this method to set the audio route as a sound card before joinging a channel and then start a device test, the SDK conducts device test on the sound card. After the device test is completed and you join a channel, the SDK still uses the microphone for audio capturing. This method is for Windows and macOS only. The scenarios where this method is applicable are as follows: Use app A to play music through a Bluetooth headset; when using app B for a video conference, play through the speakers. If the loopback device is set as the Bluetooth headset, the SDK publishes the music in app A to the remote end. If the loopback device is set as the speaker, the SDK does not publish the music in app A to the remote end. If you set the loopback device as the Bluetooth headset, and then use a wired headset to play the music in app A, you need to call this method again, set the loopback device as the wired headset, and the SDK continues to publish the music in app A to remote end. + /// The SDK uses the current playback device as the loopback device by default. If you want to specify another audio device as the loopback device, call this method, and set deviceId to the loopback device you want to specify. You can call this method to change the audio route currently being used, but this does not change the default audio route. For example, if the default audio route is microphone, you call this method to set the audio route as a sound card before joinging a channel and then start a device test, the SDK conducts device test on the sound card. After the device test is completed and you join a channel, the SDK still uses the microphone for audio capturing. This method is for Windows and macOS only. The scenarios where this method is applicable are as follows: Use app A to play music through a Bluetooth headset; when using app B for a video conference, play through the speakers. + /// If the loopback device is set as the Bluetooth headset, the SDK publishes the music in app A to the remote end. + /// If the loopback device is set as the speaker, the SDK does not publish the music in app A to the remote end. + /// If you set the loopback device as the Bluetooth headset, and then use a wired headset to play the music in app A, you need to call this method again, set the loopback device as the wired headset, and the SDK continues to publish the music in app A to remote end. /// - /// * [deviceId] Specifies the loopback device of the SDK. You can get the device ID by calling enumeratePlaybackDevices. Connecting or disconnecting the audio device does not change the value of deviceId.The maximum length is MaxDeviceIdLengthType. + /// * [deviceId] Specifies the loopback device of the SDK. You can get the device ID by calling enumeratePlaybackDevices. Connecting or disconnecting the audio device does not change the value of deviceId. The maximum length is MaxDeviceIdLengthType. /// /// 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. + /// 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 setLoopbackDevice(String deviceId); /// Gets the current loopback device. @@ -143,86 +152,113 @@ abstract class AudioDeviceManager { /// Starts the audio playback device test. /// - /// This method tests whether the audio playback device works properly. Once a user starts the test, the SDK plays an audio file specified by the user. If the user can hear the audio, the playback device works properly. After calling this method, the SDK triggers the onAudioVolumeIndication callback every 100 ms, reporting uid = 1 and the volume information of the playback device. Ensure that you call this method before joining a channel. This method is for Windows and macOS only. + /// This method tests whether the audio playback device works properly. Once a user starts the test, the SDK plays an audio file specified by the user. If the user can hear the audio, the playback device works properly. After calling this method, the SDK triggers the onAudioVolumeIndication callback every 100 ms, reporting uid = 1 and the volume information of the playback device. + /// Ensure that you call this method before joining a channel. + /// This method is for Windows and macOS only. /// - /// * [testAudioFilePath] The path of the audio file. The data format is string in UTF-8.Supported file formats: wav, mp3, m4a, and aac.Supported file sample rates: 8000, 16000, 32000, 44100, and 48000 Hz. + /// * [testAudioFilePath] The path of the audio file. The data format is string in UTF-8. + /// Supported file formats: wav, mp3, m4a, and aac. + /// Supported file sample rates: 8000, 16000, 32000, 44100, and 48000 Hz. /// /// 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. + /// 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 startPlaybackDeviceTest(String testAudioFilePath); /// Stops the audio playback device test. /// - /// This method stops the audio playback device test. You must call this method to stop the test after calling the startPlaybackDeviceTest method. This method is for Windows and macOS only. Ensure that you call this method before joining a channel. + /// This method stops the audio playback device test. You must call this method to stop the test after calling the startPlaybackDeviceTest method. + /// This method is for Windows and macOS only. + /// Ensure that you call this method before joining a channel. /// /// 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. + /// 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 stopPlaybackDeviceTest(); /// Starts the audio capture device test. /// - /// This method tests whether the audio capture device works properly. After calling this method, the SDK triggers the onAudioVolumeIndication callback at the time interval set in this method, which reports uid = 0 and the volume information of the capturing device. This method is for Windows and macOS only. Ensure that you call this method before joining a channel. + /// This method tests whether the audio capture device works properly. After calling this method, the SDK triggers the onAudioVolumeIndication callback at the time interval set in this method, which reports uid = 0 and the volume information of the capturing device. + /// This method is for Windows and macOS only. + /// Ensure that you call this method before joining a channel. /// /// * [indicationInterval] The time interval (ms) at which the SDK triggers the onAudioVolumeIndication callback. Agora recommends setting a value greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive the onAudioVolumeIndication callback. /// /// 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. + /// 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 startRecordingDeviceTest(int indicationInterval); /// Stops the audio capture device test. /// - /// This method stops the audio capture device test. You must call this method to stop the test after calling the startRecordingDeviceTest method. This method is for Windows and macOS only. Ensure that you call this method before joining a channel. + /// This method stops the audio capture device test. You must call this method to stop the test after calling the startRecordingDeviceTest method. + /// This method is for Windows and macOS only. + /// Ensure that you call this method before joining a channel. /// /// 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. + /// 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 stopRecordingDeviceTest(); /// Starts an audio device loopback test. /// - /// This method tests whether the local audio capture device and playback device are working properly. After starting the test, the audio capture device records the local audio, and the audio playback device plays the captured audio. The SDK triggers two independent onAudioVolumeIndication callbacks at the time interval set in this method, which reports the volume information of the capture device ( uid = 0) and the volume information of the playback device ( uid = 1) respectively. This method is for Windows and macOS only. You can call this method either before or after joining a channel. This method only takes effect when called by the host. This method tests local audio devices and does not report the network conditions. When you finished testing, call stopAudioDeviceLoopbackTest to stop the audio device loopback test. + /// This method tests whether the local audio capture device and playback device are working properly. After starting the test, the audio capture device records the local audio, and the audio playback device plays the captured audio. The SDK triggers two independent onAudioVolumeIndication callbacks at the time interval set in this method, which reports the volume information of the capture device (uid = 0) and the volume information of the playback device (uid = 1) respectively. + /// This method is for Windows and macOS only. + /// You can call this method either before or after joining a channel. + /// This method only takes effect when called by the host. + /// This method tests local audio devices and does not report the network conditions. + /// When you finished testing, call stopAudioDeviceLoopbackTest to stop the audio device loopback test. /// /// * [indicationInterval] The time interval (ms) at which the SDK triggers the onAudioVolumeIndication callback. Agora recommends setting a value greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive the onAudioVolumeIndication callback. /// /// 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. + /// 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 startAudioDeviceLoopbackTest(int indicationInterval); /// Stops the audio device loopback test. /// - /// This method is for Windows and macOS only. You can call this method either before or after joining a channel. This method only takes effect when called by the host. Ensure that you call this method to stop the loopback test after calling the startAudioDeviceLoopbackTest method. + /// This method is for Windows and macOS only. + /// You can call this method either before or after joining a channel. + /// This method only takes effect when called by the host. + /// Ensure that you call this method to stop the loopback test after calling the startAudioDeviceLoopbackTest method. /// /// 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. + /// 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 stopAudioDeviceLoopbackTest(); /// Sets the audio playback device used by the SDK to follow the system default audio playback device. /// /// This method is for Windows and macOS only. /// - /// * [enable] Whether to follow the system default audio playback device:true: Follow the system default audio playback device. The SDK immediately switches the audio playback device when the system default audio playback device changes.false: Do not follow the system default audio playback device. The SDK switches the audio playback device to the system default audio playback device only when the currently used audio playback device is disconnected. + /// * [enable] Whether to follow the system default audio playback device: true : Follow the system default audio playback device. The SDK immediately switches the audio playback device when the system default audio playback device changes. false : Do not follow the system default audio playback device. The SDK switches the audio playback device to the system default audio playback device only when the currently used audio playback device is disconnected. /// /// 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. + /// 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 followSystemPlaybackDevice(bool enable); /// Sets the audio recording device used by the SDK to follow the system default audio recording device. /// /// This method is for Windows and macOS only. /// - /// * [enable] Whether to follow the system default audio recording device:true: Follow the system default audio playback device. The SDK immediately switches the audio recording device when the system default audio recording device changes.false: Do not follow the system default audio playback device. The SDK switches the audio recording device to the system default audio recording device only when the currently used audio recording device is disconnected. + /// * [enable] Whether to follow the system default audio recording device: true : Follow the system default audio playback device. The SDK immediately switches the audio recording device when the system default audio recording device changes. false : Do not follow the system default audio playback device. The SDK switches the audio recording device to the system default audio recording device only when the currently used audio recording device is disconnected. /// /// 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. + /// 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 followSystemRecordingDevice(bool enable); /// Sets whether the loopback device follows the system default playback device. /// /// This method is for Windows and macOS only. /// - /// * [enable] Whether to follow the system default audio playback device:true: Follow the system default audio playback device. When the default playback device of the system is changed, the SDK immediately switches to the loopback device.false: Do not follow the system default audio playback device. The SDK switches the audio loopback device to the system default audio playback device only when the current audio playback device is disconnected. + /// * [enable] Whether to follow the system default audio playback device: true : Follow the system default audio playback device. When the default playback device of the system is changed, the SDK immediately switches to the loopback device. false : Do not follow the system default audio playback device. The SDK switches the audio loopback device to the system default audio playback device only when the current audio playback device is disconnected. /// /// 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. + /// 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 followSystemLoopbackDevice(bool enable); /// Releases all the resources occupied by the AudioDeviceManager object. @@ -233,7 +269,7 @@ abstract class AudioDeviceManager { /// This method is for Windows and macOS only. /// /// Returns - /// The details about the default audio playback device. See AudioDeviceInfo . + /// The details about the default audio playback device. See AudioDeviceInfo. Future getPlaybackDefaultDevice(); /// Gets the default audio capture device. @@ -241,6 +277,6 @@ abstract class AudioDeviceManager { /// This method is for Windows and macOS only. /// /// Returns - /// The details about the default audio capture device. See AudioDeviceInfo . + /// The details about the default audio capture device. See AudioDeviceInfo. Future getRecordingDefaultDevice(); } diff --git a/lib/src/binding/agora_music_content_center_event_impl.dart b/lib/src/binding/agora_music_content_center_event_impl.dart index 8eb988735..0a34dc9cd 100644 --- a/lib/src/binding/agora_music_content_center_event_impl.dart +++ b/lib/src/binding/agora_music_content_center_event_impl.dart @@ -72,13 +72,40 @@ class MusicContentCenterEventHandlerWrapper implements EventLoopEventHandler { MusicContentCenterEventHandlerOnLyricResultJson.fromJson(jsonMap); paramJson = paramJson.fillBuffers(buffers); String? requestId = paramJson.requestId; + int? songCode = paramJson.songCode; String? lyricUrl = paramJson.lyricUrl; MusicContentCenterStatusCode? errorCode = paramJson.errorCode; - if (requestId == null || lyricUrl == null || errorCode == null) { + if (requestId == null || + songCode == null || + lyricUrl == null || + errorCode == null) { return true; } musicContentCenterEventHandler.onLyricResult!( - requestId, lyricUrl, errorCode); + requestId, songCode, lyricUrl, errorCode); + return true; + + case 'onSongSimpleInfoResult': + if (musicContentCenterEventHandler.onSongSimpleInfoResult == null) { + return true; + } + final jsonMap = jsonDecode(eventData); + MusicContentCenterEventHandlerOnSongSimpleInfoResultJson paramJson = + MusicContentCenterEventHandlerOnSongSimpleInfoResultJson.fromJson( + jsonMap); + paramJson = paramJson.fillBuffers(buffers); + String? requestId = paramJson.requestId; + int? songCode = paramJson.songCode; + String? simpleInfo = paramJson.simpleInfo; + MusicContentCenterStatusCode? errorCode = paramJson.errorCode; + if (requestId == null || + songCode == null || + simpleInfo == null || + errorCode == null) { + return true; + } + musicContentCenterEventHandler.onSongSimpleInfoResult!( + requestId, songCode, simpleInfo, errorCode); return true; case 'onPreLoadEvent': @@ -89,12 +116,14 @@ class MusicContentCenterEventHandlerWrapper implements EventLoopEventHandler { MusicContentCenterEventHandlerOnPreLoadEventJson paramJson = MusicContentCenterEventHandlerOnPreLoadEventJson.fromJson(jsonMap); paramJson = paramJson.fillBuffers(buffers); + String? requestId = paramJson.requestId; int? songCode = paramJson.songCode; int? percent = paramJson.percent; String? lyricUrl = paramJson.lyricUrl; PreloadStatusCode? status = paramJson.status; MusicContentCenterStatusCode? errorCode = paramJson.errorCode; - if (songCode == null || + if (requestId == null || + songCode == null || percent == null || lyricUrl == null || status == null || @@ -102,7 +131,7 @@ class MusicContentCenterEventHandlerWrapper implements EventLoopEventHandler { return true; } musicContentCenterEventHandler.onPreLoadEvent!( - songCode, percent, lyricUrl, status, errorCode); + requestId, songCode, percent, lyricUrl, status, errorCode); return true; } return false; diff --git a/lib/src/binding/agora_music_content_center_impl.dart b/lib/src/binding/agora_music_content_center_impl.dart index 32e6d0d01..64fae29b4 100644 --- a/lib/src/binding/agora_music_content_center_impl.dart +++ b/lib/src/binding/agora_music_content_center_impl.dart @@ -375,11 +375,10 @@ class MusicContentCenterImpl implements MusicContentCenter { } @override - Future preload({required int songCode, String? jsonOption}) async { + Future preload(int songCode) async { final apiType = '${isOverrideClassName ? className : 'MusicContentCenter'}_preload'; - final param = - createParams({'songCode': songCode, 'jsonOption': jsonOption}); + final param = createParams({'songCode': songCode}); final callApiResult = await irisMethodChannel.invokeMethod( IrisMethodCall(apiType, jsonEncode(param), buffers: null)); if (callApiResult.irisReturnCode < 0) { @@ -390,6 +389,8 @@ class MusicContentCenterImpl implements MusicContentCenter { if (result < 0) { throw AgoraRtcException(code: result); } + final preloadJson = MusicContentCenterPreloadJson.fromJson(rm); + return preloadJson.requestId; } @override @@ -461,4 +462,46 @@ class MusicContentCenterImpl implements MusicContentCenter { final getLyricJson = MusicContentCenterGetLyricJson.fromJson(rm); return getLyricJson.requestId; } + + @override + Future getSongSimpleInfo(int songCode) async { + final apiType = + '${isOverrideClassName ? className : 'MusicContentCenter'}_getSongSimpleInfo'; + final param = createParams({'songCode': songCode}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + if (result < 0) { + throw AgoraRtcException(code: result); + } + final getSongSimpleInfoJson = + MusicContentCenterGetSongSimpleInfoJson.fromJson(rm); + return getSongSimpleInfoJson.requestId; + } + + @override + Future getInternalSongCode( + {required int songCode, required String jsonOption}) async { + final apiType = + '${isOverrideClassName ? className : 'MusicContentCenter'}_getInternalSongCode'; + final param = + createParams({'songCode': songCode, 'jsonOption': jsonOption}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + if (result < 0) { + throw AgoraRtcException(code: result); + } + final getInternalSongCodeJson = + MusicContentCenterGetInternalSongCodeJson.fromJson(rm); + return getInternalSongCodeJson.internalSongCode; + } } diff --git a/lib/src/binding/agora_rtc_engine_event_impl.dart b/lib/src/binding/agora_rtc_engine_event_impl.dart index c6115c0d5..7d80f2f80 100644 --- a/lib/src/binding/agora_rtc_engine_event_impl.dart +++ b/lib/src/binding/agora_rtc_engine_event_impl.dart @@ -388,7 +388,7 @@ class RtcEngineEventHandlerWrapper implements EventLoopEventHandler { source, width, height, elapsed); return true; - case 'onFirstLocalVideoFramePublishedEx': + case 'onFirstLocalVideoFramePublished': if (rtcEngineEventHandler.onFirstLocalVideoFramePublished == null) { return true; } @@ -397,14 +397,12 @@ class RtcEngineEventHandlerWrapper implements EventLoopEventHandler { RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJson.fromJson( jsonMap); paramJson = paramJson.fillBuffers(buffers); - RtcConnection? connection = paramJson.connection; + VideoSourceType? source = paramJson.source; int? elapsed = paramJson.elapsed; - if (connection == null || elapsed == null) { + if (source == null || elapsed == null) { return true; } - connection = connection.fillBuffers(buffers); - rtcEngineEventHandler.onFirstLocalVideoFramePublished!( - connection, elapsed); + rtcEngineEventHandler.onFirstLocalVideoFramePublished!(source, elapsed); return true; case 'onFirstRemoteVideoDecodedEx': @@ -692,7 +690,7 @@ class RtcEngineEventHandlerWrapper implements EventLoopEventHandler { rtcEngineEventHandler.onRemoteAudioStats!(connection, stats); return true; - case 'onLocalVideoStatsEx': + case 'onLocalVideoStats': if (rtcEngineEventHandler.onLocalVideoStats == null) { return true; } @@ -700,14 +698,13 @@ class RtcEngineEventHandlerWrapper implements EventLoopEventHandler { RtcEngineEventHandlerOnLocalVideoStatsJson paramJson = RtcEngineEventHandlerOnLocalVideoStatsJson.fromJson(jsonMap); paramJson = paramJson.fillBuffers(buffers); - RtcConnection? connection = paramJson.connection; + VideoSourceType? source = paramJson.source; LocalVideoStats? stats = paramJson.stats; - if (connection == null || stats == null) { + if (source == null || stats == null) { return true; } - connection = connection.fillBuffers(buffers); stats = stats.fillBuffers(buffers); - rtcEngineEventHandler.onLocalVideoStats!(connection, stats); + rtcEngineEventHandler.onLocalVideoStats!(source, stats); return true; case 'onRemoteVideoStatsEx': diff --git a/lib/src/binding/agora_rtc_engine_impl.dart b/lib/src/binding/agora_rtc_engine_impl.dart index 90dc00fa3..814a58120 100644 --- a/lib/src/binding/agora_rtc_engine_impl.dart +++ b/lib/src/binding/agora_rtc_engine_impl.dart @@ -266,6 +266,59 @@ class RtcEngineImpl implements RtcEngine { return queryCodecCapabilityJson.codecInfo; } + @override + Future preloadChannel( + {required String token, + required String channelId, + required int uid}) async { + final apiType = + '${isOverrideClassName ? className : 'RtcEngine'}_preloadChannel'; + final param = + createParams({'token': token, 'channelId': channelId, 'uid': uid}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + } + + @override + Future preloadChannelWithUserAccount( + {required String token, + required String channelId, + required String userAccount}) async { + final apiType = + '${isOverrideClassName ? className : 'RtcEngine'}_preloadChannelWithUserAccount'; + final param = createParams( + {'token': token, 'channelId': channelId, 'userAccount': userAccount}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + } + + @override + Future updatePreloadChannelToken(String token) async { + final apiType = + '${isOverrideClassName ? className : 'RtcEngine'}_updatePreloadChannelToken'; + final param = createParams({'token': token}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + if (result < 0) { + throw AgoraRtcException(code: result); + } + } + @override Future joinChannel( {required String token, @@ -2221,10 +2274,10 @@ class RtcEngineImpl implements RtcEngine { } @override - Future uploadLogFile(String requestId) async { + Future uploadLogFile() async { final apiType = '${isOverrideClassName ? className : 'RtcEngine'}_uploadLogFile'; - final param = createParams({'requestId': requestId}); + final param = createParams({}); final callApiResult = await irisMethodChannel.invokeMethod( IrisMethodCall(apiType, jsonEncode(param), buffers: null)); if (callApiResult.irisReturnCode < 0) { @@ -2235,6 +2288,8 @@ class RtcEngineImpl implements RtcEngine { if (result < 0) { throw AgoraRtcException(code: result); } + final uploadLogFileJson = RtcEngineUploadLogFileJson.fromJson(rm); + return uploadLogFileJson.requestId; } @override @@ -3215,6 +3270,38 @@ class RtcEngineImpl implements RtcEngine { } } + @override + Future isCameraExposureSupported() async { + final apiType = + '${isOverrideClassName ? className : 'RtcEngine'}_isCameraExposureSupported'; + final param = createParams({}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + return result as bool; + } + + @override + Future setCameraExposureFactor(double factor) async { + final apiType = + '${isOverrideClassName ? className : 'RtcEngine'}_setCameraExposureFactor'; + final param = createParams({'factor': factor}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + if (result < 0) { + throw AgoraRtcException(code: result); + } + } + @override Future isCameraAutoExposureFaceModeSupported() async { final apiType = @@ -3296,6 +3383,23 @@ class RtcEngineImpl implements RtcEngine { return result as bool; } + @override + Future setRouteInCommunicationMode(int route) async { + final apiType = + '${isOverrideClassName ? className : 'RtcEngine'}_setRouteInCommunicationMode'; + final param = createParams({'route': route}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + if (result < 0) { + throw AgoraRtcException(code: result); + } + } + @override Future> getScreenCaptureSources( {required SIZE thumbSize, diff --git a/lib/src/binding/call_api_event_handler_buffer_ext.dart b/lib/src/binding/call_api_event_handler_buffer_ext.dart index 67b9d22d4..02adeaf91 100644 --- a/lib/src/binding/call_api_event_handler_buffer_ext.dart +++ b/lib/src/binding/call_api_event_handler_buffer_ext.dart @@ -205,43 +205,6 @@ extension ChannelMediaOptionsBufferExt on ChannelMediaOptions { } } -extension LogUploadServerInfoBufferExt on LogUploadServerInfo { - LogUploadServerInfo fillBuffers(List bufferList) { - if (bufferList.isEmpty) return this; - return this; - } - - List collectBufferList() { - final bufferList = []; - return bufferList; - } -} - -extension AdvancedConfigInfoBufferExt on AdvancedConfigInfo { - AdvancedConfigInfo fillBuffers(List bufferList) { - if (bufferList.isEmpty) return this; - return this; - } - - List collectBufferList() { - final bufferList = []; - return bufferList; - } -} - -extension LocalAccessPointConfigurationBufferExt - on LocalAccessPointConfiguration { - LocalAccessPointConfiguration fillBuffers(List bufferList) { - if (bufferList.isEmpty) return this; - return this; - } - - List collectBufferList() { - final bufferList = []; - return bufferList; - } -} - extension LeaveChannelOptionsBufferExt on LeaveChannelOptions { LeaveChannelOptions fillBuffers(List bufferList) { if (bufferList.isEmpty) return this; @@ -456,6 +419,18 @@ extension AdvanceOptionsBufferExt on AdvanceOptions { } } +extension CodecCapLevelsBufferExt on CodecCapLevels { + CodecCapLevels fillBuffers(List bufferList) { + if (bufferList.isEmpty) return this; + return this; + } + + List collectBufferList() { + final bufferList = []; + return bufferList; + } +} + extension CodecCapInfoBufferExt on CodecCapInfo { CodecCapInfo fillBuffers(List bufferList) { if (bufferList.isEmpty) return this; @@ -1064,6 +1039,43 @@ extension RecorderStreamInfoBufferExt on RecorderStreamInfo { } } +extension LogUploadServerInfoBufferExt on LogUploadServerInfo { + LogUploadServerInfo fillBuffers(List bufferList) { + if (bufferList.isEmpty) return this; + return this; + } + + List collectBufferList() { + final bufferList = []; + return bufferList; + } +} + +extension AdvancedConfigInfoBufferExt on AdvancedConfigInfo { + AdvancedConfigInfo fillBuffers(List bufferList) { + if (bufferList.isEmpty) return this; + return this; + } + + List collectBufferList() { + final bufferList = []; + return bufferList; + } +} + +extension LocalAccessPointConfigurationBufferExt + on LocalAccessPointConfiguration { + LocalAccessPointConfiguration fillBuffers(List bufferList) { + if (bufferList.isEmpty) return this; + return this; + } + + List collectBufferList() { + final bufferList = []; + return bufferList; + } +} + extension SpatialAudioParamsBufferExt on SpatialAudioParams { SpatialAudioParams fillBuffers(List bufferList) { if (bufferList.isEmpty) return this; @@ -1285,7 +1297,8 @@ extension AudioFrameBufferExt on AudioFrame { samplesPerSec: samplesPerSec, buffer: buffer, renderTimeMs: renderTimeMs, - avsyncType: avsyncType); + avsyncType: avsyncType, + presentationMs: presentationMs); } List collectBufferList() { diff --git a/lib/src/binding/call_api_impl_params_json.dart b/lib/src/binding/call_api_impl_params_json.dart index 40e1fb1e6..9f2e2598a 100644 --- a/lib/src/binding/call_api_impl_params_json.dart +++ b/lib/src/binding/call_api_impl_params_json.dart @@ -42,6 +42,17 @@ class RtcEngineQueryCodecCapabilityJson { _$RtcEngineQueryCodecCapabilityJsonToJson(this); } +@JsonSerializable(explicitToJson: true) +class RtcEngineUploadLogFileJson { + const RtcEngineUploadLogFileJson(this.requestId); + + @JsonKey(name: 'requestId') + final String requestId; + factory RtcEngineUploadLogFileJson.fromJson(Map json) => + _$RtcEngineUploadLogFileJsonFromJson(json); + Map toJson() => _$RtcEngineUploadLogFileJsonToJson(this); +} + @JsonSerializable(explicitToJson: true) class RtcEngineGetExtensionPropertyJson { const RtcEngineGetExtensionPropertyJson(this.value); @@ -375,6 +386,17 @@ class MusicContentCenterSearchMusicJson { _$MusicContentCenterSearchMusicJsonToJson(this); } +@JsonSerializable(explicitToJson: true) +class MusicContentCenterPreloadJson { + const MusicContentCenterPreloadJson(this.requestId); + + @JsonKey(name: 'requestId') + final String requestId; + factory MusicContentCenterPreloadJson.fromJson(Map json) => + _$MusicContentCenterPreloadJsonFromJson(json); + Map toJson() => _$MusicContentCenterPreloadJsonToJson(this); +} + @JsonSerializable(explicitToJson: true) class MusicContentCenterGetCachesJson { const MusicContentCenterGetCachesJson(this.cacheInfo); @@ -397,3 +419,29 @@ class MusicContentCenterGetLyricJson { _$MusicContentCenterGetLyricJsonFromJson(json); Map toJson() => _$MusicContentCenterGetLyricJsonToJson(this); } + +@JsonSerializable(explicitToJson: true) +class MusicContentCenterGetSongSimpleInfoJson { + const MusicContentCenterGetSongSimpleInfoJson(this.requestId); + + @JsonKey(name: 'requestId') + final String requestId; + factory MusicContentCenterGetSongSimpleInfoJson.fromJson( + Map json) => + _$MusicContentCenterGetSongSimpleInfoJsonFromJson(json); + Map toJson() => + _$MusicContentCenterGetSongSimpleInfoJsonToJson(this); +} + +@JsonSerializable(explicitToJson: true) +class MusicContentCenterGetInternalSongCodeJson { + const MusicContentCenterGetInternalSongCodeJson(this.internalSongCode); + + @JsonKey(name: 'internalSongCode') + final int internalSongCode; + factory MusicContentCenterGetInternalSongCodeJson.fromJson( + Map json) => + _$MusicContentCenterGetInternalSongCodeJsonFromJson(json); + Map toJson() => + _$MusicContentCenterGetInternalSongCodeJsonToJson(this); +} diff --git a/lib/src/binding/call_api_impl_params_json.g.dart b/lib/src/binding/call_api_impl_params_json.g.dart index 95a728a1e..bd061724d 100644 --- a/lib/src/binding/call_api_impl_params_json.g.dart +++ b/lib/src/binding/call_api_impl_params_json.g.dart @@ -46,6 +46,18 @@ Map _$RtcEngineQueryCodecCapabilityJsonToJson( 'codecInfo': instance.codecInfo.map((e) => e.toJson()).toList(), }; +RtcEngineUploadLogFileJson _$RtcEngineUploadLogFileJsonFromJson( + Map json) => + RtcEngineUploadLogFileJson( + json['requestId'] as String, + ); + +Map _$RtcEngineUploadLogFileJsonToJson( + RtcEngineUploadLogFileJson instance) => + { + 'requestId': instance.requestId, + }; + RtcEngineGetExtensionPropertyJson _$RtcEngineGetExtensionPropertyJsonFromJson( Map json) => RtcEngineGetExtensionPropertyJson( @@ -383,6 +395,18 @@ Map _$MusicContentCenterSearchMusicJsonToJson( 'requestId': instance.requestId, }; +MusicContentCenterPreloadJson _$MusicContentCenterPreloadJsonFromJson( + Map json) => + MusicContentCenterPreloadJson( + json['requestId'] as String, + ); + +Map _$MusicContentCenterPreloadJsonToJson( + MusicContentCenterPreloadJson instance) => + { + 'requestId': instance.requestId, + }; + MusicContentCenterGetCachesJson _$MusicContentCenterGetCachesJsonFromJson( Map json) => MusicContentCenterGetCachesJson( @@ -408,3 +432,29 @@ Map _$MusicContentCenterGetLyricJsonToJson( { 'requestId': instance.requestId, }; + +MusicContentCenterGetSongSimpleInfoJson + _$MusicContentCenterGetSongSimpleInfoJsonFromJson( + Map json) => + MusicContentCenterGetSongSimpleInfoJson( + json['requestId'] as String, + ); + +Map _$MusicContentCenterGetSongSimpleInfoJsonToJson( + MusicContentCenterGetSongSimpleInfoJson instance) => + { + 'requestId': instance.requestId, + }; + +MusicContentCenterGetInternalSongCodeJson + _$MusicContentCenterGetInternalSongCodeJsonFromJson( + Map json) => + MusicContentCenterGetInternalSongCodeJson( + json['internalSongCode'] as int, + ); + +Map _$MusicContentCenterGetInternalSongCodeJsonToJson( + MusicContentCenterGetInternalSongCodeJson instance) => + { + 'internalSongCode': instance.internalSongCode, + }; diff --git a/lib/src/binding/event_handler_param_json.dart b/lib/src/binding/event_handler_param_json.dart index 2bf878ede..82aeecd46 100644 --- a/lib/src/binding/event_handler_param_json.dart +++ b/lib/src/binding/event_handler_param_json.dart @@ -608,10 +608,10 @@ extension RtcEngineEventHandlerOnFirstLocalVideoFrameJsonBufferExt @JsonSerializable(explicitToJson: true) class RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJson { const RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJson( - {this.connection, this.elapsed}); + {this.source, this.elapsed}); - @JsonKey(name: 'connection') - final RtcConnection? connection; + @JsonKey(name: 'source') + final VideoSourceType? source; @JsonKey(name: 'elapsed') final int? elapsed; factory RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJson.fromJson( @@ -1104,11 +1104,10 @@ extension RtcEngineEventHandlerOnRemoteAudioStatsJsonBufferExt @JsonSerializable(explicitToJson: true) class RtcEngineEventHandlerOnLocalVideoStatsJson { - const RtcEngineEventHandlerOnLocalVideoStatsJson( - {this.connection, this.stats}); + const RtcEngineEventHandlerOnLocalVideoStatsJson({this.source, this.stats}); - @JsonKey(name: 'connection') - final RtcConnection? connection; + @JsonKey(name: 'source') + final VideoSourceType? source; @JsonKey(name: 'stats') final LocalVideoStats? stats; factory RtcEngineEventHandlerOnLocalVideoStatsJson.fromJson( @@ -4032,7 +4031,7 @@ class MusicContentCenterEventHandlerOnMusicChartsResultJson { final String? requestId; @JsonKey(name: 'result') final List? result; - @JsonKey(name: 'error_code') + @JsonKey(name: 'errorCode') final MusicContentCenterStatusCode? errorCode; factory MusicContentCenterEventHandlerOnMusicChartsResultJson.fromJson( Map json) => @@ -4064,7 +4063,7 @@ class MusicContentCenterEventHandlerOnMusicCollectionResultJson { final String? requestId; @JsonKey(name: 'result', ignore: true) final MusicCollection? result; - @JsonKey(name: 'error_code') + @JsonKey(name: 'errorCode') final MusicContentCenterStatusCode? errorCode; factory MusicContentCenterEventHandlerOnMusicCollectionResultJson.fromJson( Map json) => @@ -4090,13 +4089,15 @@ extension MusicContentCenterEventHandlerOnMusicCollectionResultJsonBufferExt @JsonSerializable(explicitToJson: true) class MusicContentCenterEventHandlerOnLyricResultJson { const MusicContentCenterEventHandlerOnLyricResultJson( - {this.requestId, this.lyricUrl, this.errorCode}); + {this.requestId, this.songCode, this.lyricUrl, this.errorCode}); @JsonKey(name: 'requestId') final String? requestId; + @JsonKey(name: 'songCode') + final int? songCode; @JsonKey(name: 'lyricUrl') final String? lyricUrl; - @JsonKey(name: 'error_code') + @JsonKey(name: 'errorCode') final MusicContentCenterStatusCode? errorCode; factory MusicContentCenterEventHandlerOnLyricResultJson.fromJson( Map json) => @@ -4119,15 +4120,52 @@ extension MusicContentCenterEventHandlerOnLyricResultJsonBufferExt } } +@JsonSerializable(explicitToJson: true) +class MusicContentCenterEventHandlerOnSongSimpleInfoResultJson { + const MusicContentCenterEventHandlerOnSongSimpleInfoResultJson( + {this.requestId, this.songCode, this.simpleInfo, this.errorCode}); + + @JsonKey(name: 'requestId') + final String? requestId; + @JsonKey(name: 'songCode') + final int? songCode; + @JsonKey(name: 'simpleInfo') + final String? simpleInfo; + @JsonKey(name: 'errorCode') + final MusicContentCenterStatusCode? errorCode; + factory MusicContentCenterEventHandlerOnSongSimpleInfoResultJson.fromJson( + Map json) => + _$MusicContentCenterEventHandlerOnSongSimpleInfoResultJsonFromJson(json); + Map toJson() => + _$MusicContentCenterEventHandlerOnSongSimpleInfoResultJsonToJson(this); +} + +extension MusicContentCenterEventHandlerOnSongSimpleInfoResultJsonBufferExt + on MusicContentCenterEventHandlerOnSongSimpleInfoResultJson { + MusicContentCenterEventHandlerOnSongSimpleInfoResultJson fillBuffers( + List bufferList) { + if (bufferList.isEmpty) return this; + return this; + } + + List collectBufferList() { + final bufferList = []; + return bufferList; + } +} + @JsonSerializable(explicitToJson: true) class MusicContentCenterEventHandlerOnPreLoadEventJson { const MusicContentCenterEventHandlerOnPreLoadEventJson( - {this.songCode, + {this.requestId, + this.songCode, this.percent, this.lyricUrl, this.status, this.errorCode}); + @JsonKey(name: 'requestId') + final String? requestId; @JsonKey(name: 'songCode') final int? songCode; @JsonKey(name: 'percent') @@ -4136,7 +4174,7 @@ class MusicContentCenterEventHandlerOnPreLoadEventJson { final String? lyricUrl; @JsonKey(name: 'status') final PreloadStatusCode? status; - @JsonKey(name: 'error_code') + @JsonKey(name: 'errorCode') final MusicContentCenterStatusCode? errorCode; factory MusicContentCenterEventHandlerOnPreLoadEventJson.fromJson( Map json) => diff --git a/lib/src/binding/event_handler_param_json.g.dart b/lib/src/binding/event_handler_param_json.g.dart index 81d30c2d3..032201f9c 100644 --- a/lib/src/binding/event_handler_param_json.g.dart +++ b/lib/src/binding/event_handler_param_json.g.dart @@ -496,10 +496,7 @@ RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJson _$RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJsonFromJson( Map json) => RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJson( - connection: json['connection'] == null - ? null - : RtcConnection.fromJson( - json['connection'] as Map), + source: $enumDecodeNullable(_$VideoSourceTypeEnumMap, json['source']), elapsed: json['elapsed'] as int?, ); @@ -507,7 +504,7 @@ Map _$RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJsonToJson( RtcEngineEventHandlerOnFirstLocalVideoFramePublishedJson instance) => { - 'connection': instance.connection?.toJson(), + 'source': _$VideoSourceTypeEnumMap[instance.source], 'elapsed': instance.elapsed, }; @@ -876,10 +873,7 @@ RtcEngineEventHandlerOnLocalVideoStatsJson _$RtcEngineEventHandlerOnLocalVideoStatsJsonFromJson( Map json) => RtcEngineEventHandlerOnLocalVideoStatsJson( - connection: json['connection'] == null - ? null - : RtcConnection.fromJson( - json['connection'] as Map), + source: $enumDecodeNullable(_$VideoSourceTypeEnumMap, json['source']), stats: json['stats'] == null ? null : LocalVideoStats.fromJson(json['stats'] as Map), @@ -888,7 +882,7 @@ RtcEngineEventHandlerOnLocalVideoStatsJson Map _$RtcEngineEventHandlerOnLocalVideoStatsJsonToJson( RtcEngineEventHandlerOnLocalVideoStatsJson instance) => { - 'connection': instance.connection?.toJson(), + 'source': _$VideoSourceTypeEnumMap[instance.source], 'stats': instance.stats?.toJson(), }; @@ -2944,7 +2938,7 @@ MusicContentCenterEventHandlerOnMusicChartsResultJson ?.map((e) => MusicChartInfo.fromJson(e as Map)) .toList(), errorCode: $enumDecodeNullable( - _$MusicContentCenterStatusCodeEnumMap, json['error_code']), + _$MusicContentCenterStatusCodeEnumMap, json['errorCode']), ); Map @@ -2953,7 +2947,7 @@ Map { 'requestId': instance.requestId, 'result': instance.result?.map((e) => e.toJson()).toList(), - 'error_code': + 'errorCode': _$MusicContentCenterStatusCodeEnumMap[instance.errorCode], }; @@ -2974,7 +2968,7 @@ MusicContentCenterEventHandlerOnMusicCollectionResultJson MusicContentCenterEventHandlerOnMusicCollectionResultJson( requestId: json['requestId'] as String?, errorCode: $enumDecodeNullable( - _$MusicContentCenterStatusCodeEnumMap, json['error_code']), + _$MusicContentCenterStatusCodeEnumMap, json['errorCode']), ); Map { 'requestId': instance.requestId, - 'error_code': _$MusicContentCenterStatusCodeEnumMap[instance.errorCode], + 'errorCode': _$MusicContentCenterStatusCodeEnumMap[instance.errorCode], }; MusicContentCenterEventHandlerOnLyricResultJson @@ -2990,40 +2984,65 @@ MusicContentCenterEventHandlerOnLyricResultJson Map json) => MusicContentCenterEventHandlerOnLyricResultJson( requestId: json['requestId'] as String?, + songCode: json['songCode'] as int?, lyricUrl: json['lyricUrl'] as String?, errorCode: $enumDecodeNullable( - _$MusicContentCenterStatusCodeEnumMap, json['error_code']), + _$MusicContentCenterStatusCodeEnumMap, json['errorCode']), ); Map _$MusicContentCenterEventHandlerOnLyricResultJsonToJson( MusicContentCenterEventHandlerOnLyricResultJson instance) => { 'requestId': instance.requestId, + 'songCode': instance.songCode, 'lyricUrl': instance.lyricUrl, - 'error_code': _$MusicContentCenterStatusCodeEnumMap[instance.errorCode], + 'errorCode': _$MusicContentCenterStatusCodeEnumMap[instance.errorCode], + }; + +MusicContentCenterEventHandlerOnSongSimpleInfoResultJson + _$MusicContentCenterEventHandlerOnSongSimpleInfoResultJsonFromJson( + Map json) => + MusicContentCenterEventHandlerOnSongSimpleInfoResultJson( + requestId: json['requestId'] as String?, + songCode: json['songCode'] as int?, + simpleInfo: json['simpleInfo'] as String?, + errorCode: $enumDecodeNullable( + _$MusicContentCenterStatusCodeEnumMap, json['errorCode']), + ); + +Map _$MusicContentCenterEventHandlerOnSongSimpleInfoResultJsonToJson( + MusicContentCenterEventHandlerOnSongSimpleInfoResultJson instance) => + { + 'requestId': instance.requestId, + 'songCode': instance.songCode, + 'simpleInfo': instance.simpleInfo, + 'errorCode': _$MusicContentCenterStatusCodeEnumMap[instance.errorCode], }; MusicContentCenterEventHandlerOnPreLoadEventJson _$MusicContentCenterEventHandlerOnPreLoadEventJsonFromJson( Map json) => MusicContentCenterEventHandlerOnPreLoadEventJson( + requestId: json['requestId'] as String?, songCode: json['songCode'] as int?, percent: json['percent'] as int?, lyricUrl: json['lyricUrl'] as String?, status: $enumDecodeNullable(_$PreloadStatusCodeEnumMap, json['status']), errorCode: $enumDecodeNullable( - _$MusicContentCenterStatusCodeEnumMap, json['error_code']), + _$MusicContentCenterStatusCodeEnumMap, json['errorCode']), ); Map _$MusicContentCenterEventHandlerOnPreLoadEventJsonToJson( MusicContentCenterEventHandlerOnPreLoadEventJson instance) => { + 'requestId': instance.requestId, 'songCode': instance.songCode, 'percent': instance.percent, 'lyricUrl': instance.lyricUrl, 'status': _$PreloadStatusCodeEnumMap[instance.status], - 'error_code': _$MusicContentCenterStatusCodeEnumMap[instance.errorCode], + 'errorCode': _$MusicContentCenterStatusCodeEnumMap[instance.errorCode], }; const _$PreloadStatusCodeEnumMap = { diff --git a/lib/src/impl/agora_music_content_center_impl_override.dart b/lib/src/impl/agora_music_content_center_impl_override.dart index 4d9bfb061..3709db763 100644 --- a/lib/src/impl/agora_music_content_center_impl_override.dart +++ b/lib/src/impl/agora_music_content_center_impl_override.dart @@ -8,6 +8,7 @@ import 'package:agora_rtc_engine/src/binding/agora_music_content_center_event_im as event_binding; import 'package:agora_rtc_engine/src/binding/agora_music_content_center_impl.dart' as binding; +import 'package:agora_rtc_engine/src/binding/call_api_impl_params_json.dart'; import 'package:agora_rtc_engine/src/binding/event_handler_param_json.dart'; import 'package:agora_rtc_engine/src/impl/agora_music_content_center_impl_json.dart'; @@ -225,4 +226,23 @@ class MusicContentCenterImpl extends binding.MusicContentCenterImpl final result = rm['result']; return result == 0; } + + @override + Future preload(int songCode) async { + final apiType = + '${isOverrideClassName ? className : 'MusicContentCenter'}_preload2'; + final param = createParams({'songCode': songCode}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + final rm = callApiResult.data; + final result = rm['result']; + if (result < 0) { + throw AgoraRtcException(code: result); + } + final preloadJson = MusicContentCenterPreloadJson.fromJson(rm); + return preloadJson.requestId; + } } diff --git a/lib/src/impl/agora_rtc_engine_impl.dart b/lib/src/impl/agora_rtc_engine_impl.dart index ad2905ee5..a82c9cd47 100644 --- a/lib/src/impl/agora_rtc_engine_impl.dart +++ b/lib/src/impl/agora_rtc_engine_impl.dart @@ -1072,6 +1072,22 @@ class RtcEngineImpl extends rtc_engine_ex_binding.RtcEngineExImpl } } + @override + Future preloadChannelWithUserAccount( + {required String token, + required String channelId, + required String userAccount}) async { + final apiType = + '${isOverrideClassName ? className : 'RtcEngine'}_preloadChannel2'; + final param = createParams( + {'token': token, 'channelId': channelId, 'userAccount': userAccount}); + final callApiResult = await irisMethodChannel.invokeMethod( + IrisMethodCall(apiType, jsonEncode(param), buffers: null)); + if (callApiResult.irisReturnCode < 0) { + throw AgoraRtcException(code: callApiResult.irisReturnCode); + } + } + /////////// debug //////// /// [type] see [VideoSourceType], only [VideoSourceType.videoSourceCamera], [VideoSourceType.videoSourceRemote] supported diff --git a/lib/src/impl/agora_video_view_impl.dart b/lib/src/impl/agora_video_view_impl.dart index 025f7ff0c..a921cfa78 100644 --- a/lib/src/impl/agora_video_view_impl.dart +++ b/lib/src/impl/agora_video_view_impl.dart @@ -254,7 +254,7 @@ class _AgoraRtcRenderTextureState extends State Future _didUpdateWidget( covariant AgoraRtcRenderTexture oldWidget) async { - // For flutter texture rendering, only update the texture id and other state, and the + // For flutter texture rendering, only update the texture id and other state, and the // Flutter framework will handle the rest. _controller(widget.controller).updateController(oldWidget.controller); } diff --git a/lib/src/render/agora_video_view.dart b/lib/src/render/agora_video_view.dart index 84e3c444e..c6baa1a23 100644 --- a/lib/src/render/agora_video_view.dart +++ b/lib/src/render/agora_video_view.dart @@ -12,7 +12,9 @@ class AgoraVideoView extends StatefulWidget { this.onAgoraVideoViewCreated, }) : super(key: key); - /// Controls the type of video to render:If you want to render video of the RtcEngine, see VideoViewController.If you want to render video of the media player, see MediaPlayerController. + /// Controls the type of video to render: + /// If you want to render video of the RtcEngine, see VideoViewController. + /// If you want to render video of the media player, see MediaPlayerController. final VideoViewControllerBase controller; /// @nodoc diff --git a/lib/src/render/media_player_controller.dart b/lib/src/render/media_player_controller.dart index 43606108d..ba4f78a37 100644 --- a/lib/src/render/media_player_controller.dart +++ b/lib/src/render/media_player_controller.dart @@ -25,6 +25,7 @@ abstract class MediaPlayerController /// Creates a MediaPlayerController. /// - /// Make sure the RtcEngine is initialized before you call this method. Make sure to call this method before calling other APIs in MediaPlayer . + /// Make sure the RtcEngine is initialized before you call this method. + /// Make sure to call this method before calling other APIs in MediaPlayer. Future initialize(); } diff --git a/lib/src/render/video_view_controller.dart b/lib/src/render/video_view_controller.dart index 7a8904ec7..2808250bb 100644 --- a/lib/src/render/video_view_controller.dart +++ b/lib/src/render/video_view_controller.dart @@ -7,7 +7,10 @@ import 'package:meta/meta.dart'; /// A AgoraVideoView controller for rendering local and remote video. /// -/// On different platforms, the default view corresponding to this class is different: Android: . If you want to use , set the useAndroidSurfaceView property to true . iOS: . If you want to use Flutter Texture, set the useFlutterTexture property to true . macOS and Windows: . +/// On different platforms, the default view corresponding to this class is different: +/// Android:. If you want to use, set the useAndroidSurfaceView property to true. +/// iOS:. If you want to use Flutter Texture, set the useFlutterTexture property to true. +/// macOS and Windows:. abstract class VideoViewControllerBase { /// RtcEngine. RtcEngine get rtcEngine; @@ -18,10 +21,10 @@ abstract class VideoViewControllerBase { /// The connection information. See RtcConnection. RtcConnection? get connection; - /// Whether to use FlutterTexture to render video:true: Use FlutterTexture to render video.false: Do not use FlutterTexture to render video.FlutterTexture applies to iOS, macOS and Windows platforms. + /// Whether to use FlutterTexture to render video: true : Use FlutterTexture to render video. false : Do not use FlutterTexture to render video. FlutterTexture applies to iOS, macOS and Windows platforms. bool get useFlutterTexture; - /// Whether to use Android SurfaceView to render video:true: Use Android SurfaceView to render video.false: Do not use Android SurfaceView to render video.Android SurfaceView applies to Android platform only. + /// Whether to use Android SurfaceView to render video: true : Use Android SurfaceView to render video. false : Do not use Android SurfaceView to render video. Android SurfaceView applies to Android platform only. bool get useAndroidSurfaceView; @internal @@ -53,7 +56,10 @@ abstract class VideoViewControllerBase { /// A AgoraVideoView controller for rendering local and remote video. /// -/// On different platforms, the default view corresponding to this class is different: Android: . If you want to use , set the useAndroidSurfaceView property to true . iOS: . If you want to use Flutter Texture, set the useFlutterTexture property to true . macOS and Windows: . +/// On different platforms, the default view corresponding to this class is different: +/// Android:. If you want to use, set the useAndroidSurfaceView property to true. +/// iOS:. If you want to use Flutter Texture, set the useFlutterTexture property to true. +/// macOS and Windows:. class VideoViewController with VideoViewControllerBaseMixin implements VideoViewControllerBase { diff --git a/macos/agora_rtc_engine.podspec b/macos/agora_rtc_engine.podspec index 627ab5bd2..59afc60d7 100644 --- a/macos/agora_rtc_engine.podspec +++ b/macos/agora_rtc_engine.podspec @@ -21,8 +21,8 @@ A new flutter plugin project. puts '[plugin_dev] Found .plugin_dev file, use vendored_frameworks instead.' s.vendored_frameworks = 'libs/*.framework' else - s.dependency 'AgoraRtcEngine_macOS', '4.2.1' - s.dependency 'AgoraIrisRTC_macOS', '4.2.1-build.1' + s.dependency 'AgoraRtcEngine_macOS', '4.2.2' + s.dependency 'AgoraIrisRTC_macOS', '4.2.2-build.1' end s.platform = :osx, '10.11' diff --git a/pubspec.yaml b/pubspec.yaml index 7fad4ceb4..8ab66df4c 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -17,7 +17,7 @@ dependencies: ffi: '>=1.1.2' async: ^2.8.2 meta: ^1.7.0 - iris_method_channel: 1.1.0 + iris_method_channel: 1.2.0 dev_dependencies: flutter_test: sdk: flutter diff --git a/scripts/artifacts_version.sh b/scripts/artifacts_version.sh index 333576e01..25d2d0eb7 100644 --- a/scripts/artifacts_version.sh +++ b/scripts/artifacts_version.sh @@ -1,6 +1,6 @@ set -e -export IRIS_CDN_URL_ANDROID="https://download.agora.io/sdk/release/iris_4.2.1-build.1_DCG_Android_Video_20230625_1112.zip" -export IRIS_CDN_URL_IOS="https://download.agora.io/sdk/release/iris_4.2.1-build.1_DCG_iOS_Video_20230625_1114.zip" -export IRIS_CDN_URL_MACOS="https://download.agora.io/sdk/release/iris_4.2.1-build.1_DCG_Mac_Video_20230625_1129.zip" -export IRIS_CDN_URL_WINDOWS="https://download.agora.io/sdk/release/iris_4.2.1-build.1_DCG_Windows_Video_20230625_1112.zip" +export IRIS_CDN_URL_ANDROID="https://download.agora.io/sdk/release/iris_4.2.2-build.1_DCG_Android_Video_20230727_1158.zip" +export IRIS_CDN_URL_IOS="https://download.agora.io/sdk/release/iris_4.2.2-build.1_DCG_iOS_Video_20230727_1200.zip" +export IRIS_CDN_URL_MACOS="https://download.agora.io/sdk/release/iris_4.2.2-build.1_DCG_Mac_Video_20230727_1159.zip" +export IRIS_CDN_URL_WINDOWS="https://download.agora.io/sdk/release/iris_4.2.2-build.1_DCG_Windows_Video_20230727_1158.zip" diff --git a/test_shard/fake_test_app/integration_test/generated/mediaengine_audioframeobserver_testcases.generated.dart b/test_shard/fake_test_app/integration_test/generated/mediaengine_audioframeobserver_testcases.generated.dart index d256d4a09..a6288a940 100644 --- a/test_shard/fake_test_app/integration_test/generated/mediaengine_audioframeobserver_testcases.generated.dart +++ b/test_shard/fake_test_app/integration_test/generated/mediaengine_audioframeobserver_testcases.generated.dart @@ -48,6 +48,7 @@ void generatedTestCases(IrisTester irisTester) { Uint8List audioFrameBuffer = Uint8List.fromList([1, 2, 3, 4, 5]); const int audioFrameRenderTimeMs = 10; const int audioFrameAvsyncType = 10; + const int audioFramePresentationMs = 10; final AudioFrame audioFrame = AudioFrame( type: audioFrameType, samplesPerChannel: audioFrameSamplesPerChannel, @@ -57,6 +58,7 @@ void generatedTestCases(IrisTester irisTester) { buffer: audioFrameBuffer, renderTimeMs: audioFrameRenderTimeMs, avsyncType: audioFrameAvsyncType, + presentationMs: audioFramePresentationMs, ); final eventJson = { diff --git a/test_shard/fake_test_app/integration_test/generated/mediaengine_fake_test.generated.dart b/test_shard/fake_test_app/integration_test/generated/mediaengine_fake_test.generated.dart index 6df1cc1a9..7b451b521 100644 --- a/test_shard/fake_test_app/integration_test/generated/mediaengine_fake_test.generated.dart +++ b/test_shard/fake_test_app/integration_test/generated/mediaengine_fake_test.generated.dart @@ -167,6 +167,7 @@ void mediaEngineSmokeTestCases() { Uint8List frameBuffer = Uint8List.fromList([1, 2, 3, 4, 5]); const int frameRenderTimeMs = 10; const int frameAvsyncType = 10; + const int framePresentationMs = 10; final AudioFrame frame = AudioFrame( type: frameType, samplesPerChannel: frameSamplesPerChannel, @@ -176,6 +177,7 @@ void mediaEngineSmokeTestCases() { buffer: frameBuffer, renderTimeMs: frameRenderTimeMs, avsyncType: frameAvsyncType, + presentationMs: framePresentationMs, ); const int trackId = 10; await mediaEngine.pushAudioFrame( @@ -224,6 +226,7 @@ void mediaEngineSmokeTestCases() { Uint8List frameBuffer = Uint8List.fromList([1, 2, 3, 4, 5]); const int frameRenderTimeMs = 10; const int frameAvsyncType = 10; + const int framePresentationMs = 10; final AudioFrame frame = AudioFrame( type: frameType, samplesPerChannel: frameSamplesPerChannel, @@ -233,6 +236,7 @@ void mediaEngineSmokeTestCases() { buffer: frameBuffer, renderTimeMs: frameRenderTimeMs, avsyncType: frameAvsyncType, + presentationMs: framePresentationMs, ); await mediaEngine.pullAudioFrame( frame, diff --git a/test_shard/fake_test_app/integration_test/generated/musiccontentcenter_fake_test.generated.dart b/test_shard/fake_test_app/integration_test/generated/musiccontentcenter_fake_test.generated.dart index 897f128f6..17f86e50e 100644 --- a/test_shard/fake_test_app/integration_test/generated/musiccontentcenter_fake_test.generated.dart +++ b/test_shard/fake_test_app/integration_test/generated/musiccontentcenter_fake_test.generated.dart @@ -149,9 +149,12 @@ void musicContentCenterSmokeTestCases() { MusicContentCenterStatusCode errorCode) {}, onMusicCollectionResult: (String requestId, MusicCollection result, MusicContentCenterStatusCode errorCode) {}, - onLyricResult: (String requestId, String lyricUrl, + onLyricResult: (String requestId, int songCode, String lyricUrl, MusicContentCenterStatusCode errorCode) {}, - onPreLoadEvent: (int songCode, + onSongSimpleInfoResult: (String requestId, int songCode, + String simpleInfo, MusicContentCenterStatusCode errorCode) {}, + onPreLoadEvent: (String requestId, + int songCode, int percent, String lyricUrl, PreloadStatusCode status, @@ -349,10 +352,8 @@ void musicContentCenterSmokeTestCases() { try { const int songCode = 10; - const String jsonOption = "hello"; await musicContentCenter.preload( - songCode: songCode, - jsonOption: jsonOption, + songCode, ); } catch (e) { if (e is! AgoraRtcException) { @@ -521,5 +522,81 @@ void musicContentCenterSmokeTestCases() { }, // skip: !(), ); + + testWidgets( + 'getSongSimpleInfo', + (WidgetTester tester) async { + String engineAppId = const String.fromEnvironment('TEST_APP_ID', + defaultValue: ''); + + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: engineAppId, + areaCode: AreaCode.areaCodeGlob.value(), + )); + + final musicContentCenter = rtcEngine.getMusicContentCenter(); + + try { + const int songCode = 10; + await musicContentCenter.getSongSimpleInfo( + songCode, + ); + } catch (e) { + if (e is! AgoraRtcException) { + debugPrint('[getSongSimpleInfo] error: ${e.toString()}'); + rethrow; + } + + if (e.code != -4) { + // Only not supported error supported. + rethrow; + } + } + + await musicContentCenter.release(); + await rtcEngine.release(); + }, +// skip: !(), + ); + + testWidgets( + 'getInternalSongCode', + (WidgetTester tester) async { + String engineAppId = const String.fromEnvironment('TEST_APP_ID', + defaultValue: ''); + + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: engineAppId, + areaCode: AreaCode.areaCodeGlob.value(), + )); + + final musicContentCenter = rtcEngine.getMusicContentCenter(); + + try { + const int songCode = 10; + const String jsonOption = "hello"; + await musicContentCenter.getInternalSongCode( + songCode: songCode, + jsonOption: jsonOption, + ); + } catch (e) { + if (e is! AgoraRtcException) { + debugPrint('[getInternalSongCode] error: ${e.toString()}'); + rethrow; + } + + if (e.code != -4) { + // Only not supported error supported. + rethrow; + } + } + + await musicContentCenter.release(); + await rtcEngine.release(); + }, +// skip: !(), + ); } diff --git a/test_shard/fake_test_app/integration_test/generated/musiccontentcenter_musiccontentcentereventhandler_testcases.generated.dart b/test_shard/fake_test_app/integration_test/generated/musiccontentcenter_musiccontentcentereventhandler_testcases.generated.dart index c9683d01e..e683e70b5 100644 --- a/test_shard/fake_test_app/integration_test/generated/musiccontentcenter_musiccontentcentereventhandler_testcases.generated.dart +++ b/test_shard/fake_test_app/integration_test/generated/musiccontentcenter_musiccontentcentereventhandler_testcases.generated.dart @@ -147,7 +147,7 @@ void generatedTestCases(IrisTester irisTester) { final onLyricResultCompleter = Completer(); final theMusicContentCenterEventHandler = MusicContentCenterEventHandler( - onLyricResult: (String requestId, String lyricUrl, + onLyricResult: (String requestId, int songCode, String lyricUrl, MusicContentCenterStatusCode errorCode) { onLyricResultCompleter.complete(true); }, @@ -162,12 +162,14 @@ void generatedTestCases(IrisTester irisTester) { { const String requestId = "hello"; + const int songCode = 10; const String lyricUrl = "hello"; const MusicContentCenterStatusCode errorCode = MusicContentCenterStatusCode.kMusicContentCenterStatusOk; final eventJson = { 'requestId': requestId, + 'songCode': songCode, 'lyricUrl': lyricUrl, 'errorCode': errorCode.value(), }; @@ -191,6 +193,69 @@ void generatedTestCases(IrisTester irisTester) { timeout: const Timeout(Duration(minutes: 1)), ); + testWidgets( + 'onSongSimpleInfoResult', + (WidgetTester tester) async { + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: 'app_id', + areaCode: AreaCode.areaCodeGlob.value(), + )); + + final musicContentCenter = rtcEngine.getMusicContentCenter(); + const musicContentCenterConfiguration = MusicContentCenterConfiguration( + appId: 'app_id', token: 'token', mccUid: 10); + await musicContentCenter.initialize(musicContentCenterConfiguration); + + final onSongSimpleInfoResultCompleter = Completer(); + final theMusicContentCenterEventHandler = MusicContentCenterEventHandler( + onSongSimpleInfoResult: (String requestId, int songCode, + String simpleInfo, MusicContentCenterStatusCode errorCode) { + onSongSimpleInfoResultCompleter.complete(true); + }, + ); + + musicContentCenter.registerEventHandler( + theMusicContentCenterEventHandler, + ); + +// Delay 500 milliseconds to ensure the registerEventHandler call completed. + await Future.delayed(const Duration(milliseconds: 500)); + + { + const String requestId = "hello"; + const int songCode = 10; + const String simpleInfo = "hello"; + const MusicContentCenterStatusCode errorCode = + MusicContentCenterStatusCode.kMusicContentCenterStatusOk; + + final eventJson = { + 'requestId': requestId, + 'songCode': songCode, + 'simpleInfo': simpleInfo, + 'errorCode': errorCode.value(), + }; + + irisTester.fireEvent( + 'MusicContentCenterEventHandler_onSongSimpleInfoResult', + params: eventJson); + } + + final eventCalled = await onSongSimpleInfoResultCompleter.future; + expect(eventCalled, isTrue); + + { + musicContentCenter.unregisterEventHandler(); + } +// Delay 500 milliseconds to ensure the unregisterEventHandler call completed. + await Future.delayed(const Duration(milliseconds: 500)); + + await musicContentCenter.release(); + await rtcEngine.release(); + }, + timeout: const Timeout(Duration(minutes: 1)), + ); + testWidgets( 'onPreLoadEvent', (WidgetTester tester) async { @@ -207,8 +272,12 @@ void generatedTestCases(IrisTester irisTester) { final onPreLoadEventCompleter = Completer(); final theMusicContentCenterEventHandler = MusicContentCenterEventHandler( - onPreLoadEvent: (int songCode, int percent, String lyricUrl, - PreloadStatusCode status, MusicContentCenterStatusCode errorCode) { + onPreLoadEvent: (String requestId, + int songCode, + int percent, + String lyricUrl, + PreloadStatusCode status, + MusicContentCenterStatusCode errorCode) { onPreLoadEventCompleter.complete(true); }, ); @@ -221,6 +290,7 @@ void generatedTestCases(IrisTester irisTester) { await Future.delayed(const Duration(milliseconds: 500)); { + const String requestId = "hello"; const int songCode = 10; const int percent = 10; const String lyricUrl = "hello"; @@ -230,6 +300,7 @@ void generatedTestCases(IrisTester irisTester) { MusicContentCenterStatusCode.kMusicContentCenterStatusOk; final eventJson = { + 'requestId': requestId, 'songCode': songCode, 'percent': percent, 'lyricUrl': lyricUrl, diff --git a/test_shard/fake_test_app/integration_test/generated/rtcengine_fake_test.generated.dart b/test_shard/fake_test_app/integration_test/generated/rtcengine_fake_test.generated.dart index 3cec4ae77..5a66381c6 100644 --- a/test_shard/fake_test_app/integration_test/generated/rtcengine_fake_test.generated.dart +++ b/test_shard/fake_test_app/integration_test/generated/rtcengine_fake_test.generated.dart @@ -171,6 +171,113 @@ void rtcEngineSmokeTestCases() { }, ); + testWidgets( + 'preloadChannel', + (WidgetTester tester) async { + String engineAppId = const String.fromEnvironment('TEST_APP_ID', + defaultValue: ''); + + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: engineAppId, + areaCode: AreaCode.areaCodeGlob.value(), + )); + + try { + const String token = "hello"; + const String channelId = "hello"; + const int uid = 10; + await rtcEngine.preloadChannel( + token: token, + channelId: channelId, + uid: uid, + ); + } catch (e) { + if (e is! AgoraRtcException) { + debugPrint('[preloadChannel] error: ${e.toString()}'); + rethrow; + } + + if (e.code != -4) { + // Only not supported error supported. + rethrow; + } + } + + await rtcEngine.release(); + }, + ); + + testWidgets( + 'preloadChannelWithUserAccount', + (WidgetTester tester) async { + String engineAppId = const String.fromEnvironment('TEST_APP_ID', + defaultValue: ''); + + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: engineAppId, + areaCode: AreaCode.areaCodeGlob.value(), + )); + + try { + const String token = "hello"; + const String channelId = "hello"; + const String userAccount = "hello"; + await rtcEngine.preloadChannelWithUserAccount( + token: token, + channelId: channelId, + userAccount: userAccount, + ); + } catch (e) { + if (e is! AgoraRtcException) { + debugPrint('[preloadChannelWithUserAccount] error: ${e.toString()}'); + rethrow; + } + + if (e.code != -4) { + // Only not supported error supported. + rethrow; + } + } + + await rtcEngine.release(); + }, + ); + + testWidgets( + 'updatePreloadChannelToken', + (WidgetTester tester) async { + String engineAppId = const String.fromEnvironment('TEST_APP_ID', + defaultValue: ''); + + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: engineAppId, + areaCode: AreaCode.areaCodeGlob.value(), + )); + + try { + const String token = "hello"; + await rtcEngine.updatePreloadChannelToken( + token, + ); + } catch (e) { + if (e is! AgoraRtcException) { + debugPrint('[updatePreloadChannelToken] error: ${e.toString()}'); + rethrow; + } + + if (e.code != -4) { + // Only not supported error supported. + rethrow; + } + } + + await rtcEngine.release(); + }, + ); + testWidgets( 'joinChannel', (WidgetTester tester) async { @@ -197,11 +304,15 @@ void rtcEngineSmokeTestCases() { ChannelProfileType.channelProfileCommunication; const bool optionsPublishCameraTrack = true; const bool optionsPublishSecondaryCameraTrack = true; + const bool optionsPublishThirdCameraTrack = true; + const bool optionsPublishFourthCameraTrack = true; const bool optionsPublishMicrophoneTrack = true; const bool optionsPublishScreenCaptureVideo = true; const bool optionsPublishScreenCaptureAudio = true; const bool optionsPublishScreenTrack = true; const bool optionsPublishSecondaryScreenTrack = true; + const bool optionsPublishThirdScreenTrack = true; + const bool optionsPublishFourthScreenTrack = true; const bool optionsPublishCustomAudioTrack = true; const int optionsPublishCustomAudioTrackId = 10; const bool optionsPublishCustomVideoTrack = true; @@ -224,11 +335,15 @@ void rtcEngineSmokeTestCases() { const ChannelMediaOptions options = ChannelMediaOptions( publishCameraTrack: optionsPublishCameraTrack, publishSecondaryCameraTrack: optionsPublishSecondaryCameraTrack, + publishThirdCameraTrack: optionsPublishThirdCameraTrack, + publishFourthCameraTrack: optionsPublishFourthCameraTrack, publishMicrophoneTrack: optionsPublishMicrophoneTrack, publishScreenCaptureVideo: optionsPublishScreenCaptureVideo, publishScreenCaptureAudio: optionsPublishScreenCaptureAudio, publishScreenTrack: optionsPublishScreenTrack, publishSecondaryScreenTrack: optionsPublishSecondaryScreenTrack, + publishThirdScreenTrack: optionsPublishThirdScreenTrack, + publishFourthScreenTrack: optionsPublishFourthScreenTrack, publishCustomAudioTrack: optionsPublishCustomAudioTrack, publishCustomAudioTrackId: optionsPublishCustomAudioTrackId, publishCustomVideoTrack: optionsPublishCustomVideoTrack, @@ -298,11 +413,15 @@ void rtcEngineSmokeTestCases() { ChannelProfileType.channelProfileCommunication; const bool optionsPublishCameraTrack = true; const bool optionsPublishSecondaryCameraTrack = true; + const bool optionsPublishThirdCameraTrack = true; + const bool optionsPublishFourthCameraTrack = true; const bool optionsPublishMicrophoneTrack = true; const bool optionsPublishScreenCaptureVideo = true; const bool optionsPublishScreenCaptureAudio = true; const bool optionsPublishScreenTrack = true; const bool optionsPublishSecondaryScreenTrack = true; + const bool optionsPublishThirdScreenTrack = true; + const bool optionsPublishFourthScreenTrack = true; const bool optionsPublishCustomAudioTrack = true; const int optionsPublishCustomAudioTrackId = 10; const bool optionsPublishCustomVideoTrack = true; @@ -325,11 +444,15 @@ void rtcEngineSmokeTestCases() { const ChannelMediaOptions options = ChannelMediaOptions( publishCameraTrack: optionsPublishCameraTrack, publishSecondaryCameraTrack: optionsPublishSecondaryCameraTrack, + publishThirdCameraTrack: optionsPublishThirdCameraTrack, + publishFourthCameraTrack: optionsPublishFourthCameraTrack, publishMicrophoneTrack: optionsPublishMicrophoneTrack, publishScreenCaptureVideo: optionsPublishScreenCaptureVideo, publishScreenCaptureAudio: optionsPublishScreenCaptureAudio, publishScreenTrack: optionsPublishScreenTrack, publishSecondaryScreenTrack: optionsPublishSecondaryScreenTrack, + publishThirdScreenTrack: optionsPublishThirdScreenTrack, + publishFourthScreenTrack: optionsPublishFourthScreenTrack, publishCustomAudioTrack: optionsPublishCustomAudioTrack, publishCustomAudioTrackId: optionsPublishCustomAudioTrackId, publishCustomVideoTrack: optionsPublishCustomVideoTrack, @@ -1181,11 +1304,13 @@ void rtcEngineSmokeTestCases() { ); const int canvasView = 10; const int canvasUid = 10; + const int canvasBackgroundColor = 10; const int canvasMediaPlayerId = 10; const bool canvasEnableAlphaMask = true; const VideoCanvas canvas = VideoCanvas( view: canvasView, uid: canvasUid, + backgroundColor: canvasBackgroundColor, renderMode: canvasRenderMode, mirrorMode: canvasMirrorMode, setupMode: canvasSetupMode, @@ -1245,11 +1370,13 @@ void rtcEngineSmokeTestCases() { ); const int canvasView = 10; const int canvasUid = 10; + const int canvasBackgroundColor = 10; const int canvasMediaPlayerId = 10; const bool canvasEnableAlphaMask = true; const VideoCanvas canvas = VideoCanvas( view: canvasView, uid: canvasUid, + backgroundColor: canvasBackgroundColor, renderMode: canvasRenderMode, mirrorMode: canvasMirrorMode, setupMode: canvasSetupMode, @@ -3895,10 +4022,7 @@ void rtcEngineSmokeTestCases() { )); try { - const String requestId = "hello"; - await rtcEngine.uploadLogFile( - requestId, - ); + await rtcEngine.uploadLogFile(); } catch (e) { if (e is! AgoraRtcException) { debugPrint('[uploadLogFile] error: ${e.toString()}'); @@ -5647,6 +5771,69 @@ void rtcEngineSmokeTestCases() { }, ); + testWidgets( + 'isCameraExposureSupported', + (WidgetTester tester) async { + String engineAppId = const String.fromEnvironment('TEST_APP_ID', + defaultValue: ''); + + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: engineAppId, + areaCode: AreaCode.areaCodeGlob.value(), + )); + + try { + await rtcEngine.isCameraExposureSupported(); + } catch (e) { + if (e is! AgoraRtcException) { + debugPrint('[isCameraExposureSupported] error: ${e.toString()}'); + rethrow; + } + + if (e.code != -4) { + // Only not supported error supported. + rethrow; + } + } + + await rtcEngine.release(); + }, + ); + + testWidgets( + 'setCameraExposureFactor', + (WidgetTester tester) async { + String engineAppId = const String.fromEnvironment('TEST_APP_ID', + defaultValue: ''); + + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: engineAppId, + areaCode: AreaCode.areaCodeGlob.value(), + )); + + try { + const double factor = 10.0; + await rtcEngine.setCameraExposureFactor( + factor, + ); + } catch (e) { + if (e is! AgoraRtcException) { + debugPrint('[setCameraExposureFactor] error: ${e.toString()}'); + rethrow; + } + + if (e.code != -4) { + // Only not supported error supported. + rethrow; + } + } + + await rtcEngine.release(); + }, + ); + testWidgets( 'isCameraAutoExposureFaceModeSupported', (WidgetTester tester) async { @@ -5809,6 +5996,39 @@ void rtcEngineSmokeTestCases() { }, ); + testWidgets( + 'setRouteInCommunicationMode', + (WidgetTester tester) async { + String engineAppId = const String.fromEnvironment('TEST_APP_ID', + defaultValue: ''); + + RtcEngine rtcEngine = createAgoraRtcEngine(); + await rtcEngine.initialize(RtcEngineContext( + appId: engineAppId, + areaCode: AreaCode.areaCodeGlob.value(), + )); + + try { + const int route = 10; + await rtcEngine.setRouteInCommunicationMode( + route, + ); + } catch (e) { + if (e is! AgoraRtcException) { + debugPrint('[setRouteInCommunicationMode] error: ${e.toString()}'); + rethrow; + } + + if (e.code != -4) { + // Only not supported error supported. + rethrow; + } + } + + await rtcEngine.release(); + }, + ); + testWidgets( 'getScreenCaptureSources', (WidgetTester tester) async { @@ -7397,7 +7617,7 @@ void rtcEngineSmokeTestCases() { onFirstLocalVideoFrame: (VideoSourceType source, int width, int height, int elapsed) {}, onFirstLocalVideoFramePublished: - (RtcConnection connection, int elapsed) {}, + (VideoSourceType source, int elapsed) {}, onFirstRemoteVideoDecoded: (RtcConnection connection, int remoteUid, int width, int height, int elapsed) {}, onVideoSizeChanged: (RtcConnection connection, @@ -7433,8 +7653,7 @@ void rtcEngineSmokeTestCases() { (RtcConnection connection, LocalAudioStats stats) {}, onRemoteAudioStats: (RtcConnection connection, RemoteAudioStats stats) {}, - onLocalVideoStats: - (RtcConnection connection, LocalVideoStats stats) {}, + onLocalVideoStats: (VideoSourceType source, LocalVideoStats stats) {}, onRemoteVideoStats: (RtcConnection connection, RemoteVideoStats stats) {}, onCameraReady: () {}, @@ -7610,7 +7829,7 @@ void rtcEngineSmokeTestCases() { onFirstLocalVideoFrame: (VideoSourceType source, int width, int height, int elapsed) {}, onFirstLocalVideoFramePublished: - (RtcConnection connection, int elapsed) {}, + (VideoSourceType source, int elapsed) {}, onFirstRemoteVideoDecoded: (RtcConnection connection, int remoteUid, int width, int height, int elapsed) {}, onVideoSizeChanged: (RtcConnection connection, @@ -7646,8 +7865,7 @@ void rtcEngineSmokeTestCases() { (RtcConnection connection, LocalAudioStats stats) {}, onRemoteAudioStats: (RtcConnection connection, RemoteAudioStats stats) {}, - onLocalVideoStats: - (RtcConnection connection, LocalVideoStats stats) {}, + onLocalVideoStats: (VideoSourceType source, LocalVideoStats stats) {}, onRemoteVideoStats: (RtcConnection connection, RemoteVideoStats stats) {}, onCameraReady: () {}, @@ -8450,11 +8668,15 @@ void rtcEngineSmokeTestCases() { ChannelProfileType.channelProfileCommunication; const bool optionsPublishCameraTrack = true; const bool optionsPublishSecondaryCameraTrack = true; + const bool optionsPublishThirdCameraTrack = true; + const bool optionsPublishFourthCameraTrack = true; const bool optionsPublishMicrophoneTrack = true; const bool optionsPublishScreenCaptureVideo = true; const bool optionsPublishScreenCaptureAudio = true; const bool optionsPublishScreenTrack = true; const bool optionsPublishSecondaryScreenTrack = true; + const bool optionsPublishThirdScreenTrack = true; + const bool optionsPublishFourthScreenTrack = true; const bool optionsPublishCustomAudioTrack = true; const int optionsPublishCustomAudioTrackId = 10; const bool optionsPublishCustomVideoTrack = true; @@ -8477,11 +8699,15 @@ void rtcEngineSmokeTestCases() { const ChannelMediaOptions options = ChannelMediaOptions( publishCameraTrack: optionsPublishCameraTrack, publishSecondaryCameraTrack: optionsPublishSecondaryCameraTrack, + publishThirdCameraTrack: optionsPublishThirdCameraTrack, + publishFourthCameraTrack: optionsPublishFourthCameraTrack, publishMicrophoneTrack: optionsPublishMicrophoneTrack, publishScreenCaptureVideo: optionsPublishScreenCaptureVideo, publishScreenCaptureAudio: optionsPublishScreenCaptureAudio, publishScreenTrack: optionsPublishScreenTrack, publishSecondaryScreenTrack: optionsPublishSecondaryScreenTrack, + publishThirdScreenTrack: optionsPublishThirdScreenTrack, + publishFourthScreenTrack: optionsPublishFourthScreenTrack, publishCustomAudioTrack: optionsPublishCustomAudioTrack, publishCustomAudioTrackId: optionsPublishCustomAudioTrackId, publishCustomVideoTrack: optionsPublishCustomVideoTrack, @@ -8554,11 +8780,15 @@ void rtcEngineSmokeTestCases() { ChannelProfileType.channelProfileCommunication; const bool optionsPublishCameraTrack = true; const bool optionsPublishSecondaryCameraTrack = true; + const bool optionsPublishThirdCameraTrack = true; + const bool optionsPublishFourthCameraTrack = true; const bool optionsPublishMicrophoneTrack = true; const bool optionsPublishScreenCaptureVideo = true; const bool optionsPublishScreenCaptureAudio = true; const bool optionsPublishScreenTrack = true; const bool optionsPublishSecondaryScreenTrack = true; + const bool optionsPublishThirdScreenTrack = true; + const bool optionsPublishFourthScreenTrack = true; const bool optionsPublishCustomAudioTrack = true; const int optionsPublishCustomAudioTrackId = 10; const bool optionsPublishCustomVideoTrack = true; @@ -8581,11 +8811,15 @@ void rtcEngineSmokeTestCases() { const ChannelMediaOptions options = ChannelMediaOptions( publishCameraTrack: optionsPublishCameraTrack, publishSecondaryCameraTrack: optionsPublishSecondaryCameraTrack, + publishThirdCameraTrack: optionsPublishThirdCameraTrack, + publishFourthCameraTrack: optionsPublishFourthCameraTrack, publishMicrophoneTrack: optionsPublishMicrophoneTrack, publishScreenCaptureVideo: optionsPublishScreenCaptureVideo, publishScreenCaptureAudio: optionsPublishScreenCaptureAudio, publishScreenTrack: optionsPublishScreenTrack, publishSecondaryScreenTrack: optionsPublishSecondaryScreenTrack, + publishThirdScreenTrack: optionsPublishThirdScreenTrack, + publishFourthScreenTrack: optionsPublishFourthScreenTrack, publishCustomAudioTrack: optionsPublishCustomAudioTrack, publishCustomAudioTrackId: optionsPublishCustomAudioTrackId, publishCustomVideoTrack: optionsPublishCustomVideoTrack, diff --git a/test_shard/fake_test_app/integration_test/generated/rtcengine_rtcengineeventhandler_testcases.generated.dart b/test_shard/fake_test_app/integration_test/generated/rtcengine_rtcengineeventhandler_testcases.generated.dart index 8fe926ca8..d4d9ff163 100644 --- a/test_shard/fake_test_app/integration_test/generated/rtcengine_rtcengineeventhandler_testcases.generated.dart +++ b/test_shard/fake_test_app/integration_test/generated/rtcengine_rtcengineeventhandler_testcases.generated.dart @@ -1354,8 +1354,7 @@ void generatedTestCases(IrisTester irisTester) { final onFirstLocalVideoFramePublishedCompleter = Completer(); final theRtcEngineEventHandler = RtcEngineEventHandler( - onFirstLocalVideoFramePublished: - (RtcConnection connection, int elapsed) { + onFirstLocalVideoFramePublished: (VideoSourceType source, int elapsed) { onFirstLocalVideoFramePublishedCompleter.complete(true); }, ); @@ -1368,16 +1367,11 @@ void generatedTestCases(IrisTester irisTester) { await Future.delayed(const Duration(milliseconds: 500)); { - const String connectionChannelId = "hello"; - const int connectionLocalUid = 10; - const RtcConnection connection = RtcConnection( - channelId: connectionChannelId, - localUid: connectionLocalUid, - ); + const VideoSourceType source = VideoSourceType.videoSourceCameraPrimary; const int elapsed = 10; final eventJson = { - 'connection': connection.toJson(), + 'source': source.value(), 'elapsed': elapsed, }; @@ -2352,7 +2346,7 @@ void generatedTestCases(IrisTester irisTester) { final onLocalVideoStatsCompleter = Completer(); final theRtcEngineEventHandler = RtcEngineEventHandler( - onLocalVideoStats: (RtcConnection connection, LocalVideoStats stats) { + onLocalVideoStats: (VideoSourceType source, LocalVideoStats stats) { onLocalVideoStatsCompleter.complete(true); }, ); @@ -2365,12 +2359,7 @@ void generatedTestCases(IrisTester irisTester) { await Future.delayed(const Duration(milliseconds: 500)); { - const String connectionChannelId = "hello"; - const int connectionLocalUid = 10; - const RtcConnection connection = RtcConnection( - channelId: connectionChannelId, - localUid: connectionLocalUid, - ); + const VideoSourceType source = VideoSourceType.videoSourceCameraPrimary; const QualityAdaptIndication statsQualityAdaptIndication = QualityAdaptIndication.adaptNone; const VideoCodecType statsCodecType = VideoCodecType.videoCodecNone; @@ -2423,7 +2412,7 @@ void generatedTestCases(IrisTester irisTester) { ); final eventJson = { - 'connection': connection.toJson(), + 'source': source.value(), 'stats': stats.toJson(), }; diff --git a/test_shard/fake_test_app/integration_test/generated/rtcengineex_fake_test.generated.dart b/test_shard/fake_test_app/integration_test/generated/rtcengineex_fake_test.generated.dart index 0ef99e739..7e209f5f1 100644 --- a/test_shard/fake_test_app/integration_test/generated/rtcengineex_fake_test.generated.dart +++ b/test_shard/fake_test_app/integration_test/generated/rtcengineex_fake_test.generated.dart @@ -41,11 +41,15 @@ void rtcEngineExSmokeTestCases() { ChannelProfileType.channelProfileCommunication; const bool optionsPublishCameraTrack = true; const bool optionsPublishSecondaryCameraTrack = true; + const bool optionsPublishThirdCameraTrack = true; + const bool optionsPublishFourthCameraTrack = true; const bool optionsPublishMicrophoneTrack = true; const bool optionsPublishScreenCaptureVideo = true; const bool optionsPublishScreenCaptureAudio = true; const bool optionsPublishScreenTrack = true; const bool optionsPublishSecondaryScreenTrack = true; + const bool optionsPublishThirdScreenTrack = true; + const bool optionsPublishFourthScreenTrack = true; const bool optionsPublishCustomAudioTrack = true; const int optionsPublishCustomAudioTrackId = 10; const bool optionsPublishCustomVideoTrack = true; @@ -68,11 +72,15 @@ void rtcEngineExSmokeTestCases() { const ChannelMediaOptions options = ChannelMediaOptions( publishCameraTrack: optionsPublishCameraTrack, publishSecondaryCameraTrack: optionsPublishSecondaryCameraTrack, + publishThirdCameraTrack: optionsPublishThirdCameraTrack, + publishFourthCameraTrack: optionsPublishFourthCameraTrack, publishMicrophoneTrack: optionsPublishMicrophoneTrack, publishScreenCaptureVideo: optionsPublishScreenCaptureVideo, publishScreenCaptureAudio: optionsPublishScreenCaptureAudio, publishScreenTrack: optionsPublishScreenTrack, publishSecondaryScreenTrack: optionsPublishSecondaryScreenTrack, + publishThirdScreenTrack: optionsPublishThirdScreenTrack, + publishFourthScreenTrack: optionsPublishFourthScreenTrack, publishCustomAudioTrack: optionsPublishCustomAudioTrack, publishCustomAudioTrackId: optionsPublishCustomAudioTrackId, publishCustomVideoTrack: optionsPublishCustomVideoTrack, @@ -190,11 +198,15 @@ void rtcEngineExSmokeTestCases() { ChannelProfileType.channelProfileCommunication; const bool optionsPublishCameraTrack = true; const bool optionsPublishSecondaryCameraTrack = true; + const bool optionsPublishThirdCameraTrack = true; + const bool optionsPublishFourthCameraTrack = true; const bool optionsPublishMicrophoneTrack = true; const bool optionsPublishScreenCaptureVideo = true; const bool optionsPublishScreenCaptureAudio = true; const bool optionsPublishScreenTrack = true; const bool optionsPublishSecondaryScreenTrack = true; + const bool optionsPublishThirdScreenTrack = true; + const bool optionsPublishFourthScreenTrack = true; const bool optionsPublishCustomAudioTrack = true; const int optionsPublishCustomAudioTrackId = 10; const bool optionsPublishCustomVideoTrack = true; @@ -217,11 +229,15 @@ void rtcEngineExSmokeTestCases() { const ChannelMediaOptions options = ChannelMediaOptions( publishCameraTrack: optionsPublishCameraTrack, publishSecondaryCameraTrack: optionsPublishSecondaryCameraTrack, + publishThirdCameraTrack: optionsPublishThirdCameraTrack, + publishFourthCameraTrack: optionsPublishFourthCameraTrack, publishMicrophoneTrack: optionsPublishMicrophoneTrack, publishScreenCaptureVideo: optionsPublishScreenCaptureVideo, publishScreenCaptureAudio: optionsPublishScreenCaptureAudio, publishScreenTrack: optionsPublishScreenTrack, publishSecondaryScreenTrack: optionsPublishSecondaryScreenTrack, + publishThirdScreenTrack: optionsPublishThirdScreenTrack, + publishFourthScreenTrack: optionsPublishFourthScreenTrack, publishCustomAudioTrack: optionsPublishCustomAudioTrack, publishCustomAudioTrackId: optionsPublishCustomAudioTrackId, publishCustomVideoTrack: optionsPublishCustomVideoTrack, @@ -380,11 +396,13 @@ void rtcEngineExSmokeTestCases() { ); const int canvasView = 10; const int canvasUid = 10; + const int canvasBackgroundColor = 10; const int canvasMediaPlayerId = 10; const bool canvasEnableAlphaMask = true; const VideoCanvas canvas = VideoCanvas( view: canvasView, uid: canvasUid, + backgroundColor: canvasBackgroundColor, renderMode: canvasRenderMode, mirrorMode: canvasMirrorMode, setupMode: canvasSetupMode, diff --git a/tool/terra/terra_config_main.yaml b/tool/terra/terra_config_main.yaml index 3d9b61934..e085d4030 100644 --- a/tool/terra/terra_config_main.yaml +++ b/tool/terra/terra_config_main.yaml @@ -1,4 +1,4 @@ -include: shared:rtc_4.2.0/shared_configs.yaml +include: shared:rtc_4.2.2/shared_configs.yaml language: dart diff --git a/windows/CMakeLists.txt b/windows/CMakeLists.txt index 16f50674d..d8c469fc8 100644 --- a/windows/CMakeLists.txt +++ b/windows/CMakeLists.txt @@ -12,8 +12,8 @@ project(${PROJECT_NAME} LANGUAGES CXX) # not be changed set(PLUGIN_NAME "agora_rtc_engine_plugin") -set(IRIS_SDK_DOWNLOAD_URL "https://download.agora.io/sdk/release/iris_4.2.1-build.1_DCG_Windows_Video_20230625_1112.zip") -set(IRIS_SDK_DOWNLOAD_NAME "iris_4.2.1-build.1_DCG_Windows") +set(IRIS_SDK_DOWNLOAD_URL "https://download.agora.io/sdk/release/iris_4.2.2-build.1_DCG_Windows_Video_20230727_1158.zip") +set(IRIS_SDK_DOWNLOAD_NAME "iris_4.2.2-build.1_DCG_Windows") set(RTC_SDK_DOWNLOAD_NAME "Agora_Native_SDK_for_Windows_FULL") set(IRIS_SDK_VERSION "v3_6_2_fix.1")