# 视频增强 (/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## getFaceShapeAreaOptions [#getfaceshapeareaoptions]
获取美型部位选项。
```cpp
virtual int getFaceShapeAreaOptions(agora::rtc::FaceShapeAreaOptions::FACE_SHAPE_AREA shapeArea, FaceShapeAreaOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
调用该方法可以获取美型部位当前设置的参数信息。
### 适用场景 [#适用场景]
用户在 App 中打开美型部位和修饰力度菜单时,你可以调用该方法获取当前的美型部位选项,然后根据结果刷新用户界面中的菜单,并更新 UI。
### 调用时机 [#调用时机]
请在 [enableVideo](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_enablevideo) 之后调用该方法。
### 调用限制 [#调用限制]
无。
### 参数 [#参数]
美型部位。详见 [FACE_SHAPE_AREA](/zh-CN/api-reference/rtc/unreal-cpp/enum-faceshapearea)。
美型部位选项,详见 [FaceShapeAreaOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-faceshapeareaoptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)
## getFaceShapeBeautyOptions [#getfaceshapebeautyoptions]
获取美型效果选项。
```cpp
virtual int getFaceShapeBeautyOptions(FaceShapeBeautyOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
调用该方法可以获取美型效果当前设置的参数信息。
### 适用场景 [#适用场景-1]
用户在 App 中打开美型风格和风格强度菜单时,你可以调用该方法获取当前的美型效果选项,然后根据结果刷新用户界面中的菜单,并更新 UI。
### 调用时机 [#调用时机-1]
请在 [enableVideo](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_enablevideo) 之后调用该方法。
### 调用限制 [#调用限制-1]
无。
### 参数 [#参数-1]
美型风格选项,详见 [FaceShapeBeautyOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-faceshapebeautyoptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)
## setBeautyEffectOptions [#setbeautyeffectoptions]
设置美颜效果选项。
```cpp
virtual int setBeautyEffectOptions(bool enabled, const BeautyOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
开启本地美颜功能,并设置美颜效果选项。
### 调用时机 [#调用时机-2]
请在 [enableVideo](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_enablevideo) 或 [startPreview [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_startpreview2) 之后调用该方法。
### 调用限制 [#调用限制-2]
- 该方法依赖于视频增强动态库 `libagora_clear_vision_extension.dll`,如果删除该动态库会导致无法正常开启该功能。
- 该功能对设备性能要求较高,调用该方法时 SDK 会自动对当前设备能力进行检查。
### 参数 [#参数-2]
是否开启美颜功能:
- `true`: 开启美颜功能。
- `false`:(默认)关闭美颜功能。
美颜选项,详细定义见 [BeautyOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-beautyoptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -4:当前设备不支持该功能,可能的原因有:
- 当前设备能力不满足美颜的使用要求,建议更换性能更高的设备。
### 所属接口类 [#所属接口类-2]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)
## setColorEnhanceOptions [#setcolorenhanceoptions]
设置色彩增强功能。
```cpp
virtual int setColorEnhanceOptions(bool enabled, const ColorEnhanceOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
### 详情 [#详情]
摄像头采集到的视频画面可能存在色彩失真的现象。色彩增强功能可以通过智能调节饱和度和对比度等视频特性,提升视频色彩丰富度和色彩还原度,最终使视频画面更生动。
你可以调用该方法开启色彩增强功能并设置色彩增强的效果。
:::caution
注意:
- 请在 [enableVideo](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_enablevideo) 后调用该方法。
- 色彩增强对设备性能有一定要求。开启色彩增强后,如果设备出现严重发烫等问题,建议你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。
- 该方法依赖于视频增强动态库 `libagora_clear_vision_extension.dll`,如果删除该动态库会导致无法正常开启该功能。
:::
### 参数 [#参数-3]
是否开启色彩增强功能:
- `true`:开启色彩增强功能。
- `false`:(默认)关闭色彩增强功能。
色彩增强选项,用于设置色彩增强的效果。详见 [ColorEnhanceOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-colorenhanceoptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值-3]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)
## setFaceShapeAreaOptions [#setfaceshapeareaoptions]
设置美型部位选项并指定媒体源。
```cpp
virtual int setFaceShapeAreaOptions(const FaceShapeAreaOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
如果在 [setFaceShapeBeautyOptions](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法中实现的预设美型效果达不到预期,你可以通过该方法设置美型部位选项,对人脸的各个部位单独微调,实现更加精细的美型效果。
:::error
危险: 美型属于增值服务,计费方式详见[计费策略](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
:::
### 调用时机 [#调用时机-3]
请在 [setFaceShapeBeautyOptions](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 之后调用该方法。
### 调用限制 [#调用限制-3]
- 在 Android 平台上,该方法仅适用于 Android 4.4 及以上版本。
- 该方法依赖于视频增强动态库 `libagora_clear_vision_extension.dll`,如果删除该动态库会导致无法正常开启该功能。
- 该功能对设备性能要求较高,调用该方法时 SDK 会自动对当前设备能力进行检查。
### 参数 [#参数-4]
美型部位选项,详见 [FaceShapeAreaOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-faceshapeareaoptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值-4]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -4:当前设备不支持该功能,可能的原因有:
- 当前设备能力不满足美颜的使用要求,建议更换性能更高的设备。
- 当前设备版本低于 Android 4.4,不支持该操作,建议更换设备或升级操作系统。
### 所属接口类 [#所属接口类-4]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)
## setFaceShapeBeautyOptions [#setfaceshapebeautyoptions]
设置美型效果选项并指定媒体源。
```cpp
virtual int setFaceShapeBeautyOptions(bool enabled, const FaceShapeBeautyOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
调用该方法可对人脸各部位进行修饰,使用预设的参数一次性实现瘦脸、大眼、瘦鼻等微整形效果,支持微调整体的修饰力度。
:::error
危险: 美型属于增值服务,计费方式详见[计费策略](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
:::
### 调用时机 [#调用时机-4]
请在 [enableVideo](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_enablevideo) 之后调用该方法。
### 调用限制 [#调用限制-4]
- 在 Android 平台上,该方法仅适用于 Android 4.4 及以上版本。
- 该方法依赖于视频增强动态库 `libagora_clear_vision_extension.dll`,如果删除该动态库会导致无法正常开启该功能。
- 该功能对设备性能要求较高,调用该方法时 SDK 会自动对当前设备能力进行检查。
### 参数 [#参数-5]
是否开启美型效果:
- `true`: 开启美型功能。
- `false`:(默认)关闭美型功能。
美型风格选项,详见 [FaceShapeBeautyOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-faceshapebeautyoptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值-5]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -4:当前设备不支持该功能,可能的原因有:
- 当前设备能力不满足美颜的使用要求,建议更换性能更高的设备。
- 当前设备版本低于 Android 4.4,不支持该操作,建议更换设备或升级操作系统。
### 所属接口类 [#所属接口类-5]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)
## setFilterEffectOptions [#setfiltereffectoptions]
设置滤镜效果选项并指定媒体源。
```cpp
virtual int setFilterEffectOptions(bool enabled, const FilterEffectOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
### 调用时机 [#调用时机-5]
请在 [enableVideo](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_enablevideo) 之后调用该方法。
### 调用限制 [#调用限制-5]
- 该方法依赖于视频增强动态库 `libagora_clear_vision_extension.dll`,如果删除该动态库会导致无法正常开启该功能。
- 该功能对设备性能要求较高,调用该方法时 SDK 会自动对当前设备能力进行检查。
### 参数 [#参数-6]
是否开启滤镜效果:
- `true`: 开启滤镜功能。
- `false`:(默认)关闭滤镜功能。
滤镜选项,详见 [FilterEffectOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-filtereffectoptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值-6]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)
## setLowlightEnhanceOptions [#setlowlightenhanceoptions]
设置暗光增强功能。
```cpp
virtual int setLowlightEnhanceOptions(bool enabled, const LowlightEnhanceOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
你可以调用该方法开启暗光增强功能并设置暗光增强的效果。
### 适用场景 [#适用场景-2]
暗光增强功能可以在光线亮度偏低(如背光、阴天、暗场景)和亮度不均匀的环境下自适应调整视频画面的亮度值,恢复或凸显图像的细节信息,最终提升视频图像的整体视觉效果。
### 调用时机 [#调用时机-6]
请在 [enableVideo](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_enablevideo) 后调用该方法。
### 调用限制 [#调用限制-6]
- 该方法依赖于视频增强动态库 `libagora_clear_vision_extension.dll`,如果删除该动态库会导致无法正常开启该功能。
- 暗光增强对设备性能有一定要求。开启暗光增强后,如果设备出现严重发烫等问题,建议你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。
- 如果要实现优先画质 (LOW_LIGHT_ENHANCE_LEVEL_HIGH_QUALITY) 的暗光增强,需要先调用 [setVideoDenoiserOptions](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_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)。
### 参数 [#参数-7]
是否开启暗光增强功能:
- `true`: 开启暗光增强功能。
- `false`:(默认)关闭暗光增强功能。
暗光增强选项,用于设置暗光增强的效果。详见 [LowlightEnhanceOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-lowlightenhanceoptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值-7]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)
## setVideoDenoiserOptions [#setvideodenoiseroptions]
设置视频降噪功能。
```cpp
virtual int setVideoDenoiserOptions(bool enabled, const VideoDenoiserOptions& options, agora::media::MEDIA_SOURCE_TYPE type = agora::media::PRIMARY_CAMERA_SOURCE) = 0;
```
你可以调用该方法开启视频降噪功能并设置视频降噪的效果。
:::note
注: 如果该方法实现的降噪强度无法满足你的需求,声网推荐你调用 [setBeautyEffectOptions](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能,以获得更好的视频降噪效果。强效降噪效果的 [BeautyOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-beautyoptions) 推荐设置如下:
- lighteningContrastLevel:LIGHTENING_CONTRAST_NORMAL
- lighteningLevel:0.0
- smoothnessLevel:0.5
- rednessLevel:0.0
- sharpnessLevel:0.1
:::
### 适用场景 [#适用场景-3]
采光不足的环境和低端视频采集设备会使视频图像含有明显的噪声,影响视频画质。在实时互动场景下,视频噪声还会在编码过程中占用码流资源并降低编码效率。
### 调用时机 [#调用时机-7]
请在 [enableVideo](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_enablevideo) 后调用该方法。
### 调用限制 [#调用限制-7]
- 该方法依赖于视频增强动态库 `libagora_clear_vision_extension.dll`,如果删除该动态库会导致无法正常开启该功能。
- 视频降噪对设备性能有一定要求。开启视频降噪后,如果设备出现严重发烫等问题,建议你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。
### 参数 [#参数-8]
是否开启视频降噪功能:
- `true`: 开启视频降噪功能。
- `false`:(默认)关闭视频降噪功能。
视频降噪选项,用于设置视频降噪的效果。详见 [VideoDenoiserOptions](/zh-CN/api-reference/rtc/unreal-cpp/class-videodenoiseroptions)。
效果应用的媒体源类型。详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediasourcetype)。
:::caution
注意: 在该方法中,该参数仅支持以下两种设置:
- 使用摄像头采集本地视频时,请保持默认值 PRIMARY_CAMERA_SOURCE。
- 如果要使用自定义采集的视频,将该参数设置为 CUSTOM_VIDEO_SOURCE。
:::
### 返回值 [#返回值-8]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine)