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

iOS

最近更新时间:2026-11-11 21:20:00
本文档已由 AI 辅助审校
我的收藏
本文主要介绍短视频编辑 SDK(不含 UI)的 iOS 端 API 接口文档,以便于查阅和使用。全部接口为 Objective-C 声明,时间参数统一使用 CoreMedia 的 CMTime / CMTimeRange。

TAVMagicBase

SDK 全局入口(TAVMagic/TAVMagicBase.h),提供初始化、全局配置与工厂方法。

接口方法汇总

API
描述
SDK 全局初始化,应在使用 Editor/Recorder 之前调用一次。
是否已完成初始化。
设置日志级别并注册日志监听。
校验某个特性是否已授权。
获取 SDK 当前版本号。
创建 Editor 实例。
创建 TemplateEditor 实例(剪同款)。
创建 Recorder 实例。
创建 Highlight 实例(高光成片)。

initSDK:

描述
SDK 全局初始化,传入 LightEngine 模型资源路径。必须在创建 TAVEditor / TAVTemplateEditor / TAVRecorder 之前调用一次。
接口
+ (BOOL)initSDK:(NSString *)assetsPath
参数
参数名
类型
说明
assetsPath
NSString *
LightEngine 模型资源根目录(LightCore.bundle 路径)。
返回值
类型:BOOL
说明:初始化是否成功。
NSString *assetsPath = [[NSBundle mainBundle] pathForResource:@"LightCore" ofType:@"bundle"];
BOOL ret = [TAVMagicBase initSDK:assetsPath];

isInitialized

描述
查询 SDK 是否已完成全局初始化。
接口
+ (BOOL)isInitialized
返回值
类型:BOOL
说明:YES 表示已完成 initSDK:,NO 表示未初始化。

setLogLevel:listener:

描述
设置日志级别并注册日志监听。
接口
+ (void)setLogLevel:(TAVLogLevel)logLevel listener:(nullable id<TAVLogListener>)listener
参数
参数名
类型
说明
logLevel
TAVLogLevel
日志级别,见下方枚举。
listener
id<TAVLogListener>
日志监听者,传 nil 表示不监听。
返回值
类型:void
TAVLogLevel:
枚举值
说明
TAVLogLevelUnknown
未知。
TAVLogLevelDefault
默认。
TAVLogLevelVerbose
最详细。
TAVLogLevelDebug
调试。
TAVLogLevelInfo
信息。
TAVLogLevelWarn
警告。
TAVLogLevelError
错误。
TAVLogLevelFatal
致命。
@protocol TAVLogListener <NSObject>
- (void)onLog:(TAVLogLevel)loggerLevel logMessage:(NSString *)logMessage;
@end

isFeatureAuthorized:

描述
校验某个特性是否已授权。
接口
+ (BOOL)isFeatureAuthorized:(NSString *)featureName
参数
参数名
类型
说明
featureName
NSString *
特性名称。
返回值
类型:BOOL
说明:YES 表示已授权,NO 表示未授权。

sdkVersion

描述
获取 SDK 当前版本号。
接口
+ (NSString *)sdkVersion
返回值
类型:NSString *
说明:SDK 版本号字符串。

createEditorWithRenderSize:

描述
创建 Editor 实例。需先调用 initSDK:;未初始化时尝试使用默认路径兜底,兜底失败返回 nil。
接口
+ (nullable TAVEditor *)createEditorWithRenderSize:(CGSize)renderSize
参数
参数名
类型
说明
renderSize
CGSize
画面渲染尺寸,根据宽高比缩放。传 CGSizeZero 由 SDK 自动适配。
返回值
类型:TAVEditor *
说明:创建成功返回实例,失败返回 nil。

createTemplateEditorWithRenderSize:

描述
创建 TemplateEditor 实例(剪同款),仅暴露模板/片段/播放/导出操作。需先调用 initSDK:,未初始化时尝试使用默认路径兜底,兜底失败返回 nil。
接口
+ (nullable TAVTemplateEditor *)createTemplateEditorWithRenderSize:(CGSize)renderSize
参数
参数名
类型
说明
renderSize
CGSize
画面渲染尺寸,根据宽高比缩放。传 CGSizeZero 由 SDK 自动适配。
返回值
类型:TAVTemplateEditor *
说明:创建成功返回实例,失败返回 nil。

createRecorder

描述
创建 Recorder 实例。需先调用 initSDK:,未初始化时尝试使用默认路径兜底,兜底失败返回 nil。
接口
+ (nullable TAVRecorder *)createRecorder
返回值
类型:TAVRecorder *
说明:创建成功返回实例,失败返回 nil。

createHighlightWithConfig:

描述
创建 Highlight 实例(高光成片)。需先调用 initSDK:。工厂内部会 copy 一份配置避免外部后续修改。
接口
+ (nullable TAVHighlight *)createHighlightWithConfig:(nullable TAVHLConfig *)config
参数
参数名
类型
说明
config
TAVHLConfig *
算法配置,传 nil 使用默认值。
返回值
类型:TAVHighlight *
说明:创建成功返回实例,失败返回 nil。
说明:
返回的实例内部持有 Classifier / GL 队列,用完须调用 [highlight destroy]。

TAVEditor

短视频编辑入口类(TAVMagic/TAVEditor.h)。所有编辑操作都通过该类进行。

接口方法汇总

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

initWithRenderSize:

描述
初始化编辑器。需先调用 [TAVMagicBase initSDK:]。
接口
- (instancetype)initWithRenderSize:(CGSize)renderSize;
参数
参数名
类型
说明
renderSize
CGSize
画面渲染尺寸,根据宽高比缩放。传 CGSizeZero 由 SDK 自动适配渲染尺寸。
返回值
类型:instancetype
说明:编辑器实例。
说明:
带 assetsPath: 参数的重载已标记为 deprecated,请使用 [TAVMagicBase initSDK:] + initWithRenderSize:。

editorWithRenderSize:

描述
初始化编辑器(类方法)。需先调用 [TAVMagicBase initSDK:]。
接口
+ (instancetype)editorWithRenderSize:(CGSize)renderSize;
参数
参数名
类型
说明
renderSize
CGSize
画面渲染尺寸,根据宽高比缩放。传 CGSizeZero 由 SDK 自动适配渲染尺寸。
返回值
类型:instancetype
说明:编辑器实例。
说明:
带 assetsPath: 参数的重载已标记为 deprecated,请使用 [TAVMagicBase initSDK:] + editorWithRenderSize:。

deinit

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

fork

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

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

描述
清空所有资源(video & bgm)和所有特效(sticker & filter & motion)。
接口
- (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
说明:是否调整成功。

flushImmediately

描述
在改变资源/BGM 后调用此接口重新生成播放资源。逻辑为:1、同步生成播放器资源;2、播放器绑定资源;3、异步还原状态(播放状态、播放时间)。
接口
- (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 生成的播放器资源绑定到播放器,需回到主线程调用。与 preparePlayerItem 依次调用等价于 flushImmediately。
接口
- (void)bindPlayerItem:(AVPlayerItem *)playerItem completion:(void (^)(BOOL finished))completion
参数
参数名
类型
说明
playerItem
AVPlayerItem *
preparePlayerItem 返回的播放器资源。
completion
block
完成回调。
返回值
类型:void

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。

setReverse:

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

setClipsRotation:

描述
设置全部资源旋转角度。
接口
- (void)setClipsRotation:(int)rotation
参数
参数名
类型
说明
rotation
int
旋转角度 0-360(AVFoundation 坐标系,渲染时表现为顺时针)。
返回值
类型:void

setClipRotation:index:

描述
根据下标设置指定资源的旋转角度。
接口
- (void)setClipRotation:(int)rotation index:(int)index
参数
参数名
类型
说明
rotation
int
旋转角度 0-360(AVFoundation 坐标系,渲染时表现为顺时针)。
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

addBgm:startAtVideoTime:timeRange:

描述
添加背景音乐。
接口
- (int)addBgm:(NSString *)bgmPath startAtVideoTime:(CMTime)startAtVideoTime timeRange:(CMTimeRange)timeRange
参数
参数名
类型
说明
bgmPath
NSString *
音乐素材的文件路径。
startAtVideoTime
CMTime
BGM 在时间轴中开始播放的时间(默认 0)。
timeRange
CMTimeRange
截取音乐素材的播放区间(默认整首)。
返回值
类型:int
说明:BGM 素材唯一 ID。

removeBgm:

描述
根据唯一 ID 删除背景音乐。
接口
- (BOOL)removeBgm:(int)bgmId
参数
参数名
类型
说明
bgmId
int
背景音乐添加时生成的 ID。
返回值
类型:BOOL
说明:是否删除成功。

removeAllBgm

描述
删除所有 BGM。
接口
- (void)removeAllBgm
返回值
类型:void

updateBgm:atVideoTime:

描述
调整 BGM 在视频中开始的位置。
接口
- (void)updateBgm:(int)bgmId atVideoTime:(CMTime)startAtVideoTime
参数
参数名
类型
说明
bgmId
int
背景音乐添加时生成的 ID。
startAtVideoTime
CMTime
BGM 在时间轴中开始播放的时间。
返回值
类型:void

updateBgm:playRange:

描述
设置 BGM 播放区间。
接口
- (void)updateBgm:(int)bgmId playRange:(CMTimeRange)timeRange
参数
参数名
类型
说明
bgmId
int
背景音乐添加时生成的 ID。
timeRange
CMTimeRange
截取音乐素材的播放区间(默认整首)。
返回值
类型:void

setBgm:volume:

描述
设置背景音乐播放音量。
接口
- (void)setBgm:(int)bgmId volume:(float)volume
参数
参数名
类型
说明
bgmId
int
背景音乐添加时生成的 ID。
volume
float
音量 0-1f。
返回值
类型:void

setBgm:extraInfo:

描述
设置背景音乐的额外信息(自定义保存信息)。
接口
- (void)setBgm:(int)bgmId extraInfo:(NSDictionary *)extraInfo
参数
参数名
类型
说明
bgmId
int
背景音乐添加时生成的 ID。
extraInfo
NSDictionary *
自定义保存信息。
返回值
类型:void

getBgmExtraInfo:

描述
获取背景音乐的额外信息。
接口
- (NSDictionary *)getBgmExtraInfo:(int)bgmId
参数
参数名
类型
说明
bgmId
int
背景音乐添加时生成的 ID。
返回值
类型:NSDictionary *
说明:扩展信息字典。

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。
speed
float
播放速度,1 正常,大于 1 快,小于 1 慢。
返回值
类型:void

getBgmSpeed:

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

getBgmInfos

描述
获取当前使用的背景音乐列表。
接口
- (NSArray<TAVBgmInfo *> *)getBgmInfos
返回值
类型:NSArray<TAVBgmInfo *> *
说明:BGM 信息数组,字段见 TAVBgmInfo。

setPreview:

描述
初始化预览播放器。
接口
- (void)setPreview:(TAVPreviewParam *)param
参数
参数名
类型
说明
param
TAVPreviewParam *
需要给一个父容器和渲染方式。
返回值
类型:void
TAVPreviewParam:
字段
类型
说明
videoView
UIView *(weak)
播放器的父容器,必填。
fillModel
TAVPlayerFillMode
拉伸模式,选填。
loop
BOOL
循环播放,默认 NO。
observer
id<TAVEditorPlayerObserver>(weak)
播放状态观察者,选填。
widgetContentView
TAVWidgetContentView *(weak)
贴纸/画中画等挂件的操作容器视图,不设置则使用默认。

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

描述
停止播放(会 seek 到 0)。
接口
- (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

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 *
说明:播放器当前使用的视频合成描述。

addFilter:strength:timeRange:

描述
添加滤镜。
接口
- (int)addFilter:(NSString *)lutPath strength:(CGFloat)strength timeRange:(CMTimeRange)timeRange
参数
参数名
类型
说明
lutPath
NSString *
滤镜素材路径。
strength
CGFloat
滤镜强度。
timeRange
CMTimeRange
滤镜生效区间。
返回值
类型:int
说明:创建滤镜时生成的唯一 ID。

setFilter:Strength:timeRange:

描述
调整滤镜强度与生效区间。
接口
- (void)setFilter:(int)lutId strength:(CGFloat)strength timeRange:(CMTimeRange)timeRange
参数
参数名
类型
说明
lutId
int
创建滤镜时生成的唯一 ID。
strength
CGFloat
滤镜强度。
timeRange
CMTimeRange
滤镜生效区间。
返回值
类型:void

removeFilter:

描述
删除滤镜。
接口
- (void)removeFilter:(int)lutId
参数
参数名
类型
说明
lutId
int
创建滤镜时生成的唯一 ID。
返回值
类型:void

removeAllFilter

描述
删除所有滤镜效果。
接口
- (void)removeAllFilter
返回值
类型:void

setFilter:trackIndex:

描述
保存滤镜轨道下标(业务使用)。
接口
- (void)setFilter:(int)lutId trackIndex:(int)trackIndex
参数
参数名
类型
说明
lutId
int
创建滤镜时生成的唯一 ID。
trackIndex
int
轨道下标。
返回值
类型:void

getFilterInfos

描述
获取当前所有已设置滤镜。
接口
- (NSArray<TAVFilterInfo *> *)getFilterInfos
返回值
类型:NSArray<TAVFilterInfo *> *
说明:滤镜信息数组,字段见 TAVFilterInfo。

addMotionEffect:timeRange:

描述
添加动效(特效)。
接口
- (int)addMotionEffect:(NSString *)path timeRange:(CMTimeRange)timeRange
参数
参数名
类型
说明
path
NSString *
特效素材路径。
timeRange
CMTimeRange
特效对应的时间区域。
返回值
类型:int
说明:创建特效时生成的 ID。

updateMotionEffect:playRange:

描述
更新特效播放时间。
接口
- (void)updateMotionEffect:(int)effectId playRange:(CMTimeRange)timeRange
参数
参数名
类型
说明
effectId
int
创建特效时生成的 ID。
timeRange
CMTimeRange
特效展示区间。
返回值
类型:void

removeMotionEffect:

描述
删除特效。
接口
- (void)removeMotionEffect:(int)effectId
参数
参数名
类型
说明
effectId
int
创建特效时生成的 ID。
返回值
类型:void

removeAllMotionEffect

描述
删除所有特效。
接口
- (void)removeAllMotionEffect
返回值
类型:void

setMotionEffect:trackIndex:

描述
保存特效轨道下标(业务使用)。
接口
- (void)setMotionEffect:(int)effectId trackIndex:(int)trackIndex
参数
参数名
类型
说明
effectId
int
创建特效时生成的 ID。
trackIndex
int
轨道下标。
返回值
类型:void

getEffectInfos

描述
获取当前所有已设置特效。
接口
- (NSArray<TAVEffectInfo *> *)getEffectInfos
返回值
类型:NSArray<TAVEffectInfo *> *
说明:特效信息数组,字段见 TAVEffectInfo。

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 使用默认配置(预览分辨率 / 30 帧 / 码率 810001000)。
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

getStickerManager

描述
获取贴纸操作类。
接口
- (id<ITAVStickerManager> _Nullable)getStickerManager
返回值
类型:id<ITAVStickerManager>
说明:贴纸操作接口实例。

getPipManager

描述
获取画中画操作类。
接口
- (id<ITAVPipManager> _Nullable)getPipManager
返回值
类型:id<ITAVPipManager>
说明:画中画操作接口实例。

getVideoFrameManager

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

getDraftManager

描述
获取草稿操作类。
接口
- (id<ITAVDraftManager> _Nullable)getDraftManager
返回值
类型:id<ITAVDraftManager>
说明:草稿操作接口实例。

ITAVFrameProvider

帧提供器接口(TAVMagic/ITAVFrameProvider.h),由 [editor getVideoFrameManager] 获取。

接口方法汇总

API
说明
getClipThumbnail:count:size:completion:
按主轨道下标异步批量抽帧。
getClipThumbnail:pts:size:completion:
按主轨道下标 + pts 异步抽帧。
getClipThumbnail:pts:size:
按主轨道下标 + pts 同步抽帧。
获取主轨 pts 渲染结果帧(异步)。
getClipFrameWithTimes:exportMode:longSide:completion:
批量获取主轨渲染结果帧(异步)。
getClipFrameAtTime:exportMode:longSide:
获取主轨 pts 渲染结果帧(同步)。
getClipFrameWithTimes:exportMode:longSide:
批量获取主轨渲染结果帧(同步)。
按资源路径异步批量抽帧。
getThumbnail:pts:size:completion:
按资源路径 + pts 异步抽帧。
getThumbnail:pts:size:
按资源路径 + pts 同步抽帧。
取消异步抽帧任务。

getClipFrameAtTime:exportMode:longSide:completion:

描述
获取主轨 pts 对应的渲染结果帧(异步)。
接口
- (id)getClipFrameAtTime:(CMTime)pts
exportMode:(BOOL)isExportMode
longSide:(CGFloat)length
completion:(void (^)(UIImage *image))completion;
参数
参数名
类型
说明
pts
CMTime
时间。
isExportMode
BOOL
是否导出模式:YES 抽帧结果与导出一致,NO 与预览一致,默认 NO。
length
CGFloat
最长边的长度,SDK 内部会根据长边大小计算短边的大小。
completion
block
结果回调。
返回值
类型:id
说明:Generator 对象,可传入 cancelGenerate: 取消生成。

getThumbnail:count:size:timeRange:completion:

描述
按视频资源路径批量抽帧(异步)。
接口
- (id)getThumbnail:(NSString *)videoPath
count:(int)count
size:(CGSize)size
timeRange:(CMTimeRange)timeRange
completion:(void (^)(NSArray<UIImage *> *images, NSError *error))thumbCompletion;
参数
参数名
类型
说明
videoPath
NSString *
视频资源路径。
count
int
数量。
size
CGSize
缩略图宽高。
timeRange
CMTimeRange
视频抽帧范围,默认为整个视频时间范围。
thumbCompletion
block
回调返回缩略图数组与错误。
返回值
类型:id
说明:Generator 对象,可传入 cancelGenerate: 取消生成。

cancelGenerate:

描述
取消生成缩略图。
接口
- (void)cancelGenerate:(id)generator
参数
参数名
类型
说明
generator
id
异步接口返回的 generator 对象。
返回值
类型:void

ITAVStickerManager

贴纸操作接口(TAVMagic/ITAVStickerManager.h),由 [editor getStickerManager] 获取。

接口方法汇总

API
说明
setStickerViewDataSource:
设置自定义贴纸视图数据源(遵守 ITAVStickerViewDataSource)。
创建贴纸数据模型。
loadStickerItem:
加载贴纸。
removeStickerItem:
移除指定贴纸。
removeAllStickerItem
移除所有贴纸。
removeCurrentSticker
移除当前贴纸。
getCurrentStickerItem
获取当前贴纸 Item。
getAllStickerItems
获取所有贴纸 Item。
getStickerItemWithSticker:
根据 TAVSticker 取贴纸 Item。
getCurrentSticker
获取当前贴纸。
getCurrentStickerView
获取当前贴纸视图。
fetchStickerView:
取贴纸对应视图(按贴纸)。
fetchStickerViewWithItem:
取贴纸对应视图(按贴纸 Item)。
addStickerObserver:
添加贴纸变化观察者。
removeStickerObserver:
移除贴纸变化观察者。
activeStickerItem:
激活贴纸。
resignStickerItem:
注销贴纸。
resignCurrentStickerItem
注销当前贴纸。
resignAllStickerItems
注销全部贴纸。
currentVideoRect
获取当前视频渲染区域。

createStickerItem:stickerType:

描述
创建贴纸数据模型。
接口
- (TAVMediaStickerItem *)createStickerItem:(NSString *)stickerPath stickerType:(TAVStickerItemType)stickerItemType
参数
参数名
类型
说明
stickerPath
NSString *
贴纸路径。
stickerItemType
TAVStickerItemType
贴纸类型:TAVStickerItemTypeMotion(0) / TAVStickerItemTypeText(1) / TAVStickerItemTypeImage(2)。
返回值
类型:TAVMediaStickerItem *
说明:贴纸数据模型。

ITAVStickerViewDataSource

@protocol ITAVStickerViewDataSource <NSObject>
- (TAVStickerView *)stickerViewWithStickerItem:(TAVMediaStickerItem *)stickerItem;
@end

TAVStickerContextObserver

贴纸变化观察者,方法均为 @optional。
回调
说明
stickerContextStickerListDidChange:
贴纸集合整体变化(新增/删除)。
stickerContextCurrentStickerDidChange:
当前激活贴纸变化。
stickerContextShouldRefreshVideoFrame:
需要刷新视频帧。

TAVMediaStickerItem 主要属性

属性
类型
说明
stickerType
TAVStickerType
贴纸类型。
subImageType
TAVStickerImageSubType
图片贴纸子类型(_unkown / _image / _gif / _apng)。
stickerID
NSString *
贴纸 ID。
stickerPath
NSString *(只读)
贴纸路径。
imageFilePath
NSString *
图片贴纸的图片路径。
text
NSString *
文字贴纸的文本。
defaultText
NSString *
文字贴纸的默认文本。
textColor
UIColor *
文字颜色。
bgColor
UIColor *
整个贴纸背景色。
stickerFont
TAVMediaStickerFont *
文字字体(fontPath / fontFamily / fontStyle)。
textMaxLength
NSInteger
可输入文字最大字数。
contentMode
TAVStickerContentMode
文字框影响区域。
animationMode
TAVStickerAnimationMode
动效播放模式。
applyTextStroke
BOOL
是否开启文字描边。
textStrokeWidth
CGFloat
文字描边厚度。
textStrokeColor
UIColor *
文字描边颜色。
textBgColor
UIColor *
文字背景颜色。
textBgAlpha
CGFloat
文字背景透明度 0-1。
stickerScale
CGFloat
贴纸缩放。
stickerEdgeInsets
UIEdgeInsets
贴纸边距。
timeRange
CMTimeRange
贴纸显示时间区间(继承自 TAVMediaEffectItem)。
主要方法:
- (instancetype)initWithStickerPath:(NSString *)stickerPath stickerType:(TAVStickerType)stickerType;
- (instancetype)initWithTextSticker:(TAVSticker *)sticker;
- (TAVStickerSolidItem *)findSolidLayer;
- (TAVStickerTextItem *)findTextLayer;
- (void)updateTrackInfoAt:(CMTime)pts renderSize:(CGSize)renderSize;

ITAVPipManager

画中画操作接口(TAVMagic/ITAVPipManager.h),由 [editor getPipManager] 获取。

接口方法汇总

API
说明
setPipViewDataSource:
设置自定义画中画视图数据源(遵守 ITAVPipViewDataSource)。
创建画中画对象。
loadPip:
添加画中画。
removePip:
删除指定画中画。
removeCurrentPip
删除当前画中画。
removeAllPip
删除所有画中画。
getAllPipItems
获取所有画中画对象。
getCurrentPipItem
获取当前画中画对象。
addPipObserver:
添加画中画变化观察者。
removePipObserver:
移除画中画变化观察者。
activePip:
激活画中画。
resignPip:
注销画中画。
resignCurrentPip
注销当前画中画。
fetchPipView:
通过 pipItem 查找对应 pipView。

createPipItem:mediaType:

描述
创建画中画对象。
接口
- (TAVMediaPipItem *)createPipItem:(NSString *)filePath mediaType:(NSInteger)mediaType
参数
参数名
类型
说明
filePath
NSString *
画中画路径。
mediaType
NSInteger
资源类型,0:视频,1:图片。
返回值
类型:TAVMediaPipItem *
说明:画中画对象。

TAVPipContextObserver

画中画变化观察者,方法均为 @optional。
回调
说明
didShowPipView:
画中画视图已显示。
didHidePipView:
画中画视图已隐藏。
didRemovePipView:
画中画视图已移除。
didActivePipView:
画中画视图被激活。
didResignPipView:
画中画视图被注销。

ITAVDraftManager

草稿箱操作管理类(TAVMagic/ITAVDraftManager.h),由 [editor getDraftManager] 获取。

接口方法汇总

API
说明
setDraftStorageDir:
设置草稿存储路径,不设置则使用 SDK 内置默认路径。
readDraftList
获取草稿列表。
deleteDraft:
删除指定草稿。
deleteAllDrafts
删除所有草稿。
生成草稿,资源随草稿缓存。
generateDraftNoCacheResources
生成草稿,不缓存资源(用户自管)。
getCurrentDraft
获取当前草稿。
加载指定草稿。
resetDraftRecord
重置/开始记录草稿。
commit:
提交一次草稿。
getCommitTags
获取提交的标记值列表。
canUndo
是否可撤销。
canRedo
是否可重做。
undo:
撤销。
redo:
重做。
addDraftStateListener:
添加草稿状态监听。
removeDraftStateListener:
删除草稿状态监听。

generateDraft

描述
生成草稿到预设定目录。草稿使用到的资源(视频、图片、画中画、bgm、贴纸、滤镜等)会缓存到草稿目录,随草稿删除一起删除。
接口
- (BOOL)generateDraft
返回值
类型:BOOL
说明:是否生成成功。

loadDraft:onDraftLoadingFinished:

描述
加载指定草稿。
接口
- (void)loadDraft:(TAVDraft *)draft onDraftLoadingFinished:(TAVDraftLoadingCallBack)callback
参数
参数名
类型
说明
draft
TAVDraft *
草稿对象。
callback
TAVDraftLoadingCallBack
加载结果回调。
返回值
类型:void
typedef void(^TAVDraftLoadingCallBack)(TAVDraftLoadingResult *draftLoadingResult);

回调与监听

typedef void(^TAVDraftActionCallBack)(NSString *tag, TAVDiffResult *diffResult, NSString *errMsg);

@protocol ITAVDraftStateListener <NSObject>
- (void)onUndoStateChange:(BOOL)canUndo;
- (void)onRedoStateChange:(BOOL)canRedo;
@end

错误代码

错误代码
常量名
描述
100
TAVDraftLoadingErrorSDKInternal
SDK 内部错误。
101
TAVDraftLoadingErrorResourceNotFound
资源不存在。
102
TAVDraftLoadingErrorSDKInternalResourceInvalid
资源格式错误。
-1
TAVDraftLoadingErrorUnknown
未知错误。

TAVEditorDefinitions(数据模型与枚举)

TAVPreviewParam

字段
类型
说明
videoView
UIView *
播放器父容器,必填。
fillModel
TAVPlayerFillMode
拉伸模式。
loop
BOOL
循环播放,默认 NO。
observer
id<TAVEditorPlayerObserver>
播放状态观察者。
widgetContentView
TAVWidgetContentView *
挂件操作容器视图。

TAVEditorPlayerObserver

@protocol TAVEditorPlayerObserver <NSObject>
@optional
- (void)mediaPlayerItemDidChange:(AVPlayerItem *)playerItem;
- (void)mediaPlayerProgressDidChange:(CMTime)currentTime;
- (void)mediaPlayerStateDidChange:(TAVPlaybackState)state;
- (void)mediaPlayerSpeedDidChange:(CGFloat)speed;
- (void)mediaPlayerDidPlayToEnd;
- (void)mediaPlayerVideoRectDidChange:(CGRect)videoRect;
@end

TAVVideoCompressed

枚举值
值
说明
TAVVideoCompressed480P
0
640*480。
TAVVideoCompressed540P
1
960*540。
TAVVideoCompressed720P
2
1280*720。
TAVVideoCompressed1080P
3
1920*1080。

TAVEditorGenerateConfig

字段
默认值
videoConfig.resolution
不设置时使用预览分辨率
videoConfig.frameRate
30
videoConfig.videoBitRate
8 * 1000 * 1000
videoConfig.videoCodecType
AVVideoCodecH264(可设 AVVideoCodecTypeHEVC)
videoConfig.exportTimeRange
全部时长
audioConfig.sampleRate
44100
audioConfig.audioBitRate
128000
audioConfig.channelCount
2(双声道)

TAVEditorMediaType

枚举值
值
说明
TAVEditorMediaTypeUnknown
0
未知。
TAVEditorMediaTypeVideo
1 << 0
视频。
TAVEditorMediaTypeAudio
1 << 1
音频。
TAVEditorMediaTypeImage
1 << 2
照片。

TAVClipInfo

字段
类型
说明
uniqueID
NSString *
唯一标识。
index
NSInteger
下标。
mediaType
TAVEditorMediaType
资源类型。
filePath
NSString *
资源路径。
asset
AVAsset *
视频资源对应的 AVAsset。
image
UIImage *
图片。
speed
float
变速。
naturalSize
CGSize
资源尺寸。
timeRange
CMTimeRange
资源在时间轴内的范围(受 speed 影响)。
startTime
CMTime
在时间轴中的开始时间。
sourceUseRange
CMTimeRange
资源实际使用范围。
sourceRange
CMTimeRange
原始资源时间区间。
duration
CMTime
在时间轴中的总时长。
transitionIntersectionDuration
CMTime
转场重叠时长。
volume
CGFloat
音量。
clipTransform
CGAffineTransform
裁剪形变。
clipSize
CGSize
裁剪大小。
cropInfo
TAVMediaAssetCropInfo *
裁剪页信息。

TAVBgmInfo

字段
类型
说明
bgmId
int
BGM ID。
bgmPath
NSString *
BGM 路径。
volume
float
音量。
speed
float
速率。
startTime
CMTime
时间轴开始播放位置。
timeRange
CMTimeRange
时间轴播放区间。
sourceRange
CMTimeRange
资源实际区间。
sourceUseRange
CMTimeRange
资源实际使用范围。
extraInfo
NSDictionary *
扩展信息。

TAVFilterInfo / TAVEffectInfo

TAVFilterInfo 字段
TAVEffectInfo 字段
类型
说明
lutId
effectId
int
唯一 ID。
lutPath
effectPath
NSString *
素材路径。
strength
—
CGFloat
滤镜强度。
timeRange
timeRange
CMTimeRange
生效/播放区间。
extraInfo
extraInfo
NSDictionary *
扩展字段。
trackIndex
trackIndex
NSInteger
轨道下标(业务使用)。