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

视频增强

  • Flutter

更新时间不可用

addOrUpdateVideoEffect

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

Dart
Future<void> addOrUpdateVideoEffect(
      {required int nodeId, required String templateName});

自从

自 v6.6.2 版本新增。

注： 优先级规则：

  • 风格妆节点优先于滤镜特效节点。
  • 若要应用滤镜特效，必须先移除风格妆特效节点。

参数

参数名描述
nodeId

视频特效节点的唯一标识符或标识符组合。详见 VideoEffectNodeId。

templateName

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

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

返回值

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

所属接口类

createVideoEffectObject

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

Dart
Future<VideoEffectObject?> createVideoEffectObject(
      {required String bundlePath,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

自从

自 v6.6.2 版本新增。

参数

参数名描述
bundlePath

视频特效资源包的路径。

type

媒体源类型，详见 MediaSourceType。

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

返回值

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

所属接口类

destroyVideoEffectObject

销毁视频特效对象。

Dart
Future<void> destroyVideoEffectObject(VideoEffectObject videoEffectObject);

自从

自 v6.6.2 版本新增。

参数

参数名描述
videoEffectObject

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

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

返回值

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

所属接口类

getFaceShapeAreaOptions

获取美型部位选项。

Dart
Future<FaceShapeAreaOptions> getFaceShapeAreaOptions(
      {required FaceShapeArea shapeArea,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

调用该方法可以获取美型部位当前设置的参数信息。

适用场景

用户在 App 中打开美型部位和修饰力度菜单时，你可以调用该方法获取当前的美型部位选项，然后根据结果刷新用户界面中的菜单，并更新 UI。

调用时机

请在 enableVideo 之后调用该方法。

参数

参数名描述
shapeArea

美型部位。详见 FaceShapeArea。

type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，返回 FaceShapeAreaOptions 对象；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

getFaceShapeBeautyOptions

获取美型效果选项。

Dart
Future<FaceShapeBeautyOptions> getFaceShapeBeautyOptions(
      {MediaSourceType type = MediaSourceType.primaryCameraSource});

调用该方法可以获取美型效果当前设置的参数信息。

适用场景

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

调用时机

请在 enableVideo 之后调用该方法。

参数

参数名描述
type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，返回 FaceShapeBeautyOptions 对象；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

getVideoEffectBoolParam

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

Dart
Future<bool> getVideoEffectBoolParam(
      {required String option, required String key});

自从

自 v6.6.2 版本新增。

参数

参数名描述
option

参数所属的选项类别。

key

参数的键名。

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

返回值

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

所属接口类

getVideoEffectFloatParam

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

Dart
Future<double> getVideoEffectFloatParam(
      {required String option, required String key});

自从

自 v6.6.2 版本新增。

参数

参数名描述
option

参数所属选项的类别。

key

参数的键名。

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

返回值

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

所属接口类

getVideoEffectIntParam

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

Dart
Future<int> getVideoEffectIntParam(
      {required String option, required String key});

自从

自 v6.6.2 版本新增。

参数

参数名描述
option

参数选项的类别。

key

参数的键名。

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

返回值

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

所属接口类

performVideoEffectAction

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

Dart
Future<void> performVideoEffectAction(
      {required int nodeId, required VideoEffectAction actionId});

自从

自 v6.6.2 版本新增。

参数

参数名描述
nodeId

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

actionId

要执行的操作，详见 VideoEffectAction。

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

返回值

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

所属接口类

removeVideoEffect

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

Dart
Future<void> removeVideoEffect(int nodeId);

自从

自 v6.6.2 版本新增。

参数

参数名描述
nodeId

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

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

返回值

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

所属接口类

setBeautyEffectOptions

设置美颜效果选项。

Dart
Future<void> setBeautyEffectOptions(
    {required bool enabled,
    required BeautyOptions options,
    MediaSourceType type = MediaSourceType.primaryCameraSource});

开启本地美颜功能，并设置美颜效果选项。

注：

  • 该方法依赖于视频增强动态库 libagora_clear_vision_extension.dll，如果删除该动态库会导致无法正常开启该功能。
  • 该功能对设备性能要求较高，调用该方法时 SDK 会自动对当前设备能力进行检查。

调用时机

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

参数

参数名描述
enabled

是否开启美颜功能：

  • true: 开启美颜功能。
  • false:（默认）关闭美颜功能。
options

美颜选项，详细定义见 BeautyOptions。

type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setColorEnhanceOptions

设置色彩增强功能。

Dart
Future<void> setColorEnhanceOptions(
      {required bool enabled,
      required ColorEnhanceOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

摄像头采集到的视频画面可能存在色彩失真的现象。色彩增强功能可以通过智能调节饱和度和对比度等视频特性，提升视频色彩丰富度和色彩还原度，最终使视频画面更生动。 你可以调用该方法开启色彩增强功能并设置色彩增强的效果。

注：

  • 请在 enableVideo 后调用该方法。
  • 色彩增强对设备性能有一定要求。开启色彩增强后，如果设备出现严重发烫等问题，建议你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。
  • 该方法依赖于视频增强动态库 libagora_clear_vision_extension.dll，如果删除该动态库会导致无法正常开启该功能。

参数

参数名描述
enabled

是否开启色彩增强功能：

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

色彩增强选项，用于设置色彩增强的效果。详见 ColorEnhanceOptions。

type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setFaceShapeAreaOptions

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

Dart
Future<void> setFaceShapeAreaOptions(
      {required FaceShapeAreaOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

如果在 setFaceShapeBeautyOptions 方法中实现的预设美型效果达不到预期，你可以通过该方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。

注： 美型属于增值服务，计费方式详见计费策略。

  • 在 Android 平台上，该方法仅适用于 Android 4.4 及以上版本。
  • 该方法依赖于视频增强动态库 libagora_clear_vision_extension.dll，如果删除该动态库会导致无法正常开启该功能。
  • 该功能对设备性能要求较高，调用该方法时 SDK 会自动对当前设备能力进行检查。

调用时机

请在 setFaceShapeBeautyOptions 之后调用该方法。

参数

参数名描述
options

美型部位选项，详见 FaceShapeAreaOptions。

type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setFaceShapeBeautyOptions

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

Dart
Future<void> setFaceShapeBeautyOptions(
      {required bool enabled,
      required FaceShapeBeautyOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

调用该方法可对人脸各部位进行修饰，使用预设的参数一次性实现瘦脸、大眼、瘦鼻等微整形效果，支持微调整体的修饰力度。

注： 美型属于增值服务，计费方式详见计费策略。

  • 在 Android 平台上，该方法仅适用于 Android 4.4 及以上版本。
  • 该方法依赖于视频增强动态库 libagora_clear_vision_extension.dll，如果删除该动态库会导致无法正常开启该功能。
  • 该功能对设备性能要求较高，调用该方法时 SDK 会自动对当前设备能力进行检查。

调用时机

请在 enableVideo 之后调用该方法。

参数

参数名描述
enabled

是否开启美型效果：

  • true: 开启美型功能。
  • false:（默认）关闭美型功能。
options

美型风格选项，详见 FaceShapeBeautyOptions。

type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setFilterEffectOptions

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

Dart
Future<void> setFilterEffectOptions(
      {required bool enabled,
      required FilterEffectOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

注：

  • 该方法依赖于视频增强动态库 libagora_clear_vision_extension.dll，如果删除该动态库会导致无法正常开启该功能。
  • 该功能对设备性能要求较高，调用该方法时 SDK 会自动对当前设备能力进行检查。

调用时机

请在 enableVideo 之后调用该方法。

参数

参数名描述
enabled

是否开启滤镜效果：

  • true: 开启滤镜功能。
  • false:（默认）关闭滤镜功能。
options

滤镜选项，详见 FilterEffectOptions。

type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setLowlightEnhanceOptions

设置暗光增强功能。

Dart
Future<void> setLowlightEnhanceOptions(
      {required bool enabled,
      required LowlightEnhanceOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

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

注：

  • 该方法依赖于视频增强动态库 libagora_clear_vision_extension.dll，如果删除该动态库会导致无法正常开启该功能。

  • 暗光增强对设备性能有一定要求。开启暗光增强后，如果设备出现严重发烫等问题，建议你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。

  • 如果要实现优先画质 (lowLightEnhanceLevelHighQuality) 的暗光增强，需要先调用 setVideoDenoiserOptions 实现视频降噪，具体对应关系如下：

    • 暗光增强为自动模式 (LowLightEnhanceAuto) 时，视频降噪需设置为优先画质 (videoDenoiserLevelHighQuality)、自动模式 (videoDenoiserAuto)。
    • 暗光增强为手动模式 (LowLightEnhanceManual) 时，视频降噪需设置为优先画质 (videoDenoiserLevelHighQuality)、手动模式 (videoDenoiserManual)。

适用场景

暗光增强功能可以在光线亮度偏低（如背光、阴天、暗场景）和亮度不均匀的环境下自适应调整视频画面的亮度值，恢复或凸显图像的细节信息，最终提升视频图像的整体视觉效果。

调用时机

请在 enableVideo 后调用该方法。

参数

参数名描述
enabled

是否开启暗光增强功能：

  • true: 开启暗光增强功能。
  • false:（默认）关闭暗光增强功能。
options

暗光增强选项，用于设置暗光增强的效果。详见 LowlightEnhanceOptions。

type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setVideoDenoiserOptions

设置视频降噪功能。

Dart
Future<void> setVideoDenoiserOptions(
      {required bool enabled,
      required VideoDenoiserOptions options,
      MediaSourceType type = MediaSourceType.primaryCameraSource});

你可以调用该方法开启视频降噪功能并设置视频降噪的效果。

注： 如果该方法实现的降噪强度无法满足你的需求，声网推荐你调用 setBeautyEffectOptions 方法启用美颜磨皮功能，以获得更好的视频降噪效果。强效降噪效果的 BeautyOptions 推荐设置如下：

  • lighteningContrastLevel：lighteningContrastNormal
  • lighteningLevel：0.0
  • smoothnessLevel：0.5
  • rednessLevel：0.0
  • sharpnessLevel：0.1
  • 该方法依赖于视频增强动态库 libagora_clear_vision_extension.dll，如果删除该动态库会导致无法正常开启该功能。
  • 视频降噪对设备性能有一定要求。开启视频降噪后，如果设备出现严重发烫等问题，建议你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。

适用场景

采光不足的环境和低端视频采集设备会使视频图像含有明显的噪声，影响视频画质。在实时互动场景下，视频噪声还会在编码过程中占用码流资源并降低编码效率。

调用时机

请在 enableVideo 后调用该方法。

参数

参数名描述
enabled

是否开启视频降噪功能：

  • true: 开启视频降噪功能。
  • false:（默认）关闭视频降噪功能。
options

视频降噪选项，用于设置视频降噪的效果。详见 VideoDenoiserOptions。

type

效果应用的媒体源类型。详见 MediaSourceType。

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

  • 使用摄像头采集本地视频时，请保持默认值 primaryCameraSource。
  • 如果要使用自定义采集的视频，将该参数设置为 customVideoSource。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setVideoEffectBoolParam

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

Dart
Future<void> setVideoEffectBoolParam(
      {required String option, required String key, required bool param});

自从

自 v6.6.2 版本新增。

参数

参数名描述
option

参数选项的类别。

key

参数的键名。

param

要设置的布尔值：

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

返回值

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

所属接口类

setVideoEffectFloatParam

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

Dart
Future<void> setVideoEffectFloatParam(
      {required String option, required String key, required double param});

自从

自 v6.6.2 版本新增。

参数

参数名描述
option

参数选项的类别。

key

参数的键名。

param

要设置的浮点值。

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

返回值

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

所属接口类

setVideoEffectIntParam

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

Dart
Future<void> setVideoEffectIntParam(
      {required String option, required String key, required int param});

自从

自 v6.6.2 版本新增。

参数

参数名描述
option

参数所属选项的类别。

key

参数的键名。

param

要设置的整数参数值。

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

返回值

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利