视频增强

addOrUpdateVideoEffect

添加或更新指定视频特效节点和模板的特效。

C++
virtual int addOrUpdateVideoEffect(uint32_t nodeId, const char* templateName) = 0;

自从

自 v4.6.0 版本新增。

信息

优先级规则：

VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP 节点优先于 VIDEO_EFFECT_NODE_ID::FILTER 参数。
若要应用 VIDEO_EFFECT_NODE_ID::FILTER 参数，必须先移除 VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP 节点：

removeVideoEffect(VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP);
addOrUpdateVideoEffect(VIDEO_EFFECT_NODE_ID::FILTER, "template name");

参数

nodeId

视频特效节点的唯一标识符或标识符组合。详见 VIDEO_EFFECT_NODE_ID。示例：

单一特效：VIDEO_EFFECT_NODE_ID::BEAUTY
组合特效：VIDEO_EFFECT_NODE_ID::BEAUTY | VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP

templateName

特效模板名称。如果设置为 NULL 或空字符串，SDK 会从资源包中加载默认配置。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IVideoEffectObject

createVideoEffectObject

创建一个 IVideoEffectObject 视频特效对象。

C++
virtual agora_refptr<IVideoEffectObject> createVideoEffectObject(const char* bundlePath, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

自从

自 v4.6.0 版本新增。

参数

bundlePath: 视频特效资源包的路径。
type: 媒体源类型，详见 MEDIA_SOURCE_TYPE。

返回值

方法调用成功，返回 IVideoEffectObject 对象指针，详见 IVideoEffectObject。
方法调用失败，返回 NULL。

所属接口类

IRtcEngine

destroyVideoEffectObject

销毁视频特效对象。

C++
virtual int destroyVideoEffectObject(agora_refptr<IVideoEffectObject> videoEffectObject) = 0;

自从

自 v4.6.0 版本新增。

参数

videoEffectObject: 要销毁的视频特效对象。详见 IVideoEffectObject。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

getFaceShapeAreaOptions

获取美型区域选项。

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

适用场景

当用户在应用中打开美型区域和塑形强度菜单时，可以调用该方法获取当前的美颜特效选项，然后根据结果刷新用户界面中的菜单并更新 UI。

调用时机

在调用 enableVideo 方法之后调用该方法。

参数

shapeArea

美型增强区域，详见 FACE_SHAPE_AREA。

options

输出参数，表示美型增强区域的选项，详见 FaceShapeAreaOptions。

type

媒体源类型，详见 MEDIA_SOURCE_TYPE。

信息

在该方法中，该参数仅支持以下两种设置：

如果使用摄像头采集本地视频，使用默认值 PRIMARY_CAMERA_SOURCE。
如果使用自定义视频源，将该参数设置为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

getFaceShapeBeautyOptions

获取美型选项。

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

适用场景

当用户在应用中打开美型风格和风格强度菜单时，可以调用该方法获取当前的美型选项，然后根据结果刷新用户界面中的菜单，并更新 UI。

调用时机

在调用 enableVideo 后调用该方法。

参数

options

输出参数，表示美型风格选项。详见 FaceShapeBeautyOptions。

type

应用滤镜特效的媒体源类型。详见 MEDIA_SOURCE_TYPE。

信息

在该方法中，该参数仅支持以下两种设置：

如果使用摄像头采集本地视频，使用默认值 PRIMARY_CAMERA_SOURCE。
如果使用自定义视频源，将该参数设置为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

getVideoEffectBoolParam

获取视频特效中的布尔参数。

C++
virtual bool getVideoEffectBoolParam(const char* option, const char* key) = 0;

自从

自 v4.6.0 版本新增。

参数

option: 参数所属的选项类别。
key: 参数的键名。

返回值

true：参数已启用。
false：参数未启用或不存在。

所属接口类

IVideoEffectObject

getVideoEffectFloatParam

获取视频特效中指定 float 类型参数的值。

C++
virtual float getVideoEffectFloatParam(const char* option, const char* key) = 0;

自从

自 v4.6.0 版本新增。

参数

option: 参数所属选项的类别。
key: 参数的键名。

返回值

如果参数存在，返回对应的 float 值。
如果参数不存在或发生错误，返回 0.0f。

所属接口类

IVideoEffectObject

getVideoEffectIntParam

获取视频特效中的整数类型参数。

C++
virtual int getVideoEffectIntParam(const char* option, const char* key) = 0;

自从

自 v4.6.0 版本新增。

参数

option: 参数选项的类别。
key: 参数的键名。

返回值

如果参数存在，返回对应的整数值。
如果参数不存在或发生错误，返回 0。

所属接口类

IVideoEffectObject

performVideoEffectAction

对指定的视频特效节点执行操作。

C++
virtual int performVideoEffectAction(uint32_t nodeId, VIDEO_EFFECT_ACTION actionId) = 0;

自从

自 v4.6.0 版本新增。

参数

nodeId: 视频特效节点的唯一标识符。
actionId: 要执行的操作，详见 VIDEO_EFFECT_ACTION。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IVideoEffectObject

removeVideoEffect

移除指定节点 ID 的视频特效。

C++
virtual int removeVideoEffect(uint32_t nodeId) = 0;

自从

自 v4.6.0 版本新增。

参数

nodeId: 要移除的视频特效节点的唯一标识符，详见 VIDEO_EFFECT_NODE_ID。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IVideoEffectObject

setBeautyEffectOptions

设置美颜特效选项。

C++
virtual int setBeautyEffectOptions(bool enabled, const BeautyOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

信息

该方法依赖美颜特效动态库 libagora_clear_vision_extension.dll。如果该动态库被删除，将无法正常启用该功能。
该功能对设备性能要求较高。调用该方法时，SDK 会自动检测当前设备的性能能力。

调用时机

在调用 enableVideo 或 startPreview 之后调用该方法。

参数

enabled

是否启用美颜特效功能：

true：启用美颜特效功能。
false：（默认）禁用美颜特效功能。

options

美颜特效选项。详见 BeautyOptions。

type

应用滤镜效果的媒体源类型。详见 MEDIA_SOURCE_TYPE。

如果使用摄像头采集本地视频，使用默认值 PRIMARY_CAMERA_SOURCE。
如果使用自定义视频源，设置为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -4：当前设备不支持该功能。可能原因包括：
  - 当前设备性能不满足美颜特效的要求。建议更换为高性能设备。

所属接口类

IRtcEngine

setColorEnhanceOptions

设置视频色彩增强效果。

C++
virtual int setColorEnhanceOptions(bool enabled, const ColorEnhanceOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

自从

自 v4.0.0 版本新增。

摄像头采集的视频图像可能存在色彩失真。色彩增强功能可智能调整视频的饱和度和对比度等特性，从而增强视频的色彩丰富度和还原度，使画面更加生动。

信息

请在调用 enableVideo 方法后调用此方法。
色彩增强功能对设备性能有一定要求。开启该功能后，如设备出现严重发热，声网建议你降低色彩增强等级以减少性能消耗，或关闭该功能。
此方法依赖美颜特效动态库 libagora_clear_vision_extension.dll。若该动态库被删除，将无法正常启用该功能。

参数

enabled

是否开启色彩增强功能：

true：开启色彩增强。
false：（默认）关闭色彩增强。

options

色彩增强选项。详见 ColorEnhanceOptions。

type

应用滤镜效果的媒体源类型。详见 MEDIA_SOURCE_TYPE。

使用摄像头采集本地视频时，使用默认值 PRIMARY_CAMERA_SOURCE。
使用自定义视频源时，设置为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

setFaceShapeAreaOptions

设置面部区域的美颜特效选项并指定媒体源。

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

如果通过 setFaceShapeBeautyOptions 实现的预设美颜特效无法满足预期效果，你可以使用该方法设置美颜区域选项，单独微调面部的每个部分，从而实现更精细的美颜效果。

信息

该方法仅适用于 Android 4.4 或更高版本。
该方法依赖美颜特效动态库 libagora_clear_vision_extension.dll。如果该动态库被删除，则无法正常启用该功能。
该功能对设备性能要求较高。调用该方法时，SDK 会自动检测当前设备的能力。

调用时机

在调用 setFaceShapeBeautyOptions 之后调用该方法。

参数

options

面部增强区域，详见 FaceShapeAreaOptions。

type

媒体源类型，详见 MEDIA_SOURCE_TYPE。

信息

该参数仅支持以下两种设置：

如果使用摄像头采集本地视频，使用默认值 PRIMARY_CAMERA_SOURCE。
如果使用自定义视频源，将该参数设置为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -4：当前设备不支持该功能。可能原因包括：
  - 当前设备能力不满足美颜特效的要求。声网建议更换为高性能设备。
  - 当前设备版本低于 Android 4.4，不支持该功能。声网建议更换设备或升级操作系统。

所属接口类

IRtcEngine

setFaceShapeBeautyOptions

设置美型选项并指定媒体源。

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

调用该方法可以通过预设参数一次性调整多个面部部位，实现瘦脸、放大眼睛、瘦鼻等轻度美颜效果，并支持整体调节美型强度。

信息

该方法仅适用于 Android 4.4 或更高版本。该方法依赖美颜特效动态库 libagora_clear_vision_extension.dll。如果该动态库被删除，将无法正常启用该功能。该功能对设备性能要求较高。调用该方法时，SDK 会自动检测当前设备的能力。

调用时机

在调用 enableVideo 方法之后调用该方法。

参数

enabled

是否启用美型特效：

true：启用美型特效。
false：（默认）关闭美型特效。

options

美型风格选项，详见 FaceShapeBeautyOptions。

type

要应用滤镜特效的媒体源类型，详见 MEDIA_SOURCE_TYPE。该参数仅支持以下两种设置：

如果使用摄像头采集本地视频，使用默认值 PRIMARY_CAMERA_SOURCE。
如果使用自定义视频源，将该参数设置为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -4：当前设备不支持该功能。可能原因包括：
  - 当前设备能力不满足美颜特效要求。声网建议更换为高性能设备。
  - 当前设备版本低于 Android 4.4，不支持该功能。声网建议更换设备或升级操作系统。

所属接口类

IRtcEngine

setFilterEffectOptions

设置滤镜特效选项并指定媒体源。

C++
virtual int setFilterEffectOptions(bool enabled, const FilterEffectOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

自从

自 v4.4.1 版本新增。

信息

该方法依赖美颜特效动态库 libagora_clear_vision_extension.dll。如果该动态库被删除，则无法正常启用此功能。该功能对设备性能要求较高。调用该方法时，SDK 会自动检测当前设备的性能能力。

调用时机

在调用 enableVideo 方法之后调用本方法。

参数

enabled

是否启用滤镜特效：

true：启用。
false：（默认）不启用。

options

滤镜特效选项。详见 FilterEffectOptions。

type

应用滤镜特效的媒体源类型。详见 MEDIA_SOURCE_TYPE。

如果使用摄像头采集本地视频，使用默认值 PRIMARY_CAMERA_SOURCE。
如果使用自定义视频源，设置为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

setLowlightEnhanceOptions

设置暗光增强功能。

C++
virtual int setLowlightEnhanceOptions(bool enabled, const LowlightEnhanceOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

自从

自 v4.0.0 版本新增。

你可以调用该方法启用暗光增强功能，并设置增强效果的参数。

信息

该方法依赖美颜特效动态库 libagora_clear_vision_extension.dll。如果该动态库被删除，该功能将无法正常启用。
暗光增强对设备性能有一定要求。如果启用暗光增强后设备出现过热，声网建议将暗光增强选项设置为较低的性能消耗等级，或完全关闭暗光增强功能。
如果你希望在使用暗光增强功能时优先保证画质（LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY），需要先调用 setVideoDenoiserOptions 实现视频降噪，具体对应关系如下：
- 当暗光增强设置为自动模式（LOW_LIGHT_ENHANCE_AUTO）时，视频降噪需设置为优先保证画质（VIDEO_DENOISER_LEVEL_HIGH_QUALITY）和自动模式（VIDEO_DENOISER_AUTO）。
- 当暗光增强设置为手动模式（LOW_LIGHT_ENHANCE_MANUAL）时，视频降噪需设置为优先保证画质（VIDEO_DENOISER_LEVEL_HIGH_QUALITY）和手动模式（VIDEO_DENOISER_MANUAL）。

适用场景

暗光增强功能可自适应调整在背光、多云或黑暗等低光或光线不均的场景中采集的视频亮度值，恢复或突出图像细节，提升视频整体视觉效果。

调用时机

请在调用 enableVideo 后调用该方法。

参数

enabled

是否启用暗光增强功能：

true：启用暗光增强功能。
false：（默认）关闭暗光增强功能。

options

暗光增强选项，详见 LowlightEnhanceOptions。

type

应用滤镜效果的媒体源类型，详见 MEDIA_SOURCE_TYPE。

信息

在该方法中，该参数仅支持以下两种设置：

如果使用摄像头采集本地视频，使用默认值 PRIMARY_CAMERA_SOURCE。
如果使用自定义视频源，设置为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

setVideoDenoiserOptions

设置视频降噪功能。

C++
virtual int setVideoDenoiserOptions(bool enabled, const VideoDenoiserOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;

自从

自 v4.0.0 版本新增。

信息

该方法依赖美颜特效动态库 libagora_clear_vision_extension.dll。如果该动态库被删除，将无法正常启用该功能。
视频降噪对设备性能有一定要求。如果你在启用视频降噪后设备出现过热情况，声网建议你将视频降噪选项设置为较低的性能消耗等级，或完全关闭视频降噪功能。
如果该方法实现的视频降噪效果无法满足你的需求，声网建议你调用 setBeautyEffectOptions 方法启用美颜和磨皮功能，以获得更好的视频降噪效果。推荐用于强降噪效果的 BeautyOptions 设置如下：
- lighteningContrastLevel：LIGHTENING_CONTRAST_NORMAL。
- lighteningLevel：0.0。
- smoothnessLevel：0.5。
- rednessLevel：0.0。
- sharpnessLevel：0.1。

适用场景

在光线较暗的环境中或使用低端视频采集设备时，视频图像可能会出现明显噪点，影响视频质量。在实时互动场景中，视频噪点还会占用码流资源，降低编码效率。该方法适用于多频道场景。

调用时机

调用 enableVideo 方法后调用该方法。

参数

enabled

是否启用视频降噪功能：

true：启用视频降噪。
false：（默认）关闭视频降噪。

options

视频降噪选项，详见 VideoDenoiserOptions。

type

媒体源类型，详见 MEDIA_SOURCE_TYPE。

信息

在该方法中，该参数仅支持以下两种设置：

如果使用摄像头采集本地视频，使用默认值 PRIMARY_CAMERA_SOURCE。
如果使用自定义视频源，设置该参数为 CUSTOM_VIDEO_SOURCE。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

setVideoEffectBoolParam

设置视频特效的布尔参数。

C++
virtual int setVideoEffectBoolParam(const char* option, const char* key, bool param) = 0;

自从

自 v4.6.0 版本新增。

参数

option

参数选项的类别。

key

参数的键名。

param

要设置的布尔值：

true：启用该选项。
false：禁用该选项。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IVideoEffectObject

setVideoEffectFloatParam

设置视频特效的浮点参数。

C++
virtual int setVideoEffectFloatParam(const char* option, const char* key, float param) = 0;

自从

自 v4.6.0 版本新增。

参数

option: 参数选项的类别。
key: 参数的键名。
param: 要设置的浮点值。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IVideoEffectObject

setVideoEffectIntParam

setVideoEffectIntParam：设置视频特效的整数参数。

C++
virtual int setVideoEffectIntParam(const char* option, const char* key, int param) = 0;

自从

自 v4.6.0 版本新增。

参数

option: 参数所属选项的类别。
key: 参数的键名。
param: 要设置的整数参数值。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IVideoEffectObject

addOrUpdateVideoEffect

参数​

返回值​

createVideoEffectObject

参数​

返回值​

destroyVideoEffectObject

参数​

返回值​

getFaceShapeAreaOptions

适用场景

调用时机

参数​

返回值​

getFaceShapeBeautyOptions

适用场景

调用时机

参数​

返回值​

getVideoEffectBoolParam

参数​

返回值​

getVideoEffectFloatParam

参数​

返回值​

getVideoEffectIntParam

参数​

返回值​

performVideoEffectAction

参数​

返回值​

removeVideoEffect

参数​

返回值​

setBeautyEffectOptions

调用时机

参数​

返回值​

setColorEnhanceOptions

参数​

返回值​

setFaceShapeAreaOptions

调用时机

参数​

返回值​

setFaceShapeBeautyOptions

调用时机

参数​

返回值​

setFilterEffectOptions

调用时机

参数​

返回值​

setLowlightEnhanceOptions

适用场景

调用时机

参数​

返回值​

setVideoDenoiserOptions

适用场景

调用时机

参数​

返回值​

setVideoEffectBoolParam

参数​

返回值​

setVideoEffectFloatParam

参数​

返回值​

setVideoEffectIntParam

参数​

返回值​

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值