diff --git a/src/common/Classes.ts b/src/common/Classes.ts index d0ae1739..8e234b99 100644 --- a/src/common/Classes.ts +++ b/src/common/Classes.ts @@ -848,15 +848,19 @@ export class LiveInjectStreamConfig { */ export class CameraCapturerConfiguration { /** - * The camera capturer configuration. + * The camera capture preference. */ preference: CameraCaptureOutputPreference; /** - * Camera Capture Width + * The width (px) of the video image captured by the local camera. To customize the width of the video image, set `preference` as [`Manual`]{@link CameraCaptureOutputPreference.Manual} first, and then use `captureWidth`. + * + * @since v3.3.1. */ captureWidth?: number; /** - * Camera Capture Height + * The height (px) of the video image captured by the local camera. To customize the height of the video image, set `preference` as [`Manual`]{@link CameraCaptureOutputPreference.Manual} first, and then use `captureHeight`. + * + * @since v3.3.1. */ captureHeight?: number; /** @@ -1011,10 +1015,18 @@ export interface RtcStats { rxPacketLossRate: number; /** * System CPU usage (%). + * + * **Note** + * + * The `cpuTotalUsage` reported in the `LeaveChannel` callback is always 0. */ cpuTotalUsage: number; /** * Application CPU usage (%). + * + * **Note** + * + * The `cpuAppUsage` reported in the `LeaveChannel` callback is always 0. */ cpuAppUsage: number; /** @@ -1229,7 +1241,9 @@ export interface LocalVideoStats { */ captureFrameRate: number; /** - * The capture brightness level type. + * The brightness level of the video image captured by the local camera. See [`CaptureBrightnessLevelType`]{@link CaptureBrightnessLevelType}. + * + * @since v3.3.1. */ captureBrightnessLevel: CaptureBrightnessLevelType; } @@ -1294,15 +1308,34 @@ export interface RemoteAudioStats { */ publishDuration: number; /** - * Experience quality: #EXPERIENCE_QUALITY_TYPE + * Quality of experience (QoE) of the local user when receiving a remote audio stream. See [`ExperienceQualityType`]{@link ExperienceQualityType}. + * + * @since 3.3.1. */ qoeQuality: ExperienceQualityType; /** - * The reason for poor experience quality: #EXPERIENCE_POOR_REASON + * The reason for poor QoE of the local user when receiving a remote audio stream. See [`ExperiencePoorReason`]{@link ExperiencePoorReason}. + * + * @since 3.3.1. */ qualityChangedReason: ExperiencePoorReason; /** * The quality of the remote audio stream as determined by the Agora real-time audio MOS (Mean Opinion Score) measurement method in the reported interval. The return value ranges from 0 to 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. + * + * @since v3.3.1. + * + * 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. | + * */ mosValue: number; } @@ -1420,20 +1453,28 @@ export class ClientRoleOptions { } /** - * TODO(DOC) - * Definition of LogConfiguration + * Log file configurations. + * + * @since v3.3.1. */ export class LogConfig { /** - * The log file path, default is NULL for default log path + * The absolute path of log files. The default file path is as follows: + * - Android: `/storage/emulated/0/Android/data//files/agorasdk.log` + * - iOS: `App Sandbox/Library/caches/agorasdk.log` + * Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files. */ filePath?: string; /** - * The log file size, KB , set -1 to use default log size + * The size (KB) of a log file. The default value is 1024 KB. If you set `fileSize` to 1024 KB, the SDK outputs at most 5 MB log files; if you set it to less than 1024 KB, the setting is invalid, and the maximum size of a log file is still 1024 KB. */ fileSize?: number; /** - * The log level, set LOG_LEVEL_INFO to use default log level + * The output log level of the SDK. + * + * For example, if you set the log level to `WARN`, the SDK outputs the logs within levels `FATAL`, `ERROR`, and `WARN`. + * + * See [`LogLevel`]{@link enum LogLevel}. */ level?: LogLevel; @@ -1451,16 +1492,32 @@ export class LogConfig { } /** - * TODO(DOC) - * Data stream config + * The configurations for the data stream. + * + * @since v3.3.1 + * + * | `syncWithAudio` | `ordered` | SDK behaviors | + * | :-------------- | :-------- | :----------------------------------------------------------- | + * | `false` | `false` | The SDK triggers the `onStreamMessage` callback immediately after the receiver receives a data packet. | + * | `true` | `false` | . | + * | `false` | `true` | | + * | `true` | `true` | | */ export class DataStreamConfig { /** - * syncWithAudio Sets whether or not the recipients receive the data stream sync with current audio stream. + * 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 range, the SDK triggers the [`StreamMessage`]{@link RtcEngineEvents.StreamMessage} 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. */ syncWithAudio?: boolean; /** - * ordered Sets whether or not the recipients receive the data stream in the sent order: + * 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 to `true` if you need the receiver to receive the data immediately. */ ordered?: boolean; @@ -1473,8 +1530,9 @@ export class DataStreamConfig { } /** - * TODO(DOC) - * Definition of RtcEngineConfig. + * Configurations for the [`RtcEngine`]{@link RtcEngine}. + * + * @since v3.3.1 */ export class RtcEngineConfig { /** @@ -1487,13 +1545,18 @@ export class RtcEngineConfig { /** * The region for connection. This advanced feature applies to scenarios that have regional restrictions. * - * For the regions that Agora supports, see #AREA_CODE. After specifying the region, the SDK connects to the Agora servers within that region. + * For the regions that Agora supports, see [`AreaCode`]{@link enum.AreaCode}. + * + * After specifying the region, the SDK connects to the Agora servers within that region. * - * @note The SDK supports specify only one region. */ areaCode?: AreaCode; /** - * The config for custumer set log path, log size and log level + * The configuration of the log files that the SDK outputs. See [`LogConfig`]{@link class.LogConfig}. + * + * By default, the SDK outputs five log files, `agorasdk.log`, `agorasdk_1.log`, `agorasdk_2.log`, `agorasdk_3.log`, `agorasdk_4.log`, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in `agorasdk.log`. When `agorasdk.log` is full, the SDK deletes the log file with the earliest modification time among the other four, renames `agorasdk.log` to the name of the deleted log file, and creates a new `agorasdk.log` to record latest logs. + * + * The log file records all log data for the SDK’s operation. Ensure that the directory for the log file exists and is writable. */ logConfig?: LogConfig; diff --git a/src/common/Enums.ts b/src/common/Enums.ts index abab3d1e..e3869d6b 100644 --- a/src/common/Enums.ts +++ b/src/common/Enums.ts @@ -452,15 +452,15 @@ export enum AudioReverbType { */ export enum AudioSampleRateType { /** - * 32000: 32 kHz. + * 32000: (Default) 32000. */ Type32000 = 32000, /** - * 44100: 44.1 kHz. + * 44100: 44100. */ Type44100 = 44100, /** - * 48000: 48 kHz. + * 48000: 48000. */ Type48000 = 48000, } @@ -590,7 +590,7 @@ export enum AudioVoiceChanger { } /** - * The camera capturer configuration. + * The camera capture preference. */ export enum CameraCaptureOutputPreference { /** @@ -606,7 +606,9 @@ export enum CameraCaptureOutputPreference { */ Preview = 2, /** - * 3: Capture Dimensions determined by user. + * 3: Allows you to customize the width and height of the video image captured by the local camera. + * + * @since v3.3.1 */ Manual = 3, } @@ -859,7 +861,7 @@ export enum ConnectionChangedReason { */ KeepAliveTimeout = 14, /** - * 15: In cloud proxy mode, the proxy server connection interrupted. + * 15: In cloud proxy mode, the proxy server connection is interrupted. */ ProxyServerInterrupted = 15, } @@ -951,10 +953,14 @@ export enum EncryptionMode { SM4128ECB = 4, /** * 5: 128-bit AES encryption, GCM mode. + * + * @since v3.3.1 */ AES128GCM = 5, /** * 6: 256-bit AES encryption, GCM mode. + * + * @since v3.3.1 */ AES256GCM = 6, } @@ -1178,7 +1184,9 @@ export enum ErrorCode { */ PublishStreamFormatNotSuppported = 156, /** - * 157: The App lack necessary library file. Check whether the dynamic library is loaded. + * 157: The extension library is not integrated, such as the library for enabling deep-learning noise reduction. + * + * @since v3.3.1 */ ModuleNotFound = 157, /** @@ -1419,11 +1427,15 @@ export enum LocalVideoStreamError { */ EncodeFailure = 5, /** - * 6: Capture InBackground. + * 6: (iOS only) The application is in the background. + * + * @since v3.3.1 */ CaptureInBackground = 6, /** - * 7: Capture MultipleForegroundApps. + * 7: (iOS only) The application is running in Slide Over, Split View, or Picture in Picture mode. + * + * @since v3.3.1 */ CaptureMultipleForegroundApps = 7, } @@ -2647,8 +2659,14 @@ export enum VoiceBeautifierPreset { */ ChatBeautifierVitality = 0x01010300, + /** - * TODO(DOC) + * Singing beautifier effect. + * + * - If you call [`setVoiceBeautifierPreset(SingingBeautifier)`]{@link setVoiceBeautifierPreset}, you can beautify a male-sounding voice and add a reverberation effect that sounds like singing in a small room. Agora recommends not using `setVoiceBeautifierPreset(SingingBeautifier)` to process a female-sounding voice; otherwise, you may experience vocal distortion. + * - If you call [`setVoiceBeautifierParameters(SINGING_BEAUTIFIER, param1, param2)`]{@link setVoiceBeautifierParameters}, you can beautify a male- or female-sounding voice and add a reverberation effect. + * + * @since v3.3.1 */ SingingBeautifier = 0x01020100, @@ -2713,39 +2731,46 @@ export enum AudienceLatencyLevelType { } /** - * TODO(DOC) + * Log Level. + * + * @since v3.3.1. */ export enum LogLevel { /** - * 0: Do not output any log information. + * 0: Do not output any log. */ None = 0x0000, /** - * 0x000f: Output CRITICAL, ERROR, WARNING, and INFO level log information. - * We recommend setting your log filter as this level. + * 0x0001: (Default) Output logs of the FATAL, ERROR, WARN and INFO level. We recommend setting your log filter as this level. */ Info = 0x0001, /** - * 0x000e: Outputs CRITICAL, ERROR, and WARNING level log information. + * 0x0002: Output logs of the FATAL, ERROR and WARN level. */ Warn = 0x0002, /** - * 0x000c: Outputs CRITICAL and ERROR level log information. + * 0x0004: Output logs of the FATAL and ERROR level. */ Error = 0x0004, /** - * 0x0008: Outputs CRITICAL level log information. + * 0x0008: Output logs of the FATAL level. */ Fatal = 0x0008, } /** - * TODO(DOC) + * Capture brightness level. + * + * @since v3.1.1. */ export enum CaptureBrightnessLevelType { + /** -1: The SDK does not detect the brightness level of the video image. Wait a few seconds to get the brightness level from `CaptureBrightnessLevelType` in the next callback. */ Invalid = -1, + /** 0: The brightness level of the video image is normal. */ Normal = 0, + /** 1: The brightness level of the video image is too bright. */ Bright = 1, + /** 2: The brightness level of the video image is too dark. */ Dark = 2, } @@ -2772,75 +2797,113 @@ export enum SuperResolutionStateReason { } /** - * TODO(DOC) + * The reason for the upload failure. + * + * @since v3.3.1. */ export enum UploadErrorReason { + /** + * 0: The log file is successfully uploaded. + */ Success = 0, + /** + * 1: Network error. Check the network connection and call [`uploadLogFile`]{@link uploadLogFile} again to upload the log file. + */ NetError = 1, + /** + * 0: Agora 服务器错误，请稍后尝试。 + */ ServerError = 2, } /** - * TODO(DOC) - * Cloud proxy transport type + * The cloud proxy type. + * + * @since v3.3.1. */ export enum CloudProxyType { /** - * no proxy + * Do not use the cloud proxy. */ None = 0, /** - * udp proxy + * The cloud proxy for the UDP protocol. */ UDP = 1, /** - * tcp proxy + * The cloud proxy for the TCP (encryption) protocol. */ TCP = 2, } /** - * TODO(DOC) - * Experience quality types. + * Quality of experience (QoE) of the local user when receiving a remote audio stream. + * + * @since v3.3.1. */ export enum ExperienceQualityType { /** - * 0: Good experience quality. + * 0: QoE of the local user is good. */ Good = 0, /** - * 1: Bad experience quality. + * 1: QoE of the local user is poor. */ Bad = 1, } /** - * TODO(DOC) - * The reason for poor experience + * The reason for poor QoE of the local user when receiving a remote audio stream. + * + * @since v3.3.1. */ export enum ExperiencePoorReason { + /** + * 0: No reason, indicating good QoE of the local user. + */ None = 0, - + /** + * 1: The remote user's network quality is poor. + */ RemoteNetworkQualityPoor = 1, - + /** + * 2: The local user's network quality is poor. + */ LocalNetworkQualityPoor = 2, - + /** + * 4: The local user's Wi-Fi or mobile network signal is weak. + */ WirelessSignalPoor = 4, - + /** + * 8: The local user enables both Wi-Fi and bluetooth, and their signals interfere with each other. As a result, audio transmission quality is undermined. + */ WifiBluetoothCoexist = 8, } /** - * TODO(DOC) + * The options for SDK preset voice conversion effects. + * + * @since v3.3.1. */ export enum VoiceConversionPreset { + /** + * 0: Turn off voice conversion effects and use the original voice. + */ Off = 0, - + /** + * 50397440: A gender-neutral voice. To avoid audio distortion, ensure that you use this enumerator to process a female-sounding voice. + */ Neutral = 50397440, - + /** + * 50397696: A sweet voice. To avoid audio distortion, ensure that you use this enumerator to process a female-sounding voice. + */ Sweet = 50397696, - + /** + * 50397952: A steady voice. To avoid audio distortion, ensure that you use this enumerator to process a male-sounding voice. + */ Solid = 50397952, - + /** + * 50397952: A deep voice. To avoid audio distortion, ensure that you use this enumerator to process a male-sounding voice. + */ Bass = 50397952, } diff --git a/src/common/RtcChannel.native.ts b/src/common/RtcChannel.native.ts index 175a7572..7c869e04 100644 --- a/src/common/RtcChannel.native.ts +++ b/src/common/RtcChannel.native.ts @@ -432,11 +432,21 @@ export default class RtcChannel implements RtcChannelInterface { /** * Sets whether to receive all remote audio streams by default. * - * @deprecated TODO(DOC) + * @deprecated This method is deprecated from v3.3.1. + * + * Stops or resumes subscribing to the audio streams of all remote users by default. + * + * Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users. + * + * @note + * If you need to resume subscribing to the audio streams of remote users in the channel after calling `setDefaultMuteAllRemoteAudioStreams(true)`, do the following: + * - If you need to resume subscribing to the audio stream of a specified user, call [`muteRemoteAudioStream(false)`]{@link muteRemoteAudioStream}, and specify the user ID. + * - If you need to resume subscribing to the audio streams of multiple remote users, call [`muteRemoteAudioStream(false)`]{@link muteRemoteAudioStream} multiple times. + * + * @param muted Sets whether to stop subscribing to the audio streams of all remote users by default. + * - `true`: Stop subscribing to the audio streams of all remote users by default. + * - `false`: (Default) Resume subscribing to the audio streams of all remote users by default. * - * @param muted Determines whether to receive/stop receiving all remote audio streams by default: - * - `true`: Stop receiving all remote audio streams by default. - * - `false`: (Default) Receive all remote audio streams by default. */ setDefaultMuteAllRemoteAudioStreams(muted: boolean): Promise { return this._callMethod('setDefaultMuteAllRemoteAudioStreams', { muted }); @@ -465,23 +475,79 @@ export default class RtcChannel implements RtcChannelInterface { return this._callMethod('muteRemoteVideoStream', { uid, muted }); } + /** * Sets whether to receive all remote video streams by default. * - * @deprecated TODO(DOC) + * @deprecated This method is deprecated from v3.3.1. + * + * Stops or resumes subscribing to the video streams of all remote users by default. + * + * Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the video streams of all subsequent users. * - * @param muted Determines whether to receive/stop receiving all remote video streams by default: - * - `true`: Stop receiving all remote video streams by default. - * - `false`: (Default) Receive all remote video streams by default. + * @note + * If you need to resume subscribing to the video streams of remote users in the channel after calling `setDefaultMuteAllRemoteVideoStreams(true)`, do the following: + * - If you need to resume subscribing to the video stream of a specified user, call `muteRemoteVideoStream(false)`, and specify the user ID. + * - If you need to resume subscribing to the video streams of multiple remote users, call `muteRemoteVideoStream(false)` multiple times. + * + * @param muted Sets whether to stop subscribing to the video streams of all remote users by default. + * - `true`: Stop subscribing to the video streams of all remote users by default. + * - `false`: (Default) Resume subscribing to the video streams of all remote users by default. + * @return + * - 0: Success. + * - < 0: Failure. */ setDefaultMuteAllRemoteVideoStreams(muted: boolean): Promise { return this._callMethod('setDefaultMuteAllRemoteVideoStreams', { muted }); } /** - * TODO(DOC) - * @param uid - * @param enable + * @ignore + * Enables/Disables the super-resolution algorithm for a remote user's video stream. + * + * @since v3.3.1. (later) + * + * The algorithm effectively improves the resolution of the specified remote user's video stream. When the original resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher resolution (2a × 2b pixels) by enabling the algorithm. + * + * After calling this method, the SDK triggers the [`UserSuperResolutionEnabled`]{@link RtcChannelEvents.UserSuperResolutionEnabled} callback to report whether you have successfully enabled the super-resolution algorithm. + * + * @warning + * The super-resolution algorithm requires extra system resources. To balance the visual experience and system usage, the SDK poses the following restrictions: + * - The algorithm can only be used for a single user at a time. + * - On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels. + * - On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. + * + * If you exceed these limitations, the SDK triggers the `Warning` callback with the corresponding warning codes: + * - `SuperResolutionStreamOverLimitation(1610)`: The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. + * - `SuperResolutionUserCountOverLimitation(1611)`: Another user is already using the super-resolution algorithm. + * - `SuperResolutionDeviceNotSupported(1612)`: The device does not support the super-resolution algorithm. + * + * @note + * Requirements for the user's device: + * - Android: The following devices are known to support the method: + * - VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA + * - OPPO: PCCM00 + * - OnePlus: A6000 + * - Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro + * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750 + * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00 + * - iOS: This method is supported on devices running iOS 12.0 or later. The following device models are known to support the method: + * - iPhone XR + * - iPhone XS + * - iPhone XS Max + * - iPhone 11 + * - iPhone 11 Pro + * - iPhone 11 Pro Max + * - iPad Pro 11-inch (3rd Generation) + * - iPad Pro 12.9-inch (3rd Generation) + * - iPad Air 3 (3rd Generation) + * @param uid The ID of the remote user. + * @param enable Whether to enable the super-resolution algorithm: + * - `true`: Enable the super-resolution algorithm. + * - `false`: Disable the super-resolution algorithm. + * @return + * - 0: Success. + * - < 0: Failure. */ enableRemoteSuperResolution(uid: number, enable: boolean): Promise { return this._callMethod('enableRemoteSuperResolution', { uid, enable }); @@ -742,12 +808,10 @@ export default class RtcChannel implements RtcChannelInterface { * * In scenarios requiring high security, Agora recommends calling `enableEncryption` 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. Once all users leave the channel, the encryption key of this channel is automatically cleared. + * All users in the same channel must use the same encryption mode and encryption key. After a 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. * * **Note** - * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. - * - Agora supports four encryption modes. If you choose an encryption mode (excepting `SM4128ECB` mode), you need to add an external encryption library when integrating the SDK. For details, see the advanced guide *Channel Encryption*. - * + * If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. * * @param enabled Whether to enable the built-in encryption. * - `true`: Enable the built-in encryption. @@ -820,6 +884,10 @@ export default class RtcChannel implements RtcChannelInterface { * - [`UserJoined`]{@link RtcChannelEvents.UserJoined}(uid: 666), if the method call succeeds and the online * media stream is injected into the channel. * + * **Warning** + * + * Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it. + * * **Note** * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. * - This method can only be called by a host in a `LiveBroadcasting` channel. @@ -852,6 +920,10 @@ export default class RtcChannel implements RtcChannelInterface { * If you successfully remove the URL address from the live interactive streaming, the SDK triggers the * [`UserJoined`]{@link RtcChannelEvents.UserJoined} callback, with the stream uid of 666. * + * **Warning** + * + * Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it. + * * @param url The URL address to be removed. */ removeInjectStreamUrl(url: string): Promise { @@ -861,7 +933,9 @@ export default class RtcChannel implements RtcChannelInterface { /** * Creates a data stream. * - * @deprecated TODO(DOC) + * @deprecated + * + * This method is deprecated from v3.3.1. Use the [`createDataStreamWithConfig`]{@link createDataStreamWithConfig} method instead. * * Each user can create up to five data streams during the life cycle of the [`RtcChannel`]{@link RtcChannel} instance. * @@ -885,9 +959,22 @@ export default class RtcChannel implements RtcChannelInterface { return this._callMethod('createDataStream', { reliable, ordered }); } + /** - * TODO(DOC) - * @param config + * Creates a data stream. + * + * @since v3.3.1. + * + * Each user can create up to five data streams in a single channel. + * + * This method does not support data reliability. If the receiver receives a data packet five seconds or more after it was sent, the SDK directly discards the data. + * + * @param config The configurations for the data stream. + * + * + * @return + * - Returns the stream ID if you successfully create the data stream. + * - < 0: Fails to create the data stream. */ createDataStreamWithConfig(config: DataStreamConfig): Promise { return this._callMethod('createDataStream', { config }); diff --git a/src/common/RtcEngine.native.ts b/src/common/RtcEngine.native.ts index ff79548f..1b4e1906 100644 --- a/src/common/RtcEngine.native.ts +++ b/src/common/RtcEngine.native.ts @@ -102,15 +102,32 @@ export default class RtcEngine implements RtcEngineInterface { } } + /** - * TODO(DOC) + * Gets the SDK version. + * + * @since v3.3.1. + * + * You can call this method either before or after joining a channel. + * @return The version of the current SDK in the string format. For example, 2.3.0. */ static async getSdkVersion(): Promise { return RtcEngine._callMethod('getSdkVersion'); } + /** - * TODO(DOC) + * Gets the warning or error description. + * + * @since v3.3.1. + * + * @param error Detailed warning or error description in [`Warning`]{@link RtcEngineEvents.Warning} or [`Error`]{@link RtcEngineEvents.Error}. + * @return + *
    + *
  • 0: Success.
    • + *
  • < 0: Failure.
    • + *
+ * */ static async getErrorDescription(error: number): Promise { return RtcEngine._callMethod('getErrorDescription', { error }); @@ -119,13 +136,10 @@ export default class RtcEngine implements RtcEngineInterface { /** * Creates an [`RtcEngine`]{@link RtcEngine} instance. * - * @deprecated - * * Unless otherwise specified, all the methods provided by the [`RtcEngine`]{@link RtcEngine} class are executed asynchronously. Agora recommends calling these methods in the same thread. * * **Note** * - You must create an [`RtcEngine`]{@link RtcEngine} instance before calling any other method. - * - You can create an [`RtcEngine`]{@link RtcEngine} instance either by calling this method or by calling [`createWithAreaCode`]{@link createWithAreaCode}. The difference between [`createWithAreaCode`]{@link createWithAreaCode} and this method is that [`createWithAreaCode`]{@link createWithAreaCode} enables you to specify the connection area. * - The Agora React Native SDK supports creating only one [`RtcEngine`]{@link RtcEngine} instance for an app. * @param appId The App ID issued to you by Agora. See [How to get the App ID](https://docs.agora.io/en/Agora%20Platform/token#get-an-app-id). * Only users in apps with the same App ID can join the same channel and communicate with each other. @@ -145,12 +159,13 @@ export default class RtcEngine implements RtcEngineInterface { * * @deprecated * + * Deprecated as of v3.3.1. Use [`createWithConfig`]{@link createWithConfig} instead. + * * Unless otherwise specified, all the methods provided by the [`RtcEngine`]{@link RtcEngine} class are executed asynchronously. Agora recommends calling these methods in the same thread. * * **Note** * * - You must create an [`RtcEngine`]{@link RtcEngine} instance before calling any other method. - * - You can create an [`RtcEngine`]{@link RtcEngine} instance either by calling this method or by calling [`create`]{@link create}. The difference between [`create`]{@link create} and this method is that this method enables you to specify the connection area. * - The Agora React Native SDK supports creating only one [`RtcEngine`]{@link RtcEngine} instance for an app. * @param appId The App ID issued to you by Agora. See [How to get the App ID](https://docs.agora.io/en/Agora%20Platform/token#get-an-app-id). * Only users in apps with the same App ID can join the same channel and communicate with each other. Use an App ID to create only one [`RtcEngine`]{@link RtcEngine} instance. @@ -173,8 +188,21 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * TODO(DOC) - * @param config + * Creates an [`RtcEngine`]{@link RtcEngine} instance. + * + * @since v3.3.1. + * + * Unless otherwise specified, all the methods provided by the [`RtcEngine`]{@link RtcEngine} class are executed asynchronously. Agora recommends calling these methods in the same thread. + * + * @note + * - You must create an [`RtcEngine`]{@link RtcEngine} instance before calling any other method. + * - The Agora RTC Native SDK supports creating only one [`RtcEngine`]{@link RtcEngine} instance for an app for now. + * + * @param config Configurations for the [`RtcEngine`]{@link RtcEngine} instance. For details, see [`RtcEngineConfig`]{@link RtcEngineConfig}. + * @return + * - The [`RtcEngine`]{@link RtcEngine} instance, if the method call succeeds. + * - The error code, if the method call fails. + * - 101(InvalidAppId): The app ID is invalid. Check if it is in the correct format. */ static async createWithConfig(config: RtcEngineConfig) { if (engine) return engine; @@ -345,23 +373,22 @@ export default class RtcEngine implements RtcEngineInterface { * * Ensure that the App ID used for creating the token is the same App ID used in the `create` method for creating an [`RtcEngine`]{@link RtcEngine} object. Otherwise, CDN live streaming may fail. * - * @param token The token for authentication: - * - In situations not requiring high security: You can use the temporary token generated at Console. For details, see [Get a temporary token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#get-a-temporary-token). - * - In situations requiring high security: Set it as the token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#generatetoken). + * @param token The token generated at your server. See [Generate a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#generatetoken). * @param channelName The unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. * - All numeric characters: 0 to 9. * - The space character. * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". - * @param optionalInfo Additional information about the channel. This parameter can be set as null or contain channel related information. Other users in the channel do not receive this message. + * @param optionalInfo (Optional) Reserved for future use. * @param optionalUid (Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to (2^32-1). `optionalUid` must be unique. If `optionalUid` is not assigned (or set to `0`), the SDK assigns and returns `uid` in the [`JoinChannelSuccess`]{@link RtcEngineEvents.JoinChannelSuccess} callback. - * @param options TODO(DOC) * Your app must record and maintain the returned uid since the SDK does not do so. * * The uid is represented as a 32-bit unsigned integer in the SDK. Since unsigned integers are not supported by Java, the uid is handled as a 32-bit signed integer and larger numbers are interpreted as negative numbers in Java. * If necessary, the uid can be converted to a 64-bit integer through “uid&0xffffffffL”. * + * @param options? @since v3.3.1. (Optional) The channel media options: [`ChannelMediaOptions`]{@link ChannelMediaOptions}. + * * @returns * - 0(NoError): Success. * - Error codes: Failure. @@ -369,7 +396,7 @@ export default class RtcEngine implements RtcEngineInterface { * - 3(NotReady): The SDK fails to be initialized. You can try re-initializing the SDK. * - 5(Refused): The request is rejected. Possible reasons: * - You have created an `RtcChannel` object with the same channel name. - * - You have joined and published a stream in a channel created by the `RtcChannel` object. + * - You have joined and published a stream in a channel created by the `RtcChannel` object. When you join a channel created by the RtcEngine object, the SDK publishes the local audio and video streams to that channel by default. Because the SDK does not support publishing a local stream to more than one channel simultaneously, an error occurs in this occasion. * - 7(NotInitialized): The SDK is not initialized. */ joinChannel( @@ -402,16 +429,14 @@ export default class RtcEngine implements RtcEngineInterface { * * This method applies to the [`Audience`]{@link ClientRole.Audience} role in a [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} channel only. * - * @param token The token for authentication: - * - In situations not requiring high security: You can use the temporary token generated at Console. For details, see [Get a temporary token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#get-a-temporary-token). - * - In situations requiring high security: Set it as the token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#generatetoken). + * @param token The token generated at your server. See [Generate a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#generatetoken). * @param channelName Unique channel name for the AgoraRTC session in the string format. The string length must be less than 64 bytes. Supported character scopes are: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. * - All numeric characters: 0 to 9. * - The space character. * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". - * @param options TODO(DOC) + * @param options? @since v3.3.1. (Optional) The channel media options: [`ChannelMediaOptions`]{@link ChannelMediaOptions}. * * @returns * - 0(NoError): Success. @@ -562,9 +587,11 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets the log files that the SDK outputs. * - * TODO(DOC) * @deprecated * + * This method is deprecated from v3.3.1. Use the `LogConfig` parameter in [`createWithConfig`]{@link createWithConfig} to set the log file path instead. + * + * * By default, the SDK outputs five log files, `agorasdk.log`, `agorasdk_1.log`, `agorasdk_2.log`, `agorasdk_3.log`, `agorasdk_4.log`, each with a default size of 1024 KB. * These log files are encoded in UTF-8. The SDK writes the latest logs in `agorasdk.log`. When `agorasdk.log` is full, the SDK deletes the log file with the * earliest modification time among the other four, renames `agorasdk.log` to the name of the deleted log file, and creates a new `agorasdk.log` to record latest logs. @@ -574,7 +601,10 @@ export default class RtcEngine implements RtcEngineInterface { * * Ensure that you call this method immediately after calling the `create` method, otherwise the output log may not be complete. * - * @param filePath File path of the log file. The string of the log file is in UTF-8. The default file path is `/storage/emulated/0/Android/data/="">/files/agorasdk.log`. + * @param filePath The absolute path of log files. The default file path is as follows: + * - Android: `/storage/emulated/0/Android/data//files/agorasdk.log` + * - iOS: `App Sandbox/Library/caches/agorasdk.log` + * Ensure that the directory for the log files exists and is writable. You can use this parameter to rename the log files. */ setLogFile(filePath: string): Promise { return RtcEngine._callMethod('setLogFile', { filePath }); @@ -583,9 +613,10 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets the output log level of the SDK. * - * TODO(DOC) * @deprecated * + * This method is deprecated from v3.3.1. Use the `LogConfig` parameter in [`createWithConfig`]{@link createWithConfig} to set the log file path instead. + * * You can use one or a combination of the filters. The log level follows the sequence of `Off`, `Critical`, `Error`, `Warning`, `Info`, and `Debug`. * Choose a level to see the logs preceding that level. For example, if you set the log level to `Warning`, you see the logs within levels `Critical`, `Error`, and `Warning`. * @@ -598,9 +629,10 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets the size (KB) of a log file that the SDK outputs. * - * TODO(DOC) * @deprecated * + * This method is deprecated from v3.3.1. Use the `LogConfig` parameter in [`createWithConfig`]{@link createWithConfig} to set the log file path instead. + * * By default, the SDK outputs five log files, `agorasdk.log`, `agorasdk_1.log`, `agorasdk_2.log`, `agorasdk_3.log`, `agorasdk_4.log`, each with a default size of 1024 KB. These log files are encoded in UTF-8. The SDK writes the latest logs in `agorasdk.log`. * When `agorasdk.log` is full, the SDK deletes the log file with the earliest modification time among the other four, renames `agorasdk.log` to the name of the deleted log file, and create a new `agorasdk.log` to record latest logs. * @param fileSizeInKBytes The size (KB) of a log file. The default value is 1024 KB. If you set `fileSizeInKByte` to 1024 KB, the SDK outputs @@ -660,9 +692,7 @@ export default class RtcEngine implements RtcEngineInterface { * 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 uid of the user is set to the same parameter type. - * @param token The token generated at your server: - * - In situations not requiring high security: You can use the temporary token generated at Console. For details, see [Get a temporary token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#get-a-temporary-token). - * - In situations requiring high security: Set it as the token generated at your server. For details, see [Generate a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#generatetoken). + * @param token The token generated at your server. See [Generate a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#generatetoken). * @param channelName The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. @@ -676,7 +706,7 @@ export default class RtcEngine implements RtcEngineInterface { * - All numeric characters: 0 to 9. * - The space character. * - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",". - * @param options TODO(DOC) + * @param options? @since v3.3.1. (Optional) The channel media options: [`ChannelMediaOptions`]{@link ChannelMediaOptions}. * * @returns * - 0(NoError): Success. @@ -894,47 +924,50 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * Stops/Resumes receiving all remote audio streams. + * Stops or resumes subscribing to the audio streams of all remote users. + * + * As of v3.3.1, after successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users. + * + * **Note** + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. * - * @param muted Sets whether to receive/stop receiving all remote audio streams: - * - `true`: Stop receiving all remote audio streams. - * - `false`: (Default) Receive all remote audio streams. + * @param muted Sets whether to stop subscribing to the audio streams of all remote users. + * - `true`: Stop subscribing to the audio streams of all remote users. + * - `false`: (Default) Resume subscribing to the audio streams of all remote users. */ muteAllRemoteAudioStreams(muted: boolean): Promise { return RtcEngine._callMethod('muteAllRemoteAudioStreams', { muted }); } /** - * Stops/Resumes sending the local audio stream. + * Stops or resumes publishing the local audio stream. * A successful [`muteLocalAudioStream`]{@link muteLocalAudioStream} method call triggers the [`UserMuteAudio`]{@link RtcEngineEvents.UserMuteAudio} callback on the remote client. * * **Note** * - * - When `muted` is set as ``true``, this method does not disable the microphone and thus does not affect any ongoing recording. - * - If you call [`setChannelProfile`]{@link setChannelProfile} after this method, the SDK resets whether to mute the local audio according to the channel profile and user role. - * Therefore, we recommend calling this method after the [`setChannelProfile`]{@link setChannelProfile} method. + * - When `muted` is set as `true`, this method does not affect any ongoing audio recording, because it does not disable the microphone. + * - If you call `setChannelProfile` after this method, the SDK resets whether or not to stop publishing the local audio according to the channel profile and user role. Therefore, Agora recommends calling this method after the `setChannelProfile` method. * - * @param muted Sets whether to send/stop sending the local audio stream: - * - `true`: Stop sending the local audio stream. - * - `false`: (Default) Send the local audio stream. + * @param muted Sets whether to stop publishing the local audio stream. + * - `true`: Stop publishing the local audio stream. + * - `false`: (Default) Resumes publishing the local audio stream. */ muteLocalAudioStream(muted: boolean): Promise { return RtcEngine._callMethod('muteLocalAudioStream', { muted }); } /** - * Stops/Resumes receiving a specified audio stream. + * Stops or resumes subscribing to the audio stream of a specified user. * * **Note** + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. * - * - If you called [`muteAllRemoteAudioStreams`]{@link muteAllRemoteAudioStreams} and set `muted` as `true` to stop receiving all remote video streams, - * ensure that the [`muteAllRemoteAudioStreams`]{@link muteAllRemoteAudioStreams} method is called and set `muted` as `false` before calling this method. - * The [`muteAllRemoteAudioStreams`]{@link muteAllRemoteAudioStreams} method sets all remote audio streams, while the [`muteRemoteAudioStream`]{@link muteRemoteAudioStream} method sets a specified remote user's audio stream. - * - * @param uid ID of the specified remote user. - * @param muted Sets whether to receive/stop receiving the specified remote user's audio stream: - * - `true`: Stop receiving the specified remote user’s audio stream. - * - `false`: (Default) Receive the specified remote user’s audio stream. + * @param uid The user ID of the specified remote user. + * @param muted Sets whether to stop subscribing to the audio stream of a specified user. + * - `true`: Stop subscribing to the audio stream of a specified user. + * - `false`: (Default) Resume subscribing to the audio stream of a specified user. */ muteRemoteAudioStream(uid: number, muted: boolean): Promise { return RtcEngine._callMethod('muteRemoteAudioStream', { uid, muted }); @@ -963,21 +996,21 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets whether to receive all remote audio streams by default. * - * TODO(DOC) - * @deprecated + * @deprecated This method is deprecated from v3.3.1. * - * You can call this method either before or after joining a channel. - * If you call `setDefaultMuteAllRemoteAudioStreams(true)` after joining a channel, you will not receive the audio streams of any subsequent user. + * Stops or resumes subscribing to the audio streams of all remote users by default. * - * **Note** + * Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users. + * + * @note + * If you need to resume subscribing to the audio streams of remote users in the channel after calling `setDefaultMuteAllRemoteAudioStreams(true)`, do the following: + * - If you need to resume subscribing to the audio stream of a specified user, call [`muteRemoteAudioStream(false)`]{@link muteRemoteAudioStream}, and specify the user ID. + * - If you need to resume subscribing to the audio streams of multiple remote users, call [`muteRemoteAudioStream(false)`]{@link muteRemoteAudioStream} multiple times. * - * If you want to resume receiving audio streams, call [`muteRemoteAudioStream(false)`]{@link muteRemoteAudioStream}, and specify the ID of the remote user that you want to subscribe to. - * To resume audio streams of multiple users, call [`muteRemoteAudioStream`]{@link muteRemoteAudioStream} as many times. - * Calling `setDefaultMuteAllRemoteAudioStreams(false)` resumes receiving audio streams of the subsequent users only. + * @param muted Sets whether to stop subscribing to the audio streams of all remote users by default. + * - `true`: Stop subscribing to the audio streams of all remote users by default. + * - `false`: (Default) Resume subscribing to the audio streams of all remote users by default. * - * @param muted Sets whether to receive/stop receiving the remote audio streams by default: - * - `true`: Stop receiving any audio stream by default. - * - `false`: (Default) Receive all remote audio streams by default. */ setDefaultMuteAllRemoteAudioStreams(muted: boolean): Promise { return RtcEngine._callMethod('setDefaultMuteAllRemoteAudioStreams', { @@ -1073,49 +1106,52 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * Stops/Resumes receiving all remote video streams. + * Stops or resumes subscribing to the video streams of all remote users. + * + * As of v3.3.1, after successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users. + * + * **Note** + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. * - * @param muted Sets whether to receive/stop receiving all remote video streams: - * - `true`: Stop receiving all remote video streams. - * - `false`: (Default) Receive all remote video streams. + * @param muted Sets 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) Resume subscribing to the video streams of all remote users. */ muteAllRemoteVideoStreams(muted: boolean): Promise { return RtcEngine._callMethod('muteAllRemoteVideoStreams', { muted }); } /** - * Stops/Resumes sending the local video stream. + * Stops or resumes publishing the local video stream. * * A successful [`muteLocalVideoStream`]{@link muteLocalVideoStream} method call triggers the [`UserMuteVideo`]{@link RtcEngineEvents.UserMuteVideo} callback on the remote client. * * **Note** * - * - When you set `muted` as `true`, this method does not disable the camera and thus does not affect the retrieval of the local video streams. - * This method responds faster than calling [`enableLocalVideo`]{@link enableLocalVideo} and set `muted` as `false`, which controls sending the local video stream. - * - * - If you call [`setChannelProfile`]{@link setChannelProfile} after this method, the SDK resets whether to mute the local video according to the channel profile and user role. - * Therefore, we recommend calling this method after the [`setChannelProfile`]{@link setChannelProfile} method. + * - This method executes faster than the `enableLocalVideo` method, which controls the sending of the local video stream. + * - When `mute` is set as `true`, this method does not affect any ongoing video recording, because it does not disable the camera. + * - You can call this method either before or after joining a channel. If you call `setChannelProfile` after this method, the SDK resets whether or not to stop publishing the local video according to the channel profile and user role. Therefore, Agora recommends calling this method after the `setChannelProfile` method. * - * @param muted Sets whether to send/stop sending the local video stream: - * - `true`: Stop sending the local video stream. - * - `false`: (Default) Send the local video stream. + * @param muted Sets whether to stop publishing the local video stream. + * - `true`: Stop publishing the local video stream. + * - `false`: (Default) Resumes publishing the local video stream. */ muteLocalVideoStream(muted: boolean): Promise { return RtcEngine._callMethod('muteLocalVideoStream', { muted }); } /** - * Stops/Resumes receiving a specified remote user's video stream. + * Stops or resumes subscribing to the video stream of a specified user. * * **Note** + * - Call this method after joining a channel. + * - See recommended settings in *Set the Subscribing State*. * - * If you call [`muteAllRemoteVideoStreams`]{@link muteAllRemoteVideoStreams} and set `muted` as `true` to stop receiving all remote video streams, - * ensure that the [`muteAllRemoteVideoStreams`]{@link muteAllRemoteVideoStreams} method is called and set `muted` as `false` before calling this method. The [`muteAllRemoteVideoStreams`]{@link muteAllRemoteVideoStreams} method sets all remote streams, while this method sets a specified remote user's stream. - * - * @param uid User ID of the specified remote user. - * @param muted Sets whether to receive/stop receiving a specified remote user's video stream: - * - `true`: Stop receiving a specified remote user’s video stream. - * - `false`: (Default) Receive a specified remote user’s video stream. + * @param uid The user ID of the specified remote user. + * @param muted Sets whether to stop subscribing to the video stream of a specified user. + * - `true`: Stop subscribing to the video stream of a specified user. + * - `false`: (Default) Resume subscribing to the video stream of a specified user. */ muteRemoteVideoStream(uid: number, muted: boolean): Promise { return RtcEngine._callMethod('muteRemoteVideoStream', { uid, muted }); @@ -1151,9 +1187,53 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * TODO(DOC) - * @param uid - * @param enable + * @ignore + * + * Enables/Disables the super-resolution algorithm for a remote user's video stream. + * + * @since v3.3.1 (later) + * + * The algorithm effectively improves the resolution of the specified remote user's video stream. When the original resolution of the remote video stream is a × b pixels, you can receive and render the stream at a higher resolution (2a × 2b pixels) by enabling the algorithm. + * + * After calling this method, the SDK triggers the [`UserSuperResolutionEnabled`]{@link RtcEngineEvents.UserSuperResolutionEnabled} callback to report whether you have successfully enabled the super-resolution algorithm. + * + * @warning + * The super-resolution algorithm requires extra system resources. To balance the visual experience and system usage, the SDK poses the following restrictions: + * - The algorithm can only be used for a single user at a time. + * - On the Android platform, the original resolution of the remote video must not exceed 640 × 360 pixels. + * - On the iOS platform, the original resolution of the remote video must not exceed 640 × 480 pixels. + * + * If you exceed these limitations, the SDK triggers the `Warning` callback with the corresponding warning codes: + * - `SuperResolutionStreamOverLimitation(1610)`: The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied. + * - `SuperResolutionUserCountOverLimitation(1611)`: Another user is already using the super-resolution algorithm. + * - `SuperResolutionDeviceNotSupported(1612)`: The device does not support the super-resolution algorithm. + * + * @note + * Requirements for the user's device: + * - Android: The following devices are known to support the method: + * - VIVO: V1821A, NEX S, 1914A, 1916A, and 1824BA + * - OPPO: PCCM00 + * - OnePlus: A6000 + * - Xiaomi: Mi 8, Mi 9, MIX3, and Redmi K20 Pro + * - SAMSUNG: SM-G9600, SM-G9650, SM-N9600, SM-G9708, SM-G960U, and SM-G9750 + * - HUAWEI: SEA-AL00, ELE-AL00, VOG-AL00, YAL-AL10, HMA-AL00, and EVR-AN00 + * - iOS: This method is supported on devices running iOS 12.0 or later. The following device models are known to support the method: + * - iPhone XR + * - iPhone XS + * - iPhone XS Max + * - iPhone 11 + * - iPhone 11 Pro + * - iPhone 11 Pro Max + * - iPad Pro 11-inch (3rd Generation) + * - iPad Pro 12.9-inch (3rd Generation) + * - iPad Air 3 (3rd Generation) + * @param uid The ID of the remote user. + * @param enable Whether to enable the super-resolution algorithm: + * - `true`: Enable the super-resolution algorithm. + * - `false`: Disable the super-resolution algorithm. + * @return + * - 0: Success. + * - < 0: Failure. */ enableRemoteSuperResolution(uid: number, enable: boolean): Promise { return RtcEngine._callMethod('enableRemoteSuperResolution', { @@ -1165,20 +1245,23 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets whether to receive all remote video streams by default. * - * TODO(DOC) * @deprecated * - * You can call this method either before or after joining a channel. - * If you call `setDefaultMuteAllRemoteVideoStreams(true)` after joining a channel, you will not receive the video stream of any subsequent user. + * This method is deprecated from v3.3.1. * - * **Note** + * Stops or resumes subscribing to the video streams of all remote users by default. + * + * Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the video streams of all subsequent users. + * + * @note + * If you need to resume subscribing to the video streams of remote users in the channel after calling `setDefaultMuteAllRemoteVideoStreams(true)`, do the following: + * - If you need to resume subscribing to the video stream of a specified user, call [`muteRemoteVideoStream(false)`]{@link muteRemoteVideoStream}, and specify the user ID. + * - If you need to resume subscribing to the video streams of multiple remote users, call [`muteRemoteVideoStream(false)`]{@link muteRemoteVideoStream} multiple times. * - * If you want to resume receiving video streams, call [`muteRemoteVideoStream(false)`]{@link muteRemoteVideoStream}, and specify the ID of the remote user that you want to subscribe to. - * To resume receiving video streams of multiple users, call [`muteRemoteVideoStream`]{@link muteRemoteVideoStream} as many times. Calling `setDefaultMuteAllRemoteVideoStreams(false)` resumes receiving video streams of the subsequent users only. + * @param muted Sets whether to stop subscribing to the video streams of all remote users by default. + * - `true`: Stop subscribing to the video streams of all remote users by default. + * - `false`: (Default) Resume subscribing to the video streams of all remote users by default. * - * @param muted Sets whether to receive/stop receiving all remote video streams by default: - * - `true`: Stop receiving any remote video stream by default. - * - `false`: (Default) Receive all remote video streams by default. */ setDefaultMuteAllRemoteVideoStreams(muted: boolean): Promise { return RtcEngine._callMethod('setDefaultMuteAllRemoteVideoStreams', { @@ -1219,6 +1302,10 @@ export default class RtcEngine implements RtcEngineInterface { /** * Stops the local video preview and the video. + * + * **Note** + * + * Call this method before joining a channel. */ stopPreview(): Promise { return RtcEngine._callMethod('stopPreview'); @@ -1229,7 +1316,7 @@ export default class RtcEngine implements RtcEngineInterface { * * **Note** * - * Call this method when you are in a channel. + * Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. * * @param volume Audio mixing volume for local playback. The value ranges between 0 and 100 (default). */ @@ -1242,7 +1329,7 @@ export default class RtcEngine implements RtcEngineInterface { * * **Note** * - * Call this method when you are in a channel. + * Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. * * @param volume Audio mixing volume for publishing. The value ranges between 0 and 100 (default). */ @@ -1255,7 +1342,7 @@ export default class RtcEngine implements RtcEngineInterface { * * **Note** * - * - Call this method when you are in a channel. + * - Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. * * - Calling this method does not affect the volume of the audio effect file playback invoked by the [`playEffect`]{@link playEffect} method. * @@ -1270,7 +1357,7 @@ export default class RtcEngine implements RtcEngineInterface { * * **Note** * - * Call this method when you are in a channel. + * Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. * * @returns * - Returns the current playback position of the audio mixing, if the method call is successful. @@ -1285,7 +1372,7 @@ export default class RtcEngine implements RtcEngineInterface { * * **Note** * - * Call this method when you are in a channel. + * Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. * * @returns * - Returns the audio mixing duration, if the method call is successful. @@ -1300,6 +1387,11 @@ export default class RtcEngine implements RtcEngineInterface { * * This method helps troubleshoot audio volume related issues. * + * **Note** + * + * Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. + * + * * @returns * - Returns the audio mixing volume for local playback, if the method call is successful. The value range is [0,100]. * - Error codes: Failure. @@ -1313,6 +1405,10 @@ export default class RtcEngine implements RtcEngineInterface { * * This method helps troubleshoot audio volume related issues. * + * **Note** + * + * Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. + * * @returns * - Returns the audio mixing volume for publishing, if the method call is successful. The value range is [0,100]. * - Error codes: Failure. @@ -1347,7 +1443,7 @@ export default class RtcEngine implements RtcEngineInterface { * * **Note** * - * Call this method after calling [`startAudioMixing`]{@link startAudioMixing}. + * Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. * * @param pitch Sets the pitch of the local music file by chromatic scale. * The default value is 0, which means keep the original pitch. @@ -1360,6 +1456,11 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets the playback position (ms) of the music file to a different starting position (the default plays from the beginning). + * + * **Note** + * + * Call this method after calling `startAudioMixing` and receiving the `AudioMixingStateChanged(Playing)` callback. + * * @param pos The playback starting position (ms) of the audio mixing file. */ setAudioMixingPosition(pos: number): Promise { @@ -1591,7 +1692,10 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets the local voice changer option. * - * @deprecated Deprecated as of v3.2.0. Use `setAudioEffectPreset` or `setVoiceBeautifierPreset` instead. + * @deprecated Deprecated as of v3.2.0. Use the following methods instead: + * - setAudioEffectPreset: Audio effects. + * - setVoiceBeautifierPreset: Voice beautifier effects. + * - setVoiceConversionPreset: Voice conversion effects. * * **Note** * @@ -1692,7 +1796,7 @@ export default class RtcEngine implements RtcEngineInterface { * * - For this method to work, enable stereo panning for remote users by calling the [`enableSoundPositionIndication`]{@link enableSoundPositionIndication} method before joining a channel. * - * - This method requires hardware support. For the best sound positioning, we recommend using a stereo headset. + * - This method requires hardware support. For the best sound positioning, we recommend using a wired headset. * * @param uid The ID of the remote user. * @param pan The sound position of the remote user. @@ -1826,7 +1930,7 @@ export default class RtcEngine implements RtcEngineInterface { * **Note** * * If the method call fails, the SDK triggers the [`ChannelMediaRelayStateChanged`]{@link RtcEngineEvents.ChannelMediaRelayStateChanged} callback with the [`ServerNoResponse(2)`]{@link ChannelMediaRelayError.ServerNoResponse} - * or [`ServerConnectionLost(8)`]{@link ChannelMediaRelayError.ServerConnectionLost} state code. + * or [`ServerConnectionLost(8)`]{@link ChannelMediaRelayError.ServerConnectionLost} error code. * You can leave the channel by calling [`leaveChannel`]{@link leaveChannel}, and the media stream relay automatically stops. */ stopChannelMediaRelay(): Promise { @@ -1859,6 +1963,10 @@ export default class RtcEngine implements RtcEngineInterface { /** * Checks whether the speakerphone is enabled. * + * **Note** + * + * 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. @@ -1916,7 +2024,7 @@ export default class RtcEngine implements RtcEngineInterface { * - If you set `scenario` as `Education`, the audience cannot change the audio playback route. * * @param enabled Sets whether to route the audio to the speakerphone or earpiece: - * - `true`: Route the audio to the speakerphone. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the speakerphone. + * - `true`: Route the audio to the speakerphone. If the playback device connects to the headset or Bluetooth, the audio cannot be routed to the speakerphone. * - `false`: Route the audio to the earpiece. If the headset is plugged in, the audio is routed to the headset. */ setEnableSpeakerphone(enabled: boolean): Promise { @@ -1959,6 +2067,9 @@ export default class RtcEngine implements RtcEngineInterface { * Sets the default video-stream type of the remotely subscribed video stream * when the remote user sends dual streams. * + * **Note** + * You can call this method either before or after joining a channel. If you call both `setRemoteVideoStreamType` and `setRemoteDefaultVideoStreamType`, the SDK applies the settings in the `setRemoteVideoStreamType` method. + * * @param streamType Sets the default video-stream type. */ setRemoteDefaultVideoStreamType(streamType: VideoStreamType): Promise { @@ -1982,6 +2093,10 @@ export default class RtcEngine implements RtcEngineInterface { * * The SDK reports the result of calling this method in the [`ApiCallExecuted`]{@link RtcEngineEvents.ApiCallExecuted} callback. * + * **Note** + * + * You can call this method either before or after joining a channel. If you call both `setRemoteVideoStreamType` and `setRemoteDefaultVideoStreamType`, the SDK applies the settings in the `setRemoteVideoStreamType` method. + * * @param uid ID of the remote user sending the video stream. * @param streamType Sets the video-stream type. */ @@ -2084,7 +2199,7 @@ export default class RtcEngine implements RtcEngineInterface { * * - In the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile, a host should not call this method after joining a channel. * - If you call this method to test the last-mile quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the [`setVideoEncoderConfiguration`]{@link setVideoEncoderConfiguration} method. - * After you join the channel, whether you have called [`disableLastmileTest`]{@link disableLastmileTest} or not, the SDK automatically stops consuming the bandwidth. + * - After you join the channel, whether you have called [`disableLastmileTest`]{@link disableLastmileTest} or not, the SDK automatically stops consuming the bandwidth. */ enableLastmileTest(): Promise { return RtcEngine._callMethod('enableLastmileTest'); @@ -2244,12 +2359,10 @@ export default class RtcEngine implements RtcEngineInterface { * * In scenarios requiring high security, Agora recommends calling `enableEncryption` 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. Once all users leave the channel, the encryption key of this channel is automatically cleared. + * All users in the same channel must use the same encryption mode and encryption key. After a 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. * * **Note** - * - If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. - * - Agora supports four encryption modes. If you choose an encryption mode (excepting `SM4128ECB` mode), you need to add an external encryption library when integrating the SDK. For details, see the advanced guide *Channel Encryption*. - * + * If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function. * * @param enabled Whether to enable the built-in encryption. * - `true`: Enable the built-in encryption. @@ -2368,6 +2481,10 @@ export default class RtcEngine implements RtcEngineInterface { * - The remote client: * - [`UserJoined`]{@link RtcEngineEvents.UserJoined}(uid: 666), if the method call is successful and the online media stream is injected into the channel. * + * **Warning** + * + * Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it. + * * **Note** * * - This method applies to the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile only. @@ -2401,6 +2518,10 @@ export default class RtcEngine implements RtcEngineInterface { * * If this method call is successful, the SDK triggers the [`UserOffline`]{@link RtcEngineEvents.UserOffline} callback and returns a stream uid of 666. * + * **Warning** + * + * Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it. + * * @param url HTTP/HTTPS URL address of the added stream to be removed. */ removeInjectStreamUrl(url: string): Promise { @@ -2520,6 +2641,8 @@ export default class RtcEngine implements RtcEngineInterface { * * - If you want better quality for the local video preview, we recommend setting `config` as [`Preview(2)`]{@link CameraCaptureOutputPreference.Preview}. * + * - To customize the width and height of the video image captured by the local camera, set the camera capture configuration as [`Manual(3)`]{@link CameraCaptureOutputPreference.Manual}. + * * **Note** * * Call this method before enabling the local camera. That said, you can call this method before calling [`joinChannel`]{@link joinChannel}, [`enableVideo`]{@link enableVideo}, or [`enableLocalVideo`]{@link enableLocalVideo}, depending on which method you use to turn on your local camera. @@ -2596,9 +2719,12 @@ export default class RtcEngine implements RtcEngineInterface { /** * Creates a data stream. * - * TODO(DOC) * @deprecated * + * This method is deprecated from v3.3.1. Use the [`createDataStreamWithConfig`]{@link createDataStreamWithConfig} method instead. + * + * Ensure that you call this method after joining a channel. + * * Each user can create up to five data streams during the lifecycle of the [`RtcEngine`]{@link RtcEngine}. * * **Note** @@ -2622,8 +2748,20 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * TODO(DOC) - * @param config + * Creates a data stream. + * + * @since v3.3.1. + * + * Each user can create up to five data streams in a single channel. + * + * This method does not support data reliability. If the receiver receives a data packet five seconds or more after it was sent, the SDK directly discards the data. + * + * @param config The configurations for the data stream. + * + * + * @return + * - Returns the stream ID if you successfully create the data stream. + * - < 0: Fails to create the data stream. */ createDataStreamWithConfig(config: DataStreamConfig): Promise { return RtcEngine._callMethod('createDataStream', { config }); @@ -2708,23 +2846,77 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * TODO(DOC) - * @param enabled + * Enables or disables deep-learning noise reduction. + * + * @since v3.3.1. + * + * The SDK enables traditional noise reduction mode by default to reduce most of the stationary background noise. If you need to reduce most of the non-stationary background noise, Agora recommends enabling deep-learning noise reduction as follows: + * - 1. Integrate the following file under the `libs` folder to your project: + * - Android: `libagora_ai_denoise_extension.so` + * - iOS: `AgoraAIDenoiseExtension.xcframework` + * - 2. Call `enableDeepLearningDenoise(true)`. + * + * Deep-learning noise reduction requires high-performance devices. + * + * After successfully enabling deep-learning noise reduction, if the SDK detects that the device performance is not sufficient, it automatically disables deep-learning noise reduction and enables traditional noise reduction. + * + * If you call `enableDeepLearningDenoise(false)` or the SDK automatically disables deep-learning noise reduction in the channel, when you need to re-enable deep-learning noise reduction, you need to call `leaveChannel` first, and then call `enableDeepLearningDenoise(true)`. + * + * @note + * - This method dynamically loads `libagora_ai_denoise_extension.so` on Android or `AgoraAIDenoiseExtension.xcframework` on iOS, so Agora recommends calling this method before joining a channel. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * @param enabled Sets whether to enable deep-learning noise reduction. + * - `true`: (Default) Enables deep-learning noise reduction. + * - `false`: Disables deep-learning noise reduction. + * @return + * - 0: Success. + * - Error codes: Failure. + * - 157(ModuleNotFound): The library for enabling deep-learning noise reduction is not integrated. */ enableDeepLearningDenoise(enabled: boolean): Promise { return RtcEngine._callMethod('enableDeepLearningDenoise', { enabled }); } /** - * TODO(DOC) - * @param proxyType + * Sets the Agora cloud proxy service. + * + * @since v3.3.1. + * + * When the user's firewall restricts the IP address and port, refer to *Use Cloud Proxy* to add the specific IP addresses and ports to the firewall whitelist; then, call this method to enable the cloud proxy and set the `proxyType` parameter as `UDP(1)`, which is the cloud proxy for the UDP protocol. + * + * After a successfully cloud proxy connection, the SDK triggers the [`ConnectionStateChanged(Connecting, SettingProxyServer)`]{@link RtcEngineEvents.ConnectionStateChanged} callback. + * + * To disable the cloud proxy that has been set, call `setCloudProxy(None)`. To change the cloud proxy type that has been set, call `setCloudProxy(None)` first, and then call `setCloudProxy`, and pass the value that you expect in `proxyType`. + * + * @note + * - Agora recommends that you call this method before joining the channel or after leaving the channel. + * - When you use the cloud proxy for the UDP protocol, the services for pushing streams to CDN and co-hosting across channels are not available. + * + * @param proxyType The cloud proxy type. This parameter is required, and the SDK reports an error if you do not pass in a value. See [`CloudProxyType`]{@link CloudProxyType}. + * + * @return + * - 0: Success. + * - Error codes: Failure. + * - `2(InvalidArgument)`: The parameter is invalid. + * - `7(NotInitialized)`: The SDK is not initialized. */ setCloudProxy(proxyType: CloudProxyType): Promise { return RtcEngine._callMethod('setCloudProxy', { proxyType }); } /** - * TODO(DOC) + * @ignore + * Uploads all local SDK log files. + * @since v3.3.1. (later) + * + * Uploads all SDK log files from the client to the Agora server. After a successful method call, the SDK triggers the `[UploadLogResult]`{@link RtcEngineEvents.UploadLogResult} callback to report whether the log files are successfully uploaded to the Agora server. + * + * Do not call this method more than once per minute, otherwise the SDK returns `null`. + * + * For easier debugging, Agora recommends that you bind this method to the UI element of your App, so as to instruct the user to upload a log file when a quality issue occurs. + * @return + * - The request ID. This request ID is the same as `requestId` in the `onUploadLogResult` callback, and you can use the request ID to match a specific upload with a callback. + * - `null`: The method call fails. It may be because the call frequency exceeds the limit. */ uploadLogFile(): Promise { return RtcEngine._callMethod('uploadLogFile'); @@ -2735,20 +2927,17 @@ export default class RtcEngine implements RtcEngineInterface { * * @since v3.2.0. * - * Call this method to set the following parameters for the local user who send an audio stream: + * 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 parameters, all users in the channel can hear the relevant effect. * - * You can call this method directly or after `setAudioEffectPreset`. If you call this method after `setAudioEffectPreset`, ensure that you set the preset parameter of `setAudioEffectPreset` to `RoomAcoustics3DVoice` or `PitchCorrection` and - * then call this method to set the same enumerator; otherwise, this method overrides `setAudioEffectPreset`. - * * **Note** * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the scenario parameter * to `GameStreaming(3)` before calling this method. - * - Do not set the profile parameter of `setAudioProfile` to `SpeechStandard(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call fails. + * - Do not set the `profile` parameter of `setAudioProfile` to `SpeechStandard(1)`; otherwise, this method call does not take effect. * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. * - After calling this method, Agora recommends not calling the following methods, because they can override `setAudioEffectParameters`: * - `setAudioEffectPreset` @@ -2758,6 +2947,7 @@ export default class RtcEngine implements RtcEngineInterface { * - `setLocalVoicePitch` * - `setLocalVoiceEqualization` * - `setLocalVoiceReverb` + * - `setVoiceConversionPreset` * * @param preset The options for SDK preset audio effects: * - 3D voice effect: `RoomAcoustics3DVoice`. @@ -2807,10 +2997,42 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * TODO(DOC) - * @param preset - * @param param1 - * @param param2 + * Sets parameters for SDK preset voice beautifier effects. + * + * @since 3.3.1. + * + * 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 you call this method successfully, all users in the channel can hear the relevant effect. + * + * To achieve better audio effect quality, before you call this method, Agora recommends calling [`setAudioProfile`]{@link setAudioProfile}, and setting the `scenario` parameter to `GameStreaming(3)` and the profile parameter to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)`. + * + * @note + * - You can call this method either before or after joining a channel. + * - Do not set the `profile` parameter of `setAudioProfile` to `SpeechStandard(1)`; otherwise, this method call does not take effect. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * - After you call this method, Agora recommends not calling the following methods, because they can override `setVoiceBeautifierParameters`: + * - `setAudioEffectPreset` + * - `setAudioEffectParameters` + * - `setVoiceBeautifierPreset` + * - `setLocalVoiceReverbPreset` + * - `setLocalVoiceChanger` + * - `setLocalVoicePitch` + * - `setLocalVoiceEqualization` + * - `setLocalVoiceReverb` + * - `setVoiceConversionPreset` + * @param preset The options for SDK preset voice beautifier effects: + * - `SingingBeautifier`: Singing beautifier effect. + * @param param1 The gender characteristics options for the singing voice: + * - `1`: A male-sounding voice. + * - `2`: A female-sounding voice. + * @param param2 The reverberation effects options: + * - `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. + * @return + * - 0: Success. + * - < 0: Failure. */ setVoiceBeautifierParameters( preset: VoiceBeautifierPreset, @@ -2838,7 +3060,7 @@ export default class RtcEngine implements RtcEngineInterface { * * **Note** * - You can call this method either before or after joining a channel. - * - Do not set the profile parameter of `setAudioProfile` to `SpeechStandard(1)`; otherwise, this method call fails. + * - Do not set the `profile` parameter of `setAudioProfile` to `SpeechStandard(1)`; otherwise, this method call does not take effect. * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. * - If you call this method and set the preset parameter to enumerators except `RoomAcoustics3DVoice` or `PitchCorrection`, do not call `setAudioEffectParameters`; otherwise, `setAudioEffectParameters` overrides this method. * - After calling this method, Agora recommends not calling the following methods, because they can override `setAudioEffectPreset`: @@ -2848,6 +3070,7 @@ export default class RtcEngine implements RtcEngineInterface { * - `setLocalVoicePitch` * - `setLocalVoiceEqualization` * - `setLocalVoiceReverb` + * - `setVoiceConversionPreset` * * @param preset The options for SDK preset audio effects. See [`AudioEffectPreset`]{@link AudioEffectPreset}. * @@ -2873,7 +3096,7 @@ export default class RtcEngine implements RtcEngineInterface { * * **Note** * - You can call this method either before or after joining a channel. - * - Do not set the profile parameter of `setAudioProfile` to `SpeechStandard(1)`; otherwise, this method call fails. + * - Do not set the `profile` parameter of `setAudioProfile` to `SpeechStandard(1)`; otherwise, this method call does not take effect. * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. * - After calling this method, Agora recommends not calling the following methods, because they can override `setVoiceBeautifierPreset`: * - `setAudioEffectPreset` @@ -2882,6 +3105,7 @@ export default class RtcEngine implements RtcEngineInterface { * - `setLocalVoicePitch` * - `setLocalVoiceEqualization` * - `setLocalVoiceReverb` + * - `setVoiceConversionPreset` * * @param preset The options for SDK preset voice beautifier effects. See [`VoiceBeautifierPreset`]{@link VoiceBeautifierPreset}. * @@ -2893,9 +3117,37 @@ export default class RtcEngine implements RtcEngineInterface { return RtcEngine._callMethod('setVoiceBeautifierPreset', { preset }); } + /** - * TODO(DOC) - * @param preset + * Sets an SDK preset voice conversion effect. + * + * @since v3.3.1 + * + * Call this method to set an SDK preset voice conversion effect for the local user who sends an audio stream. After setting a voice conversion effect, all users in the channel can hear the effect. + * + * You can set different voice conversion effects for different scenarios. See *Set the Voice Effect*. + * + * To achieve better audio effect quality, Agora recommends calling [`setAudioProfile`]{@link setAudioProfile} and setting the `scenario` parameter to `GameStreaming(3)` and the `profile` parameter to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before calling this method. + * + * @note + * - You can call this method either before or after joining a channel. + * - Do not set the `profile` parameter of `setAudioProfile` to `AUDIO_PROFILE_SPEECH_STANDARD(1)`; otherwise, this method call does not take effect. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * - After calling this method, Agora recommends not calling the following methods, because they can override `[setVoiceConversionPreset]`{@link setVoiceConversionPreset}: + * - `setAudioEffectPreset` + * - `setAudioEffectParameters` + * - `setVoiceBeautifierPreset` + * - `setVoiceBeautifierParameters` + * - `setLocalVoiceReverbPreset` + * - `setLocalVoiceChanger` + * - `setLocalVoicePitch` + * - `setLocalVoiceEqualization` + * - `setLocalVoiceReverb` + * + * @param preset The options for SDK preset voice conversion effects. See [`VoiceConversionPreset`]{@link VoiceConversionPreset}. + * @return + * - 0: Success. + * - < 0: Failure. */ setVoiceConversionPreset(preset: VoiceConversionPreset): Promise { return RtcEngine._callMethod('setVoiceConversionPreset', { preset }); diff --git a/src/common/RtcEvents.ts b/src/common/RtcEvents.ts index 834c4f8e..4b158513 100644 --- a/src/common/RtcEvents.ts +++ b/src/common/RtcEvents.ts @@ -489,12 +489,24 @@ export type RtmpStreamingEventCallback = (url: string, eventCode: RtmpStreamingEvent) => void; export type UserSuperResolutionEnabledCallback = /** - * TODO(DOC) + * @ignore + * + * @param uid The ID of the remote user. + * @param enabled Whether the super-resolution algorithm is successfully enabled: + * - `true`: The super-resolution algorithm is successfully enabled. + * - `false`: The super-resolution algorithm is not successfully enabled. + * @param reason The reason why the super-resolution algorithm is not successfully enabled. See [`SuperResolutionStateReason`]{@link enum.SuperResolutionStateReason}. */ (uid: number, enabled: boolean, reason: SuperResolutionStateReason) => void; export type UploadLogResultCallback = /** - * TODO(DOC) + * @ignore + * + * @param requestId The request ID. This request ID is the same as requestId returned by `uploadLogFile`, and you can use `requestId` to match a specific upload with a callback. + * @param success Whether the log files are successfully uploaded: + * - `true`: Successfully upload the log files. + * - `false`: Fails to upload the log files. For details, see the reason parameter. + * @param reason The reason for the upload failure. See [`UploadErrorReason`]{@link enum.UploadErrorReason}. */ (requestId: string, success: boolean, reason: UploadErrorReason) => void; @@ -763,8 +775,17 @@ export interface RtcEngineEvents { * Occurs when the local video state changes. * * The SDK returns the current video state in this callback. - * 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. - * When the state is [`Failed`]{@link LocalVideoStreamState.Failed}, see the error parameter for details. + * + * The SDK triggers the `LocalVideoStateChanged(Failed, CaptureFailure)` callback in the following situations: + * - On Android: + * - (Android 9 or later) The application exits to the background, and the system recycles the camera. + * - (Android 6 or later) The camera is occupied by a third-party application. When the third-party application releases the camera, the SDK triggers the `LocalVideoStateChanged(Capturing, OK)` callback. + * - The camera starts normally, but the captured video is not output for four seconds. + * - On iOS: + * - The application exits to the background, and the system recycles the camera. + * - The camera starts normally, but the captured video is not output for four seconds. + * + * When the camera outputs the captured video frames, if all the video frames are the same for 15 consecutive frames, the SDK triggers the `LocalVideoStateChanged(Capturing, CaptureFailure)` callback. 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. * * @event LocalVideoStateChanged */ @@ -790,7 +811,7 @@ export interface RtcEngineEvents { * * **Note** * - * When the state is [`Failed`]{@link AudioLocalState.Failed}, see the error parameter for details. + * When the state is [`Failed`]{@link AudioLocalState.Failed}, see the `error` parameter for details. * * @event LocalAudioStateChanged */ @@ -1001,6 +1022,11 @@ export interface RtcEngineEvents { /** * Reports the status of injecting the online media stream. * + * **Warning** + * + * Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it. + * + * * @event StreamInjectedStatus */ StreamInjectedStatus: StreamInjectedStatusCallback; @@ -1399,12 +1425,24 @@ export interface RtcEngineEvents { RtmpStreamingEvent: RtmpStreamingEventCallback; /** - * TODO(DOC) + * @ignore + * + * Reports whether the super-resolution algorithm is enabled. + * + * @since v3.3.1 (later) + * + * After calling `enableRemoteSuperResolution`, the SDK triggers this callback to report whether the super-resolution algorithm is successfully enabled. If not successfully enabled, you can use reason for troubleshooting. */ UserSuperResolutionEnabled: UserSuperResolutionEnabledCallback; /** - * TODO(DOC) + * @ignore + * + * Reports the result of uploading the SDK log files. + * + * @since v3.3.1 (later) + * + * After the method call of `uploadLogFile`, the SDK triggers this callback to report the result of uploading the log files. If the upload fails, refer to the `reason` parameter to troubleshoot. */ UploadLogResult: UploadLogResultCallback; } @@ -1662,6 +1700,11 @@ export interface RtcChannelEvents { /** * Reports the status of injecting the online media stream. * + * **Warning** + * + * Agora will soon stop the service for injecting online media streams on the client. If you have not implemented this service, Agora recommends that you do not use it. + * + * * @event StreamInjectedStatus */ StreamInjectedStatus: StreamInjectedStatusCallback; @@ -1761,7 +1804,12 @@ export interface RtcChannelEvents { RtmpStreamingEvent: RtmpStreamingEventCallback; /** - * TODO(DOC) + * @ignore + * Reports whether the super-resolution algorithm is enabled. + * + * @since v3.3.1 (later) + * + * After calling `enableRemoteSuperResolution`, the SDK triggers this callback to report whether the super-resolution algorithm is successfully enabled. If not successfully enabled, you can use `reason` for troubleshooting. */ UserSuperResolutionEnabled: UserSuperResolutionEnabledCallback; }