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

SDK 集成
1. 在工程中添加依赖
方式一:CocoaPods(推荐)
platform :ios, '12.0'target 'YourAppTarget' douse_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.frameworkCoreMedia.frameworkCoreTelephony.frameworkJavaScriptCore.frameworkMetal.frameworkMetalPerformanceShaders.frameworkPhotos.frameworkUIKit.frameworkVideoToolbox.frameworkAudioToolbox.frameworklibc++.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 *)applicationdidFinishLaunchingWithOptions:(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:niloutputPath:@"/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; // 分辨率,默认 1080config.aspectRatio = TAVRecorderAspectRatioFull; // 9:16,默认config.fps = 30; // 帧率,默认 30config.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:configdisplayContainerView: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 详细功能介绍