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

iOS

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

功能概览

剪同款能够实现一键成片,通过剪同款功能接口能加载制作好的模板,用户添加视频或图片能实现音乐卡点及炫酷转场视频。

相关接口类

接口类名
描述
TAVTemplateEditor
剪同款编辑入口类。
TAVTemplateConfig
模板配置信息类。
TAVReplaceItem / TAVTextReplaceItem
模板中可替换素材的描述(文字类型替换项)。
说明:
剪同款场景统一使用 TAVTemplateEditor:通过 [TAVMagicBase createTemplateEditorWithRenderSize:] 创建。TAVEditor 用于普通短视频编辑,其中保留了 setTemplate: / getTemplateConfig: 等模板接口,也可完成剪同款,但能力边界与 TAVTemplateEditor 不同。

创建剪同款编辑器

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

// 剪同款入口(需先调用 [TAVMagicBase initSDK:])
TAVTemplateEditor *editor = [TAVMagicBase createTemplateEditorWithRenderSize:CGSizeZero];
// 等价写法(不建议)
// TAVTemplateEditor *editor = [TAVTemplateEditor templateEditorWithRenderSize:CGSizeZero];

// 初始化预览(必须在其它接口之前调用)
TAVPreviewParam *param = [[TAVPreviewParam alloc] init];
param.videoView = self.previewContainerView; // 预览容器
param.loop = YES;
param.observer = self;
[editor setPreview:param];

剪同款主链路

步骤
操作
接口
1
创建编辑器。
[TAVMagicBase createTemplateEditorWithRenderSize:]
2
初始化预览。
setPreview:(TAVPreviewParam *)
3
读取模板配置。
getTemplateConfig:
4
填充素材。
addVideoClip: / addImageClip:duration: / setClipRange:index:
5
应用模板。
setTemplate: → TAVTemplateCode
6
刷新。
flushImmediately
7
替换模板素材。
getReplaceItems → replaceItem:
8
播放。
play
9
导出成片。
generateVideo...
10
释放。
deinit

剪同款相关方法

获取模板配置

/// 获取视频模版坑位信息
/// - Parameter templatePath: 视频模版素材路径
- (TAVTemplateConfig *)getTemplateConfig:(NSString *)templatePath;
通常在填充素材前调用,用于读取模板的坑位数量、媒体类型限制(视频/图片/混合)、每个坑位的时长要求,以便在添加媒体资源前做合法性校验。路径无效时返回 nil。

应用模板

/// 应用模板
/// - Parameter templatePath: 视频模版素材路径
/// - return: 0 成功,1 路径无效,2 无权限
- (TAVTemplateCode)setTemplate:(NSString *)templatePath;
TAVTemplateCode:
枚举值
值
说明
TAVTemplateCodeSuccess
0
成功。
TAVTemplateCodePathInvalid
1
模板路径无效。
TAVTemplateCodeAuthInvalid
2
无权限(模板授权无效)。

获取可替换素材列表

/// 获取模板中所有可替换项,需在 setTemplate: 成功后调用
/// - Returns: TAVReplaceItem 数组,按出现时间升序排列
- (NSArray<TAVReplaceItem *> *)getReplaceItems;
TAVReplaceItem 字段:
字段
类型
说明
itemId
int(只读)
替换项唯一标识,对应 LAKEntity.id,用于回写时定位。
type
TAVTemplateReplaceType(只读)
替换类型,当前仅 TAVTemplateReplaceTypeText(文本)。
timeRange
CMTimeRange
该素材在时间轴上的区间。
scaleRect
CGRect
位置与大小,归一化数值 {centerX, centerY, width, height}。
TAVTextReplaceItem(TAVReplaceItem 子类)字段:
字段
类型
说明
src
NSString *
文本内容。
textMaxLength
NSInteger(只读)
文本最大长度。

替换模板素材

/// 将替换项的修改内容同步到模板,修改立即生效
/// - Parameter item: 经 getReplaceItems 获取并修改内容后的替换项
- (void)replaceItem:(TAVReplaceItem *)item;
文字替换示例:
for (TAVReplaceItem *item in [editor getReplaceItems]) {
if (item.type == TAVTemplateReplaceTypeText) {
TAVTextReplaceItem *textItem = (TAVTextReplaceItem *)item;
textItem.src = @"新的文案";
[editor replaceItem:textItem];
}
}

设置渲染尺寸

/// 设置当前渲染大小
- (void)setRenderSize:(CGSize)renderSize;

/// 获取当前渲染大小
- (CGSize)getRenderSize;
说明:
剪同款模板通常固定为 9:16 竖屏,建议在添加资源前调用,避免渲染链重建。

派生独立编辑器

/// 从当前编辑对象派生一个实例,返回实例保留当前的素材、裁剪、音量、滤镜等编辑状态
/// 返回实例由调用方负责 deinit
- (instancetype)fork;
说明:
fork 不接受预览参数,派生出的实例不绑定预览容器,可直接用于导出。

TAVTemplateEditor 其余能力

分类
方法
生命周期
initWithRenderSize:、templateEditorWithRenderSize:、deinit、fork
模板
setTemplate:、getTemplateConfig:、getReplaceItems、replaceItem:
素材
addVideoClip:、addVideoClips:index:、addImageClip:duration:、addImageClips:index:durations:、getClipCount、getClipInfos、removeClip:、removeAllClip、clearAll、setClipRange:index:、setClipSpeed:index:、updateClipIndex:toIndex:、setClipVolume:index:、setAllClipsVolume:、getClipVolume:、setClipsRotation:、setClipRotation:index:、setClipTransform:、setClipSize:、setCropInfo:index:
BGM
setBgm:volume:、setAllBgmVolume:、getBgmVolume:、setBgm:speed:、getBgmSpeed:
播放
setPreview:、setPlayLoop:、isPlayLoop、play、playAtTime:、pause、stop、refresh、seekToTime:、seekToTime:completion:、flushImmediately、flushImmediatelyCompletion:、preparePlayerItem、bindPlayerItem:completion:、getTotalDuration、getClipsDuration、isPlaying、currentTime、currentCMTime、setPlayerViewFillMode:、playerViewFillMode、registerPlayerObserver:、resignObserver:、setReverse:
导出
generateVideo:outputPath:progress:completion:、generateVideoWithCompressed:outputPath:progress:completion:、quickGenerateVideo:...、quickGenerateVideoWithCompressed:...、cancelGenerate:、pauseGenerate、resumeGenerate
其它
getVideoFrameManager、currentAVAsset、currentComposition
注意:
TAVTemplateEditor 未提供滤镜、动效、贴纸、画中画、草稿等接口,这些能力由 TAVEditor 提供;剪同款模板内的音视频、转场等由模板 JSON 驱动。模板自带音乐的 bgmId 固定为 TEMPLATE_DEFAULT_BGM_ID(-10001)。

TAVTemplateConfig 结构说明

字段
类型
说明
mediaType
TAVTemplateMediaType
模板兼容的媒体类型:
1:仅视频。
2:仅照片。
3:视频+照片。
minAssetCount
int
用户上传素材最少个数,0表示不限制。
maxAssetCount
int
用户上传素材最多个数,0表示不限制。
clipPlaceHolders
NSArray<TAVClipPlaceHolder *> *
视频/图片坑位列表,contentDuration 为每个坑位要求的素材时长。
clipAudioHolders
NSArray<TAVAudioPlaceHolder *> *
音频(背景音)坑位列表。
TAVAudioPlaceHolder 字段:
字段
类型
说明
path
NSString *
BGM 路径。
name
NSString *
名称。
bgmId
NSInteger
BGM ID。
duration
CMTime
时长。
volume
CGFloat
音量 0-1。
startOffset
CMTime
在时间轴中的开始时间。
loopCount
NSInteger
0:不播放;1:循环一次;-1:无限循环。

使用示例

// 1. 创建剪同款编辑器并初始化预览
TAVTemplateEditor *editor = [TAVMagicBase createTemplateEditorWithRenderSize:CGSizeZero];
TAVPreviewParam *param = [[TAVPreviewParam alloc] init];
param.videoView = self.previewContainerView;
param.loop = YES;
[editor setPreview:param];

// 2. 读取模板配置
TAVTemplateConfig *config = [editor getTemplateConfig:@"/path/to/template"];
if (config == nil) {
// 模板路径无效
return;
}

// 3. 按坑位填充素材
NSArray<TAVClipPlaceHolder *> *clipHolders = config.clipPlaceHolders;
[editor addVideoClip:@"/path/to/a.mp4"];
[editor addImageClip:@"/path/to/b.jpg" duration:clipHolders[1].contentDuration];

// 4. 应用模板
TAVTemplateCode ret = [editor setTemplate:@"/path/to/template"];
if (ret != TAVTemplateCodeSuccess) {
// ret == TAVTemplateCodePathInvalid:路径无效
// ret == TAVTemplateCodeAuthInvalid:模板授权无效
return;
}

// 5. 刷新
[editor flushImmediately];

// 6. 替换模板中的文字
for (TAVReplaceItem *item in [editor getReplaceItems]) {
if (item.type == TAVTemplateReplaceTypeText) {
TAVTextReplaceItem *textItem = (TAVTextReplaceItem *)item;
textItem.src = @"新的文案";
[editor replaceItem:textItem];
}
}

// 7. 启动播放
[editor play];

// 8. 导出成片
[editor generateVideoWithCompressed:TAVVideoCompressed720P
outputPath:@"/path/to/output.mp4"
progress:^(CGFloat progress) {
} completion:^(NSError *error, NSString *outputPath) {
// error 为 nil 表示导出成功
}];

// 9. 离开编辑页时释放
[editor deinit];

错误处理指南

返回码
含义
解决方案
TAVTemplateCodeSuccess(0)
成功。
-
TAVTemplateCodePathInvalid(1)
路径无效。
检查路径是否存在且有读取权限。
TAVTemplateCodeAuthInvalid(2)
授权无效。
检查模板授权文件是否有效。