diff --git a/package.json b/package.json index dd1655028..fffc2e176 100644 --- a/package.json +++ b/package.json @@ -53,7 +53,8 @@ "jest": "^24.9.0", "metro-react-native-babel-preset": "^0.56.0", "react-test-renderer": "16.9.0", - "typescript": "^3.7.3" + "typedoc-plugin-no-inherit": "^1.1.10", + "typescript": "^4.0.2" }, "jest": { "preset": "react-native", diff --git a/src/RtcLocalView.tsx b/src/RtcLocalView.tsx index 0c5c3e187..f9731022e 100644 --- a/src/RtcLocalView.tsx +++ b/src/RtcLocalView.tsx @@ -4,8 +4,13 @@ import {Platform, ViewProps} from "react-native"; import {RtcSurfaceView, RtcSurfaceViewProps, RtcTextureView, RtcTextureViewProps} from "./src/RtcRenderView.native"; /** - * Use SurfaceView in Android. - * Use UIView in iOS. + * The SurfaceView class. + * + * **Note** + * + * SurfaceView only applies to Android. Use UIView on iOS. + * + * @noInheritDoc */ class SurfaceView extends Component { render() { @@ -18,8 +23,12 @@ class SurfaceView extends Component { } /** - * Use TextureView in Android. - * Not support for iOS. + * The TextureView class. + * + * **Note** + * + * TextureView only applies to Android. iOS does not support TextureView. + * @noInheritDoc */ class TextureView extends Component { render() { diff --git a/src/RtcRemoteView.tsx b/src/RtcRemoteView.tsx index 2bbaa2cc7..43b29ac12 100644 --- a/src/RtcRemoteView.tsx +++ b/src/RtcRemoteView.tsx @@ -9,10 +9,7 @@ import { RtcUidProps } from "./src/RtcRenderView.native"; -/** - * Use SurfaceView in Android. - * Use UIView in iOS. - */ + class SurfaceView extends Component { render() { return ( @@ -21,10 +18,7 @@ class SurfaceView extends Component { render() { if (Platform.OS === 'ios') diff --git a/src/src/Classes.ts b/src/src/Classes.ts index 632d467df..324ab40bb 100644 --- a/src/src/Classes.ts +++ b/src/src/Classes.ts @@ -43,7 +43,9 @@ export class VideoDimensions { * The video resolution on the vertical axis. */ height: number - + /** + * @ignore + */ constructor(width: number, height: number) { this.width = width; this.height = height; @@ -58,6 +60,32 @@ export class VideoEncoderConfiguration { /** * The video frame dimensions (px), which is used to specify the video quality and measured by the total number of pixels along a * frame's width and height. The default value is 640 × 360. + * You can customize the dimension, or select from the following list: + *
    + *
  • 120x120
    • + *
  • 160x120
    • + *
  • 180x180
    • + *
  • 240x180
    • + *
  • 320x180
    • + *
  • 240x240
    • + *
  • 320x240
    • + *
  • 424x240
    • + *
  • 360x360
    • + *
  • 480x360
    • + *
  • 640x360
    • + *
  • 480x480
    • + *
  • 640x480
    • + *
  • 840x480
    • + *
  • 960x720
    • + *
  • 1280x720
    • + *
+ * + * **Note** + *
    + *
  • The value of the dimension does not indicate the orientation mode of the output ratio. For how to set the video orientation, see [`VideoOutputOrientationMode`]{@link VideoOutputOrientationMode}.
    • + *
  • Whether 720p+ can be supported depends on the device. If the device cannot support 720p, the frame rate will be lower than the one listed in the table.
    • + *
+ * */ dimensions?: VideoDimensions /** @@ -264,7 +292,9 @@ export class VideoEncoderConfiguration { * Sets the mirror mode of the published local video stream. */ mirrorMode?: VideoMirrorMode - + /** + * @ignore + */ constructor({dimensions, frameRate, minFrameRate, bitrate, minBitrate, orientationMode, degradationPrefer, mirrorMode}: { dimensions?: VideoDimensions, frameRate?: VideoFrameRate, minFrameRate?: VideoFrameRate, bitrate?: number, minBitrate?: number, orientationMode?: VideoOutputOrientationMode, degradationPrefer?: DegradationPreference, mirrorMode?: VideoMirrorMode }) { this.dimensions = dimensions; this.frameRate = frameRate; @@ -299,7 +329,9 @@ export class BeautyOptions { * The default value is 0.1. This parameter adjusts the red saturation level. */ rednessLevel?: number - + /** + * @ignore + */ constructor({lighteningContrastLevel, lighteningLevel, smoothnessLevel, rednessLevel}: { lighteningContrastLevel?: LighteningContrastLevel, lighteningLevel?: number, smoothnessLevel?: number, rednessLevel?: number }) { this.lighteningContrastLevel = lighteningContrastLevel; this.lighteningLevel = lighteningLevel; @@ -332,7 +364,9 @@ export class AgoraImage { * Height of the image on the broadcasting video. */ height: number - + /** + * @ignore + */ constructor(url: string, x: number, y: number, width: number, height: number) { this.url = url; this.x = x; @@ -371,14 +405,28 @@ export class TranscodingUser { */ zOrder?: number /** - * The transparency of the video frame of the user in the CDN live stream that ranges between 0.0 and 1.0. 0.0 means that the video frame is completely transparent and 1.0 means opaque. The default value is 1.0. + * The transparency of the video frame of the user in the CDN live streaming that ranges between 0.0 and 1.0. 0.0 means that the video frame is completely transparent and 1.0 means opaque. The default value is 1.0. */ alpha?: number /** * The audio channel ranging between 0 and 5. The default value is 0. + * + * - 0: (default) Supports dual channels. Depends on the upstream of the broadcaster. + * - 1: The audio stream of the broadcaster uses the FL audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first. + * - 2: The audio stream of the broadcaster uses the FC audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first. + * - 3: The audio stream of the broadcaster uses the FR audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first. + * - 4: The audio stream of the broadcaster uses the BL audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first. + * - 5: The audio stream of the broadcaster uses the BR audio channel. If the broadcaster’s upstream uses multiple audio channels, these channels are mixed into mono first. + * + * **Note** + * + * Special players are needed if `audioChannel` is not set as 0. + * */ audioChannel?: AudioChannel - + /** + * @ignore + */ constructor(uid: number, x: number, y: number, {width, height, zOrder, alpha, audioChannel}: { width?: number, height?: number, zOrder?: number, alpha?: number, audioChannel?: AudioChannel }) { this.uid = uid; this.x = x; @@ -408,7 +456,9 @@ export class Color { * Blue. */ blue: number - + /** + * @ignore + */ constructor(red: number, green: number, blue: number) { this.red = red; this.green = green; @@ -470,7 +520,14 @@ export class LiveTranscoding { */ audioBitrate?: number /** - * Agora self-defined audio channel type. We recommend choosing `1` or `2`. Special players are required if you choose `3`, `4` or `5`. + * The number of audio channels for the CDN live stream. + * + * 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 */ audioChannels?: AudioChannel /** @@ -493,7 +550,9 @@ export class LiveTranscoding { * An TranscodingUser object managing the user layout configuration in the CDN live stream. Agora supports a maximum of 17 transcoding users in a CDN live stream channel. */ transcodingUsers: TranscodingUser[] - + /** + * @ignore + */ constructor(transcodingUsers: TranscodingUser[], {width, height, videoBitrate, videoFramerate, lowLatency, videoGop, watermark, backgroundImage, audioSampleRate, audioBitrate, audioChannels, audioCodecProfile, videoCodecProfile, backgroundColor, userConfigExtraInfo}: { width?: number, height?: number, videoBitrate?: number, videoFramerate?: VideoFrameRate, lowLatency?: boolean, videoGop?: number, watermark?: AgoraImage, backgroundImage?: AgoraImage, audioSampleRate?: AudioSampleRateType, audioBitrate?: number, audioChannels?: AudioChannel, audioCodecProfile?: AudioCodecProfileType, videoCodecProfile?: VideoCodecProfileType, backgroundColor?: Color, userConfigExtraInfo?: string, }) { this.width = width; this.height = height; @@ -530,7 +589,9 @@ export class ChannelMediaInfo { * The user ID. */ uid: number - + /** + * @ignore + */ constructor(uid: number, {channelName, token}: { channelName?: string, token?: string }) { this.channelName = channelName; this.token = token; @@ -543,14 +604,26 @@ export class ChannelMediaInfo { */ export class ChannelMediaRelayConfiguration { /** - * Sets the information of the source channel. + * The information of the source channel: [`ChannelMediaInfo`]{@link ChannelMediaInfo}. It contains the following members: + * - `channelName`: The name of the source channel. The default value is null, which means the SDK applies the name of the current channel. + * - `uid`: ID of the host whose media stream you want to relay. The default value is 0, which means the SDK generates a random UID. You must set it as 0. + * - `token`: The token for joining the source channel. It is generated with the `channelName` and `uid` you set in `srcInfo`. + * - If you have not enabled the App Certificate, set this parameter as the default value null, which means the SDK applies the App ID. + * - If you have enabled the App Certificate, you must use the token generated with the `channelName` and `uid`, and the `uid` must be set as 0. */ srcInfo: ChannelMediaInfo /** - * Sets the information of the destination channel. + * 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. + * - `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. */ destInfos: ChannelMediaInfo[] - + /** + * @ignore + */ constructor(srcInfo: ChannelMediaInfo, destInfos: ChannelMediaInfo[]) { this.srcInfo = srcInfo; this.destInfos = destInfos; @@ -577,7 +650,9 @@ export class LastmileProbeConfig { * The expected maximum receive bitrate in bps in range of [100000,5000000]. */ expectedDownlinkBitrate: number - + /** + * @ignore + */ constructor(probeUplink: boolean, probeDownlink: boolean, expectedUplinkBitrate: number, expectedDownlinkBitrate: number) { this.probeUplink = probeUplink; this.probeDownlink = probeDownlink; @@ -606,7 +681,9 @@ export class Rectangle { * The height (pixels) of the watermark image. */ height: number - + /** + * @ignore + */ constructor(x: number, y: number, width: number, height: number) { this.x = x; this.y = y; @@ -633,7 +710,9 @@ export class WatermarkOptions { * The watermark position in the portrait mode. */ positionInPortraitMode: Rectangle - + /** + * @ignore + */ constructor(positionInLandscapeMode: Rectangle, positionInPortraitMode: Rectangle, visibleInPreview?: boolean) { this.visibleInPreview = visibleInPreview; this.positionInLandscapeMode = positionInLandscapeMode; @@ -642,15 +721,15 @@ export class WatermarkOptions { } /** - * Configuration of the imported live broadcast voice or video stream. + * Configuration of the imported live interactive voice or video stream. */ export class LiveInjectStreamConfig { /** - * Width of the added stream to the live interactive streaming. The default value is 0, which is the same width as the original stream. + * Width (pixels) of the added stream to the live interactive streaming. The default value is 0, which is the same width as the original stream. */ width?: number /** - * Height of the added stream to the live interactive streaming. The default value is 0, which is the same height as the original stream. + * Height (pixels) of the added stream to the live interactive streaming. The default value is 0, which is the same height as the original stream. */ height?: number /** @@ -666,18 +745,27 @@ export class LiveInjectStreamConfig { */ videoBitrate?: number /** - * Audio sample rate of the added stream to the live interactive streaming: AudioSampleRateType. The default value is 44100 Hz. + * Audio sample rate of the added stream to the live interactive streaming. The default value is 44100 Hz. */ audioSampleRate?: AudioSampleRateType /** - * Audio bitrate of the added stream to the live interactive streaming. The default value is 48. + * Audio bitrate of the added stream to the live interactive streaming. The default value is 48 Kbps. */ audioBitrate?: number /** - * Audio channels to add into the live interactive streaming. The value ranges between `1` and `2`. The default value is `1`. + * Audio channels to be added to the live interactive streaming. + * + * 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 */ audioChannels?: AudioChannel - + /** + * @ignore + */ constructor({width, height, videoGop, videoFramerate, videoBitrate, audioSampleRate, audioBitrate, audioChannels}: { width?: number, height?: number, videoGop?: number, videoFramerate?: VideoFrameRate, videoBitrate?: number, audioSampleRate?: AudioSampleRateType, audioBitrate?: number, audioChannels?: AudioChannel }) { this.width = width; this.height = height; @@ -702,7 +790,9 @@ export class CameraCapturerConfiguration { * The camera direction. */ cameraDirection: CameraDirection - + /** + * @ignore + */ constructor(preference: CameraCaptureOutputPreference, cameraDirection: CameraDirection) { this.preference = preference; this.cameraDirection = cameraDirection; @@ -715,13 +805,19 @@ export class CameraCapturerConfiguration { export class ChannelMediaOptions { /** * Determines whether to subscribe to audio streams when the user joins the channel. + * - `true`: (Default) Subscribe. + * - `false`: Do not subscribe. */ autoSubscribeAudio: boolean /** * Determines whether to subscribe to video streams when the user joins the channel. + * - `true`: (Default) Subscribe. + * - `false`: Do not subscribe. */ autoSubscribeVideo: boolean - + /** + * @ignore + */ constructor(autoSubscribeAudio: boolean, autoSubscribeVideo: boolean) { this.autoSubscribeAudio = autoSubscribeAudio; this.autoSubscribeVideo = autoSubscribeVideo; diff --git a/src/src/Enums.ts b/src/src/Enums.ts index d7304189c..7c9e22c5c 100644 --- a/src/src/Enums.ts +++ b/src/src/Enums.ts @@ -775,7 +775,7 @@ export enum ChannelMediaRelayEvent { */ UpdateDestinationChannelNotChange = 9, /** - * 10: The destination channel name is NULL. + * 10: The destination channel name is null. */ UpdateDestinationChannelIsNil = 10, /** diff --git a/src/src/RtcChannel.native.ts b/src/src/RtcChannel.native.ts index 28c0ca022..880d88838 100644 --- a/src/src/RtcChannel.native.ts +++ b/src/src/RtcChannel.native.ts @@ -62,7 +62,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * and call the [`joinChannel`]{@link RtcChannel.joinChannel} method of each created `RtcChannel` object. * * After joining multiple channels, you can simultaneously subscribe to streams of all the channels, but publish a stream in only one channel at one time. - * @param channelId The unique channel name for the AgoraRTC session in the string format. + * @param channelId The unique channel name for the Agora RTC 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. @@ -74,6 +74,11 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * **Note** * - This parameter does not have a default value. You must set it. * - Do not set it as the empty string "". Otherwise, the SDK returns [`Refused(-5)`]{@link ErrorCode.Refused}. + * + * @returns + * - An `RtcChannel` instance, if the method call succeeds. + * - Null, if the method call fails. + * - [`Refused(-5)`]{@link ErrorCode.Refused}, if you set channelId as the empty string "". */ static async create(channelId: string): Promise { if (channels.get(channelId)) return channels.get(channelId) as RtcChannel; @@ -164,13 +169,13 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, /** * Sets the role of a user. * - * This method sets the role of a user, such as a host or an audience. In a Live-Broadcast channel, + * 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: * - The local client: [`ClientRoleChanged`]{@link RtcChannelEvents.ClientRoleChanged}. * - The remote client: [`UserJoined`]{@link RtcChannelEvents.UserJoined} - * or [`UserOffline(BecomeAudience)`]{@link RtcChannelEvents.UserOffline}. + * or [`UserOffline(BecomeAudience)`]{@link UserOfflineReason.BecomeAudience}. * @param role The role of the user. * */ @@ -182,13 +187,13 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * Joins the channel with a user ID. * * **Note** - * - If you are already in a channel, you cannot rejoin it with the same uid. + * - If you are already in a channel, you cannot rejoin it with the same UID. * - We recommend using different UIDs for different channels. * - 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. * * @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#temptoken). + * - 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 optionalInfo Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. * @param optionalUid The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If uid is not assigned (or set as 0), the SDK assigns a uid and reports it in the [`JoinChannelSuccess`]{@link RtcChannelEvents.JoinChannelSuccess} callback. The app must maintain this user ID. @@ -203,14 +208,14 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * Joins a channel with the user account. * * **Note** - * - If you are already in a channel, you cannot rejoin it with the same uid. + * - If you are already in a channel, you cannot rejoin it with the same user account. * - We recommend using different user accounts for different channels. * - 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. * * @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. - * - In situations requiring high security: Set it as the token generated at your server. For details, see Generate a token. + * - 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 userAccount The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. * - All lowercase English letters: a to z. * - All uppercase English letters: A to Z. @@ -229,7 +234,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * * A successful call of this method triggers the following callbacks: * - The local client: [`LeaveChannel`]{@link RtcChannelEvents.LeaveChannel}. - * - The remote client: [`UserOffline`]{@link RtcChannelEvents.UserOffline}, if the user leaving the channel is in a Communication channel, or is a host in a Live-Broadcast channel. + * - The remote client: [`UserOffline`]{@link RtcChannelEvents.UserOffline}, if the user leaving the channel is in a `Communication` channel, or is a host in a `LiveBroadcasting` channel. * */ leaveChannel(): Promise { @@ -251,7 +256,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, } /** - * Gets the connection state of the SDK. + * Gets the network connection state of the SDK. */ getConnectionState(): Promise { return AgoraRtcChannelModule.getConnectionState(this._channelId) @@ -262,8 +267,8 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * You must keep the following restrictions in mind when calling this method. * Otherwise, the SDK returns the [`Refused(-5)`]{@link ErrorCode.Refused}: * - This method publishes one stream only to the channel corresponding to the current [`RtcChannel`]{@link RtcChannel} instance. - * - In a Live-Broadcast channel, only a host can call this method. To switch the client role, call [`setClientRole`]{@link RtcChannel.setClientRole} of the current [`RtcChannel`]{@link RtcChannel} instance. - * - You can publish a stream to only one channel at a time. For details, see the advanced guide Join Multiple Channels. + * - In a `LiveBroadcasting` channel, only a host can call this method. To switch the client role, call [`setClientRole`]{@link RtcChannel.setClientRole} of the current [`RtcChannel`]{@link RtcChannel} instance. + * - You can publish a stream to only one channel at a time. For details, see the advanced guide *Join Multiple Channels*. */ publish(): Promise { return AgoraRtcChannelModule.publish(this._channelId) @@ -281,6 +286,11 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, /** * Gets the current call ID. + * + * @returns + * - The current call ID, if the method call succeeds. + * - The empty string "", if the method call fails. + * */ getCallId(): Promise { return AgoraRtcChannelModule.getCallId(this._channelId) @@ -386,7 +396,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * * @param uid The ID of the remote user. * @param pan The sound position of the remote user. The value ranges from -1.0 to 1.0: - * - 0.0: The remote sound comes from the front. + * - 0.0: (default) The remote sound comes from the front. * - -1.0: The remote sound comes from the left. * - 1.0: The remote sound comes from the right. * @param gain Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain. @@ -404,7 +414,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * **Note** * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. * - Ensure that the user joins a channel before calling this method. - * - This method can only be called by a host in a Live-Broadcast channel. + * - This method can only be called by a host in a `LiveBroadcasting` channel. * - This method adds only one stream HTTP/HTTPS URL address each time it is called. * * @param url The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, such as Chinese language characters. @@ -425,7 +435,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * * **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 broadcaster in a Live-Broadcast channel. + * - This method can only be called by a host in a `LiveBroadcasting` channel. * - This method removes only one stream HTTP/HTTPS URL address each time it is called. * * @param url The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes. The URL address must not contain special characters, @@ -445,7 +455,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * **Note** * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. * - Ensure that the user joins a channel before calling this method. - * - This method can only be called by a host in a Live-Broadcast channel. + * - This method can only be called by a host in a `LiveBroadcasting` channel. * - Ensure that you call this method before calling the [`addPublishStreamUrl`]{@link RtcChannel.addPublishStreamUrl} method. * * @param transcoding Sets the CDN live audio/video transcoding settings. @@ -468,8 +478,10 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * - If the [`ChannelMediaRelayStateChanged`]{@link RtcChannelEvents.ChannelMediaRelayStateChanged} callback returns [`Failure(3)`]{@link ChannelMediaRelayState.Failure}, an exception occurs during the media stream relay. * * **Note** + * - Contact support@agora.io before implementing this function. + * - We do not support string user accounts in this API. * - Call this method after joining the channel. - * - This method can only be called by a host in a Live-Broadcast channel. + * - This method can only be called by a host in a `LiveBroadcasting` channel. * - After a successful method call, if you want to call this method again, ensure that you call the [`stopChannelMediaRelay`]{@link RtcChannel.stopChannelMediaRelay} method to quit the current relay. * * @param channelMediaRelayConfiguration The configuration of the media stream relay. @@ -569,7 +581,7 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * * **Note** * - Call this method before the [`joinChannel`]{@link RtcChannel.joinChannel} method. - * - This method applies to the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile only. + * - This method applies to the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile only. * */ registerMediaMetadataObserver(): Promise { @@ -638,13 +650,9 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, } /** - * Injects an online media stream to a Live-Broadcast channel. - * - * If this method call succeeds, the servers pulls the voice or video stream and injects it into a live channel. This applies to scenarios where all audience members in the channel can watch a live show and interact with each other. + * Injects an online media stream to live interactive streaming. * - * **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 Live-Broadcast channel. + * If this method call succeeds, the server pulls the voice or video stream and injects it into a live channel. This applies to scenarios where all audience members in the channel can watch a live show and interact with each other. * * Calling this method triggers the following callbacks: * - The local client: @@ -655,9 +663,13 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * - [`UserJoined`]{@link RtcChannelEvents.UserJoined}(uid: 666), if the method call succeeds and the online * media stream is injected into the channel. * - * @param url The URL address to be added to the ongoing live broadcast. Valid protocols are RTMP, HLS, and FLV. + * **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. + * + * @param url The URL address to be added to the ongoing live interactive streaming. Valid protocols are RTMP, HLS, and FLV. * - Supported FLV audio codec type: AAC. - * - Supported FLV video codec type: H264(AVC). + * - Supported FLV video codec type: H264 (AVC). * @param config The [`LiveInjectStreamConfig`]{@link LiveInjectStreamConfig} object, which contains the configuration information for the added voice or video stream. * */ @@ -666,11 +678,11 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, } /** - * Removes the injected online media stream from a Live-Broadcast channel. + * Removes the injected online media stream from a `LiveBroadcasting` channel. * * This method removes the URL address added by [`addInjectStreamUrl`]{@link RtcChannel.addInjectStreamUrl}. * - * If you successfully remove the URL address from the Live-Broadcast, the SDK triggers the + * 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. * * @param url The URL address to be removed. @@ -686,8 +698,8 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * * **Note** * - * Set both the reliable and ordered parameters to true or false. Do not set one as true - * and the other as false. + * Set both the `reliable` and `ordered` parameters to `true` or `false`. Do not set one as `true` + * and the other as `false`. * @param reliable Sets whether the recipients are guaranteed to receive the data stream from the * sender within five seconds. * - `true`: The recipients receive the data from the sender within five seconds. If the recipient does @@ -696,6 +708,9 @@ export default class RtcChannel implements RtcAudioInterface, RtcVideoInterface, * @param ordered Determines whether the recipients receive the data stream in the sent order. * - `true`: The recipients receive the data in the sent order. * - `false`: The recipients do not receive the data in the sent order. + * @returns + * - Returns the stream ID, if the method call is successful. + * - < 0: Failure. The error code is related to the integer displayed in [Error Codes]{@link ErrorCode}. */ createDataStream(reliable: boolean, ordered: boolean): Promise { return AgoraRtcChannelModule.createDataStream(this._channelId, reliable, ordered); diff --git a/src/src/RtcEngine.native.ts b/src/src/RtcEngine.native.ts index 992dc70b8..af898a137 100644 --- a/src/src/RtcEngine.native.ts +++ b/src/src/RtcEngine.native.ts @@ -57,7 +57,7 @@ const RtcEngineEvent = new NativeEventEmitter(AgoraRtcEngineModule); let engine: RtcEngine | undefined; /** - * [`RtcEngine`]{@link RtcEngine} is the main interface class of the Agora SDK. + * [`RtcEngine`]{@link RtcEngine} is the main class of the Agora SDK. */ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterface, RtcVideoInterface, RtcAudioMixingInterface, RtcAudioEffectInterface, RtcVoiceChangerInterface, RtcVoicePositionInterface, RtcPublishStreamInterface, @@ -68,7 +68,17 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * @ignore */ private _listeners = new Map>(); - + /** + * Gets a created [`RtcEngine`]{@link RtcEngine} instance. + * + * **Note** + * + * Ensure that you have created an `RtcEngine`. Otherwise, the method call fails and the SDK returns an error message. + * @returns + * - The `RtcEngine` instance, if the method call succeeds. + * - Returns an error when it fails to get an `RtcEngine`. + * + */ static instance(): RtcEngine { if (engine) { return engine as RtcEngine; @@ -90,6 +100,9 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * 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. To change your App ID, call [`destroy`]{@link destroy} to destroy the current [`RtcEngine`]{@link RtcEngine} instance, and after [`destroy`]{@link destroy} returns `0`, * call `create` to create an [`RtcEngine`]{@link RtcEngine} instance with the new App ID. + * @returns + * - The `RtcEngine` instance, if the method call succeeds. + * - < 0, if the method call fails. */ static async create(appId: string): Promise { return RtcEngine.createWithAreaCode(appId, IPAreaCode.AREA_GLOBAL) @@ -112,6 +125,10 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * You can use the bitwise OR operator (|) to specify multiple areas. For details, see {@link IPAreaCode}. * * After specifying the region, the app that integrates the Agora SDK connects to the Agora servers within that region. + * + * @returns + * - The `RtcEngine` instance, if the method call succeeds. + * - < 0, if the method call fails. */ static async createWithAreaCode(appId: string, areaCode: IPAreaCode): Promise { if (engine) return engine; @@ -214,11 +231,11 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac } /** - * Sets the role of a user ([Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} only). + * Sets the role of a user ([`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} only). * * 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 [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile, when a user switches user roles after joining a channel, a successful call of this method triggers the following callbacks: + * 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: * - The local client: [`ClientRoleChanged`]{@link RtcEngineEvents.ClientRoleChanged}. * - The remote client: [`UserJoined`]{@link RtcEngineEvents.UserJoined} or [`UserOffline`]{@link RtcEngineEvents.UserOffline} ([`BecomeAudience`]{@link UserOfflineReason.BecomeAudience}). * @@ -239,8 +256,8 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * - The local client: [`JoinChannelSuccess`]{@link RtcEngineEvents.JoinChannelSuccess}. * - * - The remote client: [`UserJoined`]{@link RtcEngineEvents.UserJoined}, if the user joining the channel is in the [Communication]{@link ChannelProfile.Communication} profile, - * or is a [`Broadcaster`]{@link ClientRole.Broadcaster} in the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile. + * - The remote client: [`UserJoined`]{@link RtcEngineEvents.UserJoined}, 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. * * 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. @@ -254,7 +271,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * 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#temptoken). + * - 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 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. @@ -277,17 +294,17 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac /** * Switches to a different channel. * - * This method allows the audience of a [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} channel to switch to a different channel. + * This method allows the audience of a [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} channel to switch to a different channel. * * 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. * * **Note** * - * This method applies to the [`Audience`]{@link ClientRole.Audience} role in a [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} channel only. + * 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#temptoken). + * - 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 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. @@ -311,8 +328,8 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * A successful [`leaveChannel`]{@link leaveChannel} method call triggers the following callbacks: * - The local client: [`LeaveChannel`]{@link RtcEngineEvents.LeaveChannel}. * - * - The remote client: [`UserOffline`]{@link RtcEngineEvents.UserOffline}, if the user leaving the channel is in the [Communication]{@link ChannelProfile.Communication} channel, or is a [`Broadcaster`]{@link ClientRole.Broadcaster} - * in the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile. + * - The remote client: [`UserOffline`]{@link RtcEngineEvents.UserOffline}, if the user leaving the channel is in the [`Communication`]{@link ChannelProfile.Communication} channel, or is a [`Broadcaster`]{@link ClientRole.Broadcaster} + * in the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile. * * **Note** * - If you call [`destroy`]{@link destroy} immediately after calling [`leaveChannel`]{@link leaveChannel}, the [`leaveChannel`]{@link leaveChannel} process interrupts, and the SDK does not trigger the [`LeaveChannel`]{@link RtcEngineEvents.LeaveChannel} callback. @@ -340,7 +357,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac } /** - * Enables interoperability with the Agora Web SDK ([Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} only). + * Enables interoperability with the Agora Web SDK ([`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} only). * * **Deprecated** * @@ -348,7 +365,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * * If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user. - * Use this method when the channel profile is [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting}. Interoperability with the Agora Web SDK is enabled by default when the channel profile is [Communication]{@link ChannelProfile.Communication}. + * Use this method when the channel profile is [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting}. Interoperability with the Agora Web SDK is enabled by default when the channel profile is [`Communication`]{@link ChannelProfile.Communication}. * @param enabled Sets whether to enable/disable interoperability with the Agora Web SDK: * - `true`: Enable. * - `false`: (Default) Disable. @@ -372,6 +389,9 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * The [`rate`]{@link rate} and [`complain`]{@link complain} methods require the `callId` parameter retrieved from the [`getCallId`]{@link getCallId} method during a call. * `callId` is passed as an argument into the [`rate`]{@link rate} and [`complain`]{@link complain} methods after the call ends. + * + * @returns + * Current call ID. */ getCallId(): Promise { return AgoraRtcEngineModule.getCallId() @@ -440,6 +460,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac } /** + * @ignore * Provides technical preview functionalities or special customizations by configuring the SDK with JSON options. * * The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way. @@ -479,7 +500,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * After the user successfully joins the channel, the SDK triggers the following callbacks: * - The local client: [`LocalUserRegistered`]{@link RtcEngineEvents.LocalUserRegistered} and [`JoinChannelSuccess`]{@link RtcEngineEvents.JoinChannelSuccess}. * - * - 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 [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile. + * - 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. * * **Note** * @@ -487,7 +508,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * 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#temptoken). + * - 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 channelName The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: * - All lowercase English letters: a to z. @@ -741,7 +762,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * **Note** * * - You must call this method before calling [`joinChannel`]{@link joinChannel}. - * - In the [Communication]{@link ChannelProfile.Communication} and [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profiles, the bitrates may be different from your settings due to network self-adaptation. + * - In the [`Communication`]{@link ChannelProfile.Communication} and [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profiles, the bitrates may be different from your settings due to network self-adaptation. * - In scenarios requiring high-quality audio, we recommend setting profile as [`MusicHighQuality(4)`]{@link AudioProfile.MusicHighQuality} and scenario as [`GameStreaming(3)`]{@link AudioScenario.GameStreaming}. * For example, for music education scenarios. * @@ -916,7 +937,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * **Note** * * - Call this method after calling [`enableVideo`]{@link enableVideo}. - * - This method applies to Android 4.4 or later. + * - On Android，this method applies to Android 4.4 or later. * * @param enabled Sets whether to enable image enhancement: * - `true`: Enable image enhancement. @@ -1032,6 +1053,10 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * **Note** * * Call this method when you are in a channel. + * + * @returns + * - Returns the current playback position of the audio mixing, if the method call is successful. + * - < 0: Failure. */ getAudioMixingCurrentPosition(): Promise { return AgoraRtcEngineModule.getAudioMixingCurrentPosition(); @@ -1043,6 +1068,10 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * **Note** * * Call this method when you are in a channel. + * + * @returns + * - Returns the audio mixing duration, if the method call is successful. + * - < 0: Failure. */ getAudioMixingDuration(): Promise { return AgoraRtcEngineModule.getAudioMixingDuration(); @@ -1052,6 +1081,10 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * Gets the audio mixing volume for local playback. * * This method helps troubleshoot audio volume related issues. + * + * @returns + * - Returns the audio mixing volume for local playback, if the method call is successful. The value range is [0,100]. + * - < 0: Failure. */ getAudioMixingPlayoutVolume(): Promise { return AgoraRtcEngineModule.getAudioMixingPlayoutVolume(); @@ -1061,6 +1094,10 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * Gets the audio mixing volume for publishing. * * This method helps troubleshoot audio volume related issues. + * + * @returns + * - Returns the audio mixing volume for publishing, if the method call is successful. The value range is [0,100]. + * - < 0: Failure. */ getAudioMixingPublishVolume(): Promise { return AgoraRtcEngineModule.getAudioMixingPublishVolume(); @@ -1127,15 +1164,15 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * **Note** * - * - To use this method, ensure that the Android device is v4.2 or later, and the API version is v16 or later. + * - To use this method on Android, ensure that the Android device is v4.2 or later, and the API version is v16 or later. * * - Call this method when you are in the channel, otherwise it may cause issues. * - * - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the [`TooFrequentCall = 702`]{@link AudioMixingErrorCode.TooFrequentCall} error occurs. + * - If you want to play an online music file, ensure that the time interval between calling this method is more than 100 ms, or the [`TooFrequentCall(702)`]{@link AudioMixingErrorCode.TooFrequentCall} error occurs. * * - If you want to play an online music file, Agora does not recommend using the redirected URL address. Some Android devices may fail to open a redirected URL address. * - * - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns [`CanNotOpen = 701`]{@link AudioMixingErrorCode.CanNotOpen}. + * - If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns [`CanNotOpen(701)`]{@link AudioMixingErrorCode.CanNotOpen}. * * - If you call this method on an emulator, only the MP3 file format is supported. * @@ -1170,6 +1207,10 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * Gets the volume of the audio effects. * * The value ranges between 0.0 and 100.0. + * + * @returns + * - Returns the volume, if the method call is successful. + * - < 0: Failure. */ getEffectsVolume(): Promise { return AgoraRtcEngineModule.getEffectsVolume(); @@ -1419,7 +1460,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * **Note** * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. - * - This method applies to [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} only. + * - This method applies to [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} only. * - Ensure that the user joins a channel before calling this method. * - This method adds only one stream HTTP/HTTPS URL address each time it is called. * @param url The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. @@ -1441,9 +1482,9 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * The SDK reports the result of this method call in the [`RtmpStreamingStateChanged`]{@link RtcEngineEvents.RtmpStreamingStateChanged} callback. * * **Note** - * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN. + * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. * - Ensure that the user joins a channel before calling this method. - * - This method applies to [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} only. + * - This method applies to [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} only. * - This method removes only one stream RTMP URL address each time it is called. * @param url The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes. * The URL address must not contain special characters, such as Chinese language characters. @@ -1461,7 +1502,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * **Note** * - * - This method applies to [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} only. + * - This method applies to [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} only. * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in Push Streams to CDN. * - Ensure that you call [`setClientRole`]{@link setClientRole} and set the user role as the host. * - Ensure that you call [`setLiveTranscoding`]{@link setLiveTranscoding} before calling [`addPublishStreamUrl`]{@link addPublishStreamUrl}. @@ -1490,7 +1531,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * - We do not support string user accounts in this API. * - Call this method after the [`joinChannel`]{@link joinChannel} method. * - This method takes effect only when you are a [`Broadcaster`]{@link ClientRole.Broadcaster} - * in a [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} channel. + * in a [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} channel. * - After a successful method call, if you want to call this method again, ensure that you call [`stopChannelMediaRelay`]{@link stopChannelMediaRelay} to quit the current relay. * * @param channelMediaRelayConfiguration The configuration of the media stream relay. @@ -1540,6 +1581,10 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac /** * Checks whether the speakerphone is enabled. + * + * @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. */ isSpeakerphoneEnabled(): Promise { return AgoraRtcEngineModule.isSpeakerphoneEnabled(); @@ -1554,17 +1599,17 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * joining a channel, call [`setEnableSpeakerphone`]{@link setEnableSpeakerphone}. * * The default audio route for each scenario: - * - In the [Communication]{@link ChannelProfile.Communication} profile: + * - In the [`Communication`]{@link ChannelProfile.Communication} profile: * * - For a voice call, the default audio route is the earpiece. * - For a video call, the default audio route is the speaker. If the user disables the video * using [`disableVideo`]{@link disableVideo}, or [`muteLocalVideoStream`]{@link muteLocalVideoStream} and [`muteAllRemoteVideoStreams`]{@link muteAllRemoteVideoStreams}, the default audio route automatically switches back to the earpiece. * - * - In the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile: The default audio route is the speaker. + * - In the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile: The default audio route is the speaker. * * **Note** * - * - This method applies to the [Communication]{@link ChannelProfile.Communication} profile only. + * - This method applies to the [`Communication`]{@link ChannelProfile.Communication} profile only. * - Call this method before the user joins a channel. * @param defaultToSpeaker Sets the default audio route: * - `true`: Route the audio to the speaker. If the playback device connects to the earpiece or Bluetooth, the audio cannot be routed to the earpiece. @@ -1584,7 +1629,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * - Ensure that you have successfully called [`joinChannel`]{@link joinChannel} before calling this method. * - * - This method is invalid for audience users in the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile. + * - This method is invalid for audience users in the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile. * * @param enabled Sets whether to route the audio to the speakerphone or earpiece: * - `true`: Route the audio to the speakerphone. @@ -1740,7 +1785,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * - Do not call any other methods before receiving the [`LastmileQuality`]{@link RtcEngineEvents.LastmileQuality} callback. Otherwise, the callback may be interrupted by other methods and may not execute. * - * - In the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile, a host should not call this method after joining a channel. + * - 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. * @@ -1761,7 +1806,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * - After calling this method, call [`stopEchoTest`]{@link stopEchoTest} to end the test. * Otherwise, the app cannot run the next echo test, or call [`joinChannel`]{@link joinChannel}. * - * - In the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile, only a host can call this method. + * - In the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile, only a host can call this method. * @param intervalInSeconds The time interval (s) between when you speak and when the recording plays back. */ startEchoTest(intervalInSeconds: number): Promise { @@ -1785,7 +1830,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * - This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method together with [`enableLastmileTest`]{@link enableLastmileTest}. * - Do not call other methods before receiving the [`LastmileQuality`]{@link RtcEngineEvents.LastmileQuality} and [`LastmileProbeResult`]{@link RtcEngineEvents.LastmileProbeResult} callbacks. Otherwise, the callbacks may be interrupted by other methods. - * - In the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile, a host should not call this method after joining a channel. + * - In the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile, a host should not call this method after joining a channel. * * @param config The configurations of the last-mile network probe test. * @@ -1970,7 +2015,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac } /** - * Injects an online media stream to a live interactive streaming channel. + * Injects an online media stream to live interactive streaming. * * If this method call is successful, the server pulls the voice or video stream and injects it into * a live channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other. @@ -1986,7 +2031,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * **Note** * - * - This method applies to the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile only. + * - This method applies to the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile only. * - Ensure that you enable the RTMP Converter service before using this function. See Prerequisites in *Push Streams to CDN*. * - You can inject only one media stream into the channel at the same time. * @@ -2032,6 +2077,8 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac /** * Gets the maximum zoom ratio supported by the camera. + * + * @returns The maximum camera zoom factor. */ getCameraMaxZoomFactor(): Promise { return AgoraRtcEngineModule.getCameraMaxZoomFactor(); @@ -2039,6 +2086,12 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac /** * Checks whether the camera auto-face focus function is supported. + * + * @returns + * + * - `true`: The device supports the camera auto-face focus function. + * - `false`: The device does not support the camera auto-face focus function. + * */ isCameraAutoFocusFaceModeSupported(): Promise { return AgoraRtcEngineModule.isCameraAutoFocusFaceModeSupported(); @@ -2046,6 +2099,12 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac /** * Checks whether the camera exposure function is supported. + * + * @returns + * + * - `true`: The device supports the camera exposure function. + * - `false`: The device does not support the camera exposure function. + * */ isCameraExposurePositionSupported(): Promise { return AgoraRtcEngineModule.isCameraExposurePositionSupported(); @@ -2053,6 +2112,12 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac /** * Checks whether the camera manual focus function is supported. + * + * @returns + * + * - `true`: The device supports the camera manual focus function. + * - `false`: The device does not support the camera manual focus function. + * */ isCameraFocusSupported(): Promise { return AgoraRtcEngineModule.isCameraFocusSupported(); @@ -2060,6 +2125,12 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac /** * Checks whether the camera flash function is supported. + * + * @returns + * + * - `true`: The device supports the camera flash function. + * - `false`: The device does not the support camera flash function. + * */ isCameraTorchSupported(): Promise { return AgoraRtcEngineModule.isCameraTorchSupported(); @@ -2067,6 +2138,12 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac /** * Checks whether the camera zoom function is supported. + * + * @returns + * + * - `true`: The device supports the camera zoom function. + * - `false`: The device does not support the camera zoom function. + * */ isCameraZoomSupported(): Promise { return AgoraRtcEngineModule.isCameraZoomSupported(); @@ -2173,6 +2250,10 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * @param ordered Sets whether the recipients receive the data stream in the sent order: * - `true`: The recipients receive the data in the sent order. * - `false`: The recipients do not receive the data in the sent order. + * + * @return + * - Returns the stream ID, if the method call is successful. + * - < 0: Failure. The error code is related to the integer displayed in [Error Codes]{@link ErrorCode}. */ createDataStream(reliable: boolean, ordered: boolean): Promise { return AgoraRtcEngineModule.createDataStream(reliable, ordered); @@ -2195,7 +2276,7 @@ export default class RtcEngine implements RtcUserInfoInterface, RtcAudioInterfac * * - Ensure that you have created the data stream using [`createDataStream`]{@link createDataStream} before calling this method. * - * - This method applies only to the [Communication]{@link ChannelProfile.Communication} profile or to hosts in the [Live-Broadcast]{@link ChannelProfile.LiveBroadcasting} profile. + * - This method applies only to the [`Communication`]{@link ChannelProfile.Communication} profile or to hosts in the [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profile. * @param streamId ID of the sent data stream returned by the [`createDataStream`]{@link createDataStream} method. * @param message Sent data. */ diff --git a/src/src/RtcEvents.ts b/src/src/RtcEvents.ts index 2807fb708..97ede6d50 100644 --- a/src/src/RtcEvents.ts +++ b/src/src/RtcEvents.ts @@ -707,6 +707,10 @@ export interface RtcEngineEvents { * * This callback indicates the state change of the remote audio stream. * + * **Note** + * + * This callback does not work properly when the number of users (in the [`Communication`] profile) or hosts (in the [`LiveBroadcasting`] profile) in the channel exceeds 17. + * * @event RemoteAudioStateChanged */ RemoteAudioStateChanged: RemoteAudioStateCallback @@ -911,7 +915,7 @@ export interface RtcEngineEvents { * The SDK triggers this callback to report the result of the local user calling [`addPublishStreamUrl`]{@link RtcEngine.addPublishStreamUrl} or [`removePublishStreamUrl`]{@link RtcEngine.removePublishStreamUrl}. * This callback returns the URL and its current streaming state. When the streaming state is [`Failure`]{@link RtmpStreamingState.Failure}, see the errCode parameter for details. * - * This callback indicates the state of the RTMP streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the errCode parameter. + * This callback indicates the state of the RTMP streaming. When exceptions occur, you can troubleshoot issues by referring to the detailed error descriptions in the `errCode` parameter. * * @event RtmpStreamingStateChanged */ @@ -1311,12 +1315,18 @@ export interface RtcChannelEvents { ClientRoleChanged: ClientRoleCallback /** - * Occurs when a remote user (Communication) or a broadcaster (Live-Broadcast) joins the channel. - * - Communication profile: This callback notifies the app when another user joins the channel. If other users are already in the channel, the SDK also reports to the app on the existing users. - * - Live-Broadcast profile: This callback notifies the app when the host joins the channel. If other hosts are already in the channel, the SDK also reports to the app on the existing hosts. We recommend having at most 17 hosts in a channel. + * Occurs when a remote user (`Communication`) or a host (`LiveBroadcasting`) joins the channel. + * - `Communication` profile: This callback notifies the app when another user joins the channel. If other users are already in the channel, the SDK also reports to the app on the existing users. + * - `LiveBroadcasting` profile: This callback notifies the app when the host joins the channel. If other hosts are already in the channel, the SDK also reports to the app on the existing hosts. We recommend having at most 17 hosts in a channel. + * + * The SDK triggers this callback under one of the following circumstances: + * - A remote user/host joins the channel by calling [`joinChannel`]{@link RtcChannel.joinChannel}. + * - A remote user switches the user role to the host by calling [`setClientRole`]{@link RtcChannel.setClientRole} after joining the channel. + * - A remote user/host rejoins the channel after a network interruption. + * - The host injects an online media stream into the channel by calling [`addInjectStreamUrl`]{@link RtcChannel.addInjectStreamUrl}. * * **Note** - * - In the Live-Broadcast profile: + * - In the `LiveBroadcasting` profile: * - The host receives this callback when another host joins the channel. * - The audience in the channel receives this callback when a new host joins the channel. * - When a web app joins the channel, this callback is triggered as long as the web app publishes streams. @@ -1326,11 +1336,11 @@ export interface RtcChannelEvents { UserJoined: UidWithElapsedCallback /** - * Occurs when a remote user (Communication) or a broadcaster (Live Broadcast) leaves the channel. + * Occurs when a remote user (`Communication`) or a host (`LiveBroadcasting`) leaves the channel. * * There are two reasons for users to become offline: - * - Leave the channel: When the user/broadcaster leaves the channel, the user/broadcaster sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel. - * - Go offline: When no data packet of the user or broadcaster is received for a certain period of time (around 20 seconds), the SDK assumes that the user/broadcaster drops offline. A poor network connection may lead to false detections, so we recommend using the Agora RTM SDK for reliable offline detection. + * - Leave the channel: When the user/host leaves the channel, the user/host sends a goodbye message. When this message is received, the SDK determines that the user/host leaves the channel. + * - Go offline: When no data packet of the user or host is received for a certain period of time (around 20 seconds), the SDK assumes that the user/host drops offline. A poor network connection may lead to false detections, so we recommend using the Agora RTM SDK for reliable offline detection. * * @event UserOffline */ @@ -1419,7 +1429,7 @@ export interface RtcChannelEvents { /** * Occurs when the published media stream falls back to an audio-only stream due to poor network conditions or switches back to video stream after the network conditions improve. * - * If you call {@link RtcEngine.setLocalPublishFallbackOption} and set option as [`AudioOnly`]{@link StreamFallbackOptions.AudioOnly}, this callback is triggered when the locally published stream falls back to audio-only mode due to poor uplink conditions, or when the audio stream switches back to the video after the uplink network condition improves. + * If you call [`setLocalPublishFallbackOption`]{@link RtcEngine.setLocalPublishFallbackOption} and set `option` as [`AudioOnly`]{@link StreamFallbackOptions.AudioOnly}, this callback is triggered when the locally published stream falls back to audio-only mode due to poor uplink conditions, or when the audio stream switches back to the video after the uplink network condition improves. * * @event LocalPublishFallbackToAudioOnly */ @@ -1457,16 +1467,16 @@ export interface RtcChannelEvents { NetworkQuality: NetworkQualityWithUidCallback /** - * Reports the statistics of the video stream from each remote user/broadcaster. The SDK triggers this callback once every two seconds for each remote user/broadcaster. If a channel includes multiple remote users, the SDK triggers this callback as many times. + * Reports the statistics of the video stream from each remote user/host. The SDK triggers this callback once every two seconds for each remote user/broadcaster. If a channel includes multiple remote users, the SDK triggers this callback as many times. * * @event RemoteVideoStats */ RemoteVideoStats: RemoteVideoStatsCallback /** - * Reports the statistics of the audio stream from each remote user/broadcaster. + * Reports the statistics of the audio stream from each remote user/host. * - * The SDK triggers this callback once every two seconds for each remote user/broadcaster. If a channel includes multiple remote users, the SDK triggers this callback as many times. + * The SDK triggers this callback once every two seconds for each remote user/host. If a channel includes multiple remote users, the SDK triggers this callback as many times. * * Schemes such as FEC (Forward Error Correction) or retransmission counter the frame loss rate. Hence, users may find the overall audio quality acceptable even when the packet loss rate is high. * @@ -1508,7 +1518,7 @@ export interface RtcChannelEvents { /** * Occurs when the local user receives a remote data stream. * - * The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the {@link RtcChannel.sendStreamMessage} method. + * The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the [`sendStreamMessage`]{@link RtcChannel.sendStreamMessage} method. * * @event StreamMessage */