Merge pull request #271 from TingChen2020/rc/3.1.2_en

Update doc for v3.1.2

src/src/Classes.ts

@@ -594,7 +594,7 @@ export class ChannelMediaRelayConfiguration {
     /**
      * The information of the destination channel: [`ChannelMediaInfo`]{@link ChannelMediaInfo}. It contains the following members:
      * - `channelName`: The name of the destination channel.
-     * - `uid`: ID of the host in the destination channel. The value ranges from 0 to (232-1). To avoid UID conflicts, this uid must be different from any other UIDs in the destination channel. The default value is 0, which means the SDK generates a random UID.
+     * - `uid`: ID of the host in the destination channel. The value ranges from 0 to (2<sup>32</sup>-1). To avoid UID conflicts, this uid must be different from any other UIDs in the destination channel. The default value is 0, which means the SDK generates a random UID.
      * - `token`: The token for joining the source channel. It is generated with the `channelName` and `uid` you set in `destInfo`.
      *  - If you have not enabled the App Certificate, set this parameter as the default value null, which means the SDK applies the App ID.
      *  - If you have enabled the App Certificate, you must use the token generated with the `channelName` and `uid`, and the `uid` must be set as 0.
@@ -713,25 +713,34 @@ export class LiveInjectStreamConfig {
     videoFramerate?: VideoFrameRate
     /**
      * Video bitrate of the added stream to the live interactive streaming. The default value is 400 Kbps.
+     *
+     * **Note**
+     *
+     * The setting of the video bitrate is closely linked to the resolution. If you set the video bitrate beyond a reasonable range, the SDK sets it within a reasonable range instead.
      */
     videoBitrate?: number
     /**
      * Audio sample rate of the added stream to the live interactive streaming. The default value is 44100 Hz.
+     *
+     * **Note**
+     *
+     * We recommend you use the default value and not reset it.
      */
     audioSampleRate?: AudioSampleRateType
     /**
      * Audio bitrate of the added stream to the live interactive streaming. The default value is 48 Kbps.
+     *
+     * **Note**
+     *
+     * We recommend you use the default value and not reset it.
      */
     audioBitrate?: number
     /**
-     * Audio channels to be added to the live interactive streaming.
+     * Audio channels to add into the live streaming. The value ranges between 1 and 2. The default value is 1.
      *
-     * Agora recommends choosing 1 (mono), or 2 (stereo) audio channels. Special players are required if you choose 3, 4, or 5.
-     * - 1: (Default) Mono
-     * - 2: Stereo
-     * - 3: Three audio channels
-     * - 4: Four audio channels
-     * - 5: Five audio channels
+     * **Note**
+     *
+     * We recommend you use the default value and not reset it.
      */
     audioChannels?: AudioChannel
 
@@ -774,12 +783,16 @@ export class ChannelMediaOptions {
      * Determines whether to subscribe to audio streams when the user joins the channel.
      * - `true`: (Default) Subscribe.
      * - `false`: Do not subscribe.
+     *
+     * This member serves a similar function to the [`muteAllRemoteAudioStreams`]{@link RtcEngine.muteAllRemoteAudioStreams} method. After joining the channel, you can call the `muteAllRemoteAudioStreams` method to set whether to subscribe to audio streams in the channel.
      */
     autoSubscribeAudio: boolean
     /**
      * Determines whether to subscribe to video streams when the user joins the channel.
      * - `true`: (Default) Subscribe.
      * - `false`: Do not subscribe.
+     *
+     * This member serves a similar function to the [`muteAllRemoteVideoStreams`]{@link RtcEngine.muteAllRemoteVideoStreams} method. After joining the channel, you can call the `muteAllRemoteVideoStreams` method to set whether to subscribe to audio streams in the channel.
      */
     autoSubscribeVideo: boolean
 
@@ -790,10 +803,22 @@ export class ChannelMediaOptions {
 }
 
 /**
- * TODO(doc)
+ * Definition of `EncryptionConfig`.
+ *
+ * @since v3.1.2.
  */
 export class EncryptionConfig {
+    /**
+     * Encryption mode. The default encryption mode is `AES128XTS`. See [`EncryptionMode`]{@link EncryptionMode}.
+     */
     encryptionMode: EncryptionMode
+    /**
+     * Encryption key in string type.
+     *
+     * **Note**
+     *
+     * If you do not set an encryption key or set it as null, you cannot use the built-in encryption, and the SDK returns [`InvalidArgument(2)`]{@link ErrorCode.InvalidArgument}.
+     */
     encryptionKey: string
 
     constructor(encryptionMode: EncryptionMode, encryptionKey: string) {
@@ -860,6 +885,10 @@ export interface RtcStats {
     rxVideoKBitRate: number
     /**
      * The number of users in the channel.
+     * - `COMMUNICATION` profile: The number of users in the channel.
+     * - `LiveBroadcasting` profile:
+     *  - If the local user is an audience member: The number of users in the channel = The number of hosts in the channel + 1.
+     *  - If the local user is a host: The number of users in the channel = The number of hosts in the channel.
      */
     users: number
     /**
@@ -884,18 +913,33 @@ export interface RtcStats {
     cpuAppUsage: number
     /**
      * The round-trip time delay from the client to the local router.
+     *
+     * **Note**
+     * (iOS only) Since v3.1.2, this parameter is disabled by default. See [FAQ](https://docs.agora.io/en/faq/local_network_privacy) for details. If you need to enable this parameter, contact support@agora.io.
      */
     gatewayRtt: number
     /**
      * The memory usage ratio of the app (%).
+     *
+     * **Note**
+     *
+     * This value is for reference only. Due to system limitations, you may not get the value of this member.
      */
     memoryAppUsageRatio: number
     /**
      * The memory usage ratio of the system (%).
+     *
+     * **Note**
+     *
+     * This value is for reference only. Due to system limitations, you may not get the value of this member.
      */
     memoryTotalUsageRatio: number
     /**
      * The memory usage of the app (KB).
+     *
+     * **Note**
+     *
+     * This value is for reference only. Due to system limitations, you may not get the value of this member.
      */
     memoryAppUsageInKbytes: number
 }
@@ -914,6 +958,12 @@ export interface AudioVolumeInfo {
     volume: number
     /**
      * Voice activity status of the local user.
+     * - 0: The local user is not speaking.
+     * - 1: The local user is speaking.
+     *
+     * **Note**
+     * - The `vad` parameter cannot report the voice activity status of the remote users. In the remote users' callback, `vad` = 0.
+     * - Ensure that you set `report_vad(true)` in the [`enableAudioVolumeIndication`]{@link RtcEngine.enableAudioVolumeIndication} method to enable the voice activity detection of the local user.
      */
     vad: number
     /**
@@ -1001,9 +1051,9 @@ export interface LocalAudioStats {
      */
     sentBitrate: number
     /**
-     * @since 3.1.0
+     * The video packet loss rate (%) from the local client to the Agora edge server before applying the anti-packet loss strategies.
      *
-     * TODO(doc)
+     * @since v3.1.2.
      */
     txPacketLossRate: number
 }
@@ -1061,15 +1111,15 @@ export interface LocalVideoStats {
      */
     codecType: VideoCodecType
     /**
-     * @since 3.1.0
+     * The video packet loss rate (%) from the local client to the Agora edge server before applying the anti-packet loss strategies.
      *
-     * TODO(doc)
+     * @since v3.1.2.
      */
     txPacketLossRate: number,
     /**
-     * @since 3.1.0
+     * The capture frame rate (fps) of the local video.
      *
-     * TODO(doc)
+     * @since v3.1.2.
      */
     captureFrameRate: number,
 }
@@ -1123,9 +1173,10 @@ export interface RemoteAudioStats {
      */
     totalActiveTime: number
     /**
-     * @since 3.1.0
+     * The total active time (ms) of the remote audio stream after the remote user publish the audio stream.
+     *
+     * @since v3.1.2.
      *
-     * TODO(doc)
      */
     publishDuration: number
 }
@@ -1177,20 +1228,24 @@ export interface RemoteVideoStats {
     rxStreamType: VideoStreamType
     /**
      * The total freeze time (ms) of the remote video stream after the remote user joins the channel.
+     *
+     * In a video session where the frame rate is set to no less than 5 fps, video freeze occurs when the time interval between two adjacent
+     * renderable video frames is more than 500 ms.
      */
     totalFrozenTime: number
     /**
-     * The total video freeze time as a percentage (%) of the total time when the video is available.
+     * The total video freeze time (`totalFrozenTime`) as a percentage (%) of the total active time of the remote video stream (`totalActiveTime`).
      */
     frozenRate: number
     /**
      * The total time (ms) when the remote user in the Communication profile or the remote broadcaster in the Live-broadcast profile neither stops sending the video stream nor disables the video module after joining the channel.
      */
     totalActiveTime: number
     /**
-     * @since 3.1.0
+     * The total publish duration (ms) of the remote video stream.
+     *
+     * @since v3.1.2.
      *
-     * TODO(doc)
      */
     publishDuration: number
 }