# 视频增强 (/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_video_enhance_option"></a>

<a id="api_ivideoeffectobject_addorupdatevideoeffect"></a>

<a id="ariaid-title2"></a>

## addOrUpdateVideoEffectWithNodeId\:templateName: [#addorupdatevideoeffectwithnodeidtemplatename]

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

<a id="api_ivideoeffectobject_addorupdatevideoeffect__prototype"></a>

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

<a id="api_ivideoeffectobject_addorupdatevideoeffect__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

:::note
注： 优先级规则：

- 风格妆节点 `AgoraVideoEffectNodeStyleMakeup` 的优先级高于滤镜特效 `AgoraVideoEffectNodeFilter` 节点。
- 若要应用滤镜特效，必须先移除风格妆特效节点：

```text
[self removeVideoEffectWithNodeId:AgoraVideoEffectNodeStyleMakeup];
[self addOrUpdateVideoEffectWithNodeId:AgoraVideoEffectNodeFilter templateName:@"template name"];
```
:::

<a id="api_ivideoeffectobject_addorupdatevideoeffect__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="nodeid"></a>
<Parameter name="nodeId">

视频特效节点的唯一标识符或标识符组合。例如：

- 单个特效：`AgoraVideoEffectNodeBeauty`。
- 组合特效：`AgoraVideoEffectNodeBeauty ｜ AgoraVideoEffectNodeStyleMakeup ｜ AgoraVideoEffectNodeFilter`。

</Parameter>
<a id="templatename"></a>
<Parameter name="templateName">

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

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_addorupdatevideoeffect__return_values"></a>

### 返回值 [#返回值]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_irtcengine_createvideoeffectobject"></a>

<a id="ariaid-title3"></a>

## createVideoEffectObjectWithBundlePath\:sourceType: [#createvideoeffectobjectwithbundlepathsourcetype]

创建一个视频特效对象。

<a id="api_irtcengine_createvideoeffectobject__prototype"></a>

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

<a id="api_irtcengine_createvideoeffectobject__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

返回一个 [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject) 视频特效对象的指针。

<a id="api_irtcengine_createvideoeffectobject__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="bundlepath"></a>
<Parameter name="bundlePath">

视频特效 bundle 的路径。

</Parameter>
<a id="sourcetype"></a>
<Parameter name="sourceType">

媒体源类型，例如 `AgoraMediaSourceTypePrimaryCamera`。详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_createvideoeffectobject__return_values"></a>

### 返回值 [#返回值-1]

- 方法调用成功，返回 [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject) 对象，详见 [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)。
- 方法调用失败，返回 nil。

### 所属接口类 [#所属接口类-1]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_destroyvideoeffectobject"></a>

<a id="ariaid-title4"></a>

## destroyVideoEffectObject: [#destroyvideoeffectobject]

销毁一个视频特效对象。

<a id="api_irtcengine_destroyvideoeffectobject__prototype"></a>

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

<a id="api_irtcengine_destroyvideoeffectobject__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_irtcengine_destroyvideoeffectobject__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="videoeffectobject"></a>
<Parameter name="videoEffectObject">

要销毁的 [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject) 实例的指针。详见 [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_destroyvideoeffectobject__return_values"></a>

### 返回值 [#返回值-2]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-2]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getfaceshapeareaoptions"></a>

<a id="ariaid-title5"></a>

## getFaceShapeAreaOptions\:sourceType: [#getfaceshapeareaoptionssourcetype]

获取美型区域的选项。

<a id="api_irtcengine_getfaceshapeareaoptions__prototype"></a>

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

<a id="api_irtcengine_getfaceshapeareaoptions__detailed_desc"></a>

<a id="api_irtcengine_getfaceshapeareaoptions__scenario"></a>

### 适用场景 [#适用场景]

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

<a id="api_irtcengine_getfaceshapeareaoptions__timing"></a>

### 调用时机 [#调用时机]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 之后调用此方法。

<a id="api_irtcengine_getfaceshapeareaoptions__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="area"></a>
<Parameter name="area">

美型增强区域。详见 [AgoraFaceShapeArea](/zh-CN/api-reference/rtc/ios/enum-faceshapearea)。

</Parameter>
<a id="sourcetype-1"></a>
<Parameter name="sourceType">

应用滤镜特效的媒体源类型。详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_getfaceshapeareaoptions__return_values"></a>

### 返回值 [#返回值-3]

方法调用成功，返回 [AgoraFaceShapeAreaOptions](/zh-CN/api-reference/rtc/ios/class-faceshapeareaoptions) 对象。
方法调用失败，返回 nil。

### 所属接口类 [#所属接口类-3]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getfaceshapeareaoptions2"></a>

<a id="ariaid-title6"></a>

## getFaceShapeAreaOptions: [#getfaceshapeareaoptions]

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

<a id="api_irtcengine_getfaceshapeareaoptions2__prototype"></a>

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

<a id="api_irtcengine_getfaceshapeareaoptions2__detailed_desc"></a>

<a id="api_irtcengine_getfaceshapeareaoptions2__scenario"></a>

### 适用场景 [#适用场景-1]

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

<a id="api_irtcengine_getfaceshapeareaoptions2__timing"></a>

### 调用时机 [#调用时机-1]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 之后调用此方法。

<a id="api_irtcengine_getfaceshapeareaoptions2__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="area-1"></a>
<Parameter name="area">

美型增强区域。参见 [AgoraFaceShapeArea](/zh-CN/api-reference/rtc/ios/enum-faceshapearea)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_getfaceshapeareaoptions2__return_values"></a>

### 返回值 [#返回值-4]

方法调用成功，返回 [AgoraFaceShapeAreaOptions](/zh-CN/api-reference/rtc/ios/class-faceshapeareaoptions) 对象。
方法调用失败，返回 nil。

### 所属接口类 [#所属接口类-4]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getfaceshapebeautyoptions"></a>

<a id="ariaid-title7"></a>

## getFaceShapeBeautyOptions: [#getfaceshapebeautyoptions]

获取美颜特效选项。

<a id="api_irtcengine_getfaceshapebeautyoptions__prototype"></a>

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

<a id="api_irtcengine_getfaceshapebeautyoptions__detailed_desc"></a>

<a id="api_irtcengine_getfaceshapebeautyoptions__scenario"></a>

### 适用场景 [#适用场景-2]

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

<a id="api_irtcengine_getfaceshapebeautyoptions__timing"></a>

### 调用时机 [#调用时机-2]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 后调用此方法。

<a id="api_irtcengine_getfaceshapebeautyoptions__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="sourcetype-2"></a>
<Parameter name="sourceType">

应用滤镜特效的媒体源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。在此方法中，该参数仅支持以下两种设置：

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_getfaceshapebeautyoptions__return_values"></a>

### 返回值 [#返回值-5]

- 方法调用成功，返回 [AgoraFaceShapeBeautyOptions](/zh-CN/api-reference/rtc/ios/class-faceshapebeautyoptions) 对象，详见 [AgoraFaceShapeBeautyOptions](/zh-CN/api-reference/rtc/ios/class-faceshapebeautyoptions)。
- 方法调用失败，返回 nil。

### 所属接口类 [#所属接口类-5]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getfaceshapebeautyoptions2"></a>

<a id="ariaid-title8"></a>

## getFaceShapeBeautyOptions [#getfaceshapebeautyoptions-1]

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

<a id="api_irtcengine_getfaceshapebeautyoptions2__prototype"></a>

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

<a id="api_irtcengine_getfaceshapebeautyoptions2__detailed_desc"></a>

<a id="api_irtcengine_getfaceshapebeautyoptions2__scenario"></a>

### 适用场景 [#适用场景-3]

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

<a id="api_irtcengine_getfaceshapebeautyoptions2__timing"></a>

### 调用时机 [#调用时机-3]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用该方法。

<a id="api_irtcengine_getfaceshapebeautyoptions2__return_values"></a>

### 返回值 [#返回值-6]

- 方法调用成功，返回 [AgoraFaceShapeBeautyOptions](/zh-CN/api-reference/rtc/ios/class-faceshapebeautyoptions) 对象。
- 方法调用失败，返回 nil。

### 所属接口类 [#所属接口类-6]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_ivideoeffectobject_getvideoeffectboolparam"></a>

<a id="ariaid-title9"></a>

## getVideoEffectBoolParamWithOption\:key: [#getvideoeffectboolparamwithoptionkey]

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

<a id="api_ivideoeffectobject_getvideoeffectboolparam__prototype"></a>

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

<a id="api_ivideoeffectobject_getvideoeffectboolparam__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_ivideoeffectobject_getvideoeffectboolparam__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="option"></a>
<Parameter name="option">

参数类别的标识符。

</Parameter>
<a id="key"></a>
<Parameter name="key">

参数的键值。

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_getvideoeffectboolparam__return_values"></a>

### 返回值 [#返回值-7]

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

### 所属接口类 [#所属接口类-7]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_ivideoeffectobject_getvideoeffectfloatparam"></a>

<a id="ariaid-title10"></a>

## getVideoEffectFloatParamWithOption\:key: [#getvideoeffectfloatparamwithoptionkey]

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

<a id="api_ivideoeffectobject_getvideoeffectfloatparam__prototype"></a>

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

<a id="api_ivideoeffectobject_getvideoeffectfloatparam__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

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

<a id="api_ivideoeffectobject_getvideoeffectfloatparam__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="option-1"></a>
<Parameter name="option">

参数选项的类别。

</Parameter>
<a id="key-1"></a>
<Parameter name="key">

参数的键名。

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_getvideoeffectfloatparam__return_values"></a>

### 返回值 [#返回值-8]

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

### 所属接口类 [#所属接口类-8]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_ivideoeffectobject_getvideoeffectintparam"></a>

<a id="ariaid-title11"></a>

## getVideoEffectIntParamWithOption\:key: [#getvideoeffectintparamwithoptionkey]

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

<a id="api_ivideoeffectobject_getvideoeffectintparam__prototype"></a>

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

<a id="api_ivideoeffectobject_getvideoeffectintparam__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_ivideoeffectobject_getvideoeffectintparam__parameters"></a>

### 参数 [#参数-8]

<ParameterList>
<a id="option-2"></a>
<Parameter name="option">

参数类别的标识符。

</Parameter>
<a id="key-2"></a>
<Parameter name="key">

参数的键值。

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_getvideoeffectintparam__return_values"></a>

### 返回值 [#返回值-9]

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

### 所属接口类 [#所属接口类-9]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_ivideoeffectobject_performvideoeffectaction"></a>

<a id="ariaid-title12"></a>

## performVideoEffectActionWithNodeId\:actionId: [#performvideoeffectactionwithnodeidactionid]

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

<a id="api_ivideoeffectobject_performvideoeffectaction__prototype"></a>

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

<a id="api_ivideoeffectobject_performvideoeffectaction__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_ivideoeffectobject_performvideoeffectaction__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="nodeid-1"></a>
<Parameter name="nodeId">

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

</Parameter>
<a id="actionid"></a>
<Parameter name="actionId">

要执行的操作，详见 [AgoraVideoEffectAction](/zh-CN/api-reference/rtc/ios/enum-videoeffectaction)。

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_performvideoeffectaction__return_values"></a>

### 返回值 [#返回值-10]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-10]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_ivideoeffectobject_removevideoeffect"></a>

<a id="ariaid-title13"></a>

## removeVideoEffectWithNodeId: [#removevideoeffectwithnodeid]

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

<a id="api_ivideoeffectobject_removevideoeffect__prototype"></a>

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

<a id="api_ivideoeffectobject_removevideoeffect__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_ivideoeffectobject_removevideoeffect__parameters"></a>

### 参数 [#参数-10]

<ParameterList>
<a id="nodeid-2"></a>
<Parameter name="nodeId">

要移除的视频特效节点的唯一标识符。详见 [AgoraVideoEffectNodeId](/zh-CN/api-reference/rtc/ios/enum-videoeffectnodeid)。

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_removevideoeffect__return_values"></a>

### 返回值 [#返回值-11]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-11]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_irtcengine_setbeautyeffectoptions"></a>

<a id="ariaid-title14"></a>

## setBeautyEffectOptions\:options: [#setbeautyeffectoptionsoptions]

设置美颜特效选项。

<a id="api_irtcengine_setbeautyeffectoptions__prototype"></a>

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

<a id="api_irtcengine_setbeautyeffectoptions__detailed_desc"></a>

你可以通过该方法启用或禁用美颜特效功能，并设置相关选项。请在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 或 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 方法之后调用本方法。

:::note
注：

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

<a id="api_irtcengine_setbeautyeffectoptions__timing"></a>

### 调用时机 [#调用时机-4]

请在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 或 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 方法之后调用本方法。

<a id="api_irtcengine_setbeautyeffectoptions__parameters"></a>

### 参数 [#参数-11]

<ParameterList>
<a id="enable"></a>
<Parameter name="enable">

是否启用美颜特效功能：

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

</Parameter>
<a id="options"></a>
<Parameter name="options">

美颜特效选项，详见 [AgoraBeautyOptions](/zh-CN/api-reference/rtc/ios/class-beautyoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setbeautyeffectoptions__return_values"></a>

### 返回值 [#返回值-12]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -4：当前设备不支持该功能。可能的原因包括：

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

### 所属接口类 [#所属接口类-12]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setbeautyeffectoptions2"></a>

<a id="ariaid-title15"></a>

## setBeautyEffectOptions\:options\:sourceType: [#setbeautyeffectoptionsoptionssourcetype]

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

<a id="api_irtcengine_setbeautyeffectoptions2__prototype"></a>

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

<a id="api_irtcengine_setbeautyeffectoptions2__detailed_desc"></a>

该方法与 [setBeautyEffectOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 都用于设置美颜特效选项，但该方法允许你指定应用美颜特效的媒体源。

<a id="api_irtcengine_setbeautyeffectoptions2__timing"></a>

### 调用时机 [#调用时机-5]

请在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 或 [startPreview:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 之后调用该方法。

<a id="api_irtcengine_setbeautyeffectoptions2__parameters"></a>

### 参数 [#参数-12]

<ParameterList>
<a id="enable-1"></a>
<Parameter name="enable">

是否启用美颜特效功能：

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

</Parameter>
<a id="options-1"></a>
<Parameter name="options">

美颜特效选项。详见 [AgoraBeautyOptions](/zh-CN/api-reference/rtc/ios/class-beautyoptions)。

</Parameter>
<a id="sourcetype-3"></a>
<Parameter name="sourceType">

媒体源类型。详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。

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

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setbeautyeffectoptions2__return_values"></a>

### 返回值 [#返回值-13]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -4：当前设备不支持该功能。可能的原因包括：

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

### 所属接口类 [#所属接口类-13]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setcolorenhanceoptions"></a>

<a id="ariaid-title16"></a>

## setColorEnhanceOptions\:options: [#setcolorenhanceoptionsoptions]

设置色彩增强效果。

<a id="api_irtcengine_setcolorenhanceoptions__prototype"></a>

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

<a id="api_irtcengine_setcolorenhanceoptions__detailed_desc"></a>

:::info[自从]
自 v4.0.0 版本新增。
:::

摄像头采集的视频图像可能存在色彩失真。色彩增强功能可智能调整视频的饱和度和对比度等特性，从而增强视频的色彩丰富度和色彩还原度，使视频画面更加生动。你可以调用 [setColorEnhanceOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions) 方法开启色彩增强功能并设置色彩增强效果的参数。

:::note
注：

- 请在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用此方法。
- 色彩增强功能对设备性能有一定要求。开启色彩增强后，如果设备出现严重发热问题，声网建议你降低色彩增强等级以减少性能消耗，或关闭色彩增强功能。
- 此方法依赖美颜特效动态库 AgoraClearVisionExtension.xcframework（iOS）或 `AgoraClearVisionExtension.framework`（macOS）。如果该动态库被删除，则无法正常启用该功能。
:::

<a id="api_irtcengine_setcolorenhanceoptions__parameters"></a>

### 参数 [#参数-13]

<ParameterList>
<a id="enable-2"></a>
<Parameter name="enable">

是否开启色彩增强功能：

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

</Parameter>
<a id="options-2"></a>
<Parameter name="options">

色彩增强参数，详见 [AgoraColorEnhanceOptions](/zh-CN/api-reference/rtc/ios/class-colorenhanceoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcolorenhanceoptions__return_values"></a>

### 返回值 [#返回值-14]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-14]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setcolorenhanceoptions2"></a>

<a id="ariaid-title17"></a>

## setColorEnhanceOptions\:options\:sourceType: [#setcolorenhanceoptionsoptionssourcetype]

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

<a id="api_irtcengine_setcolorenhanceoptions2__prototype"></a>

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

<a id="api_irtcengine_setcolorenhanceoptions2__detailed_desc"></a>

:::info[自从]
自 v4.0.0 版本新增。
:::

摄像头采集的视频图像可能存在色彩失真。色彩增强功能可智能调整视频的饱和度和对比度等特性，从而增强视频的色彩丰富度和色彩还原度，使视频画面更加生动。该方法与 [setColorEnhanceOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions) 方法类似，但该方法允许你指定应用色彩增强选项的媒体源。

:::note
注：

- 请在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用此方法。
- 色彩增强功能对设备性能有一定要求。开启色彩增强功能后，如果设备出现严重发热问题，声网建议你降低色彩增强等级以减少性能消耗，或关闭色彩增强功能。
- 此方法依赖美颜特效动态库 AgoraClearVisionExtension.xcframework（iOS）或 `AgoraClearVisionExtension.framework`（macOS）。如果该动态库被删除，则无法正常启用该功能。
:::

<a id="api_irtcengine_setcolorenhanceoptions2__parameters"></a>

### 参数 [#参数-14]

<ParameterList>
<a id="enable-3"></a>
<Parameter name="enable">

是否开启色彩增强功能：

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

</Parameter>
<a id="options-3"></a>
<Parameter name="options">

色彩增强选项，详见 [AgoraColorEnhanceOptions](/zh-CN/api-reference/rtc/ios/class-colorenhanceoptions)。

</Parameter>
<a id="sourcetype-4"></a>
<Parameter name="sourceType">

媒体源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setcolorenhanceoptions2__return_values"></a>

### 返回值 [#返回值-15]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-15]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setfaceshapeareaoptions"></a>

<a id="ariaid-title18"></a>

## setFaceShapeAreaOptions\:sourceType: [#setfaceshapeareaoptionssourcetype]

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

<a id="api_irtcengine_setfaceshapeareaoptions__prototype"></a>

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

<a id="api_irtcengine_setfaceshapeareaoptions__detailed_desc"></a>

如果通过 [setFaceShapeBeautyOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions2) 方法实现的预设美型效果不符合预期，你可以使用此方法设置美颜区域选项，单独微调面部的每个部分，从而实现更精细的美颜效果。

:::note
注：

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

<a id="api_irtcengine_setfaceshapeareaoptions__timing"></a>

### 调用时机 [#调用时机-6]

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

<a id="api_irtcengine_setfaceshapeareaoptions__parameters"></a>

### 参数 [#参数-15]

<ParameterList>
<a id="options-4"></a>
<Parameter name="options">

面部增强区域，详见 [AgoraFaceShapeAreaOptions](/zh-CN/api-reference/rtc/ios/class-faceshapeareaoptions)。

</Parameter>
<a id="sourcetype-5"></a>
<Parameter name="sourceType">

媒体源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setfaceshapeareaoptions__return_values"></a>

### 返回值 [#返回值-16]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -4：当前设备不支持此功能。可能原因包括：

    - 当前设备的能力不满足美颜特效的要求。声网建议你更换为高性能设备。

### 所属接口类 [#所属接口类-16]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setfaceshapeareaoptions2"></a>

<a id="ariaid-title19"></a>

## setFaceShapeAreaOptions: [#setfaceshapeareaoptions]

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

<a id="api_irtcengine_setfaceshapeareaoptions2__prototype"></a>

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

<a id="api_irtcengine_setfaceshapeareaoptions2__detailed_desc"></a>

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

:::note
注：

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

<a id="api_irtcengine_setfaceshapeareaoptions2__timing"></a>

### 调用时机 [#调用时机-7]

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

<a id="api_irtcengine_setfaceshapeareaoptions2__parameters"></a>

### 参数 [#参数-16]

<ParameterList>
<a id="options-5"></a>
<Parameter name="options">

面部增强区域。详见 [AgoraFaceShapeAreaOptions](/zh-CN/api-reference/rtc/ios/class-faceshapeareaoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setfaceshapeareaoptions2__return_values"></a>

### 返回值 [#返回值-17]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -4：当前设备不支持此功能。可能的原因包括：

    - 当前设备的能力不满足美颜特效的要求。声网建议你更换为高性能设备。

### 所属接口类 [#所属接口类-17]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setfaceshapebeautyoptions"></a>

<a id="ariaid-title20"></a>

## setFaceShapeBeautyOptions\:options\:sourceType: [#setfaceshapebeautyoptionsoptionssourcetype]

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

<a id="api_irtcengine_setfaceshapebeautyoptions__prototype"></a>

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

<a id="api_irtcengine_setfaceshapebeautyoptions__detailed_desc"></a>

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

:::note
注：

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

<a id="api_irtcengine_setfaceshapebeautyoptions__timing"></a>

### 调用时机 [#调用时机-8]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 后调用该方法。

<a id="api_irtcengine_setfaceshapebeautyoptions__parameters"></a>

### 参数 [#参数-17]

<ParameterList>
<a id="enable-4"></a>
<Parameter name="enable">

是否开启美型特效：

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

</Parameter>
<a id="options-6"></a>
<Parameter name="options">

美型风格选项，详见 [AgoraFaceShapeBeautyOptions](/zh-CN/api-reference/rtc/ios/class-faceshapebeautyoptions)。

</Parameter>
<a id="sourcetype-6"></a>
<Parameter name="sourceType">

要应用滤镜特效的媒体源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setfaceshapebeautyoptions__return_values"></a>

### 返回值 [#返回值-18]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -4：当前设备不支持该功能。可能原因包括：

    - 当前设备能力不满足美颜特效要求。声网建议你更换为高性能设备。

### 所属接口类 [#所属接口类-18]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setfaceshapebeautyoptions2"></a>

<a id="ariaid-title21"></a>

## setFaceShapeBeautyOptions\:options: [#setfaceshapebeautyoptionsoptions]

设置美型选项。

<a id="api_irtcengine_setfaceshapebeautyoptions2__prototype"></a>

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

<a id="api_irtcengine_setfaceshapebeautyoptions2__detailed_desc"></a>

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

:::note
注：

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

<a id="api_irtcengine_setfaceshapebeautyoptions2__timing"></a>

### 调用时机 [#调用时机-9]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用。

<a id="api_irtcengine_setfaceshapebeautyoptions2__parameters"></a>

### 参数 [#参数-18]

<ParameterList>
<a id="enable-5"></a>
<Parameter name="enable">

是否启用美型效果：

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

</Parameter>
<a id="options-7"></a>
<Parameter name="options">

美型风格选项，详见 [AgoraFaceShapeBeautyOptions](/zh-CN/api-reference/rtc/ios/class-faceshapebeautyoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setfaceshapebeautyoptions2__return_values"></a>

### 返回值 [#返回值-19]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -4：当前设备不支持此功能。可能的原因包括：

    - 当前设备的美颜特效能力不满足要求。声网建议你更换为高性能设备。

### 所属接口类 [#所属接口类-19]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setfiltereffectoptions"></a>

<a id="ariaid-title22"></a>

## setFilterEffectOptions\:options\:sourceType: [#setfiltereffectoptionsoptionssourcetype]

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

<a id="api_irtcengine_setfiltereffectoptions__prototype"></a>

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

<a id="api_irtcengine_setfiltereffectoptions__detailed_desc"></a>

:::info[自从]
自 v4.4.1 版本新增。
:::

该方法与 [setBeautyEffectOptions\:options\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions2) 方法都用于设置滤镜特效参数。不同之处在于，该方法允许你指定滤镜特效应用的媒体源。

:::note
注：

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

<a id="api_irtcengine_setfiltereffectoptions__timing"></a>

### 调用时机 [#调用时机-10]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 后调用该方法。

<a id="api_irtcengine_setfiltereffectoptions__parameters"></a>

### 参数 [#参数-19]

<ParameterList>
<a id="enable-6"></a>
<Parameter name="enable">

是否启用滤镜特效：

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

</Parameter>
<a id="options-8"></a>
<Parameter name="options">

滤镜特效参数，详见 [AgoraFilterEffectOptions](/zh-CN/api-reference/rtc/ios/class-filtereffectoptions)。

</Parameter>
<a id="sourcetype-7"></a>
<Parameter name="sourceType">

滤镜特效应用的媒体源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setfiltereffectoptions__return_values"></a>

### 返回值 [#返回值-20]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-20]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setfiltereffectoptions2"></a>

<a id="ariaid-title23"></a>

## setFilterEffectOptions\:options: [#setfiltereffectoptionsoptions]

设置滤镜特效选项。

<a id="api_irtcengine_setfiltereffectoptions2__prototype"></a>

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

<a id="api_irtcengine_setfiltereffectoptions2__detailed_desc"></a>

:::info[自从]
自 v4.4.1 版本新增。
:::

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用本方法。

:::note
注：

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

<a id="api_irtcengine_setfiltereffectoptions2__timing"></a>

### 调用时机 [#调用时机-11]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用。

<a id="api_irtcengine_setfiltereffectoptions2__parameters"></a>

### 参数 [#参数-20]

<ParameterList>
<a id="enable-7"></a>
<Parameter name="enable">

是否启用滤镜特效：

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

</Parameter>
<a id="options-9"></a>
<Parameter name="options">

滤镜特效选项，详见 [AgoraFilterEffectOptions](/zh-CN/api-reference/rtc/ios/class-filtereffectoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setfiltereffectoptions2__return_values"></a>

### 返回值 [#返回值-21]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-21]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlowlightenhanceoptions"></a>

<a id="ariaid-title24"></a>

## setLowlightEnhanceOptions\:options: [#setlowlightenhanceoptionsoptions]

设置暗光增强功能。

<a id="api_irtcengine_setlowlightenhanceoptions__prototype"></a>

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

<a id="api_irtcengine_setlowlightenhanceoptions__detailed_desc"></a>

:::info[自从]
自 v4.0.0 版本新增。
:::

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

:::note
注：

- 此方法依赖美颜特效动态库 AgoraClearVisionExtension.xcframework（iOS）或 `AgoraClearVisionExtension.framework`（macOS）。如果该动态库被删除，则无法正常启用该功能。
- 暗光增强对设备性能有一定要求。如果启用暗光增强后设备出现过热，声网建议将暗光增强选项设置为较低的性能消耗等级，或完全关闭暗光增强功能。
- 如果你希望在使用暗光增强功能时优先保证画质（`AgoraLowlightEnhanceLevelQuality`），需要先调用 [setVideoDenoiserOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 实现视频降噪，具体对应关系如下：

  - 当暗光增强设置为自动模式（`AgoraLowlightEnhanceModeAuto`）时，视频降噪需设置为优先保证画质（`AgoraVideoDenoiserLevelHighQuality`）和自动模式（`AgoraVideoDenoiserModeAuto`）。
  - 当暗光增强设置为手动模式（`AgoraLowlightEnhanceModeManual`）时，视频降噪需设置为优先保证画质（`AgoraVideoDenoiserLevelHighQuality`）和手动模式（`AgoraVideoDenoiserModeManual`）。
:::

<a id="api_irtcengine_setlowlightenhanceoptions__scenario"></a>

### 适用场景 [#适用场景-4]

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

<a id="api_irtcengine_setlowlightenhanceoptions__timing"></a>

### 调用时机 [#调用时机-12]

在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 之后调用此方法。

<a id="api_irtcengine_setlowlightenhanceoptions__parameters"></a>

### 参数 [#参数-21]

<ParameterList>
<a id="enable-8"></a>
<Parameter name="enable">

是否开启暗光增强功能：

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

</Parameter>
<a id="options-10"></a>
<Parameter name="options">

暗光增强选项，详见 [AgoraLowlightEnhanceOptions](/zh-CN/api-reference/rtc/ios/class-lowlightenhanceoptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlowlightenhanceoptions__return_values"></a>

### 返回值 [#返回值-22]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-22]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setlowlightenhanceoptions2"></a>

<a id="ariaid-title25"></a>

## setLowlightEnhanceOptions\:options\:sourceType: [#setlowlightenhanceoptionsoptionssourcetype]

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

<a id="api_irtcengine_setlowlightenhanceoptions2__prototype"></a>

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

<a id="api_irtcengine_setlowlightenhanceoptions2__detailed_desc"></a>

:::info[自从]
自 v4.0.0 版本新增。
:::

该方法与 [setLowlightEnhanceOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions) 方法都用于设置低光增强选项，但该方法允许你指定应用低光增强选项的媒体源类型。

:::note
注：

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

<a id="api_irtcengine_setlowlightenhanceoptions2__scenario"></a>

### 适用场景 [#适用场景-5]

适用于黑暗环境或低端视频采集设备导致图像噪点较多的场景。在实时互动中，图像噪点会占用码流资源，降低编码效率。

<a id="api_irtcengine_setlowlightenhanceoptions2__timing"></a>

### 调用时机 [#调用时机-13]

请在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用本方法。

<a id="api_irtcengine_setlowlightenhanceoptions2__parameters"></a>

### 参数 [#参数-22]

<ParameterList>
<a id="enable-9"></a>
<Parameter name="enable">

是否启用低光增强：

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

</Parameter>
<a id="options-11"></a>
<Parameter name="options">

低光增强选项，详见 [AgoraLowlightEnhanceOptions](/zh-CN/api-reference/rtc/ios/class-lowlightenhanceoptions)。

</Parameter>
<a id="sourcetype-8"></a>
<Parameter name="sourceType">

媒体源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。
注意：在该方法中，该参数仅支持以下两种设置：

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setlowlightenhanceoptions2__return_values"></a>

### 返回值 [#返回值-23]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-23]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setvideodenoiseroptions"></a>

<a id="ariaid-title26"></a>

## setVideoDenoiserOptions\:options: [#setvideodenoiseroptionsoptions]

设置视频降噪功能。

<a id="api_irtcengine_setvideodenoiseroptions__prototype"></a>

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

<a id="api_irtcengine_setvideodenoiseroptions__detailed_desc"></a>

:::info[自从]
自 v4.0.0 版本新增。
:::

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

:::note
注：

- 此方法依赖美颜特效动态库 AgoraClearVisionExtension.xcframework（iOS）或 `AgoraClearVisionExtension.framework`（macOS）。如果该动态库被删除，则无法正常启用该功能。
- 视频降噪对设备性能有一定要求。如果启用视频降噪后设备过热，声网建议将视频降噪选项设置为较低的性能消耗等级，或完全关闭视频降噪功能。
- 如果该方法实现的视频降噪效果无法满足你的需求，声网建议调用 [setBeautyEffectOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜和磨皮功能，以获得更好的视频降噪效果。推荐用于强降噪效果的 [AgoraBeautyOptions](/zh-CN/api-reference/rtc/ios/class-beautyoptions) 设置如下：

  - `lighteningContrastLevel`: `AgoraLighteningContrastNormal`
  - `lighteningLevel`: 0.0
  - `smoothnessLevel`: 0.5
  - `rednessLevel`: 0.0
  - `sharpnessLevel`: 0.1
:::

<a id="api_irtcengine_setvideodenoiseroptions__scenario"></a>

### 适用场景 [#适用场景-6]

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

<a id="api_irtcengine_setvideodenoiseroptions__timing"></a>

### 调用时机 [#调用时机-14]

请在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用此方法。

<a id="api_irtcengine_setvideodenoiseroptions__parameters"></a>

### 参数 [#参数-23]

<ParameterList>
<a id="enable-10"></a>
<Parameter name="enable">

是否启用视频降噪功能：

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

</Parameter>
<a id="options-12"></a>
<Parameter name="options">

视频降噪选项，详见 [AgoraVideoDenoiserOptions](/zh-CN/api-reference/rtc/ios/class-videodenoiseroptions)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setvideodenoiseroptions__return_values"></a>

### 返回值 [#返回值-24]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-24]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setvideodenoiseroptions2"></a>

<a id="ariaid-title27"></a>

## setVideoDenoiserOptions\:options\:sourceType: [#setvideodenoiseroptionsoptionssourcetype]

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

<a id="api_irtcengine_setvideodenoiseroptions2__prototype"></a>

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

<a id="api_irtcengine_setvideodenoiseroptions2__detailed_desc"></a>

:::info[自从]
自 v4.0.0 版本新增。
:::

你可以调用此方法启用视频降噪功能并设置视频降噪效果的选项。此方法与 [setVideoDenoiserOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 都可设置视频降噪，但此方法允许你指定应用降噪的媒体源类型。

:::note
注：

- 此方法依赖美颜特效动态库 AgoraClearVisionExtension.xcframework（iOS）或 `AgoraClearVisionExtension.framework`（macOS）。如果该动态库被删除，则无法正常启用该功能。
- 视频降噪对设备性能有一定要求。如果启用视频降噪后设备出现过热情况，声网建议你将视频降噪选项设置为较低的性能消耗等级，或完全关闭视频降噪功能。
- 如果该方法实现的视频降噪效果无法满足你的需求，声网建议你调用 [setBeautyEffectOptions\:options:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜和磨皮功能，以获得更好的视频降噪效果。推荐用于强降噪效果的 [AgoraBeautyOptions](/zh-CN/api-reference/rtc/ios/class-beautyoptions) 设置如下：

  - `lighteningContrastLevel`: `AgoraLighteningContrastNormal`
  - `lighteningLevel`: 0.0
  - `smoothnessLevel`: 0.5
  - `rednessLevel`: 0.0
  - `sharpnessLevel`: 0.1
:::

<a id="api_irtcengine_setvideodenoiseroptions2__scenario"></a>

### 适用场景 [#适用场景-7]

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

<a id="api_irtcengine_setvideodenoiseroptions2__timing"></a>

### 调用时机 [#调用时机-15]

请在调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo) 方法之后调用此方法。

<a id="api_irtcengine_setvideodenoiseroptions2__parameters"></a>

### 参数 [#参数-24]

<ParameterList>
<a id="enable-11"></a>
<Parameter name="enable">

是否启用视频降噪功能：

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

</Parameter>
<a id="options-13"></a>
<Parameter name="options">

视频降噪选项。详见 [AgoraVideoDenoiserOptions](/zh-CN/api-reference/rtc/ios/class-videodenoiseroptions)。

</Parameter>
<a id="sourcetype-9"></a>
<Parameter name="sourceType">

媒体源类型。详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype)。

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

</Parameter>
</ParameterList>

<a id="api_irtcengine_setvideodenoiseroptions2__return_values"></a>

### 返回值 [#返回值-25]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-25]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)

<a id="api_ivideoeffectobject_setvideoeffectboolparam"></a>

<a id="ariaid-title28"></a>

## setVideoEffectBoolParamWithOption\:key\:boolValue: [#setvideoeffectboolparamwithoptionkeyboolvalue]

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

<a id="api_ivideoeffectobject_setvideoeffectboolparam__prototype"></a>

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

<a id="api_ivideoeffectobject_setvideoeffectboolparam__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_ivideoeffectobject_setvideoeffectboolparam__parameters"></a>

### 参数 [#参数-25]

<ParameterList>
<a id="option-3"></a>
<Parameter name="option">

参数选项的类别。

</Parameter>
<a id="key-3"></a>
<Parameter name="key">

参数的键名。

</Parameter>
<a id="boolvalue"></a>
<Parameter name="boolValue">

要设置的布尔值。

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

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_setvideoeffectboolparam__return_values"></a>

### 返回值 [#返回值-26]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-26]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_ivideoeffectobject_setvideoeffectfloatparam"></a>

<a id="ariaid-title29"></a>

## setVideoEffectFloatParamWithOption\:key\:floatValue: [#setvideoeffectfloatparamwithoptionkeyfloatvalue]

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

<a id="api_ivideoeffectobject_setvideoeffectfloatparam__prototype"></a>

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

<a id="api_ivideoeffectobject_setvideoeffectfloatparam__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_ivideoeffectobject_setvideoeffectfloatparam__parameters"></a>

### 参数 [#参数-26]

<ParameterList>
<a id="option-4"></a>
<Parameter name="option">

参数选项的类别。

</Parameter>
<a id="key-4"></a>
<Parameter name="key">

参数的键名。

</Parameter>
<a id="floatvalue"></a>
<Parameter name="floatValue">

要设置的浮点值。

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_setvideoeffectfloatparam__return_values"></a>

### 返回值 [#返回值-27]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-27]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_ivideoeffectobject_setvideoeffectintparam"></a>

<a id="ariaid-title30"></a>

## setVideoEffectIntParamWithOption\:key\:intValue: [#setvideoeffectintparamwithoptionkeyintvalue]

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

<a id="api_ivideoeffectobject_setvideoeffectintparam__prototype"></a>

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

<a id="api_ivideoeffectobject_setvideoeffectintparam__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_ivideoeffectobject_setvideoeffectintparam__parameters"></a>

### 参数 [#参数-27]

<ParameterList>
<a id="option-5"></a>
<Parameter name="option">

参数选项的类别。

</Parameter>
<a id="key-5"></a>
<Parameter name="key">

参数的键名。

</Parameter>
<a id="intvalue"></a>
<Parameter name="intValue">

要设置的整数值。

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_setvideoeffectintparam__return_values"></a>

### 返回值 [#返回值-28]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-28]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)

<a id="api_ivideoeffectobject_setvideoeffectstringparam"></a>

<a id="ariaid-title31"></a>

## setVideoEffectStringParamWithOption\:key\:stringValue: [#setvideoeffectstringparamwithoptionkeystringvalue]

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

<a id="api_ivideoeffectobject_setvideoeffectstringparam__prototype"></a>

```objc
- (int)setVideoEffectStringParamWithOption:(NSString *)option
                                      key:(NSString *)key
                              stringValue:(NSString *)stringValue
NS_SWIFT_NAME(setVideoEffectStringParam(option:key:stringValue:));
```

<a id="api_ivideoeffectobject_setvideoeffectstringparam__detailed_desc"></a>

:::info[自从]
自 v4.6.0 版本新增。
:::

<a id="api_ivideoeffectobject_setvideoeffectstringparam__parameters"></a>

### 参数 [#参数-28]

<ParameterList>
<a id="setvideoeffectstringparam-option"></a>
<Parameter name="option">

输入参数，参数选项的类别。

</Parameter>
<a id="setvideoeffectstringparam-key"></a>
<Parameter name="key">

输入参数，参数的键名。

</Parameter>
<a id="setvideoeffectstringparam-stringvalue"></a>
<Parameter name="stringValue">

输入参数，要设置的字符串值。

</Parameter>
</ParameterList>

<a id="api_ivideoeffectobject_setvideoeffectstringparam__return_values"></a>

### 返回值 [#返回值-29]

0：成功。小于 0：失败。

### 所属接口类 [#所属接口类-29]

- [AgoraVideoEffectObject](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject)