Video Enhancement

addOrUpdateVideoEffect

Adds or updates the effect of the specified video effect node and template.

virtual int addOrUpdateVideoEffect(uint32_t nodeId, const char* templateName) = 0;
Since
Available since v4.6.0.
Note: Priority rules:
  • The VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP node takes precedence over the VIDEO_EFFECT_NODE_ID::FILTER parameter.
  • To apply the VIDEO_EFFECT_NODE_ID::FILTER parameter, you must first remove the VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP node:
removeVideoEffect(VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP);
addOrUpdateVideoEffect(VIDEO_EFFECT_NODE_ID::FILTER, "template name");

Parameters

nodeId
Unique identifier or combination of identifiers for the video effect node. See VIDEO_EFFECT_NODE_ID. Example:
  • Single effect: VIDEO_EFFECT_NODE_ID::BEAUTY
  • Combined effect: VIDEO_EFFECT_NODE_ID::BEAUTY | VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP
templateName
Name of the effect template. If set to NULL or an empty string, the SDK loads the default configuration from the resource package.

Return Values

  • 0: Success.
  • < 0: Failure.

createVideoEffectObject

Creates an IVideoEffectObject video effect object.

virtual agora_refptr<IVideoEffectObject> createVideoEffectObject(const char* bundlePath, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
Since
Available since v4.6.0.

Parameters

bundlePath
The path to the video effect resource bundle.
type
The media source type. See MEDIA_SOURCE_TYPE.

Return Values

destroyVideoEffectObject

Destroys a video effect object.

virtual int destroyVideoEffectObject(agora_refptr<IVideoEffectObject> videoEffectObject) = 0;
Since
Available since v4.6.0.

Parameters

videoEffectObject
The video effect object to destroy. See IVideoEffectObject.

Return Values

  • 0: Success.
  • < 0: Failure.

getFaceShapeAreaOptions

Gets beauty area options.

virtual int getFaceShapeAreaOptions(agora::rtc::FaceShapeAreaOptions::FACE_SHAPE_AREA shapeArea, FaceShapeAreaOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

Scenario

When users open the beauty area and shaping intensity menu in the app, you can call this method to get the current beauty effect options and update the UI accordingly.

Timing

Call this method after enableVideo.

Parameters

shapeArea
Facial enhancement area. See FACE_SHAPE_AREA.
options
Output parameter representing options for the facial enhancement area. See FaceShapeAreaOptions.
type
The media source type. See MEDIA_SOURCE_TYPE.
Note: In this method, this parameter only supports the following two settings:
  • If using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set this parameter to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.

getFaceShapeBeautyOptions

Gets beauty options.

virtual int getFaceShapeBeautyOptions(FaceShapeBeautyOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

Scenario

When users open the beauty style and intensity menu in the app, you can call this method to get the current beauty options and update the UI accordingly.

Timing

Call this method after enableVideo.

Parameters

options
Output parameter representing beauty style options. See FaceShapeBeautyOptions.
type
The media source type for applying filter effects. See MEDIA_SOURCE_TYPE.
Note: In this method, this parameter only supports the following two settings:
  • If using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set this parameter to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.

getVideoEffectBoolParam

Retrieves a boolean parameter from the video effect.

virtual bool getVideoEffectBoolParam(const char* option, const char* key) = 0;
Since
Available since v4.6.0.

Parameters

option
Category of the parameter option.
key
Key name of the parameter.

Return Values

  • true: The parameter is enabled.
  • false: The parameter is not enabled or does not exist.

getVideoEffectFloatParam

Retrieves the value of a specified float type parameter from the video effect.

virtual float getVideoEffectFloatParam(const char* option, const char* key) = 0;
Since
Available since v4.6.0.

Parameters

option
Category of the parameter option.
key
Key name of the parameter.

Return Values

  • If the parameter exists, returns the corresponding float value.
  • If the parameter does not exist or an error occurs, returns 0.0f.

getVideoEffectIntParam

Retrieves an integer type parameter from the video effect.

virtual int getVideoEffectIntParam(const char* option, const char* key) = 0;
Since
Available since v4.6.0.

Parameters

option
Category of the parameter option.
key
Key name of the parameter.

Return Values

  • If the parameter exists, returns the corresponding integer value.
  • If the parameter does not exist or an error occurs, returns 0.

performVideoEffectAction

Performs an action on the specified video effect node.

virtual int performVideoEffectAction(uint32_t nodeId, VIDEO_EFFECT_ACTION actionId) = 0;
Since
Available since v4.6.0.

Parameters

nodeId
Unique identifier of the video effect node.
actionId
Action to perform. See VIDEO_EFFECT_ACTION.

Return Values

  • 0: Success.
  • < 0: Failure.

removeVideoEffect

Removes the video effect with the specified node ID.

virtual int removeVideoEffect(uint32_t nodeId) = 0;
Since
Available since v4.6.0.

Parameters

nodeId
Unique identifier of the video effect node to be removed. See VIDEO_EFFECT_NODE_ID.

Return Values

  • 0: Success.
  • < 0: Failure.

setBeautyEffectOptions

Sets beauty effect options.

virtual int setBeautyEffectOptions(bool enabled, const BeautyOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
Note:
  • This method depends on the beauty effect dynamic library libagora_clear_vision_extension.dll. If the library is deleted, this feature cannot be enabled.
  • This feature requires high device performance. When calling this method, the SDK automatically detects the device's performance capability.

Timing

Call this method after enableVideo or startPreview.

Parameters

enabled
Whether to enable the beauty effect:
  • true: Enable the beauty effect.
  • false: (Default) Disable the beauty effect.
options
Beauty effect options. See BeautyOptions.
type
The media source type to apply the filter effect to. See MEDIA_SOURCE_TYPE.
  • If using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -4: The current device does not support this feature. Possible reasons include:
      • The current device performance does not meet the requirements for beauty effects. It is recommended to use a high-performance device.

setColorEnhanceOptions

Sets video color enhancement effects.

virtual int setColorEnhanceOptions(bool enabled, const ColorEnhanceOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
Since
Available since v4.0.0.

The video image captured by the camera may suffer from color distortion. The color enhancement feature can intelligently adjust video characteristics such as saturation and contrast to enhance color richness and fidelity, making the video more vivid.

Note:
  • Call this method after calling enableVideo.
  • The color enhancement feature requires certain device performance. If the device overheats significantly after enabling this feature, Agora recommends lowering the color enhancement level to reduce performance consumption or disabling the feature.
  • This method depends on the beauty effect dynamic library libagora_clear_vision_extension.dll. If this dynamic library is deleted, the feature cannot be enabled properly.

Parameters

enabled
Whether to enable the color enhancement feature:
  • true: Enable color enhancement.
  • false: (Default) Disable color enhancement.
options
Color enhancement options. See ColorEnhanceOptions.
type
The media source type to apply the filter effect to. See MEDIA_SOURCE_TYPE.
  • When using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • When using a custom video source, set to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.

setFaceShapeAreaOptions

Sets beauty effect options for facial areas and specifies the media source.

virtual int setFaceShapeAreaOptions(const FaceShapeAreaOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

If the preset beauty effect via setFaceShapeBeautyOptions does not meet your expectations, you can use this method to set beauty options for specific facial areas and fine-tune each part to achieve more refined results.

Note:
  • This method is only supported on Android 4.4 or later.
  • This method depends on the beauty effect dynamic library libagora_clear_vision_extension.dll. If the library is deleted, the feature cannot be enabled.
  • This feature requires high device performance. The SDK automatically detects device capabilities when this method is called.

Timing

Call this method after setFaceShapeBeautyOptions.

Parameters

options
Facial enhancement areas. See FaceShapeAreaOptions.
type
The media source type. See MEDIA_SOURCE_TYPE.
Note: This parameter only supports the following two settings:
  • If using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set this parameter to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -4: The current device does not support this feature. Possible reasons include:
      • The device does not meet the performance requirements for beauty effects. Agora recommends using a high-performance device.
      • The device runs Android version lower than 4.4, which is not supported. Agora recommends changing the device or upgrading the OS.

setFaceShapeBeautyOptions

Sets face shaping options and specifies the media source.

virtual int setFaceShapeBeautyOptions(bool enabled, const FaceShapeBeautyOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

You can call this method to adjust multiple facial features at once using preset parameters, achieving effects such as face slimming, eye enlargement, and nose slimming, and also adjust the overall intensity of the face shaping effect.

Note: This method is only applicable to Android 4.4 or later. This method depends on the beauty effect dynamic library libagora_clear_vision_extension.dll. If the library is deleted, this feature cannot be enabled. This feature requires high device performance. When calling this method, the SDK automatically detects the device's capability.

Timing

Call this method after calling enableVideo.

Parameters

enabled
Whether to enable face shaping effect:
  • true: Enable face shaping.
  • false: (Default) Disable face shaping.
options
Face shaping style options. See FaceShapeBeautyOptions.
type
The media source type to apply the filter effect to. See MEDIA_SOURCE_TYPE. This parameter only supports the following two settings:
  • If using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set this parameter to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -4: The current device does not support this feature. Possible reasons include:
      • The current device does not meet the beauty effect requirements. Agora recommends using a high-performance device.
      • The device version is lower than Android 4.4 and does not support this feature. Agora recommends changing the device or upgrading the OS.

setFilterEffectOptions

Sets filter effect options and specifies the media source.

virtual int setFilterEffectOptions(bool enabled, const FilterEffectOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
Since
Available since v4.4.1.
Note: This method depends on the beauty effect dynamic library libagora_clear_vision_extension.dll. If the library is deleted, this feature cannot be enabled properly. This feature requires high device performance. When this method is called, the SDK automatically detects the device's performance capability.

Timing

Call this method after calling enableVideo.

Parameters

enabled
Whether to enable the filter effect:
  • true: Enable.
  • false: (Default) Disable.
options
Filter effect options. See FilterEffectOptions.
type
The media source type to apply the filter effect to. See MEDIA_SOURCE_TYPE.
  • If using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.

setLowlightEnhanceOptions

Sets the low-light enhancement feature.

virtual int setLowlightEnhanceOptions(bool enabled, const LowlightEnhanceOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
Since
Available since v4.0.0.

You can call this method to enable the low-light enhancement feature and configure its parameters.

Note:
  • This method depends on the beauty effect dynamic library libagora_clear_vision_extension.dll. If the library is deleted, this feature cannot be enabled properly.
  • Low-light enhancement requires certain device performance. If overheating occurs after enabling it, Agora recommends setting a lower performance level or disabling the feature.
  • If you want to prioritize video quality when using low-light enhancement (LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY), you need to call setVideoDenoiserOptions to enable video denoising. The corresponding settings are:
    • When low-light enhancement is set to auto mode (LOW_LIGHT_ENHANCE_AUTO), video denoising should be set to high quality (VIDEO_DENOISER_LEVEL_HIGH_QUALITY) and auto mode (VIDEO_DENOISER_AUTO).
    • When low-light enhancement is set to manual mode (LOW_LIGHT_ENHANCE_MANUAL), video denoising should be set to high quality (VIDEO_DENOISER_LEVEL_HIGH_QUALITY) and manual mode (VIDEO_DENOISER_MANUAL).

Scenario

The low-light enhancement feature adaptively adjusts the brightness of video captured in low-light or uneven lighting conditions such as backlight, cloudy, or dark environments, to restore or highlight image details and improve the overall visual quality of the video.

Timing

Call this method after calling enableVideo.

Parameters

enabled
Whether to enable the low-light enhancement feature:
  • true: Enable.
  • false: (Default) Disable.
options
Low-light enhancement options. See LowlightEnhanceOptions.
type
The media source type to apply the filter effect to. See MEDIA_SOURCE_TYPE.
Note: This method only supports the following settings for this parameter:
  • If using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.

setVideoDenoiserOptions

Enables video denoising.

virtual int setVideoDenoiserOptions(bool enabled, const VideoDenoiserOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
Since
Available since v4.0.0.
Note:
  • This method depends on the beauty effect dynamic library libagora_clear_vision_extension.dll. If this library is deleted, the feature cannot be enabled properly.
  • Video denoising has certain performance requirements. If your device overheats after enabling video denoising, Agora recommends setting the denoising option to a lower performance consumption level or disabling it entirely.
  • If the denoising effect provided by this method does not meet your needs, Agora recommends calling setBeautyEffectOptions to enable beauty and smoothing effects for better video denoising. Recommended BeautyOptions settings for strong denoising:
    • lighteningContrastLevel: LIGHTENING_CONTRAST_NORMAL.
    • lighteningLevel: 0.0.
    • smoothnessLevel: 0.5.
    • rednessLevel: 0.0.
    • sharpnessLevel: 0.1.

Scenario

In low-light environments or when using low-end video capture devices, video images may exhibit noticeable noise, affecting video quality. In real-time interaction scenarios, video noise also consumes bitrate resources and reduces encoding efficiency. This method is applicable to multi-channel scenarios.

Timing

Call this method after calling enableVideo.

Parameters

enabled
Whether to enable video denoising:
  • true: Enable video denoising.
  • false: (Default) Disable video denoising.
options
Video denoising options. See VideoDenoiserOptions.
type
Media source type. See MEDIA_SOURCE_TYPE.
Note: In this method, only the following two settings are supported:
  • If using a camera to capture local video, use the default PRIMARY_CAMERA_SOURCE.
  • If using a custom video source, set this parameter to CUSTOM_VIDEO_SOURCE.

Return Values

  • 0: Success.
  • < 0: Failure.

setVideoEffectBoolParam

Sets a boolean parameter for the video effect.

virtual int setVideoEffectBoolParam(const char* option, const char* key, bool param) = 0;
Since
Available since v4.6.0.

Parameters

option
Category of the parameter option.
key
Key name of the parameter.
param
Boolean value to set:
  • true: Enable the option.
  • false: Disable the option.

Return Values

  • 0: Success.
  • < 0: Failure.

setVideoEffectFloatParam

Sets a float parameter for the video effect.

virtual int setVideoEffectFloatParam(const char* option, const char* key, float param) = 0;
Since
Available since v4.6.0.

Parameters

option
Category of the parameter option.
key
Key name of the parameter.
param
Float value to set.

Return Values

  • 0: Success.
  • < 0: Failure.

setVideoEffectIntParam

setVideoEffectIntParam: Sets an integer parameter for the video effect.

virtual int setVideoEffectIntParam(const char* option, const char* key, int param) = 0;
Since
Available since v4.6.0.

Parameters

option
Category of the parameter option.
key
Key name of the parameter.
param
Integer value to set.

Return Values

  • 0: Success.
  • < 0: Failure.