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

Android

最近更新时间:2026-11-11 21:20:00
本文档已由 AI 辅助审校
我的收藏
本文介绍剪同款 SDK 的 Android API。SDK 初始化与通用导出配置见编辑 API 文档;模板加载、素材填充与导出的组合用法见 功能特性 / 剪同款。

TAVTemplateEditor

剪同款编辑接口,通过 TAVMagicFactory.createTemplateEditor() 创建。
模板中的音乐、转场等效果由模板配置驱动。本接口提供素材填充、裁剪、音量、变速、文字替换、播放与导出能力。
API
描述
初始化预览或离屏编辑环境。
fork
复制当前状态,创建独立编辑器。
release
释放编辑器资源。
设置模板目录。
获取当前模板目录。
读取模板配置及坑位限制。
向末尾追加一个视频。
在指定位置批量插入视频。
向末尾追加一张图片,并指定展示时长。
批量插入图片,每张使用相同展示时长。
获取已添加的素材数量。
移除指定素材。
设置素材内的开始和结束时间。
设置素材画面裁剪区域。
设置单个素材原声音量。
设置全部素材原声音量。
获取素材原声音量。
设置视频播放速度。
获取视频播放速度。
获取媒体文件信息。
获取原始帧抽取接口。
startPlay
开始播放。
设置预览播放区间。
恢复播放。
pausePlay
暂停播放。
获取当前内容总时长。
isPlaying
查询播放状态。
跳转到指定时间。
注册播放进度及状态监听。
刷新编辑结果。
刷新编辑结果,并在完成后回调。
按预设质量等级导出。
按自定义配置导出。
取消导出。
获取模板中的可替换文字。
更新模板文字内容。
获取渲染画布尺寸。
设置剪同款预览尺寸。

initWithPreview

描述
初始化编辑环境,参数字段见本篇 PreviewParam。
需要预览:设置 videoView,使用 SCENE_PLAY。
仅用于导出:videoView 传 null,scene 设为 TAVEditorConstants.SCENE_EXPORT。
接口
void initWithPreview(TAVEditorConstants.PreviewParam param)
参数
参数名
类型
说明
param
TAVEditorConstants.PreviewParam
初始化参数,主要字段见本篇 PreviewParam。
返回值
类型:void
说明:无返回值。

fork

描述
复制当前模板、素材、裁剪、音量和文字状态,创建独立编辑器。新实例使用结束后需单独调用 release()。
param 传 null:不显示预览,关闭自动播放和循环播放,场景仍为 SCENE_PLAY。
仅用于导出:显式设置 param.scene = TAVEditorConstants.SCENE_EXPORT。
接口
TAVTemplateEditor fork(@Nullable TAVEditorConstants.PreviewParam param)
参数
参数名
类型
说明
param
TAVEditorConstants.PreviewParam
新实例的初始化参数,可为 null。
返回值
类型:TAVTemplateEditor
说明:独立实例;当前状态不可用于派生、实例已释放或派生失败时返回 null。

release

描述
释放编辑器及渲染资源。调用后不要再使用该实例;重新编辑时需创建新实例。
接口
void release()
参数
无。
返回值
类型:void
说明:无返回值。

setTemplateDir

描述
设置剪同款模板目录。模板必须包含有效的视频或图片坑位,并具备对应的 License 授权。
接口
int setTemplateDir(String path)
参数
参数名
类型
说明
path
String
模板目录的绝对路径。
返回值
类型:int
说明:0 成功;-1 未解析到有效的素材坑位;-2 授权校验失败。只有返回 0 后才继续填充模板素材。

getTemplateDir

描述
读取当前编辑器的模板目录。
接口
String getTemplateDir()
参数
无。
返回值
类型:String
说明:当前模板目录路径。

getTemplateConfig

描述
读取模板允许的媒体类型、素材数量及坑位时长,用于添加素材前校验输入。
路径是否有效,以 setTemplateDir 的返回码为准,不要仅判断配置对象是否为 null。未解析到素材坑位时,clipPlaceHolders 为空数组,setTemplateDir 返回 -1。
接口
TAVTemplateConfig getTemplateConfig(String templatePath)
参数
参数名
类型
说明
templatePath
String
模板目录的绝对路径。
返回值
类型:TAVTemplateConfig
说明:模板配置,字段见本篇 TAVTemplateConfig。

addVideoClip

描述
向素材列表末尾追加一个视频文件,按添加顺序填充模板坑位。
接口
int addVideoClip(String path)
参数
参数名
类型
说明
path
String
可读取的视频文件绝对路径。
返回值
类型:int
说明:添加成功时返回素材下标,从 0 开始。添加未被接受时也返回 0,因此不能仅凭返回值判断是否成功。

addVideoClip(批量插入)

描述
在指定位置按列表顺序插入视频,原有素材向后顺延。输入文件、下标和数量需满足模板要求。
接口
int addVideoClip(int clipIndex, List<String> paths)
参数
参数名
类型
说明
clipIndex
int
插入下标,从 0 开始,可插入到列表末尾。
paths
List<String>
视频文件绝对路径列表。
返回值
类型:int
说明:插入成功时返回 clipIndex,插入未被接受时返回 0。由于 0 也可能是有效下标,不能仅凭返回值判断是否成功。

addImageClip

描述
向素材列表末尾追加一张图片。duration 通常使用对应坑位的 contentDuration;需大于 0,SDK 不会自动改为 3 秒。
接口
int addImageClip(String path, long duration)
参数
参数名
类型
说明
path
String
可读取的图片文件绝对路径。
duration
long
展示时长,单位微秒,需大于 0。
返回值
类型:int
说明:添加成功时返回素材下标,添加未被接受时也返回 0,因此不能仅凭返回值判断是否成功。

addImageClip(批量插入)

描述
在指定位置插入多张图片,后续素材向后顺延。每张图片使用相同的 duration,需大于 0,SDK 不会自动改为 3 秒。
接口
int addImageClip(int clipIndex, List<String> paths, long duration)
参数
参数名
类型
说明
clipIndex
int
插入下标,从 0 开始,可插入到列表末尾。
paths
List<String>
图片文件绝对路径列表。
duration
long
每张图片的展示时长,单位微秒,需大于 0。
返回值
类型:int
说明:插入成功时返回 clipIndex,插入未被接受时返回 0。由于 0 也可能是有效下标,不能仅凭返回值判断是否成功。

getClipCount

描述
获取当前通过添加接口加入的视频和图片素材数量。
接口
int getClipCount()
参数
无。
返回值
类型:int
说明:素材数量。

removeClip

描述
移除指定下标的素材,后续素材下标前移。下标越界时不执行删除。删除后调用 flushImmediately() 更新预览。
接口
void removeClip(int clipIndex)
参数
参数名
类型
说明
clipIndex
int
素材下标,有效范围为 0 至 getClipCount() - 1。
返回值
类型:void
说明:无返回值。

setClipRange

描述
设置素材文件内的开始和结束时间,不改变素材在模板时间线上的位置。
视频:区间为 startTimeUs 至 endTimeUs,须在视频实际时长内。
图片:展示时长为 endTimeUs - startTimeUs。
起点需非负,结束时间需大于起点。修改后调用 flushImmediately() 更新预览。
接口
void setClipRange(int clipIndex, long startTimeUs, long endTimeUs)
参数
参数名
类型
说明
clipIndex
int
素材下标。
startTimeUs
long
素材内的开始时间,单位微秒。
endTimeUs
long
素材内的结束时间,单位微秒,不是持续时长。
返回值
类型:void
说明:无返回值。

setClipRect

描述
设置视频或图片的画面裁剪区域。坐标以素材经当前矩阵变换后的包围矩形为基准,使用比例值,不以整个画布为基准。
RectF(0, 0, 1, 1):保留完整区域。
null:清除裁剪。
修改后调用 flushImmediately() 更新预览。
接口
void setClipRect(int clipIndex, RectF rectF)
参数
参数名
类型
说明
clipIndex
int
素材下标。
rectF
RectF
归一化裁剪区域,可为 null。
返回值
类型:void
说明:无返回值。

setVideoClipVolume

描述
设置指定素材的原声音量,不是模板 BGM 音量。1.0f 为原音量,0 为静音。修改后调用 flushImmediately()。
接口
void setVideoClipVolume(int clipIndex, float volume)
参数
参数名
类型
说明
clipIndex
int
素材下标。
volume
float
音量系数,建议范围 0 至 3.0f。
返回值
类型:void
说明:无返回值。

setAllClipsVolume

描述
统一设置全部已添加素材的原声音量。后续可用 setVideoClipVolume 调整某个素材。修改后调用 flushImmediately()。
接口
void setAllClipsVolume(float volume)
参数
参数名
类型
说明
volume
float
音量系数,建议范围 0 至 3.0f;1.0f 为原音量,0 为静音。
返回值
类型:void
说明:无返回值。

getVideoClipVolume

描述
读取指定素材当前的原声音量。
接口
float getVideoClipVolume(int clipIndex)
参数
参数名
类型
说明
clipIndex
int
有效的素材下标。
返回值
类型:float
说明:音量系数。

setVideoClipSpeed

描述
设置视频素材的播放速度,1.0f 为原速,小于 1.0f 为慢速,大于 1.0f 为快速。需考虑变速后的素材时长能否满足模板坑位要求。修改后调用 flushImmediately()。
接口
void setVideoClipSpeed(int clipIndex, float speed)
参数
参数名
类型
说明
clipIndex
int
视频素材下标。
speed
float
正的、有限的播放速度系数。
返回值
类型:void
说明:无返回值。

getVideoClipSpeed

描述
读取视频素材当前的播放速度。
接口
float getVideoClipSpeed(int clipIndex)
参数
参数名
类型
说明
clipIndex
int
有效的视频素材下标。
返回值
类型:float
说明:播放速度系数。

getVideoInfo

描述
读取媒体文件的时长、尺寸等信息,用于添加素材前校验。该接口不负责将文件加入编辑器。
接口
TAVVideoInfo getVideoInfo(String path)
参数
参数名
类型
说明
path
String
媒体文件的绝对路径。
返回值
类型:TAVVideoInfo
说明:媒体信息,主要字段为 duration(微秒)、natureW(宽度)、natureH(高度)和 frameRate(帧率)。调用方需校验文件可读性及返回信息,不应仅用返回对象是否为 null 判定文件有效。

getThumbnailProvider

描述
获取视频原始帧抽取接口,支持素材缩略图读取。具体抽帧方法见编辑 API 文档中的 ITAVThumbProvider。
接口
ITAVThumbProvider getThumbnailProvider(boolean forceUseSoftwareDecoding)
参数
参数名
类型
说明
forceUseSoftwareDecoding
boolean
是否强制使用软件解码。
返回值
类型:ITAVThumbProvider
说明:抽帧接口;使用结束后按其生命周期要求调用 release()。

startPlay

描述
开始播放当前内容。需先完成初始化、设置有效模板并添加素材;已经在播放时调用会重新开始播放。
接口
void startPlay()
参数
无。
返回值
类型:void
说明:无返回值。

setPlayTimeRange

描述
设置预览播放区间,第二个参数为持续时长,不是结束时间。是否循环由初始化参数 loopPlay 决定,本接口不自动开启循环。
应传入有效的正持续时长;不要用 0 或负数表示“播放到末尾”。
接口
void setPlayTimeRange(long startTime, long duration)
参数
参数名
类型
说明
startTime
long
时间线起点,单位微秒。
duration
long
播放区间持续时长,单位微秒。
返回值
类型:void
说明:无返回值。

resumePlay

描述
恢复暂停的预览播放。
接口
void resumePlay()
参数
无。
返回值
类型:void
说明:无返回值。

pausePlay

描述
暂停预览,可通过 resumePlay() 恢复。
接口
void pausePlay()
参数
无。
返回值
类型:void
说明:无返回值。

getTotalDuration

描述
获取当前内容总时长。播放器时长尚未就绪时,SDK 会尝试根据素材时长和速度计算;未就绪或无法得到有效时长时返回 0。
接口
long getTotalDuration()
参数
无。
返回值
类型:long
说明:总时长,单位微秒。

isPlaying

描述
查询当前是否正在播放。
接口
boolean isPlaying()
参数
无。
返回值
类型:boolean
说明:true 表示正在播放,false 表示未处于播放状态。

seekToTime

描述
跳转到时间线上的指定位置,可选择非精准或精准跳转。
接口
void seekToTime(long timeUs, boolean isInAccurate)
参数
参数名
类型
说明
timeUs
long
时间线目标位置,单位微秒。
isInAccurate
boolean
true 为非精准跳转,跳到临近关键帧;false 为精准跳转。
返回值
类型:void
说明:无返回值。

setVideoPreviewListener

描述
注册预览播放进度和状态监听。
接口
void setVideoPreviewListener(TAVPreviewListener listener)
参数
参数名
类型
说明
listener
TAVPreviewListener
监听器,回调签名见本篇对应章节。
返回值
类型:void
说明:无返回值。

flushImmediately

描述
刷新当前帧,使素材添加、删除、参数调整及文字替换的结果在预览中生效。
接口
void flushImmediately()
参数
无。
返回值
类型:void
说明:无返回值。

flushImmediately(带回调)

描述
刷新当前帧,并在完成后回传本次刷新标识。
接口
void flushImmediately(@Nullable String tag, @Nullable TAVConsumer<String> callback)
参数
参数名
类型
说明
tag
String
刷新标识,可为 null。
callback
TAVConsumer<String>
完成回调,接收 tag,可为 null。
返回值
类型:void
说明:无返回值。

generateVideo

描述
按预设等级导出 9:16 竖屏视频,具体尺寸见本篇 导出等级。导出结果通过 TAVEditorGenerateListener 回传。
输出路径须可写,调用前需准备好父目录。
接口
void generateVideo(@TAVEditorConstants.GenerateLevel int level, String outputPath, TAVEditorGenerateListener listener)
参数
参数名
类型
说明
level
int
TAVEditorConstants.VIDEO_LEVEL_* 导出等级。
outputPath
String
输出文件的绝对路径。
listener
TAVEditorGenerateListener
开始、进度、完成及取消回调。
返回值
类型:void
说明:无同步返回值,完成时根据回调结果判断成功或失败。

generateVideo(自定义配置)

描述
使用 config 指定输出宽高、帧率和码率,不使用预设等级的固定尺寸。配置字段见编辑 API 文档的 TAVEditorGenerateConfig。
接口
void generateVideo(TAVEditorGenerateConfig config, String outputPath, TAVEditorGenerateListener listener)
参数
参数名
类型
说明
config
TAVEditorGenerateConfig
输出宽高、帧率、码率等配置。
outputPath
String
可写的输出文件绝对路径,需提前准备父目录。
listener
TAVEditorGenerateListener
导出监听器。
返回值
类型:void
说明:无同步返回值,完成时根据回调结果判断成功或失败。

cancelGenerate

描述
取消正在进行的导出任务,通过导出监听器的 onGenerateCanceled() 接收取消通知。
接口
void cancelGenerate()
参数
无。
返回值
类型:void
说明:无返回值。

getReplaceItems

描述
获取模板内可替换的文字内容。当前替换类型只有 TEXT,对应 TAVTextReplaceItem。添加的视频和图片通过素材接口管理,不属于这里的文字替换列表。
接口
List<TAVReplaceItem> getReplaceItems()
参数
无。
返回值
说明:文字替换项列表,没有可替换文字时为空;字段见本篇 TAVReplaceItem 及 TAVTextReplaceItem。

replaceItem

描述
根据替换项的 id 更新模板文字。将获取到的 TAVTextReplaceItem 的 src 改为新文字后传入,随后调用 flushImmediately() 更新预览。
接口
void replaceItem(TAVReplaceItem item)
参数
参数名
类型
说明
item
TAVReplaceItem
当前支持 type = TEXT 的 TAVTextReplaceItem,须保留模板中对应的 id。
返回值
类型:void
说明:无返回值。

getRenderSize

描述
获取当前剪同款渲染画布的宽高。
接口
Size getRenderSize()
参数
无。
返回值
类型:android.util.Size
说明:当前画布尺寸,单位像素;使用前需确认宽高有效。

setRenderSize

描述
设置剪同款预览画布尺寸。建议在添加素材前调用。不指定时,SDK 按设备等级与 9:16 比例确定尺寸。
预览固定为 9:16 竖屏。SDK 保留输入宽高中的较大值作为长边,短边按 9 / 16 计算后四舍五入,再调整为偶数,例如 (1080, 1080) 会变为 (608, 1080)。
自定义导出尺寸请设置 TAVEditorGenerateConfig,不要使用此接口。
接口
void setRenderSize(int width, int height)
参数
参数名
类型
说明
width
int
期望预览宽度,单位像素,需大于 0。
height
int
期望预览高度,单位像素,需大于 0。
返回值
类型:void
说明:无返回值。

TAVEditorConstants

剪同款使用的通用常量和初始化参数(TAVEditorConstants)。

PreviewParam

初始化及 fork 使用的参数类型为 TAVEditorConstants.PreviewParam。
字段
类型
说明
默认值
videoView
FrameLayout
预览容器,传 null 时无画面上屏。
null
autoPlay
boolean
是否自动开始播放。
true
loopPlay
boolean
是否循环播放。
true
scene
int
SCENE_PLAY(0)为播放场景;SCENE_EXPORT(1)用于仅保留编辑状态、随后导出。
SCENE_PLAY
renderSize
Size
初始渲染尺寸,单位像素。
null

导出等级

用于 generateVideo(int level, ...) 的预设等级。剪同款模式的输出尺寸如下:
常量
值
输出宽 × 高(像素)
VIDEO_LEVEL_480P
0
480 × 854
VIDEO_LEVEL_540P
1
540 × 960
VIDEO_LEVEL_720P
2
720 × 1280
VIDEO_LEVEL_1080P
3
1080 × 1920

TAVTemplateConfig

模板配置(TAVTemplateConfig),由 getTemplateConfig(...) 返回。
字段
类型
说明
mediaType
TAVMediaType
允许输入的媒体类型:VIDEO、PHOTO 或 MULTI。
minAssetCount
int
最少输入素材数量。
maxAssetCount
int
最多输入素材数量。
clipPlaceHolders
视频或图片坑位列表,按模板顺序排列;无坑位时为空数组。
audioPlaceHolders
TAVAudioPlaceHolder[]
音频坑位信息;由模板配置决定。
若存在固定正时长的素材坑位,返回的最小和最大素材数量均为坑位数;否则按模板声明的数量约束及实际坑位数确定。调用方应采用配置返回的限制,不自行假定素材数量。

TAVClipPlaceHolder

视频或图片坑位(TAVClipPlaceHolder)。
字段
类型
说明
contentDuration
long
坑位要求的素材展示时长,单位微秒。

TAVReplaceItem

模板替换项基类(TAVReplaceItem)。
字段
类型
说明
id
int
模板内的素材标识,用于定位替换目标。
type
TAVEditorConstants.TAVReplaceType
当前取值为 TEXT。
timeRange
TAVTimeRange
时间区间,fromUs(startUs, durationUs) 使用起点和持续时长,单位微秒。
screenTransform
ScreenTransform
定位组件,可能为 null;SDK 用于计算 renderRect。
renderRect
RectF
预览容器本地坐标下的包围矩形,单位像素;无有效预览容器尺寸或定位信息时为 null。

TAVTextReplaceItem

文字替换项(TAVTextReplaceItem),继承 TAVReplaceItem,新增公开字段 String src 表示文字内容。
描述
使用模板中已有的 id 和 type 构造文字替换项,或直接修改 getReplaceItems() 返回的文字项。
接口
TAVTextReplaceItem(int id, TAVEditorConstants.TAVReplaceType type, String src, TAVTimeRange timeRange)
TAVTextReplaceItem(int id, TAVEditorConstants.TAVReplaceType type, String src)
参数
参数名
类型
说明
id
int
模板内已有的替换目标标识。
type
TAVEditorConstants.TAVReplaceType
使用 TEXT。
src
String
新文字内容。
timeRange
TAVTimeRange
时间区间;未传时使用 TAVTimeRange.INVALID。
返回值
类型:TAVTextReplaceItem
说明:新建的文字替换对象;构造本身不会更新模板,需调用 replaceItem(...)。

TAVPreviewListener

预览监听器(TAVPreviewListener),通过 setVideoPreviewListener(...) 注册。

onPreviewProgress

描述
通知当前播放位置。
接口
void onPreviewProgress(long time)
参数
参数名
类型
说明
time
long
时间线播放位置,单位微秒。
返回值
类型:void
说明:无返回值。

onStatusChanged

描述
通知播放状态变化。
接口
void onStatusChanged(@Nullable TAVEditorConstants.EditorPlayerStatus status)
参数
参数名
类型
说明
status
TAVEditorConstants.EditorPlayerStatus
当前播放状态,枚举定义见 编辑的 API 文档。
返回值
类型:void
说明:无返回值。

TAVEditorGenerateListener

导出监听器(TAVEditorGenerateListener),通过 generateVideo(...) 传入。

onGenerateStarted

描述
通知导出开始。
接口
void onGenerateStarted()
参数
无。
返回值
类型:void
说明:无返回值。

onGenerateProgress

描述
通知导出进度。
接口
void onGenerateProgress(float progress)
参数
参数名
类型
说明
progress
float
导出进度,范围 0 至 1.0f。
返回值
类型:void
说明:无返回值。

onGenerateCompleted

描述
通知导出完成,包括成功或失败。应检查结果后再使用输出路径。
接口
void onGenerateCompleted(TAVEditorGenerateResult result)
参数
参数名
类型
说明
result
TAVEditorGenerateResult
结果包含 code、msg 和 outputPath,可调用 isSucceed() 判断成功。错误码见编辑 API 文档。
返回值
类型:void
说明:无返回值。

onGenerateCanceled

描述
通知导出取消。
接口
void onGenerateCanceled()
参数
无。
返回值
类型:void
说明:无返回值。