diff --git a/src/AgoraBase.ts b/src/AgoraBase.ts index 3ce16831..d741de7d 100644 --- a/src/AgoraBase.ts +++ b/src/AgoraBase.ts @@ -772,11 +772,11 @@ export enum OrientationMode { */ export enum DegradationPreference { /** - * @ignore + * 0: (Default) Automatic mode. The SDK will automatically select MaintainFramerate, MaintainBalanced or MaintainResolution based on the video scenario you set, in order to achieve the best overall quality of experience (QoE). */ MaintainAuto = -1, /** - * 0: (Default) Prefers to reduce the video frame rate while maintaining video resolution during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where video quality is prioritized. + * 0: Prefers to reduce the video frame rate while maintaining video resolution during video encoding under limited bandwidth. This degradation preference is suitable for scenarios where video quality is prioritized. Deprecated: This enumerator is deprecated. Use other enumerations instead. */ MaintainQuality = 0, /** @@ -1266,7 +1266,7 @@ export class EncodedVideoFrameInfo { */ export enum CompressionPreference { /** - * @ignore + * -1: (Default) Automatic mode. The SDK will automatically select PreferLowLatency or PreferQuality based on the video scenario you set to achieve the best user experience. */ PreferCompressionAuto = -1, /** @@ -1274,7 +1274,7 @@ export enum CompressionPreference { */ PreferLowLatency = 0, /** - * 1: (Default) High quality preference. The SDK compresses video frames while maintaining video quality. This preference is suitable for scenarios where video quality is prioritized. + * 1: High quality preference. The SDK compresses video frames while maintaining video quality. This preference is suitable for scenarios where video quality is prioritized. */ PreferQuality = 1, } @@ -2108,11 +2108,11 @@ export enum VideoApplicationScenarioType { */ ApplicationScenarioMeeting = 1, /** - * ApplicationScenario1v1 (2) is suitable for 1v1 video call scenarios. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. 2: 1v1 video call scenario. + * ApplicationScenario1v1 (2) This is applicable to the scenario. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. 2: 1v1 video call scenario. */ ApplicationScenario1v1 = 2, /** - * @ignore + * ApplicationScenarioLiveshow (3) This is applicable to the scenario. In this scenario, fast video rendering and high image quality are crucial. The SDK implements several performance optimizations, including automatically enabling accelerated audio and video frame rendering to minimize first-frame latency (no need to call enableInstantMediaRendering), and B-frame encoding to achieve better image quality and bandwidth efficiency. The SDK also provides enhanced video quality and smooth playback, even in poor network conditions or on lower-end devices. 3. Live show scenario. */ ApplicationScenarioLiveshow = 3, } @@ -3285,41 +3285,45 @@ export enum VideoTranscoderError { } /** - * @ignore + * The source of the audio streams that are mixed locally. */ export class MixedAudioStream { /** - * @ignore + * The type of the audio source. See AudioSourceType. */ sourceType?: AudioSourceType; /** - * @ignore + * The user ID of the remote user. Set this parameter if the source type of the locally mixed audio steams is AudioSourceRemoteUser. */ remoteUserUid?: number; /** - * @ignore + * 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 (89 characters in total): + * All lowercase English letters: a to z. + * All uppercase English letters: A to Z. + * All numeric characters: 0 to 9. + * "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", "," Set this parameter if the source type of the locally mixed audio streams is AudioSourceRemoteChannel or AudioSourceRemoteUser. */ channelId?: string; /** - * @ignore + * The audio track ID. Set this parameter to the custom audio track ID returned in createCustomAudioTrack. Set this parameter if the source type of the locally mixed audio steams is AudioSourceCustom. */ trackId?: number; } /** - * @ignore + * The configurations for mixing the lcoal audio. */ export class LocalAudioMixerConfiguration { /** - * @ignore + * The number of the audio streams that are mixed locally. */ streamCount?: number; /** - * @ignore + * The source of the audio streams that are mixed locally. See MixedAudioStream. */ audioInputStreams?: MixedAudioStream[]; /** - * @ignore + * Whether the mxied audio stream uses the timestamp of the audio frames captured by the local microphone. true : (Default) Yes. Set to this value if you want all locally captured audio streams synchronized. false : No. The SDK uses the timestamp of the audio frames at the time when they are mixed. */ syncWithLocalMic?: boolean; } @@ -3855,15 +3859,22 @@ export class FaceShapeBeautyOptions { } /** - * @ignore + * Filter effect options. */ export class FilterEffectOptions { /** - * @ignore + * The absolute path to the local cube map texture file, which can be used to customize the filter effect. The specified .cude file should strictly follow the Cube LUT Format Specification; otherwise, the filter options do not take effect. The following is a sample of the .cude file: + * LUT_3D_SIZE 32 + * 0.0039215689 0 0.0039215682 + * 0.0086021447 0.0037950677 0 + * ... + * 0.0728652592 0.0039215689 0 + * The identifier LUT_3D_SIZE on the first line of the cube map file represents the size of the three-dimensional lookup table. The LUT size for filter effect can only be set to 32. + * The SDK provides a built-in built_in_whiten_filter.cube file. You can pass the absolute path of this file to get the whitening filter effect. */ path?: string; /** - * @ignore + * The intensity of the filter effect, with a range value of [0.0,1.0], in which 0.0 represents no filter effect. The default value is 0.5. The higher the value, the stronger the filter effect. */ strength?: number; } @@ -3925,7 +3936,7 @@ export enum VideoDenoiserMode { } /** - * The video noise reduction level. + * Video noise reduction level. */ export enum VideoDenoiserLevel { /** @@ -3933,7 +3944,7 @@ export enum VideoDenoiserLevel { */ VideoDenoiserLevelHighQuality = 0, /** - * 1: Promotes reducing performance consumption during video noise reduction. prioritizes reducing performance consumption over video noise reduction quality. The performance consumption is lower, and the video noise reduction speed is faster. To avoid a noticeable shadowing effect (shadows trailing behind moving objects) in the processed video, Agora recommends that you use this settinging when the camera is fixed. + * 1: Promotes reducing performance consumption during video noise reduction. It prioritizes reducing performance consumption over video noise reduction quality. The performance consumption is lower, and the video noise reduction speed is faster. To avoid a noticeable shadowing effect (shadows trailing behind moving objects) in the processed video, Agora recommends that you use this setting when the camera is fixed. */ VideoDenoiserLevelFast = 1, } @@ -4089,7 +4100,7 @@ export class AudioTrackConfig { */ enableLocalPlayback?: boolean; /** - * @ignore + * Whether to enable audio processing module: true Enable the audio processing module to apply the Automatic Echo Cancellation (AEC), Automatic Noise Suppression (ANS), and Automatic Gain Control (AGC) effects. false : (Default) Do not enable the audio processing module. This parameter only takes effect on AudioTrackDirect in custom audio capturing. */ enableAudioProcessing?: boolean; } @@ -4784,7 +4795,7 @@ export class ChannelMediaRelayConfiguration { /** * The information of the target channel ChannelMediaInfo. It contains the following members: channelName : The name of the target channel. token : The token for joining the target channel. It is generated with the channelName and uid you set in destInfos. * 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. If the token of any target channel expires, the whole media relay stops; hence Agora recommends that you specify the same expiration time for the tokens of all the target channels. uid : The unique user ID to identify the relay stream in the target channel. The value ranges from 0 to (2 32 -1). To avoid user ID conflicts, this user ID must be different from any other user ID in the target channel. The default value is 0, which means the SDK generates a random user ID. + * If you have enabled the App Certificate, you must use the token generated with the channelName and uid. If the token of any target channel expires, the whole media relay stops; hence Agora recommends that you specify the same expiration time for the tokens of all the target channels. uid : The unique user ID to identify the relay stream in the target channel. The value ranges from 0 to (2 32 -1). To avoid user ID conflicts, this user ID must be different from any other user ID in the target channel. The default value is 0, which means the SDK generates a random UID. */ destInfos?: ChannelMediaInfo[]; /** diff --git a/src/AgoraMediaBase.ts b/src/AgoraMediaBase.ts index 19f4ae41..285097df 100644 --- a/src/AgoraMediaBase.ts +++ b/src/AgoraMediaBase.ts @@ -106,23 +106,23 @@ export enum VideoSourceType { } /** - * @ignore + * The audio source type. */ export enum AudioSourceType { /** - * @ignore + * 0: (Default) Microphone. */ AudioSourceMicrophone = 0, /** - * @ignore + * 1: Custom audio stream. */ AudioSourceCustom = 1, /** - * @ignore + * 2: Media player. */ AudioSourceMediaPlayer = 2, /** - * @ignore + * 3: System audio stream captured during screen sharing. */ AudioSourceLoopbackRecording = 3, /** @@ -130,15 +130,15 @@ export enum AudioSourceType { */ AudioSourceMixedStream = 4, /** - * @ignore + * 5: Audio stream from a specified remote user. */ AudioSourceRemoteUser = 5, /** - * @ignore + * 6: Mixed audio streams from all users in the current channel. */ AudioSourceRemoteChannel = 6, /** - * @ignore + * 100: An unknown audio source. */ AudioSourceUnknown = 100, } @@ -536,11 +536,11 @@ export enum VideoPixelFormat { */ export enum RenderModeType { /** - * 1: Hidden mode. Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). One dimension of the video may have clipped contents. + * 1: Hidden mode. The priority is to fill the window. Any excess video that does not match the window size will be cropped. */ RenderModeHidden = 1, /** - * 2: Fit mode. Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to disparity in the aspect ratio are filled with black. + * 2: Fit mode. The priority is to ensure that all video content is displayed. Any areas of the window that are not filled due to the mismatch between video size and window size will be filled with black. */ RenderModeFit = 2, /** @@ -876,27 +876,27 @@ export class Hdr10MetadataInfo { } /** - * @ignore + * The relative position of alphaBuffer and video frames. */ export enum AlphaStitchMode { /** - * @ignore + * 0: (Default) Only video frame, that is, alphaBuffer is not stitched with the video frame. */ NoAlphaStitch = 0, /** - * @ignore + * 1: alphaBuffer is above the video frame. */ AlphaStitchUp = 1, /** - * @ignore + * 2: alphaBuffer is below the video frame. */ AlphaStitchBelow = 2, /** - * @ignore + * 3: alphaBuffer is to the left of the video frame. */ AlphaStitchLeft = 3, /** - * @ignore + * 4: alphaBuffer is to the right of the video frame. */ AlphaStitchRight = 4, } @@ -1032,7 +1032,7 @@ export class ExternalVideoFrame { */ hdr10MetadataInfo?: Hdr10MetadataInfo; /** - * @ignore + * By default, the color space properties of video frames will apply the Full Range and BT.709 standard configurations. You can configure the settings according your needs for custom video capturing and rendering. */ colorSpace?: ColorSpace; } @@ -1130,7 +1130,7 @@ export class VideoFrame { */ hdr10MetadataInfo?: Hdr10MetadataInfo; /** - * @ignore + * By default, the color space properties of video frames will apply the Full Range and BT.709 standard configurations. You can configure the settings according your needs for custom video capturing and rendering. */ colorSpace?: ColorSpace; } @@ -1178,15 +1178,17 @@ export enum VideoModulePosition { } /** - * @ignore + * The snapshot configuration. */ export class SnapshotConfig { /** - * @ignore + * The local path (including filename extensions) of the snapshot. For example: + * iOS: /App Sandbox/Library/Caches/example.jpg + * Android: /storage/emulated/0/Android/data//files/example.jpg Ensure that the path you specify exists and is writable. */ filePath?: string; /** - * @ignore + * The position of the snapshot video frame in the video pipeline. See VideoModulePosition. */ position?: VideoModulePosition; } diff --git a/src/AgoraMediaPlayerTypes.ts b/src/AgoraMediaPlayerTypes.ts index acde0130..31a0c825 100644 --- a/src/AgoraMediaPlayerTypes.ts +++ b/src/AgoraMediaPlayerTypes.ts @@ -439,7 +439,7 @@ export class MediaSource { */ startPos?: number; /** - * Whether to enable autoplay once the media file is opened: true : (Default) Enables autoplay. false : Disables autoplay. If autoplay is disabled, you need to call the play method to play a media file after it is opened. + * Whether to enable autoplay once the media file is opened: true : (Default) Yes. false : No. If autoplay is disabled, you need to call the play method to play a media file after it is opened. */ autoPlay?: boolean; /** diff --git a/src/IAgoraMediaPlayer.ts b/src/IAgoraMediaPlayer.ts index 278c91f2..919d6850 100644 --- a/src/IAgoraMediaPlayer.ts +++ b/src/IAgoraMediaPlayer.ts @@ -152,8 +152,7 @@ export abstract class IMediaPlayer { * @param index The index of the media stream. This parameter must be less than the return value of getStreamCount. * * @returns - * If the call succeeds, returns the detailed information of the media stream. See PlayerStreamInfo. - * If the call fails, returns null. + * If the call succeeds, returns the detailed information of the media stream. See PlayerStreamInfo. null, if the method call fails. */ abstract getStreamInfo(index: number): PlayerStreamInfo; @@ -177,8 +176,8 @@ export abstract class IMediaPlayer { * * Call this method after calling open. * - * @param speed The playback speed. Agora recommends that you limit this value to a range between 50 and 400, which is defined as follows: - * 50: Half the original speed. + * @param speed The playback speed. Agora recommends that you set this to a value between 30 and 400, defined as follows: + * 30: 0.3 times the original speed. * 100: The original speed. * 400: 4 times the original speed. * @@ -493,7 +492,7 @@ export abstract class IMediaPlayer { * * You can call this method to switch the media resource to be played according to the current network status. For example: * When the network is poor, the media resource to be played is switched to a media resource address with a lower bitrate. - * When the network is good, the media resource to be played is switched to a media resource address with a higher bitrate. After calling this method, if you receive the PlayerEventSwitchComplete event in the onPlayerEvent callback, the switch is successful; If you receive the PlayerEventSwitchError event in the onPlayerEvent callback, the switch fails. + * When the network is good, the media resource to be played is switched to a media resource address with a higher bitrate. After calling this method, if you receive the onPlayerEvent callback report the PlayerEventSwitchComplete event, the switching is successful. If the switching fails, the SDK will automatically retry 3 times. If it still fails, you will receive the onPlayerEvent callback reporting the PlayerEventSwitchError event indicating an error occurred during media resource switching. * Ensure that you call this method after open. * To ensure normal playback, pay attention to the following when calling this method: * Do not call this method when playback is paused. @@ -501,14 +500,16 @@ export abstract class IMediaPlayer { * Before switching the media resource, make sure that the playback position does not exceed the total duration of the media resource to be switched. * * @param src The URL of the media resource. - * @param syncPts Whether to synchronize the playback position (ms) before and after the switch: true : Synchronize the playback position before and after the switch. false : (Default) Do not synchronize the playback position before and after the switch. Make sure to set this parameter as false if you need to play live streams, or the switch fails. If you need to play on-demand streams, you can set the value of this parameter according to your scenarios. + * @param syncPts Whether to synchronize the playback position (ms) before and after the switch: true : Synchronize the playback position before and after the switch. false : (Default) Do not synchronize the playback position before and after the switch. */ abstract switchSrc(src: string, syncPts?: boolean): number; /** * Preloads a media resource. * - * You can call this method to preload a media resource into the playlist. If you need to preload multiple media resources, you can call this method multiple times. After calling this method, if you receive the PlayerPreloadEventComplete event in the onPreloadEvent callback, the preload is successful; If you receive the PlayerPreloadEventError event in the onPreloadEvent callback, the preload fails. If the preload is successful and you want to play the media resource, call playPreloadedSrc; if you want to clear the playlist, call stop. Agora does not support preloading duplicate media resources to the playlist. However, you can preload the media resources that are being played to the playlist again. + * You can call this method to preload a media resource into the playlist. If you need to preload multiple media resources, you can call this method multiple times. After calling this method, if you receive the PlayerPreloadEventComplete event in the onPreloadEvent callback, the preload is successful; If you receive the PlayerPreloadEventError event in the onPreloadEvent callback, the preload fails. If the preload is successful and you want to play the media resource, call playPreloadedSrc; if you want to clear the playlist, call stop. + * Before calling this method, ensure that you have called open or openWithMediaSource to open the media resource successfully. + * Agora does not support preloading duplicate media resources to the playlist. However, you can preload the media resources that are being played to the playlist again. * * @param src The URL of the media resource. * @param startPos The starting position (ms) for playing after the media resource is preloaded to the playlist. When preloading a live stream, set this parameter to 0. diff --git a/src/IAgoraMediaPlayerSource.ts b/src/IAgoraMediaPlayerSource.ts index 00530af6..42176f4a 100644 --- a/src/IAgoraMediaPlayerSource.ts +++ b/src/IAgoraMediaPlayerSource.ts @@ -42,7 +42,7 @@ export interface IMediaPlayerSourceObserver { * * After calling the seek method, the SDK triggers the callback to report the results of the seek operation. * - * @param eventCode The player events. See MediaPlayerEvent. + * @param eventCode The player event. See MediaPlayerEvent. * @param elapsedTime The time (ms) when the event occurs. * @param message Information about the event. */ diff --git a/src/IAgoraRtcEngine.ts b/src/IAgoraRtcEngine.ts index 6d7e9968..9a4d336a 100644 --- a/src/IAgoraRtcEngine.ts +++ b/src/IAgoraRtcEngine.ts @@ -1185,7 +1185,7 @@ export class ChannelMediaOptions { */ publishTranscodedVideoTrack?: boolean; /** - * @ignore + * Whether to publish the mixed audio track: true : Publish the mixed audio track. false : Do not publish the mixed audio track. */ publishMixedAudioTrack?: boolean; /** @@ -2401,7 +2401,7 @@ export interface IRtcEngineEventHandler { /** * Video frame rendering event callback. * - * After calling the startMediaRenderingTracing method or joining the channel, the SDK triggers this callback to report the events of video frame rendering and the indicators during the rendering process. Developers can optimize the indicators to improve the efficiency of the first video frame rendering. + * After calling the startMediaRenderingTracing method or joining a channel, the SDK triggers this callback to report the events of video frame rendering and the indicators during the rendering process. Developers can optimize the indicators to improve the efficiency of the first video frame rendering. * * @param connection The connection information. See RtcConnection. * @param uid The user ID. @@ -3329,7 +3329,9 @@ export abstract class IRtcEngine { * * @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 Source type of the extension. See MediaSourceType. + * @param type The type of the media source to which the filter effect is applied. See MediaSourceType. In this method, this parameter supports only the following two settings: + * Use the default value PrimaryCameraSource if you use camera to capture local video. + * Set this parameter to CustomVideoSource if you use custom video source. * * @returns * 0: Success. @@ -3377,7 +3379,17 @@ export abstract class IRtcEngine { ): FaceShapeAreaOptions; /** - * @ignore + * Sets the filter effect options and specifies the media source. + * + * @param enabled Whether to enable the filter effect: true : Yes. false : (Default) No. + * @param options The filter effect options. See FilterEffectOptions. + * @param type The type of the media source to which the filter effect is applied. See MediaSourceType. In this method, this parameter supports only the following two settings: + * Use the default value PrimaryCameraSource if you use camera to capture local video. + * Set this parameter to CustomVideoSource if you use custom video source. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract setFilterEffectOptions( enabled: boolean, @@ -3388,17 +3400,13 @@ export abstract class IRtcEngine { /** * Sets low-light enhancement. * - * The low-light enhancement feature can adaptively adjust the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video. You can call this method to enable the color enhancement feature and set the options of the color enhancement effect. - * Call this method after calling enableVideo. - * Dark light enhancement has certain requirements for equipment performance. The low-light enhancement feature has certain performance requirements on devices. If your device overheats after you enable low-light enhancement, Agora recommends modifying the low-light enhancement options to a less performance-consuming level or disabling low-light enhancement entirely. - * 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 image enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + * You can call this method to enable the color enhancement feature and set the options of the color enhancement effect. * * @param enabled Whether to enable low-light enhancement: true : Enable low-light enhancement. false : (Default) Disable low-light enhancement. * @param options The low-light enhancement options. See LowlightEnhanceOptions. - * @param type The type of the video source. See MediaSourceType. + * @param type The type of the media source to which the filter effect is applied. See MediaSourceType. In this method, this parameter supports only the following two settings: + * Use the default value PrimaryCameraSource if you use camera to capture local video. + * Set this parameter to CustomVideoSource if you use custom video source. * * @returns * 0: Success. @@ -3413,17 +3421,13 @@ export abstract class IRtcEngine { /** * Sets video noise reduction. * - * Underlit environments and low-end video capture devices can cause video images to contain significant noise, which affects video quality. In real-time interactive scenarios, video noise also consumes bitstream resources and reduces encoding efficiency during encoding. You can call this method to enable the video noise reduction feature and set the options of the video noise reduction effect. - * Call this method after calling enableVideo. - * Video noise reduction has certain requirements for equipment performance. If your device overheats after you enable video noise reduction, Agora recommends modifying the video noise reduction options to a less performance-consuming level or disabling video noise reduction entirely. - * 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 image enhancement dynamic library libagora_clear_vision_extension.dll. If the dynamic library is deleted, the function cannot be enabled normally. + * You can call this method to enable the video noise reduction feature and set the options of the video noise reduction effect. If the noise reduction implemented by this method does not meet your needs, Agora recommends that you call the setBeautyEffectOptions method to enable the beauty and skin smoothing function to achieve better video noise reduction effects. The recommended BeautyOptions settings for intense noise reduction effect are as follows: lighteningContrastLevel LighteningContrastNormal lighteningLevel : 0.0 smoothnessLevel : 0.5 rednessLevel : 0.0 sharpnessLevel : 0.1 * * @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. - * @param type The type of the video source. See MediaSourceType. + * @param type The type of the media source to which the filter effect is applied. See MediaSourceType. In this method, this parameter supports only the following two settings: + * Use the default value PrimaryCameraSource if you use camera to capture local video. + * Set this parameter to CustomVideoSource if you use custom video source. * * @returns * 0: Success. @@ -3441,14 +3445,13 @@ export abstract class IRtcEngine { * The video images captured by the camera can have color distortion. The color enhancement feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid. You can call this method to enable the color enhancement feature and set the options of the color enhancement effect. * Call this method after calling enableVideo. * The color enhancement feature has certain performance requirements on devices. With color enhancement turned on, Agora recommends that you change the color enhancement level to one that consumes less performance or turn off color enhancement if your device is experiencing severe heat problems. - * 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 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. - * @param type The type of the video source. See MediaSourceType. + * @param type The type of the media source to which the filter effect is applied. See MediaSourceType. In this method, this parameter supports only the following two settings: + * Use the default value PrimaryCameraSource if you use camera to capture local video. + * Set this parameter to CustomVideoSource if you use custom video source. * * @returns * 0: Success. @@ -3484,9 +3487,9 @@ export abstract class IRtcEngine { * @param enabled Whether to enable virtual background: true : Enable virtual background. false : Disable virtual background. * @param backgroundSource The custom background. See VirtualBackgroundSource. To adapt the resolution of the custom background image to that of the video captured by the SDK, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted. * @param segproperty Processing properties for background images. See SegmentationProperty. - * @param type The type of the video source. See MediaSourceType. In this method, this parameter supports only the following two settings: - * The default value is PrimaryCameraSource. - * If you want to use the second camera to capture video, set this parameter to SecondaryCameraSource. + * @param type The type of the media source to which the filter effect is applied. See MediaSourceType. In this method, this parameter supports only the following two settings: + * Use the default value PrimaryCameraSource if you use camera to capture local video. + * Set this parameter to CustomVideoSource if you use custom video source. * * @returns * 0: Success. @@ -3528,7 +3531,7 @@ export abstract class IRtcEngine { * If someone subscribes to the low-quality stream, the SDK enables the low-quality stream and resets it to the SimulcastStreamConfig configuration used in the most recent calling of setDualStreamMode. If no configuration has been set by the user previously, the following values are used: * Resolution: 480 × 272 * Frame rate: 15 fps - * Bitrate: 500 Kbps ApplicationScenario1v1 (2) is suitable for 1v1 video call scenarios. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. + * Bitrate: 500 Kbps ApplicationScenario1v1 (2) This is applicable to the scenario. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. ApplicationScenarioLiveshow (3) This is applicable to the scenario. In this scenario, fast video rendering and high image quality are crucial. The SDK implements several performance optimizations, including automatically enabling accelerated audio and video frame rendering to minimize first-frame latency (no need to call enableInstantMediaRendering), and B-frame encoding to achieve better image quality and bandwidth efficiency. The SDK also provides enhanced video quality and smooth playback, even in poor network conditions or on lower-end devices. * * @returns * 0: Success. @@ -4798,7 +4801,14 @@ export abstract class IRtcEngine { ): number; /** - * @ignore + * Sets the maximum frame rate for rendering local video. + * + * @param sourceType The type of the video source. See VideoSourceType. + * @param targetFps The capture frame rate (fps) of the local video. Sopported values are: 1, 7, 10, 15, 24, 30, 60. Set this parameter to a value lower than the actual video frame rate; otherwise, the settings do not take effect. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract setLocalRenderTargetFps( sourceType: VideoSourceType, @@ -4806,7 +4816,13 @@ export abstract class IRtcEngine { ): number; /** - * @ignore + * Sets the maximum frame rate for rendering remote video. + * + * @param targetFps The capture frame rate (fps) of the local video. Sopported values are: 1, 7, 10, 15, 24, 30, 60. Set this parameter to a value lower than the actual video frame rate; otherwise, the settings do not take effect. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract setRemoteRenderTargetFps(targetFps: number): number; @@ -5381,7 +5397,7 @@ export abstract class IRtcEngine { /** * Checks whether the device camera supports face detection. * - * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateEncoding (2). + * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1). * This method is for Android and iOS only. * * @returns @@ -5392,7 +5408,7 @@ export abstract class IRtcEngine { /** * Checks whether the device supports camera flash. * - * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateEncoding (2). + * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1). * The app enables the front camera by default. If your front camera does not support flash, this method returns false. If you want to check whether the rear camera supports the flash function, call switchCamera before this method. * On iPads with system version 15, even if isCameraTorchSupported returns true, you might fail to successfully enable the flash by calling setCameraTorchOn due to system issues. * @@ -5404,7 +5420,7 @@ export abstract class IRtcEngine { /** * Check whether the device supports the manual focus function. * - * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateEncoding (2). + * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1). * * @returns * true : The device supports the manual focus function. false : The device does not support the manual focus function. @@ -5414,7 +5430,7 @@ export abstract class IRtcEngine { /** * Checks whether the device supports the face auto-focus function. * - * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateEncoding (2). + * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1). * * @returns * true : The device supports the face auto-focus function. false : The device does not support the face auto-focus function. @@ -5449,7 +5465,7 @@ export abstract class IRtcEngine { /** * Gets the maximum zoom ratio supported by the camera. * - * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateEncoding (2). + * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1). * * @returns * The maximum zoom factor. @@ -5503,7 +5519,7 @@ export abstract class IRtcEngine { /** * Checks whether the device supports manual exposure. * - * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateEncoding (2). + * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1). * * @returns * true : The device supports manual exposure. false : The device does not support manual exposure. @@ -5531,7 +5547,7 @@ export abstract class IRtcEngine { /** * Queries whether the current camera supports adjusting exposure value. * - * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateEncoding (2). + * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1). * Before calling setCameraExposureFactor, Agora recoomends that you call this method to query whether the current camera supports adjusting the exposure value. * By calling this method, you adjust the exposure value of the currently active camera, that is, the camera specified when calling setCameraCapturerConfiguration. * @@ -5559,7 +5575,7 @@ export abstract class IRtcEngine { /** * Checks whether the device supports auto exposure. * - * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateEncoding (2). + * This method must be called after the SDK triggers the onLocalVideoStateChanged callback and returns the local video state as LocalVideoStreamStateCapturing (1). * This method applies to iOS only. * * @returns @@ -5776,7 +5792,7 @@ export abstract class IRtcEngine { * * Call this method after starting screen sharing or window sharing. * - * @param captureParams The screen sharing encoding parameters. The default video resolution is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. The video properties of the screen sharing stream only need to be set through this parameter, and are unrelated to setVideoEncoderConfiguration. + * @param captureParams The screen sharing encoding parameters. The video properties of the screen sharing stream only need to be set through this parameter, and are unrelated to setVideoEncoderConfiguration. * * @returns * 0: Success. @@ -5795,7 +5811,7 @@ export abstract class IRtcEngine { * When you do not pass in a value, Agora bills you at 1280 × 720. * When you pass in a value, Agora bills you at that value. * - * @param captureParams The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters2. + * @param captureParams The screen sharing encoding parameters. See ScreenCaptureParameters2. * * @returns * 0: Success. @@ -5815,7 +5831,7 @@ export abstract class IRtcEngine { * This method is for Android and iOS only. * On the iOS platform, screen sharing is only available on iOS 12.0 and later. * - * @param captureParams The screen sharing encoding parameters. The default video resolution is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters2. + * @param captureParams The screen sharing encoding parameters. See ScreenCaptureParameters2. * * @returns * 0: Success. @@ -5848,7 +5864,15 @@ export abstract class IRtcEngine { }; /** - * @ignore + * Configures MediaProjection outside of the SDK to capture screen video streams. + * + * This method is for Android only. After successfully calling this method, the external MediaProjection you set will replace the MediaProjection requested by the SDK to capture the screen video stream. When the screen sharing is stopped or IRtcEngine is destroyed, the SDK will automatically release the MediaProjection. + * + * @param mediaProjection An object used to capture screen video streams. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract setExternalMediaProjection(mediaProjection: any): number; @@ -6024,19 +6048,46 @@ export abstract class IRtcEngine { abstract stopLocalVideoTranscoder(): number; /** - * @ignore + * Starts local audio mixing. + * + * This method supports merging multiple audio streams into one audio stream locally. For example, merging the audio streams captured from the local microphone, and that from the media player, the sound card, and the remote users into one audio stream, and then publish the merged audio stream to the channel. + * If you want to mix the locally captured audio streams, you can set publishMixedAudioTrack in ChannelMediaOptions to true, and then publish the mixed audio stream to the channel. + * If you want to mix the remote audio stream, ensure that the remote audio stream has been published in the channel and you have subcribed to the audio stream that you need to mix. + * + * @param config The configurations for mixing the lcoal audio. See LocalAudioMixerConfiguration. + * + * @returns + * 0: Success. + * < 0: Failure. + * -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method. */ abstract startLocalAudioMixer(config: LocalAudioMixerConfiguration): number; /** - * @ignore + * Updates the configurations for mixing audio streams locally. + * + * After calling startLocalAudioMixer, call this method if you want to update the local audio mixing configuration. + * + * @param config The configurations for mixing the lcoal audio. See LocalAudioMixerConfiguration. + * + * @returns + * 0: Success. + * < 0: Failure. + * -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method. */ abstract updateLocalAudioMixerConfiguration( config: LocalAudioMixerConfiguration ): number; /** - * @ignore + * Stops the local audio mixing. + * + * After calling startLocalAudioMixer, call this method if you want to stop the local audio mixing. + * + * @returns + * 0: Success. + * < 0: Failure. + * -7: The IRtcEngine object has not been initialized. You need to initialize the IRtcEngine object before calling this method. */ abstract stopLocalAudioMixer(): number; @@ -7021,7 +7072,16 @@ export abstract class IRtcEngine { abstract getNativeHandle(): number; /** - * @ignore + * Takes a screenshot of the video at the specified observation point. + * + * This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path. + * + * @param uid The user ID. Set uid as 0 if you want to take a snapshot of the local user's video. + * @param config The configuration of the snaptshot. See SnapshotConfig. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract takeSnapshotWithConfig(uid: number, config: SnapshotConfig): number; } @@ -7057,7 +7117,7 @@ export enum MediaDeviceStateType { */ MediaDeviceStateDisabled = 2, /** - * @ignore + * 3: The device is plugged in. */ MediaDeviceStatePluggedIn = 3, /** diff --git a/src/IAgoraRtcEngineEx.ts b/src/IAgoraRtcEngineEx.ts index cf410a4e..a35d2ce6 100644 --- a/src/IAgoraRtcEngineEx.ts +++ b/src/IAgoraRtcEngineEx.ts @@ -948,7 +948,17 @@ export abstract class IRtcEngineEx extends IRtcEngine { ): number; /** - * @ignore + * Gets a video screenshot of the specified observation point using the connection ID. + * + * This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path. + * + * @param connection The connection information. See RtcConnection. + * @param uid The user ID. Set uid as 0 if you want to take a snapshot of the local user's video. + * @param config The configuration of the snaptshot. See SnapshotConfig. + * + * @returns + * 0: Success. + * < 0: Failure. */ abstract takeSnapshotWithConfigEx( connection: RtcConnection,