# 使用美颜插件 (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)立即体验美颜功能。
具体效果可参考下图:

## 实现原理 [#实现原理]
声网 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。用于实现红润肤色等效果,取值越大,红润程度越大。