本文档对应 SDK 2.0.0。授权见 授权与许可。
错误码（FBErrorCode）
设置类接口返回 int，0 表示成功。createEngineWithConfig: 与 processImage: 返回对象，失败为 nil。
| 值 | 符号 | 含义 |
|---|---|---|
0 | FBErrorCode_Success | 成功 |
-1 | FBErrorCode_InvalidArgument | 参数无效（空配置、空路径、越界等） |
-2 | FBErrorCode_NotInitialized | 引擎未初始化 |
-3 | FBErrorCode_License | 授权失败 |
-4 | FBErrorCode_Unsupported | 不支持的格式、平台或能力 |
-5 | FBErrorCode_IO | 文件 / 资源读写失败 |
-6 | FBErrorCode_NoSlot | 无可用槽位（例如人脸过多） |
-7 | FBErrorCode_Process | 帧处理失败 |
-8 | FBErrorCode_OutOfMemory | 内存不足 |
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,
};
检查返回值
FBLogConfig *logConfig = [[FBLogConfig alloc] init];
logConfig.consoleEnabled = YES;
logConfig.level = FBLogLevel_Info;
int logRet = [FBBeautyEffectEngine setLogConfig:logConfig];
if (logRet != FBErrorCode_Success) {
NSLog(@"setLogConfig failed: %d", logRet);
}
FBEngineConfig *config = [[FBEngineConfig alloc] init];
config.appId = @"your_app_id";
config.appKey = @"your_app_key";
self.engine = [FBBeautyEffectEngine createEngineWithConfig:config];
if (self.engine == nil) {
NSLog(@"创建引擎失败（检查授权、Bundle ID 和日志）");
return;
}
int ret = [self.engine setSmoothing:0.5f];
if (ret != FBErrorCode_Success) {
NSLog(@"setSmoothing failed: %d", ret);
}
NSString *FBErrorMessage(int code) {
switch (code) {
case FBErrorCode_Success: return @"成功";
case FBErrorCode_InvalidArgument: return @"参数无效";
case FBErrorCode_NotInitialized: return @"引擎未初始化";
case FBErrorCode_License: return @"授权失败";
case FBErrorCode_Unsupported: return @"不支持";
case FBErrorCode_IO: return @"读写失败";
case FBErrorCode_NoSlot: return @"无可用槽位";
case FBErrorCode_Process: return @"处理失败";
case FBErrorCode_OutOfMemory: return @"内存不足";
default: return [NSString stringWithFormat:@"未知 (%d)", code];
}
}
引擎事件
FBEngineCallbacks.onEngineEvent 异步上报授权与初始化。创建引擎后立刻设置回调。
| 码 | 符号 | 含义 |
|---|---|---|
0 | FBEngineEventCodeLicenseValidationSuccess | 授权成功 |
1 | FBEngineEventCodeLicenseValidationFailed | 授权失败 |
100 | FBEngineEventCodeInitializationComplete | 初始化完成 |
101 | FBEngineEventCodeInitializationFailed | 初始化失败 |
FBEngineCallbacks *callbacks = [[FBEngineCallbacks alloc] init];
callbacks.onEngineEvent = ^(FBEngineEventCode code, NSString * _Nullable message) {
switch (code) {
case FBEngineEventCodeLicenseValidationFailed:
NSLog(@"授权失败: %@", message);
break;
case FBEngineEventCodeInitializationFailed:
NSLog(@"初始化失败: %@", message);
break;
default:
break;
}
};
[self.engine setCallbacks:callbacks];
createEngineWithConfig: 返回非 nil 并不等于授权已成功。在线授权仍可能随后失败，请监听事件 1 / 101。图像处理
校验帧、设置type，将 nil 视为处理失败（FBErrorCode_Process）。
- (FBImageFrame *)processSafely:(FBImageFrame *)input {
if (input == nil || input.width <= 0 || input.height <= 0) {
NSLog(@"Invalid FBImageFrame");
return nil;
}
input.type = FBFrameTypeVideo;
FBImageFrame *output = [self.engine processImage:input];
if (output == nil) {
NSLog(@"processImage returned nil");
}
return output;
}
toFile:（返回 FBErrorCode）：
int saved = [output toFile:path quality:90];
if (saved != FBErrorCode_Success) {
NSLog(@"toFile failed: %d", saved);
}
日志
在创建引擎之前打开日志。写文件时先创建目录。NSString *logPath = [NSTemporaryDirectory() stringByAppendingPathComponent:@"facebetter.log"];
NSString *logDir = [logPath stringByDeletingLastPathComponent];
[[NSFileManager defaultManager] createDirectoryAtPath:logDir
withIntermediateDirectories:YES
attributes:nil
error:nil];
FBLogConfig *logConfig = [[FBLogConfig alloc] init];
logConfig.consoleEnabled = YES;
logConfig.fileEnabled = YES;
logConfig.level = FBLogLevel_Debug;
logConfig.fileName = logPath;
[FBBeautyEffectEngine setLogConfig:logConfig];
常见原因
-1参数无效：空.fbd路径、NSData为 nil、强度越界、配置为 nil。-2未初始化：createEngineWithConfig:失败后实例为nil，不要再发消息。-3授权：appId/appKey错误、未绑定 Bundle ID、token 过期，或在线授权无网络。见 授权与许可。-5I/O：滤镜 / 贴纸 / 背景文件缺失或沙盒不可读。- 外部 GL：
externalContext = YES时必须在同一 OpenGL ES 线程创建并处理，否则processImage:可能返回nil。