From 35a80873fc32db5aa19084ed1358fe23f2a36542 Mon Sep 17 00:00:00 2001 From: Nero-Hu Date: Sat, 7 Oct 2023 02:39:59 +0000 Subject: [PATCH] [AUTO] Generate comments by iris-doc --- ts/Private/AgoraBase.ts | 18 +++++------ ts/Private/AgoraMediaBase.ts | 8 ++--- ts/Private/IAgoraMediaEngine.ts | 2 +- ts/Private/IAgoraMediaPlayer.ts | 15 ++------- ts/Private/IAgoraRtcEngine.ts | 54 ++++++++++++++++++++----------- ts/Private/IAgoraRtcEngineEx.ts | 12 ++++++- ts/Private/IAudioDeviceManager.ts | 13 ++++++-- 7 files changed, 73 insertions(+), 49 deletions(-) diff --git a/ts/Private/AgoraBase.ts b/ts/Private/AgoraBase.ts index fefe194b4..73f2e83c3 100644 --- a/ts/Private/AgoraBase.ts +++ b/ts/Private/AgoraBase.ts @@ -2047,11 +2047,11 @@ export enum LocalVideoStreamError { */ LocalVideoStreamErrorDeviceNotFound = 8, /** - * 9: (For macOS only) The video capture device currently in use is disconnected (such as being unplugged). + * 9: (macOS only) The video capture device currently in use is disconnected (such as being unplugged). */ LocalVideoStreamErrorDeviceDisconnected = 9, /** - * 10: (For macOS and Windows only) The SDK cannot find the video device in the video device list. Check whether the ID of the video device is valid. + * 10: (macOS and Windows only) The SDK cannot find the video device in the video device list. Check whether the ID of the video device is valid. */ LocalVideoStreamErrorDeviceInvalidId = 10, /** @@ -2059,18 +2059,18 @@ export enum LocalVideoStreamError { */ LocalVideoStreamErrorDeviceSystemPressure = 101, /** - * 11: (For macOS only) The shared window is minimized when you call startScreenCaptureByWindowId to share a window. The SDK cannot share a minimized window. You can cancel the minimization of this window at the application layer, for example by maximizing this window. + * 11: (macOS only) The shared window is minimized when you call startScreenCaptureByWindowId to share a window. The SDK cannot share a minimized window. You can cancel the minimization of this window at the application layer, for example by maximizing this window. */ LocalVideoStreamErrorScreenCaptureWindowMinimized = 11, /** - * 12: (For macOS and Windows only) The error code indicates that a window shared by the window ID has been closed or a full-screen window shared by the window ID has exited full-screen mode. After exiting full-screen mode, remote users cannot see the shared window. To prevent remote users from seeing a black screen, Agora recommends that you immediately stop screen sharing. Common scenarios for reporting this error code: + * 12: (macOS and Windows only) The error code indicates that a window shared by the window ID has been closed or a full-screen window shared by the window ID has exited full-screen mode. After exiting full-screen mode, remote users cannot see the shared window. To prevent remote users from seeing a black screen, Agora recommends that you immediately stop screen sharing. Common scenarios reporting this error code: * When the local user closes the shared window, the SDK reports this error code. * The local user shows some slides in full-screen mode first, and then shares the windows of the slides. After the user exits full-screen mode, the SDK reports this error code. * The local user watches a web video or reads a web document in full-screen mode first, and then shares the window of the web video or document. After the user exits full-screen mode, the SDK reports this error code. */ LocalVideoStreamErrorScreenCaptureWindowClosed = 12, /** - * 13: (For Windows only) The window being shared is overlapped by another window, so the overlapped area is blacked out by the SDK during window sharing. + * 13: (Windows only) The window being shared is overlapped by another window, so the overlapped area is blacked out by the SDK during window sharing. */ LocalVideoStreamErrorScreenCaptureWindowOccluded = 13, /** @@ -2776,7 +2776,7 @@ export class LiveTranscoding { */ height?: number; /** - * Bitrate of the output video stream for Media Push in Kbps. The default value is 400 Kbps. + * Bitrate of the output video stream for Media Push in Kbps. The default value is 400 Kbps. Set this member according to the table. If you set a bitrate beyond the proper range, the SDK automatically adapts it to a value within the range. */ videoBitrate?: number; /** @@ -3265,7 +3265,7 @@ export enum NetworkType { */ NetworkTypeMobile4g = 5, /** - * @ignore + * 6: The network type is mobile 5G. */ NetworkTypeMobile5g = 6, } @@ -3870,7 +3870,7 @@ export class ScreenCaptureParameters { */ bitrate?: number; /** - * Whether to capture the mouse in screen sharing: true : (Default) Capture the mouse. false : Do not capture the mouse. + * Whether to capture the mouse in screen sharing: true : (Default) Capture the mouse. false : Do not capture the mouse. Due to macOS system restrictions, setting this parameter to false is ineffective during screen sharing (it has no impact when sharing a window). */ captureMouseCursor?: boolean; /** @@ -3963,7 +3963,7 @@ export enum AudioEncodedFrameObserverPosition { */ export class AudioRecordingConfiguration { /** - * The absolute path (including the filename extensions) of the recording file. For example: C:\music\audio.mp4. Ensure that the directory for the log files exists and is writable. + * The absolute path (including the filename extensions) of the recording file. For example: C:\music\audio.aac. Ensure that the directory for the log files exists and is writable. */ filePath?: string; /** diff --git a/ts/Private/AgoraMediaBase.ts b/ts/Private/AgoraMediaBase.ts index 704e39e16..025c0a754 100644 --- a/ts/Private/AgoraMediaBase.ts +++ b/ts/Private/AgoraMediaBase.ts @@ -260,7 +260,7 @@ export enum ContentInspectType { */ ContentInspectInvalid = 0, /** - * 1: Video content moderation. SDK takes screenshots, inspects video content of the video stream in the channel, and uploads the screenshots and moderation results. + * @ignore */ ContentInspectModeration = 1, /** @@ -268,7 +268,7 @@ export enum ContentInspectType { */ ContentInspectSupervision = 2, /** - * @ignore + * 3: Video screenshot and upload via extensions from Agora Extensions Marketplace. SDK uses video moderation extensions from Agora Extensions Marketplace to take screenshots of the video stream in the channel and uploads them. */ ContentInspectImageModeration = 3, } @@ -414,7 +414,7 @@ export enum VideoPixelFormat { */ VideoPixelRgba = 4, /** - * 8: The format is NV12. + * @ignore */ VideoPixelNv12 = 8, /** @@ -588,7 +588,7 @@ export class ExternalVideoFrame { */ alphaBuffer?: Uint8Array; /** - * @ignore + * This parameter only applies to video data in Windows Texture format. It represents an index of an ID3D11Texture2D texture object used by the video frame in the ID3D11Texture2D array. */ texture_slice_index?: number; } diff --git a/ts/Private/IAgoraMediaEngine.ts b/ts/Private/IAgoraMediaEngine.ts index 1b4dba4b8..77a9d81be 100644 --- a/ts/Private/IAgoraMediaEngine.ts +++ b/ts/Private/IAgoraMediaEngine.ts @@ -286,7 +286,7 @@ export abstract class IMediaEngine { abstract unregisterVideoFrameObserver(observer: IVideoFrameObserver): number; /** - * Unregisters a receiver object for the encoded video image. + * Unregisters a receiver object for the encoded video frame. * * @param observer The video observer, reporting the reception of each video frame. See IVideoEncodedFrameObserver. * diff --git a/ts/Private/IAgoraMediaPlayer.ts b/ts/Private/IAgoraMediaPlayer.ts index 9435cc3fe..c418289e4 100644 --- a/ts/Private/IAgoraMediaPlayer.ts +++ b/ts/Private/IAgoraMediaPlayer.ts @@ -141,7 +141,7 @@ export abstract class IMediaPlayer { /** * Gets the number of the media streams in the media resource. * - * Call this method after calling open. + * Call this method after you call open and receive the onPlayerSourceStateChanged callback reporting the state PlayerStateOpenCompleted. * * @returns * The number of the media streams in the media resource if the method call succeeds. @@ -210,18 +210,7 @@ export abstract class IMediaPlayer { abstract setPlayerOptionInInt(key: string, value: number): number; /** - * Sets the private options for the media player. - * - * The media player supports setting private options by key and value. Under normal circumstances, you do not need to know the private option settings, and just use the default option settings. - * Ensure that you call this method before open. - * If you need to push streams with SEI into the CDN, call setPlayerOptionInString ("sei_data_with_uuid", 1); otherwise, the loss of SEI might occurs. - * - * @param key The key of the option. - * @param value The value of the key. - * - * @returns - * 0: Success. - * < 0: Failure. + * @ignore */ abstract setPlayerOptionInString(key: string, value: string): number; diff --git a/ts/Private/IAgoraRtcEngine.ts b/ts/Private/IAgoraRtcEngine.ts index 514ac6afe..fc3707a5c 100644 --- a/ts/Private/IAgoraRtcEngine.ts +++ b/ts/Private/IAgoraRtcEngine.ts @@ -1218,15 +1218,15 @@ export enum ProxyType { } /** - * @ignore + * The type of the advanced feature. */ export enum FeatureType { /** - * @ignore + * 1: Virtual background. */ VideoVirtualBackground = 1, /** - * @ignore + * 2: Image enhancement. */ VideoBeautyEffect = 2, } @@ -3272,7 +3272,8 @@ export abstract class IRtcEngine { * * Enables or disables image enhancement, and sets the options. * 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. + * This method relies on the image enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + * This feature has high requirements on device performance. When calling this method, the SDK automatically checks the capabilities of the current device. * * @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. @@ -3283,6 +3284,8 @@ export abstract class IRtcEngine { * @returns * 0: Success. * < 0: Failure. + * -4: The current device does not support this feature. Possible reasons include: + * The current device capabilities do not meet the requirements for image enhancement. Agora recommends you replace it with a high-performance device. */ abstract setBeautyEffectOptions( enabled: boolean, @@ -3299,7 +3302,7 @@ export abstract class IRtcEngine { * Both this method and setExtensionProperty can turn on low-light enhancement: * When you use the SDK to capture video, Agora recommends this method (this method only works for video captured by the SDK). * When you use an external video source to implement custom video capture, or send an external video source to the SDK, Agora recommends using setExtensionProperty. - * 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. + * This method relies on the image 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 low-light enhancement function: true : Enable low-light enhancement function. false : (Default) Disable low-light enhancement function. * @param options The low-light enhancement options. See LowlightEnhanceOptions. @@ -3324,7 +3327,7 @@ export abstract class IRtcEngine { * Both this method and setExtensionProperty can turn on video noise reduction function: * When you use the SDK to capture video, Agora recommends this method (this method only works for video captured by the SDK). * When you use an external video source to implement custom video capture, or send an external video source to the SDK, Agora recommends using setExtensionProperty. - * 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. + * This method relies on the image 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 video noise reduction: true : Enable video noise reduction. false : (Default) Disable video noise reduction. * @param options The video noise reduction options. See VideoDenoiserOptions. @@ -3349,7 +3352,7 @@ export abstract class IRtcEngine { * Both this method and setExtensionProperty can enable color enhancement: * When you use the SDK to capture video, Agora recommends this method (this method only works for video captured by the SDK). * When you use an external video source to implement custom video capture, or send an external video source to the SDK, Agora recommends using setExtensionProperty. - * 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. + * This method relies on the image 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 color enhancement: true Enable color enhancement. false : (Default) Disable color enhancement. * @param options The color enhancement options. See ColorEnhanceOptions. @@ -3369,7 +3372,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 startPreview. - * This feature requires high performance devices. Agora recommends that you implement it on devices equipped with the following chips: + * This feature has high requirements on device performance. When calling this method, the SDK automatically checks the capabilities of the current device. Agora recommends you use virtual background on devices with the following processors: * Devices with an i5 CPU and better * Agora recommends that you use this feature in scenarios that meet the following conditions: * A high-definition camera device is used, and the environment is uniformly lit. @@ -3386,9 +3389,7 @@ export abstract class IRtcEngine { * @returns * 0: Success. * < 0: Failure. - * -1: The custom background image does not exist. Check the value of source in VirtualBackgroundSource. - * -2: The color format of the custom background image is invalid. Check the value of color in VirtualBackgroundSource. - * -3: The device does not support virtual background. + * -4: The device capabilities do not meet the requirements for the virtual background feature. Agora recommends you try it on devices with higher performance. */ abstract enableVirtualBackground( enabled: boolean, @@ -3511,7 +3512,7 @@ export abstract class IRtcEngine { /** * Enables or disables the local audio capture. * - * The audio function is enabled by default when users joining a channel. This method disables or re-enables the local audio function to stop or restart local audio capturing. This method does not affect receiving or playing the remote audio streams, and enableLocalAudio (false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel. Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback, which reports LocalAudioStreamStateStopped (0) or LocalAudioStreamStateRecording (1). + * The audio function is enabled by default when users joining a channel. This method disables or re-enables the local audio function to stop or restart local audio capturing. This method does not affect receiving the remote audio streams, and enableLocalAudio (false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel. Once the local audio function is disabled or re-enabled, the SDK triggers the onLocalAudioStateChanged callback, which reports LocalAudioStreamStateStopped (0) or LocalAudioStreamStateRecording (1). * The difference between this method and muteLocalAudioStream are as follow: enableLocalAudio : Disables or re-enables the local audio capturing and processing. If you disable or re-enable local audio capturing using the enableLocalAudio method, the local user might hear a pause in the remote audio playback. muteLocalAudioStream : Sends or stops sending the local audio streams. * You can call this method either before or after joining a channel. Calling it before joining a channel only sets the device state, and it takes effect immediately after you join the channel. * @@ -3678,7 +3679,7 @@ export abstract class IRtcEngine { /** * Sets the default stream type of subscrption for remote video streams. * - * By default, the SDK enables the low-quality video stream auto mode on the sending end (it does not actively send the low-quality video stream). The host identity receiver can initiate a low-quality video stream application at the receiving end by calling this method (the call to this method by the audience receiver does not take effect). After receiving the application, the sending end automatically switches to the low-quality video stream mode. Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode (false), the receiver can choose to receive either the high-quality video stream or the low-quality video stream. The high-quality video stream has a higher resolution and bitrate, and the low-quality video stream has a lower resolution and bitrate. By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream. + * By default, the SDK enables the low-quality video stream auto mode on the sending end (it does not actively send the low-quality video stream). The host identity receiver can initiate a low-quality video stream application at the receiving end by calling this method (the call to this method by the audience receiver does not take effect). After receiving the application, the sending end automatically switches to the low-quality video stream mode. Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode (false), the receiver can choose to receive either the high-quality video stream or the low-video stream. The high-quality video stream has a higher resolution and bitrate, and the low-quality video stream has a lower resolution and bitrate. By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream. * Call this method before joining a channel. The SDK does not support changing the default subscribed video stream type after joining a channel. * If you call both this method and setRemoteVideoStreamType, the SDK applies the settings in the setRemoteVideoStreamType method. * @@ -4058,7 +4059,7 @@ export abstract class IRtcEngine { * Sets the channel mode of the current audio file. * * In a stereo music file, the left and right channels can store different audio data. According to your needs, you can set the channel mode to original mode, left channel mode, right channel mode, or mixed channel mode. For example, in the KTV scenario, the left channel of the music file stores the musical accompaniment, and the right channel stores the singing voice. If you only need to listen to the accompaniment, call this method to set the channel mode of the music file to left channel mode; if you need to listen to the accompaniment and the singing voice at the same time, call this method to set the channel mode to mixed channel mode. - * Call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AudioMixingStatePlaying) callback. + * You need to call this method after calling startAudioMixing and receiving the onAudioMixingStateChanged (AudioMixingStatePlaying) callback. * This method only applies to stereo audio files. * * @param mode The channel mode. See AudioMixingDualMonoMode. @@ -6425,11 +6426,10 @@ export abstract class IRtcEngine { /** * Enables or disables video screenshot and upload. * - * When video screenshot and upload function is enabled, the SDK takes screenshots and upload videos sent by local users based on the type and frequency of the module you set in ContentInspectConfig. After video screenshot and upload, the Agora server sends the callback notification to your app server in HTTPS requests and sends all screenshots to the third-party cloud storage service. Before calling this method, ensure that the video screenshot upload service has been activated. Before calling this method, ensure that Video content moderation service has been activated. - * This method relies on the video screenshot and upload dynamic library libagora_content_inspect_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + * When video screenshot and upload function is enabled, the SDK takes screenshots and uploads videos sent by local users based on the type and frequency of the module you set in ContentInspectConfig. After video screenshot and upload, the Agora server sends the callback notification to your app server in HTTPS requests and sends all screenshots to the third-party cloud storage service. Before calling this method, ensure that you have contacted to activate the video screenshot upload service. * * @param enabled Whether to enable video screenshot and upload : true : Enables video screenshot and upload. false : Disables video screenshot and upload. - * @param config Configuration of video screenshot and upload. See ContentInspectConfig. + * @param config Configuration of video screenshot and upload. See ContentInspectConfig. When the video moderation module is set to video moderation via Agora self-developed extension(ContentInspectSupervise ContentInspectImageModeration), the video screenshot and upload dynamic library libagora_content_inspect_extension.dll is required. Deleting this library disables the screenshot and upload feature. * * @returns * 0: Success. @@ -6458,7 +6458,16 @@ export abstract class IRtcEngine { ): number; /** - * @ignore + * Adjusts the volume of the custom audio track played locally. + * + * Ensure you have called the createCustomAudioTrack method to create a custom audio track before calling this method. If you want to change the volume of the audio to be played locally, you need to call this method again. + * + * @param trackId The audio track ID. Set this parameter to the custom audio track ID returned in createCustomAudioTrack. + * @param volume The volume of the audio source. The value can range from 0 to 100. 0 means mute; 100 means the original volume. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract adjustCustomAudioPlayoutVolume( trackId: number, @@ -6611,7 +6620,14 @@ export abstract class IRtcEngine { abstract getNtpWallTimeInMs(): number; /** - * @ignore + * Checks whether the device supports the specified advanced feature. + * + * Checks whether the capabilities of the current device meet the requirements for advanced features such as virtual background and image enhancement. + * + * @param type The type of the advanced feature, see FeatureType. + * + * @returns + * true : The current device supports the specified feature. false : The current device does not support the specified feature. */ abstract isFeatureAvailableOnDevice(type: FeatureType): boolean; diff --git a/ts/Private/IAgoraRtcEngineEx.ts b/ts/Private/IAgoraRtcEngineEx.ts index 2511b2c1f..4f6ff9552 100644 --- a/ts/Private/IAgoraRtcEngineEx.ts +++ b/ts/Private/IAgoraRtcEngineEx.ts @@ -918,7 +918,17 @@ export abstract class IRtcEngineEx extends IRtcEngine { ): number; /** - * @ignore + * Enables or disables video screenshot and upload. + * + * This method can take screenshots for multiple video streams and upload them. When video screenshot and upload function is enabled, the SDK takes screenshots and uploads videos sent by local users based on the type and frequency of the module you set in ContentInspectConfig. After video screenshot and upload, the Agora server sends the callback notification to your app server in HTTPS requests and sends all screenshots to the third-party cloud storage service. Before calling this method, ensure that you have contacted to activate the video screenshot upload service. + * + * @param enabled Whether to enable video screenshot and upload : true : Enables video screenshot and upload. false : Disables video screenshot and upload. + * @param config Configuration of video screenshot and upload. See ContentInspectConfig. When the video moderation module is set to video moderation via Agora self-developed extension(ContentInspectSupervise ContentInspectImageModeration), the video screenshot and upload dynamic library libagora_content_inspect_extension.dll is required. Deleting this library disables the screenshot and upload feature. + * @param connection The connection information. See RtcConnection. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract enableContentInspectEx( enabled: boolean, diff --git a/ts/Private/IAudioDeviceManager.ts b/ts/Private/IAudioDeviceManager.ts index 9d3de10bc..f62064280 100644 --- a/ts/Private/IAudioDeviceManager.ts +++ b/ts/Private/IAudioDeviceManager.ts @@ -146,12 +146,21 @@ export abstract class IAudioDeviceManager { abstract getLoopbackDevice(): string; /** - * @ignore + * Mutes the audio playback device. + * + * @param mute Whether to mute the audio playback device: true : Mute the audio playback device. false : Unmute the audio playback device. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract setPlaybackDeviceMute(mute: boolean): number; /** - * @ignore + * Retrieves whether the audio playback device is muted. + * + * @returns + * true : The audio playback device is muted. false : The audio playback device is unmuted. */ abstract getPlaybackDeviceMute(): boolean;