> ## Documentation Index
> Fetch the complete documentation index at: https://docs.facebetter.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 实现美颜

> 实现 Flutter 美颜

## 添加 SDK 依赖

在 `pubspec.yaml` 中添加依赖：

```yaml theme={null}
dependencies:
  facebetter_flutter: ^1.4.4
```

然后执行：

```bash theme={null}
flutter pub get
```

iOS 还需要执行：

```bash theme={null}
cd ios && pod install
```

## 导入类

```dart theme={null}
import 'package:facebetter_flutter/facebetter_flutter.dart';
```

## 日志配置

默认日志是关闭的，可以按需开启：

<Warning>
  开启日志要放到引擎初始化**之前**，否则可能看不到初始化日志。
</Warning>

```dart theme={null}
FBBeautyEffectEngine.setLogConfig(
  FBLogConfig(
    consoleEnabled: true,
    level: FBLogLevel.debug,
  ),
);
```

## 初始化引擎

按照 [此页面](/zh/intro/enable-service#获取-appid-和-appkey) 指引，获取 `appId` 和 `appKey`：

```dart theme={null}
await FBBeautyEffectEngine.init(
  FBEngineConfig(appId: 'your appId', appKey: 'your appKey'),
);

// 获取单例
final engine = FBBeautyEffectEngine.sharedInstance;
```

**验证方式优先级：**

* 如果提供了 `licenseJson`，使用授权数据验证（支持在线响应和离线授权）
* 否则使用 `appId` 和 `appKey` 进行自动联网验证

```dart theme={null}
await FBBeautyEffectEngine.init(
  FBEngineConfig(
    appId: 'your appId',
    appKey: 'your appKey',
    licenseJson: 'your license json string', // 可选
  ),
);
```

## 调节美颜参数

<Tip>
  所有美颜参数值范围为 `[0.0, 1.0]`，设置为 `0` 即禁用效果。
</Tip>

### 设置美肤参数

```dart theme={null}
final engine = FBBeautyEffectEngine.sharedInstance;

await engine.setBasicParam(FBBasicParam.smoothing, 0.8);  // 磨皮
await engine.setBasicParam(FBBasicParam.whitening, 0.6);  // 美白
await engine.setBasicParam(FBBasicParam.rosiness, 0.3);   // 红润
await engine.setBasicParam(FBBasicParam.sharpening, 0.2); // 锐化
```

支持的美肤参数：

| 参数                        | 枚举值 | 说明 |
| ------------------------- | --- | -- |
| `FBBasicParam.smoothing`  | 0   | 磨皮 |
| `FBBasicParam.sharpening` | 1   | 锐化 |
| `FBBasicParam.whitening`  | 2   | 美白 |
| `FBBasicParam.rosiness`   | 3   | 红润 |

### 设置美型参数

```dart theme={null}
await engine.setReshapeParam(FBReshapeParam.faceThin, 0.5);   // 瘦脸
await engine.setReshapeParam(FBReshapeParam.eyeSize, 0.3);    // 大眼
await engine.setReshapeParam(FBReshapeParam.noseSlim, 0.2);   // 瘦鼻梁
```

支持的美型参数：

| 参数                           | 枚举值 | 说明  |
| ---------------------------- | --- | --- |
| `FBReshapeParam.faceThin`    | 0   | 瘦脸  |
| `FBReshapeParam.faceVShape`  | 1   | V脸  |
| `FBReshapeParam.faceNarrow`  | 2   | 窄脸  |
| `FBReshapeParam.faceShort`   | 3   | 短脸  |
| `FBReshapeParam.cheekbone`   | 4   | 颧骨  |
| `FBReshapeParam.jawbone`     | 5   | 下颌骨 |
| `FBReshapeParam.chin`        | 6   | 下巴  |
| `FBReshapeParam.noseSlim`    | 7   | 瘦鼻梁 |
| `FBReshapeParam.eyeSize`     | 8   | 大眼  |
| `FBReshapeParam.eyeDistance` | 9   | 眼距  |

### 设置美妆参数

```dart theme={null}
await engine.setMakeupParam(FBMakeupParam.lipstick, 0.5); // 口红
await engine.setMakeupParam(FBMakeupParam.blush, 0.3);    // 腮红
```

### 设置美颜仅作用于皮肤区域

```dart theme={null}
await engine.setSkinOnlyBeauty(true);
```

<Tip>
  启用后，美颜效果（磨皮、美白等）仅应用于皮肤区域，非皮肤区域保持不变。
</Tip>

### 设置虚拟背景

```dart theme={null}
// 模糊背景
await engine.setVirtualBackground(FBBackgroundMode.blur);

// 图片背景
await engine.setVirtualBackground(
  FBBackgroundMode.image,
  backgroundImage: FBImageFrame(
    width: 1920, height: 1080, stride: 7680,
    data: bgRgbaBytes, format: FBImageFormat.rgba,
  ),
);

// 清除虚拟背景
await engine.setVirtualBackground(FBBackgroundMode.none);
```

## 使用滤镜和贴纸

### 滤镜功能

```dart theme={null}
// 注册滤镜资源
await engine.registerFilter('chuxin', '/path/to/chuxin.fbd');

// 或从内存注册
await engine.registerFilterData('chuxin', fbdBytes);

// 使用滤镜
await engine.setFilter('chuxin');

// 调节滤镜强度
await engine.setFilterIntensity(0.8);

// 卸载滤镜
await engine.unregisterFilter('chuxin');
```

### 贴纸功能

```dart theme={null}
// 注册贴纸资源
await engine.registerSticker('cherry', '/path/to/cherry.fbd');

// 使用贴纸
await engine.setSticker('cherry');

// 清除贴纸
await engine.setSticker('');
```

## 处理图像

### 创建图像帧

```dart theme={null}
// RGBA 格式
final inputFrame = FBImageFrame(
  width: 1080, height: 1920, stride: 4320,
  data: rgbaBytes, format: FBImageFormat.rgba,
  frameType: FBFrameType.image,
);

// I420 格式
final i420Frame = FBImageFrame.fromI420(
  width: 1080, height: 1920,
  dataY: yBytes, strideY: 1080,
  dataU: uBytes, strideU: 540,
  dataV: vBytes, strideV: 540,
);

// NV12 格式
final nv12Frame = FBImageFrame.fromNV12(
  width: 1080, height: 1920,
  dataY: yBytes, strideY: 1080,
  dataUV: uvBytes, strideUV: 1080,
);
```

### 处理图像

```dart theme={null}
final outputFrame = await engine.processImage(inputFrame);
if (outputFrame != null) {
  final processedData = outputFrame.data;
  // 使用处理后的数据...
}
```

### 处理图片文件

```dart theme={null}
final ret = await engine.processImageFile('input.png', 'output.png');
```

<Tip>
  引擎会自动保持输入输出格式一致。输入 NV21 格式，输出即为 NV21 格式；输入 RGBA 格式，输出即为 RGBA 格式。
</Tip>

## 设置回调

```dart theme={null}
engine.onEngineEvent.listen((event) {
  if (event.code == FBEngineEventCode.licenseValidationSuccess) {
    print('License 验证成功');
  } else if (event.code == FBEngineEventCode.licenseValidationFailed) {
    print('License 验证失败: ${event.message}');
  }
});
```

## 释放资源

```dart theme={null}
await engine.release();
```

## 相关文档

* [API 参考](/zh/flutter/api-reference) - 完整的 API 文档
* [TRTC 集成](/zh/flutter/trtc-integration) - TRTC 推流 SDK 集成美颜
* [授权认证](/zh/intro/license) - 在线 / 离线 License 说明