tencent cloud

iOS
下载PDF
最后更新时间：2025-10-15 15:25:28
iOS
最后更新时间： 2025-10-15 15:25:28
下载PDF

美颜特效 SDK 集成整体流程





集成准备

开发者环境要求

开发工具 Xcode 11 及以上：从 App Store 下载或单击查看 下载地址。
建议运行环境：
设备要求：iPhone 5 及以上；iPhone 6 及以下前置摄像头最多支持到 720p，不支持 1080p。
系统要求：iOS 10.0 及以上。

导入 SDK

您可以选择使用 CocoaPods 方案，或者先将 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' do
pod 'XMagic'
end
XMagic 精简版。
安装包体积比普通版小，但仅支持基础版 A1-00、基础版 A1-01、高级版 S1-00，请按如下方式编辑 Podfile 文件：
platform :ios, '8.0'

target 'App' do
pod '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. 添加美颜资源到实际项目工程中。
下载并解压对应套餐的 SDK 和美颜资源，将 resources/motionRes 文件夹下bundle 资源添加到实际工程中。在 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。
我们建议您复用 Demo 的下载逻辑，当然，也可以使用您已有的下载服务。动态下载的详细指引，请参见 SDK 包体瘦身（iOS）。

配置权限

在 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]
说明：
完成上述步骤后，用户即可根据自己的实际需求控制展示时机以及其他设备相关环境。
本页内容是否解决了您的问题？
您也可以 联系销售 或 提交工单 以寻求帮助。
是
否

文档反馈