> ## 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.

# API 参考

> Flutter API 参考

## 日志相关

### FBLogLevel

日志级别枚举。

```dart theme={null}
enum FBLogLevel {
  trace,
  debug,
  info,
  warn,
  error,
  critical,
}
```

### FBLogConfig

日志配置类。

| 字段               | 类型           | 默认值     | 说明        |
| ---------------- | ------------ | ------- | --------- |
| `consoleEnabled` | `bool`       | `false` | 是否启用控制台日志 |
| `fileEnabled`    | `bool`       | `false` | 是否启用文件日志  |
| `level`          | `FBLogLevel` | `info`  | 日志级别      |
| `fileName`       | `String`     | `''`    | 日志文件路径    |

## 引擎相关

### FBEngineConfig

引擎配置类。

| 字段                | 类型        | 说明                                   |
| ----------------- | --------- | ------------------------------------ |
| `appId`           | `String`  | 应用 ID（可选，如果提供了 `licenseJson` 则不需要）   |
| `appKey`          | `String`  | 应用密钥（可选，如果提供了 `licenseJson` 则不需要）    |
| `licenseJson`     | `String?` | 授权数据 JSON 字符串（可选，优先级高于 appId/appKey） |
| `externalContext` | `bool`    | 是否使用外部 OpenGL 上下文（默认 `false`）        |

### FBBeautyEffectEngine

美颜引擎单例类。

#### 静态方法

| 方法                                              | 说明                   |
| ----------------------------------------------- | -------------------- |
| `Future<String> getSdkVersion()`                | 获取 SDK 版本号           |
| `Future<void> setLogConfig(FBLogConfig config)` | 设置日志配置（需在 init 之前调用） |
| `Future<void> init(FBEngineConfig config)`      | 初始化引擎                |
| `FBBeautyEffectEngine get sharedInstance`       | 获取单例实例               |

#### 参数设置

| 方法                                                                                         | 说明                   |
| ------------------------------------------------------------------------------------------ | -------------------- |
| `Future<int> setBasicParam(FBBasicParam param, double value)`                              | 设置基础美颜参数 \[0.0, 1.0] |
| `Future<int> setReshapeParam(FBReshapeParam param, double value)`                          | 设置面部重塑参数 \[0.0, 1.0] |
| `Future<int> setMakeupParam(FBMakeupParam param, double value)`                            | 设置美妆参数 \[0.0, 1.0]   |
| `Future<int> setLipstickStyle(FBLipstickStyle style)`                                      | 设置口红风格               |
| `Future<int> setBlushStyle(FBBlushStyle style)`                                            | 设置腮红风格               |
| `Future<int> setSkinOnlyBeauty(bool enabled)`                                              | 美颜仅作用于皮肤区域           |
| `Future<int> setChromaKeyParam(FBChromaKeyParam param, double value)`                      | 设置色度键参数              |
| `Future<int> setVirtualBackground(FBBackgroundMode mode, {FBImageFrame? backgroundImage})` | 设置虚拟背景               |

#### 滤镜与贴纸

| 方法                                                                     | 说明                 |
| ---------------------------------------------------------------------- | ------------------ |
| `Future<int> setFilter(String filterId)`                               | 设置滤镜               |
| `Future<int> setFilterIntensity(double intensity)`                     | 设置滤镜强度 \[0.0, 1.0] |
| `Future<int> setSticker(String stickerId)`                             | 设置贴纸（空字符串清除）       |
| `Future<int> registerFilter(String filterId, String fbdFilePath)`      | 从文件注册滤镜            |
| `Future<int> registerFilterData(String filterId, Uint8List fbdData)`   | 从内存注册滤镜            |
| `Future<int> registerSticker(String stickerId, String fbdFilePath)`    | 从文件注册贴纸            |
| `Future<int> registerStickerData(String stickerId, Uint8List fbdData)` | 从内存注册贴纸            |
| `Future<int> unregisterFilter(String filterId)`                        | 卸载滤镜               |
| `Future<int> unregisterAllFilters()`                                   | 卸载所有滤镜             |
| `Future<int> unregisterSticker(String stickerId)`                      | 卸载贴纸               |
| `Future<int> unregisterAllStickers()`                                  | 卸载所有贴纸             |
| `Future<List<String>> getRegisteredFilters()`                          | 获取已注册滤镜列表          |
| `Future<List<String>> getRegisteredStickers()`                         | 获取已注册贴纸列表          |

#### 图像处理

| 方法                                                                  | 说明     |
| ------------------------------------------------------------------- | ------ |
| `Future<FBImageFrame?> processImage(FBImageFrame inputFrame)`       | 处理图像帧  |
| `Future<int> processImageFile(String inputPath, String outputPath)` | 处理图片文件 |

#### 回调

| 属性                | 类型                              | 说明       |
| ----------------- | ------------------------------- | -------- |
| `onFaceLandmarks` | `Stream<FBFaceDetectionResult>` | 人脸关键点检测流 |
| `onEngineEvent`   | `Stream<FBEngineEvent>`         | 引擎事件流    |

#### 生命周期

| 方法                       | 说明     |
| ------------------------ | ------ |
| `Future<void> release()` | 释放引擎资源 |

**返回值说明：**

* `int` 返回值：`0` 表示成功，`-1` 表示引擎未初始化
* `processImage` 返回 `null` 表示处理失败

## 美颜参数枚举

### FBBasicParam

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

### FBReshapeParam

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

### FBMakeupParam

| 枚举值        | 值 | 说明 |
| ---------- | - | -- |
| `lipstick` | 0 | 口红 |
| `blush`    | 1 | 腮红 |

### FBLipstickStyle

| 枚举值     | 值 | 说明     |
| ------- | - | ------ |
| `rouge` | 0 | 玫瑰红    |
| `coral` | 1 | 珊瑚橙    |
| `pink`  | 2 | 粉色（默认） |

### FBBlushStyle

| 枚举值       | 值 | 说明     |
| --------- | - | ------ |
| `classic` | 0 | 经典（默认） |
| `peach`   | 1 | 蜜桃     |
| `rose`    | 2 | 玫瑰     |

### FBChromaKeyParam

| 枚举值            | 值 | 说明                   |
| -------------- | - | -------------------- |
| `keyColor`     | 0 | 键色（0=绿色, 1=蓝色, 2=红色） |
| `similarity`   | 1 | 相似度 \[0.0, 1.0]      |
| `smoothness`   | 2 | 平滑度 \[0.0, 1.0]      |
| `desaturation` | 3 | 去饱和度 \[0.0, 1.0]     |

### FBBackgroundMode

| 枚举值     | 值 | 说明   |
| ------- | - | ---- |
| `none`  | 0 | 无背景  |
| `blur`  | 1 | 模糊背景 |
| `image` | 2 | 图片背景 |

## 图像相关

### FBImageFrame

图像帧类，用于封装图像数据。

#### 构造函数

```dart theme={null}
// 单平面格式（RGBA/BGRA/RGB/BGR）
FBImageFrame({
  required int width,
  required int height,
  required int stride,
  Uint8List? data,
  required FBImageFormat format,
  FBFrameType frameType = FBFrameType.video,
})

// I420 格式
FBImageFrame.fromI420({...})

// NV12 格式
FBImageFrame.fromNV12({...})

// NV21 格式
FBImageFrame.fromNV21({...})
```

#### 属性

| 字段          | 类型              | 说明               |
| ----------- | --------------- | ---------------- |
| `width`     | `int`           | 宽度（像素）           |
| `height`    | `int`           | 高度（像素）           |
| `stride`    | `int`           | 行步长（字节）          |
| `data`      | `Uint8List?`    | 像素数据（单平面格式）      |
| `format`    | `FBImageFormat` | 像素格式             |
| `frameType` | `FBFrameType`   | 帧类型（image/video） |
| `yuvData`   | `FBYUVData?`    | YUV 多平面数据        |

### FBImageFormat

| 枚举值    | 值 | 说明                                |
| ------ | - | --------------------------------- |
| `i420` | 0 | YUV 4:2:0 planar                  |
| `nv12` | 1 | YUV 4:2:0 semi-planar             |
| `nv21` | 2 | YUV 4:2:0 semi-planar（Android 默认） |
| `bgra` | 3 | BGRA 32bpp                        |
| `rgba` | 4 | RGBA 32bpp                        |
| `bgr`  | 5 | BGR 24bpp                         |
| `rgb`  | 6 | RGB 24bpp                         |

### FBFrameType

| 枚举值     | 值 | 说明            |
| ------- | - | ------------- |
| `image` | 0 | 单帧图片处理（质量更好）  |
| `video` | 1 | 连续视频流处理（性能更高） |

## 回调相关

### FBFaceDetectionResult

| 字段           | 类型                | 说明         |
| ------------ | ----------------- | ---------- |
| `rect`       | `FBRect`          | 人脸边界框      |
| `keyPoints`  | `List<FBPoint2d>` | 106 个人脸关键点 |
| `visibility` | `List<double>`    | 关键点可见度     |
| `faceId`     | `int`             | 人脸 ID      |
| `score`      | `double`          | 检测置信度      |
| `pitch`      | `double`          | 俯仰角        |
| `roll`       | `double`          | 翻滚角        |
| `yaw`        | `double`          | 偏航角        |

### FBEngineEventCode

| 枚举值                            | 值   | 说明           |
| ------------------------------ | --- | ------------ |
| `licenseValidationSuccess`     | 0   | License 验证成功 |
| `licenseValidationFailed`      | 1   | License 验证失败 |
| `engineInitializationComplete` | 100 | 引擎初始化完成      |
| `engineInitializationFailed`   | 101 | 引擎初始化失败      |

## 原生层访问

供 TRTC 等推流 SDK 在原生层获取引擎实例。

### iOS (Swift)

```swift theme={null}
let engine = FacebetterPlugin.sharedInstance().engine
```

### Android (Kotlin)

```kotlin theme={null}
val engine = FacebetterPlugin.sharedInstance?.getEngine()
```