需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

视频增强

  • C++

更新时间不可用

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) 节点。
  • 若要应用滤镜特效，必须先移除风格妆特效节点：
Text
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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

所属接口类

destroyVideoEffectObject

销毁视频特效对象。

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
videoEffectObject

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

getVideoEffectBoolParam

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

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
option

参数所属的选项类别。

key

参数的键名。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

getVideoEffectFloatParam

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

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
option

参数所属选项的类别。

key

参数的键名。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

getVideoEffectIntParam

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

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
option

参数选项的类别。

key

参数的键名。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

performVideoEffectAction

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

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
nodeId

视频特效节点的唯一标识符。

actionId

要执行的操作，详见 VIDEO_EFFECT_ACTION。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

removeVideoEffect

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

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
nodeId

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

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：当前设备不支持该功能。可能原因包括：

      • 当前设备性能不满足美颜特效的要求。建议更换为高性能设备。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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，不支持该功能。声网建议更换设备或升级操作系统。

所属接口类

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，不支持该功能。声网建议更换设备或升级操作系统。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

setVideoEffectBoolParam

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

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
option

参数选项的类别。

key

参数的键名。

param

要设置的布尔值：

  • true：启用该选项。
  • false：禁用该选项。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setVideoEffectFloatParam

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

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
option

参数选项的类别。

key

参数的键名。

param

要设置的浮点值。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setVideoEffectIntParam

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

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
option

参数所属选项的类别。

key

参数的键名。

param

要设置的整数参数值。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setVideoEffectStringParam

设置视频特效的字符串参数。

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

自从

自 v4.6.0 版本新增。

参数

参数名描述
option

选项的类别。

key

参数的键名。

param

要设置的字符串值。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利