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

iOS

最近更新时间:2026-11-11 21:20:00
本文档已由 AI 辅助审校
我的收藏
本文主要介绍短视频编辑 SDK(不含 UI)iOS 端剪同款(模板编辑)相关的 API 接口文档,以便于查阅和使用。剪同款使用独立的编辑器 TAVTemplateEditor(TAVMagic/TAVTemplateEditor.h),仅暴露模板、片段、播放与导出操作。
创建剪同款编辑器:
// 需先调用 [TAVMagicBase initSDK:];传 CGSizeZero 由 SDK 自动适配渲染尺寸
TAVTemplateEditor *templateEditor = [TAVMagicBase createTemplateEditorWithRenderSize:CGSizeZero];

TAVTemplateEditor

剪同款模板编辑器,仅暴露模板/片段/播放/导出操作。

与 TAVEditor 的差异

创建方式:[TAVMagicBase createTemplateEditorWithRenderSize:] 或 [TAVTemplateEditor templateEditorWithRenderSize:]。
不提供滤镜、动效、贴纸、画中画、草稿接口;模板内的音视频、转场等由模板 JSON 驱动。
BGM 仅提供音量与速度调节,模板自带音乐的 bgmId 固定为 TEMPLATE_DEFAULT_BGM_ID(-10001)。
fork 无参数。

接口方法汇总

API
描述
初始化剪同款编辑器。
初始化剪同款编辑器(类方法)。
- deinit
释放编辑器。
- fork
从当前编辑对象派生一个实例(无参数)。
获取视频模板坑位信息。
应用模板。
获取模板中所有可替换项。
将替换项的修改内容同步到模板。
向末尾添加视频资源。
指定位置添加视频资源。
向末尾添加图片资源。
在指定位置添加图片资源。
获取当前正在编辑的资源数量。
获取当前使用资源信息。
移除指定位置的视频或者图片资源。
删除所有资源(视频/图片/模板)片段。
清空所有资源和所有特效。
修改指定资源的时长。
修改指定资源的速率。
调整资源位置。
设置指定资源背景音量。
设置所有资源背景音量。
获取对应下标资源音量。
设置全部资源旋转角度。
设置指定资源旋转角度。
设置资源形变(全部)。
设置指定资源形变。
设置资源尺寸(全部)。
设置指定资源尺寸。
设置裁剪信息。
设置背景音乐播放音量。
设置所有背景音乐播放音量。
获取背景音乐音量。
调整背景音乐播放速度。
获取背景音乐播放速度。
初始化预览播放器。
设置循环播放。
是否循环播放。
- play
开始播放。
从某个时间开始播放。
- pause
暂停。
- stop
停止。
- refresh
刷新预览播放器。
seek 到指定时间。
带完成回调的 seek。
改变资源后重新生成播放资源。
带完成回调的 flushImmediately。
生成播放器资源(耗时,可子线程调用)。
将播放器资源绑定到播放器。
获取预览总时长。
获取主轨道总时长(秒)。
是否在播放中。
当前播放的时间(秒)。
当前播放的时间(CMTime)。
设置预览填充模式。
获取播放器填充模式。
注册播放状态监听者。
注销播放状态监听者。
设置当前渲染大小。
获取当前渲染大小。
获取当前播放器的完整 AVAsset。
获取当前播放器的完整 AVVideoComposition。
设置视频是否倒放。
生成并导出视频。
按分辨率生成并导出视频。
快速生成并导出视频。
按分辨率快速生成并导出视频。
取消生成视频。
暂停导出。
继续导出。
获取抽帧操作类。

initWithRenderSize:

描述
初始化剪同款编辑器。需先调用 [TAVMagicBase initSDK:]。
接口
- (instancetype)initWithRenderSize:(CGSize)renderSize;
参数
参数名
类型
说明
renderSize
CGSize
画面渲染尺寸,根据宽高比缩放。传 CGSizeZero 则自动适应渲染尺寸。
返回值
类型:instancetype
说明:剪同款编辑器实例。

templateEditorWithRenderSize:

描述
初始化剪同款编辑器(类方法)。需先调用 [TAVMagicBase initSDK:]。
接口
+ (instancetype)templateEditorWithRenderSize:(CGSize)renderSize
参数
参数名
类型
说明
renderSize
CGSize
画面渲染尺寸,根据宽高比缩放。传 CGSizeZero 则自动适应渲染尺寸。
返回值
类型:instancetype
说明:剪同款编辑器实例。

deinit

描述
释放编辑器,销毁编辑资源。离开剪同款页面时调用。
接口
- (void)deinit
返回值
类型:void

fork

描述
从当前编辑对象派生一个实例,保留当前的素材、裁剪、音量等编辑状态。返回实例由调用方负责 deinit。
接口
- (instancetype)fork
返回值
类型:instancetype
说明:独立的剪同款编辑器实例。
说明:
与 TAVEditor 的差异:fork 不接受 TAVPreviewParam 参数。

getTemplateConfig:

描述
获取视频模板坑位信息,可用于选素材前校验可选数量与类型。
接口
- (TAVTemplateConfig * _Nullable)getTemplateConfig:(NSString * _Nullable)templatePath
参数
参数名
类型
说明
templatePath
NSString *
视频模板素材路径。
返回值
类型:TAVTemplateConfig *
说明:模板配置对象,路径无效时返回 nil。

setTemplate:

描述
应用模板。必须在添加素材之前调用。
接口
- (TAVTemplateCode)setTemplate:(NSString * _Nullable)templatePath
参数
参数名
类型
说明
templatePath
NSString *
视频模板素材路径。
返回值
类型:TAVTemplateCode
说明:TAVTemplateCodeSuccess(0) 成功、TAVTemplateCodePathInvalid(1) 路径无效、TAVTemplateCodeAuthInvalid(2) 无权限。

getReplaceItems

描述
获取模板中所有可替换项,需在 setTemplate: 成功后调用。
接口
- (NSArray <TAVReplaceItem *> *)getReplaceItems;
返回值
类型:NSArray<TAVReplaceItem *> *
说明:按出现时间升序排列。

replaceItem:

描述
将替换项的修改内容同步到模板,修改立即生效。
接口
- (void)replaceItem:(TAVReplaceItem *)item
参数
参数名
类型
说明
item
TAVReplaceItem *
经 getReplaceItems 获取并修改内容后的替换项。
返回值
类型:void

addVideoClip:

描述
向末尾添加视频资源。
接口
- (int)addVideoClip:(NSString *)path
参数
参数名
类型
说明
path
NSString *
视频素材路径。
返回值
类型:int
说明:返回成功添加后的索引。

addVideoClips:index:

描述
指定位置添加视频资源。
接口
- (int)addVideoClips:(NSArray *)paths index:(int)index
参数
参数名
类型
说明
paths
NSArray *
视频资源路径数组。
index
int
添加的位置。
返回值
类型:int
说明:返回成功添加后的索引。

addImageClip:duration:

描述
向末尾添加图片资源。
接口
- (int)addImageClip:(NSString *)path duration:(CMTime)duration
参数
参数名
类型
说明
path
NSString *
图片资源路径。
duration
CMTime
图片素材展示的时间,传 kCMTimeZero 为默认 3s。
返回值
类型:int
说明:返回成功添加后的索引。

addImageClips:index:durations:

描述
在指定位置添加图片资源。
接口
- (int)addImageClips:(NSArray<NSString *> *)paths index:(int)index durations:(NSArray<NSNumber *> *)durations;
参数
参数名
类型
说明
paths
NSArray<NSString *> *
图片资源路径数组。
index
int
插入位置。
durations
NSArray<NSNumber *> *
展示时长,单位为秒,传 @(0) 为默认 3s。
返回值
类型:int
说明:返回成功添加后的索引。

getClipCount

描述
获取当前正在编辑的资源数量。
接口
- (int)getClipCount
返回值
类型:int
说明:资源数量。

getClipInfos

描述
获取当前使用资源信息。
接口
- (NSArray<TAVClipInfo *> *)getClipInfos;
返回值
类型:NSArray<TAVClipInfo *> *
说明:资源信息数组,字段见 TAVClipInfo。

removeClip:

描述
移除指定位置的视频或者图片资源。
接口
- (void)removeClip:(int)index
参数
参数名
类型
说明
index
int
资源下标。
返回值
类型:void

removeAllClip

描述
删除所有资源(视频/图片/模板)片段。
接口
- (void)removeAllClip
返回值
类型:void

clearAll

描述
清空所有资源和所有特效。
接口
- (void)clearAll
返回值
类型:void

setClipRange:index:

描述
修改指定资源的时长(播放区间)。
接口
- (void)setClipRange:(CMTimeRange)timeRange index:(int)index
参数
参数名
类型
说明
timeRange
CMTimeRange
资源播放区间。
index
int
资源下标。
返回值
类型:void

setClipSpeed:index:

描述
修改指定资源的速率。
接口
- (void)setClipSpeed:(CGFloat)speed index:(int)index
参数
参数名
类型
说明
speed
CGFloat
速率,取值范围 (0,3]。
index
int
资源下标。
返回值
类型:void

updateClipIndex:toIndex:

描述
调整资源位置。
接口
- (BOOL)updateClipIndex:(int)oldIndex toIndex:(int)newIndex
参数
参数名
类型
说明
oldIndex
int
调整前下标。
newIndex
int
调整后下标。
返回值
类型:BOOL
说明:是否调整成功。

setClipVolume:index:

描述
设置指定资源背景音量。
接口
- (void)setClipVolume:(float)volume index:(int)index
参数
参数名
类型
说明
volume
float
音量,取值 0-1f。
index
int
资源下标。
返回值
类型:void

setAllClipsVolume:

描述
设置所有资源背景音量。
接口
- (void)setAllClipsVolume:(float)volume
参数
参数名
类型
说明
volume
float
音量,取值 0-1f。
返回值
类型:void

getClipVolume:

描述
获取对应下标资源音量。
接口
- (float)getClipVolume:(int)index
参数
参数名
类型
说明
index
int
资源下标。
返回值
类型:float
说明:音量,取值 0-1f。

setClipsRotation:

描述
设置全部资源旋转角度,按顺时针旋转。
接口
- (void)setClipsRotation:(int)rotation
参数
参数名
类型
说明
rotation
int
顺时针旋转角度 0-360。
返回值
类型:void

setClipRotation:index:

描述
根据下标设置指定资源的旋转角度。
接口
- (void)setClipRotation:(int)rotation index:(int)index
参数
参数名
类型
说明
rotation
int
顺时针旋转角度 0-360。
index
int
资源下标。
返回值
类型:void

setClipTransform:

描述
设置资源形变(作用于全部资源)。
接口
- (void)setClipTransform:(CGAffineTransform)transform
参数
参数名
类型
说明
transform
CGAffineTransform
形变矩阵。
返回值
类型:void

setClipTransform:index:

描述
设置指定资源的形变。
接口
- (void)setClipTransform:(CGAffineTransform)transform index:(int)index
参数
参数名
类型
说明
transform
CGAffineTransform
形变矩阵。
index
int
资源下标。
返回值
类型:void

setClipSize:

描述
设置资源尺寸(作用于全部资源)。
接口
- (void)setClipSize:(CGSize)size
参数
参数名
类型
说明
size
CGSize
资源尺寸。
返回值
类型:void

setClipSize:index:

描述
设置指定资源的尺寸。
接口
- (void)setClipSize:(CGSize)size index:(int)index
参数
参数名
类型
说明
size
CGSize
资源尺寸。
index
int
资源下标。
返回值
类型:void

setCropInfo:index:

描述
设置指定资源的裁剪信息。
接口
- (void)setCropInfo:(TAVMediaAssetCropInfo *)cropInfo index:(int)index
参数
参数名
类型
说明
cropInfo
TAVMediaAssetCropInfo *
裁剪信息。
index
int
资源下标。
返回值
类型:void

setBgm:volume:

描述
设置背景音乐播放音量。
接口
- (void)setBgm:(int)bgmId volume:(float)volume
参数
参数名
类型
说明
bgmId
int
背景音乐 ID,模板自带音乐的 bgmId 固定为 TEMPLATE_DEFAULT_BGM_ID。
volume
float
音量 0-1f。
返回值
类型:void

setAllBgmVolume:

描述
设置所有背景音乐播放音量。
接口
- (void)setAllBgmVolume:(float)volume
参数
参数名
类型
说明
volume
float
音量 0-1f。
返回值
类型:void

getBgmVolume:

描述
获取指定背景音乐的音量。
接口
- (float)getBgmVolume:(int)bgmId
参数
参数名
类型
说明
bgmId
int
背景音乐 ID。
返回值
类型:float
说明:音量 0-1f。

setBgm:speed:

描述
调整背景音乐播放速度。
接口
- (void)setBgm:(int)bgmId speed:(float)speed
参数
参数名
类型
说明
bgmId
int
背景音乐 ID,模板自带音乐的 bgmId 固定为 TEMPLATE_DEFAULT_BGM_ID。
speed
float
播放速度,1 正常,大于 1 快,小于 1 慢。
返回值
类型:void

getBgmSpeed:

描述
获取指定背景音乐的播放速度。
接口
- (float)getBgmSpeed:(int)bgmId
参数
参数名
类型
说明
bgmId
int
背景音乐 ID。
返回值
类型:float
说明:播放速度,1 为正常。

setPreview:

描述
初始化预览播放器。
接口
- (void)setPreview:(TAVPreviewParam *)param
参数
参数名
类型
说明
param
TAVPreviewParam *
需要给一个父容器和渲染方式。
返回值
类型:void

setPlayLoop:

描述
设置是否循环播放。
接口
- (void)setPlayLoop:(BOOL)isLoop
参数
参数名
类型
说明
isLoop
BOOL
是否循环播放。
返回值
类型:void

isPlayLoop

描述
查询当前是否循环播放。
接口
- (BOOL)isPlayLoop
返回值
类型:BOOL
说明:是否循环播放。

play

描述
开始播放。
接口
- (void)play
返回值
类型:void

playAtTime:

描述
从某个时间开始播放。
接口
- (void)playAtTime:(CMTime)time
参数
参数名
类型
说明
time
CMTime
开始播放时间。
返回值
类型:void

pause

描述
暂停播放。
接口
- (void)pause
返回值
类型:void

stop

描述
停止播放。
接口
- (void)stop
返回值
类型:void

refresh

描述
刷新预览播放器。
接口
- (void)refresh
返回值
类型:void

seekToTime:

描述
seek 到指定时间。
接口
- (void)seekToTime:(CMTime)seekTime
参数
参数名
类型
说明
seekTime
CMTime
指定的播放时间。
返回值
类型:void

seekToTime:completion:

描述
seek 到指定时间,并回调 seek 是否完成。
接口
- (void)seekToTime:(CMTime)seekTime completion:(void (^)(BOOL finished))completion
参数
参数名
类型
说明
seekTime
CMTime
指定的播放时间。
completion
block
seek 完成回调。
返回值
类型:void

flushImmediately

描述
在改变资源后调用此接口重新生成播放资源。
接口
- (void)flushImmediately
返回值
类型:void
说明:由于内部存在异步状态,调用完 flushImmediately 后立即读取播放时间/是否正在播放可能不准确,需要在 flushImmediatelyCompletion: 的回调中再获取。

flushImmediatelyCompletion:

描述
带完成回调的 flushImmediately,回调触发时内部异步状态已还原完毕。
接口
- (void)flushImmediatelyCompletion:(void (^)(BOOL finished))completion
参数
参数名
类型
说明
completion
block
完成回调,finished 表示是否完成。
返回值
类型:void

preparePlayerItem

描述
flushImmediately 的拆分版本。该方法耗时较长,可在子线程调用;生成结果交给 bindPlayerItem:completion: 绑定到播放器。
接口
- (AVPlayerItem *)preparePlayerItem
返回值
类型:AVPlayerItem *
说明:播放器资源对象。

bindPlayerItem:completion:

描述
将 preparePlayerItem 生成的播放器资源绑定到播放器,需回到主线程调用。二者依次调用等价于 flushImmediately。
接口
- (void)bindPlayerItem:(AVPlayerItem *)playerItem completion:(void (^)(BOOL finished))completion
参数
参数名
类型
说明
playerItem
AVPlayerItem *
preparePlayerItem 返回的播放器资源。
completion
block
完成回调。
返回值
类型:void

getTotalDuration

描述
获取预览总时长。
接口
- (CMTime)getTotalDuration
返回值
类型:CMTime
说明:预览总时长。添加资源后需要调用 flushImmediately 后才能准确获取。

getClipsDuration

描述
获取主轨道总时长。
接口
- (NSTimeInterval)getClipsDuration
返回值
类型:NSTimeInterval
说明:主轨道总时长(秒),添加资源后可即时获取。

isPlaying

描述
查询当前是否在播放中。
接口
- (BOOL)isPlaying
返回值
类型:BOOL
说明:是否在播放中。

currentTime

描述
获取当前播放的时间(秒)。
接口
- (NSTimeInterval)currentTime
返回值
类型:NSTimeInterval
说明:当前播放时间。

currentCMTime

描述
获取当前播放的时间(CMTime)。
接口
- (CMTime)currentCMTime
返回值
类型:CMTime
说明:当前播放时间。

setPlayerViewFillMode:

描述
设置预览填充模式。
接口
- (void)setPlayerViewFillMode:(TAVPlayerFillMode)fillMode
参数
参数名
类型
说明
fillMode
TAVPlayerFillMode
填充模式。
返回值
类型:void

playerViewFillMode

描述
获取播放器填充模式。
接口
- (TAVPlayerFillMode)playerViewFillMode
返回值
类型:TAVPlayerFillMode
说明:当前填充模式。

registerPlayerObserver:

描述
注册播放状态监听者。
接口
- (void)registerPlayerObserver:(id<TAVEditorPlayerObserver>)observer;
参数
参数名
类型
说明
observer
id<TAVEditorPlayerObserver>
播放状态监听者。
返回值
类型:void

resignObserver:

描述
注销播放状态监听者。
接口
- (void)resignObserver:(id<TAVEditorPlayerObserver>)observer
参数
参数名
类型
说明
observer
id<TAVEditorPlayerObserver>
待注销的监听者。
返回值
类型:void

setRenderSize:

描述
设置当前渲染大小。
接口
- (void)setRenderSize:(CGSize)renderSize
参数
参数名
类型
说明
renderSize
CGSize
渲染尺寸。
返回值
类型:void

getRenderSize

描述
获取当前渲染大小。
接口
- (CGSize)getRenderSize
返回值
类型:CGSize
说明:当前渲染尺寸。

currentAVAsset

描述
获取当前播放器的完整 AVAsset。
接口
- (AVAsset *)currentAVAsset
返回值
类型:AVAsset *
说明:播放器当前使用的 AVAsset。

currentComposition

描述
获取当前播放器的完整 AVVideoComposition。
接口
- (AVVideoComposition *)currentComposition
返回值
类型:AVVideoComposition *
说明:播放器当前使用的视频合成描述。

setReverse:

描述
设置视频是否倒放。
接口
- (void)setReverse:(BOOL)isReverse
参数
参数名
类型
说明
isReverse
BOOL
YES 倒放,NO 正放。
返回值
类型:void

generateVideo:outputPath:progress:completion:

描述
生成并导出视频,config 传 nil 使用默认配置。
接口
- (void)generateVideo:(TAVEditorGenerateConfig *)config
outputPath:(NSString *)outputPath
progress:(void (^)(CGFloat progress))progressBlock
completion:(void (^)(NSError *error, NSString *outputPath))completion;
参数
参数名
类型
说明
config
TAVEditorGenerateConfig *
导出配置,传 nil 使用默认配置。
outputPath
NSString *
输出路径。
progressBlock
block
导出进度回调。
completion
block
导出完成回调,error 为 nil 表示成功。
返回值
类型:void

generateVideoWithCompressed:outputPath:progress:completion:

描述
按分辨率生成并导出视频。
接口
- (void)generateVideoWithCompressed:(TAVVideoCompressed)compressed
outputPath:(NSString *)outputPath
progress:(void (^)(CGFloat progress))progressBlock
completion:(void (^)(NSError *error, NSString *outputPath))completion;
参数
参数名
类型
说明
compressed
TAVVideoCompressed
480P(0) / 540P(1) / 720P(2) / 1080P(3)。
outputPath
NSString *
输出路径。
progressBlock
block
导出进度回调。
completion
block
导出完成回调。
返回值
类型:void

quickGenerateVideo:outputPath:progress:completion:

描述
快速生成并导出视频。
接口
- (void)quickGenerateVideo:(TAVEditorGenerateConfig *)config
outputPath:(NSString *)outputPath
progress:(void (^)(CGFloat progress))progressBlock
completion:(void (^)(NSError *error, NSString *outputPath))completion;
参数
参数名
类型
说明
config
TAVEditorGenerateConfig *
导出配置,传 nil 使用默认配置。
outputPath
NSString *
输出路径。
progressBlock
block
导出进度回调。
completion
block
导出完成回调。
返回值
类型:void

quickGenerateVideoWithCompressed:outputPath:progress:completion:

描述
按分辨率快速生成并导出视频。
接口
- (void)quickGenerateVideoWithCompressed:(TAVVideoCompressed)compressed
outputPath:(NSString *)outputPath
progress:(void (^)(CGFloat progress))progressBlock
completion:(void (^)(NSError *error, NSString *outputPath))completion;
参数
参数名
类型
说明
compressed
TAVVideoCompressed
480P(0) / 540P(1) / 720P(2) / 1080P(3)。
outputPath
NSString *
输出路径。
progressBlock
block
导出进度回调。
completion
block
导出完成回调。
返回值
类型:void

cancelGenerate:

描述
取消生成视频。
接口
- (void)cancelGenerate:(void(^ __nullable)(void))completion
参数
参数名
类型
说明
completion
block
取消完成回调,可传 nil。
返回值
类型:void

pauseGenerate

描述
暂停导出。
接口
- (void)pauseGenerate
返回值
类型:void

resumeGenerate

描述
继续导出。
接口
- (void)resumeGenerate
返回值
类型:void

getVideoFrameManager

描述
获取抽帧操作类。
接口
- (id<ITAVFrameProvider> _Nullable)getVideoFrameManager;
返回值
类型:id<ITAVFrameProvider>
说明:帧提供器接口实例。

数据模型与枚举

TAVReplaceItem

字段
类型
说明
itemId
int(只读)
替换项唯一标识,对应 LAKEntity.id。
type
TAVTemplateReplaceType(只读)
替换类型,当前仅 TAVTemplateReplaceTypeText(0)。
timeRange
CMTimeRange
该素材在时间轴上的区间。
scaleRect
CGRect
位置与大小,归一化数值 {centerX, centerY, width, height}。

TAVTextReplaceItem

TAVReplaceItem 子类。
字段
类型
说明
src
NSString *
文本内容。
textMaxLength
NSInteger(只读)
文本最大长度。

TAVTemplateConfig

字段
类型
说明
mediaType
TAVTemplateMediaType
1 仅视频 / 2 仅照片 / 3 视频+照片。
minAssetCount
int
素材最少个数,0 表示不限制。
maxAssetCount
int
素材最多个数,0 表示不限制。
clipPlaceHolders
NSArray<TAVClipPlaceHolder *> *
视频/图片坑位列表。
clipAudioHolders
NSArray<TAVAudioPlaceHolder *> *
音频坑位列表。
TAVClipPlaceHolder:contentDuration(CMTime)内容展示时间。
TAVAudioPlaceHolder:path、name、bgmId、duration(CMTime)、volume(0-1)、startOffset(CMTime)、loopCount(0 不播放 / 1 循环一次 / -1 无限循环)。

TAVTemplateCode

枚举值
值
说明
TAVTemplateCodeSuccess
0
成功。
TAVTemplateCodePathInvalid
1
模板路径无效。
TAVTemplateCodeAuthInvalid
2
无权限。