TAVTemplateEditor
剪同款编辑接口,通过
TAVMagicFactory.createTemplateEditor() 创建。模板中的音乐、转场等效果由模板配置驱动。本接口提供素材填充、裁剪、音量、变速、文字替换、播放与导出能力。
API | 描述 |
初始化预览或离屏编辑环境。 | |
复制当前状态,创建独立编辑器。 | |
释放编辑器资源。 | |
设置模板目录。 | |
获取当前模板目录。 | |
读取模板配置及坑位限制。 | |
向末尾追加一个视频。 | |
在指定位置批量插入视频。 | |
向末尾追加一张图片,并指定展示时长。 | |
批量插入图片,每张使用相同展示时长。 | |
获取已添加的素材数量。 | |
移除指定素材。 | |
设置素材内的开始和结束时间。 | |
设置素材画面裁剪区域。 | |
设置单个素材原声音量。 | |
设置全部素材原声音量。 | |
获取素材原声音量。 | |
设置视频播放速度。 | |
获取视频播放速度。 | |
获取媒体文件信息。 | |
获取原始帧抽取接口。 | |
开始播放。 | |
设置预览播放区间。 | |
恢复播放。 | |
暂停播放。 | |
获取当前内容总时长。 | |
查询播放状态。 | |
跳转到指定时间。 | |
注册播放进度及状态监听。 | |
刷新编辑结果。 | |
刷新编辑结果,并在完成后回调。 | |
按预设质量等级导出。 | |
按自定义配置导出。 | |
取消导出。 | |
获取模板中的可替换文字。 | |
更新模板文字内容。 | |
获取渲染画布尺寸。 | |
设置剪同款预览尺寸。 |
initWithPreview
描述
需要预览:设置
videoView,使用 SCENE_PLAY。仅用于导出:
videoView 传 null,scene 设为 TAVEditorConstants.SCENE_EXPORT。接口
void initWithPreview(TAVEditorConstants.PreviewParam param)参数
参数名 | 类型 | 说明 |
param | TAVEditorConstants.PreviewParam |
返回值
类型:
void说明:无返回值。
fork
描述
复制当前模板、素材、裁剪、音量和文字状态,创建独立编辑器。新实例使用结束后需单独调用
release()。param 传 null:不显示预览,关闭自动播放和循环播放,场景仍为 SCENE_PLAY。仅用于导出:显式设置
param.scene = TAVEditorConstants.SCENE_EXPORT。接口
TAVTemplateEditor fork(@Nullable TAVEditorConstants.PreviewParam param)参数
参数名 | 类型 | 说明 |
param | TAVEditorConstants.PreviewParam | 新实例的初始化参数,可为 null。 |
返回值
说明:独立实例;当前状态不可用于派生、实例已释放或派生失败时返回
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。
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
描述
接口
ITAVThumbProvider getThumbnailProvider(boolean forceUseSoftwareDecoding)参数
参数名 | 类型 | 说明 |
forceUseSoftwareDecoding | boolean | 是否强制使用软件解码。 |
返回值
说明:抽帧接口;使用结束后按其生命周期要求调用
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
描述
输出路径须可写,调用前需准备好父目录。
接口
void generateVideo(@TAVEditorConstants.GenerateLevel int level, String outputPath, TAVEditorGenerateListener listener)参数
参数名 | 类型 | 说明 |
level | int | TAVEditorConstants.VIDEO_LEVEL_* 导出等级。 |
outputPath | String | 输出文件的绝对路径。 |
listener | TAVEditorGenerateListener | 开始、进度、完成及取消回调。 |
返回值
类型:
void说明:无同步返回值,完成时根据回调结果判断成功或失败。
generateVideo(自定义配置)
描述
接口
void generateVideo(TAVEditorGenerateConfig config, String outputPath, TAVEditorGenerateListener listener)参数
参数名 | 类型 | 说明 |
config | TAVEditorGenerateConfig | 输出宽高、帧率、码率等配置。 |
outputPath | String | 可写的输出文件绝对路径,需提前准备父目录。 |
listener | TAVEditorGenerateListener | 导出监听器。 |
返回值
类型:
void说明:无同步返回值,完成时根据回调结果判断成功或失败。
cancelGenerate
描述
取消正在进行的导出任务,通过导出监听器的
onGenerateCanceled() 接收取消通知。接口
void cancelGenerate()参数
无。
返回值
类型:
void说明:无返回值。
getReplaceItems
描述
接口
List<TAVReplaceItem> getReplaceItems()参数
无。
返回值
说明:文字替换项列表,没有可替换文字时为空;字段见本篇 TAVReplaceItem 及 TAVTextReplaceItem。
replaceItem
描述
接口
void replaceItem(TAVReplaceItem item)参数
参数名 | 类型 | 说明 |
item | TAVReplaceItem |
返回值
类型:
void说明:无返回值。
getRenderSize
描述
获取当前剪同款渲染画布的宽高。
接口
Size getRenderSize()参数
无。
返回值
类型:
android.util.Size说明:当前画布尺寸,单位像素;使用前需确认宽高有效。
setRenderSize
描述
设置剪同款预览画布尺寸。建议在添加素材前调用。不指定时,SDK 按设备等级与 9:16 比例确定尺寸。
预览固定为 9:16 竖屏。SDK 保留输入宽高中的较大值作为长边,短边按
9 / 16 计算后四舍五入,再调整为偶数,例如 (1080, 1080) 会变为 (608, 1080)。接口
void setRenderSize(int width, int height)参数
参数名 | 类型 | 说明 |
width | int | 期望预览宽度,单位像素,需大于 0。 |
height | int | 期望预览高度,单位像素,需大于 0。 |
返回值
类型:
void说明:无返回值。
TAVEditorConstants
剪同款使用的通用常量和初始化参数(
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
描述
使用模板中已有的
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 |
返回值
类型:
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说明:无返回值。