Video Enhancement

addOrUpdateVideoEffect

Adds or updates a video effect for the specified video effect node ID and template.

int addOrUpdateVideoEffect(int nodeId, String templateName);

Since: Available since v4.6.0.

Note: Priority rules:

The style makeup effect node takes precedence over the FILTER parameter.
To apply the FILTER parameter, you must first remove the style makeup effect node:

removeVideoEffect(`STYLE_MAKEUP`);
addOrUpdateVideoEffect(`FILTER`, "template name");

Parameters

nodeId: Unique identifier or combination of identifiers for the video effect node. See VIDEO_EFFECT_NODE_ID.
templateName: Name of the effect template. If set to null or an empty string, the SDK loads the default parameter configuration from the resource package.

Return Values

0: Success.
< 0: Failure.

createVideoEffectObject

Creates an IVideoEffectObject video effect object.

public abstract IVideoEffectObject createVideoEffectObject(String bundlePath, Constants.MediaSourceType sourceType);

Since: Available since v4.6.0.

Note: You must call enableVideo before calling this method. This method is applicable to Android 4.4 and above.

Parameters

bundlePath: The path to the video effect resource bundle.
sourceType: The media source type, such as PRIMARY_CAMERA_SOURCE. See MediaSourceType.

Return Values

The IVideoEffectObject object, if the method call succeeds.
An empty pointer , if the method call fails.

destroyVideoEffectObject

Destroys a video effect object.

public abstract int destroyVideoEffectObject(IVideoEffectObject videoEffectObject);

Since: Available since v4.6.0.

Note: You must call the enableVideo method before calling this method. This method is applicable to Android 4.4 and later.

Parameters

videoEffectObject: The video effect object to be destroyed. See IVideoEffectObject.

Return Values

0: Success.
< 0: Failure.

getFaceShapeAreaOptions [1/2]

Gets the current settings of the face beautification area.

public abstract FaceShapeAreaOptions getFaceShapeAreaOptions(int shapeArea, Constants.MediaSourceType sourceType);

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 calling enableVideo.

Parameters

shapeArea

Face beautification enhancement area.

FACE_SHAPE_AREA_NONE (-1): (Default) Invalid area, no beautification effect applied.
FACE_SHAPE_AREA_HEADSCALE (100): Head, used to create a smaller head effect. Adjustment range: [0, 100]. Larger values result in a smaller head. Default is 100.
FACE_SHAPE_AREA_FOREHEAD (101): Forehead, used to adjust the hairline height. Adjustment range: [-100, 100]. Positive values raise the hairline, negative values lower it. The larger the absolute value, the more obvious the effect. Default is 50.
FACE_SHAPE_AREA_FACECONTOUR (102): Face contour, used to slim the face. Adjustment range: [0, 100]. Larger values result in a slimmer face. Default is 10.
FACE_SHAPE_AREA_FACELENGTH (103): Face length, used to lengthen or shorten the face. Adjustment range: [-100, 100]. Positive values lengthen the face, negative values shorten it. The larger the absolute value, the more obvious the effect. Default is 0.
FACE_SHAPE_AREA_FACEWIDTH (104): Face width, used to narrow the face. Adjustment range: [0, 100]. Larger values result in a narrower face. Default is 10.
FACE_SHAPE_AREA_CHEEKBONE (105): Cheekbones, used to adjust cheekbone width. Adjustment range: [0, 100]. Larger values result in narrower cheekbones. Default is 43.
FACE_SHAPE_AREA_CHEEK (106): Cheeks, used to adjust cheek width. Adjustment range: [0, 100]. Larger values result in narrower cheeks. Default is 50.
FACE_SHAPE_AREA_CHIN (108): Chin, used to adjust chin length. Adjustment range: [-100, 100]. Positive values lengthen the chin, negative values shorten it. The larger the absolute value, the more obvious the effect. Default is -20.
FACE_SHAPE_AREA_EYESCALE (200): Eyes, used to enlarge the eyes. Adjustment range: [0, 100]. Larger values result in bigger eyes. Default is 50.
FACE_SHAPE_AREA_EYEDISTANCE (201): Eye distance adjustment. Range: [-100, 100]. Default is 0. The larger the absolute value, the more obvious the adjustment. Negative values indicate the opposite direction.
FACE_SHAPE_AREA_EYEPOSITION (202): Eye position adjustment. Range: [-100, 100]. Default is 0. The larger the absolute value, the more obvious the adjustment. Negative values indicate the opposite direction.
FACE_SHAPE_AREA_LOWEREYELID (203): Lower eyelid adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_EYEPUPILS (204): Pupil size adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_EYEINNERCORNER (205): Inner eye corner adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_EYEOUTERCORNER (206): Outer eye corner adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_NOSELENGTH (300): Nose length, used to lengthen or shorten the nose. Adjustment range: [-100, 100]. Positive values lengthen the nose, negative values shorten it. The larger the absolute value, the more obvious the effect. Default is -10.
FACE_SHAPE_AREA_NOSEWIDTH (301): Nose width, used to slim the nose. Adjustment range: [-100, 100]. Positive values widen the nose, negative values narrow it. The larger the absolute value, the more obvious the effect. Default is 72.
FACE_SHAPE_AREA_NOSEWING (302): Nostril adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_NOSEROOT (303): Nose root adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_NOSEBRIDGE (304): Nose bridge adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_NOSETIP (305): Nose tip adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_NOSEGENERAL (306): Overall nose adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_MOUTHSCALE (400): Mouth, used to enlarge the mouth. Adjustment range: [0, 100]. Larger values result in a bigger mouth. Default is 50.
FACE_SHAPE_AREA_MOUTHPOSITION (401): Mouth position adjustment. Range: [-100, 100]. Default is 0. The larger the absolute value, the more obvious the adjustment. Negative values indicate the opposite direction.
FACE_SHAPE_AREA_MOUTHSMILE (402): Mouth corner smile adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_MOUTHLIP (403): Lip shape adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.
FACE_SHAPE_AREA_EYEBROWPOSITION (500): Eyebrow position adjustment. Range: [-100, 100]. Default is 0. The larger the absolute value, the more obvious the adjustment. Negative values indicate the opposite direction.
FACE_SHAPE_AREA_EYEBROWTHICKNESS (501): Eyebrow thickness adjustment. Range: [0, 100]. Default is 0. Larger values result in more noticeable adjustments.

sourceType

The media source type to which the filter effect is applied. See MediaSourceType.

Note: This parameter only supports the following two settings:

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

The FaceShapeAreaOptions instance, if the method call succeeds.
null, if the method call fails.

getFaceShapeAreaOptions [2/2]

Retrieves the current settings options for the beauty effect area.

public abstract FaceShapeAreaOptions getFaceShapeAreaOptions(int shapeArea);

You can call this method to get the current settings options for the beauty effect and refresh the UI menu based on the returned result.

Scenario

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

Timing

Call this method after calling enableVideo.

Parameters

shapeArea

Beauty enhancement area.

FACE_SHAPE_AREA_NONE (-1): (Default) Invalid area, no beauty effect applied.
FACE_SHAPE_AREA_HEADSCALE (100): Head, used to create a smaller head effect. Adjustment range: [0, 100]. The larger the value, the smaller the head. Default: 100.
FACE_SHAPE_AREA_FOREHEAD (101): Forehead, used to adjust hairline height. Adjustment range: [-100, 100]. Positive values raise the hairline, negative values lower it. The larger the absolute value, the more obvious the effect. Default: 50.
FACE_SHAPE_AREA_FACECONTOUR (102): Face contour, used to slim the face. Adjustment range: [0, 100]. The larger the value, the more obvious the slimming effect. Default: 10.
FACE_SHAPE_AREA_FACELENGTH (103): Face length, used to elongate the face. Adjustment range: [-100, 100]. Positive values elongate, negative values shorten. Larger absolute values yield more obvious effects. Default: 0.
FACE_SHAPE_AREA_FACEWIDTH (104): Face width, used to narrow the face. Adjustment range: [0, 100]. The larger the value, the narrower the face. Default: 10.
FACE_SHAPE_AREA_CHEEKBONE (105): Cheekbones, used to adjust cheekbone width. Adjustment range: [0, 100]. The larger the value, the narrower the cheekbones. Default: 43.
FACE_SHAPE_AREA_CHEEK (106): Cheeks, used to adjust cheek width. Adjustment range: [0, 100]. The larger the value, the narrower the cheeks. Default: 50.
FACE_SHAPE_AREA_CHIN (108): Chin, used to adjust chin length. Adjustment range: [-100, 100]. Positive values elongate, negative values shorten. Larger absolute values yield more obvious effects. Default: -20.
FACE_SHAPE_AREA_EYESCALE (200): Eyes, used to enlarge eyes. Adjustment range: [0, 100]. The larger the value, the bigger the eyes. Default: 50.
FACE_SHAPE_AREA_EYEDISTANCE (201): Eye distance adjustment. Adjustment range: [-100, 100]. Negative values indicate opposite direction. Larger absolute values yield more obvious effects. Default: 0.
FACE_SHAPE_AREA_EYEPOSITION (202): Eye position adjustment. Adjustment range: [-100, 100]. Negative values indicate opposite direction. Larger absolute values yield more obvious effects. Default: 0.
FACE_SHAPE_AREA_LOWEREYELID (203): Lower eyelid adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_EYEPUPILS (204): Pupil size adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_EYEINNERCORNER (205): Inner eye corner adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_EYEOUTERCORNER (206): Outer eye corner adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_NOSELENGTH (300): Nose length, used to elongate the nose. Adjustment range: [-100, 100]. Positive values elongate, negative values shorten. Larger absolute values yield more obvious effects. Default: -10.
FACE_SHAPE_AREA_NOSEWIDTH (301): Nose width, used to slim the nose. Adjustment range: [-100, 100]. Positive values widen, negative values narrow. Larger absolute values yield more obvious effects. Default: 72.
FACE_SHAPE_AREA_NOSEWING (302): Nostril adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_NOSEROOT (303): Nose root adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_NOSEBRIDGE (304): Nose bridge adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_NOSETIP (305): Nose tip adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_NOSEGENERAL (306): Overall nose adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_MOUTHSCALE (400): Mouth, used to enlarge the mouth. Adjustment range: [0, 100]. The larger the value, the bigger the mouth. Default: 50.
FACE_SHAPE_AREA_MOUTHPOSITION (401): Mouth position adjustment. Adjustment range: [-100, 100]. Negative values indicate opposite direction. Larger absolute values yield more obvious effects. Default: 0.
FACE_SHAPE_AREA_MOUTHSMILE (402): Smile adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_MOUTHLIP (403): Lip shape adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.
FACE_SHAPE_AREA_EYEBROWPOSITION (500): Eyebrow position adjustment. Adjustment range: [-100, 100]. Negative values indicate opposite direction. Larger absolute values yield more obvious effects. Default: 0.
FACE_SHAPE_AREA_EYEBROWTHICKNESS (501): Eyebrow thickness adjustment. Adjustment range: [0, 100]. The larger the value, the more obvious the effect. Default: 0.

Return Values

If the method call succeeds, returns a FaceShapeAreaOptions instance.
If the method call fails, returns null.

getFaceShapeBeautyOptions [1/2]

Gets the current beauty effect settings.

public abstract FaceShapeBeautyOptions getFaceShapeBeautyOptions(Constants.MediaSourceType sourceType);

You can call this method when the user opens the beauty style and intensity menu in the app, and refresh the menu and update the UI based on the returned result.

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 calling enableVideo.

Parameters

sourceType

The media source type. See MediaSourceType.

Note: This parameter only supports the following two settings:

If you use the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
If you use a custom video source, set it to CUSTOM_VIDEO_SOURCE.

Return Values

If the method call succeeds, returns a FaceShapeBeautyOptions instance. If the method call fails, returns null.

getFaceShapeBeautyOptions [2/2]

Gets the current beauty effect settings.

public abstract FaceShapeBeautyOptions getFaceShapeBeautyOptions();

Scenario

When the user opens the beauty style and intensity menu in the app, you can call this method to get the current beauty effect settings, then refresh the menu in the UI and update the UI accordingly.

Timing

Call this method after calling enableVideo.

Return Values

If the method call succeeds, returns a FaceShapeBeautyOptions instance.
If the method call fails, returns null.

getOptions

Retrieves the currently configured watermark display options.

public WatermarkOptions getOptions()

Since: Available since v4.6.0.

Return Values

The WatermarkOptions object, if the method call succeeds.

getVideoEffectBoolParam

Retrieves the boolean parameter from the video effect.

boolean getVideoEffectBoolParam(String option, String key);

Since: Available since v4.6.0.

Parameters

option: Identifier of the parameter category.
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 float value of the specified parameter in the video effect.

float getVideoEffectFloatParam(String option, String key);

Since: Available since v4.6.0.

Parameters

option: Identifier of the parameter category.
key: Key name of the parameter.

Return Values

If the method call succeeds, returns the current float value.
If the method call fails, returns 0.0f.

getVideoEffectIntParam

Retrieves the integer parameter from the video effect.

int getVideoEffectIntParam(String option, String key);

Since: Available since v4.6.0.

Parameters

option: Identifier of the parameter category.
key: Key name of the parameter.

Return Values

If the method call succeeds, returns the current parameter value.
If the method call fails, returns 0.

performVideoEffectAction

Performs an action on the specified video effect node.

int performVideoEffectAction(int nodeId, VIDEO_EFFECT_ACTION actionId);

Since: Available since v4.6.0.

Parameters

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

Return Values

0: Success.
< 0: Failure.

removeVideoEffect

Removes the video effect node for the specified node ID.

int removeVideoEffect(int nodeId);

Since: Available since v4.6.0.

Parameters

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

Return Values

0: Success.
< 0: Failure.

setBeautyEffectOptions [1/2]

Enables the beauty effect and sets its options.

public abstract int setBeautyEffectOptions(boolean enabled, BeautyOptions options);

Since: Available since v2.4.0.

Note:

This method is only supported on Android 5.0 or later.
This method depends on the dynamic library libagora_clear_vision_extension.so. If this library is deleted, the feature cannot be enabled.
This feature requires high device performance. When you call this method, the SDK automatically detects the device capabilities.

Timing

Call this method after calling 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.

Return Values

0: Success.
< 0: Failure.
- -4: The current device does not support this feature. Possible reasons include:
  - The device capabilities do not meet the requirements of the beauty effect. Agora recommends switching to a high-performance device.
  - The device runs an Android version lower than 5.0, which does not support this feature. Agora recommends upgrading the device or the OS.

setBeautyEffectOptions [2/2]

Sets beauty effect options and specifies the media source.

public abstract int setBeautyEffectOptions(boolean enabled, BeautyOptions options, Constants.MediaSourceType sourceType);

Since: Available since v2.4.0.

This method enables or disables the beauty effect and sets the related options. It is similar to the setBeautyEffectOptions [1/2] method, but allows you to specify the media source type to apply the beauty effect to.

Timing

Call this method after calling 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.

sourceType

The media source type to apply the beauty effect to. See MediaSourceType.

Note: This parameter only supports the following settings:

The default is PRIMARY_CAMERA_SOURCE.
If you use 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 performance does not meet the requirements of the beauty effect. Agora recommends switching to a high-performance device.
  - The device runs an Android version lower than 5.0, which does not support this feature. Agora recommends upgrading the device or the OS.

setColorEnhanceOptions [1/2]

Enables the color enhancement feature.

public abstract int setColorEnhanceOptions(boolean enabled, ColorEnhanceOptions options);

Since: Available since v3.6.2.

The video image captured by the camera may suffer from color distortion. This feature intelligently adjusts parameters such as saturation and contrast to enhance the richness and fidelity of the video colors, making the image more vivid.

Note:

Call this method after calling enableVideo.
The color enhancement feature requires certain device performance. If the device overheats seriously 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.so. If the library is deleted, the feature cannot be enabled properly.

Parameters

enabled

Whether to enable color enhancement:

true: Enable color enhancement.
false: (Default) Disable color enhancement.

options

Color enhancement options. See ColorEnhanceOptions.

Return Values

0: Success.
< 0: Failure.

setColorEnhanceOptions [2/2]

Sets color enhancement options and specifies the media source.

public abstract int setColorEnhanceOptions(boolean enabled, ColorEnhanceOptions options, Constants.MediaSourceType sourceType);

Since: Available since v3.6.2.

The video image captured by the camera may suffer from color distortion. The color enhancement feature intelligently adjusts parameters such as saturation and contrast to enhance the richness and fidelity of the video colors, making the image more vivid. This method has the same functionality as setColorEnhanceOptions [1/2], but allows you to specify the media source type to apply the color enhancement.

Note:

Call this method after calling enableVideo.
The color enhancement feature requires certain device performance. If the device overheats seriously 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.so. If the library is deleted, the feature cannot be enabled properly.

Parameters

enabled

Whether to enable color enhancement:

true: Enable color enhancement.
false: (Default) Disable color enhancement.

options

Color enhancement options. See ColorEnhanceOptions.

sourceType

The media source type to apply the filter effect. See MediaSourceType.

Note: This parameter only supports the following two settings:

The default value is PRIMARY_CAMERA_SOURCE.
If using a custom video source, set this parameter to CUSTOM_VIDEO_SOURCE.

Return Values

0: Success.
< 0: Failure.

setFaceShapeAreaOptions [1/2]

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

public abstract int setFaceShapeAreaOptions(FaceShapeAreaOptions options, Constants.MediaSourceType sourceType);

If the preset beauty effects set by the setFaceShapeBeautyOptions method do not meet expectations, you can use this method to set beauty area options and fine-tune each part of the face for more refined beauty effects. This method is similar to setFaceShapeAreaOptions [2/2], but it supports specifying the media source to which the beauty effect is applied.

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.so. If the library is deleted, the feature cannot be enabled.
This feature requires high device performance. The SDK will automatically detect the device capability when this method is called.

Timing

Call this method after calling setFaceShapeBeautyOptions.

Parameters

options

Face enhancement area. See FaceShapeAreaOptions.

sourceType

Media source type for applying filter effects. See MediaSourceType.

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.
- -4: The current device does not support this feature. Possible reasons include:
  - The device does not meet the requirements for beauty effects. It is recommended to use a high-performance device.
  - The device version is lower than Android 4.4 and does not support this feature. It is recommended to upgrade the OS or change the device.

setFaceShapeAreaOptions [2/2]

Sets the face area options for beauty enhancement.

public abstract int setFaceShapeAreaOptions(FaceShapeAreaOptions options);

You can call this method to set the face area options and fine-tune each part of the face for more refined beauty effects.

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.so. If the library is deleted, the feature cannot be enabled.
This feature requires high device performance. The SDK will automatically detect the device capability when this method is called.

Timing

Call this method after calling the setFaceShapeBeautyOptions method.

Parameters

options: Face enhancement area options. See FaceShapeAreaOptions.

Return Values

0: Success.
< 0: Failure.
- -4: The current device does not support this feature. Possible reasons include:
  - The device does not meet the requirements for beauty effects. It is recommended to use a high-performance device.
  - The device version is lower than Android 4.4 and does not support this feature. It is recommended to upgrade the OS or change the device.

setFaceShapeBeautyOptions [1/2]

Sets face shaping effects and specifies the media source to apply.

public abstract int setFaceShapeBeautyOptions(boolean enabled, FaceShapeBeautyOptions options, Constants.MediaSourceType sourceType);

This method allows you to adjust multiple facial areas at once using preset parameters to achieve subtle face shaping effects such as slimming the face, enlarging the eyes, and slimming the nose. It also supports adjusting the overall intensity of the face shaping effect. This method is similar to setFaceShapeBeautyOptions [2/2], with the difference that it supports specifying the media source to apply the face shaping effects.

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.so. If the library is deleted, the feature cannot be used properly.
This feature has high performance requirements for the device. When calling this method, the SDK automatically detects the capabilities of the current device.

Timing

Call this method after calling enableVideo.

Parameters

enabled

Whether to enable face shaping effects:

true: Enable face shaping effects.
false: (Default) Disable face shaping effects.

options

Face shaping style options. See FaceShapeBeautyOptions.

sourceType

The type of media source to which the face shaping effects are applied. See MediaSourceType.

Note: This parameter only supports the following two settings:

When using the camera to capture local video, use the default value PRIMARY_CAMERA_SOURCE.
When using a custom video source, set it to CUSTOM_VIDEO_SOURCE.

Return Values

0: The method call succeeds.
< 0: The method call fails.
- -4: The current device does not support this feature. Possible reasons include:
  - The current device does not meet the performance requirements for beauty effects. It is recommended to use a high-performance device.
  - The current device system version is lower than Android 4.4. It is recommended to change the device or upgrade the operating system.

setFaceShapeBeautyOptions [2/2]

Sets face shaping options.

public abstract int setFaceShapeBeautyOptions(boolean enabled, FaceShapeBeautyOptions options);

Note:

This method is only supported on Android 4.4 or later.
This method depends on the dynamic library libagora_clear_vision_extension.so. If this library is deleted, the feature cannot be enabled.
This feature requires high device performance. When you call this method, the SDK automatically detects the device capabilities.

Timing

Call this method after calling enableVideo.

Parameters

enabled

Whether to enable the face shaping effect:

true: Enable the face shaping effect.
false: (Default) Disable the face shaping effect.

options

Face shaping style options. See FaceShapeBeautyOptions.

Return Values

0: Success.
< 0: Failure.
- -4: The current device does not support this feature. Possible reasons include:
  - The device capabilities do not meet the requirements of the beauty effect. Agora recommends switching to a high-performance device.
  - The device runs an Android version lower than 4.4, which does not support this feature. Agora recommends upgrading the device or the OS.

setFilterEffectOptions [1/2]

Sets filter effect parameters and specifies the media source.

public abstract int setFilterEffectOptions(boolean enabled, FilterEffectOptions options, Constants.MediaSourceType sourceType);

Since: Available since v4.4.1.

This method allows you to set filter effect parameters and specify the media source to which the filter effect is applied.

Note:

This method is only applicable to Android 5.0 or later.
This method depends on the beauty effect dynamic library libagora_clear_vision_extension.so. If the library is deleted, this feature cannot be enabled properly.
This feature requires high device performance. When calling this method, the SDK automatically detects the device capabilities.

Timing

Call this method after calling enableVideo.

Parameters

enabled

Whether to enable the filter effect:

true: Enable.
false: (Default) Disable.

options

Filter effect parameters. See FilterEffectOptions.

sourceType

The media source type to which the filter effect is applied. See MediaSourceType.

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 to CUSTOM_VIDEO_SOURCE.

Return Values

0: Success.
< 0: Failure.

setFilterEffectOptions [2/2]

Sets filter effect options.

public abstract int setFilterEffectOptions(boolean enabled, FilterEffectOptions options);

Since: Added since v4.4.1.

Note: This method is only applicable to Android 5.0 or later. It depends on the beauty effect dynamic library libagora_clear_vision_extension.so. If this library is removed, the feature cannot be enabled properly. This feature requires high device performance. When calling this method, the SDK automatically detects the device's capabilities.

Timing

Call this method after calling enableVideo.

Parameters

enabled

Whether to enable filter effects:

true: Enable.
false: (Default) Disable.

options

Filter effect options. See FilterEffectOptions.

Return Values

0: Success.
< 0: Failure.

setLowlightEnhanceOptions [1/2]

Enables low-light enhancement.

public abstract int setLowlightEnhanceOptions(boolean enabled, LowLightEnhanceOptions options);

Since: Available since v3.6.2.

Note:

This method depends on the beauty effect dynamic library libagora_clear_vision_extension.so. If the library is deleted, the feature cannot be enabled properly.
Low-light enhancement requires certain device performance. If the device overheats after enabling it, Agora recommends setting the low-light enhancement option to a lower performance level or disabling the feature.
If you want to prioritize image 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 must 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 must 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 low-light enhancement:

true: Enable.
false: (Default) Disable.

options

Low-light enhancement options. See LowLightEnhanceOptions.

Return Values

0: Success.
< 0: Failure.

setLowlightEnhanceOptions [2/2]

Sets low-light enhancement options and specifies the media source.

public abstract int setLowlightEnhanceOptions(boolean enabled, LowLightEnhanceOptions options, Constants.MediaSourceType sourceType);

Since: Available since v3.6.2.

This method sets low-light enhancement options and allows you to specify the media source type to which low-light enhancement is applied.

Note:

This method depends on the beauty effect dynamic library libagora_clear_vision_extension.so. If the library is deleted, the feature cannot be enabled properly.
Video denoising requires certain device performance. If the device overheats after enabling video denoising, Agora recommends setting the video denoising option to a lower performance level or disabling it completely.

Scenario

Applicable to scenarios where dark environments or low-end video capture devices cause excessive image noise. In real-time interaction, noise consumes bitrate and reduces encoding efficiency.

Timing

Call this method after calling enableVideo.

Parameters

enabled

Whether to enable low-light enhancement:

true: Enable.
false: (Default) Disable.

options

Low-light enhancement options. See LowLightEnhanceOptions.

sourceType

The media source type to which the filter effect is applied. See MediaSourceType.

Note: This parameter only supports the following two settings:

Default is PRIMARY_CAMERA_SOURCE.
If you use a custom video source, set this parameter to CUSTOM_VIDEO_SOURCE.

Return Values

0: Success.
< 0: Failure.

setVideoDenoiserOptions [1/2]

Sets the video denoising feature and its options.

public abstract int setVideoDenoiserOptions(boolean enabled, VideoDenoiserOptions options);

Since: Available since v3.6.2.

You can call this method to configure the options for the video denoising effect.

Note:

This method depends on the beauty effect dynamic library libagora_clear_vision_extension.so. If the library is removed, the feature cannot be enabled properly.
Video denoising requires certain device performance. If enabling it causes device overheating, Agora recommends lowering the performance level of the denoising option or disabling the video denoising feature.
If the denoising effect provided by this method does not meet your needs, Agora recommends calling the setBeautyEffectOptions method to enable beauty and smoothing effects for better denoising. Recommended BeautyOptions settings for strong denoising effect:
- 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.

Return Values

0: Success.
< 0: Failure.

setVideoDenoiserOptions [2/2]

Sets video denoising and specifies the media source.

public abstract int setVideoDenoiserOptions(boolean enabled, VideoDenoiserOptions options, Constants.MediaSourceType sourceType);

Since: Available since v3.6.2.

You can call this method to enable the video denoising feature and configure its options. This method is similar to setVideoDenoiserOptions [1/2], but allows you to specify the type of media source to apply denoising to.

Note:

This method depends on the beauty effect dynamic library libagora_clear_vision_extension.so. If the library is removed, the feature cannot be enabled properly.
Video denoising requires certain device performance. If enabling it causes device overheating, Agora recommends setting the video denoising option to a lower performance level or disabling the feature entirely.
If the denoising effect provided by this method does not meet your needs, Agora recommends calling the setBeautyEffectOptions method to enable beauty and smoothing effects for better video denoising. Recommended BeautyOptions settings for strong denoising effect:
- lighteningContrastLevel: LIGHTENING_CONTRAST_NORMAL.
- lighteningLevel: 0.0.
- smoothnessLevel: 0.5.
- rednessLevel: 0.0.
- sharpnessLevel: 0.1.

Scenario

Low-light environments and low-end video capture devices may cause noticeable noise in video images, affecting video quality. In real-time interactive scenarios, video noise also consumes bitrate resources and reduces encoding efficiency.

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.

sourceType

The type of media source to apply the filter effect to. See MediaSourceType.

Note: In this method, this parameter only supports the following two settings:

Default is PRIMARY_CAMERA_SOURCE.
If you use 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.

int setVideoEffectBoolParam(String option, String key, boolean value);

Since: Available since v4.6.0.

Parameters

option

Identifier of the parameter category.

key

Key name of the parameter.

value

Boolean value to set:

true: Enable.
false: Disable.

Return Values

0: Success.
< 0: Failure.

setVideoEffectFloatParam

Sets a float parameter for the video effect.

int setVideoEffectFloatParam(String option, String key, float value);

Since: Available since v4.6.0.

Parameters

option: Identifier of the parameter category.
key: Key name of the parameter.
value: Float value of the parameter to set.

Return Values

0: Success.
< 0: Failure.

setVideoEffectIntParam

Sets an integer parameter for the video effect.

int setVideoEffectIntParam(String option, String key, int value);

Since: Available since v4.6.0.

Parameters

option: Identifier of the parameter category.
key: Key name of the parameter.
value: Integer value to set.

Return Values

0: Success.
< 0: Failure.