帮你快速理解、总结文档立即下载

iOS

最近更新时间:2026-11-11 21:20:00
本文档已由 AI 辅助审校
我的收藏

准备工作

1. 开发环境

Xcode 12 及以上版本。
iOS 部署目标:iOS 12.0 及以上(TAVMagic.podspec 中 s.ios.deployment_target = '12.0')。
真机调试:编辑/录制能力依赖相机、麦克风与 Metal,模拟器仅可用于工程编译验证,功能请以真机为准。
CocoaPods(推荐)或手动集成。

2. 申请 License

参见 License 申请 的指引申请 License 后,从 腾讯云视立方控制台 复制 License Key 和 License URL,如下图所示:


SDK 集成

1. 在工程中添加依赖

方式一:CocoaPods(推荐)

platform :ios, '12.0'

target 'YourAppTarget' do
use_modular_headers!

pod 'TAVMagic', :podspec => 'https://mediacloud-76607.gzc.vod.tencent-cloud.com/TAVMagic/iOS/Release/1.7.1.0/TAVMagic.podspec'
pod 'TencentEffect_Edit', :podspec => 'https://mediacloud-76607.gzc.vod.tencent-cloud.com/TencentEffect/iOS/edit/4.3.0.5/TencentEffect_Edit.podspec'
end
执行 pod install 后打开 .xcworkspace。

方式二:手动集成

1. 下载 TAVMagic SDK 和 TencentEffect_Edit 将两个 SDK 整个文件夹拖入工程。
2. 在 Target → General → Frameworks, Libraries, and Embedded Content 中补充以下系统依赖:
AVFoundation.framework
CoreMedia.framework
CoreTelephony.framework
JavaScriptCore.framework
Metal.framework
MetalPerformanceShaders.framework
Photos.framework
UIKit.framework
VideoToolbox.framework
AudioToolbox.framework
libc++.tbd
3. 将 TECodec.framework、XMagic.framework、YTCommonXMagic.framework 的 Embed 设置为 Embed & Sign。

2. 配置权限声明

编辑场景需要读取相册素材、录音旁白,录制场景还需要相机与麦克风权限,请在 Info.plist 中补充(按实际用到的能力裁剪):
<key>NSPhotoLibraryUsageDescription</key>
<string>用于选择视频与图片素材</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>用于保存导出的视频</string>
<key>NSMicrophoneUsageDescription</key>
<string>用于录制旁白</string>
<key>NSCameraUsageDescription</key>
<string>用于拍摄素材</string>

3. 设置 License 鉴权

建议在 AppDelegate 的 application:didFinishLaunchingWithOptions: 中尽早设置。设置后会立即触发 License 下载,App 只要成功联网一次即可完成鉴权,通常不必把 License 文件内置进工程。
作为兜底方案,也可以在浏览器打开 License URL 下载 License 文件,重命名为 v_cube.license 后放到工程根目录,这样即使 App 从未联网或首次联网失败也能完成鉴权。
#import <YTCommonXMagic/TELicenseCheck.h>

// 如果仅仅是为了触发下载或更新 license,而不关心鉴权结果,completion 传 nil
[TELicenseCheck setTELicense:@"<#License URL#>"
key:@"<#License KEY#>"
completion:^(NSInteger authresult, NSString *errorMsg) {
NSLog(@"authResult : %zd msg:%@", authresult, errorMsg);
if (authresult == TELicenseCheckOk) {
// 鉴权成功
} else {
// 鉴权失败,见下方错误码说明
}
}];
鉴权 authresult 说明(iOS 侧 TELicenseCheckErrorCode):
错误码
常量名
说明
0
TELicenseCheckOk
成功。
-1
TELicenseCheckInvalidInput
输入参数无效,例如 URL 或 KEY 为空。
-3
TELicenseCheckDownloadError
下载环节失败,请检查网络设置。
-4
TELicenseCheckLocalLicenseEmpty
从本地读取的 TE 授权信息为空,可能是 IO 失败引起。
-5
TELicenseCheckFileContentEmpty
读取 VCUBE TEMP License 文件内容为空,可能是 IO 失败引起。
-6
TELicenseCheckJsonErrorVcube
v_cube.license 文件 JSON 字段不对。请联系腾讯云团队处理。
-7
TELicenseCheckSignatureError
签名校验失败。请联系腾讯云团队处理。
-8
TELicenseCheckDecodeError
解密失败。请联系腾讯云团队处理。
-9
TELicenseCheckTEJsonError
TELicense 字段里的 JSON 字段不对。请联系腾讯云团队处理。
-10
TELicenseCheckTEContentEmpty
从网络解析的 TE 授权信息为空。请联系腾讯云团队处理。
-11
TELicenseCheckWriteLocalFailed
把 TE 授权信息写到本地文件时失败,可能是 IO 失败引起。
-12
TELicenseCheckDownloadAndAssetBothFailed
下载失败,解析本地 asset 也失败。
-13
TELicenseCheckAuthError
鉴权失败。

4. 初始化 SDK

initSDK: 传入 LightEngine 模型资源路径,即 LightCore.bundle 所在路径。必须在创建 TAVEditor / TAVTemplateEditor / TAVRecorder 之前调用一次。
#import <TAVMagic/TAVMagicBase.h>
#import <YTCommonXMagic/TELicenseCheck.h>

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

// 1. 设置 License 鉴权
[TELicenseCheck setTELicense:@"<#License URL#>"
key:@"<#License KEY#>"
completion:^(NSInteger authresult, NSString *errorMsg) {
NSLog(@"authResult : %zd msg:%@", authresult, errorMsg);
}];

// 2. 初始化 SDK(assetsPath 为 LightCore.bundle 路径)
NSString *assetsPath = [[NSBundle mainBundle] pathForResource:@"LightCore" ofType:@"bundle"];
BOOL ret = [TAVMagicBase initSDK:assetsPath];
NSLog(@"TAVMagic initSDK : %@", ret ? @"success" : @"failed");

return YES;
}
TAVMagicBase 全局能力:
方法
说明
+ (BOOL)initSDK:(NSString *)assetsPath
SDK 全局初始化,传入 lightCore.bundle 资源路径。
+ (BOOL)isInitialized
是否已完成初始化。
+ (void)setLogLevel:(TAVLogLevel)logLevel listener:(id<TAVLogListener>)listener
日志级别与日志监听(可选)。
+ (BOOL)isFeatureAuthorized:(NSString *)featureName
校验某个特性是否已授权。
+ (NSString *)sdkVersion
SDK 版本号。
+ (TAVEditor *)createEditorWithRenderSize:(CGSize)renderSize
创建普通编辑器实例。
+ (TAVTemplateEditor *)createTemplateEditorWithRenderSize:(CGSize)renderSize
创建剪同款(模板)编辑器实例。
+ (TAVRecorder *)createRecorder
创建录制器实例。
+ (TAVHighlight *)createHighlightWithConfig:(TAVHLConfig *)config
创建高光成片实例。
可选配置:
// 设置日志级别(可选)
[TAVMagicBase setLogLevel:TAVLogLevelVerbose listener:nil];

// 查询版本号(可选)
NSString *version = [TAVMagicBase sdkVersion];

编辑快速接入

1. 创建编辑器 TAVEditor 并初始化预览

#import <TAVMagic/TAVMagicBase.h>
#import <TAVMagic/TAVEditor.h>

// 1. 创建编辑器(传 CGSizeZero 由 SDK 自动适配渲染尺寸)
TAVEditor *editor = [TAVMagicBase createEditorWithRenderSize:CGSizeZero];

// 2. 设置预览容器
TAVPreviewParam *param = [[TAVPreviewParam alloc] init];
param.videoView = self.previewContainerView; // 播放器的父容器,必填
param.loop = YES; // 循环播放
param.observer = self; // 播放进度/状态回调,需遵守 TAVEditorPlayerObserver
[editor setPreview:param];

// 3. 添加素材并刷新
[editor addVideoClip:@"/path/to/video.mp4"];
[editor flushImmediately];

// 4. 播放
[editor play];
TAVPreviewParam 字段:
字段
类型
说明
videoView
UIView *
播放器的父容器,必填。
fillModel
TAVPlayerFillMode
画面拉伸模式,选填。
loop
BOOL
是否循环播放,默认 NO。
observer
id<TAVEditorPlayerObserver>
播放状态观察者,选填。
widgetContentView
TAVWidgetContentView *
贴纸/画中画等挂件的操作容器视图,不设置则使用默认实现。

2. 释放资源

离开编辑页面时需要释放编辑器:
[editor deinit];

剪同款快速接入

剪同款使用独立的编辑器 TAVTemplateEditor,仅暴露模板、片段、播放与导出能力。依赖集成、权限声明、License 鉴权与 initSDK: 均复用上文,完成后按以下步骤接入。

1. 创建模板编辑器

#import <TAVMagic/TAVMagicBase.h>
#import <TAVMagic/TAVTemplateEditor.h>

// 需先调用 [TAVMagicBase initSDK:];传 CGSizeZero 由 SDK 自动适配渲染尺寸
TAVTemplateEditor *templateEditor = [TAVMagicBase createTemplateEditorWithRenderSize:CGSizeZero];

2. 应用模板并初始化预览

// 1. 获取模板坑位信息(可选,用于选素材前校验可选数量与类型)
NSString *templatePath = @"/path/to/template";

// 2. 应用模板,必须在添加素材之前调用
TAVTemplateCode code = [templateEditor setTemplate:templatePath];
if (code != TAVTemplateCodeSuccess) {
// TAVTemplateCodePathInvalid:模板路径无效;TAVTemplateCodeAuthInvalid:无权限
return;
}

// 3. 设置预览容器
TAVPreviewParam *param = [[TAVPreviewParam alloc] init];
param.videoView = self.previewContainerView; // 播放器的父容器,必填
param.loop = YES; // 循环播放
param.observer = self; // 需遵守 TAVEditorPlayerObserver
[templateEditor setPreview:param];
TAVTemplateCode:
枚举值
值
说明
TAVTemplateCodeSuccess
0
应用成功。
TAVTemplateCodePathInvalid
1
模板路径无效。
TAVTemplateCodeAuthInvalid
2
无权限。
TAVTemplateConfig 字段:
字段
类型
说明
mediaType
TAVTemplateMediaType
可选素材类型:
1:仅视频。
2:仅照片。
3:照片与视频均可。
minAssetCount
int
用户上传素材最少个数,0表示不限制。
maxAssetCount
int
用户上传素材最多个数,0表示不限制。
clipPlaceHolders
NSArray<TAVClipPlaceHolder *> *
视频坑位数组,contentDuration 为单个坑位的内容时长。
clipAudioHolders
NSArray<TAVAudioPlaceHolder *> *
音频坑位数组,包含 bgm 路径、时长、音量等信息。

3. 替换素材与可替换项

// 1. 按坑位添加素材(图片默认展示 3s,传 kCMTimeZero 使用默认值)
[templateEditor addVideoClip:@"/path/to/video.mp4"];
[templateEditor addImageClip:@"/path/to/image.jpg" duration:kCMTimeZero];

// 2. 获取模板中所有可替换项,按出现时间升序排列(需在 setTemplate: 成功后调用)
NSArray<TAVReplaceItem *> *items = [templateEditor getReplaceItems];
for (TAVReplaceItem *item in items) {
// 修改替换项的出现区间与位置(scaleRect 为归一化数值)
item.timeRange = CMTimeRangeMake(kCMTimeZero, CMTimeMake(3, 1));
// 将修改同步到模板,修改立即生效
[templateEditor replaceItem:item];
}

// 3. 素材变化后需要刷新播放资源
[templateEditor flushImmediately];
TAVReplaceItem 字段:
字段
类型
说明
itemId
int
替换项唯一标识,对应 LAKEntity.id,只读。
type
TAVTemplateReplaceType
替换项类型,当前仅支持 TAVTemplateReplaceTypeText(文本)。
timeRange
CMTimeRange
替换项的出现时间区间。
scaleRect
CGRect
位置与大小,归一化数值 {centerX, centerY, width, height}。

4. 播放与导出

// 播放控制
[templateEditor play];
[templateEditor pause];
[templateEditor stop];

// 生成并导出视频
[templateEditor generateVideo:nil
outputPath:@"/path/to/output.mp4"
progress:^(CGFloat progress) {
// 导出进度 0~1
} completion:^(NSError *error, NSString *outputPath) {
if (error == nil) {
// 导出完成
}
}];

// 离开页面时释放
[templateEditor deinit];
说明:
模板自带的背景音乐 bgmId 固定为 TEMPLATE_DEFAULT_BGM_ID,可通过 setBgm:volume: 调整音量。

录制快速接入

录制能力由 TAVRecorder 提供,与编辑能力相互独立。依赖集成、License 鉴权与 initSDK: 已完成的前提下,按以下步骤接入。

1. 创建录制器

#import <TAVMagic/TAVRecorder.h>

// 推荐:由工厂方法创建(需先调用 [TAVMagicBase initSDK:])
TAVRecorder *recorder = [TAVMagicBase createRecorder];

// 不推荐:直接初始化并指定资源路径,建议改用 [TAVMagicBase createRecorder]
TAVRecorder *recorder = [[TAVRecorder alloc] initWithAssetsPath:@"/path/to/lightCore.bundle"];
说明:
建议统一使用 [TAVMagicBase createRecorder]:它会复用 initSDK: 已初始化的资源路径,未初始化时还会尝试默认路径兜底,可避免因传入错误路径导致初始化失败。

2. 配置录制参数

TAVRecorderConfig *config = [[TAVRecorderConfig alloc] init];
config.devicePosition = AVCaptureDevicePositionFront; // 前置摄像头,默认
config.resolution = TAVRecorderResolution_1080; // 分辨率,默认 1080
config.aspectRatio = TAVRecorderAspectRatioFull; // 9:16,默认
config.fps = 30; // 帧率,默认 30
config.bitrate = 0; // 码率(bps),0 表示自动
TAVRecorderConfig 字段:
字段
类型
默认值
说明
devicePosition
AVCaptureDevicePosition
AVCaptureDevicePositionFront
默认摄像头位置。
fps
int
30
帧率。
resolution
TAVRecorderResolution
TAVRecorderResolution_1080
分辨率等级。
aspectRatio
TAVRecorderAspectRatio
TAVRecorderAspectRatioFull
画面比例。
bitrate
UInt64
0
视频码率(bps)。0表示自动,按 width * height * fps * 0.22 动态计算;大于0则使用固定码率。

3. 初始化预览

TAVRecorderPrepareResult result = [recorder prepareWithRecorderConfig:config
displayContainerView:self.previewContainerView];
if (result != TAVRecorderPrepareResultSuccess) {
// TAVRecorderPrepareResultNoAuthorized:相机/麦克风权限未授予
return;
}
[recorder startPreview];
displayContainerView 为承载预览画面的 UIView,SDK 会在其中创建渲染视图并自动填充。
TAVRecorderPrepareResult:
枚举值
值
说明
TAVRecorderPrepareResultSuccess
0
初始化成功。
TAVRecorderPrepareResultNoAuthorized
-1
缺少相机/麦克风权限。

4. 设置录制监听

[recorder setRecordListener:self];

#pragma mark - TAVRecordListener
- (void)onRecordStart {
// 开始录制
}

- (void)onRecording:(CMTime)recordingTime {
// 录制中,recordingTime 为已录制时长(已按 recordSpeed 缩放)
}

- (void)onStopRecord:(NSError *)stopResult {
// 录制结束,成功时 stopResult 为 nil
}

- (void)onCameraError:(NSError *)error {
// 相机初始化/配置失败
}
说明:
TAVRecorder 对 listener 为弱引用持有,请自行保证监听对象的生命周期。

5. 开始与停止录制

// 参数:speed 录制速度(1.0 为正常速度),enableMic 是否录制麦克风声音
[recorder startRecordWithSpeed:1.0 enableMic:YES];

// 停止当前段
[recorder stopRecord];
说明:
变速录制时 BGM 播放速率会自动同步为 1.0/speed,使 BGM 节奏与最终视频对齐。
离开录制页面时需要停止预览:
- (void)viewWillDisappear:(BOOL)animated {
[super viewWillDisappear:animated];
[recorder stopPreview];
}

- (void)dealloc {
[recorder stopPreview];
}
说明:
TAVRecorder 未提供 onResume / onPause / onDestroy 生命周期方法;前后台切换请通过 stopPreview / startPreview 自行管理。

SDK 详细功能介绍

功能
介绍
预览与导出
参见 预览与导出 文档介绍。
背景音乐
参见 背景音乐 文档介绍。
动效
参见 动效 文档介绍。
滤镜
参见 滤镜 文档介绍。
贴纸与文字
参见 贴纸与文字 文档介绍。
画中画
参见 画中画 文档介绍。
模板
参见 剪同款 文档介绍。
抽帧
参见 自定义视频帧处理 文档介绍。