tencent cloud

短视频 SDK

文档短视频 SDK不含 UI 集成方案 高级版/剪同款集成指引快速接入iOS

iOS

Download
聚焦模式
字号
最后更新时间： 2026-05-11 17:46:56

准备工作

1. 开发环境

Xcode 9或更高版本
iOS12.0及以上系统

2. 下载 SDK

下载 TAVMagic_Professional_iOS.zip 压缩包，解压获得 SDK 文件后就可以开始集成工作。

3. 申请 License

参见 License 申请 的指引申请 License 后，从 云直播 或 云点播 任何一个产品控制台的 License 管理页面复制 License Key 和 License URL，如下图所示：


集成 SDK

pod 集成

# add in podfile
pod 'TAVMagic', :podspec => 'https://mediacloud-76607.gzc.vod.tencent-cloud.com/TAVMagic/iOS/Release/1.6.2.0/TAVMagic.podspec'

# update pod in terminal
pod install --repo-update

手动集成

1. 将 TAVMagic 整个文件夹拉入工程内。
2. 项目分别添加系统依赖库：
CoreTelephony.framework
JavaScriptCore.framework
libc++.tbd
MetalPerformanceShaders.framework
VideoToolbox.framework
Metal.framework
3. 在工程的 General-->Frameworks，Libraries...下将 TECodec.framework、XMagic.framework、YTCommonXMagic.framework 的 Embed 设置为 Embed&Sign。

初始化 SDK

1. 设置 License 鉴权

您可以根据自己的业务情况在相关业务模块的初始化代码中设置 URL 和 KEY。设置 License 后，将立即触发 License 下载，为了功能正常使用，建议提前设置 License，并且确保校验结果成功再进入短视频编辑功能。
//如果仅仅是为了触发下载或更新license，而不关心鉴权结果，则completion参数传入null。
[TELicenseCheck setTELicense:@"license url" key:@"licenseKey" completion:^(NSInteger authresult, NSString * _Nonnull errorMsg) {
      NSLog(@"authResult : %zd  msg:%@",authresult,errorMsg);
}];
鉴权 errorCode 说明：
错误码
说明
0
成功。
-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
鉴权失败。
其他
请联系腾讯云团队处理。

2. 初始化 SDK

1. 调用初始化 SDK 接口。
- (void)buildSDK {
    NSString *bundlePath = [[NSBundle mainBundle] pathForResource:@"LightSDK" ofType:@"bundle"];
    self.editor = [[TAVEditor alloc] initWithRenderSize:CGSizeZero assetsPath:bundlePath];
}
2. 设置预览容器。
TAVPreviewParam *param = [[TAVPreviewParam alloc] init];
param.videoView = self.view;
param.observer = self;  // 包含预览进度、状态回调
param.shouldRepeat = YES;
[self.editor initPlayerWithPreviewParam:param];

SDK 使用

1. SDK 功能使用介绍

SDK 中所有的功能都通过 TAVEditor 类进行调用。

2. 短视频剪辑

1. 在初始化预览完成之后，可以通过 addVideoClip 添加视频源或通过 addImageClip 添加图片源以在播放器中预览视频或图片：
// 添加一个视频源
[editor addVideoClip(@"您的视频路径")];
// 添加完所有视频源之后调用刷新重新生成预览资源,即可观看对应效果
[editor flushImmediately];
// 设置第1个视频的播放时间区间，从0到视频时长
[editor setClipRange:timeRange index:1];
// 设置第1个视频源的音量(可选)，音量范围是[0,1]
[editor setClipVolume:volume index:1];
2. 您还可以通过 seekToTime 方法跳转至指定时长处播放：
[editor seekToTime:seekTime];

3. 剪同款预览

1. 剪同款功能需要通过 setTemplateDir 设置模板文件夹路径。接口会有一个返回值具体参考 TAVTemplateCode。
TAVTemplateCode ret = [editor setTemplateDir@"模板文件夹路径"];
2. SDK 同时提供 getTemplateConfig 方法获取模板坑位、时长等关键信息。示例：
TAVTemplateConfig config = [editor getTemplateConfig(@"模板文件夹路径")];
//兼容的媒体格式 VIDEO（视频） PHOTO（图片） MULTI（混合）
TAVTemplateMediaType mediaType = config.mediaType;
//可填充的数量限制
NSArray<TAVClipPlaceHolder *> clipHolders = config.clipPlaceHolders;
//每个段落播放时长
clipHolders[0].contentDuration
3. 在设置完模板信息后，您可以通过 addVideoClip 添加视频源或通过 addImageClip 添加图片源以完成做同款的预览。示例：
// 做同款模式下，选择的视频源时长应该大于对应的TAVClipPlaceHolder的播放时长
// 添加一个视频源
[editor addVideoClip(@"您的视频路径")];
// 添加完所有视频源之后调用刷新重新生成预览资源,即可观看对应效果
[editor flushImmediately];

4. 其他基本操作

刷新

    /**
     * 在改变资源/BGM后需要调用此接口刷新生成播放资源
     */
    - (void)flushImmediately;

导出

1. 可通过 generateVideo 接口快速导出。示例：
// generateVideo接口第一个参数为导出压缩质量，支持下列四个等级
typedef NS_ENUM(NSInteger, TAVVideoCompressed) {
    TAVVideoCompressed480P   = 0 , // 压缩至480P分辨率（640*480）
    TAVVideoCompressed540P   = 1 , // 压缩至540P分辨率 (960*540)
    TAVVideoCompressed720P   = 2 , // 压缩至720P分辨率 (1280*720)
    TAVVideoCompressed1080P  = 3      // 压缩至1080P分辨率 (1920*1080)
};
NSString *outputPath = "您的导出路径";
[self.editor generateVideoWithCompressed:TAVVideoCompressed1080P outputPath:outputPath progress:^(CGFloat progress) {
            
} completion:^(NSError * _Nonnull error, NSString * _Nonnull outputPath) {

}];
2. 如果对导出视频要求较高，可自定义导出参数。通过另外一个 generateVideo 方法设置 TAVEditorGenerateConfig 后，视频将会按照 config 中设置的宽高导出，不再根据 TAVVideoCompressed 压缩。示例：
TAVEditorGenerateConfig *config = [TAVEditorGenerateConfig new];
config.resolution = CGSizeMake(720,1280);
config.frameRate = 60;
config.videoBitRate = 8 * 1000 * 1000;
NSString *outputPath = "您的导出路径";
[self.videoContext.editor generateVideo:nil outputPath:resDir progress:^(CGFloat progress) {
    NSLog(@"progress : %f",progress);
} completion:^(NSError * _Nonnull error, NSString * _Nonnull outputPath) {

}];

释放资源

在退出编辑时，需要释放 SDK，可以直接调用 TAVEditor 中 release 方法进行释放：
[editor deinit];

5. 预览播放相关

开始播放视频

/**
 * 开始播放
 */
- (void)play;


暂停和续播


/**
 * 暂停
 */
- (void)pause;

/**
 * 停止播放 会seek到0
 */
- (void)stop;

/**
 * 判断播放中
 *
 * @return 播放中
 */
- (BOOL)isPlaying;

获取播放总时长

/**
 * 获取播放总时长
 *
 * @return 时间
 */
- (CMTime)getTotalDuration;

跳转至指定位置播放

/**
 * seek
 *
 * @param seekTime   时间
 */
- (void)seekToTime:(CMTime)seekTime;

SDK 详细功能介绍

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

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈