Rc/3.2.+

src/common/Classes.ts

@@ -1364,10 +1364,12 @@ export interface FacePositionInfo {
 
 /**
  * The detailed options of a user.
+ *
+ * @since v3.2.0.
  */
 export class ClientRoleOptions {
   /**
-   * The latency level of an audience member in a interactive live streaming. See AgoraAudienceLatencyLevelType.
+   * The latency level of an audience member in a live interactive streaming. See {@link AudienceLatencyLevelType}.
    */
   audienceLatencyLevel: AudienceLatencyLevelType;
 

src/common/Enums.ts

@@ -389,7 +389,7 @@ export enum AudioReverbPreset {
    */
   FX_VOCAL_CONCERT = 0x00100002,
   /**
-   * The reverberation style typical of an uncle’s voice.
+   * The reverberation style typical of a middle-aged man’s voice.
    */
   FX_UNCLE = 0x00100003,
   /**
@@ -2481,7 +2481,7 @@ export enum AudioEffectPreset {
   RoomAcoustics3DVoice = 0x02010800,
 
   /**
-   * The voice of an uncle.
+   * The voice of a middle-aged man.
    *
    * **Note**
    *
@@ -2492,7 +2492,7 @@ export enum AudioEffectPreset {
   VoiceChangerEffectUncle = 0x02020100,
 
   /**
-   * The voice of an uncle.
+   * The voice of an old man.
    *
    * **Note**
    *
@@ -2665,11 +2665,11 @@ export enum VoiceBeautifierPreset {
 }
 
 /**
- * The latency level of an audience member in a interactive live streaming.
+ * The latency level of an audience member in interactive live streaming.
  *
  * **Note**
  *
- * Takes effect only when the user role is AgoraClientRoleBroadcaster.
+ * Takes effect only when the user role is `Broadcaster`.
  */
 export enum AudienceLatencyLevelType {
   /**

src/common/RtcChannel.native.ts

@@ -197,16 +197,20 @@ export default class RtcChannel implements RtcChannelInterface {
   }
 
   /**
-   * Sets the role of a user.
+   * Sets the role of a user in live interactive streaming.
    *
-   * This method sets the role of a user, such as a host or an audience member. In a `LiveBroadcasting` channel,
-   * only a host can call the [`publish`]{@link publish} method in the [`RtcChannel`]{@link RtcChannel} class.
-   *
-   * A successful call of this method triggers the following callbacks:
+   * You can call this method either before or after joining the channel to set the user role as audience or host. If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks:
    * - The local client: [`ClientRoleChanged`]{@link RtcChannelEvents.ClientRoleChanged}.
-   * - The remote client: [`UserJoined`]{@link RtcChannelEvents.UserJoined}
-   * or [`UserOffline(BecomeAudience)`]{@link UserOfflineReason.BecomeAudience}.
-   * @param role The role of the user.
+   * - The remote client: [`UserJoined`]{@link RtcChannelEvents.UserJoined} or [`UserOffline(BecomeAudience)`]{@link UserOfflineReason.BecomeAudience}.
+   *
+   * **Note**
+   * - This method applies to the `LiveBroadcasting` profile only (when the `profile` parameter in `setChannelProfile` is set as `LiveBroadcasting`).
+   * - As of v3.2.0, this method can set the user level in addition to the user role.
+   *    - The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
+   *    - The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. **Levels affect prices**.
+   *
+   * @param role The role of a user in interactive live streaming. See {@link ClientRole}.
+   * @param options? The detailed options of a user, including user level. See {@link ClientRoleOptions}.
    *
    * @returns
    * - 0(NoError): Success.
@@ -228,6 +232,8 @@ export default class RtcChannel implements RtcChannelInterface {
    * - If you want to join the same channel from different devices, ensure that the UIDs in all devices are different.
    * - Ensure that the app ID you use to generate the token is the same with the app ID used when creating the [`RtcEngine`]{@link RtcEngine} instance.
    *
+   * Once the user joins the channel (switches to another 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. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly.
+   *
    * @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).
@@ -268,6 +274,8 @@ export default class RtcChannel implements RtcChannelInterface {
    * - If you want to join the same channel from different devices, ensure that the user accounts in all devices are different.
    * - Ensure that the app ID you use to generate the token is the same with the app ID used when creating the [`RtcEngine`]{@link RtcEngine} instance.
    *
+   * Once the user joins the channel (switches to another 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. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly.
+   *
    * @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).

src/common/RtcEngine.native.ts

@@ -262,15 +262,20 @@ export default class RtcEngine implements RtcEngineInterface {
   }
 
   /**
-   * Sets the role of a user ([`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} only).
+   * Sets the role of a user in live interactive streaming.
    *
-   * This method sets the role of a user, such as a host or an audience (default), before joining a channel.
-   *
-   * This method can be used to switch the user role after a user joins a channel. In the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile, when a user switches user roles after joining a channel, a successful call of this method triggers the following callbacks:
+   * You can call this method either before or after joining the channel to set the user role as audience or host. If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks:
    * - The local client: [`ClientRoleChanged`]{@link RtcEngineEvents.ClientRoleChanged}.
    * - The remote client: [`UserJoined`]{@link RtcEngineEvents.UserJoined} or [`UserOffline`]{@link RtcEngineEvents.UserOffline} ([`BecomeAudience`]{@link UserOfflineReason.BecomeAudience}).
    *
-   * @param role Sets the role of a user.
+   * **Note**
+   * - This method applies to the `LiveBroadcasting` profile only (when the `profile` parameter in `setChannelProfile` is set as `LiveBroadcasting`).
+   * - As of v3.2.0, this method can set the user level in addition to the user role.
+   *    - The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
+   *    - The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. **Levels affect prices**.
+   *
+   * @param role The role of a user in interactive live streaming. See {@link ClientRole}.
+   * @param options? The detailed options of a user, including user level. See {@link ClientRoleOptions}.
    *
    * @returns
    * - 0(NoError): Success.
@@ -299,6 +304,8 @@ export default class RtcEngine implements RtcEngineInterface {
    * When the connection between the client and Agora 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 [`RejoinChannelSuccess`]{@link RtcEngineEvents.RejoinChannelSuccess} callback on the local client.
    *
+   * Once the user joins the channel (switches to another 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. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly.
+   *
    * **Note**
    *
    * A channel does not accept duplicate uids, such as two users with the same `uid`. If you set `uid` as `0`, the system automatically assigns a uid.
@@ -355,6 +362,8 @@ export default class RtcEngine implements RtcEngineInterface {
    * After the user successfully switches to another channel, the [`LeaveChannel`]{@link RtcEngineEvents.LeaveChannel} and [`JoinChannelSuccess`]{@link RtcEngineEvents.JoinChannelSuccess} callbacks are triggered to
    * indicate that the user has left the original channel and joined a new one.
    *
+   * Once the user joins the channel (switches to another 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. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly.
+   *
    * **Note**
    *
    * This method applies to the [`Audience`]{@link ClientRole.Audience} role in a [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} channel only.
@@ -595,6 +604,8 @@ export default class RtcEngine implements RtcEngineInterface {
    *
    * - The remote client: [`UserJoined`]{@link RtcEngineEvents.UserJoined} and [`UserInfoUpdated`]{@link RtcEngineEvents.UserInfoUpdated}, if the user joining the channel is in the [`Communication`]{@link ChannelProfile.Communication} profile, or is a [`Broadcaster`]{@link ClientRole.Broadcaster} in the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile.
    *
+   * Once the user joins the channel (switches to another 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. If you do not want to subscribe to a specified stream or all remote streams, call the `mute` methods accordingly.
+   *
    * **Note**
    *
    * To ensure smooth communication, use the same parameter type to identify the user.
@@ -2649,7 +2660,7 @@ export default class RtcEngine implements RtcEngineInterface {
    *   - 3: Japanese pentatonic scale.
    *
    * @param param2
-   * - You need to set `param2` to 0.
+   * - If you set `preset` to `RoomAcoustics3DVoice`, you need to set `param2` to `0`.
    * - If you set `preset` to `PitchCorrection`, `param2` sets the tonic pitch of the pitch correction effect:
    *   - 1: A
    *   - 2: A#