集成 SDK
如果您不想使用 UIKit,而是直接实现核心 SDK 接口调用,也可以参考本指南进行集成。
美颜特效 SDK 集成整体流程


集成准备
开发者环境要求
开发工具 Xcode 11 以上:从 App Store 下载或单击查看 下载地址。
建议运行环境:
设备要求:iPhone 5及以上;iPhone 6及以下前置摄像头最多支持到720p,不支持1080p。
系统要求:iOS 12.2及以上。
导入 SDK
您可以选择使用 CocoaPods 方案,或者先将 SDK 下载到本地,再将其手动导入到您当前的项目中。
1. 安装 CocoaPods
在终端窗口中输入如下命令(需要提前在 Mac 中安装 Ruby 环境):
sudo gem install cocoapods
2. 创建 Podfile 文件
进入项目所在路径,输入以下命令行之后项目路径下会出现一个 Podfile 文件。
pod init
3. 编辑 Podfile 文件
XMagic 版本在3.0.1以前:
根据您的项目需要选择合适的版本,并编辑 Podfile 文件:
XMagic 普通版
请按如下方式编辑 Podfile 文件:
platform :ios, '8.0'target 'App' dopod 'XMagic'end
XMagic 精简版
安装包体积比普通版小,但仅支持基础版 A1-00、基础版 A1-01、高级版 S1-00,请按如下方式编辑 Podfile 文件:
platform :ios, '8.0'target 'App' dopod 'XMagic_Smart'end
XMagic 版本在3.0.1及以后:
根据您的项目套餐选择合适的版本,并编辑 Podfile 文件:
#请根据您的套餐pod install对应的库#例如:如果您的套餐是all类型,那么只需要pod 'TencentEffect_All'#例如:如果您的套餐是S1-04类型,那么只需要pod 'TencentEffect_S1-04'pod 'TencentEffect_All'#pod 'TencentEffect_A1-00'#pod 'TencentEffect_A1-01'#pod 'TencentEffect_A1-02'#pod 'TencentEffect_A1-03'#pod 'TencentEffect_A1-04'#pod 'TencentEffect_A1-05'#pod 'TencentEffect_A1-06'#pod 'TencentEffect_S1-00'#pod 'TencentEffect_S1-01'#pod 'TencentEffect_S1-02'#pod 'TencentEffect_S1-03'#pod 'TencentEffect_S1-04'#pod 'TencentEffect_S1-05'#pod 'TencentEffect_S1-06'#pod 'TencentEffect_S1-07'#pod 'TencentEffect_X1-01'#pod 'TencentEffect_X1-02'
4. 更新并安装 SDK
在终端窗口中输入如下命令以更新本地库文件,并安装 SDK:
pod install
pod 命令执行完后,会生成集成了 SDK 的
.xcworkspace
后缀的工程文件,双击打开即可。5. 添加美颜资源到实际项目工程中
5.1 下载并解压对应套餐的 SDK 和美颜资源,将 resources/motionRes 文件夹下 bundle 资源添加到实际工程中。
5.2 在 Build Settings 中的 Other Linker Flags 添加
-ObjC
。6. 将 Bundle Identifier 修改成与申请的测试授权一致。
1. 下载并解压 SDK 和美颜资源,frameworks 文件夹里面是 sdk、resources 文件夹里面是美颜的 bundle 资源。
2. SDK 版本在2.5.1以前:
打开您的 Xcode 工程项目,把 frameworks 文件夹里面的 framework 添加到实际工程中。选择要运行的 target , 选中 General 项,单击 Frameworks,Libraries,and Embedded Content 项展开,单击底下的“+”号图标去添加依赖库。依次添加下载的
XMagic.framework
、YTCommonXMagic.framework
、libpag.framework
及其所需依赖库MetalPerformanceShaders.framework
、CoreTelephony.framework
、JavaScriptCore.framework
、VideoToolbox.framework
、libc++.tbd
。根据需要添加其它工具库 Masonry.framework
(控件布局库)、SSZipArchive
(文件解压库)。

SDK版本在2.5.1及以后:
打开您的 Xcode 工程项目,把 frameworks 文件夹里面的 framework 添加到实际工程中。选择要运行的 target , 选中 General 项,单击Frameworks,Libraries,and Embedded Content 项展开,单击底下的“+”号图标去添加依赖库。依次添加下载的
XMagic.framework
、YTCommonXMagic.framework
、libpag.framework
、Audio2Exp.framework
、TEFFmpeg.framework(version3.0.0以后,改名为:TECodec.framework)
及其所需依赖库 MetalPerformanceShaders.framework
、CoreTelephony.framework
、JavaScriptCore.framework
、VideoToolbox.framework
、libc++.tbd
。根据需要添加其它工具库 Masonry.framework
(控件布局库)、SSZipArchive
(文件解压库)。
3. 把 resources 夹里面的美颜资源添加到实际工程中。
4. 在 Build Settings 中的 Other Linker Flags 添加
-ObjC
。5. 将 Bundle Identifier 修改成与申请的测试授权一致。
为了减少包大小,您可以将 SDK 所需的模型资源和动效资源 MotionRes(部分基础版 SDK 无动效资源)改为联网下载。在下载成功后,将上述文件的路径设置给 SDK。
配置权限
在 Info.plist 文件中添加相应权限的说明,否则程序在 iOS 10 系统上会出现崩溃。请在 Privacy - Camera Usage Description 中开启相机权限,允许 App 使用相机。
集成步骤
步骤一:鉴权
1. 申请授权,得到 LicenseURL 和 LicenseKEY,请参见 License 指引。
2. 在相关业务模块的初始化代码中设置 URL 和 KEY,触发 license 下载,避免在使用前才临时去下载。也可以在 AppDelegate 的 didFinishLaunchingWithOptions 方法里触发下载。其中,LicenseURL 和 LicenseKey 是控制台绑定 License 时生成的授权信息。
SDK 版本在2.5.1以前,
TELicenseCheck.h
在XMagic.framework
里面;SDK 版本在2.5.1及以后,TELicenseCheck.h
在 YTCommonXMagic.framework
里面。[TELicenseCheck setTELicense:LicenseURL key:LicenseKey completion:^(NSInteger authresult, NSString * _Nonnull errorMsg) {if (authresult == TELicenseCheckOk) {NSLog(@"鉴权成功");} else {NSLog(@"鉴权失败");}}];
鉴权 errorCode 说明:
错误码 | 说明 |
0 | 成功。Success |
-1 | 输入参数无效,例如 URL 或 KEY 为空 |
-3 | 下载环节失败,请检查网络设置 |
-4 | 从本地读取的 TE 授权信息为空,可能是 IO 失败引起 |
-5 | 读取 VCUBE TEMP License文件内容为空,可能是 IO 失败引起 |
-6 | v_cube.license 文件 JSON 字段不对。请联系腾讯云团队处理 |
-7 | 签名校验失败。请联系腾讯云团队处理 |
-8 | 解密失败。请联系腾讯云团队处理 |
-9 | TELicense 字段里的 JSON 字段不对。请联系腾讯云团队处理 |
-10 | 从网络解析的TE授权信息为空。请联系腾讯云团队处理 |
-11 | 把 TE 授权信息写到本地文件时失败,可能是 IO 失败引起 |
-12 | 下载失败,解析本地 asset 也失败 |
-13 | 鉴权失败 |
其他 | 请联系腾讯云团队处理 |
步骤二:加载 SDK(XMagic.framework)
使用美颜特效 SDK 生命周期大致如下:
1. 加载美颜相关资源。
NSDictionary *assetsDict = @{@"core_name":@"LightCore.bundle",@"root_path":[[NSBundle mainBundle] bundlePath] // LightCore.bundle所在的目录。};
2. 初始化美颜特效 SDK。
/**previewSize:视图的宽高assetsDict:上一步配置的LightCore.bundle及其路径*/self.xMagicApi = [[XMagic alloc] initWithRenderSize:previewSize assetsDict:assetsDict];
3. 美颜特效 SDK 处理每帧数据并返回相应处理结果。
/**以设备摄像头数据输出为例*///sampleBuffer:设备摄像头输出的数据-(CMSampleBufferRef)didProcessCPUData:(CMSampleBufferRef)sampleBuffer{CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);YTProcessInput *input = [[YTProcessInput alloc] init];input.pixelData = [[YTImagePixelData alloc] init];input.pixelData.data = pixelBuffer;input.dataType = kYTImagePixelData;YTProcessOutput *output = [self.xMagicKit process:input];if (output.pixelData.data != nil) { //output.pixelData.data:美颜SDK处理以后的数据CMSampleBufferRef outSampleBuffer = [self sampleBufferFromPixelBuffer:output.pixelData.data];return outSampleBuffer;}return nil;}//PixelBuffer转sampleBuffer- (CMSampleBufferRef)sampleBufferFromPixelBuffer:(CVPixelBufferRef)pixelBuffer{CFRetain(pixelBuffer);CMSampleBufferRef outputSampleBuffer = NULL;CMSampleTimingInfo timing = {kCMTimeInvalid, kCMTimeInvalid, kCMTimeInvalid};CMVideoFormatDescriptionRef videoInfo = NULL;OSStatus result = CMVideoFormatDescriptionCreateForImageBuffer(NULL, pixelBuffer, &videoInfo);result = CMSampleBufferCreateForImageBuffer(kCFAllocatorDefault, pixelBuffer, true, NULL, NULL, videoInfo, &timing, &outputSampleBuffer);CFArrayRef attachments = CMSampleBufferGetSampleAttachmentsArray(outputSampleBuffer, YES);CFMutableDictionaryRef dict = (CFMutableDictionaryRef)CFArrayGetValueAtIndex(attachments, 0);CFDictionarySetValue(dict, kCMSampleAttachmentKey_DisplayImmediately, kCFBooleanTrue);CFRelease(videoInfo);CFRelease(pixelBuffer);return outputSampleBuffer;}
4. 释放美颜特效 SDK。
// 在需要释放SDK资源的地方调用[self.xMagicApi deinit]
说明:
完成上述步骤后,用户即可根据自己的实际需求控制展示时机以及其他设备相关环境。