diff --git a/src/AgoraBase.ts b/src/AgoraBase.ts index 86f4b680..e371f5ae 100644 --- a/src/AgoraBase.ts +++ b/src/AgoraBase.ts @@ -1947,7 +1947,7 @@ export enum LocalAudioStreamError { */ LocalAudioStreamErrorDeviceNoPermission = 2, /** - * @ignore + * 3: The local audio capture device is already in use. Remind your users to check whether another application occupies the microphone. Local audio capture automatically resumes after the microphone is idle for about five seconds. You can also try to rejoin the channel after the microphone is idle. */ LocalAudioStreamErrorDeviceBusy = 3, /** @@ -3094,7 +3094,7 @@ export enum ConnectionChangedReasonType { */ ConnectionChangedClientIpAddressChanged = 13, /** - * 14: Timeout for the keep-alive of the connection between the SDK and the Agora edge server. The connection state changes to . + * 14: Timeout for the keep-alive of the connection between the SDK and the Agora edge server. The SDK tries to reconnect to the server automatically. */ ConnectionChangedKeepAliveTimeout = 14, /** diff --git a/src/IAgoraMediaEngine.ts b/src/IAgoraMediaEngine.ts index 118579fd..1b4dba4b 100644 --- a/src/IAgoraMediaEngine.ts +++ b/src/IAgoraMediaEngine.ts @@ -66,7 +66,7 @@ export abstract class IMediaEngine { * Ensure that you call this method before joining a channel. * When handling the video data returned in the callbacks, pay attention to the changes in the width and height parameters, which may be adapted under the following circumstances: * When network conditions deteriorate, the video resolution decreases incrementally. - * If the user adjusts the video profile, the resolution of the video returned in the callbacks also changes. After registering the raw video observer, you can use the obtained raw video data in various video pre-processing scenarios, such as implementing virtual backgrounds and image enhacement scenarios by yourself, Agora provides some open source sample projects on GitHub for your reference. + * If the user adjusts the video profile, the resolution of the video returned in the callbacks also changes. * * @param observer The observer instance. See IVideoFrameObserver. * diff --git a/src/IAgoraRtcEngine.ts b/src/IAgoraRtcEngine.ts index b949c39e..0cc73542 100644 --- a/src/IAgoraRtcEngine.ts +++ b/src/IAgoraRtcEngine.ts @@ -1020,7 +1020,7 @@ export class AdvancedAudioOptions { */ export class ImageTrackOptions { /** - * The URL of the image that you want to use to replace the video feeds. The image must be in PNG format. This method supports adding an image from the local absolute or relative file path. On the Android platform, adding images from /assets/ is not supported. + * The image URL. Supported formats of images include JPEG, JPG, PNG and GIF. This method supports adding an image from the local absolute or relative file path. On the Android platform, adding images from /assets/ is not supported. */ imageUrl?: string; /** @@ -1036,7 +1036,7 @@ export class ImageTrackOptions { /** * The channel media options. * - * Agora supports publishing multiple audio streams and one video stream at the same time and in the same RtcConnection. For example, publishMicrophoneTrack, publishAudioTrack, publishCustomAudioTrack, and publishMediaPlayerAudioTrack can be set as true at the same time, but only one of publishCameraTrack, publishScreenCaptureVideo, publishCustomVideoTrack, or publishEncodedVideoTrack can be set as true. Agora recommends that you set member parameter values yourself according to your business scenario, otherwise the SDK will automatically assign values to member parameters. + * Agora supports publishing multiple audio streams and one video stream at the same time and in the same RtcConnection. For example, publishMicrophoneTrack, publishCustomAudioTrack, and publishMediaPlayerAudioTrack can be set as true at the same time, but only one of publishCameraTrack, publishScreenCaptureVideo, publishCustomVideoTrack, or publishEncodedVideoTrack can be set as true. Agora recommends that you set member parameter values yourself according to your business scenario, otherwise the SDK will automatically assign values to member parameters. */ export class ChannelMediaOptions { /** @@ -1264,7 +1264,7 @@ export interface IRtcEngineEventHandler { * * @param channel The channel name. * @param uid The user ID. - * @param proxyType The proxy type connected. See CloudProxyType. + * @param proxyType The proxy type connected. See ProxyType. * @param localProxyIp Reserved for future use. * @param elapsed The time elapsed (ms) from the user calling joinChannel until this callback is triggered. */ @@ -1897,7 +1897,7 @@ export interface IRtcEngineEventHandler { * * When the token expires during a call, the SDK triggers this callback to remind the app to renew the token. When receiving this callback, you need to generate a new token on your token server and you can renew your token through one of the following ways: * Call renewToken to pass in the new token. - * Call to leave the current channel and then pass in the new token when you call joinChannel to join a channel. + * Call leaveChannel to leave the current channel and then pass in the new token when you call joinChannel to join a channel. * * @param connection The connection information. See RtcConnection. */ @@ -2070,7 +2070,7 @@ export interface IRtcEngineEventHandler { /** * Occurs when the user role switching fails in the interactive live streaming. * - * In the live broadcasting channel profile, when the local user calls to switch the user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role. + * In the live broadcasting channel profile, when the local user calls setClientRole to switch the user role after joining the channel but the switch fails, the SDK triggers this callback to report the reason for the failure and the current user role. * * @param connection The connection information. See RtcConnection. * @param reason The reason for a user role switch failure. See ClientRoleChangeFailedReason. @@ -2882,7 +2882,7 @@ export abstract class IRtcEngine { * @param token The token generated on your server for authentication. When the token for preloading channels expires, you can update the token based on the number of channels you preload. * When preloading one channel, calling this method to pass in the new token. * When preloading more than one channels: - * If you use a wildcard token for all preloaded channels, call updatePreloadChannelToken to update the token. + * If you use a wildcard token for all preloaded channels, call updatePreloadChannelToken to update the token. When generating a wildcard token, ensure the user ID is not set as 0. * If you use different tokens to preload different channels, call this method to pass in your user ID, channel name and the new token. * @param channelId The channel name that you want to preload. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters (89 characters in total): * All lowercase English letters: a to z. @@ -2916,7 +2916,7 @@ export abstract class IRtcEngine { * @param token The token generated on your server for authentication. When the token for preloading channels expires, you can update the token based on the number of channels you preload. * When preloading one channel, calling this method to pass in the new token. * When preloading more than one channels: - * If you use a wildcard token for all preloaded channels, call updatePreloadChannelToken to update the token. + * If you use a wildcard token for all preloaded channels, call updatePreloadChannelToken to update the token. When generating a wildcard token, ensure the user ID is not set as 0. * If you use different tokens to preload different channels, call this method to pass in your user ID, channel name and the new token. * @param channelId The channel name that you want to preload. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters (89 characters in total): * All lowercase English letters: a to z. @@ -2968,7 +2968,7 @@ export abstract class IRtcEngine { * This method allows users to join only one channel at a time. * Ensure that the app ID you use to generate the token is the same app ID that you pass in the initialize method; otherwise, you may fail to join the channel by token. * - * @param token The token generated on your server for authentication. + * @param token The token generated on your server for authentication. If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. * @param channelId The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters: * All lowercase English letters: a to z. * All uppercase English letters: A to Z. @@ -3043,7 +3043,7 @@ export abstract class IRtcEngine { /** * Sets the channel profile. * - * After initializing the SDK, the default channel profile is the live streaming profile. You can call this method to set the usage scenario of the channel. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for the interactive live video streaming. + * After initializing the SDK, the default channel profile is the live streaming profile. You can call this method to set the channel profile. The Agora SDK differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call and prioritizes video quality for interactive live video streaming. * To ensure the quality of real-time communication, Agora recommends that all users in a channel use the same channel profile. * This method must be called and set before joinChannel, and cannot be set again after joining the channel. * The default audio route and video encoding bitrate are different in different channel profiles. See setDefaultAudioRouteToSpeakerphone and setVideoEncoderConfiguration. @@ -3064,7 +3064,7 @@ export abstract class IRtcEngine { * In the interactive live streaming profile, the SDK sets the user role as audience by default. You can call this method to set the user role as host. You can call this method either before or after joining a channel. If you call this method to switch the user role after joining a channel, the SDK automatically does the following: * Calls muteLocalAudioStream and muteLocalVideoStream to change the publishing state. * Triggers onClientRoleChanged on the local client. - * Triggers onUserJoined or onUserOffline on the remote client. This method applies to the interactive live streaming profile (the profile parameter of setChannelProfile is ChannelProfileLiveBroadcasting) only. + * Triggers onUserJoined or onUserOffline on the remote client. This method applies to the interactive live streaming profile (the profile parameter of setChannelProfile is set as ChannelProfileLiveBroadcasting) only. * * @param role The user role in the interactive live streaming. See ClientRoleType. * @param options The detailed options of a user, including the user level. See ClientRoleOptions. @@ -3113,13 +3113,13 @@ export abstract class IRtcEngine { * * In scenarios where there are existing cameras to capture video, Agora recommends that you use the following steps to capture and publish video with multiple cameras: * Call this method to enable multi-channel camera capture. - * Call to start the local video preview. + * Call startPreview to start the local video preview. * Call startCameraCapture, and set sourceType to start video capture with the second camera. * Call joinChannelEx, and set publishSecondaryCameraTrack to true to publish the video stream captured by the second camera in the channel. If you want to disable multi-channel camera capture, use the following steps: * Call stopCameraCapture. - * Call this method with enabled set to false. You can call this method before and after to enable multi-camera capture: - * If it is enabled before, the local video preview shows the image captured by the two cameras at the same time. - * If it is enabled after, the SDK stops the current camera capture first, and then enables the primary camera and the second camera. The local video preview appears black for a short time, and then automatically returns to normal. When using this function, ensure that the system version is 13.0 or later. The minimum iOS device types that support multi-camera capture are as follows: + * Call this method with enabled set to false. You can call this method before and after startPreview to enable multi-camera capture: + * If it is enabled before startPreview, the local video preview shows the image captured by the two cameras at the same time. + * If it is enabled after startPreview, the SDK stops the current camera capture first, and then enables the primary camera and the second camera. The local video preview appears black for a short time, and then automatically returns to normal. When using this function, ensure that the system version is 13.0 or later. The minimum iOS device types that support multi-camera capture are as follows: * iPhone XR * iPhone XS * iPhone XS Max @@ -3171,7 +3171,6 @@ export abstract class IRtcEngine { * Call enableVideo to enable the video module. * The local preview enables the mirror mode by default. * After the local video preview is enabled, if you call leaveChannel to exit the channel, the local preview remains until you call stopPreview to disable it. - * The video source type set in this method needs to be consistent with the video source type of VideoCanvas you set in setupLocalVideo. * * @param sourceType The type of the video source. See VideoSourceType. * @@ -3239,12 +3238,14 @@ export abstract class IRtcEngine { * Sets the image enhancement options. * * Enables or disables image enhancement, and sets the options. - * Call this method before calling enableVideo or. + * Call this method before calling enableVideo or startPreview. * This method relies on the video enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. * * @param enabled Whether to enable the image enhancement function: true : Enable the image enhancement function. false : (Default) Disable the image enhancement function. * @param options The image enhancement options. See BeautyOptions. - * @param type The type of the video source, see MediaSourceType. + * @param type Type of media source. See MediaSourceType. In this method, this parameter supports only the following two settings: + * The default value is UnknownMediaSource. + * If you want to use the second camera to capture video, set this parameter to SecondaryCameraSource. * * @returns * 0: Success. @@ -3334,7 +3335,7 @@ export abstract class IRtcEngine { /** * Enables/Disables the virtual background. * - * The virtual background feature enables the local user to replace their original background with a static image, dynamic video, blurred background, or portrait-background segmentation to achieve picture-in-picture effect. Once the virtual background feature is enabled, all users in the channel can see the custom background. Call this method before calling enableVideo or. + * The virtual background feature enables the local user to replace their original background with a static image, dynamic video, blurred background, or portrait-background segmentation to achieve picture-in-picture effect. Once the virtual background feature is enabled, all users in the channel can see the custom background. Call this method before calling enableVideo or startPreview. * This feature requires high performance devices. Agora recommends that you implement it on devices equipped with the following chips: * Snapdragon 700 series 750G and later * Snapdragon 800 series 835 and later @@ -4718,7 +4719,7 @@ export abstract class IRtcEngine { * * The SDK enables the low-quality video stream auto mode on the sender side by default (it does not actively sending low-quality video streams). The host identity receiver can initiate a low-quality video stream application at the receiving end by calling setRemoteVideoStreamType. After receiving the application, the sending end automatically switches to the low-quality video stream mode. * If you want to modify this behavior, you can call this method and modify the mode to DisableSimulcastStream (never send low-quality video streams) or EnableSimulcastStream (always send low-quality video streams). - * If you want to restore the default behavior after making changes, you can call this method again with mode set to AutoSimulcastStream. The difference and connection between this method and is as follows: + * If you want to restore the default behavior after making changes, you can call this method again with mode set to AutoSimulcastStream. The difference and connection between this method and enableDualStreamMode is as follows: * When calling this method and setting mode to DisableSimulcastStream, it has the same effect as calling and setting enabled to false. * When calling this method and setting mode to EnableSimulcastStream, it has the same effect as calling and setting enabled to true. * Both methods can be called before and after joining a channel. If both methods are used, the settings in the method called later takes precedence. @@ -5115,7 +5116,9 @@ export abstract class IRtcEngine { * @param extension The name of the extension. * @param key The key of the extension. * @param value The value of the extension key. - * @param type The type of the video source, see MediaSourceType. + * @param type Type of media source. See MediaSourceType. In this method, this parameter supports only the following two settings: + * The default value is UnknownMediaSource. + * If you want to use the second camera to capture video, set this parameter to SecondaryCameraSource. * * @returns * 0: Success. @@ -5433,7 +5436,7 @@ export abstract class IRtcEngine { /** * Sets the default audio playback route. * - * Most mobile phones have two audio routes: an earpiece at the top, and a speakerphone at the bottom. The earpiece plays at a lower volume, and the speakerphone at a higher volume. When setting the default audio route, you determine whether audio playback comes through the earpiece or speakerphone when no external audio device is connected. + * Ensure that you call this method before joining a channel. If you need to change the audio route after joining a channel, call setEnableSpeakerphone. Most mobile phones have two audio routes: an earpiece at the top, and a speakerphone at the bottom. The earpiece plays at a lower volume, and the speakerphone at a higher volume. When setting the default audio route, you determine whether audio playback comes through the earpiece or speakerphone when no external audio device is connected. * * @param defaultToSpeaker Whether to set the speakerphone as the default audio route: true : Set the speakerphone as the default audio route. false : Set the earpiece as the default audio route. * @@ -5740,8 +5743,7 @@ export abstract class IRtcEngine { /** * Starts pushing media streams to a CDN without transcoding. * - * Ensure that you enable the Media Push service before using this function. See Enable Media Push. - * Call this method after joining a channel. + * Call this method after joining a channel. * Only hosts in the LIVE_BROADCASTING profile can call this method. * If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. Agora recommends that you use the server-side Media Push function. You can call this method to push an audio or video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times. After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming. * @@ -5759,8 +5761,7 @@ export abstract class IRtcEngine { /** * Starts Media Push and sets the transcoding configuration. * - * Agora recommends that you use the server-side Media Push function. You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times. After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming. - * Ensure that you enable the Media Push service before using this function. See Enable Media Push. + * Agora recommends that you use the server-side Media Push function. You can call this method to push a live audio-and-video stream to the specified CDN address and set the transcoding configuration. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times. Under one Agora project, the maximum number of concurrent tasks to push media streams is 200 by default. If you need a higher quota, contact. After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming. * Call this method after joining a channel. * Only hosts in the LIVE_BROADCASTING profile can call this method. * If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. @@ -6215,7 +6216,7 @@ export abstract class IRtcEngine { * The local client: onLocalUserRegistered, onJoinChannelSuccess and onConnectionStateChanged callbacks. * The remote client: The onUserJoined callback, if the user is in the COMMUNICATION profile, and the onUserInfoUpdated callback if the user is a host in the LIVE_BROADCASTING profile. Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods. To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the ID of the user is set to the same parameter type. * - * @param token The token generated on your server for authentication. + * @param token The token generated on your server for authentication. If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. * @param channelId The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters: * All lowercase English letters: a to z. * All uppercase English letters: A to Z. @@ -6255,7 +6256,7 @@ export abstract class IRtcEngine { * The local client: onLocalUserRegistered, onJoinChannelSuccess and onConnectionStateChanged callbacks. * The remote client: The onUserJoined callback, if the user is in the COMMUNICATION profile, and the onUserInfoUpdated callback if the user is a host in the LIVE_BROADCASTING profile. Once a user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. To stop subscribing to a specified stream or all remote streams, call the corresponding mute methods. To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure all the other users use the user ID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the ID of the user is set to the same parameter type. * - * @param token The token generated on your server for authentication. + * @param token The token generated on your server for authentication. If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. * @param channelId The channel name. This parameter signifies the channel in which users engage in real-time audio and video interaction. Under the premise of the same App ID, users who fill in the same channel ID enter the same channel for audio and video interaction. The string length must be less than 64 bytes. Supported characters: * All lowercase English letters: a to z. * All uppercase English letters: A to Z. diff --git a/src/IAgoraRtcEngineEx.ts b/src/IAgoraRtcEngineEx.ts index 8c6362cc..c43ca5cc 100644 --- a/src/IAgoraRtcEngineEx.ts +++ b/src/IAgoraRtcEngineEx.ts @@ -52,7 +52,7 @@ export abstract class IRtcEngineEx extends IRtcEngine { * If you want to join the same channel from different devices, ensure that the user IDs are different for all devices. * Ensure that the app ID you use to generate the token is the same as the app ID used when creating the IRtcEngine instance. * - * @param token The token generated on your server for authentication. + * @param token The token generated on your server for authentication. If you need to join different channels at the same time or switch between channels, Agora recommends using a wildcard token so that you don't need to apply for a new token every time joining a channel. * @param connection The connection information. See RtcConnection. * @param options The channel media options. See ChannelMediaOptions. * @@ -78,7 +78,7 @@ export abstract class IRtcEngineEx extends IRtcEngine { * * This method lets the user leave the channel, for example, by hanging up or exiting the call. After calling joinChannelEx to join the channel, this method must be called to end the call before starting the next call. This method can be called whether or not a call is currently in progress. This method releases all resources related to the session. Calling this method does not necessarily mean that the user has left the channel. After you leave the channel, the SDK triggers the onLeaveChannel callback. After actually leaving the channel, the local user triggers the onLeaveChannel callback; after the user in the communication scenario and the host in the live streaming scenario leave the channel, the remote user triggers the onUserOffline callback. * If you call release immediately after calling this method, the SDK does not trigger the onLeaveChannel callback. - * Calling leaveChannel will leave the channels when calling joinChannel and joinChannelEx at the same time. + * If you want to leave the channels that you joined by calling joinChannel and joinChannelEx, call the leaveChannel method. * * @param connection The connection information. See RtcConnection. * @param options The options for leaving the channel. See LeaveChannelOptions. This parameter only supports the stopMicrophoneRecording member in the LeaveChannelOptions settings; setting other members does not take effect. @@ -500,7 +500,7 @@ export abstract class IRtcEngineEx extends IRtcEngine { /** * Creates a data stream. * - * Creates a data stream. Each user can create up to five data streams in a single channel. Compared with createDataStreamEx, this method does not support data reliability. If a data packet is not received five seconds after it was sent, the SDK directly discards the data. + * Creates a data stream. Each user can create up to five data streams in a single channel. * * @param config The configurations for the data stream. See DataStreamConfig. * @param connection The connection information. See RtcConnection. @@ -619,8 +619,7 @@ export abstract class IRtcEngineEx extends IRtcEngine { /** * Starts pushing media streams to a CDN without transcoding. * - * Ensure that you enable the Media Push service before using this function. See Enable Media Push. - * Call this method after joining a channel. + * Call this method after joining a channel. * Only hosts in the LIVE_BROADCASTING profile can call this method. * If you want to retry pushing streams after a failed push, make sure to call stopRtmpStream first, then call this method to retry pushing streams; otherwise, the SDK returns the same error code as the last failed push. Agora recommends that you use the server-side Media Push function. You can call this method to push an audio or video stream to the specified CDN address. This method can push media streams to only one CDN address at a time, so if you need to push streams to multiple addresses, call this method multiple times. After you call this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of the streaming. *