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

# FAQ

> macOS Facebetter SDK 2.0 자주 묻는 질문

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

## 연동

### 엔진 생성이 `nil`을 반환함

* `licenseToken` **또는** `appId` + `appKey`가 설정되어 있는지 확인하세요. 둘 다 있으면 토큰이 우선합니다.
* Mac **Bundle ID**를 바인딩하세요(CLI 도구: 프로세스 이름).
* 온라인 인증에는 App Sandbox의 **Outgoing Connections**와 `/facebetter/v2/auth` 경로가 필요합니다.
* `createEngineWithConfig:` **전에** 로그를 켜고 이벤트 `1` / `101`을 확인하세요.
* CocoaPods: `pod 'Facebetter', '2.0.0'`. `.xcworkspace`를 여세요.

### 헤더 또는 클래스가 없음

* `#import <Facebetter/FBBeautyEffectEngine.h>`를 임포트하세요.
* 수동 `.framework`: **Embed & Sign**.
* Xcode 15+ CocoaPods 샌드박스: `ENABLE_USER_SCRIPT_SANDBOXING`을 **No**로 설정하세요.

### 런타임 링크 / dyld 오류

* 아키텍처: **x86\_64**와 **arm64**.
* 배포 타깃 **macOS 10.15+**.

## 인증

### `licenseToken` vs `appId` / `appKey`

`licenseToken`이 비어 있지 않으면 SDK는 해당 토큰 / `{token}` JSON / `.lic`를 로컬에서 검증합니다. 그렇지 않으면 온라인 인증을 사용합니다. 자세한 내용: [인증 및 라이선스](/ko/intro/license).

### 이벤트 `1` 또는 `101`

라이선스 또는 초기화가 실패했습니다. Bundle ID, 샌드박스 네트워크, 토큰 만료, 로그를 확인하세요.

## 뷰티

### 효과가 너무 약하거나 너무 강함

* 피부 / 메이크업 / 필터: `[0.0, 1.0]`.
* 리셰이프: `setReshape:intensity:`로 **`[-1.0, 1.0]`**.
* 강도 `0`은 해당 효과를 끕니다.
* 피부만: `setBeautySkinOnly:`.

프리셋 이름: [파라미터 열거형](/ko/intro/makeup).

## 필터, 스티커, 가상 배경

`.fbd` 경로 또는 바이트를 전달하세요. 샌드박스 앱은 해당 경로를 읽을 수 있어야 합니다.

```objc theme={null}
[engine setFilter:fbdPath];
[engine setFilterIntensity:0.8f];
[engine clearFilter];
[engine setSticker:fbdPath];
[engine clearSticker];
```

가상 배경:

```objc theme={null}
[engine setVirtualBackgroundBlur:0.6f];
[engine setVirtualBackground:imagePath];
[engine setVirtualBackgroundWithData:imageData];
[engine clearVirtualBackground];
[engine setChromaKey:FBChromaKeyColor_Green];
[engine clearChromaKey];
```

## 처리

### `processImage:`가 `nil`을 반환함

잘못된 프레임, 초기화 실패, 또는 `externalContext = YES`인데 현재 GL 컨텍스트가 없는 경우입니다.

### 프레임 유형

`imageFrame.type`을 `FBFrameTypeImage`(`0`) 또는 `FBFrameTypeVideo`(`1`)로 설정하세요. 처리 모드 인자는 없습니다.

### 형식 변환

`convert:`를 사용하세요.

```objc theme={null}
FBImageFrame *rgba = [frame convert:FBImageFormatRGBA];
const uint8_t *data = [rgba data];
```

### NSImage

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

### 카메라

1. `AVCaptureVideoDataOutput` → `CVPixelBuffer`.
2. `createWithNV12:...` 또는 `createWithBGRA:...`.
3. `type = FBFrameTypeVideo`, 선택적으로 `setMirror:@"horizontal"`.
4. AppKit / OpenGL 뷰에서 `[output data]` 또는 `[output texture]`를 표시합니다.

## 성능

* 라이브에는 `FBFrameTypeVideo`를 사용하고 `getStats`를 확인하세요.
* 엔진은 하나, 직렬 큐입니다.
* 창이 최소화되면 캡처를 일시 중지하세요.

## 로깅

```objc theme={null}
[FBBeautyEffectEngine setLogConfig:logConfig];  // before createEngineWithConfig:
```

로그는 샌드박스 컨테이너 안에 쓰세요. 반환 코드: [오류 처리](/ko/macos/error-handling).

## 버전

* **macOS 10.15+**, **x86\_64** + **arm64**.
* CocoaPods: `pod 'Facebetter', '2.0.0'`.
* Universal Binary: xcframework에 두 슬라이스가 있는지 확인하세요(`lipo -info`).

## 샌드박스와 App Store

* 온라인 인증을 위한 아웃바운드 네트워크.
* 카메라용 `NSCameraUsageDescription`.
* 사용자가 선택한 파일에는 security-scoped bookmark.
* 프라이빗 API를 사용하지 마세요. 라이브 비디오는 메인 스레드에서 엔진을 돌리지 마세요.