短视频 SDK iOS

开发者环境要求
开发工具 Xcode 11 以上。
设备要求：iPhone 5 及以上；iPhone 6 及以下前置摄像头最多支持到 720p，不支持 1080p。
系统要求：iOS 12.2 及以上。
导入 SDK
美颜特效 SDK 支持 CocoaPods、Swift Package Manager 和本地手动集成方案。
CocoaPods集成
Swift Package Manager 集成
手动集成
1. 安装 CocoaPods
在终端窗口中输入如下命令（如已安装可忽略）：
sudo gem install cocoapods
2. 创建 Podfile 文件
进入项目所在路径，输入以下命令行之后项目路径下会出现一个 Podfile 文件。
pod init
3. 编辑 Podfile 文件
根据您的项目套餐选择合适的版本，并编辑 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
5. 在 Build Settings 中的 Other Linker Flags 添加 -ObjC。
6. 将 Bundle Identifier 修改成与申请的测试授权一致。
从 4.2.0.21 版本开始，美颜特效 SDK 支持 Swift Package Manager（简称 SPM）集成。
1. 选择 Package 仓库
SDK 按套餐拆分为两个 SPM 仓库，请根据您购买的套餐选择：
套餐
SPM 仓库地址
A1-00、A1-01、S1-00
﻿https://github.com/Tencent-RTC/TencentEffect_Basic_SwiftPM.git﻿
A1-02 ~ A1-06、S1-01 ~ S1-07、X1-01、X1-02、All
﻿https://github.com/Tencent-RTC/TencentEffect_SwiftPM.git﻿
2. 添加 Package
打开 Xcode 项目，选择 File > Add Package Dependencies...，在搜索框中粘贴上述对应仓库的 URL，等待加载完成后单击 Add Package。
3. 选择版本
在 Choose Package Options 中设置依赖规则（Dependency Rule），建议选择 Up to Next Major Version 自动获取最新兼容版本。
4. 选择套餐
在 Choose Package Products 中选择要集成的 Product 与目标 Target。每个套餐提供三个 Product 变体：
Product 后缀
含义
无后缀，（如 TencentEffect_S1-07）
包含 SDK 二进制库与资源包（XMagicResources）。
_nobundle（如 TencentEffect_S1-07_nobundle）
仅包含 SDK 二进制库，不含资源包。
_nolibpag（如 TencentEffect_S1-07_nolibpag）
不含 libpag 库，含资源包。
5. 集成后配置
在 Build Settings 中的 Other Linker Flags 添加 -ObjC。
将 Bundle Identifier 修改成与申请的测试授权一致。
在 Info.plist 中添加相机权限说明（Privacy - Camera Usage Description）。
如果您的套餐包含动效和滤镜功能，仍需按下文“导入素材”章节下载并导入 motionRes 下的 bundle 素材；SPM 资源包仅提供 SDK 运行所需的 LightCore 等资源。
1. 下载并解压 SDK 和美颜资源，frameworks 文件夹里面是 SDK、resources 文件夹里面是美颜的 bundle 资源。
1.1 打开您的 Xcode 工程项目，把 frameworks 文件夹里面的 framework 添加到实际工程中。
1.2 选择要运行的 target，选中 General 项，单击 Frameworks,Libraries,and Embedded Content 项展开，单击底下的“+”号图标去添加依赖库。
1.3 依次添加下载的 XMagic.framework、YTCommonXMagic.framework、libpag.framework、TEFFmpeg.framework(version3.0.0以后，改名为：TECodec.framework)及其所需依赖库 MetalPerformanceShaders.framework、CoreTelephony.framework、JavaScriptCore.framework、VideoToolbox.framework、libc++.tbd，根据需要添加其它工具库 Masonry.framework（控件布局库）、SSZipArchive（文件解压库）。
﻿
2. 在 Build Settings 中的 Other Linker Flags 添加 -ObjC。
3. 将 Bundle Identifier 修改成与申请的测试授权一致。
导入素材
如果您的套餐包含动效和滤镜功能，那么需要在 SDK 下载页面 下载对应的套餐包，解压之后将 resources/motionRes 文件夹下的 bundle 按需导入主工程任意目录下，导入后如下图所示：
﻿
注意：
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 里面，只有鉴权成功后才能使用 SDK。
[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 初始化及使用
使用美颜特效 SDK 生命周期大致如下：
1. 初始化美颜特效 SDK。
/// root_path 传入 LightCore.bundle所在的目录。
NSDictionary *assetsDict = @{@"core_name" : @"LightCore.bundle",
                             @"root_path" : [[NSBundle mainBundle] bundlePath]};
self.xMagicApi = [[XMagic alloc] initWithRenderSize:previewSize assetsDict:assetsDict];
2. 美颜特效 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;
}
美颜 process 方法及更多 API 详情见 API 文档。
3. 释放美颜特效 SDK。
/// 在需要释放SDK资源的地方调用
[self.xMagicApi deinit];
说明：
完成上述步骤后，用户即可根据自己的实际需求控制展示时机以及其他设备相关环境。

套餐	SPM 仓库地址
A1-00、A1-01、S1-00	https://github.com/Tencent-RTC/TencentEffect_Basic_SwiftPM.git
A1-02 ~ A1-06、S1-01 ~ S1-07、X1-01、X1-02、All	https://github.com/Tencent-RTC/TencentEffect_SwiftPM.git

Product 后缀	含义
无后缀，（如 `TencentEffect_S1-07`）	包含 SDK 二进制库与资源包（XMagicResources）。
`_nobundle`（如 `TencentEffect_S1-07_nobundle`）	仅包含 SDK 二进制库，不含资源包。
`_nolibpag`（如 `TencentEffect_S1-07_nolibpag`）	不含 libpag 库，含资源包。

错误码	说明
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	鉴权失败。
其他	请联系腾讯云团队处理。

iOS

本页目录：

开发者环境要求

导入 SDK

导入素材

配置权限

使用流程

步骤一：鉴权

步骤二：SDK 初始化及使用