视频增强

addOrUpdateVideoEffectWithNodeId:templateName:

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

Objective-C

- (int)addOrUpdateVideoEffectWithNodeId:(NSUInteger)nodeId
                          templateName:(NSString *)templateName
NS_SWIFT_NAME(addOrUpdateVideoEffect(nodeId:templateName:));

自从

自 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::BEAUTY。
• 组合特效：VIDEO_EFFECT_NODE_ID::BEAUTY | VIDEO_EFFECT_NODE_ID::STYLE_MAKEUP。

templateName

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

返回值

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

所属接口类

• AgoraVideoEffectObject

createVideoEffectObjectWithBundlePath:sourceType:

创建一个视频特效对象。

Objective-C

- (id<AgoraVideoEffectObject> _Nullable)createVideoEffectObjectWithBundlePath:(NSString * _Nonnull)bundlePath
                                                                   sourceType:(AgoraMediaSourceType)sourceType
    NS_SWIFT_NAME(createVideoEffectObject(bundlePath:sourceType:));

自从

自 v4.6.0 版本新增。

返回一个 AgoraVideoEffectObject 视频特效对象的指针。

参数

bundlePath

视频特效 bundle 的路径。

sourceType

媒体源类型，例如 AgoraMediaSourceTypePrimaryCamera。详见 AgoraMediaSourceType。

返回值

• 方法调用成功，返回 AgoraVideoEffectObject 对象，详见 AgoraVideoEffectObject。
• 方法调用失败，返回 nil。

所属接口类

• AgoraRtcEngineKit

destroyVideoEffectObject:

销毁一个视频特效对象。

Objective-C

- (int)destroyVideoEffectObject:(id<AgoraVideoEffectObject> _Nullable)videoEffectObject NS_SWIFT_NAME(destroyVideoEffectObject(_:));

自从

自 v4.6.0 版本新增。

参数

videoEffectObject

要销毁的 AgoraVideoEffectObject 实例的指针。详见 AgoraVideoEffectObject。

返回值

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

所属接口类

• AgoraRtcEngineKit

getFaceShapeAreaOptions:sourceType:

获取美型区域的选项。

Objective-C

- (AgoraFaceShapeAreaOptions * _Nullable)getFaceShapeAreaOptions:(AgoraFaceShapeArea) area sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(getFaceShapeAreaOptions(_:sourceType:));

适用场景

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

调用时机

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

参数

area

美型增强区域。详见 AgoraFaceShapeArea。

sourceType

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

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

返回值

方法调用成功，返回 AgoraFaceShapeAreaOptions 对象。 方法调用失败，返回 nil。

所属接口类

• AgoraRtcEngineKit

getFaceShapeAreaOptions:

获取当前的美颜特效设置。

Objective-C

- (AgoraFaceShapeAreaOptions * _Nullable)getFaceShapeAreaOptions:(AgoraFaceShapeArea) area NS_SWIFT_NAME(getFaceShapeAreaOptions(_:));

适用场景

当你在 App 中打开美型区域和强度设置菜单时，可以调用此方法获取当前的美颜特效选项，然后根据结果刷新菜单并更新 UI。

调用时机

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

参数

area

美型增强区域。参见 AgoraFaceShapeArea。

返回值

方法调用成功，返回 AgoraFaceShapeAreaOptions 对象。 方法调用失败，返回 nil。

所属接口类

• AgoraRtcEngineKit

getFaceShapeBeautyOptions:

获取美颜特效选项。

Objective-C

- (AgoraFaceShapeBeautyOptions * _Nullable)getFaceShapeBeautyOptions:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(getFaceShapeBeautyOptions(_:));

适用场景

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

调用时机

在调用 enableVideo 后调用此方法。

参数

sourceType

应用滤镜特效的媒体源类型，详见 AgoraMediaSourceType。在此方法中，该参数仅支持以下两种设置：

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

返回值

• 方法调用成功，返回 AgoraFaceShapeBeautyOptions 对象，详见 AgoraFaceShapeBeautyOptions。
• 方法调用失败，返回 nil。

所属接口类

• AgoraRtcEngineKit

getFaceShapeBeautyOptions

获取当前的美颜特效设置。

Objective-C

- (AgoraFaceShapeBeautyOptions * _Nullable)getFaceShapeBeautyOptions NS_SWIFT_NAME(getFaceShapeBeautyOptions());

适用场景

当你在应用中打开风格妆容和风格强度菜单时，可以调用该方法获取当前的美颜特效设置，然后根据结果刷新菜单并更新 UI。

调用时机

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

返回值

• 方法调用成功，返回 AgoraFaceShapeBeautyOptions 对象。
• 方法调用失败，返回 nil。

所属接口类

• AgoraRtcEngineKit

getVideoEffectBoolParamWithOption:key:

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

Objective-C

- (BOOL)getVideoEffectBoolParamWithOption:(NSString *)option
                                    key:(NSString *)key
NS_SWIFT_NAME(getVideoEffectBoolParam(option:key:));

自从

自 v4.6.0 版本新增。

参数

option

参数类别的标识符。

key

参数的键值。

返回值

• YES：参数已启用。
• NO：参数未启用或不存在。

所属接口类

• AgoraVideoEffectObject

getVideoEffectFloatParamWithOption:key:

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

Objective-C

- (float)getVideoEffectFloatParamWithOption:(NSString *)option
                                    key:(NSString *)key
NS_SWIFT_NAME(getVideoEffectFloatParam(option:key:));

自从

自 v4.6.0 版本新增。

用于获取视频特效中指定 option 和 key 对应的 float 类型参数值。

参数

option

参数选项的类别。

key

参数的键名。

返回值

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

所属接口类

• AgoraVideoEffectObject

getVideoEffectIntParamWithOption:key:

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

Objective-C

- (int)getVideoEffectIntParamWithOption:(NSString *)option
                                    key:(NSString *)key
NS_SWIFT_NAME(getVideoEffectIntParam(option:key:));

自从

自 v4.6.0 版本新增。

参数

option

参数类别的标识符。

key

参数的键值。

返回值

• 方法调用成功时，返回对应参数的整数值。
• 方法调用失败或参数不存在时，返回 0。

所属接口类

• AgoraVideoEffectObject

performVideoEffectActionWithNodeId:actionId:

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

Objective-C

- (int)performVideoEffectActionWithNodeId:(NSUInteger)nodeId
                                actionId:(AgoraVideoEffectAction)actionId
NS_SWIFT_NAME(performVideoEffectAction(nodeId:actionId:));

自从

自 v4.6.0 版本新增。

参数

nodeId

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

actionId

要执行的操作，详见 AgoraVideoEffectAction。

返回值

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

所属接口类

• AgoraVideoEffectObject

removeVideoEffectWithNodeId:

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

Objective-C

- (int)removeVideoEffectWithNodeId:(NSUInteger)nodeId
NS_SWIFT_NAME(removeVideoEffect(nodeId:));

自从

自 v4.6.0 版本新增。

参数

nodeId

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

返回值

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

所属接口类

• AgoraVideoEffectObject

setBeautyEffectOptions:options:

设置图像增强选项。

Objective-C

- (int)setBeautyEffectOptions:(BOOL)enable options:(AgoraBeautyOptions* _Nullable)options NS_SWIFT_NAME(setBeautyEffectOptions(_:options:));

你可以通过该方法启用或禁用图像增强功能，并设置相关选项。请在调用 enableVideo 或 startPreview: 方法之后调用本方法。

信息

• 该方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。
• 该功能对设备性能要求较高。调用该方法时，SDK 会自动检测当前设备的性能能力。

调用时机

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

参数

enable

是否启用图像增强功能：

• YES：启用图像增强功能。
• NO：（默认）禁用图像增强功能。

options

图像增强选项，详见 AgoraBeautyOptions。

返回值

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

所属接口类

• AgoraRtcEngineKit

setBeautyEffectOptions:options:sourceType:

设置美颜特效选项并指定媒体源。

Objective-C

- (int)setBeautyEffectOptions:(BOOL)enable options:(AgoraBeautyOptions* _Nullable)options sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(setBeautyEffectOptions(_:options:sourceType:));

该方法与 setBeautyEffectOptions:options: 都用于设置美颜特效选项，但该方法允许你指定应用美颜特效的媒体源。

调用时机

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

参数

enable

是否启用美颜特效功能：

• YES：启用美颜特效功能。
• NO：（默认）禁用美颜特效功能。

options

美颜特效选项。详见 AgoraBeautyOptions。

sourceType

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

信息

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

• 默认值为 AgoraMediaSourceTypePrimaryCamera。
• 如果你使用自定义视频源，请将该参数设置为 AgoraMediaSourceTypeCustomVideo。

返回值

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

所属接口类

• AgoraRtcEngineKit

setColorEnhanceOptions:options:

设置色彩增强效果。

Objective-C

- (int)setColorEnhanceOptions:(BOOL)enable options:(AgoraColorEnhanceOptions* _Nullable)options  NS_SWIFT_NAME(setColorEnhanceOptions(_:options:));

自从

自 v4.0.0 版本新增。

摄像头采集的视频图像可能存在色彩失真。色彩增强功能可智能调整视频的饱和度和对比度等特性，从而增强视频的色彩丰富度和色彩还原度，使视频画面更加生动。你可以调用 setColorEnhanceOptions:options: 方法开启色彩增强功能并设置色彩增强效果的参数。

信息

• 请在调用 enableVideo 方法之后调用此方法。
• 色彩增强功能对设备性能有一定要求。开启色彩增强后，如果设备出现严重发热问题，声网建议你降低色彩增强等级以减少性能消耗，或关闭色彩增强功能。
• 此方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。

参数

enable

是否开启色彩增强功能：

• YES：开启色彩增强。
• NO：（默认）关闭色彩增强。

options

色彩增强参数，详见 AgoraColorEnhanceOptions。

返回值

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

所属接口类

• AgoraRtcEngineKit

setColorEnhanceOptions:options:sourceType:

设置色彩增强选项并指定媒体源。

Objective-C

- (int)setColorEnhanceOptions:(BOOL)enable options:(AgoraColorEnhanceOptions* _Nullable)options sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(setColorEnhanceOptions(_:options:sourceType:));

自从

自 v4.0.0 版本新增。

摄像头采集的视频图像可能存在色彩失真。色彩增强功能可智能调整视频的饱和度和对比度等特性，从而增强视频的色彩丰富度和色彩还原度，使视频画面更加生动。该方法与 setColorEnhanceOptions:options: 方法类似，但该方法允许你指定应用色彩增强选项的媒体源。

信息

• 请在调用 enableVideo 方法之后调用此方法。
• 色彩增强功能对设备性能有一定要求。开启色彩增强功能后，如果设备出现严重发热问题，声网建议你降低色彩增强等级以减少性能消耗，或关闭色彩增强功能。
• 此方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。

参数

enable

是否开启色彩增强功能：

• YES：开启色彩增强功能。
• NO：（默认）关闭色彩增强功能。

options

色彩增强选项，详见 AgoraColorEnhanceOptions。

sourceType

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

• 默认值为 AgoraMediaSourceTypePrimaryCamera。
• 如果使用自定义视频源，请将该参数设置为 AgoraMediaSourceTypeCustomVideo。

返回值

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

所属接口类

• AgoraRtcEngineKit

setFaceShapeAreaOptions:sourceType:

设置美颜增强的面部区域选项。

Objective-C

- (int)setFaceShapeAreaOptions:(AgoraFaceShapeAreaOptions* _Nullable)options sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(setFaceShapeAreaOptions(_:sourceType:));

如果通过 setFaceShapeBeautyOptions:options: 方法实现的预设美型效果不符合预期，你可以使用此方法设置美颜区域选项，单独微调面部的每个部分，从而实现更精细的美颜效果。

信息

• 此方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果删除该动态库，功能将无法正常启用。
• 此功能对设备性能要求较高。调用此方法时，SDK 会自动检测当前设备的能力。

调用时机

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

参数

options

面部增强区域，详见 AgoraFaceShapeAreaOptions。

sourceType

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

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -4：当前设备不支持此功能。可能原因包括：
    • 当前设备的能力不满足图像增强的要求。声网建议你更换为高性能设备。

所属接口类

• AgoraRtcEngineKit

setFaceShapeAreaOptions:

设置美颜增强的面部区域选项。

Objective-C

- (int)setFaceShapeAreaOptions:(AgoraFaceShapeAreaOptions* _Nullable)options NS_SWIFT_NAME(setFaceShapeAreaOptions(_:));

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

信息

• 此方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果删除该动态库，功能将无法正常启用。
• 此功能对设备性能要求较高。调用此方法时，SDK 会自动检测当前设备的能力。

调用时机

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

参数

options

面部增强区域。详见 AgoraFaceShapeAreaOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -4：当前设备不支持此功能。可能的原因包括：
    • 当前设备的能力不满足图像增强的要求。声网建议你更换为高性能设备。

所属接口类

• AgoraRtcEngineKit

setFaceShapeBeautyOptions:options:sourceType:

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

Objective-C

- (int)setFaceShapeBeautyOptions:(BOOL)enable options:(AgoraFaceShapeBeautyOptions* _Nullable)options sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(setFaceShapeBeautyOptions(_:options:sourceType:));

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

信息

• 该方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果删除该动态库，功能将无法正常启用。
• 该功能对设备性能要求较高。调用该方法时，SDK 会自动检测当前设备的能力。

调用时机

在调用 enableVideo 后调用该方法。

参数

enable

是否开启美型特效：

• YES：开启美型特效。
• NO：（默认）关闭美型特效。

options

美型风格选项，详见 AgoraFaceShapeBeautyOptions。

sourceType

要应用滤镜特效的媒体源类型，详见 AgoraMediaSourceType。

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -4：当前设备不支持该功能。可能原因包括：
    • 当前设备能力不满足图像增强要求。声网建议你更换为高性能设备。

所属接口类

• AgoraRtcEngineKit

setFaceShapeBeautyOptions:options:

设置美型选项。

Objective-C

- (int)setFaceShapeBeautyOptions:(BOOL)enable options:(AgoraFaceShapeBeautyOptions* _Nullable)options NS_SWIFT_NAME(setFaceShapeBeautyOptions(_:options:));

调用该方法可以调整面部的特定部位，实现瘦脸、放大眼睛和瘦鼻等美型效果。

信息

• 此方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果删除该动态库，则无法正常启用此功能。
• 此功能对设备性能要求较高。调用该方法时，SDK 会自动检测当前设备的能力。

调用时机

在调用 enableVideo 方法之后调用。

参数

enable

是否启用美型效果：

• YES：启用美型效果。
• NO：（默认）关闭美型效果。

options

美型风格选项，详见 AgoraFaceShapeBeautyOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -4：当前设备不支持此功能。可能的原因包括：
    • 当前设备的图像增强能力不满足要求。声网建议你更换为高性能设备。

所属接口类

• AgoraRtcEngineKit

setFilterEffectOptions:options:sourceType:

设置滤镜特效参数并指定媒体源。

Objective-C

- (int)setFilterEffectOptions:(BOOL)enable options:(AgoraFilterEffectOptions* _Nullable)options sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(setFilterEffectOptions(_:options:sourceType:));

自从

自 v4.4.1 版本新增。

该方法与 setBeautyEffectOptions:options:sourceType: 方法都用于设置滤镜特效参数。不同之处在于，该方法允许你指定滤镜特效应用的媒体源。

信息

• 该方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果删除该动态库，该功能将无法正常启用。
• 该功能对设备性能要求较高。调用该方法时，SDK 会自动检测当前设备的性能能力。

调用时机

在调用 enableVideo 后调用该方法。

参数

enable

是否启用滤镜特效：

• YES：启用。
• NO：（默认）不启用。

options

滤镜特效参数，详见 AgoraFilterEffectOptions。

sourceType

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

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

返回值

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

所属接口类

• AgoraRtcEngineKit

setFilterEffectOptions:options:

设置滤镜特效选项。

Objective-C

- (int)setFilterEffectOptions:(BOOL)enable options:(AgoraFilterEffectOptions* _Nullable)options  NS_SWIFT_NAME(setFilterEffectOptions(_:options:));

自从

自 v4.4.1 版本新增。

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

信息

• 此方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果该动态库被删除，则无法正常启用此功能。
• 此功能对设备性能要求较高。调用此方法时，SDK 会自动检测当前设备的性能能力。

调用时机

在调用 enableVideo 方法之后调用。

参数

enable

是否启用滤镜特效：

• YES：启用。
• NO：（默认）不启用。

options

滤镜特效选项，详见 AgoraFilterEffectOptions。

返回值

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

所属接口类

• AgoraRtcEngineKit

setLowlightEnhanceOptions:options:

设置暗光增强功能。

Objective-C

- (int)setLowlightEnhanceOptions:(BOOL)enable options:(AgoraLowlightEnhanceOptions* _Nullable)options  NS_SWIFT_NAME(setLowlightEnhanceOptions(_:options:));

自从

自 v4.0.0 版本新增。

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

信息

• 此方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。
• 暗光增强对设备性能有一定要求。如果启用暗光增强后设备出现过热，声网建议将暗光增强选项设置为较低的性能消耗等级，或完全关闭暗光增强功能。
• 如果你希望在使用暗光增强功能时优先保证画质（AgoraLowlightEnhanceLevelQuality），需要先调用 setVideoDenoiserOptions:options: 实现视频降噪，具体对应关系如下：
  • 当暗光增强设置为自动模式（AgoraLowlightEnhanceModeAuto）时，视频降噪需设置为优先保证画质（AgoraVideoDenoiserLevelHighQuality）和自动模式（AgoraVideoDenoiserModeAuto）。
  • 当暗光增强设置为手动模式（AgoraLowlightEnhanceModeManual）时，视频降噪需设置为优先保证画质（AgoraVideoDenoiserLevelHighQuality）和手动模式（AgoraVideoDenoiserModeManual）。

适用场景

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

调用时机

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

参数

enable

是否开启暗光增强功能：

• YES：开启暗光增强。
• NO：（默认）关闭暗光增强。

options

暗光增强选项，详见 AgoraLowlightEnhanceOptions。

返回值

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

所属接口类

• AgoraRtcEngineKit

setLowlightEnhanceOptions:options:sourceType:

设置低光增强选项并指定媒体源。

Objective-C

- (int)setLowlightEnhanceOptions:(BOOL)enable options:(AgoraLowlightEnhanceOptions* _Nullable)options sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(setLowlightEnhanceOptions(_:options:sourceType:));

自从

自 v4.0.0 版本新增。

该方法与 setLowlightEnhanceOptions:options: 方法都用于设置低光增强选项，但该方法允许你指定应用低光增强选项的媒体源类型。

信息

• 该方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果删除该动态库，该功能将无法正常启用。
• 视频降噪对设备性能有一定要求。如果你在启用视频降噪后设备出现过热，声网建议你将视频降噪选项调整为较低的性能消耗等级，或完全关闭视频降噪功能。

适用场景

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

调用时机

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

参数

enable

是否启用低光增强：

• YES：启用低光增强。
• NO：（默认）关闭低光增强。

options

低光增强选项，详见 AgoraLowlightEnhanceOptions。

sourceType

应用滤镜效果的媒体源类型，详见 AgoraMediaSourceType。 注意：在该方法中，该参数仅支持以下两种设置：

• 默认值为 AgoraMediaSourceTypePrimaryCamera。
• 如果你使用自定义视频源，请将该参数设置为 AgoraMediaSourceTypeCustomVideo。

返回值

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

所属接口类

• AgoraRtcEngineKit

setVideoDenoiserOptions:options:

设置视频降噪功能。

Objective-C

- (int)setVideoDenoiserOptions:(BOOL)enable options:(AgoraVideoDenoiserOptions* _Nullable)options  NS_SWIFT_NAME(setVideoDenoiserOptions(_:options:));

自从

自 v4.0.0 版本新增。

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

信息

• 此方法依赖图像增强动态库 AgoraClearVisionExtension.xcframework（iOS）或 AgoraClearVisionExtension.framework（macOS）。如果该动态库被删除，则无法正常启用该功能。
• 视频降噪对设备性能有一定要求。如果启用视频降噪后设备过热，声网建议将视频降噪选项设置为较低的性能消耗等级，或完全关闭视频降噪功能。
• 如果该方法实现的视频降噪效果无法满足你的需求，声网建议调用 setBeautyEffectOptions:options: 方法启用美颜和磨皮功能，以获得更好的视频降噪效果。推荐用于强降噪效果的 AgoraBeautyOptions 设置如下：
  • lighteningContrastLevel: AgoraLighteningContrastNormal
  • lighteningLevel: 0.0
  • smoothnessLevel: 0.5
  • rednessLevel: 0.0
  • sharpnessLevel: 0.1

适用场景

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

调用时机

请在调用 enableVideo 方法之后调用此方法。

参数

enable

是否启用视频降噪功能：

• YES：启用视频降噪。
• NO：（默认）关闭视频降噪。

options

视频降噪选项，详见 AgoraVideoDenoiserOptions。

返回值

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

所属接口类

• AgoraRtcEngineKit

setVideoDenoiserOptions:options:sourceType:

设置视频降噪并指定媒体源。

Objective-C

- (int)setVideoDenoiserOptions:(BOOL)enable options:(AgoraVideoDenoiserOptions* _Nullable)options sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(setVideoDenoiserOptions(_:options:sourceType:));

自从

自 v4.0.0 版本新增。

你可以调用此方法启用视频降噪功能并设置视频降噪效果的选项。此方法与 setVideoDenoiserOptions:options: 都可设置视频降噪，但此方法允许你指定应用降噪的媒体源类型。

信息

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

适用场景

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

调用时机

请在调用 enableVideo 方法之后调用此方法。

参数

enable

是否启用视频降噪功能：

• YES：启用视频降噪。
• NO：（默认）关闭视频降噪。

options

视频降噪选项。详见 AgoraVideoDenoiserOptions。

sourceType

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

• 默认值为 AgoraMediaSourceTypePrimaryCamera。
• 如果你使用自定义视频源，请将该参数设置为 AgoraMediaSourceTypeCustomVideo。

返回值

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

所属接口类

• AgoraRtcEngineKit

setVideoEffectBoolParamWithOption:key:boolValue:

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

Objective-C

- (int)setVideoEffectBoolParamWithOption:(NSString *)option
                                    key:(NSString *)key
                              boolValue:(BOOL)boolValue
NS_SWIFT_NAME(setVideoEffectBoolParam(option:key:boolValue:));

自从

自 v4.6.0 版本新增。

参数

option

参数选项的类别。

key

参数的键名。

boolValue

要设置的布尔值。

• YES：设置为启用。
• NO：设置为禁用。

返回值

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

所属接口类

• AgoraVideoEffectObject

setVideoEffectFloatParamWithOption:key:floatValue:

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

Objective-C

- (int)setVideoEffectFloatParamWithOption:(NSString *)option
                                    key:(NSString *)key
                              floatValue:(float)floatValue
NS_SWIFT_NAME(setVideoEffectFloatParam(option:key:floatValue:));

自从

自 v4.6.0 版本新增。

参数

option

参数选项的类别。

key

参数的键名。

floatValue

要设置的浮点值。

返回值

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

所属接口类

• AgoraVideoEffectObject

setVideoEffectIntParamWithOption:key:intValue:

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

Objective-C

- (int)setVideoEffectIntParamWithOption:(NSString *)option
                                    key:(NSString *)key
                               intValue:(int)intValue
NS_SWIFT_NAME(setVideoEffectIntParam(option:key:intValue:));

自从

自 v4.6.0 版本新增。

参数

option

参数选项的类别。

key

参数的键名。

intValue

要设置的整数值。

返回值

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

所属接口类

• AgoraVideoEffectObject