From 14308d4d7926c814f4554020d14e0d16bcf178c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E5=A9=B7?= Date: Thu, 24 Sep 2020 13:52:25 +0800 Subject: [PATCH 1/2] Update doc for v3.1.2 --- src/src/Classes.ts | 92 ++++++++++++++++++------ src/src/Enums.ts | 134 +++++++++++++++++++++++------------ src/src/RtcChannel.native.ts | 2 +- src/src/RtcEngine.native.ts | 46 ++++++++---- src/src/RtcEvents.ts | 92 +++++++++++++++++++----- 5 files changed, 269 insertions(+), 97 deletions(-) diff --git a/src/src/Classes.ts b/src/src/Classes.ts index 135cb74dd..e2aa94fe7 100644 --- a/src/src/Classes.ts +++ b/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 (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. * - `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 /** @@ -888,14 +917,26 @@ export interface RtcStats { 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 +955,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 +1048,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 +1108,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 +1170,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,10 +1225,13 @@ 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 /** @@ -1188,9 +1239,10 @@ export interface RemoteVideoStats { */ totalActiveTime: number /** - * @since 3.1.0 + * The total publish duration (ms) of the remote video stream. + * + * @since v3.1.2. * - * TODO(doc) */ publishDuration: number } diff --git a/src/src/Enums.ts b/src/src/Enums.ts index 152730995..e3e47f8f7 100644 --- a/src/src/Enums.ts +++ b/src/src/Enums.ts @@ -1,5 +1,5 @@ /** - * IP areas + * Regions for connection. */ export enum AreaCode { /** @@ -228,8 +228,8 @@ export enum AudioOutputRouting { export enum AudioProfile { /** * 0: Default audio profile. - * - In the Communication profile: A sample rate of 32 KHz, audio encoding, mono, and a bitrate of up to 18 Kbps. - * - In the Live-broadcast profile: A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 52 Kbps. + * - In the `Communication` profile: A sample rate of 32 KHz, audio encoding, mono, and a bitrate of up to 18 Kbps. + * - In the `LiveBroadcasting` profile: A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 64 Kbps. */ Default = 0, /** @@ -237,27 +237,27 @@ export enum AudioProfile { */ SpeechStandard = 1, /** - * 2: A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 48 Kbps. + * 2: A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 64 Kbps. */ MusicStandard = 2, /** - * 3: A sample rate of 48 KHz, music encoding, stereo, and a bitrate of up to 56 Kbps. + * 3: A sample rate of 48 KHz, music encoding, stereo, and a bitrate of up to 80 Kbps. */ MusicStandardStereo = 3, /** - * 4: A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 128 Kbps. + * 4: A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 96 Kbps. */ MusicHighQuality = 4, /** - * 5: A sample rate of 48 KHz, music encoding, stereo, and a bitrate of up to 192 Kbps. + * 5: A sample rate of 48 KHz, music encoding, stereo, and a bitrate of up to 128 Kbps. */ MusicHighQualityStereo = 5, } /** - * Use mode of the onRecordAudioFrame callback. + * Use mode of the `RecordAudioFrame` callback. * - * TODO setPlaybackAudioFrameParameters + * //TODO setPlaybackAudioFrameParameters */ export enum AudioRawFrameOperationMode { /** @@ -517,9 +517,8 @@ export enum AudioScenario { /** * Audio session restriction. - * - * TODO iOS setAudioSessionOperationRestriction */ +//TODO iOS setAudioSessionOperationRestriction export enum AudioSessionOperationRestriction { /** * 0: No restriction, the SDK has full control of the audio session operations. @@ -959,23 +958,26 @@ export enum DegradationPreference { */ export enum EncryptionMode { /** - * TODO(doc) + * @deprecated + * 0: This mode is deprecated. */ None = 0, /** - * (Default) 128-bit AES encryption, XTS mode. + * 1: (Default) 128-bit AES encryption, XTS mode. */ AES128XTS = 1, /** - * 128-bit AES encryption, ECB mode. + * 2: 128-bit AES encryption, ECB mode. */ AES128ECB = 2, /** - * 256-bit AES encryption, XTS mode. + * 3: 256-bit AES encryption, XTS mode. */ AES256XTS = 3, /** - * TODO(doc) + * 4: 128-bit SM4 encryption, ECB mode. + * + * @since v3.1.2. */ SM4128ECB = 4, } @@ -1087,7 +1089,9 @@ export enum ErrorCode { */ InvalidChannelId = 102, /** - * TODO(doc) + * 103: Fails to get server resources in the specified region. Please try to specify another region. + * + * @since v3.1.2. */ NoServerResources = 103, /** @@ -1263,11 +1267,11 @@ export enum ErrorCode { */ AdmRecordAudioFailed = 1018, /** - * 1020: Audio Device Module: Abnormal audio playback frequency. + * 1020: Audio device module: The audio playback frequency is abnormal, which may cause audio freezes. This abnormality is caused by high CPU usage. Agora recommends stopping other apps. */ AdmPlayAbnormalFrequency = 1020, /** - * 1021: Audio Device Module: Abnormal audio recording frequency. + * 1021: Audio device module: The audio recording frequency is abnormal, which may cause audio freezes. This abnormality is caused by high CPU usage. Agora recommends stopping other apps. */ AdmRecordAbnormalFrequency = 1021, /** @@ -1490,8 +1494,8 @@ export enum LogFilter { /** * Media device type. * - * TODO MacOS AgoraMediaDeviceType */ +//TODO MacOS AgoraMediaDeviceType export enum MediaDeviceType { /** * -1: Unknown device. @@ -1518,8 +1522,8 @@ export enum MediaDeviceType { /** * Media type. * - * TODO LiveEngine */ +//TODO LiveEngine export enum MediaType { /** * 0: No audio and video. @@ -1541,9 +1545,8 @@ export enum MediaType { /** * The metadata type. - * - * TODO registerMediaMetadataObserver */ +//TODO registerMediaMetadataObserver export enum MetadataType { /** * -1: The metadata type is unknown. @@ -1632,10 +1635,10 @@ export enum NetworkType { } /** - * Default camera position + * Default camera position. * - * TODO AgoraRtcDefaultCamera */ +//TODO AgoraRtcDefaultCamera export enum RtcDefaultCameraPosition { /** * 0: Front camera @@ -1650,8 +1653,8 @@ export enum RtcDefaultCameraPosition { /** * Lifecycle of the CDN live video stream. * - * TODO AgoraPublisherConfiguration */ +//TODO AgoraPublisherConfiguration export enum RtmpStreamLifeCycle { /** * 1: Bound to the channel lifecycle. If all hosts leave the channel, the CDN live streaming stops after 30 seconds. @@ -1805,10 +1808,10 @@ export enum UserPriority { } /** - * Video buffer type + * Video buffer type. * - * TODO iOS AgoraVideoSourceProtocol AgoraVideoSinkProtocol */ +//TODO iOS AgoraVideoSourceProtocol AgoraVideoSinkProtocol export enum VideoBufferType { /** * 1: Use a pixel buffer to transmit the video data. @@ -1841,8 +1844,8 @@ export enum VideoCodecProfileType { /** * The content hint for screen sharing. * - * TODO MacOS setScreenCaptureContentHint */ +//TODO MacOS setScreenCaptureContentHint export enum VideoContentHint { /** * 0: (Default) No content hint. @@ -1859,7 +1862,7 @@ export enum VideoContentHint { } /** - * Video frame rate + * Video frame rate. */ export enum VideoFrameRate { /** @@ -2125,8 +2128,8 @@ export enum VideoOutputOrientationMode { /** * Video pixel format. * - * TODO iOS AgoraVideoSinkProtocol */ +//TODO iOS AgoraVideoSinkProtocol export enum VideoPixelFormat { /** * 1: I420 @@ -2267,8 +2270,8 @@ export enum VideoRenderMode { /** * Video rotation. * - * TODO iOS AgoraVideoSourceProtocol AgoraVideoSinkProtocol */ +//TODO iOS AgoraVideoSourceProtocol AgoraVideoSinkProtocol export enum VideoRotation { /** * 0: No rotation @@ -2395,7 +2398,9 @@ export enum WarningCode { */ AdmInterruption = 1025, /** - * TODO(doc) + * 1029: During a call, `AudioSessionCategory` should be set to `AVAudioSessionCategoryPlayAndRecord`, and the SDK monitors this value. If the `AudioSessionCategory` is set to other values, this warning code is triggered and the SDK will forcefully set it back to `AVAudioSessionCategoryPlayAndRecord`. + * + * @since v3.1.2. */ AdmCategoryNotPlayAndRecord = 1029, /** @@ -2411,11 +2416,18 @@ export enum WarningCode { */ AdmRecordIsOccupied = 1033, /** - * TODO(doc) + * 1040: Audio device module: An error occurs in the audio driver. Solutions: + * - Restart your audio device. + * - Restart your device where the app runs. + * - Upgrade the sound card drive. + * + * @since v3.1.2. */ AdmNoDataReadyCallback = 1040, /** - * TODO(doc) + * 1042: Audio device module: The audio recording device is different from the audio playback device, which may cause echoes problem. Agora recommends using the same audio device to record and playback audio. + * + * @since v3.1.2. */ AdmInconsistentDevices = 1042, /** @@ -2427,7 +2439,7 @@ export enum WarningCode { */ AdmGlitchState = 1052, /** - * 1053: Audio Device Module: the underlying audio settings have changed. + * 1053: Audio processing module: A residual echo is detected, which may be caused by the belated scheduling of system threads or the signal overflow. */ ApmResidualEcho = 1053, } @@ -2485,27 +2497,61 @@ export enum VideoCodecType { } /** - * TODO(doc) + * The publishing state. + * + * @since v3.1.2. */ export enum StreamPublishState { + /** + * 0: The initial publishing state after joining the channel. + */ Idle = 0, - + /** + * 1: Fails to publish the local stream. Possible reasons: + * - The local user calls [`muteLocalAudioStream(true)`]{@link RtcEngine.muteLocalAudioStream} or [`muteLocalVideoStream(true)`]{@link RtcEngine.muteLocalVideoStream} to stop sending local streams. + * - The local user calls [`disableAudio`]{@link RtcEngine.disableAudio} or [`disableVideo`]{@link RtcEngine.disableVideo} to disable the entire audio or video module. + * - The local user calls [`enableLocalAudio(false)`]{@link RtcEngine.enableLocalAudio} or [`enableLocalVideo(false)`]{@link enableLocalVideo} to disable the local audio sampling or video capturing. + * - The role of the local user is `Audience`. + */ NoPublished = 1, - + /** + * 2: Publishing. + */ Publishing = 2, - + /** + * 3: Publishes successfully. + */ Published = 3, } /** - * TODO(doc) + * The subscribing state. + * + * @since v3.1.2. */ export enum StreamSubscribeState { + /** + * 0: The initial subscribing state after joining the channel. + */ Idle = 0, - + /** + * 1: Fails to subscribe to the remote stream. Possible reasons: + * - The remote user: + * - Calls [`muteLocalAudioStream(true)`]{@link RtcEngine.muteLocalAudioStream} or [`muteLocalVideoStream(true)`]{@link RtcEngine.muteLocalVideoStream} to stop sending local streams. + * - The local user calls [`disableAudio`]{@link RtcEngine.disableAudio} or [`disableVideo`]{@link RtcEngine.disableVideo} to disable the entire audio or video module. + * - The local user calls [`enableLocalAudio(false)`]{@link RtcEngine.enableLocalAudio} or [`enableLocalVideo(false)`]{@link enableLocalVideo} to disable the local audio sampling or video capturing. + * - The role of the local user is `Audience`. + * - The local user calls the following methods to stop receiving remote streams: + * - Calls [`muteRemoteAudioStream(true)`]{@link RtcEngine.muteRemoteAudioStream}, [`muteAllRemoteAudioStreams(true)`]{@link RtcEngine.muteAllRemoteAudioStreams}, or [`setDefaultMuteAllRemoteAudioStreams(true)`]{@link RtcEngine.setDefaultMuteAllRemoteAudioStreams} to stop receiving remote audio streams. + * - Calls [`muteRemoteVideoStream(true)`]{@link RtcEngine.muteRemoteVideoStream}, [`muteAllRemoteVideoStreams(true)`]{@link RtcEngine.muteAllRemoteVideoStreams}, or [`setDefaultMuteAllRemoteVideoStreams(true)`]{@link RtcEngine.setDefaultMuteAllRemoteVideoStreams} to stop receiving remote video streams. + */ NoSubscribed = 1, - + /** + * 2: Subscribing. + */ Subscribing = 2, - + /** + * 3: Subscribes to and receives the remote stream successfully. + */ Subscribed = 3, } diff --git a/src/src/RtcChannel.native.ts b/src/src/RtcChannel.native.ts index 313411567..193f05ee6 100644 --- a/src/src/RtcChannel.native.ts +++ b/src/src/RtcChannel.native.ts @@ -560,7 +560,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, /** * Registers the metadata observer. * - * A successful call of this method triggers the [`setMaxMetadataSize`]{@link RtcChannel.setMaxMetadataSize} callback. + * A successful call of this method triggers the [`setMaxMetadataSize`]{@link RtcChannel.setMaxMetadataSize} method. * * This method enables you to add synchronized metadata in the video stream for more diversified live streaming interactions, * such as sending shopping links, digital coupons, and online quizzes. diff --git a/src/src/RtcEngine.native.ts b/src/src/RtcEngine.native.ts index 07577124e..4d30657ff 100644 --- a/src/src/RtcEngine.native.ts +++ b/src/src/RtcEngine.native.ts @@ -414,8 +414,11 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac } /** - * Specifies an SDK output log file. + * Sets the log files that the SDK outputs. * + * 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. * * **Note** @@ -441,12 +444,12 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac } /** - * Sets the log file size (KB). + * Sets the size (KB) of a log file that the SDK outputs. * - * The Agora SDK has two log files, each with a default size of 512 KB. - * If you set `fileSizeInKBytes` as 1024 KB, the SDK outputs log files with a total maximum size of 2 MB. - * If the total size of the log files exceed the set value, the new output log files overwrite the old output log files. - * @param fileSizeInKBytes The SDK log file size (KB). + * 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 + * at most 5 MB log files; if you set it to less than 1024 KB, the maximum size of a log file is still 1024 KB. */ setLogFileSize(fileSizeInKBytes: number): Promise { return AgoraRtcEngineModule.setLogFileSize(fileSizeInKBytes) @@ -1910,21 +1913,35 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac } /** - * TODO(doc) + * Enables/Disables the built-in encryption. * - * @param enabled - * @param config + * @since v3.1.2. + * + * 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. + * + * **Note** + * - If you enable the built-in encryption, you cannot use the RTMP 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*. + * + * + * @param enabled Whether to enable the built-in encryption. + * - `true`: Enable the built-in encryption. + * - `false`: Disable the built-in encryption. + * @param config Configurations of built-in encryption schemas. See [`EncryptionConfig`]{@link EncryptionConfig}. */ enableEncryption(enabled: boolean, config: EncryptionConfig): Promise { return AgoraRtcEngineModule.enableEncryption(enabled, config); } /** - * @deprecated TODO(doc) - * * Sets the built-in encryption mode. * - * The Agora SDK supports built-in encryption, which is set to `aes-128-xts` mode by default. + * @deprecated + * Deprecated as of v3.1.2. Use [`enableEncryption`]{@link enableEncryption} instead. + * + * The Agora SDK supports built-in encryption, which is set to `AES128XTS` mode by default. * Call this method to set the encryption mode to use other encryption modes. * All users in the same channel must use the same encryption mode and password. * @@ -1953,10 +1970,11 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac } /** - * @deprecated TODO(doc) - * * Enables built-in encryption with an encryption password before joining a channel. * + * @deprecated + * Deprecated as of v3.1.2. Use [`enableEncryption`]{@link enableEncryption} instead. + * * All users in a channel must set the same encryption password. * The encryption password is automatically cleared once a user leaves the channel. * If the encryption password is not specified or set to empty, the encryption functionality is disabled. diff --git a/src/src/RtcEvents.ts b/src/src/RtcEvents.ts index ae3a4075d..98c5823ff 100644 --- a/src/src/RtcEvents.ts +++ b/src/src/RtcEvents.ts @@ -357,7 +357,7 @@ export type VideoFrameWithUidCallback = (uid: number, width: number, height: number, elapsed: number) => void export type UrlWithErrorCallback = /** - * @param url The RTMP URL address. + * @param url The RTMP streaming URL. * @param error The detailed error information. */ (url: string, error: ErrorCode) => void @@ -418,20 +418,26 @@ export type FacePositionCallback = (imageWidth: number, imageHeight: number, faces: FacePositionInfo[]) => void export type StreamPublishStateCallback = /** - * TODO(doc) + * @param channel The channel name. + * @param oldState The previous publishing state. See [`StreamPublishState`]{@link StreamPublishState}. + * @param newState The current publishing state. See [`StreamPublishState`]{@link StreamPublishState}. + * @param elapseSinceLastState The time elapsed (ms) from the previous state to the current state. */ (channel: string, oldState: StreamPublishState, newState: StreamPublishState, elapseSinceLastState: number) => void export type StreamSubscribeStateCallback = /** - * TODO(doc) + * @param channel The channel name. + * @param oldState The previous publishing state. See [`StreamPublishState`]{@link StreamPublishState}. + * @param newState The current publishing state. See [`StreamPublishState`]{@link StreamPublishState}. + * @param elapseSinceLastState The time elapsed (ms) from the previous state to the current state. */ (channel: string, oldState: StreamSubscribeState, newState: StreamSubscribeState, elapseSinceLastState: number) => void /** - * The SDK uses the [`RtcEngineEvents`]{@link RtcEngineEvents} interface class to send callbacks to the application, and the application inherits the methods of this interface class to retrieve these callbacks. + * Callbacks. * + * The SDK uses the [`RtcEngineEvents`]{@link RtcEngineEvents} interface class to send callbacks to the application, and the application inherits the methods of this interface class to retrieve these callbacks. * All methods in this interface class have their (empty) default implementations, and the application can inherit only some of the required events instead of all of them. - * * In the callbacks, the application should avoid time-consuming tasks or call blocking APIs (such as SendMessage), otherwise, the SDK may not work properly. */ export interface RtcEngineEvents { @@ -640,7 +646,7 @@ export interface RtcEngineEvents { /** * Occurs when the first local audio frame is sent. * - * @deprecated TODO(doc) + * @deprecated Deprecated as of v3.1.2. Use [`FirstLocalAudioFramePublished`]{@link RtcEngineEvents.FirstLocalAudioFramePublished} instead. * * @event FirstLocalAudioFrame */ @@ -1247,37 +1253,69 @@ export interface RtcEngineEvents { MetadataReceived: MetadataCallback /** - * TODO(doc) + * Occurs when the first audio frame is published. + * + * @since v3.1.2. + * + * The SDK triggers this callback under one of the following circumstances: + * - The local client enables the audio module and calls [`joinChannel`]{@link joinChannel} successfully. + * - The local client calls [`muteLocalAudioStream(true)`]{@link RtcEngine.muteLocalAudioStream} and [`muteLocalAudioStream(false)`]{@link RtcEngine.muteLocalAudioStream} in sequence. + * - The local client calls [`disableAudio`]{@link RtcEngine.disableAudio} and [`enableAudio`]{@link RtcEngine.enableAudio} in sequence. */ FirstLocalAudioFramePublished: ElapsedCallback /** - * TODO(doc) + * Occurs when the first video frame is published. + * + * @since v3.1.2. + * + * The SDK triggers this callback under one of the following circumstances: + * - The local client enables the video module and calls [`joinChannel`]{@link joinChannel} successfully. + * - The local client calls [`muteLocalVideoStream(true)`]{@link RtcEngine.muteLocalVideoStream} and [`muteLocalVideoStream(false)`]{@link RtcEngine.muteLocalVideoStream} in sequence. + * - The local client calls [`disableVideo`]{@link RtcEngine.disableVideo} and [`enableVideo`]{@link RtcEngine.enableVideo} in sequence. */ FirstLocalVideoFramePublished: ElapsedCallback /** - * TODO(doc) + * Occurs when the audio publishing state changes. + * + * @since v3.1.2. + * + * This callback indicates the publishing state change of the local audio stream. */ AudioPublishStateChanged: StreamPublishStateCallback /** - * TODO(doc) + * Occurs when the video publishing state changes. + * + * @since v3.1.2. + * + * This callback indicates the publishing state change of the local video stream. */ VideoPublishStateChanged: StreamPublishStateCallback /** - * TODO(doc) + * Occurs when the audio subscribing state changes. + * + * @since v3.1.2. + * + * This callback indicates the subscribing state change of a remote audio stream. */ AudioSubscribeStateChanged: StreamSubscribeStateCallback /** - * TODO(doc) + * Occurs when the video subscribing state changes. + * + * @since v3.1.2. + * + * This callback indicates the subscribing state change of a remote video stream. */ VideoSubscribeStateChanged: StreamSubscribeStateCallback /** - * TODO(doc) + * Reports events during the RTMP streaming. + * + * @since v3.1.2. */ RtmpStreamingEvent: UrlWithErrorCallback } @@ -1581,27 +1619,45 @@ export interface RtcChannelEvents { MetadataReceived: MetadataCallback /** - * TODO(doc) + * Occurs when the audio publishing state changes. + * + * @since v3.1.2. + * + * This callback indicates the publishing state change of the local audio stream. */ AudioPublishStateChanged: StreamPublishStateCallback /** - * TODO(doc) + * Occurs when the video publishing state changes. + * + * @since v3.1.2. + * + * This callback indicates the publishing state change of the local video stream. */ VideoPublishStateChanged: StreamPublishStateCallback /** - * TODO(doc) + * Occurs when the audio subscribing state changes. + * + * @since v3.1.2. + * + * This callback indicates the subscribing state change of a remote audio stream. */ AudioSubscribeStateChanged: StreamSubscribeStateCallback /** - * TODO(doc) + * Occurs when the video subscribing state changes. + * + * @since v3.1.2. + * + * This callback indicates the subscribing state change of a remote video stream. */ VideoSubscribeStateChanged: StreamSubscribeStateCallback /** - * TODO(doc) + * Reports events during the RTMP streaming. + * + * @since v3.1.2. */ RtmpStreamingEvent: UrlWithErrorCallback } From 75a77e3b9d4a271252200240326d2254bac9f285 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E5=A9=B7?= Date: Thu, 24 Sep 2020 14:45:16 +0800 Subject: [PATCH 2/2] Add a note for gatewayRtt --- src/src/Classes.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/src/Classes.ts b/src/src/Classes.ts index e2aa94fe7..59b8e56a1 100644 --- a/src/src/Classes.ts +++ b/src/src/Classes.ts @@ -913,6 +913,9 @@ 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 /**