> ## 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 레퍼런스

> Facebetter SDK 2.0 iOS Objective-C API

<Note>
  이 페이지는 SDK **2.0.0**에 해당합니다. 프리셋 의미: [파라미터 열거형](/ko/intro/makeup). 인증: [인증 및 라이선스](/ko/intro/license).
</Note>

iOS와 macOS는 이 Objective-C API를 공유합니다. iOS 전용: `+[FBImageFrame createWithUIImage:]`. 최소 OS: **iOS 12.0**, 아키텍처 **arm64**.

## 로깅

### `FBLogLevel`

```objc theme={null}
typedef NS_ENUM(NSInteger, FBLogLevel) {
  FBLogLevel_Trace = 0,
  FBLogLevel_Debug,
  FBLogLevel_Info,
  FBLogLevel_Warn,
  FBLogLevel_Error,
  FBLogLevel_Critical,
};
```

### `FBLogConfig`

| 속성               | 타입           | 설명                                |
| ---------------- | ------------ | --------------------------------- |
| `consoleEnabled` | `BOOL`       | 콘솔 출력                             |
| `fileEnabled`    | `BOOL`       | 파일 출력                             |
| `level`          | `FBLogLevel` | 최소 레벨                             |
| `fileName`       | `NSString *` | 로그 경로(`fileEnabled`가 `YES`일 때 사용) |

```objc theme={null}
FB_OBJC_API @interface FBLogConfig : NSObject
@property(nonatomic, assign) BOOL consoleEnabled;
@property(nonatomic, assign) BOOL fileEnabled;
@property(nonatomic, assign) FBLogLevel level;
@property(nonatomic, copy, nullable) NSString *fileName;
- (instancetype)init;
@end
```

`createEngineWithConfig:` **전에** `+[FBBeautyEffectEngine setLogConfig:]`를 호출하세요. `FBErrorCode`를 반환합니다(`0` 성공, `config`가 nil이면 `-1`).

## 엔진 구성

### `FBEngineConfig`

| 속성                | 타입           | 설명                                                    |
| ----------------- | ------------ | ----------------------------------------------------- |
| `appId`           | `NSString *` | Dashboard App ID(온라인 인증)                              |
| `appKey`          | `NSString *` | Dashboard App Key(온라인 인증)                             |
| `licenseToken`    | `NSString *` | 라이선스 토큰 문자열, `{token}` JSON, 또는 네이티브 `.lic` 내용        |
| `externalContext` | `BOOL`       | 기본 `NO`. `YES`: 호출 측 OpenGL ES 컨텍스트를 사용하고 SDK는 만들지 않음 |

**인증 우선순위:** `licenseToken`이 비어 있지 않으면 해당 토큰을 로컬에서 검증하고 `/facebetter/v2/auth`를 건너뜁니다. 그렇지 않으면 `appId` + `appKey`로 온라인 인증합니다. Dashboard에서 앱 **Bundle ID**를 바인딩하세요.

```objc theme={null}
FB_OBJC_API @interface FBEngineConfig : NSObject
@property(nonatomic, copy) NSString *appId;
@property(nonatomic, copy) NSString *appKey;
@property(nonatomic, copy, nullable) NSString *licenseToken;
@property(nonatomic, assign) BOOL externalContext;
- (instancetype)init;
@end
```

### `FBFrameType`

`processImage:` 전에 `FBImageFrame.type`에 설정합니다. 메서드 인자가 아닙니다.

```objc theme={null}
typedef NS_ENUM(NSInteger, FBFrameType) {
  FBFrameTypeImage = 0,  // stills
  FBFrameTypeVideo = 1   // live / camera
};
```

## `FBBeautyEffectEngine`

```objc theme={null}
FB_OBJC_API @interface FBBeautyEffectEngine : NSObject

+ (int)setLogConfig:(FBLogConfig *)config;
+ (instancetype)createEngineWithConfig:(FBEngineConfig *)config;

- (int)setSmoothing:(float)intensity;
- (int)setSmoothingStyle:(FBSmoothingStyle)style;
- (int)setWhitening:(float)intensity;
- (int)setWhiteningStyle:(FBWhiteningStyle)style;
- (int)setSharpening:(float)intensity;
- (int)setRosiness:(float)intensity;
- (int)setReshape:(FBReshape)param intensity:(float)value;
- (int)setBodyReshape:(FBBodyReshape)param intensity:(float)value;
- (int)setBeautySkinOnly:(BOOL)enabled;

- (int)setLipstick:(float)intensity;
- (int)setLipstickColor:(FBLipstickColor)color;
- (int)setBlush:(float)intensity;
- (int)setBlushStyle:(FBBlushStyle)style;
- (int)setBlushColor:(FBBlushColor)color;
- (int)setContour:(float)intensity;
- (int)setContourStyle:(FBContourStyle)style;
- (int)setEyeShadow:(float)intensity;
- (int)setEyeShadowStyle:(FBEyeShadowStyle)style;
- (int)setEyeShadowColor:(FBEyeShadowColor)color;
- (int)setEyeLiner:(float)intensity;
- (int)setEyeLinerStyle:(FBEyeLinerStyle)style;
- (int)setEyeLinerColor:(FBEyeLinerColor)color;
- (int)setEyebrow:(float)intensity;
- (int)setEyebrowStyle:(FBEyebrowStyle)style;
- (int)setEyebrowColor:(FBEyebrowColor)color;
- (int)setEyelash:(float)intensity;
- (int)setEyelashStyle:(FBEyelashStyle)style;
- (int)setEyelashColor:(FBEyelashColor)color;
- (int)setPupil:(float)intensity;
- (int)setPupilColor:(FBPupilColor)color;

- (int)setChromaKey:(FBChromaKeyColor)color;
- (int)clearChromaKey;
- (int)setChromaKeySimilarity:(float)value;
- (int)setChromaKeySmoothness:(float)value;
- (int)setChromaKeyDesaturation:(float)value;
- (int)setVirtualBackgroundBlur:(float)level;
- (int)setVirtualBackground:(NSString *)imagePath;
- (int)setVirtualBackgroundWithData:(NSData *)imageData;
- (int)clearVirtualBackground;

- (int)setFilter:(NSString *)fbdFilePath;
- (int)setFilterWithData:(NSData *)fbdData;
- (int)clearFilter;
- (int)setFilterIntensity:(float)intensity;
- (int)setSticker:(NSString *)fbdFilePath;
- (int)setStickerWithData:(NSData *)fbdData;
- (int)clearSticker;
- (int)addResourcePack:(NSString *)fbdFilePath;
- (int)addResourcePackWithData:(NSData *)fbdData;
- (int)set3DSticker:(NSString *)resource;
- (int)set3DStickerWithData:(NSData *)fbdData;
- (int)clear3DSticker;

- (FBEngineStats *)getStats;
- (int)setCallbacks:(FBEngineCallbacks *)callbacks;
- (FBImageFrame * _Nullable)processImage:(FBImageFrame *)imageFrame;

@end
```

`createEngineWithConfig:`는 실패 시 `nil`을 반환합니다. 정수 메서드는 `FBErrorCode`를 반환합니다(`0` = 성공).

### 피부

| 메서드                  | 범위 / 참고                        |
| -------------------- | ------------------------------ |
| `setSmoothing:`      | `[0, 1]` 강도                    |
| `setSmoothingStyle:` | 스타일; 강도는 여전히 `setSmoothing:`에서 |
| `setWhitening:`      | `[0, 1]`                       |
| `setWhiteningStyle:` | 화이트닝 LUT를 바꿈                   |
| `setSharpening:`     | `[0, 1]`                       |
| `setRosiness:`       | `[0, 1]`                       |
| `setBeautySkinOnly:` | `YES` = 피부 영역만                 |

### 리셰이프

`setReshape:intensity:` — 강도 **`[-1.0, 1.0]`**, `0`은 꺼짐. `FBReshape` 값 `0`–`25`: `FBReshape_FaceThin` … `FBReshape_BrowThickness`. 방향: [파라미터 열거형](/ko/intro/makeup).

```objc theme={null}
typedef NS_ENUM(NSInteger, FBReshape) {
  FBReshape_FaceThin = 0,
  FBReshape_FaceVShape = 1,
  FBReshape_FaceNarrow = 2,
  FBReshape_FaceShort = 3,
  FBReshape_Cheekbone = 4,
  FBReshape_Jawbone = 5,
  FBReshape_Chin = 6,
  FBReshape_NoseSlim = 7,
  FBReshape_EyeSize = 8,
  FBReshape_EyeDistance = 9,
  FBReshape_FaceSmall = 10,
  FBReshape_Forehead = 11,
  FBReshape_NoseLong = 12,
  FBReshape_Philtrum = 13,
  FBReshape_MouthSize = 14,
  FBReshape_MouthPosition = 15,
  FBReshape_MouthSmile = 16,
  FBReshape_LipThickness = 17,
  FBReshape_EyeRound = 18,
  FBReshape_EyePosition = 19,
  FBReshape_EyeAngle = 20,
  FBReshape_EyeCornerOpen = 21,
  FBReshape_LowerEyelid = 22,
  FBReshape_BrowPosition = 23,
  FBReshape_BrowDistance = 24,
  FBReshape_BrowThickness = 25,
};
```

### 바디 리셰이프

`setBodyReshape:intensity:` — 강도 **`[0.0, 1.0]`**, `0`은 꺼짐. 먼저 `addResourcePack:`으로 `resource_body.fbd`를 등록하세요. `FBBodyReshape` 값 `0`–`8`. [파라미터 열거형](/ko/intro/makeup)과 [선택 리소스 팩](/ko/intro/resource-packs)을 참고하세요.

```objc theme={null}
typedef NS_ENUM(NSInteger, FBBodyReshape) {
  FBBodyReshape_BodySlim = 0,
  FBBodyReshape_WaistSlim = 1,
  FBBodyReshape_LegSlim = 2,
  FBBodyReshape_ShoulderSlim = 3,
  FBBodyReshape_ArmSlim = 4,
  FBBodyReshape_LegLong = 5,
  FBBodyReshape_BustEnhance = 6,
  FBBodyReshape_LegStretch = 7,
  FBBodyReshape_TorsoLong = 8,
};
```

`FBSmoothingStyle`: `Natural`, `Texture`, `Smooth`. `FBWhiteningStyle`: `ColdWhite`, `PinkWhite`, `WarmWhite`, `Wheat`, `Tan`.

### 메이크업

강도 메서드는 `[0, 1]`을 받습니다. 형태 / 색상 타입: [파라미터 열거형](/ko/intro/makeup).

| 강도              | 스타일                  | 색상                   |
| --------------- | -------------------- | -------------------- |
| `setLipstick:`  | —                    | `setLipstickColor:`  |
| `setBlush:`     | `setBlushStyle:`     | `setBlushColor:`     |
| `setContour:`   | `setContourStyle:`   | —                    |
| `setEyeShadow:` | `setEyeShadowStyle:` | `setEyeShadowColor:` |
| `setEyeLiner:`  | `setEyeLinerStyle:`  | `setEyeLinerColor:`  |
| `setEyebrow:`   | `setEyebrowStyle:`   | `setEyebrowColor:`   |
| `setEyelash:`   | `setEyelashStyle:`   | `setEyelashColor:`   |
| `setPupil:`     | —                    | `setPupilColor:`     |

### 가상 배경과 크로마키

| 메서드                             | 설명                                     |
| ------------------------------- | -------------------------------------- |
| `setChromaKey:`                 | 초록 / 파랑 / 빨강에서 마스크. 채우기는 여전히 블러 또는 이미지 |
| `clearChromaKey`                | 인물 세그멘테이션 마스크를 복원; 채우기는 **지우지 않음**     |
| `setChromaKeySimilarity:`       | 키 타이트니스 `[0, 1]`                       |
| `setChromaKeySmoothness:`       | 가장자리 페더 `[0, 1]`                       |
| `setChromaKeyDesaturation:`     | 스필 억제 `[0, 1]`                         |
| `setVirtualBackgroundBlur:`     | 블러 채우기 `[0, 1]`; `0`은 가상 배경을 지움        |
| `setVirtualBackground:`         | png/jpg 파일 경로(비어 있으면 안 됨)              |
| `setVirtualBackgroundWithData:` | 인코딩된 png/jpg `NSData`                  |
| `clearVirtualBackground`        | 블러와 이미지 채우기를 지움                        |

```objc theme={null}
typedef NS_ENUM(NSInteger, FBChromaKeyColor) {
  FBChromaKeyColor_Green = 0,
  FBChromaKeyColor_Blue,
  FBChromaKeyColor_Red,
};
```

### 필터와 스티커

ID로 등록하는 API는 없습니다. 경로 또는 바이트; GPU 리소스는 다음 `processImage:`(GL 스레드 / 외부 컨텍스트)에서 만들어집니다.

| 메서드                        | 설명                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------- |
| `setFilter:`               | `.fbd` 경로에서 LUT                                                                             |
| `setFilterWithData:`       | `.fbd` 바이트에서 LUT                                                                            |
| `clearFilter`              | LUT 제거                                                                                      |
| `setFilterIntensity:`      | `[0, 1]`                                                                                    |
| `setSticker:`              | 2D 스티커 `.fbd` 경로                                                                            |
| `setStickerWithData:`      | 스티커 바이트                                                                                     |
| `addResourcePack:`         | 추가 기능 팩 경로(예: `set3DSticker:` 전 `resource_3d.fbd`, `setBodyReshape:` 전 `resource_body.fbd`) |
| `addResourcePackWithData:` | 추가 팩 바이트                                                                                    |
| `set3DSticker:`            | 3D 스티커 `.fbd` 경로                                                                            |
| `set3DStickerWithData:`    | 3D 스티커 바이트                                                                                  |
| `clear3DSticker`           | 3D 스티커 제거                                                                                   |
| `clearSticker`             | 스티커 제거                                                                                      |

빈 경로 / nil 또는 빈 `NSData` → `FBErrorCode_InvalidArgument`.

### 처리

```objc theme={null}
- (FBImageFrame * _Nullable)processImage:(FBImageFrame *)imageFrame;
```

`imageFrame.type`(`FBFrameTypeImage` 또는 `FBFrameTypeVideo`)을 읽습니다. 출력 형식은 입력과 일치합니다. 실패 시 `nil`을 반환합니다.

## 오류 코드

```objc theme={null}
typedef NS_ENUM(NSInteger, FBErrorCode) {
  FBErrorCode_Success = 0,
  FBErrorCode_InvalidArgument = -1,
  FBErrorCode_NotInitialized = -2,
  FBErrorCode_License = -3,
  FBErrorCode_Unsupported = -4,
  FBErrorCode_IO = -5,
  FBErrorCode_NoSlot = -6,
  FBErrorCode_Process = -7,
  FBErrorCode_OutOfMemory = -8,
};
```

`-1`은 잘못된 인자입니다. `-2`는 초기화되지 않음입니다.

## 통계와 콜백

### `FBEngineStats`

| 속성                 | 타입       | 설명                        |
| ------------------ | -------- | ------------------------- |
| `fps`              | `double` | 초당 프레임                    |
| `avgProcessTimeMs` | `double` | 평균 `processImage:` 시간(ms) |
| `sessionTimeS`     | `double` | 세션 시간(초)                  |

```objc theme={null}
- (FBEngineStats *)getStats;
```

### `FBEngineEventCode`

| 값     | 심볼                                          |
| ----- | ------------------------------------------- |
| `0`   | `FBEngineEventCodeLicenseValidationSuccess` |
| `1`   | `FBEngineEventCodeLicenseValidationFailed`  |
| `100` | `FBEngineEventCodeInitializationComplete`   |
| `101` | `FBEngineEventCodeInitializationFailed`     |

### `FBEngineCallbacks`

```objc theme={null}
FB_OBJC_API @interface FBEngineCallbacks : NSObject
@property(nonatomic, copy, nullable) void (^onFaceLandmarks)
    (NSArray<FBFaceDetectionResult *> * _Nullable results);
@property(nonatomic, copy, nullable) void (^onEngineEvent)
    (FBEngineEventCode code, NSString * _Nullable message);
@end
```

### 얼굴 결과 타입

```objc theme={null}
FB_OBJC_API @interface FBPoint2d : NSObject
@property(nonatomic, assign) float x;
@property(nonatomic, assign) float y;
- (instancetype)initWithX:(float)x y:(float)y;
@end

FB_OBJC_API @interface FBRect : NSObject
@property(nonatomic, assign) float x;
@property(nonatomic, assign) float y;
@property(nonatomic, assign) float width;
@property(nonatomic, assign) float height;
- (instancetype)initWithX:(float)x y:(float)y width:(float)width height:(float)height;
@end

FB_OBJC_API @interface FBFaceDetectionResult : NSObject
@property(nonatomic, strong) FBRect *rect;
@property(nonatomic, copy, nullable) NSArray<FBPoint2d *> *keyPoints;  // 111 points
@property(nonatomic, copy, nullable) NSArray<NSNumber *> *visibility;  // [0, 1]
@property(nonatomic, assign) int faceId;
@property(nonatomic, assign) float score;
@property(nonatomic, assign) float pitch;  // up -, down +; [-π, π]
@property(nonatomic, assign) float roll;   // left -, right +
@property(nonatomic, assign) float yaw;    // left -, right +
@end
```

## `FBImageFrame`

### 생성

| 메서드                                      | 참고                                                 |
| ---------------------------------------- | -------------------------------------------------- |
| `createWithData:width:height:format:`    | 원시 버퍼 + `FBImageFormat`                            |
| `createWithRGBA:width:height:stride:`    |                                                    |
| `createWithBGRA:width:height:stride:`    |                                                    |
| `createWithRGB:width:height:stride:`     |                                                    |
| `createWithBGR:width:height:stride:`     |                                                    |
| `createWithI420:...`                     | Y / U / V 평면                                       |
| `createWithNV12:...`                     | Y + UV                                             |
| `createWithNV21:...`                     | Y + VU                                             |
| `createWithFile:`                        | png / jpg 경로                                       |
| `createWithTexture:width:height:stride:` | 현재 컨텍스트의 `GL_TEXTURE_2D`; `stride`는 보통 `width * 4` |
| `createWithUIImage:`                     | **iOS 전용**                                         |

### 작업

| 메서드               | 설명                                                        |
| ----------------- | --------------------------------------------------------- |
| `rotate:`         | `FBImageRotation`; `FBErrorCode` 반환                       |
| `mirror:`         | `"horizontal"` / `"vertical"` / `"both"`(대소문자 무시); 픽셀을 변경 |
| `setMirror:`      | `processImage:`용 플래그(추가 변환을 피함). `nil` / `@""`는 지움        |
| `convert:`        | 대상 `FBImageFormat`의 새 프레임을 반환                             |
| `toFile:quality:` | quality `0`–`100`                                         |
| `toFile:`         | quality `90`                                              |

### 속성과 접근자

`width`, `height`, `stride`, `size`, `type`. 메서드: `data`, `format`, `texture`(텍스처가 아니면 `0`). YUV: `dataY` / `dataU` / `dataV` / `dataUV`, `strideY` / `strideU` / `strideV` / `strideUV`(YUV가 아니면 `NULL` / `0`).

```objc theme={null}
typedef NS_ENUM(NSInteger, FBImageFormat) {
  FBImageFormatI420,
  FBImageFormatNV12,
  FBImageFormatNV21,
  FBImageFormatBGRA,
  FBImageFormatRGBA,
  FBImageFormatBGR,
  FBImageFormatRGB,
  FBImageFormatTexture,
};

typedef NS_ENUM(NSInteger, FBImageRotation) {
  FBImageRotation0,
  FBImageRotation90,   // clockwise
  FBImageRotation180,
  FBImageRotation270,
};
```

```objc theme={null}
FBImageFrame *frame = [FBImageFrame createWithUIImage:image];
frame.type = FBFrameTypeImage;
FBImageFrame *out = [engine processImage:frame];
```

## 메이크업 / 스타일 열거형

Objective-C 심볼은 `FBBeautyParams.h`에 있습니다. 의미 테이블은 여기에 중복하지 않습니다. [파라미터 열거형](/ko/intro/makeup)을 참고하세요.

* `FBSmoothingStyle`, `FBWhiteningStyle`
* `FBLipstickColor`
* `FBBlushStyle`, `FBBlushColor`
* `FBContourStyle`
* `FBEyeShadowStyle`, `FBEyeShadowColor`
* `FBEyeLinerStyle`, `FBEyeLinerColor`
* `FBEyebrowStyle`, `FBEyebrowColor`
* `FBEyelashStyle`, `FBEyelashColor`
* `FBPupilColor`