# 使用美颜插件 (Beta) (/zh-CN/realtime-media/rtc/build/extensions/web/image-enhancement) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## 使用美颜插件(Beta 版) [#使用美颜插件beta-版] 声网提供美颜插件 `agora-extension-beauty-effect`,可以与 Web SDK(建议 v4.12.0 或以上)搭配使用。用户可以开启美颜,调节美白、磨皮、祛痘、红润程度,实现自然的美颜效果。 点击[在线链接](https://webdemo.agora.io/example/plugin/beauty/index.html)立即体验美颜功能。 具体效果可参考下图: ![美颜插件效果示意图](https://web-cdn.agora.io/docs-files/1654605553546) ## 实现原理 [#实现原理] 声网 Web SDK 的媒体传输管道包含采集、前处理、编码、传输、解码、后处理和播放等环节。在前处理阶段,插件可以对管道中的音视频数据进行处理,从而实现虚拟背景、降噪、美颜、语音活动检测等功能。 ## 前提条件 [#前提条件] 使用美颜插件需要满足以下前提条件: - 使用最新版本的桌面端 Chrome(推荐)、Firefox 或 Safari 浏览器。 - 已集成 v4.12.0 或以上版本的 Web SDK,实现基础的实时音视频互动功能,具体参考[快速开始](/zh-CN/realtime-media/rtc/get-started/quick-start/web)文档。 ## 示例代码 [#示例代码] 以下是一段使用美颜插件的完整代码,供开发者参考。 ```typescript import AgoraRTC from "agora-rtc-sdk-ng"; import BeautyExtension from "agora-extension-beauty-effect"; // 创建 Client var client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"}); // 创建 BeautyExtension 实例 const extension = new BeautyExtension(); // 注册插件 AgoraRTC.registerExtensions([extension]); // 创建 BeautyProcessor 实例 const processor = extension .createProcessor(); var localTracks = { videoTrack: null, audioTrack: null }; async function start() { // 创建本地麦克风轨道和摄像头轨道 localTracks.audioTrack = localTracks.audioTrack || await AgoraRTC.createMicrophoneAudioTrack(); localTracks.videoTrack = localTracks.videoTrack || await AgoraRTC.createCameraVideoTrack({cameraId: videoSelect.value, encoderConfig: '720p_2'}); localTracks.videoTrack.play("local-player"); if (processor && localTracks.videoTrack) { // 将插件注入 SDK 内的视频处理管道 localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination); // 开启美颜 await processor.enable(); } } // 设置各项美颜参数 async function setBeautyOptions() { processor.setOptions({ lighteningContrastLevel: 2, lighteningLevel: 0.7, smoothnessLevel: 0.6, sharpnessLevel: 0.5, rednessLevel: 0.5 }); } ``` ## 实现步骤 [#实现步骤] 按照以下步骤集成美颜插件并实现美颜功能。 ### 1. 集成插件 [#1-集成插件] 通过 npm 将美颜插件 [agora-extension-beauty-effect](https://www.npmjs.com/package/agora-extension-beauty-effect) 集成到你的项目中。 1. 运行以下命令安装美颜插件: ```bash npm install agora-extension-beauty-effect ``` 2. 通过以下任意一种方式引入美颜插件。 - 方式一:在 JavaScript 文件中加入以下代码引入。 ```typescript import BeautyExtension from "agora-extension-beauty-effect"; ``` - 方式二:在 HTML 文件中通过 ` ``` ### 2. 注册插件 [#2-注册插件] 调用 `AgoraRTC.createClient` 创建 Client 对象后,新建一个 `BeautyExtension` 对象,然后调用 `AgoraRTC.registerExtensions` 并传入创建的 `BeautyExtension` 对象,注册美颜插件。 ```typescript // 创建 Client var client = AgoraRTC.createClient({mode: "rtc", codec: "vp8"}); // 创建 BeautyExtension 实例 const extension = new BeautyExtension(); // 注册插件 AgoraRTC.registerExtensions([extension]); ``` ### 3. 开启插件 [#3-开启插件] 按照以下步骤开启插件: 1. 调用 `extension.createProcessor` 创建 `BeautyProcessor` 实例。 ```typescript const processor = extension.createProcessor(); ``` 2. 在创建本地摄像头视频轨道后,调用 `videoTrack.pipe` 并指定 `videoTrack.processorDestination`,将插件注入到 SDK 的媒体处理管道中。 ```typescript localTracks.videoTrack.pipe(processor).pipe(localTracks.videoTrack.processorDestination); ``` 3. 调用 `processor.enable` 开启美颜。 ```typescript await processor.enable(); ``` 如果调用此方法前未调用 `setOptions`,SDK 会使用 [BeautyEffectOptions](#beautyeffectoptions) 中各项美颜参数的默认值。 ### 4. 设置美颜 [#4-设置美颜] 调用 `processor.setOptions` 设置美颜参数: ```typescript processor.setOptions({ // 对比度 lighteningContrastLevel: 2, // 亮度 lighteningLevel: 0.7, // 平滑度 smoothnessLevel: 0.6, // 锐化程度 sharpnessLevel: 0.5, // 红润度 rednessLevel: 0.5 }); ``` ## 开发注意事项 [#开发注意事项] - 美颜插件的浏览器支持如下: - 支持最新版本的 Chrome、Firefox 和 Safari。 - 为了获得更好的美颜体验,声网推荐在桌面端 Chrome 最新版上使用此功能。 - 不支持 Safari 15.4 以下版本,因为 [WebKit 已知问题](https://bugs.webkit.org/show_bug.cgi?id=181663)会导致黑屏现象。 - 不建议在移动端上开启美颜。 - 美颜插件对设备性能要求较高,声网建议满足以下要求: - Intel Core i5 2 核或以上的处理器 - RAM 8GB 或以上 - 64 位操作系统 - 使用美颜插件时,请确保开启浏览器硬件加速功能。 - 美颜插件封装了 Web SDK 4.x 内置的美颜功能(通过 `setBeautyEffect` 开启),并且升级了美颜算法。如果你使用了 SDK 内置的美颜功能,声网建议你升级到 v4.12.0 或以上,改用美颜插件的实现方案。SDK 内置的美颜功能将逐步停止更新。 - 如需同时使用多个媒体处理插件,声网建议你使用 Intel Core i5 4 核或以上的处理器。同时开启多个插件后,如果其它正在运行的程序占用了较高的系统资源,你的 App 可能会出现音视频卡顿。 ## API 参考 [#api-参考] 本节提供美颜插件的 API 参考。 ### IBeautyExtension [#ibeautyextension] **createProcessor** ```typescript createProcessor(): IBeautyProcessor; ``` 创建 `IBeautyProcessor` 对象。 ### IBeautyProcessor [#ibeautyprocessor] #### setOptions [#setoptions] ```typescript setOptions(options: BeautyEffectOptions): void; ``` 设置美颜参数。 参数: - `options`: 美颜参数,详见 [BeautyEffectOptions](#beautyeffectoptions)。 #### enable [#enable] ```typescript enable(): void | Promise; ``` 开启美颜。 如果调用此方法前未调用 `setOptions`,SDK 会使用 [BeautyEffectOptions](#beautyeffectoptions) 中各项美颜参数的默认值。 #### disable [#disable] ```typescript disable(): void | Promise; ``` 关闭美颜。 #### release [#release] ```typescript release(): Promise; ``` 释放插件占用的所有资源,包括创建的 Web Worker。 如果反复创建插件对象 `IBeautyProcessor` 但不释放插件占用资源,可能会导致内存耗尽。 #### onoverload [#onoverload] ```typescript onoverload?: () => void; ``` 当系统运算性能无法满足处理要求时,SDK 会触发 `onoverload`。 声网建议在此事件回调函数中调用 `disable` 停止美颜,并添加 UI 提示。 ### 类型定义 [#类型定义] #### BeautyEffectOptions [#beautyeffectoptions] ```typescript export type BeautyEffectOptions = { lighteningContrastLevel: 0 | 1 | 2; lighteningLevel: Number, smoothnessLevel?: Number; sharpnessLevel?: Number; rednessLevel?: Number; }; ``` 美颜参数。用于 [setOptions](#setoptions) 方法。 - `lighteningContrastLevel`: 对比度,与 `lighteningLevel` 参数搭配使用。取值越大,明暗对比越强烈。取值包括: - `0`: 低对比度。 - `1`: (默认)正常对比度。 - `2`: 高对比度。 - `lighteningLevel`: Number 型。亮度,取值范围为 [0.0,1.0],其中 0.0 表示原始亮度。默认值为 0.6。用于实现美白效果,取值越大,美白程度越大。 - `smoothnessLevel`: Number 型。平滑度,取值范围为 [0.0,1.0],其中 0.0 表示原始磨皮程度。默认值为 0.5。用于实现祛痘、磨皮等效果,取值越大,磨皮程度越大。 - `sharpnessLevel`: Number 型。锐化程度,取值范围为 [0.0,1.0],其中 0.0 表示原始锐度。默认值为 0.3。用于实现提升画面清晰度的效果,取值越大,锐化程度越大。 - `rednessLevel`: Number 型。红润度,取值范围为 [0.0,1.0],其中 0.0 表示原始红润度。默认值为 0.1。用于实现红润肤色等效果,取值越大,红润程度越大。